@unbrained/pm-cli 2026.7.14 → 2026.7.15

package/dist/sdk/extension/shared.js

@@ -0,0 +1,140 @@
+/**
+ * @module sdk/extension/shared
+ *
+ * Implements extension package-management support for Shared.
+ */
+
+!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]="79cbf5a9-d060-546d-aa23-79e4b16fa6dc")}catch(e){}}();
+import fs from "node:fs/promises";
+import path from "node:path";
+import { pathExists } from "../../core/fs/fs-utils.js";
+import { isPathWithinDirectory } from "../../core/fs/path-utils.js";
+import { EXIT_CODE } from "../../core/shared/constants.js";
+import { PmCliError } from "../../core/shared/errors.js";
+import { DEFAULT_EXTENSION_PRIORITY, isCanonicalPathWithinDirectory, } from "../../core/extensions/loader.js";
+export { DEFAULT_EXTENSION_PRIORITY, isCanonicalPathWithinDirectory };
+/** Implements normalize string list for the public runtime surface of this module. */
+export function normalizeStringList(values) {
+    return [
+        ...new Set(values.map((value) => value.trim()).filter((value) => value.length > 0)),
+    ].sort((left, right) => left.localeCompare(right));
+}
+/** Implements normalize extension name for match for the public runtime surface of this module. */
+export function normalizeExtensionNameForMatch(value) {
+    return value.trim().toLowerCase();
+}
+/** Implements normalize managed directory name for the public runtime surface of this module. */
+export function normalizeManagedDirectoryName(name) {
+    const normalized = name
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9._-]+/g, "-");
+    let start = 0;
+    while (normalized[start] === "-") {
+        start += 1;
+    }
+    let end = normalized.length;
+    while (end > start && normalized[end - 1] === "-") {
+        end -= 1;
+    }
+    const directoryName = normalized.slice(start, end);
+    if (directoryName.length === 0) {
+        throw new PmCliError("Extension manifest name must resolve to a non-empty directory name.", EXIT_CODE.USAGE);
+    }
+    if (directoryName === "." || directoryName === "..") {
+        // Manifest-controlled input must resolve to a dedicated child directory, never
+        // the extensions root itself or its parent (path-traversal guard).
+        throw new PmCliError('Extension manifest name must not resolve to "." or "..".', EXIT_CODE.USAGE);
+    }
+    return directoryName;
+}
+function parseOptionalManifestPriority(value) {
+    if (value === undefined || value === null) {
+        return DEFAULT_EXTENSION_PRIORITY;
+    }
+    return typeof value === "number" && Number.isInteger(value) ? value : null;
+}
+function parseOptionalManifestCapabilities(value) {
+    if (value === undefined || value === null) {
+        return [];
+    }
+    if (!Array.isArray(value) ||
+        value.some((entry) => typeof entry !== "string")) {
+        return null;
+    }
+    return normalizeStringList(value.map((entry) => String(entry).toLowerCase()));
+}
+/** Implements parse extension manifest for the public runtime surface of this module. */
+export function parseExtensionManifest(raw) {
+    if (typeof raw !== "object" || raw === null) {
+        return null;
+    }
+    const candidate = raw;
+    if (typeof candidate.name !== "string" ||
+        candidate.name.trim().length === 0) {
+        return null;
+    }
+    if (typeof candidate.version !== "string" ||
+        candidate.version.trim().length === 0) {
+        return null;
+    }
+    if (typeof candidate.entry !== "string" ||
+        candidate.entry.trim().length === 0) {
+        return null;
+    }
+    const priority = parseOptionalManifestPriority(candidate.priority);
+    const capabilities = parseOptionalManifestCapabilities(candidate.capabilities);
+    if (priority === null || capabilities === null) {
+        return null;
+    }
+    return {
+        name: candidate.name.trim(),
+        version: candidate.version.trim(),
+        entry: candidate.entry.trim(),
+        priority,
+        capabilities,
+    };
+}
+/** Implements validate extension directory for the public runtime surface of this module. */
+export async function validateExtensionDirectory(directory) {
+    const manifestPath = path.join(directory, "manifest.json");
+    if (!(await pathExists(manifestPath))) {
+        throw new PmCliError(`Extension manifest is missing at "${manifestPath}".`, EXIT_CODE.USAGE);
+    }
+    let parsedManifest;
+    try {
+        parsedManifest = JSON.parse(await fs.readFile(manifestPath, "utf8"));
+    }
+    catch (error) {
+        throw new PmCliError(`Failed to parse extension manifest at "${manifestPath}": ${formatManifestReadError(error)}`, EXIT_CODE.USAGE);
+    }
+    const manifest = parseExtensionManifest(parsedManifest);
+    if (!manifest) {
+        throw new PmCliError(`Extension manifest at "${manifestPath}" is invalid.`, EXIT_CODE.USAGE);
+    }
+    const entryPath = path.resolve(directory, manifest.entry);
+    if (!isPathWithinDirectory(directory, entryPath)) {
+        throw new PmCliError(`Extension entry "${manifest.entry}" resolves outside extension directory "${directory}".`, EXIT_CODE.USAGE);
+    }
+    if (!(await pathExists(entryPath))) {
+        throw new PmCliError(`Extension entry file is missing at "${entryPath}".`, EXIT_CODE.USAGE);
+    }
+    if (!(await isCanonicalPathWithinDirectory(directory, entryPath))) {
+        throw new PmCliError(`Extension entry "${manifest.entry}" resolves outside extension directory after symlink resolution.`, EXIT_CODE.USAGE);
+    }
+    return {
+        directory,
+        manifest_path: manifestPath,
+        entry_path: entryPath,
+        manifest,
+    };
+}
+function formatManifestReadError(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+/** Public contract for test only extension shared, shared by SDK and presentation-layer consumers. */
+export const _testOnlyExtensionShared = {
+    formatManifestReadError,
+};
+//# sourceMappingURL=shared.js.map
+//# debugId=79cbf5a9-d060-546d-aa23-79e4b16fa6dc

package/dist/sdk/extension/shared.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shared.js","sources":["sdk/extension/shared.ts"],"sourceRoot":"/","sourcesContent":["/**\n * @module sdk/extension/shared\n *\n * Implements extension package-management support for Shared.\n */\nimport fs from \"node:fs/promises\";\nimport path from \"node:path\";\nimport { pathExists } from \"../../core/fs/fs-utils.js\";\nimport { isPathWithinDirectory } from \"../../core/fs/path-utils.js\";\nimport { EXIT_CODE } from \"../../core/shared/constants.js\";\nimport { PmCliError } from \"../../core/shared/errors.js\";\nimport {\n  DEFAULT_EXTENSION_PRIORITY,\n  isCanonicalPathWithinDirectory,\n  type ExtensionManifest,\n} from \"../../core/extensions/loader.js\";\n\nexport { DEFAULT_EXTENSION_PRIORITY, isCanonicalPathWithinDirectory };\n\n/** Documents the validated extension directory payload exchanged by command, SDK, and package integrations. */\nexport interface ValidatedExtensionDirectory {\n  /** Value that configures or reports directory for this contract. */\n  directory: string;\n  /** Filesystem path used for manifest resolution. */\n  manifest_path: string;\n  /** Filesystem path used for entry resolution. */\n  entry_path: string;\n  /** Declarative package manifest consumed by the extension loader. */\n  manifest: ExtensionManifest;\n}\n\n/** Implements normalize string list for the public runtime surface of this module. */\nexport function normalizeStringList(values: readonly string[]): string[] {\n  return [\n    ...new Set(\n      values.map((value) => value.trim()).filter((value) => value.length > 0),\n    ),\n  ].sort((left, right) => left.localeCompare(right));\n}\n\n/** Implements normalize extension name for match for the public runtime surface of this module. */\nexport function normalizeExtensionNameForMatch(value: string): string {\n  return value.trim().toLowerCase();\n}\n\n/** Implements normalize managed directory name for the public runtime surface of this module. */\nexport function normalizeManagedDirectoryName(name: string): string {\n  const normalized = name\n    .trim()\n    .toLowerCase()\n    .replace(/[^a-z0-9._-]+/g, \"-\");\n  let start = 0;\n  while (normalized[start] === \"-\") {\n    start += 1;\n  }\n  let end = normalized.length;\n  while (end > start && normalized[end - 1] === \"-\") {\n    end -= 1;\n  }\n  const directoryName = normalized.slice(start, end);\n  if (directoryName.length === 0) {\n    throw new PmCliError(\n      \"Extension manifest name must resolve to a non-empty directory name.\",\n      EXIT_CODE.USAGE,\n    );\n  }\n  if (directoryName === \".\" || directoryName === \"..\") {\n    // Manifest-controlled input must resolve to a dedicated child directory, never\n    // the extensions root itself or its parent (path-traversal guard).\n    throw new PmCliError(\n      'Extension manifest name must not resolve to \".\" or \"..\".',\n      EXIT_CODE.USAGE,\n    );\n  }\n  return directoryName;\n}\n\nfunction parseOptionalManifestPriority(value: unknown): number | null {\n  if (value === undefined || value === null) {\n    return DEFAULT_EXTENSION_PRIORITY;\n  }\n  return typeof value === \"number\" && Number.isInteger(value) ? value : null;\n}\n\nfunction parseOptionalManifestCapabilities(value: unknown): string[] | null {\n  if (value === undefined || value === null) {\n    return [];\n  }\n  if (\n    !Array.isArray(value) ||\n    value.some((entry) => typeof entry !== \"string\")\n  ) {\n    return null;\n  }\n  return normalizeStringList(value.map((entry) => String(entry).toLowerCase()));\n}\n\n/** Implements parse extension manifest for the public runtime surface of this module. */\nexport function parseExtensionManifest(raw: unknown): ExtensionManifest | null {\n  if (typeof raw !== \"object\" || raw === null) {\n    return null;\n  }\n  const candidate = raw as Record<string, unknown>;\n  if (\n    typeof candidate.name !== \"string\" ||\n    candidate.name.trim().length === 0\n  ) {\n    return null;\n  }\n  if (\n    typeof candidate.version !== \"string\" ||\n    candidate.version.trim().length === 0\n  ) {\n    return null;\n  }\n  if (\n    typeof candidate.entry !== \"string\" ||\n    candidate.entry.trim().length === 0\n  ) {\n    return null;\n  }\n\n  const priority = parseOptionalManifestPriority(candidate.priority);\n  const capabilities = parseOptionalManifestCapabilities(\n    candidate.capabilities,\n  );\n  if (priority === null || capabilities === null) {\n    return null;\n  }\n\n  return {\n    name: candidate.name.trim(),\n    version: candidate.version.trim(),\n    entry: candidate.entry.trim(),\n    priority,\n    capabilities,\n  };\n}\n\n/** Implements validate extension directory for the public runtime surface of this module. */\nexport async function validateExtensionDirectory(\n  directory: string,\n): Promise<ValidatedExtensionDirectory> {\n  const manifestPath = path.join(directory, \"manifest.json\");\n  if (!(await pathExists(manifestPath))) {\n    throw new PmCliError(\n      `Extension manifest is missing at \"${manifestPath}\".`,\n      EXIT_CODE.USAGE,\n    );\n  }\n\n  let parsedManifest: unknown;\n  try {\n    parsedManifest = JSON.parse(\n      await fs.readFile(manifestPath, \"utf8\"),\n    ) as unknown;\n  } catch (error: unknown) {\n    throw new PmCliError(\n      `Failed to parse extension manifest at \"${manifestPath}\": ${formatManifestReadError(error)}`,\n      EXIT_CODE.USAGE,\n    );\n  }\n\n  const manifest = parseExtensionManifest(parsedManifest);\n  if (!manifest) {\n    throw new PmCliError(\n      `Extension manifest at \"${manifestPath}\" is invalid.`,\n      EXIT_CODE.USAGE,\n    );\n  }\n\n  const entryPath = path.resolve(directory, manifest.entry);\n  if (!isPathWithinDirectory(directory, entryPath)) {\n    throw new PmCliError(\n      `Extension entry \"${manifest.entry}\" resolves outside extension directory \"${directory}\".`,\n      EXIT_CODE.USAGE,\n    );\n  }\n  if (!(await pathExists(entryPath))) {\n    throw new PmCliError(\n      `Extension entry file is missing at \"${entryPath}\".`,\n      EXIT_CODE.USAGE,\n    );\n  }\n  if (!(await isCanonicalPathWithinDirectory(directory, entryPath))) {\n    throw new PmCliError(\n      `Extension entry \"${manifest.entry}\" resolves outside extension directory after symlink resolution.`,\n      EXIT_CODE.USAGE,\n    );\n  }\n\n  return {\n    directory,\n    manifest_path: manifestPath,\n    entry_path: entryPath,\n    manifest,\n  };\n}\n\nfunction formatManifestReadError(error: unknown): string {\n  return error instanceof Error ? error.message : String(error);\n}\n\n/** Public contract for test only extension shared, shared by SDK and presentation-layer consumers. */\nexport const _testOnlyExtensionShared = {\n  formatManifestReadError,\n};\n"],"names":[],"mappings":"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","debugId":"79cbf5a9-d060-546d-aa23-79e4b16fa6dc"}

