@interf/compiler 0.3.3 → 0.4.0

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

@@ -1,20 +1,41 @@
-import { mkdirSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
-import { WORKFLOW_PACKAGE_DIR } from "./interf-detect.js";
-import { renderWorkspaceQuerySkill } from "./workspace-docs.js";
+import { copyWorkflowPackageDirectory, isPortableWorkflowPackage, patchWorkflowPackageMetadata, resolveWorkflowPackageSourcePath, workflowDefinitionPath, } from "./local-workflows.js";
+import { getWorkspaceWorkflow, } from "./workflow-definitions.js";
+import { renderWorkspaceQuerySkill } from "./agent-shells.js";
+import { CHART_APPROXIMATION_NOTES } from "./chart-guidance.js";
 import { writeWorkspaceSchemaFile } from "./workspace-schema.js";
+import { workflowPackagePathForWorkspace } from "./workspace-paths.js";
 function workflowPackagePath(dirPath) {
-    return join(dirPath, WORKFLOW_PACKAGE_DIR);
+    return workflowPackagePathForWorkspace(dirPath);
 }
-function writeWorkflowStarterDocs(dirPath, docs) {
+function mergeWorkflowStagePolicyNotes(stages, baseNotes, nextNotes) {
+    const merged = {};
+    for (const stage of stages) {
+        const combined = Array.from(new Set([
+            ...(baseNotes?.[stage.id] ?? []),
+            ...(nextNotes?.[stage.id] ?? []),
+        ].map((note) => note.trim()).filter((note) => note.length > 0)));
+        if (combined.length > 0) {
+            merged[stage.id] = combined;
+        }
+    }
+    return Object.keys(merged).length > 0 ? merged : undefined;
+}
+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) {
-    writeFileSync(join(rootPath, "workflow.json"), `${JSON.stringify({
+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: "workspace",
         compiler_api: workflow.compilerApi ?? {
@@ -49,24 +70,56 @@ function renderWorkflowReadme(workflow) {
         "",
         "- `workflow.json` = stage graph, compiler API target, and compile contract mapping",
         "- `workspace.schema.json` = deterministic workspace output shape",
-        "- `create/`, `compile/stages/`, and `use/query/` = human-readable authoring docs",
-        "- Interf projects native agent shells from these docs for query use and stage execution",
+        "- `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 Compiler projects native agent shells from these docs for query use, stage execution, and workflow-improvement loops",
         "",
         "## Stages",
         "",
         stageLines,
         "",
-        "This workflow package lives under `workflow/` and is the reusable artifact that controls how Interf builds this compiled workspace.",
+        "Interf Compiler runs the workspace-local copy of this package directly from `.interf/workflow/` inside each compiled workspace.",
+        "",
+    ].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 dataset job.`,
+        "",
+        "Interf Compiler runs the workspace-local copy of this package directly. Keep changes in this folder self-contained instead of relying on runtime inheritance or fallback.",
+        "",
+        "## Emphasis",
+        "",
+        `- summarize: ${options.summarizeBias}`,
+        `- structure: ${options.structureBias}`,
+        `- shape: ${options.shapeBias}`,
         "",
     ].join("\n");
 }
-function renderCreateSkill(workflow) {
+function renderImproveSkill(workflow) {
     return [
-        "# Workspace Create Notes",
+        "# Workflow Improvement",
         "",
         `Workflow: ${workflow.id}`,
         "",
-        "This workspace uses the built-in Interf structure. Edit these notes only if you want local create-time guidance for agents or maintainers.",
+        "This file is the editable authoring source for Interf Compiler's generated native workflow-improver shell.",
+        "The improver edits this workspace-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 workspace to create a better workflow variation for this dataset.",
+        "4. Keep `workflow.json`, `workspace.schema.json`, and any changed stage docs aligned.",
+        "",
+        "Guardrails:",
+        "- do not edit truth checks, test specs, or raw dataset 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");
 }
@@ -86,6 +139,8 @@ function renderStageSkill(workflow, stage) {
             : stage.contractType === "workspace-query-shape"
                 ? [
                     "Use the workspace focus plus saved truth-check question text to shape `home.md` and retrieval routes.",
+                    "Rewrite `home.md` into a real entrypoint note. Do not leave the scaffold `Not yet compiled.` placeholder in place.",
+                    ...CHART_APPROXIMATION_NOTES,
                     "Do not copy expected answers into the workspace.",
                 ]
                 : [];
@@ -115,21 +170,107 @@ function renderStageSkill(workflow, stage) {
     ].join("\n");
 }
 export function writeWorkspaceWorkflowPackage(workspacePath, workflow) {
-    const workflowDir = workflowPackagePath(workspacePath);
-    mkdirSync(join(workflowDir, "create"), { recursive: true });
+    writeWorkflowPackageToDir(workflowPackagePath(workspacePath), 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);
-    writeWorkspaceSchemaFile(workflowDir, workflow.stages, `${workflow.label} workspace schema`);
-    writeFileSync(join(workflowDir, "README.md"), renderWorkflowReadme(workflow));
-    writeFileSync(join(workflowDir, "create", "SKILL.md"), renderCreateSkill(workflow));
-    writeFileSync(join(workflowDir, "use", "query", "SKILL.md"), renderWorkspaceQuerySkill());
+    writeWorkflowPackageJson(workflowDir, workflow, { overwrite });
+    if (overwrite || !existsSync(join(workflowDir, "workspace.schema.json"))) {
+        writeWorkspaceSchemaFile(workflowDir, workflow.stages, `${workflow.label} workspace 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"), renderWorkspaceQuerySkill());
+    }
     for (const stage of workflow.stages) {
-        writeFileSync(join(workflowDir, "compile", "stages", stage.skillDir, "SKILL.md"), renderStageSkill(workflow, stage));
+        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 seedWorkspaceWorkflowPackage(options) {
+    const resolvedWorkflow = getWorkspaceWorkflow(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
+        // workspace-local package folder without any source-root fallback.
+        copyWorkflowPackageDirectory(sourceWorkflowPath, workflowPackagePath(options.workspacePath));
+        return;
+    }
+    // Legacy or partially-defined seed packages are resolved once and
+    // materialized into a standalone workspace-local package.
+    writeWorkspaceWorkflowPackage(options.workspacePath, resolvedWorkflow);
+}
+export function createLocalWorkflowPackageFromTemplate(options) {
+    const sourceWorkflowPath = resolveWorkflowPackageSourcePath(options.sourcePath, options.baseWorkflowId);
+    const targetPath = workflowDefinitionPath(options.sourcePath, options.workflowId);
+    const stagePolicyNotes = {
+        summarize: [options.summarizeBias],
+        structure: [options.structureBias],
+        shape: [options.shapeBias],
+    };
+    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,
+            stagePolicyNotes,
+        });
+        writeFileSync(join(targetPath, "README.md"), renderDerivedWorkflowReadme({
+            label: options.label,
+            hint: options.hint,
+            baseWorkflowId: options.baseWorkflowId,
+            summarizeBias: options.summarizeBias,
+            structureBias: options.structureBias,
+            shapeBias: options.shapeBias,
+        }));
+        return targetPath;
     }
