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

package/dist/chunk-RRVT4MPS.js

@@ -0,0 +1,150 @@
+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 {
+  SEED_MARK,
+  loadEstate,
+  openspecRootOf,
+  readExistingSpecs,
+  seedChangeId,
+  seedCollisionWords,
+  seedCollisions,
+  seedSpec,
+  writeSpecFiles
+} from "./chunk-KC5DROFC.js";
+import "./chunk-RK6MKKKP.js";
+import "./chunk-47QE246J.js";
+import {
+  changeFolder
+} from "./chunk-XQ3YIV5R.js";
+import {
+  createOpenSpec
+} from "./chunk-MGVYVW7Q.js";
+import "./chunk-NGPU2ARF.js";
+import "./chunk-AY2IUF4K.js";
+import "./chunk-6JLPXDWN.js";
+import "./chunk-4GZXS6S2.js";
+import "./chunk-R4TBNKKC.js";
+import "./chunk-NIXVDQVO.js";
+import "./chunk-UR7RMZ3R.js";
+import "./chunk-N4QZJJVB.js";
+import "./chunk-PGKHJYOB.js";
+import "./chunk-MKRBG5EF.js";
+import "./chunk-5XDNUJ4P.js";
+import "./chunk-577AJVRS.js";
+import {
+  writeFileAtomic
+} from "./chunk-D3PO4DOZ.js";
+import "./chunk-TV45EUGM.js";
+
+// packages/cli/dist/spec-seed-commands.js
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+var NO_OPENSPEC = "This metarepo isn't set up with OpenSpec (no openspec/config.yaml). Set it up first: atticus openspec setup";
+async function specSeed(root, repo, o, io) {
+  const osRoot = openspecRootOf(root);
+  if (!osRoot) {
+    io.err(NO_OPENSPEC);
+    return 2;
+  }
+  const estate = await loadEstate(root, []);
+  const flows = estate.flows.filter((f) => f.repo === repo).map((f) => f.flow);
+  if (!flows.length) {
+    io.err(`${repo} has no verified flows in specs/${repo}/. Read it first: atticus map ${repo}, then atticus verify ${repo} --write`);
+    return 2;
+  }
+  const os = createOpenSpec({ root: osRoot });
+  const existing = await readExistingSpecs(os);
+  const multiRepo = new Set(estate.flows.map((f) => f.repo)).size > 1;
+  const seed = seedSpec(repo, flows, { existing, multiRepo });
+  if (!seed.deltas.length) {
+    if (o.json)
+      io.out(JSON.stringify({ change: null, repo, skipped: seed.skipped }, null, 2));
+    else
+      io.out(`Nothing to seed: openspec/specs already has every flow of ${repo} that the code runs today. Each change keeps it current when it is archived.`);
+    return 0;
+  }
+  const dir = changeFolder(root, seed.change);
+  if (!existsSync(join(dir, ".openspec.yaml")))
+    await os.newChange(seed.change, { description: `Starting spec for ${repo}` });
+  const written = await writeSpecFiles(dir, seed.files, SEED_MARK);
+  const had = await readFile(join(dir, "proposal.md"), "utf8").catch(() => void 0);
+  const proposal = had === void 0 || had.startsWith(SEED_MARK);
+  if (proposal)
+    await writeFileAtomic(join(dir, "proposal.md"), seed.proposal);
+  const kept = Object.keys(seed.files).filter((f) => !written.includes(f));
+  const collisions = (await seedCollisions(root)).filter((c) => c.seed === seed.change);
+  if (o.json) {
+    io.out(JSON.stringify({
+      change: seed.change,
+      repo,
+      capabilities: seed.deltas.map((d) => ({ capability: d.capability, flow: d.flow })),
+      written,
+      kept,
+      skipped: seed.skipped,
+      collisions
+    }, null, 2));
+    return 0;
+  }
+  for (const c of collisions)
+    io.err(`Warning: ${seedCollisionWords(c)}`);
+  const rel = `openspec/changes/${seed.change}`;
+  io.out(`Wrote ${rel}/: a starting spec for ${repo}, ${seed.deltas.length} ${seed.deltas.length === 1 ? "capability" : "capabilities"}, one per verified flow, each scenario citing its lines.`);
+  for (const f of kept)
+    io.out(`Kept ${rel}/${f} as a person left it (no mark on its first line).`);
+  if (!proposal)
+    io.out(`Kept ${rel}/proposal.md as a person left it.`);
+  for (const s of seed.skipped)
+    io.out(`Not seeded: ${s.flow} (${s.why}).`);
+  io.out(`Read each spec under ${rel}/specs/ against the code it cites, then accept it: atticus spec accept ${repo}`);
+  return 0;
+}
+async function specAccept(root, repo, o, io) {
+  if (!o.by) {
+    io.err("Say who is accepting: set your Git user (git config user.name), or pass --by <you>.");
+    return 2;
+  }
+  const osRoot = openspecRootOf(root);
+  if (!osRoot) {
+    io.err(NO_OPENSPEC);
+    return 2;
+  }
+  const change = seedChangeId(repo);
+  const dir = changeFolder(root, change);
+  if (!existsSync(join(dir, ".openspec.yaml"))) {
+    io.err(`${repo} has no starting spec waiting. Write one first: atticus spec seed ${repo}`);
+    return 2;
+  }
+  const os = createOpenSpec({ root: osRoot });
+  const v = await os.validate({ item: change, type: "change", strict: true });
+  const issues = (v.items[0]?.issues ?? []).filter((i) => i.level !== "INFO");
+  if (issues.length || v.items[0]?.valid === false) {
+    io.err(`${change} doesn't pass openspec validate --strict; fix its specs and accept again:`);
+    for (const i of issues)
+      io.err(`  ${i.path}: ${i.message}`);
+    return 1;
+  }
+  const date = (o.now ?? /* @__PURE__ */ new Date()).toISOString().slice(0, 10);
+  const p = join(dir, "proposal.md");
+  const text = await readFile(p, "utf8").catch(() => void 0);
+  if (text !== void 0 && !/\nAccepted by .+ on \d{4}-\d{2}-\d{2}\.\n?$/.test(text))
+    await writeFileAtomic(p, `${text.trimEnd()}
+
+Accepted by ${o.by} on ${date}.
+`);
+  try {
+    await os.archive(change);
+  } catch (e) {
+    io.err(`openspec archive ${change} failed: ${e.message}`);
+    return 1;
+  }
+  io.out(`Accepted ${repo}'s starting spec: openspec/specs/ has its capabilities, and ${change} is archived. Commit the metarepo and open its pull request; the next change to ${repo} modifies these requirements.`);
+  return 0;
+}
+export {
+  specAccept,
+  specSeed
+};

