@decohere/devkit 0.0.1-dev.119

package/README.md

@@ -0,0 +1,14 @@
+# Devkit
+
+The shared base for Decohere's command-line tools: forge, flux, the `decohere` CLI and the scaffolder ([ADR 0015](../../docs/adr/0015-core-devkit-testing.md)). Nothing here runs in a production app, so a production install never pulls in `commander`, `glob` or `picomatch` through it.
+
+| Subpath | What it is |
+|---|---|
+| `@decohere/devkit/cli` | The command framework on [commander](https://github.com/tj/commander.js): `DecohereCommand`, `Action`, and the shared options (`--configuration`, `--log-level`, `--env-file`, `--dry-run`, …) |
+| `@decohere/devkit/interop` | Typed wrappers that run `git`, `npm`, `pnpm`, `yarn`, `docker` and `node`, plus package-manager detection |
+| `@decohere/devkit/diagnostics` | `@trace` (method timings when `FORGE_TRACE` is set) and `@timed` (always) |
+| `@decohere/devkit/io` | File search and watch: `findFiles`, `findFile`, `findDirectories`, `watch`, `WatchEvents` |
+
+Basic file operations (`fileExists`, `readFile`, `writeFile`, …) and the file types (`FileEx`, `Watcher`) stay in `@decohere/core/io`, where runtime packages can use them without these dependencies.
+
+`@trace` reads `FORGE_TRACE` when a method is decorated, and importing it changes nothing. The bins decide the log level: `FORGE_TRACE` makes them log at `trace` unless `--log-level` or a level in the environment says otherwise.

package/commonjs/src/cli/action.js

@@ -0,0 +1,65 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+function _export(target, all) {
+    for(var name in all)Object.defineProperty(target, name, {
+        enumerable: true,
+        get: Object.getOwnPropertyDescriptor(all, name).get
+    });
+}
+_export(exports, {
+    get ActionMap () {
+        return ActionMap;
+    },
+    get ActionResponse () {
+        return ActionResponse;
+    }
+});
+const ActionMap = Symbol("ActionMap");
+class ActionResponse {
+    static Success(name, data) {
+        return new ActionResponse({
+            name,
+            data,
+            succeeded: true
+        });
+    }
+    static Skipped(name) {
+        return new ActionResponse({
+            name,
+            skipped: true
+        });
+    }
+    static Blocking(name) {
+        return new ActionResponse({
+            name,
+            succeeded: true,
+            blocking: true
+        });
+    }
+    static Error(name, messageOrData, data) {
+        if (Array.isArray(messageOrData)) {
+            const message = messageOrData.filter((r)=>!r.succeeded).map((r)=>r.error ?? "Unknown error").join("\n");
+            return new ActionResponse({
+                name,
+                message,
+                data: messageOrData
+            });
+        }
+        return new ActionResponse({
+            name,
+            message: messageOrData,
+            data
+        });
+    }
+    constructor(data){
+        Object.assign(this, data);
+    }
+    name;
+    succeeded = false;
+    skipped = false;
+    blocking = false;
+    message;
+    data;
+}

package/commonjs/src/cli/command.js

@@ -0,0 +1,127 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+function _export(target, all) {
+    for(var name in all)Object.defineProperty(target, name, {
+        enumerable: true,
+        get: Object.getOwnPropertyDescriptor(all, name).get
+    });
+}
+_export(exports, {
+    get CommandError () {
+        return CommandError;
+    },
+    get CommandResponse () {
+        return CommandResponse;
+    },
+    get DecohereCommand () {
+        return DecohereCommand;
+    }
+});
+const _commander = require("commander");
+const CommandResponse = {
+    success (_ctx, responses) {
+        return responses;
+    },
+    help () {
+        return {};
+    },
+    fromAction (name, response) {
+        return {
+            [name]: response
+        };
+    }
+};
+class CommandError extends Error {
+}
+class DecohereCommand extends _commander.Command {
+    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/commonjs/src/cli/index.js

@@ -0,0 +1,61 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+function _export(target, all) {
+    for(var name in all)Object.defineProperty(target, name, {
+        enumerable: true,
+        get: Object.getOwnPropertyDescriptor(all, name).get
+    });
+}
+_export(exports, {
+    get ActionMap () {
+        return _action.ActionMap;
+    },
+    get ActionResponse () {
+        return _action.ActionResponse;
+    },
+    get CommandError () {
+        return _command.CommandError;
+    },
+    get CommandResponse () {
+        return _command.CommandResponse;
+    },
+    get ConfigFileOption () {
+        return _options.ConfigFileOption;
+    },
+    get ConfigurationOption () {
+        return _options.ConfigurationOption;
+    },
+    get DecohereCommand () {
+        return _command.DecohereCommand;
+    },
+    get DryRunOption () {
+        return _options.DryRunOption;
+    },
+    get EnvFileIfExistsOption () {
+        return _options.EnvFileIfExistsOption;
+    },
+    get EnvFileOption () {
+        return _options.EnvFileOption;
+    },
+    get LogLevelOption () {
+        return _options.LogLevelOption;
+    },
+    get ModuleManifest () {
+        return _moduletype.ModuleManifest;
+    },
+    get NoBuildOptions () {
+        return _options.NoBuildOptions;
+    },
+    get NoCleanOptions () {
+        return _options.NoCleanOptions;
+    },
+    get ProjectOption () {
+        return _options.ProjectOption;
+    }
+});
+const _action = require("./action.js");
+const _command = require("./command.js");
+const _moduletype = require("./module.type.js");
+const _options = require("./options.js");

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

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+Object.defineProperty(exports, "ModuleManifest", {
+    enumerable: true,
+    get: function() {
+        return ModuleManifest;
+    }
+});
+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/commonjs/src/cli/options.js

@@ -0,0 +1,115 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+function _export(target, all) {
+    for(var name in all)Object.defineProperty(target, name, {
+        enumerable: true,
+        get: Object.getOwnPropertyDescriptor(all, name).get
+    });
+}
+_export(exports, {
+    get ConfigFileOption () {
+        return ConfigFileOption;
+    },
+    get ConfigurationOption () {
+        return ConfigurationOption;
+    },
+    get DryRunOption () {
+        return DryRunOption;
+    },
+    get EnvFileIfExistsOption () {
+        return EnvFileIfExistsOption;
+    },
+    get EnvFileOption () {
+        return EnvFileOption;
+    },
+    get LogLevelOption () {
+        return LogLevelOption;
+    },
+    get NoBuildOptions () {
+        return NoBuildOptions;
+    },
+    get NoCleanOptions () {
+        return NoCleanOptions;
+    },
+    get ProjectOption () {
+        return ProjectOption;
+    }
+});
+const _commander = require("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.`);
+}
+class ConfigurationOption extends _commander.Option {
+    constructor(defaultValue){
+        super("--configuration <configuration>", "Configuration name");
+        this.default(defaultValue);
+    }
+}
+class ConfigFileOption extends _commander.Option {
+    constructor(defaultValue = ".decohere.js"){
+        super("--config-file <file>", "Path to Decohere config file");
+        this.default(defaultValue);
+    }
+}
+class LogLevelOption extends _commander.Option {
+    constructor(){
+        super("--log-level <level>", "Log level (trace, debug, info, warn, error)");
+    }
+}
+class EnvFileOption extends _commander.Option {
+    constructor(){
+        super("--env-file <file>", "Load environment variables from this file before running");
+    }
+}
+class EnvFileIfExistsOption extends _commander.Option {
+    constructor(){
+        super("--env-file-if-exists <file>", "Like --env-file, but skip it when the file is missing");
+    }
+}
+class NoCleanOptions extends _commander.Option {
+    constructor(defaultValue){
+        super("--no-clean", "Will not clean the project directories");
+        this.default(defaultValue);
+    }
+}
+class NoBuildOptions extends _commander.Option {
+    constructor(defaultValue){
+        super("--no-build", "Will not run the build step");
+        this.default(defaultValue);
+    }
+}
+class DryRunOption extends _commander.Option {
+    constructor(description, defaultValue = false){
+        super("--dry-run [dryRun]", description);
+        this.default(defaultValue);
+        this.preset(true);
+        this.argParser(parseOptionalBoolean);
+    }
+}
+class ProjectOption extends _commander.Option {
+    constructor(){
+        super("--project <project>", "Project name to target");
+    }
+}

package/commonjs/src/diagnostics/index.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+function _export(target, all) {
+    for(var name in all)Object.defineProperty(target, name, {
+        enumerable: true,
+        get: Object.getOwnPropertyDescriptor(all, name).get
+    });
+}
+_export(exports, {
+    get Trace () {
+        return _trace.Trace;
+    },
+    get timed () {
+        return _trace.timed;
+    },
+    get trace () {
+        return _trace.trace;
+    }
+});
+const _trace = require("./trace.js");

package/commonjs/src/diagnostics/trace.js

@@ -0,0 +1,79 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+function _export(target, all) {
+    for(var name in all)Object.defineProperty(target, name, {
+        enumerable: true,
+        get: Object.getOwnPropertyDescriptor(all, name).get
+    });
+}
+_export(exports, {
+    get Trace () {
+        return Trace;
+    },
+    get timed () {
+        return timed;
+    },
+    get trace () {
+        return trace;
+    }
+});
+const _types = require("node:util/types");
+const _scribe = require("@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.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 ((0, _types.isPromise)(result)) {
+            return result.finally(logDuration);
+        }
+        logDuration();
+        return result;
+    };
+}
+function trace(target, propertyKey, descriptor) {
+    if (!isTraceEnabled()) return descriptor;
+    const className = target.constructor.name;
+    descriptor.value = wrapWithTiming(descriptor.value, className, propertyKey, "trace");
+    return descriptor;
+}
+function timed(target, propertyKey, descriptor) {
+    const className = target.constructor.name;
+    descriptor.value = wrapWithTiming(descriptor.value, className, propertyKey, "info");
+    return descriptor;
+}
+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/commonjs/src/interop/docker/docker.js

@@ -0,0 +1,54 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+Object.defineProperty(exports, "Docker", {
+    enumerable: true,
+    get: function() {
+        return Docker;
+    }
+});
+const _interoperror = require("../errors/interop.error.js");
+const _shell = require("../shell/shell.js");
+class Docker extends _shell.Shell {
+    name = "docker";
+    program = "docker";
+    async build(contextDir, options = {}) {
+        if (contextDir == null || contextDir.trim() === "") {
+            throw new _interoperror.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.InteropError("Docker tag is required");
+        }
+        return await this.run({
+            cwd: options.cwd
+        }, "push", tag);
+    }
+}

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

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+Object.defineProperty(exports, "InteropError", {
+    enumerable: true,
+    get: function() {
+        return InteropError;
+    }
+});
+class InteropError extends Error {
+}