skalpel 2.0.23 → 3.0.0

package/postinstall/index.js

@@ -0,0 +1,294 @@
+#!/usr/bin/env node
+// Postinstall wizard.
+//
+// 5-step flow per SPEC.md §9.6:
+//   1. detect-prior — probe configDir for prior install
+//   2. sign-in     — `skalpel login` (or hint to run it)
+//   3. service-register — render + load launchd / systemd / Task
+//   4. env-inject  — managed-block edit of shell rc files
+//   5. launch      — print next-step hint
+//
+// Dry-run: SKALPEL_INSTALL_DRY_RUN=1 (env) or --dry-run (argv) makes
+// the wizard log every action it would take and write nothing.
+//
+// Idempotence: the wizard is safe to re-run. Each step replaces or
+// skips rather than duplicating.
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const colors = require('../npm-bin/colors');
+const log = require('./lib/log');
+const paths = require('./lib/paths');
+const detectPrior = require('./lib/detect-prior');
+const signIn = require('./lib/sign-in');
+const serviceRegister = require('./lib/service-register');
+const envInject = require('./lib/env-inject');
+const launch = require('./lib/launch');
+
+function printStyledSuccess() {
+  if (!process.stdout.isTTY) return;
+  const colored = !process.env.NO_COLOR;
+  const platformLabel = `${process.platform}-${process.arch}`;
+  const check = colored ? colors.theme.green('✓') : '✓';
+  const text = colored
+    ? colors.theme.text(` skalpel installed for ${platformLabel}`)
+    : ` skalpel installed for ${platformLabel}`;
+  process.stdout.write(`${check}${text}\n`);
+}
+
+function parseArgs(argv) {
+  const out = {
+    dryRun: false,
+    skipBundle: false,
+    verbose: false,
+    uninstall: false,
+    cleanupData: false,
+  };
+  for (const a of argv.slice(2)) {
+    switch (a) {
+      case '--dry-run':
+        out.dryRun = true;
+        break;
+      case '--verbose':
+        out.verbose = true;
+        break;
+      case '--skip-bundle':
+        out.skipBundle = true;
+        break;
+      case '--uninstall':
+        out.uninstall = true;
+        break;
+      case '--cleanup-data':
+        // B29: opt-in flag to delete auth.json / config.toml /
+        // skalpeld.lock / logs/ during --uninstall.
+        out.cleanupData = true;
+        break;
+      case '--help':
+      case '-h':
+        out.help = true;
+        break;
+      default:
+        // Unknown args are ignored for npm-postinstall robustness;
+        // the user's npm CLI may pass extra flags.
+        break;
+    }
+  }
+  if (process.env.SKALPEL_INSTALL_DRY_RUN === '1') {
+    out.dryRun = true;
+  }
+  if (process.env.SKALPEL_UNINSTALL_CLEAN === '1') {
+    out.cleanupData = true;
+  }
+  return out;
+}
+
+function helpText() {
+  return [
+    'skalpel postinstall wizard',
+    '',
+    'usage: node postinstall/index.js [--dry-run] [--verbose] [--uninstall] [--cleanup-data]',
+    '',
+    'Run automatically by npm install. The wizard performs:',
+    '  1. detect-prior          probe configDir for an existing install',
+    '  2. sign-in               start `skalpel login` (or hint at it)',
+    '  3. service-register      register the per-OS daemon entry',
+    '  4. env-inject            update shell rc managed-block',
+    '  5. launch                print the run-skalpel hint',
+    '',
+    '--uninstall reverses steps 3 and 4: unregisters the daemon and',
+    '   removes the managed block from each rc file.',
+    '--cleanup-data (with --uninstall) also deletes auth.json,',
+    '   config.toml, skalpeld.lock, and logs/. Equivalent env var:',
+    '   SKALPEL_UNINSTALL_CLEAN=1.',
+    '',
+    'Dry-run mode (SKALPEL_INSTALL_DRY_RUN=1 or --dry-run) makes every',
+    'step log what it would do and write nothing.',
+  ].join('\n');
+}
+
+// B29: best-effort delete of user data on --uninstall --cleanup-data.
+// Skipped silently when files / dirs are absent.
+function cleanupUserData({ dryRun }) {
+  const removed = [];
+  const targets = [
+    paths.authFile(),
+    paths.configToml(),
+    paths.lockFile(),
+  ];
+  for (const t of targets) {
+    if (dryRun) {
+      log.dryRun(`uninstall-cleanup: would rm ${t}`);
+      removed.push(t);
+      continue;
+    }
+    try {
+      if (fs.existsSync(t)) {
+        fs.rmSync(t, { force: true });
+        log.info(`uninstall-cleanup: removed ${t}`);
+        removed.push(t);
+      }
+    } catch (err) {
+      log.warn(`uninstall-cleanup: rm ${t} failed: ${err.message}`);
+    }
+  }
+  const lDir = paths.logsDir();
+  if (dryRun) {
+    log.dryRun(`uninstall-cleanup: would rm -r ${lDir}`);
+    removed.push(lDir);
+  } else {
+    try {
+      if (fs.existsSync(lDir)) {
+        fs.rmSync(lDir, { recursive: true, force: true });
+        log.info(`uninstall-cleanup: removed ${lDir}`);
+        removed.push(lDir);
+      }
+    } catch (err) {
+      log.warn(`uninstall-cleanup: rm -r ${lDir} failed: ${err.message}`);
+    }
+  }
+  // Try to remove the (now-empty) configDir; ignore ENOTEMPTY which
+  // means the user has other state under it we don't own.
+  const cfg = paths.configDir();
+  if (!dryRun) {
+    try {
+      fs.rmdirSync(cfg);
+      log.info(`uninstall-cleanup: removed empty ${cfg}`);
+      removed.push(cfg);
+    } catch (_) {
+      // non-empty or missing — leave alone.
+    }
+  } else {
+    log.dryRun(`uninstall-cleanup: would rmdir (if empty) ${cfg}`);
+  }
+  return { removed };
+}
+
+function main(argv) {
+  const opts = parseArgs(argv);
+  if (opts.help) {
+    process.stdout.write(`${helpText()}\n`);
+    return 0;
+  }
+
+  // B32: refuse to run under `npx skalpel`.
+  if (paths.isNpxInvocation()) {
+    process.stderr.write(
+      'Skalpel does not support `npx skalpel` — please run `npm i -g @skalpelai/skalpel` instead.\n'
+    );
+    return 1;
+  }
+
+  const total = 5;
+  const mode = opts.dryRun ? 'dry-run' : 'live';
+  const action = opts.uninstall ? 'uninstall' : 'install';
+  log.info(`postinstall wizard starting (${mode} ${action}) on ${process.platform}`);
+
+  // B28: classify failures. Critical = re-throw and exit 0 (we do
+  // not want npm install to abort, but the operator should know).
+  // Warning = collect and log at end.
+  const allWarnings = [];
+
+  if (opts.uninstall) {
+    try {
+      const stepCount = opts.cleanupData ? 3 : 2;
+      log.step(1, stepCount, 'env-uninject', 'remove managed-block from rc files');
+      envInject.uninject({ dryRun: opts.dryRun });
+
+      log.step(2, stepCount, 'service-unregister', `OS=${process.platform}`);
+      const ur = serviceRegister.unregister({ dryRun: opts.dryRun }) || {};
+      if (Array.isArray(ur.errors) && ur.errors.length) {
+        allWarnings.push(...ur.errors);
+      }
+
+      // B29: optional user-data cleanup.
+      if (opts.cleanupData) {
+        log.step(3, stepCount, 'cleanup-user-data', 'delete auth.json/config.toml/lock/logs');
+        cleanupUserData({ dryRun: opts.dryRun });
+      } else {
+        log.info(
+          'uninstall: user data preserved (auth.json/config.toml/lock/logs). ' +
+          'Pass --cleanup-data or set SKALPEL_UNINSTALL_CLEAN=1 to remove.'
+        );
+      }
+    } catch (err) {
+      log.error(`uninstall failed: ${err.message}`);
+      if (opts.verbose) {
+        process.stderr.write(`${err.stack}\n`);
+      }
+      return 0;
+    }
+    if (allWarnings.length) {
+      log.warn(`postinstall wizard finished (${mode} uninstall) with ${allWarnings.length} warning(s)`);
+    } else {
+      log.info(`postinstall wizard finished (${mode} uninstall)`);
+    }
+    return 0;
+  }
+
+  let prior = false;
+  let critical = null;
+  try {
+    log.step(1, total, 'detect-prior', 'probing configDir');
+    const r = detectPrior.run({ dryRun: opts.dryRun });
+    prior = r.prior;
+
+    log.step(2, total, 'sign-in', prior ? 'skipping (prior auth)' : 'browser flow');
+    // sign-in is non-critical: a missing dispatcher / login failure
+    // is recoverable — user can run `skalpel login` later.
+    try {
+      const sr = signIn.run({ dryRun: opts.dryRun, prior });
+      if (sr && sr.error) {
+        allWarnings.push(`sign-in: ${sr.error}`);
+      }
+    } catch (err) {
+      log.warn(`sign-in: ${err.message}; continuing`);
+      allWarnings.push(`sign-in: ${err.message}`);
+    }
+
+    log.step(3, total, 'service-register', `OS=${process.platform}`);
+    // service-register is critical: a stale service unit is a real
+    // problem at boot. Errors propagate to the catch block below.
+    const sr = serviceRegister.run({ dryRun: opts.dryRun }) || {};
+    if (Array.isArray(sr.warnings) && sr.warnings.length) {
+      allWarnings.push(...sr.warnings);
+    }
+
+    log.step(4, total, 'env-inject', 'managed-block edit per shell');
+    // env-inject is critical: missing managed block means agents
+    // never see the proxy URL. Errors propagate.
+    envInject.run({ dryRun: opts.dryRun });
+
+    log.step(5, total, 'launch', 'next-step hint');
+    launch.run({ dryRun: opts.dryRun });
+  } catch (err) {
+    critical = err;
+    log.error(`postinstall failed: ${err.message}`);
+    if (opts.verbose) {
+      process.stderr.write(`${err.stack}\n`);
+    }
+  }
+
+  if (allWarnings.length) {
+    log.warn(`postinstall wizard finished (${mode}) with ${allWarnings.length} warning(s):`);
+    for (const w of allWarnings) {
+      log.warn(`  - ${w}`);
+    }
+  } else if (!critical) {
+    log.info(`postinstall wizard finished (${mode})`);
+    if (!opts.dryRun) {
+      printStyledSuccess();
+    }
+  }
+  // Always exit 0 so npm install does not abort. The user can
+  // re-run `skalpel install` if a critical step failed.
+  return 0;
+}
+
+if (require.main === module) {
+  process.exit(main(process.argv));
+}
+
+module.exports = { main, parseArgs, cleanupUserData };

