run402 4.39.1 → 4.40.0

package/cli.mjs

@@ -84,7 +84,7 @@ PLATFORM — everything else, and the things still finding a home
   transfer    Two-party project transfer (init, preview, list, accept, cancel)
   cloud       Cloud portability archive export (archives create/download/status)
   archives    Inspect and verify portable project archives locally
-  gitvault    Host-blind encrypted Git remote (init/status/push/policy/compact/prune/verify)
+  gitvault    Host-blind encrypted Git remote (init/status/push/policy/compact/prune/verify/mirror/recover)
   buzz        Buzz human/community/agent control-plane workflows
   apps        Browse and manage the app marketplace
   ai          AI translation and moderation tools

package/lib/assets.mjs

@@ -28,7 +28,7 @@ import {
 import { basename, dirname, resolve as resolvePath } from "node:path";
 import { pipeline } from "node:stream/promises";
 
-import { resolveProjectId } from "./config.mjs";
+import { resolveProjectIdAllowingLegacyEnv } from "./config.mjs";
 import { getSdk } from "./sdk.mjs";
 import { reportSdkError, fail } from "./sdk-errors.mjs";
 import { assertKnownFlags, hasHelp, normalizeArgv, parseIntegerFlag, failUnknownSubcommand } from "./argparse.mjs";
@@ -472,10 +472,9 @@ function computeDestKey(filePath, keyOpt) {
   return keyOpt;
 }
 
-async function put(projectId, argv) {
+async function put(argv) {
   const opts = parseArgs(argv);
-  opts.project = opts.project || projectId;
-  const resolvedId = resolveProjectId(opts.project);
+  const resolvedId = resolveProjectIdAllowingLegacyEnv(opts.project);
 
   if (opts.positional.length === 0) die("At least one file path is required");
   if (opts.positional.length > 1 && opts.key && !opts.key.endsWith("/")) {
@@ -499,10 +498,9 @@ async function put(projectId, argv) {
 // get
 // ---------------------------------------------------------------------------
 
-async function get(projectId, argv) {
+async function get(argv) {
   const opts = parseArgs(argv);
-  opts.project = opts.project || projectId;
-  const resolvedId = resolveProjectId(opts.project);
+  const resolvedId = resolveProjectIdAllowingLegacyEnv(opts.project);
   if (opts.positional.length === 0) die("Key required");
   if (opts.positional.length > 1) die("blob get expects exactly one key");
   if (!opts.output) die("--output <file> required");
@@ -526,10 +524,9 @@ async function get(projectId, argv) {
 // ls
 // ---------------------------------------------------------------------------
 
-async function ls(projectId, argv) {
+async function ls(argv) {
   const opts = parseArgs(argv);
-  opts.project = opts.project || projectId;
-  const resolvedId = resolveProjectId(opts.project);
+  const resolvedId = resolveProjectIdAllowingLegacyEnv(opts.project);
 
   try {
     const data = await getSdk().assets.ls(resolvedId, {
@@ -552,10 +549,9 @@ async function ls(projectId, argv) {
 // rm
 // ---------------------------------------------------------------------------
 
-async function rm(projectId, argv) {
+async function rm(argv) {
   const opts = parseArgs(argv);
-  opts.project = opts.project || projectId;
-  const resolvedId = resolveProjectId(opts.project);
+  const resolvedId = resolveProjectIdAllowingLegacyEnv(opts.project);
   if (opts.positional.length === 0) die("Key required");
   if (opts.positional.length > 1) die("blob rm expects exactly one key");
   const key = opts.positional[0];
@@ -572,10 +568,9 @@ async function rm(projectId, argv) {
 // sign
 // ---------------------------------------------------------------------------
 
-async function diagnose(projectId, argv) {
+async function diagnose(argv) {
   const opts = parseArgs(argv);
-  opts.project = opts.project || projectId;
-  const resolvedId = resolveProjectId(opts.project);
+  const resolvedId = resolveProjectIdAllowingLegacyEnv(opts.project);
   if (opts.positional.length === 0) die("URL required");
   if (opts.positional.length > 1) die("blob diagnose expects exactly one URL");
   const url = opts.positional[0];
@@ -623,10 +618,9 @@ function toCliDiagnoseEnvelope(env) {
   };
 }
 
-async function sign(projectId, argv) {
+async function sign(argv) {
   const opts = parseArgs(argv);
-  opts.project = opts.project || projectId;
-  const resolvedId = resolveProjectId(opts.project);
+  const resolvedId = resolveProjectIdAllowingLegacyEnv(opts.project);
   if (opts.positional.length === 0) die("Key required");
   if (opts.positional.length > 1) die("blob sign expects exactly one key");
   const key = opts.positional[0];
@@ -676,14 +670,13 @@ export async function run(sub, args) {
     console.log(SUB_HELP[sub] || HELP);
     process.exit(0);
   }
-  const defaultProject = process.env.RUN402_PROJECT ?? null;
   switch (sub) {
-    case "put":      await put(defaultProject, args); break;
-    case "get":      await get(defaultProject, args); break;
-    case "ls":       await ls(defaultProject, args); break;
-    case "rm":       await rm(defaultProject, args); break;
-    case "sign":     await sign(defaultProject, args); break;
-    case "diagnose": await diagnose(defaultProject, args); break;
+    case "put":      await put(args); break;
+    case "get":      await get(args); break;
+    case "ls":       await ls(args); break;
+    case "rm":       await rm(args); break;
+    case "sign":     await sign(args); break;
+    case "diagnose": await diagnose(args); break;
     default:
       failUnknownSubcommand("assets", sub);
   }

package/lib/cdn.mjs

@@ -13,7 +13,7 @@
  * are bound to a SHA at upload time and never previously cached.
  */
 
-import { resolveProjectId } from "./config.mjs";
+import { resolveProjectIdAllowingLegacyEnv } from "./config.mjs";
 import { getSdk } from "./sdk.mjs";
 import { reportSdkError, fail } from "./sdk-errors.mjs";
 import { assertKnownFlags, flagValue, normalizeArgv, parseIntegerFlag, positionalArgs, failUnknownSubcommand } from "./argparse.mjs";
@@ -91,10 +91,9 @@ function parseArgs(args) {
   return opts;
 }
 
-async function waitFresh(projectId, argv) {
+async function waitFresh(argv) {
   const opts = parseArgs(argv);
-  opts.project = opts.project || projectId;
-  const resolvedId = resolveProjectId(opts.project);
+  const resolvedId = resolveProjectIdAllowingLegacyEnv(opts.project);
   if (opts.positional.length === 0) die("URL required");
   const url = opts.positional[0];
   if (!opts.sha) die("--sha is required");
@@ -136,10 +135,9 @@ export async function run(sub, args) {
     console.log(SUB_HELP[sub] || HELP);
     process.exit(0);
   }
-  const defaultProject = process.env.RUN402_PROJECT ?? null;
   switch (sub) {
     case "wait-fresh":
-      await waitFresh(defaultProject, args);
+      await waitFresh(args);
       break;
     default:
       failUnknownSubcommand("cdn", sub);

package/lib/command-manifest.mjs

@@ -271,6 +271,26 @@ export const COMMAND_MANIFEST = [
   { path: ["gitvault", "compact"], positionals: [], projectScoped: true, legacyPositionalProject: false, minimalArgs: [], runStyle: "sub", skipBehavioral: "takes a maintenance lease and builds a checkpoint from the local repository" },
   { path: ["gitvault", "prune"], positionals: [], projectScoped: true, legacyPositionalProject: false, minimalArgs: [], runStyle: "sub", skipBehavioral: "materializes the live vault head to enumerate retention roots" },
   { path: ["gitvault", "verify"], positionals: [], projectScoped: true, legacyPositionalProject: false, minimalArgs: [], runStyle: "sub", skipBehavioral: "walks the live head chain against the keystore's authenticated pin" },
+  { path: ["gitvault", "reconcile"], positionals: [], projectScoped: true, legacyPositionalProject: false, minimalArgs: [], runStyle: "sub", skipBehavioral: "reads the live org encryption-key directory + vault envelope recipients, and may publish new key_envelope objects" },
+
+  // ── gitvault mirror (gitvault-mirror-and-recover) ────────────────────────
+  // The customer-owned ciphertext mirror — client-side only, never a server
+  // call except `sync` (lists the live vault's objects) and `status`/`verify`
+  // (a keyless read against the mirror + one live vault-record read). All
+  // five need a real keystore + (for anything but `remove`) a configured
+  // mirror destination, so — same as the gitvault family above — the gate
+  // runs structural checks only.
+  { path: ["gitvault", "mirror", "set"], positionals: [p("destination")], projectScoped: true, legacyPositionalProject: false, minimalArgs: ["s3://example-mirror-bucket"], runStyle: "sub", skipBehavioral: "writes mirror destination config beside the keystore (client-side only)" },
+  { path: ["gitvault", "mirror", "remove"], positionals: [], projectScoped: true, legacyPositionalProject: false, minimalArgs: [], runStyle: "sub", skipBehavioral: "removes mirror destination config beside the keystore (client-side only)" },
+  { path: ["gitvault", "mirror", "status"], positionals: [], projectScoped: true, legacyPositionalProject: false, minimalArgs: [], runStyle: "sub", skipBehavioral: "reads the configured mirror + the live vault record's newest_generation" },
+  { path: ["gitvault", "mirror", "sync"], positionals: [], projectScoped: true, legacyPositionalProject: false, minimalArgs: [], runStyle: "sub", skipBehavioral: "lists the live vault's stored objects and reconciles them against the configured mirror" },
+  { path: ["gitvault", "mirror", "verify"], positionals: [], projectScoped: true, legacyPositionalProject: false, minimalArgs: [], runStyle: "sub", skipBehavioral: "keyless discovery + chain verification against the configured mirror; touches no key material" },
+
+  // ── gitvault recover (gitvault-mirror-and-recover, design D4) ────────────
+  // `r402s-recover`: offline, no server call at all — reads only from the
+  // mirror source named on the command line. Not project-scoped (the source
+  // URL, not the active project, addresses the vault to recover).
+  { path: ["gitvault", "recover"], positionals: [p("source")], projectScoped: false, legacyPositionalProject: false, minimalArgs: ["s3://example-mirror-bucket", "--out", "__SCRATCH_DIR__/recover-out"], runStyle: "sub", skipBehavioral: "materializes a git repository from a mirror source, offline, with no server call" },
 
   // ── repos (vault-only porcelain, repo-first-onramp D8, task 2.6) ────────
   // `create` writes real git state into cwd and allocates a vault; `list`

package/lib/config.mjs

@@ -139,6 +139,36 @@ export function resolveProjectId(id) {
   return projectId;
 }
 
+/**
+ * `resolveProjectId`, but also honors the deprecated `RUN402_PROJECT` alias
+ * as a last-resort fallback.
+ *
+ * `RUN402_PROJECT_ID` is the canonical env var everywhere in the CLI — it's
+ * what `resolveProjectId`, `run402 doctor`, `org-context.mjs`, and every
+ * other project-scoped command read. Two commands (`cdn wait-fresh` and
+ * every `assets` subcommand) historically read the DIFFERENT, undocumented
+ * `RUN402_PROJECT` instead, so exporting the canonical `RUN402_PROJECT_ID`
+ * and running one of those two commands was a silent no-op: the export did
+ * nothing, and resolution quietly fell through to the active project.
+ *
+ * Precedence, highest first: an explicit `id` (e.g. `--project`) >
+ * `RUN402_PROJECT_ID` > the deprecated `RUN402_PROJECT` alias > the active
+ * project. The alias is only ever consulted when `RUN402_PROJECT_ID` is
+ * unset AND no explicit id was given — so it never silently overrides the
+ * canonical var or a flag. When the alias is what actually resolves the
+ * project, exactly one deprecation line goes to stderr (never stdout — the
+ * pipe contract keeps stdout pure JSON).
+ */
+export function resolveProjectIdAllowingLegacyEnv(id) {
+  if (!id && !process.env.RUN402_PROJECT_ID && process.env.RUN402_PROJECT) {
+    process.stderr.write(
+      "warning: RUN402_PROJECT is deprecated and will be removed; set RUN402_PROJECT_ID instead.\n",
+    );
+    return resolveProjectId(process.env.RUN402_PROJECT);
+  }
+  return resolveProjectId(id);
+}
+
 // Re-export core keystore functions for direct use
 export {
   configureApiBase,

package/lib/deploy-v2.mjs

@@ -1281,9 +1281,24 @@ async function applyCmd(args) {
       ...("generation" in vaulted ? { generation: vaulted.generation } : {}),
       ...("push_error" in vaulted ? { push_error: vaulted.push_error } : {}),
       ...("deploy_error" in vaulted ? { deploy_error: vaulted.deploy_error } : {}),
+      // Design D5/D6 (gitvault-human-envelopes task 4.1 + gitvault-mirror):
+      // present only when this deploy landed a new generation — the SDK
+      // omits both fields entirely on the other three outcomes rather than
+      // faking a `skipped_*` value for something that never had a chance to
+      // run. See `Gitvault.deploy`'s doc comment (sdk/src/namespaces/gitvault.ts).
+      ...("mirror_push" in vaulted ? { mirror_push: vaulted.mirror_push } : {}),
+      ...("reconcile_recipients" in vaulted ? { reconcile_recipients: vaulted.reconcile_recipients } : {}),
       next_actions: vaulted.next_actions,
       deploy: outcome.deploy,
     }, null, 2));
+    // Design D6: the mirror result is reported BESIDE the vault outcome
+    // above, on its own stderr line — a mirror failure never blocks the
+    // deploy (mirrors `run402 gitvault snapshot`'s reporting).
+    if (vaulted.mirror_push?.outcome === "pushed") {
+      console.error(`mirror: pushed generation ${vaulted.generation} (${vaulted.mirror_push.summary?.objects_copied ?? 0} object(s) copied)`);
+    } else if (vaulted.mirror_push?.outcome === "failed") {
+      console.error(`mirror: dual-push FAILED (deploy is unaffected) — ${vaulted.mirror_push.error ?? "see mirror_push.summary.errors"}`);
+    }
     // A non-activating outcome is a failed deploy even though it resolved
     // rather than threw: the five outcomes are a result type, not an error
     // channel, so the exit code has to carry the verdict.

package/lib/doctor.mjs

@@ -593,6 +593,39 @@ export async function run(sub, args = []) {
         // Echoed exactly as the SDK reported them — including the
         // doctor-persistent `grandfathered` advisory it owns.
         for (const w of gv.warnings ?? []) gaps.push(`${w.kind}: ${w.message}`);
+
+        // gitvault-mirror-and-recover task 4.3: mirror currency, reported
+        // ALONGSIDE (never in place of) the deploy-related gaps above, and
+        // never blocking `run402 deploy`'s own gate — the vault lane's
+        // outcome is unaffected regardless of mirror state (design D6).
+        // `mirror_currency` mirrors `mirror status`'s own tri-state:
+        // `current` / `stale` / `unknown` (mirror unreachable or vault
+        // unread) only STALE is actionable enough to become a warning; NO
+        // mirror configured is a purely informational, ungated advisory —
+        // most vaults have never opted in, and that is a normal shape.
+        if (gv.vault !== null && value.repo_id) {
+          try {
+            const mirrorStatus = await getSdk().gitvault.mirrorStatus({ repo_id: value.repo_id });
+            value.gitvault_mirror = {
+              configured: mirrorStatus.configured,
+              destination: mirrorStatus.destination,
+              mirrored_generation: mirrorStatus.mirrored_generation,
+              newest_generation: mirrorStatus.newest_generation,
+              is_current: mirrorStatus.is_current,
+              validity_not_freshness: mirrorStatus.validity_not_freshness,
+              keystore_still_required: mirrorStatus.keystore_still_required,
+            };
+            if (!mirrorStatus.configured) {
+              value.gitvault_mirror.advisory = "no ciphertext mirror is configured for this vault — the exit ramp is opt-in; 'run402 gitvault mirror set <destination>' to configure one.";
+            } else if (mirrorStatus.is_current === false) {
+              gaps.push(`the ciphertext mirror at ${mirrorStatus.destination} is STALE (mirrored generation ${mirrorStatus.mirrored_generation ?? "(none)"}, vault newest ${mirrorStatus.newest_generation ?? "(none)"}) — ${mirrorStatus.closing_command}`);
+            }
+          } catch {
+            // Best-effort: a mirror status read failing is never a doctor
+            // failure, and never touches the deploy-related gaps above.
+          }
+        }
+
         checks.push({
           name: "gitvault",
           status: gaps.length > 0 ? "warning" : "ok",