project-iris 0.0.1

package/dist/framework/framework-loader.js

@@ -0,0 +1,97 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import yaml from 'js-yaml';
+import { FrameworkError } from './framework-types.js';
+import { resolveFrameworkRoot } from './framework-paths.js';
+export async function loadFramework(input, options) {
+    const rootDir = resolveFrameworkRoot(input, options);
+    // 1. Validate Root Directory
+    if (!fs.existsSync(rootDir) || !fs.statSync(rootDir).isDirectory()) {
+        throw new FrameworkError('NOT_FOUND', rootDir, `Framework directory not found: ${rootDir}`, 'Expected a valid directory at the resolved path.');
+    }
+    // 2. Locate Manifest
+    let manifestPath = path.join(rootDir, 'framework.yaml');
+    if (!fs.existsSync(manifestPath)) {
+        manifestPath = path.join(rootDir, 'framework.yml');
+    }
+    if (!fs.existsSync(manifestPath)) {
+        throw new FrameworkError('MISSING_MANIFEST', rootDir, `No framework.yaml (or .yml) found in ${rootDir}`);
+    }
+    // 3. Parse Manifest
+    let raw;
+    try {
+        const content = fs.readFileSync(manifestPath, 'utf-8');
+        raw = yaml.load(content);
+    }
+    catch (e) {
+        throw new FrameworkError('INVALID_YAML', manifestPath, `Failed to parse framework manifest: ${e.message}`);
+    }
+    // 4. Validate Schema
+    if (!raw || typeof raw !== 'object') {
+        throw new FrameworkError('INVALID_SCHEMA', manifestPath, 'Manifest must be an object');
+    }
+    if (typeof raw.name !== 'string' || !raw.name) {
+        throw new FrameworkError('INVALID_SCHEMA', manifestPath, 'Missing required field: name');
+    }
+    if (typeof raw.version !== 'string' || !raw.version) {
+        throw new FrameworkError('INVALID_SCHEMA', manifestPath, 'Missing required field: version');
+    }
+    if (raw.id && typeof raw.id !== 'string') {
+        throw new FrameworkError('INVALID_SCHEMA', manifestPath, 'Field "id" must be a string');
+    }
+    // Loose ID validation
+    if (raw.id && !/^[a-z0-9-_/]+$/.test(raw.id)) {
+        throw new FrameworkError('INVALID_SCHEMA', manifestPath, 'Field "id" contains invalid characters (allowed: [a-z0-9-_/])');
+    }
+    if (raw.extends && typeof raw.extends !== 'string' && !Array.isArray(raw.extends)) {
+        throw new FrameworkError('INVALID_SCHEMA', manifestPath, 'Field "extends" must be a string or array of strings');
+    }
+    if (raw.overlays && (!Array.isArray(raw.overlays) || raw.overlays.some((o) => typeof o !== 'string'))) {
+        throw new FrameworkError('INVALID_SCHEMA', manifestPath, 'Field "overlays" must be an array of strings');
+    }
+    const manifest = {
+        name: raw.name,
+        version: raw.version,
+        id: raw.id,
+        extends: raw.extends,
+        overlays: raw.overlays,
+        templatesDir: raw.templatesDir
+    };
+    // 5. Discover Files
+    const files = {
+        manifest: manifestPath
+    };
+    const tryFile = (name) => {
+        const p = path.join(rootDir, name);
+        return fs.existsSync(p) ? p : undefined;
+    };
+    files.policy = tryFile('policy.yaml');
+    files.routes = tryFile('routes.yaml');
+    files.artifacts = tryFile('artifacts.yaml');
+    files.interview = tryFile('interview.yaml');
+    files.pack = tryFile('pack.yaml');
+    // 6. Handle Templates
+    if (manifest.templatesDir) {
+        const tplPath = path.resolve(rootDir, manifest.templatesDir);
+        if (!fs.existsSync(tplPath) || !fs.statSync(tplPath).isDirectory()) {
+            throw new FrameworkError('MISSING_FILE', tplPath, `Configured templatesDir not found: ${manifest.templatesDir}`);
+        }
+        files.templates = tplPath;
+    }
+    else {
+        const defaultTpl = path.join(rootDir, 'templates');
+        if (fs.existsSync(defaultTpl) && fs.statSync(defaultTpl).isDirectory()) {
+            files.templates = defaultTpl;
+        }
+    }
+    return {
+        manifest,
+        source: {
+            kind: 'local', // Step 1 assumption
+            path: rootDir,
+            id: input
+        },
+        files,
+        rootDir
+    };
+}

