@bramas/simulant-cli 0.0.0-stage → 0.1.1

package/dist/cli.js

@@ -0,0 +1,210 @@
+import { Command, InvalidArgumentError } from "commander";
+import { readFileSync } from "node:fs";
+function depthArgument(value) {
+    const number = Number(value);
+    if (!/^\d+$/.test(value) || !Number.isSafeInteger(number)) {
+        throw new InvalidArgumentError('Expected a non-negative integer.');
+    }
+    return number;
+}
+function countArgument(value) {
+    const number = depthArgument(value);
+    if (number === 0)
+        throw new InvalidArgumentError('Expected a positive integer.');
+    return number;
+}
+import { resolve as resolvePath } from "node:path";
+import { listProjects as listAvailableProjects, loadProject as loadNamedProject, locateProject } from "./project-registry.js";
+import { leanCommand } from "./lean.js";
+import { runSmokeChecker } from "./smoke-checker.js";
+import * as explorer from "./explorer-commands.js";
+import { requestWatch, watchProject } from "./watch.js";
+const print = (line) => console.log(line);
+/** Explorer limits from the options: no depth limit unless given (liveness needs the whole graph). */
+const explorerOptions = (options) => ({
+    maxDepth: options.maxDepth, maxStates: options.maxStates, maxConfigs: options.maxConfigs, perSetting: options.perSetting,
+});
+const program = new Command();
+const metadata = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
+program
+    .name('simulant')
+    .description('CLI tool for testing and generating artifacts from mobile entities projects')
+    .version(metadata.version)
+    .option('--root <directory>', 'Project or workspace directory (default: current directory)')
+    .option('--registry <file>', 'Project registry module, relative to --root or the current directory');
+const projectSource = () => program.opts();
+const loadProject = (name, watch = false) => {
+    if (watch)
+        requestWatch();
+    return loadNamedProject(name, projectSource());
+};
+/** A simulation that provides the explorer's commands (a `.sim` project, see `simProject`). */
+async function loadExplorable(name, watch, needs) {
+    const project = await loadProject(name, watch);
+    if (!project[needs]) {
+        console.error(`Error: Project "${name}" does not provide ${needs} (simulations are .sim experiments registered with simProject)`);
+        process.exit(1);
+    }
+    return project;
+}
+function parseSettings(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch (e) {
+        console.error(`Error: Invalid JSON in settings: ${e}`);
+        process.exit(1);
+    }
+}
+/** Runs once and exits with the run's code, or, with --watch, again on each new revision. */
+async function runOrWatch(project, watch, run) {
+    if (!watch)
+        process.exit(await run());
+    await watchProject(project, run, print).done;
+}
+const watchOption = '-w, --watch';
+const watchHelp = 'Run again on every change of the .sim sources';
+const listProjects = () => listAvailableProjects(projectSource());
+// Command: generate-config-graph
+program
+    .command('generate-config-graph')
+    .description('Generate a configuration graph in TikZ format')
+    .requiredOption('-p, --project <name>', 'Project name (e.g., gathering-on-rings)')
+    .requiredOption('-s, --settings <json>', 'Settings as JSON string')
+    .option('-d, --max-depth <number>', 'Maximum depth to explore (default: unlimited)', depthArgument)
+    .option('--max-states <number>', 'Maximum number of states', countArgument)
+    .option('-o, --output <file>', 'Output file (default: stdout)')
+    .option(watchOption, watchHelp)
+    .action(async (options) => {
+    const projectName = options.project;
+    const project = await loadExplorable(projectName, options.watch, 'stateGraph');
+    const settings = parseSettings(options.settings);
+    await runOrWatch(project, options.watch, async () => {
+        try {
+            const { tikz, states, complete } = explorer.stateGraphTikz(project, settings, explorerOptions(options));
+            console.log(`State graph of ${projectName} with ${states} states${complete ? '' : ' (incomplete: limit reached)'}`);
+            if (options.output) {
+                const fs = await import("fs/promises");
+                await fs.writeFile(options.output, tikz, 'utf-8');
+                console.log(`TikZ output written to ${options.output}`);
+            }
+            else {
+                console.log('\n=== TikZ Output ===\n');
+                console.log(tikz);
+            }
+            return 0;
+        }
+        catch (e) {
+            console.error(`Error generating graph: ${e instanceof Error ? e.stack : e}`);
+            return 1;
+        }
+    });
+});
+// Command: check-config
+program
+    .command('check-config')
+    .description('Check all possible execution paths from a configuration')
+    .requiredOption('-p, --project <name>', 'Project name')
+    .requiredOption('-s, --settings <json>', 'Settings as JSON string')
+    .option('-d, --max-depth <number>', 'Maximum depth to explore (default: unlimited)', depthArgument)
+    .option('--max-states <number>', 'Maximum number of states', countArgument)
+    .option(watchOption, watchHelp)
+    .action(async (options) => {
+    const projectName = options.project;
+    const project = await loadExplorable(projectName, options.watch, 'check');
+    const settings = parseSettings(options.settings);
+    await runOrWatch(project, options.watch, async (signal) => {
+        try {
+            return await explorer.checkConfig(project, projectName, settings, { ...explorerOptions(options), signal }, print);
+        }
+        catch (e) {
+            if (signal?.aborted)
+                throw e;
+            console.error(`Error checking config: ${e instanceof Error ? e.stack : e}`);
+            return 1;
+        }
+    });
+});
+// Command: check-all
+program
+    .command('check-all')
+    .description('Check every setting of the experiment\'s parameter domains')
+    .requiredOption('-p, --project <name>', 'Project name')
+    .option('-d, --max-depth <number>', 'Maximum depth to explore per configuration (default: unlimited)', depthArgument)
+    .option('--max-states <number>', 'Maximum number of states per state graph', countArgument)
+    .option('--max-configs <number>', 'Maximum number of configurations to test (default: all)', countArgument)
+    .option('--per-setting', 'One state graph per setting, instead of one per ring size')
+    .option(watchOption, watchHelp)
+    .action(async (options) => {
+    const projectName = options.project;
+    const project = await loadExplorable(projectName, options.watch, 'checkAll');
+    const progress = process.stdout.isTTY ? (line) => process.stdout.write(line) : undefined;
+    await runOrWatch(project, options.watch, async (signal) => {
+        try {
+            return await explorer.checkAll(project, projectName, { ...explorerOptions(options), signal }, print, progress);
+        }
+        catch (e) {
+            if (signal?.aborted)
+                throw e;
+            console.error(`\n\nError during testing: ${e instanceof Error ? e.stack : e}`);
+            return 1;
+        }
+    });
+});
+program
+    .command('lean')
+    .description('Generate into <project>/lean/Generated; preserves Proofs/ and existing Lake configuration')
+    .option('-p, --project <name>', 'Simulation name (inferred when exactly one is available)')
+    .option('-o, --out <directory>', 'Lean directory (default: <project>/lean)')
+    .option('-b, --build', 'Run lake build afterwards (checks the model and the proofs)')
+    .option(watchOption, 'Generate again (and build, with --build) on every change of the .sim sources')
+    .action(async (options) => {
+    if (options.watch)
+        requestWatch();
+    let name = options.project;
+    if (!name) {
+        const names = await listProjects();
+        if (!names.length)
+            throw new Error('No simulations found. Run from a project directory, or select one with --root or --registry.');
+        if (names.length > 1)
+            throw new Error(`Several simulations are available: ${names.join(', ')}. Choose one with --project <name> (or -p <name>).`);
+        name = names[0];
+    }
+    const { project, directory } = await locateProject(name, projectSource());
+    await runOrWatch(project, options.watch, async (signal) => {
+        try {
+            return await leanCommand(project, name, directory, { out: options.out && resolvePath(options.out), build: options.build, signal }, print);
+        }
+        catch (e) {
+            if (signal?.aborted)
+                throw e;
+            console.error(`Error: ${e instanceof Error ? e.message : e}`);
+            return 1;
+        }
+    });
+});
+program
+    .command('list-projects')
+    .description('List simulations from public packages and available local private projects')
+    .action(async () => {
+    for (const name of await listProjects())
+        console.log(name);
+});
+program
+    .command('check [project]')
+    .description('Smoke check the first execution branch for each generated setting')
+    .option('-p, --project <name>', 'Simulation name')
+    .option(watchOption, watchHelp)
+    .action(async (name, options) => {
+    const projectName = options.project ?? name;
+    if (options.watch && projectName) {
+        const project = await loadExplorable(projectName, true, 'checkFirstBranch');
+        await runOrWatch(project, true, async () => explorer.checkFirstBranches(project, projectName, {}, print));
+        return;
+    }
+    await runSmokeChecker(projectName, projectSource());
+});
+program.parseAsync().catch(error => {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exitCode = 1;
+});

