@openapi-flow/n8n 0.2.0 → 0.3.1

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

@@ -5,8 +5,15 @@ 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';
+import { prepareNativeRuntimeInputs, assembleNativeRuntimeInputs, } from './inputs/compile-native-runtime-inputs.js';
 export function compileReviewableN8nWorkflow(input) {
-    validateReviewableWorkflowGraphPlan(input);
+    // This legacy executable-fragment path does not own deferred API input slots.
+    // Only the canonical template compiler may install their preflight/materialization nodes.
+    validateReviewableWorkflowGraphPlan({
+        materials: input.materials,
+        capabilities: input.capabilities,
+        plan: input.plan,
+    });
     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();
@@ -15,9 +22,23 @@ export function compileReviewableN8nWorkflow(input) {
         throw new Error('review apiNodes must exactly match unblocked ready calls');
     if (!input.plan.gaps.length)
         return compilePlannedN8nWorkflow({ ...input, materials: ready });
+    const nativeInputs = prepareNativeRuntimeInputs({
+        nativeInputs: input.nativeInputs,
+        nativeNodes: input.plan.nativeNodes,
+        capabilities: input.capabilities,
+        apiMaterials: ready.map((item) => ({
+            callId: item.arguments.callId,
+            operation: item.operation,
+            requestMediaType: item.arguments.requestMediaType,
+        })),
+        nativeOutputs: [],
+    });
     const nativeNodes = compileNativeWorkflowNodes({
         ...input,
         materials: ready,
+        capabilities: nativeInputs === undefined
+            ? input.capabilities
+            : nativeInputs.capabilities,
     });
     validateCompiledBindingSources(input.apiNodes, nativeNodes, createNativeOutputContracts({
         nativeNodes: input.plan.nativeNodes,
@@ -48,7 +69,7 @@ export function compileReviewableN8nWorkflow(input) {
         });
     }
     const regions = placeholders.map(createGapReviewRegion);
-    const result = buildN8nWorkflow({
+    const graph = {
         id: input.id,
         name: input.name,
         nodes: [
@@ -60,11 +81,18 @@ export function compileReviewableN8nWorkflow(input) {
         starts: input.plan.starts,
         triggerConnections: 'detached',
         annotations: regions.map((region) => region.annotation),
-    });
+    };
+    const compiled = nativeInputs === undefined
+        ? undefined
+        : assembleNativeRuntimeInputs({ ...graph, nativeInputs });
+    const result = compiled === undefined ? buildN8nWorkflow(graph) : compiled.workflow;
     result.settings = { ...result.settings, executionOrder: 'v1' };
     return {
         status: 'needs-review',
         workflow: result,
         diagnostics: input.plan.gaps,
+        ...(compiled === undefined
+            ? {}
+            : { nativeInputTemplate: compiled.nativeInputTemplate }),
     };
 }

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

@@ -1,20 +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';
+import { validateWorkflowGraphPlan } from '@openapi-flow/core';
+import { compileWorkflowMaterialFragments } from './compile-workflow-material-fragments.js';
+import { resolveN8nNativeMaterials } from './resolve-n8n-native-materials.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({
+    const materialSnapshot = resolveN8nNativeMaterials({
+        apiMaterials: input.materials.map((material) => ({
+            callId: material.arguments.callId,
+            operation: material.operation,
+            requestMediaType: material.arguments.requestMediaType,
+        })),
+        nativeOutputs: [],
         nativeNodes: input.plan.nativeNodes,
         capabilities: input.capabilities,
-    }), input.materials);
-    return [...input.apiNodes, ...nativeNodes];
+    });
+    const current = { ...input, capabilities: materialSnapshot.capabilities };
+    validateWorkflowGraphPlan(current);
+    return compileWorkflowMaterialFragments(current);
 }

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

@@ -0,0 +1,4 @@
+import type { CompileNativeWorkflowNodesInput } from '../types/native-capability.js';
+import type { N8nNodeFragment } from '../types/node-fragment.js';
+/** Shared SDK material lowering. The owning strict/draft boundary validates the whole topology first. */
+export declare function compileWorkflowMaterialFragments(input: CompileNativeWorkflowNodesInput): N8nNodeFragment[];

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