-    writeWorkflowStarterDocs(workflowDir, workflow.starterDocs);
+    // Legacy or inherited base packages are materialized immediately so the new
+    // local workflow package is standalone from its first write.
+    const baseWorkflow = getWorkspaceWorkflow(options.baseWorkflowId, {
+        sourcePath: options.sourcePath,
+    });
+    const localWorkflow = {
+        ...baseWorkflow,
+        id: options.workflowId,
+        label: options.label,
+        hint: options.hint,
+        recommended: false,
+        scope: "local",
+        stagePolicyNotes: mergeWorkflowStagePolicyNotes(baseWorkflow.stages, baseWorkflow.stagePolicyNotes, stagePolicyNotes),
+        starterDocs: [
+            {
+                relativePath: "README.md",
+                content: renderDerivedWorkflowReadme({
+                    label: options.label,
+                    hint: options.hint,
+                    baseWorkflowId: options.baseWorkflowId,
+                    summarizeBias: options.summarizeBias,
+                    structureBias: options.structureBias,
+                    shapeBias: options.shapeBias,
+                }),
+            },
+            ...(baseWorkflow.starterDocs ?? []).filter((doc) => doc.relativePath !== "README.md"),
+        ],
+    };
+    writeWorkflowPackageToDir(targetPath, localWorkflow);
+    return targetPath;
 }
