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

package/build/BlueprintManagement/Versioning/BlueprintVersioning.js

@@ -0,0 +1,55 @@
+import { basename } from "node:path";
+import matter from "gray-matter";
+import { compareSemver, parseSemver, readBlueprintVersion, } from "./BlueprintVersion.js";
+export function validateVersionedMetadata(kind, entryFile, relativePath, renderedText) {
+    if (relativePath !== entryFile)
+        return;
+    const version = matter(renderedText).data.metadata?.spindle?.version;
+    if (typeof version !== "string" || parseSemver(version) === null) {
+        throw new Error(`Invalid ${kind} metadata in '${relativePath}': expected a semver \`metadata.spindle.version\` in frontmatter.`);
+    }
+}
+export async function planVersionedUpdate(input, kind, entryFile, installedFile, malformedInstalledMetadata) {
+    const { name, sourceFiles, target, installed, resolveContext } = input;
+    const source = sourceFiles.find((file) => file.outputPath === entryFile)?.sourcePath;
+    const context = source === undefined ? undefined : await resolveContext();
+    if (source !== undefined && context === undefined) {
+        throw new Error(`Cannot render the shipped ${kind.toLowerCase()} Blueprint '${name}' without resolved project Variables.`);
+    }
+    let renderedEntry;
+    const shipped = source === undefined
+        ? null
+        : await readBlueprintVersion(source, context, {
+            onRendered: (sourceText, renderedText) => {
+                renderedEntry = { sourcePath: source, outputPath: entryFile, sourceText, renderedText };
+            },
+        });
+    const shippedVersion = shipped === null ? null : parseSemver(shipped);
+    if (shipped === null || shippedVersion === null) {
+        throw new Error(`The shipped ${kind.toLowerCase()} Blueprint '${name}' has no valid semver version in its ${entryFile}.`);
+    }
+    if (!installed)
+        return { status: "new", renderedEntry };
+    const installedPath = installedFile(target);
+    const installedText = await readBlueprintVersion(installedPath, undefined, {
+        rejectMalformed: malformedInstalledMetadata === "error",
+    });
+    const installedVersion = installedText === null ? null : parseSemver(installedText);
+    if (installedText === null || installedVersion === null) {
+        const description = installedText === null ? "no version" : `non-semver version '${installedText}'`;
+        return {
+            status: "warning",
+            warning: `Skipping ${kind} '${name}': installed ${basename(installedPath)} has ${description}.`,
+        };
+    }
+    if (compareSemver(shippedVersion, installedVersion) > 0) {
+        return {
+            status: "update",
+            installedVersion: installedText,
+            availableVersion: shipped,
+            versionedEntry: source === undefined ? undefined : { sourcePath: source, outputPath: entryFile },
+            renderedEntry,
+        };
+    }
+    return { status: "up-to-date" };
+}

package/build/Commands/Command.js

@@ -0,0 +1,3 @@
+import { Service } from "../Foundation/Service.js";
+export class Command extends Service {
+}

package/build/Commands/CommandOptions.js

@@ -0,0 +1,12 @@
+export class CommandOptions {
+    static once(option) {
+        let seen = false;
+        return (value) => {
+            if (seen) {
+                throw new Error(`Option '${option}' may only be provided once.`);
+            }
+            seen = true;
+            return value;
+        };
+    }
+}

package/build/Config/Config.js

@@ -0,0 +1,3 @@
+import { Repository } from "../Support/Repository.js";
+export class Config extends Repository {
+}

package/build/Foundation/Application.js

