@linxiraos/pi-utils 1.1.9 → 1.1.11

package/dist/types/file-lock.d.ts

@@ -0,0 +1,23 @@
+import { FileLock as NativeFileLock } from "@linxiraos/pi-natives";
+/** Controls bounded waiting when an advisory file lock is contended. */
+export interface FileLockOptions {
+    /** Maximum acquisition attempts, including the initial attempt. */
+    retries?: number;
+    /** Delay between acquisition attempts. */
+    retryDelayMs?: number;
+    /** Maximum age of the lock before it is considered stale and can be broken. */
+    staleMs?: number;
+}
+declare function getLockPath(filePath: string): string;
+declare function tryAcquireLock(lockPath: string): NativeFileLock | null;
+/** Run `fn` while holding an OS-backed exclusive lock for `filePath`. */
+export declare function withFileLock<T>(filePath: string, fn: () => Promise<T>, options?: FileLockOptions): Promise<T>;
+/**
+ * Test-only acquisition handle for forcing ownership handoffs. This is not
+ * part of the supported package API.
+ */
+export declare const __internalsForTesting: {
+    tryAcquireLock: typeof tryAcquireLock;
+    getLockPath: typeof getLockPath;
+};
+export {};

package/dist/types/format.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Format a duration in milliseconds to a short human-readable string.
+ * Examples: "123ms", "1.5s", "30m15s", "2h30m", "3d2h"
+ */
+export declare function formatDuration(ms: number): string;
+/**
+ * Format a number with K/M/B suffix for compact display.
+ * Uses 1 decimal for small leading digits when non-zero, rounded otherwise.
+ * Examples: "999", "1K", "1.5K", "25K", "1M", "1.5M", "25M", "1.5B"
+ */
+export declare function formatNumber(n: number): string;
+/**
+ * Format a byte count to a human-readable string.
+ * Examples: "512B", "1.5KB", "2.3MB", "1.2GB"
+ */
+export declare function formatBytes(bytes: number): string;
+/**
+ * Truncate a string to maxLen characters, appending an ellipsis if truncated.
+ * For display-width-aware truncation (terminals), use truncateToWidth from @linxiraos/pi-tui.
+ */
+export declare function truncate(str: string, maxLen: number, ellipsis?: string): string;
+/**
+ * Format count with pluralized label (e.g., "3 files", "1 error").
+ */
+export declare function formatCount(label: string, count: number): string;
+/**
+ * Format age from seconds to human-readable string.
+ */
+export declare function formatAge(ageSeconds: number | null | undefined): string;
+/**
+ * Pluralize a label based on the count.
+ */
+export declare function pluralize(label: string, count: number): string;
+/**
+ * Format a ratio as a percentage.
+ */
+export declare function formatPercent(ratio: number): string;

package/dist/types/frontmatter.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Recursively normalize object keys from kebab-case to camelCase — the
+ * representation convention for frontmatter consumed inside this codebase.
+ * Exported for loaders that parse with `rawKeys: true` to validate exact
+ * spec-defined keys, then normalize for storage.
+ */
+export declare function normalizeFrontmatterKeys<T>(obj: T): T;
+export declare class FrontmatterError extends Error {
+    readonly source?: unknown;
+    constructor(error: Error, source?: unknown);
+    toString(): string;
+}
+export interface FrontmatterOptions {
+    /** Source of the content (alias: source) */
+    location?: unknown;
+    /** Source of the content (alias for location) */
+    source?: unknown;
+    /** Fallback frontmatter values */
+    fallback?: Record<string, unknown>;
+    /** Normalize the content */
+    normalize?: boolean;
+    /** Level of error handling */
+    level?: "off" | "warn" | "fatal";
+    /**
+     * Attempt lenient recovery of near-miss input before failing: quote
+     * ambiguous plain scalars, replace tabs with spaces, and strip leading HTML
+     * comments ahead of the opening delimiter. Default `true`. Spec-conformant
+     * loaders set `false` so malformed input is rejected instead of silently
+     * repaired (CRLF newline normalization still applies).
+     */
+    repair?: boolean;
+    /**
+     * Preserve frontmatter keys verbatim instead of normalizing kebab-case to
+     * camelCase. Default `false`. Strict spec loaders use this so a standard
+     * key (e.g. `allowed-tools`) is never aliased with its camelCase form.
+     */
+    rawKeys?: boolean;
+}
+/**
+ * Parse YAML frontmatter from markdown content
+ * Returns { frontmatter, body } where body has frontmatter stripped
+ */
+export declare function parseFrontmatter(content: string, options?: FrontmatterOptions): {
+    frontmatter: Record<string, unknown>;
+    body: string;
+};