package/dist/chunk-SS66Q4VE.js

@@ -0,0 +1,231 @@
+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 {
+  intakeContext
+} from "./chunk-WARBF2KY.js";
+import "./chunk-VOGCSYOI.js";
+import {
+  estateFacts,
+  estateRepos,
+  hostAliases,
+  joinReposOf,
+  outsideProfileSystems
+} from "./chunk-AY2IUF4K.js";
+import "./chunk-6JLPXDWN.js";
+import "./chunk-4GZXS6S2.js";
+import {
+  readVendorSpec,
+  slug,
+  vendorImpact
+} from "./chunk-R4TBNKKC.js";
+import "./chunk-NIXVDQVO.js";
+import "./chunk-UR7RMZ3R.js";
+import "./chunk-PGKHJYOB.js";
+import "./chunk-MKRBG5EF.js";
+import "./chunk-5XDNUJ4P.js";
+import {
+  inputsDirOf,
+  joinConventions,
+  readFlow,
+  specFlowFiles
+} from "./chunk-577AJVRS.js";
+import "./chunk-D3PO4DOZ.js";
+import "./chunk-TV45EUGM.js";
+
+// packages/cli/dist/vendor-impact-commands.js
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { isAbsolute, join, relative, resolve, sep } from "node:path";
+var IMPACT_WORDS = {
+  usage: "Name the vendor spec: atticus intake impact <spec> [--json]",
+  noSuchSpec: (spec) => `There is no ${spec} in inputs/. atticus intake list shows what is there.`,
+  notASpec: (path) => `${path} isn't an OpenAPI 3 or Swagger 2 spec, so it has no operations to compare.`,
+  noOtherVersion: (path) => `${path} has no other version beside it in inputs/, so there is nothing to compare. Add each version of a vendor's spec beside the last (atticus intake add), never over it.`,
+  noSystem: (path) => `${path} isn't linked to a system yet, so its operations belong to nobody. atticus triage asks which system it is.`,
+  header: (name, older, newer) => `${name}: ${older.path}${older.version ? ` (${older.version})` : ""} \u2192 ${newer.path}${newer.version ? ` (${newer.version})` : ""}`,
+  counts: (all, breaking) => all === 0 ? "The two versions publish the same operations, fields and auth." : `${all} change${all === 1 ? "" : "s"}: ${breaking} breaking, ${all - breaking} additive.`,
+  severity: { breaking: "Breaking", additive: "Additive" },
+  reachesNothing: "Nothing in the estate reaches it.",
+  direct: (component, what, where2, name) => `called directly by ${component}: ${what}, ${where2} (on ${name})`,
+  gap: (message, where2) => `Forwarded, but not in the older version either: ${message} (${where2}).`,
+  ask: (question) => `Asked: ${question}`,
+  affected: (repos, flows) => `Affected: ${repos.join(", ")}${flows.length ? `; flows ${flows.join(", ")}` : ""}.`,
+  nothingAffected: "Nothing in the estate reaches these changes.",
+  start: (spec) => `Start a change with this as its footprint: atticus change new "<title>" --type <type> --impact ${spec}`,
+  docTitle: (name, version) => `# What ${name} ${version} changes, and what in the estate it reaches`,
+  started: (name, version, i, attached) => `Its footprint is what ${name} ${version} reaches: ${i.repos.length} repo${i.repos.length === 1 ? "" : "s"}, ${i.flows.length} flow${i.flows.length === 1 ? "" : "s"}, ${i.interfaces.length} Interface${i.interfaces.length === 1 ? "" : "s"}. The impact is attached as ${attached}.`
+};
+var posix = (p) => p.split(sep).join("/");
+var SPECS = /* @__PURE__ */ new Set(["openapi", "swagger"]);
+function findDocument(root, docs, spec) {
+  const kept = docs.filter((d) => d.id);
+  if (!isAbsolute(spec) && spec.includes("/") && existsSync(resolve(spec)))
+    spec = resolve(spec);
+  const rel = isAbsolute(spec) ? `inputs/${posix(relative(inputsDirOf(root), spec))}` : posix(spec);
+  return kept.find((d) => d.path === rel) ?? kept.find((d) => d.path === `inputs/${rel}`) ?? kept.find((d) => d.id === spec) ?? (() => {
+    const named = kept.filter((d) => d.path.split("/").pop() === rel);
+    return named.length === 1 ? named[0] : void 0;
+  })();
+}
+async function loadVendorImpact(root, spec, io) {
+  const { op, inputs } = await intakeContext(root, io);
+  const doc = findDocument(root, inputs.documents, spec);
+  if (!doc)
+    return { error: IMPACT_WORDS.noSuchSpec(spec) };
+  if (!SPECS.has(doc.classification))
+    return { error: IMPACT_WORDS.notASpec(doc.path) };
+  const byId = new Map(inputs.documents.filter((d) => d.id).map((d) => [d.id, d]));
+  const older = doc.supersededBy ? doc : inputs.documents.find((d) => d.supersededBy === doc.id && SPECS.has(d.classification));
+  const newer = doc.supersededBy ? byId.get(doc.supersededBy) : doc;
+  if (!older || !newer || !SPECS.has(newer.classification))
+    return { error: IMPACT_WORDS.noOtherVersion(doc.path) };
+  const systemId = newer.systems[0] ?? older.systems[0];
+  const system = op.profiles.flatMap((p) => p.profile?.systems ?? []).find((s) => s.id === systemId);
+  if (!systemId || !system)
+    return { error: IMPACT_WORDS.noSystem(newer.path) };
+  const inputsDir = inputsDirOf(root);
+  const read = async (d) => readVendorSpec(d.path, await readFile(join(inputsDir, ...d.path.split("/").slice(1)), "utf8"), systemId);
+  const [olderSpec, newerSpec] = [await read(older), await read(newer)];
+  if (!olderSpec)
+    return { error: IMPACT_WORDS.notASpec(older.path) };
+  if (!newerSpec)
+    return { error: IMPACT_WORDS.notASpec(newer.path) };
+  const estate = await estateFacts(root, op, "");
+  const repos = joinReposOf(op, estate.repos);
+  const flows = [];
+  for (const [id, f] of await specFlowFiles(root).catch(() => /* @__PURE__ */ new Map())) {
+    const flow = await readFlow(root, f.repo, id).catch(() => void 0);
+    if (!flow)
+      continue;
+    flows.push({
+      id,
+      repo: f.repo,
+      ...flow.trigger.ref ? { trigger: flow.trigger.ref } : {},
+      refs: flow.steps.flatMap((s) => s.refs ?? [])
+    });
+  }
+  const systemOfRepo = Object.fromEntries(estateRepos(op).flatMap((r) => r.system ? [[r.id, r.system]] : []));
+  const team = system.boundary !== "vendor" && outsideProfileSystems(op).some((s) => s.id === system.id);
+  const hosts = hostAliases(system.aliases);
+  const { diff, impact } = vendorImpact({
+    vendor: {
+      system: systemId,
+      names: [system.name, ...system.aliases],
+      ...hosts.length ? { hosts } : {},
+      ...team ? { boundary: "internal" } : {}
+    },
+    older: { id: older.id, spec: olderSpec },
+    newer: { id: newer.id, spec: newerSpec },
+    repos,
+    targets: estate.targets,
+    // The org pack's facing words and gateway bundle folders (ADR 0147), as the catalog joins.
+    ...joinConventions(op),
+    flows,
+    systemOfRepo
+  });
+  const facts = /* @__PURE__ */ new Map();
+  for (const r of estate.repos)
+    for (const f of r.facts)
+      facts.set(`${r.repo}\0${f.id}`, f);
+  return { name: system.name, diff, impact, notes: estate.notes, facts };
+}
+var where = (e) => `${e.repo} ${e.at}`;
+var callWhat = (l, e) => {
+  const call = l.facts.get(`${e.repo}\0${e.fact}`);
+  return call?.kind === "call" ? [call.method?.toUpperCase(), call.path].filter(Boolean).join(" ") : e.fact;
+};
+var fieldWords = (s, field) => s.field ? s.field.uses === "sends" || s.field.uses === "reads" ? `, ${s.field.uses} ${field}${s.field.at ? ` (${s.field.at})` : ""}` : `, ${s.field.uses === "does-not-send" ? "doesn't send" : "doesn't read"} ${field}` : "";
+var upstreamLine = (u, indent) => {
+  const uvia = u.via?.length ? `, through ${u.via.join(" \u2192 ")}` : "";
+  return `${indent}\u2190 ${u.call.component}: ${where(u.call)}${uvia}${u.under ? `, under ${where(u.under)}` : ""}`;
+};
+function impactLines(l) {
+  const { impact, diff } = l;
+  const out = [];
+  out.push(IMPACT_WORDS.header(l.name, impact.older, impact.newer));
+  out.push(IMPACT_WORDS.counts(diff.length, diff.filter((c) => c.severity === "breaking").length));
+  const byId = new Map(diff.map((c) => [c.id, c]));
+  for (const c of impact.changes) {
+    const d = byId.get(c.id);
+    out.push("");
+    out.push(`${IMPACT_WORDS.severity[c.severity]}: ${c.says}`);
+    const cites = [
+      ...d.before ? [`was ${d.before.cite}`] : [],
+      ...d.after ? [`now ${d.after.cite}`] : []
+    ];
+    if (cites.length)
+      out.push(`  ${cites.join(", ")}`);
+    if (!c.forwards.length)
+      out.push(`  ${IMPACT_WORDS.reachesNothing}`);
+    for (const f of c.forwards) {
+      if (f.direct) {
+        const s = f.callers[0];
+        out.push(`  ${IMPACT_WORDS.direct(f.call.component, callWhat(l, f.call), where(f.call), l.name)}${fieldWords(s, d.field)}`);
+        if (s.under)
+          out.push(`    under ${where(s.under)}`);
+        for (const u of s.upstream)
+          out.push(upstreamLine(u, "    "));
+        continue;
+      }
+      const to = f.tie ? `to ${l.name} through ${f.tie.at}` : `to ${l.name}`;
+      out.push(`  forwarded by ${f.call.component}: ${callWhat(l, f.call)}, ${where(f.call)} (${to})`);
+      for (const s of f.callers) {
+        const via = s.via?.length ? `, through ${s.via.join(" \u2192 ")}` : "";
+        out.push(`    called by ${s.call.component}: ${where(s.call)}${fieldWords(s, d.field)}${via}`);
+        if (s.under)
+          out.push(`      under ${where(s.under)}`);
+        for (const u of s.upstream)
+          out.push(upstreamLine(u, "      "));
+      }
+    }
+  }
+  if (impact.gaps.length || impact.asks.length)
+    out.push("");
+  for (const g of impact.gaps)
+    out.push(IMPACT_WORDS.gap(g.message, where(g.call)));
+  for (const a of impact.asks)
+    out.push(IMPACT_WORDS.ask(a.question));
+  out.push("");
+  out.push(impact.repos.length ? IMPACT_WORDS.affected(impact.repos, impact.flows.map((f) => f.id)) : IMPACT_WORDS.nothingAffected);
+  return out;
+}
+async function intakeImpact(root, spec, o, io) {
+  if (!spec) {
+    io.err(IMPACT_WORDS.usage);
+    return 2;
+  }
+  const l = await loadVendorImpact(root, spec, io);
+  if ("error" in l) {
+    io.err(l.error);
+    return 1;
+  }
+  for (const n of l.notes)
+    io.err(n);
+  const reaches = l.impact.changes.some((c) => c.severity === "breaking" && c.forwards.length > 0);
+  if (o.json) {
+    io.out(JSON.stringify({ diff: l.diff, impact: l.impact }, null, 2));
+    return reaches ? 1 : 0;
+  }
+  for (const line of impactLines(l))
+    io.out(line);
+  if (l.impact.repos.length)
+    io.out(IMPACT_WORDS.start(l.impact.newer.path));
+  return reaches ? 1 : 0;
+}
+function impactDocument(l) {
+  const version = l.impact.newer.version ?? l.impact.newer.id;
+  return {
+    name: `${slug(`${l.name} ${version}`)}-impact.md`,
+    text: [IMPACT_WORDS.docTitle(l.name, version), "", ...impactLines(l), ""].join("\n")
+  };
+}
+export {
+  IMPACT_WORDS,
+  impactDocument,
+  impactLines,
+  intakeImpact,
+  loadVendorImpact
+};