@@ -0,0 +1,112 @@
+import { isAbsolute, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { Config } from "../Config/Config.js";
+import { ApplicationBuilder } from "./ApplicationBuilder.js";
+import { Container } from "./Container.js";
+import { FoundationServiceProvider } from "./FoundationServiceProvider.js";
+import { GitServiceProvider } from "../Git/GitServiceProvider.js";
+export class Application extends Container {
+    config = new Config();
+    _basePath;
+    providers = new Map();
+    commands = new Set();
+    selectedBootstrapProviders;
+    bootableProviders = [];
+    bootstrapPromise;
+    _hasBeenBootstrapped = false;
+    bootPromise;
+    _hasBeenBooted = false;
+    constructor({ basePath }) {
+        super();
+        this._basePath = resolve(basePath);
+        this.instance("path.base", this._basePath);
+        this.registerBaseBindings();
+        this.registerBaseServiceProviders();
+    }
+    get owner() {
+        return this;
+    }
+    static configure(basePath, providers = []) {
+        return new ApplicationBuilder(new Application({ basePath }))
+            .withKernels()
+            .withProviders(providers);
+    }
+    joinPaths(basePath, path = "") {
+        if (path === "")
+            return basePath;
+        return isAbsolute(path) ? path : join(basePath, path);
+    }
+    workspacePath(path = "") {
+        return this.joinPaths(this.workspaceRoot, path);
+    }
+    appPath(path = "") {
+        return this.joinPaths(fileURLToPath(new URL("../", import.meta.url)), path);
+    }
+    basePath(path = "") {
+        return this.joinPaths(this._basePath, path);
+    }
+    get workspaceRoot() {
+        return this.stringValue("path.workspace");
+    }
+    get hasBeenBootstrapped() {
+        return this._hasBeenBootstrapped;
+    }
+    get hasBeenBooted() {
+        return this._hasBeenBooted;
+    }
+    selectBootstrapProviders(providers) {
+        this.selectedBootstrapProviders = [...new Set(providers)];
+    }
+    bootstrapProviders(fallback) {
+        return this.selectedBootstrapProviders ?? fallback;
+    }
+    register(Provider) {
+        if (this.providers.has(Provider))
+            return;
+        const provider = new Provider(this);
+        this.providers.set(Provider, provider);
+        for (const Command of Provider.commands()) {
+            if (!this.commands.has(Command)) {
+                this.singleton(Command);
+                this.commands.add(Command);
+            }
+        }
+        provider.register();
+        this.bootableProviders.push(provider);
+    }
+    async bootstrapWith(bootstrappers) {
+        if (!this.bootstrapPromise) {
+            const constructors = [...bootstrappers];
+            this.bootstrapPromise = Promise.resolve().then(async () => {
+                for (const Bootstrapper of constructors)
+                    await new Bootstrapper().bootstrap(this);
+                this._hasBeenBootstrapped = true;
+            });
+        }
+        await this.bootstrapPromise;
+    }
+    async boot() {
+        this.bootPromise ??= Promise.resolve().then(async () => {
+            for (const provider of this.bootableProviders)
+                await provider.boot();
+            this._hasBeenBooted = true;
+        });
+        await this.bootPromise;
+    }
+    registerBaseBindings() {
+        this.instance("app", this);
+        this.instance(Application, this);
+        this.instance(Container, this);
+    }
+    registerBaseServiceProviders() {
+        this.register(FoundationServiceProvider);
+        this.register(GitServiceProvider);
+    }
+    stringValue(key) {
+        const value = this.value(key);
+        if (typeof value !== "string") {
+            throw new Error(`Application path '${key}' must be a string.`);
+        }
+        return value;
+    }
+}

package/build/Foundation/ApplicationBuilder.js

@@ -0,0 +1,23 @@
+import { RegisterProviders } from "./Bootstrap/RegisterProviders.js";
+import { Kernel } from "./Kernel.js";
+export class ApplicationBuilder {
+    application;
+    kernelsRegistered = false;
+    constructor(application) {
+        this.application = application;
+    }
+    withKernels() {
+        if (!this.kernelsRegistered) {
+            this.application.singleton(Kernel, (application) => new Kernel(application));
+            this.kernelsRegistered = true;
+        }
+        return this;
+    }
+    withProviders(providers = []) {
+        RegisterProviders.merge(providers);
+        return this;
+    }
+    create() {
+        return this.application;
+    }
+}

package/build/Foundation/Bootstrap/Bootstrapper.js

@@ -0,0 +1,2 @@
+export class Bootstrapper {
+}

package/build/Foundation/Bootstrap/DiscoverGitRoot.js

@@ -0,0 +1,8 @@
+import { Bootstrapper } from "./Bootstrapper.js";
+import { GitService } from "../../Git/Services/GitService.js";
+export class DiscoverGitRoot extends Bootstrapper {
+    async bootstrap(application) {
+        const git = await application.make(GitService);
+        application.instance("path.workspace", git.discoverRoot(application.basePath()));
+    }
+}

package/build/Foundation/Bootstrap/LoadConsoleArgs.js

@@ -0,0 +1,47 @@
+import { Bootstrapper } from "./Bootstrapper.js";
+import { Repository } from "../../Support/Repository.js";
+function isStringArray(value) {
+    if (!Array.isArray(value))
+        return false;
+    for (const item of value) {
+        if (typeof item !== "string")
+            return false;
+    }
+    return true;
+}
+function isOptions(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        !Array.isArray(value) &&
+        (Object.getPrototypeOf(value) === Object.prototype || Object.getPrototypeOf(value) === null));
+}
+function isConsoleInvocation(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        "raw" in value &&
+        "script" in value &&
+        "commandPath" in value &&
+        "options" in value &&
+        "positionals" in value &&
+        isStringArray(value.raw) &&
+        typeof value.script === "string" &&
+        isStringArray(value.commandPath) &&
+        isOptions(value.options) &&
+        isStringArray(value.positionals));
+}
+export class LoadConsoleArgs extends Bootstrapper {
+    bootstrap(application) {
+        const value = application.value("console.invocation");
+        if (!isConsoleInvocation(value)) {
+            throw new Error("Console invocation must include valid raw, script, command, options, and positional data.");
+        }
+        const invocation = value;
+        const args = new Repository();
+        args.set("raw", invocation.raw);
+        args.set("script", invocation.script);
+        args.set("commandPath", invocation.commandPath);
+        args.set("options", invocation.options);
+        args.set("positionals", invocation.positionals);
+        application.instance("console.args", args);
+    }
+}

