amxx-builder 1.6.0 → 1.7.0

package/src/commands/serve.js

@@ -16,8 +16,11 @@
  * Method table:
  *   manifest.validate       → validate.manifestFile
  *   manifest.resolve        → env.loadEnv + manifest.resolveManifest
+ *   manifest.dep            → agent-assets readDepManifest + parseDocEntries/parseSkillEntries
+ *   docs.list / docs.get    → agent-assets collectDepAssets / collectLocalAssets
+ *   skills.list / skills.get → agent-assets collectDepAssets / collectLocalAssets
  *   include.resolve         → include-tree parseIncludeDirective + searchIncludeFile
- *   include.list            → include-tree fetchDepIncludeDir + collectIncFiles
+ *   include.list            → deps-resolver collectDepIncludeDirs + include-tree collectIncFiles
  *   amxmodx.includes.list   → compiler-fetcher fetchCompiler + glob
  *   amxmodx.include.get     → compiler-fetcher fetchCompiler + glob + read
  *   deps.tree               → deps-tree buildDepTree + assembleRootDeps
@@ -51,11 +54,13 @@ const { on, off, EVENTS } = require('../events');
 
 const { loadEnv } = require('../env');
 const { resolveManifestPath } = require('../manifest-path');
-const { resolveManifest, parseManifest, resolveGithubToken, parseDepString } = require('../manifest');
+const { resolveManifest, parseManifest, resolveGithubToken, parseDepString, parseDepObject, parseRefTtl, parseDocEntries, parseSkillEntries } = require('../manifest');
+const { resolveLocalEntry } = require('../local-sources');
+const { readDepManifest, collectDepAssets, collectLocalAssets } = require('../agent-assets');
 const { validateManifestFile } = require('../validate');
-const { fetchDepIncludeDir, collectIncFiles, parseIncludeDirective, searchIncludeFile } = require('../include-tree');
-const { depLabel } = require('../deps-resolver');
-const { fetchCompiler, resolveAmxmodxVersion, getCompilerInfo } = require('../compiler-fetcher');
+const { collectIncFiles, parseIncludeDirective, searchIncludeFile } = require('../include-tree');
+const { depLabel, collectDepIncludeDirs } = require('../deps-resolver');
+const { fetchCompiler, resolveAmxmodxVersion, getCompilerInfo, getHostPlatform, resolveStdlibVersion } = require('../compiler-fetcher');
 const { buildDepTree, assembleRootDeps } = require('../deps-tree');
 const { listReleases, listTags } = require('../release-lister');
 const {
@@ -83,20 +88,74 @@ function readFileSafe(absPath) {
   }
 }
 