package/postinstall/launchd/com.skalpel.skalpeld.plist.tmpl

@@ -0,0 +1,41 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
+                       "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>                      <string>ai.skalpel.daemon</string>
+
+  <key>ProgramArguments</key>
+  <array>
+    <string>{{BIN}}/skalpeld</string>
+    <string>--service-mode</string>
+  </array>
+
+  <key>RunAtLoad</key>                  <true/>
+  <key>KeepAlive</key>
+  <dict>
+    <key>SuccessfulExit</key>           <false/>
+    <key>Crashed</key>                  <true/>
+  </dict>
+
+  <key>ThrottleInterval</key>           <integer>10</integer>
+
+  <key>StandardOutPath</key>            <string>{{CONFIG_DIR}}/logs/skalpeld.log</string>
+  <key>StandardErrorPath</key>          <string>{{CONFIG_DIR}}/logs/skalpeld.log</string>
+
+  <key>WorkingDirectory</key>           <string>{{HOME}}</string>
+
+  <key>EnvironmentVariables</key>
+  <dict>
+    <key>SKALPEL_CONFIG_DIR</key>       <string>{{CONFIG_DIR}}</string>
+    <key>HOME</key>                     <string>{{HOME}}</string>
+    <key>USER</key>                     <string>{{USER}}</string>
+  </dict>
+
+  <key>ProcessType</key>                <string>Interactive</string>
+  <!-- audit-2026-05-09 §6 LOW: dropped LimitLoadToSessionType=Aqua so
+       the daemon also loads under headless macOS sessions (CI runners
+       driving via SSH land in LoginWindow / Background sessions; the
+       Aqua restriction blocked load there). -->
+</dict>
+</plist>

