@decohere/devkit 0.0.1-dev.125 → 0.0.1-dev.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decohere/devkit",
-  "version": "0.0.1-dev.125",
+  "version": "0.0.1-dev.5",
   "description": "The shared base for Decohere's command-line tools: the command framework, git/npm/pnpm/docker wrappers, tracing, and file search and watch. Never needed in a production app.",
   "keywords": [
     "typescript",
@@ -9,15 +9,6 @@
     "tooling",
     "decohere"
   ],
-  "homepage": "https://github.com/typesmiths/decohere/tree/main/projects/devkit#readme",
-  "bugs": {
-    "url": "https://github.com/typesmiths/decohere/issues"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/typesmiths/decohere.git",
-    "directory": "projects/devkit"
-  },
   "license": "ISC",
   "author": "Typesmiths",
   "type": "module",
@@ -48,8 +39,8 @@
     "test": "echo \"Error: no test specified\" && exit 1"
   },
   "dependencies": {
-    "@decohere/core": "0.0.1-dev.125",
-    "@decohere/scribe": "0.0.1-dev.125",
+    "@decohere/core": "0.0.1-dev.5",
+    "@decohere/scribe": "0.0.1-dev.5",
     "commander": "^13.1.0",
     "glob": "^13.0.1",
     "picomatch": "^4.0.4"

package/src/cli/action.ts

@@ -0,0 +1,77 @@
+import type { Constructable } from "@decohere/core/reflection";
+import type { UnionToIntersection } from "@decohere/core/system";
+
+export const ActionMap = Symbol("ActionMap");
+
+export type ActionClassMap = Record<string, Constructable<Action>>;
+
+export interface ResultStatus {
+	succeeded: boolean;
+	error?: string;
+}
+
+export interface Result {
+	readonly name: string;
+	readonly succeeded: boolean;
+	readonly skipped: boolean;
+	readonly message: string;
+}
+
+export class ActionResponse<TData = unknown> implements Result {
+	public static Success<TData>(name: string, data?: TData[]) {
+		return new ActionResponse<TData>({ name, data, succeeded: true });
+	}
+
+	public static Skipped(name: string) {
+		return new ActionResponse({ name, skipped: true });
+	}
+
+	public static Blocking(name: string) {
+		return new ActionResponse({ name, succeeded: true, blocking: true });
+	}
+
+	public static Error<TData = unknown>(name: string, message: string): ActionResponse<TData>;
+	public static Error<TData extends ResultStatus>(
+		name: string,
+		data: TData[],
+	): ActionResponse<TData>;
+	public static Error<TData extends ResultStatus>(
+		name: string,
+		messageOrData: string | TData[],
+		data?: TData[],
+	) {
+		if (Array.isArray(messageOrData)) {
+			const message = messageOrData
+				.filter((r) => !r.succeeded)
+				.map((r) => r.error ?? "Unknown error")
+				.join("\n");
+			return new ActionResponse<TData>({ name, message, data: messageOrData });
+		}
+		return new ActionResponse<TData>({ name, message: messageOrData, data });
+	}
+
+	public constructor(data: Partial<ActionResponse<TData>>) {
+		Object.assign(this, data);
+	}
+
+	public readonly name: string;
+	public readonly succeeded: boolean = false;
+	public readonly skipped: boolean = false;
+	public readonly blocking: boolean = false;
+	public readonly message: string;
+	public readonly data: TData[];
+}
+
+export interface Action<T extends object = object> {
+	run(options: T): Promise<ActionResponse>;
+}
+
+export type Actions = Record<string, Action>;
+
+export type ActionOptions<A extends Action> = A extends Action<infer T> ? T : never;
+
+export type MergeOptions<TActions extends Record<string, Action>> = UnionToIntersection<
+	{
+		[K in keyof TActions]: ActionOptions<TActions[K]>;
+	}[keyof TActions]
+>;

package/src/cli/command.ts

@@ -0,0 +1,173 @@
+import { Command as CommanderType, type OptionValues } from "commander";
+import type { Constructable } from "@decohere/core/reflection";
+import type { ActionResponse, Actions } from "./action.js";
+
+export type CommandType = Constructable<DecohereCommand>;
+
+export type CommandHandler = (opts: OptionValues, cmd: DecohereCommand) => Promise<void>;
+
+export type CommandResponse<TActions extends Actions = Actions> = {
+	[ActionName in keyof TActions]?: ActionResponse;
+};
+
+export const CommandResponse = {
+	success<T extends Actions>(
+		_ctx: unknown,
+		responses: CommandResponse<T>,
+	): CommandResponse<T> {
+		return responses;
+	},
+
+	help<T extends Actions = Actions>(): CommandResponse<T> {
+		return {} as CommandResponse<T>;
+	},
+
+	fromAction(name: string, response: ActionResponse): CommandResponse {
+		return { [name]: response };
+	},
+};
+
+/** Thrown when a command execution fails due to action errors. */
+export class CommandError extends Error {}
+
+export class DecohereCommand<TActions extends Actions = Actions> extends CommanderType {
+	public get actions(): readonly Constructable<import("./action.js").Action>[] {
+		return [];
+	}
+
+	public constructor(
+		name?: string | Constructable | Record<string, CommandType>,
+		handler?: CommandHandler,
+	) {
+		super();
+		if (typeof name === "string" || typeof name === "function") {
+			this.name(this.parseCommandName(name));
+		} else {
+			this.name(this.parseCommandName(this.constructor as unknown as Constructable));
+			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.
+	 */
+	public runsUntilStopped(_options: OptionValues): boolean {
+		return false;
+	}
+
+	public async run(
+		actions: TActions,
+		options: OptionValues,
+	): Promise<CommandResponse<TActions>> {
+		const responses = await this.runActions(actions, options);
+		this.throwOnErrors(responses);
+		return CommandResponse.success(options, responses);
+	}
+
+	public registerSubcommand(command: CommandType, onAction?: CommandHandler): void;
+	public registerSubcommand(
+		commands: Record<string, DecohereCommand | CommandType>,
+		onAction?: CommandHandler,
+	): void;
+	public registerSubcommand(
+		commands: CommandType | Record<string, DecohereCommand | CommandType>,
+		onAction?: CommandHandler,
+	): void {
+		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);
+			}
+		}
+	}
+
+	protected async runActions(
+		actions: TActions,
+		options: OptionValues,
+	): Promise<CommandResponse<TActions>> {
+		const selectedActions = this.getSelectedActions(actions);
+		const responses = {} as CommandResponse<TActions>;
+		for (const [actionKey, action] of selectedActions) {
+			responses[actionKey] = (await action.run(
+				options,
+			)) as CommandResponse<TActions>[keyof TActions];
+		}
+		return responses as CommandResponse<TActions>;
+	}
+
+	protected getSelectedActions(
+		actions: TActions,
+	): Array<[keyof TActions, TActions[keyof TActions]]> {
+		if (!this.actions.length) {
+			return [];
+		}
+
+		const actionEntries = Object.entries(actions) as Array<
+			[keyof TActions, TActions[keyof TActions]]
+		>;
+		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;
+		});
+	}
+
+	protected throwOnErrors(responses: CommandResponse<TActions>): void {
+		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")}`,
+		);
+	}
+
+	private parseCommandName(stringLike: string | Constructable) {
+		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/src/cli/index.ts

@@ -0,0 +1,30 @@
+export type {
+	Action,
+	ActionClassMap,
+	ActionOptions,
+	Actions,
+	MergeOptions,
+	Result,
+	ResultStatus,
+} from "./action.js";
+export { ActionMap, ActionResponse } from "./action.js";
+export type { CommandHandler, CommandType } from "./command.js";
+export { CommandError, CommandResponse, DecohereCommand } from "./command.js";
+export type {
+	ApplicationModule,
+	CommandMap as CommandClassMap,
+	ModuleConfig,
+	WorkspaceFactoryOptions,
+} from "./module.type.js";
+export { ModuleManifest } from "./module.type.js";
+export {
+	ConfigFileOption,
+	ConfigurationOption,
+	DryRunOption,
+	EnvFileIfExistsOption,
+	EnvFileOption,
+	LogLevelOption,
+	NoBuildOptions,
+	NoCleanOptions,
+	ProjectOption,
+} from "./options.js";

package/src/cli/module.type.ts

@@ -0,0 +1,48 @@
+import type { ContainerBuilder } from "@decohere/core/composition";
+import type { ActionClassMap } from "./action.js";
+import type { CommandType, DecohereCommand } from "./command.js";
+
+export type CommandMap = Record<string, CommandType>;
+
+export type WorkspaceFactoryOptions = {
+	configFile?: string;
+	rootDir?: string;
+};
+
+export interface ApplicationModule {
+	id: string;
+	dispose?(): void;
+	asyncDispose?(): Promise<void>;
+	command: DecohereCommand;
+}
+
+export type ModuleConfig = {
+	actions?: ActionClassMap;
+	commands?: CommandMap;
+};
+
+/**
+ * Simple declaration interface for a CLI module.
+ * Extend this and implement the four abstract members.
+ */
+export abstract class ModuleManifest {
+	/** Unique module identifier, used as the root command name. */
+	public abstract readonly id: string;
+
+	/** Sub-command classes this module contributes. */
+	public readonly commands: CommandMap = {};
+
+	/** Action classes this module contributes. */
+	public readonly actions: ActionClassMap = {};
+
+	/** The root command class for this module. */
+	public abstract readonly command: CommandType;
+
+	/** Register infrastructure services into the DI container. */
+	public registerServices(_builder: ContainerBuilder): void {}
+
+	/** Lazily create a workspace instance. Return null if this module does not use a workspace. */
+	public createWorkspace(_options: WorkspaceFactoryOptions): Promise<object | null> {
+		return Promise.resolve(null);
+	}
+}

package/src/cli/options.ts

@@ -0,0 +1,81 @@
+import { Option } from "commander";
+
+function parseOptionalBoolean(input: string | boolean): boolean {
+	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 {
+	public constructor(defaultValue: string) {
+		super("--configuration <configuration>", "Configuration name");
+		this.default(defaultValue);
+	}
+}
+
+export class ConfigFileOption extends Option {
+	public constructor(defaultValue = ".decohere.js") {
+		super("--config-file <file>", "Path to Decohere config file");
+		this.default(defaultValue);
+	}
+}
+
+export class LogLevelOption extends Option {
+	public constructor() {
+		super("--log-level <level>", "Log level (trace, debug, info, warn, error)");
+	}
+}
+
+export class EnvFileOption extends Option {
+	public constructor() {
+		super("--env-file <file>", "Load environment variables from this file before running");
+	}
+}
+
+export class EnvFileIfExistsOption extends Option {
+	public constructor() {
+		super(
+			"--env-file-if-exists <file>",
+			"Like --env-file, but skip it when the file is missing",
+		);
+	}
+}
+
+export class NoCleanOptions extends Option {
+	public constructor(defaultValue: boolean) {
+		super("--no-clean", "Will not clean the project directories");
+		this.default(defaultValue);
+	}
+}
+
+export class NoBuildOptions extends Option {
+	public constructor(defaultValue: boolean) {
+		super("--no-build", "Will not run the build step");
+		this.default(defaultValue);
+	}
+}
+
+export class DryRunOption extends Option {
+	public constructor(description: string, defaultValue = false) {
+		super("--dry-run [dryRun]", description);
+		this.default(defaultValue);
+		this.preset(true);
+		this.argParser(parseOptionalBoolean);
+	}
+}
+
+export class ProjectOption extends Option {
+	public constructor() {
+		super("--project <project>", "Project name to target");
+	}
+}

package/src/diagnostics/trace.ts

@@ -0,0 +1,92 @@
+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(): boolean {
+	return process.env.FORGE_TRACE != null;
+}
+
+type AnyFn = (...args: unknown[]) => unknown;
+type TimingLevel = "info" | "trace";
+
+function serializeArgs(args: unknown[]): string {
+	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: AnyFn,
+	className: string,
+	methodName: string,
+	logLevel: TimingLevel,
+): AnyFn {
+	let logger: ReturnType<typeof scribe.logger> | undefined;
+	return function (this: unknown, ...args: unknown[]) {
+		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: object,
+	propertyKey: string,
+	descriptor: PropertyDescriptor,
+): PropertyDescriptor {
+	if (!isTraceEnabled()) return descriptor;
+	const className = (target as { constructor: { name: string } }).constructor.name;
+	descriptor.value = wrapWithTiming(
+		descriptor.value as AnyFn,
+		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: object,
+	propertyKey: string,
+	descriptor: PropertyDescriptor,
+): PropertyDescriptor {
+	const className = (target as { constructor: { name: string } }).constructor.name;
+	descriptor.value = wrapWithTiming(descriptor.value as AnyFn, className, propertyKey, "info");
+	return descriptor;
+}
+
+export function Trace(constructor: { name: string; prototype: object }): void {
+	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 as AnyFn, className, key, "trace");
+		Object.defineProperty(constructor.prototype, key, descriptor);
+	}
+}

package/src/interop/docker/docker.ts

@@ -0,0 +1,57 @@
+import { InteropError } from "../errors/interop.error.js";
+import { Shell } from "../shell/shell.js";
+
+export type DockerBuildOptions = {
+	cwd?: string;
+	dockerfile?: string;
+	tags?: string[];
+	buildArgs?: Record<string, string>;
+	secrets?: Record<string, string>;
+	noCache?: boolean;
+	pull?: boolean;
+};
+
+export type DockerPushOptions = {
+	cwd?: string;
+};
+
+export class Docker extends Shell {
+	public readonly name = "docker" as const;
+	protected program = "docker";
+
+	public async build(contextDir: string, options: DockerBuildOptions = {}) {
+		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);
+	}
+
+	public async push(tag: string, options: DockerPushOptions = {}) {
+		if (tag == null || tag.trim() === "") {
+			throw new InteropError("Docker tag is required");
+		}
+
+		return await this.run({ cwd: options.cwd }, "push", tag);
+	}
+}

package/src/interop/errors/interop.error.ts

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

package/src/interop/git/git.ts

@@ -0,0 +1,98 @@
+import { InteropError } from "../errors/interop.error.js";
+import { Shell } from "../shell/shell.js";
+import type { ShellResponse } from "../shell/shell.types.js";
+import type { CommitOptions, GitOptions, PushOptions, StageOptions } from "./git.types.js";
+
+const Commands = {
+	stage: "stage",
+	tag: "tag",
+	add: "add",
+	commit: "commit",
+	push: "push",
+	listFiles: "ls-files",
+};
+
+const defaultOptions: GitOptions = { cwd: "./" };
+
+export class Git extends Shell {
+	protected program: string = "git";
+	public async getModifiedFiles(options: GitOptions = defaultOptions) {
+		const args = [Commands.listFiles, "--modified"];
+		const { cwd } = options;
+		const result = await this.run({ cwd }, ...args);
+		return result.data;
+	}
+
+	public async getBranchName(options: GitOptions = 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];
+	}
+
+	public async tag(tag: string, options: GitOptions = defaultOptions) {
+		const args = [Commands.tag, tag];
+		const { cwd } = options;
+		const result = await this.run({ cwd }, ...args);
+		return result;
+	}
+
+	public async pushTag(
+		tag: string,
+		options: GitOptions & { remote?: string } = defaultOptions,
+	) {
+		const { cwd, remote = "origin" } = options;
+		const result = await this.run({ cwd }, Commands.push, remote, tag);
+		return result;
+	}
+
+	public async commit(message: string, options: CommitOptions): Promise<ShellResponse> {
+		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;
+	}
+
+	public async push(branch: string, options?: PushOptions) {
+		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;
+	}
+
+	public async pull(branch: string, options: GitOptions = defaultOptions) {
+		const { cwd } = options;
+		return this.run({ cwd }, "pull", "--rebase", "origin", branch);
+	}
+
+	public async stage(options: StageOptions) {
+		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);
+		}
+	}
+}