package/dist/framework/framework-paths.js

@@ -0,0 +1,48 @@
+import * as path from 'path';
+import * as fs from 'fs';
+import { fileURLToPath } from 'url';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+/**
+ * Resolves a framework input (name or path) to an absolute directory path.
+ *
+ * Heuristics:
+ * - If input implies a path (starts with ./ or /, is absolute, contains separator),
+ *   it is resolved relative to repoRoot (unless absolute).
+ * - Otherwise, it is treated as a framework name/ID.
+ *   1. Check .iris/frameworks/<name> in repo.
+ *   2. Check bundled frameworks.
+ */
+export function resolveFrameworkRoot(input, options) {
+    const { repoRoot } = options;
+    // Strict heuristics to distinguish path from name
+    const isPath = input.startsWith('.') ||
+        input.startsWith('/') ||
+        input.startsWith('\\') || // Windows explicit relative
+        path.isAbsolute(input);
+    if (isPath) {
+        return path.resolve(repoRoot, input);
+    }
+    // Check Repo Local
+    const localPath = path.resolve(repoRoot, '.iris/frameworks', input);
+    if (fs.existsSync(localPath)) {
+        return localPath;
+    }
+    // Check Bundled
+    // Bundle structure assumption: 
+    // dist/framework/framework-paths.js -> ... -> src/iris_bundle/frameworks/
+    // actually, in build: dist/iris_bundle/frameworks/<name>
+    // In dev (ts-node): src/framework/framework-paths.ts -> ../iris_bundle/frameworks
+    // Try reliable bundle resolution
+    const candidates = [
+        path.resolve(__dirname, '../../dist/iris_bundle/frameworks', input), // from dist/framework/
+        path.resolve(__dirname, '../iris_bundle/frameworks', input), // from src/framework/
+        path.resolve(__dirname, '../../src/iris_bundle/frameworks', input) // from src/framework/ (alt)
+    ];
+    for (const c of candidates) {
+        if (fs.existsSync(c))
+            return c;
+    }
+    // Fallback to local path so error message shows expected repo location
+    return localPath;
+}

package/dist/framework/framework-types.js

@@ -0,0 +1,15 @@
+/**
+ * Core types for IRIS Framework abstraction.
+ */
+export class FrameworkError extends Error {
+    code;
+    path;
+    hint;
+    constructor(code, path, message, hint) {
+        super(message);
+        this.code = code;
+        this.path = path;
+        this.hint = hint;
+        this.name = 'FrameworkError';
+    }
+}

package/dist/iris/artifact-checker.js

