@abhinav2203/codeflow-core 0.1.0

package/dist/export/index.js

@@ -0,0 +1,398 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { generateNodeCode, getNodeStubPath, isCodeBearingNode } from "../internal/codegen";
+import { createRunPlan } from "../internal/plan";
+import { getCodeBearingNodes, getDefaultExecutionTarget } from "../internal/phases";
+import { slugify } from "../internal/utils";
+const ensureDir = async (dirPath) => {
+    await fs.mkdir(dirPath, { recursive: true });
+};
+const formatField = (field) => `${field.name}: ${field.type}${field.description ? ` - ${field.description}` : ""}`;
+const formatList = (items) => (items.length ? items.map((item) => `- ${item}`).join("\n") : "- None");
+const formatFields = (fields) => fields.length ? fields.map((field) => `- ${formatField(field)}`).join("\n") : "- None";
+const layoutNodesForCanvas = (graph) => graph.nodes.map((node, index) => ({
+    id: node.id,
+    type: "text",
+    x: 80 + (index % 3) * 380,
+    y: 80 + Math.floor(index / 3) * 220,
+    width: 300,
+    height: 140,
+    text: `# ${node.name}\n\nKind: ${node.kind}\n${node.summary}`
+}));
+const buildCanvas = (graph) => ({
+    nodes: layoutNodesForCanvas(graph),
+    edges: graph.edges.map((edge) => ({
+        id: `${edge.kind}:${edge.from}:${edge.to}`,
+        fromNode: edge.from,
+        fromSide: "right",
+        toNode: edge.to,
+        toSide: "left",
+        label: edge.label ?? edge.kind
+    }))
+});
+const buildNodeDoc = (node) => {
+    const inputs = formatFields(node.contract.inputs);
+    const outputs = formatFields(node.contract.outputs);
+    const responsibilities = formatList(node.contract.responsibilities);
+    const attributes = formatFields(node.contract.attributes);
+    const dependencies = formatList(node.contract.dependencies);
+    const sideEffects = formatList(node.contract.sideEffects);
+    const errors = formatList(node.contract.errors);
+    const calls = node.contract.calls.length
+        ? node.contract.calls
+            .map((call) => `- ${call.target}${call.kind ? ` [${call.kind}]` : ""}${call.description ? ` - ${call.description}` : ""}`)
+            .join("\n")
+        : "- None";
+    const methods = node.contract.methods.length
+        ? node.contract.methods
+            .map((method) => {
+            const methodCalls = method.calls.length
+                ? method.calls
+                    .map((call) => `${call.target}${call.kind ? ` [${call.kind}]` : ""}${call.description ? ` - ${call.description}` : ""}`)
+                    .join("; ")
+                : "None";
+            return [
+                `- ${method.name}`,
+                `  Signature: ${method.signature ?? "N/A"}`,
+                `  Summary: ${method.summary}`,
+                `  Inputs: ${method.inputs.length ? method.inputs.map(formatField).join("; ") : "None"}`,
+                `  Outputs: ${method.outputs.length ? method.outputs.map(formatField).join("; ") : "None"}`,
+                `  Side effects: ${method.sideEffects.length ? method.sideEffects.join("; ") : "None"}`,
+                `  Calls: ${methodCalls}`
+            ].join("\n");
+        })
+            .join("\n")
+        : "- None";
+    const notes = formatList(node.contract.notes);
+    const stubLink = node.kind === "module" ? "N/A" : `stubs/${slugify(node.kind)}-${slugify(node.name)}.${node.kind === "ui-screen" ? "tsx" : "ts"}`;
+    return `# ${node.name}
+
+Kind: ${node.kind}
+
+Summary:
+${node.summary}
+
+Responsibilities:
+${responsibilities}
+
+Signature:
+${node.signature ?? "N/A"}
+
+Inputs:
+${inputs}
+
+Outputs:
+${outputs}
+
+Attributes / State:
+${attributes}
+
+Methods:
+${methods}
+
+Dependencies:
+${dependencies}
+
+Calls:
+${calls}
+
+Side effects:
+${sideEffects}
+
+Errors:
+${errors}
+
+Notes:
+${notes}
+
+Obsidian:
+- [[index]]
+- Stub path: ${stubLink}
+- Phase status: ${node.status ?? "spec_only"}
+`;
+};
+const buildPhaseManifest = (graph) => ({
+    phase: graph.phase ?? "spec",
+    exportedAt: new Date().toISOString(),
+    nodes: graph.nodes.map((node) => ({
+        id: node.id,
+        name: node.name,
+        kind: node.kind,
+        status: node.status ?? "spec_only",
+        specPath: getNodeStubPath(node),
+        hasSpecDraft: Boolean(node.specDraft),
+        hasImplementationDraft: Boolean(node.implementationDraft),
+        hasVerification: Boolean(node.lastVerification)
+    }))
+});
+const buildIntegrationEntrypoint = (graph) => {
+    if (graph.phase !== "integration") {
+        return null;
+    }
+    const targetNode = getDefaultExecutionTarget(graph);
+    const targetPath = targetNode ? getNodeStubPath(targetNode) : null;
+    if (!targetNode || !targetPath) {
+        return null;
+    }
+    const rootExport = targetNode.kind === "ui-screen" ? "default" : undefined;
+    const codeBearingImports = getCodeBearingNodes(graph)
+        .map((node, index) => {
+        const stubPath = getNodeStubPath(node);
+        if (!stubPath) {
+            return null;
+        }
+        return {
+            binding: node.id === targetNode.id ? "integrationRoot" : `integrationNode${index + 1}`,
+            importPath: `./${stubPath.replace(/\.(ts|tsx)$/, "")}`
+        };
+    })
+        .filter((entry) => Boolean(entry));
+    const rootNamedExport = rootExport ??
+        targetNode.name
+            .split(".")
+            .pop()
+            ?.replace(/[^A-Za-z0-9_$]+/g, " ")
+            .trim()
+            .replace(/(?:^\w|[A-Z]|\b\w)/g, (chunk, index) => (index === 0 ? chunk.toLowerCase() : chunk.toUpperCase()))
+            .replace(/\s+/g, "");
+    if (!rootNamedExport) {
+        return null;
+    }
+    return [
+        `import * as integrationRoot from "${codeBearingImports.find((entry) => entry.binding === "integrationRoot")?.importPath ?? `./${targetPath.replace(/\.(ts|tsx)$/, "")}`}";`,
+        ...codeBearingImports
+            .filter((entry) => entry.binding !== "integrationRoot")
+            .map((entry) => `import * as ${entry.binding} from "${entry.importPath}";\nvoid ${entry.binding};`),
+        "",
+        "export async function runIntegration(input: unknown) {",
+        `  const runner = integrationRoot["${rootNamedExport}"] as ((...args: any[]) => any) | undefined;`,
+        '  if (typeof runner !== "function") {',
+        '    throw new Error("Integration root export is not callable.");',
+        "  }",
+        "  const args = Array.isArray(input) ? input : [input];",
+        "  return runner(...args);",
+        "}"
+    ].join("\n");
+};
+const classifyNodeArtifact = (node, graph, draftOverride) => {
+    if (draftOverride) {
+        const isValidated = node.lastVerification?.status === "success";
+        return {
+            content: draftOverride,
+            validationState: isValidated ? "validated" : "draft",
+            maturity: isValidated ? "production" : "preview",
+            provenance: "deterministic",
+            notes: ["Using the current editor draft captured at export time."]
+        };
+    }
+    if (node.implementationDraft) {
+        const isValidated = node.lastVerification?.status === "success";
+        return {
+            content: node.implementationDraft,
+            validationState: isValidated ? "validated" : "draft",
+            maturity: isValidated ? "production" : "preview",
+            provenance: "deterministic",
+            notes: ["Using the node implementation draft stored in the blueprint."]
+        };
+    }
+    if (node.specDraft) {
+        return {
+            content: node.specDraft,
+            validationState: "draft",
+            maturity: "preview",
+            provenance: "deterministic",
+            notes: ["Using the node specification draft because no implementation draft exists."]
+        };
+    }
+    return {
+        content: generateNodeCode(node, graph),
+        validationState: "scaffold",
+        maturity: "scaffold",
+        provenance: "deterministic",
+        notes: ["Generated deterministic scaffold content from the blueprint contract."]
+    };
+};
+export const exportBlueprintArtifacts = async (graph, outputDir, executionReport, codeDrafts) => {
+    const runPlan = createRunPlan(graph);
+    const baseDir = outputDir && outputDir.trim()
+        ? path.resolve(outputDir)
+        : path.resolve(process.cwd(), "artifacts", slugify(graph.projectName));
+    const docsDir = path.join(baseDir, "docs");
+    const stubsDir = path.join(baseDir, "stubs");
+    const blueprintPath = path.join(baseDir, "blueprint.json");
+    const canvasPath = path.join(baseDir, "system.canvas");
+    const ownershipPath = path.join(baseDir, "ownership.json");
+    const obsidianIndexPath = path.join(baseDir, "obsidian-index.md");
+    const phaseManifestPath = path.join(baseDir, "phase-manifest.json");
+    const integrationEntrypointPath = path.join(baseDir, "integration-entrypoint.ts");
+    const artifactManifestPath = path.join(baseDir, "artifact-manifest.json");
+    const exportedAt = new Date().toISOString();
+    const artifacts = [];
+    await ensureDir(docsDir);
+    await ensureDir(stubsDir);
+    await fs.writeFile(blueprintPath, `${JSON.stringify(graph, null, 2)}\n`, "utf8");
+    await fs.writeFile(canvasPath, `${JSON.stringify(buildCanvas(graph), null, 2)}\n`, "utf8");
+    await fs.writeFile(phaseManifestPath, `${JSON.stringify(buildPhaseManifest(graph), null, 2)}\n`, "utf8");
+    artifacts.push({
+        relativePath: path.relative(baseDir, blueprintPath),
+        artifactType: "blueprint",
+        validationState: "validated",
+        provenance: "deterministic",
+        maturity: "production",
+        generatedAt: exportedAt,
+        notes: ["Serialized blueprint graph."]
+    });
+    artifacts.push({
+        relativePath: path.relative(baseDir, canvasPath),
+        artifactType: "canvas",
+        validationState: "validated",
+        provenance: "deterministic",
+        maturity: "production",
+        generatedAt: exportedAt,
+        notes: ["Canvas projection of the blueprint graph."]
+    });
+    const summaryDoc = `# ${graph.projectName}
+
+Generated at: ${graph.generatedAt}
+Mode: ${graph.mode}
+Current phase: ${graph.phase ?? "spec"}
+
+Nodes:
+${graph.nodes.map((node) => `- ${node.kind}: ${node.name}`).join("\n")}
+
+Workflows:
+${graph.workflows.length ? graph.workflows.map((workflow) => `- ${workflow.name}: ${workflow.steps.join(" -> ")}`).join("\n") : "- None"}
+
+Execution phases:
+${runPlan.batches.length
+        ? runPlan.batches
+            .map((batch) => {
+            const taskTitles = batch.taskIds
+                .map((taskId) => runPlan.tasks.find((task) => task.id === taskId)?.title)
+                .filter(Boolean)
+                .join("; ");
+            return `- Phase ${batch.index + 1}: ${taskTitles || "No tasks"}`;
+        })
+            .join("\n")
+        : "- None"}
+`;
+    await fs.writeFile(path.join(docsDir, "index.md"), summaryDoc, "utf8");
+    artifacts.push({
+        relativePath: path.relative(baseDir, path.join(docsDir, "index.md")),
+        artifactType: "documentation",
+        validationState: "validated",
+        provenance: "deterministic",
+        maturity: "production",
+        generatedAt: exportedAt,
+        notes: ["Top-level export summary."]
+    });
+    await fs.writeFile(obsidianIndexPath, `# ${graph.projectName} Vault Index
+
+## Core Links
+- [[docs/index]]
+- [[system.canvas]]
+
+## Nodes
+${graph.nodes.map((node) => `- [[docs/${slugify(node.kind)}-${slugify(node.name)}]]`).join("\n")}
+`, "utf8");
+    artifacts.push({
+        relativePath: path.relative(baseDir, obsidianIndexPath),
+        artifactType: "documentation",
+        validationState: "validated",
+        provenance: "deterministic",
+        maturity: "production",
+        generatedAt: exportedAt,
+        notes: ["Obsidian index for exported documentation."]
+    });
+    for (const node of graph.nodes) {
+        const docPath = path.join(docsDir, `${slugify(node.kind)}-${slugify(node.name)}.md`);
+        await fs.writeFile(docPath, buildNodeDoc(node), "utf8");
+        artifacts.push({
+            nodeId: node.id,
+            nodeName: node.name,
+            nodeKind: node.kind,
+            relativePath: path.relative(baseDir, docPath),
+            artifactType: "documentation",
+            validationState: "validated",
+            provenance: "deterministic",
+            maturity: "production",
+            generatedAt: exportedAt,
+            notes: ["Per-node architecture documentation."]
+        });
+        if (!isCodeBearingNode(node)) {
+            continue;
+        }
+        const artifact = classifyNodeArtifact(node, graph, codeDrafts?.[node.id]);
+        const stubContent = artifact.content;
+        if (!stubContent) {
+            continue;
+        }
+        const extension = node.kind === "ui-screen" ? "tsx" : "ts";
+        const stubPath = path.join(stubsDir, `${slugify(node.kind)}-${slugify(node.name)}.${extension}`);
+        await fs.writeFile(stubPath, stubContent, "utf8");
+        artifacts.push({
+            nodeId: node.id,
+            nodeName: node.name,
+            nodeKind: node.kind,
+            relativePath: path.relative(baseDir, stubPath),
+            artifactType: "code",
+            validationState: artifact.validationState,
+            provenance: artifact.provenance,
+            maturity: artifact.maturity,
+            generatedAt: exportedAt,
+            notes: artifact.notes
+        });
+    }
+    if (executionReport) {
+        await fs.writeFile(ownershipPath, `${JSON.stringify(executionReport.ownership, null, 2)}\n`, "utf8");
+        artifacts.push({
+            relativePath: path.relative(baseDir, ownershipPath),
+            artifactType: "ownership",
+            validationState: "validated",
+            provenance: "deterministic",
+            maturity: "production",
+            generatedAt: exportedAt,
+            notes: ["Ownership records for managed regions."]
+        });
+    }
+    const integrationEntrypoint = buildIntegrationEntrypoint(graph);
+    if (integrationEntrypoint) {
+        await fs.writeFile(integrationEntrypointPath, integrationEntrypoint, "utf8");
+        artifacts.push({
+            relativePath: path.relative(baseDir, integrationEntrypointPath),
+            artifactType: "integration",
+            validationState: "draft",
+            provenance: "deterministic",
+            maturity: "preview",
+            generatedAt: exportedAt,
+            notes: ["Generated integration runner entrypoint."]
+        });
+    }
+    await fs.writeFile(artifactManifestPath, `${JSON.stringify({ exportedAt, artifacts }, null, 2)}\n`, "utf8");
+    const artifactSummary = artifacts.reduce((summary, artifact) => {
+        summary.total += 1;
+        if (artifact.validationState === "validated") {
+            summary.validated += 1;
+        }
+        else if (artifact.validationState === "draft") {
+            summary.draft += 1;
+        }
+        else {
+            summary.scaffold += 1;
+        }
+        return summary;
+    }, { total: 0, validated: 0, draft: 0, scaffold: 0 });
+    return {
+        rootDir: baseDir,
+        blueprintPath,
+        canvasPath,
+        docsDir,
+        stubsDir,
+        artifactManifestPath,
+        artifactSummary,
+        phaseManifestPath,
+        integrationEntrypointPath: integrationEntrypoint ? integrationEntrypointPath : undefined,
+        ownershipPath: executionReport ? ownershipPath : undefined,
+        obsidianIndexPath
+    };
+};

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export * from "./analyzer/index";
+export * from "./schema/index";
+export * from "./export/index";
+export * from "./conflicts/index";
+export * from "./store-paths";

