@intentius/chant 0.101.0 → 0.104.0

package/src/workspace/identity.test.ts

@@ -0,0 +1,219 @@
+/**
+ * #3163, ws-080: person-attributed records and gate approvals rest on a forge
+ * identity or a signer key, and a gate the declaration names passes only on a
+ * signed approval from its class.
+ */
+
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { afterEach, describe, expect, test } from "vitest";
+import { parseDeclaration, type Declaration } from "./declaration";
+import { forgePrincipal, gateAdmissionFrom, identify, IdentityError, parseForgeIdentity, refuseUnidentified } from "./identity";
+import { createClassRegistry, coreClassRegistry } from "./principal-classes";
+import { reviewRecord } from "./records-write";
+import { answerPoint } from "./decide";
+import { gatesInLedger } from "./status-gates";
+import { emptyPolicy, type TrustPolicy } from "./trust/policy";
+import { sealGateApproval } from "./trust/seal";
+import { hasSshKeygen, TestRepo, type Key } from "./trust/test-repo";
+import { evaluateGate, memoryGateLedgerPort } from "../op/gate";
+import type { GateResolutionRecord, PendingGateRecord } from "../lifecycle/gate-ledger";
+
+const decl = (identity: unknown): Declaration =>
+  parseDeclaration(JSON.stringify({ name: "acme", schema: 1, members: [], identity }), "chant.workspace.json", "0.102.0");
+
+const policyWith = (signers: { principal: string; key: string }[], roles: Record<string, string[]> = {}): TrustPolicy => ({
+  ...emptyPolicy("0".repeat(40)),
+  active: true,
+  signers: signers.map((s, i) => ({ ...s, line: i + 1 })),
+  roles,
+});
+
+const repos: TestRepo[] = [];
+afterEach(() => {
+  while (repos.length) repos.pop()!.cleanup();
+});
+
+describe("forge identities", () => {
+  test("github and gitlab name their own host; forgejo and gitea name one", () => {
+    expect(parseForgeIdentity("github:Alice")).toEqual({ forge: "github", host: "github.com", login: "alice" });
+    expect(parseForgeIdentity("gitlab:a.b_c")).toEqual({ forge: "gitlab", host: "gitlab.com", login: "a.b_c" });
+    expect(parseForgeIdentity("forgejo@codeberg.org:bob")).toEqual({ forge: "forgejo", host: "codeberg.org", login: "bob" });
+    expect(parseForgeIdentity("github@ghe.example.com:carol")).toEqual({ forge: "github", host: "ghe.example.com", login: "carol" });
+    expect(parseForgeIdentity("forgejo:bob")).toBeNull();
+    expect(parseForgeIdentity("alice")).toBeNull();
+    expect(parseForgeIdentity("alice@example.com")).toBeNull();
+    expect(parseForgeIdentity("github:")).toBeNull();
+    expect(parseForgeIdentity("bitbucket:alice")).toBeNull();
+    expect(forgePrincipal({ forge: "github", host: "github.com", login: "alice" })).toBe("github:alice");
+    expect(forgePrincipal({ forge: "forgejo", host: "codeberg.org", login: "bob" })).toBe("forgejo@codeberg.org:bob");
+  });
+
+  test("a principal is a signer, a forge identity, a role holder or a name", () => {
+    const policy = policyWith([{ principal: "github:alice", key: "ssh-ed25519 AAAA" }, { principal: "dana@example.test", key: "ssh-ed25519 BBBB" }], { runner: ["ci-bot"] });
+    expect(identify("GitHub:Alice", policy).form).toBe("signer");
+    expect(identify("dana@example.test", policy).form).toBe("signer");
+    expect(identify("github:bob", policy).form).toBe("forge");
+    expect(identify("ci-bot", policy).form).toBe("role");
+    expect(identify("alex", policy).form).toBe("name");
+    const d = parseDeclaration(
+      JSON.stringify({ name: "acme", schema: 1, members: [{ name: "app", dir: "app", kind: "chant" }], agents: [{ name: "builder", member: "app", principals: ["builder-bot"] }] }),
+      "chant.workspace.json",
+      "0.102.0",
+    );
+    expect(identify("builder-bot", emptyPolicy(null), d).form).toBe("role");
+  });
+});
+
+describe("identity.attribution", () => {
+  test("parses, and defaults to any", () => {
+    expect(decl({}).identity).toEqual({ attribution: "any", gates: {} });
+    expect(decl({ attribution: "identified", gates: { ship: { class: "operator" }, rollback: {} } }).identity).toEqual({
+      attribution: "identified",
+      gates: {
+        ship: { gate: "ship", class: "operator", pointer: "/identity/gates/ship" },
+        rollback: { gate: "rollback", class: null, pointer: "/identity/gates/rollback" },
+      },
+    });
+    expect(() => decl({ attribution: "verified" })).toThrow();
+    expect(() => decl({ gates: { ship: { by: "x" } } })).toThrow();
+  });
+
+  test("identified refuses a bare name and takes a forge identity or a signer", () => {
+    const source = { declaration: decl({ attribution: "identified" }), policy: policyWith([{ principal: "dana@example.test", key: "ssh-ed25519 AAAA" }]) };
+    expect(() => refuseUnidentified(source, ["github:alice", "dana@example.test"], "--by")).not.toThrow();
+    expect(() => refuseUnidentified(source, ["github:alice", "alex"], "--by")).toThrow(IdentityError);
+    // any, or no identity block, keeps every name: hud's roster names still work there.
+    expect(() => refuseUnidentified({ ...source, declaration: decl({}) }, ["alex"], "--by")).not.toThrow();
+    expect(() => refuseUnidentified({ ...source, declaration: null }, ["alex"], "--by")).not.toThrow();
+  });
+
+  test.skipIf(!hasSshKeygen)("records review and points answer refuse a roster name under identified at base", async () => {
+    const r = new TestRepo("identity-review");
+    repos.push(r);
+    const DECISIONS = join(import.meta.dirname, "..", "..", "..", "..", "docs", "design", "decisions");
+    r.write("decisions/decision.kind.mjs", readFileSync(join(DECISIONS, "decision.kind.mjs"), "utf-8"));
+    r.write("decisions/decision.schema.json", readFileSync(join(DECISIONS, "decision.schema.json"), "utf-8"));
+    r.write("decisions/ws-003-seal-scope.md", readFileSync(join(DECISIONS, "ws-003-seal-scope.md"), "utf-8"));
+    r.write("chant.workspace.json", JSON.stringify({ name: "acme", schema: 1, members: [], identity: { attribution: "identified" } }));
+    r.commit("base");
+    r.git(["checkout", "-q", "-b", "change"]);
+    const kind = "decisions/decision.kind.mjs";
+    const refused = await reviewRecord({ kind, id: "ws-003", verdict: "agree", by: "alex", cwd: r.dir, on: "2026-10-03", dryRun: true });
+    expect("error" in refused && refused.error.code).toBe("principal-unidentified");
+    const taken = await reviewRecord({ kind, id: "ws-003", verdict: "agree", by: "github:alex", cwd: r.dir, on: "2026-10-03", dryRun: true });
+    expect("error" in taken ? taken.error : null).toBeNull();
+    const answer = await answerPoint({ id: "P-1", answer: "yes", by: ["alex"], cwd: r.dir });
+    expect("error" in answer && answer.error.code).toBe("principal-unidentified");
+  });
+});
+
+describe.skipIf(!hasSshKeygen)("identity.gates", () => {
+  function keys(): { r: TestRepo; alice: Key; bob: Key; mallory: Key } {
+    const r = new TestRepo("identity-gates");
+    repos.push(r);
+    return { r, alice: r.key("alice"), bob: r.key("bob"), mallory: r.key("mallory") };
+  }
+
+  const approval = (resolvedBy: string, extra: Partial<GateResolutionRecord> = {}): GateResolutionRecord => ({
+    version: 1,
+    op: "web",
+    gate: "ship",
+    environment: "prod",
+    planDigest: "sha256:" + "a".repeat(64),
+    resolvedBy,
+    timestamp: "2026-10-03T12:00:00.000Z",
+    ...extra,
+  });
+  const signed = (key: Key, a: GateResolutionRecord): GateResolutionRecord => ({ ...a, seal: sealGateApproval(key.file, a) });
+
+  test("counts only an approval sealed by a listed signer in the class", () => {
+    const { alice, bob, mallory } = keys();
+    const policy = policyWith(
+      [
+        { principal: "github:alice", key: alice.pub },
+        { principal: "github:bob", key: bob.pub },
+      ],
+      { operator: ["github:alice"] },
+    );
+    const classes = createClassRegistry([{ name: "operator", description: "operators", role: "operator", source: "plugins/ops" }]);
+    const rule = gateAdmissionFrom({ declaration: decl({ gates: { ship: { class: "operator" } } }), policy, classes }, "ship")!;
+    expect(rule.requirement.class).toBe("operator");
+    expect(gateAdmissionFrom({ declaration: decl({ gates: { ship: {} } }), policy, classes }, "rollout")).toBeNull();
+
+    expect(rule.refuses(signed(alice, approval("github:alice")))).toBeNull();
+    // A hud roster name or an unsigned forge identity can't clear it.
+    expect(rule.refuses(approval("alex"))).toMatch(/not signed/);
+    expect(rule.refuses(approval("github:alice"))).toMatch(/not signed/);
+    // Signed by a listed signer outside the class.
+    expect(rule.refuses(signed(bob, approval("github:bob")))).toMatch(/not in the class operator/);
+    // Someone else's key under alice's name.
+    expect(rule.refuses(signed(mallory, approval("github:alice")))).toMatch(/does not verify/);
+    // A seal over another plan doesn't carry over.
+    const moved = { ...signed(alice, approval("github:alice")), planDigest: "sha256:" + "b".repeat(64) };
+    expect(rule.refuses(moved)).toMatch(/does not verify/);
+
+    // Any listed signer, when the rule names no class.
+    const anySigner = gateAdmissionFrom({ declaration: decl({ gates: { ship: {} } }), policy, classes }, "ship")!;
+    expect(anySigner.refuses(signed(bob, approval("github:bob")))).toBeNull();
+    // A class no pinned package supplies lets nothing through.
+    const unknown = gateAdmissionFrom({ declaration: decl({ gates: { ship: { class: "operator" } } }), policy, classes: coreClassRegistry() }, "ship")!;
+    expect(unknown.refuses(signed(alice, approval("github:alice")))).toMatch(/no pinned package supplies/);
+  });
+
+  test("a relayed approval: the seal covers relayedBy, and status lists it (#3402)", () => {
+    const { alice } = keys();
+    const policy = policyWith([{ principal: "github:alice", key: alice.pub }]);
+    const rule = gateAdmissionFrom({ declaration: decl({ gates: { ship: {} } }), policy, classes: coreClassRegistry() }, "ship")!;
+    const relayed = signed(alice, approval("github:alice", { relayedBy: "github:hud-follower" }));
+    expect(rule.refuses(relayed)).toBeNull();
+    // The relay can't be changed, dropped or added after sealing.
+    expect(rule.refuses({ ...relayed, relayedBy: "github:mallory" })).toMatch(/does not verify/);
+    const { relayedBy: _dropped, ...unrelayed } = relayed;
+    expect(rule.refuses(unrelayed)).toMatch(/does not verify/);
+    expect(rule.refuses({ ...signed(alice, approval("github:alice")), relayedBy: "github:hud-follower" })).toMatch(/does not verify/);
+    // A seal made before #3402, with no relay, still verifies.
+    expect(rule.refuses(signed(alice, approval("github:alice")))).toBeNull();
+
+    const pending: PendingGateRecord = { version: 1, kind: "pending", op: "web", gate: "ship", environment: "prod", planDigest: "sha256:" + "a".repeat(64), timestamp: "2026-10-03T11:00:00.000Z", expiresAt: "2026-10-10T11:00:00.000Z" };
+    const ledger = [pending, relayed, approval("bob")].map((l) => JSON.stringify(l)).join("\n");
+    const gate = gatesInLedger("web", ledger, ["prod"], "2026-10-03T13:00:00.000Z").gates[0];
+    expect(gate.approvals).toEqual([
+      { principal: "github:alice", channel: null, relayedBy: "github:hud-follower", at: "2026-10-03T12:00:00.000Z" },
+      { principal: "bob", channel: null, relayedBy: null, at: "2026-10-03T12:00:00.000Z" },
+    ]);
+  });
+
+  test("a run and workspace status leave out approvals the rule refuses", async () => {
+    const { alice } = keys();
+    const policy = policyWith([{ principal: "github:alice", key: alice.pub }]);
+    const rule = gateAdmissionFrom({ declaration: decl({ gates: { ship: {} } }), policy, classes: coreClassRegistry() }, "ship")!;
+    const pending: PendingGateRecord = {
+      version: 1,
+      kind: "pending",
+      op: "web",
+      gate: "ship",
+      environment: "prod",
+      planDigest: "sha256:" + "a".repeat(64),
+      timestamp: "2026-10-03T11:00:00.000Z",
+      expiresAt: "2026-10-10T11:00:00.000Z",
+    };
+    const input = { op: "web", gate: "ship", environment: "prod", planDigest: pending.planDigest, now: "2026-10-03T13:00:00.000Z" };
+
+    const roster = memoryGateLedgerPort({ pending: [pending], resolutions: [approval("alex")] });
+    expect((await evaluateGate(roster, input)).satisfied).toBe(true);
+    expect((await evaluateGate({ ...roster, approvalRule: async () => rule }, input)).satisfied).toBe(false);
+    const sealed = memoryGateLedgerPort({ pending: [pending], resolutions: [approval("alex"), signed(alice, approval("github:alice"))] });
+    const check = await evaluateGate({ ...sealed, approvalRule: async () => rule }, input);
+    expect(check.satisfied && check.resolution.resolvedBy).toBe("github:alice");
+
+    const ledger = [pending, approval("alex")].map((l) => JSON.stringify(l)).join("\n");
+    const open = gatesInLedger("web", ledger, ["prod"], "2026-10-03T13:00:00.000Z", (g) => (g === "ship" ? rule : null)).gates[0];
+    expect(open.state).toBe("pending");
+    expect(open.signed).toEqual({ class: null });
+    expect(open.approve).toMatch(/--sign$/);
+    const plain = gatesInLedger("web", ledger, ["prod"], "2026-10-03T13:00:00.000Z").gates[0];
+    expect(plain.state).toBe("approved");
+    expect(plain.signed).toBeNull();
+  });
+});

