run402 3.5.2 → 3.5.4

package/cli.mjs

@@ -27,6 +27,9 @@ Commands:
   tier        Manage tier subscription (status, set)
   projects    Manage projects (provision, list, query, inspect, delete)
   admin       Platform-admin operations (lease-perpetual, archive, reactivate)
+  cloud       Cloud portability archive export (archives create/download/status)
+  archives    Inspect and verify portable project archives locally
+  core        Local Run402 Core import helpers
   deploy      Unified deploy operations (requires active tier)
   ci          Link GitHub Actions OIDC deploy bindings
   transfer    Two-party project transfer (init, preview, list, accept, cancel)
@@ -67,6 +70,8 @@ Examples:
   run402 allowance create
   run402 allowance fund
   run402 deploy apply --manifest app.json
+  run402 cloud archives create prj_... --wait --output ./project.r402ar --json
+  run402 core projects import ./project.r402ar --name imported-project --env-file ./required.env --json
   run402 jobs submit --file job.json
   run402 projects list
   run402 projects sql <project_id> "SELECT * FROM users LIMIT 5"
@@ -162,6 +167,21 @@ switch (cmd) {
     await run(sub, rest);
     break;
   }
+  case "cloud": {
+    const { run } = await import("./lib/cloud.mjs");
+    await run(sub, rest);
+    break;
+  }
+  case "archives": {
+    const { run } = await import("./lib/archives.mjs");
+    await run(sub, rest);
+    break;
+  }
+  case "core": {
+    const { run } = await import("./lib/core.mjs");
+    await run(sub, rest);
+    break;
+  }
   case "deploy": {
     const { run } = await import("./lib/deploy.mjs");
     await run([sub, ...rest].filter(Boolean));

package/lib/archives.mjs

@@ -0,0 +1,55 @@
+import { inspectArchive, verifyArchive } from "#sdk/node";
+import { reportSdkError, fail } from "./sdk-errors.mjs";
+import { assertKnownFlags, hasHelp, normalizeArgv, positionalArgs } from "./argparse.mjs";
+
+const HELP = `run402 archives — Inspect and verify portable Run402 project archives
+
+Usage:
+  run402 archives inspect <archive-path> [--json]
+  run402 archives verify  <archive-path> [--json]
+
+Notes:
+  - Verification is local and offline. It does not require Cloud credentials.
+  - Archives are untrusted input; verify checks integrity and compatibility, not trust.
+`;
+
+export async function run(sub, rawArgs = []) {
+  const all = [sub, ...rawArgs].filter(Boolean);
+  if (hasHelp(all)) {
+    console.log(HELP);
+    return;
+  }
+  switch (sub) {
+    case "inspect": return inspect(rawArgs);
+    case "verify": return verify(rawArgs);
+    default:
+      fail({ code: "BAD_USAGE", message: "Usage: run402 archives <inspect|verify> <archive-path> [--json]" });
+  }
+}
+
+async function inspect(rawArgs) {
+  const args = normalizeArgv(rawArgs);
+  assertKnownFlags(args, ["--json", "--help", "-h"], []);
+  const archivePath = positionalArgs(args, [])[0];
+  if (!archivePath) fail({ code: "BAD_USAGE", message: "Usage: run402 archives inspect <archive-path> [--json]" });
+  try {
+    const result = await inspectArchive(archivePath);
+    console.log(JSON.stringify({ archive: result }, null, 2));
+  } catch (err) {
+    reportSdkError(err);
+  }
+}
+
+async function verify(rawArgs) {
+  const args = normalizeArgv(rawArgs);
+  assertKnownFlags(args, ["--json", "--help", "-h"], []);
+  const archivePath = positionalArgs(args, [])[0];
+  if (!archivePath) fail({ code: "BAD_USAGE", message: "Usage: run402 archives verify <archive-path> [--json]" });
+  try {
+    const result = await verifyArchive(archivePath);
+    console.log(JSON.stringify({ ok: result.ok, verified: result.ok, archive: result }, null, 2));
+    if (!result.ok) process.exit(1);
+  } catch (err) {
+    reportSdkError(err);
+  }
+}

package/lib/cache.mjs

@@ -19,6 +19,7 @@
 import { getSdk } from "./sdk.mjs";
 import { reportSdkError, fail } from "./sdk-errors.mjs";
 import { assertKnownFlags, flagValue, normalizeArgv } from "./argparse.mjs";
+import { editRequestAction } from "./next-actions.mjs";
 
 // Locally-defined helpers — argparse.mjs's normalized form is a flat
 // string array; we need to identify positional args (non-flag, non-flag-
@@ -101,7 +102,7 @@ export async function run(sub, args) {
       fail({
         code: "BAD_USAGE",
         message: `Unknown cache subcommand: ${sub}`,
-        next_actions: ["run402 cache --help"],
+        next_actions: [editRequestAction("run402 cache --help", "Choose a supported cache subcommand.")],
       });
   }
 }
