run402 3.7.14 → 3.8.1

package/lib/credentials.mjs

@@ -0,0 +1,273 @@
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+import {
+  activeProfile,
+  getProject,
+  loadKeyStore,
+  projectCredentialsFile,
+  removeProject,
+  saveProject,
+} from "./config.mjs";
+import { assertKnownFlags, flagValue, normalizeArgv, positionalArgs } from "./argparse.mjs";
+import { fail } from "./sdk-errors.mjs";
+
+const HELP = `run402 credentials — Manage local credential material
+
+Usage:
+  run402 credentials <subcommand> [args...]
+
+Subcommands:
+  project-keys  Manage the local project-key cache
+
+Examples:
+  run402 credentials project-keys list
+  run402 credentials project-keys status --project prj_abc123
+  run402 credentials project-keys import --project prj_abc123 --service-key-stdin
+  run402 credentials project-keys export --project prj_abc123 --reveal
+`;
+
+const PROJECT_KEYS_HELP = `run402 credentials project-keys — Manage local project-key cache entries
+
+Usage:
+  run402 credentials project-keys <subcommand> [options]
+
+Subcommands:
+  list                                List cached project-key entries, redacted
+  status --project <id>               Show one cached entry, redacted
+  import --project <id> --service-key-stdin
+  import --project <id> --service-key-env <env>
+  export --project <id> --reveal       Print cached keys, including secrets
+  remove --project <id>                Remove one cached key entry
+
+Notes:
+  - This is a LOCAL CACHE surface. It is not project inventory.
+  - list/status never reveal full keys.
+  - export requires --reveal.
+  - import accepts service keys through stdin or an environment variable, not argv.
+`;
+
+function parseProjectKeyFlags(args, extraKnown = [], valueFlagsExtra = []) {
+  const parsed = normalizeArgv(args);
+  const valueFlags = ["--project", ...valueFlagsExtra];
+  assertKnownFlags(parsed, ["--project", "--help", "-h", ...extraKnown], valueFlags);
+  return {
+    projectId: flagValue(parsed, "--project"),
+    parsed,
+    rest: positionalArgs(parsed, valueFlags),
+  };
+}
+
+function fingerprint(value) {
+  if (!value) return null;
+  return createHash("sha256").update(value).digest("hex").slice(0, 16);
+}
+
+function prefix(value) {
+  if (!value) return null;
+  return `${value.slice(0, 8)}...`;
+}
+
+function provenance() {
+  const profile = activeProfile();
+  return {
+    source: "local_cache",
+    cache_path: projectCredentialsFile(),
+    wallet: profile,
+    profile,
+  };
+}
+
+function redactedEntry(projectId, entry) {
+  return {
+    project_id: projectId,
+    configured: Boolean(entry),
+    has_anon_key: Boolean(entry?.anon_key),
+    has_service_key: Boolean(entry?.service_key),
+    anon_key_prefix: prefix(entry?.anon_key),
+    service_key_prefix: prefix(entry?.service_key),
+    anon_key_fingerprint: fingerprint(entry?.anon_key),
+    service_key_fingerprint: fingerprint(entry?.service_key),
+    site_url: entry?.site_url ?? null,
+    cached_at: entry?.cached_at ?? null,
+    ...provenance(),
+  };
+}
+
+function requireProjectFlag(projectId, usage) {
+  if (!projectId) {
+    fail({
+      code: "BAD_USAGE",
+      message: "Missing --project <id>.",
+      hint: usage,
+    });
+  }
+  return projectId;
+}
+
+function requireCachedProject(projectId) {
+  const entry = getProject(projectId);
+  if (!entry) {
+    fail({
+      code: "PROJECT_CREDENTIAL_NOT_FOUND",
+      message: `No local project credentials cached for ${projectId}.`,
+      hint: "Import keys with `run402 credentials project-keys import --project <id> --service-key-stdin` if this operation truly requires local project credentials.",
+      details: { project_id: projectId, ...provenance() },
+      next_actions: [{
+        type: "run_command",
+        command: `run402 credentials project-keys import --project ${projectId} --service-key-stdin`,
+        why: "Import a service key for credential-required operations.",
+      }],
+    });
+  }
+  return entry;
+}
+
+async function list(args) {
+  const { rest } = parseProjectKeyFlags(args);
+  if (rest.length > 0) {
+    fail({ code: "BAD_USAGE", message: `Unexpected argument for project-keys list: ${rest[0]}` });
+  }
+  const store = loadKeyStore(projectCredentialsFile());
+  const projects = Object.entries(store.projects ?? {})
+    .sort(([a], [b]) => a.localeCompare(b))
+    .map(([projectId, entry]) => redactedEntry(projectId, entry));
+  console.log(JSON.stringify({ projects, ...provenance() }, null, 2));
+}
+
+async function status(args) {
+  const { projectId, rest } = parseProjectKeyFlags(args);
+  if (rest.length > 0) {
+    fail({ code: "BAD_USAGE", message: `Unexpected argument for project-keys status: ${rest[0]}` });
+  }
+  const id = requireProjectFlag(projectId, "run402 credentials project-keys status --project <id>");
+  console.log(JSON.stringify(redactedEntry(id, getProject(id)), null, 2));
+}
+
+function readSecretInput(parsed) {
+  const fromEnv = flagValue(parsed, "--service-key-env");
+  const fromStdin = parsed.includes("--service-key-stdin");
+  if (fromEnv && fromStdin) {
+    fail({ code: "BAD_USAGE", message: "Use either --service-key-env or --service-key-stdin, not both." });
+  }
+  if (fromEnv) {
+    const value = process.env[fromEnv];
+    if (!value) {
+      fail({
+        code: "BAD_ENV",
+        message: `Environment variable ${fromEnv} is empty or unset.`,
+        details: { env: fromEnv },
+      });
+    }
+    return value.trim();
+  }
+  if (fromStdin) return readFileSync(0, "utf-8").trim();
+  fail({
+    code: "BAD_USAGE",
+    message: "Import requires --service-key-stdin or --service-key-env <env>.",
+    hint: "Do not pass service keys as command-line values; argv can leak through shell history and process listings.",
+  });
+}
+
+async function importKey(args) {
+  const { projectId, parsed, rest } = parseProjectKeyFlags(
+    args,
+    ["--service-key-stdin", "--service-key-env", "--anon-key-env"],
+    ["--service-key-env", "--anon-key-env"],
+  );
+  if (rest.length > 0) {
+    fail({ code: "BAD_USAGE", message: `Unexpected argument for project-keys import: ${rest[0]}` });
+  }
+  const id = requireProjectFlag(projectId, "run402 credentials project-keys import --project <id> --service-key-stdin");
+  const serviceKey = readSecretInput(parsed);
+  if (!serviceKey) {
+    fail({ code: "BAD_USAGE", message: "Service key input was empty." });
+  }
+  const anonEnv = flagValue(parsed, "--anon-key-env");
+  const anonKey = anonEnv ? process.env[anonEnv] : undefined;
+  if (anonEnv && !anonKey) {
+    fail({ code: "BAD_ENV", message: `Environment variable ${anonEnv} is empty or unset.`, details: { env: anonEnv } });
+  }
+  const existing = getProject(id);
+  saveProject(id, {
+    anon_key: anonKey ?? existing?.anon_key ?? "",
+    service_key: serviceKey,
+    site_url: existing?.site_url,
+    deployed_at: existing?.deployed_at,
+    last_deployment_id: existing?.last_deployment_id,
+    source: "manual_import",
+    cached_at: new Date().toISOString(),
+  });
+  console.log(JSON.stringify({ imported: true, ...redactedEntry(id, getProject(id)) }, null, 2));
+}
+
+async function exportKey(args) {
+  const { projectId, parsed, rest } = parseProjectKeyFlags(args, ["--reveal"]);
+  if (rest.length > 0) {
+    fail({ code: "BAD_USAGE", message: `Unexpected argument for project-keys export: ${rest[0]}` });
+  }
+  const id = requireProjectFlag(projectId, "run402 credentials project-keys export --project <id> --reveal");
+  if (!parsed.includes("--reveal")) {
+    fail({
+      code: "REVEAL_REQUIRED",
+      message: "Exporting full project keys requires --reveal.",
+      hint: "Use `run402 credentials project-keys status --project <id>` for redacted output.",
+      details: { project_id: id, ...provenance() },
+    });
+  }
+  const entry = requireCachedProject(id);
+  console.log(JSON.stringify({ project_id: id, ...entry, ...provenance(), revealed: true }, null, 2));
+}
+
+async function remove(args) {
+  const { projectId, rest } = parseProjectKeyFlags(args);
+  if (rest.length > 0) {
+    fail({ code: "BAD_USAGE", message: `Unexpected argument for project-keys remove: ${rest[0]}` });
+  }
+  const id = requireProjectFlag(projectId, "run402 credentials project-keys remove --project <id>");
+  const existed = Boolean(getProject(id));
+  removeProject(id, projectCredentialsFile());
+  console.log(JSON.stringify({ project_id: id, removed: existed, ...provenance() }, null, 2));
+}
+
+async function runProjectKeys(sub, args) {
+  if (!sub || sub === "--help" || sub === "-h") {
+    console.log(PROJECT_KEYS_HELP);
+    process.exit(0);
+  }
+  if (Array.isArray(args) && (args.includes("--help") || args.includes("-h"))) {
+    console.log(PROJECT_KEYS_HELP);
+    process.exit(0);
+  }
+  switch (sub) {
+    case "list": await list(args); break;
+    case "status": await status(args); break;
+    case "import": await importKey(args); break;
+    case "export": await exportKey(args); break;
+    case "remove": await remove(args); break;
+    default:
+      fail({
+        code: "UNKNOWN_SUBCOMMAND",
+        message: `Unknown credentials project-keys subcommand: ${sub}`,
+        hint: "Run `run402 credentials project-keys --help` for usage.",
+        details: { command: "credentials project-keys", subcommand: sub },
+      });
+  }
+}
+
+export async function run(sub, args = []) {
+  if (!sub || sub === "--help" || sub === "-h") {
+    console.log(HELP);
+    process.exit(0);
+  }
+  if (sub === "project-keys") {
+    const [projectKeySub, ...rest] = Array.isArray(args) ? args : [];
+    await runProjectKeys(projectKeySub, rest);
+    return;
+  }
+  fail({
+    code: "UNKNOWN_SUBCOMMAND",
+    message: `Unknown credentials subcommand: ${sub}`,
+    hint: "Run `run402 credentials --help` for usage.",
+    details: { command: "credentials", subcommand: sub },
+  });
+}

