@zumino/cli 2.1.0

package/src/commands/init.js

@@ -0,0 +1,174 @@
+import { existsSync, lstatSync, writeFileSync } from "node:fs";
+import { execFileSync } from "node:child_process";
+import { join } from "node:path";
+import { createInterface } from "node:readline/promises";
+
+import { api } from "../client.js";
+import { readConfig, readRepoFile, repoKeys, resolveContext, writeConfig } from "../config.js";
+import { CliError } from "../errors.js";
+import { bold, dim, note, out, workspaceSlug } from "../output.js";
+
+/**
+ * `zumino init` — tie this repository to a project.
+ *
+ * This is the product half of `tasks/every-repo-knows-its-project.md`: a tracker
+ * only tells the truth if the work goes through it, and the failure mode is not
+ * that people refuse to file tickets — it is that an agent doing an hour of real
+ * work in a repo has no reason to know a project exists.
+ *
+ * It writes two things, in two places, on purpose:
+ *
+ *  - **`.zumino.json`, committed** — the host, workspace and project. Facts
+ *    about the work, true for everyone who clones, and carrying no secret.
+ *  - **the repo map in `~/.config/zumino/config.json`** — which *account* this
+ *    person uses here. A fact about this laptop, kept beside the token.
+ *
+ * That split is what lets a repository be self-describing without being able to
+ * name anybody's credential.
+ */
+export async function run(args, flags) {
+  const cwd = process.cwd();
+  const root = gitRoot(cwd) ?? cwd;
+  const target = join(root, ".zumino.json");
+  const existing = readRepoFile(root);
+
+  // A repository can commit `.zumino.json` as a symlink (git mode 120000) to
+  // any path, and `writeFileSync` follows one — so `zumino init` in a hostile
+  // checkout would truncate whatever it pointed at. `existsSync` follows links
+  // too, which made it worse: a link to an existing file produced the "already
+  // exists" error whose hint talks the user into `--yes`, and a link to a path
+  // that does not exist yet was written through with no confirmation at all.
+  //
+  // `zumino skill install` already refuses exactly this; the omission here was
+  // inconsistent with the package's own guard.
+  let link = null;
+  try {
+    link = lstatSync(target);
+  } catch {
+    /* absent, which is the ordinary case */
+  }
+  if (link?.isSymbolicLink()) {
+    throw new CliError(`${target} is a symlink.`, {
+      hint: "Refusing to write through it — a repository must not choose what this overwrites.",
+    });
+  }
+
+  if (existsSync(target) && !flags.yes) {
+    throw new CliError(`${target} already exists.`, {
+      hint: "Re-run with --yes to overwrite it.",
+    });
+  }
+
+  const ctx = resolveContext(flags, cwd);
+  const { projects = [] } = (await api(ctx, "GET", "/projects")) ?? {};
+  if (projects.length === 0) {
+    throw new CliError("You cannot reach any project.", {
+      hint: "Create one in the browser first — creating a project is not on the API.",
+    });
+  }
+
+  // A project slug is unique per workspace, not globally, so a slug alone can
+  // match in two places. `client.js` already refuses that case rather than
+  // guessing; picking `[0]` here would write the wrong workspace into a file
+  // everyone who clones this repo then inherits.
+  // `ctx`, not a second chain. Recomputing from flags and the repo file skipped
+  // ZUMINO_PROJECT / ZUMINO_WORKSPACE — rung 2 of the order this branch
+  // publishes — while still honouring `.zumino.json` at rung 3, so the
+  // environment was resolved and then discarded. `ctx` already folds the flags,
+  // the environment, the repo file and the home repo map in the documented
+  // order, which is the whole point of resolving once.
+  const wanted = ctx.project ?? existing?.project;
+  const wantedWorkspace = ctx.workspace ?? existing?.workspace ?? null;
+  let chosen = null;
+  if (wanted) {
+    const hits = projects.filter(
+      (p) =>
+        (p.slug === wanted || p.key === wanted) &&
+        (!wantedWorkspace || workspaceSlug(p.workspace) === wantedWorkspace),
+    );
+    if (hits.length === 0) {
+      throw new CliError(
+        `No project "${wanted}"${wantedWorkspace ? ` in workspace "${wantedWorkspace}"` : ""} you can reach.`,
+        { hint: "List what you can see with: zumino api GET /projects" },
+      );
+    }
+    if (hits.length > 1) {
+      throw new CliError(
+        `"${wanted}" exists in more than one workspace: ${hits
+          .map((h) => workspaceSlug(h.workspace))
+          .join(", ")}.`,
+        { hint: "Name one with --workspace <slug>." },
+      );
+    }
+    chosen = hits[0];
+  }
+  if (!chosen) chosen = await choose(projects);
+
+  const doc = {
+    host: ctx.host,
+    workspace: workspaceSlug(chosen.workspace),
+    project: chosen.slug,
+  };
+  writeFileSync(target, JSON.stringify(doc, null, 2) + "\n");
+
+  // Remember which account answered here, so a later command in this checkout
+  // resolves without an environment even if several accounts are configured.
+  // `ctx.account`, not a regex over `ctx.source`. Parsing the human-readable
+  // source string missed `the only account ("name")` — which is the shape the
+  // documented first-run flow produces — so `init` skipped the repo-map write
+  // and still exited 0. The repository then looked initialised while being tied
+  // to nothing, and every command started refusing the moment a second account
+  // was added, which is the whole scenario decision 0006 is built around.
+  const accountName = ctx.account;
+  if (accountName) {
+    const cfg = readConfig();
+    for (const key of repoKeys(root).slice(0, 1)) {
+      cfg.repos[key] = {
+        account: accountName,
+        project: chosen.slug,
+        workspace: workspaceSlug(chosen.workspace),
+      };
+    }
+    writeConfig(cfg);
+  }
+
+  out(`wrote ${target}`);
+  note("");
+  note(`  This repo files work to ${bold(chosen.slug)} on ${ctx.host}.`);
+  if (accountName) note(dim(`  Using account "${accountName}" here.`));
+  note(dim("  Install the agent skill once, globally: zumino skill install"));
+  return 0;
+}
+
+function gitRoot(cwd) {
+  try {
+    return execFileSync("git", ["rev-parse", "--show-toplevel"], {
+      cwd,
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+    }).trim();
+  } catch {
+    return null;
+  }
+}
+
+async function choose(projects) {
+  if (!process.stdin.isTTY) {
+    throw new CliError("Several projects, and nothing said which.", {
+      hint: `Pass --project <${projects.slice(0, 4).map((p) => p.slug).join("|")}>`,
+    });
+  }
+  const rl = createInterface({ input: process.stdin, output: process.stderr });
+  try {
+    projects.forEach((p, i) => note(
+        `  ${String(i + 1).padStart(2)}. ${p.slug}  ${dim(`${workspaceSlug(p.workspace)} · ${p.type}`)}`,
+      ));
+    const answer = (await rl.question("\nWhich project? ")).trim();
+    const idx = Number(answer) - 1;
+    const picked = projects[idx] ?? projects.find((p) => p.slug === answer);
+    if (!picked) throw new CliError(`"${answer}" is not one of them.`);
+    return picked;
+  } finally {
+    rl.close();
+  }
+}

