@metreeca/rack 0.4.0 → 0.6.0

package/README.md

@@ -10,10 +10,13 @@ package consumes a single maintained copy instead of carrying its own. Tools are
 | Subpath                     | Contents     |
 |-----------------------------|--------------|
 | [@metreeca/rack/tool][tool] | CLI tools    |
+| [@metreeca/rack/node][node] | Node hooks   |
 | [@metreeca/rack/vite][vite] | Vite plugins |
 
 [tool]: https://metreeca.github.io/rack/modules/tool.html
 
+[node]: https://metreeca.github.io/rack/modules/node.html
+
 [vite]: https://metreeca.github.io/rack/modules/vite.html
 
 # Installation

package/dist/node/index.d.ts

@@ -0,0 +1,3 @@
+import { customConditions, symlinks } from "./symlinks.js";
+export { symlinks, customConditions };
+//# sourceMappingURL=index.d.ts.map

package/dist/node/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/node/index.ts"],"names":[],"mappings":"AAoCA,OAAO,EAAE,gBAAgB,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAE3D,OAAO,EAAE,QAAQ,EAAE,gBAAgB,EAAE,CAAC"}

package/dist/node/index.js

@@ -0,0 +1,38 @@
+/*
+ * Copyright © 2026 Metreeca srl
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * Node module hooks running a process against the live source of locally linked packages, with no rebuild.
+ *
+ * Importing this module registers the {@link symlinks} hooks for the rest of the process, with the `customConditions`
+ * of the `tsconfig.json` nearest to the current working directory. Node then resolves locally linked packages to the
+ * same sources the IDE does. The module must load before any module it resolves, through the `--import` option given
+ * on the command line, in an npm script or in the Node.js run configuration template of the IDE:
+ *
+ * ```shell
+ * node --import @metreeca/rack/node src/index.ts
+ * ```
+ *
+ * Plain `node` runs TypeScript sources through its built-in type stripping, which supports erasable syntax only.
+ * Sources using `enum`, `namespace` or parameter properties need a loader such as `tsx` registered ahead of the
+ * hooks, as in `node --import tsx --import @metreeca/rack/node` or `tsx --import @metreeca/rack/node`.
+ *
+ * @module
+ */
+import { registerHooks } from "node:module";
+import { customConditions, symlinks } from "./symlinks.js";
+export { symlinks, customConditions };
+registerHooks(symlinks({ conditions: customConditions(process.cwd()) }));
+//# sourceMappingURL=index.js.map

package/dist/node/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/node/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,gBAAgB,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAE3D,OAAO,EAAE,QAAQ,EAAE,gBAAgB,EAAE,CAAC;AAGtC,aAAa,CAAC,QAAQ,CAAC,EAAE,UAAU,EAAE,gBAAgB,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC"}

package/dist/node/symlinks.d.ts

@@ -0,0 +1,54 @@
+import type { ResolveHookSync } from "node:module";
+/**
+ * Creates module hooks running a Node process against the live source of locally linked packages, with no rebuild.
+ *
+ * Imports of workspace members and of sibling checkouts linked into `node_modules` resolve to their TypeScript source,
+ * which Node runs through its built-in type stripping, so edits are picked up as they are saved. Packages installed
+ * from the registry keep resolving to their build, as do packages whose `exports` name none of the conditions.
+ *
+ * Packages are looked up as Node does, from the `node_modules` nearest to the importer up through its ancestors;
+ * imports with no importer start from the root. A linked checkout importing a package the project links as well
+ * loads the linked source rather than the registry copy it installs for itself, so the two never diverge.
+ *
+ * The process loads a single copy of every linked package and of each of their `peerDependencies`, as libraries
+ * holding module state such as Preact hooks require. Those packages resolve from the root, whatever copies a linked
+ * checkout installs for itself, and from the importer only where the root does not install them. Other dependencies
+ * of a linked package resolve from its checkout, as Node does, since the process loads no other copy of them.
+ *
+ * Relative imports of a `.js` file from a TypeScript module, as `NodeNext` module resolution requires, resolve to the
+ * `.ts` file next to it when the `.js` file does not exist. Sources compiled to `dist` thus run from `src` under plain
+ * `node`, with no loader such as `tsx`. Where such a loader is registered as well, the imports it resolves are left
+ * to it, and the hooks only add the resolution of linked packages to their TypeScript source.
+ *
+ * The hooks take effect once registered with `registerHooks` from `node:module`, before the first import they have
+ * to resolve, typically from a module loaded with `--import`. Importing `@metreeca/rack/node` registers them with the
+ * conditions of the `tsconfig.json` nearest to the current working directory, with no setup module to write.
+ *
+ * @param options The resolution settings
+ *
+ * @returns Synchronous module hooks resolving linked imports to source, deduplicating linked packages and their
+ * peers, mapping `.js` relative imports to their `.ts` sources, and leaving all other imports to the default resolution
+ */
+export declare function symlinks({ conditions, root }: {
+    /**
+     * The export conditions mapping each subpath to its source file, as listed in `customConditions`; where a package
+     * matches more than one, the key order of its own `exports` decides which applies.
+     */
+    conditions: string | readonly string[];
+    /**
+     * The project root the linked packages and their peers resolve from; defaults to the current working directory.
+     */
+    root?: string;
+}): Readonly<{
+    resolve: ResolveHookSync;
+}>;
+/**
+ * Reads the custom export conditions a project asks its TypeScript language service to resolve.
+ *
+ * @param directory The directory the search for `tsconfig.json` starts from, walking up through its ancestors
+ *
+ * @returns The `customConditions` of the nearest `tsconfig.json`, read through its `extends` chain where it declares
+ * none of its own; empty if no configuration is found or none declares any, so that linked packages resolve to `dist`
+ */
+export declare function customConditions(directory: string): readonly string[];
+//# sourceMappingURL=symlinks.d.ts.map

