bmad-studio 0.2.0 → 1.0.0

package/packages/server/dist/plugins/modules-plugin.js

@@ -1,46 +1,402 @@
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
-import { execSync } from 'node:child_process';
+import { execSync, spawnSync } from 'node:child_process';
 import yaml from 'js-yaml';
 import { ValidationError, ConflictError, NotFoundError } from '../core/errors.js';
-function readManifest(manifestPath) {
-    const content = fs.readFileSync(manifestPath, 'utf-8');
-    return yaml.load(content);
-}
-function writeManifest(manifestPath, manifest) {
-    fs.writeFileSync(manifestPath, yaml.dump(manifest, { lineWidth: -1 }), 'utf-8');
-}
+import { fetchAndCacheRegistryIndex, isRegistryCacheStale, readCachedRegistryIndex, } from '../core/module-registry.js';
+import { generateIdeSkillsForModule, removeIdeSkillsForModule, scanEntities, scanEntityDirs, } from '../core/ide-skill-generator.js';
+import { copyDirThroughWriteService, downloadGithubTarball, extractZipUpload, findCrossReferences, isPlausibleModuleDir, parseGithubSource, readManifestSafe, readOutputFolder, runVariableSubstitution, validateVariables, writeManifestThroughWriteService, } from '../core/module-installer.js';
+import { deleteDirectory, writeFile } from '../core/write-service.js';
+import { parseModuleYaml } from '../parsers/module-yaml-parser.js';
 const MODULE_NAME_RE = /^[a-z][a-z0-9-]*$/;
