@beechcms/api 0.6.0-preview.1 → 0.6.0-preview.2

package/src/shared/query-utils.ts

@@ -1,141 +1,141 @@
-// SPDX-License-Identifier: BUSL-1.1
-// Copyright (c) 2024–2026 Flavio De Musso. All rights reserved.
-// See LICENSE in the repository root for license terms.
-
-import type { FilterGroup, FilterType } from '@beechcms/core'
-
-/** Entry parsata per le risposte API — contratto immutabile (C7). */
-export interface ContentEntry {
-  id: string
-  schema_slug: string
-  slug: string | null
-  status: string
-  data: Record<string, unknown>
-  hasPendingDraft: boolean
-  created_at: number | null
-  updated_at: number | null
-}
-
-export type QueryFilterType = FilterType
-
-export type QueryFilterOperator =
-  | 'eq'
-  | 'gt'
-  | 'gte'
-  | 'lt'
-  | 'lte'
-  | 'contains'
-  | 'is_empty'
-  | 'is_not_empty'
-
-export interface QueryFilterCondition {
-  id?: string
-  op: QueryFilterOperator
-  value: string | number | boolean | null
-}
-
-/** Formato inviato dalla dashboard (usa columnId). */
-export interface QueryFilterGroup {
-  columnId: string
-  label?: string
-  type: QueryFilterType
-  conditions: QueryFilterCondition[]
-}
-
-const QUERY_FILTER_OPERATOR_SET = new Set<QueryFilterOperator>([
-  'eq', 'gt', 'gte', 'lt', 'lte', 'contains', 'is_empty', 'is_not_empty',
-])
-
-function isQueryFilterOperator(value: unknown): value is QueryFilterOperator {
-  return typeof value === 'string' && QUERY_FILTER_OPERATOR_SET.has(value as QueryFilterOperator)
-}
-
-export function cleanStr(val: unknown): string | null {
-  return (typeof val === 'string' && val.trim()) || null
-}
-
-export function safeParseJson(data: unknown): Record<string, unknown> {
-  const cleaned = cleanStr(data)
-  if (!cleaned) return {}
-  try {
-    const parsed = JSON.parse(cleaned)
-    return typeof parsed === 'object' && parsed !== null && !Array.isArray(parsed)
-      ? (parsed as Record<string, unknown>)
-      : {}
-  } catch {
-    return {}
-  }
-}
-
-export function parsePositiveInt(value: string | undefined, fallback: number): number {
-  if (!value) return fallback
-  const parsed = Number.parseInt(value, 10)
-  if (Number.isNaN(parsed) || parsed < 1) return fallback
-  return parsed
-}
-
-function parseCondition(cond: unknown): QueryFilterCondition | null {
-  if (!cond || typeof cond !== 'object') return null
-  const candidate = cond as Record<string, unknown>
-  if (!isQueryFilterOperator(candidate.op)) return null
-  const rawValue = candidate.value
-  let parsedValue: QueryFilterCondition['value'] = null
-  if (typeof rawValue === 'string' || typeof rawValue === 'number' || typeof rawValue === 'boolean') {
-    parsedValue = rawValue
-  }
-  return {
-    id: typeof candidate.id === 'string' ? candidate.id : undefined,
-    op: candidate.op,
-    value: parsedValue,
-  }
-}
-
-function parseFilterGroup(group: unknown): QueryFilterGroup | null {
-  if (!group || typeof group !== 'object') return null
-  const { columnId, type, label, conditions: rawConds } = group as Partial<QueryFilterGroup>
-  if (typeof columnId !== 'string' || typeof type !== 'string' || !Array.isArray(rawConds)) {
-    return null
-  }
-  const validConditions: QueryFilterCondition[] = []
-  for (const cond of rawConds) {
-    const parsedCond = parseCondition(cond)
-    if (parsedCond) validConditions.push(parsedCond)
-  }
-  if (validConditions.length === 0) return null
-  return {
-    columnId,
-    label: typeof label === 'string' ? label : undefined,
-    type,
-    conditions: validConditions,
-  }
-}
-
-/** Parse sicuro dei filtri da query-string (formato dashboard con columnId). */
-export function parseQueryFilters(raw: string | undefined): QueryFilterGroup[] {
-  if (!raw) return []
-  let parsed: unknown
-  try {
-    parsed = JSON.parse(raw)
-  } catch {
-    return []
-  }
-  if (!parsed || typeof parsed !== 'object') return []
-  const result: QueryFilterGroup[] = []
-  for (const group of Object.values(parsed as Record<string, unknown>)) {
-    const parsedGroup = parseFilterGroup(group)
-    if (parsedGroup) result.push(parsedGroup)
-  }
-  return result
-}
-
-/**
- * Converte QueryFilterGroup[] (formato dashboard, columnId) in FilterGroup[]
- * compatibile con buildSelectQuery del Botanical Engine.
- */
-export function toEngineFilters(groups: QueryFilterGroup[]): FilterGroup[] {
-  return groups.map((g) => ({
-    column: g.columnId,
-    type: g.type,
-    conditions: g.conditions,
-  }))
-}
+// SPDX-License-Identifier: BUSL-1.1
+// Copyright (c) 2024–2026 Flavio De Musso. All rights reserved.
+// See LICENSE in the repository root for license terms.
+
+import type { FilterGroup, FilterType } from '@beechcms/core'
+
+/** Entry parsata per le risposte API — contratto immutabile (C7). */
+export interface ContentEntry {
+  id: string
+  schema_slug: string
+  slug: string | null
+  status: string
+  data: Record<string, unknown>
+  hasPendingDraft: boolean
+  created_at: number | null
+  updated_at: number | null
+}
+
+export type QueryFilterType = FilterType
+
+export type QueryFilterOperator =
+  | 'eq'
+  | 'gt'
+  | 'gte'
+  | 'lt'
+  | 'lte'
+  | 'contains'
+  | 'is_empty'
+  | 'is_not_empty'
+
+export interface QueryFilterCondition {
+  id?: string
+  op: QueryFilterOperator
+  value: string | number | boolean | null
+}
+
+/** Formato inviato dalla dashboard (usa columnId). */
+export interface QueryFilterGroup {
+  columnId: string
+  label?: string
+  type: QueryFilterType
+  conditions: QueryFilterCondition[]
+}
+
+const QUERY_FILTER_OPERATOR_SET = new Set<QueryFilterOperator>([
+  'eq', 'gt', 'gte', 'lt', 'lte', 'contains', 'is_empty', 'is_not_empty',
+])
+
+function isQueryFilterOperator(value: unknown): value is QueryFilterOperator {
+  return typeof value === 'string' && QUERY_FILTER_OPERATOR_SET.has(value as QueryFilterOperator)
+}
+
+export function cleanStr(val: unknown): string | null {
+  return (typeof val === 'string' && val.trim()) || null
+}
+
+export function safeParseJson(data: unknown): Record<string, unknown> {
+  const cleaned = cleanStr(data)
+  if (!cleaned) return {}
+  try {
+    const parsed = JSON.parse(cleaned)
+    return typeof parsed === 'object' && parsed !== null && !Array.isArray(parsed)
+      ? (parsed as Record<string, unknown>)
+      : {}
+  } catch {
+    return {}
+  }
+}
+
+export function parsePositiveInt(value: string | undefined, fallback: number): number {
+  if (!value) return fallback
+  const parsed = Number.parseInt(value, 10)
+  if (Number.isNaN(parsed) || parsed < 1) return fallback
+  return parsed
+}
+
+function parseCondition(cond: unknown): QueryFilterCondition | null {
+  if (!cond || typeof cond !== 'object') return null
+  const candidate = cond as Record<string, unknown>
+  if (!isQueryFilterOperator(candidate.op)) return null
+  const rawValue = candidate.value
+  let parsedValue: QueryFilterCondition['value'] = null
+  if (typeof rawValue === 'string' || typeof rawValue === 'number' || typeof rawValue === 'boolean') {
+    parsedValue = rawValue
+  }
+  return {
+    id: typeof candidate.id === 'string' ? candidate.id : undefined,
+    op: candidate.op,
+    value: parsedValue,
+  }
+}
+
+function parseFilterGroup(group: unknown): QueryFilterGroup | null {
+  if (!group || typeof group !== 'object') return null
+  const { columnId, type, label, conditions: rawConds } = group as Partial<QueryFilterGroup>
+  if (typeof columnId !== 'string' || typeof type !== 'string' || !Array.isArray(rawConds)) {
+    return null
+  }
+  const validConditions: QueryFilterCondition[] = []
+  for (const cond of rawConds) {
+    const parsedCond = parseCondition(cond)
+    if (parsedCond) validConditions.push(parsedCond)
+  }
+  if (validConditions.length === 0) return null
+  return {
+    columnId,
+    label: typeof label === 'string' ? label : undefined,
+    type,
+    conditions: validConditions,
+  }
+}
+
+/** Parse sicuro dei filtri da query-string (formato dashboard con columnId). */
+export function parseQueryFilters(raw: string | undefined): QueryFilterGroup[] {
+  if (!raw) return []
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(raw)
+  } catch {
+    return []
+  }
+  if (!parsed || typeof parsed !== 'object') return []
+  const result: QueryFilterGroup[] = []
+  for (const group of Object.values(parsed as Record<string, unknown>)) {
+    const parsedGroup = parseFilterGroup(group)
+    if (parsedGroup) result.push(parsedGroup)
+  }
+  return result
+}
+
+/**
+ * Converte QueryFilterGroup[] (formato dashboard, columnId) in FilterGroup[]
+ * compatibile con buildSelectQuery del Botanical Engine.
+ */
+export function toEngineFilters(groups: QueryFilterGroup[]): FilterGroup[] {
+  return groups.map((g) => ({
+    column: g.columnId,
+    type: g.type,
+    conditions: g.conditions,
+  }))
+}

