project-iris 0.0.8 → 0.0.12

package/dist/iris/flows/manifest.js

@@ -0,0 +1,124 @@
+import path from "path";
+import fs from "fs";
+import yaml from "js-yaml";
+// --- Errors ---
+export class FlowNotFoundError extends Error {
+    flowId;
+    path;
+    constructor(flowId, path) {
+        super(`Flow '${flowId}' not found at ${path}`);
+        this.flowId = flowId;
+        this.path = path;
+        this.name = "FlowNotFoundError";
+    }
+}
+export class FlowManifestValidationError extends Error {
+    flowId;
+    constructor(flowId, message) {
+        super(`Invalid manifest for flow '${flowId}': ${message}`);
+        this.flowId = flowId;
+        this.name = "FlowManifestValidationError";
+    }
+}
+// --- Constants & Defaults ---
+const DEFAULT_ENTRYPOINTS = {
+    doctrine_dir: "doctrine",
+    policy_overlay: "policy.overlay.yaml",
+    routes_overlay: "routes.overlay.yaml"
+};
+// --- Helpers ---
+export function getFlowsDir(root) {
+    return path.join(root, ".iris/flows");
+}
+export function getFlowDir(root, flowId) {
+    return path.join(getFlowsDir(root), flowId);
+}
+export function getFlowDoctrineRoot(root, flowId, manifest) {
+    return path.join(getFlowDir(root, flowId), manifest.entrypoints.doctrine_dir);
+}
+export function getFlowPolicyOverlayPath(root, flowId, manifest) {
+    return path.join(getFlowDir(root, flowId), manifest.entrypoints.policy_overlay);
+}
+export function getFlowRoutesOverlayPath(root, flowId, manifest) {
+    return path.join(getFlowDir(root, flowId), manifest.entrypoints.routes_overlay);
+}
+// --- Loader ---
+export function loadFlowManifest(root, flowId) {
+    const flowDir = getFlowDir(root, flowId);
+    const manifestPath = path.join(flowDir, "flow.yaml");
+    if (!fs.existsSync(manifestPath)) {
+        throw new FlowNotFoundError(flowId, manifestPath);
+    }
+    let raw;
+    try {
+        raw = yaml.load(fs.readFileSync(manifestPath, "utf8"));
+    }
+    catch (e) {
+        throw new FlowManifestValidationError(flowId, `Failed to parse YAML: ${e.message}`);
+    }
+    if (!raw || typeof raw !== "object") {
+        throw new FlowManifestValidationError(flowId, "Manifest is not a valid object");
+    }
+    // Validation: Required Fields
+    if (!raw.id || typeof raw.id !== "string" || !raw.id.trim()) {
+        throw new FlowManifestValidationError(flowId, "Missing or empty 'id'");
+    }
+    if (!raw.name || typeof raw.name !== "string" || !raw.name.trim()) {
+        throw new FlowManifestValidationError(flowId, "Missing or empty 'name'");
+    }
+    if (!raw.version || typeof raw.version !== "string" || !raw.version.trim()) {
+        throw new FlowManifestValidationError(flowId, "Missing or empty 'version'");
+    }
+    // Validation: ID Match
+    if (raw.id !== flowId) {
+        throw new FlowManifestValidationError(flowId, `Manifest ID '${raw.id}' does not match flow ID '${flowId}'`);
+    }
+    // Defaults & Entrypoint Validation
+    const entrypoints = { ...DEFAULT_ENTRYPOINTS, ...(raw.entrypoints || {}) };
+    // Validate Paths
+    validateRelativePath(flowId, "doctrine_dir", entrypoints.doctrine_dir);
+    validateRelativePath(flowId, "policy_overlay", entrypoints.policy_overlay);
+    validateRelativePath(flowId, "routes_overlay", entrypoints.routes_overlay);
+    return {
+        id: raw.id,
+        name: raw.name,
+        version: raw.version,
+        description: raw.description,
+        entrypoints
+    };
+}
+function validateRelativePath(flowId, field, p) {
+    if (!p || typeof p !== "string" || !p.trim()) {
+        throw new FlowManifestValidationError(flowId, `Entrypoint '${field}' must be a non-empty string`);
+    }
+    if (path.isAbsolute(p)) {
+        throw new FlowManifestValidationError(flowId, `Entrypoint '${field}' must be relative`);
+    }
+    const normalized = path.normalize(p);
+    if (normalized.startsWith("..") || normalized === ".." || normalized.includes(path.sep + "..")) {
+        throw new FlowManifestValidationError(flowId, `Entrypoint '${field}' cannot traverse upwards`);
+    }
+}
+export function listInstalledFlows(root) {
+    const flowsDir = getFlowsDir(root);
+    if (!fs.existsSync(flowsDir))
+        return [];
+    const results = [];
+    const entries = fs.readdirSync(flowsDir, { withFileTypes: true });
+    for (const entry of entries) {
+        if (!entry.isDirectory())
+            continue;
+        const flowId = entry.name;
+        try {
+            // This will validate schema and ID match
+            const manifest = loadFlowManifest(root, flowId);
+            results.push(manifest);
+        }
+        catch (e) {
+            // Ignore invalid/partial flows during listing unless specific debug needed?
+            // User requested: "don't crash on partial folders"
+            // We sip it.
+        }
+    }
+    return results;
+}

