@cohortapp/agent-sdk 2.11.15 → 2.13.0

package/lib/cli/design.mjs

@@ -0,0 +1,185 @@
+/**
+ * lib/cli/design.mjs — `maestro design sync`.
+ *
+ *   maestro design sync [--out <dir>] [--json]
+ *
+ * Pulls the workspace's SAVED brand foundation from hq (`branding.getFoundation`
+ * — the same read the `design_foundation` tool makes; drafts are never visible
+ * to a seat) and lands it as `DESIGN.md` + `PRODUCT.md` in the agent dir, plus
+ * the raw snapshot at `state/design/foundation.json`. Design skills read those
+ * files; this command is how they stop being fiction.
+ *
+ * FAIL POSTURE. A fetch that fails writes NOTHING and exits non-zero with the
+ * server's own message. That is deliberate and is the opposite of the daemon's
+ * posture: a human who typed `design sync` is owed the error, whereas a
+ * background poll must never overwrite a good DESIGN.md with a half-answer from
+ * an hq that was briefly down. Nothing here throws — expected failures are
+ * printed and become exit 1.
+ *
+ * IDEMPOTENT. Re-running against an unchanged foundation rewrites no file (the
+ * comparison is on rendered bytes — `lib/design/write.mjs#syncDesign`), so a
+ * cron-y re-sync leaves mtimes and the git tree alone.
+ *
+ * `runDesign(argv, deps)` is the testable core (every I/O injectable);
+ * `designCmd(argv)` is the bin entry.
+ *
+ * @module lib/cli/design
+ */
+
+"use strict";
+
+import { loadOrgConfig, configFromAgent, isEnabled, brandingGetFoundation } from "../org/client.mjs";
+import { syncDesign, workspaceName } from "../design/write.mjs";
+import { DESIGN_FILES, DESIGN_STATE_REL, isUnversionedFoundation } from "../design/refresh-gate.mjs";
+
+export function usage() {
+  return [
+    "Usage:",
+    "  maestro design sync [--out <dir>] [--json]   Pull the brand foundation and write DESIGN.md + PRODUCT.md",
+    "",
+    `Writes ${DESIGN_FILES.join(" + ")} into the agent dir (or --out) and the raw`,
+    `snapshot to ${DESIGN_STATE_REL}. Unchanged files are left untouched.`,
+    "Foundation changes are human-gated: propose one with the design_propose_change tool.",
+  ].join("\n");
+}
+
+/**
+ * Parse argv → {sub, out, json, help, error}. Pure.
+ * @param {string[]} argv
+ */
+export function parseDesignArgs(argv) {
+  const args = Array.isArray(argv) ? argv.map(String) : [];
+  const out = { sub: null, out: null, json: false, help: false, error: null };
+  if (args.length === 0 || args.includes("--help") || args.includes("-h")) { out.help = true; return out; }
+  out.sub = args[0];
+  const rest = args.slice(1);
+  for (let i = 0; i < rest.length; i++) {
+    const a = rest[i];
+    const eq = a.indexOf("=");
+    const key = a.startsWith("--") && eq > 0 ? a.slice(0, eq) : a;
+    const inline = a.startsWith("--") && eq > 0 ? a.slice(eq + 1) : undefined;
+    const take = () => (inline !== undefined ? inline : rest[++i]);
+    if (key === "--json") out.json = true;
+    else if (key === "--out") {
+      // A MISSING value is an error, never a silent fallback. `--out` with the
+      // path forgotten (or eaten by the shell) used to leave `out` null and
+      // write DESIGN.md into the agent dir — exactly where the operator was
+      // trying not to write — and `--out --json` used to create a directory
+      // called "--json". Both exit 1 now and write nothing.
+      const v = take();
+      if (v === undefined) { out.error = "--out needs a directory"; return out; }
+      if (typeof v === "string" && v.startsWith("--")) { out.error = `--out needs a directory, not ${v}`; return out; }
+      out.out = v;
+    }
+    else { out.error = `unknown argument ${a}`; return out; }
+  }
+  if (out.sub !== "sync") out.error = `unknown design command: ${out.sub}`;
+  else if (out.out !== null && !String(out.out).trim()) out.error = "--out needs a directory";
+  return out;
+}
+
+/** A protocol error frame → one readable line. */
+export function describeFrame(frame) {
+  const e = frame && frame.error ? frame.error : null;
+  if (e) return `${e.code || "error"}: ${e.message || ""}`.trim();
+  return "no response";
+}
+
+/**
+ * Re-exported so `maestro design sync` and the daemon's poller name the
+ * workspace identically — the heading is part of the rendered bytes, so two
+ * definitions would make the two lanes rewrite each other's files forever.
+ * The definition lives in `lib/design/write.mjs`.
+ */
+export { workspaceName };
+
+/**
+ * The testable core. deps: {agentRoot, cfg, now, write, fetchImpl,
+ * getFoundationImpl, syncImpl, io}.
+ * @param {string[]} argv
+ * @param {object} [deps]
+ * @returns {Promise<{code:number, data?:object}>}
+ */
+export async function runDesign(argv, deps = {}) {
+  const write = typeof deps.write === "function" ? deps.write : (s) => process.stdout.write(`${s}\n`);
+  const p = parseDesignArgs(argv);
+  if (p.help) { write(usage()); return { code: 0 }; }
+  if (p.error) { write(`error: ${p.error}\n\n${usage()}`); return { code: 1 }; }
+
+  const agentRoot = deps.agentRoot || process.cwd();
+  const cfg = deps.cfg || loadOrgConfig(agentRoot);
+  if (!isEnabled(cfg)) {
+    write("error: the org (Cohort) is not enabled for this agent — run `maestro setup --only org`.");
+    return { code: 1 };
+  }
+  const conn = configFromAgent(cfg) || {};
+  const now = Number.isFinite(deps.now) ? deps.now : Date.now();
+  const outDir = p.out ? String(p.out) : agentRoot;
+
+  let frame;
+  try {
+    frame = await (deps.getFoundationImpl || brandingGetFoundation)(
+      { historyLimit: 0 },
+      { base: conn.base, token: conn.token, orgId: conn.orgId, fetchImpl: deps.fetchImpl },
+    );
+  } catch (err) {
+    // A transport throw is the same class of failure as an error frame: say so
+    // and write nothing. The last-good DESIGN.md on disk stays authoritative.
+    write(`error: could not read the brand foundation — ${err && err.message ? err.message : String(err)}. Nothing was written.`);
+    return { code: 1 };
+  }
+  if (!frame || !frame.ok || !frame.result || typeof frame.result !== "object") {
+    write(`error: could not read the brand foundation — ${describeFrame(frame)}. Nothing was written.`);
+    return { code: 1 };
+  }
+  if (!frame.result.foundation || typeof frame.result.foundation !== "object") {
+    write("error: the workspace has no brand foundation yet — set one up in Design first. Nothing was written.");
+    return { code: 1 };
+  }
+  // AN UNVERSIONED WORKSPACE IS NOT A BRAND. hq answers a workspace that has
+  // never saved a foundation with its own product defaults and `unversioned:
+  // true` — a complete, plausible palette that is nobody's brand. Writing it
+  // would hand every design skill on the seat a wrong palette wearing the
+  // authority of a generated file. See refresh-gate.mjs#isUnversionedFoundation.
+  if (isUnversionedFoundation(frame.result)) {
+    write("error: this workspace has never saved a brand foundation — hq answered with stock defaults, which are not your brand. Set one up in Design (or propose one with design_propose_change) and re-run. Nothing was written.");
+    return { code: 1 };
+  }
+
+  let result;
+  try {
+    result = (deps.syncImpl || syncDesign)(
+      { agentRoot, outDir, result: frame.result, now, name: deps.name || workspaceName(cfg), source: "cohort · branding.getFoundation" },
+      deps.io || {},
+    );
+  } catch (err) {
+    write(`error: could not write the design files — ${err && err.message ? err.message : String(err)}`);
+    return { code: 1 };
+  }
+
+  if (p.json) {
+    write(JSON.stringify(result, null, 2));
+    return { code: 0, data: result };
+  }
+  const wrote = result.written.length
+    ? `wrote ${result.written.join(", ")}`
+    : `unchanged (${result.unchanged.join(", ")})`;
+  write(`design sync: ${wrote} in ${result.outDir}${result.version ? ` — foundation ${result.version}` : ""}`);
+  return { code: 0, data: result };
+}
+
+/** bin entry: resolve the agent root (env → walk → machine pointer) and run. */
+export async function designCmd(argv) {
+  let agentRoot = null;
+  try {
+    const { resolveAgentRoot } = await import("../collective/config.mjs");
+    agentRoot = resolveAgentRoot(process.cwd());
+  } catch {
+    agentRoot = null; // fall through to cwd
+  }
+  const r = await runDesign(argv, { agentRoot: agentRoot || process.cwd() });
+  process.exitCode = r.code;
+  return r;
+}
+
+export default { runDesign, designCmd, parseDesignArgs, workspaceName, describeFrame, usage };

