nca-ai-cms-astro-plugin 1.1.2 → 1.1.3

package/docs/superpowers/plans/2026-03-24-json-db-import-export.md

@@ -0,0 +1,613 @@
+# JSON Database Import/Export Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Replace the SQLite file-swap upload (which breaks the live DB connection and causes infinite redirect loops) with JSON-based export/import that uses the live `astro:db` connection for normal delete-and-insert operations.
+
+**Architecture:** Two new API endpoints (`/api/db/export` GET, `/api/db/import` POST) that serialize/deserialize the three content tables (SiteSettings, Prompts, ScheduledPosts) as JSON. Import uses replace semantics: delete all existing rows in each table, then insert the imported rows — matching the old file-swap behavior but through the live `astro:db` connection. No file replacement, no connection disruption, no process restart. Sessions are excluded (they're per-instance auth state, so the user stays logged in).
+
+**Tech Stack:** Astro API routes, `astro:db` (existing), `db.batch()` for atomic operations, `node:test` for tests, no new dependencies.
+
+---
+
+## File Structure
+
+| Action | File | Responsibility |
+|--------|------|----------------|
+| Create | `src/services/DbTransferService.ts` | Export all content tables to JSON, import JSON back via delete+insert |
+| Create | `src/services/DbTransferService.test.ts` | Unit tests for validation logic (pure functions, no DB dependency) |
+| Create | `src/api/db/export.ts` | GET endpoint — returns JSON dump |
+| Create | `src/api/db/import.ts` | POST endpoint — accepts JSON, replaces data via DbTransferService |
+
+**Tables included in export/import:**
+- `SiteSettings` (key, value, updatedAt)
+- `Prompts` (id, name, category, promptText, updatedAt)
+- `ScheduledPosts` (id, input, inputType, scheduledDate, status, generatedTitle, generatedDescription, generatedContent, generatedTags, generatedImageData, generatedImageAlt, publishedPath, createdAt)
+
+**Tables excluded:**
+- `Sessions` — per-instance auth tokens, must not be transferred between environments
+
+---
+
+### Task 1: DbTransferService — Validation Logic and Tests
+
+**Files:**
+- Create: `src/services/DbTransferService.ts`
+- Create: `src/services/DbTransferService.test.ts`
+
+- [ ] **Step 1: Write failing tests for validation**
+
+In `src/services/DbTransferService.test.ts`:
+
+```typescript
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { validateImportPayload, type DbTransferPayload } from './DbTransferService.js';
+
+describe('validateImportPayload', () => {
+  it('accepts a valid payload with all three tables', () => {
+    const payload: DbTransferPayload = {
+      version: 1,
+      exportedAt: '2026-03-24T12:00:00.000Z',
+      tables: {
+        siteSettings: [{ key: 'content.branche', value: 'Tech', updatedAt: '2026-03-24T12:00:00.000Z' }],
+        prompts: [],
+        scheduledPosts: [],
+      },
+    };
+    const result = validateImportPayload(payload);
+    assert.equal(result.valid, true);
+    assert.equal(result.errors.length, 0);
+  });
+
+  it('rejects payload without version field', () => {
+    const result = validateImportPayload({ tables: {} } as any);
+    assert.equal(result.valid, false);
+    assert.ok(result.errors.some(e => e.includes('version')));
+  });
+
+  it('rejects payload with unsupported version', () => {
+    const result = validateImportPayload({
+      version: 99,
+      exportedAt: '2026-03-24T12:00:00.000Z',
+      tables: { siteSettings: [], prompts: [], scheduledPosts: [] },
+    });
+    assert.equal(result.valid, false);
+    assert.ok(result.errors.some(e => e.includes('version')));
+  });
+
+  it('rejects payload without tables field', () => {
+    const result = validateImportPayload({ version: 1 } as any);
+    assert.equal(result.valid, false);
+    assert.ok(result.errors.some(e => e.includes('tables')));
+  });
+
+  it('rejects payload with missing table keys', () => {
+    const result = validateImportPayload({
+      version: 1,
+      exportedAt: '2026-03-24T12:00:00.000Z',
+      tables: { siteSettings: [] },
+    } as any);
+    assert.equal(result.valid, false);
+    assert.ok(result.errors.some(e => e.includes('prompts')));
+    assert.ok(result.errors.some(e => e.includes('scheduledPosts')));
+  });
+
+  it('rejects siteSettings row missing required key field', () => {
+    const payload: DbTransferPayload = {
+      version: 1,
+      exportedAt: '2026-03-24T12:00:00.000Z',
+      tables: {
+        siteSettings: [{ value: 'Tech', updatedAt: '2026-03-24T12:00:00.000Z' } as any],
+        prompts: [],
+        scheduledPosts: [],
+      },
+    };
+    const result = validateImportPayload(payload);
+    assert.equal(result.valid, false);
+    assert.ok(result.errors.some(e => e.includes('siteSettings')));
+  });
+
+  it('rejects prompts row missing required id field', () => {
+    const payload: DbTransferPayload = {
+      version: 1,
+      exportedAt: '2026-03-24T12:00:00.000Z',
+      tables: {
+        siteSettings: [],
+        prompts: [{ name: 'test', category: 'c', promptText: 'p', updatedAt: '2026-03-24T12:00:00.000Z' } as any],
+        scheduledPosts: [],
+      },
+    };
+    const result = validateImportPayload(payload);
+    assert.equal(result.valid, false);
+    assert.ok(result.errors.some(e => e.includes('prompts')));
+  });
+
+  it('rejects scheduledPosts row missing required scheduledDate', () => {
+    const payload: DbTransferPayload = {
+      version: 1,
+      exportedAt: '2026-03-24T12:00:00.000Z',
+      tables: {
+        siteSettings: [],
+        prompts: [],
+        scheduledPosts: [{
+          id: '1', input: 'x', inputType: 'text', status: 'pending', createdAt: '2026-03-24T12:00:00.000Z',
+        } as any],
+      },
+    };
+    const result = validateImportPayload(payload);
+    assert.equal(result.valid, false);
+    assert.ok(result.errors.some(e => e.includes('scheduledPosts')));
+  });
+
+  it('accepts payload with empty tables (clears all data)', () => {
+    const payload: DbTransferPayload = {
+      version: 1,
+      exportedAt: '2026-03-24T12:00:00.000Z',
+      tables: {
+        siteSettings: [],
+        prompts: [],
+        scheduledPosts: [],
+      },
+    };
+    const result = validateImportPayload(payload);
+    assert.equal(result.valid, true);
+  });
+});
+```
+
+- [ ] **Step 2: Run tests to verify they fail**
+
+Run: `npx tsx --test src/services/DbTransferService.test.ts`
+Expected: FAIL — `validateImportPayload` does not exist
+
+- [ ] **Step 3: Implement types and validation**
+
+In `src/services/DbTransferService.ts`:
+
+```typescript
+// @ts-ignore - resolved by Astro build pipeline
+import { db, SiteSettings, Prompts, ScheduledPosts } from 'astro:db';
+
+export interface SiteSettingRow {
+  key: string;
+  value: string;
+  updatedAt: string;
+}
+
+export interface PromptRow {
+  id: string;
+  name: string;
+  category: string;
+  promptText: string;
+  updatedAt: string;
+}
+
+export interface ScheduledPostRow {
+  id: string;
+  input: string;
+  inputType: string;
+  scheduledDate: string;
+  status: string;
+  generatedTitle?: string | null;
+  generatedDescription?: string | null;
+  generatedContent?: string | null;
+  generatedTags?: string | null;
+  generatedImageData?: string | null;
+  generatedImageAlt?: string | null;
+  publishedPath?: string | null;
+  createdAt: string;
+}
+
+export interface DbTransferPayload {
+  version: number;
+  exportedAt: string;
+  tables: {
+    siteSettings: SiteSettingRow[];
+    prompts: PromptRow[];
+    scheduledPosts: ScheduledPostRow[];
+  };
+}
+
+export interface ValidationResult {
+  valid: boolean;
+  errors: string[];
+}
+
+const SUPPORTED_VERSIONS = [1];
+
+export function validateImportPayload(payload: unknown): ValidationResult {
+  const errors: string[] = [];
+  const data = payload as Record<string, unknown>;
+
+  if (!data || typeof data !== 'object') {
+    return { valid: false, errors: ['Payload must be a JSON object'] };
+  }
+
+  if (typeof data.version !== 'number' || !SUPPORTED_VERSIONS.includes(data.version)) {
+    errors.push(`Missing or unsupported "version" field (supported: ${SUPPORTED_VERSIONS.join(', ')})`);
+  }
+
+  if (!data.tables || typeof data.tables !== 'object') {
+    errors.push('Missing or invalid "tables" field');
+    return { valid: false, errors };
+  }
+
+  const tables = data.tables as Record<string, unknown>;
+
+  // Require all three table keys to be present as arrays
+  if (!Array.isArray(tables.siteSettings)) {
+    errors.push('Missing or invalid "tables.siteSettings" (must be an array)');
+  }
+  if (!Array.isArray(tables.prompts)) {
+    errors.push('Missing or invalid "tables.prompts" (must be an array)');
+  }
+  if (!Array.isArray(tables.scheduledPosts)) {
+    errors.push('Missing or invalid "tables.scheduledPosts" (must be an array)');
+  }
+
+  // If any table key is missing, return early — row validation won't work
+  if (errors.length > 0) {
+    return { valid: false, errors };
+  }
+
+  // Validate siteSettings rows
+  for (let i = 0; i < (tables.siteSettings as any[]).length; i++) {
+    const row = (tables.siteSettings as any[])[i] as Record<string, unknown>;
+    if (!row || typeof row.key !== 'string' || typeof row.value !== 'string') {
+      errors.push(`siteSettings[${i}]: missing required fields "key" and "value"`);
+    }
+  }
+
+  // Validate prompts rows
+  for (let i = 0; i < (tables.prompts as any[]).length; i++) {
+    const row = (tables.prompts as any[])[i] as Record<string, unknown>;
+    if (!row || typeof row.id !== 'string' || typeof row.name !== 'string' ||
+        typeof row.category !== 'string' || typeof row.promptText !== 'string') {
+      errors.push(`prompts[${i}]: missing required fields "id", "name", "category", "promptText"`);
+    }
+  }
+
+  // Validate scheduledPosts rows (all non-optional columns from schema)
+  for (let i = 0; i < (tables.scheduledPosts as any[]).length; i++) {
+    const row = (tables.scheduledPosts as any[])[i] as Record<string, unknown>;
+    if (!row || typeof row.id !== 'string' || typeof row.input !== 'string' ||
+        typeof row.inputType !== 'string' || typeof row.scheduledDate !== 'string' ||
+        typeof row.status !== 'string' || typeof row.createdAt !== 'string') {
+      errors.push(`scheduledPosts[${i}]: missing required fields "id", "input", "inputType", "scheduledDate", "status", "createdAt"`);
+    }
+  }
+
+  return { valid: errors.length === 0, errors };
+}
+
+export class DbTransferService {
+  async exportAll(): Promise<DbTransferPayload> {
+    const [siteSettings, prompts, scheduledPosts] = await Promise.all([
+      db.select().from(SiteSettings),
+      db.select().from(Prompts),
+      db.select().from(ScheduledPosts),
+    ]);
+
+    return {
+      version: 1,
+      exportedAt: new Date().toISOString(),
+      tables: {
+        siteSettings: siteSettings.map((row: any) => ({
+          key: row.key,
+          value: row.value,
+          updatedAt: row.updatedAt instanceof Date ? row.updatedAt.toISOString() : String(row.updatedAt),
+        })),
+        prompts: prompts.map((row: any) => ({
+          id: row.id,
+          name: row.name,
+          category: row.category,
+          promptText: row.promptText,
+          updatedAt: row.updatedAt instanceof Date ? row.updatedAt.toISOString() : String(row.updatedAt),
+        })),
+        scheduledPosts: scheduledPosts.map((row: any) => ({
+          id: row.id,
+          input: row.input,
+          inputType: row.inputType,
+          scheduledDate: row.scheduledDate instanceof Date ? row.scheduledDate.toISOString() : String(row.scheduledDate),
+          status: row.status,
+          generatedTitle: row.generatedTitle ?? null,
+          generatedDescription: row.generatedDescription ?? null,
+          generatedContent: row.generatedContent ?? null,
+          generatedTags: row.generatedTags ?? null,
+          generatedImageData: row.generatedImageData ?? null,
+          generatedImageAlt: row.generatedImageAlt ?? null,
+          publishedPath: row.publishedPath ?? null,
+          createdAt: row.createdAt instanceof Date ? row.createdAt.toISOString() : String(row.createdAt),
+        })),
+      },
+    };
+  }
+
+  /**
+   * Replace all content data atomically using db.batch().
+   * Deletes all existing rows in each table, then inserts the imported rows.
+   * Sessions table is untouched — user stays logged in.
+   */
+  async importAll(payload: DbTransferPayload): Promise<{ imported: Record<string, number> }> {
+    const { siteSettings, prompts, scheduledPosts } = payload.tables;
+
+    // Build all statements for atomic batch execution
+    const statements: any[] = [];
+
+    // Delete all existing rows from content tables
+    statements.push(db.delete(SiteSettings));
+    statements.push(db.delete(Prompts));
+    statements.push(db.delete(ScheduledPosts));
+
+    // Insert new SiteSettings
+    for (const row of siteSettings) {
+      statements.push(
+        db.insert(SiteSettings).values({
+          key: row.key,
+          value: row.value,
+          updatedAt: new Date(row.updatedAt),
+        })
+      );
+    }
+
+    // Insert new Prompts
+    for (const row of prompts) {
+      statements.push(
+        db.insert(Prompts).values({
+          id: row.id,
+          name: row.name,
+          category: row.category,
+          promptText: row.promptText,
+          updatedAt: new Date(row.updatedAt),
+        })
+      );
+    }
+
+    // Insert new ScheduledPosts
+    for (const row of scheduledPosts) {
+      statements.push(
+        db.insert(ScheduledPosts).values({
+          id: row.id,
+          input: row.input,
+          inputType: row.inputType,
+          scheduledDate: new Date(row.scheduledDate),
+          status: row.status,
+          generatedTitle: row.generatedTitle ?? undefined,
+          generatedDescription: row.generatedDescription ?? undefined,
+          generatedContent: row.generatedContent ?? undefined,
+          generatedTags: row.generatedTags ?? undefined,
+          generatedImageData: row.generatedImageData ?? undefined,
+          generatedImageAlt: row.generatedImageAlt ?? undefined,
+          publishedPath: row.publishedPath ?? undefined,
+          createdAt: new Date(row.createdAt),
+        })
+      );
+    }
+
+    // Execute all statements atomically
+    await db.batch(statements);
+
+    return {
+      imported: {
+        siteSettings: siteSettings.length,
+        prompts: prompts.length,
+        scheduledPosts: scheduledPosts.length,
+      },
+    };
+  }
+}
+```
+
+- [ ] **Step 4: Run tests to verify validation passes**
+
+Run: `npx tsx --test src/services/DbTransferService.test.ts`
+Expected: PASS — all 9 validation tests green
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/services/DbTransferService.ts src/services/DbTransferService.test.ts
+git commit -m "feat: add DbTransferService with JSON export/import and validation"
+```
+
+---
+
+### Task 2: JSON Export Endpoint
+
+**Files:**
+- Create: `src/api/db/export.ts`
+
+- [ ] **Step 1: Write the export endpoint**
+
+In `src/api/db/export.ts`:
+
+```typescript
+import type { APIRoute } from 'astro';
+import { jsonError } from '../_utils';
+import { DbTransferService } from '../../services/DbTransferService.js';
+
+export const GET: APIRoute = async () => {
+  try {
+    const service = new DbTransferService();
+    const payload = await service.exportAll();
+    const json = JSON.stringify(payload, null, 2);
+    const timestamp = new Date().toISOString().replace(/[:.]/g, '-').slice(0, 19);
+
+    return new Response(json, {
+      status: 200,
+      headers: {
+        'Content-Type': 'application/json',
+        'Content-Disposition': `attachment; filename="content-${timestamp}.json"`,
+        'Content-Length': String(Buffer.byteLength(json)),
+      },
+    });
+  } catch {
+    return jsonError('Database export failed', 500);
+  }
+};
+```
+
+- [ ] **Step 2: Commit**
+
+```bash
+git add src/api/db/export.ts
+git commit -m "feat: add GET /api/db/export endpoint for JSON data export"
+```
+
+---
+
+### Task 3: JSON Import Endpoint
+
+**Files:**
+- Create: `src/api/db/import.ts`
+
+- [ ] **Step 1: Write the import endpoint**
+
+In `src/api/db/import.ts`:
+
+```typescript
+import type { APIRoute } from 'astro';
+import { jsonResponse, jsonError } from '../_utils';
+import { DbTransferService, validateImportPayload } from '../../services/DbTransferService.js';
+
+const MAX_IMPORT_SIZE = 50 * 1024 * 1024; // 50 MB
+
+export const POST: APIRoute = async ({ request }) => {
+  try {
+    const contentType = request.headers.get('content-type') || '';
+    if (!contentType.includes('application/json')) {
+      return jsonError('Invalid content type. Use application/json.', 400);
+    }
+
+    const contentLength = Number(request.headers.get('content-length') || 0);
+    if (contentLength > MAX_IMPORT_SIZE) {
+      return jsonError('Payload too large. Maximum 50 MB.', 413);
+    }
+
+    const text = await request.text();
+    if (text.length > MAX_IMPORT_SIZE) {
+      return jsonError('Payload too large. Maximum 50 MB.', 413);
+    }
+
+    let payload: unknown;
+    try {
+      payload = JSON.parse(text);
+    } catch {
+      return jsonError('Invalid JSON.', 400);
+    }
+
+    const validation = validateImportPayload(payload);
+    if (!validation.valid) {
+      return jsonError(`Validation failed: ${validation.errors.join('; ')}`, 400);
+    }
+
+    const service = new DbTransferService();
+    const result = await service.importAll(payload as any);
+
+    return jsonResponse({
+      success: true,
+      imported: result.imported,
+    });
+  } catch {
+    return jsonError('Database import failed', 500);
+  }
+};
+```
+
+- [ ] **Step 2: Commit**
+
+```bash
+git add src/api/db/import.ts
+git commit -m "feat: add POST /api/db/import endpoint for JSON data import"
+```
+
+---
+
+### Task 4: Manual Integration Test
+
+**Files:**
+- No new files — testing against running dev server
+
+- [ ] **Step 1: Start dev server and test the full round-trip**
+
+```bash
+# Terminal 1: start dev server
+npm run dev
+
+# Terminal 2: export current data
+curl -s http://localhost:4321/api/db/export | jq '.tables | keys'
+# Expected: ["prompts", "scheduledPosts", "siteSettings"]
+
+# Save export to file
+curl -s http://localhost:4321/api/db/export > /tmp/db-export.json
+
+# Import it back (should replace without errors)
+curl -X POST http://localhost:4321/api/db/import \
+  -H 'Content-Type: application/json' \
+  -d @/tmp/db-export.json
+# Expected: {"success": true, "imported": {"siteSettings": N, "prompts": N, "scheduledPosts": N}}
+```
+
+- [ ] **Step 2: Verify no redirect loop — session stays valid**
+
+After import, navigate to `/editor` in browser. Confirm:
+- No redirect loop
+- Settings are present and correct
+- Session is still valid (you're still logged in)
+
+- [ ] **Step 3: Test validation errors**
+
+```bash
+# Missing version
+curl -X POST http://localhost:4321/api/db/import \
+  -H 'Content-Type: application/json' \
+  -d '{"tables": {}}'
+# Expected: 400 with validation error about "version"
+
+# Missing table keys
+curl -X POST http://localhost:4321/api/db/import \
+  -H 'Content-Type: application/json' \
+  -d '{"version": 1, "tables": {"siteSettings": []}}'
+# Expected: 400 with validation error about missing "prompts" and "scheduledPosts"
+
+# Invalid JSON
+curl -X POST http://localhost:4321/api/db/import \
+  -H 'Content-Type: application/json' \
+  -d 'not json'
+# Expected: 400 "Invalid JSON"
+```
+
+- [ ] **Step 4: Commit any fixes from integration testing**
+
+```bash
+git add -A
+git commit -m "fix: adjustments from integration testing"
+```
+
+---
+
+### Task 5: Deprecate Old SQLite Upload
+
+**Files:**
+- Modify: `src/api/db/upload.ts:56-60` — add deprecation notice in response
+
+- [ ] **Step 1: Add deprecation message to the SQLite upload response**
+
+In `src/api/db/upload.ts`, update the success response:
+
+```typescript
+return jsonResponse({
+  success: true,
+  size: dbBuffer.length,
+  message: 'Database uploaded. Server restarting...',
+  deprecated: 'Use POST /api/db/import with JSON payload instead. The SQLite file upload causes connection issues and will be removed in a future version.',
+});
+```
+
+- [ ] **Step 2: Commit**
+
+```bash
+git add src/api/db/upload.ts
+git commit -m "chore: add deprecation notice to SQLite file upload endpoint"
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nca-ai-cms-astro-plugin",
-  "version": "1.1.2",
+  "version": "1.1.3",
   "type": "module",
   "exports": {
     ".": "./src/index.ts",

package/src/api/db/export.ts

@@ -0,0 +1,23 @@
+import type { APIRoute } from 'astro';
+import { jsonError } from '../_utils';
+import { DbTransferService } from '../../services/DbTransferService.js';
+
+export const GET: APIRoute = async () => {
+  try {
+    const service = new DbTransferService();
+    const payload = await service.exportAll();
+    const json = JSON.stringify(payload, null, 2);
+    const timestamp = new Date().toISOString().replace(/[:.]/g, '-').slice(0, 19);
+
+    return new Response(json, {
+      status: 200,
+      headers: {
+        'Content-Type': 'application/json',
+        'Content-Disposition': `attachment; filename="content-${timestamp}.json"`,
+        'Content-Length': String(Buffer.byteLength(json)),
+      },
+    });
+  } catch {
+    return jsonError('Database export failed', 500);
+  }
+};

package/src/api/db/import.ts

@@ -0,0 +1,46 @@
+import type { APIRoute } from 'astro';
+import { jsonResponse, jsonError } from '../_utils';
+import { DbTransferService, validateImportPayload } from '../../services/DbTransferService.js';
+
+const MAX_IMPORT_SIZE = 50 * 1024 * 1024; // 50 MB
+
+export const POST: APIRoute = async ({ request }) => {
+  try {
+    const contentType = request.headers.get('content-type') || '';
+    if (!contentType.includes('application/json')) {
+      return jsonError('Invalid content type. Use application/json.', 400);
+    }
+
+    const contentLength = Number(request.headers.get('content-length') || 0);
+    if (contentLength > MAX_IMPORT_SIZE) {
+      return jsonError('Payload too large. Maximum 50 MB.', 413);
+    }
+
+    const text = await request.text();
+    if (text.length > MAX_IMPORT_SIZE) {
+      return jsonError('Payload too large. Maximum 50 MB.', 413);
+    }
+
+    let payload: unknown;
+    try {
+      payload = JSON.parse(text);
+    } catch {
+      return jsonError('Invalid JSON.', 400);
+    }
+
+    const validation = validateImportPayload(payload);
+    if (!validation.valid) {
+      return jsonError(`Validation failed: ${validation.errors.join('; ')}`, 400);
+    }
+
+    const service = new DbTransferService();
+    const result = await service.importAll(payload as any);
+
+    return jsonResponse({
+      success: true,
+      imported: result.imported,
+    });
+  } catch {
+    return jsonError('Database import failed', 500);
+  }
+};