nca-ai-cms-astro-plugin 1.0.0

package/.claude/settings.local.json

@@ -0,0 +1,9 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(tail:*)",
+      "Bash(npx tsc:*)",
+      "Bash(head:*)"
+    ]
+  }
+}

package/README.md

@@ -0,0 +1,87 @@
+# NCA AI CMS Astro Plugin
+
+An Astro plugin that adds an AI-powered content editor to your site. Generate articles and images with Google Gemini, schedule posts, and manage everything from a built-in editor UI.
+
+**Never code alone** — this is an open source project by [Never Code Alone](https://nevercodealone.de).
+
+## What it does
+
+- Adds an `/editor` page with a React-based UI for content management
+- Generates articles and images using Google Gemini AI
+- Schedules and auto-publishes posts as Markdown files
+- Handles authentication so your host project stays simple
+
+## Setup
+
+### 1. Install
+
+```bash
+npm install nca-ai-cms-astro-plugin
+```
+
+### 2. Add to your Astro config
+
+```ts
+// astro.config.mjs
+import ncaAiCms from 'nca-ai-cms-astro-plugin';
+
+export default defineConfig({
+  integrations: [ncaAiCms()],
+});
+```
+
+### 3. Environment variables
+
+```env
+GOOGLE_GEMINI_API_KEY=your-gemini-api-key
+EDITOR_ADMIN=your-username
+EDITOR_PASSWORD=your-password
+```
+
+| Variable | Required | Description |
+|---|---|---|
+| `GOOGLE_GEMINI_API_KEY` | Yes | Google Gemini API key for content and image generation |
+| `EDITOR_ADMIN` | Yes | Username for editor login |
+| `EDITOR_PASSWORD` | Yes | Password for editor login |
+
+### 4. Requirements
+
+- Astro 5+
+- `@astrojs/db` and `@astrojs/react` integrations
+- Node.js 18+
+
+## Options
+
+```ts
+ncaAiCms({
+  contentPath: 'src/content/blog', // where Markdown files are saved (default: 'nca-ai-cms-content')
+  autoPublish: true,               // auto-publish scheduled posts (default: true in production)
+});
+```
+
+## Routes added
+
+| Route | Description |
+|---|---|
+| `/login` | Login page |
+| `/editor` | Content editor UI |
+| `/api/auth/*` | Authentication endpoints |
+| `/api/generate-content` | Generate article text |
+| `/api/generate-image` | Generate article image |
+| `/api/save` | Save Markdown file |
+| `/api/prompts` | Manage prompt templates |
+| `/api/scheduler` | Manage scheduled posts |
+| `/api/articles/*` | Article operations |
+
+All `/api/*` and `/editor` routes are protected by cookie-based authentication.
+
+## Development
+
+```bash
+npm test          # run tests
+npm run typecheck # check types
+```
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "nca-ai-cms-astro-plugin",
+  "version": "1.0.0",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./services": "./src/services/index.ts",
+    "./domain": "./src/domain/index.ts",
+    "./domain/entities": "./src/domain/entities/index.ts",
+    "./domain/value-objects": "./src/domain/value-objects/index.ts",
+    "./utils": "./src/utils/index.ts",
+    "./api/*": "./src/api/*"
+  },
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit"
+  },
+  "peerDependencies": {
+    "astro": "^5.0.0",
+    "@astrojs/db": "^0.18.0",
+    "@astrojs/react": "^4.0.0",
+    "@google/genai": "^1.0.0",
+    "@google/generative-ai": "^0.24.0",
+    "gray-matter": "^4.0.0",
+    "marked": "^17.0.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "sanitize-html": "^2.0.0",
+    "sharp": "^0.34.0",
+    "turndown": "^7.0.0",
+    "zod": "^3.0.0"
+  },
+  "devDependencies": {
+    "@types/sanitize-html": "^2.16.0",
+    "@types/turndown": "^5.0.6",
+    "astro": "^5.16.4",
+    "@astrojs/db": "^0.18.3",
+    "@astrojs/react": "^4.4.2",
+    "@google/genai": "^1.31.0",
+    "@google/generative-ai": "^0.24.1",
+    "gray-matter": "^4.0.3",
+    "marked": "^17.0.1",
+    "react": "^19.2.1",
+    "react-dom": "^19.2.1",
+    "sanitize-html": "^2.17.0",
+    "sharp": "^0.34.5",
+    "turndown": "^7.2.2",
+    "zod": "^3.25.76",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.15"
+  }
+}