package/build/Foundation/Bootstrap/LoadProjectConfiguration.js

@@ -0,0 +1,144 @@
+import { readFile } from "node:fs/promises";
+import { Bootstrapper } from "./Bootstrapper.js";
+import { Records } from "../../Support/Records.js";
+import { Stacks } from "../../Support/Stacks.js";
+const malformed = '.github/spindle.json is malformed; expected {"stacks": [...], "spindle_package_manager"?: string, "tooling"?: [...]}. Fix the file or run `spindle init`.';
+export class LoadProjectConfiguration extends Bootstrapper {
+    static parse(raw) {
+        let data;
+        try {
+            data = JSON.parse(raw);
+        }
+        catch (error) {
+            if (!(error instanceof Error))
+                throw error;
+            return {
+                status: "invalid",
+                data: raw,
+                error,
+                reason: ".github/spindle.json is not valid JSON.",
+            };
+        }
+        if (!this.isConfiguration(data)) {
+            return { status: "invalid", data, error: new Error(malformed), reason: malformed };
+        }
+        if (data.stacks.length > 0) {
+            try {
+                Stacks.validate(data.stacks);
+            }
+            catch (error) {
+                if (!(error instanceof Error))
+                    throw error;
+                return { status: "invalid", data, error, reason: error.message };
+            }
+        }
+        return { status: "valid", data };
+    }
+    static async load(path) {
+        let raw;
+        try {
+            raw = await readFile(path, "utf8");
+        }
+        catch (error) {
+            if (Records.isRecord(error) && error.code === "ENOENT")
+                return { status: "absent" };
+            throw error;
+        }
+        return this.parse(raw);
+    }
+    static current(application) {
+        const state = application.value("config.project");
+        if (Records.isRecord(state)) {
+            if (state.status === "absent")
+                return { status: "absent" };
+            if (state.status === "valid" && this.isConfiguration(state.data)) {
+                return { status: "valid", data: state.data };
+            }
+            if (state.status === "invalid" &&
+                state.error instanceof Error &&
+                typeof state.reason === "string") {
+                return { status: "invalid", data: state.data, error: state.error, reason: state.reason };
+            }
+        }
+        throw new Error("Application binding 'config.project' must contain a project configuration state.");
+    }
+    static async withTemporaryState(application, state, operation) {
+        this.current(application);
+        const current = application.value("config.project");
+        if (!Records.isRecord(current)) {
+            throw new Error("Application binding 'config.project' must contain a project configuration state.");
+        }
+        const previous = { ...current };
+        const replace = (replacement) => {
+            for (const key of Object.keys(current))
+                delete current[key];
+            Object.assign(current, replacement);
+        };
+        replace(state);
+        try {
+            return await operation();
+        }
+        finally {
+            replace(previous);
+        }
+    }
+    static require(state) {
+        if (state.status === "absent") {
+            throw new Error("This repository has no .github/spindle.json. Run `spindle init` to create .github/spindle.json.");
+        }
+        if (state.status === "invalid") {
+            if (state.reason.startsWith("Invalid stack '"))
+                throw state.error;
+            throw new Error(`${state.reason} Run \`spindle init\` to create .github/spindle.json.`);
+        }
+        return { config: state.data, stacks: state.data.stacks };
+    }
+    static requireCurrent(application) {
+        return this.require(this.current(application));
+    }
+    static async refresh(application) {
+        const state = await this.load(application.workspacePath(".github/spindle.json"));
+        if (application.bound("config.project")) {
+            const current = application.value("config.project");
+            if (!Records.isRecord(current)) {
+                throw new Error("Application binding 'config.project' must contain a project configuration state.");
+            }
+            for (const key of Object.keys(current))
+                delete current[key];
+            Object.assign(current, state);
+        }
+        else {
+            application.instance("config.project", state);
+        }
+        return state;
+    }
+    async bootstrap(application) {
+        await LoadProjectConfiguration.refresh(application);
+    }
+    static isConfiguration(value) {
+        return (Records.isRecord(value) &&
+            Array.isArray(value.stacks) &&
+            value.stacks.every((stack) => typeof stack === "string") &&
+            (value.spindle_package_manager === undefined ||
+                (typeof value.spindle_package_manager === "string" &&
+                    this.isSingleLine(value.spindle_package_manager))) &&
+            (value.tooling === undefined ||
+                (Array.isArray(value.tooling) &&
+                    value.tooling.every((entry) => this.isToolingEntry(entry)) &&
+                    new Set(value.tooling.map((entry) => entry.key)).size === value.tooling.length)));
+    }
+    static isToolingEntry(value) {
+        return (Records.isRecord(value) &&
+            typeof value.key === "string" &&
+            /^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/.test(value.key) &&
+            typeof value.section === "string" &&
+            this.isSingleLine(value.section) &&
+            typeof value.command === "string" &&
+            this.isSingleLine(value.command) &&
+            (value.description === undefined ||
+                (typeof value.description === "string" && this.isSingleLine(value.description))));
+    }
+    static isSingleLine(text) {
+        return text.trim().length > 0 && !/[\r\n]/.test(text);
+    }
+}

