@unbrained/pm-cli 2026.6.20 → 2026.6.21

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## 2026.6.21 - 2026-06-21
+
+### Added
+
+- Complete SDK package-author test-assertion surface: service-override + migration helpers ([pm-6pmp](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/features/pm-6pmp.toon))
+- item-format-migration: add format-version field to front-matter for future migration gating ([pm-ae1u](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/chores/pm-ae1u.toon))
+
+### Fixed
+
+- Windows nightly: secondary POSIX-separator + mocked-path test class (static-quality-gate, docs-skills-gate, bundle-cli, contracts-snapshot, smoke-npx-from-pack) ([pm-s5pe](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-s5pe.toon))
+- Nightly windows-latest STILL red after pm-i84i: scriptModule test harness imports .mjs scripts via absolute file:// URL, shebang survives missing transform (SyntaxError) ([pm-dita](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-dita.toon))
+
+### Other
+
+- Code quality & perf audit 2026-06-12 ([pm-nimu](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/tasks/pm-nimu.toon))
+- SDK testing helper for registerFlags registrations ([pm-oveq](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/tasks/pm-oveq.toon))
+
 ## 2026.6.20 - 2026-06-20
 
 ### Added

package/dist/cli/commands/extension/scaffold.js

@@ -4,7 +4,7 @@
  * Implements extension package-management support for Scaffold.
  */
 
-!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]="c6f7e50f-9cce-50a2-97ec-7c06be6d85a1")}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]="3abac9c3-3fc0-575e-8f5d-d2624fe7a20c")}catch(e){}}();
 import fs from "node:fs/promises";
 import path from "node:path";
 import { pathExists } from "../../../core/fs/fs-utils.js";
@@ -61,6 +61,11 @@ export function buildStarterExtensionScaffoldFiles(extensionName, commandName, v
             private: true,
             type: "module",
             keywords: ["pm-package"],
+            // `node --test` runs the colocated *.test.js sample against the peer SDK
+            // testing helpers; no extra dev-dependency or test runner is required.
+            scripts: {
+                test: "node --test",
+            },
             peerDependencies: {
                 "@unbrained/pm-cli": "*",
             },
@@ -77,15 +82,45 @@ export function buildStarterExtensionScaffoldFiles(extensionName, commandName, v
                 },
             },
         }, null, 2)}\n`;
+        // node:test sample: demonstrates validating command registration with the
+        // SDK testing helpers without adding a third-party test runner. Uses the
+        // package's own `commands` capability scaffold as the unit under test.
+        const sampleTest = [
+            'import assert from "node:assert/strict";',
+            'import { test } from "node:test";',
+            'import { activateExtensionForTest, assertRegisteredCommandContract } from "@unbrained/pm-cli/sdk/testing";',
+            'import extension from "./index.js";',
+            "",
+            `test(${JSON.stringify(`${extensionName} registers its starter command`)}, async () => {`,
+            "  // `capabilities` mirrors manifest.json so the in-memory activation grants",
+            "  // the `commands` capability the entrypoint relies on.",
+            "  const activation = await activateExtensionForTest(extension, {",
+            `    name: ${JSON.stringify(extensionName)},`,
+            '    capabilities: ["commands"],',
+            "  });",
+            "  // assertRegisteredCommandContract throws if the command is not",
+            "  // registered, so reaching here already proves the wiring; assert on the",
+            "  // returned definition to demonstrate inspecting registered metadata.",
+            "  const registered = assertRegisteredCommandContract(activation.registrations, {",
+            `    command: ${JSON.stringify(commandName)},`,
+            `    extensionName: ${JSON.stringify(extensionName)},`,
+            "  });",
+            '  assert.equal(typeof registered.command.description, "string");',
+            "});",
+            "",
+        ].join("\n");
+        const gitignore = ["node_modules/", "*.log", ""].join("\n");
         const packageReadme = [
             `# ${packageName}`,
             "",
             "Generated by `pm package init`.",
             "",
             "## Included Files",
-            "- `package.json`: package metadata and `pm` resource manifest.",
+            "- `package.json`: package metadata, `test` script, and `pm` resource manifest.",
             "- `manifest.json`: extension metadata and capabilities.",
             "- `index.js`: starter command registration using the `commands` capability.",
+            "- `index.test.js`: sample `node:test` suite using the SDK testing helpers.",
+            "- `.gitignore`: ignores `node_modules/` and log files.",
             "",
             "## Quick Start",
             "```bash",
@@ -94,6 +129,15 @@ export function buildStarterExtensionScaffoldFiles(extensionName, commandName, v
             "pm package doctor --project --detail summary",
             "```",
             "",
+            "## Validate the Package",
+            "Install the peer SDK once, then run the colocated sample test:",
+            "```bash",
+            "npm install",
+            "npm test",
+            "```",
+            "`npm test` runs `node --test`, which executes `index.test.js` against the",
+            "`@unbrained/pm-cli/sdk/testing` helpers — no extra test runner required.",
+            "",
             "## Compatibility Bounds",
             "`manifest.json` cannot hold comments, so the version-compatibility fields are documented here:",
             `- \`manifest_version\` (integer): manifest schema generation. Leave at \`${SCAFFOLD_MANIFEST_VERSION}\` unless you adopt a newer manifest schema.`,
@@ -111,6 +155,8 @@ export function buildStarterExtensionScaffoldFiles(extensionName, commandName, v
             "package.json": packageJson,
             "manifest.json": manifest,
             "index.js": entrypoint,
+            "index.test.js": sampleTest,
+            ".gitignore": gitignore,
             "README.md": packageReadme,
         };
     }
@@ -203,4 +249,4 @@ export async function scaffoldExtensionProject(target, vocabulary = "extension")
     };
 }
 //# sourceMappingURL=scaffold.js.map
