@doubledigit/cli 0.1.0

package/dist/commands/add.js

@@ -0,0 +1,548 @@
+/**
+ * dd add <source> — Install a micro-app or payload plugin from GitHub or npm.
+ *
+ * Sources:
+ *   gh:owner/repo/extensions/micro-apps/app           GitHub micro-app subdirectory
+ *   gh:owner/repo/extensions/micro-apps/app#v1.0.0    Specific tag/ref
+ *   gh:owner/repo                         Full repo as micro-app
+ *   github:owner/repo/path               Alternative prefix
+ *   https://github.com/owner/repo/...    Full URL
+ *   npm:@scope/package                   npm registry
+ *   npm:@scope/package@1.2.3            Specific npm version
+ *
+ * Flow:
+ * 1. Parse source → determine type (github vs npm)
+ * 2. Pre-install validation
+ * 3. Download (giget for GitHub, pnpm for npm)
+ * 4. Post-download validation
+ * 5. Install to the appropriate extension root
+ * 6. Wire up (deps, TS paths, config, lock file)
+ * 7. Run sync + pnpm install
+ */
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { execSync } from 'node:child_process';
+import { downloadTemplate } from 'giget';
+import { resolveWorkspacePaths, allInstallRoots, allScanRoots, installDirForKind, installRelPath, installProbePaths, } from '../paths.js';
+import { readConfig, writeConfig } from '../config.js';
+import { sync } from './sync.js';
+import { parseSource } from '../lib/source-parser.js';
+import { addLockEntry, computeContentHash, } from '../lib/lock-file.js';
+import { validateLocalDirectory, validateNoNameCollision, validateNoPackageNameCollision, validateRemoteSource, validateDownloadedPackage, resolvePackageEntryPoint, extractMicroAppMetadata, validateSlugPrefix, detectPackageKind, readManagedPackageMetadata, } from '../lib/validators.js';
+import { resolveExtension, resolveExtensionFromMarketplace, extensionSourceToGhString, readKnownMarketplaces, } from '../lib/marketplace.js';
+import { rewriteExtensionTsconfig } from '../lib/rewrite-extension-tsconfig.js';
+import { resolveGitHubToken } from '../lib/github-auth.js';
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/** Extract app name from the last path segment of a source. */
+function extractAppName(source) {
+    if (source.subdir) {
+        const segments = source.subdir.split('/').filter(Boolean);
+        return segments[segments.length - 1];
+    }
+    return source.repo;
+}
+/** Check if a string looks like an npm source. */
+function isNpmSource(raw) {
+    return raw.startsWith('npm:');
+}
+/** Parse npm source → { packageSpec, name }. Validates against shell injection. */
+function parseNpmSource(raw) {
+    const spec = raw.slice(4); // strip 'npm:'
+    // Strict validation: only allow npm-safe characters (scope, name, version range)
+    if (!/^(@[\w.\-]+\/)?[\w.\-]+([@^~>=<\s\d.\-*|]+)?$/.test(spec)) {
+        throw new Error(`Invalid npm package specifier: "${spec}"\n` +
+            'Expected format: @scope/name, @scope/name@version, or name@version');
+    }
+    // Extract short name from scoped package: @scope/foo@version → foo
+    const atIdx = spec.lastIndexOf('@');
+    const packageName = atIdx > 0 ? spec.slice(0, atIdx) : spec;
+    const shortName = packageName.includes('/')
+        ? packageName.split('/').pop()
+        : packageName;
+    return { packageSpec: spec, name: shortName };
+}
+/** Print validation results and exit on errors. */
+function handleValidation(result, label) {
+    if (result.warnings.length > 0) {
+        for (const w of result.warnings) {
+            console.log(`   ⚠ ${w}`);
+        }
+    }
+    if (!result.valid) {
+        for (const e of result.errors) {
+            console.error(`   ✘ ${e}`);
+        }
+        console.error(`\n❌ ${label} failed.`);
+        process.exit(1);
+    }
+}
+function findExistingInstalls(paths, name, preferredKind) {
+    return installProbePaths(paths, name, preferredKind)
+        .filter((dir) => fs.existsSync(dir))
+        .map((dir) => ({
+        dir,
+        ...readManagedPackageMetadata(dir),
+    }));
+}
+function snapshotFiles(filePaths) {
+    return filePaths.map((filePath) => ({
+        path: filePath,
+        existed: fs.existsSync(filePath),
+        content: fs.existsSync(filePath)
+            ? fs.readFileSync(filePath, 'utf-8')
+            : undefined,
+    }));
+}
+function restoreSnapshots(snapshots) {
+    for (const snapshot of snapshots) {
+        if (snapshot.existed) {
+            fs.mkdirSync(path.dirname(snapshot.path), { recursive: true });
+            fs.writeFileSync(snapshot.path, snapshot.content ?? '', 'utf-8');
+        }
+        else if (fs.existsSync(snapshot.path)) {
+            fs.rmSync(snapshot.path, { force: true });
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// npm source handler
+// ---------------------------------------------------------------------------
+async function addFromNpm(_packageSpec, _appName, _options) {
+    // npm sources install to node_modules, but the dd sync/codegen system
+    // only discovers extensions from workspace roots. Until
+    // node_modules-backed discovery is implemented, reject npm sources.
+    console.error('\n❌ npm source is not yet supported.\n\n' +
+        '   npm packages install to node_modules/, but extension discovery\n' +
+        '   scans the workspace install roots. The app would install but never activate.\n\n' +
+        '   Use a GitHub source instead:\n' +
+        '     dd add gh:owner/repo/extensions/micro-apps/my-app\n\n' +
+        '   npm source support is planned for a future release.\n');
+    process.exit(1);
+}
+// ---------------------------------------------------------------------------
+// GitHub source handler (main flow)
+// ---------------------------------------------------------------------------
+async function addFromGitHub(raw, options, marketplaceCtx) {
+    const paths = resolveWorkspacePaths();
+    const source = parseSource(raw);
+    const appName = options?.name ?? extractAppName(source);
+    const preInstallLabel = marketplaceCtx?.kind === 'payload-plugin' ? 'payload plugin' : 'micro-app';
+    console.log(`\n📦 Installing ${preInstallLabel} from ${source.displayString}\n`);
+    // -----------------------------------------------------------------------
+    // Pre-install validation
+    // -----------------------------------------------------------------------
+    console.log('🔍 Pre-install validation...');
+    const installRoots = allInstallRoots(paths);
+    if (!options?.force) {
+        const localResult = validateLocalDirectory(installRoots, appName);
+        handleValidation(localResult, 'Local directory check');
+        console.log('   ✔ Local directory is available');
+        const collisionResult = validateNoNameCollision(installRoots, appName);
+        handleValidation(collisionResult, 'Name collision check');
+        console.log('   ✔ No name collision detected');
+    }
+    else {
+        console.log('   ⚠ Skipping local checks (--force)');
+    }
+    const remoteResult = await validateRemoteSource(source);
+    handleValidation(remoteResult, 'Remote source check');
+    console.log('   ✔ Remote repository verified');
+    console.log('');
+    // -----------------------------------------------------------------------
+    // Download to temp directory
+    // -----------------------------------------------------------------------
+    const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'dd-add-'));
+    try {
+        console.log('⬇️  Downloading from GitHub...');
+        const githubToken = resolveGitHubToken();
+        await downloadTemplate(source.templateString, {
+            dir: tempDir,
+            force: true,
+            ...(githubToken ? { auth: githubToken } : {}),
+        });
+        console.log('   ✔ Downloaded to temp directory');
+        console.log('');
+        // ---------------------------------------------------------------------
+        // Post-download validation
+        // ---------------------------------------------------------------------
+        console.log('🔍 Post-download validation...');
+        // Detect package kind from downloaded source
+        const detectedKind = detectPackageKind(tempDir);
+        // Cross-check against marketplace metadata if present
+        if (marketplaceCtx?.kind && marketplaceCtx.kind !== detectedKind) {
+            console.error(`\n❌ Kind mismatch: marketplace declares "${marketplaceCtx.kind}" ` +
+                `but downloaded package is "${detectedKind}".\n`);
+            process.exit(1);
+        }
+        const effectiveKind = detectedKind;
+        const isPayloadPlugin = effectiveKind === 'payload-plugin';
+        const downloadResult = validateDownloadedPackage(tempDir, effectiveKind);
+        handleValidation(downloadResult, 'Package validation');
+        console.log(isPayloadPlugin
+            ? '   ✔ Valid payload-plugin package structure'
+            : '   ✔ Valid DDApp package structure');
+        // Read package.json from downloaded source
+        const downloadedPkgPath = path.join(tempDir, 'package.json');
+        const downloadedPkg = JSON.parse(fs.readFileSync(downloadedPkgPath, 'utf-8'));
+        const detectedEntryPoint = resolvePackageEntryPoint(tempDir, downloadedPkg);
+        // Validate package.json contract (kind-specific)
+        const pkgErrors = [];
+        if (isPayloadPlugin) {
+            if (downloadedPkg.ddPackageType !== 'payload-plugin')
+                pkgErrors.push('"ddPackageType" must be "payload-plugin"');
+        }
+        else {
+            if (downloadedPkg.ddapp !== true)
+                pkgErrors.push('"ddapp" must be true');
+        }
+        if (!downloadedPkg.name || typeof downloadedPkg.name !== 'string')
+            pkgErrors.push('"name" is required');
+        if (!downloadedPkg.exports && !downloadedPkg.main)
+            pkgErrors.push('"exports" or "main" field is required');
+        if (pkgErrors.length > 0) {
+            for (const e of pkgErrors)
+                console.error(`   ✘ ${e}`);
+            console.error(isPayloadPlugin
+                ? '\n❌ Payload plugin package.json validation failed.'
+                : '\n❌ DDApp package.json validation failed.');
+            process.exit(1);
+        }
+        console.log(isPayloadPlugin
+            ? '   ✔ Payload plugin package.json validated'
+            : '   ✔ DDApp package.json validated');
+        if (!detectedEntryPoint) {
+            console.error('\n❌ Could not determine the package entry point for TS path mappings.\n' +
+                '   Define src/index.ts, src/index.tsx, exports["."], or main in package.json.\n');
+            process.exit(1);
+        }
+        // Micro-app only: validate DDApp key + slug prefix
+        if (!isPayloadPlugin) {
+            const { key: ddAppKey, slugPrefix: detectedSlugPrefix } = extractMicroAppMetadata(tempDir, downloadedPkg, detectedEntryPoint);
+            // Validate --name: the DDApp's internal key must match the install name.
+            // The key is the directory name which becomes the config key — mismatch
+            // causes runtime enable/disable to break silently.
+            if (options?.name && ddAppKey && ddAppKey !== options.name) {
+                console.error(`\n❌ --name "${options.name}" conflicts with the micro-app's internal key "${ddAppKey}".\n` +
+                    `   The DDApp key is baked into the source code and cannot be overridden.\n` +
+                    `   Either install without --name, or use --name ${ddAppKey}\n`);
+                process.exit(1);
+            }
+            if (detectedSlugPrefix) {
+                const slugResult = validateSlugPrefix(allScanRoots(paths), detectedSlugPrefix, appName);
+                handleValidation(slugResult, 'Slug prefix check');
+            }
+            console.log('   ✔ No slug prefix collision');
+        }
+        console.log('');
+        // Determine npm name from downloaded package
+        const npmName = downloadedPkg.name || `@doubledigit/${appName}`;
+        const packageNameCollisionResult = validateNoPackageNameCollision(allScanRoots(paths), npmName, appName);
+        handleValidation(packageNameCollisionResult, 'Package name collision check');
+        console.log('   ✔ No package name collision detected');
+        const hasSrcDir = fs.existsSync(path.join(tempDir, 'src'));
+        // ---------------------------------------------------------------------
+        // Install: move to extensions/<kind>/<name>/ with rollback safety
+        // ---------------------------------------------------------------------
+        const targetDir = installDirForKind(paths, effectiveKind, appName);
+        const targetRelPath = installRelPath(effectiveKind, appName);
+        const baseTsConfigPath = path.join(paths.root, 'tsconfig.base.json');
+        const mainTsConfigPath = path.join(paths.mainAppDir, 'tsconfig.json');
+        console.log(`📁 Installing to ${targetRelPath}...`);
+        const existingInstalls = findExistingInstalls(paths, appName, effectiveKind);
+        const unmanagedConflicts = existingInstalls.filter((install) => !install.isManagedExtension);
+        if (unmanagedConflicts.length > 0) {
+            const conflictList = unmanagedConflicts
+                .map((install) => path.relative(paths.root, install.dir))
+                .join(', ');
+            console.error('\n❌ Existing non-extension package conflicts with this install.\n' +
+                `   Conflicting path(s): ${conflictList}\n` +
+                '   `dd add --force` only replaces dd-managed extensions; it will not overwrite internal packages.\n');
+            process.exit(1);
+        }
+        if (!options?.force && existingInstalls.length > 0) {
+            const conflictList = existingInstalls
+                .map((install) => path.relative(paths.root, install.dir))
+                .join(', ');
+            console.error('\n❌ Existing extension already installed.\n' +
+                `   Conflicting path(s): ${conflictList}\n` +
+                '   Re-run with --force to replace the existing install.\n');
+            process.exit(1);
+        }
+        const previousNpmNames = new Set();
+        const previousKinds = new Set();
+        for (const existingInstall of existingInstalls) {
+            if (existingInstall.npmName) {
+                previousNpmNames.add(existingInstall.npmName);
+            }
+            if (existingInstall.kind) {
+                previousKinds.add(existingInstall.kind);
+            }
+        }
+        const backups = [];
+        if (options?.force) {
+            const backupSuffix = Date.now();
+            const backupRoot = path.join(paths.root, '.doubledigit', 'tmp-backups');
+            fs.mkdirSync(backupRoot, { recursive: true });
+            for (const [index, existingInstall] of existingInstalls.entries()) {
+                const backupDir = path.join(backupRoot, `${path.basename(existingInstall.dir)}.bak-${backupSuffix}-${index}`);
+                fs.renameSync(existingInstall.dir, backupDir);
+                backups.push({ originalDir: existingInstall.dir, backupDir });
+                console.log(`   ⚠ Replacing existing install at ${path.relative(paths.root, existingInstall.dir)}`);
+            }
+        }
+        const rollbackSnapshots = snapshotFiles([
+            paths.mainAppPackageJsonPath,
+            baseTsConfigPath,
+            mainTsConfigPath,
+            paths.configPath,
+            paths.lockFilePath,
+            paths.microAppsOutputPath,
+            paths.payloadPluginsOutputPath,
+        ]);
+        try {
+            // Ensure parent directory exists (extensions/<kind>/ may not yet exist)
+            fs.mkdirSync(path.dirname(targetDir), { recursive: true });
+            // Copy from temp to target
+            fs.cpSync(tempDir, targetDir, { recursive: true });
+            // Rewrite tsconfig relative paths for the new installation depth
+            rewriteExtensionTsconfig(targetDir, paths.root);
+            console.log(`   ✔ Installed to ${targetRelPath}`);
+            // -------------------------------------------------------------------
+            // Wire up (mirrors create.ts pattern)
+            // -------------------------------------------------------------------
+            // Add dependency to main-app/package.json
+            const mainPkg = JSON.parse(fs.readFileSync(paths.mainAppPackageJsonPath, 'utf-8'));
+            if (!mainPkg.dependencies)
+                mainPkg.dependencies = {};
+            for (const previousNpmName of previousNpmNames) {
+                if (previousNpmName !== npmName) {
+                    delete mainPkg.dependencies[previousNpmName];
+                }
+            }
+            mainPkg.dependencies[npmName] = 'workspace:*';
+            mainPkg.dependencies = Object.fromEntries(Object.entries(mainPkg.dependencies).sort(([a], [b]) => a.localeCompare(b)));
+            fs.writeFileSync(paths.mainAppPackageJsonPath, JSON.stringify(mainPkg, null, 2) + '\n', 'utf-8');
+            console.log('   ✔ Added dependency to main-app/package.json');
+            // Add TS path mappings to tsconfig.base.json
+            if (fs.existsSync(baseTsConfigPath)) {
+                const tsconfig = JSON.parse(fs.readFileSync(baseTsConfigPath, 'utf-8'));
+                if (!tsconfig.compilerOptions)
+                    tsconfig.compilerOptions = {};
+                if (!tsconfig.compilerOptions.paths)
+                    tsconfig.compilerOptions.paths = {};
+                for (const previousNpmName of previousNpmNames) {
+                    if (previousNpmName === npmName)
+                        continue;
+                    delete tsconfig.compilerOptions.paths[previousNpmName];
+                    delete tsconfig.compilerOptions.paths[`${previousNpmName}/*`];
+                }
+                tsconfig.compilerOptions.paths[npmName] = [
+                    `${targetRelPath}/${detectedEntryPoint}`,
+                ];
+                if (hasSrcDir) {
+                    tsconfig.compilerOptions.paths[`${npmName}/*`] = [
+                        `${targetRelPath}/src/*`,
+                    ];
+                }
+                else {
+                    delete tsconfig.compilerOptions.paths[`${npmName}/*`];
+                }
+                fs.writeFileSync(baseTsConfigPath, JSON.stringify(tsconfig, null, 2) + '\n', 'utf-8');
+            }
+            // Add TS path mappings to apps/main-app/tsconfig.json
+            if (fs.existsSync(mainTsConfigPath)) {
+                const tsconfig = JSON.parse(fs.readFileSync(mainTsConfigPath, 'utf-8'));
+                if (!tsconfig.compilerOptions)
+                    tsconfig.compilerOptions = {};
+                if (!tsconfig.compilerOptions.paths)
+                    tsconfig.compilerOptions.paths = {};
+                for (const previousNpmName of previousNpmNames) {
+                    if (previousNpmName === npmName)
+                        continue;
+                    delete tsconfig.compilerOptions.paths[previousNpmName];
+                    delete tsconfig.compilerOptions.paths[`${previousNpmName}/*`];
+                }
+                tsconfig.compilerOptions.paths[npmName] = [
+                    `../../${targetRelPath}/${detectedEntryPoint}`,
+                ];
+                if (hasSrcDir) {
+                    tsconfig.compilerOptions.paths[`${npmName}/*`] = [
+                        `../../${targetRelPath}/src/*`,
+                    ];
+                }
+                else {
+                    delete tsconfig.compilerOptions.paths[`${npmName}/*`];
+                }
+                fs.writeFileSync(mainTsConfigPath, JSON.stringify(tsconfig, null, 2) + '\n', 'utf-8');
+            }
+            console.log('   ✔ Added TS path mappings');
+            // Add entry to dd-apps.config.json (micro-app only)
+            const config = readConfig(paths.configPath);
+            if (!isPayloadPlugin) {
+                if (!config.apps)
+                    config.apps = {};
+                config.apps[appName] = true;
+                writeConfig(paths.configPath, config);
+                console.log('   ✔ Updated dd-apps.config.json');
+            }
+            else if (previousKinds.has('micro-app') && config.apps?.[appName] !== undefined) {
+                delete config.apps[appName];
+                writeConfig(paths.configPath, config);
+                console.log('   ✔ Removed stale dd-apps.config.json entry');
+            }
+            // Update lock file (persist npmName for uninstall)
+            const contentHash = await computeContentHash(targetDir);
+            const now = new Date().toISOString();
+            const lockEntry = {
+                source: raw,
+                resolvedSource: source.templateString,
+                contentHash,
+                ref: marketplaceCtx?.ref ?? source.ref,
+                npmName,
+                installedAt: now,
+                updatedAt: now,
+                kind: effectiveKind,
+                ...(marketplaceCtx?.marketplace && { marketplace: marketplaceCtx.marketplace }),
+                ...(marketplaceCtx?.sha && { sha: marketplaceCtx.sha }),
+                ...(marketplaceCtx?.version && { marketplaceVersion: marketplaceCtx.version }),
+                installPath: targetRelPath,
+                installStrategy: 'workspace-vendor',
+            };
+            addLockEntry(paths.lockFilePath, appName, lockEntry);
+            console.log('   ✔ Updated dd-apps.lock.json');
+            console.log('');
+            // Run sync
+            await sync();
+        }
+        catch (installErr) {
+            console.error('   ✘ Install failed — rolling back workspace changes');
+            try {
+                restoreSnapshots(rollbackSnapshots);
+                if (fs.existsSync(targetDir)) {
+                    fs.rmSync(targetDir, { recursive: true, force: true });
+                }
+                for (const backup of backups) {
+                    if (!fs.existsSync(backup.backupDir))
+                        continue;
+                    fs.mkdirSync(path.dirname(backup.originalDir), { recursive: true });
+                    fs.renameSync(backup.backupDir, backup.originalDir);
+                }
+            }
+            catch {
+                const backupDirs = backups.map((backup) => backup.backupDir).join(', ');
+                console.error(`   ✘ Rollback failed. Backup(s) at: ${backupDirs}`);
+            }
+            throw installErr;
+        }
+        for (const backup of backups) {
+            if (fs.existsSync(backup.backupDir)) {
+                fs.rmSync(backup.backupDir, { recursive: true, force: true });
+            }
+        }
+        // Run pnpm install
+        console.log('\n📦 Running pnpm install...');
+        try {
+            execSync('pnpm install', { cwd: paths.root, stdio: 'inherit' });
+        }
+        catch {
+            console.warn('⚠ pnpm install failed. Run it manually.');
+        }
+        console.log(`
+✅ ${isPayloadPlugin ? 'Payload plugin' : 'Micro-app'} "${appName}" installed successfully from GitHub!
+
+Next steps:
+  1. Review the installed code: ${targetRelPath}/
+  2. Run: pnpm db:migrate:create
+  3. Run: pnpm db:migrate
+  4. Run: pnpm dev
+`);
+    }
+    finally {
+        // Clean up temp directory
+        try {
+            fs.rmSync(tempDir, { recursive: true, force: true });
+        }
+        catch {
+            // Ignore cleanup failures
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+export async function add(source, options) {
+    // 1. npm: prefix → npm install
+    if (isNpmSource(source)) {
+        const { packageSpec, name } = parseNpmSource(source);
+        const appName = options?.name ?? name;
+        await addFromNpm(packageSpec, appName, options);
+        return;
+    }
+    // 2. Explicit GitHub prefixes → GitHub install directly
+    if (source.startsWith('gh:') ||
+        source.startsWith('github:') ||
+        source.startsWith('https://')) {
+        await addFromGitHub(source, options);
+        return;
+    }
+    // 3. name@marketplace → resolve from a specific marketplace
+    // 4. bare name (no prefix, no @) → resolve from any known marketplace
+    const { root } = resolveWorkspacePaths();
+    const atIdx = source.indexOf('@');
+    if (atIdx > 0) {
+        // name@marketplace syntax
+        const extName = source.slice(0, atIdx);
+        const marketplaceName = source.slice(atIdx + 1);
+        const known = readKnownMarketplaces(root);
+        if (!(marketplaceName in known.marketplaces)) {
+            console.error(`Error: marketplace "${marketplaceName}" is not registered.\n` +
+                'Run `dd marketplace add` to register it, then `dd marketplace update` to fetch its catalog.');
+            process.exit(1);
+        }
+        const ext = resolveExtensionFromMarketplace(root, extName, marketplaceName);
+        if (!ext) {
+            console.error(`Error: extension "${extName}" not found in marketplace "${marketplaceName}".\n` +
+                `Run \`dd marketplace update ${marketplaceName}\` to refresh the catalog.`);
+            process.exit(1);
+        }
+        if (options?.name && options.name !== ext.name) {
+            console.error(`Error: --name "${options.name}" conflicts with marketplace extension name "${ext.name}".\n` +
+                'Marketplace installs must keep the catalog name so info/outdated/reconcile continue to match.');
+            process.exit(1);
+        }
+        const ghSource = extensionSourceToGhString(ext);
+        console.log(`Resolved ${source} → ${ghSource} (from "${marketplaceName}" marketplace)`);
+        await addFromGitHub(ghSource, { ...options, name: ext.name }, {
+            kind: ext.kind,
+            marketplace: marketplaceName,
+            sha: ext.source.sha,
+            ref: ext.source.ref,
+            version: ext.version,
+        });
+        return;
+    }
+    // Bare name — try resolving across all known marketplaces
+    const ext = resolveExtension(root, source);
+    if (ext) {
+        if (options?.name && options.name !== ext.name) {
+            console.error(`Error: --name "${options.name}" conflicts with marketplace extension name "${ext.name}".\n` +
+                'Marketplace installs must keep the catalog name so info/outdated/reconcile continue to match.');
+            process.exit(1);
+        }
+        const ghSource = extensionSourceToGhString(ext);
+        console.log(`Resolved ${source} → ${ghSource} (from "${ext.marketplace}" marketplace)`);
+        await addFromGitHub(ghSource, { ...options, name: ext.name }, {
+            kind: ext.kind,
+            marketplace: ext.marketplace,
+            sha: ext.source.sha,
+            ref: ext.source.ref,
+            version: ext.version,
+        });
+        return;
+    }
+    // Fallback: treat as GitHub source (preserves existing behavior for owner/repo strings)
+    await addFromGitHub(source, options);
+}

package/dist/commands/browse.d.ts

@@ -0,0 +1,8 @@
+/**
+ * dd browse [marketplace] — Browse extensions in registered marketplaces.
+ *
+ * Lists available extensions with kind, version, tags, and install command.
+ * Optionally filters by marketplace name or search query.
+ */
+export declare function browse(args: string[]): Promise<void>;
+//# sourceMappingURL=browse.d.ts.map

package/dist/commands/browse.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browse.d.ts","sourceRoot":"","sources":["../../src/commands/browse.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAyCH,wBAAsB,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CA0G1D"}

package/dist/commands/browse.js

@@ -0,0 +1,116 @@
+/**
+ * dd browse [marketplace] — Browse extensions in registered marketplaces.
+ *
+ * Lists available extensions with kind, version, tags, and install command.
+ * Optionally filters by marketplace name or search query.
+ */
+import { readKnownMarketplaces, getAllCachedExtensions, readCachedMarketplace, } from '../lib/marketplace.js';
+import { resolveWorkspacePaths } from '../paths.js';
+// ---------------------------------------------------------------------------
+// Formatting helpers
+// ---------------------------------------------------------------------------
+function kindBadge(kind) {
+    const badges = {
+        'micro-app': '📦',
+        'payload-plugin': '🔌',
+    };
+    return badges[kind] ?? '📄';
+}
+function formatExtension(ext) {
+    const badge = kindBadge(ext.kind);
+    const verified = ext.verified ? ' ✓' : '';
+    const version = ext.version ? ` v${ext.version}` : '';
+    const tags = ext.tags.length > 0 ? ` [${ext.tags.join(', ')}]` : '';
+    const desc = ext.description ? `\n    ${ext.description}` : '';
+    return (`  ${badge} ${ext.name}${version}${verified}  (${ext.kind})${tags}${desc}\n` +
+        `    Install: dd add ${ext.name}@${ext.marketplace}`);
+}
+// ---------------------------------------------------------------------------
+// Browse command
+// ---------------------------------------------------------------------------
+export async function browse(args) {
+    const paths = resolveWorkspacePaths();
+    const known = readKnownMarketplaces(paths.root);
+    if (Object.keys(known.marketplaces).length === 0) {
+        console.log('\nNo marketplaces registered.\n\n' +
+            'Add one first:\n' +
+            '  dd marketplace add owner/repo\n');
+        return;
+    }
+    // Parse args: [marketplace] [--kind <kind>] [--search <query>]
+    let marketplaceName;
+    let kindFilter;
+    let searchQuery;
+    for (let i = 0; i < args.length; i++) {
+        if (args[i] === '--kind') {
+            i++;
+            kindFilter = args[i];
+        }
+        else if (args[i] === '--search' || args[i] === '-s') {
+            i++;
+            searchQuery = args[i]?.toLowerCase();
+        }
+        else if (!args[i].startsWith('--')) {
+            marketplaceName = args[i];
+        }
+    }
+    let extensions;
+    if (marketplaceName) {
+        // Specific marketplace
+        if (!(marketplaceName in known.marketplaces)) {
+            console.error(`\n❌ Marketplace "${marketplaceName}" is not registered.\n` +
+                '   Run `dd marketplace list` to see registered marketplaces.\n');
+            process.exit(1);
+        }
+        const cached = readCachedMarketplace(paths.root, marketplaceName);
+        if (!cached) {
+            console.log(`\nMarketplace "${marketplaceName}" has no cached catalog.\n` +
+                `Run: dd marketplace update ${marketplaceName}\n`);
+            return;
+        }
+        extensions = cached.manifest.extensions.map((e) => ({
+            ...e,
+            marketplace: marketplaceName,
+        }));
+    }
+    else {
+        // All marketplaces
+        extensions = getAllCachedExtensions(paths.root);
+    }
+    // Apply filters
+    if (kindFilter) {
+        extensions = extensions.filter((e) => e.kind === kindFilter);
+    }
+    if (searchQuery) {
+        extensions = extensions.filter((e) => e.name.toLowerCase().includes(searchQuery) ||
+            e.description?.toLowerCase().includes(searchQuery) ||
+            e.tags.some((t) => t.toLowerCase().includes(searchQuery)));
+    }
+    if (extensions.length === 0) {
+        const filterHint = searchQuery
+            ? ` matching "${searchQuery}"`
+            : kindFilter
+                ? ` of kind "${kindFilter}"`
+                : '';
+        console.log(`\nNo extensions found${filterHint}.\n` +
+            'Try `dd marketplace update` to refresh catalogs.\n');
+        return;
+    }
+    // Group by marketplace
+    const grouped = new Map();
+    for (const ext of extensions) {
+        const group = grouped.get(ext.marketplace) ?? [];
+        group.push(ext);
+        grouped.set(ext.marketplace, group);
+    }
+    console.log(`\n🏪 Available extensions (${extensions.length}):\n`);
+    for (const [mpName, exts] of grouped) {
+        if (grouped.size > 1) {
+            console.log(`  ── ${mpName} ──\n`);
+        }
+        for (const ext of exts) {
+            console.log(formatExtension(ext));
+            console.log('');
+        }
+    }
+}