@@ -119,7 +120,7 @@ async function inspect(args) {
     fail({
       code: "BAD_USAGE",
       message: "Missing URL argument.",
-      next_actions: ["run402 cache inspect <url>"],
+      next_actions: [editRequestAction("run402 cache inspect <url>", "Provide the absolute URL to inspect.")],
     });
   }
   const url = positionals[0];
@@ -127,7 +128,7 @@ async function inspect(args) {
     fail({
       code: "BAD_USAGE",
       message: `URL must be absolute (got: ${url})`,
-      next_actions: ["run402 cache inspect https://<host>/<path>"],
+      next_actions: [editRequestAction("run402 cache inspect https://<host>/<path>", "Use an absolute HTTP(S) URL.")],
     });
   }
 
@@ -164,7 +165,7 @@ async function invalidate(args) {
       fail({
         code: "BAD_USAGE",
         message: "--all requires --host <hostname>",
-        next_actions: ["run402 cache invalidate --all --host <hostname>"],
+        next_actions: [editRequestAction("run402 cache invalidate --all --host <hostname>", "Name the host whose cache should be invalidated.")],
       });
     }
     try {
@@ -181,7 +182,7 @@ async function invalidate(args) {
       fail({
         code: "BAD_USAGE",
         message: "--prefix requires --host <hostname>",
-        next_actions: ["run402 cache invalidate --prefix /blog/ --host <hostname>"],
+        next_actions: [editRequestAction("run402 cache invalidate --prefix /blog/ --host <hostname>", "Pair prefix invalidation with the owning host.")],
       });
     }
     if (!prefix.startsWith("/")) {
@@ -205,9 +206,9 @@ async function invalidate(args) {
       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>",
+        editRequestAction("run402 cache invalidate <url>", "Invalidate one absolute URL."),
+        editRequestAction("run402 cache invalidate --prefix /blog/ --host <hostname>", "Invalidate cached entries under a path prefix."),
+        editRequestAction("run402 cache invalidate --all --host <hostname>", "Invalidate every cached entry for a host."),
       ],
     });
   }
