orbital-command 0.3.0 → 1.0.0

package/README.md

@@ -24,52 +24,32 @@ Think of it as the control tower that turns a collection of AI-assisted coding s
 
 - **Node.js >= 18**
 - **Claude Code** installed and available as `claude` on your PATH
+- **iTerm2** (macOS, recommended) — sprint dispatch and batch orchestration use iTerm2 tabs to run parallel Claude Code sessions. Without it, sessions fall back to basic subprocess mode. The setup wizard will prompt you to install it.
 - **C++ compiler** for the `better-sqlite3` native module:
   - macOS: Xcode Command Line Tools (`xcode-select --install`)
   - Linux: `build-essential` (`apt install build-essential`)
 
-## Installation
-
-**Global install (recommended for regular use):**
-
-```bash
-npm install -g github:SakaraLabs/orbital-command
-```
-
-This registers the `orbital` command globally. Then in any project:
-
-```bash
-orbital init
-orbital dev
-```
-
-**Without global install:**
-
-```bash
-npx github:SakaraLabs/orbital-command init
-npx github:SakaraLabs/orbital-command dev
-```
-
 ## Quick Start
 
 ```bash
-# 1. Navigate to your project
+npm install orbital-command
 cd my-project
+orbital
+```
 
-# 2. Scaffold Orbital Command (hooks, skills, agents, config)
-orbital init
+That's it. The `orbital` command detects your context and guides you through everything:
 
-# 3. Launch the dashboard
-orbital dev
-```
+1. **First run** — setup wizard configures Orbital globally
+2. **New project** — project setup wizard scaffolds hooks, skills, agents, and workflow config
+3. **Existing project** — hub menu lets you launch the dashboard, edit config, run diagnostics, or update templates
 
-Open [http://localhost:4445](http://localhost:4445) in your browser. The API server runs on port 4444.
+On macOS, the wizard will recommend installing [iTerm2](https://iterm2.com) for the full dispatch experience — it polls for the install automatically so you can continue once it's ready.
 
-The `init` command is non-destructive — it skips files that already exist. Pass `--force` to overwrite everything with the latest templates.
+Open [http://localhost:4444](http://localhost:4444) after launching.
 
 ## What Gets Installed
 
-After `orbital init`, your project receives:
+After setup, your project receives:
 
 ```
 .claude/
@@ -111,15 +91,26 @@ scopes/
 
 ## CLI Reference
 
+The bare `orbital` command is the primary entry point — it detects context and shows the right options. All subcommands below are also available directly for scripting or when you know what you want.
+
 | Command | Description |
 |---------|-------------|
-| `orbital init` | Scaffold hooks, skills, agents, and config into the current project |
-| `orbital init --force` | Re-scaffold, overwriting all existing files with latest templates |
-| `orbital dev` | Start the API server and Vite dev server concurrently |
-| `orbital build` | Production build of the dashboard frontend |
+| `orbital` | Context-aware hub menu (setup, init, launch, config, etc.) |
+| `orbital` | Context-aware hub menu (setup, launch, config, doctor, etc.) |
+| `orbital config` | Modify project settings interactively |
+| `orbital doctor` | Health check and version diagnostics |
+| `orbital update` | Sync templates and apply migrations |
+| `orbital status` | Show template sync status |
 | `orbital emit <TYPE> [JSON]` | Emit an event to the file-based event bus |
-| `orbital update` | Re-copy hooks, skills, agents, and presets (overwrites). Pass `--include-examples` to include domain-specific example agents |
-| `orbital uninstall` | Remove all Orbital artifacts from the project. Preserves `scopes/` and event history |
+| `orbital validate` | Check cross-references and consistency |
+| `orbital register [path]` | Register a project with the dashboard |
+| `orbital unregister <id>` | Remove a project from the dashboard |
+| `orbital projects` | List all registered projects |
+| `orbital pin <path>` | Lock a file from template updates |
+| `orbital unpin <path>` | Unlock a pinned file |
+| `orbital diff <path>` | Show diff between template and local file |
+| `orbital reset <path>` | Restore a file from the current template |
+| `orbital uninstall` | Remove all Orbital artifacts from the project |
 
 ## Workflow Presets
 