package/dist/types/fs-error.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Type-safe filesystem error handling utilities.
+ *
+ * Use these to check error codes without string matching on messages:
+ *
+ * @example
+ * ```ts
+ * import { isEnoent, isFsError } from "@linxiraos/pi-utils";
+ *
+ * try {
+ *     return await Bun.file(path).text();
+ * } catch (err) {
+ *     if (isEnoent(err)) return null;
+ *     throw err;
+ * }
+ * ```
+ */
+export interface FsError extends Error {
+    code: string;
+    errno?: number;
+    syscall?: string;
+    path?: string;
+}
+export declare function isFsError(err: unknown): err is FsError;
+export declare function isEnoent(err: unknown): err is FsError;
+export declare function isEacces(err: unknown): err is FsError;
+export declare function isEisdir(err: unknown): err is FsError;
+export declare function isEnotdir(err: unknown): err is FsError;
+export declare function isEexist(err: unknown): err is FsError;
+export declare function isEnotempty(err: unknown): err is FsError;
+export declare function hasFsCode(err: unknown, code: string): err is FsError;

package/dist/types/glob.d.ts

@@ -0,0 +1,28 @@
+export interface GlobPathsOptions {
+    /** Base directory for glob patterns. Defaults to getProjectDir(). */
+    cwd?: string;
+    /** Glob exclusion patterns. */
+    exclude?: string[];
+    /** Abort signal to cancel the glob. */
+    signal?: AbortSignal;
+    /** Timeout in milliseconds for the glob operation. */
+    timeoutMs?: number;
+    /** Include dotfiles when true. */
+    dot?: boolean;
+    /** Only return files (skip directories). Default: true. */
+    onlyFiles?: boolean;
+    /** Respect .gitignore files when true. Walks up directory tree to find all applicable .gitignore files. */
+    gitignore?: boolean;
+}
+/**
+ * Load .gitignore patterns from a directory and its parents.
+ * Walks up the directory tree to find all applicable .gitignore files.
+ * Returns glob-compatible exclude patterns.
+ */
+export declare function loadGitignorePatterns(baseDir: string): Promise<string[]>;
+/**
+ * Resolve filesystem paths matching glob patterns with optional exclude filters.
+ * Returns paths relative to the provided cwd (or getProjectDir()).
+ * Errors and abort/timeouts are surfaced to the caller.
+ */
+export declare function globPaths(patterns: string | string[], options?: GlobPathsOptions): Promise<string[]>;

package/dist/types/headers.d.ts

@@ -0,0 +1,34 @@
+/** Behavior-compatible reimplementation of header-generator's used surface. */
+/** A browser family supported by the curated header profiles. */
+export type BrowserName = "chrome" | "firefox" | "safari";
+/** A desktop operating system supported by the curated header profiles. */
+export type OperatingSystem = "windows" | "macos" | "linux";
+/** Constructor and per-call constraints for header generation. */
+export interface HeaderGeneratorOptions {
+    /** Browser families eligible for a draw. */
+    browsers: BrowserName[];
+    /** Browser selection query; the supported `last 3 versions` query uses the curated versions. */
+    browserListQuery: string;
+    /** Desktop operating systems eligible for a draw. */
+    operatingSystems: OperatingSystem[];
+    /** Device classes eligible for a draw. */
+    devices: "desktop"[];
+    /** Ordered locales for the Accept-Language value. */
+    locales: string[];
+    /** HTTP protocol generation mode. */
+    httpVersion: "1" | "2";
+    /** Whether impossible constraints throw instead of relaxing to a coherent profile. */
+    strict: boolean;
+    /** Random source returning a value in the range from zero (inclusive) to one (exclusive). */
+    rng: () => number;
+}
+/** A generated HTTP request header map. */
+export type Headers = Record<string, string>;
+/** Generates coherent modern desktop browser navigation headers. */
+export declare class HeaderGenerator {
+    #private;
+    /** Creates a generator with reusable constraints and an optionally injectable RNG. */
+    constructor(options?: Partial<HeaderGeneratorOptions>);
+    /** Generates one header set, applying per-call constraints and request overrides. */
+    getHeaders(options?: Partial<HeaderGeneratorOptions>, overrides?: Headers): Headers;
+}

package/dist/types/incoming-json.d.ts

@@ -0,0 +1,232 @@
+/**
+ * Typed cursors over a JSON document while its text is still arriving.
+ *
+ * {@link IncomingDoc.channel} returns a push-side {@link IncomingFeed} and a
+ * read-side {@link IncomingDoc}. The producer appends text fragments, then
+ * explicitly calls {@link IncomingFeed.finish} or {@link IncomingFeed.abort};
+ * a feed that is never closed leaves every pending pull waiting forever.
+ * There is one shared append-only buffer; cursors are cheap, immutable
+ * path handles over it, and every pull is an ordinary promise that
+ * re-scans the buffer whenever the feed changes. There are no snapshots,
+ * per-field events, or fan-out channels.
+ *
+ * A scalar completes at its closing quote/delimiter, and a container
+ * completes only when its closing delimiter arrives. Finished-but-truncated
+ * input rejects with kind `incomplete`; abandoned input rejects with
+ * `aborted`. String chunks contain only decoded text whose meaning is
+ * stable, so an escape or Unicode escape may span any number of fragments.
+ *
+ * Pulling an {@link IncomingObject.key} makes that key required: a missing
+ * or mistyped value is a structured {@link IncomingJsonError}. Object members
+ * never pulled are skipped without validation. {@link IncomingDoc.whole} is
+ * the explicit whole-document pull and runs only after successful input
+ * completion.
+ *
+ * Object cursors bind the first occurrence of a duplicate key, whereas
+ * complete-value pulls (`value()`, `collect()`, `whole()`) go through the
+ * final parser (`parseJsonWithRepair`), whose objects are last-write-wins.
+ *
+ * Mid-stream cursors tolerate incomplete tokens but read double-quoted
+ * strings with the final parser's strict closing rule: an unescaped inner
+ * `"` can never swallow a sibling key or value. A pulled scalar completes
+ * only once a value terminator follows it, like numbers, so structural
+ * garbage after a value surfaces as `incomplete` rather than a silently
+ * misparsed pull. Single-quote recovery (`'it's'`) is shared with the final
+ * parser and passes both.
+ *
+ * @example
+ * ```ts
+ * const { feed, doc } = IncomingDoc.channel();
+ * const args = doc.root().object();
+ * const content = args.key("content").string();
+ * feed.push('{"path":"a.ts","content":"hel');
+ * await content.nextChunk(); // "hel"
+ * feed.push('lo"}');
+ * feed.finish();
+ * await content.nextChunk(); // "lo"
+ * await content.nextChunk(); // undefined
+ * await args.key("path").value<string>(); // "a.ts"
+ * ```
+ */
+/** Location component in a pulled JSON path: an object member name or an array index. */
+export type PullPathSegment = string | number;
+/** JSON shape observed by a started pull. */
+export type IncomingValueKind = "null" | "boolean" | "number" | "string" | "array" | "object";
+/** Why a pull could not produce the requested shape. */
+export type PullIssueKind = 
+/** The requested member was absent when its container completed. */
+"missing"
+/** The producer finished before the pulled value's closing token. */
+ | "incomplete"
+/** The producer abandoned the input before the pull completed. */
+ | "aborted"
+/** A complete pulled value could not be parsed. */
+ | "malformed"
+/** A value was present with a different JSON shape (see `found`). */
+ | "mismatch";
+/** Structured failure while awaiting an incoming JSON value. */
+export declare class IncomingJsonError extends Error {
+    /** Full key/index path pulled by the consumer. */
+    readonly path: readonly PullPathSegment[];
+    /** Shape requested by the typed cursor. */
+    readonly expected: string;
+    /** Why the pull could not produce that shape. */
+    readonly kind: PullIssueKind;
+    /** Shape observed in the input when `kind` is `mismatch`. */
+    readonly found?: string;
+    constructor(path: readonly PullPathSegment[], expected: string, kind: PullIssueKind, options?: {
+        found?: string;
+        cause?: unknown;
+    });
+}
+type Shape = {
+    kind: "null" | "array" | "object";
+} | {
+    kind: "boolean";
+    value: boolean;
+} | {
+    kind: "number";
+    value: number;
+} | {
+    kind: "string";
+    value: string;
+    stableLen: number;
+};
+interface Located {
+    tag: "located";
+    /** Source offset of the value's first char. */
+    start: number;
+    /** Source offset just past the value's closing token; `undefined` while it is still open. */
+    end: number | undefined;
+    shape: Shape;
+}
+/** Readiness predicate a pull waits for once its value has been located. */
+type Ready = (located: Located) => boolean;
+/** Append-only buffer, terminal state, and change notification shared by one feed and its cursors. */
+declare class Shared {
+    #private;
+    text: string;
+    end: "open" | "finished" | "aborted";
+    /** Resolves once the buffer or terminal state changes after this call. */
+    get changed(): Promise<void>;
+    notify(): void;
+    /** Await input completion; rejects with `aborted` when the feed was abandoned. */
+    finished(): Promise<void>;
+    /**
+     * Await the value at `path` until `ready` accepts it. Resolves `undefined`
+     * when the value's container completed without it.
+     */
+    pull(path: readonly PullPathSegment[], expected: string, ready: Ready): Promise<Located | undefined>;
+}
+/**
+ * Push side of an {@link IncomingDoc} channel. Call {@link finish} to mark
+ * the document complete or {@link abort} to abandon it; both are idempotent
+ * and every pending pull settles on the first one.
+ */
+export declare class IncomingFeed {
+    #private;
+    constructor(shared: Shared);
+    /** Append one text fragment and wake every pending cursor. Throws once the feed is closed. */
+    push(fragment: string): void;
+    /** Mark the input complete. */
+    finish(): void;
+    /** Abandon the input; pending and future pulls reject with kind `aborted`. */
+    abort(): void;
+}
+/** Read side of one growing JSON document. */
+export declare class IncomingDoc {
+    #private;
+    constructor(shared: Shared);
+    /** Create a push feed and its read-side document. */
+    static channel(): {
+        feed: IncomingFeed;
+        doc: IncomingDoc;
+    };
+    /** Text received so far. */
+    get text(): string;
+    /** Await explicit input completion; rejects with kind `aborted` if the feed was abandoned. */
+    finished(): Promise<void>;
+    /**
+     * Parse the entire finished document with the final tolerant parser.
+     * Waits for {@link IncomingFeed.finish}; aborted input is not decoded and a
+     * document that fails the final parse rejects with kind `malformed`.
+     */
+    whole<T = unknown>(): Promise<T>;
+    /** Cursor for the root JSON value. */
+    root(): IncomingJson;
+}
+/** Cursor for one JSON value in the incoming document, addressed by path. */
+export declare class IncomingJson {
+    #private;
+    readonly path: readonly PullPathSegment[];
+    constructor(shared: Shared, path: readonly PullPathSegment[]);
+    /** Await the value's first token and report its JSON shape. */
+    kind(): Promise<IncomingValueKind>;
+    /** Await and parse the complete value. Containers go through the final tolerant parser. */
+    value<T = unknown>(): Promise<T>;
+    /** Await a complete number. */
+    number(): Promise<number>;
+    /** Await a complete boolean. */
+    boolean(): Promise<boolean>;
+    /** Await a complete `null`. */
+    null(): Promise<null>;
+    /** View this value as an incremental decoded string. */
+    string(): IncomingString;
+    /** View this value as an array of element cursors. */
+    array(): IncomingArray;
+    /** View this value as an object with keyed cursors. */
+    object(): IncomingObject;
+}
+/**
+ * Incremental decoded string consumer. Chunks are emitted in order without
+ * overlap and are always prefixes of the final decoded string;
+ * {@link text} returns the complete string independently of whether chunks
+ * were consumed. Async iteration yields chunks. Concurrent `nextChunk` /
+ * `nextLine` calls are served in call order, like a stream reader: a call
+ * whose result is abandoned still consumes its chunk.
+ */
+export declare class IncomingString implements AsyncIterable<string> {
+    #private;
+    constructor(shared: Shared, path: readonly PullPathSegment[]);
+    /** Await the next stable decoded chunk, or `undefined` after the closing quote. */
+    nextChunk(): Promise<string | undefined>;
+    /**
+     * Await the next complete decoded line, retaining its trailing newline.
+     * A final unterminated line is returned once the closing quote arrives.
+     */
+    nextLine(): Promise<string | undefined>;
+    /** Iterate complete decoded lines. */
+    lines(): AsyncGenerator<string, void, undefined>;
+    [Symbol.asyncIterator](): AsyncGenerator<string, void, undefined>;
+    /** Await the closing quote and return the complete decoded string. */
+    text(): Promise<string>;
+}
+/**
+ * Linear cursor over elements of an incoming array. Async iteration yields
+ * element cursors. Concurrent `next` calls are served in call order.
+ */
+export declare class IncomingArray implements AsyncIterable<IncomingJson> {
+    #private;
+    constructor(shared: Shared, path: readonly PullPathSegment[]);
+    /** Await the start of the next element; `undefined` only after the closing bracket. */
+    next(): Promise<IncomingJson | undefined>;
+    [Symbol.asyncIterator](): AsyncGenerator<IncomingJson, void, undefined>;
+    /** Await the closing bracket and collect the fully parsed elements. */
+    collect<T = unknown>(): Promise<T[]>;
+}
+/** Keyed cursor and final collection for an incoming object. */
+export declare class IncomingObject {
+    #private;
+    constructor(shared: Shared, path: readonly PullPathSegment[]);
+    /**
+     * Cursor bound to the first occurrence of `name`. Pulling it makes the
+     * key required: a missing member rejects with kind `missing`.
+     */
+    key(name: string): IncomingJson;
+    /**
+     * Await the closing brace and collect the object through the final parser,
+     * whose duplicate keys are last-write-wins unlike {@link key}.
+     */
+    collect<T = Record<string, unknown>>(): Promise<T>;
+}
+export {};

