@unbrained/pm-web 2026.7.26 → 2026.7.28

package/dist/services/package-catalog.d.ts

@@ -0,0 +1,84 @@
+/**
+ * The set of capabilities a pm package can declare, mirrored verbatim from
+ * each package's `manifest.json` `capabilities` array. The union is kept
+ * open-ended as a string array (not a closed enum) because the pm extension
+ * contract may add new capability kinds upstream; pinning a closed list here
+ * would reject a future package that uses a capability we have not enumerated.
+ */
+export type PackageCapability = string;
+/**
+ * Honest gating metadata so the UI can tell a user what they must configure
+ * before a package is useful. Both fields are OPTIONAL — most packages work
+ * with no external setup.
+ *
+ * - `requiresService`: a backing service the package talks to (e.g. Neo4j for
+ *   pm-graph's sync). When set, the UI explains that the package's
+ *   service-dependent features will not work until the service is reachable.
+ *   `optional: true` means the package is still useful without the service
+ *   (e.g. pm-graph's offline export/analyze work without Neo4j).
+ *
+ * - `requiresCredentials`: human-supplied secrets the package needs for its
+ *   network-mutating commands (e.g. JIRA_API_TOKEN, LINEAR_API_KEY,
+ *   PM_SLACK_WEBHOOK, GITHUB_TOKEN). Each entry names the env var(s) and a
+ *   short human description. The UI must not pretend these are one-click; it
+ *   surfaces the variables the user must set.
+ */
+export interface ServiceRequirement {
+    /** Display name of the backing service, e.g. "Neo4j". */
+    name: string;
+    /** True when the package is useful without the service (best-effort). */
+    optional?: boolean;
+}
+export interface CredentialRequirement {
+    /** Display label for what the credentials unlock, e.g. "Jira sync". */
+    label: string;
+    /** Environment variable(s) the package reads for the credentials. */
+    envVars: string[];
+    /**
+     * True when the package is partially usable without the credentials (e.g.
+     * `--dry-run` paths, unauthenticated reads). When false, the package is
+     * inert until the credentials are configured.
+     */
+    optional?: boolean;
+}
+export interface PackageCatalogEntry {
+    /** Canonical npm package name, e.g. `pm-graph`. */
+    readonly name: string;
+    /** The install spec passed to `pm install`, always `npm:<name>`. */
+    readonly npmSpec: string;
+    /** Human-friendly title, e.g. `Graph`. */
+    readonly title: string;
+    /** One-line description, mirrored from the package's manifest/package.json. */
+    readonly description: string;
+    /** Capabilities declared in the package manifest. */
+    readonly capabilities: readonly PackageCapability[];
+    /** Backing service the package needs (optional). */
+    readonly requiresService?: ServiceRequirement;
+    /** Credentials the user must configure (optional). */
+    readonly requiresCredentials?: readonly CredentialRequirement[];
+}
+/**
+ * The catalog. Order is the display order in the UI. The list is exhaustive
+ * over user-facing pm packages: every package in the fleet that is not an
+ * authoring template (`pm-starter`/`pm-ts-starter`) and not pm-web itself is
+ * here. `pm-starter`/`pm-ts-starter` are authoring templates, not user-facing
+ * packages; `pm-web` is this package.
+ */
+export declare const PACKAGE_CATALOG: readonly PackageCatalogEntry[];
+/**
+ * Look up a catalog entry by package name. Returns the entry or `undefined`
+ * when the name is not in the catalog. This is the security-critical gate:
+ * route handlers MUST call this and reject with 400 on a miss BEFORE passing
+ * the name to any pm command, so a user-supplied string can never be
+ * interpolated into an install target.
+ */
+export declare function findCatalogEntry(name: string): PackageCatalogEntry | undefined;
+/**
+ * Resolve a package name to its verified npm install spec
+ * (`npm:<name>`), or `null` when the name is not in the catalog. Route
+ * handlers use this to obtain the spawn argument without ever building an
+ * install target from a raw user string.
+ */
+export declare function resolveNpmSpec(name: string): string | null;
+/** The immutable list of catalog package names, in display order. */
+export declare function catalogNames(): readonly string[];

package/dist/services/package-catalog.js

