@blurname/debrief 0.1.0

package/dist/debrief.js

@@ -0,0 +1,1207 @@
+#!/usr/bin/env node
+// @bun
+
+// src/backends/mock.ts
+import { join as join2 } from "node:path";
+
+// src/version.ts
+function parseVersion(raw) {
+  const v = raw.trim();
+  let epoch = 0;
+  let rest = v;
+  const colon = v.indexOf(":");
+  if (colon !== -1) {
+    const e = v.slice(0, colon);
+    if (/^\d+$/.test(e)) {
+      epoch = parseInt(e, 10);
+      rest = v.slice(colon + 1);
+    }
+  }
+  let upstream = rest;
+  let revision = "";
+  const dash = rest.lastIndexOf("-");
+  if (dash !== -1) {
+    upstream = rest.slice(0, dash);
+    revision = rest.slice(dash + 1);
+  }
+  return { epoch, upstream, revision };
+}
+function order(c) {
+  if (c === undefined || c === "")
+    return 0;
+  if (c === "~")
+    return -1;
+  if (/[a-zA-Z]/.test(c))
+    return c.charCodeAt(0);
+  return c.charCodeAt(0) + 256;
+}
+var isDigit = (c) => c !== undefined && c >= "0" && c <= "9";
+function verrevcmp(a, b) {
+  let i = 0;
+  let j = 0;
+  while (i < a.length || j < b.length) {
+    while (i < a.length && !isDigit(a[i]) || j < b.length && !isDigit(b[j])) {
+      const ac = order(a[i]);
+      const bc = order(b[j]);
+      if (ac !== bc)
+        return ac - bc;
+      i++;
+      j++;
+    }
+    while (a[i] === "0")
+      i++;
+    while (b[j] === "0")
+      j++;
+    let firstDiff = 0;
+    while (isDigit(a[i]) && isDigit(b[j])) {
+      if (firstDiff === 0)
+        firstDiff = a.charCodeAt(i) - b.charCodeAt(j);
+      i++;
+      j++;
+    }
+    if (isDigit(a[i]))
+      return 1;
+    if (isDigit(b[j]))
+      return -1;
+    if (firstDiff !== 0)
+      return firstDiff;
+  }
+  return 0;
+}
+function compareVersions(a, b) {
+  const va = parseVersion(a);
+  const vb = parseVersion(b);
+  if (va.epoch !== vb.epoch)
+    return va.epoch - vb.epoch;
+  const up = verrevcmp(va.upstream, vb.upstream);
+  if (up !== 0)
+    return up;
+  return verrevcmp(va.revision, vb.revision);
+}
+function maxVersion(versions) {
+  if (versions.length === 0)
+    return;
+  return versions.reduce((best, v) => compareVersions(v, best) > 0 ? v : best);
+}
+function numericComponents(upstream) {
+  const out = [];
+  for (const part of upstream.split(".")) {
+    const m = /^(\d+)/.exec(part);
+    if (!m)
+      break;
+    out.push(parseInt(m[1], 10));
+    if (m[1].length !== part.length)
+      break;
+  }
+  return out;
+}
+var gte = (v, bound) => compareVersions(v, bound) >= 0;
+var gt = (v, bound) => compareVersions(v, bound) > 0;
+var lt = (v, bound) => compareVersions(v, bound) < 0;
+var lte = (v, bound) => compareVersions(v, bound) <= 0;
+var eq = (v, bound) => compareVersions(v, bound) === 0;
+function caretUpper(version) {
+  const { epoch, upstream } = parseVersion(version);
+  const comps = numericComponents(upstream);
+  const major = comps[0] ?? 0;
+  const prefix = epoch > 0 ? `${epoch}:` : "";
+  return `${prefix}${major + 1}`;
+}
+function tildeUpper(version) {
+  const { epoch, upstream } = parseVersion(version);
+  const comps = numericComponents(upstream);
+  const prefix = epoch > 0 ? `${epoch}:` : "";
+  if (comps.length >= 2)
+    return `${prefix}${comps[0]}.${comps[1] + 1}`;
+  return `${prefix}${(comps[0] ?? 0) + 1}`;
+}
+function parseComparator(token) {
+  const t = token.trim();
+  if (t === "" || t === "*" || t === "x" || t === "latest" || t === "any") {
+    return () => true;
+  }
+  let m;
+  if (m = /^\^\s*(.+)$/.exec(t)) {
+    const base = m[1].trim();
+    const upper = caretUpper(base);
+    return (v) => gte(v, base) && lt(v, upper);
+  }
+  if (m = /^~\s*(.+)$/.exec(t)) {
+    const base = m[1].trim();
+    const upper = tildeUpper(base);
+    return (v) => gte(v, base) && lt(v, upper);
+  }
+  if (m = /^>=\s*(.+)$/.exec(t))
+    return (v) => gte(v, m[1].trim());
+  if (m = /^<=\s*(.+)$/.exec(t))
+    return (v) => lte(v, m[1].trim());
+  if (m = /^>\s*(.+)$/.exec(t))
+    return (v) => gt(v, m[1].trim());
+  if (m = /^<\s*(.+)$/.exec(t))
+    return (v) => lt(v, m[1].trim());
+  if (m = /^!=\s*(.+)$/.exec(t))
+    return (v) => !eq(v, m[1].trim());
+  if (m = /^=\s*(.+)$/.exec(t))
+    return (v) => eq(v, m[1].trim());
+  return (v) => eq(v, t);
+}
+function parseConstraint(raw) {
+  const tokens = raw.trim().split(/\s+/).filter(Boolean);
+  const preds = tokens.length === 0 ? [() => true] : tokens.map(parseComparator);
+  return {
+    raw: raw.trim() || "*",
+    test: (version) => preds.every((p) => p(version))
+  };
+}
+function bestMatch(constraint, candidates) {
+  const c = parseConstraint(constraint);
+  return maxVersion(candidates.filter((v) => c.test(v)));
+}
+
+// src/sys.ts
+import { accessSync, constants } from "node:fs";
+import { access, readFile, writeFile } from "node:fs/promises";
+import { execFile } from "node:child_process";
+import { join } from "node:path";
+async function exists(path) {
+  try {
+    await access(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function readText(path) {
+  return readFile(path, "utf8");
+}
+async function readJson(path) {
+  return JSON.parse(await readText(path));
+}
+async function readBytes(path) {
+  return readFile(path);
+}
+async function writeText(path, data) {
+  await writeFile(path, data);
+}
+function run(cmd, opts = {}) {
+  const [bin, ...args] = cmd;
+  return new Promise((resolve) => {
+    execFile(bin, args, {
+      env: opts.env,
+      timeout: opts.timeoutMs,
+      encoding: "utf8",
+      maxBuffer: 64 * 1024 * 1024
+    }, (err, stdout, stderr) => {
+      let code = 0;
+      if (err)
+        code = typeof err.code === "number" ? err.code : 1;
+      resolve({ code, stdout: stdout ?? "", stderr: stderr ?? "" });
+    });
+  });
+}
+function whichSync(cmd) {
+  const paths = (process.env.PATH ?? "").split(":");
+  for (const dir of paths) {
+    if (!dir)
+      continue;
+    const full = join(dir, cmd);
+    try {
+      accessSync(full, constants.X_OK);
+      return full;
+    } catch {}
+  }
+  return null;
+}
+
+// src/backends/mock.ts
+var DEFAULT_SYSTEM = {
+  nginx: { version: "1.24.0-2", auto: false },
+  git: { version: "1:2.39.2-1.1", auto: false },
+  htop: { version: "3.2.1-1", auto: false },
+  curl: { version: "7.88.1-10", auto: false },
+  vim: { version: "2:9.0.1378-2", auto: false },
+  jq: { version: "1.6-2.1", auto: false },
+  "build-essential": { version: "12.9", auto: false },
+  libc6: { version: "2.36-9+deb12u4", auto: true },
+  libssl3: { version: "3.0.11-1~deb12u2", auto: true },
+  zlib1g: { version: "1:1.2.13.dfsg-1", auto: true },
+  "libpcre2-8-0": { version: "10.42-1", auto: true },
+  "perl-base": { version: "5.36.0-7+deb12u1", auto: true },
+  "libstdc++6": { version: "12.2.0-14", auto: true },
+  "libgcc-s1": { version: "12.2.0-14", auto: true },
+  "ca-certificates": { version: "20230311", auto: true },
+  libcurl4: { version: "7.88.1-10", auto: true }
+};
+var DEFAULT_REPO = {
+  nginx: ["1.18.0-6.1", "1.22.1-9", "1.24.0-1", "1.24.0-2", "1.26.0-1"],
+  git: ["1:2.30.2-1", "1:2.39.2-1.1", "1:2.43.0-1"],
+  htop: ["3.0.5-7", "3.2.1-1", "3.3.0-1"],
+  curl: ["7.74.0-1.3", "7.88.1-10", "8.5.0-2"],
+  vim: ["2:8.2.3995-1", "2:9.0.1378-2", "2:9.1.0016-1"],
+  ripgrep: ["13.0.0-4", "14.1.0-1"],
+  jq: ["1.6-2.1", "1.7.1-3"],
+  postgresql: ["13+225", "15+248", "16+257"],
+  redis: ["5:6.0.16-1", "5:7.0.15-1"],
+  "build-essential": ["12.9", "12.10"]
+};
+var STATE_FILE = ".debrief-mock-state.json";
+function normalizeInstalled(raw) {
+  const out = {};
+  const src = raw ?? {};
+  for (const [name, val] of Object.entries(src)) {
+    if (typeof val === "string")
+      out[name] = { version: val, auto: false };
+    else if (val && typeof val === "object" && "version" in val) {
+      const v = val;
+      out[name] = { version: v.version, auto: v.auto ?? false };
+    }
+  }
+  return out;
+}
+var cloneInstalled = (src) => Object.fromEntries(Object.entries(src).map(([k, v]) => [k, { ...v }]));
+
+class MockBackend {
+  name = "mock";
+  repo;
+  statePath;
+  initialInstalled;
+  ownedPaths;
+  state = { installed: {} };
+  loadPromise = null;
+  constructor(opts = {}) {
+    this.repo = opts.repo ?? DEFAULT_REPO;
+    this.statePath = opts.statePath ?? (opts.cwd ? join2(opts.cwd, STATE_FILE) : null);
+    this.initialInstalled = opts.initialInstalled ?? {};
+    this.ownedPaths = new Set(opts.ownedPaths ?? []);
+  }
+  async owns(path) {
+    return this.ownedPaths.has(path);
+  }
+  load() {
+    if (!this.loadPromise)
+      this.loadPromise = this.doLoad();
+    return this.loadPromise;
+  }
+  async doLoad() {
+    if (this.statePath && await exists(this.statePath)) {
+      try {
+        const raw = await readJson(this.statePath);
+        this.state = { installed: normalizeInstalled(raw.installed) };
+        return;
+      } catch {}
+    }
+    this.state = { installed: cloneInstalled(this.initialInstalled) };
+  }
+  async persist() {
+    if (!this.statePath)
+      return;
+    await writeText(this.statePath, JSON.stringify(this.state, null, 2) + `
+`);
+  }
+  async installed(pkg) {
+    await this.load();
+    return this.state.installed[pkg]?.version ?? null;
+  }
+  async listInstalled() {
+    await this.load();
+    return Object.entries(this.state.installed).map(([name, { version, auto }]) => ({ name, version, arch: "amd64", auto })).sort((a, b) => a.name.localeCompare(b.name));
+  }
+  async candidates(pkg) {
+    return this.repo[pkg] ? [...this.repo[pkg]] : [];
+  }
+  async install(pkg, version) {
+    await this.load();
+    const avail = this.repo[pkg];
+    if (!avail || avail.length === 0) {
+      throw new Error(`package "${pkg}" has no installation candidate (unknown to mock repo)`);
+    }
+    let target = version ?? maxVersion(avail);
+    if (version && !avail.includes(version)) {
+      throw new Error(`version "${version}" of "${pkg}" is not available (have: ${avail.join(", ")})`);
+    }
+    this.state.installed[pkg] = { version: target, auto: false };
+    await this.persist();
+    return target;
+  }
+  async remove(pkg) {
+    await this.load();
+    delete this.state.installed[pkg];
+    await this.persist();
+  }
+  async refresh() {}
+}
+
+// src/backends/apt.ts
+function usrmergeVariants(path) {
+  const merged = /^\/(bin|sbin|lib|lib32|lib64|libx32)\//;
+  if (path.startsWith("/usr/")) {
+    const stripped = path.slice(4);
+    if (merged.test(stripped))
+      return [path, stripped];
+  } else if (merged.test(path)) {
+    return [path, "/usr" + path];
+  }
+  return [path];
+}
+function privileged(cmd) {
+  const isRoot = typeof process.getuid === "function" && process.getuid() === 0;
+  if (isRoot)
+    return cmd;
+  if (Bun.which("sudo"))
+    return ["sudo", ...cmd];
+  return cmd;
+}
+var APT_ENV = { ...process.env, DEBIAN_FRONTEND: "noninteractive" };
+var runWithEnv = (cmd) => run(cmd, { env: APT_ENV });
+
+class AptBackend {
+  name = "apt";
+  async installed(pkg) {
+    const res = await run([
+      "dpkg-query",
+      "-W",
+      "-f=${db:Status-Status} ${Version}",
+      pkg
+    ]);
+    if (res.code !== 0)
+      return null;
+    const [status, version] = res.stdout.trim().split(" ");
+    if (status !== "installed" || !version)
+      return null;
+    return version;
+  }
+  async listInstalled() {
+    const dq = await run([
+      "dpkg-query",
+      "-W",
+      "-f=${db:Status-Status}\t${Package}\t${Version}\t${Architecture}\n"
+    ]);
+    if (dq.code !== 0) {
+      throw new Error(`dpkg-query failed:
+${dq.stderr.trim() || dq.stdout.trim()}`);
+    }
+    const manual = new Set;
+    const mk = await run(["apt-mark", "showmanual"]);
+    if (mk.code === 0) {
+      for (const line of mk.stdout.split(`
+`)) {
+        const name = line.trim();
+        if (name)
+          manual.add(name);
+      }
+    }
+    const out = [];
+    for (const line of dq.stdout.split(`
+`)) {
+      if (!line)
+        continue;
+      const [status, name, version, arch] = line.split("\t");
+      if (status !== "installed" || !name || !version)
+        continue;
+      const isManual = manual.has(name) || (arch ? manual.has(`${name}:${arch}`) : false);
+      out.push({ name, version, arch: arch || undefined, auto: !isManual });
+    }
+    out.sort((a, b) => a.name.localeCompare(b.name));
+    return out;
+  }
+  async owns(path) {
+    for (const p of usrmergeVariants(path)) {
+      if ((await run(["dpkg", "-S", p])).code === 0)
+        return true;
+    }
+    return false;
+  }
+  async candidates(pkg) {
+    const res = await run(["apt-cache", "madison", pkg]);
+    if (res.code !== 0)
+      return [];
+    const versions = [];
+    for (const line of res.stdout.split(`
+`)) {
+      const cols = line.split("|").map((c) => c.trim());
+      if (cols.length >= 2 && cols[1])
+        versions.push(cols[1]);
+    }
+    return [...new Set(versions)];
+  }
+  async install(pkg, version) {
+    const spec = version ? `${pkg}=${version}` : pkg;
+    const cmd = privileged(["apt-get", "install", "-y", "--allow-downgrades", spec]);
+    const res = await runWithEnv(cmd);
+    if (res.code !== 0) {
+      throw new Error(`apt-get install ${spec} failed:
+${res.stderr.trim() || res.stdout.trim()}`);
+    }
+    const now = await this.installed(pkg);
+    if (!now)
+      throw new Error(`installed ${spec} but dpkg does not report it as installed`);
+    return now;
+  }
+  async remove(pkg) {
+    const cmd = privileged(["apt-get", "remove", "-y", pkg]);
+    const res = await runWithEnv(cmd);
+    if (res.code !== 0) {
+      throw new Error(`apt-get remove ${pkg} failed:
+${res.stderr.trim() || res.stdout.trim()}`);
+    }
+  }
+  async refresh() {
+    const res = await runWithEnv(privileged(["apt-get", "update"]));
+    if (res.code !== 0) {
+      throw new Error(`apt-get update failed:
+${res.stderr.trim() || res.stdout.trim()}`);
+    }
+  }
+}
+
+// src/backend.ts
+function selectBackend(opts) {
+  const chosen = opts.explicit ?? process.env.DEBRIEF_BACKEND ?? opts.fromLock ?? (whichSync("apt-get") ? "apt" : "mock");
+  switch (chosen) {
+    case "apt":
+      return new AptBackend;
+    case "mock":
+      return new MockBackend({ cwd: opts.cwd, initialInstalled: DEFAULT_SYSTEM });
+    default:
+      throw new Error(`unknown backend "${chosen}" (expected "apt" or "mock")`);
+  }
+}
+
+// src/store.ts
+import { join as join3 } from "node:path";
+var MANIFEST_FILE = "debrief.json";
+var LOCK_FILE = "debrief.lock";
+var LOCKFILE_VERSION = 1;
+function manifestPath(dir) {
+  return join3(dir, MANIFEST_FILE);
+}
+function lockPath(dir) {
+  return join3(dir, LOCK_FILE);
+}
+function emptyManifest() {
+  return { packages: {} };
+}
+async function readManifest(dir) {
+  if (!await exists(manifestPath(dir)))
+    return null;
+  const data = await readJson(manifestPath(dir));
+  return {
+    name: data.name,
+    description: data.description,
+    packages: data.packages ?? {}
+  };
+}
+async function requireManifest(dir) {
+  const m = await readManifest(dir);
+  if (!m) {
+    throw new Error(`no ${MANIFEST_FILE} found in ${dir} — run \`debrief init\` first`);
+  }
+  return m;
+}
+async function writeManifest(dir, manifest) {
+  const sorted = {};
+  for (const key of Object.keys(manifest.packages).sort()) {
+    sorted[key] = manifest.packages[key];
+  }
+  const out = {
+    ...manifest.name !== undefined ? { name: manifest.name } : {},
+    ...manifest.description !== undefined ? { description: manifest.description } : {},
+    packages: sorted
+  };
+  await writeText(manifestPath(dir), JSON.stringify(out, null, 2) + `
+`);
+}
+async function readLock(dir) {
+  if (!await exists(lockPath(dir)))
+    return null;
+  return readJson(lockPath(dir));
+}
+async function writeLock(dir, lock) {
+  const sorted = {};
+  for (const key of Object.keys(lock.packages).sort()) {
+    sorted[key] = lock.packages[key];
+  }
+  const out = { ...lock, packages: sorted };
+  if (lock.binaries !== undefined) {
+    const sortedBins = {};
+    for (const key of Object.keys(lock.binaries).sort()) {
+      sortedBins[key] = lock.binaries[key];
+    }
+    out.binaries = sortedBins;
+  } else {
+    delete out.binaries;
+  }
+  await writeText(lockPath(dir), JSON.stringify(out, null, 2) + `
+`);
+}
+
+// src/commands.ts
+import { basename } from "node:path";
+
+// src/resolve.ts
+async function inspect(pkg, constraint, backend, lock) {
+  const [installed, candidates] = await Promise.all([
+    backend.installed(pkg),
+    backend.candidates(pkg)
+  ]);
+  const parsed = parseConstraint(constraint);
+  const target = bestMatch(constraint, candidates) ?? null;
+  const latest = maxVersion(candidates) ?? null;
+  const satisfied = installed !== null && parsed.test(installed);
+  const locked = lock?.packages[pkg]?.version ?? null;
+  const lockedUsable = locked !== null && candidates.includes(locked) && parsed.test(locked);
+  const resolvedTarget = lockedUsable ? locked : target;
+  return { pkg, constraint, installed, locked, target, latest, satisfied, resolvedTarget };
+}
+async function inspectAll(manifest, backend, lock) {
+  const entries = Object.entries(manifest.packages);
+  const rows = await Promise.all(entries.map(([pkg, c]) => inspect(pkg, c, backend, lock)));
+  return rows.sort((a, b) => a.pkg.localeCompare(b.pkg));
+}
+function classify(row) {
+  if (row.installed === null)
+    return row.target ? "missing" : "unavailable";
+  if (row.satisfied)
+    return "satisfied";
+  return "drifted";
+}
+
+// src/collector.ts
+import { readdir, realpath, stat } from "node:fs/promises";
+import { join as join4 } from "node:path";
+import { createHash } from "node:crypto";
+function defaultBinDirs() {
+  const home = process.env.HOME ?? "";
+  return [
+    "/usr/local/bin",
+    "/usr/local/sbin",
+    "/opt/bin",
+    home && `${home}/.local/bin`,
+    home && `${home}/bin`
+  ].filter((d) => Boolean(d));
+}
+var HASH_MAX_BYTES = 256 * 1024 * 1024;
+async function sha256File(path, size) {
+  if (size > HASH_MAX_BYTES)
+    return;
+  try {
+    const bytes = await readBytes(path);
+    return createHash("sha256").update(bytes).digest("hex");
+  } catch {
+    return;
+  }
+}
+async function probeVersion(path) {
+  const res = await run([path, "--version"], { timeoutMs: 3000 });
+  const line = (res.stdout + res.stderr).split(`
+`).find((l) => l.trim())?.trim() ?? "";
+  if (!line)
+    return;
+  const m = /\d+\.\d+(?:\.\d+)?(?:[-+.\w~]*)?/.exec(line);
+  return m?.[0] ?? line.slice(0, 60);
+}
+async function collectBinaries(opts) {
+  const wantHash = opts.hash !== false;
+  const out = {};
+  for (const dir of opts.dirs) {
+    let names;
+    try {
+      names = await readdir(dir);
+    } catch {
+      continue;
+    }
+    for (const name of names) {
+      if (name in out)
+        continue;
+      const full = join4(dir, name);
+      let st;
+      try {
+        st = await stat(full);
+      } catch {
+        continue;
+      }
+      if (!st.isFile())
+        continue;
+      if ((st.mode & 73) === 0)
+        continue;
+      let real = full;
+      try {
+        real = await realpath(full);
+      } catch {}
+      if (await opts.backend.owns(real))
+        continue;
+      const entry = { path: full, size: st.size };
+      if (wantHash)
+        entry.sha256 = await sha256File(real, st.size);
+      if (opts.probeVersions)
+        entry.version = await probeVersion(full);
+      out[name] = entry;
+    }
+  }
+  return out;
+}
+
+// src/table.ts
+var stripAnsi = (s) => s.replace(/\x1b\[[0-9;]*m/g, "");
+function table(headers, rows) {
+  const all = [headers, ...rows];
+  const widths = headers.map((_, col) => Math.max(...all.map((r) => stripAnsi(r[col] ?? "").length)));
+  const fmtRow = (r) => r.map((cell, col) => {
+    const pad = widths[col] - stripAnsi(cell ?? "").length;
+    return (cell ?? "") + " ".repeat(Math.max(0, pad));
+  }).join("  ").trimEnd();
+  return [fmtRow(headers), ...rows.map(fmtRow)].join(`
+`);
+}
+
+// src/log.ts
+var enabled = process.stdout.isTTY && !process.env.NO_COLOR;
+var wrap = (code) => (s) => enabled ? `\x1B[${code}m${s}\x1B[0m` : String(s);
+var c = {
+  bold: wrap(1),
+  dim: wrap(2),
+  red: wrap(31),
+  green: wrap(32),
+  yellow: wrap(33),
+  blue: wrap(34),
+  cyan: wrap(36),
+  gray: wrap(90)
+};
+var sym = {
+  add: c.green("+"),
+  ok: c.dim("="),
+  warn: c.yellow("!"),
+  err: c.red("✗"),
+  arrow: c.gray("→")
+};
+function info(msg) {
+  console.log(msg);
+}
+function warn(msg) {
+  console.warn(`${c.yellow("warning")} ${msg}`);
+}
+function error(msg) {
+  console.error(`${c.red("error")} ${msg}`);
+}
+
+// src/commands.ts
+function parseSpec(spec) {
+  const eq2 = spec.indexOf("=");
+  if (eq2 !== -1) {
+    const pkg = spec.slice(0, eq2);
+    const version = spec.slice(eq2 + 1);
+    return { pkg, constraint: version, exactVersion: version };
+  }
+  const at = spec.indexOf("@");
+  if (at !== -1) {
+    return { pkg: spec.slice(0, at), constraint: spec.slice(at + 1) };
+  }
+  return { pkg: spec, constraint: null };
+}
+function defaultConstraint(version) {
+  const { epoch, upstream } = parseVersion(version);
+  const prefix = epoch > 0 ? `${epoch}:` : "";
+  return `^${prefix}${upstream}`;
+}
+async function loadLockOrNew(ctx) {
+  const existing = await readLock(ctx.cwd);
+  if (existing)
+    return existing;
+  return { lockfileVersion: LOCKFILE_VERSION, backend: ctx.backend.name, packages: {} };
+}
+async function cmdInit(ctx, opts) {
+  const existing = await readManifest(ctx.cwd);
+  if (existing) {
+    warn(`${MANIFEST_FILE} already exists — leaving it untouched`);
+    return 0;
+  }
+  const manifest = emptyManifest();
+  manifest.name = opts.name ?? basename(ctx.cwd);
+  if (ctx.dryRun) {
+    info(`${sym.arrow} would create ${MANIFEST_FILE} (name: ${manifest.name})`);
+    return 0;
+  }
+  await writeManifest(ctx.cwd, manifest);
+  info(`${sym.add} created ${c.bold(MANIFEST_FILE)} (name: ${manifest.name})`);
+  info(`${c.dim("add packages with:")} debrief add <package>`);
+  return 0;
+}
+async function cmdAdd(ctx, specs) {
+  if (specs.length === 0) {
+    error("nothing to add — usage: debrief add <package>[@constraint|=version] ...");
+    return 1;
+  }
+  const manifest = await readManifest(ctx.cwd) ?? emptyManifest();
+  const lock = await loadLockOrNew(ctx);
+  lock.backend = ctx.backend.name;
+  let failures = 0;
+  for (const spec of specs.map(parseSpec)) {
+    const constraint = spec.constraint ?? "*";
+    const row = await inspect(spec.pkg, constraint, ctx.backend, lock);
+    if (row.latest === null && row.installed === null) {
+      error(`${spec.pkg}: no installation candidate (unknown package)`);
+      failures++;
+      continue;
+    }
+    const wanted = spec.exactVersion ?? row.target ?? row.latest;
+    if (spec.constraint && row.target === null && !spec.exactVersion) {
+      error(`${spec.pkg}: no available version satisfies "${constraint}" (latest is ${row.latest})`);
+      failures++;
+      continue;
+    }
+    const alreadyGood = row.installed !== null && row.satisfied && !spec.exactVersion;
+    let installedVersion = row.installed;
+    if (alreadyGood) {
+      info(`${sym.ok} ${spec.pkg} ${row.installed} ${c.dim(`(already satisfies ${constraint})`)}`);
+    } else if (ctx.dryRun) {
+      info(`${sym.arrow} would install ${spec.pkg} ${c.bold(String(wanted))}`);
+      installedVersion = wanted ?? row.installed;
+    } else {
+      try {
+        installedVersion = await ctx.backend.install(spec.pkg, spec.exactVersion ?? wanted ?? undefined);
+        info(`${sym.add} ${spec.pkg} ${c.bold(installedVersion)}`);
+      } catch (e) {
+        error(`${spec.pkg}: ${e.message}`);
+        failures++;
+        continue;
+      }
+    }
+    const finalConstraint = spec.constraint ?? (installedVersion ? defaultConstraint(installedVersion) : "*");
+    manifest.packages[spec.pkg] = finalConstraint;
+    if (installedVersion) {
+      lock.packages[spec.pkg] = { version: installedVersion, constraint: finalConstraint };
+    }
+  }
+  if (!ctx.dryRun) {
+    await writeManifest(ctx.cwd, manifest);
+    await writeLock(ctx.cwd, lock);
+  }
+  return failures > 0 ? 1 : 0;
+}
+async function cmdRemove(ctx, pkgs, opts) {
+  if (pkgs.length === 0) {
+    error("nothing to remove — usage: debrief remove <package> ...");
+    return 1;
+  }
+  const manifest = await requireManifest(ctx.cwd);
+  const lock = await loadLockOrNew(ctx);
+  let failures = 0;
+  for (const pkg of pkgs) {
+    const inManifest = pkg in manifest.packages;
+    const installed = opts.saveOnly ? null : await ctx.backend.installed(pkg);
+    if (!inManifest && !installed) {
+      warn(`${pkg}: not in ${MANIFEST_FILE} and not installed — skipping`);
+      continue;
+    }
+    if (!opts.saveOnly && installed) {
+      if (ctx.dryRun) {
+        info(`${sym.arrow} would uninstall ${pkg} ${c.dim(installed)}`);
+      } else {
+        try {
+          await ctx.backend.remove(pkg);
+          info(`${c.red("-")} ${pkg} ${c.dim(`(was ${installed})`)}`);
+        } catch (e) {
+          error(`${pkg}: ${e.message}`);
+          failures++;
+          continue;
+        }
+      }
+    }
+    delete manifest.packages[pkg];
+    delete lock.packages[pkg];
+    if (opts.saveOnly)
+      info(`${c.red("-")} ${pkg} ${c.dim("(removed from manifest only)")}`);
+  }
+  if (!ctx.dryRun) {
+    await writeManifest(ctx.cwd, manifest);
+    await writeLock(ctx.cwd, lock);
+  }
+  return failures > 0 ? 1 : 0;
+}
+async function cmdInstall(ctx) {
+  const manifest = await requireManifest(ctx.cwd);
+  const lock = await loadLockOrNew(ctx);
+  lock.backend = ctx.backend.name;
+  const rows = await inspectAll(manifest, ctx.backend, lock);
+  if (rows.length === 0) {
+    info(`${c.dim("no packages declared in")} ${MANIFEST_FILE}`);
+    return 0;
+  }
+  let installed = 0;
+  let failures = 0;
+  let drifted = 0;
+  for (const row of rows) {
+    const state = classify(row);
+    switch (state) {
+      case "missing": {
+        const version = row.resolvedTarget;
+        const pinned = row.locked !== null && version === row.locked;
+        const mark = pinned ? c.dim(" ↺") : "";
+        if (ctx.dryRun) {
+          info(`${sym.arrow} would install ${row.pkg} ${c.bold(String(version))}${mark}`);
+          if (version)
+            lock.packages[row.pkg] = { version, constraint: row.constraint };
+          installed++;
+          break;
+        }
+        try {
+          const v = await ctx.backend.install(row.pkg, version ?? undefined);
+          info(`${sym.add} ${row.pkg} ${c.bold(v)}${mark}`);
+          lock.packages[row.pkg] = { version: v, constraint: row.constraint };
+          installed++;
+        } catch (e) {
+          error(`${row.pkg}: ${e.message}`);
+          failures++;
+        }
+        break;
+      }
+      case "satisfied": {
+        info(`${sym.ok} ${row.pkg} ${c.dim(row.installed)}`);
+        lock.packages[row.pkg] = { version: row.installed, constraint: row.constraint };
+        break;
+      }
+      case "drifted": {
+        warn(`${row.pkg} ${row.installed} does not satisfy ${c.bold(row.constraint)} ` + `${c.dim(`(run \`debrief add ${row.pkg}@${row.constraint}\` to change it)`)}`);
+        drifted++;
+        break;
+      }
+      case "unavailable": {
+        error(`${row.pkg}: no candidate satisfies ${c.bold(row.constraint)}`);
+        failures++;
+        break;
+      }
+    }
+  }
+  if (!ctx.dryRun)
+    await writeLock(ctx.cwd, lock);
+  const parts = [];
+  parts.push(`${installed} installed`);
+  if (drifted)
+    parts.push(c.yellow(`${drifted} drifted`));
+  if (failures)
+    parts.push(c.red(`${failures} failed`));
+  info(c.dim(`— ${parts.join(", ")}`));
+  return failures > 0 ? 1 : 0;
+}
+function statusLabel(row) {
+  switch (classify(row)) {
+    case "missing":
+      return c.blue("missing");
+    case "satisfied":
+      return c.green("ok");
+    case "drifted":
+      return c.yellow("drift");
+    case "unavailable":
+      return c.red("no-candidate");
+  }
+}
+async function cmdList(ctx) {
+  const manifest = await requireManifest(ctx.cwd);
+  const lock = await readLock(ctx.cwd);
+  const rows = await inspectAll(manifest, ctx.backend, lock);
+  if (rows.length === 0) {
+    info(`${c.dim("no packages declared. add one with:")} debrief add <package>`);
+    return 0;
+  }
+  const body = rows.map((r) => {
+    const newer = r.latest && r.installed && r.latest !== r.installed ? c.dim(`(latest ${r.latest})`) : "";
+    return [
+      c.bold(r.pkg),
+      r.constraint,
+      r.installed ?? c.dim("—"),
+      statusLabel(r),
+      newer
+    ];
+  });
+  info(table(["PACKAGE", "CONSTRAINT", "INSTALLED", "STATUS", ""], body));
+  info(c.dim(`
+backend: ${ctx.backend.name}  •  ${rows.length} package(s) declared`));
+  return 0;
+}
+var byName = (a, b) => a.name.localeCompare(b.name);
+async function cmdCollect(ctx, opts) {
+  const inventory = await ctx.backend.listInstalled();
+  if (inventory.length === 0) {
+    warn("the backend reports no installed packages — nothing to collect");
+    return 0;
+  }
+  const manual = inventory.filter((p) => !p.auto);
+  const manifest = opts.replace ? emptyManifest() : await readManifest(ctx.cwd) ?? emptyManifest();
+  manifest.name ??= basename(ctx.cwd);
+  let added = 0;
+  for (const p of manual) {
+    if (p.name in manifest.packages && !opts.replace)
+      continue;
+    manifest.packages[p.name] = opts.pin ? p.version : "*";
+    added++;
+  }
+  const lock = { lockfileVersion: LOCKFILE_VERSION, backend: ctx.backend.name, packages: {} };
+  for (const p of inventory) {
+    lock.packages[p.name] = {
+      version: p.version,
+      constraint: manifest.packages[p.name] ?? "*",
+      ...p.arch ? { arch: p.arch } : {},
+      ...p.auto ? { auto: true } : {}
+    };
+  }
+  let bins = {};
+  if (opts.binaries !== false) {
+    bins = await collectBinaries({
+      dirs: opts.dirs ?? defaultBinDirs(),
+      backend: ctx.backend,
+      probeVersions: opts.probeVersions
+    });
+    lock.binaries = bins;
+  }
+  const binCount = Object.keys(bins).length;
+  if (ctx.dryRun) {
+    info(`${sym.arrow} would record ${c.bold(String(manual.length))} manual package(s) in ${MANIFEST_FILE} ` + `(${added} new), ${c.bold(String(inventory.length))} total + ${c.bold(String(binCount))} loose binaries in ${LOCK_FILE}`);
+    return 0;
+  }
+  await writeManifest(ctx.cwd, manifest);
+  await writeLock(ctx.cwd, lock);
+  info(`${sym.add} collected ${c.bold(String(inventory.length))} installed package(s)`);
+  info(`  ${c.dim("→ manifest:")} ${manual.length} manual ${c.dim(`(+${added} new)`)}   ` + `${c.dim("→ lock:")} ${inventory.length} total ${c.dim(`(incl. ${inventory.length - manual.length} deps)`)}`);
+  if (opts.binaries !== false) {
+    info(`  ${c.dim("→ loose binaries (non-dpkg):")} ${binCount}`);
+  }
+  return 0;
+}
+async function cmdStatus(ctx, opts = {}) {
+  const lock = await readLock(ctx.cwd);
+  if (!lock) {
+    error(`no snapshot found — run \`debrief collect\` first`);
+    return 1;
+  }
+  const live = await ctx.backend.listInstalled();
+  const liveNames = new Set(live.map((p) => p.name));
+  const snap = lock.packages;
+  const added = [];
+  const changed = [];
+  for (const p of live) {
+    const s = snap[p.name];
+    if (!s)
+      added.push(p);
+    else if (s.version !== p.version) {
+      changed.push({ name: p.name, from: s.version, to: p.version, auto: p.auto });
+    }
+  }
+  const removed = Object.entries(snap).filter(([name]) => !liveNames.has(name)).map(([name, e]) => ({ name, version: e.version, auto: e.auto ?? false }));
+  const binAdded = [];
+  const binChanged = [];
+  const binRemoved = [];
+  if (lock.binaries) {
+    const liveBins = await collectBinaries({ dirs: opts.dirs ?? defaultBinDirs(), backend: ctx.backend });
+    const snapBins = lock.binaries;
+    for (const [name, e] of Object.entries(liveBins)) {
+      const s = snapBins[name];
+      if (!s)
+        binAdded.push(`${name} ${e.path}`);
+      else if (s.sha256 && e.sha256 && s.sha256 !== e.sha256)
+        binChanged.push(`${name} ${e.path}`);
+    }
+    for (const name of Object.keys(snapBins)) {
+      if (!(name in liveBins))
+        binRemoved.push(`${name} ${snapBins[name].path}`);
+    }
+  }
+  const nothing = added.length + changed.length + removed.length + binAdded.length + binChanged.length + binRemoved.length === 0;
+  if (nothing) {
+    info(c.green("in sync — the live system matches the snapshot"));
+    return 0;
+  }
+  const tag = (auto) => auto ? c.dim(" (dep)") : "";
+  for (const p of added.sort(byName))
+    info(`${c.green("+")} ${p.name} ${p.version}${tag(p.auto)}`);
+  for (const ch of changed.sort(byName)) {
+    info(`${c.yellow("~")} ${ch.name} ${c.dim(ch.from)} ${sym.arrow} ${ch.to}${tag(ch.auto)}`);
+  }
+  for (const p of removed.sort(byName))
+    info(`${c.red("-")} ${p.name} ${c.dim(p.version)}${tag(p.auto)}`);
+  if (binAdded.length + binChanged.length + binRemoved.length > 0) {
+    info(c.dim(`
+non-dpkg binaries (curl|sh / manual / brew / ...):`));
+    for (const b of binAdded.sort())
+      info(`${c.green("+")} ${b}`);
+    for (const b of binChanged.sort())
+      info(`${c.yellow("~")} ${b} ${c.dim("(contents changed)")}`);
+    for (const b of binRemoved.sort())
+      info(`${c.red("-")} ${b}`);
+  }
+  const pkgLine = `${added.length} added  ~${changed.length} changed  -${removed.length} removed`;
+  const binLine = lock.binaries !== undefined ? `   binaries: +${binAdded.length} ~${binChanged.length} -${binRemoved.length}` : "";
+  info(c.dim(`
+packages: +${pkgLine}${binLine}  (run \`debrief collect\` to update the snapshot)`));
+  return 0;
+}
+async function cmdOutdated(ctx) {
+  const manifest = await requireManifest(ctx.cwd);
+  const lock = await readLock(ctx.cwd);
+  const rows = await inspectAll(manifest, ctx.backend, lock);
+  const outdated = rows.filter((r) => r.installed !== null && r.latest !== null && r.installed !== r.latest);
+  if (outdated.length === 0) {
+    info(c.green("everything is up to date"));
+    return 0;
+  }
+  const body = outdated.map((r) => [
+    c.bold(r.pkg),
+    r.installed ?? c.dim("—"),
+    r.target && r.target !== r.installed ? c.green(r.target) : c.dim(r.target ?? "—"),
+    c.cyan(r.latest)
+  ]);
+  info(table(["PACKAGE", "INSTALLED", "WANTED", "LATEST"], body));
+  info(c.dim(`
+WANTED = newest within your constraint • LATEST = newest in the repo
+` + `bump a constraint with: debrief add <pkg>@<constraint>`));
+  return 0;
+}
+
+// src/cli.ts
+var VERSION = "0.1.0";
+var HELP = `${c.bold("debrief")} — a package.json for your Debian packages
+
+${c.bold("USAGE")}
+  debrief <command> [args] [options]
+
+${c.bold("COMMANDS")}
+  ${c.bold("collect")}                  snapshot dpkg packages + loose PATH binaries into the lock
+  ${c.bold("status")}                   diff the live system against the snapshot
+  list                     show declared packages and their status  (alias: ls)
+  outdated                 show packages with newer versions available
+  init                     create an empty debrief.json
+  add <pkg[@ver|=ver]> …   install package(s) and record them in the manifest
+  remove <pkg> …           uninstall package(s) and drop them from the manifest
+  install                  install everything in the manifest that is missing
+  help                     show this help
+
+${c.bold("COLLECT / STATUS OPTIONS")}
+  --pin                    (collect) record exact installed versions, not "*"
+  --replace                (collect) overwrite the manifest instead of merging
+  --no-binaries            skip scanning PATH for loose (non-dpkg) binaries
+  --probe-versions         run \`<bin> --version\` on loose binaries (executes them)
+  --scan-dirs a:b:c        override which dirs to scan for loose binaries
+
+${c.bold("VERSION SPECS")}  (npm-flavored, resolved against real Debian versions)
+  nginx                    latest candidate; manifest gets ^<installed>
+  nginx@^1.24              >= 1.24 and < 2       (caret: allow non-major)
+  nginx@~1.24              >= 1.24 and < 1.25    (tilde: pin the minor)
+  nginx@'>=1.22 <1.26'     an AND-ed range
+  nginx=1.24.0-1           an exact Debian version
+
+${c.bold("OPTIONS")}
+  --backend <mock|apt>     force a backend (default: from lockfile, else auto)
+  -n, --dry-run            show what would happen without changing anything
+  -y, --yes                assume yes (non-interactive)
+  --save-only              (remove) drop from manifest without uninstalling
+  --name <name>            (init) set the project name
+  --cwd <dir>              run as if in <dir>
+  -V, --version            print version
+  -h, --help               show this help
+
+${c.dim("On a machine without apt (e.g. NixOS) the mock backend is used automatically.")}`;
+var VALUE_FLAGS = new Set(["backend", "cwd", "name", "scan-dirs"]);
+var ALIASES = {
+  n: "dry-run",
+  y: "yes",
+  h: "help",
+  V: "version"
+};
+function parse(argv) {
+  const positionals = [];
+  const flags = {};
+  for (let i = 0;i < argv.length; i++) {
+    const tok = argv[i];
+    if (tok.startsWith("--")) {
+      const body = tok.slice(2);
+      const eq2 = body.indexOf("=");
+      if (eq2 !== -1) {
+        flags[body.slice(0, eq2)] = body.slice(eq2 + 1);
+      } else if (VALUE_FLAGS.has(body)) {
+        flags[body] = argv[++i] ?? "";
+      } else {
+        flags[body] = true;
+      }
+    } else if (tok.startsWith("-") && tok.length > 1) {
+      const name = ALIASES[tok.slice(1)] ?? tok.slice(1);
+      if (VALUE_FLAGS.has(name))
+        flags[name] = argv[++i] ?? "";
+      else
+        flags[name] = true;
+    } else {
+      positionals.push(tok);
+    }
+  }
+  const [command = null, ...rest] = positionals;
+  return { command, positionals: rest, flags };
+}
+function scanDirs(flags) {
+  const v = flags["scan-dirs"];
+  return typeof v === "string" ? v.split(":").filter(Boolean) : undefined;
+}
+async function main(argv) {
+  const { command, positionals, flags } = parse(argv);
+  if (flags.version) {
+    console.log(VERSION);
+    return 0;
+  }
+  if (flags.help || command === null || command === "help") {
+    console.log(HELP);
+    return 0;
+  }
+  const cwd = typeof flags.cwd === "string" ? flags.cwd : process.cwd();
+  const dryRun = !!flags["dry-run"];
+  const yes = !!flags.yes;
+  const lock = await readLock(cwd).catch(() => null);
+  const backend = selectBackend({
+    explicit: typeof flags.backend === "string" ? flags.backend : undefined,
+    fromLock: lock?.backend,
+    cwd
+  });
+  const ctx = { cwd, backend, dryRun, yes };
+  try {
+    switch (command) {
+      case "collect":
+      case "import":
+      case "freeze":
+        return await cmdCollect(ctx, {
+          pin: !!flags.pin,
+          replace: !!flags.replace,
+          binaries: !flags["no-binaries"],
+          probeVersions: !!flags["probe-versions"],
+          dirs: scanDirs(flags)
+        });
+      case "status":
+      case "diff":
+        return await cmdStatus(ctx, { dirs: scanDirs(flags) });
+      case "init":
+        return await cmdInit(ctx, { name: typeof flags.name === "string" ? flags.name : undefined });
+      case "add":
+        return await cmdAdd(ctx, positionals);
+      case "remove":
+      case "rm":
+      case "uninstall":
+        return await cmdRemove(ctx, positionals, { saveOnly: !!flags["save-only"] });
+      case "install":
+      case "i":
+        if (positionals.length > 0) {
+          error(`\`install\` takes no package arguments — use \`debrief add ${positionals.join(" ")}\``);
+          return 1;
+        }
+        return await cmdInstall(ctx);
+      case "list":
+      case "ls":
+        return await cmdList(ctx);
+      case "outdated":
+        return await cmdOutdated(ctx);
+      default:
+        error(`unknown command "${command}" — run \`debrief help\``);
+        return 1;
+    }
+  } catch (e) {
+    error(e.message);
+    return 1;
+  }
+}
+
+// bin/debrief.ts
+process.exit(await main(process.argv.slice(2)));