@sechroom/cli 2026.6.1

package/README.md

@@ -0,0 +1,144 @@
+# 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
+```
+
+## Generate the client (once, and after any API change)
+
+```bash
+# defaults to https://app.sechroom.ai/api/openapi/v1.json
+npm run gen
+SECHROOM_OPENAPI_URL=https://<host>/api/openapi/v1.json npm run gen   # other envs
+```
+
+`npm run 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 --json memory get mem_XXXX     # agent-friendly
+```
+
+Headless:
+
+```bash
+export SECHROOM_TOKEN="<jwt from /auth/dev/token>"
+export SECHROOM_TENANT=ocd
+sechroom --json memory search "rate limiting" 
+```
+
+## 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 — `npm run gen`; real types committed (hermetic)
+  commands/
+    memory.ts         create / get / search
+    worklog.ts        append
+```
+
+## 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
+`npm ci → gen → typecheck → build → publish` in a `node:20` container, authed by
+a masked `NPM_TOKEN` param; `next` stamps a per-build prerelease, `latest` ships
+`BASE_CLI_VERSION`.
+
+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.

package/dist/index.js

@@ -0,0 +1,341 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { Command } from "commander";
+
+// src/auth.ts
+import { createServer } from "http";
+import { randomBytes, createHash } from "crypto";
+import open from "open";
+
+// src/config.ts
+import { homedir } from "os";
+import { join } from "path";
+import { mkdirSync, readFileSync, writeFileSync, existsSync } from "fs";
+var CONFIG_DIR = join(homedir(), ".config", "sechroom");
+var CONFIG_FILE = join(CONFIG_DIR, "config.json");
+var TOKEN_FILE = join(CONFIG_DIR, "token.json");
+var DEFAULT_BASE_URL = "https://app.sechroom.ai/api";
+function ensureDir() {
+  if (!existsSync(CONFIG_DIR)) mkdirSync(CONFIG_DIR, { recursive: true, mode: 448 });
+}
+function readPersisted() {
+  try {
+    return JSON.parse(readFileSync(CONFIG_FILE, "utf8"));
+  } catch {
+    return {};
+  }
+}
+function writePersisted(patch) {
+  ensureDir();
+  const next = { ...readPersisted(), ...patch };
+  writeFileSync(CONFIG_FILE, JSON.stringify(next, null, 2), { mode: 384 });
+}
+function readToken() {
+  const envTok = process.env.SECHROOM_TOKEN;
+  if (envTok) return { accessToken: envTok };
+  try {
+    return JSON.parse(readFileSync(TOKEN_FILE, "utf8"));
+  } catch {
+    return null;
+  }
+}
+function writeToken(tok) {
+  ensureDir();
+  writeFileSync(TOKEN_FILE, JSON.stringify(tok, null, 2), { mode: 384 });
+}
+function resolveConfig(flags) {
+  const persisted = readPersisted();
+  const baseUrl = flags.baseUrl ?? process.env.SECHROOM_BASE_URL ?? persisted.baseUrl ?? DEFAULT_BASE_URL;
+  const tenant = flags.tenant ?? process.env.SECHROOM_TENANT ?? persisted.tenant ?? "";
+  if (!tenant) {
+    throw new Error(
+      "No tenant set. The Sechroom API rejects untenanted requests (HTTP 400). Pass --tenant <id>, set SECHROOM_TENANT, or run `sechroom config set tenant <id>`."
+    );
+  }
+  return { baseUrl: baseUrl.replace(/\/$/, ""), tenant, clientId: persisted.clientId };
+}
+
+// src/auth.ts
+var SCOPES = "openid email profile";
+var CANDIDATE_PORTS = [51787, 51788, 51789];
+var REDIRECT_PATH = "/callback";
+function b64url(buf) {
+  return buf.toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+function redirectUriFor(port) {
+  return `http://127.0.0.1:${port}${REDIRECT_PATH}`;
+}
+async function discover(baseUrl) {
+  const res = await fetch(`${baseUrl}/.well-known/oauth-authorization-server`);
+  if (!res.ok) throw new Error(`AS discovery failed (${res.status}) at ${baseUrl}`);
+  return await res.json();
+}
+async function ensureClientId(meta) {
+  const cached = readPersisted().clientId;
+  if (cached) return cached;
+  if (!meta.registration_endpoint) {
+    throw new Error(
+      "Server advertises no registration_endpoint and no client_id is cached. Pre-register a client and run `sechroom config set clientId <id>`."
+    );
+  }
+  const res = await fetch(meta.registration_endpoint, {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify({
+      client_name: "sechroom-cli",
+      redirect_uris: CANDIDATE_PORTS.map(redirectUriFor)
+    })
+  });
+  if (!res.ok) throw new Error(`Dynamic client registration failed (${res.status}): ${await res.text()}`);
+  const reg = await res.json();
+  writePersisted({ clientId: reg.client_id });
+  return reg.client_id;
+}
+function startLoopback(state) {
+  return new Promise((resolveOuter, rejectOuter) => {
+    const tryPort = (i) => {
+      if (i >= CANDIDATE_PORTS.length) {
+        rejectOuter(new Error(`All loopback ports busy (${CANDIDATE_PORTS.join(", ")}). Close the conflicting process and retry.`));
+        return;
+      }
+      const port = CANDIDATE_PORTS[i];
+      let resolveCode;
+      let rejectCode;
+      const code = new Promise((res, rej) => {
+        resolveCode = res;
+        rejectCode = rej;
+      });
+      const server = createServer((req, res) => {
+        const url = new URL(req.url ?? "/", "http://127.0.0.1");
+        if (!url.pathname.startsWith(REDIRECT_PATH)) {
+          res.writeHead(404).end();
+          return;
+        }
+        const got = url.searchParams.get("code");
+        const gotState = url.searchParams.get("state");
+        const err = url.searchParams.get("error");
+        res.writeHead(err ? 400 : 200, { "content-type": "text/html" });
+        res.end(
+          err ? `<h3>Authorization failed: ${err}</h3>` : "<h3>Signed in to Sechroom.</h3><p>Return to the terminal.</p>"
+        );
+        server.close();
+        if (err) return rejectCode(new Error(`Authorization error: ${err}`));
+        if (!got) return rejectCode(new Error("No code in callback."));
+        if (gotState !== state) return rejectCode(new Error("State mismatch \u2014 possible CSRF."));
+        resolveCode(got);
+      });
+      server.on("error", (e) => {
+        if (e.code === "EADDRINUSE") tryPort(i + 1);
+        else rejectOuter(e);
+      });
+      server.listen(port, "127.0.0.1", () => {
+        resolveOuter({ port, redirectUri: redirectUriFor(port), code });
+      });
+    };
+    tryPort(0);
+  });
+}
+async function exchange(meta, clientId, code, verifier, redirectUri) {
+  const res = await fetch(meta.token_endpoint, {
+    method: "POST",
+    headers: { "content-type": "application/x-www-form-urlencoded" },
+    body: new URLSearchParams({
+      grant_type: "authorization_code",
+      code,
+      redirect_uri: redirectUri,
+      client_id: clientId,
+      code_verifier: verifier
+    })
+  });
+  if (!res.ok) throw new Error(`Token exchange failed (${res.status}): ${await res.text()}`);
+  persistTokenResponse(await res.json());
+}
+function persistTokenResponse(json) {
+  const tok = json;
+  writeToken({
+    accessToken: tok.access_token,
+    refreshToken: tok.refresh_token,
+    expiresAt: tok.expires_in ? Date.now() + tok.expires_in * 1e3 : void 0
+  });
+}
+async function login(cfg) {
+  const meta = await discover(cfg.baseUrl);
+  const clientId = await ensureClientId(meta);
+  const state = b64url(randomBytes(16));
+  const verifier = b64url(randomBytes(32));
+  const challenge = b64url(createHash("sha256").update(verifier).digest());
+  const loopback = await startLoopback(state);
+  const authUrl = new URL(meta.authorization_endpoint);
+  authUrl.searchParams.set("response_type", "code");
+  authUrl.searchParams.set("client_id", clientId);
+  authUrl.searchParams.set("redirect_uri", loopback.redirectUri);
+  authUrl.searchParams.set("scope", SCOPES);
+  authUrl.searchParams.set("state", state);
+  authUrl.searchParams.set("code_challenge", challenge);
+  authUrl.searchParams.set("code_challenge_method", "S256");
+  process.stderr.write(`Opening browser for sign-in...
+If it does not open, visit:
+${authUrl}
+`);
+  await open(authUrl.toString());
+  const code = await loopback.code;
+  await exchange(meta, clientId, code, verifier, loopback.redirectUri);
+  process.stderr.write("Signed in. Token cached.\n");
+}
+async function requireToken(cfg) {
+  if (process.env.SECHROOM_TOKEN) return process.env.SECHROOM_TOKEN;
+  const cached = readToken();
+  if (!cached?.accessToken) {
+    throw new Error("Not signed in. Run `sechroom login` (or set SECHROOM_TOKEN for headless use).");
+  }
+  const nearExpiry = cached.expiresAt !== void 0 && Date.now() > cached.expiresAt - 6e4;
+  if (nearExpiry && cached.refreshToken) {
+    const meta = await discover(cfg.baseUrl);
+    const res = await fetch(meta.token_endpoint, {
+      method: "POST",
+      headers: { "content-type": "application/x-www-form-urlencoded" },
+      body: new URLSearchParams({
+        grant_type: "refresh_token",
+        refresh_token: cached.refreshToken
+      })
+    });
+    if (res.ok) {
+      persistTokenResponse(await res.json());
+      return readToken().accessToken;
+    }
+    throw new Error("Session expired and refresh failed. Run `sechroom login` again.");
+  }
+  return cached.accessToken;
+}
+
+// src/client.ts
+import createClient from "openapi-fetch";
+async function makeClient(cfg) {
+  const token = await requireToken(cfg);
+  const client = createClient({ baseUrl: cfg.baseUrl });
+  client.use({
+    onRequest({ request }) {
+      request.headers.set("authorization", `Bearer ${token}`);
+      request.headers.set("tenant", cfg.tenant);
+      return request;
+    }
+  });
+  return client;
+}
+function emit(data, json) {
+  if (json) {
+    process.stdout.write(JSON.stringify(data) + "\n");
+  } else {
+    process.stdout.write(JSON.stringify(data, null, 2) + "\n");
+  }
+}
+function fail(error) {
+  const msg = typeof error === "object" && error !== null && "title" in error ? String(error.title) : typeof error === "object" ? JSON.stringify(error) : String(error);
+  process.stderr.write(`error: ${msg}
+`);
+  process.exit(1);
+}
+
+// src/commands/memory.ts
+function registerMemory(program2) {
+  const memory = program2.command("memory").description("Create, read, and search memories");
+  memory.command("create").description("Create a memory (POST /memories)").requiredOption("--text <text>", "Memory body text").option("--type <type>", "Memory type", "reference").option("--title <title>", "Optional title").option("--tag <tag...>", "Tags (repeatable)").option("--owner-type <ownerType>", "Workspace | Project | Unfiled", "Unfiled").option("--owner-id <ownerId>", "Owner id (required for Workspace/Project)").option("--source <source>", "Source / lane stamp", "cli").option("--confidence <n>", "Confidence 0..1", "1.0").action(async (opts, cmd) => {
+    const cfg = resolveConfig(cmd.optsWithGlobals());
+    const client = await makeClient(cfg);
+    const unfiled = String(opts.ownerType).toLowerCase() === "unfiled";
+    const { data, error } = await client.POST("/memories", {
+      body: {
+        text: opts.text,
+        type: opts.type,
+        content: "{}",
+        confidence: Number(opts.confidence),
+        source: opts.source,
+        archetype: "Document",
+        title: opts.title ?? null,
+        tags: opts.tag ?? null,
+        owner: unfiled ? null : { type: opts.ownerType, id: String(opts.ownerId ?? "") }
+      }
+    });
+    if (error) fail(error);
+    emit(data, cmd.optsWithGlobals().json);
+  });
+  memory.command("get <memoryId>").description("Fetch a memory by id (GET /memories/{memoryId})").action(async (memoryId, _opts, cmd) => {
+    const cfg = resolveConfig(cmd.optsWithGlobals());
+    const client = await makeClient(cfg);
+    const { data, error } = await client.GET("/memories/{memoryId}", {
+      params: { path: { memoryId } }
+    });
+    if (error) fail(error);
+    emit(data, cmd.optsWithGlobals().json);
+  });
+  memory.command("search <query>").description("Hybrid search (POST /memories/search; SemanticQuery -> vector+FTS RRF)").option("--limit <n>", "Max results", "10").option("--tag <tag...>", "Require all listed tags").option("--workspace <workspaceId>", "Scope to a workspace (cascades to its projects)").option("--include-archived", "Include archived memories", false).action(async (query, opts, cmd) => {
+    const cfg = resolveConfig(cmd.optsWithGlobals());
+    const client = await makeClient(cfg);
+    const { data, error } = await client.POST("/memories/search", {
+      body: {
+        query: null,
+        textQuery: null,
+        semanticQuery: query,
+        hybrid: true,
+        limit: Number(opts.limit),
+        includeArchived: Boolean(opts.includeArchived),
+        includeSystem: false,
+        ...opts.tag ? { tags: opts.tag } : {},
+        ...opts.workspace ? { workspaceId: opts.workspace } : {}
+      }
+    });
+    if (error) fail(error);
+    emit(data, cmd.optsWithGlobals().json);
+  });
+}
+
+// src/commands/worklog.ts
+function registerWorklog(program2) {
+  const worklog = program2.command("worklog").description("Append to the daily work log");
+  worklog.command("append").description("Append a work-log entry (POST /operator-surface/work-log/append)").requiredOption("--text <text>", "Entry body (short bullets / pointers) \u2014 the bullet").option("--source <source>", "Lane stamp (e.g. claude-code-chris) \u2014 laneId", "cli").option("--workspace <workspaceId>", "Target work-log workspace (default: caller's daily log)").option("--title <title>", "Optional entry title").action(async (opts, cmd) => {
+    const cfg = resolveConfig(cmd.optsWithGlobals());
+    const client = await makeClient(cfg);
+    const { data, error } = await client.POST("/operator-surface/work-log/append", {
+      body: {
+        bullet: opts.text,
+        laneId: opts.source ?? null,
+        workspaceId: opts.workspace ?? null,
+        title: opts.title ?? null
+      }
+    });
+    if (error) fail(error);
+    emit(data, cmd.optsWithGlobals().json);
+  });
+}
+
+// src/index.ts
+var program = new Command();
+program.name("sechroom").description("Sechroom CLI \u2014 thin generated client over the Sechroom HTTP API. An agent/human surface alongside MCP.").version("0.0.0").option("--base-url <url>", "API base URL (overrides config / SECHROOM_BASE_URL)").option("--tenant <tenant>", "Tenant id (required by the API; overrides config / SECHROOM_TENANT)").option("--json", "Emit compact JSON (for scripts and agents)", false);
+program.command("login").description("Sign in via browser (OAuth auth-code + PKCE, dynamic client registration)").action(async (_opts, cmd) => {
+  const g = cmd.optsWithGlobals();
+  const persisted = readPersisted();
+  const baseUrl = g.baseUrl ?? process.env.SECHROOM_BASE_URL ?? persisted.baseUrl ?? "https://app.sechroom.ai/api";
+  await login({ baseUrl: baseUrl.replace(/\/$/, ""), tenant: g.tenant ?? "" });
+});
+var config = program.command("config").description("Manage persisted CLI config");
+config.command("set <key> <value>").description("Set baseUrl | tenant | clientId").action((key, value) => {
+  if (!["baseUrl", "tenant", "clientId"].includes(key)) {
+    process.stderr.write(`unknown key: ${key} (expected baseUrl | tenant | clientId)
+`);
+    process.exit(1);
+  }
+  writePersisted({ [key]: value });
+  process.stdout.write(`set ${key}
+`);
+});
+config.command("show").description("Print persisted config").action(() => {
+  process.stdout.write(JSON.stringify(readPersisted(), null, 2) + "\n");
+});
+registerMemory(program);
+registerWorklog(program);
+program.parseAsync().catch((err) => {
+  process.stderr.write(`error: ${err instanceof Error ? err.message : String(err)}
+`);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@sechroom/cli",
+  "version": "2026.6.1",
+  "description": "Sechroom CLI — a thin, generated client over the Sechroom HTTP API. An agent/human surface alongside MCP.",
+  "type": "module",
+  "license": "UNLICENSED",
+  "author": "OCD",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/OcdLimited/sechroom.git",
+    "directory": "tools/sechroom-cli"
+  },
+  "bin": {
+    "sechroom": "./dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "scripts": {
+    "gen": "openapi-typescript \"${SECHROOM_OPENAPI_URL:-https://app.sechroom.ai/api/openapi/v1.json}\" -o src/generated/api.d.ts",
+    "build": "tsup src/index.ts --format esm --target node20 --clean",
+    "dev": "tsx src/index.ts",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "commander": "^12.1.0",
+    "open": "^10.1.0",
+    "openapi-fetch": "^0.13.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.14.0",
+    "openapi-typescript": "^7.4.0",
+    "tsup": "^8.3.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.6.0"
+  }
+}