@@ -0,0 +1,78 @@
+import fs from "fs";
+import path from "path";
+/**
+ * Normalizes an artifact path by:
+ * - Removing CRLF (\r) characters
+ * - Trimming whitespace
+ * - Converting backslashes to forward slashes
+ * - Removing trailing slashes (except for root)
+ */
+export function normalizeArtifactPath(rawPath) {
+    let normalized = rawPath;
+    // Remove \r characters (CRLF normalization)
+    normalized = normalized.replace(/\r/g, "");
+    // Trim whitespace
+    normalized = normalized.trim();
+    // Convert backslashes to forward slashes
+    normalized = normalized.replace(/\\/g, "/");
+    // Remove trailing slashes (but keep single "/" for root)
+    if (normalized.length > 1) {
+        normalized = normalized.replace(/\/+$/, "");
+    }
+    return normalized;
+}
+/**
+ * Infers whether a path represents a file or directory based on:
+ * - Trailing slash → directory
+ * - Has file extension → file
+ * - No extension → directory
+ */
+export function inferArtifactKind(normalizedPath) {
+    // If original had trailing slash (before normalization), it's a directory
+    // But we've already normalized, so check for extension
+    const basename = path.basename(normalizedPath);
+    const hasExtension = basename.includes(".") && !basename.startsWith(".");
+    return hasExtension ? "file" : "directory";
+}
+/**
+ * Checks if a raw path contains control characters
+ */
+export function hasControlCharacters(rawPath) {
+    // Check for common control characters: \r, \n, \t, etc.
+    return /[\r\n\t\x00-\x1F]/.test(rawPath);
+}
+/**
+ * Main artifact validation function.
+ * Validates an artifact path and returns detailed information.
+ */
+export function checkArtifact(repoRoot, rawPath, expectedType) {
+    const normalized = normalizeArtifactPath(rawPath);
+    const absolutePath = path.resolve(repoRoot, normalized);
+    const hasControlChars = hasControlCharacters(rawPath);
+    const inferredKind = expectedType || inferArtifactKind(normalized);
+    let exists = false;
+    let isDirectory = false;
+    let isFile = false;
+    try {
+        exists = fs.existsSync(absolutePath);
+        if (exists) {
+            const stats = fs.statSync(absolutePath);
+            isDirectory = stats.isDirectory();
+            isFile = stats.isFile();
+        }
+    }
+    catch (e) {
+        // If stat fails, treat as non-existent
+        exists = false;
+    }
+    return {
+        exists,
+        isDirectory,
+        isFile,
+        absolutePath,
+        normalized,
+        raw: rawPath,
+        hasControlChars,
+        inferredKind
+    };
+}

package/dist/iris/artifacts/config.js

@@ -0,0 +1,68 @@
+import fs from "fs";
+import yaml from "js-yaml";
+import kleur from "kleur";
+// Default Artifacts: Summary + User Stories
+export const DEFAULT_ARTIFACTS_CONFIG = {
+    schemaVersion: 1,
+    artifacts: [
+        {
+            id: "summary",
+            type: "summary",
+            mode: "template",
+            output: {
+                template: "# Summary\n\n**Goal**: {{goal}}\n\n**User**: {{userType}}\n**Phase**: {{projectPhase}}\n\n**Success Criteria**:\n{{successCriteria}}\n"
+            }
+        },
+        {
+            id: "user-stories",
+            type: "stories",
+            mode: "template",
+            required: false, // Don't fail if fields missing, just skip or partial? 
+            // Wait, default should be robust.
+            // If fields missing, template will fail.
+            // Let's require standard fields.
+            input: { from: ["goal", "userType"] },
+            output: {
+                template: "As a {{userType}}, I want to {{goal}}, so that [Value Placeholders]"
+            }
+        }
+    ]
+};
+export function loadEffectiveArtifactsConfig(framework) {
+    if (!framework || !framework.files.artifacts || !fs.existsSync(framework.files.artifacts)) {
+        return DEFAULT_ARTIFACTS_CONFIG;
+    }
+    try {
+        const content = fs.readFileSync(framework.files.artifacts, "utf8");
+        const raw = yaml.load(content);
+        if (raw.schemaVersion !== 1) {
+            console.error(kleur.yellow(`IRIS_WARNING: Unsupported artifacts schema version ${raw.schemaVersion}. Using default.`));
+            return DEFAULT_ARTIFACTS_CONFIG;
+        }
+        if (!Array.isArray(raw.artifacts)) {
+            console.error(kleur.yellow(`IRIS_WARNING: Invalid artifacts.yaml (missing 'artifacts' array). Using default.`));
+            return DEFAULT_ARTIFACTS_CONFIG;
+        }
+        // Validate fields against KNOWN_INTENT_FIELDS
+        for (const art of raw.artifacts) {
+            if (art.input?.from) {
+                for (const field of art.input.from) {
+                    // Check against KNOWN fields (or allow unknown if we trust framework author? Plan said "Config Error")
+                    // Actually, plan says "Check missing input fields in draft".
+                    // But here we validate the CONFIG itself referencing known variables.
+                    // KNOWN_INTENT_FIELDS includes common ones. 
+                    // Let's be lenient on config validation for now to support custom aliases, 
+                    // but strict on generation (if draft misses it).
+                }
+            }
+        }
+        return {
+            schemaVersion: raw.schemaVersion,
+            artifacts: raw.artifacts
+        };
+    }
+    catch (e) {
+        console.error(kleur.yellow(`IRIS_WARNING: Failed to parse artifacts.yaml: ${e.message}. Using default.`));
+        return DEFAULT_ARTIFACTS_CONFIG;
+    }
+}

