flight-rules 0.8.0 → 0.10.0

package/README.md

@@ -89,6 +89,28 @@ Two core flows:
 
 Agents don't start these flows on their own; you explicitly invoke them.
 
+### Available Commands
+
+Flight Rules provides workflow commands that agents can execute:
+
+| Command | Purpose |
+|---------|---------|
+| `/dev-session.start` | Begin a structured coding session with goals and plan |
+| `/dev-session.end` | End session, summarize work, update progress |
+| `/prd.create` | Create a Product Requirements Document |
+| `/prd.clarify` | Refine specific sections of an existing PRD |
+| `/impl.outline` | Create implementation area structure |
+| `/impl.create` | Add detailed tasks to implementation specs |
+| `/feature.add` | Add a new feature to PRD and implementation docs |
+| `/test.add` | Add tests for specific functionality |
+| `/test.assess-current` | Analyze existing test coverage |
+| `/prompt.refine` | Iteratively improve a prompt |
+| `/readme.create` | Generate README from PRD and project state |
+| `/readme.reconcile` | Update README to reflect recent changes |
+| `/prd.reconcile` | Update PRD based on what was actually built |
+| `/impl.reconcile` | Update implementation docs with status changes |
+| `/docs.reconcile` | Run all reconcile commands + consistency check |
+
 ### Versioning
 
 Each project tracks which Flight Rules version it uses:
@@ -126,11 +148,22 @@ your-project/
     │   ├── session-log.md
     │   └── implementation/
     │       └── overview.md
-    ├── commands/
+    ├── commands/             # Workflow commands
     │   ├── dev-session.start.md
     │   ├── dev-session.end.md
+    │   ├── prd.create.md
+    │   ├── prd.clarify.md
+    │   ├── impl.outline.md
+    │   ├── impl.create.md
+    │   ├── feature.add.md
     │   ├── test.add.md
