dylan-sutton-chavez/edge-python/skill

Edge Lang

This document is self-verifying and its examples follow the cells v1 grammar. A mini or yml block followed immediately by a text block is a runnable cell, and the skill crate beside it in the repository executes every cell through the edge CLI and compares it against the text block. The tag on the text block is Output for a run whose stdout must equal the block, or Error for a failing run whose stderr contains the given text. A mini block tagged skip never runs on any engine and never pairs with a text block, and it always says why with one // skip comment at the exact construct that is nondeterministic. A yml block tagged actor runs a trusted actor pool through edge actor, while one tagged untrusted runs eval groups. Any mini block without a text pair is illustrative only. Every cell runs in a scratch directory holding the edge.json the runner writes, {}, since nothing resolves undeclared, and the yml cells find the same manifest beside their actor.yml. Verify the whole file from the repository root with make test-skill, which builds the CLI first, or with cargo run -p skill -- skill/SKILL.md --edge <path to edge>.

Edge Lang is an engine for building language runtimes, a single-pass compiler to bytecode and a register VM in one WebAssembly binary. The edge CLI runs mini, the reference runtime built on it, on macOS, Linux and WSL, and the JS host runs the same edge.wasm in browsers and in JavaScript runtimes such as Deno. Mini opens a block with a header colon and deeper indentation, writes fn, true, false, nil, &&, ||, ! and else if, starts a comment with // and divides toward zero at ~/, where % takes the sign of the number it divides. A test reads nil, false, 0, NaN and "" as false and every list, map, set and tuple as true, empty or not. Every module is a file or a package declared in edge.json and resolved at compile time. Programs are deterministic, and a program reaches no network or file unless its edge.json grants it.

Use this skill to drive the edge CLI. It covers running, testing, packing and publishing a project, declaring what it imports, granting it the network and files, running actor pools and staying inside the sandbox limits.

The working loop

A project is any folder with .mini files and an edge.json declaring every module they import. The loop is always the same.

1. Write or edit the .mini files.
2. Run the entry point with edge run main.mini.
3. Add tests in *_test.mini files and run edge test.
4. Pack a release with edge build when the program must run elsewhere.

edge init myapp                          # scaffold main.mini, edge.json and index.html
cd myapp
edge run main.mini                       # run the entry point
echo 'assert 6 * 7 == 42' > answer_test.mini
edge test                                # run every *_test.mini under the folder
edge add slugify=./slugify_mod.wasm      # declare a module by path, by URL or by registry name
edge lock                                # pin each declared version and URL in edge.lock
edge build                               # pack a portable ./app.edge bundle

edge init writes main.mini, which prints one line, an index.html that runs it in a browser, and an edge.json holding only the engine that made it.

{
  "edge": "0.9.7"
}

Piping a script works too, which is how the cells of this document run.

echo 'print(6 * 7)' | edge run

When a file path is given, piped stdin instead feeds input(), one line per call.

CLI reference

Bare edge prints help and exits 0. edge -v prints the version. Ctrl+C exits 130. Errors print to stderr and exit 1.

Global flags

edge run

edge run [file] executes a .mini script, a packed .edge bundle or an app binary, auto-detected by content. With no file it reads the script from stdin. A bare edge run in a terminal with no pipe errors. edge run -c 'print(1)' runs inline code instead of a file or stdin, and piped stdin then feeds input().

Run flags.

exit(code) ends the run cleanly with that code and no traceback, and exit() ends it with 0. Any other uncaught error prints a traceback and exits 1.

--web serves the JS host and the engine from the binary on a loopback port, so only the modules a manifest declares by URL leave the machine. It drives a Chrome the system already has, or one it offers to download once into ~/.local/share/edge/chromium, which edge uninstall offers to remove. EDGE_CHROME_PATH names a browser directly and skips the search.

send(channel, line) writes one line to a named output outside an actor pool, in order with what the run prints. A plain name prints its lines under the name, and file:<path> writes a file in the directory the run started in, a path below it with no ... Only the root package writes a file channel without a grant.

send("report", "github up")
print("checked 1 service")

