skalpel 2.0.23 → 3.0.0

package/postinstall/lib/paths.js

@@ -0,0 +1,186 @@
+// Per-OS path resolution for the postinstall wizard.
+//
+// SPEC.md §9.1 — config directory paths, service-registration
+// destinations, expected rc-files per shell. Centralising the
+// table here keeps every step honest about what it touches.
+
+'use strict';
+
+const path = require('path');
+const os = require('os');
+
+// B41: validate that paths supplied via env or os.homedir() are
+// absolute and free of `..` components — defense-in-depth against
+// a malicious / corrupted env that would have us write into a
+// parent directory or into the project tree.
+function validatePath(p, name) {
+  if (p === undefined || p === null || p === '') {
+    return; // optional values handled by caller
+  }
+  if (!path.isAbsolute(p)) {
+    throw new Error(`${name} must be an absolute path; got ${JSON.stringify(p)}`);
+  }
+  const parts = String(p).split(path.sep);
+  if (parts.includes('..')) {
+    throw new Error(`${name} must not contain ".." components; got ${JSON.stringify(p)}`);
+  }
+}
+
+function home() {
+  const h = os.homedir();
+  validatePath(h, 'os.homedir()');
+  return h;
+}
+
+function configDir() {
+  const h = home();
+  switch (process.platform) {
+    case 'darwin':
+      return path.join(h, 'Library', 'Application Support', 'skalpel');
+    case 'win32': {
+      const appdata = process.env.APPDATA;
+      validatePath(appdata, 'APPDATA');
+      return path.join(appdata || path.join(h, 'AppData', 'Roaming'), 'skalpel');
+    }
+    default: {
+      const xdg = process.env.XDG_CONFIG_HOME;
+      validatePath(xdg, 'XDG_CONFIG_HOME');
+      return path.join(xdg || path.join(h, '.config'), 'skalpel');
+    }
+  }
+}
+
+function authFile() {
+  return path.join(configDir(), 'auth.json');
+}
+
+function configToml() {
+  return path.join(configDir(), 'config.toml');
+}
+
+function lockFile() {
+  return path.join(configDir(), 'skalpeld.lock');
+}
+
+function logsDir() {
+  return path.join(configDir(), 'logs');
+}
+
+// Per-OS service registration destination.
+function servicePath() {
+  const h = home();
+  switch (process.platform) {
+    case 'darwin':
+      return path.join(h, 'Library', 'LaunchAgents', 'ai.skalpel.daemon.plist');
+    case 'win32':
+      return path.join(configDir(), 'Task.xml');
+    default: {
+      const xdg = process.env.XDG_CONFIG_HOME;
+      validatePath(xdg, 'XDG_CONFIG_HOME');
+      return path.join(xdg || path.join(h, '.config'), 'systemd', 'user', 'skalpel-daemon.service');
+    }
+  }
+}
+
+// B32: detect when postinstall is running inside `npx skalpel`.
+function isNpxInvocation() {
+  if (process.env.npm_lifecycle_event && /\/_npx\//.test(process.execPath)) {
+    return true;
+  }
+  if (process.env.npm_execpath && /\/_npx\//.test(process.env.npm_execpath)) {
+    return true;
+  }
+  if (/\/_npx\//.test(process.argv[1] || '')) {
+    return true;
+  }
+  return false;
+}
+
+// Where the platform binary lives once optionalDependencies installed it.
+function binPath(name) {
+  if (isNpxInvocation()) {
+    throw new Error(
+      'Skalpel does not support `npx skalpel` — please run `npm i -g @skalpelai/skalpel` instead.'
+    );
+  }
+  const h = home();
+  const npmPrefix = process.env.npm_config_prefix;
+  validatePath(npmPrefix, 'npm_config_prefix');
+  if (process.platform === 'win32') {
+    if (npmPrefix) {
+      return path.join(npmPrefix, `${name}.exe`);
+    }
+    return path.join(h, 'AppData', 'Local', 'skalpel', `${name}.exe`);
+  }
+  if (npmPrefix) {
+    return path.join(npmPrefix, 'bin', name);
+  }
+  if (process.platform === 'darwin') {
+    return path.join('/usr/local/bin', name);
+  }
+  return path.join(h, '.local', 'bin', name);
+}
+
+// rc-files per shell. The wizard touches zero or more of these,
+// depending on what exists on disk.
+//
+// B22: ~/.profile is sourced by sh / bash-login / ksh / dash and is
+// the only POSIX-portable per-user rc file — it is always emitted.
+// B23: ~/.bash_profile is bash-login-only; it is conventionally
+// edited on macOS (where Terminal.app launches login shells by
+// default) but rarely on Linux. We emit it only on darwin.
+function rcFiles() {
+  const h = home();
+  if (process.platform === 'win32') {
+    const docs = process.env.USERPROFILE
+      ? path.join(process.env.USERPROFILE, 'Documents')
+      : path.join(h, 'Documents');
+    return [
+      { shell: 'powershell', path: path.join(docs, 'PowerShell', 'Microsoft.PowerShell_profile.ps1') },
+      { shell: 'powershell-legacy', path: path.join(docs, 'WindowsPowerShell', 'Microsoft.PowerShell_profile.ps1') },
+    ];
+  }
+  // audit-2026-05-09 §6 LOW: fish config respects $XDG_CONFIG_HOME per
+  // the fish spec; previously we hardcoded $HOME/.config/fish.
+  const xdgConfig = process.env.XDG_CONFIG_HOME;
+  validatePath(xdgConfig, 'XDG_CONFIG_HOME');
+  const fishConfigDir = xdgConfig
+    ? path.join(xdgConfig, 'fish')
+    : path.join(h, '.config', 'fish');
+  const list = [
+    { shell: 'zsh', path: path.join(h, '.zshrc') },
+    { shell: 'bash', path: path.join(h, '.bashrc') },
+    { shell: 'profile', path: path.join(h, '.profile') }, // B22
+    { shell: 'fish', path: path.join(fishConfigDir, 'config.fish') },
+  ];
+  if (process.platform === 'darwin') {
+    list.push({ shell: 'bash-profile', path: path.join(h, '.bash_profile') }); // B23
+  }
+  return list;
+}
+
+function templateValues() {
+  const h = home();
+  return {
+    USER: os.userInfo().username,
+    HOME: h,
+    BIN: path.dirname(binPath('skalpeld')),
+    CONFIG_DIR: configDir(),
+    SKALPELD_BIN: binPath('skalpeld'),
+    SKALPEL_BIN: binPath('skalpel'),
+  };
+}
+
+module.exports = {
+  configDir,
+  authFile,
+  configToml,
+  lockFile,
+  logsDir,
+  servicePath,
+  binPath,
+  rcFiles,
+  templateValues,
+  isNpxInvocation,
+  validatePath,
+};

