@intentius/chant 0.100.0 → 0.101.0

package/src/workspace/agent-cli.ts

@@ -0,0 +1,134 @@
+/**
+ * `chant workspace agent [<name>] [--json]` (#2524 D20, #2548, ws-067): what
+ * an agent session reloads from, read from the repository alone.
+ *
+ * A session is declared in the declaration's `agents` list and bound to one
+ * member. This prints the session, its member, its write scope (the files
+ * and the record kinds, with their verbs, it may write) and the spec: the
+ * `spec` block `chant workspace records --current --json` prints (#2546). An
+ * agent that resumes needs nothing else: no memory of an earlier run, no
+ * state outside the checkout.
+ *
+ * The session and its scope come from the declaration at base, as the
+ * write paths and `check --changes` read them; the spec from the working
+ * tree, which is what the agent works on. Without a name, the session
+ * `CHANT_AGENT` names.
+ */
+
+import { formatError } from "../cli/format";
+import type { CommandContext } from "../cli/registry";
+import { readerVersion, WORKSPACE_ERROR_CODES, WorkspaceReadError, WRITE_VERBS, type WriteVerb } from "./declaration";
+import type { ReasonCode } from "./reason-codes";
+import { declaredKindFiles, queryDeclaredRecords, type SpecView } from "./records-cli";
+import { AGENT_ENV, resolveWriter, scopeOf, scopeSource, WriteScopeError } from "./write-scope";
+
+/** The version of the `agent` document this chant writes. */
+export const AGENT_CONTRACT_VERSION = 1;
+
+export const AGENT_OUTPUT_SCHEMA_ID = "https://intentius.io/chant/schemas/workspace/agent/v1/agent.schema.json";
+
+/** Why the session can't be printed. Closed. */
+export const AGENT_ERROR_CODES = [...WORKSPACE_ERROR_CODES, "agent-unknown"] as const satisfies readonly ReasonCode[];
+export type AgentErrorCode = (typeof AGENT_ERROR_CODES)[number];
+
+/** A record kind in the session's reach, with the verbs it may write it with. */
+export interface AgentKindScope {
+  /** The kind file from the workspace root, as the declaration names it. */
+  path: string;
+  /** The kind file's recordKind.name, or null when it can't be loaded. */
+  kind: string | null;
+  /** The name the declaration gives it, or null. */
+  name: string | null;
+  /** The member that declares it, or null for the workspace's own. */
+  member: string | null;
+  /** Empty when writeScope.agent.records leaves the kind out. */
+  verbs: WriteVerb[];
+}
+
+interface Head {
+  $schema: string;
+  contract: number;
+  chant: string;
+}
+
+export type AgentDocument =
+  | (Head & {
+      workspace: { name: string; root: string; scopeFrom: "base" | "working-tree" };
+      agent: { name: string; member: { name: string; dir: string; kind: string }; principals: string[] };
+      scope: {
+        /** The one member whose files the session writes. */
+        members: string[];
+        /** Every declared kind in reach: the workspace's own and the member's. */
+        records: AgentKindScope[];
+      };
+      /** The spec, as records --current --json prints it. */
+      spec: SpecView;
+      /** The reads that rebuild the session's context. */
+      reload: string[];
+    })
+  | (Head & { error: { code: AgentErrorCode; message: string } });
+
+/** The session `name` names, as {@link AgentDocument} prints it. Never throws a read or scope error. */
+export async function agentSession(q: { cwd: string; name: string }): Promise<AgentDocument> {
+  const head: Head = { $schema: AGENT_OUTPUT_SCHEMA_ID, contract: AGENT_CONTRACT_VERSION, chant: readerVersion() };
+  try {
+    const source = scopeSource(q.cwd);
+    if (source.declaration === null || source.from === null) {
+      throw new WorkspaceReadError("declaration-missing", "no chant.workspace.json or .jsonc between this directory and the git root, so no agent session is declared");
+    }
+    const decl = source.declaration;
+    const writer = resolveWriter(decl, source.policy, { agent: q.name });
+    const agent = writer.agent!;
+    const member = decl.members.find((m) => m.name === agent.member)!;
+    const rules = scopeOf(decl, writer)!.records;
+    // The spec query, over every declared kind in the working tree.
+    const set = await queryDeclaredRecords(declaredKindFiles(q.cwd), { cwd: q.cwd, current: true });
+    const loadedName = new Map(set.kinds.map((k) => [k.declared.path, "error" in k ? null : k.kind.name]));
+    const records: AgentKindScope[] = [...decl.records, ...member.records].map((d) => {
+      const kind = loadedName.get(d.path) ?? null;
+      const names = [kind, d.name].filter((n): n is string => n !== null);
+      const verbs = rules === null ? [...WRITE_VERBS] : WRITE_VERBS.filter((v) => names.some((n) => (rules[n] ?? []).includes(v)));
+      return { path: d.path, kind, name: d.name, member: d.member, verbs };
+    });
+    return {
+      ...head,
+      workspace: { name: decl.name, root: source.root ?? ".", scopeFrom: source.from },
+      agent: { name: agent.name, member: { name: member.name, dir: member.dir, kind: member.kind }, principals: agent.principals },
+      scope: { members: [member.name], records },
+      spec: set.spec ?? { kinds: [], records: [] },
+      reload: [`chant workspace agent ${agent.name} --json`, "chant workspace records --current --json"],
+    };
+  } catch (err) {
+    if (err instanceof WorkspaceReadError || err instanceof WriteScopeError) {
+      return { ...head, error: { code: err.code as AgentErrorCode, message: err instanceof WorkspaceReadError ? err.describe() : err.message } };
+    }
+    throw err;
+  }
+}
+
+const USAGE = "chant workspace agent [<name>] [--json]";
+
+/** `chant workspace agent`: exit 0 when the session was printed, 1 otherwise. */
+export async function runWorkspaceAgent(ctx: CommandContext): Promise<number> {
+  const { args } = ctx;
+  const name = args.extraPositional ?? (process.env[AGENT_ENV] || undefined);
+  if (!name) {
+    console.error(formatError({ message: `name the agent session, or set ${AGENT_ENV}`, hint: USAGE }));
+    return 1;
+  }
+  const doc = await agentSession({ cwd: process.cwd(), name });
+  if (args.json || args.format === "json") console.log(JSON.stringify(doc, null, 2));
+  if ("error" in doc) {
+    if (!args.json && args.format !== "json") console.error(formatError({ message: `${doc.error.code}: ${doc.error.message}`, hint: USAGE }));
+    return 1;
+  }
+  if (args.json || args.format === "json") return 0;
+  const out: string[] = [];
+  out.push(`agent     ${doc.agent.name}, bound to member ${doc.agent.member.name} (${doc.agent.member.dir}), scope read from ${doc.workspace.scopeFrom}`);
+  for (const r of doc.scope.records) out.push(`records   ${r.name ?? r.kind ?? r.path} (${r.path}): ${r.verbs.length > 0 ? r.verbs.join(", ") : "not writable"}`);
+  out.push(`spec      ${doc.spec.records.length} current records of ${doc.spec.kinds.length} spec kinds`);
+  for (const r of doc.spec.records) out.push(`          ${r.kind}/${r.id ?? "?"} ${r.state ?? ""} ${r.path}`);
+  out.push(`reload    ${doc.reload.join("; ")}`);
+  console.log(out.join("\n"));
+  return 0;
+}

