@niujiajie/freespec 0.0.0-stage → 1.15.0

package/dist/utils/interactive.js

@@ -0,0 +1,174 @@
+import { createInterface } from 'node:readline';
+/**
+ * Resolves whether non-interactive mode is requested.
+ * Handles both explicit `noInteractive: true` and Commander.js style `interactive: false`.
+ * Use this helper instead of manually checking options.noInteractive to avoid bugs.
+ */
+export function resolveNoInteractive(value) {
+    if (typeof value === 'boolean')
+        return value;
+    return value?.noInteractive === true || value?.interactive === false;
+}
+export function isInteractive(value) {
+    if (resolveNoInteractive(value))
+        return false;
+    if (process.env.OPEN_SPEC_INTERACTIVE === '0')
+        return false;
+    // Respect the standard CI environment variable (set by GitHub Actions, GitLab CI, Travis, etc.)
+    if ('CI' in process.env)
+        return false;
+    return !!process.stdin.isTTY;
+}
+/**
+ * True when a prompt failed because no answer could be read — an agent or a
+ * script that ran the command with stdin closed, a CI job, or a shell whose
+ * stdin is not a terminal. @inquirer rejects those with `User force closed
+ * the prompt with 0 null`, which is accurate and useless: it names no flag
+ * and no next step (#1479).
+ *
+ * Two things it deliberately is not:
+ *
+ * - It is not a substitute for `isInteractive()`. This classifies a prompt
+ *   that has *already failed*, so piped answers are unaffected: an answer
+ *   that arrives resolves the prompt and never reaches this check. Refusing
+ *   to prompt up front would break `printf 'y\n' | freespec archive ...`,
+ *   which works today.
+ * - It is not a cancellation check. Ctrl-C raises the same error class, and
+ *   it reaches a process whose stdin is a pipe just as easily as one at a
+ *   terminal, so the SIGINT signal - not the terminal - is what proves
+ *   somebody was there and chose to quit.
+ *
+ * Beyond that it defers to `isInteractive()`, so `CI`, `OPEN_SPEC_INTERACTIVE=0`
+ * and `--no-interactive` count even when a runner allocated a pty. It also
+ * counts a redirected stdout: `confirmPrompt` drops to the plain reader whenever
+ * *either* stream is not a TTY, so a stdin-TTY-but-stdout-redirected run
+ * (`freespec archive x > log.txt` from a terminal) that hits EOF must classify
+ * the same way the prompt was selected — otherwise it would leak the raw
+ * `ExitPromptError` instead of the `--yes` guidance.
+ */
+export function isNonInteractivePromptError(error, value) {
+    if (!(error instanceof Error))
+        return false;
+    const failedPrompt = error.name === 'ExitPromptError' || error.message.includes('force closed the prompt');
+    if (!failedPrompt)
+        return false;
+    if (error.message.includes('SIGINT'))
+        return false;
+    return !isInteractive(value) || !process.stdout.isTTY;
+}
+/**
+ * Ask a yes/no question. A real terminal gets @inquirer's rich prompt;
+ * everything else — a pipe, a file redirect, an agent that captures stdout —
+ * reads one plain line instead.
+ *
+ * @inquirer renders `confirm` by writing ANSI cursor-movement escape sequences,
+ * and it emits them even when stdout is not a TTY. Redirected to a file those
+ * sequences are noise, and in some non-TTY hosts the render loop never settles
+ * and repeats `ESC[NNG` cursor moves until the disk fills (#1526). Reading
+ * the answer ourselves keeps the single piped answer @inquirer ever supported
+ * working (`printf 'y\n' | freespec archive ...`) without emitting any escapes.
+ *
+ * `io` overrides the streams; it exists for tests and mirrors @inquirer's own
+ * `{ input, output }` context. Production callers pass only the prompt.
+ */
+export async function confirmPrompt(prompt, io = {}) {
+    const input = io.input ?? process.stdin;
+    const output = io.output ?? process.stdout;
+    const isTerminal = Boolean(input.isTTY) &&
+        Boolean(output.isTTY);
+    if (isTerminal) {
+        const { confirm } = await import('@inquirer/prompts');
+        return confirm(prompt);
+    }
+    return readYesNo(prompt, input, output);
+}
+function readYesNo(prompt, input, output) {
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        // Detach the input-stream error listener on settle: `input` is the
+        // long-lived process.stdin, so a leftover listener would accumulate across
+        // archive's successive prompts and swallow a later, unrelated stdin error.
+        const cleanup = () => {
+            input.removeListener('error', onError);
+        };
+        const blockOnNoAnswer = () => {
+            if (settled)
+                return;
+            settled = true;
+            cleanup();
+            // No line could be read (stdin closed / EOF). Mirror @inquirer's failure
+            // so callers that classify it — isNonInteractivePromptError, the #1479
+            // "rerun with --yes" guidance — keep working unchanged.
+            const error = new Error('User force closed the prompt');
+            error.name = 'ExitPromptError';
+            reject(error);
+        };
+        // A stdin error surfaces on the interface (readline forwards input-stream
+        // errors since Node 16). Without a handler the promise would hang and the
+        // 'error' would go unhandled; settle it with the real fault instead.
+        const onError = (err) => {
+            if (settled)
+                return;
+            settled = true;
+            cleanup();
+            rl.close();
+            reject(err instanceof Error ? err : new Error(String(err)));
+        };
+        // An earlier prompt may have already drained stdin (only one piped answer
+        // was ever supported). A fresh readline over an ended stream never emits
+        // 'close', so guard here rather than hang and exit as a no-op.
+        if (input.readableEnded) {
+            blockOnNoAnswer();
+            return;
+        }
+        output.write(`${prompt.message} ${prompt.default ? '(Y/n)' : '(y/N)'} `);
+        // terminal:false guarantees readline never emits its own line-editing
+        // escapes — an escape-free read is the whole point here.
+        const rl = createInterface({ input, terminal: false });
+        input.once('error', onError);
+        rl.once('error', onError);
+        rl.once('line', (line) => {
+            if (settled)
+                return;
+            settled = true;
+            cleanup();
+            rl.close();
+            output.write('\n');
+            // Mirror @inquirer/confirm's parser (prefix match on y/yes and n/no,
+            // otherwise the default) so a piped answer resolves identically to the
+            // interactive prompt it replaces.
+            const answer = line.trim();
+            if (/^(y|yes)/i.test(answer)) {
+                resolve(true);
+            }
+            else if (/^(n|no)/i.test(answer)) {
+                resolve(false);
+            }
+            else {
+                resolve(prompt.default);
+            }
+        });
+        rl.once('close', () => {
+            blockOnNoAnswer();
+        });
+    });
+}
+/**
+ * Whether a spinner can safely render to `stream`.
+ *
+ * ora decides how many lines to erase with `ceil(width / stream.columns)`, so a
+ * TTY that reports zero columns makes that count `Infinity` and `clear()` never
+ * ends: the spinner emits cursor-up/clear-line escapes as fast as it can and the
+ * command never finishes (#2106). Zero-width TTYs are real — a pty inherited
+ * from a pre-commit runner such as lefthook, or `script -qec` — and nothing can
+ * be drawn in zero columns anyway, so refuse the spinner and let the caller fall
+ * back to its plain output.
+ */
+export function canRenderSpinner(stream = process.stderr) {
+    // A non-TTY stream never enters the clear loop: ora disables itself and
+    // prints one plain line instead.
+    if (!stream.isTTY)
+        return true;
+    return (stream.columns ?? 0) > 0;
+}
+//# sourceMappingURL=interactive.js.map