package/postinstall/lib/rc-edit.js

@@ -0,0 +1,167 @@
+// rc-file injection: the fenced "managed block" that holds the env
+// vars Skalpel needs the user's coding agents to see.
+//
+// SPEC.md §9.5 — the block is identified by its begin/end fences. The
+// injector finds the existing block (if any) and replaces it; otherwise
+// appends. The injector NEVER edits outside its own fences; user-added
+// export lines are preserved.
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+// Decision D260 / B30 — vendor-prefixed fence format:
+//   # >>> @skalpelai/skalpel begin (managed)
+//   # <<< @skalpelai/skalpel end (managed)
+const FENCE_BEGIN_POSIX = '# >>> @skalpelai/skalpel begin (managed)';
+const FENCE_END_POSIX = '# <<< @skalpelai/skalpel end (managed)';
+const FENCE_BEGIN_PS = '# >>> @skalpelai/skalpel begin (managed) >>>';
+const FENCE_END_PS = '# <<< @skalpelai/skalpel end (managed) <<<';
+
+function envBlockValues(port) {
+  const p = String(port || 7878);
+  const root = `http://127.0.0.1:${p}`;
+  return {
+    ANTHROPIC_API_URL: root,
+    ANTHROPIC_BASE_URL: root,
+    OPENAI_BASE_URL: `${root}/v1`,
+    OPENAI_API_BASE: `${root}/v1`,
+    SKALPEL_PROXY_URL: root,
+  };
+}
+
+function fenceFor(shell) {
+  if (shell === 'powershell' || shell === 'powershell-legacy') {
+    return { begin: FENCE_BEGIN_PS, end: FENCE_END_PS };
+  }
+  return { begin: FENCE_BEGIN_POSIX, end: FENCE_END_POSIX };
+}
+
+// B19: shell-escape value v inside a double-quoted POSIX export.
+function shellEscapePosixDQ(v) {
+  return String(v).replace(/[\\"$`]/g, '\\$&');
+}
+
+// PowerShell single-quoted strings are fully literal except `'` doubled.
+function shellEscapePsSQ(v) {
+  return String(v).replace(/'/g, "''");
+}
+
+function bodyFor(shell, env) {
+  const note =
+    'This block is managed by skalpel install. Do not edit by hand;\n' +
+    're-run `skalpel install` or `npx skalpel` to update.';
+  switch (shell) {
+    case 'fish':
+      return [
+        '# Managed by skalpel install; safe to delete.',
+        ...Object.entries(env).map(
+          ([k, v]) => `set -gx ${k} "${shellEscapePosixDQ(v)}"`
+        ),
+      ].join('\n');
+    case 'powershell':
+    case 'powershell-legacy':
+      return [
+        ...note.split('\n').map((l) => `# ${l}`),
+        ...Object.entries(env).map(
+          ([k, v]) => `$env:${k} = '${shellEscapePsSQ(v)}'`
+        ),
+      ].join('\n');
+    default:
+      return [
+        ...note.split('\n').map((l) => `# ${l}`),
+        ...Object.entries(env).map(
+          ([k, v]) => `export ${k}="${shellEscapePosixDQ(v)}"`
+        ),
+      ].join('\n');
+  }
+}
+
+function buildBlock(shell, env) {
+  const { begin, end } = fenceFor(shell);
+  return `${begin}\n${bodyFor(shell, env)}\n${end}`;
+}
+
+function escapeRegex(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+// B17: tighten trailing-newline match. (\n|$) instead of \n? makes
+// the intent explicit: match exactly one newline OR end-of-input.
+function blockRegex(shell) {
+  const { begin, end } = fenceFor(shell);
+  return new RegExp(
+    `(^|\\n)${escapeRegex(begin)}[\\s\\S]*?${escapeRegex(end)}(\\n|$)`,
+    'g'
+  );
+}
+
+function rewrite(existing, shell, env) {
+  const block = buildBlock(shell, env);
+  const re = blockRegex(shell);
+  if (re.test(existing)) {
+    re.lastIndex = 0;
+    return existing.replace(re, (m, pre) => `${pre}${block}\n`);
+  }
+  const sep = existing.length === 0 || existing.endsWith('\n') ? '' : '\n';
+  return `${existing}${sep}${existing.length ? '\n' : ''}${block}\n`;
+}
+
+function applyBlock({ shell, file, env, dryRun }) {
+  const current = fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : '';
+  const next = rewrite(current, shell, env);
+  if (dryRun) {
+    return { changed: current !== next, dryRun: true };
+  }
+  if (current === next) {
+    return { changed: false };
+  }
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, next);
+  return { changed: true };
+}
+
+function removeBlock({ shell, file, dryRun }) {
+  if (!fs.existsSync(file)) {
+    return { changed: false, missing: true };
+  }
+  const current = fs.readFileSync(file, 'utf8');
+  const re = blockRegex(shell);
+  const next = current.replace(re, '');
+  if (current === next) {
+    return { changed: false };
+  }
+  if (dryRun) {
+    return { changed: true, dryRun: true };
+  }
+  fs.writeFileSync(file, next);
+  return { changed: true };
+}
+
+// xmlEscape: B47 — used by Task.xml renderer.
+function xmlEscape(v) {
+  return String(v)
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&apos;');
+}
+
+module.exports = {
+  envBlockValues,
+  buildBlock,
+  rewrite,
+  applyBlock,
+  removeBlock,
+  fenceFor,
+  bodyFor,
+  shellEscapePosixDQ,
+  shellEscapePsSQ,
+  xmlEscape,
+  FENCE_BEGIN_POSIX,
+  FENCE_END_POSIX,
+  FENCE_BEGIN_PS,
+  FENCE_END_PS,
+};

package/postinstall/lib/rc-edit.test.js

@@ -0,0 +1,196 @@
+#!/usr/bin/env node
+// rc-edit tests.
+//
+// Mandatory test (per w3c-packaging promise): TestRcEdit_Idempotent_Fenced
+// — runs applyBlock twice against a temp rc-file, asserts only one
+// managed block exists, content matches expected.
+//
+// Additional tests cover all four shells (zsh, bash, fish, PowerShell),
+// removeBlock idempotence, user-line preservation, and re-run with a
+// different port (block replaced, single instance).
+//
+// Stdlib only: assert + fs + os + path. No mocha / no jest.
+
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const assert = require('assert');
+
+const rc = require('./rc-edit');
+
+let pass = 0;
+let fail = 0;
+
+function tmpFile(prefix) {
+  const name = `${prefix}-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2)}`;
+  return path.join(os.tmpdir(), name);
+}
+
+function test(name, fn) {
+  try {
+    fn();
+    process.stdout.write(`  PASS ${name}\n`);
+    pass += 1;
+  } catch (err) {
+    process.stderr.write(`  FAIL ${name}\n    ${err.message}\n`);
+    fail += 1;
+  }
+}
+
+function countMatches(s, needle) {
+  let c = 0;
+  let i = 0;
+  while ((i = s.indexOf(needle, i)) !== -1) {
+    c += 1;
+    i += needle.length;
+  }
+  return c;
+}
+
+function run() {
+  process.stdout.write('rc-edit tests:\n');
+
+  test('TestRcEdit_Idempotent_Fenced', () => {
+    const file = tmpFile('rcedit-bash');
+    fs.writeFileSync(file, '# user content\nexport FOO=bar\n');
+    try {
+      const env = rc.envBlockValues(7878);
+      const r1 = rc.applyBlock({ shell: 'bash', file, env });
+      assert.strictEqual(r1.changed, true, 'first run should change file');
+      const r2 = rc.applyBlock({ shell: 'bash', file, env });
+      assert.strictEqual(r2.changed, false, 'second run with same env is a no-op');
+      const after = fs.readFileSync(file, 'utf8');
+      assert.strictEqual(
+        countMatches(after, rc.FENCE_BEGIN_POSIX),
+        1,
+        'managed block begin marker must appear exactly once'
+      );
+      assert.strictEqual(
+        countMatches(after, rc.FENCE_END_POSIX),
+        1,
+        'managed block end marker must appear exactly once'
+      );
+      assert.ok(after.includes('export ANTHROPIC_API_URL="http://127.0.0.1:7878"'));
+      assert.ok(after.includes('export OPENAI_BASE_URL="http://127.0.0.1:7878/v1"'));
+      assert.ok(after.includes('# user content'), 'user content preserved');
+      assert.ok(after.includes('export FOO=bar'), 'user export preserved');
+    } finally {
+      fs.unlinkSync(file);
+    }
+  });
+
+  test('TestRcEdit_Idempotent_Fenced_zsh', () => {
+    const file = tmpFile('rcedit-zsh');
+    fs.writeFileSync(file, '');
+    try {
+      const env = rc.envBlockValues(7878);
+      rc.applyBlock({ shell: 'zsh', file, env });
+      rc.applyBlock({ shell: 'zsh', file, env });
+      rc.applyBlock({ shell: 'zsh', file, env });
+      const after = fs.readFileSync(file, 'utf8');
+      assert.strictEqual(countMatches(after, rc.FENCE_BEGIN_POSIX), 1);
+      assert.strictEqual(countMatches(after, rc.FENCE_END_POSIX), 1);
+    } finally {
+      fs.unlinkSync(file);
+    }
+  });
+
+  test('TestRcEdit_Idempotent_Fenced_fish', () => {
+    const file = tmpFile('rcedit-fish');
+    fs.writeFileSync(file, '# fish prelude\n');
+    try {
+      const env = rc.envBlockValues(7878);
+      rc.applyBlock({ shell: 'fish', file, env });
+      rc.applyBlock({ shell: 'fish', file, env });
+      const after = fs.readFileSync(file, 'utf8');
+      assert.strictEqual(countMatches(after, rc.FENCE_BEGIN_POSIX), 1);
+      assert.ok(after.includes('set -gx ANTHROPIC_API_URL'));
+      assert.ok(after.includes('# fish prelude'), 'fish prelude preserved');
+    } finally {
+      fs.unlinkSync(file);
+    }
+  });
+
+  test('TestRcEdit_Idempotent_Fenced_powershell', () => {
+    const file = tmpFile('rcedit-ps');
+    fs.writeFileSync(file, '');
+    try {
+      const env = rc.envBlockValues(7878);
+      rc.applyBlock({ shell: 'powershell', file, env });
+      rc.applyBlock({ shell: 'powershell', file, env });
+      const after = fs.readFileSync(file, 'utf8');
+      assert.strictEqual(countMatches(after, rc.FENCE_BEGIN_PS), 1);
+      assert.strictEqual(countMatches(after, rc.FENCE_END_PS), 1);
+      assert.ok(after.includes("$env:ANTHROPIC_API_URL = 'http://127.0.0.1:7878'"));
+    } finally {
+      fs.unlinkSync(file);
+    }
+  });
+
+  test('TestRcEdit_Replaces_When_Port_Changes', () => {
+    const file = tmpFile('rcedit-port');
+    fs.writeFileSync(file, '');
+    try {
+      rc.applyBlock({ shell: 'bash', file, env: rc.envBlockValues(7878) });
+      const r2 = rc.applyBlock({ shell: 'bash', file, env: rc.envBlockValues(9999) });
+      assert.strictEqual(r2.changed, true, 'changing port should rewrite');
+      const after = fs.readFileSync(file, 'utf8');
+      assert.strictEqual(countMatches(after, rc.FENCE_BEGIN_POSIX), 1);
+      assert.ok(after.includes('http://127.0.0.1:9999'));
+      assert.ok(!after.includes('http://127.0.0.1:7878'));
+    } finally {
+      fs.unlinkSync(file);
+    }
+  });
+
+  test('TestRcEdit_RemoveBlock_Leaves_User_Content', () => {
+    const file = tmpFile('rcedit-remove');
+    fs.writeFileSync(file, 'export USER_VAR=1\n');
+    try {
+      rc.applyBlock({ shell: 'bash', file, env: rc.envBlockValues(7878) });
+      const r = rc.removeBlock({ shell: 'bash', file });
+      assert.strictEqual(r.changed, true);
+      const after = fs.readFileSync(file, 'utf8');
+      assert.ok(!after.includes(rc.FENCE_BEGIN_POSIX));
+      assert.ok(after.includes('export USER_VAR=1'), 'user var preserved');
+    } finally {
+      fs.unlinkSync(file);
+    }
+  });
+
+  test('TestRcEdit_Pure_Rewrite_Function', () => {
+    // The pure rewrite() function must satisfy:
+    //   rewrite(rewrite(x, e), e) == rewrite(x, e)
+    const env = rc.envBlockValues(7878);
+    const samples = [
+      '',
+      '# header\n',
+      '# header\n# trailing',
+      'export A=1\nexport B=2\n',
+    ];
+    for (const s of samples) {
+      const once = rc.rewrite(s, 'bash', env);
+      const twice = rc.rewrite(once, 'bash', env);
+      assert.strictEqual(once, twice, `idempotent for sample: ${JSON.stringify(s)}`);
+    }
+  });
+
+  test('TestRcEdit_Body_Has_All_Five_Vars', () => {
+    const env = rc.envBlockValues(7878);
+    const block = rc.buildBlock('bash', env);
+    for (const k of Object.keys(env)) {
+      assert.ok(block.includes(k), `missing var ${k}`);
+    }
+  });
+
+  process.stdout.write(`\n  pass=${pass} fail=${fail}\n`);
+  return fail === 0 ? 0 : 1;
+}
+
+if (require.main === module) {
+  process.exit(run());
+}
+
+module.exports = { run };