@josfox/jos 4.0.8 → 5.0.0

package/src/args.js

@@ -0,0 +1,47 @@
+'use strict';
+// Command-line splitting shared by the commands. `--` ends the options: everything after it is a file,
+// so `jos run -- -odd-name.jos` works. A lone `-` is a file name, not an option.
+function split(args) {
+    const flags = [];
+    const files = [];
+    let positional = false;
+    for (const a of args) {
+        if (positional) files.push(a);
+        else if (a === '--') positional = true;
+        else if (a.length > 1 && a.startsWith('-')) flags.push(a);
+        else files.push(a);
+    }
+    return { flags, files, help: flags.includes('--help') || flags.includes('-h') };
+}
+
+// Like split, with options that take a value. spec maps an option to false (a switch), true (one value, the last one
+// given wins) or 'many' (repeatable, values in order). Returns { opts, files, help, error }: opts[name] is true, a
+// string or an array; error is the first problem found (an unknown option, or an option without its value), or null.
+function parse(args, spec) {
+    const opts = {};
+    const files = [];
+    let help = false;
+    let error = null;
+    let positional = false;
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i];
+        if (positional) { files.push(a); continue; }
+        if (a === '--') { positional = true; continue; }
+        if (!(a.length > 1 && a.startsWith('-'))) { files.push(a); continue; }
+        if (a === '--help' || a === '-h') { help = true; continue; }
+        if (!Object.prototype.hasOwnProperty.call(spec, a)) { if (!error) error = { option: a, kind: 'unknown' }; continue; }
+        if (spec[a] === false) { opts[a] = true; continue; }
+        if (i + 1 >= args.length) { if (!error) error = { option: a, kind: 'value' }; continue; }
+        const v = args[++i];
+        if (spec[a] === 'many') (opts[a] = opts[a] || []).push(v);
+        else opts[a] = v;
+    }
+    return { opts, files, help, error };
+}
+
+// The message for parse()'s error: "unknown option --x" or "option needs a value: --flow".
+function problem(error) {
+    return (error.kind === 'unknown' ? 'unknown option ' : 'option needs a value: ') + error.option;
+}
+
+module.exports = { split, parse, problem };

package/src/commands/_frozen/add.README.md

@@ -0,0 +1 @@
+Frozen in 5.0.0: `jos add` edited 0.0.7 `orchestration.definitions` and `orchestration.flows` and regenerated their `.sig.json` manifest (`jos run` verifies such a manifest again since jos-core 2.0.0-rc.8; `jos migrate` reseals the document as 2.0). jos-core runs 2.0 flows (`orchestration`, `use`, `needs`, gates); write them in the document (`jos start` writes one, `flow.jos`, and examples/03-flow-gate.jos is another). No date is set for `add`.

package/src/commands/_frozen/get.README.md

@@ -0,0 +1 @@
+Frozen in 5.0.0: downloads a .jos from a repo without verifying it and writes to a path built from meta.name (path traversal); to be rewritten on PAL/Store in F2/F3.

package/src/commands/_frozen/llm.README.md

@@ -0,0 +1 @@
+Frozen in 5.0.0: overwrites the .jos file with model output without validating it and sends the artifact with the encrypted vault file as the Bearer token; to be rewritten on PAL/Store in F2/F3.

package/src/commands/_frozen/prompts.README.md

@@ -0,0 +1 @@
+Frozen in 5.0.0: `optimize` overwrites the .jos file with model output without validating it, and the adapters fabricate quality scores; to be rewritten on PAL/Store in F2/F3.

package/src/commands/_frozen/repo.README.md

@@ -0,0 +1 @@
+Frozen in 5.0.0: manages ~/.jos/repos.json for the frozen `get`, which fetches unverified artifacts over plain HTTP; to be rewritten on PAL/Store in F2/F3.

package/src/commands/_frozen/serve-explorer.README.md

@@ -0,0 +1 @@
+Frozen in 5.0.0: the file explorer served files by cwd without a sandbox and exposed ~/.jos/secrets when cwd was HOME (the live src/serve.js keeps only `--mcp`); to be rewritten in F3.

package/src/commands/ids.js