package/src/api/_utils.ts

@@ -0,0 +1,20 @@
+export function jsonResponse(data: unknown, status = 200): Response {
+  return new Response(JSON.stringify(data), {
+    status,
+    headers: { 'Content-Type': 'application/json' },
+  });
+}
+
+export function jsonError(error: unknown, status = 500): Response {
+  const message = error instanceof Error ? error.message : String(error);
+  return new Response(JSON.stringify({ error: message }), {
+    status,
+    headers: { 'Content-Type': 'application/json' },
+  });
+}
+
+export async function parseBody<T = Record<string, unknown>>(
+  request: Request
+): Promise<T> {
+  return request.json() as Promise<T>;
+}

package/src/api/articles/[id]/apply.ts

@@ -0,0 +1,89 @@
+import type { APIRoute } from 'astro';
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import matter from 'gray-matter';
+import {
+  ArticleService,
+  ArticleNotFoundError,
+} from '../../../services/ArticleService';
+import { convertToWebP } from '../../../services/ImageConverter';
+import { contentPath } from 'virtual:nca-ai-cms/config';
+import { jsonResponse, jsonError } from '../../_utils';
+
+interface ApplyRequest {
+  // For text updates
+  title?: string;
+  description?: string;
+  content?: string;
+  tags?: string[];
+  // For image updates
+  imageUrl?: string;
+  imageAlt?: string;
+}
+
+// POST /api/articles/[id]/apply - Save regenerated content or image
+export const POST: APIRoute = async ({ params, request }) => {
+  try {
+    const slug = params.id;
+
+    if (!slug) {
+      return jsonError('Article ID required', 400);
+    }
+
+    const data: ApplyRequest = await request.json();
+    const service = new ArticleService(contentPath);
+
+    // Read existing article
+    const existingArticle = await service.read(slug);
+    if (!existingArticle) {
+      throw new ArticleNotFoundError(slug);
+    }
+
+    // Handle image update if imageUrl is provided
+    if (data.imageUrl) {
+      const heroPath = path.join(existingArticle.folderPath, 'hero.webp');
+
+      console.log('Saving image to:', heroPath);
+      console.log('Image URL length:', data.imageUrl.length);
+
+      // Decode base64 image data and convert to WebP
+      const base64Data = data.imageUrl.replace(/^data:image\/\w+;base64,/, '');
+
+      await convertToWebP(base64Data, heroPath);
+      console.log('Image saved successfully');
+
+      // Update imageAlt if provided
+      if (data.imageAlt) {
+        const indexPath = path.join(existingArticle.folderPath, 'index.md');
+        const fileContent = await fs.readFile(indexPath, 'utf-8');
+        const { data: frontmatter, content } = matter(fileContent);
+
+        frontmatter.imageAlt = data.imageAlt;
+
+        const updatedContent = matter.stringify(content, frontmatter);
+        await fs.writeFile(indexPath, updatedContent);
+      }
+    }
+
+    // Handle text update if content is provided
+    if (data.content || data.title || data.description) {
+      await service.updateContent(slug, {
+        ...(data.title && { title: data.title }),
+        ...(data.description && { description: data.description }),
+        ...(data.content && { content: data.content }),
+      });
+    }
+
+    return jsonResponse({
+      success: true,
+      articleId: existingArticle.articleId,
+    });
+  } catch (error) {
+    if (error instanceof ArticleNotFoundError) {
+      return jsonError(error, 404);
+    }
+
+    console.error('Apply changes error:', error);
+    return jsonError(error);
+  }
+};

package/src/api/articles/[id]/regenerate-image.ts

