run402 3.7.14 → 3.8.1

package/README.md

@@ -7,13 +7,13 @@ For the full CLI reference (every flag, every subcommand) see **<https://docs.ru
 ## Install
 
 ```bash
-npm install -g run402
+npm install -g run402@latest
 ```
 
 Or run without installing:
 
 ```bash
-npx run402 <command>
+npx -y run402@latest <command>
 ```
 
 ## 30-second start
@@ -29,6 +29,8 @@ That's a real Postgres database + a deployed static site, paid for autonomously
 
 Every command prints **JSON to stdout**, **JSON errors to stderr**, and exits **0 on success / 1 on failure**. Designed for shells, scripts, and agent loops — pipe everything to `jq`.
 
+Stale CLI notices are advisory and never pollute success stdout. When a cached npm check says a newer `run402` exists, normal commands may emit a structured `cli.update_available` JSON object on stderr, or an NDJSON event in `--json-stream`. Run `run402 doctor --refresh` for the explicit live check; it reports whether this invocation is local, global, npx/npm exec, pnpm/yarn/bun, or custom, and includes an `upgrade_client` action with both `command` and `argv`.
+
 ## Common commands
 
 ### One-command app deploy

package/cli.mjs

@@ -24,6 +24,7 @@ Commands:
   init mpp    Set up with MPP payment rail (Tempo Moderato testnet)
   status      Show full account state (allowance, balance, tier, projects)
   wallets     Manage multiple named wallets (list, new, use, rename, bind, import)
+  credentials Manage local credential material (project-keys)
   allowance   Manage your agent allowance (create, fund, balance, status)
   tier        Manage tier subscription (status, set)
   projects    Manage projects (provision, list, query, inspect, delete)
@@ -154,6 +155,11 @@ switch (cmd) {
     await run(sub, rest);
     break;
   }
