@decohere/devkit 0.0.1-dev.119

package/es6/src/interop/pnpm/pnpm.js

@@ -0,0 +1,24 @@
+import { Shell } from "../shell/shell.js";
+const Commands = {
+    install: "install"
+};
+export class Pnpm extends Shell {
+    name = "pnpm";
+    program = "pnpm";
+    async install(options = {
+        cwd: "./"
+    }) {
+        const { cwd } = options;
+        return this.run({
+            cwd
+        }, Commands.install);
+    }
+    async syncLockFile(options = {
+        cwd: "./"
+    }) {
+        const { cwd } = options;
+        return this.run({
+            cwd
+        }, Commands.install, "--lockfile-only", "--ignore-scripts");
+    }
+}

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

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

package/es6/src/interop/shell/shell.argv.js

@@ -0,0 +1,35 @@
+function fields(args) {
+    const positional = [];
+    const flags = {};
+    for(let i = 0; i < args.length; i++){
+        const arg = args[i];
+        if (arg === "--") {
+            positional.push(...args.slice(i + 1));
+            break;
+        }
+        if (arg.startsWith("--")) {
+            const body = arg.slice(2);
+            const eq = body.indexOf("=");
+            if (eq !== -1) {
+                flags[body.slice(0, eq)] = body.slice(eq + 1);
+                continue;
+            }
+            const next = args[i + 1];
+            if (next != null && !next.startsWith("-")) {
+                flags[body] = next;
+                i += 1;
+            } else {
+                flags[body] = true;
+            }
+            continue;
+        }
+        positional.push(arg);
+    }
+    return {
+        _: positional,
+        ...flags
+    };
+}
+export const shellArgv = {
+    fields
+};

package/es6/src/interop/shell/shell.js

@@ -0,0 +1,95 @@
+import { spawn } from "node:child_process";
+import { scribe } from "@decohere/scribe";
+import { InteropError } from "../errors/interop.error.js";
+import { shellArgv } from "./shell.argv.js";
+export class Shell {
+    async run(options, ...args) {
+        const logger = scribe.logger(Shell.name);
+        const argv = args ?? [];
+        const argvFields = shellArgv.fields(argv);
+        const positionals = Array.isArray(argvFields._) ? argvFields._ : [];
+        const commandName = [
+            this.program,
+            ...positionals
+        ].join(" ").trim();
+        logger.info("Running", {
+            program: this.program,
+            args: argvFields
+        });
+        return new Promise((resolve, reject)=>{
+            let settled = false;
+            const resolveOnce = (response)=>{
+                if (settled) {
+                    return;
+                }
+                settled = true;
+                resolve(response);
+            };
+            const rejectOnce = (error)=>{
+                if (settled) {
+                    return;
+                }
+                settled = true;
+                reject(error);
+            };
+            const { cwd, env } = options;
+            const spawnOpt = {
+                cwd: cwd ?? ".",
+                stdio: [
+                    "inherit",
+                    "pipe",
+                    "pipe"
+                ],
+                env: env ?? {
+                    ...process.env
+                }
+            };
+            const proc = spawn(this.program, argv, spawnOpt);
+            const responseData = [];
+            const errorData = [];
+            proc.on("close", (code, signal)=>{
+                if (code === 0) {
+                    resolveOnce({
+                        message: `${commandName} completed`,
+                        data: responseData
+                    });
+                    return;
+                }
+                const stderr = errorData.join("\n").trim();
+                const stdout = responseData.join("\n").trim();
+                const exitCodeText = code == null ? "unknown" : String(code);
+                const signalText = signal ? ` signal ${signal}` : "";
+                const base = `Running '${commandName}' failed with code ${exitCodeText}${signalText}`;
+                const details = [
+                    stderr ? `stderr:\n${stderr}` : "",
+                    !stderr && stdout ? `stdout:\n${stdout}` : ""
+                ].filter(Boolean).join("\n");
+                rejectOnce(new InteropError(details ? `${base}\n${details}` : base));
+            });
+            proc.on("error", (err)=>{
+                rejectOnce(err);
+            });
+            proc.stdout.on("error", (err)=>{
+                rejectOnce(err);
+            });
+            proc.stdout.on("data", (data)=>{
+                const lines = this.parseStream(data);
+                console.log(data.toString());
+                responseData.push(...lines);
+            });
+            proc.stderr?.on("error", (err)=>{
+                rejectOnce(err);
+            });
+            proc.stderr?.on("data", (data)=>{
+                const lines = this.parseStream(data);
+                console.error(data.toString());
+                errorData.push(...lines);
+            });
+        });
+    }
+    parseStream(data) {
+        const dataStr = data.toString();
+        const lines = dataStr.split("\n").filter((l)=>l !== "");
+        return lines;
+    }
+}

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

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

