@calibraops/cli 0.1.0

package/README.md

@@ -0,0 +1,94 @@
+# `calibra` CLI
+
+CalibraOps Operating Layer 的独立命令行客户端（#131 S4/S6）。任何 coding agent /
+人，加载角色 bundle 后经本 CLI 操作 CalibraOps——薄 HTTP 客户端，**治理逻辑在
+服务端**：
+
+- **写**只走 `POST /api/apply`（受治理内核 `Calibra.Cli.apply` + 同事务不可变
+  `ChangeRecord`）；身份（`actor` / `customer` / `actor_kind` / `actor_role`）由
+  服务端从认证 token 派生，CLI **不自证**。
+- **读**走 `GET /api/calibra/{query,search,get,changelog}`，认证 actor 传 Ash，
+  租户隔离策略生效。
+
+> 与 `mix calibra`（dev / 本地运维，in-process 无认证）相对——本 CLI 是
+> **production 写入路径**。
+
+## 运行
+
+```sh
+bun install            # 首次
+bun run bin/calibra.ts <command>
+# 或链接为 calibra：bun link
+```
+
+## 认证
+
+两种模式，都存 `~/.calibra/credentials.json`（0600，多 profile）；token 过期自动刷新。
+
+**OAuth Authorization Code + PKCE（人，浏览器交互）**——`calibra login` 默认走此：
+
+```sh
+calibra login [--profile <name>]
+```
+
+打开浏览器经 Hydra 登录，loopback `127.0.0.1:18988` 收回调。
+
+**client_credentials（agent / 机器，非交互）**——给 `--client-id/--client-secret`：
+
+```sh
+calibra login --profile agent --client-id calibra-agent --client-secret <secret>
+```
+
+环境变量：`CALIBRA_API_URL`（默认 `http://localhost:4001`）、`CALIBRA_AUTH_URL`
+（默认 `http://localhost:4544/oauth2/auth`）、`CALIBRA_TOKEN_URL`（默认
+`…/oauth2/token`）、`CALIBRA_TOKEN`（直供 token，跳过 login，CI / 调试用）。
+
+### 多 profile
+
+每个 `--profile <name>` 是独立身份（人 / agent / 不同租户）。所有命令支持
+`--profile`，缺省用 current。
+
+```sh
+calibra profile list          # 列出所有 profile，标 current
+calibra profile use <name>    # 切换 current
+calibra status [--profile N]  # 某 profile 的身份 / 过期时间
+calibra logout [--profile N]
+```
+
+### 注册 Hydra client（一次性运维）
+
+两个 client 由运维在 Hydra（dev admin 端口 4545）注册一次：
+
+```sh
+# 人——PKCE public client（无 secret）
+hydra create client --endpoint http://localhost:4545 \
+  --grant-type authorization_code,refresh_token --response-type code \
+  --token-endpoint-auth-method none --scope "openid offline_access" \
+  --redirect-uri http://127.0.0.1:18988/callback --id calibra-cli
+
+# agent——client_credentials confidential client
+hydra create client --endpoint http://localhost:4545 \
+  --grant-type client_credentials --token-endpoint-auth-method client_secret_post \
+  --id calibra-agent --secret <secret>
+```
+
+`calibra-agent` 已在 `config :calibra, :machine_principals` 白名单里映射到受控
+service-principal Member（`calibra-agent@svc.calibra`，role `compliance_admin`）。
+
+## 命令
+
+```sh
+calibra login [--profile <name>] [--client-id <id> --client-secret <s>]
+calibra logout [--profile <name>]
+calibra status [--profile <name>]
+calibra profile list | use <name>
+
+calibra query <name> [--<arg> <value> ...]   # 必答查询 / 列表
+calibra search <text> [--limit <n>]          # 纯 Postgres FTS
+calibra get <kind> <id>
+calibra changelog <kind> <id>
+calibra apply --kind <k> --op <create|update|...> \
+  --data '<json>' --rationale '<text>' [--cite a,b] [--target-id <id>]
+```
+
+成功输出单个 JSON（stdout）；失败 stderr + 退出码 1。

package/dist/calibra.js

@@ -0,0 +1,451 @@
+#!/usr/bin/env bun
+// @bun
+
+// src/auth.ts
+import { createServer } from "http";
+import { exec } from "child_process";
+import { createHash, randomBytes } from "crypto";
+
+// src/store.ts
+import { homedir } from "os";
+import { join } from "path";
+import { existsSync, mkdirSync, readFileSync, writeFileSync, chmodSync } from "fs";
+var DIR = join(homedir(), ".calibra");
+var CREDENTIALS_FILE = join(DIR, "credentials.json");
+function emptyStore() {
+  return { version: 1, current: "default", profiles: {} };
+}
+function loadStore() {
+  if (!existsSync(CREDENTIALS_FILE))
+    return emptyStore();
+  try {
+    const parsed = JSON.parse(readFileSync(CREDENTIALS_FILE, "utf8"));
+    if (parsed && parsed.version === 1 && parsed.profiles)
+      return parsed;
+    return emptyStore();
+  } catch {
+    return emptyStore();
+  }
+}
+function saveStore(s) {
+  if (!existsSync(DIR))
+    mkdirSync(DIR, { recursive: true, mode: 448 });
+  writeFileSync(CREDENTIALS_FILE, JSON.stringify(s, null, 2), { mode: 384 });
+  chmodSync(CREDENTIALS_FILE, 384);
+}
+function getProfile(s, name) {
+  return s.profiles[name ?? s.current] ?? null;
+}
+function putProfile(name, c) {
+  const s = loadStore();
+  s.profiles[name] = c;
+  s.current = name;
+  saveStore(s);
+}
+function removeProfile(name) {
+  const s = loadStore();
+  delete s.profiles[name];
+  if (s.current === name)
+    s.current = Object.keys(s.profiles)[0] ?? "default";
+  saveStore(s);
+}
+function setCurrent(name) {
+  const s = loadStore();
+  if (!s.profiles[name])
+    throw new Error(`profile not found: ${name}`);
+  s.current = name;
+  saveStore(s);
+}
+
+// src/auth.ts
+var DEFAULT_API = process.env.CALIBRA_API_URL ?? "http://localhost:4001";
+var DEFAULT_TOKEN_URL = process.env.CALIBRA_TOKEN_URL ?? "http://localhost:4544/oauth2/token";
+var DEFAULT_AUTH_URL = process.env.CALIBRA_AUTH_URL ?? "http://localhost:4544/oauth2/auth";
+var PKCE_CLIENT_ID = process.env.CALIBRA_PKCE_CLIENT_ID ?? "calibra-cli";
+var LOOPBACK_PORT = 18988;
+var REDIRECT_URI = `http://127.0.0.1:${LOOPBACK_PORT}/callback`;
+function b64url(buf) {
+  return buf.toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+async function exchangeToken(tokenUrl, params) {
+  const res = await fetch(tokenUrl, {
+    method: "POST",
+    headers: { "content-type": "application/x-www-form-urlencoded" },
+    body: new URLSearchParams(params)
+  });
+  if (!res.ok)
+    throw new Error(`token endpoint ${res.status}: ${await res.text()}`);
+  return await res.json();
+}
+function identityFromJwt(jwt) {
+  try {
+    const part = jwt.split(".")[1];
+    if (!part)
+      return "unknown";
+    const payload = JSON.parse(Buffer.from(part, "base64url").toString());
+    return payload.email ?? payload.sub ?? "unknown";
+  } catch {
+    return "unknown";
+  }
+}
+async function clientCredentialsLogin(opts) {
+  const tokenUrl = opts.tokenUrl ?? DEFAULT_TOKEN_URL;
+  const apiUrl = opts.apiUrl ?? DEFAULT_API;
+  const t = await exchangeToken(tokenUrl, {
+    grant_type: "client_credentials",
+    client_id: opts.clientId,
+    client_secret: opts.clientSecret
+  });
+  const c = {
+    apiUrl,
+    tokenUrl,
+    authMode: "client_credentials",
+    clientId: opts.clientId,
+    clientSecret: opts.clientSecret,
+    token: t.access_token,
+    expiresAt: Date.now() + (t.expires_in ?? 3600) * 1000,
+    identity: opts.clientId
+  };
+  putProfile(opts.profile, c);
+  return c;
+}
+async function pkceLogin(opts) {
+  const apiUrl = opts.apiUrl ?? DEFAULT_API;
+  const authUrl = opts.authUrl ?? DEFAULT_AUTH_URL;
+  const tokenUrl = opts.tokenUrl ?? DEFAULT_TOKEN_URL;
+  const verifier = b64url(randomBytes(32));
+  const challenge = b64url(createHash("sha256").update(verifier).digest());
+  const state = b64url(randomBytes(16));
+  const u = new URL(authUrl);
+  u.searchParams.set("response_type", "code");
+  u.searchParams.set("client_id", PKCE_CLIENT_ID);
+  u.searchParams.set("redirect_uri", REDIRECT_URI);
+  u.searchParams.set("scope", "openid offline_access");
+  u.searchParams.set("state", state);
+  u.searchParams.set("code_challenge", challenge);
+  u.searchParams.set("code_challenge_method", "S256");
+  const code = await waitForCode(u.toString(), state);
+  const t = await exchangeToken(tokenUrl, {
+    grant_type: "authorization_code",
+    code,
+    redirect_uri: REDIRECT_URI,
+    client_id: PKCE_CLIENT_ID,
+    code_verifier: verifier
+  });
+  const c = {
+    apiUrl,
+    tokenUrl,
+    authMode: "pkce",
+    clientId: PKCE_CLIENT_ID,
+    refreshToken: t.refresh_token,
+    token: t.access_token,
+    expiresAt: Date.now() + (t.expires_in ?? 3600) * 1000,
+    identity: identityFromJwt(t.access_token)
+  };
+  putProfile(opts.profile, c);
+  return c;
+}
+function waitForCode(authorizeUrl, expectedState) {
+  return new Promise((resolve, reject) => {
+    const timeout = setTimeout(() => {
+      server.close();
+      reject(new Error("login timed out (120s)"));
+    }, 120000);
+    const server = createServer((req, res) => {
+      const url = new URL(req.url ?? "/", `http://127.0.0.1:${LOOPBACK_PORT}`);
+      if (url.pathname !== "/callback") {
+        res.writeHead(404);
+        res.end("not found");
+        return;
+      }
+      const code = url.searchParams.get("code");
+      const state = url.searchParams.get("state");
+      const err = url.searchParams.get("error");
+      const page = (title, msg) => {
+        res.writeHead(200, { "content-type": "text/html" });
+        res.end(`<!doctype html><body style="font-family:system-ui;text-align:center;padding:48px">` + `<h2>${title}</h2><p>${msg}</p></body>`);
+        clearTimeout(timeout);
+        server.close();
+      };
+      if (err) {
+        page("Login failed", err);
+        reject(new Error(`OAuth error: ${err}`));
+        return;
+      }
+      if (!code || state !== expectedState) {
+        page("Login failed", "state mismatch or missing code");
+        reject(new Error("invalid callback: state mismatch or missing code"));
+        return;
+      }
+      page("Login successful", "You can close this window and return to the terminal.");
+      resolve(code);
+    });
+    server.on("error", (e) => {
+      clearTimeout(timeout);
+      reject(e.code === "EADDRINUSE" ? new Error(`port ${LOOPBACK_PORT} in use \u2014 close other \`calibra login\` and retry`) : e);
+    });
+    server.listen(LOOPBACK_PORT, "127.0.0.1", () => {
+      console.error(`
+calibra: opening browser for login\u2026`);
+      console.error(`  \u82E5\u6D4F\u89C8\u5668\u672A\u6253\u5F00\uFF0C\u624B\u52A8\u8BBF\u95EE\uFF1A
+  ${authorizeUrl}
+`);
+      const cmd = process.platform === "darwin" ? "open" : process.platform === "win32" ? "start" : "xdg-open";
+      exec(`${cmd} "${authorizeUrl}"`, () => {});
+    });
+  });
+}
+async function bearer(profileName) {
+  const envTok = process.env.CALIBRA_TOKEN;
+  if (envTok)
+    return { token: envTok, apiUrl: DEFAULT_API };
+  const store = loadStore();
+  const c = getProfile(store, profileName);
+  if (!c) {
+    throw new Error(`not logged in${profileName ? ` (profile ${profileName})` : ""} \u2014 run \`calibra login\``);
+  }
+  if (c.expiresAt && Date.now() > c.expiresAt - 30000) {
+    const refreshed = await refresh(c);
+    putProfile(profileName ?? store.current, refreshed);
+    return { token: refreshed.token, apiUrl: refreshed.apiUrl };
+  }
+  return { token: c.token, apiUrl: c.apiUrl };
+}
+async function refresh(c) {
+  if (c.authMode === "client_credentials" && c.clientId && c.clientSecret) {
+    const t = await exchangeToken(c.tokenUrl, {
+      grant_type: "client_credentials",
+      client_id: c.clientId,
+      client_secret: c.clientSecret
+    });
+    return { ...c, token: t.access_token, expiresAt: Date.now() + (t.expires_in ?? 3600) * 1000 };
+  }
+  if (c.authMode === "pkce" && c.refreshToken && c.clientId) {
+    const t = await exchangeToken(c.tokenUrl, {
+      grant_type: "refresh_token",
+      refresh_token: c.refreshToken,
+      client_id: c.clientId
+    });
+    return {
+      ...c,
+      token: t.access_token,
+      refreshToken: t.refresh_token ?? c.refreshToken,
+      expiresAt: Date.now() + (t.expires_in ?? 3600) * 1000
+    };
+  }
+  throw new Error("token expired and cannot refresh \u2014 run `calibra login`");
+}
+
+// src/api.ts
+async function parse(res) {
+  const text = await res.text();
+  const json = text ? JSON.parse(text) : {};
+  if (!res.ok)
+    throw new Error(typeof json.error === "string" ? json.error : `HTTP ${res.status}`);
+  return json;
+}
+async function apiGet(path, profile) {
+  const { token, apiUrl } = await bearer(profile);
+  const res = await fetch(`${apiUrl}${path}`, {
+    headers: { authorization: `Bearer ${token}`, accept: "application/json" }
+  });
+  return parse(res);
+}
+async function apiPost(path, body, profile) {
+  const { token, apiUrl } = await bearer(profile);
+  const res = await fetch(`${apiUrl}${path}`, {
+    method: "POST",
+    headers: {
+      authorization: `Bearer ${token}`,
+      "content-type": "application/json",
+      accept: "application/json"
+    },
+    body: JSON.stringify(body)
+  });
+  return parse(res);
+}
+
+// src/main.ts
+var USAGE = `calibra \u2014 CalibraOps Operating Layer CLI (#131)
+
+  calibra login [--profile <name>]                       # OAuth PKCE \u6D4F\u89C8\u5668\u767B\u5F55\uFF08\u4EBA\uFF09
+                [--client-id <id> --client-secret <s>]   # \u6216 client_credentials\uFF08agent/\u673A\u5668\uFF09
+                [--api-url <u>] [--auth-url <u>] [--token-url <u>]
+  calibra logout [--profile <name>]
+  calibra status [--profile <name>]
+  calibra profile list | use <name>
+
+  calibra query <name> [--<arg> <value> ...]
+  calibra search <text> [--limit <n>]
+  calibra get <kind> <id>
+  calibra changelog <kind> <id>
+  calibra apply --kind <k> --op <create|update|...> --data <json> --rationale <text>
+                [--cite <chunk_a,chunk_b>] [--target-id <id>]
+
+\u6240\u6709\u547D\u4EE4\u652F\u6301 --profile <name>\uFF08\u9ED8\u8BA4 current profile\uFF09\u3002
+\u8EAB\u4EFD\u4ECE\u8BA4\u8BC1 token \u6D3E\u751F\uFF08\u670D\u52A1\u7AEF\uFF09\uFF1B\u5199\u5165\u53EA\u7ECF POST /api/apply\uFF08\u53D7\u6CBB\u7406 + ChangeRecord\uFF09\u3002
+\u73AF\u5883\u53D8\u91CF\uFF1ACALIBRA_API_URL\u3001CALIBRA_AUTH_URL\u3001CALIBRA_TOKEN_URL\u3001CALIBRA_TOKEN\u3002`;
+function parseArgs(args) {
+  const flags = {};
+  const positional = [];
+  for (let i = 0;i < args.length; i++) {
+    const a = args[i];
+    if (a.startsWith("--")) {
+      const key = a.slice(2);
+      const next = args[i + 1];
+      if (next !== undefined && !next.startsWith("--")) {
+        flags[key] = next;
+        i++;
+      } else {
+        flags[key] = "true";
+      }
+    } else {
+      positional.push(a);
+    }
+  }
+  return { flags, positional };
+}
+function out(v) {
+  console.log(JSON.stringify(v, null, 2));
+}
+function die(msg) {
+  console.error(`calibra: ${msg}`);
+  process.exit(1);
+}
+async function main() {
+  const argv = process.argv.slice(2);
+  const cmd = argv[0];
+  const { flags, positional } = parseArgs(argv.slice(1));
+  const profile = flags["profile"];
+  if (!cmd || cmd === "help" || cmd === "--help" || cmd === "-h") {
+    console.log(USAGE);
+    process.exit(cmd ? 0 : 1);
+  }
+  try {
+    switch (cmd) {
+      case "login": {
+        const name = profile ?? "default";
+        const clientId = flags["client-id"] ?? process.env.CALIBRA_CLIENT_ID;
+        const clientSecret = flags["client-secret"] ?? process.env.CALIBRA_CLIENT_SECRET;
+        if (clientId && clientSecret) {
+          const c = await clientCredentialsLogin({
+            profile: name,
+            clientId,
+            clientSecret,
+            tokenUrl: flags["token-url"],
+            apiUrl: flags["api-url"]
+          });
+          console.error(`calibra: logged in [${name}] as ${c.identity} (client_credentials)`);
+        } else {
+          const c = await pkceLogin({
+            profile: name,
+            apiUrl: flags["api-url"],
+            authUrl: flags["auth-url"],
+            tokenUrl: flags["token-url"]
+          });
+          console.error(`calibra: logged in [${name}] as ${c.identity} (pkce)`);
+        }
+        break;
+      }
+      case "logout": {
+        const store = loadStore();
+        const name = profile ?? store.current;
+        removeProfile(name);
+        console.error(`calibra: logged out [${name}]`);
+        break;
+      }
+      case "status": {
+        const store = loadStore();
+        const name = profile ?? store.current;
+        const c = store.profiles[name];
+        if (!c)
+          die(`not logged in (profile ${name})`);
+        out({
+          profile: name,
+          current: store.current === name,
+          identity: c.identity ?? null,
+          authMode: c.authMode,
+          apiUrl: c.apiUrl,
+          expiresAt: c.expiresAt ? new Date(c.expiresAt).toISOString() : null
+        });
+        break;
+      }
+      case "profile": {
+        const sub = positional[0];
+        const store = loadStore();
+        if (sub === "list") {
+          out(Object.entries(store.profiles).map(([name, c]) => ({
+            profile: name,
+            current: store.current === name,
+            identity: c.identity ?? null,
+            authMode: c.authMode
+          })));
+        } else if (sub === "use") {
+          const name = positional[1] ?? die("profile use \u9700 <name>");
+          setCurrent(name);
+          console.error(`calibra: current profile \u2192 ${name}`);
+        } else {
+          die("profile \u9700 list | use <name>");
+        }
+        break;
+      }
+      case "query": {
+        const name = positional[0] ?? die("query \u9700 <name>");
+        const qs = new URLSearchParams;
+        for (const [k, v] of Object.entries(flags)) {
+          if (k === "profile")
+            continue;
+          qs.set(k.replace(/-/g, "_"), v);
+        }
+        const suffix = qs.toString();
+        out(await apiGet(`/api/calibra/query/${name}${suffix ? `?${suffix}` : ""}`, profile));
+        break;
+      }
+      case "search": {
+        const text = positional[0] ?? die("search \u9700 <text>");
+        const p = new URLSearchParams({ q: text });
+        if (flags["limit"])
+          p.set("limit", flags["limit"]);
+        out(await apiGet(`/api/calibra/search?${p}`, profile));
+        break;
+      }
+      case "get": {
+        const kind = positional[0] ?? die("get \u9700 <kind> <id>");
+        const id = positional[1] ?? die("get \u9700 <kind> <id>");
+        out(await apiGet(`/api/calibra/get/${kind}/${id}`, profile));
+        break;
+      }
+      case "changelog": {
+        const kind = positional[0] ?? die("changelog \u9700 <kind> <id>");
+        const id = positional[1] ?? die("changelog \u9700 <kind> <id>");
+        out(await apiGet(`/api/calibra/changelog/${kind}/${id}`, profile));
+        break;
+      }
+      case "apply": {
+        if (!flags["kind"] || !flags["op"])
+          die("apply \u9700 --kind \u4E0E --op");
+        const body = {
+          kind: flags["kind"],
+          op: flags["op"],
+          data: flags["data"] ? JSON.parse(flags["data"]) : {},
+          rationale: flags["rationale"]
+        };
+        if (flags["cite"])
+          body.cite = flags["cite"].split(",");
+        if (flags["target-id"])
+          body.target_id = flags["target-id"];
+        out(await apiPost("/api/apply", body, profile));
+        break;
+      }
+      default:
+        die(`\u672A\u77E5\u547D\u4EE4: ${cmd}
+
+${USAGE}`);
+    }
+  } catch (e) {
+    die(e.message);
+  }
+}
+
+// bin/calibra.ts
+main();

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@calibraops/cli",
+  "version": "0.1.0",
+  "description": "CalibraOps CLI — Operating Layer client: calibra login + query/search/get/changelog/apply",
+  "type": "module",
+  "bin": {
+    "calibra": "./dist/calibra.js"
+  },
+  "main": "./dist/calibra.js",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "bun": ">=1.0.0"
+  },
+  "keywords": [
+    "compliance",
+    "calibraops",
+    "cli",
+    "governance",
+    "audit"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/luqg/calibraops.git",
+    "directory": "apps/cli"
+  },
+  "homepage": "https://github.com/luqg/calibraops/tree/main/apps/cli",
+  "license": "UNLICENSED",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "dev": "bun run bin/calibra.ts",
+    "build": "bun build bin/calibra.ts --outfile dist/calibra.js --target bun",
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.2.0",
+    "typescript": "^5.7.0"
+  }
+}