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

package/build/BlueprintManagement/Commands/UpdateCommand.js

@@ -0,0 +1,86 @@
+import chalk from "chalk";
+import { BlueprintCommandOptions } from "./BlueprintCommandOptions.js";
+import { parseConflictPolicy } from "./ConflictPolicy.js";
+import { promptNewBlueprints, promptOutdated } from "./Prompts.js";
+import { blueprintHandlers } from "../Handlers/BlueprintHandlers.js";
+import { BlueprintReconciliationService } from "../Services/BlueprintReconciliationService.js";
+import { Command } from "../../Commands/Command.js";
+import { LoadProjectConfiguration } from "../../Foundation/Bootstrap/LoadProjectConfiguration.js";
+import { Stacks } from "../../Support/Stacks.js";
+export class UpdateCommand extends Command {
+    handlers = [];
+    reconciliationService;
+    static register(program, createApp) {
+        program
+            .command("update")
+            .description(`Re-render installed Blueprints (Skills, Agents, and Instructions) whose shipped version is newer.
+Reads stacks and the Spindle package-manager command from .github/spindle.json and leaves it unchanged.
+New shipped Blueprints are offered interactively; use
+--include-new to install all of them without a prompt.`)
+            .addOption(BlueprintCommandOptions.conflictPolicyOption("Policy for outdated Blueprints"))
+            .addOption(BlueprintCommandOptions.noInteractiveOption("Never prompt; outdated Blueprints without --on-conflict are an error"))
+            .option("--include-new", "Install every newly shipped Blueprint without prompting")
+            .addHelpText("after", `
+Requires .github/spindle.json; run \`spindle init\` first.
+Installed Blueprints with a missing or non-semver version are skipped with a warning.
+`)
+            .allowExcessArguments(false)
+            .action(async (options) => {
+            const interactive = options.interactive && Boolean(process.stdin.isTTY) && Boolean(process.stdout.isTTY);
+            const policy = parseConflictPolicy(options.onConflict);
+            await (await (await createApp()).make(UpdateCommand)).run(interactive, policy, options.includeNew);
+        });
+    }
+    constructor(app) {
+        super(app);
+    }
+    async boot() {
+        this.handlers = blueprintHandlers;
+        this.reconciliationService = await this.app.make(BlueprintReconciliationService);
+    }
+    async run(interactive, policy, includeNew = false) {
+        this.assertApplicationBooted();
+        const config = LoadProjectConfiguration.require(await LoadProjectConfiguration.refresh(this.app));
+        if (config.stacks.length === 0) {
+            throw new Error(`No Blueprint stacks are configured. Run \`spindle init --stack <${Stacks.supported.join("|")}>\` first.`);
+        }
+        const spindlePackageManager = config.config.spindle_package_manager;
+        if (spindlePackageManager === undefined) {
+            throw new Error('Missing "spindle_package_manager" in .github/spindle.json; add the preferred Spindle package-manager command before running `spindle update`.');
+        }
+        const outcomes = await this.reconciliationService.reconcile(this.handlers, {
+            mode: "update",
+            config: config.config,
+            includeNew,
+            chooseNew: interactive && !includeNew ? promptNewBlueprints : undefined,
+            conflictPolicy: policy,
+            chooseConflict: interactive && policy === undefined
+                ? async (kind, name, installed, available) => promptOutdated(kind, name, installed, available)
+                : undefined,
+            resolveContext: async () => ({
+                stacks: config.stacks,
+                variables: {},
+            }),
+        });
+        await LoadProjectConfiguration.refresh(this.app);
+        for (const outcome of outcomes) {
+            if (outcome.warning) {
+                console.error(chalk.yellow(outcome.warning));
+            }
+        }
+        for (const outcome of outcomes.filter((item) => item.status === "removed")) {
+            console.log(`${chalk.green("✔")} Removed ${outcome.kind.toLowerCase()} '${outcome.name}'`);
+        }
+        if (outcomes.length === 0) {
+            console.log(`${chalk.green("✔")} No Blueprints apply to the selected stacks`);
+        }
+        for (const kind of new Set(outcomes.map((outcome) => outcome.kind))) {
+            const ofKind = outcomes.filter((outcome) => outcome.kind === kind);
+            const added = ofKind.filter((outcome) => outcome.status === "installed").length;
+            const updated = ofKind.filter((outcome) => outcome.status === "updated").length;
+            const skipped = ofKind.filter((outcome) => outcome.status === "skipped").length;
+            const upToDate = ofKind.filter((outcome) => outcome.status === "up-to-date").length;
+            console.log(`${chalk.green("✔")} Added ${added}, updated ${updated}, skipped ${skipped}, up to date ${upToDate} ${kind.toLowerCase()}(s)`);
+        }
+    }
+}

package/build/BlueprintManagement/Handlers/Agents/AgentHandler.js