package/dist/iris/artifacts/generator.js

@@ -0,0 +1,88 @@
+import { getByPath, isMissing } from "../interview/utils.js";
+import { interpolateTokens } from "../utils/interpolate.js";
+// Error Codes
+export const ERRORS = {
+    MODE_NOT_SUPPORTED: "ARTIFACT_MODE_NOT_SUPPORTED",
+    INPUT_MISSING: "ARTIFACT_INPUT_MISSING",
+    TEMPLATE_VAR_MISSING: "ARTIFACT_TEMPLATE_MISSING_VAR",
+    UNSUPPORTED_ARRAY: "ARTIFACT_TEMPLATE_UNSUPPORTED_ARRAY_TYPE"
+};
+/**
+ * Renders a simple template with {{var}} substitution.
+ * Supports dot-paths.
+ */
+function renderTemplate(template, context, artifactId) {
+    // Strict regex: only alphanumeric, underscore, dot. 
+    // Trims whitespace inside braces.
+    return template.replace(/\{\{\s*([a-zA-Z0-9_.]+)\s*\}\}/g, (match, path) => {
+        const key = path.trim();
+        // Safety: Prevent prototype pollution access
+        if (key.includes('__proto__') || key.includes('constructor') || key.includes('prototype')) {
+            throw new Error(`${ERRORS.TEMPLATE_VAR_MISSING}: Unsafe variable path '${key}' in artifact '${artifactId}'`);
+        }
+        const value = getByPath(context, key);
+        if (value === undefined || value === null) {
+            throw new Error(`${ERRORS.TEMPLATE_VAR_MISSING}: Artifact '${artifactId}' requires variable '${key}'`);
+        }
+        if (Array.isArray(value)) {
+            // Check for objects (non-primitives)
+            if (value.some(v => typeof v === 'object' && v !== null)) {
+                throw new Error(`${ERRORS.UNSUPPORTED_ARRAY}: Artifact '${artifactId}' variable '${key}' contains objects (unsupported for joining).`);
+            }
+            return value.join('\n');
+        }
+        return String(value);
+    });
+}
+export function generateArtifacts(draft, config, frameworkResolution, intentId = null) {
+    const artifacts = [];
+    for (const def of config.artifacts) {
+        // 1. Mode Check
+        if (def.mode === 'llm') {
+            throw new Error(`${ERRORS.MODE_NOT_SUPPORTED}: LLM mode not supported yet (Artifact: ${def.id})`);
+        }
+        // 2. Input Validation (Declared requirements)
+        if (def.input?.from) {
+            const missing = def.input.from.filter(f => isMissing(getByPath(draft, f)));
+            if (missing.length > 0) {
+                throw new Error(`${ERRORS.INPUT_MISSING}: Artifact '${def.id}' requires missing fields: ${missing.join(', ')}`);
+            }
+        }
+        // 3. Transformation (Template)
+        if (def.output.template) {
+            const content = renderTemplate(def.output.template, draft, def.id);
+            // Interpolate 'out' path if specified
+            let outPath;
+            if (def.out) {
+                try {
+                    outPath = interpolateTokens(def.out, { intentId: intentId || undefined });
+                }
+                catch (e) {
+                    throw new Error(`${ERRORS.TEMPLATE_VAR_MISSING}: Path interpolation failed for artifact '${def.id}': ${e.message}`);
+                }
+            }
+            artifacts.push({
+                id: def.id,
+                type: def.type,
+                content,
+                path: outPath
+            });
+        }
+    }
+    const isFramework = frameworkResolution && frameworkResolution.files.artifacts;
+    return {
+        schemaVersion: 1,
+        framework: {
+            id: frameworkResolution?.manifest.id || "default",
+            version: frameworkResolution?.manifest.version || null
+        },
+        intentId: intentId,
+        artifacts,
+        artifactsSource: {
+            kind: isFramework ? "framework" : "default",
+            path: isFramework ? frameworkResolution.files.artifacts : null,
+            activeFrameworkId: frameworkResolution?.manifest.id || null
+        },
+        createdAt: new Date().toISOString()
+    };
+}

