agentsmesh 0.3.0 → 0.5.0

package/CHANGELOG.md

@@ -1,6 +1,66 @@
 # Changelog
 
-## Next version
+## 0.5.0
+
+### Minor Changes
+
+- ec5e3a6: **Breaking (descriptor authors):** Built-in targets now declare global mode under `globalSupport` (capabilities, detection paths, layout, optional `scopeExtras`) instead of separate `global`, `globalCapabilities`, and `globalDetectionPaths` fields. Command/workflow and Gemini settings generation are modeled with capability **flavors** on the canonical generators; Copilot/Cursor root mirrors use `layout.outputFamilies` for rewrite cache keys.
+
+  **CLI / docs:** `pnpm matrix:generate` refreshes README and website support-matrix blocks from the catalog; `pnpm matrix:verify` fails on drift (also runs in CI). Init detection uses `collectDetectionPaths` from the catalog.
+
+- ec5e3a6: Add public library entry points (`./engine`, `./canonical`, `./targets`) for programmatic use, introduce the parametrized target contract matrix under `tests/contract/`, and document coverage exclusions in `tasks/coverage-gaps.md`.
+
+## 0.4.1 - 2026-04-23
+
+### Added
+
+- **JSON Schema for all config files** — `agentsmesh.yaml`, `agentsmesh.local.yaml`, `.agentsmesh/permissions.yaml`, `.agentsmesh/hooks.yaml`, `.agentsmesh/mcp.json`, and `.agentsmesh/packs/*/pack.yaml` now ship with JSON Schemas derived directly from Zod source schemas. Enables full IDE autocomplete, enum validation, and hover docs in VS Code, JetBrains, and any YAML/JSON Language Server with zero user configuration. Schemas are published to `schemas/` in the npm package and accessible at `https://unpkg.com/agentsmesh/schemas/*.json`. Run `pnpm schemas:generate` to regenerate after schema changes.
+- **`$schema` comment in generated config files** — `agentsmesh init` now writes a `# yaml-language-server: $schema=...` comment as the first line of both `agentsmesh.yaml` and `agentsmesh.local.yaml`, activating IDE validation without any manual setup.
+- **Global mode** (`--global`, canonical `~/.agentsmesh/`) for **all** built-in targets — Claude Code, Cursor, Copilot, Continue, Junie, Kiro, Gemini CLI, Cline, Codex CLI, Windsurf, Antigravity, and Roo Code. Each target has a `descriptor.global` layout with project→user path rewriting, import/generate alignment, optional `~/.agents/skills/` mirroring when Codex CLI is not a global target, reference/link rewriting, and comprehensive test coverage.
+- **Roo Code agents → custom modes**: canonical agents now generate `.roomodes` (project) and `settings/custom_modes.yaml` (global) with a `customModes` YAML structure. Roo Code agents capability upgraded from `—` to `partial`.
+- **Copilot global extras**: `~/.copilot/AGENTS.md` is now generated in global mode as a root-instructions compat file.
+- **Continue global config**: global mode generates `~/.continue/config.yaml` (aggregating rules as `rules:`, commands as `prompts:`, MCP as `mcpServers:`) and `~/.continue/AGENTS.md`.
+- **Copilot global skill mirror**: skills are now mirrored to both `~/.agents/skills/` and `~/.claude/skills/` in global mode.
+- **Cline global hooks round-trip**: `agentsmesh import --from cline` now reads hook scripts from `~/Documents/Cline/Hooks/` (global mode) and `.clinerules/hooks/` (project mode). Hook scripts embed a `# agentsmesh-event: <event>` metadata comment for lossless round-trip; the generator also includes this comment going forward.
+- `sharedArtifacts` field added to target descriptor — enables collision-free generation when multiple targets share an output path (e.g. `.agents/skills/`).
+- Lint hooks wired to all target descriptors.
+- Contributor skill **`add-global-mode-target`** for scoped work when extending or validating one target’s global-mode behavior.
+- Comprehensive structure validation test coverage for all 12 targets in both project and global modes.
+- Shared validation helpers library (`tests/unit/targets/validation-helpers.ts`) with reusable helpers for JSON, Markdown, YAML, frontmatter, and file structure validation.
+
+### Fixed
+
+- **Claude Code output-styles**: generated output-style files no longer carry `agent-` / `command-` filename prefixes — now `{name}.md` as documented.
+- **Windsurf**: `src/AGENTS.md` removed from `managedOutputs` (was incorrectly tracked as a managed file).
+- **Cline**: `.clinerules/` directory added to `managedOutputs.dirs` for correct stale-artifact cleanup after `generate`.
+- **Copilot global instructions**: path-specific instructions now aggregate into `~/.copilot/copilot-instructions.md` in global mode (previously suppressed).
+- **Windsurf MCP capability**: both project and global scopes now consistently `partial` (global was incorrectly `native`).
+- **Codex CLI detection**: detection paths expanded to include `AGENTS.md`, `AGENTS.override.md`, `.codex/config.toml`, `.codex/agents`, and `.codex/rules`.
+- **Link rebaser**: `.agentsmesh/` anchor preserved correctly in generated prose.
+
+### Changed
+
+- **Init scaffold:** example files created by `agentsmesh init` are now prefixed with `_` (`_example.md`, `skills/_example/SKILL.md`). Files and directories with a `_` prefix are excluded from generation, so the starter templates serve as visible reference only and do not produce tool-specific output. `_root.md` remains the sole `_`-prefixed file that is always included in generation.
+- **Documentation:** README and website updated to reflect Roo Code agents support, Copilot and Continue global extras, and the new `schemas/` package contents. `generate.mdx` documents global mode path resolution (how `--global` maps to `homedir()` as `projectRoot`).
+
+### Refactored
+
+- Extracted `mirrorSkillsToAgents()` shared helper (`src/targets/catalog/skill-mirror.ts`) — replaces repeated `!activeTargets.includes(‘codex-cli’)` guards inline across 8 target files.
+- Consolidated import map builders; removed duplicate validation tests.
+- Extracted shared skill-import pipeline; deleted obsolete `skills-helpers` files.
+- Improved link rebaser resolution and managed embedding.
+- Removed unused `COPILOT_GLOBAL_MCP` / `COPILOT_GLOBAL_CONFIG` constants.
+
+## 0.3.1 - 2026-04-12
+
+### Changed
+
+- Refresh direct and transitive dependencies to patched releases, including guarded `pnpm` overrides for vulnerable `vite`, `picomatch`, and `brace-expansion` ranges pulled in through the toolchain.
+
+### Fixed
+
+- Remove the brittle `npm install -g npm@latest` step from the npm trusted-publishing workflow and run the publish job on Node 24 so release automation uses a bundled npm that already satisfies trusted-publishing requirements.
+- Harden `watch` command unit-test wait budgets after the Vitest upgrade so the full suite stays stable under slower CI and coverage runs.
 
 ## 0.3.0 - 2026-04-12
 

