@interf/compiler 0.5.1 → 0.6.3

package/dist/packages/workflow-package/local-workflows.js

@@ -0,0 +1,422 @@
+import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync, } from "node:fs";
+import { dirname, join, relative } from "node:path";
+import { z } from "zod";
+import { listFilesRecursive } from "../../lib/filesystem.js";
+import { warnInterf } from "../../lib/logger.js";
+import { readJsonFileUnchecked, readJsonFileWithSchema } from "../../lib/parse.js";
+import { isMarkdownFile } from "../../lib/util.js";
+import { WORKFLOW_SCHEMA_FILE as WORKFLOW_SCHEMA_FILENAME, workflowSchemaExists, writeWorkflowSchemaDocument, workflowSchemaFilePath, readWorkflowSchemaFile, } from "../compiler/compiled-schema.js";
+import { WorkflowCompilerApiSchema, RuntimeContractTypeSchema, RuntimeStageAcceptanceSchema, WorkflowPurposeSchema, WorkflowStageZoneAccessSchema, WorkflowIdPattern, } from "../compiler/lib/schema.js";
+import { listBuiltinCompiledZoneSpecs, } from "./builtin-compiled-workflow.js";
+import { PACKAGE_ROOT } from "./lib/package-root.js";
+import { mergeStagePolicyNotesForStages } from "./workflow-stage-policy.js";
+const LocalWorkflowStageDefinitionSchema = z.object({
+    id: z.string().regex(WorkflowIdPattern),
+    label: z.string().min(1),
+    contract_type: RuntimeContractTypeSchema,
+    skill_dir: z.string().regex(WorkflowIdPattern).optional(),
+    description: z.string().min(1).optional(),
+    reads: WorkflowStageZoneAccessSchema,
+    writes: WorkflowStageZoneAccessSchema,
+    acceptance: RuntimeStageAcceptanceSchema.optional(),
+});
+const LocalWorkflowDefinitionSchema = z.object({
+    id: z.string().regex(WorkflowIdPattern),
+    type: z.literal("compiled"),
+    compiler_api: WorkflowCompilerApiSchema.optional(),
+    purpose: WorkflowPurposeSchema.optional(),
+    label: z.string().min(1),
+    hint: z.string().min(1),
+    extends: z.string().regex(WorkflowIdPattern).optional(),
+    stages: z.array(LocalWorkflowStageDefinitionSchema).min(1).optional(),
+    stage_policy_notes: z.record(z.string(), z.array(z.string())).optional(),
+});
+function workflowRootPath(sourcePath) {
+    return join(sourcePath, "interf", "workflows");
+}
+function builtinWorkflowRootPath(workflowId) {
+    return join(PACKAGE_ROOT, "builtin-workflows", workflowId);
+}
+export function workflowDefinitionPath(sourcePath, id) {
+    return join(workflowRootPath(sourcePath), id);
+}
+function isSupportedWorkflowStarterDocPath(relativePath) {
+    if (relativePath === "README.md")
+        return true;
+    if (relativePath.startsWith("improve/"))
+        return true;
+    if (relativePath.startsWith("use/query/"))
+        return true;
+    if (relativePath.startsWith("compile/stages/"))
+        return true;
+    return false;
+}
+function collectStarterDocs(dirPath) {
+    return listFilesRecursive(dirPath, isMarkdownFile)
+        .map((filePath) => relative(dirPath, filePath).replaceAll("\\", "/"))
+        .filter((relativePath) => isSupportedWorkflowStarterDocPath(relativePath))
+        .map((relativePath) => ({
+        relativePath,
+        content: readFileSync(join(dirPath, relativePath), "utf8"),
+    }))
+        .sort((a, b) => a.relativePath.localeCompare(b.relativePath));
+}
+function workflowPackageCopyPaths(dirPath) {
+    return [
+        "workflow.json",
+        WORKFLOW_SCHEMA_FILENAME,
+        ...collectStarterDocs(dirPath).map((doc) => doc.relativePath),
+    ];
+}
+function copyRelativeFile(sourceRoot, targetRoot, relativePath) {
+    const sourcePath = join(sourceRoot, relativePath);
+    if (!existsSync(sourcePath))
+        return;
+    const targetPath = join(targetRoot, relativePath);
+    mkdirSync(dirname(targetPath), { recursive: true });
+    cpSync(sourcePath, targetPath, { force: true });
+}
+function copyWorkflowPackageFiles(sourceWorkflowPath, targetWorkflowPath) {
+    rmSync(targetWorkflowPath, { recursive: true, force: true });
+    mkdirSync(targetWorkflowPath, { recursive: true });
+    for (const relativePath of workflowPackageCopyPaths(sourceWorkflowPath)) {
+        copyRelativeFile(sourceWorkflowPath, targetWorkflowPath, relativePath);
+    }
+}
+export function loadWorkflowDefinitionFromDir(dirPath) {
+    const workflowPath = existsSync(join(dirPath, "workflow.json"))
+        ? join(dirPath, "workflow.json")
+        : null;
+    if (!workflowPath)
+        return null;
+    const definition = readJsonFileWithSchema(workflowPath, "local workflow definition", LocalWorkflowDefinitionSchema);
+    if (!definition)
+        return null;
+    const workflowSchema = readWorkflowSchemaFile(dirPath);
+    if (!workflowSchema)
+        return null;
+    if (definition.type !== "compiled") {
+        warnInterf(`Warning: local workflow definition at ${workflowPath} has unexpected type "${definition.type}".`);
+        return null;
+    }
+    return {
+        ...definition,
+        workflow_schema: workflowSchema,
+        starter_docs: collectStarterDocs(dirPath),
+        directoryPath: dirPath,
+        workflowPath,
+        workflowSchemaPath: workflowSchemaFilePath(dirPath),
+    };
+}
+export function listLocalWorkflowDefinitions(sourcePath) {
+    const root = workflowRootPath(sourcePath);
+    if (!existsSync(root))
+        return [];
+    return readdirSync(root)
+        .map((entry) => join(root, entry))
+        .filter((entryPath) => {
+        try {
+            return statSync(entryPath).isDirectory();
+        }
+        catch {
+            return false;
+        }
+    })
+        .map((entryPath) => loadWorkflowDefinitionFromDir(entryPath))
+        .filter((definition) => definition !== null)
+        .sort((a, b) => a.label.localeCompare(b.label));
+}
+export function loadLocalWorkflowDefinition(sourcePath, id) {
+    return loadWorkflowDefinitionFromDir(workflowDefinitionPath(sourcePath, id));
+}
+export function resolveWorkflowPackageSourcePath(sourcePath, workflowId) {
+    const builtinPath = builtinWorkflowRootPath(workflowId);
+    if (workflowId === "interf" && existsSync(join(builtinPath, "workflow.json")))
+        return builtinPath;
+    const localPath = workflowDefinitionPath(sourcePath, workflowId);
+    if (existsSync(join(localPath, "workflow.json")))
+        return localPath;
+    if (existsSync(join(builtinPath, "workflow.json")))
+        return builtinPath;
+    return null;
+}
+export function isWorkflowId(value) {
+    return WorkflowIdPattern.test(value);
+}
+function readWorkflowJsonObject(dirPath) {
+    const workflowPath = join(dirPath, "workflow.json");
+    const raw = readJsonFileUnchecked(workflowPath, "workflow package");
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+        throw new Error(`Workflow package at ${dirPath} is missing a valid workflow.json.`);
+    }
+    return { ...raw };
+}
+export function patchWorkflowPackageMetadata(dirPath, options = {}) {
+    const workflowPath = join(dirPath, "workflow.json");
+    const workflowJson = readWorkflowJsonObject(dirPath);
+    const normalizedStages = Array.isArray(workflowJson.stages) && workflowJson.stages.length > 0
+        ? workflowJson.stages
+        : null;
+    if (!normalizedStages) {
+        throw new Error(`Cannot patch workflow package at ${dirPath}: workflow.json must declare explicit stages before it can be copied or rewritten.`);
+    }
+    const nextWorkflowJson = {
+        ...workflowJson,
+        type: "compiled",
+        compiler_api: workflowJson.compiler_api ?? {
+            kind: "compiled",
+            version: 1,
+        },
+        stages: normalizedStages,
+        ...(options.id ? { id: options.id } : {}),
+        ...(options.label ? { label: options.label } : {}),
+        ...(options.hint ? { hint: options.hint } : {}),
+    };
+    delete nextWorkflowJson.extends;
+    const mergedStagePolicyNotes = mergeStagePolicyNotesForStages(normalizedStages, workflowJson.stage_policy_notes, options.stagePolicyNotes);
+    if (mergedStagePolicyNotes) {
+        nextWorkflowJson.stage_policy_notes = mergedStagePolicyNotes;
+    }
+    else {
+        delete nextWorkflowJson.stage_policy_notes;
+    }
+    writeFileSync(workflowPath, JSON.stringify(nextWorkflowJson, null, 2) + "\n");
+    const schemaLabel = `${String(nextWorkflowJson.label ?? workflowJson.label ?? options.id ?? "Workflow")} workflow schema`;
+    const existingSchema = readWorkflowSchemaFile(dirPath);
+    if (!existingSchema) {
+        throw new Error(`Cannot patch workflow package at ${dirPath}: missing ${WORKFLOW_SCHEMA_FILENAME}. Restore or reseed the package instead of regenerating a schema from workflow.json.`);
+    }
+    writeWorkflowSchemaDocument(dirPath, {
+        ...existingSchema,
+        label: schemaLabel,
+    });
+}
+function collectWorkflowPackageStructureIssues(dirPath, stages) {
+    const issues = [];
+    const workflowPath = join(dirPath, "workflow.json");
+    if (!existsSync(workflowPath))
+        issues.push("missing workflow.json");
+    if (!workflowSchemaExists(dirPath))
+        issues.push("missing workflow.schema.json");
+    if (!existsSync(join(dirPath, "README.md")))
+        issues.push("missing README.md");
+    if (!existsSync(join(dirPath, "improve", "SKILL.md")))
+        issues.push("missing improve/SKILL.md");
+    if (!existsSync(join(dirPath, "use", "query", "SKILL.md")))
+        issues.push("missing use/query/SKILL.md");
+    if (!stages)
+        return issues;
+    for (const stage of stages) {
+        const skillDir = typeof stage.skill_dir === "string" && stage.skill_dir.trim().length > 0
+            ? stage.skill_dir
+            : stage.id;
+        if (!existsSync(join(dirPath, "compile", "stages", skillDir, "SKILL.md"))) {
+            issues.push(`missing compile/stages/${skillDir}/SKILL.md`);
+        }
+    }
+    return issues;
+}
+function collectWorkflowStageSkillIssues(dirPath, stages) {
+    if (!stages)
+        return [];
+    const issues = [];
+    for (const stage of stages) {
+        const skillDir = typeof stage.skill_dir === "string" && stage.skill_dir.trim().length > 0
+            ? stage.skill_dir
+            : stage.id;
+        if (!existsSync(join(dirPath, "compile", "stages", skillDir, "SKILL.md"))) {
+            issues.push(`missing compile/stages/${skillDir}/SKILL.md`);
+        }
+    }
+    return issues;
+}
+export function describeWorkflowPackagePortability(dirPath) {
+    const issues = collectWorkflowPackageStructureIssues(dirPath, null);
+    if (issues.length > 0)
+        return issues;
+    let workflowJson;
+    try {
+        workflowJson = readWorkflowJsonObject(dirPath);
+    }
+    catch (error) {
+        issues.push(error instanceof Error ? error.message : String(error));
+        return issues;
+    }
+    const parsed = LocalWorkflowDefinitionSchema.safeParse(workflowJson);
+    if (!parsed.success) {
+        issues.push(...parsed.error.issues.map((issue) => issue.path.length > 0
+            ? `workflow.json ${issue.path.join(".")}: ${issue.message}`
+            : `workflow.json: ${issue.message}`));
+        return issues;
+    }
+    if (typeof parsed.data.extends === "string" && parsed.data.extends.trim().length > 0) {
+        issues.push("workflow.json uses legacy extends; portable workflow packages must be materialized standalone");
+    }
+    if (!parsed.data.stages || parsed.data.stages.length === 0) {
+        issues.push("workflow.json must declare explicit stages for a portable workflow package");
+        return issues;
+    }
+    return [
+        ...issues,
+        ...collectWorkflowStageSkillIssues(dirPath, parsed.data.stages ?? null),
+    ];
+}
+export function isPortableWorkflowPackage(dirPath) {
+    return describeWorkflowPackagePortability(dirPath).length === 0;
+}
+export function copyWorkflowPackageDirectory(sourceWorkflowPath, targetWorkflowPath) {
+    const portabilityIssues = describeWorkflowPackagePortability(sourceWorkflowPath);
+    if (portabilityIssues.length > 0) {
+        throw new Error(`Workflow package at ${sourceWorkflowPath} is not directly copyable: ${portabilityIssues.join("; ")}.`);
+    }
+    mkdirSync(dirname(targetWorkflowPath), { recursive: true });
+    copyWorkflowPackageFiles(sourceWorkflowPath, targetWorkflowPath);
+}
+export function validateWorkflowPackage(dirPath) {
+    const workflowPath = join(dirPath, "workflow.json");
+    if (!existsSync(workflowPath)) {
+        return {
+            ok: false,
+            summary: `No workflow.json found at ${dirPath}`,
+            errors: ["Missing workflow.json"],
+            counts: {},
+        };
+    }
+    const raw = readJsonFileUnchecked(workflowPath, "workflow package");
+    if (!raw) {
+        return {
+            ok: false,
+            summary: `Failed to parse workflow.json at ${workflowPath}`,
+            errors: ["Invalid JSON in workflow.json"],
+            counts: {},
+        };
+    }
+    const parsed = LocalWorkflowDefinitionSchema.safeParse(raw);
+    if (!parsed.success) {
+        const issues = parsed.error.issues.map((issue) => `${issue.path.join(".")}: ${issue.message}`);
+        return {
+            ok: false,
+            summary: `workflow.json failed validation: ${issues.length} issue(s)`,
+            errors: issues,
+            counts: {},
+        };
+    }
+    const def = parsed.data;
+    const errors = [];
+    if (typeof def.extends === "string" && def.extends.trim().length > 0) {
+        errors.push("workflow.json uses legacy extends. Portable workflow packages must be materialized as standalone packages.");
+    }
+    if (!def.stages || def.stages.length === 0) {
+        errors.push("workflow.json must declare explicit stages. Legacy inherited packages are not portable.");
+    }
+    if (def.stage_policy_notes && def.stages) {
+        const stageIds = new Set(def.stages.map((stage) => stage.id));
+        for (const stageId of Object.keys(def.stage_policy_notes)) {
+            if (!stageIds.has(stageId)) {
+                errors.push(`workflow.json stage_policy_notes references unknown stage "${stageId}".`);
+            }
+        }
+    }
+    for (const issue of collectWorkflowPackageStructureIssues(dirPath, def.stages ?? null)) {
+        const formatted = issue.startsWith("missing ")
+            ? `Missing ${issue.slice("missing ".length)}.`
+            : issue;
+        errors.push(formatted);
+    }
+    const workflowSchema = readWorkflowSchemaFile(dirPath);
+    if (!workflowSchema) {
+        errors.push("workflow.schema.json is missing or invalid.");
+    }
+    if (workflowSchema) {
+        const stages = def.stages ?? [];
+        const stageIds = new Set(stages.map((stage) => stage.id));
+        const seenPaths = new Map();
+        const seenZoneIds = new Set();
+        const zoneById = new Map(workflowSchema.zones.map((zone) => [zone.id, zone]));
+        const normalizedParts = (value) => value.replaceAll("\\", "/").split("/").filter(Boolean);
+        const hasOverlappingPath = (value, other) => {
+            const a = normalizedParts(value);
+            const b = normalizedParts(other);
+            const shorter = a.length <= b.length ? a : b;
+            const longer = a.length <= b.length ? b : a;
+            return shorter.every((part, index) => longer[index] === part);
+        };
+        for (const zone of workflowSchema.zones) {
+            if (seenZoneIds.has(zone.id)) {
+                errors.push(`workflow.schema.json repeats zone id "${zone.id}".`);
+            }
+            seenZoneIds.add(zone.id);
+            const existingPathOwner = seenPaths.get(zone.path);
+            if (existingPathOwner) {
+                errors.push(`workflow.schema.json repeats zone path "${zone.path}".`);
+            }
+            for (const [existingPath, existingZoneId] of seenPaths.entries()) {
+                if (existingPath === zone.path)
+                    continue;
+                if (hasOverlappingPath(zone.path, existingPath)) {
+                    errors.push(`workflow.schema.json zones "${zone.id}" and "${existingZoneId}" overlap on path "${zone.path}" / "${existingPath}".`);
+                }
+            }
+            seenPaths.set(zone.path, zone.id);
+            if ((zone.role === "input" || zone.role === "runtime") && zone.owned_by.length > 0) {
+                errors.push(`workflow.schema.json zone "${zone.id}" cannot declare owners because its role is "${zone.role}".`);
+            }
+            for (const owner of zone.owned_by) {
+                if (!stageIds.has(owner)) {
+                    errors.push(`workflow.schema.json references unknown stage "${owner}" for zone "${zone.path}".`);
+                }
+            }
+        }
+        for (const stage of stages) {
+            for (const zoneId of stage.reads) {
+                if (!zoneById.has(zoneId)) {
+                    errors.push(`Stage "${stage.id}" reads unknown zone "${zoneId}".`);
+                }
+            }
+            for (const zoneId of stage.writes) {
+                const zone = zoneById.get(zoneId);
+                if (!zone) {
+                    errors.push(`Stage "${stage.id}" writes unknown zone "${zoneId}".`);
+                    continue;
+                }
+                if (zone.role === "input" || zone.role === "runtime") {
+                    errors.push(`Stage "${stage.id}" writes zone "${zoneId}" but zones with role "${zone.role}" are engine-owned inputs, not writable stage outputs.`);
+                }
+                if (!zone.owned_by.includes(stage.id)) {
+                    errors.push(`Stage "${stage.id}" writes zone "${zoneId}" but that zone is not owned by the stage in workflow.schema.json.`);
+                }
+            }
+        }
+        for (const requiredZone of listBuiltinCompiledZoneSpecs().filter((zone) => zone.id === "raw" || zone.id === "runtime")) {
+            const match = zoneById.get(requiredZone.id);
+            if (!match) {
+                errors.push(`workflow.schema.json is missing required zone "${requiredZone.id}".`);
+                continue;
+            }
+            if (match.kind !== requiredZone.kind) {
+                errors.push(`workflow.schema.json zone "${requiredZone.id}" should be kind "${requiredZone.kind}".`);
+            }
+            if (match.role !== requiredZone.role) {
+                errors.push(`workflow.schema.json zone "${requiredZone.id}" should have role "${requiredZone.role}".`);
+            }
+        }
+    }
+    const stageDirs = existsSync(join(dirPath, "compile", "stages"))
+        ? listFilesRecursive(join(dirPath, "compile", "stages"), (filePath) => basename(filePath) === "SKILL.md")
+        : [];
+    const counts = {
+        starter_docs: collectStarterDocs(dirPath).length,
+        compile_stage_docs: stageDirs.length,
+        compiled_zones: workflowSchema?.zones.length ?? 0,
+        workflow_zones: workflowSchema?.zones.length ?? 0,
+    };
+    return {
+        ok: errors.length === 0,
+        summary: errors.length === 0 ? "Workflow package is valid." : `Workflow package has ${errors.length} issue(s).`,
+        errors,
+        counts,
+    };
+}
+function basename(filePath) {
+    return filePath.split(/[\\/]/).pop() ?? filePath;
+}

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

