Skip to content
Astrolabe

CLI (astl)

astl comes with @astrolabe/devkit. It registers the built-in components (<astl-gap>, <astl-choice>). In this repository, run it as pnpm astl ... after pnpm build.

astl validate <files...> [--json] [--locale <tag>]
astl compile <file> --out <dir> --key-out <file> --salt <salt> [--secret-env <NAME>]
astl conformance [dir] [--update]
Exit code Meaning
0 done, no errors
1 problems found (a document with errors, a failed fixture, a file that cannot be read)
2 usage or configuration error (unknown command or flag, missing arguments, no secret)

Issue messages come from the catalogs, in the --locale UI language (default: from LC_ALL, LC_MESSAGES or LANG; English for C, POSIX or nothing). The rest of the output is for developers and stays English.

validate

Section titled “validate”

Checks exercise sources, or HTML pages with <astl-doc> elements inside (every document of a page is checked), and prints their issues. Exits 1 when a document has errors; warnings alone exit 0.

Terminal window
astl validate lesson.html --locale en
lesson.html: error CHOICE_CORRECT_MISSING at astl-doc > astl-choice#q1
  Question q1 has no correct answer.
Flag Meaning
--locale <tag> language of the messages, for example en or pl
--json one report per document: { file, document, ok, issues }, each issue with its message

A page with several documents prints them as file [1], file [2], and so on.

compile

Section titled “compile”

Compiles one source into its public and private parts.

Terminal window
export ASTL_SECRET="$(openssl rand -base64 32)"   # once; keep it with your other secrets
astl compile lesson.html --out public/lesson --key-out private/lesson.key.json --salt lesson-42
Flag Meaning
--out <dir> public output: view.html and meta.json
--key-out <file> the private answer key, written with mode 0600; refused when it is inside --out
--salt <salt> required and not empty, for example the exercise id: it keeps ids unique per exercise
--secret-env <NAME> the environment variable holding the secret (default ASTL_SECRET), at least 16 bytes
--locale <tag> language of the issue messages

The file must contain exactly one <astl-doc>. Issues are printed as with validate; on success the command prints the viewHash and reminds you that the key is private.

conformance

Section titled “conformance”

Runs the conformance fixtures: for each fixtures/<case>/ folder under [dir] (default: the built-in components' fixtures) it compiles source.html, compares the view, key, metadata and issues with the golden files, checks that compiling twice gives the same view, runs the leak probe (no private value in the view) and grades every case in grading.json.

Flag Meaning
[dir] where to look for fixture folders
--update rewrite goldens that differ (missing goldens are always written) 
ok   gap/fixtures/gap-basic
FAIL choice/fixtures/choice-shuffle
       view.html differs from the compiled output
32 fixtures, 1 failed

To run the fixtures of your own components, use runConformance from @astrolabe/devkit with an engine that registers them; see Write your own component.