@interf/compiler 0.18.0 → 0.22.0

package/dist/packages/build-plans/package/interf-build-plan-package.js

@@ -0,0 +1,466 @@
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { renderVerifiableContextQuerySkill } from "../../engine/agents/lib/shells.js";
+import { copyBuildPlanPackageDirectory, isPortableBuildPlanPackage, patchBuildPlanPackageMetadata, resolveBuildPlanPackageSourcePath, buildPlanDefinitionPath, mergeStagePolicyNotesForStages, } from "./local-build-plans.js";
+import { getBuildPlan, } from "./build-plan-definitions.js";
+import { CONTEXT_INTERFACE_FILE, deriveBuildPlanInputsFromContextInterface, listContextInterfaceArtifacts, summarizeContextInterface, writeContextInterface, writeContextInterfaceFile, } from "./context-interface.js";
+import { buildPlanPackagePathForVerifiableContext } from "../../engine/build/verifiable-context-paths.js";
+function writeBuildPlanStarterDocs(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 writeBuildPlanPackageJson(rootPath, buildPlan, options) {
+    const targetPath = join(rootPath, "build-plan.json");
+    if (!options.overwrite && existsSync(targetPath))
+        return;
+    const inputs = buildPlan.inputs?.length
+        ? buildPlan.inputs
+        : deriveBuildPlanInputsFromContextInterface(buildPlan.contextInterface ?? buildPlan.schema);
+    writeFileSync(targetPath, `${JSON.stringify({
+        id: buildPlan.id,
+        type: "build-plan",
+        engine_api: buildPlan.engineApi ?? {
+            kind: "build",
+            version: 1,
+        },
+        ...(buildPlan.purpose
+            ? {
+                purpose: {
+                    label: buildPlan.purpose.label,
+                    task_hint: buildPlan.purpose.taskHint,
+                },
+            }
+            : {}),
+        ...(inputs.length > 0 ? { inputs } : {}),
+        label: buildPlan.label,
+        hint: buildPlan.hint,
+        stages: buildPlan.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,
+        })),
+        ...(buildPlan.stagePolicyNotes ? { stage_policy_notes: buildPlan.stagePolicyNotes } : {}),
+    }, null, 2)}\n`);
+}
+function renderBuildPlanReadme(buildPlan) {
+    const contextInterface = buildPlan.contextInterface ?? buildPlan.schema ?? null;
+    const stageLines = buildPlan.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 = buildPlan.inputs?.length
+        ? buildPlan.inputs
+        : deriveBuildPlanInputsFromContextInterface(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 [
+        `# ${buildPlan.label}`,
+        "",
+        buildPlan.hint,
+        ...(buildPlan.purpose
+            ? [
+                "",
+                "## Purpose",
+                "",
+                `- ${buildPlan.purpose.label}`,
+                `- ${buildPlan.purpose.taskHint}`,
+            ]
+            : []),
+        ...(inputLines
+            ? [
+                "",
+                "## Inputs",
+                "",
+                inputLines,
+            ]
+            : []),
+        ...(contextInterfaceLines
+            ? [
+                "",
+                "## Context Interface",
+                "",
+                ...(contextInterfaceSummaryLines
+                    ? [
+                        contextInterfaceSummaryLines,
+                        "",
+                    ]
+                    : []),
+                "Artifact map:",
+                "",
+                contextInterfaceLines,
+            ]
+            : []),
+        "",
+        "## Package",
+        "",
+        "- `build-plan.json` = Build Plan stage graph, local-engine API target, and build contract mapping",
+        "- `build-plan.schema.json` = deterministic context interface for the Build Plan",
+        "- `improve/`, `build/stages/`, and `use/query/` = human-readable authoring docs",
+        "- Build Plans 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 Build Plan improvement loops",
+        "",
+        "## Stages",
+        "",
+        stageLines,
+        "",
+        "Interf runs the local copy of this Build Plan directly from `.interf/build-plan/` inside each verifiable-context output.",
+        "",
+    ].join("\n");
+}
+function renderDerivedBuildPlanReadme(options) {
+    return [
+        `# ${options.label}`,
+        "",
+        options.hint,
+        "",
+        `This Build Plan package was forked from \`${options.baseBuildPlanId}\` and materialized as a standalone package for this kind of agent work.`,
+        "It starts with that Build Plan 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 renderSeedBuildPlanReadme(options) {
+    return [
+        `# ${options.label}`,
+        "",
+        options.hint,
+        "",
+        `This Build Plan package was forked from \`${options.baseBuildPlanId}\` as a standalone local package.`,
+        "It starts with that Build Plan 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 renderScratchBuildPlanReadme(options) {
+    return [
+        `# ${options.label}`,
+        "",
+        options.hint,
+        "",
+        "This Build Plan 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 Build Plan this source data and task actually need.",
+        "",
+    ].join("\n");
+}
+function renderImproveSkill(buildPlan) {
+    return [
+        "# Build Plan Improvement",
+        "",
+        `Build Plan package: ${buildPlan.id}`,
+        "",
+        "This file is the editable authoring source for Interf's generated native Build Plan 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 Build Plan package for this verifiable context to create a better Build Plan implementation for this kind of agent work.",
+        `4. Keep purpose, inputs, \`build-plan.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 Build Plan docs",
+        "- keep this package standalone; do not rely on runtime inheritance",
+        "- keep the Build Plan stack coherent: purpose, inputs, context interface, and stages should describe the same job",
+        "- prefer small, defensible Build Plan changes over random churn",
+        "",
+    ].join("\n");
+}
+function renderStageSkill(buildPlan, stage) {
+    const notes = buildPlan.stagePolicyNotes?.[stage.id] ?? [];
+    const abstractRules = stage.contractType === "build-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 `build-plan.json` and `build-plan.schema.json` as the authoritative package contract for this stage.",
+        "- Read only from the declared input Artifacts unless this package explicitly documents broader Build Plan behavior.",
+        "- Write only inside the declared output Artifacts for this stage. Do not invent undeclared Artifacts or implicit outputs.",
+        "- Keep stage instructions, artifact ownership, and Build Plan checks aligned when you change this stage.",
+        "- Treat runtime files as proof and execution state, not as the source of truth for Build Plan 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 writeBuildPlanPackageForVerifiableContext(verifiableContextPath, buildPlan) {
+    writeBuildPlanPackageToDir(buildPlanPackagePathForVerifiableContext(verifiableContextPath), buildPlan);
+}
+export function writeBuildPlanPackageToDir(buildPlanDir, buildPlan, options = {}) {
+    const overwrite = options.overwrite ?? true;
+    mkdirSync(join(buildPlanDir, "improve"), { recursive: true });
+    mkdirSync(join(buildPlanDir, "use", "query"), { recursive: true });
+    mkdirSync(join(buildPlanDir, "build", "stages"), { recursive: true });
+    for (const stage of buildPlan.stages) {
+        mkdirSync(join(buildPlanDir, "build", "stages", stage.skillDir), { recursive: true });
+    }
+    writeBuildPlanPackageJson(buildPlanDir, buildPlan, { overwrite });
+    if (overwrite || !existsSync(join(buildPlanDir, CONTEXT_INTERFACE_FILE))) {
+        const contextInterface = buildPlan.contextInterface ?? buildPlan.schema;
+        if (contextInterface) {
+            writeContextInterface(buildPlanDir, {
+                ...contextInterface,
+                label: contextInterface.label || `${buildPlan.label} Build Plan schema`,
+            });
+        }
+        else {
+            writeContextInterfaceFile(buildPlanDir, buildPlan.stages, `${buildPlan.label} Build Plan schema`);
+        }
+    }
+    if (overwrite || !existsSync(join(buildPlanDir, "README.md"))) {
+        writeFileSync(join(buildPlanDir, "README.md"), renderBuildPlanReadme(buildPlan));
+    }
+    if (overwrite || !existsSync(join(buildPlanDir, "improve", "SKILL.md"))) {
+        writeFileSync(join(buildPlanDir, "improve", "SKILL.md"), renderImproveSkill(buildPlan));
+    }
+    if (overwrite || !existsSync(join(buildPlanDir, "use", "query", "SKILL.md"))) {
+        writeFileSync(join(buildPlanDir, "use", "query", "SKILL.md"), renderVerifiableContextQuerySkill());
+    }
+    for (const stage of buildPlan.stages) {
+        const targetPath = join(buildPlanDir, "build", "stages", stage.skillDir, "SKILL.md");
+        if (overwrite || !existsSync(targetPath)) {
+            writeFileSync(targetPath, renderStageSkill(buildPlan, stage));
+        }
+    }
+    writeBuildPlanStarterDocs(buildPlanDir, buildPlan.starterDocs, { overwrite });
+}
+export function seedVerifiableContextBuildPlanPackage(options) {
+    const resolvedBuildPlan = getBuildPlan(options.buildPlanId, {
+        prepDataDir: options.prepDataDir,
+    });
+    const sourceBuildPlanPath = resolveBuildPlanPackageSourcePath(options.prepDataDir, resolvedBuildPlan.id);
+    if (sourceBuildPlanPath && isPortableBuildPlanPackage(sourceBuildPlanPath)) {
+        // Portable seed packages can be copied directly because Build runs the
+        // local package folder without reading source-root Build Plan packages.
+        copyBuildPlanPackageDirectory(sourceBuildPlanPath, buildPlanPackagePathForVerifiableContext(options.verifiableContextPath));
+        patchBuildPlanPackageMetadata(buildPlanPackagePathForVerifiableContext(options.verifiableContextPath), {
+            id: resolvedBuildPlan.id,
+            inputs: resolvedBuildPlan.inputs,
+            label: resolvedBuildPlan.label,
+            hint: resolvedBuildPlan.hint,
+            stagePolicyNotes: resolvedBuildPlan.stagePolicyNotes,
+        });
+        // The verifiable-context README is always derived from the resolved Build Plan;
+        // any hand-authored README belongs in the Preparation-local draft at
+        // <prep-data>/build-plans/<id>/, not in the built copy.
+        writeFileSync(join(buildPlanPackagePathForVerifiableContext(options.verifiableContextPath), "README.md"), renderBuildPlanReadme(resolvedBuildPlan));
+        return;
+    }
+    // Legacy or partially-defined seed packages are resolved once and
+    // materialized into a standalone local package.
+    writeBuildPlanPackageForVerifiableContext(options.verifiableContextPath, resolvedBuildPlan);
+}
+export function createLocalBuildPlanPackageFromTemplate(options) {
+    const targetPath = seedLocalBuildPlanPackageFromBase({
+        prepDataDir: options.prepDataDir,
+        baseBuildPlanId: options.baseBuildPlanId,
+        buildPlanId: options.buildPlanId,
+        label: options.label,
+        hint: options.hint,
+    });
+    const baseBuildPlan = getBuildPlan(options.baseBuildPlanId, {
+        prepDataDir: options.prepDataDir,
+    });
+    const stagePolicyNotes = mergeStagePolicyNotesForStages(baseBuildPlan.stages, baseBuildPlan.stagePolicyNotes, options.stagePolicyNotes);
+    patchBuildPlanPackageMetadata(targetPath, {
+        id: options.buildPlanId,
+        label: options.label,
+        hint: options.hint,
+        stagePolicyNotes,
+    });
+    writeFileSync(join(targetPath, "README.md"), renderDerivedBuildPlanReadme({
+        label: options.label,
+        hint: options.hint,
+        baseBuildPlanId: options.baseBuildPlanId,
+        emphasis: baseBuildPlan.stages
+            .map((stage) => ({
+            stageId: stage.id,
+            label: stage.label,
+            notes: stagePolicyNotes?.[stage.id] ?? [],
+        }))
+            .filter((entry) => entry.notes.length > 0),
+    }));
+    return targetPath;
+}
+export function seedLocalBuildPlanPackageFromBase(options) {
+    const baseBuildPlan = getBuildPlan(options.baseBuildPlanId, {
+        prepDataDir: options.prepDataDir,
+    });
+    const sourceBuildPlanPath = resolveBuildPlanPackageSourcePath(options.prepDataDir, options.baseBuildPlanId);
+    const targetPath = buildPlanDefinitionPath(options.prepDataDir, options.buildPlanId);
+    if (sourceBuildPlanPath && isPortableBuildPlanPackage(sourceBuildPlanPath)) {
+        // Copy directly when the base package is already portable and standalone.
+        copyBuildPlanPackageDirectory(sourceBuildPlanPath, targetPath);
+        patchBuildPlanPackageMetadata(targetPath, {
+            id: options.buildPlanId,
+            inputs: baseBuildPlan.inputs,
+            label: options.label,
+            hint: options.hint,
+        });
+        writeFileSync(join(targetPath, "README.md"), renderSeedBuildPlanReadme({
+            label: options.label,
+            hint: options.hint,
+            baseBuildPlanId: options.baseBuildPlanId,
+        }));
+        return targetPath;
+    }
+    // Base packages are materialized immediately so the new local Build Plan package
+    // is standalone from its first write.
+    const localBuildPlan = {
+        ...baseBuildPlan,
+        id: options.buildPlanId,
+        label: options.label,
+        hint: options.hint,
+        recommended: false,
+        scope: "local",
+        starterDocs: [
+            {
+                relativePath: "README.md",
+                content: renderSeedBuildPlanReadme({
+                    label: options.label,
+                    hint: options.hint,
+                    baseBuildPlanId: options.baseBuildPlanId,
+                }),
+            },
+            ...(baseBuildPlan.starterDocs ?? []).filter((doc) => doc.relativePath !== "README.md"),
+        ],
+    };
+    writeBuildPlanPackageToDir(targetPath, localBuildPlan);
+    return targetPath;
+}
+export function createScratchLocalBuildPlanPackage(options) {
+    const targetPath = buildPlanDefinitionPath(options.prepDataDir, options.buildPlanId);
+    const buildPlan = {
+        id: options.buildPlanId,
+        engineApi: {
+            kind: "build",
+            version: 1,
+        },
+        purpose: {
+            label: "From-scratch Build Plan draft",
+            taskHint: "Replace this neutral scaffold with the Build Plan 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: "build-plan-schema",
+            version: 1,
+            target_type: "verifiable-context",
+            label: `${options.label} Build Plan 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 Build Plan authoring. Replace this stage with the topology this agent work needs.",
+                contractType: "build-plan-draft-stage",
+                skillDir: "prepare",
+                role: "general",
+                reads: [],
+                writes: ["draft-context"],
+            },
+        ],
+        stagePolicyNotes: {
+            prepare: [
+                "This is a neutral authoring scaffold, not a recommended Build Plan topology.",
+                "Replace this stage, Artifact, and check when drafting the final Build Plan.",
+            ],
+        },
+        starterDocs: [
+            {
+                relativePath: "README.md",
+                content: renderScratchBuildPlanReadme({
+                    label: options.label,
+                    hint: options.hint,
+                }),
+            },
+        ],
+    };
+    writeBuildPlanPackageToDir(targetPath, buildPlan);
+    return targetPath;
+}

package/dist/packages/{methods → build-plans}/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/methods/package/lib/ -> package root)
+// Package root (dist/packages/build-plans/package/lib/ -> package root)
 export const PACKAGE_ROOT = join(__dirname, "..", "..", "..", "..", "..");

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

@@ -0,0 +1,74 @@
+import { z } from "zod";
+import { BuildPlanEngineApiSchema, BuildPlanPurposeSchema, type BuildPlanStageArtifactReadAccess, type BuildPlanStageArtifactWriteAccess } from "../../engine/build/lib/schema.js";
+import { RuntimeContractTypeSchema } from "../../contracts/lib/schema.js";
+import { BuildPlanInputSpecSchema, type ContextInterface, type BuildPlanInputSpec } from "./context-interface.js";
+export interface LocalBuildPlanStarterDoc {
+    relativePath: string;
+    content: string;
+}
+export interface LocalBuildPlanStageDefinition {
+    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: BuildPlanStageArtifactReadAccess;
+    writes: BuildPlanStageArtifactWriteAccess;
+}
+export interface LocalBuildPlanDefinition {
+    id: string;
+    type: "build-plan";
+    engine_api?: z.infer<typeof BuildPlanEngineApiSchema>;
+    purpose?: z.infer<typeof BuildPlanPurposeSchema>;
+    inputs?: Array<z.infer<typeof BuildPlanInputSpecSchema>>;
+    label: string;
+    hint: string;
+    stages?: LocalBuildPlanStageDefinition[];
+    stage_policy_notes?: Record<string, string[]>;
+    build_plan_schema: ContextInterface;
+    starter_docs: LocalBuildPlanStarterDoc[];
+    directoryPath: string;
+    buildPlanPath: string;
+    buildPlanSchemaPath: string;
+}
+export declare function mergeStagePolicyNotesForStages(stages: readonly {
+    id: string;
+}[], baseNotes: unknown, overrideNotes: Record<string, string[]> | undefined): Record<string, string[]> | undefined;
+export declare function builtinBuildPlanPackagePath(buildPlanId: string): string;
+export declare function buildPlanDefinitionPath(prepDataDir: string, id: string): string;
+export declare function loadBuildPlanDefinitionFromDir(dirPath: string): LocalBuildPlanDefinition | null;
+export declare function isNeutralScaffoldBuildPlanDefinition(definition: Pick<LocalBuildPlanDefinition, "purpose" | "stages" | "build_plan_schema">): boolean;
+export declare function listLocalBuildPlanDefinitions(prepDataDir: string): LocalBuildPlanDefinition[];
+export declare function loadLocalBuildPlanDefinition(prepDataDir: string, id: string): LocalBuildPlanDefinition | null;
+export declare function resolveBuildPlanPackageSourcePath(prepDataDir: string, buildPlanId: string): string | null;
+export declare function seedLocalDefaultBuildPlan(options: {
+    prepDataDir: string;
+}): {
+    buildPlanId: string;
+    targetPath: string;
+    alreadyExisted: boolean;
+};
+export declare function isBuildPlanId(value: string): boolean;
+export declare function patchBuildPlanPackageMetadata(dirPath: string, options: {
+    id?: string;
+    inputs?: BuildPlanInputSpec[];
+    label?: string;
+    hint?: string;
+    stagePolicyNotes?: Record<string, string[]>;
+}): void;
+export declare function describeBuildPlanPackagePortability(dirPath: string): string[];
+export declare function isPortableBuildPlanPackage(dirPath: string): boolean;
+export declare function copyBuildPlanPackageDirectory(sourceBuildPlanPath: string, targetBuildPlanPath: string): void;
+export interface BuildPlanValidationResult {
+    ok: boolean;
+    summary: string;
+    errors: string[];
+    counts: Record<string, number>;
+}
+export declare function validateBuildPlanPackage(dirPath: string): BuildPlanValidationResult;