package/dist/sdk/extension/update-check.d.ts

@@ -0,0 +1,15 @@
+import type { ManagedExtensionSource } from "./managed-state.js";
+import { runGitCommand } from "./install-sources.js";
+/** Describes the remote revision health of one managed GitHub extension. */
+export interface GithubUpdateStatus {
+    /** Time at which the remote comparison completed. */
+    checked_at: string;
+    /** Whether the remote commit differs, or null when no comparison is possible. */
+    available: boolean | null;
+    /** Peeled remote commit when the selected reference resolves. */
+    remote_commit?: string;
+    /** Stable failure reason when the comparison is incomplete. */
+    error?: string;
+}
+/** Compare one managed GitHub extension against its remote revision. */
+export declare const checkGithubUpdate: (source: ManagedExtensionSource, gitCommandRunner?: typeof runGitCommand) => Promise<GithubUpdateStatus>;

package/dist/sdk/extension/update-check.js

@@ -0,0 +1,68 @@
+/**
+ * @module sdk/extension/update-check
+ *
+ * Provides bounded and annotated-tag-aware update checks for managed extensions.
+ */
+
+!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]="59876183-57e7-59fa-8137-5f86dac61ea5")}catch(e){}}();
+import { nowIso } from "../../core/shared/time.js";
+import { runGitCommand } from "./install-sources.js";
+const GITHUB_UPDATE_CHECK_TIMEOUT_MS = 10_000;
+/** Compare ls-remote output with an optional installed revision baseline. */
+const resolveGithubUpdateOutput = (output, installedCommitInput, checkedAt) => {
+    const references = output
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .filter(Boolean)
+        .map((line) => {
+        const [commit, ref = ""] = line.split(/\s+/);
+        return { commit, ref };
+    });
+    const remoteReference = references.find((reference) => reference.ref.endsWith("^{}")) ??
+        references[0];
+    if (!remoteReference) {
+        return {
+            checked_at: checkedAt,
+            available: null,
+            error: "no_remote_reference_found",
+        };
+    }
+    const installedCommit = installedCommitInput?.trim();
+    return installedCommit
+        ? {
+            checked_at: checkedAt,
+            remote_commit: remoteReference.commit,
+            available: remoteReference.commit !== installedCommit,
+        }
+        : {
+            checked_at: checkedAt,
+            remote_commit: remoteReference.commit,
+            available: null,
+            error: "missing_installed_commit",
+        };
+};
+/** Compare one managed GitHub extension against its remote revision. */
+export const checkGithubUpdate = async (source, gitCommandRunner = runGitCommand) => {
+    const checkedAt = nowIso();
+    if (source.kind !== "github" || !source.repository) {
+        return {
+            checked_at: checkedAt,
+            available: null,
+            error: "not_a_github_managed_source",
+        };
+    }
+    try {
+        const ref = [source.ref?.trim(), "HEAD"].find(Boolean);
+        const output = await gitCommandRunner(["ls-remote", source.repository, ref, `${ref}^{}`], undefined, GITHUB_UPDATE_CHECK_TIMEOUT_MS);
+        return resolveGithubUpdateOutput(output, source.commit, checkedAt);
+    }
+    catch (error) {
+        return {
+            checked_at: checkedAt,
+            available: null,
+            error: error instanceof Error ? error.message : String(error),
+        };
+    }
+};
+//# sourceMappingURL=update-check.js.map
+//# debugId=59876183-57e7-59fa-8137-5f86dac61ea5