package/dist/node/symlinks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"symlinks.d.ts","sourceRoot":"","sources":["../../src/node/symlinks.ts"],"names":[],"mappings":"AAiBA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAOnD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,QAAQ,CAAC,EAExB,UAAU,EACV,IAAoB,EAEpB,EAAE;IAEF;;;OAGG;IACH,UAAU,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CAAA;IAEtC;;OAEG;IACH,IAAI,CAAC,EAAE,MAAM,CAAA;CAEb,GAAG,QAAQ,CAAC;IAAE,OAAO,EAAE,eAAe,CAAA;CAAE,CAAC,CAgGzC;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CA2BrE"}

package/dist/node/symlinks.js

@@ -0,0 +1,134 @@
+/*
+ * Copyright © 2026 Metreeca srl
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { existsSync, readFileSync, realpathSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { exports } from "resolve.exports";
+import { bare, lookup, manifest, shared } from "../symlinks.js";
+/**
+ * Creates module hooks running a Node process against the live source of locally linked packages, with no rebuild.
+ *
+ * Imports of workspace members and of sibling checkouts linked into `node_modules` resolve to their TypeScript source,
+ * which Node runs through its built-in type stripping, so edits are picked up as they are saved. Packages installed
+ * from the registry keep resolving to their build, as do packages whose `exports` name none of the conditions.
+ *
+ * Packages are looked up as Node does, from the `node_modules` nearest to the importer up through its ancestors;
+ * imports with no importer start from the root. A linked checkout importing a package the project links as well
+ * loads the linked source rather than the registry copy it installs for itself, so the two never diverge.
+ *
+ * The process loads a single copy of every linked package and of each of their `peerDependencies`, as libraries
+ * holding module state such as Preact hooks require. Those packages resolve from the root, whatever copies a linked
+ * checkout installs for itself, and from the importer only where the root does not install them. Other dependencies
+ * of a linked package resolve from its checkout, as Node does, since the process loads no other copy of them.
+ *
+ * Relative imports of a `.js` file from a TypeScript module, as `NodeNext` module resolution requires, resolve to the
+ * `.ts` file next to it when the `.js` file does not exist. Sources compiled to `dist` thus run from `src` under plain
+ * `node`, with no loader such as `tsx`. Where such a loader is registered as well, the imports it resolves are left
+ * to it, and the hooks only add the resolution of linked packages to their TypeScript source.
+ *
+ * The hooks take effect once registered with `registerHooks` from `node:module`, before the first import they have
+ * to resolve, typically from a module loaded with `--import`. Importing `@metreeca/rack/node` registers them with the
+ * conditions of the `tsconfig.json` nearest to the current working directory, with no setup module to write.
+ *
+ * @param options The resolution settings
+ *
+ * @returns Synchronous module hooks resolving linked imports to source, deduplicating linked packages and their
+ * peers, mapping `.js` relative imports to their `.ts` sources, and leaving all other imports to the default resolution
+ */
+export function symlinks({ conditions, root = process.cwd() }) {
+    const $conditions = typeof conditions === "string" ? [conditions] : conditions;
+    const names = new Set(shared(root)); // the packages resolved from the root, whoever imports them
+    return {
+        resolve(specifier, context, next) {
+            const { parentURL } = context;
+            const parent = parentURL?.startsWith("file:") ? fileURLToPath(parentURL) : undefined;
+            const base = parent === undefined ? root : dirname(parent);
+            const name = bare(specifier);
+            const link = name === undefined ? undefined : lookup(name, base) ?? lookup(name, root);
+            if (link !== undefined) {
+                const path = realpathSync(link);
+                const target = source(path, specifier, context.conditions);
+                return target === undefined
+                    ? next(specifier, context) // subpath not exported or excluded by a null target: node reports it
+                    : { url: pathToFileURL(resolve(path, target)).href, shortCircuit: true };
+            }
+            else if (name !== undefined && names.has(name)) {
+                return rooted(specifier, context, next);
+            }
+            else if (parent?.endsWith(".ts") && /^\.\.?\/.*\.js$/.test(specifier)) {
+                return sibling(specifier, context, next, resolve(base, specifier).replace(/\.js$/, ".ts"));
+            }
+            else {
+                return next(specifier, context);
+            }
+        }
+    };
+    function source(path, specifier, conditions) {
+        try {
+            return exports(manifest(path), specifier, {
+                conditions: $conditions,
+                require: conditions.includes("require")
+            })?.[0];
+        }
+        catch { // subpath not exported or excluded by a null target
+            return undefined;
+        }
+    }
+    function rooted(specifier, context, next) {
+        try {
+            return next(specifier, { ...context, parentURL: pathToFileURL(join(root, "package.json")).href });
+        }
+        catch { // not installed by the root: falls back to the importer
+            return next(specifier, context);
+        }
+    }
+    function sibling(specifier, context, next, path) {
+        try {
+            return next(specifier, context);
+        }
+        catch (error) { // the .js file does not exist: a .ts file next to it is the source
+            if (existsSync(path)) {
+                return { url: pathToFileURL(path).href, shortCircuit: true };
+            }
+            else {
+                throw error;
+            }
+        }
+    }
+}
+/**
+ * Reads the custom export conditions a project asks its TypeScript language service to resolve.
+ *
+ * @param directory The directory the search for `tsconfig.json` starts from, walking up through its ancestors
+ *
+ * @returns The `customConditions` of the nearest `tsconfig.json`, read through its `extends` chain where it declares
+ * none of its own; empty if no configuration is found or none declares any, so that linked packages resolve to `dist`
+ */
+export function customConditions(directory) {
+    const config = join(directory, "tsconfig.json");
+    const parent = dirname(directory);
+    return existsSync(config) ? declared(config)
+        : parent === directory ? []
+            : customConditions(parent);
+    function declared(config) {
+        const { extends: base, compilerOptions } = JSON.parse(readFileSync(config, "utf8")); // trusted local file, not validated
+        const conditions = compilerOptions?.customConditions;
+        return conditions !== undefined ? conditions
+            : base !== undefined && existsSync(resolve(dirname(config), base)) ? declared(resolve(dirname(config), base))
+                : [];
+    }
+}
+//# sourceMappingURL=symlinks.js.map

