@unbrained/pm-cli 2026.10.11 → 2026.10.13

package/dist/sdk/files.d.ts

@@ -4,181 +4,181 @@ import { type LinkedPathValidation } from "./linked-artifacts.js";
 import { type SourceLineRange, type SourceTraceabilityExplanation, type SourceTraceabilityReceipt } from "./traceability/source-traceability.js";
 /** Documents the files command options payload exchanged by command, SDK, and package integrations. */
 export interface FilesCommandOptions {
-    /** Value that configures or reports add for this contract. */
-    add?: string[];
-    /** Value that configures or reports add glob for this contract. */
-    addGlob?: string[];
-    /** Value that configures or reports remove for this contract. */
-    remove?: string[];
-    /** Value that configures or reports migrate for this contract. */
-    migrate?: string[];
-    /** GH-170 (pm-pfnx): standalone note applied to every --add/--add-glob link in this invocation. */
-    note?: string;
-    /** Value that configures or reports list for this contract. */
-    list?: boolean;
-    /** Value that configures or reports append stable for this contract. */
-    appendStable?: boolean;
-    /** Value that configures or reports validate paths for this contract. */
-    validatePaths?: boolean;
-    /** Value that configures or reports author for this contract. */
-    author?: string;
-    /** Human-readable explanation suitable for logs and agent-facing output. */
-    message?: string;
-    /** Value that configures or reports force for this contract. */
-    force?: boolean;
+/** Value that configures or reports add for this contract. */
+add?: string[];
+/** Value that configures or reports add glob for this contract. */
+addGlob?: string[];
+/** Value that configures or reports remove for this contract. */
+remove?: string[];
+/** Value that configures or reports migrate for this contract. */
+migrate?: string[];
+/** GH-170 (pm-pfnx): standalone note applied to every --add/--add-glob link in this invocation. */
+note?: string;
+/** Value that configures or reports list for this contract. */
+list?: boolean;
+/** Value that configures or reports append stable for this contract. */
+appendStable?: boolean;
+/** Value that configures or reports validate paths for this contract. */
+validatePaths?: boolean;
+/** Value that configures or reports author for this contract. */
+author?: string;
+/** Human-readable explanation suitable for logs and agent-facing output. */
+message?: string;
+/** Value that configures or reports force for this contract. */
+force?: boolean;
 }
 /** Documents the files discover options payload exchanged by command, SDK, and package integrations. */
 export interface FilesDiscoverOptions {
-    /** Value that configures or reports apply for this contract. */
-    apply?: boolean;
-    /** Value that configures or reports append stable for this contract. */
-    appendStable?: boolean;
-    /** Value that configures or reports note for this contract. */
-    note?: string;
-    /** Value that configures or reports author for this contract. */
-    author?: string;
-    /** Human-readable explanation suitable for logs and agent-facing output. */
-    message?: string;
-    /** Value that configures or reports force for this contract. */
-    force?: boolean;
+/** Value that configures or reports apply for this contract. */
+apply?: boolean;
+/** Value that configures or reports append stable for this contract. */
+appendStable?: boolean;
+/** Value that configures or reports note for this contract. */
+note?: string;
+/** Value that configures or reports author for this contract. */
+author?: string;
+/** Human-readable explanation suitable for logs and agent-facing output. */
+message?: string;
+/** Value that configures or reports force for this contract. */
+force?: boolean;
 }
 /** Documents the files discovery candidate payload exchanged by command, SDK, and package integrations. */
 export interface FilesDiscoveryCandidate {
-    /** Filesystem path used for path resolution. */
-    path: string;
-    /** Value that configures or reports scope for this contract. */
-    scope: LinkScope;
-    /** Lifecycle state reported for status. */
-    status: "addable" | "already_linked";
-    /** Number of source entries represented by this result. */
-    source_count: number;
-    /** Value that configures or reports source fields for this contract. */
-    source_fields: string[];
-    /** Value that configures or reports original paths for this contract. */
-    original_paths: string[];
+/** Filesystem path used for path resolution. */
+path: string;
+/** Value that configures or reports scope for this contract. */
+scope: LinkScope;
+/** Lifecycle state reported for status. */
+status: "addable" | "already_linked";
+/** Number of source entries represented by this result. */
+source_count: number;
+/** Value that configures or reports source fields for this contract. */
+source_fields: string[];
+/** Value that configures or reports original paths for this contract. */
+original_paths: string[];
 }
 /** Documents the files result payload exchanged by command, SDK, and package integrations. */
 export interface FilesResult {
-    /** Stable identifier used to reference this record across commands and storage. */
-    id: string;
-    /** Value that configures or reports files for this contract. */
-    files: LinkedFile[];
-    /** Value that configures or reports changed for this contract. */
-    changed: boolean;
-    /** Value that configures or reports count for this contract. */
-    count: number;
-    /** Value that configures or reports migrations applied for this contract. */
-    migrations_applied?: number;
-    /** Value that configures or reports validation for this contract. */
-    validation?: LinkedPathValidation;
+/** Stable identifier used to reference this record across commands and storage. */
+id: string;
+/** Value that configures or reports files for this contract. */
+files: LinkedFile[];
+/** Value that configures or reports changed for this contract. */
+changed: boolean;
+/** Value that configures or reports count for this contract. */
+count: number;
+/** Value that configures or reports migrations applied for this contract. */
+migrations_applied?: number;
+/** Value that configures or reports validation for this contract. */
+validation?: LinkedPathValidation;
 }
 /** Documents the files discover result payload exchanged by command, SDK, and package integrations. */
 export interface FilesDiscoverResult {
-    /** Stable identifier used to reference this record across commands and storage. */
-    id: string;
-    /** Value that configures or reports files for this contract. */
-    files: LinkedFile[];
-    /** Value that configures or reports changed for this contract. */
-    changed: boolean;
-    /** Value that configures or reports apply for this contract. */
-    apply: boolean;
-    /** Value that configures or reports count for this contract. */
-    count: number;
-    /** Number of candidate entries represented by this result. */
-    candidate_count: number;
-    /** Number of addable entries represented by this result. */
-    addable_count: number;
-    /** Number of added entries represented by this result. */
-    added_count: number;
-    /** Number of skipped existing entries represented by this result. */
-    skipped_existing_count: number;
-    /** Value that configures or reports candidates for this contract. */
-    candidates: FilesDiscoveryCandidate[];
-    /** Value that configures or reports added for this contract. */
-    added: LinkedFile[];
-    /** Value that configures or reports skipped existing for this contract. */
-    skipped_existing: FilesDiscoveryCandidate[];
+/** Stable identifier used to reference this record across commands and storage. */
+id: string;
+/** Value that configures or reports files for this contract. */
+files: LinkedFile[];
+/** Value that configures or reports changed for this contract. */
+changed: boolean;
+/** Value that configures or reports apply for this contract. */
+apply: boolean;
+/** Value that configures or reports count for this contract. */
+count: number;
+/** Number of candidate entries represented by this result. */
+candidate_count: number;
+/** Number of addable entries represented by this result. */
+addable_count: number;
+/** Number of added entries represented by this result. */
+added_count: number;
+/** Number of skipped existing entries represented by this result. */
+skipped_existing_count: number;
+/** Value that configures or reports candidates for this contract. */
+candidates: FilesDiscoveryCandidate[];
+/** Value that configures or reports added for this contract. */
+added: LinkedFile[];
+/** Value that configures or reports skipped existing for this contract. */
+skipped_existing: FilesDiscoveryCandidate[];
 }
 /** Documents reverse linked-file lookup options shared by CLI, SDK, and MCP. */
 export interface FilesLookupOptions {
-    /** Project-relative or absolute source paths to resolve. */
-    paths: string[];
-    /** Restrict matches to one linked-file scope. */
-    scope?: LinkScope;
-    /** Maximum referencing items returned. */
-    limit?: number;
-    /** Number of ordered referencing items skipped. */
-    offset?: number;
-    /** Return every match instead of applying the default output bound. */
-    noTruncate?: boolean;
-    /** Fail when any authoritative item cannot be read. */
-    strictRead?: boolean;
-    /** Include rationale, governing-decision paths, and ambiguity receipts. */
-    explain?: boolean;
-    /** Optional inclusive line range; implies explain and requires one path. */
-    lineRange?: SourceLineRange;
-    /** Maximum relationship depth searched for a governing decision. */
-    decisionDepth?: number;
+/** Project-relative or absolute source paths to resolve. */
+paths: string[];
+/** Restrict matches to one linked-file scope. */
+scope?: LinkScope;
+/** Maximum referencing items returned. */
+limit?: number;
+/** Number of ordered referencing items skipped. */
+offset?: number;
+/** Return every match instead of applying the default output bound. */
+noTruncate?: boolean;
+/** Fail when any authoritative item cannot be read. */
+strictRead?: boolean;
+/** Include rationale, governing-decision paths, and ambiguity receipts. */
+explain?: boolean;
+/** Optional inclusive line range; implies explain and requires one path. */
+lineRange?: SourceLineRange;
+/** Maximum relationship depth searched for a governing decision. */
+decisionDepth?: number;
 }
 /** Token-efficient item identity returned by reverse linked-file lookup. */
 export interface FilesLookupItem {
-    /** Stable item identifier. */
-    id: string;
-    /** Human-readable item title. */
-    title: string;
-    /** Item kind. */
-    type: string;
-    /** Lifecycle status. */
-    status: string;
-    /** Numeric scheduling priority. */
-    priority: number;
-    /** Last authoritative update timestamp. */
-    updated_at: string;
+/** Stable item identifier. */
+id: string;
+/** Human-readable item title. */
+title: string;
+/** Item kind. */
+type: string;
+/** Lifecycle status. */
+status: string;
+/** Numeric scheduling priority. */
+priority: number;
+/** Last authoritative update timestamp. */
+updated_at: string;
 }
 /** One item and its exact file links that matched a reverse lookup. */
 export interface FilesLookupMatch {
-    /** Referencing item identity. */
-    item: FilesLookupItem;
-    /** Matching linked-file evidence. */
-    files: LinkedFile[];
-    /** Optional bounded rationale and line-attribution explanation. */
-    traceability?: SourceTraceabilityExplanation;
+/** Referencing item identity. */
+item: FilesLookupItem;
+/** Matching linked-file evidence. */
+files: LinkedFile[];
+/** Optional bounded rationale and line-attribution explanation. */
+traceability?: SourceTraceabilityExplanation;
 }
 /** Reverse linked-file lookup result with bounded output and read provenance. */
 export interface FilesLookupResult {
-    /** Normalized paths used for matching. */
-    paths: string[];
-    /** Total referencing items before pagination. */
-    total: number;
-    /** Number of matches in this page. */
-    count: number;
-    /** Zero-based page offset. */
-    offset: number;
-    /** Effective result limit, or null when unbounded. */
-    limit: number | null;
-    /** Whether more matches remain after this page. */
-    has_more: boolean;
-    /** Whether the current page is bounded below the total match count. */
-    truncated: boolean;
-    /** Read source and completeness receipt. */
-    completeness: {
-        status: "complete" | "partial" | "unchecked";
-        source: "index" | "source_scan";
-    };
-    /** Non-fatal authoritative read warnings. */
-    warnings: string[];
-    /** Ordered reverse-traceability matches. */
-    matches: FilesLookupMatch[];
-    /** Aggregate receipt for an explained source query. */
-    traceability_receipt?: SourceTraceabilityReceipt;
+/** Normalized paths used for matching. */
+paths: string[];
+/** Total referencing items before pagination. */
+total: number;
+/** Number of matches in this page. */
+count: number;
+/** Zero-based page offset. */
+offset: number;
+/** Effective result limit, or null when unbounded. */
+limit: number | null;
+/** Whether more matches remain after this page. */
+has_more: boolean;
+/** Whether the current page is bounded below the total match count. */
+truncated: boolean;
+/** Read source and completeness receipt. */
+completeness: {
+status: "complete" | "partial" | "unchecked";
+source: "index" | "source_scan";
+};
+/** Non-fatal authoritative read warnings. */
+warnings: string[];
+/** Ordered reverse-traceability matches. */
+matches: FilesLookupMatch[];
+/** Aggregate receipt for an explained source query. */
+traceability_receipt?: SourceTraceabilityReceipt;
 }
 interface TextReference {
-    field: string;
-    value: string;
+field: string;
+value: string;
 }
 interface RawPathReference {
-    field: string;
-    value: string;
+field: string;
+value: string;
 }
 declare function normalizeCandidatePathForOutput(value: string): string;
 declare function realpathForContainment(inputPath: string): Promise<string>;
