@intentius/chant 0.124.12 → 0.124.14

package/dist/workspace/reference-kinds/app/workspace-kinds.json

@@ -0,0 +1,45 @@
+{
+  "$comment": "The app member kind (#3151, ws-093). A workspace pins a copy of this directory by path, as the reference workspace does at kinds/app, and chant reads it as data. The fields are the conventions an orchestrator relies on to run, migrate, test and check an app: the scripts in its package.json, the environment variables it reads, and the path it answers health on. The canonical copy ships in @intentius/chant at src/workspace/reference-kinds/app.",
+  "schema": 1,
+  "kinds": [
+    {
+      "name": "app",
+      "description": "an app: a Node package with a start script in the package.json directly in its directory",
+      "precedence": 100,
+      "probe": {
+        "anyJsonKey": {
+          "in": ["package.json"],
+          "pointers": ["/scripts/start"]
+        }
+      },
+      "outputs": ["source", "url"],
+      "fields": {
+        "scripts": {
+          "type": "object",
+          "description": "Which package.json script plays each part, run with npm run from the member's directory",
+          "properties": {
+            "start": { "type": "string", "description": "Runs a release of the app; it listens on the port env.port names", "default": "start" },
+            "dev": { "type": "string", "description": "Runs the app in development", "default": "dev" },
+            "test": { "type": "string", "description": "The app's own tests, run before a release", "default": "test" },
+            "migrate": { "type": "string", "description": "Applies the app's migrations to the data directory env.data names; a missing script means there are none", "default": "migrate" }
+          }
+        },
+        "env": {
+          "type": "object",
+          "description": "The environment variables the app reads, by name",
+          "properties": {
+            "port": { "type": "string", "description": "The port the app listens on", "default": "PORT", "pattern": "^[A-Z_][A-Z0-9_]*$" },
+            "data": { "type": "string", "description": "The directory the app keeps its data in", "default": "APP_DATA", "pattern": "^[A-Z_][A-Z0-9_]*$" },
+            "revision": { "type": "string", "description": "The revision the running app reports, such as the release's commit", "default": "APP_REVISION", "pattern": "^[A-Z_][A-Z0-9_]*$" }
+          }
+        },
+        "health": {
+          "type": "string",
+          "description": "The path the running app answers on with a status below 500 once it is up",
+          "default": "/health",
+          "pattern": "^/"
+        }
+      }
+    }
+  ]
+}

package/dist/workspace/returns.js