package/src/commands/queue.js

@@ -0,0 +1,60 @@
+import { api } from "../client.js";
+import { resolveContext } from "../config.js";
+import { clip, codeOf, dim, json, note, out, table, workspaceSlug, positiveInt } from "../output.js";
+
+/**
+ * `zumino queue` — what to work on next, across every project you can reach.
+ *
+ * `GET /queue` computes availability rather than reading a column: committed,
+ * shaped, and unblocked. That is why an empty answer is a *finding* and this
+ * command says so instead of printing nothing — the specs are below the bar or
+ * their blockers are open, which is actionable, and silence is not.
+ */
+export async function run(args, flags) {
+  const ctx = resolveContext(flags);
+  const res = await api(ctx, "GET", "/queue", {
+    query: {
+      needsInput: flags["needs-input"] ? "true" : undefined,
+      workspace: ctx.workspace ?? undefined,
+      project: ctx.project ?? undefined,
+      limit: positiveInt(flags.limit, "limit"),
+    },
+  });
+
+  const tasks = res?.tasks ?? [];
+  if (flags.json) {
+    json(tasks);
+    return 0;
+  }
+
+  if (tasks.length === 0) {
+    out(
+      flags["needs-input"]
+        ? "Nothing is waiting on you."
+        : "Nothing available to pick up.",
+    );
+    if (!flags["needs-input"]) {
+      note(
+        dim(
+          "  Not the same as no work: the queue offers only tasks that are\n" +
+            "  committed, shaped and unblocked. What is committed but unshaped\n" +
+            "  is below the bar — read a candidate with zumino task show <CODE>\n" +
+            "  and shape it with zumino task spec.",
+        ),
+      );
+    }
+    return 0;
+  }
+
+  table(
+    tasks.map((t) => [
+      codeOf(t),
+      t.status ?? "",
+      t.priority ?? "",
+      clip(t.title),
+      dim(`${workspaceSlug(t.workspace)}/${t.project}`),
+    ]),
+    { head: ["CODE", "STATUS", "PRIORITY", "TITLE", "WHERE"] },
+  );
+  return 0;
+}