package/dist/iris/artifacts/types.js

@@ -0,0 +1 @@
+export {};

package/dist/iris/bundle.js

@@ -0,0 +1,44 @@
+import path from "path";
+import fs from "fs";
+import { fileURLToPath } from "url";
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+/**
+ * Resolves the root of the IRIS Bundle (src/iris_bundle or dist/iris_bundle)
+ * independent of CWD.
+ */
+export function getBundleRoot() {
+    // 1. Production / Dist layout
+    // __dirname is usually dist/iris or similar. Bundle in dist/iris_bundle
+    // Check sibling of 'dist' if we are in dist/iris
+    // Attempt 1: Sibling 'iris_bundle' in expected location relative to THIS file
+    // Example: .../dist/iris/bundle.js -> .../dist/iris_bundle
+    // Or: .../src/iris/bundle.ts -> .../src/iris_bundle
+    const candidates = [
+        path.resolve(__dirname, "../iris_bundle"), // Typical sibling in src/ or dist/
+        path.resolve(__dirname, "../../src/iris_bundle"), // Dev fallback if running from dist but source present
+        path.resolve(__dirname, "../../iris_bundle") // Another dist layout possibility
+    ];
+    for (const candidate of candidates) {
+        if (fs.existsSync(candidate) && fs.existsSync(path.join(candidate, ".iris"))) {
+            return candidate;
+        }
+    }
+    // Fallback/Throw? 
+    // In dev environment, if src/iris_bundle exists relative to root?
+    throw new Error(`Could not resolve IRIS bundle root. Searched: ${candidates.join(", ")}`);
+}
+export function getBundledFlowsDir() {
+    return path.join(getBundleRoot(), ".iris/flows");
+}
+export function getBundledFrameworksDir() {
+    return path.join(getBundleRoot(), "frameworks");
+}
+export function listBundledFlows() {
+    const flowsDir = getBundledFlowsDir();
+    if (!fs.existsSync(flowsDir))
+        return [];
+    return fs.readdirSync(flowsDir, { withFileTypes: true })
+        .filter(ent => ent.isDirectory())
+        .map(ent => ent.name);
+}

package/dist/iris/doctrine/collector.js