package/dist/sdk/extension/update-check.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"update-check.js","sources":["sdk/extension/update-check.ts"],"sourceRoot":"/","sourcesContent":["/**\n * @module sdk/extension/update-check\n *\n * Provides bounded and annotated-tag-aware update checks for managed extensions.\n */\nimport { nowIso } from \"../../core/shared/time.js\";\nimport type { ManagedExtensionSource } from \"./managed-state.js\";\nimport { runGitCommand } from \"./install-sources.js\";\n\nconst GITHUB_UPDATE_CHECK_TIMEOUT_MS = 10_000;\n\n/** Describes the remote revision health of one managed GitHub extension. */\nexport interface GithubUpdateStatus {\n  /** Time at which the remote comparison completed. */\n  checked_at: string;\n  /** Whether the remote commit differs, or null when no comparison is possible. */\n  available: boolean | null;\n  /** Peeled remote commit when the selected reference resolves. */\n  remote_commit?: string;\n  /** Stable failure reason when the comparison is incomplete. */\n  error?: string;\n}\n\n/** Compare ls-remote output with an optional installed revision baseline. */\nconst resolveGithubUpdateOutput = (\n  output: string,\n  installedCommitInput: string | undefined,\n  checkedAt: string,\n): GithubUpdateStatus => {\n  const references = output\n    .split(/\\r?\\n/)\n    .map((line) => line.trim())\n    .filter(Boolean)\n    .map((line) => {\n      const [commit, ref = \"\"] = line.split(/\\s+/) as [string, string?];\n      return { commit, ref };\n    });\n  const remoteReference =\n    references.find((reference) => reference.ref.endsWith(\"^{}\")) ??\n    references[0];\n  if (!remoteReference) {\n    return {\n      checked_at: checkedAt,\n      available: null,\n      error: \"no_remote_reference_found\",\n    };\n  }\n  const installedCommit = installedCommitInput?.trim();\n  return installedCommit\n    ? {\n        checked_at: checkedAt,\n        remote_commit: remoteReference.commit,\n        available: remoteReference.commit !== installedCommit,\n      }\n    : {\n        checked_at: checkedAt,\n        remote_commit: remoteReference.commit,\n        available: null,\n        error: \"missing_installed_commit\",\n      };\n};\n\n/** Compare one managed GitHub extension against its remote revision. */\nexport const checkGithubUpdate = async (\n  source: ManagedExtensionSource,\n  gitCommandRunner: typeof runGitCommand = runGitCommand,\n): Promise<GithubUpdateStatus> => {\n  const checkedAt = nowIso();\n  if (source.kind !== \"github\" || !source.repository) {\n    return {\n      checked_at: checkedAt,\n      available: null,\n      error: \"not_a_github_managed_source\",\n    };\n  }\n  try {\n    const ref = [source.ref?.trim(), \"HEAD\"].find(Boolean) as string;\n    const output = await gitCommandRunner(\n      [\"ls-remote\", source.repository, ref, `${ref}^{}`],\n      undefined,\n      GITHUB_UPDATE_CHECK_TIMEOUT_MS,\n    );\n    return resolveGithubUpdateOutput(output, source.commit, checkedAt);\n  } catch (error: unknown) {\n    return {\n      checked_at: checkedAt,\n      available: null,\n      error: error instanceof Error ? error.message : String(error),\n    };\n  }\n};\n"],"names":[],"mappings":"AAAA;;;;GAIG;;;AACH,OAAO,EAAE,MAAM,EAAE,MAAM,2BAA2B,CAAC;AAEnD,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAErD,MAAM,8BAA8B,GAAG,MAAM,CAAC;AAc9C,6EAA6E;AAC7E,MAAM,yBAAyB,GAAG,CAChC,MAAc,EACd,oBAAwC,EACxC,SAAiB,EACG,EAAE;IACtB,MAAM,UAAU,GAAG,MAAM;SACtB,KAAK,CAAC,OAAO,CAAC;SACd,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;SAC1B,MAAM,CAAC,OAAO,CAAC;SACf,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE;QACZ,MAAM,CAAC,MAAM,EAAE,GAAG,GAAG,EAAE,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAsB,CAAC;QAClE,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC;IACzB,CAAC,CAAC,CAAC;IACL,MAAM,eAAe,GACnB,UAAU,CAAC,IAAI,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,SAAS,CAAC,GAAG,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;QAC7D,UAAU,CAAC,CAAC,CAAC,CAAC;IAChB,IAAI,CAAC,eAAe,EAAE,CAAC;QACrB,OAAO;YACL,UAAU,EAAE,SAAS;YACrB,SAAS,EAAE,IAAI;YACf,KAAK,EAAE,2BAA2B;SACnC,CAAC;IACJ,CAAC;IACD,MAAM,eAAe,GAAG,oBAAoB,EAAE,IAAI,EAAE,CAAC;IACrD,OAAO,eAAe;QACpB,CAAC,CAAC;YACE,UAAU,EAAE,SAAS;YACrB,aAAa,EAAE,eAAe,CAAC,MAAM;YACrC,SAAS,EAAE,eAAe,CAAC,MAAM,KAAK,eAAe;SACtD;QACH,CAAC,CAAC;YACE,UAAU,EAAE,SAAS;YACrB,aAAa,EAAE,eAAe,CAAC,MAAM;YACrC,SAAS,EAAE,IAAI;YACf,KAAK,EAAE,0BAA0B;SAClC,CAAC;AACR,CAAC,CAAC;AAEF,wEAAwE;AACxE,MAAM,CAAC,MAAM,iBAAiB,GAAG,KAAK,EACpC,MAA8B,EAC9B,mBAAyC,aAAa,EACzB,EAAE;IAC/B,MAAM,SAAS,GAAG,MAAM,EAAE,CAAC;IAC3B,IAAI,MAAM,CAAC,IAAI,KAAK,QAAQ,IAAI,CAAC,MAAM,CAAC,UAAU,EAAE,CAAC;QACnD,OAAO;YACL,UAAU,EAAE,SAAS;YACrB,SAAS,EAAE,IAAI;YACf,KAAK,EAAE,6BAA6B;SACrC,CAAC;IACJ,CAAC;IACD,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC,GAAG,EAAE,IAAI,EAAE,EAAE,MAAM,CAAC,CAAC,IAAI,CAAC,OAAO,CAAW,CAAC;QACjE,MAAM,MAAM,GAAG,MAAM,gBAAgB,CACnC,CAAC,WAAW,EAAE,MAAM,CAAC,UAAU,EAAE,GAAG,EAAE,GAAG,GAAG,KAAK,CAAC,EAClD,SAAS,EACT,8BAA8B,CAC/B,CAAC;QACF,OAAO,yBAAyB,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;IACrE,CAAC;IAAC,OAAO,KAAc,EAAE,CAAC;QACxB,OAAO;YACL,UAAU,EAAE,SAAS;YACrB,SAAS,EAAE,IAAI;YACf,KAAK,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC;SAC9D,CAAC;IACJ,CAAC;AACH,CAAC,CAAC","debugId":"59876183-57e7-59fa-8137-5f86dac61ea5"}

