@unbrained/pm-cli 2026.6.23 → 2026.6.30

package/dist/cli/commands/extension.d.ts

@@ -1,5 +1,5 @@
 import fs from "node:fs/promises";
-import { activateExtensions } from "../../core/extensions/index.js";
+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";
@@ -29,6 +29,8 @@ export interface ExtensionCommandOptions {
     explore?: boolean;
     manage?: boolean;
     describe?: boolean;
+    markdown?: boolean;
+    output?: string;
     reload?: boolean;
     doctor?: boolean;
     catalog?: boolean;
@@ -53,6 +55,7 @@ export interface ExtensionCommandOptions {
     fixManagedState?: boolean;
     fields?: string;
     capability?: string;
+    declarative?: boolean;
     vocabulary?: "extension" | "package";
 }
 /**
@@ -273,8 +276,24 @@ interface AdoptUnmanagedExtensionsResult {
 }
 declare function adoptUnmanagedExtensions(extensionsRoot: string, scope: ExtensionScope, installedExtensions: ManagedExtensionSummary[], state: ManagedExtensionState): Promise<AdoptUnmanagedExtensionsResult>;
 declare function resolveGithubOption(options: ExtensionCommandOptions): string | undefined;
-declare function requireTarget(target: string | undefined, action: ExtensionCommandAction): string;
+declare function requireTarget(target: string | undefined, action: ExtensionCommandAction, options?: ExtensionCommandOptions): string;
 declare function collectGlobalOutputOverrideDoctorWarnings(activationResult: Awaited<ReturnType<typeof activateExtensions>>): string[];
+/**
+ * Doctor advisory: flag loaded extensions that contribute GLOBAL schema (custom
+ * item types or fields) yet also declare narrow `activation.commands`.
+ *
+ * Custom item types and fields must be present for the built-in commands the
+ * extension does not own and cannot enumerate (`pm create <type>`,
+ * `pm list --type <type>`, `pm validate`). Declaring `activation.commands` gates
+ * lazy activation to only the listed command paths, so the package never
+ * activates for those built-ins and its custom type silently fails to register —
+ * a quiet footgun (decision pm-halx). The `schema` scaffold deliberately omits
+ * the field; this advisory catches hand-authored packages that do not. It is
+ * doctor-only and non-blocking — `pm health` does not surface it — so the author
+ * can either drop `activation.commands` or, when the schema is intentionally
+ * command-scoped, knowingly ignore the hint.
+ */
+declare function collectSchemaNarrowActivationDoctorWarnings(loadResult: Awaited<ReturnType<typeof loadExtensions>>, activationResult: Awaited<ReturnType<typeof activateExtensions>>): string[];
 /**
  * Implements run extension for the public runtime surface of this module.
  */
@@ -289,6 +308,7 @@ export declare const _testOnly: {
     findActivationFailureByName: typeof findActivationFailureByName;
     resolveInstallRuntimeActivationStatus: typeof resolveInstallRuntimeActivationStatus;
     collectGlobalOutputOverrideDoctorWarnings: typeof collectGlobalOutputOverrideDoctorWarnings;
+    collectSchemaNarrowActivationDoctorWarnings: typeof collectSchemaNarrowActivationDoctorWarnings;
     copyExtensionDirectoryWithoutSelfNesting: typeof copyExtensionDirectoryWithoutSelfNesting;
     isErrnoCode: typeof isErrnoCode;
     isRetriableExtensionInstallCopyError: typeof isRetriableExtensionInstallCopyError;

package/dist/cli/commands/extension.js

@@ -4,7 +4,7 @@
  * Implements the pm extension command surface and its agent-facing runtime behavior.
  */
 
-!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]="bc327a80-93b0-5be9-9ebf-8864cf67d23d")}catch(e){}}();
+!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]="e112e059-bf75-55f5-a0ec-652b037fe54b")}catch(e){}}();
 import { execFile } from "node:child_process";
 import fs from "node:fs/promises";
 import os from "node:os";
