@contentrain/mcp 1.3.0 → 1.5.0

package/testing/conformance/01-new-collection-entry/expected/.contentrain/models/blog.json

@@ -0,0 +1,16 @@
+{
+  "domain": "blog",
+  "fields": {
+    "body": {
+      "type": "text"
+    },
+    "title": {
+      "required": true,
+      "type": "string"
+    }
+  },
+  "i18n": true,
+  "id": "blog",
+  "kind": "collection",
+  "name": "Blog"
+}

package/testing/conformance/01-new-collection-entry/scenario.json

@@ -0,0 +1,19 @@
+{
+  "context_tool": "contentrain_content_save",
+  "description": "Save a new collection entry for a model",
+  "id": "01-new-collection-entry",
+  "input": {
+    "entries": [
+      {
+        "data": {
+          "body": "First post content",
+          "title": "Hello World"
+        },
+        "id": "abc123def456",
+        "locale": "en"
+      }
+    ],
+    "model": "blog"
+  },
+  "operation": "save_content"
+}

package/testing/conformance/01-new-collection-entry/setup/.contentrain/config.json

@@ -0,0 +1,15 @@
+{
+  "domains": [
+    "blog"
+  ],
+  "locales": {
+    "default": "en",
+    "supported": [
+      "en",
+      "tr"
+    ]
+  },
+  "stack": "vue-nuxt",
+  "version": 1,
+  "workflow": "auto-merge"
+}

package/testing/conformance/01-new-collection-entry/setup/.contentrain/models/blog.json

@@ -0,0 +1,16 @@
+{
+  "domain": "blog",
+  "fields": {
+    "body": {
+      "type": "text"
+    },
+    "title": {
+      "required": true,
+      "type": "string"
+    }
+  },
+  "i18n": true,
+  "id": "blog",
+  "kind": "collection",
+  "name": "Blog"
+}

package/testing/conformance/02-new-singleton/expected/.contentrain/config.json

@@ -0,0 +1,15 @@
+{
+  "domains": [
+    "marketing"
+  ],
+  "locales": {
+    "default": "en",
+    "supported": [
+      "en",
+      "tr"
+    ]
+  },
+  "stack": "vue-nuxt",
+  "version": 1,
+  "workflow": "auto-merge"
+}

package/testing/conformance/02-new-singleton/expected/.contentrain/content/marketing/hero/en.json

@@ -0,0 +1,4 @@
+{
+  "subtitle": "Build the web with AI agents",
+  "title": "Welcome to Contentrain"
+}

package/testing/conformance/02-new-singleton/expected/.contentrain/context.json

@@ -0,0 +1,22 @@
+{
+  "lastOperation": {
+    "entries": [
+      "en"
+    ],
+    "locale": "en",
+    "model": "hero",
+    "source": "mcp-local",
+    "timestamp": "2026-01-01T00:00:00.000Z",
+    "tool": "contentrain_content_save"
+  },
+  "stats": {
+    "entries": 1,
+    "lastSync": "2026-01-01T00:00:00.000Z",
+    "locales": [
+      "en",
+      "tr"
+    ],
+    "models": 1
+  },
+  "version": "1"
+}

package/testing/conformance/02-new-singleton/expected/.contentrain/meta/hero/en.json

@@ -0,0 +1,5 @@
+{
+  "source": "agent",
+  "status": "draft",
+  "updated_by": "contentrain-mcp"
+}

package/testing/conformance/02-new-singleton/expected/.contentrain/models/hero.json

@@ -0,0 +1,16 @@
+{
+  "domain": "marketing",
+  "fields": {
+    "subtitle": {
+      "type": "text"
+    },
+    "title": {
+      "required": true,
+      "type": "string"
+    }
+  },
+  "i18n": true,
+  "id": "hero",
+  "kind": "singleton",
+  "name": "Hero"
+}

package/testing/conformance/02-new-singleton/scenario.json

@@ -0,0 +1,18 @@
+{
+  "context_tool": "contentrain_content_save",
+  "description": "Save a new singleton content block",
+  "id": "02-new-singleton",
+  "input": {
+    "entries": [
+      {
+        "data": {
+          "subtitle": "Build the web with AI agents",
+          "title": "Welcome to Contentrain"
+        },
+        "locale": "en"
+      }
+    ],
+    "model": "hero"
+  },
+  "operation": "save_content"
+}

package/testing/conformance/02-new-singleton/setup/.contentrain/config.json

