@unbrained/pm-cli 2026.6.24 → 2026.7.1

package/dist/core/profile/profile-plan.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"profile-plan.js","sources":["core/profile/profile-plan.ts"],"sourceRoot":"/","sourcesContent":["/**\n * @module core/profile/profile-plan\n *\n * Pure planning for `pm profile apply`. Given a {@link ProjectProfileDefinition}\n * and a snapshot of the current tracker state, computes an idempotent diff across\n * every profile dimension (item types, statuses, fields, per-type workflows,\n * config knobs, templates, and package recommendations) without touching disk.\n *\n * Idempotency is structural: each schema component is upserted onto a clone and\n * the canonical serialization is compared before/after, so re-running `apply`\n * against an already-applied profile reports every entry as `unchanged` and the\n * command performs zero writes. The resulting files/settings the planner returns\n * are exactly what the apply step persists, guaranteeing the dry-run preview and\n * the real mutation never diverge.\n */\nimport {\n  normalizeAddTypeInput,\n  parseItemTypesFile,\n  serializeItemTypesFile,\n  upsertItemType,\n  type ItemTypesFile,\n} from \"../schema/item-types-file.js\";\nimport {\n  normalizeAddStatusInput,\n  parseStatusDefsFile,\n  serializeStatusDefsFile,\n  upsertStatusDef,\n  type StatusDefsFile,\n} from \"../schema/status-defs-file.js\";\nimport {\n  normalizeAddFieldInput,\n  parseFieldsFile,\n  serializeFieldsFile,\n  upsertField,\n  type FieldsFile,\n} from \"../schema/fields-file.js\";\nimport {\n  parseNestedSettingValue,\n  readNestedSettingValue,\n  resolveNestedSettingDescriptor,\n} from \"../config/nested-settings.js\";\nimport type { TypeWorkflowDefinition } from \"../../types.js\";\nimport type {\n  ProfileTemplateOptions,\n  ProjectProfileDefinition,\n} from \"./profile-presets.js\";\n\n/** Per-entry change classification used across every profile dimension. */\nexport type ProfileChangeStatus = \"add\" | \"update\" | \"unchanged\";\n\n/** A single staged change keyed by its component identifier. */\nexport interface ProfileComponentChange {\n  /** Component identity (type name, status id, field key, etc.). */\n  key: string;\n  /** Whether the entry is new, an overwrite, or already current. */\n  status: ProfileChangeStatus;\n}\n\n/** Plan for a file-backed schema component (types/statuses/fields). */\nexport interface ProfileSchemaPlan<TFile> {\n  /** Serialized file content to persist when `changed`. */\n  file: TFile;\n  /** Per-entry classifications in profile order. */\n  changes: ProfileComponentChange[];\n  /** True when at least one entry is add/update. */\n  changed: boolean;\n}\n\n/** A staged per-type workflow change plus the merged result list. */\nexport interface ProfileWorkflowChange {\n  /** Item type the workflow governs. */\n  type: string;\n  /** Whether the workflow is new, changed, or already current. */\n  status: ProfileChangeStatus;\n}\n\n/** Plan for the `schema.type_workflows` settings subtree. */\nexport interface ProfileWorkflowPlan {\n  /** Per-workflow classifications in profile order. */\n  changes: ProfileWorkflowChange[];\n  /** Full merged workflow list to persist when `changed`. */\n  result: TypeWorkflowDefinition[];\n  /** True when at least one workflow is add/update. */\n  changed: boolean;\n}\n\n/** A staged config knob plus the resolved settings path and typed value. */\nexport interface ProfileConfigChange {\n  /** Descriptor key (snake_case). */\n  key: string;\n  /** Dotted PmSettings path the value writes to. */\n  path: string;\n  /** Typed leaf value to persist. */\n  value: string | number | boolean;\n  /** Whether the leaf is new, changed, or already current. */\n  status: ProfileChangeStatus;\n}\n\n/** Plan for the nested-settings knobs a profile stages. */\nexport interface ProfileConfigPlan {\n  /** Per-knob classifications in profile order. */\n  changes: ProfileConfigChange[];\n  /** True when at least one knob is add/update. */\n  changed: boolean;\n}\n\n/** A staged create-template change. */\nexport interface ProfileTemplateChange {\n  /** Template name. */\n  name: string;\n  /** Option payload to persist for the template. */\n  options: ProfileTemplateOptions;\n  /** Whether the template is new, changed, or already current. */\n  status: ProfileChangeStatus;\n}\n\n/** Plan for the create templates a profile stages. */\nexport interface ProfileTemplatePlan {\n  /** Per-template classifications in profile order. */\n  changes: ProfileTemplateChange[];\n  /** True when at least one template is add/update. */\n  changed: boolean;\n}\n\n/** Advisory package recommendation with install status. */\nexport interface ProfilePackagePlan {\n  /** Catalog alias or install spec. */\n  spec: string;\n  /** Why the archetype benefits from the package. */\n  reason: string;\n  /** `installed` when already present, otherwise `recommended`. */\n  status: \"installed\" | \"recommended\";\n}\n\n/** Current tracker state the planner diffs the profile against. */\nexport interface ProfileCurrentState {\n  /** Raw `schema/types.json` content (or null when absent). */\n  typesRaw: string | null;\n  /** Raw status-defs file content (or null when absent). */\n  statusesRaw: string | null;\n  /** Raw fields file content (or null when absent). */\n  fieldsRaw: string | null;\n  /** Current `schema.type_workflows` entries. */\n  workflows: readonly TypeWorkflowDefinition[];\n  /** Settings object used to read current config leaf values. */\n  settings: unknown;\n  /** Existing stored template options keyed by template name. */\n  templates: ReadonlyMap<string, ProfileTemplateOptions>;\n  /** Install specs/aliases already present in the project. */\n  installedPackages: ReadonlySet<string>;\n}\n\n/** Complete idempotent plan for applying a profile. */\nexport interface ProfileApplicationPlan {\n  /** Identifying metadata for the planned profile. */\n  profile: { name: string; title: string; summary: string };\n  /** Item-type plan. */\n  types: ProfileSchemaPlan<ItemTypesFile>;\n  /** Status plan. */\n  statuses: ProfileSchemaPlan<StatusDefsFile>;\n  /** Field plan. */\n  fields: ProfileSchemaPlan<FieldsFile>;\n  /** Per-type workflow plan. */\n  workflows: ProfileWorkflowPlan;\n  /** Config-knob plan. */\n  config: ProfileConfigPlan;\n  /** Template plan. */\n  templates: ProfileTemplatePlan;\n  /** Advisory package recommendations. */\n  packages: ProfilePackagePlan[];\n  /** True when any dimension stages an add/update. */\n  changed: boolean;\n}\n\n/**\n * Plans a file-backed schema component by upserting each normalized input onto a\n * working clone and comparing canonical serializations to classify add/update/\n * unchanged. Shared by the type, status, and field planners.\n */\nfunction planSchemaComponent<TInput, TFile>(\n  initialFile: TFile,\n  inputs: readonly TInput[],\n  keyOf: (input: TInput) => string,\n  serialize: (file: TFile) => string,\n  upsert: (file: TFile, input: TInput) => { file: TFile; replaced: boolean },\n): ProfileSchemaPlan<TFile> {\n  let file = initialFile;\n  const changes: ProfileComponentChange[] = [];\n  for (const input of inputs) {\n    const before = serialize(file);\n    const result = upsert(file, input);\n    const after = serialize(result.file);\n    file = result.file;\n    const status: ProfileChangeStatus = before === after ? \"unchanged\" : result.replaced ? \"update\" : \"add\";\n    changes.push({ key: keyOf(input), status });\n  }\n  return { file, changes, changed: changes.some((change) => change.status !== \"unchanged\") };\n}\n\n/**\n * Canonicalizes an allowed-transition list to an order-independent string. The\n * transitions are a set of `[from, to]` pairs, so a stored list that merely\n * reorders the same pairs must not register as a spurious `update`.\n */\nfunction canonicalTransitions(transitions: readonly [string, string][]): string {\n  return JSON.stringify(transitions.map((pair) => pair.join(\"\u0000\")).sort());\n}\n\n/**\n * Plans the per-type workflow merge. A workflow whose transition set matches the\n * current entry (order-independent) is `unchanged`; a new type is `add`; a\n * changed transition set is `update`. The merged result preserves untouched\n * entries.\n */\nfunction planWorkflows(\n  current: readonly TypeWorkflowDefinition[],\n  desired: readonly TypeWorkflowDefinition[],\n): ProfileWorkflowPlan {\n  const result = current.map((entry) => ({ ...entry }));\n  const changes: ProfileWorkflowChange[] = [];\n  for (const workflow of desired) {\n    const index = result.findIndex((entry) => entry.type === workflow.type);\n    const next: TypeWorkflowDefinition = { type: workflow.type, allowed_transitions: workflow.allowed_transitions };\n    if (index < 0) {\n      result.push(next);\n      changes.push({ type: workflow.type, status: \"add\" });\n    } else if (canonicalTransitions(result[index].allowed_transitions) === canonicalTransitions(workflow.allowed_transitions)) {\n      changes.push({ type: workflow.type, status: \"unchanged\" });\n    } else {\n      result[index] = next;\n      changes.push({ type: workflow.type, status: \"update\" });\n    }\n  }\n  return { changes, result, changed: changes.some((change) => change.status !== \"unchanged\") };\n}\n\n/**\n * Plans config knobs by resolving each descriptor, coercing the value, and\n * comparing it against the current settings leaf. Throws a plain Error for an\n * unknown key or invalid value so the CLI can map it to a USAGE exit code.\n */\nfunction planConfig(profile: ProjectProfileDefinition, settings: unknown): ProfileConfigPlan {\n  const changes: ProfileConfigChange[] = [];\n  for (const entry of profile.config) {\n    const descriptor = resolveNestedSettingDescriptor(entry.key);\n    if (descriptor === undefined) {\n      throw new Error(`Profile \"${profile.name}\" references unknown config key \"${entry.key}\".`);\n    }\n    const parsed = parseNestedSettingValue(descriptor, entry.value);\n    if (!parsed.ok) {\n      throw new Error(`Profile \"${profile.name}\" config ${entry.key}: ${parsed.error.message}`);\n    }\n    // readNestedSettingValue returns `null` (never `undefined`) when the leaf is\n    // absent, so a null current is an unambiguous \"add\".\n    const current = readNestedSettingValue(settings, descriptor);\n    const status: ProfileChangeStatus =\n      current === null ? \"add\" : current === parsed.parsed.value ? \"unchanged\" : \"update\";\n    changes.push({ key: descriptor.key, path: descriptor.path, value: parsed.parsed.value, status });\n  }\n  return { changes, changed: changes.some((change) => change.status !== \"unchanged\") };\n}\n\n/**\n * Canonicalizes a template option payload to a key-order-independent string so a\n * profile's authored option order never produces a spurious `update` against the\n * key-sorted form `pm templates save` persists.\n */\nfunction canonicalTemplateOptions(options: ProfileTemplateOptions): string {\n  const sorted = Object.entries(options).sort(([left], [right]) => left.localeCompare(right));\n  return JSON.stringify(sorted);\n}\n\n/**\n * Plans create templates by comparing each profile template's option payload\n * against the stored template (if any). Equality is canonical so option key\n * ordering never produces a spurious `update`.\n */\nfunction planTemplates(\n  profile: ProjectProfileDefinition,\n  existing: ReadonlyMap<string, ProfileTemplateOptions>,\n): ProfileTemplatePlan {\n  const changes: ProfileTemplateChange[] = [];\n  for (const template of profile.templates) {\n    const current = existing.get(template.name);\n    let status: ProfileChangeStatus;\n    if (current === undefined) {\n      status = \"add\";\n    } else if (canonicalTemplateOptions(current) === canonicalTemplateOptions(template.options)) {\n      status = \"unchanged\";\n    } else {\n      status = \"update\";\n    }\n    changes.push({ name: template.name, options: template.options, status });\n  }\n  return { changes, changed: changes.some((change) => change.status !== \"unchanged\") };\n}\n\n/**\n * Computes the complete idempotent application plan for a profile against the\n * supplied tracker snapshot. The returned files/settings are exactly what the\n * apply step persists; nothing here touches disk.\n */\nexport function planProfileApplication(\n  profile: ProjectProfileDefinition,\n  current: ProfileCurrentState,\n): ProfileApplicationPlan {\n  const types = planSchemaComponent(\n    parseItemTypesFile(current.typesRaw),\n    profile.types,\n    (input) => normalizeAddTypeInput(input).name,\n    serializeItemTypesFile,\n    (file, input) => upsertItemType(file, normalizeAddTypeInput(input)),\n  );\n  const statuses = planSchemaComponent(\n    parseStatusDefsFile(current.statusesRaw),\n    profile.statuses,\n    (input) => normalizeAddStatusInput(input).id,\n    serializeStatusDefsFile,\n    (file, input) => upsertStatusDef(file, normalizeAddStatusInput(input)),\n  );\n  const fields = planSchemaComponent(\n    parseFieldsFile(current.fieldsRaw),\n    profile.fields,\n    (input) => normalizeAddFieldInput(input).key,\n    serializeFieldsFile,\n    (file, input) => upsertField(file, normalizeAddFieldInput(input)),\n  );\n  const workflows = planWorkflows(current.workflows, profile.workflows);\n  const config = planConfig(profile, current.settings);\n  const templates = planTemplates(profile, current.templates);\n  const packages = profile.packages.map((recommendation) => ({\n    spec: recommendation.spec,\n    reason: recommendation.reason,\n    status: current.installedPackages.has(recommendation.spec) ? (\"installed\" as const) : (\"recommended\" as const),\n  }));\n  const changed = types.changed || statuses.changed || fields.changed || workflows.changed || config.changed || templates.changed;\n  return {\n    profile: { name: profile.name, title: profile.title, summary: profile.summary },\n    types,\n    statuses,\n    fields,\n    workflows,\n    config,\n    templates,\n    packages,\n    changed,\n  };\n}\n"],"names":[],"mappings":"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","debugId":"4435194d-79d2-5bb2-ae11-3959340e495b"}

