@avantmedia/af 0.0.1

package/commands/scaffold.ts

@@ -0,0 +1,105 @@
+import { existsSync, writeFileSync } from 'node:fs';
+import { error, success } from '../utils/output.ts';
+
+/**
+ * Docker Compose overlay file content for E2E testing.
+ * Adds migrate-seed init container that runs migrations before services start.
+ */
+const TEST_COMPOSE_CONTENT = `# Docker Compose overlay for E2E testing
+# Adds migrate-seed init container that runs migrations before services start
+#
+# Usage: docker compose -f docker-compose.yml -f docker-compose.test.yml --profile testing up -d --wait
+
+services:
+  migrate-seed:
+    profiles:
+      - testing
+    build:
+      context: .
+      dockerfile: Dockerfile.worker
+    command:
+      - bun
+      - run
+      - migrate-and-seed
+    working_dir: /code/apps/worker
+    restart: "no"
+    depends_on:
+      db:
+        condition: service_healthy
+    environment:
+      NODE_ENV: production
+      DB_HOST: db
+      DB_PORT: 5432
+      DB_NAME: postgres
+      DB_USER: postgres
+      DB_PASSWORD: u7-6wAaIR.2S
+      DB_NO_SSL: 1
+    networks:
+      - app-network
+
+  # Override hosting-server to wait for migrations
+  hosting-server:
+    depends_on:
+      db:
+        condition: service_healthy
+      migrate-seed:
+        condition: service_completed_successfully
+
+  # Override e2e to wait for migrations
+  e2e:
+    depends_on:
+      db:
+        condition: service_healthy
+      hosting-server:
+        condition: service_healthy
+      migrate-seed:
+        condition: service_completed_successfully
+    volumes:
+      - ./e2e/tests/visual-baselines:/workspace/tests/visual-baselines
+`;
+
+const OUTPUT_FILE = 'docker-compose.test.yml';
+
+/**
+ * Handle the 'scaffold test-compose' command.
+ * Generates a docker-compose.test.yml file for E2E testing.
+ *
+ * @returns Exit code (0 for success, 1 for error)
+ */
+export function handleScaffoldTestCompose(): number {
+    // Check if file already exists
+    if (existsSync(OUTPUT_FILE)) {
+        error(`${OUTPUT_FILE} already exists`);
+        return 1;
+    }
+
+    // Write the file
+    writeFileSync(OUTPUT_FILE, TEST_COMPOSE_CONTENT);
+    success(`Created ${OUTPUT_FILE}`);
+    return 0;
+}
+
+/**
+ * Handle the 'scaffold' command.
+ * Routes to the appropriate subcommand handler.
+ *
+ * @param args - Command arguments (subcommand and additional args)
+ * @returns Exit code (0 for success, 1 for error)
+ */
+export function handleScaffold(args: string[]): number {
+    const [subcommand] = args;
+
+    if (!subcommand) {
+        error('Error: scaffold command requires a subcommand');
+        console.error("Run 'af help scaffold' for more information.");
+        return 1;
+    }
+
+    if (subcommand === 'test-compose') {
+        return handleScaffoldTestCompose();
+    }
+
+    error(`Error: Unknown scaffold subcommand: ${subcommand}`);
+    console.error("Run 'af help scaffold' for available subcommands.");
+    return 1;
+}

package/commands/setup.tsx

