@osovv/vv-opencode 0.35.18 → 0.35.20

package/dist/lib/config-layers.js

@@ -0,0 +1,255 @@
+// FILE: src/lib/config-layers.ts
+// VERSION: 1.0.0
+// START_MODULE_CONTRACT
+//   PURPOSE: Resolve vvoc and OpenCode config layers for global, project, and effective scopes.
+//   SCOPE: Env override handling, ancestor project-root discovery, project write-root selection, global fallback paths, runtime vvoc loading, and source metadata.
+//   DEPENDS: [node:fs/promises, node:path, src/lib/vvoc-config.ts, src/lib/vvoc-paths.ts]
+//   LINKS: [M-CONFIG-LAYERS, M-CLI-CONFIG]
+//   ROLE: RUNTIME
+//   MAP_MODE: EXPORTS
+// END_MODULE_CONTRACT
+//
+// START_MODULE_MAP
+//   VVOC_CONFIG_ENV - Environment variable name for explicit vvoc config selection.
+//   OPENCODE_CONFIG_ENV - Environment variable name for explicit OpenCode config selection.
+//   ConfigWriteScope - Supported write scopes for mutating commands.
+//   ConfigReadScope - Supported read scopes for list/show/diagnostic commands.
+//   ConfigSourceKind - Source kind labels for selected config sources.
+//   ConfigSource - Metadata describing a selected config source.
+//   ProjectConfigRoot - Nearest project config layer metadata.
+//   ConfigLayerOptions - Common layered config resolution inputs.
+//   findNearestProjectConfigRoot - Finds the closest ancestor with .vvoc/vvoc.json or .opencode/opencode.json(c).
+//   resolveProjectWriteRoot - Selects the project root that project-scope mutations write to.
+//   resolveProjectOpenCodeConfigPath - Selects the canonical project .opencode/opencode.json(c) path.
+//   resolveVvocConfigSource - Resolves vvoc source metadata for global, project, or effective reads.
+//   resolveOpenCodeConfigSource - Resolves OpenCode source metadata for global, project, or effective reads.
+//   resolveConfigWriteTargets - Returns canonical global or project write paths.
+//   loadVvocConfigForRead - Loads vvoc config for CLI read/list/show commands without creating files.
+//   loadEffectiveVvocConfigForRuntime - Loads the effective vvoc config for runtime plugins.
+// END_MODULE_MAP
+//
+// START_CHANGE_SUMMARY
+//   LAST_CHANGE: [v1.0.0 - Added layered config source discovery, write target resolution, and runtime vvoc loading.]
+// END_CHANGE_SUMMARY
+import { access, readFile } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { createDefaultVvocConfig, loadLenientVvocConfigText, parseVvocConfigText, } from "./vvoc-config.js";
+import { getGlobalOpencodeDir, getGlobalVvocConfigPath, getGlobalVvocDir, getProjectOpencodeDir, getProjectVvocConfigPath, } from "./vvoc-paths.js";
+export const VVOC_CONFIG_ENV = "VVOC_CONFIG";
+export const OPENCODE_CONFIG_ENV = "OPENCODE_CONFIG";
+const OPENCODE_CONFIG_FILE_NAMES = ["opencode.json", "opencode.jsonc"];
+// START_BLOCK_PROJECT_LAYER_DISCOVERY
+export async function findNearestProjectConfigRoot(cwd) {
+    let currentDir = resolve(cwd);
+    while (true) {
+        const vvocConfigPath = getProjectVvocConfigPath(currentDir);
+        const opencodeConfigPath = await findExistingProjectOpenCodeConfigPath(currentDir);
+        const hasVvocConfig = await pathExists(vvocConfigPath);
+        if (hasVvocConfig || opencodeConfigPath) {
+            return {
+                rootDir: currentDir,
+                vvocConfigPath: hasVvocConfig ? vvocConfigPath : undefined,
+                opencodeConfigPath,
+            };
+        }
+        const parentDir = dirname(currentDir);
+        if (parentDir === currentDir) {
+            return undefined;
+        }
+        currentDir = parentDir;
+    }
+}
+export async function resolveProjectWriteRoot(cwd) {
+    return (await findNearestProjectConfigRoot(cwd))?.rootDir ?? resolve(cwd);
+}
+export async function resolveProjectOpenCodeConfigPath(projectRoot) {
+    return ((await findExistingProjectOpenCodeConfigPath(projectRoot)) ??
+        join(getProjectOpencodeDir(projectRoot), "opencode.json"));
+}
+// END_BLOCK_PROJECT_LAYER_DISCOVERY
+// START_BLOCK_SOURCE_RESOLUTION
+export async function resolveVvocConfigSource(options) {
+    if (options.scope === "global") {
+        return resolveGlobalVvocSource(options.configDir);
+    }
+    if (options.scope === "project") {
+        return resolveProjectVvocSource(options.cwd);
+    }
+    const envSource = readEnvConfigSource(options.env, VVOC_CONFIG_ENV);
+    if (envSource) {
+        return envSource;
+    }
+    const projectSource = await resolveProjectVvocSource(options.cwd);
+    if (projectSource.kind === "project") {
+        return projectSource;
+    }
+    const globalSource = await resolveGlobalVvocSource(options.configDir);
+    if (globalSource.kind === "global") {
+        return globalSource;
+    }
+    if (options.allowDefault) {
+        return { kind: "default", reason: "no vvoc config found" };
+    }
+    return globalSource.kind === "missing" ? globalSource : projectSource;
+}
+export async function resolveOpenCodeConfigSource(options) {
+    if (options.scope === "global") {
+        return resolveGlobalOpenCodeSource(options.configDir);
+    }
+    if (options.scope === "project") {
+        return resolveProjectOpenCodeSource(options.cwd);
+    }
+    const envSource = readEnvConfigSource(options.env, OPENCODE_CONFIG_ENV);
+    if (envSource) {
+        return envSource;
+    }
+    const projectSource = await resolveProjectOpenCodeSource(options.cwd);
+    if (projectSource.kind === "project") {
+        return projectSource;
+    }
+    return resolveGlobalOpenCodeSource(options.configDir);
+}
+export async function resolveConfigWriteTargets(options) {
+    if (options.scope === "global") {
+        const opencodeBaseDir = getGlobalOpencodeDir(options.configDir);
+        const opencodeConfigPath = await selectExistingPath(OPENCODE_CONFIG_FILE_NAMES.map((name) => join(opencodeBaseDir, name)));
+        return {
+            scope: "global",
+            opencodeBaseDir,
+            vvocBaseDir: getGlobalVvocDir(options.configDir),
+            opencodeConfigPath,
+            vvocConfigPath: getGlobalVvocConfigPath(options.configDir),
+        };
+    }
+    const projectRoot = await resolveProjectWriteRoot(options.cwd);
+    const opencodeBaseDir = getProjectOpencodeDir(projectRoot);
+    return {
+        scope: "project",
+        projectRoot,
+        opencodeBaseDir,
+        vvocBaseDir: dirname(getProjectVvocConfigPath(projectRoot)),
+        opencodeConfigPath: await resolveProjectOpenCodeConfigPath(projectRoot),
+        vvocConfigPath: getProjectVvocConfigPath(projectRoot),
+    };
+}
+// END_BLOCK_SOURCE_RESOLUTION
+// START_BLOCK_RUNTIME_VVOC_LOADING
+export async function loadVvocConfigForRead(options) {
+    const source = await resolveVvocConfigSource(options);
+    if (source.kind === "default" ||
+        (source.kind === "missing" && options.scope === "global" && options.allowDefault)) {
+        return {
+            config: createDefaultVvocConfig(),
+            source: { kind: "default", reason: source.reason },
+            warnings: [],
+        };
+    }
+    if (source.kind === "missing") {
+        throw new Error(source.reason ?? `vvoc config missing${source.path ? ` at ${source.path}` : ""}`);
+    }
+    if (!source.path) {
+        throw new Error(`selected vvoc config source has no path (${source.kind})`);
+    }
+    return {
+        config: parseVvocConfigText(await readFile(source.path, "utf8"), source.path),
+        source,
+        warnings: [],
+    };
+}
+export async function loadEffectiveVvocConfigForRuntime(options = {}) {
+    const source = await resolveVvocConfigSource({
+        scope: "effective",
+        allowDefault: true,
+        cwd: options.cwd ?? process.cwd(),
+        configDir: options.configDir,
+        env: options.env,
+    });
+    if (source.kind === "default") {
+        return { config: createDefaultVvocConfig(), source, warnings: [] };
+    }
+    if (!source.path) {
+        throw new Error(`selected vvoc config source has no path (${source.kind})`);
+    }
+    const text = await readFile(source.path, "utf8");
+    if (source.kind === "env" || source.kind === "project") {
+        return { config: parseVvocConfigText(text, source.path), source, warnings: [] };
+    }
+    const warnings = [];
+    const config = loadLenientVvocConfigText(text, source.path, warnings);
+    return { config, source, warnings };
+}
+// END_BLOCK_RUNTIME_VVOC_LOADING
+async function resolveProjectVvocSource(cwd) {
+    const root = await findNearestProjectConfigRoot(cwd);
+    if (root?.vvocConfigPath) {
+        return { kind: "project", path: root.vvocConfigPath, rootDir: root.rootDir };
+    }
+    return {
+        kind: "missing",
+        reason: "project vvoc config missing; run vvoc install --scope project",
+    };
+}
+async function resolveProjectOpenCodeSource(cwd) {
+    const root = await findNearestProjectConfigRoot(cwd);
+    if (root?.opencodeConfigPath) {
+        return { kind: "project", path: root.opencodeConfigPath, rootDir: root.rootDir };
+    }
+    return {
+        kind: "missing",
+        reason: "project OpenCode config missing; run vvoc install --scope project",
+    };
+}
+async function resolveGlobalVvocSource(configDir) {
+    const path = getGlobalVvocConfigPath(configDir);
+    return (await pathExists(path))
+        ? { kind: "global", path }
+        : { kind: "missing", path, reason: "global vvoc config missing" };
+}
+async function resolveGlobalOpenCodeSource(configDir) {
+    const baseDir = getGlobalOpencodeDir(configDir);
+    const path = await findExistingOpenCodeConfigPath(baseDir);
+    return path
+        ? { kind: "global", path }
+        : {
+            kind: "missing",
+            path: join(baseDir, "opencode.json"),
+            reason: "global OpenCode config missing",
+        };
+}
+function readEnvConfigSource(env, name) {
+    const value = env ? env[name] : process.env[name];
+    if (typeof value !== "string" || !value.trim()) {
+        return undefined;
+    }
+    return { kind: "env", path: resolve(value.trim()), reason: name };
+}
+async function findExistingProjectOpenCodeConfigPath(projectRoot) {
+    return findExistingOpenCodeConfigPath(getProjectOpencodeDir(projectRoot));
+}
+async function findExistingOpenCodeConfigPath(baseDir) {
+    for (const name of OPENCODE_CONFIG_FILE_NAMES) {
+        const candidate = join(baseDir, name);
+        if (await pathExists(candidate)) {
+            return candidate;
+        }
+    }
+    return undefined;
+}
+async function selectExistingPath(candidates) {
+    for (const candidate of candidates) {
+        if (await pathExists(candidate)) {
+            return candidate;
+        }
+    }
+    return candidates[0];
+}
+async function pathExists(path) {
+    try {
+        await access(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=config-layers.js.map

package/dist/lib/config-layers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config-layers.js","sourceRoot":"","sources":["../../src/lib/config-layers.ts"],"names":[],"mappings":"AAAA,iCAAiC;AACjC,iBAAiB;AACjB,wBAAwB;AACxB,gGAAgG;AAChG,mKAAmK;AACnK,0FAA0F;AAC1F,2CAA2C;AAC3C,kBAAkB;AAClB,sBAAsB;AACtB,sBAAsB;AACtB,EAAE;AACF,mBAAmB;AACnB,oFAAoF;AACpF,4FAA4F;AAC5F,qEAAqE;AACrE,+EAA+E;AAC/E,uEAAuE;AACvE,iEAAiE;AACjE,+DAA+D;AAC/D,kEAAkE;AAClE,kHAAkH;AAClH,8FAA8F;AAC9F,sGAAsG;AACtG,qGAAqG;AACrG,6GAA6G;AAC7G,iFAAiF;AACjF,sGAAsG;AACtG,6FAA6F;AAC7F,iBAAiB;AACjB,EAAE;AACF,uBAAuB;AACvB,sHAAsH;AACtH,qBAAqB;AAErB,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACnD,OAAO,EACL,uBAAuB,EACvB,yBAAyB,EACzB,mBAAmB,GAEpB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,oBAAoB,EACpB,uBAAuB,EACvB,gBAAgB,EAChB,qBAAqB,EACrB,wBAAwB,GACzB,MAAM,iBAAiB,CAAC;AAEzB,MAAM,CAAC,MAAM,eAAe,GAAG,aAAa,CAAC;AAC7C,MAAM,CAAC,MAAM,mBAAmB,GAAG,iBAAiB,CAAC;AAkCrD,MAAM,0BAA0B,GAAG,CAAC,eAAe,EAAE,gBAAgB,CAAU,CAAC;AAEhF,sCAAsC;AACtC,MAAM,CAAC,KAAK,UAAU,4BAA4B,CAChD,GAAW;IAEX,IAAI,UAAU,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;IAE9B,OAAO,IAAI,EAAE,CAAC;QACZ,MAAM,cAAc,GAAG,wBAAwB,CAAC,UAAU,CAAC,CAAC;QAC5D,MAAM,kBAAkB,GAAG,MAAM,qCAAqC,CAAC,UAAU,CAAC,CAAC;QACnF,MAAM,aAAa,GAAG,MAAM,UAAU,CAAC,cAAc,CAAC,CAAC;QAEvD,IAAI,aAAa,IAAI,kBAAkB,EAAE,CAAC;YACxC,OAAO;gBACL,OAAO,EAAE,UAAU;gBACnB,cAAc,EAAE,aAAa,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC,SAAS;gBAC1D,kBAAkB;aACnB,CAAC;QACJ,CAAC;QAED,MAAM,SAAS,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;QACtC,IAAI,SAAS,KAAK,UAAU,EAAE,CAAC;YAC7B,OAAO,SAAS,CAAC;QACnB,CAAC;QACD,UAAU,GAAG,SAAS,CAAC;IACzB,CAAC;AACH,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,uBAAuB,CAAC,GAAW;IACvD,OAAO,CAAC,MAAM,4BAA4B,CAAC,GAAG,CAAC,CAAC,EAAE,OAAO,IAAI,OAAO,CAAC,GAAG,CAAC,CAAC;AAC5E,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,gCAAgC,CAAC,WAAmB;IACxE,OAAO,CACL,CAAC,MAAM,qCAAqC,CAAC,WAAW,CAAC,CAAC;QAC1D,IAAI,CAAC,qBAAqB,CAAC,WAAW,CAAC,EAAE,eAAe,CAAC,CAC1D,CAAC;AACJ,CAAC;AACD,oCAAoC;AAEpC,gCAAgC;AAChC,MAAM,CAAC,KAAK,UAAU,uBAAuB,CAC3C,OAA+E;IAE/E,IAAI,OAAO,CAAC,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC/B,OAAO,uBAAuB,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IACpD,CAAC;IAED,IAAI,OAAO,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC;QAChC,OAAO,wBAAwB,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IAC/C,CAAC;IAED,MAAM,SAAS,GAAG,mBAAmB,CAAC,OAAO,CAAC,GAAG,EAAE,eAAe,CAAC,CAAC;IACpE,IAAI,SAAS,EAAE,CAAC;QACd,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,MAAM,aAAa,GAAG,MAAM,wBAAwB,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IAClE,IAAI,aAAa,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;QACrC,OAAO,aAAa,CAAC;IACvB,CAAC;IAED,MAAM,YAAY,GAAG,MAAM,uBAAuB,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IACtE,IAAI,YAAY,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;QACnC,OAAO,YAAY,CAAC;IACtB,CAAC;IAED,IAAI,OAAO,CAAC,YAAY,EAAE,CAAC;QACzB,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,sBAAsB,EAAE,CAAC;IAC7D,CAAC;IAED,OAAO,YAAY,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,aAAa,CAAC;AACxE,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,2BAA2B,CAC/C,OAAwD;IAExD,IAAI,OAAO,CAAC,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC/B,OAAO,2BAA2B,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IACxD,CAAC;IAED,IAAI,OAAO,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC;QAChC,OAAO,4BAA4B,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IACnD,CAAC;IAED,MAAM,SAAS,GAAG,mBAAmB,CAAC,OAAO,CAAC,GAAG,EAAE,mBAAmB,CAAC,CAAC;IACxE,IAAI,SAAS,EAAE,CAAC;QACd,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,MAAM,aAAa,GAAG,MAAM,4BAA4B,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IACtE,IAAI,aAAa,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;QACrC,OAAO,aAAa,CAAC;IACvB,CAAC;IAED,OAAO,2BAA2B,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;AACxD,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,yBAAyB,CAC7C,OAAyD;IAEzD,IAAI,OAAO,CAAC,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC/B,MAAM,eAAe,GAAG,oBAAoB,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;QAChE,MAAM,kBAAkB,GAAG,MAAM,kBAAkB,CACjD,0BAA0B,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,eAAe,EAAE,IAAI,CAAC,CAAC,CACtE,CAAC;QACF,OAAO;YACL,KAAK,EAAE,QAAQ;YACf,eAAe;YACf,WAAW,EAAE,gBAAgB,CAAC,OAAO,CAAC,SAAS,CAAC;YAChD,kBAAkB;YAClB,cAAc,EAAE,uBAAuB,CAAC,OAAO,CAAC,SAAS,CAAC;SAC3D,CAAC;IACJ,CAAC;IAED,MAAM,WAAW,GAAG,MAAM,uBAAuB,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IAC/D,MAAM,eAAe,GAAG,qBAAqB,CAAC,WAAW,CAAC,CAAC;IAC3D,OAAO;QACL,KAAK,EAAE,SAAS;QAChB,WAAW;QACX,eAAe;QACf,WAAW,EAAE,OAAO,CAAC,wBAAwB,CAAC,WAAW,CAAC,CAAC;QAC3D,kBAAkB,EAAE,MAAM,gCAAgC,CAAC,WAAW,CAAC;QACvE,cAAc,EAAE,wBAAwB,CAAC,WAAW,CAAC;KACtD,CAAC;AACJ,CAAC;AACD,8BAA8B;AAE9B,mCAAmC;AACnC,MAAM,CAAC,KAAK,UAAU,qBAAqB,CACzC,OAA+E;IAE/E,MAAM,MAAM,GAAG,MAAM,uBAAuB,CAAC,OAAO,CAAC,CAAC;IACtD,IACE,MAAM,CAAC,IAAI,KAAK,SAAS;QACzB,CAAC,MAAM,CAAC,IAAI,KAAK,SAAS,IAAI,OAAO,CAAC,KAAK,KAAK,QAAQ,IAAI,OAAO,CAAC,YAAY,CAAC,EACjF,CAAC;QACD,OAAO;YACL,MAAM,EAAE,uBAAuB,EAAE;YACjC,MAAM,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE;YAClD,QAAQ,EAAE,EAAE;SACb,CAAC;IACJ,CAAC;IAED,IAAI,MAAM,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;QAC9B,MAAM,IAAI,KAAK,CACb,MAAM,CAAC,MAAM,IAAI,sBAAsB,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,OAAO,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,CACjF,CAAC;IACJ,CAAC;IAED,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;QACjB,MAAM,IAAI,KAAK,CAAC,4CAA4C,MAAM,CAAC,IAAI,GAAG,CAAC,CAAC;IAC9E,CAAC;IAED,OAAO;QACL,MAAM,EAAE,mBAAmB,CAAC,MAAM,QAAQ,CAAC,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,IAAI,CAAC;QAC7E,MAAM;QACN,QAAQ,EAAE,EAAE;KACb,CAAC;AACJ,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,iCAAiC,CACrD,UAAuC,EAAE;IAEzC,MAAM,MAAM,GAAG,MAAM,uBAAuB,CAAC;QAC3C,KAAK,EAAE,WAAW;QAClB,YAAY,EAAE,IAAI;QAClB,GAAG,EAAE,OAAO,CAAC,GAAG,IAAI,OAAO,CAAC,GAAG,EAAE;QACjC,SAAS,EAAE,OAAO,CAAC,SAAS;QAC5B,GAAG,EAAE,OAAO,CAAC,GAAG;KACjB,CAAC,CAAC;IAEH,IAAI,MAAM,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;QAC9B,OAAO,EAAE,MAAM,EAAE,uBAAuB,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAC;IACrE,CAAC;IAED,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;QACjB,MAAM,IAAI,KAAK,CAAC,4CAA4C,MAAM,CAAC,IAAI,GAAG,CAAC,CAAC;IAC9E,CAAC;IAED,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IACjD,IAAI,MAAM,CAAC,IAAI,KAAK,KAAK,IAAI,MAAM,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;QACvD,OAAO,EAAE,MAAM,EAAE,mBAAmB,CAAC,IAAI,EAAE,MAAM,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAC;IAClF,CAAC;IAED,MAAM,QAAQ,GAAa,EAAE,CAAC;IAC9B,MAAM,MAAM,GAAG,yBAAyB,CAAC,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;IACtE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC;AACtC,CAAC;AACD,iCAAiC;AAEjC,KAAK,UAAU,wBAAwB,CAAC,GAAW;IACjD,MAAM,IAAI,GAAG,MAAM,4BAA4B,CAAC,GAAG,CAAC,CAAC;IACrD,IAAI,IAAI,EAAE,cAAc,EAAE,CAAC;QACzB,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,IAAI,CAAC,cAAc,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC;IAC/E,CAAC;IAED,OAAO;QACL,IAAI,EAAE,SAAS;QACf,MAAM,EAAE,+DAA+D;KACxE,CAAC;AACJ,CAAC;AAED,KAAK,UAAU,4BAA4B,CAAC,GAAW;IACrD,MAAM,IAAI,GAAG,MAAM,4BAA4B,CAAC,GAAG,CAAC,CAAC;IACrD,IAAI,IAAI,EAAE,kBAAkB,EAAE,CAAC;QAC7B,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,IAAI,CAAC,kBAAkB,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC;IACnF,CAAC;IAED,OAAO;QACL,IAAI,EAAE,SAAS;QACf,MAAM,EAAE,mEAAmE;KAC5E,CAAC;AACJ,CAAC;AAED,KAAK,UAAU,uBAAuB,CAAC,SAAkB;IACvD,MAAM,IAAI,GAAG,uBAAuB,CAAC,SAAS,CAAC,CAAC;IAChD,OAAO,CAAC,MAAM,UAAU,CAAC,IAAI,CAAC,CAAC;QAC7B,CAAC,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE;QAC1B,CAAC,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,EAAE,4BAA4B,EAAE,CAAC;AACtE,CAAC;AAED,KAAK,UAAU,2BAA2B,CAAC,SAAkB;IAC3D,MAAM,OAAO,GAAG,oBAAoB,CAAC,SAAS,CAAC,CAAC;IAChD,MAAM,IAAI,GAAG,MAAM,8BAA8B,CAAC,OAAO,CAAC,CAAC;IAC3D,OAAO,IAAI;QACT,CAAC,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE;QAC1B,CAAC,CAAC;YACE,IAAI,EAAE,SAAS;YACf,IAAI,EAAE,IAAI,CAAC,OAAO,EAAE,eAAe,CAAC;YACpC,MAAM,EAAE,gCAAgC;SACzC,CAAC;AACR,CAAC;AAED,SAAS,mBAAmB,CAC1B,GAAkC,EAClC,IAAY;IAEZ,MAAM,KAAK,GAAG,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAClD,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,EAAE,CAAC;QAC/C,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,OAAO,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC;AACpE,CAAC;AAED,KAAK,UAAU,qCAAqC,CAClD,WAAmB;IAEnB,OAAO,8BAA8B,CAAC,qBAAqB,CAAC,WAAW,CAAC,CAAC,CAAC;AAC5E,CAAC;AAED,KAAK,UAAU,8BAA8B,CAAC,OAAe;IAC3D,KAAK,MAAM,IAAI,IAAI,0BAA0B,EAAE,CAAC;QAC9C,MAAM,SAAS,GAAG,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;QACtC,IAAI,MAAM,UAAU,CAAC,SAAS,CAAC,EAAE,CAAC;YAChC,OAAO,SAAS,CAAC;QACnB,CAAC;IACH,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,KAAK,UAAU,kBAAkB,CAAC,UAAoB;IACpD,KAAK,MAAM,SAAS,IAAI,UAAU,EAAE,CAAC;QACnC,IAAI,MAAM,UAAU,CAAC,SAAS,CAAC,EAAE,CAAC;YAChC,OAAO,SAAS,CAAC;QACnB,CAAC;IACH,CAAC;IACD,OAAO,UAAU,CAAC,CAAC,CAAC,CAAC;AACvB,CAAC;AAED,KAAK,UAAU,UAAU,CAAC,IAAY;IACpC,IAAI,CAAC;QACH,MAAM,MAAM,CAAC,IAAI,CAAC,CAAC;QACnB,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC"}

package/dist/lib/opencode.d.ts

@@ -1,6 +1,7 @@
 import { type ManagedOpenCodeAgentName } from "./managed-agents.js";
 import { type GuardianConfig, type GuardianConfigOverrides, type SecretsRedactionConfig, type VvocConfig } from "./vvoc-config.js";
 import { PACKAGE_NAME } from "./package.js";
+import { type ConfigReadScope, type ConfigSource } from "./config-layers.js";
 export declare const CLI_NAME = "vvoc";
 export { PACKAGE_NAME };
 export declare const OPENCODE_SCHEMA_URL = "https://opencode.ai/config.json";
@@ -11,6 +12,7 @@ export type ResolvedPaths = {
     scope: Scope;
     cwd: string;
     configHome: string;
+    projectRoot?: string;
     opencodeBaseDir: string;
     vvocBaseDir: string;
     vvocConfigPath: string;
@@ -31,7 +33,7 @@ export type OpenCodeAgentOverride = {
 };
 export type ManagedAgentOverrideMap = Record<ManagedOpenCodeAgentName, OpenCodeAgentOverride>;
 export type InstallationInspection = {
-    scope: Scope;
+    scope: ConfigReadScope;
     opencode: {
         path: string;
         exists: boolean;
@@ -74,7 +76,7 @@ export declare function resolvePaths(options: {
     configDir?: string;
 }): Promise<ResolvedPaths>;
 export declare function ensurePackageConfigText(text: string | undefined, packageSpecifier?: string): string;
-export declare function ensureManagedAgentRegistrationsConfigText(text: string | undefined, paths: Pick<ResolvedPaths, "managedAgentsDirPath" | "opencodeConfigPath">): string;
+export declare function ensureManagedAgentRegistrationsConfigText(text: string | undefined, paths: Pick<ResolvedPaths, "managedAgentsDirPath" | "managedSkillsDirPath" | "opencodeConfigPath">): string;
 export declare function syncManagedAgentRegistrations(paths: ResolvedPaths): Promise<{
     path: string;
     changed: boolean;
@@ -107,7 +109,7 @@ export declare function writeOpenCodeDefaultModel(paths: Pick<ResolvedPaths, "op
     ensureEntry: boolean;
 }): Promise<WriteResult>;
 export declare function writeOpenCodeProviderObject(paths: Pick<ResolvedPaths, "opencodeConfigPath">, providerID: string, value: JsonObject): Promise<WriteResult>;
-export declare function writeManagedAgentModel(paths: Pick<ResolvedPaths, "managedAgentsDirPath" | "opencodeConfigPath">, agentName: ManagedOpenCodeAgentName, options: {
+export declare function writeManagedAgentModel(paths: Pick<ResolvedPaths, "managedAgentsDirPath" | "managedSkillsDirPath" | "opencodeConfigPath">, agentName: ManagedOpenCodeAgentName, options: {
     model?: string;
     ensureEntry: boolean;
 }): Promise<WriteResult>;
@@ -125,4 +127,12 @@ export declare function writeGuardianConfig(paths: Pick<ResolvedPaths, "vvocConf
     merge?: boolean;
 }): Promise<WriteResult>;
 export declare function inspectInstallation(paths: ResolvedPaths): Promise<InstallationInspection>;
+export declare function inspectInstallationForScope(options: {
+    scope: ConfigReadScope;
+    cwd: string;
+    configDir?: string;
+}): Promise<InstallationInspection & {
+    opencodeSource: ConfigSource;
+    vvocSource: ConfigSource;
+}>;
 export declare function describeWriteResult(result: WriteResult): string;

package/dist/lib/opencode.js

@@ -1,9 +1,9 @@
 // FILE: src/lib/opencode.ts
 // VERSION: 1.0.0
 // START_MODULE_CONTRACT
-//   PURPOSE: Manage OpenCode config mutation, provider patching, and the canonical vvoc.json config file.
-//   SCOPE: Scope-aware path resolution, pinned plugin writes, top-level OpenCode model/default writes, managed OpenCode default-agent, command, and tool gating, provider baseURL patching, provider object patching, managed OpenCode agent registration/model overrides, managed agent prompt sync, managed skill file install/sync, version-aware canonical vvoc config rendering and sync, and installation inspection.
-//   DEPENDS: [jsonc-parser, node:fs/promises, node:path, src/lib/managed-agents.ts, src/lib/managed-skills.ts, src/lib/package.ts, src/lib/vvoc-config.ts, src/lib/vvoc-paths.ts]
+//   PURPOSE: Manage OpenCode config mutation, provider patching, and scoped vvoc.json config files.
+//   SCOPE: Layer-aware path resolution, pinned plugin writes, managed OpenCode defaults, local skills path registration, provider patching, managed prompts/skills, version-aware vvoc config rendering, and installation inspection.
+//   DEPENDS: [jsonc-parser, node:fs/promises, node:path, src/lib/config-layers.ts, src/lib/managed-agents.ts, src/lib/managed-skills.ts, src/lib/package.ts, src/lib/vvoc-config.ts, src/lib/vvoc-paths.ts]
 //   LINKS: [M-CLI-CONFIG]
 //   ROLE: RUNTIME
 //   MAP_MODE: EXPORTS
@@ -45,6 +45,7 @@
 //   writeManagedAgentModel - Writes or removes a bundled vvoc-managed OpenCode agent model override in OpenCode config.
 //   writeGuardianConfig - Writes the guardian section into the canonical vvoc.json document.
 //   inspectInstallation - Reads current OpenCode/vvoc installation state for status and doctor commands.
+//   inspectInstallationForScope - Reads installation state using strict/effective layered source resolution.
 //   describeWriteResult - Formats config write outcomes for CLI output.
 //   ManagedAgentModelMap - Map of managed agent names to model selections.
 //   OpenCodeAgentOverride - Agent override config for OpenCode.
@@ -56,6 +57,8 @@
 // END_MODULE_MAP
 //
 // START_CHANGE_SUMMARY
+//   LAST_CHANGE: [v1.1.1 - Fixed syncManagedSkillFiles to not sync references when parent skill is skipped (user-owned/custom). Added regression coverage.]
+//   LAST_CHANGE: [v1.1.0 - Switched project-scope writes to .opencode/.vvoc layers and added local managed skills path registration.]
 //   LAST_CHANGE: [v0.5.1 - Added ensureManagedSkillSymlink. Fixed renderManagedSkill to preserve YAML frontmatter.]
 //   LAST_CHANGE: [v1.0.1 - Added managed plan directory resolution and creation for analyst/architect artifacts.]
 //   LAST_CHANGE: [v0.5.0 - Replaced managed command registrations (vv-plan/vv-review) with managed skills system. Added managedSkillsDirPath to ResolvedPaths. Added installManagedSkillFiles and syncManagedSkillFiles.]
@@ -76,7 +79,8 @@ import { MANAGED_SKILL_NAMES, getManagedSkillFilePath, listManagedSkillReference
 import { BUILTIN_ROLE_NAMES, getBuiltInRoleBindings, ROLE_REFERENCE_PREFIX, } from "./model-roles.js";
 import { createDefaultVvocConfig, createGuardianConfig, parseVersionedVvocConfigText, parseVvocConfigText, renderVvocConfig, } from "./vvoc-config.js";
 import { getPinnedPackageSpecifier, PACKAGE_NAME } from "./package.js";
-import { getConfigHome, getGlobalOpencodeDir, getGlobalOpencodeSkillsDir, getGlobalVvocConfigPath, getGlobalVvocDir, getProjectVvocDir, getVvocAgentsDir, getVvocPlansDir, getVvocSkillsDir, } from "./vvoc-paths.js";
+import { resolveConfigWriteTargets, resolveOpenCodeConfigSource, resolveVvocConfigSource, } from "./config-layers.js";
+import { getConfigHome, getGlobalOpencodeSkillsDir, getGlobalVvocDir, getVvocAgentsDir, getVvocPlansDir, getVvocSkillsDir, } from "./vvoc-paths.js";
 export const CLI_NAME = "vvoc";
 export { PACKAGE_NAME };
 export const OPENCODE_SCHEMA_URL = "https://opencode.ai/config.json";
@@ -111,26 +115,24 @@ const JSON_FORMAT = {
 };
 // START_BLOCK_RESOLVE_CONFIG_PATHS
 export async function resolvePaths(options) {
+    const targets = await resolveConfigWriteTargets(options);
     const configHome = getConfigHome(options.configDir);
-    const vvocBaseDir = getGlobalVvocDir(options.configDir);
-    const opencodeBaseDir = options.scope === "global" ? getGlobalOpencodeDir(options.configDir) : options.cwd;
-    const managedAgentsBaseDir = options.scope === "global" ? vvocBaseDir : getProjectVvocDir(options.cwd);
-    const managedAgentsDirPath = getVvocAgentsDir(managedAgentsBaseDir);
-    const managedPlansDirPath = getVvocPlansDir(managedAgentsBaseDir);
-    const managedSkillsDirPath = getVvocSkillsDir(managedAgentsBaseDir);
-    const opencodeSelection = await selectPrimaryPath(OPENCODE_CONFIG_FILE_NAMES.map((name) => join(opencodeBaseDir, name)));
+    const managedAgentsDirPath = getVvocAgentsDir(targets.vvocBaseDir);
+    const managedPlansDirPath = getVvocPlansDir(targets.vvocBaseDir);
+    const managedSkillsDirPath = getVvocSkillsDir(targets.vvocBaseDir);
     return {
         scope: options.scope,
         cwd: options.cwd,
         configHome,
-        opencodeBaseDir,
-        vvocBaseDir,
-        vvocConfigPath: getGlobalVvocConfigPath(options.configDir),
+        projectRoot: targets.projectRoot,
+        opencodeBaseDir: targets.opencodeBaseDir,
+        vvocBaseDir: targets.vvocBaseDir,
+        vvocConfigPath: targets.vvocConfigPath,
         managedAgentsDirPath,
         managedPlansDirPath,
         managedSkillsDirPath,
-        opencodeConfigPath: opencodeSelection.primary,
-        opencodeAlternatePaths: opencodeSelection.alternates,
+        opencodeConfigPath: targets.opencodeConfigPath,
+        opencodeAlternatePaths: await resolveOpenCodeAlternates(targets.opencodeBaseDir, targets.opencodeConfigPath),
     };
 }
 // END_BLOCK_RESOLVE_CONFIG_PATHS
@@ -187,6 +189,9 @@ export function ensureManagedAgentRegistrationsConfigText(text, paths) {
                 ...Object.fromEntries(Object.entries(builtInAgentModelRefs).map(([name, model]) => [name, { model }])),
                 ...managedRegistrations,
             },
+            skills: {
+                paths: [getManagedSkillsPathReference(paths)],
+            },
             command: {},
         });
     }
@@ -252,7 +257,7 @@ export function ensureManagedAgentRegistrationsConfigText(text, paths) {
             }));
         }
     }
-    return ensureTrailingNewline(applyEdits(nextText, format(nextText, undefined, JSON_FORMAT)));
+    return ensureManagedSkillsPathConfigText(ensureTrailingNewline(applyEdits(nextText, format(nextText, undefined, JSON_FORMAT))), paths);
 }
 export async function syncManagedAgentRegistrations(paths) {
     const currentText = await readOptionalText(paths.opencodeConfigPath);
@@ -341,9 +346,13 @@ export async function installManagedSkillFiles(paths, options) {
 export async function syncManagedSkillFiles(paths, options) {
     const results = [];
     for (const skillName of MANAGED_SKILL_NAMES) {
-        results.push(await syncManagedSkill(paths, skillName, options));
-        const refResults = await syncManagedSkillReferences(paths.managedSkillsDirPath, skillName);
-        results.push(...refResults);
+        const skillResult = await syncManagedSkill(paths, skillName, options);
+        results.push(skillResult);
+        // Only sync references when the parent skill was not skipped (user-owned/custom)
+        if (skillResult.action !== "skipped") {
+            const refResults = await syncManagedSkillReferences(paths.managedSkillsDirPath, skillName);
+            results.push(...refResults);
+        }
     }
     return results;
 }
@@ -682,6 +691,52 @@ export async function inspectInstallation(paths) {
         problems,
     };
 }
+export async function inspectInstallationForScope(options) {
+    const [opencodeSource, vvocSource] = await Promise.all([
+        resolveOpenCodeConfigSource({
+            scope: options.scope,
+            cwd: options.cwd,
+            configDir: options.configDir,
+        }),
+        resolveVvocConfigSource({
+            scope: options.scope,
+            cwd: options.cwd,
+            configDir: options.configDir,
+            allowDefault: options.scope === "effective",
+        }),
+    ]);
+    if (options.scope === "project") {
+        const missingSource = [opencodeSource, vvocSource].find((source) => source.kind === "missing");
+        if (missingSource) {
+            throw new Error(missingSource.reason ?? "project config missing; run vvoc install --scope project");
+        }
+    }
+    const fallbackPaths = await resolvePaths({
+        scope: options.scope === "global" ? "global" : "project",
+        cwd: options.cwd,
+        configDir: options.configDir,
+    });
+    const opencodeConfigPath = opencodeSource.path ?? fallbackPaths.opencodeConfigPath;
+    const vvocConfigPath = vvocSource.path ?? fallbackPaths.vvocConfigPath;
+    const scopedPaths = {
+        ...fallbackPaths,
+        opencodeBaseDir: dirname(opencodeConfigPath),
+        vvocBaseDir: dirname(vvocConfigPath),
+        opencodeConfigPath,
+        vvocConfigPath,
+        opencodeAlternatePaths: [],
+        managedAgentsDirPath: getVvocAgentsDir(dirname(vvocConfigPath)),
+        managedPlansDirPath: getVvocPlansDir(dirname(vvocConfigPath)),
+        managedSkillsDirPath: getVvocSkillsDir(dirname(vvocConfigPath)),
+    };
+    const inspection = await inspectInstallation(scopedPaths);
+    return {
+        ...inspection,
+        scope: options.scope,
+        opencodeSource,
+        vvocSource,
+    };
+}
 // END_BLOCK_INSPECT_INSTALLATION_STATE
 export function describeWriteResult(result) {
     let message = "";
@@ -726,6 +781,12 @@ function readPluginList(document, label) {
     }
     return raw.slice();
 }
+function readStringArray(value, label) {
+    if (!Array.isArray(value) || value.some((entry) => typeof entry !== "string")) {
+        throw new Error(`${label}: expected an array of strings`);
+    }
+    return value.slice();
+}
 function normalizePluginList(currentPlugins, packageSpecifier) {
     const nextPlugins = [];
     const seen = new Set();
@@ -873,6 +934,25 @@ function getManagedOpenCodeAgentPromptReference(paths, agentName) {
     const promptRef = relative(dirname(paths.opencodeConfigPath), promptPath).replaceAll("\\", "/");
     return `{file:${promptRef.startsWith(".") ? promptRef : `./${promptRef}`}}`;
 }
+function getManagedSkillsPathReference(paths) {
+    const skillsRef = relative(dirname(paths.opencodeConfigPath), paths.managedSkillsDirPath).replaceAll("\\", "/");
+    return skillsRef.startsWith(".") ? skillsRef : `./${skillsRef}`;
+}
+function ensureManagedSkillsPathConfigText(text, paths) {
+    const document = parseObjectDocument(text, "OpenCode config");
+    const skills = readOptionalObject(document, "skills", "OpenCode config");
+    const rawPaths = skills?.paths;
+    const currentPaths = rawPaths === undefined ? [] : readStringArray(rawPaths, "OpenCode config: skills.paths");
+    const managedSkillsPath = getManagedSkillsPathReference(paths);
+    if (currentPaths.includes(managedSkillsPath)) {
+        return text;
+    }
+    const nextPaths = [...currentPaths, managedSkillsPath];
+    const nextText = applyEdits(text, modify(text, ["skills", "paths"], nextPaths, {
+        formattingOptions: JSON_FORMAT,
+    }));
+    return ensureTrailingNewline(applyEdits(nextText, format(nextText, undefined, JSON_FORMAT)));
+}
 function getLegacyTrackedManagedPromptReferences(paths, agentName) {
     const promptPath = join(paths.managedAgentsDirPath, LEGACY_TRACKED_PROMPT_FILE_NAMES[agentName]);
     const promptRef = relative(dirname(paths.opencodeConfigPath), promptPath).replaceAll("\\", "/");
@@ -1188,17 +1268,14 @@ async function writeText(path, text) {
     await mkdir(dirname(path), { recursive: true });
     await writeFile(path, text, "utf8");
 }
-async function selectPrimaryPath(candidates) {
-    const existing = [];
-    for (const candidate of candidates) {
-        if ((await readOptionalText(candidate)) !== undefined) {
-            existing.push(candidate);
+async function resolveOpenCodeAlternates(opencodeBaseDir, selectedPath) {
+    const alternates = [];
+    for (const candidate of OPENCODE_CONFIG_FILE_NAMES.map((name) => join(opencodeBaseDir, name))) {
+        if (candidate !== selectedPath && (await readOptionalText(candidate)) !== undefined) {
+            alternates.push(candidate);
         }
     }
-    return {
-        primary: existing[0] ?? candidates[0],
-        alternates: existing.slice(1),
-    };
+    return alternates;
 }
 // END_BLOCK_FILESYSTEM_HELPERS
 //# sourceMappingURL=opencode.js.map