@unbrained/pm-cli 2026.7.15 → 2026.7.17

package/dist/sdk/cli-bootstrap.d.ts

@@ -0,0 +1,122 @@
+/**
+ * @module sdk/cli-bootstrap
+ *
+ * Provides public bootstrap argument normalization for embedded CLI hosts.
+ */
+import { EXECUTABLE_COMMAND_ALIASES, type CliFlagContract } from "./cli-contracts.js";
+export { EXECUTABLE_COMMAND_ALIASES };
+/** Documents the bootstrap global options payload exchanged by command, SDK, and package integrations. */
+export interface BootstrapGlobalOptions {
+    /** Filesystem path used for path resolution. */
+    path?: string;
+    /** Value that configures or reports no extensions for this contract. */
+    noExtensions: boolean;
+    /** Value that configures or reports no pager for this contract. */
+    noPager: boolean;
+    /** Value that configures or reports json for this contract. */
+    json: boolean;
+    /** Value that configures or reports quiet for this contract. */
+    quiet: boolean;
+    /** Invocation-wide mutation author override. */
+    author?: string;
+    /** Whether `--author` was present without its required value. */
+    authorMissingValue?: true;
+}
+/** Implements parse bootstrap global options for the public runtime surface of this module. */
+export declare function parseBootstrapGlobalOptions(argv: string[]): BootstrapGlobalOptions;
+/** Implements strip global bootstrap tokens for the public runtime surface of this module. */
+export declare function stripGlobalBootstrapTokens(argv: string[]): string[];
+/** Documents the bootstrap help request payload exchanged by command, SDK, and package integrations. */
+export interface BootstrapHelpRequest {
+    /** Value that configures or reports requested for this contract. */
+    requested: boolean;
+    /** Value that configures or reports command path tokens for this contract. */
+    commandPathTokens: string[];
+}
+/** Implements parse bootstrap help request for the public runtime surface of this module. */
+export declare function parseBootstrapHelpRequest(argv: string[]): BootstrapHelpRequest;
+/** Implements parse bootstrap command name for the public runtime surface of this module. */
+export declare function parseBootstrapCommandName(argv: string[]): string | undefined;
+/** Implements apply bootstrap pager policy for the public runtime surface of this module. */
+export declare function applyBootstrapPagerPolicy(argv: string[]): () => void;
+/** Implements normalize legacy extension action syntax for the public runtime surface of this module. */
+export declare function normalizeLegacyExtensionActionSyntax(argv: string[]): string[];
+type BootstrapNormalizationReason = "legacy_extension_action" | "command_alias" | "flag_alias" | "flag_typo" | "bare_key_value" | "list_merge";
+type BootstrapNormalizationConfidence = "high" | "medium";
+/** Documents the bootstrap normalization event payload exchanged by command, SDK, and package integrations. */
+export interface BootstrapNormalizationEvent {
+    /** Value that configures or reports from for this contract. */
+    from: string;
+    /** Value that configures or reports to for this contract. */
+    to: string[];
+    /** Value that configures or reports reason for this contract. */
+    reason: BootstrapNormalizationReason;
+    /** Value that configures or reports confidence for this contract. */
+    confidence: BootstrapNormalizationConfidence;
+}
+/** Documents the bootstrap invocation normalization result payload exchanged by command, SDK, and package integrations. */
+export interface BootstrapInvocationNormalizationResult {
+    /** Value that configures or reports argv for this contract. */
+    argv: string[];
+    /** Value that configures or reports command name for this contract. */
+    commandName: string | undefined;
+    /** Value that configures or reports trace for this contract. */
+    trace: BootstrapNormalizationEvent[];
+}
+interface FlagLookup {
+    canonicalByNormalized: Map<string, string | null>;
+    canonicalByCompact: Map<string, string | null>;
+    canonicalComparables: Array<{
+        canonicalFlag: string;
+        comparable: string;
+    }>;
+    listCanonicalFlags: Set<string>;
+}
+declare function markUnambiguousFlag(map: Map<string, string | null>, key: string, canonicalFlag: string): void;
+declare function collectLongFlagCandidates(contract: CliFlagContract): string[];
+declare function buildFlagLookup(commandName: string | undefined, contractsOverride?: CliFlagContract[]): FlagLookup;
+declare function resolveCanonicalFlag(rawKey: string, lookup: FlagLookup): {
+    flag: string;
+    reason: "flag_alias" | "flag_typo";
+    confidence: BootstrapNormalizationConfidence;
+} | null;
+/** Implements list alias plural keys for the public runtime surface of this module. */
+export declare function listAliasPluralKeys(normalizedKey: string): string[];
+declare function normalizeLongOptionToken(token: string, lookup: FlagLookup, preserve?: boolean): {
+    tokens: string[];
+    event?: BootstrapNormalizationEvent;
+};
+/** Locate global path-value tokens that normalization must preserve literally. */
+declare function collectBootstrapPathValueIndices(argv: string[]): Set<number>;
+/**
+ * Coalesce repeated occurrences of comma-separated list flags into a single
+ * `--flag=v1,v2,v3` token anchored at the FIRST occurrence. Without this,
+ * Commander treats these flags as scalars and silently keeps only the last
+ * value (data loss). Both `--flag value` and `--flag=value` forms are merged;
+ * a value-less occurrence is preserved untouched, and a `--` terminator stops
+ * coalescing (remainder is passed through verbatim).
+ *
+ * `valueConsumingFlags` lists option flags (e.g. global `--path`) whose value
+ * may itself begin with `--`. Their value token is emitted verbatim so a
+ * list-flag-looking value (`--path --tags`) is never reinterpreted as a flag
+ * nor allowed to swallow the following command/positional token.
+ */
+export declare function coalesceRepeatedListFlags(argv: string[], listFlags: Set<string>, valueConsumingFlags?: Set<string>, multiValueListFlags?: Set<string>): {
+    argv: string[];
+    events: BootstrapNormalizationEvent[];
+};
+/** Accept the two-token linked-test form `pm test <id> --add command "npm test -- parser"` by merging the bare key token and its single quoted value into the documented `--add command=...` shape. Without this merge Commander binds the bare key as the option value and treats the quoted command as an excess positional, failing with "too many arguments" (GH-191). The merge only fires when EXACTLY ONE non-flag token follows the bare key, i.e. the value was quoted into one shell token — an unquoted multi-token value stays ambiguous (it may swallow the item id), still fails fast, and is routed to targeted quoting guidance by the commander error classifier instead. */
+export declare function mergeLinkedTestTwoTokenEntries(argv: string[], commandName: string | undefined, trace: BootstrapNormalizationEvent[]): string[];
+/** Implements normalize bootstrap invocation for the public runtime surface of this module. */
+export declare function normalizeBootstrapInvocation(argv: string[]): BootstrapInvocationNormalizationResult;
+/** Implements parse bootstrap type value for the public runtime surface of this module. */
+export declare function parseBootstrapTypeValue(argv: string[]): string | undefined;
+/** Public contract for test only, shared by SDK and presentation-layer consumers. */
+export declare const _testOnly: {
+    buildFlagLookup: typeof buildFlagLookup;
+    collectBootstrapPathValueIndices: typeof collectBootstrapPathValueIndices;
+    collectLongFlagCandidates: typeof collectLongFlagCandidates;
+    markUnambiguousFlag: typeof markUnambiguousFlag;
+    normalizeLongOptionToken: typeof normalizeLongOptionToken;
+    resolveCanonicalFlag: typeof resolveCanonicalFlag;
+};