@nodii/dev 0.5.0 → 0.6.2

package/README.md

@@ -36,6 +36,11 @@ refuses those flags. The first command you run after upgrading deletes the old
 config and its stored secret (Keychain item or file) without printing it, then
 asks you to run `nodii-dev login`.
 
+`nodii-dev` is only the Dev control CLI. The local-stack CLI is `./nodii-stack`,
+run from the `nodii-local-stack` checkout (renamed per operator ruling G3-6,
+with no alias under the old name). Typing one of its verbs here, such as
+`nodii-dev doctor`, fails and names the `./nodii-stack` command instead.
+
 Every command accepts `--json`; without it, output is formatted for humans.
 Dev failures print Dev's error code to stderr and exit non-zero.
 
@@ -93,7 +98,34 @@ nodii-dev heartbeat audit [SERVICE]
 nodii-dev design entries [--kind KIND] [--group GROUP] [--q TEXT]
 nodii-dev design entry KEY
 nodii-dev design guide PAGE_TYPE
+```
+
+### Design-system guidelines
 
+Edit an entry's guideline through Dev, not with signed scripts. A proposal is
+a guideline change set; a person approves or rejects it in Dev (nobody decides
+their own), and the approved edit becomes a design-system PR.
+
+```bash
+nodii-dev design guideline list [--drafted] [--kind KIND] [--q TEXT] [--all]
+nodii-dev design guideline show ENTRY > ENTRY.md     # the editable Markdown form
+nodii-dev design guideline propose ENTRY --file ENTRY.md [--summary TEXT] [--dry-run]
+nodii-dev design changeset list [--entry KEY] [--state in_review] [--limit N]
+nodii-dev design changeset show GCS-001
+```
+
+The file has one `## <list>` section per statement list (`whenToUse`,
+`whenNotToUse`, `dos`, `donts`, and for an active guideline `anatomy`,
+`states.states`, `states.loading`, `states.empty`, `states.error`, `copy`,
+`composition`, `data.notes`), one `- ` bullet per item, and `(drafted)` after
+the list name when the text still awaits a real source. A line that is an
+HTML comment is ignored (`<!--` inside an item stays in its text), and a line
+break inside an item reads back as a space. The `#` title, as `show` prints it,
+names the entry: `propose` refuses a file titled for another one. `propose` sends
+only the lists that differ from Dev's current guideline, and `--dry-run`
+prints them without creating anything.
+
+```bash
 nodii-dev figma lock FILE_KEY --title TEXT
 nodii-dev figma check FILE_KEY
 nodii-dev figma log-write CHANGE_SET --tool TOOL --nodes NODE[,NODE]
@@ -137,8 +169,83 @@ nodii-dev people refresh-names
 nodii-dev setup                    # preview files that would change
 nodii-dev setup --yes              # merge and write the harness
 nodii-dev setup --check            # exit non-zero when it has drifted
+
+nodii-dev rulebook list [--section rulebook|services] [--kind KIND] [--q TEXT]
+nodii-dev rulebook show CODE [--version V]     # the current text, from Dev
+nodii-dev rulebook diff CODE [--from V] [--to V]
+
+nodii-dev docs check PATH...                   # local M-05 checks only
+nodii-dev docs validate PATH... --class CLASS  # Dev's dry run of the upload
+nodii-dev docs upload PATH... --class ruling|conformance|editorial
+                      [--base CODE=VERSION ...] [--decision DECISION.json]
+                      [--conformance-ref PR|REPO@SHA] [--meaning-unchanged REASON]
+                      [--wait [--wait-minutes N]]
+nodii-dev docs ratify --domain KEY [--domain KEY ...] --decision DECISION.json [--wait]
+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
 ```
 