package/dist/node/symlinks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"symlinks.js","sourceRoot":"","sources":["../../src/node/symlinks.ts"],"names":[],"mappings":"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"}

package/dist/symlinks.d.ts

@@ -0,0 +1,49 @@
+import type { Package } from "resolve.exports";
+/**
+ * The package manifest fields the linked package resolvers and the `ln` command rely on.
+ */
+export type Manifest = Package & Readonly<{
+    bin?: string | Readonly<Record<string, string>>;
+    workspaces?: readonly string[];
+    dependencies?: Readonly<Record<string, string>>;
+    devDependencies?: Readonly<Record<string, string>>;
+    peerDependencies?: Readonly<Record<string, string>>;
+    optionalDependencies?: Readonly<Record<string, string>>;
+}>;
+/**
+ * Matches the package name a module specifier starts with.
+ *
+ * @param specifier The module specifier to match
+ *
+ * @returns The scoped or bare package name opening `specifier`, subpath excluded; `undefined` for relative and
+ * absolute paths, for URLs and for `node:` builtins, which no `node_modules` lookup can resolve
+ */
+export declare function bare(specifier: string): string | undefined;
+/**
+ * Looks a package up as Node does, from the `node_modules` nearest to a directory up through its ancestors.
+ *
+ * @param name The name of the package to look up
+ * @param directory The directory the lookup starts from
+ *
+ * @returns The path of the `node_modules` entry of `name`, if it is a symbolic link; `undefined` if the package is
+ * not found or is an installed copy, which the default resolution handles as it does for any registry package
+ */
+export declare function lookup(name: string, directory: string): string | undefined;
+/**
+ * Lists the packages a project loads a single copy of.
+ *
+ * @param root The project root
+ *
+ * @returns The names of the packages linked into the `node_modules` of `root`, of its ancestors and of its workspace
+ * members, along with the names of their `peerDependencies`, without duplicates
+ */
+export declare function shared(root: string): readonly string[];
+/**
+ * Reads a package manifest.
+ *
+ * @param path The path of the package folder
+ *
+ * @returns The manifest of the package at `path`, read once per process for each distinct `path`
+ */
+export declare function manifest(path: string): Manifest;
+//# sourceMappingURL=symlinks.d.ts.map

