run402 4.93.2 → 4.95.0

package/lib/ai.mjs

@@ -24,7 +24,7 @@ Examples:
 
 Notes:
   - [project_id] defaults to the active project when omitted (set with
-    'run402 projects use <id>'). Project IDs start with 'prj_'; any first
+    'run402 projects use <project_id>'). Project IDs start with 'prj_'; any first
     positional that doesn't is treated as the next argument instead.
   - translate requires the AI Translation add-on on the project
   - moderate is free for all projects
@@ -47,7 +47,7 @@ Options:
   --to <lang>         Target language code (required, e.g. es, ja, fr)
   --from <lang>       Source language code (optional; auto-detected if omitted)
   --context <hint>    Optional translation hint (e.g. "formal business email")
-  --project <id>      Project ID (alternative to the positional argument)
+  --project <project_id>      Project ID (alternative to the positional argument)
 
 Notes:
   - Requires the AI Translation add-on on the project
@@ -71,7 +71,7 @@ Arguments:
   <text>              Text to check (quote it to preserve spaces)
 
 Options:
-  --project <id>      Project ID (alternative to the positional argument)
+  --project <project_id>      Project ID (alternative to the positional argument)
 
 Notes:
   - Free for all projects; uses the project's service key
@@ -91,7 +91,7 @@ Arguments:
                       Must start with 'prj_'; any other first positional is an error.
 
 Options:
-  --project <id>      Project ID (alternative to the positional argument)
+  --project <project_id>      Project ID (alternative to the positional argument)
 
 Notes:
   - Reports translation word quota and usage; only meaningful with the