@@ -0,0 +1,49 @@
+import type { APIRoute } from 'astro';
+import {
+  ArticleService,
+  ArticleNotFoundError,
+} from '../../../services/ArticleService';
+import { ImageGenerator } from '../../../services/ImageGenerator';
+import { getEnvVariable } from '../../../utils/envUtils';
+import { contentPath } from 'virtual:nca-ai-cms/config';
+import { jsonResponse, jsonError } from '../../_utils';
+
+// POST /api/articles/[id]/regenerate-image - Generate new image for article
+// Returns preview of new image URL WITHOUT saving
+export const POST: APIRoute = async ({ params }) => {
+  try {
+    const slug = params.id;
+
+    if (!slug) {
+      return jsonError('Article ID required', 400);
+    }
+
+    // Read existing article to get title for image generation
+    const service = new ArticleService(contentPath);
+    const existingArticle = await service.read(slug);
+
+    if (!existingArticle) {
+      throw new ArticleNotFoundError(slug);
+    }
+
+    // Generate new image using article title
+    const apiKey = getEnvVariable('GOOGLE_GEMINI_API_KEY');
+    const generator = new ImageGenerator({ apiKey });
+    const image = await generator.generate(existingArticle.title);
+
+    return jsonResponse({
+      url: image.url,
+      alt: image.alt,
+      // Include article info for reference
+      articleId: existingArticle.articleId,
+      articleTitle: existingArticle.title,
+    });
+  } catch (error) {
+    if (error instanceof ArticleNotFoundError) {
+      return jsonError(error, 404);
+    }
+
+    console.error('Regenerate image error:', error);
+    return jsonError(error);
+  }
+};

package/src/api/articles/[id]/regenerate-text.ts

@@ -0,0 +1,57 @@
+import type { APIRoute } from 'astro';
+import {
+  ArticleService,
+  ArticleNotFoundError,
+} from '../../../services/ArticleService';
+import { ContentGenerator } from '../../../services/ContentGenerator';
+import { PromptService } from '../../../services/PromptService';
+import { getEnvVariable } from '../../../utils/envUtils';
+import { contentPath } from 'virtual:nca-ai-cms/config';
+import { jsonResponse, jsonError } from '../../_utils';
+
+// POST /api/articles/[id]/regenerate-text - Generate new content for article
+// Returns preview of new content WITHOUT saving
+export const POST: APIRoute = async ({ params }) => {
+  try {
+    const slug = params.id;
+
+    if (!slug) {
+      return jsonError('Article ID required', 400);
+    }
+
+    // Read existing article to get title for regeneration
+    const service = new ArticleService(contentPath);
+    const existingArticle = await service.read(slug);
+
+    if (!existingArticle) {
+      throw new ArticleNotFoundError(slug);
+    }
+
+    // Generate new content using existing title as keywords
+    const apiKey = getEnvVariable('GOOGLE_GEMINI_API_KEY');
+    const promptService = new PromptService();
+    const generator = new ContentGenerator({ apiKey, promptService });
+
+    // Use the existing title as keywords for regeneration
+    const newArticle = await generator.generateFromKeywords(
+      existingArticle.title
+    );
+
+    return jsonResponse({
+      title: newArticle.title,
+      description: newArticle.description,
+      content: newArticle.content,
+      tags: newArticle.tags,
+      // Include original article info for reference
+      originalTitle: existingArticle.title,
+      articleId: existingArticle.articleId,
+    });
+  } catch (error) {
+    if (error instanceof ArticleNotFoundError) {
+      return jsonError(error, 404);
+    }
+
+    console.error('Regenerate text error:', error);
+    return jsonError(error);
+  }
+};

package/src/api/articles/[id].ts

@@ -0,0 +1,53 @@
+import type { APIRoute } from 'astro';
+import {
+  ArticleService,
+  ArticleNotFoundError,
+} from '../../services/ArticleService';
+import { contentPath } from 'virtual:nca-ai-cms/config';
+import { jsonResponse, jsonError } from '../_utils';
+
+// GET /api/articles/[id] - Get article details
+export const GET: APIRoute = async ({ params }) => {
+  try {
+    const slug = params.id;
+
+    if (!slug) {
+      return jsonError('Article ID required', 400);
+    }
+
+    const service = new ArticleService(contentPath);
+    const article = await service.read(slug);
+
+    if (!article) {
+      return jsonError('Article not found', 404);
+    }
+
+    return jsonResponse(article);
+  } catch (error) {
+    console.error('Read error:', error);
+    return jsonError(error);
+  }
+};
+
+// DELETE /api/articles/[id] - Delete an article by slug
+export const DELETE: APIRoute = async ({ params }) => {
+  try {
+    const slug = params.id;
+
+    if (!slug) {
+      return jsonError('Article ID required', 400);
+    }
+
+    const service = new ArticleService(contentPath);
+    await service.delete(slug);
+
+    return jsonResponse({ success: true });
+  } catch (error) {
+    if (error instanceof ArticleNotFoundError) {
+      return jsonError(error, 404);
+    }
+
+    console.error('Delete error:', error);
+    return jsonError(error);
+  }
+};

