@decohere/devkit 0.0.1-dev.119

package/es6/src/cli/command.js

@@ -0,0 +1,106 @@
+import { Command as CommanderType } from "commander";
+export const CommandResponse = {
+    success (_ctx, responses) {
+        return responses;
+    },
+    help () {
+        return {};
+    },
+    fromAction (name, response) {
+        return {
+            [name]: response
+        };
+    }
+};
+/** Thrown when a command execution fails due to action errors. */ export class CommandError extends Error {
+}
+export class DecohereCommand extends CommanderType {
+    get actions() {
+        return [];
+    }
+    constructor(name, handler){
+        super();
+        if (typeof name === "string" || typeof name === "function") {
+            this.name(this.parseCommandName(name));
+        } else {
+            this.name(this.parseCommandName(this.constructor));
+            if (name) {
+                this.registerSubcommand(name, handler);
+            }
+        }
+        if (handler && !this.commands.length) {
+            this.action(handler);
+        }
+        this.exitOverride();
+    }
+    /**
+	 * Whether the command, with these options, runs until it is stopped (`flux serve`,
+	 * `forge build --watch`). The CLI then listens for SIGINT and SIGTERM from the moment it
+	 * starts, so a stop during start-up still shuts down cleanly; other commands keep Node's
+	 * default, where Ctrl+C ends them at once.
+	 */ runsUntilStopped(_options) {
+        return false;
+    }
+    async run(actions, options) {
+        const responses = await this.runActions(actions, options);
+        this.throwOnErrors(responses);
+        return CommandResponse.success(options, responses);
+    }
+    registerSubcommand(commands, onAction) {
+        if (typeof commands === "function") {
+            const instance = new commands(commands, onAction);
+            this.addCommand(instance);
+            if (onAction && !instance.commands.length) {
+                instance.action(onAction);
+            }
+            return;
+        }
+        for (const [key, command] of Object.entries(commands)){
+            const instance = command instanceof DecohereCommand ? command : new command(key, onAction);
+            this.addCommand(instance);
+            if (onAction && !instance.commands.length) {
+                instance.action(onAction);
+            }
+        }
+    }
+    async runActions(actions, options) {
+        const selectedActions = this.getSelectedActions(actions);
+        const responses = {};
+        for (const [actionKey, action] of selectedActions){
+            responses[actionKey] = await action.run(options);
+        }
+        return responses;
+    }
+    getSelectedActions(actions) {
+        if (!this.actions.length) {
+            return [];
+        }
+        const actionEntries = Object.entries(actions);
+        return this.actions.map((ActionClass)=>{
+            const selectedAction = actionEntries.find(([, action])=>action instanceof ActionClass);
+            if (!selectedAction) {
+                throw new CommandError(`${this.name()} command missing action instance for ${ActionClass.name}`);
+            }
+            return selectedAction;
+        });
+    }
+    throwOnErrors(responses) {
+        const failures = Object.entries(responses).filter(([, response])=>{
+            if (!response) {
+                return false;
+            }
+            return !response.succeeded && !response.skipped;
+        });
+        if (!failures.length) {
+            return;
+        }
+        throw new CommandError(`${this.name()} command failed. ${failures.map(([actionName, response])=>`${actionName}: ${response?.message ?? "Unknown error"}`).join("\n")}`);
+    }
+    parseCommandName(stringLike) {
+        const command = typeof stringLike === "string" ? stringLike : stringLike.name?.toLowerCase().replace("command", "") ?? "";
+        if (command === "") {
+            throw new CommandError(`Could not parse command name from ${stringLike.toString()}`);
+        }
+        return command;
+    }
+}

package/es6/src/cli/index.js

@@ -0,0 +1,4 @@
+export { ActionMap, ActionResponse } from "./action.js";
+export { CommandError, CommandResponse, DecohereCommand } from "./command.js";
+export { ModuleManifest } from "./module.type.js";
+export { ConfigFileOption, ConfigurationOption, DryRunOption, EnvFileIfExistsOption, EnvFileOption, LogLevelOption, NoBuildOptions, NoCleanOptions, ProjectOption } from "./options.js";

package/es6/src/cli/module.type.js

@@ -0,0 +1,11 @@
+/**
+ * Simple declaration interface for a CLI module.
+ * Extend this and implement the four abstract members.
+ */ export class ModuleManifest {
+    /** Sub-command classes this module contributes. */ commands = {};
+    /** Action classes this module contributes. */ actions = {};
+    /** Register infrastructure services into the DI container. */ registerServices(_builder) {}
+    /** Lazily create a workspace instance. Return null if this module does not use a workspace. */ createWorkspace(_options) {
+        return Promise.resolve(null);
+    }
+}

