instabox 0.4.3 → 0.5.1

package/skills/instabox-basic-setup/scripts/plan.mjs

@@ -0,0 +1,295 @@
+#!/usr/bin/env node
+// The checkbox plan between the scan and the push.
+//
+//   node plan.mjs write --scan scan.json --vault vault.json [--selector k=v,...] > plan.md
+//   node plan.mjs parse --scan scan.json --vault vault.json plan.md > selection.json
+//
+// vault.json is `instabox vault ls --json`: items already in the Vault. One
+// set there by an earlier run of this skill (listed in the manifest, see
+// push.mjs) is replaced; one set any other way is unchecked, and checking it
+// replaces it.
+//
+// `parse` reads the plan back strictly: every id exactly once, nothing
+// unknown, no malformed checkbox. Errors go to stderr, all at once, exit 1.
+// Over the Vault's limits: exit 3, with the sizes.
+import { createHash } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { fileContent } from './content.mjs';
+import {
+  VAULT_MAX_ITEMS,
+  VAULT_MAX_TOTAL,
+  VAULT_MAX_VALUE,
+  human,
+  isMain,
+  parseSelector,
+  selectorString,
+} from './lib.mjs';
+
+export const MANIFEST = join(homedir(), '.config', 'instabox-basic-setup', 'pushed.json');
+
+export function readManifest(path = MANIFEST) {
+  try {
+    const m = JSON.parse(readFileSync(path, 'utf8'));
+    return Array.isArray(m.items) ? m : { items: [] };
+  } catch {
+    return { items: [] };
+  }
+}
+
+const SECTIONS = [
+  ['tokens', 'Tokens', 'Environment variables, on tmpfs in the box (gone at a stop, back at the next start; never in a snapshot). Values go from this machine straight into the Vault and are never shown.'],
+  ['git', 'Git', 'Files in the box’s home, written at every start and resume.'],
+  ['editor', 'Editor and terminal', 'Files in the box’s home, written at every start and resume.'],
+];
+
+// Vault names an item writes: env name, or each file's item name.
+const vaultNames = (it) => (it.kind === 'env' ? [it.name] : it.files.map((f) => f.name));
+
+// What is in the Vault already under one of this item's names or paths: [{vault item, ours}].
+export function existingFor(it, vault, manifest) {
+  const ours = new Set((manifest?.items || []).map((m) => m.name));
+  const found = [];
+  const names = new Set(vaultNames(it));
+  const paths = new Set(it.kind === 'file' ? it.files.map((f) => f.path) : []);
+  for (const v of vault || []) {
+    if (names.has(v.name) || (v.path && paths.has(v.path))) found.push({ item: v, ours: ours.has(v.name) });
+  }
+  return found;
+}
+
+export function planDigest(scan, vault, manifest) {
+  const v = (vault || []).map((i) => [i.name, i.kind, i.path || '', selectorString(i.selector)]).sort();
+  const m = (manifest?.items || []).map((i) => i.name).sort();
+  return createHash('sha256').update(JSON.stringify([scan, v, m])).digest('hex').slice(0, 16);
+}
+
+// The default checkbox: the scan's, except that something set in the Vault some other way stays unless checked.
+function defaults(scan, vault, manifest) {
+  return scan.items.map((it) => {
+    const ex = existingFor(it, vault, manifest);
+    const theirs = ex.filter((e) => !e.ours);
+    return { it, ex, theirs, checked: it.checked && !theirs.length };
+  });
+}
+
+export function writePlan(scan, { vault = [], manifest = { items: [] }, selector = {} } = {}) {
+  const h = scan.home;
+  const out = [];
+  out.push('# instabox basic setup: plan', '');
+  out.push(
+    'Check `[x]` what goes into your instabox Vault and uncheck `[ ]` what stays out.',
+    'Do not edit the ids in backticks or delete lines: the agent reads this file back and stops on anything it does not recognise.',
+    '',
+    'The selector says which of your boxes get these items: `*` is every box, the ones you create later included;',
+    '`key=value` (comma-separated for more) only boxes with that metadata (`instabox create --meta key=value`).',
+    '',
+    `Selector: \`${selectorString(selector)}\``,
+    '',
+    `<!-- plan ${planDigest(scan, vault, manifest)}: written from this scan and Vault; scan again and write a new plan if either changed -->`,
+  );
+  const rows = defaults(scan, vault, manifest);
+  for (const [key, title, blurb] of SECTIONS) {
+    out.push('', `## ${title}`, '', blurb, '');
+    const mine = rows.filter((r) => r.it.section === key);
+    if (!mine.length) out.push('_Nothing found._');
+    for (const { it, ex, theirs, checked } of mine) {
+      let text;
+      if (it.kind === 'env') text = `${it.name} from ${it.from}`;
+      else if (it.files.length === 1) text = `~/${it.path} · ${human(it.bytes)}`;
+      else text = `~/${it.path}/: ${it.files.length} files · ${human(it.bytes)}`;
+      if (it.reason) text += ` · off by default: ${it.reason}`;
+      if (it.note) text += ` · ${it.note}`;
+      if (theirs.length)
+        text += ` · already in your Vault as ${theirs.map((e) => e.item.name).join(', ')}, set some other way: checking this replaces it`;
+      else if (ex.length) text += ' · replaces the copy from your last run';
+      out.push(`- [${checked ? 'x' : ' '}] \`${it.id}\` ${text}`);
+    }
+  }
+  out.push('', '## Can’t move: do these yourself', '');
+  out.push('No checkbox: the agent repeats these at the end, with the command for each.', '');
+  if (!scan.manual.length) out.push('_Nothing._');
+  for (const m of scan.manual) out.push(`- ${m.what}: ${m.why}. ${m.todo}`);
+  out.push('');
+  return out.join('\n');
+}
+
+export class PlanError extends Error {
+  constructor(errors, code = 1) {
+    super(errors.join('\n'));
+    this.errors = errors;
+    this.code = code;
+  }
+}
+
+// Reads the plan back. Throws PlanError listing every problem (code 1), or the limits (code 3).
+export function parsePlan(scan, text, { vault = [], manifest = { items: [] }, limits = {} } = {}) {
+  const maxItems = limits.maxItems || VAULT_MAX_ITEMS;
+  const maxBytes = limits.maxBytes || VAULT_MAX_TOTAL;
+  const errors = [];
+  const byId = new Map(scan.items.map((i) => [i.id, i]));
+  const state = new Map();
+  let selector = null;
+  let sawSelector = false;
+  let digest = null;
+  text.split('\n').forEach((raw, i) => {
+    const n = i + 1;
+    const l = raw.replace(/\r$/, '');
+    const s = l.match(/^Selector:\s*(.*)$/);
+    if (s && /^`/.test(s[1].trim())) {
+      if (sawSelector) errors.push(`line ${n}: a second Selector: line`);
+      sawSelector = true;
+      const m = s[1].trim().match(/^`([^`]*)`$/);
+      if (!m) errors.push(`line ${n}: write the selector in backticks: Selector: \`*\``);
+      else
+        try {
+          selector = parseSelector(m[1]);
+        } catch (e) {
+          errors.push(`line ${n}: ${e.message}`);
+        }
+      return;
+    }
+    const d = l.match(/<!-- plan ([0-9a-f]+):/);
+    if (d) digest = d[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*`(?:env|file|files):/.test(l)) return;
+    const m = l.match(/^- \[([ 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 (!byId.has(id)) return errors.push(`line ${n}: unknown id \`${id}\``);
+    if (state.has(id)) return errors.push(`line ${n}: \`${id}\` appears twice`);
+    state.set(id, mark !== ' ');
+  });
+  if (!sawSelector) errors.push('no "Selector: `*`" line (write `*` for every box)');
+  if (digest === null) errors.push('the "<!-- plan ... -->" line is missing: write the plan again');
+  else if (digest !== planDigest(scan, vault, manifest))
+    errors.push('this plan was written from a different scan or Vault: scan, list the Vault and write the plan again');
+  for (const id of byId.keys()) if (!state.has(id)) errors.push(`\`${id}\` is missing from the plan (uncheck a line instead of deleting it)`);
+  if (errors.length) throw new PlanError(errors);
+
+  const picked = scan.items.filter((i) => state.get(i.id));
+  // GH_TOKEN from this plan, or already in the Vault: either way gh's credential helper works.
+  const ghToken =
+    picked.some((i) => i.kind === 'env' && i.name === 'GH_TOKEN') || vault.some((v) => v.kind === 'env' && v.name === 'GH_TOKEN');
+  const items = [];
+  const sizes = [];
+  for (const it of picked) {
+    const ex = existingFor(it, vault, manifest);
+    const out = { ...it, replace: ex.map((e) => e.item.name) };
+    delete out.checked;
+    if (it.kind === 'file') {
+      out.files = it.files.map((f) => {
+        const c = fileContent(f, { home: scan.home, ghToken });
+        if (c.error) errors.push(`\`${it.id}\`: ${c.error}`);
+        const bytes = c.error ? 0 : Buffer.byteLength(c.text);
+        if (bytes > VAULT_MAX_VALUE) errors.push(`\`${it.id}\`: ~/${f.path} is ${human(bytes)}, over the Vault's 64 KiB per item: uncheck it`);
+        if (!c.error && !bytes) errors.push(`\`${it.id}\`: ~/${f.path} is empty, and the Vault takes no empty file: uncheck it`);
+        return { ...f, bytes };
+      });
+      out.bytes = out.files.reduce((s, f) => s + f.bytes, 0);
+    }
+    sizes.push({ id: it.id, items: vaultNames(it).length, bytes: out.bytes || 0 });
+    items.push(out);
+  }
+  if (errors.length) throw new PlanError(errors);
+
+  // The Vault's quotas count every item of the user, so what stays there counts too.
+  const replaced = new Set(items.flatMap((i) => i.replace));
+  const staying = vault.filter((v) => !replaced.has(v.name));
+  const stayBytes = staying.reduce((s, v) => s + (v.size || 0), 0);
+  const nItems = staying.length + sizes.reduce((s, x) => s + x.items, 0);
+  const nBytes = stayBytes + sizes.reduce((s, x) => s + x.bytes, 0);
+  const vaultUse = { items: nItems, maxItems, fileBytes: nBytes, maxBytes, staying: staying.length, stayingBytes: stayBytes };
+  if (nItems > maxItems || nBytes > maxBytes) {
+    const big = [...sizes].sort((a, b) => b.bytes - a.bytes || b.items - a.items).slice(0, 8);
+    throw new PlanError(
+      [
+        `over the Vault's limits: ${nItems} items of ${maxItems}, ${human(nBytes)} of ${human(maxBytes)} (tokens not counted yet), ${staying.length} items (${human(stayBytes)}) of them already in your Vault and staying.`,
+        `the biggest checked lines: ${big.map((b) => `\`${b.id}\` ${b.items} item${b.items === 1 ? '' : 's'}, ${human(b.bytes)}`).join('; ')}`,
+        'uncheck some, or remove Vault items you no longer need (`instabox vault ls`, `instabox vault rm NAME`)',
+      ],
+      3,
+    );
+  }
+
+  const ours = new Set((manifest.items || []).map((m) => m.name));
+  const pickedNames = new Set(items.flatMap(vaultNames));
+  return {
+    version: 2,
+    home: scan.home,
+    selector,
+    ghToken,
+    items,
+    manual: scan.manual,
+    skipped: scan.items.filter((i) => !state.get(i.id)).map((i) => i.id),
+    // From an earlier run and not in this plan any more: left in the Vault, listed in the report.
+    leftover: (manifest.items || []).filter((m) => !pickedNames.has(m.name) && vault.some((v) => v.name === m.name)).map((m) => m.name),
+    vault: vaultUse,
+    ours: [...ours],
+  };
+}
+
+function readVault(file) {
+  const v = JSON.parse(readFileSync(file, 'utf8'));
+  if (!Array.isArray(v.items)) throw new Error(`${file}: not \`instabox vault ls --json\` output`);
+  return v.items;
+}
+
+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] ?? '';
+    rest.splice(i, 2);
+    return v;
+  };
+  const usage = () => {
+    process.stderr.write(
+      'usage: plan.mjs write --scan scan.json --vault vault.json [--selector k=v,...] [--manifest FILE]\n' +
+        '       plan.mjs parse --scan scan.json --vault vault.json [--limits limits.json] [--manifest FILE] plan.md\n',
+    );
+    process.exit(2);
+  };
+  const scanFile = opt('--scan');
+  const vaultFile = opt('--vault');
+  const manifest = readManifest(opt('--manifest') || MANIFEST);
+  if (!scanFile || !vaultFile) usage();
+  const scan = JSON.parse(readFileSync(scanFile, 'utf8'));
+  const vault = readVault(vaultFile);
+  if (cmd === 'write') {
+    let selector = {};
+    const s = opt('--selector');
+    try {
+      if (s !== undefined) selector = parseSelector(s);
+    } catch (e) {
+      process.stderr.write(e.message + '\n');
+      process.exit(2);
+    }
+    if (rest.length) usage();
+    process.stdout.write(writePlan(scan, { vault, manifest, selector }));
+  } else if (cmd === 'parse') {
+    const lf = opt('--limits');
+    if (rest.length !== 1) usage();
+    let limits = {};
+    if (lf) {
+      try {
+        limits = JSON.parse(readFileSync(lf, 'utf8')) || {};
+      } catch {}
+    }
+    try {
+      const sel = parsePlan(scan, readFileSync(rest[0], 'utf8'), { vault, manifest, limits });
+      process.stdout.write(JSON.stringify(sel, null, 2) + '\n');
+    } catch (e) {
+      if (!(e instanceof PlanError)) throw e;
+      process.stderr.write(`${rest[0]}: ${e.code === 3 ? 'too big' : `${e.errors.length} problem(s)`}:\n${e.errors.map((x) => `  ${x}`).join('\n')}\n`);
+      process.exit(e.code);
+    }
+  } else usage();
+}
+
+if (isMain(import.meta)) main();