package/dist/iris/framework-context.js

@@ -0,0 +1,49 @@
+import kleur from "kleur";
+import { loadState, getActiveFramework } from "./state.js";
+import { loadFramework } from "../framework/framework-loader.js";
+import { FrameworkError } from "../framework/framework-types.js";
+import { repoRoot } from "../lib.js";
+/**
+ * Resolves the currently active framework from state.
+ * Centralizes logic for commands to obtain the framework context.
+ *
+ * Rules:
+ * 1. Reads .iris/state.yaml for active ID.
+ * 2. Attempts to load framework.
+ * 3. Returns structured context (success or failure).
+ * 4. Prints warning to stderr if load fails (but returns context so caller can decide fallback).
+ */
+export async function resolveActiveFramework(root) {
+    const r = root || repoRoot();
+    const state = loadState(); // loadState() takes no args currently
+    const activeFw = getActiveFramework(state);
+    try {
+        const resolution = await loadFramework(activeFw.current, { repoRoot: r });
+        return {
+            activeId: activeFw.current,
+            activeVersion: activeFw.version,
+            resolution,
+            error: null
+        };
+    }
+    catch (err) {
+        // If it's a known FrameworkError, return it.
+        // If generic error, wrap it? loadFramework usually throws FrameworkError or Error.
+        let fwError;
+        if (err instanceof FrameworkError) {
+            fwError = err;
+        }
+        else {
+            // Generic error wrapper
+            fwError = new FrameworkError("INVALID_YAML", activeFw.current, `Failed to load framework '${activeFw.current}': ${err instanceof Error ? err.message : String(err)}`);
+        }
+        // Emit Warning as requested
+        console.error(kleur.yellow(`IRIS_WARNING IRIS_FRAMEWORK_LOAD_FAILED: Could not load active framework '${activeFw.current}'. Reason: ${fwError.message}`));
+        return {
+            activeId: activeFw.current,
+            activeVersion: activeFw.version,
+            resolution: null,
+            error: fwError
+        };
+    }
+}

package/dist/iris/framework-manager.js

