@zumino/cli 2.1.0 → 2.2.0

package/src/commands/project.js

@@ -0,0 +1,147 @@
+import { api, resolveWorkspace } from "../client.js";
+import { requireProject, requireSafeSegment, resolveContext } from "../config.js";
+import { CliError } from "../errors.js";
+import { clip, dim, json, note, out, safeText, table, workspaceSlug } from "../output.js";
+
+/*
+ * The projects a token can reach, and what is in one.
+ *
+ * Reads only. Creating, configuring or deleting a project is not on this API
+ * surface and will not be: a project takes a permanent, workspace-unique key,
+ * and an agent inventing `ONS` because it seemed reasonable is a name you live
+ * with (`DOMAIN.md` § Rules, governance).
+ *
+ * `list` is the read that answers which half of the CLI applies. A **feedback**
+ * project has no key and holds requests, so its items are `#42` and
+ * `zumino request …` writes them; a **work** project has a key and holds tasks
+ * and epics, so its items are `ACME-14` and `zumino task …` does. Getting that
+ * wrong is the most common first mistake, and it used to take two `zumino api`
+ * calls to avoid.
+ */
+
+export const SUB = { list, show, tags };
+
+export async function run(args, flags) {
+  const [sub, ...rest] = args;
+  const fn = SUB[sub];
+  if (!fn) {
+    throw new CliError(`zumino project: unknown subcommand "${sub ?? ""}".`, {
+      hint: `One of: ${Object.keys(SUB).join(", ")}`,
+    });
+  }
+  return fn(rest, flags);
+}
+
+async function list(args, flags) {
+  const ctx = resolveContext(flags);
+  const named = workspaceSlug(ctx.workspace);
+
+  /*
+   * Two endpoints answer this, and which one applies is not a detail.
+   *
+   * `GET /projects` is one of the two deliberately cross-workspace reads and
+   * lists every project in every workspace the token's owner *belongs to*. The
+   * workspace-scoped read answers a different question: a workspace slug is not
+   * a secret, so a non-member may name one and see its public projects. Without
+   * the second call, `--workspace` on a public board you do not belong to
+   * answered an empty list — correct for the endpoint, wrong for the question.
+   */
+  const res = named
+    ? await api(ctx, "GET", `/workspaces/${named}/projects`)
+    : await api(ctx, "GET", "/projects");
+  const projects = res?.projects ?? [];
+  if (flags.json) return json(projects), 0;
+
+  if (projects.length === 0) {
+    out("No projects.");
+    note(
+      dim(
+        "  Either this token's owner belongs to no workspace with projects, or\n" +
+          "  --workspace named one they cannot see. Check with: zumino workspace list",
+      ),
+    );
+    return 0;
+  }
+
+  table(
+    projects.map((p) => [
+      `${workspaceSlug(p.workspace) ?? "?"}/${p.slug}`,
+      p.type ?? "",
+      p.key ?? "—",
+      String(p.type === "feedback" ? (p.requestCount ?? 0) : (p.taskCount ?? 0)),
+      clip(p.name, 40),
+    ]),
+    { head: ["PROJECT", "TYPE", "KEY", "ITEMS", "NAME"] },
+  );
+  out(
+    dim(
+      "\nITEMS is requests on a feedback project and tasks on a work project.\n" +
+        "A work project's KEY is what an item's code is written with.",
+    ),
+  );
+  return 0;
+}
+
+/** The project named as an argument, or the one the context resolved. */
+async function target(ctx, args) {
+  const named = args[0]
+    ? requireSafeSegment(args[0], "project", "the project argument")
+    : requireProject(ctx);
+  const workspace = await resolveWorkspace({ ...ctx, project: named });
+  return { project: named, workspace };
+}
+
+async function show(args, flags) {
+  const ctx = resolveContext(flags);
+  const { project, workspace } = await target(ctx, args);
+  const res = await api(ctx, "GET", `/workspaces/${workspace}/projects/${project}`);
+  if (flags.json) return json(res), 0;
+
+  const p = res?.project ?? {};
+  const stats = res?.stats ?? {};
+  out(`${workspace}/${p.slug}  ${safeText(p.name)}`);
+  out(`type ${p.type ?? "?"}   key ${p.key ?? "—"}   visibility ${p.visibility ?? "?"}`);
+  if (p.description) out(`\n${safeText(p.description)}`);
+
+  // The counters are the feedback half's summary and answer with zeroes on a
+  // work project — so they are printed where they mean something and the other
+  // half is pointed at the read that does answer.
+  if (p.type === "feedback") {
+    out(
+      `\nrequests ${stats.total ?? 0}   votes ${stats.votes ?? 0}   comments ${stats.comments ?? 0}`,
+    );
+    if (stats.byStatus) {
+      out(
+        dim(
+          Object.entries(stats.byStatus)
+            .map(([k, v]) => `${k} ${v}`)
+            .join("   "),
+        ),
+      );
+    }
+  } else {
+    out(dim(`\nCount the work with: zumino task list --project ${p.slug} --json | jq length`));
+  }
+  return 0;
+}
+
+async function tags(args, flags) {
+  const ctx = resolveContext(flags);
+  const { project, workspace } = await target(ctx, args);
+  const res = await api(ctx, "GET", `/workspaces/${workspace}/projects/${project}/tags`);
+  const list = res?.tags ?? [];
+  if (flags.json) return json(list), 0;
+
+  if (list.length === 0) {
+    out("No tags.");
+    return 0;
+  }
+  table(
+    list.map((t) => [t.id ?? "", clip(t.name, 30), t.color ?? ""]),
+    { head: ["ID", "NAME", "COLOUR"] },
+  );
+  // The id is the filter's argument, and it is the only reason this read exists
+  // — `--tag` takes an id because a name is not unique across projects.
+  out(dim("\nFilter with: zumino task list --tag <ID>"));
+  return 0;
+}