package/README.md

@@ -1,3 +1,5 @@
+<div align="center">
+
 # AgentsMesh
 
 [![CI](https://github.com/sampleXbro/agentsmesh/actions/workflows/ci.yml/badge.svg)](https://github.com/sampleXbro/agentsmesh/actions/workflows/ci.yml)
@@ -10,8 +12,11 @@
 [![Docs](https://img.shields.io/badge/docs-website-brightgreen.svg)](https://samplexbro.github.io/agentsmesh)
 [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](https://github.com/sampleXbro/agentsmesh/pulls)
 
+
 AgentsMesh maintains a single canonical configuration in `.agentsmesh/` and syncs it bidirectionally to Claude Code, Cursor, Copilot, Continue, Junie, Kiro, Gemini CLI, Cline, Codex CLI, Windsurf, Antigravity, and Roo Code. Rules, commands, agents, skills, MCP servers, hooks, ignore patterns, and permissions -- all from one source of truth.
 
+</div>
+
 > **Full documentation: [samplexbro.github.io/agentsmesh](https://samplexbro.github.io/agentsmesh)**
 
 ---
@@ -72,24 +77,87 @@ agentsmesh import --from cursor
 agentsmesh generate
 ```
 
+### Personal global config (user home)
+
+```bash
+# Initialize canonical home config
+agentsmesh init --global
+
+# Import a user-level tool setup into ~/.agentsmesh/
+agentsmesh import --global --from claude-code
+agentsmesh import --global --from antigravity
+agentsmesh import --global --from codex-cli
+agentsmesh import --global --from cursor
+
+# Install shared packs into ~/.agentsmesh/
+agentsmesh install --global github:org/shared-rules
+
+# Work against home-level canonical config
+agentsmesh diff --global
+agentsmesh lint --global
+agentsmesh watch --global
+agentsmesh check --global
+agentsmesh merge --global
+agentsmesh matrix --global
+agentsmesh generate --global
+```
+
+Global mode uses `~/.agentsmesh/` as the canonical source of truth instead of a project-local `.agentsmesh/`. **All** built-in targets support `--global`; `agentsmesh generate --global` writes user-level outputs for whichever targets are enabled in `agentsmesh.yaml`. Typical paths include:
+
+- **Claude Code** — `~/.claude/CLAUDE.md` (with `# Global Instructions` framing), `~/.claude/settings.json` (permissions), `~/.claude/hooks.json` (hooks), `~/.claude/agents/`, `~/.claude/skills/`, optional mirror to `~/.agents/skills/` when Codex is **not** also a global target (otherwise Codex owns `~/.agents/skills/`), `~/.claude/commands/`, optional `~/.claude/output-styles/` when `outputStyle: true` on an agent or command, `~/.claudeignore`, and `~/.claude.json` for MCP
+- **Cursor** — `~/.cursor/rules/*.mdc`, `~/.cursor/AGENTS.md` (aggregate), `~/.cursor/mcp.json`, `~/.cursor/hooks.json`, `~/.cursorignore`, plus skills, agents, and commands under `~/.cursor/`; legacy `~/.agentsmesh-exports/cursor/user-rules.md` is still read on import when present; `agentsmesh import --global --from cursor` maps those paths back into `~/.agentsmesh/`
+- **Copilot** — `~/.copilot/copilot-instructions.md` (all rules merged, including glob-scoped instructions), `~/.copilot/AGENTS.md` (compat mirror), `~/.copilot/agents/*.agent.md`, `~/.copilot/skills/`, `~/.copilot/prompts/*.prompt.md`, skills mirrored to `~/.agents/skills/` and `~/.claude/skills/` when Codex is **not** also a global target
+- **Continue** — `~/.continue/rules/`, `~/.continue/prompts/`, `~/.continue/skills/`, `~/.continue/mcpServers/agentsmesh.json`, `~/.continue/AGENTS.md` (compat mirror), `~/.continue/config.yaml` (global config)
+- **Junie** — `~/.junie/AGENTS.md` (aggregate), `~/.junie/skills/`, `~/.junie/agents/*.md`, `~/.junie/commands/*.md`, `~/.junie/mcp/mcp.json`, optional mirror to `~/.agents/skills/` when Codex is **not** also a global target
+- **Kiro** — `~/.kiro/steering/AGENTS.md` (aggregate), `~/.kiro/steering/*.md` (per-rule files), `~/.kiro/agents/*.md`, `~/.kiro/skills/`, `~/.kiro/settings/mcp.json`, `~/.kiro/settings/kiroignore`, optional mirror to `~/.agents/skills/` when Codex is **not** also a global target
+- **Gemini CLI** — `~/.gemini/GEMINI.md`, `~/.gemini/AGENTS.md` (compatibility aggregate), `~/.gemini/settings.json` (includes MCP and hooks), `~/.gemini/commands/*.toml`, `~/.gemini/skills/`, `~/.gemini/agents/*.md` (experimental), optional mirror to `~/.agents/skills/` when Codex is **not** also a global target
+- **Cline** — `~/Documents/Cline/Rules/`, `~/Documents/Cline/Workflows/`, `~/Documents/Cline/Hooks/`, `~/.cline/skills/`, `~/.cline/cline_mcp_settings.json`, `~/.clineignore`, optional mirror to `~/.agents/skills/`
+- **Codex CLI** — `~/.codex/AGENTS.md`, `~/.codex/config.toml`, `~/.codex/agents/*.toml`, `~/.codex/rules/*.rules` when rules use execution semantics, and `~/.agents/skills/` for skills
+- **Windsurf** — `~/.codeium/windsurf/memories/global_rules.md`, `~/.codeium/windsurf/skills/`, `~/.codeium/windsurf/global_workflows/`, `~/.codeium/windsurf/hooks.json`, `~/.codeium/windsurf/mcp_config.json`, `~/.codeium/.codeiumignore`, optional mirror to `~/.agents/skills/` when Codex is **not** also a global target
+- **Antigravity** — `~/.gemini/antigravity/GEMINI.md`, `~/.gemini/antigravity/skills/`, `~/.gemini/antigravity/workflows/`, and `~/.gemini/antigravity/mcp_config.json`
+- **Roo Code** — `~/.roo/AGENTS.md` (compatibility aggregate), `~/.roo/rules/*.md`, `~/.roo/commands/*.md`, `~/.roo/skills/`, `~/mcp_settings.json`, `~/.rooignore`, `~/.roo/settings/custom_modes.yaml` (agents → custom modes), optional mirror to `~/.agents/skills/` when Codex is **not** also a global target
+
+See the [supported tools matrix](https://samplexbro.github.io/agentsmesh/reference/supported-tools/#global-mode) for project vs global capability notes per target.
+
 That's it. Your `.agentsmesh/` directory is now the single source of truth, and the generated files for each tool stay in sync with it.
 
 ---
 
 ## Supported Tools
 
-| Feature       | Claude Code | Cursor  | Copilot | Continue | Junie    | Kiro   | Gemini CLI | Cline   | Codex CLI | Windsurf | Antigravity | Roo Code |
-|---------------|:-----------:|:-------:|:-------:|:--------:|:--------:|:------:|:----------:|:-------:|:---------:|:--------:|:-----------:|:--------:|
-| Rules         | Native      | Native  | Native  | Native   | Native   | Native | Native     | Native  | Native    | Native   | Native      | Native   |
-| Commands      | Native      | Native  | Native  | Embedded | Embedded | --     | Native     | Native  | Embedded  | Native   | Partial     | Native   |
-| Agents        | Native      | Native  | Native  | --       | Embedded | --     | Native     | Embedded| Native    | Embedded | --          | --       |
-| Skills        | Native      | Native  | Native  | Embedded | Embedded | Native | Native     | Native  | Native    | Native   | Native      | Native   |
-| MCP Servers   | Native      | Native  | --      | Native   | Native   | Native | Native     | Native  | Native    | Partial  | --          | Native   |
-| Hooks         | Native      | Native  | Partial | --       | --       | Native | Partial    | --      | --        | Native   | --          | --       |
-| Ignore        | Native      | Native  | --      | --       | Native   | Native | Native     | Native  | --        | Native   | --          | Native   |
-| Permissions   | Native      | Partial | --      | --       | --       | --     | Partial    | --      | --        | --       | --          | --       |
-
-See the [full feature matrix docs](https://samplexbro.github.io/agentsmesh/reference/supported-tools/) for details on native vs. embedded support.
+### Project scope (`agentsmesh generate`)
+
+<!-- agentsmesh:support-matrix:project -->
+| Feature | Claude Code | Cursor | Copilot | Continue | Junie | Kiro | Gemini CLI | Cline | Codex CLI | Windsurf | Antigravity | Roo Code |
+|---|:-----------:|:-----------:|:-----------:|:-----------:|:-----------:|:-----------:|:-----------:|:-----------:|:-----------:|:-----------:|:-----------:|:-----------:|
+| Rules | Native | Native | Native | Native | Native | Native | Native | Native | Native | Native | Native | Native |
+| Additional Rules | Native | Embedded | Native | Native | Native | Native | Embedded | Native | Native | Native | Native | Native |
+| Commands | Native | Native | Native | Embedded | Native | — | Native | Native (workflows) | Embedded | Native (workflows) | Partial (workflows) | Native |
+| Agents | Native | Native | Native | — | Native | Native | Native | Embedded | Native | Embedded | — | Partial |
+| Skills | Native | Native | Native | Embedded | Native | Native | Native | Native | Native | Native | Native | Native |
+| MCP Servers | Native | Native | — | Native | Native | Native | Native | Native | Native | Partial | — | Native |
+| Hooks | Native | Native | Partial | — | — | Native | Partial | Native | — | Native | — | — |
+| Ignore | Native | Native | — | — | Native | Native | Native (settings-embedded) | Native | — | Native | — | Native |
+| Permissions | Native | Partial | — | — | — | — | Partial | — | — | — | — | — |
+<!-- /agentsmesh:support-matrix:project -->
+
+### Global scope (`agentsmesh matrix --global`)
+
+<!-- agentsmesh:support-matrix:global -->
+| Feature | Claude Code | Cursor | Copilot | Continue | Junie | Kiro | Gemini CLI | Cline | Codex CLI | Windsurf | Antigravity | Roo Code |
+|---|:-----------:|:-----------:|:-----------:|:-----------:|:-----------:|:-----------:|:-----------:|:-----------:|:-----------:|:-----------:|:-----------:|:-----------:|
+| Rules | Native | Native | Native | Native | Native | Native | Native | Native | Native | Native | Native | Native |
+| Additional Rules | Native | Embedded | Native | Native | Embedded | Native | Embedded | Native | Embedded | Partial | Embedded | Native |
+| Commands | Native | Native | Native | Native | Native | — | Native | Native (workflows) | Embedded | Native (workflows) | Partial (workflows) | Native |
+| Agents | Native | Native | Native | — | Native | Native | Native | Embedded | Native | Embedded | — | Partial |
+| Skills | Native | Native | Native | Native | Native | Native | Native | Native | Native | Native | Native | Native |
+| MCP Servers | Native | Native | — | Native | Native | Native | Native | Native | Native | Partial | Native | Native |
+| Hooks | Native | Native | — | — | — | — | Partial | Native | — | Native | — | — |
+| Ignore | Native | Native | — | — | — | Native | — | Native | — | Native | — | Native |
+| Permissions | Native | — | — | — | — | — | — | — | — | — | — | — |
+<!-- /agentsmesh:support-matrix:global -->
+
+See the [full feature matrix docs](https://samplexbro.github.io/agentsmesh/reference/supported-tools/) for details on native vs. embedded support and global paths.
 
 **Note:** The canonical root rule always lives at `.agentsmesh/rules/_root.md`. Some targets write that content to a tool-specific main file named `general` (for example `.continue/rules/general.md` and `.agents/rules/general.md` for Antigravity) instead of `_root.md` on disk.
 

package/dist/canonical-types-gdrUi3bD.d.ts

@@ -0,0 +1,146 @@
+/** Hook definition */
+interface HookEntry {
+    matcher: string;
+    command: string;
+    timeout?: number;
+    type?: 'command' | 'prompt';
+    prompt?: string;
+}
+interface Hooks {
+    PreToolUse?: HookEntry[];
+    PostToolUse?: HookEntry[];
+    Notification?: HookEntry[];
+    UserPromptSubmit?: HookEntry[];
+    SubagentStart?: HookEntry[];
+    SubagentStop?: HookEntry[];
+    [key: string]: HookEntry[] | undefined;
+}
+
+interface BaseMcpServer {
+    description?: string;
+    type: string;
+    env: Record<string, string>;
+}
+/** Stdio MCP server configuration */
+interface StdioMcpServer extends BaseMcpServer {
+    command: string;
+    args: string[];
+}
+/** URL-based MCP server configuration (HTTP/SSE/streamable HTTP) */
+interface UrlMcpServer extends BaseMcpServer {
+    url: string;
+    headers: Record<string, string>;
+}
+/** MCP server configuration */
+type McpServer = StdioMcpServer | UrlMcpServer;
+interface McpConfig {
+    mcpServers: Record<string, McpServer>;
+}
+
+/** A parsed rule from .agentsmesh/rules/ (glob: *.md) */
+interface CanonicalRule {
+    /** Source file path (for error reporting) */
+    source: string;
+    /** If true, this is the root/always-applied rule */
+    root: boolean;
+    /** Which targets receive this rule. Empty = all */
+    targets: string[];
+    /** Human description for AI context */
+    description: string;
+    /** Glob patterns for file scoping */
+    globs: string[];
+    /** Markdown body content */
+    body: string;
+    /** Activation mode hint for tools that support it (e.g. Windsurf) */
+    trigger?: 'always_on' | 'model_decision' | 'glob' | 'manual';
+    /**
+     * Codex CLI: `advisory` (default) → nested `AGENTS.md` / `AGENTS.override.md`.
+     * `execution` → `.codex/rules/{slug}.rules` body must be Starlark (`prefix_rule`, …).
+     * @see docs/agent-structures/codex-cli-project-level-advanced.md §6.2, §6.10
+     */
+    codexEmit?: 'advisory' | 'execution';
+    /**
+     * Codex nested instruction filename: `override` → `AGENTS.override.md` (advisory only).
+     */
+    codexInstructionVariant?: 'default' | 'override';
+}
+/** A parsed command from .agentsmesh/commands/ (glob: *.md) */
+interface CanonicalCommand {
+    source: string;
+    /** Command name (derived from filename) */
+    name: string;
+    description: string;
+    /** Tool permissions: ["Read", "Grep", "Bash(git diff)"] */
+    allowedTools: string[];
+    /** When true, also emit ~/.claude/output-styles/{name}.md in Claude global mode */
+    outputStyle?: boolean;
+    body: string;
+}
+/** A parsed subagent from .agentsmesh/agents/ (glob: *.md) */
+interface CanonicalAgent {
+    source: string;
+    name: string;
+    description: string;
+    /** Tools this agent can use */
+    tools: string[];
+    /** Tools explicitly denied */
+    disallowedTools: string[];
+    /** AI model preference */
+    model: string;
+    /** Permission mode */
+    permissionMode: string;
+    /** Max conversation turns */
+    maxTurns: number;
+    /** MCP servers available to this agent */
+    mcpServers: string[];
+    /** Hooks specific to this agent */
+    hooks: Hooks;
+    /** Skills available to this agent */
+    skills: string[];
+    /** Memory file path */
+    memory: string;
+    /** System prompt (markdown body) */
+    body: string;
+    /** When true, also emit ~/.claude/output-styles/{name}.md in Claude global mode */
+    outputStyle?: boolean;
+}
+/** Supporting file for a skill */
+interface SkillSupportingFile {
+    relativePath: string;
+    absolutePath: string;
+    /** File content (utf-8) for generation; empty if unreadable */
+    content: string;
+}
+/** A parsed skill from .agentsmesh/skills/{name}/SKILL.md */
+interface CanonicalSkill {
+    source: string;
+    /** Skill name (derived from directory name) */
+    name: string;
+    description: string;
+    /** SKILL.md content */
+    body: string;
+    /** Paths to supporting files (relative to skill dir) */
+    supportingFiles: SkillSupportingFile[];
+}
+/** Permission allow/deny/ask lists */
+interface Permissions {
+    allow: string[];
+    deny: string[];
+    /** Present in parsed YAML; omitted in some legacy fixtures */
+    ask?: string[];
+}
+/** Ignore patterns (gitignore syntax lines) */
+type IgnorePatterns = string[];
+/** All canonical files loaded from .agentsmesh/ */
+interface CanonicalFiles {
+    rules: CanonicalRule[];
+    commands: CanonicalCommand[];
+    agents: CanonicalAgent[];
+    skills: CanonicalSkill[];
+    mcp: McpConfig | null;
+    permissions: Permissions | null;
+    hooks: Hooks | null;
+    ignore: IgnorePatterns;
+}
+
+export type { CanonicalFiles as C, CanonicalRule as a };

package/dist/canonical.d.ts

@@ -0,0 +1,23 @@
+import { C as CanonicalFiles } from './canonical-types-gdrUi3bD.js';
+
+/**
+ * Load all canonical files from a canonical directory into CanonicalFiles.
+ */
+
+/**
+ * Load all canonical files from a canonical directory or project root.
+ * Missing directories/files yield empty arrays or null as per each parser.
+ *
+ * @param canonicalDirOrProjectRoot - Absolute path to canonical directory or project root
+ * @returns CanonicalFiles with all parsed data
+ */
+declare function loadCanonicalFiles(canonicalDirOrProjectRoot: string): Promise<CanonicalFiles>;
+
+/**
+ * Public API — canonical loading (package.json "exports"."./canonical").
+ */
+
+/** Load `.agentsmesh/` from a project root (or an explicit canonical directory). */
+declare function loadCanonical(projectRoot: string): Promise<CanonicalFiles>;
+
+export { loadCanonical, loadCanonicalFiles };