@@ -0,0 +1,21 @@
+import { join } from "node:path";
+import { planVersionedUpdate, validateVersionedMetadata, } from "../../Versioning/BlueprintVersioning.js";
+export const agentHandler = {
+    kind: "Agent",
+    catalogKind: "agents",
+    sourceDirectory: (blueprintSourceRoot) => join(blueprintSourceRoot, "agents"),
+    destinationDirectory: (githubDirectory) => join(githubDirectory, "agents"),
+    fileTarget: true,
+    targetPath: (destinationDirectory, name) => join(destinationDirectory, name),
+    validateMetadata: (relativePath, renderedText) => {
+        if (relativePath.toLowerCase().endsWith(".md")) {
+            validateVersionedMetadata("Agent", relativePath, relativePath, renderedText);
+        }
+    },
+    planUpdate: (input) => {
+        const entry = input.sourceFiles[0].outputPath;
+        return entry.toLowerCase().endsWith(".md")
+            ? planVersionedUpdate(input, "Agent", entry, (target) => target, "warning")
+            : Promise.resolve({ status: input.installed ? "conflict" : "new" });
+    },
+};

package/build/BlueprintManagement/Handlers/BlueprintHandlers.js

@@ -0,0 +1,4 @@
+import { agentHandler } from "./Agents/AgentHandler.js";
+import { instructionHandler } from "./Instructions/InstructionHandler.js";
+import { skillHandler } from "./Skills/SkillHandler.js";
+export const blueprintHandlers = [skillHandler, agentHandler, instructionHandler];

package/build/BlueprintManagement/Handlers/Instructions/InstructionHandler.js

@@ -0,0 +1,21 @@
+import { join } from "node:path";
+import { planVersionedUpdate, validateVersionedMetadata, } from "../../Versioning/BlueprintVersioning.js";
+export const instructionHandler = {
+    kind: "Instruction",
+    catalogKind: "instructions",
+    sourceDirectory: (blueprintSourceRoot) => join(blueprintSourceRoot, "instructions"),
+    destinationDirectory: (githubDirectory) => join(githubDirectory, "instructions"),
+    fileTarget: true,
+    targetPath: (destinationDirectory, name) => join(destinationDirectory, name),
+    validateMetadata: (relativePath, renderedText) => {
+        if (relativePath.toLowerCase().endsWith(".md")) {
+            validateVersionedMetadata("Instruction", relativePath, relativePath, renderedText);
+        }
+    },
+    planUpdate: (input) => {
+        const entry = input.sourceFiles[0].outputPath;
+        return entry.toLowerCase().endsWith(".md")
+            ? planVersionedUpdate(input, "Instruction", entry, (target) => target, "warning")
+            : Promise.resolve({ status: input.installed ? "conflict" : "new" });
+    },
+};

package/build/BlueprintManagement/Handlers/Skills/SkillHandler.js

@@ -0,0 +1,10 @@
+import { join } from "node:path";
+import { planVersionedUpdate, validateVersionedMetadata, } from "../../Versioning/BlueprintVersioning.js";
+export const skillHandler = {
+    kind: "Skill",
+    catalogKind: "skills",
+    sourceDirectory: (blueprintSourceRoot) => join(blueprintSourceRoot, "skills"),
+    destinationDirectory: (githubDirectory) => join(githubDirectory, "skills"),
+    validateMetadata: (relativePath, renderedText) => validateVersionedMetadata("Skill", "SKILL.md", relativePath, renderedText),
+    planUpdate: (input) => planVersionedUpdate(input, "Skill", "SKILL.md", (target) => join(target, "SKILL.md"), "error"),
+};

package/build/BlueprintManagement/Reconciliation/BlueprintCatalogPlanner.js