package/dist/explorer-commands.js

@@ -0,0 +1,112 @@
+export const exitCode = (r) => r.status === 'success' ? 0 : r.status === 'failure' ? 1 : 2;
+/** Prints a counterexample by replaying its path in the project's execution, as the simulator does. */
+export function printTrace(project, r, print) {
+    const trace = r.trace;
+    if (!trace)
+        return;
+    const model = project.setup(trace.settings);
+    const execution = project.execute(model);
+    print(`Counterexample (${trace.kind === 'lasso' ? 'an execution that repeats forever' : 'a failing configuration'}):`);
+    print(`  settings ${JSON.stringify(trace.settings)}, path [${trace.path.join(', ')}] (load both in the simulator to replay it)`);
+    trace.path.forEach((_, i) => {
+        const prefix = trace.path.slice(0, i + 1);
+        const shown = project.debugConfig ? project.debugConfig(execution.get(prefix), model) : '';
+        const label = trace.steps[i].label ? ` (${trace.steps[i].label})` : '';
+        const cycle = trace.cycleStart === i ? '  <- the cycle starts here' : '';
+        print(`  Step ${i}${label}: ${shown} [${trace.steps[i].verdict}]${cycle}`);
+    });
+    if (trace.kind === 'lasso')
+        print(`  The last step returns to step ${trace.cycleStart} (up to symmetry); the steps after it repeat forever.`);
+}
+function printStats(r, print) {
+    const s = r.stats;
+    const graphs = r.settings !== undefined ? `, ${r.settings} settings in ${r.graphs} state graph(s)` : '';
+    print(`States: ${s.states} (expanded ${s.expanded}, edges ${s.edges}, depth ${s.maxDepth}, symmetry group of ${s.group})${graphs}`);
+    if (r.revision)
+        print(`Revision: ${r.revision}`);
+}
+function printVerdict(r, print, what) {
+    if (r.status === 'success')
+        print(`✅ ${what}: ${r.reason}`);
+    else if (r.status === 'failure')
+        print(`❌ ${what}: ${r.reason}`);
+    else
+        print(`⚠️  ${what}: exploration incomplete (${r.reason})`);
+}
+export async function checkConfig(project, name, settings, options, print) {
+    print(`Checking every admissible execution of ${name} (explorer)...`);
+    print(`Settings: ${JSON.stringify(settings)}`);
+    const r = await project.check(settings, options);
+    print('');
+    print('=== Result ===');
+    printStats(r, print);
+    printVerdict(r, print, 'Result');
+    printTrace(project, r, print);
+    return exitCode(r);
+}
+export async function checkAll(project, name, options, print, progress) {
+    print(`Checking every generated setting of ${name} (explorer${options.perSetting ? ', one state graph per setting' : ', settings of a ring size share a state graph'})...`);
+    const r = await project.checkAll(options, (done, total) => progress?.(`\rChecked ${done}/${total} settings`));
+    progress?.('\n');
+    print('');
+    print('=== Summary ===');
+    printStats(r, print);
+    printVerdict(r, print, r.status === 'failure' ? 'FAILURE FOUND' : r.status === 'success' ? 'ALL CONFIGURATIONS PASSED' : 'INCOMPLETE');
+    printTrace(project, r, print);
+    return exitCode(r);
+}
+/** `simulant check`: the first branch of every generated setting. */
+export function checkFirstBranches(project, name, options, print) {
+    print(`Starting checks for project: ${name} (first branch of each setting, explorer)`);
+    let tested = 0, succeeded = 0, failed = 0;
+    for (const settings of project.settingsGenerator?.() ?? []) {
+        tested++;
+        const r = project.checkFirstBranch(settings, options);
+        if (r.status === 'success') {
+            succeeded++;
+            continue;
+        }
+        failed++;
+        print(`Result: ${r.status === 'failure' ? 'Failure' : 'Incomplete'} (${r.reason})`);
+        print(`Settings: ${JSON.stringify(settings)}`);
+        printTrace(project, r, print);
+        break;
+    }
+    print('\n--- Summary ---');
+    print(`Project: ${name}`);
+    print(`Total Tested: ${tested}`);
+    print(`Succeeded: ${succeeded}`);
+    print(`Failed: ${failed}`);
+    print('---------------');
+    return failed ? 1 : 0;
+}
+const tex = (s) => s.replace(/[\\{}&%$#_^~]/g, c => c === '\\' ? '\\textbackslash{}' : c === '^' ? '\\^{}' : c === '~' ? '\\~{}' : `\\${c}`);
+/** The explored state graph in TikZ: states by depth, edges labelled with their witnesses. */
+export function stateGraphTikz(project, settings, options) {
+    const g = project.stateGraph(settings, options);
+    const model = project.setup(settings);
+    const lines = [
+        '\\begin{tikzpicture}[',
+        '  node/.style={circle, draw, minimum size=1cm},',
+        '  success/.style={node, fill=green!20},',
+        '  failure/.style={node, fill=red!20},',
+        '  inProgress/.style={node, fill=orange!20},',
+        '  edge/.style={->, font=\\tiny}',
+        ']',
+        '',
+    ];
+    const perDepth = new Map();
+    for (const s of g.states) {
+        const x = (perDepth.get(s.depth) ?? 0) * 3;
+        perDepth.set(s.depth, x / 3 + 1);
+        const shown = project.debugConfig ? tex(project.debugConfig(s.config, model)) : String(s.id);
+        lines.push(`  \\node[${s.verdict}] (s${s.id}) at (${x},${-s.depth * 2}) {\\begin{tabular}{c}\\tiny s${s.id} \\\\ \\texttt{\\tiny ${shown}}\\end{tabular}};`);
+    }
+    lines.push('');
+    for (const e of g.edges) {
+        const loop = e.from === e.to ? ' [loop right]' : '';
+        lines.push(`  \\draw[edge] (s${e.from}) to${loop} node[midway, sloped, above] {${tex(e.label)}} (s${e.to});`);
+    }
+    lines.push('\\end{tikzpicture}');
+    return { tikz: lines.join('\n'), states: g.states.length, complete: g.complete };
+}

package/dist/lean.js

@@ -0,0 +1,118 @@
+/**
+ * Lean generation for a project (plan, Sections 5 and 6.6): `simulant lean -p <simulation>`.
+ *
+ *   <project>/lean/lakefile.toml               created once, then the researcher's
+ *   <project>/lean/lean-toolchain              the workspace's toolchain, created once
+ *   <project>/lean/Generated/<Module>/Model.lean   replaced by each generation
+ *   <project>/lean/Generated/<Module>/revision.json source revision and toolchain of the file
+ *   <project>/lean/Proofs/                     hand-written proofs: never written by generation
+ *
+ * After a change, the proofs must be checked again (`--build` runs `lake build`, which also
+ * checks them, after a scan for constructs a proof file may not use).
+ */
+import { spawn } from "node:child_process";
+import { existsSync, mkdirSync, readdirSync, readFileSync, realpathSync, writeFileSync } from "node:fs";
+import { dirname, join, relative, sep } from "node:path";
+import { createRequire } from "node:module";
+import { checkProofFile } from "@bramas/simulant-lean-gen/check-proofs";
+import { generateModel } from "@bramas/simulant-lean-gen/model";
+import { leanModuleName } from "@bramas/simulant-lean-gen/names";
+const libraryLean = dirname(createRequire(import.meta.url).resolve('@bramas/simulant-lean/package.json'));
+export { leanModuleName } from "@bramas/simulant-lean-gen/names";
+function writeIfChanged(file, text) {
+    if (existsSync(file) && readFileSync(file, 'utf8') === text)
+        return false;
+    writeFileSync(file, text);
+    return true;
+}
+/** Writes the generated files; returns the paths written. Never touches `Proofs/`. */
+export function generateProjectLean(project, simulation, projectDir, out = join(projectDir, 'lean')) {
+    if (!project.experiment)
+        throw new Error(`${simulation} is not a .sim project: there is nothing to generate`);
+    const module = leanModuleName(simulation);
+    const exp = project.experiment().ir;
+    const written = [];
+    mkdirSync(join(out, 'Generated', module), { recursive: true });
+    mkdirSync(join(out, 'Proofs'), { recursive: true });
+    const lakefile = join(out, 'lakefile.toml');
+    if (!existsSync(lakefile)) {
+        writeFileSync(lakefile, `name = "${leanModuleName(projectDir.split('/').pop() ?? 'project')}"
+defaultTargets = ["Generated", "Proofs"]
+
+# The Simulant semantic core and component library.
+[[require]]
+name = "simulant"
+path = ${JSON.stringify(relative(realpathSync(out), libraryLean).split(sep).join('/') || '.')}
+
+# Generated by \`simulant lean\`: replaced by each generation.
+[[lean_lib]]
+name = "Generated"
+globs = ["Generated.+"]
+
+# Hand-written proofs: never written by generation.
+[[lean_lib]]
+name = "Proofs"
+globs = ["Proofs.+"]
+`);
+        written.push(lakefile);
+    }
+    const toolchain = join(out, 'lean-toolchain');
+    if (!existsSync(toolchain)) {
+        writeFileSync(toolchain, readFileSync(join(libraryLean, 'lean-toolchain'), 'utf8'));
+        written.push(toolchain);
+    }
+    const model = join(out, 'Generated', module, 'Model.lean');
+    if (writeIfChanged(model, generateModel(exp, `Generated.${module}`)))
+        written.push(model);
+    const revision = join(out, 'Generated', module, 'revision.json');
+    const info = { simulation, experiment: exp.name, revision: project.revision?.(), toolchain: readFileSync(join(libraryLean, 'lean-toolchain'), 'utf8').trim() };
+    if (writeIfChanged(revision, JSON.stringify(info, null, 2) + '\n'))
+        written.push(revision);
+    return { module, out, written };
+}
+/** Problems of the hand-written proof files (forbidden constructs, see check-proofs.ts). */
+export function scanProofs(out) {
+    const dir = join(out, 'Proofs');
+    const files = existsSync(dir) ? readdirSync(dir, { recursive: true }).map(String).filter(f => f.endsWith('.lean')) : [];
+    return files.flatMap(f => checkProofFile(readFileSync(join(dir, f), 'utf8')).map(p => `Proofs/${f}: ${p}`));
+}
+/** `lake build` in the project's Lean directory; cancelled by `signal`. */
+export function lakeBuild(out, print, signal) {
+    return new Promise(resolve => {
+        const child = spawn('lake', ['build'], { cwd: out, signal });
+        let output = '';
+        child.stdout.on('data', d => { output += d; });
+        child.stderr.on('data', d => { output += d; });
+        child.on('error', error => {
+            if (!signal?.aborted)
+                print(`lake build failed to start: ${error.message}`);
+            resolve(1);
+        });
+        child.on('close', code => {
+            if (signal?.aborted)
+                return resolve(1);
+            if (code)
+                print(output.trim());
+            resolve(code ? 1 : 0);
+        });
+    });
+}
+export async function leanCommand(project, simulation, projectDir, options, print) {
+    const { module, out, written } = generateProjectLean(project, simulation, projectDir, options.out);
+    print(`Lean model of ${simulation}: ${join(out, 'Generated', module, 'Model.lean')} (revision ${project.revision?.() ?? '?'})`);
+    print(written.length ? `Written: ${written.map(f => relative(out, f)).join(', ')}` : 'Up to date: nothing written.');
+    if (written.some(f => f.endsWith('Model.lean')))
+        print('The proofs in Proofs/ must be checked again against the new definitions.');
+    const problems = scanProofs(out);
+    for (const p of problems)
+        print(`❌ ${p}`);
+    if (problems.length)
+        return 1;
+    if (!options.build)
+        return 0;
+    print('Running lake build (the generated model and the proofs)...');
+    const code = await lakeBuild(out, print, options.signal);
+    if (!options.signal?.aborted)
+        print(code ? '❌ lake build failed' : '✅ lake build succeeded: the model and the proofs check');
+    return code;
+}

package/dist/project-registry.js

@@ -0,0 +1,108 @@
+import { access, readFile, readdir } from "node:fs/promises";
+import { basename, dirname, join, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+function exportTarget(value) {
+    if (typeof value === 'string')
+        return value;
+    if (value && typeof value === 'object') {
+        const conditions = value;
+        return exportTarget(conditions.node) ?? exportTarget(conditions.import) ?? exportTarget(conditions.default);
+    }
+}
+async function packageAt(directory) {
+    let manifest;
+    try {
+        manifest = JSON.parse(await readFile(join(directory, 'package.json'), 'utf8'));
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return;
+        throw error;
+    }
+    const declared = exportTarget(manifest.exports?.['./projects']);
+    const candidates = declared ? [declared] : ['projects.ts', 'src/projects.ts'];
+    for (const candidate of candidates) {
+        const registry = resolve(directory, candidate);
+        try {
+            await access(registry);
+            return { slug: basename(directory), registry };
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+            if (declared)
+                throw new Error(`Project registry declared in ${directory}/package.json does not exist: ${registry}`);
+        }
+    }
+}
+async function packagesIn(directory) {
+    let entries;
+    try {
+        entries = await readdir(directory, { withFileTypes: true });
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return [];
+        throw error;
+    }
+    const packages = [];
+    for (const entry of entries) {
+        if (!entry.isDirectory() || entry.name.startsWith('.'))
+            continue;
+        const pkg = await packageAt(join(directory, entry.name));
+        if (pkg)
+            packages.push(pkg);
+    }
+    return packages.sort((a, b) => a.slug.localeCompare(b.slug));
+}
+export async function discoverProjectPackages(source = {}) {
+    const root = resolve(source.root ?? process.cwd());
+    if (source.registry)
+        return [{ slug: basename(root), registry: resolve(root, source.registry) }];
+    const [currentPackage, publicPackages, privatePackages] = await Promise.all([
+        packageAt(root), packagesIn(join(root, 'projects')), packagesIn(join(root, 'projects/private')),
+    ]);
+    return [...(currentPackage ? [currentPackage] : []), ...publicPackages, ...privatePackages];
+}
+async function loadRegistry(pkg) {
+    const module = await import(pathToFileURL(pkg.registry).href);
+    if (!module.projects || typeof module.projects !== 'object') {
+        throw new Error(`${pkg.registry} must export a projects map`);
+    }
+    return module.projects;
+}
+export async function listProjects(source = {}) {
+    const registries = await Promise.all((await discoverProjectPackages(source)).map(loadRegistry));
+    const names = registries.flatMap(registry => Object.keys(registry));
+    if (new Set(names).size !== names.length)
+        throw new Error('Duplicate simulation names in project registries');
+    return names.sort();
+}
+/** Prefer the matching package so an unrelated private project cannot break a public command. */
+export async function loadProject(name, source = {}) {
+    return (await locateProject(name, source)).project;
+}
+/** A simulation and the directory of the package that registers it (its `package.json`). */
+export async function locateProject(name, source = {}) {
+    const packages = await discoverProjectPackages(source);
+    const matching = packages.filter(pkg => name === pkg.slug || name.startsWith(`${pkg.slug}-`));
+    const candidates = matching.length ? matching : packages;
+    for (const pkg of candidates) {
+        const registry = await loadRegistry(pkg);
+        if (Object.hasOwn(registry, name))
+            return { project: registry[name], directory: await packageDirectory(pkg.registry) };
+    }
+    throw new Error(`Unknown project "${name}". Run simulant list-projects to see available simulations.`);
+}
+async function packageDirectory(registry) {
+    for (let dir = dirname(registry);; dir = dirname(dir)) {
+        try {
+            await access(join(dir, 'package.json'));
+            return dir;
+        }
+        catch {
+            if (dirname(dir) === dir)
+                return dirname(registry);
+        }
+    }
+}

package/dist/smoke-checker.js

@@ -0,0 +1,21 @@
+import { listProjects, loadProject } from "./project-registry.js";
+import { checkFirstBranches } from "./explorer-commands.js";
+// This checks the first branch at each step. Use cli check-config for exhaustive checking.
+export async function runSmokeChecker(projectName, source = {}) {
+    if (!projectName) {
+        console.log('Usage: simulant check <simulation-name>');
+        console.log('Available projects:');
+        for (const name of await listProjects(source))
+            console.log(`  - ${name}`);
+        return;
+    }
+    const project = await loadProject(projectName, source);
+    if (!project.checkFirstBranch) {
+        console.error(`Error: Project "${projectName}" does not provide checkFirstBranch (simulations are .sim experiments registered with simProject)`);
+        process.exit(1);
+    }
+    // The first branch, judged by the explorer's goal semantics.
+    const code = checkFirstBranches(project, projectName, {}, line => console.log(line));
+    if (code)
+        process.exit(code);
+}

package/dist/watch.js

@@ -0,0 +1,51 @@
+/** Must be called before the registry is loaded: compiled `.sim` modules then watch their sources. */
+export function requestWatch() {
+    globalThis.__simulantWatch = true;
+}
+export class Superseded extends Error {
+    constructor() { super('superseded by a newer revision'); }
+}
+export function watchProject(project, run, print) {
+    if (!project.subscribe)
+        throw new Error('--watch needs a .sim project');
+    let controller;
+    const start = () => {
+        controller?.abort(new Superseded());
+        const own = controller = new AbortController();
+        print(`--- revision ${project.revision?.() ?? '?'} (${new Date().toLocaleTimeString()}) ---`);
+        run(own.signal).then(code => { if (!own.signal.aborted)
+            print(`--- exit code ${code}; watching for changes (Ctrl-C to stop) ---`); }, error => {
+            if (own.signal.aborted)
+                return;
+            print(`Error: ${error instanceof Error ? error.message : error}`);
+            print('--- exit code 1; watching for changes (Ctrl-C to stop) ---');
+        });
+    };
+    const unsubscribe = project.subscribe(update => {
+        if (update.kind === 'replaced') {
+            print('');
+            print('Sources changed.');
+            start();
+        }
+        else if (update.kind === 'failed') {
+            controller?.abort(new Superseded());
+            print('');
+            print(`--- revision ${update.revision}: the sources do not compile ---`);
+            for (const d of update.diagnostics)
+                print(d);
+            print('--- watching for changes ---');
+        }
+        else {
+            print(`(sources changed without changing the experiment: revision ${project.revision?.()}, results unchanged)`);
+        }
+    });
+    // The watchers poll the sources; this keeps the process alive until stopped.
+    let resolve;
+    const done = new Promise(r => { resolve = r; });
+    const alive = setInterval(() => { }, 1 << 30);
+    start();
+    return {
+        done,
+        stop: () => { controller?.abort(new Superseded()); unsubscribe(); clearInterval(alive); resolve(); },
+    };
+}

package/package.json

@@ -1,6 +1,37 @@
 {
   "name": "@bramas/simulant-cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.1",
+  "private": false,
+  "license": "CECILL-B",
+  "type": "module",
+  "engines": {
+    "node": ">=20.6.0"
+  },
+  "bin": {
+    "simulant": "./bin/simulant.mjs"
+  },
+  "files": [
+    "src",
+    "dist",
+    "bin",
+    "LICENCE.txt"
+  ],
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "dependencies": {
+    "commander": "^14.0.2",
+    "tsx": "^4.20.6",
+    "@bramas/simulant-core": "0.1.1",
+    "@bramas/simulant-lean-gen": "0.1.1",
+    "@bramas/simulant-lang": "0.1.1",
+    "@bramas/simulant-lean": "0.1.1",
+    "@bramas/simulant-vite-plugin": "0.1.1"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Bramas/simulant.git",
+    "directory": "packages/cli"
+  }
 }