package/src/commands/request.js

@@ -0,0 +1,176 @@
+import { api } from "../client.js";
+import { resolveContext } from "../config.js";
+import { CliError } from "../errors.js";
+import { clip, json, out, pick, safeText, givenFlag } from "../output.js";
+import { projectPath, resolveItem } from "../items.js";
+
+/*
+ * Everything that writes a request.
+ *
+ * **A request on a feedback project has no code**, because a feedback project
+ * has no key — `#42` is the whole of its name. So every reference here is
+ * resolved as a request by default rather than as a task, and nothing
+ * synthesizes a code for one.
+ */
+
+const SUB = { create, answer, status, note: internalNote, comment, promote, show };
+
+export async function run(args, flags) {
+  const [sub, ...rest] = args;
+  const fn = SUB[sub];
+  if (!fn) {
+    throw new CliError(`zumino request: unknown subcommand "${sub ?? ""}".`, {
+      hint: `One of: ${Object.keys(SUB).join(", ")}`,
+    });
+  }
+  return fn(rest, flags);
+}
+
+async function create(args, flags) {
+  const ctx = resolveContext(flags);
+  const title = flags.title ?? args.join(" ").trim();
+  if (!title) throw new CliError('A request needs a title.', { hint: 'zumino request create --title "…"' });
+  const base = await projectPath(ctx);
+  const body = { title };
+  if (givenFlag(flags.description) !== undefined) body.description = flags.description;
+  const res = pick(await api(ctx, "POST", `${base}/requests`, { body }), "request");
+  if (flags.json) return json(res), 0;
+  out(`#${res.number}  ${safeText(res.title)}`);
+  return 0;
+}
+
+/**
+ * Post a comment and mark it the official answer.
+ *
+ * Two calls because the API models it as two things: at most one comment on a
+ * request may be official (`comment.is_official`, held by a partial unique
+ * index), so the answer is *a comment that has been designated*, not a field.
+ * Doing both here is the whole reason this subcommand exists.
+ */
+async function answer(args, flags) {
+  const [ref, ...text] = args;
+  const bodyText = flags.body ?? text.join(" ").trim();
+  if (!ref || !bodyText) throw new CliError("zumino request answer <#N|CODE> <text>");
+  const ctx = resolveContext(flags);
+  const { path } = await resolveItem(ctx, ref, { kind: "request" });
+
+  const comment = pick(await api(ctx, "POST", `${path}/comments`, { body: { body: bodyText } }), "comment");
+
+  // From here the comment is public. The two calls sit behind different gates —
+  // commenting is open to any member (and to any token holder on a public
+  // feedback project), while marking an answer needs owner/admin — so the second
+  // can be refused after the first has landed. It can also be rate limited: the
+  // buckets are separate.
+  //
+  // The failure that matters is not the refusal, it is the silence. Reported as
+  // a bare `needAdmin`, nothing says a comment was posted, so the natural
+  // response — hand it to an admin, or an agent obeying the skill's "repeat that
+  // exact call" rule — posts a second one on a public board, and the API offers
+  // no way to delete either.
+  try {
+    const res = pick(
+      await api(ctx, "PUT", `${path}/answer`, { body: { commentId: comment.id } }),
+      "request",
+    );
+    if (flags.json) return json(res), 0;
+    out(`${ref}  answered`);
+    return 0;
+  } catch (err) {
+    throw new CliError(
+      `The comment was posted on ${ref}, but marking it the official answer failed: ${err.message}`,
+      {
+        exitCode: err.exitCode,
+        key: err.key,
+        hint:
+          `Do NOT re-run this command — it would post a second comment. ` +
+          `Mark the existing one: zumino api PUT ${path}/answer --body '{"commentId":"${comment.id}"}'`,
+      },
+    );
+  }
+}
+
+async function status(args, flags) {
+  const [ref, value] = args;
+  if (!ref || !value) {
+    throw new CliError("zumino request status <#N|CODE> <status>", {
+      hint: "Owner or admin only. Moving to done or wont_do closes the item.",
+    });
+  }
+  const ctx = resolveContext(flags);
+  const { path } = await resolveItem(ctx, ref, { kind: "request" });
+  const res = pick(await api(ctx, "PATCH", path, { body: { status: value } }), "request");
+  if (flags.json) return json(res), 0;
+  out(`${ref}  ${res.status}`);
+  return 0;
+}
+
+async function internalNote(args, flags) {
+  const [ref, ...text] = args;
+  if (!ref) throw new CliError("zumino request note <#N|CODE> <text|->");
+  const ctx = resolveContext(flags);
+  const { path } = await resolveItem(ctx, ref, { kind: "request" });
+  const body = text.join(" ").trim();
+  const res = await api(ctx, "PUT", `${path}/internal-note`, {
+    body: { note: !body || body === "-" ? null : body },
+  });
+  if (flags.json) return json(res), 0;
+  out(`${ref}  note ${body && body !== "-" ? "written" : "cleared"}`);
+  return 0;
+}
+
+async function comment(args, flags) {
+  const [ref, ...text] = args;
+  const bodyText = flags.body ?? text.join(" ").trim();
+  if (!ref || !bodyText) throw new CliError("zumino request comment <#N|CODE> <text>");
+  const ctx = resolveContext(flags);
+  const { path } = await resolveItem(ctx, ref, { kind: "request" });
+  const res = pick(await api(ctx, "POST", `${path}/comments`, { body: { body: bodyText } }), "comment");
+  if (flags.json) return json(res), 0;
+  out(`${ref}  commented`);
+  return 0;
+}
+
+/**
+ * Promote a request into work.
+ *
+ * A request never *becomes* a task (`docs/decisions/0002`) — this creates a task
+ * that answers it, and both go on living. The wording here says so, because the
+ * alternative reading is the one everybody arrives with.
+ */
+async function promote(args, flags) {
+  const [ref] = args;
+  if (!ref) throw new CliError("zumino request promote <#N|CODE> --to <slug>");
+
+  // The destination is `--to`, not `--project`, because `--project` already
+  // names where the *request* lives — and it has to, since a request on a
+  // feedback project has no code and `#42` is the whole of its name. Binding
+  // one flag to both ends addressed the request in the target project, which
+  // either 404s or, when that project happens to have a request of the same
+  // number, promotes the wrong item silently.
+  const target = flags.to;
+  if (!target) {
+    throw new CliError("Which work project should the task go in?", {
+      hint: "zumino request promote <#N> --to <work-project-slug>",
+    });
+  }
+
+  const ctx = resolveContext(flags);
+  const { path } = await resolveItem(ctx, ref, { kind: "request" });
+  const res = pick(await api(ctx, "POST", `${path}/promote`, { body: { project: target } }), "task");
+  if (flags.json) return json(res), 0;
+  out(`${ref}  →  ${res.code ?? res.ref ?? `#${res.number}`}  (the request stays open)`);
+  return 0;
+}
+
+async function show(args, flags) {
+  const [ref] = args;
+  if (!ref) throw new CliError("zumino request show <#N|CODE>");
+  const ctx = resolveContext(flags);
+  const { path } = await resolveItem(ctx, ref, { kind: "request" });
+  const res = pick(await api(ctx, "GET", path), "request");
+  if (flags.json) return json(res), 0;
+  out(`#${res.number}  ${safeText(res.title)}`);
+  out(`status ${res.status}   votes ${res.voteCount ?? 0}`);
+  if (res.description) out(`\n${clip(res.description, 2000)}`);
+  return 0;
+}

package/src/commands/self-update.js

@@ -0,0 +1,40 @@
+import { spawnSync } from "node:child_process";
+
+import { VERSION } from "../client.js";
+import { CliError } from "../errors.js";
+import { dim, note, out } from "../output.js";
+
+/**
+ * `zumino self-update` — the command every stale-version message names.
+ *
+ * It exists so that an agent never has to work out which package manager
+ * installed this, or whether the install was global. One command, always
+ * correct, printed verbatim in the failure that requires it — that is the entire
+ * mechanism by which drift gets fixed rather than reported.
+ */
+export async function run() {
+  const pkg = "@zumino/cli@latest";
+  out(`Updating ${pkg} (from ${VERSION})…`);
+
+  const res = spawnSync("npm", ["install", "-g", pkg], {
+    stdio: ["ignore", "inherit", "inherit"],
+    encoding: "utf8",
+  });
+
+  if (res.error) {
+    throw new CliError(`Could not run npm: ${res.error.message}`, {
+      hint: `Update by hand: npm install -g ${pkg}`,
+    });
+  }
+  if (res.status !== 0) {
+    throw new CliError(`npm exited ${res.status}.`, {
+      // The overwhelmingly common cause, and the one whose fix is not obvious
+      // from npm's own error.
+      hint: `If this is a permissions failure, either use a node version manager or: sudo npm install -g ${pkg}`,
+    });
+  }
+
+  note(dim("\nUpdated. Re-run what you were doing."));
+  note(dim("If the skill is older than the CLI: zumino skill install"));
+  return 0;
+}

package/src/commands/skill.js

@@ -0,0 +1,97 @@
+import { copyFileSync, lstatSync, mkdirSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { VERSION } from "../client.js";
+import { CliError } from "../errors.js";
+import { bold, dim, note, out } from "../output.js";
+
+/*
+ * `zumino skill install` — put the agent skill where every repo can see it.
+ *
+ * **Globally, at `~/.claude/skills/zumino/`, and never inside a project.** A
+ * per-repo copy is N copies of one document, each aging separately with nothing
+ * to say which is current — the same drift the version handshake exists to
+ * remove, reintroduced one directory at a time.
+ *
+ * The skill travels inside this package rather than being fetched, so it is
+ * locked to the CLI's version, which is the release version. `--check` compares
+ * the two without writing.
+ */
+
+const here = dirname(fileURLToPath(import.meta.url));
+const BUNDLED = join(here, "..", "..", "skill", "SKILL.md");
+
+function defaultDir() {
+  return join(homedir(), ".claude", "skills", "zumino");
+}
+
+export async function run(args, flags) {
+  const [sub = "install"] = args;
+  if (sub !== "install") {
+    throw new CliError(`zumino skill: unknown subcommand "${sub}".`, { hint: "Only: install" });
+  }
+
+  const dir = flags.dir ? String(flags.dir) : defaultDir();
+  const target = join(dir, "SKILL.md");
+  const installed = readVersion(target);
+
+  if (flags.check) {
+    if (!installed) {
+      out(`not installed (would write ${target})`);
+      return 1;
+    }
+    if (installed === VERSION) {
+      out(`skill is ${installed} — current`);
+      return 0;
+    }
+    out(`skill is ${installed}, CLI is ${VERSION} — run without --check to update`);
+    return 1;
+  }
+
+  // `lstatSync` in a try, not `existsSync && lstatSync` — `existsSync` follows
+  // the link, so a *dangling* one reported absent and both guards were skipped:
+  // `mkdirSync` created the real parent and `copyFileSync` wrote through to the
+  // link's destination, putting a stray file in a repository the user never
+  // asked to touch while printing the link's path as though that were written.
+  // `init.js` already uses this shape; the claim that this file did was wrong.
+  if (isSymlink(dir)) {
+    throw new CliError(`${dir} is a symlink.`, {
+      hint: `It probably points into a repo you version. Install there deliberately: zumino skill install --dir <path>`,
+    });
+  }
+  if (isSymlink(target)) {
+    throw new CliError(`${target} is a symlink.`, {
+      hint: "Refusing to write through it. Use --dir to name a real directory.",
+    });
+  }
+
+  mkdirSync(dir, { recursive: true });
+  copyFileSync(BUNDLED, target);
+
+  out(`wrote ${target} (${VERSION})`);
+  note("");
+  note(`  ${bold("One skill, every repo.")} Tie a repo to a project with: zumino init`);
+  note(dim("  Check it later with: zumino skill install --check"));
+  return 0;
+}
+
+/** True for a symlink, dangling or not. */
+function isSymlink(path) {
+  try {
+    return lstatSync(path).isSymbolicLink();
+  } catch {
+    return false;
+  }
+}
+
+/** The `version:` line the bundled skill carries in its frontmatter. */
+function readVersion(path) {
+  try {
+    const head = readFileSync(path, "utf8").slice(0, 600);
+    return /^version:\s*(\S+)\s*$/m.exec(head)?.[1] ?? "unknown";
+  } catch {
+    return null;
+  }
+}