package/src/workspace/identity.ts

@@ -0,0 +1,186 @@
+/**
+ * Who a person-attributed record or gate approval names (#3163, ws-080).
+ *
+ * chant never authenticates a person (ws-052): hud, studio or behold signs a
+ * person in and maps the session to one of the identities below, then passes
+ * it to chant's write commands (`--by`, `--actor`). chant records what it is
+ * given and says which form it is:
+ *
+ * - `signer`: a principal `.chant/allowed_signers` lists at base. A seal made
+ *   with that principal's key (`--sign`) attests it.
+ * - `forge`: a forge identity, `github:<login>`, `gitlab:<login>`, or
+ *   `<forge>@<host>:<login>` (forgejo, gitea, or a self-hosted github or
+ *   gitlab). The surface that signed the person in vouches for it; nothing
+ *   here checks it, and only a seal verified against the signers at base
+ *   attests it. The signers file and the role grants name people this way, so
+ *   one string is the person in the record, the key list and the classes.
+ * - `role`: a principal holding the agent, runner or service role at base, or
+ *   listed by a declared agent session: not a person, and named by a grant an
+ *   admin controls.
+ * - `name`: anything else, such as a hud roster name or `$USER`.
+ *
+ * The declaration's `identity` block, read at base, turns this into rules:
+ * `attribution: "identified"` refuses a `name` on every person-attributed
+ * write, and `gates.<gate>` lets a gate of that name pass only on an approval
+ * sealed by a signer, from a class when it names one.
+ */
+
+import type { Declaration, SignedGate } from "./declaration";
+import { classesOf, coreClassRegistry, principalClass, type ClassRegistry } from "./principal-classes";
+import type { ReasonCode } from "./reason-codes";
+import { normalisePrincipal } from "./records";
+import type { TrustPolicy } from "./trust/policy";
+import { checkGateSeal, type SealedGateApproval } from "./trust/seal";
+import { scopeSource } from "./write-scope";
+
+/** The forges a forge identity can name. */
+export const FORGES = ["github", "gitlab", "forgejo", "gitea"] as const;
+export type Forge = (typeof FORGES)[number];
+
+/** The host a forge identity means when it names none. Forgejo and gitea have no default: name the host. */
+const DEFAULT_HOST: Record<Forge, string | null> = { github: "github.com", gitlab: "gitlab.com", forgejo: null, gitea: null };
+
+/** A person's account on a forge. */
+export interface ForgeIdentity {
+  forge: Forge;
+  /** Lower-cased, such as `github.com` or `codeberg.org`. */
+  host: string;
+  /** Lower-cased: the forges compare logins without case. */
+  login: string;
+}
+
+const LABEL = "[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?";
+const FORGE_PRINCIPAL = new RegExp(`^(${FORGES.join("|")})(?:@(${LABEL}(?:\\.${LABEL})+))?:([a-z0-9](?:[a-z0-9._-]{0,98}[a-z0-9_])?)$`);
+
+/**
+ * Read `principal` as a forge identity, or null when it is not one. Case and
+ * surrounding space are folded as {@link normalisePrincipal} folds them.
+ */
+export function parseForgeIdentity(principal: string): ForgeIdentity | null {
+  const m = FORGE_PRINCIPAL.exec(normalisePrincipal(principal));
+  if (!m) return null;
+  const forge = m[1] as Forge;
+  const host = m[2] ?? DEFAULT_HOST[forge];
+  if (host === null) return null;
+  return { forge, host, login: m[3] };
+}
+
+/** The principal string of a forge identity: `<forge>:<login>` on the forge's default host, else `<forge>@<host>:<login>`. */
+export function forgePrincipal(id: ForgeIdentity): string {
+  return id.host === DEFAULT_HOST[id.forge] ? `${id.forge}:${id.login}` : `${id.forge}@${id.host}:${id.login}`;
+}
+
+export type IdentityForm = "signer" | "forge" | "role" | "name";
+
+export interface Identified {
+  principal: string;
+  form: IdentityForm;
+  /** Set whenever the principal reads as a forge identity, whatever its form. */
+  forge: ForgeIdentity | null;
+}
+
+const NON_PERSON_CLASSES = new Set(["agent", "runner", "service"]);
+
+/**
+ * What `principal` is, under the policy and declaration read at base. A
+ * principal the signers file lists is a `signer` even when it is also a
+ * forge identity, since a seal can attest it.
+ */
+export function identify(principal: string, policy: TrustPolicy, declaration: Declaration | null = null): Identified {
+  const name = normalisePrincipal(principal);
+  const forge = parseForgeIdentity(principal);
+  if (policy.active && policy.signers.some((s) => normalisePrincipal(s.principal) === name)) return { principal, form: "signer", forge };
+  if (forge) return { principal, form: "forge", forge };
+  const session = (declaration?.agents ?? []).some((a) => a.principals.some((p) => normalisePrincipal(p) === name));
+  if (session || classesOf(coreClassRegistry(), policy, principal).some((c) => NON_PERSON_CLASSES.has(c))) return { principal, form: "role", forge: null };
+  return { principal, form: "name", forge: null };
+}
+
+/** Why a write naming a person was refused. Closed. */
+export const IDENTITY_CODES = ["principal-unidentified"] as const satisfies readonly ReasonCode[];
+export type IdentityCode = (typeof IDENTITY_CODES)[number];
+
+export class IdentityError extends Error {
+  readonly code: IdentityCode = "principal-unidentified";
+  constructor(message: string) {
+    super(message);
+    this.name = "IdentityError";
+  }
+}
+
+/** What {@link refuseUnidentified} reads: the declaration and policy at base, as `scopeSource` gives them. */
+export interface IdentitySource {
+  declaration: Declaration | null;
+  policy: TrustPolicy;
+}
+
+/**
+ * Refuse a person-attributed write that names someone by a bare name, when
+ * the declaration at base sets `identity.attribution` to `identified`.
+ * `flag` names where the name came from (`--by`, `--actor`). A write in a
+ * declared agent session (`CHANT_AGENT`) names the session, not a person,
+ * and is not judged here. Throws an {@link IdentityError}.
+ */
+export function refuseUnidentified(source: IdentitySource, names: readonly string[], flag: string, opts: { agent?: string | null } = {}): void {
+  if (source.declaration?.identity?.attribution !== "identified") return;
+  if (opts.agent !== undefined && opts.agent !== null && source.declaration.agents.some((a) => a.name === opts.agent)) return;
+  for (const name of names) {
+    if (identify(name, source.policy, source.declaration).form !== "name") continue;
+    throw new IdentityError(
+      `${flag} ${JSON.stringify(name)} names no identity the workspace can check: chant.workspace.json at base sets identity.attribution to identified, so a person is named by a forge identity (github:<login>, gitlab:<login>, or <forge>@<host>:<login>) or by a principal ${source.policy.signersPath} lists at base`,
+    );
+  }
+}
+
+/** A gate approval as the rule judges it: the resolution line's own fields. */
+export type GateApprovalLike = SealedGateApproval;
+
+/** A gate the declaration names in `identity.gates`, and the judge for its approvals. */
+export interface GateAdmission {
+  requirement: SignedGate;
+  /** Why `approval` doesn't count toward the gate, or null when it does. */
+  refuses(approval: GateApprovalLike): string | null;
+}
+
+/** What {@link gateAdmissionFrom} reads: the declaration, policy and classes at base, as `scopeSource` gives them. */
+export interface GateRuleSource extends IdentitySource {
+  classes: ClassRegistry;
+}
+
+/**
+ * The rule for `gate`, or null when the declaration at base names none. An
+ * approval counts only when its seal verifies for its approver against the
+ * signers at base and, when the rule names a class, the approver's role
+ * grants at base put it in that class. A class no pinned package supplies
+ * lets nothing through.
+ */
+export function gateAdmissionFrom(source: GateRuleSource, gate: string): GateAdmission | null {
+  const requirement = source.declaration?.identity?.gates[gate];
+  if (!requirement) return null;
+  const { policy, classes } = source;
+  return {
+    requirement,
+    refuses(a) {
+      const want = requirement.class;
+      if (want !== null && classes.get(want) === undefined) {
+        return `identity.gates.${gate} names the class ${want}, which no pinned package supplies, so no approval can show it is in that class (known classes: ${classes.names().join(", ")})`;
+      }
+      if (!policy.active) return `gate ${gate} needs a signed approval, and there is no signers file (${policy.signersPath}) at base to check one against`;
+      const seal = checkGateSeal(policy, a);
+      if (seal.attested !== true) return a.seal === undefined || a.seal === null ? `the approval by ${a.resolvedBy} is not signed; gate ${gate} needs chant approve --sign` : seal.message;
+      if (want === null) return null;
+      const inClass = want === "human" ? principalClass(policy, a.resolvedBy, classes) === "human" : classesOf(classes, policy, a.resolvedBy).includes(want);
+      return inClass ? null : `${a.resolvedBy} is not in the class ${want} that gate ${gate} needs: no role grant at base puts them there`;
+    },
+  };
+}
+
+/**
+ * The rule for `gate` in the workspace holding `cwd`, read at base (the
+ * target branch tip), or null when there is no declaration or it names none.
+ * What a run, `chant approve` and `workspace status` ask before counting an
+ * approval.
+ */
+export function gateAdmission(cwd: string, gate: string): GateAdmission | null {
+  return gateAdmissionFrom(scopeSource(cwd), gate);
+}

