agentsmesh 0.14.0 → 0.16.0

package/CHANGELOG.md

@@ -1,5 +1,37 @@
 # Changelog
 
+## 0.16.0
+
+### Minor Changes
+
+- 0b33c0d: Security and robustness hardening across MCP write tools, hook script generation, remote fetch, and canonical name validation. Some changes are behaviorally breaking; pre-1.0 minor bump per project policy.
+
+  **Hardening (no contract change)**
+  - MCP `add_mcp_server` / `update_mcp_server` / `update_hooks` / `update_permissions` now reject obviously malicious payloads at the schema layer (shell metacharacters in `command`, embedded newlines in matchers, env keys outside `[A-Za-z_][A-Za-z0-9_]*`, non-`http(s)` URLs, args arrays over 100, unknown server fields, permission patterns outside `Tool` / `Tool(matcher)`).
+  - Generated Copilot and Cline hook wrappers strip CR/LF from event/matcher/command before embedding them in the `# agentsmesh-*:` comment header so a multi-line YAML scalar cannot break out of the comment into executable shell.
+  - Generated `.sh` / `.bash` / `.zsh` files are now written with mode `0o755` so hooks emitted to disk are exec'able by the runner without a manual `chmod +x`.
+  - GitHub tarball downloads are capped at 500 MiB and aborted mid-stream when the running byte total exceeds the cap (Content-Length is also pre-checked).
+  - Git refs and clone URLs that begin with `-` are rejected to block `--upload-pack=…` style option injection.
+  - `MCP` non-`McpError` fallbacks redact absolute filesystem paths from raw `Error.message` strings; `IO_ERROR` envelopes carry the underlying `errno` in `details`.
+  - `parseAgents` / `parseCommands` / `parseRules` / `parseSkills` reject canonical filenames that are Windows reserved devices (CON, AUX, NUL, COM1–9, LPT1–9), contain `<>:|?*`, or end in `.`/space; nested basename collisions (e.g. `agents/foo.md` and `agents/sub/foo.md`) now error instead of silently last-write-wins.
+  - `loadAllPlugins` now collects all per-plugin failures and rethrows as a single combined error when any entry has `strict: true` or `AGENTSMESH_STRICT_PLUGINS=1` is set in the environment. Previous warn-and-skip behavior remains the default.
+
+  **Breaking**
+  - Generated hook wrappers run under `set -eu` instead of `set -e`. A canonical `command` that references an unset shell variable (`echo $VAR` where `$VAR` is never exported) will now abort the hook. Use `${VAR:-default}` syntax when an unset value is intentional.
+  - `AGENTSMESH_CACHE` must now be an absolute path that is not the filesystem root (`/` or a Windows drive root). Relative paths and roots throw at startup. Previously the value was used verbatim.
+  - MCP `create_rule` / `create_command` / `create_agent` and the canonical handlers reject names containing `/`. The `NAME_RE` validator was tightened from `[a-zA-Z0-9_/-]*` to `[a-zA-Z0-9_-]*` — names must be flat identifiers.
+  - Canonical files named after Windows reserved devices or with reserved characters now throw `CanonicalNameError` at parse time on every host (previously silent failure on Windows, success on POSIX).
+
+  **Internal**
+  - `src/mcp/register.ts`, `src/utils/filesystem/fs.ts`, `src/mcp/handlers/orchestrate.ts`, and `src/cli/commands/target-scaffold/templates.ts` were each split under the project's 200-line file budget. Public API surface (`./engine`, `./canonical`, `./targets`) is unchanged.
+  - New `executableModeFor(path)` helper in `src/utils/filesystem/fs.ts` infers the executable bit from the path extension; `writeFileAtomic` accepts an optional `{ mode }` override.
+
+## 0.15.0
+
+### Minor Changes
+
+- 1edb936: Homebrew tap and standalone-binary distribution. `brew tap samplexbro/agentsmesh && brew install agentsmesh` installs from a Homebrew formula auto-rendered against the published npm tarball; `curl -fsSL https://github.com/sampleXbro/agentsmesh/releases/latest/download/install.sh | sh` downloads a Node-free Bun-compiled binary for macOS (arm64/x64) and Linux (arm64/x64), verifies SHA256, installs to `~/.agentsmesh/bin`, and adds it to PATH for zsh, bash, and fish. The release workflow builds binaries for every supported platform on each `master` push, attaches them to a GitHub Release alongside `SHA256SUMS`, and pushes the formula to the tap repo; `workflow_dispatch` re-runs rebuild assets against an existing tag. Installer fails closed on missing/unverifiable checksums and rejects shell-unsafe `AGENTSMESH_INSTALL` paths.
+
 ## 0.14.0
 
 ### Minor Changes

package/README.md

@@ -24,6 +24,31 @@ AI coding assistants now ship with their own configuration formats — `CLAUDE.m
 
 ---
 
+## Install
+
+### npm (recommended for Node.js projects)
+
+```bash
+npm install -g agentsmesh
+```
+
+### Homebrew (macOS / Linux)
+
+```bash
+brew tap samplexbro/agentsmesh
+brew install agentsmesh
+```
+
+### Standalone binary (no Node.js required)
+
+```bash
+curl -fsSL https://github.com/sampleXbro/agentsmesh/releases/latest/download/install.sh | sh
+```
+
+Or download a binary directly from [GitHub Releases](https://github.com/sampleXbro/agentsmesh/releases/latest).
+
+---
+
 ## Before / After
 
 **Before — fragmented assistant-native config in one repo:**
@@ -64,7 +89,7 @@ The native files above are still emitted — AgentsMesh writes them for you from
 
 ## 60-second quickstart
 
-Requires Node.js 20+. Works on Linux, macOS, and Windows (native, not WSL).
+Works on Linux, macOS, and Windows. The `npx` commands below require Node.js 20+; see [Install](#install) for alternatives that don't need Node.js.
 
 ```bash
 npx agentsmesh init       # scaffold .agentsmesh/ + agentsmesh.yaml
