@openapi-flow/n8n 0.0.0-stage → 0.2.0

package/dist/workflow/build-n8n-workflow.js

@@ -0,0 +1,143 @@
+import { trigger, workflow, validateWorkflow } from '@n8n/workflow-sdk';
+import { validateNodeFragments } from './validate-node-fragments.js';
+import { createBatchExecutionScopes } from './batch/create-batch-execution-scopes.js';
+export function buildN8nWorkflow({ id, name, nodes, edges, starts, triggerConnections, annotations, batchScopes, }) {
+    if (!['connected', 'detached'].includes(triggerConnections))
+        throw new Error('triggerConnections must be connected or detached');
+    if (!Array.isArray(annotations) ||
+        annotations.some((item) => item.type !== 'n8n-nodes-base.stickyNote'))
+        throw new Error('workflow annotations must be Sticky Notes');
+    if (typeof id !== 'string' ||
+        !id.trim() ||
+        typeof name !== 'string' ||
+        !name.trim())
+        throw new Error('workflow.id and workflow.name must be non-empty');
+    if (!Array.isArray(nodes) ||
+        nodes.length === 0 ||
+        !Array.isArray(edges) ||
+        !Array.isArray(starts) ||
+        starts.length === 0)
+        throw new Error('workflow requires nodes, edges and explicit starts');
+    if (nodes.some((fragment) => fragment.nodes.some((item) => 'isTrigger' in item && item.isTrigger === true)))
+        throw new Error('workflow fragments must not introduce an additional trigger');
+    const byId = new Map(nodes.map((fragment) => [fragment.nodeId, fragment]));
+    if (byId.size !== nodes.length ||
+        nodes.some((fragment) => !fragment.nodeId.trim()))
+        throw new Error('workflow nodes require unique non-empty nodeId');
+    const batches = batchScopes === undefined
+        ? []
+        : createBatchExecutionScopes({
+            id,
+            name,
+            nodes,
+            edges,
+            starts,
+            batchScopes,
+        });
+    const sdkNodes = [
+        ...nodes.flatMap((fragment) => fragment.nodes),
+        ...annotations,
+        ...batches.map((batch) => batch.controller),
+    ];
+    const sdkIds = sdkNodes.map((node) => node.id);
+    const sdkNames = sdkNodes.map((node) => node.name);
+    if (new Set(sdkIds).size !== sdkIds.length ||
+        new Set(sdkNames).size !== sdkNames.length ||
+        sdkNames.includes('Start') ||
+        sdkIds.includes('openapi-flow-start'))
+        throw new Error('workflow SDK node IDs and names must be unique and not use the Start trigger identity');
+    validateNodeFragments(nodes);
+    if (starts.some((id) => {
+        const fragment = byId.get(id);
+        return (fragment?.inputEndpoints &&
+            new Set(Object.values(fragment.inputEndpoints).map((endpoint) => endpoint.nodeId)).size > 1);
+    }))
+        throw new Error('workflow starts cannot bypass independent fragment input endpoints');
+    const successors = new Map(nodes.map((fragment) => [fragment.nodeId, []]));
+    const inbound = new Map(nodes.map((fragment) => [fragment.nodeId, 0]));
+    const edgeIds = new Set();
+    for (const edge of edges) {
+        const source = byId.get(edge.from);
+        const target = byId.get(edge.to);
+        if (!source || !target)
+            throw new Error(`edge ${edge.from} -> ${edge.to} references a missing node`);
+        if (!Object.hasOwn(source.outputPorts, edge.output) ||
+            !Object.hasOwn(target.inputPorts, edge.input))
+            throw new Error(`edge ${edge.from} -> ${edge.to} references an undeclared port`);
+        const key = JSON.stringify(edge);
+        if (edgeIds.has(key))
+            throw new Error(`duplicate edge ${edge.from} -> ${edge.to}`);
+        edgeIds.add(key);
+        successors.get(edge.from).push(edge.to);
+        inbound.set(edge.to, inbound.get(edge.to) + 1);
+    }
+    const roots = [...inbound]
+        .filter(([, count]) => count === 0)
+        .map(([nodeId]) => nodeId);
+    if (new Set(starts).size !== starts.length ||
+        starts.some((nodeId) => !roots.includes(nodeId)) ||
+        roots.some((nodeId) => !starts.includes(nodeId)))
+        throw new Error('workflow.starts must identify every root exactly once');
+    const pending = [...roots];
+    let visited = 0;
+    while (pending.length) {
+        const current = pending.shift();
+        visited++;
+        for (const next of successors.get(current)) {
+            const count = inbound.get(next) - 1;
+            inbound.set(next, count);
+            if (count === 0)
+                pending.push(next);
+        }
+    }
+    if (visited !== nodes.length)
+        throw new Error('workflow DAG has a cycle');
+    const start = trigger({
+        type: 'n8n-nodes-base.manualTrigger',
+        version: 1,
+        config: { id: 'openapi-flow-start', name: 'Start', position: [0, 0] },
+    });
+    let built = workflow(id, name).add(start);
+    for (const fragment of nodes)
+        for (const node of fragment.nodes)
+            built = built.add(node);
+    for (const batch of batches) {
+        built = built.add(batch.controller);
+        built = built.connect(batch.controller, 1, byId.get(batch.scope.entryNodeId).entry, byId.get(batch.scope.entryNodeId).inputPorts.main);
+        built = built.connect(byId.get(batch.scope.exitNodeId).exit, byId.get(batch.scope.exitNodeId).outputPorts.main, batch.controller, 0);
+    }
+    for (const fragment of nodes)
+        for (const edge of fragment.internalEdges ?? [])
+            built = built.connect(fragment.nodes.find((item) => item.id === edge.from), edge.output, fragment.nodes.find((item) => item.id === edge.to), edge.input);
+    if (triggerConnections === 'connected')
+        for (const nodeId of starts)
+            built = built.connect(start, 0, batches.find((batch) => batch.scope.entryNodeId === nodeId)
+                ?.controller ?? byId.get(nodeId).entry, 0);
+    for (const note of annotations)
+        built = built.add(note);
+    for (const edge of edges) {
+        const source = byId.get(edge.from);
+        const target = byId.get(edge.to);
+        const endpoint = target.inputEndpoints?.[edge.input];
+        const sourceBatch = batches.find((batch) => batch.scope.exitNodeId === edge.from &&
+            !batch.scope.nodeIds.includes(edge.to));
+        const targetBatch = batches.find((batch) => batch.scope.entryNodeId === edge.to &&
+            !batch.scope.nodeIds.includes(edge.from));
+        built = built.connect(sourceBatch ? sourceBatch.controller : source.exit, sourceBatch ? 0 : source.outputPorts[edge.output], targetBatch
+            ? targetBatch.controller
+            : endpoint
+                ? target.nodes.find((node) => node.id === endpoint.nodeId)
+                : target.entry, targetBatch
+            ? 0
+            : endpoint
+                ? endpoint.input
+                : target.inputPorts[edge.input]);
+    }
+    const checked = validateWorkflow(built);
+    if (!checked.valid)
+        throw new Error(`n8n SDK validation failed: ${checked.errors.map((error) => error.message).join('; ')}`);
+    const result = built.toJSON();
+    if (triggerConnections === 'detached')
+        result.active = false;
+    return result;
+}

