@guidobuilds/forge-ai 0.6.0 → 0.8.0

package/dist/src/cli.js

@@ -5,14 +5,21 @@ import { readFileSync } from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { rm } from 'node:fs/promises';
+import { knownClaudeModels } from './adapters/claude-known.js';
+import { knownGrokModels } from './adapters/grok-known.js';
 import { formatDiagnostic, hasErrors } from './diagnostics.js';
-import { buildManifest, classifyPruneEntries, loadManifest, pruneEntries, resolveBackupPath, resolveBackupRoot, resolveManifestLocation, saveManifest, staleEntries } from './manifest.js';
-import { buildWritePlan, parsePlatform, parseScope } from './processor.js';
-import { runSelfUpdate } from './self-update.js';
+import { buildManifest, classifyPruneEntries, detectLegacyStateDrift, listInstalls, loadManifest, pruneEntries, resolveBackupPath, resolveBackupRoot, resolveManifestLocation, saveManifest, stateRoot, staleEntries } from './manifest.js';
+import { getModelPreference, loadModelPreferences, modelPreferencesPath, saveModelPreferences, setModelPreference } from './model-preferences.js';
+import { discoverOpenCodeModels } from './opencode-discovery.js';
+import { allowedInstallRoots } from './paths.js';
+import { supportsModel } from './platform-capabilities.js';
+import { buildWritePlan, discoverArtifacts, parsePlatform, parseScope, resolvePlatforms } from './processor.js';
+import { isValidVersionSpec, normalizeVersionSpec, runSelfUpdate } from './self-update.js';
 import { checkLatestVersion, formatVersionNotice } from './version-check.js';
 import { writeOutputs } from './writer.js';
 import { hasPendingDecisions } from './model.js';
-const emptyPrunePlan = { deletable: [], modifiedWithConsent: [], skippedMissing: [] };
+const emptyPrunePlan = { deletable: [], modifiedWithConsent: [], skippedMissing: [], skippedUnsafe: [] };
 export async function main(argv = process.argv.slice(2), promptIO = {}) {
     if (argv.length === 0 || argv[0] === '--help' || argv[0] === '-h') {
         showUsage();
@@ -42,8 +49,17 @@ export async function main(argv = process.argv.slice(2), promptIO = {}) {
             skipSpecUpdate: options.skipSpecUpdate,
         });
     }
+    if (command === 'uninstall') {
+        return runUninstall(options, promptIO);
+    }
+    if (command === 'list') {
+        return runList(promptIO);
+    }
+    if (command === 'configure') {
+        return runConfigure(options, promptIO);
+    }
     const versionCheckPromise = shouldCheckForUpdates(options, promptIO)