@@ -0,0 +1,18 @@
+import { createNativeOutputContracts } from '@openapi-flow/core';
+import { compileNativeWorkflowNodes } from './compile-native-workflow-nodes.js';
+import { validateCompiledBindingSources } from './validate-compiled-binding-sources.js';
+/** Shared SDK material lowering. The owning strict/draft boundary validates the whole topology first. */
+export function compileWorkflowMaterialFragments(input) {
+    const expected = input.materials
+        .map((material) => material.arguments.callId)
+        .sort();
+    const actual = input.apiNodes.map((fragment) => fragment.nodeId).sort();
+    if (JSON.stringify(expected) !== JSON.stringify(actual))
+        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.js

@@ -1,17 +1,58 @@
-import { createNativeOutputContracts } from '@openapi-flow/core';
+import { inspectNativeReferenceStructure, resolveNativeStructureParameters, } from '@openapi-flow/core';
+import { resolveN8nNativeMaterials } from './resolve-n8n-native-materials.js';
+import { compileNativeMaterialFragments } from './compile-native-material-fragments.js';
+import { prepareNativeRuntimeInputs } from './inputs/compile-native-runtime-inputs.js';
 /** 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],
+    const references = input.nativeNodes.flatMap((node) => {
+        const capability = input.capabilities.find((capability) => capability.name === node.capability);
+        if (!capability)
+            throw new Error('Missing native compiler ' + node.capability);
+        if (capability.referenceStructureSchema)
+            return inspectNativeReferenceStructure({ node, capability }).map((binding) => binding.reference);
+        const parameters = resolveNativeStructureParameters(node, capability);
+        return [
+            ...capability.responseReferences(parameters),
+            ...Object.values(capability.inputReferences
+                ? capability.inputReferences(parameters)
+                : {}).flat(),
+        ];
+    });
+    for (const reference of references)
+        if (reference.source === 'response' &&
+            (!input.apiResponseContracts ||
+                !Object.hasOwn(input.apiResponseContracts, reference.nodeId)))
+            throw new Error('createN8nNativeOutputSources.apiResponseContracts is missing ' +
+                reference.nodeId);
+    const apiMaterials = input.apiResponseContracts === undefined
+        ? []
+        : Object.entries(input.apiResponseContracts).map(([callId, operation]) => ({ callId, operation }));
+    const externalNativeOutputSources = input.externalNativeOutputSources === undefined
+        ? []
+        : input.externalNativeOutputSources;
+    const nativeInputs = input.nativeInputs === undefined
+        ? undefined
+        : prepareNativeRuntimeInputs({
+            nativeInputs: input.nativeInputs,
+            nativeNodes: input.nativeNodes,
+            capabilities: input.capabilities,
+            apiMaterials,
+            nativeOutputs: externalNativeOutputSources,
         });
-        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 };
+    const materials = resolveN8nNativeMaterials({
+        apiMaterials,
+        nativeOutputs: externalNativeOutputSources,
+        nativeNodes: input.nativeNodes,
+        capabilities: nativeInputs === undefined
+            ? input.capabilities
+            : nativeInputs.capabilities,
     });
+    return compileNativeMaterialFragments({
+        nativeNodes: input.nativeNodes,
+        materials,
+        apiMaterials,
+        apiNodeNames: input.apiNodeNames,
+        externalNativeOutputSources,
+        nodeIds: materials.outputs.map((output) => output.nodeId),
+    }).outputSources;
 }

package/dist/workflow/entrypoint/manual-trigger.d.ts

@@ -0,0 +1,4 @@
+import type { WorkflowEntryPointContract } from '@openapi-flow/core';
+/** The same compiler-owned start is described to planning and built by the SDK. */
+export declare function describeN8nManualTrigger(): WorkflowEntryPointContract;
+export declare function createN8nManualTrigger(): import("@n8n/workflow-sdk").TriggerInstance<string, `${number}`, unknown>;

package/dist/workflow/entrypoint/manual-trigger.js

@@ -0,0 +1,16 @@
+import { trigger } from '@n8n/workflow-sdk';
+const nodeType = 'n8n-nodes-base.manualTrigger';
+/** The same compiler-owned start is described to planning and built by the SDK. */
+export function describeN8nManualTrigger() {
+    return {
+        kind: nodeType,
+        description: 'The n8n compiler supplies one Manual Trigger start. Users run the workflow manually; this entrypoint is not a selectable native capability and requires no extra planned trigger instance.',
+    };
+}
+export function createN8nManualTrigger() {
+    return trigger({
+        type: nodeType,
+        version: 1,
+        config: { id: 'openapi-flow-start', name: 'Start', position: [0, 0] },
+    });
+}

package/dist/workflow/find-singleton-api-responses.d.ts

@@ -0,0 +1,3 @@
+import type { CompileNativeWorkflowNodesInput } from '../types/native-capability.js';
+/** Prove at-most-one output from the single Manual Trigger item; unknown native streams are not singleton evidence. */
+export declare function findSingletonApiResponses(input: CompileNativeWorkflowNodesInput): string[];

package/dist/workflow/find-singleton-api-responses.js

@@ -0,0 +1,22 @@
+/** Prove at-most-one output from the single Manual Trigger item; unknown native streams are not singleton evidence. */
+export function findSingletonApiResponses(input) {
+    const proven = new Set();
+    const pending = input.apiNodes.filter((fragment) => fragment.preservesInputItems === true);
+    let changed = true;
+    while (pending.length && changed) {
+        changed = false;
+        for (let index = 0; index < pending.length;) {
+            const node = pending[index];
+            const incoming = input.plan.edges.filter((edge) => edge.to === node.nodeId);
+            const isRoot = incoming.length === 0 && input.plan.starts.includes(node.nodeId);
+            if (isRoot || (incoming.length === 1 && proven.has(incoming[0].from))) {
+                proven.add(node.nodeId);
+                pending.splice(index, 1);
+                changed = true;
+            }
+            else
+                index++;
+        }
+    }
+    return [...proven];
+}

package/dist/workflow/inputs/compile-native-runtime-inputs.d.ts

@@ -0,0 +1,5 @@
+import type { PrepareNativeRuntimeInputsInput, PreparedNativeRuntimeInputs, AssembleNativeRuntimeInputsInput, N8nNativeInputCompilationResult } from '../../types/native-runtime-parameters.js';
+/** One explicit execution-input protocol, shared by strict and review compilation. */
+export declare function prepareNativeRuntimeInputs(input: PrepareNativeRuntimeInputsInput): PreparedNativeRuntimeInputs | undefined;
+/** Preserve every original DAG edge; only explicit system roots precede the graph. */
+export declare function assembleNativeRuntimeInputs(input: AssembleNativeRuntimeInputsInput): N8nNativeInputCompilationResult;

package/dist/workflow/inputs/compile-native-runtime-inputs.js

@@ -0,0 +1,129 @@
+import { sticky } from '@n8n/workflow-sdk';
+import { inspectNativeRuntimeInputs, createNativeRuntimeParameterMaterializations, } from '@openapi-flow/core';
+import { n8nNativeInputConfigurationSchema } from '../../schemas/native-runtime-input-schema.js';
+import { resolveN8nNativeMaterials } from '../resolve-n8n-native-materials.js';
+import { createRuntimeInputNativeCapabilities } from './create-runtime-input-native-capabilities.js';
+import { createTemplateInputNodes } from '../../nodes/inputs/create-template-input-nodes.js';
+import { buildN8nWorkflow } from '../build-n8n-workflow.js';
+import { TEMPLATE_INPUT_ID, TEMPLATE_INPUT_NAME, TEMPLATE_PREFLIGHT_ID, TEMPLATE_PREFLIGHT_NAME, TEMPLATE_GUIDE_ID, } from '../templates/workflow-template-identities.js';
+/** One explicit execution-input protocol, shared by strict and review compilation. */
+export function prepareNativeRuntimeInputs(input) {
+    if (input.nativeInputs === undefined) {
+        if (input.nativeNodes.some((node) => node.runtimeParameters !== undefined))
+            throw new Error('nativeInputs.revision is required when the plan declares native runtime parameters');
+        return undefined;
+    }
+    const configuration = n8nNativeInputConfigurationSchema.parse(input.nativeInputs);
+    const snapshot = resolveN8nNativeMaterials({
+        apiMaterials: input.apiMaterials,
+        nativeOutputs: input.nativeOutputs,
+        nativeNodes: input.nativeNodes,
+        capabilities: input.capabilities,
+    });
+    const inputValues = configuration.inputValues === undefined ? {} : configuration.inputValues;
+    const inspection = inspectNativeRuntimeInputs({
+        nativeNodes: input.nativeNodes,
+        capabilities: snapshot.capabilities,
+        inputValues,
+    });
+    if (inspection.status === 'invalid-input')
+        throw new Error(`nativeInputs.inputValues: ${inspection.issues.map((issue) => issue.message).join('; ')}`);
+    if (!inspection.slots.length)
+        return undefined;
+    return {
+        revision: configuration.revision,
+        inputValues: structuredClone(inputValues),
+        inputsReady: inspection.status === 'ready',
+        slots: inspection.slots,
+        nativeParameters: createNativeRuntimeParameterMaterializations({
+            nativeNodes: input.nativeNodes,
+            capabilities: snapshot.capabilities,
+        }),
+        capabilities: createRuntimeInputNativeCapabilities({
+            capabilities: snapshot.capabilities,
+            slots: inspection.slots,
+            revision: configuration.revision,
+            inputNodeName: TEMPLATE_PREFLIGHT_NAME,
+        }),
+    };
+}
+/** Preserve every original DAG edge; only explicit system roots precede the graph. */
+export function assembleNativeRuntimeInputs(input) {
+    const prepared = input.nativeInputs;
+    const inputSlots = prepared.slots.map((slot) => {
+        const fragment = input.nodes.find((node) => node.nodeId === slot.nodeId);
+        if (!fragment)
+            throw new Error(`Native input ${slot.id} has no compiled node ${slot.nodeId}`);
+        return {
+            ...slot,
+            editNodeId: TEMPLATE_INPUT_ID,
+            editNodeName: TEMPLATE_INPUT_NAME,
+            editParameter: 'jsCode',
+            materializerNodeName: fragment.entry.name,
+        };
+    });
+    const guide = [
+        '# Native 실행 입력 안내',
+        `입력 버전: ${prepared.revision}`,
+        '입력 설정 노드의 inputValues 객체에 아래 슬롯 ID와 실제 JSON 값을 넣으세요. 미입력 값에 임시 값을 넣지 마세요. 인증 비밀값은 n8n credential에 설정하세요.',
+        `입력 준비: ${prepared.inputsReady ? '완료' : '미입력 값 있음'}`,
+        ...(input.triggerConnections === 'detached'
+            ? [
+                '결손이 있어 Start 연결을 끊었습니다. 경고 영역을 해결한 뒤 연결을 검토하세요.',
+            ]
+            : []),
+        ...inputSlots.map((slot) => `\n## ${slot.nodeId}${slot.targetPointer}\n슬롯 ID: ${slot.id}\n입력 위치: ${slot.editNodeName}\n실행 직전 검사: ${slot.materializerNodeName}\n원래 형식:\n\`\`\`json\n${JSON.stringify(slot.schema, null, 2)}\n\`\`\``),
+        '입력 사전 검사는 모든 초기 native 값을 외부 호출 전에 확인합니다. 각 native 노드는 실행 직전에도 원래 전체 스키마와 버전을 검사합니다. 부분 실행이나 pinning은 검사를 우회할 수 있으므로 보안 경계로 사용하지 마세요.',
+    ].join('\n\n');
+    const system = createTemplateInputNodes({
+        revision: prepared.revision,
+        slots: prepared.slots,
+        inputValues: prepared.inputValues,
+        requests: [],
+        nativeParameters: prepared.nativeParameters,
+    });
+    const height = 160 +
+        guide
+            .split('\n')
+            .reduce((total, line) => total + Math.max(1, Math.ceil(line.length / 90)) * 24, 0);
+    const workflow = buildN8nWorkflow({
+        ...input,
+        nodes: [...system, ...input.nodes],
+        edges: [
+            {
+                from: TEMPLATE_INPUT_ID,
+                output: 'main',
+                to: TEMPLATE_PREFLIGHT_ID,
+                input: 'main',
+            },
+            ...input.starts.map((to) => ({
+                from: TEMPLATE_PREFLIGHT_ID,
+                output: 'main',
+                to,
+                input: 'main',
+            })),
+            ...input.edges,
+        ],
+        starts: [TEMPLATE_INPUT_ID],
+        annotations: [
+            ...input.annotations,
+            sticky(guide, [], {
+                id: TEMPLATE_GUIDE_ID,
+                name: 'Native 실행 입력 안내',
+                position: [0, -height - 100],
+                width: 1000,
+                height,
+                color: prepared.inputsReady ? 5 : 3,
+            }),
+        ],
+    });
+    return {
+        workflow,
+        nativeInputTemplate: {
+            revision: prepared.revision,
+            inputsReady: prepared.inputsReady,
+            inputSlots,
+            guide,
+        },
+    };
+}

package/dist/workflow/inputs/create-runtime-input-native-capabilities.d.ts

@@ -0,0 +1,4 @@
+import type { CreateRuntimeInputNativeCapabilitiesInput } from '../../types/native-runtime-parameters.js';
+import type { N8nNativeCapability } from '../../types/native-capability.js';
+/** Runtime ownership remains explicit; the original schema and metadata are never replaced. */
+export declare function createRuntimeInputNativeCapabilities(input: CreateRuntimeInputNativeCapabilitiesInput): N8nNativeCapability[];

package/dist/workflow/inputs/create-runtime-input-native-capabilities.js

@@ -0,0 +1,36 @@
+import { createNativeRuntimeParameterMaterializations, captureNativePlanningCapability, } from '@openapi-flow/core';
+/** Runtime ownership remains explicit; the original schema and metadata are never replaced. */
+export function createRuntimeInputNativeCapabilities(input) {
+    function wrap(capability) {
+        if (capability.supportsRuntimeParameters !== true)
+            return capability;
+        const bind = capability.bindMaterialContracts;
+        return {
+            ...capability,
+            ...captureNativePlanningCapability(capability),
+            bindMaterialContracts: bind === undefined
+                ? undefined
+                : (sources) => wrap(bind.call(capability, sources)),
+            compile(source) {
+                if (source.planned.runtimeParameters === undefined)
+                    return capability.compile(source);
+                const [materialization] = createNativeRuntimeParameterMaterializations({
+                    nativeNodes: [source.planned],
+                    capabilities: [capability],
+                });
+                if (!materialization ||
+                    materialization.inputs.some((source) => !input.slots.some((slot) => slot.id === source.id)))
+                    throw new Error(`node ${source.planned.id}: template has no declared native runtime input slot`);
+                return capability.compile({
+                    ...source,
+                    runtimeInput: {
+                        materialization,
+                        revision: input.revision,
+                        inputNodeName: input.inputNodeName,
+                    },
+                });
+            },
+        };
+    }
+    return input.capabilities.map(wrap);
+}

package/dist/workflow/resolve-n8n-native-materials.d.ts

@@ -0,0 +1,2 @@
+import type { ResolveN8nNativeMaterialsInput, ResolvedN8nNativeMaterials } from '../types/native-material-binding.js';
+export declare function resolveN8nNativeMaterials(input: ResolveN8nNativeMaterialsInput): ResolvedN8nNativeMaterials;

package/dist/workflow/resolve-n8n-native-materials.js

@@ -0,0 +1,16 @@
+import { resolveNativeMaterialSnapshot, NativeMaterialResolutionError, } from '@openapi-flow/core';
+export function resolveN8nNativeMaterials(input) {
+    const snapshot = resolveNativeMaterialSnapshot({
+        ...input,
+        deferredNodeIds: [],
+    });
+    if (snapshot.status !== 'ready')
+        throw new NativeMaterialResolutionError(snapshot.pending);
+    for (const capability of snapshot.capabilities)
+        if (!('compile' in capability) || typeof capability.compile !== 'function')
+            throw new Error(`Native material binding ${capability.name} did not retain its n8n compiler`);
+    return {
+        capabilities: snapshot.capabilities,
+        outputs: snapshot.outputs,
+    };
+}

package/dist/workflow/templates/compile-n8n-workflow-template.d.ts

@@ -0,0 +1,3 @@
+import type { CompileN8nWorkflowTemplateInput, N8nWorkflowTemplateResult } from '../../types/workflow-template.js';
+/** An explicit template boundary, never a false fully-resolved strict request. */
+export declare function compileN8nWorkflowTemplate(source: CompileN8nWorkflowTemplateInput): N8nWorkflowTemplateResult;