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

package/tests/io/watch.spec.ts

@@ -0,0 +1,291 @@
+import path from "node:path";
+import { fs, vol } from "memfs";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { watch } from "../../src/io/watch.js";
+
+vi.mock("fs");
+vi.mock("node:fs");
+vi.mock("fs/promises");
+vi.mock("node:fs/promises");
+
+describe("io.watch", () => {
+	beforeEach(() => {
+		vol.reset();
+	});
+
+	afterEach(() => {
+		vol.reset();
+	});
+
+	it("emits change for nested subdirectory files", async () => {
+		const rootPath = "/workspace/project/src";
+		const nestedDirectoryPath = path.join(rootPath, "nested", "deeper");
+		const nestedFilePath = path.join(nestedDirectoryPath, "index.ts");
+		const expectedRelativePath = path.posix.join("nested", "deeper", "index.ts");
+
+		fs.mkdirSync(nestedDirectoryPath, { recursive: true });
+		fs.writeFileSync(nestedFilePath, "export const v = 1;", { encoding: "utf8" });
+
+		await new Promise<void>((resolve, reject) => {
+			const watcher = watch(rootPath);
+
+			watcher.on("change", (file) => {
+				if (file.relativePath !== expectedRelativePath) {
+					return;
+				}
+
+				expect(file.fullPath).toBe(nestedFilePath);
+				watcher.close();
+				resolve();
+			});
+
+			setTimeout(() => {
+				fs.writeFileSync(nestedFilePath, "export const v = 2;", { encoding: "utf8" });
+			}, 30);
+
+			setTimeout(() => {
+				watcher.close();
+				reject(new Error("expected change event was not emitted for nested file"));
+			}, 800);
+		});
+	});
+
+	it("does not emit initial add events when ignoreInitial is true", async () => {
+		const rootPath = "/workspace/project/src";
+		const existingFilePath = path.join(rootPath, "index.ts");
+
+		fs.mkdirSync(rootPath, { recursive: true });
+		fs.writeFileSync(existingFilePath, "export const v = 1;", { encoding: "utf8" });
+
+		await new Promise<void>((resolve, reject) => {
+			const watcher = watch(rootPath, { ignoreInitial: true });
+
+			watcher.on("add", () => {
+				watcher.close();
+				reject(new Error("unexpected initial add event"));
+			});
+
+			setTimeout(() => {
+				watcher.close();
+				resolve();
+			}, 100);
+		});
+	});
+
+	it("emits add for a new file when ignoreInitial is true", async () => {
+		const rootPath = "/workspace/project/src";
+		const addedFilePath = path.join(rootPath, "new-file.ts");
+
+		fs.mkdirSync(rootPath, { recursive: true });
+		fs.writeFileSync(path.join(rootPath, "existing.ts"), "export const x = 1;", {
+			encoding: "utf8",
+		});
+
+		await new Promise<void>((resolve, reject) => {
+			const watcher = watch(rootPath, { ignoreInitial: true });
+
+			watcher.on("add", (file) => {
+				if (file.relativePath !== "new-file.ts") {
+					return;
+				}
+
+				expect(file.fullPath).toBe(addedFilePath);
+				watcher.close();
+				resolve();
+			});
+
+			watcher.ready.then(() => {
+				fs.writeFileSync(addedFilePath, "export const y = 2;", { encoding: "utf8" });
+			});
+
+			setTimeout(() => {
+				watcher.close();
+				reject(new Error("expected add event was not emitted for new file"));
+			}, 800);
+		});
+	});
+
+	it("emits unlink when a watched file is deleted", async () => {
+		const rootPath = "/workspace/project/src";
+		const removedFilePath = path.join(rootPath, "index.ts");
+
+		fs.mkdirSync(rootPath, { recursive: true });
+		fs.writeFileSync(removedFilePath, "export const v = 1;", { encoding: "utf8" });
+
+		await new Promise<void>((resolve, reject) => {
+			const watcher = watch(rootPath, { ignoreInitial: true });
+
+			watcher.on("unlink", (file) => {
+				if (file.relativePath !== "index.ts") {
+					return;
+				}
+
+				expect(file.fullPath).toBe(removedFilePath);
+				watcher.close();
+				resolve();
+			});
+
+			watcher.ready.then(() => {
+				fs.unlinkSync(removedFilePath);
+			});
+
+			setTimeout(() => {
+				watcher.close();
+				reject(new Error("expected unlink event was not emitted for removed file"));
+			}, 800);
+		});
+	});
+
+	it("applies include patterns to emitted events", async () => {
+		const rootPath = "/workspace/project/src";
+		const ignoredFilePath = path.join(rootPath, "ignored.js");
+		const includedFilePath = path.join(rootPath, "included.ts");
+
+		fs.mkdirSync(rootPath, { recursive: true });
+
+		await new Promise<void>((resolve, reject) => {
+			const watcher = watch(rootPath, { ignoreInitial: true, include: ["**/*.ts"] });
+
+			watcher.on("add", (file) => {
+				if (file.relativePath === "ignored.js") {
+					watcher.close();
+					reject(new Error("include filter emitted ignored.js unexpectedly"));
+					return;
+				}
+
+				if (file.relativePath !== "included.ts") {
+					return;
+				}
+
+				expect(file.fullPath).toBe(includedFilePath);
+				watcher.close();
+				resolve();
+			});
+
+			watcher.ready.then(() => {
+				fs.writeFileSync(ignoredFilePath, "export const ignored = true;", {
+					encoding: "utf8",
+				});
+				fs.writeFileSync(includedFilePath, "export const included = true;", {
+					encoding: "utf8",
+				});
+			});
+
+			setTimeout(() => {
+				watcher.close();
+				reject(new Error("include filter did not emit included.ts"));
+			}, 800);
+		});
+	});
+
+	it("applies ignore patterns to emitted events", async () => {
+		const rootPath = "/workspace/project/src";
+		const ignoredFilePath = path.join(rootPath, "index.spec.ts");
+		const includedFilePath = path.join(rootPath, "index.ts");
+
+		fs.mkdirSync(rootPath, { recursive: true });
+
+		await new Promise<void>((resolve, reject) => {
+			const watcher = watch(rootPath, {
+				ignoreInitial: true,
+				ignore: ["**/*.spec.ts"],
+			});
+
+			watcher.on("add", (file) => {
+				if (file.relativePath === "index.spec.ts") {
+					watcher.close();
+					reject(new Error("ignore filter emitted index.spec.ts unexpectedly"));
+					return;
+				}
+
+				if (file.relativePath !== "index.ts") {
+					return;
+				}
+
+				expect(file.fullPath).toBe(includedFilePath);
+				watcher.close();
+				resolve();
+			});
+
+			watcher.ready.then(() => {
+				fs.writeFileSync(ignoredFilePath, "export const ignored = true;", {
+					encoding: "utf8",
+				});
+				fs.writeFileSync(includedFilePath, "export const included = true;", {
+					encoding: "utf8",
+				});
+			});
+
+			setTimeout(() => {
+				watcher.close();
+				reject(new Error("ignore filter did not emit index.ts"));
+			}, 800);
+		});
+	});
+
+	it("emits ready after watcher initialization", async () => {
+		const rootPath = "/workspace/project/src";
+		fs.mkdirSync(rootPath, { recursive: true });
+		fs.writeFileSync(path.join(rootPath, "index.ts"), "export const v = 1;", {
+			encoding: "utf8",
+		});
+
+		await new Promise<void>((resolve, reject) => {
+			const watcher = watch(rootPath, { ignoreInitial: true });
+
+			watcher.on("ready", () => {
+				watcher.close();
+				resolve();
+			});
+
+			setTimeout(() => {
+				watcher.close();
+				reject(new Error("watcher did not emit ready event"));
+			}, 200);
+		});
+	});
+
+	it("resolves watcher.ready after initialization", async () => {
+		const rootPath = "/workspace/project/src";
+		fs.mkdirSync(rootPath, { recursive: true });
+		const watcher = watch(rootPath, { ignoreInitial: true });
+
+		await expect(watcher.ready).resolves.toBeUndefined();
+		watcher.close();
+	});
+
+	it("emits change only once for a single write", async () => {
+		const rootPath = "/workspace/project/src";
+		const filePath = path.join(rootPath, "index.ts");
+
+		fs.mkdirSync(rootPath, { recursive: true });
+		fs.writeFileSync(filePath, "export const v = 1;", { encoding: "utf8" });
+
+		await new Promise<void>((resolve, reject) => {
+			const watcher = watch(rootPath, { ignoreInitial: true });
+			let changeCount = 0;
+
+			watcher.on("change", (file) => {
+				if (file.relativePath !== "index.ts") {
+					return;
+				}
+
+				changeCount += 1;
+			});
+
+			watcher.ready.then(() => {
+				fs.writeFileSync(filePath, "export const v = 2;", { encoding: "utf8" });
+			});
+
+			setTimeout(() => {
+				watcher.close();
+				try {
+					expect(changeCount).toBeLessThanOrEqual(1);
+					resolve();
+				} catch (error) {
+					reject(error);
+				}
+			}, 300);
+		});
+	});
+});

package/LICENSE

@@ -1,15 +0,0 @@
-ISC License
-
-Copyright (c) 2025-2026 Typesmiths
-
-Permission to use, copy, modify, and/or distribute this software for any
-purpose with or without fee is hereby granted, provided that the above
-copyright notice and this permission notice appear in all copies.
-
-THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
-WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
-MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
-ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
-WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
-ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
-OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/commonjs/src/cli/action.js

@@ -1,65 +0,0 @@
-"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

@@ -1,127 +0,0 @@
-"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

@@ -1,61 +0,0 @@
-"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

@@ -1,18 +0,0 @@
-"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

@@ -1,115 +0,0 @@
-"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");
-    }
-}