@use-the-fork/spindle 0.0.0-stage → 0.0.2

package/build/BlueprintManagement/Services/BlueprintReconciliationService.js

@@ -0,0 +1,391 @@
+import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { join, relative, sep } from "node:path";
+import { planBlueprintCatalogReconciliation } from "../Reconciliation/BlueprintCatalogPlanner.js";
+import { applyRemovalOperations, catalogRemovalOperation, membershipRemovalOperation, validateRemovalTarget, } from "../Reconciliation/BlueprintRemovalCoordinator.js";
+import { InstallationService } from "./InstallationService.js";
+import { assertSafeInstallPaths, assertSingleFileDestination, exists, preparePlannedBlueprintFiles, } from "../Support/BlueprintFiles.js";
+import { readBlueprintVersion } from "../Versioning/BlueprintVersion.js";
+import { LoadProjectConfiguration } from "../../Foundation/Bootstrap/LoadProjectConfiguration.js";
+import { Service } from "../../Foundation/Service.js";
+import { ComputedContextService } from "../../TemplateRendering/Computed/ComputedContextService.js";
+function willInstallBlueprint(blueprint, selectedNewBlueprints, decisions) {
+    return (blueprint.status === "install" ||
+        (blueprint.status === "new" && selectedNewBlueprints.has(blueprint.name)) ||
+        ((blueprint.status === "conflict" || blueprint.status === "update") &&
+            decisions.get(blueprint.name) === "overwrite"));
+}
+async function prepareFiles(files, context, handler, renderedEntry) {
+    const requireText = handler.entryFile !== undefined
+        ? true
+        : handler.fileTarget
+            ? (file) => file.outputPath.toLowerCase().endsWith(".md")
+            : false;
+    if (renderedEntry === undefined) {
+        return preparePlannedBlueprintFiles(files, context, handler.validateMetadata, requireText);
+    }
+    const prepared = [];
+    for (const file of files) {
+        if (file.sourcePath !== renderedEntry.sourcePath ||
+            file.outputPath !== renderedEntry.outputPath) {
+            prepared.push(...(await preparePlannedBlueprintFiles([file], context, handler.validateMetadata, requireText)));
+            continue;
+        }
+        const bytes = await readFile(file.sourcePath);
+        if (!Buffer.from(renderedEntry.sourceText, "utf8").equals(bytes)) {
+            throw new Error(`Blueprint entry '${file.outputPath}' changed while planning; run again.`);
+        }
+        if (bytes.includes(0)) {
+            prepared.push(...(await preparePlannedBlueprintFiles([file], context, handler.validateMetadata, requireText)));
+            continue;
+        }
+        handler.validateMetadata?.(file.outputPath, renderedEntry.renderedText);
+        prepared.push({ ...file, renderedText: renderedEntry.renderedText });
+    }
+    return prepared;
+}
+async function planReconciliation(handler, options, blueprintNames, sourceFilesByName, resolveContext) {
+    const { mode, githubDirectory } = options;
+    const destinationDirectory = handler.destinationDirectory(githubDirectory);
+    const targetPath = (name) => handler.targetPath?.(destinationDirectory, name) ?? join(destinationDirectory, name);
+    const plan = [];
+    for (const name of blueprintNames) {
+        const target = targetPath(name);
+        const installed = await exists(target);
+        if (mode === "init") {
+            plan.push({ name, status: installed ? "conflict" : "install" });
+            continue;
+        }
+        plan.push({
+            name,
+            ...(handler.planUpdate
+                ? await handler.planUpdate({
+                    name,
+                    sourceFiles: sourceFilesByName.get(name),
+                    target,
+                    installed,
+                    resolveContext,
+                })
+                : { status: installed ? "conflict" : "new" }),
+        });
+    }
+    const newBlueprints = plan.filter((blueprint) => blueprint.status === "new").map((b) => b.name);
+    const selectedNewBlueprints = new Set(options.mode === "update"
+        ? options.includeNew
+            ? newBlueprints
+            : options.chooseNew && newBlueprints.length > 0
+                ? await options.chooseNew(handler.kind, newBlueprints)
+                : []
+        : []);
+    const decisions = new Map();
+    for (const blueprint of plan) {
+        if (blueprint.status !== "conflict" && blueprint.status !== "update")
+            continue;
+        if (options.conflictPolicy !== undefined) {
+            decisions.set(blueprint.name, options.conflictPolicy);
+        }
+        else if (options.chooseConflict) {
+            decisions.set(blueprint.name, await options.chooseConflict(handler.kind, blueprint.name, blueprint.installedVersion, blueprint.availableVersion));
+        }
+        else if (blueprint.status === "conflict") {
+            throw new Error(`${handler.kind} '${blueprint.name}' already exists; pass --on-conflict <overwrite|skip> to choose what to do in non-interactive runs.`);
+        }
+        else {
+            throw new Error(`${handler.kind} '${blueprint.name}' is outdated (${blueprint.installedVersion} -> ${blueprint.availableVersion}); pass --on-conflict <overwrite|skip> to choose what to do in non-interactive runs.`);
+        }
+    }
+    const willInstall = plan.some((blueprint) => willInstallBlueprint(blueprint, selectedNewBlueprints, decisions));
+    return {
+        handler,
+        mode,
+        githubDirectory,
+        destinationDirectory,
+        sourceFilesByName,
+        plan,
+        selectedNewBlueprints,
+        decisions,
+        willInstall,
+    };
+}
+async function applyReconciliation(prepared, preparedFilesByName, membershipCleanupOperations, installationService, recordAppliedChange) {
+    const { handler, mode, githubDirectory, destinationDirectory, plan, selectedNewBlueprints, decisions, } = prepared;
+    const targetPath = (name) => handler.targetPath?.(destinationDirectory, name) ?? join(destinationDirectory, name);
+    const outcomes = [];
+    for (const blueprint of plan) {
+        if (blueprint.status === "warning") {
+            outcomes.push({
+                kind: handler.kind,
+                name: blueprint.name,
+                status: "skipped",
+                warning: blueprint.warning,
+            });
+            continue;
+        }
+        if (blueprint.status === "up-to-date") {
+            outcomes.push({ kind: handler.kind, name: blueprint.name, status: "up-to-date" });
+            continue;
+        }
+        if (blueprint.status === "new" && !selectedNewBlueprints.has(blueprint.name)) {
+            outcomes.push({ kind: handler.kind, name: blueprint.name, status: "skipped" });
+            continue;
+        }
+        if ((blueprint.status === "conflict" || blueprint.status === "update") &&
+            decisions.get(blueprint.name) === "skip") {
+            outcomes.push({ kind: handler.kind, name: blueprint.name, status: "skipped" });
+            continue;
+        }
+        const target = targetPath(blueprint.name);
+        await assertSafeInstallPaths(githubDirectory, [blueprint.name], destinationDirectory, targetPath);
+        const replacing = blueprint.status === "conflict" || blueprint.status === "update";
+        const replacedMembershipPaths = [];
+        try {
+            if (replacing && handler.entryFile === undefined && !handler.fileTarget) {
+                for (const operation of membershipCleanupOperations) {
+                    if (operation.handler !== handler)
+                        continue;
+                    const pathWithinTarget = relative(target, operation.plan.target);
+                    if (pathWithinTarget === "" ||
+                        pathWithinTarget === ".." ||
+                        pathWithinTarget.startsWith(`..${sep}`)) {
+                        continue;
+                    }
+                    if (await validateRemovalTarget(githubDirectory, {
+                        ...operation,
+                        expectedTarget: "file",
+                    })) {
+                        replacedMembershipPaths.push(operation.plan);
+                    }
+                }
+                await rm(target, { recursive: true, force: true });
+                recordAppliedChange(`removed existing ${handler.kind} '${blueprint.name}' before replacement`);
+                for (const removed of replacedMembershipPaths) {
+                    recordAppliedChange(`removed destination-only ${handler.kind} file '${removed.path}'`);
+                }
+            }
+            outcomes.push(...replacedMembershipPaths.map((removed) => ({
+                kind: handler.kind,
+                name: removed.path,
+                status: "removed",
+            })));
+            await mkdir(destinationDirectory, { recursive: true });
+            const preparedFiles = preparedFilesByName.get(blueprint.name);
+            if (preparedFiles === undefined) {
+                throw new Error(`No prepared files are available for ${handler.kind} '${blueprint.name}'.`);
+            }
+            await installationService.installPreparedFiles(preparedFiles, target, handler.entryFile, replacing && (handler.entryFile !== undefined || handler.fileTarget === true), handler.fileTarget, (file) => {
+                if (handler.kind === "Skill") {
+                    recordAppliedChange(`applied Skill file '${blueprint.name}/${file.outputPath}'`);
+                }
+            });
+            const status = mode === "init" || blueprint.status === "new" ? "installed" : "updated";
+            recordAppliedChange(`${status} ${handler.kind} '${blueprint.name}'`);
+        }
+        catch (error) {
+            throw new Error(`Failed to apply ${handler.kind} '${blueprint.name}': ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+        }
+        outcomes.push({
+            kind: handler.kind,
+            name: blueprint.name,
+            status: mode === "init" || blueprint.status === "new" ? "installed" : "updated",
+        });
+    }
+    return outcomes;
+}
+async function performReconciliation(handlers, options, installationService) {
+    const outcomes = [];
+    let hasBlueprints = false;
+    const stacks = options.config?.stacks ?? options.context?.stacks ?? [];
+    const collections = [];
+    const initializers = [];
+    const deletionOperations = [];
+    const membershipCleanupOperations = [];
+    await assertSafeInstallPaths(options.githubDirectory, [], options.githubDirectory);
+    const handlerPlans = await planBlueprintCatalogReconciliation(handlers, options.githubDirectory, options.blueprintSourceRoot, stacks);
+    for (const handlerPlan of handlerPlans) {
+        const { handler, selections, catalogDeletions } = handlerPlan;
+        const destinationDirectory = handler.destinationDirectory(options.githubDirectory);
+        const deletions = handlerPlan.deletions;
+        membershipCleanupOperations.push(...handlerPlan.membershipCleanup.map((plan) => ({ handler, plan })));
+        catalogDeletions.forEach((deletion, index) => {
+            deletionOperations.push({ handler, deletion, plan: deletions[index] });
+        });
+        if (deletions.length > 0 || handlerPlan.membershipCleanup.length > 0)
+            hasBlueprints = true;
+        if (handler.prepareInitialize !== undefined) {
+            if (selections.length > 0 || catalogDeletions.length > 0) {
+                hasBlueprints = true;
+                initializers.push({ handler, selections, deletions: catalogDeletions });
+            }
+            continue;
+        }
+        const files = new Map();
+        for (const selection of selections) {
+            files.set(selection.name, selection.files);
+        }
+        const names = [...files.keys()];
+        if (names.length === 0)
+            continue;
+        hasBlueprints = true;
+        const targetPath = (name) => handler.targetPath?.(destinationDirectory, name) ?? join(destinationDirectory, name);
+        await assertSafeInstallPaths(options.githubDirectory, names, destinationDirectory, targetPath);
+        if (handler.entryFile !== undefined || handler.fileTarget) {
+            for (const name of names)
+                await assertSingleFileDestination(targetPath(name));
+        }
+        collections.push({ handler, names, files, deletions });
+    }
+    const plannedRemovals = [
+        ...deletionOperations.map(catalogRemovalOperation),
+        ...membershipCleanupOperations.map(membershipRemovalOperation),
+    ];
+    for (const operation of plannedRemovals) {
+        await validateRemovalTarget(options.githubDirectory, operation);
+    }
+    if (!hasBlueprints)
+        throw new Error("No Blueprints are available to install.");
+    let contextService;
+    const resolveContext = async () => {
+        contextService ??= options.app.make(ComputedContextService);
+        return (await contextService).resolve(async () => options.context ?? (await options.resolveContext?.()));
+    };
+    const plans = [];
+    for (const { handler, names, files } of collections) {
+        plans.push(await planReconciliation(handler, options, names, files, resolveContext));
+    }
+    const installing = plans.find((plan) => plan.willInstall);
+    const needsContext = installing !== undefined ||
+        initializers.some((initializer) => initializer.selections.length > 0);
+    const context = needsContext ? await resolveContext() : options.context;
+    if (needsContext && !context) {
+        throw new Error("Cannot install Blueprints without resolved Variables.");
+    }
+    for (const plan of plans) {
+        const targetPath = (name) => plan.handler.targetPath?.(plan.destinationDirectory, name) ??
+            join(plan.destinationDirectory, name);
+        await assertSafeInstallPaths(plan.githubDirectory, plan.plan.map((blueprint) => blueprint.name), plan.destinationDirectory, targetPath);
+        for (const blueprint of plan.plan) {
+            if (plan.handler.entryFile !== undefined || plan.handler.fileTarget) {
+                await assertSingleFileDestination(targetPath(blueprint.name));
+            }
+            const selectedNew = blueprint.status === "install" ||
+                (blueprint.status === "new" && plan.selectedNewBlueprints.has(blueprint.name));
+            if (selectedNew && (await exists(targetPath(blueprint.name)))) {
+                throw new Error(`${plan.handler.kind} '${blueprint.name}' already exists; it appeared while planning. Run the command again to resolve the conflict.`);
+            }
+        }
+    }
+    const preparedFilesByPlan = new Map();
+    // Capture every selected versioned entry before any supporting template can
+    // mutate the shared context, and confirm the planned version still matches.
+    for (const plan of plans) {
+        for (const blueprint of plan.plan) {
+            if (blueprint.status !== "update" ||
+                !willInstallBlueprint(blueprint, plan.selectedNewBlueprints, plan.decisions) ||
+                blueprint.renderedEntry !== undefined ||
+                blueprint.versionedEntry === undefined) {
+                continue;
+            }
+            const { sourcePath, outputPath } = blueprint.versionedEntry;
+            let renderedEntry;
+            const actual = await readBlueprintVersion(sourcePath, context, {
+                onRendered: (sourceText, renderedText) => {
+                    renderedEntry = { sourcePath, outputPath, sourceText, renderedText };
+                },
+            });
+            if (actual !== blueprint.availableVersion || renderedEntry === undefined) {
+                throw new Error(`${plan.handler.kind} '${blueprint.name}' version changed while planning; run again.`);
+            }
+            blueprint.renderedEntry = renderedEntry;
+        }
+    }
+    for (const plan of plans) {
+        const preparedFilesByName = new Map();
+        for (const blueprint of plan.plan) {
+            if (!willInstallBlueprint(blueprint, plan.selectedNewBlueprints, plan.decisions))
+                continue;
+            preparedFilesByName.set(blueprint.name, await prepareFiles(plan.sourceFilesByName.get(blueprint.name), context, plan.handler, blueprint.renderedEntry));
+        }
+        preparedFilesByPlan.set(plan, preparedFilesByName);
+    }
+    const configWrite = options.mode === "init"
+        ? {
+            path: join(options.githubDirectory, "spindle.json"),
+            content: `${JSON.stringify(options.config, null, 2)}\n`,
+        }
+        : undefined;
+    const preparedInitializers = [];
+    try {
+        for (const { handler, selections, deletions } of initializers) {
+            preparedInitializers.push({
+                handler,
+                initialization: await handler.prepareInitialize(options.githubDirectory, context ?? { stacks, variables: {} }, selections, deletions),
+            });
+        }
+    }
+    catch (error) {
+        await Promise.all(preparedInitializers.map(({ initialization }) => initialization.dispose().catch(() => undefined)));
+        throw error;
+    }
+    const completedChanges = [];
+    const recordAppliedChange = (description) => completedChanges.push(description);
+    try {
+        for (const plan of plans) {
+            outcomes.push(...(await applyReconciliation(plan, preparedFilesByPlan.get(plan), membershipCleanupOperations, installationService, recordAppliedChange)));
+        }
+        for (const { handler, initialization } of preparedInitializers) {
+            const initialized = await initialization.apply(recordAppliedChange);
+            for (const name of initialized.installed) {
+                outcomes.push({ kind: handler.kind, name, status: "installed" });
+            }
+            for (const name of initialized.removed) {
+                outcomes.push({ kind: handler.kind, name, status: "removed" });
+            }
+        }
+        outcomes.push(...(await applyRemovalOperations(options.githubDirectory, deletionOperations
+            .filter((operation) => operation.handler.prepareInitialize === undefined)
+            .map(catalogRemovalOperation), recordAppliedChange)));
+        outcomes.push(...(await applyRemovalOperations(options.githubDirectory, membershipCleanupOperations.map(membershipRemovalOperation), recordAppliedChange)));
+        if (configWrite !== undefined) {
+            try {
+                await mkdir(options.githubDirectory, { recursive: true });
+                await writeFile(configWrite.path, configWrite.content);
+                recordAppliedChange("wrote Config '.github/spindle.json'");
+            }
+            catch (error) {
+                throw new Error(`Failed to write Config '${configWrite.path}': ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+            }
+        }
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        const progress = completedChanges.length > 0 ? ` Completed changes: ${completedChanges.join(", ")}.` : "";
+        throw new Error(`${message}${progress} Application stopped; rollback was not attempted.`, {
+            cause: error,
+        });
+    }
+    finally {
+        await Promise.all(preparedInitializers.map(({ initialization }) => initialization.dispose().catch(() => undefined)));
+    }
+    return outcomes;
+}
+export class BlueprintReconciliationService extends Service {
+    installationService;
+    constructor(app) {
+        super(app);
+    }
+    async boot() {
+        this.installationService = await this.app.make(InstallationService);
+    }
+    async reconcile(handlers, options) {
+        this.assertApplicationBooted();
+        const perform = () => performReconciliation(handlers, {
+            ...options,
+            app: this.app,
+            githubDirectory: this.app.workspacePath(".github"),
+            blueprintSourceRoot: this.app.appPath("Assets/Blueprints"),
+        }, this.installationService);
+        if (options.mode === "init") {
+            return LoadProjectConfiguration.withTemporaryState(this.app, { status: "valid", data: options.config }, perform);
+        }
+        return perform();
+    }
+}