report
github up
checked 1 service

edge test

edge test [path] discovers *_test.mini recursively, skipping hidden dirs and dist. A file argument runs exactly that file. Each file executes in a fresh session and state never leaks between files. A file passes when it ends cleanly or exits with 0, so a failed assert fails it, and its output never decides it. The exit code is 0 when everything passes, 1 when a file fails or no tests are found, and 2 when the engine cannot start. --memory and --ops apply as they do for edge run.

edge test --web runs the same files on the browser host in headless Chrome, one browser for the suite with a fresh page per file, so a package can prove it answers the same in a browser.

edge init, edge add, edge remove, edge lock

edge init [name] scaffolds main.mini, edge.json and index.html in a new directory, or in the current one with no name. --bare skips the HTML. It never overwrites a file, and refuses with the name of the first one that already exists.

edge add <name> looks a name up in the registry at its newest version, or at the one <name>@0.1.0 names, writes one imports entry holding that version alone, and prints it with what the package asks the root to grant. edge add foo=<url> or edge add foo=./path registers a custom spec verbatim, also under imports, since each host tells a .mini and a .wasm module apart by the artifact, and a .js or .mjs spec is refused before anything is written. edge add keeps extends and any other key already there. edge remove deletes entries. Unknown names abort the whole command before any write, and neither command touches edge.lock. The same registry answers over HTTP, where GET https://edgelang.dev/api/search?q=<term> finds a package and every address it names answers as data under /api.

edge lock turns each declared version into the URL and digest of that release, pins each bare URL to the digest of its bytes, and writes edge.lock beside the manifest, rebuilding the whole file each time. It is the only command that asks the registry where a name points, so edge run, edge test and edge build read the lock and resolve nothing themselves. A version with no entry, or one whose entry holds another release, fails with '<name>' is not locked, run edge lock. It also walks every package in the tree, each through its own edge.lock, and writes nothing while a package lacks what it lists from its importer. edge run and edge test repeat that check on the nearest edge.json above the script or the tested path before compiling, and edge build on the project's own.

edge serve

A static dev server with live reload for the current directory. --host defaults to 127.0.0.1, --port to 5173, --open opens a browser. On a loopback address it answers only a request whose Host names that address, with 421 for any other, and a path through a dot entry or a link out of the directory answers 404.

edge build

Three mutually exclusive modes.

--out <path> overrides the default. The bundle contains every .mini and .wasm under the project plus edge.json, each edge.lock, the README.md and any LICENSE at the project root, together with each module the manifest declares by URL and the files it imports. When edge.json declares a docs directory, a .edge also carries its .mdx pages under a reserved @docs/ prefix, checked against the rendering convention first, and an app binary leaves them out. The entry is main.mini, app.mini or index.mini, the first present. An app binary accepts only the snapshot flags --save-state, --restore-state, --preempt and --events.

edge publish

edge publish app.edge uploads a .edge packed by edge build, reading EDGE_TOKEN for a token made at edgelang.dev/settings#tokens, which signs the request and never leaves the machine. The artifact is the whole request. The registry opens it and reads the name, the version, the description, the repository, the LICENSE and the pages under @docs/ out of the bytes it is about to store, so nothing is declared twice and a listing shows what you shipped. A name is first come and permanent, a version is never overwritten and publishing one twice exits 2, and the bundle is stored exactly as packed. One artifact is 10 MB at most, an account claims 10 names and publishes 60 versions a day, and its packages add up to 50 MB when it signs in by address alone or a gigabyte with GitHub or Google linked.

edge actor

edge actor <file> runs an actor pool from an actor.yml manifest, resolving group imports through the edge.json beside it or the one --manifest names. See the actors section for the schema and the two execution models.

edge uninstall

Interactive removal of the binary and PATH entries.

Environment variables

Imports

Every import resolves at compile time through a host resolver. The compiler flattens each module into the bytecode and the VM fetches nothing at run time.

Dotted specs import files. A leading dot anchors at the importing file, one extra dot per directory up. Without it the spec anchors at the nearest edge.json dir. The .mini suffix is implicit.