package/dist/utils/item-discovery.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Returns the ids of active changes: every `<名称>变更` directory directly under freespec/.
+ *
+ * A change is resolved by its directory alone - the same rule `list`,
+ * `status`, `instructions` and `validate` use (`getAvailableChanges`).
+ * Requiring proposal.md here made `freespec show` and shell completion miss
+ * changes those commands resolve: `freespec new change <name>` scaffolds only
+ * `.freespec.yaml`, and a custom schema need not define a proposal artifact at
+ * all (#1161).
+ */
+export declare function getActiveChangeIds(root?: string): Promise<string[]>;
+/** Main specs and archived changes are not part of this workflow. */
+export declare function getSpecIds(_root?: string): Promise<string[]>;
+export declare function getArchivedChangeIds(_root?: string): Promise<string[]>;
+//# sourceMappingURL=item-discovery.d.ts.map

package/dist/utils/item-discovery.js

@@ -0,0 +1,33 @@
+import { promises as fs } from 'fs';
+import { changeParentDir, isChangeDirectoryName } from '../core/change-layout.js';
+/**
+ * Returns the ids of active changes: every `<名称>变更` directory directly under freespec/.
+ *
+ * A change is resolved by its directory alone - the same rule `list`,
+ * `status`, `instructions` and `validate` use (`getAvailableChanges`).
+ * Requiring proposal.md here made `freespec show` and shell completion miss
+ * changes those commands resolve: `freespec new change <name>` scaffolds only
+ * `.freespec.yaml`, and a custom schema need not define a proposal artifact at
+ * all (#1161).
+ */
+export async function getActiveChangeIds(root = process.cwd()) {
+    const changesPath = changeParentDir(root);
+    try {
+        const entries = await fs.readdir(changesPath, { withFileTypes: true });
+        return entries
+            .filter((entry) => entry.isDirectory() && isChangeDirectoryName(entry.name))
+            .map((entry) => entry.name)
+            .sort();
+    }
+    catch {
+        return [];
+    }
+}
+/** Main specs and archived changes are not part of this workflow. */
+export async function getSpecIds(_root = process.cwd()) {
+    return [];
+}
+export async function getArchivedChangeIds(_root = process.cwd()) {
+    return [];
+}
+//# sourceMappingURL=item-discovery.js.map

package/dist/utils/line-endings.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Line-ending helpers.
+ *
+ * Every parser in this codebase normalizes CRLF to LF on the way in, so all
+ * serialization logic can assume '\n'. That leaves the write side responsible
+ * for restoring whatever convention the file already used: without it, editing
+ * one requirement in a CRLF spec rewrites every line of the file and buries the
+ * real change in the diff.
+ */
+export type LineEnding = '\n' | '\r\n';
+/**
+ * The dominant line ending in `content`, or undefined when it holds no line
+ * break to judge from.
+ *
+ * Mixed files resolve to whichever ending is more common, with CRLF winning a
+ * tie: a file that is mostly CRLF is a CRLF file that picked up a stray LF, and
+ * settling the whole file on one ending is what keeps later diffs small.
+ */
+export declare function detectLineEnding(content: string): LineEnding | undefined;
+/**
+ * Re-apply `ending` to LF-normalized `content`.
+ *
+ * Normalizes to LF first, so the result is uniform even if the caller passed
+ * content that already contained CRLF.
+ */
+export declare function applyLineEnding(content: string, ending: LineEnding): string;
+/**
+ * Rewrite `content` to match the convention of `original`.
+ *
+ * When `original` has no line break to learn from, `content` is left as LF —
+ * the portable default this project writes new files with.
+ */
+export declare function matchLineEnding(content: string, original: string): string;
+//# sourceMappingURL=line-endings.d.ts.map

package/dist/utils/line-endings.js

@@ -0,0 +1,46 @@
+/**
+ * Line-ending helpers.
+ *
+ * Every parser in this codebase normalizes CRLF to LF on the way in, so all
+ * serialization logic can assume '\n'. That leaves the write side responsible
+ * for restoring whatever convention the file already used: without it, editing
+ * one requirement in a CRLF spec rewrites every line of the file and buries the
+ * real change in the diff.
+ */
+/**
+ * The dominant line ending in `content`, or undefined when it holds no line
+ * break to judge from.
+ *
+ * Mixed files resolve to whichever ending is more common, with CRLF winning a
+ * tie: a file that is mostly CRLF is a CRLF file that picked up a stray LF, and
+ * settling the whole file on one ending is what keeps later diffs small.
+ */
+export function detectLineEnding(content) {
+    const crlf = content.match(/\r\n/g)?.length ?? 0;
+    // Count LFs not preceded by CR, so CRLF is never also counted as LF.
+    const lf = content.match(/(?<!\r)\n/g)?.length ?? 0;
+    if (crlf === 0 && lf === 0)
+        return undefined;
+    return crlf >= lf ? '\r\n' : '\n';
+}
+/**
+ * Re-apply `ending` to LF-normalized `content`.
+ *
+ * Normalizes to LF first, so the result is uniform even if the caller passed
+ * content that already contained CRLF.
+ */
+export function applyLineEnding(content, ending) {
+    const normalized = content.replace(/\r\n/g, '\n');
+    return ending === '\n' ? normalized : normalized.replace(/\n/g, '\r\n');
+}
+/**
+ * Rewrite `content` to match the convention of `original`.
+ *
+ * When `original` has no line break to learn from, `content` is left as LF —
+ * the portable default this project writes new files with.
+ */
+export function matchLineEnding(content, original) {
+    const ending = detectLineEnding(original);
+    return ending === undefined ? content : applyLineEnding(content, ending);
+}
+//# sourceMappingURL=line-endings.js.map

package/dist/utils/match.d.ts

@@ -0,0 +1,3 @@
+export declare function nearestMatches(input: string, candidates: string[], max?: number): string[];
+export declare function levenshtein(a: string, b: string): number;
+//# sourceMappingURL=match.d.ts.map

package/dist/utils/match.js

@@ -0,0 +1,22 @@
+export function nearestMatches(input, candidates, max = 5) {
+    const scored = candidates.map(candidate => ({ candidate, distance: levenshtein(input, candidate) }));
+    scored.sort((a, b) => a.distance - b.distance);
+    return scored.slice(0, max).map(s => s.candidate);
+}
+export function levenshtein(a, b) {
+    const m = a.length;
+    const n = b.length;
+    const dp = Array.from({ length: m + 1 }, () => Array(n + 1).fill(0));
+    for (let i = 0; i <= m; i++)
+        dp[i][0] = i;
+    for (let j = 0; j <= n; j++)
+        dp[0][j] = j;
+    for (let i = 1; i <= m; i++) {
+        for (let j = 1; j <= n; j++) {
+            const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+            dp[i][j] = Math.min(dp[i - 1][j] + 1, dp[i][j - 1] + 1, dp[i - 1][j - 1] + cost);
+        }
+    }
+    return dp[m][n];
+}
+//# sourceMappingURL=match.js.map

package/dist/utils/nested-change.d.ts

@@ -0,0 +1,35 @@
+/** A namespace folder under `freespec/` and the change directories buried in it. */
+export interface NestedChangeFinding {
+    /** The directory name directly under `freespec/` that is not a change. */
+    name: string;
+    /**
+     * Slash-separated paths of the nested change directories, relative to
+     * `freespec/`, sorted. Always at least one entry.
+     */
+    nested: string[];
+}
+/**
+ * Reports whether the directory `freespec/<name>/` is a namespace folder holding
+ * one or more nested change directories rather than a change of its own.
+ *
+ * Returns undefined for every ordinary change, including a scaffolded one with
+ * no artifacts yet: only a *nested* change directory distinguishes the two.
+ */
+export declare function findNestedChangesIn(changesDir: string, name: string): Promise<NestedChangeFinding | undefined>;
+/**
+ * The same check across every candidate directory under `freespec/`, for the
+ * commands that enumerate rather than resolve a single name.
+ */
+export declare function findNestedChanges(changesDir: string, names: string[]): Promise<NestedChangeFinding[]>;
+/**
+ * The stable phrase every nested-change diagnostic contains. Callers that have
+ * only the rendered message - `validate`'s next-steps, which branches on the
+ * exact issue it is advising about - recognise the case by this.
+ */
+export declare const NESTED_CHANGE_ISSUE_MARKER = "is not a change: it is a folder wrapping";
+/**
+ * The one explanation every surface prints, so the constraint and the way out
+ * read identically wherever a user meets them.
+ */
+export declare function describeNestedChange(finding: NestedChangeFinding): string;
+//# sourceMappingURL=nested-change.d.ts.map

package/dist/utils/nested-change.js

@@ -0,0 +1,185 @@
+import { promises as fs } from 'fs';
+import path from 'path';
+import { artifactOutputExists } from '../core/artifact-graph/outputs.js';
+import { resolveSchema } from '../core/artifact-graph/resolver.js';
+import { METADATA_FILENAME, resolveSchemaForChange } from './change-metadata.js';
+/**
+ * Files that only ever sit at the root of a change directory. Their presence
+ * inside a directory that is *not* directly under `freespec/` is one of the two
+ * signals that someone laid a change out in a namespace folder
+ * (`freespec/<area>/<名称>变更/`), which this workflow does not support: a change
+ * is a directory directly under `freespec/`, named `<名称>变更`.
+ *
+ * The list is deliberately short. Every entry is written by FreeSpec itself for
+ * the default schema - `.freespec.yaml` by `freespec new change` for *every*
+ * schema. A custom schema whose root artifacts are named differently can still
+ * be missed when the directory was created by hand rather than by the CLI; that
+ * misses the diagnostic and behaves exactly as it did before, which is the safe
+ * way round.
+ */
+const CHANGE_ROOT_MARKERS = [
+    METADATA_FILENAME,
+    '需求文档.md',
+    '设计文档.md',
+    '任务清单.md',
+    '测试用例.md',
+];
+/**
+ * How far below a candidate directory to look for a nested change. One level
+ * covers a nested layout (`freespec/移动端/刷新变更/`); the
+ * extra levels cover a store namespaced by more than one axis
+ * (`freespec/移动端/苹果/刷新变更/`) without turning this into an unbounded
+ * walk of every change's spec tree.
+ */
+const MAX_NESTING_DEPTH = 3;
+async function hasChangeRootMarker(dir) {
+    for (const marker of CHANGE_ROOT_MARKERS) {
+        const stats = await fs.stat(path.join(dir, marker)).catch(() => undefined);
+        if (stats?.isFile())
+            return true;
+    }
+    return false;
+}
+/**
+ * Whether `dir` is a change rather than a folder wrapping one.
+ *
+ * Two independent signals, because either alone leaves a hole. A root artifact
+ * covers the CLI-created change and the hand-made one that starts from a
+ * proposal. A populated `specs/` covers the change that starts from its delta
+ * specs - the case that arrives here most often, since a nested change is
+ * always hand-made (`freespec new change` rejects a name with a separator) and
+ * "mkdir the tree, write the deltas" is how someone gets there.
+ *
+ * The `specs/` signal is what keeps a custom schema safe. A schema may generate
+ * every root artifact into a subdirectory (`generates: rfc/proposal.md`), and
+ * such a change, created by hand so it has no `.freespec.yaml`, would otherwise
+ * look exactly like a namespace folder wrapping a change called `rfc`. Its
+ * delta specs still live under `specs/`, so it is recognised as the change it
+ * is. `specs/**\/*.md` is fixed by the delta format itself, not by the schema.
+ */
+async function looksLikeChange(dir, projectRoot) {
+    if (await hasChangeRootMarker(dir))
+        return true;
+    const thinking = await fs.stat(path.join(dir, '深思')).catch(() => undefined);
+    if (thinking?.isDirectory())
+        return true;
+    return hasSchemaOutput(dir, projectRoot);
+}
+/**
+ * Whether `dir` already holds a file exactly where the schema it resolves to
+ * would generate one - the signal `freespec status` itself uses to call an
+ * artifact done. It covers the subdirectory-rooted custom schema before any
+ * delta spec exists, when neither other signal can. A schema that cannot be
+ * resolved gives no signal, which leaves the other two in charge.
+ */
+function hasSchemaOutput(dir, projectRoot) {
+    try {
+        const schema = resolveSchema(resolveSchemaForChange(dir, undefined, projectRoot), projectRoot);
+        return schema.artifacts.some((artifact) => artifactOutputExists(dir, artifact.generates));
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Whether `dir` holds any file of its own. A change directory with content at
+ * its root - a custom schema's artifact under a name this module does not know,
+ * a README, a note - is never reported as a namespace folder. A namespace
+ * folder someone created with `mkdir` holds nothing but directories.
+ */
+async function hasOwnFile(dir) {
+    const entries = await fs
+        .readdir(dir, { withFileTypes: true })
+        .catch(() => []);
+    return entries.some((entry) => !entry.name.startsWith('.') && !entry.isDirectory());
+}
+/**
+ * Subdirectories of `dir`, or none when it cannot be read. This probe only ever
+ * adds a diagnostic, so an unreadable directory falls back to the behaviour
+ * that existed before it rather than failing the command around it.
+ */
+async function readSubdirectories(dir) {
+    const entries = await fs
+        .readdir(dir, { withFileTypes: true })
+        .catch(() => []);
+    return entries
+        .filter((entry) => entry.isDirectory() && !entry.name.startsWith('.'))
+        .map((entry) => entry.name);
+}
+/**
+ * Collects the nested change directories under `dir`, deepest search bounded by
+ * `MAX_NESTING_DEPTH`. A directory that carries a marker is reported and not
+ * descended into: its own `specs/` tree is part of that change, not a further
+ * nesting level.
+ */
+async function collectNested(dir, prefix, depth, found, projectRoot) {
+    if (depth > MAX_NESTING_DEPTH)
+        return;
+    for (const child of await readSubdirectories(dir)) {
+        const childPath = path.join(dir, child);
+        const id = `${prefix}/${child}`;
+        if (await looksLikeChange(childPath, projectRoot)) {
+            found.push(id);
+            continue;
+        }
+        await collectNested(childPath, id, depth + 1, found, projectRoot);
+    }
+}
+/**
+ * Reports whether the directory `freespec/<name>/` is a namespace folder holding
+ * one or more nested change directories rather than a change of its own.
+ *
+ * Returns undefined for every ordinary change, including a scaffolded one with
+ * no artifacts yet: only a *nested* change directory distinguishes the two.
+ */
+export async function findNestedChangesIn(changesDir, name) {
+    // `archive` is not a change and never was, so its dated entries must not be
+    // read as nested changes and offered up for renaming. `list`, `status` and
+    // `validate` already exclude it; `change show` does not.
+    if (name === 'archive' || name.startsWith('.'))
+        return undefined;
+    const dir = path.join(changesDir, name);
+    // Change folders sit directly under <root>/freespec.
+    const projectRoot = path.resolve(changesDir, '..');
+    if (await looksLikeChange(dir, projectRoot))
+        return undefined;
+    if (await hasOwnFile(dir))
+        return undefined;
+    const nested = [];
+    await collectNested(dir, name, 1, nested, projectRoot);
+    if (nested.length === 0)
+        return undefined;
+    return { name, nested: nested.sort() };
+}
+/**
+ * The same check across every candidate directory under `freespec/`, for the
+ * commands that enumerate rather than resolve a single name.
+ */
+export async function findNestedChanges(changesDir, names) {
+    const findings = await Promise.all(names.map((name) => findNestedChangesIn(changesDir, name)));
+    return findings.filter((finding) => finding !== undefined);
+}
+/**
+ * The stable phrase every nested-change diagnostic contains. Callers that have
+ * only the rendered message - `validate`'s next-steps, which branches on the
+ * exact issue it is advising about - recognise the case by this.
+ */
+export const NESTED_CHANGE_ISSUE_MARKER = 'is not a change: it is a folder wrapping';
+/** Flattens a namespace path into the change name FreeSpec would accept. */
+function flatten(nestedId) {
+    return nestedId.split('/').join('-');
+}
+/**
+ * The one explanation every surface prints, so the constraint and the way out
+ * read identically wherever a user meets them.
+ */
+export function describeNestedChange(finding) {
+    const list = finding.nested.map((id) => `freespec/${id}/`).join(', ');
+    const example = flatten(finding.nested[0]);
+    return (`"${finding.name}" ${NESTED_CHANGE_ISSUE_MARKER} ${list}. ` +
+        'A change must be a directory directly under freespec/, named with a 变更 suffix, so those ' +
+        'nested directories are invisible while the folder around them ' +
+        'is reported as a change. ' +
+        `Rename each nested change to a flat name (for example "${example}").`);
+}
+//# sourceMappingURL=nested-change.js.map

package/dist/utils/shell-detection.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Supported shell types for completion generation
+ */
+export type SupportedShell = 'zsh' | 'bash' | 'fish' | 'powershell';
+/**
+ * Result of shell detection
+ */
+export interface ShellDetectionResult {
+    /** The detected shell if supported, otherwise undefined */
+    shell: SupportedShell | undefined;
+    /** The raw shell name detected (even if unsupported), or undefined if nothing detected */
+    detected: string | undefined;
+}
+/**
+ * Detects the current user's shell based on the parent process and environment
+ *
+ * @returns Detection result with supported shell and raw detected name
+ */
+export declare function detectShell(): ShellDetectionResult;
+//# sourceMappingURL=shell-detection.d.ts.map

package/dist/utils/shell-detection.js

@@ -0,0 +1,94 @@
+import { execFileSync } from 'node:child_process';
+/**
+ * Map a raw shell name/path to a supported shell, if any.
+ */
+function matchSupportedShell(name) {
+    // Match the executable basename exactly so lookalikes such as `fish-lsp` or
+    // `bash-language-server` don't get mistaken for the shell itself. Login
+    // shells report a leading dash (e.g. `-zsh`), so strip it first.
+    const executable = name.trim().toLowerCase().split('/').pop()?.replace(/^-/, '');
+    if (executable === 'zsh')
+        return 'zsh';
+    if (executable === 'bash')
+        return 'bash';
+    if (executable === 'fish')
+        return 'fish';
+    return undefined;
+}
+/**
+ * Detect the interactive shell from the parent process.
+ *
+ * `process.env.SHELL` is only the login shell, so users whose interactive shell
+ * differs from it (e.g. running fish while their login shell is bash) are
+ * misdetected. Inspecting the parent process reflects the shell that actually
+ * launched freespec. POSIX-only and best-effort — any failure returns undefined
+ * so the caller falls back to `$SHELL`.
+ *
+ * @returns The supported shell running as the parent process, or undefined
+ */
+function detectShellFromParentProcess() {
+    // `ps` is POSIX-only; Windows shells are handled via PSModulePath/COMSPEC.
+    if (process.platform === 'win32') {
+        return undefined;
+    }
+    const ppid = process.ppid;
+    if (!ppid || ppid <= 1) {
+        return undefined;
+    }
+    try {
+        const comm = execFileSync('ps', ['-p', String(ppid), '-o', 'comm='], {
+            encoding: 'utf8',
+            timeout: 1000,
+        }).trim();
+        if (!comm) {
+            return undefined;
+        }
+        // Only trust the parent process when it maps to a supported shell; an
+        // unrelated parent (node, npm, sudo, a pager) falls through to `$SHELL`.
+        return matchSupportedShell(comm);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Detects the current user's shell based on the parent process and environment
+ *
+ * @returns Detection result with supported shell and raw detected name
+ */
+export function detectShell() {
+    // Prefer the actual running shell (parent process) over `$SHELL`, which only
+    // reflects the login shell and misses users whose interactive shell differs.
+    const parentShell = detectShellFromParentProcess();
+    if (parentShell) {
+        return { shell: parentShell, detected: parentShell };
+    }
+    // Try SHELL environment variable next (Unix-like systems)
+    const shellPath = process.env.SHELL;
+    if (shellPath) {
+        const supported = matchSupportedShell(shellPath);
+        if (supported) {
+            return { shell: supported, detected: supported };
+        }
+        // Shell detected but not supported
+        // Extract shell name from path (e.g., /bin/tcsh -> tcsh)
+        const match = shellPath.match(/\/([^/]+)$/);
+        const detectedName = match ? match[1] : shellPath;
+        return { shell: undefined, detected: detectedName };
+    }
+    // Check for PowerShell on Windows
+    // PSModulePath is a reliable PowerShell-specific environment variable
+    if (process.env.PSModulePath || process.platform === 'win32') {
+        const comspec = process.env.COMSPEC?.toLowerCase();
+        // If PSModulePath exists, we're definitely in PowerShell
+        if (process.env.PSModulePath) {
+            return { shell: 'powershell', detected: 'powershell' };
+        }
+        // On Windows without PSModulePath, we might be in cmd.exe
+        if (comspec?.includes('cmd.exe')) {
+            return { shell: undefined, detected: 'cmd.exe' };
+        }
+    }
+    return { shell: undefined, detected: undefined };
+}
+//# sourceMappingURL=shell-detection.js.map