@@ -0,0 +1,101 @@
+/**
+ * JOS IDS - the identifiers jos-core gives each document (JOSID): the content id art_<sha256 of the canonical
+ * document> (SPEC-2.0 §8.2) and the entity id ent_ = uuid5("<jos.kind>:<id>") of the name. For a folder with a
+ * .jos/ directory, also the directory hash that seals it (SPEC-2.0 §9.3). Nothing runs.
+ * Exit codes: 0 every document valid, 2 one or more invalid, 5 no kernel, 64 usage.
+ */
+'use strict';
+const path = require('path');
+const kernel = require('../kernel');
+const ui = require('../ui');
+const { RULE } = ui;
+const { parse, problem } = require('../args');
+
+const USAGE = 'usage: jos ids <file.jos | folder>... [--json]';
+
+const HELP = (C) => `
+${C.purple}${RULE}${C.reset}
+${C.bold}JOS IDS${C.reset} // Content and entity identifiers of .jos documents
+${C.purple}${RULE}${C.reset}
+
+${C.bold}Usage:${C.reset}
+  jos ids <file.jos | folder>... [--json]
+
+  artifact   art_ + SHA-256 of the canonical document (RFC 8785): changes when any byte
+             of meaning changes; the same in both reference kernels
+  entity     ent_ = UUIDv5 of "<jos.kind>:<id>": stays when the content changes
+  directory  for a folder D with D/.jos/manifest.jos: the hash over D/.jos/ that
+             integrity.hash must match for the folder to run (sealed)
+
+${C.bold}Options:${C.reset}
+  --json    Print one object per document (file, valid, artifact, kind, id, ent)
+
+${C.bold}Exit codes:${C.reset}
+  0 all valid, 2 one or more invalid, 5 no kernel, 64 usage
+`;
+
+function idsOf(core, given) {
+    const abs = path.resolve(given);
+    const file = core.documentPath(abs);
+    const out = { file: given, valid: false, artifact: null, kind: null, id: null, ent: null };
+    let v;
+    try { v = core.validate(core.loadFile(file)); } catch (e) {
+        if (!(e instanceof core.JosError)) throw e;
+        return Object.assign(out, { errors: e.errors });
+    }
+    out.valid = v.valid;
+    out.artifact = v.artifact;
+    if (!v.valid) return Object.assign(out, { errors: v.errors });
+    out.kind = v.document.jos.kind;
+    out.id = typeof v.document.id === 'string' ? v.document.id : null;
+    if (out.id !== null) out.ent = core.josid.named(out.kind, out.id);
+    if (file !== abs || path.basename(file) === 'manifest.jos') {
+        const jd = path.dirname(file);
+        const declared = v.document.integrity && typeof v.document.integrity.hash === 'string' ? v.document.integrity.hash : null;
+        out.directory = { hash: core.dirHash(jd).hash, sealed: declared !== null };
+        if (declared !== null) out.directory.matches = declared === out.directory.hash;
+    }
+    return out;
+}
+
+exports.execute = async (args) => {
+    const err = ui.printer(process.stderr);
+    const { opts, files, help, error } = parse(args, { '--json': false });
+    if (help) {
+        const out = ui.printer(process.stdout);
+        out.text(HELP(out.C));
+        return 0;
+    }
+    if (error || !files.length) {
+        err.fail('jos ids: ' + (error ? problem(error) : 'takes one or more files'));
+        err.hint(USAGE);
+        return 64;
+    }
+    let k;
+    let core;
+    try { k = kernel.locate(); core = kernel.need(k, ['validate', 'loadFile', 'documentPath', 'josid.named', 'dirHash']); } catch (e) { return kernel.fail(e); }
+    const rows = files.map((f) => idsOf(core, f));
+    const code = rows.every((r) => r.valid) ? 0 : 2;
+    if (opts['--json']) {
+        ui.json(process.stdout, rows);
+        return code;
+    }
+    const out = ui.printer(process.stdout);
+    out.header('JOS IDS', 'jos-core ' + k.version);
+    for (const r of rows) {
+        if (!r.valid) {
+            out.fail(r.file, '(invalid)');
+            for (const e of r.errors) out.hint(e);
+            continue;
+        }
+        out.ok(r.file, '(' + r.kind + (r.id === null ? '' : ' ' + r.id) + ')');
+        out.field('artifact', r.artifact);
+        out.field('entity', r.ent === null ? 'none (the document has no id)' : r.ent);
+        if (r.directory) {
+            const seal = !r.directory.sealed ? 'not sealed (no integrity.hash)' : r.directory.matches ? 'sealed, matches' : 'sealed, does NOT match: jos run refuses it (code 3)';
+            out.field('directory', r.directory.hash + ' (' + seal + ')');
+        }
+    }
+    out.line();
+    return code;
+};