package/dist/types/index.d.ts

@@ -0,0 +1,43 @@
+export { once, untilAborted } from "./abortable.js";
+export * from "./async.js";
+export * from "./binary.js";
+export * from "./color.js";
+export * from "./dirs.js";
+export * from "./env.js";
+export * from "./fetch-retry.js";
+export * from "./file-lock.js";
+export * from "./format.js";
+export * from "./frontmatter.js";
+export * from "./fs-error.js";
+export * from "./glob.js";
+export * from "./incoming-json.js";
+export * from "./json.js";
+export * from "./json-parse.js";
+export * as logger from "./logger.js";
+export * from "./loop-phase.js";
+export * from "./materialize-string.js";
+export * from "./math-delimiters.js";
+export * from "./mermaid-ascii.js";
+export * from "./mime.js";
+export * from "./path.js";
+export * from "./path-tree.js";
+export * from "./peek-file.js";
+export * as postmortem from "./postmortem.js";
+export * from "./process-name.js";
+export * as procmgr from "./procmgr.js";
+export * as prompt from "./prompt.js";
+export * as ptree from "./ptree.js";
+export { AbortError, ChildProcess, Exception, NonZeroExitError } from "./ptree.js";
+export * from "./runtime-install.js";
+export * from "./sanitize-text.js";
+export * from "./snowflake.js";
+export * from "./sqlite.js";
+export * from "./stderr-guard.js";
+export * from "./stream.js";
+export * from "./tab-spacing.js";
+export * from "./temp.js";
+export * from "./tls-fetch.js";
+export * from "./type-guards.js";
+export * from "./version.js";
+export * from "./which.js";
+export declare function structuredCloneJSON<T>(value: T): T;

