@interf/compiler 0.5.1 → 0.6.1

package/dist/lib/validate.js

@@ -7,12 +7,6 @@ import { listFilesRecursive } from "./filesystem.js";
 import { readInterfConfig } from "./interf.js";
 import { parseJsonFrontmatter } from "./parse.js";
 import { compiledInterfConfigPath } from "./compiled-paths.js";
-const REQUIRED_DIGEST_FIELDS = [
-    "source_kind",
-    "evidence_tier",
-    "truth_mode",
-    "state",
-];
 const MIN_ABSTRACT_WORDS = 5;
 const WIKILINK_PATTERN = /!?\[\[([^[\]]+)\]\]/g;
 export function readCompiledConfig(dirPath) {
@@ -36,7 +30,7 @@ export function readCompiledConfig(dirPath) {
         },
     };
 }
-export function validateSynthFiles(files) {
+export function validateSynthFiles(files, options) {
     let invalidFrontmatter = 0;
     let shortAbstracts = 0;
     for (const filePath of files) {
@@ -44,7 +38,7 @@ export function validateSynthFiles(files) {
         if (content === null)
             continue;
         const parsed = parseJsonFrontmatter(content);
-        if (!parsed || !hasRequiredSynthFields(parsed.frontmatter)) {
+        if (!parsed || !hasRequiredFrontmatterKeys(parsed.frontmatter, options?.requiredFrontmatterKeys)) {
             invalidFrontmatter += 1;
             continue;
         }
@@ -138,9 +132,8 @@ function dedupeFiles(dirPaths) {
     }
     return files;
 }
-function hasRequiredSynthFields(frontmatter) {
-    const hasSourceReference = "source" in frontmatter;
-    return hasSourceReference && REQUIRED_DIGEST_FIELDS.every((field) => field in frontmatter);
+function hasRequiredFrontmatterKeys(frontmatter, requiredKeys) {
+    return (requiredKeys ?? []).every((field) => field in frontmatter);
 }
 function extractBodyAbstract(body) {
     const lines = body.split(/\r?\n/);

package/dist/lib/workflow-authoring.d.ts

@@ -0,0 +1,26 @@
+import type { WorkflowExecutor } from "./executors.js";
+import { validateWorkflowPackage } from "./local-workflows.js";
+import type { SourceTruthCheck } from "./schema.js";
+import { type WorkflowReporter } from "./workflows.js";
+export interface WorkflowAuthoringRunResult {
+    status: "updated" | "no-change" | "invalid" | "executor-failed";
+    changed: boolean;
+    summary: string;
+    validation: ReturnType<typeof validateWorkflowPackage> | null;
+    workflowPath: string;
+    shellPath: string;
+}
+export declare function runWorkflowAuthoringDraft(options: {
+    sourcePath: string;
+    datasetPath: string;
+    baseWorkflowId: string;
+    workflowId: string;
+    label: string;
+    hint: string;
+    taskPrompt: string;
+    checks?: SourceTruthCheck[];
+    executor: WorkflowExecutor;
+    preparePreview?: boolean;
+    previewReporter?: WorkflowReporter | null;
+}): Promise<WorkflowAuthoringRunResult>;
+export declare function resolveWorkflowDraftPath(sourcePath: string, workflowId: string): string;

package/dist/lib/workflow-authoring.js

@@ -0,0 +1,119 @@
+import { mkdtempSync, rmSync, } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { createWorkflowAuthoringShell } from "./agent-shells.js";
+import { WORKFLOW_SCHEMA_FILE } from "./compiled-schema.js";
+import { projectRawSnapshot } from "./compiled-raw.js";
+import { seedLocalWorkflowPackageFromBase } from "./interf-workflow-package.js";
+import { validateWorkflowPackage, workflowDefinitionPath } from "./local-workflows.js";
+import { runWorkflowEditSession } from "./workflow-edit-session.js";
+import { copyDirectory } from "./workflow-edit-utils.js";
+import { createCompiled, compileCompiled } from "./workflows.js";
+function buildWorkflowAuthoringPrompt() {
+    return [
+        "This is an automated Interf workflow-authoring run, not an open-ended chat session.",
+        "Execute it now.",
+        "Read `runtime/authoring-context.json` first.",
+        `Then read \`workflow/README.md\`, \`workflow/workflow.json\`, and \`workflow/${WORKFLOW_SCHEMA_FILE}\`.`,
+        "Review `artifacts/source-dataset/raw/` and any `artifacts/preview-compiled/` notes before editing the package.",
+        "Prefer direct file-reading and search tools over shell commands for routine file inspection.",
+        "Do not use shell helpers like `cat`, `sed`, `ls`, or `find` when a native read/search tool can inspect the same files.",
+        "Edit only files under `workflow/`.",
+        "Keep the workflow valid for the current compiler API and workflow schema.",
+        "Make the package materially more specific to this dataset task than the seeded base workflow. A no-op copy is not acceptable.",
+        "Prefer explicit stage-doc, stage-policy, purpose, and zone-contract edits over vague rewrites.",
+        "Do not introduce wikilinks unless the workflow also creates the target note by exact basename or explicit relative path.",
+        "Respect stage boundaries: a stage may only introduce links that resolve within that stage's declared writes or already-existing read zones.",
+        "Do not make one stage point at files or notes that are only created later by another stage.",
+        "Prefer conservative retrieval routing over speculative note sprawl.",
+        "Do not narrate plans or ask follow-up questions.",
+        "Only emit user-visible updates that begin with STATUS:, DONE:, BLOCKED:, or ERROR:.",
+        "As soon as the workflow edits are complete, stop.",
+    ].join("\n");
+}
+async function prepareWorkflowAuthoringPreview(options) {
+    const tempRoot = mkdtempSync(join(tmpdir(), "interf-workflow-preview-"));
+    projectRawSnapshot({
+        sourcePath: options.datasetPath,
+        destinationPath: tempRoot,
+        compiledPath: tempRoot,
+        mode: "copy",
+        prune: true,
+        preserveTimestamps: true,
+    });
+    copyDirectory(options.workflowPath, workflowDefinitionPath(tempRoot, options.workflowId));
+    const compiledPath = createCompiled("preview", tempRoot, options.workflowId, options.about, tempRoot);
+    const result = await compileCompiled({
+        executor: options.executor,
+        compiledPath,
+        ...(options.reporter ? { reporter: options.reporter } : {}),
+        preserveStageShells: "on-failure",
+    });
+    return {
+        tempRoot,
+        compiledPath,
+        compileResult: {
+            ok: result.ok,
+            failedStage: result.failedStage,
+        },
+    };
+}
+export async function runWorkflowAuthoringDraft(options) {
+    const workflowPath = seedLocalWorkflowPackageFromBase({
+        sourcePath: options.sourcePath,
+        baseWorkflowId: options.baseWorkflowId,
+        workflowId: options.workflowId,
+        label: options.label,
+        hint: options.hint,
+    });
+    let preview = null;
+    try {
+        if (options.preparePreview !== false) {
+            preview = await prepareWorkflowAuthoringPreview({
+                datasetPath: options.datasetPath,
+                about: options.taskPrompt,
+                workflowId: options.workflowId,
+                workflowPath,
+                executor: options.executor,
+                reporter: options.previewReporter ?? null,
+            });
+        }
+        const shell = createWorkflowAuthoringShell({
+            workflowPath,
+            workflowId: options.workflowId,
+            label: options.label,
+            baseWorkflowId: options.baseWorkflowId,
+            datasetPath: options.datasetPath,
+            taskPrompt: options.taskPrompt,
+            checks: options.checks ?? [],
+            preview,
+        });
+        if (preview) {
+            rmSync(preview.tempRoot, { recursive: true, force: true });
+            preview = null;
+        }
+        const session = await runWorkflowEditSession({
+            executor: options.executor,
+            workflowPath,
+            shell,
+            prompt: buildWorkflowAuthoringPrompt(),
+            validate: validateWorkflowPackage,
+        });
+        return {
+            status: session.status,
+            changed: session.changed,
+            summary: session.summary,
+            validation: session.validation,
+            workflowPath,
+            shellPath: shell.rootPath,
+        };
+    }
+    finally {
+        if (preview) {
+            rmSync(preview.tempRoot, { recursive: true, force: true });
+        }
+    }
+}
+export function resolveWorkflowDraftPath(sourcePath, workflowId) {
+    return workflowDefinitionPath(sourcePath, workflowId);
+}

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

@@ -1,4 +1,4 @@
-import type { RuntimeContractType, RuntimeStageAcceptance, WorkflowCompilerApi, WorkflowId, WorkflowZoneId } from "./schema.js";
+import type { RuntimeContractType, RuntimeStageAcceptance, WorkflowCompilerApi, WorkflowCompiledSchema, WorkflowId, WorkflowZoneId } from "./schema.js";
 export interface WorkflowStarterDoc {
     relativePath: string;
     content: string;
@@ -16,9 +16,14 @@ export interface WorkflowStageDefinition {
 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[];
@@ -28,6 +33,10 @@ 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<{
@@ -41,6 +50,7 @@ export declare function standaloneWorkflowDefinitionFromLocalPackage(local: {
         acceptance?: RuntimeStageAcceptance;
     }>;
     stage_policy_notes?: Record<string, string[]>;
+    workflow_schema?: WorkflowCompiledSchema;
     starter_docs: WorkflowStarterDoc[];
 }): WorkflowDefinition<string>;
 export declare function listCompiledWorkflowChoices(sourcePath?: string): WorkflowDefinition<string>[];

package/dist/lib/workflow-definitions.js

@@ -5,6 +5,7 @@ import { PACKAGE_ROOT } from "./config.js";
 import { resolveSourceControlPath } from "./interf.js";
 import { warnInterf } from "./logger.js";
 import { workflowPackagePathForCompiled } from "./compiled-paths.js";
+import { mergeStagePolicyNotesForStages } from "./workflow-stage-policy.js";
 let builtinInterfWorkflowCache = null;
 function toWorkflowStages(stages, fallbackStages) {
     if (!stages || stages.length === 0)
@@ -20,19 +21,6 @@ function toWorkflowStages(stages, fallbackStages) {
         ...(stage.acceptance ? { acceptance: stage.acceptance } : {}),
     }));
 }
-function mergeStagePolicyNotes(stages, baseNotes, overrideNotes) {
-    const merged = {};
-    for (const definition of stages) {
-        const combined = Array.from(new Set([
-            ...(baseNotes?.[definition.id] ?? []),
-            ...((overrideNotes?.[definition.id] ?? []).filter((note) => note.trim().length > 0)),
-        ]));
-        if (combined.length > 0) {
-            merged[definition.id] = combined;
-        }
-    }
-    return Object.keys(merged).length > 0 ? merged : undefined;
-}
 export function standaloneWorkflowDefinitionFromLocalPackage(local) {
     if (!local.stages || local.stages.length === 0) {
         throw new Error(`Workflow package "${local.id}" is missing explicit stages. Compiled-local and portable workflow packages must be standalone.`);
@@ -44,11 +32,20 @@ export function standaloneWorkflowDefinitionFromLocalPackage(local) {
             kind: "compiled",
             version: 1,
         },
+        ...(local.purpose
+            ? {
+                purpose: {
+                    label: local.purpose.label,
+                    taskHint: local.purpose.task_hint,
+                },
+            }
+            : {}),
         label: local.label,
         hint: local.hint,
         recommended: false,
+        ...(local.workflow_schema ? { schema: local.workflow_schema } : {}),
         stages,
-        stagePolicyNotes: mergeStagePolicyNotes(stages, undefined, local.stage_policy_notes),
+        stagePolicyNotes: mergeStagePolicyNotesForStages(stages, undefined, local.stage_policy_notes),
         starterDocs: [...local.starter_docs],
         scope: "local",
     };
@@ -113,7 +110,7 @@ export function getCompiledWorkflow(workflowId, options = {}) {
             return local;
         throw new Error(`No local workflow package found for "${workflowId}" under ${join(options.sourcePath, "interf", "workflows", workflowId)}.`);
     }
-    throw new Error(`Workflow "${workflowId}" is not built-in. Provide a source path so Interf Compiler can resolve a local workflow package.`);
+    throw new Error(`Workflow "${workflowId}" is not built-in. Provide a source path so Interf can resolve a local workflow package.`);
 }
 export function getActiveCompiledWorkflow(compiledPath, fallbackWorkflowId) {
     const workflowPath = workflowPackagePathForCompiled(compiledPath);

package/dist/lib/workflow-edit-session.d.ts

@@ -0,0 +1,16 @@
+import type { WorkflowExecutor } from "./executors.js";
+import type { WorkflowValidationResult } from "./local-workflows.js";
+import { type WorkflowEditShellArtifacts } from "./workflow-edit-utils.js";
+export interface WorkflowEditSessionResult {
+    status: "updated" | "no-change" | "invalid" | "executor-failed";
+    changed: boolean;
+    validation: WorkflowValidationResult | null;
+    summary: string;
+}
+export declare function runWorkflowEditSession(options: {
+    executor: WorkflowExecutor;
+    workflowPath: string;
+    shell: WorkflowEditShellArtifacts;
+    prompt: string;
+    validate: (workflowPath: string) => WorkflowValidationResult;
+}): Promise<WorkflowEditSessionResult>;

package/dist/lib/workflow-edit-session.js

@@ -0,0 +1,57 @@
+import { writeFileSync } from "node:fs";
+import { copyDirectory, directoriesMatch } from "./workflow-edit-utils.js";
+export async function runWorkflowEditSession(options) {
+    copyDirectory(options.workflowPath, options.shell.workflowBeforePath);
+    writeFileSync(options.shell.promptLogPath, `${options.prompt}\n`);
+    let code = 1;
+    let executeError = null;
+    try {
+        code = await options.executor.execute(options.shell.rootPath, options.prompt, {
+            eventLogPath: options.shell.eventLogPath,
+            statusLogPath: options.shell.statusLogPath,
+        });
+    }
+    catch (error) {
+        executeError = error instanceof Error ? error.message : String(error);
+    }
+    copyDirectory(options.workflowPath, options.shell.workflowAfterPath);
+    const changed = !directoriesMatch(options.shell.workflowBeforePath, options.shell.workflowAfterPath);
+    if (executeError) {
+        copyDirectory(options.shell.workflowBeforePath, options.workflowPath);
+        return {
+            status: "executor-failed",
+            changed,
+            validation: null,
+            summary: `Workflow editor failed before completing: ${executeError}`,
+        };
+    }
+    if (code !== 0) {
+        copyDirectory(options.shell.workflowBeforePath, options.workflowPath);
+        return {
+            status: "executor-failed",
+            changed,
+            validation: null,
+            summary: `Workflow editor exited with code ${code}.`,
+        };
+    }
+    const validation = options.validate(options.workflowPath);
+    if (!validation.ok) {
+        copyDirectory(options.shell.workflowBeforePath, options.workflowPath);
+        return {
+            status: "invalid",
+            changed,
+            validation,
+            summary: changed
+                ? `Workflow package failed validation: ${validation.summary}`
+                : `Workflow package is invalid without any workflow edits: ${validation.summary}`,
+        };
+    }
+    return {
+        status: changed ? "updated" : "no-change",
+        changed,
+        validation,
+        summary: changed
+            ? "Workflow package updated and validated."
+            : "Workflow package is valid without additional edits.",
+    };
+}

package/dist/lib/workflow-edit-utils.d.ts

@@ -0,0 +1,10 @@
+export declare function copyDirectory(sourcePath: string, targetPath: string): void;
+export declare function directoriesMatch(leftPath: string, rightPath: string): boolean;
+export interface WorkflowEditShellArtifacts {
+    rootPath: string;
+    workflowBeforePath: string;
+    workflowAfterPath: string;
+    promptLogPath: string;
+    eventLogPath: string;
+    statusLogPath: string;
+}

package/dist/lib/workflow-edit-utils.js

@@ -0,0 +1,39 @@
+import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, } from "node:fs";
+import { join, relative } from "node:path";
+export function copyDirectory(sourcePath, targetPath) {
+    rmSync(targetPath, { recursive: true, force: true });
+    mkdirSync(targetPath, { recursive: true });
+    cpSync(sourcePath, targetPath, { recursive: true });
+}
+function listFileSnapshot(dirPath) {
+    const snapshot = new Map();
+    if (!existsSync(dirPath))
+        return snapshot;
+    const collect = (currentPath) => {
+        for (const entry of readdirSync(currentPath)) {
+            const fullPath = join(currentPath, entry);
+            const stat = statSync(fullPath);
+            if (stat.isDirectory()) {
+                collect(fullPath);
+                continue;
+            }
+            if (!stat.isFile())
+                continue;
+            snapshot.set(relative(dirPath, fullPath), readFileSync(fullPath, "utf8"));
+        }
+    };
+    collect(dirPath);
+    return snapshot;
+}
+export function directoriesMatch(leftPath, rightPath) {
+    const left = listFileSnapshot(leftPath);
+    const right = listFileSnapshot(rightPath);
+    if (left.size !== right.size)
+        return false;
+    for (const [relativePath, content] of left.entries()) {
+        if (right.get(relativePath) !== content) {
+            return false;
+        }
+    }
+    return true;
+}