project-iris 0.0.6

package/dist/iris/validator.js

@@ -0,0 +1,329 @@
+import fs from "fs";
+import path from "path";
+import matter from "gray-matter";
+import { loadPolicy } from "./policy.js";
+import { loadState, saveState } from "./state.js";
+import { checkArtifact } from "./artifact-checker.js";
+// Force specific phases to be valid per context? Or just trust policy? context says "Valid Phases: inception, construction, operations"
+// We will rely on policy.yaml for configuration but code logic handles general cases.
+export async function validate(options) {
+    const shouldWrite = options.writeBack !== false;
+    // Step A: Load & validate config
+    const policy = loadPolicy();
+    const state = loadState();
+    const errors = [];
+    // Step B: Resolve target phase
+    let targetPhase = state.phase.current;
+    if (options.phase) {
+        targetPhase = options.phase;
+    }
+    // Check if phase exists in policy
+    if (!policy.phases[targetPhase]) {
+        errors.push({
+            code: "UNKNOWN_PHASE",
+            message: `Target phase '${targetPhase}' does not exist in policy.`,
+            severity: "error"
+        });
+        return finalizeResult(errors, state, false, shouldWrite);
+    }
+    // Step C: Required artifacts (FAIL FAST)
+    // Gather requirements for the phase
+    const requirements = policy.phases[targetPhase].requires || [];
+    for (const req of requirements) {
+        const check = checkArtifact(process.cwd(), req.path, req.type);
+        if (!check.exists) {
+            errors.push({
+                code: "MISSING_ARTIFACT",
+                path: check.normalized,
+                message: `Required ${req.type} missing: ${check.normalized}`,
+                remediation: req.template
+                    ? `Create from template: ${req.template}`
+                    : `Create ${req.type} at ${check.normalized}`,
+                template: req.template,
+                artifactType: req.type,
+                severity: "error"
+            });
+        }
+        else {
+            // Validate type matches
+            if (req.type === "directory" && !check.isDirectory) {
+                errors.push({
+                    code: "INVALID_TYPE",
+                    path: check.normalized,
+                    message: `Expected directory but found file: ${check.normalized}`,
+                    remediation: "Remove file and create directory",
+                    severity: "error"
+                });
+            }
+            else if (req.type === "file" && !check.isFile) {
+                errors.push({
+                    code: "INVALID_TYPE",
+                    path: check.normalized,
+                    message: `Expected file but found directory: ${check.normalized}`,
+                    remediation: "Remove directory and create file",
+                    severity: "error"
+                });
+            }
+            else if (req.type === "file") {
+                // Content Quality Check (Warnings)
+                const qualityWarnings = checkContentQuality(check.absolutePath);
+                errors.push(...qualityWarnings);
+            }
+        }
+    }
+    // Fail fast if strict artifact check fails?
+    // Specs say "Missing artifacts -> fail fast errors". 
+    // Usually means return immediately or don't proceed to gates?
+    // Let's collect all missing artifacts first, but if ANY are missing, we probably shouldn't check gates that rely on them.
+    if (errors.length > 0) {
+        return finalizeResult(errors, state, false, shouldWrite);
+    }
+    // Optional Structure Check: Units
+    // IF units/ exists under any intent, IT MUST contain unit-brief.md
+    checkOptionalUnits(errors);
+    if (errors.length > 0) {
+        return finalizeResult(errors, state, false, shouldWrite);
+    }
+    // Step D: Gate checks (HARD ERRORS)
+    // "Support frontmatter gates"
+    const gates = policy.phases[targetPhase].gates || [];
+    for (const gate of gates) {
+        if (gate.kind === "frontmatter") {
+            const gateError = checkFrontmatterGate(gate);
+            if (gateError) {
+                errors.push(gateError);
+            }
+        }
+        else {
+            console.warn(`Unknown gate kind: ${gate.kind}`);
+        }
+    }
+    if (errors.length > 0) {
+        return finalizeResult(errors, state, false, shouldWrite);
+    }
+    // Step E: Phase transition enforcement
+    let applying = false;
+    // Only check transition if we have a requested phase and we are NOT just probing a specific phase with --phase
+    if (state.phase.requested && !options.phase) {
+        // Validate transition
+        const from = state.phase.current;
+        const to = state.phase.requested;
+        const transition = policy.transitions.find(t => t.from === from && t.to === to);
+        if (!transition) {
+            errors.push({
+                code: "INVALID_TRANSITION",
+                message: `Transition from '${from}' to '${to}' is not defined in policy.`,
+                remediation: "Reset requested phase or update policy.",
+                severity: "error"
+            });
+        }
+        else {
+            // Validate requires_gates[] for transition
+            // These reference gates defined in the phase? OR are they ids?
+            // "Validate requires_gates[] for transition" implies the transition object has a list of gate IDs that must pass.
+            // But where are these gates defined? Usually gates are on the phase.
+            // Interpretation: Check if the gates identified by ID in the CURRENT phase (or destination?) are passed?
+            // "If transition not allowed -> ERROR"
+            // "Validate requires_gates[] for transition" -> "If any gate fails -> ERROR"
+            // Let's assume gates are identified by 'id' in policy.phases[...].gates
+            // AND the transition rules apply to the CURRENT state config or the TARGET?
+            // Usually transition gates check if you are ready to LEAVE 'from' or ENTER 'to'.
+            // Given "inception.intent.approved", it likely checks the state of the *current* phase artifacts to allow moving forward.
+            if (transition.requires_gates) {
+                // Find these gates. They could be in the 'from' phase or 'to' phase. 
+                // A safe bet is to search all defined gates in 'from' phase, or global?
+                // The snippet shows: id: "inception.intent.approved" -> implies inception phase.
+                // We need to look up these gates.
+                // NOTE: We only ran checks for 'targetPhase' above. 
+                // If targetPhase == current, we checked current.
+                // If targetPhase == requested (via --phase), we checked requested.
+                // Transition logic is: checking if we can move FROM current TO requested.
+                // So we should validate gates required by the transition.
+                for (const gateId of transition.requires_gates) {
+                    // Find the gate definition. 
+                    // We search in 'from' phase first, then 'to' phase?
+                    // Or just iterate all phases?
+                    let foundGate;
+                    // Optimization: check 'from' first
+                    if (policy.phases[from]?.gates) {
+                        foundGate = policy.phases[from].gates?.find(g => g.id === gateId);
+                    }
+                    // check 'to' next
+                    if (!foundGate && policy.phases[to]?.gates) {
+                        foundGate = policy.phases[to].gates?.find(g => g.id === gateId);
+                    }
+                    if (!foundGate) {
+                        errors.push({
+                            code: "MISSING_GATE_DEF",
+                            message: `Transition requires gate '${gateId}' but it is not found in '${from}' or '${to}' phases.`,
+                            severity: "error"
+                        });
+                        continue;
+                    }
+                    // Run the gate check
+                    if (foundGate.kind === "frontmatter") {
+                        const gateError = checkFrontmatterGate(foundGate);
+                        if (gateError) {
+                            errors.push(gateError);
+                        }
+                    }
+                }
+            }
+        }
+    }
+    // Step F: Apply transition (--apply)
+    // Only apply if we are allowed to write back
+    if (shouldWrite && errors.length === 0 && options.apply && state.phase.requested && !options.phase) {
+        // Valid and apply requested
+        // Safety: ensure transition valid again? (already done in Step E if we had errors, it would fail)
+        // If we are here, Step E passed.
+        state.phase.current = state.phase.requested;
+        state.phase.requested = null; // Clear request
+        applying = true;
+    }
+    return finalizeResult(errors, state, applying, shouldWrite);
+}
+function checkFrontmatterGate(gate) {
+    const filePath = path.join(process.cwd(), gate.file);
+    if (!fs.existsSync(filePath)) {
+        return {
+            code: "GATE_FILE_MISSING",
+            path: gate.file,
+            message: `Gate '${gate.id}' failed: File missing`,
+            remediation: `Create ${gate.file}`,
+            severity: "error"
+        };
+    }
+    try {
+        const content = fs.readFileSync(filePath, 'utf8');
+        const parsed = matter(content);
+        if (!parsed.data) {
+            return {
+                code: "GATE_NO_FRONTMATTER",
+                path: gate.file,
+                message: `Gate '${gate.id}' failed: No frontmatter found`,
+                remediation: "Add frontmatter variables",
+                severity: "error"
+            };
+        }
+        if (gate.field) {
+            const val = parsed.data[gate.field];
+            if (val === undefined) {
+                return {
+                    code: "GATE_FIELD_MISSING",
+                    path: gate.file,
+                    message: `Gate '${gate.id}' failed: Field '${gate.field}' missing`,
+                    remediation: `Add '${gate.field}' to frontmatter`,
+                    severity: "error"
+                };
+            }
+            if (gate.equals !== undefined && val !== gate.equals) {
+                return {
+                    code: "GATE_VALUE_MISMATCH",
+                    path: gate.file,
+                    message: `Gate '${gate.id}' failed: Field '${gate.field}' is '${val}', expected '${gate.equals}'`,
+                    remediation: `Set '${gate.field}: ${gate.equals}' in ${gate.file}`,
+                    severity: "error"
+                };
+            }
+        }
+        return null;
+    }
+    catch (e) {
+        return {
+            code: "GATE_PARSE_ERROR",
+            path: gate.file,
+            message: `Gate '${gate.id}' failed: Error parsing file: ${e}`,
+            severity: "error"
+        };
+    }
+}
+function checkOptionalUnits(errors) {
+    const intentsDir = path.join(process.cwd(), "memory-bank", "intents");
+    if (!fs.existsSync(intentsDir))
+        return;
+    try {
+        const intents = fs.readdirSync(intentsDir).filter(f => fs.statSync(path.join(intentsDir, f)).isDirectory());
+        for (const intent of intents) {
+            const unitsDir = path.join(intentsDir, intent, "units");
+            if (fs.existsSync(unitsDir) && fs.statSync(unitsDir).isDirectory()) {
+                // Units folder exists, check contents
+                const units = fs.readdirSync(unitsDir).filter(f => fs.statSync(path.join(unitsDir, f)).isDirectory());
+                for (const unit of units) {
+                    const briefPath = path.join(unitsDir, unit, "unit-brief.md");
+                    if (!fs.existsSync(briefPath)) {
+                        const relPath = path.relative(process.cwd(), briefPath);
+                        errors.push({
+                            code: "MISSING_ARTIFACT",
+                            path: relPath,
+                            message: `Unit '${unit}' requires unit-brief.md`,
+                            remediation: "Create from template",
+                            template: ".iris/aidlc/templates/unit-brief.md",
+                            artifactType: "file",
+                            severity: "error"
+                        });
+                    }
+                    else {
+                        // Check quality of unit brief too
+                        errors.push(...checkContentQuality(briefPath));
+                    }
+                }
+            }
+        }
+    }
+    catch (e) {
+        // Ignore read errors
+    }
+}
+function checkContentQuality(filePath) {
+    const warnings = [];
+    try {
+        const content = fs.readFileSync(filePath, "utf8");
+        const relativePath = path.relative(process.cwd(), filePath);
+        // 1. Effective emptiness
+        if (content.trim().length < 20) {
+            warnings.push({
+                code: "QUALITY_EMPTY",
+                path: relativePath,
+                message: `File is effectively empty (<20 chars): ${relativePath}`,
+                severity: "warning",
+                remediation: "Add meaningful content"
+            });
+        }
+        // 2. Placeholders
+        const placeholderRegex = /\b(TODO|FIXME|TBD)\b|<[^>]+>/;
+        if (placeholderRegex.test(content)) {
+            warnings.push({
+                code: "QUALITY_PLACEHOLDER",
+                path: relativePath,
+                message: `File contains placeholders (TODO/FIXME/TBD/<...>): ${relativePath}`,
+                severity: "warning",
+                remediation: "Replace placeholders with actual content"
+            });
+        }
+    }
+    catch (e) {
+        // Ignore read errors
+    }
+    return warnings;
+}
+function finalizeResult(errors, state, applied, writeBack) {
+    const hasErrors = errors.some(e => e.severity === "error");
+    const hasWarnings = errors.some(e => e.severity === "warning");
+    const isValid = !hasErrors;
+    if (writeBack) {
+        state.last_validation.at = new Date().toISOString();
+        state.last_validation.result = isValid ? "valid" : "invalid";
+        saveState(state);
+    }
+    return {
+        valid: isValid,
+        warnings: hasWarnings,
+        phase: {
+            current: state.phase.current,
+            requested: state.phase.requested,
+            applied: applied
+        },
+        errors: errors
+    };
+}

