@avantmedia/af 0.0.1

package/commands/bun.ts

@@ -0,0 +1,55 @@
+import { getBunOutdatedPackages, bunUpgradeAllPackages } from '../bun-upgrade.ts';
+import { info, success, error, header, listItem } from '../utils/output.ts';
+
+/**
+ * Handle the 'bun upgrade' command.
+ * Checks for outdated packages and upgrades them all using Bun.
+ *
+ * @returns Exit code (0 for success, 1 for error)
+ */
+export async function handleBunUpgrade(): Promise<number> {
+    try {
+        info('Checking for outdated packages...');
+
+        const outdatedPackages = await getBunOutdatedPackages();
+
+        if (outdatedPackages.length === 0) {
+            success('All packages are up to date!');
+            return 0;
+        }
+
+        console.log(`\nFound ${outdatedPackages.length} package(s) to upgrade:`);
+        outdatedPackages.forEach(pkg => listItem(pkg));
+        console.log('');
+
+        const results = await bunUpgradeAllPackages(outdatedPackages);
+
+        // Display summary
+        const successful = results.filter(r => r.success);
+        const failed = results.filter(r => !r.success);
+
+        header('Upgrade Summary');
+        console.log('='.repeat(50));
+        console.log(`Successfully upgraded: ${successful.length} package(s)`);
+
+        if (successful.length > 0) {
+            successful.forEach(r => listItem(r.package, '✓'));
+        }
+
+        if (failed.length > 0) {
+            console.log(`\nFailed to upgrade: ${failed.length} package(s)`);
+            failed.forEach(r => listItem(`${r.package}: ${r.error}`, '✗'));
+            return 1;
+        }
+
+        success('\nAll packages upgraded successfully!');
+        return 0;
+    } catch (err) {
+        if (err instanceof Error) {
+            error(`Error: ${err.message}`);
+        } else {
+            error('An unexpected error occurred');
+        }
+        return 1;
+    }
+}

package/commands/changes.ts

@@ -0,0 +1,35 @@
+import { error, info } from '../utils/output.ts';
+import { getActiveChanges } from '../utils/proposal.ts';
+
+/**
+ * Handle the 'changes' command.
+ * Lists all OpenSpec changes with their titles and task progress.
+ *
+ * @param hasArgs - Whether any arguments were provided to the command
+ * @returns Exit code (0 for success, 1 for error)
+ */
+export async function handleChanges(hasArgs: boolean): Promise<number> {
+    // Reject if arguments were provided
+    if (hasArgs) {
+        error('Error: changes command does not accept arguments');
+        console.error('Usage: af changes');
+        return 1;
+    }
+
+    const changes = getActiveChanges();
+
+    if (changes.length === 0) {
+        info('No active changes');
+        return 0;
+    }
+
+    console.log('Changes:');
+
+    for (const change of changes) {
+        const displayName = change.title ? `${change.title} (${change.id})` : change.id;
+        const taskProgress = `${change.completedTasks}/${change.totalTasks} tasks`;
+        console.log(`  ${displayName}     ${taskProgress}`);
+    }
+
+    return 0;
+}

package/commands/e2e.ts

@@ -0,0 +1,12 @@
+import { runE2eTests } from '../scripts/e2e_tests.ts';
+
+/**
+ * Handle the 'e2e' command.
+ * Runs e2e tests directly with any provided arguments.
+ *
+ * @param args - Arguments to pass through to the test runner
+ * @returns Exit code from the test runner
+ */
+export async function handleE2e(args: string[]): Promise<number> {
+    return await runE2eTests(args);
+}

package/commands/help.ts