-    │   └── test.assess-current.md
+    │   ├── test.assess-current.md
+    │   ├── prompt.refine.md
+    │   ├── readme.create.md
+    │   ├── readme.reconcile.md
+    │   ├── prd.reconcile.md
+    │   ├── impl.reconcile.md
+    │   └── docs.reconcile.md
     └── prompts/              # Reusable prompt templates
 ```
 

package/dist/commands/update.d.ts

@@ -0,0 +1 @@
+export declare function update(args?: string[]): Promise<void>;

package/dist/commands/update.js

@@ -0,0 +1,137 @@
+import * as p from '@clack/prompts';
+import pc from 'picocolors';
+import { spawn } from 'child_process';
+import { checkForUpdate } from '../utils/version-check.js';
+import { getChannel, setChannel } from '../utils/config.js';
+import { isInteractive } from '../utils/interactive.js';
+/**
+ * Parse --channel flag from args
+ */
+function parseChannelArg(args) {
+    const channelIndex = args.findIndex(arg => arg === '--channel');
+    if (channelIndex !== -1 && args[channelIndex + 1]) {
+        const value = args[channelIndex + 1];
+        if (value === 'dev' || value === 'latest') {
+            return value;
+        }
+    }
+    // Also support --channel=dev format
+    const channelArg = args.find(arg => arg.startsWith('--channel='));
+    if (channelArg) {
+        const value = channelArg.split('=')[1];
+        if (value === 'dev' || value === 'latest') {
+            return value;
+        }
+    }
+    return undefined;
+}
+/**
+ * Run npm install to update the CLI
+ */
+function runNpmInstall(channel) {
+    return new Promise((resolve) => {
+        const packageSpec = `flight-rules@${channel}`;
+        const npmProcess = spawn('npm', ['install', '-g', packageSpec], {
+            stdio: ['inherit', 'pipe', 'pipe'],
+            shell: true,
+        });
+        let stdout = '';
+        let stderr = '';
+        npmProcess.stdout?.on('data', (data) => {
+            stdout += data.toString();
+        });
+        npmProcess.stderr?.on('data', (data) => {
+            stderr += data.toString();
+        });
+        npmProcess.on('close', (code) => {
+            if (code === 0) {
+                resolve({ success: true });
+            }
+            else {
+                resolve({
+                    success: false,
+                    error: stderr || stdout || `npm exited with code ${code}`
+                });
+            }
+        });
+        npmProcess.on('error', (err) => {
+            resolve({ success: false, error: err.message });
+        });
+    });
+}
+export async function update(args = []) {
+    const interactive = isInteractive();
+    // Parse --channel flag
+    const requestedChannel = parseChannelArg(args);
+    const currentChannel = getChannel();
+    const targetChannel = requestedChannel || currentChannel;
+    // If switching channels, inform the user
+    if (requestedChannel && requestedChannel !== currentChannel) {
+        p.log.info(`Switching from ${pc.yellow(currentChannel)} to ${pc.cyan(requestedChannel)} channel.`);
+    }
+    // Check for updates (force fetch, bypass cache)
+    const spinner = p.spinner();
+    spinner.start('Checking for updates...');
+    const result = await checkForUpdate({ force: true });
+    if (!result) {
+        spinner.stop('Unable to check for updates');
+        p.log.error('Could not connect to npm registry. Check your network connection.');
+        return;
+    }
+    spinner.stop('Version check complete');
+    // Display version info
+    p.log.info(`Current version: ${pc.cyan(result.currentVersion)}`);
+    p.log.info(`Latest version (${targetChannel}): ${pc.cyan(result.latestVersion)}`);
+    // Check if update is needed
+    if (!result.updateAvailable && targetChannel === currentChannel) {
+        p.log.success('You are already on the latest version!');
+        p.outro(pc.green('No update needed.'));
+        return;
+    }
+    // If only switching channels (no version change), still proceed
+    const switchingChannels = requestedChannel && requestedChannel !== currentChannel;
+    if (!result.updateAvailable && !switchingChannels) {
+        p.log.success('You are already on the latest version!');
+        p.outro(pc.green('No update needed.'));
+        return;
+    }
+    // Non-interactive mode: show info but don't update
+    if (!interactive) {
+        if (result.updateAvailable) {
+            p.log.info(`Update available: ${pc.yellow(result.currentVersion)} → ${pc.cyan(result.latestVersion)}`);
+            p.log.message('Run this command in an interactive terminal to update.');
+        }
+        if (switchingChannels) {
+            p.log.info(`Run this command in an interactive terminal to switch to the ${requestedChannel} channel.`);
+        }
+        return;
+    }
+    // Interactive mode: confirm and update
+    const message = result.updateAvailable
+        ? `Update from ${result.currentVersion} to ${result.latestVersion}?`
+        : `Switch to ${targetChannel} channel?`;
+    const shouldUpdate = await p.confirm({
+        message,
+        initialValue: true,
+    });
+    if (p.isCancel(shouldUpdate) || !shouldUpdate) {
+        p.log.info('Update cancelled.');
+        return;
+    }
+    // Perform update
+    spinner.start(`Installing flight-rules@${targetChannel}...`);
+    const installResult = await runNpmInstall(targetChannel);
+    if (!installResult.success) {
+        spinner.stop('Update failed');
+        p.log.error(installResult.error || 'Unknown error during npm install');
+        p.log.message(`You can try manually: ${pc.cyan(`npm install -g flight-rules@${targetChannel}`)}`);
+        return;
+    }
+    spinner.stop('Update complete!');
+    // Update channel in config if it changed
+    if (requestedChannel && requestedChannel !== currentChannel) {
+        setChannel(requestedChannel);
+        p.log.success(`Channel set to ${pc.cyan(requestedChannel)}`);
+    }
+    p.outro(pc.green(`Successfully updated to flight-rules@${targetChannel}!`));
+}

package/dist/index.js

@@ -4,7 +4,10 @@ import pc from 'picocolors';
 import { init } from './commands/init.js';
 import { upgrade } from './commands/upgrade.js';
 import { adapter } from './commands/adapter.js';
+import { update } from './commands/update.js';
 import { getCliVersion } from './utils/files.js';
+import { checkForUpdate, shouldSkipUpdateCheck } from './utils/version-check.js';
+import { isInteractive } from './utils/interactive.js';
 const command = process.argv[2];
 const args = process.argv.slice(3);
 /**
@@ -41,6 +44,9 @@ async function main() {
         case 'adapter':
             await adapter(args);
             break;
+        case 'update':
+            await update(args);
+            break;
         case undefined:
         case '--help':
         case '-h':
@@ -51,6 +57,8 @@ async function main() {
             showHelp();
             process.exit(1);
     }
+    // Show update notification after command completes (uses cache, non-blocking)
+    await showUpdateNotification();
 }
 function showHelp() {
     console.log(`
@@ -60,11 +68,16 @@ ${pc.bold('Commands:')}
   init        Install Flight Rules into the current project
   upgrade     Upgrade Flight Rules (preserves your docs)
   adapter     Generate agent-specific adapter files
+  update      Update the Flight Rules CLI itself
 
 ${pc.bold('Upgrade Options:')}
   --version <version>   Upgrade to a specific version (e.g., 0.1.4)
                         Defaults to latest from main branch
 
+${pc.bold('Update Options:')}
+  --channel <channel>   Switch release channel (dev or latest)
+                        Defaults to current channel
+
 ${pc.bold('Adapter Options:')}
   --cursor    Generate AGENTS.md for Cursor
   --claude    Generate CLAUDE.md for Claude Code