package/es6/src/interop/types/detect-package-manager.js

@@ -0,0 +1,50 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { createInterface } from "node:readline/promises";
+import { Npm } from "../npm/npm.js";
+import { Pnpm } from "../pnpm/pnpm.js";
+import { Yarn } from "../yarn/yarn.js";
+const LOCKFILES = [
+    [
+        "pnpm-lock.yaml",
+        ()=>new Pnpm()
+    ],
+    [
+        "yarn.lock",
+        ()=>new Yarn()
+    ],
+    [
+        "package-lock.json",
+        ()=>new Npm()
+    ]
+];
+function fromLockfile(cwd) {
+    for (const [file, factory] of LOCKFILES){
+        if (existsSync(join(cwd, file))) return factory();
+    }
+    return undefined;
+}
+function fromUserAgent() {
+    const agent = process.env.npm_config_user_agent ?? "";
+    if (agent.startsWith("pnpm")) return new Pnpm();
+    if (agent.startsWith("yarn")) return new Yarn();
+    if (agent.startsWith("npm")) return new Npm();
+    return undefined;
+}
+export function detectPackageManager(cwd) {
+    return fromLockfile(cwd) ?? fromUserAgent();
+}
+export function packageManagerFromString(name) {
+    if (name === "yarn") return new Yarn();
+    if (name === "npm") return new Npm();
+    return new Pnpm();
+}
+export async function promptForPackageManager() {
+    const rl = createInterface({
+        input: process.stdin,
+        output: process.stdout
+    });
+    const answer = await rl.question("Package manager? [pnpm/yarn/npm] (default: pnpm): ");
+    rl.close();
+    return packageManagerFromString(answer.trim().toLowerCase());
+}

package/es6/src/interop/types/package-manager.js

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

package/es6/src/interop/yarn/yarn.js

@@ -0,0 +1,24 @@
+import { Shell } from "../shell/shell.js";
+const Commands = {
+    install: "install"
+};
+export class Yarn extends Shell {
+    name = "yarn";
+    program = "yarn";
+    async install(options = {
+        cwd: "./"
+    }) {
+        const { cwd } = options;
+        return this.run({
+            cwd
+        }, Commands.install);
+    }
+    async syncLockFile(options = {
+        cwd: "./"
+    }) {
+        const { cwd } = options;
+        return this.run({
+            cwd
+        }, Commands.install, "--mode", "update-lockfile", "--ignore-scripts");
+    }
+}

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

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

package/es6/src/io/find-directories.js

@@ -0,0 +1,11 @@
+import { glob } from "glob";
+export async function findDirectories(...pattern) {
+    const paths = await glob(pattern, {
+        withFileTypes: true
+    });
+    const dirs = paths.filter((p)=>p.isDirectory()).map((p)=>({
+            name: p.name,
+            parentPath: p.parentPath
+        }));
+    return dirs;
+}

package/es6/src/io/find-file.js

@@ -0,0 +1,27 @@
+import { glob } from "glob";
+import { FileEx } from "@decohere/core/io";
+export async function findFile(pattern) {
+    const files = await glob(pattern, {
+        includeChildMatches: false
+    });
+    if (files.length === 0) {
+        return;
+    }
+    const file = {
+        relativePath: files.at(0)
+    };
+    return file;
+}
+export async function findFiles(patterns, options) {
+    const paths = await glob(patterns, {
+        ...options,
+        withFileTypes: true
+    });
+    const files = paths.filter((p)=>p.isFile()).map((p)=>{
+        return new FileEx({
+            relativePath: p.relative(),
+            fullPath: p.fullpath()
+        });
+    });
+    return files;
+}

package/es6/src/io/index.js

@@ -0,0 +1,3 @@
+export * from "./find-directories.js";
+export * from "./find-file.js";
+export * from "./watch.js";

