@unbrained/pm-cli 2026.7.14 → 2026.7.16

package/dist/sdk/schema.d.ts

@@ -0,0 +1,507 @@
+import { buildInvalidTypeHint, type ItemTypeDefinition } from "../core/schema/item-types-file.js";
+import { type RuntimeStatusDefinition } from "../core/schema/status-defs-file.js";
+import { type RuntimeFieldDefinition } from "../core/schema/fields-file.js";
+import { type TypePresetName } from "../core/schema/type-presets.js";
+import { type InferredTypeCandidate } from "../core/schema/type-inference.js";
+import { type ResolvedItemTypeDefinition } from "../core/item/type-registry.js";
+import type { GlobalOptions } from "../core/shared/command-types.js";
+/** Public contract for schema subcommands, shared by SDK and presentation-layer consumers. */
+export declare const SCHEMA_SUBCOMMANDS: readonly ["add-type", "remove-type", "add-status", "remove-status", "add-field", "remove-field", "list-fields", "show-field", "apply-preset", "list", "show", "show-status"];
+/** Restricts schema subcommand values accepted by command, SDK, and storage contracts. */
+export type SchemaSubcommand = (typeof SCHEMA_SUBCOMMANDS)[number];
+/** Documents the schema add type command options payload exchanged by command, SDK, and package integrations. */
+export interface SchemaAddTypeCommandOptions {
+    /** Value that configures or reports description for this contract. */
+    description?: string;
+    /** Lifecycle state reported for defaultthe record. */
+    defaultStatus?: string;
+    /** Value that configures or reports folder for this contract. */
+    folder?: string;
+    /** Value that configures or reports alias for this contract. */
+    alias?: string[];
+    /** Value that configures or reports author for this contract. */
+    author?: string;
+    /** Value that configures or reports force for this contract. */
+    force?: boolean;
+}
+/** Documents the schema remove type command options payload exchanged by command, SDK, and package integrations. */
+export interface SchemaRemoveTypeCommandOptions {
+    /** Value that configures or reports author for this contract. */
+    author?: string;
+    /** Value that configures or reports force for this contract. */
+    force?: boolean;
+}
+/** Documents the schema add status command options payload exchanged by command, SDK, and package integrations. */
+export interface SchemaAddStatusCommandOptions {
+    /** Value that configures or reports role for this contract. */
+    role?: string[];
+    /** Value that configures or reports alias for this contract. */
+    alias?: string[];
+    /** Value that configures or reports description for this contract. */
+    description?: string;
+    /** Value that configures or reports order for this contract. */
+    order?: number;
+    /** Value that configures or reports author for this contract. */
+    author?: string;
+    /** Value that configures or reports force for this contract. */
+    force?: boolean;
+}
+/** Documents the schema remove status command options payload exchanged by command, SDK, and package integrations. */
+export interface SchemaRemoveStatusCommandOptions {
+    /** Value that configures or reports author for this contract. */
+    author?: string;
+    /** Value that configures or reports force for this contract. */
+    force?: boolean;
+}
+/** Documents the schema add type result payload exchanged by command, SDK, and package integrations. */
+export interface SchemaAddTypeResult {
+    /** Value that configures or reports action for this contract. */
+    action: "add-type";
+    /** Value that configures or reports registered for this contract. */
+    registered: boolean;
+    /** Value that configures or reports replaced for this contract. */
+    replaced: boolean;
+    /** Schema type that determines the shape and validation rules for this value. */
+    type: ItemTypeDefinition;
+    /** Value that configures or reports file for this contract. */
+    file: {
+        path: string;
+        definitions: number;
+    };
+    /** Value that configures or reports warnings for this contract. */
+    warnings: string[];
+    /** ISO 8601 timestamp recording when generated occurred. */
+    generated_at: string;
+}
+/** Documents the schema remove type result payload exchanged by command, SDK, and package integrations. */
+export interface SchemaRemoveTypeResult {
+    /** Value that configures or reports action for this contract. */
+    action: "remove-type";
+    /** Value that configures or reports removed for this contract. */
+    removed: boolean;
+    /** Schema type that determines the shape and validation rules for this value. */
+    type?: ItemTypeDefinition;
+    /** Value that configures or reports file for this contract. */
+    file: {
+        path: string;
+        definitions: number;
+    };
+    /** Value that configures or reports warnings for this contract. */
+    warnings: string[];
+    /** ISO 8601 timestamp recording when generated occurred. */
+    generated_at: string;
+}
+/** Documents the schema add status result payload exchanged by command, SDK, and package integrations. */
+export interface SchemaAddStatusResult {
+    /** Value that configures or reports action for this contract. */
+    action: "add-status";
+    /** Value that configures or reports registered for this contract. */
+    registered: boolean;
+    /** Value that configures or reports replaced for this contract. */
+    replaced: boolean;
+    /** Lifecycle state reported for status. */
+    status: RuntimeStatusDefinition;
+    /** Value that configures or reports file for this contract. */
+    file: {
+        path: string;
+        statuses: number;
+    };
+    /** Value that configures or reports warnings for this contract. */
+    warnings: string[];
+    /** ISO 8601 timestamp recording when generated occurred. */
+    generated_at: string;
+}
+/** Documents the schema remove status result payload exchanged by command, SDK, and package integrations. */
+export interface SchemaRemoveStatusResult {
+    /** Value that configures or reports action for this contract. */
+    action: "remove-status";
+    /** Value that configures or reports removed for this contract. */
+    removed: boolean;
+    /** Lifecycle state reported for status. */
+    status?: RuntimeStatusDefinition;
+    /** Value that configures or reports file for this contract. */
+    file: {
+        path: string;
+        statuses: number;
+    };
+    /** Value that configures or reports warnings for this contract. */
+    warnings: string[];
+    /** ISO 8601 timestamp recording when generated occurred. */
+    generated_at: string;
+}
+/** Documents the schema add field command options payload exchanged by command, SDK, and package integrations. */
+export interface SchemaAddFieldCommandOptions {
+    /** Schema type that determines the shape and validation rules for this value. */
+    type?: string;
+    /** Value that configures or reports commands for this contract. */
+    commands?: string[];
+    /** Value that configures or reports description for this contract. */
+    description?: string;
+    /** Value that configures or reports cli flag for this contract. */
+    cliFlag?: string;
+    /** Value that configures or reports alias for this contract. */
+    alias?: string[];
+    /** Value that configures or reports required for this contract. */
+    required?: boolean;
+    /** Value that configures or reports required on create for this contract. */
+    requiredOnCreate?: boolean;
+    /** Value that configures or reports allow unset for this contract. */
+    allowUnset?: boolean;
+    /** Value that configures or reports required types for this contract. */
+    requiredTypes?: string[];
+    /** Value that configures or reports author for this contract. */
+    author?: string;
+    /** Value that configures or reports force for this contract. */
+    force?: boolean;
+}
+/** Documents the schema remove field command options payload exchanged by command, SDK, and package integrations. */
+export interface SchemaRemoveFieldCommandOptions {
+    /** Value that configures or reports author for this contract. */
+    author?: string;
+    /** Value that configures or reports force for this contract. */
+    force?: boolean;
+}
+/** Documents the schema apply preset command options payload exchanged by command, SDK, and package integrations. */
+export interface SchemaApplyPresetCommandOptions {
+    /** Value that configures or reports author for this contract. */
+    author?: string;
+    /** Value that configures or reports force for this contract. */
+    force?: boolean;
+}
+/** Documents the schema add type infer command options payload exchanged by command, SDK, and package integrations. */
+export interface SchemaAddTypeInferCommandOptions {
+    /** Number of min entries represented by this result. */
+    minCount?: number;
+    /** Value that configures or reports apply for this contract. */
+    apply?: boolean;
+    /** Value that configures or reports author for this contract. */
+    author?: string;
+    /** Value that configures or reports force for this contract. */
+    force?: boolean;
+}
+/** Documents the schema field summary payload exchanged by command, SDK, and package integrations. */
+export interface SchemaFieldSummary {
+    /** Value that configures or reports key for this contract. */
+    key: string;
+    /** Schema type that determines the shape and validation rules for this value. */
+    type: string;
+    /** Value that configures or reports commands for this contract. */
+    commands: string[];
+    /** Value that configures or reports cli flag for this contract. */
+    cli_flag: string;
+    /** Value that configures or reports cli aliases for this contract. */
+    cli_aliases: string[];
+    /** Value that configures or reports description for this contract. */
+    description?: string;
+    /** Value that configures or reports required for this contract. */
+    required: boolean;
+    /** Value that configures or reports required on create for this contract. */
+    required_on_create: boolean;
+    /** Value that configures or reports allow unset for this contract. */
+    allow_unset: boolean;
+    /** Value that configures or reports required types for this contract. */
+    required_types: string[];
+}
+/** Documents the schema add field result payload exchanged by command, SDK, and package integrations. */
+export interface SchemaAddFieldResult {
+    /** Value that configures or reports action for this contract. */
+    action: "add-field";
+    /** Value that configures or reports registered for this contract. */
+    registered: boolean;
+    /** Value that configures or reports replaced for this contract. */
+    replaced: boolean;
+    /** Value that configures or reports field for this contract. */
+    field: RuntimeFieldDefinition;
+    /** Value that configures or reports file for this contract. */
+    file: {
+        path: string;
+        fields: number;
+    };
+    /** Value that configures or reports warnings for this contract. */
+    warnings: string[];
+    /** ISO 8601 timestamp recording when generated occurred. */
+    generated_at: string;
+}
+/** Documents the schema remove field result payload exchanged by command, SDK, and package integrations. */
+export interface SchemaRemoveFieldResult {
+    /** Value that configures or reports action for this contract. */
+    action: "remove-field";
+    /** Value that configures or reports removed for this contract. */
+    removed: boolean;
+    /** Value that configures or reports field for this contract. */
+    field?: RuntimeFieldDefinition;
+    /** Value that configures or reports file for this contract. */
+    file: {
+        path: string;
+        fields: number;
+    };
+    /** Value that configures or reports warnings for this contract. */
+    warnings: string[];
+    /** ISO 8601 timestamp recording when generated occurred. */
+    generated_at: string;
+}
+/** Documents the schema list fields result payload exchanged by command, SDK, and package integrations. */
+export interface SchemaListFieldsResult {
+    /** Value that configures or reports action for this contract. */
+    action: "list-fields";
+    /** Value that configures or reports fields for this contract. */
+    fields: SchemaFieldSummary[];
+    /** Value that configures or reports counts for this contract. */
+    counts: {
+        total: number;
+    };
+    /** Value that configures or reports file for this contract. */
+    file: {
+        path: string;
+    };
+    /** ISO 8601 timestamp recording when generated occurred. */
+    generated_at: string;
+}
+/** Documents the schema show field result payload exchanged by command, SDK, and package integrations. */
+export interface SchemaShowFieldResult {
+    /** Value that configures or reports action for this contract. */
+    action: "show-field";
+    /** Value that configures or reports field for this contract. */
+    field: SchemaFieldSummary;
+    /** Value that configures or reports file for this contract. */
+    file: {
+        path: string;
+    };
+    /** ISO 8601 timestamp recording when generated occurred. */
+    generated_at: string;
+}
+/** Documents the schema apply preset result payload exchanged by command, SDK, and package integrations. */
+export interface SchemaApplyPresetResult {
+    /** Value that configures or reports action for this contract. */
+    action: "apply-preset";
+    /** Value that configures or reports preset for this contract. */
+    preset: TypePresetName;
+    /** Value that configures or reports registered for this contract. */
+    registered: string[];
+    /** Value that configures or reports replaced for this contract. */
+    replaced: string[];
+    /** Value that configures or reports file for this contract. */
+    file: {
+        path: string;
+        definitions: number;
+    };
+    /** Value that configures or reports warnings for this contract. */
+    warnings: string[];
+    /** ISO 8601 timestamp recording when generated occurred. */
+    generated_at: string;
+}
+/** Documents the schema add type infer result payload exchanged by command, SDK, and package integrations. */
+export interface SchemaAddTypeInferResult {
+    /** Value that configures or reports action for this contract. */
+    action: "infer-types";
+    /** Value that configures or reports applied for this contract. */
+    applied: boolean;
+    /** Number of min entries represented by this result. */
+    min_count: number;
+    /** Value that configures or reports candidates for this contract. */
+    candidates: InferredTypeCandidate[];
+    /** Value that configures or reports registered for this contract. */
+    registered: string[];
+    /** Value that configures or reports replaced for this contract. */
+    replaced: string[];
+    /** Value that configures or reports skipped for this contract. */
+    skipped: Array<{
+        name: string;
+        reason: string;
+    }>;
+    /** Value that configures or reports file for this contract. */
+    file: {
+        path: string;
+        definitions: number;
+    };
+    /** Value that configures or reports warnings for this contract. */
+    warnings: string[];
+    /** ISO 8601 timestamp recording when generated occurred. */
+    generated_at: string;
+}
+/** Documents the schema type summary payload exchanged by command, SDK, and package integrations. */
+export interface SchemaTypeSummary {
+    /** Value that configures or reports name for this contract. */
+    name: string;
+    /** Value that configures or reports folder for this contract. */
+    folder: string;
+    /** Value that configures or reports aliases for this contract. */
+    aliases: string[];
+    /** Lifecycle state reported for defaultthe record. */
+    default_status?: string;
+    /** Value that configures or reports description for this contract. */
+    description?: string;
+}
+/** Documents the schema status summary payload exchanged by command, SDK, and package integrations. */
+export interface SchemaStatusSummary {
+    /** Stable identifier used to reference this record across commands and storage. */
+    id: string;
+    /** Value that configures or reports source for this contract. */
+    source: "builtin" | "custom";
+    /** Value that configures or reports roles for this contract. */
+    roles: string[];
+    /** Value that configures or reports aliases for this contract. */
+    aliases: string[];
+    /** Value that configures or reports description for this contract. */
+    description?: string;
+    /** Value that configures or reports order for this contract. */
+    order?: number;
+}
+/** Documents the schema type definition result payload exchanged by command, SDK, and package integrations. */
+export interface SchemaTypeDefinitionResult extends SchemaTypeSummary {
+    /** Value that configures or reports source for this contract. */
+    source: "builtin" | "custom" | "extension";
+    /** Value that configures or reports extension for this contract. */
+    extension?: {
+        layer: string;
+        name: string;
+    };
+    /** Value that configures or reports required create fields for this contract. */
+    required_create_fields: string[];
+    /** Value that configures or reports required create repeatables for this contract. */
+    required_create_repeatables: string[];
+    /** Value that configures or reports options for this contract. */
+    options: ResolvedItemTypeDefinition["options"];
+    /** Value that configures or reports command option policies for this contract. */
+    command_option_policies: ResolvedItemTypeDefinition["command_option_policies"];
+}
+/** Documents the schema list result payload exchanged by command, SDK, and package integrations. */
+export interface SchemaListResult {
+    /** Value that configures or reports action for this contract. */
+    action: "list";
+    /** Value that configures or reports builtin for this contract. */
+    builtin: SchemaTypeSummary[];
+    /** Value that configures or reports custom for this contract. */
+    custom: SchemaTypeSummary[];
+    /** Value that configures or reports extension for this contract. */
+    extension: SchemaTypeSummary[];
+    /** Value that configures or reports counts for this contract. */
+    counts: {
+        builtin: number;
+        custom: number;
+        extension: number;
+        total: number;
+    };
+    /** Value that configures or reports statuses for this contract. */
+    statuses: {
+        builtin: SchemaStatusSummary[];
+        custom: SchemaStatusSummary[];
+        counts: {
+            builtin: number;
+            custom: number;
+            total: number;
+        };
+    };
+    /** Value that configures or reports fields for this contract. */
+    fields: {
+        custom: SchemaFieldSummary[];
+        counts: {
+            total: number;
+        };
+    };
+    /** Value that configures or reports file for this contract. */
+    file: {
+        path: string;
+    };
+    /** ISO 8601 timestamp recording when generated occurred. */
+    generated_at: string;
+}
+/** Documents the schema show result payload exchanged by command, SDK, and package integrations. */
+export interface SchemaShowResult {
+    /** Value that configures or reports action for this contract. */
+    action: "show";
+    /** Schema type that determines the shape and validation rules for this value. */
+    type: SchemaTypeDefinitionResult;
+    /** Value that configures or reports file for this contract. */
+    file: {
+        path: string;
+    };
+    /** ISO 8601 timestamp recording when generated occurred. */
+    generated_at: string;
+}
+/** Documents the schema show status result payload exchanged by command, SDK, and package integrations. */
+export interface SchemaShowStatusResult {
+    /** Value that configures or reports action for this contract. */
+    action: "show-status";
+    /** Lifecycle state reported for status. */
+    status: SchemaStatusSummary;
+    /** Value that configures or reports file for this contract. */
+    file: {
+        path: string;
+    };
+    /** ISO 8601 timestamp recording when generated occurred. */
+    generated_at: string;
+}
+/** Restricts schema inspect result values accepted by command, SDK, and storage contracts. */
+export type SchemaInspectResult = SchemaListResult | SchemaShowResult | SchemaShowStatusResult | SchemaListFieldsResult | SchemaShowFieldResult;
+declare function toAuthor(candidate: string | undefined, defaultAuthor: string): string;
+/** Implements run schema add type for the public runtime surface of this module. */
+export declare function runSchemaAddType(name: string | undefined, options: SchemaAddTypeCommandOptions, global: GlobalOptions): Promise<SchemaAddTypeResult>;
+/** Returns the workflow role-slot names (open_status, close_status, ...) that currently point at `statusId` (normalized). Used to warn before removing a status that a workflow default still references. */
+declare function workflowSlotsReferencing(workflow: {
+    draft_status?: string;
+    open_status?: string;
+    in_progress_status?: string;
+    blocked_status?: string;
+    close_status?: string;
+    canceled_status?: string;
+}, statusId: string): string[];
+/** Implements run schema remove type for the public runtime surface of this module. */
+export declare function runSchemaRemoveType(name: string | undefined, options: SchemaRemoveTypeCommandOptions, global: GlobalOptions): Promise<SchemaRemoveTypeResult>;
+/** Creates the storage folder for each item-type definition (resolving the default folder when unset) and runs on-write hooks for newly created folders. Shared with `pm profile apply` so profile-staged types scaffold identically to `pm schema add-type`. Existing folders are skipped, keeping the call idempotent. */
+export declare function ensureTypeFolderScaffold(pmRoot: string, definitions: readonly ItemTypeDefinition[], warnings: string[], op: string): Promise<void>;
+/** Implements run schema add status for the public runtime surface of this module. */
+export declare function runSchemaAddStatus(id: string | undefined, options: SchemaAddStatusCommandOptions, global: GlobalOptions): Promise<SchemaAddStatusResult>;
+/** Implements run schema remove status for the public runtime surface of this module. */
+export declare function runSchemaRemoveStatus(id: string | undefined, options: SchemaRemoveStatusCommandOptions, global: GlobalOptions): Promise<SchemaRemoveStatusResult>;
+/** Implements run schema list for the public runtime surface of this module. */
+export declare function runSchemaList(global: GlobalOptions): Promise<SchemaListResult>;
+/** Implements run schema show for the public runtime surface of this module. */
+export declare function runSchemaShow(name: string | undefined, global: GlobalOptions): Promise<SchemaShowResult>;
+/** Implements run schema show status for the public runtime surface of this module. */
+export declare function runSchemaShowStatus(id: string | undefined, global: GlobalOptions): Promise<SchemaShowStatusResult>;
+/** Implements run schema add field for the public runtime surface of this module. */
+export declare function runSchemaAddField(key: string | undefined, options: SchemaAddFieldCommandOptions, global: GlobalOptions): Promise<SchemaAddFieldResult>;
+/** Implements run schema remove field for the public runtime surface of this module. */
+export declare function runSchemaRemoveField(key: string | undefined, options: SchemaRemoveFieldCommandOptions, global: GlobalOptions): Promise<SchemaRemoveFieldResult>;
+/** Implements run schema list fields for the public runtime surface of this module. */
+export declare function runSchemaListFields(global: GlobalOptions): Promise<SchemaListFieldsResult>;
+/** Implements run schema show field for the public runtime surface of this module. */
+export declare function runSchemaShowField(key: string | undefined, global: GlobalOptions): Promise<SchemaShowFieldResult>;
+/** Implements run schema apply preset for the public runtime surface of this module. */
+export declare function runSchemaApplyPreset(preset: string | undefined, options: SchemaApplyPresetCommandOptions, global: GlobalOptions): Promise<SchemaApplyPresetResult>;
+/** Implements run schema infer types for the public runtime surface of this module. */
+export declare function runSchemaInferTypes(options: SchemaAddTypeInferCommandOptions, global: GlobalOptions): Promise<SchemaAddTypeInferResult>;
+/** Implements format schema add type human for the public runtime surface of this module. */
+export declare function formatSchemaAddTypeHuman(result: SchemaAddTypeResult): string;
+/** Implements format schema remove type human for the public runtime surface of this module. */
+export declare function formatSchemaRemoveTypeHuman(result: SchemaRemoveTypeResult): string;
+/** Implements format schema add status human for the public runtime surface of this module. */
+export declare function formatSchemaAddStatusHuman(result: SchemaAddStatusResult): string;
+/** Implements format schema remove status human for the public runtime surface of this module. */
+export declare function formatSchemaRemoveStatusHuman(result: SchemaRemoveStatusResult): string;
+/** Implements format schema list human for the public runtime surface of this module. */
+export declare function formatSchemaListHuman(result: SchemaListResult): string;
+/** Implements format schema show human for the public runtime surface of this module. */
+export declare function formatSchemaShowHuman(result: SchemaShowResult): string;
+/** Implements format schema show status human for the public runtime surface of this module. */
+export declare function formatSchemaShowStatusHuman(result: SchemaShowStatusResult): string;
+/** Implements format schema add field human for the public runtime surface of this module. */
+export declare function formatSchemaAddFieldHuman(result: SchemaAddFieldResult): string;
+/** Implements format schema remove field human for the public runtime surface of this module. */
+export declare function formatSchemaRemoveFieldHuman(result: SchemaRemoveFieldResult): string;
+/** Implements format schema list fields human for the public runtime surface of this module. */
+export declare function formatSchemaListFieldsHuman(result: SchemaListFieldsResult): string;
+/** Implements format schema show field human for the public runtime surface of this module. */
+export declare function formatSchemaShowFieldHuman(result: SchemaShowFieldResult): string;
+/** Implements format schema apply preset human for the public runtime surface of this module. */
+export declare function formatSchemaApplyPresetHuman(result: SchemaApplyPresetResult): string;
+/** Implements format schema infer types human for the public runtime surface of this module. */
+export declare function formatSchemaInferTypesHuman(result: SchemaAddTypeInferResult): string;
+/** Re-export so register-mutation can surface the hint in usage examples without importing the core module directly. */
+export { buildInvalidTypeHint };
+/** Public contract for test only schema command, shared by SDK and presentation-layer consumers. */
+export declare const _testOnlySchemaCommand: {
+    toAuthor: typeof toAuthor;
+    workflowSlotsReferencing: typeof workflowSlotsReferencing;
+};