instabox 0.4.2 → 0.4.3

package/README.md

@@ -4,9 +4,9 @@
 npx instabox@latest
 ```
 
-Signs you in to instabox in your browser (first run only; Google by default, `--github` for GitHub), lets you pick one of your boxes or start a new one (no boxes yet: a new one, no question; `--box NAME` skips the question), installs the `instabox` CLI already signed in or updates an out-of-date one (macOS/Linux; skip with `--no-cli`), installs or updates the agent skills from [`../skills`](../skills) in `~/.claude/skills` and `~/.agents/skills` (skip with `--no-skills`), and drops you into the box over SSH. `npx instabox@latest sh` does the same.
+Signs you in to instabox in your browser (first run only; GitHub by default, `--google` for Google), lets you pick one of your boxes or start a new one (no boxes yet: a new one, no question; `--box NAME` skips the question), installs the `instabox` CLI already signed in or updates an out-of-date one (macOS/Linux; skip with `--no-cli`), installs or updates the agent skills from [`../skills`](../skills) in `~/.claude/skills` and `~/.agents/skills` (skip with `--no-skills`), and drops you into the box over SSH. `npx instabox@latest sh` does the same.
 
-Google and GitHub sign-ins are separate instabox accounts, each with its own boxes. The CLI's own `instabox login` signs in with GitHub by default (`--provider google` for Google), so when the CLI needs a new sign-in, `instabox login --provider google` keeps you in the account you used here with Google.
+A GitHub and a Google sign-in are separate instabox accounts, each with its own boxes, so this and the CLI's own `instabox login` default to the same provider, GitHub. With `--google`, the account is the Google one, and the CLI reaches it with `instabox login --provider google`.
 
 Any other command line is the instabox CLI's ([`cmd/instabox`](../cmd/instabox)): `npx instabox@latest ls` runs `instabox ls`, installing the CLI first if it is missing.
 
@@ -26,7 +26,7 @@ npm ci
 npm test
 npm run format:check
 npm pack            # copies ../skills, then builds instabox-<version>.tgz
-npx --package=./instabox-0.4.2.tgz instabox --help
+npx --package=./instabox-0.4.3.tgz instabox --help
 ```
 
 `INSTABOX_API_URL` points it at another instabox server.

package/bin/instabox.mjs