package/es6/src/io/watch.js

@@ -0,0 +1,238 @@
+import { watch as nativeWatch, readdirSync, statSync } from "node:fs";
+import path from "node:path";
+import picomatch from "picomatch";
+import { FileEx } from "@decohere/core/io";
+export const WatchEvents = {
+    add: "add",
+    change: "change",
+    addDir: "addDir",
+    unlink: "unlink",
+    unlinkDir: "unlinkDir"
+};
+export function watch(directory, options = {
+    cwd: "."
+}) {
+    const { include, ignore, ignoreInitial = false } = options;
+    const changeCoalesceMs = 25;
+    const handlers = {
+        ready: new Set(),
+        add: new Set(),
+        change: new Set(),
+        addDir: new Set(),
+        unlink: new Set(),
+        unlinkDir: new Set()
+    };
+    let resolveReady;
+    const ready = new Promise((resolve)=>{
+        resolveReady = resolve;
+    });
+    const snapshot = buildSnapshot(directory);
+    const isFiltered = (relativePath)=>{
+        const posixRelativePath = toPosixPath(relativePath);
+        const posixFullPath = toPosixPath(path.resolve(directory, relativePath));
+        const matchesEitherPath = (patterns)=>picomatch.isMatch(posixRelativePath, patterns) || picomatch.isMatch(posixFullPath, patterns);
+        if (include && include.length > 0) {
+            return !matchesEitherPath(include);
+        }
+        if (ignore && ignore.length > 0) {
+            return matchesEitherPath(ignore);
+        }
+        return false;
+    };
+    const emit = (event, relativePath)=>{
+        if (isFiltered(relativePath)) {
+            return;
+        }
+        const fullPath = path.resolve(directory, relativePath);
+        for (const handler of handlers[event]){
+            handler(new FileEx({
+                fullPath,
+                relativePath
+            }));
+        }
+    };
+    const pendingChangeTimers = new Map();
+    const emitChange = (relativePath)=>{
+        const existing = pendingChangeTimers.get(relativePath);
+        if (existing != null) {
+            clearTimeout(existing);
+        }
+        const timer = setTimeout(()=>{
+            pendingChangeTimers.delete(relativePath);
+            emit("change", relativePath);
+        }, changeCoalesceMs);
+        pendingChangeTimers.set(relativePath, timer);
+    };
+    const emitReady = ()=>{
+        for (const handler of handlers.ready){
+            handler();
+        }
+    };
+    queueMicrotask(()=>{
+        if (!ignoreInitial) {
+            for (const [relativePath, entry] of snapshot){
+                emit(entry.isDirectory ? "addDir" : "add", relativePath);
+            }
+        }
+        emitReady();
+        resolveReady?.();
+        resolveReady = undefined;
+    });
+    // One non-recursive watcher per directory. Node's recursive mode on Linux tracks files
+    // individually and goes silent for a file once an editor replaces it with an atomic save
+    // (write temp file, rename over the original); directory watchers keep seeing it (#505).
+    const directoryWatchers = new Map();
+    const watchDirectory = (relativeDir)=>{
+        if (directoryWatchers.has(relativeDir)) {
+            return;
+        }
+        try {
+            const watcher = nativeWatch(path.resolve(directory, relativeDir), (_eventType, fileName)=>{
+                if (fileName != null) {
+                    onFsEvent(path.posix.join(relativeDir, toPosixPath(fileName.toString())));
+                }
+            });
+            watcher.on("error", ()=>unwatchDirectory(relativeDir));
+            directoryWatchers.set(relativeDir, watcher);
+        } catch  {
+        // The directory vanished before we could watch it; its unlink event covers it.
+        }
+    };
+    const unwatchDirectory = (relativeDir)=>{
+        for (const [watchedDir, watcher] of directoryWatchers){
+            if (watchedDir === relativeDir || watchedDir.startsWith(`${relativeDir}/`)) {
+                watcher.close();
+                directoryWatchers.delete(watchedDir);
+            }
+        }
+    };
+    /** A directory appeared: watch it, and report what was created in it before we were watching. */ const addDirectory = (relativeDir)=>{
+        watchDirectory(relativeDir);
+        const found = new Map();
+        try {
+            collectSnapshotEntries(directory, path.resolve(directory, relativeDir), found);
+        } catch  {
+            return;
+        }
+        for (const [relativePath, entry] of found){
+            if (snapshot.has(relativePath)) continue;
+            snapshot.set(relativePath, entry);
+            if (entry.isDirectory) watchDirectory(relativePath);
+            emit(entry.isDirectory ? "addDir" : "add", relativePath);
+        }
+    };
+    /** A directory went away: stop watching it and forget everything that was under it. */ const removeDirectoryContents = (relativeDir)=>{
+        unwatchDirectory(relativeDir);
+        // oxlint-disable-next-line unicorn/no-useless-spread -- iterate a copy: the loop deletes from the snapshot
+        for (const [relativePath, entry] of [
+            ...snapshot
+        ]){
+            if (relativePath.startsWith(`${relativeDir}/`)) {
+                snapshot.delete(relativePath);
+                emit(entry.isDirectory ? "unlinkDir" : "unlink", relativePath);
+            }
+        }
+    };
+    const onFsEvent = (eventPath)=>{
+        const relativePath = eventPath === "." ? "" : eventPath;
+        if (relativePath.length === 0) {
+            return;
+        }
+        const fullPath = path.resolve(directory, relativePath);
+        const previous = snapshot.get(relativePath);
+        try {
+            const stat = statSync(fullPath);
+            const current = toSnapshotEntry(stat);
+            snapshot.set(relativePath, current);
+            if (previous == null) {
+                emit(current.isDirectory ? "addDir" : "add", relativePath);
+                if (current.isDirectory) addDirectory(relativePath);
+                return;
+            }
+            if (previous.isDirectory !== current.isDirectory) {
+                if (previous.isDirectory) removeDirectoryContents(relativePath);
+                emit(previous.isDirectory ? "unlinkDir" : "unlink", relativePath);
+                emit(current.isDirectory ? "addDir" : "add", relativePath);
+                return;
+            }
+            if (!current.isDirectory && previous.fingerprint !== current.fingerprint) {
+                emitChange(relativePath);
+            }
+        } catch  {
+            if (previous == null) {
+                return;
+            }
+            snapshot.delete(relativePath);
+            const pending = pendingChangeTimers.get(relativePath);
+            if (pending != null) {
+                clearTimeout(pending);
+                pendingChangeTimers.delete(relativePath);
+            }
+            emit(previous.isDirectory ? "unlinkDir" : "unlink", relativePath);
+        }
+    };
+    watchDirectory("");
+    for (const [relativePath, entry] of snapshot){
+        if (entry.isDirectory) watchDirectory(relativePath);
+    }
+    const watchApi = {
+        ready,
+        on (event, handler) {
+            if (event === "ready") {
+                handlers.ready.add(handler);
+                return watchApi;
+            }
+            handlers[event].add(handler);
+            return watchApi;
+        },
+        close: ()=>{
+            for (const pending of pendingChangeTimers.values()){
+                clearTimeout(pending);
+            }
+            pendingChangeTimers.clear();
+            for (const watcher of directoryWatchers.values()){
+                watcher.close();
+            }
+            directoryWatchers.clear();
+        }
+    };
+    return watchApi;
+}
+function buildSnapshot(directoryPath) {
+    const snapshot = new Map();
+    collectSnapshotEntries(directoryPath, directoryPath, snapshot);
+    return snapshot;
+}
+/** Never source, and huge: watching every folder inside them could exhaust OS watch limits. */ const UNWATCHED_DIRECTORIES = new Set([
+    "node_modules",
+    ".git"
+]);
+function collectSnapshotEntries(rootDirectoryPath, currentDirectoryPath, snapshot) {
+    for (const entry of readdirSync(currentDirectoryPath, {
+        encoding: "utf8"
+    })){
+        const name = typeof entry === "string" ? entry : String(entry);
+        const fullPath = path.join(currentDirectoryPath, name);
+        if (UNWATCHED_DIRECTORIES.has(name)) {
+            continue;
+        }
+        const relativePath = toPosixPath(path.relative(rootDirectoryPath, fullPath));
+        const stat = statSync(fullPath);
+        const snapshotEntry = toSnapshotEntry(stat);
+        snapshot.set(relativePath, snapshotEntry);
+        if (!snapshotEntry.isDirectory) {
+            continue;
+        }
+        collectSnapshotEntries(rootDirectoryPath, fullPath, snapshot);
+    }
+}
+function toSnapshotEntry(stat) {
+    const isDirectory = stat.isDirectory();
+    return {
+        isDirectory,
+        fingerprint: isDirectory ? `dir:${stat.mtimeMs}` : `file:${stat.mtimeMs}:${stat.size}`
+    };
+}
+function toPosixPath(filePath) {
+    return filePath.split(path.sep).join(path.posix.sep);
+}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@decohere/devkit",
+  "version": "0.0.1-dev.119",
+  "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",
+    "cli",
+    "commander",
+    "tooling",
+    "decohere"
+  ],
+  "license": "ISC",
+  "author": "Typesmiths",
+  "type": "module",
+  "main": "index.js",
+  "exports": {
+    "./cli": {
+      "types": "./types/src/cli/index.d.ts",
+      "import": "./es6/src/cli/index.js",
+      "require": "./commonjs/src/cli/index.js"
+    },
+    "./diagnostics": {
+      "types": "./types/src/diagnostics/index.d.ts",
+      "import": "./es6/src/diagnostics/index.js",
+      "require": "./commonjs/src/diagnostics/index.js"
+    },
+    "./interop": {
+      "types": "./types/src/interop/index.d.ts",
+      "import": "./es6/src/interop/index.js",
+      "require": "./commonjs/src/interop/index.js"
+    },
+    "./io": {
+      "types": "./types/src/io/index.d.ts",
+      "import": "./es6/src/io/index.js",
+      "require": "./commonjs/src/io/index.js"
+    }
+  },
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "dependencies": {
+    "@decohere/core": "0.0.1-dev.119",
+    "@decohere/scribe": "0.0.1-dev.119",
+    "commander": "^13.1.0",
+    "glob": "^13.0.1",
+    "picomatch": "^4.0.4"
+  },
+  "devDependencies": {}
+}