package/dist/index.js

@@ -0,0 +1,5 @@
+export * from "./analyzer/index";
+export * from "./schema/index";
+export * from "./export/index";
+export * from "./conflicts/index";
+export * from "./store-paths";

package/dist/internal/codegen.d.ts

@@ -0,0 +1,5 @@
+import type { BlueprintGraph, BlueprintNode } from "../schema/index";
+export declare const isCodeBearingNode: (node: BlueprintNode) => boolean;
+export declare const getNodeStubPath: (node: BlueprintNode) => string | null;
+export declare const getNodeRuntimeExport: (node: BlueprintNode) => string | null;
+export declare const generateNodeCode: (node: BlueprintNode, graph: BlueprintGraph) => string | null;

package/dist/internal/codegen.js

@@ -0,0 +1,224 @@
+import { emptyContract } from "../schema/index";
+export const isCodeBearingNode = (node) => node.kind !== "module";
+const normalizeContract = (contract) => ({
+    ...emptyContract(),
+    ...contract
+});
+const sanitizeIdentifier = (value) => {
+    const cleaned = value
+        .replace(/[^A-Za-z0-9_$]+/g, " ")
+        .trim()
+        .replace(/(?:^\w|[A-Z]|\b\w)/g, (chunk, index) => index === 0 ? chunk.toLowerCase() : chunk.toUpperCase())
+        .replace(/\s+/g, "");
+    return cleaned || "generatedNode";
+};
+const toPascalCase = (value) => {
+    const camel = sanitizeIdentifier(value);
+    return camel.charAt(0).toUpperCase() + camel.slice(1);
+};
+export const getNodeStubPath = (node) => {
+    if (!isCodeBearingNode(node)) {
+        return null;
+    }
+    const extension = node.kind === "ui-screen" ? "tsx" : "ts";
+    return `stubs/${node.kind.replace(/[^A-Za-z0-9]+/g, "-").toLowerCase()}-${node.name
+        .replace(/[^A-Za-z0-9]+/g, "-")
+        .toLowerCase()}.${extension}`;
+};
+export const getNodeRuntimeExport = (node) => {
+    if (node.kind === "function" || node.kind === "api") {
+        return sanitizeIdentifier(node.name.split(".").pop() ?? node.name);
+    }
+    if (node.kind === "class") {
+        return toPascalCase(node.name);
+    }
+    return null;
+};
+const formatField = (field) => `${field.name}: ${field.type}${field.description ? ` - ${field.description}` : ""}`;
+const formatCommentSection = (title, lines) => lines.length ? [` * ${title}:`, ...lines.map((line) => ` * - ${line}`)] : [];
+const buildDocComment = (node) => {
+    const contract = normalizeContract(node.contract);
+    const lines = [
+        "/**",
+        ` * ${node.summary}`,
+        " * @codeflowMaturity scaffold",
+        " * @codeflowValidation scaffold",
+        ...formatCommentSection("Responsibilities", contract.responsibilities),
+        ...formatCommentSection("Inputs", contract.inputs.map(formatField)),
+        ...formatCommentSection("Outputs", contract.outputs.map(formatField)),
+        ...formatCommentSection("Calls", contract.calls.map((call) => `${call.target}${call.kind ? ` [${call.kind}]` : ""}${call.description ? ` - ${call.description}` : ""}`)),
+        ...formatCommentSection("Errors", contract.errors),
+        ` * @blueprintId ${node.id}`,
+        " */"
+    ];
+    return `${lines.join("\n")}\n`;
+};
+const unwrapPromiseType = (value) => {
+    const match = value.trim().match(/^Promise<(.+)>$/);
+    return match ? match[1].trim() : null;
+};
+const buildReturnExpression = (returnType) => {
+    const normalizedType = returnType.trim();
+    if (!normalizedType || normalizedType === "void") {
+        return null;
+    }
+    const promisedType = unwrapPromiseType(normalizedType);
+    if (promisedType) {
+        const innerExpression = buildReturnExpression(promisedType) ?? "undefined";
+        return `Promise.resolve(${innerExpression})`;
+    }
+    if (normalizedType === "string") {
+        return '""';
+    }
+    if (normalizedType === "number" || normalizedType === "bigint") {
+        return "0";
+    }
+    if (normalizedType === "boolean") {
+        return "false";
+    }
+    if (normalizedType === "null") {
+        return "null";
+    }
+    if (normalizedType === "unknown" || normalizedType === "any") {
+        return "undefined";
+    }
+    if (normalizedType.startsWith("Array<") ||
+        normalizedType.startsWith("ReadonlyArray<") ||
+        normalizedType.endsWith("[]")) {
+        return `[] as ${normalizedType}`;
+    }
+    return `undefined as unknown as ${normalizedType}`;
+};
+const buildScaffoldNotice = (node) => {
+    const notes = [
+        `const scaffoldStatus = "CodeFlow scaffold for ${node.id}"`,
+        "console.warn(scaffoldStatus)"
+    ];
+    return notes.map((line) => `  ${line};`);
+};
+const buildChecklistComment = (node) => {
+    const contract = normalizeContract(node.contract);
+    return [
+        ...contract.responsibilities.map((item) => `// TODO: ${item}`),
+        ...contract.calls.map((call) => `// TODO: integrate ${call.target}${call.description ? ` (${call.description})` : ""}`),
+        ...contract.errors.map((error) => `// TODO: handle ${error}`)
+    ];
+};
+const buildFunctionCode = (node) => {
+    const contract = normalizeContract(node.contract);
+    const functionName = sanitizeIdentifier(node.name.split(".").pop() ?? node.name);
+    const inputList = contract.inputs
+        .map((field) => `${sanitizeIdentifier(field.name)}: ${field.type || "unknown"}`)
+        .join(", ");
+    const returnType = contract.outputs[0]?.type || "void";
+    const checklist = buildChecklistComment(node);
+    const scaffoldNotice = buildScaffoldNotice(node);
+    return `${buildDocComment(node)}export function ${functionName}(${inputList}): ${returnType} {
+${scaffoldNotice.join("\n")}
+${checklist.length ? `  ${checklist.join("\n  ")}\n` : ""}  throw new Error("CodeFlow scaffold: implementation required for ${node.id}");
+}
+`;
+};
+const buildApiCode = (node) => {
+    const functionName = sanitizeIdentifier(node.name.replace(/\s+/g, " "));
+    const checklist = buildChecklistComment(node);
+    return `${buildDocComment(node)}export async function ${functionName}(request: Request): Promise<Response> {
+  const body = await request.json().catch(() => null);
+${buildScaffoldNotice(node).join("\n")}
+${checklist.length ? `  ${checklist.join("\n  ")}\n` : ""}  return Response.json(
+    {
+      ok: false,
+      blueprintId: "${node.id}",
+      route: "${node.name}",
+      maturity: "scaffold",
+      received: body
+    },
+    { status: 501 }
+  );
+}
+`;
+};
+const buildUiScreenCode = (node) => {
+    const contract = normalizeContract(node.contract);
+    const componentName = toPascalCase(node.name);
+    const attributeNotes = contract.attributes.length
+        ? contract.attributes.map((attribute) => `      <li>${attribute.name}: ${attribute.type}</li>`).join("\n")
+        : '      <li>No state model defined yet.</li>';
+    const responsibilityNotes = contract.responsibilities.length
+        ? contract.responsibilities.map((item) => `        <li>${item}</li>`).join("\n")
+        : "        <li>Implementation responsibilities will appear here once the screen is wired.</li>";
+    return `${buildDocComment(node)}export default function ${componentName}(): JSX.Element {
+  return (
+    <main data-codeflow-maturity="scaffold">
+      <h1>${node.name}</h1>
+      <p>${node.summary}</p>
+      <p>This screen is a scaffold artifact. Replace the placeholder structure with real UI before shipping.</p>
+      <section>
+        <h2>Responsibilities</h2>
+        <ul>
+${responsibilityNotes}
+        </ul>
+      </section>
+      <section>
+        <h2>State / attributes</h2>
+        <ul>
+${attributeNotes}
+        </ul>
+      </section>
+    </main>
+  );
+}
+`;
+};
+const buildClassCode = (node, graph) => {
+    const contract = normalizeContract(node.contract);
+    const className = toPascalCase(node.name);
+    const ownedMethods = graph.nodes.filter((candidate) => candidate.ownerId === node.id && candidate.kind === "function");
+    const attributes = contract.attributes.length
+        ? contract.attributes
+            .map((attribute) => `  ${sanitizeIdentifier(attribute.name)}: ${attribute.type};`)
+            .join("\n")
+        : "  // TODO: add class attributes from the blueprint.";
+    const methods = (ownedMethods.length ? ownedMethods : [])
+        .map((methodNode) => {
+        const methodName = sanitizeIdentifier(methodNode.name.split(".").pop() ?? methodNode.name);
+        const methodContract = normalizeContract(methodNode.contract);
+        const inputList = methodContract.inputs
+            .map((field) => `${sanitizeIdentifier(field.name)}: ${field.type || "unknown"}`)
+            .join(", ");
+        const returnType = methodContract.outputs[0]?.type || "void";
+        return `  ${buildDocComment(methodNode)
+            .trimEnd()
+            .split("\n")
+            .map((line) => (line.startsWith(" *") || line.startsWith("/**") || line.startsWith(" */") ? `  ${line}` : line))
+            .join("\n")}
+  ${methodName}(${inputList}): ${returnType} {
+    throw new Error("CodeFlow scaffold: implementation required for ${methodNode.id}");
+  }`;
+    })
+        .join("\n\n");
+    return `${buildDocComment(node)}export class ${className} {
+${attributes}
+
+${methods || "  // TODO: add methods from the blueprint contract."}
+}
+`;
+};
+export const generateNodeCode = (node, graph) => {
+    if (!isCodeBearingNode(node)) {
+        return null;
+    }
+    if (node.kind === "function") {
+        return buildFunctionCode(node);
+    }
+    if (node.kind === "api") {
+        return buildApiCode(node);
+    }
+    if (node.kind === "ui-screen") {
+        return buildUiScreenCode(node);
+    }
+    if (node.kind === "class") {
+        return buildClassCode(node, graph);
+    }
+    return null;
+};

