phewsh 0.15.15 → 0.15.20

package/bin/phewsh.js

@@ -30,7 +30,7 @@ function showBrand() {
   console.log('');
   console.log(`  ${b(w('█▀█ █░█ █▀▀ █░█ █▀ █░█'))}`);
   console.log(`  ${b(w('█▀▀ █▀█ ██▄ ▀▄▀ ▄█ █▀█'))}`);
-  console.log(`  ${g('.intent/ — your project\'s working memory for every AI tool.')}`);
+  console.log(`  ${g('Keep all your AI tools. phewsh is the one memory they share.')}`);
   console.log('');
 
   // Context-aware hint
@@ -49,10 +49,11 @@ function showBrand() {
 const COMMANDS = {
   session: () => require('../commands/session'),
   intent:  () => require('../commands/intent'),
-  clarify: () => require('../commands/clarify'),
+  clarify: () => require('../commands/clarify').run(),
   push:    () => require('../commands/push'),
   pull:    () => require('../commands/pull'),
   link:    () => require('../commands/link'),
+  sync:    () => require('../commands/sync').main('status'),
   login:   () => require('../commands/login'),
   ai:      () => require('../commands/ai'),
   style:   () => require('../commands/style'),

package/commands/clarify.js

@@ -45,10 +45,52 @@ async function askForInput() {
   });
 }
 
-async function callClarifyAPI(apiKey, raw, existing) {
-  const isRefine = !!(existing?.intent?.goal);
+// The guided walk — the five strongest nodes of the web's 12-node Intent
+// Compass, asked one at a time. The web compass helps the user *see* what
+// they're building; this brings that to the terminal. Not a form: every
+// question is skippable, and the point is to help you think, not interrogate.
+const GUIDE_NODES = [
+  { id: 'purpose', title: 'Purpose', directive: 'the core reason this exists',
+    q: 'What outcome are you really after — and why does this need to exist?' },
+  { id: 'audience', title: 'Audience', directive: 'the people this serves',
+    q: 'Who is this for? Who feels it most when it works?' },
+  { id: 'method', title: 'Method', directive: 'the mechanism and approach',
+    q: 'How does it actually work — the core mechanism or approach?' },
+  { id: 'scope', title: 'Scope', directive: 'boundaries, in and out',
+    q: "What's in — and just as important, what's deliberately out, for now?" },
+  { id: 'differentiation', title: 'Edge', directive: 'what makes this yours',
+    q: 'What would be lost if someone else built this instead of you?' },
+];
+
+function ask(rl, question) {
+  return new Promise((resolve) => rl.question(question, (a) => resolve((a || '').trim())));
+}
 
-  const systemPrompt = `You are a project compiler. Your job is to extract clean, structured intent from messy human input.
+// rl is injectable so the walk can be driven deterministically in tests.
+async function askGuided(rl = readline.createInterface({ input: process.stdin, output: process.stdout })) {
+  console.log('\n  Five quick questions to align your own thinking first —');
+  console.log('  a sentence or two each. Blank skips. (esc stops, nothing saved.)\n');
+  const answers = [];
+  for (let i = 0; i < GUIDE_NODES.length; i++) {
+    const n = GUIDE_NODES[i];
+    console.log(`  ${i + 1}/${GUIDE_NODES.length}  ${n.title} — ${n.directive}`);
+    const a = await ask(rl, `  ${n.q}\n  > `);
+    if (a) answers.push({ ...n, answer: a });
+    console.log('');
+  }
+  rl.close();
+  return answers;
+}
+
+// Label each answer by its node so the compiler keeps the structure the walk
+// surfaced (a Purpose answer informs the goal, Scope informs constraints, etc.)
+function assembleRaw(answers) {
+  return answers.map((a) => `${a.title} (${a.directive}): ${a.answer}`).join('\n');
+}
+
+function buildClarifySystemPrompt(existing) {
+  const isRefine = !!(existing?.intent?.goal);
+  return `You are a project compiler. Your job is to extract clean, structured intent from messy human input.
 
 Return ONLY valid JSON — no markdown, no explanation, no commentary. The JSON must match this exact schema:
 
@@ -73,7 +115,26 @@ Rules:
 - tasks: 3-7 concrete next actions, specific enough to act on immediately
 - type options: "do" (manual action), "copy" (command to run), "open" (URL to visit), "install" (package to install)
 ${isRefine ? '\nThis is a refinement of existing intent. The previous goal was: ' + existing.intent.goal : ''}`;
+}
 
+// Pull the first valid JSON object out of model output — harnesses may wrap it
+// in prose or code fences; the API returns it clean. Throws if none parses.
+function extractJson(text) {
+  const candidates = [];
+  const fence = text.match(/```(?:json)?\s*([\s\S]*?)```/i);
+  if (fence) candidates.push(fence[1].trim());
+  const first = text.indexOf('{');
+  const last = text.lastIndexOf('}');
+  if (first !== -1 && last > first) candidates.push(text.slice(first, last + 1));
+  candidates.push(text.trim());
+  for (const c of candidates) {
+    try { return JSON.parse(c); } catch { /* try next candidate */ }
+  }
+  throw new Error('could not parse a project spec from the model output');
+}
+
+async function callClarifyAPI(apiKey, raw, existing) {
+  const systemPrompt = buildClarifySystemPrompt(existing);
   const response = await fetch('https://api.anthropic.com/v1/messages', {
     method: 'POST',
     headers: {
@@ -95,11 +156,17 @@ ${isRefine ? '\nThis is a refinement of existing intent. The previous goal was:
   }
 
   const data = await response.json();
-  const text = data.content?.[0]?.text || '';
+  return extractJson(data.content?.[0]?.text || '');
+}
 
-  // Strip markdown code fences if present
-  const clean = text.replace(/^```(?:json)?\n?/m, '').replace(/\n?```$/m, '').trim();
-  return JSON.parse(clean);
+// No API key? Compile through an installed harness instead — pass-through, so
+// clarify works for anyone with Claude Code / Codex / etc., no key required.
+async function callClarifyViaHarness(harnessId, raw, existing) {
+  const { runViaHarness } = require('../lib/harnesses');
+  const systemPrompt = buildClarifySystemPrompt(existing) +
+    '\n\nReturn ONLY the JSON object — no prose, no code fences, before or after.';
+  const out = await runViaHarness(harnessId, systemPrompt, raw, { quiet: true });
+  return extractJson(out || '');
 }
 
 function writeViews(intentDir, pps) {
@@ -126,17 +193,22 @@ async function main() {
   😮‍💨🤫  phewsh clarify
 
   Usage:
-    phewsh clarify                    Interactive: describe your project, get structured PPS
+    phewsh clarify                    Guided: a 5-question walk that aligns your thinking, then compiles
+    phewsh clarify --freeform         Free-form: describe it all in one messy blob
     phewsh clarify --text "..."       Inline: pass raw text directly
     phewsh clarify --update           Refine existing PPS with new input
 
   What it does:
-    Takes messy, buzzword-heavy input and compiles it into a structured project spec (PPS).
+    Walks you through the five strongest nodes of the Intent Compass —
+    Purpose, Audience, Method, Scope, Edge — one question at a time, so the
+    terminal helps you *think*, not just compile. Then turns your answers
+    into a structured project spec (PPS):
     Writes .intent/pps.json as the source of truth.
     Generates vision.md, plan.md, next.md as human-readable views.
 
   Requires:
-    phewsh login --set-key            Set your Anthropic API key first
+    An installed agent CLI (Claude Code, Codex, Gemini…) — phewsh uses its
+    login, no key. Or run "phewsh login --set-key" to use an Anthropic API key.
 
   Examples:
     phewsh clarify
@@ -147,8 +219,13 @@ async function main() {
   }
 
   const config = loadConfig();
-  if (!config?.apiKey) {
-    console.log('\n  No API key found. Run `phewsh login --set-key` first.\n');
+  // Pass-through: with no API key, compile through an installed harness
+  // (Claude Code, Codex, …) — the same login the rest of phewsh rides on.
+  const harnessId = config?.apiKey ? null : require('../lib/harnesses').detectInstalled();
+  if (!config?.apiKey && !harnessId) {
+    console.log('\n  Nothing to compile with yet. Either:');
+    console.log('    • install an agent CLI (Claude Code, Codex, Gemini…) — phewsh uses its login, or');
+    console.log('    • run `phewsh login --set-key` to add an API key.\n');
     process.exit(1);
   }
 
@@ -161,13 +238,25 @@ async function main() {
 
   console.log('\n  😮‍💨🤫  phewsh clarify\n');
 
+  const freeform = args.includes('--freeform') || args.includes('-f');
   let raw = rawFromFlag;
   if (!raw) {
     if (!process.stdin.isTTY) {
       console.error('\n  Pipe input or use --text "your description"\n');
       process.exit(1);
     }
-    raw = await askForInput();
+    if (freeform) {
+      raw = await askForInput();
+    } else {
+      // Guided is the default interactive path: help the user think first.
+      const answers = await askGuided();
+      raw = assembleRaw(answers);
+      if (!raw) {
+        // Skipped every question — fall back to a single free-form description.
+        console.log('  No problem — describe it your own way instead.');
+        raw = await askForInput();
+      }
+    }
   }
 
   if (!raw) {
@@ -175,11 +264,15 @@ async function main() {
     return;
   }
 
-  console.log('\n  Compiling...\n');
+  const { HARNESSES } = require('../lib/harnesses');
+  const via = harnessId ? ` via ${HARNESSES[harnessId]?.label || harnessId}` : '';
+  console.log(`\n  Compiling your intent into a spec${via}...\n`);
 
   let extracted;
   try {
-    extracted = await callClarifyAPI(config.apiKey, raw, existing);
+    extracted = harnessId
+      ? await callClarifyViaHarness(harnessId, raw, existing)
+      : await callClarifyAPI(config.apiKey, raw, existing);
   } catch (err) {
     console.error('\n  Clarify failed:', err.message, '\n');
     process.exit(1);
@@ -238,7 +331,11 @@ async function main() {
   `);
 }
 