package/dist/core/profile/profile-presets.d.ts

@@ -0,0 +1,218 @@
+/**
+ * @module core/profile/profile-presets
+ *
+ * Defines the project-profile model and the first-party archetype presets that
+ * compose the existing schema, config, template, and package primitives into a
+ * single declarative bundle. A profile is a higher-level customization unit than
+ * a {@link TYPE_PRESET_DEFINITIONS type preset}: where a type preset only stages
+ * item types, a profile stages item types, custom statuses, custom fields,
+ * per-type workflows, configuration knobs, create templates, and recommended
+ * packages so a fresh tracker can be tailored to an archetype (agile delivery,
+ * operations, or research) in one idempotent `pm profile apply` invocation.
+ *
+ * The raw type definitions are shared verbatim with {@link TYPE_PRESET_DEFINITIONS}
+ * so `pm profile apply agile` registers byte-identical item types to
+ * `pm init --type-preset agile` and `pm schema apply-preset agile`. Everything in
+ * this module is pure data plus name normalization; the planning and apply logic
+ * lives in {@link module:core/profile/profile-plan} and `cli/commands/profile`.
+ */
+import type { RawAddTypeInput } from "../schema/item-types-file.js";
+import type { RawAddStatusInput } from "../schema/status-defs-file.js";
+import type { RawAddFieldInput } from "../schema/fields-file.js";
+import type { TypeWorkflowDefinition } from "../../types.js";
+/**
+ * Repeatable create-flag values used to stage a profile template. Mirrors the
+ * stored-template option shape (`Record<flag, string | string[]>`) accepted by
+ * `pm templates save` without importing the CLI module into core.
+ */
+export type ProfileTemplateOptions = Readonly<Record<string, string | readonly string[]>>;
+/**
+ * A single nested-settings knob a profile stages during apply. The `key` is a
+ * {@link module:core/config/nested-settings} descriptor key (snake_case) and the
+ * `value` is the raw string the descriptor parser coerces into a typed leaf, so
+ * profile config reuses exactly the same validation as `pm config set`.
+ */
+export interface ProfileConfigEntry {
+    /** Nested-settings descriptor key, e.g. `search_provider`. */
+    key: string;
+    /** Raw value parsed by the descriptor (e.g. `"bm25"`, `"20"`). */
+    value: string;
+    /** Short human-facing rationale surfaced in profile descriptions. */
+    summary: string;
+}
+/**
+ * A named create template a profile stages into `<pmRoot>/templates/<name>.json`
+ * so operators can immediately `pm create --template <name>`.
+ */
+export interface ProfileTemplateEntry {
+    /** Template name (matches the `pm templates` naming rules). */
+    name: string;
+    /** Create-flag option payload stored for the template. */
+    options: ProfileTemplateOptions;
+}
+/**
+ * A package the profile recommends but never auto-installs. Apply surfaces these
+ * as advisory `pm package install` hints, keeping profile application offline and
+ * side-effect-free with respect to the package registry.
+ */
+export interface ProfilePackageRecommendation {
+    /** Catalog alias or install spec, e.g. `templates` or `npm:@unbrained/pm-templates`. */
+    spec: string;
+    /** Why this archetype benefits from the package. */
+    reason: string;
+}
+/**
+ * The complete declarative definition of a project profile. Every dimension is
+ * optional-by-emptiness: an empty array simply stages nothing for that surface.
+ */
+export interface ProjectProfileDefinition {
+    /** Stable lowercase profile identifier, e.g. `agile`. */
+    name: string;
+    /** Human-facing display title. */
+    title: string;
+    /** One-line description of the archetype the profile tailors the tracker for. */
+    summary: string;
+    /** Item types to upsert (shared with the matching type preset). */
+    types: readonly RawAddTypeInput[];
+    /** Custom statuses to upsert. */
+    statuses: readonly RawAddStatusInput[];
+    /** Custom fields to upsert. */
+    fields: readonly RawAddFieldInput[];
+    /** Per-type workflow transition allow-lists to stage into settings. */
+    workflows: readonly TypeWorkflowDefinition[];
+    /** Nested-settings knobs to stage. */
+    config: readonly ProfileConfigEntry[];
+    /** Create templates to stage. */
+    templates: readonly ProfileTemplateEntry[];
+    /** Advisory package recommendations (never auto-installed). */
+    packages: readonly ProfilePackageRecommendation[];
+}
+/**
+ * The shape an extension passes to `api.registerProfile(profile)`.
+ *
+ * Only `name` and `title` are required; every other dimension is optional and
+ * defaults to an empty array (and `summary` to an empty string) during
+ * registration, matching the "optional-by-emptiness" model of
+ * {@link ProjectProfileDefinition}. The loader normalizes a registration input
+ * into a full {@link ProjectProfileDefinition} before storing it, so a sparse
+ * `{ name, title }` archetype is a first-class, fully-typed call — no casts —
+ * while a complete definition (a built-in or `defineProjectProfile`-typed value)
+ * also satisfies it.
+ */
+export type ProjectProfileRegistrationInput = Pick<ProjectProfileDefinition, "name" | "title"> & Partial<Omit<ProjectProfileDefinition, "name" | "title">>;
+/**
+ * Ordered list of first-party profile names. Drives CLI help, completion,
+ * contracts, and the `pm profile list` ordering.
+ */
+export declare const PROFILE_NAMES: readonly ["agile", "ops", "research"];
+/**
+ * Restricts profile name values accepted by command, SDK, and storage contracts.
+ */
+export type ProfileName = (typeof PROFILE_NAMES)[number];
+/**
+ * First-party archetype profiles. Each composes its matching
+ * {@link TYPE_PRESET_DEFINITIONS} entry (so item types stay identical to the
+ * standalone type preset) with archetype-appropriate statuses, fields, a primary
+ * workflow, offline-friendly search config, a starter template, and package
+ * recommendations.
+ */
+export declare const BUILTIN_PROFILES: Record<ProfileName, ProjectProfileDefinition>;
+/**
+ * Validates and normalizes a raw profile-name value. Returns `undefined` when the
+ * value is omitted. Throws a plain Error with a stable message for an empty or
+ * unknown name; CLI layers map it to a USAGE exit code. Accepts hyphen/underscore
+ * and casing variations for ergonomics, mirroring {@link normalizeTypePresetName}.
+ */
+export declare function normalizeProfileName(rawValue: string | undefined): ProfileName | undefined;
+/**
+ * Resolves a built-in profile definition by validated name. Throws (via
+ * {@link normalizeProfileName}) when the name is missing or unknown.
+ */
+export declare function resolveProfile(rawValue: string | undefined): ProjectProfileDefinition;
+/**
+ * Returns all built-in profile definitions in {@link PROFILE_NAMES} order. Used by
+ * `pm profile list` and SDK consumers enumerating available archetypes.
+ */
+export declare function listProfiles(): ProjectProfileDefinition[];
+/**
+ * Whether a resolved profile is core-baked or contributed by an active extension.
+ */
+export type ProfileSourceKind = "builtin" | "extension";
+/**
+ * A profile definition paired with where it came from, returned by the merged
+ * `pm profile` resolution so callers can label a profile's origin.
+ */
+export interface ResolvedProfile {
+    /** The profile definition. */
+    definition: ProjectProfileDefinition;
+    /** Whether the profile is core-baked or contributed by an active extension. */
+    source: ProfileSourceKind;
+    /** For an extension profile, the owning package/extension name; absent for builtins. */
+    package?: string;
+}
+/**
+ * A profile contributed by an active extension, fed into the merge resolver.
+ *
+ * This intentionally mirrors the loader's `RegisteredExtensionProjectProfile`
+ * without importing `core/extensions` — `extension-types` depends on this module
+ * for {@link ProjectProfileDefinition}, so importing back would form a cycle. The
+ * CLI maps the active registration registry onto this shape.
+ */
+export interface ExtensionProfileContribution {
+    /** Owning extension/package name, surfaced as the resolved profile's source. */
+    name: string;
+    /** The profile definition the extension registered. */
+    profile: ProjectProfileDefinition;
+}
+/**
+ * Result of {@link resolveProfileCatalog}: the merged profile list plus any
+ * non-fatal collisions encountered while merging.
+ */
+export interface ResolveProfileCatalogResult {
+    /** Builtins first (in {@link PROFILE_NAMES} order), then accepted extension profiles in contribution order. */
+    profiles: ResolvedProfile[];
+    /** Non-fatal merge warnings (built-in shadowing attempts, duplicate names). */
+    warnings: string[];
+}
+/**
+ * Result of {@link resolveProfileEntry}: the single resolved profile plus the
+ * same non-fatal merge `warnings` {@link resolveProfileCatalog} produced, so
+ * `pm profile show`/`apply` surface a shadowed or duplicate extension profile
+ * just like `pm profile list` does rather than swallowing it.
+ */
+export interface ResolveProfileEntryResult {
+    /** The resolved profile and its source. */
+    resolved: ResolvedProfile;
+    /** Non-fatal merge warnings from building the catalog the entry was resolved against. */
+    warnings: string[];
+}
+/**
+ * Canonical lookup key for a profile name: trimmed, lowercased, with hyphens
+ * folded to underscores. Shared by both sides of every catalog match (and by
+ * {@link normalizeProfileName}) so a user can type `my-flow`, `My-Flow`, or
+ * `my_flow ` interchangeably. Interior spaces are preserved — only the
+ * hyphen/underscore distinction and surrounding whitespace/casing are folded.
+ */
+export declare function normalizeProfileLookupKey(rawValue: string): string;
+/**
+ * Merges the core-baked {@link BUILTIN_PROFILES} with profiles contributed by
+ * active extensions into one resolvable catalog.
+ *
+ * Built-in names are reserved: an extension profile whose normalized name
+ * collides with a built-in archetype is dropped with a warning, so a package can
+ * never silently shadow a core profile. Two extension profiles that normalize to
+ * the same key keep the first contribution and warn on each later duplicate.
+ * Builtins always sort first, preserving the established `pm profile list`
+ * ordering. Names are non-blank by construction — the loader's
+ * `registerProfile` validation rejects an empty `name` before it can reach the
+ * registry that feeds this resolver.
+ */
+export declare function resolveProfileCatalog(contributions?: readonly ExtensionProfileContribution[]): ResolveProfileCatalogResult;
+/**
+ * Resolves a single profile by name from the merged catalog (builtins +
+ * extension contributions), returning it alongside the catalog's merge warnings.
+ * Throws a plain Error with a stable, name-listing message when the value is
+ * missing or unknown, so CLI layers map it to a USAGE exit code — the
+ * extension-aware counterpart to {@link resolveProfile}.
+ */
+export declare function resolveProfileEntry(rawValue: string | undefined, contributions?: readonly ExtensionProfileContribution[]): ResolveProfileEntryResult;