package/src/workspace/agent.schema.json

@@ -0,0 +1,356 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://intentius.io/chant/schemas/workspace/agent/v1/agent.schema.json",
+  "title": "chant workspace agent output",
+  "description": "What `chant workspace agent <name> --json` prints (#2524 D20, #2548, ws-067): an agent session, the one member it is bound to, its write scope and the spec, read from the repository alone, so a session that resumes rebuilds its context from this and nothing else. The session and its scope are read from the declaration at base, as the write paths and check --changes read them; the spec from the working tree. Readers ignore fields they do not know; a field is only ever added within a version. The error codes are a closed list, and every one is in the one closed list of `reason-codes.ts`. Contract version 1; this document was added to it by #2548.",
+  "oneOf": [
+    {
+      "$ref": "#/$defs/result"
+    },
+    {
+      "$ref": "#/$defs/failure"
+    }
+  ],
+  "$defs": {
+    "result": {
+      "description": "The session was found. Exit code 0.",
+      "type": "object",
+      "required": [
+        "$schema",
+        "contract",
+        "chant",
+        "workspace",
+        "agent",
+        "scope",
+        "spec",
+        "reload"
+      ],
+      "properties": {
+        "$schema": {
+          "const": "https://intentius.io/chant/schemas/workspace/agent/v1/agent.schema.json"
+        },
+        "contract": {
+          "const": 1
+        },
+        "chant": {
+          "type": "string",
+          "description": "The chant that wrote the document."
+        },
+        "workspace": {
+          "type": "object",
+          "required": [
+            "name",
+            "root",
+            "scopeFrom"
+          ],
+          "properties": {
+            "name": {
+              "type": "string"
+            },
+            "root": {
+              "type": "string",
+              "description": "The workspace root relative to the git root, \".\" for the git root."
+            },
+            "scopeFrom": {
+              "enum": [
+                "base",
+                "working-tree"
+              ],
+              "description": "Where the declaration was read: the base revision (origin/HEAD, main or master), or the working tree when there is no base or no declaration at it."
+            }
+          }
+        },
+        "agent": {
+          "type": "object",
+          "required": [
+            "name",
+            "member",
+            "principals"
+          ],
+          "properties": {
+            "name": {
+              "type": "string"
+            },
+            "member": {
+              "type": "object",
+              "required": [
+                "name",
+                "dir",
+                "kind"
+              ],
+              "properties": {
+                "name": {
+                  "type": "string"
+                },
+                "dir": {
+                  "type": "string"
+                },
+                "kind": {
+                  "type": "string"
+                }
+              }
+            },
+            "principals": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              },
+              "description": "Principals that write only as this session."
+            }
+          }
+        },
+        "scope": {
+          "type": "object",
+          "required": [
+            "members",
+            "records"
+          ],
+          "properties": {
+            "members": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              },
+              "description": "The one member whose files the session writes."
+            },
+            "records": {
+              "type": "array",
+              "description": "Every declared record kind in the session's reach: the workspace's own kinds, then the member's.",
+              "items": {
+                "type": "object",
+                "required": [
+                  "path",
+                  "kind",
+                  "name",
+                  "member",
+                  "verbs"
+                ],
+                "properties": {
+                  "path": {
+                    "type": "string",
+                    "description": "The kind file from the workspace root."
+                  },
+                  "kind": {
+                    "type": [
+                      "string",
+                      "null"
+                    ],
+                    "description": "The kind file's recordKind.name, or null when it can't be loaded."
+                  },
+                  "name": {
+                    "type": [
+                      "string",
+                      "null"
+                    ],
+                    "description": "The name the declaration gives the kind, or null."
+                  },
+                  "member": {
+                    "type": [
+                      "string",
+                      "null"
+                    ],
+                    "description": "The member that declares the kind, or null for the workspace's own."
+                  },
+                  "verbs": {
+                    "type": "array",
+                    "items": {
+                      "enum": [
+                        "new",
+                        "amend",
+                        "review",
+                        "close"
+                      ]
+                    },
+                    "description": "How the session may write the kind's records; empty when writeScope.agent.records leaves the kind out."
+                  }
+                }
+              }
+            }
+          }
+        },
+        "spec": {
+          "description": "The spec exactly as chant workspace records --current --json prints it under spec (#2546): the current records of each declared kind marked spec: true, read in the working tree, each with the workspace files it pins.",
+          "type": "object",
+          "required": [
+            "kinds",
+            "records"
+          ],
+          "properties": {
+            "kinds": {
+              "type": "array",
+              "description": "The spec kinds, as the declaration names them, in its order.",
+              "items": {
+                "type": "object",
+                "required": [
+                  "member",
+                  "path",
+                  "name"
+                ],
+                "properties": {
+                  "member": {
+                    "type": [
+                      "string",
+                      "null"
+                    ]
+                  },
+                  "path": {
+                    "type": "string"
+                  },
+                  "name": {
+                    "type": [
+                      "string",
+                      "null"
+                    ]
+                  }
+                }
+              }
+            },
+            "records": {
+              "type": "array",
+              "description": "Every current record of the spec kinds, in the order of kinds and then path. Invalid records are listed with valid false, as under kinds.",
+              "items": {
+                "type": "object",
+                "required": [
+                  "kind",
+                  "id",
+                  "path",
+                  "state",
+                  "valid",
+                  "digest",
+                  "assets"
+                ],
+                "properties": {
+                  "kind": {
+                    "type": "string",
+                    "description": "The kind's name, such as decision."
+                  },
+                  "id": {
+                    "type": [
+                      "string",
+                      "null"
+                    ]
+                  },
+                  "path": {
+                    "type": "string"
+                  },
+                  "state": {
+                    "type": [
+                      "string",
+                      "null"
+                    ]
+                  },
+                  "valid": {
+                    "type": "boolean"
+                  },
+                  "digest": {
+                    "type": "string",
+                    "pattern": "^[0-9a-f]{64}$"
+                  },
+                  "assets": {
+                    "type": "array",
+                    "items": {
+                      "$ref": "#/$defs/asset"
+                    }
+                  }
+                }
+              }
+            }
+          }
+        },
+        "reload": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "The reads that rebuild the session's context."
+        }
+      }
+    },
+    "failure": {
+      "description": "The declaration could not be read, or names no such session. Exit code 1.",
+      "type": "object",
+      "required": [
+        "$schema",
+        "contract",
+        "chant",
+        "error"
+      ],
+      "properties": {
+        "$schema": {
+          "const": "https://intentius.io/chant/schemas/workspace/agent/v1/agent.schema.json"
+        },
+        "contract": {
+          "const": 1
+        },
+        "chant": {
+          "type": "string"
+        },
+        "error": {
+          "type": "object",
+          "required": [
+            "code",
+            "message"
+          ],
+          "properties": {
+            "code": {
+              "enum": [
+                "declaration-missing",
+                "declaration-ambiguous",
+                "declaration-unparseable",
+                "declaration-invalid",
+                "placement-invalid",
+                "reader-too-old",
+                "root-chant-required",
+                "not-a-git-repository",
+                "revision-unknown",
+                "agent-unknown"
+              ]
+            },
+            "message": {
+              "type": "string"
+            }
+          }
+        },
+        "agent": false,
+        "scope": false
+      }
+    },
+    "asset": {
+      "type": "object",
+      "required": [
+        "path",
+        "sha256",
+        "actual",
+        "state"
+      ],
+      "properties": {
+        "path": {
+          "type": "string",
+          "description": "From the workspace root (workspaceRoot), with / separators."
+        },
+        "sha256": {
+          "type": "string",
+          "pattern": "^[0-9a-f]{64}$",
+          "description": "The hash the record pins."
+        },
+        "actual": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "pattern": "^[0-9a-f]{64}$",
+          "description": "The hash of the file's bytes in the tree read, or null when the file is missing."
+        },
+        "state": {
+          "enum": [
+            "pinned",
+            "drifted",
+            "missing",
+            "stale"
+          ],
+          "description": "pinned when the hashes match; drifted when they differ (a warning asset-drift); missing when the file is not there (a warning asset-missing); stale when the hashes match and a record this one supersedes pinned the same hash, with the file unchanged since this record was recorded (a warning asset-stale)."
+        }
+      }
+    }
+  }
+}