package/postinstall/lib/detect-prior.js

@@ -0,0 +1,51 @@
+// Step 1: detect prior install.
+//
+// SPEC.md §9.6 — read <configDir>/auth.json existence, config.toml
+// existence, and presence of LaunchAgent / systemd unit / Task. If any
+// of these are present, the wizard short-circuits and the TUI is
+// launched directly.
+//
+// We also check the lock file (which the daemon writes) so an active
+// install with running daemon is detected even if config.toml hasn't
+// been written yet.
+
+'use strict';
+
+const fs = require('fs');
+const log = require('./log');
+const paths = require('./paths');
+
+function fileExists(p) {
+  try {
+    fs.accessSync(p, fs.constants.F_OK);
+    return true;
+  } catch (_e) {
+    return false;
+  }
+}
+
+function run({ dryRun }) {
+  const probes = [
+    { label: 'auth.json', path: paths.authFile() },
+    { label: 'config.toml', path: paths.configToml() },
+    { label: 'lock file', path: paths.lockFile() },
+    { label: 'service registration', path: paths.servicePath() },
+  ];
+
+  const findings = probes.map((p) => ({ ...p, exists: fileExists(p.path) }));
+  const prior = findings.some((f) => f.exists);
+
+  if (dryRun) {
+    log.dryRun(`step 1 detect-prior: would probe ${findings.length} paths`);
+  }
+  for (const f of findings) {
+    log.info(
+      `  ${f.exists ? 'present' : 'absent '} — ${f.label}: ${f.path}`
+    );
+  }
+
+  log.info(prior ? 'detected prior install' : 'no prior install detected');
+  return { prior, findings };
+}
+
+module.exports = { run };

