nawabari 0.11.0 → 0.13.0

package/README.md

@@ -1,3 +1,14 @@
+<p align="center">
+  <img src="./docs/assets/readme/nawabari-hero.webp" alt="Nawabari — Git Worktree Isolation." width="100%">
+</p>
+
+<p align="center">
+  <a href="https://github.com/yohn-jp/nawabari/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/yohn-jp/nawabari/actions/workflows/ci.yml/badge.svg"></a>
+  <a href="https://www.npmjs.com/package/nawabari"><img alt="npm" src="https://img.shields.io/npm/v/nawabari"></a>
+  <a href="https://www.npmjs.com/package/nawabari"><img alt="Node" src="https://img.shields.io/node/v/nawabari"></a>
+  <a href="./LICENSE"><img alt="License" src="https://img.shields.io/npm/l/nawabari"></a>
+</p>
+
 # Nawabari
 
 Nawabari is a local governance layer for parallel coding agents. It gives each agent session an owned Git worktree and branch, records which repository resources that session may use, and checks those boundaries before governed mutations.
@@ -69,6 +80,77 @@ worktree=$(printf '%s' "$created" | jq -r .worktree)
 
 The initial-claim grammar is `--resource <path-or-glob> --mode <read|write|exclusive-write>` and the pair may be repeated. Each resource is paired with its own mode. The parser also permits zero pairs for backward compatibility, but the canonical routine path declares at least one initial claim. Initial claims are committed atomically with the new session, worktree, and branch. A conflict returns a machine-readable failure such as `RESOURCE_CLAIM_CONFLICT` and does not leave a partially established session or claim set.
 
+Resource-claim enforcement is disabled by default for a new session: `commit`/`push` authorization does not require the session to hold a resource claim for its own session-owned operations. Pass `--enforce-claims` to `session create` to opt that session into the previous claim-authorization behavior, including `MISSING_RESOURCE_CLAIM`/`INSUFFICIENT_CLAIM_MODE` denials and existing claim-mode compatibility rules. Worktree ownership, branch ownership, and `RESOURCE_CLAIM_CONFLICT` protection against another session's active claim remain enforced either way.
+
+### Working-set artifacts
+
+For a bounded session, supply **both** `--execution-scope-file` and `--candidate-working-set-file` to `session create`. The JSON below illustrates the versioned fields accepted by the [canonical parsers](./src/working-set.ts). Replace the identity, revision, digest, and paths with values from the implementation authorization and the repository being bootstrapped. `repositoryHost` and `repositoryId` must agree between the two artifacts and the authorization; `repository` is optional in the execution scope and required in the candidate. The candidate `revision` and execution-scope `base.revision` must equal the session's resolved Git base revision (40 or 64 hexadecimal characters). `base.branch` names that base; `base.freshness` and the top-level execution-scope `branch` are optional bounded strings.
+
+`execution-scope.json`:
+
+```json
+{
+  "version": 1,
+  "kind": "implementation-execution-scope",
+  "authorization": {
+    "version": 1,
+    "kind": "implementation-authorization",
+    "contractVersion": 1,
+    "implementation": {
+      "repositoryHost": "github.com",
+      "repositoryId": "1329799765",
+      "repository": "yohn-jp/nawabari",
+      "number": 659
+    },
+    "governedBodyDigest": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
+  },
+  "repository": { "repositoryHost": "github.com", "repositoryId": "1329799765", "repository": "yohn-jp/nawabari" },
+  "base": { "branch": "main", "revision": "e0e3c4376c9d70c87f24c7211b5ded1f3d58a983" },
+  "scope": {
+    "readOnly": ["README.md", "src/**"],
+    "write": [],
+    "create": [],
+    "delete": [],
+    "deny": []
+  }
+}
+```
+
+`candidate-working-set.json`:
+
+```json
+{
+  "kind": "candidate-working-set",
+  "schemaVersion": 1,
+  "workingSetId": "implementation-659-candidate-v1",
+  "repository": { "repositoryHost": "github.com", "repositoryId": "1329799765", "repository": "yohn-jp/nawabari" },
+  "revision": "e0e3c4376c9d70c87f24c7211b5ded1f3d58a983",
+  "entries": [
+    {
+      "state": "required",
+      "target": { "kind": "file", "locator": "README.md" },
+      "reason": { "id": "implementation-659", "summary": "Read the public contract" },
+      "evidence": [{ "artifact": "implementation-659", "reference": "working-set-bootstrap" }]
+    }
+  ]
+}
+```
+
+The execution scope is the maximum authority: all five arrays (`readOnly`, `write`, `create`, `delete`, `deny`) are required, contain canonical repository-relative path selectors, and may be empty. The authorization's `implementation.number` is a positive integer and `governedBodyDigest` is a 64-character lowercase hexadecimal digest from the governing authorization. `implementation.repository` is optional. Candidate `entries` may be empty; each entry requires `state` (`required`, `supporting`, `verification`, or `unresolved`), `target` (`kind`: `file`, `symbol`, `test`, or `unresolved`; plus a nonempty `locator`), `reason` (`id` and `summary`), and an `evidence` array of `{ "artifact", "reference" }` objects. An `unresolved` state requires an `unresolved` target kind; concrete states require a concrete target kind. Candidate entries describe need, not permission. Unknown fields are rejected; the parser in `src/working-set.ts` is the contract authority.
+
+```bash
+nawabari session create --base main --execution-scope-file execution-scope.json \
+  --candidate-working-set-file candidate-working-set.json --json
+nawabari session show --session "$session_id" --json
+nawabari session scope expand --help --json
+nawabari session scope expand --session "$session_id" --repository 1329799765 \
+  --repository-host github.com --revision "$revision" \
+  --execution-scope-file execution-scope.json --path src/new-context.ts \
+  --operation READONLY --reason 'Needed for current task' --json
+```
+
+Read `working_set.revision` from `session show --json` before expansion. A granted expansion advances that revision and appends `working_set.history`; a stale revision or different execution-scope provenance is rejected without changing the working set. The requested path must be within the original execution-scope maximum and outside its `deny` selectors. READONLY expansion grants no WRITE, CREATE, or DELETE authority. Mutation still follows the existing claim and scope checks. If a resource handoff reports `Destination maximum scope is unavailable`, inspect the destination and explicitly expand its scope first; retry `session handoff` with fresh claim-set generation through the normal handoff command. Handoff never expands destination scope itself.
+
 The packed auxiliary-state declaration above is the bounded `copy` form: a `repository-local` source is copied to a `managed-worktree` target with `durability: durable`. It is an explicit, repeatable, allowlisted capability. It does not discover ignored state, project process-local sockets/PID files/logs, shadow Git-tracked paths, or expose arbitrary host filesystem paths. Auxiliary-state projection is separate from `SessionRuntimeProjection`: the former copies declared repository-local durable state for a managed worktree; the latter describes explicit runtime material and filesystem visibility for protected execution. Auxiliary state does not change the runtime projection.
 
 The create operation is atomic, but a caller must treat an uncertain result carefully. If JSON reports `REGISTRY_DURABILITY_UNCERTAIN`, re-read the reported session and claims before retrying. If the exact original declaration is already present, follow `bootstrap_retry.next_action: inspect-established-session` and inspect that `session_id`; if another declaration owns the worktree or branch, follow `bootstrap_retry.next_action: inspect-blocking-session`. Nawabari never silently adopts an existing owner. A retry is appropriate only after the authoritative state proves that the requested bootstrap was not established.
