@intentius/chant 0.101.0 → 0.104.0

package/src/workspace/principal-classes.test.ts

@@ -0,0 +1,175 @@
+/**
+ * Principal classes a plugin supplies (#3080, ws-079): the data file, the
+ * registry, and how a principal's role grants at base put it in a class.
+ */
+
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { afterAll, describe, expect, test } from "vitest";
+import { cleanScratch, scratchDir } from "./__fixtures__/contract-repo";
+import {
+  CLASS_NAME,
+  classesOf,
+  coreClassRegistry,
+  loadClassRegistry,
+  parseClassData,
+  principalClass,
+  PRINCIPALS_SCHEMA_ID,
+  readPackageClasses,
+  treeFiles,
+  unknownScopeClasses,
+} from "./principal-classes";
+import { emptyPolicy } from "./trust/policy";
+import type { WorkspaceTree } from "./tree";
+
+afterAll(cleanScratch);
+
+const data = (classes: unknown[]) => JSON.stringify({ schema: 1, classes });
+const reviewer = { name: "reviewer", description: "people who review decisions", role: "reviewer" };
+const operator = { name: "operator", description: "people who apply infrastructure", role: "ops" };
+
+/** A plugin package directory on disk, publishing `classes` at ./workspace-principals. */
+function plugin(root: string, dir: string, classes: unknown[], pkg: Record<string, unknown> = {}): void {
+  const abs = join(root, ...dir.split("/"));
+  mkdirSync(abs, { recursive: true });
+  writeFileSync(join(abs, "package.json"), JSON.stringify({ name: dir.replace(/\//g, "-"), version: "1.0.0", exports: { "./workspace-principals": "./principals.json" }, ...pkg }));
+  writeFileSync(join(abs, "principals.json"), data(classes));
+}
+
+describe("the principals file", () => {
+  test("has a versioned schema id and a name grammar shared with writeScope", () => {
+    expect(PRINCIPALS_SCHEMA_ID).toBe("https://intentius.io/chant/schemas/workspace/principals/v1/workspace-principals.schema.json");
+    expect(CLASS_NAME.test("reviewer")).toBe(true);
+    expect(CLASS_NAME.test("x-reviewer")).toBe(false);
+    expect(CLASS_NAME.test("Reviewer")).toBe(false);
+  });
+
+  test("a valid file yields its classes in file order, with the pin as source", () => {
+    expect(parseClassData(data([reviewer, operator]), "plugins/review")).toEqual({
+      classes: [
+        { ...reviewer, source: "plugins/review" },
+        { ...operator, source: "plugins/review" },
+      ],
+      problems: [],
+    });
+  });
+
+  test.each([
+    ["not JSON", "{", /not JSON/],
+    ["a missing role", data([{ name: "reviewer", description: "d" }]), /role/],
+    ["an unknown field", data([{ ...reviewer, members: ["app"] }]), /additional properties/],
+    ["an x- name", data([{ ...reviewer, name: "x-reviewer" }]), /pattern/],
+  ])("refuses %s", (_, text, message) => {
+    const read = parseClassData(text, "p");
+    expect(read.classes).toEqual([]);
+    expect(read.problems.join("\n")).toMatch(message);
+  });
+
+  test("leaves out a core name, a core role, a name twice and a role twice, keeping the rest", () => {
+    const read = parseClassData(
+      data([
+        { name: "human", description: "d", role: "people" },
+        { name: "bots", description: "d", role: "agent" },
+        reviewer,
+        { ...reviewer, role: "other" },
+        { name: "checker", description: "d", role: "reviewer" },
+        operator,
+      ]),
+      "p",
+    );
+    expect(read.classes.map((c) => c.name)).toEqual(["reviewer", "operator"]);
+    expect(read.problems).toEqual([
+      "p: class human is a core class and can't be supplied by a package",
+      "p: class bots names the role agent, which puts a principal in the core agent class",
+      "p: class reviewer is listed twice",
+      "p: class checker names the role reviewer, which another class in the file names; a role puts a principal in one class",
+    ]);
+  });
+});
+
+describe("reading a package's classes", () => {
+  test("a package exporting no ./workspace-principals supplies none, without a problem", () => {
+    const root = scratchDir();
+    plugin(root, "kinds-only", [reviewer], { exports: { "./workspace-kinds": "./kinds.json" } });
+    expect(loadClassRegistry([{ package: null, version: null, path: "kinds-only" }], root)).toMatchObject({ problems: [] });
+  });
+
+  test("the export must name a JSON file inside the package", () => {
+    const files = (pkg: object) => (p: string) => (p === "package.json" ? JSON.stringify(pkg) : undefined);
+    expect(readPackageClasses(files({ exports: { "./workspace-principals": "./index.js" } }), "p").problems[0]).toMatch(/must name a .json file/);
+    expect(readPackageClasses(files({ exports: { "./workspace-principals": "./../x.json" } }), "p").problems[0]).toMatch(/points outside the package/);
+    expect(readPackageClasses(files({ exports: { "./workspace-principals": "./gone.json" } }), "p").problems[0]).toMatch(/does not exist/);
+  });
+
+  test("a path pin is read through a tree when one is given, such as the base revision", () => {
+    const files: Record<string, string> = {
+      "plugins/review/package.json": JSON.stringify({ exports: { "./workspace-principals": "./principals.json" } }),
+      "plugins/review/principals.json": data([reviewer]),
+    };
+    const tree: WorkspaceTree = {
+      label: " at base",
+      stat: (p) => (p in files ? "file" : undefined),
+      list: () => undefined,
+      read: (p) => files[p],
+    };
+    expect(readPackageClasses(treeFiles(tree, "plugins/review"), "plugins/review").classes.map((c) => c.name)).toEqual(["reviewer"]);
+    // The working tree is not consulted: nothing exists on disk at this root.
+    const loaded = loadClassRegistry([{ package: null, version: null, path: "plugins/review" }], "/nonexistent", { tree });
+    expect(loaded.problems).toEqual([]);
+    expect(loaded.registry.names()).toEqual(["human", "agent", "runner", "service", "reviewer"]);
+  });
+
+  test("a class name or a role two pins supply is left out, with a problem on the second pin", () => {
+    const root = scratchDir();
+    plugin(root, "a", [reviewer, operator]);
+    plugin(root, "b", [{ ...reviewer, role: "approver" }]);
+    plugin(root, "c", [{ name: "applier", description: "d", role: "ops" }]);
+    const pins = ["a", "b", "c"].map((path) => ({ package: null, version: null, path }));
+    const { registry, problems } = loadClassRegistry(pins, root);
+    expect(registry.names()).toEqual(["human", "agent", "runner", "service"]);
+    expect(problems).toEqual([
+      { pin: 1, message: "class reviewer is supplied by both a and b; a class name has one source" },
+      { pin: 2, message: "class applier (c) names the role ops, which class operator (a) names; a role puts a principal in one class" },
+    ]);
+  });
+
+  test("a package pin that is not installed is a problem, and a pin naming neither is skipped", () => {
+    const root = scratchDir();
+    const { problems } = loadClassRegistry(
+      [
+        { package: "absent", version: "1.0.0", path: null },
+        { package: null, version: null, path: null },
+      ],
+      root,
+    );
+    expect(problems).toEqual([{ pin: 0, message: "pinned package absent is not installed; install it to read the kinds it supplies" }]);
+  });
+});
+
+describe("a principal's classes", () => {
+  const root = scratchDir();
+  plugin(root, "review", [reviewer, operator]);
+  const { registry } = loadClassRegistry([{ package: null, version: null, path: "review" }], root);
+  const policy = { ...emptyPolicy("x"), roles: { reviewer: ["Rev@example.com", "ci@example.com"], ops: ["rev@example.com"], runner: ["ci@example.com"] } };
+
+  test("come from role grants at base, core first, then the domain classes in order", () => {
+    expect(classesOf(registry, policy, "rev@example.com")).toEqual(["reviewer", "operator"]);
+    expect(classesOf(registry, policy, "ci@example.com")).toEqual(["runner", "reviewer"]);
+    expect(classesOf(registry, policy, "lex00")).toEqual([]);
+    expect(classesOf(registry, policy, null)).toEqual([]);
+  });
+
+  test("write scope judges a principal by the first, and human is the rest", () => {
+    expect(principalClass(policy, "rev@example.com", registry)).toBe("reviewer");
+    expect(principalClass(policy, "ci@example.com", registry)).toBe("runner");
+    expect(principalClass(policy, "lex00", registry)).toBe("human");
+    // Without the plugin's classes, a domain principal is a human (the behaviour before #3080).
+    expect(principalClass(policy, "rev@example.com")).toBe("human");
+  });
+
+  test("a writeScope key no class has is unknown", () => {
+    expect(unknownScopeClasses({ human: {}, reviewer: {}, auditor: {} }, registry)).toEqual(["auditor"]);
+    expect(unknownScopeClasses({ reviewer: {} }, coreClassRegistry())).toEqual(["reviewer"]);
+    expect(unknownScopeClasses(null, registry)).toEqual([]);
+  });
+});

package/src/workspace/principal-classes.ts

@@ -0,0 +1,307 @@
+/**
+ * Principal classes (#2524 D5; #3080, ws-079).
+ *
+ * A principal class names a set of principals so the declaration can scope
+ * what they write. Four are core: `agent`, `runner` and `service`, each the
+ * holders of the role of that name in the trust policy at base, and `human`,
+ * everyone else. A plugin adds domain classes as data, the way it adds member
+ * kinds: a JSON file at its `./workspace-principals` subpath, read through
+ * the package's `package.json` and never imported. Each class it supplies
+ * names the role whose grant puts a principal in it.
+ *
+ * A principal's classes are read only from role grants at base, through
+ * {@link classesOf}. Core classes are tried first, then the domain classes
+ * in pin order and file order; the first that holds is the class write scope
+ * judges the principal as, and `human` is the rest. A gate or a record that
+ * asks whether a principal is in a class (#3163) asks {@link classesOf},
+ * which lists every class the principal's grants put it in.
+ *
+ * A path-pinned plugin's classes are read from the base revision when the
+ * caller has it (write scope does), so a change can't remap a class by
+ * editing its own copy of the plugin. A package pin is read from the
+ * installed package, which must be at the version the base pins.
+ */
+
+import { readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { join, posix } from "node:path";
+import { kindsExportTarget, pinnedPackageDir, type KindLoadProblem, type PinLike } from "./kinds";
+import { normalisePrincipal } from "./records";
+import schema from "./workspace-principals.schema.json";
+import type { TrustPolicy } from "./trust/policy";
+import { joinPath, type WorkspaceTree } from "./tree";
+
+export const PRINCIPALS_SCHEMA_ID = schema.$id;
+
+/** The subpath a package publishes its principal classes at. */
+export const PRINCIPALS_SUBPATH = "./workspace-principals";
+
+/** The core classes, in the order a principal's roles are tried; `human` holds no role and is the rest. */
+export const CORE_PRINCIPAL_CLASSES = ["human", "agent", "runner", "service"] as const;
+export type CorePrincipalClass = (typeof CORE_PRINCIPAL_CLASSES)[number];
+
+/** A class name: a core class, or a domain class a pinned package supplies. */
+export type PrincipalClassName = string;
+
+/** The grammar of a class name, as `workspace-principals.schema.json` and the declaration's writeScope keys say it. */
+export const CLASS_NAME = /^(?!x-)[a-z][a-z0-9-]{0,39}$/;
+
+export interface PrincipalClass {
+  name: string;
+  /** One line saying who is in the class. */
+  description: string;
+  /** The role whose grant at base puts a principal in the class, or null for `human`, the rest. */
+  role: string | null;
+  /** `core`, or the pin (package name or path) that supplies the class. */
+  source: string;
+}
+
+export const CORE_CLASSES: readonly PrincipalClass[] = [
+  { name: "human", description: "a principal holding none of the roles of another class", role: null, source: "core" },
+  { name: "agent", description: "a principal holding the agent role, or a write naming an agent session", role: "agent", source: "core" },
+  { name: "runner", description: "a principal holding the runner role, such as a CI job's signing identity", role: "runner", source: "core" },
+  { name: "service", description: "a principal holding the service role", role: "service", source: "core" },
+];
+
+const CORE_ROLES = new Set(CORE_CLASSES.map((c) => c.role).filter((r): r is string => r !== null));
+
+export interface ClassRegistry {
+  get(name: string): PrincipalClass | undefined;
+  /** Every class name, core first, for "unknown class" messages. */
+  names(): string[];
+  /** Every class, core first, then the domain classes in pin order and file order. */
+  all(): readonly PrincipalClass[];
+}
+
+export function createClassRegistry(extra: readonly PrincipalClass[] = []): ClassRegistry {
+  const all = [...CORE_CLASSES, ...extra];
+  const byName = new Map(all.map((c) => [c.name, c]));
+  return {
+    get: (name) => byName.get(name),
+    names: () => all.map((c) => c.name),
+    all: () => all,
+  };
+}
+
+/** The four core classes and nothing else: what a workspace whose pins supply no class has. */
+export function coreClassRegistry(): ClassRegistry {
+  return createClassRegistry();
+}
+
+/**
+ * The role grants a class is read from. Every read of roles for a class goes
+ * through here, so where the grants live (`.chant/trust.json` today,
+ * possibly the declaration, #2547) is decided in one place: the policy.
+ */
+export function roleGrants(policy: TrustPolicy): Record<string, string[]> {
+  return policy.roles;
+}
+
+/**
+ * Every class `principal`'s role grants at base put it in, in registry order
+ * (core first). Empty for a principal in no class but `human`, and for null.
+ * Names compare as {@link normalisePrincipal} folds them.
+ */
+export function classesOf(classes: ClassRegistry, policy: TrustPolicy, principal: string | null): string[] {
+  if (principal === null) return [];
+  const name = normalisePrincipal(principal);
+  const grants = roleGrants(policy);
+  return classes
+    .all()
+    .filter((c) => c.role !== null && (grants[c.role] ?? []).some((p) => normalisePrincipal(p) === name))
+    .map((c) => c.name);
+}
+
+/** The class write scope judges `principal` as: the first class its grants put it in, or `human`. */
+export function principalClass(policy: TrustPolicy, principal: string | null, classes: ClassRegistry = coreClassRegistry()): string {
+  return classesOf(classes, policy, principal)[0] ?? "human";
+}
+
+// ── Reading a plugin's classes ───────────────────────────────────────────────
+
+interface AjvError {
+  instancePath: string;
+  message?: string;
+}
+type Validate = ((data: unknown) => boolean) & { errors?: AjvError[] | null };
+
+let compiled: Validate | undefined;
+function validator(): Validate {
+  if (compiled) return compiled;
+  const require = createRequire(import.meta.url);
+  // ajv is CommonJS; its class is the default export, or that export's own default.
+  const mod = require("ajv/dist/2020") as { default?: unknown };
+  const Ajv = (mod.default ?? mod) as new (opts: object) => { compile(s: object): Validate };
+  compiled = new Ajv({ allErrors: true, strict: true }).compile(schema);
+  return compiled;
+}
+
+export interface ClassData {
+  classes: PrincipalClass[];
+  /** Why some of the data can't be used, one line each. Empty when all of it can. */
+  problems: string[];
+}
+
+/**
+ * Check the text of a principals file against
+ * `workspace-principals.schema.json` and the rules the schema can't say: no
+ * core name or core role, and no name or role twice. `source` names the pin
+ * in the classes and in the messages.
+ */
+export function parseClassData(text: string, source: string): ClassData {
+  let raw: unknown;
+  try {
+    raw = JSON.parse(text);
+  } catch (err) {
+    return { classes: [], problems: [`${source}: the principals file is not JSON (${(err as Error).message})`] };
+  }
+  const validate = validator();
+  if (!validate(raw)) {
+    const problems = (validate.errors ?? []).map((e) => `${source}: ${e.instancePath || "the principals file"} ${e.message ?? "is invalid"}`);
+    return { classes: [], problems: [...new Set(problems)] };
+  }
+  const problems: string[] = [];
+  const classes: PrincipalClass[] = [];
+  const names = new Set<string>();
+  const roles = new Set<string>();
+  for (const c of (raw as { classes: { name: string; description: string; role: string }[] }).classes) {
+    if ((CORE_PRINCIPAL_CLASSES as readonly string[]).includes(c.name)) {
+      problems.push(`${source}: class ${c.name} is a core class and can't be supplied by a package`);
+      continue;
+    }
+    if (CORE_ROLES.has(c.role)) {
+      problems.push(`${source}: class ${c.name} names the role ${c.role}, which puts a principal in the core ${c.role} class`);
+      continue;
+    }
+    if (names.has(c.name)) {
+      problems.push(`${source}: class ${c.name} is listed twice`);
+      continue;
+    }
+    if (roles.has(c.role)) {
+      problems.push(`${source}: class ${c.name} names the role ${c.role}, which another class in the file names; a role puts a principal in one class`);
+      continue;
+    }
+    names.add(c.name);
+    roles.add(c.role);
+    classes.push({ name: c.name, description: c.description, role: c.role, source });
+  }
+  return { classes, problems };
+}
+
+/** A package's files, by a `/`-separated path inside it, or undefined when one is not there. */
+export type PackageFiles = (path: string) => string | undefined;
+
+/** A package directory on disk. */
+export function diskFiles(dir: string): PackageFiles {
+  return (path) => {
+    try {
+      return readFileSync(join(dir, ...path.split("/")), "utf-8");
+    } catch {
+      return undefined;
+    }
+  };
+}
+
+/** A package directory at `dir` in `tree`, such as the workspace at the base revision. */
+export function treeFiles(tree: WorkspaceTree, dir: string): PackageFiles {
+  return (path) => {
+    const full = joinPath(dir, path);
+    if (tree.stat(full) !== "file") return undefined;
+    try {
+      return tree.read(full);
+    } catch {
+      return undefined;
+    }
+  };
+}
+
+/** Read the classes a package publishes at `./workspace-principals`. Reads files only; imports nothing. A package that publishes none supplies none. */
+export function readPackageClasses(files: PackageFiles, source: string): ClassData {
+  const manifest = files("package.json");
+  if (manifest === undefined) return { classes: [], problems: [`${source}: no readable package.json`] };
+  let pkg: Record<string, unknown>;
+  try {
+    pkg = JSON.parse(manifest) as Record<string, unknown>;
+  } catch {
+    return { classes: [], problems: [`${source}: package.json is not JSON`] };
+  }
+  const target = kindsExportTarget(pkg, PRINCIPALS_SUBPATH);
+  if (target === undefined) return { classes: [], problems: [] };
+  if (typeof target !== "string") return { classes: [], problems: [`${source}: ${target.problem}`] };
+  const inside = posix.normalize(target.slice(2));
+  if (inside.startsWith("../") || inside === "..") return { classes: [], problems: [`${source}: exports["${PRINCIPALS_SUBPATH}"] points outside the package`] };
+  const text = files(inside);
+  if (text === undefined) return { classes: [], problems: [`${source}: exports["${PRINCIPALS_SUBPATH}"] names ${target}, which does not exist`] };
+  return parseClassData(text, source);
+}
+
+export interface LoadedClasses {
+  registry: ClassRegistry;
+  problems: KindLoadProblem[];
+}
+
+/**
+ * The classes a workspace knows: the core four plus every class its pins
+ * supply. A package pin is read from the installed package, looked up from
+ * `workspaceRoot`, and must be at the pinned version. A path pin is read
+ * through `tree` when given (the base revision, for write scope), else from
+ * `workspaceRoot` on disk, checked against its integrity digest. A class
+ * name, or a role, two pins both supply is a problem, and every class
+ * involved is left out, so a writeScope entry for it reads as unknown and
+ * fails closed. Never throws.
+ */
+export function loadClassRegistry(pins: readonly PinLike[], workspaceRoot: string, opts: { tree?: WorkspaceTree } = {}): LoadedClasses {
+  const problems: KindLoadProblem[] = [];
+  const extra: PrincipalClass[] = [];
+  const byName = new Map<string, string>();
+  const byRole = new Map<string, string>();
+  const clashing = new Set<string>();
+  pins.forEach((pin, i) => {
+    let files: PackageFiles;
+    let source: string;
+    if (pin.path && opts.tree) {
+      files = treeFiles(opts.tree, pin.path);
+      source = pin.path;
+    } else {
+      const found = pinnedPackageDir(pin, workspaceRoot);
+      if (found === null) return;
+      if ("problem" in found) {
+        problems.push({ pin: i, message: found.problem });
+        return;
+      }
+      files = diskFiles(found.dir);
+      source = found.source;
+    }
+    const read = readPackageClasses(files, source);
+    for (const p of read.problems) problems.push({ pin: i, message: p });
+    for (const c of read.classes) {
+      const named = byName.get(c.name);
+      const roled = byRole.get(c.role!);
+      if (named !== undefined || roled !== undefined) {
+        clashing.add(c.name);
+        if (named !== undefined) {
+          problems.push({ pin: i, message: `class ${c.name} is supplied by both ${named} and ${source}; a class name has one source` });
+        } else {
+          const other = extra.find((e) => e.role === c.role)!;
+          clashing.add(other.name);
+          problems.push({ pin: i, message: `class ${c.name} (${source}) names the role ${c.role}, which class ${other.name} (${roled}) names; a role puts a principal in one class` });
+        }
+        continue;
+      }
+      byName.set(c.name, source);
+      byRole.set(c.role!, source);
+      extra.push(c);
+    }
+  });
+  // A name or role two pins both supply is left out altogether: neither reading is safe.
+  return { registry: createClassRegistry(extra.filter((c) => !clashing.has(c.name))), problems };
+}
+
+/**
+ * The writeScope keys no class in `classes` has, in file order. A writer
+ * judged `human` may be in such a class, since nothing says which role puts
+ * a principal in it, so write scope refuses that writer (fail closed).
+ */
+export function unknownScopeClasses(writeScope: Record<string, unknown> | null, classes: ClassRegistry): string[] {
+  return Object.keys(writeScope ?? {}).filter((name) => classes.get(name) === undefined);
+}

package/src/workspace/profiles.test.ts

@@ -0,0 +1,159 @@
+/**
+ * #3174, ws-096: factory fields are opt-in, and the reference workspace ships
+ * three profiles (ideation, app, infra) that `chant workspace init --profile`
+ * copies. A records-only workspace, an infra workspace with no factory and an
+ * infra workspace whose factory has no app member and no box services all
+ * pass `chant workspace check`, and so does a copy of each profile.
+ */
+
+import { execFileSync, spawnSync } from "node:child_process";
+import { mkdtempSync, readdirSync, readFileSync, realpathSync, rmSync, statSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, relative } from "node:path";
+import { afterAll, describe, expect, test } from "vitest";
+import { REPO, repo } from "./__fixtures__/contract-repo";
+import { plantability } from "./box-factory";
+import { runDeclarationChecks } from "./checks";
+import { readDeclaration } from "./declaration";
+import { PROFILES, PROFILES_DIR, profileSource } from "./init";
+import { initFromCommand } from "./lineage-init";
+import { workingTree } from "./tree";
+
+const scratch: string[] = [];
+afterAll(() => {
+  for (const d of scratch) rmSync(d, { recursive: true, force: true });
+});
+
+const REFERENCE = join(REPO, "reference-workspace");
+const CHANT = join(REPO, "packages", "core", "bin", "chant");
+
+/** Every file under `dir`, relative to it, sorted. */
+function files(dir: string): string[] {
+  const out: string[] = [];
+  const walk = (at: string) => {
+    for (const name of readdirSync(at)) {
+      const p = join(at, name);
+      if (statSync(p).isDirectory()) walk(p);
+      else out.push(relative(dir, p));
+    }
+  };
+  walk(dir);
+  return out.sort();
+}
+
+/** The errors `chant workspace check` reports, as `<id>:<entity>: <message>`. */
+async function errors(root: string): Promise<string[]> {
+  const report = await runDeclarationChecks(root);
+  return report.diagnostics.filter((d) => d.severity === "error").map((d) => `${d.ruleId}:${d.entity ?? ""}: ${d.message}`);
+}
+
+/** A copy of a profile, made the way `chant workspace init --profile` makes it, from this checkout. */
+async function copyOf(profile: string): Promise<string> {
+  const dir = realpathSync(mkdtempSync(join(tmpdir(), `chant-3174-${profile}-`)));
+  scratch.push(dir);
+  const made = await initFromCommand({ from: `${REPO}#${PROFILES_DIR}/${profile}`, path: dir, params: profile === "infra" ? {} : { name: "Fern" } });
+  expect(made.success, made.error).toBe(true);
+  execFileSync("git", ["init", "-q"], { cwd: dir });
+  return dir;
+}
+
+describe("factory fields are opt-in (#3174)", () => {
+  test("a records-only workspace passes check, with no member, box or factory", async () => {
+    const root = repo({
+      "chant.workspace.json": JSON.stringify({ name: "notes", schema: 1, members: [], records: [{ kind: "decisions/decision.kind.mjs" }] }, null, 2),
+      "decisions/decision.kind.mjs": readFileSync(join(REFERENCE, "decisions", "decision.kind.mjs"), "utf-8"),
+      "decisions/decision.schema.json": readFileSync(join(REFERENCE, "decisions", "decision.schema.json"), "utf-8"),
+    });
+    expect(await errors(root)).toEqual([]);
+  });
+
+  test("an infra workspace with no factory passes check", async () => {
+    const root = repo({
+      "chant.workspace.json": JSON.stringify({ name: "estate", schema: 1, members: [{ name: "network", dir: "network", kind: "chant" }] }, null, 2),
+      "network/chant.config.json": '{ "lexicons": ["terraform"] }\n',
+    });
+    expect(await errors(root)).toEqual([]);
+  });
+
+  test("an infra workspace whose factory builds an estate member, with no app member and no box services, passes check and isn't plantable", async () => {
+    const declaration = {
+      name: "estate",
+      schema: 1,
+      members: [{ name: "network", dir: "network", kind: "chant", box: { factory: { builds: ["network"], check: { run: "chant lint", kind: "lint" } } } }],
+    };
+    const root = repo({ "chant.workspace.json": JSON.stringify(declaration, null, 2), "network/chant.config.json": '{ "lexicons": ["terraform"] }\n' });
+    expect(await errors(root)).toEqual([]);
+    expect(plantability(readDeclaration(workingTree(root), "")).reason?.code).toBe("box-none");
+  });
+});
+
+describe("the reference workspace's profiles (#3174)", () => {
+  test("are ideation, app and infra, each a template directory with a declaration", () => {
+    expect(readdirSync(join(REPO, PROFILES_DIR)).sort()).toEqual([...PROFILES].sort());
+  });
+
+  test("carry the reference workspace's own record kinds and app kind, byte for byte", () => {
+    for (const profile of PROFILES) {
+      const dir = join(REPO, PROFILES_DIR, profile);
+      for (const f of files(dir).filter((p) => /^(decisions|work|answers|kinds)\//.test(p))) {
+        expect(readFileSync(join(dir, f), "utf-8"), `${profile}/${f}`).toBe(readFileSync(join(REFERENCE, f), "utf-8"));
+      }
+    }
+  });
+
+  test("ideation: records and a stub app of the app kind, no box and no factory, and check passes", async () => {
+    const root = await copyOf("ideation");
+    expect(await errors(root)).toEqual([]);
+    const d = readDeclaration(workingTree(root), "");
+    expect(d.members.map((m) => `${m.name}:${m.kind}`)).toEqual(["app:app"]);
+    expect(d.members.every((m) => m.box === null)).toBe(true);
+    expect(d.records.map((r) => r.kind)).toEqual(["decisions/decision.kind.mjs", "work/work.kind.mjs", "answers/answer.kind.mjs"]);
+    expect(readFileSync(join(root, "app", "server.mjs"), "utf-8")).toContain('NAME = "Fern"');
+  });
+
+  test("app: the app member runs as the box's service and the factory builds it, and check passes", async () => {
+    const root = await copyOf("app");
+    expect(await errors(root)).toEqual([]);
+    const d = readDeclaration(workingTree(root), "");
+    expect(plantability(d)).toMatchObject({ plantable: true, box: "app" });
+    expect(d.members[0].box?.factory?.builds).toEqual(["app"]);
+  });
+
+  test("infra: an estate member and a factory, no app member and no box services, and check passes", async () => {
+    const root = await copyOf("infra");
+    expect(await errors(root)).toEqual([]);
+    const d = readDeclaration(workingTree(root), "");
+    expect(d.members.map((m) => `${m.name}:${m.kind}`)).toEqual(["network:chant"]);
+    expect(d.members[0].box?.factory?.check).toEqual({ run: "cd network && npx chant lint && npx chant build", kind: "lint" });
+    expect(d.members[0].box?.services).toEqual([]);
+    expect(d.pins).toEqual([]);
+  });
+});
+
+describe("chant workspace init --profile (#3174)", () => {
+  test("reads the profile from the chant repository at this chant's tag, or from --from", () => {
+    expect(profileSource("app", undefined, "0.103.0")).toBe("https://github.com/INTENTIUS/chant@chant-v0.103.0#reference-workspace/profiles/app");
+    expect(profileSource("infra", "/src/chant", "0.103.0")).toBe("/src/chant#reference-workspace/profiles/infra");
+  });
+
+  test("copies the profile with a lineage lock and names the workspace", () => {
+    const dir = realpathSync(mkdtempSync(join(tmpdir(), "chant-3174-cli-")));
+    scratch.push(dir);
+    const run = spawnSync(CHANT, ["workspace", "init", dir, "--profile", "ideation", "--from", REPO, "--name", "fern", "--param", "name=Fern", "--yes"], { encoding: "utf-8" });
+    expect(run.status, run.stderr).toBe(0);
+    expect(JSON.parse(readFileSync(join(dir, "chant.workspace.json"), "utf-8")).name).toBe("fern");
+    expect(readdirSync(join(dir, ".chant"))).toContain("workspace.lock.json");
+  });
+
+  test("names the profiles when given another, and writes nothing without --yes", () => {
+    const dir = realpathSync(mkdtempSync(join(tmpdir(), "chant-3174-cli-")));
+    scratch.push(dir);
+    const bad = spawnSync(CHANT, ["workspace", "init", dir, "--profile", "web"], { encoding: "utf-8" });
+    expect(bad.status).toBe(1);
+    expect(bad.stderr).toMatch(/the profiles are ideation, app, infra/);
+    const dry = spawnSync(CHANT, ["workspace", "init", dir, "--profile", "infra", "--from", REPO], { encoding: "utf-8", input: "" });
+    expect(dry.status).toBe(0);
+    expect(dry.stdout).toMatch(/Nothing written/);
+    expect(readdirSync(dir)).toEqual([]);
+  });
+});

package/src/workspace/read-contract.test.ts

@@ -215,7 +215,7 @@ describe("every schema against the reference workspace (#2543)", () => {
         expect(doc.components[0].runtimes).toEqual([{ name: "local", lexicon: null, default: true, command: "chant run --components app" }]);
         expect(doc.members.find((m) => m.name === "delivery")!.runtimeReasons).toEqual([]);
         // #2695: the reference config declares no environments, so the app deploys to local only.
-        expect(doc.components[0].environments).toEqual([{ name: "local", default: true, source: "builtin", command: "chant run --components app" }]);
+        expect(doc.components[0].environments).toEqual([{ name: "local", default: true, source: "builtin", site: null, command: "chant run --components app" }]);
         expect(doc.members.find((m) => m.name === "delivery")!.environmentReasons.map((r) => r.code)).toEqual(["environments-none-declared"]);
         expect(doc.reasons).toEqual([]);
       }
@@ -244,7 +244,7 @@ describe("every schema against the reference workspace (#2543)", () => {
       const doc = await workspacePoints({ cwd: FIXTURE, at });
       expectValid(doc);
       if ("error" in doc) throw new Error(doc.error.message);
-      expect(doc.points.map((p) => p.name)).toEqual(["slice-tier", "ship-skip", "finding-triage", "needs-a-decision"]);
+      expect(doc.points.map((p) => p.name)).toEqual(["slice-tier", "understand", "ship-skip", "finding-triage", "needs-a-decision", "intent-origin", "intent-judgment", "intent-disposition", "agent-question"]);
       const sliceTier = doc.points.find((p) => p.name === "slice-tier")!;
       expect(sliceTier.criteria).toEqual({
         small: "A haiku-class builder. The work item fits the small limits.",