package/es6/src/cli/options.js

@@ -0,0 +1,76 @@
+import { Option } from "commander";
+function parseOptionalBoolean(input) {
+    if (typeof input === "boolean") {
+        return input;
+    }
+    const value = input.trim().toLowerCase();
+    if ([
+        "true",
+        "1",
+        "yes",
+        "on"
+    ].includes(value)) {
+        return true;
+    }
+    if ([
+        "false",
+        "0",
+        "no",
+        "off"
+    ].includes(value)) {
+        return false;
+    }
+    throw new Error(`Invalid boolean value: "${input}". Use true/false.`);
+}
+export class ConfigurationOption extends Option {
+    constructor(defaultValue){
+        super("--configuration <configuration>", "Configuration name");
+        this.default(defaultValue);
+    }
+}
+export class ConfigFileOption extends Option {
+    constructor(defaultValue = ".decohere.js"){
+        super("--config-file <file>", "Path to Decohere config file");
+        this.default(defaultValue);
+    }
+}
+export class LogLevelOption extends Option {
+    constructor(){
+        super("--log-level <level>", "Log level (trace, debug, info, warn, error)");
+    }
+}
+export class EnvFileOption extends Option {
+    constructor(){
+        super("--env-file <file>", "Load environment variables from this file before running");
+    }
+}
+export class EnvFileIfExistsOption extends Option {
+    constructor(){
+        super("--env-file-if-exists <file>", "Like --env-file, but skip it when the file is missing");
+    }
+}
+export class NoCleanOptions extends Option {
+    constructor(defaultValue){
+        super("--no-clean", "Will not clean the project directories");
+        this.default(defaultValue);
+    }
+}
+export class NoBuildOptions extends Option {
+    constructor(defaultValue){
+        super("--no-build", "Will not run the build step");
+        this.default(defaultValue);
+    }
+}
+export class DryRunOption extends Option {
+    constructor(description, defaultValue = false){
+        super("--dry-run [dryRun]", description);
+        this.default(defaultValue);
+        this.preset(true);
+        this.argParser(parseOptionalBoolean);
+    }
+}
+export class ProjectOption extends Option {
+    constructor(){
+        super("--project <project>", "Project name to target");
+    }
+}

package/es6/src/diagnostics/index.js

@@ -0,0 +1 @@
+export { Trace, timed, trace } from "./trace.js";

package/es6/src/diagnostics/trace.js

@@ -0,0 +1,61 @@
+import { isPromise } from "node:util/types";
+import { scribe } from "@decohere/scribe";
+/**
+ * Trace mode is toggled with FORGE_TRACE, read when a method is decorated. Raising the log level
+ * to see the output is the CLI's job at its entry point: importing this module changes nothing.
+ */ function isTraceEnabled() {
+    return process.env.FORGE_TRACE != null;
+}
+function serializeArgs(args) {
+    if (args.length === 0) return "";
+    return args.map((arg)=>{
+        if (Array.isArray(arg)) return `[${arg.map(String).join(", ")}]`;
+        const s = String(arg);
+        return s.length > 60 ? `${s.slice(0, 57)}...` : s;
+    }).join(", ");
+}
+function wrapWithTiming(fn, className, methodName, logLevel) {
+    let logger;
+    return function(...args) {
+        if (logger == null) {
+            logger = scribe.logger(className);
+        }
+        const log = logger;
+        const label = `${methodName}(${serializeArgs(args)})`;
+        const start = performance.now();
+        const logDuration = ()=>{
+            log[logLevel](`${label}: ${(performance.now() - start).toFixed(2)}ms`);
+        };
+        const result = fn.apply(this, args);
+        if (isPromise(result)) {
+            return result.finally(logDuration);
+        }
+        logDuration();
+        return result;
+    };
+}
+export function trace(target, propertyKey, descriptor) {
+    if (!isTraceEnabled()) return descriptor;
+    const className = target.constructor.name;
+    descriptor.value = wrapWithTiming(descriptor.value, className, propertyKey, "trace");
+    return descriptor;
+}
+/**
+ * Always-on method timing. Logs duration at `info` regardless of `FORGE_TRACE`.
+ * Use this to time a specific method without raising the process log level.
+ */ export function timed(target, propertyKey, descriptor) {
+    const className = target.constructor.name;
+    descriptor.value = wrapWithTiming(descriptor.value, className, propertyKey, "info");
+    return descriptor;
+}
+export function Trace(constructor) {
+    if (!isTraceEnabled()) return;
+    const className = constructor.name;
+    for (const key of Object.getOwnPropertyNames(constructor.prototype)){
+        if (key === "constructor") continue;
+        const descriptor = Object.getOwnPropertyDescriptor(constructor.prototype, key);
+        if (descriptor == null || typeof descriptor.value !== "function") continue;
+        descriptor.value = wrapWithTiming(descriptor.value, className, key, "trace");
+        Object.defineProperty(constructor.prototype, key, descriptor);
+    }
+}

