@growth-labs/cms 0.1.0

package/package.json

@@ -0,0 +1,82 @@
+{
+  "name": "@growth-labs/cms",
+  "version": "0.1.0",
+  "type": "module",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./schema": {
+      "types": "./dist/schema/index.d.ts",
+      "import": "./dist/schema/index.js"
+    },
+    "./engine": {
+      "types": "./dist/engine/index.d.ts",
+      "import": "./dist/engine/index.js"
+    },
+    "./routes": {
+      "types": "./dist/routes/index.d.ts",
+      "import": "./dist/routes/index.js"
+    },
+    "./integration": {
+      "types": "./dist/integration/index.d.ts",
+      "import": "./dist/integration/index.js"
+    },
+    "./ui": {
+      "types": "./dist/ui/components/CmsApp.d.ts",
+      "import": "./dist/ui/components/CmsApp.js"
+    },
+    "./ui/client": {
+      "import": "./dist/ui/client/mount.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src/**/*.ts",
+    "src/**/*.tsx",
+    "src/**/*.astro",
+    "src/**/*.css",
+    "src/**/*.sql",
+    "migrations",
+    "README.md"
+  ],
+  "peerDependencies": {
+    "astro": "^6.1.10 || ^7.0.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "dependencies": {
+    "@tiptap/core": "3.24.0",
+    "@tiptap/extension-image": "3.24.0",
+    "@tiptap/extension-link": "3.24.0",
+    "@tiptap/extension-underline": "3.24.0",
+    "@tiptap/pm": "3.24.0",
+    "@tiptap/starter-kit": "3.24.0",
+    "zod": "^3.24.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.5.0",
+    "@types/react": "19.2.16",
+    "@types/react-dom": "19.2.3",
+    "astro": "^6.4.6",
+    "miniflare": "^4.20260515.0",
+    "react": "19.2.7",
+    "react-dom": "19.2.7",
+    "typescript": "^5.7.0",
+    "vite": "^7.3.5",
+    "vitest": "^4.1.8"
+  },
+  "scripts": {
+    "build": "tsc && node scripts/copy-assets.mjs",
+    "check": "biome check src/",
+    "test": "node scripts/run-tests.mjs",
+    "test:flat": "vitest run",
+    "test:watch": "vitest"
+  }
+}

package/src/engine/activity-log.ts

@@ -0,0 +1,39 @@
+// activity-log.ts — first-party D1 write helper for cms_activity_log (P5 Task 3).
+// The table was created in migration 0011. This module provides the single write
+// path (logActivity) so other engine/route code does not inline SQL.
+
+import type { D1Database } from './d1.js'
+
+/** Shape of a single activity log entry (all fields except auto-generated id + created_at). */
+export interface ActivityEntry {
+	workspaceId: string
+	userId: string | null
+	action: string
+	targetId: string | null
+	targetTitle: string | null
+	type: string | null
+}
+
+/**
+ * Inserts one row into cms_activity_log for the given workspace.
+ * Failures are not thrown — callers should wrap in try/catch if they want to
+ * suppress logging errors (see the publish action pattern).
+ */
+export async function logActivity(db: D1Database, entry: ActivityEntry): Promise<void> {
+	const id = crypto.randomUUID()
+	await db
+		.prepare(
+			`INSERT INTO cms_activity_log (id, workspace_id, user_id, action, target_id, target_title, type)
+			 VALUES (?, ?, ?, ?, ?, ?, ?)`,
+		)
+		.bind(
+			id,
+			entry.workspaceId,
+			entry.userId ?? null,
+			entry.action,
+			entry.targetId ?? null,
+			entry.targetTitle ?? null,
+			entry.type ?? null,
+		)
+		.run()
+}

package/src/engine/ai-prompts.ts