package/lib/cli/design.test.mjs

@@ -0,0 +1,270 @@
+/**
+ * design.test.mjs — `maestro design sync` (WP-M7 mechanic 4).
+ *
+ * Drives the REAL `runDesign` against a temp agent dir with an injected
+ * `branding.getFoundation`. Two claims carry the command and both are load
+ * bearing:
+ *
+ *   · FAIL-OPEN MEANS "WRITE NOTHING". A seat's DESIGN.md is what every design
+ *     skill grounds on. A failed read must leave the last-good file exactly
+ *     where it is and exit non-zero — the opposite of half-writing a file that
+ *     then looks authoritative.
+ *   · IDEMPOTENT BY BYTES. A second run against an unchanged foundation must
+ *     not touch a single mtime, so the 15-minute daemon poll never churns the
+ *     tree or wakes an editor's file watcher.
+ */
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, readFileSync, writeFileSync, statSync, utimesSync, existsSync, rmSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { execFileSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+import { runDesign, parseDesignArgs, describeFrame, workspaceName, usage } from "./design.mjs";
+
+const NOW = Date.parse("2026-09-08T12:00:00Z");
+const FIXTURE = JSON.parse(readFileSync(new URL("../design/fixtures/foundation.json", import.meta.url), "utf8"));
+const CFG = { org: { cohort: { enabled: true, base: "https://os.example.test", token: "nlk_t", orgId: "org_1", orgName: "Northwind" } } };
+
+const okFrame = (over = {}) => ({
+  ok: true,
+  result: {
+    foundation: FIXTURE,
+    version: { id: "bv_01HQZ", seq: 7, label: "V2.7" },
+    headVersionId: "bv_01HQZ",
+    isHead: true,
+    unversioned: false,
+    history: [],
+    ...over,
+  },
+});
+
+function harness(t, opts = {}) {
+  const root = mkdtempSync(join(tmpdir(), "maestro-design-cli-"));
+  t.after(() => rmSync(root, { recursive: true, force: true }));
+  const lines = [];
+  const calls = [];
+  const deps = {
+    agentRoot: root,
+    cfg: opts.cfg === undefined ? CFG : opts.cfg,
+    now: opts.now === undefined ? NOW : opts.now,
+    write: (s) => lines.push(s),
+    getFoundationImpl: opts.getFoundationImpl || (async (params, o) => { calls.push({ params, o }); return okFrame(); }),
+  };
+  return { root, lines, calls, deps, out: () => lines.join("\n") };
+}
+
+// ── argument parsing ────────────────────────────────────────────────────────
+
+test("parseDesignArgs handles the flags, both spellings, and rejects the rest", () => {
+  assert.deepEqual(parseDesignArgs(["sync"]), { sub: "sync", out: null, json: false, help: false, error: null });
+  assert.equal(parseDesignArgs(["sync", "--json"]).json, true);
+  assert.equal(parseDesignArgs(["sync", "--out", "docs"]).out, "docs");
+  assert.equal(parseDesignArgs(["sync", "--out=docs"]).out, "docs");
+  assert.equal(parseDesignArgs([]).help, true);
+  assert.equal(parseDesignArgs(["--help"]).help, true);
+  assert.equal(parseDesignArgs(["-h"]).help, true);
+  assert.match(parseDesignArgs(["shove"]).error, /unknown design command: shove/);
+  assert.match(parseDesignArgs(["sync", "--wat"]).error, /unknown argument --wat/);
+  assert.match(parseDesignArgs(["sync", "--out", ""]).error, /--out needs a directory/);
+
+  // A MISSING value is an error, not a silent fallback to the agent dir —
+  // which is precisely the directory the operator was trying not to write to.
+  assert.match(parseDesignArgs(["sync", "--out"]).error, /--out needs a directory/);
+  assert.equal(parseDesignArgs(["sync", "--out"]).out, null);
+  assert.match(parseDesignArgs(["sync", "--out", "--json"]).error, /--out needs a directory, not --json/);
+  assert.equal(parseDesignArgs(["sync", "--out", "--json"]).json, false, "and --json was not eaten as a path");
+});
+
+test("`--out` with no path exits 1 and writes nothing at all", async (t) => {
+  const h = harness(t);
+  const r = await runDesign(["sync", "--out"], h.deps);
+  assert.equal(r.code, 1);
+  assert.match(h.out(), /--out needs a directory/);
+  assert.equal(h.calls.length, 0, "not even a read is spent");
+  assert.deepEqual(readdirSync(h.root), [], "and no DESIGN.md lands in the agent dir by accident");
+});
+
+test("--help and a bad argument both print the usage; only the bad argument is an error", async (t) => {
+  const h = harness(t);
+  assert.deepEqual(await runDesign(["--help"], h.deps), { code: 0 });
+  assert.match(h.out(), /maestro design sync/);
+
+  const h2 = harness(t);
+  const r = await runDesign(["sync", "--nope"], h2.deps);
+  assert.equal(r.code, 1);
+  assert.match(h2.out(), /error: unknown argument --nope/);
+  assert.match(h2.out(), /maestro design sync/, "the usage follows the error");
+  assert.ok(usage().includes("design_propose_change"), "the usage says how a change is actually made");
+});
+
+// ── the happy path ──────────────────────────────────────────────────────────
+
+test("sync writes DESIGN.md, PRODUCT.md and the snapshot, and reads the SAVED foundation", async (t) => {
+  const h = harness(t);
+  const r = await runDesign(["sync"], h.deps);
+
+  assert.equal(r.code, 0);
+  assert.deepEqual(r.data.written, ["DESIGN.md", "PRODUCT.md"]);
+  assert.ok(existsSync(join(h.root, "DESIGN.md")));
+  assert.ok(existsSync(join(h.root, "PRODUCT.md")));
+  assert.ok(existsSync(join(h.root, "state", "design", "foundation.json")));
+  assert.match(h.out(), /design sync: wrote DESIGN\.md, PRODUCT\.md/);
+  assert.match(h.out(), /foundation bv_01HQZ/);
+
+  assert.equal(h.calls.length, 1);
+  assert.deepEqual(h.calls[0].params, { historyLimit: 0 }, "no history is fetched — the seat only needs the head");
+  assert.equal(h.calls[0].o.base, "https://os.example.test", "the agent's own connection is used");
+  assert.equal(h.calls[0].o.orgId, "org_1");
+
+  const design = readFileSync(join(h.root, "DESIGN.md"), "utf8");
+  assert.match(design, /^---\nname: "Northwind"\n/, "the heading comes from the org config, not the foundation prose");
+  assert.match(design, /\{colors\.primary\}/);
+  assert.equal(statSync(join(h.root, "DESIGN.md")).mode & 0o777, 0o644);
+  assert.equal(statSync(join(h.root, "PRODUCT.md")).mode & 0o777, 0o644);
+});
+
+test("--json prints the machine result and still writes the files", async (t) => {
+  const h = harness(t);
+  const r = await runDesign(["sync", "--json"], h.deps);
+  assert.equal(r.code, 0);
+  const doc = JSON.parse(h.out());
+  assert.deepEqual(doc.written, ["DESIGN.md", "PRODUCT.md"]);
+  assert.equal(doc.version, "bv_01HQZ");
+  assert.equal(doc.outDir, h.root);
+});
+
+test("--out puts the docs elsewhere and keeps the snapshot under the agent root", async (t) => {
+  const h = harness(t);
+  const outDir = join(h.root, "brand");
+  const r = await runDesign(["sync", "--out", outDir], h.deps);
+  assert.equal(r.code, 0);
+  assert.ok(existsSync(join(outDir, "DESIGN.md")));
+  assert.ok(!existsSync(join(h.root, "DESIGN.md")));
+  assert.ok(existsSync(join(h.root, "state", "design", "foundation.json")));
+});
+
+test("re-running against an unchanged foundation rewrites nothing", async (t) => {
+  const h = harness(t);
+  await runDesign(["sync"], h.deps);
+  const old = new Date(NOW - 86_400_000);
+  for (const rel of ["DESIGN.md", "PRODUCT.md"]) utimesSync(join(h.root, rel), old, old);
+  const before = ["DESIGN.md", "PRODUCT.md"].map((rel) => statSync(join(h.root, rel)).mtimeMs);
+
+  const r = await runDesign(["sync"], { ...h.deps, now: NOW + 3_600_000 });
+  assert.equal(r.code, 0);
+  assert.deepEqual(r.data.written, []);
+  assert.deepEqual(r.data.unchanged, ["DESIGN.md", "PRODUCT.md"]);
+  assert.match(h.out(), /design sync: unchanged \(DESIGN\.md, PRODUCT\.md\)/);
+  assert.deepEqual(["DESIGN.md", "PRODUCT.md"].map((rel) => statSync(join(h.root, rel)).mtimeMs), before);
+});
+
+// ── the failure postures ────────────────────────────────────────────────────
+
+test("an error frame exits 1 and writes NOTHING", async (t) => {
+  const h = harness(t, { getFoundationImpl: async () => ({ ok: false, error: { code: "FORBIDDEN", message: "design.read is not granted to this seat." } }) });
+  const r = await runDesign(["sync"], h.deps);
+  assert.equal(r.code, 1);
+  assert.match(h.out(), /FORBIDDEN: design\.read is not granted to this seat\./);
+  assert.match(h.out(), /Nothing was written\./);
+  assert.deepEqual(readdirSync(h.root), [], "not one file, not even the state dir");
+});
+
+test("a transport throw exits 1, says so, and leaves the last-good files exactly as they were", async (t) => {
+  const h = harness(t);
+  await runDesign(["sync"], h.deps); // establish a good DESIGN.md first
+  const good = readFileSync(join(h.root, "DESIGN.md"), "utf8");
+  const old = new Date(NOW - 86_400_000);
+  utimesSync(join(h.root, "DESIGN.md"), old, old);
+  const mtime = statSync(join(h.root, "DESIGN.md")).mtimeMs;
+
+  const r = await runDesign(["sync"], { ...h.deps, getFoundationImpl: async () => { throw new Error("fetch failed: ECONNREFUSED"); } });
+  assert.equal(r.code, 1);
+  assert.match(h.out(), /could not read the brand foundation — fetch failed: ECONNREFUSED/);
+  assert.match(h.out(), /Nothing was written\./);
+  assert.equal(readFileSync(join(h.root, "DESIGN.md"), "utf8"), good, "the last-good file is untouched");
+  assert.equal(statSync(join(h.root, "DESIGN.md")).mtimeMs, mtime);
+});
+
+test("a workspace with no foundation yet is named as such, not rendered as an empty brand", async (t) => {
+  const h = harness(t, { getFoundationImpl: async () => ({ ok: true, result: { foundation: null, headVersionId: null, unversioned: true, history: [] } }) });
+  const r = await runDesign(["sync"], h.deps);
+  assert.equal(r.code, 1);
+  assert.match(h.out(), /no brand foundation yet — set one up in Design first/);
+  assert.deepEqual(readdirSync(h.root), []);
+});
+
+test("hq's stock defaults are refused: an unversioned workspace writes nothing and is told why", async (t) => {
+  // The FRAME HQ ACTUALLY SENDS for a workspace that never saved a foundation:
+  // a complete `dsDefaults()` palette, `unversioned: true`, `headVersionId:
+  // null`. The `foundation: null` case above cannot occur in production, so
+  // this is the guard that has to hold.
+  const h = harness(t, {
+    getFoundationImpl: async () => ({
+      ok: true,
+      result: {
+        foundation: { ...FIXTURE, colors: [{ name: "Ink", value: "#0d0d0d" }] },
+        version: null,
+        headVersionId: null,
+        isHead: false,
+        unversioned: true,
+        history: [],
+      },
+    }),
+  });
+  const r = await runDesign(["sync"], h.deps);
+  assert.equal(r.code, 1);
+  assert.match(h.out(), /never saved a brand foundation/);
+  assert.match(h.out(), /stock defaults, which are not your brand/);
+  assert.match(h.out(), /Nothing was written\./);
+  assert.deepEqual(readdirSync(h.root), [], "no DESIGN.md wearing another product's palette");
+});
+
+test("an older hq that omits `unversioned` is judged by the version identity instead", async (t) => {
+  const h = harness(t, {
+    getFoundationImpl: async () => ({ ok: true, result: { foundation: FIXTURE, version: null, headVersionId: null, history: [] } }),
+  });
+  const r = await runDesign(["sync"], h.deps);
+  assert.equal(r.code, 1);
+  assert.match(h.out(), /never saved a brand foundation/);
+  assert.deepEqual(readdirSync(h.root), []);
+});
+
+test("a seat that is not enrolled in the org exits 1 and points at setup", async (t) => {
+  const h = harness(t, { cfg: { org: { cohort: { enabled: false } } } });
+  const r = await runDesign(["sync"], h.deps);
+  assert.equal(r.code, 1);
+  assert.match(h.out(), /not enabled for this agent — run `maestro setup --only org`/);
+  assert.equal(h.calls.length, 0, "no hq call is attempted");
+  assert.deepEqual(readdirSync(h.root), []);
+});
+
+test("a write failure is reported, not thrown", async (t) => {
+  const h = harness(t);
+  const r = await runDesign(["sync"], { ...h.deps, syncImpl: () => { throw new Error("EROFS: read-only file system"); } });
+  assert.equal(r.code, 1);
+  assert.match(h.out(), /could not write the design files — EROFS/);
+});
+
+test("describeFrame turns any frame into one readable line", () => {
+  assert.equal(describeFrame({ ok: false, error: { code: "RATE_LIMITED", message: "Slow down." } }), "RATE_LIMITED: Slow down.");
+  assert.equal(describeFrame({ ok: false, error: { message: "no code" } }), "error: no code");
+  assert.equal(describeFrame(null), "no response");
+  assert.equal(describeFrame({ ok: true }), "no response");
+});
+
+test("workspaceName is the one shared with the daemon", async () => {
+  const { workspaceName: fromWriter } = await import("../design/write.mjs");
+  assert.equal(workspaceName, fromWriter, "one definition, so the CLI and the daemon cannot render different headings");
+});
+
+// ── the bin seam ────────────────────────────────────────────────────────────
+
+test("`maestro design` is wired into bin/maestro.mjs", () => {
+  const bin = fileURLToPath(new URL("../../bin/maestro.mjs", import.meta.url));
+  const out = execFileSync(process.execPath, [bin, "design", "--help"], { encoding: "utf8" });
+  assert.match(out, /maestro design sync \[--out <dir>\] \[--json\]/);
+  assert.match(execFileSync(process.execPath, [bin, "--help"], { encoding: "utf8" }), /design sync/, "and listed in the top-level help");
+});