flight-rules 0.5.9

package/dist/utils/files.js

@@ -0,0 +1,245 @@
+import { existsSync, mkdirSync, cpSync, createWriteStream, rmSync, readdirSync, readFileSync, writeFileSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+import { tmpdir } from 'os';
+import { pipeline } from 'stream/promises';
+import * as tar from 'tar';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const GITHUB_REPO = 'ryanpacker/flight-rules';
+/**
+ * Get the CLI version from package.json
+ */
+export function getCliVersion() {
+    // Structure: flight-rules/dist/utils/files.js
+    // Go up 2 levels to get to flight-rules/, then read package.json
+    const projectRoot = dirname(dirname(__dirname));
+    const packageJsonPath = join(projectRoot, 'package.json');
+    try {
+        const content = readFileSync(packageJsonPath, 'utf-8');
+        const pkg = JSON.parse(content);
+        return pkg.version || 'unknown';
+    }
+    catch {
+        return 'unknown';
+    }
+}
+/**
+ * Get the path to the payload directory (the Flight Rules content to install)
+ */
+export function getPayloadPath() {
+    // Structure: flight-rules/dist/utils/files.js
+    // Go up 2 levels to get to flight-rules/, then into payload/
+    const projectRoot = dirname(dirname(__dirname));
+    return join(projectRoot, 'payload');
+}
+/**
+ * Check if Flight Rules is already installed in the target directory
+ */
+export function isFlightRulesInstalled(targetDir) {
+    return existsSync(join(targetDir, '.flight-rules'));
+}
+/**
+ * Get the .flight-rules directory path in the target
+ */
+export function getFlightRulesDir(targetDir) {
+    return join(targetDir, '.flight-rules');
+}
+/**
+ * Copy the payload to the target directory as .flight-rules
+ */
+export function copyPayload(targetDir) {
+    const payloadPath = getPayloadPath();
+    const destPath = getFlightRulesDir(targetDir);
+    if (!existsSync(payloadPath)) {
+        throw new Error(`Payload not found at ${payloadPath}`);
+    }
+    cpSync(payloadPath, destPath, { recursive: true });
+}
+/**
+ * Copy only framework files (not docs/) during upgrade
+ */
+export function copyFrameworkFiles(targetDir) {
+    const payloadPath = getPayloadPath();
+    const destPath = getFlightRulesDir(targetDir);
+    // Files/directories that are safe to replace on upgrade
+    const frameworkItems = [
+        'AGENTS.md',
+        'doc-templates',
+        'commands',
+        'prompts'
+    ];
+    for (const item of frameworkItems) {
+        const srcItem = join(payloadPath, item);
+        const destItem = join(destPath, item);
+        if (existsSync(srcItem)) {
+            cpSync(srcItem, destItem, { recursive: true });
+        }
+    }
+}
+/**
+ * Ensure a directory exists
+ */
+export function ensureDir(dir) {
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true });
+    }
+}
+/**
+ * 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 async function fetchPayloadFromGitHub(version) {
+    const ref = (!version || version === 'latest') ? 'main' : version.startsWith('v') ? version : `v${version}`;
+    const tarballUrl = `https://github.com/${GITHUB_REPO}/tarball/${ref}`;
+    // Create temp directory
+    const tempDir = join(tmpdir(), `flight-rules-${Date.now()}`);
+    mkdirSync(tempDir, { recursive: true });
+    const tarballPath = join(tempDir, 'payload.tar.gz');
+    const extractDir = join(tempDir, 'extracted');
+    mkdirSync(extractDir, { recursive: true });
+    const cleanup = () => {
+        try {
+            rmSync(tempDir, { recursive: true, force: true });
+        }
+        catch {
+            // Ignore cleanup errors
+        }
+    };
+    try {
+        // Download tarball
+        const response = await fetch(tarballUrl, {
+            headers: { 'Accept': 'application/vnd.github+json' },
+            redirect: 'follow',
+        });
+        if (!response.ok) {
+            if (response.status === 404) {
+                throw new Error(`Version '${ref}' not found. Check available versions at https://github.com/${GITHUB_REPO}/tags`);
+            }
+            throw new Error(`Failed to download from GitHub: ${response.status} ${response.statusText}`);
+        }
+        if (!response.body) {
+            throw new Error('No response body received from GitHub');
+        }
+        // Write tarball to disk using Readable.fromWeb for proper stream compatibility
+        const { Readable } = await import('stream');
+        const fileStream = createWriteStream(tarballPath);
+        const nodeStream = Readable.fromWeb(response.body);
+        await pipeline(nodeStream, fileStream);
+        // Extract tarball
+        await tar.extract({
+            file: tarballPath,
+            cwd: extractDir,
+        });
+        // Find the extracted directory (GitHub creates a directory like 'user-repo-hash')
+        const extractedDirs = readdirSync(extractDir);
+        if (extractedDirs.length === 0) {
+            throw new Error('No files extracted from tarball');
+        }
+        const repoDir = join(extractDir, extractedDirs[0]);
+        const payloadPath = join(repoDir, 'payload');
+        if (!existsSync(payloadPath)) {
+            throw new Error('Payload directory not found in downloaded content');
+        }
+        // Read version from AGENTS.md
+        let detectedVersion = ref;
+        try {
+            const agentsMd = readFileSync(join(payloadPath, 'AGENTS.md'), 'utf-8');
+            const versionMatch = agentsMd.match(/flight_rules_version:\s*([\d.]+)/);
+            if (versionMatch) {
+                detectedVersion = versionMatch[1];
+            }
+        }
+        catch {
+            // Ignore version detection errors
+        }
+        return {
+            payloadPath,
+            version: detectedVersion,
+            cleanup,
+        };
+    }
+    catch (error) {
+        cleanup();
+        throw error;
+    }
+}
+/**
+ * Copy framework files from a source payload directory (used by both local and remote)
+ */
+export function copyFrameworkFilesFrom(sourcePayloadPath, targetDir) {
+    const destPath = getFlightRulesDir(targetDir);
+    // Files/directories that are safe to replace on upgrade
+    const frameworkItems = [
+        'AGENTS.md',
+        'doc-templates',
+        'commands',
+        'prompts'
+    ];
+    for (const item of frameworkItems) {
+        const srcItem = join(sourcePayloadPath, item);
+        const destItem = join(destPath, item);
+        if (existsSync(srcItem)) {
+            cpSync(srcItem, destItem, { recursive: true });
+        }
+    }
+}
+/**
+ * Copy entire payload from a source directory (used by both local and remote)
+ */
+export function copyPayloadFrom(sourcePayloadPath, targetDir) {
+    const destPath = getFlightRulesDir(targetDir);
+    if (!existsSync(sourcePayloadPath)) {
+        throw new Error(`Payload not found at ${sourcePayloadPath}`);
+    }
+    cpSync(sourcePayloadPath, destPath, { recursive: true });
+}
+/**
+ * Read the manifest.json from a Flight Rules installation
+ * @returns The manifest data, or null if not found
+ */
+export function readManifest(targetDir) {
+    const manifestPath = join(getFlightRulesDir(targetDir), 'manifest.json');
+    if (!existsSync(manifestPath)) {
+        return null;
+    }
+    try {
+        const content = readFileSync(manifestPath, 'utf-8');
+        return JSON.parse(content);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Write the manifest.json to a Flight Rules installation
+ */
+export function writeManifest(targetDir, data) {
+    const manifestPath = join(getFlightRulesDir(targetDir), 'manifest.json');
+    writeFileSync(manifestPath, JSON.stringify(data, null, 2) + '\n', 'utf-8');
+}
+/**
+ * Get the current version from manifest, falling back to AGENTS.md
+ * @returns The version string, or null if not found
+ */
+export function getInstalledVersion(targetDir) {
+    // Try manifest first
+    const manifest = readManifest(targetDir);
+    if (manifest) {
+        return manifest.version;
+    }
+    // Fall back to AGENTS.md for older installations
+    const agentsMdPath = join(getFlightRulesDir(targetDir), 'AGENTS.md');
+    if (!existsSync(agentsMdPath)) {
+        return null;
+    }
+    try {
+        const content = readFileSync(agentsMdPath, 'utf-8');
+        const match = content.match(/flight_rules_version:\s*([\d.]+)/);
+        return match ? match[1] : null;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/utils/interactive.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Check if the CLI is running in an interactive terminal.
+ * Returns false in CI environments, piped output, or when called by agents.
+ */
+export declare function isInteractive(): boolean;

package/dist/utils/interactive.js

@@ -0,0 +1,7 @@
+/**
+ * Check if the CLI is running in an interactive terminal.
+ * Returns false in CI environments, piped output, or when called by agents.
+ */
+export function isInteractive() {
+    return process.stdout.isTTY === true;
+}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "flight-rules",
+  "version": "0.5.9",
+  "description": "An opinionated framework for AI-assisted software development",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "flight-rules": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "payload"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ryanpacker/flight-rules.git"
+  },
+  "publishConfig": {
+    "tag": "dev"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "start": "node dist/index.js",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "prepublishOnly": "npm run build",
+    "version": "npm run build && node scripts/sync-version.js && git add payload/AGENTS.md dist/"
+  },
+  "keywords": [
+    "cli",
+    "ai",
+    "development",
+    "agents",
+    "documentation"
+  ],
+  "author": "",
+  "license": "MIT",
+  "devDependencies": {
+    "@types/node": "^20.10.0",
+    "@types/tar": "^6.1.13",
+    "@vitest/coverage-v8": "^4.0.16",
+    "typescript": "^5.3.0",
+    "vitest": "^4.0.16"
+  },
+  "dependencies": {
+    "@clack/prompts": "^0.7.0",
+    "picocolors": "^1.0.0",
+    "tar": "^7.5.2"
+  }
+}

package/payload/.editorconfig

@@ -0,0 +1,15 @@
+# EditorConfig helps maintain consistent coding styles
+# https://editorconfig.org
+
+root = true
+
+[*]
+insert_final_newline = true
+end_of_line = lf
+charset = utf-8
+trim_trailing_whitespace = true
+
+[*.md]
+trim_trailing_whitespace = false
+
+

package/payload/AGENTS.md

@@ -0,0 +1,247 @@
+# Flight Rules – Agent Guidelines
+
+flight_rules_version: 0.5.9
+
+This file defines how agents (Claude Code, Cursor, etc.) should work on software projects using the Flight Rules system.
+
+It explains:
+- How project docs are structured
+- How implementation specs work
+- How to use start / end coding sessions
+- Where progress and learnings are tracked
+
+The goal: any agent (or human) should be able to understand the project's lifecycle and contribute without guesswork.
+
+---
+
+## 1. High-level lifecycle
+
+Assume the following lifecycle for projects:
+
+1. **Idea & PRD** – captured in `docs/prd.md`
+2. **Implementation specs (iterative)** – The spec system (Areas → Task Groups → Tasks) lives under `docs/implementation/`. Usually, Areas and Task Groups are drafted first, but individual Tasks are typically fleshed out incrementally, often at the start of each coding session as part of setting the plan for that session.
+
+3. **Coding sessions** – At the beginning of a session, identify or refine the relevant Tasks within a Task Group, make a clear plan for implementation, and then execute against that plan.
+   - Each session should produce:
+     - Detailed documentation in `docs/session_logs/`
+     - A brief summary/log entry in `docs/progress.md` also links to the details in `session_logs`.
+4. **Critical learnings** – promoted into `docs/critical-learnings.md`
+5. **Commits & releases** – Git history + tags/releases reflect implementation of the specs
+
+Agents should prefer working *with* this system rather than inventing their own structure.
+
+---
+
+## 2. Project structure
+
+Projects using Flight Rules have two key locations:
+
+### `.flight-rules/` – Framework files
+
+The `.flight-rules/` directory contains Flight Rules framework files. These can be replaced on upgrade.
+
+- `.flight-rules/AGENTS.md` – This file; agent guidelines
+- `.flight-rules/doc-templates/` – Templates for creating project docs
+- `.flight-rules/commands/` – Workflow command files (start/end coding session)
+- `.flight-rules/prompts/` – Reusable prompt templates
+
+### `docs/` – Your project documentation
+
+The `docs/` directory at the project root contains your project content. These files are created by `flight-rules init` and new templates are added during `flight-rules upgrade`.
+
+- `docs/prd.md`  
+  - Product requirements and high-level goals.
+  - Agents should read this when clarifying "what are we building and why?"
+
+- `docs/implementation/`  
+  - Home of the implementation spec hierarchy (see next section).
+  - The **spec is the single source of truth** for what should exist in the codebase and why.
+
+- `docs/progress.md`  
+  - A running high-level log of sessions and milestones.
+  - Each session gets a short entry + link to its detailed log file.
+
+- `docs/critical-learnings.md`  
+  - A curated list of reusable insights, patterns, and "never again" notes.
+  - Agents should propose additions when a session reveals something important or reusable.
+
+- `docs/tech-stack.md`  
+  - Documents the project's technical environment (testing framework, runtime, key dependencies).
+  - Agents should read this when performing tech-dependent tasks like creating tests.
+  - Use `/test.assess-current` to auto-populate this file based on the project's setup.
+
+- `docs/session_logs/`  
+  - Session documentation created during coding sessions.
+  - Contains plans, summaries, and learnings from each session.
+  - Agents create new session logs following the structure in `.flight-rules/doc-templates/session-log.md`.
+
+---
+
+## 3. Implementation spec system (Areas, Task Groups, Tasks)
+
+Implementation specs live in `docs/implementation/` and follow a 3-level hierarchy:
+
+| Level | Name | Example | Description |
+|-------|------|---------|-------------|
+| 1 | **Area** | `1-foundation-shell/` | A major implementation area (directory) |
+| 2 | **Task Group** | `1.4-application-shell.md` | A file containing related tasks |
+| 3 | **Task** | `1.4.1. Routing Structure` | A specific unit of work with status |
+
+### Areas (Level 1)
+
+- Listed in `docs/implementation/overview.md`
+- Each Area is a directory: `docs/implementation/{N}-{kebab-topic}/`
+- Contains an `index.md` with overview, goals, and architecture context
+- Examples: "Foundation & Shell", "Core Domain Models", "API Integration"
+
+### Task Groups (Level 2)
+
+- Files within an Area directory: `{N}.{M}-topic.md`
+- Each Task Group covers a coherent piece of work
+- Contains multiple related Tasks
+
+### Tasks (Level 3)
+
+- Sections within a Task Group file (e.g., `1.4.1. Routing Structure`)
+- Each Task includes:
+  - Clear goals and scope
+  - Constraints and decisions
+  - A breakdown of steps
+  - A `Status:` line
+
+**Status tracking**
+
+- Status is tracked **at the Task level** within Task Group files, not in code comments or random notes.
+- Typical status values:
+  - `Status: 🔵 Planned`
+  - `Status: 🟡 In Progress`
+  - `Status: ✅ Complete`
+
+**Core rule: the spec is the single source of truth**
+
+- If the code deviates from the spec (because the user or agent made a change), that's acceptable **only if the spec is updated** to reflect reality.
+- In an ideal world, someone could recreate the project from scratch by implementing each spec file one by one.
+
+**Agent behavior with specs**
+
+When working on code:
+
+1. Identify the relevant Area, Task Group, and Task(s) for the work.
+2. Explicitly reference the Task ID(s) (e.g., `1.4.2 Left Sidebar Implementation`) in your working notes / session plan.
+3. After implementation:
+   - Propose updates to the corresponding Task(s) for the user's approval:
+     - What was actually done
+     - Any deviations from original plan
+     - Updated `Status:` values
+
+---
+
+## 4. Coding sessions
+
+The user will explicitly start and end sessions using commands or workflows like:
+
+- **"start coding session"** → use `.flight-rules/commands/dev-session.start.md`
+- **"end coding session"**   → use `.flight-rules/commands/dev-session.end.md`
+
+Agents **must not** initiate these workflows on their own; they are only run when the user asks.
+
+### 4.1 Start coding session
+
+When the user triggers a start session command, follow the process defined in `.flight-rules/commands/dev-session.start.md`. The generic behavior:
+
+1. **Review project context**
+   - Read `docs/prd.md`, `docs/implementation/overview.md`, relevant spec files, and `docs/progress.md`.
+   - Read the most recent session log in `docs/session_logs/` if present.
+   - Scan code as needed to understand current state.
+
+2. **Establish session goals**
+   - Ask the user for goals for this session.
+   - Suggest goals based on "Next Steps" from the last session and spec statuses.
+   - Agree on a small set of specific, achievable goals.
+
+3. **Create a detailed implementation plan**
+   - Collaborate with the user on approach:
+     - Technical options (with pros/cons)
+     - Constraints
+     - Potential challenges and mitigations
+
+4. **Document the session plan**
+   - Create a session log in `docs/session_logs/` using the template at `.flight-rules/doc-templates/session-log.md`.
+   - Reference relevant Task Group and Task IDs.
+
+5. **Confirm before coding**
+   - Show the user the plan (or a summary).
+   - Ask explicitly:  
+     > "The session plan has been documented. Are you ready for me to begin implementing this plan?"  
+   - **Do not** begin implementation until they confirm.
+
+### 4.2 End coding session
+
+When the user triggers an end session command, follow the process in `.flight-rules/commands/dev-session.end.md`. Generic behavior:
+
+1. **Review sandbox / scratch files**  
+   - Identify temporary / sandbox code and determine, with the user, what to keep vs delete.
+
+2. **Summarize the session**
+   - Draft a summary covering:
+     - What was accomplished
+     - Key decisions (especially deviations from spec)
+     - Implementation details of note
+     - Challenges and how they were resolved
+     - Proposed next steps
+   - Present the summary to the user for edits/approval.
+
+3. **Update the session log**
+   - Update the session log in `docs/session_logs/` with the summary.
+   - Link to relevant Task Groups, Tasks, and code areas.
+
+4. **Update progress**
+   - Append a short entry to `docs/progress.md`:
+     - Date/time
+     - 2–4 bullet summary
+     - Link to the session log file.
+
+5. **Promote critical learnings**  
+   - Scan the session details for reusable insights or "this will matter again" items.
+   - Propose additions to `docs/critical-learnings.md` and update that file when the user approves.
+
+6. **Offer to commit**
+   - Ask if the user wants to commit now.
+   - If yes, help prepare a concise, meaningful commit message summarizing the session.
+
+---
+
+## 5. Agent behavior & tone
+
+- **Opinionated but not rigid**  
+  - Prefer following this workflow, but do not block the user if they want to "just do X in file Y right now."
+  - It's appropriate to say things like:
+    - "We *could* create a quick session plan first; want to do that?"
+    - "This change touches multiple specs; should we update them before we stop?"
+
+- **Ask questions when uncertain**  
+  - If an instruction is ambiguous, ask for clarification rather than guessing.
+
+- **Defer to project-specific overrides**  
+  - If the project has its own `AGENTS.local.md` or agent-specific config that extends these rules, follow those where they differ.
+
+---
+
+## 6. Where to look for project-specific instructions
+
+When working in a project that uses this system:
+
+1. Read this `.flight-rules/AGENTS.md` file.
+2. Look for project-specific overrides or additions in:
+   - `AGENTS.local.md` (if present at project root)
+   - Additional docs under `docs/` (e.g., `architecture.md`, project-specific guides)
+3. Treat project-specific content as authoritative where it narrows or extends these global rules.
+
+---
+
+If you are an agent in this project, your default behavior should be:
+
+1. Respect the structure and workflows described here.
+2. Use the implementation spec as the single source of truth.
+3. Use start/end coding session workflows when the user explicitly invokes them.
+4. Help keep PRD, specs, progress, and learnings clean, accurate, and up-to-date.

package/payload/commands/dev-session.end.md

@@ -0,0 +1,79 @@
+# End Coding Session
+
+When the user invokes "end coding session", follow this process:
+
+## 1. Review Work Done
+
+Identify:
+- What code was written or modified
+- Any sandbox/scratch files that need to be kept or discarded
+- Any temporary debugging code that should be removed
+
+Ask the user about anything uncertain.
+
+## 2. Summarize the Session
+
+Draft a summary covering:
+- **What was accomplished** – Key deliverables
+- **Key decisions** – Especially any deviations from the original plan
+- **Implementation details** – Notable technical choices
+- **Challenges and solutions** – Problems encountered and how they were resolved
+- **Proposed next steps** – What should happen in future sessions
+
+Present the summary to the user for review and approval.
+
+## 3. Update the Session Log
+
+Update the session log file in `docs/session_logs/YYYYMMDD_HHMM_session.md`
+
+Use the template at `.flight-rules/doc-templates/session-log.md` as a guide if creating a new log.
+
+Include:
+- Summary
+- Goal completion status
+- Detailed description of work
+- Key decisions
+- Challenges and solutions
+- Code areas touched
+- Spec updates needed
+- Next steps
+
+## 4. Update Progress
+
+Append a short entry to `docs/progress.md`:
+
+```markdown
+### YYYY-MM-DD HH:MM
+
+- Brief summary point 1
+- Brief summary point 2
+- See: [session_logs/YYYYMMDD_HHMM_session.md](session_logs/YYYYMMDD_HHMM_session.md)
+```
+
+## 5. Propose Spec Updates
+
+If implementation deviated from specs or completed spec items:
+- Identify which spec files need updates
+- Propose the specific changes to the user for approval
+- Update specs when approved
+
+## 6. Promote Critical Learnings
+
+Scan the session for reusable insights:
+- Patterns that worked well
+- Mistakes to avoid
+- Important decisions that should inform future work
+
+Propose additions to `docs/critical-learnings.md` and update when approved.
+
+## 7. Offer to Commit
+
+Ask the user:
+> "Would you like to commit these changes now?"
+
+If yes, help prepare a commit message that:
+- Summarizes what was accomplished
+- References the session log file
+- Is concise but meaningful
+
+