@osovv/vvcode 0.4.1 → 0.5.1

package/README.md

@@ -8,14 +8,20 @@
 bun add -g @osovv/vvcode
 ```
 
-Or for local development:
+For local development from this repo:
 
 ```bash
 bun install
 bun run cli -- --help
 ```
 
-## Runtime config
+## Config layout
+
+Global config path:
+
+```text
+~/.config/vvcode/config.jsonc
+```
 
 Project config path:
 
@@ -23,30 +29,101 @@ Project config path:
 .vvcode/config.jsonc
 ```
 
-Default global config path:
+The current behavior is:
 
-```text
-~/.config/vvcode/config.jsonc
+1. Global config is the source of shared presets and profiles.
+2. Project config is optional for launch if a project root already exists.
+3. `vvcode init` creates a minimal project config scaffold.
+4. `vvcode preset add <name>` copies a preset from global config into the project config.
+5. `vvcode preset remove <name>` removes a copied project preset and prunes unused copied profiles.
+
+## Quick start
+
+Initialize a project-local config:
+
+```bash
+vvcode init
+```
+
+See which presets are available:
+
+```bash
+vvcode preset list
+```
+
+Copy a global preset into the current project:
+
+```bash
+vvcode preset add openai
+```
+
+Launch OpenCode with a preset:
+
+```bash
+vvcode opencode --preset openai
+```
+
+Or use the shorthand form:
+
+```bash
+vvcode --preset openai
+```
+
+## Commands
+
+Show help:
+
+```bash
+vvcode help
+vvcode --help
+```
+
+Initialize project config:
+
+```bash
+vvcode init
+vvcode init --project-root /path/to/project
 ```
 
-## Usage
+Launch OpenCode:
 
 ```bash
 vvcode opencode --preset <name>
+vvcode --preset <name>
+```
+
+By default `vvcode` starts the shell with:
+
+```bash
+opencode
+```
+
+You can override the shell command, for example:
+
+```bash
+OPENCODE_SHELL_COMMAND='bun x opencode-ai' vvcode --preset openai
 ```
 
 Options:
 
-- `--preset`, `-p` (required)
-- `--global-config`, `-c` (optional)
-- `--project-root`, `-r` (optional)
+1. `--preset`, `-p` for the preset name.
+2. `--global-config`, `-c` to override the global config file path.
+3. `--project-root`, `-r` to launch from a different project root.
 
-You can also omit `opencode` because it is the default subcommand:
+Manage presets:
 
 ```bash