package/src/shared/request-utils.ts

@@ -1,26 +1,26 @@
-// SPDX-License-Identifier: BUSL-1.1
-// Copyright (c) 2024–2026 Flavio De Musso. All rights reserved.
-// See LICENSE in the repository root for license terms.
-
-import type { HonoRequest } from "hono"
-
-/** The header Cloudflare sets on every incoming request to the Worker. */
-const CLOUDFLARE_CLIENT_IP_HEADER = "cf-connecting-ip"
-
-/** The fallback value used when the IP header is absent (local dev, unit tests). */
-const UNKNOWN_IP = "unknown"
-
-/**
- * Extracts the real client IP address from a Cloudflare Worker request.
- *
- * Cloudflare injects the cf-connecting-ip header on every request that
- * passes through the edge. In local development (wrangler dev) or in
- * unit tests the header may be absent, in which case the string "unknown"
- * is returned so that rate-limiter keys remain non-empty and safe to use.
- *
- * Never derive security decisions from this value alone; treat it as a
- * best-effort hint for rate-limiting and logging purposes only.
- */
-export function getClientIp(request: HonoRequest): string {
-  return request.raw.headers.get(CLOUDFLARE_CLIENT_IP_HEADER) ?? UNKNOWN_IP
-}
+// SPDX-License-Identifier: BUSL-1.1
+// Copyright (c) 2024–2026 Flavio De Musso. All rights reserved.
+// See LICENSE in the repository root for license terms.
+
+import type { HonoRequest } from "hono"
+
+/** The header Cloudflare sets on every incoming request to the Worker. */
+const CLOUDFLARE_CLIENT_IP_HEADER = "cf-connecting-ip"
+
+/** The fallback value used when the IP header is absent (local dev, unit tests). */
+const UNKNOWN_IP = "unknown"
+
+/**
+ * Extracts the real client IP address from a Cloudflare Worker request.
+ *
+ * Cloudflare injects the cf-connecting-ip header on every request that
+ * passes through the edge. In local development (wrangler dev) or in
+ * unit tests the header may be absent, in which case the string "unknown"
+ * is returned so that rate-limiter keys remain non-empty and safe to use.
+ *
+ * Never derive security decisions from this value alone; treat it as a
+ * best-effort hint for rate-limiting and logging purposes only.
+ */
+export function getClientIp(request: HonoRequest): string {
+  return request.raw.headers.get(CLOUDFLARE_CLIENT_IP_HEADER) ?? UNKNOWN_IP
+}