package/dist/symlinks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"symlinks.d.ts","sourceRoot":"","sources":["../src/symlinks.ts"],"names":[],"mappings":"AAmBA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAC;AAW/C;;GAEG;AACH,MAAM,MAAM,QAAQ,GAAG,OAAO,GAAG,QAAQ,CAAC;IAEzC,GAAG,CAAC,EAAE,MAAM,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;IAC/C,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IAE9B,YAAY,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;IAC/C,eAAe,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;IAClD,gBAAgB,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;IACnD,oBAAoB,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;CAEvD,CAAC,CAAC;AAKH;;;;;;;GAOG;AACH,wBAAgB,IAAI,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAE1D;AAED;;;;;;;;GAQG;AACH,wBAAgB,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAQ1E;AAED;;;;;;;GAOG;AACH,wBAAgB,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CA6CtD;AAED;;;;;;GAMG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,QAAQ,CAkB/C"}

package/dist/symlinks.js

@@ -0,0 +1,107 @@
+/*
+ * Copyright © 2026 Metreeca srl
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { existsSync, globSync, lstatSync, readdirSync, readFileSync, realpathSync, statSync } from "node:fs";
+import { createRequire } from "node:module";
+import { join, parse, relative, sep } from "node:path";
+/**
+ * The package manifests read by {@link manifest}, keyed by package folder path and retained for the process lifetime.
+ */
+const manifests = new Map();
+////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
+/**
+ * Matches the package name a module specifier starts with.
+ *
+ * @param specifier The module specifier to match
+ *
+ * @returns The scoped or bare package name opening `specifier`, subpath excluded; `undefined` for relative and
+ * absolute paths, for URLs and for `node:` builtins, which no `node_modules` lookup can resolve
+ */
+export function bare(specifier) {
+    return specifier.match(/^(?![./]|[a-z]+:)(@[^/]+\/)?[^/]+/i)?.[0];
+}
+/**
+ * Looks a package up as Node does, from the `node_modules` nearest to a directory up through its ancestors.
+ *
+ * @param name The name of the package to look up
+ * @param directory The directory the lookup starts from
+ *
+ * @returns The path of the `node_modules` entry of `name`, if it is a symbolic link; `undefined` if the package is
+ * not found or is an installed copy, which the default resolution handles as it does for any registry package
+ */
+export function lookup(name, directory) {
+    const path = (createRequire(join(directory, sep)).resolve.paths(name) ?? []) // trailing separator: a folder, not a file
+        .map(modules => join(modules, name))
+        .find(candidate => lstatSync(candidate, { throwIfNoEntry: false }));
+    return path !== undefined && lstatSync(path).isSymbolicLink() ? path : undefined;
+}
+/**
+ * Lists the packages a project loads a single copy of.
+ *
+ * @param root The project root
+ *
+ * @returns The names of the packages linked into the `node_modules` of `root`, of its ancestors and of its workspace
+ * members, along with the names of their `peerDependencies`, without duplicates
+ */
+export function shared(root) {
+    return [...new Set(links().flatMap(link => {
+            const { name, peerDependencies } = manifest(realpathSync(link));
+            return [name, ...Object.keys(peerDependencies ?? {})];
+        }))];
+    function links() {
+        return [...ancestors(), ...members()]
+            .map(directory => join(directory, "node_modules"))
+            .flatMap(modules => children(modules)
+            .filter(entry => !entry.startsWith(".")) // hidden entries such as .bin
+            .flatMap(entry => entry.startsWith("@")
+            ? children(join(modules, entry)).map(name => join(modules, entry, name))
+            : [join(modules, entry)])
+            .filter(entry => lstatSync(entry).isSymbolicLink()));
+    }
+    function ancestors() {
+        const { root: base } = parse(root);
+        const segments = relative(base, root).split(sep).filter(Boolean);
+        return segments.map((_, index) => join(base, ...segments.slice(0, segments.length - index)));
+    }
+    function members() {
+        return existsSync(join(root, "package.json"))
+            ? (manifest(root).workspaces ?? [])
+                .flatMap(pattern => globSync(pattern, { cwd: root }))
+                .map(member => join(root, member))
+            : [];
+    }
+    function children(path) {
+        return statSync(path, { throwIfNoEntry: false })?.isDirectory() ? readdirSync(path) : [];
+    }
+}
+/**
+ * Reads a package manifest.
+ *
+ * @param path The path of the package folder
+ *
+ * @returns The manifest of the package at `path`, read once per process for each distinct `path`
+ */
+export function manifest(path) {
+    const cached = manifests.get(path);
+    if (cached === undefined) {
+        const loaded = JSON.parse(readFileSync(join(path, "package.json"), "utf8")); // trusted local file
+        manifests.set(path, loaded);
+        return loaded;
+    }
+    else {
+        return cached;
+    }
+}
+//# sourceMappingURL=symlinks.js.map

package/dist/symlinks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"symlinks.js","sourceRoot":"","sources":["../src/symlinks.ts"],"names":[],"mappings":"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"}

package/dist/tool/cp.d.ts

