HackerScript

Table of Contents

• Struktura repozytorium
• Jak to dziala
• Szybki start
• Kolorowe CLI i pasek postepu
• Historia wersji
• Status projektu
• Dokumentacja
• Uwaga

Jezyk programowania ogolnego przeznaczenia. Zwykla fun kompiluje sie do prawdziwego Rusta (statyczne typy, bezpieczenstwo pamieci, zero-cost abstractions). direct [ …​ ] to ucieczka do czystego Pythona, wykonywanego przez wbudowany interpreter (PyO3) - dla tego niewielkiego fragmentu kodu, ktory nigdy nie bedzie wymagal wydajnosci.

Status	Bootstrap osiagniety + FFI 0.3 + workspace 0.4 - hackerc (transpilator) i virus (menedzer pakietow/narzedzie budowania) sa dzis w calosci napisane w samym HackerScript (.hcs), nie w Pythonie/Rust jak w wersji 0.0.1. Od 0.3 dochodzi przeprojektowane FFI: get <extern:…​> use <static|dynamic> + region [ …​ ], get <c:…​>/get <cpp:…​> oraz native {C++} [ …​ ]. Od 0.4: get <work:czlonek[::plik]> (import DOWOLNEGO czlonka workspace, nie tylko core/std), sekcja [build] w Virus.hk usunieta (plik wejsciowy jest teraz zawsze cmd/main.hcs, bez konfiguracji), oraz naprawiony blad z duplikujacym sie cache/ w workspace (patrz Historia wersji).
Wersja	0.4 (ta - self-hostujaca sie, wydawana na GitHub Releases) - 0.0.1 to zamrozona wersja startowa sprzed bootstrapu (patrz Historia wersji).
Licencja	MIT (c) 2026 HackerOS Team

struct Point [
    x: Int,
    y: Int
]

fun distance_squared(p: Point) -> Int [
    end (p.x * p.x) + (p.y * p.y)
]

fun main() [
    let p = Point(3, 4)
    log("dist^2 =", distance_squared(p))

    direct [
        print("To jest czysty Python wykonywany wewnatrz binarki Rust.")
    ]
    end
]

Zobacz docs/hello-world/, docs/module-demo/, docs/showcase/ (ogromny, jednoplikowy przeglad niemal calego jezyka - zmienne, funkcje, struct/enum/match/impl, kolekcje, stringi, manual[…​], oraz FFI 0.3) i docs/ffi-demo/ (minimalny, samodzielny przyklad samego FFI: get<extern:…​> use<…​> + region, get<c:…​>/ get<cpp:…​>, i kompilowany build-time blok C++) - dzialajace przyklady, wszystkie zweryfikowane realna kompilacja i uruchomieniem (patrz naglowkowy komentarz kazdego pliku po instrukcje budowania). Oraz docs/SYNTAX.md - pelny opis skladni (w tym, od 0.4, get <work:czlonek[::plik]> - import dowolnego czlonka workspace) i docs/ROADMAP.md - pelna, szczera lista tego co jeszcze brakuje.

Struktura repozytorium

