@interf/compiler 0.7.3 → 0.9.3

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

@@ -1,389 +0,0 @@
-import { existsSync, mkdirSync, writeFileSync } from "node:fs";
-import { dirname, join } from "node:path";
-import { renderCompiledQuerySkill } from "../agents/lib/shells.js";
-import { copyWorkflowPackageDirectory, isPortableWorkflowPackage, patchWorkflowPackageMetadata, resolveWorkflowPackageSourcePath, workflowDefinitionPath, } from "./local-workflows.js";
-import { getCompiledWorkflow, } from "./workflow-definitions.js";
-import { CONTEXT_INTERFACE_FILE, deriveWorkflowInputsFromContextInterface, summarizeContextInterface, writeContextInterface, writeContextInterfaceFile, } from "./context-interface.js";
-import { workflowPackagePathForCompiled } from "../compiler/compiled-paths.js";
-import { mergeStagePolicyNotesForStages } from "./workflow-stage-policy.js";
-function workflowPackagePath(dirPath) {
-    return workflowPackagePathForCompiled(dirPath);
-}
-function writeWorkflowStarterDocs(dirPath, docs, options) {
-    for (const doc of docs ?? []) {
-        const targetPath = join(dirPath, doc.relativePath);
-        if (!options.overwrite && existsSync(targetPath))
-            continue;
-        mkdirSync(dirname(targetPath), { recursive: true });
-        writeFileSync(targetPath, doc.content);
-    }
-}
-function writeWorkflowPackageJson(rootPath, workflow, options) {
-    const targetPath = join(rootPath, "workflow.json");
-    if (!options.overwrite && existsSync(targetPath))
-        return;
-    const inputs = workflow.inputs?.length
-        ? workflow.inputs
-        : deriveWorkflowInputsFromContextInterface(workflow.contextInterface ?? workflow.schema);
-    writeFileSync(targetPath, `${JSON.stringify({
-        id: workflow.id,
-        type: "compiled",
-        compiler_api: workflow.compilerApi ?? {
-            kind: "compiled",
-            version: 1,
-        },
-        ...(workflow.purpose
-            ? {
-                purpose: {
-                    label: workflow.purpose.label,
-                    task_hint: workflow.purpose.taskHint,
-                },
-            }
-            : {}),
-        ...(inputs.length > 0 ? { inputs } : {}),
-        label: workflow.label,
-        hint: workflow.hint,
-        stages: workflow.stages.map((stage) => ({
-            id: stage.id,
-            label: stage.label,
-            description: stage.description,
-            contract_type: stage.contractType,
-            skill_dir: stage.skillDir,
-            reads: stage.reads,
-            writes: stage.writes,
-            ...(stage.acceptance ? { acceptance: stage.acceptance } : {}),
-        })),
-        ...(workflow.stagePolicyNotes ? { stage_policy_notes: workflow.stagePolicyNotes } : {}),
-    }, null, 2)}\n`);
-}
-function renderWorkflowReadme(workflow) {
-    const contextInterface = workflow.contextInterface ?? workflow.schema ?? null;
-    const stageLines = workflow.stages
-        .map((stage) => `- \`${stage.id}\` — ${stage.description} (${stage.contractType}; reads: ${stage.reads.join(", ")}; writes: ${stage.writes.join(", ")})`)
-        .join("\n");
-    const interfaceSummary = contextInterface
-        ? summarizeContextInterface(contextInterface)
-        : null;
-    const contextInterfaceLines = contextInterface?.zones
-        ? contextInterface.zones
-            .map((zone) => `- \`${zone.id}\` — ${zone.role} ${zone.kind} at \`${zone.path}\`: ${zone.description}`)
-            .join("\n")
-        : null;
-    const inputs = workflow.inputs?.length
-        ? workflow.inputs
-        : deriveWorkflowInputsFromContextInterface(contextInterface);
-    const inputLines = inputs.length > 0
-        ? inputs
-            .map((input) => `- \`${input.id}\` — ${input.label}: ${input.description}${input.required ? " (required)" : ""}${input.examples?.length ? ` Example inputs: ${input.examples.join("; ")}` : ""}`)
-            .join("\n")
-        : null;
-    const contextInterfaceSummaryLines = interfaceSummary
-        ? [
-            `- Input zones: ${interfaceSummary.inputZones.length > 0 ? interfaceSummary.inputZones.map((zone) => `\`${zone.id}\``).join(", ") : "none"}`,
-            `- Working zones: ${interfaceSummary.workingZones.length > 0 ? interfaceSummary.workingZones.map((zone) => `\`${zone.id}\``).join(", ") : "none"}`,
-            `- Output zones: ${interfaceSummary.outputZones.length > 0 ? interfaceSummary.outputZones.map((zone) => `\`${zone.id}\``).join(", ") : "none"}`,
-            `- Runtime zones: ${interfaceSummary.runtimeZones.length > 0 ? interfaceSummary.runtimeZones.map((zone) => `\`${zone.id}\``).join(", ") : "none"}`,
-        ].join("\n")
-        : null;
-    return [
-        `# ${workflow.label}`,
-        "",
-        workflow.hint,
-        ...(workflow.purpose
-            ? [
-                "",
-                "## Purpose",
-                "",
-                `- ${workflow.purpose.label}`,
-                `- ${workflow.purpose.taskHint}`,
-            ]
-            : []),
-        ...(inputLines
-            ? [
-                "",
-                "## Inputs",
-                "",
-                inputLines,
-            ]
-            : []),
-        ...(contextInterfaceLines
-            ? [
-                "",
-                "## Context Interface",
-                "",
-                ...(contextInterfaceSummaryLines
-                    ? [
-                        contextInterfaceSummaryLines,
-                        "",
-                    ]
-                    : []),
-                "Zone map:",
-                "",
-                contextInterfaceLines,
-            ]
-            : []),
-        "",
-        "## Package",
-        "",
-        "- `workflow.json` = stage graph, compiler API target, and compile contract mapping",
-        "- `workflow.schema.json` = deterministic context interface for the workflow package",
-        "- `improve/`, `compile/stages/`, and `use/query/` = human-readable authoring docs",
-        "- Portable workflow packages are standalone: explicit stages, schema, and docs live together in this folder",
-        "- Interf projects native agent shells from these docs for query use, stage execution, and workflow-improvement loops",
-        "",
-        "## Stages",
-        "",
-        stageLines,
-        "",
-        "Interf runs the local copy of this package directly from `.interf/workflow/` inside each compiled context.",
-        "",
-    ].join("\n");
-}
-function renderDerivedWorkflowReadme(options) {
-    return [
-        `# ${options.label}`,
-        "",
-        options.hint,
-        "",
-        `This workflow package was copied from \`${options.baseWorkflowId}\` and materialized as a standalone package for this kind of work.`,
-        "",
-        "Interf runs the local copy of this package directly. Keep purpose, inputs, context interface, and stage docs self-contained in this folder instead of relying on runtime inheritance or fallback.",
-        "",
-        "## Emphasis",
-        "",
-        ...(options.emphasis.length > 0
-            ? options.emphasis.map((entry) => `- ${entry.stageId} (${entry.label}): ${entry.notes.join("; ")}`)
-            : ["- No stage-specific emphasis was added yet."]),
-        "",
-    ].join("\n");
-}
-function renderSeedWorkflowReadme(options) {
-    return [
-        `# ${options.label}`,
-        "",
-        options.hint,
-        "",
-        `This workflow package was seeded from \`${options.baseWorkflowId}\` as a standalone local draft.`,
-        "",
-        "Interf runs the local copy of this package directly. Refine purpose, inputs, context interface, and stage instructions in this folder instead of relying on inheritance or runtime fallback.",
-        "",
-    ].join("\n");
-}
-function renderImproveSkill(workflow) {
-    return [
-        "# Workflow Improvement",
-        "",
-        `Workflow: ${workflow.id}`,
-        "",
-        "This file is the editable authoring source for Interf's generated native workflow-improver shell.",
-        "The improver edits this local package directly.",
-        "",
-        "Default loop:",
-        "1. Read the loop context first.",
-        "2. Review preserved stage shells, runtime logs, and saved test runs from failed attempts.",
-        "3. Edit only the local workflow package for this compiled context to create a better workflow variation for this kind of work.",
-        `4. Keep purpose, inputs, \`workflow.json\`, \`${CONTEXT_INTERFACE_FILE}\`, and any changed stage docs aligned.`,
-        "",
-        "Guardrails:",
-        "- do not edit checks, test specs, or raw files",
-        "- do not hardcode expected answers into workflow docs",
-        "- keep this package standalone; do not add or rely on runtime `extends` or fallback behavior",
-        "- keep the workflow stack coherent: purpose, inputs, context interface, and stages should describe the same job",
-        "- prefer small, defensible workflow changes over random churn",
-        "",
-    ].join("\n");
-}
-function renderStageSkill(workflow, stage) {
-    const notes = workflow.stagePolicyNotes?.[stage.id] ?? [];
-    const acceptanceKeys = stage.acceptance ? Object.keys(stage.acceptance) : [];
-    const abstractRules = stage.contractType === "compiled-file-evidence"
-        ? [
-            "- Valid abstract forms for deterministic validation are:",
-            '  - frontmatter key `"abstract"` with a real sentence, or',
-            "  - a markdown heading `## Abstract` followed by at least one sentence",
-            "- A bare `Abstract` label without markdown heading syntax does not count.",
-        ]
-        : [];
-    return [
-        `# ${stage.label}`,
-        "",
-        stage.description,
-        "",
-        "## Stage Contract",
-        "",
-        `- Contract type: \`${stage.contractType}\``,
-        `- Reads zones: ${stage.reads.map((zoneId) => `\`${zoneId}\``).join(", ")}`,
-        `- Writes zones: ${stage.writes.map((zoneId) => `\`${zoneId}\``).join(", ")}`,
-        "",
-        "## Requirements",
-        "",
-        "- Treat `workflow.json` and `workflow.schema.json` as the authoritative package contract for this stage.",
-        "- Read only from the declared input zones unless this package explicitly documents a broader method.",
-        "- Write only inside the declared output zones for this stage. Do not invent undeclared zones or implicit outputs.",
-        "- Keep stage instructions, zone ownership, and workflow-level acceptance aligned when you change this stage.",
-        "- Treat runtime files as proof and execution state, not as the source of truth for workflow behavior.",
-        "- Prefer direct file-reading and search tools over shell commands for routine file inspection.",
-        ...abstractRules,
-        "",
-        ...(acceptanceKeys.length > 0
-            ? [
-                "## Declarative Acceptance",
-                "",
-                ...acceptanceKeys.map((key) => `- \`${key}\``),
-                "",
-            ]
-            : []),
-        ...(notes.length > 0
-            ? [
-                "## Notes",
-                "",
-                ...notes.map((note) => `- ${note}`),
-                "",
-            ]
-            : []),
-    ].join("\n");
-}
-export function writeCompiledWorkflowPackage(compiledPath, workflow) {
-    writeWorkflowPackageToDir(workflowPackagePath(compiledPath), workflow);
-}
-export function writeWorkflowPackageToDir(workflowDir, workflow, options = {}) {
-    const overwrite = options.overwrite ?? true;
-    mkdirSync(join(workflowDir, "improve"), { recursive: true });
-    mkdirSync(join(workflowDir, "use", "query"), { recursive: true });
-    mkdirSync(join(workflowDir, "compile", "stages"), { recursive: true });
-    for (const stage of workflow.stages) {
-        mkdirSync(join(workflowDir, "compile", "stages", stage.skillDir), { recursive: true });
-    }
-    writeWorkflowPackageJson(workflowDir, workflow, { overwrite });
-    if (overwrite || !existsSync(join(workflowDir, CONTEXT_INTERFACE_FILE))) {
-        const contextInterface = workflow.contextInterface ?? workflow.schema;
-        if (contextInterface) {
-            writeContextInterface(workflowDir, {
-                ...contextInterface,
-                label: contextInterface.label || `${workflow.label} workflow schema`,
-            });
-        }
-        else {
-            writeContextInterfaceFile(workflowDir, workflow.stages, `${workflow.label} workflow schema`);
-        }
-    }
-    if (overwrite || !existsSync(join(workflowDir, "README.md"))) {
-        writeFileSync(join(workflowDir, "README.md"), renderWorkflowReadme(workflow));
-    }
-    if (overwrite || !existsSync(join(workflowDir, "improve", "SKILL.md"))) {
-        writeFileSync(join(workflowDir, "improve", "SKILL.md"), renderImproveSkill(workflow));
-    }
-    if (overwrite || !existsSync(join(workflowDir, "use", "query", "SKILL.md"))) {
-        writeFileSync(join(workflowDir, "use", "query", "SKILL.md"), renderCompiledQuerySkill());
-    }
-    for (const stage of workflow.stages) {
-        const targetPath = join(workflowDir, "compile", "stages", stage.skillDir, "SKILL.md");
-        if (overwrite || !existsSync(targetPath)) {
-            writeFileSync(targetPath, renderStageSkill(workflow, stage));
-        }
-    }
-    writeWorkflowStarterDocs(workflowDir, workflow.starterDocs, { overwrite });
-}
-export function seedCompiledWorkflowPackage(options) {
-    const resolvedWorkflow = getCompiledWorkflow(options.workflowId, {
-        sourcePath: options.sourcePath,
-    });
-    const sourceWorkflowPath = resolveWorkflowPackageSourcePath(options.sourcePath, resolvedWorkflow.id);
-    if (sourceWorkflowPath && isPortableWorkflowPackage(sourceWorkflowPath)) {
-        // Portable seed packages can be copied directly because compile runs the
-        // local package folder without any source-root fallback.
-        copyWorkflowPackageDirectory(sourceWorkflowPath, workflowPackagePath(options.compiledPath));
-        patchWorkflowPackageMetadata(workflowPackagePath(options.compiledPath), {
-            id: resolvedWorkflow.id,
-            inputs: resolvedWorkflow.inputs,
-            label: resolvedWorkflow.label,
-            hint: resolvedWorkflow.hint,
-            stagePolicyNotes: resolvedWorkflow.stagePolicyNotes,
-        });
-        if (resolvedWorkflow.scope === "builtin") {
-            writeFileSync(join(workflowPackagePath(options.compiledPath), "README.md"), renderWorkflowReadme(resolvedWorkflow));
-        }
-        return;
-    }
-    // Legacy or partially-defined seed packages are resolved once and
-    // materialized into a standalone local package.
-    writeCompiledWorkflowPackage(options.compiledPath, resolvedWorkflow);
-}
-export function createLocalWorkflowPackageFromTemplate(options) {
-    const targetPath = seedLocalWorkflowPackageFromBase({
-        sourcePath: options.sourcePath,
-        baseWorkflowId: options.baseWorkflowId,
-        workflowId: options.workflowId,
-        label: options.label,
-        hint: options.hint,
-    });
-    const baseWorkflow = getCompiledWorkflow(options.baseWorkflowId, {
-        sourcePath: options.sourcePath,
-    });
-    const stagePolicyNotes = mergeStagePolicyNotesForStages(baseWorkflow.stages, baseWorkflow.stagePolicyNotes, options.stagePolicyNotes);
-    patchWorkflowPackageMetadata(targetPath, {
-        id: options.workflowId,
-        label: options.label,
-        hint: options.hint,
-        stagePolicyNotes,
-    });
-    writeFileSync(join(targetPath, "README.md"), renderDerivedWorkflowReadme({
-        label: options.label,
-        hint: options.hint,
-        baseWorkflowId: options.baseWorkflowId,
-        emphasis: baseWorkflow.stages
-            .map((stage) => ({
-            stageId: stage.id,
-            label: stage.label,
-            notes: stagePolicyNotes?.[stage.id] ?? [],
-        }))
-            .filter((entry) => entry.notes.length > 0),
-    }));
-    return targetPath;
-}
-export function seedLocalWorkflowPackageFromBase(options) {
-    const baseWorkflow = getCompiledWorkflow(options.baseWorkflowId, {
-        sourcePath: options.sourcePath,
-    });
-    const sourceWorkflowPath = resolveWorkflowPackageSourcePath(options.sourcePath, options.baseWorkflowId);
-    const targetPath = workflowDefinitionPath(options.sourcePath, options.workflowId);
-    if (sourceWorkflowPath && isPortableWorkflowPackage(sourceWorkflowPath)) {
-        // Copy directly when the base package is already portable and standalone.
-        copyWorkflowPackageDirectory(sourceWorkflowPath, targetPath);
-        patchWorkflowPackageMetadata(targetPath, {
-            id: options.workflowId,
-            inputs: baseWorkflow.inputs,
-            label: options.label,
-            hint: options.hint,
-        });
-        writeFileSync(join(targetPath, "README.md"), renderSeedWorkflowReadme({
-            label: options.label,
-            hint: options.hint,
-            baseWorkflowId: options.baseWorkflowId,
-        }));
-        return targetPath;
-    }
-    // Legacy or inherited base packages are materialized immediately so the new
-    // local workflow package is standalone from its first write.
-    const localWorkflow = {
-        ...baseWorkflow,
-        id: options.workflowId,
-        label: options.label,
-        hint: options.hint,
-        recommended: false,
-        scope: "local",
-        starterDocs: [
-            {
-                relativePath: "README.md",
-                content: renderSeedWorkflowReadme({
-                    label: options.label,
-                    hint: options.hint,
-                    baseWorkflowId: options.baseWorkflowId,
-                }),
-            },
-            ...(baseWorkflow.starterDocs ?? []).filter((doc) => doc.relativePath !== "README.md"),
-        ],
-    };
-    writeWorkflowPackageToDir(targetPath, localWorkflow);
-    return targetPath;
-}