@@ -16,9 +16,11 @@ 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 { levenshteinDistanceWithinLimit } from "../../core/shared/levenshtein.js";
 import { nowIso } from "../../core/shared/time.js";
 import { resolveGlobalPmRoot, resolvePmRoot } from "../../core/store/paths.js";
 import { readSettings, writeSettings } from "../../core/store/settings.js";
+import { ensureTypeFolderScaffold } from "./schema.js";
 // Cohesive helper groups now live in ./extension/* sibling modules. They are
 // imported for the command wiring that stays here and re-exported below so
 // existing import sites (sdk barrels, upgrade.ts, tests) keep importing the
@@ -39,6 +41,41 @@ const EXTENSION_INSTALL_COPY_ATTEMPTS = 3;
 const EXTENSION_INSTALL_LOCK_ATTEMPTS = 120;
 const EXTENSION_INSTALL_LOCK_DELAY_MS = 250;
 const EXTENSION_INSTALL_LOCK_STALE_MS = 120_000;
+const LIFECYCLE_ACTION_TARGETS = [
+    ["install", "install", "--install"],
+    ["uninstall", "uninstall", "--uninstall"],
+    ["explore", "explore", "--explore"],
+    ["list", "explore", "--explore"],
+    ["manage", "manage", "--manage"],
+    ["describe", "describe", "--describe"],
+    ["reload", "reload", "--reload"],
+    ["doctor", "doctor", "--doctor"],
+    ["catalog", "catalog", "--catalog"],
+    ["init", "init", "--init"],
+    ["scaffold", "init", "--scaffold"],
+    ["adopt", "adopt", "--adopt"],
+    ["adopt-all", "adopt-all", "--adopt-all"],
+    ["activate", "activate", "--activate"],
+    ["deactivate", "deactivate", "--deactivate"],
+];
+const LIFECYCLE_ACTION_FLAG_HINT = LIFECYCLE_ACTION_TARGETS.map(([, , flag]) => flag)
+    .filter((flag, index, flags) => flags.indexOf(flag) === index)
+    .join(", ");
+const LIFECYCLE_ACTION_FLAGS = {
+    install: "--install",
+    uninstall: "--uninstall",
+    explore: "--explore",
+    manage: "--manage",
+    describe: "--describe",
+    reload: "--reload",
+    doctor: "--doctor",
+    catalog: "--catalog",
+    adopt: "--adopt",
+    "adopt-all": "--adopt-all",
+    activate: "--activate",
+    deactivate: "--deactivate",
+    init: "--init",
+};
 const NATIVE_OUTPUT_MARKER = "__pm_native_output";
 function buildExtensionPolicyDetails(policy) {
     const overrides = (policy.extension_overrides ?? [])
@@ -268,6 +305,53 @@ function clearExtensionState(settings, name) {
     return (settings.extensions.enabled.join("\u0000") !== previousEnabled.join("\u0000") ||
         settings.extensions.disabled.join("\u0000") !== previousDisabled.join("\u0000"));
 }
+function suggestLifecycleActionTarget(target) {
+    const normalizedTarget = target.trim().toLowerCase();
+    const exactMatch = LIFECYCLE_ACTION_TARGETS.find(([candidate]) => candidate === normalizedTarget);
+    if (exactMatch) {
+        return { action: exactMatch[1], flag: exactMatch[2] };
+    }
+    const maxDistance = normalizedTarget.length <= 4 ? 1 : 2;
+    let nearest = null;
+    for (const [candidate, action, flag] of LIFECYCLE_ACTION_TARGETS) {
+        const distance = levenshteinDistanceWithinLimit(normalizedTarget, candidate, maxDistance);
+        if (distance === null) {
+            continue;
+        }
+        if (nearest === null) {
+            nearest = { action, flag, distance };
+            continue;
+        }
+        if (distance < nearest.distance) {
+            nearest = { action, flag, distance };
+        }
+    }
+    return nearest === null ? null : { action: nearest.action, flag: nearest.flag };
+}
+function buildUnknownLifecycleActionError(target, options) {
+    const noun = options.vocabulary === "package" ? "package" : "extension";
+    const suggestion = suggestLifecycleActionTarget(target);
+    if (!suggestion) {
+        return new PmCliError(`One action flag is required. Use one of: ${LIFECYCLE_ACTION_FLAG_HINT}. Bare \`pm package\` and \`pm extension\` default to --explore.`, EXIT_CODE.USAGE);
+    }
+    const command = `pm ${noun} ${suggestion.flag}`;
+    return new PmCliError(`Unknown ${noun} lifecycle action "${target}". Did you mean "${suggestion.flag}"?`, EXIT_CODE.USAGE, {
+        code: "unknown_lifecycle_action",
+        required: `Use one of: ${LIFECYCLE_ACTION_FLAG_HINT}.`,
+        examples: [command, `pm ${noun} --help`],
+        recovery: {
+            attempted_command: `pm ${noun} ${target}`,
+            suggested_retry: command,
+            fallback_candidates: [
+                {
+                    source: "lifecycle_action",
+                    command,
+                    reason: `nearest lifecycle action for "${target}"`,
+                },
+            ],
+        },
+    });
+}
 function resolveAction(target, options) {
     const selected = [...new Set([
             options.install ? "install" : null,
@@ -310,7 +394,7 @@ function resolveAction(target, options) {
         if (target === undefined) {
             return "explore";
         }
-        throw new PmCliError("One action flag is required. Use one of: --install, --uninstall, --explore, --manage, --describe, --reload, --doctor, --catalog, --init/--scaffold, --adopt, --adopt-all, --activate, --deactivate. Bare `pm package` and `pm extension` default to --explore.", EXIT_CODE.USAGE);
+        throw buildUnknownLifecycleActionError(target, options);
     }
     if (selected.length > 1) {
         throw new PmCliError("Extension action flags are mutually exclusive.", EXIT_CODE.USAGE);
@@ -542,6 +626,7 @@ async function probeRuntimeCommandPathsForInstall(pmRoot, settings, refreshedIns
         installed: applyDoctorRuntimeActivationState(refreshedInstalled, loadResult, activationResult),
         warnings: [...loadResult.warnings, ...activationResult.warnings],
         activation_failures: collectActivationFailureDiagnostics(activationResult.failed),
+        item_type_registrations: activationResult.registrations.item_types,
     };
 }
 async function checkGithubUpdate(source, gitCommandRunner = runGitCommand) {
@@ -673,13 +758,37 @@ function resolveGithubOption(options) {
     }
     return undefined;
 }
-function requireTarget(target, action) {
+function getLifecycleActionFlag(action) {
+    return LIFECYCLE_ACTION_FLAGS[action];
+}
+function requireTarget(target, action, options = {}) {
     const normalized = target?.trim();
     if (!normalized) {
         if (action === "init") {
             throw new PmCliError('Action "init" requires a scaffold target path (for example: pm package init ./my-package or pm extension init ./my-extension).', EXIT_CODE.USAGE);
         }
-        throw new PmCliError(`Action "${action}" requires an extension name or source target argument.`, EXIT_CODE.USAGE);
+        const noun = options.vocabulary === "package" ? "package" : "extension";
+        const targetName = action === "install" ? "source" : "name";
+        const targetLabel = `${noun} ${targetName}`;
+        const actionFlag = getLifecycleActionFlag(action);
+        const commandTarget = `<${targetName}>`;
+        const command = `pm ${noun} ${actionFlag} ${commandTarget}`;
+        throw new PmCliError(`Action "${action}" requires ${targetLabel} input.`, EXIT_CODE.USAGE, {
+            code: "missing_lifecycle_target",
+            required: `Provide a ${targetName} target for ${action}.`,
+            examples: [`pm ${noun} ${action} ${commandTarget}`, command, `pm ${noun} --help`],
+            recovery: {
+                attempted_command: `pm ${noun} ${action}`,
+                suggested_retry: command,
+                fallback_candidates: [
+                    {
+                        source: "lifecycle_action",
+                        command,
+                        reason: `flag-form ${action} command with required ${targetName} target`,
+                    },
+                ],
+            },
+        });
     }
     return normalized;
 }
@@ -696,6 +805,44 @@ function collectGlobalOutputOverrideDoctorWarnings(activationResult) {
     }
     return [...new Set(warnings)].sort((left, right) => left.localeCompare(right));
 }
+/**
+ * Doctor advisory: flag loaded extensions that contribute GLOBAL schema (custom
+ * item types or fields) yet also declare narrow `activation.commands`.
+ *
+ * Custom item types and fields must be present for the built-in commands the
+ * extension does not own and cannot enumerate (`pm create <type>`,
+ * `pm list --type <type>`, `pm validate`). Declaring `activation.commands` gates
+ * lazy activation to only the listed command paths, so the package never
+ * activates for those built-ins and its custom type silently fails to register —
+ * a quiet footgun (decision pm-halx). The `schema` scaffold deliberately omits
+ * the field; this advisory catches hand-authored packages that do not. It is
+ * doctor-only and non-blocking — `pm health` does not surface it — so the author
+ * can either drop `activation.commands` or, when the schema is intentionally
+ * command-scoped, knowingly ignore the hint.
+ */
+function collectSchemaNarrowActivationDoctorWarnings(loadResult, activationResult) {
+    const schemaContributors = new Set();
+    for (const entry of activationResult.registrations.item_types) {
+        if (entry.types.length > 0) {
+            schemaContributors.add(`${entry.layer}:${normalizeExtensionNameForMatch(entry.name)}`);
+        }
+    }
+    for (const entry of activationResult.registrations.item_fields) {
+        if (entry.fields.length > 0) {
+            schemaContributors.add(`${entry.layer}:${normalizeExtensionNameForMatch(entry.name)}`);
+        }
+    }
+    const warnings = [];
+    for (const extension of loadResult.loaded) {
+        if ((extension.activation?.commands ?? []).length === 0) {
+            continue;
+        }
+        if (schemaContributors.has(`${extension.layer}:${normalizeExtensionNameForMatch(extension.name)}`)) {
+            warnings.push(`extension_schema_narrow_activation:${extension.layer}:${extension.name}`);
+        }
+    }
+    return [...new Set(warnings)].sort((left, right) => left.localeCompare(right));
+}
 /**
  * Implements run extension for the public runtime surface of this module.
  */
@@ -719,6 +866,9 @@ export async function runExtension(target, options, global) {
     if (options.capability !== undefined && action !== "init") {
         throw new PmCliError("--capability is only valid with --init/--scaffold.", EXIT_CODE.USAGE);
     }
+    if (options.declarative === true && action !== "init") {
+        throw new PmCliError("--declarative is only valid with --init/--scaffold.", EXIT_CODE.USAGE);
+    }
     /* c8 ignore start -- alias-normalization matrix is covered by resolveAction tests; this IIFE only rewrites positional aliases */
     const normalizedTarget = (() => {
         const normalizedInput = target?.trim().toLowerCase();
@@ -779,8 +929,8 @@ export async function runExtension(target, options, global) {
         if (githubOption !== undefined || (typeof options.ref === "string" && options.ref.trim().length > 0)) {
             throw new PmCliError('Action "init" does not accept --gh/--github/--ref options.', EXIT_CODE.USAGE);
         }
-        const scaffoldTarget = requireTarget(normalizedTarget, action);
-        const scaffold = await scaffoldExtensionProject(scaffoldTarget, options.vocabulary ?? "extension", options.capability);
+        const scaffoldTarget = requireTarget(normalizedTarget, action, options);
+        const scaffold = await scaffoldExtensionProject(scaffoldTarget, options.vocabulary ?? "extension", options.capability, options.declarative === true);
         const quotedTargetPath = JSON.stringify(scaffold.target_path);
         // Forward-slash the path for the copy-pasteable `cd` hint: Windows cmd.exe /
         // PowerShell reject the doubled backslashes JSON.stringify emits, while both
@@ -793,15 +943,25 @@ export async function runExtension(target, options, global) {
                 command: scaffold.command_name,
             },
             capability: scaffold.capability,
+            style: scaffold.style,
             target_path: scaffold.target_path,
             created_directory: scaffold.created_directory,
             files: scaffold.files,
             next_steps: [
+                // Extensions are authored AND loaded as TypeScript (ADR pm-2c28 / pm-m1uz):
+                // the manifest entry is ./index.ts and pm strips types on load (Node
+                // >=22.18), so there is no compile/build step — install dependencies, then
+                // install the scaffold directly.
+                ...(options.vocabulary === "package"
+                    ? [`Install dependencies: cd ${quotedShellTargetPath}, then run "npm install"`]
+                    : [
+                        `Install type-check dependencies: cd ${quotedShellTargetPath}, then run "npm install -D typescript @types/node @unbrained/pm-cli"`,
+                    ]),
                 `Install the scaffold: ${options.vocabulary === "package" ? "pm install --project" : "pm extension --install --project"} ${quotedTargetPath}`,
                 `Smoke-test command path: pm ${scaffold.command_name}`,
                 ...(options.vocabulary === "package"
-                    ? [`Validate the sample test: cd ${quotedShellTargetPath}, then run "npm install" and "npm test"`]
-                    : []),
+                    ? [`Validate the package: cd ${quotedShellTargetPath}, then run "npm run typecheck" and "npm test"`]
+                    : [`Type-check the source (optional): cd ${quotedShellTargetPath}, then run "npx tsc --noEmit"`]),
                 `Run diagnostics: ${options.vocabulary === "package" ? "pm package doctor" : "pm extension --doctor"} --project --detail summary`,
             ],
         });
@@ -862,7 +1022,7 @@ export async function runExtension(target, options, global) {
     }
     if (action === "install") {
         const githubOption = resolveGithubOption(options);
-        const explicitSourceInput = githubOption ?? requireTarget(normalizedTarget, action);
+        const explicitSourceInput = githubOption ?? requireTarget(normalizedTarget, action, options);
         if (typeof githubOption !== "string" && isBundledPackageInstallAllTarget(explicitSourceInput)) {
             if (typeof options.ref === "string" && options.ref.trim().length > 0) {
                 throw new PmCliError('Action "install all" does not accept --ref.', EXIT_CODE.USAGE);
@@ -981,6 +1141,20 @@ export async function runExtension(target, options, global) {
                 warnings.push(...refreshedInstalled.warnings);
                 const runtimeProbe = await probeRuntimeCommandPathsForInstall(resolvedRoots.pm_root, settings, refreshedInstalled.extensions, global);
                 warnings.push(...runtimeProbe.warnings);
+                // Scaffold the folders for any item types the installed package contributes
+                // so the tracker is immediately healthy — matching `pm schema add-type` and
+                // `pm profile apply`, the other paths that register a type. Without this a
+                // freshly-installed schema package leaves a `missing_directory` health
+                // warning until the first item of its type is created. Scoped to project
+                // installs, where `pm_root` is unambiguously the tracker the type folders
+                // belong to; a global install is not tied to one tracker, so its folders are
+                // created lazily on first use in each project.
+                const installedItemTypeDefinitions = runtimeProbe.item_type_registrations
+                    .filter((entry) => normalizeExtensionNameForMatch(entry.name) === normalizeExtensionNameForMatch(validated.manifest.name))
+                    .flatMap((entry) => entry.types.map((type) => ({ name: type.name, folder: type.folder })));
+                if (scope === "project" && installedItemTypeDefinitions.length > 0) {
+                    await ensureTypeFolderScaffold(resolvedRoots.pm_root, installedItemTypeDefinitions, warnings, "install:type-folder");
+                }
                 const commandSummary = summarizeRuntimeCommandPathsForExtension(validated.manifest.name, runtimeProbe.installed);
                 const installActivationFailure = findActivationFailureByName(validated.manifest.name, runtimeProbe.activation_failures, scope);
                 const runtimeActivationStatus = resolveInstallRuntimeActivationStatus(validated.manifest.name, scope, runtimeProbe.installed, installActivationFailure);
@@ -1063,7 +1237,7 @@ export async function runExtension(target, options, global) {
         /* c8 ignore stop */
     }
     if (action === "adopt") {
-        const extensionTarget = requireTarget(normalizedTarget, action);
+        const extensionTarget = requireTarget(normalizedTarget, action, options);
         const githubOption = resolveGithubOption(options);
         const settings = await readSettings(resolvedRoots.settings_root);
         const managedStateRead = await readManagedExtensionState(resolvedRoots.selected_root);
@@ -1150,7 +1324,7 @@ export async function runExtension(target, options, global) {
         /* c8 ignore stop */
     }
     if (action === "uninstall") {
-        const extensionTarget = requireTarget(normalizedTarget, action);
+        const extensionTarget = requireTarget(normalizedTarget, action, options);
         const settings = await readSettings(resolvedRoots.settings_root);
         const managedStateRead = await readManagedExtensionState(resolvedRoots.selected_root);
         warnings.push(...managedStateRead.warnings);
@@ -1186,7 +1360,7 @@ export async function runExtension(target, options, global) {
         });
     }
     if (action === "activate" || action === "deactivate") {
-        const extensionTarget = requireTarget(normalizedTarget, action);
+        const extensionTarget = requireTarget(normalizedTarget, action, options);
         const settings = await readSettings(resolvedRoots.settings_root);
         const managedStateRead = await readManagedExtensionState(resolvedRoots.selected_root);
         warnings.push(...managedStateRead.warnings);
@@ -1252,6 +1426,7 @@ export async function runExtension(target, options, global) {
         warnings.push(...classifyDoctorActivationFailureWarnings(activationResult.failed));
         warnings.push(...classifyUnusedCapabilityWarnings(loadResult, activationResult));
         warnings.push(...collectGlobalOutputOverrideDoctorWarnings(activationResult));
+        warnings.push(...collectSchemaNarrowActivationDoctorWarnings(loadResult, activationResult));
         const runtimeInstalledExtensions = applyDoctorRuntimeActivationState(refreshedInstalled.extensions, loadResult, activationResult);
         const doctorConsistency = buildDoctorConsistencySummary(scope, runtimeInstalledExtensions, loadResult.loaded.map((entry) => ({ layer: entry.layer, name: entry.name })), loadResult.failed.map((entry) => ({ name: entry.name })), loadResult.disabled_by_flag);
         warnings.push(...doctorConsistency.warnings);
@@ -1595,6 +1770,7 @@ export const _testOnly = {
     findActivationFailureByName,
     resolveInstallRuntimeActivationStatus,
     collectGlobalOutputOverrideDoctorWarnings,
+    collectSchemaNarrowActivationDoctorWarnings,
     copyExtensionDirectoryWithoutSelfNesting,
     isErrnoCode,
     isRetriableExtensionInstallCopyError,
@@ -1609,4 +1785,4 @@ export const _testOnly = {
     withExtensionInstallLock,
 };
 //# sourceMappingURL=extension.js.map
-//# debugId=bc327a80-93b0-5be9-9ebf-8864cf67d23d
+//# debugId=e112e059-bf75-55f5-a0ec-652b037fe54b