@sechroom/cli 2026.6.1-rc.0f873d7f

package/README.md

@@ -0,0 +1,271 @@
+# sechroom-cli (Route 1 skeleton)
+
+A thin **npm-distributed** CLI over the Sechroom HTTP API. A deliberate
+alternative agent/human surface to MCP — and because the agentic coding tools
+(Claude Code, Codex, Cursor) drive CLIs by reading `--help` and parsing stdout,
+every command emits clean JSON via `--json`.
+
+## Why this shape (grounded in the backend, verified against source)
+
+- **One contract.** OpenAPI is served at `/openapi/v1.json` (`Program.cs`:
+  `AddOpenApi()` + `MapOpenApi()`) — the same doc the UI's
+  `frontend/packages/api-client` and Bruno consume. The CLI generates its
+  client from it; there is no hand-maintained request/response surface.
+- **The API is the real surface.** Every MCP tool is a thin shim over a
+  Wolverine handler that is *also* a `[WolverinePost]`/`[WolverineGet]` endpoint
+  carrying the same `[TenantPermission]`. The permission middleware is HTTP-only,
+  so the CLI inherits identical enforcement.
+- **Tenant is mandatory.** `MapWolverineEndpoints` calls `TenantId.AssertExists()`
+  — a missing `tenant` header is a hard 400. The client sets it on every request.
+- **Auth matches the AS.** `OAuthEndpointMappings.cs` exposes auth-code + PKCE
+  (`/oauth/authorize` -> `/oauth/token`), RFC 8414 discovery, and RFC 7591
+  dynamic client registration (`/oauth/register`). No device-code or
+  client-credentials grant — so the CLI uses the loopback auth-code + PKCE
+  pattern and self-registers via DCR, mirroring how Claude.ai web connects.
+  Headless/CI sets `SECHROOM_TOKEN`.
+
+### Verified specifics that shaped the code
+
+- **DCR `client_id` is deterministic** (`RegisterClientEndpoint.cs`):
+  `dyn-` + base64url(SHA256(sorted `redirect_uris`))[:22], idempotent on the
+  redirect set. PKCE-only, no secret. The CLI therefore registers a **fixed set
+  of candidate loopback ports** as the redirect_uris (stable set -> stable id)
+  and binds whichever is free — so re-login never mints a new client or stales
+  the cache.
+- **PKCE is S256-only** (`TokenEndpoint.VerifyPkce`).
+- **Refresh works** (`TokenEndpoint`): `grant_type=refresh_token` is a real
+  grant, and the token body returns a `refresh_token` for non-browser clients.
+  `requireToken()` refreshes automatically near expiry.
+- **`POST /memories`** binds `CreateMemoryInput` — `Content` and `Confidence`
+  are required (MCP shim defaults `"{}"` / `1.0`); `Owner` is nullable (omit for
+  Unfiled). The `create` command applies those defaults.
+- **`GET /memories/{memoryId}`** returns an `OperationsItem<MemoryReadModel>` envelope.
+- **`POST /memories/search`** (`SearchMemoriesEndpoint`) — `SemanticQuery`
+  routes to the hybrid vector+FTS RRF ranker; the `search` command uses it.
+
+## Install
+
+```bash
+# pre-GA / internal builds are published under the `next` dist-tag
+npx @sechroom/cli@next login
+npm i -g @sechroom/cli@next
+
+# once GA (promoted to `latest`)
+npx @sechroom/cli login
+```
+
+## Develop
+
+This is a **pnpm workspace member** (`frontend/apps/cli`). Install from the repo root
+(`pnpm install`), then run scripts via the filter (or `pnpm <script>` from this dir):
+
+```bash
+pnpm --filter @sechroom/cli run gen          # regenerate the typed client
+pnpm --filter @sechroom/cli run check-types
+pnpm --filter @sechroom/cli run build
+pnpm --filter @sechroom/cli run dev -- --help # tsx, no build
+```
+
+## Generate the client (once, and after any API change)
+
+```bash
+# defaults to https://app.sechroom.ai/api/openapi/v1.json
+pnpm --filter @sechroom/cli run gen
+SECHROOM_OPENAPI_URL=https://<host>/api/openapi/v1.json pnpm --filter @sechroom/cli run gen   # other envs
+```
+
+`gen` overwrites `src/generated/api.d.ts`. The **real generated types are
+committed** (regenerated from the live prod spec) so builds are hermetic — no
+live-API dependency at compile time; re-run `gen` after any API change. Generating
+against the live schema is what caught the original placeholder's shape drift
+(e.g. the work-log append body is `{bullet, laneId, workspaceId, title}`, and
+`CreateMemoryInput`/`SearchInput` require several nullable fields present), now
+fixed in the command bodies.
+
+## Use
+
+```bash
+sechroom config set baseUrl https://app.sechroom.ai/api      # prod (staging: https://staging.app.sechroom.ai/api)
+sechroom config set tenant  ocd
+sechroom login
+
+sechroom memory create --text "first note from the CLI" --type reference
+sechroom memory get mem_XXXX
+sechroom memory search "convention lifecycle drift" --limit 5
+sechroom worklog append --text "shipped CLI skeleton; pointers: ..." --source claude-code-chris
+
+sechroom lookup mem_XXXX                 # what is this id? -> kind / title / view URL
+sechroom lookup sechroom:mem_XXXX --json # namespaced form also resolves
+
+sechroom --json memory get mem_XXXX     # agent-friendly
+```
+
+**Output shape.** Mutating commands (`memory create`, `worklog append`) print a concise confirmation line — id + view URL — the way the MCP tools hand an LLM a result, instead of dumping the raw envelope. Pass `--json` for the full response body (the machine channel) on any command. Output is lightly colorized on a TTY and auto-plain when piped, under `--json`, or when `NO_COLOR` is set.
+
+```bash
+sechroom memory create --text "a note" --title "Note"
+# ✓ created memory mem_XXXX "Note" → https://sechroom.yi.ocd.codes/view/mem_XXXX
+```
+
+**Per-directory config.** A project dir can pin its own `tenant` + `baseUrl` in a local `.sechroom.json`, discovered by walking **up** from cwd (nearest wins, so any subdir inherits it). It overrides the global config — precedence: `--flag` > env > directory-local > global > default. `clientId` / auth state stays global.
+
+```bash
+sechroom config set --local tenant  cli-smoke                       # this dir + subdirs
+sechroom config set --local baseUrl https://staging.app.sechroom.ai/api
+sechroom config show                                                # resolved values + which source won
+```
+
+**Smoke testing.** There is a dedicated **`cli-smoke`** tenant on **both staging and prod** for exercising the CLI without touching real tenants — point at staging and use it:
+
+```bash
+sechroom config set --local baseUrl https://staging.app.sechroom.ai/api
+sechroom config set --local tenant  cli-smoke
+sechroom login
+sechroom worklog append --text "cli smoke" --source claude-code-chris
+```
+
+Headless:
+
+```bash
+export SECHROOM_TOKEN="<bearer: a PAT or dev-token JWT>"
+export SECHROOM_TENANT=ocd
+sechroom --json memory search "rate limiting" 
+```
+
+## Command surface (MCP parity)
+
+The CLI mirrors the sechroom MCP tool surface — every command is a thin wrapper over the same HTTP endpoint the matching MCP tool shims, so enforcement (`[TenantPermission]`) is identical. Run `sechroom <group> --help` for the subcommands + examples.
+
+| Group | Covers |
+|---|---|
+| `memory` | create / get / search · edit-text(+batch) · archive / restore / move · versions / revert · list-archived · owners / tags / types · sum-tokens · similar · by-url |
+| `relationship` | create / list / delete · suggest · `suggestion` get / accept / reject / defer |
+| `workspace` | create / list / get · rename / describe / move · archive / restore · feed |
+| `project` | create / list / get · rename / describe / move · status · victory-conditions · archive / restore |
+| `filing` | suggestions / get · preview · accept / reject / defer / edit-and-accept |
+| `continuity` | snapshot-create / -get · snapshots · resume-me / resume-lane · changed-since · load-set · grant / revoke-grant |
+| `id` | next / peek (FR-_/D-_ sequence allocation) |
+| `account` | profile / set-profile · feed · reviews / review-get / review-accept · lookup-batch |
+| `chat` | send · messages · replies · stop-tracking (Slack / Discord, via `--surface`) |
+| `worklog` · `lookup` | append · resolve any id |
+
+Notes on deliberate gaps (API-rooted, not CLI):
+- **No `memory delete`** — the API exposes no hard DELETE; `memory archive` is the soft-delete path.
+- **`memory revert`** needs `--text` + `--content` — the revert endpoint doesn't reconstruct a version's body from its number; pull them from `memory versions` / `memory get` first.
+
+## Onboarding (`init` / `setup`)
+
+`sechroom init` wires a project for sechroom by rendering the server's
+operator-surface setup descriptors (`GET /operator-surface/setup`, tenant-scoped
+— the aggregator URL is baked in) into local AI-client config + agent instruction
+files. **Idempotent — merges/appends, never clobbers** (JSON `mcpServers` merge;
+Codex TOML table replace; instruction files use a managed marker block).
+
+```bash
+sechroom init                       # Claude Code (default): .mcp.json + CLAUDE.md
+sechroom init --client all          # claude-code, claude-desktop, codex, cursor
+sechroom init --client codex,cursor # a subset
+sechroom init --mcp-only            # just the MCP config (skip agent files)
+sechroom init --dry-run --json      # preview the writes, no changes
+
+# granular pieces init orchestrates:
+sechroom setup mcp claude-desktop          # just the MCP config for one client
+sechroom setup agent-files codex           # just the AGENTS.md instruction file
+```
+
+### `sechroom onboard` — guided first run
+
+`onboard` orchestrates the whole zero-to-wired path interactively: configure base
+URL + tenant, sign in, set the profile timezone, then wire your AI client(s). Two
+prompts make it fit how you actually work:
+
+- **Where to save config** — globally (`~/.config/sechroom`, all projects) or a
+  directory-local `.sechroom.json` (this project + subdirs). Defaults to local
+  when a `.sechroom.json` already governs the dir.
+- **How far to wire** — full (MCP server + agent instructions), agent
+  instructions only (skip `.mcp.json`), or **CLI only** (write nothing for AI
+  clients — for when you just want the `sechroom` command).
+
+```bash
+sechroom onboard                    # interactive: asks where to save + how to wire
+sechroom onboard --cli-only         # just the CLI — no .mcp.json, no agent files
+sechroom onboard --no-mcp           # agent instructions only, skip MCP config
+sechroom onboard --local            # save tenant + base URL to ./.sechroom.json
+sechroom onboard --yes              # non-interactive: defaults + global config + full wire
+```
+
+Per client → where it writes:
+
+| client | MCP config | instruction file |
+|---|---|---|
+| `claude-code` | `./.mcp.json` | `./CLAUDE.md` |
+| `claude-desktop` | `claude_desktop_config.json` (OS path) | `~/.claude/CLAUDE.md` |
+| `codex` | `~/.codex/config.toml` | `./AGENTS.md` |
+| `cursor` | `./.cursor/mcp.json` | `./AGENTS.md` |
+
+The instruction-file step pulls the role template the SEM Starter bundle ships
+(via the descriptor's tag-query artifact). If that bundle isn't installed in the
+tenant, the step **skips gracefully** with a note (MCP config still gets written).
+
+## Layout
+
+```
+src/
+  index.ts            commander root + global flags + login/config
+  auth.ts             OAuth auth-code+PKCE loopback (fixed-port DCR) + refresh + cache
+  client.ts           openapi-fetch client (auth + tenant middleware) + emit/fail
+  config.ts           base-url / tenant / token resolution + persistence
+  generated/api.d.ts  typed client — `pnpm run gen`; real types committed (hermetic)
+  commands/
+    memory.ts         create / get / search / edit / archive / move / versions / …
+    relationships.ts  relationships + relationship-suggestions
+    workspace.ts      workspace CRUD + feed
+    project.ts        project CRUD + status / victory-conditions
+    filing.ts         filing-suggestion review (accept / reject / defer / edit-and-accept)
+    continuity.ts     snapshots + resume / grant
+    account.ts        id next/peek + profile / feed / reviews / lookup-batch
+    chat.ts           read Slack / Discord messages + replies
+    worklog.ts        append
+    lookup.ts         resolve any id (mem_…/unprefixed/sechroom:<id>) -> kind/title/url
+    setup.ts          init + setup mcp/agent-files
+  setup/
+    operator-surface.ts  fetch GET /operator-surface/setup + resolve template artifacts
+    clients.ts           client→(surface, local paths, format) registry
+    apply.ts             writers: mcp json merge / codex toml / instruction marker block
+```
+
+## Remaining before ship
+
+- **Provision the npm publish credential** (the only blocker): create the
+  `@sechroom` npmjs org + an Automation token and paste it into the
+  `Sechroom_PublishCli` build config's `NPM_TOKEN` param. See
+  [`ci/PUBLISHING.md`](./ci/PUBLISHING.md).
+- Decide the registered candidate-port set (`CANDIDATE_PORTS` in `auth.ts`) —
+  three localhost ports today; keep them stable, since the DCR client id is a
+  function of that set.
+
+## Distribution (initial)
+
+Public **npmjs** under the `@sechroom` org is the host; **TeamCity** is the
+publisher (build config `Sechroom_PublishCli`). The full pipeline — steps,
+parameters, npm auth, provisioning, and how to run a publish — is documented in
+[`ci/PUBLISHING.md`](./ci/PUBLISHING.md). In short: a manual-trigger config runs
+`pnpm install → gen → check-types → build → publish` (filtered to `@sechroom/cli`)
+in a `node:20` container, authed by a masked `NPM_TOKEN` param. Every publish gets a
+fresh calendar version `YYYY.M.<n>` (own counter); the dist-tag separates next/latest.
+
+Why public npmjs: the CLI is customer-facing, and `npx @sechroom/cli` must work
+with zero `.npmrc`/token on the customer side. GitHub Packages or a private
+registry would force every external adopter to authenticate just to install.
+
+Pure Node — no runtime prerequisite beyond Node 20. If a zero-dependency single
+binary is later preferred, the alternative is per-platform AOT binaries published
+as npm `optionalDependencies` behind a launcher shim (the esbuild/biome pattern),
+at the cost of an OS×arch build matrix. This (plain Node) keeps install friction
+lowest.
+
+## Onboarding hook
+
+Parallels `BuildMcpConfigSection` in `OperatorSurfaceDescriptors`: a
+`BuildCliConfigSection` can emit the `npx @sechroom/cli` invocation + the
+`config set` bootstrap the same way the MCP config is surfaced today.