@@ -0,0 +1,78 @@
+import type { RuntimeContractType, RuntimeStageAcceptance, WorkflowCompilerApi, WorkflowCompiledSchema, WorkflowId, WorkflowZoneId } from "../compiler/lib/schema.js";
+export interface WorkflowStarterDoc {
+    relativePath: string;
+    content: string;
+}
+export interface WorkflowStageDefinition {
+    id: string;
+    label: string;
+    description: string;
+    contractType: RuntimeContractType;
+    skillDir: string;
+    reads: WorkflowZoneId[];
+    writes: WorkflowZoneId[];
+    acceptance?: RuntimeStageAcceptance;
+}
+export interface WorkflowDefinition<TId extends string> {
+    id: TId;
+    compilerApi?: WorkflowCompilerApi;
+    purpose?: {
+        label: string;
+        taskHint: string;
+    };
+    label: string;
+    hint: string;
+    recommended?: boolean;
+    schema?: WorkflowCompiledSchema;
+    stages: WorkflowStageDefinition[];
+    stagePolicyNotes?: Record<string, string[]>;
+    starterDocs?: WorkflowStarterDoc[];
+    scope?: "builtin" | "local";
+}
+export type CompiledWorkflowId = string;
+export declare function standaloneWorkflowDefinitionFromLocalPackage(local: {
+    id: string;
+    compiler_api?: WorkflowCompilerApi;
+    purpose?: {
+        label: string;
+        task_hint: string;
+    };
+    label: string;
+    hint: string;
+    stages?: Array<{
+        id: string;
+        label: string;
+        description?: string;
+        contract_type: RuntimeContractType;
+        skill_dir?: string;
+        reads: WorkflowZoneId[];
+        writes: WorkflowZoneId[];
+        acceptance?: RuntimeStageAcceptance;
+    }>;
+    stage_policy_notes?: Record<string, string[]>;
+    workflow_schema?: WorkflowCompiledSchema;
+    starter_docs: WorkflowStarterDoc[];
+}): WorkflowDefinition<string>;
+export declare function listCompiledWorkflowChoices(sourcePath?: string): WorkflowDefinition<string>[];
+export declare function getCompiledWorkflow(workflowId: CompiledWorkflowId, options?: {
+    sourcePath?: string;
+}): WorkflowDefinition<string>;
+export declare function getActiveCompiledWorkflow(compiledPath: string, fallbackWorkflowId: CompiledWorkflowId): WorkflowDefinition<string>;
+export declare function resolveCompiledWorkflowId(value: unknown): CompiledWorkflowId | null;
+export declare function resolveCompiledWorkflowFromConfig(config: unknown): CompiledWorkflowId | null;
+export declare function resolveRequiredCompiledWorkflowFromConfig(config: unknown, label?: string): CompiledWorkflowId;
+export declare function formatCompiledWorkflowStageStep(workflowId: CompiledWorkflowId, stage: string, options?: {
+    sourcePath?: string;
+}): string;
+export declare function getWorkflowStageDefinition(workflowId: WorkflowId, stage: string, sourcePath?: string): WorkflowStageDefinition | null;
+export declare function getWorkflowStagePosition(workflowId: WorkflowId, stage: string, sourcePath?: string): {
+    stageIndex: number;
+    stageTotal: number;
+    stages: string[];
+} | null;
+export declare function getWorkflowStages(workflowId: WorkflowId, sourcePath?: string): string[];
+export declare function getActiveCompiledStages(compiledPath: string, fallbackWorkflowId: WorkflowId): string[];
+export declare function getWorkflowStagePolicyNotes(workflowId: WorkflowId, stage: string, sourcePath?: string): string[];
+export declare function getActiveCompiledStagePolicyNotes(compiledPath: string, fallbackWorkflowId: WorkflowId, stage: string): string[];
+export declare function resolveActiveCompiledStageAcceptance(compiledPath: string, fallbackWorkflowId: WorkflowId, stage: string): WorkflowStageDefinition["acceptance"] | undefined;
+export declare function formatActiveCompiledWorkflowStageStep(compiledPath: string, fallbackWorkflowId: CompiledWorkflowId, stage: string): string;