package/es6/src/interop/docker/docker.js

@@ -0,0 +1,44 @@
+import { InteropError } from "../errors/interop.error.js";
+import { Shell } from "../shell/shell.js";
+export class Docker extends Shell {
+    name = "docker";
+    program = "docker";
+    async build(contextDir, options = {}) {
+        if (contextDir == null || contextDir.trim() === "") {
+            throw new InteropError("Docker build context is required");
+        }
+        const args = [
+            "build"
+        ];
+        if (options.dockerfile) {
+            args.push("-f", options.dockerfile);
+        }
+        for (const tag of options.tags ?? []){
+            args.push("-t", tag);
+        }
+        for (const [key, value] of Object.entries(options.buildArgs ?? {})){
+            args.push("--build-arg", `${key}=${value}`);
+        }
+        for (const [id, env] of Object.entries(options.secrets ?? {})){
+            args.push("--secret", `id=${id},env=${env}`);
+        }
+        if (options.noCache) {
+            args.push("--no-cache");
+        }
+        if (options.pull) {
+            args.push("--pull");
+        }
+        args.push(contextDir);
+        return await this.run({
+            cwd: options.cwd
+        }, ...args);
+    }
+    async push(tag, options = {}) {
+        if (tag == null || tag.trim() === "") {
+            throw new InteropError("Docker tag is required");
+        }
+        return await this.run({
+            cwd: options.cwd
+        }, "push", tag);
+    }
+}

package/es6/src/interop/errors/interop.error.js

@@ -0,0 +1,2 @@
+export class InteropError extends Error {
+}

package/es6/src/interop/git/git.js

@@ -0,0 +1,124 @@
+import { InteropError } from "../errors/interop.error.js";
+import { Shell } from "../shell/shell.js";
+const Commands = {
+    stage: "stage",
+    tag: "tag",
+    add: "add",
+    commit: "commit",
+    push: "push",
+    listFiles: "ls-files"
+};
+const defaultOptions = {
+    cwd: "./"
+};
+export class Git extends Shell {
+    program = "git";
+    async getModifiedFiles(options = defaultOptions) {
+        const args = [
+            Commands.listFiles,
+            "--modified"
+        ];
+        const { cwd } = options;
+        const result = await this.run({
+            cwd
+        }, ...args);
+        return result.data;
+    }
+    async getBranchName(options = defaultOptions) {
+        const { cwd } = options;
+        const args = [
+            "rev-parse",
+            "--symbolic-full-name",
+            "--abbrev-ref",
+            "HEAD"
+        ];
+        const result = await this.run({
+            cwd
+        }, ...args);
+        return result.data[0];
+    }
+    async tag(tag, options = defaultOptions) {
+        const args = [
+            Commands.tag,
+            tag
+        ];
+        const { cwd } = options;
+        const result = await this.run({
+            cwd
+        }, ...args);
+        return result;
+    }
+    async pushTag(tag, options = defaultOptions) {
+        const { cwd, remote = "origin" } = options;
+        const result = await this.run({
+            cwd
+        }, Commands.push, remote, tag);
+        return result;
+    }
+    async commit(message, options) {
+        const optionsAndDefaults = {
+            ...defaultOptions,
+            ...options
+        };
+        const { cwd, files = [], all } = optionsAndDefaults;
+        const args = [
+            Commands.commit
+        ];
+        if (files.length > 0 && all) {
+            throw new InteropError("Cannot commit all and files at the same time");
+        }
+        if (files.length > 0) {
+            await this.stage({
+                files
+            });
+        }
+        if (options.all) {
+            args.push("-a");
+        }
+        args.push("-m", message);
+        const result = await this.run({
+            cwd
+        }, ...args);
+        return result;
+    }
+    async push(branch, options) {
+        const optionsAndDefaults = {
+            ...defaultOptions,
+            ...options
+        };
+        const { cwd, setUpstream } = optionsAndDefaults;
+        const args = [
+            Commands.push
+        ];
+        args.push("--set-upstream", setUpstream ?? "origin");
+        args.push(branch);
+        const result = await this.run({
+            cwd
+        }, ...args);
+        return result;
+    }
+    async pull(branch, options = defaultOptions) {
+        const { cwd } = options;
+        return this.run({
+            cwd
+        }, "pull", "--rebase", "origin", branch);
+    }
+    async stage(options) {
+        const optionsAndDefaults = {
+            ...defaultOptions,
+            ...options
+        };
+        const { cwd, files = [], all } = optionsAndDefaults;
+        if (all) {
+            await this.run({
+                cwd
+            }, Commands.stage, "-a");
+            return;
+        }
+        for (const file of files){
+            await this.run({
+                cwd
+            }, Commands.stage, file);
+        }
+    }
+}

