@nodii/dev 0.4.1 → 0.6.1

package/README.md

@@ -13,35 +13,43 @@ nodii-dev login                      # opens the approval page in your browser
 nodii-dev login --no-browser         # prints the link and code instead
 nodii-dev login --scope devops.issues.read,devops.issues.write   # narrower grant
 nodii-dev agent register --name my-agent
-
-# Temporary compatibility path:
-printf '%s' "$PLANNING_HUB_HMAC_SECRET" | nodii-dev login --person PERSON_ID --secret-stdin
-nodii-dev login --hmac --person PERSON_ID --from-aws
 ```
 
-OAuth is the default: the CLI signs in as the platform tenant's nodii-dev app
-(`NODII_DEV_OAUTH_CLIENT_ID` or `--client-id` overrides the built-in public
-client id). With no `--scope`, auth grants the app's full ceiling: every live
-`devops.*` key except `devops.releases.promote`, which is never granted. Pass
-`--hmac` to keep the interim path. Login uses RFC 8628 and
-opens the verification page on an interactive terminal unless `--no-browser`
-is passed. Refresh tokens are stored only in macOS Keychain or Linux Secret
-Service (`secret-tool`); the CLI refuses plaintext fallback. Access tokens stay
-in memory. OAuth API calls use the platform edge `/devops` route and send the
-registered `x-agent-id`. `logout` revokes the refresh chain before erasing local
+`nodii-dev` talks only to Dev, through the platform edge
+(`https://platform.nucleus-cloud.in/devops/*`), signed in as the platform
+tenant's nodii-dev OAuth app (D1368). There is no other host and no other way
+to sign in. `NODII_DEV_OAUTH_CLIENT_ID` or `--client-id` overrides the built-in
+public client id. With no `--scope`, auth grants the app's full ceiling: every
+live `devops.*` key except `devops.releases.promote`, which is never granted.
+Login uses the RFC 8628 device flow and opens the verification page on an
+interactive terminal unless `--no-browser` is passed. Refresh tokens are
+stored only in macOS Keychain or Linux Secret Service (`secret-tool`); the CLI
+refuses plaintext fallback. Access tokens stay in memory. Every API call goes
+to the edge's `/devops` prefix with the OAuth bearer and the registered
+`x-agent-id`. `logout` revokes the refresh chain before erasing local
 credentials. `--auth-url`, `--edge-url`, and `--tenant-hint` select another real
 deployment.
 
+Upgrading from 0.4.x: the shared-secret login (`login --hmac`, `--person`,
+`--secret-stdin`, `--from-aws`, `--hub-url`) was removed in 0.5.0, and `login`
+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.
-Hub failures print the hub error code to stderr and exit non-zero.
+Dev failures print Dev's error code to stderr and exit non-zero.
 
 ## Commands
 
 ```text
-nodii-dev login [--no-browser]
-nodii-dev login --hmac --person ID (--secret-stdin | --from-aws)
+nodii-dev login [--no-browser] [--scope KEYS]
 nodii-dev logout
-nodii-dev whoami
+nodii-dev whoami                   # OAuth identity plus the registered agent
 nodii-dev config show
 
 nodii-dev api list [--tag TAG] [--json]
@@ -134,17 +142,92 @@ 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
 worktree from git unless overridden, and resolves `--issue` keys to the UUIDs
-required by the hub. Lane keys are passed directly to every lane and Built
+required by Dev. Lane keys are passed directly to every lane and Built
 acknowledgement route. `next` reads the lane's generated
 API steps and prints the exact next `lane step` command. Server refusals,
 including operator-only actions, workflow blocks, lane limits and Built items
-that are not on dev, retain the hub error code/message and exit non-zero.
+that are not on dev, retain Dev's error code/message and exit non-zero.
 
 `setup` installs the Claude Code workflow harness in the current repository.
 It writes `.claude/skills/nodii-build-workflow/SKILL.md`, merges SessionStart,
@@ -152,15 +235,16 @@ Stop and Bash PostToolUse hooks into `.claude/settings.json`, and maintains one
 marked section in an existing `CLAUDE.md` or `AGENTS.md` (creating `CLAUDE.md`
 when neither exists). Existing settings and hooks are preserved. The default
 is a read-only preview; `--yes` applies, and `--check` is suitable for drift
-checks. Setup also checks `whoami` and prints `nodii-dev login` guidance without
-exposing credential details.
+checks. Setup also checks the OAuth login (a token refresh, then the registered
+agent) and prints `nodii-dev login` guidance without exposing credential
+details.
 
-Heartbeat notes are optional and limited by the hub to 500 characters.
+Heartbeat notes are optional and limited by Dev to 500 characters.
 Prioritize and deprioritize require a 1–500 character reason, which the CLI
-sends to the hub. `lane review` records the review gate.
+sends to Dev. `lane review` records the review gate.
 
 The CLI does not duplicate authorization policy. It sends requests and prints
-the hub's refusal unchanged. Stop, Built acknowledgement, and machine
+Dev's refusal unchanged. Stop, Built acknowledgement, and machine
 create/update/coordinator changes require a staff person login. Machine agent
 assignment is for coordinators; lane-limit and repository-grant changes are for
 the target agent's coordinator or staff. Agent registration does not accept
@@ -177,19 +261,23 @@ nodii-dev requests resolve UUID --commit-sha abc1234 --resolution-md "shipped"
 nodii-dev open-questions answer UUID --decision-id D1420
 ```
 
