amxx-builder 1.6.1 → 1.7.0

package/src/commands/init.js

@@ -8,6 +8,12 @@ const logger = require('../logger');
 const TEMPLATES_DIR = path.join(__dirname, '..', '..', 'templates');
 const SCHEMA_URL    = 'https://raw.githubusercontent.com/AmxxModularEcosystem/amxx-builder/master/schema/amxbuild.schema.json';
 
+// Written to .vscode/extensions.json by `amxb init --vscode`.
+const VSCODE_EXTENSIONS = [
+  'Faktor.amxx-pawn-all-in',
+  'amxx-modular-ecosystem.amxb-vscode',
+];
+
 // Auto-discovered by opencode (.opencode/plugin/*.js). Registers skills from all
 // three sources in the config hook, with no machine-specific paths in opencode.json.
 const OPENCODE_BRIDGE_FILE   = path.join('.opencode', 'plugin', 'amxb-skills.js');
@@ -98,6 +104,12 @@ async function runInitInteractive(options) {
     initial: true,
   }).run();
 
+  const doVscode = await new Confirm({
+    name: 'vscode',
+    message: 'Create .vscode/extensions.json with recommended extensions?',
+    initial: true,
+  }).run();
+
   const actions = [];
   actions.push('amxbuild.yml');
   if (doWorkflow) actions.push('.github/workflows/ci.yml');