package/dist/sdk/extension.d.ts

@@ -0,0 +1,367 @@
+/**
+ * @module sdk/extension
+ *
+ * Implements the pm extension command surface and its agent-facing runtime behavior.
+ */
+import fs from "node:fs/promises";
+import { activateExtensions, loadExtensions } from "../core/extensions/index.js";
+import type { GlobalOptions } from "../core/shared/command-types.js";
+import type { PmSettings } from "../types/index.js";
+import { parseExtensionManifest, validateExtensionDirectory } from "./extension/shared.js";
+import { readManagedExtensionState, writeManagedExtensionState, resolveManagedExtensionStatePath, type ManagedExtensionSource, type ManagedExtensionRecord, type ManagedExtensionState } from "./extension/managed-state.js";
+import { parseExtensionInstallSource } from "./extension/install-sources.js";
+import { copyExtensionDirectoryForInstall, resolveCanonicalExtensionInstallDestination } from "./extension/install-runtime.js";
+export { parseExtensionManifest, validateExtensionDirectory, readManagedExtensionState, writeManagedExtensionState, resolveManagedExtensionStatePath, parseExtensionInstallSource, copyExtensionDirectoryForInstall, resolveCanonicalExtensionInstallDestination, };
+export type { ManagedExtensionSource, ManagedExtensionRecord, ManagedExtensionState, };
+export type { ManagedExtensionStateReadResult } from "./extension/managed-state.js";
+/** Restricts extension command action values accepted by command, SDK, and storage contracts. */
+export type ExtensionCommandAction = "install" | "uninstall" | "explore" | "manage" | "describe" | "reload" | "doctor" | "catalog" | "adopt" | "adopt-all" | "activate" | "deactivate" | "init";
+/** Restricts extension scope values accepted by command, SDK, and storage contracts. */
+export type ExtensionScope = "project" | "global";
+/** Restricts extension activation status values accepted by command, SDK, and storage contracts. */
+export type ExtensionActivationStatus = "ok" | "failed" | "not_loaded" | "unknown";
+/** Documents the extension command options payload exchanged by command, SDK, and package integrations. */
+export interface ExtensionCommandOptions {
+    /** Value that configures or reports install for this contract. */
+    install?: boolean;
+    /** Value that configures or reports uninstall for this contract. */
+    uninstall?: boolean;
+    /** Value that configures or reports explore for this contract. */
+    explore?: boolean;
+    /** Value that configures or reports manage for this contract. */
+    manage?: boolean;
+    /** Value that configures or reports describe for this contract. */
+    describe?: boolean;
+    /** Value that configures or reports markdown for this contract. */
+    markdown?: boolean;
+    /** Value that configures or reports output for this contract. */
+    output?: string;
+    /** Value that configures or reports reload for this contract. */
+    reload?: boolean;
+    /** Value that configures or reports doctor for this contract. */
+    doctor?: boolean;
+    /** Value that configures or reports catalog for this contract. */
+    catalog?: boolean;
+    /** Value that configures or reports init for this contract. */
+    init?: boolean;
+    /** Value that configures or reports scaffold for this contract. */
+    scaffold?: boolean;
+    /** Value that configures or reports strict exit for this contract. */
+    strictExit?: boolean;
+    /** Value that configures or reports fail on warn for this contract. */
+    failOnWarn?: boolean;
+    /** Value that configures or reports adopt for this contract. */
+    adopt?: boolean;
+    /** Value that configures or reports adopt all for this contract. */
+    adoptAll?: boolean;
+    /** Registers this package's commands, actions, and runtime hooks with the host. */
+    activate?: boolean;
+    /** Value that configures or reports deactivate for this contract. */
+    deactivate?: boolean;
+    /** Value that configures or reports project for this contract. */
+    project?: boolean;
+    /** Value that configures or reports local for this contract. */
+    local?: boolean;
+    /** Value that configures or reports global for this contract. */
+    global?: boolean;
+    /** Value that configures or reports gh for this contract. */
+    gh?: string;
+    /** Value that configures or reports github for this contract. */
+    github?: string;
+    /** Value that configures or reports ref for this contract. */
+    ref?: string;
+    /** Value that configures or reports detail for this contract. */
+    detail?: string;
+    /** Value that configures or reports trace for this contract. */
+    trace?: boolean;
+    /** Value that configures or reports watch for this contract. */
+    watch?: boolean;
+    /** Value that configures or reports runtime probe for this contract. */
+    runtimeProbe?: boolean;
+    /** Value that configures or reports fix managed state for this contract. */
+    fixManagedState?: boolean;
+    /** Value that configures or reports isolated for this contract. */
+    isolated?: boolean;
+    /** Value that configures or reports ignore global for this contract. */
+    ignoreGlobal?: boolean;
+    /** Value that configures or reports fields for this contract. */
+    fields?: string;
+    /** Value that configures or reports capability for this contract. */
+    capability?: string;
+    /** Value that configures or reports declarative for this contract. */
+    declarative?: boolean;
+    /** Value that configures or reports vocabulary for this contract. */
+    vocabulary?: "extension" | "package";
+}
+/** Documents the managed extension summary payload exchanged by command, SDK, and package integrations. */
+export interface ManagedExtensionSummary {
+    /** Value that configures or reports name for this contract. */
+    name: string;
+    /** Value that configures or reports directory for this contract. */
+    directory: string;
+    /** Value that configures or reports version for this contract. */
+    version: string;
+    /** Value that configures or reports entry for this contract. */
+    entry: string;
+    /** Value that configures or reports scope for this contract. */
+    scope: ExtensionScope;
+    /** Value that configures or reports active for this contract. */
+    active: boolean;
+    /** Whether enabled applies to this operation. */
+    enabled: boolean;
+    /** Value that configures or reports runtime active for this contract. */
+    runtime_active: boolean | null;
+    /** Lifecycle state reported for activationthe record. */
+    activation_status: ExtensionActivationStatus;
+    /** Value that configures or reports command paths for this contract. */
+    command_paths?: string[];
+    /** Value that configures or reports action paths for this contract. */
+    action_paths?: string[];
+    /** Value that configures or reports managed for this contract. */
+    managed: boolean;
+    /** Value that configures or reports source for this contract. */
+    source?: ManagedExtensionSource;
+    /** Value that configures or reports update available for this contract. */
+    update_available?: boolean | null;
+    /** ISO 8601 timestamp recording when last update check occurred. */
+    last_update_check_at?: string;
+    /** Value that configures or reports last update remote commit for this contract. */
+    last_update_remote_commit?: string;
+    /** Value that configures or reports update error for this contract. */
+    update_error?: string;
+    /** Lifecycle state reported for update checkthe record. */
+    update_check_status: ExtensionUpdateCheckStatus;
+    /** Value that configures or reports update check reason for this contract. */
+    update_check_reason: string;
+}
+/** Documents the extension command result payload exchanged by command, SDK, and package integrations. */
+export interface ExtensionCommandResult {
+    /** Whether the operation completed without a blocking failure. */
+    ok: boolean;
+    /** Value that configures or reports action for this contract. */
+    action: ExtensionCommandAction;
+    /** Value that configures or reports scope for this contract. */
+    scope: ExtensionScope;
+    /** Value that configures or reports roots for this contract. */
+    roots: {
+        project: string;
+        global: string;
+        selected: string;
+        settings_root: string;
+    };
+    /** Value that configures or reports warnings for this contract. */
+    warnings: string[];
+    /** Value that configures or reports details for this contract. */
+    details: Record<string, unknown>;
+}
+/** Documents the extension triage summary payload exchanged by command, SDK, and package integrations. */
+export interface ExtensionTriageSummary {
+    /** Lifecycle state reported for status. */
+    status: "ok" | "warn";
+    /** Number of warning entries represented by this result. */
+    warning_count: number;
+    /** Value that configures or reports warning codes for this contract. */
+    warning_codes: string[];
+    /** Value that configures or reports warnings for this contract. */
+    warnings: string[];
+    /** Number of policy warning entries represented by this result. */
+    policy_warning_count: number;
+    /** Number of policy violation entries represented by this result. */
+    policy_violation_count: number;
+    /** Number of policy blocked entries represented by this result. */
+    policy_blocked_count: number;
+    /** Value that configures or reports total extensions for this contract. */
+    total_extensions: number;
+    /** Value that configures or reports managed total for this contract. */
+    managed_total: number;
+    /** Value that configures or reports enabled total for this contract. */
+    enabled_total: number;
+    /** Value that configures or reports active total for this contract. */
+    active_total: number;
+    /** Value that configures or reports update available total for this contract. */
+    update_available_total: number;
+    /** Value that configures or reports update health coverage for this contract. */
+    update_health_coverage: "full" | "partial";
+    /** Value that configures or reports update health partial for this contract. */
+    update_health_partial: boolean;
+    /** Number of unmanaged loaded extension entries represented by this result. */
+    unmanaged_loaded_extension_count: number;
+    /** Value that configures or reports unmanaged loaded extensions for this contract. */
+    unmanaged_loaded_extensions: string[];
+    /** Number of unmanaged expected extension entries represented by this result. */
+    unmanaged_expected_extension_count: number;
+    /** Value that configures or reports unmanaged expected extensions for this contract. */
+    unmanaged_expected_extensions: string[];
+    /** Number of unmanaged action required extension entries represented by this result. */
+    unmanaged_action_required_extension_count: number;
+    /** Value that configures or reports unmanaged action required extensions for this contract. */
+    unmanaged_action_required_extensions: string[];
+    /** Value that configures or reports update check status totals for this contract. */
+    update_check_status_totals: Record<ExtensionUpdateCheckStatus, number>;
+    /** Value that configures or reports update check failed total for this contract. */
+    update_check_failed_total: number;
+    /** Value that configures or reports top warnings for this contract. */
+    top_warnings: string[];
+    /** Value that configures or reports remediation for this contract. */
+    remediation: string[];
+    /** Value that configures or reports collision plan for this contract. */
+    collision_plan?: ExtensionCollisionPlan;
+}
+/** Documents the extension collision plan payload exchanged by command, SDK, and package integrations. */
+export interface ExtensionCollisionPlan {
+    /** Lifecycle state reported for status. */
+    status: "ok" | "conflicts_detected";
+    /** Number of collision entries represented by this result. */
+    collision_count: number;
+    /** Number of extension entries represented by this result. */
+    extension_count: number;
+    /** Value that configures or reports next best command for this contract. */
+    next_best_command: string;
+    /** Value that configures or reports collisions for this contract. */
+    collisions: Array<{
+        code: string;
+        surface: string;
+        winner: {
+            layer: ExtensionScope;
+            name: string;
+        };
+        displaced: {
+            layer: ExtensionScope;
+            name: string;
+        };
+    }>;
+    /** Value that configures or reports remediation candidates for this contract. */
+    remediation_candidates: Array<{
+        action: "deactivate";
+        extension: string;
+        command: string;
+        affected_collisions: number;
+        feature_loss: {
+            command_paths: string[];
+            action_paths: string[];
+        };
+    }>;
+}
+/** Restricts extension update check status values accepted by command, SDK, and storage contracts. */
+export type ExtensionUpdateCheckStatus = "checked" | "skipped_unmanaged" | "skipped_non_github" | "failed" | "not_checked";
+interface ExtensionUpdateCheckResolution {
+    status: ExtensionUpdateCheckStatus;
+    reason: string;
+}
+/** Restricts extension doctor detail mode values accepted by command, SDK, and storage contracts. */
+export type ExtensionDoctorDetailMode = "summary" | "deep";
+interface ExtensionPolicyOverrideDetails {
+    name: string;
+    disabled?: boolean;
+    require_trusted?: boolean;
+    require_provenance?: boolean;
+    sandbox_profile?: "none" | "restricted" | "strict";
+    allowed_capabilities?: string[];
+    blocked_capabilities?: string[];
+    allowed_surfaces?: string[];
+    blocked_surfaces?: string[];
+    allowed_commands?: string[];
+    blocked_commands?: string[];
+    allowed_actions?: string[];
+    blocked_actions?: string[];
+    allowed_services?: string[];
+    blocked_services?: string[];
+}
+interface ExtensionPolicyDetails {
+    mode: "off" | "warn" | "enforce";
+    trust_mode: "off" | "warn" | "enforce";
+    require_provenance: boolean;
+    trusted_extensions: string[];
+    default_sandbox_profile: "none" | "restricted" | "strict";
+    allowed_extensions: string[];
+    blocked_extensions: string[];
+    allowed_capabilities: string[];
+    blocked_capabilities: string[];
+    allowed_surfaces: string[];
+    blocked_surfaces: string[];
+    allowed_commands: string[];
+    blocked_commands: string[];
+    allowed_actions: string[];
+    blocked_actions: string[];
+    allowed_services: string[];
+    blocked_services: string[];
+    extension_overrides: ExtensionPolicyOverrideDetails[];
+}
+type ActivationFailureEntry = Awaited<ReturnType<typeof activateExtensions>>["failed"][number];
+interface ActivationFailureDiagnostic {
+    layer: string;
+    name: string;
+    entry_path: string;
+    error: string;
+    missing_capability?: string;
+    hint?: string;
+    trace?: {
+        method: string;
+        registration_index: number;
+        expected_schema: string;
+        command?: string;
+        capability?: string;
+        missing_capability?: string;
+        hint?: string;
+    };
+}
+interface AdoptedUnmanagedExtension {
+    name: string;
+    directory: string;
+    version: string;
+    entry: string;
+    source: ManagedExtensionSource;
+}
+interface AdoptUnmanagedExtensionsResult {
+    state: ManagedExtensionState;
+    adopted_entries: AdoptedUnmanagedExtension[];
+    unmanaged_candidates: ManagedExtensionSummary[];
+    already_managed_count: number;
+}
+/**
+ * Entry point for the `pm extension` / `pm package` command surface. Resolves the
+ * requested lifecycle action and scope, rejects out-of-scope option usage,
+ * normalizes positional aliases, then dispatches to the matching action handler —
+ * each of which reads and writes managed-extension state, runtime-probes, and
+ * returns the canonical {@link ExtensionCommandResult}. `--doctor` results are
+ * flagged for native (non-JSON-wrapped) output.
+ */
+export declare const runExtension: (target: string | undefined, options: ExtensionCommandOptions, global: GlobalOptions) => Promise<ExtensionCommandResult>;
+/** Public contract for test only, shared by SDK and presentation-layer consumers. */
+export declare const _testOnly: {
+    adoptUnmanagedExtensions: (extensionsRoot: string, scope: ExtensionScope, installedExtensions: ManagedExtensionSummary[], state: ManagedExtensionState) => Promise<AdoptUnmanagedExtensionsResult>;
+    buildAdoptedExtensionSource: (githubOption: string | undefined, extensionTarget: string, extensionDirectory: string, ref: string | undefined) => ManagedExtensionSource;
+    buildExtensionPolicyDetails: (policy: PmSettings["extensions"]["policy"] | null | undefined) => ExtensionPolicyDetails;
+    buildInstallCommandDiscovery: (extensionName: string, source: ManagedExtensionSource, commandSummary: {
+        command_paths: string[];
+        action_paths: string[];
+    }, activationFailure?: ActivationFailureDiagnostic) => Record<string, unknown>;
+    checkGithubUpdate: (source: ManagedExtensionSource, gitCommandRunner?: typeof import("./extension/install-sources.js").runGitCommand) => Promise<import("./extension/update-check.js").GithubUpdateStatus>;
+    clearExtensionState: (settings: PmSettings, name: string) => boolean;
+    collectActivationFailureDiagnostics: (failures: ActivationFailureEntry[]) => ActivationFailureDiagnostic[];
+    findActivationFailureByName: (extensionName: string, failures: ActivationFailureDiagnostic[], layer?: ExtensionScope) => ActivationFailureDiagnostic | undefined;
+    resolveInstallRuntimeActivationStatus: (extensionName: string, scope: ExtensionScope, runtimeInstalled: ManagedExtensionSummary[], installActivationFailure: ActivationFailureDiagnostic | undefined) => ExtensionActivationStatus;
+    collectGlobalOutputOverrideDoctorWarnings: (activationResult: Awaited<ReturnType<typeof activateExtensions>>) => string[];
+    collectSchemaNarrowActivationDoctorWarnings: (loadResult: Awaited<ReturnType<typeof loadExtensions>>, activationResult: Awaited<ReturnType<typeof activateExtensions>>) => string[];
+    copyExtensionDirectoryWithoutSelfNesting: (sourceDirectory: string, destinationDirectory: string, copyDirectory: typeof fs.cp, temporaryDirectory?: string) => Promise<void>;
+    isErrnoCode: (error: unknown, code: string) => boolean;
+    isRetriableExtensionInstallCopyError: (error: unknown) => boolean;
+    listInstalledExtensions: (extensionsRoot: string, scope: ExtensionScope, settings: PmSettings, state: ManagedExtensionState) => Promise<{
+        extensions: ManagedExtensionSummary[];
+        warnings: string[];
+    }>;
+    mapWithFixedConcurrency: <Input, Output>(inputs: Input[], concurrency: number, mapper: (input: Input) => Promise<Output>) => Promise<Output[]>;
+    projectExtensionUpdateCheck: (entry: ManagedExtensionSummary | undefined) => {
+        update_check_status: string | null;
+        update_check_reason: string | null;
+    };
+    readOptionalMetadataFile: (filePath: string) => Promise<Buffer | null>;
+    requireTarget: (target: string | undefined, action: ExtensionCommandAction, options?: ExtensionCommandOptions) => string;
+    resolveAction: (target: string | undefined, options: ExtensionCommandOptions) => ExtensionCommandAction;
+    resolveCommandDiscoveryPackageName: (extensionName: string, source: ManagedExtensionSource) => string;
+    resolveGithubOption: (options: ExtensionCommandOptions) => string | undefined;
+    resolveInstalledExtensionCandidate: (installed: ManagedExtensionSummary[], extensionTarget: string) => Promise<ManagedExtensionSummary | undefined>;
+    resolveScope: (options: ExtensionCommandOptions) => ExtensionScope;
+    resolveUpdateCheckResolution: (managedEntry: ManagedExtensionRecord | undefined) => ExtensionUpdateCheckResolution;
+    withExtensionInstallLock: <T>(settingsRoot: string, destinationDirectoryName: string, run: () => Promise<T>, options?: import("./extension/install-runtime.js").ExtensionInstallLockOptions) => Promise<T>;
+};