run402 2.10.0 → 2.11.0

package/cli.mjs

@@ -46,6 +46,10 @@ Commands:
   contracts   KMS contract wallets ($0.04/day rental + $0.000005/sign)
   agent       Manage agent identity (contact info)
   service     Run402 service health and availability (status, health)
+  cache       Inspect and invalidate the SSR origin cache (inspect, invalidate)
+  doctor      Health and config diagnostics (machine-readable with --json)
+  dev         Run Astro dev with Run402 env + credentials in scope
+  logs        Fetch function logs by request id (--request-id req_...)
 
 Run 'run402 <command> --help' for detailed usage of each command.
 
@@ -226,6 +230,26 @@ switch (cmd) {
     await run(sub, rest);
     break;
   }
+  case "cache": {
+    const { run } = await import("./lib/cache.mjs");
+    await run(sub, rest);
+    break;
+  }
+  case "doctor": {
+    const { run } = await import("./lib/doctor.mjs");
+    await run(sub, rest);
+    break;
+  }
+  case "logs": {
+    const { run } = await import("./lib/logs.mjs");
+    await run(sub, rest);
+    break;
+  }
+  case "dev": {
+    const { run } = await import("./lib/dev.mjs");
+    await run(sub, rest);
+    break;
+  }
   default:
     console.error(`Unknown command: ${cmd}\n`);
     console.log(HELP);

package/lib/cache.mjs