package/lib/deploy-v2.mjs

@@ -38,6 +38,7 @@ import { normalizeArgv } from "./argparse.mjs";
 import { loadLiveControlPlaneSession } from "../core-dist/control-plane-session.js";
 import { withAutoApprove } from "./operator.mjs";
 import { editRequestAction, nextAction, retryAction } from "./next-actions.mjs";
+import { createUpdateCheckScheduler, emitUpdateNotice } from "./update-check.mjs";
 
 const APPLY_HELP = `run402 deploy apply — Unified deploy primitive (v1.34+)
 
@@ -444,6 +445,7 @@ function parsePromoteArgs(args) {
 
 async function promoteCmd(args) {
   const opts = parsePromoteArgs(args);
+  emitDeployUpdateNotice("promote", args, { quiet: opts.quiet });
   const projectId = opts.project ?? resolveProjectId(null);
 
   // Preserve the aggressive early-exit when no allowance is configured
@@ -500,6 +502,13 @@ function makeStderrEventWriter(quiet) {
   };
 }
 
+function emitDeployUpdateNotice(subcommand, args, { quiet = false } = {}) {
+  const scheduler = createUpdateCheckScheduler({
+    command: ["run402", "deploy", subcommand, ...args],
+  });
+  emitUpdateNotice(scheduler.cachedNotice, { quiet });
+}
+
 function parseApplyArgs(args) {
   const opts = {
     manifest: null,
@@ -787,6 +796,7 @@ async function applyCmd(args) {
   const opts = parseApplyArgs(args);
   const { source, error: sourceError } = resolveApplySource(opts, hasStdinSource());
   if (sourceError) fail(sourceError);
+  emitDeployUpdateNotice("apply", args, { quiet: opts.quiet });
 
   let raw;
   let manifestPath = null;
@@ -1377,6 +1387,7 @@ async function resumeCmd(args) {
     project: parsed.flags["--project"] ?? null,
     quiet: Boolean(parsed.flags["--quiet"]),
   };
+  emitDeployUpdateNotice("resume", args, { quiet: opts.quiet });
   const project = resolveProjectId(opts.project);
 
   allowanceAuthHeaders("/apply/v1/operations");

package/lib/doctor.mjs

@@ -19,22 +19,25 @@ import {
   scanSourceTree,
   SCAN_SEVERITY,
 } from "./doctor-source-scan.mjs";
+import { doctorUpdateCheck } from "./update-check.mjs";
 
 const HELP = `run402 doctor — Health and config diagnostics
 
 Usage:
