purple-ai 0.0.3 → 0.0.5

package/bin/purple.js

@@ -1,3 +1,50 @@
 #!/usr/bin/env node
 
-console.log("Coming soon. Visit bepurple.ai");
+const { spawn } = require('child_process');
+const path = require('path');
+const os = require('os');
+const fs = require('fs');
+
+function getPlatformBinary() {
+  const platform = os.platform();
+  const arch = os.arch();
+
+  let platformDir;
+  if (platform === 'darwin' && arch === 'arm64') {
+    platformDir = 'darwin-arm64';
+  } else if (platform === 'darwin' && (arch === 'x64' || arch === 'x86_64')) {
+    platformDir = 'darwin-x64';
+  } else if (platform === 'linux' && (arch === 'x64' || arch === 'x86_64')) {
+    platformDir = 'linux-x64';
+  } else {
+    console.error(`Unsupported platform: ${platform}-${arch}`);
+    console.error('Purple currently supports: macOS (arm64, x64), Linux (x64)');
+    process.exit(1);
+  }
+
+  return path.join(__dirname, platformDir, 'purple');
+}
+
+const binaryPath = getPlatformBinary();
+
+// Check if binary exists
+if (!fs.existsSync(binaryPath)) {
+  console.error(`Binary not found: ${binaryPath}`);
+  console.error('Please reinstall the package: npm install -g purple-ai');
+  process.exit(1);
+}
+
+// Spawn the binary with all arguments passed through
+const child = spawn(binaryPath, process.argv.slice(2), {
+  stdio: 'inherit',
+  env: process.env
+});
+
+child.on('error', (err) => {
+  console.error('Failed to start Purple:', err.message);
+  process.exit(1);
+});
+
+child.on('close', (code) => {
+  process.exit(code || 0);
+});

package/package.json

@@ -1,13 +1,39 @@
 {
   "name": "purple-ai",
-  "version": "0.0.3",
-  "description": "Placeholder package. Implementation coming soon.",
-  "main": "index.js",
+  "version": "0.0.5",
+  "description": "Purple - AI-powered workspace management CLI that wraps Claude Code",
+  "main": "bin/purple.js",
   "bin": {
-    "purple-ai": "./bin/purple.js"
+    "purple-ai": "./bin/purple.js",
+    "purple": "./bin/purple.js"
   },
   "scripts": {
     "test": "echo \"No tests yet\""
   },
-  "license": "ISC"
+  "keywords": [
+    "claude",
+    "ai",
+    "cli",
+    "workspace",
+    "agent",
+    "anthropic"
+  ],
+  "author": "Purple AI",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/bepurple/purple-ai"
+  },
+  "homepage": "https://bepurple.ai",
+  "engines": {
+    "node": ">=16.0.0"
+  },
+  "os": [
+    "darwin",
+    "linux"
+  ],
+  "cpu": [
+    "x64",
+    "arm64"
+  ]
 }

package/purple-CLIent technical.md

@@ -0,0 +1,19 @@
+
+## Purple CLIent
+
+This is a CLI tool, that works together with backend and needs a very nice UI and also can handle multiple terminals and switching of outputs, with pty or similar to be able to switch into claude code and then use thigns over that, like spawning command palletes, or a bottom bar.
+
+Initial implemetntaiton v0 example, the current directory has an exmaple of the pallete and the bottom bar and the behavior between shwitchng over to claude code and back.
+
+New tools that we want to use:
+
+### For UI:
+- TO make the temrinal UI entirely: https://github.com/charmbracelet/bubbletea
+- FOr building itneractive forms and prompts: https://github.com/charmbracelet/huh
+Bubbletea + Huh?
+Huh is built on Bubble Tea and, in addition to its standalone mode, huh? has first-class support and can be easily integrated into Bubble Tea applications. It’s very useful in portions of your Bubble Tea application that need form-like input, and for times when you need more flexibility than huh? alone can offer.
+
+
+### For the rest
+
+

