@maycombhq/atticus 0.0.0-stage → 2.0.0-beta.10

package/dist/chunk-4PJADZRR.js

@@ -0,0 +1,545 @@
+import { createRequire as __atticusCreateRequire } from "node:module";
+import { fileURLToPath as __atticusFileURLToPath } from "node:url";
+var require = __atticusCreateRequire(import.meta.url);
+var __atticusUrl = (p) => new URL("./" + p, import.meta.url).href;
+var __atticusPath = (p) => __atticusFileURLToPath(__atticusUrl(p));
+import {
+  storeChangeRows
+} from "./chunk-23M2LUYM.js";
+import {
+  metarepoOpenSpec
+} from "./chunk-KC5DROFC.js";
+import {
+  table
+} from "./chunk-VOGCSYOI.js";
+import {
+  gateStatus,
+  ownerWaitsLine,
+  reviewedGates
+} from "./chunk-47QE246J.js";
+import {
+  ChangeError,
+  archiveChange,
+  changeFootprint,
+  changeReport,
+  changeStore,
+  completeCaptures,
+  detectConflicts,
+  formatLearn,
+  handoff,
+  learnReport,
+  loadChangeContext,
+  newChange,
+  returnToPo,
+  syncHandoff
+} from "./chunk-XQ3YIV5R.js";
+import {
+  createAdapters,
+  fileStepStore
+} from "./chunk-NGPU2ARF.js";
+import {
+  baseClonePath,
+  createWorkspace,
+  isInPlace,
+  loadRepos
+} from "./chunk-PGKHJYOB.js";
+import {
+  changesRelOf,
+  handoffBranch,
+  loadOrgPack,
+  orgPackDirOf
+} from "./chunk-577AJVRS.js";
+
+// packages/cli/dist/change-commands.js
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+var nowIso = () => (/* @__PURE__ */ new Date()).toISOString().replace(/\.\d{3}Z$/, "Z");
+function printReasons(io, reasons) {
+  for (const r of reasons)
+    io.err(`  - ${r.message}`);
+}
+function fail(io, e) {
+  if (e instanceof ChangeError) {
+    io.err(e.message);
+    printReasons(io, e.reasons);
+    return e.code === "invalid" ? 2 : 1;
+  }
+  if (e instanceof Error && e.name === "AdapterError") {
+    io.err(e.message);
+    return 1;
+  }
+  throw e;
+}
+async function gitHostFor(root, deps, io) {
+  if (deps.gitHost)
+    return deps.gitHost;
+  const op = await loadOrgPack(join(orgPackDirOf(root)));
+  const gh = createAdapters(op.runtime, {}, { store: fileStepStore(root), root, procedures: op.procedures }).gitHost;
+  if (!gh)
+    io.err("No Git host is configured. Set adapters.gitHost in org-pack/runtime.yaml.");
+  return gh;
+}
+var approvalOf = (by, at, ref) => ({ by, at, ref });
+function parseOwners(values) {
+  const out = {};
+  for (const v of values) {
+    const m = /^([a-z0-9][a-z0-9._-]*)=(.+)$/.exec(v.trim());
+    if (!m)
+      return `--owner takes role=person[,person], for example architect=ari; got "${v}"`;
+    out[m[1]] = [
+      ...out[m[1]] ?? [],
+      ...m[2].split(",").map((s) => s.trim()).filter(Boolean)
+    ];
+  }
+  return out;
+}
+async function changeNew(root, o, io, deps = {}) {
+  if (!o.title || !o.type || !o.by) {
+    io.err('Usage: atticus change new "<title>" --type <change type> [--by <you>] [--template <id>]');
+    if (!o.type) {
+      try {
+        const op = await loadOrgPack(join(orgPackDirOf(root)));
+        if (op.changeTypes.types.length) {
+          io.err("The change types here:");
+          for (const t of op.changeTypes.types)
+            io.err(`  ${t.id}  ${t.name}`);
+        }
+      } catch {
+      }
+    }
+    return 2;
+  }
+  const owners = parseOwners(o.owners ?? []);
+  if (typeof owners === "string") {
+    io.err(owners);
+    return 2;
+  }
+  let like;
+  if (o.like) {
+    const { findPastChange } = await import("./chunk-MF7QH4AX.js");
+    like = await findPastChange(root, o.like);
+    if (!like) {
+      io.err(`There is no archived change ${o.like}: atticus change similar "<what it is about>" lists them.`);
+      return 1;
+    }
+  }
+  let impact;
+  if (o.impact) {
+    const { loadVendorImpact } = await import("./chunk-SS66Q4VE.js");
+    const got = await loadVendorImpact(root, o.impact, io);
+    if ("error" in got) {
+      io.err(got.error);
+      return 1;
+    }
+    impact = got;
+  }
+  try {
+    const i = impact?.impact;
+    const systems = [...o.systems ?? [], ...i?.systems ?? []];
+    const c = await newChange(root, {
+      title: o.title,
+      type: o.type,
+      by: o.by,
+      owners,
+      ...o.template ? { template: o.template } : {},
+      ...o.id ? { id: o.id } : {},
+      ...systems.length ? { systems } : {},
+      ...i ? {
+        touches: {
+          repos: i.repos,
+          interfaces: i.interfaces.map((id) => ({ id, status: "planned-modify" })),
+          records: [.../* @__PURE__ */ new Set([...i.flows.map((f) => f.id), ...i.endpoints])].sort()
+        }
+      } : {},
+      ...deps.now ? { now: deps.now } : {}
+    });
+    io.out(`Created ${c.id} (${c.type}, from the ${c.template} template). It is in ${c.state}.`);
+    if (impact) {
+      const { attachToChange } = await import("./chunk-FOGG4AUR.js");
+      const { changeFolder } = await import("./chunk-6VBXAGJX.js");
+      const { impactDocument, IMPACT_WORDS } = await import("./chunk-SS66Q4VE.js");
+      const doc = impactDocument(impact);
+      const attached = await attachToChange(changeFolder(root, c.id), [{ name: doc.name, bytes: new TextEncoder().encode(doc.text) }], { by: o.by, at: deps.now ?? (/* @__PURE__ */ new Date()).toISOString().replace(/\.\d{3}Z$/, "Z") });
+      const path = attached.added[0]?.path ?? `inputs/${doc.name}`;
+      io.out(IMPACT_WORDS.started(impact.name, impact.impact.newer.version ?? impact.impact.newer.id, impact.impact, path));
+    }
+    if (like) {
+      const { attachPastChange } = await import("./chunk-MF7QH4AX.js");
+      const name = await attachPastChange(root, c.id, like, o.by, deps.now ? new Date(deps.now) : /* @__PURE__ */ new Date());
+      io.out(`It starts from ${like}: attached as inputs/${name}, which its steps read as an example.`);
+    }
+    io.out(`Write the brief: ${changesRelOf(root)}/${c.id}/brief.md`);
+    return 0;
+  } catch (e) {
+    return fail(io, e);
+  }
+}
+async function changeStatus(root, id, o, io) {
+  let r;
+  try {
+    r = await changeReport(root, id);
+  } catch (e) {
+    if (e instanceof Error && e.name === "ChangeFileError") {
+      io.err(e.message);
+      return 1;
+    }
+    return fail(io, e);
+  }
+  for (const p of r.problems)
+    io.err(p);
+  const critic = await usedUpGates(root, r.change.id);
+  if (o.json) {
+    io.out(JSON.stringify({
+      id: r.change.id,
+      state: r.state,
+      phase: r.phase,
+      next: r.next,
+      ...r.progress ? { progress: r.progress } : {},
+      nextStep: r.nextStep,
+      reasons: r.reasons,
+      risk: r.risk,
+      tests: r.tests,
+      privacy: r.privacy,
+      handoff: r.handoff,
+      footprint: r.footprint,
+      ...critic.length ? { critic } : {}
+    }, null, 2));
+    return 0;
+  }
+  io.out(`${r.change.id}: ${r.change.title} (${r.change.type})`);
+  io.out(`State: ${r.state}`);
+  if (r.progress)
+    io.out(`Work: ${r.progress.summary}`);
+  io.out(`Next: ${r.nextStep}`);
+  io.out(`Risk: ${r.risk.level} (${r.risk.score})${r.risk.factors.length ? ": " : ""}${r.risk.factors.map((f) => `${f.detail} +${f.points}${f.cites?.length ? ` (${f.cites.join(", ")})` : ""}`).join("; ")}`);
+  if (r.phase)
+    io.out(r.handoff ? r.handoff.state === "changes-requested" ? `Hand-off: PR #${r.handoff.pr.number} has changes requested (${r.handoff.pr.url}); update the artifacts and hand off again.` : `Hand-off: merge PR #${r.handoff.pr.number} to approve the ${r.phase} gate (${r.handoff.pr.url}).` : `Hand-off: no PR yet; atticus change handoff ${r.change.id} --approve opens it, and merging it approves the ${r.phase} gate.`);
+  io.out(`Tests: ${r.tests.required.length ? r.tests.required.join(", ") : "none listed"}`);
+  if (r.tests.note)
+    io.out(`  (${r.tests.note})`);
+  for (const a of r.tests.added ?? [])
+    io.out(`  ${a.kinds.join(" and ")}, for ${a.factor}: tests ${a.why} (${a.cites.join(", ")})`);
+  const counted = `counted as personal: ${r.privacy.counted.levels.join(", ")}; from ${r.privacy.counted.from === "change-policy" ? "the change policy's privacy.classifications" : "the change policy's privacy.classifications and the org pack's levels above internal"}`;
+  io.out(r.privacy.touched ? `Privacy: touches personal data (${r.privacy.records.map((x) => x.field ? `${x.id}.${x.field} ${x.classification}` : `${x.id} ${x.classification}`).join(", ")}); review it with the ${r.privacy.phase} hand-off (${counted}).` : r.risk.factors.some((f) => f.factor === "personal-data") ? `Privacy: no data classified personal touched (${counted}), but its steps touch personal or consent data by name: see the risk's personal-data factor.` : `Privacy: no personal data touched (${counted}).`);
+  if (r.reasons.length > 0) {
+    io.out("Blocked by:");
+    for (const x of r.reasons)
+      io.out(`  - ${x.message}`);
+  }
+  for (const line of critic)
+    io.out(`Critic: ${line}`);
+  return 0;
+}
+async function usedUpGates(root, id) {
+  const out = [];
+  for (const g of await reviewedGates(root, id).catch(() => [])) {
+    const s = await gateStatus(root, id, g).catch(() => void 0);
+    if (s && (s.humanDecides || s.checkRound || ownerWaitsLine(s, id)))
+      out.push((await import("./chunk-62YMDXY6.js")).statusLine(s, id));
+  }
+  return out;
+}
+async function changeHandoff(root, id, o, io, deps = {}) {
+  if (!o.by) {
+    io.err("Say who is handing off: set your Git user (git config user.name), or pass --by <you>.");
+    return 2;
+  }
+  if (!o.approve)
+    return handoffPreview(root, id, o.by, io);
+  const gitHost = await gitHostFor(root, deps, io);
+  if (!gitHost)
+    return 1;
+  const now = deps.now ?? nowIso();
+  try {
+    const c = await changeStore(root).read(id);
+    const phase = c.state === "release-ready" ? "release" : c.state;
+    const ref = /^(define|design|plan|build|qa|release)$/.test(phase) ? handoffBranch(id, phase) : `change/${id}`;
+    const h = await handoff(root, id, {
+      gitHost,
+      by: o.by,
+      approval: approvalOf(o.by, now, ref),
+      now,
+      ...o.repo ? { repo: o.repo } : {},
+      ...o.base ? { base: o.base } : {},
+      ...deps.publisher ? { publisher: deps.publisher } : {},
+      // WP7.4: the PR reviews itself: the change as a picture, its estimate, its open findings.
+      review: await (await import("./chunk-LTQANUDH.js")).handoffReview(root, id),
+      ...metarepoOpenSpec(root) ? { openspec: metarepoOpenSpec(root) } : {}
+    });
+    io.out(`Hand-off PR #${h.pr.number} (${h.branch}) is open: ${h.pr.url}`);
+    io.out(`Reviewers: ${h.reviewers.length ? h.reviewers.map((r) => `@${r}`).join(", ") : "none named"}`);
+    io.out(`Merging it approves the gate; the Git host's own rules decide who may approve it.`);
+    return 0;
+  } catch (e) {
+    if (e instanceof Error && e.name === "ChangeFileError") {
+      io.err(e.message);
+      return 1;
+    }
+    return fail(io, e);
+  }
+}
+async function handoffPreview(root, id, by, io) {
+  let r;
+  try {
+    r = await changeReport(root, id);
+  } catch (e) {
+    if (e instanceof Error && e.name === "ChangeFileError") {
+      io.err(e.message);
+      return 1;
+    }
+    return fail(io, e);
+  }
+  if (!r.phase) {
+    io.err(`${id} is ${r.state}; there is nothing to hand off.`);
+    return 1;
+  }
+  if (r.blockers.length) {
+    io.err(`${id} isn't ready to hand off ${r.phase}:`);
+    printReasons(io, r.blockers);
+    return 1;
+  }
+  const open = r.handoff && r.handoff.phase === r.phase;
+  io.out(open ? `Would update hand-off PR #${r.handoff.pr.number} (${r.handoff.pr.url}) with the ${r.phase} files, as ${by}.` : `Would open the ${r.phase} hand-off PR ${handoffBranch(id, r.phase)} with the phase's files, as ${by}.`);
+  io.out(`Nothing was sent. To do it: atticus change handoff ${id} --approve. Merging the PR approves the gate.`);
+  return 0;
+}
+async function changeSync(root, id, o, io, deps = {}) {
+  const gitHost = await gitHostFor(root, deps, io);
+  if (!gitHost)
+    return 1;
+  const now = deps.now ?? nowIso();
+  try {
+    const r = await syncHandoff(root, id, {
+      gitHost,
+      now,
+      ...o.repo ? { repo: o.repo } : {},
+      ...o.approve && o.by ? { approval: approvalOf(o.by, now, `${id}#merge`) } : {},
+      ...deps.git ? { git: deps.git } : {}
+    });
+    if (r.merged) {
+      io.out(`PR #${r.handoff.pr.number} merged. ${id} is now ${r.state}.`);
+      if (r.capture)
+        io.out(captureLine(r.capture));
+      return 0;
+    }
+    if (r.ready) {
+      io.out(`PR #${r.handoff.pr.number} is approved and the Git host's rules are met. Merge it on the Git host, or run atticus change sync ${id} --approve to merge it as you.`);
+      return 1;
+    }
+    io.err(`PR #${r.handoff.pr.number} can't merge yet:`);
+    printReasons(io, r.reasons);
+    return 1;
+  } catch (e) {
+    if (e instanceof Error && e.name === "ChangeFileError") {
+      io.err(e.message);
+      return 1;
+    }
+    return fail(io, e);
+  }
+}
+function captureLine(c) {
+  if (c.state !== "captured")
+    return c.note ?? "";
+  const edited = c.files.filter((f) => f.status !== "same").length;
+  return `Kept what Atticus drafted beside what merged: stage/${c.stage}.drafted/ and stage/${c.stage}.merged/ (${edited} of ${c.files.length} file${c.files.length === 1 ? "" : "s"} changed by people). atticus change learn measures it.`;
+}
+async function changeLearn(root, o, io, deps = {}) {
+  const now = deps.now ?? nowIso();
+  try {
+    const ctx = await loadChangeContext(root);
+    await completeCaptures(root, ctx, { now, ...deps.git ? { git: deps.git } : {} });
+  } catch {
+  }
+  const report = await learnReport(root);
+  if (o.json)
+    io.out(JSON.stringify(report, null, 2));
+  else
+    for (const l of formatLearn(report))
+      io.out(l);
+  return 0;
+}
+async function changeReturn(root, id, o, io, deps = {}) {
+  if (!o.by || !o.reason) {
+    io.err('Usage: atticus change return <id> --reason "<why>" --approve [--by <you>]');
+    return 2;
+  }
+  if (!o.approve) {
+    try {
+      const r = await changeReport(root, id);
+      if (!r.handoff) {
+        io.err(`${id} has no open hand-off PR to return.`);
+        return 1;
+      }
+      io.out(`Would comment on PR #${r.handoff.pr.number} (${r.handoff.pr.url}) and close it, and return ${id} to the product owner, as ${o.by}.`);
+      io.out(`Nothing was sent. To do it: atticus change return ${id} --reason "..." --approve.`);
+      return 0;
+    } catch (e) {
+      if (e instanceof Error && e.name === "ChangeFileError") {
+        io.err(e.message);
+        return 1;
+      }
+      return fail(io, e);
+    }
+  }
+  const gitHost = await gitHostFor(root, deps, io);
+  if (!gitHost)
+    return 1;
+  const now = deps.now ?? nowIso();
+  try {
+    const r = await returnToPo(root, id, {
+      gitHost,
+      by: o.by,
+      reason: o.reason,
+      approval: approvalOf(o.by, now, `${id}#return`),
+      now,
+      ...o.repo ? { repo: o.repo } : {}
+    });
+    io.out(r.closedOnHost ? `Returned ${id} to the product owner and closed PR #${r.handoff.pr.number}.` : `Returned ${id} to the product owner. Close PR #${r.handoff.pr.number} on the Git host by hand; this Git host adapter can't close pull requests.`);
+    return 0;
+  } catch (e) {
+    if (e instanceof Error && e.name === "ChangeFileError") {
+      io.err(e.message);
+      return 1;
+    }
+    return fail(io, e);
+  }
+}
+async function rescanAfterArchive(root, id, io, deps) {
+  const ctx = await loadChangeContext(root);
+  const change = await changeStore(root).read(id);
+  const fp = await changeFootprint(ctx, change);
+  const all = await loadRepos(root);
+  const manifest = new Map(all.map((r) => [r.id, r]));
+  const wanted = [
+    .../* @__PURE__ */ new Set([
+      ...fp.repos,
+      ...all.filter((r) => fp.components.includes(r.component ?? r.id) || r.system !== void 0 && fp.systems.includes(r.system)).map((r) => r.id)
+    ])
+  ].sort();
+  const here = wanted.filter((r) => {
+    const m = manifest.get(r);
+    return !!m && (isInPlace(m.url) || existsSync(baseClonePath(root, r)));
+  });
+  const away = wanted.filter((r) => !here.includes(r));
+  const command = (ids) => `atticus workspace sync --repos ${ids.join(",")} && atticus scan`;
+  if (wanted.length === 0) {
+    io.out("The change names no repos; run atticus scan to refresh the catalog.");
+    return 0;
+  }
+  if (here.length === 0) {
+    io.out(`The change's repos aren't in base clones here, so the catalog wasn't rescanned. Run: ${command(away)}`);
+    return 0;
+  }
+  const clones = here.map((r) => manifest.get(r)).filter((m) => !isInPlace(m.url));
+  if (clones.length) {
+    const synced = await createWorkspace(root, deps.git).sync(clones);
+    for (const s of synced.filter((x) => x.action === "failed" || x.action === "skipped"))
+      io.out(`Couldn't update the base clone of ${s.id} (${s.reason ?? s.action}); scanning what is there.`);
+  }
+  io.out(`Rescanning for ${id}'s repos: ${here.join(", ")}.`);
+  const code = await (await import("./chunk-DZRQDNPT.js")).scanCommand(root, {}, io);
+  if (away.length)
+    io.out(`Not in a base clone here: ${away.join(", ")}. To add them, run: ${command(away)}`);
+  return code;
+}
+async function changeArchive(root, id, o, io, deps = {}) {
+  if (!o.by) {
+    io.err("Say who is archiving: set your Git user (git config user.name), or pass --by <you>.");
+    return 2;
+  }
+  try {
+    const os = metarepoOpenSpec(root);
+    await archiveChange(root, id, {
+      by: o.by,
+      ...deps.now ? { now: deps.now } : {},
+      ...os ? { openspec: os } : {}
+    });
+    io.out(`Archived ${id}.`);
+    if (o.rescan === false)
+      return 0;
+    return await rescanAfterArchive(root, id, io, deps);
+  } catch (e) {
+    if (e instanceof Error && e.name === "ChangeFileError") {
+      io.err(e.message);
+      return 1;
+    }
+    return fail(io, e);
+  }
+}
+async function changeList(root, o, io) {
+  const all = await changeStore(root).list();
+  const stores = await storeChangeRows(root);
+  for (const l of stores.err)
+    io.err(l);
+  const progress = new Map((await metarepoOpenSpec(root)?.listChanges().catch(() => void 0))?.map((c) => [c.name, c]) ?? []);
+  const tasksOf = (id) => {
+    const p = progress.get(id);
+    return p ? { completedTasks: p.completedTasks, totalTasks: p.totalTasks } : void 0;
+  };
+  if (o.json) {
+    io.out(JSON.stringify([
+      ...all.map((c) => ({
+        id: c.id,
+        title: c.title,
+        type: c.type,
+        state: c.state,
+        ...tasksOf(c.id) ? { tasks: tasksOf(c.id) } : {}
+      })),
+      ...stores.json
+    ], null, 2));
+    return 0;
+  }
+  if (all.length === 0)
+    io.out("No changes yet. Start one with atticus change new.");
+  else {
+    const withTasks = progress.size > 0;
+    const rows = all.map((c) => {
+      const live = c.handoffs.find((h) => h.state === "open" || h.state === "changes-requested");
+      const t = tasksOf(c.id);
+      return [
+        c.id,
+        c.type,
+        c.state,
+        ...withTasks ? [t ? `${t.completedTasks}/${t.totalTasks}` : ""] : [],
+        live ? `#${live.pr.number} ${live.state}` : "",
+        c.title
+      ];
+    });
+    const head = ["ID", "TYPE", "STATE", ...withTasks ? ["TASKS"] : [], "HAND-OFF", "TITLE"];
+    for (const l of table(head, rows))
+      io.out(l);
+  }
+  for (const l of stores.lines)
+    io.out(l);
+  return 0;
+}
+async function changeConflicts(root, o, io) {
+  const pairs = await detectConflicts(root);
+  if (o.json) {
+    io.out(JSON.stringify(pairs, null, 2));
+    return pairs.length ? 1 : 0;
+  }
+  if (pairs.length === 0) {
+    io.out("No open changes overlap.");
+    return 0;
+  }
+  for (const p of pairs) {
+    const parts = Object.entries(p.overlap).filter(([, v]) => v.length > 0).map(([k, v]) => `${k} ${v.join(", ")}`);
+    io.out(`${p.changes[0]} and ${p.changes[1]} both touch ${parts.join("; ")}`);
+  }
+  return 1;
+}
+
+export {
+  parseOwners,
+  changeNew,
+  changeStatus,
+  changeHandoff,
+  changeSync,
+  captureLine,
+  changeLearn,
+  changeReturn,
+  changeArchive,
+  changeList,
+  changeConflicts
+};

