astro-blog-kit 0.1.0

package/README.md

@@ -0,0 +1,298 @@
+# astro-blog-kit
+
+A ready-to-use blog system for Astro with WordPress headless support, optional i18n, multiple layouts, and a comment system.
+
+## Features
+
+- 🚀 **One command setup** — `npx astro-blog-kit init`
+- 📝 **WordPress headless** — connects to WordPress REST API out of the box
+- 🎨 **Multiple layouts** — magazine, grid, and list
+- 💬 **Comment system** — with secure proxy to WordPress
+- 🌍 **Optional i18n** — multi-language support
+- 🎨 **Themeable** — customize colors and fonts via `blogKit()` config
+- 📦 **Zero config** — works without any configuration
+
+---
+
+## Quick Start
+
+### 1. Install
+
+```bash
+npm install astro-blog-kit
+```
+
+### 2. Run the setup wizard
+
+```bash
+npx astro-blog-kit init
+```
+
+The wizard will ask you:
+- WordPress URL
+- Posts per page
+- Default layout
+- Default locale
+- i18n support
+
+And will automatically create:
+- `blog.config.ts` — your blog configuration
+- `src/pages/blog/index.astro` — blog listing page
+- `src/pages/blog/[...slug].astro` — individual post page
+- `src/pages/blog/page/[page].astro` — pagination pages
+- `src/pages/api/comments.ts` — secure comment proxy
+- `.env.example` — environment variables template
+
+### 3. Add the integration
+
+```js
+// astro.config.mjs
+import { defineConfig } from "astro/config";
+import { blogKit } from "astro-blog-kit/integration";
+
+export default defineConfig({
+  integrations: [
+    blogKit({
+      postsPerPage: 5,
+      defaultLayout: "magazine",
+      theme: {
+        accent: "#facc15",
+        fontHeading: "Georgia, serif",
+      },
+    }),
+  ],
+});
+```
+
+### 4. Add your WordPress credentials
+
+Copy `.env.example` to `.env` and fill in your credentials:
+
+```env
+WP_API_URL=https://cms.yourdomain.com
+WP_APP_USER=your-wordpress-username
+WP_APP_PASSWORD=xxxx xxxx xxxx xxxx xxxx xxxx
+```
+
+To generate an Application Password in WordPress:
+1. Go to **Users → Profile**
+2. Scroll to **Application Passwords**
+3. Enter a name (e.g. `astro-blog-kit`) and click **Add New**
+4. Copy the generated password
+
+### 5. Run your site
+
+```bash
+npm run dev
+```
+
+---
+
+## Configuration
+
+### `blog.config.ts`
+
+```ts
+import { defineBlogConfig } from "astro-blog-kit";
+
+export default defineBlogConfig({
+  wpUrl: "https://cms.yourdomain.com",
+  postsPerPage: 5,
+  defaultLayout: "magazine",
+  locale: "en",
+  theme: {
+    accent: "#facc15",
+    background: "#ffffff",
+    text: "#0a0a0a",
+    fontHeading: "Georgia, serif",
+    fontBody: "system-ui, sans-serif",
+  },
+});
+```
+
+### Theme options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `accent` | `string` | `#facc15` | Primary accent color |
+| `background` | `string` | `#ffffff` | Background color |
+| `surface` | `string` | `#f8f8f8` | Surface color (cards, sidebars) |
+| `text` | `string` | `#0a0a0a` | Primary text color |
+| `muted` | `string` | `#6b7280` | Secondary text color |
+| `border` | `string` | `#e5e7eb` | Border color |
+| `fontHeading` | `string` | `Georgia, serif` | Heading font |
+| `fontBody` | `string` | `system-ui, sans-serif` | Body font |
+| `fontMono` | `string` | `monospace` | Monospace font |
+| `containerMax` | `string` | `1200px` | Max container width |
+
+---
+
+## Layouts
+
+### Magazine (default)
+Featured post on the left + smaller posts on the right.
+
+### Grid
+3-column card grid (responsive: 2 cols on tablet, 1 on mobile).
+
+### List
+Horizontal rows with image on the left.
+
+```astro
+<BlogList layout="grid" ... />
+<BlogList layout="list" ... />
+<BlogList layout="magazine" ... />
+```
+
+---
+
+## Components
+
+### `<BlogList>`
+
+```astro
+---
+import { BlogList } from "astro-blog-kit/components";
+---
+<BlogList
+  posts={posts}
+  currentPage={1}
+  totalPages={totalPages}
+  basePath="/blog/page/"
+  blogBase="/blog/"
+  dateLocale="en-US"
+  t={t}
+  locale="en"
+  layout="magazine"
+/>
+```
+
+### `<BlogPost>`
+
+```astro
+---
+import { BlogPost } from "astro-blog-kit/components";
+---
+<BlogPost post={post} t={t} lang="en" />
+```
+
+### `<Comments>`
+
+```astro
+---
+import { Comments } from "astro-blog-kit/components";
+---
+<Comments comments={comments} postId={post.id ?? 0} />
+```
+
+### `<CommentForm>`
+
+```astro
+---
+import { CommentForm } from "astro-blog-kit/components";
+---
+<CommentForm postId={post.id ?? 0} apiRoute="/api/comments" />
+```
+
+---
+
+## Utils
+
+### WordPress client
+
+```ts
+import { createWPClient } from "astro-blog-kit/utils";
+
+const wp = createWPClient("https://cms.yourdomain.com");
+
+// Get paginated posts
+const { posts, total, totalPages } = await wp.getPosts({ perPage: 5, page: 1 });
+
+// Get all posts (for getStaticPaths)
+const posts = await wp.getAllPosts();
+
+// Get single post by slug
+const post = await wp.getPost("my-post-slug");
+
+// Get comments for a post
+const comments = await wp.getComments(postId);
+
+// Get categories
+const categories = await wp.getCategories();
+```
+
+### i18n helpers
+
+```ts
+import { getLang, useTranslations, getBlogBase } from "astro-blog-kit/utils";
+
+const lang = getLang(Astro.url, import.meta.env.BASE_URL, config);
+const t = useTranslations(lang, { en, es });
+const blogBase = getBlogBase(lang, import.meta.env.BASE_URL, config);
+```
+
+### Static paths helpers
+
+```ts
+import { getStaticPathsForPosts, getStaticPathsForPages } from "astro-blog-kit/utils";
+
+// For [...slug].astro
+export const getStaticPaths = () => getStaticPathsForPosts(posts);
+
+// For [page].astro
+export const getStaticPaths = () => getStaticPathsForPages(posts, { postsPerPage: 5 });
+```
+
+---
+
+## Automatic deploys with GitHub Actions
+
+Copy `node_modules/astro-blog-kit/examples/deploy-ftp.yml` to `.github/workflows/deploy.yml`.
+
+Add these secrets to your GitHub repository (**Settings → Secrets**):
+
+| Secret | Description |
+|--------|-------------|
+| `FTP_HOST` | Your server hostname |
+| `FTP_USERNAME` | FTP username |
+| `FTP_PASSWORD` | FTP password |
+| `WP_API_URL` | Your WordPress URL |
+
+The workflow triggers on:
+- Push to `main`
+- WordPress webhook (`wp_update`, `wp_comment`)
+- Manual trigger
+
+To trigger from WordPress, install the **WP Webhooks** plugin and configure it to send a `repository_dispatch` event to GitHub when a post is published or a comment is approved.
+
+---
+
+## i18n Support
+
+```js
+// astro.config.mjs
+blogKit({
+  i18n: {
+    locales: ["en", "es"],
+    defaultLocale: "en",
+  },
+})
+```
+
+With i18n enabled:
+- Default locale: `/blog/my-post`
+- Other locales: `/es/blog/my-post`
+
+---
+
+## Requirements
+
+- Astro v4 or v5
+- Node.js 18+
+- WordPress with REST API enabled
+
+---
+
+## License
+
+MIT