@@ -0,0 +1,194 @@
+// ═══════════════════════════════════════════════════════════════
+// PACKAGE CATALOG — the typed, immutable list of every user-facing pm package
+// ═══════════════════════════════════════════════════════════════
+//
+// pm-web used to ship exactly one pm package — a vendored copy of pm-graph
+// pinned to an old CLI — and offered no way to install any other. This
+// catalog is the single source of truth for the per-project "Packages" view
+// and the extensions routes: every package the UI can install is declared
+// here, and every `:name` route parameter is validated against it BEFORE a
+// pm command is ever spawned. A user-supplied name can never reach an install
+// target — a catalog lookup miss must 400 before any process spawn.
+//
+// Truthfulness contract: the catalog mirrors each package's real
+// `manifest.json` (name, capabilities) and README (gating). Do NOT invent
+// capabilities or hide requirements here — the UI surfaces `requiresService`
+// and `requiresCredentials` so users are not promised a one-click install for
+// a package that needs a Neo4j instance or an API token. The
+// `test/catalog.test.ts` suite asserts that every entry's declared capabilities
+// match the on-disk `manifest.json` under fleet/<pkg>/manifest.json, so a
+// drift between this catalog and the packages is a failing test, not a silent
+// UI lie.
+/**
+ * The catalog. Order is the display order in the UI. The list is exhaustive
+ * over user-facing pm packages: every package in the fleet that is not an
+ * authoring template (`pm-starter`/`pm-ts-starter`) and not pm-web itself is
+ * here. `pm-starter`/`pm-ts-starter` are authoring templates, not user-facing
+ * packages; `pm-web` is this package.
+ */
+export const PACKAGE_CATALOG = [
+    {
+        name: "pm-graph",
+        npmSpec: "npm:pm-graph",
+        title: "Graph",
+        description: "Knowledge graph and dependency graph extension for pm CLI workspaces, with optional Neo4j sync.",
+        capabilities: ["commands", "importers", "services"],
+        requiresService: { name: "Neo4j", optional: true },
+    },
+    {
+        name: "pm-beads",
+        npmSpec: "npm:pm-beads",
+        title: "Beads",
+        description: "Beads JSONL importer/exporter. Import work items from the Beads JSONL format into pm and export pm items back to Beads JSONL, preserving ids and dependency edges.",
+        capabilities: ["commands", "schema", "importers"],
+    },
+    {
+        name: "pm-brief",
+        npmSpec: "npm:pm-brief",
+        title: "Brief",
+        description: "Token-budgeted agent briefs and next-work plans for pm workspaces",
+        capabilities: ["commands", "renderers", "schema"],
+    },
+    {
+        name: "pm-changelog",
+        npmSpec: "npm:pm-changelog",
+        title: "Changelog",
+        description: "Generate CHANGELOG.md release notes from pm-cli items",
+        capabilities: ["commands", "schema", "importers", "renderers"],
+    },
+    {
+        name: "pm-context",
+        npmSpec: "npm:pm-context",
+        title: "Context",
+        description: "Generate deterministic pm context packs for agent handoffs, reviews, and status briefs",
+        capabilities: ["commands", "renderers", "schema"],
+    },
+    {
+        name: "pm-csv",
+        npmSpec: "npm:pm-csv",
+        title: "CSV",
+        description: "CSV importer and exporter for pm-cli",
+        capabilities: ["commands", "importers", "schema"],
+    },
+    {
+        name: "pm-gantt-chart",
+        npmSpec: "npm:pm-gantt-chart",
+        title: "Gantt Chart",
+        description: "ASCII Gantt chart renderer + multi-format exporter for pm-cli",
+        capabilities: ["commands", "schema", "importers", "preflight"],
+    },
+    {
+        name: "pm-github",
+        npmSpec: "npm:pm-github",
+        title: "GitHub",
+        description: "GitHub Issues + Projects v2 integration. Imports issues as pm items (`pm github import`), exports pm items as GitHub issues, syncs issue state, and bidirectionally syncs pm items with a GitHub Projects v2 board (`pm github project import/sync/list/fields`) — mapping pm status to the board Status column with idempotent, no-data-loss provenance.",
+        capabilities: ["commands", "importers", "schema", "hooks", "preflight", "search"],
+        requiresCredentials: [
+            {
+                label: "GitHub token (for private repos, 5000 req/hr, and export/push)",
+                envVars: ["GITHUB_TOKEN", "GH_TOKEN"],
+                optional: true,
+            },
+        ],
+    },
+    {
+        name: "pm-jira",
+        npmSpec: "npm:pm-jira",
+        title: "Jira",
+        description: "Jira issue sync for pm-cli",
+        capabilities: ["commands", "schema", "importers", "hooks", "preflight"],
+        requiresCredentials: [
+            {
+                label: "Jira API credentials (for live sync, import, and export --push)",
+                envVars: ["JIRA_BASE_URL", "JIRA_EMAIL", "JIRA_API_TOKEN"],
+            },
+        ],
+    },
+    {
+        name: "pm-linear",
+        npmSpec: "npm:pm-linear",
+        title: "Linear",
+        description: "Linear.app issue sync for pm-cli",
+        capabilities: ["commands", "schema", "importers", "preflight"],
+        requiresCredentials: [
+            {
+                label: "Linear API key (for live import/export and validate --check-network)",
+                envVars: ["LINEAR_API_KEY"],
+            },
+        ],
+    },
+    {
+        name: "pm-ops",
+        npmSpec: "npm:pm-ops",
+        title: "Ops",
+        description: "Multi-repo fleet operations for pm-cli",
+        capabilities: ["commands", "renderers", "schema", "parser"],
+    },
+    {
+        name: "pm-presets",
+        npmSpec: "npm:pm-presets",
+        title: "Presets",
+        description: "All 7 official pm-cli workspace presets in one package: bug-triage, indie-dev, open-source, software-sprint, startup-roadmap, kanban, agent-workflow",
+        capabilities: ["commands", "schema"],
+    },
+    {
+        name: "pm-slack",
+        npmSpec: "npm:pm-slack",
+        title: "Slack",
+        description: "Slack notifications for pm item lifecycle events",
+        capabilities: ["commands", "hooks", "schema", "preflight"],
+        requiresCredentials: [
+            {
+                label: "Slack webhook (for posting notifications)",
+                envVars: ["PM_SLACK_WEBHOOK"],
+            },
+        ],
+    },
+    {
+        name: "pm-slack-standup",
+        npmSpec: "npm:pm-slack-standup",
+        title: "Slack Standup",
+        description: "Post pm context as a Slack standup message",
+        capabilities: ["commands", "schema", "importers", "preflight", "services"],
+        requiresCredentials: [
+            {
+                label: "Slack webhook (for posting the standup)",
+                envVars: ["PM_SLACK_WEBHOOK"],
+            },
+        ],
+    },
+    {
+        name: "pm-todos",
+        npmSpec: "npm:pm-todos",
+        title: "Todos",
+        description: "TODO round-trip. Import/export/sync markdown checkboxes, todo.txt, jsonl, checkbox, and pi coding-agent todo JSON as pm items.",
+        capabilities: ["commands", "schema", "importers", "preflight"],
+    },
+];
+/** A frozen map keyed by package name for O(1) catalog lookup. */
+const CATALOG_BY_NAME = new Map(PACKAGE_CATALOG.map((entry) => [entry.name, entry]));
+/**
+ * Look up a catalog entry by package name. Returns the entry or `undefined`
+ * when the name is not in the catalog. This is the security-critical gate:
+ * route handlers MUST call this and reject with 400 on a miss BEFORE passing
+ * the name to any pm command, so a user-supplied string can never be
+ * interpolated into an install target.
+ */
+export function findCatalogEntry(name) {
+    return CATALOG_BY_NAME.get(name);
+}
+/**
+ * Resolve a package name to its verified npm install spec
+ * (`npm:<name>`), or `null` when the name is not in the catalog. Route
+ * handlers use this to obtain the spawn argument without ever building an
+ * install target from a raw user string.
+ */
+export function resolveNpmSpec(name) {
+    const entry = CATALOG_BY_NAME.get(name);
+    return entry ? entry.npmSpec : null;
+}
+/** The immutable list of catalog package names, in display order. */
+export function catalogNames() {
+    return PACKAGE_CATALOG.map((entry) => entry.name);
+}
+//# sourceMappingURL=package-catalog.js.map