package/purple-CLIent-product-spec.md

@@ -0,0 +1,513 @@
+# Purple CLIent - Product Specification
+
+Version: 1.2
+Last Updated: 2026-01-12
+
+---
+
+## Overview
+
+Purple CLIent is a terminal-based workspace manager that brings structure and elegance to AI-assisted development. It wraps Claude Code with workspace management, team collaboration, and a streamlined spec-to-implementation workflow.
+
+---
+
+## Why Purple?
+
+Claude Code is powerful but lacks:
+
+- **Organization** - No concept of workspaces, teams, or persistent project structure
+- **Workflow** - The spec → architect → implement pipeline is powerful but manual to set up
+- **Onboarding** - Getting a codebase "AI-ready" with standards is tedious
+
+Purple solves all three by providing a polished interface that manages workspaces, installs plugins, and guides users through feature development from spec to shipped code.
+
+---
+
+## Who is Purple for?
+
+| User | Entry Point | Primary Goal |
+|------|-------------|--------------|
+| **Solo developer** | Creates workspace for personal project | Structured AI workflow without manual setup |
+| **Tech lead** | Creates workspace, team members auto-join | Standardize how team uses AI for development |
+| **Team developer** | Joins existing workspace | Focus on building features, not configuration |
+
+---
+
+## Core Concepts
+
+### Workspace
+
+A workspace is a folder containing:
+- One or more cloned repositories
+- Installed plugins (which contain agents and commands)
+- Synced standards for the codebase
+- Feature sessions and documentation
+
+Workspaces belong to a team and are stored in the backend. The local `purple.json` only stores the `workspace_id` - all other data is fetched from the API.
+
+A user can have unlimited workspaces on their machine.
+
+### Plugin
+
+A plugin is a package that contains agents and/or commands. Plugins are company-managed and installed per workspace.
+
+**Purple Core** (required) contains:
+- product-spec-writer agent
+- engineering-architect agent
+- senior-engineer agent
+- incremental-change-engineer agent
+- build-from-spec command
+- create-standards command
+
+**Extra plugins** (optional):
+- QA Engineer plugin
+- Documentation Writer plugin
+- etc.
+
+Plugins can be distributed as:
+- **Tarball** - Downloaded and extracted to `.claude/`
+- **Repo** - Cloned from a git repository
+
+### Session
+
+A session represents one feature being built. Sessions are **purely local** - they never sync to the backend.
+
+Each session provides:
+- **Context preservation** - Claude conversation history persists, resume anytime
+- **Progress tracking** - See which features are in-progress, completed, or archived
+- **Auto-documentation** - Spec, architecture, and tickets all live in one folder
+
+Sessions live in `workbench/documentation/{feature-name}/`. When complete, users can archive sessions to reduce clutter while keeping history.
+
+### Team
+
+Teams are auto-created when a user registers. Users with the same email domain (e.g., `@company.com`) automatically join the same team.
+
+Teams share:
+- Workspaces (listed via API)
+- Standards (synced from backend to local)
+- Plugin configurations
+
+Each team member clones repos locally and has their own sessions. No roles exposed in v1 - all team members have equal access.
+
+### Standards
+
+Standards are markdown documents that describe coding conventions, architecture, and patterns for a codebase. They help Claude understand how to write code that fits the project.
+
+Standards are:
+- Generated locally by Claude via `/create-standards`
+- Uploaded to the backend for team sharing
+- Synced to local `workbench/standards/` on workspace open
+- Versioned in the backend (auto-increments on update)
+
+---
+
+## User Flows
+
+### Flow 1: Registration & First Time Setup
+
+```
+User runs: npx purple-ai
+         │
+         ▼
+┌─────────────────────────────┐
+│  No stored session found    │
+│  > Login                    │
+│  > Register                 │
+└─────────────────────────────┘
+         │
+         ▼ (Register)
+┌─────────────────────────────┐
+│  Register form:             │
+│  - Email                    │
+│  - Password                 │
+│  - Name                     │
+└─────────────────────────────┘
+         │
+         ▼
+┌─────────────────────────────────────────┐
+│  POST /api/v1/auth/register             │
+│  Backend creates user + team            │
+│                                         │
+│  If email domain matches existing team: │
+│  "You've been added to Company team     │
+│   based on your email domain"           │
+└─────────────────────────────────────────┘
+         │
+         ▼
+┌─────────────────────────────┐
+│  No workspace found         │
+│  > Create new workspace     │
+│    Clone from team          │
+└─────────────────────────────┘
+         │
+         ▼
+┌─────────────────────────────┐
+│  Select team (if multiple)  │
+│  Name your workspace        │
+│  Default: folder name       │
+│  Location: current dir      │
+│  (option to change)         │
+└─────────────────────────────┘
+         │
+         ▼
+┌─────────────────────────────┐
+│  Select repositories        │
+│  [x] org/react-app          │
+│  [x] org/api-server         │
+│  [ ] org/old-project        │
+│                             │
+│  (via gh CLI or manual URL) │
+└─────────────────────────────┘
+         │
+         ▼
+┌─────────────────────────────────────────┐
+│  POST /api/v1/workspace                 │
+│  { name, teamId }                       │
+│  → Returns workspace with id            │
+│                                         │
+│  POST /api/v1/repo (for each repo)      │
+│  { workspaceId, remoteUrl, branch }     │
+└─────────────────────────────────────────┘
+         │
+         ▼
+┌─────────────────────────────┐
+│  Select plugins             │
+│                             │
+│  Core (required):           │
+│  ✓ Purple Core              │
+│                             │
+│  Extras:                    │
+│  [x] QA Engineer            │
+│  [ ] Documentation Writer   │
+└─────────────────────────────┘
+         │
+         ▼
+┌─────────────────────────────────────────┐
+│  GET /api/v1/plugins/{id}               │
+│  Download and install selected plugins  │
+│  POST /api/v1/workspace/{id}/plugins    │
+│  { pluginId } for each selected         │
+└─────────────────────────────────────────┘
+         │
+         ▼
+┌─────────────────────────────┐
+│  "Making your codebase      │
+│   AI-ready..."              │
+│                             │
+│  → Launches Claude Code     │
+│  → Runs /create-standards   │
+│  → Returns to Purple        │
+└─────────────────────────────┘
+         │
+         ▼
+┌─────────────────────────────────────────┐
+│  POST /api/v1/standard (for each file)  │
+│  Upload generated standards to backend  │
+└─────────────────────────────────────────┘
+         │
+         ▼
+┌─────────────────────────────┐
+│  Setup complete!            │
+│  → Session list (empty)     │
+│  → Start new session        │
+└─────────────────────────────┘
+```
+
+### Flow 2: Returning User
+
+```
+User runs: npx purple-ai
+         │
+         ▼
+┌─────────────────────────────────────────┐
+│  Load token from keychain               │
+│  POST /api/v1/auth/refresh if expired   │
+│  GET /api/v1/user/me                    │
+└─────────────────────────────────────────┘
+         │
+         ▼
+┌─────────────────────────────────────────┐
+│  Workspace detection:                   │
+│  - Check current directory for          │
+│    purple.json with workspace_id        │
+│  - Check subdirectories                 │
+│                                         │
+│  If one found → open directly           │
+│  If multiple → show picker              │
+│  If none → create/clone options         │
+└─────────────────────────────────────────┘
+         │
+         ▼
+┌─────────────────────────────────────────┐
+│  On workspace open:                     │
+│  GET /api/v1/workspace/{id}             │
+│  GET /api/v1/repo?workspaceId=xxx       │
+│  GET /api/v1/standard?workspaceId=xxx   │
+│  GET /api/v1/workspace/{id}/plugins     │
+│                                         │
+│  Sync standards to local files          │
+│  Check for plugin updates               │
+└─────────────────────────────────────────┘
+         │
+         ▼
+┌─────────────────────────────┐
+│  Session List (home screen) │
+│                             │
+│  Sessions:                  │
+│  > auth-feature (active)    │
+│    dashboard (done)         │
+│    api-refactor (done)      │
+│                             │
+│  [+ New Session] [Archive]  │
+└─────────────────────────────┘
+```
+
+### Flow 3: Starting a New Session
+
+```
+User selects: + New Session
+         │
+         ▼
+┌─────────────────────────────────────────┐
+│  Check workbench/documentation/         │
+│  user-originals/ for spec files         │
+└─────────────────────────────────────────┘
+         │
+    ┌────┴────┐
+    ▼         ▼
+[Specs      [No specs
+ exist]      found]
+    │         │
+    ▼         ▼
+┌─────────┐ ┌─────────────────────────────┐
+│ Select  │ │ Enter feature name          │
+│ a spec  │ │ → Creates template file     │
+│ file    │ │ → Opens in default editor   │
+└─────────┘ │ → "Edit and save when done" │
+    │       └─────────────────────────────┘
+    │         │
+    └────┬────┘
+         ▼
+┌─────────────────────────────┐
+│  Launch Claude Code with:   │
+│  /build-from-spec {path}    │
+│                             │
+│  Status bar shows progress  │
+│  Session named after folder │
+└─────────────────────────────┘
+         │
+         ▼
+┌─────────────────────────────┐
+│  Claude session ends        │
+│  → Hook triggers return     │
+│  → Back to session list     │
+└─────────────────────────────┘
+```
+
+### Flow 4: Resuming a Session
+
+```
+User selects: existing session
+         │
+         ▼
+┌─────────────────────────────┐
+│  Launch Claude Code with:   │
+│  --resume {session-name}    │
+│                             │
+│  Full context restored      │
+│  Continue where you left    │
+└─────────────────────────────┘
+```
+
+### Flow 5: Joining a Team Workspace
+
+```
+User selects: Clone from team
+         │
+         ▼
+┌─────────────────────────────────────────┐
+│  GET /api/v1/team                       │
+│  → Returns teams user belongs to        │
+│                                         │
+│  GET /api/v1/team/{id}                  │
+│  → Returns team with workspace list     │
+└─────────────────────────────────────────┘
+         │
+         ▼
+┌─────────────────────────────┐
+│  Team Workspaces:           │
+│  > web-platform (3 repos)   │
+│    mobile-app (2 repos)     │
+│    data-pipeline (4 repos)  │
+└─────────────────────────────┘
+         │
+         ▼
+┌─────────────────────────────────────────┐
+│  GET /api/v1/workspace/{id}             │
+│  GET /api/v1/repo?workspaceId=xxx       │
+│  GET /api/v1/standard?workspaceId=xxx   │
+│  GET /api/v1/workspace/{id}/plugins     │
+└─────────────────────────────────────────┘
+         │
+         ▼
+┌─────────────────────────────┐
+│  Cloning workspace...       │
+│  - Create folder structure  │
+│  - Write purple.json        │
+│  - Clone all repos          │
+│  - Download & install       │
+│    plugins                  │
+│  - Sync standards to local  │
+└─────────────────────────────┘
+         │
+         ▼
+┌─────────────────────────────┐
+│  Ready! Session list        │
+└─────────────────────────────┘
+```
+
+### Flow 6: Adding a Repository
+
+```
+User selects: Settings → Add Repository
+         │
+         ▼
+┌─────────────────────────────┐
+│  Enter repo URL or select   │
+│  from gh CLI list           │
+└─────────────────────────────┘
+         │
+         ▼
+┌─────────────────────────────────────────┐
+│  POST /api/v1/repo                      │
+│  { workspaceId, remoteUrl, branch }     │
+└─────────────────────────────────────────┘
+         │
+         ▼
+┌─────────────────────────────┐
+│  Clone repo to /repos       │
+│  Offer to regenerate        │
+│  standards                  │
+└─────────────────────────────┘
+```
+
+### Flow 7: Updating Standards
+
+```
+After /create-standards runs or user edits standards:
+         │
+         ▼
+┌─────────────────────────────────────────┐
+│  For each standard file in              │
+│  workbench/standards/:                  │
+│                                         │
+│  Check if exists in backend:            │
+│  - PUT /api/v1/standard/{id}            │
+│    (version auto-increments)            │
+│  - POST /api/v1/standard                │
+│    (if new file)                        │
+└─────────────────────────────────────────┘
+```
+
+---
+
+## Workspace Structure
+
+```
+~/projects/my-workspace/
+├── purple.json                 # Just { "workspace_id": "uuid" }
+├── repos/
+│   ├── react-app/              # Cloned repo
+│   ├── api-server/             # Cloned repo
+│   └── shared-lib/             # Cloned repo
+├── .claude/
+│   ├── agents/                 # From installed plugins
+│   │   ├── product-spec-writer.md
+│   │   ├── engineering-architect.md
+│   │   ├── senior-engineer.md
+│   │   └── incremental-change-engineer.md
+│   └── commands/               # From installed plugins
+│       ├── build-from-spec.md
+│       ├── create-standards.md
+│       └── ...
+└── workbench/
+    ├── standards/              # Synced from backend
+    │   ├── coding-conventions.md
+    │   ├── architecture.md
+    │   └── ...
+    └── documentation/          # Purely local
+        ├── user-originals/     # User-written specs
+        │   └── auth-feature.md
+        ├── 260112-auth-feature/    # Session folder
+        │   ├── product-spec.md
+        │   ├── implementation-spec.md
+        │   └── ...
+        └── archived/           # Completed sessions
+            └── 260110-dashboard/
+```
+
+---
+
+## Data Ownership
+
+| Data | Location | Synced? |
+|------|----------|---------|
+| User profile | Backend | - |
+| Team membership | Backend | - |
+| Workspace config | Backend | purple.json has ID only |
+| Repo list | Backend | Cloned locally |
+| Standards | Backend | Synced to local files |
+| Plugins | Backend | Downloaded to .claude/ |
+| Sessions | Local only | Never synced |
+| User spec files | Local only | Never synced |
+
+---
+
+## The Purple + Claude Experience
+
+### Status Bar
+
+While in Claude Code, a status bar at the bottom shows:
+- Current phase (Spec, Architecture, Implementation)
+- Active agent
+- Ticket progress (3/10)
+- Current mode (Plan, Execute, Review)
+
+Agents update this via MCP tools.
+
+### Command Palette
+
+Press `Ctrl+K` while in Claude to open Purple's command palette:
+- **Return to Purple** - Exit Claude session, return to session list
+- **All /commands** - Quick access to commands from `.claude/commands/` folder
+
+### Returning to Purple
+
+When Claude session ends (via hook), user returns to Purple's session list automatically. No manual switching needed.
+
+### Interactive Mode
+
+Users can also "Open Claude" without starting a structured session - for freeform exploration or quick tasks. These sessions are auto-named (e.g., `interactive-260112-1`).
+
+---
+
+## What's NOT in v1
+
+- Windows support (macOS + Linux only)
+- Offline mode
+- Team roles/permissions (exists in DB but not exposed)
+- Real-time collaboration
+- Headless/CI mode
+- Custom plugin marketplace
+
+---
+
+## Success Metrics
+
+- Time from "I have an idea" to "PR ready"
+- Number of workspaces created
+- Session completion rate
+- Team adoption (workspaces with 2+ members)
+- Standards generation success rate
+- Plugin installation rate