package/cli.ts

@@ -0,0 +1,218 @@
+#!/usr/bin/env node
+// ─────────────────────────────────────────────────────────────
+// astro-blog-kit · cli.ts
+// Comando: npx astro-blog-kit init
+// ─────────────────────────────────────────────────────────────
+
+import * as p from "@clack/prompts";
+import fs from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+// ── Helpers ───────────────────────────────────────────────────
+
+function copyTemplate(
+  templateName: string,
+  destPath: string,
+  replacements: Record<string, string>
+) {
+  const templatePath = path.join(__dirname, "templates", templateName);
+  let content = fs.readFileSync(templatePath, "utf-8");
+
+  for (const [key, value] of Object.entries(replacements)) {
+    content = content.replaceAll(`__${key}__`, value);
+  }
+
+  const dir = path.dirname(destPath);
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+
+  if (fs.existsSync(destPath)) {
+    return false; // ya existe, no sobreescribir
+  }
+
+  fs.writeFileSync(destPath, content, "utf-8");
+  return true;
+}
+
+function log(symbol: string, message: string) {
+  console.log(`${symbol} ${message}`);
+}
+
+// ── Main ──────────────────────────────────────────────────────
+
+async function main() {
+  console.log("");
+  p.intro("astro-blog-kit — Blog setup wizard");
+
+  // ── Preguntas ──────────────────────────────────────────────
+
+  const answers = await p.group(
+    {
+      wpUrl: () =>
+        p.text({
+          message: "WordPress URL",
+          placeholder: "https://cms.tudominio.com",
+          validate: (v) => {
+            if (!v) return "WordPress URL is required";
+            try {
+              new URL(v);
+            } catch {
+              return "Please enter a valid URL";
+            }
+          },
+        }),
+
+      postsPerPage: () =>
+        p.text({
+          message: "Posts per page",
+          placeholder: "5",
+          initialValue: "5",
+          validate: (v) => {
+            const n = Number(v);
+            if (isNaN(n) || n < 1) return "Must be a number greater than 0";
+          },
+        }),
+
+      defaultLayout: () =>
+        p.select({
+          message: "Default layout",
+          options: [
+            { value: "magazine", label: "Magazine — featured post + grid" },
+            { value: "grid", label: "Grid — 3 column card grid" },
+            { value: "list", label: "List — horizontal rows" },
+          ],
+        }),
+
+      locale: () =>
+        p.text({
+          message: "Default locale",
+          placeholder: "en",
+          initialValue: "en",
+        }),
+
+      i18n: () =>
+        p.confirm({
+          message: "Enable i18n (multiple languages)?",
+          initialValue: false,
+        }),
+    },
+    {
+      onCancel: () => {
+        p.cancel("Setup cancelled.");
+        process.exit(0);
+      },
+    }
+  );
+
+  // ── Replacements ──────────────────────────────────────────
+
+  const replacements: Record<string, string> = {
+    WP_URL: answers.wpUrl as string,
+    POSTS_PER_PAGE: answers.postsPerPage as string,
+    DEFAULT_LAYOUT: answers.defaultLayout as string,
+    LOCALE: answers.locale as string,
+  };
+
+  // ── Copia archivos ────────────────────────────────────────
+
+  const cwd = process.cwd();
+  const spinner = p.spinner();
+  spinner.start("Creating blog files...");
+
+  const files = [
+    {
+      template: "blog-config.ts.template",
+      dest: path.join(cwd, "blog.config.ts"),
+    },
+    {
+      template: "blog-index.astro.template",
+      dest: path.join(cwd, "src", "pages", "blog", "index.astro"),
+    },
+    {
+      template: "blog-slug.astro.template",
+      dest: path.join(cwd, "src", "pages", "blog", "[...slug].astro"),
+    },
+    {
+      template: "blog-page.astro.template",
+      dest: path.join(cwd, "src", "pages", "blog", "page", "[page].astro"),
+    },
+    {
+      template: "api-comments.ts.template",
+      dest: path.join(cwd, "src", "pages", "api", "comments.ts"),
+    },
+  ];
+
+  const created: string[] = [];
+  const skipped: string[] = [];
+
+  for (const file of files) {
+    const ok = copyTemplate(file.template, file.dest, replacements);
+    const relativePath = path.relative(cwd, file.dest);
+    if (ok) {
+      created.push(relativePath);
+    } else {
+      skipped.push(relativePath);
+    }
+  }
+
+  spinner.stop("Blog files ready!");
+
+  // ── Crea .env.example ─────────────────────────────────────
+
+  const envExample = path.join(cwd, ".env.example");
+  if (!fs.existsSync(envExample)) {
+    fs.writeFileSync(
+      envExample,
+      [
+        `WP_API_URL=${answers.wpUrl}`,
+        `WP_APP_USER=your-wordpress-username`,
+        `WP_APP_PASSWORD=xxxx xxxx xxxx xxxx xxxx xxxx`,
+      ].join("\n"),
+      "utf-8"
+    );
+    created.push(".env.example");
+  }
+
+  // ── Resumen ───────────────────────────────────────────────
+
+  console.log("");
+
+  if (created.length > 0) {
+    log("✅", "Created:");
+    created.forEach((f) => log("  ", f));
+  }
+
+  if (skipped.length > 0) {
+    console.log("");
+    log("⚠️ ", "Skipped (already exist):");
+    skipped.forEach((f) => log("  ", f));
+  }
+
+  console.log("");
+
+  p.note(
+    [
+      "1. Add your WordPress credentials to .env:",
+      "   WP_APP_USER=your-username",
+      "   WP_APP_PASSWORD=xxxx xxxx xxxx xxxx",
+      "",
+      "2. Add blogKit() to your astro.config.mjs:",
+      "   import { blogKit } from 'astro-blog-kit/integration';",
+      "   integrations: [blogKit()]",
+      "",
+      "3. Run: npm run dev",
+    ].join("\n"),
+    "Next steps"
+  );
+
+  p.outro("Your blog is ready! 🚀");
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});