package/dist/services/package-catalog.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"package-catalog.js","sourceRoot":"","sources":["../../src/services/package-catalog.ts"],"names":[],"mappings":"AAAA,kEAAkE;AAClE,8EAA8E;AAC9E,kEAAkE;AAClE,EAAE;AACF,2EAA2E;AAC3E,uEAAuE;AACvE,4EAA4E;AAC5E,0EAA0E;AAC1E,2EAA2E;AAC3E,8EAA8E;AAC9E,oEAAoE;AACpE,EAAE;AACF,iEAAiE;AACjE,0EAA0E;AAC1E,6EAA6E;AAC7E,8EAA8E;AAC9E,6DAA6D;AAC7D,gFAAgF;AAChF,0EAA0E;AAC1E,8EAA8E;AAC9E,UAAU;AAiEV;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,eAAe,GAAmC;IAC7D;QACE,IAAI,EAAE,UAAU;QAChB,OAAO,EAAE,cAAc;QACvB,KAAK,EAAE,OAAO;QACd,WAAW,EACT,iGAAiG;QACnG,YAAY,EAAE,CAAC,UAAU,EAAE,WAAW,EAAE,UAAU,CAAC;QACnD,eAAe,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE;KACnD;IACD;QACE,IAAI,EAAE,UAAU;QAChB,OAAO,EAAE,cAAc;QACvB,KAAK,EAAE,OAAO;QACd,WAAW,EACT,oKAAoK;QACtK,YAAY,EAAE,CAAC,UAAU,EAAE,QAAQ,EAAE,WAAW,CAAC;KAClD;IACD;QACE,IAAI,EAAE,UAAU;QAChB,OAAO,EAAE,cAAc;QACvB,KAAK,EAAE,OAAO;QACd,WAAW,EACT,mEAAmE;QACrE,YAAY,EAAE,CAAC,UAAU,EAAE,WAAW,EAAE,QAAQ,CAAC;KAClD;IACD;QACE,IAAI,EAAE,cAAc;QACpB,OAAO,EAAE,kBAAkB;QAC3B,KAAK,EAAE,WAAW;QAClB,WAAW,EAAE,uDAAuD;QACpE,YAAY,EAAE,CAAC,UAAU,EAAE,QAAQ,EAAE,WAAW,EAAE,WAAW,CAAC;KAC/D;IACD;QACE,IAAI,EAAE,YAAY;QAClB,OAAO,EAAE,gBAAgB;QACzB,KAAK,EAAE,SAAS;QAChB,WAAW,EACT,wFAAwF;QAC1F,YAAY,EAAE,CAAC,UAAU,EAAE,WAAW,EAAE,QAAQ,CAAC;KAClD;IACD;QACE,IAAI,EAAE,QAAQ;QACd,OAAO,EAAE,YAAY;QACrB,KAAK,EAAE,KAAK;QACZ,WAAW,EAAE,sCAAsC;QACnD,YAAY,EAAE,CAAC,UAAU,EAAE,WAAW,EAAE,QAAQ,CAAC;KAClD;IACD;QACE,IAAI,EAAE,gBAAgB;QACtB,OAAO,EAAE,oBAAoB;QAC7B,KAAK,EAAE,aAAa;QACpB,WAAW,EACT,+DAA+D;QACjE,YAAY,EAAE,CAAC,UAAU,EAAE,QAAQ,EAAE,WAAW,EAAE,WAAW,CAAC;KAC/D;IACD;QACE,IAAI,EAAE,WAAW;QACjB,OAAO,EAAE,eAAe;QACxB,KAAK,EAAE,QAAQ;QACf,WAAW,EACT,2VAA2V;QAC7V,YAAY,EAAE,CAAC,UAAU,EAAE,WAAW,EAAE,QAAQ,EAAE,OAAO,EAAE,WAAW,EAAE,QAAQ,CAAC;QACjF,mBAAmB,EAAE;YACnB;gBACE,KAAK,EAAE,gEAAgE;gBACvE,OAAO,EAAE,CAAC,cAAc,EAAE,UAAU,CAAC;gBACrC,QAAQ,EAAE,IAAI;aACf;SACF;KACF;IACD;QACE,IAAI,EAAE,SAAS;QACf,OAAO,EAAE,aAAa;QACtB,KAAK,EAAE,MAAM;QACb,WAAW,EAAE,4BAA4B;QACzC,YAAY,EAAE,CAAC,UAAU,EAAE,QAAQ,EAAE,WAAW,EAAE,OAAO,EAAE,WAAW,CAAC;QACvE,mBAAmB,EAAE;YACnB;gBACE,KAAK,EAAE,iEAAiE;gBACxE,OAAO,EAAE,CAAC,eAAe,EAAE,YAAY,EAAE,gBAAgB,CAAC;aAC3D;SACF;KACF;IACD;QACE,IAAI,EAAE,WAAW;QACjB,OAAO,EAAE,eAAe;QACxB,KAAK,EAAE,QAAQ;QACf,WAAW,EAAE,kCAAkC;QAC/C,YAAY,EAAE,CAAC,UAAU,EAAE,QAAQ,EAAE,WAAW,EAAE,WAAW,CAAC;QAC9D,mBAAmB,EAAE;YACnB;gBACE,KAAK,EAAE,sEAAsE;gBAC7E,OAAO,EAAE,CAAC,gBAAgB,CAAC;aAC5B;SACF;KACF;IACD;QACE,IAAI,EAAE,QAAQ;QACd,OAAO,EAAE,YAAY;QACrB,KAAK,EAAE,KAAK;QACZ,WAAW,EAAE,wCAAwC;QACrD,YAAY,EAAE,CAAC,UAAU,EAAE,WAAW,EAAE,QAAQ,EAAE,QAAQ,CAAC;KAC5D;IACD;QACE,IAAI,EAAE,YAAY;QAClB,OAAO,EAAE,gBAAgB;QACzB,KAAK,EAAE,SAAS;QAChB,WAAW,EACT,sJAAsJ;QACxJ,YAAY,EAAE,CAAC,UAAU,EAAE,QAAQ,CAAC;KACrC;IACD;QACE,IAAI,EAAE,UAAU;QAChB,OAAO,EAAE,cAAc;QACvB,KAAK,EAAE,OAAO;QACd,WAAW,EAAE,kDAAkD;QAC/D,YAAY,EAAE,CAAC,UAAU,EAAE,OAAO,EAAE,QAAQ,EAAE,WAAW,CAAC;QAC1D,mBAAmB,EAAE;YACnB;gBACE,KAAK,EAAE,2CAA2C;gBAClD,OAAO,EAAE,CAAC,kBAAkB,CAAC;aAC9B;SACF;KACF;IACD;QACE,IAAI,EAAE,kBAAkB;QACxB,OAAO,EAAE,sBAAsB;QAC/B,KAAK,EAAE,eAAe;QACtB,WAAW,EAAE,4CAA4C;QACzD,YAAY,EAAE,CAAC,UAAU,EAAE,QAAQ,EAAE,WAAW,EAAE,WAAW,EAAE,UAAU,CAAC;QAC1E,mBAAmB,EAAE;YACnB;gBACE,KAAK,EAAE,yCAAyC;gBAChD,OAAO,EAAE,CAAC,kBAAkB,CAAC;aAC9B;SACF;KACF;IACD;QACE,IAAI,EAAE,UAAU;QAChB,OAAO,EAAE,cAAc;QACvB,KAAK,EAAE,OAAO;QACd,WAAW,EACT,gIAAgI;QAClI,YAAY,EAAE,CAAC,UAAU,EAAE,QAAQ,EAAE,WAAW,EAAE,WAAW,CAAC;KAC/D;CACF,CAAC;AAEF,kEAAkE;AAClE,MAAM,eAAe,GAA6C,IAAI,GAAG,CACvE,eAAe,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,IAAI,EAAE,KAAK,CAAU,CAAC,CAC7D,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,UAAU,gBAAgB,CAAC,IAAY;IAC3C,OAAO,eAAe,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;AACnC,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,cAAc,CAAC,IAAY;IACzC,MAAM,KAAK,GAAG,eAAe,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IACxC,OAAO,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC;AACtC,CAAC;AAED,qEAAqE;AACrE,MAAM,UAAU,YAAY;IAC1B,OAAO,eAAe,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;AACpD,CAAC"}