@@ -351,7 +342,7 @@ When you dispatch a scope from the dashboard, Orbital:
 No. Orbital Command is purpose-built for Claude Code. The hooks, skills, agents, and session tracking all depend on Claude Code's lifecycle events and CLI.
 
 ### Do I need to keep the dashboard running?
-No. The file-based event bus means hooks write events as JSON files regardless of whether the server is running. Events queue up and get ingested when you next run `orbital dev`.
+No. The file-based event bus means hooks write events as JSON files regardless of whether the server is running. Events queue up and get ingested when you next launch the dashboard.
 
 ### How do I customize the workflow columns?
 Open the Workflow Visualizer (`/workflow` in the dashboard). You can add/remove columns, create transitions, attach hooks, and set confirmation levels. Or edit `.claude/config/workflow.json` directly. Changes take effect immediately.
@@ -370,7 +361,7 @@ Sprints group multiple scopes for batch execution. The orchestrator resolves dep
 ### How do I reset everything?
 ```bash
 orbital uninstall    # Remove all Orbital artifacts
-orbital init --force # Re-scaffold from scratch
+# Then run `orbital` and select "Reset to defaults"
 ```
 
 This preserves your `scopes/` directory and event history.
@@ -382,14 +373,48 @@ Yes. Set `terminal.adapter` in your config:
 - `"subprocess"` — Generic subprocess spawning (works everywhere)
 - `"none"` — Disable terminal dispatch
 
+## Development
+
+```bash
+# Install dependencies (includes all build/frontend packages as devDependencies)
+npm install
+
+# Start dev server with hot-reload
+npm run dev:local
+
+# Run the full validation pipeline (typecheck → test → build → build:server)
+npm run validate
+```
+
+| Script | Purpose |
+|--------|---------|
+| `npm run dev:local` | Express API + Vite dev server with hot-reload |
+| `npm run dev:server` | Express API only (tsx watch) |
+| `npm run dev:client` | Vite dev server only |
+| `npm run typecheck` | Type check client + server tsconfigs |
+| `npm run test` | Run all tests |
+| `npm run build` | Vite production build (frontend) |
+| `npm run build:server` | TypeScript compile server to dist/server |
+| `npm run validate` | Full pipeline: typecheck → test → build → build:server |
+
+### Releasing
+
+```bash
+npm run release             # patch bump (0.3.0 → 0.3.1)
+npm run release -- minor    # minor bump (0.3.0 → 0.4.0)
+npm run release -- major    # major bump (0.3.0 → 1.0.0)
+```
+
+This validates the full pipeline, bumps the version, creates a git tag, and pushes. The tag push triggers the publish workflow which validates again and publishes to npm with provenance.
+
 ## Contributing
 
+Open an issue first for large changes or new features.
+
 1. Fork the repository and clone locally
 2. Install dependencies: `npm install`
 3. Start development: `npm run dev:local`
-4. Typecheck: `npm run typecheck`
-
-Open an issue first for large changes or new features.
+4. Validate before submitting: `npm run validate`
 
 ## License
 

package/bin/commands/config.js

@@ -0,0 +1,19 @@
+import {
+  detectProjectRoot,
+  getPackageVersion,
+  loadWizardModule,
+} from '../lib/helpers.js';
+
+export async function cmdConfig(args) {
+  const { runConfigEditor } = await loadWizardModule();
+  const projectRoot = detectProjectRoot();
+  const version = getPackageVersion();
+  await runConfigEditor(projectRoot, version, args);
+}
+
+export async function cmdDoctor() {
+  const { runDoctor } = await loadWizardModule();
+  const projectRoot = detectProjectRoot();
+  const version = getPackageVersion();
+  await runDoctor(projectRoot, version);
+}

package/bin/commands/events.js