@@ -0,0 +1,15 @@
+{
+  "domains": [
+    "marketing"
+  ],
+  "locales": {
+    "default": "en",
+    "supported": [
+      "en",
+      "tr"
+    ]
+  },
+  "stack": "vue-nuxt",
+  "version": 1,
+  "workflow": "auto-merge"
+}

package/testing/conformance/02-new-singleton/setup/.contentrain/models/hero.json

@@ -0,0 +1,16 @@
+{
+  "domain": "marketing",
+  "fields": {
+    "subtitle": {
+      "type": "text"
+    },
+    "title": {
+      "required": true,
+      "type": "string"
+    }
+  },
+  "i18n": true,
+  "id": "hero",
+  "kind": "singleton",
+  "name": "Hero"
+}

package/testing/conformance/03-new-dictionary/expected/.contentrain/config.json

@@ -0,0 +1,15 @@
+{
+  "domains": [
+    "marketing"
+  ],
+  "locales": {
+    "default": "en",
+    "supported": [
+      "en",
+      "tr"
+    ]
+  },
+  "stack": "vue-nuxt",
+  "version": 1,
+  "workflow": "auto-merge"
+}

package/testing/conformance/03-new-dictionary/expected/.contentrain/content/marketing/ui-strings/en.json

@@ -0,0 +1,5 @@
+{
+  "hero.cta": "Get started",
+  "hero.subtitle": "Build the web with AI agents",
+  "hero.title": "Welcome to Contentrain"
+}

package/testing/conformance/03-new-dictionary/expected/.contentrain/context.json

@@ -0,0 +1,22 @@
+{
+  "lastOperation": {
+    "entries": [
+      "en"
+    ],
+    "locale": "en",
+    "model": "ui-strings",
+    "source": "mcp-local",
+    "timestamp": "2026-01-01T00:00:00.000Z",
+    "tool": "contentrain_content_save"
+  },
+  "stats": {
+    "entries": 1,
+    "lastSync": "2026-01-01T00:00:00.000Z",
+    "locales": [
+      "en",
+      "tr"
+    ],
+    "models": 1
+  },
+  "version": "1"
+}

package/testing/conformance/03-new-dictionary/expected/.contentrain/meta/ui-strings/en.json

@@ -0,0 +1,5 @@
+{
+  "source": "agent",
+  "status": "draft",
+  "updated_by": "contentrain-mcp"
+}

package/testing/conformance/03-new-dictionary/expected/.contentrain/models/ui-strings.json

@@ -0,0 +1,7 @@
+{
+  "domain": "marketing",
+  "i18n": true,
+  "id": "ui-strings",
+  "kind": "dictionary",
+  "name": "UI Strings"
+}

package/testing/conformance/03-new-dictionary/scenario.json

@@ -0,0 +1,19 @@
+{
+  "context_tool": "contentrain_content_save",
+  "description": "Create a dictionary with multiple string keys",
+  "id": "03-new-dictionary",
+  "input": {
+    "entries": [
+      {
+        "data": {
+          "hero.cta": "Get started",
+          "hero.subtitle": "Build the web with AI agents",
+          "hero.title": "Welcome to Contentrain"
+        },
+        "locale": "en"
+      }
+    ],
+    "model": "ui-strings"
+  },
+  "operation": "save_content"
+}

package/testing/conformance/03-new-dictionary/setup/.contentrain/config.json

@@ -0,0 +1,15 @@
+{
+  "domains": [
+    "marketing"
+  ],
+  "locales": {
+    "default": "en",
+    "supported": [
+      "en",
+      "tr"
+    ]
+  },
+  "stack": "vue-nuxt",
+  "version": 1,
+  "workflow": "auto-merge"
+}

package/testing/conformance/03-new-dictionary/setup/.contentrain/models/ui-strings.json

@@ -0,0 +1,7 @@
+{
+  "domain": "marketing",
+  "i18n": true,
+  "id": "ui-strings",
+  "kind": "dictionary",
+  "name": "UI Strings"
+}

package/testing/conformance/README.md