@@ -0,0 +1,236 @@
+import { header, section, listItem, error } from '../utils/output.ts';
+
+/**
+ * Help content for all commands
+ */
+const HELP_CONTENT: Record<string, { description: string; usage: string; examples?: string[] }> = {
+    npm: {
+        description: 'Manage npm packages',
+        usage: 'af npm upgrade',
+        examples: ['af npm upgrade  # Upgrade all outdated npm packages'],
+    },
+    bun: {
+        description: 'Manage Bun packages',
+        usage: 'af bun upgrade',
+        examples: ['af bun upgrade  # Upgrade all outdated Bun packages'],
+    },
+    spec: {
+        description: 'Manage OpenSpec changes',
+        usage: 'af spec <subcommand> [args]',
+        examples: [
+            'af spec propose "Add new feature"  # Create a new proposal',
+            'af spec apply my-change-id         # Apply a change',
+            'af spec apply                      # Interactively select a change',
+            'af spec archive my-change-id       # Archive a change',
+            'af spec archive                    # Interactively select a spec',
+        ],
+    },
+    propose: {
+        description: 'Create a new OpenSpec proposal (shorthand for "spec propose")',
+        usage: 'af propose <proposal-text>',
+        examples: ['af propose "Add dark mode support"'],
+    },
+    apply: {
+        description: 'Apply an approved OpenSpec change (shorthand for "spec apply")',
+        usage: 'af apply [change-id]',
+        examples: [
+            'af apply my-change-id  # Apply a specific change',
+            'af apply               # Interactively select a change',
+        ],
+    },
+    archive: {
+        description: 'Archive an OpenSpec change (shorthand for "spec archive")',
+        usage: 'af archive [spec-id]',
+        examples: [
+            'af archive my-change-id  # Archive a specific spec',
+            'af archive               # Interactively select a spec',
+        ],
+    },
+    commit: {
+        description: 'Commit changes with message and optional trailers',
+        usage: 'af commit <subcommand> [args]',
+        examples: [
+            'af commit save "Fix bug"                    # Commit with message',
+            'af commit save "Fix bug" Issue=PROJ-123     # Commit with Issue trailer',
+            'af commit save "Add feature" Issue=PROJ-456 Reviewed-by=alice',
+            'af commit my-change-id                      # Commit with "Apply: <title>"',
+            'af commit apply my-change-id                # Same as above',
+        ],
+    },
+    changes: {
+        description: 'List all OpenSpec changes',
+        usage: 'af changes',
+        examples: ['af changes  # Show all active OpenSpec changes'],
+    },
+    e2e: {
+        description: 'Run E2E tests in a fresh Docker environment',
+        usage: 'af e2e [args...]',
+        examples: [
+            'af e2e                                        # Run all tests with defaults',
+            'af e2e npm run e2e -- --grep "booking"   # Custom command',
+        ],
+    },
+    'stop-hook': {
+        description: 'Conditionally run e2e tests if relevant files changed',
+        usage: 'af stop-hook',
+        examples: ['af stop-hook  # Run e2e only if source files changed (not just openspec/)'],
+    },
+    todo: {
+        description: 'Show all TODO items from active OpenSpec changes',
+        usage: 'af todo',
+        examples: ['af todo  # Display all tasks from active changes'],
+    },
+    watch: {
+        description:
+            'Continuously monitor and display TODO items from active changes with idle indicator',
+        usage: 'af watch',
+        examples: [
+            'af watch  # Start watch mode for real-time TODO updates',
+            '          # Shows idle warning after 60 seconds of inactivity',
+        ],
+    },
+    versions: {
+        description: 'Manage version worktrees',
+        usage: 'af versions <subcommand>',
+        examples: [
+            'af versions reset  # Reset all version worktrees to HEAD',
+            'af versions push   # Force push all version worktrees',
+        ],
+    },
+    jira: {
+        description: 'Manage Jira issues from the command line',
+        usage: 'af jira <subcommand> [args] [options]',
+        examples: [
+            'af jira get PROJ-123              # Get issue details',
+            'af jira list PROJ --limit 20     # List project issues',
+            'af jira search "status = Open"   # Search with JQL',
+            'af jira create --project PROJ --type Bug --summary "Title"',
+            'af jira projects                  # List all projects',
+        ],
+    },
+    licenses: {
+        description: 'Show license and copyright information',
+        usage: 'af licenses',
+        examples: ['af licenses  # Display copyright and license details'],
+    },
+    scaffold: {
+        description: 'Generate project files from templates',
+        usage: 'af scaffold <subcommand>',
+        examples: ['af scaffold test-compose  # Generate docker-compose.test.yml for E2E testing'],
+    },
+    setup: {
+        description: 'Copy configuration files to Claude and OpenCode directories',
+        usage: 'af setup [--list] [--force]',
+        examples: [
+            'af setup              # Copy to ~/.claude/ and ~/.config/opencode/',
+            'af setup --list       # Preview files without copying',
+            'af setup --force      # Overwrite existing files',
+        ],
+    },
+    'install-extension': {
+        description: 'Install the OpenSpec Tasks VSCode extension',
+        usage: 'af install-extension',
+        examples: ['af install-extension  # Install the bundled VSCode extension'],
+    },
+    worktree: {
+        description: 'Manage git worktrees',
+        usage: 'af worktree <subcommand> [args]',
+        examples: [
+            'af worktree new feature-x        # Create worktree with new branch',
+            'af worktree new hotfix --detach  # Create worktree with detached HEAD',
+            'af worktree reset                # Reset current worktree to HEAD',
+            'af worktree reset feature-x      # Reset named worktree to HEAD',
+        ],
+    },
+    help: {
+        description: 'Display help information',
+        usage: 'af help [command]',
+        examples: ['af help        # Show all commands', 'af help npm    # Show npm help'],
+    },
+};
+
+/**
+ * Display general help showing all available commands.
+ */
+function showGeneralHelp(): void {
+    header('af - Development utility CLI');
+
+    section('USAGE');
+    console.log('  af <command> [options]');
+
+    section('COMMANDS');
+    listItem('npm upgrade            Upgrade all outdated npm packages');
+    listItem('bun upgrade            Upgrade all outdated Bun packages');
+    listItem('spec propose <text>    Create a new OpenSpec proposal');
+    listItem('spec apply [id]        Apply an approved OpenSpec change');
+    listItem('spec archive [id]      Archive an OpenSpec change');
+    listItem('propose <text>         Shorthand for "spec propose"');
+    listItem('apply [id]             Shorthand for "spec apply"');
+    listItem('archive [id]           Shorthand for "spec archive"');
+    listItem('commit save <msg>      Commit all changes with message and trailers');
+    listItem('commit [apply] [id]    Commit all changes with "Apply: <title>"');
+    listItem('changes                List all OpenSpec changes');
+    listItem('e2e [args...]          Run E2E tests in Docker');
+    listItem('stop-hook              Run e2e only if relevant files changed');
+    listItem('todo                   Show all TODO items from active changes');
+    listItem('watch                  Continuously show updated TODO items (with idle indicator)');
+    listItem('versions reset         Reset version worktrees to HEAD');
+    listItem('versions push          Force push version worktrees');
+    listItem('jira <subcommand>      Manage Jira issues (get, list, create, etc.)');
+    listItem('licenses               Show license and copyright information');
+    listItem('scaffold <subcommand>  Generate project files from templates');
+    listItem('setup                  Copy Claude + OpenCode config files');
+    listItem('install-extension      Install VSCode extension');
+    listItem('worktree new <name>    Create new worktree with env files');
+    listItem('worktree reset [name]  Reset worktree to HEAD');
+    listItem('help [command]         Show help for a command');
+
+    section('OPTIONS');
+    listItem('--help, -h            Show help information');
+
+    console.log("\nRun 'af help <command>' for more information on a command.");
+}
+
+/**
+ * Display help for a specific command.
+ *
+ * @param command - The command to show help for
+ */
+function showCommandHelp(command: string): void {
+    const helpInfo = HELP_CONTENT[command];
+
+    if (!helpInfo) {
+        error(`Unknown command: ${command}`);
+        console.log("\nRun 'af help' to see all available commands.");
+        return;
+    }
+
+    header(`af ${command}`);
+
+    section('DESCRIPTION');
+    console.log(`  ${helpInfo.description}`);
+
+    section('USAGE');
+    console.log(`  ${helpInfo.usage}`);
+
+    if (helpInfo.examples && helpInfo.examples.length > 0) {
+        section('EXAMPLES');
+        helpInfo.examples.forEach(example => console.log(`  ${example}`));
+    }
+}
+
+/**
+ * Handle the 'help' command.
+ * Displays general help or command-specific help.
+ *
+ * @param command - Optional command to show help for
+ * @returns Exit code (always 0)
+ */
+export async function handleHelp(command?: string): Promise<number> {
+    if (command) {
+        showCommandHelp(command);
+    } else {
+        showGeneralHelp();
+    }
+    return 0;
+}