@@ -74,9 +87,37 @@ ${pc.bold('Examples:')}
   flight-rules init
   flight-rules upgrade
   flight-rules upgrade --version 0.1.4
+  flight-rules update
+  flight-rules update --channel=latest
   flight-rules adapter --cursor --claude
 `);
 }
+/**
+ * Show update notification if a newer version is available.
+ * Uses cached check result to avoid slowing down commands.
+ * Only shows in interactive (TTY) mode.
+ */
+async function showUpdateNotification() {
+    // Skip in non-interactive mode or if disabled
+    if (!isInteractive() || shouldSkipUpdateCheck()) {
+        return;
+    }
+    // Skip for commands that handle their own version checking
+    if (command === 'update' || command === '--version' || command === '-v') {
+        return;
+    }
+    try {
+        const result = await checkForUpdate(); // Uses cache, won't slow down
+        if (result?.updateAvailable) {
+            console.log();
+            p.log.message(pc.yellow(`Update available: ${result.currentVersion} → ${result.latestVersion}`) +
+                pc.dim(` Run 'flight-rules update' to upgrade.`));
+        }
+    }
+    catch {
+        // Silent failure - don't disrupt the user's workflow
+    }
+}
 main().catch((err) => {
     p.log.error(err.message);
     process.exit(1);

package/dist/utils/config.d.ts

@@ -0,0 +1,44 @@
+/**
+ * User-level configuration for Flight Rules CLI
+ */
+export interface UserConfig {
+    channel: 'dev' | 'latest';
+    lastUpdateCheck?: {
+        timestamp: string;
+        latestVersion: string;
+    };
+}
+/**
+ * Get the path to the user-level Flight Rules directory
+ */
+export declare function getUserFlightRulesDir(): string;
+/**
+ * Get the path to the user-level config file
+ */
+export declare function getConfigPath(): string;
+/**
+ * Read the user-level config, creating default if missing
+ */
+export declare function readConfig(): UserConfig;
+/**
+ * Write the user-level config
+ */
+export declare function writeConfig(config: UserConfig): void;
+/**
+ * Get the configured release channel
+ */
+export declare function getChannel(): 'dev' | 'latest';
+/**
+ * Set the release channel
+ */
+export declare function setChannel(channel: 'dev' | 'latest'): void;
+/**
+ * Update the cached update check result
+ */
+export declare function updateLastCheck(latestVersion: string): void;
+/**
+ * Get the cached update check result, if still valid
+ * @param maxAgeMs - Maximum age in milliseconds (default 24 hours)
+ * @returns The cached version if valid, null otherwise
+ */
+export declare function getCachedVersion(maxAgeMs?: number): string | null;

package/dist/utils/config.js

@@ -0,0 +1,89 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
+import { join, dirname } from 'path';
+import { homedir } from 'os';
+const DEFAULT_CONFIG = {
+    channel: 'dev',
+};
+/**
+ * Get the path to the user-level Flight Rules directory
+ */
+export function getUserFlightRulesDir() {
+    return join(homedir(), '.flight-rules');
+}
+/**
+ * Get the path to the user-level config file
+ */
+export function getConfigPath() {
+    return join(getUserFlightRulesDir(), 'config.json');
+}
+/**
+ * Read the user-level config, creating default if missing
+ */
+export function readConfig() {
+    const configPath = getConfigPath();
+    if (!existsSync(configPath)) {
+        return { ...DEFAULT_CONFIG };
+    }
+    try {
+        const content = readFileSync(configPath, 'utf-8');
+        const parsed = JSON.parse(content);
+        // Merge with defaults to handle missing fields
+        return { ...DEFAULT_CONFIG, ...parsed };
+    }
+    catch {
+        return { ...DEFAULT_CONFIG };
+    }
+}
+/**
+ * Write the user-level config
+ */
+export function writeConfig(config) {
+    const configPath = getConfigPath();
+    const configDir = dirname(configPath);
+    if (!existsSync(configDir)) {
+        mkdirSync(configDir, { recursive: true });
+    }
+    writeFileSync(configPath, JSON.stringify(config, null, 2) + '\n', 'utf-8');
+}
+/**
+ * Get the configured release channel
+ */
+export function getChannel() {
+    return readConfig().channel;
+}
+/**
+ * Set the release channel
+ */
+export function setChannel(channel) {
+    const config = readConfig();
+    config.channel = channel;
+    writeConfig(config);
+}
+/**
+ * Update the cached update check result
+ */
+export function updateLastCheck(latestVersion) {
+    const config = readConfig();
+    config.lastUpdateCheck = {
+        timestamp: new Date().toISOString(),
+        latestVersion,
+    };
+    writeConfig(config);
+}
+/**
+ * Get the cached update check result, if still valid
+ * @param maxAgeMs - Maximum age in milliseconds (default 24 hours)
+ * @returns The cached version if valid, null otherwise
+ */
+export function getCachedVersion(maxAgeMs = 24 * 60 * 60 * 1000) {
+    const config = readConfig();
+    if (!config.lastUpdateCheck) {
+        return null;
+    }
+    const checkTime = new Date(config.lastUpdateCheck.timestamp).getTime();
+    const now = Date.now();
+    if (now - checkTime > maxAgeMs) {
+        return null; // Cache expired
+    }
+    return config.lastUpdateCheck.latestVersion;
+}

package/dist/utils/version-check.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Result of a version check
+ */
+export interface VersionCheckResult {
+    currentVersion: string;
+    latestVersion: string;
+    updateAvailable: boolean;
+    channel: 'dev' | 'latest';
+}
+/**
+ * Options for version check
+ */
+export interface VersionCheckOptions {
+    force?: boolean;
+}
+/**
+ * Check for available updates
+ * @param options - Options for the check
+ * @returns Version check result, or null if check failed
+ */
+export declare function checkForUpdate(options?: VersionCheckOptions): Promise<VersionCheckResult | null>;
+/**
+ * Check if update check should be skipped based on environment
+ */
+export declare function shouldSkipUpdateCheck(): boolean;

package/dist/utils/version-check.js

@@ -0,0 +1,87 @@
+import { getCliVersion } from './files.js';
+import { getChannel, getCachedVersion, updateLastCheck } from './config.js';
+const NPM_REGISTRY_URL = 'https://registry.npmjs.org/flight-rules';
+/**
+ * Compare two semver versions
+ * @returns true if v2 is newer than v1
+ */
+function isNewerVersion(current, latest) {
+    const v1Parts = current.split('.').map(Number);
+    const v2Parts = latest.split('.').map(Number);
+    for (let i = 0; i < Math.max(v1Parts.length, v2Parts.length); i++) {
+        const v1 = v1Parts[i] || 0;
+        const v2 = v2Parts[i] || 0;
+        if (v2 > v1)
+            return true;
+        if (v2 < v1)
+            return false;
+    }
+    return false;
+}
+/**
+ * Fetch the latest version from npm registry
+ * @returns The latest version for the given channel, or null on error
+ */
+async function fetchLatestVersion(channel) {
+    try {
+        const response = await fetch(NPM_REGISTRY_URL, {
+            headers: { 'Accept': 'application/json' },
+        });
+        if (!response.ok) {
+            return null;
+        }
+        const data = await response.json();
+        const distTags = data['dist-tags'];
+        if (!distTags) {
+            return null;
+        }
+        return distTags[channel] || null;
+    }
+    catch {
+        // Silent failure on network errors
+        return null;
+    }
+}
+/**
+ * Check for available updates
+ * @param options - Options for the check
+ * @returns Version check result, or null if check failed
+ */
+export async function checkForUpdate(options = {}) {
+    const currentVersion = getCliVersion();
+    const channel = getChannel();
+    if (currentVersion === 'unknown') {
+        return null;
+    }
+    // Check cache first (unless forced)
+    if (!options.force) {
+        const cachedVersion = getCachedVersion();
+        if (cachedVersion) {
+            return {
+                currentVersion,
+                latestVersion: cachedVersion,
+                updateAvailable: isNewerVersion(currentVersion, cachedVersion),
+                channel,
+            };
+        }
+    }
+    // Fetch from npm registry
+    const latestVersion = await fetchLatestVersion(channel);
+    if (!latestVersion) {
+        return null; // Network error or registry issue
+    }
+    // Update cache
+    updateLastCheck(latestVersion);
+    return {
+        currentVersion,
+        latestVersion,
+        updateAvailable: isNewerVersion(currentVersion, latestVersion),
+        channel,
+    };
+}
+/**
+ * Check if update check should be skipped based on environment
+ */
+export function shouldSkipUpdateCheck() {
+    return process.env.FLIGHT_RULES_NO_UPDATE_CHECK === '1';
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flight-rules",
-  "version": "0.8.0",
+  "version": "0.10.0",
   "description": "An opinionated framework for AI-assisted software development",
   "type": "module",
   "main": "dist/index.js",

package/payload/AGENTS.md

@@ -1,6 +1,6 @@
 # Flight Rules – Agent Guidelines
 
-flight_rules_version: 0.8.0
+flight_rules_version: 0.10.0
 
 This file defines how agents (Claude Code, Cursor, etc.) should work on software projects using the Flight Rules system.