-  run402 doctor [--verbose] [--no-scan] [--scan-dir <D>]
+  run402 doctor [--verbose] [--refresh] [--no-scan] [--scan-dir <D>]
 
 Output:
   Stdout is a JSON report { ok, checks: [{ name, status, value?, hint?, message? }] }.
 
 Options:
   --verbose      Include extra detail (timing, error messages)
+  --refresh      Wait for a bounded live npm version check for the run402 CLI
   --no-scan      Skip the source-tree scan (config / health checks only)
   --scan-dir D   Scan a custom directory instead of \`<cwd>/src\`
 
 Checks performed:
   - Config directory exists and is writable
+  - Installed run402 CLI version and update guidance
   - Allowance is configured and on a valid rail (x402 / mpp)
   - Keystore has at least one wallet
   - API_BASE is reachable (network check via /health)
@@ -60,6 +63,7 @@ export async function run(sub, args = []) {
     return;
   }
   const verbose = all.includes("--verbose");
+  const refresh = all.includes("--refresh");
   const skipScan = all.includes("--no-scan");
   const scanDirArgIdx = all.indexOf("--scan-dir");
   const scanDirOverride = scanDirArgIdx >= 0 ? all[scanDirArgIdx + 1] : null;
@@ -87,6 +91,18 @@ export async function run(sub, args = []) {
     });
   }
 
+  // 1b. CLI version/update state. This is advisory: stale or unknown version
+  // state should help the user, not hide the rest of doctor.
+  try {
+    checks.push(await doctorUpdateCheck({ refresh }));
+  } catch (err) {
+    checks.push({
+      name: "cli_update",
+      status: "unknown",
+      message: err instanceof Error ? err.message : String(err),
+    });
+  }
+
   // 2. Allowance.
   try {
     const allowance = readAllowance();
@@ -324,7 +340,7 @@ export async function run(sub, args = []) {
   // 'warning' counts as ok for exit-code purposes — gaps are surfaced in
   // output but don't fail the doctor. Only hard 'error' / 'missing' /
   // 'empty' fail.
-  const allOk = checks.every((c) => c.status === "ok" || c.status === "warning" || c.status === "skipped");
+  const allOk = checks.every((c) => c.status === "ok" || c.status === "warning" || c.status === "skipped" || c.status === "unknown");
 
   console.log(JSON.stringify({ ok: allOk, checks }, null, 2));
   process.exit(allOk ? 0 : 1);

package/lib/domains.mjs

@@ -9,14 +9,15 @@ Usage:
   run402 domains <subcommand> [args...]
 
 Subcommands:
-  add    <domain> <subdomain_name> [--project <id>]   Register a custom domain
-  list   [--project <id>]                              List custom domains for a project
-  status <domain> [--project <id>]                     Check domain DNS/SSL status
-  delete <domain> --confirm [--project <id>]           Release a custom domain. Requires --confirm.
+  add    <domain> <subdomain_name> [--project <id>] [--auth principal|service-key]
+  list   [--project <id>] [--auth principal|service-key]
+  status <domain> [--project <id>] [--auth principal|service-key]
+  delete <domain> --confirm [--project <id>] [--auth principal|service-key]
 
 Examples:
   run402 domains add example.com myapp
-  run402 domains add example.com myapp --project prj_123
+	  run402 domains add example.com myapp --project prj_123
+	  run402 domains list --project prj_123 --auth service-key
   run402 domains list
   run402 domains status example.com
   run402 domains delete example.com --confirm
@@ -31,7 +32,7 @@ const SUB_HELP = {
   add: `run402 domains add — Register a custom domain for a project
 
 Usage:
