{
  "markdown": "# c3-domain-manager\n\nDomain-driven design analysis for Construct 3 projects. Classifies source files into domains, parses event sheet dependencies, and provides health and boundary validation — all driven by a single `domain-config.json` file.\n\n## What it does\n\n- **File classification** — maps `eventSheets/`, `layouts/`, and `scripts/` files to named domains using directory patterns and per-file overrides\n- **Domain index generation** — writes markdown pages to `extracted/domain-index/` with per-domain file lists, function signatures, and include graphs\n- **Health metrics** — computes coupling (Ca/Ce) and instability scores for each domain\n- **Boundary validation** — detects undeclared cross-domain dependencies and forbidden dependency directions\n- **Glossary collision detection** — flags terms defined differently across domains\n- **Context map** — generates text or Mermaid diagrams of inter-domain relationships\n- **Editor-strictness validation** — reports event sheets the C3 editor would refuse to import (e.g. missing required fields on `variable` or `group` events)\n- **MCP server** — exposes all of the above as Model Context Protocol tools for AI agents\n\n## Requirements\n\n- Node.js >= 22\n- A Construct 3 project with `eventSheets/`, `layouts/`, and `scripts/` directories\n- A `domain-config.json` at the project root (see [wiki/reference/domain-architecture.md](wiki/reference/domain-architecture.md))\n\n## Installation\n\nInstall from npm:\n\n```bash\nnpm install @genvidtech/c3-domain-manager\n```\n\nOr run the CLI without installing:\n\n```bash\nnpx @genvidtech/c3-domain-manager generate\n```\n\n## Quick start\n\n### 1. Create domain-config.json\n\nAt the root of your Construct 3 project:\n\n```json\n{\n  \"domains\": {\n    \"Authentication\": {\n      \"description\": \"Login, device binding, user profile\",\n      \"eventSheetDirs\": [\"Login\", \"Profile\"],\n      \"layoutDirs\": [\"Login\"],\n      \"scriptDirs\": [\"Auth\"]\n    },\n    \"Gameplay\": {\n      \"description\": \"Battle loop, enemies, skills\",\n      \"eventSheetDirs\": [\"Battle\", \"Enemies\"],\n      \"layoutDirs\": [\"Levels\"],\n      \"scriptDirs\": [\"Battle\", \"Skills\"]\n    }\n  },\n  \"sharedSubdomains\": {\n    \"UI Components\": {\n      \"description\": \"Reusable UI widgets used across domains\",\n      \"scriptDirs\": [\"UI\"]\n    }\n  },\n  \"overrides\": {\n    \"eventSheets/Shared/ChatEvents.json\": \"Watch Content\"\n  }\n}\n```\n\n### 2. Generate the domain index\n\nRun from your project root:\n\n```bash\nnpx @genvidtech/c3-domain-manager generate\n```\n\nThis writes markdown pages to `extracted/domain-index/`.\n\n### 3. Check coverage\n\n```bash\nnpx @genvidtech/c3-domain-manager list-uncategorized\n```\n\nLists files not covered by any domain mapping.\n\n## CLI reference\n\nRun any subcommand with `--help` for full usage.\n\n| Subcommand | Description |\n|------------|-------------|\n| `generate` | Generate domain index at `extracted/domain-index/` |\n| `list-uncategorized` | List files/directories not mapped to any domain — the worklist for `generate`'s output |\n| `list-stale-overrides` | List override entries pointing to non-existent files, plus inert entries no enumeration can ever produce |\n| `validate-editor` | Report event sheets the C3 editor would reject (editor-strictness validation) |\n| `addon-inventory` | Report project-wide addon usage: declared-but-unused and used-but-undeclared addons |\n| `server` | Start the MCP server (stdio transport) |\n\nAll subcommands share three global options:\n\n| Option | Default | Description |\n|--------|---------|-------------|\n| `--project-dir <path>` | auto-detected | C3 project source root (`eventSheets/`, `layouts/`, `scripts/`). Auto-detected from a `project.c3proj` marker in the current dir or an immediate child; also honoured via the `C3_PROJECT_DIR` env var. Relative paths resolve from the current directory. |\n| `--config <path>` | `<project-root>/domain-config.json` | Path to `domain-config.json`. Relative paths resolve from the project root. |\n| `--extracted <path>` | `<project-root>/extracted` | Output directory for the generated domain index. Pass `none` for an ephemeral temp dir auto-cleaned on exit. |\n\n`server` additionally accepts a repeatable option, not shared by the other five subcommands:\n\n| Option | Default | Description |\n|--------|---------|-------------|\n| `--project <id>=<path>` | none (falls back to `--project-dir`/discovery) | Register a project for this server invocation, as `<id>=<path>` (explicit id) or a bare path (id derived from the basename). Repeatable — pass it once per project to host several C3 projects in one server. When one or more are given, they define the registry entirely and `--project-dir`/`C3_PROJECT_DIR`/`project.c3proj` discovery do not apply. With more than one `--project`, `--config`/`--extracted` must be relative (rebased per project) or omitted. |\n\nWith neither `--project` nor `--project-dir`, `server` registers **every** discovered `project.c3proj` root instead of erroring on ambiguity — the five non-`server` subcommands still error when discovery finds two or more roots. See [wiki/reference/domain-architecture.md](wiki/reference/domain-architecture.md#paths-and-locations) for the full `--project-dir` resolution precedence (flag > `C3_PROJECT_DIR` > `project.c3proj` discovery > cwd).\n\n## MCP server\n\nThe MCP server exposes 15 tools over stdio, suitable for use with Claude or any MCP-compatible client. It can host more than one Construct 3 project in a single server process (see `--project` above) — every tool below except `list-projects` accepts an optional `project` selector naming which registered project to target; omitted, it resolves to the sole registered project when exactly one is registered, and returns an error listing the known ids when more than one is.\n\n### Starting the server\n\n```bash\nnpx @genvidtech/c3-domain-manager server\n```\n\nOr in an MCP client config (e.g. Claude Desktop `claude_desktop_config.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"c3-domain-manager\": {\n      \"command\": \"npx\",\n      \"args\": [\"@genvidtech/c3-domain-manager\", \"server\"],\n      \"cwd\": \"/path/to/your/c3-project\"\n    }\n  }\n}\n```\n\nThe server auto-generates the domain index on startup if `extracted/domain-index/` does not exist.\n\n### Available tools\n\n**Read tools** (no side effects)\n\n| Tool | Description |\n|------|-------------|\n| `read-domain-index` | Read the master index or a named domain's detail page. Supports `offset`/`limit` pagination. |\n| `read-domain-config` | Read `domain-config.json` in formatted text. Filter by `section`: `domains`, `sharedSubdomains`, `overrides`, or `all`. |\n| `list-uncategorized` | List files/directories with no domain assignment — the worklist for the generated domain index. |\n| `list-stale-overrides` | List override entries whose files no longer exist on disk, plus inert entries no enumeration can ever produce. |\n| `get-state` | Return current `txId` and `domainDirty` flag. |\n| `glossary-check` | Report glossary terms that are defined differently across domains. |\n| `validate-boundaries` | Report undeclared cross-domain dependencies and forbidden dependency directions. |\n| `domain-health` | Compute Ca, Ce, and instability metrics per domain. |\n| `context-map` | Generate a context map in `text` or `mermaid` format. |\n| `validate-editor` | Report event sheets the C3 editor would reject. Re-walks sheets fresh from disk; never reads the cached domain index. |\n| `addon-inventory` | Report project-wide addon usage: declared-but-unused and used-but-undeclared addons. Derives attribution fresh from disk; never reads the cached domain index. |\n| `list-projects` | List every registered project's id and resolved root. The one tool exempt from the `project` selector — use it to discover which id to pass to every other tool. |\n\n**Mutate tools** (modify `domain-config.json`)\n\n| Tool | Description |\n|------|-------------|\n| `set-overrides` | Add or update file-to-domain override entries. Accepts optional `txId` for optimistic concurrency. |\n| `remove-overrides` | Remove override entries by file path. |\n\n**Regenerate tools**\n\n| Tool | Description |\n|------|-------------|\n| `regenerate` | Re-run the domain index generator and clear the `domainDirty` flag. |\n\n### Stale index warning\n\nIf `domain-config.json` changes while the server is running, mutate tools mark the index as dirty. Read tools that depend on the index append a warning: `[Warning: domain index may be stale — run regenerate to refresh]`. Call `regenerate` to clear it.\n\n### Optimistic concurrency\n\n`set-overrides` and `remove-overrides` accept an optional `txId`. If provided, the write is rejected when the server's current `txId` does not match. Use `get-state` to read the current `txId` before a write sequence. `txId` is a composite `<projectId>:<n>` string (e.g. `game-a:3`), not a bare integer — it carries which registered project the counter belongs to.\n\n## Library API\n\nImport directly in TypeScript:\n\n```typescript\nimport {\n  classifyFile,\n  generateDomainIndex,\n  computeDomainData,\n  listUncategorized,\n  listStaleOverrides,\n  listInertOverrides,\n  validateEditorStrictness,\n  formatEditorStrictnessReport,\n} from \"@genvidtech/c3-domain-manager\";\n```\n\nKey exports from `src/index.ts`:\n\n| Export | Module | Description |\n|--------|--------|-------------|\n| `classifyFile(path, fileType, config)` | `classification` | Classify one file path into a domain name |\n| `generateDomainIndex(root, extracted, configDir, configFileName, log)` → `Promise` | `domainGenerator` | Async I/O entry point — validates config via `DomainConfigSchema`, writes index |\n| `computeDomainData(root, config)` | `domainGenerator` | Pure computation — returns `DomainData[]` without I/O |\n| `listUncategorized(root, config)` | `domainAnalysis` | Return file/directory paths not covered by the config — shares its `scripts/` enumeration with the generator (see next row) |\n| `findScriptEntries(scriptsDir, config?)` | `domainGenerator` | Enumerate `scripts/` entries (files and collapsed directories) — consumed by both `computeDomainData` and `listUncategorized` |\n| `listStaleOverrides(root, config)` | `domainAnalysis` | Return override keys whose files are missing |\n| `listInertOverrides(root, config)` | `domainAnalysis` | Return override keys whose files exist but no enumeration this tool performs can ever produce |\n| `collectGlossary(config)` | `glossary` | Collect all glossary entries across domains |\n| `findCollisions(entries)` | `glossary` | Find terms with conflicting definitions |\n| `validateBoundaries(domains, config, filter?)` | `relationships` | Check declared vs observed dependencies |\n| `computeHealth(domain)` | `health` | Ca, Ce, instability for one `DomainData` |\n| `generateContextMap(domains, config, opts)` | `contextMap` | Produce text or Mermaid context map |\n| `validateEditorStrictness(root, config, log?)` | `editorValidation` | Walk event sheets and return issues grouped by sheet |\n| `formatEditorStrictnessReport(report)` | `editorValidation` | Render an `EditorStrictnessReport` to text |\n\nType definitions are in `src/domain/types.ts`: `DomainConfig`, `DomainDefinition`, `SharedSubdomainDefinition`, `DomainData`, `Relationship`, `FunctionDef`. Editor-validation types (`EditorStrictnessReport`, `EditorStrictnessSheetReport`) are in `src/domain/editorValidation.ts`.\n\n## Further reading\n\n- [wiki/reference/domain-architecture.md](wiki/reference/domain-architecture.md) — domain model concepts, configuration schema, classification rules\n",
  "bytes": 11440,
  "sha": "69cb3fde5d445ba2af18aa37b94e4b8bd48c8e4036c7c9dad9bfb5d35d1c0dcf",
  "repo_slug": "genvidtechnologies/c3-domain-manager",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/okf_genvidtechnologies_c3_domain_manager_wik_d3b4b678/readme"
}