@getfootgun/keys 0.2.0-rc.1 → 0.2.0-rc.3

package/lib/dispatch.d.mts

@@ -1,2 +1,4 @@
 export const COMMANDS: string[];
-export function dispatch(argv: string[], libDir?: string, importModule?: (specifier: string) => Promise<{ run(args: string[]): unknown }>): Promise<number>;
+type RuntimeOpts = { platform?: string; arch?: string; env?: Record<string, string | undefined>; exists?: (path: string) => boolean };
+export function missingRuntimeMessage(e: unknown, opts?: RuntimeOpts): string | null;
+export function dispatch(argv: string[], libDir?: string, importModule?: (specifier: string) => Promise<{ run(args: string[]): unknown }>, opts?: RuntimeOpts & { print?: (line: string) => void }): Promise<number>;

package/lib/dispatch.mjs

@@ -8,7 +8,20 @@ const LIB = fileURLToPath(new URL(".", import.meta.url));
 // "Not built yet" means the subcommand's own module file is absent. Any error thrown while loading
 // an existing module (such as a missing dependency) propagates. The module is imported by file: URL,
 // since Windows rejects a plain absolute path (C:\...) as an ESM specifier.
-export async function dispatch(argv, libDir = LIB, importModule = (specifier) => import(specifier)) {
+// The Windows key-store binding needs Microsoft's Visual C++ Runtime (vcruntime140.dll), which a fresh
+// Windows may not have. Then loading fails with "Cannot find native binding"; say what to install instead.
+export function missingRuntimeMessage(e, { platform = process.platform, arch = process.arch, env = process.env, exists = existsSync } = {}) {
+  if (platform !== "win32") return null;
+  if (!/native binding/i.test(String(e?.message ?? ""))) return null;
+  if (exists(join(env.SystemRoot ?? "C:\\Windows", "System32", "vcruntime140.dll"))) return null;
+  const a = arch === "arm64" ? "arm64" : arch === "ia32" ? "x86" : "x64";
+  return [
+    "Footgun Keys needs Microsoft's Visual C++ Runtime, which this PC does not have yet.",
+    `Install it from https://aka.ms/vs/17/release/vc_redist.${a}.exe, then run npx.cmd @getfootgun/keys setup again.`,
+  ].join("\n");
+}
+
+export async function dispatch(argv, libDir = LIB, importModule = (specifier) => import(specifier), opts = {}) {
   const [cmd, ...args] = argv;
   if (!COMMANDS.includes(cmd)) {
     console.error(`Usage: footgun-keys <${COMMANDS.join("|")}> [args]`);
@@ -19,6 +32,14 @@ export async function dispatch(argv, libDir = LIB, importModule = (specifier) =>
     console.error("not built yet");
     return 2;
   }
-  const mod = await importModule(pathToFileURL(file).href);
+  let mod;
+  try {
+    mod = await importModule(pathToFileURL(file).href);
+  } catch (e) {
+    const msg = missingRuntimeMessage(e, opts);
+    if (!msg) throw e;
+    (opts.print ?? console.error)(msg);
+    return 1;
+  }
   return (await mod.run(args)) ?? 0;
 }

package/lib/envrefs.d.mts

@@ -0,0 +1,7 @@
+export const ENV_FILES: string[];
+export const PUBLIC_PREFIX: RegExp;
+export function isManaged(name: string): boolean;
+export function isLocalValue(value: string): boolean;
+export function codeNames(projectPath: string): Promise<string[]>;
+export function parseEnv(text: string): Map<string, string>;
+export function envFileValues(projectPath: string): Promise<Map<string, { value: string; file: string }>>;

package/lib/envrefs.mjs

@@ -0,0 +1,88 @@
+import { readdir, readFile, stat } from "node:fs/promises";
+import { join } from "node:path";
+
+// Which env var names a project uses, and which values its local env files hold. Only names are read from
+// code; values are read from env files and stay in the caller (never in a result).
+
+const SKIP_DIRS = new Set(["node_modules", "dist", "build", "out", "coverage", "vendor", "venv", "__pycache__", "target"]);
+const EXTENSIONS = /\.(?:[cm]?[jt]sx?|vue|svelte|astro|py|prisma)$/;
+const MAX_FILES = 5000;
+const MAX_BYTES = 1024 * 1024;
+const NAME = "[A-Z_][A-Z0-9_]*";
+const PATTERNS = [
+  new RegExp(`process\\.env\\.(${NAME})\\b`, "g"),
+  new RegExp(`process\\.env\\[\\s*["'\`](${NAME})["'\`]\\s*\\]`, "g"),
+  new RegExp(`import\\.meta\\.env\\.(${NAME})\\b`, "g"),
+  new RegExp(`Deno\\.env\\.get\\(\\s*["'](${NAME})["']`, "g"),
+  new RegExp(`os\\.environ\\[\\s*["'](${NAME})["']\\s*\\]`, "g"),
+  new RegExp(`os\\.(?:environ\\.get|getenv)\\(\\s*["'](${NAME})["']`, "g"),
+  new RegExp(`\\benv\\(\\s*["'](${NAME})["']\\s*\\)`, "g"), // prisma schema and env() helpers
+];
+const DESTRUCTURE = /\{([^{}]*)\}\s*=\s*(?:process\.env|import\.meta\.env)\b/g;
+
+// Read in this order; the first file that sets a name wins, so production values beat development ones.
+export const ENV_FILES = [".env.production.local", ".env.production", ".env.local", ".env"];
+// Names the platform or the framework sets itself.
+const MANAGED = /^(?:VERCEL|VERCEL_.*|RAILWAY_.*|NODE_ENV|PORT|CI|MODE|DEV|PROD|SSR|BASE_URL|NEXT_RUNTIME|HOSTNAME|PWD|HOME)$/;
+export const PUBLIC_PREFIX = /^(?:NEXT_PUBLIC_|VITE_|PUBLIC_|EXPO_PUBLIC_|NUXT_PUBLIC_|REACT_APP_)/;
+// A value that only works on the developer's machine must never reach a deployed app.
+const LOCAL = /\b(?:localhost|127\.0\.0\.1|0\.0\.0\.0|host\.docker\.internal|\[::1\])\b/i;
+
+export const isManaged = (name) => MANAGED.test(name);
+export const isLocalValue = (value) => LOCAL.test(value);
+
+/** Env var names referenced in source, sorted. */
+export async function codeNames(projectPath) {
+  const names = new Set();
+  let files = 0;
+  async function walk(dir) {
+    let entries;
+    try { entries = await readdir(dir, { withFileTypes: true }); } catch { return; }
+    for (const e of entries) {
+      if (files >= MAX_FILES) return;
+      if (e.name.startsWith(".") || SKIP_DIRS.has(e.name)) continue;
+      const p = join(dir, e.name);
+      if (e.isDirectory()) { await walk(p); continue; }
+      if (!e.isFile() || !EXTENSIONS.test(e.name)) continue;
+      files++;
+      try { if ((await stat(p)).size > MAX_BYTES) continue; } catch { continue; }
+      let text;
+      try { text = await readFile(p, "utf8"); } catch { continue; }
+      for (const re of PATTERNS) for (const m of text.matchAll(re)) names.add(m[1]);
+      for (const m of text.matchAll(DESTRUCTURE)) {
+        for (const part of m[1].split(",")) {
+          const n = part.trim().split(/[\s:=]/)[0];
+          if (new RegExp(`^${NAME}$`).test(n)) names.add(n);
+        }
+      }
+    }
+  }
+  await walk(projectPath);
+  return [...names].filter((n) => !isManaged(n)).sort();
+}
+
+// KEY=value lines as dotenv reads them: optional "export ", quotes stripped, inline comments after an unquoted value dropped.
+export function parseEnv(text) {
+  const out = new Map();
+  for (const raw of text.split(/\r?\n/)) {
+    const m = /^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)$/.exec(raw);
+    if (!m) continue;
+    let v = m[2].trim();
+    const q = v[0];
+    if ((q === '"' || q === "'" || q === "`") && v.lastIndexOf(q) > 0) v = v.slice(1, v.lastIndexOf(q));
+    else v = v.replace(/\s+#.*$/, "");
+    if (!out.has(m[1])) out.set(m[1], v);
+  }
+  return out;
+}
+
+/** name -> { value, file } from the project's local env files, in ENV_FILES order. */
+export async function envFileValues(projectPath) {
+  const out = new Map();
+  for (const file of ENV_FILES) {
+    let text;
+    try { text = await readFile(join(projectPath, file), "utf8"); } catch { continue; }
+    for (const [name, value] of parseEnv(text)) if (!out.has(name) && value !== "") out.set(name, { value, file });
+  }
+  return out;
+}

package/lib/mcp.d.mts

@@ -4,7 +4,7 @@ import type { Server } from "./server.mjs";
 export type ToolResult = { content: { type: "text"; text: string }[]; isError?: boolean };
 export const SERVER_INFO: { name: string; version: string };
 export const INSTRUCTIONS: string;
-export const SPECS: Record<"keys_list" | "keys_guides" | "keys_write_env" | "keys_request" | "keys_check", { description: string; inputSchema: import("zod").ZodType }>;
+export const SPECS: Record<"keys_list" | "keys_guides" | "keys_write_env" | "keys_request" | "keys_check" | "keys_sync_env", { description: string; inputSchema: import("zod").ZodType }>;
 export function buildTools(deps: {
   vault: Vault;
   server: Server;
@@ -19,6 +19,7 @@ export function buildTools(deps: {
   keys_write_env(args: { project_path: string; env_vars: string[] }): Promise<ToolResult>;
   keys_request(args: { provider: string; project_path: string; env_vars?: string[]; label?: string; session?: string }): Promise<ToolResult>;
   keys_check(args?: { env_var?: string }): Promise<ToolResult>;
+  keys_sync_env(args: { project_path: string; platform: "vercel" | "railway"; apply?: boolean; overwrite?: string[]; targets?: ("production" | "preview" | "development")[] }): Promise<ToolResult>;
 };
 export function toolsFor(platform: string, makeDeps: () => Parameters<typeof buildTools>[0]): ReturnType<typeof buildTools>;
 export function runMcp(): Promise<void>;

package/lib/mcp.mjs

@@ -11,6 +11,7 @@ import { SITE } from "./paths.mjs";
 import { openUrl } from "./platform.mjs";
 import { groupByProviderLabel, healthRecord } from "./check.mjs";
 import { isProtected } from "./protect.mjs";
+import { syncEnv, VERCEL_TARGETS } from "./sync.mjs";
 import { LABEL_RE, FREE_GUIDES } from "../shared/contract.mjs";
 
 // Every result here carries names, statuses and messages. A key value is never read into a result.
@@ -18,7 +19,7 @@ const HELPER_VERSION = JSON.parse(readFileSync(new URL("../package.json", import
 export const SERVER_INFO = { name: "footgun-keys", version: HELPER_VERSION };
 
 export const INSTRUCTIONS =
-  "When a project needs a third-party API key, call keys_request instead of asking the user to paste it. Tool results never contain key values.";
+  "When a project needs a third-party API key, call keys_request instead of asking the user to paste it. Before or after deploying to Vercel or Railway, call keys_sync_env to find env vars the deployed app is missing. Tool results never contain key values.";
 
 const NAME_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
 const PROVIDER_RE = /^[a-z0-9][a-z0-9-]{0,63}$/; // the server's guide slug rule
@@ -189,6 +190,14 @@ export function buildTools({ vault, server, openUrl, home, now = () => new Date(
       }
       return reply(lines.join("\n"));
     },
+
+    async keys_sync_env({ project_path, platform, apply = false, overwrite = [], targets }) {
+      const blocked = await planBlock("keys_sync_env");
+      if (blocked) return reply(blocked);
+      if (overwrite.some((n) => !NAME_RE.test(n))) return reply("One of the names is not a valid env var name.", true);
+      const r = await syncEnv({ projectPath: project_path, platform, apply, overwrite, targets, vault, fetch: fetchFn, home });
+      return reply(r.text, r.isError);
+    },
   };
 
   // Poll the session file once a second, up to waitMs.
@@ -239,6 +248,16 @@ export const SPECS = {
     description: "Test saved keys against their provider and record whether each still works.",
     inputSchema: z.object({ env_var: z.string().optional().describe("Check just this env var. Defaults to all saved keys.") }),
   },
+  keys_sync_env: {
+    description: "Compare the env vars this project uses with what its Vercel or Railway project has, and push the missing ones from the Keychain or the project's env file. Without apply it only reports; show the report to the user and get their yes before apply. Existing variables are never changed unless named in overwrite. Never shows values.",
+    inputSchema: z.object({
+      project_path: z.string().describe("Absolute path of the project folder (linked with vercel link or railway link)."),
+      platform: z.enum(["vercel", "railway"]).describe("Where the app is deployed."),
+      apply: z.boolean().optional().describe("Push the missing variables. Defaults to false: report only."),
+      overwrite: names.optional().describe("Variables already set on the platform to replace with the local value."),
+      targets: z.array(z.enum(VERCEL_TARGETS)).optional().describe("Vercel only. Defaults to production and preview."),
+    }),
+  },
 };
 
 // On other platforms the server still answers initialize and tools/list (so a plugin that starts it does not

package/lib/schedule.d.mts

@@ -8,4 +8,5 @@ export function registerNativeHost(opts: {
   manifest: { name: string; [key: string]: unknown };
 }): Promise<void>;
 export function healthTaskXml(launcher: string, now?: Date): string;
-export function scheduleDaily(opts: { platform: string; exec: Exec; home: string; launcher: string; uid?: number; support?: string; now?: () => Date }): Promise<void>;
+export function scheduleDaily(opts: { platform: string; exec: Exec; home: string; launcher: string; uid?: number; support?: string; now?: () => Date }): Promise<{ when: "daily" } | { when: "signin"; reason: string }>;
+export function firstLine(e: unknown): string;

package/lib/schedule.mjs

@@ -6,6 +6,8 @@ import { launchdPlist } from "./launchd.mjs";
 const LABEL = "com.getfootgun.keys.health";
 const WIN_HOST_KEY = "HKCU\\Software\\Google\\Chrome\\NativeMessagingHosts\\com.getfootgun.keys";
 const TASK = "Footgun Keys health";
+const WIN_RUN_KEY = "HKCU\\Software\\Microsoft\\Windows\\CurrentVersion\\Run";
+const WIN_RUN_VALUE = "FootgunKeysHealth";
 
 async function loadAgent(exec, uid, plist) {
   try {
@@ -79,19 +81,35 @@ export function healthTaskXml(launcher, now = new Date()) {
   ].join("\r\n");
 }
 
-// Daily 9:30 run of "<launcher> health". Throws if the OS scheduler refuses.
+// Daily 9:30 run of "<launcher> health". Resolves { when: "daily" }, or on a Windows PC that blocks
+// Task Scheduler { when: "signin", reason } after falling back to a per-user Run entry that checks
+// at each sign-in. Throws if neither works.
 export async function scheduleDaily({ platform, exec, home, launcher, uid, support, now = () => new Date() }) {
   if (platform === "win32") {
     // schtasks reads /XML files as UTF-16LE with a byte order mark.
     const xmlPath = win32.join(support, "health-task.xml");
     const body = Buffer.from(healthTaskXml(launcher, now()), "utf16le");
     await writePrivate(xmlPath, Buffer.concat([Buffer.from([0xff, 0xfe]), body]));
-    await exec("schtasks", ["/Create", "/F", "/TN", TASK, "/XML", xmlPath]);
-    return;
+    try {
+      await exec("schtasks", ["/Create", "/F", "/TN", TASK, "/XML", xmlPath]);
+    } catch (e) {
+      // Some PCs (security software, policy) refuse every new task, even for an administrator.
+      await exec("reg", ["add", WIN_RUN_KEY, "/v", WIN_RUN_VALUE, "/t", "REG_SZ", "/d", `conhost.exe --headless "${launcher}" health`, "/f"]).catch(() => { throw e; });
+      return { when: "signin", reason: firstLine(e) };
+    }
+    // A sign-in entry from an earlier blocked run would now double the checks.
+    await exec("reg", ["delete", WIN_RUN_KEY, "/v", WIN_RUN_VALUE, "/f"]).catch(() => {});
+    return { when: "daily" };
   }
   const agents = join(home, "Library", "LaunchAgents");
   await mkdir(agents, { recursive: true });
   const plist = join(agents, `${LABEL}.plist`);
   await writePrivate(plist, launchdPlist(launcher));
   await loadAgent(exec, uid, plist);
+  return { when: "daily" };
+}
+
+// The OS tool's own message (schtasks/launchctl stderr), which names no key.
+export function firstLine(e) {
+  return String(e?.stderr || (e instanceof Error ? e.message : "") || "").trim().split(/\r?\n/)[0];
 }

package/lib/setup.mjs

@@ -8,7 +8,7 @@ import { Writable } from "node:stream";
 import { promisify } from "node:util";
 import { EXTENSION_IDS } from "../shared/extension-ids.mjs";
 import { SITE, ensureSupportDir, writePrivate } from "./paths.mjs";
-import { registerNativeHost, scheduleDaily } from "./schedule.mjs";
+import { firstLine, registerNativeHost, scheduleDaily } from "./schedule.mjs";
 import { keychainStore } from "./vault.mjs";
 import { WIN_NOTIFY_SCRIPT } from "./platform.mjs";
 import { makeServer } from "./server.mjs";
@@ -17,6 +17,8 @@ const HOST = "com.getfootgun.keys";
 const MAX_TRIES = 3;
 
 const NO_NODE = "Footgun Keys cannot find Node. Run npx @getfootgun/keys setup again.";
+// PowerShell blocks npx (npx.ps1) by default, so Windows text names npx.cmd, which runs in both shells.
+const WIN_NO_NODE = "Footgun Keys cannot find Node. Run npx.cmd @getfootgun/keys setup again.";
 const NOTIFY_SCRIPT = ["on run argv", "display notification (item 2 of argv) with title (item 1 of argv)", "end run"];
 
 // The Windows .cmd launcher: same fallback order, but the notification text travels as environment
@@ -37,7 +39,7 @@ function windowsLauncher(nodePath, bin, subcommand) {
     ")",
     'if not exist "%NODE%" (',
     '  set "FOOTGUN_NOTIFY_TITLE=Footgun Keys"',
-    `  set "FOOTGUN_NOTIFY_BODY=${NO_NODE}"`,
+    `  set "FOOTGUN_NOTIFY_BODY=${WIN_NO_NODE}"`,
     `  powershell.exe -NoProfile -NonInteractive -Command "${WIN_NOTIFY_SCRIPT}" >nul 2>&1`,
     "  exit /b 1",
     ")",
@@ -83,6 +85,7 @@ export async function setup({ home, platform, prompt, exec, installApp, server,
   }
 
   const win = platform === "win32";
+  const npx = win ? "npx.cmd" : "npx";
   const j = win ? win32.join : join;
   const support = await ensureSupportDir(home, platform, env);
   print("Created the Footgun Keys support folder.");
@@ -134,16 +137,23 @@ export async function setup({ home, platform, prompt, exec, installApp, server,
 
   let scheduled = true;
   try {
-    await scheduleDaily({ platform, exec, home, launcher, uid, support, now });
-    print("Scheduled the daily key check.");
-  } catch {
+    const result = await scheduleDaily({ platform, exec, home, launcher, uid, support, now });
+    if (result?.when === "signin") {
+      print(`Windows would not create a scheduled task on this PC${result.reason ? ` (${result.reason})` : ""}.`);
+      print("Footgun will check your keys each time you sign in to Windows instead.");
+    } else {
+      print("Scheduled the daily key check.");
+    }
+  } catch (e) {
     scheduled = false;
     print("Could not schedule the daily key check. Run setup again to retry.");
+    const reason = firstLine(e);
+    if (reason) print(`The scheduler said: ${reason}`);
   }
   // A failed schedule must not end in apparent success, so it is repeated last and fails the run.
   const finish = (code) => {
     if (scheduled) return code;
-    print("The daily key check is NOT scheduled. Run npx @getfootgun/keys setup again.");
+    print(`The daily key check is NOT scheduled. Run ${npx} @getfootgun/keys setup again.`);
     return 1;
   };
 
@@ -168,7 +178,7 @@ export async function setup({ home, platform, prompt, exec, installApp, server,
   print(`Claude Code: claude mcp add footgun-keys -- ${win ? "cmd /c " : ""}npx -y @getfootgun/keys mcp`);
   print("Cursor: add the same command under MCP servers.");
   print("Chrome: install the Footgun Keys extension.");
-  print(`Your keys live in ${win ? "the Windows Credential Manager" : "your Mac's Keychain"} and in the env files you choose. AI tools can still read those env files; run npx @getfootgun/keys protect in a project so Claude Code's Read tool will not open them (shell commands still can).`);
+  print(`Your keys live in ${win ? "the Windows Credential Manager" : "your Mac's Keychain"} and in the env files you choose. AI tools can still read those env files; run ${npx} @getfootgun/keys protect in a project so Claude Code's Read tool will not open them (shell commands still can).`);
   return finish(0);
 }
 

package/lib/sync.d.mts

@@ -0,0 +1,16 @@
+import type { Vault } from "./vault.mjs";
+
+export const VERCEL_TARGETS: ("production" | "preview" | "development")[];
+export const PLATFORMS: Record<"vercel" | "railway", unknown>;
+export function syncEnv(opts: {
+  projectPath: string;
+  platform: string;
+  apply?: boolean;
+  overwrite?: string[];
+  targets?: string[];
+  vault: Vault;
+  fetch?: typeof fetch;
+  home?: string;
+}): Promise<{ text: string; isError: boolean }>;
+
+export function samePath(a: unknown, b: unknown, platform?: string): boolean;

package/lib/sync.mjs

@@ -0,0 +1,229 @@
+import { readFile, realpath } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { codeNames, envFileValues, isLocalValue, isManaged, PUBLIC_PREFIX } from "./envrefs.mjs";
+
+// keys_sync_env: compare the env vars a project needs with what its hosting platform has, and push the missing
+// ones. Values go from the Keychain (or the project's env file) only to the platform's own API host, fixed here.
+// Results and errors carry names, never values. Endpoints checked against the official docs on 2026-11-04:
+//   https://vercel.com/docs/rest-api/reference/endpoints/projects/retrieve-the-environment-variables-of-a-project-by-id-or-name
+//   https://vercel.com/docs/rest-api/reference/endpoints/projects/create-one-or-more-environment-variables
+//   https://vercel.com/docs/rest-api/reference/endpoints/projects/edit-an-environment-variable
+//   https://vercel.com/docs/cli/project-linking (.vercel/project.json holds orgId and projectId)
+//   https://docs.railway.com/integrations/api and https://docs.railway.com/integrations/api/manage-variables
+//   https://github.com/railwayapp/cli/blob/master/src/config.rs (~/.railway/config.json, projects keyed by path)
+
+const VERCEL_API = "https://api.vercel.com";
+const RAILWAY_API = "https://backboard.railway.com/graphql/v2";
+const TIMEOUT_MS = 15000;
+export const VERCEL_TARGETS = ["production", "preview", "development"];
+
+async function readJson(file) {
+  try { return JSON.parse(await readFile(file, "utf8")); } catch { return null; }
+}
+const timed = () => AbortSignal.timeout(TIMEOUT_MS);
+const refused = (name, status) => (status === 401 || status === 403
+  ? `${name} refused the saved token (status ${status}). Run keys_check, or keys_request to replace it.`
+  : `${name} answered with status ${status}.`);
+
+const vercel = {
+  name: "Vercel",
+  tokenVar: "VERCEL_TOKEN",
+  async link(projectPath) {
+    const p = await readJson(join(projectPath, ".vercel", "project.json"));
+    if (typeof p?.projectId !== "string") return { ok: false, error: "This folder is not linked to a Vercel project. Run vercel link in it first." };
+    // a team project needs teamId on every call; a personal one has a user id here instead
+    const teamId = typeof p.orgId === "string" && p.orgId.startsWith("team_") ? p.orgId : null;
+    return { ok: true, link: { projectId: p.projectId, teamId } };
+  },
+  url(link, path, extra = "") {
+    const q = new URLSearchParams(link.teamId ? { teamId: link.teamId } : {});
+    const qs = [q.toString(), extra].filter(Boolean).join("&");
+    return `${VERCEL_API}${path}${qs ? `?${qs}` : ""}`;
+  },
+  // name -> [{ id, targets }] for variables that apply to whole targets (branch-specific ones do not count)
+  async list(token, link, fetchFn) {
+    const res = await fetchFn(this.url(link, `/v10/projects/${encodeURIComponent(link.projectId)}/env`), { headers: { Authorization: `Bearer ${token}` }, signal: timed() });
+    if (!res.ok) return { ok: false, error: refused("Vercel", res.status) };
+    const body = await res.json().catch(() => null);
+    const envs = Array.isArray(body?.envs) ? body.envs : body && typeof body.key === "string" ? [body] : [];
+    const records = new Map();
+    for (const e of envs) {
+      if (typeof e?.key !== "string" || e.gitBranch) continue;
+      const targets = (Array.isArray(e.target) ? e.target : [e.target]).filter((t) => VERCEL_TARGETS.includes(t));
+      if (!records.has(e.key)) records.set(e.key, []);
+      records.get(e.key).push({ id: e.id, targets });
+    }
+    return { ok: true, records };
+  },
+  async push(token, link, plan, fetchFn) {
+    const headers = { Authorization: `Bearer ${token}`, "Content-Type": "application/json" };
+    const done = [];
+    const failed = [];
+    for (const { name, value, id } of plan.edits) {
+      const res = await fetchFn(this.url(link, `/v9/projects/${encodeURIComponent(link.projectId)}/env/${encodeURIComponent(id)}`), { method: "PATCH", headers, body: JSON.stringify({ value }), signal: timed() });
+      (res.ok ? done : failed).push(name);
+    }
+    if (plan.creates.length) {
+      const body = plan.creates.map(({ name, value, targets }) => ({ key: name, value, type: "encrypted", target: targets }));
+      const res = await fetchFn(this.url(link, `/v10/projects/${encodeURIComponent(link.projectId)}/env`), { method: "POST", headers, body: JSON.stringify(body), signal: timed() });
+      if (!res.ok) failed.push(...plan.creates.map((c) => c.name));
+      else {
+        // one bad item comes back in failed[] inside a 201
+        const r = await res.json().catch(() => null);
+        const bad = new Set((Array.isArray(r?.failed) ? r.failed : []).map((f) => f?.error?.key ?? f?.error?.envVarKey).filter(Boolean));
+        for (const c of plan.creates) (bad.has(c.name) ? failed : done).push(c.name);
+      }
+    }
+    return { done: [...new Set(done)].filter((n) => !failed.includes(n)), failed: [...new Set(failed)] };
+  },
+};
+
+async function railwayCall(token, query, variables, fetchFn) {
+  const res = await fetchFn(RAILWAY_API, {
+    method: "POST",
+    headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json" },
+    body: JSON.stringify({ query, variables }),
+    signal: timed(),
+  });
+  if (!res.ok) return { ok: false, error: refused("Railway", res.status) };
+  const body = await res.json().catch(() => null);
+  if (!body || Array.isArray(body.errors) && body.errors.length) {
+    const msg = body?.errors?.[0]?.message;
+    // Railway's own message names a field or a permission, never a value we sent
+    return { ok: false, error: `Railway refused the request${typeof msg === "string" ? `: ${msg.slice(0, 200)}` : "."}` };
+  }
+  return { ok: true, data: body.data };
+}
+
+// Windows paths ignore case and may use either slash ("c:\\app" and "C:/app" are one folder).
+export function samePath(a, b, platform = process.platform) {
+  if (typeof a !== "string" || typeof b !== "string") return false;
+  if (platform !== "win32") return a === b;
+  const norm = (p) => p.replace(/\//g, "\\").replace(/\\+$/, "").toLowerCase();
+  return norm(a) === norm(b);
+}
+
+const railway = {
+  name: "Railway",
+  tokenVar: "RAILWAY_API_TOKEN",
+  async link(projectPath, home = homedir()) {
+    const config = await readJson(join(home, ".railway", "config.json"));
+    const projects = config?.projects && typeof config.projects === "object" ? config.projects : {};
+    let dir;
+    try { dir = await realpath(projectPath); } catch { dir = resolve(projectPath); }
+    // the CLI links the folder it ran in; a parent's link covers this folder too
+    for (let d = dir; ; d = dirname(d)) {
+      const hit = Object.entries(projects).find(([k, v]) => samePath(k, d) || samePath(v?.projectPath, d))?.[1];
+      if (hit) {
+        if (typeof hit.project !== "string" || typeof hit.environment !== "string") break;
+        if (typeof hit.service !== "string") return { ok: false, error: "This folder is linked to a Railway project but not to a service. Run railway service in it first." };
+        return { ok: true, link: { projectId: hit.project, environmentId: hit.environment, serviceId: hit.service } };
+      }
+      if (dirname(d) === d) break;
+    }
+    return { ok: false, error: "This folder is not linked to a Railway project. Run railway link in it first." };
+  },
+  async list(token, link, fetchFn) {
+    const r = await railwayCall(token,
+      "query vars($projectId: String!, $environmentId: String!, $serviceId: String) { variables(projectId: $projectId, environmentId: $environmentId, serviceId: $serviceId, unrendered: true) }",
+      link, fetchFn);
+    if (!r.ok) return r;
+    const names = r.data?.variables && typeof r.data.variables === "object" ? Object.keys(r.data.variables) : [];
+    return { ok: true, records: new Map(names.map((n) => [n, [{ id: null, targets: ["service"] }]])) };
+  },
+  async push(token, link, plan, fetchFn) {
+    const all = [...plan.edits, ...plan.creates];
+    const variables = Object.fromEntries(all.map(({ name, value }) => [name, value]));
+    // replace: false keeps every other variable; skipDeploys: the user redeploys when ready
+    const r = await railwayCall(token,
+      "mutation set($input: VariableCollectionUpsertInput!) { variableCollectionUpsert(input: $input) }",
+      { input: { ...link, variables, replace: false, skipDeploys: true } }, fetchFn);
+    const names = all.map((v) => v.name);
+    return r.ok ? { done: names, failed: [] } : { done: [], failed: names, error: r.error };
+  },
+};
+
+export const PLATFORMS = { vercel, railway };
+
+/**
+ * Builds the report, and pushes when apply is true. Returns { text, isError }. Values never enter text.
+ * vault: the Keys vault. targets: Vercel targets (Railway has one service environment).
+ */
+export async function syncEnv({ projectPath, platform, apply = false, overwrite = [], targets, vault, fetch: fetchFn = globalThis.fetch, home }) {
+  const p = PLATFORMS[platform];
+  const err = (text) => ({ text, isError: true });
+  if (!p) return err("Env sync supports vercel and railway.");
+  const wanted = platform === "vercel" ? (targets?.length ? targets : ["production", "preview"]) : ["service"];
+  if (platform === "vercel" && wanted.some((t) => !VERCEL_TARGETS.includes(t))) return err(`Vercel targets are ${VERCEL_TARGETS.join(", ")}.`);
+
+  const linked = await p.link(projectPath, home);
+  if (!linked.ok) return err(linked.error);
+
+  const entries = await vault.list();
+  const newest = (name) => entries.filter((e) => e.envVar === name).sort((a, b) => b.createdAt.localeCompare(a.createdAt))[0];
+  const tokenEntry = newest(p.tokenVar);
+  const token = tokenEntry ? await vault.get(tokenEntry.provider, tokenEntry.label, p.tokenVar) : null;
+  if (!token) return err(`No ${p.name} token saved. Call keys_request with provider ${platform} first.`);
+
+  const listed = await p.list(token, linked.link, fetchFn);
+  if (!listed.ok) return err(listed.error);
+
+  const files = await envFileValues(projectPath);
+  const needed = [...new Set([...(await codeNames(projectPath)), ...[...files.keys()].filter((n) => !isManaged(n))])].sort();
+  const valueOf = async (name) => {
+    const e = newest(name);
+    const v = e ? await vault.get(e.provider, e.label, name) : null;
+    if (v !== null && v !== undefined) return { value: v, source: "Keychain" };
+    const f = files.get(name);
+    return f ? { value: f.value, source: f.file } : null;
+  };
+
+  const set = [];
+  const local = [];
+  const missing = [];
+  const creates = [];
+  const edits = [];
+  const notes = [];
+  for (const name of needed) {
+    const records = listed.records.get(name) ?? [];
+    const covered = new Set(records.flatMap((r) => r.targets));
+    const uncovered = platform === "vercel" ? wanted.filter((t) => !covered.has(t)) : covered.size ? [] : ["service"];
+    const replace = overwrite.includes(name) && records.length > 0;
+    if (!uncovered.length && !replace) { set.push(name); continue; }
+    const v = await valueOf(name);
+    if (!v) { missing.push(name); continue; }
+    if (v.source !== "Keychain" && isLocalValue(v.value)) { local.push(`${name} (${v.source})`); continue; }
+    const label = `${name} (from ${v.source}${PUBLIC_PREFIX.test(name) ? ", public in the browser" : ""})`;
+    if (replace) {
+      for (const r of records) if (platform === "railway" || r.targets.some((t) => wanted.includes(t))) edits.push({ name, value: v.value, id: r.id, label });
+    }
+    if (uncovered.length && !(platform === "railway" && replace)) creates.push({ name, value: v.value, targets: uncovered, label });
+  }
+  for (const name of overwrite) if (!needed.includes(name)) notes.push(`${name}: not used by this project, so not overwritten.`);
+
+  const where = platform === "vercel" ? `${p.name} (${wanted.join(", ")})` : p.name;
+  const lines = [`${where}:`];
+  const labels = [...new Map([...edits, ...creates].map((x) => [x.name, x.label])).values()];
+  if (set.length) lines.push(`Already set, not changed: ${set.join(", ")}`);
+  if (labels.length) lines.push(`${apply ? "Pushing" : "Can push"}: ${labels.join("; ")}`);
+  if (local.length) lines.push(`Not pushed, the value points at this computer: ${local.join(", ")}`);
+  if (missing.length) lines.push(`Missing everywhere: ${missing.join(", ")}. Get these with keys_request, or add them on ${p.name} yourself.`);
+  lines.push(...notes);
+  if (!labels.length) { lines.push("Nothing to push."); return { text: lines.join("\n"), isError: false }; }
+  if (!apply) {
+    lines.push(`Nothing was sent. Show this to the user, and with their yes call keys_sync_env again with apply: true to push ${labels.length}.`);
+    if (set.length) lines.push("Names already set are only replaced when listed in overwrite.");
+    return { text: lines.join("\n"), isError: false };
+  }
+
+  let pushed;
+  try {
+    pushed = await p.push(token, linked.link, { creates, edits }, fetchFn);
+  } catch {
+    return err(`Could not reach ${p.name}. Nothing was confirmed as pushed; run keys_sync_env again to see what is set.`);
+  }
+  if (pushed.done.length) lines.push(`Pushed: ${pushed.done.join(", ")}. Redeploy on ${p.name} for the new values to take effect.`);
+  if (pushed.failed.length) lines.push(`Failed: ${pushed.failed.join(", ")}.${pushed.error ? ` ${pushed.error}` : ""}`);
+  return { text: lines.join("\n"), isError: pushed.done.length === 0 };
+}

package/package.json

@@ -1 +1 @@
-{ "name": "@getfootgun/keys", "version": "0.2.0-rc.1", "description": "Footgun Keys: guided API key setup that saves keys to the Mac Keychain or Windows Credential Manager.", "bin": { "footgun-keys": "bin/footgun-keys.mjs" }, "type": "module", "license": "MIT", "files": ["bin", "lib", "shared", "README.md"], "dependencies": { "@modelcontextprotocol/server": "2.3.1", "@napi-rs/keyring": "2.1.2", "zod": "4.6.7" }, "engines": { "node": ">=20" } }
+{ "name": "@getfootgun/keys", "version": "0.2.0-rc.3", "description": "Footgun Keys: guided API key setup that saves keys to the Mac Keychain or Windows Credential Manager.", "bin": { "footgun-keys": "bin/footgun-keys.mjs" }, "type": "module", "license": "MIT", "files": ["bin", "lib", "shared", "README.md"], "dependencies": { "@modelcontextprotocol/server": "2.3.1", "@napi-rs/keyring": "2.1.2", "zod": "4.6.7" }, "engines": { "node": ">=20" } }