-The first-class resource families cover every live OpenAPI tag: services,
+The CLI bundles Dev's OpenAPI document as the edge routes it (the edge does not
+serve Dev's own document), so `api list` works offline and lists only
+operations the edge exposes. The first-class resource families cover every tag: services,
 feature docs, contracts (gRPC, REST, outbox, sagas, tables), libraries,
 workers, projects, slices, SQL lookups, issues, backlogs, builds, changes,
-deploy reports, runtime, people, agents, inbox/gates, design, runbooks,
+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
 non-Figma tools and allowlisted Figma reads, but defaults to denying every
-Figma write if the file key is absent, the hub cannot be reached, or the lock
+Figma write if the file key is absent, Dev cannot be reached, or the lock
 is denied. It exits `2`, which makes Claude Code block the call. The post-hook
 best-effort logs the write and never blocks. Per D1433, Codex remains read-only
 for Figma; this package does not write to Figma itself.

package/dist/api.js

@@ -1,13 +1,14 @@
 import { readFile } from "node:fs/promises";
 import { stdin } from "node:process";
-import { CliError, encode, hubRawRequest, readConfig } from "./core.js";
+import { CliError, devRawRequest, encode } from "./core.js";
 
 const methods = new Set(["get", "post", "put", "patch", "delete", "head", "options"]);
-export async function loadOpenApi(fetcher = fetch) {
-  const { hubUrl } = await readConfig();
-  const response = await fetcher(`${hubUrl.replace(/\/$/, "")}/openapi.json`, { headers: { accept: "application/json" } });
-  if (!response.ok) throw new CliError("OPENAPI_UNAVAILABLE", `Cannot load OpenAPI: HTTP ${response.status}`);
-  return response.json();
+// The Dev API as the platform edge routes it, bundled with the package (the
+// edge does not serve Dev's own document). Refresh: `npm run openapi:snapshot`.
+let bundled;
+export async function loadOpenApi() {
+  bundled ??= JSON.parse(await readFile(new URL("./devops-openapi.json", import.meta.url), "utf8"));
+  return bundled;
 }
 
 export function operationsFrom(spec) {
@@ -86,20 +87,22 @@ export function flagsToOperation(entry, positional, flags) {
 
 export async function callOperation(entry, params, body) {
   const request = buildOperationRequest(entry, params, body);
-  return hubRawRequest(request.method, request.path, body === undefined ? undefined : JSON.stringify(body));
+  return devRawRequest(request.method, request.path, body === undefined ? undefined : JSON.stringify(body));
 }
 
 export const GROUPS = {
   services: "Services", "feature-docs": "FeatureDocs", contracts: ["GrpcInterfaces", "RestInterfaces", "Outbox", "OutboxTopics", "Sagas", "Tables"],
   sagas: "Sagas", "outbox-topics": ["Outbox", "OutboxTopics"], tables: "Tables", libraries: "Libraries", workers: "Workers",
-  projects: "Projects", issues: "Issues", backlog: "Backlogs", backlogs: "Backlogs", builds: "Delivery", changes: "Delivery", "deploy-reports": "Runtime",
+  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",
+  rulebook: "ad-documents", "ad-decisions": "ad-decisions", domains: "ad-domains", standardizations: "standardizations",
+  archive: "archive", harness: "harness",
 };
 
 export const ALIASES = {
@@ -123,12 +126,12 @@ export const ALIASES = {
   "projects:list": "listServiceProjects", "projects:show": "getProject", "projects:create": "createProject", "projects:update": "updateProject",
   "builds:list": "listBuilds", "builds:show": "getBuild", "builds:report": "reportBuild",
   "changes:list": "listChanges", "changes:show": "getChange", "changes:mark": "markChange",
-  "deploy-reports:report": "reportDeployment", "runtime:list": "listRuntimeInventory", "runtime:show": "getServiceRuntime",
+  "runtime:list": "listRuntimeInventory", "runtime:show": "getServiceRuntime",
   "people:list": "listPeople", "people:show": "getPerson", "agents:list": "listAgents", "agents:show": "getAgent",
   "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",
@@ -142,6 +145,12 @@ 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",
 };