@@ -0,0 +1,303 @@
+/**
+ * Returns: the record an import writes when a copy of the workspace comes
+ * back (#2552, #2524 D10, ws-004, ws-073).
+ *
+ * `chant workspace import` writes `.chant/returns/<id>.json` at the workspace
+ * root, beside the lock. It names the export the copy started from, the
+ * copy's HEAD when the copy is a git repository of its own, and every path
+ * the import wrote or removed. For each written path whose bytes are the
+ * copy's own (no host value was switched back into it), it also carries the
+ * origin: the raw commit object that last changed the file in the copy, and
+ * the raw tree objects from that commit's root tree down to the file. Those
+ * objects hash to the ids that name them, so anyone can check offline that
+ * the commit, with its original signature, holds exactly the bytes the
+ * workspace now has. Nothing is re-signed: the signature is the one the
+ * author made where the copy lived.
+ *
+ * The commit is judged by the attestors of #2547 with the policy at base. A
+ * signer the base policy does not list makes it `attested-unverifiable-here`,
+ * not `unattested`: there is a signature, and nothing here can say whose key
+ * it is. An admin admits the signers by adding them to `.chant/trust.json`
+ * under `admitted`, naming the return (`chant workspace admit <id>`). That
+ * file is policy, read at base, and changing it is a protected write, so the
+ * admission is signed by the admin's own commit. From then on, the returned
+ * commits read as `attested`. An admitted key verifies only that return's
+ * commits and seals, never a commit made in the workspace's own repository.
+ */
+import { execFileSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { z } from "zod";
+import { fileHash, LockError } from "./lineage-lock.js";
+import { attestRawCommit } from "./trust/attestor.js";
+import { returnedPolicy, TRUST_CONFIG_PATH } from "./trust/policy.js";
+import { splitSignedCommit, sshSignatureIntact, sshSignatureKey } from "./trust/ssh-commit.js";
+/** Where return records live, relative to the workspace root. */
+export const RETURNS_DIR = ".chant/returns";
+const Sha256 = z.string().regex(/^sha256:[0-9a-f]{64}$/);
+const CommitId = z.string().regex(/^[0-9a-f]{40}([0-9a-f]{24})?$/);
+const Base64 = z.string().regex(/^[A-Za-z0-9+/]*={0,2}$/);
+const OriginSchema = z
+    .object({
+    /** The commit in the returned copy that last changed the file. */
+    commit: CommitId,
+    /** That commit object, raw, in base64: the signed payload and its signature. */
+    raw: Base64,
+    /** The raw tree objects from the commit's root tree down to the file's directory, in base64. */
+    trees: z.array(Base64).min(1),
+})
+    .strict();
+const ReturnSchema = z
+    .object({
+    schema: z.literal(1),
+    id: z.string().regex(/^ret-[0-9a-f]{12}$/),
+    /** The export the copy started from (`.chant/export.json`). */
+    export: z.object({ id: z.string().min(1), workspace: z.string().min(1), revision: CommitId.nullable() }).strict(),
+    /** The copy's HEAD, when it was a git repository of its own. */
+    head: CommitId.nullable(),
+    /** Paths written, relative to the workspace root, with the bytes' hash and, when it can be proved, the commit they come from. */
+    paths: z.record(z.string(), z.object({ sha256: Sha256, origin: OriginSchema.optional() }).strict()),
+    /** Paths removed. */
+    removed: z.array(z.string()),
+    /** Paths whose host-bound values the import switched back: their bytes are not the copy's, so they carry no origin. */
+    hostValues: z.array(z.string()),
+    /** The keys that signed the origin commits, for an admin to admit. `principal` is the committer's email, a suggestion only. */
+    signers: z.array(z
+        .object({
+        key: z.string().min(1),
+        fingerprint: z.string(),
+        principal: z.string().min(1),
+        commits: z.array(CommitId),
+    })
+        .strict()),
+})
+    .strict();
+// ── Git objects ──────────────────────────────────────────────────────────────
+/** The id git gives an object: the hash of `<type> <length>\0<data>`, SHA-1 or SHA-256 by the id length in use. */
+export function gitObjectId(type, data, algorithm) {
+    return createHash(algorithm).update(`${type} ${data.length}\0`).update(data).digest("hex");
+}
+/** The entries of a raw tree object: mode, name and id. */
+export function parseTree(raw, idBytes) {
+    const out = [];
+    let i = 0;
+    while (i < raw.length) {
+        const sp = raw.indexOf(0x20, i);
+        const nul = raw.indexOf(0, sp);
+        if (sp < 0 || nul < 0 || nul + 1 + idBytes > raw.length)
+            throw new Error("malformed tree object");
+        out.push({ mode: raw.subarray(i, sp).toString("latin1"), name: raw.subarray(sp + 1, nul).toString("utf-8"), id: raw.subarray(nul + 1, nul + 1 + idBytes).toString("hex") });
+        i = nul + 1 + idBytes;
+    }
+    return out;
+}
+function gitBuf(cwd, args) {
+    return execFileSync("git", args, { cwd, maxBuffer: 256 * 1024 * 1024, stdio: ["ignore", "pipe", "pipe"] });
+}
+/**
+ * The origin of `path` (relative to the copy's root) in the copy's own
+ * repository at `dir`: the last commit that changed it, and the tree objects
+ * down to it. Undefined when the file at that commit is not `content`, such
+ * as a file with uncommitted changes.
+ */
+export function buildOrigin(dir, path, content) {
+    let commit;
+    try {
+        commit = gitBuf(dir, ["log", "-1", "--format=%H", "HEAD", "--", path]).toString("utf-8").trim();
+    }
+    catch {
+        return undefined;
+    }
+    if (!commit)
+        return undefined;
+    const raw = gitBuf(dir, ["cat-file", "commit", commit]);
+    const proof = { commit, raw: raw.toString("base64"), trees: [] };
+    let tree = /^tree ([0-9a-f]+)$/m.exec(raw.toString("latin1"))?.[1];
+    const parts = path.split("/");
+    for (let i = 0; i < parts.length && tree; i++) {
+        const t = gitBuf(dir, ["cat-file", "tree", tree]);
+        proof.trees.push(t.toString("base64"));
+        tree = parseTree(t, tree.length / 2).find((e) => e.name === parts[i])?.id;
+    }
+    return verifyOrigin(proof, path, content).ok ? proof : undefined;
+}
+/** Check that `origin`'s objects hash to their ids and lead from the commit to `content` at `path`. */
+export function verifyOrigin(origin, path, content) {
+    const algorithm = origin.commit.length === 64 ? "sha256" : "sha1";
+    const raw = Buffer.from(origin.raw, "base64");
+    if (gitObjectId("commit", raw, algorithm) !== origin.commit)
+        return { ok: false, reason: `the commit object does not hash to ${origin.commit.slice(0, 12)}` };
+    let id = /^tree ([0-9a-f]+)$/m.exec(raw.toString("latin1"))?.[1];
+    const parts = path.split("/");
+    if (origin.trees.length !== parts.length)
+        return { ok: false, reason: `the proof has ${origin.trees.length} tree(s) for a path ${parts.length} deep` };
+    for (let i = 0; i < parts.length; i++) {
+        const t = Buffer.from(origin.trees[i], "base64");
+        if (!id || gitObjectId("tree", t, algorithm) !== id)
+            return { ok: false, reason: `the tree for ${parts.slice(0, i).join("/") || "the root"} does not hash to its id` };
+        let entries;
+        try {
+            entries = parseTree(t, id.length / 2);
+        }
+        catch {
+            return { ok: false, reason: "a tree object in the proof is malformed" };
+        }
+        id = entries.find((e) => e.name === parts[i])?.id;
+    }
+    if (!id || gitObjectId("blob", content, algorithm) !== id)
+        return { ok: false, reason: `the commit holds other bytes at ${path}` };
+    return { ok: true };
+}
+// ── Signers ──────────────────────────────────────────────────────────────────
+/** The committer's email in a raw commit object. */
+function committerEmail(raw) {
+    return /^committer [^<]*<([^>]+)>/m.exec(raw.toString("utf-8"))?.[1];
+}
+function signatureHeader(origin) {
+    return origin.commit.length === 64 ? "gpgsig-sha256" : "gpgsig";
+}
+/** The keys that signed the origins, grouped by key, for an admin to admit. */
+export function originSigners(origins) {
+    const byKey = new Map();
+    const seen = new Set();
+    for (const o of origins) {
+        if (seen.has(o.commit))
+            continue;
+        seen.add(o.commit);
+        const raw = Buffer.from(o.raw, "base64");
+        const { payload, signature } = splitSignedCommit(raw, signatureHeader(o));
+        if (!signature)
+            continue;
+        const key = sshSignatureKey(signature);
+        if (!key)
+            continue;
+        const entry = byKey.get(key);
+        if (entry) {
+            entry.commits.push(o.commit);
+            continue;
+        }
+        const fingerprint = sshSignatureIntact(payload, signature, "git");
+        if (fingerprint === false)
+            continue;
+        byKey.set(key, { key, fingerprint: fingerprint ?? "", principal: committerEmail(raw) ?? "unknown", commits: [o.commit] });
+    }
+    return [...byKey.values()].sort((a, b) => a.key.localeCompare(b.key));
+}
+// ── Reading and writing ──────────────────────────────────────────────────────
+export function parseReturn(text, label) {
+    let raw;
+    try {
+        raw = JSON.parse(text);
+    }
+    catch (err) {
+        throw new LockError(`${label} is not JSON: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    const parsed = ReturnSchema.safeParse(raw);
+    if (!parsed.success)
+        throw new LockError(`${label} is not a return record: ${parsed.error.issues.map((i) => `${i.path.join(".") || "/"}: ${i.message}`).join("; ")}`);
+    return parsed.data;
+}
+export function renderReturn(r) {
+    const paths = {};
+    for (const p of Object.keys(r.paths).sort())
+        paths[p] = r.paths[p];
+    return JSON.stringify(ReturnSchema.parse({ ...r, paths, removed: [...r.removed].sort(), hostValues: [...r.hostValues].sort() }), null, 2) + "\n";
+}
+export function writeReturn(root, r) {
+    const rel = `${RETURNS_DIR}/${r.id}.json`;
+    mkdirSync(join(root, RETURNS_DIR), { recursive: true });
+    writeFileSync(join(root, rel), renderReturn(r));
+    return rel;
+}
+/** The return records in `tree` (the workspace root's), sorted by id. Unreadable ones are skipped and named in `problems`. */
+export function readReturns(tree) {
+    const returns = [];
+    const problems = [];
+    for (const e of (tree.list(RETURNS_DIR) ?? []).filter((x) => x.type === "file" && x.name.endsWith(".json")).sort((a, b) => a.name.localeCompare(b.name))) {
+        const path = `${RETURNS_DIR}/${e.name}`;
+        try {
+            const r = parseReturn(tree.read(path), path);
+            if (`${r.id}.json` !== e.name)
+                throw new LockError(`${path} holds return ${r.id}`);
+            returns.push(r);
+        }
+        catch (err) {
+            if (!(err instanceof LockError))
+                throw err;
+            problems.push(err.message);
+        }
+    }
+    return { returns, problems };
+}
+// ── Provenance ───────────────────────────────────────────────────────────────
+/**
+ * The provenance of a returned file: its origin commit judged by the
+ * attestors with the policy at base plus the signers admitted for the
+ * return. Undefined when the return holds no origin for the path, or the
+ * workspace's bytes are not the ones returned, so the commit that holds the
+ * file here is what counts.
+ */
+export function returnedProvenance(policy, attestors, ret, path, content, host) {
+    const entry = ret.paths[path];
+    if (!entry || entry.sha256 !== fileHash(content))
+        return undefined;
+    const returned = { id: ret.id, importedIn: host.commit };
+    if (!entry.origin)
+        return undefined;
+    const proof = verifyOrigin(entry.origin, path, content);
+    if (!proof.ok) {
+        return { level: "unattested", commit: host.commit, reason: `returned in ${ret.id}, and its origin does not check: ${proof.reason}`, returned: { ...returned, commit: entry.origin.commit } };
+    }
+    const raw = Buffer.from(entry.origin.raw, "base64");
+    const judged = returnedPolicy(policy, ret.id);
+    const a = attestRawCommit({ repo: "", policy: judged }, raw, attestors);
+    const at = `returned in ${ret.id} from commit ${entry.origin.commit.slice(0, 12)}`;
+    const base = { commit: host.commit, attestor: a.attestor, returned: { ...returned, commit: entry.origin.commit } };
+    if (a.level === "attested") {
+        const admitted = (policy.admitted[ret.id] ?? []).some((s) => s.principal === a.principal) && !policy.signers.some((s) => s.principal === a.principal);
+        return { ...base, level: "attested", ...(a.principal ? { principal: a.principal } : {}), ...(a.key ? { key: a.key } : {}), reason: `${at}, ${a.reason}${admitted ? `, a signer admitted for ${ret.id} at base` : ""}` };
+    }
+    if (a.level === "unattested") {
+        const { payload, signature } = splitSignedCommit(raw, signatureHeader(entry.origin));
+        const intact = signature?.startsWith("-----BEGIN SSH SIGNATURE-----") ? sshSignatureIntact(payload, signature, "git") : false;
+        if (intact) {
+            return {
+                ...base,
+                level: "attested-unverifiable-here",
+                key: intact,
+                reason: `${at}, signed with ${intact}, a key neither the signers nor an admission at base lists; it reads as attested once an admin admits the signer (chant workspace admit ${ret.id})`,
+            };
+        }
+    }
+    return { ...base, level: a.level, ...(a.key ? { key: a.key } : {}), reason: `${at}: ${a.reason}` };
+}
+/**
+ * Add the signers of return `ret` to the `admitted` list of
+ * `.chant/trust.json` at the repository root `repo`, keeping everything else
+ * in it. The admission counts once an admin's signed commit merges it: the
+ * file is policy, read at base, and a protected write.
+ */
+export function admitReturn(repo, ret, opts = {}) {
+    if (ret.signers.length === 0)
+        throw new LockError(`return ${ret.id} names no signer: none of its origin commits carries an ssh signature`);
+    const abs = join(repo, TRUST_CONFIG_PATH);
+    let config = { schema: 1 };
+    if (existsSync(abs)) {
+        try {
+            config = JSON.parse(readFileSync(abs, "utf-8"));
+        }
+        catch (err) {
+            throw new LockError(`${TRUST_CONFIG_PATH} is not valid JSON, so the admission cannot be added to it: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    const admitted = Array.isArray(config.admitted) ? config.admitted : [];
+    const have = new Set(admitted.filter((a) => a.return === ret.id).flatMap((a) => (a.signers ?? []).map((s) => s.key)));
+    const added = ret.signers.filter((s) => !have.has(s.key)).map((s) => ({ principal: s.principal, key: s.key }));
+    if (added.length > 0 && !opts.dryRun) {
+        config.admitted = [...admitted, { return: ret.id, signers: added, ...(opts.note ? { note: opts.note } : {}) }];
+        mkdirSync(dirname(abs), { recursive: true });
+        writeFileSync(abs, JSON.stringify(config, null, 2) + "\n");
+    }
+    return { id: ret.id, path: TRUST_CONFIG_PATH, added, written: added.length > 0 && !opts.dryRun };
+}

package/dist/workspace/root-refusal.js

@@ -0,0 +1,75 @@
+/**
+ * `chant build` and `chant lint` at the root of a declared workspace (#2537,
+ * #2524 D0 and D12, ws-023).
+ *
+ * Once `chant.workspace.json` declares members, their directories leave the
+ * root project. A top-level `chant build` there would quietly build less than
+ * it did before the file existed, so both commands refuse with `WSP000` and
+ * point to `chant workspace build` and `chant workspace lint`. `--root-only`,
+ * or `rootOnly: true` in the root's `chant.config`, lets them run on the root
+ * project alone, with the member directories and example-group matches left
+ * out of discovery.
+ *
+ * `main.ts` decides with `findWorkspaceRoot` and `findProjectRoot`, which only
+ * test whether files exist, and imports this module only when the command's
+ * project is a declared root. A project with no declaration never loads it.
+ */
+import { relative } from "node:path";
+import { formatError } from "../cli/format.js";
+import { ownerOf, readDeclaration, resolveGroups, rootExclusions, WorkspaceReadError } from "./declaration.js";
+import { workingTree } from "./tree.js";
+/** The code a refusal carries. `WSP` ids name workspace findings (#2524 D16); `000` is the refusal itself. */
+export const ROOT_REFUSAL_CODE = "WSP000";
+/** Decide what a root `build` or `lint` does. Pure apart from reading the declaration. */
+export function decideRootCommand(input) {
+    const tree = workingTree(input.workspaceDir);
+    let declaration;
+    let groups;
+    try {
+        declaration = readDeclaration(tree);
+        groups = resolveGroups(declaration, tree);
+    }
+    catch (err) {
+        if (!(err instanceof WorkspaceReadError))
+            throw err;
+        return {
+            action: "refuse",
+            message: `${ROOT_REFUSAL_CODE}: ${input.workspaceDir} holds a workspace declaration that can't be read, so chant ${input.verb} ` +
+                `can't tell which directories belong to the root project. ${err.code}: ${err.describe()}`,
+        };
+    }
+    const rel = relative(input.workspaceDir, input.target).split("\\").join("/") || ".";
+    const owner = ownerOf(declaration, groups, rel === "." ? "." : rel);
+    if (owner && ("group" in owner || owner.member.dir !== "."))
+        return { action: "not-root" };
+    const excluded = rootExclusions(declaration, groups).map((e) => e.dir);
+    if (input.rootOnly)
+        return { action: "root-only", excluded };
+    const members = declaration.members.filter((m) => m.dir !== ".").length;
+    const matches = groups.reduce((n, g) => n + g.matches.length, 0);
+    const moved = [
+        `${members} member${members === 1 ? "" : "s"}`,
+        ...(matches > 0 ? [`${matches} example project${matches === 1 ? "" : "s"}`] : []),
+    ].join(" and ");
+    return {
+        action: "refuse",
+        message: `${ROOT_REFUSAL_CODE}: this is the root of workspace ${declaration.name} (${declaration.file}), which moves ` +
+            `${moved} out of the root project. Run chant workspace ${input.verb} to ${input.verb} each member with its own ` +
+            `toolchain, or pass --root-only (or set rootOnly: true in chant.config) to ${input.verb} the root project alone.`,
+    };
+}
+/**
+ * Apply {@link decideRootCommand}: print the refusal and return 1, or return
+ * undefined so the command goes on. A root-only run needs nothing set up:
+ * every discovery walk under a declaration already leaves the member
+ * directories and group matches out (#2527, `workspaceMemberDirs` in
+ * `../discovery/walk.ts`), and `excluded` names the same directories.
+ */
+export function guardRootCommand(input) {
+    const result = decideRootCommand(input);
+    if (result.action === "refuse") {
+        console.error(formatError({ message: result.message }));
+        return 1;
+    }
+    return undefined;
+}