@crustjs/extensions 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Chenxin Yan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,13 @@
+# @crustjs/extensions
+
+Official Extensions for the Crust CLI framework
+
+## Install
+
+```sh
+bun add @crustjs/extensions
+```
+
+## Documentation
+
+Full docs: [crustjs.com/docs/modules/extensions](https://crustjs.com/docs/modules/extensions)

package/dist/index.d.ts

@@ -0,0 +1,287 @@
+import { CommandDefinition, CommandSnapshot, Extension, ExtensionContext, ExtensionFactory, ExtensionId, RootMetaKey } from "@crustjs/core";
+//#region src/completion/index.d.ts
+/** The set of shells supported by the v1 completion extension. */
+type CompletionShell = "bash" | "zsh" | "fish";
+/** Options for the completion Extension. */
+interface CompletionOptions {
+  /**
+   * Subcommand name. Override only if the default conflicts with an existing user-defined command.
+   *
+   * @default "completion"
+   */
+  command?: string;
+  /**
+   * 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.
+   *
+   * @default The root command's `meta.name`
+   */
+  binName?: string;
+  /**
+   * Free-form version string embedded in generated script headers. The
+   * walker does not parse it.
+   *
+   * @default The root command's `meta.version`
+   */
+  version?: string;
+}
+/** Render inputs shared by the pure shell renderers. */
+type CompletionRenderOptions = Pick<CompletionOptions, "binName" | "version">;
+/** Render a bash completion script from a prepared root Command Snapshot. */
+export declare function renderBashCompletion(root: CommandSnapshot, options?: CompletionRenderOptions): string;
+/** Render a zsh completion script from a prepared root Command Snapshot. */
+export declare function renderZshCompletion(root: CommandSnapshot, options?: CompletionRenderOptions): string;
+/** Render a fish completion script from a prepared root Command Snapshot. */
+export declare function renderFishCompletion(root: CommandSnapshot, options?: CompletionRenderOptions): string;
+/**
+ * Build an Extension that contributes a `completion <shell>` command
+ * which emits a tab-completion script for bash, zsh, or fish.
+ *
+ * **Strategy: pure-static.** The action walks the final root snapshot, so
+ * registration order is irrelevant — any commands or recursive flags added
+ * by other Extensions are visible by the time we generate the script. The
+ * walker projects Core's documentation model to a small completion model; per-shell
+ * renderers turn that into a self-contained shell script with no runtime
+ * callbacks.
+ *
+ * **Print vs `--output-dir`.**
+ * - With no `--output-dir`: print the script for the requested `<shell>`
+ *   to stdout (the install pattern is
+ *   `mycli completion bash > ~/.local/share/...`).
+ * - With `--output-dir <path>`: write **all** supported shells' files
+ *   into the directory using the canonical per-shell filename
+ *   (`<bin>` for bash, `_<bin>` for zsh, `<bin>.fish` for fish). This
+ *   is the artifact-generation path used by Homebrew, Nix, and similar
+ *   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.
+ */
+export declare const completion: ExtensionFactory<[options?: CompletionOptions], {}, [], [], readonly CommandDefinition<any, any, any, any>[]>;
+//#endregion
+//#region src/did-you-mean.d.ts
+interface DidYouMeanOptions {
+  /**
+   * Presentation mode for command-not-found errors.
+   *
+   * `"error"` writes the message and visible commands to stderr. `"help"`
+   * writes the message and parent command help to stdout.
+   *
+   * @default "error"
+   */
+  mode?: "error" | "help";
+}
+export declare const didYouMean: ExtensionFactory<[options?: DidYouMeanOptions]>;
+//#endregion
+//#region src/help.d.ts
+export declare function renderHelp(command: CommandSnapshot, path?: readonly string[]): string;
+declare const helpFlags: readonly [{
+  readonly name: "help";
+  readonly type: "boolean";
+  readonly short: "h";
+  readonly noNegate: true;
+  readonly description: "Show help";
+}];
+export declare const help: ExtensionFactory<[], {}, [], typeof helpFlags>;
+//#endregion
+//#region src/no-color.d.ts
+declare const colorFlags: readonly [{
+  readonly name: "color";
+  readonly type: "boolean";
+  readonly description: "Enable colored output";
+}];
+/**
+ * Adds a recursive `--color` / `--no-color` flag pair that scopes the
+ * standard color environment variables around command execution:
+ *
+ * - `--color` sets `FORCE_COLOR=3` (and clears `NO_COLOR`, so strict
+ *   no-color.org-only child processes also comply) — forces all ANSI on
+ *   (truecolor), overriding non-TTY detection. Any color library that
+ *   honors `FORCE_COLOR` (including `@crustjs/style` and chalk) obeys it,
+ *   and child processes inherit it.
+ * - `--no-color` sets `NO_COLOR=1` (and clears `FORCE_COLOR` so the flag
+ *   wins over ambient env) — suppresses colors while non-color modifiers
+ *   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.
+ */
+export declare const noColor: ExtensionFactory<[], {}, [], typeof colorFlags>;
+//#endregion
+//#region src/update-notifier.d.ts
+type UpdateNotifierPackageManager = "npm" | "pnpm" | "yarn" | "bun";
+type UpdateCommandResolver = (info: {
+  packageName: string;
+  packageManager: UpdateNotifierPackageManager;
+}) => string;
+interface UpdateNotifierState {
+  lastCheckedAt: number;
+  latestVersion?: string;
+  lastNotifiedVersion?: string;
+}
+interface UpdateNotifierCacheAdapter {
+  read(): Promise<UpdateNotifierState | null | undefined>;
+  write(state: UpdateNotifierState): Promise<void>;
+}
+/**
+ * Cache configuration for the update notifier extension.
+ *
+ * Wraps a {@link UpdateNotifierCacheAdapter} with cache-specific settings.
+ */
+interface UpdateNotifierCacheConfig {
+  /**
+   * Persistence adapter for reading and writing notifier state.
+   *
+   * When omitted, the built-in `@crustjs/store` persistence is used, so
+   * `intervalMs` can be tuned without reimplementing storage.
+   */
+  adapter?: UpdateNotifierCacheAdapter;
+  /**
+   * Minimum interval in milliseconds between network update checks.
+   *
+   * Cached results are reused until this interval elapses.
+   *
+   * @default 86_400_000 (24 hours)
+   */
+  intervalMs?: number;
+}
+/**
+ * Configuration options for the update notifier extension.
+ *
+ * @example
+ * ```ts
+ * import { updateNotifier } from "@crustjs/extensions";
+ *
+ * updateNotifier({ packageName: "my-cli" });
+ * ```
+ */
+interface UpdateNotifierOptions {
+  /**
+   * Override the current version of the CLI package.
+   *
+   * @default The root command's `meta.version`
+   */
+  currentVersion?: string;
+  /**
+   * The npm package name to check for updates.
+   */
+  packageName: string;
+  /**
+   * Network request timeout in milliseconds for the registry check.
+   *
+   * If the check does not complete within this duration, it is silently
+   * aborted and treated as a soft failure. This timeout does not bound cache
+   * operations or the entire postRun hook.
+   *
+   * @default 5_000 (5 seconds)
+   */
+  timeoutMs?: number;
+  /**
+   * Custom npm registry URL to query for the latest version.
+   *
+   * @default "https://registry.npmjs.org"
+   */
+  registryUrl?: string;
+  /**
+   * Upgrade command shown in the notice.
+   *
+   * Pass a string for a fixed command, a callback to build one from the
+   * package name and detected package manager, or a scope to generate the
+   * package manager's standard local/global command. When omitted, the notice
+   * does not suggest a command.
+   */
+  updateCommand?: string | UpdateCommandResolver | {
+    scope: "global" | "local";
+  };
+  /**
+   * Documentation URL shown after the update notice.
+   */
+  updateDocsUrl?: string;
+  /**
+   * Cache configuration for cross-run persistence.
+   *
+   * By default, notifier state is persisted in the platform-standard state
+   * directory for {@link packageName}. Set to `false` to disable persistence,
+   * provide `intervalMs` alone to tune the built-in cache interval, or
+   * provide a custom adapter to control storage.
+   *
+   * @example
+   * ```ts
+   * cache: false
+   * ```
+   */
+  cache?: false | UpdateNotifierCacheConfig;
+}
+/**
+ * Creates an update notifier extension that checks the npm registry after a
+ * successful command action and displays a notice when a newer version is available.
+ *
+ * **Behavior:**
+ * - By default, checks are cached for 24 hours in the package's state directory.
+ * - `cache: false` disables cross-run persistence.
+ * - A custom cache adapter can override the built-in persistence.
+ * - The notice is command-less unless `updateCommand` is configured.
+ * - The postRun hook awaits the network check and cache reads and writes,
+ *   delaying invocation completion after the action.
+ * - `timeoutMs` bounds only the network request, defaulting to 5 seconds.
+ * - Network, cache, and parsing errors are silently swallowed. A missing
+ *   current version throws a DEFINITION error before that recovery block.
+ * - Update notices are intentionally written to the invocation's stderr callback.
+ * - Duplicate notifications for the same version are suppressed.
+ *
+ * @param options - Extension configuration. `packageName` is required.
+ * @returns An Extension registered with `.extend()`.
+ *
+ * @example
+ * ```ts
+ * import { Crust } from "@crustjs/core";
+ * import { updateNotifier } from "@crustjs/extensions";
+ *
+ * const app = new Crust("my-cli", { description: "My awesome CLI", version: "1.2.3" })
+ *   .extend(updateNotifier({ packageName: "my-cli" }))
+ *   .action(() => {
+ *     console.log("Hello!");
+ *   });
+ *
+ * await app.execute();
+ * ```
+ */
+export declare const updateNotifier: ExtensionFactory<[options: UpdateNotifierOptions]>;
+//#endregion
+//#region src/version.d.ts
+type VersionValue = string | (() => string);
+interface VersionOptions {
+  /**
+   * Output format. `"plain"` prints the bare version (script-friendly:
+   * `$(cli --version)`); a function receives the resolved version and the
+   * extension context and returns the line to print.
+   *
+   * @default `${rootName} v${version}`
+   */
+  readonly format?: "plain" | ((version: string, context: ExtensionContext) => string);
+}
+declare const versionFlags: readonly [{
+  readonly name: "version";
+  readonly type: "boolean";
+  readonly short: "v";
+  readonly noNegate: true;
+  readonly description: "Show version number";
+  readonly recursive: false;
+}];
+type VersionRegistration<K extends RootMetaKey> = Extension<{}, [], typeof versionFlags, [], K>;
+/** Explicit values supply their own version; omitted values require root metadata. */
+interface VersionExtension {
+  (value: VersionValue, options?: VersionOptions): VersionRegistration<never>;
+  (value?: VersionValue, options?: VersionOptions): VersionRegistration<"version">;
+  readonly id: ExtensionId;
+}
+export declare const version: VersionExtension;
+//#endregion
+export type { CompletionOptions, CompletionRenderOptions, CompletionShell, DidYouMeanOptions, UpdateCommandResolver, UpdateNotifierCacheAdapter, UpdateNotifierCacheConfig, UpdateNotifierOptions, UpdateNotifierPackageManager, UpdateNotifierState, VersionExtension, VersionOptions, VersionValue };