package/src/shared/schema-mutator.d1.test.ts

@@ -0,0 +1,142 @@
+// SPDX-License-Identifier: BUSL-1.1
+// Copyright (c) 2024–2026 Flavio De Musso. All rights reserved.
+// See LICENSE in the repository root for license terms.
+
+import { describe, it, expect, vi } from 'vitest'
+import { D1SchemaMutator } from './schema-mutator.d1'
+
+function makeMockDb() {
+  const runMock = vi.fn().mockResolvedValue({ success: true })
+  const firstMock = vi.fn().mockResolvedValue(null)
+  const allMock = vi.fn().mockResolvedValue({ results: [] })
+  const bindMock = vi.fn(() => ({ run: runMock, first: firstMock, all: allMock }))
+  const stmt = { bind: bindMock, run: runMock, first: firstMock, all: allMock }
+  const prepareMock = vi.fn(() => stmt)
+  const batchMock = vi.fn().mockResolvedValue([])
+
+  return {
+    db: {
+      prepare: prepareMock,
+      batch: batchMock,
+    } as unknown as D1Database,
+    prepareMock,
+    bindMock,
+    runMock,
+    firstMock,
+    allMock,
+    batchMock,
+  }
+}
+
+describe('D1SchemaMutator', () => {
+  describe('getColumns', () => {
+    it('returns null if table has no columns (empty result)', async () => {
+      const { db, allMock } = makeMockDb()
+      allMock.mockResolvedValueOnce({ results: [] })
+      const mutator = new D1SchemaMutator(db)
+      const cols = await mutator.getColumns('users')
+      expect(cols).toBeNull()
+    })
+
+    it('returns set of column names when columns are found', async () => {
+      const { db, allMock, prepareMock } = makeMockDb()
+      allMock.mockResolvedValueOnce({
+        results: [{ name: 'id' }, { name: 'email' }],
+      })
+      const mutator = new D1SchemaMutator(db)
+      const cols = await mutator.getColumns('users')
+      expect(prepareMock).toHaveBeenCalledWith('PRAGMA table_info(users)')
+      expect(cols).toEqual(new Set(['id', 'email']))
+    })
+
+    it('throws error if table name is unsafe', async () => {
+      const { db } = makeMockDb()
+      const mutator = new D1SchemaMutator(db)
+      await expect(mutator.getColumns('users; DROP TABLE users;')).rejects.toThrow(
+        'Unsafe table name',
+      )
+    })
+  })
+
+  describe('execDdl', () => {
+    it('returns early if statements are empty', async () => {
+      const { db, batchMock } = makeMockDb()
+      const mutator = new D1SchemaMutator(db)
+      await mutator.execDdl([])
+      expect(batchMock).not.toHaveBeenCalled()
+    })
+
+    it('prepares and executes batch DDL statements', async () => {
+      const { db, batchMock, prepareMock } = makeMockDb()
+      const mutator = new D1SchemaMutator(db)
+      await mutator.execDdl(['CREATE TABLE test (id TEXT)', 'CREATE INDEX idx ON test (id)'])
+      expect(prepareMock).toHaveBeenCalledTimes(2)
+      expect(batchMock).toHaveBeenCalled()
+    })
+  })
+
+  describe('dropTable', () => {
+    it('executes DROP TABLE IF EXISTS for a safe identifier', async () => {
+      const { db, prepareMock, runMock } = makeMockDb()
+      const mutator = new D1SchemaMutator(db)
+      await mutator.dropTable('articles')
+      expect(prepareMock).toHaveBeenCalledWith('DROP TABLE IF EXISTS articles')
+      expect(runMock).toHaveBeenCalled()
+    })
+
+    it('throws error on unsafe table name', async () => {
+      const { db } = makeMockDb()
+      const mutator = new D1SchemaMutator(db)
+      await expect(mutator.dropTable('articles; --')).rejects.toThrow('Unsafe identifier')
+    })
+  })
+
+  describe('dropColumn', () => {
+    it('executes ALTER TABLE DROP COLUMN for safe identifiers', async () => {
+      const { db, prepareMock, runMock } = makeMockDb()
+      const mutator = new D1SchemaMutator(db)
+      await mutator.dropColumn('articles', 'title')
+      expect(prepareMock).toHaveBeenCalledWith('ALTER TABLE articles DROP COLUMN title')
+      expect(runMock).toHaveBeenCalled()
+    })
+
+    it('throws error on unsafe column name', async () => {
+      const { db } = makeMockDb()
+      const mutator = new D1SchemaMutator(db)
+      await expect(mutator.dropColumn('articles', 'title;')).rejects.toThrow('Unsafe identifier')
+    })
+  })
+
+  describe('renameColumn', () => {
+    it('executes ALTER TABLE RENAME COLUMN for safe identifiers', async () => {
+      const { db, prepareMock, runMock } = makeMockDb()
+      const mutator = new D1SchemaMutator(db)
+      await mutator.renameColumn('articles', 'old_name', 'new_name')
+      expect(prepareMock).toHaveBeenCalledWith('ALTER TABLE articles RENAME COLUMN old_name TO new_name')
+      expect(runMock).toHaveBeenCalled()
+    })
+
+    it('throws error on unsafe parameters', async () => {
+      const { db } = makeMockDb()
+      const mutator = new D1SchemaMutator(db)
+      await expect(mutator.renameColumn('articles', 'old', 'new --')).rejects.toThrow('Unsafe identifier')
+    })
+  })
+
+  describe('execDestructive', () => {
+    it('returns early if statements are empty', async () => {
+      const { db, batchMock } = makeMockDb()
+      const mutator = new D1SchemaMutator(db)
+      await mutator.execDestructive([])
+      expect(batchMock).not.toHaveBeenCalled()
+    })
+
+    it('prepares and executes batch destructive statements', async () => {
+      const { db, batchMock, prepareMock } = makeMockDb()
+      const mutator = new D1SchemaMutator(db)
+      await mutator.execDestructive(['DROP TABLE test'])
+      expect(prepareMock).toHaveBeenCalledWith('DROP TABLE test')
+      expect(batchMock).toHaveBeenCalled()
+    })
+  })
+})