@@ -111,7 +111,7 @@ async function translate(args) {
   args = normalizeArgv(args);
   assertKnownFlags(args, TRANSLATE_VALUE_FLAGS, TRANSLATE_VALUE_FLAGS);
 
-  // --project <id> wins over positional, mirroring previous behavior.
+  // --project <project_id> wins over positional, mirroring previous behavior.
   const projectOpt = flagValue(args, "--project");
   const to = flagValue(args, "--to");
   const from = flagValue(args, "--from");

package/lib/approve.mjs

@@ -0,0 +1,81 @@
+/**
+ * `run402 approve --action <capability> (--org <org_id> | --project <project_id>)`
+ * — mint a passkey-signed write approval scoped to one (action, target) so a
+ * person signed in without a wallet can provision, deploy, or write secrets.
+ * See sign-in.mjs.
+ */
+
+import { fail } from "./sdk-errors.mjs";
+import { normalizeArgv, hasHelp, assertKnownFlags, flagValue, positionalArgs } from "./argparse.mjs";
+import { APPROVAL_ACTIONS, mintApproval } from "./sign-in.mjs";
+
+const HELP = `run402 approve — mint a write approval for one action on one target
+
+Usage:
+  run402 approve --action <capability> (--org <org_id> | --project <project_id>) [--no-open]
+
+A person signed in with 'run402 login' (no wallet) needs a write approval to
+provision a project, deploy, or write secrets. It is signed with your passkey,
+covers one action on one org or project, lasts 30 minutes idle (4 hours at
+most), and dies with the sign-in session. It never counts as a step-up.
+From an interactive terminal the CLI opens this ceremony for you when a write
+needs it; agents and CI relay the command instead.
+
+Actions:
+  org.project.create     --org <org_id>
+  project.deploy         --project <project_id>
+  project.secret.write   --project <project_id>
+
+Options:
+  --no-open  Do not open the browser; print the URL only.
+
+Notes:
+  - Requires 'run402 login' (a device-grade session cannot approve).
+  - 'run402 whoami' lists the approvals cached on this machine.
+`;
+
+export async function run(args = []) {
+  args = normalizeArgv(args);
+  if (hasHelp(args)) {
+    console.log(HELP);
+    process.exit(0);
+  }
+  const valueFlags = ["--action", "--org", "--project"];
+  assertKnownFlags(args, ["--help", "-h", "--no-open", ...valueFlags], valueFlags);
+  const extra = positionalArgs(args, valueFlags);
+  if (extra.length > 0) {
+    fail({ code: "BAD_USAGE", message: `Unexpected argument for approve: ${extra[0]}`, hint: "Use `run402 approve --action <capability> (--org <org_id> | --project <project_id>)`." });
+  }
+  const action = flagValue(args, "--action");
+  const org = flagValue(args, "--org");
+  const project = flagValue(args, "--project");
+
+  if (!action || !APPROVAL_ACTIONS[action]) {
+    fail({
+      code: "BAD_FLAG",
+      message: `--action must be one of: ${Object.keys(APPROVAL_ACTIONS).join(", ")}`,
+      details: { flag: "--action", value: action, allowed: Object.keys(APPROVAL_ACTIONS) },
+    });
+  }
+  const scope = APPROVAL_ACTIONS[action];
+  if (scope === "org" && !org) fail({ code: "BAD_FLAG", message: `--org <org_id> is required for --action ${action}` });
+  if (scope === "project" && !project) fail({ code: "BAD_FLAG", message: `--project <project_id> is required for --action ${action}` });
+  if (scope === "org" && project) fail({ code: "BAD_FLAG", message: `--project is not valid for org-scoped --action ${action}; use --org` });
+  if (scope === "project" && org) fail({ code: "BAD_FLAG", message: `--org is not valid for project-scoped --action ${action}; use --project` });
+
+  const approval = await mintApproval({
+    action,
+    orgId: org ?? undefined,
+    projectId: project ?? undefined,
+    noOpen: args.includes("--no-open"),
+  });
+  console.log(
+    JSON.stringify({
+      approved: true,
+      action,
+      ...(org ? { org_id: org } : {}),
+      ...(project ? { project_id: project } : {}),
+      expires_at: new Date(approval.expires_at).toISOString(),
+    }),
+  );
+}

package/lib/apps.mjs

@@ -1,4 +1,4 @@
-import { allowanceAuthHeaders, saveProject } from "./config.mjs";
+import { walletAuthHeaders, saveProject } from "./config.mjs";
 import { getSdk } from "./sdk.mjs";
 import { reportSdkError, fail } from "./sdk-errors.mjs";
 import { assertAllowedValue, assertKnownFlags, flagValue, normalizeArgv, positionalArgs, resolveProjectSelector, failUnknownSubcommand } from "./argparse.mjs";
@@ -12,13 +12,13 @@ Subcommands:
   browse  [--tag <tag>]                   Browse public apps
   fork    <version_id> --name <name> [--subdomain <name>]
                                            Fork a published app into your own project
-  publish [--project <id>] [--description <desc>] [--tags <t1,t2>] [--visibility <v>] [--fork-allowed]
+  publish [--project <project_id>] [--description <desc>] [--tags <t1,t2>] [--visibility <v>] [--fork-allowed]
                                            Publish a project as an app
-  versions [--project <id>]                List published versions of a project
+  versions [--project <project_id>]                List published versions of a project
   inspect <version_id>                     Inspect a published app version
-  update  <version_id> [--project <id>] [--description <desc>] [--tags <t1,t2>] [--visibility <v>] [--fork-allowed] [--no-fork]
+  update  <version_id> [--project <project_id>] [--description <desc>] [--tags <t1,t2>] [--visibility <v>] [--fork-allowed] [--no-fork]
                                            Update a published version
-  delete  <version_id> [--project <id>]    Delete a published version
+  delete  <version_id> [--project <project_id>]    Delete a published version
 
 Legacy (still supported): the old positional forms keep working, e.g.
   run402 apps fork <version_id> <name>
@@ -72,13 +72,13 @@ Examples:
   publish: `run402 apps publish — Publish a project as an app
 
 Usage:
-  run402 apps publish [--project <id>] [options]
+  run402 apps publish [--project <project_id>] [options]
 
 Legacy (still supported):
   run402 apps publish <project_id> [options]
 
 Options (project):
-  --project <id>      Project ID to publish (defaults to the active project)
+  --project <project_id>      Project ID to publish (defaults to the active project)
 
 Options:
   --description <d>   Human-readable description of the app
@@ -93,7 +93,7 @@ Examples:
   update: `run402 apps update — Update a published version's metadata
 
 Usage:
-  run402 apps update <version_id> [--project <id>] [options]
+  run402 apps update <version_id> [--project <project_id>] [options]
 
 Legacy (still supported):
   run402 apps update <project_id> <version_id> [options]
@@ -127,7 +127,7 @@ Examples:
   versions: `run402 apps versions — List published versions of a project
 
 Usage:
-  run402 apps versions [--project <id>]
+  run402 apps versions [--project <project_id>]
 
 Legacy (still supported):
   run402 apps versions <project_id>
@@ -138,7 +138,7 @@ Examples:
   delete: `run402 apps delete — Delete a published version
 
 Usage:
-  run402 apps delete <version_id> [--project <id>]
+  run402 apps delete <version_id> [--project <project_id>]
 
 Legacy (still supported):
   run402 apps delete <project_id> <version_id>
@@ -185,8 +185,8 @@ async function fork(versionId, name, args) {
     fail({ code: "BAD_USAGE", message: `Unexpected argument for apps fork: ${positionals[expected]}` });
   }
   const opts = { subdomain: flagValue(parsedArgs, "--subdomain") ?? undefined };
-  // Preserve the aggressive early exit when no allowance is configured.
-  allowanceAuthHeaders("/fork/v1");
+  // Preserve the aggressive early exit when no local wallet is configured.
+  walletAuthHeaders("/fork/v1");
 
   try {
     const data = await getSdk().apps.fork({

package/lib/archives.mjs

@@ -1,18 +1,106 @@
-import { inspectArchive, verifyArchive } from "#sdk/node";
-import { reportSdkError, fail } from "./sdk-errors.mjs";
-import { assertKnownFlags, hasHelp, normalizeArgv, positionalArgs, failUnknownSubcommand } from "./argparse.mjs";
+import { mkdirSync, writeFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
 
-const HELP = `run402 archives — Inspect and verify portable Run402 project archives
+import { importArchiveToCore, inspectArchive, verifyArchive } from "#sdk/node";
+import { getSdk } from "./sdk.mjs";
+import { fail, reportSdkError } from "./sdk-errors.mjs";
+import { assertAllowedValue, assertKnownFlags, flagValue, hasHelp, normalizeArgv, parseIntegerFlag, positionalArgs, resolveProjectSelector, failUnknownSubcommand } from "./argparse.mjs";
+
+const HELP = `run402 archives — portable Run402 project archives
 
 Usage:
-  run402 archives inspect <archive-path> [--json]
-  run402 archives verify  <archive-path> [--json]
+  run402 archives create   [<project_id>] [--project <project_id>] [--target cloud] [options]
+  run402 archives status   [<project_id>] <archive_id> [--project <project_id>] [--target cloud] [--json]
+  run402 archives download [<project_id>] <archive_id> --output <file> [--project <project_id>] [--target cloud] [--json]
+  run402 archives inspect  <archive_path> [--json]
+  run402 archives verify   <archive_path> [--json]
+  run402 archives import   <archive_path> --name <project_name> [--target core] [options]
+
+--target names the Run402 deployment the command talks to: create, status, and
+download export from Run402 Cloud (--target cloud, the default); import loads an
+archive into a local Run402 Core (--target core, the default). inspect and verify
+are local and offline and take no target. A leading prj_... positional selects
+the project; --project defaults to the active project.
+
+Canonical agent path:
+  run402 archives create <project_id> --target cloud \\
+    --scope portable-runtime-v1 --auth stubs --consistency pause-writes \\
+    --wait --output ./project.r402ar --json
+  run402 archives verify ./project.r402ar --json
+  run402 archives import ./project.r402ar --target core --name imported-project --env-file ./required.env --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.
+
+Options for import:
+  --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.
 
 Notes:
   - Verification is local and offline. It does not require Cloud credentials.
   - Archives are untrusted input; verify checks integrity and compatibility, not trust.
 `;
 
+const TARGETS = ["cloud", "core"];
+
+/**
+ * Read --target and require the one deployment kind this verb talks to:
+ * Run402 Cloud exports archives, Run402 Core imports them.
+ */
+function requireTarget(args, verb, expected) {
+  const target = flagValue(args, "--target") ?? expected;
+  assertAllowedValue(target, TARGETS, "--target");
+  if (target !== expected) {
+    fail({
+      code: "BAD_FLAG",
+      message: `archives ${verb} runs against --target ${expected}; --target ${target} does not ${expected === "cloud" ? "export archives" : "import archives"}.`,
+      details: { flag: "--target", value: target, expected },
+      hint: expected === "cloud"
+        ? "Export with --target cloud, then load the file with: run402 archives import <archive_path> --target core"
+        : "Import into Run402 Core with --target core; export from Run402 Cloud with: run402 archives create --target cloud",
+    });
+  }
+  return target;
+}
+
+const CREATE_FLAG_VALUES = [
+  "--project",
+  "--target",
+  "--scope",
+  "--auth",
+  "--consistency",
+  "--idempotency-key",
+  "--output",
+  "--poll-interval",
+  "--timeout",
+];
+const CREATE_FLAGS = new Set([
+  ...CREATE_FLAG_VALUES,
+  "--wait",
+  "--json",
+  "--json-stream",
+  "--help",
+  "-h",
+]);
+
+const IMPORT_FLAG_VALUES = ["--target", "--name", "--env-file", "--secret", "--core-url"];
+const IMPORT_FLAGS = new Set([...IMPORT_FLAG_VALUES, "--dry-run", "--require-runnable", "--json", "--json-stream", "--help", "-h"]);
+
 export async function run(sub, rawArgs = []) {
   const all = [sub, ...rawArgs].filter(Boolean);
   if (hasHelp(all)) {
@@ -20,18 +108,206 @@ export async function run(sub, rawArgs = []) {
     return;
   }
   switch (sub) {
+    case "create": return create(rawArgs);
+    case "status": return status(rawArgs);
+    case "download": return download(rawArgs);
     case "inspect": return inspect(rawArgs);
     case "verify": return verify(rawArgs);
+    case "import": return importProject(rawArgs);
     default:
       failUnknownSubcommand("archives", sub);
   }
 }
 
+async function create(rawArgs) {
+  const args = normalizeArgv(rawArgs);
+  assertKnownFlags(args, [...CREATE_FLAGS], CREATE_FLAG_VALUES);
+  requireTarget(args, "create", "cloud");
+  const { projectId, rest } = resolveProjectSelector(args, { valueFlags: CREATE_FLAG_VALUES });
+  const extraPos = positionalArgs(rest, CREATE_FLAG_VALUES);
+  if (extraPos.length > 0) {
+    fail({ code: "BAD_USAGE", message: `Unexpected argument for archives create: ${extraPos[0]}` });
+  }
+  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 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 {
+      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, ["--project", "--target", "--output", "--json", "--help", "-h"], ["--project", "--target", "--output"]);
+  requireTarget(args, "download", "cloud");
+  const { projectId, rest } = resolveProjectSelector(args, { valueFlags: ["--project", "--target", "--output"] });
+  const pos = positionalArgs(rest, ["--project", "--target", "--output"]);
+  const [archiveId] = pos;
+  const output = flagValue(args, "--output");
+  if (!archiveId || pos.length > 1 || !output) {
+    fail({ code: "BAD_USAGE", message: "Usage: run402 archives download [<project_id>] <archive_id> --output <file> [--project <project_id>] [--target cloud] [--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 archives import ${JSON.stringify(outputPath)} --target core --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, ["--project", "--target", "--json", "--help", "-h"], ["--project", "--target"]);
+  requireTarget(args, "status", "cloud");
+  const { projectId, rest } = resolveProjectSelector(args, { valueFlags: ["--project", "--target"] });
+  const pos = positionalArgs(rest, ["--project", "--target"]);
+  const [archiveId] = pos;
+  if (!archiveId || pos.length > 1) {
+    fail({ code: "BAD_USAGE", message: "Usage: run402 archives status [<project_id>] <archive_id> [--project <project_id>] [--target cloud] [--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 archives import ${JSON.stringify(outputPath)} --target core --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));
+}
+
 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]" });
+  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));
@@ -44,7 +320,7 @@ 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]" });
+  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));
@@ -53,3 +329,90 @@ async function verify(rawArgs) {
     reportSdkError(err);
   }
 }
+
+async function importProject(rawArgs) {
+  const args = normalizeArgv(rawArgs);
+  assertKnownFlags(args, [...IMPORT_FLAGS], IMPORT_FLAG_VALUES);
+  requireTarget(args, "import", "core");
+  const archivePath = positionalArgs(args, IMPORT_FLAG_VALUES)[0];
+  if (!archivePath) {
+    fail({ code: "BAD_USAGE", message: "Usage: run402 archives import <archive_path> --name <project_name> [--target core] [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;
+}

package/lib/argparse.mjs

@@ -318,11 +318,11 @@ export function resolvePositionalProject(args, opts = {}) {
 }
 
 // Resolve the project id for a project-scoped command from BOTH accepted
-// forms — the canonical `--project <id>` flag and the legacy leading
+// forms — the canonical `--project <project_id>` flag and the legacy leading
 // positional `prj_...` — with active-project fallback (CLI-wide convention).
 //
 // Precedence:
-//   1. explicit `--project <id>` (canonical)
+//   1. explicit `--project <project_id>` (canonical)
 //   2. a leading positional starting with "prj_" (legacy compat, no warning)
 //   3. the active project (`resolveProjectId(null)`)
 //
@@ -338,7 +338,7 @@ export function resolvePositionalProject(args, opts = {}) {
 //   requireRestPositional: only treat a leading `prj_` positional as the
 //     project selector when at least one more bare positional follows (counted
 //     with opts.valueFlags). Needed by commands whose OWN attribute is itself a
-//     project id (e.g. `branches renew <branch-project-id>`).
+//     project id (e.g. `branches renew <branch_project_id>`).
 export function resolveProjectSelector(args, opts = {}) {
   const list = Array.isArray(args) ? [...args] : [];
   let flagProject = null;
@@ -361,7 +361,7 @@ export function resolveProjectSelector(args, opts = {}) {
         fail({
           code: "BAD_USAGE",
           message: `Conflicting project ids: --project ${flagProject} vs positional ${first}`,
-          hint: "Pass the project once — prefer --project <id>.",
+          hint: "Pass the project once — prefer --project <project_id>.",
           details: { project_flag: flagProject, positional: first },
         });
       }
@@ -405,7 +405,7 @@ function closestFlag(flag, candidates) {
 /**
  * Known subcommands of a command family, derived from COMMAND_MANIFEST
  * (never hand-maintained). `family` may be multi-word for nested groups
- * (e.g. "cloud archives", "email webhooks").
+ * (e.g. "deploy releases", "email webhooks").
  */
 export function knownSubcommands(family) {
   const familyWords = String(family).split(" ").filter(Boolean);