@stacksjs/defaults 0.70.356 → 0.70.357

package/ai/skills/stacks-orm/SKILL.md

@@ -196,6 +196,12 @@ await createUser('Alice', 'alice@example.com') // auto-wrapped
 
 Both `transaction()` and `savepoint()` delegate to `db.transaction()` and `db.savepoint()` from `@stacksjs/database`.
 
+### Transaction executor boundary
+
+Every query that must commit or roll back together must use the callback handle (`tx` or `sp`), including validation reads, pivot writes, and the final readback. Do not mix `Model.find()`, `Model.create()`, instance `update()` / `delete()`, or instance relation calls into a raw query-builder transaction. The model executor is a separate execution surface and is not rebound to the callback handle. On SQLite it may use a separate connection, so it cannot observe an uncommitted row written through `tx`.
+
+`runInTransactionScope()` buffers supported side effects until commit, but it does not rebind model queries. For a transaction-backed custom action, use the model definition as the schema and relationship source of truth, then execute the complete persistence workflow through `tx`. Read the created or updated row through `tx` before returning so a readback failure also rolls back the mutation.
+
 ## Trait Methods (traits/)
 
 ### Taggable (when `traits.taggable: true`)

package/app/Actions/Dashboard/Content/AuthorDestroyAction.ts

@@ -1,7 +1,9 @@
 import type { RequestInstance } from '@stacksjs/types'
 import { Action } from '@stacksjs/actions'
 import { db } from '@stacksjs/database'
+import { transaction } from '@stacksjs/orm'
 import { response } from '@stacksjs/router'