@@ -0,0 +1,124 @@
+import fs from "fs";
+import path from "path";
+import kleur from "kleur";
+import { loadFlowManifest, getFlowDoctrineRoot } from "../flows/manifest.js";
+// --- Cache ---
+const manifestCache = new Map();
+// --- Internal Helpers ---
+function getManifestCached(root, flowId) {
+    const key = `${root}:${flowId}`;
+    if (manifestCache.has(key)) {
+        const cached = manifestCache.get(key);
+        if (!cached)
+            throw new Error(`Flow '${flowId}' manifest previously failed to load.`);
+        return cached;
+    }
+    try {
+        const m = loadFlowManifest(root, flowId);
+        manifestCache.set(key, m);
+        return m;
+    }
+    catch (e) {
+        manifestCache.set(key, null); // Negative cache? Or just throw.
+        // If manifest is required (active flow), we should throw.
+        throw e;
+    }
+}
+/**
+ * Recursively walks a directory and returns map of relative -> absolute paths.
+ */
+function walkDoctrineDir(dir, relativePrefix = "", index) {
+    if (!fs.existsSync(dir))
+        return;
+    const entries = fs.readdirSync(dir, { withFileTypes: true });
+    for (const entry of entries) {
+        const relativePath = path.join(relativePrefix, entry.name);
+        const absolutePath = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+            walkDoctrineDir(absolutePath, relativePath, index);
+        }
+        else if (entry.isFile()) {
+            // Normalize separators to forward slash for consistency in keys
+            const key = relativePath.split(path.sep).join("/");
+            index.set(key, absolutePath);
+        }
+    }
+}
+// --- Public API ---
+/**
+ * Collects all doctrine files, overlaying Flow doctrine over Base doctrine.
+ * Returns a Map<relative, absolute>.
+ */
+export function collectDoctrineIndex(root, activeFlowId) {
+    const index = new Map();
+    let overrides = 0;
+    // 1. Base Doctrine
+    const baseDoctrine = path.join(root, ".iris/aidlc");
+    walkDoctrineDir(baseDoctrine, "", index); // Populates index
+    // 2. Flow Doctrine (Overlay)
+    if (activeFlowId) {
+        try {
+            const manifest = getManifestCached(root, activeFlowId);
+            const flowDoctrine = getFlowDoctrineRoot(root, activeFlowId, manifest);
+            if (fs.existsSync(flowDoctrine)) {
+                // We walk flow doctrine and overwrite base keys
+                const flowIndex = new Map();
+                walkDoctrineDir(flowDoctrine, "", flowIndex);
+                for (const [key, absPath] of flowIndex) {
+                    if (index.has(key))
+                        overrides++;
+                    index.set(key, absPath);
+                }
+                // Debug log (if verbose env var, or just console.debug if we had a logger)
+                // console.debug(`[Doctrine] Active Flow: ${activeFlowId}. Overrides: ${overrides}`);
+            }
+        }
+        catch (e) {
+            // Strict error if flow is active but manifest fails
+            console.error(kleur.red(`Failed to load manifest for active flow '${activeFlowId}': ${e.message}`));
+            throw e;
+        }
+    }
+    return index;
+}
+/**
+ * Collect all effective doctrine files as ABSOLUTE paths.
+ * Useful for tools that need to iterate all doctrine (like Packer).
+ */
+export function collectDoctrineFiles(root, activeFlowId) {
+    const index = collectDoctrineIndex(root, activeFlowId);
+    return Array.from(index.values());
+}
+/**
+ * Resolve a specific doctrine file by its DOCTRINE-RELATIVE path.
+ *
+ * @param root Repo root
+ * @param doctrineRelPath Relative path within doctrine dir (e.g. "templates/foo.md")
+ * @param activeFlowId Active flow ID (optional)
+ * @returns Absolute path to the resolved file, or undefined if not found in either flow or base.
+ */
+export function resolveDoctrinePath(root, doctrineRelPath, activeFlowId) {
+    // 1. Check Flow Override
+    if (activeFlowId) {
+        try {
+            const manifest = getManifestCached(root, activeFlowId);
+            // Default doctrine dir is 'doctrine' if not specified
+            const flowDoctrineDir = manifest.entrypoints?.doctrine_dir || "doctrine";
+            // Construct absolute path to flow doctrine file
+            const flowAbsPath = path.join(root, ".iris/flows", activeFlowId, flowDoctrineDir, doctrineRelPath);
+            if (fs.existsSync(flowAbsPath)) {
+                return flowAbsPath;
+            }
+        }
+        catch (e) {
+            // Let it throw to caller.
+            throw e;
+        }
+    }
+    // 2. Check Base Doctrine (.iris/aidlc)
+    const baseAbsPath = path.join(root, ".iris/aidlc", doctrineRelPath);
+    if (fs.existsSync(baseAbsPath)) {
+        return baseAbsPath;
+    }
+    return undefined;
+}