@nodii/dev 0.6.4 → 0.6.5

package/README.md

@@ -78,6 +78,8 @@ nodii-dev issues create --service ID --title TEXT [--body TEXT|--body-file FILE]
 nodii-dev issues update ISSUE [the same mutable fields]
 nodii-dev issues claim ISSUE [--ttl MINUTES]
 nodii-dev issues release ISSUE [--note TEXT]
+nodii-dev issues transition ISSUE --to todo|in_progress|in_review|blocked|done|wont_do
+                            [--reason TEXT] [--dev-check REF] [--json]
 
 nodii-dev inbox list [--service ID] [--kind drift|request|question]
 nodii-dev inbox show drift|request|question ID
@@ -194,7 +196,33 @@ nodii-dev docs parked [CODE] [--status pending|acknowledged]
 
 nodii-dev harness install [--include-drafts] [--adopt PATH,...] [--dry-run]
 nodii-dev harness update [--include-drafts] [--adopt PATH,...] [--dry-run]
-nodii-dev harness update --check               # exit 1 when Dev would write anything different
+nodii-dev harness check [--json]               # 0 current, 1 differs from Dev, 2 no harness
+nodii-dev harness update --check               # the same check
+```
+
+### Moving an issue: `issues transition`
+
+`issues transition` moves an issue along Dev's status map (MW1-16) with
+Dev's `transitionIssue` operation. It checks MW1-17 before sending anything,
+and refuses with `USAGE` (exit 2) when a move lacks what it needs:
+
+| `--to` | Needs |
+|---|---|
+| `blocked` | `--reason` naming the blocking condition and who or what clears it (`cleared by …`, `waiting on …`, `until …`) |
+| `wont_do` | `--reason` saying why |
+| `done` | `--dev-check REF` citing the lane's dev-check evidence (MW3-36); a merge alone never makes an issue done |
+
+`--reason` and `--dev-check` are optional for the other moves, and
+`--dev-check` goes only with `done`. Dev keeps one note per transition, so
+the CLI sends the reason, then `Dev check: REF` on its own line, as that
+note. A move Dev refuses (for example `ISSUE_ILLEGAL_TRANSITION`, with the
+allowed set in its details, or `CLAIM_HELD_BY_OTHER`) exits 1 with Dev's
+error code unchanged (MW1-61).
+
+```text
+nodii-dev issues transition TKT-412 --to blocked \
+  --reason "edge route /tickets 404s on dev; cleared by the nodii-edge lane deploying it"
+nodii-dev issues transition TKT-412 --to done --dev-check "lane:tkt-412 dev probe GET /tickets/412 200"
 ```
 
 ## AD documents
@@ -255,6 +283,24 @@ source documents moved, and each file created, updated or removed. It
 removes only files, blocks and hook entries it wrote, and it refuses (writing
 nothing) when one of its files was edited by hand.
 
+`harness check` (MW5-4) compares the repository with what Dev would generate
+now and writes nothing. `harness update --check` is the same check. It asks
+Dev with the options install recorded, and exits:
+
+- `0` when every file matches and the stamp names the methodology version Dev
+  serves: `Harness is current: REPO, methodology VERSION, N files match Dev.`
+- `1` when anything differs. It prints one line per difference: the
+  methodology version, each source document that moved, each file that is
+  missing, differs from Dev's or is no longer generated, and each file edited
+  by hand since nodii-dev wrote it. `--json` gives the same as `current`,
+  `installed`, `available`, `sources`, `changes` and `conflicts`.
+- `2` with `HARNESS_NOT_INSTALLED` when the repository has no harness. The
+  message lists the files `harness install` would write.
+
+Inside a lane, a failed check is noted in the step, and the harness files
+are left alone; the repository's orchestrator runs `harness update` in a
+`chore` lane (MW5-8).
+
 ## Preflight: `doctor`
 
 Run `nodii-dev doctor` from the lane's worktree, with the lane agent's config,

package/dist/cli.js

@@ -58,6 +58,8 @@ Usage: nodii-dev <command> [options] [--json]
   doctor [--json]                       # preflight: sign-in, agent, permissions, machine, repo, lane slots
   agent register --name NAME | agent heartbeat
   issues list|show|create|update|claim|release
+  issues transition ISSUE --to STATUS [--reason TEXT] [--dev-check REF]
+                                        # blocked and wont_do need --reason; done needs --dev-check
   inbox list|show
   drift file | request file
   decisions list|get|search
@@ -69,7 +71,8 @@ Usage: nodii-dev <command> [options] [--json]
   hook claude-figma-pre|claude-figma-post|print-settings
   setup [--yes|--check]                 # dry-run by default
   harness install|update [--include-drafts[=false]] [--adopt PATH,...] [--dry-run]
-  harness update --check                # exit 1 when Dev would write anything different
+  harness check                         # 0 current, 1 differs from Dev, 2 not installed
+  harness update --check                # the same check
   docs check|validate|upload <path...> --class ruling|conformance|editorial
        [--base CODE=VERSION] [--decision FILE] [--conformance-ref REF]
        [--meaning-unchanged REASON] [--wait]
@@ -224,9 +227,44 @@ async function issues(action, args, f, json) {
       }),
       json,
     );
+  if (action === "transition")
+    return emit(
+      await devRequest("POST", `/api/v1/issues/${encode(ref)}/transition`, {
+        ...transitionBody(f),
+        onBehalfOf: config.person,
+      }),
+      json,
+      (p) => `${p.data.key} ${p.data.status} — ${p.data.title}`,
+    );
   throw new CliError("USAGE", `Unknown issues action: ${action}`, 2);
 }
 
+const ISSUE_STATUSES = ["todo", "in_progress", "in_review", "blocked", "done", "wont_do"];
+// A blocked reason names who or what clears it: "cleared by", "unblocks", "waiting on", "until".
+const CLEARED_BY = /\b(clear(s|ed)?|unblock(s|ed)?|wait(s|ing)? (on|for)|until)\b/i;
+
+/**
+ * transitionIssue's body ({ to, note }), with MW1-17 checked before anything
+ * is sent. Dev stores no separate reason or dev-check field: both go in the note.
+ */
+export function transitionBody(f) {
+  const to = requireFlag(f, "to");
+  if (!ISSUE_STATUSES.includes(to))
+    throw new CliError("USAGE", `--to must be one of ${ISSUE_STATUSES.join(", ")}`, 2);
+  const reason = typeof f.reason === "string" ? f.reason.trim() : "";
+  const devCheck = typeof f["dev-check"] === "string" ? f["dev-check"].trim() : "";
+  if (f["dev-check"] !== undefined && to !== "done")
+    throw new CliError("USAGE", "--dev-check goes with --to done", 2);
+  if (to === "blocked" && !CLEARED_BY.test(reason))
+    throw new CliError("USAGE", 'A move to blocked needs --reason naming the blocking condition and who or what clears it (MW1-17), e.g. --reason "waiting on PR #12 in nodii-edge; cleared by the edge lane merging it"', 2);
+  if (to === "wont_do" && !reason)
+    throw new CliError("USAGE", "A move to wont_do needs --reason saying why (MW1-17)", 2);
+  if (to === "done" && !devCheck)
+    throw new CliError("USAGE", "A move to done needs --dev-check REF citing the lane's dev-check evidence (MW1-17, MW3-36). A merge alone never makes an issue done.", 2);
+  const note = [reason, devCheck && `Dev check: ${devCheck}`].filter(Boolean).join("\n");
+  return { to, ...(note ? { note } : {}) };
+}
+
 export async function main(argv = process.argv.slice(2)) {
   if (argv.length === 1 && ["--version", "-v"].includes(argv[0]))
     return console.log(VERSION);
@@ -282,7 +320,7 @@ export async function main(argv = process.argv.slice(2)) {
     if (result.exitCode) process.exitCode = result.exitCode;
     return;
   }
-  if (command === "harness" && ["install", "update"].includes(action)) {
+  if (command === "harness" && ["install", "update", "check"].includes(action)) {
     // `--include-drafts` is a switch: `--include-drafts false` would leave `false` here and turn drafts on.
     if (rest.length) throw new CliError("USAGE", `harness ${action} takes no arguments, got: ${rest.join(" ")}. Write a flag value as --include-drafts=false.`, 2);
     return emitCommand(await harnessCommand(action, f));

package/dist/core.js

@@ -4,7 +4,7 @@ import { chmod, mkdir, readFile, rm, writeFile } from "node:fs/promises";
 import { homedir, platform } from "node:os";
 import { dirname, join } from "node:path";
 
-export const VERSION = "0.6.4";
+export const VERSION = "0.6.5";
 export const configPath = () =>
   process.env.NODII_DEV_CONFIG_PATH ??
   join(homedir(), ".config/nodii-dev/config.json");

package/dist/doctor.js

@@ -15,7 +15,7 @@ import { inferGitContext, repoName } from "./lanes.js";
  */
 export const LANE_PERMISSIONS = [
   { key: "devops.issues.read", for: "issues list|show" },
-  { key: "devops.issues.write", for: "issues create|update|claim|release, api transitionIssue" },
+  { key: "devops.issues.write", for: "issues create|update|claim|release|transition" },
   { key: "devops.lanes.read", for: "lane show|list, next" },
   { key: "devops.lanes.write", for: "lane start|step|evidence|heartbeat|review|land|verify" },
   { key: "devops.agents.read", for: "whoami, reading this agent" },

package/dist/harness.js

@@ -290,33 +290,78 @@ export async function repoContext(cwd = process.cwd()) {
 const flagList = (value) => (value === undefined || value === true ? [] : [value].flat().flatMap((x) => String(x).split(",")).filter(Boolean));
 const changeLine = (c) => `${{ create: "+", remove: "-" }[c.action] ?? "~"} ${c.path}${["create", "update", "remove"].includes(c.action) ? "" : ` (${c.action})`}`;
 
+// What each planned change means for a check: how the file on disk differs from Dev's.
+const DIFFERENCE = {
+  create: "missing; Dev would create it",
+  update: "differs from Dev's",
+  "add block": "has no nodii-dev block",
+  merge: "hooks differ from Dev's",
+  remove: "Dev no longer generates it",
+  "remove block": "Dev no longer generates its block",
+  unmerge: "has hooks Dev no longer generates",
+};
+const plural = (n, word) => `${n} ${word}${n === 1 ? "" : "s"}`;
+
+/**
+ * `harness check` (and its alias `harness update --check`): compare the files
+ * on disk, and the methodology stamp, with what Dev would generate now (MW5-4,
+ * MW5-6). Writes nothing. Exit 0 when current, 1 when anything differs, 2
+ * when there is no harness.
+ */
+async function checkCommand(root, repo, state, fetchHarness) {
+  if (!state) {
+    let would;
+    try {
+      const plan = await planHarness(root, (await fetchHarness()).data, { install: true });
+      const paths = plan.changes.map((c) => c.path);
+      const taken = plan.conflicts.map((c) => c.path);
+      would = ` Dev would write ${plural(paths.length, "file")}: ${paths.join(", ")}.${taken.length ? ` ${plural(taken.length, "file")} ${taken.length === 1 ? "already exists and needs" : "already exist and need"} --adopt: ${taken.join(", ")}.` : ""}`;
+    } catch (error) {
+      would = ` Dev cannot say what install would write (${error?.code ?? "ERROR"}: ${error?.message ?? error}).`;
+    }
+    throw new CliError("HARNESS_NOT_INSTALLED", `No nodii-dev harness here.${would} Run \`nodii-dev harness install\` first.`, 2);
+  }
+  // Compare the files Dev would write now, not only the version: the
+  // CLAUDE.md block also changes when the service's domain becomes AD.
+  const harness = (await fetchHarness()).data;
+  const plan = await planHarness(root, harness, { install: false });
+  const moved = sourceChanges(state.sources, harness.sources);
+  const versionMoved = harness.methodologyVersion !== state.methodologyVersion;
+  const behind = versionMoved || moved.length > 0 || plan.changes.length > 0 || plan.conflicts.length > 0;
+  const payload = { data: { repo, current: !behind, installed: state.methodologyVersion, available: harness.methodologyVersion, sources: moved, changes: plan.changes.map(({ path, action: a, mode }) => ({ path, action: a, mode })), conflicts: plan.conflicts } };
+  const owned = Object.keys(state.files ?? {}).length;
+  if (!behind) return { payload, human: `Harness is current: ${repo}, methodology ${state.methodologyVersion}, ${plural(owned, "file")} ${owned === 1 ? "matches" : "match"} Dev.` };
+  process.exitCode = 1;
+  return {
+    payload,
+    human: [
+      `Harness differs from what Dev would generate for ${repo}:`,
+      ...(versionMoved ? [`  methodology: ${state.methodologyVersion} installed, ${harness.methodologyVersion} available`] : []),
+      ...moved.map((x) => `  source ${x}`),
+      ...plan.changes.map((c) => `  ${c.path}: ${DIFFERENCE[c.action] ?? c.action}`),
+      ...plan.conflicts.map((c) => `  ${c.path}: ${c.reason}`),
+      "Fix with `nodii-dev harness update` (inside a lane: note this in the step and leave the harness files alone; MW5-8).",
+    ].join("\n"),
+  };
+}
+
 export async function harnessCommand(action, flags, { request = devRequest, context = repoContext } = {}) {
-  if (!["install", "update"].includes(action)) throw new CliError("USAGE", "harness install|update [--repo NAME] [--service ID] [--include-drafts[=false]] [--adopt PATH,...] [--dry-run] [--check]", 2);
+  if (!["install", "update", "check"].includes(action)) throw new CliError("USAGE", "harness install|update|check [--repo NAME] [--service ID] [--include-drafts[=false]] [--adopt PATH,...] [--dry-run] [--check]", 2);
   if (flags.fleet || flags.all) throw new CliError("USAGE", "The harness is installed one service at a time, in that service's repository. There is no fleet mode.", 2);
   if (flags.root === true || flags.repo === true) throw new CliError("USAGE", "--root and --repo need a value.", 2);
   const ctx = flags.root ? { root: flags.root, repo: flags.repo } : await context();
   const repo = flags.repo && flags.repo !== true ? String(flags.repo) : ctx.repo;
   if (!repo) throw new CliError("USAGE", "Pass --repo NAME.", 2);
   const state = await readState(ctx.root);
-  // Update asks Dev for what install asked for, unless told otherwise.
-  const saved = action === "update" ? (state?.request ?? {}) : {};
+  // Update and check ask Dev for what install asked for, unless told otherwise.
+  const saved = action === "install" ? {} : (state?.request ?? {});
   const serviceId = flags.service && flags.service !== true ? String(flags.service) : (saved.serviceId ?? undefined);
   const includeDrafts = flags["include-drafts"] !== undefined ? flags["include-drafts"] !== "false" : Boolean(saved.includeDrafts);
   const params = { repo, serviceId, includeDrafts: includeDrafts ? "true" : undefined };
 
   if (action === "install" && flags.check) throw new CliError("USAGE", "--check goes with `harness update`; to preview an install use --dry-run.", 2);
-  if (action === "update" && flags.check) {
-    if (!state) throw new CliError("HARNESS_NOT_INSTALLED", "No nodii-dev harness here. Run `nodii-dev harness install` first.", 2);
-    // Compare the files Dev would write now, not only the version: the
-    // CLAUDE.md block also changes when the service's domain becomes AD.
-    const harness = (await request("GET", `/api/v1/harness${query(params)}`)).data;
-    const plan = await planHarness(ctx.root, harness, { install: false });
-    const moved = sourceChanges(state.sources, harness.sources);
-    const behind = harness.methodologyVersion !== state.methodologyVersion || plan.changes.length > 0 || plan.conflicts.length > 0;
-    const payload = { data: { repo, current: !behind, installed: state.methodologyVersion, available: harness.methodologyVersion, sources: moved, changes: plan.changes.map(({ path, action: a, mode }) => ({ path, action: a, mode })), conflicts: plan.conflicts } };
-    if (behind) process.exitCode = 1;
-    return { payload, human: behind ? [`Harness is behind: ${state.methodologyVersion} → ${harness.methodologyVersion}`, ...moved.map((x) => `  source ${x}`), ...plan.changes.map(changeLine), ...plan.conflicts.map((c) => `  conflict ${c.path}: ${c.reason}`), "Run `nodii-dev harness update`."].join("\n") : `Harness is current (${state.methodologyVersion}).` };
-  }
+  if (action === "check" && (flags["dry-run"] || flags.adopt)) throw new CliError("USAGE", "harness check writes nothing; --dry-run and --adopt go with install and update.", 2);
+  if (action === "check" || (action === "update" && flags.check)) return checkCommand(ctx.root, repo, state, () => request("GET", `/api/v1/harness${query(params)}`));
 
   const harness = (await request("GET", `/api/v1/harness${query(params)}`)).data;
   const plan = await planHarness(ctx.root, harness, { install: action === "install", adopt: flagList(flags.adopt), request: { ...(serviceId ? { serviceId } : {}), includeDrafts } });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nodii/dev",
-  "version": "0.6.4",
+  "version": "0.6.5",
   "description": "Agent CLI for Nodii Dev, reached through the platform edge",
   "type": "module",
   "bin": {