-main().catch(err => {
-  console.error('\n  Error:', err.message);
-  process.exit(1);
-});
+if (require.main === module) {
+  main().catch(err => {
+    console.error('\n  Error:', err.message);
+    process.exit(1);
+  });
+}
+
+module.exports = { run: main, GUIDE_NODES, assembleRaw, askGuided, extractJson };

package/commands/serve.js

@@ -219,6 +219,13 @@ function json(req, res, data, status = 200) {
 }
 
 function main() {
+  if (process.argv.includes('--help') || process.argv.includes('-h')) {
+    console.log('\n  phewsh serve — local execution bridge for phewsh.com/intent');
+    console.log('    Runs a loopback server so the web workspace can dispatch to your');
+    console.log('    installed agents. Stays running until you stop it (ctrl+c).');
+    console.log('\n  Usage:  phewsh serve [--port <n>]   (default 7483)\n');
+    return;
+  }
   const port = getPort();
   const runtimes = detectRuntimes();
   const hasClaudeCode = runtimes.find(r => r.id === 'claude-code')?.connected;

package/commands/style.js

@@ -174,6 +174,15 @@ async function main() {
   const args = process.argv.slice(3);
   const config = loadConfig();
 
+  if (args.includes('--help') || args.includes('-h')) {
+    console.log('\n  phewsh style — your creative identity (StyleTree)');
+    console.log('\n  Usage:');
+    console.log('    phewsh style                  show your style profile');
+    console.log('    phewsh style --ingest <file>  add an artifact to learn from');
+    console.log('    phewsh style --status         same as bare (profile + sync tip)\n');
+    return;
+  }
+
   // --status
   if (args.includes('--status') || args.length === 0) {
     const entries = loadLocal();

package/commands/sync.js

@@ -256,7 +256,71 @@ async function link(config, token, cloudId) {
   console.log('  Run `phewsh push` to sync.\n');
 }
 
+function isAuthError(err) {
+  const m = (err && err.message || '').toLowerCase();
+  return m.includes('jwt') || m.includes('expired') || m.includes('401') || m.includes('unauthorized');
+}
+
+function agoMs(ms) {
+  const mins = Math.floor(ms / 60000);
+  if (mins < 1) return 'just now';
+  if (mins < 60) return `${mins}m ago`;
+  const hrs = Math.floor(mins / 60);
+  if (hrs < 24) return `${hrs}h ago`;
+  return `${Math.floor(hrs / 24)}d ago`;
+}
+
+// Compare local .intent/ against the cloud copy. Read-only — tells you which
+// way to sync, without doing it.
+async function status(config, token) {
+  if (!fs.existsSync(INTENT_DIR)) {
+    console.log('\n  No .intent/ here. Run `phewsh clarify` or `phewsh intent --init` first.\n');
+    return;
+  }
+  const pps = readPPS(INTENT_DIR);
+  const cloudId = pps?.adapters?.phewsh?.cloud_id;
+  const projectName = getProjectName();
+  const query = cloudId
+    ? `id=eq.${cloudId}&user_id=eq.${config.supabaseUserId}&select=id,updated_at`
+    : `name=eq.${encodeURIComponent(projectName)}&user_id=eq.${config.supabaseUserId}&select=id,updated_at`;
+
+  const projects = await select('projects', query, token);
+  if (projects.length === 0) {
+    console.log(`\n  ↕ "${projectName}" isn't in the cloud yet — run \`phewsh push\` to sync.\n`);
+    return;
+  }
+  const project = projects[0];
+  const artifacts = await select(
+    'artifacts',
+    `project_id=eq.${project.id}&user_id=eq.${config.supabaseUserId}&select=updated_at&order=updated_at.desc&limit=1`,
+    token
+  );
+  const cloudTime = artifacts.length > 0
+    ? new Date(artifacts[0].updated_at).getTime()
+    : new Date(project.updated_at).getTime();
+
+  let latestLocal = 0;
+  for (const f of ['vision.md', 'plan.md', 'next.md']) {
+    const p = path.join(INTENT_DIR, f);
+    if (fs.existsSync(p)) latestLocal = Math.max(latestLocal, fs.statSync(p).mtimeMs);
+  }
+  if (latestLocal === 0) { console.log('\n  ↕ Not linked to cloud — run `phewsh push`.\n'); return; }
+
+  const drift = Math.abs(cloudTime - latestLocal);
+  if (drift < 60000) console.log('\n  ↕ In sync — local and cloud match.\n');
+  else if (cloudTime > latestLocal) console.log(`\n  ↓ Cloud is newer (${agoMs(Date.now() - cloudTime)}) — run \`phewsh pull\`.\n`);
+  else console.log(`\n  ↑ Local changes not pushed (${agoMs(Date.now() - latestLocal)}) — run \`phewsh push\`.\n`);
+}
+
 async function main(direction = 'push') {
+  const argv = process.argv.slice(3);
+  if (argv.includes('--help') || argv.includes('-h')) {
+    console.log(`\n  phewsh ${direction} — sync .intent/ with phewsh.com/intent`);
+    console.log(`    sync   show which way to sync      push   .intent/ → cloud`);
+    console.log(`    pull   cloud → .intent/            link   adopt a cloud project\n`);
+    return;
+  }
+
   const config = loadConfig();
   if (!config?.supabaseUserId) {
     console.log('\n  Not logged in. Run `phewsh login` first.\n');
@@ -269,19 +333,31 @@ async function main(direction = 'push') {
     process.exit(1);
   }
 
-  if (direction === 'pull') {
-    await pull(config, token);
-  } else if (direction === 'link') {
-    const args = process.argv.slice(3);
-    const cloudId = args[1];
-    if (!cloudId) {
-      console.log('\n  Usage: phewsh link <cloud-project-id>\n');
-      process.exit(1);
+  // The token can still be rejected server-side (refresh token also expired).
+  // Convert that into the same friendly nudge instead of a raw stack trace.
+  try {
+    if (direction === 'status') {
+      await status(config, token);
+    } else if (direction === 'pull') {
+      await pull(config, token);
+    } else if (direction === 'link') {
+      const cloudId = argv[0] && !argv[0].startsWith('-') ? argv[0] : process.argv[4];
+      if (!cloudId) {
+        console.log('\n  Usage: phewsh link <cloud-project-id>\n');
+        process.exit(1);
+      }
+      await link(config, token, cloudId);
+    } else {
+      await push(config, token);
+    }
+  } catch (err) {
+    if (isAuthError(err)) {
+      console.log('\n  Session expired. Run `phewsh login` to re-authenticate.\n');
+    } else {
+      console.log(`\n  ${direction} failed: ${err.message}\n`);
     }
-    await link(config, token, cloudId);
-  } else {
-    await push(config, token);
+    process.exit(1);
   }
 }
 
-module.exports = { main, push, pull, link, ensureValidToken, loadConfig };
+module.exports = { main, push, pull, link, status, ensureValidToken, loadConfig };

package/package.json

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