@loj-lang/cli 0.5.0 → 0.5.1

package/README.md

@@ -65,6 +65,9 @@ npx @loj-lang/cli agent install codex --scope project
 # add a skill bundle from a local or remote source
 npx @loj-lang/cli agent add codex --from ./tooling/skills/loj-authoring
 
+# add directly from the GitHub release asset
+npx @loj-lang/cli agent add codex --from https://github.com/juliusrl/loj/releases/download/v0.5.0/loj-authoring-0.5.0.tgz
+
 # install into any explicit skills directory
 npx @loj-lang/cli agent install generic --skills-dir ~/.my-agent/skills
 

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAuCA,MAAM,WAAW,KAAK;IACpB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAChC,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAChC,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;IACzC,OAAO,CAAC,EAAE,UAAU,CAAC;IACrB,YAAY,CAAC,EAAE,CAAC,OAAO,EAAE,UAAU,KAAK,IAAI,CAAC;CAC9C;AAiUD,MAAM,WAAW,UAAU;IACzB,KAAK,IAAI,IAAI,CAAC;CACf;AAED,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC,KAAK,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9B;AAED,MAAM,WAAW,mBAAmB;IAClC,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;IACzC,YAAY,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACtC,YAAY,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACtC,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,KAAK,IAAI,CAAC;CAC/D;AAED,MAAM,WAAW,UAAU;IACzB,KAAK,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,KAAK,IAAI,GAAG,UAAU,CAAC;IAC/F,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,OAAO,EAAE,mBAAmB,GAAG,UAAU,CAAC;IACjF,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;IAC9B,UAAU,IAAI,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,UAAU;IACzB,KAAK,IAAI,IAAI,CAAC;IACd,OAAO,CAAC,OAAO,CAAC,EAAE,QAAQ,GAAG,QAAQ,GAAG,IAAI,CAAC;CAC9C;AAkUD,wBAAgB,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,GAAE,KAAU,GAAG,MAAM,CAmD7D"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAwCA,MAAM,WAAW,KAAK;IACpB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAChC,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAChC,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;IACzC,OAAO,CAAC,EAAE,UAAU,CAAC;IACrB,YAAY,CAAC,EAAE,CAAC,OAAO,EAAE,UAAU,KAAK,IAAI,CAAC;CAC9C;AA2UD,MAAM,WAAW,UAAU;IACzB,KAAK,IAAI,IAAI,CAAC;CACf;AAED,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC,KAAK,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9B;AAED,MAAM,WAAW,mBAAmB;IAClC,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;IACzC,YAAY,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACtC,YAAY,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACtC,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,KAAK,IAAI,CAAC;CAC/D;AAED,MAAM,WAAW,UAAU;IACzB,KAAK,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,KAAK,IAAI,GAAG,UAAU,CAAC;IAC/F,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,OAAO,EAAE,mBAAmB,GAAG,UAAU,CAAC;IACjF,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;IAC9B,UAAU,IAAI,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,UAAU;IACzB,KAAK,IAAI,IAAI,CAAC;IACd,OAAO,CAAC,OAAO,CAAC,EAAE,QAAQ,GAAG,QAAQ,GAAG,IAAI,CAAC;CAC9C;AAkUD,wBAAgB,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,GAAE,KAAU,GAAG,MAAM,CAqD7D"}

package/dist/index.js

