flight-rules 0.5.9

package/dist/commands/init.js

@@ -0,0 +1,197 @@
+import * as p from '@clack/prompts';
+import pc from 'picocolors';
+import { isFlightRulesInstalled, fetchPayloadFromGitHub, copyPayloadFrom, getFlightRulesDir, ensureDir, writeManifest, getCliVersion } from '../utils/files.js';
+import { isInteractive } from '../utils/interactive.js';
+import { cpSync, existsSync } from 'fs';
+import { join } from 'path';
+const DOC_FILES = [
+    { src: 'prd.md', dest: 'prd.md' },
+    { src: 'progress.md', dest: 'progress.md' },
+    { src: 'critical-learnings.md', dest: 'critical-learnings.md' },
+    { src: 'implementation/overview.md', dest: 'implementation/overview.md' },
+    { src: 'tech-stack.md', dest: 'tech-stack.md' },
+];
+async function copyDocsFromTemplates(templatesDir, docsDir, skipExisting) {
+    ensureDir(docsDir);
+    ensureDir(join(docsDir, 'implementation'));
+    ensureDir(join(docsDir, 'session_logs'));
+    for (const file of DOC_FILES) {
+        const srcPath = join(templatesDir, file.src);
+        const destPath = join(docsDir, file.dest);
+        if (!existsSync(srcPath))
+            continue;
+        if (skipExisting && existsSync(destPath)) {
+            continue;
+        }
+        cpSync(srcPath, destPath);
+    }
+}
+export async function init() {
+    const cwd = process.cwd();
+    const interactive = isInteractive();
+    // Check if already installed
+    if (isFlightRulesInstalled(cwd)) {
+        if (interactive) {
+            const shouldContinue = await p.confirm({
+                message: 'Flight Rules is already installed. Do you want to reinstall? (This will overwrite existing files)',
+                initialValue: false,
+            });
+            if (p.isCancel(shouldContinue) || !shouldContinue) {
+                p.log.info('Installation cancelled.');
+                p.outro('Run `flight-rules upgrade` to update framework files while preserving your docs.');
+                return;
+            }
+        }
+        else {
+            // Non-interactive: skip reinstall (safe default)
+            p.log.info('Flight Rules is already installed. Skipping reinstall.');
+            p.outro('Run `flight-rules upgrade` to update framework files while preserving your docs.');
+            return;
+        }
+    }
+    const spinner = p.spinner();
+    // Fetch from GitHub
+    spinner.start('Fetching latest Flight Rules from GitHub...');
+    let fetched;
+    try {
+        fetched = await fetchPayloadFromGitHub();
+        spinner.stop(`Found Flight Rules version ${pc.cyan(fetched.version)}`);
+    }
+    catch (error) {
+        spinner.stop('Failed to fetch from GitHub');
+        if (error instanceof Error) {
+            p.log.error(error.message);
+        }
+        p.outro('Check your network connection and try again.');
+        return;
+    }
+    // Copy payload
+    spinner.start('Installing Flight Rules...');
+    try {
+        copyPayloadFrom(fetched.payloadPath, cwd);
+        // Write manifest to track deployed version
+        writeManifest(cwd, {
+            version: fetched.version,
+            deployedAt: new Date().toISOString(),
+            deployedBy: {
+                cli: getCliVersion(),
+                command: 'init',
+            },
+        });
+        spinner.stop('Flight Rules installed!');
+    }
+    catch (error) {
+        spinner.stop('Failed to install Flight Rules');
+        fetched.cleanup();
+        throw error;
+    }
+    fetched.cleanup();
+    // Ask about initializing docs
+    let initDocs;
+    if (interactive) {
+        const initDocsResult = await p.confirm({
+            message: 'Would you like to initialize project docs from templates?',
+            initialValue: true,
+        });
+        if (p.isCancel(initDocsResult)) {
+            p.outro('Flight Rules installed. Run `flight-rules adapter` to generate agent adapters.');
+            return;
+        }
+        initDocs = initDocsResult;
+    }
+    else {
+        // Non-interactive: default to yes (create docs)
+        initDocs = true;
+    }
+    if (initDocs) {
+        const flightRulesDir = getFlightRulesDir(cwd);
+        const templatesDir = join(flightRulesDir, 'doc-templates');
+        const docsDir = join(cwd, 'docs');
+        // Check if docs directory already exists with content
+        const docsExist = existsSync(docsDir);
+        let skipExisting = false;
+        if (docsExist) {
+            if (interactive) {
+                const handleExisting = await p.select({
+                    message: 'A docs/ directory already exists. How would you like to proceed?',
+                    options: [
+                        { value: 'skip', label: 'Skip existing files', hint: 'only create missing files' },
+                        { value: 'overwrite', label: 'Overwrite existing files' },
+                        { value: 'cancel', label: 'Cancel docs initialization' },
+                    ],
+                });
+                if (p.isCancel(handleExisting) || handleExisting === 'cancel') {
+                    p.log.info('Skipped docs initialization.');
+                }
+                else {
+                    skipExisting = handleExisting === 'skip';
+                    await copyDocsFromTemplates(templatesDir, docsDir, skipExisting);
+                    p.log.success('Project docs initialized from templates.');
+                }
+            }
+            else {
+                // Non-interactive: skip existing files (safe default)
+                skipExisting = true;
+                await copyDocsFromTemplates(templatesDir, docsDir, skipExisting);
+                p.log.success('Project docs initialized from templates (skipped existing files).');
+            }
+        }
+        else {
+            await copyDocsFromTemplates(templatesDir, docsDir, false);
+            p.log.success('Project docs initialized from templates.');
+        }
+    }
+    // Ask about generating adapters
+    if (interactive) {
+        const generateAdaptersResult = await p.confirm({
+            message: 'Would you like to generate agent adapter files?',
+            initialValue: true,
+        });
+        if (p.isCancel(generateAdaptersResult)) {
+            p.outro('Done! Your project now has Flight Rules.');
+            return;
+        }
+        if (generateAdaptersResult) {
+            const adapters = await p.multiselect({
+                message: 'Which adapters would you like to generate?',
+                options: [
+                    { value: 'cursor', label: 'Cursor (AGENTS.md + .cursor/commands/)', hint: 'recommended' },
+                    { value: 'claude', label: 'Claude Code (CLAUDE.md + .claude/commands/)' },
+                ],
+                initialValues: ['cursor'],
+            });
+            if (p.isCancel(adapters)) {
+                p.outro('Done! Your project now has Flight Rules.');
+                return;
+            }
+            // Import and run adapter generation
+            const { generateAdapters: genAdapters } = await import('./adapter.js');
+            await genAdapters(adapters);
+        }
+    }
+    else {
+        // Non-interactive: skip adapter generation (user can run `flight-rules adapter` separately)
+        p.log.info('Skipping adapter generation. Run `flight-rules adapter --cursor` or `--claude` to generate adapters.');
+    }
+    // Ask about installing .editorconfig
+    const editorConfigPath = join(cwd, '.editorconfig');
+    const editorConfigExists = existsSync(editorConfigPath);
+    if (!editorConfigExists) {
+        if (interactive) {
+            const installEditorConfig = await p.confirm({
+                message: 'Would you like to add a standard .editorconfig? (helps prevent formatting diffs)',
+                initialValue: true,
+            });
+            if (!p.isCancel(installEditorConfig) && installEditorConfig) {
+                const flightRulesDir = getFlightRulesDir(cwd);
+                const srcEditorConfig = join(flightRulesDir, '.editorconfig');
+                if (existsSync(srcEditorConfig)) {
+                    cpSync(srcEditorConfig, editorConfigPath);
+                    p.log.success('Added .editorconfig to project root.');
+                }
+            }
+        }
+        // Non-interactive: skip .editorconfig installation (safe default)
+    }
+    p.outro(pc.green('Flight Rules is ready! Start with: "start coding session"'));
+}