@@ -106,6 +118,7 @@ async function runInitInteractive(options) {
   if (doDeploy) actions.push('.env');
   if (doOpencode) actions.push('.opencode/opencode.json');
   if (doScript) actions.push('build.bat', 'build.sh');
+  if (doVscode) actions.push('.vscode/extensions.json');
 
   logger.info('Creating:');
   for (const a of actions) logger.dim(`  ${a}`);
@@ -128,9 +141,7 @@ async function runInitInteractive(options) {
   }
 
   if (doGitignore) {
-    writeIfAbsent('.gitignore', [
-      '*.amxx', '*.zip', '.env', '.amxb-cache', '.claude', 'build', 'dist', '',
-    ].join('\n'), options.force);
+    writeGitignore(options.force);
   }
 
   if (doDeploy) {
@@ -145,6 +156,10 @@ async function runInitInteractive(options) {
   if (doScript) {
     writeBuildScripts(options.force);
   }
+
+  if (doVscode) {
+    writeVscodeExtensions();
+  }
 }
 
 function runInit(options) {
@@ -167,9 +182,7 @@ function runInit(options) {
   }
 
   if (options.gitignore) {
-    writeIfAbsent('.gitignore', [
-      '*.amxx', '*.zip', '.env', '.amxb-cache', '.claude', 'build', 'dist', '',
-    ].join('\n'), options.force);
+    writeGitignore(options.force);
   }
 
   if (options.deploy) {
@@ -184,6 +197,16 @@ function runInit(options) {
   if (options.script) {
     writeBuildScripts(options.force);
   }
+
+  if (options.vscode || options.vsc) {
+    writeVscodeExtensions();
+  }
+}
+
+// Shared by both init paths; also the .gitignore basis the amxb-migration skill
+// reuses, so keep templates/init-gitignore in sync with its step 6.
+function writeGitignore(force) {
+  return writeIfAbsent('.gitignore', renderTemplate('init-gitignore'), force);
 }
 
 function writeBuildScripts(force) {
@@ -269,6 +292,46 @@ function writeOpencodeBridge(force) {
   writeIfAbsent(OPENCODE_BRIDGE_FILE, OPENCODE_BRIDGE_PLUGIN, force);
 }
 
+// The extensions file is shared with the user's own editor setup, so it is
+// merged rather than overwritten: existing recommendations are preserved and
+// only the missing amxb entries are appended.
+function writeVscodeExtensions() {
+  const dir  = '.vscode';
+  const file = path.join(dir, 'extensions.json');
+
+  if (!fs.existsSync(file)) {
+    fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(file, JSON.stringify({ recommendations: VSCODE_EXTENSIONS }, null, 2) + '\n');
+    logger.success(`Created ${file}`);
+    return;
+  }
+
+  let cfg;
+  try {
+    cfg = JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch (err) {
+    logger.warn(`${file} exists but is invalid JSON, skipping`);
+    return;
+  }
+
+  if (cfg === null || typeof cfg !== 'object' || Array.isArray(cfg)) {
+    logger.warn(`${file} is not a JSON object, skipping`);
+    return;
+  }
+
+  const current = Array.isArray(cfg.recommendations) ? cfg.recommendations : [];
+  const missing = VSCODE_EXTENSIONS.filter((id) => !current.includes(id));
+
+  if (missing.length === 0) {
+    logger.warn(`${file} already recommends the amxb extensions, skipping`);
+    return;
+  }
+
+  cfg.recommendations = current.concat(missing);
+  fs.writeFileSync(file, JSON.stringify(cfg, null, 2) + '\n');
+  logger.success(`Updated ${file} with recommended extensions`);
+}
+
 function renderTemplate(name, vars = {}) {
   let content = fs.readFileSync(path.join(TEMPLATES_DIR, name), 'utf8');
   for (const [key, value] of Object.entries(vars)) {

package/src/commands/serve.js

@@ -54,7 +54,8 @@ const { on, off, EVENTS } = require('../events');
 
 const { loadEnv } = require('../env');
 const { resolveManifestPath } = require('../manifest-path');
-const { resolveManifest, parseManifest, resolveGithubToken, parseDepString, parseDocEntries, parseSkillEntries } = 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 { collectIncFiles, parseIncludeDirective, searchIncludeFile } = require('../include-tree');
@@ -184,7 +185,9 @@ function resolveGithubTokenFor(params, repo) {
 function depFromParams(params) {
   let dep;
   if (params?.dep) {
-    dep = typeof params.dep === 'string' ? parseDepString(params.dep) : { ...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';
@@ -194,7 +197,10 @@ function depFromParams(params) {
   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 dep;
+  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
@@ -540,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' });

package/src/commands/watch.js

@@ -11,7 +11,8 @@ const { deployBuild, deployPlugin, deployFile, removeDeployedFile } = require('.
 const { sendRconForPlugins } = require('../rcon');
 const { DepGraph }           = require('../dep-graph');
 const { startWatch }         = require('../watcher');
-const { fetchRepo, resolveRepoRefs } = require('../repo-fetcher');
+const { resolveRepoRefs } = require('../repo-fetcher');
+const { ensureRepoDir }   = require('../local-sources');
 const { resolveDeps, repoKey } = require('../deps-resolver');
 const { resolveManifestPath, loadEnv } = require('./shared');
 const { runBuild } = require('./build');
@@ -20,6 +21,13 @@ const { subscribeCompiledRendering } = require('./compile-renderer');
 // Render compiler 'compiled' events (previously direct stdout/stderr writes).
 subscribeCompiledRendering();
 
+// Watch never regenerates INI files, so applyPluginRule is only used as a skip
+// check here; the base only has to be a valid defaults layer.
+function pluginRuleBase(manifest) {
+  const { defaultIni, defaultDebug } = manifest.pluginIni;
+  return { ini: defaultIni, debug: defaultDebug === true };
+}
+
 async function runWatch(options) {
   const manifestPath = resolveManifestPath(options.manifest);
   const buildDir     = path.resolve(options.buildDir || './build');
@@ -52,8 +60,14 @@ async function runWatch(options) {
       for (const repoConfig of manifest.repos) {
         const key = repoKey(repoConfig);
         if (!cloneJobs.has(key)) {
+          // Cache-only, like before; ensureRepoDir returns `_localDir` for
+          // local entries (no network, no noFetch check).
           cloneJobs.set(key,
-            fetchRepo(repoConfig.repo, repoConfig._resolvedRef, resolveGithubToken(manifest, repoConfig.repo), true, manifest.github.ssh)
+            ensureRepoDir(repoConfig, {
+              token: resolveGithubToken(manifest, repoConfig.repo),
+              noFetch: true,
+              ssh: manifest.github.ssh,
+            })
           );
         }
       }
@@ -144,7 +158,7 @@ async function runWatch(options) {
       return enqueue(async () => {
         state.depGraph.update(smaPath);
         const smaRel = path.relative(state.scriptingRootDir, smaPath).split(path.sep).join('/');
-        const pluginRule = applyPluginRule(smaRel, state.manifest.pluginRules, state.manifest.globalPostfix);
+        const pluginRule = applyPluginRule(smaRel, state.manifest.plugins.rules, pluginRuleBase(state.manifest));
         if (!pluginRule) {
           logger.dim(`  Skipped by plugin rule: ${smaRel}`);
           return;
@@ -178,7 +192,7 @@ async function runWatch(options) {
           const compiled = [];
           for (const smaPath of affected) {
             const smaRel = path.relative(state.scriptingRootDir, smaPath).split(path.sep).join('/');
-            const pluginRule = applyPluginRule(smaRel, state.manifest.pluginRules, state.manifest.globalPostfix);
+            const pluginRule = applyPluginRule(smaRel, state.manifest.plugins.rules, pluginRuleBase(state.manifest));
             if (!pluginRule) {
               logger.dim(`  Skipped by plugin rule: ${smaRel}`);
               continue;

package/src/compile-utils.js

@@ -4,11 +4,113 @@ const fs   = require('fs');
 const path = require('path');
 const { execFile } = require('child_process');
 
+// ─── WSL DrvFs/9p input guard ────────────────────────────────────────────────
+//
+// amxxpc is a 32-bit Linux binary that cannot READ files on WSL DrvFs/9p mounts
+// (/mnt/c, /mnt/d, /mnt/j, …). A source or include dir there makes it fail with
+// "fatal error 100: cannot read from file" (a directory used as -i aborts it
+// with std::bad_alloc), even though the file exists and Node reads it fine.
+// Writing output to such a mount works. Catch this up-front and hand back an
+// actionable message instead of the cryptic compiler output.
+
+let _isWsl;
+let _mountpoints = null;
+
+function isWsl() {
+  if (_isWsl !== undefined) return _isWsl;
+  _isWsl = false;
+  if (process.platform === 'linux') {
+    if (process.env.WSL_DISTRO_NAME || process.env.WSL_INTEROP) {
+      _isWsl = true;
+    } else {
+      try {
+        _isWsl = /microsoft|wsl/i.test(fs.readFileSync('/proc/version', 'utf8'));
+      } catch (_) { /* no /proc/version — assume not WSL */ }
+    }
+  }
+  return _isWsl;
+}
+
+// "/proc/mounts" text → mountpoints whose fstype is 9p (WSL DrvFs).
+// Mountpoints escape spaces/tabs/backslashes as \040 / \011 / \134.
+function parse9pMountpoints(mountsText) {
+  const out = [];
+  for (const line of String(mountsText).split('\n')) {
+    const parts = line.split(/\s+/);
+    if (parts.length >= 4 && parts[2] === '9p') {
+      out.push(parts[1].replace(/\\([0-7]{3})/g, (_, oct) => String.fromCharCode(parseInt(oct, 8))));
+    }
+  }
+  return out;
+}
+
+function get9pMountpoints() {
+  if (_mountpoints) return _mountpoints;
+  _mountpoints = [];
+  if (process.platform === 'linux') {
+    try { _mountpoints = parse9pMountpoints(fs.readFileSync('/proc/mounts', 'utf8')); }
+    catch (_) { /* no /proc/mounts — nothing to guard */ }
+  }
+  return _mountpoints;
+}
+
+// Compiler argv → the paths amxxpc must READ (source + `-i` include dirs).
+// `-o` output paths are ignored — writing to a 9p mount works.
+function collectCompilerInputs(args) {
+  const inputs = [];
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === '-i') { if (args[i + 1]) inputs.push(args[++i]); continue; }
+    if (arg.startsWith('-i')) { inputs.push(arg.slice(2)); continue; }
+    if (arg === '-o') { i++; continue; }
+    if (arg.startsWith('-o')) continue;
+    if (i === 0 && !arg.startsWith('-')) inputs.push(arg); // source is argv[0]
+  }
+  return inputs.filter(Boolean);
+}
+
+function isUnder(p, dir) {
+  const abs = path.resolve(p);
+  if (abs === dir) return true;
+  return abs.startsWith(dir.endsWith('/') ? dir : dir + '/');
+}
+
+function findNonNativeInputs(args, mountpoints) {
+  return collectCompilerInputs(args).filter((p) => mountpoints.some((mp) => isUnder(p, mp)));
+}
+
+function nonNativeInputError(inputs) {
+  return [
+    'amxxpc cannot read files on WSL DrvFs/9p mounts (/mnt/*).',
+    'Unreadable input(s):',
+    ...inputs.map((p) => `  ${p}`),
+    'The compiler is a 32-bit Linux binary; on these mounts it fails with',
+    '"fatal error 100: cannot read from file" (an include directory aborts it with',
+    'std::bad_alloc), although the file exists and Node can read it.',
+    'Run the build from the Linux-native filesystem instead — copy the project to',
+    'e.g. ~/ (the ~/.cache/amxx-builder cache is shared, nothing re-downloads), or',
+    'run the build on Windows.',
+  ].join('\n');
+}
+
+/**
+ * Preflight for a compiler invocation. On WSL, when the source or any `-i`
+ * include dir sits on a DrvFs/9p mount, `ok` is false and `error` is a
+ * ready-to-print explanation. `wsl`/`mountpoints` are injectable for tests.
+ */
+function checkCompilerInputs(args, { wsl = isWsl(), mountpoints = get9pMountpoints() } = {}) {
+  if (!wsl || !mountpoints.length) return { ok: true, inputs: [], error: null };
+  const inputs = findNonNativeInputs(args, mountpoints);
+  if (!inputs.length) return { ok: true, inputs: [], error: null };
+  return { ok: false, inputs, error: nonNativeInputError(inputs) };
+}
+
 /**
  * Unified compiler spawn. Interface-agnostic core helper (used by the CLI build,
  * watch mode and the MCP compile tool).
  *
  * ALWAYS resolves — never rejects:
+ *  - WSL + input on a DrvFs/9p mount (/mnt/*): { status: 1, output: <explanation> }
  *  - on spawn error (ENOENT etc.): { status: 1, output: String(err.message) }
  *  - on close (including non-zero exit): { status: code, output: stdout+stderr merged }
  *
@@ -16,7 +118,11 @@ const { execFile } = require('child_process');
  * amxxpc needs its bundled libs). windowsHide: true keeps a console from
  * flashing on Windows.
  */
-function spawnCompiler(cmd, args, { maxBuffer = 10 * 1024 * 1024 } = {}) {
+function spawnCompiler(cmd, args, { maxBuffer = 10 * 1024 * 1024, ...guardOptions } = {}) {
+  const guard = checkCompilerInputs(args, guardOptions);
+  if (!guard.ok) {
+    return Promise.resolve({ status: 1, output: guard.error });
+  }
   return new Promise((resolve) => {
     const env = { ...process.env };
     if (process.platform === 'linux') {
@@ -71,4 +177,4 @@ function buildDefineArgs(defines) {
   return (defines || []).map((d) => (d.includes('=') ? d : `${d}=1`));
 }
 
-module.exports = { spawnCompiler, buildIncludeArgs, buildDefineArgs };
+module.exports = { spawnCompiler, buildIncludeArgs, buildDefineArgs, checkCompilerInputs, parse9pMountpoints };

package/src/compiler.js

@@ -9,19 +9,31 @@ const { repoKey, normalizeRepo } = require('./deps-resolver');
 
 /**
  * Applies plugin rules to a local .sma file path (relative to scripting/).
- * Returns null if the plugin should be skipped (enabled: false),
- * or { postfix, skipIni } where postfix is the INI postfix (false = skip INI).
+ *
+ * @param {string} smaRelPath - .sma path relative to scripting/
+ * @param {Array}  rules      - manifest.plugins.rules (first matching rule wins)
+ * @param {{ ini: false|string, debug: boolean }} base - plugins.defaults layer:
+ *   ini '' → plugins.ini, ini false → excluded from every INI
+ * @returns {null|{ postfix: string, skipIni: boolean, debug: boolean }} null
+ *   when the matching rule has enabled:false (skip the plugin entirely);
+ *   otherwise the effective INI postfix, whether the plugin is excluded from
+ *   every INI (ini:false), and the effective debug flag. `ini` unset/null and
+ *   `debug` unset/null inherit `base`.
  */
-function applyPluginRule(smaRelPath, rules, defaultPostfix) {
+function applyPluginRule(smaRelPath, rules, base) {
   const normalized = smaRelPath.split(path.sep).join('/');
   for (const rule of rules) {
     if (micromatch.isMatch(normalized, rule.match, { dot: true })) {
-      if (!rule.enabled) return null;
-      const postfix = rule.ini !== null ? rule.ini : defaultPostfix;
-      return { postfix, skipIni: rule.ini === false };
+      if (rule.enabled === false) return null;
+      const ini = rule.ini != null ? rule.ini : base.ini;
+      return {
+        postfix: ini === false ? '' : ini,
+        skipIni: ini === false,
+        debug: rule.debug != null ? rule.debug : base.debug,
+      };
     }
   }
-  return { postfix: defaultPostfix, skipIni: false };
+  return { postfix: base.ini === false ? '' : base.ini, skipIni: base.ini === false, debug: base.debug };
 }
 
 async function compilePlugins(manifest, repoLocalDirs, compilerPath, includeDirs, buildDir) {
@@ -30,6 +42,12 @@ async function compilePlugins(manifest, repoLocalDirs, compilerPath, includeDirs
 
   const collectedIncDir = path.join(buildDir, 'amxmodx', 'scripting', 'include');
 
+  // plugins.defaults is the base layer for every plugin (local + repo).
+  const pluginIni = manifest.pluginIni || { defaultIni: false, defaultDebug: false };
+  const base = { ini: pluginIni.defaultIni, debug: pluginIni.defaultDebug === true };
+  // AMXB_PLUGINS_DEBUG outranks rule/repo debug when set (true or false).
+  const forceDebug = pluginIni.forceDebug != null ? pluginIni.forceDebug : null;
+
   // ── Build unified source list ──────────────────────────────────────────────
   const seenSources = new Set(); // case-insensitive repo identity (dedupe)
   const sources = [];
@@ -46,7 +64,7 @@ async function compilePlugins(manifest, repoLocalDirs, compilerPath, includeDirs
         'scripting'
       ),
       exclude: repoConfig.exclude,
-      postfix: repoConfig.plugins_ini_postfix,
+      settings: repoConfig._pluginSettings || { ini: null, debug: null },
     });
   }
 
@@ -54,7 +72,7 @@ async function compilePlugins(manifest, repoLocalDirs, compilerPath, includeDirs
   if (fs.existsSync(localScriptingDir)) {
     sources.push({
       label: '(local)', ref: 'local', isLocal: true, scriptingDir: localScriptingDir,
-      exclude: [], postfix: manifest.globalPostfix,
+      exclude: [], settings: null,
     });
   }
 
@@ -62,7 +80,7 @@ async function compilePlugins(manifest, repoLocalDirs, compilerPath, includeDirs
   const onConflict = manifest.output.on_conflict || 'last_wins';
   const tasksByOut = new Map(); // outPath → task (dedupe cross-source collisions)
   for (const src of sources) {
-    const { scriptingDir, exclude, postfix, label, ref, isLocal = false } = src;
+    const { scriptingDir, exclude, settings, label, ref, isLocal = false } = src;
 
     if (!fs.existsSync(scriptingDir)) {
       logger.dim(`  ${label}: no scripting/ dir`);
@@ -86,23 +104,32 @@ async function compilePlugins(manifest, repoLocalDirs, compilerPath, includeDirs
     }
 
     for (const smaRel of smaFiles) {
-      let taskPostfix = postfix;
-      let skipIni     = false;
+      let taskPostfix;
+      let skipIni = false;
+      let taskDebug = base.debug;
 
       if (isLocal) {
-        const ruleResult = applyPluginRule(smaRel, manifest.pluginRules, postfix);
+        const ruleResult = applyPluginRule(smaRel, manifest.plugins.rules, base);
         if (!ruleResult) {
           logger.skip(`Skipped (plugin rule): ${smaRel}`);
           continue;
         }
         taskPostfix = ruleResult.postfix;
         skipIni     = ruleResult.skipIni;
+        taskDebug   = forceDebug != null ? forceDebug : ruleResult.debug;
+      } else {
+        const ini = settings.ini != null ? settings.ini : base.ini;
+        taskPostfix = ini === false ? '' : ini;
+        skipIni     = ini === false;
+        taskDebug   = forceDebug != null
+          ? forceDebug
+          : (settings.debug != null ? settings.debug : base.debug);
       }
 
       const baseName = path.basename(smaRel);
       const outName  = smaRel.replace(/\.sma$/, '.amxx').split(path.sep).join('/');
       const task = {
-        label, ref, postfix: taskPostfix, skipIni, baseName,
+        label, ref, postfix: taskPostfix, skipIni, debug: taskDebug, baseName,
         srcPath: path.join(scriptingDir, smaRel),
         outName,
         outPath: path.join(pluginsDir, ...outName.split('/')),
@@ -172,7 +199,7 @@ async function mapLimit(items, limit, fn) {
 }
 
 async function runCompile(compilerPath, task) {
-  const { srcPath, outPath, outName, includes, defines, baseName, postfix, skipIni, label, ref } = task;
+  const { srcPath, outPath, outName, includes, defines, baseName, postfix, skipIni, debug, label, ref } = task;
 
   fs.mkdirSync(path.dirname(outPath), { recursive: true });
   const args = [srcPath, `-o${outPath}`, ...includes, ...defines];
@@ -189,7 +216,7 @@ async function runCompile(compilerPath, task) {
 
   emit(EVENTS.COMPILED, { baseName, ok: true, output, amxxName: outName, repo: label, ref, outName });
 
-  return { amxxName: outName, plugins_ini_postfix: postfix, skipIni: skipIni || false, repo: label, ref };
+  return { amxxName: outName, plugins_ini_postfix: postfix, skipIni: skipIni || false, debug: debug === true, repo: label, ref };
 }
 
 async function findExcluded(dir, patterns) {

package/src/deps-resolver.js

@@ -3,7 +3,8 @@ const path = require('path');
 const glob = require('fast-glob');
 const logger = require('./logger');
 const { parseDepsLines, resolveGithubToken } = require('./manifest');
-const { fetchRepo, resolveRefIfLatest } = require('./repo-fetcher');
+const { isLocal } = require('./local-sources');
+const { fetchRepo, resolveRefIfLatest, applicableRefTtl } = require('./repo-fetcher');
 const { fetchReleaseDep } = require('./release-fetcher');
 const { fetchFungunDep } = require('./fungun-fetcher');
 
@@ -11,6 +12,9 @@ const { fetchFungunDep } = require('./fungun-fetcher');
  * Resolves all deps, clones them, copies .inc files to build/_includes/,
  * and returns an array of include-dir paths to pass to the compiler (-i flags).
  *
+ * Local deps (from ./local-sources) short-circuit first: their include dir is
+ * resolved from disk — no ref resolution, fetch or token lookup.
+ *
  * Priority: manifest.globalDeps > repo.deps_override > DEPS_LIST file in repo root
  */
 async function resolveDeps(manifest, repoLocalDirs, noFetch, buildDir) {
@@ -54,7 +58,9 @@ async function resolveDeps(manifest, repoLocalDirs, noFetch, buildDir) {
 
   for (const [k, dep] of merged) {
     let srcDir;
-    if (dep.source === 'release') {
+    if (isLocal(dep)) {
+      srcDir = resolveIncludePath(dep._localDir, dep.include_path, dep.repo);
+    } else if (dep.source === 'release') {
       const token = resolveGithubToken(manifest, dep.repo);
       srcDir = await fetchReleaseDep(dep, token, noFetch);
     } else if (dep.source === 'fungun') {
@@ -62,7 +68,10 @@ async function resolveDeps(manifest, repoLocalDirs, noFetch, buildDir) {
     } else {
       const token = resolveGithubToken(manifest, dep.repo);
       const resolvedDepRef = await resolveRefIfLatest(dep.ref, dep.repo, token);
-      const depDir = await fetchRepo(dep.repo, resolvedDepRef, token, noFetch, manifest.github.ssh);
+      const depDir = await fetchRepo(
+        dep.repo, resolvedDepRef, token, noFetch, manifest.github.ssh,
+        applicableRefTtl(dep.ref, dep.ref_ttl)
+      );
       srcDir = resolveIncludePath(depDir, dep.include_path, dep.repo);
     }
 
@@ -138,6 +147,9 @@ function resolveIncludePath(repoDir, explicitPath, repoName) {
  * Single source of truth shared by the build pipeline, the MCP server and
  * agent-assets resolution.
  *
+ * Local deps short-circuit on disk before any release/fungun/git branch — they
+ * need no token, ref, fetch or `--no-fetch` handling.
+ *
  * `dep` is a parsed dep OBJECT ({ repo, ref, source, include_path, asset }).
  * GitHub token resolution (per-owner fallbacks) is an interface-layer concern —
  * callers pass the already-resolved token, this function never calls fallbackToken.
@@ -150,6 +162,17 @@ function resolveIncludePath(repoDir, explicitPath, repoName) {
  * @returns {Promise<{ rootDir: string, label: string }>}
  */
 async function fetchDepRoot(dep, { token, noFetch, ssh = false } = {}) {
+  if (isLocal(dep)) {
+    if (dep.include_path) {
+      const sub = path.join(dep._localDir, dep.include_path);
+      if (!fs.existsSync(sub)) {
+        throw new Error(`include_path "${dep.include_path}" not found in ${dep.repo}`);
+      }
+      return { rootDir: sub, label: `${dep.repo} (local)` };
+    }
+    return { rootDir: dep._localDir, label: `${dep.repo} (local)` };
+  }
+
   if (dep.source === 'release') {
     const dir = await fetchReleaseDep(dep, token, noFetch);
     return { rootDir: dir, label: `${dep.repo}@${dep.ref} (release)` };
@@ -161,7 +184,9 @@ async function fetchDepRoot(dep, { token, noFetch, ssh = false } = {}) {
   }
 
   const resolvedRef = await resolveRefIfLatest(dep.ref, dep.repo, token);
-  const repoDir = await fetchRepo(dep.repo, resolvedRef, token, noFetch, ssh);
+  const repoDir = await fetchRepo(
+    dep.repo, resolvedRef, token, noFetch, ssh, applicableRefTtl(dep.ref, dep.ref_ttl)
+  );
   if (dep.include_path) {
     const sub = path.join(repoDir, dep.include_path);
     if (!fs.existsSync(sub)) {
@@ -173,11 +198,14 @@ async function fetchDepRoot(dep, { token, noFetch, ssh = false } = {}) {
 }
 
 /**
- * Fetch a dependency's include directory (release/fungun/git), using the
+ * Fetch a dependency's include directory (local/release/fungun/git), using the
  * fetch cache where possible.
  * Canonical single-source-of-truth shared by the build pipeline (include-tree),
  * the CLI, the serve interface and the MCP layer.
  *
+ * Local deps are always on disk — short-circuit to their `_localDir` before any
+ * token/ref/fetch logic (`--no-fetch` is irrelevant for them).
+ *
  * Explicit-include_path semantics: silently falls back to the repo root when
  * the given path does not exist (the interface callers rely on this).
  *
@@ -188,6 +216,8 @@ async function fetchDepRoot(dep, { token, noFetch, ssh = false } = {}) {
  * @returns {Promise<string>} directory to use as the include dir
  */
 async function fetchDepIncludeDir(dep, token, noFetch, ssh = false) {
+  if (isLocal(dep)) return findDepIncludeDir(dep._localDir, dep.include_path);
+
   if (dep.source === 'release') {
     return fetchReleaseDep(
       { repo: dep.repo, ref: dep.ref, include_path: dep.include_path, asset: dep.asset },
@@ -201,7 +231,9 @@ async function fetchDepIncludeDir(dep, token, noFetch, ssh = false) {
   }
 
   const resolvedRef = await resolveRefIfLatest(dep.ref, dep.repo, token);
-  const repoDir = await fetchRepo(dep.repo, resolvedRef, token, noFetch, ssh);
+  const repoDir = await fetchRepo(
+    dep.repo, resolvedRef, token, noFetch, ssh, applicableRefTtl(dep.ref, dep.ref_ttl)
+  );
   return findDepIncludeDir(repoDir, dep.include_path);
 }
 
@@ -218,6 +250,7 @@ async function fetchDepIncludeDir(dep, token, noFetch, ssh = false) {
  * interface's existing formatting.
  *
  * GitHub tokens are resolved per-owner via resolveGithubToken(manifest, repo);
+ * local deps skip the lookup entirely (null token — they never leave disk).
  * ssh must be passed explicitly by the caller (manifest.github.ssh).
  *
  * @param {object|null} manifest - parsed manifest (null → no deps)
@@ -233,7 +266,8 @@ async function collectDepIncludeDirs(manifest, { noFetch = false, ssh = false }
   for (let i = 0; i < deps.length; i++) {
     const dep = deps[i];
     try {
-      dirs[i] = await fetchDepIncludeDir(dep, resolveGithubToken(manifest, dep.repo), noFetch, ssh);
+      const token = isLocal(dep) ? null : resolveGithubToken(manifest, dep.repo);
+      dirs[i] = await fetchDepIncludeDir(dep, token, noFetch, ssh);
     } catch (err) {
       errors[i] = err && err.message ? err.message : String(err);
     }
@@ -245,11 +279,15 @@ async function collectDepIncludeDirs(manifest, { noFetch = false, ssh = false }
 // and dedup by core modules that previously inlined repo.toLowerCase()).
 function normalize(repo) { return repo.toLowerCase(); }
 
-// Human-readable dep label (fungun deps: no repo@ref — addressed by shop page id).
+// Human-readable dep label (fungun deps: no repo@ref — addressed by shop page
+// id; local deps: synthetic local/<name> id, versioned by the working tree).
 function depLabel(dep) {
   if (dep && dep.source === 'fungun') {
     return `fungun.net plugin #${dep.id}`;
   }
+  if (isLocal(dep)) {
+    return `${dep.repo} (local)`;
+  }
   return `${dep.repo}@${dep.ref || 'default branch'}`;
 }