package/commands/install-extension.ts

@@ -0,0 +1,133 @@
+/**
+ * Install extension command handler.
+ * Installs the bundled VSCode extension from the embedded VSIX file.
+ */
+
+import { spawn } from 'node:child_process';
+import { copyFileSync, unlinkSync, mkdtempSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, dirname } from 'node:path';
+import { EXTENSION_FILE, isCompiled } from '../generated/setup-manifest.ts';
+import { success, error, info } from '../utils/output.ts';
+
+/**
+ * Check if VSCode CLI is available.
+ */
+async function isCodeCliAvailable(): Promise<boolean> {
+    return new Promise(resolve => {
+        const child = spawn('code', ['--version'], { stdio: 'pipe' });
+        child.on('error', () => resolve(false));
+        child.on('close', code => resolve(code === 0));
+    });
+}
+
+/**
+ * Install extension using VSCode CLI.
+ */
+async function installExtension(vsixPath: string): Promise<{ success: boolean; output: string }> {
+    return new Promise(resolve => {
+        const child = spawn('code', ['--install-extension', vsixPath], {
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+
+        let stdout = '';
+        let stderr = '';
+
+        child.stdout?.on('data', data => {
+            stdout += data.toString();
+        });
+
+        child.stderr?.on('data', data => {
+            stderr += data.toString();
+        });
+
+        child.on('error', err => {
+            resolve({ success: false, output: err.message });
+        });
+
+        child.on('close', code => {
+            if (code === 0) {
+                resolve({ success: true, output: stdout });
+            } else {
+                resolve({ success: false, output: stderr || stdout });
+            }
+        });
+    });
+}
+
+/**
+ * Handle the 'install-extension' command.
+ * Installs the bundled VSCode extension.
+ *
+ * @returns Exit code (0 for success, 1 for error)
+ */
+export async function handleInstallExtension(): Promise<number> {
+    // Check if extension file is available
+    if (!EXTENSION_FILE) {
+        error('Error: No extension file bundled');
+        console.error('The VSCode extension file is not available.');
+        return 1;
+    }
+
+    // Check if VSCode CLI is available
+    info('Checking for VSCode CLI...');
+    const codeAvailable = await isCodeCliAvailable();
+
+    if (!codeAvailable) {
+        error('Error: VSCode CLI not found');
+        console.error('The "code" command is not available. Please ensure VSCode is installed');
+        console.error('and the "code" command is in your PATH.');
+        console.error('');
+        console.error('To add the "code" command to PATH:');
+        console.error('  1. Open VSCode');
+        console.error('  2. Press Cmd+Shift+P (macOS) or Ctrl+Shift+P (Windows/Linux)');
+        console.error('  3. Type "Shell Command: Install \'code\' command in PATH"');
+        return 1;
+    }
+
+    // Create temp directory and copy VSIX file
+    info(`Installing ${EXTENSION_FILE.name}...`);
+    const tempDir = mkdtempSync(join(tmpdir(), 'artifex-extension-'));
+    const tempVsixPath = join(tempDir, EXTENSION_FILE.name);
+
+    try {
+        // Copy embedded file to temp location
+        if (isCompiled()) {
+            // In compiled mode, use Bun.file() to read from $bunfs virtual filesystem
+            const content = await Bun.file(EXTENSION_FILE.embeddedPath).bytes();
+            writeFileSync(tempVsixPath, content);
+        } else {
+            // In development mode, copy from source directory
+            const sourcePath = join(
+                dirname(import.meta.dirname),
+                'vscode-extension',
+                EXTENSION_FILE.name,
+            );
+            copyFileSync(sourcePath, tempVsixPath);
+        }
+
+        // Install the extension
+        const result = await installExtension(tempVsixPath);
+
+        if (result.success) {
+            success('Extension installed successfully!');
+            if (result.output.trim()) {
+                console.log(result.output.trim());
+            }
+            return 0;
+        } else {
+            error('Error: Extension installation failed');
+            if (result.output.trim()) {
+                console.error(result.output.trim());
+            }
+            return 1;
+        }
+    } finally {
+        // Clean up temp file
+        try {
+            unlinkSync(tempVsixPath);
+        } catch {
+            // Ignore cleanup errors
+        }
+    }
+}