@@ -6,6 +6,7 @@ import { basename, dirname, relative, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import YAML from 'yaml';
 import { runCli as runReactCli } from '@loj-lang/rdsl-cli';
+import { compileProject as compileFrontendProject } from '@loj-lang/rdsl-compiler';
 import { runCli as runSpringCli } from '@loj-lang/sdsl-cli';
 import { compileProject as compileBackendProject } from '@loj-lang/sdsl-compiler';
 import { buildRulesManifestFileName, countRulesEntries, compileRulesSource, isRulesSourceFile, } from './rules-proof.js';
@@ -251,6 +252,8 @@ export function runCli(args, io = {}) {
             return handleStop(parseStopArgs(rest), context);
         case 'doctor':
             return handleDoctor(parseDoctorArgs(rest), context);
+        case 'graph':
+            return handleGraph(parseGraphArgs(rest), context);
         case 'rules':
             return handleRules(parseRulesArgs(rest), context);
         case 'flow':
@@ -1345,6 +1348,111 @@ function handleRules(options, context) {
     }
     return 0;
 }
+function handleGraph(options, context) {
+    if ('error' in options) {
+        context.stderr(`${options.error}\n`);
+        return 1;
+    }
+    const loaded = loadProject(options.projectFile, context.cwd, context.env);
+    if ('error' in loaded) {
+        writeFailure(loaded.error, context.stderr, context.stdout, options.json);
+        return 1;
+    }
+    const selectedTargets = selectProjectTargets(loaded.project, options.targetAliases);
+    if ('error' in selectedTargets) {
+        writeFailure(selectedTargets.error, context.stderr, context.stdout, options.json);
+        return 1;
+    }
+    const activeProject = selectedTargets.project;
+    const graphDocuments = [];
+    const compileErrors = [];
+    if (options.surface === 'source' || options.surface === 'all') {
+        const sourceGraphs = buildProjectSourceGraphs(activeProject);
+        if ('error' in sourceGraphs) {
+            compileErrors.push(sourceGraphs.error);
+        }
+        else {
+            graphDocuments.push(...sourceGraphs.documents);
+        }
+    }
+    if (options.surface === 'frontend' || options.surface === 'all') {
+        for (const target of activeProject.targets.filter((entry) => entry.type === 'rdsl')) {
+            const frontendGraph = buildFrontendGeneratedGraph(target, activeProject.projectDir);
+            if ('error' in frontendGraph) {
+                compileErrors.push(frontendGraph.error);
+                continue;
+            }
+            graphDocuments.push(frontendGraph.document);
+        }
+    }
+    if (options.surface === 'backend' || options.surface === 'all') {
+        for (const target of activeProject.targets.filter((entry) => entry.type === 'sdsl')) {
+            const backendGraph = buildBackendGeneratedGraph(target, activeProject.projectDir);
+            if ('error' in backendGraph) {
+                compileErrors.push(backendGraph.error);
+                continue;
+            }
+            graphDocuments.push(backendGraph.document);
+        }
+    }
+    if (compileErrors.length > 0) {
+        if (options.json) {
+            writeJsonArtifact(context.stdout, 'loj.graph.result', {
+                success: false,
+                projectFile: options.projectFile,
+                surface: options.surface,
+                app: { name: activeProject.appName },
+                targets: activeProject.targets.map((target) => ({
+                    alias: target.alias,
+                    type: presentTargetType(target.type),
+                    entry: target.entry,
+                })),
+                errors: compileErrors,
+                graphs: [],
+            });
+            return 1;
+        }
+        writeFailure(compileErrors.join('\n'), context.stderr, context.stdout, false);
+        return 1;
+    }
+    if (options.json) {
+        writeJsonArtifact(context.stdout, 'loj.graph.result', {
+            success: true,
+            projectFile: options.projectFile,
+            surface: options.surface,
+            app: { name: activeProject.appName },
+            targets: activeProject.targets.map((target) => ({
+                alias: target.alias,
+                type: presentTargetType(target.type),
+                entry: target.entry,
+            })),
+            graphs: graphDocuments,
+        });
+        return 0;
+    }
+    if (options.outDir) {
+        const absoluteOutDir = resolve(activeProject.projectDir, options.outDir);
+        mkdirSync(absoluteOutDir, { recursive: true });
+        for (const graph of graphDocuments) {
+            const graphFile = resolve(absoluteOutDir, `${graph.id}.mmd`);
+            writeFileSync(graphFile, `${graph.mermaid}\n`, 'utf8');
+        }
+    }
+    writeCliBanner(context.stdout, 'loj graph', 'emit mermaid architecture views for the selected project');
+    context.stdout(`Project graph: ${normalizePath(resolveProjectAbsoluteFile(options.projectFile, context.cwd))}\n\n`);
+    for (const graph of graphDocuments) {
+        context.stdout(`${graph.title}\n`);
+        context.stdout('```mermaid\n');
+        context.stdout(`${graph.mermaid}\n`);
+        context.stdout('```\n\n');
+    }
+    writeCliSection(context.stdout, 'next', [
+        ...(options.outDir ? [`wrote mermaid files to: ${normalizePath(options.outDir)}`] : []),
+        `copy a graph into docs or release notes`,
+        `re-run with JSON output: loj graph ${options.projectFile} --json`,
+    ]);
+    return 0;
+}
 function handleFlow(options, context) {
     if ('error' in options) {
         context.stderr(`${options.error}\n`);
@@ -1568,6 +1676,45 @@ function parseDoctorArgs(args) {
     }
     return parsed;
 }
+function parseGraphArgs(args) {
+    if (args.length === 0) {
+        return { error: 'Usage: loj graph <loj.project.yaml> [--surface source|frontend|backend|all] [--target <alias>] [--out-dir <dir>] [--json]' };
+    }
+    let surface = 'all';
+    let outDir;
+    const filteredArgs = [];
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        if (arg === '--surface') {
+            const value = (args[index + 1] ?? '').trim();
+            if (value !== 'source' && value !== 'frontend' && value !== 'backend' && value !== 'all') {
+                return { error: 'loj graph --surface must be one of: source, frontend, backend, all' };
+            }
+            surface = value;
+            index += 1;
+            continue;
+        }
+        if (arg === '--out-dir') {
+            const value = (args[index + 1] ?? '').trim();
+            if (!value) {
+                return { error: 'loj graph --out-dir must be a non-empty path' };
+            }
+            outDir = value;
+            index += 1;
+            continue;
+        }
+        filteredArgs.push(arg);
+    }
+    const parsed = parseProjectTargetArgs('graph', filteredArgs);
+    if ('error' in parsed) {
+        return parsed;
+    }
+    return {
+        ...parsed,
+        surface,
+        outDir,
+    };
+}
 function parseProjectTargetArgs(command, args, options = {}) {
     let json = false;
     let debug = false;
@@ -4096,6 +4243,350 @@ function compileBackendIrForTarget(target, projectDir) {
         };
     }
 }
