@intentius/chant 0.110.0 → 0.111.0

package/src/op/factory.e2e.test.ts

@@ -184,7 +184,7 @@ describe("the factory Op's seams for an orchestrator (studio#382)", () => {
       // A builder that reports a run and a check that reports per criterion.
       writeFileSync(join(dir, "hooks", "builder2.cjs"), `${BUILDER}\nconsole.log(JSON.stringify({ ok: true, run: { id: "run-7" }, agent: "builder-small", chantAgent: "factory", records: ["contract:C-1"] }));\n`);
       writeFileSync(join(dir, "hooks", "check2.cjs"), `console.log(JSON.stringify({ criteria: { "AC-1": "pass", "AC-2": "fail" }, built: JSON.parse(process.env.FACTORY_BUILD).agent }));`);
-      writeFileSync(join(dir, "hooks", "after.cjs"), `require("node:fs").writeFileSync(require("node:path").join(process.env.FACTORY_FAIL_DIR, "after.json"), JSON.stringify({ outcome: process.env.FACTORY_OUTCOME, commit: process.env.FACTORY_COMMIT, reason: process.env.FACTORY_REASON, check: JSON.parse(process.env.FACTORY_CHECK) }));`);
+      writeFileSync(join(dir, "hooks", "after.cjs"), `require("node:fs").writeFileSync(require("node:path").join(process.env.FACTORY_FAIL_DIR, "after.json"), JSON.stringify({ outcome: process.env.FACTORY_OUTCOME, commit: process.env.FACTORY_COMMIT, reason: process.env.FACTORY_REASON, check: JSON.parse(process.env.FACTORY_CHECK), activity: process.env.CHANT_RUN_ACTIVITY ?? null }));`);
       // The prepare hook writes W-110 in the checkout and leaves it uncommitted; the others are taken out of the way.
       writeFileSync(
         join(dir, "hooks", "prepare.cjs"),
@@ -204,6 +204,8 @@ describe("the factory Op's seams for an orchestrator (studio#382)", () => {
       expect(result.workLease).toMatchObject({ item: "W-110", outcome: "not_done" });
       const after = JSON.parse(readFileSync(join(dir, "after.json"), "utf-8"));
       expect(after).toMatchObject({ outcome: "not_done", reason: "criteria AC-2 have no passing evidence", check: { built: "builder-small" } });
+      // A hook gets the run's activity file, as a shell step does (#3637).
+      expect(after.activity).toMatch(/\.activity\.jsonl$/);
       // The attempt was committed with why, and the run kept that commit.
       expect(after.commit).toMatch(/^[0-9a-f]{40}$/);
       // The kept attempt holds the carried item with AC-1 ticked and AC-2 failed.

package/src/workspace/box-cli.ts

@@ -2,8 +2,9 @@
  * `chant workspace box`: a member's box block. Two verbs:
  *
  * - `box listing set <member>` (#3308) changes the box's listing
- *   (`box-listing.ts`). A box's other configuration is changed by editing the
- *   declaration in a reviewed change.
+ *   (`box-listing.ts`), and `box factory set <member>` (#3600) its factory,
+ *   such as where it publishes (`box-factory-write.ts`). A box's other
+ *   configuration is changed by editing the declaration in a reviewed change.
  * - `box publish <member> <item> | --records` (#3165, ws-088) runs the
  *   publisher the box block names and checks what it did (`box-publish.ts`).
  */
@@ -12,12 +13,14 @@ import { readFileSync } from "node:fs";
 import { resolve } from "node:path";
 import { formatError } from "../cli/format";
 import type { CommandContext } from "../cli/registry";
+import { BOX_FACTORY_CONTRACT_VERSION, BOX_FACTORY_WRITE_SCHEMA_ID, boxFactorySet, type BoxFactoryWriteDocument } from "./box-factory-write";
 import { BOX_LISTING_CONTRACT_VERSION, BOX_LISTING_WRITE_SCHEMA_ID, boxListingSet, type BoxListingWriteDocument } from "./box-listing";
 import { BOX_PUBLISH_CONTRACT_VERSION, BOX_PUBLISH_SCHEMA_ID, boxPublish, type BoxPublishDocument } from "./box-publish";
 import { readerVersion } from "./declaration";
 import { AGENT_ENV } from "./write-scope";
 
 const USAGE = "chant workspace box listing set <member> [--from <file|->] [--cover <image> [--cover-path <path>]] [--by <principal>] [--dry-run] [--json]";
+const FACTORY_USAGE = "chant workspace box factory set <member> --from <file|-> [--by <principal>] [--dry-run] [--json]";
 const PUBLISH_USAGE = "chant workspace box publish <member> (<item> | --records) [--by <principal>] [--head <owner/name>] [--dry-run] [--json]";
 
 export async function runWorkspaceBox(ctx: CommandContext): Promise<number> {
@@ -27,11 +30,13 @@ export async function runWorkspaceBox(ctx: CommandContext): Promise<number> {
   const [, noun, verb, member, ...extra] = args.positionals ?? [];
   // For publish, the third positional is the member and the fourth the item.
   if (noun === "publish") return runPublish(ctx, verb, member === undefined ? [] : [member, ...extra]);
+  if (noun === "factory" && verb === "set") return runFactorySet(ctx, member, extra);
   if (noun !== "listing" || verb !== "set") {
+    const verbs = "listing set <member>, factory set <member> or publish <member>";
     console.error(
       formatError({
-        message: noun === undefined ? "chant workspace box takes listing set <member> or publish <member>" : `chant workspace box takes listing set <member> or publish <member>, not ${[noun, verb].filter(Boolean).join(" ")}`,
-        hint: `${USAGE}\n${PUBLISH_USAGE}`,
+        message: noun === undefined ? `chant workspace box takes ${verbs}` : `chant workspace box takes ${verbs}, not ${[noun, verb].filter(Boolean).join(" ")}`,
+        hint: `${USAGE}\n${FACTORY_USAGE}\n${PUBLISH_USAGE}`,
       }),
     );
     return 1;
@@ -75,6 +80,32 @@ export async function runWorkspaceBox(ctx: CommandContext): Promise<number> {
   );
 }
 
+/** `box factory set <member> --from <file|->` (#3600). */
+function runFactorySet(ctx: CommandContext, member: string | undefined, extra: string[]): number {
+  const { args } = ctx;
+  const cwd = process.cwd();
+  const print = (doc: BoxFactoryWriteDocument): number => {
+    console.log(JSON.stringify(doc, null, 2));
+    return "error" in doc ? 1 : 0;
+  };
+  const fail = (code: "write-usage-invalid" | "write-input-invalid", message: string) =>
+    print({ $schema: BOX_FACTORY_WRITE_SCHEMA_ID, contract: BOX_FACTORY_CONTRACT_VERSION, chant: readerVersion(), member: member ?? null, error: { code, message } });
+  if (member === undefined) return fail("write-usage-invalid", `box factory set needs the member whose box builds; ${FACTORY_USAGE}`);
+  if (extra.length > 0) return fail("write-usage-invalid", `box factory set takes one member, and was also given ${extra.join(" ")}`);
+  for (const [flag, v] of [["--set", args.set], ["--kind", args.kind], ["--at", args.at], ["--cover", args.cover]] as const) {
+    if (v !== undefined) return fail("write-usage-invalid", `box factory set takes its fields with --from, not ${flag}`);
+  }
+  let fields: string | undefined;
+  if (args.migrateFrom !== undefined) {
+    try {
+      fields = readFileSync(args.migrateFrom === "-" ? 0 : resolve(cwd, args.migrateFrom), "utf-8");
+    } catch (err) {
+      return fail("write-input-invalid", `--from ${args.migrateFrom} could not be read: ${err instanceof Error ? err.message : String(err)}`);
+    }
+  }
+  return print(boxFactorySet({ cwd, member, fields, by: args.by, agent: process.env[AGENT_ENV] || undefined, dryRun: args.dryRun === true }));
+}
+
 /** `box publish <member> <item>` or `box publish <member> --records`. */
 function runPublish(ctx: CommandContext, member: string | undefined, rest: string[]): number {
   const { args } = ctx;

package/src/workspace/box-factory-write.schema.json

@@ -0,0 +1,342 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://intentius.io/chant/schemas/workspace/box-factory-write/v1/box-factory-write.schema.json",
+  "title": "chant workspace box factory set output",
+  "description": "What `chant workspace box factory set <member> --from <file|->` prints (#3600): the box's factory before and after, as `status --json` prints it, and the file the write changed, or the reason it wrote nothing. The write changes only the factory's own top-level properties, members[i].box.factory in the declaration, in place, keeping the file's formatting and comments. It never commits. Readers ignore fields they do not know; a field is only ever added within a version. The error codes are a closed list, each in the one closed list of `reason-codes.ts`. Contract version 1 of this document is written by chant 0.110.0 and newer.",
+  "oneOf": [
+    {
+      "$ref": "#/$defs/result"
+    },
+    {
+      "$ref": "#/$defs/failure"
+    }
+  ],
+  "$defs": {
+    "result": {
+      "description": "The factory was written, or would be with --dry-run, or already held what was given (changed false). Exit code 0.",
+      "type": "object",
+      "required": [
+        "$schema",
+        "contract",
+        "chant",
+        "member",
+        "declaration",
+        "paths",
+        "changed",
+        "dryRun",
+        "previous",
+        "factory"
+      ],
+      "properties": {
+        "$schema": {
+          "const": "https://intentius.io/chant/schemas/workspace/box-factory-write/v1/box-factory-write.schema.json"
+        },
+        "contract": {
+          "const": 1
+        },
+        "chant": {
+          "type": "string",
+          "description": "The chant that wrote it."
+        },
+        "member": {
+          "type": "string",
+          "description": "The member whose box block holds the factory."
+        },
+        "declaration": {
+          "type": "object",
+          "required": [
+            "path",
+            "sha256"
+          ],
+          "properties": {
+            "path": {
+              "type": "string",
+              "description": "The declaration file, relative to the repository root (the working directory outside git), with / separators."
+            },
+            "sha256": {
+              "type": "string",
+              "pattern": "^[0-9a-f]{64}$",
+              "description": "The sha256 of the declaration's bytes after the write, or as they would be with --dry-run."
+            }
+          }
+        },
+        "paths": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "The declaration, relative to the repository root, when the write changed it or would with --dry-run; empty when the factory already held what was given."
+        },
+        "changed": {
+          "type": "boolean",
+          "description": "Whether the declaration changed: paths is not empty."
+        },
+        "dryRun": {
+          "type": "boolean",
+          "description": "True when --dry-run was given: nothing was written, and the document says what would have been."
+        },
+        "previous": {
+          "oneOf": [
+            {
+              "type": "null"
+            },
+            {
+              "$ref": "#/$defs/factory"
+            }
+          ],
+          "description": "The factory before the write, as status --json prints it, or null when the box declared none."
+        },
+        "factory": {
+          "oneOf": [
+            {
+              "type": "null"
+            },
+            {
+              "$ref": "#/$defs/factory"
+            }
+          ],
+          "description": "The factory after the write, as status --json prints it, or null when the box still declares none."
+        }
+      }
+    },
+    "factory": {
+      "type": "object",
+      "required": [
+        "builds",
+        "check",
+        "checks",
+        "builders",
+        "tiers",
+        "builderFor",
+        "publish"
+      ],
+      "properties": {
+        "builds": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "type": "string"
+          },
+          "description": "The members the factory builds, in declaration order. A work item a person asks for constrains member:<the first>."
+        },
+        "check": {
+          "description": "The verdict command, run from the workspace root, and what it is; null when none is declared.",
+          "oneOf": [
+            {
+              "type": "null"
+            },
+            {
+              "type": "object",
+              "required": [
+                "run",
+                "kind"
+              ],
+              "properties": {
+                "run": {
+                  "type": "string"
+                },
+                "kind": {
+                  "enum": [
+                    "test",
+                    "build",
+                    "lint",
+                    "plan",
+                    "conformance"
+                  ]
+                }
+              }
+            }
+          ]
+        },
+        "checks": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "description": "Where a work item's builder writes its check, from the workspace root, or null for the orchestrator's choice."
+        },
+        "builders": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "description": "The member that declares the builder agents, or null."
+        },
+        "tiers": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": [
+              "tier",
+              "agent",
+              "kinds",
+              "session"
+            ],
+            "properties": {
+              "tier": {
+                "type": "string"
+              },
+              "agent": {
+                "type": "string"
+              },
+              "kinds": {
+                "oneOf": [
+                  {
+                    "type": "null"
+                  },
+                  {
+                    "type": "array",
+                    "items": {
+                      "type": "string"
+                    }
+                  }
+                ]
+              },
+              "session": {
+                "type": [
+                  "string",
+                  "null"
+                ]
+              }
+            }
+          },
+          "description": "Which builder agent builds at which tier, as declared (#3152, ws-094), each { tier, agent, kinds, session } with kinds and session null when not declared; empty when none is. Added in contract 1 by chant 0.103.0."
+        },
+        "builderFor": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "object",
+            "additionalProperties": {
+              "type": "object",
+              "required": [
+                "agent",
+                "session"
+              ],
+              "properties": {
+                "agent": {
+                  "type": "string"
+                },
+                "session": {
+                  "type": [
+                    "string",
+                    "null"
+                  ]
+                }
+              }
+            }
+          },
+          "description": "The builder for each member the factory builds, by tier (#3152): member name, then tier, then { agent, session }. For a member the entry naming its kind is used, else the tier's entry with no kinds; a tier with neither is left out. Added in contract 1 by chant 0.103.0."
+        },
+        "publish": {
+          "description": "Where a finished build is published, or null when the factory doesn't publish past the box.",
+          "oneOf": [
+            {
+              "type": "null"
+            },
+            {
+              "type": "object",
+              "required": [
+                "forge",
+                "repo",
+                "base",
+                "branchPrefix",
+                "head"
+              ],
+              "properties": {
+                "forge": {
+                  "const": "github"
+                },
+                "repo": {
+                  "type": "string",
+                  "description": "owner/name: where the pull request is opened."
+                },
+                "base": {
+                  "type": [
+                    "string",
+                    "null"
+                  ],
+                  "description": "The branch the pull request targets, or null for the repository's default branch."
+                },
+                "branchPrefix": {
+                  "type": "string",
+                  "description": "What the published branch's name starts with, before the work item's id. chant/work/ unless declared."
+                },
+                "head": {
+                  "type": [
+                    "string",
+                    "null"
+                  ],
+                  "description": "owner/name of the fork the branch is pushed to, or null to push to repo."
+                }
+              }
+            }
+          ]
+        }
+      }
+    },
+    "failure": {
+      "type": "object",
+      "description": "Nothing was written. Exit code 1.",
+      "required": [
+        "$schema",
+        "contract",
+        "chant",
+        "member",
+        "error"
+      ],
+      "properties": {
+        "$schema": {
+          "const": "https://intentius.io/chant/schemas/workspace/box-factory-write/v1/box-factory-write.schema.json"
+        },
+        "contract": {
+          "const": 1
+        },
+        "chant": {
+          "type": "string"
+        },
+        "member": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "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",
+                "write-usage-invalid",
+                "write-input-invalid",
+                "factory-member-unknown",
+                "factory-box-missing",
+                "write-scope-member",
+                "write-scope-protected",
+                "write-scope-class-unknown",
+                "agent-unknown",
+                "principal-unidentified",
+                "write-lock-timeout",
+                "write-lock-not-held"
+              ]
+            },
+            "message": {
+              "type": "string"
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/src/workspace/box-factory-write.test.ts

@@ -0,0 +1,108 @@
+/**
+ * #3600: a box's factory written through chant, so a box planted from a
+ * shared template gets its factory.publish target at planting.
+ */
+
+import { readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { afterAll, describe, expect, test } from "vitest";
+import { cleanScratch, contract, git, repo } from "./__fixtures__/contract-repo";
+import { boxFactorySet, type BoxFactoryWriteDocument, type BoxFactoryWriteRequest } from "./box-factory-write";
+import schema from "./box-factory-write.schema.json";
+import { workspaceStatus } from "./status";
+
+afterAll(cleanScratch);
+
+const { expectValid } = contract(schema);
+
+/** The template's declaration: a box whose factory builds the app and names no publish target. */
+const TEMPLATE = `{
+  // planted from the studio template
+  "name": "fern",
+  "schema": 1,
+  "members": [
+    { "name": "app", "dir": "app", "kind": "other", "because": "the app" },
+    {
+      "name": "box",
+      "dir": "box",
+      "kind": "other",
+      "because": "the box",
+      "box": {
+        "factory": { "builds": ["app"], "check": "npm test" }, // no publish: the template can't know the repo
+        "publisher": "node box/publish.mjs",
+      },
+    },
+  ],
+}
+`;
+
+function run(root: string, req: Omit<BoxFactoryWriteRequest, "cwd" | "fields"> & { fields?: unknown }): BoxFactoryWriteDocument {
+  const doc = boxFactorySet({ ...req, cwd: root, fields: req.fields === undefined ? undefined : JSON.stringify(req.fields) });
+  expectValid(doc);
+  return doc;
+}
+
+const code = (doc: BoxFactoryWriteDocument) => ("error" in doc ? doc.error.code : null);
+
+describe("box factory set (#3600)", () => {
+  test("a planter sets factory.publish, status reads it back, and the file keeps its comments", async () => {
+    const root = repo({ "chant.workspace.jsonc": TEMPLATE, "app/a.txt": "", "box/b.txt": "" });
+    const doc = run(root, { member: "box", fields: { publish: { repo: "alex/fern", base: "main" } } });
+    expect(doc).toMatchObject({
+      member: "box",
+      changed: true,
+      paths: ["chant.workspace.jsonc"],
+      previous: { builds: ["app"], publish: null },
+      factory: { builds: ["app"], check: { run: "npm test", kind: "test" }, publish: { forge: "github", repo: "alex/fern", base: "main", branchPrefix: "chant/work/", head: null } },
+    });
+    const text = readFileSync(join(root, "chant.workspace.jsonc"), "utf-8");
+    expect(text).toContain("// no publish: the template can't know the repo");
+    expect(text).toContain("// planted from the studio template");
+    const status = await workspaceStatus({ cwd: root, env: "box" });
+    if ("error" in status) throw new Error(status.error.message);
+    expect(status.members.find((m) => m.name === "box")?.box?.factory?.publish?.repo).toBe("alex/fern");
+
+    // The same again changes nothing; null takes a field out.
+    expect(run(root, { member: "box", fields: { publish: { repo: "alex/fern", base: "main" } } })).toMatchObject({ changed: false, paths: [] });
+    expect(run(root, { member: "box", fields: { publish: null } })).toMatchObject({ changed: true, factory: { publish: null } });
+  });
+
+  test("a dry run writes nothing, and a box with no factory gets one", () => {
+    const root = repo({
+      "chant.workspace.json": `${JSON.stringify({ name: "w", schema: 1, members: [{ name: "app", dir: "app", kind: "other", because: "b", box: {} }] }, null, 2)}\n`,
+      "app/a.txt": "",
+    });
+    const before = readFileSync(join(root, "chant.workspace.json"), "utf-8");
+    expect(run(root, { member: "app", fields: { builds: ["app"], publish: { repo: "o/r" } }, dryRun: true })).toMatchObject({ changed: true, dryRun: true, previous: null });
+    expect(readFileSync(join(root, "chant.workspace.json"), "utf-8")).toBe(before);
+    expect(run(root, { member: "app", fields: { builds: ["app"], publish: { repo: "o/r" } } })).toMatchObject({ factory: { builds: ["app"], publish: { repo: "o/r" } } });
+  });
+
+  test("refuses an unknown member, a member with no box, a field a factory doesn't take, and a repo that isn't owner/name", () => {
+    const root = repo({ "chant.workspace.jsonc": TEMPLATE, "app/a.txt": "", "box/b.txt": "" });
+    const before = readFileSync(join(root, "chant.workspace.jsonc"), "utf-8");
+    expect(code(run(root, { member: "ghost", fields: { publish: { repo: "o/r" } } }))).toBe("factory-member-unknown");
+    expect(code(run(root, { member: "app", fields: { publish: { repo: "o/r" } } }))).toBe("factory-box-missing");
+    expect(code(run(root, { member: "box", fields: { listing: {} } }))).toBe("write-input-invalid");
+    const bad = run(root, { member: "box", fields: { publish: { repo: "{{chant:repo}}" } } });
+    expect(code(bad)).toBe("write-input-invalid");
+    expect(code(run(root, { member: "box" }))).toBe("write-usage-invalid");
+    expect(readFileSync(join(root, "chant.workspace.jsonc"), "utf-8")).toBe(before);
+  });
+
+  test("a protected declaration takes the write when its except names the publish target", () => {
+    const decl = (except?: string[]) => ({
+      name: "w",
+      schema: 1,
+      members: [{ name: "app", dir: ".", kind: "other", because: "b", box: { factory: { builds: ["app"] } } }],
+      writeScope: { human: { protected: [except ? { path: "chant.workspace.json", except } : "chant.workspace.json"] } },
+    });
+    const root = repo({ "chant.workspace.json": `${JSON.stringify(decl(), null, 2)}\n` }, true);
+    git(root, "branch", "-M", "main");
+    expect(code(run(root, { member: "app", fields: { publish: { repo: "o/r" } } }))).toBe("write-scope-protected");
+    writeFileSync(join(root, "chant.workspace.json"), `${JSON.stringify(decl(["/members/*/box/factory/publish"]), null, 2)}\n`);
+    git(root, "commit", "-q", "-am", "planting may set the publish target");
+    expect(run(root, { member: "app", fields: { publish: { repo: "o/r" } } })).toMatchObject({ changed: true });
+    expect(code(run(root, { member: "app", fields: { "x-note": 1 } }))).toBe("write-scope-protected");
+  });
+});