package/dist/workflow/compile-native-workflow-nodes.d.ts

@@ -0,0 +1,3 @@
+import type { CompileNativeWorkflowNodesInput } from '../types/native-capability.js';
+import type { N8nNodeFragment } from '../types/node-fragment.js';
+export declare function compileNativeWorkflowNodes(input: CompileNativeWorkflowNodesInput): N8nNodeFragment[];

package/dist/workflow/compile-native-workflow-nodes.js

@@ -0,0 +1,26 @@
+export function compileNativeWorkflowNodes(input) {
+    const names = Object.fromEntries(input.apiNodes.map((item) => [item.nodeId, item.exit.name]));
+    const apiResponseContracts = Object.fromEntries(input.materials.map((item) => [item.arguments.callId, item.operation]));
+    const nativeNodes = input.plan.nativeNodes.map((planned, index) => {
+        const capability = input.capabilities.find((item) => item.name === planned.capability);
+        if (!capability)
+            throw new Error(`Missing native compiler ${planned.capability}`);
+        const compiled = capability.compile({
+            planned,
+            apiNodeNames: names,
+            apiResponseContracts,
+            position: [600 + index * 250, 300],
+        });
+        if (compiled.nodeId !== planned.id ||
+            JSON.stringify(Object.keys(compiled.inputPorts)) !==
+                JSON.stringify(capability.inputPorts(planned.parameters)) ||
+            JSON.stringify(Object.keys(compiled.outputPorts)) !==
+                JSON.stringify(capability.outputPorts(planned.parameters)))
+            throw new Error(`Native compiler ${planned.capability} violated declared node identity/ports`);
+        if (compiled.rejoinsExclusiveOutputs !==
+            capability.rejoinsExclusiveOutputs?.(planned.parameters))
+            throw new Error(`Native compiler ${planned.capability} violated declared rejoinsExclusiveOutputs`);
+        return compiled;
+    });
+    return nativeNodes;
+}