+  case "credentials": {
+    const { run } = await import("./lib/credentials.mjs");
+    await run(sub, rest);
+    break;
+  }
   case "allowance": {
     const { run } = await import("./lib/allowance.mjs");
     await run(sub, rest);

package/core-dist/config.js

@@ -119,8 +119,17 @@ export function getConfigDir() {
     return profile === DEFAULT_PROFILE ? base : join(base, "profiles", profile);
 }
 export function getKeystorePath() {
+    return getProjectCredentialsPath();
+}
+export function getLegacyProjectsPath() {
     return join(getConfigDir(), "projects.json");
 }
+export function getProjectCredentialsPath() {
+    return join(getConfigDir(), "credentials", "project-keys.v1.json");
+}
+export function getProfileStatePath() {
+    return join(getConfigDir(), "state.json");
+}
 export function getApiTargetConfigPath() {
     return join(getConfigDir(), "target.json");
 }

package/core-dist/keystore.js

@@ -1,7 +1,8 @@
-import { readFileSync, writeFileSync, mkdirSync, renameSync, chmodSync, rmdirSync } from "node:fs";
+import { existsSync, readFileSync, writeFileSync, mkdirSync, renameSync, chmodSync, rmdirSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { randomBytes } from "node:crypto";
-import { getKeystorePath } from "./config.js";
+import { getLegacyProjectsPath, getProjectCredentialsPath } from "./config.js";
+import { clearActiveProjectId as clearProfileActiveProjectId, getActiveProjectId as getProfileActiveProjectId, recordMigration, setActiveProjectId as setProfileActiveProjectId, } from "./profile-state.js";
 function withFileLock(path, fn, { retries = 200, delayMs = 20 } = {}) {
     const lockDir = path + ".lock";
     mkdirSync(dirname(path), { recursive: true });
@@ -29,56 +30,107 @@ function withFileLock(path, fn, { retries = 200, delayMs = 20 } = {}) {
     }
     throw new Error(`Could not acquire keystore lock after ${retries} retries: ${lockDir}`);
 }
-/**
- * Load the keystore from disk.
- * Auto-migrates legacy formats:
- * - Array format (CLI legacy): [{project_id, ...}] → {projects: {id: {...}}}
- * - Old field name: expires_at → lease_expires_at
- */
-export function loadKeyStore(path) {
-    const p = path ?? getKeystorePath();
-    try {
-        const data = readFileSync(p, "utf-8");
-        const parsed = JSON.parse(data);
-        if (Array.isArray(parsed)) {
-            const projects = {};
-            for (const item of parsed) {
-                if (item.project_id) {
-                    projects[item.project_id] = {
-                        anon_key: item.anon_key,
-                        service_key: item.service_key,
-                        ...(item.site_url && { site_url: item.site_url }),
-                        ...(item.deployed_at && { deployed_at: item.deployed_at }),
-                    };
-                }
+function normalizeParsedKeyStore(parsed) {
+    if (Array.isArray(parsed)) {
+        const projects = {};
+        for (const item of parsed) {
+            if (item.project_id) {
+                projects[item.project_id] = {
+                    anon_key: item.anon_key,
+                    service_key: item.service_key,
+                    ...(item.site_url && { site_url: item.site_url }),
+                    ...(item.deployed_at && { deployed_at: item.deployed_at }),
+                    cached_at: new Date().toISOString(),
+                    source: "legacy_projects_json",
+                };
             }
-            return { projects };
         }
-        if (parsed && typeof parsed === "object" && parsed.projects) {
-            for (const proj of Object.values(parsed.projects)) {
-                const rec = proj;
-                delete rec.tier;
-                delete rec.lease_expires_at;
-                delete rec.expires_at;
-            }
-            return {
-                ...(parsed.active_project_id && { active_project_id: parsed.active_project_id }),
-                ...(parsed.previous_active_project_id && { previous_active_project_id: parsed.previous_active_project_id }),
-                projects: parsed.projects,
-            };
+        return { version: 1, source: "local_cache", projects };
+    }
+    if (parsed && typeof parsed === "object" && "projects" in parsed) {
+        const obj = parsed;
+        const rawProjects = obj.projects && typeof obj.projects === "object" && !Array.isArray(obj.projects)
+            ? obj.projects
+            : {};
+        const projects = {};
+        for (const [id, proj] of Object.entries(rawProjects)) {
+            const rec = { ...proj };
+            delete rec.tier;
+            delete rec.lease_expires_at;
+            delete rec.expires_at;
+            projects[id] = rec;
         }
-        return { projects: {} };
+        return {
+            version: 1,
+            source: "local_cache",
+            ...(typeof obj.active_project_id === "string" && { active_project_id: obj.active_project_id }),
+            ...(typeof obj.previous_active_project_id === "string" && { previous_active_project_id: obj.previous_active_project_id }),
+            projects,
+            ...(typeof obj.migrated_from === "string" && { migrated_from: obj.migrated_from }),
+            ...(typeof obj.migrated_at === "string" && { migrated_at: obj.migrated_at }),
+        };
+    }
+    return { version: 1, source: "local_cache", projects: {} };
+}
+function loadParsedKeyStore(path) {
+    try {
+        return normalizeParsedKeyStore(JSON.parse(readFileSync(path, "utf-8")));
     }
     catch {
-        return { projects: {} };
+        return { version: 1, source: "local_cache", projects: {} };
     }
 }
+function migrateLegacyProjectsJson(targetPath) {
+    const legacyPath = getLegacyProjectsPath();
+    if (existsSync(targetPath) || !existsSync(legacyPath))
+        return;
+    const legacy = loadParsedKeyStore(legacyPath);
+    const migratedAt = new Date().toISOString();
+    const cache = {
+        version: 1,
+        source: "local_cache",
+        projects: legacy.projects,
+        migrated_from: legacyPath,
+        migrated_at: migratedAt,
+    };
+    saveKeyStore(cache, targetPath);
+    if (legacy.active_project_id) {
+        setProfileActiveProjectId(legacy.active_project_id);
+    }
+    recordMigration("projects_json_import", {
+        legacy_path: legacyPath,
+        cache_path: targetPath,
+        project_count: Object.keys(legacy.projects).length,
+        imported_at: migratedAt,
+    });
+}
+/**
+ * Load the project-key credential cache from disk.
+ * Auto-imports legacy `projects.json` formats into the new cache path when using
+ * the default location:
+ * - Array format (CLI legacy): [{project_id, ...}] → {projects: {id: {...}}}
+ * - Object format: {active_project_id, projects} → credentials cache + state.json
+ * - Old metadata fields: tier/expires_at/lease_expires_at are stripped
+ */
+export function loadKeyStore(path) {
+    const p = path ?? getProjectCredentialsPath();
+    if (!path)
+        migrateLegacyProjectsJson(p);
+    return loadParsedKeyStore(p);
+}
 export function saveKeyStore(store, path) {
-    const p = path ?? getKeystorePath();
+    const p = path ?? getProjectCredentialsPath();
     const dir = dirname(p);
     mkdirSync(dir, { recursive: true });
-    const tmp = join(dir, `.projects.${randomBytes(4).toString("hex")}.tmp`);
-    writeFileSync(tmp, JSON.stringify(store, null, 2), { mode: 0o600 });
+    const cache = {
+        version: 1,
+        source: "local_cache",
+        ...(store.migrated_from ? { migrated_from: store.migrated_from } : {}),
+        ...(store.migrated_at ? { migrated_at: store.migrated_at } : {}),
+        projects: store.projects,
+    };
+    const tmp = join(dir, `.project-keys.${randomBytes(4).toString("hex")}.tmp`);
+    writeFileSync(tmp, JSON.stringify(cache, null, 2), { mode: 0o600 });
     renameSync(tmp, p);
     chmodSync(p, 0o600);
 }
@@ -87,55 +139,38 @@ export function getProject(projectId, path) {
     return store.projects[projectId];
 }
 export function saveProject(projectId, project, path) {
-    const p = path ?? getKeystorePath();
+    const p = path ?? getProjectCredentialsPath();
     withFileLock(p, () => {
         const store = loadKeyStore(p);
-        store.projects[projectId] = project;
+        store.projects[projectId] = { ...project, cached_at: project.cached_at ?? new Date().toISOString() };
         saveKeyStore(store, p);
     });
 }
 export function updateProject(projectId, update, path) {
-    const p = path ?? getKeystorePath();
+    const p = path ?? getProjectCredentialsPath();
     withFileLock(p, () => {
         const store = loadKeyStore(p);
         const existing = store.projects[projectId];
         if (existing) {
-            store.projects[projectId] = { ...existing, ...update };
+            store.projects[projectId] = { ...existing, ...update, cached_at: existing.cached_at ?? new Date().toISOString() };
             saveKeyStore(store, p);
         }
     });
 }
 export function removeProject(projectId, path) {
-    const p = path ?? getKeystorePath();
+    const p = path ?? getProjectCredentialsPath();
     withFileLock(p, () => {
         const store = loadKeyStore(p);
         delete store.projects[projectId];
-        if (store.active_project_id === projectId) {
-            const fallback = store.previous_active_project_id;
-            if (fallback && fallback !== projectId && store.projects[fallback]) {
-                store.active_project_id = fallback;
-            }
-            else {
-                delete store.active_project_id;
-            }
-            delete store.previous_active_project_id;
-        }
         saveKeyStore(store, p);
     });
+    if (!path)
+        clearProfileActiveProjectId(projectId);
 }
 export function getActiveProjectId(path) {
-    const store = loadKeyStore(path);
-    return store.active_project_id;
+    return getProfileActiveProjectId(path);
 }
 export function setActiveProjectId(projectId, path) {
-    const p = path ?? getKeystorePath();
-    withFileLock(p, () => {
-        const store = loadKeyStore(p);
-        if (store.active_project_id && store.active_project_id !== projectId) {
-            store.previous_active_project_id = store.active_project_id;
-        }
-        store.active_project_id = projectId;
-        saveKeyStore(store, p);
-    });
+    setProfileActiveProjectId(projectId, path);
 }
 //# sourceMappingURL=keystore.js.map

package/core-dist/profile-state.js

@@ -0,0 +1,137 @@
+import { readFileSync, writeFileSync, mkdirSync, renameSync, chmodSync, rmdirSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { randomBytes } from "node:crypto";
+import { getActiveProfile, getApiBase, getProfileStatePath } from "./config.js";
+function withFileLock(path, fn, { retries = 200, delayMs = 20 } = {}) {
+    const lockDir = path + ".lock";
+    mkdirSync(dirname(path), { recursive: true });
+    for (let i = 0; i < retries; i++) {
+        try {
+            mkdirSync(lockDir, { mode: 0o700 });
+        }
+        catch (e) {
+            const code = e.code;
+            if (code !== "EEXIST")
+                throw e;
+            const until = Date.now() + delayMs;
+            while (Date.now() < until) { /* spin */ }
+            continue;
+        }
+        try {
+            return fn();
+        }
+        finally {
+            try {
+                rmdirSync(lockDir);
+            }
+            catch { /* best-effort */ }
+        }
+    }
+    throw new Error(`Could not acquire profile-state lock after ${retries} retries: ${lockDir}`);
+}
+export function loadProfileState(path) {
+    const p = path ?? getProfileStatePath();
+    try {
+        const parsed = JSON.parse(readFileSync(p, "utf-8"));
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+            return {};
+        return parsed;
+    }
+    catch {
+        return {};
+    }
+}
+export function saveProfileState(state, path) {
+    const p = path ?? getProfileStatePath();
+    const dir = dirname(p);
+    mkdirSync(dir, { recursive: true });
+    const tmp = join(dir, `.state.${randomBytes(4).toString("hex")}.tmp`);
+    writeFileSync(tmp, JSON.stringify({ version: 1, ...state }, null, 2), { mode: 0o600 });
+    renameSync(tmp, p);
+    chmodSync(p, 0o600);
+}
+export function defaultActiveProjectScope(scope = {}) {
+    return {
+        api_base: scope.api_base ?? getApiBase(),
+        profile: scope.profile ?? getActiveProfile(),
+        principal: scope.principal ?? null,
+    };
+}
+export function activeProjectScopeKey(scope = {}) {
+    const resolved = defaultActiveProjectScope(scope);
+    return JSON.stringify({
+        api_base: resolved.api_base,
+        profile: resolved.profile,
+        principal: resolved.principal ?? "unknown",
+    });
+}
+export function getActiveProjectId(path, scope = {}) {
+    const state = loadProfileState(path);
+    const key = activeProjectScopeKey(scope);
+    return state.active_projects?.[key]?.project_id ?? state.active_project_id;
+}
+export function setActiveProjectId(projectId, path, scope = {}) {
+    const p = path ?? getProfileStatePath();
+    withFileLock(p, () => {
+        const state = loadProfileState(p);
+        const key = activeProjectScopeKey(scope);
+        const resolved = defaultActiveProjectScope(scope);
+        const current = state.active_projects?.[key]?.project_id ?? state.active_project_id;
+        const previous = current && current !== projectId ? current : undefined;
+        state.active_projects = state.active_projects ?? {};
+        state.active_projects[key] = {
+            project_id: projectId,
+            ...(previous ? { previous_project_id: previous } : {}),
+            api_base: resolved.api_base,
+            principal: resolved.principal ?? null,
+            profile: resolved.profile,
+            updated_at: new Date().toISOString(),
+        };
+        state.active_project_id = projectId;
+        if (previous)
+            state.previous_active_project_id = previous;
+        else
+            delete state.previous_active_project_id;
+        saveProfileState(state, p);
+    });
+}
+export function clearActiveProjectId(projectId, path, scope = {}) {
+    const p = path ?? getProfileStatePath();
+    withFileLock(p, () => {
+        const state = loadProfileState(p);
+        const key = activeProjectScopeKey(scope);
+        const scoped = state.active_projects?.[key];
+        if (scoped?.project_id === projectId && state.active_projects) {
+            if (scoped.previous_project_id) {
+                state.active_projects[key] = {
+                    ...scoped,
+                    project_id: scoped.previous_project_id,
+                    previous_project_id: undefined,
+                    updated_at: new Date().toISOString(),
+                };
+            }
+            else {
+                delete state.active_projects[key];
+            }
+        }
+        if (state.active_project_id === projectId) {
+            if (state.previous_active_project_id && state.previous_active_project_id !== projectId) {
+                state.active_project_id = state.previous_active_project_id;
+            }
+            else {
+                delete state.active_project_id;
+            }
+            delete state.previous_active_project_id;
+        }
+        saveProfileState(state, p);
+    });
+}
+export function recordMigration(marker, value, path) {
+    const p = path ?? getProfileStatePath();
+    withFileLock(p, () => {
+        const state = loadProfileState(p);
+        state.migrations = { ...(state.migrations ?? {}), [marker]: value };
+        saveProfileState(state, p);
+    });
+}
+//# sourceMappingURL=profile-state.js.map

package/lib/config.mjs

@@ -7,8 +7,11 @@ import {
   getApiBase,
   getApiBaseSource,
   getApiTargetKind,
+  getActiveProfile,
   getConfigDir,
-  getKeystorePath,
+  getLegacyProjectsPath,
+  getProfileStatePath,
+  getProjectCredentialsPath,
   getAllowancePath,
   configureApiBase,
   isCoreApiTarget,
@@ -18,18 +21,22 @@ 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";
+import { initializeWalletAction, selectProjectAction } 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
 // before wallet resolution). Production code (init/doctor/allowance) uses these.
 export function configDir() { return getConfigDir(); }
 export function allowanceFile() { return getAllowancePath(); }
-export function projectsFile() { return getKeystorePath(); }
+export function projectCredentialsFile() { return getProjectCredentialsPath(); }
+export function profileStateFile() { return getProfileStatePath(); }
+export function legacyProjectsFile() { return getLegacyProjectsPath(); }
+export function projectsFile() { return projectCredentialsFile(); }
 export function apiBase() { return getApiBase(); }
 export function apiBaseSource() { return getApiBaseSource(); }
 export function apiTargetKind() { return getApiTargetKind(); }
 export function coreTarget() { return isCoreApiTarget(); }
+export function activeProfile() { return getActiveProfile(); }
 
 // Snapshot constants, retained for backward compatibility (tests, the OpenClaw
 // config re-export). These are evaluated when this module is first imported.
@@ -39,7 +46,9 @@ export function coreTarget() { return isCoreApiTarget(); }
 // prefer the getters above.
 export const CONFIG_DIR = getConfigDir();
 export const ALLOWANCE_FILE = getAllowancePath();
-export const PROJECTS_FILE = getKeystorePath();
+export const PROJECTS_FILE = getProjectCredentialsPath();
+export const PROJECT_CREDENTIALS_FILE = getProjectCredentialsPath();
+export const PROFILE_STATE_FILE = getProfileStatePath();
 
 // API base is independent of the active wallet, so a module-load snapshot is safe.
 export const API = getApiBase();
@@ -89,41 +98,42 @@ export function findProject(id) {
   const p = getProject(id);
   if (!p) {
     const idStr = id ?? "";
-    const hint = idStr && !String(idStr).startsWith("prj_")
-      ? `project IDs start with "prj_". Check that the argument order is <project_id> <name>.`
-      : undefined;
     fail({
-      code: "PROJECT_NOT_FOUND",
-      message: `Project ${idStr} not found in local registry.`,
-      hint,
-      details: { project_id: idStr, source: "local_registry" },
-      next_actions: [createProjectAction()],
+      code: "PROJECT_CREDENTIAL_NOT_FOUND",
+      message: `No local project credentials cached for ${idStr}.`,
+      hint: "Use a principal-auth command, or import project keys with `run402 credentials project-keys import --project <id> --service-key-stdin`.",
+      details: { project_id: idStr, source: "local_cache", cache_path: projectCredentialsFile(), wallet: activeProfile(), profile: activeProfile() },
+      next_actions: [{
+        type: "run_command",
+        command: `run402 credentials project-keys status --project ${idStr || "<id>"}`,
+        why: "Inspect the local project-key cache without revealing secrets.",
+      }],
     });
   }
   return p;
 }
 
 export function resolveProject(id) {
-  const projectId = id || getActiveProjectId();
+  const projectId = id || process.env.RUN402_PROJECT_ID || getActiveProjectId();
   if (!projectId) {
     fail({
-      code: "NO_ACTIVE_PROJECT",
+      code: "PROJECT_REQUIRED",
       message: "no project specified and no active project set.",
-      hint: "Run: run402 projects provision",
-      next_actions: [createProjectAction()],
+      hint: "Pass --project <id>, set RUN402_PROJECT_ID, or run: run402 projects use <id>",
+      next_actions: [selectProjectAction()],
     });
   }
   return findProject(projectId);
 }
 
 export function resolveProjectId(id) {
-  const projectId = id || getActiveProjectId();
+  const projectId = id || process.env.RUN402_PROJECT_ID || getActiveProjectId();
   if (!projectId) {
     fail({
-      code: "NO_ACTIVE_PROJECT",
+      code: "PROJECT_REQUIRED",
       message: "no project specified and no active project set.",
-      hint: "Run: run402 projects provision",
-      next_actions: [createProjectAction()],
+      hint: "Pass --project <id>, set RUN402_PROJECT_ID, or run: run402 projects use <id>",
+      next_actions: [selectProjectAction()],
     });
   }
   return projectId;
@@ -134,6 +144,7 @@ export {
   configureApiBase,
   isCoreApiTarget,
   readApiTargetConfig,
+  getProject,
   loadKeyStore,
   saveProject,
   updateProject,