contentrain-normalize

Contentrain Normalize

Normalize converts a codebase with hardcoded strings into a Contentrain-managed content architecture. It runs in two independent phases, each producing a separate branch for review.

• Phase 1 (Extraction): Pull content from source code into .contentrain/ structure. Source files are NOT modified.
• Phase 2 (Reuse): Patch source files to replace hardcoded strings with content references. Requires completed extraction.

Phase 1 alone is valuable: content becomes manageable in Studio, translatable, and publishable without touching source code.

---

MUST Rules

• MUST scan before extract (contentrain_scan → contentrain_apply)
• MUST dry_run: true before dry_run: false for every contentrain_apply call
• MUST merge Phase 1 branch before starting Phase 2
• MUST run npx contentrain generate after Phase 2 completes
• MUST NOT reuse without scoped model or domain (whole-project patching is blocked)
• MUST NOT patch .contentrain/ files via reuse (content files are read-only for reuse)
• MUST NOT exceed 100 patches per contentrain_apply call

Transport Requirements

Normalize (contentrain_scan and contentrain_apply) requires local disk access — AST scanners walk the source tree and patch files in place. It runs only on a LocalProvider (stdio transport, or an HTTP transport configured with a LocalProvider).

Remote providers (GitHubProvider, GitLabProvider, future BitbucketProvider) expose astScan: false, sourceRead: false, and sourceWrite: false. Calling these tools over a remote provider returns a uniform capability error:

{
  "error": "contentrain_scan requires local filesystem access.",
  "capability_required": "astScan",
  "hint": "This tool is unavailable when MCP is driven by a remote provider. Use a LocalProvider or the stdio transport."
}

If the agent is driving a remote-only MCP session, normalize must run in a separate local-checkout session before the extracted content branch is pushed.