package/dist/chunk-T4RTWMJD.js

@@ -0,0 +1,310 @@
+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 {
+  nearRepos
+} from "./chunk-MKFYQQ5Q.js";
+import {
+  gitUser,
+  loadRepos
+} from "./chunk-PGKHJYOB.js";
+import {
+  ManifestEditError,
+  REPO_DESCRIPTION_MAX,
+  RecordId,
+  RepoDescription,
+  addManifestRepo,
+  descriptionLine,
+  factsDirOf,
+  manifestFiles,
+  parseFacts,
+  setManifestDescription
+} from "./chunk-577AJVRS.js";
+import "./chunk-D3PO4DOZ.js";
+import "./chunk-TV45EUGM.js";
+
+// packages/cli/dist/repo-commands.js
+import { readFile, stat } from "node:fs/promises";
+import { basename, dirname, join, resolve } from "node:path";
+import { createInterface } from "node:readline/promises";
+import { stdin, stdout } from "node:process";
+var askOnTerminal = async (prompt) => {
+  if (!stdin.isTTY)
+    return void 0;
+  const rl = createInterface({ input: stdin, output: stdout });
+  try {
+    return (await rl.question(`${prompt} `)).trim() || void 0;
+  } finally {
+    rl.close();
+  }
+};
+var ASK = "What is this repo, in one line? (what it is for, who uses it; Enter to skip and write it later)";
+function idFromUrl(url) {
+  const last = url.replace(/[/\\]+$/, "").split(/[/\\:]/).pop() ?? "";
+  return last.replace(/\.git$/i, "").toLowerCase().replace(/[^a-z0-9._-]+/g, "-").replace(/^-+|-+$/g, "") || "repo";
+}
+var trimmed = (t) => {
+  const s = t?.trim();
+  return s ? s.slice(0, REPO_DESCRIPTION_MAX) : void 0;
+};
+function written(text, by, now) {
+  return RepoDescription.parse({
+    text,
+    trust: "verified",
+    by,
+    at: now.toISOString().replace(/\.\d{3}Z$/, "Z")
+  });
+}
+async function declaredFrameworks(root, repo) {
+  const text = await readFile(join(factsDirOf(root), `${repo}.jsonl`), "utf8").catch(() => void 0);
+  if (text === void 0)
+    return [];
+  const p = parseFacts(text);
+  if (!p.ok)
+    return [];
+  return p.facts.flatMap((f) => f.kind === "framework" ? [{ name: f.name, cite: `${f.cite.file}:${f.cite.line}` }] : []);
+}
+async function typeOf(url, description, frameworks = []) {
+  if (/^[a-z][a-z0-9+.-]*:\/\//i.test(url) || /^[^/\\]+@/.test(url))
+    return void 0;
+  const dir = resolve(url);
+  if (!await stat(dir).then((s) => s.isDirectory(), () => false))
+    return void 0;
+  const [{ detectRepoType }, { fsRepo }] = await Promise.all([
+    import("./chunk-QKEFZRHS.js"),
+    import("./chunk-YGKYFMSL.js")
+  ]);
+  const d = await detectRepoType(fsRepo(basename(dir), dir, "0".repeat(40)), {
+    ...description ? { description } : {},
+    ...frameworks.length ? { frameworks } : {}
+  });
+  return d.type === "unknown" ? void 0 : { type: d.type, signals: d.signals, confidence: d.confidence };
+}
+async function cloneAt(url) {
+  if (/^[a-z][a-z0-9+.-]*:\/\//i.test(url) || /^[^/\\]+@/.test(url))
+    return void 0;
+  const dir = resolve(url);
+  if (!await stat(join(dir, ".git")).catch(() => void 0))
+    return void 0;
+  const { execFile } = await import("node:child_process");
+  const git = (...args) => new Promise((done) => execFile("git", args, { cwd: dir }, (e, out) => done(e ? "" : String(out).trim())));
+  const origin = await git("config", "--get", "remote.origin.url");
+  const branch = await git("rev-parse", "--abbrev-ref", "HEAD");
+  return {
+    dir,
+    ...origin ? { origin } : {},
+    ...branch && branch !== "HEAD" ? { branch } : {}
+  };
+}
+async function whoFor(root, d) {
+  if (d.by)
+    return d.by;
+  try {
+    return (await gitUser(root)).handle;
+  } catch {
+    return "someone";
+  }
+}
+async function repoAdd(root, url, o, io, deps = {}) {
+  if (!url?.trim()) {
+    io.err('Usage: atticus repo add <clone URL or path> [--id id] [--type repo type] [--owner team] [--description "what it is"].');
+    return 2;
+  }
+  const clone = await cloneAt(url.trim());
+  const id = o.id?.trim() || idFromUrl(url.trim());
+  if (!RecordId.safeParse(id).success) {
+    io.err(`${id} isn't a repo id: ids are lowercase slugs (a-z, 0-9, '.', '_' and '-'). Give one with --id.`);
+    return 2;
+  }
+  const files = await manifestFiles(root);
+  const platform = o.platform?.trim() || (files.length === 1 ? files[0].platform : void 0);
+  if (!platform) {
+    io.err(files.length ? `There are ${files.length} platform profiles (${files.map((f) => f.platform).join(", ")}): say which with --platform.` : "The org pack has no platform profile yet (org-pack/profiles/<platform>/repos.manifest.yaml). Run atticus repos discover <folder of clones>, or atticus init first.");
+    return 2;
+  }
+  let text = trimmed(o.description);
+  let asked = false;
+  if (!text && !o.noDescription && !o.json) {
+    text = trimmed(await (deps.ask ?? askOnTerminal)(`${id}: ${ASK}`));
+    asked = true;
+  }
+  const by = await whoFor(root, deps);
+  const description = text ? written(text, by, deps.now ?? /* @__PURE__ */ new Date()) : void 0;
+  const detected = o.type?.trim() ? void 0 : await typeOf(url.trim(), text, await declaredFrameworks(root, id));
+  const listed = await loadRepos(root).catch(() => []);
+  const near = nearRepos({ id, url: clone?.origin ?? url.trim() }, listed);
+  try {
+    const file = await addManifestRepo(root, platform, {
+      id,
+      url: clone?.origin ?? url.trim(),
+      ...clone?.branch ? { defaultBranch: clone.branch } : {},
+      type: o.type?.trim() || detected?.type || "unknown",
+      owner: o.owner?.trim() || "unassigned",
+      ...o.system?.trim() ? { system: o.system.trim() } : {},
+      ...o.component?.trim() ? { component: o.component.trim() } : {},
+      ...description ? { description } : {}
+    });
+    for (const n of near)
+      io.err(`Warning: ${id} looks like ${n.id}, already listed (${n.why}). If they are one repo, remove this entry from ${file.rel}, or keep one id: atticus repo rename <old> <new>.`);
+    if (o.json) {
+      io.out(JSON.stringify({ repo: id, platform, file: file.rel, description, ...near.length ? { near } : {} }, null, 2));
+      return 0;
+    }
+    io.out(`Added ${id} to ${file.rel}: commit it in a pull request.`);
+    if (detected)
+      io.out(`Type: ${detected.type}, from ${detected.signals.join(", ")} (${detected.confidence} confidence). Change it in the manifest if it is wrong.`);
+    if (description)
+      io.out(`What it is: ${description.text}`);
+    else
+      io.out(`${id} has no description yet${asked ? "" : " (--description, or atticus repo describe)"}: atticus repo describe ${id} --description "what it is". Until then its reading prompts, the join's questions and the views have only its id to go on.`);
+    io.out(clone?.origin ? `From your clone: ${clone.origin}, branch ${clone.branch ?? "main"}. Next: atticus workspace sync --from "${dirname(clone.dir)}" --repos ${id} (copied from it, no network), then read it: /atticus-map ${id}.` : `Next: atticus workspace sync, then read it: /atticus-map ${id}.`);
+    return 0;
+  } catch (e) {
+    if (e instanceof ManifestEditError) {
+      io.err(e.message);
+      return e.code === "not-found" ? 2 : 1;
+    }
+    throw e;
+  }
+}
+async function undescribedRepos(root) {
+  const repos = await loadRepos(root).catch(() => []);
+  const missing = [];
+  const unconfirmed = [];
+  for (const r of repos) {
+    if (r.archived)
+      continue;
+    if (!r.description)
+      missing.push(r.id);
+    else if (r.description.trust === "suggested")
+      unconfirmed.push({ id: r.id, text: r.description.text });
+  }
+  return { missing, unconfirmed };
+}
+async function repoDescribe(root, repo, o, io, deps = {}) {
+  if (!repo?.trim()) {
+    const { missing, unconfirmed } = await undescribedRepos(root);
+    if (o.json) {
+      io.out(JSON.stringify({ missing, unconfirmed }, null, 2));
+      return 0;
+    }
+    if (!missing.length && !unconfirmed.length) {
+      io.out("Every repo of the manifests says what it is.");
+      return 0;
+    }
+    if (missing.length) {
+      io.out(`${missing.length} repo${missing.length === 1 ? " has" : "s have"} no description:`);
+      for (const id2 of missing)
+        io.out(`  ${id2}: atticus repo describe ${id2} --description "..."`);
+    }
+    if (unconfirmed.length) {
+      io.out(`${unconfirmed.length} description${unconfirmed.length === 1 ? " was" : "s were"} drafted by your assistant and nobody has confirmed ${unconfirmed.length === 1 ? "it" : "them"} yet:`);
+      for (const u of unconfirmed)
+        io.out(`  ${u.id}: "${u.text}" \u2014 atticus repo describe ${u.id} --accept`);
+    }
+    return 0;
+  }
+  const id = repo.trim();
+  const found = (await loadRepos(root).catch(() => [])).find((r) => r.id === id);
+  if (!found) {
+    io.err(`There is no repo ${id} in any repos.manifest.yaml.`);
+    return 2;
+  }
+  const now = deps.now ?? /* @__PURE__ */ new Date();
+  const at = now.toISOString().replace(/\.\d{3}Z$/, "Z");
+  if (o.drafted !== void 0) {
+    const cites = (o.cites ?? "").split(",").map((c) => c.trim()).filter(Boolean).flatMap((c) => {
+      const m = /^(.*):(\d+)$/.exec(c);
+      return m && Number(m[2]) > 0 ? [{ file: m[1], line: Number(m[2]) }] : [];
+    });
+    if (!cites.length) {
+      io.err(`Say where you read it: atticus repo describe ${id} --drafted "..." --cites <file>:<line> (several separated by commas), as a fact cites its line.`);
+      return 2;
+    }
+    const r = await keepDraftedDescription(root, id, { text: o.drafted, cites }, now);
+    if (o.json) {
+      io.out(JSON.stringify({ repo: id, ...r }, null, 2));
+      return r.kept ? 0 : 1;
+    }
+    if (!r.kept) {
+      io.err(`The draft wasn't kept: ${r.why ?? "it wasn't one line"}.`);
+      return 1;
+    }
+    io.out(`${id}: "${o.drafted.trim()}" \u2014 kept as a draft, unconfirmed, with the lines you read it from. A person confirms it (atticus repo describe ${id} --accept), changes it or drops it.`);
+    return 0;
+  }
+  let next;
+  if (o.reject) {
+    if (!found.description) {
+      io.err(`${id} has no description to reject.`);
+      return 2;
+    }
+    next = void 0;
+  } else {
+    let text = trimmed(o.description);
+    if (!text && o.accept) {
+      if (!found.description) {
+        io.err(`${id} has no description to confirm. Write one: atticus repo describe ${id} --description "what it is".`);
+        return 2;
+      }
+      text = found.description.text;
+    }
+    if (!text && !o.json)
+      text = trimmed(await (deps.ask ?? askOnTerminal)(`${id}: ${ASK}`));
+    if (!text) {
+      io.err(`Say what ${id} is: atticus repo describe ${id} --description "what it is" (or --accept to keep the draft, --reject to drop it).`);
+      return 2;
+    }
+    next = written(text, await whoFor(root, deps), now);
+  }
+  try {
+    const file = await setManifestDescription(root, id, next);
+    if (o.json) {
+      io.out(JSON.stringify({ repo: id, file: file.rel, description: next ?? null }, null, 2));
+      return 0;
+    }
+    io.out(next ? `${id}: ${descriptionLine(next)}` : `${id}: the description was dropped; nothing says what it is now.`);
+    io.out(`Written to ${file.rel} at ${at}: commit it in a pull request.`);
+    return 0;
+  } catch (e) {
+    if (e instanceof ManifestEditError) {
+      io.err(e.message);
+      return e.code === "not-found" ? 2 : 1;
+    }
+    throw e;
+  }
+}
+async function keepDraftedDescription(root, repo, draft, now) {
+  const found = (await loadRepos(root).catch(() => [])).find((r) => r.id === repo);
+  if (!found)
+    return { kept: false, why: `${repo} isn't in any repos.manifest.yaml` };
+  if (found.description)
+    return {
+      kept: false,
+      why: found.description.trust === "verified" ? `${repo} already says what it is, in a person's words` : `${repo} already has a drafted description waiting for a person`
+    };
+  const text = trimmed(draft.text);
+  if (!text)
+    return { kept: false, why: "the draft was empty" };
+  const d = RepoDescription.safeParse({
+    text,
+    trust: "suggested",
+    by: draft.by ?? "assistant",
+    at: now.toISOString().replace(/\.\d{3}Z$/, "Z"),
+    cites: (draft.cites ?? []).slice(0, 6)
+  });
+  if (!d.success)
+    return { kept: false, why: d.error.issues[0]?.message ?? "the draft wasn't one line" };
+  await setManifestDescription(root, repo, d.data);
+  return { kept: true };
+}
+export {
+  askOnTerminal,
+  idFromUrl,
+  keepDraftedDescription,
+  repoAdd,
+  repoDescribe,
+  undescribedRepos
+};