package/dist/services/pm-runner.d.ts

@@ -1,5 +1,5 @@
-import { PmCliError, EXIT_CODE, type GetItemAtResult } from "@unbrained/pm-cli/sdk";
-export { PmCliError, EXIT_CODE, type GetItemAtResult };
+import { PmClient, PmCliError, isPmCliExpectedError, EXIT_CODE, type GetItemAtResult } from "@unbrained/pm-cli/sdk";
+export { PmCliError, isPmCliExpectedError, EXIT_CODE, type GetItemAtResult };
 export declare class Semaphore {
     private readonly limit;
     private active;
@@ -40,6 +40,8 @@ export interface PmRunResult {
     stderr: string;
     ok: boolean;
     parsed?: unknown;
+    /** pm CLI exit code from either the SDK dispatcher or spawned CLI fallback. */
+    exitCode?: number;
 }
 export interface EnsureGraphExtensionResult {
     ok: boolean;
@@ -47,7 +49,87 @@ export interface EnsureGraphExtensionResult {
     active: boolean;
     error?: string;
 }
+/**
+ * The per-extension state shape emitted by `pm extension --json`. Only the
+ * fields consumers read are typed; the command emits far more (triage, policy,
+ * diagnostics) which is deliberately dropped.
+ */
+export interface ExtensionState {
+    name: string;
+    version?: string;
+    active?: boolean;
+    enabled?: boolean;
+    runtime_active?: boolean;
+    activation_status?: string;
+    managed?: boolean;
+    source?: {
+        kind?: string;
+        input?: string;
+    };
+}
+/**
+ * Outcome of reading per-project extension state.
+ *
+ * `ok` distinguishes "the command ran and this is the state" from "the command
+ * failed, so we know nothing" — a distinction both previous copies of this
+ * parser collapsed, reporting a failed `pm extension --json` identically to a
+ * project with nothing installed.
+ */
+export interface ExtensionStatesResult {
+    ok: boolean;
+    states: Map<string, ExtensionState>;
+    error?: string;
+}
+/**
+ * Read the per-project extension state from `pm extension --json`, returning a
+ * map keyed by extension name. Used both by {@link ensureGraphExtension} and
+ * the extensions routes' catalog join.
+ */
+export declare function readProjectExtensionStates(projectDir: string): Promise<ExtensionStatesResult>;
+/**
+ * Timeout for package installs, which resolve and download from the npm
+ * registry rather than only touching local state.
+ *
+ * The 30s default is sized for local commands and leaves too thin a margin
+ * here. Measured on this host: a warm-cache install is ~2s, and a cold-cache
+ * install of the heaviest catalog package (pm-graph, which pulls
+ * `neo4j-driver`) is ~10s. That is only a 3x margin on a fast connection,
+ * before accounting for a container sharing bandwidth or a slow registry —
+ * and the failure mode is a project create or package install that dies
+ * mid-download. A hung install still terminates, just later.
+ */
+export declare const INSTALL_COMMAND_TIMEOUT_MS = 180000;
+/**
+ * Ensure the pm-graph package is installed and active for a project.
+ *
+ * This used to install a *vendored* copy of pm-graph from
+ * `extensions/pm-graph/` (a stale fork pinned to pm-cli `^2026.7.5`). The
+ * vendored fork is gone; pm-graph is now installed from npm through the same
+ * generic catalog path as every other pm package
+ * (src/services/package-catalog.ts). The npm spec is resolved from the catalog
+ * — never built from a user-supplied string — so the install target is always
+ * the verified `npm:pm-graph` constant.
+ *
+ * The graph routes in src/routes/pm.ts call this before `pm pm-graph export`,
+ * and {@link initProject} calls it on project creation, so the user-facing
+ * graph behaviour is unchanged.
+ */
 export declare function ensureGraphExtension(userId: string, slug: string): Promise<EnsureGraphExtensionResult>;
+/**
+ * Return a cached {@link PmClient} for a workspace pm-root, creating one on
+ * first use. The SDK owns extension activation and serialization internally;
+ * caching avoids reconstructing the immutable workspace defaults while each
+ * call still receives the SDK's current extension snapshot. Author identity is
+ * resolved by the SDK's default detection, preserving prior CLI behaviour.
+ */
+export declare function getPmClient(pmRoot: string): PmClient;
+/** Drop a cached client when its workspace is deleted. */
+export declare function evictPmClient(pmRoot: string): void;
+/**
+ * Read a workspace's parsed `settings.json` for the search-tuning resolvers.
+ * Returns `{}` when absent so resolvers fall back to their built-in defaults.
+ */
+export declare function readPmSettings(userId: string, slug: string): unknown;
 export declare function runPm(opts: PmRunOptions): Promise<PmRunResult>;
 /**
  * Reconstruct a single item at a one-based version or ISO timestamp using the