package/src/workspace/behold-kinds.test.ts

@@ -153,6 +153,6 @@ describe("behold's member kinds from their packages (#2545)", () => {
     await runWorkspaceLs({ args: parseArgs(["workspace", "ls", root, "--json"]), plugins: [] } as never);
     const doc = JSON.parse(out.join("\n")) as Extract<LsDocument, { members: unknown }>;
     expect(doc.members.map((m) => m.reason?.code ?? null)).toEqual(["unknown-kind", "unknown-kind", "unknown-kind", null]);
-    expect(doc.members[0].reason?.message).toMatch(/known kinds: chant, other, workspace$/);
+    expect(doc.members[0].reason?.message).toMatch(/known kinds: chant, design, other, workspace$/);
   });
 });

package/src/workspace/changes-cli.ts

@@ -32,6 +32,11 @@ export function formatChanges(doc: Result): string {
     out.push(`${p.status.padEnd(12)} ${p.change.padEnd(8)} ${p.path}${p.from ? ` (from ${p.from})` : ""}${why ? `; ${why}` : ""}`);
   }
   for (const f of doc.findings) out.push(`${f.severity === "fail" ? "error  " : "warning"}   ${f.code}: ${f.message}`);
+  if (doc.scope) {
+    const sc = doc.scope;
+    out.push(`scope     ${sc.commits.length} commits judged against the declaration at ${sc.base.slice(0, 8)}; restricted: ${sc.restricted.join(", ") || "none"}`);
+    for (const f of sc.findings) out.push(`error     ${f.code}: ${f.message}`);
+  }
   const s = doc.summary;
   out.push(`${s.paths} changed paths: ${s.covered} covered, ${s.uncovered} uncovered, ${s.outOfScope} out of scope, ${s.ignored} ignored, ${s.records} records; ${doc.findings.length} findings`);
   return out.join("\n");