package/types/src/cli/action.d.ts

@@ -0,0 +1,36 @@
+import type { Constructable } from "@decohere/core/reflection";
+import type { UnionToIntersection } from "@decohere/core/system";
+export declare const ActionMap: unique symbol;
+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 declare class ActionResponse<TData = unknown> implements Result {
+    static Success<TData>(name: string, data?: TData[]): ActionResponse<TData>;
+    static Skipped(name: string): ActionResponse<unknown>;
+    static Blocking(name: string): ActionResponse<unknown>;
+    static Error<TData = unknown>(name: string, message: string): ActionResponse<TData>;
+    static Error<TData extends ResultStatus>(name: string, data: TData[]): ActionResponse<TData>;
+    constructor(data: Partial<ActionResponse<TData>>);
+    readonly name: string;
+    readonly succeeded: boolean;
+    readonly skipped: boolean;
+    readonly blocking: boolean;
+    readonly message: string;
+    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/types/src/cli/command.d.ts

@@ -0,0 +1,34 @@
+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 declare const CommandResponse: {
+    success<T extends Actions>(_ctx: unknown, responses: CommandResponse<T>): CommandResponse<T>;
+    help<T extends Actions = Actions>(): CommandResponse<T>;
+    fromAction(name: string, response: ActionResponse): CommandResponse;
+};
+/** Thrown when a command execution fails due to action errors. */
+export declare class CommandError extends Error {
+}
+export declare class DecohereCommand<TActions extends Actions = Actions> extends CommanderType {
+    get actions(): readonly Constructable<import("./action.js").Action>[];
+    constructor(name?: string | Constructable | Record<string, CommandType>, handler?: CommandHandler);
+    /**
+     * 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: OptionValues): boolean;
+    run(actions: TActions, options: OptionValues): Promise<CommandResponse<TActions>>;
+    registerSubcommand(command: CommandType, onAction?: CommandHandler): void;
+    registerSubcommand(commands: Record<string, DecohereCommand | CommandType>, onAction?: CommandHandler): void;
+    protected runActions(actions: TActions, options: OptionValues): Promise<CommandResponse<TActions>>;
+    protected getSelectedActions(actions: TActions): Array<[keyof TActions, TActions[keyof TActions]]>;
+    protected throwOnErrors(responses: CommandResponse<TActions>): void;
+    private parseCommandName;
+}

package/types/src/cli/index.d.ts

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