@interf/compiler 0.18.0 → 0.22.0

package/dist/packages/build-plans/package/local-build-plans.js

@@ -0,0 +1,472 @@
+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 { BuildPlanEngineApiSchema, BuildPlanPurposeSchema, BuildPlanStageArtifactReadAccessSchema, BuildPlanStageArtifactWriteAccessSchema, } from "../../engine/build/lib/schema.js";
+import { RuntimeContractTypeSchema, InterfIdPattern, } from "../../contracts/lib/schema.js";
+import { asPreparationDataDir, preparationBuildPlansRoot, } from "../../contracts/lib/preparation-paths.js";
+import { CONTEXT_INTERFACE_FILE, ContextInterfaceSchema, contextInterfaceExists, contextInterfaceFilePath, listContextInterfaceArtifacts, readContextInterface, BuildPlanInputSpecSchema, writeContextInterface, } from "./context-interface.js";
+import { PACKAGE_ROOT } from "./lib/package-root.js";
+const LocalBuildPlanStageDefinitionSchema = 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: BuildPlanStageArtifactReadAccessSchema,
+    writes: BuildPlanStageArtifactWriteAccessSchema,
+});
+const LocalBuildPlanDefinitionSchema = z.object({
+    id: z.string().regex(InterfIdPattern),
+    type: z.literal("build-plan"),
+    engine_api: BuildPlanEngineApiSchema.optional(),
+    purpose: BuildPlanPurposeSchema.optional(),
+    inputs: z.array(BuildPlanInputSpecSchema).min(1).optional(),
+    label: z.string().min(1),
+    hint: z.string().min(1),
+    stages: z.array(LocalBuildPlanStageDefinitionSchema).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 buildPlanRootPath(prepDataDir) {
+    return preparationBuildPlansRoot(asPreparationDataDir(prepDataDir));
+}
+export function builtinBuildPlanPackagePath(buildPlanId) {
+    return join(PACKAGE_ROOT, "public-repo", "build-plans", buildPlanId);
+}
+export function buildPlanDefinitionPath(prepDataDir, id) {
+    return join(buildPlanRootPath(prepDataDir), id);
+}
+function isSupportedBuildPlanStarterDocPath(relativePath) {
+    if (relativePath === "README.md")
+        return true;
+    if (relativePath.startsWith("improve/"))
+        return true;
+    if (relativePath.startsWith("use/query/"))
+        return true;
+    if (relativePath.startsWith("build/stages/"))
+        return true;
+    return false;
+}
+function collectStarterDocs(dirPath) {
+    return listFilesRecursive(dirPath, isMarkdownFile)
+        .map((filePath) => relative(dirPath, filePath).replaceAll("\\", "/"))
+        .filter((relativePath) => isSupportedBuildPlanStarterDocPath(relativePath))
+        .map((relativePath) => ({
+        relativePath,
+        content: readFileSync(join(dirPath, relativePath), "utf8"),
+    }))
+        .sort((a, b) => a.relativePath.localeCompare(b.relativePath));
+}
+function buildPlanPackageCopyPaths(dirPath) {
+    return [
+        "build-plan.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 copyBuildPlanPackageFiles(sourceBuildPlanPath, targetBuildPlanPath) {
+    rmSync(targetBuildPlanPath, { recursive: true, force: true });
+    mkdirSync(targetBuildPlanPath, { recursive: true });
+    for (const relativePath of buildPlanPackageCopyPaths(sourceBuildPlanPath)) {
+        copyRelativeFile(sourceBuildPlanPath, targetBuildPlanPath, relativePath);
+    }
+}
+export function loadBuildPlanDefinitionFromDir(dirPath) {
+    const buildPlanPath = existsSync(join(dirPath, "build-plan.json"))
+        ? join(dirPath, "build-plan.json")
+        : null;
+    if (!buildPlanPath)
+        return null;
+    const definition = readJsonFileWithSchema(buildPlanPath, "local Build Plan definition", LocalBuildPlanDefinitionSchema);
+    if (!definition)
+        return null;
+    const buildPlanSchema = readContextInterface(dirPath);
+    if (!buildPlanSchema)
+        return null;
+    if (definition.type !== "build-plan") {
+        warnInterf(`Warning: local Build Plan definition at ${buildPlanPath} has unexpected type "${definition.type}".`);
+        return null;
+    }
+    return {
+        ...definition,
+        build_plan_schema: buildPlanSchema,
+        starter_docs: collectStarterDocs(dirPath),
+        directoryPath: dirPath,
+        buildPlanPath,
+        buildPlanSchemaPath: contextInterfaceFilePath(dirPath),
+    };
+}
+export function isNeutralScaffoldBuildPlanDefinition(definition) {
+    const hasScaffoldPurpose = definition.purpose?.label === "From-scratch Build Plan draft" ||
+        Boolean(definition.purpose?.task_hint?.includes("Replace this neutral scaffold"));
+    const hasScaffoldStage = Boolean(definition.stages?.some((stage) => stage.id === "prepare" &&
+        stage.contract_type === "build-plan-draft-stage" &&
+        stage.writes.includes("draft-context")));
+    const hasScaffoldArtifact = listContextInterfaceArtifacts(definition.build_plan_schema).some((artifact) => artifact.id === "draft-context" &&
+        artifact.description.includes("neutral authoring scaffold"));
+    return hasScaffoldPurpose || hasScaffoldStage || hasScaffoldArtifact;
+}
+export function listLocalBuildPlanDefinitions(prepDataDir) {
+    const definitions = new Map();
+    const root = buildPlanRootPath(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 = loadBuildPlanDefinitionFromDir(entryPath);
+            if (definition && !isNeutralScaffoldBuildPlanDefinition(definition)) {
+                definitions.set(definition.id, definition);
+            }
+        }
+    }
+    return [...definitions.values()].sort((a, b) => a.label.localeCompare(b.label));
+}
+export function loadLocalBuildPlanDefinition(prepDataDir, id) {
+    const definition = loadBuildPlanDefinitionFromDir(buildPlanDefinitionPath(prepDataDir, id));
+    if (!definition || isNeutralScaffoldBuildPlanDefinition(definition))
+        return null;
+    return definition;
+}
+export function resolveBuildPlanPackageSourcePath(prepDataDir, buildPlanId) {
+    const localPath = buildPlanDefinitionPath(prepDataDir, buildPlanId);
+    const local = loadBuildPlanDefinitionFromDir(localPath);
+    if (local && !isNeutralScaffoldBuildPlanDefinition(local))
+        return localPath;
+    const builtinPath = builtinBuildPlanPackagePath(buildPlanId);
+    if (loadBuildPlanDefinitionFromDir(builtinPath))
+        return builtinPath;
+    return null;
+}
+export function seedLocalDefaultBuildPlan(options) {
+    const buildPlanId = "interf-default";
+    const targetPath = buildPlanDefinitionPath(options.prepDataDir, buildPlanId);
+    if (existsSync(join(targetPath, "build-plan.json"))) {
+        return { buildPlanId, targetPath, alreadyExisted: true };
+    }
+    const builtinInterfPath = builtinBuildPlanPackagePath(buildPlanId);
+    if (!existsSync(join(builtinInterfPath, "build-plan.json"))) {
+        throw new Error(`Built-in "${buildPlanId}" Build Plan package not found at ${builtinInterfPath}.`);
+    }
+    copyBuildPlanPackageDirectory(builtinInterfPath, targetPath);
+    patchBuildPlanPackageMetadata(targetPath, {
+        id: buildPlanId,
+        label: "Built-in Interf Build Plan",
+        hint: "Built-in file-processing Build Plan: summarize source-grounded evidence, structure cross-file connections, and shape verifiable context around the saved readiness checks.",
+    });
+    return { buildPlanId, targetPath, alreadyExisted: false };
+}
+export function isBuildPlanId(value) {
+    return InterfIdPattern.test(value);
+}
+function readBuildPlanJsonObject(dirPath) {
+    const buildPlanPath = join(dirPath, "build-plan.json");
+    const raw = readJsonFileUnchecked(buildPlanPath, "Build Plan package");
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+        throw new Error(`Build Plan package at ${dirPath} is missing a valid build-plan.json.`);
+    }
+    return { ...raw };
+}
+export function patchBuildPlanPackageMetadata(dirPath, options) {
+    const buildPlanPath = join(dirPath, "build-plan.json");
+    const buildPlanJson = readBuildPlanJsonObject(dirPath);
+    const normalizedStages = Array.isArray(buildPlanJson.stages) && buildPlanJson.stages.length > 0
+        ? buildPlanJson.stages
+        : null;
+    if (!normalizedStages) {
+        throw new Error(`Cannot patch Build Plan package at ${dirPath}: build-plan.json must declare explicit stages before it can be copied or rewritten.`);
+    }
+    const nextBuildPlanJson = {
+        ...buildPlanJson,
+        type: "build-plan",
+        engine_api: buildPlanJson.engine_api ?? {
+            kind: "build",
+            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, buildPlanJson.stage_policy_notes, options.stagePolicyNotes);
+    if (mergedStagePolicyNotes) {
+        nextBuildPlanJson.stage_policy_notes = mergedStagePolicyNotes;
+    }
+    else {
+        delete nextBuildPlanJson.stage_policy_notes;
+    }
+    writeFileSync(buildPlanPath, JSON.stringify(nextBuildPlanJson, null, 2) + "\n");
+    const schemaLabel = `${String(nextBuildPlanJson.label ?? buildPlanJson.label ?? options.id ?? "Build Plan")} Build Plan schema`;
+    const existingSchema = readContextInterface(dirPath);
+    if (!existingSchema) {
+        throw new Error(`Cannot patch Build Plan package at ${dirPath}: missing ${CONTEXT_INTERFACE_FILE}. Restore or reseed the package instead of regenerating a schema from build-plan.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 collectBuildPlanPackageStructureIssues(dirPath, stages) {
+    const issues = [];
+    const buildPlanPath = join(dirPath, "build-plan.json");
+    if (!existsSync(buildPlanPath))
+        issues.push("missing build-plan.json");
+    if (!contextInterfaceExists(dirPath))
+        issues.push("missing build-plan.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, "build", "stages", skillDir, "SKILL.md"))) {
+            issues.push(`missing build/stages/${skillDir}/SKILL.md`);
+        }
+    }
+    return issues;
+}
+export function describeBuildPlanPackagePortability(dirPath) {
+    const issues = collectBuildPlanPackageStructureIssues(dirPath, null);
+    if (issues.length > 0)
+        return issues;
+    let buildPlanJson;
+    try {
+        buildPlanJson = readBuildPlanJsonObject(dirPath);
+    }
+    catch (error) {
+        issues.push(error instanceof Error ? error.message : String(error));
+        return issues;
+    }
+    const parsed = LocalBuildPlanDefinitionSchema.safeParse(buildPlanJson);
+    if (!parsed.success) {
+        issues.push(...parsed.error.issues.map((issue) => issue.path.length > 0
+            ? `build-plan.json ${issue.path.join(".")}: ${issue.message}`
+            : `build-plan.json: ${issue.message}`));
+        return issues;
+    }
+    if (!parsed.data.stages || parsed.data.stages.length === 0) {
+        issues.push("build-plan.json must declare explicit stages for a portable Build Plan package");
+        return issues;
+    }
+    // Structural issues already returned earlier; only stage-skill files can be missing now.
+    return [
+        ...issues,
+        ...collectBuildPlanPackageStructureIssues(dirPath, parsed.data.stages ?? null),
+    ];
+}
+export function isPortableBuildPlanPackage(dirPath) {
+    return describeBuildPlanPackagePortability(dirPath).length === 0;
+}
+export function copyBuildPlanPackageDirectory(sourceBuildPlanPath, targetBuildPlanPath) {
+    const portabilityIssues = describeBuildPlanPackagePortability(sourceBuildPlanPath);
+    if (portabilityIssues.length > 0) {
+        throw new Error(`Build Plan package at ${sourceBuildPlanPath} is not directly copyable: ${portabilityIssues.join("; ")}.`);
+    }
+    mkdirSync(dirname(targetBuildPlanPath), { recursive: true });
+    copyBuildPlanPackageFiles(sourceBuildPlanPath, targetBuildPlanPath);
+}
+export function validateBuildPlanPackage(dirPath) {
+    const buildPlanPath = join(dirPath, "build-plan.json");
+    if (!existsSync(buildPlanPath)) {
+        return {
+            ok: false,
+            summary: `No build-plan.json found at ${dirPath}`,
+            errors: ["Missing build-plan.json"],
+            counts: {},
+        };
+    }
+    const raw = readJsonFileUnchecked(buildPlanPath, "Build Plan package");
+    if (!raw) {
+        return {
+            ok: false,
+            summary: `Failed to parse build-plan.json at ${buildPlanPath}`,
+            errors: ["Invalid JSON in build-plan.json"],
+            counts: {},
+        };
+    }
+    const parsed = LocalBuildPlanDefinitionSchema.safeParse(raw);
+    if (!parsed.success) {
+        const issues = parsed.error.issues.map((issue) => `${issue.path.join(".")}: ${issue.message}`);
+        return {
+            ok: false,
+            summary: `build-plan.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("build-plan.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(`build-plan.json stage_policy_notes references unknown stage "${stageId}".`);
+            }
+        }
+    }
+    for (const issue of collectBuildPlanPackageStructureIssues(dirPath, def.stages ?? null)) {
+        const formatted = issue.startsWith("missing ")
+            ? `Missing ${issue.slice("missing ".length)}.`
+            : issue;
+        errors.push(formatted);
+    }
+    const buildPlanSchema = readContextInterface(dirPath);
+    if (!buildPlanSchema) {
+        errors.push(...describeContextInterfaceValidationIssues(dirPath));
+    }
+    if (buildPlanSchema) {
+        const stages = def.stages ?? [];
+        const stageIds = new Set(stages.map((stage) => stage.id));
+        const seenPaths = new Map();
+        const seenArtifactIds = new Set();
+        const schemaArtifacts = listContextInterfaceArtifacts(buildPlanSchema);
+        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(`build-plan.schema.json repeats Artifact id "${artifact.id}".`);
+            }
+            seenArtifactIds.add(artifact.id);
+            const existingPathOwner = seenPaths.get(artifact.path);
+            if (existingPathOwner) {
+                errors.push(`build-plan.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(`build-plan.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(`build-plan.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(`build-plan.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 build-plan.schema.json.`);
+                }
+            }
+        }
+    }
+    const stageDirs = existsSync(join(dirPath, "build", "stages"))
+        ? listFilesRecursive(join(dirPath, "build", "stages"), (filePath) => basename(filePath) === "SKILL.md")
+        : [];
+    const counts = {
+        starter_docs: collectStarterDocs(dirPath).length,
+        build_stage_docs: stageDirs.length,
+        build_artifacts: buildPlanSchema ? listContextInterfaceArtifacts(buildPlanSchema).length : 0,
+        build_plan_artifacts: buildPlanSchema ? listContextInterfaceArtifacts(buildPlanSchema).length : 0,
+    };
+    return {
+        ok: errors.length === 0,
+        summary: errors.length === 0 ? "Build Plan package is valid." : `Build Plan package has ${errors.length} issue(s).`,
+        errors,
+        counts,
+    };
+}
+function describeContextInterfaceValidationIssues(dirPath) {
+    const buildPlanSchemaPath = contextInterfaceFilePath(dirPath);
+    if (!existsSync(buildPlanSchemaPath)) {
+        return ["build-plan.schema.json is missing."];
+    }
+    const raw = readJsonFileUnchecked(buildPlanSchemaPath, "Build Plan context interface");
+    if (raw === null) {
+        return ["build-plan.schema.json is invalid JSON."];
+    }
+    const parsed = ContextInterfaceSchema.safeParse(raw);
+    if (parsed.success) {
+        return ["build-plan.schema.json is missing or invalid."];
+    }
+    return parsed.error.issues.map((issue) => {
+        const path = issue.path.length > 0 ? issue.path.join(".") : "<root>";
+        return `build-plan.schema.json ${path}: ${issue.message}`;
+    });
+}

package/dist/packages/build-plans/package/user-build-plans.d.ts

@@ -0,0 +1,17 @@
+import { type LocalBuildPlanDefinition } from "./local-build-plans.js";
+export declare function userBuildPlanPath(id: string): string;
+export declare function userBuildPlanExists(id: string): boolean;
+export declare function listUserBuildPlanDefinitions(): LocalBuildPlanDefinition[];
+export declare function loadUserBuildPlanDefinition(id: string): LocalBuildPlanDefinition | null;
+export interface InstallUserBuildPlanOptions {
+    sourceDir: string;
+    id?: string;
+    overwrite?: boolean;
+}
+export interface InstallUserBuildPlanResult {
+    id: string;
+    path: string;
+    overwritten: boolean;
+}
+export declare function installUserBuildPlan(options: InstallUserBuildPlanOptions): InstallUserBuildPlanResult;
+export declare function removeUserBuildPlan(id: string): boolean;

package/dist/packages/build-plans/package/user-build-plans.js

@@ -0,0 +1,77 @@
+import { cpSync, existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync, } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { warnInterf } from "../../contracts/utils/logger.js";
+import { userBuildPlanPackagePath, userBuildPlansRoot, } from "../../contracts/lib/preparation-paths.js";
+import { loadBuildPlanDefinitionFromDir, } from "./local-build-plans.js";
+export function userBuildPlanPath(id) {
+    return userBuildPlanPackagePath(id);
+}
+export function userBuildPlanExists(id) {
+    return existsSync(join(userBuildPlanPath(id), "build-plan.json"));
+}
+export function listUserBuildPlanDefinitions() {
+    const root = userBuildPlansRoot();
+    if (!existsSync(root))
+        return [];
+    const definitions = [];
+    for (const entry of readdirSync(root)) {
+        const entryPath = join(root, entry);
+        try {
+            if (!statSync(entryPath).isDirectory())
+                continue;
+        }
+        catch {
+            continue;
+        }
+        const definition = loadBuildPlanDefinitionFromDir(entryPath);
+        if (definition)
+            definitions.push(definition);
+    }
+    return definitions.sort((a, b) => a.label.localeCompare(b.label));
+}
+export function loadUserBuildPlanDefinition(id) {
+    return loadBuildPlanDefinitionFromDir(userBuildPlanPath(id));
+}
+export function installUserBuildPlan(options) {
+    const sourceDir = resolve(options.sourceDir);
+    if (!existsSync(join(sourceDir, "build-plan.json"))) {
+        throw new Error(`No build-plan.json found at ${sourceDir}.`);
+    }
+    const definition = loadBuildPlanDefinitionFromDir(sourceDir);
+    if (!definition) {
+        throw new Error(`Could not load Build Plan package at ${sourceDir}.`);
+    }
+    const id = options.id ?? definition.id;
+    if (!id)
+        throw new Error("Build Plan id is required.");
+    const targetPath = userBuildPlanPath(id);
+    const existed = existsSync(targetPath);
+    if (existed && !options.overwrite) {
+        throw new Error(`User Build Plan "${id}" already exists at ${targetPath}. Pass overwrite to replace it.`);
+    }
+    mkdirSync(dirname(targetPath), { recursive: true });
+    if (existed)
+        rmSync(targetPath, { recursive: true, force: true });
+    cpSync(sourceDir, targetPath, { recursive: true, force: true });
+    if (id !== definition.id) {
+        const targetBuildPlanJson = join(targetPath, "build-plan.json");
+        const raw = readFileSync(targetBuildPlanJson, "utf8");
+        const parsed = JSON.parse(raw);
+        parsed.id = id;
+        writeFileSync(targetBuildPlanJson, `${JSON.stringify(parsed, null, 2)}\n`);
+    }
+    return { id, path: targetPath, overwritten: existed };
+}
+export function removeUserBuildPlan(id) {
+    const target = userBuildPlanPath(id);
+    if (!existsSync(target))
+        return false;
+    try {
+        rmSync(target, { recursive: true, force: true });
+        return true;
+    }
+    catch (error) {
+        warnInterf(`Warning: failed to remove user Build Plan ${id} at ${target}: ${error instanceof Error ? error.message : String(error)}`);
+        return false;
+    }
+}

package/dist/packages/contracts/index.d.ts

@@ -1,3 +1,3 @@
 export * as schema from "./lib/schema.js";
-export type { AgentRecord, AgentsRegistry, Artifact, ArtifactId, ArtifactShape, ArtifactStatus, CanonicalRole, Check, CheckKind, GateStatus, Locator, LocatorKind, MethodId, PreparationName, Proof, ReadinessGate, ReadinessStatus, Readiness, ReadyVerdict, RoleMap, RuntimeContractType, RuntimeExecutorInfo, RuntimeStage, RuntimeTargetType, Source, SourceFile, SourceFiles, SourceKind, SourceSnapshot, StageInput, StageInputs, StandardEvidenceFrontmatterKey, TestCaseExpect, TestTargetType, VerifyTargetResult, } from "./lib/schema.js";
+export type { AgentRecord, AgentsRegistry, Artifact, ArtifactId, ArtifactShape, ArtifactStatus, CanonicalRole, Check, CheckKind, GateStatus, Locator, LocatorKind, BuildPlanId, PreparationName, Proof, ReadinessGate, ReadinessStatus, Readiness, ReadyVerdict, RoleMap, RuntimeContractType, RuntimeExecutorInfo, RuntimeStage, RuntimeTargetType, Source, SourceFile, SourceFiles, SourceKind, SourceSnapshot, StageInput, StageInputs, StandardEvidenceFrontmatterKey, TestCaseExpect, TestTargetType, VerifyTargetResult, } from "./lib/schema.js";
 export { CANONICAL_ROLES, CHECK_KINDS, STANDARD_EVIDENCE_FRONTMATTER_KEYS, } from "./lib/schema.js";