package/src/api/auth/check.ts

@@ -0,0 +1,6 @@
+import type { APIRoute } from 'astro';
+import { jsonResponse } from '../_utils.js';
+
+export const GET: APIRoute = async () => {
+  return jsonResponse({ authenticated: true });
+};

package/src/api/auth/login.ts

@@ -0,0 +1,43 @@
+import type { APIRoute } from 'astro';
+import { z } from 'zod';
+import { jsonResponse, jsonError } from '../_utils.js';
+import { getEnvVariable } from '../../utils/envUtils.js';
+
+const loginSchema = z.object({
+  username: z.string().min(1),
+  password: z.string().min(1),
+});
+
+export const POST: APIRoute = async ({ request, cookies }) => {
+  let body: unknown;
+  try {
+    body = await request.json();
+  } catch {
+    return jsonError('Invalid JSON', 400);
+  }
+
+  const result = loginSchema.safeParse(body);
+  if (!result.success) {
+    return jsonError('Username and password are required', 400);
+  }
+
+  const { username, password } = result.data;
+  const expectedUsername = getEnvVariable('EDITOR_ADMIN');
+  const expectedPassword = getEnvVariable('EDITOR_PASSWORD');
+
+  if (username !== expectedUsername || password !== expectedPassword) {
+    return jsonError('Invalid credentials', 401);
+  }
+
+  const token = btoa(`${username}:${password}`);
+
+  cookies.set('editor-auth', token, {
+    httpOnly: true,
+    secure: import.meta.env.PROD,
+    sameSite: 'strict',
+    path: '/',
+    maxAge: 60 * 60 * 24, // 24 hours
+  });
+
+  return jsonResponse({ success: true });
+};

package/src/api/auth/logout.ts

@@ -0,0 +1,6 @@
+import type { APIRoute } from 'astro';
+
+export const POST: APIRoute = async ({ cookies, redirect }) => {
+  cookies.delete('editor-auth', { path: '/' });
+  return redirect('/login', 302);
+};

package/src/api/generate-content.ts

@@ -0,0 +1,43 @@
+import type { APIRoute } from 'astro';
+import { z } from 'zod';
+import { ContentGenerator } from '../services/ContentGenerator';
+import { PromptService } from '../services/PromptService';
+import { getEnvVariable } from '../utils/envUtils';
+import { jsonResponse, jsonError } from './_utils';
+
+const GenerateContentSchema = z.object({
+  url: z.string().url().optional(),
+  keywords: z.string().min(1).optional(),
+}).refine((data) => data.url || data.keywords, {
+  message: 'URL or keywords required',
+});
+
+export const POST: APIRoute = async ({ request }) => {
+  try {
+    const body = await request.json();
+    const parsed = GenerateContentSchema.safeParse(body);
+    if (!parsed.success) {
+      return jsonError(parsed.error.errors[0]?.message ?? 'Invalid request', 400);
+    }
+    const { url, keywords } = parsed.data;
+
+    const apiKey = getEnvVariable('GOOGLE_GEMINI_API_KEY');
+    const promptService = new PromptService();
+    const generator = new ContentGenerator({ apiKey, promptService });
+    const article = url
+      ? await generator.generateFromUrl(url)
+      : await generator.generateFromKeywords(keywords!);
+
+    return jsonResponse({
+      title: article.title,
+      description: article.description,
+      content: article.content,
+      filepath: article.filepath,
+      tags: article.tags,
+      date: article.date.toISOString(),
+    });
+  } catch (error) {
+    console.error('Generation error:', error);
+    return jsonError(error);
+  }
+};