@@ -0,0 +1,124 @@
+// AI prompt contracts for the CMS house-style assist (P4 Task 1).
+// Pure string builders — no I/O, no LlmDispatch call. Every route action
+// calls one of these builders to produce the { task, prompt } pair it hands
+// to LlmDispatch.dispatch().
+
+/** House-style system prompt + style guide.
+ *
+ * This is the single shared preamble embedded in every AI prompt. It establishes
+ * the publication's voice, editorial standards, and style constraints so the LLM
+ * produces copy that reads on-brand without fine-tuning or standing RAG infra.
+ *
+ * Exemplar articles, when provided, are passed in-context by the individual
+ * builders — they are NOT stored here.
+ */
+export const HOUSE_STYLE_SYSTEM = `You are an expert editor and writer working for a serious, independent digital publication. Your writing is precise, analytical, and authoritative — you never pad copy with filler phrases or vague hedging.
+
+Style guide:
+- Voice: clear, direct, and economical. Every sentence earns its place.
+- Tone: serious but not stuffy. Informed but not condescending.
+- Avoid: passive voice where active is possible, clichés, jargon without explanation, excessive adjectives, and corporate-speak.
+- Headlines: specific and concrete — name the actor, the action, and the stakes. Avoid questions and listicles unless they are the strongest option.
+- Meta descriptions: factual summaries that state what the article covers; never a teaser or a question.
+- Takeaways: distil the three most important facts or conclusions; do not repeat the headline.
+- Length discipline: tighter is better. Cut redundant words before adding new ones.`
+
+/** Input to proofreadPrompt. */
+export interface ProofreadPromptInput {
+	body: string
+	exemplars?: string[]
+}
+
+/** Input to headlinesPrompt. */
+export interface HeadlinesPromptInput {
+	title: string
+	body: string
+	exemplars?: string[]
+}
+
+/** Input to takeawaysPrompt. */
+export interface TakeawaysPromptInput {
+	body: string
+}
+
+/** Input to metaDescriptionPrompt. */
+export interface MetaDescriptionPromptInput {
+	title: string
+	body: string
+}
+
+/** The typed prompt contract shape consumed by LlmDispatch.dispatch(). */
+export interface AiPromptContract {
+	task: string
+	prompt: string
+}
+
+/** Build the exemplars block when exemplars are supplied. */
+function buildExemplarsBlock(exemplars: string[] | undefined): string {
+	if (!exemplars || exemplars.length === 0) return ''
+	const items = exemplars.map((e, i) => `--- Exemplar ${i + 1} ---\n${e}`).join('\n\n')
+	return `\n\nHere are examples of published articles in this publication's house style for reference:\n\n${items}\n\n--- End of exemplars ---`
+}
+
+/**
+ * Build the prompt for "Proofread & tighten".
+ * The LLM should fix grammar and trim approximately 8% of body length,
+ * returning the revised body text.
+ */
+export function proofreadPrompt(input: ProofreadPromptInput): AiPromptContract {
+	const exemplarsBlock = buildExemplarsBlock(input.exemplars)
+	const prompt = `${HOUSE_STYLE_SYSTEM}${exemplarsBlock}
+
+Task: Proofread and tighten the following article body. Fix grammar, punctuation, and style issues. Trim approximately 8% of the length by removing redundant words, padding, and weak phrases — without losing meaning. Return only the revised article body with no commentary or preamble.
+
+Article body:
+${input.body}`
+	return { task: 'cms.proofread', prompt }
+}
+
+/**
+ * Build the prompt for "Suggest 5 headlines".
+ * The LLM should return exactly 5 SEO-aware headlines, one per line.
+ */
+export function headlinesPrompt(input: HeadlinesPromptInput): AiPromptContract {
+	const exemplarsBlock = buildExemplarsBlock(input.exemplars)
+	const prompt = `${HOUSE_STYLE_SYSTEM}${exemplarsBlock}
+
+Task: Suggest exactly 5 SEO-aware headline alternatives for the following article, in the house voice. Each headline should be specific, concrete, and optimised for search intent. Return exactly 5 headlines, each on a new line, with no numbering, bullets, or additional commentary.
+
+Current title: ${input.title}
+
+Article body:
+${input.body}`
+	return { task: 'cms.headlines', prompt }
+}
+
+/**
+ * Build the prompt for "Generate key takeaways".
+ * The LLM should return 3 bullet takeaways as a JSON array of strings.
+ */
+export function takeawaysPrompt(input: TakeawaysPromptInput): AiPromptContract {
+	const prompt = `${HOUSE_STYLE_SYSTEM}
+
+Task: Extract exactly 3 key takeaways from the following article. Each takeaway should be a concise, factual sentence that distils an important conclusion or finding. Return ONLY a JSON array of 3 strings — no markdown, no commentary, no preamble. Example output format: ["Takeaway one.", "Takeaway two.", "Takeaway three."]
+
+Article body:
+${input.body}`
+	return { task: 'cms.takeaways', prompt }
+}
+
+/**
+ * Build the prompt for "Draft meta description".
+ * The LLM should return a single meta description strictly under 160 characters.
+ */
+export function metaDescriptionPrompt(input: MetaDescriptionPromptInput): AiPromptContract {
+	const prompt = `${HOUSE_STYLE_SYSTEM}
+
+Task: Write a single meta description for the following article. The meta description must be strictly less than 160 characters, factual, and summarise what the article covers. Do not use questions, teasers, or clickbait. Return only the meta description text with no commentary or preamble.
+
+Article title: ${input.title}
+
+Article body:
+${input.body}`
+	return { task: 'cms.meta', prompt }
+}

