@osovv/vvcode 0.4.1 → 0.5.0

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,89 @@ 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>
 ```
 
 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 +125,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.0",
   description: "Packaged CLI for launching OpenCode with vvcode runtime semantics.",
   license: "MIT",
   homepage: "https://github.com/osovv/vvcode",
@@ -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";
@@ -1730,6 +1758,7 @@ async function launchOpenCodeProcess(request) {
 // 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 +1767,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 +1784,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 +1864,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) || !isRecord2(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 (!isRecord2(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 (!isRecord2(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 (!isRecord2(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 +2016,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 +2036,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 (isRecord2(bucket)) {
+    return bucket;
+  }
+  const nextBucket = {};
+  config[key] = nextBucket;
+  return nextBucket;
+}
+function toObjectBucket(value) {
+  return isRecord2(value) ? value : {};
+}
+function isRecord2(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.0",
   "description": "Packaged CLI for launching OpenCode with vvcode runtime semantics.",
   "license": "MIT",
   "homepage": "https://github.com/osovv/vvcode",