package/src/commands/init.js

@@ -1,162 +1,128 @@
 /**
- * JOS INIT Command - Create new .jos artifacts
- * Creates a minimal valid .jos with detached integrity manifest
- * Format version v0.0.7 — Specification maturity v0.1.0 (Alpha)
+ * JOS INIT - write a new .jos document that `jos run` accepts today.
+ * 5.0.0 writes a 2.0.0 atom (SPEC-2.0 §3), validated by jos-core before it touches the disk; 4.1.0 wrote a
+ * 0.0.7 document with flows plus a `.sig.json` manifest (verified by run; jos migrate reseals such a document).
+ * Exit codes: 0 written, 1 file exists or cannot be written, 5 no kernel, 64 usage.
  */
-
+'use strict';
 const fs = require('fs');
 const path = require('path');
-const crypto = require('crypto');
-
-const C = {
-    reset: '\x1b[0m', bold: '\x1b[1m',
-    purple: '\x1b[38;5;135m', cyan: '\x1b[38;5;51m',
-    green: '\x1b[38;5;78m', gray: '\x1b[38;5;245m'
-};
-
-exports.execute = async (args, home) => {
-    const name = args[0] || 'new-artifact';
-    const type = args.includes('--pipeline') ? 'pipeline' : 'atom';
-    const filename = `${name}.jos`;
-
-    if (args.includes('--help') || args.includes('-h')) {
-        console.log(`
-${C.purple}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${C.reset}
-${C.bold}JOS INIT${C.reset} // Create new .jos artifacts
-${C.purple}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${C.reset}
+const kernel = require('../kernel');
+const ui = require('../ui');
+const { RULE } = ui;
+const { split } = require('../args');
+
+const NAME = /^[a-z][a-z0-9._-]*$/; // same alphabet as the document id (SPEC-2.0 §2.7)
+const EXT = /\.jos(\.json)?$/; // a name that already ends in .jos or .jos.json gets no second extension
+
+// "hola" -> hola.jos, "hola.jos" -> hola.jos, "hola.jos.json" -> hola.jos.json, "dir/hola.jos" -> dir/hola.jos;
+// the id is the file name without its extension and without the directory: "hola" in all four.
+function target(given) {
+    const ext = EXT.test(given) ? '' : '.jos';
+    const shown = given + ext;
+    return { shown, file: path.resolve(shown), id: path.basename(given).replace(EXT, '') };
+}
+
+const HELP = (C) => `
+${C.purple}${RULE}${C.reset}
+${C.bold}JOS INIT${C.reset} // Write a new .jos 2.0 atom
+${C.purple}${RULE}${C.reset}
 
 ${C.bold}Usage:${C.reset}
-  jos init <name> [options]
-
-${C.bold}Options:${C.reset}
-  --pipeline    Create a pipeline artifact (default: atom)
-
-${C.bold}Creates:${C.reset}
-  <name>.jos           The artifact file
-  <name>.jos.sig.json  Detached integrity manifest
-`);
-        return;
-    }
+  jos init <name> [--force]
 
-    console.log(`\n${C.purple}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${C.reset}`);
-    console.log(`${C.bold}JOS INIT${C.reset} // ${C.gray}Creating ${type} artifact${C.reset}`);
-    console.log(`${C.purple}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${C.reset}\n`);
-
-    // Create artifact with full JOSFOXAI + MAGIC compliance
-    const template = {
-        "$schema": "https://josfox.ai/schemas/jos-0.0.7.json",
-        "$comment": "Format version v0.0.7 — Specification maturity v0.1.0 (Alpha)",
-
-        // JOSFOXAI Kernel
-        "jos": {
-            "open": `jos run ${type}`,
-            "supports": ["@josfox/jos", "josctl"],
-            "canonical": "Format version v0.0.7 — Specification maturity v0.1.0 (Alpha)"
-        },
-        "orchestration_contract": {
-            "version": "0.0.7",
-            "mode": "sync"
-        },
-        "id_jos": `${type}-${name}-${Date.now()}`,
-        "adaptive_ai": {
-            "learning_mode": "frozen",
-            "llm_friendly_sentence": `This ${type} artifact performs the ${name} task.`
-        },
-        "security": {
-            "type": "open",
-            "permissions": [],
-            "health_check": null,
-            "integrity": null,
-            "integrity_ref": `./${filename}.sig.json`
-        },
-        "files": [],
-        "orchestration": {
-            "state": { "current_status": "idle" },
-            "definitions": {
-                "main_task": {
-                    "type": "shell",
-                    "description": "Main task - replace with your command",
-                    "command": "echo 'Hello from " + name + "'"
-                }
-            },
-            "flows": {
-                "main": {
-                    "description": "Main execution flow",
-                    "steps": ["main_task"]
-                }
-            }
-        },
-        "x_run_params": {
-            "timeout": 300,
-            "retry_on_failure": false
-        },
+${C.bold}Writes:${C.reset}
+  <name>.jos    a 2.0.0 atom: intention, success criteria, guardrails and a shell step,
+                validated by jos-core before writing; run it with \`jos run <name>.jos\`
+                A name that already ends in .jos or .jos.json is used as is:
+                \`jos init hola.jos\` writes hola.jos, \`jos init dir/hola\` writes dir/hola.jos
+                (dir must exist).
 
-        // MAGIC Kernel
-        "meta": {
-            "version": "1.0.0",
-            "type": type,
-            "name": name,
-            "provider": "local",
-            "author": "JOS Developer",
-            "canonical_version": "Format version v0.0.7 — Specification maturity v0.1.0 (Alpha)"
-        },
-        "artifacts": {
-            "description": `Auto-generated ${type} artifact. Update this description.`,
-            "outputs": []
+${C.bold}Options:${C.reset}
+  --force       overwrite the file if it exists
+
+${C.bold}Name:${C.reset} the file name without .jos / .jos.json becomes the document id: lowercase letter
+      first, then letters, digits, '.', '_' or '-'
+${C.dim}--pipeline was removed: init writes atoms only. For a flow, see the flow.jos that jos start writes.${C.reset}
+`;
+
+function template(name) {
+    return {
+        jos: { version: '2.0.0', kind: 'atom' },
+        id: name,
+        meta: { name, version: '0.1.0', description: 'Replace this description.' },
+        intention: {
+            objective: 'Describe what done means for ' + name + '.',
+            success_criteria: [{ exit: 0 }, { stdout_contains: 'Hello from ' + name }],
         },
-        "guardrails": {
-            "avoid": [],
-            "max_retries": 1
+        guardrails: {
+            avoid: ['rm -rf', 'curl', 'wget'],
+            limit: { seconds: 30, output_bytes: 65536, retries: 0 },
         },
-        "intention": {
-            "objective": "Define your objective here",
-            "success_criteria": "Define success criteria here"
+        execution: {
+            engine: 'shell',
+            run: ['echo', 'Hello from ' + name],
+            on_error: 'fail',
+            env: ['PATH', 'HOME'],
+            cwd: '.',
         },
-        "capabilities": []
-    };
-
-    // Write artifact
-    const content = JSON.stringify(template, null, 2);
-    fs.writeFileSync(filename, content);
-    console.log(`${C.green}✓ Created:${C.reset} ${filename}`);
-
-    // Generate integrity manifest
-    const sha256 = crypto.createHash('sha256').update(content).digest('hex');
-    const stats = fs.statSync(filename);
-
-    const manifest = {
-        "$schema": "https://josfox.ai/schemas/jos-manifest-0.0.7.json",
-        "manifest_version": "1.0.0",
-        "artifact_ref": filename,
-        "artifact_sha256": sha256,
-        "artifact_size_bytes": stats.size,
-        "timestamp": new Date().toISOString(),
-        "generated_by": "jos init command",
-        "canonical_version": "Format version v0.0.7 — Specification maturity v0.1.0 (Alpha)"
     };
+}
+
+exports.execute = async (args) => {
+    const err = ui.printer(process.stderr);
+    const { flags, files, help } = split(args);
+    if (help) {
+        const out = ui.printer(process.stdout);
+        out.text(HELP(out.C));
+        return 0;
+    }
+    for (const f of flags) {
+        if (f === '--force') continue;
+        err.fail('jos init: unknown option ' + f + (f === '--pipeline' ? ' (removed in 5.0.0: init writes atoms; jos start writes a flow to copy)' : ''));
+        return 64;
+    }
+    if (files.length !== 1) {
+        err.fail('jos init: takes exactly one name');
+        err.hint('usage: jos init <name> [--force]');
+        return 64;
+    }
+    const t = target(files[0]);
+    if (!NAME.test(t.id) || t.id.length > 128) {
+        err.fail('jos init: invalid name ' + JSON.stringify(t.id));
+        err.hint('the id is the file name without .jos: lowercase letter first, then [a-z0-9._-], at most 128');
+        return 64;
+    }
+    const dir = path.dirname(t.file);
+    if (!fs.existsSync(dir) || !fs.statSync(dir).isDirectory()) {
+        err.fail('jos init: ' + path.dirname(t.shown) + ' is not an existing directory');
+        return 1;
+    }
+    if (fs.existsSync(t.file) && !flags.includes('--force')) {
+        err.fail('jos init: ' + t.shown + ' exists', '(use --force to overwrite)');
+        return 1;
+    }
 
-    const manifestPath = filename + '.sig.json';
-    fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2));
-    console.log(`${C.green}✓ Created:${C.reset} ${manifestPath}`);
-    console.log(`${C.gray}  SHA256: ${sha256}${C.reset}`);
-
-    console.log(`
-${C.cyan}Next steps:${C.reset}
-  1. Edit ${filename} to define your tasks
-  2. Run: ${C.purple}jos validate ${filename}${C.reset}
-  3. Run: ${C.purple}jos run ${filename}${C.reset}
-`);
-
-    // Log to witness
-    const runDir = path.join(home, 'runs', 'init-' + new Date().toISOString().replace(/[:.]/g, '-'));
-    if (!fs.existsSync(runDir)) fs.mkdirSync(runDir, { recursive: true });
+    let k;
+    try { k = kernel.locate(); } catch (e) { return kernel.fail(e); }
+    const doc = template(t.id);
+    const v = k.core.validate(doc);
+    if (!v.valid) throw new Error('jos init: the template is not valid for jos-core ' + k.version + ': ' + v.errors.join('; '));
+
+    const tmp = t.file + '.tmp';
+    try {
+        fs.writeFileSync(tmp, JSON.stringify(doc, null, 2) + '\n');
+        fs.renameSync(tmp, t.file);
+    } catch (e) {
+        // the environment refused the write (EACCES, EROFS, ENOSPC...): an error, not a host bug
+        try { fs.rmSync(tmp, { force: true }); } catch (e2) { /* nothing to clean */ }
+        err.fail('jos init: cannot write ' + t.shown + ': ' + (e && e.code ? e.code : e.message));
+        return 1;
+    }
 
-    const event = {
-        timestamp: new Date().toISOString(),
-        type: 'init:created',
-        artifact: filename,
-        manifest: manifestPath,
-        sha256: sha256
-    };
-    fs.appendFileSync(path.join(runDir, 'events.jsonl'), JSON.stringify(event) + '\n');
+    err.header('JOS INIT', 'jos-core ' + k.version);
+    err.ok('Written: ' + t.shown, `(2.0.0 atom, id ${t.id}, ${v.artifact})`);
+    err.hint('Next: jos run ' + ui.shellArg(t.shown));
+    err.line();
+    return 0;
 };

package/src/commands/ledger.js

@@ -0,0 +1,94 @@
+/**
+ * JOS LEDGER - `jos ledger verify <run_ | file>`: checks the hash chain of a run's ledger with jos-core
+ * (Ledger 0.1.0 §2): every entry hash recomputed, seq, prev and run continuous, the run ended with its `end` entry.
+ * Read-only. Exit codes: 0 verifies, 1 does not verify, 2 no ledger or unreadable, 5 no kernel, 64 usage.
+ */
+'use strict';
+const kernel = require('../kernel');
+const ledgers = require('../ledgers');
+const ui = require('../ui');
+const { RULE } = ui;
+const { parse, problem } = require('../args');
+
+const USAGE = 'usage: jos ledger verify <run_id | ledger.jsonl | run folder> [--json]';
+
+const HELP = (C) => `
+${C.purple}${RULE}${C.reset}
+${C.bold}JOS LEDGER${C.reset} // Verify the ledger of a run with jos-core
+${C.purple}${RULE}${C.reset}
+
+${C.bold}Usage:${C.reset}
+  jos ledger verify <run_id | ledger.jsonl | run folder> [--json]
+
+  A run id (run_...) is looked up in .jos/replays/ of the folders above the current
+  directory, then in ~/.jos/runs/. Every entry's hash is recomputed over its canonical
+  form (RFC 8785); seq, prev and run must be continuous and the run must have ended.
+  Nothing is written.
+
+${C.bold}Options:${C.reset}
+  --json    Print the verification result as JSON
+
+${C.bold}Exit codes:${C.reset}
+  0 verifies, 1 does not verify, 2 no ledger or unreadable, 5 no kernel, 64 usage
+
+${C.bold}See also:${C.reset}
+  jos runs              list the runs in ~/.jos/runs
+  jos meter <run_id>    tokens, cost and time from a verified ledger
+`;
+
+exports.execute = async (args, josHome) => {
+    const err = ui.printer(process.stderr);
+    const { opts, files, help, error } = parse(args, { '--json': false });
+    if (help) {
+        const out = ui.printer(process.stdout);
+        out.text(HELP(out.C));
+        return 0;
+    }
+    if (error || files[0] !== 'verify' || files.length !== 2) {
+        err.fail('jos ledger: ' + (error ? problem(error) : 'takes the subcommand verify and one run'));
+        err.hint(USAGE);
+        return 64;
+    }
+    const ref = files[1];
+
+    let core;
+    try { core = kernel.need(kernel.locate(), ['ledger.find', 'ledger.read', 'ledger.verify']); } catch (e) { return kernel.fail(e); }
+    const where = ledgers.locate(core, ref, josHome);
+    if (where.error === 'usage') {
+        err.fail('jos ledger: ' + ref + ' is not a run id (run_...) nor a ledger file');
+        err.hint(USAGE);
+        return 64;
+    }
+    if (where.error === 'missing') {
+        ledgers.explainMissing(err, 'ledger', ref, josHome);
+        return 2;
+    }
+    const r = ledgers.read(core, where.file);
+    if (r.errors) {
+        err.fail('jos ledger: ' + where.file + ': ' + r.errors.join('; '));
+        return 2;
+    }
+    const v = Object.assign(core.ledger.verify(r.lines, {}), { file: where.file });
+    if (opts['--json']) {
+        ui.json(process.stdout, v);
+        return v.ok ? 0 : 1;
+    }
+    const out = ui.printer(process.stdout);
+    out.header('JOS LEDGER', 'verify');
+    out.field('File', v.file);
+    if (v.ok) {
+        out.field('Run', v.run);
+        out.field('Entries', String(v.count));
+        out.field('Head', v.head);
+        out.line();
+        out.ok(out.C.bold + 'LEDGER VERIFIED', '(every hash recomputed, chain continuous, run ended)');
+        out.line();
+        return 0;
+    }
+    out.field('Reason', v.reason);
+    out.field('First bad entry', String(v.first_bad_seq));
+    out.line();
+    out.fail(out.C.bold + 'LEDGER DOES NOT VERIFY');
+    out.line();
+    return 1;
+};

package/src/commands/meter.js

@@ -0,0 +1,96 @@
+/**
+ * JOS METER - `jos meter <run_ | file>`: the metering view of a run (Ledger 0.1.0 §5) computed by jos-core from the
+ * run's ledger, only when that ledger verifies: attempts, time, tokens, cost, approvals. A meter that no engine
+ * reported is "not reported", never zero. Read-only.
+ * Exit codes: 0 metered, 1 the ledger does not verify, 2 no ledger or unreadable, 5 no kernel, 64 usage.
+ */
+'use strict';
+const kernel = require('../kernel');
+const ledgers = require('../ledgers');
+const ui = require('../ui');
+const { RULE } = ui;
+const { parse, problem } = require('../args');
+
+const USAGE = 'usage: jos meter <run_id | ledger.jsonl | run folder> [--json]';
+
+const HELP = (C) => `
+${C.purple}${RULE}${C.reset}
+${C.bold}JOS METER${C.reset} // Tokens, cost and time of a run, from its verified ledger
+${C.purple}${RULE}${C.reset}
+
+${C.bold}Usage:${C.reset}
+  jos meter <run_id | ledger.jsonl | run folder> [--json]
+
+  The ledger is found like \`jos ledger verify\` finds it, and must verify: the numbers
+  come only from its receipts. Tokens and cost appear when an engine reported them;
+  the shell engine reports neither, so they read "not reported" (never 0).
+
+${C.bold}Options:${C.reset}
+  --json    Print the meter as JSON (null for a meter no engine reported)
+
+${C.bold}Exit codes:${C.reset}
+  0 metered, 1 the ledger does not verify, 2 no ledger or unreadable, 5 no kernel, 64 usage
+`;
+
+const shown = (v, f) => (v === null ? 'not reported' : f(v));
+
+exports.execute = async (args, josHome) => {
+    const err = ui.printer(process.stderr);
+    const { opts, files, help, error } = parse(args, { '--json': false });
+    if (help) {
+        const out = ui.printer(process.stdout);
+        out.text(HELP(out.C));
+        return 0;
+    }
+    if (error || files.length !== 1) {
+        err.fail('jos meter: ' + (error ? problem(error) : 'takes exactly one run'));
+        err.hint(USAGE);
+        return 64;
+    }
+    const ref = files[0];
+
+    let core;
+    try { core = kernel.need(kernel.locate(), ['ledger.find', 'ledger.read', 'ledger.meter']); } catch (e) { return kernel.fail(e); }
+    const where = ledgers.locate(core, ref, josHome);
+    if (where.error === 'usage') {
+        err.fail('jos meter: ' + ref + ' is not a run id (run_...) nor a ledger file');
+        err.hint(USAGE);
+        return 64;
+    }
+    if (where.error === 'missing') {
+        ledgers.explainMissing(err, 'meter', ref, josHome);
+        return 2;
+    }
+    const r = ledgers.read(core, where.file);
+    if (r.errors) {
+        err.fail('jos meter: ' + where.file + ': ' + r.errors.join('; '));
+        return 2;
+    }
+    let m;
+    try { m = core.ledger.meter(r.lines); } catch (e) {
+        if (!(e instanceof core.JosError)) throw e;
+        err.fail('jos meter: the ledger of ' + ref + ' does not verify; meter reads only a verified ledger');
+        err.hint('see why: jos ledger verify ' + ui.shellArg(ref));
+        return 1;
+    }
+    if (opts['--json']) {
+        ui.json(process.stdout, Object.assign({}, m, { file: where.file }));
+        return 0;
+    }
+    const out = ui.printer(process.stdout);
+    out.header('JOS METER', m.run);
+    out.field('Ledger', where.file + ' (verified)');
+    out.field('Code', m.code === null ? 'none (the run has no end entry)' : String(m.code));
+    out.field('Steps', m.steps.length ? m.steps.join(', ') : 'none');
+    out.field('Engines', m.engines.length ? m.engines.join(', ') : 'none');
+    out.field('Attempts', String(m.attempts));
+    out.field('Time', shown(m.duration_ms, (v) => v + ' ms (sum of the receipts)'));
+    out.field('Tokens in', shown(m.tokens_in, String));
+    out.field('Tokens out', shown(m.tokens_out, String));
+    out.field('Cost', shown(m.cost_usd, (v) => v + ' USD'));
+    out.field('Approvals', String(m.approvals));
+    out.field('Denials', String(m.denials));
+    out.field('Cache hits', String(m.cache_hits));
+    out.line();
+    return 0;
+};