@@ -0,0 +1,264 @@
+/**
+ * run402 cache — SSR cache inspection and invalidation.
+ *
+ * Capability `ssr-isr-cache` (Run402 v1.52). Used by AI coding agents
+ * and human developers to:
+ *
+ *   - Inspect the cache row state for a URL (`cache inspect`)
+ *   - Invalidate a specific URL, prefix, or entire host (`cache invalidate`)
+ *
+ * Both subcommands are project-scoped: the active project id is read
+ * from the SDK config, and any host referenced MUST be owned by that
+ * project (subdomain `*.run402.com` or attached custom domain). The
+ * gateway returns `R402_CACHE_INVALIDATION_HOST_FORBIDDEN` for
+ * cross-project attempts; the CLI surfaces that as a structured error.
+ *
+ * @see https://docs.run402.com/cache/concepts
+ */
+
+import { getSdk } from "./sdk.mjs";
+import { reportSdkError, fail } from "./sdk-errors.mjs";
+import { assertKnownFlags, flagValue, normalizeArgv } from "./argparse.mjs";
+
+// Locally-defined helpers — argparse.mjs's normalized form is a flat
+// string array; we need to identify positional args (non-flag, non-flag-
+// value tokens) and detect flag presence.
+function hasFlag(args, flags) {
+  return args.some((a) => flags.includes(a));
+}
+function positionalArgs(args) {
+  // Filter out flags (--foo) AND values that immediately follow a
+  // value-taking flag. We approximate by treating any token after a
+  // --flag as the flag's value unless it starts with --.
+  const out = [];
+  const valueTakingFlags = new Set(["--locale", "--release-id", "--prefix", "--host"]);
+  for (let i = 0; i < args.length; i++) {
+    const token = args[i];
+    if (typeof token !== "string") continue;
+    if (token.startsWith("--")) {
+      if (valueTakingFlags.has(token)) i += 1; // skip the value
+      continue;
+    }
+    out.push(token);
+  }
+  return out;
+}
+
+const HELP = `run402 cache — SSR cache inspection and invalidation
+
+Usage:
+  run402 cache <subcommand> [args...]
+
+Subcommands:
+  inspect    <url>             Inspect cache row state for a URL
+  invalidate <url>             Invalidate a specific URL
+  invalidate --prefix <p> --host <h>   Invalidate all rows under a path prefix
+  invalidate --all --host <h>          Invalidate all rows for a host
+
+Common flags:
+  --json                       Machine-readable output
+  --locale <code>              (inspect only) Inspect a specific locale's row
+                               (default: project's default locale)
+  --release-id <id>            (inspect only) Inspect a specific release id
+                               (default: project's active release)
+
+Examples:
+  run402 cache inspect https://eagles.kychon.com/the-guys
+  run402 cache inspect https://eagles.kychon.com/the-guys --locale es --json
+  run402 cache invalidate https://eagles.kychon.com/the-guys
+  run402 cache invalidate --prefix /blog/ --host eagles.kychon.com
+  run402 cache invalidate --all --host eagles.kychon.com
+
+Notes:
+  - The cache key is canonicalized (case-preserving query, ignored fragments,
+    repeated-key ordering preserved). See the cache concepts doc for the
+    canonical-key formula.
+  - 'inspect' returns HIT (a fresh row exists) or MISS (no fresh row). It
+    NEVER returns BYPASS — BYPASS is a runtime decision based on incoming
+    request properties (cookies, auth headers, etc.), and inspect does not
+    issue a request.
+  - Invalidation is generation-guarded: an in-flight MISS render started
+    before the invalidate will NOT overwrite the freshly-cleared state.
+`;
+
+export async function run(sub, args) {
+  if (!sub || sub === "--help" || sub === "-h") {
+    console.log(HELP);
+    return;
+  }
+
+  switch (sub) {
+    case "inspect":
+      await inspect(args);
+      break;
+    case "invalidate":
+      await invalidate(args);
+      break;
+    default:
+      fail({
+        code: "BAD_USAGE",
+        message: `Unknown cache subcommand: ${sub}`,
+        next_actions: ["run402 cache --help"],
+      });
+  }
+}
+
+async function inspect(args) {
+  const parsed = normalizeArgv(args);
+  assertKnownFlags(parsed, ["--json", "--locale", "--release-id", "--help", "-h"]);
+  if (hasFlag(parsed, ["--help", "-h"])) {
+    console.log(HELP);
+    return;
+  }
+
+  const positionals = positionalArgs(parsed);
+  if (positionals.length === 0) {
+    fail({
+      code: "BAD_USAGE",
+      message: "Missing URL argument.",
+      next_actions: ["run402 cache inspect <url>"],
+    });
+  }
+  const url = positionals[0];
+  if (!url.startsWith("https://") && !url.startsWith("http://")) {
+    fail({
+      code: "BAD_USAGE",
+      message: `URL must be absolute (got: ${url})`,
+      next_actions: ["run402 cache inspect https://<host>/<path>"],
+    });
+  }
+
+  const locale = flagValue(parsed, "--locale");
+  const releaseId = flagValue(parsed, "--release-id");
+  const json = hasFlag(parsed, ["--json"]);
+
+  try {
+    const sdk = getSdk();
+    // SDK shape — the gateway's cache inspect endpoint isn't yet wired
+    // (separate task). For now the CLI POSTs to the same /cache/v1/
+    // namespace with kind=inspect.
+    const result = await sdk.cache.inspect(url, { locale, releaseId });
+    if (json) {
+      console.log(JSON.stringify(result, null, 2));
+    } else {
+      console.log(formatInspectResult(result));
+    }
+  } catch (err) {
+    reportSdkError(err);
+  }
+}
+
+async function invalidate(args) {
+  const parsed = normalizeArgv(args);
+  assertKnownFlags(parsed, ["--json", "--prefix", "--host", "--all", "--help", "-h"]);
+  if (hasFlag(parsed, ["--help", "-h"])) {
+    console.log(HELP);
+    return;
+  }
+
+  const positionals = positionalArgs(parsed);
+  const json = hasFlag(parsed, ["--json"]);
+  const prefix = flagValue(parsed, "--prefix");
+  const host = flagValue(parsed, "--host");
+  const all = hasFlag(parsed, ["--all"]);
+
+  const sdk = getSdk();
+
+  // Three modes: exact URL, prefix, all.
+  if (all) {
+    if (!host) {
+      fail({
+        code: "BAD_USAGE",
+        message: "--all requires --host <hostname>",
+        next_actions: ["run402 cache invalidate --all --host <hostname>"],
+      });
+    }
+    try {
+      const result = await sdk.cache.invalidateAll({ host });
+      emit(result, json);
+    } catch (err) {
+      reportSdkError(err);
+    }
+    return;
+  }
+
+  if (prefix) {
+    if (!host) {
+      fail({
+        code: "BAD_USAGE",
+        message: "--prefix requires --host <hostname>",
+        next_actions: ["run402 cache invalidate --prefix /blog/ --host <hostname>"],
+      });
+    }
+    if (!prefix.startsWith("/")) {
+      fail({
+        code: "BAD_USAGE",
+        message: `prefix must start with '/' (got: ${prefix})`,
+      });
+    }
+    try {
+      const result = await sdk.cache.invalidatePrefix({ host, prefix });
+      emit(result, json);
+    } catch (err) {
+      reportSdkError(err);
+    }
+    return;
+  }
+
+  // Exact URL form.
+  if (positionals.length === 0) {
+    fail({
+      code: "BAD_USAGE",
+      message: "Missing URL argument.",
+      next_actions: [
+        "run402 cache invalidate <url>",
+        "run402 cache invalidate --prefix /blog/ --host <hostname>",
+        "run402 cache invalidate --all --host <hostname>",
+      ],
+    });
+  }
+  const url = positionals[0];
+  if (!url.startsWith("https://") && !url.startsWith("http://")) {
+    fail({
+      code: "BAD_USAGE",
+      message: `URL must be absolute (got: ${url})`,
+      next_actions: ["run402 cache invalidate https://<host>/<path>"],
+    });
+  }
+  try {
+    const result = await sdk.cache.invalidate(url);
+    emit(result, json);
+  } catch (err) {
+    reportSdkError(err);
+  }
+}
+
+function emit(result, json) {
+  if (json) {
+    console.log(JSON.stringify(result, null, 2));
+  } else {
+    const parts = [`Invalidated ${result.deleted} cache row(s)`];
+    if (result.host) parts.push(`on ${result.host}`);
+    if (result.path) parts.push(`for ${result.path}`);
+    parts.push(`(generation: ${result.generation})`);
+    console.log(parts.join(" "));
+  }
+}
+
+function formatInspectResult(result) {
+  if (result.status === "MISS") {
+    return `MISS — no cache row for ${result.url || "this URL"}.`;
+  }
+  const lines = [
+    `${result.status} — ${result.host}${result.path}`,
+    `  locale:           ${result.locale}`,
+    `  releaseId:        ${result.releaseId}`,
+    `  cachedAt:         ${result.cachedAt}`,
+    `  expiresAt:        ${result.expiresAt}`,
+    `  contentSha256:    ${result.contentSha256}`,
+  ];
+  if (result.writtenUnderGeneration) {
+    lines.push(`  writtenUnderGen:  ${result.writtenUnderGeneration}`);
+  }
+  return lines.join("\n");
+}