package/src/engine/ai-writeback.ts

@@ -0,0 +1,62 @@
+// ai_locked_fields write-back gate (P4 Task 2).
+// Pure functions — no I/O, no D1, no LlmDispatch.
+//
+// The per-field manual-override model (spec §9): a field listed in
+// ai_locked_fields was hand-edited and must NOT be clobbered by an AI write.
+
+/**
+ * Parse the raw ai_locked_fields column value (JSON string | null | undefined)
+ * into a string array. Tolerates null, undefined, empty string, and malformed
+ * JSON — returns [] in all error cases.
+ */
+export function parseLockedFields(raw: string | null | undefined): string[] {
+	if (!raw) return []
+	try {
+		const parsed = JSON.parse(raw)
+		if (!Array.isArray(parsed)) return []
+		return parsed as string[]
+	} catch {
+		return []
+	}
+}
+
+/**
+ * Return true if the field may be AI-written (not in lockedFields).
+ * Return false if the field is listed in lockedFields.
+ */
+export function canWriteField(lockedFields: string[], field: string): boolean {
+	return !lockedFields.includes(field)
+}
+
+/** Input to applyAiWrite. */
+export interface AiWriteInput<T = unknown> {
+	/** The current locked-fields list (from parseLockedFields). */
+	locked: string[]
+	/** The DB column / field name being written. */
+	field: string
+	/** The AI-generated value to (conditionally) write. */
+	value: T
+}
+
+/** Result of applyAiWrite. */
+export interface AiWriteResult<T = unknown> {
+	/** True when the value should be persisted; false when the field is locked. */
+	written: boolean
+	/** The generated value, echoed back regardless of written status. */
+	value: T
+}
+
+/**
+ * Decide whether the AI-generated value for `field` may be persisted.
+ *
+ * - If the field is NOT in `locked` → `{ written: true, value }`.
+ * - If the field IS in `locked` → `{ written: false, value }` (value echoed,
+ *   not written — the caller returns the suggestion but skips the DB update).
+ */
+export function applyAiWrite<T = unknown>(input: AiWriteInput<T>): AiWriteResult<T> {
+	const { locked, field, value } = input
+	if (canWriteField(locked, field)) {
+		return { written: true, value }
+	}
+	return { written: false, value }
+}

package/src/engine/api-keys.ts