@@ -0,0 +1,40 @@
+import fs from 'fs';
+import path from 'path';
+import crypto from 'crypto';
+import { detectProjectRoot } from '../lib/helpers.js';
+
+export function cmdEmit(args) {
+  const type = args[0];
+  const jsonStr = args.slice(1).join(' ');
+
+  if (!type) {
+    console.error('Usage: orbital emit <TYPE> <JSON>');
+    process.exit(1);
+  }
+
+  const projectRoot = detectProjectRoot();
+  const eventsDir = path.join(projectRoot, '.claude', 'orbital-events');
+  if (!fs.existsSync(eventsDir)) fs.mkdirSync(eventsDir, { recursive: true });
+
+  let payload;
+  try {
+    payload = jsonStr ? JSON.parse(jsonStr) : {};
+  } catch (err) {
+    console.error(`Invalid JSON: ${err.message}`);
+    process.exit(1);
+  }
+
+  const eventId = crypto.randomUUID();
+  const event = {
+    ...payload,
+    id: eventId,
+    type,
+    timestamp: new Date().toISOString(),
+  };
+
+  const filePath = path.join(eventsDir, `${eventId}.json`);
+  fs.writeFileSync(filePath, JSON.stringify(event, null, 2) + '\n', 'utf8');
+
+  console.log(`Event emitted: ${type} (${eventId})`);
+  console.log(`  File: ${path.relative(projectRoot, filePath)}`);
+}

package/bin/commands/launch.js

@@ -0,0 +1,126 @@
+import fs from 'fs';
+import path from 'path';
+import { spawn } from 'child_process';
+import {
+  PACKAGE_ROOT,
+  resolveBin,
+  detectProjectRoot,
+  loadConfig,
+  openBrowser,
+} from '../lib/helpers.js';
+
+export function cmdLaunchOrDev(forceViteFlag) {
+  const shouldOpen = process.argv.includes('--open');
+  const forceVite = forceViteFlag || process.argv.includes('--vite');
+  const projectRoot = detectProjectRoot();
+  const config = loadConfig(projectRoot);
+  const serverPort = config.serverPort || 4444;
+  const clientPort = config.clientPort || 4445;
+
+  // Detect packaged mode: dist/index.html exists -> serve pre-built frontend
+  const hasPrebuiltFrontend = fs.existsSync(path.join(PACKAGE_ROOT, 'dist', 'index.html'));
+  const useVite = forceVite || !hasPrebuiltFrontend;
+
+  // Detect compiled server: dist/server/server/launch.js exists -> run with node
+  const compiledServer = path.join(PACKAGE_ROOT, 'dist', 'server', 'server', 'launch.js');
+  const hasCompiledServer = fs.existsSync(compiledServer);
+  const useCompiledServer = hasCompiledServer && !useVite;
+
+  console.log(`\nOrbital Command — ${useVite ? 'dev' : 'launch'}`);
+  console.log(`Project root: ${projectRoot}`);
+  if (useVite) {
+    console.log(`Server: http://localhost:${serverPort}`);
+    console.log(`Client: http://localhost:${clientPort} (Vite dev server)\n`);
+  } else {
+    console.log(`Dashboard: http://localhost:${serverPort}\n`);
+  }
+
+  const env = {
+    ...process.env,
+    ORBITAL_LAUNCH_MODE: 'central',
+    ORBITAL_AUTO_REGISTER: projectRoot,
+    ORBITAL_SERVER_PORT: String(serverPort),
+  };
+
+  let serverProcess;
+
+  if (useCompiledServer) {
+    serverProcess = spawn(process.execPath, [compiledServer],
+      { stdio: 'inherit', env, cwd: PACKAGE_ROOT });
+  } else {
+    const tsxBin = resolveBin('tsx');
+    const serverScript = path.join(PACKAGE_ROOT, 'server', 'launch.ts');
+    if (tsxBin) {
+      serverProcess = spawn(tsxBin, ['watch', serverScript],
+        { stdio: 'inherit', env, cwd: PACKAGE_ROOT });
+    } else {
+      console.error('Error: tsx not found. Install it with: npm install tsx');
+      process.exit(1);
+    }
+  }
+
+  let viteProcess = null;
+
+  if (useVite) {
+    const viteBin = resolveBin('vite');
+    if (!viteBin) {
+      console.error('Error: vite not found. Install it with: npm install vite');
+      process.exit(1);
+    }
+    viteProcess = spawn(viteBin, ['--config', path.join(PACKAGE_ROOT, 'vite.config.ts'), '--port', String(clientPort)],
+      { stdio: 'inherit', env, cwd: PACKAGE_ROOT });
+  }
+
+  const dashboardUrl = useVite
+    ? `http://localhost:${clientPort}`
+    : `http://localhost:${serverPort}`;
+
+  if (shouldOpen) {
+    setTimeout(() => openBrowser(dashboardUrl), 2000);
+  }
+
+  let exiting = false;
+
+  function cleanup() {
+    if (exiting) return;
+    exiting = true;
+    serverProcess.kill();
+    if (viteProcess) viteProcess.kill();
+    process.exit(0);
+  }
+  process.on('SIGINT', cleanup);
+  process.on('SIGTERM', cleanup);
+
+  serverProcess.on('exit', (code) => {
+    if (exiting) return;
+    exiting = true;
+    console.log(`Server exited with code ${code}`);
+    if (viteProcess) viteProcess.kill();
+    process.exit(code || 0);
+  });
+  if (viteProcess) {
+    viteProcess.on('exit', (code) => {
+      if (exiting) return;
+      exiting = true;
+      console.log(`Vite exited with code ${code}`);
+      serverProcess.kill();
+      process.exit(code || 0);
+    });
+  }
+}
+
+export function cmdBuild() {
+  console.log(`\nOrbital Command — build\n`);
+
+  const viteBin = resolveBin('vite');
+  if (!viteBin) {
+    console.error('Error: vite not found. Install it with: npm install vite');
+    process.exit(1);
+  }
+  const buildProcess = spawn(viteBin, ['build', '--config', path.join(PACKAGE_ROOT, 'vite.config.ts')],
+    { stdio: 'inherit', cwd: PACKAGE_ROOT });
+
+  buildProcess.on('exit', (code) => {
+    process.exit(code || 0);
+  });
+}

