run402 3.5.3 → 3.5.5

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/core-dist/config.js

@@ -1,7 +1,8 @@
 import { homedir } from "node:os";
-import { join } from "node:path";
-import { existsSync, renameSync, mkdirSync, chmodSync } from "node:fs";
-const DEFAULT_API_BASE = "https://api.run402.com";
+import { dirname, join } from "node:path";
+import { existsSync, renameSync, mkdirSync, chmodSync, readFileSync, writeFileSync } from "node:fs";
+import { randomBytes } from "node:crypto";
+export const DEFAULT_API_BASE = "https://api.run402.com";
 /**
  * Validate a user-supplied API base URL. Throws a clear error message that
  * names the env var when the URL is malformed or uses a scheme other than
@@ -33,7 +34,12 @@ function validateApiBase(envVar, raw, fallback) {
 }
 export function getApiBase() {
     const validated = validateApiBase("RUN402_API_BASE", process.env.RUN402_API_BASE, DEFAULT_API_BASE);
-    return validated ?? DEFAULT_API_BASE;
+    return validated ?? getConfiguredApiBase() ?? DEFAULT_API_BASE;
+}
+export function getApiBaseSource() {
+    if (process.env.RUN402_API_BASE !== undefined)
+        return "env";
+    return getConfiguredApiBase() ? "profile" : "default";
 }
 /**
  * API base for the deploy-v2 routes. Defaults to the same value as
@@ -115,6 +121,82 @@ export function getConfigDir() {
 export function getKeystorePath() {
     return join(getConfigDir(), "projects.json");
 }
+export function getApiTargetConfigPath() {
+    return join(getConfigDir(), "target.json");
+}
+export function readApiTargetConfig(path) {
+    const p = path ?? getApiTargetConfigPath();
+    try {
+        const parsed = JSON.parse(readFileSync(p, "utf-8"));
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+            return null;
+        const cfg = parsed;
+        if (cfg.api_base !== undefined && typeof cfg.api_base !== "string")
+            return null;
+        if (cfg.target_kind !== undefined &&
+            cfg.target_kind !== "cloud" &&
+            cfg.target_kind !== "core" &&
+            cfg.target_kind !== "unknown") {
+            return null;
+        }
+        return cfg;
+    }
+    catch {
+        return null;
+    }
+}
+function atomicWrite(path, content, mode) {
+    const dir = dirname(path);
+    mkdirSync(dir, { recursive: true });
+    const tmp = join(dir, `.target.${randomBytes(4).toString("hex")}.tmp`);
+    writeFileSync(tmp, content, { mode });
+    renameSync(tmp, path);
+    try {
+        chmodSync(path, mode);
+    }
+    catch {
+        /* best-effort on non-POSIX */
+    }
+}
+export function saveApiTargetConfig(config, path) {
+    const p = path ?? getApiTargetConfigPath();
+    atomicWrite(p, JSON.stringify(config, null, 2), 0o600);
+}
+export function configureApiBase(apiBase, options = {}) {
+    if (apiBase === "") {
+        throw new Error("api_base must be a non-empty http(s) URL.");
+    }
+    const validated = validateApiBase("api_base", apiBase, DEFAULT_API_BASE);
+    if (!validated) {
+        throw new Error("api_base must be a non-empty http(s) URL.");
+    }
+    const config = {
+        api_base: validated.replace(/\/+$/, ""),
+        target_kind: options.target_kind ?? "unknown",
+        updated_at: options.updated_at ?? new Date().toISOString(),
+        ...(options.health_status ? { health_status: options.health_status } : {}),
+        ...(options.health_error ? { health_error: options.health_error } : {}),
+    };
+    saveApiTargetConfig(config);
+    return config;
+}
+export function getConfiguredApiBase() {
+    const cfg = readApiTargetConfig();
+    if (!cfg?.api_base)
+        return null;
+    const validated = validateApiBase("api_base", cfg.api_base, DEFAULT_API_BASE);
+    return validated ? validated.replace(/\/+$/, "") : null;
+}
+export function getApiTargetKind() {
+    const cfg = readApiTargetConfig();
+    return cfg?.target_kind ?? "unknown";
+}
+export function isCoreApiTarget() {
+    const cfg = readApiTargetConfig();
+    if (cfg?.target_kind !== "core" || !cfg.api_base)
+        return false;
+    return getApiBase().replace(/\/+$/, "") === cfg.api_base.replace(/\/+$/, "");
+}
 export function getAllowancePath() {
     if (process.env.RUN402_ALLOWANCE_PATH)
         return process.env.RUN402_ALLOWANCE_PATH;

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

@@ -3,7 +3,17 @@
  * Adds CLI-specific behavior: process.exit() on errors.
  */
 
-import { getApiBase, getConfigDir, getKeystorePath, getAllowancePath } from "../core-dist/config.js";
+import {
+  getApiBase,
+  getApiBaseSource,
+  getApiTargetKind,
+  getConfigDir,
+  getKeystorePath,
+  getAllowancePath,
+  configureApiBase,
+  isCoreApiTarget,
+  readApiTargetConfig,
+} from "../core-dist/config.js";
 import { readAllowance as coreReadAllowance, saveAllowance as coreSaveAllowance } from "../core-dist/allowance.js";
 import { loadKeyStore, getProject, saveProject, updateProject, removeProject, saveKeyStore, getActiveProjectId, setActiveProjectId } from "../core-dist/keystore.js";
 import { getAllowanceAuthHeaders as coreGetAllowanceAuthHeaders } from "../core-dist/allowance-auth.js";
@@ -16,6 +26,10 @@ import { initializeWalletAction, createProjectAction } from "./next-actions.mjs"
 export function configDir() { return getConfigDir(); }
 export function allowanceFile() { return getAllowancePath(); }
 export function projectsFile() { return getKeystorePath(); }
+export function apiBase() { return getApiBase(); }
+export function apiBaseSource() { return getApiBaseSource(); }
+export function apiTargetKind() { return getApiTargetKind(); }
+export function coreTarget() { return isCoreApiTarget(); }
 
 // Snapshot constants, retained for backward compatibility (tests, the OpenClaw
 // config re-export). These are evaluated when this module is first imported.
@@ -116,4 +130,15 @@ export function resolveProjectId(id) {
 }
 
 // Re-export core keystore functions for direct use
-export { loadKeyStore, saveProject, updateProject, removeProject, saveKeyStore, getActiveProjectId, setActiveProjectId };
+export {
+  configureApiBase,
+  isCoreApiTarget,
+  readApiTargetConfig,
+  loadKeyStore,
+  saveProject,
+  updateProject,
+  removeProject,
+  saveKeyStore,
+  getActiveProjectId,
+  setActiveProjectId,
+};