-  run402 domains add <domain> <subdomain_name> [--project <id>]
+  run402 domains add <domain> <subdomain_name> [--project <id>] [--auth principal|service-key]
 
 Arguments:
   <domain>            Custom domain (e.g. example.com)
@@ -39,6 +40,8 @@ Arguments:
 
 Options:
   --project <id>      Project ID (defaults to the active project)
+  --auth <mode>       principal (default, server-authoritative) or service-key
+                      (uses local project-key cache)
 
 Notes:
   - After adding, configure DNS as shown in the response
@@ -52,10 +55,14 @@ Examples:
   list: `run402 domains list — List custom domains for a project
 
 Usage:
-  run402 domains list [--project <id>]
+  run402 domains list [--project <id>] [--auth principal|service-key]
 
-Arguments:
-  <id>                Project ID (defaults to the active project)
+	Arguments:
+	  <id>                Project ID (defaults to the active project)
+
+Options:
+  --auth <mode>       principal (default, server-authoritative) or service-key
+                      (uses local project-key cache)
 
 Examples:
   run402 domains list
@@ -64,13 +71,15 @@ Examples:
   status: `run402 domains status — Check DNS/SSL status of a custom domain
 
 Usage:
-  run402 domains status <domain> [--project <id>]
+  run402 domains status <domain> [--project <id>] [--auth principal|service-key]
 
 Arguments:
   <domain>            Custom domain to check
 
 Options:
   --project <id>      Project ID (defaults to the active project)
