@crustjs/extensions 0.2.1 → 0.3.1

package/README.md

@@ -5,7 +5,7 @@ Official Extensions for the Crust CLI framework
 ## Install
 
 ```sh
-bun add @crustjs/extensions
+npm install @crustjs/extensions
 ```
 
 ## Documentation

package/dist/index.d.ts

@@ -13,8 +13,8 @@ interface CompletionOptions {
   /**
    * Binary name embedded in generated scripts (the `complete -F` target,
    * the `#compdef` line, the `complete -c <bin>` rules).
-   * Applies to the runtime command and build hook; set it when `crust build --name`
-   * or the npm bin key installs the CLI under a different name.
+   * Applies to the runtime command and build hook; set it when the npm bin key
+   * installs the CLI under a different name.
    *
    * @default The root command's `meta.name`
    */
@@ -57,9 +57,10 @@ export declare function renderFishCompletion(root: CommandSnapshot, options?: Co
  *   distribution channels — distributors run it once at packaging time
  *   and the resulting files become drop-ins.
  *
- * **Build hook.** `crust build` writes the same three files under
- * `<outDir>/completions/`; `--package` stages that directory. The binary name
- * defaults to the snapshot's `meta.name`, unless `options.binName` is set.
+ * **Build hook.** Returns the same three files under `completions/`; `crust build`
+ * writes them to `.crust/artifacts/completions/` and copies that directory into
+ * the root package and each platform package's `bin/`. The binary name defaults
+ * to the snapshot's `meta.name`, unless `options.binName` is set.
  */
 export declare const completion: ExtensionFactory<[options?: CompletionOptions], {}, [], [], readonly CommandDefinition<any, any, any, any>[]>;
 //#endregion
@@ -108,10 +109,11 @@ declare const colorFlags: readonly [{
  *   and hyperlinks keep following TTY detection, per
  *   [no-color.org](https://no-color.org/).
  *
- * Previous values are restored after the command finishes. When overlapping
- * programmatic runs in one process use opposite flags, the later run wins
- * mid-flight (the env is process-global); the ambient values are restored
- * once all runs finish.
+ * Previous values are restored after the command finishes. Overlapping
+ * programmatic runs in one process may share a direction (both `--color` or
+ * both `--no-color`); the ambient values are restored once all runs finish.
+ * An overlapping run with the opposing flag throws a `CrustError` in
+ * `preRun`, because the env is process-global and cannot hold both values.
  */
 export declare const noColor: ExtensionFactory<[], {}, [], typeof colorFlags>;
 //#endregion

package/dist/index.js

@@ -1,4 +1,4 @@
-import { mkdir, mkdtemp, rename, rm, writeFile } from "node:fs/promises";
+import { mkdir, writeFile } from "node:fs/promises";
 import { basename, join, resolve } from "node:path";
 import { CrustError, defineCommand, defineExtension, defineExtensionId } from "@crustjs/core";
 import { buildCommandDocumentation, formatDescription, isListed, sectionsFor } from "@crustjs/core/tooling";
@@ -410,6 +410,16 @@ function renderBash(spec, binName, version) {
 	lines.push("	return 1");
 	lines.push("}");
 	lines.push("");
+	if (valueTypeCases.some((c) => c.kind === "path")) {
+		lines.push(`__${ident}_file_candidates() {`);
+		lines.push("	local f");
+		lines.push("	compopt -o filenames 2>/dev/null || :");
+		lines.push("	while IFS= read -r f; do");
+		lines.push("		if [[ -n \"$f\" ]]; then COMPREPLY[${#COMPREPLY[@]}]=\"$1$f\"; fi");
+		lines.push("	done <<< \"$(compgen -f -- \"$2\")\"");
+		lines.push("}");
+		lines.push("");
+	}
 	lines.push(`${fnName}() {`);
 	lines.push("	local cur prev words cword");
 	lines.push("	if declare -F _init_completion >/dev/null 2>&1; then");
@@ -478,7 +488,7 @@ function renderBash(spec, binName, version) {
 		lines.push("		case \"$cmd_path|$_flag\" in");
 		for (const c of valueTypeCases) {
 			lines.push(`\t\t\t"${bashDoubleQuoteInner(c.key)}")`);
-			if (c.kind === "path") lines.push("				COMPREPLY=( $(compgen -P \"${_flag}=\" -f -- \"$_value\") )");
+			if (c.kind === "path") lines.push(`\t\t\t\t__${ident}_file_candidates "\${_flag}=" "$_value"`);
 			else lines.push("				compopt +o default 2>/dev/null");
 			lines.push("				return");
 			lines.push("				;;");
@@ -503,7 +513,7 @@ function renderBash(spec, binName, version) {
 		lines.push("	case \"$cmd_path|$prev\" in");
 		for (const c of valueTypeCases) {
 			lines.push(`\t\t"${bashDoubleQuoteInner(c.key)}")`);
-			if (c.kind === "path") lines.push("			COMPREPLY=( $(compgen -f -- \"$cur\") )");
+			if (c.kind === "path") lines.push(`\t\t\t__${ident}_file_candidates "" "$cur"`);
 			else lines.push("			compopt +o default 2>/dev/null");
 			lines.push("			return");
 			lines.push("			;;");
@@ -699,12 +709,7 @@ function emitRules(binName, ident, path, current, out) {
 	};
 	for (const flag of current.flags) {
 		const desc = flag.description ?? "";
-		const baseRule = {
-			condition,
-			long: flag.name,
-			description: desc
-		};
-		if (flag.short !== void 0) baseRule.short = flag.short;
+		const spellings = [flag.name, ...flag.aliases ?? []];
 		const emitValueRule = (rule) => {
 			if (flag.choices !== void 0 && flag.choices.length > 0) {
 				emitChoiceFlag(rule, flag.choices);
@@ -723,27 +728,21 @@ function emitRules(binName, ident, path, current, out) {
 				requireParameter: true
 			}));
 		};
-		if (flag.takesValue) emitValueRule(baseRule);
-		else out.push(renderRule(binName, baseRule));
-		if (flag.aliases !== void 0) for (const alias of flag.aliases) {
-			const aliasRule = {
+		for (const [index, spelling] of spellings.entries()) {
+			const rule = {
 				condition,
-				long: alias,
+				long: spelling,
 				description: desc
 			};
-			if (flag.takesValue) emitValueRule(aliasRule);
-			else out.push(renderRule(binName, aliasRule));
+			if (index === 0 && flag.short !== void 0) rule.short = flag.short;
+			if (flag.takesValue) emitValueRule(rule);
+			else out.push(renderRule(binName, rule));
 		}
 		if (flag.negatable) {
 			const negDesc = `disable: ${desc}`.trim();
-			out.push(renderRule(binName, {
+			for (const spelling of spellings) out.push(renderRule(binName, {
 				condition,
-				long: `no-${flag.name}`,
-				description: negDesc
-			}));
-			if (flag.aliases !== void 0) for (const alias of flag.aliases) out.push(renderRule(binName, {
-				condition,
-				long: `no-${alias}`,
+				long: `no-${spelling}`,
 				description: negDesc
 			}));
 		}
@@ -863,7 +862,8 @@ function renderFish(spec, binName, version) {
 /**
 * Pure-static zsh completion script renderer.
 *
-* Strategy: emit one `_<bin>_<path>` helper per command in the tree.
+* Strategy: emit one `_<bin>__<path>` helper per command in the tree
+* (path segments joined by `__`, see {@link helperName}).
 * Helpers for non-leaf commands declare an `_arguments -C` spec with
 * `1: :->cmds` and `*::arg:->args`, then dispatch via `case "$line[1]"`
 * into the child helper — the canonical `->state` routing pattern from
@@ -958,13 +958,26 @@ function renderArgSpecs(node) {
 	return specs;
 }
 /**
+* Encode one validated command name (`[A-Za-z0-9][A-Za-z0-9._-]*`) as a
+* helper-name segment. Alphanumerics pass through; `.`, `-` and `_`
+* become `_<hex>` (`_2e`, `_2d`, `_5f`). The result never contains `__`
+* and never ends in `_`, so `__` is unambiguous as the path separator in
+* {@link helperName}: `foo-bar`, `foo_bar` and nested `foo bar` map to
+* `foo_2dbar`, `foo_5fbar` and `foo__bar`. Mapping every non-alphanumeric
+* to `_` (as {@link toShellIdent} does) let distinct commands overwrite
+* one another's helper.
+*/
+function encodeHelperSegment(name) {
+	return name.replace(/[^A-Za-z0-9]/g, (ch) => `_${ch.charCodeAt(0).toString(16)}`);
+}
+/**
 * Build the function name for the helper that handles a given command
-* path. The root is `_<ident>`; nested children append `_<segment>` for
-* each step.
+* path. The root is `_<ident>`; nested children append `__<segment>` for
+* each step, with segments encoded by {@link encodeHelperSegment}.
 */
 function helperName(rootIdent, path) {
 	if (path.length === 0) return `_${rootIdent}`;
-	return `_${rootIdent}_${path.map(toShellIdent).join("_")}`;
+	return `_${rootIdent}__${path.map(encodeHelperSegment).join("__")}`;
 }
 /**
 * Render a single command's helper function.
@@ -1213,17 +1226,13 @@ function prepareRender(root, options) {
 		version: sanitizeFreeText(version)
 	};
 }
-async function writeCompletionFiles(dir, root, options) {
+/** Every supported shell's drop-in file, named by its autoload convention. */
+function renderCompletionFiles(root, options) {
 	const { spec, binName, version } = prepareRender(root, options);
-	await mkdir(dir, { recursive: true });
-	const filenames = [];
-	for (const shell of SUPPORTED_SHELLS) {
-		const filename = filenameForShell(shell, binName);
-		const script = SHELL_RENDERERS[shell](spec, binName, version);
-		await writeFile(join(dir, filename), script, "utf8");
-		filenames.push(filename);
-	}
-	return filenames;
+	return SUPPORTED_SHELLS.map((shell) => ({
+		path: filenameForShell(shell, binName),
+		content: SHELL_RENDERERS[shell](spec, binName, version)
+	}));
 }
 function renderCompletionScript(shell, root, options = {}) {
 	const { spec, binName, version } = prepareRender(root, options);
@@ -1263,9 +1272,10 @@ function renderFishCompletion(root, options) {
 *   distribution channels — distributors run it once at packaging time
 *   and the resulting files become drop-ins.
 *
-* **Build hook.** `crust build` writes the same three files under
-* `<outDir>/completions/`; `--package` stages that directory. The binary name
-* defaults to the snapshot's `meta.name`, unless `options.binName` is set.
+* **Build hook.** Returns the same three files under `completions/`; `crust build`
+* writes them to `.crust/artifacts/completions/` and copies that directory into
+* the root package and each platform package's `bin/`. The binary name defaults
+* to the snapshot's `meta.name`, unless `options.binName` is set.
 */
 const completion = defineExtension(COMPLETION, (options = {}) => {
 	const subcommandName = options.command ?? "completion";
@@ -1286,27 +1296,15 @@ const completion = defineExtension(COMPLETION, (options = {}) => {
 				context.stdout(renderCompletionScript(context.args.shell, context.rootCommand, options));
 				return;
 			}
-			await writeCompletionFiles(resolve(outputDir), context.rootCommand, options);
+			const dir = resolve(outputDir);
+			const files = renderCompletionFiles(context.rootCommand, options);
+			await mkdir(dir, { recursive: true });
+			for (const file of files) await writeFile(join(dir, file.path), file.content);
 		}))],
-		build: async ({ snapshot, outDir }) => {
-			const dir = join(outDir, "completions");
-			await mkdir(outDir, { recursive: true });
-			const stagedDir = await mkdtemp(join(outDir, ".completions-"));
-			try {
-				const filenames = await writeCompletionFiles(stagedDir, snapshot, options);
-				await rm(dir, {
-					recursive: true,
-					force: true
-				});
-				await rename(stagedDir, dir);
-				return filenames.map((filename) => join("completions", filename));
-			} finally {
-				await rm(stagedDir, {
-					recursive: true,
-					force: true
-				});
-			}
-		}
+		build: ({ snapshot }) => renderCompletionFiles(snapshot, options).map((file) => ({
+			...file,
+			path: `completions/${file.path}`
+		}))
 	};
 });
 //#endregion
@@ -1412,7 +1410,7 @@ function levenshtein(a, b) {
 	return row[bLen];
 }
 /**
-* Find canonical-name suggestions for `input` by matching against every
+* Find the best canonical-name suggestion for `input` by matching against every
 * sibling's canonical name **and** any aliases declared on each sibling.
 *
 * Matched aliases are mapped back to their canonical, so suggestions only
@@ -1432,36 +1430,28 @@ function levenshtein(a, b) {
 * shortcut is intentionally omitted: with aliases in the candidate set,
 * any 1–2 char alias would falsely match every typo as distance 0.
 */
-function findSuggestions(input, subCommands) {
-	const best = /* @__PURE__ */ new Map();
-	const score = (text) => {
-		if (text.startsWith(input)) return 0;
-		const d = levenshtein(input, text);
-		return d <= 3 ? d : null;
-	};
-	const record = (canonical, distance) => {
-		const prev = best.get(canonical);
-		if (prev === void 0 || distance < prev) best.set(canonical, distance);
-	};
+function findSuggestion(input, subCommands) {
+	let bestName;
+	let bestDistance = Infinity;
 	for (const [name, node] of Object.entries(subCommands)) {
 		if (!isListed(node)) continue;
-		const d = score(name);
-		if (d !== null) record(name, d);
-		for (const alias of node.meta.aliases ?? []) {
-			const da = score(alias);
-			if (da !== null) record(name, da);
+		let distance = Infinity;
+		for (const spelling of [name, ...node.meta.aliases ?? []]) distance = Math.min(distance, spelling.startsWith(input) ? 0 : levenshtein(input, spelling));
+		if (distance <= 3 && (bestName === void 0 || distance < bestDistance || distance === bestDistance && name.localeCompare(bestName) < 0)) {
+			bestName = name;
+			bestDistance = distance;
 		}
 	}
-	return [...best.entries()].sort(([aName, aDist], [bName, bDist]) => aDist !== bDist ? aDist - bDist : aName.localeCompare(bName)).map(([name]) => name);
+	return bestName;
 }
 const didYouMean = defineExtension(DID_YOU_MEAN, (options = {}) => {
 	const mode = options.mode ?? "error";
 	return { hooks: { onError(error, context) {
 		if (!(error instanceof CrustError) || !error.is("COMMAND_NOT_FOUND")) return;
 		const details = error.details;
-		const suggestions = findSuggestions(details.input, details.parentCommand.subCommands);
+		const suggestion = findSuggestion(details.input, details.parentCommand.subCommands);
 		let message = `Unknown command "${details.input}".`;
-		if (suggestions.length > 0) message += ` Did you mean "${suggestions[0]}"?`;
+		if (suggestion !== void 0) message += ` Did you mean "${suggestion}"?`;
 		if (mode === "help") {
 			context.stdout(message);
 			context.stdout("");
@@ -1477,6 +1467,7 @@ const didYouMean = defineExtension(DID_YOU_MEAN, (options = {}) => {
 //#region src/no-color.ts
 const NO_COLOR = defineExtensionId("crust:no-color");
 let activeRuns = 0;
+let activeFlag;
 let baseForceColor;
 let baseNoColor;
 const colorRuns = /* @__PURE__ */ new WeakSet();
@@ -1499,10 +1490,11 @@ const colorFlags = [{
 *   and hyperlinks keep following TTY detection, per
 *   [no-color.org](https://no-color.org/).
 *
-* Previous values are restored after the command finishes. When overlapping
-* programmatic runs in one process use opposite flags, the later run wins
-* mid-flight (the env is process-global); the ambient values are restored
-* once all runs finish.
+* Previous values are restored after the command finishes. Overlapping
+* programmatic runs in one process may share a direction (both `--color` or
+* both `--no-color`); the ambient values are restored once all runs finish.
+* An overlapping run with the opposing flag throws a `CrustError` in
+* `preRun`, because the env is process-global and cannot hold both values.
 */
 const noColor = defineExtension(NO_COLOR, () => ({
 	flags: colorFlags,
@@ -1510,6 +1502,12 @@ const noColor = defineExtension(NO_COLOR, () => ({
 		preRun(context) {
 			const flagValue = context.flags.color;
 			if (flagValue !== true && flagValue !== false) return;
+			if (activeRuns > 0 && activeFlag !== flagValue) throw new CrustError("DEFINITION", "noColor: cannot start a --color run while a --no-color run is in flight (or vice versa); opposing overlapping runs share process.env", {
+				subject: "extension",
+				name: NO_COLOR,
+				reason: "opposing-overlap"
+			});
+			activeFlag = flagValue;
 			if (activeRuns === 0) {
 				baseForceColor = process.env.FORCE_COLOR;
 				baseNoColor = process.env.NO_COLOR;
@@ -1529,6 +1527,7 @@ const noColor = defineExtension(NO_COLOR, () => ({
 			colorRuns.delete(context);
 			activeRuns--;
 			if (activeRuns === 0) {
+				activeFlag = void 0;
 				if (baseForceColor === void 0) delete process.env.FORCE_COLOR;
 				else process.env.FORCE_COLOR = baseForceColor;
 				if (baseNoColor === void 0) delete process.env.NO_COLOR;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@crustjs/extensions",
-	"version": "0.2.1",
+	"version": "0.3.1",
 	"description": "Official Extensions for the Crust CLI framework",
 	"type": "module",
 	"sideEffects": false,
@@ -46,17 +46,17 @@
 		"postpack": "rm -f LICENSE"
 	},
 	"dependencies": {
-		"@crustjs/store": "^0.3.1",
-		"@crustjs/style": "^0.3.1"
+		"@crustjs/store": "^0.4.0",
+		"@crustjs/style": "^0.3.3"
 	},
 	"devDependencies": {
 		"@crustjs/config": "0.0.0",
-		"@crustjs/core": "0.2.1",
+		"@crustjs/core": "0.3.1",
 		"@crustjs/utils": "0.0.0",
 		"tsdown": "^0.23.0"
 	},
 	"peerDependencies": {
-		"@crustjs/core": "^0.2.1",
+		"@crustjs/core": "^0.3.1",
 		"typescript": "^7.0.0"
 	},
 	"peerDependenciesMeta": {