@@ -216,7 +217,7 @@ async function invalidate(args) {
     fail({
       code: "BAD_USAGE",
       message: `URL must be absolute (got: ${url})`,
-      next_actions: ["run402 cache invalidate https://<host>/<path>"],
+      next_actions: [editRequestAction("run402 cache invalidate https://<host>/<path>", "Use an absolute HTTP(S) URL.")],
     });
   }
   try {

package/lib/cloud.mjs

@@ -0,0 +1,254 @@
+import { mkdirSync, writeFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+
+import { getSdk } from "./sdk.mjs";
+import { fail, reportSdkError } from "./sdk-errors.mjs";
+import { assertAllowedValue, assertKnownFlags, flagValue, hasHelp, normalizeArgv, parseIntegerFlag, positionalArgs } from "./argparse.mjs";
+
+const HELP = `run402 cloud — Run402 Cloud portability commands
+
+Usage:
+  run402 cloud archives create <project-id> [options]
+  run402 cloud archives download <project-id> <archive-id> --output <file> [--json]
+  run402 cloud archives status <project-id> <archive-id> [--json]
+
+Canonical agent path:
+  run402 cloud archives create prj_... \\
+    --scope portable-runtime-v1 --auth stubs --consistency pause-writes \\
+    --wait --output ./project.r402ar --json
+
+Options for create:
+  --scope <scope>          Archive scope. v1 supports portable-runtime-v1.
+  --auth <mode>            Auth export mode: stubs (default) or none.
+  --consistency <mode>     pause-writes (default) or cloud_write_pause_v1.
+  --idempotency-key <key>  Retry-safe creation key.
+  --wait                   Poll until the archive is ready.
+  --output <file>          Save archive bytes. Implies --wait.
+  --poll-interval <ms>     Poll interval while waiting (default 1000).
+  --timeout <ms>           Wait timeout (default 600000).
+  --json                   Emit final JSON on stdout.
+  --json-stream            Emit NDJSON progress events on stdout.
+`;
+
+const FLAG_VALUES = [
+  "--scope",
+  "--auth",
+  "--consistency",
+  "--idempotency-key",
+  "--output",
+  "--poll-interval",
+  "--timeout",
+];
+const FLAGS = new Set([
+  ...FLAG_VALUES,
+  "--wait",
+  "--json",
+  "--json-stream",
+  "--help",
+  "-h",
+]);
+
+export async function run(sub, args = []) {
+  const all = [sub, ...args].filter(Boolean);
+  if (hasHelp(all)) {
+    console.log(HELP);
+    return;
+  }
+  if (sub !== "archives") {
+    fail({
+      code: "BAD_USAGE",
+      message: "Usage: run402 cloud archives <create|download|status> ...",
+      next_actions: [{ type: "run_command", command: "run402 cloud archives --help" }],
+    });
+  }
+  const action = args[0];
+  const rest = args.slice(1);
+  if (action === "create") return create(rest);
+  if (action === "download") return download(rest);
+  if (action === "status") return status(rest);
+  fail({
+    code: "BAD_USAGE",
+    message: "Usage: run402 cloud archives <create|download|status> ...",
+    next_actions: [{ type: "run_command", command: "run402 cloud archives --help" }],
+  });
+}
+
+async function create(rawArgs) {
+  const args = normalizeArgv(rawArgs);
+  assertKnownFlags(args, [...FLAGS], FLAG_VALUES);
+  const pos = positionalArgs(args, FLAG_VALUES);
+  const projectId = pos[0];
+  if (!projectId) {
+    fail({ code: "BAD_PROJECT_ID", message: "Missing project id." });
+  }
+  const scope = flagValue(args, "--scope") ?? "portable-runtime-v1";
+  const auth = flagValue(args, "--auth") ?? "stubs";
+  const consistency = flagValue(args, "--consistency") ?? "pause-writes";
+  assertAllowedValue(scope, ["portable-runtime-v1"], "--scope");
+  assertAllowedValue(auth, ["stubs", "none"], "--auth");
+  assertAllowedValue(consistency, ["pause-writes", "cloud_write_pause_v1"], "--consistency");
+
+  const output = flagValue(args, "--output");
+  const wait = args.includes("--wait") || Boolean(output);
+  const jsonStream = args.includes("--json-stream");
+  const json = args.includes("--json") || jsonStream || true;
+  const idempotencyKey = flagValue(args, "--idempotency-key") ?? undefined;
+  const pollIntervalMs = parseIntegerFlag("--poll-interval", flagValue(args, "--poll-interval"), { min: 100, def: 1000 });
+  const timeoutMs = parseIntegerFlag("--timeout", flagValue(args, "--timeout"), { min: 1000, def: 600000 });
+  const emit = (event) => {
+    if (jsonStream) console.log(JSON.stringify(event));
+  };
+
+  try {
+    const sdk = getSdk();
+    const created = await sdk.archives.create(projectId, {
+      scope,
+      auth,
+      consistency,
+      idempotencyKey,
+    });
+    emit(progressEvent("archive_export_created", "create", projectId, created));
+
+    let archive = created;
+    let outputPath = null;
+    let bytesWritten = 0;
+    if (wait) {
+      archive = created.status === "ready"
+        ? created
+        : await sdk.archives.wait(projectId, created.archive_id, {
+            pollIntervalMs,
+            timeoutMs,
+            onProgress: emit,
+          });
+      if (archive.status !== "ready") {
+        const result = finalCreateResult({ projectId, created, archive, outputPath, bytesWritten });
+        printJson(result, jsonStream);
+        process.exit(1);
+      }
+      if (output) {
+        const download = await sdk.archives.download(projectId, archive.archive_id);
+        outputPath = resolve(output);
+        mkdirSync(dirname(outputPath), { recursive: true });
+        writeFileSync(outputPath, download.bytes);
+        bytesWritten = download.bytes.byteLength;
+        emit({
+          ...progressEvent("archive_export_downloaded", "download", projectId, archive),
+          context: { output_path: outputPath, bytes_written: bytesWritten },
+        });
+      }
+    }
+
+    const result = finalCreateResult({ projectId, created, archive, outputPath, bytesWritten });
+    if (jsonStream) {
+      console.log(JSON.stringify({
+        event: "archive_export_complete",
+        stage: "complete",
+        resource_type: "project_archive",
+        resource_id: archive.archive_id,
+        project_id: projectId,
+        status: archive.status === "ready" ? "complete" : archive.status,
+        completed_units: archive.status === "ready" ? 1 : 0,
+        total_units: 1,
+        code: null,
+        message: archive.status === "ready" ? "Archive export complete." : "Archive export did not complete.",
+        next_action: archive.next_action,
+        retryable: false,
+        result,
+      }));
+    } else if (json) {
+      console.log(JSON.stringify(result, null, 2));
+    }
+    if (archive.status !== "ready") process.exit(1);
+  } catch (err) {
+    reportSdkError(err);
+  }
+}
+
+async function download(rawArgs) {
+  const args = normalizeArgv(rawArgs);
+  assertKnownFlags(args, ["--output", "--json", "--help", "-h"], ["--output"]);
+  const pos = positionalArgs(args, ["--output"]);
+  const [projectId, archiveId] = pos;
+  const output = flagValue(args, "--output");
+  if (!projectId || !archiveId || !output) {
+    fail({ code: "BAD_USAGE", message: "Usage: run402 cloud archives download <project-id> <archive-id> --output <file> [--json]" });
+  }
+  try {
+    const download = await getSdk().archives.download(projectId, archiveId);
+    const outputPath = resolve(output);
+    mkdirSync(dirname(outputPath), { recursive: true });
+    writeFileSync(outputPath, download.bytes);
+    console.log(JSON.stringify({
+      ok: true,
+      project_id: projectId,
+      archive_id: archiveId,
+      output_path: outputPath,
+      bytes_written: download.bytes.byteLength,
+      sha256: download.archive.sha256,
+      verify_command: `run402 archives verify ${JSON.stringify(outputPath)} --json`,
+      import_command: `run402 core projects import ${JSON.stringify(outputPath)} --name imported-project --env-file ./required.env --json`,
+      archive: download.archive,
+    }, null, 2));
+  } catch (err) {
+    reportSdkError(err);
+  }
+}
+
+async function status(rawArgs) {
+  const args = normalizeArgv(rawArgs);
+  assertKnownFlags(args, ["--json", "--help", "-h"], []);
+  const pos = positionalArgs(args, []);
+  const [projectId, archiveId] = pos;
+  if (!projectId || !archiveId) {
+    fail({ code: "BAD_USAGE", message: "Usage: run402 cloud archives status <project-id> <archive-id> [--json]" });
+  }
+  try {
+    const archive = await getSdk().archives.get(projectId, archiveId);
+    console.log(JSON.stringify({ archive }, null, 2));
+  } catch (err) {
+    reportSdkError(err);
+  }
+}
+
+function finalCreateResult({ projectId, created, archive, outputPath, bytesWritten }) {
+  return {
+    ok: archive.status === "ready",
+    project_id: projectId,
+    archive_id: archive.archive_id,
+    operation_id: archive.operation_id,
+    created_archive_id: created.archive_id,
+    archive_status: archive.status,
+    output_path: outputPath,
+    bytes_written: bytesWritten,
+    sha256: archive.sha256,
+    byte_count: archive.byte_count,
+    expires_at: archive.expires_at,
+    verify_command: outputPath ? `run402 archives verify ${JSON.stringify(outputPath)} --json` : null,
+    import_command: outputPath ? `run402 core projects import ${JSON.stringify(outputPath)} --name imported-project --env-file ./required.env --json` : null,
+    next_action: archive.next_action,
+    portability_report: archive.portability_report,
+    export_report: archive.export_report,
+    archive,
+  };
+}
+
+function progressEvent(event, stage, projectId, archive) {
+  return {
+    event,
+    stage,
+    resource_type: "project_archive",
+    resource_id: archive.archive_id,
+    project_id: projectId,
+    status: archive.status,
+    completed_units: archive.status === "ready" || archive.status === "failed" || archive.status === "expired" ? 1 : 0,
+    total_units: 1,
+    code: archive.status === "failed" ? archive.error?.code ?? "ARCHIVE_EXPORT_FAILED" : null,
+    message: `Archive export status: ${archive.status}`,
+    next_action: archive.next_action,
+    retryable: archive.status === "running",
+  };
+}
+
+function printJson(result, alreadyStreamed) {
+  if (!alreadyStreamed) console.log(JSON.stringify(result, null, 2));
+}

package/lib/config.mjs

@@ -8,6 +8,7 @@ import { readAllowance as coreReadAllowance, saveAllowance as coreSaveAllowance
 import { loadKeyStore, getProject, saveProject, updateProject, removeProject, saveKeyStore, getActiveProjectId, setActiveProjectId } from "../core-dist/keystore.js";
 import { getAllowanceAuthHeaders as coreGetAllowanceAuthHeaders } from "../core-dist/allowance-auth.js";
 import { fail } from "./sdk-errors.mjs";
+import { initializeWalletAction, createProjectAction } from "./next-actions.mjs";
 
 // Wallet-dependent paths are exposed as getters (preferred — they always
 // reflect the active profile, even if some future code path imports this module
@@ -48,6 +49,7 @@ export function readAllowance() {
       message: err?.message ?? "allowance.json is malformed",
       hint: "Back up ~/.config/run402/allowance.json and run 'run402 init' to recreate it.",
       details: { path: allowanceFile() },
+      next_actions: [initializeWalletAction()],
     });
   }
 }
