phewsh 0.15.46 → 0.15.48

package/bin/phewsh.js

@@ -88,6 +88,7 @@ const COMMANDS = {
   ambient: () => require('../commands/ambient')(),
   shim:    () => require('../commands/shim')(),
   status:  () => require('../commands/status')(),
+  pack:    () => require('../commands/pack')(),
   hook:    () => require('../commands/hook')(),
   welcome: () => require('../commands/welcome')(),
   intro:   () => require('../commands/welcome')(),
@@ -128,6 +129,7 @@ function showHelp() {
   console.log(`    ${cyan('mcp')}        ${g('Connect AI agents via MCP protocol')}`);
   console.log(`    ${cyan('ambient')}    ${g('Continuity without launching phewsh — enhance your other tools')}`);
   console.log(`    ${cyan('shim')}       ${g('Guaranteed launch banner — phewsh prints status before each tool')}`);
+  console.log(`    ${cyan('pack')}       ${g('Opt-in workflow packs (Karpathy guidelines, GSD…) — attributed, reversible')}`);
   console.log(`    ${cyan('receipts')}   ${g('Proof trail — what agents actually did, with evidence')}`);
   console.log(`    ${cyan('outcomes')}   ${g('Decision record — what was kept, reverted, or failed')}`);
   console.log(`    ${cyan('bypass')}     ${g('Went around phewsh? Record why — 10 seconds, no guilt')}`);
@@ -228,11 +230,12 @@ if (!command) {
   exitAfterUpdate(0);
 } else if (COMMANDS[command]) {
   COMMANDS[command]();
-} else if (require('../lib/harnesses').HARNESSES[command]) {
-  // `phewsh <harness>` — a doorway shortcut. Launch the session and have it
-  // auto-run /work for that harness (preflight → brief → native handoff →
-  // postflight). This is what the phewsh.com doorways copy as a single command.
-  process.env.PHEWSH_AUTOWORK = command;
+} else if (require('../lib/harnesses').resolveHarness(command)) {
+  // `phewsh <harness>` — a doorway shortcut. Accepts the id OR the tool's real
+  // binary (so `phewsh claude` works, since that's the Claude Code binary).
+  // Launch the session and auto-run /work for that harness (preflight → brief →
+  // native handoff → postflight). This is what the phewsh.com doorways copy.
+  process.env.PHEWSH_AUTOWORK = require('../lib/harnesses').resolveHarness(command);
   ambientSelfHeal().finally(() => maybeFirstRunIntro().then(() => COMMANDS.session()));
 } else {
   console.error(`\n  Unknown command: ${command}\n  Run 'phewsh help' for available commands.\n`);

package/commands/pack.js

@@ -0,0 +1,97 @@
+// phewsh pack — opt-in gateway to AI-workflow enhancements (Karpathy-style
+// guidelines, GSD, …). Attributed, previewed, confirmed, reversible. phewsh's
+// core stays continuity; packs are an optional layer you choose.
+//
+//   phewsh pack                  list packs (available + installed)
+//   phewsh pack install <name>   show source/license + diff, confirm, install
+//   phewsh pack remove <name>    remove a vendored pack's marked block
+
+const readline = require('readline');
+const packs = require('../lib/packs');
+
+const b = (s) => `\x1b[1m${s}\x1b[0m`;
+const teal = (s) => `\x1b[38;5;79m${s}\x1b[0m`;
+const sage = (s) => `\x1b[38;5;151m${s}\x1b[0m`;
+const slate = (s) => `\x1b[38;5;247m${s}\x1b[0m`;
+const cream = (s) => `\x1b[38;5;230m${s}\x1b[0m`;
+const peach = (s) => `\x1b[38;5;216m${s}\x1b[0m`;
+const green = (s) => `\x1b[32m${s}\x1b[0m`;
+const yellow = (s) => `\x1b[33m${s}\x1b[0m`;
+
+async function confirm(q) {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise(res => rl.question(q, a => { rl.close(); res(/^y(es)?$/i.test(a.trim())); }));
+}
+
+function list() {
+  console.log('');
+  console.log(`  ${b(cream('phewsh packs'))} ${sage('— optional, attributed, reversible enhancements')}`);
+  console.log(`  ${slate('phewsh\'s core is continuity; these are extras you opt into.')}`);
+  console.log('');
+  for (const [name, p] of Object.entries(packs.PACKS)) {
+    const on = packs.isInstalled(name);
+    const tag = p.kind === 'linked' ? slate('[linked]') : (on ? green('[installed]') : slate('[available]'));
+    console.log(`  ${cream(name.padEnd(16))} ${tag}`);
+    console.log(`    ${slate(p.desc)}`);
+    console.log(`    ${slate('source: ' + p.source)}`);
+  }
+  console.log('');
+  console.log(`  ${sage('Install:')} ${cream('phewsh pack install <name>')}   ${sage('Remove:')} ${cream('phewsh pack remove <name>')}`);
+  console.log('');
+}
+
+async function install(name) {
+  const p = packs.PACKS[name];
+  if (!p) { console.log(`\n  ${yellow('Unknown pack:')} ${name}. See ${cream('phewsh pack')}.\n`); return; }
+
+  console.log('');
+  console.log(`  ${b(cream(p.title))} ${slate('(pack: ' + name + ')')}`);
+  console.log(`  ${slate(p.desc)}`);
+  console.log(`  ${peach('source:')}  ${slate(p.source)}`);
+  console.log(`  ${peach('license:')} ${slate(p.license)}`);
+  console.log('');
+
+  if (p.kind === 'linked') {
+    console.log(`  ${sage('This is a separate tool — phewsh doesn\'t vendor it. Install it with:')}`);
+    console.log(`    ${cream(p.install)}`);
+    console.log('');
+    return;
+  }
+
+  const preview = packs.previewInstall(name);
+  console.log(`  ${sage('Writes a clearly-marked, removable block into:')} ${cream(preview.files.join(', '))}`);
+  console.log(`  ${slate('Preview:')}`);
+  preview.block.split('\n').slice(0, 8).forEach(l => console.log(`    ${slate('│ ' + l)}`));
+  console.log(`    ${slate('│ … (' + preview.block.split('\n').length + ' lines total)')}`);
+  console.log('');
+
+  const ok = await confirm(`  ${b('Install this pack here?')} ${slate('[y/N] ')}`);
+  if (!ok) { console.log(`  ${sage('Nothing changed.')}\n`); return; }
+
+  const { written } = packs.install(name);
+  console.log('');
+  console.log(`  ${green('●')} ${b('Installed.')} ${slate('→ ' + written.join(', '))}`);
+  console.log(`  ${sage('Remove anytime:')} ${cream('phewsh pack remove ' + name)}`);
+  console.log('');
+}
+
+function remove(name) {
+  const p = packs.PACKS[name];
+  if (!p) { console.log(`\n  ${yellow('Unknown pack:')} ${name}.\n`); return; }
+  if (p.kind === 'linked') { console.log(`\n  ${sage(p.title + ' is a separate tool — uninstall it the way you installed it.')}\n`); return; }
+  const { removed } = packs.remove(name);
+  console.log('');
+  if (removed.length) console.log(`  ${green('●')} ${b('Removed.')} ${slate('← ' + removed.join(', '))}`);
+  else console.log(`  ${sage('Not installed here — nothing to remove.')}`);
+  console.log('');
+}
+
+async function main() {
+  const sub = process.argv[3];
+  const name = process.argv[4];
+  if (sub === 'install' && name) return install(name);
+  if (sub === 'remove' && name) return remove(name);
+  return list();
+}
+
+module.exports = main;

package/lib/harnesses.js

@@ -218,9 +218,32 @@ function runViaHarness(id, systemPrompt, userPrompt, opts = {}) {
   });
 }
 
+// Resolve a user-typed token to a harness id. Accepts the canonical id, the
+// tool's actual binary (so `phewsh claude` → claude-code, since `claude` is the
+// Claude Code binary; `phewsh cursor-agent` → cursor), or a friendly alias.
+// Returns the harness id, or null if nothing matches.
+const HARNESS_ALIASES = {
+  claude: 'claude-code',
+  cc: 'claude-code',
+  'cursor-agent': 'cursor',
+  'kiro-cli': 'kiro',
+  copilot: 'copilot',
+};
+function resolveHarness(token) {
+  if (!token) return null;
+  const t = String(token).toLowerCase();
+  if (HARNESSES[t]) return t;
+  if (HARNESS_ALIASES[t]) return HARNESS_ALIASES[t];
+  for (const [id, h] of Object.entries(HARNESSES)) {
+    if (h.bin && h.bin.toLowerCase() === t) return id;
+  }
+  return null;
+}
+
 module.exports = {
   HARNESSES,
   INSTALL,
+  resolveHarness,
   isInstalled,
   detectInstalled,
   interactiveLaunchArgs,

package/lib/packs.js

@@ -0,0 +1,127 @@
+// phewsh packs — an opt-in gateway to proven AI-workflow enhancements.
+//
+// phewsh's core is project truth + continuity + record. It is NOT a grab-bag of
+// every viral CLAUDE.md. But good ideas exist out there, and phewsh is a natural
+// front door to them — IF they stay optional, attributed, and reversible. So:
+//   • Nothing is vendored or injected by default (never in ambient/first-run).
+//   • `phewsh pack install <name>` shows the source + license + a diff preview
+//     and asks before writing.
+//   • `phewsh pack remove <name>` cleanly reverses it (marked block only).
+//
+// Two kinds of pack:
+//   • vendored — phewsh writes a clearly-marked block into the project's agent
+//     files (e.g. Karpathy's coding guidelines into CLAUDE.md/AGENTS.md).
+//   • linked   — phewsh doesn't vendor it; it points you at the upstream
+//     installer (e.g. GSD is its own tool — we hand you its command).
+
+const fs = require('fs');
+const path = require('path');
+
+const KARPATHY_GUIDELINES = `## Coding guidelines
+**Tradeoff:** these bias toward caution over speed. For trivial tasks, use judgment.
+
+### 1. Think before coding
+State assumptions explicitly; if uncertain, ask. If multiple interpretations exist, present them — don't pick silently. If a simpler approach exists, say so. If something's unclear, stop and name it.
+
+### 2. Simplicity first
+Minimum code that solves the problem, nothing speculative. No features beyond what was asked, no abstractions for single-use code, no error handling for impossible cases. If 200 lines could be 50, rewrite. Ask: "would a senior engineer call this overcomplicated?"
+
+### 3. Surgical changes
+Touch only what you must. Don't "improve" adjacent code, don't refactor what isn't broken, match existing style. Remove only the orphans YOUR change created; mention pre-existing dead code, don't delete it. Every changed line should trace to the request.
+
+### 4. Goal-driven execution
+Turn tasks into verifiable goals ("add validation" → "write tests for invalid inputs, then make them pass"). For multi-step work, state a brief plan with a verify step each. Strong success criteria let you loop independently.
+
+**Working if:** fewer unnecessary diffs, fewer rewrites from overcomplication, and clarifying questions come before mistakes, not after.`;
+
+const PACKS = {
+  'karpathy-style': {
+    kind: 'vendored',
+    title: 'Karpathy-style coding guidelines',
+    desc: 'Behavioral guidelines that reduce common LLM coding mistakes (think-before-coding, simplicity, surgical changes, goal-driven loops).',
+    source: "Andrej Karpathy's CLAUDE.md · github.com/multica-ai/andrej-karpathy-skills",
+    license: 'review the source repo for license before redistributing',
+    targets: ['CLAUDE.md', 'AGENTS.md'],
+    content: KARPATHY_GUIDELINES,
+  },
+  gsd: {
+    kind: 'linked',
+    title: 'GSD — Get Shit Done',
+    desc: 'A Claude-centric workflow augmentation (hooks, commands, planning). Its own tool — phewsh just points you at it; it is not vendored.',
+    source: 'github.com/gsd-build/get-shit-done',
+    license: 'see the GSD repo',
+    install: 'npx @gsd-build/get-shit-done init   # follow the GSD repo for current instructions',
+  },
+};
+
+function markers(name) {
+  return { start: `<!-- phewsh-pack:${name} START -->`, end: `<!-- phewsh-pack:${name} END -->` };
+}
+
+function blockFor(name, pack) {
+  const m = markers(name);
+  const header = `# ${pack.title} (phewsh pack: ${name})\n`
+    + `> Source: ${pack.source}\n`
+    + `> Opt-in via \`phewsh pack install ${name}\` · remove: \`phewsh pack remove ${name}\`\n\n`;
+  return `${m.start}\n${header}${pack.content}\n${m.end}`;
+}
+
+function isInstalled(name, cwd = process.cwd()) {
+  const pack = PACKS[name];
+  if (!pack || pack.kind !== 'vendored') return false;
+  return pack.targets.some(f => {
+    try { return fs.readFileSync(path.join(cwd, f), 'utf-8').includes(markers(name).start); }
+    catch { return false; }
+  });
+}
+
+// Returns the files it WOULD write to + the block, without writing — for preview.
+function previewInstall(name, cwd = process.cwd()) {
+  const pack = PACKS[name];
+  if (!pack || pack.kind !== 'vendored') return null;
+  return { files: pack.targets, block: blockFor(name, pack) };
+}
+
+function install(name, cwd = process.cwd()) {
+  const pack = PACKS[name];
+  if (!pack || pack.kind !== 'vendored') return { written: [] };
+  const block = blockFor(name, pack);
+  const m = markers(name);
+  const written = [];
+  for (const f of pack.targets) {
+    const fp = path.join(cwd, f);
+    let existing = '';
+    try { existing = fs.readFileSync(fp, 'utf-8'); } catch { /* new file */ }
+    if (existing.includes(m.start)) {
+      // refresh in place
+      const re = new RegExp(escapeRe(m.start) + '[\\s\\S]*?' + escapeRe(m.end));
+      fs.writeFileSync(fp, existing.replace(re, block));
+    } else {
+      fs.writeFileSync(fp, (existing ? existing.replace(/\s*$/, '') + '\n\n' : '') + block + '\n');
+    }
+    written.push(f);
+  }
+  return { written };
+}
+
+function remove(name, cwd = process.cwd()) {
+  const pack = PACKS[name];
+  if (!pack || pack.kind !== 'vendored') return { removed: [] };
+  const m = markers(name);
+  const removed = [];
+  for (const f of pack.targets) {
+    const fp = path.join(cwd, f);
+    try {
+      const existing = fs.readFileSync(fp, 'utf-8');
+      if (!existing.includes(m.start)) continue;
+      const re = new RegExp('\\n*' + escapeRe(m.start) + '[\\s\\S]*?' + escapeRe(m.end) + '\\n*', 'g');
+      fs.writeFileSync(fp, existing.replace(re, '\n').replace(/\n{3,}/g, '\n\n').replace(/^\n+/, ''));
+      removed.push(f);
+    } catch { /* not there */ }
+  }
+  return { removed };
+}
+
+function escapeRe(s) { return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'); }
+
+module.exports = { PACKS, install, remove, isInstalled, previewInstall, blockFor };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "phewsh",
-  "version": "0.15.46",
+  "version": "0.15.48",
   "description": "Turn intent into action. Structure your thinking, execute your next step.",
   "bin": {
     "phewsh": "bin/phewsh.js"