package/build/Foundation/Bootstrap/RegisterProviders.js

@@ -0,0 +1,12 @@
+import { Bootstrapper } from "./Bootstrapper.js";
+export class RegisterProviders extends Bootstrapper {
+    static providers = [];
+    static merge(providers) {
+        this.providers = [...new Set(providers.filter((provider) => provider != null))];
+    }
+    bootstrap(application) {
+        for (const Provider of application.bootstrapProviders(RegisterProviders.providers)) {
+            application.register(Provider);
+        }
+    }
+}

package/build/Foundation/Bootstrap/RequireProjectConfiguration.js

@@ -0,0 +1,14 @@
+import { Bootstrapper } from "./Bootstrapper.js";
+import { LoadProjectConfiguration } from "./LoadProjectConfiguration.js";
+import { Repository } from "../../Support/Repository.js";
+export class RequireProjectConfiguration extends Bootstrapper {
+    bootstrap(application) {
+        const args = application.value("console.args");
+        if (!(args instanceof Repository)) {
+            throw new Error("Console arguments must be loaded before requiring project Config.");
+        }
+        if (args.array("commandPath")[0] === "init")
+            return;
+        LoadProjectConfiguration.requireCurrent(application);
+    }
+}

package/build/Foundation/ConsoleInvocation.js

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