package/lib/dev.mjs

@@ -0,0 +1,137 @@
+/**
+ * run402 dev — Run a local Astro dev server with Run402 context injected.
+ *
+ * Capability `astro-ssr-runtime` (Run402 v1.52). Wraps `astro dev` with
+ * Run402-specific environment + SDK proxy so the dev experience matches
+ * production:
+ *
+ *   1. Load .env.local (if present) for project credentials.
+ *   2. Confirm RUN402_PROJECT_ID + RUN402_SERVICE_KEY are set.
+ *   3. Spawn `astro dev` as a child process inheriting the env.
+ *
+ * Future enhancements (deferred):
+ *   - DB/auth/storage/cache emulation via a local proxy.
+ *   - AsyncLocalStorage middleware that populates the same context
+ *     shape as the SSR Lambda runtime.
+ *   - Visible cache.invalidate() events in the dev log.
+ *
+ * Until those land, `run402 dev` is a thin wrapper that ensures the
+ * env shape is right and the Astro dev server starts with Run402
+ * credentials in scope — SDK calls in frontmatter then hit the live
+ * project via @run402/functions's default API_BASE.
+ */
+
+import { spawn } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { fail } from "./sdk-errors.mjs";
+
+const HELP = `run402 dev — Run Astro dev with Run402 context
+
+Usage:
+  run402 dev [--port <n>] [--host <h>] [--project <id>]
+
+Options:
+  --port <n>        Astro dev port (default 4321)
+  --host <h>        Astro dev host (default localhost)
+  --project <id>    Project id (default: RUN402_PROJECT_ID env var)
+
+The command:
+  1. Loads .env.local from the current directory (if present)
+  2. Verifies RUN402_PROJECT_ID and RUN402_SERVICE_KEY are set
+  3. Spawns 'astro dev' with the env inherited
+
+SDK calls (db, getUser, cache.invalidate, assets.put) hit the LIVE
+project at https://api.run402.com — no local DB / S3 / KMS setup needed.
+This is the recommended dev model: shape-parity with production.
+
+For offline dev with a local emulator, deferred to v1.5.
+
+Tip: in your project's package.json:
+  { "scripts": { "dev": "run402 dev" } }
+`;
+
+export async function run(sub, args = []) {
+  const all = [sub, ...args].filter(Boolean);
+  if (all.includes("--help") || all.includes("-h")) {
+    console.log(HELP);
+    return;
+  }
+
+  // Load .env.local (best effort — silently ignore if missing).
+  const envFile = resolve(process.cwd(), ".env.local");
+  if (existsSync(envFile)) {
+    const content = readFileSync(envFile, "utf-8");
+    for (const line of content.split("\n")) {
+      const trimmed = line.trim();
+      if (!trimmed || trimmed.startsWith("#")) continue;
+      const eq = trimmed.indexOf("=");
+      if (eq === -1) continue;
+      const key = trimmed.slice(0, eq).trim();
+      let val = trimmed.slice(eq + 1).trim();
+      // Strip optional surrounding quotes.
+      if ((val.startsWith('"') && val.endsWith('"')) || (val.startsWith("'") && val.endsWith("'"))) {
+        val = val.slice(1, -1);
+      }
+      if (!process.env[key]) process.env[key] = val;
+    }
+  }
+
+  const port = pickFlagValue(all, "--port") ?? "4321";
+  const host = pickFlagValue(all, "--host") ?? "localhost";
+  const projectId = pickFlagValue(all, "--project") ?? process.env.RUN402_PROJECT_ID;
+
+  if (!projectId) {
+    fail({
+      code: "BAD_USAGE",
+      message: "Missing RUN402_PROJECT_ID.",
+      hint: "Set it in .env.local (or pass --project <id>). Run 'run402 projects provision' first if you don't have one.",
+    });
+  }
+  if (!process.env.RUN402_SERVICE_KEY) {
+    fail({
+      code: "BAD_USAGE",
+      message: "Missing RUN402_SERVICE_KEY.",
+      hint: "Add it to .env.local. Get the service key from 'run402 projects list' or your Run402 dashboard.",
+    });
+  }
+
+  process.env.RUN402_PROJECT_ID = projectId;
+
+  console.log(`run402 dev — Astro on http://${host}:${port}`);
+  console.log(`  project:  ${projectId}`);
+  console.log(`  api_base: ${process.env.RUN402_API_BASE ?? "https://api.run402.com"}`);
+  console.log(`  env: .env.local ${existsSync(envFile) ? "loaded" : "not present (using process env)"}`);
+  console.log("");
+
+  // Spawn `npx astro dev`. We use `npx` so the local astro install resolves
+  // even if it's not on PATH. The child inherits stdio so the user sees
+  // Astro's normal output.
+  const child = spawn("npx", ["astro", "dev", "--port", port, "--host", host], {
+    stdio: "inherit",
+    env: process.env,
+    shell: false,
+  });
+
+  // Bubble up exit codes for clean tooling integration.
+  child.on("exit", (code, signal) => {
+    if (signal) {
+      process.kill(process.pid, signal);
+    } else {
+      process.exit(code ?? 0);
+    }
+  });
+
+  // Forward SIGINT / SIGTERM to the child so Ctrl-C cleanly stops Astro.
+  for (const sig of ["SIGINT", "SIGTERM"]) {
+    process.on(sig, () => {
+      child.kill(sig);
+    });
+  }
+}
+
+function pickFlagValue(args, flag) {
+  const idx = args.indexOf(flag);
+  if (idx === -1) return undefined;
+  return args[idx + 1];
+}