package/dist/packages/workflow-package/local-workflows.d.ts

@@ -1,64 +0,0 @@
-import { z } from "zod";
-import { WorkflowCompilerApiSchema, RuntimeContractTypeSchema, RuntimeStageAcceptanceSchema, WorkflowPurposeSchema, WorkflowStageZoneAccessSchema } from "../compiler/lib/schema.js";
-import { WorkflowInputSpecSchema, type ContextInterface, type WorkflowInputSpec } from "./context-interface.js";
-export interface LocalWorkflowStarterDoc {
-    relativePath: string;
-    content: string;
-}
-export interface LocalWorkflowStageDefinition {
-    id: string;
-    label: string;
-    contract_type: z.infer<typeof RuntimeContractTypeSchema>;
-    skill_dir?: string;
-    description?: string;
-    reads: z.infer<typeof WorkflowStageZoneAccessSchema>;
-    writes: z.infer<typeof WorkflowStageZoneAccessSchema>;
-    acceptance?: z.infer<typeof RuntimeStageAcceptanceSchema>;
-}
-export interface LocalWorkflowDefinition {
-    id: string;
-    type: "compiled";
-    compiler_api?: z.infer<typeof WorkflowCompilerApiSchema>;
-    purpose?: z.infer<typeof WorkflowPurposeSchema>;
-    inputs?: Array<z.infer<typeof WorkflowInputSpecSchema>>;
-    label: string;
-    hint: string;
-    extends?: string;
-    stages?: LocalWorkflowStageDefinition[];
-    stage_policy_notes?: Record<string, string[]>;
-    workflow_schema: ContextInterface;
-    starter_docs: LocalWorkflowStarterDoc[];
-    directoryPath: string;
-    workflowPath: string;
-    workflowSchemaPath: string;
-}
-export declare function workflowDefinitionPath(sourcePath: string, id: string): string;
-export declare function loadWorkflowDefinitionFromDir(dirPath: string): LocalWorkflowDefinition | null;
-export declare function listLocalWorkflowDefinitions(sourcePath: string): LocalWorkflowDefinition[];
-export declare function loadLocalWorkflowDefinition(sourcePath: string, id: string): LocalWorkflowDefinition | null;
-export declare function resolveWorkflowPackageSourcePath(sourcePath: string, workflowId: string): string | null;
-export declare function seedLocalDefaultWorkflow(options: {
-    sourcePath: string;
-}): {
-    workflowId: string;
-    targetPath: string;
-    alreadyExisted: boolean;
-};
-export declare function isWorkflowId(value: string): boolean;
-export declare function patchWorkflowPackageMetadata(dirPath: string, options?: {
-    id?: string;
-    inputs?: WorkflowInputSpec[];
-    label?: string;
-    hint?: string;
-    stagePolicyNotes?: Record<string, string[]>;
-}): void;
-export declare function describeWorkflowPackagePortability(dirPath: string): string[];
-export declare function isPortableWorkflowPackage(dirPath: string): boolean;
-export declare function copyWorkflowPackageDirectory(sourceWorkflowPath: string, targetWorkflowPath: string): void;
-export interface WorkflowValidationResult {
-    ok: boolean;
-    summary: string;
-    errors: string[];
-    counts: Record<string, number>;
-}
-export declare function validateWorkflowPackage(dirPath: string): WorkflowValidationResult;