-        ? checkLatestVersion({ current: readPackageVersion(), cachePath: path.join(resolveHome(promptIO), '.forge-ai', 'version-check.json') }).catch(() => undefined)
+        ? checkLatestVersion({ current: readPackageVersion(), cachePath: path.join(stateRoot(resolveHome(promptIO)), 'version-check.json') }).catch(() => undefined)
         : Promise.resolve(undefined);
     try {
         const install = command === 'install' || command === 'update';
@@ -54,24 +70,44 @@ export async function main(argv = process.argv.slice(2), promptIO = {}) {
         const interactive = install && isInteractivePrompt(promptIO);
         if (interactive)
             p.intro(`${pc.bold('Forge AI')} ${pc.dim(command === 'update' ? 'updater' : 'installer')}`, clackIO(promptIO));
+        const cwd = process.cwd();
+        const home = resolveHome(promptIO);
+        const now = new Date();
         if (install) {
-            const prompted = await promptForMissingInstallOptions(options, promptIO);
+            const prompted = await promptForMissingInstallOptions(options, promptIO, cwd, home);
             if (!prompted) {
                 if (interactive)
                     p.cancel('Cancelled', clackIO(promptIO));
                 return 1;
             }
         }
-        const cwd = process.cwd();
-        const home = resolveHome(promptIO);
-        const now = new Date();
         let manifestLocation;
         let oldManifest;
         let backupRoot;
+        let modelPreferences;
         if (install) {
             manifestLocation = await resolveManifestLocation(options.scope, cwd, home);
             oldManifest = await loadManifest(manifestLocation.manifestPath);
             backupRoot = resolveBackupRoot(manifestLocation, now);
+            const drift = await detectLegacyStateDrift(manifestLocation, home);
+            if (drift)
+                console.error(`Warning: ${drift}`);
+            const prefsPath = modelPreferencesPath(manifestLocation);
+            modelPreferences = await loadModelPreferences(prefsPath);
+            if (options.modelExplicit || options.modelMapExplicit) {
+                const { artifacts } = await discoverArtifacts(options.source);
+                const applied = applyModelFlags(modelPreferences, options, artifacts);
+                if ('error' in applied) {
+                    console.error(applied.error);
+                    return 1;
+                }
+                modelPreferences = applied.preferences;
+                await saveModelPreferences(prefsPath, modelPreferences);
+            }
+            else if (options.pendingModelPreferences) {
+                modelPreferences = options.pendingModelPreferences;
+                await saveModelPreferences(prefsPath, modelPreferences);
+            }
         }
         const plan = await buildWritePlan({
             source: options.source,
@@ -82,10 +118,13 @@ export async function main(argv = process.argv.slice(2), promptIO = {}) {
             manifest: oldManifest,
             backupRoot,
             checkCollisions: install,
+            modelPreferences,
         });
         let prunePlan = emptyPrunePlan;
+        let pruneRoots = [];
         if (install && command === 'update' && options.prune) {
-            prunePlan = await classifyPrune(oldManifest, plan.files, backupRoot, options.scope, cwd, home);
+            pruneRoots = allowedInstallRoots(options.scope, home, cwd, oldManifest?.projectPath);
+            prunePlan = await classifyPrune(oldManifest, plan.files, backupRoot, options.scope, cwd, home, pruneRoots);
         }
         const needsConfirm = install && !options.force && (hasPendingDecisions(plan.pending) || prunePlan.modifiedWithConsent.length > 0);
         if (install && !options.dryRun && needsConfirm) {
@@ -117,8 +156,8 @@ export async function main(argv = process.argv.slice(2), promptIO = {}) {
                 try {
                     await writeOutputs(plan.files);
                     if (command === 'update' && options.prune)
-                        await pruneEntries([...prunePlan.deletable, ...prunePlan.modifiedWithConsent]);
-                    await saveManifest(manifestLocation.manifestPath, await buildManifest(manifestLocation, plan.files));
+                        await pruneEntries([...prunePlan.deletable, ...prunePlan.modifiedWithConsent], pruneRoots);
+                    await saveManifest(manifestLocation.manifestPath, await buildManifest(manifestLocation, plan.files, readPackageVersion(), now, oldManifest));
                     spinner.stop(`Wrote ${plan.files.length} file(s).`);
                 }
                 catch (error) {
@@ -129,8 +168,8 @@ export async function main(argv = process.argv.slice(2), promptIO = {}) {
             else {
                 await writeOutputs(plan.files);
                 if (command === 'update' && options.prune)
-                    await pruneEntries([...prunePlan.deletable, ...prunePlan.modifiedWithConsent]);
-                await saveManifest(manifestLocation.manifestPath, await buildManifest(manifestLocation, plan.files));
+                    await pruneEntries([...prunePlan.deletable, ...prunePlan.modifiedWithConsent], pruneRoots);
+                await saveManifest(manifestLocation.manifestPath, await buildManifest(manifestLocation, plan.files, readPackageVersion(), now, oldManifest));
                 console.log(`Wrote ${plan.files.length} file(s).`);
                 const totalDeleted = prunePlan.deletable.length + prunePlan.modifiedWithConsent.length;
                 if (command === 'update' && options.prune && totalDeleted > 0)
@@ -156,7 +195,7 @@ export async function main(argv = process.argv.slice(2), promptIO = {}) {
     }
 }
 function parseArgs(argv) {
-    const options = { command: argv[0], platform: 'all', scope: 'user', source: '.', dryRun: false, force: false, prune: true, yes: false, noUpdateCheck: false, skipSpecUpdate: false, platformExplicit: false, scopeExplicit: false, sourceExplicit: false };
+    const options = { command: argv[0], platform: 'all', scope: 'user', source: '.', dryRun: false, force: false, prune: true, yes: false, noUpdateCheck: false, skipSpecUpdate: false, platformExplicit: false, scopeExplicit: false, sourceExplicit: false, modelExplicit: false, modelMapExplicit: false };
     for (let index = 1; index < argv.length; index += 1) {
         const arg = argv[index];
         if (arg === '--dry-run')
@@ -175,7 +214,9 @@ function parseArgs(argv) {
             const value = argv[++index];
             if (!value)
                 return { error: 'Missing --to value' };
-            options.targetVersion = value;
+            if (!isValidVersionSpec(value))
+                return { error: `Invalid --to ${value}; expected a semver or "latest"` };
+            options.targetVersion = normalizeVersionSpec(value);
         }
         else if (arg === '--platform') {
             const value = argv[++index];
@@ -200,6 +241,23 @@ function parseArgs(argv) {
             options.source = value;
             options.sourceExplicit = true;
         }
+        else if (arg === '--model') {
+            const value = argv[++index];
+            if (!value)
+                return { error: 'Missing --model value' };
+            options.model = value;
+            options.modelExplicit = true;
+        }
+        else if (arg === '--model-map') {
+            const value = argv[++index];
+            if (!value)
+                return { error: 'Missing --model-map value' };
+            const modelMap = parseModelMap(value);
+            if (!modelMap)
+                return { error: `Invalid --model-map ${value}; expected name=model,name2=model2` };
+            options.modelMap = modelMap;
+            options.modelMapExplicit = true;
+        }
         else {
             return { error: `Unknown argument ${arg}` };
         }
@@ -211,31 +269,45 @@ function parseArgs(argv) {
         return { error: 'validate only accepts --platform and --source' };
     if (command !== 'self-update' && (options.targetVersion !== undefined || options.skipSpecUpdate))
         return { error: '--to and --skip-spec-update are only accepted for self-update' };
+    if ((options.modelExplicit || options.modelMapExplicit) && (command !== 'install' && command !== 'update' && command !== 'configure'))
+        return { error: '--model and --model-map are only accepted for install, update, and configure' };
+    if ((options.modelExplicit || options.modelMapExplicit) && (!options.platformExplicit || options.platform === 'all'))
+        return { error: '--model and --model-map require an explicit single --platform (model ids are not portable across platforms)' };
     if (command === 'self-update' && (options.platformExplicit || options.scopeExplicit || options.sourceExplicit || options.force || options.yes))
         return { error: 'self-update only accepts --to, --dry-run, --skip-spec-update' };
+    if (command === 'uninstall' && options.sourceExplicit)
+        return { error: 'uninstall does not accept --source' };
+    if (command === 'list' && (options.platformExplicit || options.scopeExplicit || options.sourceExplicit || options.dryRun || options.force || options.yes))
+        return { error: 'list does not accept any flags' };
+    if (command === 'configure' && (options.force || options.yes))
+        return { error: 'configure does not accept --force or --yes; use --model/--model-map for non-interactive use' };
     return { options };
 }
-async function classifyPrune(oldManifest, files, backupRoot, scope, cwd, home) {
+async function classifyPrune(oldManifest, files, backupRoot, scope, cwd, home, roots) {
     const stale = staleEntries(oldManifest, files);
-    const classified = await classifyPruneEntries(stale);
+    const classified = await classifyPruneEntries(stale, roots);
     const anchor = scope === 'user' ? home : cwd;
     const modifiedWithConsent = [];
     const skippedMissing = [];
+    const skippedUnsafe = [];
     for (const item of classified.skipped) {
         if (item.reason === 'checksum-mismatch')
             modifiedWithConsent.push({ ...item, backupPath: resolveBackupPath(backupRoot, item.path, anchor) });
+        else if (item.reason === 'unsafe-path')
+            skippedUnsafe.push(item);
         else
             skippedMissing.push(item);
     }
-    return { deletable: classified.deletable, modifiedWithConsent, skippedMissing };
+    return { deletable: classified.deletable, modifiedWithConsent, skippedMissing, skippedUnsafe };
 }
-async function promptForMissingInstallOptions(options, promptIO) {
+async function promptForMissingInstallOptions(options, promptIO, cwd, home) {
     if (options.yes)
         return true;
-    if (options.platformExplicit && options.scopeExplicit)
-        return true;
     if (!isInteractivePrompt(promptIO))
         return true;
+    const modelFlagsGiven = options.modelExplicit || options.modelMapExplicit;
+    if (options.platformExplicit && options.scopeExplicit && modelFlagsGiven)
+        return true;
     const io = clackIO(promptIO);
     if (!options.platformExplicit) {
         const platform = await p.select({
@@ -268,8 +340,132 @@ async function promptForMissingInstallOptions(options, promptIO) {
             return false;
         options.scope = scope;
     }
+    if (!modelFlagsGiven) {
+        return promptForModelSelection(options, promptIO, cwd, home);
+    }
     return true;
 }
+function modelablePairs(artifacts, targetPlatforms) {
+    const pairs = [];
+    for (const platform of targetPlatforms) {
+        for (const artifact of artifacts) {
+            const effectiveKind = artifact[platform]?.kind ?? artifact.kind;
+            if (supportsModel(platform, effectiveKind))
+                pairs.push({ platform, artifact });
+        }
+    }
+    return pairs;
+}
+const CONFIRM_PROMPT_COUNT_ABOVE = 6;
+// Returns false only on user cancellation (Ctrl+C mid-prompt) — declining the "choose per agent"
+// path, or there being nothing to choose, both return true (proceed with defaults).
+async function promptForModelSelection(options, promptIO, cwd, home) {
+    const io = clackIO(promptIO);
+    const { artifacts } = await discoverArtifacts(options.source);
+    const targetPlatforms = resolvePlatforms(options.platform);
+    const pairs = modelablePairs(artifacts, targetPlatforms);
+    if (pairs.length === 0)
+        return true;
+    const mode = await p.select({
+        message: 'Model selection',
+        initialValue: 'default',
+        options: [
+            { value: 'default', label: "Use each agent's recommended default" },
+            { value: 'per-agent', label: 'Choose per agent' }
+        ],
+        ...io
+    });
+    if (p.isCancel(mode))
+        return false;
+    if (mode === 'default')
+        return true;
+    if (pairs.length > CONFIRM_PROMPT_COUNT_ABOVE) {
+        const proceed = await p.confirm({
+            message: `This will ask ${pairs.length} questions (one per agent per platform). Continue?`,
+            active: 'Continue',
+            inactive: 'Use defaults instead',
+            initialValue: true,
+            ...io
+        });
+        if (p.isCancel(proceed))
+            return false;
+        if (!proceed)
+            return true;
+    }
+    const manifestLocation = await resolveManifestLocation(options.scope, cwd, home);
+    let preferences = await loadModelPreferences(modelPreferencesPath(manifestLocation));
+    const discoveredOpenCodeModels = targetPlatforms.includes('opencode') ? discoverOpenCodeModels(cwd) : undefined;
+    for (const { platform, artifact } of pairs) {
+        const current = getModelPreference(preferences, platform, artifact.name) ?? artifact[platform]?.model;
+        const chosen = await promptForModelValue(platform, artifact.name, current, discoveredOpenCodeModels, promptIO);
+        if (chosen === undefined)
+            return false;
+        preferences = setModelPreference(preferences, platform, artifact.name, chosen);
+    }
+    options.pendingModelPreferences = preferences;
+    return true;
+}
+const CUSTOM_MODEL_VALUE = '__custom__';
+async function promptForModelValue(platform, artifactName, current, discoveredOpenCodeModels, promptIO) {
+    const io = clackIO(promptIO);
+    const knownChoices = platform === 'opencode' && discoveredOpenCodeModels ? discoveredOpenCodeModels
+        : platform === 'claude' ? [...knownClaudeModels]
+            : platform === 'grok' ? [...knownGrokModels]
+                : undefined;
+    if (knownChoices && knownChoices.length > 0) {
+        const initialValue = current && knownChoices.includes(current) ? current : knownChoices[0];
+        const choice = await p.select({
+            message: `Model for \`${artifactName}\` (${platform})`,
+            initialValue,
+            options: [...knownChoices.map((value) => ({ value, label: value })), { value: CUSTOM_MODEL_VALUE, label: 'Custom…' }],
+            ...io
+        });
+        if (p.isCancel(choice))
+            return undefined;
+        if (choice !== CUSTOM_MODEL_VALUE)
+            return choice;
+    }
+    const text = await p.text({
+        message: `Model for \`${artifactName}\` (${platform})`,
+        initialValue: current,
+        validate: (value) => (value && value.trim().length > 0 ? undefined : 'A model id is required'),
+        ...io
+    });
+    if (p.isCancel(text))
+        return undefined;
+    return text;
+}
+function parseModelMap(value) {
+    const result = {};
+    for (const pair of value.split(',')) {
+        const [name, model] = pair.split('=').map((part) => part?.trim());
+        if (!name || !model)
+            return undefined;
+        result[name] = model;
+    }
+    return Object.keys(result).length > 0 ? result : undefined;
+}
+function applyModelFlags(preferences, options, artifacts) {
+    const targetPlatforms = resolvePlatforms(options.platform);
+    const platform = targetPlatforms[0];
+    let next = preferences;
+    if (options.model) {
+        for (const artifact of artifacts) {
+            const effectiveKind = artifact[platform]?.kind ?? artifact.kind;
+            if (supportsModel(platform, effectiveKind))
+                next = setModelPreference(next, platform, artifact.name, options.model);
+        }
+    }
+    if (options.modelMap) {
+        const knownNames = new Set(artifacts.map((artifact) => artifact.name));
+        for (const [name, model] of Object.entries(options.modelMap)) {
+            if (!knownNames.has(name))
+                return { error: `--model-map references unknown artifact "${name}"` };
+            next = setModelPreference(next, platform, name, model);
+        }
+    }
+    return { preferences: next };
+}
 async function promptForUpdate(plan, prunePlan, backupRoot, promptIO) {
     if (!isInteractivePrompt(promptIO))
         return false;
@@ -296,6 +492,279 @@ async function promptForUpdate(plan, prunePlan, backupRoot, promptIO) {
         return undefined;
     return accepted;
 }
+async function runUninstall(options, promptIO) {
+    if (options.yes)
+        options.force = true;
+    const interactive = isInteractivePrompt(promptIO);
+    if (interactive)
+        p.intro(`${pc.bold('Forge AI')} ${pc.dim('uninstaller')}`, clackIO(promptIO));
+    const prompted = await promptForMissingUninstallOptions(options, promptIO);
+    if (!prompted) {
+        if (interactive)
+            p.cancel('Cancelled', clackIO(promptIO));
+        return 1;
+    }
+    const cwd = process.cwd();
+    const home = resolveHome(promptIO);
+    const now = new Date();
+    const manifestLocation = await resolveManifestLocation(options.scope, cwd, home);
+    const manifest = await loadManifest(manifestLocation.manifestPath);
+    const drift = await detectLegacyStateDrift(manifestLocation, home);
+    if (drift)
+        console.error(`Warning: ${drift}`);
+    if (!manifest || manifest.entries.length === 0) {
+        console.log(`Nothing to uninstall for ${options.scope} scope.`);
+        return 0;
+    }
+    const targeted = options.platform === 'all' ? manifest.entries : manifest.entries.filter((entry) => entry.platform === options.platform);
+    if (targeted.length === 0) {
+        console.log(`No ${options.platform} files recorded for this ${options.scope} install.`);
+        return 0;
+    }
+    const backupRoot = resolveBackupRoot(manifestLocation, now);
+    const anchor = options.scope === 'user' ? home : cwd;
+    const roots = allowedInstallRoots(options.scope, home, cwd, manifest.projectPath);
+    const classified = await classifyPruneEntries(targeted, roots);
+    const modifiedWithConsent = classified.skipped
+        .filter((item) => item.reason === 'checksum-mismatch')
+        .map((item) => ({ ...item, backupPath: resolveBackupPath(backupRoot, item.path, anchor) }));
+    const skippedMissing = classified.skipped.filter((item) => item.reason === 'missing');
+    const skippedUnsafe = classified.skipped.filter((item) => item.reason === 'unsafe-path');
+    const needsConfirm = !options.force && modifiedWithConsent.length > 0;
+    if (!options.dryRun && needsConfirm) {
+        if (!interactive) {
+            printUninstallPlan(classified.deletable, modifiedWithConsent, skippedMissing, skippedUnsafe);
+            console.error('Forge needs your decision on edited files; re-run with --yes or --force to accept deletion + backup.');
+            return 1;
+        }
+        const accepted = await promptForUninstall(classified.deletable, modifiedWithConsent, backupRoot, promptIO);
+        if (accepted === undefined) {
+            p.cancel('Cancelled', clackIO(promptIO));
+            return 1;
+        }
+        if (!accepted) {
+            p.outro(pc.yellow('Forge was not uninstalled.'), clackIO(promptIO));
+            return 1;
+        }
+    }
+    printUninstallPlan(classified.deletable, modifiedWithConsent, skippedMissing, skippedUnsafe);
+    if (options.dryRun) {
+        if (interactive)
+            p.outro(pc.cyan('Dry run complete.'), clackIO(promptIO));
+        return 0;
+    }
+    const toRemove = [...classified.deletable, ...modifiedWithConsent];
+    await pruneEntries(toRemove, roots);
+    const targetedPaths = new Set(targeted.map((entry) => entry.path));
+    const remaining = manifest.entries.filter((entry) => !targetedPaths.has(entry.path));
+    if (remaining.length === 0) {
+        await rm(manifestLocation.manifestPath, { force: true });
+    }
+    else {
+        await saveManifest(manifestLocation.manifestPath, { ...manifest, entries: remaining, updatedAt: now.toISOString() });
+    }
+    console.log(`Removed ${toRemove.length} file(s).`);
+    if (skippedMissing.length > 0)
+        console.log(`${skippedMissing.length} file(s) were already missing.`);
+    if (skippedUnsafe.length > 0)
+        console.error(`Warning: skipped ${skippedUnsafe.length} file(s) outside Forge's install roots (unsafe path); they were NOT removed.`);
+    if (interactive)
+        p.outro(pc.green('Forge was uninstalled.'), clackIO(promptIO));
+    return 0;
+}
+async function promptForMissingUninstallOptions(options, promptIO) {
+    if (options.yes)
+        return true;
+    if (options.platformExplicit && options.scopeExplicit)
+        return true;
+    if (!isInteractivePrompt(promptIO))
+        return true;
+    const io = clackIO(promptIO);
+    if (!options.platformExplicit) {
+        const platform = await p.select({
+            message: 'Uninstall Forge for which coding agent?',
+            initialValue: 'all',
+            options: [
+                { value: 'all', label: 'All supported agents', hint: 'OpenCode, Codex, Claude Code, and Grok Build' },
+                { value: 'opencode', label: 'OpenCode' },
+                { value: 'codex', label: 'Codex' },
+                { value: 'claude', label: 'Claude Code' },
+                { value: 'grok', label: 'Grok Build' }
+            ],
+            ...io
+        });
+        if (p.isCancel(platform))
+            return false;
+        options.platform = platform;
+    }
+    if (!options.scopeExplicit) {
+        const scope = await p.select({
+            message: 'Uninstall Forge from which scope?',
+            initialValue: 'user',
+            options: [
+                { value: 'user', label: 'User', hint: 'Installed for every project' },
+                { value: 'project', label: 'Project', hint: 'Only this repository' }
+            ],
+            ...io
+        });
+        if (p.isCancel(scope))
+            return false;
+        options.scope = scope;
+    }
+    return true;
+}
+async function promptForUninstall(deletable, modifiedWithConsent, backupRoot, promptIO) {
+    if (!isInteractivePrompt(promptIO))
+        return false;
+    const io = clackIO(promptIO);
+    p.log.warn(`${pc.yellow('Edited by you, will be deleted (backup):')}\n${modifiedWithConsent.map((entry) => `  - ${entry.path}`).join('\n')}\n\nBackups → ${backupRoot}`, io);
+    const accepted = await p.confirm({
+        message: 'Continue with deletion + backup?',
+        active: 'Continue',
+        inactive: 'Cancel',
+        initialValue: false,
+        ...io
+    });
+    if (p.isCancel(accepted))
+        return undefined;
+    return accepted;
+}
+function printUninstallPlan(deletable, modifiedWithConsent, skippedMissing, skippedUnsafe) {
+    console.log(`uninstall: ${deletable.length + modifiedWithConsent.length} file(s) to remove`);
+    for (const entry of deletable)
+        console.log(`- delete ${entry.platform} ${entry.kind} ${entry.name} -> ${entry.path}`);
+    for (const entry of modifiedWithConsent)
+        console.log(`- delete ${entry.platform} ${entry.kind} ${entry.name} -> ${entry.path} [backup -> ${entry.backupPath}]`);
+    for (const entry of skippedMissing)
+        console.log(`- skip missing ${entry.platform} ${entry.kind} ${entry.name} -> ${entry.path}`);
+    for (const entry of skippedUnsafe)
+        console.log(`- skip unsafe ${entry.platform} ${entry.kind} ${entry.name} -> ${entry.path}`);
+}
+async function runList(promptIO) {
+    const home = resolveHome(promptIO);
+    const summaries = await listInstalls(home);
+    if (summaries.length === 0) {
+        console.log('No Forge installs recorded.');
+        return 0;
+    }
+    for (const summary of summaries) {
+        console.log(formatInstallSummary(summary));
+        if (summary.driftWarning)
+            console.error(`Warning: ${summary.driftWarning}`);
+    }
+    return 0;
+}
+function formatInstallSummary(summary) {
+    const target = summary.scope === 'user' ? 'user' : `project ${summary.projectPath ?? '(unknown path)'}`;
+    const platforms = summary.platforms.length > 0 ? summary.platforms.join(', ') : 'none';
+    return `${target}: forge ${summary.forgeVersion}, ${summary.fileCount} file(s), platforms: ${platforms}, updated ${summary.updatedAt}`;
+}
+async function runConfigure(options, promptIO) {
+    const interactive = isInteractivePrompt(promptIO);
+    if (interactive)
+        p.intro(`${pc.bold('Forge AI')} ${pc.dim('configure')}`, clackIO(promptIO));
+    if (!options.scopeExplicit) {
+        if (!interactive) {
+            console.error('forge-ai configure needs --scope when not run interactively.');
+            return 1;
+        }
+        const scope = await p.select({
+            message: 'Configure which scope?',
+            initialValue: 'user',
+            options: [
+                { value: 'user', label: 'User', hint: 'Available in every project' },
+                { value: 'project', label: 'Project', hint: 'Only this repository' }
+            ],
+            ...clackIO(promptIO)
+        });
+        if (p.isCancel(scope)) {
+            p.cancel('Cancelled', clackIO(promptIO));
+            return 1;
+        }
+        options.scope = scope;
+    }
+    const cwd = process.cwd();
+    const home = resolveHome(promptIO);
+    const now = new Date();
+    const manifestLocation = await resolveManifestLocation(options.scope, cwd, home);
+    const manifest = await loadManifest(manifestLocation.manifestPath);
+    const drift = await detectLegacyStateDrift(manifestLocation, home);
+    if (drift)
+        console.error(`Warning: ${drift}`);
+    if (!manifest || manifest.entries.length === 0) {
+        console.log(`Nothing installed for ${options.scope} scope — run \`forge-ai install\` first.`);
+        return 0;
+    }
+    const installedPlatforms = [...new Set(manifest.entries.map((entry) => entry.platform))];
+    const targetPlatforms = options.platformExplicit ? installedPlatforms.filter((platform) => platform === options.platform) : installedPlatforms;
+    if (targetPlatforms.length === 0) {
+        console.log(`${options.platform} is not installed for ${options.scope} scope.`);
+        return 0;
+    }
+    const source = options.sourceExplicit ? options.source : bundledSourceRoot();
+    const { artifacts } = await discoverArtifacts(source);
+    const prefsPath = modelPreferencesPath(manifestLocation);
+    let preferences = await loadModelPreferences(prefsPath);
+    if (options.modelExplicit || options.modelMapExplicit) {
+        const applied = applyModelFlags(preferences, options, artifacts);
+        if ('error' in applied) {
+            console.error(applied.error);
+            return 1;
+        }
+        preferences = applied.preferences;
+    }
+    else {
+        if (!interactive) {
+            console.error('forge-ai configure needs --model or --model-map when not run interactively.');
+            return 1;
+        }
+        const pairs = modelablePairs(artifacts, targetPlatforms);
+        if (pairs.length === 0) {
+            console.log('No installed agent on the selected scope supports a configurable model.');
+            return 0;
+        }
+        const discoveredOpenCodeModels = targetPlatforms.includes('opencode') ? discoverOpenCodeModels(cwd) : undefined;
+        for (const { platform, artifact } of pairs) {
+            const current = getModelPreference(preferences, platform, artifact.name) ?? artifact[platform]?.model;
+            const chosen = await promptForModelValue(platform, artifact.name, current, discoveredOpenCodeModels, promptIO);
+            if (chosen === undefined) {
+                p.cancel('Cancelled', clackIO(promptIO));
+                return 1;
+            }
+            preferences = setModelPreference(preferences, platform, artifact.name, chosen);
+        }
+    }
+    await saveModelPreferences(prefsPath, preferences);
+    const backupRoot = resolveBackupRoot(manifestLocation, now);
+    let files = [];
+    let diagnostics = [];
+    for (const platform of targetPlatforms) {
+        const result = await buildWritePlan({ source, platform, scope: options.scope, cwd, home, manifest, backupRoot, checkCollisions: true, modelPreferences: preferences });
+        files = files.concat(result.files);
+        diagnostics = diagnostics.concat(result.diagnostics);
+    }
+    console.log(`configure: ${files.length} file(s) to update`);
+    for (const file of files)
+        console.log(`- ${file.platform} ${file.kind} ${file.name} -> ${file.path}${statusSuffix(file)}`);
+    for (const item of diagnostics)
+        console.log(formatDiagnostic(item));
+    if (hasErrors(diagnostics)) {
+        if (interactive)
+            p.outro(pc.red('Forge was not reconfigured.'), clackIO(promptIO));
+        return 1;
+    }
+    if (options.dryRun) {
+        if (interactive)
+            p.outro(pc.cyan('Dry run complete. Model preferences were saved; files were not written.'), clackIO(promptIO));
+        return 0;
+    }
+    await writeOutputs(files);
+    await saveManifest(manifestLocation.manifestPath, await buildManifest(manifestLocation, files, readPackageVersion(), now, manifest));
+    console.log(`Updated ${files.length} file(s) with new model preferences.`);
+    if (interactive)
+        p.outro(pc.green('Forge is reconfigured.'), clackIO(promptIO));
+    return 0;
+}
 function normalizeCommand(command) {
     if (command === 'install' || command === 'i')
         return 'install';
@@ -303,6 +772,12 @@ function normalizeCommand(command) {
         return 'update';
     if (command === 'validate')
         return 'validate';
+    if (command === 'uninstall')
+        return 'uninstall';
+    if (command === 'list' || command === 'ls')
+        return 'list';
+    if (command === 'configure')
+        return 'configure';
     if (command === 'self-update')
         return 'self-update';
     return undefined;
@@ -344,11 +819,15 @@ function readPackageVersion() {
     }
 }
 function showUsage() {
-    console.log('Usage: forge-ai install [--platform opencode|claude|codex|grok|all] [--scope user|project] [--source <dir>] [--dry-run] [--force] [--yes]');
-    console.log('       forge-ai update [--platform opencode|claude|codex|grok|all] [--scope user|project] [--source <dir>] [--dry-run] [--no-prune] [--yes]');
+    console.log('Usage: forge-ai install [--platform opencode|claude|codex|grok|all] [--scope user|project] [--source <dir>] [--dry-run] [--force] [--yes] [--model <id>] [--model-map name=model,...]');
+    console.log('       forge-ai update [--platform opencode|claude|codex|grok|all] [--scope user|project] [--source <dir>] [--dry-run] [--no-prune] [--yes] [--model <id>] [--model-map name=model,...]');
+    console.log('       forge-ai uninstall [--platform opencode|claude|codex|grok|all] [--scope user|project] [--dry-run] [--force] [--yes]');
+    console.log('       forge-ai list');
+    console.log('       forge-ai configure [--platform opencode|claude|codex|grok] [--scope user|project] [--source <dir>] [--dry-run] [--model <id>] [--model-map name=model,...]');
     console.log('       forge-ai validate [--platform opencode|claude|codex|grok|all] [--source <dir>]');
     console.log('       forge-ai self-update [--to <version>] [--dry-run] [--skip-spec-update]');
     console.log('');
+    console.log('--model and --model-map require an explicit single --platform (model ids are not portable across platforms).');
     console.log('Global flags: --no-update-check (also FORGE_NO_UPDATE_CHECK=1 or CI=true)');
 }
 function printPlan(command, sourceCount, files, diagnostics, prunePlan) {
@@ -361,6 +840,8 @@ function printPlan(command, sourceCount, files, diagnostics, prunePlan) {
         console.log(`- delete stale ${item.platform} ${item.kind} ${item.name} -> ${item.path} [backup -> ${item.backupPath}]`);
     for (const item of prunePlan.skippedMissing)
         console.log(`- skip missing ${item.platform} ${item.kind} ${item.name} -> ${item.path}`);
+    for (const item of prunePlan.skippedUnsafe)
+        console.log(`- skip unsafe ${item.platform} ${item.kind} ${item.name} -> ${item.path}`);
     for (const item of diagnostics)
         console.log(formatDiagnostic(item));
 }