+import { dashboardOperationalError } from '../dashboard-response'
 import { rowExists, rowId, timestamp } from './content-input'
 
 /**
@@ -22,17 +24,29 @@ export default new Action({
     if (!id)
       return response.json({ message: 'A valid author id is required.' }, 422)
 
-    if (!await rowExists('authors', id))
-      return response.json({ message: 'Author not found.' }, 404)
+    try {
+      const deleted = await transaction(async (rawTrx) => {
+        const trx = rawTrx as unknown as typeof db
+        if (!await rowExists('authors', id, trx))
+          return false
 
-    await db
-      .updateTable('posts')
-      .set({ author_id: null, updated_at: timestamp() } as any)
-      .where('author_id', '=', id)
-      .execute()
+        await trx
+          .updateTable('posts')
+          .set({ author_id: null, updated_at: timestamp() } as any)
+          .where('author_id', '=', id)
+          .execute()
 
-    await db.deleteFrom('authors').where('id', '=', id).execute()
+        await trx.deleteFrom('authors').where('id', '=', id).execute()
+        return true
+      })
 
-    return response.json({ message: 'Author deleted.', id })
+      if (!deleted)
+        return response.json({ message: 'Author not found.' }, 404)
+
+      return response.json({ message: 'Author deleted.', id })
+    }
+    catch (error) {
+      return dashboardOperationalError(error, 'Author could not be deleted.', 'AuthorDestroyAction', 500)
+    }
   },
 })

package/app/Actions/Dashboard/Content/AuthorIndexAction.ts

@@ -1,5 +1,6 @@
 import { Action } from '@stacksjs/actions'
 import { db } from '@stacksjs/database'
+import { dashboardOperationalError } from '../dashboard-response'
 
 interface AuthorRow {
   id: number
@@ -30,36 +31,41 @@ export default new Action({
   method: 'GET',
   apiResponse: true,
   async handle() {
-    const [rows, postAuthors] = await Promise.all([
-      db.selectFrom('authors').selectAll().orderBy('created_at', 'desc').execute() as unknown as Promise<AuthorRow[]>,
-      db.selectFrom('posts').select(['author_id']).execute() as unknown as Promise<Array<{ author_id: number | null }>>,
-    ])
+    try {
+      const [rows, postAuthors] = await Promise.all([
+        db.selectFrom('authors').selectAll().orderBy('created_at', 'desc').execute() as unknown as Promise<AuthorRow[]>,
+        db.selectFrom('posts').select(['author_id']).execute() as unknown as Promise<Array<{ author_id: number | null }>>,
+      ])
 
-    const postCounts = new Map<number, number>()
-    for (const post of postAuthors) {
-      if (post.author_id == null)
-        continue
+      const postCounts = new Map<number, number>()
+      for (const post of postAuthors) {
+        if (post.author_id == null)
+          continue
 
-      const id = Number(post.author_id)
-      postCounts.set(id, (postCounts.get(id) || 0) + 1)
-    }
+        const id = Number(post.author_id)
+        postCounts.set(id, (postCounts.get(id) || 0) + 1)
+      }
 
-    const authors = rows.map(row => ({
-      id: Number(row.id),
-      name: String(row.name || ''),
-      email: String(row.email || ''),
-      bio: String(row.bio || ''),
-      avatar: String(row.avatar || ''),
-      postCount: postCounts.get(Number(row.id)) || 0,
-      created_at: row.created_at || null,
-      updated_at: row.updated_at || null,
-    }))
+      const authors = rows.map(row => ({
+        id: Number(row.id),
+        name: String(row.name || ''),
+        email: String(row.email || ''),
+        bio: String(row.bio || ''),
+        avatar: String(row.avatar || ''),
+        postCount: postCounts.get(Number(row.id)) || 0,
+        created_at: row.created_at || null,
+        updated_at: row.updated_at || null,
+      }))
 
-    // Posts whose author no longer exists are not counted: the stat means
-    // "posts reachable from this list", which is what the page's Assigned Posts
-    // tile claims to show.
-    const assignedPostCount = authors.reduce((sum, author) => sum + author.postCount, 0)
+      // Posts whose author no longer exists are not counted: the stat means
+      // "posts reachable from this list", which is what the page's Assigned Posts
+      // tile claims to show.
+      const assignedPostCount = authors.reduce((sum, author) => sum + author.postCount, 0)
 
-    return { authors, assignedPostCount }
+      return { authors, assignedPostCount }
+    }
+    catch (error) {
+      return dashboardOperationalError(error, 'Authors could not be loaded.', 'AuthorIndexAction')
+    }
   },
 })

package/app/Actions/Dashboard/Content/AuthorStoreAction.ts

@@ -1,8 +1,10 @@
 import type { RequestInstance } from '@stacksjs/types'
 import { Action } from '@stacksjs/actions'
 import { db } from '@stacksjs/database'
+import { isUniqueViolation, transaction } from '@stacksjs/orm'
 import { response } from '@stacksjs/router'
 import { randomUUIDv7 } from 'bun'
+import { dashboardOperationalError } from '../dashboard-response'
 import { parseAuthorInput } from './author-input'
 import { findRow, insertedId, timestamp } from './content-input'
 
@@ -25,35 +27,53 @@ export default new Action({
     if ('message' in input)
       return response.json({ message: input.message }, 422)
 
-    const duplicate = await db
-      .selectFrom('authors')
-      .select(['id'])
-      .where('email', '=', input.data.email)
-      .executeTakeFirst()
+    try {
+      const author = await transaction(async (rawTrx) => {
+        const trx = rawTrx as unknown as typeof db
+        const duplicate = await trx
+          .selectFrom('authors')
+          .select(['id'])
+          .where('email', '=', input.data.email)
+          .executeTakeFirst()
 
-    if (duplicate)
-      return response.json({ message: 'An author with that email already exists.' }, 422)
+        if (duplicate)
+          return null
 
-    const now = timestamp()
+        const now = timestamp()
 
-    const result = await db
-      .insertInto('authors')
-      .values({
-        uuid: randomUUIDv7(),
-        name: input.data.name,
-        email: input.data.email,
-        bio: input.data.bio || null,
-        avatar: input.data.avatar || null,
-        created_at: now,
-        updated_at: now,
-      } as any)
-      .executeTakeFirst()
+        const result = await trx
+          .insertInto('authors')
+          .values({
+            uuid: randomUUIDv7(),
+            name: input.data.name,
+            email: input.data.email,
+            bio: input.data.bio || null,
+            avatar: input.data.avatar || null,
+            created_at: now,
+            updated_at: now,
+          } as any)
+          .executeTakeFirst()
 
-    const id = insertedId(result)
+        const id = insertedId(result)
 
-    if (!id)
-      return response.json({ message: 'Could not create author.' }, 500)
+        if (!id)
+          throw new Error('Author insert did not return an id.')
 
-    return response.json(await findRow('authors', id), 201)
+        const created = await findRow('authors', id, trx)
+        if (!created)
+          throw new Error('Created author could not be loaded.')
+        return created
+      })
+
+      if (!author)
+        return response.json({ message: 'An author with that email already exists.' }, 422)
+
+      return response.json(author, 201)
+    }
+    catch (error) {
+      if (isUniqueViolation(error))
+        return response.json({ message: 'An author with that email already exists.' }, 422)
+      return dashboardOperationalError(error, 'Author could not be created.', 'AuthorStoreAction', 500)
+    }
   },
 })

package/app/Actions/Dashboard/Content/AuthorUpdateAction.ts

@@ -1,7 +1,9 @@
 import type { RequestInstance } from '@stacksjs/types'
 import { Action } from '@stacksjs/actions'
 import { db } from '@stacksjs/database'
+import { isUniqueViolation, transaction } from '@stacksjs/orm'
 import { response } from '@stacksjs/router'
+import { dashboardOperationalError } from '../dashboard-response'
 import { parseAuthorInput } from './author-input'
 import { findRow, rowExists, rowId, timestamp } from './content-input'
 
@@ -15,36 +17,56 @@ export default new Action({
     if (!id)
       return response.json({ message: 'A valid author id is required.' }, 422)
 
-    if (!await rowExists('authors', id))
-      return response.json({ message: 'Author not found.' }, 404)
-
     const input = parseAuthorInput(request)
 
     if ('message' in input)
       return response.json({ message: input.message }, 422)
 
-    const duplicate = await db
-      .selectFrom('authors')
-      .select(['id'])
-      .where('email', '=', input.data.email)
-      .where('id', '!=', id)
-      .executeTakeFirst()
-
-    if (duplicate)
-      return response.json({ message: 'An author with that email already exists.' }, 422)
-
-    await db
-      .updateTable('authors')
-      .set({
-        name: input.data.name,
-        email: input.data.email,
-        bio: input.data.bio || null,
-        avatar: input.data.avatar || null,
-        updated_at: timestamp(),
-      } as any)
-      .where('id', '=', id)
-      .execute()
-
-    return response.json(await findRow('authors', id))
+    try {
+      const result = await transaction(async (rawTrx) => {
+        const trx = rawTrx as unknown as typeof db
+        if (!await rowExists('authors', id, trx))
+          return { kind: 'not-found' } as const
+
+        const duplicate = await trx
+          .selectFrom('authors')
+          .select(['id'])
+          .where('email', '=', input.data.email)
+          .where('id', '!=', id)
+          .executeTakeFirst()
+
+        if (duplicate)
+          return { kind: 'duplicate' } as const
+
+        await trx
+          .updateTable('authors')
+          .set({
+            name: input.data.name,
+            email: input.data.email,
+            bio: input.data.bio || null,
+            avatar: input.data.avatar || null,
+            updated_at: timestamp(),
+          } as any)
+          .where('id', '=', id)
+          .execute()
+
+        const author = await findRow('authors', id, trx)
+        if (!author)
+          throw new Error('Updated author could not be loaded.')
+        return { kind: 'updated', author } as const
+      })
+
+      if (result.kind === 'not-found')
+        return response.json({ message: 'Author not found.' }, 404)
+      if (result.kind === 'duplicate')
+        return response.json({ message: 'An author with that email already exists.' }, 422)
+
+      return response.json(result.author)
+    }
+    catch (error) {
+      if (isUniqueViolation(error))
+        return response.json({ message: 'An author with that email already exists.' }, 422)
+      return dashboardOperationalError(error, 'Author could not be updated.', 'AuthorUpdateAction', 500)
+    }
   },
 })

package/app/Actions/Dashboard/Content/CategoryDestroyAction.ts

@@ -1,13 +1,16 @@
 import type { RequestInstance } from '@stacksjs/types'
 import { Action } from '@stacksjs/actions'
+import { db } from '@stacksjs/database'
+import { transaction } from '@stacksjs/orm'
 import { response } from '@stacksjs/router'
+import { dashboardOperationalError } from '../dashboard-response'
 import { rowId } from './content-input'
 
 /**
  * `DELETE /api/dashboard/categories/{id}` — deletes a CMS category.
  *
- * Detaches related posts through the model relation before removing the
- * category so no pivot rows are orphaned.
+ * Detaches related posts through the model-declared pivot before removing the
+ * category, with both writes committed by the same transaction.
  */
 export default new Action({
   name: 'CategoryDestroyAction',
@@ -19,13 +22,29 @@ export default new Action({
     if (!id)
       return response.json({ message: 'A valid category id is required.' }, 422)
 
-    const category = await Category.find(id)
-    if (!category)
-      return response.json({ message: 'Category not found.' }, 404)
+    try {
+      const deleted = await transaction(async (rawTrx) => {
+        const trx = rawTrx as unknown as typeof db
+        const category = await trx.selectFrom('categories').select(['id']).where('id', '=', id).executeTakeFirst()
+        if (!category)
+          return false
 
-    await category.posts().detach()
-    await category.delete()
+        await trx
+          .deleteFrom('categorizable_models')
+          .where('category_id', '=', id)
+          .where('categorizable_type', '=', 'posts')
+          .execute()
+        await trx.deleteFrom('categories').where('id', '=', id).execute()
+        return true
+      })
 
-    return response.json({ message: 'Category deleted.', id })
+      if (!deleted)
+        return response.json({ message: 'Category not found.' }, 404)
+
+      return response.json({ message: 'Category deleted.', id })
+    }
+    catch (error) {
+      return dashboardOperationalError(error, 'Category could not be deleted.', 'CategoryDestroyAction', 500)
+    }
   },
 })

package/app/Actions/Dashboard/Content/CategoryIndexAction.ts

@@ -1,5 +1,6 @@
 import { Action } from '@stacksjs/actions'
 import { db } from '@stacksjs/database'
+import { dashboardOperationalError } from '../dashboard-response'
 
 interface CategoryRow {
   id: number
@@ -29,22 +30,27 @@ export default new Action({
   method: 'GET',
   apiResponse: true,
   async handle() {
-    const rows = await db
-      .selectFrom('categories')
-      .selectAll()
-      .orderBy('created_at', 'desc')
-      .execute() as unknown as CategoryRow[]
+    try {
+      const rows = await db
+        .selectFrom('categories')
+        .selectAll()
+        .orderBy('created_at', 'desc')
+        .execute() as unknown as CategoryRow[]
 
-    const categories = rows.map(row => ({
-      id: Number(row.id),
-      name: String(row.name || ''),
-      slug: String(row.slug || ''),
-      description: String(row.description || ''),
-      is_active: row.is_active == null ? true : Boolean(row.is_active),
-      created_at: row.created_at || null,
-      updated_at: row.updated_at || null,
-    }))
+      const categories = rows.map(row => ({
+        id: Number(row.id),
+        name: String(row.name || ''),
+        slug: String(row.slug || ''),
+        description: String(row.description || ''),
+        is_active: row.is_active == null ? true : Boolean(row.is_active),
+        created_at: row.created_at || null,
+        updated_at: row.updated_at || null,
+      }))
 
-    return { categories }
+      return { categories }
+    }
+    catch (error) {
+      return dashboardOperationalError(error, 'Categories could not be loaded.', 'CategoryIndexAction')
+    }
   },
 })

package/app/Actions/Dashboard/Content/CategoryStoreAction.ts

@@ -1,8 +1,10 @@
 import type { RequestInstance } from '@stacksjs/types'
 import { Action } from '@stacksjs/actions'
 import { db } from '@stacksjs/database'
+import { transaction } from '@stacksjs/orm'
 import { response } from '@stacksjs/router'
 import { randomUUIDv7 } from 'bun'
+import { dashboardOperationalError } from '../dashboard-response'
 import { findRow, insertedId, slugify, str, timestamp } from './content-input'
 
 /**
@@ -26,40 +28,56 @@ export default new Action({
     if (!slug)
       return response.json({ message: 'Slug could not be derived from the name; enter one.' }, 422)
 
-    const duplicate = await db
-      .selectFrom('categories')
-      .select(['id'])
-      .where('slug', '=', slug)
-      .executeTakeFirst()
+    try {
+      const category = await transaction(async (rawTrx) => {
+        const trx = rawTrx as unknown as typeof db
+        const duplicate = await trx
+          .selectFrom('categories')
+          .select(['id'])
+          .where('slug', '=', slug)
+          .executeTakeFirst()
 
-    if (duplicate)
-      return response.json({ message: 'A category with that slug already exists.' }, 422)
+        if (duplicate)
+          return null
 
-    const now = timestamp()
-    const displayOrder = await db
-      .selectFrom('categories')
-      .select(db.fn.max('display_order').as('max_display_order'))
-      .executeTakeFirst()
+        const now = timestamp()
+        const displayOrder = await trx
+          .selectFrom('categories')
+          .select(db.fn.max('display_order').as('max_display_order'))
+          .executeTakeFirst()
 
-    const result = await db
-      .insertInto('categories')
-      .values({
-        uuid: randomUUIDv7(),
-        name,
-        slug,
-        description,
-        is_active: 1,
-        display_order: Number(displayOrder?.max_display_order || 0) + 1,
-        created_at: now,
-        updated_at: now,
-      } as any)
-      .executeTakeFirst()
+        const result = await trx
+          .insertInto('categories')
+          .values({
+            uuid: randomUUIDv7(),
+            name,
+            slug,
+            description,
+            is_active: 1,
+            display_order: Number(displayOrder?.max_display_order || 0) + 1,
+            created_at: now,
+            updated_at: now,
+          } as any)
+          .executeTakeFirst()
 
-    const id = insertedId(result)
+        const id = insertedId(result)
 
-    if (!id)
-      return response.json({ message: 'Could not create category.' }, 500)
+        if (!id)
+          throw new Error('Category insert did not return an id.')
 
-    return response.json(await findRow('categories', id), 201)
+        const created = await findRow('categories', id, trx)
+        if (!created)
+          throw new Error('Created category could not be loaded.')
+        return created
+      })
+
+      if (!category)
+        return response.json({ message: 'A category with that slug already exists.' }, 422)
+
+      return response.json(category, 201)
+    }
+    catch (error) {
+      return dashboardOperationalError(error, 'Category could not be created.', 'CategoryStoreAction', 500)
+    }
   },
 })

package/app/Actions/Dashboard/Content/CommentDestroyAction.ts

@@ -1,7 +1,9 @@
 import type { RequestInstance } from '@stacksjs/types'
 import { Action } from '@stacksjs/actions'
 import { db } from '@stacksjs/database'
+import { transaction } from '@stacksjs/orm'
 import { response } from '@stacksjs/router'
+import { dashboardOperationalError } from '../dashboard-response'
 import { rowExists, rowId } from './content-input'
 
 /**
@@ -20,11 +22,22 @@ export default new Action({
     if (!id)
       return response.json({ message: 'A valid comment id is required.' }, 422)
 
-    if (!await rowExists('comments', id))
-      return response.json({ message: 'Comment not found.' }, 404)
+    try {
+      const deleted = await transaction(async (rawTrx) => {
+        const trx = rawTrx as unknown as typeof db
+        if (!await rowExists('comments', id, trx))
+          return false
+        await trx.deleteFrom('comments').where('id', '=', id).execute()
+        return true
+      })
 
-    await db.deleteFrom('comments').where('id', '=', id).execute()
+      if (!deleted)
+        return response.json({ message: 'Comment not found.' }, 404)
 
-    return response.json({ message: 'Comment deleted.', id })
+      return response.json({ message: 'Comment deleted.', id })
+    }
+    catch (error) {
+      return dashboardOperationalError(error, 'Comment could not be deleted.', 'CommentDestroyAction', 500)
+    }
   },
 })

package/app/Actions/Dashboard/Content/CommentIndexAction.ts

@@ -1,5 +1,6 @@
 import { Action } from '@stacksjs/actions'
 import { db } from '@stacksjs/database'
+import { dashboardOperationalError } from '../dashboard-response'
 import { normalizeCommentStatus } from './comment-input'
 
 interface CommentRow {
@@ -33,24 +34,29 @@ export default new Action({
   method: 'GET',
   apiResponse: true,
   async handle() {
-    const rows = await db
-      .selectFrom('comments')
-      .selectAll()
-      .orderBy('created_at', 'desc')
-      .execute() as unknown as CommentRow[]
+    try {
+      const rows = await db
+        .selectFrom('comments')
+        .selectAll()
+        .orderBy('created_at', 'desc')
+        .execute() as unknown as CommentRow[]
 
-    const comments = rows.map(row => ({
-      id: Number(row.id),
-      author_name: String(row.author_name || ''),
-      author_email: String(row.author_email || ''),
-      content: String(row.content || row.body || ''),
-      post_title: String(row.post_title || ''),
-      status: normalizeCommentStatus(row.status),
-      is_approved: Boolean(row.is_approved),
-      created_at: row.created_at || null,
-      updated_at: row.updated_at || null,
-    }))
+      const comments = rows.map(row => ({
+        id: Number(row.id),
+        author_name: String(row.author_name || ''),
+        author_email: String(row.author_email || ''),
+        content: String(row.content || row.body || ''),
+        post_title: String(row.post_title || ''),
+        status: normalizeCommentStatus(row.status),
+        is_approved: Boolean(row.is_approved),
+        created_at: row.created_at || null,
+        updated_at: row.updated_at || null,
+      }))
 
-    return { comments }
+      return { comments }
+    }
+    catch (error) {
+      return dashboardOperationalError(error, 'Comments could not be loaded.', 'CommentIndexAction')
+    }
   },
 })