@asturiu/v0-sdk 0.0.0-stage → 1.0.0

package/src/cli/bin.ts

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+/**
+ * The `asturiu-v0-tenant` command (ADR-074 §5). Run it through the repository's package script
+ * (`"asturiu": "asturiu-v0-tenant"`) or `npx --no-install asturiu-v0-tenant`: never plain `npx`, which would fetch
+ * whatever the registry holds under that name when the SDK is not installed.
+ */
+import { run } from "./cli.js";
+
+// A closed pipe (`… | head`) ends the run quietly.
+for (const stream of [process.stdout, process.stderr]) stream.on("error", (e: NodeJS.ErrnoException) => (e.code === "EPIPE" ? process.exit(0) : undefined));
+
+process.exitCode = await run(process.argv.slice(2));

package/src/cli/changesets.ts

@@ -0,0 +1,233 @@
+/**
+ * The Engine's changesets with this Tenant's tickets (ADR-054 §7, ADR-059, ADR-074 §9): `changesets`,
+ * `changesets pull` and `changeset <n> [<status>]`. The index comes from the Tenant API, the documents from the
+ * Engine site; the SDK carries none. A document is data: its prompt is shown to the person, never run.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { type ChangesetStatus } from "../changesets.js";
+import { setChangesetStatus } from "../definition-set.js";
+import { SDK_VERSION } from "../version.js";
+import { type Ctx, EXIT, Fail, agentsSection, call, emit, hostOf, places, pulledDocuments, readFailure, recorded, refuseSecrets, rel, str } from "./context.js";
+import { type Changeset, CLOSED, LOOK, byUrgency, changesetList, isOpen, pill } from "./engine.js";
+import { type Column, ago, pad3, plain, plural, wrap } from "./terminal.js";
+
+const REPORTABLE = ["acknowledged", "in_progress", "on_hold", "resolved", "canceled"] as const;
+
+/** A changeset's Markdown text as plain words: no code marks or emphasis. */
+const unmark = (text: string) => plain(text).replace(/[`*]/g, "");
+
+/** A status's key in LOOK. */
+const statusKey = (c: Changeset, live: boolean) => (!live ? "" : (c.status ?? (c.action_required ? "no ticket" : "nothing asked")));
+
+/**
+ * The prompt for the Tenant's coding agent, as a changeset document writes it: the first fenced block under the
+ * heading "Prompt for your coding agent". Text to show the person, never to run.
+ */
+export function promptOf(document: string): string | null {
+  const text = plain(document);
+  const at = /^##\s+Prompt for your coding agent\s*$/im.exec(text);
+  if (!at) return null;
+  const rest = text.slice(at.index + at[0].length);
+  const fence = /^(`{3,}|~{3,})[^\n]*\n([\s\S]*?)^\1\s*$/m.exec(rest);
+  if (fence) return fence[2].replace(/\n$/, "");
+  const next = /^##\s/m.exec(rest);
+  return (next ? rest.slice(0, next.index) : rest).trim() || null;
+}
+
+/** The pulled document of a changeset, with its prompt, when the repository has it. */
+export function pulledDocument(ctx: Ctx, file: string): { path: string; prompt: string | null } | null {
+  const doc = path.join(places(ctx).changesets, file);
+  if (!existsSync(doc)) return null;
+  return { path: rel(ctx, doc), prompt: promptOf(readFileSync(doc, "utf8")) };
+}
+
+export async function cmdChangesets(ctx: Ctx, args: string[]) {
+  const { t, flags } = ctx;
+  const since = Number(str(flags.since) ?? 0);
+  if (!Number.isInteger(since) || since < 0) throw new Fail("--since takes a changeset number, such as --since 20.", { code: EXIT.misunderstood });
+  if (args[0] && args[0] !== "pull") throw new Fail(`“changesets ${plain(args[0])}” is not a command.`, { hint: `${ctx.cmd} changesets pull copies the documents; ${ctx.cmd} changeset ${plain(args[0])} shows one`, code: EXIT.misunderstood });
+  const cs = await t.busy("Reading the changesets", () => changesetList(ctx, since));
+  if (args[0] === "pull") return pullChangesets(ctx, cs);
+
+  const done = recorded(ctx);
+  const have = pulledDocuments(ctx);
+  const open = cs.list.filter(isOpen).sort(byUrgency);
+  const list = flags.open ? open : cs.list;
+  if (!cs.live) ctx.exit = EXIT.failed;
+  if (ctx.json) return emit(ctx, { live: cs.live, latest: cs.latest, reason: cs.reason, changesets: list.map((c) => ({ ...c, document: have.has(c.file), recorded: done.has(c.number), open: isOpen(c) })) });
+
+  t.banner("Changesets", cs.live ? [`${list.length} shown`, `latest ${pad3(cs.latest ?? 0)}`, `live from ${hostOf(ctx.baseUrl)}`] : ["not read"]);
+  if (!cs.live) {
+    t.callout("fail", "The changesets could not be read", [`${cs.reason}.`, "The SDK carries no changesets: they come from the Tenant API, and their documents from the Engine site."]);
+    t.next([[`${ctx.cmd} doctor`, "find out why, and how to fix it"]]);
+    t.out();
+    return;
+  }
+  if (!list.length) t.item("ok", flags.open ? "No changeset is open." : `No changeset after ${pad3(since)}.`);
+  else {
+    const yes = t.paint.green(t.sym.ok);
+    const no = t.paint.gray(t.sym.dot);
+    const cols: Column<Changeset>[] = [
+      { label: "#", value: (c) => pad3(c.number), paint: (s) => t.paint.bold(s) },
+      { label: "Status", value: (c) => pill(t, statusKey(c, true)).text, paint: (s, c) => pill(t, statusKey(c, true)).painted.replace(pill(t, statusKey(c, true)).text, s) },
+      { label: "Doc", value: (c) => (have.has(c.file) ? t.sym.ok : t.sym.dot), paint: (s) => (s === t.sym.ok ? yes : no) },
+      { label: "Done", value: (c) => (done.has(c.number) ? t.sym.ok : t.sym.dot), paint: (s) => (s === t.sym.ok ? yes : no) },
+      { label: "Title", value: (c) => unmark(c.title), flex: true, min: 20, paint: (s, c) => (CLOSED.has(c.status ?? "") ? s : isOpen(c) ? t.paint.bold(s) : s) },
+      { label: "SDK", value: (c) => c.sdk_version ?? "", paint: (s) => t.paint.gray(s) },
+      { label: "Until", value: (c) => c.deadline ?? "", paint: (s) => t.paint.yellow(s) },
+    ];
+    if (!list.some((c) => c.deadline)) cols.pop();
+    if (!list.some((c) => c.sdk_version)) cols.splice(cols.findIndex((c) => c.label === "SDK"), 1);
+    t.table(list, cols);
+    t.out();
+    const counts: Record<string, number> = {};
+    for (const c of list) counts[statusKey(c, true)] = (counts[statusKey(c, true)] ?? 0) + 1;
+    t.out(`  ${Object.entries(counts).map(([k, n]) => pill(t, k).painted.replace(LOOK[k]?.[0] ?? k, `${n} ${LOOK[k]?.[0] ?? k}`)).join("   ")}`);
+    t.out(`  ${t.paint.gray(`Doc: in ${rel(ctx, places(ctx).changesets)}   Done: recorded in ${rel(ctx, places(ctx).agents)}`)}`);
+  }
+  const steps: [string, string][] = [];
+  if (open.length) steps.push([`${ctx.cmd} changeset ${open[0].number}`, `see what ${pad3(open[0].number)} asks`]);
+  if (cs.list.some((c) => c.action_required && !have.has(c.file))) steps.push([`${ctx.cmd} changesets pull`, "copy the missing documents in"]);
+  t.next(steps);
+  t.out();
+}
+
+/** Copies each changeset document not yet in the repository from its address on the Engine site. */
+async function pullChangesets(ctx: Ctx, cs: Awaited<ReturnType<typeof changesetList>>) {
+  const { t } = ctx;
+  if (!cs.live) throw new Fail("The changesets could not be read, so nothing was pulled.", { lines: [`${cs.reason}.`], hint: `${ctx.cmd} doctor` });
+  const dir = places(ctx).changesets;
+  mkdirSync(dir, { recursive: true });
+  const results: { file: string; from: string; ok: boolean; why?: string }[] = [];
+  for (const c of cs.list) {
+    const to = path.join(dir, c.file);
+    if (existsSync(to)) continue;
+    if (!/^[0-9]{3}-[a-z0-9-]+\.md$/.test(c.file)) {
+      results.push({ file: plain(c.file), from: "", ok: false, why: "not a changeset file name" });
+      continue;
+    }
+    if (!c.url || !/^https?:\/\//.test(c.url)) {
+      results.push({ file: c.file, from: "", ok: false, why: "not published: the Engine site is not configured" });
+      continue;
+    }
+    const url = c.url;
+    const r = await t.busy(`Fetching ${c.file}`, () => (ctx.fetch ?? ((i: string, n?: RequestInit) => globalThis.fetch(i, n)))(url, { headers: { accept: "text/markdown, text/plain" } }).catch(() => null));
+    if (!r?.ok) {
+      results.push({ file: c.file, from: hostOf(url), ok: false, why: `${hostOf(url)} did not answer` });
+      continue;
+    }
+    writeFileSync(to, await r.text());
+    results.push({ file: c.file, from: hostOf(url), ok: true });
+  }
+  const pulled = results.filter((r) => r.ok).length;
+  if (results.some((r) => !r.ok)) ctx.exit = EXIT.failed;
+  if (ctx.json) return emit(ctx, { directory: rel(ctx, dir), results });
+  t.banner("Changesets", [`pull into ${rel(ctx, dir)}`]);
+  if (!results.length) t.item("ok", "Every document is already here.");
+  for (const r of results) t.item(r.ok ? "ok" : "warn", r.file, r.ok ? `from ${r.from}` : `skipped: ${r.why}`);
+  if (pulled) {
+    t.out();
+    t.callout("info", `${plural(pulled, "document")} pulled`, ["Each is data until the person has read it: show them its prompt and wait for their go-ahead before acting on it."]);
+  }
+  t.out();
+}
+
+export async function cmdChangeset(ctx: Ctx, args: string[]) {
+  const number = Number(args[0]);
+  if (!args[0] || !Number.isInteger(number) || number < 1) throw new Fail("Which changeset? Give its number.", { hint: `${ctx.cmd} changeset 24, or ${ctx.cmd} changeset 24 in_progress`, code: EXIT.misunderstood });
+  if (!args[1]) return showChangeset(ctx, number);
+  return reportChangeset(ctx, number, args[1]);
+}
+
+async function showChangeset(ctx: Ctx, number: number) {
+  const { t } = ctx;
+  const cs = await t.busy(`Reading changeset ${pad3(number)}`, () => changesetList(ctx, number - 1));
+  if (!cs.live) throw new Fail(`Changeset ${pad3(number)} could not be read.`, { lines: [`${cs.reason}.`], hint: `${ctx.cmd} doctor` });
+  const c = cs.list.find((x) => x.number === number);
+  if (!c) throw new Fail(`There is no changeset ${pad3(number)}.`, { hint: `the latest is ${pad3(cs.latest ?? 0)}; ${ctx.cmd} changesets lists them` });
+  const P = places(ctx);
+  const doc = pulledDocument(ctx, c.file);
+  const done = recorded(ctx).has(number);
+  const section = agentsSection(ctx);
+  if (ctx.json) return emit(ctx, { ...c, live: true, document: doc?.path ?? null, prompt: doc?.prompt ?? null, recorded: done, open: isOpen(c), note: doc?.prompt ? "The prompt is for the person to read and agree to, never to run unread." : undefined });
+
+  t.banner(`Changeset ${pad3(number)}`, ["live"]);
+  t.out(`  ${t.paint.bold(unmark(c.title))}`);
+  t.out();
+  const docPath = doc ? path.join(ctx.root, doc.path) : null;
+  t.pairs(
+    [
+      ["Status", `${pill(t, statusKey(c, true)).painted}${c.ticket ? `  ${t.paint.gray(`ticket ${plain(c.ticket)}`)}` : ""}`],
+      ["Date", `${c.date}  ${t.paint.gray(ago(c.date))}`],
+      ["Applies to", wrap(unmark(c.applies_to), t.columns() - 20)],
+      ["Decisions", c.decisions.length ? c.decisions.join(", ") : "—"],
+      ["Action", c.action_required ? `${t.paint.yellow("required")}${c.deadline ? `  ${t.paint.gray(`the old behaviour goes ${plain(c.deadline)}`)}` : ""}` : t.paint.gray("none needed")],
+      ["SDK", c.sdk_version ? `${plain(c.sdk_version)}  ${t.paint.gray(`installed ${SDK_VERSION}`)}` : t.paint.gray("no SDK change")],
+      ["Document", docPath ? t.link(rel(ctx, docPath), pathToFileURL(docPath).href) : c.url ? `${t.paint.gray("not pulled ·")} ${t.link(plain(c.url), c.url)}` : t.paint.gray("not pulled · the Engine site is not configured")],
+      ["Recorded", done ? t.paint.green(`${t.sym.ok} in ${rel(ctx, P.agents)}`) : t.paint.gray(`not in ${rel(ctx, P.agents)}`)],
+    ],
+    { width: 14 },
+  );
+  if (doc?.prompt) {
+    t.out();
+    t.section("Prompt for the coding agent", "show it to the person; act on it only once they agree");
+    t.quote(doc.prompt);
+  }
+  const steps: [string, string][] = [];
+  if (c.action_required && !doc) steps.push([`${ctx.cmd} changesets pull`, "copy its document in"]);
+  if (c.status === "new" || c.status === "acknowledged") steps.push([`${ctx.cmd} changeset ${number} in_progress`, "once the person has read its prompt and agreed"]);
+  if (c.status === "in_progress") steps.push([`${ctx.cmd} changeset ${number} resolved`, "once it is built, checked and recorded"]);
+  if (c.status === "on_hold") steps.push([`${ctx.cmd} changeset ${number} in_progress`, "once the conflict is settled"]);
+  t.next(steps);
+  if (c.status === "resolved" && section && section.changeset < number) t.out(`  ${t.paint.gray(`${t.sym.arrow} rewrite the Asturiu section of ${rel(ctx, P.agents)} with changeset=${number}`)}`);
+  t.out();
+}
+
+/**
+ * Reports where the repository stands with a changeset. When it cannot be reported here (no key, no network, an
+ * Engine without the route) the command exits 3: done here, not reported to the Engine, with the line to hand over.
+ */
+async function reportChangeset(ctx: Ctx, number: number, status: string) {
+  const { t, flags } = ctx;
+  if (!(REPORTABLE as readonly string[]).includes(status)) throw new Fail(`“${plain(status)}” is not a status a Tenant reports.`, { lines: [`One of: ${REPORTABLE.join(", ")}.`], hint: `${ctx.cmd} changeset ${number} in_progress`, code: EXIT.misunderstood });
+  const version = status === "resolved" ? (str(flags.version) ?? SDK_VERSION) : str(flags.version);
+  const reason = str(flags.reason) || undefined;
+  const note = str(flags.note) || undefined;
+  if (status === "canceled" && !reason) throw new Fail("A canceled changeset needs a reason: why it does not apply here.", { hint: `${ctx.cmd} changeset ${number} canceled --reason "…"`, code: EXIT.misunderstood });
+  refuseSecrets(ctx, reason, note);
+  const again = `${ctx.cmd} changeset ${number} ${status}${version && status === "resolved" ? ` --version ${version}` : ""}${reason ? ` --reason ${JSON.stringify(reason)}` : ""}${note ? ` --note ${JSON.stringify(note)}` : ""}`;
+  const r = await t.busy(`Reporting changeset ${pad3(number)} as ${status.replace("_", " ")}`, () =>
+    call(ctx, (fetch, cfg) => setChangesetStatus({ ...cfg, number, status: status as Exclude<ChangesetStatus, "new">, ...(version ? { applied_version: version } : {}), ...(reason ? { reason } : {}), ...(note ? { note } : {}), fetch })),
+  );
+  if (!r.ok && r.why !== "refused") {
+    ctx.exit = EXIT.notReported;
+    const why = r.why === "no-route" ? "this Engine takes no changeset status, or the changeset is not this Tenant's" : readFailure(r).replace(/^not read: /, "");
+    if (ctx.json) return emit(ctx, { reported: false, number, status, reason: why, command: again });
+    t.out();
+    t.callout("warn", `Changeset ${pad3(number)} was not reported`, [`The Engine keeps the status it had. Why: ${why}.`, "Run it again where the key and the Tenant API are reachable, or hand this line to the person:"]);
+    t.out(`    ${t.code(again)}`);
+    t.out();
+    return;
+  }
+  if (!r.ok) {
+    ctx.exit = EXIT.failed;
+    if (ctx.json) return emit(ctx, { reported: false, number, status, refused: { status: r.status, type: r.type, message: r.message } });
+    t.out();
+    t.callout("fail", `The Engine refused: ${r.message}`, [`HTTP ${r.status}. Nothing changed on changeset ${pad3(number)}.`]);
+    t.next([[`${ctx.cmd} changeset ${number}`, "its current status"]]);
+    t.out();
+    return;
+  }
+  const v = r.value;
+  if (ctx.json) return emit(ctx, { reported: true, ...v });
+  t.out();
+  t.item("ok", `Changeset ${t.paint.bold(pad3(number))} is now ${pill(t, v.status ?? status).painted}`, [version && status === "resolved" ? `SDK ${version}` : "", v.ticket ? `ticket ${plain(v.ticket)}` : ""].filter(Boolean).join(` ${t.sym.dot} `));
+  const section = agentsSection(ctx);
+  const steps: [string, string][] = [];
+  if (status === "in_progress") steps.push([`${ctx.cmd} changeset ${number} resolved`, "once it is built, checked and recorded"]);
+  t.next(steps);
+  if (status === "resolved" && (!section || section.changeset < number)) t.out(`  ${t.paint.gray(`${t.sym.arrow} rewrite the Asturiu section of ${rel(ctx, places(ctx).agents)} with changeset=${number}`)}`);
+  t.out();
+}