package/bin/commands/manifest.js

@@ -0,0 +1,283 @@
+import fs from 'fs';
+import path from 'path';
+import { execFileSync } from 'child_process';
+import {
+  PACKAGE_ROOT,
+  detectProjectRoot,
+  getPackageVersion,
+  loadSharedModule,
+} from '../lib/helpers.js';
+
+export async function cmdStatus() {
+  const projectRoot = detectProjectRoot();
+
+  const mod = await loadSharedModule();
+  const manifest = mod.loadManifest(projectRoot);
+
+  if (!manifest) {
+    console.log('\nNo manifest found. Run `orbital` to set up this project.\n');
+    return;
+  }
+
+  const claudeDir = path.join(projectRoot, '.claude');
+  mod.refreshFileStatuses(manifest, claudeDir);
+
+  const summary = mod.summarizeManifest(manifest);
+  const packageVersion = getPackageVersion();
+  const needsUpdate = manifest.packageVersion !== packageVersion;
+
+  console.log(`\nOrbital Command v${packageVersion}${needsUpdate ? ` (installed: ${manifest.packageVersion} → needs update)` : ''}\n`);
+
+  for (const [type, counts] of Object.entries(summary.byType)) {
+    const parts = [];
+    if (counts.synced) parts.push(`${counts.synced} synced`);
+    if (counts.outdated) parts.push(`${counts.outdated} outdated`);
+    if (counts.modified) parts.push(`${counts.modified} modified`);
+    if (counts.pinned) parts.push(`${counts.pinned} pinned`);
+    if (counts.userOwned) parts.push(`${counts.userOwned} user-owned`);
+    console.log(`  ${type.padEnd(16)} ${parts.join(', ')}`);
+  }
+
+  const outdated = Object.entries(manifest.files)
+    .filter(([, r]) => r.status === 'outdated');
+  if (outdated.length > 0) {
+    console.log('\n  Outdated files (safe to update):');
+    for (const [file] of outdated) {
+      console.log(`    ${file}`);
+    }
+  }
+
+  const modified = Object.entries(manifest.files)
+    .filter(([, r]) => r.status === 'modified');
+  if (modified.length > 0) {
+    console.log('\n  Modified files (user edited):');
+    for (const [file] of modified) {
+      console.log(`    ${file}  (run 'orbital diff ${file}')`);
+    }
+  }
+
+  const pinned = Object.entries(manifest.files)
+    .filter(([, r]) => r.status === 'pinned');
+  if (pinned.length > 0) {
+    console.log('\n  Pinned files:');
+    for (const [file, record] of pinned) {
+      const reason = record.pinnedReason ? `"${record.pinnedReason}"` : '';
+      console.log(`    ${file}  ${reason}`);
+    }
+  }
+
+  console.log();
+}
+
+export async function cmdValidate() {
+  const projectRoot = detectProjectRoot();
+
+  const mod = await loadSharedModule();
+  const report = mod.validate(projectRoot, getPackageVersion());
+  console.log(mod.formatValidationReport(report));
+  process.exit(report.errors > 0 ? 1 : 0);
+}
+
+export async function cmdPin(args) {
+  const projectRoot = detectProjectRoot();
+  const filePath = args.find(a => !a.startsWith('--'));
+  const reasonIdx = args.indexOf('--reason');
+  const reason = reasonIdx !== -1 ? args[reasonIdx + 1] : undefined;
+
+  if (!filePath) {
+    console.error('Usage: orbital pin <relative-path> [--reason "..."]');
+    process.exit(1);
+  }
+
+  const mod = await loadSharedModule();
+  const manifest = mod.loadManifest(projectRoot);
+  if (!manifest) {
+    console.error('No manifest found. Run `orbital` first.');
+    process.exit(1);
+  }
+
+  const record = manifest.files[filePath];
+  if (!record) {
+    console.error(`File not tracked: ${filePath}`);
+    process.exit(1);
+  }
+  if (record.origin === 'user') {
+    console.error(`Cannot pin user-owned file: ${filePath}`);
+    process.exit(1);
+  }
+
+  record.status = 'pinned';
+  record.pinnedAt = new Date().toISOString();
+  if (reason) record.pinnedReason = reason;
+
+  mod.saveManifest(projectRoot, manifest);
+  console.log(`Pinned: ${filePath}${reason ? ` (${reason})` : ''}`);
+}
+
+export async function cmdUnpin(args) {
+  const projectRoot = detectProjectRoot();
+  const filePath = args[0];
+
+  if (!filePath) {
+    console.error('Usage: orbital unpin <relative-path>');
+    process.exit(1);
+  }
+
+  const mod = await loadSharedModule();
+  const manifest = mod.loadManifest(projectRoot);
+  if (!manifest) {
+    console.error('No manifest found. Run `orbital` first.');
+    process.exit(1);
+  }
+
+  const record = manifest.files[filePath];
+  if (!record || record.status !== 'pinned') {
+    console.error(`File is not pinned: ${filePath}`);
+    process.exit(1);
+  }
+
+  record.status = 'synced';
+  delete record.pinnedAt;
+  delete record.pinnedReason;
+
+  const absPath = path.join(projectRoot, '.claude', filePath);
+  if (fs.existsSync(absPath)) {
+    const currentHash = mod.hashFile(absPath);
+    record.status = mod.computeFileStatus(record, currentHash);
+  } else {
+    record.status = 'synced';
+  }
+
+  mod.saveManifest(projectRoot, manifest);
+  console.log(`Unpinned: ${filePath} (now ${record.status})`);
+}
+
+export async function cmdPins() {
+  const projectRoot = detectProjectRoot();
+
+  const mod = await loadSharedModule();
+  const manifest = mod.loadManifest(projectRoot);
+  if (!manifest) {
+    console.error('No manifest found. Run `orbital` first.');
+    process.exit(1);
+  }
+
+  const pinned = Object.entries(manifest.files)
+    .filter(([, r]) => r.status === 'pinned');
+
+  if (pinned.length === 0) {
+    console.log('No pinned files.');
+    return;
+  }
+
+  console.log(`\n  Pinned files:\n`);
+  for (const [file, record] of pinned) {
+    const reason = record.pinnedReason || '(no reason)';
+    const date = record.pinnedAt ? new Date(record.pinnedAt).toLocaleDateString() : '';
+    console.log(`  ${file}`);
+    console.log(`    Reason: ${reason}  Pinned: ${date}`);
+    if (record.templateHash !== record.installedHash) {
+      console.log(`    Template has changed since pin — run 'orbital diff ${file}' to compare`);
+    }
+  }
+  console.log();
+}
+
+export async function cmdDiff(args) {
+  const projectRoot = detectProjectRoot();
+  const filePath = args[0];
+
+  if (!filePath) {
+    console.error('Usage: orbital diff <relative-path>');
+    process.exit(1);
+  }
+
+  const mod = await loadSharedModule();
+  const manifest = mod.loadManifest(projectRoot);
+  if (!manifest) {
+    console.error('No manifest found. Run `orbital` first.');
+    process.exit(1);
+  }
+
+  const record = manifest.files[filePath];
+  if (!record || record.origin !== 'template') {
+    console.error(`Not a template file: ${filePath}`);
+    process.exit(1);
+  }
+
+  let templateRelPath = filePath;
+  if (filePath.startsWith('config/workflows/')) {
+    templateRelPath = filePath.replace('config/workflows/', 'presets/');
+  }
+
+  const templatePath = path.join(PACKAGE_ROOT, 'templates', templateRelPath);
+  const localPath = path.join(projectRoot, '.claude', filePath);
+
+  if (!fs.existsSync(templatePath)) {
+    console.error(`Template file not found: ${templateRelPath}`);
+    process.exit(1);
+  }
+  if (!fs.existsSync(localPath)) {
+    console.log('Local file does not exist. Template content:');
+    console.log(fs.readFileSync(templatePath, 'utf-8'));
+    return;
+  }
+
+  try {
+    const output = execFileSync(
+      'git', ['diff', '--no-index', '--color', '--', templatePath, localPath],
+      { encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] }
+    );
+    console.log(output);
+  } catch (e) {
+    if (e.stdout) console.log(e.stdout);
+    else console.log('Files differ but git diff is unavailable.');
+  }
+}
+
+export async function cmdReset(args) {
+  const projectRoot = detectProjectRoot();
+  const filePath = args[0];
+
+  if (!filePath) {
+    console.error('Usage: orbital reset <relative-path>');
+    process.exit(1);
+  }
+
+  const mod = await loadSharedModule();
+  const manifest = mod.loadManifest(projectRoot);
+  if (!manifest) {
+    console.error('No manifest found. Run `orbital` first.');
+    process.exit(1);
+  }
+
+  const record = manifest.files[filePath];
+  if (!record || record.origin !== 'template') {
+    console.error(`Not a template file: ${filePath}`);
+    process.exit(1);
+  }
+
+  let templateRelPath = filePath;
+  if (filePath.startsWith('config/workflows/')) {
+    templateRelPath = filePath.replace('config/workflows/', 'presets/');
+  }
+
+  const templatePath = path.join(PACKAGE_ROOT, 'templates', templateRelPath);
+  const localPath = path.join(projectRoot, '.claude', filePath);
+
+  if (!fs.existsSync(templatePath)) {
+    console.error(`Template file not found: ${templateRelPath}`);
+    process.exit(1);
+  }
+
+  fs.copyFileSync(templatePath, localPath);
+  const newHash = mod.hashFile(localPath);
+  record.status = 'synced';
+  record.templateHash = newHash;
+  record.installedHash = newHash;
+  delete record.pinnedAt;
+  delete record.pinnedReason;
+
+  mod.saveManifest(projectRoot, manifest);
+  console.log(`Reset: ${filePath} → synced with template`);
+}