HackerScript/
  hackerc/cmd/          transpilator .hcs -> Rust, W CALOSCI w HackerScript (self-hosted)
    lexer.hcs              tokenizacja + resolve_escape (\n \t \r \e ...)
    parser.hcs              recursive-descent parser -> AST
    ast_nodes.hcs           definicje Expr/Stmt/typow AST
    typecheck.hcs           diagnostyki (bledy/warningi), builtin-y
    typeinfer.hcs           inferencja typow, sygnatury projektu
    codegen.hcs             AST -> tekst Rust (~3700 linii, najwiekszy plik)
    transpiler.hcs          spina lexer/parser/typecheck/codegen w calosc
    project.hcs             wielo-plikowe skladanie projektu, Cargo.toml
    formatter.hcs            formater kodu .hcs
    diagnostics.hcs          renderowanie bledow w stylu rustc (podkreslona linia)
    main.hcs                 CLI: build/check/lint/fmt (kolorowe, z paskiem postepu) - do 0.3: cli.hcs
    playground.hcs           demo/checker uzywany przez playground WASM
  virus/cmd/             menedzer pakietow i build tool, W CALOSCI w HackerScript
    main.hcs                 CLI: init/build/check/lint/fmt/install/remove/repair/clean
    manifest.hcs              parser formatu .hk (Virus.hk - NIE TOML) - [build] usuniete w 0.4
    install.hcs               pobieranie zaleznosci z PyPI/crates.io/npm/JSR
    hackerc_bridge.hcs         resolve+download hackerc wg `using <wersja>`
    build.hcs / check.hcs / lint.hcs / fmt.hcs / cache.hcs / cache_cmd.hcs
    progress.hcs               kolorowy CLI (std:term) - naglowki/pasek postepu
    remove.hcs / repair.hcs / clean.hcs / init.hcs
  libs/
    core/lib/memory/        4 alokatory: arena, chained_arena, stack_allocator, pool_allocator
    std/lib/                fs, io, string, math, path, json, toml, hk, env,
                             process, http, term (KOLORY + PASEK POSTEPU - nowe),
                             result, cybersecurity/ (constant_time_eq, shannon_entropy)
  playground/             checker HackerScript skompilowany do WASM (przegladarka, 0.4)
    cmd/main.hcs            statycznie linkuje hackerc przez get<work:...>, @wasm_export check_source
    web/                    index.html + main.js - dzialajaca strona w stylu Rust Playground
    web/README.md           dokladne kroki budowania (virus build --wasm + wasm-bindgen-cli)
  docs/
    hello-world/            minimalny dzialajacy przyklad (.hk + .hcs)
    module-demo/            przyklad systemu modulow (get <core:...>)
    showcase/               ogromny, jednoplikowy przeglad jezyka (0.3/0.4)
    ffi-demo/               samodzielny przyklad FFI 0.3 (extern/region/c/cpp)
    SYNTAX.md                 pelny opis skladni (w tym get <work:...>, 0.4)
    ROADMAP.md                 co jeszcze brakuje (szczegolowo, per-plik)
  scripts/                install.sh/remove.sh (HackerOS) + skrypty .hl
  .github/workflows/      CI (buduje I URUCHAMIA wygenerowany crate) + Release

Tip	Wczesniejsza architektura (hackerc/ w Pythonie, virus/cli virus/hk-parser w Rust z clap/reqwest) zostala calkowicie zastapiona kodem HackerScript powyzej - patrz Historia wersji jesli szukasz kontekstu tej zmiany.

Jak to dziala

1. fun → hackerc generuje prawdziwy Rust (struct → struct
impl new(), manual[] → unsafe{}, List<T> → Vec<T>, parametry struct/List/Str automatycznie dostaja &/&mut zamiast przenoszenia wlasnosci).

2. direct [ …​ ] → surowy Python wykonywany w trakcie dzialania programu przez Python::with_gil (PyO3, tryb auto-initialize) - Rust jest hostem.

3. get <core:memory::arena> → realnie importuje kod z libs/core/lib/memory/arena.hcs (system modulow: project.hcs dwufazowo zbiera sygnatury z calego projektu, zeby wywolania cross-plikowe tez dostaly poprawne &/&mut).

4. get <crates:nazwa> → prawdziwa zaleznosc Cargo. get <pypi/npm/jsr:…​> → pobierane przez virus install (bezposrednio z PyPI/crates.io/npm/JSR API, BEZ pip/cargo add/npm install).

5. virus install vira <nazwa> → szuka biblioteki w oficjalnym rejestrze https://vira.io (JSON publikowany pod github.com/vira-io/repository) i pobiera ja wg zadeklarowanego typu. Dla typu git kod trafia do cache/libs/vira/<nazwa>/ i jest importowalny wprost przez get <vira:nazwa[::plik]> (jak get <std:…​>/get <core:…​> - biblioteka MUSI miec mod.hcs w korzeniu, jesli ma byc importowana bez ::). Dla static-lib/shared-lib/rust-lib linkowanie do wygenerowanego crate’a dzieje sie automatycznie przy virus build (wygenerowany build.rs/.cargo/config.toml), a uzycie w kodzie to extern "nazwa" fun …​ (.hlib zaplanowane na przyszlosc) - patrz docs/ROADMAP.md, sekcja "Ekosystem bibliotek Vira".

6. using <wersja> na poczatku pliku (albo [package] using w Virus.hk) → deklaruje wymagana wersje hackerc. Jesli nie jest zainstalowana, virus pobiera ja automatycznie z GitHub Releases:

   https://github.com/HackerOS-Linux-System/HackerScript/releases/download/v<wersja>/hackerc

   (przez curl, z natywnym paskiem postepu, cache’owana w cache/env/hackerc-<wersja>/) - patrz virus/cmd/hackerc_bridge.hcs.