package/src/commands/queue.js

@@ -1,6 +1,7 @@
 import { api } from "../client.js";
 import { resolveContext } from "../config.js";
-import { clip, codeOf, dim, json, note, out, table, workspaceSlug, positiveInt } from "../output.js";
+import { clip, codeOf, dim, json, note, out, table, workspaceSlug } from "../output.js";
+import { positiveInt } from "../flags.js";
 
 /**
  * `zumino queue` — what to work on next, across every project you can reach.

package/src/commands/request.js

@@ -1,11 +1,20 @@
 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 { clip, dim, json, out, pageLine, pick, safeText, table } from "../output.js";
+import {
+  csv,
+  givenFlag,
+  nonNegativeInt,
+  oneValue,
+  positiveInt,
+  searchText,
+} from "../flags.js";
+import { listEvents } from "../events.js";
 import { projectPath, resolveItem } from "../items.js";
 
 /*
- * Everything that writes a request.
+ * Requests: what people asked for, read and written.
  *
  * **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
@@ -13,7 +22,20 @@ import { projectPath, resolveItem } from "../items.js";
  * synthesizes a code for one.
  */
 
-const SUB = { create, answer, status, note: internalNote, comment, promote, show };
+export const SUB = {
+  list,
+  show,
+  events,
+  create,
+  edit,
+  answer,
+  status,
+  note: internalNote,
+  comment,
+  promote,
+  tag,
+  untag,
+};
 
 export async function run(args, flags) {
   const [sub, ...rest] = args;
@@ -26,19 +48,117 @@ export async function run(args, flags) {
   return fn(rest, flags);
 }
 
+async function list(args, flags) {
+  const ctx = resolveContext(flags);
+  const base = await projectPath(ctx);
+  const offset = nonNegativeInt(flags.offset, "offset");
+
+  const res = await api(ctx, "GET", `${base}/requests`, {
+    query: {
+      q: searchText(args, flags),
+      status: csv(flags, "status"),
+      type: oneValue(flags, "type"),
+      tag: oneValue(flags, "tag"),
+      sort: oneValue(flags, "sort"),
+      offset,
+      limit: positiveInt(flags.limit, "limit"),
+    },
+  });
+
+  const requests = res?.requests ?? [];
+  if (flags.json) return json(requests), 0;
+  if (requests.length === 0) return out("No requests match."), 0;
+
+  table(
+    requests.map((r) => [
+      `#${r.number}`,
+      r.status ?? "",
+      String(r.voteCount ?? 0),
+      r.type ?? "",
+      clip(r.title, 52),
+    ]),
+    { head: ["ID", "STATUS", "VOTES", "TYPE", "TITLE"] },
+  );
+  out(dim(`\n${pageLine(res, requests.length, offset)}`));
+  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;
+}
+
+async function events(args, flags) {
+  const [ref] = args;
+  if (!ref) throw new CliError("zumino request events <#N|CODE>");
+  const ctx = resolveContext(flags);
+  const { path } = await resolveItem(ctx, ref, { kind: "request" });
+  return listEvents(ctx, path, 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 title = oneValue(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;
+  if (givenFlag(flags.description) !== undefined) body.description = givenFlag(flags.description);
+  const type = oneValue(flags, "type");
+  if (type !== undefined) body.type = type;
   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;
 }
 
+/**
+ * One PATCH carrying every field that was named.
+ *
+ * The two halves of this body sit behind different gates — the words are the
+ * author's or a moderator's, the status and the pinning are a moderator's — so a
+ * mixed call can be refused as a whole. That is the server's rule, and the reason
+ * `status` also keeps its own subcommand: deciding a request is a distinct act,
+ * and it reads better as one.
+ */
+async function edit(args, flags) {
+  const [ref] = args;
+  if (!ref) throw new CliError("zumino request edit <#N|CODE> [fields]");
+  const ctx = resolveContext(flags);
+
+  /** @type {Record<string, any>} */
+  const body = {};
+  for (const name of ["title", "description"]) {
+    const v = givenFlag(flags[name]);
+    if (v !== undefined) body[name] = v;
+  }
+  for (const name of ["type", "status"]) {
+    const v = oneValue(flags, name);
+    if (v !== undefined) body[name] = v;
+  }
+  const pinned = oneValue(flags, "pinned");
+  if (pinned !== undefined) body.pinned = pinned === "true";
+
+  if (Object.keys(body).length === 0) {
+    throw new CliError("Nothing to change.", {
+      hint: "Name at least one field. See: zumino help request edit",
+    });
+  }
+
+  const { path } = await resolveItem(ctx, ref, { kind: "request" });
+  const res = pick(await api(ctx, "PATCH", path, { body }), "request");
+  if (flags.json) return json(res), 0;
+  out(`#${res.number}  ${Object.keys(body).join(", ")} written`);
+  return 0;
+}
+
 /**
  * Post a comment and mark it the official answer.
  *
@@ -147,7 +267,7 @@ async function promote(args, flags) {
   // 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;
+  const target = oneValue(flags, "to");
   if (!target) {
     throw new CliError("Which work project should the task go in?", {
       hint: "zumino request promote <#N> --to <work-project-slug>",
@@ -162,15 +282,33 @@ async function promote(args, flags) {
   return 0;
 }
 
-async function show(args, flags) {
-  const [ref] = args;
-  if (!ref) throw new CliError("zumino request show <#N|CODE>");
+async function tag(args, flags) {
+  return setTag(args, flags, true);
+}
+
+async function untag(args, flags) {
+  return setTag(args, flags, false);
+}
+
+/** A tag on or off, by id — `zumino project tags` lists them. */
+async function setTag(args, flags, on) {
+  const [ref, tagId] = args;
+  const verb = on ? "tag" : "untag";
+  if (!ref || !tagId) {
+    throw new CliError(`zumino request ${verb} <#N|CODE> <tagId>`, {
+      hint: "List the project's tag ids with: zumino project tags",
+    });
+  }
   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)}`);
+  // Written as two calls with literal methods rather than one with a ternary:
+  // `test/cli-routes.test.ts` reads these call sites out of the source to check
+  // each against the server, and a method it cannot read is an endpoint nothing
+  // checks.
+  const res = on
+    ? await api(ctx, "PUT", `${path}/tags/${encodeURIComponent(tagId)}`)
+    : await api(ctx, "DELETE", `${path}/tags/${encodeURIComponent(tagId)}`);
+  if (flags.json) return json(res ?? { ok: true }), 0;
+  out(`${ref}  ${on ? "tagged" : "untagged"}`);
   return 0;
 }

package/src/commands/skill.js

@@ -27,12 +27,22 @@ function defaultDir() {
   return join(homedir(), ".claude", "skills", "zumino");
 }
 
+export const SUB = { install };
+
 export async function run(args, flags) {
+  // `zumino skill` has meant `zumino skill install` since the first release, and
+  // it is the one group with a default: there is nothing else to do with a
+  // bundled document. `spec.js` records that as `defaultSub`, so the dispatcher
+  // validates the flags against `install` rather than refusing a bare `skill`.
   const [sub = "install"] = args;
-  if (sub !== "install") {
+  const fn = SUB[sub];
+  if (!fn) {
     throw new CliError(`zumino skill: unknown subcommand "${sub}".`, { hint: "Only: install" });
   }
+  return fn(args.slice(1), flags);
+}
 
+async function install(args, flags) {
   const dir = flags.dir ? String(flags.dir) : defaultDir();
   const target = join(dir, "SKILL.md");
   const installed = readVersion(target);