@zksecurity/zkao-cli 0.5.1 → 0.11.0-next.2

package/README.md

@@ -14,6 +14,7 @@ npx @zksecurity/zkao-cli --help
 zkao login                                  # browser approval; saves credentials
 zkao repos
 zkao scans launch --repo <repoId> --budget 500 --preset <ref>
+zkao scans launch --repo <repoId> --preset "builtin:Diff Scan" --base main --commit <sha>
 zkao scans wait <scanId>                    # block until the scan finishes
 zkao scans cancel <scanId>                  # cancel a running or queued scan
 zkao findings list --scan <scanId>

package/dist/index.js

@@ -6,7 +6,8 @@ import { createRequire } from "module";
 import { Command } from "commander";
 import {
   ZkaoApiError,
-  ZkaoClient
+  ZkaoClient,
+  getTokenInfo
 } from "@zksecurity/zkao-sdk";
 
 // src/config.ts
@@ -39,18 +40,93 @@ function readFile() {
     );
   }
 }
-function writeConfig(update) {
-  let existing;
+function readFileForWrite() {
+  let file;
   try {
-    existing = readFile();
+    file = readFile();
   } catch {
     console.error(`zkao: replacing unparseable config at ${CONFIG_PATH}`);
-    existing = {};
+    return {};
+  }
+  if (file.projectId && file.token && !file.projects?.[file.projectId]) {
+    file.projects = {
+      ...file.projects,
+      [file.projectId]: stripUndefinedProject({
+        token: file.token,
+        baseUrl: file.baseUrl
+      })
+    };
   }
-  const merged = { ...existing, ...stripUndefined(update) };
-  writeSecretFile(CONFIG_PATH, `${JSON.stringify(merged, null, 2)}
+  return file;
+}
+function writeFile(file) {
+  writeSecretFile(CONFIG_PATH, `${JSON.stringify(file, null, 2)}
 `);
-  return merged;
+}
+function activate(file, projectId, saved) {
+  file.projectId = projectId;
+  file.token = saved.token;
+  if (saved.baseUrl === void 0) {
+    delete file.baseUrl;
+  } else {
+    file.baseUrl = saved.baseUrl;
+  }
+}
+function writeConfig(update) {
+  const file = readFileForWrite();
+  const projectId = update.projectId ?? file.projectId;
+  const saved = update.projectId ? file.projects?.[update.projectId] : void 0;
+  if (update.token === void 0 && update.projectId !== void 0 && saved) {
+    activate(file, update.projectId, {
+      ...saved,
+      baseUrl: update.baseUrl ?? saved.baseUrl
+    });
+  } else {
+    const switching = update.projectId !== void 0 && update.projectId !== file.projectId;
+    Object.assign(file, stripUndefined(update));
+    if (switching && update.token === void 0) {
+      delete file.token;
+    }
+  }
+  if (projectId && file.token && file.projectId === projectId) {
+    file.projects = {
+      ...file.projects,
+      [projectId]: {
+        ...file.projects?.[projectId],
+        token: file.token,
+        baseUrl: file.baseUrl
+      }
+    };
+  }
+  writeFile(file);
+  return { token: file.token, projectId: file.projectId, baseUrl: file.baseUrl };
+}
+function saveProjectCredentials(projectId, saved) {
+  const file = readFileForWrite();
+  file.projects = { ...file.projects, [projectId]: stripUndefinedProject(saved) };
+  activate(file, projectId, saved);
+  writeFile(file);
+}
+function useProject(projectId) {
+  const file = readFileForWrite();
+  const saved = file.projects?.[projectId];
+  if (!saved) {
+    throw new Error(
+      `No saved credentials for project ${projectId}. Run \`zkao login --project ${projectId}\`.`
+    );
+  }
+  activate(file, projectId, saved);
+  writeFile(file);
+  return saved;
+}
+function savedProjects() {
+  const file = readFile();
+  return { activeProjectId: file.projectId, projects: file.projects ?? {} };
+}
+function stripUndefinedProject(saved) {
+  return Object.fromEntries(
+    Object.entries(saved).filter(([, v]) => v !== void 0)
+  );
 }
 function writeSecretFile(path, contents) {
   mkdirSync(dirname(path), { recursive: true, mode: 448 });
@@ -67,44 +143,84 @@ function stripUndefined(obj) {
 }
 function resolveConfig(flags) {
   const file = readFile();
+  const projectId = flags.projectId ?? process.env.ZKAO_PROJECT_ID ?? file.projectId;
+  const saved = projectId ? file.projects?.[projectId] : void 0;
+  const activeMatches = file.projectId === void 0 || file.projectId === projectId;
   return {
-    token: flags.token ?? process.env.ZKAO_API_TOKEN ?? file.token,
-    projectId: flags.projectId ?? process.env.ZKAO_PROJECT_ID ?? file.projectId,
-    baseUrl: flags.baseUrl ?? resolveBaseUrlFromEnv() ?? file.baseUrl
+    token: flags.token ?? process.env.ZKAO_API_TOKEN ?? saved?.token ?? (activeMatches ? file.token : void 0),
+    projectId,
+    baseUrl: flags.baseUrl ?? resolveBaseUrlFromEnv() ?? // The top-level base URL is the active project's; a saved project
+    // carries its own (none means production).
+    (saved ? saved.baseUrl : file.baseUrl)
   };
 }
 var PENDING_PATH = join(homedir(), ".zkao", "pending-login.json");
-function writePendingLogin(pending) {
-  writeSecretFile(PENDING_PATH, `${JSON.stringify(pending, null, 2)}
-`);
+function isPendingLogin(value) {
+  if (typeof value !== "object" || value === null) {
+    return false;
+  }
+  const v = value;
+  return typeof v.deviceCode === "string" && typeof v.origin === "string" && typeof v.interval === "number" && typeof v.expiresAtMs === "number";
 }
-function readPendingLogin() {
+function readPendingLogins() {
   let raw;
   try {
     raw = readFileSync(PENDING_PATH, "utf8");
   } catch (err) {
     if (err.code === "ENOENT") {
-      return null;
+      return [];
     }
     throw err;
   }
+  let parsed;
   try {
-    return JSON.parse(raw);
+    parsed = JSON.parse(raw);
   } catch {
     console.error(
       `zkao: ignoring unparseable pending login at ${PENDING_PATH}`
     );
-    return null;
+    return [];
+  }
+  if (isPendingLogin(parsed)) {
+    return [parsed];
   }
+  const logins = parsed?.logins;
+  return logins && typeof logins === "object" ? Object.values(logins).filter(isPendingLogin) : [];
 }
-function clearPendingLogin() {
-  try {
-    unlinkSync(PENDING_PATH);
-  } catch (err) {
-    if (err.code !== "ENOENT") {
-      throw err;
+function writePendingLogins(logins) {
+  if (logins.length === 0) {
+    try {
+      unlinkSync(PENDING_PATH);
+    } catch (err) {
+      if (err.code !== "ENOENT") {
+        throw err;
+      }
     }
+    return;
   }
+  const file = {
+    logins: Object.fromEntries(logins.map((l) => [l.deviceCode, l]))
+  };
+  writeSecretFile(PENDING_PATH, `${JSON.stringify(file, null, 2)}
+`);
+}
+function addPendingLogin(pending) {
+  const now = Date.now();
+  writePendingLogins([
+    ...readPendingLogins().filter(
+      (l) => l.expiresAtMs > now && l.deviceCode !== pending.deviceCode
+    ),
+    pending
+  ]);
+}
+function removePendingLogins(deviceCodes) {
+  const now = Date.now();
+  const drop = new Set(deviceCodes);
+  writePendingLogins(
+    readPendingLogins().filter(
+      (l) => l.expiresAtMs > now && !drop.has(l.deviceCode)
+    )
+  );
 }
 
 // src/login.ts
@@ -157,15 +273,39 @@ Approve only if you started this login.
 `
   );
 }
+function describeProject(projectId, names) {
+  if (!names.name) {
+    return projectId;
+  }
+  const org = names.organization ? ` of organization "${names.organization}"` : "";
+  return `"${names.name}"${org} (${projectId})`;
+}
 function persistCredentials(poll, baseUrl) {
-  const saved = writeConfig({
-    token: poll.token,
-    projectId: poll.projectId,
-    baseUrl
+  const tokens = poll.tokens?.length ? poll.tokens : [poll];
+  for (const issued of [...tokens].reverse()) {
+    saveProjectCredentials(issued.projectId, {
+      token: issued.token,
+      baseUrl,
+      name: issued.projectName,
+      organization: issued.organizationName
+    });
+  }
+  const describe = (issued) => describeProject(issued.projectId, {
+    name: issued.projectName,
+    organization: issued.organizationName
   });
-  clearPendingLogin();
-  console.log("Authorized. Credentials saved.\n");
-  console.log(`  project: ${saved.projectId}`);
+  if (tokens.length === 1) {
+    console.log(`Authorized for project ${describe(poll)}.`);
+  } else {
+    console.log(`Authorized for ${tokens.length} projects:`);
+    for (const issued of tokens) {
+      console.log(`  ${describe(issued)}`);
+    }
+  }
+  console.log(`Active project: ${describe(poll)}.`);
+  console.log(
+    "Credentials for other projects are kept. `zkao config show` lists them; `zkao config use <projectId>` switches."
+  );
 }
 async function login(flags) {
   const cfg = resolveConfig({
@@ -175,98 +315,129 @@ async function login(flags) {
   });
   const apiBase = cfg.baseUrl ?? DEFAULT_BASE_URL;
   const origin = appOrigin(apiBase);
+  const project = flags.project ?? process.env.ZKAO_PROJECT_ID;
   const start = await postJson(`${origin}/api/auth/device`, {
-    label: hostname()
+    label: hostname(),
+    ...project ? { project } : {}
   });
   printInstructions(start);
   if (!flags.noBrowser) {
     openBrowser(start.verificationUriComplete);
   }
-  writePendingLogin({
+  const pending = {
     deviceCode: start.deviceCode,
+    userCode: start.userCode,
     origin,
     interval: Math.max(1, start.interval),
     expiresAtMs: Date.now() + start.expiresIn * 1e3,
     baseUrl: cfg.baseUrl
-  });
+  };
+  addPendingLogin(pending);
   if (flags.wait === false) {
     console.log(
       "Once you approve in the browser, run `zkao login --resume` to finish.\n"
     );
     return;
   }
-  await pollUntilDone({
-    origin,
-    deviceCode: start.deviceCode,
-    intervalMs: Math.max(1, start.interval) * 1e3,
-    deadlineMs: Date.now() + start.expiresIn * 1e3,
-    baseUrl: cfg.baseUrl
-  });
+  await pollUntilDone([pending], pending.expiresAtMs);
 }
 async function resumeLogin(flags) {
-  const pending = readPendingLogin();
-  if (!pending) {
+  const all = readPendingLogins();
+  const now = Date.now();
+  const live = all.filter((l) => l.expiresAtMs > now);
+  if (live.length < all.length) {
+    removePendingLogins([]);
+  }
+  if (live.length === 0) {
     throw new Error(
-      "No pending login. Run `zkao login --no-wait` to start one first."
+      all.length > 0 ? "The login request expired. Run `zkao login` again." : "No pending login. Run `zkao login --no-wait` to start one first."
     );
   }
-  if (Date.now() >= pending.expiresAtMs) {
-    clearPendingLogin();
-    throw new Error("The login request expired. Run `zkao login` again.");
-  }
   const waitMs = (flags.timeout ?? 0) * 1e3;
-  await pollUntilDone({
-    origin: pending.origin,
-    deviceCode: pending.deviceCode,
-    intervalMs: Math.max(1, pending.interval) * 1e3,
-    deadlineMs: Math.min(pending.expiresAtMs, Date.now() + waitMs),
-    baseUrl: pending.baseUrl,
-    reportStillPending: true
-  });
+  const lastExpiry = Math.max(...live.map((l) => l.expiresAtMs));
+  await pollUntilDone(live, Math.min(lastExpiry, Date.now() + waitMs), true);
 }
-async function pollUntilDone(opts) {
-  let intervalMs = opts.intervalMs;
+function label(pending) {
+  return pending.userCode ? `code ${pending.userCode}` : "an earlier login";
+}
+async function pollUntilDone(logins, deadlineMs, reportStillPending = false) {
+  let open = [...logins];
+  let intervalMs = Math.min(...open.map((l) => Math.max(1, l.interval))) * 1e3;
+  let lastFailure = "The login request expired. Run `zkao login` again.";
   let polled = false;
-  for (; ; ) {
+  while (open.length > 0) {
     if (polled) {
-      const remaining = opts.deadlineMs - Date.now();
+      const remaining = deadlineMs - Date.now();
       if (remaining <= 0) {
         break;
       }
       await sleep(Math.min(intervalMs, remaining));
     }
     polled = true;
-    const poll = await postJson(
-      `${opts.origin}/api/auth/device/token`,
-      { deviceCode: opts.deviceCode }
-    );
-    switch (poll.status) {
-      case "pending":
-      case "slow_down":
-        if (poll.status === "slow_down") {
+    const resolved = [];
+    const dropped = [];
+    for (const pending of open) {
+      if (Date.now() >= pending.expiresAtMs) {
+        resolved.push(pending.deviceCode);
+        dropped.push(`${label(pending)} expired`);
+        lastFailure = "The login request expired. Run `zkao login` again.";
+        continue;
+      }
+      const poll = await postJson(
+        `${pending.origin}/api/auth/device/token`,
+        { deviceCode: pending.deviceCode }
+      );
+      switch (poll.status) {
+        case "pending":
+          break;
+        case "slow_down":
           intervalMs += 2e3;
+          break;
+        case "denied":
+          resolved.push(pending.deviceCode);
+          dropped.push(`${label(pending)} was denied`);
+          lastFailure = "Authorization was denied in the browser.";
+          break;
+        case "expired":
+          resolved.push(pending.deviceCode);
+          dropped.push(`${label(pending)} expired`);
+          lastFailure = "The login request expired. Run `zkao login` again.";
+          break;
+        case "approved": {
+          removePendingLogins([...resolved, pending.deviceCode]);
+          persistCredentials(poll, pending.baseUrl);
+          const rest = open.filter(
+            (l) => l !== pending && !resolved.includes(l.deviceCode)
+          );
+          if (rest.length > 0) {
+            console.log(
+              `Still pending: ${rest.map(label).join(", ")}. Run \`zkao login --resume\` again to finish ${rest.length > 1 ? "them" : "it"}.`
+            );
+          }
+          return;
         }
-        break;
-      case "denied":
-        clearPendingLogin();
-        throw new Error("Authorization was denied in the browser.");
-      case "expired":
-        clearPendingLogin();
-        throw new Error("The login request expired. Run `zkao login` again.");
-      case "approved":
-        persistCredentials(poll, opts.baseUrl);
-        return;
-      default: {
-        const _exhaustive = poll;
-        throw new Error(
-          `Unexpected device status: ${JSON.stringify(_exhaustive)}`
-        );
+        default: {
+          const _exhaustive = poll;
+          throw new Error(
+            `Unexpected device status: ${JSON.stringify(_exhaustive)}`
+          );
+        }
+      }
+    }
+    if (resolved.length > 0) {
+      removePendingLogins(resolved);
+      open = open.filter((l) => !resolved.includes(l.deviceCode));
+      if (open.length > 0) {
+        console.error(`zkao: dropped pending login: ${dropped.join(", ")}.`);
       }
     }
   }
-  if (opts.reportStillPending) {
+  if (open.length === 0) {
+    throw new Error(lastFailure);
+  }
+  if (reportStillPending) {
     console.log(
-      "Still waiting for approval. Approve in the browser, then run `zkao login --resume` again."
+      open.length > 1 ? `Still waiting for approval of ${open.length} logins (${open.map(label).join(", ")}). Approve in the browser, then run \`zkao login --resume\` again.` : "Still waiting for approval. Approve in the browser, then run `zkao login --resume` again."
     );
     return;
   }
@@ -280,6 +451,9 @@ var CACHE_PATH = join2(dirname2(configPath()), "update-check.json");
 var CHECK_INTERVAL_MS = 24 * 60 * 60 * 1e3;
 var REGISTRY_TIMEOUT_MS = 1500;
 var PACKAGE = "@zksecurity/zkao-cli";
+function channelOf(version2) {
+  return version2.includes("-") ? "next" : "latest";
+}
 function debug(message, err) {
   if (process.env.ZKAO_DEBUG) {
     console.error(`zkao: ${message}: ${err instanceof Error ? err.message : String(err)}`);
@@ -288,7 +462,7 @@ function debug(message, err) {
 function disabled() {
   return Boolean(process.env.ZKAO_NO_UPDATE_CHECK);
 }
-function readCache() {
+function readCache(channel) {
   let raw;
   try {
     raw = readFileSync2(CACHE_PATH, "utf8");
@@ -300,7 +474,8 @@ function readCache() {
   }
   try {
     const parsed = JSON.parse(raw);
-    return typeof parsed.latest === "string" && typeof parsed.checkedAtMs === "number" ? parsed : null;
+    const valid = typeof parsed.latest === "string" && typeof parsed.checkedAtMs === "number";
+    return valid && (parsed.channel ?? "latest") === channel ? parsed : null;
   } catch (err) {
     debug("ignoring an unparseable update cache", err);
     return null;
@@ -317,47 +492,53 @@ function writeCache(cache) {
 }
 function isNewerVersion(latest, current) {
   const parse = (v) => {
-    const match = /^(\d+)\.(\d+)\.(\d+)$/.exec(v.trim());
-    return match ? [Number(match[1]), Number(match[2]), Number(match[3])] : null;
+    const match = /^(\d+)\.(\d+)\.(\d+)(?:-next\.(\d+))?$/.exec(v.trim());
+    return match ? {
+      core: [Number(match[1]), Number(match[2]), Number(match[3])],
+      pre: match[4] === void 0 ? null : Number(match[4])
+    } : null;
   };
   const a = parse(latest);
   const b = parse(current);
-  if (!(a && b)) {
+  if (!(a && b) || a.pre !== null && b.pre === null) {
     return false;
   }
-  const [aMajor, aMinor, aPatch] = a;
-  const [bMajor, bMinor, bPatch] = b;
-  if (aMajor !== bMajor) {
-    return aMajor > bMajor;
+  for (const [x, y] of a.core.map((n, i) => [n, b.core[i] ?? 0])) {
+    if (x !== y) {
+      return x > y;
+    }
   }
-  if (aMinor !== bMinor) {
-    return aMinor > bMinor;
+  if (a.pre === null || b.pre === null) {
+    return a.pre === null && b.pre !== null;
   }
-  return aPatch > bPatch;
+  return a.pre > b.pre;
 }
 function printUpdateNotice(currentVersion) {
   if (disabled()) {
     return;
   }
-  const cache = readCache();
+  const channel = channelOf(currentVersion);
+  const cache = readCache(channel);
   if (!(cache && isNewerVersion(cache.latest, currentVersion))) {
     return;
   }
+  const spec = channel === "next" ? `${PACKAGE}@next` : PACKAGE;
   console.error(
-    `zkao: version ${cache.latest} is available (running ${currentVersion}). Update with \`npm install -g ${PACKAGE}\`. If you are an agent working from a zkao skill file, update that too: it may describe fewer commands than the API now offers.`
+    `zkao: version ${cache.latest} is available (running ${currentVersion}). Update with \`npm install -g ${spec}\`. If you are an agent working from a zkao skill file, update that too: it may describe fewer commands than the API now offers.`
   );
 }
-async function refreshUpdateCache() {
+async function refreshUpdateCache(currentVersion) {
   if (disabled()) {
     return;
   }
-  const cache = readCache();
+  const channel = channelOf(currentVersion);
+  const cache = readCache(channel);
   if (cache && Date.now() - cache.checkedAtMs < CHECK_INTERVAL_MS) {
     return;
   }
-  const keepPrevious = () => writeCache({ checkedAtMs: Date.now(), latest: cache?.latest ?? "" });
+  const keepPrevious = () => writeCache({ checkedAtMs: Date.now(), latest: cache?.latest ?? "", channel });
   try {
-    const res = await fetch(`https://registry.npmjs.org/${PACKAGE}/latest`, {
+    const res = await fetch(`https://registry.npmjs.org/${PACKAGE}/${channel}`, {
       headers: { accept: "application/json" },
       signal: AbortSignal.timeout(REGISTRY_TIMEOUT_MS)
     });
@@ -372,7 +553,7 @@ async function refreshUpdateCache() {
       keepPrevious();
       return;
     }
-    writeCache({ checkedAtMs: Date.now(), latest: body.version });
+    writeCache({ checkedAtMs: Date.now(), latest: body.version, channel });
   } catch (err) {
     debug("could not reach the npm registry", err);
     keepPrevious();
@@ -390,11 +571,16 @@ function fail(message) {
   console.error(message);
   process.exit(1);
 }
-function client() {
+function globalConfig() {
   const g = program.opts();
-  const cfg = resolveConfig({ token: g.token, projectId: g.project, baseUrl: g.baseUrl });
+  return resolveConfig({ token: g.token, projectId: g.project, baseUrl: g.baseUrl });
+}
+function client() {
+  const cfg = globalConfig();
   if (!cfg.token) {
-    fail("No API token. Pass --token, set ZKAO_API_TOKEN, or run `zkao config set --token <token>`.");
+    fail(
+      cfg.projectId ? `No saved credentials for project ${cfg.projectId}. Run \`zkao login --project ${cfg.projectId}\`, or pass --token / set ZKAO_API_TOKEN.` : "No API token. Run `zkao login`, pass --token, or set ZKAO_API_TOKEN."
+    );
   }
   if (!cfg.projectId) {
     fail("No project id. Pass --project, set ZKAO_PROJECT_ID, or run `zkao config set --project <id>`.");
@@ -453,8 +639,28 @@ program.command("login").description(
     });
   }
 );
+program.command("whoami").description("Show which project and organization the current token belongs to").action(async () => {
+  const cfg = globalConfig();
+  if (!cfg.token) {
+    fail("No API token. Run `zkao login`, pass --token, or set ZKAO_API_TOKEN.");
+  }
+  try {
+    const info = await getTokenInfo({ token: cfg.token, baseUrl: cfg.baseUrl });
+    if (cfg.projectId && cfg.projectId !== info.project.id) {
+      console.error(
+        `zkao: this token belongs to project ${info.project.id}, not the configured ${cfg.projectId}.`
+      );
+    }
+    out(info);
+  } catch (err) {
+    if (err instanceof ZkaoApiError) {
+      fail(`Error ${err.status} (${err.code}): ${err.message}`);
+    }
+    throw err;
+  }
+});
 var config = program.command("config").description("Manage stored credentials");
-config.command("set").description(`Persist settings to ${configPath()}`).option("--token <token>", "project API token").option("--project <id>", "project id").option("--base-url <url>", "API base URL").action((opts) => {
+config.command("set").description(`Persist settings to ${configPath()}`).option("--token <token>", "project API token").option("--project <id>", "project id").option("--base-url <url>", "API base URL").action(async (opts) => {
   const g = program.opts();
   const update = {
     token: opts.token ?? g.token,
@@ -464,17 +670,52 @@ config.command("set").description(`Persist settings to ${configPath()}`).option(
   if (update.token === void 0 && update.projectId === void 0 && update.baseUrl === void 0) {
     fail("Nothing to save. Pass --token, --project, or --base-url.");
   }
+  if (update.token !== void 0 && update.projectId === void 0) {
+    const baseUrl = resolveConfig({ baseUrl: update.baseUrl }).baseUrl;
+    try {
+      const info = await getTokenInfo({ token: update.token, baseUrl });
+      const names = {
+        name: info.project.name,
+        organization: info.project.organization.name
+      };
+      saveProjectCredentials(info.project.id, { token: update.token, baseUrl, ...names });
+      console.log(
+        `Saved to ${configPath()}. Active project: ${describeProject(info.project.id, names)}`
+      );
+      return;
+    } catch (err) {
+      console.error(
+        `zkao: could not look up the token's project (${err instanceof Error ? err.message : String(err)}); saving it without one.`
+      );
+    }
+  }
   writeConfig(update);
   console.log(`Saved to ${configPath()}`);
 });
 config.command("show").description("Show the resolved settings (token masked)").action(() => {
   const cfg = resolveConfig({});
+  const { activeProjectId, projects } = savedProjects();
   out({
     token: cfg.token ? `${cfg.token.slice(0, 14)}\u2026` : null,
     projectId: cfg.projectId ?? null,
-    baseUrl: cfg.baseUrl ?? "https://zkao.io/api/v1 (default)"
+    baseUrl: cfg.baseUrl ?? "https://zkao.io/api/v1 (default)",
+    savedProjects: Object.entries(projects).map(([id, saved]) => ({
+      projectId: id,
+      name: saved.name ?? null,
+      organization: saved.organization ?? null,
+      baseUrl: saved.baseUrl ?? "https://zkao.io/api/v1 (default)",
+      active: id === activeProjectId
+    }))
   });
 });
+config.command("use <projectId>").description("Switch the active project to one with saved credentials").action((projectId) => {
+  try {
+    const saved = useProject(projectId);
+    console.log(`Active project: ${describeProject(projectId, saved)}`);
+  } catch (err) {
+    fail(err instanceof Error ? err.message : String(err));
+  }
+});
 program.command("repos").description("List repositories in the project").action(() => run((c) => c.listRepositories()));
 program.command("repos:wait <repositoryId>").description("Wait until a repository is ready to scan").option("--timeout <ms>", "give up after this long", toInt).action(
   (repositoryId, opts) => run(
@@ -542,7 +783,14 @@ scans.command("wait <scanId>").description("Poll a scan until it finishes (honor
     }).finally(() => process.removeListener("SIGINT", onSigint))
   );
 });
-scans.command("launch").description("Launch a scan").requiredOption("--repo <id>", "repository id").requiredOption("--budget <credits>", "max budget, in credits", toInt).option("--preset <ref>", "scan preset ref (see `zkao presets`)").option("--branch <name>", "branch to scan").option("--commit <sha>", "specific commit to scan").option("--message <text>", "commit message (metadata)").option("--flow <id>", "optional-flow id to opt into (repeatable)", collect, []).option(
+scans.command("launch").description("Launch a scan").requiredOption("--repo <id>", "repository id").option(
+  "--budget <credits>",
+  "max budget, in credits (default: the budget zkao recommends for this scan type on this repository)",
+  toInt
+).option("--preset <ref>", "scan preset ref (see `zkao presets`)").option("--branch <name>", "branch to scan").option("--commit <sha>", "specific commit to scan").option(
+  "--base <ref>",
+  "base commit or ref of a diff scan; the scan audits only the change from it (requires a diff preset)"
+).option("--message <text>", "commit message (metadata)").option(
   "--guidance <file|->",
   "per-scan guidance from a file (or - for stdin); replaces the repo's guidance for this scan"
 ).option(
@@ -558,8 +806,8 @@ scans.command("launch").description("Launch a scan").requiredOption("--repo <id>
       presetRef: opts.preset,
       branch: opts.branch ?? null,
       commitHash: opts.commit ?? null,
+      baseCommit: opts.base,
       commitMessage: opts.message ?? null,
-      optInFlowIds: opts.flow.length > 0 ? opts.flow : void 0,
       auditAreaKeys: opts.area.length > 0 ? opts.area : void 0,
       ...opts.guidance !== void 0 ? { guidance: readContentArg(opts.guidance) } : {}
     };
@@ -594,16 +842,30 @@ findings.command("resolution <findingId> <status>").description("Set resolution
 findings.command("publish <findingId>").description("Publish a finding as a public artifact").option("--note <noteId>", "note to pin as the published note").option("--password", "generate an access password").action(
   (findingId, opts) => run((c) => c.publishFinding(findingId, { noteId: opts.note, withPassword: opts.password }))
 );
-var billing = program.command("billing").description("Read the project's credit balance and usage");
-billing.command("balance").description("Credit balance, what active scans hold, and what is available").action(() => run((c) => c.getBillingBalance()));
+var billing = program.command("billing").description("Read the credit balance available to the project and its usage");
+billing.command("balance").description("The organization's shared credit balance, what active scans hold, and what is available").action(() => run((c) => c.getBillingBalance()));
 billing.command("usage").description("Credit ledger movements (defaults to the last 30 days)").option("--from <date>", "ISO date or timestamp to start from").option("--to <date>", "ISO date or timestamp to stop at").option("--limit <n>", "max events to return", toInt).action(
   (opts) => run((c) => c.getBillingUsage(opts))
 );
 billing.command("summary").description("Per-month credits spent and purchased, newest first").option("--months <n>", "how many months to return", toInt).action(
   (opts) => run((c) => c.getBillingSummary({ months: opts.months }))
 );
+var admin = program.command("admin", { hidden: true }).description("Site-admin operations on the project");
+admin.command("manual-audit").description("Record a zkSecurity audit report as a manual audit").requiredOption("--repo <id>", "repository id").requiredOption("--commit <sha>", "commit the audit reviewed").requiredOption(
+  "--findings <file|->",
+  "findings YAML (report-tool: `just export-findings <slug>`)"
+).option("--report <file|->", "report body markdown (report-tool: `just export-overview <slug>`)").option("--commit-message <text>", "commit message to show with the commit").action(
+  (opts) => run(
+    (c) => c.createManualAudit({
+      repositoryId: opts.repo,
+      commitHash: opts.commit,
+      findingsYaml: readContentArg(opts.findings),
+      reportMarkdown: opts.report === void 0 ? null : readContentArg(opts.report),
+      commitMessage: opts.commitMessage ?? null
+    })
+  )
+);
 program.command("presets").description("List scan presets the project can launch").action(() => run((c) => c.listScanPresets()));
-program.command("flows").description("List opt-in flows available at launch").action(() => run((c) => c.listOptionalFlows()));
 function errorMessage(err) {
   if (err instanceof AggregateError && err.errors.length > 0) {
     return err.errors.map(errorMessage).join("; ");
@@ -615,7 +877,7 @@ function errorMessage(err) {
   return err.cause ? `${message}: ${errorMessage(err.cause)}` : message;
 }
 printUpdateNotice(version);
-program.parseAsync().then(() => refreshUpdateCache()).catch((err) => {
+program.parseAsync().then(() => refreshUpdateCache(version)).catch((err) => {
   console.error(errorMessage(err));
   process.exit(1);
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zksecurity/zkao-cli",
-  "version": "0.5.1",
+  "version": "0.11.0-next.2",
   "description": "Command-line interface for the zkao Project API",
   "license": "MIT",
   "author": "zkSecurity",
@@ -39,7 +39,7 @@
     "prepublishOnly": "node -e \"if (!(process.env.npm_config_user_agent || '').includes('bun/')) { console.error('Publish with bun publish: npm ships the literal workspace:* dependency and breaks installs.'); process.exit(1); }\""
   },
   "dependencies": {
-    "@zksecurity/zkao-sdk": "0.5.1",
+    "@zksecurity/zkao-sdk": "0.11.0-next.2",
     "commander": "^12.1.0"
   },
   "devDependencies": {