Table of Contents

Development

The checks

Command What it proves Needs
npm test Every *.test.ts under tests/ passes (node --test, native type stripping), the dependency rule of tests/repository/architecture.test.ts included Node 24
npm run typecheck The whole project type-checks (scripts/typecheck.mjs, tsc over tsconfig.json, one line per error) npm ci
npm run bundle:check Every command and crew bundles with the runtime's esbuild flags, without any Node API npm ci
npm run check:provenance No marker of another product's material in the sources (scripts/provenance-markers.json); -- --strict also requires the baseline to be empty, as CI does Node
npm run docs:commands -- --check docs/commands.md and docs/fr/commands.md match the commands Node
node scripts/check-docs-parity.mjs docs/fr/ mirrors docs/: every page has its French twin, with the same heading levels, the same code blocks and tables of the same length, and the two toc.yml list the same pages Node
npm run check All of the above npm ci
bash scripts/smoke-runtime.sh [--mode ...] The real REPL loads every command (N loaded, 0 skipped, 0 conflicts) a runtime
bash scripts/check-file-modes.sh Scripts are committed executable git
node scripts/render-prompts.mjs <dir> Writes every prompt as the model reads it (tests/support/fixtures/prompt-catalogue.ts), to review a prompt change as a diff -r of two renders; tests/repository/prompt-contract.test.ts checks the same catalogue Node 24

CI (.github/workflows/ci.yml) runs, as separate steps on every pull request and push to main, the tests, the type check, the bundle check, the provenance gate, the two command pages up to date, the documentation parity and the file modes (that is npm run check plus the file modes). runtime-smoke.yml runs the smoke every Monday, on demand (workflow_dispatch), and on a pull request that touches .orkeon-version, orkeon-code, scripts/smoke-runtime.sh, src/commands/** or the workflow. The job checks Orkeon's sources out at the pin read from .orkeon-version, builds the REPL and runs the source mode, the reference runtime; locally, ORKEON_SOURCE=<an Orkeon checkout at the pin> bash scripts/smoke-runtime.sh --mode source is the same check.

Running a crew alone

bash scripts/run-crew.sh src/crews/git-commit/crew.ork.ts
ORKEON_CODE_WORKSPACE=~/src/app bash scripts/run-crew.sh src/crews/project-init/crew.ork.ts

It uses the orkeon tool (Orkeon.Scripting.Cli, nuget.org, named by .config/dotnet-tools.json; the .NET SDK that restores and runs it is pinned by global.json, like Orkeon's: 10.0.300 with rollForward: latestFeature) or the orkeon-runners image, on the demo fixture unless ORKEON_CODE_WORKSPACE says otherwise. Both are a release, never the pin: the tool is on nuget.org at 1.0.0-rc.6, the image is orkeon-runners:latest (the last one published, 1.0.0-rc.5); ORKEON_CODE_MODE=source ORKEON_SOURCE=<checkout at the pin> runs it from an Orkeon checkout, built on the spot. That tool reads its script limits from Orkeon:Scripting:Limits, not from the REPL's Orkeon:Cli:ScriptCommands:Limits (Configuration).

The run is headless: nobody answers the permission gate's questions, and there are no session rules. With the gate on, as the example settings set it, a call the mode would ask about is refused instead (the model reads DENIED: …): main-loop launched without a mode runs in default, so its writes, commands and network reads are refused. Give it a mode to let them run, e.g. --inputs '{"prompt":"…","permissionMode":"bypassPermissions"}', on a project you can afford to change. The same command run unattended, from a scheduler, a CI job or an application: Autonomous and embedded runs.

Typings

src/crews/.orkeon/orkeon.d.ts and src/commands/.orkeon/orkeon-cli.d.ts describe the runtime API. They are generated by orkeon typings from the pin: ORKEON_SOURCE=<path to an Orkeon checkout> npm run typings, never edited by hand, the same variable the launcher's source mode reads. The checkout must sit at the pin, refused otherwise (npm run typings -- --any overrides it); without ORKEON_SOURCE, the typings come from the release of .config/dotnet-tools.json, with a warning, not from the pin.

Upgrading Orkeon

The pin is a commit of Orkeon's main, never a release (ADR 0013). It lives in four places that must agree (tests/repository/version.test.ts checks the first two):

  1. .orkeon-version: the full commit, whose first seven characters the launcher, /status and /doctor print;
  2. src/commands/_lib/status/meta.ts: ORKEON_RUNTIME_COMMIT, the same commit;
  3. package.json: esbuild, pinned to the version the runtime bundles with (tools/scripting-esbuild/package-lock.json in Orkeon/orkeon at that commit);
  4. global.json: the .NET SDK, the same pin as Orkeon's global.json at that commit (tests/repository/version.test.ts checks it).

.config/dotnet-tools.json names the last release of orkeon.scripting.cli, for the tool fallback of the typings and of scripts/run-crew.sh: it no longer follows the pin. Then:

export ORKEON_SOURCE=<an Orkeon checkout at the pin>
npm ci && npm run typings && npm run check && bash scripts/smoke-runtime.sh --mode source

and a live session on the demo fixture (/init, /assistant, /commit, /review) before merging. Dependabot leaves esbuild alone for that reason.

Releasing

  1. Move the [Unreleased] entries of CHANGELOG.md under ## [x.y.z] - YYYY-MM-DD.
  2. Bump package.json version and CLI_VERSION in src/commands/_lib/status/meta.ts (the test keeps them equal), and the release notes in the same file.
  3. Run bash scripts/check-shared-memory.sh in a terminal (it asks for rag_eval): the shared memory's recall on its reference set must end on check-shared-memory: thresholds met (recall@5 >= 0.85, MRR >= 0.70). The question with no answer (q13) passes only when the runtime's settings give Orkeon:Rag:Retrieval:MinScore: without that floor every query returns passages, q13 fails and so does the check.
  4. Merge, then tag vx.y.z on main and push the tag: release.yml checks that the tag matches, runs the checks and the strict provenance gate, and publishes the GitHub Release with the runnable archives (orkeon-code-<v>.tar.gz and .zip, what the installers fetch), install.sh and install.ps1, the source archives, SHA256SUMS and a build provenance attestation (gh attestation verify <file> --repo Orkeon/orkeon-code). Its npm job then publishes the package to npm with provenance: through trusted publishing (configured on npmjs.com for this repository), or with the NPM_TOKEN secret when the repository sets one; a version with a suffix goes to the next dist-tag, any other to latest.

A version with a suffix (-alpha.1, -rc.1) is published as a pre-release.

Edit this page