-// Resolve the AMX Mod X version for a request: explicit `version` arg wins,
-// then the project manifest's amxmodx.version, then latest. Priority logic
-// lives in core (compiler-fetcher.resolveAmxmodxVersion).
+// JSON-RPC params spell no-fetch either `noFetch` (serve convention) or
+// `no_fetch` (snake_case convention) — normalize once here.
+function noFetchParam(params) {
+  return params?.noFetch === true || params?.no_fetch === true;
+}
+
+// Resolve a concrete compiler version string for handlers that go on to call
+// fetchCompiler() (dep-graph.get, compile.single). Explicit `version` arg wins,
+// then the project manifest's amxmodx.version, then latest — priority lives in
+// core (compiler-fetcher.resolveAmxmodxVersion). An invalid explicit version is
+// a JSON-RPC param error (-32602); everything else (incl. LATEST_NOT_CACHED)
+// propagates — these handlers fetch a real compiler, so a graceful empty state
+// is meaningless here.
 async function resolveVersionFromParams(params) {
-  if (params?.version) return resolveAmxmodxVersion(null, { version: params.version });
+  try {
+    if (params?.version) {
+      // await is required: a returned non-awaited promise bypasses this
+      // try/catch, so INVALID_AMXMODX_VERSION would never map to -32602.
+      return await resolveAmxmodxVersion(null, { version: params.version, noFetch: noFetchParam(params) });
+    }
 
-  const manifestPath = params?.manifest
-    ? path.resolve(params.manifest)
-    : resolveManifestPath().path;
+    const manifestPath = params?.manifest
+      ? path.resolve(params.manifest)
+      : resolveManifestPath().path;
+    let manifest = null;
+    if (fs.existsSync(manifestPath)) {
+      try { manifest = parseManifest(manifestPath); } catch { manifest = null; }
+    }
+    return await resolveAmxmodxVersion(manifest, { noFetch: noFetchParam(params) });
+  } catch (err) {
+    if (err && err.code === 'INVALID_AMXMODX_VERSION') {
+      err.code = -32602;
+      throw err;
+    }
+    throw err;
+  }
+}
+
+// Informational stdlib lookup for manifest-less / offline clients. Never
+// downloads when noFetch; if latest cannot be resolved offline, degrades to
+// the newest cached compiler instead of failing (degraded: true). Nothing
+// cached at all → graceful empty state (version: null), not an error.
+// Version-priority + offline degradation live in core
+// (compiler-fetcher.resolveStdlibVersion); this wrapper only does arg/manifest
+// discovery, the INVALID→-32602 remap and getCompilerInfo state shaping.
+async function resolveStdlibState(params) {
+  const noFetch = noFetchParam(params);
   let manifest = null;
-  if (fs.existsSync(manifestPath)) {
-    try { manifest = parseManifest(manifestPath); } catch { manifest = null; }
+  if (!params?.version) {
+    const manifestPath = manifestPathFor(params);
+    if (fs.existsSync(manifestPath)) {
+      try { manifest = parseManifest(manifestPath); } catch { manifest = null; }
+    }
   }
-  return resolveAmxmodxVersion(manifest, { noFetch: params?.noFetch === true });
+  const { version, degraded, error } = await resolveStdlibVersion({
+    version: params?.version,
+    manifest,
+    noFetch,
+  });
+  if (error) {
+    if (error.code === 'INVALID_AMXMODX_VERSION') error.code = -32602;
+    throw error;
+  }
+  if (version === null) {
+    return { version: null, degraded: false, platform: getHostPlatform(), compilerPath: null, includeDir: null, cached: false };
+  }
+  const info = await getCompilerInfo(version, { noFetch });
+  return { version: info.version, degraded, platform: info.platform, compilerPath: info.compilerPath, includeDir: info.includeDir, cached: info.cached };
 }
 
 function manifestPathFor(params) {
@@ -121,6 +180,43 @@ function resolveGithubTokenFor(params, repo) {
   return params?.token || process.env.GITHUB_TOKEN || null;
 }
 
+// Build a parsed dep object from params: either a full `dep` string/object or
+// explicit { repo, ref?, source?, include_path?, asset? } fields.
+function depFromParams(params) {
+  let dep;
+  if (params?.dep) {
+    if (typeof params.dep === 'string') dep = parseDepString(params.dep);
+    else if (params.dep.source === 'local') dep = parseDepObject(params.dep);
+    else dep = { ...params.dep };
+  } else {
+    if (!params?.repo) throw new Error('Provide either "dep" or "repo"');
+    const source = params.source || 'git';
+    const ref = params.ref || (source === 'release' ? 'latest' : null);
+    dep = { repo: params.repo, ref, source, include_path: params.include_path || null, asset: params.asset ?? null };
+  }
+  if (params?.source) dep.source = params.source;
+  if (params?.include_path) dep.include_path = params.include_path;
+  if (params?.asset != null) dep.asset = params.asset;
+  return resolveLocalEntry(
+    dep,
+    params?.manifest ? path.dirname(path.resolve(params.manifest)) : process.cwd()
+  );
+}
+
+// Agent docs/skills: dep mode when dep/repo is present, otherwise the local
+// project's own manifest.
+async function collectAgentAssets(params) {
+  const noFetch = noFetchParam(params);
+  if (params?.dep || params?.repo) {
+    const dep = depFromParams(params);
+    const token = resolveGithubTokenFor(params, dep.repo);
+    return collectDepAssets(dep, { token, noFetch });
+  }
+  const manifestPath = manifestPathFor(params);
+  loadEnvQuiet(manifestPath);
+  return collectLocalAssets(parseManifest(manifestPath));
+}
+
 /**
  * Shape a GitHub API error into the JSON-RPC error contract: -32603 with
  * error.data = { status, repo, message }. Returns null for non-GitHub errors
@@ -198,6 +294,89 @@ function createServeServer() {
     return resolveManifest(manifestPath, { set: params?.set, define: params?.define });
   });
 
+  // ─── Dependency manifest + agent assets ──────────────────────────────────
+
+  server.onRequest('manifest.dep', async (params) => {
+    let dep;
+    try {
+      dep = depFromParams(params);
+    } catch (err) {
+      err.code = -32602;
+      throw err;
+    }
+    const token = resolveGithubTokenFor(params, dep.repo);
+    const m = await readDepManifest(dep, { token, noFetch: noFetchParam(params) });
+
+    let docs = [];
+    let skills = [];
+    try { docs = parseDocEntries(m.raw?.docs || []); } catch { docs = []; }
+    try { skills = parseSkillEntries(m.raw?.skills || []); } catch { skills = []; }
+
+    return {
+      label: m.label,
+      manifestPath: m.manifestPath,
+      manifestName: m.raw?.name || null,
+      raw: m.raw,
+      docs: docs.map((d) => ({ name: d.name, description: d.description, file: d.file })),
+      skills: skills.map((s) => ({ name: s.name, description: s.description, file: s.file, dir: s.dir })),
+    };
+  });
+
+  server.onRequest('docs.list', async (params) => {
+    const assets = await collectAgentAssets(params);
+    return {
+      label: assets.label || null,
+      docs: assets.docs.map((d) => ({ name: d.name, description: d.description, file: d.file })),
+      missing: assets.missing,
+    };
+  });
+
+  server.onRequest('docs.get', async (params) => {
+    const assets = await collectAgentAssets(params);
+    let docs = assets.docs;
+    if (params?.name || params?.file) {
+      docs = docs.filter(
+        (d) => (params.name && d.name === params.name) || (params.file && d.file === params.file)
+      );
+    }
+    return {
+      label: assets.label || null,
+      docs: docs.map((d) => ({ name: d.name, description: d.description, file: d.file, content: d.content })),
+      missing: assets.missing,
+    };
+  });
+
+  server.onRequest('skills.list', async (params) => {
+    const assets = await collectAgentAssets(params);
+    return {
+      label: assets.label || null,
+      skills: assets.skills.map((s) => ({
+        name: s.name,
+        description: s.description,
+        kind: s.kind,
+        file: s.file,
+        dir: s.dir,
+        files: s.kind === 'dir' ? s.files.map((f) => f.rel) : undefined,
+      })),
+      missing: assets.missing,
+    };
+  });
+
+  server.onRequest('skills.get', async (params) => {
+    const assets = await collectAgentAssets(params);
+    let skills = assets.skills;
+    if (params?.name) skills = skills.filter((s) => s.name === params.name);
+    return {
+      label: assets.label || null,
+      skills: skills.map((s) => (
+        s.kind === 'dir'
+          ? { name: s.name, description: s.description, kind: 'dir', dir: s.dir, files: s.files.map((f) => ({ rel: f.rel, content: f.content })) }
+          : { name: s.name, description: s.description, kind: 'file', file: s.file, content: s.content }
+      )),
+      missing: assets.missing,
+    };
+  });
+
   // ─── Include resolution ──────────────────────────────────────────────────
 
   server.onRequest('include.resolve', async (params) => {
@@ -230,25 +409,23 @@ function createServeServer() {
       loadEnvQuiet(manifestPath);
       try {
         manifest = parseManifest(manifestPath);
-        for (const dep of manifest.globalDeps) {
-          try {
-            const depDir = await fetchDepIncludeDir(
-              dep, resolveGithubToken(manifest, dep.repo),
-              params?.noFetch === true, manifest.github.ssh
-            );
-            searchPaths.push({ path: depDir, label: depLabel(dep) });
-          } catch (err) {
-            errors.push(`${depLabel(dep)}: ${err.message}`);
-          }
-        }
       } catch (err) {
         errors.push(`manifest ${manifestPath}: ${err.message}`);
       }
     }
+    if (manifest) {
+      const { dirs, errors: depErrors } = await collectDepIncludeDirs(manifest, {
+        noFetch: noFetchParam(params),
+        ssh: manifest.github.ssh,
+      });
+      manifest.globalDeps.forEach((dep, i) => {
+        if (dirs[i]) searchPaths.push({ path: dirs[i], label: depLabel(dep) });
+        else if (depErrors[i]) errors.push(`${depLabel(dep)}: ${depErrors[i]}`);
+      });
+    }
 
-    const version = await resolveVersionFromParams(params);
-    const { includeDir } = await fetchCompiler(version);
-    if (includeDir) searchPaths.push({ path: includeDir, label: `AMXX stdlib ${version}` });
+    const stdlib = await resolveStdlibState(params);
+    if (stdlib.includeDir) searchPaths.push({ path: stdlib.includeDir, label: `AMXX stdlib ${stdlib.version}` });
 
     const result = searchIncludeFile(searchPaths, filename);
     if (!result) {
@@ -279,21 +456,27 @@ function createServeServer() {
     loadEnvQuiet(manifestPath);
     const manifest = parseManifest(manifestPath);
 
+    const { dirs, errors } = await collectDepIncludeDirs(manifest, {
+      noFetch: noFetchParam(params),
+      ssh: manifest.github.ssh,
+    });
+
     const deps = [];
-    for (const dep of manifest.globalDeps) {
+    for (let i = 0; i < manifest.globalDeps.length; i++) {
+      const dep = manifest.globalDeps[i];
       const base = dep.source === 'fungun'
         ? { source: 'fungun', id: dep.id, url: dep.url }
         : { source: dep.source || 'git', repo: dep.repo, ref: dep.ref };
+      if (errors[i]) {
+        deps.push({ ...base, error: errors[i], files: [], count: 0 });
+        continue;
+      }
       try {
-        const includeDir = await fetchDepIncludeDir(
-          dep, resolveGithubToken(manifest, dep.repo),
-          params?.noFetch === true, manifest.github.ssh
-        );
-        const files = await collectIncFiles(includeDir);
+        const files = await collectIncFiles(dirs[i]);
         deps.push({
           ...base,
           include_path: dep.include_path || null,
-          include_dir: includeDir,
+          include_dir: dirs[i],
           count: files.length,
           files: files.map((f) => ({ rel: f.rel, abs: f.abs })),
         });
@@ -307,39 +490,49 @@ function createServeServer() {
   // ─── AMXX standard includes ──────────────────────────────────────────────
 
   server.onRequest('amxmodx.includes.list', async (params) => {
-    const version = await resolveVersionFromParams(params);
+    const state = await resolveStdlibState(params);
     const pattern = params?.pattern || '*.inc';
 
-    const { includeDir } = await fetchCompiler(version);
-    if (!includeDir) return { version, includeDir: null, pattern, count: 0, files: [] };
+    if (!state.includeDir) {
+      const result = { version: state.version, includeDir: null, pattern, count: 0, files: [] };
+      if (state.degraded) result.degraded = true;
+      return result;
+    }
 
-    const files = await glob(pattern, { cwd: includeDir, dot: false });
+    const files = await glob(pattern, { cwd: state.includeDir, dot: false });
     files.sort();
-    return { version, includeDir, pattern, count: files.length, files };
+    const result = { version: state.version, includeDir: state.includeDir, pattern, count: files.length, files };
+    if (state.degraded) result.degraded = true;
+    return result;
   });
 
   server.onRequest('amxmodx.include.get', async (params) => {
-    const version = await resolveVersionFromParams(params);
+    const state = await resolveStdlibState(params);
     const pattern = params?.file || params?.pattern || '*.inc';
 
-    const { includeDir } = await fetchCompiler(version);
-    if (!includeDir) return { version, includeDir: null, count: 0, files: [] };
+    if (!state.includeDir) {
+      const result = { version: state.version, includeDir: null, count: 0, files: [] };
+      if (state.degraded) result.degraded = true;
+      return result;
+    }
 
-    const files = await glob(pattern, { cwd: includeDir, dot: false });
+    const files = await glob(pattern, { cwd: state.includeDir, dot: false });
     files.sort();
-    return {
-      version,
-      includeDir,
+    const result = {
+      version: state.version,
+      includeDir: state.includeDir,
       count: files.length,
-      files: files.map((rel) => ({ rel, content: readFileSafe(path.join(includeDir, rel)) })),
+      files: files.map((rel) => ({ rel, content: readFileSafe(path.join(state.includeDir, rel)) })),
     };
+    if (state.degraded) result.degraded = true;
+    return result;
   });
 
   // ─── Deps tree ───────────────────────────────────────────────────────────
 
   server.onRequest('deps.tree', async (params) => {
     const depth = params?.depth || 0;
-    const noFetch = params?.noFetch === true;
+    const noFetch = noFetchParam(params);
 
     if (params?.deps) {
       const rootDeps = params.deps.map((entry) => {
@@ -353,6 +546,7 @@ function createServeServer() {
           source: entry.source || 'git',
           include_path: entry.include_path || null,
           asset: entry.asset != null ? entry.asset : null,
+          ...(entry.ref_ttl != null ? { ref_ttl: parseRefTtl(entry.ref_ttl, `deps entry ${entry.repo}`) } : {}),
         };
       });
       return buildDepTree(rootDeps, { token: params?.token, noFetch, depth, from: 'user' });
@@ -387,7 +581,7 @@ function createServeServer() {
       throw err;
     }
 
-    const noFetch = params?.noFetch === true;
+    const noFetch = noFetchParam(params);
 
     const manifestPath = manifestPathFor(params);
     let manifest = null;
@@ -402,13 +596,8 @@ function createServeServer() {
     // Dep includes come BEFORE the stdlib — matching the real build's search order.
     const includeDirs = [];
     if (manifest) {
-      for (const dep of manifest.globalDeps) {
-        try {
-          includeDirs.push(await fetchDepIncludeDir(
-            dep, resolveGithubToken(manifest, dep.repo), noFetch, manifest.github.ssh
-          ));
-        } catch (err) { /* keep the rest of the dirs on partial failure */ }
-      }
+      const { dirs } = await collectDepIncludeDirs(manifest, { noFetch, ssh: manifest.github.ssh });
+      for (const dir of dirs) if (dir) includeDirs.push(dir);
     }
     if (includeDir) includeDirs.push(includeDir);
     for (const d of (params?.include_dirs || [])) includeDirs.push(path.resolve(d));