package/dist/commands/upgrade.d.ts

@@ -0,0 +1 @@
+export declare function upgrade(version?: string): Promise<void>;

package/dist/commands/upgrade.js

@@ -0,0 +1,255 @@
+import * as p from '@clack/prompts';
+import pc from 'picocolors';
+import { existsSync, cpSync } from 'fs';
+import { join } from 'path';
+import { isFlightRulesInstalled, fetchPayloadFromGitHub, copyFrameworkFilesFrom, ensureDir, getInstalledVersion, writeManifest, getCliVersion } from '../utils/files.js';
+import { isInteractive } from '../utils/interactive.js';
+import { isCursorAdapterInstalled, isClaudeAdapterInstalled, setupCursorCommands, setupClaudeCommands, } from './adapter.js';
+const DOC_FILES = [
+    { src: 'prd.md', dest: 'prd.md' },
+    { src: 'progress.md', dest: 'progress.md' },
+    { src: 'critical-learnings.md', dest: 'critical-learnings.md' },
+    { src: 'implementation/overview.md', dest: 'implementation/overview.md' },
+    { src: 'tech-stack.md', dest: 'tech-stack.md' },
+];
+/**
+ * Copy new doc templates to docs/ without overwriting existing files.
+ * Returns the list of files that were copied.
+ */
+function copyNewDocsFromTemplates(templatesDir, docsDir) {
+    ensureDir(docsDir);
+    ensureDir(join(docsDir, 'implementation'));
+    ensureDir(join(docsDir, 'session_logs'));
+    const copied = [];
+    for (const file of DOC_FILES) {
+        const srcPath = join(templatesDir, file.src);
+        const destPath = join(docsDir, file.dest);
+        if (!existsSync(srcPath))
+            continue;
+        // Only copy if destination doesn't exist
+        if (!existsSync(destPath)) {
+            cpSync(srcPath, destPath);
+            copied.push(file.dest);
+        }
+    }
+    return copied;
+}
+export async function upgrade(version) {
+    const cwd = process.cwd();
+    // Check if Flight Rules is installed
+    if (!isFlightRulesInstalled(cwd)) {
+        p.log.error('Flight Rules is not installed in this directory.');
+        p.outro('Run `flight-rules init` to install Flight Rules first.');
+        return;
+    }
+    // Get current installed version
+    const currentVersion = getInstalledVersion(cwd);
+    // Detect installed adapters before upgrade
+    const cursorAdapterInstalled = isCursorAdapterInstalled(cwd);
+    const claudeAdapterInstalled = isClaudeAdapterInstalled(cwd);
+    const agentsMdExists = existsSync(join(cwd, 'AGENTS.md'));
+    const claudeMdExists = existsSync(join(cwd, 'CLAUDE.md'));
+    // Show what will be upgraded
+    p.log.info(`${pc.bold('The .flight-rules/ directory will be upgraded.')}`);
+    p.log.message('  Framework files (AGENTS.md, doc-templates/, commands/, prompts/) will be replaced.');
+    console.log();
+    // Show adapter upgrade info
+    const adaptersToUpgrade = [];
+    if (cursorAdapterInstalled) {
+        adaptersToUpgrade.push('Cursor (.cursor/commands/)');
+    }
+    if (claudeAdapterInstalled) {
+        adaptersToUpgrade.push('Claude Code (.claude/commands/)');
+    }
+    else if (claudeMdExists) {
+        // CLAUDE.md exists but .claude/commands/ doesn't - will be created on upgrade
+        adaptersToUpgrade.push('Claude Code (.claude/commands/ will be created)');
+    }
+    if (agentsMdExists) {
+        adaptersToUpgrade.push('AGENTS.md');
+    }
+    if (claudeMdExists && !adaptersToUpgrade.some(a => a.includes('Claude Code'))) {
+        adaptersToUpgrade.push('CLAUDE.md');
+    }
+    if (adaptersToUpgrade.length > 0) {
+        p.log.info(`${pc.bold('Installed adapters will also be upgraded:')}`);
+        p.log.message(`  ${adaptersToUpgrade.join(', ')}`);
+        console.log();
+    }
+    p.log.info(`${pc.bold('Your project content will be preserved.')}`);
+    p.log.message('  New templates may be added to docs/, but existing files are never modified.');
+    console.log();
+    const spinner = p.spinner();
+    // Fetch from GitHub
+    spinner.start(version ? `Fetching Flight Rules ${version} from GitHub...` : 'Fetching latest Flight Rules from GitHub...');
+    let fetched;
+    try {
+        fetched = await fetchPayloadFromGitHub(version);
+        spinner.stop(`Found Flight Rules version ${pc.cyan(fetched.version)}`);
+    }
+    catch (error) {
+        spinner.stop('Failed to fetch from GitHub');
+        if (error instanceof Error) {
+            p.log.error(error.message);
+        }
+        p.outro('Check your network connection and try again.');
+        return;
+    }
+    // Show version comparison
+    if (currentVersion) {
+        p.log.info(`Current version: ${pc.yellow(currentVersion)} → ${pc.cyan(fetched.version)}`);
+    }
+    if (isInteractive()) {
+        const shouldContinue = await p.confirm({
+            message: `Upgrade to version ${fetched.version}?`,
+            initialValue: true,
+        });
+        if (p.isCancel(shouldContinue) || !shouldContinue) {
+            fetched.cleanup();
+            p.log.info('Upgrade cancelled.');
+            return;
+        }
+    }
+    else {
+        // Non-interactive: proceed with upgrade
+        p.log.info(`Upgrading to version ${fetched.version}...`);
+    }
+    // Upgrade .flight-rules/
+    spinner.start('Upgrading Flight Rules...');
+    try {
+        copyFrameworkFilesFrom(fetched.payloadPath, cwd);
+        // Write manifest to track deployed version
+        writeManifest(cwd, {
+            version: fetched.version,
+            deployedAt: new Date().toISOString(),
+            deployedBy: {
+                cli: getCliVersion(),
+                command: 'upgrade',
+            },
+        });
+        spinner.stop('Flight Rules framework upgraded!');
+    }
+    catch (error) {
+        spinner.stop('Failed to upgrade Flight Rules');
+        fetched.cleanup();
+        throw error;
+    }
+    p.log.success('Framework files have been updated.');
+    // Add new doc templates to docs/ (without overwriting existing files)
+    const templatesDir = join(fetched.payloadPath, 'doc-templates');
+    const docsDir = join(cwd, 'docs');
+    const newDocs = copyNewDocsFromTemplates(templatesDir, docsDir);
+    if (newDocs.length > 0) {
+        p.log.success(`Added ${newDocs.length} new template(s) to docs/: ${newDocs.join(', ')}`);
+    }
+    // Upgrade installed adapters
+    if (adaptersToUpgrade.length > 0) {
+        spinner.start('Upgrading adapters...');
+        try {
+            const sourceCommandsDir = join(fetched.payloadPath, 'commands');
+            // Upgrade Cursor commands if installed
+            if (cursorAdapterInstalled) {
+                const result = await setupCursorCommands(cwd, sourceCommandsDir, true); // skipPrompts = true for upgrade
+                if (result.copied.length > 0) {
+                    p.log.success(`Updated ${result.copied.length} command(s) in .cursor/commands/`);
+                }
+            }
+            // Upgrade Claude commands if installed, or create them if CLAUDE.md exists but .claude/commands/ doesn't
+            // (handles upgrade from pre-0.5.4 where Claude didn't have native commands)
+            if (claudeAdapterInstalled || claudeMdExists) {
+                const result = await setupClaudeCommands(cwd, sourceCommandsDir, true); // skipPrompts = true for upgrade
+                if (result.copied.length > 0) {
+                    const action = claudeAdapterInstalled ? 'Updated' : 'Created';
+                    p.log.success(`${action} ${result.copied.length} command(s) in .claude/commands/`);
+                }
+            }
+            // Regenerate adapter files
+            const adaptersToRegenerate = [];
+            if (agentsMdExists) {
+                adaptersToRegenerate.push('cursor');
+            }
+            if (claudeMdExists) {
+                adaptersToRegenerate.push('claude');
+            }
+            if (adaptersToRegenerate.length > 0) {
+                // For upgrade, we regenerate silently (the files already exist, so we just overwrite)
+                for (const adapterName of adaptersToRegenerate) {
+                    await regenerateAdapterFile(cwd, adapterName, sourceCommandsDir);
+                }
+            }
+            spinner.stop('Adapters upgraded!');
+        }
+        catch (error) {
+            spinner.stop('Failed to upgrade adapters');
+            fetched.cleanup();
+            throw error;
+        }
+    }
+    fetched.cleanup();
+    p.outro(pc.green('Upgrade complete!'));
+}
+/**
+ * Regenerate a single adapter file during upgrade (no prompts, just overwrite)
+ */
+async function regenerateAdapterFile(cwd, adapterName, _sourceCommandsDir) {
+    // Import the adapter config and content generator
+    const { writeFileSync } = await import('fs');
+    const { join } = await import('path');
+    const ADAPTERS = {
+        cursor: {
+            filename: 'AGENTS.md',
+            title: 'Flight Rules – Cursor Adapter',
+            description: 'This file is placed at the project root as `AGENTS.md` for Cursor compatibility.',
+            hasNativeCommands: true,
+            commandsDirectory: '.cursor/commands',
+        },
+        claude: {
+            filename: 'CLAUDE.md',
+            title: 'Flight Rules – Claude Code Adapter',
+            description: 'This file is placed at the project root as `CLAUDE.md` for Claude Code compatibility.',
+            hasNativeCommands: true,
+            commandsDirectory: '.claude/commands',
+        },
+    };
+    const config = ADAPTERS[adapterName];
+    if (!config)
+        return;
+    const commandLocation = config.hasNativeCommands && config.commandsDirectory
+        ? `\`${config.commandsDirectory}/\` (as slash commands)`
+        : `\`.flight-rules/commands/\``;
+    const commandInstructions = config.hasNativeCommands
+        ? `Use the \`/dev-session.start\` and \`/dev-session.end\` slash commands.`
+        : `When the user says "start coding session" or "end coding session", follow the instructions in \`.flight-rules/commands/\`.`;
+    const content = `# ${config.title}
+
+${config.description}
+
+---
+
+**This project uses Flight Rules.**
+
+Agent guidelines and workflows live in \`.flight-rules/\`. Project documentation lives in \`docs/\`.
+
+## Quick Reference
+
+| What | Where |
+|------|-------|
+| Agent Guidelines | \`.flight-rules/AGENTS.md\` |
+| PRD | \`docs/prd.md\` |
+| Implementation Specs | \`docs/implementation/\` |
+| Progress Log | \`docs/progress.md\` |
+| Session Commands | ${commandLocation} |
+
+## For Agents
+
+Please read \`.flight-rules/AGENTS.md\` for complete guidelines on:
+- Project structure
+- Implementation specs
+- Coding sessions
+- How to work with this system
+
+${commandInstructions}
+`;
+    const filePath = join(cwd, config.filename);
+    writeFileSync(filePath, content, 'utf-8');
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,83 @@
+#!/usr/bin/env node
+import * as p from '@clack/prompts';
+import pc from 'picocolors';
+import { init } from './commands/init.js';
+import { upgrade } from './commands/upgrade.js';
+import { adapter } from './commands/adapter.js';
+import { getCliVersion } from './utils/files.js';
+const command = process.argv[2];
+const args = process.argv.slice(3);
+/**
+ * Parse --version flag from args, returning the version value if present
+ */
+function parseVersionArg(args) {
+    const versionIndex = args.findIndex(arg => arg === '--version' || arg === '-V');
+    if (versionIndex !== -1 && args[versionIndex + 1]) {
+        return args[versionIndex + 1];
+    }
+    // Also support --version=0.1.4 format
+    const versionArg = args.find(arg => arg.startsWith('--version='));
+    if (versionArg) {
+        return versionArg.split('=')[1];
+    }
+    return undefined;
+}
+async function main() {
+    // Handle --version early, without intro banner
+    if (command === '--version' || command === '-v') {
+        console.log(getCliVersion());
+        return;
+    }
+    console.log();
+    p.intro(pc.bgCyan(pc.black(' flight-rules ')));
+    switch (command) {
+        case 'init':
+            await init();
+            break;
+        case 'upgrade':
+            const version = parseVersionArg(args);
+            await upgrade(version);
+            break;
+        case 'adapter':
+            await adapter(args);
+            break;
+        case undefined:
+        case '--help':
+        case '-h':
+            showHelp();
+            break;
+        default:
+            p.log.error(`Unknown command: ${command}`);
+            showHelp();
+            process.exit(1);
+    }
+}
+function showHelp() {
+    console.log(`
+${pc.bold('Usage:')} flight-rules <command> [options]
+
+${pc.bold('Commands:')}
+  init        Install Flight Rules into the current project
+  upgrade     Upgrade Flight Rules (preserves your docs)
+  adapter     Generate agent-specific adapter files
+
+${pc.bold('Upgrade Options:')}
+  --version <version>   Upgrade to a specific version (e.g., 0.1.4)
+                        Defaults to latest from main branch
+
+${pc.bold('Adapter Options:')}
+  --cursor    Generate AGENTS.md for Cursor
+  --claude    Generate CLAUDE.md for Claude Code
+  --all       Generate all adapters
+
+${pc.bold('Examples:')}
+  flight-rules init
+  flight-rules upgrade
+  flight-rules upgrade --version 0.1.4
+  flight-rules adapter --cursor --claude
+`);
+}
+main().catch((err) => {
+    p.log.error(err.message);
+    process.exit(1);
+});

package/dist/utils/files.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Get the CLI version from package.json
+ */
+export declare function getCliVersion(): string;
+/**
+ * Get the path to the payload directory (the Flight Rules content to install)
+ */
+export declare function getPayloadPath(): string;
+/**
+ * Check if Flight Rules is already installed in the target directory
+ */
+export declare function isFlightRulesInstalled(targetDir: string): boolean;
+/**
+ * Get the .flight-rules directory path in the target
+ */
+export declare function getFlightRulesDir(targetDir: string): string;
+/**
+ * Copy the payload to the target directory as .flight-rules
+ */
+export declare function copyPayload(targetDir: string): void;
+/**
+ * Copy only framework files (not docs/) during upgrade
+ */
+export declare function copyFrameworkFiles(targetDir: string): void;
+/**
+ * Ensure a directory exists
+ */
+export declare function ensureDir(dir: string): void;
+/**
+ * Result of fetching payload from GitHub
+ */
+export interface FetchedPayload {
+    payloadPath: string;
+    version: string;
+    cleanup: () => void;
+}
+/**
+ * Fetch the Flight Rules payload from GitHub
+ * @param version - Git ref to fetch (tag like 'v0.1.4', branch like 'main', or 'latest' for main)
+ * @returns Object with payloadPath, version string, and cleanup function
+ */
+export declare function fetchPayloadFromGitHub(version?: string): Promise<FetchedPayload>;
+/**
+ * Copy framework files from a source payload directory (used by both local and remote)
+ */
+export declare function copyFrameworkFilesFrom(sourcePayloadPath: string, targetDir: string): void;
+/**
+ * Copy entire payload from a source directory (used by both local and remote)
+ */
+export declare function copyPayloadFrom(sourcePayloadPath: string, targetDir: string): void;
+/**
+ * Manifest file structure for tracking deployed Flight Rules version
+ */
+export interface Manifest {
+    version: string;
+    deployedAt: string;
+    deployedBy: {
+        cli: string;
+        command: 'init' | 'upgrade';
+    };
+}
+/**
+ * Read the manifest.json from a Flight Rules installation
+ * @returns The manifest data, or null if not found
+ */
+export declare function readManifest(targetDir: string): Manifest | null;
+/**
+ * Write the manifest.json to a Flight Rules installation
+ */
+export declare function writeManifest(targetDir: string, data: Manifest): void;
+/**
+ * Get the current version from manifest, falling back to AGENTS.md
+ * @returns The version string, or null if not found
+ */
+export declare function getInstalledVersion(targetDir: string): string | null;