@growth-labs/cms 0.8.19 → 0.8.23

package/src/engine/publisher.ts

@@ -30,6 +30,7 @@ import {
 	validateDeclaredTagList,
 	validateStoredTaxonomyRows,
 } from './taxonomy.js'
+import { VideoSourceNotIngestableError, videoSourceUrlIngestableOverHttps } from './video-source.js'
 
 export {
 	MAX_ITEM_TAG_COUNT,
@@ -625,6 +626,20 @@ export async function createContent(
 	db: D1Database,
 	input: CreateContentInput,
 ): Promise<{ id: string; slug: string }> {
+	// Refuse before the provider probe or any row write: an http_url source
+	// with a query, fragment, userinfo or non-https scheme can never pass
+	// Foundry's media probe, so storing it strands a scheduled video (the
+	// HomeFronts 2026-10-01T18:05Z incident). Dropbox links legitimately
+	// carry `?dl=1` and stay out of this check.
+	if (
+		input.type === 'video' &&
+		input.content.processingSourceUrl !== undefined &&
+		input.content.processingSourceUrl !== null &&
+		(input.content.processingSourceKind ?? 'http_url') === 'http_url' &&
+		!videoSourceUrlIngestableOverHttps(input.content.processingSourceUrl)
+	) {
+		throw new VideoSourceNotIngestableError()
+	}
 	const resolvedMediaDuration =
 		input.type === 'video'
 			? await resolveMediaDuration(
@@ -775,6 +790,21 @@ export async function getContentItem(
 		.first<ContentItemRecord>()
 }
 
+/**
+ * A human-initiated canonical change written outside updateContentItem (an
+ * editor-triggered AI write-back to a field updateContentItem does not carry):
+ * advances canonical_version exactly as updateContentItem's own UPDATE does.
+ * canonical_version is how the Foundry machine route knows the working copy is
+ * no longer only what its last PUT wrote (M3-18 resync guard).
+ */
+export function canonicalEditStatement(db: D1Database, contentId: string) {
+	return db
+		.prepare(
+			'UPDATE content_items SET canonical_version = canonical_version + 1, updated_at = unixepoch() WHERE id = ?',
+		)
+		.bind(contentId)
+}
+
 export async function updateContentItem(
 	db: D1Database,
 	id: string,
@@ -823,6 +853,16 @@ export async function updateContentItem(
 			const sourceKind = hasOwn(videoContent, 'processingSourceKind')
 				? (videoContent.processingSourceKind ?? null)
 				: current.processing_source_kind
+			// Same refusal as createContent, against the merged (input-or-stored)
+			// source: a row that already holds a query-bearing link is corrected
+			// at the next save, while the editor is still there to re-capture it.
+			if (
+				sourceUrl !== null &&
+				(sourceKind ?? 'http_url') === 'http_url' &&
+				!videoSourceUrlIngestableOverHttps(sourceUrl)
+			) {
+				throw new VideoSourceNotIngestableError()
+			}
 			const sourceChanged =
 				sourceUrl !== current.processing_source_url || sourceKind !== current.processing_source_kind
 			const durationProvided = hasOwn(videoContent, 'durationSeconds')
@@ -997,8 +1037,8 @@ export async function updateContentItem(
 		: existing.metadata_json
 
 	if (options.requiredStatus) {
-		if (input.tags !== undefined || input.relations !== undefined) {
-			throw new TypeError('Status-constrained updates do not support tags or relations')
+		if (input.relations !== undefined) {
+			throw new TypeError('Status-constrained updates do not support relations')
 		}
 		if (!isBodyBackedContentType(existing.type)) {
 			throw new TypeError('Status-constrained updates require body-backed content')
@@ -1131,6 +1171,31 @@ export async function updateContentItem(
 			)
 		}
 
+		if (tagPairs) {
+			// Tag links join the same transaction under the same status predicate,
+			// so a refused (non-matching status) update leaves the links untouched.
+			// Tag dictionary rows are shared and idempotent, so they may be ensured
+			// up front even when the guarded write below is refused.
+			const tagRows = tagPairs.length > 0 ? await ensureTags(db, tagPairs) : []
+			const statusGuard = `EXISTS (SELECT 1 FROM content_items
+			   WHERE id = ? AND status = ? AND deleted_at IS NULL)`
+			statements.push(
+				db
+					.prepare(`DELETE FROM content_tag_links WHERE content_id = ? AND ${statusGuard}`)
+					.bind(id, id, options.requiredStatus),
+			)
+			for (const tag of tagRows) {
+				statements.push(
+					db
+						.prepare(
+							`INSERT INTO content_tag_links (content_id, tag_id, label)
+							 SELECT ?, ?, ? WHERE ${statusGuard}`,
+						)
+						.bind(id, tag.id, tag.label, id, options.requiredStatus),
+				)
+			}
+		}
+
 		const statusResultIndex = statements.length
 		statements.push(
 			db
@@ -1677,14 +1742,25 @@ export async function claimScheduledForPublish(
 	return changes > 0
 }
 
-export async function unpublishContent(db: D1Database, id: string): Promise<void> {
+export async function unpublishContent(
+	db: D1Database,
+	id: string,
+	options: {
+		/**
+		 * A person pulled the item: advance canonical_version in the same UPDATE,
+		 * so a machine publisher can never put it back without a new write of its
+		 * own (the Foundry machine route's human-edit guard, M3-18).
+		 */
+		canonicalEdit?: boolean
+	} = {},
+): Promise<void> {
 	await db
 		.prepare(
 			`UPDATE content_items
        SET status = 'draft',
            published_at = NULL,
            publish_at = NULL,
-           updated_at = unixepoch()
+           updated_at = unixepoch()${options.canonicalEdit ? ', canonical_version = canonical_version + 1' : ''}
        WHERE id = ?`,
 		)
 		.bind(id)

package/src/engine/tags.ts

@@ -106,12 +106,32 @@ export async function renameTag(db: D1Database, tagId: string, label: string): P
 			.prepare('UPDATE content_tags SET label = ?, slug = ? WHERE id = ?')
 			.bind(tag.label, tag.slug, tagId),
 		db.prepare('UPDATE content_tag_links SET label = ? WHERE tag_id = ?').bind(tag.label, tagId),
+		// A rename is a human-initiated canonical change to every item carrying
+		// the tag, exactly as topic rename is (engine/topics.ts).
+		bumpTaggedItems(db, tagId),
 	])
 	return Boolean(res.meta && (res.meta as { changes?: number }).changes)
 }
 
 export async function deleteTag(db: D1Database, tagId: string): Promise<boolean> {
 	// content_tag_links has ON DELETE CASCADE on tag_id (0001), so links go too.
-	const res = await db.prepare('DELETE FROM content_tags WHERE id = ?').bind(tagId).run()
+	// The tagged items are bumped first, in the same batch, while the links that
+	// name them still exist.
+	const [, res] = await db.batch([
+		bumpTaggedItems(db, tagId),
+		db.prepare('DELETE FROM content_tags WHERE id = ?').bind(tagId),
+	])
 	return Boolean(res.meta && (res.meta as { changes?: number }).changes)
 }
+
+/** canonical_version + 1 for every live item linked to the tag. */
+function bumpTaggedItems(db: D1Database, tagId: string) {
+	return db
+		.prepare(
+			`UPDATE content_items
+			 SET canonical_version = canonical_version + 1, updated_at = unixepoch()
+			 WHERE deleted_at IS NULL
+			   AND id IN (SELECT content_id FROM content_tag_links WHERE tag_id = ?)`,
+		)
+		.bind(tagId)
+}

package/src/engine/topics.ts

@@ -133,7 +133,10 @@ export async function renameTopic(
 	const res = await db
 		.prepare(
 			`UPDATE content_items
-			 SET primary_topic = ?, updated_at = unixepoch()
+			 SET primary_topic = ?, updated_at = unixepoch(),
+			     -- A rename is a human-initiated canonical change to every item it
+			     -- touches, exactly as an editor's per-item topic change is.
+			     canonical_version = canonical_version + 1
 			 WHERE deleted_at IS NULL AND primary_topic = ?`,
 		)
 		.bind(nextSlug, currentSlug)

package/src/engine/video-source.ts

@@ -46,3 +46,47 @@ export async function frontsVideoSourceGeneration(
 export function videoSourceIngestableOverHttps(kind: string | null | undefined): boolean {
 	return kind === 'http_url' || kind === 'dropbox'
 }
+
+/**
+ * The URL shape Foundry's ingest accepts (capabilityplane/ingest.go
+ * `validHTTPSIngestURL`): https, a host, and no userinfo, query or
+ * fragment. A URL outside this shape is refused at the Go media probe with
+ * "artifact ingest probe source URL is invalid" — the failure that blocked
+ * a scheduled HomeFronts video on 2026-10-01T18:05Z. The IP-range checks
+ * (`PublicHTTPSIngestHost`) stay Foundry's: the CMS only refuses what no
+ * host would accept.
+ */
+export function videoSourceUrlIngestableOverHttps(rawUrl: string | null | undefined): boolean {
+	if (!rawUrl) return false
+	let url: URL
+	try {
+		url = new URL(rawUrl)
+	} catch {
+		return false
+	}
+	return (
+		url.protocol === 'https:' &&
+		url.hostname !== '' &&
+		!url.username &&
+		!url.password &&
+		url.search === '' &&
+		url.hash === ''
+	)
+}
+
+/**
+ * A video source whose URL `videoSourceUrlIngestableOverHttps` refuses (a
+ * query string, fragment, userinfo or non-https scheme). Thrown by the
+ * publisher's video write so the save fails before a row can strand a
+ * scheduled video at the Go media probe. The message is the whole
+ * editor-facing error and deliberately echoes no part of the URL — a share
+ * link's path or query can carry its token.
+ */
+export class VideoSourceNotIngestableError extends Error {
+	constructor() {
+		super(
+			'Video source URL must be a direct HTTPS link with no query string or fragment — Foundry refuses to ingest it. A Fulcrum Drive share link must be pasted in its direct /download form.',
+		)
+		this.name = 'VideoSourceNotIngestableError'
+	}
+}

package/src/foundry-emit.ts

@@ -0,0 +1,255 @@
+// @growth-labs/cms/foundry-emit — the one v2 schema for the Foundry machine
+// article route, shared by the route (routes/foundry-publish.ts) and by every
+// producer that emits into it, plus a pure mapper from the archive-import item
+// shape (ContentArchiveItem, as the channel repos' compiler.mjs builds it) to a
+// v2 body.
+//
+// This module must stay importable in pure Node: zod, the pure slug helpers and
+// type-only imports. Nothing here touches D1, the network or `cloudflare:*`.
+
+import { sha256Hex } from '@growth-labs/foundry-signing'
+import { z } from 'zod'
+import type { ContentArchiveItem } from './engine/publication.js'
+import { slugify } from './engine/slug.js'
+
+export const FOUNDRY_ARTICLE_SCHEMA_VERSION = 2 as const
+
+/** The machine route's own source namespace; an adoption never targets it. */
+export const FOUNDRY_SOURCE_PREFIX = 'foundry:'
+
+/** Upper bound the publication kernel accepts for a revision's slug. */
+export const FOUNDRY_SLUG_MAX_LENGTH = 512
+
+/**
+ * The engine's slug rule, applied verbatim: a v2 slug is accepted only when it
+ * is already canonical (`slugify(slug) === slug`), because the route never
+ * derives, rewrites or suffixes a v2 slug.
+ */
+export function isCanonicalSlug(value: string): boolean {
+	return value.length >= 3 && value.length <= FOUNDRY_SLUG_MAX_LENGTH && slugify(value) === value
+}
+
+const HERO_IMAGE_KEY = /^[A-Za-z0-9][A-Za-z0-9._\-/]*$/
+
+export const FoundryArticleV2Schema = z
+	.object({
+		schemaVersion: z.literal(FOUNDRY_ARTICLE_SCHEMA_VERSION),
+		slug: z.string().refine(isCanonicalSlug, {
+			message: 'slug must already be canonical: lowercase a-z, 0-9 and single hyphens, 3-512 chars',
+		}),
+		title: z.string().trim().min(3),
+		body_html: z.string().min(1),
+		hero_image_key: z
+			.string()
+			.min(1)
+			.max(1024)
+			.refine((key) => HERO_IMAGE_KEY.test(key) && !key.split('/').includes('..'), {
+				message: 'hero_image_key must be a relative object key',
+			})
+			.optional(),
+		hero_image_url: z
+			.string()
+			.url()
+			.refine((url) => url.startsWith('https://'), { message: 'hero_image_url must be https' })
+			.optional(),
+		publishAt: z.string().datetime({ offset: true }).optional(),
+		author: z.string().trim().min(1).max(200).optional(),
+		desk: z.string().trim().min(1).max(100).optional(),
+		tags: z.array(z.string().trim().min(1).max(100)).max(50).optional(),
+		description: z.string().trim().min(1).optional(),
+		visibility: z.enum(['free', 'premium']).optional(),
+		adoptSourceId: z
+			.string()
+			.min(1)
+			.max(256)
+			.refine((value) => value === value.trim() && !value.startsWith(FOUNDRY_SOURCE_PREFIX), {
+				message: 'adoptSourceId must be a trimmed bridge source id, never a foundry: id',
+			})
+			.optional(),
+	})
+	.strict()
+	.refine((body) => !(body.hero_image_key && body.hero_image_url), {
+		message: 'send hero_image_key or hero_image_url, not both',
+		path: ['hero_image_key'],
+	})
+
+export type FoundryArticleV2 = z.output<typeof FoundryArticleV2Schema>
+
+export class FoundryEmitError extends Error {
+	readonly code: string
+
+	constructor(code: string, message: string) {
+		super(message)
+		this.name = 'FoundryEmitError'
+		this.code = code
+	}
+}
+
+export interface FoundryEmitOptions {
+	/**
+	 * Overrides the publication time. Omitted: the item's `publishedAt` (unix
+	 * seconds) is used when present. `null`: no publishAt, so the route writes a
+	 * draft only.
+	 */
+	publishAt?: string | null
+}
+
+function present(value: string | null | undefined): value is string {
+	return typeof value === 'string' && value.trim().length > 0
+}
+
+/**
+ * Map one archive-import item to a v2 route body. Pure: the same item always
+ * yields the same body, and the result is parsed by the route's own schema, so
+ * a body this function returns is one the route accepts.
+ */
+export function toFoundryArticleV2(
+	item: ContentArchiveItem,
+	options: FoundryEmitOptions = {},
+): FoundryArticleV2 {
+	if (item.type !== undefined && item.type !== 'article') {
+		throw new FoundryEmitError('unsupported_type', `only articles are emitted, got ${item.type}`)
+	}
+	if (!present(item.slug)) throw new FoundryEmitError('slug_missing', 'archive item has no slug')
+	if (!present(item.title)) throw new FoundryEmitError('title_missing', 'archive item has no title')
+	if (!present(item.bodyHtml)) {
+		throw new FoundryEmitError('body_html_missing', 'archive item has no rendered bodyHtml')
+	}
+
+	let publishAt: string | undefined
+	if (options.publishAt !== undefined) {
+		publishAt = options.publishAt ?? undefined
+	} else if (typeof item.publishedAt === 'number' && Number.isFinite(item.publishedAt)) {
+		publishAt = new Date(item.publishedAt * 1_000).toISOString()
+	}
+
+	const hero = present(item.heroImageId) ? item.heroImageId.trim() : null
+	const author = present(item.byline) ? item.byline : present(item.authorId) ? item.authorId : null
+	const description = present(item.description)
+		? item.description
+		: present(item.excerpt)
+			? item.excerpt
+			: null
+
+	const body: Record<string, unknown> = {
+		schemaVersion: FOUNDRY_ARTICLE_SCHEMA_VERSION,
+		slug: item.slug,
+		title: item.title,
+		body_html: item.bodyHtml,
+		...(hero
+			? /^https?:\/\//i.test(hero)
+				? { hero_image_url: hero }
+				: { hero_image_key: hero }
+			: {}),
+		...(publishAt ? { publishAt } : {}),
+		...(author ? { author } : {}),
+		...(present(item.primaryCategory) ? { desk: item.primaryCategory } : {}),
+		...(item.tags && item.tags.length > 0 ? { tags: [...item.tags] } : {}),
+		...(description ? { description } : {}),
+		...(item.visibility ? { visibility: item.visibility } : {}),
+		...(present(item.sourceId) ? { adoptSourceId: item.sourceId } : {}),
+	}
+	return FoundryArticleV2Schema.parse(body)
+}
+
+// --- content-emit.json: the whole archive as the exact PUT bodies foundryd sends ---
+
+export const CONTENT_EMIT_SCHEMA_VERSION = 1 as const
+
+/** An item the producer retires (frontmatter `status: archived`): no request is sent. */
+export interface ContentEmitRetireItem {
+	path: string
+	videoId: string | null
+	retire: true
+}
+
+/**
+ * An item to PUT. `request` is the exact PUT body as a JSON STRING, never a
+ * nested object, so re-indenting the envelope cannot change its bytes;
+ * `requestSha256` is the lowercase hex SHA-256 of its UTF-8 bytes, which is the
+ * `request_sha256` the route stores and echoes for that PUT.
+ */
+export interface ContentEmitPutItem {
+	path: string
+	videoId: string | null
+	retire: false
+	requestSha256: string
+	request: string
+}
+
+export type ContentEmitItem = ContentEmitRetireItem | ContentEmitPutItem
+
+export interface ContentEmit {
+	schemaVersion: typeof CONTENT_EMIT_SCHEMA_VERSION
+	app: string
+	sourceSha: string
+	items: ContentEmitItem[]
+}
+
+const APP_ID = /^[a-z0-9][a-z0-9-]{0,63}$/
+const SOURCE_SHA = /^[0-9a-f]{7,64}$/
+
+/** Lowercase hex SHA-256 of a string's UTF-8 bytes (the shared implementation). */
+export { sha256Hex }
+
+function archivePath(item: ContentArchiveItem, index: number): string {
+	const sourceId = item.sourceId
+	const separator = typeof sourceId === 'string' ? sourceId.indexOf(':') : -1
+	if (!sourceId || separator < 1 || separator === sourceId.length - 1) {
+		throw new FoundryEmitError(
+			'source_id_missing',
+			`archive item ${index} has no "<ns>:<relpath>" sourceId`,
+		)
+	}
+	return sourceId.slice(separator + 1)
+}
+
+/**
+ * Build content-emit.json for a WHOLE archive. Every item is either retired
+ * (`metadata.originalStatus === 'archived'`, the compiler's carry of frontmatter
+ * `status: archived`) or carries its exact v2 PUT body. Any item that cannot be
+ * emitted fails the whole build: a partial emit would silently drop articles.
+ */
+export async function buildContentEmit(
+	archive: { items?: ContentArchiveItem[] },
+	options: { app: string; sourceSha: string },
+): Promise<ContentEmit> {
+	if (!APP_ID.test(options.app)) {
+		throw new FoundryEmitError('app_invalid', 'app must be a lowercase id (a-z, 0-9, -)')
+	}
+	if (!SOURCE_SHA.test(options.sourceSha)) {
+		throw new FoundryEmitError('source_sha_invalid', 'sourceSha must be a lowercase hex commit')
+	}
+	if (!Array.isArray(archive.items)) {
+		throw new FoundryEmitError('archive_invalid', 'archive has no items array')
+	}
+	const seen = new Set<string>()
+	const items: ContentEmitItem[] = []
+	for (const [index, item] of archive.items.entries()) {
+		const path = archivePath(item, index)
+		if (seen.has(path)) throw new FoundryEmitError('path_duplicate', `duplicate path ${path}`)
+		seen.add(path)
+		const videoId =
+			typeof item.metadata?.videoId === 'string' && item.metadata.videoId
+				? item.metadata.videoId
+				: null
+		if (item.metadata?.originalStatus === 'archived') {
+			items.push({ path, videoId, retire: true })
+			continue
+		}
+		let request: string
+		try {
+			request = JSON.stringify(toFoundryArticleV2(item))
+		} catch (error) {
+			const detail = error instanceof Error ? error.message : String(error)
+			throw new FoundryEmitError('item_invalid', `${path}: ${detail}`)
+		}
+		items.push({ path, videoId, retire: false, requestSha256: await sha256Hex(request), request })
+	}
+	return {
+		schemaVersion: CONTENT_EMIT_SCHEMA_VERSION,
+		app: options.app,
+		sourceSha: options.sourceSha,
+		items,
+	}
+}

package/src/integration/index.ts

@@ -33,6 +33,10 @@ export default function growthLabsCms(userOptions: CmsIntegrationOptions): Astro
 					pattern: '/api/cms/foundry/articles/[external_id]/unpublish',
 					entrypoint: resolveEntrypoint('../ui/api/foundry/articles/[external_id]/unpublish'),
 				})
+				injectRoute({
+					pattern: '/api/cms/foundry/articles/[external_id]/publish',
+					entrypoint: resolveEntrypoint('../ui/api/foundry/articles/[external_id]/publish'),
+				})
 				// the SPA shell index (SSR, prerender=false)
 				injectRoute({ pattern: base, entrypoint: resolveAstro('../ui/pages/admin.astro') })
 				// the /admin/api/* JSON routes
@@ -270,6 +274,11 @@ export default function growthLabsCms(userOptions: CmsIntegrationOptions): Astro
 					pattern: `${base}/api/surveys/[surveyId]/responses.csv`,
 					entrypoint: resolveEntrypoint('../ui/api/surveys/[surveyId]/responses.csv'),
 				})
+				// Owner-only classification of a written answer (technical/general).
+				injectRoute({
+					pattern: `${base}/api/surveys/[surveyId]/answers/label`,
+					entrypoint: resolveEntrypoint('../ui/api/surveys/[surveyId]/answers/label'),
+				})
 				// Calendar
 				injectRoute({
 					pattern: `${base}/api/calendar`,

package/src/integration/options.ts

@@ -1,3 +1,4 @@
+import { isCanonicalHost } from '@growth-labs/foundry-signing'
 import { z } from 'zod'
 import { SurveyIdSchema } from '../surveys/schema.js'
 
@@ -124,6 +125,17 @@ const surveyResultsSchema = z
 	})
 	.strict()
 
+const surveysOptionsSchema = z
+	.object({
+		// Automatic technical/general labeling of new written survey answers
+		// through the host's LlmDispatch (2026-10-02, packet 08), scheduled off
+		// the survey results request via waitUntil. Off by default: a site
+		// opts in, and only a site that wired the LlmDispatch seam pays for
+		// the background dispatches.
+		autoLabel: z.boolean().default(false),
+	})
+	.default({})
+
 export const cmsIntegrationOptionsSchema = z
 	.object({
 		workspaces: z.array(workspaceSchema).min(1, 'at least one workspace is required'),
@@ -143,6 +155,17 @@ export const cmsIntegrationOptionsSchema = z
 		theme: themeSchema,
 		socialSharing: socialSharingSchema,
 		surveyResults: surveyResultsSchema.optional(),
+		surveys: surveysOptionsSchema,
+		// This publication's canonical host for the Foundry machine route
+		// (/api/cms/foundry/*), e.g. `warfronts.pub`. Declared, the route verifies
+		// only the host-bound foundry-cms-v2 signature on every request and never
+		// the legacy form, whatever the per-request hooks set.
+		foundryCanonicalHost: z
+			.string()
+			.refine(isCanonicalHost, {
+				message: 'foundryCanonicalHost must be a lowercase host with no scheme or port',
+			})
+			.optional(),
 	})
 	.transform((o) => ({ ...o, activeWorkspaceId: o.activeWorkspaceId ?? o.workspaces[0].id }))