@@ -1,21 +1,22 @@
-#!/usr/bin/env node
 /**
  * Copies the files matching a set of glob patterns into a target directory, keeping their relative layout.
  *
+ * Runs on the command line as `ush cp <target> <pattern>...`.
+ *
  * Each match lands under `target` at its path relative to the base of its pattern, that is the leading segments free
  * of glob characters: `src/**\/*.css` copies `src/a/b.css` to `<target>/a/b.css`, and a plain file path copies the
  * file to the top of `target`. Missing directories are created and existing files are overwritten.
  *
  * Directories matched by a pattern are skipped: only files are copied.
  *
- * Each copied file is printed on stdout, one per line, by its source path as the pattern matched it.
+ * Each copied file is printed on stdout as `cp <source>`, with the source path spelled as the pattern matched it.
  *
  * @example
  *
  * Shipping stylesheets next to the compiled modules, from an npm script:
  *
  * ```shell
- * cp dist 'src/**\/*.css'
+ * ush cp dist 'src/**\/*.css'
  * ```
  *
  * Patterns are quoted so that they reach the tool unexpanded, as shells differ in their glob support.
@@ -27,4 +28,7 @@
  * @throws Error If a pattern matches no file, in which case no file is copied for any of the patterns
  */
 export declare function cp(target: string, ...patterns: readonly string[]): void;
+export declare namespace cp {
+    var usage: string;
+}
 //# sourceMappingURL=cp.d.ts.map

package/dist/tool/cp.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cp.d.ts","sourceRoot":"","sources":["../../src/tool/cp.ts"],"names":[],"mappings":";AA8BA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,QAAQ,EAAE,SAAS,MAAM,EAAE,GAAG,IAAI,CAiCvE"}
+{"version":3,"file":"cp.d.ts","sourceRoot":"","sources":["../../src/tool/cp.ts"],"names":[],"mappings":"AA4BA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,QAAQ,EAAE,SAAS,MAAM,EAAE,GAAG,IAAI,CAiCvE;yBAjCe,EAAE"}

package/dist/tool/cp.js

@@ -1,4 +1,3 @@
-#!/usr/bin/env node
 /*
  * Copyright © 2026 Metreeca srl
  *
@@ -16,28 +15,30 @@
  */
 import { copyFileSync, globSync, mkdirSync, statSync } from "node:fs";
 import { dirname, join, relative } from "node:path";