@@ -234,7 +259,7 @@ agentsmesh generate            # plugin targets run alongside built-ins
 agentsmesh generate --global   # global mode works for plugins too
 ```
 
-Plugins have full parity with built-in targets: project + global layouts, feature conversions, scoped settings, per-feature lint hooks, and hook post-processing. [Build a plugin →](https://samplexbro.github.io/agentsmesh/guides/building-plugins/)
+Plugins have full parity with built-in targets: project + global layouts, feature conversions, scoped settings, per-feature lint hooks, and hook post-processing. By default a failed plugin import logs a warning and is skipped; set `strict: true` on the plugin entry or run `AGENTSMESH_STRICT_PLUGINS=1 agentsmesh generate` to fail the build instead — useful in CI where a missing target is a real regression. [Build a plugin →](https://samplexbro.github.io/agentsmesh/guides/building-plugins/)
 
 ### Team-safe collaboration & CI drift detection
 

package/dist/canonical.d.ts

@@ -1,5 +1,5 @@
-import { b as CanonicalFiles, V as ValidatedConfig } from './schema-o4oXUVBP.js';
-export { C as CanonicalAgent, a as CanonicalCommand, c as CanonicalRule, d as CanonicalSkill, H as HookEntry, e as Hooks, I as IgnorePatterns, M as McpConfig, f as McpServer, P as Permissions, S as SkillSupportingFile, g as StdioMcpServer, U as UrlMcpServer } from './schema-o4oXUVBP.js';
+import { b as CanonicalFiles, V as ValidatedConfig } from './schema-CD2qcmDL.js';
+export { C as CanonicalAgent, a as CanonicalCommand, c as CanonicalRule, d as CanonicalSkill, H as HookEntry, e as Hooks, I as IgnorePatterns, M as McpConfig, f as McpServer, P as Permissions, S as SkillSupportingFile, g as StdioMcpServer, U as UrlMcpServer } from './schema-CD2qcmDL.js';
 import 'zod';
 
 /**

package/dist/canonical.js

@@ -1,5 +1,5 @@
-import { access, readdir, realpath, stat, readFile, rm, mkdir, writeFile, rename, lstat, unlink } from 'fs/promises';
 import { join, basename, dirname, resolve, relative, posix, win32, extname } from 'path';
+import { access, readdir, realpath, stat, readFile, rm, mkdir, writeFile, rename, lstat, unlink, chmod } from 'fs/promises';
 import { constants, existsSync, realpathSync, statSync } from 'fs';
 import { parse, stringify } from 'yaml';
 import { parse as parse$1 } from 'smol-toml';
@@ -79,6 +79,104 @@ function shouldNormalizeLineEndings(path) {
 function normalizeLineEndings(content) {
   return content.replace(/\r\n?/g, "\n");
 }
+function executableModeFor(path) {
+  return EXECUTABLE_SCRIPT_EXTENSIONS.has(extname(path).toLowerCase()) ? 493 : void 0;
+}
+var UTF8_BOM, TEXT_EXTENSIONS, TEXT_DOTFILES, EXECUTABLE_SCRIPT_EXTENSIONS;
+var init_fs_text_encoding = __esm({
+  "src/utils/filesystem/fs-text-encoding.ts"() {
+    UTF8_BOM = "\uFEFF";
+    TEXT_EXTENSIONS = /* @__PURE__ */ new Set([
+      ".md",
+      ".mdc",
+      ".mdx",
+      ".markdown",
+      ".txt",
+      ".json",
+      ".jsonc",
+      ".yaml",
+      ".yml",
+      ".toml",
+      ".ini",
+      ".sh",
+      ".bash",
+      ".zsh",
+      ".ps1",
+      ".js",
+      ".mjs",
+      ".cjs",
+      ".ts",
+      ".tsx",
+      ".html",
+      ".css"
+    ]);
+    TEXT_DOTFILES = /* @__PURE__ */ new Set([
+      ".gitignore",
+      ".cursorignore",
+      ".cursorindexingignore",
+      ".aiignore",
+      ".agentignore",
+      ".clineignore",
+      ".geminiignore",
+      ".codeiumignore",
+      ".continueignore",
+      ".copilotignore",
+      ".windsurfignore",
+      ".junieignore",
+      ".kiroignore",
+      ".rooignore",
+      ".antigravityignore"
+    ]);
+    EXECUTABLE_SCRIPT_EXTENSIONS = /* @__PURE__ */ new Set([".sh", ".bash", ".zsh"]);
+  }
+});
+async function readDirRecursive(dir, visited) {
+  let canonicalDir;
+  try {
+    canonicalDir = await realpath(dir);
+  } catch (err) {
+    const e = err;
+    if (e.code === "ENOENT" || e.code === "ENOTDIR" || e.code === "ELOOP") return [];
+    throw new FileSystemError(
+      dir,
+      `Failed to read directory ${dir}: ${e.message}. Check permissions.`,
+      { cause: err, errnoCode: e.code }
+    );
+  }
+  const seen = visited ?? /* @__PURE__ */ new Set();
+  if (seen.has(canonicalDir)) return [];
+  seen.add(canonicalDir);
+  try {
+    const entries = await readdir(dir, { withFileTypes: true });
+    const files = [];
+    for (const ent of entries) {
+      const full = join(dir, ent.name);
+      const walkChild = ent.isDirectory() || ent.isSymbolicLink() && await stat(full).then(
+        (s) => s.isDirectory(),
+        () => false
+      );
+      if (walkChild) {
+        files.push(...await readDirRecursive(full, seen));
+      } else {
+        files.push(full);
+      }
+    }
+    return files;
+  } catch (err) {
+    const e = err;
+    if (e.code === "ENOENT" || e.code === "ENOTDIR" || e.code === "EACCES") return [];
+    throw new FileSystemError(
+      dir,
+      `Failed to read directory ${dir}: ${e.message}. Check permissions.`,
+      { cause: err, errnoCode: e.code }
+    );
+  }
+}
+var init_fs_traverse = __esm({
+  "src/utils/filesystem/fs-traverse.ts"() {
+    init_errors();
+  }
+});
 async function readFileSafe(path) {
   try {
     const data = await readFile(path, "utf-8");
@@ -93,7 +191,7 @@ async function readFileSafe(path) {
     );
   }
 }
-async function writeFileAtomic(path, content) {
+async function writeFileAtomic(path, content, options) {
   const dir = dirname(path);
   await mkdir(dir, { recursive: true });
   try {
@@ -117,6 +215,7 @@ async function writeFileAtomic(path, content) {
   }
   const tmpPath = `${path}.tmp`;
   const payload = shouldNormalizeLineEndings(path) ? normalizeLineEndings(content) : content;
+  const mode = executableModeFor(path);
   try {
     try {
       const tmpInfo = await lstat(tmpPath);
@@ -126,8 +225,16 @@ async function writeFileAtomic(path, content) {
     } catch (tmpErr) {
       if (tmpErr.code !== "ENOENT") throw tmpErr;
     }
-    await writeFile(tmpPath, payload, { encoding: "utf-8", flag: "w" });
+    const writeOpts = {
+      encoding: "utf-8",
+      flag: "w"
+    };
+    if (mode !== void 0) writeOpts.mode = mode;
+    await writeFile(tmpPath, payload, writeOpts);
     await rename(tmpPath, path);
+    if (mode !== void 0) {
+      await chmod(path, mode);
+    }
   } catch (err) {
     await rm(tmpPath, { force: true }).catch(() => {
     });
@@ -150,94 +257,12 @@ async function exists(path) {
 async function mkdirp(path) {
   await mkdir(path, { recursive: true });
 }
-async function readDirRecursive(dir, visited) {
-  let canonicalDir;
-  try {
-    canonicalDir = await realpath(dir);
-  } catch (err) {
-    const e = err;
-    if (e.code === "ENOENT" || e.code === "ENOTDIR" || e.code === "ELOOP") return [];
-    throw new FileSystemError(
-      dir,
-      `Failed to read directory ${dir}: ${e.message}. Check permissions.`,
-      { cause: err, errnoCode: e.code }
-    );
-  }
-  const seen = visited ?? /* @__PURE__ */ new Set();
-  if (seen.has(canonicalDir)) return [];
-  seen.add(canonicalDir);
-  try {
-    const entries = await readdir(dir, { withFileTypes: true });
-    const files = [];
-    for (const ent of entries) {
-      const full = join(dir, ent.name);
-      const walkChild = ent.isDirectory() || ent.isSymbolicLink() && await stat(full).then(
-        (s) => s.isDirectory(),
-        () => false
-      );
-      if (walkChild) {
-        files.push(...await readDirRecursive(full, seen));
-      } else {
-        files.push(full);
-      }
-    }
-    return files;
-  } catch (err) {
-    const e = err;
-    if (e.code === "ENOENT" || e.code === "ENOTDIR" || e.code === "EACCES") return [];
-    throw new FileSystemError(
-      dir,
-      `Failed to read directory ${dir}: ${e.message}. Check permissions.`,
-      { cause: err, errnoCode: e.code }
-    );
-  }
-}
-var UTF8_BOM, TEXT_EXTENSIONS, TEXT_DOTFILES;
 var init_fs = __esm({
   "src/utils/filesystem/fs.ts"() {
     init_errors();
-    UTF8_BOM = "\uFEFF";
-    TEXT_EXTENSIONS = /* @__PURE__ */ new Set([
-      ".md",
-      ".mdc",
-      ".mdx",
-      ".markdown",
-      ".txt",
-      ".json",
-      ".jsonc",
-      ".yaml",
-      ".yml",
-      ".toml",
-      ".ini",
-      ".sh",
-      ".bash",
-      ".zsh",
-      ".ps1",
-      ".js",
-      ".mjs",
-      ".cjs",
-      ".ts",
-      ".tsx",
-      ".html",
-      ".css"
-    ]);
-    TEXT_DOTFILES = /* @__PURE__ */ new Set([
-      ".gitignore",
-      ".cursorignore",
-      ".cursorindexingignore",
-      ".aiignore",
-      ".agentignore",
-      ".clineignore",
-      ".geminiignore",
-      ".codeiumignore",
-      ".continueignore",
-      ".copilotignore",
-      ".windsurfignore",
-      ".junieignore",
-      ".kiroignore",
-      ".rooignore",
-      ".antigravityignore"
-    ]);
+    init_fs_text_encoding();
+    init_fs_traverse();
+    init_fs_text_encoding();
   }
 });
 function parseFrontmatter(content) {
@@ -3998,13 +4023,16 @@ function generateAgents4(canonical) {
 function safeEventName(event) {
   return event.replace(/[^a-zA-Z0-9]/g, "-").toLowerCase();
 }
+function safeShellLine(value) {
+  return value.replace(/[\r\n]+/g, " ");
+}
 function buildHookScript(event, command, matcher) {
   return [
     "#!/usr/bin/env bash",
-    `# agentsmesh-event: ${event}`,
-    `# agentsmesh-matcher: ${matcher}`,
-    `# agentsmesh-command: ${command}`,
-    "set -e",
+    `# agentsmesh-event: ${safeShellLine(event)}`,
+    `# agentsmesh-matcher: ${safeShellLine(matcher)}`,
+    `# agentsmesh-command: ${safeShellLine(command)}`,
+    "set -eu",
     command,
     ""
   ].join("\n");