package/dist/lib.js

@@ -0,0 +1,96 @@
+import fs from "node:fs";
+import path from "node:path";
+import { spawn } from "node:child_process";
+export function repoRoot() {
+    return process.cwd();
+}
+export function ensureDir(p) {
+    fs.mkdirSync(p, { recursive: true });
+}
+export function copyDir(src, dst) {
+    ensureDir(dst);
+    for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+        const s = path.join(src, entry.name);
+        const d = path.join(dst, entry.name);
+        if (entry.isDirectory())
+            copyDir(s, d);
+        else if (entry.isSymbolicLink()) {
+            const link = fs.readlinkSync(s);
+            try {
+                fs.symlinkSync(link, d);
+            }
+            catch { /* ignore */ }
+        }
+        else {
+            ensureDir(path.dirname(d));
+            fs.copyFileSync(s, d);
+        }
+    }
+}
+export function removeDir(p) {
+    if (!fs.existsSync(p))
+        return;
+    fs.rmSync(p, { recursive: true, force: true });
+}
+export function writeFile(p, content) {
+    ensureDir(path.dirname(p));
+    fs.writeFileSync(p, content, "utf8");
+}
+/**
+ * Sanitize a folder name to be a valid npm package name
+ */
+export function sanitizeFolderName(name) {
+    return name
+        .toLowerCase()
+        .replace(/[^a-z0-9-_]/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .replace(/-+/g, "-")
+        || "my-project";
+}
+/**
+ * Check if npm is available in PATH
+ */
+export function hasNpm() {
+    try {
+        const result = spawn("npm", ["--version"], { stdio: "ignore" });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Spawn a command asynchronously and return the result
+ */
+export function spawnAsync(command, args, cwd) {
+    return new Promise((resolve) => {
+        const proc = spawn(command, args, {
+            cwd,
+            stdio: ["inherit", "pipe", "pipe"],
+            shell: true
+        });
+        let stdout = "";
+        let stderr = "";
+        if (proc.stdout) {
+            proc.stdout.on("data", (data) => {
+                const text = data.toString();
+                stdout += text;
+                process.stdout.write(text);
+            });
+        }
+        if (proc.stderr) {
+            proc.stderr.on("data", (data) => {
+                const text = data.toString();
+                stderr += text;
+                process.stderr.write(text);
+            });
+        }
+        proc.on("close", (code) => {
+            resolve({ code: code ?? 0, stdout, stderr });
+        });
+        proc.on("error", (err) => {
+            stderr += err.message;
+            resolve({ code: 1, stdout, stderr });
+        });
+    });
+}

package/dist/utils/exit-codes.js

@@ -0,0 +1,7 @@
+export const EXIT_CODES = {
+    SUCCESS: 0,
+    INVALID: 2, // Missing artifacts, failed gates, invalid transition
+    VALID_WITH_WARNINGS: 3,
+    POLICY_ERROR: 4, // Policy invalid
+    STATE_ERROR: 5, // State invalid/unwritable
+};

package/dist/workflows/bolt-execution.js

@@ -0,0 +1,238 @@
+import { randomUUID } from "crypto";
+import inquirer from "inquirer";
+import kleur from "kleur";
+import { WorkflowStage } from "../bridge/types.js";
+import { appendEvent, saveRun } from "../iris/run-state.js";
+/**
+ * Execute Bolt Execution stage
+ * For each bolt:
+ * 1. Design notes (optional gate)
+ * 2. Implementation
+ * 3. Testing
+ * 4. Gate after implementation
+ */
+export async function executeBoltExecution(runState, connector, options) {
+    console.log(kleur.bold("Bolt Execution Stage"));
+    console.log(kleur.dim(`Executing ${runState.bolts.length} bolt(s)\n`));
+    // Execute each bolt in order
+    while (runState.currentBoltIndex < runState.bolts.length) {
+        const bolt = runState.bolts[runState.currentBoltIndex];
+        console.log(kleur.bold(kleur.cyan(`\n=== Bolt ${runState.currentBoltIndex + 1}/${runState.bolts.length}: ${bolt.id} ===\n`)));
+        bolt.status = "in_progress";
+        saveRun(runState);
+        try {
+            await executeSingleBolt(runState, bolt, connector, options);
+            bolt.status = "completed";
+            runState.currentBoltIndex++;
+            saveRun(runState);
+            console.log(kleur.green(`✓ Bolt "${bolt.id}" completed\n`));
+        }
+        catch (error) {
+            console.error(kleur.red(`✗ Bolt "${bolt.id}" failed: ${error.message}\n`));
+            bolt.status = "failed";
+            saveRun(runState);
+            throw error;
+        }
+    }
+    // All bolts complete
+    console.log(kleur.bold(kleur.green("\n✓ All bolts executed successfully!")));
+    runState.stage = WorkflowStage.DONE;
+    saveRun(runState);
+}
+async function executeSingleBolt(runState, bolt, connector, options) {
+    // Step 1: Design (optional)
+    console.log(kleur.cyan("→ Design phase..."));
+    const designTaskId = randomUUID();
+    const designPacket = {
+        taskId: designTaskId,
+        intent: runState.intent,
+        stage: WorkflowStage.BOLT_EXECUTION,
+        agent: "iris-construction-agent",
+        instructions: `Design phase for bolt: ${bolt.id}
+
+Review the bolt file: memory-bank/operations/bolts/${bolt.id}.md
+
+Create design notes covering:
+- Domain model (if applicable)
+- Technical approach
+- Key decisions (ADRs if needed)
+- File structure
+
+You may create design notes inline in the bolt file or in separate files.
+This is optional but recommended for complex bolts.`,
+        inputs: [
+            `memory-bank/operations/bolts/${bolt.id}.md`,
+            ...runState.artifacts
+        ],
+        expectedOutputs: [],
+        metadata: { step: "design", boltId: bolt.id }
+    };
+    appendEvent(runState.runId, {
+        stage: WorkflowStage.BOLT_EXECUTION,
+        boltId: bolt.id,
+        action: "Design phase started",
+        taskId: designTaskId
+    });
+    if (!options.noBridge) {
+        await connector.sendTask(designPacket);
+        console.log(kleur.dim(`  Task sent: ${designTaskId}`));
+        console.log(kleur.dim("  Waiting for design notes...\n"));
+        const designResult = await connector.waitResult(designTaskId, {
+            timeoutMs: 600000 // 10 minutes
+        });
+        if (designResult.status === "ok") {
+            console.log(kleur.green("✓ Design complete"));
+            if (designResult.filesChanged) {
+                designResult.filesChanged.forEach(file => console.log(kleur.dim(`  - ${file}`)));
+            }
+            console.log("");
+            bolt.designCompleted = true;
+            appendEvent(runState.runId, {
+                stage: WorkflowStage.BOLT_EXECUTION,
+                boltId: bolt.id,
+                action: "Design completed",
+                outputs: designResult.filesChanged,
+                resultStatus: "ok"
+            });
+        }
+    }
+    else {
+        console.log(kleur.yellow("  Bridge disabled. Skipping design phase.\n"));
+    }
+    // Step 2: Implementation
+    console.log(kleur.cyan("→ Implementation phase..."));
+    const implTaskId = randomUUID();
+    const implPacket = {
+        taskId: implTaskId,
+        intent: runState.intent,
+        stage: WorkflowStage.BOLT_EXECUTION,
+        agent: "iris-construction-agent",
+        instructions: `Implementation phase for bolt: ${bolt.id}
+
+Review:
+- Bolt file: memory-bank/operations/bolts/${bolt.id}.md
+- Intent artifacts in memory-bank/intents/
+- Any design notes created
+
+Implement all tasks listed in the bolt file.
+Create/modify code files as needed.
+Follow the project's coding standards.
+
+Mark tasks as complete in the bolt file as you finish them.`,
+        inputs: [
+            `memory-bank/operations/bolts/${bolt.id}.md`,
+            ...runState.artifacts
+        ],
+        expectedOutputs: [],
+        gates: ["Implementation complete - ready for testing"],
+        metadata: { step: "implementation", boltId: bolt.id }
+    };
+    appendEvent(runState.runId, {
+        stage: WorkflowStage.BOLT_EXECUTION,
+        boltId: bolt.id,
+        action: "Implementation started",
+        taskId: implTaskId
+    });
+    if (!options.noBridge) {
+        await connector.sendTask(implPacket);
+        console.log(kleur.dim(`  Task sent: ${implTaskId}`));
+        console.log(kleur.dim("  Waiting for implementation...\n"));
+        const implResult = await connector.waitResult(implTaskId, {
+            timeoutMs: 1200000 // 20 minutes
+        });
+        if (implResult.status === "error") {
+            throw new Error(implResult.error || "Implementation failed");
+        }
+        console.log(kleur.green("✓ Implementation complete"));
+        if (implResult.filesChanged) {
+            implResult.filesChanged.forEach(file => console.log(kleur.dim(`  - ${file}`)));
+        }
+        console.log("");
+        bolt.implementationCompleted = true;
+        appendEvent(runState.runId, {
+            stage: WorkflowStage.BOLT_EXECUTION,
+            boltId: bolt.id,
+            action: "Implementation completed",
+            outputs: implResult.filesChanged,
+            resultStatus: "ok"
+        });
+    }
+    else {
+        console.log(kleur.yellow("  Bridge disabled. Skipping implementation.\n"));
+    }
+    // Step 3: Testing
+    console.log(kleur.cyan("→ Testing phase..."));
+    const testTaskId = randomUUID();
+    const testPacket = {
+        taskId: testTaskId,
+        intent: runState.intent,
+        stage: WorkflowStage.BOLT_EXECUTION,
+        agent: "iris-construction-agent",
+        instructions: `Testing phase for bolt: ${bolt.id}
+
+Run tests or propose test commands for the implemented changes.
+
+If tests exist, run them and report results.
+If no tests exist, propose what should be tested and expected outcomes.
+
+Include:
+- Test commands run
+- Test results
+- Any issues found`,
+        inputs: [
+            `memory-bank/operations/bolts/${bolt.id}.md`
+        ],
+        expectedOutputs: [],
+        metadata: { step: "testing", boltId: bolt.id }
+    };
+    appendEvent(runState.runId, {
+        stage: WorkflowStage.BOLT_EXECUTION,
+        boltId: bolt.id,
+        action: "Testing started",
+        taskId: testTaskId
+    });
+    if (!options.noBridge) {
+        await connector.sendTask(testPacket);
+        console.log(kleur.dim(`  Task sent: ${testTaskId}`));
+        console.log(kleur.dim("  Waiting for test results...\n"));
+        const testResult = await connector.waitResult(testTaskId, {
+            timeoutMs: 600000 // 10 minutes
+        });
+        console.log(kleur.green("✓ Testing complete"));
+        console.log(kleur.dim(`  ${testResult.message}`));
+        console.log("");
+        bolt.testingCompleted = true;
+        appendEvent(runState.runId, {
+            stage: WorkflowStage.BOLT_EXECUTION,
+            boltId: bolt.id,
+            action: "Testing completed",
+            message: testResult.message,
+            resultStatus: testResult.status
+        });
+    }
+    else {
+        console.log(kleur.yellow("  Bridge disabled. Skipping testing.\n"));
+    }
+    // Step 4: Gate - Approve bolt?
+    if (options.gate === "manual") {
+        console.log(kleur.bold(kleur.yellow("Gate: Bolt Completion")));
+        const { approved } = await inquirer.prompt([
+            {
+                type: "confirm",
+                name: "approved",
+                message: `Approve bolt "${bolt.id}" and continue?`,
+                default: true
+            }
+        ]);
+        appendEvent(runState.runId, {
+            stage: WorkflowStage.BOLT_EXECUTION,
+            boltId: bolt.id,
+            action: "Gate decision",
+            userGateDecision: approved ? "approved" : "rejected"
+        });
+        if (!approved) {
+            throw new Error("Bolt rejected by user");
+        }
+        console.log(kleur.green("✓ Bolt approved\n"));
+    }
+}