package/dist/types/json-lexer.d.ts

@@ -0,0 +1,116 @@
+/**
+ * Tolerant JSON lexer shared by the final parser (`parseJsonWithRepair`), the
+ * streaming partial builder (`parseStreamingJson`), and the incoming cursors
+ * (`IncomingDoc`). {@link JsonLexerMode} selects how truncation and unescaped
+ * inner double quotes are treated.
+ *
+ * The grammar is a forgiving superset of JSON covering malformations commonly
+ * produced by language models:
+ *
+ * - single-quoted strings and unquoted object keys (JSON5);
+ * - trailing / stray commas, and `//` + block comments;
+ * - Python literals `True` / `False` / `None`, plus `0x` / `0b` numbers;
+ * - raw control characters and invalid `\x` escapes inside strings (kept literally);
+ * - unescaped quotes inside strings — a single quote only closes a string when
+ *   followed by a value terminator, recovering apostrophes such as `'it's'`;
+ *   the same recovery applies to double quotes in `streaming` mode only,
+ *   everywhere else they close strictly;
+ * - unquoted string values in value position — an unrecognized bareword such
+ *   as `{"paths": packages/foo/*}` is recovered as a string up to the next
+ *   `,` / `}` / `]` / newline.
+ */
+export declare const QUOTE = 34;
+export declare const SQUOTE = 39;
+export declare const BACKSLASH = 92;
+export declare const SLASH = 47;
+export declare const COLON = 58;
+export declare const COMMA = 44;
+export declare const LBRACE = 123;
+export declare const RBRACE = 125;
+export declare const LBRACKET = 91;
+export declare const RBRACKET = 93;
+/** Valid chars after `\` in a strict JSON escape: `" \ / b f n r t u`. */
+export declare const VALID_ESCAPE_CHAR: Uint8Array<ArrayBuffer>;
+export declare function isHexDigit(cp: number): boolean;
+/** JSON insignificant whitespace (RFC 8259 §2). */
+export declare function isWhitespace(cp: number): boolean;
+/** First char of a numeric token: sign, dot, or digit. */
+export declare function isNumberStart(cp: number): boolean;
+/**
+ * Grammar tolerance selected by the lexer's consumer.
+ *
+ * - `strict`: final parse — complete input required, double quotes close strictly.
+ * - `streaming`: mid-stream snapshot — incomplete tokens tolerated and unescaped
+ *   inner double quotes recovered for display.
+ * - `incoming`: incremental typed pulls — incomplete tokens tolerated, but double
+ *   quotes close strictly so pulled values match the final parse.
+ */
+export type JsonLexerMode = "strict" | "streaming" | "incoming";
+/** Decoded state of a string token at the current streaming edge. */
+export interface JsonStringProgress {
+    /** Decoded content so far (complete when `complete` is true). */
+    value: string;
+    /**
+     * Length of the prefix of `value` whose meaning cannot change when more
+     * input arrives. Excludes a trailing split escape, a high surrogate whose
+     * low half may still follow, and everything from a quote whose close/inner
+     * reading is still undecidable at the buffer edge.
+     */
+    stableLen: number;
+    /** Whether the closing quote was consumed. */
+    complete: boolean;
+}
+/**
+ * Cursor over the input with the tolerant token readers. `pos` is the current
+ * offset; readers advance it. In `strict` mode a truncated or malformed token
+ * throws `SyntaxError`; the lenient modes report progress or return
+ * `undefined` so the caller can roll back.
+ */
+export declare class JsonLexer {
+    #private;
+    readonly src: string;
+    readonly mode: JsonLexerMode;
+    pos: number;
+    constructor(src: string, mode: JsonLexerMode, pos?: number);
+    get atEnd(): boolean;
+    /** Char code at the cursor; `NaN` at end of input (so every comparison is false). */
+    peek(): number;
+    /** Skip whitespace plus `//` line and `/* *\/` block comments. */
+    ws(): void;
+    /**
+     * Read a string starting at the opening `quote`, retaining the information
+     * an incremental consumer needs. Strict mode throws on an unterminated
+     * string; lenient modes consume to the end of input and report progress.
+     */
+    string(quote: number): JsonStringProgress;
+    /**
+     * Read a numeric token with JS `Number()` semantics (decimal with optional
+     * sign / leading or trailing dot / exponent, plus `0x` hex and `0b` binary).
+     * Non-finite or malformed tokens throw in strict mode and return
+     * `undefined` in lenient modes; the cursor is left past the token either way.
+     */
+    number(): number | undefined;
+    /**
+     * Match a keyword literal at the cursor; consumes only on success and
+     * returns `undefined` otherwise. Requires a non-identifier boundary so
+     * `Truex` / `nullish` are not misread as the keyword followed by junk.
+     */
+    keyword(): boolean | null | undefined;
+    /** Read an unquoted object key: everything up to `:` / `,` / `}` / whitespace. May be empty. */
+    unquotedKey(): string;
+    /**
+     * Recover an unquoted string value, e.g. `{"paths": packages/foo/*}`:
+     * consume until `,` / `}` / `]` / newline and trim trailing whitespace.
+     * Recovery still fails — so a final parse never accepts a half-formed or
+     * non-finite argument — when the token:
+     * - hits end-of-input before a delimiter (truncated value);
+     * - contains a `"`, `{`, `[`, or a key-like `:` — this grammar accepts
+     *   unquoted keys, so a missed comma (`{"a": foo "b": 1}`) would otherwise
+     *   silently swallow the following field. A colon followed by `/` or `\`
+     *   stays literal so URL and Windows-path values recover;
+     * - is a non-finite atom ({@link NON_RECOVERABLE_BAREWORDS}).
+     *
+     * Failure throws in strict mode and returns `undefined` in lenient modes.
+     */
+    bareword(): string | undefined;
+}