package/src/shared/schema-mutator.d1.ts

@@ -1,64 +1,64 @@
-// SPDX-License-Identifier: BUSL-1.1
-// Copyright (c) 2024–2026 Flavio De Musso. All rights reserved.
-// See LICENSE in the repository root for license terms.
-
-/// <reference types="@cloudflare/workers-types" />
-import type { ISchemaMutator } from '@beechcms/core'
-
-export class D1SchemaMutator implements ISchemaMutator {
-  constructor(private readonly db: D1Database) {}
-
-  async getColumns(table: string): Promise<Set<string> | null> {
-    // PRAGMA table_info returns rows {cid,name,type,notnull,dflt_value,pk}.
-    // Table name cannot be parameterized in PRAGMA — validate it is a safe identifier.
-    if (!/^[A-Za-z0-9_]+$/.test(table)) throw new Error(`Unsafe table name: ${table}`)
-    const rs = await this.db.prepare(`PRAGMA table_info(${table})`).all<{ name: string }>()
-    const rows = rs.results ?? []
-    if (rows.length === 0) return null // table absent
-    return new Set(rows.map(r => r.name))
-  }
-
-  async execDdl(statements: string[]): Promise<void> {
-    if (statements.length === 0) return
-    // D1 batch is atomic per call; if one statement fails, the rest roll back.
-    await this.db.batch(statements.map(s => this.db.prepare(s)))
-  }
-
-  // --- destructive (sprint 06 — Danger Zone) -------------------------------
-  // These emit IRREVERSIBLE SQL. Identifiers cannot be parameterized in DDL, so
-  // every table/column name is validated against the same `^[A-Za-z0-9_]+$`
-  // guard getColumns already applies before interpolation.
-
-  private static assertIdentifier(name: string): void {
-    if (!/^[A-Za-z0-9_]+$/.test(name)) throw new Error(`Unsafe identifier: ${name}`)
-  }
-
-  async dropTable(table: string): Promise<void> {
-    D1SchemaMutator.assertIdentifier(table)
-    await this.db.prepare(`DROP TABLE IF EXISTS ${table}`).run()
-  }
-
-  async dropColumn(table: string, column: string): Promise<void> {
-    D1SchemaMutator.assertIdentifier(table)
-    D1SchemaMutator.assertIdentifier(column)
-    await this.db.prepare(`ALTER TABLE ${table} DROP COLUMN ${column}`).run()
-  }
-
-  async renameColumn(table: string, from: string, to: string): Promise<void> {
-    D1SchemaMutator.assertIdentifier(table)
-    D1SchemaMutator.assertIdentifier(from)
-    D1SchemaMutator.assertIdentifier(to)
-    await this.db.prepare(`ALTER TABLE ${table} RENAME COLUMN ${from} TO ${to}`).run()
-  }
-
-  async execDestructive(statements: string[]): Promise<void> {
-    if (statements.length === 0) return
-    // The statements come from the core destructive generators
-    // (generateDropTable / generateRetypeColumn / planFtsRebuild), which only
-    // interpolate slugs/aliases already validated by the seed registry
-    // (`^[a-z0-9_]+$`). FTS trigger bodies legitimately contain internal
-    // semicolons (BEGIN … ; END), so we do not split or reject on `;`.
-    // D1 batch is atomic per call; if one statement fails, the rest roll back.
-    await this.db.batch(statements.map(s => this.db.prepare(s)))
-  }
-}
+// SPDX-License-Identifier: BUSL-1.1
+// Copyright (c) 2024–2026 Flavio De Musso. All rights reserved.
+// See LICENSE in the repository root for license terms.
+
+/// <reference types="@cloudflare/workers-types" />
+import type { ISchemaMutator } from '@beechcms/core'
+
+export class D1SchemaMutator implements ISchemaMutator {
+  constructor(private readonly db: D1Database) {}
+
+  async getColumns(table: string): Promise<Set<string> | null> {
+    // PRAGMA table_info returns rows {cid,name,type,notnull,dflt_value,pk}.
+    // Table name cannot be parameterized in PRAGMA — validate it is a safe identifier.
+    if (!/^[A-Za-z0-9_]+$/.test(table)) throw new Error(`Unsafe table name: ${table}`)
+    const rs = await this.db.prepare(`PRAGMA table_info(${table})`).all<{ name: string }>()
+    const rows = rs.results ?? []
+    if (rows.length === 0) return null // table absent
+    return new Set(rows.map(r => r.name))
+  }
+
+  async execDdl(statements: string[]): Promise<void> {
+    if (statements.length === 0) return
+    // D1 batch is atomic per call; if one statement fails, the rest roll back.
+    await this.db.batch(statements.map(s => this.db.prepare(s)))
+  }
+
+  // --- destructive (sprint 06 — Danger Zone) -------------------------------
+  // These emit IRREVERSIBLE SQL. Identifiers cannot be parameterized in DDL, so
+  // every table/column name is validated against the same `^[A-Za-z0-9_]+$`
+  // guard getColumns already applies before interpolation.
+
+  private static assertIdentifier(name: string): void {
+    if (!/^[A-Za-z0-9_]+$/.test(name)) throw new Error(`Unsafe identifier: ${name}`)
+  }
+
+  async dropTable(table: string): Promise<void> {
+    D1SchemaMutator.assertIdentifier(table)
+    await this.db.prepare(`DROP TABLE IF EXISTS ${table}`).run()
+  }
+
+  async dropColumn(table: string, column: string): Promise<void> {
+    D1SchemaMutator.assertIdentifier(table)
+    D1SchemaMutator.assertIdentifier(column)
+    await this.db.prepare(`ALTER TABLE ${table} DROP COLUMN ${column}`).run()
+  }
+
+  async renameColumn(table: string, from: string, to: string): Promise<void> {
+    D1SchemaMutator.assertIdentifier(table)
+    D1SchemaMutator.assertIdentifier(from)
+    D1SchemaMutator.assertIdentifier(to)
+    await this.db.prepare(`ALTER TABLE ${table} RENAME COLUMN ${from} TO ${to}`).run()
+  }
+
+  async execDestructive(statements: string[]): Promise<void> {
+    if (statements.length === 0) return
+    // The statements come from the core destructive generators
+    // (generateDropTable / generateRetypeColumn / planFtsRebuild), which only
+    // interpolate slugs/aliases already validated by the seed registry
+    // (`^[a-z0-9_]+$`). FTS trigger bodies legitimately contain internal
+    // semicolons (BEGIN … ; END), so we do not split or reject on `;`.
+    // D1 batch is atomic per call; if one statement fails, the rest roll back.
+    await this.db.batch(statements.map(s => this.db.prepare(s)))
+  }
+}