@interf/compiler 0.18.0 → 0.22.0

package/dist/packages/methods/package/local-methods.js

@@ -1,457 +0,0 @@
-import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync, } from "node:fs";
-import { basename, dirname, join, relative } from "node:path";
-import { z } from "zod";
-import { listFilesRecursive } from "../../contracts/utils/filesystem.js";
-import { warnInterf } from "../../contracts/utils/logger.js";
-import { readJsonFileUnchecked, readJsonFileWithSchema } from "../../contracts/utils/parse.js";
-import { isMarkdownFile } from "../../contracts/utils/file-types.js";
-import { MethodCompilerApiSchema, MethodPurposeSchema, MethodStageArtifactReadAccessSchema, MethodStageArtifactWriteAccessSchema, } from "../../engine/compile/lib/schema.js";
-import { RuntimeContractTypeSchema, InterfIdPattern, } from "../../contracts/lib/schema.js";
-import { asPreparationDataDir, preparationMethodsRoot, } from "../../contracts/lib/preparation-paths.js";
-import { CONTEXT_INTERFACE_FILE, ContextInterfaceSchema, contextInterfaceExists, contextInterfaceFilePath, listContextInterfaceArtifacts, readContextInterface, MethodInputSpecSchema, writeContextInterface, } from "./context-interface.js";
-import { PACKAGE_ROOT } from "./lib/package-root.js";
-const LocalMethodStageDefinitionSchema = z.object({
-    id: z.string().regex(InterfIdPattern),
-    label: z.string().min(1),
-    contract_type: RuntimeContractTypeSchema,
-    skill_dir: z.string().regex(InterfIdPattern).optional(),
-    description: z.string().min(1).optional(),
-    role: z.string().min(1).optional(),
-    reads: MethodStageArtifactReadAccessSchema,
-    writes: MethodStageArtifactWriteAccessSchema,
-});
-const LocalMethodDefinitionSchema = z.object({
-    id: z.string().regex(InterfIdPattern),
-    type: z.literal("compiled"),
-    compiler_api: MethodCompilerApiSchema.optional(),
-    purpose: MethodPurposeSchema.optional(),
-    inputs: z.array(MethodInputSpecSchema).min(1).optional(),
-    label: z.string().min(1),
-    hint: z.string().min(1),
-    stages: z.array(LocalMethodStageDefinitionSchema).min(1).optional(),
-    stage_policy_notes: z.record(z.string(), z.array(z.string())).optional(),
-});
-function normalizeStagePolicyNotes(value) {
-    if (!value || typeof value !== "object" || Array.isArray(value))
-        return undefined;
-    const normalized = {};
-    for (const [stageId, notes] of Object.entries(value)) {
-        if (!Array.isArray(notes))
-            continue;
-        const cleaned = Array.from(new Set(notes
-            .filter((note) => typeof note === "string")
-            .map((note) => note.trim())
-            .filter((note) => note.length > 0)));
-        if (cleaned.length > 0) {
-            normalized[stageId] = cleaned;
-        }
-    }
-    return Object.keys(normalized).length > 0 ? normalized : undefined;
-}
-export function mergeStagePolicyNotesForStages(stages, baseNotes, overrideNotes) {
-    const normalizedBase = normalizeStagePolicyNotes(baseNotes);
-    const merged = {};
-    for (const stage of stages) {
-        const combined = Array.from(new Set([
-            ...(normalizedBase?.[stage.id] ?? []),
-            ...((overrideNotes?.[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 methodRootPath(prepDataDir) {
-    return preparationMethodsRoot(asPreparationDataDir(prepDataDir));
-}
-export function builtinMethodPackagePath(methodId) {
-    return join(PACKAGE_ROOT, "builtin-methods", methodId);
-}
-export function methodDefinitionPath(prepDataDir, id) {
-    return join(methodRootPath(prepDataDir), id);
-}
-function isSupportedMethodStarterDocPath(relativePath) {
-    if (relativePath === "README.md")
-        return true;
-    if (relativePath.startsWith("improve/"))
-        return true;
-    if (relativePath.startsWith("use/query/"))
-        return true;
-    if (relativePath.startsWith("compile/stages/"))
-        return true;
-    return false;
-}
-function collectStarterDocs(dirPath) {
-    return listFilesRecursive(dirPath, isMarkdownFile)
-        .map((filePath) => relative(dirPath, filePath).replaceAll("\\", "/"))
-        .filter((relativePath) => isSupportedMethodStarterDocPath(relativePath))
-        .map((relativePath) => ({
-        relativePath,
-        content: readFileSync(join(dirPath, relativePath), "utf8"),
-    }))
-        .sort((a, b) => a.relativePath.localeCompare(b.relativePath));
-}
-function methodPackageCopyPaths(dirPath) {
-    return [
-        "method.json",
-        CONTEXT_INTERFACE_FILE,
-        ...collectStarterDocs(dirPath).map((doc) => doc.relativePath),
-    ];
-}
-function copyRelativeFile(sourceRoot, targetRoot, relativePath) {
-    const sourcePath = join(sourceRoot, relativePath);
-    if (!existsSync(sourcePath))
-        return;
-    const targetPath = join(targetRoot, relativePath);
-    mkdirSync(dirname(targetPath), { recursive: true });
-    cpSync(sourcePath, targetPath, { force: true });
-}
-function copyMethodPackageFiles(sourceMethodPath, targetMethodPath) {
-    rmSync(targetMethodPath, { recursive: true, force: true });
-    mkdirSync(targetMethodPath, { recursive: true });
-    for (const relativePath of methodPackageCopyPaths(sourceMethodPath)) {
-        copyRelativeFile(sourceMethodPath, targetMethodPath, relativePath);
-    }
-}
-export function loadMethodDefinitionFromDir(dirPath) {
-    const methodPath = existsSync(join(dirPath, "method.json"))
-        ? join(dirPath, "method.json")
-        : null;
-    if (!methodPath)
-        return null;
-    const definition = readJsonFileWithSchema(methodPath, "local Method definition", LocalMethodDefinitionSchema);
-    if (!definition)
-        return null;
-    const methodSchema = readContextInterface(dirPath);
-    if (!methodSchema)
-        return null;
-    if (definition.type !== "compiled") {
-        warnInterf(`Warning: local Method definition at ${methodPath} has unexpected type "${definition.type}".`);
-        return null;
-    }
-    return {
-        ...definition,
-        method_schema: methodSchema,
-        starter_docs: collectStarterDocs(dirPath),
-        directoryPath: dirPath,
-        methodPath,
-        methodSchemaPath: contextInterfaceFilePath(dirPath),
-    };
-}
-export function listLocalMethodDefinitions(prepDataDir) {
-    const definitions = new Map();
-    const root = methodRootPath(prepDataDir);
-    if (existsSync(root)) {
-        for (const entryPath of readdirSync(root).map((entry) => join(root, entry))) {
-            try {
-                if (!statSync(entryPath).isDirectory())
-                    continue;
-            }
-            catch {
-                continue;
-            }
-            const definition = loadMethodDefinitionFromDir(entryPath);
-            if (definition)
-                definitions.set(definition.id, definition);
-        }
-    }
-    return [...definitions.values()].sort((a, b) => a.label.localeCompare(b.label));
-}
-export function loadLocalMethodDefinition(prepDataDir, id) {
-    return loadMethodDefinitionFromDir(methodDefinitionPath(prepDataDir, id));
-}
-export function resolveMethodPackageSourcePath(prepDataDir, methodId) {
-    const localPath = methodDefinitionPath(prepDataDir, methodId);
-    if (loadMethodDefinitionFromDir(localPath))
-        return localPath;
-    const builtinPath = builtinMethodPackagePath(methodId);
-    if (loadMethodDefinitionFromDir(builtinPath))
-        return builtinPath;
-    return null;
-}
-export function seedLocalDefaultMethod(options) {
-    const methodId = "interf-default";
-    const targetPath = methodDefinitionPath(options.prepDataDir, methodId);
-    if (existsSync(join(targetPath, "method.json"))) {
-        return { methodId, targetPath, alreadyExisted: true };
-    }
-    const builtinInterfPath = builtinMethodPackagePath(methodId);
-    if (!existsSync(join(builtinInterfPath, "method.json"))) {
-        throw new Error(`Built-in "${methodId}" Method package not found at ${builtinInterfPath}.`);
-    }
-    copyMethodPackageDirectory(builtinInterfPath, targetPath);
-    patchMethodPackageMetadata(targetPath, {
-        id: methodId,
-        label: "Built-in Interf Method",
-        hint: "Built-in file-processing Method: summarize source-grounded evidence, structure cross-file connections, and shape portable context around the saved readiness checks.",
-    });
-    return { methodId, targetPath, alreadyExisted: false };
-}
-export function isMethodId(value) {
-    return InterfIdPattern.test(value);
-}
-function readMethodJsonObject(dirPath) {
-    const methodPath = join(dirPath, "method.json");
-    const raw = readJsonFileUnchecked(methodPath, "Method package");
-    if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
-        throw new Error(`Method package at ${dirPath} is missing a valid method.json.`);
-    }
-    return { ...raw };
-}
-export function patchMethodPackageMetadata(dirPath, options) {
-    const methodPath = join(dirPath, "method.json");
-    const methodJson = readMethodJsonObject(dirPath);
-    const normalizedStages = Array.isArray(methodJson.stages) && methodJson.stages.length > 0
-        ? methodJson.stages
-        : null;
-    if (!normalizedStages) {
-        throw new Error(`Cannot patch Method package at ${dirPath}: method.json must declare explicit stages before it can be copied or rewritten.`);
-    }
-    const nextMethodJson = {
-        ...methodJson,
-        type: "compiled",
-        compiler_api: methodJson.compiler_api ?? {
-            kind: "compiled",
-            version: 1,
-        },
-        stages: normalizedStages,
-        ...(options.id ? { id: options.id } : {}),
-        ...(options.inputs && options.inputs.length > 0 ? { inputs: options.inputs } : {}),
-        ...(options.label ? { label: options.label } : {}),
-        ...(options.hint ? { hint: options.hint } : {}),
-    };
-    const mergedStagePolicyNotes = mergeStagePolicyNotesForStages(normalizedStages, methodJson.stage_policy_notes, options.stagePolicyNotes);
-    if (mergedStagePolicyNotes) {
-        nextMethodJson.stage_policy_notes = mergedStagePolicyNotes;
-    }
-    else {
-        delete nextMethodJson.stage_policy_notes;
-    }
-    writeFileSync(methodPath, JSON.stringify(nextMethodJson, null, 2) + "\n");
-    const schemaLabel = `${String(nextMethodJson.label ?? methodJson.label ?? options.id ?? "Method")} Method schema`;
-    const existingSchema = readContextInterface(dirPath);
-    if (!existingSchema) {
-        throw new Error(`Cannot patch Method package at ${dirPath}: missing ${CONTEXT_INTERFACE_FILE}. Restore or reseed the package instead of regenerating a schema from method.json.`);
-    }
-    writeContextInterface(dirPath, {
-        ...existingSchema,
-        label: schemaLabel,
-    });
-}
-function resolveStageSkillDir(stage) {
-    return typeof stage.skill_dir === "string" && stage.skill_dir.trim().length > 0
-        ? stage.skill_dir
-        : stage.id;
-}
-function collectMethodPackageStructureIssues(dirPath, stages) {
-    const issues = [];
-    const methodPath = join(dirPath, "method.json");
-    if (!existsSync(methodPath))
-        issues.push("missing method.json");
-    if (!contextInterfaceExists(dirPath))
-        issues.push("missing method.schema.json");
-    if (!existsSync(join(dirPath, "README.md")))
-        issues.push("missing README.md");
-    if (!existsSync(join(dirPath, "improve", "SKILL.md")))
-        issues.push("missing improve/SKILL.md");
-    if (!existsSync(join(dirPath, "use", "query", "SKILL.md")))
-        issues.push("missing use/query/SKILL.md");
-    if (!stages)
-        return issues;
-    for (const stage of stages) {
-        const skillDir = resolveStageSkillDir(stage);
-        if (!existsSync(join(dirPath, "compile", "stages", skillDir, "SKILL.md"))) {
-            issues.push(`missing compile/stages/${skillDir}/SKILL.md`);
-        }
-    }
-    return issues;
-}
-export function describeMethodPackagePortability(dirPath) {
-    const issues = collectMethodPackageStructureIssues(dirPath, null);
-    if (issues.length > 0)
-        return issues;
-    let methodJson;
-    try {
-        methodJson = readMethodJsonObject(dirPath);
-    }
-    catch (error) {
-        issues.push(error instanceof Error ? error.message : String(error));
-        return issues;
-    }
-    const parsed = LocalMethodDefinitionSchema.safeParse(methodJson);
-    if (!parsed.success) {
-        issues.push(...parsed.error.issues.map((issue) => issue.path.length > 0
-            ? `method.json ${issue.path.join(".")}: ${issue.message}`
-            : `method.json: ${issue.message}`));
-        return issues;
-    }
-    if (!parsed.data.stages || parsed.data.stages.length === 0) {
-        issues.push("method.json must declare explicit stages for a portable Method package");
-        return issues;
-    }
-    // Structural issues already returned earlier; only stage-skill files can be missing now.
-    return [
-        ...issues,
-        ...collectMethodPackageStructureIssues(dirPath, parsed.data.stages ?? null),
-    ];
-}
-export function isPortableMethodPackage(dirPath) {
-    return describeMethodPackagePortability(dirPath).length === 0;
-}
-export function copyMethodPackageDirectory(sourceMethodPath, targetMethodPath) {
-    const portabilityIssues = describeMethodPackagePortability(sourceMethodPath);
-    if (portabilityIssues.length > 0) {
-        throw new Error(`Method package at ${sourceMethodPath} is not directly copyable: ${portabilityIssues.join("; ")}.`);
-    }
-    mkdirSync(dirname(targetMethodPath), { recursive: true });
-    copyMethodPackageFiles(sourceMethodPath, targetMethodPath);
-}
-export function validateMethodPackage(dirPath) {
-    const methodPath = join(dirPath, "method.json");
-    if (!existsSync(methodPath)) {
-        return {
-            ok: false,
-            summary: `No method.json found at ${dirPath}`,
-            errors: ["Missing method.json"],
-            counts: {},
-        };
-    }
-    const raw = readJsonFileUnchecked(methodPath, "Method package");
-    if (!raw) {
-        return {
-            ok: false,
-            summary: `Failed to parse method.json at ${methodPath}`,
-            errors: ["Invalid JSON in method.json"],
-            counts: {},
-        };
-    }
-    const parsed = LocalMethodDefinitionSchema.safeParse(raw);
-    if (!parsed.success) {
-        const issues = parsed.error.issues.map((issue) => `${issue.path.join(".")}: ${issue.message}`);
-        return {
-            ok: false,
-            summary: `method.json failed validation: ${issues.length} issue(s)`,
-            errors: issues,
-            counts: {},
-        };
-    }
-    const def = parsed.data;
-    const errors = [];
-    if (!def.stages || def.stages.length === 0) {
-        errors.push("method.json must declare explicit stages.");
-    }
-    if (def.stage_policy_notes && def.stages) {
-        const stageIds = new Set(def.stages.map((stage) => stage.id));
-        for (const stageId of Object.keys(def.stage_policy_notes)) {
-            if (!stageIds.has(stageId)) {
-                errors.push(`method.json stage_policy_notes references unknown stage "${stageId}".`);
-            }
-        }
-    }
-    for (const issue of collectMethodPackageStructureIssues(dirPath, def.stages ?? null)) {
-        const formatted = issue.startsWith("missing ")
-            ? `Missing ${issue.slice("missing ".length)}.`
-            : issue;
-        errors.push(formatted);
-    }
-    const methodSchema = readContextInterface(dirPath);
-    if (!methodSchema) {
-        errors.push(...describeContextInterfaceValidationIssues(dirPath));
-    }
-    if (methodSchema) {
-        const stages = def.stages ?? [];
-        const stageIds = new Set(stages.map((stage) => stage.id));
-        const seenPaths = new Map();
-        const seenArtifactIds = new Set();
-        const schemaArtifacts = listContextInterfaceArtifacts(methodSchema);
-        const artifactById = new Map(schemaArtifacts.map((artifact) => [artifact.id, artifact]));
-        const normalizedParts = (value) => value.replaceAll("\\", "/").split("/").filter(Boolean);
-        const hasOverlappingPath = (value, other) => {
-            const a = normalizedParts(value);
-            const b = normalizedParts(other);
-            const shorter = a.length <= b.length ? a : b;
-            const longer = a.length <= b.length ? b : a;
-            return shorter.every((part, index) => longer[index] === part);
-        };
-        for (const artifact of schemaArtifacts) {
-            if (seenArtifactIds.has(artifact.id)) {
-                errors.push(`method.schema.json repeats Artifact id "${artifact.id}".`);
-            }
-            seenArtifactIds.add(artifact.id);
-            const existingPathOwner = seenPaths.get(artifact.path);
-            if (existingPathOwner) {
-                errors.push(`method.schema.json repeats Artifact path "${artifact.path}".`);
-            }
-            for (const [existingPath, existingZoneId] of seenPaths.entries()) {
-                if (existingPath === artifact.path)
-                    continue;
-                if (hasOverlappingPath(artifact.path, existingPath)) {
-                    errors.push(`method.schema.json Artifacts "${artifact.id}" and "${existingZoneId}" overlap on path "${artifact.path}" / "${existingPath}".`);
-                }
-            }
-            seenPaths.set(artifact.path, artifact.id);
-            if ((artifact.role === "input" || artifact.role === "runtime") && artifact.owned_by.length > 0) {
-                errors.push(`method.schema.json Artifact "${artifact.id}" cannot declare owners because its role is "${artifact.role}".`);
-            }
-            for (const owner of artifact.owned_by) {
-                if (!stageIds.has(owner)) {
-                    errors.push(`method.schema.json references unknown stage "${owner}" for Artifact path "${artifact.path}".`);
-                }
-            }
-        }
-        for (const stage of stages) {
-            for (const artifactId of stage.reads) {
-                if (!artifactById.has(artifactId)) {
-                    errors.push(`Stage "${stage.id}" reads unknown Artifact "${artifactId}".`);
-                }
-            }
-            for (const artifactId of stage.writes) {
-                const artifact = artifactById.get(artifactId);
-                if (!artifact) {
-                    errors.push(`Stage "${stage.id}" writes unknown Artifact "${artifactId}".`);
-                    continue;
-                }
-                if (artifact.role === "input" || artifact.role === "runtime") {
-                    errors.push(`Stage "${stage.id}" writes Artifact "${artifactId}" but Artifacts with role "${artifact.role}" are engine-owned inputs, not writable stage outputs.`);
-                }
-                if (!artifact.owned_by.includes(stage.id)) {
-                    errors.push(`Stage "${stage.id}" writes Artifact "${artifactId}" but that Artifact is not owned by the stage in method.schema.json.`);
-                }
-            }
-        }
-    }
-    const stageDirs = existsSync(join(dirPath, "compile", "stages"))
-        ? listFilesRecursive(join(dirPath, "compile", "stages"), (filePath) => basename(filePath) === "SKILL.md")
-        : [];
-    const counts = {
-        starter_docs: collectStarterDocs(dirPath).length,
-        compile_stage_docs: stageDirs.length,
-        compiled_artifacts: methodSchema ? listContextInterfaceArtifacts(methodSchema).length : 0,
-        method_artifacts: methodSchema ? listContextInterfaceArtifacts(methodSchema).length : 0,
-    };
-    return {
-        ok: errors.length === 0,
-        summary: errors.length === 0 ? "Method package is valid." : `Method package has ${errors.length} issue(s).`,
-        errors,
-        counts,
-    };
-}
-function describeContextInterfaceValidationIssues(dirPath) {
-    const methodSchemaPath = contextInterfaceFilePath(dirPath);
-    if (!existsSync(methodSchemaPath)) {
-        return ["method.schema.json is missing."];
-    }
-    const raw = readJsonFileUnchecked(methodSchemaPath, "Method context interface");
-    if (raw === null) {
-        return ["method.schema.json is invalid JSON."];
-    }
-    const parsed = ContextInterfaceSchema.safeParse(raw);
-    if (parsed.success) {
-        return ["method.schema.json is missing or invalid."];
-    }
-    return parsed.error.issues.map((issue) => {
-        const path = issue.path.length > 0 ? issue.path.join(".") : "<root>";
-        return `method.schema.json ${path}: ${issue.message}`;
-    });
-}

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

@@ -1,61 +0,0 @@
-import { type LocalMethodDefinition } from "./local-methods.js";
-import type { MethodCompilerApi } from "../../engine/compile/lib/schema.js";
-import type { MethodId, RuntimeContractType } from "../../contracts/lib/schema.js";
-import { type ContextInterface, type ContextInterfaceArtifactId, type MethodInputSpec } from "./context-interface.js";
-export interface MethodStarterDoc {
-    relativePath: string;
-    content: string;
-}
-export interface MethodStageDefinition {
-    id: string;
-    label: string;
-    description: string;
-    contractType: RuntimeContractType;
-    skillDir: string;
-    /**
-     * Role hint declared by the Method package. Defaults to `general` when
-     * absent; mapped to a connected agent via the user's role-map at run
-     * time.
-     */
-    role: string;
-    reads: ContextInterfaceArtifactId[];
-    writes: ContextInterfaceArtifactId[];
-}
-export interface MethodDefinition<TId extends string> {
-    id: TId;
-    compilerApi?: MethodCompilerApi;
-    purpose?: {
-        label: string;
-        taskHint: string;
-    };
-    inputs?: MethodInputSpec[];
-    label: string;
-    hint: string;
-    recommended?: boolean;
-    contextInterface?: ContextInterface;
-    schema?: ContextInterface;
-    stages: MethodStageDefinition[];
-    stagePolicyNotes?: Record<string, string[]>;
-    starterDocs?: MethodStarterDoc[];
-    scope?: "builtin" | "user" | "local";
-}
-export type CompiledMethodId = string;
-export declare function standaloneMethodDefinitionFromLocalPackage(local: LocalMethodDefinition): MethodDefinition<string>;
-export declare function listCompiledMethodChoices(prepDataDir?: string): MethodDefinition<string>[];
-export declare function getCompiledMethod(methodId: CompiledMethodId, options?: {
-    prepDataDir?: string;
-}): MethodDefinition<string>;
-export declare function getActiveCompiledMethod(compiledPath: string): MethodDefinition<string>;
-export declare function resolveCompiledMethodId(value: unknown): CompiledMethodId | null;
-export declare function resolveCompiledMethodFromConfig(config: unknown): CompiledMethodId | null;
-export declare function resolveRequiredCompiledMethodFromConfig(config: unknown, label?: string): CompiledMethodId;
-export declare function getMethodStageDefinition(methodId: MethodId, stage: string, prepDataDir?: string): MethodStageDefinition | null;
-export declare function getMethodStagePosition(methodId: MethodId, stage: string, prepDataDir?: string): {
-    stageIndex: number;
-    stageTotal: number;
-    stages: string[];
-} | null;
-export declare function getMethodStages(methodId: MethodId, prepDataDir?: string): string[];
-export declare function getActiveCompiledStages(compiledPath: string): string[];
-export declare function getActiveCompiledStagePolicyNotes(compiledPath: string, stage: string): string[];
-export declare function formatActiveCompiledMethodStageStep(compiledPath: string, stage: string): string;