package/build/Foundation/Container.js

@@ -0,0 +1,185 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { bootService, Service } from "./Service.js";
+function isClassConstructor(value) {
+    return (typeof value === "function" &&
+        /^class(?:\s|\{)/.test(Function.prototype.toString.call(value)) &&
+        typeof value.prototype === "object");
+}
+function normalizeKey(key) {
+    if (typeof key === "string") {
+        if (key.length === 0)
+            throw new TypeError("Dependency keys must be non-empty strings.");
+        return { name: key };
+    }
+    if (!isClassConstructor(key)) {
+        throw new TypeError("Dependency keys must be strings or class constructors.");
+    }
+    if (key.name.length === 0) {
+        throw new TypeError("Class dependency keys must have a name.");
+    }
+    return { name: key.name, classKey: key };
+}
+function isServiceConstructor(key) {
+    return key === Service || key.prototype instanceof Service;
+}
+export class Container {
+    bindings = new Map();
+    singletons = new Map();
+    inFlight = new Map();
+    resolution = new AsyncLocalStorage();
+    bind(key, factory) {
+        this.registerFactory(key, "transient", factory);
+    }
+    singleton(key, factory) {
+        this.registerFactory(key, "singleton", factory);
+    }
+    instance(key, value) {
+        const normalized = normalizeKey(key);
+        this.assertUnbound(normalized);
+        this.assertInstanceType(normalized, value);
+        if (value instanceof Service && !value.isBooted) {
+            throw new Error(`Supplied service instance '${normalized.name}' must already be booted.`);
+        }
+        this.bindings.set(normalized.name, {
+            kind: "instance",
+            value,
+            classKey: normalized.classKey,
+        });
+    }
+    bound(key) {
+        return this.bindings.has(normalizeKey(key).name);
+    }
+    value(key) {
+        const normalized = normalizeKey(key);
+        const binding = this.binding(normalized);
+        if (binding.kind !== "instance") {
+            throw new Error(`Value '${normalized.name}' must be registered as an instance for synchronous access.`);
+        }
+        return binding.value;
+    }
+    async make(key) {
+        const normalized = normalizeKey(key);
+        const binding = this.binding(normalized);
+        if (binding.kind === "instance") {
+            this.assertInstanceType(normalized, binding.value);
+            return binding.value;
+        }
+        if (this.singletons.has(normalized.name)) {
+            const value = this.singletons.get(normalized.name);
+            this.assertInstanceType(normalized, value);
+            return value;
+        }
+        const chain = this.resolution.getStore() ?? [];
+        this.assertNoAncestorCycle(normalized.name, chain);
+        let initialization = binding.kind === "singleton" ? this.inFlight.get(normalized.name) : undefined;
+        if (!initialization) {
+            const token = { key: normalized.name, dependencies: new Map() };
+            const promise = Promise.resolve().then(() => this.constructAndBoot(token, chain, binding.factory, normalized.classKey));
+            initialization = { token, promise };
+            if (binding.kind === "singleton") {
+                this.inFlight.set(normalized.name, initialization);
+                void promise.then((initialized) => {
+                    if (this.inFlight.get(normalized.name)?.promise === promise) {
+                        this.singletons.set(normalized.name, initialized);
+                        this.inFlight.delete(normalized.name);
+                    }
+                }, () => {
+                    if (this.inFlight.get(normalized.name)?.promise === promise) {
+                        this.inFlight.delete(normalized.name);
+                    }
+                });
+            }
+        }
+        const unlink = this.linkDependency(chain.at(-1), initialization.token);
+        try {
+            const value = await initialization.promise;
+            this.assertInstanceType(normalized, value);
+            return value;
+        }
+        finally {
+            unlink();
+        }
+    }
+    binding(key) {
+        const binding = this.bindings.get(key.name);
+        if (!binding)
+            throw new Error(`Unbound dependency: ${key.name}.`);
+        if (key.classKey && binding.classKey && key.classKey !== binding.classKey) {
+            throw new Error(`Dependency '${key.name}' is bound to a different constructor.`);
+        }
+        return binding;
+    }
+    assertUnbound(key) {
+        if (this.bindings.has(key.name)) {
+            throw new Error(`Dependency '${key.name}' is already bound.`);
+        }
+    }
+    assertInstanceType(key, value) {
+        if (key.classKey && !(value instanceof key.classKey)) {
+            throw new Error(`Dependency '${key.name}' did not produce an instance of its class key.`);
+        }
+    }
+    registerFactory(key, kind, factory) {
+        const normalized = normalizeKey(key);
+        this.assertUnbound(normalized);
+        if (!factory) {
+            if (!normalized.classKey || !isServiceConstructor(normalized.classKey)) {
+                throw new Error(`Dependency '${normalized.name}' requires an explicit factory.`);
+            }
+            const ServiceType = normalized.classKey;
+            factory = (application) => new ServiceType(application);
+        }
+        this.bindings.set(normalized.name, {
+            kind,
+            factory,
+            classKey: normalized.classKey,
+        });
+    }
+    assertNoAncestorCycle(key, chain) {
+        const start = chain.findIndex((token) => token.key === key);
+        if (start >= 0) {
+            throw new Error(`Circular service dependency: ${[...chain.slice(start).map((token) => token.key), key].join(" -> ")}`);
+        }
+    }
+    linkDependency(parent, target) {
+        if (!parent)
+            return () => { };
+        const path = this.findPath(target, parent);
+        if (path) {
+            throw new Error(`Circular service dependency: ${[parent, ...path].map((token) => token.key).join(" -> ")}`);
+        }
+        parent.dependencies.set(target, (parent.dependencies.get(target) ?? 0) + 1);
+        return () => {
+            const references = parent.dependencies.get(target);
+            if (references === 1)
+                parent.dependencies.delete(target);
+            else if (references !== undefined)
+                parent.dependencies.set(target, references - 1);
+        };
+    }
+    findPath(start, target) {
+        const visit = (current, visited) => {
+            if (current === target)
+                return [current];
+            if (visited.has(current))
+                return undefined;
+            visited.add(current);
+            for (const dependency of current.dependencies.keys()) {
+                const path = visit(dependency, visited);
+                if (path)
+                    return [current, ...path];
+            }
+            return undefined;
+        };
+        return visit(start, new Set());
+    }
+    async constructAndBoot(token, parentChain, factory, constructor) {
+        return this.resolution.run([...parentChain, token], async () => {
+            const value = await factory(this.owner);
+            this.assertInstanceType({ name: token.key, classKey: constructor }, value);
+            if (value instanceof Service && !value.isBooted)
+                await bootService(value);
+            return value;
+        });
+    }
+}

package/build/Foundation/FoundationServiceProvider.js

@@ -0,0 +1,5 @@
+import { ServiceProvider } from "./ServiceProvider.js";
+export class FoundationServiceProvider extends ServiceProvider {
+    register() { }
+    async boot() { }
+}

package/build/Foundation/Kernel.js

@@ -0,0 +1,30 @@
+import { DiscoverGitRoot } from "./Bootstrap/DiscoverGitRoot.js";
+import { LoadConsoleArgs } from "./Bootstrap/LoadConsoleArgs.js";
+import { LoadProjectConfiguration } from "./Bootstrap/LoadProjectConfiguration.js";
+import { RegisterProviders } from "./Bootstrap/RegisterProviders.js";
+import { RequireProjectConfiguration } from "./Bootstrap/RequireProjectConfiguration.js";
+export class Kernel {
+    app;
+    constructor(app) {
+        this.app = app;
+    }
+    bootstrappers() {
+        return [
+            LoadConsoleArgs,
+            DiscoverGitRoot,
+            LoadProjectConfiguration,
+            RequireProjectConfiguration,
+            RegisterProviders,
+        ];
+    }
+    async bootstrap() {
+        await this.app.bootstrapWith(this.bootstrappers());
+    }
+    async boot(invocation) {
+        if (!this.app.bound("console.invocation")) {
+            this.app.instance("console.invocation", invocation);
+        }
+        await this.bootstrap();
+        await this.app.boot();
+    }
+}