@josfox/jos 4.0.8 → 5.0.0

package/src/intention.js

@@ -0,0 +1,114 @@
+'use strict';
+// The intention of a document and the verdict of a run, in words, for `jos run` and `jos validate` (text mode only;
+// `--json` is the kernel's result unchanged). The intention comes from the document as jos-core normalized it
+// (intention.objective, intention.success_criteria, guardrails.avoid and guardrails.limit); the verdict comes only
+// from the receipts the kernel returned (criteria[].check / verdict / detail): the host evaluates nothing itself.
+
+const ONE_LINE = 160;
+
+const isObj = (x) => x !== null && typeof x === 'object' && !Array.isArray(x);
+const q = (s) => JSON.stringify(s);
+
+function oneLine(s) {
+    const t = s.replace(/\s+/g, ' ').trim();
+    return t.length > ONE_LINE ? t.slice(0, ONE_LINE - 1) + '…' : t;
+}
+
+// A declared success criterion as a short phrase: "exit 0", 'stdout contains "x"', "all of (exit 0; stderr is empty)".
+// Criteria come from a document jos-core validated, so each object has the one key its schema allows.
+const short = (h) => h.replace(/^sha256:/, '').slice(0, 12) + '…';
+function describe(c) {
+    if (typeof c === 'string') return oneLine(c) + ' (descriptive)';
+    const k = Object.keys(c)[0];
+    const v = c[k];
+    switch (k) {
+        case 'exit': return 'exit ' + v;
+        case 'stdout_contains': return 'stdout contains ' + q(v);
+        case 'stdout_matches': return 'stdout matches /' + v + '/';
+        case 'stderr_empty': return 'stderr is empty';
+        case 'file_exists': return 'file ' + q(v) + ' exists';
+        case 'file_sha256': return 'file ' + q(v.path) + ' has sha256 ' + short(v.hash);
+        case 'sha256': return 'output has sha256 ' + short(v);
+        case 'json_schema': return 'output validates against a JSON Schema';
+        case 'judge': return 'a judge engine grades it: ' + oneLine(v.rubric);
+        case 'all': case 'any': return k + ' of (' + v.map(describe).join('; ') + ')';
+        case 'not': return 'not (' + describe(v) + ')';
+        default: return k + ' ' + q(v);
+    }
+}
+
+const LIMIT_WORDS = { seconds: ' s', output_bytes: ' output bytes per stream', tokens: ' tokens', retries: ' retries' };
+function limitText(limit) {
+    return Object.keys(limit).map((k) => {
+        if (k === 'cost_usd') return limit[k] + ' USD';
+        if (Object.prototype.hasOwnProperty.call(LIMIT_WORDS, k)) return limit[k] + LIMIT_WORDS[k];
+        return k + ' ' + q(limit[k]);
+    }).join(', ');
+}
+
+// "Intention:", "Done when:", and when declared "Avoid:" and "Limit:", for the normalized document `doc`.
+function intention(p, doc) {
+    const { C } = p;
+    const it = isObj(doc.intention) ? doc.intention : {};
+    const g = isObj(doc.guardrails) ? doc.guardrails : {};
+    p.line();
+    p.line(`${C.bold}Intention:${C.reset} ` + (typeof it.objective === 'string' && it.objective.trim() ? oneLine(it.objective) : `${C.gray}not declared${C.reset}`));
+    const criteria = it.success_criteria === undefined ? [] : [].concat(it.success_criteria);
+    if (!criteria.length) p.line(`${C.bold}Done when:${C.reset} ${C.gray}not declared${C.reset}`);
+    else {
+        p.line(`${C.bold}Done when:${C.reset}`);
+        for (const c of criteria) p.item(describe(c));
+    }
+    if (Array.isArray(g.avoid) && g.avoid.length) p.line(`${C.bold}Avoid:${C.reset} ` + g.avoid.map(q).join(', '));
+    if (isObj(g.limit) && Object.keys(g.limit).length) p.line(`${C.bold}Limit:${C.reset} ` + limitText(g.limit));
+}
+
+// "Inferred:": the `inferred` section of jos-core (2.0.0-rc.8) for a valid document, one line per JSON Pointer in the
+// kernel's order: what the kernel applies that the document does not write (value and source, SPEC section or jos-core
+// default, and its note), and, flagged with ⚠, what the document does not declare.
+function inferred(p, section) {
+    const { C } = p;
+    const keys = Object.keys(section);
+    p.line();
+    if (!keys.length) {
+        p.line(`${C.bold}Inferred:${C.reset} ${C.gray}nothing (the document writes every member jos-core applies)${C.reset}`);
+        return;
+    }
+    p.line(`${C.bold}Inferred:${C.reset} ${C.gray}(applied by jos-core, not written in the document)${C.reset}`);
+    for (const k of keys) {
+        const e = section[k];
+        const note = e.note ? ` ${C.gray}— ${oneLine(e.note)}${C.reset}` : '';
+        if (e.source === 'not declared') p.line(`  ${C.yellow}⚠ ${k}: not declared${C.reset}` + note);
+        else p.item(k + (Object.prototype.hasOwnProperty.call(e, 'value') ? ' = ' + oneLine(JSON.stringify(e.value)) : '') + ` ${C.gray}(${e.source})${C.reset}` + note);
+    }
+}
+
+// One line per criterion verdict of a receipt, indented by depth; combinators list their items below them.
+function criteriaLines(p, list, depth) {
+    const { C } = p;
+    const pad = '  '.repeat(depth);
+    for (const c of list) {
+        const sign = c.verdict === 'pass' ? `${C.green}✓` : c.verdict === 'fail' ? `${C.red}✖` : `${C.gray}•`;
+        const note = c.verdict === 'descriptive' ? ' (descriptive, recorded only)' : '';
+        p.line(`${pad}${sign} ${c.check}${C.reset}${C.gray}: ${c.detail}${note}${C.reset}`);
+        if (Array.isArray(c.items)) criteriaLines(p, c.items, depth + 1);
+    }
+}
+
+// "Verdict:": per receipt (each step of a flow, then the flow itself) its code and the verdict of each criterion.
+// The caller passes a result with at least one receipt.
+function verdict(p, result) {
+    const { C } = p;
+    p.line();
+    p.line(`${C.bold}Verdict:${C.reset}`);
+    for (const r of result.receipts) {
+        const mark = r.ok ? `${C.green}✓` : `${C.red}✖`;
+        const label = r.flow ? r.step + ' (flow ' + r.flow + ')' : r.step;
+        p.line(`  ${C.blue}[${r.attempt}] ${label}${C.reset} ${mark} code ${r.code}${C.reset}` + (r.reason ? ` ${C.gray}${r.reason}${C.reset}` : ''));
+        const list = r.criteria || [];
+        if (list.length) criteriaLines(p, list, 2);
+        else p.line(`    ${C.gray}no criterion evaluated${C.reset}`);
+    }
+}
+
+module.exports = { describe, limitText, oneLine, intention, inferred, verdict };