-//# sourceMappingURL=interf-workflow-package.js.map

package/dist/lib/interf.d.ts

@@ -1,6 +1,5 @@
-export { INTERF_CONTAINER_NAME, WORKSPACE_CONTAINER_NAME, WORKFLOW_CONTAINER_NAME, BENCHMARK_CONTAINER_NAME, INTERF_CONFIG_FILE, WORKFLOW_PACKAGE_DIR, readInterfConfig, detectInterf, resolveWorkspace, resolveSourceFolderPath, resolveSourceControlPath, listWorkspacesForSourceFolder, hasSourceFolderInput, assertWorkspaceContainer, assertWritableTargetDir, assertWorkspaceName, } from "./interf-detect.js";
+export { INTERF_CONTAINER_NAME, WORKSPACE_CONTAINER_NAME, WORKFLOW_CONTAINER_NAME, TEST_CONTAINER_NAME, INTERF_CONFIG_FILE, WORKFLOW_PACKAGE_DIR, prepareWorkspaceLayout, readInterfConfig, detectInterf, resolveWorkspace, resolveSourceFolderPath, resolveSourceControlPath, listWorkspacesForSourceFolder, hasSourceFolderInput, assertWorkspaceContainer, assertWritableTargetDir, assertWorkspaceName, } from "./interf-detect.js";
 export type { InterfConfig, ResolvedWorkspace } from "./interf-detect.js";
 export { ensureWorkspaceRawBinding, resolveWorkspaceRawPath, syncWorkspaceRawSnapshot, } from "./workspace-raw.js";
 export { refreshWorkspaceBootstrapGuidance, renderClaudeBootstrap, } from "./interf-bootstrap.js";
 export { createWorkspace, defaultWorkspaceNameForSource, } from "./interf-scaffold.js";
-//# sourceMappingURL=interf.d.ts.map

package/dist/lib/interf.js

@@ -1,5 +1,4 @@
-export { INTERF_CONTAINER_NAME, WORKSPACE_CONTAINER_NAME, WORKFLOW_CONTAINER_NAME, BENCHMARK_CONTAINER_NAME, INTERF_CONFIG_FILE, WORKFLOW_PACKAGE_DIR, readInterfConfig, detectInterf, resolveWorkspace, resolveSourceFolderPath, resolveSourceControlPath, listWorkspacesForSourceFolder, hasSourceFolderInput, assertWorkspaceContainer, assertWritableTargetDir, assertWorkspaceName, } from "./interf-detect.js";
+export { INTERF_CONTAINER_NAME, WORKSPACE_CONTAINER_NAME, WORKFLOW_CONTAINER_NAME, TEST_CONTAINER_NAME, INTERF_CONFIG_FILE, WORKFLOW_PACKAGE_DIR, prepareWorkspaceLayout, readInterfConfig, detectInterf, resolveWorkspace, resolveSourceFolderPath, resolveSourceControlPath, listWorkspacesForSourceFolder, hasSourceFolderInput, assertWorkspaceContainer, assertWritableTargetDir, assertWorkspaceName, } from "./interf-detect.js";
 export { ensureWorkspaceRawBinding, resolveWorkspaceRawPath, syncWorkspaceRawSnapshot, } from "./workspace-raw.js";
 export { refreshWorkspaceBootstrapGuidance, renderClaudeBootstrap, } from "./interf-bootstrap.js";
 export { createWorkspace, defaultWorkspaceNameForSource, } from "./interf-scaffold.js";
-//# sourceMappingURL=interf.js.map

package/dist/lib/local-workflows.d.ts

@@ -33,7 +33,17 @@ export declare function workflowDefinitionPath(sourcePath: string, id: 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;
@@ -41,8 +51,3 @@ export interface WorkflowValidationResult {
     counts: Record<string, number>;
 }
 export declare function validateWorkflowPackage(dirPath: string): WorkflowValidationResult;
-export declare function writeLocalWorkflowDefinition(sourcePath: string, id: string, workflowJson: Record<string, unknown>, docs: Array<{
-    relativePath: string;
-    content: string;
-}>): string;
-//# sourceMappingURL=local-workflows.d.ts.map