package/skills/instabox-basic-setup/scripts/push.mjs

@@ -0,0 +1,252 @@
+#!/usr/bin/env node
+// Puts the checked items into the Vault, piping each value from where it
+// lives straight into `instabox vault set` / `vault set-file`.
+//
+//   node push.mjs --selection selection.json --dry-run   # names, sizes, what it would do
+//   node push.mjs --selection selection.json
+//
+// 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. Output: one line per Vault item with its name, kind, size and outcome.
+//
+// Every value is read and the totals checked against the Vault's limits
+// before anything is written: over them, nothing is written (exit 3).
+// An item that is in the Vault now but was not when the plan was written,
+// and was not set by this skill, is left alone. The manifest
+// (~/.config/instabox-basic-setup/pushed.json: names, kinds, paths; no
+// values) records what this skill set, so a later run replaces those.
+import { spawnSync } from 'node:child_process';
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { fileContent } from './content.mjs';
+import { VAULT_MAX_ITEMS, VAULT_MAX_TOTAL, VAULT_MAX_VALUE, human, isMain, run, selectorString } from './lib.mjs';
+import { MANIFEST, readManifest } from './plan.mjs';
+
+const shellFor = (file) => (/\/\.z[^/]*$/.test(file) && spawnSync('zsh', ['-c', 'true']).status === 0 ? 'zsh' : 'bash');
+
+const NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
+
+// The values of some variables a shell startup file exports, sourcing it once: {name: value}.
+// Never logged. The file is sourced the way a shell does, its output discarded, and only the
+// variables are printed (NUL-separated: a shell variable cannot hold a NUL). Names still unset
+// after that get one more try in an interactive shell, for rc files that start with the usual
+// `case $- in *i*)` / `[[ -o interactive ]] || return` guard; that shell reads no startup file
+// of its own, so nothing it prints reaches the output.
+export function readRc(file, names, env = process.env) {
+  const got = {};
+  const zsh = shellFor(file) === 'zsh';
+  for (const interactive of [false, true]) {
+    const want = names.filter((n) => NAME.test(n) && !got[n]);
+    if (!want.length) break;
+    const flags = interactive ? (zsh ? ['-f', '-i'] : ['--norc', '--noprofile', '-i']) : [];
+    const script = `. "$1" >/dev/null 2>&1 </dev/null; printf '%s\\0' ${want.map((n) => `"\${${n}-}"`).join(' ')}`;
+    const r = spawnSync(zsh ? 'zsh' : 'bash', [...flags, '-c', script, 'instabox-basic-setup', file], {
+      env,
+      encoding: 'utf8',
+      timeout: 30_000,
+      stdio: ['ignore', 'pipe', 'ignore'],
+    });
+    const vals = (r.stdout || '').split('\0');
+    want.forEach((n, i) => {
+      if (vals[i]) got[n] = vals[i];
+    });
+  }
+  return got;
+}
+
+// The value of one token, or {error}. Never logged. rc: {file: {name: value}} already read by
+// readRc, so a file holding several tokens is sourced once.
+export function readValue(src, env = process.env, rc = {}) {
+  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': {
+        if (!NAME.test(src.name)) return { error: 'bad name' };
+        const v = (rc[src.file] ?? readRc(src.file, [src.name], env))[src.name];
+        if (v) return { value: v };
+        // The shell this runs from may have it already (an rc that returned early, or set it some other way).
+        if (env[src.name]) return { value: env[src.name] };
+        return {
+          error: `${src.name} is not set after sourcing ${src.file} (also tried as an interactive shell), nor in this environment`,
+        };
+      }
+      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})` };
+      }
+    }
+  } 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 writeManifest(path, items) {
+  mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+  const tmp = `${path}.tmp`;
+  writeFileSync(tmp, JSON.stringify({ version: 1, items }, null, 2) + '\n', { mode: 0o600 });
+  renameSync(tmp, path);
+}
+
+export function push(sel, { instabox = 'instabox', env = process.env, dryRun = false, manifestPath = MANIFEST, log = (s) => console.log(s) } = {}) {
+  const results = [];
+  const fail = (msg) => {
+    log(msg);
+    return { ok: false, code: 1, results };
+  };
+  const ls = run([instabox, 'vault', 'ls', '--json'], { env });
+  if (!ls.ok) return fail(`instabox vault ls failed: ${ls.stderr.trim().split('\n').pop()} (signed in? \`instabox login\`; INSTABOX_API_KEY must be unset)`);
+  let vault;
+  try {
+    vault = JSON.parse(ls.stdout).items || [];
+  } catch {
+    return fail('instabox vault ls --json did not print JSON; is the instabox CLI up to date?');
+  }
+  let maxItems = VAULT_MAX_ITEMS;
+  let maxBytes = VAULT_MAX_TOTAL;
+  const usage = run([instabox, 'usage', '--json'], { env });
+  try {
+    const l = JSON.parse(usage.stdout).limits?.vault;
+    if (l?.maxItems) maxItems = l.maxItems;
+    if (l?.maxBytes) maxBytes = l.maxBytes;
+  } catch {}
+
+  const manifest = readManifest(manifestPath);
+  const ours = new Set(manifest.items.map((m) => m.name));
+  const byName = new Map(vault.map((v) => [v.name, v]));
+  const byPath = new Map(vault.filter((v) => v.path).map((v) => [v.path, v]));
+  const selector = sel.selector || {};
+  // One --selector per label: the CLI's flag takes key=value and repeats.
+  const selFlag = Object.entries(selector).flatMap(([k, v]) => ['--selector', `${k}=${v}`]);
+
+  // 1. Every Vault item this selection makes, with its value, in memory only. Each shell
+  // startup file is sourced once for all the tokens read from it, and only if one is needed.
+  const rcNames = new Map();
+  for (const it of sel.items) {
+    if (it.kind !== 'env' || it.source?.type !== 'rc') continue;
+    if (!rcNames.has(it.source.file)) rcNames.set(it.source.file, []);
+    rcNames.get(it.source.file).push(it.source.name);
+  }
+  const rcValues = {};
+  const rcFor = (file) => (rcValues[file] ??= readRc(file, rcNames.get(file) || [], env));
+  const rcOf = (src) => (src.type === 'rc' ? { [src.file]: rcFor(src.file) } : {});
+  const plan = [];
+  for (const it of sel.items) {
+    const allowed = new Set(it.replace || []);
+    const units =
+      it.kind === 'env'
+        ? [{ name: it.name, kind: 'env', get: () => readValue(it.source, env, rcOf(it.source)) }]
+        : it.files.map((f) => ({ name: f.name, kind: 'file', path: f.path, get: () => fileContent(f, { home: sel.home, ghToken: sel.ghToken }) }));
+    for (const u of units) {
+      const r = { id: it.id, name: u.name, kind: u.kind, path: u.path };
+      results.push(r);
+      // A file's path first: the Vault holds one file item per path, so whoever writes it is the one replaced.
+      const old = (u.path && byPath.get(u.path)) || byName.get(u.name);
+      if (old && !ours.has(old.name) && !allowed.has(old.name)) {
+        r.status = 'kept';
+        r.detail = `already in your Vault as ${old.name} (${old.kind}${old.path ? ` ~/${old.path}` : ''}, selector ${selectorString(old.selector)}), set some other way since the plan was written: left unchanged`;
+        log(`kept   ${u.name}: ${r.detail}`);
+        continue;
+      }
+      // A file item already writing this path under another name is replaced under its own name:
+      // the Vault allows one file item per path, so a second name would be refused.
+      if (old && u.path && old.path === u.path && old.name !== u.name) {
+        u.name = old.name;
+        r.name = old.name;
+      }
+      const got = u.get();
+      const value = got.error ? null : got.value ?? got.text;
+      if (got.error || value === '' || value == null) {
+        r.status = 'failed';
+        r.detail = got.error || 'empty';
+        log(`failed ${u.name} (${u.kind}): ${r.detail}`);
+        continue;
+      }
+      const sent = u.kind === 'env' ? value.replace(/\n$/, '') : value;
+      r.bytes = Buffer.byteLength(sent);
+      if (r.bytes > VAULT_MAX_VALUE) {
+        r.status = 'failed';
+        r.detail = `${r.bytes} bytes: over the Vault's 64 KiB per item`;
+        log(`failed ${u.name} (${u.kind}): ${r.detail}`);
+        continue;
+      }
+      plan.push({ r, u, old, sent });
+    }
+  }
+
+  // 2. The quotas: what stays in the Vault plus what this run sets.
+  const replacing = new Set(plan.filter((p) => p.old).map((p) => p.old.name));
+  const staying = vault.filter((v) => !replacing.has(v.name));
+  const nItems = staying.length + plan.length;
+  const nBytes = staying.reduce((s, v) => s + (v.size || 0), 0) + plan.reduce((s, p) => s + p.r.bytes, 0);
+  const totals = { items: nItems, maxItems, bytes: nBytes, maxBytes };
+  if (nItems > maxItems || nBytes > maxBytes) {
+    const big = [...plan].sort((a, b) => b.r.bytes - a.r.bytes).slice(0, 8);
+    log(
+      `over the Vault's limits, nothing written: ${nItems} items of ${maxItems}, ${human(nBytes)} of ${human(maxBytes)}. ` +
+        `Biggest: ${big.map((p) => `${p.u.name} ${human(p.r.bytes)}`).join(', ')}. Uncheck some in the plan, or remove items you no longer need (instabox vault rm NAME).`,
+    );
+    return { ok: false, code: 3, results, totals };
+  }
+
+  // 3. Write.
+  let ok = !results.some((r) => r.status === 'failed');
+  const where = Object.keys(selector).length ? `boxes with ${selectorString(selector)}` : 'every box';
+  for (const { r, u, sent } of plan) {
+    const what = `${u.name} (${u.kind}${u.path ? ` ~/${u.path}` : ''}, ${r.bytes} bytes) for ${where}`;
+    if (dryRun) {
+      r.status = 'would set';
+      log(`would set ${what}`);
+      continue;
+    }
+    const argv =
+      u.kind === 'env'
+        ? [instabox, 'vault', 'set', u.name, ...selFlag]
+        : [instabox, 'vault', 'set-file', u.path, '--name', u.name, ...selFlag];
+    // env items: the CLI drops one trailing newline from stdin, so send exactly one.
+    const p = run(argv, { env, input: u.kind === 'env' ? sent + '\n' : sent });
+    if (p.ok) {
+      r.status = 'set';
+      log(`set    ${what}`);
+    } else {
+      ok = false;
+      r.status = 'failed';
+      r.detail = mask(p.stderr || p.stdout, sent);
+      log(`failed ${u.name} (${u.kind}): ${r.detail}`);
+    }
+  }
+  if (!dryRun) {
+    const set = new Map(manifest.items.map((m) => [m.name, m]));
+    for (const { r } of plan) if (r.status === 'set') set.set(r.name, { name: r.name, kind: r.kind, ...(r.path ? { path: r.path } : {}) });
+    // Forget names that are gone from the Vault (removed by hand since).
+    const live = new Set([...vault.map((v) => v.name), ...plan.filter((p) => p.r.status === 'set').map((p) => p.r.name)]);
+    writeManifest(manifestPath, [...set.values()].filter((m) => live.has(m.name)).sort((a, b) => (a.name < b.name ? -1 : 1)));
+  }
+  return { ok, code: ok ? 0 : 1, results, totals };
+}
+
+function main() {
+  const args = process.argv.slice(2);
+  const i = args.indexOf('--selection');
+  if (i < 0 || !args[i + 1]) {
+    process.stderr.write('usage: push.mjs --selection selection.json [--dry-run]\n');
+    process.exit(2);
+  }
+  const dryRun = args.includes('--dry-run');
+  const sel = JSON.parse(readFileSync(args[i + 1], 'utf8'));
+  const { code, results, totals } = push(sel, { dryRun, instabox: process.env.INSTABOX_BIN || 'instabox' });
+  const n = (s) => results.filter((r) => r.status === s).length;
+  console.log(
+    `\n${dryRun ? `${n('would set')} would be set` : `${n('set')} set`}, ${n('kept')} left as they were, ${n('failed')} failed${dryRun ? ' (dry run)' : ''}.`,
+  );
+  if (totals) console.log(`Vault after this: ${totals.items} of ${totals.maxItems} items, ${human(totals.bytes)} of ${human(totals.maxBytes)}.`);
+  if (sel.leftover?.length) console.log(`Still in your Vault from an earlier run, unchecked now: ${sel.leftover.join(' ')} (remove with instabox vault rm NAME).`);
+  process.exit(code);
+}
+
+if (isMain(import.meta)) main();