instabox 0.4.3 → 0.5.1

package/skills/instabox-basic-setup/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: instabox-basic-setup
+description: Use when the user wants their instabox boxes set up like their laptop — "put my tokens / dotfiles / git config into instabox", "set up my boxes like my laptop", "give every box my GitHub and Claude tokens", "move my setup to instabox", "move everything to instabox". Scans this machine, lets the user pick from a checkbox plan, then puts the picks into their instabox Vault, so every box (and every box created later) gets them: tokens (GH_TOKEN, CLAUDE_CODE_OAUTH_TOKEN, model and service API keys) as environment variables, and git and editor config (~/.gitconfig, global gitignore, ~/.vimrc, nvim, ~/.tmux.conf) as files. Moves no code: for a repo, use instabox-move-repo.
+metadata:
+  installed-by: instabox
+---
+
+# Put a basic setup into the instabox Vault
+
+This skill puts the user's personal setup into their instabox **Vault** (`instabox vault`: per-user secrets and files, written into their boxes), so every box of theirs starts with it: the ones running now (at their next start or resume, or at once with `instabox vault push <box>`) and every box created later. It copies no repository, no agent history, installs nothing and touches no box directly. To move a repository, use the `instabox-move-repo` skill. See the `instabox` skill for the CLI.
+
+What it moves, and nothing else:
+
+| Group | Becomes | From |
+| --- | --- | --- |
+| Tokens | Vault `env` items: on tmpfs in the box, set in every login shell; gone at a stop, back at the next start; never in a snapshot | `GH_TOKEN` from `gh auth token`; well-known model and service tokens exported in the shell files (`ANTHROPIC_API_KEY`, `CLAUDE_CODE_OAUTH_TOKEN`, `OPENAI_API_KEY`, `GEMINI_API_KEY`, `OPENROUTER_API_KEY`, `HF_TOKEN`, `NPM_TOKEN`, `VERCEL_TOKEN`, `CLOUDFLARE_API_TOKEN`, `SUPABASE_ACCESS_TOKEN`, `FLY_API_TOKEN`, `SENTRY_AUTH_TOKEN`, `LINEAR_API_KEY`, ...) or in this shell's environment. Other credential-looking exports are listed unchecked. |
+| Git | Vault `file` items in the box's home | `~/.gitconfig` (and `~/.config/git/config`), the global gitignore |
+| Editor and terminal | Vault `file` items | `~/.vimrc`, nvim's `init.lua` / `init.vim` and the `.lua` / `.vim` files around it (no plugin checkouts), `~/.tmux.conf` |
+
+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: tokens by name and place (never values), the files, and what cannot move. |
+| `plan.mjs` | `write`: the checkbox plan. `parse`: reads the edited plan back, strictly, as JSON. |
+| `push.mjs` | Puts the picks into the Vault, piping each value from its source into `instabox vault set` / `set-file`. `--dry-run` first. |
+| `content.mjs` | What a file becomes in the Vault (used by the other two). |
+
+**Never read, print or paste a credential value yourself**: not `gh auth token`, not `echo $OPENAI_API_KEY`, not `cat` of a shell file or of `~/.gitconfig`, never the macOS keychain. `push.mjs` is the only thing that touches values. If something needs a value the scripts cannot get, tell the user the command to run themselves (`instabox vault set NAME` prompts without echo).
+
+Before starting, tell the user plainly: a scan of this machine (nothing changes here), a plan file they edit, then their Vault gets what they checked. By default every box they have and will create gets it; they can scope it with a selector. Nothing is copied from a box back here, and nothing keeps the two in sync: to change something later, change it here and run this again.
+
+## 1. Scan
+
+```bash
+instabox whoami                                    # signed in? otherwise: instabox login
+S=~/.claude/skills/instabox-basic-setup/scripts    # or ~/.agents/skills/instabox-basic-setup/scripts: wherever this file is
+W=~/instabox-basic-setup && mkdir -p -m 700 "$W"
+node "$S/scan.mjs" > "$W/scan.json"
+instabox vault ls --json > "$W/vault.json"         # what is in the Vault already (names, no values)
+instabox usage --json | jq '.limits.vault // {}' > "$W/limits.json"
+```
+
+`instabox vault ls` fails with `API keys cannot manage the vault` when `INSTABOX_API_KEY` is set: ask the user to unset it and `instabox login`. A `404` means the server has no Vault: stop and say so.
+
+## 2. Write the plan and let the user choose
+
+```bash
+node "$S/plan.mjs" write --scan "$W/scan.json" --vault "$W/vault.json" > "$W/plan.md"
+```
+
+Add `--selector key=value` (comma-separated for more) only if the user wants the setup on some boxes, not all; the plan's `Selector:` line can be edited too (`*` is every box). A box gets the items when its metadata has every label (`instabox create --meta key=value`).
+
+`plan.md` has a `- [x]` / `- [ ]` line per item, in three sections (Tokens, Git, Editor and terminal), then a "Can't move" list with no checkboxes. Defaults:
+
+- Well-known tokens and every file are checked. Other credential-looking exports, and tokens the shell reads from the macOS keychain, are unchecked (checking the latter runs that keychain lookup once, at push time).
+- Something already in the Vault, set there some other way than this skill, is unchecked and says so: checking it **replaces** it (for every box its selector reached). Items this skill set on an earlier run are replaced without asking (the manifest, step 3).
+
+Show the user a short summary (which tokens, which files, what cannot move) and the path of the file, and ask them to edit the checkboxes and the selector, then tell you to go on. In Claude Code you may ask a coarse question first with AskUserQuestion (multiSelect: "Tokens / Git / Editor and terminal") and apply the answer by changing only `[x]` and `[ ]`; the user still gets the file for details.
+
+When they are done, read it back:
+
+```bash
+node "$S/plan.mjs" parse --scan "$W/scan.json" --vault "$W/vault.json" --limits "$W/limits.json" "$W/plan.md" > "$W/selection.json"
+```
+
+- Exit 1: the plan has problems (a malformed checkbox, a line deleted or duplicated, an unknown id, a bad selector, a plan from another scan or Vault state, a file that became empty or over 64 KiB). All are listed; show them, fix or let the user fix, parse again. Never fix a plan by editing ids or deleting lines. If the scan or Vault changed, run step 1 and 2 again.
+- Exit 3: over the Vault's limits (100 items, 256 KiB in all, items already there included; 64 KiB per item). The message gives the totals and the biggest lines: ask the user what to uncheck (nvim's files are one item each), or which old Vault items to remove (`instabox vault rm NAME`), then parse again.
+
+## 3. Push into the Vault
+
+```bash
+node "$S/push.mjs" --selection "$W/selection.json" --dry-run   # names, sizes, totals; writes nothing
+node "$S/push.mjs" --selection "$W/selection.json"
+```
+
+Show the user the dry run's lines before the real run. Values go from their source (`gh auth token`, a variable after sourcing the user's shell file, this environment) straight into the CLI's stdin. A shell file that only exports when interactive (the usual `case $- in *i*)` guard) is sourced a second time in an interactive shell, which may run its prompt setup; a token it still does not yield comes from this environment, or fails with the reason; the output is names, sizes and outcomes. Every value is read and the totals checked before anything is written: over the limits, nothing is written (exit 3). An item that appeared in the Vault after the plan was written is left alone (`kept`). A `failed` line names the item and why; give the user the command to set it themselves (`instabox vault set NAME`, which prompts without echo). Re-running is safe: the same items are set again.
+
+The run records what it set in `~/.config/instabox-basic-setup/pushed.json` (names, kinds, paths; no values), so the next run knows those are its own.
+
+What a file becomes (counted per file in the plan's sizes):
+
+- This machine's HOME is rewritten to the box's (`/data/home`); lines that look like a credential are replaced by a comment; macOS-only lines (`osxkeychain`, Homebrew paths, `pbcopy`, `reattach-to-user-namespace`, ...) are commented out.
+- `~/.gitconfig` also: commit and tag signing is turned off (`gpgsign`: the signing key is not on the box), `url."git@...".insteadOf` rewrites are commented out (the box has no SSH key), and when `GH_TOKEN` is in the Vault, gh's credential helper for github.com is added (what `gh auth setup-git` writes), so `git clone https://github.com/...` and `git push` use the token.
+
+## 4. Verify on a box (optional)
+
+If the user names a running box (`instabox ls`), or wants one to try, write the Vault into it now and look:
+
+```bash
+BOX=<box>
+instabox vault push "$BOX"            # writes now; lists variables and files written, and any "kept" path
+instabox vault show "$BOX"            # what it gets with its metadata
+instabox exec "$BOX" -- 'gh auth status; git config --get user.name; test -n "${CLAUDE_CODE_OAUTH_TOKEN-}${ANTHROPIC_API_KEY-}" && echo claude token set'
+```
+
+A `kept: ~/path (not written: ... symlink ...)` line means the box has a symlink in that path; tell the user. Check presence of a token, never print one. A box created with `--no-vault` gets nothing, ever; one whose metadata does not match the selector gets nothing either. Do not create a box for this unless the user asks.
+
+## 5. Report
+
+Tell the user, in short sections:
+
+- **In your Vault**: each token by name, each file by path, and which boxes get them (every box, or the selector). Running boxes get them at their next start or resume, or now with `instabox vault push <box>`; new boxes at once.
+- **Left alone**: what they unchecked, items kept because they were set some other way, failures with the reason. Items from an earlier run they unchecked this time are still in the Vault (the push prints them): `instabox vault rm NAME` removes one, and boxes lose it at their next write.
+- **Do these yourself**: every entry of `.manual` in `selection.json`, with its command, for example: Claude Code's sign-in — run `claude setup-token` here yourself, then `instabox vault set CLAUDE_CODE_OAUTH_TOKEN` and paste it (or `claude`, then `/login`, on each box); Codex — `codex login --device-auth` on the box, or `instabox vault set OPENAI_API_KEY`; `gh auth login` here if gh is not signed in.
+- **Good to know**: Vault files are written again at every start and resume, so an edit made to them on a box is replaced; change them here and run this skill again (or `instabox vault rm` the item to keep a box's own copy). Tokens are environment variables of login shells (SSH, `instabox exec`, the terminal), not of systemd services. Shell aliases, SSH keys, cloud credential files and agent config are not part of this setup.
+
+Delete `$W` when the user is done with it (it holds the scan, the plan and the Vault's item names, no values).

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

@@ -0,0 +1,98 @@
+// What a file item's content becomes in the Vault: the local file with this
+// machine's HOME rewritten to the box's, lines that look like credentials
+// removed and macOS-only lines commented out. ~/.gitconfig also gets a few
+// changes so git works on a box that has GH_TOKEN and no SSH key.
+//
+// Used by plan.mjs (for sizes) and push.mjs (for the upload). Nothing here
+// prints a file's content.
+import { readFileSync } from 'node:fs';
+import { basename, extname } from 'node:path';
+import { BOX_HOME, MACOS_ONLY, SECRET_KEY_LINE, SECRET_VALUE } from './lib.mjs';
+
+const TAG = '[instabox-basic-setup]';
+
+function commentStyle(path) {
+  const b = basename(path);
+  const e = extname(path);
+  if (e === '.lua') return '--';
+  if (e === '.vim' || b === '.vimrc' || b === '.gvimrc') return '"';
+  return '#';
+}
+
+const isComment = (line) => /^\s*(?:#|;|--|")/.test(line);
+
+// Filters one text file. Returns the new text and how many lines were changed.
+export function scrubText(text, { path, home }) {
+  const c = commentStyle(path);
+  let secrets = 0;
+  let macos = 0;
+  const out = text.split('\n').map((line) => {
+    if (SECRET_VALUE.test(line) || (SECRET_KEY_LINE.test(line) && !isComment(line))) {
+      secrets++;
+      return `${c} ${TAG} removed a line that looked like a credential`;
+    }
+    if (MACOS_ONLY.test(line) && !isComment(line)) {
+      macos++;
+      return `${c} ${TAG} macOS only: ${line.trim()}`;
+    }
+    return home ? line.split(home).join(BOX_HOME) : line;
+  });
+  return { text: out.join('\n'), secrets, macos };
+}
+
+// The credential helper `gh auth setup-git` writes: git over HTTPS uses GH_TOKEN through gh.
+export const GH_HELPER = [
+  '',
+  `# ${TAG}: git over HTTPS to GitHub uses GH_TOKEN (from the Vault) through gh`,
+  '[credential "https://github.com"]',
+  '\thelper =',
+  '\thelper = !gh auth git-credential',
+  '[credential "https://gist.github.com"]',
+  '\thelper =',
+  '\thelper = !gh auth git-credential',
+  '',
+].join('\n');
+
+// ~/.gitconfig for the box. ghToken: GH_TOKEN goes to the Vault too, so the gh helper is added.
+// Changes, besides scrubText's:
+//  - commit/tag signing is turned off: the signing key (GPG, SSH, 1Password) is not on the box;
+//  - url.<ssh>.insteadOf rewrites are commented out: the box has no SSH key, and they would
+//    send HTTPS remotes over SSH.
+export function gitconfigText(text, { home, ghToken }) {
+  const r = scrubText(text, { path: '.gitconfig', home });
+  let section = '';
+  let signing = 0;
+  let insteadOf = 0;
+  const lines = r.text.split('\n').map((line) => {
+    const h = line.match(/^\s*\[([^\]]*)\]/);
+    if (h) section = h[1].trim();
+    if (isComment(line)) return line;
+    if (/^\s*gpgsign\s*=\s*(?:true|yes|on|1)\s*$/i.test(line)) {
+      signing++;
+      return `# ${TAG} signing off (no signing key on the box): ${line.trim()}`;
+    }
+    if (/^\s*(?:push)?insteadof\s*=/i.test(line) && /^url\s+"(?:git@|ssh:\/\/)/i.test(section)) {
+      insteadOf++;
+      return `# ${TAG} no SSH key on the box: ${line.trim()}`;
+    }
+    return line;
+  });
+  let out = lines.join('\n');
+  if (ghToken) out = out.replace(/\n*$/, '\n') + GH_HELPER;
+  return { text: out, secrets: r.secrets, macos: r.macos, signing, insteadOf };
+}
+
+// The content of one file of a file item, or {error}. f: {path, src, transform}.
+export function fileContent(f, { home, ghToken = false } = {}) {
+  let buf;
+  try {
+    buf = readFileSync(f.src);
+  } catch (e) {
+    return { error: `${f.src}: ${e.code || 'unreadable'}` };
+  }
+  if (buf.includes(0)) return { error: `${f.src}: a binary file (the Vault holds text only)` };
+  const text = buf.toString('utf8');
+  if (f.transform === 'gitconfig') return gitconfigText(text, { home, ghToken });
+  if (f.transform === 'raw') return { text, secrets: 0, macos: 0 };
+  return scrubText(text, { path: f.path, home });
+}

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

@@ -0,0 +1,233 @@
+// Shared by the instabox-basic-setup scripts. Node >= 18, no dependencies.
+//
+// The one rule every function here keeps: a credential's value is never
+// returned to the agent, stored in a file or printed. Code that looks at a
+// secret returns names, places and sizes only.
+import { spawnSync } from 'node:child_process';
+import { lstatSync, readdirSync, readFileSync, realpathSync, statSync } 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). 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 they are called: token prefixes of the common
+// services, private keys, 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); 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|extraheader|private[_-]?key)[\w.-]*["']?\s*[=:]\s*["']?(?![0-9.]+\b|true\b|false\b)[^\s"',}]/i;
+
+// Model-provider and developer-service tokens: moved by default when found. Any other
+// credential-looking variable exported in a shell file is listed unchecked.
+export const WELL_KNOWN = new Set([
+  'GH_TOKEN',
+  'GITHUB_TOKEN',
+  'CLAUDE_CODE_OAUTH_TOKEN',
+  'ANTHROPIC_API_KEY',
+  'OPENAI_API_KEY',
+  'GEMINI_API_KEY',
+  'GOOGLE_API_KEY',
+  'GOOGLE_GENERATIVE_AI_API_KEY',
+  'OPENROUTER_API_KEY',
+  'GROQ_API_KEY',
+  'MISTRAL_API_KEY',
+  'DEEPSEEK_API_KEY',
+  'XAI_API_KEY',
+  'TOGETHER_API_KEY',
+  'FIREWORKS_API_KEY',
+  'PERPLEXITY_API_KEY',
+  'COHERE_API_KEY',
+  'VOYAGE_API_KEY',
+  'REPLICATE_API_TOKEN',
+  'ELEVENLABS_API_KEY',
+  'TAVILY_API_KEY',
+  'EXA_API_KEY',
+  'FIRECRAWL_API_KEY',
+  'BRAVE_API_KEY',
+  'PINECONE_API_KEY',
+  'HF_TOKEN',
+  'HUGGING_FACE_HUB_TOKEN',
+  'NPM_TOKEN',
+  'VERCEL_TOKEN',
+  'NETLIFY_AUTH_TOKEN',
+  'CLOUDFLARE_API_TOKEN',
+  'SUPABASE_ACCESS_TOKEN',
+  'FLY_API_TOKEN',
+  'RAILWAY_TOKEN',
+  'RENDER_API_KEY',
+  'NEON_API_KEY',
+  'SENTRY_AUTH_TOKEN',
+  'LINEAR_API_KEY',
+  'GITLAB_TOKEN',
+  'DIGITALOCEAN_ACCESS_TOKEN',
+]);
+
+// Names the Vault refuses for env items (docs/vault.md).
+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_')
+  );
+}
+
+export const isSecretName = (name) => SECRET_NAME.test(name);
+
+// Lines in macOS 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|\breattach-to-user-namespace\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, pkg/instaboxapi MaxVaultValueBytes); the server's own
+// come from `instabox usage --json` (.limits.vault) when it answers.
+export const VAULT_MAX_VALUE = 64 * 1024;
+export const VAULT_MAX_TOTAL = 256 * 1024;
+export const VAULT_MAX_ITEMS = 100;
+
+export const BOX_HOME = '/data/home';
+
+// 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;
+}
+
+// stat, following symlinks (dotfiles are often links into a dotfiles repo), or null.
+export function statOrNull(p) {
+  try {
+    return statSync(p);
+  } catch {
+    return null;
+  }
+}
+
+// Every regular file under dir (symlinks followed), as paths relative to it, sorted.
+export function listFiles(dir, skip = () => false, rel = '', depth = 0) {
+  const out = [];
+  if (depth > 8) return 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 = statOrNull(join(dir, r));
+    if (!st) continue;
+    if (st.isDirectory()) out.push(...listFiles(dir, skip, r, depth + 1));
+    else if (st.isFile()) out.push(r);
+  }
+  return out;
+}
+
+export function readText(p) {
+  try {
+    return readFileSync(p, 'utf8');
+  } catch {
+    return null;
+  }
+}
+
+export function human(bytes) {
+  if (bytes < 1024) return `${bytes} B`;
+  const u = ['KB', 'MB', 'GB'];
+  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]}`;
+}
+
+// The Vault item name for a file item: its path with / as -, as `instabox vault set-file` does.
+export function vaultFileName(path) {
+  return path
+    .replace(/^\./, '')
+    .replaceAll('/', '-')
+    .replace(/[^A-Za-z0-9._-]/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 128);
+}
+
+// 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;
+  return p.split('/').every((c) => c !== '' && c !== '.' && !c.startsWith('..'));
+}
+
+// A selector as the plan writes it: `*` (every box) or `key=value,key=value`.
+export function parseSelector(s) {
+  s = s.trim();
+  if (s === '*' || s === '') return {};
+  const out = {};
+  for (const part of s.split(',')) {
+    const m = part.trim().match(/^([A-Za-z0-9_.-]{1,63})=([^,]{0,512})$/);
+    if (!m) throw new Error(`selector ${JSON.stringify(s)}: write * or key=value,key=value`);
+    out[m[1]] = m[2];
+  }
+  if (Object.keys(out).length > 32) throw new Error('selector: 32 labels at most');
+  return out;
+}
+
+export function selectorString(sel) {
+  const e = Object.entries(sel || {}).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+  return e.length ? e.map(([k, v]) => `${k}=${v}`).join(',') : '*';
+}
+
+export function sameSelector(a, b) {
+  return selectorString(a) === selectorString(b);
+}
+
+// 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;
+  }
+}