@interf/compiler 0.7.3 → 0.9.3

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

@@ -0,0 +1,496 @@
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { renderCompiledQuerySkill } from "../agents/lib/shells.js";
+import { copyMethodPackageDirectory, isPortableMethodPackage, patchMethodPackageMetadata, resolveMethodPackageSourcePath, methodDefinitionPath, } from "./local-methods.js";
+import { getCompiledMethod, } from "./method-definitions.js";
+import { CONTEXT_INTERFACE_FILE, deriveMethodInputsFromContextInterface, summarizeContextInterface, writeContextInterface, writeContextInterfaceFile, } from "./context-interface.js";
+import { methodPackagePathForCompiled } from "../compiler/compiled-paths.js";
+import { mergeStagePolicyNotesForStages } from "./method-stage-policy.js";
+function methodPackagePath(dirPath) {
+    return methodPackagePathForCompiled(dirPath);
+}
+function writeMethodStarterDocs(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 writeMethodPackageJson(rootPath, method, options) {
+    const targetPath = join(rootPath, "method.json");
+    if (!options.overwrite && existsSync(targetPath))
+        return;
+    const inputs = method.inputs?.length
+        ? method.inputs
+        : deriveMethodInputsFromContextInterface(method.contextInterface ?? method.schema);
+    writeFileSync(targetPath, `${JSON.stringify({
+        id: method.id,
+        type: "compiled",
+        compiler_api: method.compilerApi ?? {
+            kind: "compiled",
+            version: 1,
+        },
+        ...(method.purpose
+            ? {
+                purpose: {
+                    label: method.purpose.label,
+                    task_hint: method.purpose.taskHint,
+                },
+            }
+            : {}),
+        ...(inputs.length > 0 ? { inputs } : {}),
+        label: method.label,
+        hint: method.hint,
+        stages: method.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 } : {}),
+        })),
+        ...(method.stagePolicyNotes ? { stage_policy_notes: method.stagePolicyNotes } : {}),
+    }, null, 2)}\n`);
+}
+function renderMethodReadme(method) {
+    const contextInterface = method.contextInterface ?? method.schema ?? null;
+    const stageLines = method.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 = method.inputs?.length
+        ? method.inputs
+        : deriveMethodInputsFromContextInterface(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 [
+        `# ${method.label}`,
+        "",
+        method.hint,
+        ...(method.purpose
+            ? [
+                "",
+                "## Purpose",
+                "",
+                `- ${method.purpose.label}`,
+                `- ${method.purpose.taskHint}`,
+            ]
+            : []),
+        ...(inputLines
+            ? [
+                "",
+                "## Inputs",
+                "",
+                inputLines,
+            ]
+            : []),
+        ...(contextInterfaceLines
+            ? [
+                "",
+                "## Context Interface",
+                "",
+                ...(contextInterfaceSummaryLines
+                    ? [
+                        contextInterfaceSummaryLines,
+                        "",
+                    ]
+                    : []),
+                "Zone map:",
+                "",
+                contextInterfaceLines,
+            ]
+            : []),
+        "",
+        "## Package",
+        "",
+        "- `method.json` = stage graph, compiler API target, and compile contract mapping",
+        "- `method.schema.json` = deterministic context interface for the Method package",
+        "- `improve/`, `compile/stages/`, and `use/query/` = human-readable authoring docs",
+        "- Portable Method 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 Method-improvement loops",
+        "",
+        "## Stages",
+        "",
+        stageLines,
+        "",
+        "Interf runs the local copy of this package directly from `.interf/method/` inside each portable context.",
+        "",
+    ].join("\n");
+}
+function renderDerivedMethodReadme(options) {
+    return [
+        `# ${options.label}`,
+        "",
+        options.hint,
+        "",
+        `This Method package was forked from \`${options.baseMethodId}\` and materialized as a standalone package for this kind of agent work.`,
+        "It starts with that Method's topology; edit the package when the agent work needs different stages, zones, or proof.",
+        "",
+        "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.",
+        "",
+        "## 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 renderSeedMethodReadme(options) {
+    return [
+        `# ${options.label}`,
+        "",
+        options.hint,
+        "",
+        `This Method package was forked from \`${options.baseMethodId}\` as a standalone local package.`,
+        "It starts with that Method's topology; edit the package when the agent work needs different stages, zones, or proof.",
+        "",
+        "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.",
+        "",
+    ].join("\n");
+}
+function renderScratchMethodReadme(options) {
+    return [
+        `# ${options.label}`,
+        "",
+        options.hint,
+        "",
+        "This Method package is a neutral from-scratch authoring scaffold.",
+        "",
+        "It is not copied from `interf-default`, and its placeholder stage is not a recommended topology.",
+        "Replace purpose, inputs, context interface, stages, stage docs, proof rules, and query guidance with the Method this source data and task actually need.",
+        "",
+    ].join("\n");
+}
+function renderImproveSkill(method) {
+    return [
+        "# Method Improvement",
+        "",
+        `Method: ${method.id}`,
+        "",
+        "This file is the editable authoring source for Interf's generated native Method-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 Method package for this portable context to create a better Method variation for this kind of agent work.",
+        `4. Keep purpose, inputs, \`method.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 Method docs",
+        "- keep this package standalone; do not rely on runtime inheritance",
+        "- keep the Method stack coherent: purpose, inputs, context interface, and stages should describe the same job",
+        "- prefer small, defensible Method changes over random churn",
+        "",
+    ].join("\n");
+}
+function renderStageSkill(method, stage) {
+    const notes = method.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 `method.json` and `method.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 Method-level acceptance aligned when you change this stage.",
+        "- Treat runtime files as proof and execution state, not as the source of truth for Method 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 writeCompiledMethodPackage(compiledPath, method) {
+    writeMethodPackageToDir(methodPackagePath(compiledPath), method);
+}
+export function writeMethodPackageToDir(methodDir, method, options = {}) {
+    const overwrite = options.overwrite ?? true;
+    mkdirSync(join(methodDir, "improve"), { recursive: true });
+    mkdirSync(join(methodDir, "use", "query"), { recursive: true });
+    mkdirSync(join(methodDir, "compile", "stages"), { recursive: true });
+    for (const stage of method.stages) {
+        mkdirSync(join(methodDir, "compile", "stages", stage.skillDir), { recursive: true });
+    }
+    writeMethodPackageJson(methodDir, method, { overwrite });
+    if (overwrite || !existsSync(join(methodDir, CONTEXT_INTERFACE_FILE))) {
+        const contextInterface = method.contextInterface ?? method.schema;
+        if (contextInterface) {
+            writeContextInterface(methodDir, {
+                ...contextInterface,
+                label: contextInterface.label || `${method.label} Method schema`,
+            });
+        }
+        else {
+            writeContextInterfaceFile(methodDir, method.stages, `${method.label} Method schema`);
+        }
+    }
+    if (overwrite || !existsSync(join(methodDir, "README.md"))) {
+        writeFileSync(join(methodDir, "README.md"), renderMethodReadme(method));
+    }
+    if (overwrite || !existsSync(join(methodDir, "improve", "SKILL.md"))) {
+        writeFileSync(join(methodDir, "improve", "SKILL.md"), renderImproveSkill(method));
+    }
+    if (overwrite || !existsSync(join(methodDir, "use", "query", "SKILL.md"))) {
+        writeFileSync(join(methodDir, "use", "query", "SKILL.md"), renderCompiledQuerySkill());
+    }
+    for (const stage of method.stages) {
+        const targetPath = join(methodDir, "compile", "stages", stage.skillDir, "SKILL.md");
+        if (overwrite || !existsSync(targetPath)) {
+            writeFileSync(targetPath, renderStageSkill(method, stage));
+        }
+    }
+    writeMethodStarterDocs(methodDir, method.starterDocs, { overwrite });
+}
+export function seedCompiledMethodPackage(options) {
+    const resolvedMethod = getCompiledMethod(options.methodId, {
+        sourcePath: options.sourcePath,
+    });
+    const sourceMethodPath = resolveMethodPackageSourcePath(options.sourcePath, resolvedMethod.id);
+    if (sourceMethodPath && isPortableMethodPackage(sourceMethodPath)) {
+        // Portable seed packages can be copied directly because compile runs the
+        // local package folder without reading source-root Method packages.
+        copyMethodPackageDirectory(sourceMethodPath, methodPackagePath(options.compiledPath));
+        patchMethodPackageMetadata(methodPackagePath(options.compiledPath), {
+            id: resolvedMethod.id,
+            inputs: resolvedMethod.inputs,
+            label: resolvedMethod.label,
+            hint: resolvedMethod.hint,
+            stagePolicyNotes: resolvedMethod.stagePolicyNotes,
+        });
+        if (resolvedMethod.scope === "builtin") {
+            writeFileSync(join(methodPackagePath(options.compiledPath), "README.md"), renderMethodReadme(resolvedMethod));
+        }
+        return;
+    }
+    // Legacy or partially-defined seed packages are resolved once and
+    // materialized into a standalone local package.
+    writeCompiledMethodPackage(options.compiledPath, resolvedMethod);
+}
+export function createLocalMethodPackageFromTemplate(options) {
+    const targetPath = seedLocalMethodPackageFromBase({
+        sourcePath: options.sourcePath,
+        baseMethodId: options.baseMethodId,
+        methodId: options.methodId,
+        label: options.label,
+        hint: options.hint,
+    });
+    const baseMethod = getCompiledMethod(options.baseMethodId, {
+        sourcePath: options.sourcePath,
+    });
+    const stagePolicyNotes = mergeStagePolicyNotesForStages(baseMethod.stages, baseMethod.stagePolicyNotes, options.stagePolicyNotes);
+    patchMethodPackageMetadata(targetPath, {
+        id: options.methodId,
+        label: options.label,
+        hint: options.hint,
+        stagePolicyNotes,
+    });
+    writeFileSync(join(targetPath, "README.md"), renderDerivedMethodReadme({
+        label: options.label,
+        hint: options.hint,
+        baseMethodId: options.baseMethodId,
+        emphasis: baseMethod.stages
+            .map((stage) => ({
+            stageId: stage.id,
+            label: stage.label,
+            notes: stagePolicyNotes?.[stage.id] ?? [],
+        }))
+            .filter((entry) => entry.notes.length > 0),
+    }));
+    return targetPath;
+}
+export function seedLocalMethodPackageFromBase(options) {
+    const baseMethod = getCompiledMethod(options.baseMethodId, {
+        sourcePath: options.sourcePath,
+    });
+    const sourceMethodPath = resolveMethodPackageSourcePath(options.sourcePath, options.baseMethodId);
+    const targetPath = methodDefinitionPath(options.sourcePath, options.methodId);
+    if (sourceMethodPath && isPortableMethodPackage(sourceMethodPath)) {
+        // Copy directly when the base package is already portable and standalone.
+        copyMethodPackageDirectory(sourceMethodPath, targetPath);
+        patchMethodPackageMetadata(targetPath, {
+            id: options.methodId,
+            inputs: baseMethod.inputs,
+            label: options.label,
+            hint: options.hint,
+        });
+        writeFileSync(join(targetPath, "README.md"), renderSeedMethodReadme({
+            label: options.label,
+            hint: options.hint,
+            baseMethodId: options.baseMethodId,
+        }));
+        return targetPath;
+    }
+    // Base packages are materialized immediately so the new local Method package
+    // is standalone from its first write.
+    const localMethod = {
+        ...baseMethod,
+        id: options.methodId,
+        label: options.label,
+        hint: options.hint,
+        recommended: false,
+        scope: "local",
+        starterDocs: [
+            {
+                relativePath: "README.md",
+                content: renderSeedMethodReadme({
+                    label: options.label,
+                    hint: options.hint,
+                    baseMethodId: options.baseMethodId,
+                }),
+            },
+            ...(baseMethod.starterDocs ?? []).filter((doc) => doc.relativePath !== "README.md"),
+        ],
+    };
+    writeMethodPackageToDir(targetPath, localMethod);
+    return targetPath;
+}
+export function createScratchLocalMethodPackage(options) {
+    const targetPath = methodDefinitionPath(options.sourcePath, options.methodId);
+    const method = {
+        id: options.methodId,
+        compilerApi: {
+            kind: "compiled",
+            version: 1,
+        },
+        purpose: {
+            label: "From-scratch Method draft",
+            taskHint: "Replace this neutral scaffold with the Method stages, outputs, and proof rules this agent work requires.",
+        },
+        inputs: [
+            {
+                id: "raw",
+                label: "Raw",
+                description: "Source-folder raw snapshot copied into the Preparation for direct evidence and verification.",
+                required: true,
+            },
+        ],
+        label: options.label,
+        hint: options.hint,
+        recommended: false,
+        scope: "local",
+        contextInterface: {
+            kind: "method-schema",
+            version: 1,
+            target_type: "compiled",
+            label: `${options.label} Method schema`,
+            zones: [
+                {
+                    id: "raw",
+                    role: "input",
+                    path: "raw",
+                    kind: "directory",
+                    required: true,
+                    owned_by: [],
+                    description: "Source-folder raw snapshot copied into the Preparation for direct evidence and verification.",
+                },
+                {
+                    id: "draft-context",
+                    role: "output",
+                    path: "draft",
+                    kind: "directory",
+                    required: true,
+                    owned_by: ["prepare"],
+                    description: "Temporary placeholder output zone for the neutral authoring scaffold. Replace it with task-specific output zones.",
+                },
+                {
+                    id: "runtime",
+                    role: "runtime",
+                    path: ".interf/runtime",
+                    kind: "runtime",
+                    required: true,
+                    owned_by: [],
+                    description: "CLI-owned runtime state, health, stage contracts, and proof artifacts.",
+                },
+            ],
+        },
+        stages: [
+            {
+                id: "prepare",
+                label: "Prepare",
+                description: "Neutral placeholder stage for Method authoring. Replace this stage with the topology this agent work needs.",
+                contractType: "method-draft-stage",
+                skillDir: "prepare",
+                reads: ["raw", "runtime"],
+                writes: ["draft-context"],
+                acceptance: {
+                    stage_truthy: ["finished_at"],
+                },
+            },
+        ],
+        stagePolicyNotes: {
+            prepare: [
+                "This is a neutral authoring scaffold, not a recommended method topology.",
+                "Replace this stage, output zone, and proof rule when drafting the final method.",
+            ],
+        },
+        starterDocs: [
+            {
+                relativePath: "README.md",
+                content: renderScratchMethodReadme({
+                    label: options.label,
+                    hint: options.hint,
+                }),
+            },
+        ],
+    };
+    writeMethodPackageToDir(targetPath, method);
+    return targetPath;
+}

package/dist/packages/{workflow-package → method-package}/lib/package-root.js

@@ -2,5 +2,5 @@ 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)
+// Package root (dist/packages/method-package/lib/ -> package root)
 export const PACKAGE_ROOT = join(__dirname, "..", "..", "..", "..");

package/dist/packages/method-package/local-methods.d.ts

@@ -0,0 +1,64 @@
+import { z } from "zod";
+import { MethodCompilerApiSchema, RuntimeStageAcceptanceSchema, MethodPurposeSchema, MethodStageZoneAccessSchema } from "../compiler/lib/schema.js";
+import { RuntimeContractTypeSchema } from "../contracts/lib/schema.js";
+import { MethodInputSpecSchema, type ContextInterface, type MethodInputSpec } from "./context-interface.js";
+export interface LocalMethodStarterDoc {
+    relativePath: string;
+    content: string;
+}
+export interface LocalMethodStageDefinition {
+    id: string;
+    label: string;
+    contract_type: z.infer<typeof RuntimeContractTypeSchema>;
+    skill_dir?: string;
+    description?: string;
+    reads: z.infer<typeof MethodStageZoneAccessSchema>;
+    writes: z.infer<typeof MethodStageZoneAccessSchema>;
+    acceptance?: z.infer<typeof RuntimeStageAcceptanceSchema>;
+}
+export interface LocalMethodDefinition {
+    id: string;
+    type: "compiled";
+    compiler_api?: z.infer<typeof MethodCompilerApiSchema>;
+    purpose?: z.infer<typeof MethodPurposeSchema>;
+    inputs?: Array<z.infer<typeof MethodInputSpecSchema>>;
+    label: string;
+    hint: string;
+    stages?: LocalMethodStageDefinition[];
+    stage_policy_notes?: Record<string, string[]>;
+    method_schema: ContextInterface;
+    starter_docs: LocalMethodStarterDoc[];
+    directoryPath: string;
+    methodPath: string;
+    methodSchemaPath: string;
+}
+export declare function methodDefinitionPath(sourcePath: string, id: string): string;
+export declare function loadMethodDefinitionFromDir(dirPath: string): LocalMethodDefinition | null;
+export declare function listLocalMethodDefinitions(sourcePath: string): LocalMethodDefinition[];
+export declare function loadLocalMethodDefinition(sourcePath: string, id: string): LocalMethodDefinition | null;
+export declare function resolveMethodPackageSourcePath(sourcePath: string, methodId: string): string | null;
+export declare function seedLocalDefaultMethod(options: {
+    sourcePath: string;
+}): {
+    methodId: string;
+    targetPath: string;
+    alreadyExisted: boolean;
+};
+export declare function isMethodId(value: string): boolean;
+export declare function patchMethodPackageMetadata(dirPath: string, options?: {
+    id?: string;
+    inputs?: MethodInputSpec[];
+    label?: string;
+    hint?: string;
+    stagePolicyNotes?: Record<string, string[]>;
+}): void;
+export declare function describeMethodPackagePortability(dirPath: string): string[];
+export declare function isPortableMethodPackage(dirPath: string): boolean;
+export declare function copyMethodPackageDirectory(sourceMethodPath: string, targetMethodPath: string): void;
+export interface MethodValidationResult {
+    ok: boolean;
+    summary: string;
+    errors: string[];
+    counts: Record<string, number>;
+}
+export declare function validateMethodPackage(dirPath: string): MethodValidationResult;