@@ -191,16 +191,16 @@ declare function resolveDiscoveredFile(rawPath: string, workspaceRoot: string, i
 declare function discoverReferencedFiles(document: ItemDocument, workspaceRoot: string, invocationRoot?: string): Promise<FilesDiscoveryCandidate[]>;
 /** Public contract for test only, shared by SDK and presentation-layer consumers. */
 export declare const _testOnly: {
-    relativeReferenceScanMaxChars: number;
-    normalizeCandidatePathForOutput: typeof normalizeCandidatePathForOutput;
-    realpathForContainment: typeof realpathForContainment;
-    linkedFileResolvedKey: typeof linkedFileResolvedKey;
-    collectTextReferences: typeof collectTextReferences;
-    collectItemTextReferences: typeof collectItemTextReferences;
-    cleanupPathToken: typeof cleanupPathToken;
-    extractRawPathReferences: typeof extractRawPathReferences;
-    resolveDiscoveredFile: typeof resolveDiscoveredFile;
-    discoverReferencedFiles: typeof discoverReferencedFiles;
+relativeReferenceScanMaxChars: number;
+normalizeCandidatePathForOutput: typeof normalizeCandidatePathForOutput;
+realpathForContainment: typeof realpathForContainment;
+linkedFileResolvedKey: typeof linkedFileResolvedKey;
+collectTextReferences: typeof collectTextReferences;
+collectItemTextReferences: typeof collectItemTextReferences;
+cleanupPathToken: typeof cleanupPathToken;
+extractRawPathReferences: typeof extractRawPathReferences;
+resolveDiscoveredFile: typeof resolveDiscoveredFile;
+discoverReferencedFiles: typeof discoverReferencedFiles;
 };
 /** Implements run files for the public runtime surface of this module. */
 export declare function runFiles(id: string, options: FilesCommandOptions, global: GlobalOptions): Promise<FilesResult>;

package/dist/sdk/flag-invocation-contracts.d.ts

@@ -3,59 +3,59 @@ import type { CliFlagContract } from "./cli-contracts.js";
 export type CliFlagInputSource = "argv" | "file" | "stdin";
 /** Complete invocation semantics for one accepted CLI flag. */
 export interface CliFlagInvocationContract extends CliFlagContract {
-    /** Human-readable behavior, always present for generated surfaces. */
-    description: string;
-    /** Whether the option consumes a value token. */
-    takes_value: boolean;
-    /** Whether omission of the consumed value is invalid. */
-    value_required: boolean;
-    /** Machine value type after CLI parsing. */
-    value_type: "string" | "number" | "boolean";
-    /** Whether the option itself is required. */
-    required: boolean;
-    /** Whether repeated occurrences accumulate. */
-    repeatable: boolean;
-    /** Accepted value channels. */
-    input_sources: CliFlagInputSource[];
-    /** Sentinel that redirects the argv value to stdin. */
-    stdin_token?: "-";
-    /** Prefix that redirects the argv value to a file path. */
-    file_token_prefix?: "@";
+/** Human-readable behavior, always present for generated surfaces. */
+description: string;
+/** Whether the option consumes a value token. */
+takes_value: boolean;
+/** Whether omission of the consumed value is invalid. */
+value_required: boolean;
+/** Machine value type after CLI parsing. */
+value_type: "string" | "number" | "boolean";
+/** Whether the option itself is required. */
+required: boolean;
+/** Whether repeated occurrences accumulate. */
+repeatable: boolean;
+/** Accepted value channels. */
+input_sources: CliFlagInputSource[];
+/** Sentinel that redirects the argv value to stdin. */
+stdin_token?: "-";
+/** Prefix that redirects the argv value to a file path. */
+file_token_prefix?: "@";
 }
 /** Executable option arity observed from the registered Commander program. */
 export interface CliFlagArityObservation {
-    /** Canonical command path owning the option. */
-    command: string;
-    /** Long option spelling. */
-    flag: string;
-    /** Whether the option consumes a value token. */
-    takes_value: boolean;
-    /** Whether the consumed value is mandatory. */
-    value_required: boolean;
-    /** Whether repeated values accumulate. */
-    repeatable: boolean;
+/** Canonical command path owning the option. */
+command: string;
+/** Long option spelling. */
+flag: string;
+/** Whether the option consumes a value token. */
+takes_value: boolean;
+/** Whether the consumed value is mandatory. */
+value_required: boolean;
+/** Whether repeated values accumulate. */
+repeatable: boolean;
 }
 /** One machine-readable mismatch between declared and executable flag arity. */
 export interface CliFlagInvocationParityFinding {
-    /** Stable finding code. */
-    code: "duplicate_observation" | "missing_observation" | "takes_value_mismatch" | "value_required_mismatch" | "repeatable_mismatch" | "undeclared_observation";
-    /** Canonical command path. */
-    command: string;
-    /** Long option spelling. */
-    flag: string;
-    /** Human-readable mismatch detail. */
-    detail: string;
+/** Stable finding code. */
+code: "duplicate_observation" | "missing_observation" | "takes_value_mismatch" | "value_required_mismatch" | "repeatable_mismatch" | "undeclared_observation";
+/** Canonical command path. */
+command: string;
+/** Long option spelling. */
+flag: string;
+/** Human-readable mismatch detail. */
+detail: string;
 }
 /** Complete parity receipt for one command's declared and executable flags. */
 export interface CliFlagInvocationParityReport {
-    /** Whether the two surfaces agree exactly. */
-    ok: boolean;
-    /** Number of declared invocation rows. */
-    declared_count: number;
-    /** Number of executable observations. */
-    observed_count: number;
-    /** Stable mismatch list. */
-    findings: CliFlagInvocationParityFinding[];
+/** Whether the two surfaces agree exactly. */
+ok: boolean;
+/** Number of declared invocation rows. */
+declared_count: number;
+/** Number of executable observations. */
+observed_count: number;
+/** Stable mismatch list. */
+findings: CliFlagInvocationParityFinding[];
 }
 /** Enrich one vocabulary row with deterministic invocation and input-channel metadata. */
 export declare function enrichCliFlagInvocationContract(command: string, contract: CliFlagContract): CliFlagInvocationContract;