package/dist/workflow/compile-planned-n8n-workflow.d.ts

@@ -0,0 +1,3 @@
+import type { CompilePlannedN8nWorkflowInput } from '../types/native-capability.js';
+import type { N8nCompileResult } from '../types/workflow-compilation.js';
+export declare function compilePlannedN8nWorkflow(input: CompilePlannedN8nWorkflowInput): N8nCompileResult;

package/dist/workflow/compile-planned-n8n-workflow.js

@@ -0,0 +1,17 @@
+import { assembleN8nWorkflow } from './assemble-n8n-workflow.js';
+import { compileValidatedWorkflowFragments } from './compile-validated-workflow-fragments.js';
+export function compilePlannedN8nWorkflow(input) {
+    const nodes = compileValidatedWorkflowFragments(input);
+    const result = assembleN8nWorkflow({
+        id: input.id,
+        name: input.name,
+        nodes,
+        edges: input.plan.edges,
+        starts: input.plan.starts,
+    });
+    result.workflow.settings = {
+        ...result.workflow.settings,
+        executionOrder: 'v1',
+    };
+    return result;
+}

package/dist/workflow/compile-reviewable-n8n-workflow.d.ts

@@ -0,0 +1,3 @@
+import type { CompileReviewableN8nWorkflowInput } from '../types/reviewable-workflow.js';
+import type { N8nWorkflowResult } from '../types/workflow-compilation.js';
+export declare function compileReviewableN8nWorkflow(input: CompileReviewableN8nWorkflowInput): N8nWorkflowResult;

package/dist/workflow/compile-reviewable-n8n-workflow.js

@@ -0,0 +1,70 @@
+import { validateReviewableWorkflowGraphPlan, createNativeOutputContracts, } from '@openapi-flow/core';
+import { createGapReviewRegion } from './review/create-gap-review-region.js';
+import { GAP_REVIEW_REGION_WIDTH, GAP_REVIEW_REGION_SPACING, } from './review/gap-review-region-layout.js';
+import { compilePlannedN8nWorkflow } from './compile-planned-n8n-workflow.js';
+import { compileNativeWorkflowNodes } from './compile-native-workflow-nodes.js';
+import { buildN8nWorkflow } from './build-n8n-workflow.js';
+import { validateCompiledBindingSources } from './validate-compiled-binding-sources.js';
+export function compileReviewableN8nWorkflow(input) {
+    validateReviewableWorkflowGraphPlan(input);
+    const blocked = new Set(input.plan.blockedCalls.map((item) => item.callId));
+    const ready = input.materials.filter((item) => item.status === 'ready' && !blocked.has(item.arguments.callId));
+    const expected = ready.map((item) => item.arguments.callId).sort();
+    const actual = input.apiNodes.map((item) => item.nodeId).sort();
+    if (JSON.stringify(expected) !== JSON.stringify(actual))
+        throw new Error('review apiNodes must exactly match unblocked ready calls');
+    if (!input.plan.gaps.length)
+        return compilePlannedN8nWorkflow({ ...input, materials: ready });
+    const nativeNodes = compileNativeWorkflowNodes({
+        ...input,
+        materials: ready,
+    });
+    validateCompiledBindingSources(input.apiNodes, nativeNodes, createNativeOutputContracts({
+        nativeNodes: input.plan.nativeNodes,
+        capabilities: input.capabilities,
+    }), ready);
+    const occupiedPositions = [...input.apiNodes, ...nativeNodes].flatMap((fragment) => fragment.nodes.flatMap((node) => node.config.position === undefined ? [] : [node.config.position]));
+    const regionTop = Math.max(0, ...occupiedPositions.map((point) => point[1])) + 240;
+    const regionStep = GAP_REVIEW_REGION_WIDTH + GAP_REVIEW_REGION_SPACING;
+    const placeholders = input.plan.gaps.map((gap, index) => ({
+        nodeId: gap.id,
+        gaps: [gap],
+        position: [600 + index * regionStep, regionTop],
+    }));
+    for (const [index, item] of input.plan.blockedCalls.entries()) {
+        const material = input.materials.find((material) => (material.status === 'ready'
+            ? material.arguments.callId
+            : material.callId) === item.callId);
+        if (!material)
+            throw new Error('review placeholder material is missing');
+        placeholders.push({
+            nodeId: item.callId,
+            gaps: input.plan.gaps.filter((gap) => item.gapIds.includes(gap.id)),
+            operation: material.operation,
+            position: [
+                600 + (input.plan.gaps.length + index) * regionStep,
+                regionTop,
+            ],
+        });
+    }
+    const regions = placeholders.map(createGapReviewRegion);
+    const result = buildN8nWorkflow({
+        id: input.id,
+        name: input.name,
+        nodes: [
+            ...input.apiNodes,
+            ...nativeNodes,
+            ...regions.map((region) => region.fragment),
+        ],
+        edges: input.plan.edges,
+        starts: input.plan.starts,
+        triggerConnections: 'detached',
+        annotations: regions.map((region) => region.annotation),
+    });
+    result.settings = { ...result.settings, executionOrder: 'v1' };
+    return {
+        status: 'needs-review',
+        workflow: result,
+        diagnostics: input.plan.gaps,
+    };
+}

