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

package/README.md

@@ -85,6 +85,9 @@ ncaAiCms({
 | `/api/prompts` | Manage prompt templates |
 | `/api/scheduler` | Manage scheduled posts |
 | `/api/articles/*` | Article operations |
+| `/api/db/export` | Export settings + prompts as JSON |
+| `/api/db/import` | Import settings + prompts (merge/upsert) |
+| `/api/db/download` | Download raw SQLite database backup |
 
 All `/api/*` and `/editor` routes are protected by cookie-based authentication.
 

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

@@ -0,0 +1,461 @@
+# Settings 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:** Refactor the database import/export into a community-friendly settings transfer system with merge (upsert) semantics and partial import support — no data loss, no connection issues, no restart needed.
+
+**Architecture:** Rework `DbTransferService` to export only shareable configuration (SiteSettings + Prompts, not ScheduledPosts). Flatten the payload (no `tables` wrapper). Import uses upsert semantics (merge into existing data) instead of delete-and-replace. Payload sections are optional so users can import just prompts or just settings. Clean up dead code from removed SQLite upload.
+
+**Tech Stack:** Astro API routes, `astro:db` (existing), vitest, no new dependencies.
+
+---
+
+## File Structure
+
+| Action | File | Responsibility |
+|--------|------|----------------|
+| Modify | `src/services/DbTransferService.ts` | Drop ScheduledPosts, flatten payload, upsert semantics, partial import |
+| Modify | `src/services/DbTransferService.test.ts` | Validation tests for new flat schema with partial import |
+| Modify | `src/services/index.ts` | Drop `ScheduledPostRow` export |
+| Rewrite | `src/api/db/upload.test.ts` | Replace stale tests with single 410 stub test |
+| Delete | `src/utils/dbUploadUtils.ts` | Dead code — upload is a 410 stub |
+| Delete | `src/utils/dbUploadUtils.test.ts` | Tests for dead code |
+| Modify | `src/utils/index.ts` | Remove dbUploadUtils exports |
+| Keep | `src/api/db/export.ts` | No changes (calls `exportAll`) |
+| Keep | `src/api/db/import.ts` | No changes (calls `importAll`) |
+| Keep | `src/api/db/upload.ts` | Already a 410 stub |
+| Keep | `src/api/db/download.ts` | Raw SQLite backup stays |
+
+**What's exported/imported (flat payload):**
+- `siteSettings` — site configuration (content settings, image settings, CTA config)
+- `prompts` — AI prompt templates (community-shareable)
+
+**What's removed:**
+- `scheduledPosts` — instance-specific runtime state
+- `tables` wrapper — payload is now flat (`{ version, siteSettings, prompts }`)
+
+**Import semantics:**
+- **Upsert/merge** — existing rows updated by key/id, new rows inserted, unmentioned rows untouched
+- **Partial** — include only the sections you want to update
+
+**Upsert pattern:** Uses `.get()` + update-or-insert (same pattern as `PromptService.updateSetting` at `src/services/PromptService.ts:124-143`). This is the established codebase convention — `.get()` is used across `SessionService`, `PromptService`, and `SchedulerDBAdapter`.
+
+---
+
+### Task 1: Rewrite DbTransferService — Flat Payload, Upsert, Partial Import
+
+**Files:**
+- Modify: `src/services/DbTransferService.ts`
+- Modify: `src/services/DbTransferService.test.ts`
+
+- [ ] **Step 1: Update validation tests for new schema**
+
+Replace the full contents of `src/services/DbTransferService.test.ts`:
+
+```typescript
+import { describe, it, expect, vi } from 'vitest';
+
+vi.mock('astro:db', () => ({
+  db: {},
+  SiteSettings: {},
+  Prompts: {},
+  eq: vi.fn(),
+}));
+
+import { validateImportPayload, type DbTransferPayload } from './DbTransferService.js';
+
+describe('validateImportPayload', () => {
+  it('accepts a valid payload with both sections', () => {
+    const payload: DbTransferPayload = {
+      version: 1,
+      exportedAt: '2026-03-24T12:00:00.000Z',
+      siteSettings: [{ key: 'content.branche', value: 'Tech', updatedAt: '2026-03-24T12:00:00.000Z' }],
+      prompts: [{ id: 'p1', name: 'Blog', category: 'content', promptText: 'Write...', updatedAt: '2026-03-24T12:00:00.000Z' }],
+    };
+    const result = validateImportPayload(payload);
+    expect(result.valid).toBe(true);
+    expect(result.errors).toHaveLength(0);
+  });
+
+  it('accepts payload with only siteSettings (partial import)', () => {
+    const result = validateImportPayload({
+      version: 1,
+      exportedAt: '2026-03-24T12:00:00.000Z',
+      siteSettings: [{ key: 'k', value: 'v', updatedAt: '2026-03-24T12:00:00.000Z' }],
+    });
+    expect(result.valid).toBe(true);
+  });
+
+  it('accepts payload with only prompts (partial import)', () => {
+    const result = validateImportPayload({
+      version: 1,
+      exportedAt: '2026-03-24T12:00:00.000Z',
+      prompts: [{ id: 'p1', name: 'n', category: 'c', promptText: 't', updatedAt: '2026-03-24T12:00:00.000Z' }],
+    });
+    expect(result.valid).toBe(true);
+  });
+
+  it('rejects payload with neither siteSettings nor prompts', () => {
+    const result = validateImportPayload({ version: 1, exportedAt: '2026-03-24T12:00:00.000Z' });
+    expect(result.valid).toBe(false);
+    expect(result.errors.some(e => e.includes('at least one'))).toBe(true);
+  });
+
+  it('rejects payload without version field', () => {
+    const result = validateImportPayload({ siteSettings: [] });
+    expect(result.valid).toBe(false);
+    expect(result.errors.some(e => e.includes('version'))).toBe(true);
+  });
+
+  it('rejects unsupported version', () => {
+    const result = validateImportPayload({
+      version: 99,
+      exportedAt: '2026-03-24T12:00:00.000Z',
+      siteSettings: [],
+    });
+    expect(result.valid).toBe(false);
+    expect(result.errors.some(e => e.includes('version'))).toBe(true);
+  });
+
+  it('rejects siteSettings row missing key', () => {
+    const result = validateImportPayload({
+      version: 1,
+      exportedAt: '2026-03-24T12:00:00.000Z',
+      siteSettings: [{ value: 'v', updatedAt: '2026-03-24T12:00:00.000Z' }],
+    });
+    expect(result.valid).toBe(false);
+    expect(result.errors.some(e => e.includes('siteSettings'))).toBe(true);
+  });
+
+  it('rejects prompts row missing id', () => {
+    const result = validateImportPayload({
+      version: 1,
+      exportedAt: '2026-03-24T12:00:00.000Z',
+      prompts: [{ name: 'n', category: 'c', promptText: 't', updatedAt: '2026-03-24T12:00:00.000Z' }],
+    });
+    expect(result.valid).toBe(false);
+    expect(result.errors.some(e => e.includes('prompts'))).toBe(true);
+  });
+
+  it('accepts empty arrays (valid but no-op)', () => {
+    const result = validateImportPayload({
+      version: 1,
+      exportedAt: '2026-03-24T12:00:00.000Z',
+      siteSettings: [],
+      prompts: [],
+    });
+    expect(result.valid).toBe(true);
+  });
+
+  it('rejects non-array siteSettings', () => {
+    const result = validateImportPayload({
+      version: 1,
+      exportedAt: '2026-03-24T12:00:00.000Z',
+      siteSettings: 'not an array',
+    });
+    expect(result.valid).toBe(false);
+    expect(result.errors.some(e => e.includes('siteSettings'))).toBe(true);
+  });
+});
+```
+
+- [ ] **Step 2: Run tests to verify they fail**
+
+Run: `npx vitest run src/services/DbTransferService.test.ts`
+Expected: FAIL — old `DbTransferPayload` has `tables` property, not flat `siteSettings`/`prompts`
+
+- [ ] **Step 3: Rewrite DbTransferService**
+
+Replace `src/services/DbTransferService.ts` with:
+
+```typescript
+// @ts-ignore - resolved by Astro build pipeline
+import { db, SiteSettings, Prompts, eq } 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 DbTransferPayload {
+  version: number;
+  exportedAt: string;
+  siteSettings?: SiteSettingRow[];
+  prompts?: PromptRow[];
+}
+
+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(', ')})`);
+  }
+
+  const hasSiteSettings = 'siteSettings' in data;
+  const hasPrompts = 'prompts' in data;
+
+  if (!hasSiteSettings && !hasPrompts) {
+    errors.push('Payload must contain at least one of "siteSettings" or "prompts"');
+    return { valid: false, errors };
+  }
+
+  if (hasSiteSettings) {
+    if (!Array.isArray(data.siteSettings)) {
+      errors.push('"siteSettings" must be an array');
+    } else {
+      for (let i = 0; i < data.siteSettings.length; i++) {
+        const row = data.siteSettings[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"`);
+        }
+      }
+    }
+  }
+
+  if (hasPrompts) {
+    if (!Array.isArray(data.prompts)) {
+      errors.push('"prompts" must be an array');
+    } else {
+      for (let i = 0; i < data.prompts.length; i++) {
+        const row = data.prompts[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"`);
+        }
+      }
+    }
+  }
+
+  return { valid: errors.length === 0, errors };
+}
+
+export class DbTransferService {
+  async exportAll(): Promise<DbTransferPayload> {
+    const [siteSettings, prompts] = await Promise.all([
+      db.select().from(SiteSettings),
+      db.select().from(Prompts),
+    ]);
+
+    return {
+      version: 1,
+      exportedAt: new Date().toISOString(),
+      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),
+      })),
+    };
+  }
+
+  /**
+   * Merge imported data into the live database using upsert semantics.
+   * Only sections present in the payload are touched. Existing data not
+   * referenced in the payload is left untouched.
+   * Uses the same select-then-update-or-insert pattern as PromptService.updateSetting.
+   */
+  async importAll(payload: DbTransferPayload): Promise<{ imported: Record<string, number> }> {
+    const counts: Record<string, number> = {};
+
+    if (payload.siteSettings) {
+      for (const row of payload.siteSettings) {
+        const existing = await db.select().from(SiteSettings)
+          .where(eq(SiteSettings.key, row.key)).get();
+        if (existing) {
+          await db.update(SiteSettings)
+            .set({ value: row.value, updatedAt: new Date(row.updatedAt) })
+            .where(eq(SiteSettings.key, row.key));
+        } else {
+          await db.insert(SiteSettings).values({
+            key: row.key,
+            value: row.value,
+            updatedAt: new Date(row.updatedAt),
+          });
+        }
+      }
+      counts.siteSettings = payload.siteSettings.length;
+    }
+
+    if (payload.prompts) {
+      for (const row of payload.prompts) {
+        const existing = await db.select().from(Prompts)
+          .where(eq(Prompts.id, row.id)).get();
+        if (existing) {
+          await db.update(Prompts)
+            .set({
+              name: row.name,
+              category: row.category,
+              promptText: row.promptText,
+              updatedAt: new Date(row.updatedAt),
+            })
+            .where(eq(Prompts.id, row.id));
+        } else {
+          await db.insert(Prompts).values({
+            id: row.id,
+            name: row.name,
+            category: row.category,
+            promptText: row.promptText,
+            updatedAt: new Date(row.updatedAt),
+          });
+        }
+      }
+      counts.prompts = payload.prompts.length;
+    }
+
+    return { imported: counts };
+  }
+}
+```
+
+- [ ] **Step 4: Run tests to verify they pass**
+
+Run: `npx vitest run src/services/DbTransferService.test.ts`
+Expected: PASS — all 10 tests green
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/services/DbTransferService.ts src/services/DbTransferService.test.ts
+git commit -m "refactor: settings-focused export/import with upsert and partial import"
+```
+
+---
+
+### Task 2: Fix Stale Upload Test and Clean Up Dead Code
+
+**Files:**
+- Rewrite: `src/api/db/upload.test.ts`
+- Delete: `src/utils/dbUploadUtils.ts`
+- Delete: `src/utils/dbUploadUtils.test.ts`
+- Modify: `src/utils/index.ts:8-11` — remove dbUploadUtils exports
+- Modify: `src/services/index.ts:28-36` — remove `ScheduledPostRow`
+
+- [ ] **Step 1: Replace the upload test**
+
+Replace `src/api/db/upload.test.ts` with:
+
+```typescript
+import { describe, it, expect } from 'vitest';
+
+describe('DB Upload API (deprecated)', () => {
+  it('returns 410 Gone with migration instructions', async () => {
+    const { POST } = await import('./upload.js');
+
+    const response = await POST({ request: new Request('http://localhost/api/db/upload', { method: 'POST' }) } as any);
+    const data = await response.json();
+
+    expect(response.status).toBe(410);
+    expect(data.error).toContain('/api/db/import');
+  });
+});
+```
+
+- [ ] **Step 2: Delete dead dbUploadUtils files**
+
+```bash
+rm src/utils/dbUploadUtils.ts src/utils/dbUploadUtils.test.ts
+```
+
+- [ ] **Step 3: Remove dbUploadUtils exports from barrel**
+
+In `src/utils/index.ts`, remove:
+```typescript
+export {
+  validateSqliteHeader,
+  validateFileSize,
+} from "./dbUploadUtils.js";
+```
+
+The file should become:
+```typescript
+export { renderMarkdown } from "./markdown.js";
+export {
+  sanitizeMarkdownHtml,
+  escapeJsonLd,
+  escapeHtml,
+} from "./sanitize.js";
+export { getEnvVariable } from "./envUtils.js";
+```
+
+- [ ] **Step 4: Update services barrel — remove ScheduledPostRow**
+
+In `src/services/index.ts`, replace the DbTransferService export block with:
+
+```typescript
+export {
+  DbTransferService,
+  validateImportPayload,
+  type DbTransferPayload,
+  type ValidationResult,
+  type SiteSettingRow,
+  type PromptRow,
+} from './DbTransferService';
+```
+
+- [ ] **Step 5: Run upload test**
+
+Run: `npx vitest run src/api/db/upload.test.ts`
+Expected: PASS — 1 test green
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add -A
+git commit -m "chore: fix stale upload test, remove dead dbUploadUtils code"
+```
+
+---
+
+### Task 3: Run Full Test Suite and Verify
+
+**Files:**
+- No new files — verification only
+
+- [ ] **Step 1: Run all tests**
+
+Run: `npx vitest run`
+Expected: ALL tests pass, zero failures
+
+- [ ] **Step 2: Check for stale references**
+
+```bash
+grep -r "ScheduledPostRow" src/ --include="*.ts" | grep -v node_modules
+grep -r "dbUploadUtils" src/ --include="*.ts" | grep -v node_modules
+grep -r "tables\." src/services/DbTransferService.ts
+```
+
+Expected: No results for any of these (all old references removed)
+
+- [ ] **Step 3: Commit any fixes if needed**
+
+```bash
+git add -A
+git commit -m "fix: adjustments from verification"
+```

package/package.json

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

package/src/api/db/upload.test.ts

@@ -1,173 +1,13 @@
-import { describe, it, expect, vi, beforeEach } from 'vitest';
-import * as fs from 'fs/promises';
+import { describe, it, expect } from 'vitest';
 
-const mockClose = vi.fn();
-const mockReconnect = vi.fn();
-
-vi.mock('astro:db', () => ({
-  db: {
-    $client: {
-      close: mockClose,
-      reconnect: mockReconnect,
-    },
-  },
-}));
-
-vi.mock('fs/promises', () => ({
-  writeFile: vi.fn().mockResolvedValue(undefined),
-  copyFile: vi.fn().mockResolvedValue(undefined),
-}));
-
-// SQLite file header
-const SQLITE_HEADER = Buffer.from('SQLite format 3\0');
-
-function createSqliteBuffer(size = 4096): Buffer {
-  const buf = Buffer.alloc(size);
-  SQLITE_HEADER.copy(buf);
-  return buf;
-}
-
-function createFormDataRequest(file: Buffer, fieldName = 'database'): Request {
-  const formData = new FormData();
-  formData.append(fieldName, new Blob([file]), 'test.db');
-  return new Request('http://localhost/api/db/upload', {
-    method: 'POST',
-    body: formData,
-  });
-}
-
-function createOctetStreamRequest(file: Buffer): Request {
-  return new Request('http://localhost/api/db/upload', {
-    method: 'POST',
-    headers: { 'Content-Type': 'application/octet-stream' },
-    body: file,
-  });
-}
-
-describe('DB Upload API', () => {
-  beforeEach(() => {
-    vi.clearAllMocks();
-    process.env.ASTRO_DATABASE_FILE = '.astro/content.db';
-  });
-
-  it('accepts a valid SQLite file via multipart/form-data', async () => {
-    const { POST } = await import('./upload.js');
-    const request = createFormDataRequest(createSqliteBuffer());
-
-    const response = await POST({ request } as any);
-    const data = await response.json();
-
-    expect(response.status).toBe(200);
-    expect(data.success).toBe(true);
-    expect(data.size).toBeGreaterThan(0);
-  });
-
-  it('accepts a valid SQLite file via application/octet-stream', async () => {
-    const { POST } = await import('./upload.js');
-    const request = createOctetStreamRequest(createSqliteBuffer());
-
-    const response = await POST({ request } as any);
-    const data = await response.json();
-
-    expect(response.status).toBe(200);
-    expect(data.success).toBe(true);
-  });
-
-  it('rejects non-SQLite files', async () => {
-    const { POST } = await import('./upload.js');
-    const badFile = Buffer.from('not a sqlite file');
-    const request = createFormDataRequest(badFile);
-
-    const response = await POST({ request } as any);
-    const data = await response.json();
-
-    expect(response.status).toBe(400);
-    expect(data.error).toContain('not a SQLite database');
-  });
-
-  it('rejects missing database field', async () => {
-    const { POST } = await import('./upload.js');
-    const formData = new FormData();
-    formData.append('wrongfield', new Blob([createSqliteBuffer()]), 'test.db');
-    const request = new Request('http://localhost/api/db/upload', {
-      method: 'POST',
-      body: formData,
-    });
-
-    const response = await POST({ request } as any);
-    const data = await response.json();
-
-    expect(response.status).toBe(400);
-    expect(data.error).toContain('No database file');
-  });
-
-  it('rejects invalid content type', async () => {
-    const { POST } = await import('./upload.js');
-    const request = new Request('http://localhost/api/db/upload', {
-      method: 'POST',
-      headers: { 'Content-Type': 'text/plain' },
-      body: 'hello',
-    });
-
-    const response = await POST({ request } as any);
-    const data = await response.json();
-
-    expect(response.status).toBe(400);
-    expect(data.error).toContain('Invalid content type');
-  });
-
-  it('creates a backup before writing', async () => {
-    const { POST } = await import('./upload.js');
-    const request = createFormDataRequest(createSqliteBuffer());
-
-    await POST({ request } as any);
-
-    expect(fs.copyFile).toHaveBeenCalled();
-  });
-
-  it('reconnects the DB client after successful upload', async () => {
-    const { POST } = await import('./upload.js');
-    const request = createFormDataRequest(createSqliteBuffer());
-
-    await POST({ request } as any);
-
-    expect(mockClose).toHaveBeenCalledOnce();
-    expect(mockReconnect).toHaveBeenCalledOnce();
-  });
-
-  it('rejects oversized file via multipart/form-data', async () => {
-    const { POST } = await import('./upload.js');
-    const oversized = createSqliteBuffer(50 * 1024 * 1024 + 1);
-    const request = createFormDataRequest(oversized);
-
-    const response = await POST({ request } as any);
-    const data = await response.json();
-
-    expect(response.status).toBe(413);
-    expect(data.error).toContain('too large');
-  });
-
-  it('rejects oversized file via application/octet-stream', async () => {
-    const { POST } = await import('./upload.js');
-    const oversized = createSqliteBuffer(50 * 1024 * 1024 + 1);
-    const request = createOctetStreamRequest(oversized);
-
-    const response = await POST({ request } as any);
-    const data = await response.json();
-
-    expect(response.status).toBe(413);
-    expect(data.error).toContain('too large');
-  });
-
-  it('still succeeds if reconnect is not available', async () => {
+describe('DB Upload API (deprecated)', () => {
+  it('returns 410 Gone with migration instructions', async () => {
     const { POST } = await import('./upload.js');
-    mockClose.mockImplementation(() => { throw new Error('not available'); });
 
-    const request = createFormDataRequest(createSqliteBuffer());
-    const response = await POST({ request } as any);
+    const response = await POST({ request: new Request('http://localhost/api/db/upload', { method: 'POST' }) } as any);
     const data = await response.json();
 
-    expect(response.status).toBe(200);
-    expect(data.success).toBe(true);
+    expect(response.status).toBe(410);
+    expect(data.error).toContain('/api/db/import');
   });
 });