package/es6/src/interop/git/git.types.js

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

package/es6/src/interop/index.js

@@ -0,0 +1,21 @@
+// << Git >>
+// << Docker >>
+export * from "./docker/docker.js";
+export * from "./git/git.js";
+export * as git from "./git/git.types.js";
+// << Node >>
+export * from "./node/node.js";
+// << Npm >>
+export * from "./npm/npm.js";
+export * as npm from "./npm/npm.types.js";
+// << Pnpm >>
+export * from "./pnpm/pnpm.js";
+export * as pnpm from "./pnpm/pnpm.types.js";
+// << Shell >>
+export * from "./shell/shell.js";
+export * as shell from "./shell/shell.types.js";
+export * from "./types/detect-package-manager.js";
+export * from "./types/package-manager.js";
+// << Yarn >>
+export * from "./yarn/yarn.js";
+export * as yarn from "./yarn/yarn.types.js";

package/es6/src/interop/node/index.js

@@ -0,0 +1 @@
+export * from "./node.js";

package/es6/src/interop/node/node.js

@@ -0,0 +1,35 @@
+import { spawn } from "node:child_process";
+import { Shell } from "../shell/shell.js";
+export class Node extends Shell {
+    program = "node";
+    async runScript(script, ...args) {
+        const spawnOpt = {
+            cwd: ".",
+            stdio: "inherit",
+            env: {
+                ...process.env
+            }
+        };
+        return new Promise((resolve, reject)=>{
+            const proc = spawn("node", [
+                script,
+                ...args
+            ], spawnOpt);
+            proc.on("exit", (code)=>{
+                if (code !== 0) {
+                    reject();
+                }
+                resolve(null);
+            });
+            proc.on("close", (code)=>{
+                resolve(null);
+                if (code === 0) {
+                    resolve({
+                        message: `${script} completed`
+                    });
+                }
+                reject(`Running '${script}' failed with code ${code}`);
+            });
+        });
+    }
+}

package/es6/src/interop/npm/npm.js