package/dist/workflow/compile-validated-workflow-fragments.d.ts

@@ -0,0 +1,3 @@
+import type { CompilePlannedN8nWorkflowInput } from '../types/native-capability.js';
+import type { N8nNodeFragment } from '../types/node-fragment.js';
+export declare function compileValidatedWorkflowFragments(input: CompilePlannedN8nWorkflowInput): N8nNodeFragment[];

package/dist/workflow/compile-validated-workflow-fragments.js

@@ -0,0 +1,20 @@
+import { compileNativeWorkflowNodes } from './compile-native-workflow-nodes.js';
+import { validateWorkflowGraphPlan, createNativeOutputContracts, } from '@openapi-flow/core';
+import { validateCompiledBindingSources } from './validate-compiled-binding-sources.js';
+export function compileValidatedWorkflowFragments(input) {
+    if (input.plan.gaps.length)
+        throw new Error(`Workflow needs review: ${JSON.stringify(input.plan.gaps)}`);
+    validateWorkflowGraphPlan(input);
+    const expectedIds = input.materials
+        .map((item) => item.arguments.callId)
+        .sort();
+    const actualIds = input.apiNodes.map((item) => item.nodeId).sort();
+    if (JSON.stringify(expectedIds) !== JSON.stringify(actualIds))
+        throw new Error('apiNodes must match material callIds exactly');
+    const nativeNodes = compileNativeWorkflowNodes(input);
+    validateCompiledBindingSources(input.apiNodes, nativeNodes, createNativeOutputContracts({
+        nativeNodes: input.plan.nativeNodes,
+        capabilities: input.capabilities,
+    }), input.materials);
+    return [...input.apiNodes, ...nativeNodes];
+}

package/dist/workflow/create-n8n-native-output-sources.d.ts

@@ -0,0 +1,3 @@
+import type { CreateN8nNativeOutputSourcesInput, N8nNativeOutputSource } from '../types/output-binding-source.js';
+/** Resolve runtime names from the actual SDK producer, not an ID/name guess. */
+export declare function createN8nNativeOutputSources(input: CreateN8nNativeOutputSourcesInput): N8nNativeOutputSource[];

package/dist/workflow/create-n8n-native-output-sources.js

@@ -0,0 +1,17 @@
+import { createNativeOutputContracts } from '@openapi-flow/core';
+/** Resolve runtime names from the actual SDK producer, not an ID/name guess. */
+export function createN8nNativeOutputSources(input) {
+    const outputs = createNativeOutputContracts(input);
+    return outputs.map((output) => {
+        const planned = input.nativeNodes.find((item) => item.id === output.nodeId);
+        const capability = input.capabilities.find((item) => item.name === planned.capability);
+        const fragment = capability.compile({
+            planned,
+            apiNodeNames: input.apiNodeNames,
+            position: [600, 300],
+        });
+        if (fragment.nodeId !== output.nodeId || !fragment.exit.name.trim())
+            throw new Error(`native output ${output.nodeId} requires its compiled identity/name`);
+        return { ...output, nodeName: fragment.exit.name };
+    });
+}