@@ -63,6 +65,7 @@ export function allowanceAuthHeaders(path) {
       code: "NO_ALLOWANCE",
       message: "No agent allowance found.",
       hint: "Run: run402 allowance create",
+      next_actions: [initializeWalletAction()],
     });
   }
   return headers;
@@ -80,6 +83,7 @@ export function findProject(id) {
       message: `Project ${idStr} not found in local registry.`,
       hint,
       details: { project_id: idStr, source: "local_registry" },
+      next_actions: [createProjectAction()],
     });
   }
   return p;
@@ -92,6 +96,7 @@ export function resolveProject(id) {
       code: "NO_ACTIVE_PROJECT",
       message: "no project specified and no active project set.",
       hint: "Run: run402 projects provision",
+      next_actions: [createProjectAction()],
     });
   }
   return findProject(projectId);
@@ -104,6 +109,7 @@ export function resolveProjectId(id) {
       code: "NO_ACTIVE_PROJECT",
       message: "no project specified and no active project set.",
       hint: "Run: run402 projects provision",
+      next_actions: [createProjectAction()],
     });
   }
   return projectId;

package/lib/core.mjs

@@ -0,0 +1,122 @@
+import { importArchiveToCore } from "#sdk/node";
+import { fail, reportSdkError } from "./sdk-errors.mjs";
+import { assertKnownFlags, flagValue, hasHelp, normalizeArgv, positionalArgs } from "./argparse.mjs";
+
+const HELP = `run402 core — Local Run402 Core commands
+
+Usage:
+  run402 core projects import <archive-path> --name <project-name> [options]
+
+Options:
+  --name <name>             New Core project name (default imported-project)
+  --env-file <path>         Env file satisfying required archive secrets.
+  --secret KEY=VALUE        Inline secret value; repeatable. Overrides --env-file.
+  --core-url <url>          Core gateway URL (default RUN402_CORE_URL or http://127.0.0.1:4020)
+  --dry-run                 Verify and plan without creating a Core project.
+  --require-runnable        Block import unless required secrets are supplied.
+  --json                    Emit final JSON.
+  --json-stream             Emit NDJSON progress events and final result event.
+`;
+
+const FLAG_VALUES = ["--name", "--env-file", "--secret", "--core-url"];
+const FLAGS = new Set([...FLAG_VALUES, "--dry-run", "--require-runnable", "--json", "--json-stream", "--help", "-h"]);
+
+export async function run(sub, args = []) {
+  const all = [sub, ...args].filter(Boolean);
+  if (hasHelp(all)) {
+    console.log(HELP);
+    return;
+  }
+  if (sub !== "projects") {
+    fail({ code: "BAD_USAGE", message: "Usage: run402 core projects import <archive-path> [options]" });
+  }
+  const action = args[0];
+  if (action === "import") return importProject(args.slice(1));
+  fail({ code: "BAD_USAGE", message: "Usage: run402 core projects import <archive-path> [options]" });
+}
+
+async function importProject(rawArgs) {
+  const args = normalizeArgv(rawArgs);
+  assertKnownFlags(args, [...FLAGS], FLAG_VALUES);
+  const archivePath = positionalArgs(args, FLAG_VALUES)[0];
+  if (!archivePath) {
+    fail({ code: "BAD_USAGE", message: "Usage: run402 core projects import <archive-path> --name <project-name> [options]" });
+  }
+  const jsonStream = args.includes("--json-stream");
+  const secretValues = parseSecrets(args);
+  const name = flagValue(args, "--name") ?? "imported-project";
+  const coreUrl = flagValue(args, "--core-url") ?? undefined;
+  const startedEvent = {
+    event: "core_archive_import_started",
+    stage: "verify",
+    resource_type: "project_archive",
+    resource_id: archivePath,
+    status: "running",
+    completed_units: 0,
+    total_units: 1,
+    code: null,
+    message: "Verifying archive locally before Core import.",
+    next_action: { type: "none" },
+    retryable: false,
+    context: { archive_path: archivePath, core_url: coreUrl ?? null, project_name: name },
+  };
+  if (jsonStream) console.log(JSON.stringify(startedEvent));
+  try {
+    const result = await importArchiveToCore({
+      archivePath,
+      name,
+      coreUrl,
+      envFile: flagValue(args, "--env-file") ?? undefined,
+      secretValues,
+      dryRun: args.includes("--dry-run"),
+      requireRunnable: args.includes("--require-runnable"),
+    });
+    if (jsonStream) {
+      console.log(JSON.stringify({
+        event: "core_archive_import_complete",
+        stage: "complete",
+        resource_type: "project_archive",
+        resource_id: archivePath,
+        status: result.status,
+        completed_units: result.status === "imported" || result.status === "dry_run" ? 1 : 0,
+        total_units: 1,
+        code: firstDiagnosticCode(result),
+        message: `Core archive import status: ${result.status}`,
+        next_action: result.next_action,
+        retryable: result.status === "failed" && result.diagnostics.some((d) => d.retryable),
+        result,
+      }));
+    } else {
+      console.log(JSON.stringify({ ok: result.status === "imported" || result.status === "dry_run", import: result }, null, 2));
+    }
+    if (result.status !== "imported" && result.status !== "dry_run") process.exit(1);
+  } catch (err) {
+    reportSdkError(err);
+  }
+}
+
+function parseSecrets(args) {
+  const out = {};
+  for (let i = 0; i < args.length; i += 1) {
+    if (args[i] !== "--secret") continue;
+    const value = args[i + 1];
+    if (!value || value.startsWith("--")) {
+      fail({ code: "BAD_FLAG", message: "--secret requires KEY=VALUE" });
+    }
+    const eq = value.indexOf("=");
+    if (eq <= 0) {
+      fail({ code: "BAD_FLAG", message: "--secret requires KEY=VALUE", details: { value } });
+    }
+    const key = value.slice(0, eq);
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key)) {
+      fail({ code: "BAD_FLAG", message: `Invalid secret env var name: ${key}` });
+    }
+    out[key] = value.slice(eq + 1);
+    i += 1;
+  }
+  return out;
+}
+
+function firstDiagnosticCode(result) {
+  return result.diagnostics.find((d) => d.severity === "blocking")?.code ?? null;
+}