7. virus build → hackerc build (generuje cargo crate) → cargo build (jedyne miejsce, gdzie virus uzywa cargo - jako kompilator, nie menedzer pakietow). Uruchomiony na korzeniu z [workspace] w Virus.hk (patrz glowny /Virus.hk tego repo) buduje KAZDEGO czlonka majacego wlasny, uruchamialny plik wejsciowy - analogicznie do cargo build w workspace Cargo.

8. (0.4) Plik wejsciowy KAZDEGO budowalnego czlonka/projektu jest teraz ZAWSZE cmd/main.hcs - sekcja [build] → entry ⇒ <sciezka>, pozwalajaca to kiedys nadpisac, zostala calkowicie usunieta z formatu .hk (dokladny analog tego, jak Cargo samo znajduje src/main.rs, bez zadnego pola w Cargo.toml) - patrz find_cmd_entry() w virus/cmd/manifest.hcs.

9. (0.4) get <work:czlonek[::plik]> → importuje lib/mod.hcs (albo lib/<plik>.hcs) DOWOLNEGO czlonka [workspace] → members, nie tylko uprzywilejowanych core/std (ktore maja wlasne, krotsze aliasy get <core:…​>/get <std:…​>, dzialajace identycznie) - analog Rustowego use nazwa_membera::modul::*; w workspace Cargo. Patrz docs/SYNTAX.md.

10. (0.4) cache/ jest teraz NAPRAWDE wspolny dla calego workspace, niezaleznie z ktorego czlonka odpalisz virus (hackerc/, virus/, libs/core/, libs/std/ czy korzenia) - wczesniej kazdy z nich (majac WLASNY, poprawny Virus.hk) dostawal WLASNY, osobny cache/ zamiast dzielic jeden z korzeniem, dokladnie tak jak cargo w workspace zawsze dzieli jeden target/. Patrz virus/cmd/cache.hcs.

Szybki start

# hackerc i virus sa binarkami natywnymi (self-hosted) - najprosciej
# pobrac gotowe wydanie:
curl -L --fail -o hackerc \
  https://github.com/HackerOS-Linux-System/HackerScript/releases/download/v0.4/hackerc
chmod +x hackerc

./hackerc check docs/hello-world/Virus.hk
./hackerc build docs/hello-world/cmd/main.hcs -o /tmp/out
cd /tmp/out && cargo run   # wymaga zainstalowanego Rust

Albo, w projekcie zarzadzanym przez virus (patrz Virus.hk):

virus init --name moj-projekt
cd moj-projekt
virus build --release   # pobierze wlasciwy hackerc automatycznie (using <wersja>)

Kolorowe CLI i pasek postepu

hackerc build/virus build/check/lint/fmt maja teraz kolorowe wyjscie (zielony = sukces, czerwony = blad, cyan = nazwy/etykiety) i realny, procentowy pasek postepu renderowany w miejscu (nie osobna linia per krok) - patrz nowy modul libs/std/lib/term.hcs (get <std:term>).