@@ -0,0 +1,215 @@
+import fs from "fs";
+import path from "path";
+import { FrameworkError } from "../framework/framework-types.js";
+import { loadFramework } from "../framework/framework-loader.js";
+import { getBundledFrameworksDir } from "./bundle.js";
+import { copyDir, ensureDir } from "../lib.js";
+import { loadState, getActiveFramework } from "./state.js";
+// --- Validation ---
+/**
+ * Validates a framework ID.
+ * Defaults to strict mode: ^[a-z0-9][a-z0-9-_]*$
+ * Future: allowScoped option.
+ */
+export function validateFrameworkId(id, options = {}) {
+    const { allowScoped = false } = options;
+    if (!id || typeof id !== 'string')
+        return false;
+    // Strict mode (current default)
+    // Starts with alphanumeric, followed by alphanumeric, -, _
+    // TODO: Support scoped IDs (e.g. @scope/pkg) in future version.
+    // Suggestion: Store scoped IDs under .iris/frameworks/@scope__pkg (encoded) to keep flat structure.
+    const strictRegex = /^[a-z0-9][a-z0-9-_]*$/;
+    return strictRegex.test(id);
+}
+// --- Listing ---
+export async function listInstalledFrameworks(root) {
+    const frameworksDir = path.join(root, ".iris/frameworks");
+    const state = loadState();
+    const activeFw = getActiveFramework(state);
+    if (!fs.existsSync(frameworksDir)) {
+        return [];
+    }
+    const entries = fs.readdirSync(frameworksDir, { withFileTypes: true });
+    const results = [];
+    for (const entry of entries) {
+        if (!entry.isDirectory())
+            continue;
+        // Ignore temp directories from failed atomic installs
+        if (entry.name.startsWith('.tmp-'))
+            continue;
+        const fwPath = path.join(frameworksDir, entry.name);
+        // Ensure active checking uses the folder name derived ID if logical ID is missing?
+        // Actually framework state uses the ID.
+        const isActive = activeFw.current === entry.name;
+        try {
+            const resolution = await loadFramework(entry.name, { repoRoot: root });
+            results.push({
+                id: resolution.manifest.id || entry.name, // Source of truth fallback
+                version: resolution.manifest.version,
+                path: fwPath,
+                valid: true,
+                active: isActive,
+                manifest: resolution.manifest
+            });
+        }
+        catch (error) {
+            results.push({
+                id: entry.name, // Fallback to folder name
+                version: null,
+                path: fwPath,
+                valid: false,
+                active: isActive,
+                error: {
+                    code: error.code || 'UNKNOWN',
+                    message: error.message || String(error)
+                }
+            });
+        }
+    }
+    return results;
+}
+export async function listBundledFrameworks() {
+    const bundleDir = getBundledFrameworksDir();
+    if (!fs.existsSync(bundleDir)) {
+        return [];
+    }
+    const entries = fs.readdirSync(bundleDir, { withFileTypes: true });
+    const results = [];
+    for (const entry of entries) {
+        if (!entry.isDirectory())
+            continue;
+        const fwPath = path.join(bundleDir, entry.name);
+        try {
+            // Load explicitly from path
+            const resolution = await loadFramework(fwPath, { repoRoot: "/" });
+            results.push({
+                id: resolution.manifest.id || entry.name,
+                path: fwPath,
+                version: resolution.manifest.version,
+                valid: true
+            });
+        }
+        catch (e) {
+            results.push({
+                id: entry.name,
+                path: fwPath,
+                valid: false,
+                error: e.message
+            });
+        }
+    }
+    return results;
+}
+// --- Installation ---
+export async function installFrameworkFromPath(root, sourcePath, options = {}) {
+    const frameworksDir = path.join(root, ".iris/frameworks");
+    ensureDir(frameworksDir);
+    // 1. Validate Source & Get ID
+    // We load it to ensure it's a valid framework AND to get the canonical ID
+    let resolution;
+    try {
+        resolution = await loadFramework(sourcePath, { repoRoot: root });
+    }
+    catch (e) {
+        throw new FrameworkError('INSTALL_FAILED', sourcePath, `Failed to load source framework: ${e.message}`, e.hint);
+    }
+    // Ensure ID is present
+    const id = resolution.manifest.id;
+    if (!id) {
+        throw new FrameworkError('INVALID_SCHEMA', sourcePath, `Framework manifest missing required 'id' field.`);
+    }
+    // 2. Validate ID (Strict)
+    if (!validateFrameworkId(id)) {
+        throw new FrameworkError('INVALID_ID', id, `Framework ID '${id}' is invalid.`, "IDs must match ^[a-z0-9][a-z0-9-_]*$");
+    }
+    // 3. Resolve Target Path & Safety Guard
+    const targetPath = path.resolve(frameworksDir, id);
+    // Guard: Path Traversal
+    if (!targetPath.startsWith(path.resolve(frameworksDir) + path.sep)) {
+        throw new FrameworkError('SECURITY_VIOLATION', id, `Invalid framework ID '${id}': Resulting path traverses outside frameworks directory.`);
+    }
+    // 4. Check Existence
+    if (fs.existsSync(targetPath)) {
+        if (!options.force) {
+            throw new FrameworkError('ALREADY_EXISTS', targetPath, `Framework '${id}' is already installed.`, "Use --force to overwrite.");
+        }
+    }
+    // 5. Atomic Install
+    // Copy to .tmp-<id>-<random>
+    const tempName = `.tmp-${id}-${Math.random().toString(36).substring(7)}`;
+    const tempPath = path.join(frameworksDir, tempName);
+    try {
+        // Copy recursive
+        copyDir(resolution.rootDir, tempPath);
+        // 6. Rename / Swap
+        if (fs.existsSync(targetPath)) {
+            // Remove old (Safe because verified inside frameworksDir)
+            fs.rmSync(targetPath, { recursive: true, force: true });
+        }
+        fs.renameSync(tempPath, targetPath);
+        return {
+            id,
+            version: resolution.manifest.version,
+            path: targetPath,
+            valid: true,
+            active: false,
+            manifest: resolution.manifest
+        };
+    }
+    catch (e) {
+        // Cleanup temp
+        if (fs.existsSync(tempPath)) {
+            fs.rmSync(tempPath, { recursive: true, force: true });
+        }
+        throw new FrameworkError('INSTALL_FAILED', targetPath, `Failed to install framework: ${e.message}`);
+    }
+}
+export async function installBundledFramework(root, id, options = {}) {
+    const bundleDir = getBundledFrameworksDir();
+    // Fallback logic to find bundled framework
+    let sourcePath = path.join(bundleDir, id);
+    if (!fs.existsSync(sourcePath)) {
+        const allBundled = await listBundledFrameworks();
+        const found = allBundled.find(b => b.id === id && b.valid);
+        if (found) {
+            sourcePath = found.path;
+        }
+        else {
+            throw new FrameworkError('NOT_FOUND', id, `Bundled framework '${id}' not found.`);
+        }
+    }
+    return installFrameworkFromPath(root, sourcePath, options);
+}
+// --- Removal ---
+export function removeFramework(root, id) {
+    const frameworksDir = path.join(root, ".iris/frameworks");
+    // 1. Guard: Frameworks dir exists?
+    if (!fs.existsSync(frameworksDir)) {
+        throw new FrameworkError('NOT_FOUND', frameworksDir, "No frameworks installed.");
+    }
+    // 2. Resolve Target & Safety
+    // Use regex first
+    if (!validateFrameworkId(id)) {
+        throw new FrameworkError('INVALID_ID', id, `Invalid framework ID format.`);
+    }
+    const targetPath = path.resolve(frameworksDir, id);
+    if (!targetPath.startsWith(path.resolve(frameworksDir) + path.sep)) {
+        throw new FrameworkError('SECURITY_VIOLATION', id, `Path traversal detected.`);
+    }
+    if (!fs.existsSync(targetPath)) {
+        throw new FrameworkError('NOT_FOUND', targetPath, `Framework '${id}' is not installed.`);
+    }
+    // 3. Guard: Active
+    const state = loadState();
+    if (state.framework.current === id) {
+        throw new FrameworkError('ACTIVE_FRAMEWORK', id, `Cannot remove active framework '${id}'.`, "Switch to another framework first (e.g. 'iris framework use iris-core').");
+    }
+    // 4. Delete
+    fs.rmSync(targetPath, { recursive: true, force: true });
+}
+// --- Validation Wrapper ---
+export async function validateFrameworkParams(input, root) {
+    // Just a wrapper for loadFramework but enables consistent error handling for CLI
+    return loadFramework(input, { repoRoot: root });
+}