@@ -515,8 +704,10 @@ function createServeServer() {
   });
 
   server.onRequest('compiler.info', async (params) => {
-    const version = await resolveVersionFromParams(params);
-    return getCompilerInfo(version, { noFetch: params?.noFetch === true });
+    const state = await resolveStdlibState(params);
+    const result = { version: state.version, platform: state.platform, compilerPath: state.compilerPath, includeDir: state.includeDir, cached: state.cached };
+    if (state.degraded) result.degraded = true;
+    return result;
   });
 
   server.onRequest('build.plan', (params) => {
@@ -541,37 +732,43 @@ function createServeServer() {
     const controller = new AbortController();
     activeBuild = controller;
 
-    const manifestPath = manifestPathFor(params);
-    loadEnvQuiet(manifestPath);
-    const manifest = resolveManifest(manifestPath, { set: params?.set, define: params?.define });
-
-    // Forward core lifecycle events as server→client notifications while the
-    // build runs. COMPILED/PROGRESS are emitted by compiler.js/progress.js on
-    // the bus; STAGE/DONE/ERROR by build-service.
-    const listeners = [
-      [EVENTS.STAGE,    (p) => server.notify('build.stage', p)],
-      [EVENTS.COMPILED, (p) => server.notify('build.compiled', p)],
-      [EVENTS.PROGRESS, (p) => server.notify('build.progress', p)],
-      [EVENTS.DONE,     (p) => server.notify('build.done', p)],
-      [EVENTS.ERROR,    (p) => server.notify('build.error', p)],
-    ];
-    for (const [ev, fn] of listeners) on(ev, fn);
-
     try {
-      const result = await runBuild(manifest, {
-        buildDir: params?.buildDir,
-        fetch:    params?.fetch,
-        archive:  params?.archive,
-        signal:   controller.signal,
-      });
-      return result;
-    } catch (err) {
-      if (err.code === 'CANCELLED') {
-        return { ok: false, cancelled: true, message: err.message };
+      const manifestPath = manifestPathFor(params);
+      loadEnvQuiet(manifestPath);
+      const manifest = resolveManifest(manifestPath, { set: params?.set, define: params?.define });
+
+      // Forward core lifecycle events as server→client notifications while the
+      // build runs. COMPILED/PROGRESS are emitted by compiler.js/progress.js on
+      // the bus; STAGE/DONE/ERROR by build-service.
+      const listeners = [
+        [EVENTS.STAGE,    (p) => server.notify('build.stage', p)],
+        [EVENTS.COMPILED, (p) => server.notify('build.compiled', p)],
+        [EVENTS.PROGRESS, (p) => server.notify('build.progress', p)],
+        [EVENTS.DONE,     (p) => server.notify('build.done', p)],
+        [EVENTS.ERROR,    (p) => server.notify('build.error', p)],
+      ];
+      for (const [ev, fn] of listeners) on(ev, fn);
+
+      try {
+        const result = await runBuild(manifest, {
+          buildDir: params?.buildDir,
+          fetch:    params?.fetch,
+          archive:  params?.archive,
+          signal:   controller.signal,
+        });
+        return result;
+      } catch (err) {
+        if (err.code === 'CANCELLED') {
+          return { ok: false, cancelled: true, message: err.message };
+        }
+        return { ok: false, message: err.message };
+      } finally {
+        for (const [ev, fn] of listeners) off(ev, fn);
       }
-      return { ok: false, message: err.message };
     } finally {
-      for (const [ev, fn] of listeners) off(ev, fn);
+      // Even a pre-build failure (manifest missing, bad --set) must release the
+      // single-build lock, or every later build.start dies with "Build already
+      // running" until the process is restarted.
       activeBuild = null;
     }
   });
@@ -676,7 +873,7 @@ function createServeServer() {
       throw err;
     }
 
-    const noFetch = params?.noFetch === true;
+    const noFetch = noFetchParam(params);
 
     const manifestPath = manifestPathFor(params);
     let manifest = null;
@@ -692,28 +889,26 @@ function createServeServer() {
     const depDirs = [];
     const depErrors = [];
     if (manifest) {
-      for (const dep of manifest.globalDeps) {
-        try {
-          depDirs.push(await fetchDepIncludeDir(
-            dep, resolveGithubToken(manifest, dep.repo), noFetch, manifest.github.ssh
-          ));
-        } catch (err) {
-          depErrors.push(`${depLabel(dep)}: ${err.message}`);
-        }
-      }
+      const { dirs, errors } = await collectDepIncludeDirs(manifest, { noFetch, ssh: manifest.github.ssh });
+      manifest.globalDeps.forEach((dep, i) => {
+        if (dirs[i]) depDirs.push(dirs[i]);
+        else if (errors[i]) depErrors.push(`${depLabel(dep)}: ${errors[i]}`);
+      });
     }
 
     const includeDirs = [...depDirs];
     if (includeDir) includeDirs.push(includeDir);
     for (const d of (params?.include_dirs || [])) includeDirs.push(path.resolve(d));
 
-    const buildDir = path.join(os.tmpdir(), 'amxb-serve-compile');
+    // Unique per-call build dir + event tag: the transport dispatches requests
+    // concurrently, so two compile.single calls for same-named plugins must not
+    // share an output path nor mis-attribute COMPILED events (cf. MCP).
+    const runId     = `${process.pid}_${Date.now().toString(36)}${Math.random().toString(36).slice(2, 6)}`;
+    const buildDir  = path.join(os.tmpdir(), 'amxb-serve-compile', runId);
     const compileManifest = manifest || { amxmodx: { defines: [] } };
 
-    // Capture the compiler output emitted as an event by compileSingle.
-    const baseName = path.basename(smaPath);
     let compiled = null;
-    const onCompiled = (p) => { if (p.baseName === baseName) compiled = p; };
+    const onCompiled = (p) => { if (p.tag === runId) compiled = p; };
     on(EVENTS.COMPILED, onCompiled);
     let amxxName;
     try {
@@ -723,17 +918,19 @@ function createServeServer() {
         compilerPath,
         includeDirs,
         buildDir,
-        params?.scripting_root ? path.resolve(params.scripting_root) : undefined
+        params?.scripting_root ? path.resolve(params.scripting_root) : undefined,
+        runId
       );
     } finally {
       off(EVENTS.COMPILED, onCompiled);
     }
 
+    const outputPath = amxxName ? path.join(buildDir, 'amxmodx', 'plugins', amxxName) : null;
     return {
       ok: amxxName != null,
       amxxName,
       output: compiled ? compiled.output : undefined,
-      output_path: amxxName ? path.join(buildDir, 'amxmodx', 'plugins', amxxName) : null,
+      output_path: outputPath,
       dep_errors: depErrors.length ? depErrors : undefined,
     };
   });
@@ -748,6 +945,7 @@ function createServeServer() {
     }
 
     const manifestPath = manifestPathFor(params);
+    loadEnvQuiet(manifestPath);
     const manifest = parseManifest(manifestPath);
 
     const notify = (kind, extra = {}) => server.notify('watch.changed', { kind, ...extra });
@@ -773,13 +971,13 @@ function createServeServer() {
   return server;
 }
 
-// Load project .env from the workspace root like the CLI does; keep stdout free
-// for JSON-RPC (logs → stderr, progress bars disabled).
-function prepareEnvironment() {
-  dotenv.config({ path: path.join(process.cwd(), '.env'), quiet: true });
-  logger.setStderr(true);
-  progress.setEnabled(false);
-}
+  // Load project .env from the workspace root like the CLI does; keep stdout free
+  // for JSON-RPC (logs → stderr, progress bars disabled).
+  function prepareEnvironment() {
+    dotenv.config({ path: path.join(process.cwd(), '.env'), quiet: true });
+    logger.setStderr(true);
+    progress.setEnabled(false);
+  }
 
 /**
  * Start the serve server — listens on stdin/stdout forever.

package/src/commands/skills-dir.js

@@ -0,0 +1,21 @@
+'use strict';
+
+const fs   = require('fs');
+const path = require('path');
+
+// Absolute path to the skills/ directory bundled with this amxb installation.
+// Resolved relative to the running code, so it works for any install method
+// (npm -g, install.sh/ps1, linked dev checkout) without consulting npm.
+const SKILLS_DIR = path.join(__dirname, '..', '..', 'skills');
+
+function runSkillsDir() {
+  if (!fs.existsSync(SKILLS_DIR)) {
+    process.stderr.write(`skills directory not found: ${SKILLS_DIR}\n`);
+    process.exitCode = 1;
+    return;
+  }
+  // Pure stdout — consumers (e.g. the opencode bridge plugin) parse exactly this line.
+  process.stdout.write(SKILLS_DIR + '\n');
+}
+
+module.exports = { runSkillsDir, SKILLS_DIR };