package/lib/doctor.mjs

@@ -0,0 +1,188 @@
+/**
+ * run402 doctor — Health and config diagnostics.
+ *
+ * Reports the state of the local Run402 setup: config dir, allowance,
+ * tier, project selection, API reachability. Agent-friendly: with
+ * `--json`, emits a structured report the agent can branch on without
+ * parsing English output.
+ *
+ * Capability `astro-ssr-runtime` (Run402 v1.52). Part of the agent-DX
+ * contract — agents run `run402 doctor` first to verify the environment
+ * before attempting other commands.
+ */
+
+import { existsSync, statSync } from "node:fs";
+import { CONFIG_DIR, readAllowance, loadKeyStore } from "./config.mjs";
+import { getSdk } from "./sdk.mjs";
+
+const HELP = `run402 doctor — Health and config diagnostics
+
+Usage:
+  run402 doctor [--json] [--verbose]
+
+Options:
+  --json       Emit a structured JSON report on stdout
+  --verbose    Include extra detail (timing, error messages)
+
+Checks performed:
+  - Config directory exists and is writable
+  - Allowance is configured and on a valid rail (x402 / mpp)
+  - Keystore has at least one wallet
+  - API_BASE is reachable (network check via /health)
+  - Active tier resolves and is not 'past_due' / 'frozen'
+
+Exit codes:
+  0  — all checks pass
+  1  — one or more checks failed (details in output)
+`;
+
+export async function run(sub, args = []) {
+  const all = [sub, ...args].filter(Boolean);
+  if (all.includes("--help") || all.includes("-h")) {
+    console.log(HELP);
+    return;
+  }
+  const json = all.includes("--json");
+  const verbose = all.includes("--verbose");
+
+  const checks = [];
+
+  // 1. Config directory.
+  try {
+    if (existsSync(CONFIG_DIR) && statSync(CONFIG_DIR).isDirectory()) {
+      checks.push({ name: "config_dir", status: "ok", value: CONFIG_DIR });
+    } else {
+      checks.push({
+        name: "config_dir",
+        status: "missing",
+        value: CONFIG_DIR,
+        hint: "Run 'run402 init' to set up the config directory.",
+      });
+    }
+  } catch (err) {
+    checks.push({
+      name: "config_dir",
+      status: "error",
+      message: err instanceof Error ? err.message : String(err),
+    });
+  }
+
+  // 2. Allowance.
+  try {
+    const allowance = readAllowance();
+    if (allowance) {
+      checks.push({
+        name: "allowance",
+        status: "ok",
+        value: {
+          rail: allowance.rail,
+          // Don't surface amounts or addresses unless --verbose; agents
+          // checking for config presence don't need wallet details.
+          ...(verbose && { details: allowance }),
+        },
+      });
+    } else {
+      checks.push({
+        name: "allowance",
+        status: "missing",
+        hint: "Run 'run402 init' to create an allowance.",
+      });
+    }
+  } catch (err) {
+    checks.push({
+      name: "allowance",
+      status: "error",
+      message: err instanceof Error ? err.message : String(err),
+    });
+  }
+
+  // 3. Keystore.
+  try {
+    const keystore = loadKeyStore();
+    const walletCount = Object.keys(keystore?.wallets ?? {}).length;
+    checks.push({
+      name: "keystore",
+      status: walletCount > 0 ? "ok" : "empty",
+      value: { wallet_count: walletCount },
+      ...(walletCount === 0 && {
+        hint: "Run 'run402 init' to generate a wallet.",
+      }),
+    });
+  } catch (err) {
+    checks.push({
+      name: "keystore",
+      status: "error",
+      message: err instanceof Error ? err.message : String(err),
+    });
+  }
+
+  // 4. API base reachability.
+  try {
+    const sdk = getSdk();
+    // Use the service.status endpoint (read-only, unauthenticated).
+    const t0 = Date.now();
+    await sdk.service.status();
+    const elapsed = Date.now() - t0;
+    checks.push({
+      name: "api_reachable",
+      status: "ok",
+      ...(verbose && { value: { elapsed_ms: elapsed } }),
+    });
+  } catch (err) {
+    checks.push({
+      name: "api_reachable",
+      status: "error",
+      message: err instanceof Error ? err.message : String(err),
+      hint: "Check the RUN402_API_BASE env var and your network connection.",
+    });
+  }
+
+  // 5. Active tier.
+  try {
+    const sdk = getSdk();
+    const tier = await sdk.tier.status();
+    const tierName = tier?.tier ?? null;
+    if (tierName && tierName !== "past_due" && tierName !== "frozen" && tierName !== "dormant") {
+      checks.push({
+        name: "tier",
+        status: "ok",
+        value: { tier: tierName },
+      });
+    } else {
+      checks.push({
+        name: "tier",
+        status: tierName ?? "missing",
+        ...(tierName && {
+          hint: "Run 'run402 tier set prototype' to subscribe (or upgrade).",
+        }),
+      });
+    }
+  } catch (err) {
+    checks.push({
+      name: "tier",
+      status: "error",
+      message: err instanceof Error ? err.message : String(err),
+    });
+  }
+
+  const allOk = checks.every((c) => c.status === "ok");
+
+  if (json) {
+    console.log(JSON.stringify({ ok: allOk, checks }, null, 2));
+  } else {
+    console.log(`Run402 doctor — ${allOk ? "all checks passed" : "issues found"}`);
+    console.log("");
+    for (const c of checks) {
+      const icon =
+        c.status === "ok" ? "✓"
+        : c.status === "missing" || c.status === "empty" ? "⚠"
+        : "✗";
+      const status = c.status === "ok" ? "ok" : c.status;
+      console.log(`  ${icon} ${c.name.padEnd(16)} ${status}`);
+      if (c.hint) console.log(`     → ${c.hint}`);
+      if (c.message) console.log(`     ${c.message}`);
+    }
+  }
+
+  process.exit(allOk ? 0 : 1);
+}