@interf/compiler 0.18.0 → 0.22.0

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

@@ -1,466 +0,0 @@
-import { existsSync, mkdirSync, writeFileSync } from "node:fs";
-import { dirname, join } from "node:path";
-import { renderCompiledQuerySkill } from "../../engine/agents/lib/shells.js";
-import { copyMethodPackageDirectory, isPortableMethodPackage, patchMethodPackageMetadata, resolveMethodPackageSourcePath, methodDefinitionPath, mergeStagePolicyNotesForStages, } from "./local-methods.js";
-import { getCompiledMethod, } from "./method-definitions.js";
-import { CONTEXT_INTERFACE_FILE, deriveMethodInputsFromContextInterface, listContextInterfaceArtifacts, summarizeContextInterface, writeContextInterface, writeContextInterfaceFile, } from "./context-interface.js";
-import { methodPackagePathForCompiled } from "../../engine/compile/compiled-paths.js";
-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,
-        })),
-        ...(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 contextInterfaceArtifacts = contextInterface
-        ? listContextInterfaceArtifacts(contextInterface)
-        : [];
-    const contextInterfaceLines = contextInterfaceArtifacts.length > 0
-        ? contextInterfaceArtifacts
-            .map((artifact) => `- \`${artifact.id}\` — ${artifact.role} ${artifact.kind} Artifact at \`${artifact.path}\`: ${artifact.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 Artifacts: ${interfaceSummary.inputArtifacts.length > 0 ? interfaceSummary.inputArtifacts.map((artifact) => `\`${artifact.id}\``).join(", ") : "none"}`,
-            `- Working Artifacts: ${interfaceSummary.workingArtifacts.length > 0 ? interfaceSummary.workingArtifacts.map((artifact) => `\`${artifact.id}\``).join(", ") : "none"}`,
-            `- Output Artifacts: ${interfaceSummary.outputArtifacts.length > 0 ? interfaceSummary.outputArtifacts.map((artifact) => `\`${artifact.id}\``).join(", ") : "none"}`,
-            `- Runtime Artifacts: ${interfaceSummary.runtimeArtifacts.length > 0 ? interfaceSummary.runtimeArtifacts.map((artifact) => `\`${artifact.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,
-                        "",
-                    ]
-                    : []),
-                "Artifact 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, Artifacts, or checks.",
-        "",
-        "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, Artifacts, or checks.",
-        "",
-        "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 source artifacts",
-        "- 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 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 Artifacts: ${stage.reads.map((artifactId) => `\`${artifactId}\``).join(", ")}`,
-        `- Writes Artifacts: ${stage.writes.map((artifactId) => `\`${artifactId}\``).join(", ")}`,
-        "",
-        "## Requirements",
-        "",
-        "- Treat `method.json` and `method.schema.json` as the authoritative package contract for this stage.",
-        "- Read only from the declared input Artifacts unless this package explicitly documents a broader method.",
-        "- Write only inside the declared output Artifacts for this stage. Do not invent undeclared Artifacts or implicit outputs.",
-        "- Keep stage instructions, artifact ownership, and Method-level checks 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,
-        "",
-        ...(notes.length > 0
-            ? [
-                "## Notes",
-                "",
-                ...notes.map((note) => `- ${note}`),
-                "",
-            ]
-            : []),
-    ].join("\n");
-}
-export function writeCompiledMethodPackage(compiledPath, method) {
-    writeMethodPackageToDir(methodPackagePathForCompiled(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, {
-        prepDataDir: options.prepDataDir,
-    });
-    const sourceMethodPath = resolveMethodPackageSourcePath(options.prepDataDir, 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, methodPackagePathForCompiled(options.compiledPath));
-        patchMethodPackageMetadata(methodPackagePathForCompiled(options.compiledPath), {
-            id: resolvedMethod.id,
-            inputs: resolvedMethod.inputs,
-            label: resolvedMethod.label,
-            hint: resolvedMethod.hint,
-            stagePolicyNotes: resolvedMethod.stagePolicyNotes,
-        });
-        // The portable-context README is always derived from the resolved Method;
-        // any hand-authored README belongs in the workspace draft at
-        // <workspace>/methods/<id>/, not in the compiled copy.
-        writeFileSync(join(methodPackagePathForCompiled(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({
-        prepDataDir: options.prepDataDir,
-        baseMethodId: options.baseMethodId,
-        methodId: options.methodId,
-        label: options.label,
-        hint: options.hint,
-    });
-    const baseMethod = getCompiledMethod(options.baseMethodId, {
-        prepDataDir: options.prepDataDir,
-    });
-    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, {
-        prepDataDir: options.prepDataDir,
-    });
-    const sourceMethodPath = resolveMethodPackageSourcePath(options.prepDataDir, options.baseMethodId);
-    const targetPath = methodDefinitionPath(options.prepDataDir, 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.prepDataDir, 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: "source",
-                label: "Source",
-                description: "Source references assigned to each stage by Interf runtime.",
-                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`,
-            artifacts: [
-                {
-                    id: "draft-context",
-                    description: "Temporary placeholder Artifact for the neutral authoring scaffold. Replace it with task-specific Artifacts.",
-                    shape: { kind: "path", path: "draft", artifact_kind: "directory" },
-                    checks: [
-                        { id: "exists", kind: "min_file_count", required: true, params: { min: 1 } },
-                    ],
-                    built_by_stages: ["prepare"],
-                },
-            ],
-        },
-        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",
-                role: "general",
-                reads: [],
-                writes: ["draft-context"],
-            },
-        ],
-        stagePolicyNotes: {
-            prepare: [
-                "This is a neutral authoring scaffold, not a recommended method topology.",
-                "Replace this stage, Artifact, and check 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/methods/package/local-methods.d.ts

@@ -1,73 +0,0 @@
-import { z } from "zod";
-import { MethodCompilerApiSchema, MethodPurposeSchema, type MethodStageArtifactReadAccess, type MethodStageArtifactWriteAccess } from "../../engine/compile/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;
-    /**
-     * Optional role hint. Open-ended string; defaults to `general` at the
-     * runtime layer when missing. Maps to a connected agent via the user's
-     * role-map (`~/.interf/agents.json`).
-     */
-    role?: string;
-    reads: MethodStageArtifactReadAccess;
-    writes: MethodStageArtifactWriteAccess;
-}
-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 mergeStagePolicyNotesForStages(stages: readonly {
-    id: string;
-}[], baseNotes: unknown, overrideNotes: Record<string, string[]> | undefined): Record<string, string[]> | undefined;
-export declare function builtinMethodPackagePath(methodId: string): string;
-export declare function methodDefinitionPath(prepDataDir: string, id: string): string;
-export declare function loadMethodDefinitionFromDir(dirPath: string): LocalMethodDefinition | null;
-export declare function listLocalMethodDefinitions(prepDataDir: string): LocalMethodDefinition[];
-export declare function loadLocalMethodDefinition(prepDataDir: string, id: string): LocalMethodDefinition | null;
-export declare function resolveMethodPackageSourcePath(prepDataDir: string, methodId: string): string | null;
-export declare function seedLocalDefaultMethod(options: {
-    prepDataDir: 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;