aontu 0.64.0 → 0.65.0

package/dist/cli.js

@@ -15,7 +15,11 @@ exports.runView = runView;
 exports.runJsonSchema = runJsonSchema;
 exports.runTemplate = runTemplate;
 exports.runTrace = runTrace;
-exports.runMod = runMod;
+exports.runPkg = runPkg;
+exports.runModel = runModel;
+exports.runPackageVerb = runPackageVerb;
+exports.pkgToolOptions = pkgToolOptions;
+exports.serveUntilInterrupted = serveUntilInterrupted;
 exports.runHash = runHash;
 exports.runGet = runGet;
 exports.runHelp = runHelp;
@@ -46,7 +50,8 @@ const report_sarif_1 = require("./report-sarif");
 const lsp_server_1 = require("./lsp-server");
 const mcp_server_1 = require("./mcp-server");
 const jsonschema_1 = require("./jsonschema");
-const mod_tool_1 = require("./mod-tool");
+const pkg_1 = require("./pkg");
+const pkg_net_1 = require("./pkg-net");
 const mod_1 = require("./mod");
 const vet_1 = require("./vet");
 const reach_1 = require("./reach");
@@ -72,10 +77,18 @@ const HELP = `Usage: aontu [options] [file]
        aontu trace [--at <path>] [--format json] [--marker <token>]
                    [--profile <file>] <file>
        aontu hash [options] <file>
-       aontu mod tidy|verify|vendor|manifest [options] [dir]
-       aontu get <path> [options] <file>
-       aontu why <path> [options] <file>
-       aontu set <path>=<value>... --entry <file> --overlay <file>
+       aontu sync [--frozen] [options] [dir]
+       aontu add <pkg>[@<version>] [options] [dir]
+       aontu get <pkg>[@<version>] [options] [dir]
+       aontu remove <pkg> [options] [dir]
+       aontu why <pkg> [options] [dir]
+       aontu publish [--yes] [--to <dir>] [options] [dir]
+       aontu pkg tidy|verify|vendor|manifest|refreeze|tree|outdated|serve
+                 [options] [dir]
+       aontu pkg keygen <file>
+       aontu model get <path> [options] <file>
+       aontu model why <path> [options] <file>
+       aontu model set <path>=<value>... --entry <file> --overlay <file>
        aontu allow --role <role> [--at <path>] <roles-file> <path>...
        aontu agentsmd [--write <AGENTS.md>] [--depth <n>] <file>
        aontu fmt [-w|-l|--check|-d|--lint] [--marker <token>]
@@ -144,18 +157,57 @@ Options:
                   named format keeps its meaning, and .js stays
                   refused. Every verb takes it
 
-Mod options:
+Package verbs (a module is imported; a package is published):
+  sync      Make the project correct: resolve by minimum version
+            selection, fetch what is missing, write aontu_meta/pkg-lock.aon,
+            vendor, verify. --frozen refuses to change the lockfile
+  add       Take on a dependency the project does not have, then sync;
+            refuses one it has and names get
+  get       Add a dependency or raise its minimum, then sync. Without a
+            version, the newest version outside the cooldown
+  remove    Drop a dependency, then sync
+  why       Why is this package in the closure: every path of
+            requirements that reaches it
+  publish   Publish this package. A dry run without --yes; --to <dir>
+            writes the repository layout into a directory instead
+
+Package options:
   --format <f>    text (default) or json
-  --against <dir> manifest: a prior version's module tree, to gate on
+  --frozen        sync: fail if the lockfile would change (the CI mode)
+  --yes           publish: send it (the default is a dry run)
+  --to <dir>      publish: write the read-path layout into a directory
+  --key <file>    publish: the Ed25519 private key (PKCS#8 PEM) that
+                  signs the manifest, for the key provider
+  --token <file>  publish: the forge's OIDC token, read from a file
+  --base <url>    the repository to read from (repeatable; overrides
+                  pkg.aon repo.base)
+  --write <url>   publish: the write path (overrides pkg.aon repo.write)
+  --against <dir> manifest: a prior version's tree, to gate on
+  --upstream <u>  serve: fetch on miss from this repository (repeatable)
+  --listen <a>    serve: the address to listen on (default 127.0.0.1:8017)
 
-Mod subcommands:
-  tidy      Resolve the module closure by minimum version selection and
-            rewrite aontu_meta/mod-lock.aon in canonical form
-  verify    Check every locked module still means what the lockfile
-            pins, and change nothing (the CI gate; tidy rewrites)
+pkg subcommands (the rest of the package operations):
+  tidy      Resolve the closure by minimum version selection and
+            rewrite aontu_meta/pkg-lock.aon in canonical form
+  verify    Check every locked package still is and still means what
+            the lockfile pins, bytes before meaning, and change nothing
+            (the CI gate; tidy rewrites)
   vendor    Materialise the locked closure into aontu_meta/vendor/
-  manifest  Print the OCI artifact a publish would push, gated on the
-            breaking check against --against
+  manifest  Print the manifest a publish would send, gated on the
+            compatibility check against --against
+  refreeze  Recompute every canon pin and nothing else, after a
+            canonical-form change in the engine
+  tree      The locked closure as a graph
+  outdated  What could move, and what would move with it
+  serve     Serve a repository directory; with --upstream, a caching
+            proxy in front of another repository
+  keygen    Write a new Ed25519 signing key (PKCS#8 PEM) to a file,
+            once, and print the signer id a consumer names
+
+model subcommands (one document, interrogated or edited):
+  get       What the document says at a path
+  why       Every contribution to the value at a path
+  set       Append a path-flattened conjunct to an overlay
 
 Vet options:
   --at <path>       Validate against this path of the schema ($.a.b)
@@ -234,21 +286,21 @@ Hash options:
 Hash exit codes: 0 hashed, 2 usage, 4 the document does not stand up
 on its own.
 
-Get options:
+Model get options:
   -c, --canon     Canonical-form fragment (default: generated JSON)
   --keys          Keys at the node, one per line
   --types         Shape view: concrete leaves lifted to their kinds
   --depth <n>     Structure to depth n; deeper nodes render as top
   --format <f>    text (default) or json
 
-Get exit codes: 0 rendered, 1 the path names nothing, 2 usage, 4 the
-document does not stand up on its own.
+Model get exit codes: 0 rendered, 1 the path names nothing, 2 usage, 4
+the document does not stand up on its own.
 
-Why options:
+Model why options:
   --format <f>    text (default) or json
 
-Why exit codes mirror get's: 0 explained, 1 the path names nothing,
-2 usage, 4 the document does not stand up on its own.
+Model why exit codes mirror get's: 0 explained, 1 the path names
+nothing, 2 usage, 4 the document does not stand up on its own.
 
 View kinds: doc, lattice, tree, matrix, graph, layer, sets, layers,
 ladder, poset (the poset takes several files). The figure goes to stdout, the loss
@@ -338,7 +390,7 @@ every other line is a line of output.
 
 Template exit codes: 0 written, 1 --check drift, 2 usage or I/O.
 
-Set options:
+Model set options:
   --entry <file>    The document the change is checked against
   --overlay <file>  The file the change is appended to (created if
                     absent; not written when the change does not hold)
@@ -354,7 +406,7 @@ Set options:
   --format <f>      text (default) or json
 
 Set exit codes are vet's verdict classes: 0 valid, 1 invalid (the
-change contradicts a pinned value -- aontu why locates it, and
+change contradicts a pinned value -- aontu model why locates it, and
 --in-place rewrites it), 2 usage, 3 incomplete, 4 the entry does not
 stand up on its own.
 
@@ -556,7 +608,7 @@ function trustOpts(trust, entryRoot) {
             return { ...text, trustWarn: makeTrustWarn(), trustWarnRoot: entryRoot };
     }
 }
-function takeTrust(argv) {
+function takeTrust(argv, io = PROCESS_IO) {
     const rest = [];
     let trust = { kind: 'system-warn', textExt: [] };
     let textExt = [];
@@ -565,7 +617,7 @@ function takeTrust(argv) {
         if ('--trust' === arg) {
             const parsed = null == argv[i + 1] ? undefined : parseTrustArg(argv[++i]);
             if (null == parsed) {
-                process.stderr.write('aontu: --trust needs system, none, or root[:dir]\n');
+                io.err('aontu: --trust needs system, none, or root[:dir]\n');
                 return undefined;
             }
             trust = parsed;
@@ -573,7 +625,7 @@ function takeTrust(argv) {
         else if ('--include-root' === arg) {
             const dir = argv[++i];
             if (null == dir) {
-                process.stderr.write('aontu: --include-root needs a directory\n');
+                io.err('aontu: --include-root needs a directory\n');
                 return undefined;
             }
             trust = { kind: 'root', dir, textExt };
@@ -581,7 +633,7 @@ function takeTrust(argv) {
         else if ('--text-ext' === arg) {
             const list = null == argv[i + 1] ? undefined : parseTextExt(argv[++i]);
             if (null == list) {
-                process.stderr.write('aontu: --text-ext needs extensions, without dots' +
+                io.err('aontu: --text-ext needs extensions, without dots' +
                     ' (--text-ext md,sql)\n');
                 return undefined;
             }
@@ -594,7 +646,7 @@ function takeTrust(argv) {
     return { argv: rest, trust: { ...trust, textExt } };
 }
 // `md,sql` or `.md,.sql` -- the dot is accepted and dropped, because a
-// reader who has just written `@"notes.txt"` reaches for one. An empty
+// reader who has just written `@"./notes.txt"` reaches for one. An empty
 // element, or anything that is not an extension, is a usage error
 // rather than a silently ignored word: a flag that quietly does
 // nothing is how a document ends up refused with no reason visible.
@@ -1735,81 +1787,134 @@ const VIEW_USAGE_CODES = [
     'view_at_required', 'view_sets_required', 'view_group_required',
     'view_document_shape', 'view_style_profile', 'view_style_unknown',
 ];
-const MOD_HELP = 'aontu mod tidy|verify|vendor|manifest [dir] (try --help)';
-function runMod(argv) {
-    const trusted = takeTrust(argv);
-    if (null == trusted) {
-        return 2;
-    }
-    argv = trusted.argv;
-    const trust = trusted.trust;
-    const rest = [];
-    let format = 'text';
-    let against;
+const PKG_HELP = 'aontu pkg tidy|verify|vendor|manifest|refreeze|tree|outdated|serve [dir] | keygen <file> (try --help)';
+const PKG_SUBS = [
+    'tidy', 'verify', 'vendor', 'manifest', 'refreeze', 'tree', 'outdated',
+    'serve', 'keygen',
+];
+function parsePkgArgs(argv, verb, io) {
+    const out = {
+        rest: [], format: 'text', frozen: false, yes: false, base: [], upstream: [],
+    };
+    const value = (name, i) => {
+        const v = argv[i];
+        if (null == v) {
+            io.err(`aontu: ${name} needs a value\n`);
+        }
+        return v;
+    };
     for (let i = 0; i < argv.length; i++) {
         const arg = argv[i];
         if ('-h' === arg || '--help' === arg) {
-            process.stdout.write(HELP);
-            return 0;
+            io.out(HELP);
+            return undefined;
         }
         if ('--format' === arg) {
             const f = argv[++i];
             if ('text' !== f && 'json' !== f) {
-                process.stderr.write('aontu: --format needs text or json\n');
-                return 2;
+                io.err('aontu: --format needs text or json\n');
+                return undefined;
             }
-            format = f;
+            out.format = f;
         }
-        else if ('--against' === arg) {
-            const a = argv[++i];
-            if (null == a) {
-                process.stderr.write('aontu: --against needs a module directory\n');
-                return 2;
+        else if ('--frozen' === arg) {
+            out.frozen = true;
+        }
+        else if ('--yes' === arg) {
+            out.yes = true;
+        }
+        else if ('--against' === arg || '--to' === arg || '--key' === arg ||
+            '--token' === arg || '--write' === arg || '--listen' === arg) {
+            const v = value(arg, ++i);
+            if (null == v) {
+                return undefined;
             }
-            against = a;
+            out['--against' === arg ? 'against' : '--to' === arg ? 'to' :
+                '--key' === arg ? 'key' : '--token' === arg ? 'token' :
+                    '--write' === arg ? 'write' : 'listen'] = v;
+        }
+        else if ('--base' === arg || '--upstream' === arg) {
+            const v = value(arg, ++i);
+            if (null == v) {
+                return undefined;
+            }
+            out['--base' === arg ? 'base' : 'upstream'].push(v);
         }
         else if (arg.startsWith('-')) {
-            process.stderr.write(`aontu: unknown mod option ${arg} (try --help)\n`);
-            return 2;
+            io.err(`aontu: unknown ${verb} option ${arg} (try --help)\n`);
+            return undefined;
         }
         else {
-            rest.push(arg);
+            out.rest.push(arg);
         }
     }
-    const sub = rest[0];
-    const dir = rest[1] ?? '.';
-    if ('get' === sub || 'publish' === sub) {
-        process.stderr.write('aontu: mod ' + sub + ' needs a registry client, which this build ' +
-            'does not ship; vendor the module by hand and run ' +
-            "'aontu mod tidy'\n");
+    return out;
+}
+// A verb that finds the older layout names the current one, once, and
+// reads nothing from it.
+function nameOldLayout(dir, io) {
+    const old = ['aon_vendor', 'mod-lock.aon', 'mod.aon',
+        (0, node_path_1.join)(mod_1.META_DIR, 'mod-lock.aon')].filter((f) => (0, node_fs_1.existsSync)((0, node_path_1.join)(dir, f)));
+    if (0 < old.length) {
+        io.err('aontu: ' + old.join(', ') + ' belong to an older layout: the package ' +
+            'file is ' + mod_1.PKG_FILE + ', the lockfile ' + (0, node_path_1.join)(mod_1.META_DIR, mod_1.LOCK_FILE) +
+            ' and the vendor tree ' + (0, node_path_1.join)(mod_1.META_DIR, 'vendor') + '; rename ' +
+            mod_1.PKG_FILE + '\'s `mod` block to `pkg`, then run aontu sync\n');
+    }
+}
+function runPkg(argv, servers) {
+    const io = servers.io ?? PROCESS_IO;
+    const trusted = takeTrust(argv, io);
+    if (null == trusted) {
         return 2;
     }
-    if (!MOD_SUBS.includes(sub) || 2 < rest.length) {
-        process.stderr.write(`aontu: mod needs tidy, verify, vendor or manifest\n${MOD_HELP}\n`);
+    const args = parsePkgArgs(trusted.argv, 'pkg', io);
+    if (null == args) {
+        return '-h' === trusted.argv[0] || trusted.argv.includes('--help') ? 0 : 2;
+    }
+    const trust = trusted.trust;
+    const sub = args.rest[0];
+    const dir = args.rest[1] ?? '.';
+    if (!PKG_SUBS.includes(sub) || 2 < args.rest.length) {
+        io.err(`aontu: pkg needs one of ${PKG_SUBS.join(', ')}\n${PKG_HELP}\n`);
         return 2;
     }
-    if ((0, node_fs_1.existsSync)((0, node_path_1.join)(dir, 'aon_vendor')) || (0, node_fs_1.existsSync)((0, node_path_1.join)(dir, 'mod-lock.aon'))) {
-        process.stderr.write('aontu: aon_vendor/ and mod-lock.aon now live under aontu_meta/: ' +
-            'move them, or run aontu mod tidy and aontu mod vendor\n');
+    if ('keygen' === sub) {
+        if (2 !== args.rest.length) {
+            io.err('aontu: pkg keygen needs the file to write\naontu pkg keygen <file>\n');
+            return 2;
+        }
+        const made = (0, pkg_net_1.keygen)(args.rest[1]);
+        if (null != made.refused) {
+            io.err('aontu: ' + made.refused + '\n');
+            return 2;
+        }
+        io.out('signer: ' + made.signer + '\n');
+        return 0;
     }
-    // `--against` gates a manifest and means nothing to the other two;
+    nameOldLayout(dir, io);
+    // `--against` gates a manifest and means nothing to the others;
     // accepting it there would say it had been honoured.
-    if (null != against && 'manifest' !== sub) {
-        process.stderr.write('aontu: --against is a manifest option\n');
-        return 2;
-    }
-    const modopts = modToolOptions(trust, (0, node_path_1.resolve)(dir));
-    const report = 'tidy' === sub ? (0, mod_tool_1.modTidy)(dir, modopts) :
-        'verify' === sub ? (0, mod_tool_1.modVerify)(dir, modopts) :
-            'vendor' === sub ? (0, mod_tool_1.modVendor)(dir, modopts) :
-                (0, mod_tool_1.modManifest)(dir, modopts, against);
-    process.stdout.write(('json' === format ?
-        (0, aontu_1.exactJSON)({ aontu: { version: version(), verb: 'mod ' + sub }, ...report }, 2) :
-        modText(sub, report)) + '\n');
-    return MOD_EXIT[report.verdict];
-}
-const MOD_SUBS = ['tidy', 'verify', 'vendor', 'manifest'];
-const MOD_EXIT = {
+    if (null != args.against && 'manifest' !== sub) {
+        io.err('aontu: --against is a manifest option\n');
+        return 2;
+    }
+    const opts = pkgToolOptions(trust, (0, node_path_1.resolve)(dir));
+    if ('outdated' === sub || 'serve' === sub) {
+        return runPkgNet(sub, dir, args, opts, servers, io);
+    }
+    const report = 'tidy' === sub ? (0, pkg_1.pkgTidy)(dir, opts) :
+        'verify' === sub ? (0, pkg_1.pkgVerify)(dir, opts) :
+            'vendor' === sub ? (0, pkg_1.pkgVendor)(dir, opts) :
+                'refreeze' === sub ? (0, pkg_1.pkgRefreeze)(dir, opts) :
+                    'tree' === sub ? (0, pkg_1.pkgTree)(dir, opts) :
+                        (0, pkg_1.pkgManifest)(dir, opts, args.against);
+    io.out(('json' === args.format ?
+        (0, aontu_1.exactJSON)({ aontu: { version: version(), verb: 'pkg ' + sub }, ...report }, 2) :
+        pkgText(sub, report)) + '\n');
+    return PKG_EXIT[report.verdict];
+}
+const PKG_EXIT = {
     ok: 0,
     missing: 1,
     mismatch: 1,
@@ -1817,13 +1922,19 @@ const MOD_EXIT = {
     // nothing to check, which is a refusal and not a pass.
     unlocked: 1,
     breaking: 1,
+    frozen: 1,
+    refused: 1,
+    outdated: 1,
+    sent: 0,
+    'dry-run': 0,
+    current: 0,
     undecided: 3,
     error: 4,
 };
 // The tooling's evaluator: the same standalone evaluation the module
 // resolver verifies with (ts/src/mod.ts), and for the same reason —
 // only the engine can say what a module MEANS.
-function modToolOptions(trust, entryRoot) {
+function pkgToolOptions(trust, entryRoot) {
     const opts = verbOpts(trust, entryRoot);
     // The user cache lives outside any confinement root, so a confined
     // run reads the vendor tree only -- as the evaluator's own module
@@ -1840,24 +1951,54 @@ function modToolOptions(trust, entryRoot) {
                 hash: (0, aontu_1.canonHash)(val),
                 canon: val.canon,
                 // The same question `aontu hash` asks before it will answer:
-                // did this document stand up ON ITS OWN? See ModToolEval.
+                // did this document stand up ON ITS OWN? See PkgToolEval.
                 ok: 0 === ctx.err.length && true !== val.isNil,
             };
         },
     };
 }
-function modText(sub, report) {
+function pkgLockLines(entries) {
+    return entries.map((e) => e.key + ' ' + e.v + ' ' + e.canon);
+}
+// The renderers verify, tidy and sync share, as the Go port's do.
+function pkgMismatchLines(mismatched) {
+    return mismatched.map((m) => 'canon' === m.pin ?
+        m.key + ': pinned ' + m.want + ' but the store means ' +
+            ('' === m.got ? 'nothing (it does not evaluate)' : m.got) :
+        m.key + ': pinned ' + m.pin + ' ' + m.want + ' but the store holds ' + m.got);
+}
+// NOT a fetch: the package may well be sitting in the store. What is
+// absent is the PIN, and only a sync writes one.
+function pkgUnlockedLines(unlocked) {
+    return unlocked.map((key) => key + ': not in the lockfile (run: aontu sync)');
+}
+function pkgForbiddenLines(forbidden) {
+    return forbidden.map((f) => f + ': not admitted in a package');
+}
+function pkgText(sub, report) {
     const lines = ['verdict: ' + report.verdict];
     if ('manifest' === sub) {
-        if ('' !== report.mod) {
-            lines.push(report.mod + ' ' + report.version);
-            lines.push('config: ' + report.config);
-        }
-        for (const key of Object.keys(report.annotations).sort()) {
-            lines.push(key + ': ' + report.annotations[key]);
-        }
-        for (const file of report.files) {
-            lines.push('layer: ' + file);
+        const m = report.manifest;
+        if (null != m) {
+            lines.push(m.package + ' ' + m.version + ' ' + m.publish);
+            lines.push('archive: ' + m.archive.digest + ' (' + m.archive.files.length +
+                ' files, ' + m.archive.size + ' bytes)');
+            for (const mod of m.modules) {
+                lines.push('module: ' + mod.path + ' ' + mod.main + ' ' + mod.canon);
+            }
+            for (const key of Object.keys(m.deps).sort(keyorder_1.cmpCodePoint)) {
+                lines.push('dep: ' + key + ' ' + m.deps[key].v +
+                    (null == m.deps[key].pkg ? '' : ' (' + m.deps[key].pkg + ')'));
+            }
+            for (const v of m.retract ?? []) {
+                lines.push('retract: ' + v);
+            }
+            if (null != m.moved) {
+                lines.push('moved: ' + m.moved);
+            }
+            for (const f of m.archive.files) {
+                lines.push('file: ' + f.path + ' ' + f.digest + ' ' + f.size);
+            }
         }
         for (const f of report.findings) {
             lines.push(f.path + ': ' + f.message);
@@ -1865,44 +2006,281 @@ function modText(sub, report) {
         for (const miss of report.missing) {
             lines.push(miss + ': missing');
         }
+        lines.push(...pkgForbiddenLines(report.forbidden));
         return lines.join('\n');
     }
     if ('verify' === sub) {
-        for (const mod of report.verified) {
-            lines.push(mod + ': verified');
+        for (const key of report.verified) {
+            lines.push(key + ': verified');
+        }
+        lines.push(...pkgMismatchLines(report.mismatched), ...pkgUnlockedLines(report.unlocked));
+        for (const miss of report.missing) {
+            lines.push(miss + ': not fetched (run: aontu sync)');
         }
-        for (const m of report.mismatched) {
-            lines.push(m.mod + ': pinned ' + m.want + ' but the store means ' +
-                ('' === m.got ? 'nothing (it does not evaluate)' : m.got));
+        return lines.join('\n');
+    }
+    if ('refreeze' === sub) {
+        for (const r of report.repinned) {
+            lines.push(r.key + ': ' + r.from + ' -> ' + r.to);
         }
-        // NOT a fetch: the module may well be sitting in the store. What
-        // is absent is the PIN, and only a tidy writes one.
-        for (const mod of report.unlocked) {
-            lines.push(mod + ': not in the lockfile (run: aontu mod tidy)');
+        for (const key of report.unchanged) {
+            lines.push(key + ': unchanged');
+        }
+        for (const bad of report.unevaluable) {
+            lines.push(bad + ': does not evaluate on its own; nothing to pin');
         }
         for (const miss of report.missing) {
-            lines.push(miss + ': not fetched (run: aontu mod get)');
+            lines.push(miss + ': not fetched (run: aontu sync)');
         }
         return lines.join('\n');
     }
-    const done = 'tidy' === sub ? report.lock : report.vendored;
-    for (const item of done) {
-        lines.push('tidy' === sub ?
-            item.mod + ' ' + item.v + ' ' + item.canon : '' + item);
+    if ('tree' === sub) {
+        const byKey = new Map(report.nodes.map((n) => [n.key, n]));
+        const seen = new Set();
+        const walk = (key, depth) => {
+            const node = byKey.get(key);
+            const again = seen.has(key);
+            seen.add(key);
+            lines.push('  '.repeat(depth) + key +
+                (null == node || '' === node.v ? '' : ' ' + node.v) +
+                (again ? ' (above)' : null == node ? ' (not locked)' : ''));
+            if (again || null == node) {
+                return;
+            }
+            for (const dep of node.deps) {
+                walk(dep, depth + 1);
+            }
+        };
+        walk(report.root, 0);
+        for (const miss of report.missing) {
+            lines.push(miss + ': not fetched (run: aontu sync)');
+        }
+        return lines.join('\n');
     }
-    // A module that is PRESENT but does not stand up. Named separately
+    const done = 'tidy' === sub ? pkgLockLines(report.lock) : report.vendored;
+    lines.push(...done);
+    // A package that is PRESENT but does not stand up. Named separately
     // from a missing one because the repair is different: a fetch cannot
-    // help, the module itself has to be fixed (or its own dependencies
+    // help, the package itself has to be fixed (or its own dependencies
     // vendored beside it). Before the missing tail, as the Go port's
     // shared renderer orders them.
     for (const bad of report.unevaluable ?? []) {
         lines.push(bad + ': does not evaluate on its own; nothing to pin');
     }
+    lines.push(...pkgForbiddenLines(report.forbidden ?? []));
     for (const miss of report.missing) {
-        lines.push(miss + ': not fetched (run: aontu mod get)');
+        lines.push(miss + ': not fetched (run: aontu sync)');
     }
     return lines.join('\n');
 }
+// The two `pkg` subcommands that reach a repository.
+async function runPkgNet(sub, dir, args, opts, servers, io) {
+    if ('serve' === sub) {
+        const served = await (0, pkg_net_1.startServe)({
+            dir: (0, node_path_1.resolve)(dir), upstream: args.upstream,
+            listen: args.listen ?? '127.0.0.1:8017', http: servers.http(),
+        });
+        io.out('serving ' + (0, node_path_1.resolve)(dir) + ' at ' + served.url + '\n' +
+            args.upstream.map((u) => 'upstream: ' + u + '\n').join(''));
+        await servers.serve(served);
+        await served.close();
+        return 0;
+    }
+    if (null == opts.cache) {
+        io.err(NO_CACHE);
+        return 2;
+    }
+    const report = await (0, pkg_net_1.pkgOutdated)(dir, opts, servers.http(), { base: netBase(args) });
+    io.out(pkgReportText('pkg outdated', args.format, report) + '\n');
+    return PKG_EXIT[report.verdict];
+}
+const NO_CACHE = 'aontu: this verb reads and writes the user cache, which a ' +
+    'confined run (--trust root) does not reach and this host does not name ' +
+    '(set XDG_CACHE_HOME or HOME)\n';
+function netBase(args) {
+    return 0 === args.base.length ? undefined : args.base;
+}
+const PACKAGE_VERBS = ['sync', 'add', 'get', 'remove', 'why', 'publish'];
+const PACKAGE_HELP = {
+    sync: 'aontu sync [--frozen] [dir] (try --help)',
+    add: 'aontu add <pkg> [dir] (try --help)',
+    get: 'aontu get <pkg>[@<version>] [dir] (try --help)',
+    remove: 'aontu remove <pkg> [dir] (try --help)',
+    why: 'aontu why <pkg> [dir] (try --help)',
+    publish: 'aontu publish [--yes] [--to <dir>] [--key <file>] [dir] (try --help)',
+};
+// The top-level package verbs (ADR-039 part 5). Every one but `why`
+// reaches a repository, so every one runs behind the seam.
+async function runPackageVerb(verb, argv, servers) {
+    const io = servers.io ?? PROCESS_IO;
+    const trusted = takeTrust(argv, io);
+    if (null == trusted) {
+        return 2;
+    }
+    const args = parsePkgArgs(trusted.argv, verb, io);
+    if (null == args) {
+        return '-h' === trusted.argv[0] || trusted.argv.includes('--help') ? 0 : 2;
+    }
+    const wantsPkg = 'sync' !== verb && 'publish' !== verb;
+    const dir = args.rest[wantsPkg ? 1 : 0] ?? '.';
+    if (args.rest.length > (wantsPkg ? 2 : 1) || (wantsPkg && 0 === args.rest.length)) {
+        io.err('aontu: ' + verb + (wantsPkg ? ' needs a package' : ' takes a directory') +
+            '\n' + PACKAGE_HELP[verb] + '\n');
+        return 2;
+    }
+    nameOldLayout(dir, io);
+    const opts = pkgToolOptions(trusted.trust, (0, node_path_1.resolve)(dir));
+    const http = servers.http();
+    if ('why' === verb) {
+        const report = (0, pkg_net_1.pkgWhy)(dir, opts, args.rest[0]);
+        io.out(pkgReportText('why', args.format, report) + '\n');
+        return PKG_EXIT[report.verdict];
+    }
+    if ('publish' === verb) {
+        for (const f of [args.key, args.token]) {
+            if (null != f && !(0, node_fs_1.existsSync)(f)) {
+                io.err('aontu: cannot read ' + f + '\n');
+                return 2;
+            }
+        }
+        if (true === args.yes && null == args.key) {
+            io.err('aontu: publish --yes needs --key <file>, the Ed25519 key that signs\n');
+            return 2;
+        }
+        const report = await (0, pkg_net_1.pkgPublish)(dir, opts, http, {
+            yes: args.yes, to: null == args.to ? undefined : (0, node_path_1.resolve)(args.to), key: args.key,
+            token: args.token, against: args.against, base: netBase(args), write: args.write,
+        });
+        io.out(pkgReportText('publish', args.format, report) + '\n');
+        return PKG_EXIT[report.verdict];
+    }
+    if (null == opts.cache) {
+        io.err(NO_CACHE);
+        return 2;
+    }
+    const net = { base: netBase(args) };
+    const report = 'sync' === verb ? await (0, pkg_net_1.pkgSync)(dir, opts, http, { ...net, frozen: args.frozen }) :
+        'remove' === verb ? await (0, pkg_net_1.pkgRemove)(dir, opts, http, args.rest[0], net) :
+            await (0, pkg_net_1.pkgGet)(dir, opts, http, args.rest[0], { ...net, mode: verb });
+    if ('string' === typeof report) {
+        io.err('aontu: ' + report + '\n');
+        return 2;
+    }
+    io.out(pkgReportText(verb, args.format, report) + '\n');
+    return PKG_EXIT[report.verdict];
+}
+function pkgReportText(verb, fmt, report) {
+    return 'json' === fmt ?
+        (0, aontu_1.exactJSON)({ aontu: { version: version(), verb }, ...report }, 2) :
+        pkgNetText(verb, report);
+}
+function pkgNetText(verb, report) {
+    const lines = ['verdict: ' + report.verdict];
+    const tail = () => {
+        for (const e of report.events ?? []) {
+            lines.push(e.code + ': ' + e.message);
+        }
+        if (null != report.refusal) {
+            lines.push('refused: ' + report.refusal.code + ': ' + report.refusal.message);
+        }
+    };
+    if ('why' === verb) {
+        const why = report;
+        for (const p of why.paths) {
+            lines.push(p.join(' -> '));
+        }
+        if ('missing' === why.verdict) {
+            lines.push(why.pkg + ': not in the closure');
+        }
+        return lines.join('\n');
+    }
+    if ('publish' === verb) {
+        const pub = report;
+        lines.push(...pkgText('manifest', pub).split('\n').slice(1));
+        if (null != pub.digest) {
+            lines.push('digest: ' + pub.digest);
+        }
+        if (null != pub.signer) {
+            lines.push('signer: ' + pub.signer);
+        }
+        if (null != pub.against) {
+            lines.push('against: ' + pub.against);
+        }
+        if (null != pub.to) {
+            lines.push('to: ' + pub.to);
+        }
+        if (null != pub.write) {
+            lines.push('write: ' + pub.write + pkg_net_1.PUBLISH_PATH);
+        }
+        if ('dry-run' === pub.verdict) {
+            lines.push('dry run: nothing sent (add --yes)');
+        }
+        if ('sent' === pub.verdict) {
+            lines.push('sent');
+        }
+        tail();
+        return lines.join('\n');
+    }
+    if ('pkg outdated' === verb) {
+        const out = report;
+        for (const e of out.locked) {
+            if (0 < (0, pkg_1.versionCompare)(e.newest, e.v)) {
+                lines.push(e.key + ' ' + e.v + ' -> ' + e.newest);
+                for (const m of e.moves) {
+                    lines.push('  ' + m);
+                }
+            }
+            else {
+                lines.push(e.key + ' ' + e.v + ': current');
+            }
+            if (null != e.retracted) {
+                lines.push(e.key + ' ' + e.v + ': retracted by ' + e.retracted);
+            }
+        }
+        tail();
+        return lines.join('\n');
+    }
+    const sync = report;
+    if (null != sync.change) {
+        lines.push('change: ' + sync.change);
+    }
+    for (const f of sync.fetched) {
+        lines.push('fetched: ' + f);
+    }
+    lines.push(...pkgLockLines(sync.lock));
+    for (const bad of sync.unevaluable) {
+        lines.push(bad + ': does not evaluate on its own; nothing to pin');
+    }
+    lines.push(...pkgForbiddenLines(sync.forbidden), ...pkgMismatchLines(sync.mismatched), ...pkgUnlockedLines(sync.unlocked));
+    for (const miss of sync.missing) {
+        lines.push(miss + ': not fetched (run: aontu sync)');
+    }
+    for (const c of sync.changes) {
+        lines.push('lockfile would change: ' + c);
+    }
+    tail();
+    return lines.join('\n');
+}
+const MODEL_HELP = 'aontu model get|why|set ... (try --help)';
+// One document, interrogated or edited (ADR-039 part 5).
+function runModel(argv) {
+    const sub = argv[0];
+    if ('-h' === sub || '--help' === sub) {
+        process.stdout.write(HELP);
+        return 0;
+    }
+    if ('get' === sub) {
+        return runGet(argv.slice(1));
+    }
+    if ('why' === sub) {
+        return runWhy(argv.slice(1));
+    }
+    if ('set' === sub) {
+        return runSet(argv.slice(1));
+    }
+    process.stderr.write(`aontu: model needs get, why or set\n${MODEL_HELP}\n`);
+    return 2;
+}
 function vacuous(what, why) {
     process.stderr.write(`aontu: ${what}: ${why}\n`);
 }
@@ -2807,7 +3185,7 @@ function runHash(argv) {
     process.stdout.write(text + '\n');
     return 0;
 }
-const GET_HELP = 'aontu get <path> <file> (try --help)';
+const GET_HELP = 'aontu model get <path> <file> (try --help)';
 function runGet(argv) {
     const trusted = takeTrust(argv);
     if (null == trusted) {
@@ -2851,7 +3229,7 @@ function runGet(argv) {
             format = f;
         }
         else if (arg.startsWith('-')) {
-            process.stderr.write(`aontu: unknown get option ${arg} (try --help)\n`);
+            process.stderr.write(`aontu: unknown model get option ${arg} (try --help)\n`);
             return 2;
         }
         else {
@@ -2859,7 +3237,7 @@ function runGet(argv) {
         }
     }
     if (2 !== rest.length) {
-        process.stderr.write(`aontu: get needs a path and one file\n${GET_HELP}\n`);
+        process.stderr.write(`aontu: model get needs a path and one file\n${GET_HELP}\n`);
         return 2;
     }
     const [path, file] = rest;
@@ -2883,7 +3261,7 @@ function runGet(argv) {
     });
     if ('json' === format) {
         process.stdout.write((0, aontu_1.exactJSON)({
-            aontu: { version: version(), verb: 'get' },
+            aontu: { version: version(), verb: 'model get' },
             findings: report.findings,
             ok: report.ok,
             out: report.out,
@@ -2908,7 +3286,7 @@ function runGet(argv) {
 // contributions that met there, each with the site it was written at.
 // The positive twin of the vet report: errors explain what failed to
 // unify, this explains what did.
-const WHY_HELP = 'aontu why <path> <file> (try --help)';
+const WHY_HELP = 'aontu model why <path> <file> (try --help)';
 function runWhy(argv) {
     const trusted = takeTrust(argv);
     if (null == trusted) {
@@ -2933,7 +3311,7 @@ function runWhy(argv) {
             format = f;
         }
         else if (arg.startsWith('-')) {
-            process.stderr.write(`aontu: unknown why option ${arg} (try --help)\n`);
+            process.stderr.write(`aontu: unknown model why option ${arg} (try --help)\n`);
             return 2;
         }
         else {
@@ -2941,7 +3319,7 @@ function runWhy(argv) {
         }
     }
     if (2 !== rest.length) {
-        process.stderr.write(`aontu: why needs a path and one file\n${WHY_HELP}\n`);
+        process.stderr.write(`aontu: model why needs a path and one file\n${WHY_HELP}\n`);
         return 2;
     }
     const [path, file] = rest;
@@ -2958,7 +3336,7 @@ function runWhy(argv) {
     });
     if ('json' === format) {
         process.stdout.write((0, aontu_1.exactJSON)({
-            aontu: { version: version(), verb: 'why' },
+            aontu: { version: version(), verb: 'model why' },
             findings: report.findings,
             ok: report.ok,
             ...(null == report.record ? {} : { record: report.record }),
@@ -2990,7 +3368,7 @@ function renderWhyText(record) {
             ('literal' === c.role ? '' : `  (${c.role})`);
     })).join('\n');
 }
-const SET_HELP = 'aontu set <path>=<value> --entry <file> --overlay <file> (try --help)';
+const SET_HELP = 'aontu model set <path>=<value> --entry <file> --overlay <file> (try --help)';
 function runSet(argv) {
     const trusted = takeTrust(argv);
     if (null == trusted) {
@@ -3031,7 +3409,7 @@ function runSet(argv) {
             format = f;
         }
         else if (arg.startsWith('-')) {
-            process.stderr.write(`aontu: unknown set option ${arg} (try --help)\n`);
+            process.stderr.write(`aontu: unknown model set option ${arg} (try --help)\n`);
             return 2;
         }
         else {
@@ -3039,7 +3417,7 @@ function runSet(argv) {
         }
     }
     if (0 === assignments.length || null == entry || null == overlayFile) {
-        process.stderr.write(`aontu: set needs assignments, --entry and --overlay\n${SET_HELP}\n`);
+        process.stderr.write(`aontu: model set needs assignments, --entry and --overlay\n${SET_HELP}\n`);
         return 2;
     }
     let entrySrc;
@@ -3086,7 +3464,7 @@ function runSet(argv) {
     }
     if ('json' === format) {
         process.stdout.write((0, aontu_1.exactJSON)({
-            aontu: { version: version(), verb: 'set' },
+            aontu: { version: version(), verb: 'model set' },
             appended: report.appended,
             findings: report.findings,
             overlay: report.overlay,
@@ -3523,12 +3901,22 @@ function fmtOne(name, src, flags, marker) {
     }
     return flags.check ? 1 : strict;
 }
+const PROCESS_IO = {
+    out: (s) => void process.stdout.write(s),
+    err: (s) => void process.stderr.write(s),
+};
+// `pkg serve` runs until the process is interrupted.
+function serveUntilInterrupted() {
+    return new Promise((done) => process.once('SIGINT', () => done()));
+}
 // Excluded: the real pair takes the process stdio, so ts/test/cli.test.ts
 // drives each server through a child process instead.
-/* node:coverage ignore next 4 */
+/* node:coverage ignore next 6 */
 const SERVERS = {
     lsp: () => void (0, lsp_server_1.main)(),
     mcp: (argv) => void (0, mcp_server_1.main)(undefined, undefined, undefined, undefined, argv),
+    serve: serveUntilInterrupted,
+    http: pkg_net_1.defaultHttp,
 };
 // undefined: the server took the process; a number: an answer the CLI
 // gives itself, --help or a usage error.
@@ -3801,10 +4189,10 @@ function runInit(argv) {
     return 0;
 }
 const KNOWN_VERBS = [
-    'agentsmd', 'allow', 'breaking', 'explain', 'fmt', 'get', 'hash',
-    'help', 'init', 'jsonschema', 'lsp', 'mcp', 'mod', 'reaches',
-    'relations', 'set', 'subsume', 'template', 'trace', 'trim',
-    'vet', 'view', 'why',
+    'add', 'agentsmd', 'allow', 'breaking', 'explain', 'fmt', 'get', 'hash',
+    'help', 'init', 'jsonschema', 'lsp', 'mcp', 'model', 'pkg', 'publish',
+    'reaches', 'relations', 'remove', 'subsume', 'sync', 'template', 'trace',
+    'trim', 'vet', 'view', 'why',
 ];
 exports.KNOWN_VERBS = KNOWN_VERBS;
 // looksLikeVerb reports whether an unreadable argument was meant as a
@@ -3889,17 +4277,18 @@ function main(argv, servers = SERVERS) {
     if ('mcp' === argv[2]) {
         return servers.mcp(argv.slice(3));
     }
-    if ('set' === argv[2]) {
-        return finish(runSet(argv.slice(3)));
-    }
     if ('allow' === argv[2]) {
         return finish(runAllow(argv.slice(3)));
     }
-    if ('why' === argv[2]) {
-        return finish(runWhy(argv.slice(3)));
+    if ('model' === argv[2]) {
+        return finish(runModel(argv.slice(3)));
     }
-    if ('get' === argv[2]) {
-        return finish(runGet(argv.slice(3)));
+    if ('pkg' === argv[2]) {
+        const r = runPkg(argv.slice(3), servers);
+        return 'number' === typeof r ? finish(r) : void r.then(finish);
+    }
+    if (PACKAGE_VERBS.includes(argv[2])) {
+        return void runPackageVerb(argv[2], argv.slice(3), servers).then(finish);
     }
     if ('hash' === argv[2]) {
         return finish(runHash(argv.slice(3)));
@@ -3915,9 +4304,6 @@ function main(argv, servers = SERVERS) {
     if ('init' === argv[2]) {
         return finish(runInit(argv.slice(3)));
     }
-    if ('mod' === argv[2]) {
-        return finish(runMod(argv.slice(3)));
-    }
     if ('relations' === argv[2]) {
         return finish(runRelations(argv.slice(3)));
     }