agentsmesh 0.7.0 → 0.8.0

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## 0.8.0
+
+### Minor Changes
+
+- b3f702d: Adds three new `agentsmesh lint` diagnostics, a recommended `.gitignore` policy for materialized packs, and a one-step `agentsmesh target-scaffold` workflow.
+
+  Added:
+  - New lint diagnostics: `silent-drop-guard` flags canonical content a target would otherwise drop without trace, `hook-script-references` reports hook commands pointing at missing wrapper scripts, and `rule-scope-inversion` catches manual-activation rules whose scope contradicts the target's projection rules. They are wired into `runLint` for every target via descriptor capabilities, so existing configs may surface new warnings; no rule has been removed.
+  - `agentsmesh init` now writes `.agentsmesh/packs/` into `.gitignore` alongside `agentsmesh.local.yaml`, `.agentsmeshcache`, and `.agentsmesh/.lock.tmp`. Materialized packs are treated like `node_modules` — `installs.yaml` is committed and `agentsmesh install --sync` reproduces the tree deterministically post-clone.
+  - `agentsmesh target-scaffold` post-steps collapse the previous three-edit sequence into one `pnpm catalog:generate` invocation, backed by a new auto-discovered builtin-target catalog (`scripts/generate-target-catalog.ts` + `pnpm catalog:verify` drift guard in CI).
+
+  Changed:
+  - The `agentsmesh.json` and `pack.json` schemas now list `targets` enums alphabetically. Schema consumers that pin order will see a one-time diff; values are unchanged.
+  - README documents the commit-vs-gitignore convention for generated tool folders and clarifies native Windows support (no WSL).
+
+  Internal:
+  - Per-target importers (`antigravity`, `claude-code`, `continue`, `copilot`, `cursor`, `gemini-cli`, `junie`, `kiro`, `roo-code`) migrated to the descriptor-driven import runner with mapper functions extracted into `import-mappers.ts` to keep `index.ts` ↔ `importer.ts` cycles out of the TDZ.
+  - New shared link-format registry (`src/core/reference/link-format-registry.ts`) consolidates per-target link rendering rules.
+
 ## 0.7.0
 
 ### Minor Changes

package/README.md

@@ -1,6 +1,6 @@
 <div align="center">
 
