phewsh 0.15.20 → 0.15.22

package/bin/phewsh.js

@@ -74,6 +74,8 @@ const COMMANDS = {
   seq:     () => require('../commands/sequence')(),
   ambient: () => require('../commands/ambient')(),
   hook:    () => require('../commands/hook')(),
+  welcome: () => require('../commands/welcome')(),
+  intro:   () => require('../commands/welcome')(),
   help:    showHelp,
   version: showVersion,
 };
@@ -158,10 +160,23 @@ function exitAfterUpdate(code = 0) {
   setTimeout(() => process.exit(code), 2000);
 }
 
+async function maybeFirstRunIntro() {
+  // First ever run → play the intro once, then never again. Marker, not config,
+  // so it's independent of login state. Never blocks the session on failure.
+  try {
+    const fs = require('fs'), path = require('path'), os = require('os');
+    const marker = path.join(os.homedir(), '.phewsh', '.welcomed');
+    if (fs.existsSync(marker)) return;
+    if (process.stdout.isTTY) await require('../lib/intro').playIntro();
+    fs.mkdirSync(path.dirname(marker), { recursive: true });
+    fs.writeFileSync(marker, new Date().toISOString());
+  } catch { /* the intro is a nicety — never let it block the session */ }
+}
+
 if (!command) {
-  // Bare `phewsh` — always drop into persistent session
+  // Bare `phewsh` — first run gets the intro, then drop into the session.
   // Session handles missing API key gracefully with /login and /key commands
-  COMMANDS.session();
+  maybeFirstRunIntro().then(() => COMMANDS.session());
 } else if (command === 'help' || command === '--help' || command === '-h') {
   showHelp();
   exitAfterUpdate(0);

package/commands/welcome.js

@@ -0,0 +1,4 @@
+// phewsh welcome — the first-impression intro. Replayable any time.
+const { playIntro } = require('../lib/intro');
+
+module.exports = () => playIntro();

package/lib/intro.js

@@ -0,0 +1,83 @@
+// The first impression. A staggered, terminal-safe reveal: the mark, the
+// promise, then the magic moment — phewsh scans the machine and your installed
+// AI tools light up one by one. That last beat IS the value prop: "it already
+// works with everything you have."
+//
+// Safe by construction: line-by-line printing only, no cursor-up rewrites
+// (Apple Terminal hazard). Non-TTY / piped → everything prints instantly.
+// Timing + harness list + output are injectable so the sequence is testable.
+
+const ui = require('./ui');
+
+// The exhale mark (😮‍💨) — rasterized from assets/phew.svg to a 30×14 grid
+// once, baked here so there's no runtime cost. It draws in row by row.
+const FACE = [
+  '          ███ ██ ███',
+  '      █                █',
+  '    █                    █',
+  '  █        █      █        █',
+  ' █      ██          ██      █',
+  '█           █    █           █',
+  '█     █████        █████     █',
+  '█                            █',
+  '█                            █',
+  ' █  ██  ██   █  █           █',
+  '  ██        █    █         █',
+  '  █        █  ██         █',
+  '   ███  ███            █',
+  '          ███    ███',
+];
+
+const LOGO = ['█▀█ █░█ █▀▀ █░█ █▀ █░█', '█▀▀ █▀█ ██▄ ▀▄▀ ▄█ █▀█'];
+
+function sleep(ms) { return new Promise((r) => setTimeout(r, ms)); }
+
+async function playIntro(opts = {}) {
+  const {
+    animated = !!process.stdout.isTTY,
+    delay = sleep,
+    out = console.log,
+    listHarnesses = require('./harnesses').listHarnesses,
+  } = opts;
+
+  const { b, cream, sage, slate, teal, green } = ui;
+  const pause = async (ms) => { if (animated) await delay(ms); };
+
+  out('');
+  for (const line of FACE) { out(`  ${cream(line)}`); await pause(55); }
+  await pause(160);
+  out('');
+  for (const line of LOGO) { out(`  ${b(cream(line))}`); await pause(90); }
+  await pause(140);
+  out(`  ${sage('Keep all your AI tools.')} ${cream('phewsh is the one memory they share.')}`);
+  out('');
+  await pause(260);
+
+  // The magic beat: discover the tools already on this machine.
+  out(`  ${slate('scanning your machine for AI tools…')}`);
+  await pause(320);
+
+  let harnesses = [];
+  try { harnesses = listHarnesses().filter((h) => h.installed); } catch { /* none */ }
+
+  if (harnesses.length === 0) {
+    out(`  ${slate('· none found yet — install Claude Code, Codex, or Gemini and phewsh picks it up.')}`);
+  } else {
+    for (const h of harnesses) {
+      out(`    ${green('✓')} ${cream(h.label.padEnd(14))} ${sage(h.role || '')}`);
+      await pause(130);
+    }
+    await pause(160);
+    out('');
+    const n = harnesses.length;
+    out(`  ${teal('●')} ${sage(`Found ${n} tool${n !== 1 ? 's' : ''} — they'll all share one memory now.`)}`);
+  }
+  out('');
+  await pause(160);
+  out(`  ${sage('Next:')} ${cream('just type to start')} ${slate('·')} ${cream('phewsh setup')} ${slate('to pick a default route')}`);
+  out('');
+
+  return { toolsFound: harnesses.length };
+}
+
+module.exports = { playIntro, LOGO, FACE };

package/package.json

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