@@ -6461,7 +6489,7 @@ function extractMatcher(comment) {
 function extractWrapperCommand(content) {
   const metadataMatch = content.match(/^# agentsmesh-command:\s*(.+)$/m);
   if (metadataMatch?.[1]) return metadataMatch[1].trim();
-  return content.replace(/^#!.*\n/, "").replace(/^#.*\n/gm, "").replace(/^HOOK_DIR=.*\n/gm, "").replace(/^set -e\n?/m, "").trim();
+  return content.replace(/^#!.*\n/, "").replace(/^#.*\n/gm, "").replace(/^HOOK_DIR=.*\n/gm, "").replace(/^set -e[u]?\n?/m, "").trim();
 }
 async function importHooks(projectRoot, results) {
   const hooksDir = join(projectRoot, COPILOT_HOOKS_DIR);
@@ -6783,12 +6811,15 @@ async function buildAssetOutput(projectRoot, command) {
 function wrapperPath(event, index) {
   return `${COPILOT_HOOKS_DIR}/scripts/${safePhaseName(event)}-${index}.sh`;
 }
+function safeShellLine2(value) {
+  return value.replace(/[\r\n]+/g, " ");
+}
 function buildWrapper(command, matcher) {
   return [
     "#!/usr/bin/env bash",
-    `# agentsmesh-matcher: ${matcher}`,
-    `# agentsmesh-command: ${command}`,
-    "set -e",
+    `# agentsmesh-matcher: ${safeShellLine2(matcher)}`,
+    `# agentsmesh-command: ${safeShellLine2(command)}`,
+    "set -eu",
     command,
     ""
   ].join("\n");
@@ -6812,8 +6843,8 @@ async function addHookScriptAssets(projectRoot, canonical, outputs) {
         }
       }
       const wrapper = buildWrapper(command, entry.matcher).replace(
-        "set -e\n",
-        'set -e\nHOOK_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"\n'
+        "set -eu\n",
+        'set -eu\nHOOK_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"\n'
       );
       wrapperOutputs.push({ path: scriptPath, content: wrapper });
       index++;
@@ -14417,6 +14448,13 @@ init_fs();
 init_fs();
 var execFileAsync = promisify(execFile);
 var REPO_DIRNAME = "repo";
+function ensureNotFlag(value, kind) {
+  if (value.startsWith("-")) {
+    throw new Error(
+      `agentsmesh refuses ${kind} starting with "-" (option-injection guard): ${value}`
+    );
+  }
+}
 async function fetchGitRemoteExtend(parsed, extendName, options, cacheDir, buildCacheKey2) {
   const provider = "cloneUrl" in parsed ? "gitlab" : "git";
   const identifier = "cloneUrl" in parsed ? `${parsed.namespace}/${parsed.project}` : parsed.url;
@@ -14474,9 +14512,11 @@ function resolveCloneUrl(parsed) {
   return parsed.url;
 }
 async function cloneRepo(cloneUrl, repoDir) {
+  ensureNotFlag(cloneUrl, "clone-url");
   await runGit(["clone", cloneUrl, repoDir]);
 }
 async function checkoutRef(repoDir, ref) {
+  ensureNotFlag(ref, "ref");
   await runGit(["checkout", ref], repoDir);
 }
 async function getHeadSha(repoDir) {
@@ -14495,6 +14535,46 @@ async function runGit(args, cwd) {
 
 // src/config/remote/github-remote.ts
 init_fs();
+var MAX_TARBALL_BYTES = 500 * 1024 * 1024;
+async function readBoundedResponse(res, maxBytes) {
+  const lenHeader = typeof res.headers?.get === "function" ? res.headers.get("content-length") : null;
+  if (lenHeader !== null) {
+    const declared = Number(lenHeader);
+    if (Number.isFinite(declared) && declared > maxBytes) {
+      throw new Error(`remote response declared ${declared} bytes; exceeds cap of ${maxBytes}`);
+    }
+  }
+  const stream = res.body;
+  if (!stream) {
+    const buf = await res.arrayBuffer();
+    if (buf.byteLength > maxBytes) {
+      throw new Error(`remote response is ${buf.byteLength} bytes; exceeds cap of ${maxBytes}`);
+    }
+    return new Uint8Array(buf);
+  }
+  const reader = stream.getReader();
+  const chunks = [];
+  let total = 0;
+  for (; ; ) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    if (!value) continue;
+    total += value.byteLength;
+    if (total > maxBytes) {
+      await reader.cancel().catch(() => {
+      });
+      throw new Error(`remote response exceeded cap of ${maxBytes} bytes during streaming`);
+    }
+    chunks.push(value);
+  }
+  const out2 = new Uint8Array(total);
+  let offset = 0;
+  for (const c2 of chunks) {
+    out2.set(c2, offset);
+    offset += c2.byteLength;
+  }
+  return out2;
+}
 async function resolveLatestTag(org, repo, token) {
   const url = `https://api.github.com/repos/${org}/${repo}/releases/latest`;
   const headers = {
@@ -14534,11 +14614,11 @@ async function fetchGithubRemoteExtend(parsed, extendName, options, cacheDir, bu
   const tarballUrl = `https://github.com/${parsed.org}/${parsed.repo}/tarball/${tag}`;
   const headers = {};
   if (token) headers.Authorization = `Bearer ${token}`;
-  let tarballBuffer;
+  let tarballBytes;
   try {
     const res = await globalThis.fetch(tarballUrl, { headers, redirect: "follow" });
     if (!res.ok) throw new Error(`HTTP ${res.status}: ${res.statusText}`);
-    tarballBuffer = await res.arrayBuffer();
+    tarballBytes = await readBoundedResponse(res, MAX_TARBALL_BYTES);
   } catch (err) {
     const allowFallback = options.allowOfflineFallback !== false;
     if (allowFallback && await exists(extractDir)) {
@@ -14555,7 +14635,7 @@ async function fetchGithubRemoteExtend(parsed, extendName, options, cacheDir, bu
   await rm(extractDir, { recursive: true, force: true });
   await mkdir(extractDir, { recursive: true });
   const tarPath = join(extractDir, "archive.tar.gz");
-  await writeFile(tarPath, new Uint8Array(tarballBuffer));
+  await writeFile(tarPath, tarballBytes);
   try {
     await tar.extract({
       file: tarPath,
@@ -14727,7 +14807,20 @@ function buildCacheKey(provider, identifier, ref) {
 }
 function getCacheDir() {
   const env = process.env.AGENTSMESH_CACHE;
-  if (env) return env;
+  if (env) {
+    const trimmed = env.trim();
+    if (!trimmed) {
+      return join(homedir(), ".agentsmesh", "cache");
+    }
+    const isAbs = /^([A-Za-z]:[\\/]|\/)/.test(trimmed);
+    if (!isAbs) {
+      throw new Error(`AGENTSMESH_CACHE must be an absolute path (got: "${trimmed}").`);
+    }
+    if (trimmed === "/" || /^[A-Za-z]:[\\/]?$/.test(trimmed)) {
+      throw new Error(`AGENTSMESH_CACHE must not be the filesystem root (got: "${trimmed}").`);
+    }
+    return trimmed;
+  }
   return join(homedir(), ".agentsmesh", "cache");
 }
 async function fetchRemoteExtend(source, extendName, options = {}) {
@@ -14819,6 +14912,98 @@ async function resolveExtendPaths(config, configDir, options = {}) {
 // src/canonical/features/rules.ts
 init_fs();
 init_markdown();
+
+// src/utils/filesystem/windows-path-safety.ts
+var WINDOWS_RESERVED_NAMES = /* @__PURE__ */ new Set([
+  "CON",
+  "PRN",
+  "AUX",
+  "NUL",
+  "COM1",
+  "COM2",
+  "COM3",
+  "COM4",
+  "COM5",
+  "COM6",
+  "COM7",
+  "COM8",
+  "COM9",
+  "LPT1",
+  "LPT2",
+  "LPT3",
+  "LPT4",
+  "LPT5",
+  "LPT6",
+  "LPT7",
+  "LPT8",
+  "LPT9"
+]);
+var WINDOWS_ILLEGAL_CHARS = new RegExp('[<>:"|?*\\u0000-\\u001F]');
+function segmentReservedName(segment) {
+  const stem = segment.replace(/\.[^.]*$/, "").toUpperCase();
+  return WINDOWS_RESERVED_NAMES.has(stem);
+}
+function findWindowsPathIssues(path) {
+  const issues = [];
+  const segments = path.split(/[\\/]/);
+  for (const segment of segments) {
+    if (segment === "" || segment === "." || segment === "..") continue;
+    if (WINDOWS_ILLEGAL_CHARS.test(segment)) {
+      issues.push({ segment, reason: "illegal-character" });
+      continue;
+    }
+    if (/[. ]$/.test(segment)) {
+      issues.push({ segment, reason: "trailing-dot-or-space" });
+      continue;
+    }
+    if (segmentReservedName(segment)) {
+      issues.push({ segment, reason: "reserved-name" });
+    }
+  }
+  return issues;
+}
+
+// src/canonical/features/validate-name.ts
+var CanonicalNameError = class extends Error {
+  feature;
+  name;
+  constructor(feature, name, message) {
+    super(message);
+    this.feature = feature;
+    this.name = name;
+  }
+};
+function assertCanonicalName(feature, name) {
+  const issues = findWindowsPathIssues(name);
+  if (issues.length === 0) return;
+  const reasons = issues.map((i) => `${i.segment} (${i.reason})`).join(", ");
+  throw new CanonicalNameError(
+    feature,
+    name,
+    `canonical ${feature} name "${name}" is not portable to Windows: ${reasons}. Rename the file.`
+  );
+}
+function assertNoBasenameCollisions(feature, paths, stripExt) {
+  const seen = /* @__PURE__ */ new Map();
+  for (const p of paths) {
+    const fwdIdx = p.lastIndexOf("/");
+    const bckIdx = p.lastIndexOf("\\");
+    const idx = Math.max(fwdIdx, bckIdx);
+    const base = idx === -1 ? p : p.slice(idx + 1);
+    const slug = base.endsWith(stripExt) ? base.slice(0, -stripExt.length) : base;
+    const prior = seen.get(slug);
+    if (prior !== void 0 && prior !== p) {
+      throw new CanonicalNameError(
+        feature,
+        slug,
+        `canonical ${feature} files collide on slug "${slug}": ${prior} vs ${p}. Rename one.`
+      );
+    }
+    seen.set(slug, p);
+  }
+}
+
+// src/canonical/features/rules.ts
 var VALID_TRIGGERS = ["always_on", "model_decision", "glob", "manual"];
 function toStrArray(v) {
   if (Array.isArray(v)) return v.filter((x) => typeof x === "string");
@@ -14838,6 +15023,7 @@ async function parseRules(rulesDir) {
     if (!content) continue;
     const { frontmatter, body } = parseFrontmatter(content);
     const name = basename(path, ".md");
+    assertCanonicalName("rule", name);
     const rootFromFilename = name === "_root";
     const rootFromFm = frontmatter.root === true;
     const triggerRaw = frontmatter.trigger;
@@ -14879,12 +15065,14 @@ function toToolsArray(v) {
 async function parseCommands(commandsDir) {
   const files = await readDirRecursive(commandsDir);
   const mdFiles = files.filter((f) => f.endsWith(".md") && !basename(f).startsWith("_"));
+  assertNoBasenameCollisions("command", mdFiles, ".md");
   const commands = [];
   for (const path of mdFiles) {
     const content = await readFileSafe(path);
     if (!content) continue;
     const { frontmatter, body } = parseFrontmatter(content);
     const name = basename(path, ".md");
+    assertCanonicalName("command", name);
     const fromCamel = toToolsArray(frontmatter.allowedTools);
     const fromKebab = toToolsArray(frontmatter["allowed-tools"]);
     const allowedTools = fromCamel.length > 0 ? fromCamel : fromKebab;
@@ -14932,12 +15120,14 @@ function toHooks(v) {
 async function parseAgents(agentsDir) {
   const files = await readDirRecursive(agentsDir);
   const mdFiles = files.filter((f) => f.endsWith(".md") && !basename(f).startsWith("_"));
+  assertNoBasenameCollisions("agent", mdFiles, ".md");
   const agents = [];
   for (const path of mdFiles) {
     const content = await readFileSafe(path);
     if (!content) continue;
     const { frontmatter, body } = parseFrontmatter(content);
     const name = basename(path, ".md");
+    assertCanonicalName("agent", name);
     const toolsCamel = toStrArray2(frontmatter.tools);
     const toolsKebab = toStrArray2(frontmatter["tools"]);
     const tools = toolsCamel.length > 0 ? toolsCamel : toolsKebab;
@@ -15005,9 +15195,11 @@ async function parseSkillDirectory(skillDir) {
   const { frontmatter, body } = parseFrontmatter(content);
   const supportingFiles = await listSupportingFiles(skillDir);
   const fmName = typeof frontmatter.name === "string" ? sanitizeSkillName(frontmatter.name) : "";
+  const name = fmName || basename(skillDir);
+  assertCanonicalName("skill", name);
   return {
     source: skillPath,
-    name: fmName || basename(skillDir),
+    name,
     description: typeof frontmatter.description === "string" ? frontmatter.description : "",
     body,
     supportingFiles
@@ -15024,6 +15216,7 @@ async function parseSkills(skillsDir) {
   for (const ent of entries) {
     if (!ent.isDirectory()) continue;
     if (ent.name.startsWith("_")) continue;
+    assertCanonicalName("skill", ent.name);
     const skillDir = join(skillsDir, ent.name);
     const skillPath = join(skillDir, SKILL_FILE);
     const content = await readFileSafe(skillPath);
@@ -15842,7 +16035,15 @@ var conversionsSchema = z.object({
 var pluginEntrySchema = z.object({
   id: z.string().regex(/^[a-z][a-z0-9-]*$/),
   source: z.string(),
-  version: z.string().optional()
+  version: z.string().optional(),
+  /**
+   * When true, a failure to import or validate this plugin throws and
+   * aborts the run. Default `false` keeps the lenient behavior of logging
+   * a warning and continuing. Use strict mode in CI when missing
+   * descriptors should fail the build instead of silently shrinking the
+   * generation matrix.
+   */
+  strict: z.boolean().optional()
 }).strict();
 var configSchema = z.object({
   version: z.literal(1),