package/dist/workflow/review/create-gap-review-content.d.ts

@@ -0,0 +1,2 @@
+import type { CreateGapNodeInput } from '../../types/reviewable-workflow.js';
+export declare function createGapReviewContent(input: CreateGapNodeInput): string[];

package/dist/workflow/review/create-gap-review-content.js

@@ -0,0 +1,28 @@
+import { escapeReviewMarkdown } from './escape-review-markdown.js';
+const stageLabels = {
+    'api-selection': 'API 선택',
+    'api-bindings': '요청값 연결',
+    'workflow-graph': '워크플로 구성',
+};
+export function createGapReviewContent(input) {
+    const content = [
+        '# 확인 필요',
+        '미해결 단계: ' + escapeReviewMarkdown(input.nodeId),
+        ...input.gaps.map((gap) => escapeReviewMarkdown(`${stageLabels[gap.stage]} — ${gap.description}`)),
+        '아래 노드는 미해결 작업의 위치를 표시하는 대역입니다. 실제 API를 호출하거나 응답을 만들지 않습니다.',
+        '실수로 실행하지 않도록 Start의 연결을 끊어 두었습니다. 이 대역을 직접 실행하거나 다시 연결하면 오류로 중단됩니다.',
+        '필요한 API·입력값·연결을 확인한 뒤 대역을 실제 구현으로 교체하고 검증하세요. 교체 전에는 Start를 연결하지 마세요.',
+    ];
+    for (const gap of input.gaps)
+        if (gap.callId !== undefined && gap.targetPointer !== undefined)
+            content.push('확인할 요청값: ' +
+                escapeReviewMarkdown(gap.callId + gap.targetPointer));
+    if (input.operation)
+        content.push('대상 OAS 작업: ' +
+            escapeReviewMarkdown(input.operation.key.documentId +
+                ' ' +
+                input.operation.method +
+                ' ' +
+                input.operation.path));
+    return content;
+}

package/dist/workflow/review/create-gap-review-region.d.ts

@@ -0,0 +1,2 @@
+import type { CreateGapNodeInput, GapReviewRegion } from '../../types/reviewable-workflow.js';
+export declare function createGapReviewRegion(input: CreateGapNodeInput): GapReviewRegion;

package/dist/workflow/review/create-gap-review-region.js

@@ -0,0 +1,23 @@
+import { sticky } from '@n8n/workflow-sdk';
+import { createGapNode } from '../../nodes/gap/create-gap-node.js';
+import { createGapReviewContent } from './create-gap-review-content.js';
+import { gapReviewRegionLayout } from './gap-review-region-layout.js';
+export function createGapReviewRegion(input) {
+    const content = createGapReviewContent(input);
+    const layout = gapReviewRegionLayout(input.position, content);
+    const fragment = createGapNode({
+        ...input,
+        position: layout.nodePosition,
+    });
+    return {
+        fragment,
+        annotation: sticky(content.join('\n\n'), fragment.nodes, {
+            id: 'openapi-flow-gap-note-' + input.nodeId,
+            name: '확인 안내 · ' + input.nodeId,
+            position: layout.notePosition,
+            color: 3,
+            width: layout.width,
+            height: layout.height,
+        }),
+    };
+}

package/dist/workflow/review/escape-review-markdown.d.ts

@@ -0,0 +1 @@
+export declare function escapeReviewMarkdown(value: string): string;

package/dist/workflow/review/escape-review-markdown.js

