@guidobuilds/forge-ai 0.7.0 → 0.9.0

package/dist/src/cli.js

@@ -5,15 +5,22 @@ 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 { knownCodexModels } from './adapters/codex-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 { runBuildPlugin } from './build-plugin.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 { discoverModels, mergeLiveWithCurated } from './model-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();
@@ -43,19 +50,19 @@ 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 {
-        if (command === 'build-plugin') {
-            return await runBuildPlugin({
-                source: options.sourceExplicit ? options.source : bundledSourceRoot(),
-                outDir: options.out,
-                target: options.target,
-                dryRun: options.dryRun,
-                force: options.force,
-            });
-        }
         const install = command === 'install' || command === 'update';
         if (install && !options.sourceExplicit)
             options.source = bundledSourceRoot();
@@ -64,24 +71,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,
@@ -92,10 +119,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) {
@@ -127,8 +157,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) {
@@ -139,8 +169,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)
@@ -166,7 +196,7 @@ export async function main(argv = process.argv.slice(2), promptIO = {}) {
     }
 }
 function parseArgs(argv) {
-    const options = { command: argv[0], platform: 'all', scope: 'user', source: '.', out: path.join(process.cwd(), 'forge-plugin'), target: 'claude', outExplicit: false, 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')
@@ -185,7 +215,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];
@@ -210,20 +242,22 @@ function parseArgs(argv) {
             options.source = value;
             options.sourceExplicit = true;
         }
-        else if (arg === '--out') {
+        else if (arg === '--model') {
             const value = argv[++index];
             if (!value)
-                return { error: 'Missing --out value' };
-            options.out = value;
-            options.outExplicit = true;
+                return { error: 'Missing --model value' };
+            options.model = value;
+            options.modelExplicit = true;
         }
-        else if (arg === '--target') {
+        else if (arg === '--model-map') {
             const value = argv[++index];
-            if (value !== 'claude' && value !== 'codex')
-                return { error: `Invalid --target ${value ?? ''}; expected claude or codex` };
-            options.target = value;
-            if (!options.outExplicit)
-                options.out = path.join(process.cwd(), value === 'claude' ? 'forge-plugin' : 'plugins/forge');
+            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}` };
@@ -236,33 +270,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 === 'build-plugin' && (options.platformExplicit || options.scopeExplicit || options.yes))
-        return { error: 'build-plugin only accepts --target, --source, --out, --dry-run, --force' };
+    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({
@@ -295,8 +341,185 @@ 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 modelablePlatforms = [...new Set(pairs.map((pair) => pair.platform))];
+    const discovered = discoverModelChoices(modelablePlatforms, cwd, promptIO);
+    for (const { platform, artifact } of pairs) {
+        const current = getModelPreference(preferences, platform, artifact.name) ?? artifact[platform]?.model;
+        const chosen = await promptForModelValue(platform, artifact.name, current, discovered, promptIO);
+        if (chosen === undefined)
+            return false;
+        preferences = setModelPreference(preferences, platform, artifact.name, chosen);
+    }
+    options.pendingModelPreferences = preferences;
     return true;
 }
+const CUSTOM_MODEL_VALUE = '__custom__';
+// Pure label helper: suffixes a live-derived value's *label* with ` (live)` so the user can tell live
+// options from curated/merged extras. The select **value** stays the bare model id, so stored
+// preferences and `initialValue` matching are unchanged. Curated extras and the `Custom…` escape are
+// never in the live set, so they are never suffixed.
+export function withLiveLabels(values, liveSet) {
+    return values.map((value) => ({ value, label: liveSet.has(value) ? `${value} (live)` : value }));
+}
+// Curated model suggestions for the interactive per-agent model prompt, or undefined when there is
+// no fixed list (the prompt then falls back to free text). Discovery results are live-first, highest
+// priority. Each platform is an explicit branch — a missing branch fails loudly rather than silently
+// producing a "no choices" path (see the codex-model-options regression in .forge/lessons.md):
+//   opencode: live, else free-text (undefined) — no curated set.
+//   codex:    live, NO merge (the live catalog is the real account-filtered set; merging stale curated
+//             suggestions would present ids the user may not be able to select); curated on failure.
+//   grok:     live + curated extras merged (dedupe, stable order) — `grok models` doesn't advertise the
+//             Forge-specific aliases, so they must survive a successful live query; curated on failure.
+//   claude:   curated always — no dynamic source, never empty/undefined.
+export function modelChoicesFor(platform, discovered = {}) {
+    const live = discovered[platform];
+    if (platform === 'opencode')
+        return live && live.length > 0 ? live : undefined;
+    if (platform === 'claude')
+        return [...knownClaudeModels];
+    if (platform === 'codex')
+        return live && live.length > 0 ? live : [...knownCodexModels];
+    if (platform === 'grok')
+        return live && live.length > 0 ? mergeLiveWithCurated(live, knownGrokModels) : [...knownGrokModels];
+    return undefined;
+}
+async function promptForModelValue(platform, artifactName, current, discovered, promptIO) {
+    const io = clackIO(promptIO);
+    const knownChoices = modelChoicesFor(platform, discovered);
+    if (knownChoices && knownChoices.length > 0) {
+        const initialValue = current && knownChoices.includes(current) ? current : knownChoices[0];
+        const liveSet = new Set(discovered[platform] ?? []);
+        const choice = await p.select({
+            message: `Model for \`${artifactName}\` (${platform})`,
+            initialValue,
+            options: [...withLiveLabels(knownChoices, liveSet), { 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;
+}
+// Compute the per-platform discovery map once per CLI run, scoped to the deduped set of platforms that
+// actually have a modelable pair in this run (so e.g. `install --platform all` with no Codex agent
+// artifact never sparks a needless `codex debug models` spawn). Discovery is synchronous (spawnSync).
+// A failed non-claude discovery emits a single info diagnostic. `claude` is skipped because it has no
+// dynamic source by design (not because it failed). The diagnostic is rendered inside the clack frame
+// (p.log.warn) when the run is interactive so it doesn't corrupt the TUI (raw console.error writes to
+// stderr, the same terminal clack draws on, which clack does not redraw/clear — see lessons.md
+// dynamic-model-discovery); console.error is only the non-interactive fallback.
+function discoverModelChoices(platforms, cwd, promptIO) {
+    const discovered = {};
+    for (const platform of platforms) {
+        const models = discoverModels(platform, cwd);
+        if (models && models.length > 0) {
+            discovered[platform] = models;
+        }
+        else if (platform !== 'claude') {
+            const note = `forge: model discovery for ${platform} failed; using curated fallback.`;
+            if (isInteractivePrompt(promptIO))
+                p.log.warn(note, clackIO(promptIO));
+            else
+                console.error(note);
+        }
+    }
+    return discovered;
+}
+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;
@@ -323,6 +546,280 @@ 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 modelablePlatforms = [...new Set(pairs.map((pair) => pair.platform))];
+        const discovered = discoverModelChoices(modelablePlatforms, cwd, promptIO);
+        for (const { platform, artifact } of pairs) {
+            const current = getModelPreference(preferences, platform, artifact.name) ?? artifact[platform]?.model;
+            const chosen = await promptForModelValue(platform, artifact.name, current, discovered, 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';
@@ -330,10 +827,14 @@ 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';
-    if (command === 'build-plugin')
-        return 'build-plugin';
     return undefined;
 }
 function shouldCheckForUpdates(options, promptIO) {
@@ -373,12 +874,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('       forge-ai build-plugin [--target claude|codex] [--out <dir>] [--source <dir>] [--dry-run] [--force]');
     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) {
@@ -391,6 +895,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));
 }