package/dist/iris/fs/atomic.js

@@ -0,0 +1,22 @@
+import fs from "fs";
+import path from "path";
+export function writeJsonAtomic(filePath, data) {
+    const tmpPath = `${filePath}.tmp.${Date.now()}`;
+    const dir = path.dirname(filePath);
+    if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true });
+    }
+    try {
+        fs.writeFileSync(tmpPath, JSON.stringify(data, null, 2));
+        fs.renameSync(tmpPath, filePath);
+    }
+    catch (error) {
+        // Attempt cleanup
+        try {
+            if (fs.existsSync(tmpPath))
+                fs.unlinkSync(tmpPath);
+        }
+        catch { }
+        throw error;
+    }
+}

package/dist/iris/importers/index.js

@@ -0,0 +1,9 @@
+const REGISTRY = {};
+export function registerImporter(importer) {
+    REGISTRY[importer.id] = importer;
+}
+// No importers registered - IRIS ships only iris-core
+export function getImporter(id) {
+    return REGISTRY[id] || null;
+}
+export const IMPORTERS = REGISTRY;

package/dist/iris/importers/types.js

@@ -0,0 +1,8 @@
+export class ImporterError extends Error {
+    exitCode;
+    constructor(message, exitCode = 1) {
+        super(message);
+        this.exitCode = exitCode;
+        this.name = 'ImporterError';
+    }
+}

package/dist/iris/importers/writer.js

