@unbrained/pm-cli 2026.7.14 → 2026.7.16

package/dist/sdk/init.d.ts

@@ -0,0 +1,186 @@
+import readline from "node:readline/promises";
+import { type TypePresetName } from "../core/schema/type-presets.js";
+import type { GlobalOptions } from "../core/shared/command-types.js";
+import type { GovernancePreset, PmSettings } from "../types/index.js";
+import { type ExtensionCommandResult } from "./extension.js";
+import { type InitAgentGuidanceMode, type InitAgentGuidanceSummary } from "./init-agent-guidance.js";
+/** Documents the init installed packages summary payload exchanged by command, SDK, and package integrations. */
+export interface InitInstalledPackagesSummary {
+    /** Value that configures or reports installed all for this contract. */
+    installed_all: boolean;
+    /** Number of installed entries represented by this result. */
+    installed_count: number;
+    /** Value that configures or reports packages for this contract. */
+    packages: Array<{
+        alias: string;
+        ok: boolean;
+    }>;
+}
+/** Restricts init type preset name values accepted by command, SDK, and storage contracts. */
+export type InitTypePresetName = TypePresetName;
+/** Documents the init registered type preset summary payload exchanged by command, SDK, and package integrations. */
+export interface InitRegisteredTypePresetSummary {
+    /** Value that configures or reports name for this contract. */
+    name: InitTypePresetName;
+    /** Value that configures or reports registered for this contract. */
+    registered: string[];
+    /** Value that configures or reports updated for this contract. */
+    updated: string[];
+    /** Value that configures or reports file for this contract. */
+    file: string;
+}
+/** Documents the init agent-guidance summary plus generated next-step hints returned by init. */
+export type InitAgentGuidanceResult = InitAgentGuidanceSummary & {
+    next_steps: string[];
+};
+/** Describes how init resolved the tracker and optional workspace target. */
+export interface InitTargetResolution {
+    /** Value that configures or reports mode for this contract. */
+    mode: "workspace-discovery" | "tracker-path" | "workspace-path";
+    /** Value that configures or reports tracker root for this contract. */
+    tracker_root: string;
+    /** Value that configures or reports workspace root for this contract. */
+    workspace_root?: string;
+}
+/** Documents the init result payload exchanged by command, SDK, and package integrations. */
+export interface InitResult {
+    /** Whether the operation completed without a blocking failure. */
+    ok: boolean;
+    /** Filesystem path used for path resolution. */
+    path: string;
+    /** Value that configures or reports target for this contract. */
+    target: InitTargetResolution;
+    /** Value that configures or reports settings for this contract. */
+    settings: PmSettings;
+    /** Value that configures or reports created dirs for this contract. */
+    created_dirs: string[];
+    /** Value that configures or reports warnings for this contract. */
+    warnings: string[];
+    /** Value that configures or reports governance preset for this contract. */
+    governance_preset: GovernancePreset;
+    /** Value that configures or reports wizard used for this contract. */
+    wizard_used: boolean;
+    /** Value that configures or reports registered type preset for this contract. */
+    registered_type_preset?: InitRegisteredTypePresetSummary;
+    /** Value that configures or reports installed packages for this contract. */
+    installed_packages?: InitInstalledPackagesSummary;
+    /** Value that configures or reports next steps for this contract. */
+    next_steps: string[];
+    /** Value that configures or reports agent guidance for this contract. */
+    agent_guidance: InitAgentGuidanceResult;
+}
+/** Documents the init command options payload exchanged by command, SDK, and package integrations. */
+export interface InitCommandOptions {
+    /** Item-id prefix supplied through the flag-oriented SDK/CLI input surface. */
+    idPrefix?: string;
+    /** Value that configures or reports preset for this contract. */
+    preset?: string;
+    /** Value that configures or reports defaults for this contract. */
+    defaults?: boolean;
+    /** Value that configures or reports author for this contract. */
+    author?: string;
+    /** Value that configures or reports with packages for this contract. */
+    withPackages?: boolean;
+    /** Value that configures or reports agent guidance for this contract. */
+    agentGuidance?: string;
+    /** Value that configures or reports type preset for this contract. */
+    typePreset?: string;
+    /** Value that configures or reports force for this contract. */
+    force?: boolean;
+    /** Value that configures or reports workspace for this contract. */
+    workspace?: string;
+}
+/** Concise projection of an InitResult for the default (toon) renderer. It keeps every piece of information that only init can surface — the resolved path, id prefix, governance preset, telemetry capture level, created-directory count, the full warnings list (including `already_exists:` markers), agent-guidance summary, and next steps — but replaces the verbose full settings tree (~190 lines) with a compact `settings` summary. Use --verbose for the full tree. */
+export interface InitConciseResult {
+    /** Whether the operation completed without a blocking failure. */
+    ok: boolean;
+    /** Filesystem path used for path resolution. */
+    path: string;
+    /** Value that configures or reports target for this contract. */
+    target: InitTargetResolution;
+    /** Value that configures or reports id prefix for this contract. */
+    id_prefix: string;
+    /** Value that configures or reports governance preset for this contract. */
+    governance_preset: GovernancePreset;
+    /** Value that configures or reports telemetry for this contract. */
+    telemetry: {
+        enabled: boolean;
+        capture_level: string;
+    };
+    /** Value that configures or reports output format for this contract. */
+    output_format: string;
+    /** Number of created dirs entries represented by this result. */
+    created_dirs_count: number;
+    /** Value that configures or reports created dirs for this contract. */
+    created_dirs: string[];
+    /** Value that configures or reports warnings for this contract. */
+    warnings: string[];
+    /** Value that configures or reports wizard used for this contract. */
+    wizard_used: boolean;
+    /** Value that configures or reports registered type preset for this contract. */
+    registered_type_preset?: InitRegisteredTypePresetSummary;
+    /** Value that configures or reports installed packages for this contract. */
+    installed_packages?: InitInstalledPackagesSummary;
+    /** Value that configures or reports next steps for this contract. */
+    next_steps: string[];
+    /** Value that configures or reports agent guidance for this contract. */
+    agent_guidance: InitAgentGuidanceResult;
+    /** Value that configures or reports hint for this contract. */
+    hint: string;
+}
+/** Implements summarize init result for the public runtime surface of this module. */
+export declare function summarizeInitResult(result: InitResult): InitConciseResult;
+/** Public contract for test only, shared by SDK and presentation-layer consumers. */
+export declare const _testOnly: {
+    normalizeInitGovernancePreset: typeof normalizeInitGovernancePreset;
+    normalizeInitTypePreset: typeof normalizeInitTypePreset;
+    normalizeOptionalInitAuthor: typeof normalizeOptionalInitAuthor;
+    normalizeInitAgentGuidanceMode: typeof normalizeInitAgentGuidanceMode;
+    isPathLikeInitTarget: typeof isPathLikeInitTarget;
+    resolveInitInvocation: typeof resolveInitInvocation;
+    resolveInitPrefixInput: typeof resolveInitPrefixInput;
+    parseYesNoChoice: typeof parseYesNoChoice;
+    applyGovernancePreset: typeof applyGovernancePreset;
+    runInitWizard: typeof runInitWizard;
+    setInitReadlineFactoryForTests: typeof setInitReadlineFactoryForTests;
+    summarizeInstalledPackages: typeof summarizeInstalledPackages;
+    buildInitNextSteps: typeof buildInitNextSteps;
+    registerInitTypePreset: typeof registerInitTypePreset;
+    assertExplicitTrackerPathIsNotWorkspaceRoot: typeof assertExplicitTrackerPathIsNotWorkspaceRoot;
+    isLikelyWorkspaceRoot: typeof isLikelyWorkspaceRoot;
+};
+type InitReadlineInterface = ReturnType<typeof readline.createInterface>;
+declare function setInitReadlineFactoryForTests(factory: (() => InitReadlineInterface) | undefined): void;
+type BuiltinGovernancePreset = Exclude<GovernancePreset, "custom">;
+declare function normalizeInitGovernancePreset(rawValue: string | undefined): BuiltinGovernancePreset | undefined;
+declare function normalizeInitTypePreset(rawValue: string | undefined): InitTypePresetName | undefined;
+declare function normalizeOptionalInitAuthor(rawValue: string | undefined): string | undefined;
+declare function isPathLikeInitTarget(rawValue: string | undefined): boolean;
+declare function resolveInitInvocation(cwd: string, global: GlobalOptions, prefixArg: string | undefined, workspaceArg?: string): {
+    pmRoot: string;
+    prefixArg: string | undefined;
+    target: InitTargetResolution;
+};
+/** Resolves the optional positional and flag-oriented id-prefix inputs, accepting equivalent normalized spellings and rejecting ambiguous conflicts. */
+declare function resolveInitPrefixInput(positionalPrefix: string | undefined, flaggedPrefix: string | undefined): string | undefined;
+declare function normalizeInitAgentGuidanceMode(rawValue: string | undefined): InitAgentGuidanceMode;
+declare function parseYesNoChoice(answer: string, currentDefault: boolean): boolean;
+declare function applyGovernancePreset(settings: PmSettings, preset: BuiltinGovernancePreset): void;
+declare function summarizeInstalledPackages(result: ExtensionCommandResult): InitInstalledPackagesSummary;
+declare function registerInitTypePreset(pmRoot: string, settings: PmSettings, preset: InitTypePresetName): Promise<InitRegisteredTypePresetSummary>;
+declare function isLikelyWorkspaceRoot(candidate: string): Promise<boolean>;
+declare function assertExplicitTrackerPathIsNotWorkspaceRoot(pmRoot: string, explicitTrackerTarget: boolean, force: boolean): Promise<void>;
+declare function runInitWizard(initialPrefix: string, telemetryDefault: boolean): Promise<{
+    prefix: string;
+    preset: BuiltinGovernancePreset;
+    telemetry_enabled: boolean;
+}>;
+declare function buildInitNextSteps(params: {
+    installBundledPackages: boolean;
+    registeredTypePreset: InitRegisteredTypePresetSummary | undefined;
+    agentGuidanceNextSteps: string[];
+    target: InitTargetResolution;
+}): string[];
+/** Implements run init for the public runtime surface of this module. */
+export declare function runInit(prefixArg: string | undefined, global: GlobalOptions, options?: InitCommandOptions): Promise<InitResult>;
+export {};