@@ -34,7 +34,10 @@ const API = (
 const IMAGE = process.env.INSTABOX_IMAGE || 'universal';
 // SSH certificate lifetime for a box with no timeout of its own.
 const CERT_MIN = 120;
-const PROVIDER = process.argv.includes('--github') ? 'github' : 'google';
+// GitHub, the provider the instabox CLI itself signs in with: a GitHub and a
+// Google sign-in are separate accounts, and the two entry points disagreeing
+// put one person in both. --google is still here for a Google account.
+const PROVIDER = process.argv.includes('--google') ? 'google' : 'github';
 const bold = (s) => (process.stdout.isTTY ? `\x1b[1m${s}\x1b[0m` : s);
 const dim = (s) => (process.stdout.isTTY ? `\x1b[2m${s}\x1b[0m` : s);
 const green = (s) => (process.stdout.isTTY ? `\x1b[32m${s}\x1b[0m` : s);
@@ -53,8 +56,9 @@ function usage() {
   npx instabox@latest               sign in (first time), pick one of your boxes or start a new
                                     one, SSH into it, and install the instabox CLI and agent skills
       --box NAME                    go straight to that box instead of asking
-      --github                      sign in with GitHub instead of Google (a separate account;
-                                    instabox login uses GitHub, --provider google for Google)
+      --google                      sign in with Google instead of GitHub (a separate account
+                                    with its own boxes; instabox login --provider google
+                                    signs the CLI in to the same one)
       --no-cli                      do not install or update the instabox CLI
       --no-skills                   do not install the instabox agent skills
   npx instabox@latest <command>     run an instabox CLI command (instabox help lists them)
@@ -293,8 +297,19 @@ async function ensureCli() {
   );
 }
 
-// Agent skills shipped in this package (skills/<name>/SKILL.md) into the folders coding agents
-// read. Overwrites only copies we installed earlier (marked `installed-by: instabox`).
+// A skill directory's files, relative to it, sorted.
+function skillFiles(dir, rel = '') {
+  return readdirSync(join(dir, rel), { withFileTypes: true })
+    .sort((a, b) => a.name.localeCompare(b.name))
+    .flatMap((e) => {
+      const r = rel ? `${rel}/${e.name}` : e.name;
+      return e.isDirectory() ? skillFiles(dir, r) : e.isFile() ? [r] : [];
+    });
+}
+
+// Agent skills shipped in this package (skills/<name>/SKILL.md, with any scripts beside it) into
+// the folders coding agents read. Overwrites only copies we installed earlier (marked
+// `installed-by: instabox`).
 function installSkills() {
   if (process.argv.includes('--no-skills')) return null;
   const src = join(dirname(fileURLToPath(import.meta.url)), '..', 'skills');
@@ -313,7 +328,6 @@ function installSkills() {
     for (const n of names) {
       const dest = join(root, n, 'SKILL.md');
       try {
-        const body = readFileSync(join(src, n, 'SKILL.md'), 'utf8');
         let what = 'installed';
         if (existsSync(dest)) {
           const old = readFileSync(dest, 'utf8');
@@ -321,11 +335,16 @@ function installSkills() {
             kept.add(n);
             continue;
           }
-          what = old === body ? 'unchanged' : 'updated';
+          what = 'unchanged';
         }
-        if (what !== 'unchanged') {
-          mkdirSync(join(root, n), { recursive: true });
-          writeFileSync(dest, body);
+        // SKILL.md and whatever else the skill ships (scripts/...).
+        for (const f of skillFiles(join(src, n))) {
+          const body = readFileSync(join(src, n, f));
+          const to = join(root, n, f);
+          if (existsSync(to) && readFileSync(to).equals(body)) continue;
+          if (what === 'unchanged') what = 'updated';
+          mkdirSync(dirname(to), { recursive: true });
+          writeFileSync(to, body);
         }
         if (rank[what] > (rank[outcome.get(n)] ?? -1)) outcome.set(n, what);
       } catch {}

package/lib/cli.mjs

@@ -5,7 +5,7 @@ import { createReadStream, realpathSync, statSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { delimiter, join, sep } from 'node:path';
 
-const OUR_FLAGS = new Set(['--github', '--no-cli', '--no-skills']);
+const OUR_FLAGS = new Set(['--github', '--google', '--no-cli', '--no-skills']);
 
 // Bare `instabox` (or the old `sh`) with only our flags; anything else is a CLI command.
 export function isOnboarding(args) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instabox",
-  "version": "0.4.2",
+  "version": "0.4.3",
   "description": "A cloud box for your coding agent, the instabox CLI and its agent skills in one command: npx instabox@latest",
   "type": "module",
   "bin": {

package/skills/instabox/SKILL.md

@@ -16,7 +16,7 @@ instabox whoami              # who is signed in (fails if nobody)
 instabox login               # browser sign-in with GitHub; --provider google for Google
 ```
 
-A GitHub sign-in and a Google sign-in are separate accounts with separate boxes, so sign in the way the user did. `npx instabox@latest` signs in with Google unless given `--github`, and the CLI shares its sign-in.
+A GitHub sign-in and a Google sign-in are separate accounts with separate boxes, so sign in the way the user did. Both `instabox login` and `npx instabox@latest` sign in with GitHub unless given `--provider google` or `--google`, and the CLI shares the sign-in `npx` made.
 
 For CI or an agent without a browser, use an API key instead: `export INSTABOX_API_KEY=ibk_...` (the user creates it on the dashboard's API Keys page). Never print, commit or log a key.
 

package/skills/instabox-move-all/SKILL.md

@@ -0,0 +1,158 @@
+---
+name: instabox-move-all
+description: Use when the user wants to move their whole local setup onto instabox, not just one repo — "move everything to instabox", "move my whole setup", "all my projects to a box", "set up a box like my laptop". Scans this machine (repos with unsaved work, agent history, credentials, dotfiles, agent config, global tools), lets the user pick from a checkbox plan, then moves the picks onto one new box. The bulk version of instabox-migrate.
+metadata:
+  installed-by: instabox
+---
+
+# Move a whole local setup to instabox
+
+The bulk version of the `instabox-migrate` skill: instead of the current repo, it moves everything the user picks onto **one new box**. Each repo goes over exactly as `instabox-migrate` moves one; this skill adds the scan, the plan, credentials and the environment around it. See the `instabox` skill for the CLI.
+
+Four scripts in `scripts/` next to this file do the parts that must be exact (Node 18+, nothing to install):
+
+| Script | Does |
+| --- | --- |
+| `scan.mjs` | Read-only inventory, as JSON. Credentials by name and place only, never values. |
+| `plan.mjs` | `write`: the checkbox plan from the scan. `parse`: reads the edited plan back, strictly, as JSON. |
+| `stage-env.mjs` | Copies the picked dotfiles and agent config into a local directory, credentials and macOS-only lines removed, plus a setup script for the box. |
+| `push-creds.mjs` | Puts the picked credentials into the Vault for this box only, piping each value from its source into `instabox vault set`. |
+
+**Never read, print or paste a credential value yourself**: not `gh auth token`, not `cat ~/.aws/credentials`, not `echo $OPENAI_API_KEY`, not a `.env`. `push-creds.mjs` is the only thing that touches values. If a credential needs something the script cannot do, tell the user the command to run themselves.
+
+Before starting, tell the user plainly:
+
+- What happens: a scan of this machine (nothing changes here), a plan file they edit, then one new box with what they checked. Their local copies stay as they are, and nothing keeps the two in sync afterwards.
+- **Agent conversation history can contain secrets they pasted into a chat.** It is a separate checkbox per repo.
+- Some sign-ins cannot move (below); the final report says what to run on the box for each.
+
+## 1. Scan
+
+```bash
+instabox whoami                                   # signed in? otherwise: instabox login
+S=~/.claude/skills/instabox-move-all/scripts      # or ~/.agents/skills/instabox-move-all/scripts: wherever this file is
+W=~/instabox-move && mkdir -p -m 700 "$W"
+node "$S/scan.mjs" > "$W/scan.json"
+```
+
+It looks for git repos under `~/Work ~/work ~/code ~/src ~/projects ~/dev ~/Developer ~/repos ~/git ~/github` (three levels down), the current directory's repo, and any repo the user's Claude Code or Codex history points at. If the user keeps code elsewhere, add `--root DIR` (repeatable); `--depth N` to look deeper; `--no-tools` to skip asking brew/npm/uv/cargo.
+
+What it finds, in four lists:
+
+- `work`: each repo with its branch, changed / untracked / stashed / unpushed counts, whether it has a remote, and its size the way `instabox-migrate` copies it (`.git` plus files git does not ignore). Its box directory is `/data/workspace/<name>`, `-2`, `-3`... when two repos share a name.
+- `history`: Claude Code (`~/.claude/projects`) and Codex (`~/.codex/sessions`) sessions, per repo.
+- `credentials`: each with where it comes from and what it becomes: a Vault `env` item, a Vault `file` item, or `manual` (cannot move, with the reason and the command to run on the box).
+- `environment`: dotfiles, Claude Code and Codex config, skills, local MCP servers, and global tools (`brew leaves`, `npm -g`, `uv tool`, `cargo install`, `~/go/bin`).
+
+## 2. Write the plan and let the user choose
+
+Pick a box name `instabox ls` does not show (lowercase letters, digits, `-`), then:
+
+```bash
+BOX=<box>
+node "$S/plan.mjs" write --scan "$W/scan.json" --box "$BOX" > "$W/migrate-plan.md"
+```
+
+`migrate-plan.md` has three sections, Work, Credentials and Environment, one `- [x]` / `- [ ]` line per item with its size and where it goes. Defaults:
+
+- Repos with work that exists only here (uncommitted, untracked, stashed, unpushed, or no remote) are checked, with their history. Clean, pushed repos are unchecked: they can be cloned again.
+- Credentials that work as a token or a file are checked. SSH private keys are unchecked (prefer `GH_TOKEN` over HTTPS, or a new key made on the box). Sign-ins that cannot move are unchecked and marked "can't move".
+- Dotfiles, agent config and tools are checked.
+
+Show the user a short summary (how many repos and how big, which credentials, what cannot move) and the path of the file, and ask them to edit the checkboxes and the `Box:` line, then tell you to go on. In Claude Code you may first ask a few coarse questions with AskUserQuestion (multiSelect), such as "Move: repos with unsaved work / every repo / credentials / dotfiles and agent config / tools", and apply the answers to the plan by changing only `[x]` and `[ ]`; the user still gets the file for the details.
+
+When they are done, read it back:
+
+```bash
+GIB=$(instabox usage --json | jq -r '.limits.machineSpec.persistentDiskGiB // 20')
+node "$S/plan.mjs" parse --scan "$W/scan.json" --disk-gib "$GIB" "$W/migrate-plan.md" > "$W/selection.json"
+```
+
+- Exit 1: the plan has problems (a malformed checkbox, a line deleted or duplicated, an unknown id, a "can't move" item checked, history checked without its repo, a bad box name, a plan from an older scan). All are listed; show them to the user, fix or let them fix, and parse again. Never fix a plan by editing ids or deleting lines.
+- Exit 2: a usage error, e.g. `--disk-gib` is empty because `instabox usage` failed. Fix that (`instabox login`) and parse again; never drop `--disk-gib`.
+- Exit 3: too big. Every box has the same `/data` disk, and half of it stays free for dependencies and builds. Ask the user what to uncheck (the message gives the sizes), then parse again.
+- Warnings about the Vault's limits (100 items, 256 KiB in all): ask the user to uncheck some credential files.
+
+From here on, `selection.json` is the plan: `.box`, `.work`, `.history`, `.credentials`, `.environment`, `.tools`, `.manual` (what the user must do by hand) and `.bytes`.
+
+## 3. Create the box
+
+```bash
+BOX=$(jq -r .box "$W/selection.json")
+instabox create --name "$BOX" --meta migrated="$BOX"
+instabox ls --meta migrated="$BOX"                     # exactly this box
+instabox exec "$BOX" -- df -h /data                    # room for what is coming
+```
+
+The `migrated=<box>` label is what the credentials select on (next step), so they reach this box and no other. No `--timeout`: this box is meant to stay (offer `instabox timeout "$BOX" 8h --on-timeout pause` if the user wants it to pause itself).
+
+## 4. Credentials into the Vault
+
+```bash
+node "$S/push-creds.mjs" --selection "$W/selection.json" --dry-run   # names and sizes only
+node "$S/push-creds.mjs" --selection "$W/selection.json"
+instabox vault push "$BOX"
+instabox vault show "$BOX"
+```
+
+Every item gets the selector `migrated=<box>`. Values go from their source (a variable sourced from the user's shell file, `gh auth token`, a key in `~/.codex/auth.json`, a file) straight into the CLI's stdin; the output is names, sizes and outcomes. An item already in the Vault under the same name or path is left alone (it would change what other boxes get), unless it is from an earlier run of this move; the output says which. `.env` files of repos go in as Vault files under `~/.config/instabox-move/env/<repo>/` and are linked into the repo in step 5. If an item fails, tell the user what failed and the command to set it themselves, for example `instabox vault set NAME --selector migrated=<box>` (it prompts without echo).
+
+## 5. Environment
+
+```bash
+node "$S/stage-env.mjs" --selection "$W/selection.json" --out "$W/stage"
+COPYFILE_DISABLE=1 tar -C "$W/stage" -czf - . |
+  instabox ssh "$BOX" -- 'tar -xzf - --skip-old-files --no-overwrite-dir --warning=no-unknown-keyword -C ~'
+instabox ssh "$BOX" -- 'bash -l ~/.config/instabox-move/setup.sh'
+rm -rf "$W/stage"
+```
+
+What the staged copy and `setup.sh` do on the box:
+
+- Lines that look like credentials are replaced by a comment; macOS-only lines (Homebrew paths, `osxkeychain`, `UseKeychain`, `pbcopy`, ...) are commented out; this machine's HOME becomes `/data/home`. The JSON summary printed by `stage-env.mjs` counts the lines changed per file.
+- The box keeps its own startup files: `~/.bashrc` sources the user's bash files, `~/.gitconfig` includes theirs, Claude Code `settings.json` is merged (theirs wins), `CLAUDE.md` / `AGENTS.md` are appended. Files the box already has are not overwritten (`--skip-old-files`). zsh is installed when there is a `.zshrc`; bash stays the login shell.
+- Skills, commands and agents go to `~/.claude/...` and `~/.agents/skills`; local MCP servers are added with `claude mcp add-json` (their secrets come from the Vault as environment variables).
+- Tools are installed fresh: Homebrew formulae through a table of Debian packages (or `uv tool` / `npm -g`), npm globals, `uv tool`, `cargo install`, `go install`. No macOS binary is copied. Formulae without a mapping are listed in `.manual`.
+
+`setup.sh` is safe to run again. Run it over `ssh` (installs can take minutes). It carries on past a failed step, then lists every failed step and exits 1: report those to the user, fix what you can on the box and run it again. Then check the shells still parse: `instabox exec "$BOX" -- 'bash -n ~/.bashrc; [ -f ~/.zshrc ] && zsh -n ~/.zshrc'`. Fix a broken line in the staged copy under `~/.config/instabox-move/shell/` on the box.
+
+## 6. Work: each repo
+
+For each repo in `selection.json`:
+
+```bash
+jq -r '.work[] | [.path, .name] | @tsv' "$W/selection.json"
+jq -r '.history[].repo' "$W/selection.json"        # repos whose history goes too ("repo:<path>")
+```
+
+follow **steps 2, 3 and 4 of the `instabox-migrate` skill** for that repo, with two changes:
+
+- `cd` into the repo's path first, and set `NAME` to the repo's `name` from `selection.json` instead of the `basename` line, so two repos with the same name do not land in one directory.
+- Copy the Claude Code and Codex history (the second and third parts of its step 2, and its step 3) only if the repo is in `.history`.
+
+Its checks apply: the box must show the same `git status` and `HEAD`. Do the dependency installs and builds of its step 4 per repo; the tools and `.env` links from step 5 are already there.
+
+## 7. Verify and report
+
+```bash
+instabox exec "$BOX" -- 'gh auth status; git config user.name; claude --version; codex --version'
+instabox exec "$BOX" -- 'test "${GH_TOKEN+x}" = x && echo GH_TOKEN set'   # presence only; same for other names
+instabox vault show "$BOX"
+```
+
+Tell the user, in short sections:
+
+- **Moved**: the box name (`instabox ssh <box>`), each repo with its directory and whether it builds and its tests pass, the credentials now in the Vault for this box, the environment and tools installed.
+- **Skipped**: what they unchecked, and anything that failed (with the reason).
+- **To do by hand**: every entry of `.manual`, with its exact command (for example `codex login --device-auth`, `claude` then `/login`, `gcloud auth login --no-launch-browser`, `docker login ghcr.io`, `aws sso login --use-device-code`), and how to pick up old conversations (`claude --continue` in a repo; `codex resume <id>`).
+- The credentials reach only boxes with the label `migrated=<box>`; a box created later with `--meta migrated=<box>` gets them too. Remove one with `instabox vault rm NAME`.
+- Ignored files stayed behind (except the `.env` files that went to the Vault), and secrets in committed files or in the copied history went over.
+
+Delete `$W` when the user is done with it (it holds the scan and plan, no values).
+
+## What cannot move, and why
+
+- **Rotating OAuth sign-ins**: Claude Code's login, Codex's ChatGPT login (`~/.codex/auth.json` tokens), gcloud user credentials, remote MCP servers signed in with OAuth. Their refresh token changes on use, so a copy would sign one side out. Sign in again on the box.
+- **macOS keychain-bound**: Docker's `credsStore`, Claude Code on macOS, AWS `credential_process` helpers. The keychain does not exist on the box. (`gh`'s keychain token can move: it is read with `gh auth token`.)
+- **Short-lived**: AWS SSO sessions and `aws_session_token`. Sign in on the box.
+- **Too big**: a credential file over 64 KiB; the plan says how to copy it.

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;
+  }
+}