@@ -0,0 +1,180 @@
+import { InteropError } from "../errors/interop.error.js";
+import { Shell } from "../shell/shell.js";
+const Commands = {
+    publish: "publish",
+    version: "version",
+    link: "link",
+    install: "install"
+};
+export class Npm extends Shell {
+    name = "npm";
+    program = "npm";
+    async publish(directory, options = {
+        channel: "beta"
+    }) {
+        const { cwd, dryRun, skipIfPublished, channel, authToken, otp, provenance } = options;
+        if (directory == null) {
+            throw new InteropError("Directory is required");
+        }
+        if (skipIfPublished && !dryRun) {
+            const alreadyPublished = await this.isPublished(directory, {
+                cwd
+            });
+            if (alreadyPublished) {
+                return {
+                    message: `Skipping publish — version already exists on registry`,
+                    data: []
+                };
+            }
+        }
+        const args = [
+            Commands.publish,
+            directory
+        ];
+        let tmpUserConfigPath;
+        args.push("--tag", channel ?? "beta");
+        if (provenance) {
+            args.push("--provenance");
+        }
+        // Explicit --token (local bootstrap). OIDC publish must not inherit cwd .npmrc / NODE_AUTH_TOKEN.
+        if (authToken?.trim()) {
+            tmpUserConfigPath = await this.createTempUserConfig(authToken.trim());
+            args.push("--userconfig", tmpUserConfigPath);
+        }
+        if (dryRun) {
+            args.push("--dry-run");
+        }
+        const env = {
+            ...process.env
+        };
+        if (!authToken?.trim()) {
+            delete env.NODE_AUTH_TOKEN;
+            delete env.NPM_TOKEN;
+            env.NPM_CONFIG_USERCONFIG = "/dev/null";
+        }
+        if (otp) {
+            env.NPM_CONFIG_OTP = otp;
+        }
+        try {
+            return await this.run({
+                cwd,
+                env
+            }, ...args);
+        } catch (error) {
+            if (skipIfPublished && !dryRun && isAlreadyPublishedError(error)) {
+                return {
+                    message: `Skipping publish — version already exists on registry`,
+                    data: []
+                };
+            }
+            throw error;
+        } finally{
+            if (tmpUserConfigPath) {
+                await this.removeTempUserConfig(tmpUserConfigPath);
+            }
+        }
+    }
+    /**
+	 * @description Runs in the directory of the package
+	 * @param options
+	 * @returns
+	 */ async version(versionType, options) {
+        const { cwd, noTag, preid } = options;
+        const args = [
+            Commands.version,
+            versionType
+        ];
+        if (noTag) {
+            args.push("--no-git-tag-version");
+        }
+        if (preid) {
+            args.push("--preid", preid);
+        }
+        return this.run({
+            cwd
+        }, ...args);
+    }
+    async link(directory, options = {
+        cwd: "./"
+    }) {
+        const { cwd } = options;
+        const args = [
+            Commands.link,
+            directory
+        ];
+        return this.run({
+            cwd
+        }, ...args);
+    }
+    async install(options = {
+        cwd: "./"
+    }) {
+        const { cwd } = options;
+        return this.run({
+            cwd
+        }, Commands.install);
+    }
+    /**
+	 * Install only `dependencies` as real folders: `--omit=dev` skips devDependencies and
+	 * `--no-bin-links` skips the `.bin` symlinks, so the result holds no symlinks at all.
+	 */ async installProduction(options = {
+        cwd: "./"
+    }) {
+        const { cwd } = options;
+        return this.run({
+            cwd
+        }, Commands.install, "--omit=dev", "--no-bin-links", "--no-audit", "--no-fund", "--loglevel=error");
+    }
+    async syncLockFile(options = {
+        cwd: "./"
+    }) {
+        const { cwd } = options;
+        return this.run({
+            cwd
+        }, Commands.install, "--package-lock-only", "--ignore-scripts");
+    }
+    /**
+	 * True when package@version exists on the registry.
+	 * Uses ambient npm config (cwd `.npmrc`); do not pass tokens on argv.
+	 */ async isPublished(directory, options) {
+        const { readFileSync } = await import("node:fs");
+        const { join } = await import("node:path");
+        try {
+            const pkgJson = JSON.parse(readFileSync(join(directory, "package.json"), "utf8"));
+            const spec = `${pkgJson.name}@${pkgJson.version}`;
+            await this.run(options, "view", spec, "version");
+            return true;
+        } catch  {
+            return false;
+        }
+    }
+    async createTempUserConfig(authToken) {
+        const { mkdtemp, writeFile } = await import("node:fs/promises");
+        const { tmpdir } = await import("node:os");
+        const { join } = await import("node:path");
+        const tempDir = await mkdtemp(join(tmpdir(), "decohere-npmrc-"));
+        const npmrcPath = join(tempDir, ".npmrc");
+        const npmrc = [
+            "registry=https://registry.npmjs.org/",
+            "always-auth=true",
+            `//registry.npmjs.org/:_authToken=${authToken}`
+        ].join("\n");
+        await writeFile(npmrcPath, `${npmrc}\n`, {
+            mode: 0o600
+        });
+        return npmrcPath;
+    }
+    async removeTempUserConfig(npmrcPath) {
+        const { rm } = await import("node:fs/promises");
+        const { dirname } = await import("node:path");
+        const dir = dirname(npmrcPath);
+        await rm(dir, {
+            recursive: true,
+            force: true
+        });
+    }
+}
+function isAlreadyPublishedError(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return /cannot publish over the previously published versions/i.test(message);
+}

package/es6/src/interop/npm/npm.types.js

@@ -0,0 +1,6 @@
+export const VersionTypes = {
+    major: "major",
+    minor: "minor",
+    patch: "patch",
+    prerelease: "prerelease"
+};