@interf/compiler 0.6.1 → 0.6.4

package/dist/packages/workflow-package/context-interface.d.ts

@@ -0,0 +1,96 @@
+import { z } from "zod";
+import { type WorkflowCompiledSchema, type WorkflowCompiledZone, type WorkflowZoneId } from "../compiler/lib/schema.js";
+export declare const CONTEXT_INTERFACE_FILE = "workflow.schema.json";
+export declare const ContextInterfaceSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"workflow-schema">;
+    version: z.ZodLiteral<1>;
+    target_type: z.ZodLiteral<"compiled">;
+    label: z.ZodString;
+    zones: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        role: z.ZodEnum<{
+            output: "output";
+            runtime: "runtime";
+            input: "input";
+            working: "working";
+        }>;
+        path: z.ZodString;
+        kind: z.ZodEnum<{
+            runtime: "runtime";
+            directory: "directory";
+            file: "file";
+        }>;
+        required: z.ZodBoolean;
+        owned_by: z.ZodArray<z.ZodString>;
+        description: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export declare const ContextInterfaceZoneSchema: z.ZodObject<{
+    id: z.ZodString;
+    role: z.ZodEnum<{
+        output: "output";
+        runtime: "runtime";
+        input: "input";
+        working: "working";
+    }>;
+    path: z.ZodString;
+    kind: z.ZodEnum<{
+        runtime: "runtime";
+        directory: "directory";
+        file: "file";
+    }>;
+    required: z.ZodBoolean;
+    owned_by: z.ZodArray<z.ZodString>;
+    description: z.ZodString;
+}, z.core.$strip>;
+export declare const ContextInterfaceZoneIdSchema: z.ZodString;
+export declare const ContextInterfaceZoneRoleSchema: z.ZodEnum<{
+    output: "output";
+    runtime: "runtime";
+    input: "input";
+    working: "working";
+}>;
+export declare const WorkflowInputSpecSchema: z.ZodObject<{
+    id: z.ZodString;
+    label: z.ZodString;
+    description: z.ZodString;
+    required: z.ZodDefault<z.ZodBoolean>;
+    examples: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strict>;
+export declare const WorkflowInputContractSchema: z.ZodArray<z.ZodObject<{
+    id: z.ZodString;
+    label: z.ZodString;
+    description: z.ZodString;
+    required: z.ZodDefault<z.ZodBoolean>;
+    examples: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strict>>;
+export type ContextInterface = WorkflowCompiledSchema;
+export type ContextInterfaceZone = WorkflowCompiledZone;
+export type ContextInterfaceZoneId = WorkflowZoneId;
+export type ContextInterfaceZoneRole = z.infer<typeof ContextInterfaceZoneRoleSchema>;
+export type WorkflowInputSpec = z.infer<typeof WorkflowInputSpecSchema>;
+export interface ContextInterfaceStageLike {
+    id: string;
+    writes: readonly string[];
+}
+export interface ContextInterfaceSummary {
+    inputZones: ContextInterfaceZone[];
+    workingZones: ContextInterfaceZone[];
+    outputZones: ContextInterfaceZone[];
+    runtimeZones: ContextInterfaceZone[];
+}
+export declare function contextInterfaceFilePath(rootPath: string): string;
+export declare function resolveContextInterfacePath(rootPath: string): string | null;
+export declare function contextInterfaceExists(rootPath: string): boolean;
+export declare function contextInterfaceRelativePath(): string;
+export declare function listContextInterfaceZones(contextInterface: ContextInterface): ContextInterfaceZone[];
+export declare function findContextInterfaceZone(contextInterface: ContextInterface, zoneId: ContextInterfaceZoneId): ContextInterfaceZone | null;
+export declare function contextInterfaceZoneAbsolutePath(compiledPath: string, zone: Pick<ContextInterfaceZone, "path">): string;
+export declare function contextInterfaceArtifactPath(zone: Pick<ContextInterfaceZone, "path" | "kind">): string;
+export declare function contextInterfaceArtifactPathsForZoneIds(contextInterface: ContextInterface, zoneIds: readonly ContextInterfaceZoneId[]): string[];
+export declare function summarizeContextInterface(contextInterface: ContextInterface): ContextInterfaceSummary;
+export declare function deriveWorkflowInputsFromContextInterface(contextInterface: ContextInterface | null | undefined): WorkflowInputSpec[];
+export declare function buildContextInterface(stages: ContextInterfaceStageLike[], label?: string): ContextInterface;
+export declare function writeContextInterfaceFile(rootPath: string, stages: ContextInterfaceStageLike[], label?: string): ContextInterface;
+export declare function writeContextInterface(rootPath: string, contextInterface: ContextInterface): ContextInterface;
+export declare function readContextInterface(rootPath: string): ContextInterface | null;

package/dist/packages/workflow-package/context-interface.js

@@ -0,0 +1,146 @@
+import { existsSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { z } from "zod";
+import { warnInterf } from "../shared/logger.js";
+import { readJsonFileUnchecked } from "../shared/parse.js";
+import { WorkflowCompiledSchemaSchema, WorkflowCompiledZoneSchema, WorkflowZoneIdSchema, WorkflowZoneRoleSchema, } from "../compiler/lib/schema.js";
+import { listBuiltinCompiledZoneSpecs, requiredCompiledZoneOwners, } from "./builtin-compiled-workflow.js";
+// Workflow packages define the context interface. The compiler persists the
+// same schema on disk, but higher layers should prefer this boundary when they
+// mean "the workflow-declared shape a compiled context must implement."
+export const CONTEXT_INTERFACE_FILE = "workflow.schema.json";
+export const ContextInterfaceSchema = WorkflowCompiledSchemaSchema;
+export const ContextInterfaceZoneSchema = WorkflowCompiledZoneSchema;
+export const ContextInterfaceZoneIdSchema = WorkflowZoneIdSchema;
+export const ContextInterfaceZoneRoleSchema = WorkflowZoneRoleSchema;
+// Package-owned input contract for authoring, review, and future Studio flows.
+// This does not change compiler execution semantics; it describes what data a
+// workflow expects to organize before the compiler materializes the context
+// interface on disk.
+export const WorkflowInputSpecSchema = z.object({
+    id: WorkflowZoneIdSchema,
+    label: z.string().min(1),
+    description: z.string().min(1),
+    required: z.boolean().default(false),
+    examples: z.array(z.string().min(1)).optional(),
+}).strict();
+export const WorkflowInputContractSchema = z.array(WorkflowInputSpecSchema);
+function normalizeContextInterface(contextInterface) {
+    return {
+        ...contextInterface,
+        kind: "workflow-schema",
+    };
+}
+function pushContextInterfaceZone(zones, zone) {
+    if (zones.some((existing) => existing.path === zone.path))
+        return;
+    zones.push(zone);
+}
+function titleCaseZoneId(zoneId) {
+    return zoneId
+        .split("-")
+        .filter(Boolean)
+        .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+        .join(" ");
+}
+export function contextInterfaceFilePath(rootPath) {
+    return join(rootPath, CONTEXT_INTERFACE_FILE);
+}
+export function resolveContextInterfacePath(rootPath) {
+    const path = contextInterfaceFilePath(rootPath);
+    return existsSync(path) ? path : null;
+}
+export function contextInterfaceExists(rootPath) {
+    return existsSync(contextInterfaceFilePath(rootPath));
+}
+export function contextInterfaceRelativePath() {
+    return `workflow/${CONTEXT_INTERFACE_FILE}`;
+}
+export function listContextInterfaceZones(contextInterface) {
+    return [...contextInterface.zones];
+}
+export function findContextInterfaceZone(contextInterface, zoneId) {
+    return contextInterface.zones.find((zone) => zone.id === zoneId) ?? null;
+}
+export function contextInterfaceZoneAbsolutePath(compiledPath, zone) {
+    return join(compiledPath, zone.path);
+}
+export function contextInterfaceArtifactPath(zone) {
+    if (zone.kind === "file")
+        return zone.path;
+    return zone.path.endsWith("/") ? zone.path : `${zone.path}/`;
+}
+export function contextInterfaceArtifactPathsForZoneIds(contextInterface, zoneIds) {
+    return zoneIds.map((zoneId) => {
+        const zone = findContextInterfaceZone(contextInterface, zoneId);
+        if (!zone) {
+            throw new Error(`Context interface is missing declared zone "${zoneId}".`);
+        }
+        return contextInterfaceArtifactPath(zone);
+    });
+}
+export function summarizeContextInterface(contextInterface) {
+    return {
+        inputZones: contextInterface.zones.filter((zone) => zone.role === "input"),
+        workingZones: contextInterface.zones.filter((zone) => zone.role === "working"),
+        outputZones: contextInterface.zones.filter((zone) => zone.role === "output"),
+        runtimeZones: contextInterface.zones.filter((zone) => zone.role === "runtime"),
+    };
+}
+export function deriveWorkflowInputsFromContextInterface(contextInterface) {
+    if (!contextInterface)
+        return [];
+    return contextInterface.zones
+        .filter((zone) => zone.role === "input")
+        .map((zone) => ({
+        id: zone.id,
+        label: titleCaseZoneId(zone.id),
+        description: zone.description,
+        required: zone.required,
+    }));
+}
+export function buildContextInterface(stages, label = "Workflow context interface") {
+    const zones = [];
+    for (const zone of listBuiltinCompiledZoneSpecs()) {
+        pushContextInterfaceZone(zones, {
+            id: zone.id,
+            role: zone.role,
+            path: zone.path,
+            kind: zone.kind,
+            required: zone.required,
+            owned_by: requiredCompiledZoneOwners(stages, zone.id),
+            description: zone.description,
+        });
+    }
+    return {
+        kind: "workflow-schema",
+        version: 1,
+        target_type: "compiled",
+        label,
+        zones,
+    };
+}
+export function writeContextInterfaceFile(rootPath, stages, label) {
+    const contextInterface = buildContextInterface(stages, label);
+    writeContextInterface(rootPath, contextInterface);
+    return contextInterface;
+}
+export function writeContextInterface(rootPath, contextInterface) {
+    const normalized = normalizeContextInterface(contextInterface);
+    writeFileSync(contextInterfaceFilePath(rootPath), `${JSON.stringify(normalized, null, 2)}\n`);
+    return normalized;
+}
+export function readContextInterface(rootPath) {
+    const path = contextInterfaceFilePath(rootPath);
+    if (!existsSync(path))
+        return null;
+    const raw = readJsonFileUnchecked(path, "workflow context interface");
+    if (raw === null)
+        return null;
+    const parsed = ContextInterfaceSchema.safeParse(raw);
+    if (!parsed.success) {
+        warnInterf(`Warning: failed to validate workflow context interface at ${path}: ${parsed.error.issues.map((issue) => issue.message).join("; ")}`);
+        return null;
+    }
+    return normalizeContextInterface(parsed.data);
+}

package/dist/packages/workflow-package/index.d.ts

@@ -0,0 +1,11 @@
+export * as builtinWorkflow from "./builtin-compiled-workflow.js";
+export * as contextInterface from "./context-interface.js";
+export * as localWorkflows from "./local-workflows.js";
+export * as packageWriters from "./interf-workflow-package.js";
+export * as workflowDefinitions from "./workflow-definitions.js";
+export * as workflowHelpers from "./workflow-helpers.js";
+export * as workflowStagePolicy from "./workflow-stage-policy.js";
+export * as workflowStageRunner from "./workflow-stage-runner.js";
+export * as workflowReviewPaths from "./workflow-review-paths.js";
+export * as packageRoot from "./lib/package-root.js";
+export { CONTEXT_INTERFACE_FILE, ContextInterfaceSchema, ContextInterfaceZoneSchema, ContextInterfaceZoneIdSchema, ContextInterfaceZoneRoleSchema, WorkflowInputSpecSchema, WorkflowInputContractSchema, contextInterfaceFilePath, resolveContextInterfacePath, contextInterfaceExists, contextInterfaceRelativePath, listContextInterfaceZones, findContextInterfaceZone, contextInterfaceZoneAbsolutePath, contextInterfaceArtifactPath, contextInterfaceArtifactPathsForZoneIds, buildContextInterface, writeContextInterfaceFile, writeContextInterface, readContextInterface, type ContextInterface, type ContextInterfaceZone, type ContextInterfaceZoneId, type ContextInterfaceZoneRole, type ContextInterfaceStageLike, type WorkflowInputSpec, type ContextInterfaceSummary, summarizeContextInterface, deriveWorkflowInputsFromContextInterface, } from "./context-interface.js";

package/dist/packages/workflow-package/index.js

@@ -0,0 +1,11 @@
+export * as builtinWorkflow from "./builtin-compiled-workflow.js";
+export * as contextInterface from "./context-interface.js";
+export * as localWorkflows from "./local-workflows.js";
+export * as packageWriters from "./interf-workflow-package.js";
+export * as workflowDefinitions from "./workflow-definitions.js";
+export * as workflowHelpers from "./workflow-helpers.js";
+export * as workflowStagePolicy from "./workflow-stage-policy.js";
+export * as workflowStageRunner from "./workflow-stage-runner.js";
+export * as workflowReviewPaths from "./workflow-review-paths.js";
+export * as packageRoot from "./lib/package-root.js";
+export { CONTEXT_INTERFACE_FILE, ContextInterfaceSchema, ContextInterfaceZoneSchema, ContextInterfaceZoneIdSchema, ContextInterfaceZoneRoleSchema, WorkflowInputSpecSchema, WorkflowInputContractSchema, contextInterfaceFilePath, resolveContextInterfacePath, contextInterfaceExists, contextInterfaceRelativePath, listContextInterfaceZones, findContextInterfaceZone, contextInterfaceZoneAbsolutePath, contextInterfaceArtifactPath, contextInterfaceArtifactPathsForZoneIds, buildContextInterface, writeContextInterfaceFile, writeContextInterface, readContextInterface, summarizeContextInterface, deriveWorkflowInputsFromContextInterface, } from "./context-interface.js";

package/dist/packages/workflow-package/interf-workflow-package.d.ts

@@ -0,0 +1,25 @@
+import { type WorkflowDefinition } from "./workflow-definitions.js";
+export declare function writeCompiledWorkflowPackage(compiledPath: string, workflow: WorkflowDefinition<string>): void;
+export declare function writeWorkflowPackageToDir(workflowDir: string, workflow: WorkflowDefinition<string>, options?: {
+    overwrite?: boolean;
+}): void;
+export declare function seedCompiledWorkflowPackage(options: {
+    compiledPath: string;
+    sourcePath: string;
+    workflowId: string;
+}): void;
+export declare function createLocalWorkflowPackageFromTemplate(options: {
+    sourcePath: string;
+    baseWorkflowId: string;
+    workflowId: string;
+    label: string;
+    hint: string;
+    stagePolicyNotes: Record<string, string[]>;
+}): string;
+export declare function seedLocalWorkflowPackageFromBase(options: {
+    sourcePath: string;
+    baseWorkflowId: string;
+    workflowId: string;
+    label: string;
+    hint: string;
+}): string;