codebase-snapshot 0.0.0-stage → 4.5.0

package/dist/cli.d.cts

@@ -0,0 +1,124 @@
+import { O as OutputFormat, D as DiscoveryMode } from './types-Ca4PmkiQ.cjs';
+
+type Command = "generate" | "validate" | "report" | "init" | "setup" | "explain" | "diff" | "describe" | "skill";
+/** A user-input problem: printed without a stack trace, exits 2. */
+declare class UsageError extends Error {
+}
+interface ParsedInvocation {
+    command: Command;
+    /** Positional arguments that follow the command name. */
+    args: string[];
+    format: OutputFormat;
+    dryRun: boolean;
+    watch: boolean;
+    /** Ignore any config file and run on the built-in defaults. */
+    noConfig: boolean;
+    preset?: string;
+    /** The size exactly as typed, so the generated config can keep `120k`. */
+    maxPartBytesRaw?: string;
+    include?: string;
+    exclude?: string;
+    yes: boolean;
+    force: boolean;
+    /** `setup` only: skip the dependency install. */
+    noInstall: boolean;
+    /** `skill` only: write the skill into the repository instead of printing it. */
+    install: boolean;
+    /** `skill` only: which location(s) to write. */
+    target?: string;
+    cwd: string;
+    outDir?: string;
+    includeMonolith?: boolean;
+    includeSensitiveFiles?: boolean;
+    maxPartBytes?: number;
+    largeFileBytes?: number;
+    maxMonolithBytes?: number | null;
+    skipArtifacts?: string[];
+    /** How candidates are discovered; `auto` when unset. */
+    discovery?: DiscoveryMode;
+}
+declare function parsePositiveInteger(raw: string | undefined, optionName: string, minimum: number): number | undefined;
+/**
+ * Parses a byte-budget option, accepting human-readable units (`120k`, `1.5mb`)
+ * as well as raw byte counts.
+ */
+declare function parseByteOption(raw: string | undefined, optionName: string, minimum: number): number | undefined;
+/**
+ * Parses argv.
+ *
+ * Uses `node:util.parseArgs` in strict mode, so `--option=value` works, unknown
+ * flags are rejected instead of silently ignored, and a typo can no longer fall
+ * through to the writable `generate` command.
+ */
+declare function parseCliArgs(argv: string[]): ParsedInvocation;
+/**
+ * The environment a nested package-manager run gets: the caller's, minus npm's own config.
+ *
+ * Running `setup` through `npx`/`npm exec` puts the parent npm's resolved config into
+ * `npm_config_*` variables, and a child that inherits them is not the `npm install` a user would
+ * type — with an npm that supports an `allowScripts` switch, the child aborted with
+ * `EALLOWSCRIPTS: --allow-scripts is not allowed in project-scoped installs`. Stripping them makes
+ * the child read the project's own `.npmrc` and flags, which is the whole point of using the
+ * project's package manager.
+ */
+declare function cleanInstallEnv(env?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
+/** Runs the CLI and returns the process exit code. */
+declare function main(argv?: string[]): Promise<number>;
+/** Coalesce bursts of filesystem events into one run. */
+declare const WATCH_DEBOUNCE_MS = 250;
+/**
+ * Unattributed watcher events (no filename) are ignored this long after a run.
+ * Named source events are never ignored: that is how an edit in the quiet
+ * window or during a run reaches the loop.
+ */
+declare const WATCH_SETTLE_MS = 1500;
+interface WatchState {
+    running: boolean;
+    pending: boolean;
+    settleUntil: number;
+}
+interface WatchPaths {
+    cwd: string;
+    outDir: string;
+    tmpDir: string;
+}
+interface WatchEvent {
+    /** Absolute path, or null when `fs.watch` did not attribute the event. */
+    path: string | null;
+    /** `performance.now()` at delivery. */
+    now: number;
+}
+type WatchAction = "ignore" | "pending" | "schedule";
+interface WatchDecision {
+    state: WatchState;
+    action: WatchAction;
+}
+declare function initialWatchState(): WatchState;
+declare function beginWatchRun(state: WatchState): WatchState;
+/**
+ * Finish one run. `schedule` is true when a source event arrived while the run
+ * was in flight, so exactly one follow-up run is owed.
+ */
+declare function finishWatchRun(state: WatchState, now: number): {
+    state: WatchState;
+    schedule: boolean;
+};
+/**
+ * True only for the resolved output/staging paths and their contents.
+ *
+ * This deliberately does not match a directory just because its basename is
+ * `docs`: a source directory `src/docs` is not the output directory `docs`.
+ */
+declare function isGeneratedWatchPath(candidate: string, paths: WatchPaths): boolean;
+/**
+ * Decide what one watcher event means.
+ *
+ * - generated paths are always ignored;
+ * - a named source event is `pending` during a run and `schedule` otherwise,
+ *   including inside the settle window (an edit is never swallowed);
+ * - an unattributed event is ignored during a run and for the settle window,
+ *   because Windows does not always name the path our own writes produced.
+ */
+declare function decideWatchEvent(state: WatchState, event: WatchEvent, paths: WatchPaths): WatchDecision;
+
+export { UsageError, WATCH_DEBOUNCE_MS, WATCH_SETTLE_MS, type WatchAction, type WatchDecision, type WatchEvent, type WatchPaths, type WatchState, beginWatchRun, cleanInstallEnv, decideWatchEvent, finishWatchRun, initialWatchState, isGeneratedWatchPath, main, parseByteOption, parseCliArgs, parsePositiveInteger };

package/dist/cli.d.ts

@@ -0,0 +1,124 @@
+import { O as OutputFormat, D as DiscoveryMode } from './types-Ca4PmkiQ.js';
+
+type Command = "generate" | "validate" | "report" | "init" | "setup" | "explain" | "diff" | "describe" | "skill";
+/** A user-input problem: printed without a stack trace, exits 2. */
+declare class UsageError extends Error {
+}
+interface ParsedInvocation {
+    command: Command;
+    /** Positional arguments that follow the command name. */
+    args: string[];
+    format: OutputFormat;
+    dryRun: boolean;
+    watch: boolean;
+    /** Ignore any config file and run on the built-in defaults. */
+    noConfig: boolean;
+    preset?: string;
+    /** The size exactly as typed, so the generated config can keep `120k`. */
+    maxPartBytesRaw?: string;
+    include?: string;
+    exclude?: string;
+    yes: boolean;
+    force: boolean;
+    /** `setup` only: skip the dependency install. */
+    noInstall: boolean;
+    /** `skill` only: write the skill into the repository instead of printing it. */
+    install: boolean;
+    /** `skill` only: which location(s) to write. */
+    target?: string;
+    cwd: string;
+    outDir?: string;
+    includeMonolith?: boolean;
+    includeSensitiveFiles?: boolean;
+    maxPartBytes?: number;
+    largeFileBytes?: number;
+    maxMonolithBytes?: number | null;
+    skipArtifacts?: string[];
+    /** How candidates are discovered; `auto` when unset. */
+    discovery?: DiscoveryMode;
+}
+declare function parsePositiveInteger(raw: string | undefined, optionName: string, minimum: number): number | undefined;
+/**
+ * Parses a byte-budget option, accepting human-readable units (`120k`, `1.5mb`)
+ * as well as raw byte counts.
+ */
+declare function parseByteOption(raw: string | undefined, optionName: string, minimum: number): number | undefined;
+/**
+ * Parses argv.
+ *
+ * Uses `node:util.parseArgs` in strict mode, so `--option=value` works, unknown
+ * flags are rejected instead of silently ignored, and a typo can no longer fall
+ * through to the writable `generate` command.
+ */
+declare function parseCliArgs(argv: string[]): ParsedInvocation;
+/**
+ * The environment a nested package-manager run gets: the caller's, minus npm's own config.
+ *
+ * Running `setup` through `npx`/`npm exec` puts the parent npm's resolved config into
+ * `npm_config_*` variables, and a child that inherits them is not the `npm install` a user would
+ * type — with an npm that supports an `allowScripts` switch, the child aborted with
+ * `EALLOWSCRIPTS: --allow-scripts is not allowed in project-scoped installs`. Stripping them makes
+ * the child read the project's own `.npmrc` and flags, which is the whole point of using the
+ * project's package manager.
+ */
+declare function cleanInstallEnv(env?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
+/** Runs the CLI and returns the process exit code. */
+declare function main(argv?: string[]): Promise<number>;
+/** Coalesce bursts of filesystem events into one run. */
+declare const WATCH_DEBOUNCE_MS = 250;
+/**
+ * Unattributed watcher events (no filename) are ignored this long after a run.
+ * Named source events are never ignored: that is how an edit in the quiet
+ * window or during a run reaches the loop.
+ */
+declare const WATCH_SETTLE_MS = 1500;
+interface WatchState {
+    running: boolean;
+    pending: boolean;
+    settleUntil: number;
+}
+interface WatchPaths {
+    cwd: string;
+    outDir: string;
+    tmpDir: string;
+}
+interface WatchEvent {
+    /** Absolute path, or null when `fs.watch` did not attribute the event. */
+    path: string | null;
+    /** `performance.now()` at delivery. */
+    now: number;
+}
+type WatchAction = "ignore" | "pending" | "schedule";
+interface WatchDecision {
+    state: WatchState;
+    action: WatchAction;
+}
+declare function initialWatchState(): WatchState;
+declare function beginWatchRun(state: WatchState): WatchState;
+/**
+ * Finish one run. `schedule` is true when a source event arrived while the run
+ * was in flight, so exactly one follow-up run is owed.
+ */
+declare function finishWatchRun(state: WatchState, now: number): {
+    state: WatchState;
+    schedule: boolean;
+};
+/**
+ * True only for the resolved output/staging paths and their contents.
+ *
+ * This deliberately does not match a directory just because its basename is
+ * `docs`: a source directory `src/docs` is not the output directory `docs`.
+ */
+declare function isGeneratedWatchPath(candidate: string, paths: WatchPaths): boolean;
+/**
+ * Decide what one watcher event means.
+ *
+ * - generated paths are always ignored;
+ * - a named source event is `pending` during a run and `schedule` otherwise,
+ *   including inside the settle window (an edit is never swallowed);
+ * - an unattributed event is ignored during a run and for the settle window,
+ *   because Windows does not always name the path our own writes produced.
+ */
+declare function decideWatchEvent(state: WatchState, event: WatchEvent, paths: WatchPaths): WatchDecision;
+
+export { UsageError, WATCH_DEBOUNCE_MS, WATCH_SETTLE_MS, type WatchAction, type WatchDecision, type WatchEvent, type WatchPaths, type WatchState, beginWatchRun, cleanInstallEnv, decideWatchEvent, finishWatchRun, initialWatchState, isGeneratedWatchPath, main, parseByteOption, parseCliArgs, parsePositiveInteger };