@@ -0,0 +1,156 @@
+/**
+ * Setup command handler.
+ * Copies bundled configuration files to Claude and OpenCode directories.
+ */
+
+import { homedir } from 'node:os';
+import { render } from '../utils/ink-render.tsx';
+import { FileConflict } from '../components/file-conflict.tsx';
+import {
+    performSetup,
+    listSetupFiles,
+    getTargetDir,
+    getOpenCodeDir,
+    getSetupFileCount,
+    getOpenCodeCommandCount,
+    type ConflictResolution,
+} from '../utils/setup-files.ts';
+import { success, error, info, header, section, listItem, warn } from '../utils/output.ts';
+
+/**
+ * Prompt user for conflict resolution using interactive component.
+ */
+function promptConflict(targetPath: string): Promise<ConflictResolution> {
+    return new Promise(resolve => {
+        const { unmount } = render(
+            <FileConflict
+                filePath={targetPath}
+                onResolve={resolution => {
+                    unmount();
+                    resolve(resolution);
+                }}
+            />,
+        );
+    });
+}
+
+/**
+ * Format a path for display, replacing home directory with ~.
+ */
+function formatPath(path: string): string {
+    const home = homedir();
+    if (path.startsWith(home)) {
+        return path.replace(home, '~');
+    }
+    return path;
+}
+
+/**
+ * Handle the 'setup' command.
+ * Copies configuration files to ~/.claude/ and ~/.config/opencode/.
+ *
+ * Options:
+ *   --list, -l  List files that would be copied without copying
+ *   --force, -f Overwrite all existing files without prompting
+ *
+ * @param args - Command arguments
+ * @returns Exit code (0 for success, 1 for error)
+ */
+export async function handleSetup(args: string[]): Promise<number> {
+    // Parse flags
+    const forceFlag = args.includes('--force') || args.includes('-f');
+    const listFlag = args.includes('--list') || args.includes('-l');
+
+    const claudeDir = `${formatPath(getTargetDir())}/.claude`;
+    const openCodeDir = formatPath(getOpenCodeDir());
+
+    // List mode - show what would be copied
+    if (listFlag) {
+        header('Files to copy');
+        console.log();
+        info('Targets:');
+        listItem(`Claude: ${claudeDir} (commands + skills)`);
+        listItem(`OpenCode: ${openCodeDir} (commands only, skills shared)`);
+        console.log();
+
+        const files = listSetupFiles();
+
+        section('Claude files');
+        for (const { file, exists } of files) {
+            const status = exists ? ' (exists)' : '';
+            listItem(`${file.relativePath}${status}`);
+        }
+
+        // Show OpenCode command files
+        const commandFiles = files.filter(f => f.openCodePath);
+        if (commandFiles.length > 0) {
+            console.log();
+            section('OpenCode command files');
+            for (const { openCodePath, openCodeExists } of commandFiles) {
+                const status = openCodeExists ? ' (exists)' : '';
+                listItem(`${formatPath(openCodePath!)}${status}`);
+            }
+        }
+
+        const existingCount = files.filter(f => f.exists).length;
+        const openCodeExisting = commandFiles.filter(f => f.openCodeExists).length;
+        console.log();
+        info(
+            `${files.length} Claude files (${existingCount} exist), ` +
+                `${commandFiles.length} OpenCode files (${openCodeExisting} exist)`,
+        );
+
+        return 0;
+    }
+
+    // Perform setup
+    header('Setting up AI agent configurations');
+    console.log();
+    info('Targets:');
+    listItem(`Claude: ${claudeDir}`);
+    listItem(`OpenCode: ${openCodeDir} (commands only)`);
+    console.log();
+    info(`Files: ${getSetupFileCount()} Claude + ${getOpenCodeCommandCount()} OpenCode`);
+    console.log();
+
+    const result = await performSetup(async targetPath => {
+        if (forceFlag) {
+            return 'overwrite';
+        }
+        return promptConflict(targetPath);
+    });
+
+    // Report results
+    if (result.copied.length > 0) {
+        section('Copied files');
+        for (const path of result.copied) {
+            listItem(formatPath(path), '+');
+        }
+    }
+
+    if (result.skipped.length > 0) {
+        section('Skipped files');
+        for (const path of result.skipped) {
+            listItem(formatPath(path), '-');
+        }
+    }
+
+    if (result.errors.length > 0) {
+        section('Errors');
+        for (const { path, error: err } of result.errors) {
+            error(`  ${path}: ${err}`);
+        }
+        return 1;
+    }
+
+    console.log();
+    if (result.copied.length > 0) {
+        success(`Setup complete! ${result.copied.length} files copied.`);
+    } else if (result.skipped.length > 0) {
+        warn(`Setup complete. All ${result.skipped.length} files were skipped.`);
+    } else {
+        info('Nothing to do.');
+    }
+
+    return 0;
+}

package/commands/spec.ts

@@ -0,0 +1,405 @@
+import { spawn } from 'node:child_process';
+import { getAgentCommand } from '../utils/claude.ts';
+import {
+    hasChangesToCommit,
+    stageAllAndCommit,
+    stageAllAndCommitWithTrailers,
+    stageAndCommit,
+    stageDirectory,
+} from '../utils/git.ts';
+import { listOngoingChanges } from '../utils/openspec.ts';
+import { error, info, success, warn } from '../utils/output.ts';
+import { extractProposalTitle, getLatestChangeId } from '../utils/proposal.ts';
+
+/**
+ * Builds command arguments for the agent, conditionally adding Claude-specific flags.
+ *
+ * @param slashCommand - The OpenSpec slash command to execute
+ * @returns Array of command arguments
+ */
+function buildAgentArgs(slashCommand: string): string[] {
+    const agentCommand = getAgentCommand();
+
+    if (agentCommand === 'claude') {
+        return ['--permission-mode', 'acceptEdits', slashCommand];
+    }
+
+    if (agentCommand === 'copilot') {
+        return ['--allow-all-tools', '-p', slashCommand];
+    }
+
+    return [slashCommand];
+}
+
+/**
+ * Invoke Claude with the archive command for a specific spec-id.
+ *
+ * @param specId - The spec ID to archive
+ * @returns Exit code (0 for success, 1 for error)
+ */
+function invokeArchive(specId: string): Promise<number> {
+    // Extract the title from the proposal before archiving
+    const specDir = `openspec/changes/${specId}`;
+    const proposalPath = `${specDir}/proposal.md`;
+    const title = extractProposalTitle(proposalPath);
+
+    if (!title) {
+        warn('Warning: Could not extract proposal title for auto-commit');
+        return Promise.resolve(1);
+    }
+
+    const slashCommand = `/openspec:archive ${specId}`;
+    const claudeArgs = buildAgentArgs(slashCommand);
+    const claudeProcess = spawn(getAgentCommand(), claudeArgs, {
+        stdio: 'inherit',
+    });
+
+    return new Promise(resolve => {
+        claudeProcess.on('close', code => {
+            // If Claude process failed, return the error code
+            if (code !== 0) {
+                resolve(code ?? 1);
+                return;
+            }
+
+            const commitMessage = `Archive: ${title}`;
+            stageDirectory(`openspec/specs`);
+            stageDirectory(`openspec/changes/archive`);
+            const result = stageAndCommit(specDir, commitMessage);
+
+            if (!result.success) {
+                warn(`Warning: Failed to auto-commit archive: ${result.error}`);
+                warn('Archive completed but not committed. Please commit manually.');
+                resolve(0);
+                return;
+            }
+
+            success(`Archive committed: ${commitMessage}`);
+            resolve(0);
+        });
+
+        claudeProcess.on('error', err => {
+            error(`Error executing claude command: ${err.message}`);
+            resolve(1);
+        });
+    });
+}
+
+/**
+ * Handle the 'spec archive [spec-id]' command.
+ * Archives a spec by invoking Claude Code with the openspec:archive command.
+ * After successful archival, automatically commits the archived spec files.
+ *
+ * When spec-id is omitted:
+ * - 0 changes: Show error message
+ * - 1 change: Auto-select it
+ * - Multiple changes: Show interactive selection menu
+ *
+ * @param specId - Optional spec ID to archive
+ * @returns Exit code (0 for success, 1 for error)
+ */
+export async function handleSpecArchive(specId: string | undefined): Promise<number> {
+    // If specId is provided, invoke directly
+    if (specId) {
+        return invokeArchive(specId);
+    }
+
+    // No specId provided - check how many ongoing changes exist
+    const changes = listOngoingChanges();
+
+    if (changes.length === 0) {
+        error('No ongoing changes found');
+        return 1;
+    }
+
+    if (changes.length === 1) {
+        const selectedChange = changes[0];
+        info(`Auto-selected change: ${selectedChange.id}`);
+        return invokeArchive(selectedChange.id);
+    }
+
+    // Multiple changes - show interactive selection (uses dynamic import for .tsx)
+    const { renderChangeSelect } = await import('../utils/change-select-render.tsx');
+    const selectedId = await renderChangeSelect(changes, 'Select a change to archive:');
+
+    if (!selectedId) {
+        // User cancelled selection
+        return 0;
+    }
+
+    return invokeArchive(selectedId);
+}
+
+/**
+ * Invoke Claude with the apply command for a specific change-id.
+ *
+ * @param changeId - The change ID to apply
+ * @returns Exit code (0 for success, 1 for error)
+ */
+function invokeApply(changeId: string): Promise<number> {
+    const slashCommand = `/openspec:apply ${changeId}`;
+    const claudeArgs = buildAgentArgs(slashCommand);
+    const claudeProcess = spawn(getAgentCommand(), claudeArgs, {
+        stdio: 'inherit',
+    });
+
+    return new Promise(resolve => {
+        claudeProcess.on('close', code => {
+            resolve(code ?? 1);
+        });
+
+        claudeProcess.on('error', err => {
+            error(`Error executing claude command: ${err.message}`);
+            resolve(1);
+        });
+    });
+}
+
+/**
+ * Handle the 'spec apply [change-id]' command.
+ * Applies an approved OpenSpec change by invoking Claude Code with the openspec:apply command.
+ *
+ * When change-id is omitted:
+ * - 0 changes: Show error message
+ * - 1 change: Auto-select it
+ * - Multiple changes: Show interactive selection menu
+ *
+ * @param changeId - Optional change ID to apply
+ * @returns Exit code (0 for success, 1 for error)
+ */
+export async function handleSpecApply(changeId: string | undefined): Promise<number> {
+    // If changeId is provided, invoke directly
+    if (changeId) {
+        return invokeApply(changeId);
+    }
+
+    // No changeId provided - check how many ongoing changes exist
+    const changes = listOngoingChanges();
+
+    if (changes.length === 0) {
+        error('No ongoing changes found');
+        return 1;
+    }
+
+    if (changes.length === 1) {
+        const selectedChange = changes[0];
+        info(`Auto-selected change: ${selectedChange.id}`);
+        return invokeApply(selectedChange.id);
+    }
+
+    // Multiple changes - show interactive selection (uses dynamic import for .tsx)
+    const { renderChangeSelect } = await import('../utils/change-select-render.tsx');
+    const selectedId = await renderChangeSelect(changes, 'Select a change to apply:');
+
+    if (!selectedId) {
+        // User cancelled selection
+        return 0;
+    }
+
+    return invokeApply(selectedId);
+}
+
+/**
+ * Handle the 'spec propose <text>' command.
+ * Creates a new spec proposal by invoking Claude Code with the openspec:proposal command.
+ * After successful proposal creation, automatically commits the proposal files.
+ *
+ * @param proposalText - The proposal text
+ * @returns Exit code (0 for success, 1 for error)
+ */
+export async function handleSpecPropose(proposalText: string): Promise<number> {
+    // Validate that proposalText is provided
+    if (!proposalText || proposalText.trim() === '') {
+        error('Error: spec propose requires proposal text');
+        console.error('Usage: af spec propose <proposal-text>');
+        return 1;
+    }
+
+    // Build and execute the claude command
+    const claudeArgs = buildAgentArgs(`/openspec:proposal ${proposalText}`);
+    const claudeProcess = spawn(getAgentCommand(), claudeArgs, {
+        stdio: 'inherit', // Pipe stdout, stderr, and stdin to parent process
+    });
+
+    // Wait for the process to complete and return its status code
+    return new Promise(resolve => {
+        claudeProcess.on('close', code => {
+            // If Claude process failed, return the error code
+            if (code !== 0) {
+                resolve(code ?? 1);
+                return;
+            }
+
+            // Proposal created successfully, now auto-commit
+            const changeId = getLatestChangeId();
+            if (!changeId) {
+                warn('Warning: Could not determine change ID for auto-commit');
+                warn('Proposal created but not committed. Please commit manually.');
+                resolve(0);
+                return;
+            }
+
+            const proposalPath = `openspec/changes/${changeId}/proposal.md`;
+            const title = extractProposalTitle(proposalPath);
+            if (!title) {
+                warn('Warning: Could not extract proposal title for auto-commit');
+                warn('Proposal created but not committed. Please commit manually.');
+                resolve(0);
+                return;
+            }
+
+            const commitMessage = `Propose: ${title}`;
+            const changeDir = `openspec/changes/${changeId}`;
+            const result = stageAndCommit(changeDir, commitMessage);
+
+            if (!result.success) {
+                warn(`Warning: Failed to auto-commit proposal: ${result.error}`);
+                warn('Proposal created but not committed. Please commit manually.');
+                resolve(0);
+                return;
+            }
+
+            success(`Proposal committed: ${commitMessage}`);
+            resolve(0);
+        });
+
+        claudeProcess.on('error', err => {
+            error(`Error executing claude command: ${err.message}`);
+            resolve(1);
+        });
+    });
+}
+
+/**
+ * Commit all staged/unstaged changes with a message referencing the change title.
+ *
+ * @param changeId - The change ID to reference
+ * @returns Exit code (0 for success, 1 for error)
+ */
+function commitForChange(changeId: string): number {
+    const proposalPath = `openspec/changes/${changeId}/proposal.md`;
+    const title = extractProposalTitle(proposalPath);
+
+    if (!title) {
+        error('Error: Could not extract proposal title');
+        return 1;
+    }
+
+    const commitMessage = `Apply: ${title}`;
+    const result = stageAllAndCommit(commitMessage);
+
+    if (!result.success) {
+        error(`Error: ${result.error}`);
+        return 1;
+    }
+
+    success(`Committed: ${commitMessage}`);
+    return 0;
+}
+
+/**
+ * Handle the 'commit apply [change-id]' command.
+ * Commits all staged/unstaged changes with the message format: `Apply: <Change Title>`.
+ *
+ * When change-id is omitted:
+ * - 0 changes: Show error message
+ * - 1 change: Auto-select it
+ * - Multiple changes: Show interactive selection menu
+ *
+ * @param changeId - Optional change ID to commit for
+ * @returns Exit code (0 for success, 1 for error)
+ */
+export async function handleCommitApply(changeId: string | undefined): Promise<number> {
+    // If changeId is provided, commit directly
+    if (changeId) {
+        return commitForChange(changeId);
+    }
+
+    // No changeId provided - check how many ongoing changes exist
+    const changes = listOngoingChanges();
+
+    if (changes.length === 0) {
+        error('No ongoing changes found');
+        return 1;
+    }
+
+    if (changes.length === 1) {
+        const selectedChange = changes[0];
+        info(`Auto-selected change: ${selectedChange.id}`);
+        return commitForChange(selectedChange.id);
+    }
+
+    // Multiple changes - show interactive selection (uses dynamic import for .tsx)
+    const { renderChangeSelect } = await import('../utils/change-select-render.tsx');
+    const selectedId = await renderChangeSelect(changes, 'Select a change to commit for:');
+
+    if (!selectedId) {
+        // User cancelled selection
+        return 0;
+    }
+
+    return commitForChange(selectedId);
+}
+
+/**
+ * Parse a Key=Value argument into a trailer object.
+ *
+ * @param arg - The argument string in Key=Value format
+ * @returns Trailer object or null if not a valid Key=Value format
+ */
+function parseTrailer(arg: string): { key: string; value: string } | null {
+    const eqIndex = arg.indexOf('=');
+    if (eqIndex === -1) {
+        return null;
+    }
+    const key = arg.substring(0, eqIndex);
+    const value = arg.substring(eqIndex + 1);
+    if (!key || !value) {
+        return null;
+    }
+    return { key, value };
+}
+
+/**
+ * Handle the 'commit save "<message>" [Key=Value...]' command.
+ * Stages all changes and commits with the provided message.
+ * Additional arguments in Key=Value format are added as git trailers.
+ *
+ * @param message - The commit message
+ * @param trailerArgs - Additional arguments that may be Key=Value trailers
+ * @returns Exit code (0 for success, 1 for error)
+ */
+export function handleCommitSave(message: string | undefined, trailerArgs: string[]): number {
+    // Validate message is provided
+    if (!message || message.trim() === '') {
+        error('Error: commit save requires a message');
+        console.error('Usage: af commit save "<message>" [Key=Value...]');
+        return 1;
+    }
+
+    // Check if there are changes to commit
+    if (!hasChangesToCommit()) {
+        info('Nothing to commit');
+        return 0;
+    }
+
+    // Parse trailers from remaining arguments
+    const trailers: Array<{ key: string; value: string }> = [];
+    for (const arg of trailerArgs) {
+        const trailer = parseTrailer(arg);
+        if (trailer) {
+            trailers.push(trailer);
+        }
+    }
+
+    // Commit with trailers
+    const result = stageAllAndCommitWithTrailers(message, trailers);
+
+    if (!result.success) {
+        error(`Error: ${result.error}`);
+        return 1;
+    }
+
+    success(`Committed: ${message}`);
+    return 0;
+}