package/build/BlueprintManagement/Services/InstallationService.js

@@ -0,0 +1,54 @@
+import { copyFile, mkdir, mkdtemp, rename, rm, writeFile } from "node:fs/promises";
+import { basename, dirname, join } from "node:path";
+import { assertSingleFileDestination } from "../Support/BlueprintFiles.js";
+import { Service } from "../../Foundation/Service.js";
+async function installFile(file, destinationPath, replace = false, requireText = false) {
+    await mkdir(dirname(destinationPath), { recursive: true });
+    if (replace && requireText) {
+        await assertSingleFileDestination(destinationPath, true);
+        const stagingDirectory = await mkdtemp(join(dirname(destinationPath), ".spindle-"));
+        try {
+            const stagedPath = join(stagingDirectory, basename(destinationPath));
+            await writeFile(stagedPath, file.renderedText, { flag: "wx" });
+            await assertSingleFileDestination(destinationPath, true);
+            await rename(stagedPath, destinationPath);
+        }
+        finally {
+            await rm(stagingDirectory, { recursive: true, force: true });
+        }
+        return;
+    }
+    if (replace)
+        await rm(destinationPath, { recursive: true, force: true });
+    if (file.renderedText === null) {
+        await copyFile(file.sourcePath, destinationPath);
+    }
+    else if (requireText) {
+        await writeFile(destinationPath, file.renderedText, { flag: "wx" });
+    }
+    else {
+        await writeFile(destinationPath, file.renderedText);
+    }
+}
+export class InstallationService extends Service {
+    constructor(app) {
+        super(app);
+    }
+    async installPreparedFiles(files, target, entryFile, replace = false, atTarget = false, onFileApplied) {
+        this.assertApplicationBooted();
+        for (const file of files) {
+            const destinationPath = atTarget
+                ? target
+                : entryFile === undefined
+                    ? join(target, file.outputPath)
+                    : target;
+            try {
+                await installFile(file, destinationPath, replace, entryFile !== undefined || (atTarget && file.outputPath.toLowerCase().endsWith(".md")));
+            }
+            catch (error) {
+                throw new Error(`Failed to apply file '${file.outputPath}' at '${destinationPath}': ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+            }
+            onFileApplied?.(file, destinationPath);
+        }
+    }
+}

package/build/BlueprintManagement/Support/BlueprintFiles.js

@@ -0,0 +1,113 @@
+import { access, lstat, readFile } from "node:fs/promises";
+import { extname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { renderText } from "../../TemplateRendering/Rendering/RenderText.js";
+// Only known text formats are rendered; all other files are copied unchanged.
+const textExtensions = new Set([
+    ".md",
+    ".txt",
+    ".json",
+    ".yml",
+    ".yaml",
+    ".toml",
+    ".sh",
+    ".ts",
+    ".js",
+    ".py",
+    ".php",
+    ".html",
+    ".css",
+    ".xml",
+    ".j2",
+    ".njk",
+    "",
+]);
+export async function exists(path) {
+    try {
+        await access(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export async function assertSafeInstallPaths(githubDirectory, blueprintNames, destinationDirectory = join(githubDirectory, "skills"), targetPath = (name) => join(destinationDirectory, name)) {
+    const installRoot = resolve(githubDirectory);
+    const paths = [
+        githubDirectory,
+        destinationDirectory,
+        join(githubDirectory, "spindle.json"),
+        ...blueprintNames.map(targetPath),
+    ];
+    for (const path of paths) {
+        const absolutePath = resolve(path);
+        const pathFromRoot = relative(installRoot, absolutePath);
+        if (pathFromRoot === ".." || pathFromRoot.startsWith(`..${sep}`) || isAbsolute(pathFromRoot)) {
+            throw new Error(`Refusing to write '${path}': target is outside .github.`);
+        }
+        let current = installRoot;
+        for (const segment of pathFromRoot === "" ? [] : pathFromRoot.split(sep)) {
+            current = join(current, segment);
+            try {
+                if ((await lstat(current)).isSymbolicLink()) {
+                    throw new Error(`Refusing to write through symbolic link '${current}'. Spindle writes only inside .github.`);
+                }
+            }
+            catch (error) {
+                if (error.code === "ENOENT")
+                    break;
+                throw error;
+            }
+        }
+        try {
+            if ((await lstat(path)).isSymbolicLink()) {
+                throw new Error("Refusing to write through symbolic link '" +
+                    path +
+                    "'. Spindle writes only inside .github.");
+            }
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+        }
+    }
+}
+export async function assertSingleFileDestination(path, mustExist = false) {
+    let stat;
+    try {
+        stat = await lstat(path);
+    }
+    catch (error) {
+        if (!mustExist && error.code === "ENOENT")
+            return;
+        throw error;
+    }
+    if (stat.isSymbolicLink()) {
+        throw new Error(`Refusing to replace symbolic link '${path}'.`);
+    }
+    if (!stat.isFile()) {
+        throw new Error(`Refusing to overwrite '${path}': expected a regular file.`);
+    }
+}
+export async function preparePlannedBlueprintFiles(files, context, validateRenderedFile, requireText = false) {
+    const prepared = [];
+    for (const file of files) {
+        const content = await readFile(file.sourcePath);
+        let text = null;
+        if (textExtensions.has(extname(file.sourcePath).toLowerCase()) && !content.includes(0)) {
+            try {
+                text = new TextDecoder("utf-8", { fatal: true }).decode(content);
+            }
+            catch {
+                // Invalid UTF-8 is not renderable text; preserve the original bytes below.
+            }
+        }
+        if (text === null && (typeof requireText === "function" ? requireText(file) : requireText)) {
+            throw new Error(`Blueprint entry '${file.outputPath}' must be valid UTF-8 text.`);
+        }
+        const renderedText = text === null ? null : renderText(text, context);
+        if (renderedText !== null)
+            validateRenderedFile?.(file.outputPath, renderedText);
+        prepared.push({ ...file, renderedText });
+    }
+    return prepared;
+}

package/build/BlueprintManagement/Types/Blueprint.js

@@ -0,0 +1 @@
+export {};

package/build/BlueprintManagement/Types/Installation.js

@@ -0,0 +1 @@
+export {};

package/build/BlueprintManagement/Types/Reconciliation.js

@@ -0,0 +1 @@
+export {};

package/build/BlueprintManagement/Versioning/BlueprintVersion.js

@@ -0,0 +1,70 @@
+import { readFile } from "node:fs/promises";
+import matter from "gray-matter";
+import { renderText } from "../../TemplateRendering/Rendering/RenderText.js";
+const semverPattern = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+[0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*)?$/;
+export function parseSemver(value) {
+    const match = semverPattern.exec(value);
+    if (!match)
+        return null;
+    return {
+        core: [BigInt(match[1]), BigInt(match[2]), BigInt(match[3])],
+        prerelease: match[4] ? match[4].split(".") : [],
+    };
+}
+function comparePrerelease(a, b) {
+    // A version without a prerelease outranks one with it.
+    if (a.length === 0 || b.length === 0)
+        return b.length - a.length;
+    for (let i = 0; i < Math.min(a.length, b.length); i++) {
+        const numA = /^\d+$/.test(a[i]);
+        const numB = /^\d+$/.test(b[i]);
+        if (numA && numB) {
+            const valueA = BigInt(a[i]);
+            const valueB = BigInt(b[i]);
+            if (valueA !== valueB)
+                return valueA < valueB ? -1 : 1;
+        }
+        else if (numA !== numB) {
+            return numA ? -1 : 1;
+        }
+        else if (a[i] !== b[i]) {
+            return a[i] < b[i] ? -1 : 1;
+        }
+    }
+    return Math.sign(a.length - b.length);
+}
+export function compareSemver(a, b) {
+    for (let i = 0; i < 3; i++) {
+        if (a.core[i] !== b.core[i])
+            return a.core[i] < b.core[i] ? -1 : 1;
+    }
+    return comparePrerelease(a.prerelease, b.prerelease);
+}
+// Returns the raw Spindle-owned version value from entry-file frontmatter, or null when absent or unreadable.
+export async function readBlueprintVersion(entryFile, context, options = {}) {
+    let content;
+    try {
+        content = await readFile(entryFile, "utf8");
+    }
+    catch {
+        return null;
+    }
+    const rendered = context
+        ? renderText(content, {
+            stacks: [...context.stacks],
+            variables: { ...context.variables },
+            computed: { ...context.computed },
+        })
+        : content;
+    if (context)
+        options.onRendered?.(content, rendered);
+    try {
+        const version = matter(rendered, {}).data.metadata?.spindle?.version;
+        return typeof version === "string" || typeof version === "number" ? String(version) : null;
+    }
+    catch (error) {
+        if (options.rejectMalformed)
+            throw error;
+        return null;
+    }
+}