-import { cli } from "./index.core.js";
-if (import.meta.main) {
-    process.exitCode = cli(cp, "<target> <pattern>...");
-}
+/**
+ * The command line synopsis of {@link cp}, printed by `ush cp --help`.
+ */
+cp.usage = "<target> <pattern>...";
 ////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
 /**
  * Copies the files matching a set of glob patterns into a target directory, keeping their relative layout.
  *
+ * Runs on the command line as `ush cp <target> <pattern>...`.
+ *
  * Each match lands under `target` at its path relative to the base of its pattern, that is the leading segments free
  * of glob characters: `src/**\/*.css` copies `src/a/b.css` to `<target>/a/b.css`, and a plain file path copies the
  * file to the top of `target`. Missing directories are created and existing files are overwritten.
  *
  * Directories matched by a pattern are skipped: only files are copied.
  *
- * Each copied file is printed on stdout, one per line, by its source path as the pattern matched it.
+ * Each copied file is printed on stdout as `cp <source>`, with the source path spelled as the pattern matched it.
  *
  * @example
  *
  * Shipping stylesheets next to the compiled modules, from an npm script:
  *
  * ```shell
- * cp dist 'src/**\/*.css'
+ * ush cp dist 'src/**\/*.css'
  * ```
  *
  * Patterns are quoted so that they reach the tool unexpanded, as shells differ in their glob support.
@@ -58,7 +59,7 @@ export function cp(target, ...patterns) {
     patterns.flatMap(copies).forEach(({ source, destination }) => {
         mkdirSync(dirname(destination), { recursive: true });
         copyFileSync(source, destination);
-        console.log(source);
+        console.log(`cp ${source}`);
     });
     function copies(pattern) {
         const sources = globSync(pattern).filter(source => statSync(source).isFile());

package/dist/tool/cp.js.map

@@ -1 +1 @@
-{"version":3,"file":"cp.js","sourceRoot":"","sources":["../../src/tool/cp.ts"],"names":[],"mappings":";AAEA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,YAAY,EAAE,QAAQ,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AACtE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AACpD,OAAO,EAAE,GAAG,EAAE,MAAM,iBAAiB,CAAC;AAGtC,IAAK,MAAM,CAAC,IAAI,CAAC,IAAI,EAAG,CAAC;IACxB,OAAO,CAAC,QAAQ,GAAG,GAAG,CAAC,EAAE,EAAE,uBAAuB,CAAC,CAAC;AACrD,CAAC;AAGD,wHAAwH;AAExH;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,UAAU,EAAE,CAAC,MAAc,EAAE,GAAG,QAA2B;IAEhE,IAAK,CAAC,MAAM,EAAG,CAAC;QACf,MAAM,IAAI,SAAS,CAAC,wBAAwB,CAAC,CAAC;IAC/C,CAAC;IAED,IAAK,CAAC,QAAQ,CAAC,MAAM,EAAG,CAAC;QACxB,MAAM,IAAI,SAAS,CAAC,yBAAyB,CAAC,CAAC;IAChD,CAAC;IAED,QAAQ,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,OAAO,CAAC,CAAC,EAAE,MAAM,EAAE,WAAW,EAAE,EAAE,EAAE;QAC5D,SAAS,CAAC,OAAO,CAAC,WAAW,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QACrD,YAAY,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;QAClC,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;IACrB,CAAC,CAAC,CAAC;IAGH,SAAS,MAAM,CAAC,OAAe;QAE9B,MAAM,OAAO,GAAG,QAAQ,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC;QAE9E,IAAK,CAAC,OAAO,CAAC,MAAM,EAAG,CAAC;YACvB,MAAM,IAAI,KAAK,CAAC,sBAAsB,OAAO,GAAG,CAAC,CAAC;QACnD,CAAC;QAED,MAAM,QAAQ,GAAG,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QACpC,MAAM,IAAI,GAAG,QAAQ,CAAC,SAAS,CAAC,OAAO,CAAC,EAAE,CAAC,WAAW,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC;QACtE,MAAM,IAAI,GAAG,IAAI,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,GAAG,CAAC;QAEpF,OAAO,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,WAAW,EAAE,IAAI,CAAC,MAAM,EAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IAE/F,CAAC;AAEF,CAAC"}
+{"version":3,"file":"cp.js","sourceRoot":"","sources":["../../src/tool/cp.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,YAAY,EAAE,QAAQ,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AACtE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAGpD;;GAEG;AACH,EAAE,CAAC,KAAK,GAAG,uBAAuB,CAAC;AAGnC,wHAAwH;AAExH;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,MAAM,UAAU,EAAE,CAAC,MAAc,EAAE,GAAG,QAA2B;IAEhE,IAAK,CAAC,MAAM,EAAG,CAAC;QACf,MAAM,IAAI,SAAS,CAAC,wBAAwB,CAAC,CAAC;IAC/C,CAAC;IAED,IAAK,CAAC,QAAQ,CAAC,MAAM,EAAG,CAAC;QACxB,MAAM,IAAI,SAAS,CAAC,yBAAyB,CAAC,CAAC;IAChD,CAAC;IAED,QAAQ,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,OAAO,CAAC,CAAC,EAAE,MAAM,EAAE,WAAW,EAAE,EAAE,EAAE;QAC5D,SAAS,CAAC,OAAO,CAAC,WAAW,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QACrD,YAAY,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;QAClC,OAAO,CAAC,GAAG,CAAC,MAAM,MAAM,EAAE,CAAC,CAAC;IAC7B,CAAC,CAAC,CAAC;IAGH,SAAS,MAAM,CAAC,OAAe;QAE9B,MAAM,OAAO,GAAG,QAAQ,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC;QAE9E,IAAK,CAAC,OAAO,CAAC,MAAM,EAAG,CAAC;YACvB,MAAM,IAAI,KAAK,CAAC,sBAAsB,OAAO,GAAG,CAAC,CAAC;QACnD,CAAC;QAED,MAAM,QAAQ,GAAG,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QACpC,MAAM,IAAI,GAAG,QAAQ,CAAC,SAAS,CAAC,OAAO,CAAC,EAAE,CAAC,WAAW,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC;QACtE,MAAM,IAAI,GAAG,IAAI,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,GAAG,CAAC;QAEpF,OAAO,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,WAAW,EAAE,IAAI,CAAC,MAAM,EAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IAE/F,CAAC;AAEF,CAAC"}

package/dist/tool/index.core.d.ts

@@ -4,15 +4,17 @@
  * The tool receives the operands as its arguments, with `undefined` in place of a missing one, and throws a
  * `TypeError` on a command line it cannot act on, so that the error message also points to the help.
  *
- * `--help` and `-h` print the usage line to stdout and skip the tool. Errors go to stderr prefixed with the tool name;
- * usage errors, including unrecognized options, also point to `--help`. Operands starting with `-` follow `--`.
+ * `--help` and `-h` print the usage line to stdout, followed by the description if any, and skip the tool. Errors go to
+ * stderr prefixed with the command name; usage errors, including unrecognized options, also point to `--help`.
+ * Operands starting with `-` follow `--`, which ends option parsing as on any GNU command line.
  *
  * @param tool The tool to run on the operands
- * @param help The operand synopsis printed by `--help` after the tool name, such as `<target> <pattern>...`
- * @param name The tool name prefixing messages; defaults to the script name without extension, else the `tool` name
- * @param args The command line arguments after the script path; defaults to those the process was launched with
+ * @param help The operand synopsis printed by `--help` after the command name, such as `<target> <pattern>...`
+ * @param name The command prefixing messages, as in `ush cp`; defaults to the bare script name, else the `tool` name
+ * @param args The command line arguments after the command name; defaults to those the process was launched with
+ * @param description The text printed by `--help` below the usage line, such as a list of subcommands
  *
  * @returns The process exit status: `0` on success, `1` on failure
  */