@@ -0,0 +1,77 @@
+# Conformance Fixtures
+
+Byte-identical conformance test suite for content operations. Each fixture describes an operation and its expected on-disk file tree after execution. Used by `packages/mcp/tests/conformance.test.ts`.
+
+**Purpose** — guarantee byte-level parity between providers (LocalProvider today; GitHubProvider + GitLabProvider in later phases) for the same operation. Any silent drift in serialization, meta generation, context.json, or path resolution shows up as a failed fixture.
+
+## Directory layout
+
+```
+conformance/
+├── README.md             — this file
+├── scenarios.json        — human-readable index
+├── 01-new-collection-entry/
+│   ├── scenario.json     — input spec
+│   ├── setup/            — files copied into temp projectRoot before op runs (optional)
+│   └── expected/         — byte-identical file tree after op (GENERATED, committed)
+├── 02-new-singleton/
+│   └── ...
+└── 03-new-dictionary/
+    └── ...
+```
+
+## Scenario schema
+
+```jsonc
+{
+  "id": "01-new-collection-entry",
+  "description": "Save a new collection entry",
+  "operation": "save_content",     // save_content | save_model | delete_content
+  "context_tool": "contentrain_content_save",  // tool name recorded in context.json (optional)
+  "input": {                         // operation-specific params
+    "model": "blog",
+    "entries": [
+      { "id": "...", "locale": "en", "data": { ... } }
+    ]
+  }
+}
+```
+
+## Determinism rules
+
+The harness fixes non-deterministic sources so output is reproducible:
+
+- `Date.now()` / `new Date()` returns `2026-01-01T00:00:00.000Z` (vitest fake timers)
+- `CONTENTRAIN_SOURCE=mcp-local` env var is set
+- `Math.random()` is NOT stubbed globally — scenarios that need determinism must pass explicit entry IDs instead of relying on `generateEntryId()`
+- Git is not initialized — core write functions don't require it
+
+## Regenerating `expected/`
+
+When an intentional behavior change lands (e.g., schema bump, new default field), regenerate the expected fixtures and review the diff:
+
+```bash
+GENERATE_FIXTURES=1 pnpm --filter @contentrain/mcp test -- conformance
+```
+
+Then `git diff` the `expected/` directories. Each byte difference must be a conscious decision.
+
+## Adding a new fixture
+
+1. `mkdir NN-short-name/setup/.contentrain`
+2. Write `scenario.json` at the fixture root
+3. Optionally add setup files under `setup/`
+4. `GENERATE_FIXTURES=1 pnpm --filter @contentrain/mcp test -- conformance` to populate `expected/`
+5. Review generated `expected/` files manually — they become the contract
+6. Commit both `setup/` and `expected/`
+
+## Provider matrix (future)
+
+Today the harness runs scenarios against the current MCP write path (direct fs + `writeContent` + `writeContext`). Post-refactor phases will add:
+
+- Phase 2 — run through plan/apply API, assert `FileChange[]` → same `expected/`
+- Phase 3 — LocalProvider.applyPlan → same `expected/`
+- Phase 5 — GitHubProvider.applyPlan (mocked) → same `expected/`
+- Phase 8 — GitLab/Bitbucket providers → same `expected/`
+
+The fixtures themselves never change between providers. Only the runner wiring does.

package/testing/conformance/scenarios.json

@@ -0,0 +1,36 @@
+{
+  "seeds": [
+    {
+      "id": "01-new-collection-entry",
+      "operation": "save_content",
+      "coverage": "collection kind — new entry, merge semantics, object-map sort"
+    },
+    {
+      "id": "02-new-singleton",
+      "operation": "save_content",
+      "coverage": "singleton kind — new entry, default meta"
+    },
+    {
+      "id": "03-new-dictionary",
+      "operation": "save_content",
+      "coverage": "dictionary kind — multi-key create, flat object format"
+    }
+  ],
+  "planned": [
+    "04-collection-update",
+    "05-singleton-update",
+    "06-dictionary-update",
+    "07-new-document",
+    "08-document-i18n-directory",
+    "09-delete-collection-entry",
+    "10-locale-copy",
+    "11-model-save-new",
+    "12-model-save-update",
+    "13-entry-status-update",
+    "14-delete-entire-locale",
+    "15-relation-validation",
+    "16-unique-field-violation",
+    "17-vocabulary-advisory",
+    "18-init-project-minimal"
+  ]
+}

package/dist/config-BIl5Ybj0.mjs.map