-vvcode --preset <name>
+vvcode preset list
+vvcode preset add <preset-name>
+vvcode preset remove <preset-name>
 ```
 
+`preset list` prints one preset per line with its source label:
+
+1. `global`
+2. `project`
+3. `project-overrides-global`
+
 ## Runtime artifacts
 
 - `.vvcode/local/runtime/overlays/`
@@ -60,9 +137,9 @@ vvcode --preset <name>
 ## Packaging notes
 
 - Package name: `@osovv/vvcode`
-- CLI bin: `bin/vvcode`
+- CLI bin: `vvcode`
 - Published runtime entry: `dist/vvcode.js`
 - Build command: `bun run build`
 - Local dev command: `bun run cli -- --help`
-- `prepack` builds `dist` automatically before publish/pack
+- `prepack` builds `dist` automatically before publish or pack
 - Scoped publish target: `npm publish --access=public`

package/dist/vvcode.js

@@ -543,11 +543,11 @@ function _getBuiltinFlags(long, short, userNames, userAliases) {
 
 // src/cli/vvcode.ts
 import { homedir } from "os";
-import { join as join3 } from "path";
+import { join as join3, resolve } from "path";
 // package.json
 var package_default = {
   name: "@osovv/vvcode",
-  version: "0.4.1",
+  version: "0.5.1",
   description: "Packaged CLI for launching OpenCode with vvcode runtime semantics.",
   license: "MIT",
   homepage: "https://github.com/osovv/vvcode",
@@ -565,7 +565,7 @@ var package_default = {
     "dist"
   ],
   bin: {
-    vvcode: "./bin/vvcode"
+    vvcode: "bin/vvcode"
   },
   publishConfig: {
     access: "public"
@@ -602,10 +602,6 @@ var package_default = {
   ]
 };
 
-// src/cli/pivv-opencode.ts
-import { rm } from "fs/promises";
-import { spawn } from "child_process";
-
 // src/config/load-pivv-config.ts
 class PivvConfigError extends Error {
   code;
@@ -628,9 +624,6 @@ async function loadPivvConfig(globalConfigPath, projectRoot) {
   for (const sourceCandidate of sourceCandidates) {
     const sourcePath = sourceCandidate.path;
     const sourceExists = await pathExists(sourcePath);
-    if (!sourceExists && sourceCandidate.sourceType === "project") {
-      throw new PivvConfigError("CONFIG_NOT_FOUND", `Project config not found at ${sourcePath}`);
-    }
     if (!sourceExists) {
       continue;
     }
@@ -674,6 +667,37 @@ async function findProjectRoot(projectRoot) {
   }
   throw new PivvConfigError("CONFIG_NOT_FOUND", `Unable to resolve project root from ${projectRoot}`);
 }
+function resolveProjectConfigPath(projectRoot) {
+  return joinPath(resolvePath(projectRoot), PROJECT_CONFIG_PATH);
+}
+function createEmptyRawVvcodeConfig() {
+  return {
+    profiles: {},
+    presets: {},
+    memory: {},
+    overlay: {}
+  };
+}
+async function readOptionalRawVvcodeConfig(configPath) {
+  const normalizedPath = resolvePath(configPath);
+  if (!await pathExists(normalizedPath)) {
+    return null;
+  }
+  return readJsoncConfig(normalizedPath);
+}
+async function writeRawVvcodeConfig(configPath, config) {
+  const normalizedPath = resolvePath(configPath);
+  const fsPromises = await getFsPromises();
+  const stableConfig = {
+    profiles: isRecord(config.profiles) ? config.profiles : {},
+    presets: isRecord(config.presets) ? config.presets : {},
+    memory: isRecord(config.memory) ? config.memory : {},
+    overlay: isRecord(config.overlay) ? config.overlay : {}
+  };
+  await fsPromises.mkdir(getParentPath(normalizedPath), { recursive: true });
+  await fsPromises.writeFile(normalizedPath, `${JSON.stringify(stableConfig, null, 2)}
+`, "utf-8");
+}
 function normalizeConfig(rawConfig, projectRoot, configSources) {
   if (!isRecord(rawConfig)) {
     throw new PivvConfigError("CONFIG_INVALID", "Config root must be an object");
@@ -899,6 +923,10 @@ function normalizePath(path) {
   return withSingleSlashes;
 }
 
+// src/cli/pivv-opencode.ts
+import { rm } from "fs/promises";
+import { spawn } from "child_process";
+
 // src/opencode/build-runtime-overlay.ts
 import { mkdir, writeFile } from "fs/promises";
 import { join } from "path";
@@ -1331,7 +1359,8 @@ function createTraceWriteError(message, cause) {
 // src/cli/pivv-opencode.ts
 var LAUNCHER_LOG_PREFIX = "[VvcodeLauncher]";
 var BLOCK_LOAD_ACTIVE_PRESET = "BLOCK_LOAD_ACTIVE_PRESET";
-var OPENCODE_ENTRYPOINT = "bun x opencode-ai";
+var DEFAULT_OPENCODE_SHELL_COMMAND = "opencode";
+var OPENCODE_SHELL_COMMAND_ENV = "OPENCODE_SHELL_COMMAND";
 function buildRuntimeEnvironment(runtimeOverlay, baseEnvironment = process.env) {
   const runtimeEnvironment = {};
   for (const [key, value] of Object.entries(baseEnvironment)) {
@@ -1340,7 +1369,12 @@ function buildRuntimeEnvironment(runtimeOverlay, baseEnvironment = process.env)
     }
   }
   runtimeEnvironment.OPENCODE_CONFIG_DIR = runtimeOverlay.overlayDirPath;
-  runtimeEnvironment.OPENCODE_CONFIG_CONTENT = JSON.stringify(runtimeOverlay);
+  runtimeEnvironment.OPENCODE_CONFIG_CONTENT = JSON.stringify({
+    provider: normalizeProviderConfig(runtimeOverlay.providers),
+    agent: runtimeOverlay.agents,
+    command: normalizeCommandConfig(runtimeOverlay.commands),
+    tools: runtimeOverlay.tools
+  });
   return runtimeEnvironment;
 }
 async function runPivvOpencode(cliArgs) {
@@ -1355,6 +1389,8 @@ async function runPivvOpencode(cliArgs) {
   let aliasModelCount = 0;
   let providerIds = [];
   let lifecycleStage = "config.load";
+  const openCodeShellCommand = resolveOpenCodeShellCommand();
+  const openCodeEntrypoint = openCodeShellCommand.entrypoint;
   if (!traceRecorder) {
     try {
       resolvedProjectRoot = await findProjectRoot(cliArgs.projectRoot);
@@ -1373,7 +1409,7 @@ async function runPivvOpencode(cliArgs) {
       preset: cliArgs.preset,
       projectRoot: resolvedProjectRoot,
       cwd: resolvedProjectRoot,
-      entrypoint: OPENCODE_ENTRYPOINT
+      entrypoint: openCodeEntrypoint
     }
   });
   try {
@@ -1387,7 +1423,7 @@ async function runPivvOpencode(cliArgs) {
         preset: cliArgs.preset,
         projectRoot: resolvedProjectRoot,
         cwd: resolvedProjectRoot,
-        entrypoint: OPENCODE_ENTRYPOINT
+        entrypoint: openCodeEntrypoint
       }
     });
     const projectConfig = await loadPivvConfig(cliArgs.globalConfigPath, cliArgs.projectRoot);
@@ -1402,7 +1438,7 @@ async function runPivvOpencode(cliArgs) {
         preset: cliArgs.preset,
         projectRoot: resolvedProjectRoot,
         cwd: resolvedProjectRoot,
-        entrypoint: OPENCODE_ENTRYPOINT
+        entrypoint: openCodeEntrypoint
       }
     });
     lifecycleStage = "preset.resolve";
@@ -1416,7 +1452,7 @@ async function runPivvOpencode(cliArgs) {
         preset: cliArgs.preset,
         coreSlotsResolved: 0,
         cwd: resolvedProjectRoot,
-        entrypoint: OPENCODE_ENTRYPOINT
+        entrypoint: openCodeEntrypoint
       }
     });
     const resolvedPreset = resolvePreset(cliArgs.preset, projectConfig);
@@ -1431,7 +1467,7 @@ async function runPivvOpencode(cliArgs) {
         profileCount: resolvedPreset.profileCount,
         coreSlotsResolved: Object.keys(resolvedPreset.coreProfiles).length,
         cwd: resolvedProjectRoot,
-        entrypoint: OPENCODE_ENTRYPOINT
+        entrypoint: openCodeEntrypoint
       }
     });
     lifecycleStage = "overlay.build";
@@ -1446,7 +1482,7 @@ async function runPivvOpencode(cliArgs) {
         aliasModelCount,
         providerIds,
         cwd: resolvedProjectRoot,
-        entrypoint: OPENCODE_ENTRYPOINT
+        entrypoint: openCodeEntrypoint
       }
     });
     const runtimeOverlay = await buildRuntimeOverlay(resolvedPreset, projectConfig, baseOpenCodeInputs);
@@ -1465,7 +1501,7 @@ async function runPivvOpencode(cliArgs) {
         aliasModelCount,
         providerIds,
         cwd: resolvedProjectRoot,
-        entrypoint: OPENCODE_ENTRYPOINT
+        entrypoint: openCodeEntrypoint
       }
     });
     lifecycleStage = "launch";
@@ -1483,7 +1519,7 @@ async function runPivvOpencode(cliArgs) {
         aliasModelCount,
         providerIds,
         cwd: resolvedProjectRoot,
-        entrypoint: OPENCODE_ENTRYPOINT
+        entrypoint: openCodeEntrypoint
       }
     });
     const launchResult = await launchOpenCodeProcess({
@@ -1491,7 +1527,8 @@ async function runPivvOpencode(cliArgs) {
       projectRoot: resolvedProjectRoot,
       runtimeOverlay,
       runtimeEnvironment,
-      traceContext
+      traceContext,
+      openCodeShellCommand
     });
     if (launchResult.exitCode !== 0) {
       const cleanupResult = await cleanupRuntimeOverlay(runtimeOverlayPath);
@@ -1503,7 +1540,8 @@ async function runPivvOpencode(cliArgs) {
         exitCode: launchResult.exitCode,
         cleanupResult,
         aliasModelCount,
-        providerIds
+        providerIds,
+        entrypoint: openCodeEntrypoint
       });
       return failureResult;
     }
@@ -1520,7 +1558,7 @@ async function runPivvOpencode(cliArgs) {
         aliasModelCount,
         providerIds,
         cwd: resolvedProjectRoot,
-        entrypoint: OPENCODE_ENTRYPOINT
+        entrypoint: openCodeEntrypoint
       }
     });
     const runFinishTrace = await persistLaunchTrace(traceRecorder, traceContext, {
@@ -1535,7 +1573,7 @@ async function runPivvOpencode(cliArgs) {
         projectRoot: resolvedProjectRoot,
         runtimeOverlayPath,
         cwd: resolvedProjectRoot,
-        entrypoint: OPENCODE_ENTRYPOINT
+        entrypoint: openCodeEntrypoint
       }
     });
     console.info(`${LAUNCHER_LOG_PREFIX}[runPivvOpencode][${BLOCK_LOAD_ACTIVE_PRESET}] launch completed`, {
@@ -1565,7 +1603,7 @@ async function runPivvOpencode(cliArgs) {
           preset: cliArgs.preset,
           projectRoot: resolvedProjectRoot,
           cwd: resolvedProjectRoot,
-          entrypoint: OPENCODE_ENTRYPOINT
+          entrypoint: openCodeEntrypoint
         }
       });
     }
@@ -1581,7 +1619,7 @@ async function runPivvOpencode(cliArgs) {
           projectRoot: resolvedProjectRoot,
           coreSlotsResolved: 0,
           cwd: resolvedProjectRoot,
-          entrypoint: OPENCODE_ENTRYPOINT
+          entrypoint: openCodeEntrypoint
         }
       });
     }
@@ -1599,7 +1637,7 @@ async function runPivvOpencode(cliArgs) {
           aliasModelCount,
           providerIds,
           cwd: resolvedProjectRoot,
-          entrypoint: OPENCODE_ENTRYPOINT
+          entrypoint: openCodeEntrypoint
         }
       });
     }
@@ -1612,7 +1650,8 @@ async function runPivvOpencode(cliArgs) {
       code: failureCode,
       cleanupResult,
       aliasModelCount,
-      providerIds
+      providerIds,
+      entrypoint: openCodeEntrypoint
     });
   }
 }
@@ -1672,7 +1711,7 @@ async function finalizeLaunchFailure(traceRecorder, traceContext, context) {
       aliasModelCount: context.aliasModelCount,
       providerIds: context.providerIds,
       cwd: context.projectRoot,
-      entrypoint: OPENCODE_ENTRYPOINT
+      entrypoint: context.entrypoint
     }
   });
   const runFailTrace = await persistLaunchTrace(traceRecorder, traceContext, {
@@ -1689,7 +1728,7 @@ async function finalizeLaunchFailure(traceRecorder, traceContext, context) {
       code: context.code,
       exitCode: context.exitCode,
       cwd: context.projectRoot,
-      entrypoint: OPENCODE_ENTRYPOINT
+      entrypoint: context.entrypoint
     }
   });
   console.info(`${LAUNCHER_LOG_PREFIX}[runPivvOpencode][${BLOCK_LOAD_ACTIVE_PRESET}] launch failed`, {
@@ -1711,7 +1750,7 @@ async function finalizeLaunchFailure(traceRecorder, traceContext, context) {
 }
 async function launchOpenCodeProcess(request) {
   return await new Promise((resolve, reject) => {
-    const launchedProcess = spawn("bun", ["x", "opencode-ai"], {
+    const launchedProcess = spawn(request.openCodeShellCommand.executable, request.openCodeShellCommand.args, {
       cwd: request.projectRoot,
       env: request.runtimeEnvironment,
       stdio: "inherit"
@@ -1726,10 +1765,127 @@ async function launchOpenCodeProcess(request) {
     });
   });
 }
+function resolveOpenCodeShellCommand(baseEnvironment = process.env) {
+  const configuredCommand = baseEnvironment[OPENCODE_SHELL_COMMAND_ENV]?.trim();
+  const entrypoint = configuredCommand && configuredCommand.length > 0 ? configuredCommand : DEFAULT_OPENCODE_SHELL_COMMAND;
+  const tokens = splitShellCommand(entrypoint);
+  if (tokens.length === 0) {
+    return {
+      executable: DEFAULT_OPENCODE_SHELL_COMMAND,
+      args: [],
+      entrypoint: DEFAULT_OPENCODE_SHELL_COMMAND
+    };
+  }
+  return {
+    executable: tokens[0],
+    args: tokens.slice(1),
+    entrypoint
+  };
+}
+function splitShellCommand(command) {
+  const tokens = [];
+  let current = "";
+  let quote = null;
+  for (let index = 0;index < command.length; index += 1) {
+    const character = command[index];
+    if (quote === null) {
+      if (character === '"' || character === "'") {
+        quote = character === '"' ? "double" : "single";
+        continue;
+      }
+      if (/\s/.test(character)) {
+        if (current.length > 0) {
+          tokens.push(current);
+          current = "";
+        }
+        continue;
+      }
+    } else if (quote === "double" && character === '"' || quote === "single" && character === "'") {
+      quote = null;
+      continue;
+    }
+    current += character;
+  }
+  if (current.length > 0) {
+    tokens.push(current);
+  }
+  return tokens;
+}
+function normalizeCommandConfig(commands) {
+  const normalizedCommands = {};
+  for (const [commandName, commandConfig] of Object.entries(commands)) {
+    const template = typeof commandConfig.prompt === "string" ? commandConfig.prompt : undefined;
+    if (!template) {
+      continue;
+    }
+    normalizedCommands[commandName] = {
+      template,
+      ...typeof commandConfig.description === "string" ? { description: commandConfig.description } : {},
+      ...typeof commandConfig.agent === "string" ? { agent: commandConfig.agent } : {},
+      ...typeof commandConfig.model === "string" ? { model: commandConfig.model } : {},
+      ...typeof commandConfig.subtask === "boolean" ? { subtask: commandConfig.subtask } : {}
+    };
+  }
+  return normalizedCommands;
+}
+function normalizeProviderConfig(providers) {
+  const normalizedProviders = {};
+  for (const [providerId, providerConfig] of Object.entries(providers)) {
+    const normalizedProvider = {};
+    for (const key of ["api", "name", "env", "id", "npm", "whitelist", "blacklist", "options"]) {
+      if (key in providerConfig) {
+        normalizedProvider[key] = providerConfig[key];
+      }
+    }
+    if (isRecord2(providerConfig.models)) {
+      const normalizedModels = {};
+      for (const [modelId, modelConfig] of Object.entries(providerConfig.models)) {
+        if (!isRecord2(modelConfig)) {
+          continue;
+        }
+        const normalizedModel = {};
+        for (const key of [
+          "id",
+          "name",
+          "family",
+          "release_date",
+          "attachment",
+          "reasoning",
+          "temperature",
+          "tool_call",
+          "interleaved",
+          "cost",
+          "limit",
+          "modalities",
+          "experimental",
+          "status",
+          "options",
+          "headers",
+          "variants"
+        ]) {
+          if (key in modelConfig) {
+            normalizedModel[key] = modelConfig[key];
+          }
+        }
+        if (isRecord2(modelConfig.provider)) {
+          normalizedModel.provider = modelConfig.provider;
+        }
+        normalizedModels[modelId] = normalizedModel;
+      }
+      normalizedProvider.models = normalizedModels;
+    }
+    normalizedProviders[providerId] = normalizedProvider;
+  }
+  return normalizedProviders;
+}
+function isRecord2(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
 
 // src/cli/vvcode.ts
 var CLI_LOG_PREFIX = "[VvcodeCli]";
 var BLOCK_RUN_OPENCODE_COMMAND = "BLOCK_RUN_OPENCODE_COMMAND";
+var KNOWN_TOP_LEVEL_COMMANDS = new Set(["help", "init", "opencode", "preset"]);
 function resolveDefaultGlobalConfigPath() {
   return join3(homedir(), ".config", "vvcode", "config.jsonc");
 }
@@ -1738,7 +1894,7 @@ function createVvcodeCommand(dependencyOverrides = {}) {
   const opencodeArgs = {
     preset: {
       type: "string",
-      description: "Preset name defined in .vvcode/config.jsonc.",
+      description: "Preset name defined in global or project vvcode config.",
       alias: ["p"],
       required: true
     },
@@ -1755,15 +1911,63 @@ function createVvcodeCommand(dependencyOverrides = {}) {
       default: dependencies.cwd()
     }
   };
+  const configManagementArgs = {
+    "global-config": {
+      type: "string",
+      description: "Path to the global vvcode config file.",
+      alias: ["c"],
+      default: dependencies.defaultGlobalConfigPath()
+    },
+    "project-root": {
+      type: "string",
+      description: "Project root where .vvcode/config.jsonc should be managed.",
+      alias: ["r"],
+      default: dependencies.cwd()
+    }
+  };
   return defineCommand({
     meta: {
       name: "vvcode",
       version: package_default.version,
       description: "Packaged CLI for launching OpenCode with vvcode runtime semantics."
     },
-    args: opencodeArgs,
-    default: "opencode",
     subCommands: {
+      help: defineCommand({
+        meta: {
+          name: "help",
+          description: "Show vvcode command help."
+        },
+        args: {
+          command: {
+            type: "positional",
+            description: "Optional subcommand name to show help for.",
+            required: false
+          }
+        },
+        async run({ args }) {
+          const helpArgs = typeof args.command === "string" && args.command.length > 0 ? [args.command, "--help"] : ["--help"];
+          await runMain(createVvcodeCommand(dependencyOverrides), { rawArgs: helpArgs });
+        }
+      }),
+      init: defineCommand({
+        meta: {
+          name: "init",
+          description: "Create a project-local .vvcode/config.jsonc scaffold."
+        },
+        args: {
+          "project-root": configManagementArgs["project-root"]
+        },
+        async run({ args }) {
+          const configPath = resolveProjectConfigPath(String(args.projectRoot));
+          const existingConfig = await readOptionalRawVvcodeConfig(configPath);
+          if (existingConfig !== null) {
+            dependencies.writeStdout(`vvcode: project config already exists at ${configPath}`);
+            return;
+          }
+          await writeRawVvcodeConfig(configPath, createEmptyRawVvcodeConfig());
+          dependencies.writeStdout(`vvcode: initialized project config at ${configPath}`);
+        }
+      }),
       opencode: defineCommand({
         meta: {
           name: "opencode",
@@ -1787,13 +1991,151 @@ function createVvcodeCommand(dependencyOverrides = {}) {
           }
           return launchResult;
         }
+      }),
+      preset: defineCommand({
+        meta: {
+          name: "preset",
+          description: "Inspect or manage project presets copied from global vvcode config."
+        },
+        default: "list",
+        subCommands: {
+          list: defineCommand({
+            meta: {
+              name: "list",
+              description: "List available presets from global and project config."
+            },
+            args: configManagementArgs,
+            async run({ args }) {
+              const snapshot = await loadProjectConfigSnapshot(String(args.globalConfig), String(args.projectRoot));
+              const presetNames = collectPresetNames(snapshot);
+              if (presetNames.length === 0) {
+                dependencies.writeStdout("vvcode: no presets found in global or project config");
+                return;
+              }
+              for (const presetName of presetNames) {
+                dependencies.writeStdout(`${presetName}	${describePresetSource(snapshot, presetName)}`);
+              }
+            }
+          }),
+          add: defineCommand({
+            meta: {
+              name: "add",
+              description: "Copy one preset and its referenced profiles from global config into the project config."
+            },
+            args: {
+              name: {
+                type: "positional",
+                description: "Preset name to copy into the project config.",
+                required: true
+              },
+              ...configManagementArgs
+            },
+            async run({ args }) {
+              const presetName = String(args.name);
+              const snapshot = await loadProjectConfigSnapshot(String(args.globalConfig), String(args.projectRoot));
+              const globalPresets = toObjectBucket(snapshot.globalConfig?.presets);
+              const globalProfiles = toObjectBucket(snapshot.globalConfig?.profiles);
+              if (!(presetName in globalPresets) || !isRecord3(globalPresets[presetName])) {
+                throw new Error(`Preset "${presetName}" was not found in global config ${snapshot.globalConfigPath}`);
+              }
+              const projectConfig = snapshot.projectConfig ?? createEmptyRawVvcodeConfig();
+              const projectPresets = toMutableBucket(projectConfig, "presets");
+              const projectProfiles = toMutableBucket(projectConfig, "profiles");
+              if (presetName in projectPresets) {
+                dependencies.writeStdout(`vvcode: preset "${presetName}" already exists in ${snapshot.projectConfigPath}`);
+                return;
+              }
+              const globalPreset = globalPresets[presetName];
+              const copiedProfiles = [];
+              const normalizedPreset = {};
+              for (const [slotName, profileNameValue] of Object.entries(globalPreset)) {
+                if (typeof profileNameValue !== "string" || profileNameValue.length === 0) {
+                  throw new Error(`Global preset "${presetName}" slot "${slotName}" must reference a non-empty profile name`);
+                }
+                const profileName = profileNameValue;
+                const globalProfile = globalProfiles[profileName];
+                if (!isRecord3(globalProfile)) {
+                  throw new Error(`Global preset "${presetName}" references missing profile "${profileName}"`);
+                }
+                if (profileName in projectProfiles) {
+                  if (!areJsonValuesEqual(projectProfiles[profileName], globalProfile)) {
+                    throw new Error(`Project config already defines profile "${profileName}" with different settings; remove it or rename the project profile before adding preset "${presetName}"`);
+                  }
+                } else {
+                  projectProfiles[profileName] = globalProfile;
+                  copiedProfiles.push(profileName);
+                }
+                normalizedPreset[slotName] = profileName;
+              }
+              projectPresets[presetName] = normalizedPreset;
+              await writeRawVvcodeConfig(snapshot.projectConfigPath, projectConfig);
+              dependencies.writeStdout(`vvcode: added preset "${presetName}" to ${snapshot.projectConfigPath} (copied ${copiedProfiles.length} profiles)`);
+            }
+          }),
+          remove: defineCommand({
+            meta: {
+              name: "remove",
+              description: "Remove one preset from the project config and prune unreferenced copied profiles."
+            },
+            args: {
+              name: {
+                type: "positional",
+                description: "Preset name to remove from the project config.",
+                required: true
+              },
+              "project-root": configManagementArgs["project-root"]
+            },
+            async run({ args }) {
+              const presetName = String(args.name);
+              const projectRoot = resolve(String(args.projectRoot));
+              const projectConfigPath = resolveProjectConfigPath(projectRoot);
+              const projectConfig = await readOptionalRawVvcodeConfig(projectConfigPath);
+              if (projectConfig === null) {
+                throw new Error(`Project config was not found at ${projectConfigPath}`);
+              }
+              const projectPresets = toMutableBucket(projectConfig, "presets");
+              const projectProfiles = toMutableBucket(projectConfig, "profiles");
+              const removedPreset = projectPresets[presetName];
+              if (!isRecord3(removedPreset)) {
+                throw new Error(`Preset "${presetName}" was not found in project config ${projectConfigPath}`);
+              }
+              delete projectPresets[presetName];
+              const stillReferencedProfiles = new Set;
+              for (const presetValue of Object.values(projectPresets)) {
+                if (!isRecord3(presetValue)) {
+                  continue;
+                }
+                for (const profileNameValue of Object.values(presetValue)) {
+                  if (typeof profileNameValue === "string" && profileNameValue.length > 0) {
+                    stillReferencedProfiles.add(profileNameValue);
+                  }
+                }
+              }
+              const removedProfiles = [];
+              for (const profileNameValue of Object.values(removedPreset)) {
+                if (typeof profileNameValue !== "string" || profileNameValue.length === 0) {
+                  continue;
+                }
+                if (stillReferencedProfiles.has(profileNameValue)) {
+                  continue;
+                }
+                if (profileNameValue in projectProfiles) {
+                  delete projectProfiles[profileNameValue];
+                  removedProfiles.push(profileNameValue);
+                }
+              }
+              await writeRawVvcodeConfig(projectConfigPath, projectConfig);
+              dependencies.writeStdout(`vvcode: removed preset "${presetName}" from ${projectConfigPath} (removed ${removedProfiles.length} profiles)`);
+            }
+          })
+        }
       })
     }
   });
 }
 async function runVvcodeCli(rawArgs = process.argv.slice(2), dependencyOverrides = {}) {
   const vvcodeCommand = createVvcodeCommand(dependencyOverrides);
-  await runMain(vvcodeCommand, { rawArgs });
+  await runMain(vvcodeCommand, { rawArgs: normalizeRawArgs(rawArgs) });
 }
 function resolveVvcodeCliDependencies(dependencyOverrides) {
   return {
@@ -1801,6 +2143,7 @@ function resolveVvcodeCliDependencies(dependencyOverrides) {
     cwd: dependencyOverrides.cwd ?? (() => process.cwd()),
     defaultGlobalConfigPath: dependencyOverrides.defaultGlobalConfigPath ?? resolveDefaultGlobalConfigPath,
     writeStderr: dependencyOverrides.writeStderr ?? ((message) => console.error(message)),
+    writeStdout: dependencyOverrides.writeStdout ?? ((message) => console.log(message)),
     setExitCode: dependencyOverrides.setExitCode ?? ((code) => {
       process.exitCode = code;
     })
@@ -1820,6 +2163,72 @@ function formatLaunchFailure(launchResult) {
   }
   return failureFields.join(" ");
 }
+function normalizeRawArgs(rawArgs) {
+  if (rawArgs.length === 0) {
+    return ["help"];
+  }
+  if (KNOWN_TOP_LEVEL_COMMANDS.has(rawArgs[0])) {
+    return rawArgs;
+  }
+  if (rawArgs.some((arg) => arg === "-p" || arg === "--preset" || arg.startsWith("--preset="))) {
+    return ["opencode", ...rawArgs];
+  }
+  return rawArgs;
+}
+async function loadProjectConfigSnapshot(globalConfigPath, projectRoot) {
+  const normalizedProjectRoot = resolve(projectRoot);
+  const projectConfigPath = resolveProjectConfigPath(normalizedProjectRoot);
+  const [globalConfig, projectConfig] = await Promise.all([
+    readOptionalRawVvcodeConfig(globalConfigPath),
+    readOptionalRawVvcodeConfig(projectConfigPath)
+  ]);
+  return {
+    projectRoot: normalizedProjectRoot,
+    projectConfigPath,
+    globalConfigPath: resolve(globalConfigPath),
+    globalConfig,
+    projectConfig
+  };
+}
+function collectPresetNames(snapshot) {
+  const presetNames = new Set;
+  for (const presetName of Object.keys(toObjectBucket(snapshot.globalConfig?.presets))) {
+    presetNames.add(presetName);
+  }
+  for (const presetName of Object.keys(toObjectBucket(snapshot.projectConfig?.presets))) {
+    presetNames.add(presetName);
+  }
+  return [...presetNames].sort((left, right) => left.localeCompare(right));
+}
+function describePresetSource(snapshot, presetName) {
+  const hasGlobalPreset = presetName in toObjectBucket(snapshot.globalConfig?.presets);
+  const hasProjectPreset = presetName in toObjectBucket(snapshot.projectConfig?.presets);
+  if (hasProjectPreset && hasGlobalPreset) {
+    return "project-overrides-global";
+  }
+  if (hasProjectPreset) {
+    return "project";
+  }
+  return "global";
+}
+function toMutableBucket(config, key) {
+  const bucket = config[key];
+  if (isRecord3(bucket)) {
+    return bucket;
+  }
+  const nextBucket = {};
+  config[key] = nextBucket;
+  return nextBucket;
+}
+function toObjectBucket(value) {
+  return isRecord3(value) ? value : {};
+}
+function isRecord3(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function areJsonValuesEqual(left, right) {
+  return JSON.stringify(left) === JSON.stringify(right);
+}
 
 // src/cli/vvcode-entry.ts
 await runVvcodeCli();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@osovv/vvcode",
-  "version": "0.4.1",
+  "version": "0.5.1",
   "description": "Packaged CLI for launching OpenCode with vvcode runtime semantics.",
   "license": "MIT",
   "homepage": "https://github.com/osovv/vvcode",
@@ -18,7 +18,7 @@
     "dist"
   ],
   "bin": {
-    "vvcode": "./bin/vvcode"
+    "vvcode": "bin/vvcode"
   },
   "publishConfig": {
     "access": "public"