instabox 0.4.2 → 0.5.0

package/skills/instabox-move-all/scripts/lib.mjs

@@ -0,0 +1,226 @@
+// Shared by the instabox-move-all scripts. Node >= 18, no dependencies.
+//
+// The one rule every function here keeps: a credential's value is never
+// returned, stored or printed. Code that looks at a secret-bearing file
+// returns booleans, names and sizes only.
+import { spawnSync } from 'node:child_process';
+import { lstatSync, readdirSync, readFileSync, openSync, readSync, closeSync, realpathSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { join } from 'node:path';
+
+// Environment variable names that hold a credential, also with a rotation or environment
+// qualifier after it (OPENAI_API_KEY_2, GITHUB_TOKEN_OLD, DB_PASSWORD_PROD). The qualifier
+// needs its own `_`, so PATH is not PAT plus H.
+export const SECRET_NAME =
+  /(?:^|_)(?:API_?KEY|APIKEY|KEY_?SECRET|TOKEN|ACCESS_?TOKEN|AUTH_?TOKEN|REFRESH_?TOKEN|SECRET|SECRET_?KEY|CLIENT_?SECRET|ACCESS_?KEY|ACCESS_?KEY_?ID|PASSWORD|PASSWD|PASS|PAT|PRIVATE_?KEY|CREDENTIALS?)(?:_(?:\d+|V\d+|OLD|NEW|PREV|PREVIOUS|BAK|BACKUP|ALT|PROD|PRODUCTION|DEV|STAGING|STAGE|TEST|LOCAL|CI))?$/i;
+
+// Values that are credentials whatever the variable is called: token
+// prefixes of the common services, and URLs with a password in them.
+export const SECRET_VALUE = new RegExp(
+  [
+    String.raw`\bgh[pousr]_[A-Za-z0-9]{20,}`,
+    String.raw`\bgithub_pat_[A-Za-z0-9_]{20,}`,
+    String.raw`\bsk-[A-Za-z0-9_-]{20,}`,
+    String.raw`\bAKIA[0-9A-Z]{16}\b`,
+    String.raw`\bASIA[0-9A-Z]{16}\b`,
+    String.raw`\bxox[abposr]-[A-Za-z0-9-]{10,}`,
+    String.raw`\bglpat-[A-Za-z0-9_-]{20,}`,
+    String.raw`\bnpm_[A-Za-z0-9]{30,}`,
+    String.raw`\bAIza[0-9A-Za-z_-]{35}`,
+    String.raw`-----BEGIN [A-Z ]*PRIVATE KEY-----`,
+    String.raw`[a-z][a-z0-9+.-]*://[^/\s:@'"]+:[^@\s'"/]+@`,
+  ].join('|'),
+);
+
+// key = value / key: value pairs whose key says it is a secret (config files), at the start
+// of a line or inside an inline table; numbers and booleans are not secrets (max_tokens = 100).
+export const SECRET_KEY_LINE =
+  /(?:^|[\s{,;])["']?[\w.-]*(?:token|password|passwd|secret|api[_-]?key|apikey|_auth|authorization|private[_-]?key)[\w.-]*["']?\s*[=:]\s*["']?(?![0-9.]+\b|true\b|false\b)[^\s"',}]/i;
+
+// Names the Vault refuses for env items (docs/vault.md), plus our own.
+const RESERVED = new Set(['HOME', 'PATH', 'USER', 'LOGNAME', 'SHELL', 'TERM', 'XDG_RUNTIME_DIR', 'DBUS_SESSION_BUS_ADDRESS']);
+export function vaultEnvNameOK(name) {
+  return (
+    /^[A-Za-z_][A-Za-z0-9_]*$/.test(name) &&
+    name.length <= 128 &&
+    !RESERVED.has(name) &&
+    !name.startsWith('INSTABOX_') &&
+    !name.startsWith('SSH_')
+  );
+}
+
+// Whether a variable's name says it holds a credential. This is the scrubber's question; whether
+// the Vault can store it under that name is a separate one (vaultEnvNameOK).
+export function isSecretName(name) {
+  return SECRET_NAME.test(name);
+}
+
+// Lines in macOS shells and configs that mean nothing on the Linux box.
+export const MACOS_ONLY =
+  /\/opt\/homebrew|\/usr\/local\/Cellar|\/usr\/local\/Homebrew|\/Applications\/|\/Library\/|\bosxkeychain\b|\bUseKeychain\b|\bpbcopy\b|\bpbpaste\b|\bosascript\b|\bbrew shellenv\b|\bterminal-notifier\b|\bafplay\b|\/System\/|\.orbstack\/|1password.*agent\.sock|\bsecurity (?:find|add)-[a-z-]*password\b/i;
+
+// The Vault's limits (docs/vault.md).
+export const VAULT_MAX_VALUE = 64 * 1024;
+export const VAULT_MAX_TOTAL = 256 * 1024;
+export const VAULT_MAX_ITEMS = 100;
+
+export const BOX_NAME = /^[a-z0-9][a-z0-9-]{0,62}$/;
+export const BOX_HOME = '/data/home';
+export const BOX_WORKSPACE = '/data/workspace';
+// Staged files that are merged into the box's own copies rather than replacing them.
+export const STAGE_DIR = '.config/instabox-move';
+
+// Runs a command without a shell; never throws. stdout is returned to the
+// caller only: callers that run credential tools (gh auth token) must not
+// keep or print it.
+export function run(argv, { cwd, env, input, timeout = 30_000 } = {}) {
+  const r = spawnSync(argv[0], argv.slice(1), {
+    cwd,
+    env,
+    input,
+    timeout,
+    encoding: 'utf8',
+    maxBuffer: 64 * 1024 * 1024,
+    stdio: [input === undefined ? 'ignore' : 'pipe', 'pipe', 'pipe'],
+  });
+  return { ok: r.status === 0 && !r.error, status: r.status, stdout: r.stdout || '', stderr: r.stderr || '' };
+}
+
+export function hasCommand(name, env) {
+  for (const dir of (env?.PATH || '').split(':')) {
+    if (!dir) continue;
+    try {
+      const st = lstatSync(join(dir, name));
+      if (st.isFile() || st.isSymbolicLink()) return true;
+    } catch {}
+  }
+  return false;
+}
+
+export function lstatOrNull(p) {
+  try {
+    return lstatSync(p);
+  } catch {
+    return null;
+  }
+}
+
+// Bytes under a path, symlinks counted as links, not followed.
+export function treeBytes(p, skip = () => false) {
+  const st = lstatOrNull(p);
+  if (!st) return 0;
+  if (!st.isDirectory()) return st.size;
+  let total = 0;
+  let names = [];
+  try {
+    names = readdirSync(p);
+  } catch {
+    return 0;
+  }
+  for (const n of names) if (!skip(n)) total += treeBytes(join(p, n), skip);
+  return total;
+}
+
+// Every regular file and symlink under dir, as paths relative to it, sorted.
+export function listFiles(dir, skip = () => false, rel = '') {
+  const out = [];
+  let names = [];
+  try {
+    names = readdirSync(join(dir, rel)).sort();
+  } catch {
+    return out;
+  }
+  for (const n of names) {
+    if (skip(n)) continue;
+    const r = rel ? `${rel}/${n}` : n;
+    const st = lstatOrNull(join(dir, r));
+    if (!st) continue;
+    if (st.isDirectory()) out.push(...listFiles(dir, skip, r));
+    else if (st.isFile() || st.isSymbolicLink()) out.push(r);
+  }
+  return out;
+}
+
+export function readText(p) {
+  try {
+    return readFileSync(p, 'utf8');
+  } catch {
+    return null;
+  }
+}
+
+export function readJSON(p) {
+  const t = readText(p);
+  if (t === null) return null;
+  try {
+    return JSON.parse(t);
+  } catch {
+    return null;
+  }
+}
+
+// The first n bytes of a file, for sniffing a header.
+export function readHead(p, n = 4096) {
+  let fd;
+  try {
+    fd = openSync(p, 'r');
+    const buf = Buffer.alloc(n);
+    const len = readSync(fd, buf, 0, n, 0);
+    return buf.subarray(0, len).toString('utf8');
+  } catch {
+    return '';
+  } finally {
+    if (fd !== undefined) closeSync(fd);
+  }
+}
+
+export function isBinary(buf) {
+  return buf.includes(0);
+}
+
+export function human(bytes) {
+  if (bytes < 1024) return `${bytes} B`;
+  const u = ['KB', 'MB', 'GB', 'TB'];
+  let v = bytes / 1024;
+  let i = 0;
+  while (v >= 1024 && i < u.length - 1) {
+    v /= 1024;
+    i++;
+  }
+  return `${v >= 10 ? Math.round(v) : v.toFixed(1)} ${u[i]}`;
+}
+
+// Claude Code's name for a project directory: every non-alphanumeric character becomes '-'.
+export function claudeProjectName(path) {
+  return path.replace(/[^A-Za-z0-9]/g, '-');
+}
+
+// A name that is safe in a path and a quoted shell word (as instabox-migrate does).
+export function safeName(s) {
+  return s.replace(/[^A-Za-z0-9._-]/g, '-');
+}
+
+// The Vault item name for a file item: its path with / as -, as `instabox vault set-file` does.
+export function vaultFileName(path) {
+  return safeName(path.replace(/^\./, '').replaceAll('/', '-')).replace(/^-+|-+$/g, '');
+}
+
+// A Vault file path must be relative, clean, without .. components (docs/vault.md).
+export function vaultPathOK(p) {
+  if (!p || p.startsWith('/') || p.length > 255 || /[\0\\\n]/.test(p)) return false;
+  const parts = p.split('/');
+  return parts.every((c) => c !== '' && c !== '.' && !c.startsWith('..'));
+}
+
+export function homeRel(home, p) {
+  return p.startsWith(home + '/') ? '~/' + p.slice(home.length + 1) : p;
+}
+
+// True when the module is the script node was started with (not imported by a test).
+export function isMain(meta) {
+  try {
+    return realpathSync(process.argv[1]) === realpathSync(fileURLToPath(meta.url));
+  } catch {
+    return false;
+  }
+}

package/skills/instabox-move-all/scripts/plan.mjs

@@ -0,0 +1,263 @@
+#!/usr/bin/env node
+// The checkbox plan between the scan and the move.
+//
+//   node plan.mjs write --scan scan.json --box NAME > migrate-plan.md
+//   node plan.mjs parse --scan scan.json [--disk-gib N] migrate-plan.md > selection.json
+//
+// `write` renders every scanned item as a `- [x]` / `- [ ]` line with its id
+// in backticks. The user edits the checkboxes (and the box name); `parse`
+// reads them back strictly: every id exactly once, nothing unknown, no
+// malformed checkbox, nothing checked that cannot move. Errors go to stderr,
+// all of them at once, with exit status 1. --disk-gib N: exit 3 when the
+// selection does not fit the box.
+import { createHash } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+import { BOX_NAME, VAULT_MAX_ITEMS, VAULT_MAX_TOTAL, human, isMain } from './lib.mjs';
+import { describeTools, mapTools } from './tools.mjs';
+
+export function scanDigest(scan) {
+  return createHash('sha256').update(JSON.stringify(scan)).digest('hex').slice(0, 16);
+}
+
+const tilde = (home, p) => (p && p.startsWith(home + '/') ? '~' + p.slice(home.length) : p);
+
+function allItems(scan) {
+  return [...scan.work, ...scan.history, ...scan.credentials, ...scan.environment];
+}
+
+function line(item, text) {
+  return `- [${item.checked ? 'x' : ' '}] \`${item.id}\` ${text}`;
+}
+
+export function writePlan(scan, box) {
+  if (!BOX_NAME.test(box)) throw new Error(`box name ${JSON.stringify(box)}: use lowercase letters, digits and -`);
+  const h = scan.home;
+  const out = [];
+  out.push('# Move to instabox: plan');
+  out.push('');
+  out.push(
+    'Check `[x]` what moves to the new box and uncheck `[ ]` what stays. Change the box name if you like.',
+    'Do not edit the ids in backticks or delete lines: the agent reads this file back and stops on anything it does not recognise.',
+  );
+  out.push('');
+  out.push(`Box: \`${box}\``);
+  out.push('');
+  out.push(`<!-- scan ${scanDigest(scan)}: this plan belongs to that scan; scan again and write a new plan if anything changed -->`);
+
+  out.push('', '## Work', '');
+  out.push(
+    'Each repo goes to /data/workspace on the box with its uncommitted and untracked work (files git ignores stay here).',
+    'Checked by default: repos with work that exists only on this machine.',
+    '',
+  );
+  if (!scan.work.length) out.push('_No git repos found._');
+  for (const r of scan.work) {
+    const state = [r.branch, r.why].join(' · ');
+    out.push(line(r, `${tilde(h, r.path)} · ${state} · ${human(r.bytes)} → ${r.dest}`));
+    const hist = scan.history.find((x) => x.repo === r.id);
+    if (hist) {
+      const parts = [];
+      const n = (k) => `${k} session${k === 1 ? '' : 's'}`;
+      if (hist.claude) parts.push(`Claude Code ${n(hist.claude.sessions)}`);
+      if (hist.codex) parts.push(`Codex ${n(hist.codex.sessions)}`);
+      out.push(
+        '  ' +
+          line(
+            hist,
+            `its agent history: ${parts.join(', ')} · ${human(hist.bytes)} (may contain secrets you pasted into a chat)`,
+          ),
+      );
+    }
+  }
+
+  out.push('', '## Credentials', '');
+  out.push(
+    `Checked items go into your instabox Vault for this box only (selector migrated=${box}): values go straight from here to the Vault and are never shown.`,
+    'Lines marked "can\'t move" are listed for the final report: check them and the plan is refused.',
+    '',
+  );
+  if (!scan.credentials.length) out.push('_No credentials found._');
+  for (const c of scan.credentials) {
+    let text;
+    if (c.kind === 'env') text = `${c.name} from ${c.from} → Vault env`;
+    else if (c.kind === 'file') text = `${c.from}${c.bytes ? ` (${human(c.bytes)})` : ''} → Vault file ~/${c.path}`;
+    else text = `${c.name}: can't move: ${c.reason}. ${c.manual}`;
+    if (c.kind !== 'manual' && c.reason) text += ` · off by default: ${c.reason}`;
+    if (c.note) text += ` · ${c.note}`;
+    out.push(line(c, text));
+  }
+
+  out.push('', '## Environment', '');
+  out.push('Dotfiles and agent config are copied with secrets and macOS-only lines left out; tools are installed fresh for Linux.', '');
+  if (!scan.environment.length) out.push('_Nothing found._');
+  for (const e of scan.environment) {
+    let text;
+    if (e.kind === 'tools') text = `${e.manager}: ${e.names.length + (e.unknown?.length || 0)} tools → ${describeTools(e)}`;
+    else if (e.names) text = `~/${e.path}: ${e.names.join(', ')}${e.bytes ? ` · ${human(e.bytes)}` : ''}`;
+    else text = `~/${e.path}${e.dir ? '/' : ''} · ${human(e.bytes)}`;
+    if (e.note) text += ` · ${e.note}`;
+    out.push(line(e, text));
+  }
+  out.push('');
+  return out.join('\n');
+}
+
+export class PlanError extends Error {
+  constructor(errors) {
+    super(errors.join('\n'));
+    this.errors = errors;
+  }
+}
+
+// Reads the plan back. Throws PlanError listing every problem.
+export function parsePlan(scan, text, { diskGiB } = {}) {
+  const errors = [];
+  const items = new Map(allItems(scan).map((i) => [i.id, i]));
+  const state = new Map();
+  let box = null;
+  let digest = null;
+  text.split('\n').forEach((raw, i) => {
+    const n = i + 1;
+    const l = raw.replace(/\r$/, '');
+    const b = l.match(/^Box:\s*(.*)$/);
+    if (b) {
+      if (box !== null) errors.push(`line ${n}: a second Box: line`);
+      const m = b[1].trim().match(/^`([^`]*)`$/);
+      if (!m) errors.push(`line ${n}: write the box name in backticks: Box: \`name\``);
+      else if (!BOX_NAME.test(m[1])) errors.push(`line ${n}: box name ${JSON.stringify(m[1])}: use lowercase letters, digits and -, 63 at most, not starting with -`);
+      else box = m[1];
+      return;
+    }
+    const s = l.match(/<!-- scan ([0-9a-f]+):/);
+    if (s) digest = s[1];
+    // Anything that looks like a list item with a checkbox must be exactly one of ours.
+    if (!/^\s*(?:[-*+]|\d+[.)])\s*\[/.test(l) && !/^\s*[-*+]\s*`[a-z]+:/.test(l)) return;
+    const m = l.match(/^(?: {2})?- \[([ xX])\] `([^`]+)`(?: .*)?$/);
+    if (!m) {
+      errors.push(`line ${n}: not a checkbox line this plan understands: ${JSON.stringify(l.slice(0, 80))} (write "- [x] \`id\` ..." or "- [ ] \`id\` ...")`);
+      return;
+    }
+    const [, mark, id] = m;
+    if (!items.has(id)) {
+      errors.push(`line ${n}: unknown id \`${id}\``);
+      return;
+    }
+    if (state.has(id)) {
+      errors.push(`line ${n}: \`${id}\` appears twice`);
+      return;
+    }
+    state.set(id, mark !== ' ');
+  });
+  if (box === null && !errors.some((e) => e.includes('box name') || e.includes('Box:'))) errors.push('no "Box: `name`" line');
+  if (digest === null) errors.push('the "<!-- scan ... -->" line is missing: write the plan again from the scan');
+  else if (digest !== scanDigest(scan)) errors.push(`this plan was written from a different scan (${digest}, the scan file is ${scanDigest(scan)}): write the plan again`);
+  for (const id of items.keys()) if (!state.has(id)) errors.push(`\`${id}\` is missing from the plan (uncheck a line instead of deleting it)`);
+
+  const on = (id) => state.get(id) === true;
+  for (const [id, checked] of state) {
+    if (!checked) continue;
+    const it = items.get(id);
+    if (it.kind === 'manual') errors.push(`\`${id}\` can't move (${it.reason}); uncheck it: it is listed in the final report with what to do instead`);
+    if (it.id.startsWith('history:') && !on(it.repo)) errors.push(`\`${id}\` is checked but its repo \`${it.repo}\` is not: check both or neither`);
+    if (it.repo && it.id.startsWith('cred:') && !on(it.repo)) errors.push(`\`${id}\` is a .env of \`${it.repo}\`, which is not checked: check both or neither`);
+  }
+  if (errors.length) throw new PlanError(errors);
+
+  const pick = (list) => list.filter((i) => on(i.id));
+  const work = pick(scan.work);
+  const history = pick(scan.history);
+  const credentials = pick(scan.credentials);
+  const environment = pick(scan.environment);
+  const tools = mapTools(environment.filter((e) => e.kind === 'tools'));
+  const manual = [
+    ...scan.credentials.filter((c) => c.kind === 'manual').map((c) => ({ what: c.name, why: c.reason, todo: c.manual.replaceAll('<box>', box) })),
+    ...tools.manual.map((m) => ({ what: m.split(':')[0], why: 'no automatic Linux install', todo: m.split(': ').slice(1).join(': ') })),
+  ];
+  const bytes = {
+    work: work.reduce((s, r) => s + r.bytes, 0),
+    history: history.reduce((s, x) => s + x.bytes, 0),
+    environment: environment.reduce((s, e) => s + (e.bytes || 0), 0),
+  };
+  bytes.total = bytes.work + bytes.history + bytes.environment;
+  const vaultBytes = credentials.reduce((s, c) => s + (c.bytes || 0), 0);
+  const warnings = [];
+  if (credentials.length > VAULT_MAX_ITEMS) warnings.push(`${credentials.length} credentials: the Vault holds ${VAULT_MAX_ITEMS} items at most`);
+  if (vaultBytes > VAULT_MAX_TOTAL) warnings.push(`credential files total ${human(vaultBytes)}: the Vault holds ${human(VAULT_MAX_TOTAL)} at most`);
+  const result = {
+    box,
+    home: scan.home,
+    selector: { migrated: box },
+    work,
+    history,
+    credentials,
+    environment,
+    tools,
+    manual,
+    skipped: [...state].filter(([, v]) => !v).map(([id]) => id),
+    bytes,
+    vault: { items: credentials.length, fileBytes: vaultBytes },
+    warnings,
+  };
+  if (diskGiB) {
+    const disk = diskGiB * 1024 ** 3;
+    // Half the disk stays free for dependencies, builds and tools installed on the box.
+    result.disk = { gib: diskGiB, budgetBytes: disk / 2, fits: bytes.total <= disk / 2 };
+  }
+  return result;
+}
+
+function main() {
+  const [cmd, ...rest] = process.argv.slice(2);
+  const opt = (name) => {
+    const i = rest.indexOf(name);
+    if (i < 0) return undefined;
+    const v = rest[i + 1] ?? ''; // a flag with no value is an empty one, not an absent one
+    rest.splice(i, 2);
+    return v;
+  };
+  const usage = () => {
+    process.stderr.write(
+      'usage: plan.mjs write --scan scan.json --box NAME\n       plan.mjs parse --scan scan.json [--disk-gib N] migrate-plan.md\n',
+    );
+    process.exit(2);
+  };
+  const scanFile = opt('--scan');
+  if (!scanFile) usage();
+  const scan = JSON.parse(readFileSync(scanFile, 'utf8'));
+  if (cmd === 'write') {
+    const box = opt('--box');
+    if (!box || rest.length) usage();
+    try {
+      process.stdout.write(writePlan(scan, box));
+    } catch (e) {
+      process.stderr.write(e.message + '\n');
+      process.exit(1);
+    }
+  } else if (cmd === 'parse') {
+    const disk = opt('--disk-gib');
+    if (rest.length !== 1) usage();
+    // An empty or non-numeric value (say `instabox usage` failed) must not switch the disk check off.
+    if (disk !== undefined && !(/^\d+(?:\.\d+)?$/.test(disk) && Number(disk) > 0)) {
+      process.stderr.write(`--disk-gib must be a positive number of GiB, got ${JSON.stringify(disk ?? '')}\n`);
+      usage();
+    }
+    let sel;
+    try {
+      sel = parsePlan(scan, readFileSync(rest[0], 'utf8'), { diskGiB: disk === undefined ? undefined : Number(disk) });
+    } catch (e) {
+      if (!(e instanceof PlanError)) throw e;
+      process.stderr.write(`${rest[0]}: ${e.errors.length} problem(s):\n${e.errors.map((x) => `  ${x}`).join('\n')}\n`);
+      process.exit(1);
+    }
+    process.stdout.write(JSON.stringify(sel, null, 2) + '\n');
+    for (const w of sel.warnings) process.stderr.write(`warning: ${w}\n`);
+    if (sel.disk && !sel.disk.fits) {
+      process.stderr.write(
+        `too big: the selection is ${human(sel.bytes.total)}; the box's /data disk is ${sel.disk.gib} GiB and half of it is kept for dependencies and builds (${human(sel.disk.budgetBytes)}). Uncheck some repos or history.\n`,
+      );
+      process.exit(3);
+    }
+  } else usage();
+}
+
+if (isMain(import.meta)) main();

package/skills/instabox-move-all/scripts/push-creds.mjs

@@ -0,0 +1,154 @@
+#!/usr/bin/env node
+// Puts the checked credentials into the Vault for one box only, piping each
+// value from where it lives straight into `instabox vault set` / `set-file`.
+//
+//   node push-creds.mjs --selection selection.json [--dry-run]
+//
+// A value is held in this process's memory between reading it and writing it
+// to instabox's stdin; it is never printed, logged or put on a command line.
+// What is printed: one line per item with its name, kind and outcome.
+//
+// Items already in the Vault are left alone unless they carry exactly this
+// box's selector (a re-run): replacing them would change what other boxes get.
+// Afterwards, run `instabox vault push <box>` to write them into the running box.
+import { spawnSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import { VAULT_MAX_VALUE, isMain, run } from './lib.mjs';
+
+const shellFor = (file) => (/\/\.z[^/]*$/.test(file) && spawnSync('zsh', ['-c', 'true']).status === 0 ? 'zsh' : 'bash');
+
+// The value of one credential, or {error}. Never logged.
+export function readValue(src, env = process.env) {
+  try {
+    switch (src.type) {
+      case 'env':
+        return env[src.name] ? { value: env[src.name] } : { error: `${src.name} is not set in this environment` };
+      case 'rc': {
+        // Source the startup file the way a shell does, with its output discarded, then print only the variable.
+        if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(src.name)) return { error: 'bad name' };
+        const r = spawnSync(
+          shellFor(src.file),
+          ['-c', `. "$1" >/dev/null 2>&1 </dev/null; printf %s "\${${src.name}-}"`, 'instabox-move-all', src.file],
+          { env, encoding: 'utf8', timeout: 30_000, stdio: ['ignore', 'pipe', 'ignore'] },
+        );
+        return r.stdout ? { value: r.stdout } : { error: `${src.name} is empty after sourcing ${src.file}` };
+      }
+      case 'cmd': {
+        const r = run(src.argv, { env });
+        const v = r.stdout.replace(/\n$/, '');
+        return r.ok && v ? { value: v } : { error: `\`${src.argv.join(' ')}\` failed (exit ${r.status})` };
+      }
+      case 'file': {
+        const buf = readFileSync(src.path);
+        if (buf.includes(0)) return { error: 'a binary file: the Vault holds text only' };
+        return { value: buf.toString('utf8') };
+      }
+      case 'json': {
+        let v = JSON.parse(readFileSync(src.path, 'utf8'));
+        for (const k of src.keys) v = v?.[k];
+        return typeof v === 'string' && v ? { value: v } : { error: `no ${src.keys.join('.')} in ${src.path}` };
+      }
+    }
+  } catch (e) {
+    return { error: e.code || 'unreadable' };
+  }
+  return { error: `unknown source ${src.type}` };
+}
+
+// instabox's own output with the value masked, in case a message ever echoes it.
+const mask = (text, value) => (value ? text.split(value).join('***') : text).trim().split('\n').pop() || '';
+
+function sameSelector(a, b) {
+  const ka = Object.keys(a || {}).sort();
+  const kb = Object.keys(b || {}).sort();
+  return ka.length === kb.length && ka.every((k, i) => k === kb[i] && a[k] === b[k]);
+}
+
+export function pushCreds(sel, { instabox = 'instabox', env = process.env, dryRun = false, log = (s) => console.log(s) } = {}) {
+  const selector = `migrated=${sel.box}`;
+  const results = [];
+  const ls = run([instabox, 'vault', 'ls', '--json'], { env });
+  if (!ls.ok) {
+    log(`instabox vault ls failed: ${ls.stderr.trim().split('\n').pop()} (signed in? \`instabox login\`; INSTABOX_API_KEY must be unset)`);
+    return { ok: false, results };
+  }
+  let existing;
+  try {
+    existing = JSON.parse(ls.stdout).items || [];
+  } catch {
+    log('instabox vault ls --json did not print JSON; is the instabox CLI up to date?');
+    return { ok: false, results };
+  }
+  const byName = new Map(existing.map((i) => [i.name, i]));
+  const byPath = new Map(existing.filter((i) => i.path).map((i) => [i.path, i]));
+  let ok = true;
+  for (const c of sel.credentials) {
+    const r = { id: c.id, name: c.name, kind: c.kind };
+    results.push(r);
+    const old = byName.get(c.name) || (c.path && byPath.get(c.path));
+    if (old && !sameSelector(old.selector, sel.selector)) {
+      r.status = 'kept';
+      const sel0 = Object.keys(old.selector || {}).length;
+      r.detail = sel0
+        ? `already in your Vault as ${old.name} for sandboxes with ${Object.entries(old.selector).map(([k, v]) => `${k}=${v}`).join(',')}; left unchanged, so it does not reach this box unless you add that metadata`
+        : `already in your Vault as ${old.name} for every box, this one included; left unchanged`;
+      log(`kept   ${c.name} (${c.kind}): ${r.detail}`);
+      continue;
+    }
+    const got = readValue(c.source, env);
+    if (got.error) {
+      ok = false;
+      r.status = 'failed';
+      r.detail = got.error;
+      log(`failed ${c.name} (${c.kind}): ${got.error}`);
+      continue;
+    }
+    const bytes = Buffer.byteLength(got.value);
+    if (bytes > VAULT_MAX_VALUE) {
+      ok = false;
+      r.status = 'failed';
+      r.detail = `${bytes} bytes: over the Vault's 64 KiB per item`;
+      log(`failed ${c.name} (${c.kind}): ${r.detail}`);
+      continue;
+    }
+    const argv =
+      c.kind === 'env'
+        ? [instabox, 'vault', 'set', c.name, '--selector', selector]
+        : [instabox, 'vault', 'set-file', c.path, '--name', c.name, '--selector', selector];
+    if (dryRun) {
+      r.status = 'would set';
+      log(`would set ${c.name} (${c.kind}${c.path ? ` ~/${c.path}` : ''}, ${bytes} bytes) for ${selector}`);
+      continue;
+    }
+    // env items: the CLI drops one trailing newline from stdin, so send exactly one.
+    const input = c.kind === 'env' ? got.value.replace(/\n$/, '') + '\n' : got.value;
+    const p = run(argv, { env, input });
+    if (p.ok) {
+      r.status = 'set';
+      log(`set    ${c.name} (${c.kind}${c.path ? ` ~/${c.path}` : ''}, ${bytes} bytes) for ${selector}`);
+    } else {
+      ok = false;
+      r.status = 'failed';
+      r.detail = mask(p.stderr || p.stdout, got.value);
+      log(`failed ${c.name} (${c.kind}): ${r.detail}`);
+    }
+  }
+  return { ok, results };
+}
+
+function main() {
+  const args = process.argv.slice(2);
+  const i = args.indexOf('--selection');
+  if (i < 0 || !args[i + 1]) {
+    process.stderr.write('usage: push-creds.mjs --selection selection.json [--dry-run]\n');
+    process.exit(2);
+  }
+  const sel = JSON.parse(readFileSync(args[i + 1], 'utf8'));
+  const { ok, results } = pushCreds(sel, { dryRun: args.includes('--dry-run'), instabox: process.env.INSTABOX_BIN || 'instabox' });
+  const n = (s) => results.filter((r) => r.status === s).length;
+  console.log(`\n${n('set')} set, ${n('kept')} already there, ${n('failed')} failed${args.includes('--dry-run') ? ' (dry run)' : ''}.`);
+  if (!args.includes('--dry-run') && n('set')) console.log(`Next: instabox vault push ${sel.box}`);
+  process.exit(ok ? 0 : 1);
+}
+
+if (isMain(import.meta)) main();