-export declare function cli(tool: (...args: string[]) => void, help: string, name?: string, args?: readonly string[]): number;
+export declare function cli(tool: (...args: string[]) => void, help: string, name?: string, args?: readonly string[], description?: string): number;
 //# sourceMappingURL=index.core.d.ts.map

package/dist/tool/index.core.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.core.d.ts","sourceRoot":"","sources":["../../src/tool/index.core.ts"],"names":[],"mappings":"AAoBA;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,GAAG,CAClB,IAAI,EAAE,CAAC,GAAG,IAAI,EAAE,MAAM,EAAE,KAAK,IAAI,EACjC,IAAI,EAAE,MAAM,EACZ,IAAI,GAAE,MAAgF,EACtF,IAAI,GAAE,SAAS,MAAM,EAA0B,GAC7C,MAAM,CAoDR"}
+{"version":3,"file":"index.core.d.ts","sourceRoot":"","sources":["../../src/tool/index.core.ts"],"names":[],"mappings":"AAoBA;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,GAAG,CAClB,IAAI,EAAE,CAAC,GAAG,IAAI,EAAE,MAAM,EAAE,KAAK,IAAI,EACjC,IAAI,EAAE,MAAM,EACZ,IAAI,GAAE,MAAgF,EACtF,IAAI,GAAE,SAAS,MAAM,EAA0B,EAC/C,WAAW,CAAC,EAAE,MAAM,GAClB,MAAM,CAuDR"}

package/dist/tool/index.core.js

@@ -21,17 +21,19 @@ import { parseArgs } from "node:util";
  * The tool receives the operands as its arguments, with `undefined` in place of a missing one, and throws a
  * `TypeError` on a command line it cannot act on, so that the error message also points to the help.
  *
- * `--help` and `-h` print the usage line to stdout and skip the tool. Errors go to stderr prefixed with the tool name;
- * usage errors, including unrecognized options, also point to `--help`. Operands starting with `-` follow `--`.
+ * `--help` and `-h` print the usage line to stdout, followed by the description if any, and skip the tool. Errors go to
+ * stderr prefixed with the command name; usage errors, including unrecognized options, also point to `--help`.
+ * Operands starting with `-` follow `--`, which ends option parsing as on any GNU command line.
  *
  * @param tool The tool to run on the operands
- * @param help The operand synopsis printed by `--help` after the tool name, such as `<target> <pattern>...`
- * @param name The tool name prefixing messages; defaults to the script name without extension, else the `tool` name
- * @param args The command line arguments after the script path; defaults to those the process was launched with
+ * @param help The operand synopsis printed by `--help` after the command name, such as `<target> <pattern>...`
+ * @param name The command prefixing messages, as in `ush cp`; defaults to the bare script name, else the `tool` name
+ * @param args The command line arguments after the command name; defaults to those the process was launched with
+ * @param description The text printed by `--help` below the usage line, such as a list of subcommands
  *
  * @returns The process exit status: `0` on success, `1` on failure
  */