package/src/workspace/init.ts

@@ -21,10 +21,18 @@
  *   never written.
  *
  * Nothing here runs project code: it reads file names and package.json files.
+ *
+ * `--profile ideation|app|infra` starts a workspace from one of the reference
+ * workspace's profiles instead (#3174, ws-096): records only with a stub app,
+ * an app with its factory, or an estate with a factory and no app. It is
+ * `chant init --from` on `reference-workspace/profiles/<profile>` of the chant
+ * repository at this chant's release tag, or of the repository or directory
+ * `--from` names, so the new workspace gets a lineage lock and can be upgraded
+ * like any template copy.
  */
 
 import { execFileSync } from "node:child_process";
-import { existsSync, readdirSync, writeFileSync } from "node:fs";
+import { existsSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
 import { basename, join, resolve } from "node:path";
 import { formatError, formatSuccess } from "../cli/format";
 import type { CommandContext } from "../cli/registry";
@@ -36,12 +44,34 @@ import {
   rootExclusions,
   WorkspaceReadError,
   isInside,
+  readerVersion,
 } from "./declaration";
 import { expandGlob } from "./glob";
+import { setProperty } from "./json-edit";
 import { holdsChantProject } from "./kinds";
 import { gitTop, skippedDir, workingTree, type WorkspaceTree } from "./tree";
 
-const USAGE = "chant workspace init [dir] [--name <name>] [--yes] [--verbose]";
+const USAGE = "chant workspace init [dir] [--name <name>] [--yes] [--verbose]\n       chant workspace init --profile ideation|app|infra [dir] [--name <name>] [--param name=<display name>] [--from <repo>@<ref>|<chant checkout>] [--yes]";
+
+/** The profiles `--profile` takes (#3174), each a directory under {@link PROFILES_DIR} in the chant repository. */
+export const PROFILES = ["ideation", "app", "infra"] as const;
+export type Profile = (typeof PROFILES)[number];
+
+/** Where the profiles live in the chant repository. */
+export const PROFILES_DIR = "reference-workspace/profiles";
+
+/** The repository the profiles are read from by default, at this chant's release tag. */
+export const PROFILES_REPO = "https://github.com/INTENTIUS/chant";
+
+/**
+ * The `chant init --from` source for a profile: `from` (a `<repo>@<ref>` or
+ * a directory holding a chant checkout) when given, else the chant repository
+ * at the tag of the chant reading, `chant-v<version>`.
+ */
+export function profileSource(profile: Profile, from: string | undefined, version: string): string {
+  const base = from ?? `${PROFILES_REPO}@chant-v${version}`;
+  return `${base}#${PROFILES_DIR}/${profile}`;
+}
 
 /** Directory names whose children are examples or test fixtures, not members. */
 const EXAMPLE_DIRS = new Map<string, "examples" | "fixtures">([
@@ -544,6 +574,8 @@ export async function runWorkspaceInit(ctx: CommandContext): Promise<number> {
     return 1;
   }
 
+  if (args.profile !== undefined) return initProfile(args, root);
+
   let proposal: Proposal;
   try {
     proposal = proposeWorkspace(root, { name: args.selectName });
@@ -583,3 +615,51 @@ export async function runWorkspaceInit(ctx: CommandContext): Promise<number> {
   console.log(formatSuccess(`Wrote ${target}. chant workspace ls lists what it declares.`));
   return 0;
 }
+
+/** `chant workspace init --profile <profile>` (#3174): copy a profile with `chant init --from`, then name the workspace. */
+async function initProfile(args: CommandContext["args"], root: string): Promise<number> {
+  const profile = args.profile as Profile;
+  if (!(PROFILES as readonly string[]).includes(profile)) {
+    console.error(formatError({ message: `--profile ${JSON.stringify(args.profile)} is not a profile; the profiles are ${PROFILES.join(", ")}`, hint: USAGE }));
+    return 1;
+  }
+  const { parseParamArgs } = await import("./template-manifest");
+  let params: Record<string, string>;
+  try {
+    params = parseParamArgs(args.param ?? []);
+  } catch (err) {
+    console.error(formatError({ message: (err as Error).message, hint: USAGE }));
+    return 1;
+  }
+  const from = profileSource(profile, args.migrateFrom, readerVersion());
+  console.log(`chant workspace init --profile ${profile} copies ${from} into ${root}, as chant init --from would, with a lineage lock.`);
+  if (args.selectName !== undefined) console.log(`The workspace is named ${args.selectName}.`);
+  console.log("");
+  let write = !!args.yes;
+  if (!write) {
+    if (!process.stdin.isTTY) {
+      console.log("Nothing written. Re-run with --yes to write it.");
+      return 0;
+    }
+    write = await confirm(`Make the ${profile} workspace? [y/N] `);
+  }
+  if (!write) {
+    console.log("Nothing written.");
+    return 0;
+  }
+  const { initFromCommand } = await import("./lineage-init");
+  const result = await initFromCommand({ from, path: root, params, force: args.force });
+  if (!result.success) {
+    console.error(formatError({ message: result.error ?? `the ${profile} profile could not be copied`, hint: USAGE }));
+    return 1;
+  }
+  if (args.selectName !== undefined) {
+    const file = join(root, "chant.workspace.json");
+    writeFileSync(file, setProperty(readFileSync(file, "utf-8"), false, "", "name", args.selectName));
+  }
+  console.log(formatSuccess(`Made a ${profile} workspace in ${root}:`));
+  for (const f of result.createdFiles) console.log(`  ${f}`);
+  console.log("");
+  console.log("chant workspace check checks it, and chant workspace upgrade takes a later version of the profile.");
+  return 0;
+}