package/postinstall/lib/env-inject.js

@@ -0,0 +1,121 @@
+// Step 4: environment-variable injection into shell rc files.
+//
+// Delegates to lib/rc-edit.js for the idempotent fenced-block edit.
+// The set of files we touch is paths.rcFiles(); each file that
+// already exists gets its managed block written (or replaced).
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const log = require('./log');
+const paths = require('./paths');
+const rcEdit = require('./rc-edit');
+
+// B21: when none of the per-shell candidates exist, fall back to
+// creating a fresh ~/.profile (POSIX) or ~/.bash_profile (the
+// macOS bash-login default). Without this, a fresh-install user
+// who has no rc files yet ends up with no managed block at all
+// and the daemon's env vars never reach their shells.
+function fallbackRc() {
+  if (process.platform === 'win32') {
+    // PowerShell candidates are listed even when absent; rc-edit
+    // creates the path on first apply. No fallback needed.
+    return null;
+  }
+  // We pick ~/.profile because it is sourced by sh / bash-login /
+  // ksh / dash and is the only POSIX-portable file. macOS users
+  // who exclusively use Terminal.app's bash-login may also want
+  // ~/.bash_profile, but that is already in paths.rcFiles() on
+  // darwin.
+  return {
+    shell: 'profile',
+    path: path.join(require('os').homedir(), '.profile'),
+  };
+}
+
+function run({ dryRun, port }) {
+  const targetPort = port || 7878;
+  const env = rcEdit.envBlockValues(targetPort);
+  const rcs = paths.rcFiles();
+  const touched = [];
+  const present = [];
+
+  for (const rc of rcs) {
+    const exists = fs.existsSync(rc.path);
+    if (!exists) {
+      log.info(`env-inject: ${rc.shell} rc absent (${rc.path}) — skip`);
+      continue;
+    }
+    present.push(rc);
+    if (dryRun) {
+      log.dryRun(`step 4 env-inject: would update managed block in ${rc.path} (${rc.shell})`);
+      touched.push(rc.path);
+      continue;
+    }
+    rcEdit.applyBlock({ shell: rc.shell, file: rc.path, env });
+    log.info(`env-inject: updated managed block in ${rc.path} (${rc.shell})`);
+    touched.push(rc.path);
+  }
+
+  // B21: no candidates existed — bootstrap a fresh ~/.profile so
+  // the env vars are reachable from a freshly-provisioned account.
+  if (present.length === 0) {
+    const fallback = fallbackRc();
+    if (fallback) {
+      if (dryRun) {
+        log.dryRun(
+          `step 4 env-inject: no rc files present — would create ${fallback.path} ` +
+          `with the managed block (${fallback.shell})`
+        );
+        touched.push(fallback.path);
+      } else {
+        log.info(
+          `env-inject: no rc files present — creating ${fallback.path} ` +
+          `with the managed block (${fallback.shell})`
+        );
+        // Write a small header so the user knows we created the file.
+        const header = '# Created by skalpel install — feel free to add your own lines below.\n';
+        fs.mkdirSync(path.dirname(fallback.path), { recursive: true });
+        fs.writeFileSync(fallback.path, header);
+        rcEdit.applyBlock({ shell: fallback.shell, file: fallback.path, env });
+        touched.push(fallback.path);
+      }
+    }
+  }
+
+  if (touched.length === 0) {
+    log.info('env-inject: no shell rc files present — user can re-run after creating one');
+  } else {
+    log.info(
+      'env-inject: restart your shell or `source` the rc file to pick up the variables'
+    );
+  }
+  return { touched };
+}
+
+function uninject({ dryRun }) {
+  const rcs = paths.rcFiles();
+  const removed = [];
+  for (const rc of rcs) {
+    const exists = fs.existsSync(rc.path);
+    if (!exists) {
+      log.info(`uninstall: ${rc.shell} rc absent (${rc.path}) — skip`);
+      continue;
+    }
+    if (dryRun) {
+      log.dryRun(`uninstall: would remove managed block from ${rc.path} (${rc.shell})`);
+      removed.push(rc.path);
+      continue;
+    }
+    const r = rcEdit.removeBlock({ shell: rc.shell, file: rc.path });
+    if (r.changed) {
+      log.info(`uninstall: removed managed block from ${rc.path} (${rc.shell})`);
+      removed.push(rc.path);
+    }
+  }
+  return { removed };
+}
+
+module.exports = { run, uninject, fallbackRc };

