diff --git a/test/test-installation-components.js b/test/test-installation-components.js index 4827afcbf..a687def21 100644 --- a/test/test-installation-components.js +++ b/test/test-installation-components.js @@ -285,6 +285,10 @@ async function runTests() { const opencodeInstaller = platformCodes.platforms.opencode?.installer; assert(opencodeInstaller?.target_dir === '.agents/skills', 'OpenCode target_dir uses native skills path'); + assert( + opencodeInstaller?.commands_target_dir === '.opencode/commands', + 'OpenCode commands_target_dir is configured for / slash commands', + ); const tempProjectDir = await fs.mkdtemp(path.join(os.tmpdir(), 'bmad-opencode-test-')); const installedBmadDir = await createTestBmadFixture(); @@ -301,6 +305,55 @@ async function runTests() { const skillFile = path.join(tempProjectDir, '.agents', 'skills', 'bmad-master', 'SKILL.md'); assert(await fs.pathExists(skillFile), 'OpenCode install writes SKILL.md directory output'); + // Command pointer assertions: a / slash command should exist + // for each installed skill so users can invoke skills directly without + // going through the /skills menu. + const commandFile = path.join(tempProjectDir, '.opencode', 'commands', 'bmad-master.md'); + assert(await fs.pathExists(commandFile), 'OpenCode install writes per-skill command pointer file'); + + const commandContent = await fs.readFile(commandFile, 'utf8'); + assert(commandContent.includes('@skills/bmad-master'), 'Command pointer body references the skill via @skills/'); + assert(commandContent.includes('description:'), 'Command pointer carries a description in YAML frontmatter'); + + // Idempotency: re-running install must not duplicate or rewrite pointers. + const result2 = await ideManager.setup('opencode', tempProjectDir, installedBmadDir, { + silent: true, + selectedModules: ['bmm'], + }); + assert(result2.success === true, 'Second OpenCode install succeeds (idempotent)'); + assert(await fs.pathExists(commandFile), 'Command pointer survives a second install pass'); + + // Description-update propagation: when the manifest description changes + // and the on-disk pointer still matches the generator pattern, refresh + // the file so users see the updated description. + const csvPath = path.join(installedBmadDir, '_config', 'skill-manifest.csv'); + const updatedCsv = + 'canonicalId,name,description,module,path\n' + + '"bmad-master","bmad-master","UPDATED description for the test agent","core","_bmad/core/bmad-master/SKILL.md"\n'; + await fs.writeFile(csvPath, updatedCsv); + const result3 = await ideManager.setup('opencode', tempProjectDir, installedBmadDir, { + silent: true, + selectedModules: ['bmm'], + }); + assert(result3.success === true, 'Third OpenCode install succeeds after description update'); + const refreshed = await fs.readFile(commandFile, 'utf8'); + assert(refreshed.includes('UPDATED description'), 'Generator-shaped pointer is refreshed when manifest description changes'); + + // Hand-edit preservation across the production install flow. The + // installer passes previousSkillIds — without the cleanup-side spare, + // hand edits would be wiped here. + const SENTINEL = 'HAND_EDITED_BY_USER_SHOULD_SURVIVE'; + const handEditedBody = `---\ndescription: my custom description\n---\n\n${SENTINEL}\n`; + await fs.writeFile(commandFile, handEditedBody); + const result4 = await ideManager.setup('opencode', tempProjectDir, installedBmadDir, { + silent: true, + selectedModules: ['bmm'], + previousSkillIds: new Set(['bmad-master']), + }); + assert(result4.success === true, 'Fourth OpenCode install succeeds with hand-edited pointer present'); + const afterReinstall = await fs.readFile(commandFile, 'utf8'); + assert(afterReinstall.includes(SENTINEL), 'Hand-edited pointer survives a routine reinstall (cleanup spares active-manifest IDs)'); + await fs.remove(tempProjectDir); await fs.remove(path.dirname(installedBmadDir)); } catch (error) { @@ -2731,6 +2784,113 @@ async function runTests() { console.log(''); + // ============================================================ + // Test Suite 40c: OpenCode command pointers in multi-IDE batches + // ============================================================ + // Regression: when OpenCode is the *peer* in a setupBatch sharing + // .agents/skills (e.g. with openhands), the skill write is dedup-skipped + // but the per-IDE .opencode/commands/ pointers must still be generated. + // Symmetrically, partial uninstall while a peer remains must still clean + // up OpenCode's own command pointers. + console.log(`${colors.yellow}Test Suite 40c: OpenCode command pointers in shared-target batches${colors.reset}\n`); + + try { + clearCache(); + const platformCodes40c = await loadPlatformCodes(); + const opencodeTarget40c = platformCodes40c.platforms.opencode?.installer?.target_dir; + const openhandsTarget40c = platformCodes40c.platforms.openhands?.installer?.target_dir; + assert( + opencodeTarget40c === '.agents/skills' && openhandsTarget40c === '.agents/skills', + 'OpenCode and OpenHands share .agents/skills target_dir', + ); + + // Order A: opencode first → opencode is the writer. + const projA = await fs.mkdtemp(path.join(os.tmpdir(), 'bmad-opencode-batch-a-')); + const bmadA = await createTestBmadFixture(); + const mgrA = new IdeManager(); + await mgrA.ensureInitialized(); + const resultsA = await mgrA.setupBatch(['opencode', 'openhands'], projA, bmadA, { + silent: true, + selectedModules: ['core'], + }); + const cmdA = path.join(projA, '.opencode', 'commands', 'bmad-master.md'); + assert( + resultsA.every((r) => r.success === true), + 'opencode-first batch: all platforms succeed', + ); + assert(await fs.pathExists(cmdA), 'opencode-first batch: command pointer is created'); + + // Order B: openhands first → opencode is the peer (skipTarget=true). + // Without the fix, the early-return would bypass installCommandPointers. + const projB = await fs.mkdtemp(path.join(os.tmpdir(), 'bmad-opencode-batch-b-')); + const bmadB = await createTestBmadFixture(); + const mgrB = new IdeManager(); + await mgrB.ensureInitialized(); + const resultsB = await mgrB.setupBatch(['openhands', 'opencode'], projB, bmadB, { + silent: true, + selectedModules: ['core'], + }); + const cmdB = path.join(projB, '.opencode', 'commands', 'bmad-master.md'); + const opencodeResultB = resultsB.find((r) => r.ide === 'opencode'); + assert( + resultsB.every((r) => r.success === true), + 'openhands-first batch: all platforms succeed', + ); + assert( + opencodeResultB?.handlerResult?.results?.sharedTargetHandledByPeer === true, + 'openhands-first batch: opencode is marked sharedTargetHandledByPeer (skill write deduped)', + ); + assert(await fs.pathExists(cmdB), 'openhands-first batch: command pointer is generated even when skill write is deduped'); + + // Cleanup symmetry: uninstall opencode while openhands remains. + // Uses an in-project bmadDir so the cleanup path can compute removalSet + // from the manifest (the production layout). The cross-temp-dir fixture + // above can't exercise this — same constraint Test Suite 40 documents. + const projC = await fs.mkdtemp(path.join(os.tmpdir(), 'bmad-opencode-batch-c-')); + const bmadC = path.join(projC, '_bmad'); + await fs.ensureDir(path.join(bmadC, '_config')); + await fs.writeFile( + path.join(bmadC, '_config', 'skill-manifest.csv'), + 'canonicalId,name,description,module,path\n' + + '"bmad-master","bmad-master","Minimal test agent fixture","core","_bmad/core/bmad-master/SKILL.md"\n', + ); + const skillC = path.join(bmadC, 'core', 'bmad-master'); + await fs.ensureDir(skillC); + await fs.writeFile( + path.join(skillC, 'SKILL.md'), + ['---', 'name: bmad-master', 'description: Minimal test agent fixture', '---', '', 'You are a test agent.'].join('\n'), + ); + + const mgrC = new IdeManager(); + await mgrC.ensureInitialized(); + await mgrC.setupBatch(['openhands', 'opencode'], projC, bmadC, { + silent: true, + selectedModules: ['core'], + }); + const cmdC = path.join(projC, '.opencode', 'commands', 'bmad-master.md'); + assert(await fs.pathExists(cmdC), 'in-project fixture: pointer is generated for opencode peer'); + + const cleanupResultsC = await mgrC.cleanupByList(projC, ['opencode'], { + silent: true, + remainingIdes: ['openhands'], + }); + assert(cleanupResultsC[0].success !== false, 'opencode partial-uninstall reports success'); + const sharedSurvivesC = await fs.pathExists(path.join(projC, '.agents', 'skills', 'bmad-master', 'SKILL.md')); + assert(sharedSurvivesC, 'shared .agents/skills/ survives partial uninstall (peer still uses it)'); + assert(!(await fs.pathExists(cmdC)), 'opencode command pointer is removed on partial uninstall even when peer remains'); + + await fs.remove(projA).catch(() => {}); + await fs.remove(path.dirname(bmadA)).catch(() => {}); + await fs.remove(projB).catch(() => {}); + await fs.remove(path.dirname(bmadB)).catch(() => {}); + await fs.remove(projC).catch(() => {}); + } catch (error) { + console.log(`${colors.red}Test Suite 40c setup failed: ${error.message}${colors.reset}`); + failed++; + } + + console.log(''); + // ============================================================ // Test Suite 41: Custom-module skill ownership (non-bmad prefix) // ============================================================ diff --git a/tools/installer/ide/_config-driven.js b/tools/installer/ide/_config-driven.js index 737e10862..ad3fafd7a 100644 --- a/tools/installer/ide/_config-driven.js +++ b/tools/installer/ide/_config-driven.js @@ -6,6 +6,78 @@ const csv = require('csv-parse/sync'); const { BMAD_FOLDER_NAME } = require('./shared/path-utils'); const { getInstalledCanonicalIds, isBmadOwnedEntry } = require('./shared/installed-skills'); +// Reserved OpenCode slash commands. A skill whose canonicalId collides with +// one of these is skipped during command-pointer generation so it doesn't +// shadow a built-in. +const RESERVED_OPENCODE_COMMANDS = new Set([ + 'review', + 'commit', + 'init', + 'help', + 'skills', + 'fast', + 'compact', + 'clear', + 'undo', + 'redo', + 'edit', + 'editor', + 'exit', + 'quit', + 'theme', + 'config', + 'model', + 'session', +]); + +// Wrap a description for safe insertion into single-line YAML frontmatter. +// Leaves plain values untouched; double-quotes (and escapes) anything that +// could break YAML parsing or span multiple lines. +function yamlSafeSingleLine(value) { + const collapsed = String(value) + .replaceAll(/[\r\n]+/g, ' ') + .trim(); + const needsQuoting = /[:#'"\\]/.test(collapsed) || /^[!&*?|>%@`[{]/.test(collapsed); + if (!needsQuoting) return collapsed; + const escaped = collapsed.replaceAll('\\', '\\\\').replaceAll('"', String.raw`\"`); + return `"${escaped}"`; +} + +// Validate that a canonicalId is a safe basename — no path separators, no +// parent-dir traversal, no leading dots, only the character set we expect. +// Defense-in-depth: the manifest is trusted today, but the value flows +// directly into a file path and a malformed entry should not write outside +// the commands directory. +function isSafeCanonicalId(value) { + return typeof value === 'string' && /^[a-zA-Z0-9][a-zA-Z0-9_.-]*$/.test(value) && !value.includes('..'); +} + +// The exact body the installer would generate for a given description and +// canonicalId. Centralised so both the write and the freshness-check paths +// agree on the canonical form. +function buildCommandPointerBody(description, canonicalId) { + return `---\ndescription: ${yamlSafeSingleLine(description)}\n---\n\n@skills/${canonicalId}\n`; +} + +// Heuristic: does an existing pointer file look like our generator's output +// (and therefore safe to refresh) versus a user-modified file (which we +// preserve)? We check the body shape rather than full equality so that +// description-only edits in the manifest can propagate without trampling +// hand edits to the body. +function looksLikeGeneratorOutput(content, canonicalId) { + if (typeof content !== 'string') return false; + const trimmed = content.trim(); + // Must end with the exact reference line our generator writes. + if (!trimmed.endsWith(`@skills/${canonicalId}`)) return false; + // Must start with frontmatter containing exactly one description: line. + const fmMatch = trimmed.match(/^---\n([\S\s]*?)\n---\n/); + if (!fmMatch) return false; + const fmLines = fmMatch[1].split('\n').filter((l) => l.length > 0); + if (fmLines.length !== 1) return false; + if (!fmLines[0].startsWith('description:')) return false; + return true; +} + /** * Config-driven IDE setup handler * @@ -97,9 +169,15 @@ class ConfigDrivenIdeSetup { } // When a peer platform in the same install batch owns this target_dir, - // skip the skill write — the peer has already populated it. + // skip the skill write — the peer has already populated it. Command + // pointers, however, write to a separate per-IDE directory and must + // still be generated for this IDE; they are not deduped across peers. if (options.skipTarget) { - return { success: true, results: { skills: 0, sharedTargetHandledByPeer: true } }; + const results = { skills: 0, sharedTargetHandledByPeer: true }; + if (this.installerConfig.commands_target_dir) { + results.commands = await this.installCommandPointers(projectDir, bmadDir, this.installerConfig, options); + } + return { success: true, results }; } if (this.installerConfig.target_dir) { @@ -128,11 +206,141 @@ class ConfigDrivenIdeSetup { results.skills = await this.installVerbatimSkills(projectDir, bmadDir, targetPath, config); results.skillDirectories = this.skillWriteTracker.size; + if (config.commands_target_dir) { + results.commands = await this.installCommandPointers(projectDir, bmadDir, config, options); + } + await this.printSummary(results, target_dir, options); this.skillWriteTracker = null; return { success: true, results }; } + /** + * Generate per-skill command pointer files for IDEs that surface commands + * separately from skills (e.g. OpenCode's `.opencode/commands/.md`). + * + * Each pointer is a tiny markdown file whose body is `@skills/` + * so invoking `/` routes the user straight to the skill instead + * of forcing them through a `/skills` menu. + * + * Skips: + * - Names that collide with reserved built-in slash commands. + * - canonicalIds that aren't safe basename-only identifiers (defense + * against path traversal even though the manifest is currently trusted). + * - Existing files whose body looks user-modified (preserves hand edits); + * pointer files matching the generator pattern get overwritten so that + * description changes in skill-manifest.csv propagate on re-install. + * + * Per-file write failures are recorded and reported but do not abort the + * rest of the install — pointer files are a non-essential adjunct to the + * skill copy that already succeeded. + * + * @param {string} projectDir + * @param {string} bmadDir + * @param {Object} config - Installer config; reads commands_target_dir. + * @param {Object} options - Setup options. forceCommands overwrites existing + * files unconditionally (including hand-modified ones). + * @returns {Promise} { created, updated, skippedExisting, skippedCollision, skippedInvalidId, writeFailures, fallbackDescription } + */ + async installCommandPointers(projectDir, bmadDir, config, options = {}) { + const result = { + created: 0, + updated: 0, + skippedExisting: 0, + skippedCollision: 0, + skippedInvalidId: 0, + writeFailures: 0, + fallbackDescription: 0, + }; + + const csvPath = path.join(bmadDir, '_config', 'skill-manifest.csv'); + if (!(await fs.pathExists(csvPath))) return result; + + const commandsPath = path.join(projectDir, config.commands_target_dir); + await fs.ensureDir(commandsPath); + + const csvContent = await fs.readFile(csvPath, 'utf8'); + const records = csv.parse(csvContent, { columns: true, skip_empty_lines: true }); + + for (const record of records) { + const canonicalId = record.canonicalId; + if (!canonicalId) continue; + + // Defensive basename validation. canonicalId comes from a trusted + // manifest today, but the value flows directly into a file path — + // reject anything that could escape commands_target_dir. + if (!isSafeCanonicalId(canonicalId)) { + result.skippedInvalidId++; + continue; + } + + // Reserved-name guard is OpenCode-specific. Other adapters that opt + // into commands_target_dir later should declare their own reserved + // set rather than inheriting OpenCode's. + if (this.name === 'opencode' && RESERVED_OPENCODE_COMMANDS.has(canonicalId)) { + result.skippedCollision++; + continue; + } + + let description = (record.description || '').trim(); + if (!description) { + description = `Run the ${canonicalId} skill`; + result.fallbackDescription++; + } + + const body = buildCommandPointerBody(description, canonicalId); + const commandFile = path.join(commandsPath, `${canonicalId}.md`); + + // If a pointer file already exists, decide whether to overwrite based + // on whether it looks like generator output (description-only diff) or + // a user-modified file. forceCommands overrides this protection. + if (!options.forceCommands && (await fs.pathExists(commandFile))) { + let existing; + try { + existing = await fs.readFile(commandFile, 'utf8'); + } catch { + // Treat unreadable as user-owned and skip — safer than overwriting. + result.skippedExisting++; + continue; + } + + if (existing === body) { + // No-op idempotent re-run. + result.skippedExisting++; + continue; + } + if (looksLikeGeneratorOutput(existing, canonicalId)) { + // Description (or other generated bit) has changed; refresh in place. + try { + await fs.writeFile(commandFile, body, 'utf8'); + result.updated++; + } catch (error) { + result.writeFailures++; + if (!options.silent) { + await prompts.log.warn(`Failed to update command pointer ${canonicalId}.md: ${error.message}`); + } + } + continue; + } + // Hand-modified pointer — preserve it. + result.skippedExisting++; + continue; + } + + try { + await fs.writeFile(commandFile, body, 'utf8'); + result.created++; + } catch (error) { + result.writeFailures++; + if (!options.silent) { + await prompts.log.warn(`Failed to write command pointer ${canonicalId}.md: ${error.message}`); + } + } + } + + return result; + } + /** * Install verbatim native SKILL.md directories from skill-manifest.csv. * Copies the entire source directory as-is into the IDE skill directory. @@ -207,6 +415,18 @@ class ConfigDrivenIdeSetup { if (count > 0) { await prompts.log.success(`${this.name} configured: ${count} skills → ${targetDir}`); } + const cmd = results.commands; + if (cmd && (cmd.created > 0 || cmd.updated > 0) && this.installerConfig?.commands_target_dir) { + const total = cmd.created + cmd.updated; + const detail = cmd.updated > 0 ? `${cmd.created} new, ${cmd.updated} refreshed` : `${total}`; + await prompts.log.success(`${this.name} commands: ${detail} → ${this.installerConfig.commands_target_dir}`); + if (cmd.skippedCollision > 0) { + await prompts.log.message(` (${cmd.skippedCollision} skipped — name collides with reserved slash command)`); + } + if (cmd.writeFailures > 0) { + await prompts.log.warn(` (${cmd.writeFailures} pointer writes failed — see warnings above)`); + } + } } /** @@ -247,6 +467,28 @@ class ConfigDrivenIdeSetup { await this.cleanupRovoDevPrompts(projectDir, options); } + // Clean generated command pointer files in commands_target_dir. + // Mirrors target_dir cleanup so uninstalls and skill removals don't + // leave dangling / commands pointing at missing skills. + // Runs regardless of skipTarget — command pointers live in a per-IDE + // directory and are not deduped across peers, so a peer-owned shared + // skills directory does not protect this IDE's command pointers from + // cleanup. The "currently active" set is passed so install-flow cleanup + // (where removalSet contains skills that will be re-added moments later) + // doesn't trample hand-edited pointers; install-flow cleanup will only + // delete pointers for skills that are not in the new manifest. + if (this.installerConfig?.commands_target_dir) { + // In the install/update flow (signal: previousSkillIds was passed), + // spare pointers whose canonicalId is still in the manifest so hand + // edits survive a routine reinstall. In the uninstall flow (no + // previousSkillIds — full uninstall or per-IDE removal via + // cleanupByList), don't spare anything; the IDE itself is going away, + // so its pointers should go with it. + const isInstallFlow = options.previousSkillIds && options.previousSkillIds.size > 0; + const activeSkillIds = isInstallFlow ? await this._readActiveSkillIds(resolvedBmadDir) : new Set(); + await this.cleanupCommandPointers(projectDir, this.installerConfig.commands_target_dir, options, removalSet, activeSkillIds); + } + // Skip target_dir cleanup when a peer platform owns this directory // (set during dedup'd install or when uninstalling one of several // platforms that share the same target_dir). @@ -346,6 +588,86 @@ class ConfigDrivenIdeSetup { } } + /** + * Cleanup generated command pointer files for entries in removalSet. + * Symmetric counterpart to installCommandPointers — removes .md + * files whose canonicalId is in the set. Removes the commands directory + * entirely if it ends up empty. + * @param {string} projectDir + * @param {string} commandsTargetDir - Relative dir (e.g. .opencode/commands) + * @param {Object} options + * @param {Set} removalSet - canonicalIds whose pointer files to remove + * @param {Set} [activeSkillIds] - canonicalIds present in the + * current manifest. Pointers for IDs in this set are spared so an + * install-flow cleanup (where removalSet === previousSkillIds and the + * same skills are about to be re-installed) doesn't wipe hand-edited + * pointer files. Pass an empty set or omit to delete every match in + * removalSet (uninstall flow). + */ + async cleanupCommandPointers(projectDir, commandsTargetDir, options = {}, removalSet = new Set(), activeSkillIds = new Set()) { + if (!removalSet || removalSet.size === 0) return; + + const commandsPath = path.join(projectDir, commandsTargetDir); + if (!(await fs.pathExists(commandsPath))) return; + + let entries; + try { + entries = await fs.readdir(commandsPath); + } catch { + return; + } + + for (const entry of entries) { + if (!entry.endsWith('.md')) continue; + const canonicalId = entry.slice(0, -3); + if (!removalSet.has(canonicalId)) continue; + // Spare pointers for skills that are still in the manifest; the + // install pass will refresh them in place if their content has gone + // stale, while preserving hand edits. + if (activeSkillIds.has(canonicalId)) continue; + try { + await fs.remove(path.join(commandsPath, entry)); + } catch { + // Skip files we can't remove. + } + } + + // Remove the commands directory if we emptied it. + try { + const remaining = await fs.readdir(commandsPath); + if (remaining.length === 0) { + await fs.remove(commandsPath); + } + } catch { + // Directory may already be gone. + } + } + + /** + * Read the canonicalIds currently present in the skill-manifest.csv. + * Used by cleanup to distinguish "re-install of an existing skill" + * (preserve pointer) from "skill truly being removed" (delete pointer). + * @param {string|null} bmadDir + * @returns {Promise>} + */ + async _readActiveSkillIds(bmadDir) { + const ids = new Set(); + if (!bmadDir) return ids; + const csvPath = path.join(bmadDir, '_config', 'skill-manifest.csv'); + if (!(await fs.pathExists(csvPath))) return ids; + try { + const content = await fs.readFile(csvPath, 'utf8'); + const records = csv.parse(content, { columns: true, skip_empty_lines: true }); + for (const record of records) { + if (record.canonicalId) ids.add(record.canonicalId); + } + } catch { + // Manifest unreadable — return an empty set so cleanup falls back to + // the conservative "delete what removalSet says" behavior. + } + return ids; + } + /** * Cleanup a specific target directory. * When removalSet is provided, only removes entries in that set. diff --git a/tools/installer/ide/platform-codes.yaml b/tools/installer/ide/platform-codes.yaml index 0f49a7fbe..78ca1d271 100644 --- a/tools/installer/ide/platform-codes.yaml +++ b/tools/installer/ide/platform-codes.yaml @@ -222,6 +222,7 @@ platforms: installer: target_dir: .agents/skills global_target_dir: ~/.agents/skills + commands_target_dir: .opencode/commands openhands: name: "OpenHands"