-# AgentsMesh — One AI Coding Config for Every Tool
+# AgentsMesh — AI Coding Config Sync for Every Tool
 
 [![CI](https://github.com/sampleXbro/agentsmesh/actions/workflows/ci.yml/badge.svg)](https://github.com/sampleXbro/agentsmesh/actions/workflows/ci.yml)
 [![npm version](https://img.shields.io/npm/v/agentsmesh.svg)](https://www.npmjs.com/package/agentsmesh)
@@ -12,11 +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)
 
-**One canonical `.agentsmesh/` directory replaces scattered rules, prompts, agents, skills, MCP servers, hooks, ignore files, and permissions across every major AI coding tool.**
+**AgentsMesh is an open-source CLI and TypeScript library for AI coding configuration sync. One canonical `.agentsmesh/` directory manages rules, prompts, commands, agents, skills, MCP servers, hooks, ignore files, and permissions across every major AI coding tool.**
 
-Edit once — generate `CLAUDE.md`, `AGENTS.md`, `.cursor/rules`, `.github/copilot-instructions.md`, `.gemini/settings.json`, `.windsurf/rules`, `.codex/config.toml`, `.kiro/steering`, and more from the same source. Bidirectional import so you can adopt it on existing projects with one command.
+Edit once and generate `CLAUDE.md`, `AGENTS.md`, `.cursor/rules`, `.github/copilot-instructions.md`, `.gemini/settings.json`, `.windsurf/rules`, `.codex/config.toml`, `.kiro/steering`, and more from the same source. Import existing Claude Code, Cursor, Copilot, Gemini CLI, Windsurf, Codex CLI, and other configs back into canonical form without losing round-trip metadata.
 
-**Works with** Claude Code · Cursor · GitHub Copilot · Gemini CLI · Windsurf · Continue · Cline · Kiro · Codex CLI · Junie · Roo Code · Antigravity — and new tools as the ecosystem grows. See the [full feature matrix](https://samplexbro.github.io/agentsmesh/reference/supported-tools/).
+**Works with** Claude Code · Cursor · GitHub Copilot · Gemini CLI · Windsurf · Continue · Cline · Kiro · Codex CLI · Junie · Roo Code · Antigravity — plus plugin targets. See the [full feature matrix](https://samplexbro.github.io/agentsmesh/reference/supported-tools/).
 
 </div>
 
@@ -24,21 +24,20 @@ Edit once — generate `CLAUDE.md`, `AGENTS.md`, `.cursor/rules`, `.github/copil
 
 ---
 
-## Why AgentsMesh
+## Why developers use AgentsMesh
 
-- **One source of truth** — edit `.agentsmesh/`, generate everywhere. No more copy-pasting rules between tool directories.
-- **Bidirectional sync** — import existing configs into canonical form and generate back out. Lossless round-trip, no manual reformatting.
-- **Project + Global modes** — sync team config via project-local `.agentsmesh/` *and* personal config via user-level `~/.agentsmesh/`.
-- **Plugin system** — add support for any AI coding tool via an npm package. No fork, no core PR.
-- **Team-safe collaboration** — lock files track generated state, `check` catches drift in CI, `merge` resolves conflicts after `git merge`.
-- **Community packs** — install shared skills, rules, agents, and commands from GitHub / GitLab / git URLs.
-- **Growing tool coverage** — new AI coding tools are added as the ecosystem evolves. See the [matrix](https://samplexbro.github.io/agentsmesh/reference/supported-tools/).
+- **Unify AI coding rules** across Claude Code, Cursor, Copilot, Gemini CLI, Windsurf, Codex CLI, and mixed-tool teams.
+- **Adopt existing projects safely** with bidirectional `import` and `generate` instead of rewriting every tool config by hand.
+- **Sync personal global config** from `~/.agentsmesh/` to user-level assistant folders such as `~/.claude/`, `~/.cursor/`, and `~/.codex/`.
+- **Standardize MCP, hooks, permissions, skills, and agents** where tools support them natively, with metadata-backed projections where they do not.
+- **Catch config drift in CI** with lock-file checks, diffs, linting, and merge recovery built for team workflows.
+- **Share and extend configuration** with community packs, remote `extends`, runtime plugins, and a typed programmatic API.
 
 ---
 
 ## Install
 
-Requires **Node.js 20+**. Supported platforms: **Linux**, **macOS**, and **Windows**.
+Requires **Node.js 20+**. Supported platforms: **Linux**, **macOS**, and **Windows** (native, not WSL).
 
 ```bash
 npm install -D agentsmesh       # or: pnpm add -D / yarn add -D
@@ -47,6 +46,8 @@ npx agentsmesh --help           # run without installing
 
 CLI aliases: `agentsmesh` and `amsh`.
 
+> **Windows notes:** All paths are normalized internally so generated configs and `installs.yaml` are portable across platforms. Watch mode uses polling on Windows because `ReadDirectoryChangesW` can miss just-created files in tmpdirs. CI runs the full test suite on Linux, macOS, and Windows.
+
 ---
 
 ## Quick start
@@ -76,9 +77,9 @@ agentsmesh generate --global          # writes to ~/.claude/, ~/.cursor/, etc.
 
 ---
 
-## Features
+## High-demand features
 
-### One config, every AI coding tool
+### AI coding config sync for every tool
 
 AgentsMesh generates native configuration for every major AI coding assistant. Each tool's files are produced from a single `.agentsmesh/` directory with support for **rules, commands, agents, skills, MCP servers, hooks, ignore patterns, and permissions**:
 
@@ -99,7 +100,11 @@ AgentsMesh generates native configuration for every major AI coding assistant. E
 
 When a tool lacks native support for a feature, AgentsMesh embeds it with round-trip metadata — no data loss on re-import. See the [supported tools matrix](https://samplexbro.github.io/agentsmesh/reference/supported-tools/) for per-tool native vs. embedded breakdown.
 
-### Global mode — personal setup, same workflow
+### Bidirectional import and lossless generate
+
+Use `agentsmesh import --from <tool>` to migrate existing AI tool configs into canonical `.agentsmesh/` files, then `agentsmesh generate` to project them back out. Managed embedding, reference rewriting, and lock metadata preserve projected features so commands, agents, and skills can round-trip even when a target stores them differently.
+
+### Global mode for personal AI assistant config
 
 `.agentsmesh/` at the project level is for teams. `~/.agentsmesh/` at the home level is for personal setup across every repo you touch:
 
@@ -111,7 +116,7 @@ agentsmesh generate --global   # writes ~/.claude/CLAUDE.md, ~/.cursor/, ~/.code
 
 Every built-in target and every plugin supports global mode. Every CLI command (`diff`, `lint`, `watch`, `check`, `merge`, `matrix`) accepts `--global`. [Global mode paths per tool →](https://samplexbro.github.io/agentsmesh/reference/supported-tools/#global-mode)
 
-### Plugins — add any AI tool
+### Plugins for new AI coding tools
 
 Ship new target support as a standalone npm package — no fork, no core PR:
 
@@ -127,10 +132,12 @@ Plugins have full parity with built-in targets: project + global layouts, featur
 
 - **`agentsmesh check`** — CI gate that exits 1 if generated files drifted from the lock
 - **`agentsmesh diff`** — preview what the next `generate` would change
+- **`agentsmesh lint`** — validate canonical config against target-specific constraints
+- **`agentsmesh watch`** — regenerate target files on save during local editing
 - **`agentsmesh merge`** — recover from three-way `.lock` conflicts after `git merge`
 - **Collaboration config** — `lock_features` and `strategy` prevent accidental overrides
 
-### Community packs
+### Community packs and shared config
 
 Install shared skills, rules, agents, and commands from any git repo:
 
@@ -142,13 +149,45 @@ agentsmesh install --sync       # restore all packs after clone
 
 Packs live in `.agentsmesh/packs/`, track in `installs.yaml`, and merge into canonical config on every `generate`.
 
+### What to commit and what to gitignore
+
+`agentsmesh init` writes a `.gitignore` that follows the recommended convention. The defaults are deliberate:
+
+| Path | In git? | Why |
+|---|---|---|
+| `.agentsmesh/` (canonical) | **commit** | The source of truth — must be in git. |
+| `.agentsmesh/.lock` | **commit** | Drift detection contract. `agentsmesh check` compares against this. |
+| `.agentsmesh/packs/` | **gitignore** | Materialized from `installs.yaml`. Same model as `node_modules` — `agentsmesh install --sync` reproduces them deterministically post-clone. |
+| `agentsmesh.local.yaml` | **gitignore** | Per-developer overrides. |
+| `.agentsmesh/.lock.tmp` | **gitignore** | Transient. |
+| `.agentsmeshcache` | **gitignore** | Remote-extends cache. |
+| Generated tool folders (`.claude/`, `.cursor/`, `.github/`, `.gemini/`, `CLAUDE.md`, `AGENTS.md`, etc.) | **commit** | AI tools read these at runtime. Committing means a fresh clone has working AI configs without a build step. `agentsmesh check` in CI catches drift between canonical and generated. |
+
+Why generated configs stay committed: the same reason `package-lock.json` does. They're deterministic build output that downstream consumers (in this case, the AI tool itself) read directly. Gitignoring them breaks fresh-clone UX and makes `agentsmesh check` meaningless. PR reviewers also benefit from seeing the projected diff in the format Claude/Cursor/Copilot will actually consume.
+
+If your team has a strong reason to gitignore generated configs (e.g., monorepo size concerns, regenerate-on-checkout hooks), add the target-specific entries manually — but expect to wire `agentsmesh generate` into your post-checkout flow.
+
 ### Extending AgentsMesh
 
-- **`agentsmesh target scaffold foo-ide`** — generate a built-in target skeleton (10 files, ready to contribute upstream) with global mode, conversion support, and lint hooks pre-wired
-- **`agentsmesh plugin add <pkg>`** — load third-party npm packages as runtime targets with full built-in parity
+- **`agentsmesh target scaffold foo-ide`** — generate a built-in target skeleton (10 files: descriptor, generators, importer, linter, tests, fixtures) with global mode, conversion support, and lint hooks pre-wired. The catalog is auto-discovered at build time (`pnpm catalog:generate`) — no manual edits to `target-ids.ts`, `builtin-targets.ts`, or the import-map barrel.
+- **`agentsmesh plugin add <pkg>`** — load third-party npm packages as runtime targets with full built-in parity. Supports `agentsmesh plugin list`, `info`, and `remove`.
 
 [Extending guide →](https://samplexbro.github.io/agentsmesh/guides/extending/) · [Building plugins →](https://samplexbro.github.io/agentsmesh/guides/building-plugins/)
 
+### Schema-validated configs (IDE autocomplete)
+
+Every config file ships with a generated JSON Schema, so VS Code, JetBrains, and other editors give you autocomplete and validation out of the box:
+
+| Config file | JSON Schema |
+|---|---|
+| `agentsmesh.yaml` / `.local.yaml` | `node_modules/agentsmesh/schemas/agentsmesh.json` |
+| `.agentsmesh/hooks.yaml` | `schemas/hooks.json` |
+| `.agentsmesh/permissions.yaml` | `schemas/permissions.json` |
+| `.agentsmesh/mcp.json` | `schemas/mcp.json` |
+| `.agentsmesh/packs/*/pack.json` | `schemas/pack.json` |
+
+`agentsmesh init` writes the appropriate `# yaml-language-server: $schema=...` directive (or `$schema` field for JSON) into each canonical file, so editors pick up validation immediately.
+
 ---
 
 ## Supported tools — feature matrix
@@ -156,33 +195,33 @@ Packs live in `.agentsmesh/packs/`, track in `installs.yaml`, and merge into can
 ### 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 |
+| Feature | Antigravity | Claude Code | Cline | Codex CLI | Continue | Copilot | Cursor | Gemini CLI | Junie | Kiro | Roo Code | Windsurf |
 |---|:-----------:|:-----------:|:-----------:|:-----------:|:-----------:|:-----------:|:-----------:|:-----------:|:-----------:|:-----------:|:-----------:|:-----------:|
 | 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 | — | — | — | — | — |
+| Additional Rules | Native | Native | Native | Native | Native | Native | Embedded | Embedded | Native | Native | Native | Native |
+| Commands | Partial (workflows) | Native | Native (workflows) | Embedded | Embedded | Native | Native | Native | Native | — | Native | Native (workflows) |
+| Agents | — | Native | Embedded | Native | — | Native | Native | Native | Native | Native | Partial | Embedded |
+| Skills | Native | Native | Native | Native | Embedded | Native | Native | Native | Native | Native | Native | Native |
+| MCP Servers | — | Native | Native | Native | Native | — | Native | Native | Native | Native | Native | Partial |
+| Hooks | — | Native | Native | — | — | Partial | Native | Partial | — | Native | — | Native |
+| Ignore | — | Native | Native | — | — | — | Native | Native (settings-embedded) | Native | Native | Native | Native |
+| Permissions | — | Native | — | — | — | — | Partial | Partial | — | — | — | — |
 <!-- /agentsmesh:support-matrix:project -->
 
 ### Global scope (`agentsmesh generate --global`)
 
 <!-- agentsmesh:support-matrix:global -->
-| Feature | Claude Code | Cursor | Copilot | Continue | Junie | Kiro | Gemini CLI | Cline | Codex CLI | Windsurf | Antigravity | Roo Code |
+| Feature | Antigravity | Claude Code | Cline | Codex CLI | Continue | Copilot | Cursor | Gemini CLI | Junie | Kiro | Roo Code | Windsurf |
 |---|:-----------:|:-----------:|:-----------:|:-----------:|:-----------:|:-----------:|:-----------:|:-----------:|:-----------:|:-----------:|:-----------:|:-----------:|
 | 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 |
+| Additional Rules | Embedded | Native | Native | Embedded | Native | Native | Embedded | Embedded | Embedded | Native | Native | Partial |
+| Commands | Partial (workflows) | Native | Native (workflows) | Embedded | Native | Native | Native | Native | Native | — | Native | Native (workflows) |
+| Agents | — | Native | Embedded | Native | — | Native | Native | Native | Native | Native | Partial | Embedded |
 | 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 | — | — | — | — | — | — | — | — | — | — | — |
+| MCP Servers | Native | Native | Native | Native | Native | — | Native | Native | Native | Native | Native | Partial |
+| Hooks | — | Native | Native | — | — | — | Native | Partial | — | — | — | 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 native vs. embedded support details and per-tool global paths.
@@ -193,6 +232,8 @@ See the [full feature matrix docs](https://samplexbro.github.io/agentsmesh/refer
 
 AgentsMesh is also importable as a typed ESM library, so you can drive every CLI capability — `generate`, `import`, `lint`, `diff`, `check` — from scripts, IDE extensions, MCP servers, or CI without spawning the CLI. Public entrypoints: `agentsmesh` (full surface), `agentsmesh/engine`, `agentsmesh/canonical`, `agentsmesh/targets`.
 
+`loadProjectContext()` mirrors what the CLI does on startup: resolves config, applies local overrides, loads plugins, materializes `extends` and installed packs, and reads the canonical directory. The result is a single context value you can pass to `generate`, `lint`, or `diff` — the same surface the CLI uses.
+
 ```ts
 import {
   loadProjectContext,
@@ -241,7 +282,7 @@ import { loadCanonical, loadCanonicalFiles } from 'agentsmesh/canonical';
 import { getAllDescriptors } from 'agentsmesh/targets';
 ```
 
-Every public symbol resolves to a real `.d.ts` under strict TypeScript. Full reference at [agentsmesh.dev/reference/programmatic-api](https://samplexbro.github.io/agentsmesh/reference/programmatic-api/) — entrypoint table, every function signature, the typed error taxonomy, and the canonical/target type lists. ESM-only; requires Node.js 20+.
+Every public symbol resolves to a real `.d.ts` under strict TypeScript. Full reference in the [programmatic API docs](https://samplexbro.github.io/agentsmesh/reference/programmatic-api/) — entrypoint table, every function signature, the typed error taxonomy, and the canonical/target type lists. ESM-only; requires Node.js 20+.
 
 ---
 

package/dist/canonical.d.ts

@@ -1,5 +1,5 @@
-import { b as CanonicalFiles, V as ValidatedConfig } from './schema-B7ZSqkrS.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-B7ZSqkrS.js';
+import { b as CanonicalFiles, V as ValidatedConfig } from './schema-BeGiBqbB.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-BeGiBqbB.js';
 import 'zod';
 
 /**