+## AD documents
+
+AD documents (the rulebook and per-service feature docs) live in Dev, one
+current text per document with its version history (M-05). `docs upload`
+takes files or folders (folders are searched for `.md` files, skipping `_`
+and `.` entries) and checks every document locally before sending anything:
+front matter, the section order for its kind, unique clause ids that use the
+document's code, no bare decision ids (`D123`; cite `pre:D123`), and the
+parked (`Undecided`) items, which it lists. All problems are printed with
+Dev's error codes, and nothing is sent until there are none. Dev then runs the
+same checks, plus the ones that need its data, in one transaction.
+
+- `--class` is required on every write (M05-8). A `ruling` carries its
+  decision (`--decision`, with `amends`), and the decision locks with the new
+  versions or nothing is written. An `editorial` write that changes a Rules
+  clause is refused unless `--meaning-unchanged REASON` is given (M05-10).
+- A new document is based on nothing. For a document Dev already has, pass
+  the version you started from with `--base CODE=VERSION` (M05-11). The CLI
+  never fills it in from Dev, so a stale edit is refused instead of
+  overwriting newer text.
+- **Parked items:** when a document has parked items the operator has not
+  acknowledged, Dev refuses the upload and records the list. The CLI prints
+  it and exits `4`. The operator acknowledges it in Dev (this CLI is an OAuth
+  app and cannot). Re-run the upload then, or pass `--wait` to poll and retry
+  once it is acknowledged.
+- `docs ratify` is the bulk ratification mode: one decision locks v1.0 of
+  every draft document in the named domains, which then become AD (M05-2).
+  Upload the drafts first (`--class conformance`), then ratify domain by
+  domain. The decision file holds `title`, `context`, `options`, `ruling`,
+  `consequences` and `provenance`; Dev mints the `DEC-nnnn` id and generates
+  the amends. A domain that is already AD can be named again to ratify drafts
+  added to it since (a new feature doc in a ratified service).
+- `docs validate` also prints Dev's warnings for each document (they never
+  block) and any problems with the decision's amends.
+
+Like every other command, these reach Dev only through the platform edge
+(`/devops/api/v1/documents`, `/domains`, `/harness`, …) with the OAuth login.
+
+## Agent harness
+
+`harness install` writes the repository's agent harness as Dev generates it
+from the ratified methodology: the `CLAUDE.md` and `AGENTS.md` pointer
+blocks, one pointer skill per methodology document, the Claude Code hooks
+merged into `.claude/settings.json`, and Dev's `.nodii/harness.json`. Every
+generated file carries the methodology version it came from. Nothing about
+the rules is authored locally. Run it in the service's own repository: it
+installs one service at a time, and there is no fleet mode. `--include-drafts`
+uses draft methodology while none is ratified.
+
+The CLI records what it wrote in `.nodii/harness-state.json` and never touches
+anything else. An existing file it did not write is refused, unless the
+operator names it with `--adopt PATH` (a `CLAUDE.md` then keeps its text and
+gains the managed block; `settings.json` keeps its other keys and hooks).
+`harness update` re-syncs: it prints the methodology version change, which
+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.
+
 ## Build lanes and repository setup
 
 `lane start` creates and starts a lane. It infers the repository, branch and
@@ -190,7 +297,9 @@ runtime, people, agents, inbox/gates, design, runbooks,
 doctrine and exceptions, changelog, health verdicts, approval kinds,
 notification registry, skills, questions, decisions, drift, requests,
 pipelines, runners, routing, usage, audit, reconciliation, cron, composite
-surfaces, service edges, lanes, swaps, ideas, and terminology. `api list` is the authoritative discovery view;
+surfaces, service edges, lanes, swaps, ideas, terminology, and the AD era: `rulebook`
+(documents, plus `rulebook versions CODE`), `ad-decisions`, `domains`, `standardizations`,
+`archive` (`archive resolve --ref pre:D1366`), and `harness methodology`. `api list` is the authoritative discovery view;
 `api OPERATION_ID` makes every operation callable even without an alias.
 
 `figma check` exits `0` when allowed and `3` when denied. The pre-hook permits

package/dist/api.js