@@ -0,0 +1,7 @@
+export function escapeReviewMarkdown(value) {
+    return value
+        .replace(/&/g, '&')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/([\\`*_{}[\]()#+.!|~-])/g, '\\$1');
+}

package/dist/workflow/review/gap-review-region-layout.d.ts

@@ -0,0 +1,4 @@
+import type { GapReviewRegionLayout } from '../../types/reviewable-workflow.js';
+export declare const GAP_REVIEW_REGION_WIDTH = 560;
+export declare const GAP_REVIEW_REGION_SPACING = 64;
+export declare function gapReviewRegionLayout(origin: [number, number], content: string[]): GapReviewRegionLayout;

package/dist/workflow/review/gap-review-region-layout.js

@@ -0,0 +1,21 @@
+export const GAP_REVIEW_REGION_WIDTH = 560;
+export const GAP_REVIEW_REGION_SPACING = 64;
+// Reserve the upper area for wrapped Markdown, then place the node below it.
+// These are canvas spacing metrics, not limits on diagnostic text or OAS data.
+export function gapReviewRegionLayout(origin, content) {
+    const textHeight = 96 +
+        content
+            .slice(1)
+            .reduce((height, paragraph) => height +
+            paragraph
+                .split('\n')
+                .reduce((lines, line) => lines + Math.max(1, Math.ceil(Array.from(line).length / 34)), 0) *
+                28 +
+            16, 0);
+    return {
+        notePosition: origin,
+        nodePosition: [origin[0] + 232, origin[1] + textHeight + 32],
+        width: GAP_REVIEW_REGION_WIDTH,
+        height: textHeight + 272,
+    };
+}

package/dist/workflow/validate-compiled-binding-sources.d.ts

@@ -0,0 +1,4 @@
+import type { NativeOutputContract, WorkflowApiMaterial } from '@openapi-flow/core';
+import type { N8nNodeFragment } from '../types/node-fragment.js';
+/** The runtime reader must use the same producer/root/schema the plan validated. */
+export declare function validateCompiledBindingSources(apiNodes: N8nNodeFragment[], nativeNodes: N8nNodeFragment[], contracts: NativeOutputContract[], materials: WorkflowApiMaterial[]): void;

package/dist/workflow/validate-compiled-binding-sources.js

@@ -0,0 +1,40 @@
+import { isDeepStrictEqual } from 'node:util';
+/** The runtime reader must use the same producer/root/schema the plan validated. */
+export function validateCompiledBindingSources(apiNodes, nativeNodes, contracts, materials) {
+    const apis = new Map(apiNodes.map((fragment) => [fragment.nodeId, fragment]));
+    const natives = new Map(nativeNodes.map((fragment) => [fragment.nodeId, fragment]));
+    const outputs = new Map(contracts.map((contract) => [contract.nodeId, contract]));
+    for (const fragment of apiNodes) {
+        const material = materials.find((item) => item.arguments.callId === fragment.nodeId);
+        if (!material)
+            throw new Error(`binding fragment ${fragment.nodeId} has no API material`);
+        const expected = [
+            ...new Set(material.arguments.bindings
+                .map((binding) => binding.sourceNodeId)
+                .filter((id) => outputs.has(id))),
+        ].sort();
+        const actual = (fragment.bindingSources ?? [])
+            .filter((source) => source.kind === 'native-json')
+            .map((source) => source.nodeId)
+            .sort();
+        if (!isDeepStrictEqual(expected, actual))
+            throw new Error(`binding fragment ${fragment.nodeId} must declare every native producer exactly once`);
+    }
+    for (const fragment of [...apiNodes, ...nativeNodes]) {
+        for (const source of fragment.bindingSources ?? []) {
+            const producer = source.kind === 'api-response'
+                ? apis.get(source.nodeId)
+                : natives.get(source.nodeId);
+            if (!producer || producer.exit.name !== source.nodeName)
+                throw new Error(`binding source ${source.nodeId} does not match its compiled producer name/kind`);
+            if (source.kind === 'native-json' &&
+                !isDeepStrictEqual(source.schema, outputs.get(source.nodeId)?.schema))
+                throw new Error(`binding source ${source.nodeId} does not match its declared native output schema`);
+            if (source.kind === 'api-response' &&
+                source.operation &&
+                !isDeepStrictEqual(source.operation, materials.find((item) => item.arguments.callId === source.nodeId)
+                    ?.operation))
+                throw new Error(`binding source ${source.nodeId} does not match its original OAS response contract`);
+        }
+    }
+}

package/dist/workflow/validate-node-fragments.d.ts

@@ -0,0 +1,3 @@
+import type { N8nNodeFragment } from '../types/node-fragment.js';
+/** Internal implementation nodes must form one declared-entries-to-exit DAG. */
+export declare function validateNodeFragments(fragments: N8nNodeFragment[]): void;

package/dist/workflow/validate-node-fragments.js

@@ -0,0 +1,58 @@
+/** Internal implementation nodes must form one declared-entries-to-exit DAG. */
+export function validateNodeFragments(fragments) {
+    for (const fragment of fragments) {
+        const byId = new Map(fragment.nodes.map((item) => [item.id, item]));
+        if (!fragment.nodes.includes(fragment.entry) ||
+            !fragment.nodes.includes(fragment.exit) ||
+            byId.size !== fragment.nodes.length)
+            throw new Error(`node fragment ${fragment.nodeId} has invalid entry/exit or duplicate IDs`);
+        const edges = fragment.internalEdges ?? [];
+        const endpoints = fragment.inputEndpoints;
+        if (endpoints &&
+            (Object.keys(endpoints).length !==
+                Object.keys(fragment.inputPorts).length ||
+                Object.keys(fragment.inputPorts).some((port) => !Object.hasOwn(endpoints, port) ||
+                    !byId.has(endpoints[port].nodeId) ||
+                    !Number.isInteger(endpoints[port].input) ||
+                    endpoints[port].input < 0 ||
+                    endpoints[port].input !== fragment.inputPorts[port]) ||
+                !Object.values(endpoints).some((endpoint) => endpoint.nodeId === fragment.entry.id)))
+            throw new Error(`node fragment ${fragment.nodeId} has invalid input endpoints`);
+        const entries = endpoints
+            ? new Set(Object.values(endpoints).map((endpoint) => endpoint.nodeId))
+            : new Set([fragment.entry.id]);
+        const keys = new Set();
+        for (const edge of edges) {
+            const key = JSON.stringify(edge);
+            if (!byId.has(edge.from) ||
+                !byId.has(edge.to) ||
+                keys.has(key) ||
+                !Number.isInteger(edge.output) ||
+                edge.output < 0 ||
+                !Number.isInteger(edge.input) ||
+                edge.input < 0)
+                throw new Error(`node fragment ${fragment.nodeId} has an invalid internal edge`);
+            keys.add(key);
+        }
+        const reached = new Set();
+        const active = new Set();
+        function visit(id) {
+            if (active.has(id))
+                throw new Error(`node fragment ${fragment.nodeId} has an internal cycle`);
+            if (reached.has(id))
+                return;
+            active.add(id);
+            for (const edge of edges.filter((item) => item.from === id))
+                visit(edge.to);
+            active.delete(id);
+            reached.add(id);
+        }
+        for (const entry of entries)
+            visit(entry);
+        if (reached.size !== byId.size ||
+            edges.some((edge) => entries.has(edge.to) || edge.from === fragment.exit.id) ||
+            fragment.nodes.some((item) => item !== fragment.exit &&
+                !edges.some((edge) => edge.from === item.id)))
+            throw new Error(`node fragment ${fragment.nodeId} must connect every internal node from entry to exit`);
+    }
+}

package/package.json

@@ -1,6 +1,56 @@
 {
   "name": "@openapi-flow/n8n",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "license": "MIT",
+  "type": "module",
+  "description": "Deterministic OpenAPI request nodes and n8n workflow assembly",
+  "engines": {
+    "node": ">=24"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/public-api.d.ts",
+      "default": "./dist/public-api.js"
+    },
+    "./legacy": {
+      "types": "./dist/legacy-api.d.ts",
+      "default": "./dist/legacy-api.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "THIRD_PARTY_NOTICES.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json && node ../../scripts/build-request-runtime.mjs && node ../../scripts/build-item-join-runtime.mjs && node ../../scripts/build-response-runtime.mjs",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  },
+  "dependencies": {
+    "@n8n/config": "2.41.2",
+    "@n8n/workflow-sdk": "0.36.4",
+    "@openapi-flow/core": "0.2.0",
+    "@sentry/node": "10.70.0",
+    "@types/estree": "1.0.8",
+    "@types/express": "5.0.1",
+    "@types/json-schema": "7.0.15",
+    "@types/luxon": "3.2.0",
+    "@types/semver": "7.7.0",
+    "@types/ssh2": "1.15.0",
+    "ajv": "8.20.0",
+    "ajv-formats": "3.0.1",
+    "esbuild": "0.28.2",
+    "nock": "14.0.14",
+    "zod": "4.6.5"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/carefreelife98/openapi-flow.git",
+    "directory": "packages/n8n"
+  }
+}