project-iris 0.0.1

package/dist/iris/interactive/intent-interview.js

@@ -0,0 +1,345 @@
+import kleur from "kleur";
+import fs from "fs";
+import { writeJsonAtomic } from "../fs/atomic.js";
+import { InquirerIO } from "./interview-io.js";
+import { ensureDir } from "../../lib.js";
+import { getInboxPath, getHistoryDraftPath, getLatestDraftPath, getLegacyDraftPath } from "../paths.js";
+import { createEmptyDraft, validateDraft } from "./intent-schema.js";
+// --- Rubric Logic Moved to Schema/Shared or kept here? ---
+// The prompt asked for logic in schema.ts? No, prompt asked for SCHEMA definition in schema.ts.
+// Let's keep logic in schema.ts or here. 
+// Actually, `calculateConfidence` is better in `intent-schema.ts` if we want to test it easily without inquirer deps.
+// But my previous `intent-schema.ts` didn't have `calculateConfidence`. 
+// I should probably move `calculateConfidence` into `intent-schema.ts` OR just import the type and keep logic here.
+// To minimize changes to `intent-schema.ts` which I already wrote, I will keep `calculateConfidence` here 
+// BUT I need to make sure I use the types correctly.
+// WAIT, I ALREADY WROTE `intent-schema.ts` WITHOUT `calculateConfidence`.
+// So I will implement `calculateConfidence` here in this file, extending the one in schema if needed or just standalone.
+// Re-defining locally to match the file I tried to write before
+// ACTUALLY, checking `intent-schema.ts` content from Step 193... it does NOT have calculateConfidence.
+// So I must implement it here.
+export function formatIntentDraft(draft) {
+    return `
+# Intent: ${draft.goal}
+
+## Context
+- **Target User:** ${draft.userType}
+- **Project Phase:** ${draft.projectPhase}
+- **Confidence:** ${draft.confidence.score}
+
+## Success Criteria
+${draft.successCriteria.length > 0 ? draft.successCriteria.map(c => `- ${c}`).join("\n") : "(None provided)"}
+
+## Technical Constraints
+${draft.constraints.map(c => `- ${c}`).join("\n")}
+
+## Tooling Stack
+${draft.tools.map(t => `- ${t}`).join("\n")}
+
+## Additional Details
+${draft.nonGoals.length > 0 ? `\n### Non-Goals\n${draft.nonGoals.map(x => `- ${x}`).join("\n")}` : ""}
+${draft.acceptanceTests.length > 0 ? `\n### Acceptance Tests\n${draft.acceptanceTests.map(x => `- ${x}`).join("\n")}` : ""}
+
+---
+*Generated via IRIS Interactive Interview*
+`.trim();
+}
+function calcConfidenceScore(draft) {
+    let score = 0;
+    const explanation = [];
+    // 1. Goal Clarity
+    if (draft.goal && draft.goal.split(" ").length > 3) {
+        score += 0.2;
+        explanation.push("+0.2 for clear goal statement");
+    }
+    else if (draft.goal) {
+        score += 0.1;
+        explanation.push("+0.1 for goal presence");
+    }
+    const successLen = draft.successCriteria?.length || 0;
+    if (successLen > 0) {
+        score += 0.2;
+        explanation.push(`+0.2 for ${successLen} success criteria`);
+    }
+    const acceptLen = draft.acceptanceTests?.length || 0;
+    if (acceptLen > 0) {
+        score += 0.1;
+        explanation.push(`+0.1 for ${acceptLen} acceptance tests`);
+    }
+    if (draft.constraints && draft.constraints.length > 0) {
+        score += 0.1;
+        explanation.push("+0.1 for identified constraints");
+    }
+    if (draft.tools && draft.tools.length > 0) {
+        score += 0.1;
+        explanation.push("+0.1 for tool selection");
+    }
+    if (draft.nonGoals && draft.nonGoals.length > 0) {
+        score += 0.1;
+        explanation.push("+0.1 for explicit non-goals");
+    }
+    if (draft.userType && draft.projectPhase) {
+        score += 0.1;
+        explanation.push("+0.1 for user context & phase");
+    }
+    score = Math.min(1.0, Math.max(0, Math.round(score * 10) / 10));
+    return { score, explanation };
+}
+// Export for tests if needed, but the main export is runIntentInterview
+export { calcConfidenceScore as calculateConfidence };
+// --- Interview Logic ---
+export async function runIntentInterview(initialIntent, config, existingDraft, io = new InquirerIO()) {
+    io.header("\n🎤 Interactive Intent Interview");
+    if (config?.guidance?.systemNotes) {
+        io.print(kleur.dim(config.guidance.systemNotes));
+    }
+    else {
+        io.print(kleur.dim("Let's clarify your goals before we start building.\n"));
+    }
+    const draftPartial = existingDraft ? { ...existingDraft } : createEmptyDraft();
+    // If we have an existing draft, we assume we are resuming/refining, so we don't overwrite unless intent is new?
+    // Actually if initialIntent is provided on resume, it might be the "follow up prompt" context, which isn't a draft field.
+    // But draftPartial.goal is the high level goal.
+    if (!existingDraft && initialIntent) {
+        draftPartial.goal = initialIntent;
+    }
+    // 1. Goal (Skip if exists)
+    if (!draftPartial.goal) {
+        const { goal } = await io.ask([
+            {
+                type: "input",
+                name: "goal",
+                message: config?.guidance?.starterQuestions?.[0] || "What are you trying to build?",
+                validate: (input) => input.trim().length > 0 || "Please provide a goal."
+            }
+        ]);
+        draftPartial.goal = goal;
+    }
+    else {
+        // If resuming or passed in arg
+        io.print(`${kleur.cyan("? ")}Goal: ${kleur.cyan(draftPartial.goal || "")}`);
+    }
+    // 2. User & Phase
+    const context = await io.ask([
+        {
+            type: "list",
+            name: "userType",
+            message: "Who is the primary user?",
+            choices: [
+                "Individual Developer",
+                "Team / Connectors",
+                "Enterprise / Organization",
+                "End Consumers"
+            ]
+        },
+        {
+            type: "list",
+            name: "projectPhase",
+            message: "What phase is this project in?",
+            choices: [
+                { name: "Inception (New Idea)", value: "Inception" },
+                { name: "Construction (Active Dev)", value: "Construction" },
+                { name: "Operations (Maintenance)", value: "Operations" }
+            ]
+        }
+    ]);
+    Object.assign(draftPartial, context);
+    // 3. Success Criteria (Required)
+    io.print("\n" + kleur.bold("Success Criteria"));
+    // Loop until we have at least one criteria (Enforcement)
+    while (true) {
+        io.print(kleur.dim("What must be true for this to be considered done? (Enter empty line to finish)"));
+        const criteria = [];
+        if (draftPartial.successCriteria)
+            criteria.push(...draftPartial.successCriteria);
+        while (true) {
+            const { item } = await io.ask([{
+                    type: "input",
+                    name: "item",
+                    message: `Criterion ${criteria.length + 1}:`
+                }]);
+            if (!item.trim())
+                break;
+            criteria.push(item.trim());
+        }
+        draftPartial.successCriteria = criteria;
+        if (criteria.length === 0) {
+            io.warn("⚠ At least one Success Criterion is required.");
+            const { retry } = await io.ask([{
+                    type: "confirm",
+                    name: "retry",
+                    message: "Try adding criteria again?",
+                    default: true
+                }]);
+            if (!retry) {
+                io.warn("Cannot proceed without success criteria. Interview cancelled.");
+                return null;
+            }
+        }
+        else {
+            break;
+        }
+    }
+    // 4. Constraints (Multi-select)
+    const { constraints } = await io.ask([
+        {
+            type: "checkbox",
+            name: "constraints",
+            message: "What constraints matter most?",
+            choices: [
+                "Time (Speed to Market)",
+                "Quality (Robustness)",
+                "Compliance / Security",
+                "Performance",
+                "Cost / Budget",
+                "Simplicity"
+            ]
+        }
+    ]);
+    draftPartial.constraints = constraints;
+    // 5. Tools
+    const { tools } = await io.ask([
+        {
+            type: "checkbox",
+            name: "tools",
+            message: "Which tools/platforms are involved?",
+            choices: [
+                { name: "Node.js / TypeScript", checked: true },
+                "Python",
+                "React / Frontend",
+                "Docker / K8s",
+                "AWS / Cloud",
+                "Database (SQL/NoSQL)"
+            ]
+        }
+    ]);
+    draftPartial.tools = tools;
+    // 6. Optional Fields
+    const { addMore } = await io.ask([{
+            type: "confirm",
+            name: "addMore",
+            message: "Add non-goals, risks, or acceptance tests? (Optional)",
+            default: false
+        }]);
+    if (addMore) {
+        // Non Goals
+        io.print("\n" + kleur.bold("Non-Goals (What are we NOT doing?)"));
+        while (true) {
+            const { item } = await io.ask([{ type: "input", name: "item", message: ">" }]);
+            if (!item.trim())
+                break;
+            if (!draftPartial.nonGoals)
+                draftPartial.nonGoals = [];
+            draftPartial.nonGoals.push(item.trim());
+        }
+        // Acceptance Tests
+        io.print("\n" + kleur.bold("Acceptance Tests (How will we verify?)"));
+        while (true) {
+            const { item } = await io.ask([{ type: "input", name: "item", message: ">" }]);
+            if (!item.trim())
+                break;
+            if (!draftPartial.acceptanceTests)
+                draftPartial.acceptanceTests = [];
+            draftPartial.acceptanceTests.push(item.trim());
+        }
+    }
+    // Calculate Confidence
+    const rubric = calcConfidenceScore(draftPartial);
+    // Assemble final draft
+    const draft = {
+        ...createEmptyDraft(),
+        ...draftPartial,
+        confidence: rubric,
+        // Ensure successCriteria is array
+        successCriteria: draftPartial.successCriteria || [],
+        createdAt: new Date().toISOString()
+    };
+    // Summary
+    io.divider();
+    io.header("📋 Intent Summary");
+    io.print(`Goal:      ${draft.goal}`);
+    io.print(`Context:   ${draft.userType} / ${draft.projectPhase}`);
+    io.print(`Criteria:  ${draft.successCriteria.length} items`);
+    io.print(`Tools:     ${draft.tools.join(", ")}`);
+    io.print("");
+    const scoreColor = draft.confidence.score > 0.7 ? kleur.green : draft.confidence.score > 0.4 ? kleur.yellow : kleur.red;
+    io.print(`Confidence Score: ${scoreColor(draft.confidence.score.toFixed(2) + " / 1.0")}`);
+    draft.confidence.explanation.forEach(exp => io.print(kleur.dim(`  ${exp}`)));
+    io.divider();
+    // Validation check
+    const val = validateDraft(draft);
+    if (!val.valid) {
+        io.warn(kleur.red("Draft validation failed:"));
+        val.errors.forEach(e => io.print(`- ${e}`));
+        io.print("Please restart or fix inputs.");
+        return null;
+    }
+    const { confirm } = await io.ask([
+        {
+            type: "confirm",
+            name: "confirm",
+            message: "Do you want to generate intent artifacts now?",
+            default: true
+        }
+    ]);
+    if (!confirm) {
+        io.warn("Interview cancelled. No artifacts generated.");
+        return null;
+    }
+    return draft;
+}
+/**
+ * Saves intent draft enforcing schema.
+ * @param writeLegacy If true, also writes .iris/inbox/intent-draft.json (deprecated)
+ */
+export function saveIntentDraft(root, draft, writeLegacy = false) {
+    const inboxDir = getInboxPath(root);
+    ensureDir(inboxDir);
+    // Enforce Schema Defaults & Versioning
+    const fullDraft = {
+        ...createEmptyDraft(),
+        ...draft,
+        createdAt: draft.createdAt || new Date().toISOString()
+    };
+    // Recalculate confidence if missing
+    if (!draft.confidence) {
+        fullDraft.confidence = calcConfidenceScore(fullDraft);
+    }
+    // 1. Save History
+    const historyFile = getHistoryDraftPath(root, new Date(fullDraft.createdAt));
+    // 2. Save Latest (Canonical)
+    const latestFile = getLatestDraftPath(root);
+    writeJsonAtomic(historyFile, fullDraft);
+    writeJsonAtomic(latestFile, fullDraft);
+    // 3. Optional Legacy
+    if (writeLegacy) {
+        const legacyFile = getLegacyDraftPath(root);
+        writeJsonAtomic(legacyFile, fullDraft);
+    }
+}
+/**
+ * Migrates legacy intent-draft.json to intent-draft.latest.json.
+ */
+export function migrateLegacyDraft(root) {
+    const legacyFile = getLegacyDraftPath(root);
+    const latestFile = getLatestDraftPath(root);
+    if (fs.existsSync(legacyFile) && !fs.existsSync(latestFile)) {
+        try {
+            const content = JSON.parse(fs.readFileSync(legacyFile, "utf-8"));
+            // Enforce schema by saving via normalized function
+            // Treat content as partial
+            if (!content.successCriteria) {
+                content.successCriteria = ["(Migrated from legacy draft)"];
+            }
+            // Re-save (generates latest + history)
+            // Do NOT write legacy again (avoid loop), so writeLegacy=false
+            saveIntentDraft(root, content, false);
+            return true;
+        }
+        catch (e) {
+            console.error(kleur.red(`Failed to migrate legacy draft: ${e}`));
+            return false;
+        }
+    }
+    return false;
+}

package/dist/iris/interactive/intent-schema.js

@@ -0,0 +1,28 @@
+export const CURRENT_SCHEMA_VERSION = "1";
+export function createEmptyDraft() {
+    return {
+        version: CURRENT_SCHEMA_VERSION,
+        createdAt: new Date().toISOString(),
+        goal: "",
+        userType: "",
+        projectPhase: "",
+        constraints: [],
+        tools: [],
+        successCriteria: [],
+        nonGoals: [],
+        assumptions: [],
+        risks: [],
+        acceptanceTests: [],
+        confidence: { score: 0, explanation: [] }
+    };
+}
+export function validateDraft(draft) {
+    const errors = [];
+    if (!draft.goal)
+        errors.push("Goal is required");
+    if (!draft.successCriteria || draft.successCriteria.length === 0) {
+        errors.push("At least one Success Criterion is required");
+    }
+    // We can add more strict checks here if needed
+    return { valid: errors.length === 0, errors };
+}

package/dist/iris/interactive/interview-io.js

@@ -0,0 +1,22 @@
+import inquirer from "inquirer";
+import kleur from "kleur";
+export class InquirerIO {
+    async ask(questions) {
+        // map Question interface to inquirer question
+        // Inquirer types are slightly different, but compatible enough for pass-through usually
+        const answers = await inquirer.prompt(questions);
+        return answers;
+    }
+    print(message) {
+        console.log(message);
+    }
+    header(text) {
+        console.log(kleur.bold(text));
+    }
+    divider() {
+        console.log(kleur.dim("=========================================="));
+    }
+    warn(message) {
+        console.log(kleur.yellow(message));
+    }
+}

package/dist/iris/interview/config.js

@@ -0,0 +1,71 @@
+import fs from "fs";
+import yaml from "js-yaml";
+import kleur from "kleur";
+import { KNOWN_INTENT_FIELDS } from "./types.js";
+export const DEFAULT_INTERVIEW_CONFIG = {
+    schemaVersion: 1,
+    required: ["successCriteria", "user", "problem"],
+    optional: ["nonGoals", "risks", "acceptanceTests"],
+    guidance: {
+        systemNotes: "You are a Product Manager / Business Analyst. Ask clarifying questions.",
+        starterQuestions: [
+            "Who is the user and what problem are we solving?",
+            "What does success look like (measurable)?",
+            "What are the constraints (time, budget, tech, legal)?"
+        ],
+        redFlags: ["Ambiguous scope", "No success metric"]
+    },
+    weights: {
+        successCriteria: 3,
+        risks: 2
+    },
+    fieldPrompts: {
+        successCriteria: "What does success look like? How will we measure it?",
+        user: "Who is the specific user for this feature?",
+        problem: "What core problem are we solving?",
+        risks: "Are there any risks or non-goals we should state?",
+        constraints: "Are there any technical or budget constraints?"
+    }
+};
+export function loadEffectiveInterviewConfig(framework) {
+    if (!framework || !framework.files.interview || !fs.existsSync(framework.files.interview)) {
+        return DEFAULT_INTERVIEW_CONFIG;
+    }
+    try {
+        const content = fs.readFileSync(framework.files.interview, "utf8");
+        const raw = yaml.load(content);
+        // 1. Schema Version Check
+        if (raw.schemaVersion !== 1) {
+            console.error(kleur.yellow(`IRIS_WARNING: Unsupported interview schema version ${raw.schemaVersion}. Using default.`));
+            return DEFAULT_INTERVIEW_CONFIG;
+        }
+        // 2. Strict Field Validation
+        const allFields = [...(raw.required || []), ...(raw.optional || [])];
+        const unknownFields = allFields.filter(f => !KNOWN_INTENT_FIELDS.has(f));
+        if (unknownFields.length > 0) {
+            console.error(kleur.yellow(`IRIS_WARNING: Invalid interview configuration. Unknown fields: ${unknownFields.join(", ")}. Using default.`));
+            return DEFAULT_INTERVIEW_CONFIG;
+        }
+        // 3. Merge with minimal defaults (or just return raw if we trust it completely?)
+        // The plan says "If invalid/missing return DEFAULT".
+        // But if valid, we return the parsed object.
+        // Should we merge fieldPrompts if missing? 
+        // Best to provide safety defaults for prompts if not overridden.
+        return {
+            schemaVersion: raw.schemaVersion,
+            required: raw.required || [],
+            optional: raw.optional || [],
+            guidance: {
+                systemNotes: raw.guidance?.systemNotes || DEFAULT_INTERVIEW_CONFIG.guidance.systemNotes,
+                starterQuestions: raw.guidance?.starterQuestions || DEFAULT_INTERVIEW_CONFIG.guidance.starterQuestions,
+                redFlags: raw.guidance?.redFlags || DEFAULT_INTERVIEW_CONFIG.guidance.redFlags
+            },
+            weights: raw.weights || {},
+            fieldPrompts: { ...DEFAULT_INTERVIEW_CONFIG.fieldPrompts, ...raw.fieldPrompts }
+        };
+    }
+    catch (e) {
+        console.error(kleur.yellow(`IRIS_WARNING: Failed to parse interview.yaml: ${e.message}. Using default.`));
+        return DEFAULT_INTERVIEW_CONFIG;
+    }
+}

package/dist/iris/interview/types.js

@@ -0,0 +1,16 @@
+export const KNOWN_INTENT_FIELDS = new Set([
+    'successCriteria',
+    'user',
+    'problem',
+    'constraints',
+    'nonGoals',
+    'risks',
+    'acceptanceTests',
+    'context',
+    'context.user',
+    'context.phase',
+    'visuals',
+    'name', // Sometimes inferred, but valid
+    'description', // Basic
+    'features', // High level
+]);

package/dist/iris/interview/utils.js

@@ -0,0 +1,38 @@
+/**
+ * Access a value in an object via dot-notation.
+ * Safe traversal: returns undefined if path breaks.
+ */
+export function getByPath(obj, path) {
+    if (!obj)
+        return undefined;
+    const parts = path.split('.');
+    let current = obj;
+    for (const part of parts) {
+        if (current === null || current === undefined)
+            return undefined;
+        current = current[part];
+    }
+    return current;
+}
+/**
+ * Checks if a value is "missing" according to strict interview rules.
+ * Missing = null, undefined, empty string "", whitespace-only string, or empty array [].
+ */
+export function isMissing(value) {
+    if (value === null || value === undefined)
+        return true;
+    if (typeof value === 'string')
+        return value.trim().length === 0;
+    if (Array.isArray(value))
+        return value.length === 0;
+    // Objects? We typically check leaf nodes, but an empty object {} usually counts as present for 'context'
+    // UNLESS the requirement is specifically context.user.
+    // So for generic objects, existence is enough.
+    return false;
+}
+/**
+ * Returns a list of required fields that are missing in the draft.
+ */
+export function getMissingFields(draft, requiredFields) {
+    return requiredFields.filter(field => isMissing(getByPath(draft, field)));
+}

package/dist/iris/manifest.js

@@ -0,0 +1,54 @@
+import fs from "fs";
+import path from "path";
+import yaml from "js-yaml";
+import { writeFile } from "../lib.js";
+const MANIFEST_PATH = path.join(process.cwd(), ".iris/manifest.yaml");
+export function loadManifest() {
+    if (!fs.existsSync(MANIFEST_PATH))
+        return null;
+    try {
+        const doc = yaml.load(fs.readFileSync(MANIFEST_PATH, "utf8"));
+        // Basic migration/defaulting if needed
+        return {
+            version: 1,
+            installed_at: new Date().toISOString(),
+            tools_selected: [],
+            paths_installed: [],
+            created_dirs: [],
+            ...doc
+        };
+    }
+    catch (e) {
+        console.error("Failed to parse manifest:", e);
+        return null;
+    }
+}
+export function saveManifest(manifest) {
+    writeFile(MANIFEST_PATH, yaml.dump(manifest));
+}
+export function updateManifest(updates) {
+    const current = loadManifest() || {
+        version: 1,
+        installed_at: new Date().toISOString(),
+        tools_selected: [],
+        paths_installed: [],
+        created_dirs: [],
+    };
+    const updated = {
+        ...current,
+        ...updates,
+        installed_at: new Date().toISOString(), // Always update timestamp
+        tools_selected: Array.from(new Set([...current.tools_selected, ...(updates.tools_selected || [])])),
+        paths_installed: mergePaths(current.paths_installed, updates.paths_installed || []),
+        created_dirs: Array.from(new Set([...current.created_dirs, ...(updates.created_dirs || [])])),
+    };
+    saveManifest(updated);
+}
+function mergePaths(current, updates) {
+    // Map current paths by path string for easy update
+    const map = new Map();
+    current.forEach(p => map.set(p.path, p));
+    // Apply updates
+    updates.forEach(p => map.set(p.path, p));
+    return Array.from(map.values());
+}