• Kolory wylaczaja sie automatycznie gdy ustawiona jest zmienna srodowiskowa NO_COLOR (https://no-color.org).

• Pasek dla hackerc build: 4 kroki (parsowanie → sygnatury projektu → sprawdzanie typow → generowanie crate’a Rust).

• Pobieranie binarek (virus install, auto-pobieranie hackerc wg using <wersja>) uzywa natywnego paska curl --progress-bar zamiast wlasnego renderowania - virus nie ma dostepu do bajtow strumienia w trakcie trwania procesu pobierania (patrz docs/ROADMAP.md, sekcja "CLI - kolory i pasek postepu", po wyjasnienie dlaczego).

Historia wersji

0.0.1	Zamrozona. Wersja startowa: hackerc w Pythonie, virus (cli/hk-parser) w Rust z clap/reqwest. Nie jest juz rozwijana - punkt odniesienia "skad zaczelismy".
0.1	Bootstrap. hackerc i virus przepisane w calosci na sam HackerScript (.hcs), kompilowane przez wlasny transpilator do Rusta. Pierwsze wydanie publikowane binarnie na GitHub Releases pod v0.1.
0.2	Wewnetrzna. Kolorowe CLI i realny pasek postepu (libs/std/lib/term.hcs, get <std:term>) dla hackerc build/check/lint/fmt i virus odpowiednikow - patrz "Kolorowe CLI i pasek postepu" wyzej.
0.3	Przeprojektowane FFI. Stare, jedno-funkcyjne extern "lib" fun nazwa(…​) zastapione przez get <extern:sciezka> use <static|dynamic> + region [ …​ ] (dowolnie wiele sygnatur naraz, powiazanych z jedna biblioteka). Dolozono get <c:nazwa>/get <cpp:nazwa> (zaleznosci C/C budowane przez crate `cc`) oraz `native {C} [ …​ ]` (analog native {JavaScript}, ale kompilowany build-time zamiast interpretowany). Mechanizm using <wersja> pobieral wtedy v0.3. Pelny opis skladni: docs/SYNTAX.md, sekcja "FFI: extern/region/c/cpp".
0.4	Ta wersja. Workspace + porzadki + WASM. Szesc zmian: get <work:czlonek[::plik]> i include <work:czlonek[::plik]> - ogolny import/statyczne linkowanie DOWOLNEGO czlonka [workspace] → members (nie tylko core/std), analog Rustowego use nazwa_membera::…​;; sekcja [build] w Virus.hk calkowicie usunieta - plik wejsciowy jest teraz zawsze cmd/main.hcs, bez zadnej konfiguracji (przy okazji naprawiono realny blad: [build] → entry ⇒ cli.hcs w hackerc/Virus.hk nigdy nie wskazywalo na istniejacy plik, wiec hackerc byl po cichu pomijany przy virus build na calym workspace - plik przemianowany na cmd/main.hcs); naprawiony cache/ - wczesniej kazdy czlonek workspace majacy WLASNY Virus.hk (hackerc/, virus/, libs/core/, libs/std/) dostawal WLASNY, osobny katalog cache/ zamiast dzielic jeden wspolny z korzeniem, jak cargo dzieli jeden target/ w calym workspace; oraz @wasm_export + virus build --wasm - pierwszy dzialajacy pipeline do WASM, uzyty w nowym playground/ (playground/cmd/main.hcs linkuje statycznie caly checker hackerc`a przez `include <work:hackerc::…​>, playground/web/ to gotowa strona w stylu Rust Playground). Mechanizm using <wersja> pobiera teraz v0.4. Pelny opis: docs/SYNTAX.md (sekcje “get <work:…​>”, “include <work:…​>”, “@wasm_export”) i docs/ROADMAP.md (sekcja "Zrobione w 0.4").

Status projektu

Caly kompilator (hackerc/cmd/) i menedzer pakietow (virus/cmd/) sa dzis napisane w HackerScript i weryfikowane strukturalnie przez hackerc check + inspekcje, a koncowo przez CI (.github/workflows/ci.yml), ktore kompiluje i uruchamia wygenerowany crate na prawdziwym runnerze z Rustem - to jedyne miejsce, gdzie poprawnosc generowanego kodu Rust jest dzis realnie zweryfikowana automatycznie przy kazdym PR.

W trakcie przepisywania na self-hosting znaleziono i naprawiono kilka realnych bledow odziedziczonych z oryginalnej wersji Pythonowej (m.in. != mylone z komentarzem, Vec::len() zwracajace usize a nie i64, przenoszenie wlasnosci struct/Vec/String przy wielokrotnym uzyciu tej samej zmiennej).

Pelna, szczera lista tego co jeszcze brakuje - braki jezykowe bootstrapu (iteracja po Dict, Set, numery linii w AST, prawdziwe ParseError, log() dla struct/enum), uproszczenia per-plik (codegen.hcs/typeinfer.hcs/project.hcs/main.hcs/ formatter.hcs/parser.hcs), luki w libs/std poza rdzeniem, oraz gapy w FFI 0.3/0.4 (kompilacja wlasnego zrodla .c/.cpp z projektu przez cc zamiast linkowania systemowej biblioteki dla get <c:…​>/get <cpp:…​>) - jest w docs/ROADMAP.md, razem z lista tego, co juz naprawiono w 0.4 (wspolny cache/ dla workspace, usuniecie [build], get <work:…​>).

Dokumentacja

• docs/SYNTAX.md - pelny opis skladni (w tym FFI 0.3: get <extern:…​> use <…​> + region [ …​ ], get <c:…​>/get <cpp:…​>, native {C++} [ …​ ]).

• docs/ROADMAP.md - co brakuje, szczegolowo i per-plik

• Format .hk: https://hackeros-linux-system.github.io/HackerOS-Website/tools-docs/hk.html

Uwaga

HackerScript osiagnal juz bootstraping.