@interf/compiler 0.5.1 → 0.6.3

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

@@ -0,0 +1,9 @@
+export * as builtinWorkflow from "./builtin-compiled-workflow.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";

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

@@ -0,0 +1,9 @@
+export * as builtinWorkflow from "./builtin-compiled-workflow.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";

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;

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

@@ -0,0 +1,342 @@
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { renderCompiledQuerySkill } from "../agents/lib/shells.js";
+import { WORKFLOW_SCHEMA_FILE, writeWorkflowSchemaDocument, writeWorkflowSchemaFile, } from "../compiler/compiled-schema.js";
+import { copyWorkflowPackageDirectory, isPortableWorkflowPackage, patchWorkflowPackageMetadata, resolveWorkflowPackageSourcePath, workflowDefinitionPath, } from "./local-workflows.js";
+import { getCompiledWorkflow, } from "./workflow-definitions.js";
+import { workflowPackagePathForCompiled } from "../project-model/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;
+    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,
+                },
+            }
+            : {}),
+        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 stageLines = workflow.stages
+        .map((stage) => `- \`${stage.id}\` — ${stage.description} (${stage.contractType}; reads: ${stage.reads.join(", ")}; writes: ${stage.writes.join(", ")})`)
+        .join("\n");
+    const zoneLines = workflow.schema?.zones
+        ? workflow.schema.zones
+            .map((zone) => `- \`${zone.id}\` — ${zone.role} ${zone.kind} at \`${zone.path}\``)
+            .join("\n")
+        : null;
+    return [
+        `# ${workflow.label}`,
+        "",
+        workflow.hint,
+        ...(workflow.purpose
+            ? [
+                "",
+                "## Purpose",
+                "",
+                `- ${workflow.purpose.label}`,
+                `- ${workflow.purpose.taskHint}`,
+            ]
+            : []),
+        "",
+        "## Package",
+        "",
+        "- `workflow.json` = stage graph, compiler API target, and compile contract mapping",
+        "- `workflow.schema.json` = deterministic zone contract 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",
+        ...(zoneLines
+            ? [
+                "",
+                "## Zones",
+                "",
+                zoneLines,
+            ]
+            : []),
+        "",
+        "## 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 task.`,
+        "",
+        "Interf runs the local copy of this package directly. Keep changes in this folder self-contained 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 the workflow docs, stage instructions, and zone contract 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 task.",
+        `4. Keep \`workflow.json\`, \`${WORKFLOW_SCHEMA_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",
+        "- 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, WORKFLOW_SCHEMA_FILE))) {
+        if (workflow.schema) {
+            writeWorkflowSchemaDocument(workflowDir, {
+                ...workflow.schema,
+                label: workflow.schema.label || `${workflow.label} workflow schema`,
+            });
+        }
+        else {
+            writeWorkflowSchemaFile(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,
+            label: resolvedWorkflow.label,
+            hint: resolvedWorkflow.hint,
+            stagePolicyNotes: resolvedWorkflow.stagePolicyNotes,
+        });
+        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 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,
+            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 baseWorkflow = getCompiledWorkflow(options.baseWorkflowId, {
+        sourcePath: options.sourcePath,
+    });
+    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/{lib/config.d.ts → packages/workflow-package/lib/package-root.d.ts}

@@ -1,2 +1 @@
 export declare const PACKAGE_ROOT: string;
-export declare const INTERF_HOME: string;

package/dist/packages/workflow-package/lib/package-root.js

@@ -0,0 +1,6 @@
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+// Package root (dist/packages/workflow-package/lib/ -> package root)
+export const PACKAGE_ROOT = join(__dirname, "..", "..", "..", "..");

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

@@ -0,0 +1,54 @@
+import { z } from "zod";
+import { WorkflowCompilerApiSchema, RuntimeContractTypeSchema, RuntimeStageAcceptanceSchema, WorkflowPurposeSchema, WorkflowStageZoneAccessSchema, type WorkflowCompiledSchema } from "../compiler/lib/schema.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>;
+    label: string;
+    hint: string;
+    extends?: string;
+    stages?: LocalWorkflowStageDefinition[];
+    stage_policy_notes?: Record<string, string[]>;
+    workflow_schema: WorkflowCompiledSchema;
+    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 isWorkflowId(value: string): boolean;
+export declare function patchWorkflowPackageMetadata(dirPath: string, options?: {
+    id?: string;
+    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;