@contentrain/types 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Contentrain
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,174 @@
+# `@contentrain/types`
+
+Shared TypeScript types for the Contentrain ecosystem.
+
+This package is the common schema layer used by:
+
+- `@contentrain/mcp`
+- `contentrain`
+- `@contentrain/query`
+- `@contentrain/rules`
+
+It defines the stable type vocabulary for models, config, metadata, validation, scanning, and context files.
+
+## ✨ When To Use It
+
+Use `@contentrain/types` when you are:
+
+- building tooling on top of Contentrain packages
+- sharing model/config types between packages in a workspace
+- authoring framework integrations or SDK extensions
+- consuming Contentrain JSON structures directly in TypeScript
+
+## 🚀 Install
+
+```bash
+pnpm add @contentrain/types
+```
+
+## 📦 What It Exports
+
+Core unions:
+
+- `FieldType`
+- `ModelKind`
+- `ContentStatus`
+- `ContentSource`
+- `WorkflowMode`
+- `StackType`
+- `Platform`
+- `ContextSource`
+- `CollectionRuntimeFormat`
+- `LocaleStrategy`
+
+Core interfaces:
+
+- `FieldDef`
+- `ModelDefinition`
+- `ContentrainConfig`
+- `Vocabulary`
+- `EntryMeta`
+- `AssetEntry`
+- `ValidationError`
+- `ValidationResult`
+- `ScaffoldTemplate`
+- `ScanCandidate`
+- `DuplicateGroup`
+- `GraphNode`
+- `ProjectGraph`
+- `ScanCandidatesResult`
+- `ScanSummaryResult`
+- `ContextJson`
+
+Storage/runtime helper types:
+
+- `SingletonContentFile`
+- `CollectionContentFile`
+- `DictionaryContentFile`
+- `CollectionEntry`
+- `CollectionContentOutput`
+- `SingletonMeta`
+- `CollectionMeta`
+- `DocumentMeta`
+- `DictionaryMeta`
+
+## 🧭 Stability
+
+This package is intended to be the shared public contract across the Contentrain ecosystem.
+
+In practice that means:
+
+- types exported from the package root are the public surface
+- packages should depend on these shared definitions instead of redefining domain types
+- breaking changes here should be treated as ecosystem-level breaking changes
+
+## 🧪 Quick Example
+
+```ts
+import type {
+  ContentrainConfig,
+  FieldDef,
+  ModelDefinition,
+  ValidationResult,
+} from '@contentrain/types'
+
+const fields: Record<string, FieldDef> = {
+  title: { type: 'string', required: true },
+  slug: { type: 'slug', required: true, unique: true },
+}
+
+const model: ModelDefinition = {
+  id: 'blog-post',
+  name: 'Blog Post',
+  kind: 'collection',
+  domain: 'blog',
+  i18n: true,
+  fields,
+}
+
+const config: ContentrainConfig = {
+  version: 1,
+  stack: 'next',
+  workflow: 'review',
+  locales: { default: 'en', supported: ['en', 'tr'] },
+  domains: ['blog'],
+}
+
+const result: ValidationResult = {
+  valid: true,
+  errors: [],
+}
+```
+
+## 📝 Import Style
+
+Type-only usage:
+
+```ts
+import type { ModelDefinition, ContentrainConfig } from '@contentrain/types'
+```
+
+Runtime-safe mixed usage:
+
+```ts
+import type { FieldDef } from '@contentrain/types'
+```
+
+## 🧠 Design Role
+
+`@contentrain/types` exists so every package in the monorepo speaks the same domain language.
+
+Examples:
+
+- MCP validates and writes `ModelDefinition`
+- CLI reads `ContextJson`
+- SDK codegen consumes `ModelDefinition` and `FieldDef`
+- AI rules align with the same model and workflow vocabulary
+
+This package should stay:
+
+- small
+- dependency-light
+- stable
+- free of package-specific behavior
+
+## 🛠 Development
+
+From the monorepo root:
+
+```bash
+pnpm --filter @contentrain/types build
+pnpm --filter @contentrain/types test
+pnpm --filter @contentrain/types typecheck
+```
+
+## 🔗 Related Packages
+
+- `@contentrain/mcp`
+- `contentrain`
+- `@contentrain/query`
+- `@contentrain/rules`
+
+## 📄 License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,191 @@
+//#region src/index.d.ts
+type FieldType = 'string' | 'text' | 'email' | 'url' | 'slug' | 'color' | 'phone' | 'code' | 'icon' | 'markdown' | 'richtext' | 'number' | 'integer' | 'decimal' | 'percent' | 'rating' | 'boolean' | 'date' | 'datetime' | 'image' | 'video' | 'file' | 'relation' | 'relations' | 'select' | 'array' | 'object';
+type ModelKind = 'singleton' | 'collection' | 'document' | 'dictionary';
+type ContentStatus = 'draft' | 'in_review' | 'published' | 'rejected' | 'archived';
+type ContentSource = 'agent' | 'human' | 'import';
+type WorkflowMode = 'auto-merge' | 'review';
+type StackType = 'nuxt' | 'next' | 'astro' | 'sveltekit' | 'remix' | 'analog' | 'vue' | 'react' | 'svelte' | 'solid' | 'angular' | 'react-native' | 'expo' | 'flutter' | 'node' | 'express' | 'fastify' | 'nestjs' | 'django' | 'rails' | 'laravel' | 'go' | 'rust' | 'dotnet' | 'hugo' | 'jekyll' | 'eleventy' | 'electron' | 'tauri' | 'other';
+type Platform = 'web' | 'mobile' | 'api' | 'desktop' | 'static' | 'other';
+type ContextSource = 'mcp-local' | 'mcp-studio' | 'studio-ui';
+type CollectionRuntimeFormat = 'map' | 'array';
+interface FieldDef {
+  type: FieldType;
+  required?: boolean;
+  unique?: boolean;
+  default?: unknown;
+  min?: number;
+  max?: number;
+  pattern?: string;
+  options?: string[];
+  model?: string | string[];
+  items?: string | FieldDef;
+  fields?: Record<string, FieldDef>;
+  accept?: string;
+  maxSize?: number;
+  description?: string;
+}
+type LocaleStrategy = 'file' | 'suffix' | 'directory' | 'none';
+interface ModelDefinition {
+  id: string;
+  name: string;
+  kind: ModelKind;
+  domain: string;
+  i18n: boolean;
+  description?: string;
+  fields?: Record<string, FieldDef>;
+  /** Framework-relative path for content files (e.g. "content/blog", "locales"). When set, content is written here instead of .contentrain/content/ */
+  content_path?: string;
+  /** How locale is encoded in file names. Default: "file" ({dir}/{locale}.json or {dir}/{slug}/{locale}.md) */
+  locale_strategy?: LocaleStrategy;
+}
+interface ContentrainConfig {
+  version: number;
+  platform?: Platform;
+  stack: StackType;
+  workflow: WorkflowMode;
+  repository?: {
+    provider: 'github';
+    owner: string;
+    name: string;
+    default_branch: string;
+  };
+  locales: {
+    default: string;
+    supported: string[];
+  };
+  domains: string[];
+  assets_path?: string;
+  branchRetention?: number;
+}
+interface Vocabulary {
+  version: number;
+  terms: Record<string, Record<string, string>>;
+}
+interface EntryMeta {
+  status: ContentStatus;
+  source: ContentSource;
+  updated_by: string;
+  approved_by?: string | null;
+  version?: string;
+  publish_at?: string;
+  expire_at?: string;
+}
+type SingletonMeta = EntryMeta;
+type CollectionMeta = Record<string, EntryMeta>;
+type DocumentMeta = EntryMeta;
+type DictionaryMeta = EntryMeta;
+interface AssetEntry {
+  path: string;
+  type: string;
+  size: number;
+  alt?: string;
+}
+interface ValidationError {
+  severity: 'error' | 'warning' | 'notice';
+  model?: string;
+  locale?: string;
+  entry?: string;
+  slug?: string;
+  field?: string;
+  message: string;
+}
+interface ValidationResult {
+  valid: boolean;
+  errors: ValidationError[];
+}
+type SingletonContentFile = Record<string, unknown>;
+type CollectionContentFile = Record<string, Record<string, unknown>>;
+type DictionaryContentFile = Record<string, string>;
+type CollectionEntry = {
+  id: string;
+} & Record<string, unknown>;
+type CollectionContentOutput = CollectionEntry[];
+interface ScaffoldTemplate {
+  id: string;
+  models: ModelDefinition[];
+  sample_content?: Record<string, Record<string, unknown>>;
+  vocabulary?: Record<string, Record<string, string>>;
+}
+type StringContext = 'jsx_text' | 'jsx_attribute' | 'template_text' | 'template_attribute' | 'variable_assignment' | 'function_argument' | 'object_value' | 'other';
+type FileCategory = 'page' | 'component' | 'layout' | 'other';
+interface ScanCandidate {
+  file: string;
+  line: number;
+  column: number;
+  value: string;
+  context: StringContext;
+  surrounding: string;
+}
+interface DuplicateGroup {
+  value: string;
+  count: number;
+  occurrences: Array<{
+    file: string;
+    line: number;
+  }>;
+}
+interface GraphNode {
+  file: string;
+  category: FileCategory;
+  components?: string[];
+  imports: string[];
+  used_by: string[];
+  strings: number;
+}
+interface ProjectGraph {
+  pages: GraphNode[];
+  components: GraphNode[];
+  layouts: GraphNode[];
+  orphan_files: string[];
+  stats: {
+    total_files: number;
+    total_components: number;
+    total_pages: number;
+    total_strings_estimate: number;
+  };
+}
+interface ScanCandidatesResult {
+  candidates: ScanCandidate[];
+  duplicates: DuplicateGroup[];
+  stats: {
+    files_scanned: number;
+    raw_strings_found: number;
+    after_filtering: number;
+    candidates_returned: number;
+    has_more: boolean;
+  };
+}
+interface ScanSummaryResult {
+  total_files: number;
+  total_candidates_estimate: number;
+  by_directory: Record<string, {
+    files: number;
+    candidates: number;
+  }>;
+  top_repeated: Array<{
+    value: string;
+    count: number;
+  }>;
+  sampling_note?: string;
+  file_types: Record<string, number>;
+}
+interface ContextJson {
+  version: string;
+  lastOperation: {
+    tool: string;
+    model: string;
+    locale: string;
+    entries?: string[];
+    timestamp: string;
+    source: ContextSource;
+  };
+  stats: {
+    models: number;
+    entries: number;
+    locales: string[];
+    lastSync: string;
+  };
+}
+//#endregion
+export { AssetEntry, CollectionContentFile, CollectionContentOutput, CollectionEntry, CollectionMeta, CollectionRuntimeFormat, ContentSource, ContentStatus, ContentrainConfig, ContextJson, ContextSource, DictionaryContentFile, DictionaryMeta, DocumentMeta, DuplicateGroup, EntryMeta, FieldDef, FieldType, FileCategory, GraphNode, LocaleStrategy, ModelDefinition, ModelKind, Platform, ProjectGraph, ScaffoldTemplate, ScanCandidate, ScanCandidatesResult, ScanSummaryResult, SingletonContentFile, SingletonMeta, StackType, StringContext, ValidationError, ValidationResult, Vocabulary, WorkflowMode };
+//# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/index.ts"],"mappings":"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"}

package/dist/index.mjs

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@contentrain/types",
+  "version": "0.1.0",
+  "license": "MIT",
+  "description": "Shared TypeScript types for Contentrain ecosystem",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/contentrain/contentrain-ai.git",
+    "directory": "packages/types"
+  },
+  "homepage": "https://github.com/contentrain/contentrain-ai/tree/main/packages/types",
+  "bugs": {
+    "url": "https://github.com/contentrain/contentrain-ai/issues"
+  },
+  "keywords": [
+    "contentrain",
+    "types",
+    "typescript",
+    "schema",
+    "content-governance"
+  ],
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs"
+    }
+  },
+  "main": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "devDependencies": {
+    "tsdown": "^0.21.0",
+    "typescript": "^5.7.0"
+  },
+  "scripts": {
+    "build": "tsdown src/index.ts --format esm --dts",
+    "dev": "tsdown src/index.ts --format esm --dts --watch",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist"
+  }
+}