package/src/kernel.js

@@ -0,0 +1,69 @@
+'use strict';
+// Locates the jos-core reference kernel. No network.
+//   1. the installed dependency @josfox/jos-core
+//   2. ../../../kernel/js/jos-core.js (monorepo checkout)
+//   3. otherwise a clear error; hosts map it to exit code 5 (SPEC-2.0 section 7.1).
+
+const fs = require('fs');
+const path = require('path');
+const ui = require('./ui');
+
+const MONOREPO_PATH = path.resolve(__dirname, '..', '..', '..', 'kernel', 'js', 'jos-core.js');
+
+class KernelNotFound extends Error {}
+
+let cached = null;
+
+function locate() {
+    if (cached) return cached;
+    let file = null;
+    let source = null;
+    try {
+        file = require.resolve('@josfox/jos-core');
+        source = 'dependency';
+    } catch (e) {
+        if (e.code !== 'MODULE_NOT_FOUND') throw e;
+    }
+    if (!file && fs.existsSync(MONOREPO_PATH)) {
+        file = MONOREPO_PATH;
+        source = 'monorepo';
+    }
+    if (!file) {
+        throw new KernelNotFound(
+            'jos-core not found. Install @josfox/jos-core next to @josfox/jos, ' +
+            'or run from a checkout that contains kernel/js/jos-core.js.');
+    }
+    let core;
+    try {
+        core = require(file);
+    } catch (e) {
+        throw new KernelNotFound('jos-core at ' + file + ' failed to load: ' + e.message);
+    }
+    for (const fn of ['validate', 'run', 'loadFile']) {
+        if (typeof core[fn] !== 'function') {
+            throw new KernelNotFound('jos-core at ' + file + ' does not export ' + fn + '()');
+        }
+    }
+    cached = { core, version: core.VERSION, file, source };
+    return cached;
+}
+
+// The kernel's core when it has every function in names ('validate', 'ledger.verify', ...); otherwise KernelNotFound
+// naming the first one missing (an older jos-core), which a command turns into exit 5 with fail().
+function need(k, names) {
+    for (const n of names) {
+        let v = k.core;
+        for (const part of n.split('.')) v = v === null || v === undefined ? undefined : v[part];
+        if (typeof v !== 'function') throw new KernelNotFound('jos-core ' + k.version + ' at ' + k.file + ' does not export ' + n + '()');
+    }
+    return k.core;
+}
+
+// Prints the error and returns exit code 5, for use as `return kernel.fail(e)`.
+function fail(e) {
+    if (!(e instanceof KernelNotFound)) throw e;
+    ui.printer(process.stderr).fail('jos: ' + e.message);
+    return 5;
+}
+
+module.exports = { locate, need, fail, KernelNotFound, MONOREPO_PATH };

