phewsh 0.15.47 → 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')}`);

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/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.47",
+  "version": "0.15.48",
   "description": "Turn intent into action. Structure your thinking, execute your next step.",
   "bin": {
     "phewsh": "bin/phewsh.js"