@@ -1 +0,0 @@
-{"version":3,"file":"config-BIl5Ybj0.mjs","names":[],"sources":["../src/core/config.ts"],"sourcesContent":["import type { ContentrainConfig, Vocabulary } from '@contentrain/types'\nimport { join } from 'node:path'\nimport { contentrainDir, readJson } from '../util/fs.js'\nimport type { RepoReader } from './contracts/index.js'\n\nconst CONFIG_PATH = '.contentrain/config.json'\nconst VOCABULARY_PATH = '.contentrain/vocabulary.json'\n\nasync function readJsonViaReader<T>(reader: RepoReader, path: string): Promise<T | null> {\n  try {\n    return JSON.parse(await reader.readFile(path)) as T\n  } catch {\n    return null\n  }\n}\n\nfunction normaliseConfig(raw: Partial<ContentrainConfig> | null): ContentrainConfig | null {\n  if (!raw) return null\n  return {\n    version: raw.version ?? 1,\n    stack: raw.stack ?? 'other',\n    workflow: raw.workflow ?? 'auto-merge',\n    locales: {\n      default: raw.locales?.default ?? 'en',\n      supported: raw.locales?.supported ?? [raw.locales?.default ?? 'en'],\n    },\n    domains: raw.domains ?? [],\n    repository: raw.repository,\n    assets_path: raw.assets_path,\n    branchRetention: raw.branchRetention,\n  }\n}\n\n/**\n * Read `.contentrain/config.json` and normalise it with safe defaults.\n *\n * Accepts either a legacy `projectRoot` string (LocalReader is constructed\n * internally) or any `RepoReader` — tool handlers pass their provider so\n * the same logic resolves against local fs or the GitHub Git Data API.\n */\nexport function readConfig(projectRoot: string): Promise<ContentrainConfig | null>\nexport function readConfig(reader: RepoReader): Promise<ContentrainConfig | null>\nexport async function readConfig(input: string | RepoReader): Promise<ContentrainConfig | null> {\n  if (typeof input === 'string') {\n    const raw = await readJson<Partial<ContentrainConfig>>(join(contentrainDir(input), 'config.json'))\n    return normaliseConfig(raw)\n  }\n  const raw = await readJsonViaReader<Partial<ContentrainConfig>>(input, CONFIG_PATH)\n  return normaliseConfig(raw)\n}\n\n/**\n * Read `.contentrain/vocabulary.json`. Same dual signature as {@link readConfig}.\n */\nexport function readVocabulary(projectRoot: string): Promise<Vocabulary | null>\nexport function readVocabulary(reader: RepoReader): Promise<Vocabulary | null>\nexport async function readVocabulary(input: string | RepoReader): Promise<Vocabulary | null> {\n  if (typeof input === 'string') {\n    return readJson<Vocabulary>(join(contentrainDir(input), 'vocabulary.json'))\n  }\n  return readJsonViaReader<Vocabulary>(input, VOCABULARY_PATH)\n}\n"],"mappings":";;;AAKA,MAAM,cAAc;AACpB,MAAM,kBAAkB;AAExB,eAAe,kBAAqB,QAAoB,MAAiC;AACvF,KAAI;AACF,SAAO,KAAK,MAAM,MAAM,OAAO,SAAS,KAAK,CAAC;SACxC;AACN,SAAO;;;AAIX,SAAS,gBAAgB,KAAkE;AACzF,KAAI,CAAC,IAAK,QAAO;AACjB,QAAO;EACL,SAAS,IAAI,WAAW;EACxB,OAAO,IAAI,SAAS;EACpB,UAAU,IAAI,YAAY;EAC1B,SAAS;GACP,SAAS,IAAI,SAAS,WAAW;GACjC,WAAW,IAAI,SAAS,aAAa,CAAC,IAAI,SAAS,WAAW,KAAK;GACpE;EACD,SAAS,IAAI,WAAW,EAAE;EAC1B,YAAY,IAAI;EAChB,aAAa,IAAI;EACjB,iBAAiB,IAAI;EACtB;;AAYH,eAAsB,WAAW,OAA+D;AAC9F,KAAI,OAAO,UAAU,SAEnB,QAAO,gBADK,MAAM,SAAqC,KAAK,eAAe,MAAM,EAAE,cAAc,CAAC,CACvE;AAG7B,QAAO,gBADK,MAAM,kBAA8C,OAAO,YAAY,CACxD;;AAQ7B,eAAsB,eAAe,OAAwD;AAC3F,KAAI,OAAO,UAAU,SACnB,QAAO,SAAqB,KAAK,eAAe,MAAM,EAAE,kBAAkB,CAAC;AAE7E,QAAO,kBAA8B,OAAO,gBAAgB"}