package/src/ledgers.js

@@ -0,0 +1,57 @@
+'use strict';
+// Run ledgers for `jos ledger verify`, `jos meter` and `jos runs`: thin calls into the ledger API of jos-core
+// (Ledger 0.1.0: find, read, verify, meter). Read-only: nothing here writes, creates ~/.jos or runs a document.
+const fs = require('fs');
+const path = require('path');
+
+// A run id as jos-core mints it (`run_` + a ULID); anything else must be the path of a ledger.
+const RUN_ID = /^run_[0-9A-Za-z]{1,64}$/;
+
+const isFile = (p) => { try { return fs.statSync(p).isFile(); } catch (e) { return false; } };
+const isDir = (p) => { try { return fs.statSync(p).isDirectory(); } catch (e) { return false; } };
+
+// Where the ledger of `ref` is: { file } for a ledger file, a run folder holding ledger.jsonl, or a run id that
+// jos-core finds (.jos/replays/ of the folders above the current directory, then ~/.jos/runs/); { error: 'usage' }
+// when ref is neither a path nor a run id; { error: 'missing' } when no ledger of that run exists.
+function locate(core, ref, josHome) {
+    if (isFile(ref)) return { file: path.resolve(ref) };
+    if (isDir(ref) && isFile(path.join(ref, 'ledger.jsonl'))) return { file: path.resolve(ref, 'ledger.jsonl') };
+    if (!RUN_ID.test(ref)) return { error: 'usage' };
+    const file = core.ledger.find(ref, { home: path.dirname(josHome) });
+    return file === null ? { error: 'missing' } : { file };
+}
+
+// The lines of a ledger file, or { errors } when it cannot be read (a JosError of the kernel).
+function read(core, file) {
+    try { return { lines: core.ledger.read(file) }; } catch (e) {
+        if (!(e instanceof core.JosError)) throw e;
+        return { errors: e.errors };
+    }
+}
+
+// What a listing shows of one run, from its ledger lines: whether the ledger verifies and, only when it does, when the
+// run started, the document (the name on its top-level receipt, the last one, and the art_ it admitted), its exit code
+// and its metered cost (null when no engine reported one). A ledger that does not verify says only why.
+const str = (x) => (typeof x === 'string' ? x : null);
+const obj = (x) => (x !== null && typeof x === 'object' ? x : {});
+function summary(core, lines) {
+    const v = core.ledger.verify(lines, {});
+    if (!v.ok) return { ledger_ok: false, reason: v.reason, started: null, document: null, artifact: null, code: null, cost_usd: null };
+    const entries = lines.map((l) => JSON.parse(l));
+    const m = core.ledger.meter(lines);
+    const receipts = entries.filter((e) => e.kind === 'receipt');
+    const top = receipts.length ? obj(receipts[receipts.length - 1].body) : {};
+    return {
+        ledger_ok: true, reason: null, started: str(entries[0].ts), document: str(top.step),
+        artifact: str(obj(entries[entries.length - 1].body).artifact), code: typeof m.code === 'number' ? m.code : null, cost_usd: m.cost_usd,
+    };
+}
+
+// The text after a failed lookup, for the printer of a command.
+function explainMissing(err, cmd, ref, josHome) {
+    err.fail('jos ' + cmd + ': no ledger for ' + ref);
+    err.hint('searched .jos/replays/ of the folders above ' + process.cwd() + ' and ' + path.join(josHome, 'runs'));
+    err.hint('list the runs with: jos runs');
+}
+
+module.exports = { RUN_ID, locate, read, summary, explainMissing };