-function copyDirRecursive(src, dest) {
-    if (!fs.existsSync(src))
-        return;
-    fs.mkdirSync(dest, { recursive: true });
-    for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
-        const srcPath = path.join(src, entry.name);
-        const destPath = path.join(dest, entry.name);
-        if (entry.isDirectory()) {
-            copyDirRecursive(srcPath, destPath);
+export async function modulesPlugin(app) {
+    const PREVIEW_CACHE_TTL_MS = 5 * 60 * 1000;
+    const previewCache = new Map();
+    function previewCacheKey(ghSource) {
+        return `${ghSource.owner}/${ghSource.repo}@${ghSource.branch ?? 'main'}${ghSource.subpath ? `/${ghSource.subpath}` : ''}`;
+    }
+    function getPreviewCacheEntry(key) {
+        const entry = previewCache.get(key);
+        if (!entry)
+            return null;
+        if (Date.now() - entry.fetchedAt > PREVIEW_CACHE_TTL_MS) {
+            try {
+                fs.rmSync(entry.tmpDir, { recursive: true, force: true });
+            }
+            catch {
+                /* ignore cleanup errors */
+            }
+            previewCache.delete(key);
+            return null;
         }
-        else {
-            fs.copyFileSync(srcPath, destPath);
+        return entry;
+    }
+    // Story 17.3 — Clean-slate remove helper. Called by each install branch when
+    // the destination directory already exists so the install can proceed as a
+    // silent upgrade rather than throwing 409.
+    // Throws ValidationError if the module is built-in (cannot be replaced) or
+    // if any I/O step fails. Safe to call when the module dir doesn't exist yet
+    // (all steps guard with existsSync / nullish checks).
+    function cleanRemoveModule(moduleCode, bmadDir, manifestPath) {
+        const moduleDir = path.join(bmadDir, moduleCode);
+        const manifest = readManifestSafe(manifestPath);
+        const entry = manifest?.modules.find((m) => m.name === moduleCode);
+        if (entry?.source === 'built-in') {
+            throw new ValidationError(`Cannot reinstall built-in module "${moduleCode}"`);
+        }
+        // 1. Remove IDE skill launchers
+        if (manifest) {
+            const r = removeIdeSkillsForModule(app.fileStore.projectRoot, moduleCode, manifest, app.fileStore.studioDir);
+            if (!r.ok)
+                throw new ValidationError(r.error);
+        }
+        // 2. Delete the module directory
+        if (fs.existsSync(moduleDir)) {
+            const r = deleteDirectory(moduleDir, app.fileStore.studioDir);
+            if (!r.ok)
+                throw new ValidationError(r.error);
+        }
+        // 3. Remove the manifest entry so the incoming install writes a fresh one
+        if (manifest) {
+            manifest.modules = manifest.modules.filter((m) => m.name !== moduleCode);
+            const wrote = writeManifestThroughWriteService(manifestPath, manifest, app.fileStore.studioDir, app.fileStore);
+            if (!wrote.ok)
+                throw new ValidationError(wrote.error);
         }
     }
-}
-export async function modulesPlugin(app) {
-    // Install module from npm package
+    // Story 15.9 — Read-only preview endpoint. Fetches a source (local or github)
+    // and returns the parsed module.yaml + entity counts WITHOUT installing anything.
+    // For github sources, the downloaded tarball is cached for 5 minutes so the
+    // subsequent install call can reuse it without re-downloading.
+    app.post('/api/modules/preview-source', async (request) => {
+        if (!('fileStore' in app)) {
+            throw new ValidationError('No project detected');
+        }
+        const body = request.body;
+        const source = body?.source;
+        if (!source || !source.type || !source.value) {
+            throw new ValidationError('Request body must include { source: { type, value } }');
+        }
+        let stagedRoot;
+        if (source.type === 'local') {
+            stagedRoot = path.isAbsolute(source.value)
+                ? source.value
+                : path.join(app.fileStore.projectRoot, source.value);
+        }
+        else if (source.type === 'github') {
+            let ghSource;
+            try {
+                ghSource = parseGithubSource(source.value);
+            }
+            catch (err) {
+                throw new ValidationError(err instanceof Error ? err.message : String(err));
+            }
+            const cacheKey = previewCacheKey(ghSource);
+            let entry = getPreviewCacheEntry(cacheKey);
+            if (!entry) {
+                let downloaded;
+                try {
+                    downloaded = await downloadGithubTarball(ghSource);
+                }
+                catch (err) {
+                    throw new ValidationError(err instanceof Error ? err.message : String(err));
+                }
+                entry = {
+                    extractedRoot: downloaded.extractedRoot,
+                    tmpDir: downloaded.tmpDir,
+                    resolvedBranch: downloaded.resolvedBranch,
+                    fetchedAt: Date.now(),
+                };
+                previewCache.set(cacheKey, entry);
+            }
+            stagedRoot = ghSource.subpath
+                ? path.join(entry.extractedRoot, ghSource.subpath)
+                : entry.extractedRoot;
+            // Note: no try/finally cleanup here — the tmpDir lives in previewCache and is
+            // cleaned up on TTL expiry or when the install endpoint consumes it.
+        }
+        else {
+            throw new ValidationError(`preview-source does not support source type "${source.type}". Use "local" or "github".`);
+        }
+        if (!isPlausibleModuleDir(stagedRoot)) {
+            throw new ValidationError('Source does not look like a BMAD module — expected module.yaml or one of agents/skills/workflows/tasks');
+        }
+        const parsed = parseModuleYaml(stagedRoot);
+        if (!parsed.ok)
+            throw new ValidationError(parsed.error);
+        const counts = {
+            agents: scanEntities(path.join(stagedRoot, 'agents'), '.md').length,
+            workflows: scanEntityDirs(path.join(stagedRoot, 'workflows')).length,
+            tasks: scanEntityDirs(path.join(stagedRoot, 'tasks')).length,
+        };
+        const bmadDir = path.join(app.fileStore.projectRoot, '_bmad');
+        const existingDir = path.join(bmadDir, parsed.data.code);
+        const willReplace = fs.existsSync(existingDir);
+        return { ok: true, moduleYaml: parsed.data, counts, willReplace };
+    });
+    // Polymorphic install endpoint — accepts npm | local | github source types via
+    // { source: { type, value }, variables? }, plus the legacy { packageName } shape.
+    // Zip uploads go to a separate multipart route POST /api/modules/install/upload (Story 15.4).
     app.post('/api/modules/install', async (request, reply) => {
         if (!('fileStore' in app)) {
             throw new ValidationError('No project detected');
         }
         const body = request.body;
-        const packageName = body.packageName?.trim();
-        if (!packageName) {
-            throw new ValidationError('Package name is required');
+        // Defensive guard: if the request body is missing (e.g. a multipart upload sent
+        // to this JSON-only route — multipart goes to /upload), fail loudly with a 422
+        // instead of an unhandled TypeError. AC-15.4.11.
+        if (!body || typeof body !== 'object') {
+            throw new ValidationError('Request body must be JSON. For zip uploads, POST to /api/modules/install/upload instead.');
+        }
+        // TD-22 — discriminate source vs legacy. Prefer `source` if both are present.
+        let source;
+        if (body.source) {
+            source = body.source;
+            if (body.packageName) {
+                request.log.warn({ packageName: body.packageName }, 'Both `source` and `packageName` provided to /api/modules/install — using `source`');
+            }
+        }
+        else if (body.packageName) {
+            const pkg = body.packageName.trim();
+            if (!pkg) {
+                throw new ValidationError('Package name is required');
+            }
+            source = { type: 'npm', value: pkg };
         }
+        else {
+            throw new ValidationError('Either `source` or `packageName` is required');
+        }
+        // Story 15.5 — variables are now consumed (not just threaded through).
+        const variables = body.variables ?? {};
         const bmadDir = path.join(app.fileStore.projectRoot, '_bmad');
         const manifestPath = path.join(bmadDir, '_config', 'manifest.yaml');
-        const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'bmad-install-'));
+        // Hard requirement (AC-15.2.9 / finding #8): every install branch needs an existing manifest.
+        // Without it, the installed module would be invisible to GET /api/modules.
+        if (!fs.existsSync(manifestPath)) {
+            throw new ValidationError('Cannot install module: missing _bmad/_config/manifest.yaml. Run `npx bmad-method install` to initialise the project first.');
+        }
+        // Story 15.5 — validate variables BEFORE any source-type branching so bad input
+        // fails fast without wasting CPU on a download/extraction.
+        const varValidation = validateVariables(variables);
+        if (!varValidation.ok)
+            throw new ValidationError(varValidation.error);
+        // Helper to build the substitution context for a given module code. Used by every branch.
+        const makeSubContext = (moduleCode) => ({
+            moduleCode,
+            projectRoot: app.fileStore.projectRoot,
+            outputFolder: readOutputFolder(app.fileStore.projectRoot),
+            variables,
+        });
+        // Helper to run the IDE skill generator for a freshly-installed module and
+        // return per-IDE counts for the response shape (Story 15.6 / AC-15.6.8).
+        // Re-reads the manifest to get the latest `ides[]` after the manifest update.
+        const runGenerator = (moduleCode) => {
+            const updatedManifest = readManifestSafe(manifestPath);
+            if (!updatedManifest)
+                return {};
+            const genResult = generateIdeSkillsForModule(app.fileStore.projectRoot, moduleCode, updatedManifest, app.fileStore.studioDir, app.fileStore);
+            if (!genResult.ok)
+                throw new ValidationError(genResult.error);
+            const counts = {};
+            for (const [ide, skills] of Object.entries(genResult.skillsByIde)) {
+                counts[ide] = skills.length;
+            }
+            return counts;
+        };
+        // ─────────────────────────────────────────────────────────────────────────
+        // local source
+        // ─────────────────────────────────────────────────────────────────────────
+        if (source.type === 'local') {
+            const sourcePath = path.isAbsolute(source.value)
+                ? source.value
+                : path.join(app.fileStore.projectRoot, source.value);
+            if (!isPlausibleModuleDir(sourcePath)) {
+                throw new ValidationError(`Path "${sourcePath}" does not look like a BMAD module — expected module.yaml or one of agents/skills/workflows/tasks`);
+            }
+            const parsed = parseModuleYaml(sourcePath);
+            if (!parsed.ok)
+                throw new ValidationError(parsed.error);
+            const moduleCode = parsed.data.code;
+            const destDir = path.join(bmadDir, moduleCode);
+            // Story 17.3 — clean-slate re-install: silently remove any existing copy before writing.
+            if (fs.existsSync(destDir)) {
+                cleanRemoveModule(moduleCode, bmadDir, manifestPath);
+            }
+            const copyResult = copyDirThroughWriteService(sourcePath, destDir, app.fileStore.studioDir, app.fileStore);
+            if (!copyResult.ok)
+                throw new ValidationError(copyResult.error);
+            // Story 15.5 — substitute placeholders in installed text files BEFORE updating the manifest.
+            const subResult = runVariableSubstitution(destDir, makeSubContext(moduleCode), app.fileStore.studioDir, app.fileStore);
+            if (!subResult.ok)
+                throw new ValidationError(subResult.error);
+            // Update manifest (guaranteed to exist by the check above)
+            const manifest = readManifestSafe(manifestPath);
+            const now = new Date().toISOString();
+            const existing = manifest.modules.find((m) => m.name === moduleCode);
+            if (existing) {
+                existing.lastUpdated = now;
+                existing.source = 'local';
+                existing.npmPackage = null;
+                existing.repoUrl = sourcePath;
+            }
+            else {
+                manifest.modules.push({
+                    name: moduleCode,
+                    version: parsed.data.version ?? '1.0.0',
+                    installDate: now,
+                    lastUpdated: now,
+                    source: 'local',
+                    npmPackage: null,
+                    repoUrl: sourcePath,
+                });
+            }
+            const wrote = writeManifestThroughWriteService(manifestPath, manifest, app.fileStore.studioDir, app.fileStore);
+            if (!wrote.ok)
+                throw new ValidationError(wrote.error);
+            // Story 15.6 — generate IDE launchers AFTER the manifest is committed.
+            // A failure here leaves the user with an installed module + no launchers;
+            // recovery is the "Regenerate IDE skills" button (Story 15.8).
+            const skillsGenerated = runGenerator(moduleCode);
+            app.fileStore.rebuild();
+            reply.status(200);
+            return {
+                ok: true,
+                modules: [moduleCode],
+                filesCopied: { text: copyResult.textCount, binary: copyResult.binaryCount },
+                skillsGenerated,
+            };
+        }
+        // ─────────────────────────────────────────────────────────────────────────
+        // github source
+        // ─────────────────────────────────────────────────────────────────────────
+        if (source.type === 'github') {
+            // parseGithubSource throws plain Error on invalid input — convert to ValidationError.
+            let ghSource;
+            try {
+                ghSource = parseGithubSource(source.value);
+            }
+            catch (err) {
+                throw new ValidationError(err instanceof Error ? err.message : String(err));
+            }
+            // Story 15.9 — check previewCache before downloading. If the user clicked
+            // "Fetch" then "Install" in quick succession the tarball is already on disk;
+            // reuse it and skip the second download. Consume the cache entry (delete it)
+            // so a future preview call re-downloads fresh content.
+            const cacheKey = previewCacheKey(ghSource);
+            const cachedEntry = getPreviewCacheEntry(cacheKey);
+            let extractedRoot;
+            let tmpDir;
+            let resolvedBranch;
+            if (cachedEntry) {
+                previewCache.delete(cacheKey); // consumed — install now owns cleanup
+                extractedRoot = cachedEntry.extractedRoot;
+                tmpDir = cachedEntry.tmpDir;
+                resolvedBranch = cachedEntry.resolvedBranch;
+            }
+            else {
+                // No cache hit — download fresh.
+                let downloaded;
+                try {
+                    downloaded = await downloadGithubTarball(ghSource);
+                }
+                catch (err) {
+                    throw new ValidationError(err instanceof Error ? err.message : String(err));
+                }
+                extractedRoot = downloaded.extractedRoot;
+                tmpDir = downloaded.tmpDir;
+                resolvedBranch = downloaded.resolvedBranch;
+            }
+            try {
+                // Navigate to the optional subpath
+                const moduleSrc = ghSource.subpath
+                    ? path.join(extractedRoot, ghSource.subpath)
+                    : extractedRoot;
+                if (!isPlausibleModuleDir(moduleSrc)) {
+                    throw new ValidationError(`${ghSource.owner}/${ghSource.repo}${ghSource.subpath ? `/${ghSource.subpath}` : ''} does not look like a BMAD module`);
+                }
+                const parsed = parseModuleYaml(moduleSrc);
+                if (!parsed.ok)
+                    throw new ValidationError(parsed.error);
+                const moduleCode = parsed.data.code;
+                const destDir = path.join(bmadDir, moduleCode);
+                // Story 17.3 — clean-slate re-install.
+                if (fs.existsSync(destDir)) {
+                    cleanRemoveModule(moduleCode, bmadDir, manifestPath);
+                }
+                const copyResult = copyDirThroughWriteService(moduleSrc, destDir, app.fileStore.studioDir, app.fileStore);
+                if (!copyResult.ok)
+                    throw new ValidationError(copyResult.error);
+                // Story 15.5 — substitute placeholders before manifest update
+                const subResult = runVariableSubstitution(destDir, makeSubContext(moduleCode), app.fileStore.studioDir, app.fileStore);
+                if (!subResult.ok)
+                    throw new ValidationError(subResult.error);
+                // Update manifest (guaranteed to exist by the check at the top of the handler)
+                const manifest = readManifestSafe(manifestPath);
+                const now = new Date().toISOString();
+                const repoUrl = `https://github.com/${ghSource.owner}/${ghSource.repo}`;
+                const existing = manifest.modules.find((m) => m.name === moduleCode);
+                if (existing) {
+                    existing.lastUpdated = now;
+                    existing.source = 'github';
+                    existing.repoUrl = repoUrl;
+                    existing.npmPackage = null;
+                }
+                else {
+                    manifest.modules.push({
+                        name: moduleCode,
+                        version: parsed.data.version ?? '1.0.0',
+                        installDate: now,
+                        lastUpdated: now,
+                        source: 'github',
+                        npmPackage: null,
+                        repoUrl,
+                    });
+                }
+                const wrote = writeManifestThroughWriteService(manifestPath, manifest, app.fileStore.studioDir, app.fileStore);
+                if (!wrote.ok)
+                    throw new ValidationError(wrote.error);
+                // Story 15.6 — generate IDE launchers after manifest commit
+                const skillsGenerated = runGenerator(moduleCode);
+                app.fileStore.rebuild();
+                reply.status(200);
+                return {
+                    ok: true,
+                    modules: [moduleCode],
+                    filesCopied: { text: copyResult.textCount, binary: copyResult.binaryCount },
+                    source: { type: 'github', value: source.value, branch: resolvedBranch },
+                    skillsGenerated,
+                };
+            }
+            finally {
+                try {
+                    fs.rmSync(tmpDir, { recursive: true, force: true });
+                }
+                catch {
+                    /* ignore cleanup errors */
+                }
+            }
+        }
+        // ─────────────────────────────────────────────────────────────────────────
+        // Guard: reject unknown source types before falling through to npm.
+        // The InstallSource union only allows 'npm'|'local'|'github', but the body
+        // is untyped at the HTTP boundary — 'zip' or any other string would silently
+        // run `npm pack <value>` without this check.
+        // Cast to string to sidestep TS control-flow narrowing (source is already
+        // narrowed to the npm variant by this point, so source.type === 'npm' always,
+        // but this guard provides a runtime safety net for unexpected payloads).
+        // ─────────────────────────────────────────────────────────────────────────
+        const sourceTypeStr = source.type;
+        if (sourceTypeStr !== 'npm') {
+            throw new ValidationError(`Unknown source type "${sourceTypeStr}". Valid types: local, github, npm. For zip uploads use POST /api/modules/install/upload.`);
+        }
+        // ─────────────────────────────────────────────────────────────────────────
+        // npm source — refactored to route writes through WriteService
+        // ─────────────────────────────────────────────────────────────────────────
+        const packageName = source.value;
+        // TD-20 — realpathSync resolves the macOS /var → /private/var symlink so
+        // path comparisons inside the install loop are stable.
+        const tmpDir = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), 'bmad-install-')));
         try {
             // 1. Download the package tarball via npm pack
             execSync(`npm pack ${packageName} --pack-destination ${tmpDir}`, {
@@ -51,7 +407,7 @@ export async function modulesPlugin(app) {
             // 2. Find the tarball file
             const tarballs = fs.readdirSync(tmpDir).filter((f) => f.endsWith('.tgz'));
             if (tarballs.length === 0) {
-                return reply.status(400).send({ ok: false, error: 'No tarball downloaded' });
+                throw new ValidationError('No tarball downloaded');
             }
             const tarballPath = path.join(tmpDir, tarballs[0]);
             // 3. Extract the tarball
@@ -67,60 +423,95 @@ export async function modulesPlugin(app) {
             const packageDir = path.join(extractDir, 'package');
             const bmadSrcDir = path.join(packageDir, '_bmad');
             if (!fs.existsSync(bmadSrcDir)) {
-                return reply.status(400).send({
-                    ok: false,
-                    error: `Package "${packageName}" does not contain a _bmad/ directory`,
-                });
+                throw new ValidationError(`Package "${packageName}" does not contain a _bmad/ directory`);
             }
             // 5. Copy module directories from the package's _bmad/ into the project's _bmad/
+            // Routes through WriteService for text files, byte-copies binaries (TD-16).
             const installedModules = [];
+            let totalText = 0;
+            let totalBinary = 0;
             for (const entry of fs.readdirSync(bmadSrcDir, { withFileTypes: true })) {
                 if (entry.isDirectory() && entry.name !== '_config') {
                     const srcModuleDir = path.join(bmadSrcDir, entry.name);
-                    const destModuleDir = path.join(bmadDir, entry.name);
-                    copyDirRecursive(srcModuleDir, destModuleDir);
-                    installedModules.push(entry.name);
+                    // Read module.yaml for the authoritative module code (AC-15.2.8).
+                    // Falls back to the directory name if module.yaml is absent or doesn't
+                    // declare a code field — consistent with local/github/zip branches.
+                    const parsedMod = parseModuleYaml(srcModuleDir);
+                    if (!parsedMod.ok)
+                        throw new ValidationError(parsedMod.error);
+                    const moduleCode = parsedMod.data.code;
+                    const destModuleDir = path.join(bmadDir, moduleCode);
+                    // Story 17.3 — clean-slate re-install.
+                    if (fs.existsSync(destModuleDir)) {
+                        cleanRemoveModule(moduleCode, bmadDir, manifestPath);
+                    }
+                    const copyResult = copyDirThroughWriteService(srcModuleDir, destModuleDir, app.fileStore.studioDir, app.fileStore);
+                    if (!copyResult.ok)
+                        throw new ValidationError(copyResult.error);
+                    totalText += copyResult.textCount;
+                    totalBinary += copyResult.binaryCount;
+                    // Story 15.5 — substitute placeholders in each installed module dir.
+                    const subResult = runVariableSubstitution(destModuleDir, makeSubContext(moduleCode), app.fileStore.studioDir, app.fileStore);
+                    if (!subResult.ok)
+                        throw new ValidationError(subResult.error);
+                    installedModules.push(moduleCode);
                 }
             }
             if (installedModules.length === 0) {
-                return reply.status(400).send({
-                    ok: false,
-                    error: `Package "${packageName}" has no module directories in _bmad/`,
-                });
+                throw new ValidationError(`Package "${packageName}" has no module directories in _bmad/`);
             }
-            // 6. Update manifest.yaml with new module entries
-            if (fs.existsSync(manifestPath)) {
-                const manifest = readManifest(manifestPath);
-                const now = new Date().toISOString();
-                for (const moduleName of installedModules) {
-                    const existing = manifest.modules.find((m) => m.name === moduleName);
-                    if (existing) {
-                        existing.lastUpdated = now;
-                        existing.npmPackage = packageName;
-                        existing.source = 'npm';
-                    }
-                    else {
-                        manifest.modules.push({
-                            name: moduleName,
-                            version: '1.0.0',
-                            installDate: now,
-                            lastUpdated: now,
-                            source: 'npm',
-                            npmPackage: packageName,
-                            repoUrl: null,
-                        });
-                    }
+            // 6. Update manifest.yaml with new module entries (snapshot via WriteService)
+            const manifest = readManifestSafe(manifestPath);
+            const now = new Date().toISOString();
+            for (const moduleName of installedModules) {
+                const existing = manifest.modules.find((m) => m.name === moduleName);
+                if (existing) {
+                    existing.lastUpdated = now;
+                    existing.npmPackage = packageName;
+                    existing.source = 'npm';
+                }
+                else {
+                    manifest.modules.push({
+                        name: moduleName,
+                        version: '1.0.0',
+                        installDate: now,
+                        lastUpdated: now,
+                        source: 'npm',
+                        npmPackage: packageName,
+                        repoUrl: null,
+                    });
+                }
+            }
+            const wrote = writeManifestThroughWriteService(manifestPath, manifest, app.fileStore.studioDir, app.fileStore);
+            if (!wrote.ok)
+                throw new ValidationError(wrote.error);
+            // Story 15.6 — generate IDE launchers for each installed module.
+            // The npm branch installs MULTIPLE modules; sum the per-IDE counts.
+            const skillsGenerated = {};
+            for (const moduleName of installedModules) {
+                const counts = runGenerator(moduleName);
+                for (const [ide, count] of Object.entries(counts)) {
+                    skillsGenerated[ide] = (skillsGenerated[ide] ?? 0) + count;
                 }
-                writeManifest(manifestPath, manifest);
             }
             // 7. Rebuild file store
             app.fileStore.rebuild();
             reply.status(200);
-            return { ok: true, modules: installedModules };
+            return {
+                ok: true,
+                modules: installedModules,
+                filesCopied: { text: totalText, binary: totalBinary },
+                skillsGenerated,
+            };
         }
         catch (err) {
-            const message = err instanceof Error ? err.message : 'Installation failed';
-            return reply.status(400).send({ ok: false, error: message });
+            // Rethrow known error types so the global handler produces the correct
+            // status (422 for ValidationError, 409 for ConflictError). Wrap any
+            // unexpected error (e.g. execSync failure) as a ValidationError.
+            if (err instanceof ValidationError || err instanceof ConflictError || err instanceof NotFoundError) {
+                throw err;
+            }
+            throw new ValidationError(err instanceof Error ? err.message : 'Installation failed');
         }
         finally {
             // Cleanup temp directory
@@ -132,6 +523,141 @@ export async function modulesPlugin(app) {
             }
         }
     });
+    // Multipart zip upload route — Story 15.4. Separate from POST /api/modules/install
+    // because multipart bodies and JSON bodies have different shapes inside Fastify;
+    // splitting the routes is cleaner than content-type discrimination inside one handler.
+    app.post('/api/modules/install/upload', async (request, reply) => {
+        if (!('fileStore' in app)) {
+            throw new ValidationError('No project detected');
+        }
+        // Iterate all multipart parts in stream order so the `variables` field is
+        // captured regardless of whether it arrives before or after the file part.
+        // Using request.parts() instead of request.file() avoids the ordering bug
+        // where data.fields is only populated for fields that precede the file.
+        let zipBuffer = null;
+        let uploadVariables = {};
+        for await (const part of request.parts()) {
+            if (part.type === 'file') {
+                zipBuffer = await part.toBuffer();
+            }
+            else if (part.type === 'field' && part.fieldname === 'variables') {
+                const raw = part.value;
+                if (typeof raw === 'string') {
+                    try {
+                        const parsed = JSON.parse(raw);
+                        if (parsed && typeof parsed === 'object') {
+                            uploadVariables = parsed;
+                        }
+                    }
+                    catch {
+                        throw new ValidationError('Invalid `variables` field — expected JSON object');
+                    }
+                }
+            }
+        }
+        if (!zipBuffer) {
+            throw new ValidationError('No zip file uploaded');
+        }
+        const buffer = zipBuffer;
+        const varValidation = validateVariables(uploadVariables);
+        if (!varValidation.ok)
+            throw new ValidationError(varValidation.error);
+        const bmadDir = path.join(app.fileStore.projectRoot, '_bmad');
+        const manifestPath = path.join(bmadDir, '_config', 'manifest.yaml');
+        // Manifest existence guard (AC-15.4.9). Runs BEFORE extractZipUpload so a
+        // misconfigured project doesn't waste CPU on adm-zip extraction.
+        if (!fs.existsSync(manifestPath)) {
+            throw new ValidationError('Cannot install module: missing _bmad/_config/manifest.yaml. Run `npx bmad-method install` to initialise the project first.');
+        }
+        // extractZipUpload throws plain Error on failure (malformed zip, zip-slip, etc.)
+        // Convert to ValidationError so the user sees a 422 with a clean message.
+        let extracted;
+        try {
+            extracted = await extractZipUpload(buffer);
+        }
+        catch (err) {
+            throw new ValidationError(err instanceof Error ? err.message : String(err));
+        }
+        const { extractedRoot, tmpDir } = extracted;
+        try {
+            if (!isPlausibleModuleDir(extractedRoot)) {
+                throw new ValidationError('Uploaded zip does not look like a BMAD module');
+            }
+            const parsed = parseModuleYaml(extractedRoot);
+            if (!parsed.ok)
+                throw new ValidationError(parsed.error);
+            const moduleCode = parsed.data.code;
+            const destDir = path.join(bmadDir, moduleCode);
+            // Story 17.3 — clean-slate re-install.
+            if (fs.existsSync(destDir)) {
+                cleanRemoveModule(moduleCode, bmadDir, manifestPath);
+            }
+            const copyResult = copyDirThroughWriteService(extractedRoot, destDir, app.fileStore.studioDir, app.fileStore);
+            if (!copyResult.ok)
+                throw new ValidationError(copyResult.error);
+            // Story 15.5 — substitute placeholders before manifest update
+            const subResult = runVariableSubstitution(destDir, {
+                moduleCode,
+                projectRoot: app.fileStore.projectRoot,
+                outputFolder: readOutputFolder(app.fileStore.projectRoot),
+                variables: uploadVariables,
+            }, app.fileStore.studioDir, app.fileStore);
+            if (!subResult.ok)
+                throw new ValidationError(subResult.error);
+            // Update manifest (guaranteed to exist by the check at the top of the handler)
+            const manifest = readManifestSafe(manifestPath);
+            const now = new Date().toISOString();
+            const existing = manifest.modules.find((m) => m.name === moduleCode);
+            if (existing) {
+                existing.lastUpdated = now;
+                existing.source = 'zip';
+                existing.npmPackage = null;
+                existing.repoUrl = null;
+            }
+            else {
+                manifest.modules.push({
+                    name: moduleCode,
+                    version: parsed.data.version ?? '1.0.0',
+                    installDate: now,
+                    lastUpdated: now,
+                    source: 'zip',
+                    npmPackage: null,
+                    repoUrl: null,
+                });
+            }
+            const wrote = writeManifestThroughWriteService(manifestPath, manifest, app.fileStore.studioDir, app.fileStore);
+            if (!wrote.ok)
+                throw new ValidationError(wrote.error);
+            // Story 15.6 — generate IDE launchers after manifest commit
+            const updatedManifest = readManifestSafe(manifestPath);
+            const skillsGenerated = {};
+            if (updatedManifest) {
+                const genResult = generateIdeSkillsForModule(app.fileStore.projectRoot, moduleCode, updatedManifest, app.fileStore.studioDir, app.fileStore);
+                if (!genResult.ok)
+                    throw new ValidationError(genResult.error);
+                for (const [ide, skills] of Object.entries(genResult.skillsByIde)) {
+                    skillsGenerated[ide] = skills.length;
+                }
+            }
+            app.fileStore.rebuild();
+            reply.status(200);
+            return {
+                ok: true,
+                modules: [moduleCode],
+                filesCopied: { text: copyResult.textCount, binary: copyResult.binaryCount },
+                source: { type: 'zip' },
+                skillsGenerated,
+            };
+        }
+        finally {
+            try {
+                fs.rmSync(tmpDir, { recursive: true, force: true });
+            }
+            catch {
+                /* ignore cleanup errors */
+            }
+        }
+    });
     app.post('/api/modules', async (request, reply) => {
         if (!('fileStore' in app)) {
             throw new ValidationError('No project detected');
@@ -164,10 +690,12 @@ export async function modulesPlugin(app) {
             '',
             `project_name: ${name}`,
         ].join('\n');
-        fs.writeFileSync(path.join(moduleDir, 'config.yaml'), configContent, 'utf-8');
+        const wResult = writeFile(path.join(moduleDir, 'config.yaml'), configContent, app.fileStore.studioDir);
+        if (!wResult.ok)
+            throw new ValidationError(wResult.error);
         // Update manifest
-        if (fs.existsSync(manifestPath)) {
-            const manifest = readManifest(manifestPath);
+        const manifest = readManifestSafe(manifestPath);
+        if (manifest) {
             const now = new Date().toISOString();
             manifest.modules.push({
                 name,
@@ -178,14 +706,20 @@ export async function modulesPlugin(app) {
                 npmPackage: null,
                 repoUrl: null,
             });
-            writeManifest(manifestPath, manifest);
+            const wrote = writeManifestThroughWriteService(manifestPath, manifest, app.fileStore.studioDir, app.fileStore);
+            if (!wrote.ok)
+                throw new ValidationError(wrote.error);
         }
         // Rebuild index
         app.fileStore.rebuild();
         reply.status(201);
-        return { ok: true, name, path: moduleDir };
+        return { ok: true, name };
     });
-    app.delete('/api/modules/:name', async (request) => {
+    // Story 15.8 — Regenerate IDE skills for an installed module. Removes all
+    // prefix-matched launcher dirs and re-runs the generator against the current
+    // module contents. Used by the "Regenerate IDE skills" button on PackagesPage
+    // and as the Q9 smoke test for dept-aem.
+    app.post('/api/modules/:name/regenerate-skills', async (request) => {
         if (!('fileStore' in app)) {
             throw new ValidationError('No project detected');
         }
@@ -193,27 +727,199 @@ export async function modulesPlugin(app) {
         const bmadDir = path.join(app.fileStore.projectRoot, '_bmad');
         const moduleDir = path.join(bmadDir, name);
         const manifestPath = path.join(bmadDir, '_config', 'manifest.yaml');
-        // Check manifest for source
-        if (fs.existsSync(manifestPath)) {
-            const manifest = readManifest(manifestPath);
-            const entry = manifest.modules.find((m) => m.name === name);
-            if (!entry) {
-                throw new NotFoundError(`Module "${name}" not found in manifest`);
+        if (!fs.existsSync(moduleDir)) {
+            throw new NotFoundError(`Module "${name}" is not installed`);
+        }
+        const manifest = readManifestSafe(manifestPath);
+        if (!manifest)
+            throw new ValidationError('No manifest.yaml found');
+        // Remove existing launcher files first (snapshots text content via WriteService)
+        const removeResult = removeIdeSkillsForModule(app.fileStore.projectRoot, name, manifest, app.fileStore.studioDir);
+        if (!removeResult.ok)
+            throw new ValidationError(removeResult.error);
+        // Regenerate from the current module contents — picks up any manual edits.
+        const genResult = generateIdeSkillsForModule(app.fileStore.projectRoot, name, manifest, app.fileStore.studioDir, app.fileStore);
+        if (!genResult.ok)
+            throw new ValidationError(genResult.error);
+        const regenerated = {};
+        for (const [ide, skills] of Object.entries(genResult.skillsByIde)) {
+            regenerated[ide] = skills.length;
+        }
+        app.fileStore.rebuild();
+        return { ok: true, regenerated };
+    });
+    // Story 15.7 — Remove preview. Returns a structured pre-flight summary so the
+    // remove dialog (Story 15.9) can render an informed confirmation screen.
+    app.get('/api/modules/:name/remove-preview', async (request) => {
+        if (!('fileStore' in app)) {
+            throw new ValidationError('No project detected');
+        }
+        const { name } = request.params;
+        const bmadDir = path.join(app.fileStore.projectRoot, '_bmad');
+        const moduleDir = path.join(bmadDir, name);
+        const manifestPath = path.join(bmadDir, '_config', 'manifest.yaml');
+        const manifest = readManifestSafe(manifestPath);
+        const entry = manifest?.modules.find((m) => m.name === name);
+        if (!entry)
+            throw new NotFoundError(`Module "${name}" not found in manifest`);
+        // Built-in modules: blocked
+        const removalBlocked = entry.source === 'built-in'
+            ? `Module "${name}" is built-in and cannot be removed via Studio.`
+            : null;
+        // Module file count + size
+        let fileCount = 0;
+        let totalBytes = 0;
+        if (fs.existsSync(moduleDir)) {
+            const walk = (dir) => {
+                for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
+                    const full = path.join(dir, e.name);
+                    if (e.isDirectory())
+                        walk(full);
+                    else {
+                        fileCount++;
+                        totalBytes += fs.statSync(full).size;
+                    }
+                }
+            };
+            walk(moduleDir);
+        }
+        // IDE skills (prefix-matched dirs under each configured IDE output dir)
+        const ideSkills = {};
+        if (manifest?.ides) {
+            for (const ide of manifest.ides) {
+                if (ide !== 'claude-code' && ide !== 'antigravity')
+                    continue;
+                const dir = path.join(app.fileStore.projectRoot, ide === 'claude-code' ? '.claude/skills' : '.antigravity/skills');
+                if (!fs.existsSync(dir)) {
+                    ideSkills[ide] = [];
+                    continue;
+                }
+                const agentPrefix = `bmad-agent-${name}-`;
+                const otherPrefix = `bmad-${name}-`;
+                ideSkills[ide] = fs
+                    .readdirSync(dir, { withFileTypes: true })
+                    .filter((e) => e.isDirectory() &&
+                    (e.name.startsWith(agentPrefix) || e.name.startsWith(otherPrefix)))
+                    .map((e) => e.name);
             }
-            if (entry.source === 'built-in') {
-                throw new ValidationError(`Cannot remove built-in module "${name}"`);
+        }
+        // Preserved directories from module.yaml (declared output dirs)
+        const parsed = parseModuleYaml(moduleDir);
+        const preservedDirectories = [];
+        let moduleYamlPresent = false;
+        if (parsed.ok && fs.existsSync(path.join(moduleDir, 'module.yaml'))) {
+            moduleYamlPresent = true;
+            for (const declared of parsed.data.directories ?? []) {
+                const resolved = path.isAbsolute(declared)
+                    ? declared
+                    : path.join(app.fileStore.projectRoot, declared);
+                if (fs.existsSync(resolved)) {
+                    preservedDirectories.push({ path: resolved, declared: true });
+                }
             }
-            // Remove from manifest
-            manifest.modules = manifest.modules.filter((m) => m.name !== name);
-            writeManifest(manifestPath, manifest);
         }
-        // Delete module directory
+        // Cross-references (TD-19 scope)
+        const crossReferences = findCrossReferences(app.fileStore.getIndex(), name);
+        // External-installer warning
+        const externalInstallerWarning = entry.source === 'external'
+            ? `Module "${name}" was installed by the BMAD installer. Removing it via Studio will not update the upstream installation — re-running the installer will reinstall it.`
+            : null;
+        return {
+            module: { name: entry.name, version: entry.version, source: entry.source },
+            moduleFiles: { count: fileCount, totalBytes },
+            ideSkills,
+            manifestEntries: { 'manifest.yaml': true },
+            preservedDirectories,
+            moduleYamlPresent,
+            crossReferences,
+            crossReferenceScopeNotice: 'Cross-reference scanning covers teams and workflow steps. References from agent menus or skill lists are not detected — review the affected modules manually after removal.',
+            recoverableFrom: '.bmad-studio/history/',
+            removalBlocked,
+            externalInstallerWarning,
+        };
+    });
+    // Story 15.7 — Rich remove handler. Replaces the thin DELETE. Removes IDE
+    // launcher files, then deletes the module dir through WriteService (text
+    // files snapshot to history/ before unlink), then removes the manifest entry.
+    // Preserves directories declared in module.yaml.directories[].
+    app.delete('/api/modules/:name', async (request) => {
+        if (!('fileStore' in app)) {
+            throw new ValidationError('No project detected');
+        }
+        const { name } = request.params;
+        const bmadDir = path.join(app.fileStore.projectRoot, '_bmad');
+        const moduleDir = path.join(bmadDir, name);
+        const manifestPath = path.join(bmadDir, '_config', 'manifest.yaml');
+        const manifest = readManifestSafe(manifestPath);
+        const entry = manifest?.modules.find((m) => m.name === name);
+        if (!entry)
+            throw new NotFoundError(`Module "${name}" not found in manifest`);
+        if (entry.source === 'built-in') {
+            throw new ValidationError(`Cannot remove built-in module "${name}"`);
+        }
+        // Read module.yaml BEFORE deletion so we can capture directories: to preserve.
+        const parsed = parseModuleYaml(moduleDir);
+        const preserved = parsed.ok
+            ? (parsed.data.directories ?? []).map((d) => path.isAbsolute(d) ? d : path.join(app.fileStore.projectRoot, d))
+            : [];
+        // 1. Remove prefix-matched IDE skill directories (each deletion snapshots through WriteService)
+        let removedSkills = {};
+        if (manifest) {
+            const r = removeIdeSkillsForModule(app.fileStore.projectRoot, name, manifest, app.fileStore.studioDir);
+            if (!r.ok)
+                throw new ValidationError(r.error);
+            removedSkills = r.removedByIde;
+        }
+        // 2. Delete the module directory through WriteService (text files snapshot first).
+        //    Count files before delete so the response summary is accurate.
+        let filesRemoved = 0;
         if (fs.existsSync(moduleDir)) {
-            fs.rmSync(moduleDir, { recursive: true, force: true });
+            const walk = (dir) => {
+                for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
+                    const full = path.join(dir, e.name);
+                    if (e.isDirectory())
+                        walk(full);
+                    else
+                        filesRemoved++;
+                }
+            };
+            walk(moduleDir);
+            const r = deleteDirectory(moduleDir, app.fileStore.studioDir);
+            if (!r.ok)
+                throw new ValidationError(r.error);
         }
-        // Rebuild index
+        // 3. Update the manifest (snapshot via WriteService)
+        if (manifest) {
+            manifest.modules = manifest.modules.filter((m) => m.name !== name);
+            const wrote = writeManifestThroughWriteService(manifestPath, manifest, app.fileStore.studioDir, app.fileStore);
+            if (!wrote.ok)
+                throw new ValidationError(wrote.error);
+        }
+        // 4. Rebuild index and broadcast the change
         app.fileStore.rebuild();
-        return { ok: true, name };
+        if ('ws' in app) {
+            try {
+                ;
+                app.ws.broadcast({
+                    type: 'file:deleted',
+                    path: moduleDir,
+                    category: 'config',
+                });
+            }
+            catch {
+                /* ignore — broadcast is best-effort */
+            }
+        }
+        return {
+            ok: true,
+            name,
+            removed: {
+                filesRemoved,
+                skills: removedSkills,
+            },
+            preservedDirectories: preserved,
+            recoverableFrom: '.bmad-studio/history/',
+        };
     });
     // Story 12.1 + 12.2: Add/upload entities to a module
     app.post('/api/modules/:name/entities', async (request, reply) => {
@@ -221,6 +927,9 @@ export async function modulesPlugin(app) {
             throw new ValidationError('No project detected');
         }
         const { name } = request.params;
+        if (!MODULE_NAME_RE.test(name)) {
+            throw new ValidationError('Module name must be lowercase alphanumeric with hyphens');
+        }
         const body = request.body;
         const entityType = body.type;
         const entityName = body.name?.trim();
@@ -258,7 +967,9 @@ export async function modulesPlugin(app) {
                 '<!-- Add skill instructions here -->',
                 '',
             ].join('\n');
-            fs.writeFileSync(filePath, content, 'utf-8');
+            const wResult = writeFile(filePath, content, app.fileStore.studioDir);
+            if (!wResult.ok)
+                throw new ValidationError(wResult.error);
         }
         else if (entityType === 'workflow') {
             // Workflows get their own directory with a workflow.md file
@@ -282,7 +993,9 @@ export async function modulesPlugin(app) {
                 '<!-- Add workflow steps here -->',
                 '',
             ].join('\n');
-            fs.writeFileSync(filePath, content, 'utf-8');
+            const wResult = writeFile(filePath, content, app.fileStore.studioDir);
+            if (!wResult.ok)
+                throw new ValidationError(wResult.error);
         }
         else {
             // Agent: .md file in agents/ directory
@@ -305,12 +1018,14 @@ export async function modulesPlugin(app) {
                 '<!-- Add agent definition here -->',
                 '',
             ].join('\n');
-            fs.writeFileSync(filePath, content, 'utf-8');
+            const wResult = writeFile(filePath, content, app.fileStore.studioDir);
+            if (!wResult.ok)
+                throw new ValidationError(wResult.error);
         }
         // Rebuild index
         app.fileStore.rebuild();
         reply.status(201);
-        return { ok: true, type: entityType, name: entityName, path: filePath };
+        return { ok: true, type: entityType, name: entityName };
     });
     // Story 12.3: Export module manifest
     app.post('/api/modules/:name/export', async (request) => {
@@ -320,10 +1035,10 @@ export async function modulesPlugin(app) {
         const { name } = request.params;
         const bmadDir = path.join(app.fileStore.projectRoot, '_bmad');
         const manifestPath = path.join(bmadDir, '_config', 'manifest.yaml');
-        if (!fs.existsSync(manifestPath)) {
+        const manifest = readManifestSafe(manifestPath);
+        if (!manifest) {
             throw new NotFoundError('No manifest found');
         }
-        const manifest = readManifest(manifestPath);
         const entry = manifest.modules.find((m) => m.name === name);
         if (!entry) {
             throw new NotFoundError(`Module "${name}" not found in manifest`);
@@ -361,6 +1076,9 @@ export async function modulesPlugin(app) {
             throw new ValidationError('No project detected');
         }
         const { name } = request.params;
+        if (!MODULE_NAME_RE.test(name)) {
+            throw new ValidationError('Module name must be lowercase alphanumeric with hyphens');
+        }
         const body = request.body;
         const bmadDir = path.join(app.fileStore.projectRoot, '_bmad');
         const moduleDir = path.join(bmadDir, name);
@@ -369,23 +1087,27 @@ export async function modulesPlugin(app) {
             throw new NotFoundError(`Module "${name}" config not found`);
         }
         const configContent = fs.readFileSync(configPath, 'utf-8');
-        const config = yaml.load(configContent);
+        const config = yaml.load(configContent) ?? {};
         if (body.version !== undefined)
             config.version = body.version;
         if (body.description !== undefined)
             config.description = body.description;
         const updated = yaml.dump(config, { lineWidth: -1 });
-        fs.writeFileSync(configPath, updated, 'utf-8');
+        const wResult = writeFile(configPath, updated, app.fileStore.studioDir);
+        if (!wResult.ok)
+            throw new ValidationError(wResult.error);
         // Also update manifest.yaml
         const manifestPath = path.join(bmadDir, '_config', 'manifest.yaml');
-        if (fs.existsSync(manifestPath)) {
-            const manifest = readManifest(manifestPath);
+        const manifest = readManifestSafe(manifestPath);
+        if (manifest) {
             const mod = manifest.modules.find((m) => m.name === name);
             if (mod) {
                 if (body.version !== undefined)
                     mod.version = body.version;
-                mod.lastUpdated = new Date().toISOString().split('T')[0];
-                writeManifest(manifestPath, manifest);
+                mod.lastUpdated = new Date().toISOString();
+                const wrote = writeManifestThroughWriteService(manifestPath, manifest, app.fileStore.studioDir, app.fileStore);
+                if (!wrote.ok)
+                    throw new ValidationError(wrote.error);
             }
         }
         app.fileStore.rebuild();
@@ -397,10 +1119,10 @@ export async function modulesPlugin(app) {
         }
         const bmadDir = path.join(app.fileStore.projectRoot, '_bmad');
         const manifestPath = path.join(bmadDir, '_config', 'manifest.yaml');
-        if (!fs.existsSync(manifestPath)) {
+        const manifest = readManifestSafe(manifestPath);
+        if (!manifest) {
             return [];
         }
-        const manifest = readManifest(manifestPath);
         const index = app.fileStore.getIndex();
         return manifest.modules.map((m) => {
             const moduleAgents = index.agents.filter((a) => a.module === m.name);
@@ -430,6 +1152,9 @@ export async function modulesPlugin(app) {
         if (!name) {
             throw new ValidationError('Package name is required');
         }
+        if (!/^[a-zA-Z0-9][a-zA-Z0-9_-]*$/.test(name)) {
+            throw new ValidationError('Package name must start with a letter or digit and contain only alphanumeric characters, hyphens, or underscores');
+        }
         const description = body.description?.trim() || '';
         const version = body.version?.trim() || '1.0.0';
         const agentIds = body.agents ?? [];
@@ -492,7 +1217,10 @@ export async function modulesPlugin(app) {
             fs.writeFileSync(path.join(packageDir, 'package.yaml'), yaml.dump(packageManifest, { lineWidth: -1 }), 'utf-8');
             // Create tar.gz archive
             const archivePath = path.join(tmpBase, `${name}.tar.gz`);
-            execSync(`tar -czf "${archivePath}" -C "${tmpBase}" "${name}"`);
+            const tarResult = spawnSync('tar', ['-czf', archivePath, '-C', tmpBase, name], { stdio: 'pipe' });
+            if (tarResult.status !== 0) {
+                throw new ValidationError('Failed to create package archive');
+            }
             // Send as downloadable file
             reply.header('Content-Disposition', `attachment; filename="${name}.tar.gz"`);
             reply.type('application/gzip');
@@ -527,5 +1255,59 @@ export async function modulesPlugin(app) {
             throw new ValidationError(`Export failed: ${err instanceof Error ? err.message : 'Unknown error'}`);
         }
     });
+    // ─────────────────────────────────────────────────────────────────────────────
+    // Story 16.2 — Registry index endpoints
+    // ─────────────────────────────────────────────────────────────────────────────
+    app.get('/api/registry', async (_request, reply) => {
+        if (!('fileStore' in app)) {
+            return reply.send({ ok: false, configured: false, error: 'No project detected' });
+        }
+        const settingsPath = path.join(app.fileStore.studioDir, 'settings.json');
+        if (!fs.existsSync(settingsPath)) {
+            return reply.send({ ok: false, configured: false, error: 'No registry configured' });
+        }
+        const settings = JSON.parse(fs.readFileSync(settingsPath, 'utf-8'));
+        if (!settings.registry?.repo) {
+            return reply.send({ ok: false, configured: false, error: 'No registry configured' });
+        }
+        let ghSource;
+        try {
+            ghSource = parseGithubSource(settings.registry.repo);
+        }
+        catch (err) {
+            throw new ValidationError(err instanceof Error ? err.message : String(err));
+        }
+        let cached = readCachedRegistryIndex(app.fileStore.studioDir, ghSource.owner, ghSource.repo);
+        if (!cached || isRegistryCacheStale(cached)) {
+            try {
+                cached = await fetchAndCacheRegistryIndex(app.fileStore.studioDir, settings.registry.repo, settings.registry.branch ?? 'main');
+            }
+            catch (err) {
+                throw new ValidationError(err instanceof Error ? err.message : String(err));
+            }
+        }
+        return reply.send({ ok: true, configured: true, index: cached });
+    });
+    app.post('/api/registry/refresh', async (_request, reply) => {
+        if (!('fileStore' in app)) {
+            throw new ValidationError('No project detected');
+        }
+        const settingsPath = path.join(app.fileStore.studioDir, 'settings.json');
+        if (!fs.existsSync(settingsPath)) {
+            throw new ValidationError('No registry configured');
+        }
+        const settings = JSON.parse(fs.readFileSync(settingsPath, 'utf-8'));
+        if (!settings.registry?.repo) {
+            throw new ValidationError('No registry configured');
+        }
+        let index;
+        try {
+            index = await fetchAndCacheRegistryIndex(app.fileStore.studioDir, settings.registry.repo, settings.registry.branch ?? 'main');
+        }
+        catch (err) {
+            throw new ValidationError(err instanceof Error ? err.message : String(err));
+        }
+        return reply.send({ ok: true, index });
+    });
 }
 //# sourceMappingURL=modules-plugin.js.map