phewsh 0.1.0

package/README.md

@@ -0,0 +1,36 @@
+# phewsh
+
+Turn intent into action.
+
+## Install
+
+```bash
+npm install -g phewsh
+```
+
+## Usage
+
+```bash
+phewsh intent --init      # Create .intent/ in any project
+phewsh intent --status    # Check artifact state and next actions
+phewsh intent --open      # Open the web compass
+phewsh intent --evolve    # Update artifacts as the project grows
+```
+
+## What it does
+
+`phewsh intent --init` asks what you're building and what success looks like, then creates three structured artifacts in `.intent/`:
+
+- **vision.md** — The north star. Why this exists and where it's going.
+- **plan.md** — The strategy. Phases, systems, sequence, constraints.
+- **next.md** — Right now. Executable checklist with copy-paste commands.
+
+Drop `.intent/` in any project and your AI tools gain full context instantly.
+
+## Web app
+
+[phewsh.com/intent](https://phewsh.com/intent)
+
+## License
+
+MIT

package/bin/phewsh.js

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+
+const args = process.argv.slice(2);
+const command = args[0];
+
+const COMMANDS = {
+  intent: () => require('../commands/intent'),
+  music: () => require('../commands/music'),
+  sap: () => require('../commands/sap'),
+  help: () => showHelp(),
+  version: () => console.log(`phewsh v${require('../package.json').version}`),
+};
+
+function showHelp() {
+  console.log(`
+  😮‍💨🤫  phewsh — turn intent into action
+
+  Usage:
+    phewsh <command> [options]
+
+  Commands:
+    intent    Capture structured intent → generate vision, plan, and next actions
+    music     Open the MBHD music engine
+    sap       View Sustainable AI Protocol usage stats
+    help      Show this help message
+    version   Show version
+
+  Quick start:
+    phewsh intent              Start a new intent capture session
+    phewsh intent --evolve     Evolve existing .intent/ artifacts
+    phewsh intent --open       Open phewsh.com/intent in your browser
+
+  Learn more: https://phewsh.com
+  `);
+}
+
+if (!command || command === 'help' || command === '--help' || command === '-h') {
+  showHelp();
+  process.exit(0);
+}
+
+if (command === 'version' || command === '--version' || command === '-v') {
+  COMMANDS.version();
+  process.exit(0);
+}
+
+if (COMMANDS[command]) {
+  COMMANDS[command]();
+} else {
+  console.error(`  Unknown command: ${command}\n  Run 'phewsh help' for available commands.`);
+  process.exit(1);
+}

package/commands/intent.js

@@ -0,0 +1,258 @@
+const fs = require('fs');
+const path = require('path');
+const readline = require('readline');
+const { execSync } = require('child_process');
+
+const args = process.argv.slice(3);
+const INTENT_DIR = path.join(process.cwd(), '.intent');
+const WEB_URL = 'https://phewsh.com/intent';
+
+const flags = {
+  evolve: args.includes('--evolve') || args.includes('-e'),
+  open: args.includes('--open') || args.includes('-o'),
+  status: args.includes('--status') || args.includes('-s'),
+  init: args.includes('--init') || args.includes('-i'),
+  help: args.includes('--help') || args.includes('-h'),
+};
+
+function hasExistingArtifacts() {
+  return fs.existsSync(INTENT_DIR) &&
+    fs.existsSync(path.join(INTENT_DIR, 'vision.md')) &&
+    fs.existsSync(path.join(INTENT_DIR, 'plan.md'));
+}
+
+function createPrompter() {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  const ask = (question) => new Promise((resolve) => {
+    rl.question(question, (answer) => resolve(answer.trim()));
+  });
+  const close = () => rl.close();
+  return { ask, close };
+}
+
+function openWeb() {
+  console.log(`\n  Opening ${WEB_URL} ...\n`);
+  try {
+    if (process.platform === 'darwin') execSync(`open "${WEB_URL}"`);
+    else if (process.platform === 'win32') execSync(`start "${WEB_URL}"`);
+    else execSync(`xdg-open "${WEB_URL}"`);
+  } catch {
+    console.log(`  Could not open browser. Visit: ${WEB_URL}\n`);
+  }
+}
+
+function showStatus() {
+  if (!hasExistingArtifacts()) {
+    console.log('\n  No .intent/ found in this directory.');
+    console.log('  Run `phewsh intent --init` to create one.\n');
+    return;
+  }
+
+  console.log('\n  .intent/ — artifact status\n');
+
+  const files = ['vision.md', 'plan.md', 'next.md', 'status.md'];
+  for (const file of files) {
+    const filePath = path.join(INTENT_DIR, file);
+    if (fs.existsSync(filePath)) {
+      const stat = fs.statSync(filePath);
+      const kb = (stat.size / 1024).toFixed(1);
+      const updated = stat.mtime.toLocaleDateString();
+      console.log(`  ✓ ${file.padEnd(14)} ${kb}KB   updated ${updated}`);
+    }
+  }
+
+  const nextPath = path.join(INTENT_DIR, 'next.md');
+  const statusPath = path.join(INTENT_DIR, 'status.md');
+  const actionFile = fs.existsSync(nextPath) ? nextPath : fs.existsSync(statusPath) ? statusPath : null;
+
+  if (actionFile) {
+    const content = fs.readFileSync(actionFile, 'utf-8');
+    const checkboxes = content.split('\n').filter(l => l.match(/^[-*]\s*\[[ x]\]/));
+    if (checkboxes.length > 0) {
+      const done = checkboxes.filter(l => l.includes('[x]')).length;
+      console.log(`\n  Next Actions: ${done}/${checkboxes.length} complete\n`);
+      checkboxes.slice(0, 5).forEach(line => {
+        const checked = line.includes('[x]');
+        const text = line.replace(/^[-*]\s*\[[ x]\]\s*/, '').replace(/\*\*/g, '');
+        console.log(`  ${checked ? '✅' : '⬜'} ${text}`);
+      });
+      if (checkboxes.length > 5) console.log(`  ... and ${checkboxes.length - 5} more`);
+    }
+  }
+
+  console.log('\n  Run `phewsh intent --evolve` to update artifacts.\n');
+}
+
+async function initIntent() {
+  if (hasExistingArtifacts()) {
+    console.log('\n  .intent/ already exists in this directory.');
+    console.log('  Use `phewsh intent --status` to view or `--evolve` to update.\n');
+    return;
+  }
+
+  const projectName = path.basename(process.cwd());
+  const date = new Date().toISOString().split('T')[0];
+
+  console.log('\n  😮‍💨🤫  phewsh intent --init\n');
+
+  let what = '';
+  let goal = '';
+
+  if (process.stdin.isTTY) {
+    console.log('  Answer two questions. Your artifacts will be ready instantly.\n');
+    const { ask, close } = createPrompter();
+    what = await ask('  What are you building? (one or two sentences)\n  > ');
+    goal = await ask('\n  What does success look like? What\'s the primary outcome?\n  > ');
+    close();
+    console.log('');
+  } else {
+    console.log('  Creating starter artifacts...\n');
+  }
+
+  console.log('\n  Creating .intent/ ...\n');
+
+  fs.mkdirSync(INTENT_DIR, { recursive: true });
+
+  const vision = `---
+entity: ${projectName}
+archetype: product
+created: ${date}
+updated: ${date}
+---
+
+# Vision
+
+## North Star
+${what || `What is ${projectName} and why does it exist?`}
+
+## Outcomes
+${goal ? `- ${goal}` : '<!-- What does success look like? 3-5 concrete outcomes. -->'}
+- <!-- Add more outcomes here -->
+
+## Principles
+<!-- Non-negotiable values and constraints. What will you never compromise on? -->
+-
+-
+
+## Beneficiaries
+<!-- Who benefits from this and how? Be specific. -->
+`;
+
+  const plan = `---
+entity: ${projectName}
+archetype: product
+created: ${date}
+updated: ${date}
+---
+
+# Plan
+
+## Current Strategy
+<!-- One paragraph: the approach and why it's the right one right now. -->
+
+## Systems
+<!-- What needs to exist? Key components, tools, structures. -->
+
+## Sequence
+<!-- Phased plan. What must come first? What is blocked on what? -->
+- Phase 1:
+- Phase 2:
+- Phase 3:
+
+## Constraints
+<!-- What limits this? Budget, time, team, technical. Be honest. -->
+
+## Resources
+<!-- What do you have available? Team, tools, existing assets. -->
+`;
+
+  const next = `---
+entity: ${projectName}
+archetype: product
+created: ${date}
+updated: ${date}
+---
+
+# Next
+
+## Current State
+${what ? `Building: ${what}` : '<!-- Where things stand right now, honestly. -->'}
+
+## Next Actions
+- [ ] **Refine the vision** — Open the web compass and complete vision.md
+- [ ] **Define Phase 1** — What is the smallest thing you can ship?
+- [ ] **Identify the first blocker** — What is standing between you and execution?
+
+## Blocked
+<!-- What is stuck and why? What decision is needed to unblock it? -->
+
+## Metrics
+<!-- 2-3 numbers that tell you if it's working. -->
+`;
+
+  fs.writeFileSync(path.join(INTENT_DIR, 'vision.md'), vision);
+  fs.writeFileSync(path.join(INTENT_DIR, 'plan.md'), plan);
+  fs.writeFileSync(path.join(INTENT_DIR, 'next.md'), next);
+
+  console.log(`  ✓ .intent/vision.md    — The north star`);
+  console.log(`  ✓ .intent/plan.md      — The strategy`);
+  console.log(`  ✓ .intent/next.md      — What to do right now`);
+  console.log(`
+  These files are your persistent context.
+  Drop them in any AI coding session and your tools gain full understanding.
+
+  Next:
+    phewsh intent --open      Open the web compass to go deeper
+    phewsh intent --status    Check your progress any time
+  `);
+}
+
+function showHelp() {
+  console.log(`
+  😮‍💨🤫  phewsh intent
+
+  Usage:
+    phewsh intent              Show status (or prompt to init if new)
+    phewsh intent --init       Create .intent/ with structured artifacts
+    phewsh intent --status     Show artifact state and next actions
+    phewsh intent --open       Open the web compass at phewsh.com/intent
+    phewsh intent --evolve     Open compass to update existing artifacts
+
+  Artifacts created in .intent/:
+    vision.md   — Why this exists and where it's going
+    plan.md     — How to get there, in what order
+    next.md     — What to do right now (executable checklist)
+
+  These work with any AI coding tool. Your context travels with the project.
+  `);
+}
+
+// Main
+async function main() {
+  if (flags.help) {
+    showHelp();
+  } else if (flags.open) {
+    openWeb();
+  } else if (flags.init) {
+    await initIntent();
+  } else if (flags.status) {
+    showStatus();
+  } else if (flags.evolve) {
+    if (!hasExistingArtifacts()) {
+      console.log('\n  No .intent/ found. Run `phewsh intent --init` first.\n');
+    } else {
+      openWeb();
+    }
+  } else {
+    if (hasExistingArtifacts()) {
+      showStatus();
+    } else {
+      showHelp();
+    }
+  }
+}
+
+main().catch(err => {
+  console.error('\n  Error:', err.message);
+  process.exit(1);
+});

package/commands/music.js

@@ -0,0 +1,17 @@
+const { execSync } = require('child_process');
+
+const WEB_URL = 'https://phewsh.com/music';
+
+console.log(`\n  🎵 Opening MBHD Music Engine...\n`);
+
+try {
+  if (process.platform === 'darwin') {
+    execSync(`open "${WEB_URL}"`);
+  } else if (process.platform === 'win32') {
+    execSync(`start "${WEB_URL}"`);
+  } else {
+    execSync(`xdg-open "${WEB_URL}"`);
+  }
+} catch {
+  console.log(`  Could not open browser. Visit: ${WEB_URL}\n`);
+}

package/commands/sap.js

@@ -0,0 +1,20 @@
+const fs = require('fs');
+const path = require('path');
+
+const args = process.argv.slice(3);
+
+console.log(`
+  🌿 Sustainable AI Protocol (SAP)
+
+  Track AI usage and environmental impact across your tools.
+
+  Status: SDK available, dashboard coming soon.
+
+  Quick links:
+    Web:  https://phewsh.com/sap
+    Docs: https://sustainableaiprotocol.com
+
+  To embed SAP tracking in your project:
+    const SAP = require('sustainable-ai-protocol');
+    const passport = await SAP.createPassport({ model: 'claude-opus', tokens: 1500 });
+`);

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "phewsh",
+  "version": "0.1.0",
+  "description": "Turn intent into action. Structure your thinking, execute your next step.",
+  "bin": {
+    "phewsh": "./bin/phewsh.js"
+  },
+  "files": [
+    "bin/",
+    "commands/",
+    "README.md"
+  ],
+  "keywords": [
+    "intent",
+    "ai",
+    "artifacts",
+    "planning",
+    "execution",
+    "vision",
+    "productivity",
+    "claude",
+    "phewsh"
+  ],
+  "author": "Phewsh <hello@phewsh.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/cleverIdeaz/phewsh"
+  },
+  "homepage": "https://phewsh.com",
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}