openplanr 2.2641.0 → 2.2641.2

package/dist/services/runtime-manager-service.js

@@ -1,5 +1,5 @@
 /**
- * Runtime adapter manager behind `planr setup`, `planr doctor` and `planr runtime`: previews and
+ * Runtime adapter manager behind `openplanr setup`, `openplanr doctor` and `openplanr runtime`: previews and
  * applies project or user installs of the OpenPlanr skills for Claude Code, Codex and Cursor,
  * records owned files in `<planrHome>/runtime/state.json` with per-project backups, and diagnoses
  * drift. Entry points: `previewSetup`, `applySetup`, `rollbackRuntime`, `removeRuntime`,
@@ -10,20 +10,20 @@ import { createHash, randomUUID } from 'node:crypto';
 import { existsSync, constants as fsConstants, lstatSync, readdirSync, readFileSync, realpathSync, } from 'node:fs';
 import { mkdir, open, readFile, rename, rm, unlink, writeFile, } from 'node:fs/promises';
 import path from 'node:path';
-import { fileURLToPath } from 'node:url';
 import { validateJson } from '../../lib/json-schema.mjs';
 import { CLI_NODE_REMEDIATION, cliNodeVersionMessage, supportsCliNodeVersion, } from '../../lib/node-runtime.mjs';
 import { planrHome, userHome } from '../../lib/planr-home.mjs';
+import { CLI_COMMAND, getPackageRoot, PLANNING_FOLDER } from '../utils/constants.js';
 import { spliceManagedBlock } from '../utils/splice-managed-block.js';
 import { applyBundledClaudePluginIntegration, claudePluginUninstallCommand, inspectBundledClaudePluginIntegration, } from './claude-plugin-service.js';
 import { applyCodexPluginIntegration, inspectCodexPluginIntegration, } from './codex-plugin-service.js';
 import { resolvePipelinePackage } from './pipeline-package-service.js';
 import { readOpenPlanrVersion } from './provenance-service.js';
 import { effectiveCodexHome, inspectCodexSkillDiscovery, } from './runtime-manager/codex-discovery.js';
-import { classifyComponentDrift as classifyRuntimeComponentDrift, diagnoseManagedRuntimeFiles, diagnoseRuntimeProvenance, } from './runtime-manager/doctor.js';
+import { classifyComponentDrift as classifyRuntimeComponentDrift, diagnoseManagedRuntimeFiles, diagnoseRetiredCommandSkills, diagnoseRuntimeProvenance, pluginDocuments, } from './runtime-manager/doctor.js';
 import { migrateLegacyGlobalRuntimeState, } from './runtime-manager/global-state.js';
 import { inventoryManagedSkillFiles, planCodexUserBundleTransition, } from './runtime-manager/install-plan.js';
-import { detectInstalledRuntimes, inspectRuntimeProjectContext, listInstalledRuntimeAdapters, } from './runtime-manager/inventory.js';
+import { detectInstalledRuntimes, inspectRuntimeProjectContext, listInstalledRuntimeAdapters, planningFolderConflict, } from './runtime-manager/inventory.js';
 import { inspectRuntimeLocator, inspectRuntimePackage, inspectThinRule, runtimeLocator, thinDiscoveryMetadata, thinSkillEntry, } from './runtime-manager/runtime-package.js';
 export { classifyComponentDrift } from './runtime-manager/doctor.js';
 const runtimeLockSchema = JSON.parse(readFileSync(new URL('../../lib/runtime-lock.schema.json', import.meta.url), 'utf8'));
@@ -631,7 +631,7 @@ function chooseRuntimes(choice) {
     return detected;
 }
 function readRegistry() {
-    const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
+    const root = getPackageRoot();
     const registryPath = path.join(root, 'lib', 'host-packages', 'adapter-registry.json');
     if (!existsSync(registryPath)) {
         throw new RuntimeManagerError('E_HOST_PACKAGE_MISSING', 'The OpenPlanr host-package inventory is missing.', 'Reinstall the OpenPlanr utility CLI or run the workspace skill generator.');
@@ -645,7 +645,7 @@ function readRegistry() {
     };
 }
 export function bundledHostRoot(host) {
-    const cliRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
+    const cliRoot = getPackageRoot();
     const root = path.join(cliRoot, 'lib', 'host-packages', host);
     if (!existsSync(root) || lstatSync(root).isSymbolicLink() || !lstatSync(root).isDirectory()) {
         throw new RuntimeManagerError('E_HOST_PACKAGE_MISSING', `The bundled ${host} OpenPlanr package is missing or unsafe.`, 'Reinstall the OpenPlanr utility CLI or run the workspace skill generator.');
@@ -733,7 +733,7 @@ function normalizeInstallScope(adapter, requested) {
     const supportsUser = adapter.installScopes.includes('user');
     const supportsProject = adapter.installScopes.includes('project');
     if (requested === 'user' && !supportsUser) {
-        throw new RuntimeManagerError('E_SCOPE_UNSUPPORTED', `OpenPlanr's ${adapter.id} integration currently requires project scope.`, `Change into your project, then run \`planr setup --runtime ${adapter.id} --scope project\`. To initialize a new project there, run \`planr init\` first.`);
+        throw new RuntimeManagerError('E_SCOPE_UNSUPPORTED', `OpenPlanr's ${adapter.id} integration currently requires project scope.`, `Change into your project, then run \`${CLI_COMMAND} setup --runtime ${adapter.id} --scope project\`. To initialize a new project there, run \`${CLI_COMMAND} init\` first.`);
     }
     if (requested === 'project' && !supportsProject) {
         throw new RuntimeManagerError('E_SCOPE_UNSUPPORTED', `${adapter.id} does not support project-scope installation.`);
@@ -795,7 +795,7 @@ function buildRuntimeLock(options, runtimes, runtimeScopes, registry, pipelineVe
         adapters,
         skillModes,
     });
-    const lockPath = path.join(options.projectDir, '.planr', 'runtime-lock.json');
+    const lockPath = path.join(options.projectDir, PLANNING_FOLDER, 'runtime-lock.json');
     if (existsSync(lockPath)) {
         try {
             const existing = JSON.parse(readFileSync(lockPath, 'utf8'));
@@ -907,7 +907,7 @@ function buildActions(options, runtimes, runtimeScopes, retainedProject) {
                 actions.push({
                     runtime,
                     scope: 'project',
-                    target: path.join(options.projectDir, '.planr', 'runtime-policy', `${runtime}.json`),
+                    target: path.join(options.projectDir, PLANNING_FOLDER, 'runtime-policy', `${runtime}.json`),
                     content: Buffer.from(`${JSON.stringify({ schemaVersion: '1.0.0', runtime, discovery: 'user', mode: skillInstallMode(runtime, options), packageDigest: runtimePackage.digest, packageVersion: runtimePackage.version }, null, 2)}\n`),
                     kind: 'file',
                     custody: 'professional-skill',
@@ -978,7 +978,7 @@ function buildActions(options, runtimes, runtimeScopes, retainedProject) {
         actions.push({
             runtime: 'core',
             scope: 'project',
-            target: path.join(options.projectDir, '.planr', 'runtime-lock.json'),
+            target: path.join(options.projectDir, PLANNING_FOLDER, 'runtime-lock.json'),
             content: buildRuntimeLock({
                 ...options,
                 projectSkillMode: options.projectSkillMode ?? retainedProject?.skillModes?.codex,
@@ -1005,7 +1005,7 @@ function isRetiredGeneratedCursorRule(target, content) {
     }
     const generatedFooter = source.trimEnd().split(/\r?\n/u).at(-1) ?? '';
     const deprecatedAlias = '---\ndescription: Deprecated OpenPlanr pipeline alias\nalwaysApply: false\n---\n\nThis compatibility alias is deprecated. Use the portable `openplanr.mdc` rule.\n';
-    return ((generatedFooter.startsWith('*Generated by `planr rules generate --target cursor --scope pipeline`.') &&
+    return ((generatedFooter.startsWith(`*Generated by \`${CLI_COMMAND} rules generate --target cursor --scope pipeline\`.`) &&
         generatedFooter.endsWith('*')) ||
         source === deprecatedAlias);
 }
@@ -1332,8 +1332,13 @@ export async function previewSetup(options) {
                 .find((adapter) => adapter.id === runtime)
                 ?.installScopes.includes('user')) &&
             options.skillMode !== 'project-rule';
-        throw new RuntimeManagerError('E_PROJECT_CONTEXT_REQUIRED', `Project-scoped setup requires a Git worktree or initialized OpenPlanr project; ${projectContext.path} is neither.`, `Change into your project and rerun this command, or run \`planr init\` here to initialize one.${canUseUserScope ? ' To install across projects instead, rerun this command with --scope user.' : ''}`);
+        throw new RuntimeManagerError('E_PROJECT_CONTEXT_REQUIRED', `Project-scoped setup requires a Git worktree or initialized OpenPlanr project; ${projectContext.path} is neither.`, `Change into your project and rerun this command, or run \`${CLI_COMMAND} init\` here to initialize one.${canUseUserScope ? ' To install across projects instead, rerun this command with --scope user.' : ''}`);
     }
+    const folderConflict = !options.minimal && (scope === 'project' || scope === 'both')
+        ? planningFolderConflict(options.projectDir)
+        : null;
+    if (folderConflict)
+        throw new RuntimeManagerError(folderConflict.code, folderConflict.problem, folderConflict.fix);
     let scopeIncompatibleRuntimes = [];
     if (!options.minimal && (options.runtime ?? 'auto') === 'auto' && !options.runtimes) {
         const adapters = listRuntimeAdapters();
@@ -1343,7 +1348,7 @@ export async function previewSetup(options) {
         });
         selectedRuntimes = selectedRuntimes.filter((runtime) => !scopeIncompatibleRuntimes.includes(runtime));
         if (selectedRuntimes.length === 0) {
-            throw new RuntimeManagerError('E_SCOPE_UNSUPPORTED', 'Detected coding agents require project scope, but setup defaulted to user scope.', 'Change into a Git or initialized OpenPlanr project and run `planr setup --scope project`.');
+            throw new RuntimeManagerError('E_SCOPE_UNSUPPORTED', 'Detected coding agents require project scope, but setup defaulted to user scope.', `Change into a Git or initialized OpenPlanr project and run \`${CLI_COMMAND} setup --scope project\`.`);
         }
     }
     let runtimes = selectedRuntimes;
@@ -1433,7 +1438,7 @@ export async function previewSetup(options) {
                 runtime: 'claude-code',
                 status: 'fail',
                 message: `Claude plugin state could not be inspected: ${claudeInspection.error}`,
-                fix: 'Update Claude Code, then rerun `planr setup --runtime claude --scope user`.',
+                fix: `Update Claude Code, then rerun \`${CLI_COMMAND} setup --runtime claude --scope user\`.`,
             });
         }
         else if (claudeInspection.ready) {
@@ -1485,7 +1490,7 @@ export async function previewSetup(options) {
                 runtime: 'codex',
                 status: 'fail',
                 message: `Codex plugin state could not be inspected: ${codexInspection.error}`,
-                fix: 'Repair the Codex marketplace state, then rerun planr setup --dry-run.',
+                fix: `Repair the Codex marketplace state, then rerun ${CLI_COMMAND} setup --dry-run.`,
             });
         }
         else if (codexInspection.duplicates.length > 0) {
@@ -1635,7 +1640,7 @@ export async function applySetup(options) {
             replacesPlugin ||
             replacesClaudePlugin) &&
             !options.replaceManaged) {
-            throw new RuntimeManagerError('E_INSTALL_MODE_CONFLICT', 'Changing OpenPlanr discovery mode would retire existing OpenPlanr-managed content.', 'Review planr setup --dry-run, then rerun with --replace-managed to replace only OpenPlanr-owned content.');
+            throw new RuntimeManagerError('E_INSTALL_MODE_CONFLICT', 'Changing OpenPlanr discovery mode would retire existing OpenPlanr-managed content.', `Review ${CLI_COMMAND} setup --dry-run, then rerun with --replace-managed to replace only OpenPlanr-owned content.`);
         }
         const expectedTargets = new Map(actions.map((action) => {
             if (!existsSync(action.target))
@@ -2312,6 +2317,7 @@ export async function runtimeDoctor(projectDir, options = {}) {
     const claudeManagedAtUserScope = Object.values(state.projects).some((project) => project.runtimes.includes('claude-code') &&
         ['user', 'both'].includes(project.runtimeScopes?.['claude-code'] ??
             inferRuntimeScope(project.ownedFiles, 'claude-code')));
+    const pluginSkillDocuments = [];
     const claudeDetected = Boolean(options.claudeCommandRunner) ||
         (detectedRuntimes.find((runtime) => runtime.runtime === 'claude-code')?.installed ?? false);
     if (claudeDetected && claudeManagedAtUserScope) {
@@ -2321,10 +2327,16 @@ export async function runtimeDoctor(projectDir, options = {}) {
                 code: 'runtime-claude-plugins',
                 status: 'fail',
                 message: `Claude plugin state could not be inspected: ${inspection.error}`,
-                fix: 'Update Claude Code, then run `planr runtime update claude --scope user`.',
+                fix: `Update Claude Code, then run \`${CLI_COMMAND} runtime update claude --scope user\`.`,
             });
         }
         else {
+            for (const root of [
+                ...inspection.plugins.flatMap((plugin) => plugin.installPath ?? []),
+                ...inspection.duplicatePluginPaths,
+            ]) {
+                pluginSkillDocuments.push(...pluginDocuments('claude-code', root));
+            }
             const drift = inspection.plugins.filter((plugin) => !plugin.installed ||
                 !plugin.enabled ||
                 !plugin.identityValid ||
@@ -2340,7 +2352,9 @@ export async function runtimeDoctor(projectDir, options = {}) {
                         .map((plugin) => `${plugin.id} ${plugin.installedVersion ?? 'missing'} → ${plugin.expectedVersion}${!plugin.identityValid ? ' (invalid identity)' : ''}`)
                         .join(', ')}`,
                 ...(!inspection.ready
-                    ? { fix: 'Run `planr runtime update claude --scope user` and restart Claude Code.' }
+                    ? {
+                        fix: `Run \`${CLI_COMMAND} runtime update claude --scope user\` and restart Claude Code.`,
+                    }
                     : {}),
             });
             if (inspection.legacyPluginIds.length > 0) {
@@ -2361,7 +2375,7 @@ export async function runtimeDoctor(projectDir, options = {}) {
         }
     }
     const expectsProjectLock = installed?.ownedFiles.some((file) => file.scope === 'project') ?? false;
-    const lock = path.join(projectDir, '.planr', 'runtime-lock.json');
+    const lock = path.join(projectDir, PLANNING_FOLDER, 'runtime-lock.json');
     if (!existsSync(lock)) {
         const lockStatus = expectsProjectLock ? 'warn' : installed ? 'pass' : 'warn';
         diagnostics.push({
@@ -2373,9 +2387,9 @@ export async function runtimeDoctor(projectDir, options = {}) {
                     ? 'User-scope setup does not require a project runtime lock'
                     : 'No managed runtime setup found for this directory',
             ...(expectsProjectLock
-                ? { fix: 'Run `planr setup --scope project`.' }
+                ? { fix: `Run \`${CLI_COMMAND} setup --scope project\`.` }
                 : !installed
-                    ? { fix: 'Run `planr setup`.' }
+                    ? { fix: `Run \`${CLI_COMMAND} setup\`.` }
                     : {}),
         });
     }
@@ -2414,7 +2428,7 @@ export async function runtimeDoctor(projectDir, options = {}) {
             // digest/adapter drift, or a component drift that does not include the CLI
             // (for example a pinned obsolete skill bundle), remains a genuine `fail`.
             // The warn/fail derivation lives in the single `classifyComponentDrift`
-            // helper so `planr upgrade status` reuses this exact distinction rather
+            // helper so `openplanr upgrade status` reuses this exact distinction rather
             // than re-deriving it; a digest/adapter drift is doctor's
             // flavour of an incompatible tuple.
             const { drift, genuineDrift, upgradeOnlyDrift, status } = classifyRuntimeComponentDrift({
@@ -2435,8 +2449,8 @@ export async function runtimeDoctor(projectDir, options = {}) {
                 ...(drift
                     ? {
                         fix: upgradeOnlyDrift
-                            ? 'Run `planr runtime update all --scope project` to refresh the lock to the upgraded component versions.'
-                            : 'Run `planr runtime update all --scope project`.',
+                            ? `Run \`${CLI_COMMAND} runtime update all --scope project\` to refresh the lock to the upgraded component versions.`
+                            : `Run \`${CLI_COMMAND} runtime update all --scope project\`.`,
                     }
                     : {}),
             });
@@ -2446,7 +2460,7 @@ export async function runtimeDoctor(projectDir, options = {}) {
                 code: 'runtime-lock-invalid',
                 status: 'fail',
                 message: 'Project runtime lock is not valid JSON or does not match the supported contract',
-                fix: 'Run `planr setup --scope project` after reviewing the existing lock.',
+                fix: `Run \`${CLI_COMMAND} setup --scope project\` after reviewing the existing lock.`,
             });
         }
     }
@@ -2465,7 +2479,9 @@ export async function runtimeDoctor(projectDir, options = {}) {
                 message: stateDrift
                     ? 'Runtime lock adapters do not match the managed installation state'
                     : 'Runtime lock adapters match the managed installation state',
-                ...(stateDrift ? { fix: 'Run `planr setup --dry-run`, then approve the repair.' } : {}),
+                ...(stateDrift
+                    ? { fix: `Run \`${CLI_COMMAND} setup --dry-run\`, then approve the repair.` }
+                    : {}),
             });
         }
     }
@@ -2474,7 +2490,7 @@ export async function runtimeDoctor(projectDir, options = {}) {
             code: 'runtime-state-missing',
             status: 'warn',
             message: 'The project has a runtime lock but this machine has no managed adapter state',
-            fix: 'Run `planr setup` to install the locked runtime adapters on this machine.',
+            fix: `Run \`${CLI_COMMAND} setup\` to install the locked runtime adapters on this machine.`,
         });
     }
     const globallyOwned = Object.values(state.userBundles ?? {}).flatMap((bundle) => bundle?.ownedFiles ?? []);
@@ -2485,6 +2501,9 @@ export async function runtimeDoctor(projectDir, options = {}) {
     const managedFileDiagnostic = diagnoseManagedRuntimeFiles(managedFiles, ownershipHash);
     if (managedFileDiagnostic)
         diagnostics.push(managedFileDiagnostic);
+    const commandDiagnostic = diagnoseRetiredCommandSkills([...managedFiles, ...pluginSkillDocuments], options.commandRoots ?? [], managedBlockBytes);
+    if (commandDiagnostic)
+        diagnostics.push(commandDiagnostic);
     const verifiedPackages = new Map();
     const closureFailures = [];
     for (const file of managedFiles) {
@@ -2507,7 +2526,7 @@ export async function runtimeDoctor(projectDir, options = {}) {
                 : 'Pinned runtime packages match their complete content inventories',
             ...(closureFailures.length
                 ? {
-                    fix: 'Run `planr doctor --fix` to preview exact-package repair; preserve modified cache bytes for inspection.',
+                    fix: `Run \`${CLI_COMMAND} doctor --fix\` to preview exact-package repair; preserve modified cache bytes for inspection.`,
                 }
                 : {}),
         });
@@ -2546,7 +2565,7 @@ export async function runtimeDoctor(projectDir, options = {}) {
                 code: 'runtime-codex-skill-resolution',
                 status: 'warn',
                 message: `${stale.length} stale skill(s), ${missing.length} missing skill(s), ${unreadable.length} unreadable skill(s), ${ambiguous.length} multiple discovery path(s), ${oldCaches.length} skill(s) with inactive cached copies. CLI package ${codexDiscovery.packageVersion}; per-skill and Protocol versions, paths and closure hashes are in doctor --json. An already-open session may retain earlier skills.`,
-                fix: 'Run `planr setup --runtime codex --dry-run` in this profile, review the installer repair, then restart Codex. Do not delete plugin caches by hand.',
+                fix: `Run \`${CLI_COMMAND} setup --runtime codex --dry-run\` in this profile, review the installer repair, then restart Codex. Do not delete plugin caches by hand.`,
             });
         }
         if (oldCaches.length > 0) {
@@ -2563,7 +2582,7 @@ export async function runtimeDoctor(projectDir, options = {}) {
                 code: 'runtime-codex-plugin',
                 status: 'warn',
                 message: `Codex plugin state could not be inspected: ${inspection.error}`,
-                fix: 'Run `planr setup --runtime codex --dry-run` for an exact repair preview.',
+                fix: `Run \`${CLI_COMMAND} setup --runtime codex --dry-run\` for an exact repair preview.`,
             });
         }
         else {
@@ -2578,7 +2597,7 @@ export async function runtimeDoctor(projectDir, options = {}) {
                 ...(inspection.ready
                     ? {}
                     : {
-                        fix: 'Run `planr doctor --fix` to preview repairs while preserving your saved discovery choice.',
+                        fix: `Run \`${CLI_COMMAND} doctor --fix\` to preview repairs while preserving your saved discovery choice.`,
                     }),
             });
             if ((directSkillFiles > 0 && inspection.installed) || inspection.duplicates.length > 0) {
@@ -2597,7 +2616,7 @@ export async function runtimeDoctor(projectDir, options = {}) {
             code: 'home-project-install',
             status: 'warn',
             message: `${accidentalHomeFiles.length} project-scoped managed file(s) were installed in the home directory`,
-            fix: 'Run `planr doctor --fix` to preview and remove only recorded OpenPlanr-owned project content.',
+            fix: `Run \`${CLI_COMMAND} doctor --fix\` to preview and remove only recorded OpenPlanr-owned project content.`,
         });
     }
     const provenanceDiagnostic = diagnoseRuntimeProvenance(projectDir);
@@ -2636,7 +2655,7 @@ export async function runtimeDoctor(projectDir, options = {}) {
                 code: 'pipeline-doctor-unavailable',
                 status: 'warn',
                 message: 'The pipeline doctor did not return valid JSON',
-                fix: 'Run `planr doctor` for direct diagnostics.',
+                fix: `Run \`${CLI_COMMAND} doctor\` for direct diagnostics.`,
             });
         }
     }