+  --auth <mode>       principal (default, server-authoritative) or service-key
+                      (uses local project-key cache)
 
 Examples:
   run402 domains status example.com
@@ -79,7 +88,7 @@ Examples:
   delete: `run402 domains delete — Release a custom domain
 
 Usage:
-  run402 domains delete <domain> --confirm [--project <id>]
+  run402 domains delete <domain> --confirm [--project <id>] [--auth principal|service-key]
 
 Arguments:
   <domain>            Custom domain to release
@@ -89,6 +98,8 @@ Options:
                       project and clears its DNS/SSL configuration
                       (irreversible)
   --project <id>      Project ID (defaults to the active project)
+  --auth <mode>       principal (default, server-authoritative) or service-key
+                      (uses local project-key cache)
 
 Examples:
   run402 domains delete example.com --confirm
@@ -97,17 +108,26 @@ Examples:
 
 function parseProjectFlag(args, extraKnown = []) {
   const parsedArgs = normalizeArgv(args);
-  const valueFlags = ["--project"];
+  const valueFlags = ["--project", "--auth"];
   assertKnownFlags(parsedArgs, [...valueFlags, ...extraKnown, "--help", "-h"], valueFlags);
+  const auth = flagValue(parsedArgs, "--auth") ?? "principal";
+  if (auth !== "principal" && auth !== "service-key") {
+    fail({
+      code: "BAD_FLAG",
+      message: "--auth must be one of: principal, service-key.",
+      details: { flag: "--auth", value: auth, allowed: ["principal", "service-key"] },
+    });
+  }
   return {
     project: flagValue(parsedArgs, "--project"),
+    authMode: auth === "service-key" ? "service_key" : "principal",
     rest: positionalArgs(parsedArgs, valueFlags),
     args: parsedArgs,
   };
 }
 
 async function add(args) {
-  const { project, rest } = parseProjectFlag(args);
+  const { project, authMode, rest } = parseProjectFlag(args);
   const domain = rest[0];
   const subdomainName = rest[1];
   if (!domain || !subdomainName) {
@@ -122,7 +142,7 @@ async function add(args) {
   }
   const projectId = resolveProjectId(project);
   try {
-    const data = await getSdk().domains.add(projectId, { domain, subdomainName });
+    const data = await getSdk().domains.add(projectId, { domain, subdomainName, authMode });
     console.log(JSON.stringify(data, null, 2));
   } catch (err) {
     reportSdkError(err);
@@ -131,7 +151,7 @@ async function add(args) {
 
 async function list(args) {
   const argList = Array.isArray(args) ? args : [];
-  const { project, rest } = parseProjectFlag(argList);
+  const { project, authMode, rest } = parseProjectFlag(argList);
   if (rest.length > 0) {
     fail({
       code: "BAD_USAGE",
@@ -141,7 +161,7 @@ async function list(args) {
   }
   const projectId = resolveProjectId(project);
   try {
-    const data = await getSdk().domains.list(projectId);
+    const data = await getSdk().domains.list(projectId, { authMode });
     console.log(JSON.stringify(data, null, 2));
   } catch (err) {
     reportSdkError(err);
@@ -149,7 +169,7 @@ async function list(args) {
 }
 
 async function status(args) {
-  const { project, rest } = parseProjectFlag(args);
+  const { project, authMode, rest } = parseProjectFlag(args);
   const domain = rest[0];
   if (!domain) {
     fail({
@@ -163,7 +183,7 @@ async function status(args) {
   }
   const projectId = resolveProjectId(project);
   try {
-    const data = await getSdk().domains.status(projectId, domain);
+    const data = await getSdk().domains.status(projectId, domain, { authMode });
     console.log(JSON.stringify(data, null, 2));
   } catch (err) {
     reportSdkError(err);
@@ -171,7 +191,7 @@ async function status(args) {
 }
 
 async function deleteDomain(args) {
-  const { project, rest, args: parsedArgs } = parseProjectFlag(args, ["--confirm"]);
+  const { project, authMode, rest, args: parsedArgs } = parseProjectFlag(args, ["--confirm"]);
   const domain = rest[0];
   if (!domain) {
     fail({
@@ -192,7 +212,7 @@ async function deleteDomain(args) {
   }
   const projectId = resolveProjectId(project);
   try {
-    await getSdk().domains.remove(domain, { projectId });
+    await getSdk().domains.remove(domain, { projectId, authMode });
     console.log(JSON.stringify({ domain, project_id: projectId, released: true }));
   } catch (err) {
     reportSdkError(err);

package/lib/next-actions.mjs

@@ -46,6 +46,13 @@ export function createProjectAction() {
   });
 }
 
+export function selectProjectAction() {
+  return nextAction("edit_request", {
+    command: "run402 projects use <project_id>",
+    why: "Select a server-visible project, or pass --project <project_id> on the command.",
+  });
+}
+
 export function setTierAction(tier = "prototype") {
   return nextAction("renew_tier", {
     command: `run402 tier set ${tier}`,