-//# debugId=c6f7e50f-9cce-50a2-97ec-7c06be6d85a1
+//# debugId=3abac9c3-3fc0-575e-8f5d-d2624fe7a20c

package/dist/cli/commands/extension/scaffold.js.map

@@ -1 +1 @@
-{"version":3,"file":"scaffold.js","sources":["cli/commands/extension/scaffold.ts"],"sourceRoot":"/","sourcesContent":["/**\n * @module cli/commands/extension/scaffold\n *\n * Implements extension package-management support for Scaffold.\n */\nimport fs from \"node:fs/promises\";\nimport path from \"node:path\";\nimport { pathExists } from \"../../../core/fs/fs-utils.js\";\nimport { EXIT_CODE } from \"../../../core/shared/constants.js\";\nimport { PmCliError } from \"../../../core/shared/errors.js\";\nimport { normalizeManagedDirectoryName } from \"./shared.js\";\n\n// Safe compatibility floor emitted into scaffolded manifests. Mirrors the\n// first-party package manifests (pm-nf2q): every current 2026.5.x CLI\n// satisfies it, and it models the field for external authors. manifest_version\n// tracks the manifest schema generation (currently 1).\nconst SCAFFOLD_MANIFEST_VERSION = 1;\nconst SCAFFOLD_PM_MIN_VERSION = \"2026.5.0\";\n\ninterface ExtensionScaffoldFileResult {\n  path: string;\n  status: \"created\" | \"unchanged\";\n}\n\ninterface ExtensionScaffoldResult {\n  extension_name: string;\n  command_name: string;\n  target_path: string;\n  created_directory: boolean;\n  files: ExtensionScaffoldFileResult[];\n}\n\n\n/**\n * Implements build starter extension scaffold files for the public runtime surface of this module.\n */\nexport function buildStarterExtensionScaffoldFiles(\n  extensionName: string,\n  commandName: string,\n  vocabulary: \"extension\" | \"package\",\n): Record<string, string> {\n  const packageName = `pm-${extensionName}`;\n  const manifest = `${JSON.stringify(\n    {\n      name: extensionName,\n      version: \"0.1.0\",\n      entry: \"./index.js\",\n      capabilities: [\"commands\"],\n      manifest_version: SCAFFOLD_MANIFEST_VERSION,\n      pm_min_version: SCAFFOLD_PM_MIN_VERSION,\n    },\n    null,\n    2,\n  )}\\n`;\n  // Keep scaffolds dependency-light by default: even package mode can be\n  // installed before peer dependencies are materialized in the generated root.\n  // The JSDoc import preserves editor narrowing without forcing the runtime\n  // loader to resolve @unbrained/pm-cli/sdk from a freshly generated scaffold.\n  const entrypoint = [\n    '/** @param {import(\"@unbrained/pm-cli/sdk\").ExtensionApi} api */',\n    \"export function activate(api) {\",\n    \"  api.registerCommand({\",\n    `    name: ${JSON.stringify(commandName)},`,\n    '    description: \"Starter scaffold command. Replace with your own behavior.\",',\n    \"    run: async (context) => ({\",\n    \"      ok: true,\",\n    `      source: ${JSON.stringify(extensionName)},`,\n    \"      command: context.command,\",\n    '      message: \"Starter extension scaffold is active.\",',\n    \"    }),\",\n    \"  });\",\n    \"}\",\n    \"\",\n    \"export default {\",\n    \"  activate,\",\n    \"};\",\n    \"\",\n  ].join(\"\\n\");\n  if (vocabulary === \"package\") {\n    const packageJson = `${JSON.stringify(\n      {\n        name: packageName,\n        version: \"0.1.0\",\n        private: true,\n        type: \"module\",\n        keywords: [\"pm-package\"],\n        peerDependencies: {\n          \"@unbrained/pm-cli\": \"*\",\n        },\n        pm: {\n          aliases: [extensionName],\n          extensions: [\".\"],\n          docs: [\"README.md\"],\n          examples: [\"README.md\"],\n          catalog: {\n            display_name: extensionName,\n            category: \"workflow\",\n            summary: \"Starter pm package scaffold.\",\n            tags: [\"starter\"],\n          },\n        },\n      },\n      null,\n      2,\n    )}\\n`;\n    const packageReadme = [\n      `# ${packageName}`,\n      \"\",\n      \"Generated by `pm package init`.\",\n      \"\",\n      \"## Included Files\",\n      \"- `package.json`: package metadata and `pm` resource manifest.\",\n      \"- `manifest.json`: extension metadata and capabilities.\",\n      \"- `index.js`: starter command registration using the `commands` capability.\",\n      \"\",\n      \"## Quick Start\",\n      \"```bash\",\n      \"pm install --project <package-path>\",\n      `pm ${commandName}`,\n      \"pm package doctor --project --detail summary\",\n      \"```\",\n      \"\",\n      \"## Compatibility Bounds\",\n      \"`manifest.json` cannot hold comments, so the version-compatibility fields are documented here:\",\n      `- \\`manifest_version\\` (integer): manifest schema generation. Leave at \\`${SCAFFOLD_MANIFEST_VERSION}\\` unless you adopt a newer manifest schema.`,\n      `- \\`pm_min_version\\` (string): lowest pm CLI version that may load this package. Scaffolded as \\`${SCAFFOLD_PM_MIN_VERSION}\\`. The loader blocks the package on older CLIs.`,\n      \"- `pm_max_version` (string, optional): highest pm CLI version that may load this package. Add it to block CLIs that are newer than the version you have validated against. The loader blocks the package when the CLI exceeds this bound.\",\n      \"\",\n      \"## Notes\",\n      \"- Keep simple starter runtime behavior at the package root so local installs work without dependency bootstrapping.\",\n      \"- Move larger runtimes into subdirectories only after adding package dependencies and validating `pm package doctor`.\",\n      \"- Add capabilities to the extension manifest only when the entrypoint uses the matching SDK API.\",\n      \"- Use `@unbrained/pm-cli/sdk` as the public SDK import for richer package runtimes.\",\n      \"\",\n    ].join(\"\\n\");\n    return {\n      \"package.json\": packageJson,\n      \"manifest.json\": manifest,\n      \"index.js\": entrypoint,\n      \"README.md\": packageReadme,\n    };\n  }\n  const readme = [\n    `# ${extensionName}`,\n    \"\",\n    \"Generated by `pm extension init`.\",\n    \"\",\n    \"## Included Files\",\n    \"- `manifest.json`: extension metadata and capabilities.\",\n    \"- `index.js`: starter command registration using the `commands` capability.\",\n    \"\",\n    \"## Quick Start\",\n    \"```bash\",\n    \"pm extension --install --project <scaffold-path>\",\n    `pm ${commandName}`,\n    \"pm extension --doctor --project --detail summary\",\n    \"```\",\n    \"\",\n    \"## Compatibility Bounds\",\n    \"`manifest.json` cannot hold comments, so the version-compatibility fields are documented here:\",\n    `- \\`manifest_version\\` (integer): manifest schema generation. Leave at \\`${SCAFFOLD_MANIFEST_VERSION}\\` unless you adopt a newer manifest schema.`,\n    `- \\`pm_min_version\\` (string): lowest pm CLI version that may load this extension. Scaffolded as \\`${SCAFFOLD_PM_MIN_VERSION}\\`. The loader blocks the extension on older CLIs.`,\n    \"- `pm_max_version` (string, optional): highest pm CLI version that may load this extension. Add it to block CLIs that are newer than the version you have validated against. The loader blocks the extension when the CLI exceeds this bound.\",\n    \"\",\n    \"## Notes\",\n    \"- This scaffold uses ESM exports so it works in package scopes with `type: module`.\",\n    \"- Update `manifest.json` capabilities and `index.js` command behavior as your extension evolves.\",\n    \"\",\n  ].join(\"\\n\");\n  return {\n    \"manifest.json\": manifest,\n    \"index.js\": entrypoint,\n    \"README.md\": readme,\n  };\n}\n\n/**\n * Implements scaffold extension project for the public runtime surface of this module.\n */\nexport async function scaffoldExtensionProject(\n  target: string,\n  vocabulary: \"extension\" | \"package\" = \"extension\",\n): Promise<ExtensionScaffoldResult> {\n  const normalizedTarget = target.trim();\n  const targetPath = path.resolve(process.cwd(), normalizedTarget);\n  const extensionName = normalizeManagedDirectoryName(path.basename(targetPath));\n  const commandName = `${extensionName} ping`;\n  const scaffoldFiles = buildStarterExtensionScaffoldFiles(extensionName, commandName, vocabulary);\n\n  let createdDirectory = false;\n  if (await pathExists(targetPath)) {\n    const existingTargetStats = await fs.stat(targetPath);\n    if (!existingTargetStats.isDirectory()) {\n      throw new PmCliError(\n        `Scaffold target \"${targetPath}\" exists and is not a directory.`,\n        EXIT_CODE.CONFLICT,\n      );\n    }\n  } else {\n    await fs.mkdir(targetPath, { recursive: true });\n    createdDirectory = true;\n  }\n\n  for (const [relativePath, content] of Object.entries(scaffoldFiles)) {\n    const absolutePath = path.join(targetPath, relativePath);\n    if (!(await pathExists(absolutePath))) {\n      continue;\n    }\n    const existingContent = await fs.readFile(absolutePath, \"utf8\");\n    if (existingContent !== content) {\n      throw new PmCliError(\n        `Scaffold file \"${relativePath}\" already exists with different content in \"${targetPath}\". Choose a new target path or remove conflicting files.`,\n        EXIT_CODE.CONFLICT,\n      );\n    }\n  }\n\n  const files: ExtensionScaffoldFileResult[] = [];\n  for (const [relativePath, content] of Object.entries(scaffoldFiles)) {\n    const absolutePath = path.join(targetPath, relativePath);\n    if (await pathExists(absolutePath)) {\n      files.push({\n        path: relativePath,\n        status: \"unchanged\",\n      });\n      continue;\n    }\n    await fs.mkdir(path.dirname(absolutePath), { recursive: true });\n    await fs.writeFile(absolutePath, content, \"utf8\");\n    files.push({\n      path: relativePath,\n      status: \"created\",\n    });\n  }\n\n  return {\n    extension_name: extensionName,\n    command_name: commandName,\n    target_path: targetPath,\n    created_directory: createdDirectory,\n    files,\n  };\n}\n"],"names":[],"mappings":"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","debugId":"c6f7e50f-9cce-50a2-97ec-7c06be6d85a1"}
+{"version":3,"file":"scaffold.js","sources":["cli/commands/extension/scaffold.ts"],"sourceRoot":"/","sourcesContent":["/**\n * @module cli/commands/extension/scaffold\n *\n * Implements extension package-management support for Scaffold.\n */\nimport fs from \"node:fs/promises\";\nimport path from \"node:path\";\nimport { pathExists } from \"../../../core/fs/fs-utils.js\";\nimport { EXIT_CODE } from \"../../../core/shared/constants.js\";\nimport { PmCliError } from \"../../../core/shared/errors.js\";\nimport { normalizeManagedDirectoryName } from \"./shared.js\";\n\n// Safe compatibility floor emitted into scaffolded manifests. Mirrors the\n// first-party package manifests (pm-nf2q): every current 2026.5.x CLI\n// satisfies it, and it models the field for external authors. manifest_version\n// tracks the manifest schema generation (currently 1).\nconst SCAFFOLD_MANIFEST_VERSION = 1;\nconst SCAFFOLD_PM_MIN_VERSION = \"2026.5.0\";\n\ninterface ExtensionScaffoldFileResult {\n  path: string;\n  status: \"created\" | \"unchanged\";\n}\n\ninterface ExtensionScaffoldResult {\n  extension_name: string;\n  command_name: string;\n  target_path: string;\n  created_directory: boolean;\n  files: ExtensionScaffoldFileResult[];\n}\n\n\n/**\n * Implements build starter extension scaffold files for the public runtime surface of this module.\n */\nexport function buildStarterExtensionScaffoldFiles(\n  extensionName: string,\n  commandName: string,\n  vocabulary: \"extension\" | \"package\",\n): Record<string, string> {\n  const packageName = `pm-${extensionName}`;\n  const manifest = `${JSON.stringify(\n    {\n      name: extensionName,\n      version: \"0.1.0\",\n      entry: \"./index.js\",\n      capabilities: [\"commands\"],\n      manifest_version: SCAFFOLD_MANIFEST_VERSION,\n      pm_min_version: SCAFFOLD_PM_MIN_VERSION,\n    },\n    null,\n    2,\n  )}\\n`;\n  // Keep scaffolds dependency-light by default: even package mode can be\n  // installed before peer dependencies are materialized in the generated root.\n  // The JSDoc import preserves editor narrowing without forcing the runtime\n  // loader to resolve @unbrained/pm-cli/sdk from a freshly generated scaffold.\n  const entrypoint = [\n    '/** @param {import(\"@unbrained/pm-cli/sdk\").ExtensionApi} api */',\n    \"export function activate(api) {\",\n    \"  api.registerCommand({\",\n    `    name: ${JSON.stringify(commandName)},`,\n    '    description: \"Starter scaffold command. Replace with your own behavior.\",',\n    \"    run: async (context) => ({\",\n    \"      ok: true,\",\n    `      source: ${JSON.stringify(extensionName)},`,\n    \"      command: context.command,\",\n    '      message: \"Starter extension scaffold is active.\",',\n    \"    }),\",\n    \"  });\",\n    \"}\",\n    \"\",\n    \"export default {\",\n    \"  activate,\",\n    \"};\",\n    \"\",\n  ].join(\"\\n\");\n  if (vocabulary === \"package\") {\n    const packageJson = `${JSON.stringify(\n      {\n        name: packageName,\n        version: \"0.1.0\",\n        private: true,\n        type: \"module\",\n        keywords: [\"pm-package\"],\n        // `node --test` runs the colocated *.test.js sample against the peer SDK\n        // testing helpers; no extra dev-dependency or test runner is required.\n        scripts: {\n          test: \"node --test\",\n        },\n        peerDependencies: {\n          \"@unbrained/pm-cli\": \"*\",\n        },\n        pm: {\n          aliases: [extensionName],\n          extensions: [\".\"],\n          docs: [\"README.md\"],\n          examples: [\"README.md\"],\n          catalog: {\n            display_name: extensionName,\n            category: \"workflow\",\n            summary: \"Starter pm package scaffold.\",\n            tags: [\"starter\"],\n          },\n        },\n      },\n      null,\n      2,\n    )}\\n`;\n    // node:test sample: demonstrates validating command registration with the\n    // SDK testing helpers without adding a third-party test runner. Uses the\n    // package's own `commands` capability scaffold as the unit under test.\n    const sampleTest = [\n      'import assert from \"node:assert/strict\";',\n      'import { test } from \"node:test\";',\n      'import { activateExtensionForTest, assertRegisteredCommandContract } from \"@unbrained/pm-cli/sdk/testing\";',\n      'import extension from \"./index.js\";',\n      \"\",\n      `test(${JSON.stringify(`${extensionName} registers its starter command`)}, async () => {`,\n      \"  // `capabilities` mirrors manifest.json so the in-memory activation grants\",\n      \"  // the `commands` capability the entrypoint relies on.\",\n      \"  const activation = await activateExtensionForTest(extension, {\",\n      `    name: ${JSON.stringify(extensionName)},`,\n      '    capabilities: [\"commands\"],',\n      \"  });\",\n      \"  // assertRegisteredCommandContract throws if the command is not\",\n      \"  // registered, so reaching here already proves the wiring; assert on the\",\n      \"  // returned definition to demonstrate inspecting registered metadata.\",\n      \"  const registered = assertRegisteredCommandContract(activation.registrations, {\",\n      `    command: ${JSON.stringify(commandName)},`,\n      `    extensionName: ${JSON.stringify(extensionName)},`,\n      \"  });\",\n      '  assert.equal(typeof registered.command.description, \"string\");',\n      \"});\",\n      \"\",\n    ].join(\"\\n\");\n    const gitignore = [\"node_modules/\", \"*.log\", \"\"].join(\"\\n\");\n    const packageReadme = [\n      `# ${packageName}`,\n      \"\",\n      \"Generated by `pm package init`.\",\n      \"\",\n      \"## Included Files\",\n      \"- `package.json`: package metadata, `test` script, and `pm` resource manifest.\",\n      \"- `manifest.json`: extension metadata and capabilities.\",\n      \"- `index.js`: starter command registration using the `commands` capability.\",\n      \"- `index.test.js`: sample `node:test` suite using the SDK testing helpers.\",\n      \"- `.gitignore`: ignores `node_modules/` and log files.\",\n      \"\",\n      \"## Quick Start\",\n      \"```bash\",\n      \"pm install --project <package-path>\",\n      `pm ${commandName}`,\n      \"pm package doctor --project --detail summary\",\n      \"```\",\n      \"\",\n      \"## Validate the Package\",\n      \"Install the peer SDK once, then run the colocated sample test:\",\n      \"```bash\",\n      \"npm install\",\n      \"npm test\",\n      \"```\",\n      \"`npm test` runs `node --test`, which executes `index.test.js` against the\",\n      \"`@unbrained/pm-cli/sdk/testing` helpers — no extra test runner required.\",\n      \"\",\n      \"## Compatibility Bounds\",\n      \"`manifest.json` cannot hold comments, so the version-compatibility fields are documented here:\",\n      `- \\`manifest_version\\` (integer): manifest schema generation. Leave at \\`${SCAFFOLD_MANIFEST_VERSION}\\` unless you adopt a newer manifest schema.`,\n      `- \\`pm_min_version\\` (string): lowest pm CLI version that may load this package. Scaffolded as \\`${SCAFFOLD_PM_MIN_VERSION}\\`. The loader blocks the package on older CLIs.`,\n      \"- `pm_max_version` (string, optional): highest pm CLI version that may load this package. Add it to block CLIs that are newer than the version you have validated against. The loader blocks the package when the CLI exceeds this bound.\",\n      \"\",\n      \"## Notes\",\n      \"- Keep simple starter runtime behavior at the package root so local installs work without dependency bootstrapping.\",\n      \"- Move larger runtimes into subdirectories only after adding package dependencies and validating `pm package doctor`.\",\n      \"- Add capabilities to the extension manifest only when the entrypoint uses the matching SDK API.\",\n      \"- Use `@unbrained/pm-cli/sdk` as the public SDK import for richer package runtimes.\",\n      \"\",\n    ].join(\"\\n\");\n    return {\n      \"package.json\": packageJson,\n      \"manifest.json\": manifest,\n      \"index.js\": entrypoint,\n      \"index.test.js\": sampleTest,\n      \".gitignore\": gitignore,\n      \"README.md\": packageReadme,\n    };\n  }\n  const readme = [\n    `# ${extensionName}`,\n    \"\",\n    \"Generated by `pm extension init`.\",\n    \"\",\n    \"## Included Files\",\n    \"- `manifest.json`: extension metadata and capabilities.\",\n    \"- `index.js`: starter command registration using the `commands` capability.\",\n    \"\",\n    \"## Quick Start\",\n    \"```bash\",\n    \"pm extension --install --project <scaffold-path>\",\n    `pm ${commandName}`,\n    \"pm extension --doctor --project --detail summary\",\n    \"```\",\n    \"\",\n    \"## Compatibility Bounds\",\n    \"`manifest.json` cannot hold comments, so the version-compatibility fields are documented here:\",\n    `- \\`manifest_version\\` (integer): manifest schema generation. Leave at \\`${SCAFFOLD_MANIFEST_VERSION}\\` unless you adopt a newer manifest schema.`,\n    `- \\`pm_min_version\\` (string): lowest pm CLI version that may load this extension. Scaffolded as \\`${SCAFFOLD_PM_MIN_VERSION}\\`. The loader blocks the extension on older CLIs.`,\n    \"- `pm_max_version` (string, optional): highest pm CLI version that may load this extension. Add it to block CLIs that are newer than the version you have validated against. The loader blocks the extension when the CLI exceeds this bound.\",\n    \"\",\n    \"## Notes\",\n    \"- This scaffold uses ESM exports so it works in package scopes with `type: module`.\",\n    \"- Update `manifest.json` capabilities and `index.js` command behavior as your extension evolves.\",\n    \"\",\n  ].join(\"\\n\");\n  return {\n    \"manifest.json\": manifest,\n    \"index.js\": entrypoint,\n    \"README.md\": readme,\n  };\n}\n\n/**\n * Implements scaffold extension project for the public runtime surface of this module.\n */\nexport async function scaffoldExtensionProject(\n  target: string,\n  vocabulary: \"extension\" | \"package\" = \"extension\",\n): Promise<ExtensionScaffoldResult> {\n  const normalizedTarget = target.trim();\n  const targetPath = path.resolve(process.cwd(), normalizedTarget);\n  const extensionName = normalizeManagedDirectoryName(path.basename(targetPath));\n  const commandName = `${extensionName} ping`;\n  const scaffoldFiles = buildStarterExtensionScaffoldFiles(extensionName, commandName, vocabulary);\n\n  let createdDirectory = false;\n  if (await pathExists(targetPath)) {\n    const existingTargetStats = await fs.stat(targetPath);\n    if (!existingTargetStats.isDirectory()) {\n      throw new PmCliError(\n        `Scaffold target \"${targetPath}\" exists and is not a directory.`,\n        EXIT_CODE.CONFLICT,\n      );\n    }\n  } else {\n    await fs.mkdir(targetPath, { recursive: true });\n    createdDirectory = true;\n  }\n\n  for (const [relativePath, content] of Object.entries(scaffoldFiles)) {\n    const absolutePath = path.join(targetPath, relativePath);\n    if (!(await pathExists(absolutePath))) {\n      continue;\n    }\n    const existingContent = await fs.readFile(absolutePath, \"utf8\");\n    if (existingContent !== content) {\n      throw new PmCliError(\n        `Scaffold file \"${relativePath}\" already exists with different content in \"${targetPath}\". Choose a new target path or remove conflicting files.`,\n        EXIT_CODE.CONFLICT,\n      );\n    }\n  }\n\n  const files: ExtensionScaffoldFileResult[] = [];\n  for (const [relativePath, content] of Object.entries(scaffoldFiles)) {\n    const absolutePath = path.join(targetPath, relativePath);\n    if (await pathExists(absolutePath)) {\n      files.push({\n        path: relativePath,\n        status: \"unchanged\",\n      });\n      continue;\n    }\n    await fs.mkdir(path.dirname(absolutePath), { recursive: true });\n    await fs.writeFile(absolutePath, content, \"utf8\");\n    files.push({\n      path: relativePath,\n      status: \"created\",\n    });\n  }\n\n  return {\n    extension_name: extensionName,\n    command_name: commandName,\n    target_path: targetPath,\n    created_directory: createdDirectory,\n    files,\n  };\n}\n"],"names":[],"mappings":"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","debugId":"3abac9c3-3fc0-575e-8f5d-d2624fe7a20c"}

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]="4c40a0ee-f2c1-5329-a52d-355491472f77")}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]="b0b28569-ac5e-5484-8ffb-a578de22fd15")}catch(e){}}();
 import { execFile } from "node:child_process";
 import fs from "node:fs/promises";
 import os from "node:os";
@@ -777,6 +777,10 @@ export async function runExtension(target, options, global) {
         const scaffoldTarget = requireTarget(normalizedTarget, action);
         const scaffold = await scaffoldExtensionProject(scaffoldTarget, options.vocabulary ?? "extension");
         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
+        // shells (and POSIX) accept forward slashes.
+        const quotedShellTargetPath = JSON.stringify(scaffold.target_path.replace(/\\/g, "/"));
         return withResult({
             scaffolded: scaffold.created_directory || scaffold.files.some((entry) => entry.status === "created"),
             extension: {
@@ -789,6 +793,9 @@ export async function runExtension(target, options, global) {
             next_steps: [
                 `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"`]
+                    : []),
                 `Run diagnostics: ${options.vocabulary === "package" ? "pm package doctor" : "pm extension --doctor"} --project --detail summary`,
             ],
         });
@@ -1572,4 +1579,4 @@ export const _testOnly = {
     withExtensionInstallLock,
 };
 //# sourceMappingURL=extension.js.map
-//# debugId=4c40a0ee-f2c1-5329-a52d-355491472f77
+//# debugId=b0b28569-ac5e-5484-8ffb-a578de22fd15