@@ -0,0 +1,87 @@
+import { lstat, readdir } from "node:fs/promises";
+import { join, relative, sep } from "node:path";
+import { planBlueprintCatalog, blueprintCatalog, validateBlueprintCatalog, } from "../Catalog/BlueprintCatalog.js";
+import { assertSafeInstallPaths } from "../Support/BlueprintFiles.js";
+async function collectDestinationFiles(directory, result = []) {
+    let directoryStat;
+    try {
+        directoryStat = await lstat(directory);
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return result;
+        throw error;
+    }
+    if (directoryStat.isSymbolicLink()) {
+        throw new Error(`Refusing to reconcile selected directory '${directory}': symbolic-link traversal is unsafe.`);
+    }
+    if (!directoryStat.isDirectory()) {
+        throw new Error(`Refusing to reconcile selected directory '${directory}': expected a directory.`);
+    }
+    for (const entry of (await readdir(directory)).sort()) {
+        const path = join(directory, entry);
+        const stat = await lstat(path);
+        if (stat.isSymbolicLink()) {
+            throw new Error(`Refusing to reconcile selected directory '${directory}': symbolic link '${path}' is unsafe.`);
+        }
+        if (stat.isDirectory()) {
+            await collectDestinationFiles(path, result);
+        }
+        else if (stat.isFile()) {
+            result.push(path);
+        }
+        else {
+            throw new Error(`Refusing to reconcile selected directory '${directory}': '${path}' is not a regular file or directory.`);
+        }
+    }
+    return result;
+}
+export async function planBlueprintCatalogReconciliation(handlers, githubDirectory, blueprintSourceRoot, selectedStacks) {
+    const catalog = validateBlueprintCatalog(blueprintCatalog);
+    const handlerPlans = [];
+    for (const handler of handlers) {
+        const expansion = await planBlueprintCatalog(catalog, handler.catalogKind, handler.sourceDirectory(blueprintSourceRoot), selectedStacks);
+        const destinationDirectory = handler.destinationDirectory(githubDirectory);
+        const deletions = expansion.deletions.map((deletion) => ({
+            kind: handler.kind,
+            catalogKind: handler.catalogKind,
+            key: deletion.entry.key,
+            path: deletion.path,
+            target: handler.targetPath?.(destinationDirectory, deletion.path) ??
+                join(destinationDirectory, deletion.path),
+            directory: deletion.entry.directory,
+            reason: deletion.reason,
+        }));
+        const membershipCleanup = [];
+        for (const directory of expansion.directories) {
+            const directoryTarget = handler.targetPath?.(destinationDirectory, directory.path) ??
+                join(destinationDirectory, directory.path);
+            await assertSafeInstallPaths(githubDirectory, [directory.path], destinationDirectory, (name) => handler.targetPath?.(destinationDirectory, name) ?? join(destinationDirectory, name));
+            const sourceFiles = new Set(directory.sourceFiles);
+            const installedFiles = await collectDestinationFiles(directoryTarget);
+            for (const installedFile of installedFiles) {
+                const relativePath = relative(directoryTarget, installedFile).split(sep).join("/");
+                if (sourceFiles.has(relativePath))
+                    continue;
+                const path = `${directory.path}/${relativePath}`;
+                membershipCleanup.push({
+                    kind: handler.kind,
+                    catalogKind: handler.catalogKind,
+                    key: directory.entry.key,
+                    path,
+                    target: handler.targetPath?.(destinationDirectory, path) ?? join(destinationDirectory, path),
+                    directory: false,
+                    reason: "directory-membership",
+                });
+            }
+        }
+        handlerPlans.push({
+            handler,
+            selections: expansion.selections,
+            catalogDeletions: expansion.deletions,
+            deletions,
+            membershipCleanup,
+        });
+    }
+    return handlerPlans;
+}

package/build/BlueprintManagement/Reconciliation/BlueprintRemovalCoordinator.js

@@ -0,0 +1,78 @@
+import { lstat, rm } from "node:fs/promises";
+import { join } from "node:path";
+import { assertSafeInstallPaths } from "../Support/BlueprintFiles.js";
+export async function validateRemovalTarget(githubDirectory, operation) {
+    const { handler, plan, expectedTarget } = operation;
+    const destinationDirectory = handler.destinationDirectory(githubDirectory);
+    const targetPath = (name) => handler.targetPath?.(destinationDirectory, name) ?? join(destinationDirectory, name);
+    await assertSafeInstallPaths(githubDirectory, [plan.path], destinationDirectory, targetPath);
+    try {
+        const stat = await lstat(plan.target);
+        if (stat.isSymbolicLink()) {
+            throw new Error(`Refusing to remove '${plan.target}': symbolic-link targets are unsafe.`);
+        }
+        if (expectedTarget === "directory" ? !stat.isDirectory() : !stat.isFile()) {
+            const expected = expectedTarget === "directory" ? "a directory" : "a regular file";
+            throw new Error(`Refusing to remove '${plan.target}': expected ${expected}.`);
+        }
+        return true;
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return false;
+        throw error;
+    }
+}
+export function catalogRemovalOperation(operation) {
+    const { handler, deletion, plan } = operation;
+    const name = `${handler.kind} '${deletion.path}'`;
+    return {
+        handler,
+        plan,
+        expectedTarget: deletion.entry.directory ? "directory" : "file",
+        recursive: deletion.entry.directory,
+        validationDescription: `removal of ${name}`,
+        removalDescription: name,
+        completedName: name,
+    };
+}
+export function membershipRemovalOperation(operation) {
+    const { handler, plan } = operation;
+    const name = `${handler.kind} '${plan.path}'`;
+    return {
+        handler,
+        plan,
+        expectedTarget: "file",
+        recursive: false,
+        validationDescription: `directory-membership cleanup of ${name}`,
+        removalDescription: `destination-only ${handler.kind} file '${plan.path}'`,
+        completedName: name,
+    };
+}
+export async function applyRemovalOperations(githubDirectory, operations, recordAppliedChange) {
+    const outcomes = [];
+    for (const operation of operations) {
+        let targetExists;
+        try {
+            targetExists = await validateRemovalTarget(githubDirectory, operation);
+        }
+        catch (error) {
+            throw new Error(`Failed to validate ${operation.validationDescription} at '${operation.plan.target}': ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+        }
+        if (!targetExists)
+            continue;
+        try {
+            await rm(operation.plan.target, { recursive: operation.recursive });
+        }
+        catch (error) {
+            throw new Error(`Failed to remove ${operation.removalDescription} at '${operation.plan.target}': ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+        }
+        recordAppliedChange(`removed ${operation.completedName}`);
+        outcomes.push({
+            kind: operation.handler.kind,
+            name: operation.plan.path,
+            status: "removed",
+        });
+    }
+    return outcomes;
+}