@@ -0,0 +1,239 @@
+// api-keys.ts — CMS API key engine (P7 Task 7).
+//
+// Implements:
+//   generateRawKey()    — prefixed random token (Web Crypto, workerd-native)
+//   sha256Hex(s)        — SHA-256 hex digest (Web Crypto — no node:crypto)
+//   createApiKey()      — generate raw, hash, store hash+prefix only, return raw once
+//   listApiKeys()       — masked list (no hash, no raw)
+//   revokeApiKey()      — DELETE row
+//   verifyCmsApiKey()   — hash the input, SELECT by key_hash, bump last_used, return
+//                         workspaceId + scopes or null
+//
+// Security invariants (spec §12 scope guard 4):
+//   - Raw key is NEVER stored. Only key_hash (SHA-256 hex) lives in D1.
+//   - Masked display uses the stored key_prefix hint (added in migration 0014).
+//   - verifyCmsApiKey equality is on the SHA-256 hash lookup — NOT a raw string
+//     comparison — so the lookup is constant-time-safe at the DB layer.
+//   - No node:crypto — uses Web Crypto (crypto.subtle / crypto.getRandomValues),
+//     workerd-native.
+
+import type { D1Database } from './d1.js'
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/** The result of createApiKey — rawKey is revealed ONCE and never stored. */
+export interface CreateApiKeyResult {
+	id: string
+	/** The full raw key — shown ONCE on creation, never stored in D1. */
+	rawKey: string
+	/** Safe masked display hint stored in D1 (e.g. 'mk_live_••••ab12'). */
+	masked: string
+}
+
+/** A masked API key entry for the list view — no hash, no raw. */
+export interface ApiKeyListEntry {
+	id: string
+	name: string
+	/** Safe masked display (e.g. 'mk_live_••••ab12'). */
+	masked: string
+	scopes: string[]
+	createdAt: number
+	lastUsed: number | null
+}
+
+/** The result of a successful verifyCmsApiKey lookup. */
+export interface VerifyApiKeyResult {
+	workspaceId: string
+	scopes: string[]
+}
+
+export interface CreateApiKeyInput {
+	workspaceId: string
+	name: string
+	scopes: string[]
+}
+
+// ---------------------------------------------------------------------------
+// Crypto helpers (Web Crypto — no node:crypto, workerd-native)
+// ---------------------------------------------------------------------------
+
+const KEY_PREFIX = 'mk_live_'
+
+/**
+ * Generate a random API key with the 'mk_live_' prefix.
+ * Uses crypto.getRandomValues for entropy (workerd-native).
+ * The returned value is 32 random bytes encoded as hex (64 chars) + prefix.
+ */
+export function generateRawKey(): string {
+	const bytes = new Uint8Array(32)
+	crypto.getRandomValues(bytes)
+	const hex = Array.from(bytes)
+		.map((b) => b.toString(16).padStart(2, '0'))
+		.join('')
+	return `${KEY_PREFIX}${hex}`
+}
+
+/**
+ * Compute the SHA-256 hex digest of a string. Uses Web Crypto (crypto.subtle)
+ * — no node:crypto, workerd-native.
+ */
+export async function sha256Hex(input: string): Promise<string> {
+	const encoder = new TextEncoder()
+	const data = encoder.encode(input)
+	const hashBuffer = await crypto.subtle.digest('SHA-256', data)
+	const hashArray = Array.from(new Uint8Array(hashBuffer))
+	return hashArray.map((b) => b.toString(16).padStart(2, '0')).join('')
+}
+
+/**
+ * Build the safe display hint for a raw key.
+ * Format: '<prefix>••••<last4>' — e.g. 'mk_live_••••a1b2'
+ * The last 4 characters of the hex portion are kept; the rest is masked.
+ */
+function buildMaskedHint(rawKey: string): string {
+	const last4 = rawKey.slice(-4)
+	return `${KEY_PREFIX}••••${last4}`
+}
+
+// ---------------------------------------------------------------------------
+// createApiKey
+// ---------------------------------------------------------------------------
+
+/**
+ * Create a new CMS API key.
+ *
+ * - Generates a random raw key (prefix + 32 random hex bytes).
+ * - Computes SHA-256(raw) and stores ONLY the hash.
+ * - Stores a safe masked display hint (key_prefix column, migration 0014).
+ * - Returns the raw key ONCE — it is never retrievable again.
+ */
+export async function createApiKey(
+	db: D1Database,
+	input: CreateApiKeyInput,
+): Promise<CreateApiKeyResult> {
+	const id = crypto.randomUUID()
+	const rawKey = generateRawKey()
+	const keyHash = await sha256Hex(rawKey)
+	const masked = buildMaskedHint(rawKey)
+	const scopesJson = JSON.stringify(input.scopes)
+	const now = Math.floor(Date.now() / 1000)
+
+	await db
+		.prepare(
+			`INSERT INTO cms_api_keys (id, workspace_id, name, key_hash, key_prefix, scopes, created_at)
+			 VALUES (?, ?, ?, ?, ?, ?, ?)`,
+		)
+		.bind(id, input.workspaceId, input.name, keyHash, masked, scopesJson, now)
+		.run()
+
+	return { id, rawKey, masked }
+}
+
+// ---------------------------------------------------------------------------
+// listApiKeys
+// ---------------------------------------------------------------------------
+
+/**
+ * List all API keys for a workspace. Returns masked entries — no hash, no raw.
+ * Ordered by created_at ASC (deterministic).
+ */
+export async function listApiKeys(db: D1Database, workspaceId: string): Promise<ApiKeyListEntry[]> {
+	const result = await db
+		.prepare(
+			`SELECT id, name, key_prefix, scopes, created_at, last_used
+			 FROM cms_api_keys
+			 WHERE workspace_id = ?
+			 ORDER BY created_at ASC`,
+		)
+		.bind(workspaceId)
+		.all<{
+			id: string
+			name: string
+			key_prefix: string | null
+			scopes: string
+			created_at: number
+			last_used: number | null
+		}>()
+
+	return (result.results ?? []).map((row) => ({
+		id: row.id,
+		name: row.name,
+		// If key_prefix is stored (migration 0014), use it; otherwise fall back.
+		masked: row.key_prefix ?? `${KEY_PREFIX}••••`,
+		scopes: parseScopes(row.scopes),
+		createdAt: row.created_at,
+		lastUsed: row.last_used,
+	}))
+}
+
+// ---------------------------------------------------------------------------
+// revokeApiKey
+// ---------------------------------------------------------------------------
+
+/**
+ * Revoke (delete) an API key by its id, SCOPED to the caller's workspace.
+ *
+ * The workspaceId is resolved from the authenticated caller (auth/locals) and
+ * MUST be passed by the route — never trusted from the client. Scoping the
+ * DELETE by workspace_id closes a cross-workspace IDOR: a member of workspace A
+ * cannot revoke workspace B's key by guessing/leaking its id.
+ *
+ * After revocation, verifyCmsApiKey returns null for the associated raw key.
+ */
+export async function revokeApiKey(db: D1Database, id: string, workspaceId: string): Promise<void> {
+	await db
+		.prepare(`DELETE FROM cms_api_keys WHERE id = ? AND workspace_id = ?`)
+		.bind(id, workspaceId)
+		.run()
+}
+
+// ---------------------------------------------------------------------------
+// verifyCmsApiKey — gateway helper (exported for the content-API gateway)
+// ---------------------------------------------------------------------------
+
+/**
+ * Verify a raw CMS API key at the content-API gateway.
+ *
+ * - Hashes the raw input via SHA-256.
+ * - Looks up the row by key_hash (equality on the hash — constant-time-safe
+ *   at the DB layer; the raw string is never compared).
+ * - On match: bumps last_used, returns { workspaceId, scopes }.
+ * - On miss (unknown or revoked): returns null.
+ */
+export async function verifyCmsApiKey(
+	db: D1Database,
+	rawKey: string,
+): Promise<VerifyApiKeyResult | null> {
+	const keyHash = await sha256Hex(rawKey)
+	const now = Math.floor(Date.now() / 1000)
+
+	const row = await db
+		.prepare(`SELECT id, workspace_id, scopes FROM cms_api_keys WHERE key_hash = ?`)
+		.bind(keyHash)
+		.first<{ id: string; workspace_id: string; scopes: string }>()
+
+	if (!row) return null
+
+	// Bump last_used (fire-and-forget — best-effort; does not affect auth decision)
+	await db.prepare(`UPDATE cms_api_keys SET last_used = ? WHERE id = ?`).bind(now, row.id).run()
+
+	return {
+		workspaceId: row.workspace_id,
+		scopes: parseScopes(row.scopes),
+	}
+}
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+function parseScopes(scopesJson: string): string[] {
+	try {
+		const parsed = JSON.parse(scopesJson)
+		return Array.isArray(parsed) ? parsed : []
+	} catch {
+		return []
+	}
+}