@@ -247,6 +329,22 @@ JSON mode emits one bounded document on stdout. Consumers should use machine-rea
 
 The command surface includes Session lifecycle, Resource Claims, authorization/evidence, governed Git commit/push, reconciliation/discovery, and protected execution. Use `--help --json` and `capabilities --json` for the authoritative inventory. Human-readable guidance and agent integrations use these same command and action identifiers; there is no separate human or agent workflow.
 
+`src/cli-command-registry.ts` is the single canonical authority for that surface: every command/option name is a `CommandId`/`OptionId` literal type derived directly from the registry data (not hand-typed), and `--help`, `capabilities`, and the executable dispatcher's own accepted-flag parsing all read that same data. There is no second command or option table to keep in sync.
+
+### Optional machine-local Control Server
+
+```bash
+nawabari server [--port <port>]
+```
+
+`nawabari server` runs one foreground Control Server and built-in Web UI at `http://127.0.0.1:47471/` (default port `47471`; `--port` selects another; an occupied port fails instead of choosing another endpoint). The listener binds IPv4 loopback `127.0.0.1` only and the bind address is not configurable. Stop it with Ctrl-C or `SIGTERM`.
+
+One listener serves every locally known Nawabari repository. Repository discovery uses a machine-local locator catalog (`$XDG_STATE_HOME/nawabari/control-repositories.json`, default `~/.local/state/nawabari/`) that holds only repository identity (common Git directory) and worktree path; `session create` and `server` record the current repository when it already has a Nawabari registry. The catalog is discovery metadata, not authority: each request reopens that repository's own backend, and each repository's registry, lifecycle, claims, runtime and filesystem authority stay independent.
+
+The HTTP v1 API is `GET /api/v1/health`, `GET /api/v1/repositories`, `GET /api/v1/repositories/:repositoryKey/snapshot`, `GET /api/v1/repositories/:repositoryKey/sessions/:sessionId`, and `POST /api/v1/repositories/:repositoryKey/sessions/:sessionId/actions`. Reads re-project the canonical `RepositoryRuntimeSnapshot`; actions accept only the typed `session action` contract (`action_id`, `token`, `confirmation`) and delegate to the repository's `SessionActionDispatcher`, so stale evidence fails closed (HTTP 409) and `discard-session` still needs the authoritative preview plus explicit confirmation. No route executes command text.
+
+Every API request needs the `x-nawabari-control-token` header. The token is random per start, bootstrapped only into the same-origin root document, and never printed, logged, persisted, or put in URLs. Requests with an unexpected `Host` or a foreign `Origin` are rejected, no CORS headers are sent, and actions accept bounded `application/json` bodies only. The Web UI polls every 3 seconds and has a manual refresh; it offers only the actions listed by the current canonical diagnostic. The server is optional: every other command, including `nawabari ui`, keeps calling the backend directly.
+
 ## Stable package exports
 
 Node consumers can use public projections without spawning the CLI: