@aliyunrds/ctxdb 1.0.8-beta.2 → 1.0.8-beta.4

package/dist/cli/main.js

@@ -16,7 +16,7 @@ import {
   uploadFile,
   uploadText,
   validateLocalFile
-} from "../chunk-CULTDVI2.js";
+} from "../chunk-ZW7YXNJ6.js";
 import {
   AGENT_CHOICES,
   CtxdbError,
@@ -32,27 +32,30 @@ import {
   agentHomeDirs,
   agentPlatformSupport,
   configuredAgents,
+  defaultConfigPath,
   detectInstalledAgents,
   hasConfiguredAgent,
   inspectAgentHomes,
   isAgentSlug,
   isBuiltinAgent,
-  isComplete,
+  isDataApiReady,
   load,
   removeAgent,
+  resolveDataApiCredential,
   save,
+  secureAtomicWrite,
   updateConfiguredDebug,
   writeInstalledPkgVersion
-} from "../chunk-DMS5YHIK.js";
+} from "../chunk-SVO6H62S.js";
 import {
   beginUpdateNotification,
   completeUpdateNotification,
   runSelfUpdate
-} from "../chunk-ULAWTBBC.js";
+} from "../chunk-OEZM2ZYA.js";
 import {
   DISTRIBUTION_MANIFEST
-} from "../chunk-R67JELM7.js";
-import "../chunk-VIG4SYLU.js";
+} from "../chunk-5ITT5GSP.js";
+import "../chunk-PI2SUS3M.js";
 
 // src/cli/util.ts
 var BOOLEAN_FLAGS = /* @__PURE__ */ new Set([
@@ -275,6 +278,8 @@ function formatStatusResult(r) {
     ["base_url", r.base_url],
     ["user_id", r.user_id],
     ["api_key", r.api_key_set ? "set" : "not set"],
+    ["access_token", r.access_token_set ? "set" : "not set"],
+    ["credential_type", r.credential_type ?? "none"],
     ["auto_capture", r.auto_capture],
     ["auto_recall", r.auto_recall],
     ["top_k", r.top_k],
@@ -323,15 +328,16 @@ function agentFromFlags(flags) {
 function buildContext(args) {
   const agent = agentFromFlags(args?.flags ?? {});
   const cfg = load({ agent });
-  if (!isComplete(cfg)) {
-    const hint = agent === "default" ? "run `ctxdb setup --api-key=<key> --base-url=<url>` or set CTXDB_API_KEY / CTXDB_BASE_URL env vars" : `run \`ctxdb setup --agent ${agent}\` or set CTXDB_API_KEY / CTXDB_BASE_URL / CTXDB_USER_ID env vars`;
+  const credential = resolveDataApiCredential(cfg);
+  if (!cfg.baseUrl || !credential) {
+    const hint = agent === "default" ? "run `ctxdb setup --api-key=<key> --base-url=<url>` or set CTXDB_ACCESS_TOKEN / CTXDB_API_KEY / CTXDB_BASE_URL env vars" : `run \`ctxdb setup --agent ${agent}\` or set CTXDB_ACCESS_TOKEN / CTXDB_API_KEY / CTXDB_BASE_URL / CTXDB_USER_ID env vars`;
     process.stderr.write(`config incomplete for agent ${agent}: ${hint}
 `);
     process.exit(2);
   }
   const client = new HttpClient({
     baseUrl: cfg.baseUrl,
-    apiKey: cfg.apiKey
+    credential
   });
   return { cfg, client, agent };
 }
@@ -468,11 +474,14 @@ async function runSetup(options) {
   }
   const cfg = load({ agent });
   const persistedCredentialConfig = options.persistCredential === false ? load({ agent, env: {}, managedCredentials: false }) : null;
-  if (options.apiKey) cfg.apiKey = options.apiKey;
+  if (options.apiKey) {
+    cfg.apiKey = options.apiKey;
+    cfg.oauthCredential = void 0;
+  }
   if (options.baseUrl) cfg.baseUrl = options.baseUrl.replace(/\/+$/, "");
   else if (!cfg.baseUrl) cfg.baseUrl = DEFAULT_BASE_URL;
   cfg.userId = options.userId ?? cfg.userId ?? DEFAULT_USER_ID;
-  if (!cfg.apiKey) {
+  if (!isDataApiReady(cfg)) {
     steps.push({
       step: "write-config",
       ok: false,
@@ -492,7 +501,7 @@ async function runSetup(options) {
     ok: true,
     detail: `${agent}: ${cfg.baseUrl} (user_id=${cfg.userId})`
   });
-  if (isBuiltinAgent(agent)) {
+  if (isBuiltinAgent(agent) && !cfg.oauthCredential) {
     const hasDefault = configuredAgents().includes("default");
     if (!hasDefault) {
       save(persistedCfg, void 0, { agent: "default", omitApiKey });
@@ -716,7 +725,7 @@ async function runSetup(options) {
     }
   }
   if (validate) {
-    if (!cfg.apiKey || !cfg.baseUrl) {
+    if (!isDataApiReady(cfg)) {
       steps.push({
         step: "validate-ping",
         ok: false,
@@ -724,7 +733,10 @@ async function runSetup(options) {
       });
     } else {
       try {
-        const client = new HttpClient({ baseUrl: cfg.baseUrl, apiKey: cfg.apiKey });
+        const client = new HttpClient({
+          baseUrl: cfg.baseUrl,
+          credential: resolveDataApiCredential(cfg)
+        });
         await client.get("/v1/ping/");
         steps.push({ step: "validate-ping", ok: true });
       } catch (err) {
@@ -811,8 +823,8 @@ async function runSetupAll(options = {}, dependencies = {}) {
   }
   for (const agent of detection.selected) {
     const existing = configSnapshot.get(agent);
-    const apiKey = options.apiKey ?? existing.apiKey;
-    if (!apiKey) {
+    const apiKey = options.apiKey ?? (existing.oauthCredential ? void 0 : existing.apiKey ?? void 0);
+    if (!apiKey && !isDataApiReady(existing)) {
       agents[agent] = missingApiKeyResult(agent);
       continue;
     }
@@ -2090,12 +2102,13 @@ FLAGS
 `;
 async function inspectStatus(agent) {
   const cfg = load({ agent });
-  const complete = isComplete(cfg);
+  const credential = resolveDataApiCredential(cfg);
+  const complete = Boolean(cfg.baseUrl && credential);
   let connected = false;
   let pingError = null;
-  if (complete) {
+  if (complete && credential) {
     try {
-      const client = new HttpClient({ baseUrl: cfg.baseUrl, apiKey: cfg.apiKey });
+      const client = new HttpClient({ baseUrl: cfg.baseUrl, credential });
       await client.get("/v1/ping/");
       connected = true;
     } catch (err) {
@@ -2110,6 +2123,8 @@ async function inspectStatus(agent) {
       base_url: cfg.baseUrl,
       user_id: cfg.userId,
       api_key_set: Boolean(cfg.apiKey),
+      access_token_set: Boolean(process.env.CTXDB_ACCESS_TOKEN?.trim()),
+      credential_type: credential?.type ?? null,
       auto_capture: cfg.autoCapture,
       auto_recall: cfg.autoRecall,
       top_k: cfg.topK,
@@ -2192,17 +2207,217 @@ ${hint}
 async function ping(args) {
   const agent = agentFromFlags(args.flags);
   const cfg = load({ agent });
-  if (!isComplete(cfg)) {
+  const credential = resolveDataApiCredential(cfg);
+  if (!cfg.baseUrl || !credential) {
     fail(
-      `config incomplete for agent ${agent} \u2014 run \`ctxdb setup --agent ${agent}\` or set CTXDB_API_KEY / CTXDB_BASE_URL / CTXDB_USER_ID`
+      `config incomplete for agent ${agent} \u2014 run \`ctxdb setup --agent ${agent}\` or set CTXDB_ACCESS_TOKEN / CTXDB_API_KEY / CTXDB_BASE_URL / CTXDB_USER_ID`
     );
   }
-  const client = new HttpClient({ baseUrl: cfg.baseUrl, apiKey: cfg.apiKey });
+  const client = new HttpClient({ baseUrl: cfg.baseUrl, credential });
   const resp = await client.get("/v1/ping/");
   printResult(resp, !!args.flags.json);
   return 0;
 }
 
+// src/cli/device-auth-cli.ts
+import { dirname as dirname3, join as join2 } from "path";
+import { CoreDeviceClient, normalizeCoreOrigin as normalizeCoreOrigin2, OAuthSessionStore } from "@aliyunrds/ctxdb-shared";
+
+// src/lib/oauth-login-config.ts
+import { closeSync, existsSync as existsSync2, mkdirSync as mkdirSync2, openSync, readFileSync as readFileSync2, unlinkSync as unlinkSync2 } from "fs";
+import { dirname as dirname2 } from "path";
+import { setTimeout as delay } from "timers/promises";
+import { normalizeCoreOrigin, oauthProfile } from "@aliyunrds/ctxdb-shared";
+function read(path) {
+  if (!existsSync2(path)) return { version: 2, agents: {} };
+  let raw;
+  try {
+    raw = JSON.parse(readFileSync2(path, "utf8"));
+  } catch {
+    throw new Error("Invalid ctxdb configuration; login did not overwrite it.");
+  }
+  if (!raw || raw.version !== 2 || !raw.agents || typeof raw.agents !== "object" || Array.isArray(raw.agents)) {
+    throw new Error("Unsupported ctxdb configuration; login did not overwrite it.");
+  }
+  return raw;
+}
+function selectedOAuthProfile(path, agent) {
+  const section = read(path).agents[agent];
+  return oauthProfile(section?.oauth_credential_ref, path, agent, section?.base_url);
+}
+async function commitOAuthProfile(path, agent, reference, baseUrl) {
+  oauthProfile(reference, path, agent, baseUrl);
+  mkdirSync2(dirname2(path), { recursive: true, mode: 448 });
+  const lock = path + ".oauth-config.lock", deadline = Date.now() + 1e4;
+  let fd;
+  while (true) {
+    try {
+      fd = openSync(lock, "wx", 384);
+      break;
+    } catch (error) {
+      if (error.code !== "EEXIST") throw new Error("Cannot lock OAuth profile configuration.");
+      if (Date.now() >= deadline) throw new Error("OAuth profile configuration is locked; recover a crashed login's config lock before retrying.");
+      await delay(25);
+    }
+  }
+  try {
+    const raw = read(path), section = raw.agents[agent] ?? {};
+    if (typeof section !== "object" || Array.isArray(section)) throw new Error("Invalid agent profile; login did not overwrite it.");
+    const previous = oauthProfile(section.oauth_credential_ref, path, agent, section.base_url);
+    raw.agents[agent] = { ...section, oauth_credential_ref: reference, base_url: normalizeCoreOrigin(baseUrl) };
+    delete raw.agents[agent].api_key;
+    secureAtomicWrite(path, JSON.stringify(raw, null, 2) + "\n");
+    return previous;
+  } finally {
+    closeSync(fd);
+    unlinkSync2(lock);
+  }
+}
+function consoleAuthorizationBase(path, core) {
+  if (!existsSync2(path)) return void 0;
+  try {
+    const raw = JSON.parse(readFileSync2(path, "utf8"));
+    if (raw.version !== 1 || !Array.isArray(raw.environments) || raw.environments.length > 32) throw new Error();
+    const matches = raw.environments.filter((entry) => normalizeCoreOrigin(entry.core_url) === core);
+    if (matches.length > 1) throw new Error();
+    if (!matches.length) return void 0;
+    const url = new URL(matches[0].authorization_url);
+    if (url.protocol !== "https:" || url.username || url.password || url.search || url.hash) throw new Error();
+    return url.toString();
+  } catch {
+    throw new Error("Invalid local device-environments.json. No authorization request was created.");
+  }
+}
+
+// src/cli/device-auth-cli.ts
+var usage = "ctxdb login [--agent <name>] [--server <core-origin>] [--device-code] [--no-browser] [--json]\n";
+function createPublicAuthCommands(dependencies = {}) {
+  const env = () => dependencies.env ?? process.env;
+  const stdout = dependencies.stdout ?? ((s) => {
+    process.stdout.write(s);
+  });
+  const stderr = dependencies.stderr ?? ((s) => {
+    process.stderr.write(s);
+  });
+  const client = dependencies.client ?? ((url) => new CoreDeviceClient(url));
+  const output = (value, json) => stdout(json ? JSON.stringify(value) + "\n" : String(value) + "\n");
+  function options(args, login = false) {
+    const allowed = ["agent", "json", "help", "h", ...login ? ["server", "device-code", "no-browser"] : []];
+    if (args.positional.length || Object.keys(args.flags).some((k) => !allowed.includes(k))) throw new Error("Unsupported Device login option.");
+    for (const flag of ["json", "help", "h", "device-code", "no-browser"]) {
+      if (args.flags[flag] !== void 0 && args.flags[flag] !== true) throw new Error("Invalid boolean Device login option.");
+    }
+    const agent = args.flags.agent ?? agentFromEnv(env());
+    if (!isAgentSlug(agent)) throw new Error("Invalid agent profile.");
+    const path = defaultConfigPath(env());
+    return { agent, path, json: args.flags.json === true };
+  }
+  async function revoke(profile) {
+    return new OAuthSessionStore(profile.directory).logout(profile.reference, profile.profile, client(profile.baseUrl));
+  }
+  return {
+    async login(args) {
+      if (args.flags.help || args.flags.h) {
+        stdout(usage);
+        return 0;
+      }
+      const { agent, path, json } = options(args, true);
+      if (["CTXDB_API_KEY", "CTXDB_ACCESS_TOKEN", "CTXDB_BASE_URL"].some((k) => env()[k])) {
+        throw new Error("Unset CTXDB_API_KEY, CTXDB_ACCESS_TOKEN and CTXDB_BASE_URL before managed login; use --server to select Core.");
+      }
+      if (args.flags.server !== void 0 && typeof args.flags.server !== "string") throw new Error("--server requires a Core origin.");
+      const previous = selectedOAuthProfile(path, agent);
+      const baseUrl = normalizeCoreOrigin2(args.flags.server ?? previous?.baseUrl ?? DEFAULT_BASE_URL);
+      const consoleBase = consoleAuthorizationBase(join2(dirname3(path), "device-environments.json"), baseUrl);
+      const connection = client(baseUrl), controller = new AbortController();
+      const interrupt = () => controller.abort();
+      process.once("SIGINT", interrupt);
+      try {
+        const session = await connection.login({ signal: controller.signal, onPrompt: (prompt) => {
+          const url = consoleBase ? new URL(consoleBase) : void 0;
+          url?.searchParams.set("user_code", prompt.userCode);
+          const safe = {
+            event: "device_authorization",
+            user_code: prompt.userCode,
+            request_id: prompt.requestId,
+            expires_in: prompt.expiresIn,
+            ...url ? { authorization_url: url.toString() } : {}
+          };
+          stderr(json ? JSON.stringify(safe) + "\n" : `User code: ${prompt.userCode}
+${url ? url.toString() : "Console URL is not configured. Complete authorization with the independent POP test client."}
+`);
+        } });
+        const store = new OAuthSessionStore(join2(dirname3(path), "oauth-credentials"));
+        const reference = store.saveLogin(agent, session);
+        let replaced;
+        try {
+          replaced = await commitOAuthProfile(path, agent, reference, baseUrl);
+        } catch (error) {
+          await store.logout(reference, agent, connection);
+          throw error;
+        }
+        if (replaced) {
+          try {
+            if (!(await revoke(replaced)).remoteRevoked) stderr("New login saved; old session could not be revoked remotely.\n");
+          } catch {
+            stderr("New login saved; old credential cleanup needs attention.\n");
+          }
+        }
+        output(json ? {
+          ok: true,
+          agent,
+          workspace_id: session.workspaceId,
+          member_id: session.memberId,
+          scope: session.scope,
+          client_id: session.clientId,
+          account_display: session.accountDisplay,
+          authorization_method: "device-code"
+        } : `Logged in for ${agent}: Workspace ${session.workspaceId}, Member ${session.memberId}, scope ${session.scope}. Run ctxdb setup --agent ${agent} separately.`, json);
+        return 0;
+      } finally {
+        process.removeListener("SIGINT", interrupt);
+      }
+    },
+    async status(args) {
+      if (args.flags.help || args.flags.h) {
+        stdout("ctxdb auth status [--agent <name>] [--json]\n");
+        return 0;
+      }
+      const { agent, path, json } = options(args);
+      const profile = selectedOAuthProfile(path, agent);
+      const state = profile ? new OAuthSessionStore(profile.directory).status(profile.reference, agent) : { state: "missing" };
+      const overridden = Boolean(env().CTXDB_ACCESS_TOKEN || env().CTXDB_API_KEY);
+      const ok = state.state === "ready";
+      output(json ? { ok, agent, ...state, environment_credential_override: overridden } : `${agent}: ${state.state}${overridden ? " (environment credential takes precedence for DATA requests)" : ""}`, json);
+      return ok ? 0 : 1;
+    },
+    async logout(args) {
+      if (args.flags.help || args.flags.h) {
+        stdout("ctxdb logout [--agent <name>] [--json]\n");
+        return 0;
+      }
+      const { agent, path, json } = options(args);
+      const profile = selectedOAuthProfile(path, agent);
+      if (!profile) {
+        output(json ? { ok: true, agent, local_cleared: true, remote_revoked: false, status: "no_managed_session" } : `${agent}: no managed session.`, json);
+        return 0;
+      }
+      const store = new OAuthSessionStore(profile.directory);
+      if (store.status(profile.reference, agent).state === "logged_out") {
+        output(json ? { ok: true, agent, local_cleared: true, remote_revoked: false, status: "already_logged_out" } : `${agent}: already logged out locally.`, json);
+        return 0;
+      }
+      const result = await revoke(profile);
+      output(json ? { ok: result.remoteRevoked, agent, local_cleared: true, remote_revoked: result.remoteRevoked } : `${agent}: local credential cleared; ${result.remoteRevoked ? "remote revoke completed" : "remote revoke failed or could not be confirmed"}.`, json);
+      return result.remoteRevoked ? 0 : 1;
+    }
+  };
+}
+var commands = createPublicAuthCommands();
+var deviceLogin = commands.login;
+var deviceAuthStatus = commands.status;
+var deviceLogout = commands.logout;
+
 // src/cli/setup-cli.ts
 var HELP = `ctxdb setup \u2014 configure an agent
 
@@ -2781,12 +2996,12 @@ function parseFileUpdate(args) {
   }
   fail(UPDATE_FILE_USAGE, 2);
 }
-function shouldWaitForIngest(args, usage) {
+function shouldWaitForIngest(args, usage2) {
   const waitRequested = args.flags.wait !== void 0;
   const noWaitRequested = args.flags["no-wait"] !== void 0;
   if (waitRequested && noWaitRequested) {
     fail(`cannot use --wait and --no-wait together
-${usage}`, 2);
+${usage2}`, 2);
   }
   return waitRequested;
 }
@@ -3396,130 +3611,130 @@ function stringFlag(args, name) {
   const value = args.flags[name];
   return typeof value === "string" && value.trim() !== "" ? value : void 0;
 }
-function requireIdFlag(args, name, usage) {
+function requireIdFlag(args, name, usage2) {
   const value = stringFlag(args, name);
   if (value === void 0) fail(`--${name} is required
-${usage}`, 2);
+${usage2}`, 2);
   return value;
 }
-function requireTemplateIdPositional(args, usage) {
+function requireTemplateIdPositional(args, usage2) {
   const templateId = args.positional[0];
-  if (!templateId || templateId.trim() === "") fail(usage, 2);
+  if (!templateId || templateId.trim() === "") fail(usage2, 2);
   return templateId;
 }
-function intFlag(args, name, usage) {
+function intFlag(args, name, usage2) {
   const raw = stringFlag(args, name);
   if (raw === void 0) return void 0;
   const n = Number(raw);
   if (!Number.isInteger(n) || n < 1) {
     fail(`invalid --${name}: ${raw} (expected a positive integer)
-${usage}`, 2);
+${usage2}`, 2);
   }
   return n;
 }
-function parseIdsFlag(args, usage) {
+function parseIdsFlag(args, usage2) {
   const raw = stringFlag(args, "ids");
   if (raw === void 0) fail(`--ids is required (comma-separated)
-${usage}`, 2);
+${usage2}`, 2);
   const ids = raw.split(",").map((s) => s.trim()).filter(Boolean);
   if (ids.length === 0) fail(`--ids must contain at least one id
-${usage}`, 2);
+${usage2}`, 2);
   if (ids.length > BATCH_MAX_ITEMS) {
     fail(`--ids accepts at most ${BATCH_MAX_ITEMS} items per request (got ${ids.length})
-${usage}`, 2);
+${usage2}`, 2);
   }
   return ids;
 }
-function parseResolutions(raw, usage) {
+function parseResolutions(raw, usage2) {
   let parsed;
   try {
     parsed = JSON.parse(raw);
   } catch {
     fail(`--resolutions-json is not valid JSON
-${usage}`, 2);
+${usage2}`, 2);
   }
   if (!Array.isArray(parsed) || parsed.length === 0) {
     fail(`--resolutions-json must be a non-empty array
-${usage}`, 2);
+${usage2}`, 2);
   }
   return parsed.map((entry, i) => {
     if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
       fail(`--resolutions-json[${i}] must be an object
-${usage}`, 2);
+${usage2}`, 2);
     }
     const e = entry;
     if (typeof e.index !== "number" || !Number.isInteger(e.index) || e.index < 0) {
       fail(`--resolutions-json[${i}].index must be a non-negative integer
-${usage}`, 2);
+${usage2}`, 2);
     }
     if (typeof e.choice !== "string" || e.choice.trim() === "") {
       fail(`--resolutions-json[${i}].choice must be a non-empty string
-${usage}`, 2);
+${usage2}`, 2);
     }
     const out = { index: e.index, choice: e.choice };
     if (e.comment !== void 0 && e.comment !== null) {
       if (typeof e.comment !== "string") {
         fail(`--resolutions-json[${i}].comment must be a string
-${usage}`, 2);
+${usage2}`, 2);
       }
       out.comment = e.comment;
     }
     return out;
   });
 }
-function buildTemplateUpsertBody(args, usage) {
+function buildTemplateUpsertBody(args, usage2) {
   const name = stringFlag(args, "name");
   if (name === void 0) fail(`--name is required
-${usage}`, 2);
+${usage2}`, 2);
   const sectionsRaw = args.flags["sections-json"];
   if (typeof sectionsRaw !== "string" || sectionsRaw.trim() === "") {
     fail(`--sections-json is required
-${usage}`, 2);
+${usage2}`, 2);
   }
-  const sections = parseSections(sectionsRaw, usage);
+  const sections = parseSections(sectionsRaw, usage2);
   const body = { name, sections };
   if (args.flags["is-default"] === true) body.is_default = true;
   return body;
 }
-function parseSections(raw, usage) {
+function parseSections(raw, usage2) {
   let parsed;
   try {
     parsed = JSON.parse(raw);
   } catch {
     fail(`--sections-json is not valid JSON
-${usage}`, 2);
+${usage2}`, 2);
   }
   if (!Array.isArray(parsed) || parsed.length === 0) {
     fail(`--sections-json must be a non-empty array
-${usage}`, 2);
+${usage2}`, 2);
   }
   if (parsed.length > TEMPLATE_SECTIONS_MAX) {
     fail(`--sections-json accepts at most ${TEMPLATE_SECTIONS_MAX} sections (got ${parsed.length})
-${usage}`, 2);
+${usage2}`, 2);
   }
   return parsed.map((entry, i) => {
     if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
       fail(`--sections-json[${i}] must be an object
-${usage}`, 2);
+${usage2}`, 2);
     }
     const e = entry;
     if (typeof e.title !== "string" || e.title.trim() === "") {
       fail(`--sections-json[${i}].title must be a non-empty string
-${usage}`, 2);
+${usage2}`, 2);
     }
     if (/[\r\n]/.test(e.title.trim())) {
       fail(`--sections-json[${i}].title must not contain line breaks
-${usage}`, 2);
+${usage2}`, 2);
     }
     if (typeof e.guidance !== "string" || e.guidance.trim() === "") {
       fail(`--sections-json[${i}].guidance must be a non-empty string
-${usage}`, 2);
+${usage2}`, 2);
     }
     const out = { title: e.title, guidance: e.guidance };
     if (e.level !== void 0 && e.level !== null) {
       if (typeof e.level !== "number" || !Number.isInteger(e.level) || e.level < 1 || e.level > 3) {
         fail(`--sections-json[${i}].level must be an integer in 1-3
-${usage}`, 2);
+${usage2}`, 2);
       }
       out.level = e.level;
     }
@@ -3594,7 +3809,7 @@ function compactTemplateList(data) {
 }
 
 // src/cli/review-cli.ts
-import { readFileSync as readFileSync2 } from "fs";
+import { readFileSync as readFileSync3 } from "fs";
 
 // src/lib/review.ts
 function unwrapReviewData(response, operation) {
@@ -3896,43 +4111,43 @@ function stringValue(args, name) {
   const value = args.flags[name];
   return typeof value === "string" && value.trim() !== "" ? value : void 0;
 }
-function requireId(args, flagName, positionalIndex, usage) {
+function requireId(args, flagName, positionalIndex, usage2) {
   const positional = args.positional[positionalIndex]?.trim();
   const value = positional !== void 0 && positional !== "" ? positional : stringValue(args, flagName);
-  if (value === void 0) fail(usage, 2);
+  if (value === void 0) fail(usage2, 2);
   return value.trim();
 }
-function requireEnumFlag(args, flagName, allowed, usage) {
+function requireEnumFlag(args, flagName, allowed, usage2) {
   const value = stringValue(args, flagName);
-  if (value === void 0) fail(usage, 2);
+  if (value === void 0) fail(usage2, 2);
   if (!allowed.includes(value)) {
     fail(`${flagName} must be one of ${allowed.join("|")}
-${usage}`, 2);
+${usage2}`, 2);
   }
   return value;
 }
-function positiveIntFlag(args, flagName, usage) {
+function positiveIntFlag(args, flagName, usage2) {
   const value = args.flags[flagName];
   if (value === void 0) return void 0;
-  if (typeof value !== "string") fail(usage, 2);
+  if (typeof value !== "string") fail(usage2, 2);
   const parsed = Number(value);
   if (!Number.isInteger(parsed) || parsed < 1) {
     fail(`${flagName} must be a positive integer
-${usage}`, 2);
+${usage2}`, 2);
   }
   return parsed;
 }
-function readPayloadInput(args, inlineFlag, fileFlag, usage) {
+function readPayloadInput(args, inlineFlag, fileFlag, usage2) {
   const inline = stringValue(args, inlineFlag);
   const filePath = stringValue(args, fileFlag);
   if (inline !== void 0 && filePath !== void 0) {
     fail(`cannot use --${inlineFlag} and --${fileFlag} together
-${usage}`, 2);
+${usage2}`, 2);
   }
   if (inline !== void 0) return inline;
   if (filePath !== void 0) {
     try {
-      return readFileSync2(filePath, "utf-8");
+      return readFileSync3(filePath, "utf-8");
     } catch (error) {
       fail(
         `cannot read --${fileFlag} ${filePath}: ${error instanceof Error ? error.message : String(error)}`,
@@ -3940,17 +4155,17 @@ ${usage}`, 2);
       );
     }
   }
-  fail(usage, 2);
+  fail(usage2, 2);
 }
-function parseIdsFlag2(args, usage) {
+function parseIdsFlag2(args, usage2) {
   const raw = stringValue(args, "ids");
-  if (raw === void 0) fail(usage, 2);
+  if (raw === void 0) fail(usage2, 2);
   const ids = parseIdList(raw);
   if (ids.length === 0) fail(`--ids must contain at least one id
-${usage}`, 2);
+${usage2}`, 2);
   if (ids.length > BATCH_MAX_ITEMS2) {
     fail(`--ids accepts at most ${BATCH_MAX_ITEMS2} ids per request
-${usage}`, 2);
+${usage2}`, 2);
   }
   return ids;
 }
@@ -4034,7 +4249,7 @@ ${REVIEW_ACTION_USAGE}`, 2);
   if (editedContent !== void 0) body.edited_content = editedContent;
   else if (editedContentFile !== void 0) {
     try {
-      body.edited_content = readFileSync2(editedContentFile, "utf-8");
+      body.edited_content = readFileSync3(editedContentFile, "utf-8");
     } catch (error) {
       fail(
         `cannot read --edited-content-file ${editedContentFile}: ${error instanceof Error ? error.message : String(error)}`,
@@ -4115,28 +4330,28 @@ async function reviewTemplateList(args) {
   printResult(out, !!args.flags.json);
   return 0;
 }
-function buildTemplateUpsertBody2(args, usage, requireNameAndSections) {
+function buildTemplateUpsertBody2(args, usage2, requireNameAndSections) {
   const body = {};
   const name = stringValue(args, "name");
   if (name !== void 0) {
     if (name.length > TEMPLATE_MAX_NAME_LENGTH) {
       fail(`--name must be at most ${TEMPLATE_MAX_NAME_LENGTH} characters
-${usage}`, 2);
+${usage2}`, 2);
     }
     body.name = name;
   }
   const hasSectionsInput = Object.hasOwn(args.flags, "sections") || Object.hasOwn(args.flags, "sections-file");
   if (hasSectionsInput) {
-    const raw = readPayloadInput(args, "sections", "sections-file", usage);
+    const raw = readPayloadInput(args, "sections", "sections-file", usage2);
     try {
       body.sections = parseTemplateSections(raw);
     } catch (error) {
       fail(`${error instanceof Error ? error.message : String(error)}
-${usage}`, 2);
+${usage2}`, 2);
     }
   }
   if (requireNameAndSections && (body.name === void 0 || body.sections === void 0)) {
-    fail(usage, 2);
+    fail(usage2, 2);
   }
   return body;
 }
@@ -4299,7 +4514,12 @@ USAGE
   ctxdb <command> [args] [--flags]
 
 COMMANDS
-  setup [--agent <${SUPPORTED_AGENT_CHOICES}> | --all]
+${DISTRIBUTION_MANIFEST.capabilities.deviceFlow ? `  login [--agent <name>] [--scope read_only|read_write|default] [--server <core-origin>]
+        [--device-code] [--no-browser] [--json]
+                                 Device Flow login only; run setup separately.
+  auth status [--agent <name>] [--json]
+  logout [--agent <name>] [--json]
+` : ""}  setup [--agent <${SUPPORTED_AGENT_CHOICES}> | --all]
         [--api-key=K] [--base-url=URL] [--user-id=ID]
         [--no-install-skill] [--no-validate] [--json]
                                  Without --agent \u2192 writes agents.default (CLI-only, no hooks/skills)
@@ -4474,6 +4694,7 @@ AGENT RESOLUTION (when --agent is omitted):
 ENV VARS (override selected ~/.ctxdb/ctxdb.json agent config):
   CTXDB_AGENT  CTXDB_API_KEY  CTXDB_BASE_URL  CTXDB_USER_ID
   CTXDB_AGENT_ID  CTXDB_APP_ID
+  CTXDB_ACCESS_TOKEN  Runtime-only Data API Bearer credential; takes precedence over API key
 
 UPDATE CHECK ENV VARS:
   CTXDB_DISABLE_UPDATE_CHECK=1
@@ -4487,6 +4708,7 @@ CONFIG: ~/.ctxdb/ctxdb.json (agents.default / ${SUPPORTED_AGENTS.map((agent) =>
 LOGS:   ~/.ctxdb/logs/ctxdb.log, ~/.ctxdb/logs/recall-trace.jsonl
 `;
 var ROUTES = {
+  ...DISTRIBUTION_MANIFEST.capabilities.deviceFlow ? { login: deviceLogin, logout: deviceLogout, auth: { status: deviceAuthStatus } } : {},
   setup,
   status,
   ping,
@@ -4591,14 +4813,14 @@ async function dispatch(argv, routes = ROUTES, help = HELP5) {
   return dispatchGroup([first], route, rest);
 }
 async function dispatchGroup(path, group, argv) {
-  const usage = `usage: ctxdb ${path.join(" ")} <${Object.keys(group).join("|")}> ...
+  const usage2 = `usage: ctxdb ${path.join(" ")} <${Object.keys(group).join("|")}> ...
 `;
   if (argv.length === 0) {
-    process.stderr.write(usage);
+    process.stderr.write(usage2);
     return 2;
   }
   if (argv[0] === "-h" || argv[0] === "--help") {
-    process.stdout.write(usage);
+    process.stdout.write(usage2);
     return 0;
   }
   const [sub, ...subRest] = argv;