@@ -95,12 +95,14 @@ export const GROUPS = {
   sagas: "Sagas", "outbox-topics": ["Outbox", "OutboxTopics"], tables: "Tables", libraries: "Libraries", workers: "Workers",
   projects: "Projects", issues: "Issues", backlog: "Backlogs", backlogs: "Backlogs", builds: "Delivery", changes: "Delivery",
   runtime: "Runtime", people: "People", agents: "Agents", inbox: "Inbox", gate: "Inbox", design: "Design", runbooks: "Runbooks",
-  doctrine: ["Doctrine", "DoctrineExceptions"], rulebook: "Doctrine", changelog: "Changelog", "health-verdicts": "HealthVerdicts",
+  doctrine: ["Doctrine", "DoctrineExceptions"], changelog: "Changelog", "health-verdicts": "HealthVerdicts",
   "approval-kinds": "ApprovalKinds", "notification-registry": "Notification registry", skills: "Skills", "open-questions": "OpenQuestions",
   decisions: "Decisions", drift: "Drift", requests: "Requests", pipelines: "Pipelines", slices: "Slices", "sql-lookups": "SqlLookups",
   runners: "Runners", routing: "Routing", usage: "Usage", audit: "AuditLog", reconciliation: "Reconciliation", cron: "Cron", health: "Health",
   composite: "Composite", "service-edges": "ServiceEdges", lanes: "Lanes",
-  swaps: "Swaps", ideas: "Ideas", terminology: "Terminology",
+  swaps: "Swaps", ideas: "Ideas", terminology: "Terminology", credentials: "Credentials",
+  rulebook: "ad-documents", "ad-decisions": "ad-decisions", domains: "ad-domains", standardizations: "standardizations",
+  archive: "archive", harness: "harness",
 };
 
 export const ALIASES = {
@@ -129,7 +131,7 @@ export const ALIASES = {
   "gate:fleet": "getFleetGate", "gate:service": "getServiceGate", "gate:dry-run": "getGateDryRun",
   "runbooks:list": "listRunbooks", "runbooks:show": "getRunbook", "runbooks:create": "registerRunbook", "runbooks:update": "updateRunbook",
   "doctrine:list": "listDoctrine", "doctrine:show": "getDoctrine", "doctrine:create": "createDoctrine", "doctrine:revise": "reviseDoctrine",
-  "rulebook:list": "listDoctrine", "rulebook:show": "getDoctrine", "changelog:list": "listChangelog", "changelog:append": "appendChangelog",
+  "changelog:list": "listChangelog", "changelog:append": "appendChangelog",
   "health-verdicts:list": "listHealthVerdicts", "health-verdicts:post": "postHealthVerdict",
   "approval-kinds:list": "listApprovalKinds", "approval-kinds:show": "getApprovalKind", "approval-kinds:create": "createApprovalKind",
   "notification-registry:list": "listNotificationEvents", "notification-registry:show": "getNotificationEvent", "notification-registry:propose": "proposeNotificationEvent",
@@ -143,14 +145,28 @@ export const ALIASES = {
   "service-edges:list": "listServiceEdges", "service-edges:show": "getServiceEdgesForService",
   "swaps:list": "listSwaps", "swaps:show": "getSwap", "swaps:create": "createSwap", "swaps:close": "closeSwap",
   "ideas:list": "listIdeas", "ideas:show": "getIdea", "ideas:create": "createIdea", "ideas:status": "updateIdeaStatus",
+  "rulebook:versions": "listAdDocumentVersions", "rulebook:parked": "getAdDocumentParked",
+  "ad-decisions:list": "listAdDecisions", "ad-decisions:show": "getAdDecision", "ad-decisions:lock": "lockAndAmendAdDecision",
+  "domains:list": "listAdDomains", "domains:show": "getAdDomain",
+  "standardizations:list": "listStandardizations", "standardizations:show": "getStandardization", "standardizations:update": "updateStandardization",
+  "archive:search": "searchPreDevArchive", "archive:resolve": "resolvePreCitation",
+  "harness:show": "generateHarness", "harness:methodology": "getHarnessMethodologyVersion",
   "terminology:list": "listTerminology", "terminology:show": "getTerminologyTerm", "terminology:create": "createTerminologyTerm", "terminology:update": "updateTerminologyTerm",
 };
 
+// Decisions a person makes in Dev (operator authority): nodii-dev never sends them.
+export const PERSON_ONLY = new Set(["approveDesignGuidelineChangeSet", "rejectDesignGuidelineChangeSet", "mergeDesignRelease"]);
+export function refusePersonOnly(operationId) {
+  if (PERSON_ONLY.has(operationId))
+    throw new CliError("PERSON_ONLY", `${operationId} is a person's decision in Dev; nodii-dev does not send it.`, 2);
+}
+
 export function findFirstClass(operations, group, action) {
   const aliased = ALIASES[`${group}:${action}`];
   if (aliased) return operations.find(x => x.operationId === aliased);
   const tags = Array.isArray(GROUPS[group]) ? GROUPS[group] : [GROUPS[group]];
-  const candidates = operations.filter(x => x.tags.some(t => tags.includes(t)));
+  // A person-only operation is never picked by name, so a guessed verb cannot reach it.
+  const candidates = operations.filter(x => !PERSON_ONLY.has(x.operationId) && x.tags.some(t => tags.includes(t)));
   const normalized = action?.replace(/-([a-z])/g, (_, c) => c.toUpperCase()).toLowerCase();
   return candidates.find(x => x.operationId.toLowerCase() === normalized || x.operationId.toLowerCase().endsWith(normalized));
 }

package/dist/cli.js

@@ -24,6 +24,9 @@ import {
 } from "./oauth.js";
 import { heartbeatCurrentLane, postHook, preHook, settingsSnippet, workflowSuggestion } from "./hooks.js";
 import { setupCommand } from "./setup.js";
+import { harnessCommand } from "./harness.js";
+import { docsCommand, rulebookCommand } from "./upload.js";
+import { changeSetCommand, guidelineCommand } from "./guidelines.js";
 import {
   ALIASES,
   GROUPS,
@@ -31,6 +34,7 @@ import {
   callOperation,
   findFirstClass,
   flagsToOperation,
+  refusePersonOnly,
   loadOpenApi,
   operationsFrom,
   parseParams,
@@ -56,9 +60,20 @@ Usage: nodii-dev <command> [options] [--json]
   drift file | request file
   decisions list|get|search
   design entries|entry|guide
+  design guideline list [--drafted] [--all] | show ENTRY
+  design guideline propose ENTRY --file FILE.md [--summary TEXT] [--dry-run]
+  design changeset list [--entry KEY] [--state STATE] | show ID
   figma lock|check|log-write|submit|apply|published|abandon|release
   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
+  docs check|validate|upload <path...> --class ruling|conformance|editorial
+       [--base CODE=VERSION] [--decision FILE] [--conformance-ref REF]
+       [--meaning-unchanged REASON] [--wait]
+  docs ratify --domain KEY [--domain KEY ...] --decision FILE [--wait]
+  docs parked [CODE] [--status pending|acknowledged]
+  rulebook list|show CODE [--version V]|diff CODE
 
   lane start <key> --title TEXT --kind KIND --side SIDE [--repo REPO] [--issue ISSUE]
   lane step <key> --side SIDE --start|--done|--block <step>
@@ -79,10 +94,15 @@ Resource commands cover every OpenAPI tag, including services, feature-docs,
 contracts, sagas, outbox-topics, tables, libraries, workers, projects, issues,
 backlogs, builds, changes, deploy-reports, runtime, people, agents, inbox,
 gate, design, runbooks, doctrine, changelog, health-verdicts, approval-kinds,
-notification-registry, skills, open-questions, decisions, drift, and requests.
+notification-registry, skills, open-questions, decisions, drift, requests,
+rulebook, ad-decisions, domains, standardizations, archive, and harness.
 
 Run a command with --help or see the package README for all flags.`;
 
+// Verbs of the local-stack CLI, which shared this name until it became
+// ./nodii-stack (operator G3-6, no alias). Named here only to point there.
+const STACK_VERBS = new Set(["up", "down", "doctor", "sync", "seed", "wipe", "reset", "rebuild", "restart", "smoke", "urls", "peek", "trace", "stats", "bootstrap", "provenance", "stale", "status", "logs", "world", "totp", "token", "bench"]);
+
 async function stdinText() {
   let value = "";
   for await (const chunk of stdin) value += chunk;
@@ -222,6 +242,7 @@ export async function main(argv = process.argv.slice(2)) {
     if (!action) throw new CliError("USAGE", "api needs an operationId or list", 2);
     const entry = operations.find((x) => x.operationId === action);
     if (!entry) throw new CliError("UNKNOWN_OPERATION", `No OpenAPI operationId: ${action}`, 2);
+    refusePersonOnly(entry.operationId);
     const parsed = await readBody(f.body);
     const request = buildOperationRequest(entry, parseParams(f.param), parsed?.value);
     return emit(await devRawRequest(request.method, request.path, parsed?.text), json);
@@ -248,6 +269,16 @@ export async function main(argv = process.argv.slice(2)) {
   }
   const emitCommand = async (result) => emit(result.payload, json, result.human);
   if (command === "setup") return emitCommand(await setupCommand(f));
+  if (command === "harness" && ["install", "update"].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));
+  }
+  if (command === "docs") return emitCommand(await docsCommand(action, rest, f));
+  if (command === "rulebook" && ["list", "show", "diff"].includes(action)) return emitCommand(await rulebookCommand(action, rest, f));
+  // Guideline change sets: approving or rejecting one is a person's action in Dev.
+  if (command === "design" && action === "guideline") return emitCommand(await guidelineCommand(rest[0], rest.slice(1), f));
+  if (command === "design" && action === "changeset") return emitCommand(await changeSetCommand(rest[0], rest.slice(1), f));
   if (command === "lane") return emitCommand(await laneCommand(action, rest, f));
   if (command === "next") return emitCommand(await nextCommand(action, f));
   if (command === "built") return emitCommand(await builtCommand(action, rest, f));
@@ -568,7 +599,7 @@ export async function main(argv = process.argv.slice(2)) {
   }
   throw new CliError(
     "USAGE",
-    `Unknown command: ${[command, action].filter(Boolean).join(" ")}`,
+    `Unknown command: ${[command, action].filter(Boolean).join(" ")}${STACK_VERBS.has(command) ? `. The local-stack CLI is \`./nodii-stack ${command}\`, run from the nodii-local-stack checkout.` : ""}`,
     2,
   );
 }

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.5.0";
+export const VERSION = "0.6.2";
 export const configPath = () =>
   process.env.NODII_DEV_CONFIG_PATH ??
   join(homedir(), ".config/nodii-dev/config.json");
@@ -105,10 +105,10 @@ export function requestUrl(config, path) {
   return `${config.edgeUrl.replace(/\/$/, "")}/devops${path}`;
 }
 
-export async function devRawRequest(method, path, bodyText, contentType = "application/json") {
+async function devFetch(method, path, bodyText, contentType, accept) {
   const config = await readConfig();
   const auth = await authProvider();
-  const headers = { accept: "application/json" };
+  const headers = { accept };
   if (bodyText !== undefined) headers["content-type"] = contentType;
   Object.assign(headers, await auth.headers({ method, path, body: bodyText ?? "" }));
   const url = requestUrl(config, path);
@@ -118,7 +118,11 @@ export async function devRawRequest(method, path, bodyText, contentType = "appli
   } catch (error) {
     throw new CliError("DEV_UNREACHABLE", `Cannot reach Dev at ${new URL(url).origin}: ${error.message}`);
   }
-  const raw = await response.text();
+  return { response, raw: await response.text() };
+}
+
+export async function devRawRequest(method, path, bodyText, contentType = "application/json") {
+  const { response, raw } = await devFetch(method, path, bodyText, contentType, "application/json");
   let payload;
   try {
     payload = raw ? JSON.parse(raw) : {};
@@ -135,6 +139,15 @@ export async function devRawRequest(method, path, bodyText, contentType = "appli
   return payload;
 }
 
+/** A Dev route that answers with text (e.g. a document body as text/markdown). Errors are Dev's JSON. */
+export async function devTextRequest(method, path) {
+  const { response, raw } = await devFetch(method, path, undefined, undefined, "text/markdown, text/plain, application/json");
+  if (response.ok) return raw;
+  let payload = {};
+  try { payload = JSON.parse(raw); } catch { payload = { message: raw }; }
+  throw new CliError(payload.code ?? `HTTP_${response.status}`, payload.message ?? `Dev returned HTTP ${response.status}`, 1, payload.details);
+}
+
 export const devRequest = (method, path, body) =>
   devRawRequest(method, path, body === undefined ? undefined : JSON.stringify(body));
 
@@ -147,6 +160,9 @@ export async function checkLogin() {
 }
 
 export const encode = (value) => encodeURIComponent(value);
+// Switches never take the next token as their value, so
+// `docs upload --wait rulebook/` keeps rulebook/ as a path.
+const SWITCHES = new Set(["json", "wait", "dry-run", "check", "all", "fleet", "help", "yes", "mine", "no-browser", "include-drafts", "drafted"]);
 export function parseArgs(argv) {
   const flags = {};
   const args = [];
@@ -156,11 +172,13 @@ export function parseArgs(argv) {
       args.push(token);
       continue;
     }
-    const [key, inline] = token.slice(2).split("=", 2);
+    const at = token.indexOf("=");
+    const key = at === -1 ? token.slice(2) : token.slice(2, at);
+    const inline = at === -1 ? undefined : token.slice(at + 1);
     const value =
       inline !== undefined
         ? inline
-        : argv[i + 1] && !argv[i + 1].startsWith("--")
+        : !SWITCHES.has(key) && argv[i + 1] && !argv[i + 1].startsWith("--")
           ? argv[++i]
           : true;
     flags[key] =