@@ -0,0 +1,139 @@
+import * as fs from 'fs';
+import * as path from 'path';
+// Safe extensions to import
+const SAFE_EXTENSIONS = ['.md', '.txt', '.yml', '.yaml', '.json'];
+const IGNORED_DIRS = ['node_modules', '.git', 'dist', 'build', 'coverage'];
+export function ensureDoctrineOnlyFlowInstalled(opts) {
+    const result = {
+        flowId: opts.flowId,
+        installedDir: '', // set below
+        copiedFiles: 0,
+        skippedFiles: 0,
+        overwrittenFiles: 0,
+    };
+    const flowDir = path.join(opts.repoRoot, '.iris', 'flows', opts.flowId);
+    result.installedDir = flowDir;
+    if (opts.verbose) {
+        console.log(`Preparing to install flow '${opts.flowId}' into ${flowDir}`);
+    }
+    // 1. Check if flow already exists
+    if (fs.existsSync(flowDir) && !opts.force) {
+        // If not creating/updating, we might still want to report what happened, 
+        // but typically we'd expect the caller to handle "already exists" checks if they wanted to abort early.
+        // However, the requirement is "overwrite if force", which implies "skip/merge if not force".
+        // For simplicity, if it exists and !force, we might just return early if we consider the flow "installed".
+        // But let's proceed to copy templates with "skip existing" semantics.
+    }
+    if (opts.dryRun) {
+        console.log(`[Dry Run] Would create/update flow directory: ${flowDir}`);
+    }
+    else {
+        fs.mkdirSync(flowDir, { recursive: true });
+    }
+    // 2. Ensure flow.yaml exists
+    const flowYamlPath = path.join(flowDir, 'flow.yaml');
+    if (opts.dryRun) {
+        if (!fs.existsSync(flowYamlPath) || opts.force) {
+            console.log(`[Dry Run] Would write flow.yaml for ${opts.flowId}`);
+        }
+    }
+    else {
+        if (!fs.existsSync(flowYamlPath) || opts.force) {
+            const flowYamlContent = `# Generated by iris flow import
+id: ${opts.flowId}
+name: ${opts.flowId}
+description: Imported from ${opts.displayName}
+version: imported
+`;
+            fs.writeFileSync(flowYamlPath, flowYamlContent);
+        }
+    }
+    // 3. Ensure overlays exist (empty)
+    const overlays = ['policy.overlay.yaml', 'routes.overlay.yaml'];
+    for (const file of overlays) {
+        const filePath = path.join(flowDir, file);
+        if (opts.dryRun) {
+            if (!fs.existsSync(filePath) || opts.force) {
+                console.log(`[Dry Run] Would ensure empty ${file}`);
+            }
+        }
+        else {
+            if (!fs.existsSync(filePath) || opts.force) {
+                fs.writeFileSync(filePath, '{}\n');
+            }
+        }
+    }
+    // 4. Copy templates
+    // Destination: .iris/flows/<id>/doctrine/templates/<id>/...
+    // We nest under <id> again inside templates/ to avoid collision if multiple flows share generic names,
+    // and to keep it namespaced.
+    const destTemplateRoot = path.join(flowDir, 'doctrine', 'templates', opts.flowId);
+    if (opts.dryRun) {
+        console.log(`[Dry Run] Would copy templates to ${destTemplateRoot}`);
+    }
+    else {
+        fs.mkdirSync(destTemplateRoot, { recursive: true });
+    }
+    for (const srcDir of opts.sourceTemplateDirs) {
+        copyRecursive(srcDir, destTemplateRoot, opts, result);
+    }
+    return result;
+}
+function copyRecursive(src, dest, opts, result, relPath = '') {
+    if (!fs.existsSync(src))
+        return;
+    const stats = fs.statSync(src);
+    if (stats.isDirectory()) {
+        // Check ignore list
+        const dirName = path.basename(src);
+        if (IGNORED_DIRS.includes(dirName))
+            return;
+        if (!opts.dryRun) {
+            fs.mkdirSync(dest, { recursive: true });
+        }
+        const children = fs.readdirSync(src);
+        for (const child of children) {
+            copyRecursive(path.join(src, child), path.join(dest, child), opts, result, path.join(relPath, child));
+        }
+    }
+    else if (stats.isFile()) {
+        // Filter extensions
+        const ext = path.extname(src).toLowerCase();
+        if (!SAFE_EXTENSIONS.includes(ext)) {
+            if (opts.verbose)
+                console.log(`Skipping unsafe/irrelevant file type: ${src}`);
+            return;
+        }
+        if (opts.dryRun) {
+            // Just log what would happen
+            if (fs.existsSync(dest)) {
+                if (opts.force) {
+                    console.log(`[Dry Run] Would overwrite ${relPath}`);
+                    result.overwrittenFiles++;
+                }
+                else {
+                    console.log(`[Dry Run] Would skip existing ${relPath}`);
+                    result.skippedFiles++;
+                }
+            }
+            else {
+                console.log(`[Dry Run] Would copy ${relPath}`);
+                result.copiedFiles++;
+            }
+            return;
+        }
+        if (fs.existsSync(dest)) {
+            if (opts.force) {
+                fs.copyFileSync(src, dest);
+                result.overwrittenFiles++;
+            }
+            else {
+                result.skippedFiles++;
+            }
+        }
+        else {
+            fs.copyFileSync(src, dest);
+            result.copiedFiles++;
+        }
+    }
+}