package/dist/core/profile/profile-presets.js

@@ -0,0 +1,325 @@
+
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="6353f7f8-4aed-512c-8f04-a61eef52a775")}catch(e){}}();
+import { TYPE_PRESET_DEFINITIONS } from "../schema/type-presets.js";
+/**
+ * Ordered list of first-party profile names. Drives CLI help, completion,
+ * contracts, and the `pm profile list` ordering.
+ */
+export const PROFILE_NAMES = ["agile", "ops", "research"];
+/**
+ * First-party archetype profiles. Each composes its matching
+ * {@link TYPE_PRESET_DEFINITIONS} entry (so item types stay identical to the
+ * standalone type preset) with archetype-appropriate statuses, fields, a primary
+ * workflow, offline-friendly search config, a starter template, and package
+ * recommendations.
+ */
+export const BUILTIN_PROFILES = {
+    agile: {
+        name: "agile",
+        title: "Agile delivery",
+        summary: "Story/Spike delivery with a review stage, story points, and acceptance ownership.",
+        types: TYPE_PRESET_DEFINITIONS.agile,
+        statuses: [
+            {
+                id: "review",
+                roles: ["active"],
+                aliases: ["in-review"],
+                description: "Work is implementation-complete and awaiting peer review.",
+            },
+        ],
+        fields: [
+            {
+                key: "story_points",
+                type: "number",
+                commands: ["create", "update", "list"],
+                description: "Relative estimation size for a story or spike.",
+                aliases: ["points"],
+            },
+            {
+                key: "acceptance_owner",
+                type: "string",
+                commands: ["create", "update", "list"],
+                description: "Stakeholder accountable for accepting the delivered story.",
+                aliases: ["acceptor"],
+            },
+        ],
+        workflows: [
+            {
+                type: "Story",
+                allowed_transitions: [
+                    ["open", "in_progress"],
+                    ["in_progress", "review"],
+                    ["review", "in_progress"],
+                    ["review", "closed"],
+                    ["in_progress", "blocked"],
+                    ["blocked", "in_progress"],
+                ],
+            },
+        ],
+        config: [
+            { key: "search_provider", value: "bm25", summary: "Offline BM25 lexical search works without an embedding service." },
+            { key: "search_max_results", value: "20", summary: "Sprint-sized result cap for quick triage." },
+        ],
+        templates: [
+            {
+                name: "story",
+                options: {
+                    type: "Story",
+                    priority: "2",
+                    tags: "story",
+                    acceptanceCriteria: "Story delivers the stated user outcome with tests and docs updated.",
+                    body: "## As a\n\n## I want\n\n## So that\n\n## Acceptance\n- [ ] \n",
+                },
+            },
+        ],
+        packages: [
+            { spec: "templates", reason: "Reusable create templates for recurring story shapes." },
+            { spec: "calendar", reason: "Sprint and iteration scheduling views." },
+            { spec: "search-advanced", reason: "Richer retrieval as the backlog grows." },
+        ],
+    },
+    ops: {
+        name: "ops",
+        title: "Operations",
+        summary: "Incident/Runbook response with mitigation and monitoring stages, severity, and service fields.",
+        types: TYPE_PRESET_DEFINITIONS.ops,
+        statuses: [
+            {
+                id: "mitigating",
+                roles: ["active"],
+                aliases: ["mitigation"],
+                description: "Active mitigation is underway to restore service.",
+            },
+            {
+                id: "monitoring",
+                roles: ["active"],
+                aliases: ["observing"],
+                description: "Mitigation applied; monitoring for recurrence before closure.",
+            },
+        ],
+        fields: [
+            {
+                key: "severity",
+                type: "string",
+                commands: ["create", "update", "list"],
+                description: "Incident severity classification (e.g. sev1, sev2, sev3).",
+                aliases: ["sev"],
+            },
+            {
+                key: "service",
+                type: "string",
+                commands: ["create", "update", "list"],
+                description: "Primary affected service or component.",
+            },
+        ],
+        workflows: [
+            {
+                type: "Incident",
+                allowed_transitions: [
+                    ["open", "mitigating"],
+                    ["mitigating", "monitoring"],
+                    ["monitoring", "mitigating"],
+                    ["monitoring", "closed"],
+                    ["mitigating", "blocked"],
+                    ["blocked", "mitigating"],
+                ],
+            },
+        ],
+        config: [
+            { key: "search_provider", value: "bm25", summary: "Offline BM25 lexical search for fast incident lookup." },
+            { key: "search_max_results", value: "25", summary: "Wider result cap to surface related incidents and runbooks." },
+        ],
+        templates: [
+            {
+                name: "incident",
+                options: {
+                    type: "Incident",
+                    priority: "1",
+                    tags: "incident",
+                    acceptanceCriteria: "Service restored, root cause documented, and follow-ups filed.",
+                    body: "## Impact\n\n## Timeline\n\n## Root cause\n\n## Mitigation\n\n## Follow-ups\n",
+                },
+            },
+        ],
+        packages: [
+            { spec: "lifecycle-hooks", reason: "Automate transitions and notifications on incident state changes." },
+            { spec: "governance-audit", reason: "Audit incident metadata completeness and closure quality." },
+            { spec: "calendar", reason: "On-call and follow-up scheduling." },
+        ],
+    },
+    research: {
+        name: "research",
+        title: "Research",
+        summary: "Experiment/Hypothesis investigation with an analysis stage, hypothesis, and method fields.",
+        types: TYPE_PRESET_DEFINITIONS.research,
+        statuses: [
+            {
+                id: "analyzing",
+                roles: ["active"],
+                aliases: ["analysis"],
+                description: "Data collected; analysis and synthesis in progress.",
+            },
+        ],
+        fields: [
+            {
+                key: "hypothesis",
+                type: "string",
+                commands: ["create", "update"],
+                description: "The testable claim the experiment evaluates.",
+            },
+            {
+                key: "method",
+                type: "string",
+                commands: ["create", "update", "list"],
+                description: "Experimental method or protocol used to evaluate the hypothesis.",
+                aliases: ["protocol"],
+            },
+        ],
+        workflows: [
+            {
+                type: "Experiment",
+                allowed_transitions: [
+                    ["open", "in_progress"],
+                    ["in_progress", "analyzing"],
+                    ["analyzing", "in_progress"],
+                    ["analyzing", "closed"],
+                    ["in_progress", "blocked"],
+                    ["blocked", "in_progress"],
+                ],
+            },
+        ],
+        config: [
+            { key: "search_provider", value: "bm25", summary: "Offline BM25 lexical search across the research corpus." },
+            { key: "search_max_results", value: "50", summary: "Broader recall cap for literature and prior-experiment discovery." },
+        ],
+        templates: [
+            {
+                name: "experiment",
+                options: {
+                    type: "Experiment",
+                    priority: "2",
+                    tags: "experiment",
+                    acceptanceCriteria: "Hypothesis is supported, rejected, or refined with recorded evidence.",
+                    body: "## Hypothesis\n\n## Method\n\n## Results\n\n## Conclusion\n",
+                },
+            },
+        ],
+        packages: [
+            { spec: "search-advanced", reason: "Semantic retrieval over experiments and findings." },
+            { spec: "templates", reason: "Consistent experiment and hypothesis scaffolds." },
+            { spec: "beads", reason: "Import structured prior work into the tracker." },
+        ],
+    },
+};
+/**
+ * Validates and normalizes a raw profile-name value. Returns `undefined` when the
+ * value is omitted. Throws a plain Error with a stable message for an empty or
+ * unknown name; CLI layers map it to a USAGE exit code. Accepts hyphen/underscore
+ * and casing variations for ergonomics, mirroring {@link normalizeTypePresetName}.
+ */
+export function normalizeProfileName(rawValue) {
+    if (rawValue === undefined) {
+        return undefined;
+    }
+    const normalized = normalizeProfileLookupKey(rawValue);
+    if (normalized.length === 0) {
+        throw new Error("Profile name must not be empty.");
+    }
+    // Validate against PROFILE_NAMES so adding a profile never drifts from the
+    // accepted set (single source of truth shared with BUILTIN_PROFILES).
+    if (PROFILE_NAMES.includes(normalized)) {
+        return normalized;
+    }
+    throw new Error(`Invalid profile "${rawValue}". Allowed: ${PROFILE_NAMES.join(", ")}.`);
+}
+/**
+ * Resolves a built-in profile definition by validated name. Throws (via
+ * {@link normalizeProfileName}) when the name is missing or unknown.
+ */
+export function resolveProfile(rawValue) {
+    const name = normalizeProfileName(rawValue);
+    if (name === undefined) {
+        throw new Error(`Profile name is required. Allowed: ${PROFILE_NAMES.join(", ")}.`);
+    }
+    return BUILTIN_PROFILES[name];
+}
+/**
+ * Returns all built-in profile definitions in {@link PROFILE_NAMES} order. Used by
+ * `pm profile list` and SDK consumers enumerating available archetypes.
+ */
+export function listProfiles() {
+    return PROFILE_NAMES.map((name) => BUILTIN_PROFILES[name]);
+}
+/**
+ * Canonical lookup key for a profile name: trimmed, lowercased, with hyphens
+ * folded to underscores. Shared by both sides of every catalog match (and by
+ * {@link normalizeProfileName}) so a user can type `my-flow`, `My-Flow`, or
+ * `my_flow ` interchangeably. Interior spaces are preserved — only the
+ * hyphen/underscore distinction and surrounding whitespace/casing are folded.
+ */
+export function normalizeProfileLookupKey(rawValue) {
+    return rawValue.trim().toLowerCase().replaceAll("-", "_");
+}
+function formatAvailableProfileNames(profiles) {
+    return profiles.map((entry) => entry.definition.name).join(", ");
+}
+/**
+ * Merges the core-baked {@link BUILTIN_PROFILES} with profiles contributed by
+ * active extensions into one resolvable catalog.
+ *
+ * Built-in names are reserved: an extension profile whose normalized name
+ * collides with a built-in archetype is dropped with a warning, so a package can
+ * never silently shadow a core profile. Two extension profiles that normalize to
+ * the same key keep the first contribution and warn on each later duplicate.
+ * Builtins always sort first, preserving the established `pm profile list`
+ * ordering. Names are non-blank by construction — the loader's
+ * `registerProfile` validation rejects an empty `name` before it can reach the
+ * registry that feeds this resolver.
+ */
+export function resolveProfileCatalog(contributions = []) {
+    const profiles = PROFILE_NAMES.map((name) => ({
+        definition: BUILTIN_PROFILES[name],
+        source: "builtin",
+    }));
+    const builtinKeys = new Set(PROFILE_NAMES.map((name) => normalizeProfileLookupKey(name)));
+    const seen = new Set(builtinKeys);
+    const warnings = [];
+    for (const contribution of contributions) {
+        const key = normalizeProfileLookupKey(contribution.profile.name);
+        if (builtinKeys.has(key)) {
+            warnings.push(`Extension "${contribution.name}" profile "${contribution.profile.name}" uses a name reserved by a built-in archetype and was ignored.`);
+            continue;
+        }
+        if (seen.has(key)) {
+            warnings.push(`Profile "${contribution.profile.name}" from extension "${contribution.name}" duplicates an already-registered profile and was ignored.`);
+            continue;
+        }
+        seen.add(key);
+        profiles.push({ definition: contribution.profile, source: "extension", package: contribution.name });
+    }
+    return { profiles, warnings };
+}
+/**
+ * Resolves a single profile by name from the merged catalog (builtins +
+ * extension contributions), returning it alongside the catalog's merge warnings.
+ * Throws a plain Error with a stable, name-listing message when the value is
+ * missing or unknown, so CLI layers map it to a USAGE exit code — the
+ * extension-aware counterpart to {@link resolveProfile}.
+ */
+export function resolveProfileEntry(rawValue, contributions = []) {
+    const { profiles, warnings } = resolveProfileCatalog(contributions);
+    // Treat any non-string name as missing — undefined, null, or a non-string
+    // primitive slipping in from an untyped JS caller or parsed payload — so the
+    // `.trim()` below never throws.
+    if (typeof rawValue !== "string" || rawValue.trim().length === 0) {
+        throw new Error(`Profile name is required. Allowed: ${formatAvailableProfileNames(profiles)}.`);
+    }
+    const key = normalizeProfileLookupKey(rawValue);
+    const match = profiles.find((entry) => normalizeProfileLookupKey(entry.definition.name) === key);
+    if (match === undefined) {
+        throw new Error(`Invalid profile "${rawValue}". Allowed: ${formatAvailableProfileNames(profiles)}.`);
+    }
+    return { resolved: match, warnings };
+}
+//# sourceMappingURL=profile-presets.js.map
+//# debugId=6353f7f8-4aed-512c-8f04-a61eef52a775