package/dist/chunk-4Q3NN7VF.js

@@ -0,0 +1,32 @@
+import { createRequire as __atticusCreateRequire } from "node:module";
+import { fileURLToPath as __atticusFileURLToPath } from "node:url";
+var require = __atticusCreateRequire(import.meta.url);
+var __atticusUrl = (p) => new URL("./" + p, import.meta.url).href;
+var __atticusPath = (p) => __atticusFileURLToPath(__atticusUrl(p));
+
+// packages/cli/dist/handoff-steps.js
+var STEPS = /* @__PURE__ */ new Set([
+  "scan survey",
+  "scan verify",
+  "spec draft",
+  "knowledge scan",
+  // ADR 0087: the feature and architecture stages (plan stories already takes it).
+  "change feature",
+  "change architecture",
+  // ADR 0113: the fast path's one step.
+  "change small",
+  "change draft",
+  "plan stories",
+  // ADR 0101: what a change needs from the organisation.
+  "change needs",
+  "knowledge find",
+  "knowledge ask"
+]);
+var isHandoffStep = (group, command) => STEPS.has(`${group ?? ""} ${command ?? ""}`) || isCritic(group, command) || // ADR 0124 §4: atticus map <repo>, the batched read, one batch per hand-off.
+group === "map" && !!command && !command.startsWith("-");
+var isCritic = (group, command) => group === "critic" && !!command && command !== "stats";
+
+export {
+  isHandoffStep,
+  isCritic
+};