-export function cli(tool, help, name = process.argv[1] !== undefined ? parse(process.argv[1]).name : tool.name, args = process.argv.slice(2)) {
+export function cli(tool, help, name = process.argv[1] !== undefined ? parse(process.argv[1]).name : tool.name, args = process.argv.slice(2), description) {
     const { values, positionals, tokens } = parseArgs({
         args: [...args],
         options: { help: { type: "boolean", short: "h" } },
@@ -44,7 +46,9 @@ export function cli(tool, help, name = process.argv[1] !== undefined ? parse(pro
         return fail(`unrecognized option <${unknown.rawName}>`, true);
     }
     else if (values.help) {
-        console.log(`Usage: ${name} ${help}`);
+        console.log(description === undefined
+            ? `Usage: ${name} ${help}`
+            : `Usage: ${name} ${help}\n\n${description}`);
         return 0;
     }
     else {

package/dist/tool/index.core.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.core.js","sourceRoot":"","sources":["../../src/tool/index.core.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,KAAK,EAAE,MAAM,WAAW,CAAC;AAClC,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAGtC;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,GAAG,CAClB,IAAiC,EACjC,IAAY,EACZ,OAAe,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,EACtF,OAA0B,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC;IAG/C,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,GAAG,SAAS,CAAC;QACjD,IAAI,EAAE,CAAC,GAAG,IAAI,CAAC;QACf,OAAO,EAAE,EAAE,IAAI,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,GAAG,EAAE,EAAE;QAClD,gBAAgB,EAAE,IAAI;QACtB,MAAM,EAAE,KAAK,EAAE,+DAA+D;QAC9E,MAAM,EAAE,IAAI;KACZ,CAAC,CAAC;IAEH,MAAM,OAAO,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CACnC,KAAK,CAAC,IAAI,KAAK,QAAQ,IAAI,KAAK,CAAC,IAAI,KAAK,MAAM,CAChD,CAAC;IAEF,IAAK,OAAO,EAAE,IAAI,KAAK,QAAQ,EAAG,CAAC;QAElC,OAAO,IAAI,CAAC,wBAAwB,OAAO,CAAC,OAAO,GAAG,EAAE,IAAI,CAAC,CAAC;IAE/D,CAAC;SAAM,IAAK,MAAM,CAAC,IAAI,EAAG,CAAC;QAE1B,OAAO,CAAC,GAAG,CAAC,UAAU,IAAI,IAAI,IAAI,EAAE,CAAC,CAAC;QAEtC,OAAO,CAAC,CAAC;IAEV,CAAC;SAAM,CAAC;QAEP,IAAI,CAAC;YAEJ,IAAI,CAAC,GAAG,WAAW,CAAC,CAAC;YAErB,OAAO,CAAC,CAAC;QAEV,CAAC;QAAC,OAAQ,KAAK,EAAG,CAAC;YAElB,OAAO,IAAI,CAAC,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,KAAK,YAAY,SAAS,CAAC,CAAC;QAEjG,CAAC;IAEF,CAAC;IAGD,SAAS,IAAI,CAAC,OAAe,EAAE,KAAc;QAE5C,OAAO,CAAC,KAAK,CAAC,KAAK;YAClB,CAAC,CAAC,GAAG,IAAI,KAAK,OAAO,UAAU,IAAI,gCAAgC;YACnE,CAAC,CAAC,GAAG,IAAI,KAAK,OAAO,EAAE,CACvB,CAAC;QAEF,OAAO,CAAC,CAAC;IAEV,CAAC;AAEF,CAAC"}
+{"version":3,"file":"index.core.js","sourceRoot":"","sources":["../../src/tool/index.core.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,KAAK,EAAE,MAAM,WAAW,CAAC;AAClC,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAGtC;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,GAAG,CAClB,IAAiC,EACjC,IAAY,EACZ,OAAe,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,EACtF,OAA0B,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,EAC/C,WAAoB;IAGpB,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,GAAG,SAAS,CAAC;QACjD,IAAI,EAAE,CAAC,GAAG,IAAI,CAAC;QACf,OAAO,EAAE,EAAE,IAAI,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,GAAG,EAAE,EAAE;QAClD,gBAAgB,EAAE,IAAI;QACtB,MAAM,EAAE,KAAK,EAAE,+DAA+D;QAC9E,MAAM,EAAE,IAAI;KACZ,CAAC,CAAC;IAEH,MAAM,OAAO,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CACnC,KAAK,CAAC,IAAI,KAAK,QAAQ,IAAI,KAAK,CAAC,IAAI,KAAK,MAAM,CAChD,CAAC;IAEF,IAAK,OAAO,EAAE,IAAI,KAAK,QAAQ,EAAG,CAAC;QAElC,OAAO,IAAI,CAAC,wBAAwB,OAAO,CAAC,OAAO,GAAG,EAAE,IAAI,CAAC,CAAC;IAE/D,CAAC;SAAM,IAAK,MAAM,CAAC,IAAI,EAAG,CAAC;QAE1B,OAAO,CAAC,GAAG,CAAC,WAAW,KAAK,SAAS;YACpC,CAAC,CAAC,UAAU,IAAI,IAAI,IAAI,EAAE;YAC1B,CAAC,CAAC,UAAU,IAAI,IAAI,IAAI,OAAO,WAAW,EAAE,CAC5C,CAAC;QAEF,OAAO,CAAC,CAAC;IAEV,CAAC;SAAM,CAAC;QAEP,IAAI,CAAC;YAEJ,IAAI,CAAC,GAAG,WAAW,CAAC,CAAC;YAErB,OAAO,CAAC,CAAC;QAEV,CAAC;QAAC,OAAQ,KAAK,EAAG,CAAC;YAElB,OAAO,IAAI,CAAC,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,KAAK,YAAY,SAAS,CAAC,CAAC;QAEjG,CAAC;IAEF,CAAC;IAGD,SAAS,IAAI,CAAC,OAAe,EAAE,KAAc;QAE5C,OAAO,CAAC,KAAK,CAAC,KAAK;YAClB,CAAC,CAAC,GAAG,IAAI,KAAK,OAAO,UAAU,IAAI,gCAAgC;YACnE,CAAC,CAAC,GAAG,IAAI,KAAK,OAAO,EAAE,CACvB,CAAC;QAEF,OAAO,CAAC,CAAC;IAEV,CAAC;AAEF,CAAC"}