package/postinstall/lib/launch.js

@@ -0,0 +1,28 @@
+// Step 5: launch.
+//
+// SPEC.md §9.6 step 6 — launch the TUI; if no agents are configured
+// yet, the empty-state from spec §3.2 is shown.
+//
+// During npm postinstall we don't actually launch the TUI (it would
+// wedge the install behind a long-running interactive process).
+// Instead we print the one-line "next-step" hint. Real TUI launch
+// happens when the user types `skalpel` themselves.
+//
+// In dry-run we log the same hint marked [dry-run].
+
+'use strict';
+
+const path = require('path');
+const log = require('./log');
+
+function run({ dryRun }) {
+  const hint = 'all set — run `skalpel` to open the TUI';
+  if (dryRun) {
+    log.dryRun(`step 5 launch: would print: ${hint}`);
+    return { launched: false, dryRun: true };
+  }
+  log.info(hint);
+  return { launched: false, deferred: true };
+}
+
+module.exports = { run };

package/postinstall/lib/log.js

@@ -0,0 +1,31 @@
+// Tiny logger for the postinstall wizard.
+//
+// No third-party deps: stdlib only. The wizard runs as part of
+// `npm install` so its output is interleaved with npm's own; we
+// prefix every line with `skalpel install:` to make it easy to grep.
+
+'use strict';
+
+const PREFIX = 'skalpel install:';
+
+function info(msg) {
+  process.stdout.write(`${PREFIX} ${msg}\n`);
+}
+
+function warn(msg) {
+  process.stderr.write(`${PREFIX} WARN ${msg}\n`);
+}
+
+function error(msg) {
+  process.stderr.write(`${PREFIX} ERROR ${msg}\n`);
+}
+
+function dryRun(msg) {
+  process.stdout.write(`${PREFIX} [dry-run] ${msg}\n`);
+}
+
+function step(n, total, name, msg) {
+  process.stdout.write(`${PREFIX} (${n}/${total}) ${name}: ${msg}\n`);
+}
+
+module.exports = { info, warn, error, dryRun, step };