package/dist/internal/phases.d.ts

@@ -0,0 +1,17 @@
+import type { BlueprintGraph, BlueprintNode, BlueprintPhase, NodeVerification, ExecutionStep, RuntimeExecutionResult } from "../schema/index";
+export declare const getCodeBearingNodes: (graph: BlueprintGraph) => BlueprintNode[];
+export declare const withSpecDrafts: (graph: BlueprintGraph) => BlueprintGraph;
+export declare const canCompleteSpecPhase: (graph: BlueprintGraph) => boolean;
+export declare const canEnterImplementationPhase: (graph: BlueprintGraph) => boolean;
+export declare const canEnterIntegrationPhase: (graph: BlueprintGraph) => boolean;
+export declare const setGraphPhase: (graph: BlueprintGraph, phase: BlueprintPhase) => BlueprintGraph;
+export declare const updateNodeStatus: (graph: BlueprintGraph, nodeId: string, updater: (node: BlueprintNode) => BlueprintNode) => BlueprintGraph;
+export declare const markNodeImplemented: (graph: BlueprintGraph, nodeId: string, implementationDraft: string) => BlueprintGraph;
+export declare const createNodeVerification: (result: RuntimeExecutionResult, verifiedAt?: string) => NodeVerification;
+export declare const createNodeVerificationFromStep: (step: Pick<ExecutionStep, "status" | "stdout" | "stderr" | "completedAt">, exitCode?: number | null) => NodeVerification;
+export declare const markNodeVerified: (graph: BlueprintGraph, nodeId: string, result: RuntimeExecutionResult) => BlueprintGraph;
+export declare const getDefaultExecutionTarget: (graph: BlueprintGraph) => BlueprintNode | null;
+export declare const markGraphConnected: (graph: BlueprintGraph) => BlueprintGraph;
+export declare const applyExecutionResultToGraph: (graph: BlueprintGraph, result: RuntimeExecutionResult, options: {
+    integrationRun: boolean;
+}) => BlueprintGraph;