+function compileFrontendSemanticForTarget(target, projectDir) {
+    try {
+        const compiled = compileFrontendProject({
+            entryFile: target.entry,
+            projectRoot: '.',
+            readFile(fileName) {
+                return readFileSync(resolve(projectDir, fileName), 'utf8');
+            },
+            listFiles(directory) {
+                const absoluteDirectory = resolve(projectDir, directory);
+                return nodeFs.readdirSync(absoluteDirectory)
+                    .map((entry) => normalizePath(directory === '.' ? entry : `${directory}/${entry}`));
+            },
+        });
+        if (!compiled.success || !compiled.ir) {
+            const firstError = compiled.errors[0];
+            return {
+                error: `failed to compile frontend graph for target "${target.alias}"${firstError ? `: ${firstError.message}` : ''}`,
+            };
+        }
+        return {
+            ir: compiled.ir,
+            files: compiled.files.map((file) => ({ path: file.path })),
+            sourceFiles: compiled.semanticManifest?.sourceFiles ?? [target.entry],
+            moduleGraph: compiled.semanticManifest?.moduleGraph,
+        };
+    }
+    catch (error) {
+        return {
+            error: `failed to compile frontend graph for target "${target.alias}": ${error instanceof Error ? error.message : String(error)}`,
+        };
+    }
+}
+function buildProjectSourceGraphs(project) {
+    const documents = [];
+    for (const target of project.targets) {
+        if (target.type === 'rdsl') {
+            const compiled = compileFrontendSemanticForTarget(target, project.projectDir);
+            if ('error' in compiled) {
+                return compiled;
+            }
+            documents.push({
+                id: `${target.alias}.source`,
+                title: `Source graph (${target.alias})`,
+                mermaid: buildFrontendSourceMermaid(project, target, compiled.ir, compiled.sourceFiles, compiled.moduleGraph),
+            });
+            continue;
+        }
+        const compiled = compileBackendIrForTarget(target, project.projectDir);
+        if ('error' in compiled) {
+            return compiled;
+        }
+        documents.push({
+            id: `${target.alias}.source`,
+            title: `Source graph (${target.alias})`,
+            mermaid: buildBackendSourceMermaid(project, target, compiled.ir),
+        });
+    }
+    return { documents };
+}
+function buildFrontendGeneratedGraph(target, projectDir) {
+    const compiled = compileFrontendSemanticForTarget(target, projectDir);
+    if ('error' in compiled) {
+        return compiled;
+    }
+    return {
+        document: {
+            id: `${target.alias}.frontend`,
+            title: `Generated frontend graph (${target.alias})`,
+            mermaid: buildFrontendGeneratedMermaid(target, compiled.files),
+        },
+    };
+}
+function buildBackendGeneratedGraph(target, projectDir) {
+    const compiled = compileBackendProject({
+        entryFile: target.entry,
+        projectRoot: '.',
+        readFile(fileName) {
+            return readFileSync(resolve(projectDir, fileName), 'utf8');
+        },
+        listFiles(directory) {
+            const absoluteDirectory = resolve(projectDir, directory);
+            return nodeFs.readdirSync(absoluteDirectory)
+                .map((entry) => normalizePath(directory === '.' ? entry : `${directory}/${entry}`));
+        },
+    });
+    if (!compiled.success) {
+        const firstError = compiled.errors[0];
+        return {
+            error: `failed to compile backend graph for target "${target.alias}"${firstError ? `: ${firstError.message}` : ''}`,
+        };
+    }
+    return {
+        document: {
+            id: `${target.alias}.backend`,
+            title: `Generated backend graph (${target.alias})`,
+            mermaid: buildBackendGeneratedMermaid(target, compiled.files.map((file) => ({ path: file.path }))),
+        },
+    };
+}
+function buildFrontendSourceMermaid(project, target, ir, sourceFiles, moduleGraph) {
+    const lines = ['flowchart TD'];
+    const appId = mermaidNodeId(`app.${target.alias}`);
+    lines.push(`  ${appId}[${mermaidLabel(`${project.appName} / ${target.alias}`)}]`);
+    const entryId = mermaidNodeId(`entry.${target.alias}`);
+    lines.push(`  ${entryId}[${mermaidLabel(target.entry)}]`);
+    lines.push(`  ${appId} --> ${entryId}`);
+    const models = toNamedList(ir.models);
+    const resources = toNamedList(ir.resources);
+    const readModels = toNamedList(ir.readModels);
+    const pages = toNamedList(ir.pages);
+    for (const file of sourceFiles) {
+        const fileId = mermaidNodeId(`sourceFile.${target.alias}.${file}`);
+        lines.push(`  ${fileId}[${mermaidLabel(file)}]`);
+        lines.push(`  ${entryId} -.imports.-> ${fileId}`);
+    }
+    if (moduleGraph) {
+        for (const [from, imports] of Object.entries(moduleGraph)) {
+            const fromId = mermaidNodeId(`sourceFile.${target.alias}.${from}`);
+            for (const imported of imports) {
+                const importedId = mermaidNodeId(`sourceFile.${target.alias}.${imported}`);
+                lines.push(`  ${fromId} -.imports.-> ${importedId}`);
+            }
+        }
+    }
+    for (const model of models) {
+        const modelId = mermaidNodeId(`model.${target.alias}.${model.name}`);
+        lines.push(`  ${modelId}[${mermaidLabel(`model ${model.name}`)}]`);
+        lines.push(`  ${appId} --> ${modelId}`);
+    }
+    for (const resource of resources) {
+        const resourceId = mermaidNodeId(`resource.${target.alias}.${resource.name}`);
+        lines.push(`  ${resourceId}[${mermaidLabel(`resource ${resource.name}`)}]`);
+        lines.push(`  ${appId} --> ${resourceId}`);
+        if (typeof resource.model === 'string') {
+            lines.push(`  ${resourceId} --> ${mermaidNodeId(`model.${target.alias}.${resource.model}`)}`);
+        }
+        const workflow = resource.workflow;
+        if (workflow && typeof workflow === 'object' && typeof workflow.resolvedPath === 'string') {
+            const workflowPath = workflow.resolvedPath;
+            const workflowId = mermaidNodeId(`workflow.${target.alias}.${workflowPath}`);
+            lines.push(`  ${workflowId}[${mermaidLabel(`workflow ${basename(workflowPath)}`)}]`);
+            lines.push(`  ${resourceId} --> ${workflowId}`);
+        }
+    }
+    for (const readModel of readModels) {
+        const readModelId = mermaidNodeId(`readModel.${target.alias}.${readModel.name}`);
+        lines.push(`  ${readModelId}[${mermaidLabel(`readModel ${readModel.name}`)}]`);
+        lines.push(`  ${appId} --> ${readModelId}`);
+        const rules = readModel.rules;
+        if (rules && typeof rules === 'object' && typeof rules.resolvedPath === 'string') {
+            const rulesPath = rules.resolvedPath;
+            const rulesId = mermaidNodeId(`rules.${target.alias}.${rulesPath}`);
+            lines.push(`  ${rulesId}[${mermaidLabel(`rules ${basename(rulesPath)}`)}]`);
+            lines.push(`  ${readModelId} --> ${rulesId}`);
+        }
+    }
+    for (const page of pages) {
+        const pageId = mermaidNodeId(`page.${target.alias}.${page.name}`);
+        lines.push(`  ${pageId}[${mermaidLabel(`page ${page.name}`)}]`);
+        lines.push(`  ${appId} --> ${pageId}`);
+        const blocks = Array.isArray(page.blocks) ? page.blocks : [];
+        for (const block of blocks) {
+            if (!block || typeof block !== 'object' || typeof block.id !== 'string') {
+                continue;
+            }
+            const blockTitle = typeof block.title === 'string'
+                ? block.title
+                : block.blockType === 'string'
+                    ? block.blockType
+                    : 'block';
+            const blockId = mermaidNodeId(`pageBlock.${target.alias}.${block.id}`);
+            lines.push(`  ${blockId}[${mermaidLabel(`block ${blockTitle}`)}]`);
+            lines.push(`  ${pageId} --> ${blockId}`);
+            const data = block.data;
+            if (typeof data === 'string') {
+                lines.push(`  ${blockId} --> ${mermaidNodeId(`readModel.${target.alias}.${data}`)}`);
+            }
+        }
+    }
+    return lines.join('\n');
+}
+function buildBackendSourceMermaid(project, target, ir) {
+    const lines = ['flowchart TD'];
+    const appId = mermaidNodeId(`app.${target.alias}`);
+    lines.push(`  ${appId}[${mermaidLabel(`${project.appName} / ${target.alias}`)}]`);
+    const entryId = mermaidNodeId(`entry.${target.alias}`);
+    lines.push(`  ${entryId}[${mermaidLabel(target.entry)}]`);
+    lines.push(`  ${appId} --> ${entryId}`);
+    for (const sourceFile of ir.sourceFiles) {
+        const sourceId = mermaidNodeId(`sourceFile.${target.alias}.${sourceFile}`);
+        lines.push(`  ${sourceId}[${mermaidLabel(sourceFile)}]`);
+        lines.push(`  ${entryId} -.imports.-> ${sourceId}`);
+    }
+    for (const [from, imports] of Object.entries(ir.moduleGraph)) {
+        const fromId = mermaidNodeId(`sourceFile.${target.alias}.${from}`);
+        for (const imported of imports) {
+            const importedId = mermaidNodeId(`sourceFile.${target.alias}.${imported}`);
+            lines.push(`  ${fromId} -.imports.-> ${importedId}`);
+        }
+    }
+    for (const model of ir.models) {
+        const modelId = mermaidNodeId(`model.${target.alias}.${model.name}`);
+        lines.push(`  ${modelId}[${mermaidLabel(`model ${model.name}`)}]`);
+        lines.push(`  ${appId} --> ${modelId}`);
+    }
+    for (const resource of ir.resources) {
+        const resourceId = mermaidNodeId(`resource.${target.alias}.${resource.name}`);
+        lines.push(`  ${resourceId}[${mermaidLabel(`resource ${resource.name}`)}]`);
+        lines.push(`  ${appId} --> ${resourceId}`);
+        lines.push(`  ${resourceId} --> ${mermaidNodeId(`model.${target.alias}.${resource.model}`)}`);
+        if (resource.workflow) {
+            const workflowId = mermaidNodeId(`workflow.${target.alias}.${resource.workflow.resolvedPath}`);
+            lines.push(`  ${workflowId}[${mermaidLabel(`workflow ${basename(resource.workflow.resolvedPath)}`)}]`);
+            lines.push(`  ${resourceId} --> ${workflowId}`);
+        }
+        if (resource.create?.rules) {
+            const rulesId = mermaidNodeId(`createRules.${target.alias}.${resource.create.rules.resolvedPath}`);
+            lines.push(`  ${rulesId}[${mermaidLabel(`create.rules ${basename(resource.create.rules.resolvedPath)}`)}]`);
+            lines.push(`  ${resourceId} --> ${rulesId}`);
+        }
+    }
+    for (const readModel of ir.readModels) {
+        const readModelId = mermaidNodeId(`readModel.${target.alias}.${readModel.name}`);
+        lines.push(`  ${readModelId}[${mermaidLabel(`readModel ${readModel.name}`)}]`);
+        lines.push(`  ${appId} --> ${readModelId}`);
+        const handlerId = mermaidNodeId(`handler.${target.alias}.${readModel.name}`);
+        lines.push(`  ${handlerId}[${mermaidLabel(`${readModel.handler.source} ${basename(readModel.handler.resolvedPath)}`)}]`);
+        lines.push(`  ${readModelId} --> ${handlerId}`);
+        if (readModel.rules) {
+            const rulesId = mermaidNodeId(`rules.${target.alias}.${readModel.rules.resolvedPath}`);
+            lines.push(`  ${rulesId}[${mermaidLabel(`rules ${basename(readModel.rules.resolvedPath)}`)}]`);
+            lines.push(`  ${readModelId} --> ${rulesId}`);
+        }
+    }
+    return lines.join('\n');
+}
+function buildFrontendGeneratedMermaid(target, files) {
+    const lines = ['flowchart TD'];
+    const appId = mermaidNodeId(`generated.frontend.${target.alias}`);
+    lines.push(`  ${appId}[${mermaidLabel(`generated frontend ${target.alias}`)}]`);
+    const groups = groupGeneratedFrontendFiles(files.map((file) => file.path));
+    for (const [groupName, groupFiles] of groups) {
+        const groupId = mermaidNodeId(`generated.frontend.${target.alias}.${groupName}`);
+        lines.push(`  ${groupId}[${mermaidLabel(`${groupName} (${groupFiles.length})`)}]`);
+        lines.push(`  ${appId} --> ${groupId}`);
+        for (const file of groupFiles.slice(0, 8)) {
+            const fileId = mermaidNodeId(`generated.frontend.file.${target.alias}.${file}`);
+            lines.push(`  ${fileId}[${mermaidLabel(basename(file))}]`);
+            lines.push(`  ${groupId} --> ${fileId}`);
+        }
+        if (groupFiles.length > 8) {
+            const moreId = mermaidNodeId(`generated.frontend.more.${target.alias}.${groupName}`);
+            lines.push(`  ${moreId}[${mermaidLabel(`… ${groupFiles.length - 8} more`)}]`);
+            lines.push(`  ${groupId} --> ${moreId}`);
+        }
+    }
+    return lines.join('\n');
+}
+function buildBackendGeneratedMermaid(target, files) {
+    const lines = ['flowchart TD'];
+    const backendId = mermaidNodeId(`generated.backend.${target.alias}`);
+    lines.push(`  ${backendId}[${mermaidLabel(`generated backend ${target.alias}`)}]`);
+    const groups = groupGeneratedBackendFiles(files.map((file) => file.path));
+    for (const [groupName, groupFiles] of groups) {
+        const groupId = mermaidNodeId(`generated.backend.${target.alias}.${groupName}`);
+        lines.push(`  ${groupId}[${mermaidLabel(`${groupName} (${groupFiles.length})`)}]`);
+        lines.push(`  ${backendId} --> ${groupId}`);
+        for (const file of groupFiles.slice(0, 8)) {
+            const fileId = mermaidNodeId(`generated.backend.file.${target.alias}.${file}`);
+            lines.push(`  ${fileId}[${mermaidLabel(basename(file))}]`);
+            lines.push(`  ${groupId} --> ${fileId}`);
+        }
+        if (groupFiles.length > 8) {
+            const moreId = mermaidNodeId(`generated.backend.more.${target.alias}.${groupName}`);
+            lines.push(`  ${moreId}[${mermaidLabel(`… ${groupFiles.length - 8} more`)}]`);
+            lines.push(`  ${groupId} --> ${moreId}`);
+        }
+    }
+    return lines.join('\n');
+}
+function groupGeneratedFrontendFiles(files) {
+    const groups = new Map();
+    for (const file of files.slice().sort()) {
+        const normalized = normalizePath(file);
+        const group = normalized.startsWith('pages/')
+            ? 'pages'
+            : normalized.startsWith('models/')
+                ? 'models'
+                : normalized.startsWith('layout/')
+                    ? 'layout'
+                    : normalized.startsWith('views/')
+                        ? 'views'
+                        : normalized.startsWith('styles/')
+                            ? 'styles'
+                            : normalized.startsWith('frontend/')
+                                ? 'host-files'
+                                : normalized.startsWith('components/')
+                                    ? 'components'
+                                    : normalized === 'App.tsx' || normalized === 'router.tsx' || normalized === 'GENERATED.md'
+                                        ? 'app-shell'
+                                        : 'other';
+        const entries = groups.get(group) ?? [];
+        entries.push(normalized);
+        groups.set(group, entries);
+    }
+    return groups;
+}
+function groupGeneratedBackendFiles(files) {
+    const groups = new Map();
+    for (const file of files.slice().sort()) {
+        const normalized = normalizePath(file);
+        const group = normalized.includes('/controller/') || normalized.startsWith('app/routes/') || normalized.startsWith('app/routers/')
+            ? 'routes-controllers'
+            : normalized.includes('/service/') || normalized.startsWith('app/services/')
+                ? 'services'
+                : normalized.includes('/model/') || normalized.includes('/entity/') || normalized.startsWith('app/models/')
+                    ? 'models'
+                    : normalized.includes('/dto/') || normalized.startsWith('app/dto/')
+                        ? 'dto'
+                        : normalized.includes('/workflow/') || normalized.startsWith('app/workflow/')
+                            ? 'workflow'
+                            : normalized.includes('/rules/') || normalized.startsWith('app/rules/') || normalized.startsWith('app/custom/rules/')
+                                ? 'rules'
+                                : normalized.startsWith('app/custom/read_models/') || normalized.includes('/readmodel/')
+                                    ? 'read-models'
+                                    : 'support';
+        const entries = groups.get(group) ?? [];
+        entries.push(normalized);
+        groups.set(group, entries);
+    }
+    return groups;
+}
+function mermaidNodeId(value) {
+    return value.replace(/[^A-Za-z0-9_]/g, '_');
+}
+function mermaidLabel(value) {
+    return value.replace(/"/g, '#quot;');
+}
+function toNamedList(value) {
+    return Array.isArray(value)
+        ? value.filter((entry) => isRecord(entry) && typeof entry.name === 'string')
+        : [];
+}
 function validateDatabaseConfigForTargetRuntime(target, targetTriple) {
     if (!target.database || !targetTriple) {
         return null;
@@ -5280,6 +5771,7 @@ function writeUsage(write) {
         '  loj validate <loj.project.yaml> [--json]',
         '  loj build <loj.project.yaml> [--json]',
         '  loj dev <loj.project.yaml> [--target <alias>] [--debug] [--json]',
+        '  loj graph <loj.project.yaml> [--surface source|frontend|backend|all] [--target <alias>] [--out-dir <dir>] [--json]',
         '  loj rebuild <loj.project.yaml> [--target <alias>] [--json]',
         '  loj restart <loj.project.yaml> [--service host|server|all] [--json]',
         '  loj status <loj.project.yaml> [--target <alias>] [--json]',
@@ -5296,6 +5788,7 @@ function writeUsage(write) {
         'Common project-shell loop:',
         '  loj doctor <loj.project.yaml>   # validate dependencies, generated outputs, and linked artifacts',
         '  loj dev <loj.project.yaml>      # watch the project and run managed host/backend services',
+        '  loj graph <loj.project.yaml>    # emit mermaid architecture views for source and generated targets',
         '  loj rebuild <loj.project.yaml>  # rebuild selected targets without restarting the whole loop',
         '  loj restart <loj.project.yaml>  # restart host/server processes inside the active loop',
         '  loj status <loj.project.yaml>   # inspect current URLs, probes, services, and debugger endpoints',