package/src/mcp-guide.js

@@ -0,0 +1,138 @@
+/**
+ * What a person reads about `jos serve --mcp`: the help screen (`jos serve --help`, stdout) and the notice the server
+ * prints on stderr when its stdin is a terminal (a person, not an MCP client). Both name the tools with one line each,
+ * what a client cannot do, and how to connect this very bin/jos, with its absolute path resolved at run time.
+ * Nothing here writes to the JSON-RPC channel; every line goes through a printer of ui.js (STYLE.md).
+ */
+'use strict';
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const ui = require('./ui');
+
+const BIN = path.resolve(__dirname, '..', 'bin', 'jos');
+const SECURITY = path.resolve(__dirname, '..', 'SECURITY-MCP.md');
+
+// One line per tool of src/mcp.js (test/mcp.test.js checks that every tool has one and that no extra one is listed).
+const USES = {
+    list_files: 'list the files and folders of a directory under the root (recursive to depth 3)',
+    read_file: 'read a regular file under the root (at most 10 MB)',
+    search_files: 'find files under the root by a glob on the name (* and ?; 100 matches, depth 5)',
+    read_markdown: 'read a Markdown file under the root, with its line count',
+    list_modules: 'list the modules in ~/.jos/modules and whether ~/.jos/modules.json enables them',
+    list_processes: 'list the runs recorded in ~/.jos/runs/*/report.json',
+    hot_reload: 'read ~/.jos/modules.json again and report the enabled and disabled modules',
+    write_file: 'create or overwrite a file under the root, never under ~/.jos',
+    run_command: 'run a program with an argv (no shell) in a folder under the root; each one shown on stderr',
+};
+const FLAG = { write_file: '--allow-write', run_command: '--allow-shell' };
+
+// What --allow-shell grants, said the same way in the help screen, the notice and SECURITY-MCP.md (review OAI-RC6-05).
+const SHELL_RISK = '--allow-shell grants local code execution with your user privileges: a program it runs can read ' +
+    'your secrets (~/.jos/secrets, ~/.ssh, cloud keys) outside the MCP tools and their denials. Do not give it to an ' +
+    'untrusted agent without an external sandbox (a container or a virtual machine).';
+
+const CANNOT = [
+    'reach a file outside the root (real paths, symlinks resolved, device and inode compared)',
+    'read, list, search or write ~/.jos/secrets, nor any .master or vault.json under ~/.jos',
+    'write a file without --allow-write, nor under ~/.jos with it',
+    'run a program without --allow-shell (with it the program runs as you and could read ~/.jos/secrets)',
+];
+
+// The absolute path of a `jos` on PATH that is this bin/jos (an npm install), or null.
+function onPath(env) {
+    const self = fs.realpathSync(BIN);
+    for (const dir of String(env.PATH || '').split(path.delimiter)) {
+        if (!path.isAbsolute(dir)) continue;
+        const p = path.join(dir, 'jos');
+        try { if (fs.realpathSync(p) === self) return p; } catch (e) { /* not there */ }
+    }
+    return null;
+}
+
+// How to connect this server, read-only, with `root` as its root: Claude Code, then Claude Desktop / Cursor.
+function connect(p, root, env) {
+    const { C } = p;
+    const args = [BIN, 'serve', '--mcp', '--root', root];
+    p.line(`${C.bold}Connect it${C.reset} ${C.gray}(read-only, root ${root})${C.reset}`);
+    const home = os.homedir();
+    if (home === root || home.startsWith(root.endsWith(path.sep) ? root : root + path.sep)) {
+        p.warn('This root is your home directory or contains it: put a project folder after --root before you copy these.');
+    }
+    p.line(`  ${C.white}Claude Code:${C.reset}`);
+    p.cmd('claude mcp add jos -- node ' + args.map(ui.shellArg).join(' '));
+    const installed = onPath(env);
+    if (installed) p.cmd('claude mcp add jos -- jos ' + args.slice(1).map(ui.shellArg).join(' ') + `${C.reset}   ${C.gray}(jos on PATH: ${installed})`);
+    p.cmd('claude mcp remove jos' + `${C.reset}   ${C.gray}(to remove it)`);
+    p.line(`  ${C.white}Claude Desktop${C.reset} ${C.gray}(claude_desktop_config.json)${C.reset} ${C.white}or Cursor${C.reset} ${C.gray}(.cursor/mcp.json):${C.reset}`);
+    const block = JSON.stringify({ mcpServers: { jos: { command: 'node', args } } }, null, 2);
+    for (const l of block.split('\n')) p.line('    ' + l);
+    p.hint('If the client cannot find node, put its absolute path in "command": ' + process.execPath);
+    p.hint('Add --allow-write or --allow-shell to the arguments only if the client needs them (SECURITY-MCP.md).');
+}
+
+function tools(p, names, marked) {
+    const w = Math.max(...names.map((n) => n.length));
+    for (const n of names) {
+        p.item(`${p.C.cyan}${n.padEnd(w)}${p.C.reset}  ${USES[n]}` + (marked && FLAG[n] ? ` ${p.C.yellow}(only with ${FLAG[n]})${p.C.reset}` : ''));
+    }
+}
+
+// `jos serve --help`. names: every tool of src/mcp.js, the gated ones included; root: the root it would serve.
+function help(stream, names, root, env) {
+    const p = ui.printer(stream);
+    const { C } = p;
+    p.header('JOS SERVE', 'MCP server over stdio (Model Context Protocol)');
+    p.text(`${C.bold}Usage:${C.reset}
+  jos serve --mcp [--root <dir>] [--allow-write] [--allow-shell]
+
+${C.bold}Options:${C.reset}
+  --mcp           Start as MCP server (stdio JSON-RPC mode); read-only by default
+  --root <dir>    The one directory the client may reach (default: the working
+                  directory). Without it the server refuses to start in "/", in
+                  your home directory or in any directory that contains it.
+  --allow-write   Also offer write_file (inside the root, never under ~/.jos)
+  --allow-shell   Also offer run_command: the client runs any program as you, with
+                  an argv and no shell (announced on stderr; variables named like a
+                  secret of the vault are dropped from its environment). This is
+                  local code execution with your privileges: never for an
+                  untrusted agent without an external sandbox
+  --help, -h      Show this help
+
+`);
+    p.line(`${C.bold}Tools an MCP client gets:${C.reset}`);
+    tools(p, names, true);
+    p.line();
+    p.line(`${C.bold}What an MCP client cannot do:${C.reset}`);
+    for (const c of CANNOT) p.item(c);
+    p.warn(SHELL_RISK);
+    p.hint('The module tools read ~/.jos/modules.json, ~/.jos/modules and ~/.jos/runs only.');
+    p.hint('Details: ' + SECURITY);
+    p.line();
+    connect(p, root, env);
+    p.line();
+    p.hint('The HTTP file explorer is disabled until F3.');
+    p.line();
+}
+
+// The notice on stderr when stdin is a terminal. p: a printer on stderr; names: the tools this server offers.
+function notice(p, context, names) {
+    const { C } = p;
+    p.header('JOS SERVE', 'MCP server on stdio, waiting for a client');
+    p.warn('This is an MCP server: it reads JSON-RPC 2.0 on stdin and answers on stdout.');
+    p.hint('An MCP client starts this command and talks to it; typing here is not needed.');
+    p.line();
+    p.field('Root', context.root);
+    const on = [context.allowWrite && 'write_file (--allow-write)', context.allowShell && 'run_command (--allow-shell)'].filter(Boolean);
+    p.field('Mode', on.length ? `read-only plus ${C.yellow}${on.join(', ')}${C.reset}` : 'read-only');
+    p.field('Denied', '~/.jos/secrets, and any .master or vault.json under ~/.jos');
+    if (context.allowShell) p.warn(SHELL_RISK);
+    p.line();
+    p.line(`${C.bold}Tools:${C.reset}`);
+    tools(p, names, false);
+    p.line();
+    connect(p, context.root, context.env);
+    p.line();
+}
+
+module.exports = { help, notice, USES, BIN, onPath, SHELL_RISK };