package/src/api/generate-image.ts

@@ -0,0 +1,33 @@
+import type { APIRoute } from 'astro';
+import { z } from 'zod';
+import { ImageGenerator } from '../services/ImageGenerator';
+import { getEnvVariable } from '../utils/envUtils';
+import { jsonResponse, jsonError } from './_utils';
+
+const GenerateImageSchema = z.object({
+  title: z.string().min(1, 'Title is required'),
+});
+
+export const POST: APIRoute = async ({ request }) => {
+  try {
+    const body = await request.json();
+    const parsed = GenerateImageSchema.safeParse(body);
+    if (!parsed.success) {
+      return jsonError(parsed.error.errors[0]?.message ?? 'Invalid request', 400);
+    }
+    const { title } = parsed.data;
+
+    const apiKey = getEnvVariable('GOOGLE_GEMINI_API_KEY');
+    const generator = new ImageGenerator({ apiKey });
+    const image = await generator.generate(title);
+
+    return jsonResponse({
+      url: image.url,
+      alt: image.alt,
+      filepath: image.filepath,
+    });
+  } catch (error) {
+    console.error('Image generation error:', error);
+    return jsonError(error);
+  }
+};

package/src/api/prompts.ts

@@ -0,0 +1,45 @@
+import type { APIRoute } from 'astro';
+import { PromptService } from '../services/PromptService';
+import { jsonResponse, jsonError } from './_utils';
+
+const service = new PromptService();
+
+// GET /api/prompts - Get all prompts and settings
+export const GET: APIRoute = async () => {
+  try {
+    const [prompts, settings] = await Promise.all([
+      service.getAllPrompts(),
+      service.getAllSettings(),
+    ]);
+
+    return jsonResponse({
+      prompts,
+      settings,
+    });
+  } catch (error) {
+    console.error('Get prompts error:', error);
+    return jsonError(error);
+  }
+};
+
+// POST /api/prompts - Update a prompt or setting
+export const POST: APIRoute = async ({ request }) => {
+  try {
+    const data = await request.json();
+
+    if (data.type === 'prompt' && data.id && data.promptText !== undefined) {
+      await service.updatePrompt(data.id, data.promptText);
+      return jsonResponse({ success: true, type: 'prompt', id: data.id });
+    }
+
+    if (data.type === 'setting' && data.key && data.value !== undefined) {
+      await service.updateSetting(data.key, data.value);
+      return jsonResponse({ success: true, type: 'setting', key: data.key });
+    }
+
+    return jsonError('Invalid request: missing type, id/key, or value', 400);
+  } catch (error) {
+    console.error('Update prompt error:', error);
+    return jsonError(error);
+  }
+};

package/src/api/save-image.ts

@@ -0,0 +1,38 @@
+import type { APIRoute } from 'astro';
+import path from 'node:path';
+import { z } from 'zod';
+import { convertToWebP } from '../services/ImageConverter';
+import { jsonResponse, jsonError } from './_utils';
+
+const SaveImageSchema = z.object({
+  url: z.string().regex(/^data:image\/\w+;base64,.+$/, 'Invalid image data URL'),
+  folderPath: z.string().min(1, 'folderPath is required'),
+});
+
+export const POST: APIRoute = async ({ request }) => {
+  try {
+    const body = await request.json();
+    const parsed = SaveImageSchema.safeParse(body);
+    if (!parsed.success) {
+      return jsonError(parsed.error.errors[0]?.message ?? 'Invalid request', 400);
+    }
+    const { url, folderPath } = parsed.data;
+
+    // Regex is guaranteed to match since Zod already validated the format
+    const base64Data = url.split(',')[1]!;
+
+    // Save hero.webp in the article folder
+    const filepath = path.join(folderPath, 'hero.webp');
+    const fullPath = path.resolve(process.cwd(), filepath);
+
+    await convertToWebP(base64Data, fullPath);
+
+    return jsonResponse({
+      success: true,
+      filepath: filepath,
+    });
+  } catch (error) {
+    console.error('Image save error:', error);
+    return jsonError(error);
+  }
+};