@karaoke-cms/create 0.6.3 → 0.9.1

package/README.md

@@ -0,0 +1,76 @@
+# @karaoke-cms/create
+
+Scaffolding tool for karaoke-cms. Creates a complete new project from scratch with a single command.
+
+## Where it belongs
+
+`packages/create/` in the monorepo. Published to npm as `@karaoke-cms/create` and invoked via npm's `create` shorthand:
+
+```bash
+npm create @karaoke-cms@latest
+# or
+npm create @karaoke-cms@latest my-site
+```
+
+This resolves to running `packages/create/src/index.js` via the `create-karaoke-cms` bin entry.
+
+## What it does
+
+Runs an interactive CLI that prompts for project configuration, then generates a complete project directory:
+
+**Prompts:**
+1. Project directory name
+2. Site title
+3. Site URL (for sitemap and OG tags)
+4. Description
+5. Theme (`default`, `minimal`, or `blog`)
+6. Enable Pagefind search? (y/n)
+7. Enable Giscus comments? (y/n) — if yes, prompts for repo, repoId, category, categoryId
+
+**Generated files:**
+```
+my-site/
+  package.json           # deps pinned to same version as create package
+  astro.config.mjs       # site URL, karaoke() integration
+  karaoke.config.ts      # title, description, theme, modules, vault path
+  src/
+    content.config.ts    # makeCollections() wired to vault/
+    env.d.ts             # /// <reference types="@karaoke-cms/astro/client" />
+  tsconfig.json
+  .gitignore
+  .env.default           # KARAOKE_VAULT=./vault/
+  public/
+    _redirects           # Cloudflare Pages 404 config
+  vault/                 # Obsidian vault with sample blog post and doc
+    blog/
+    docs/
+    karaoke-cms/
+      config/
+        collections.yaml
+        menus.yaml
+```
+
+After scaffolding, `git init` + initial commit runs automatically if `git` is available.
+
+## How to use
+
+```bash
+npm create @karaoke-cms@latest
+
+cd my-site
+npm install
+npm run dev     # → http://localhost:4321
+```
+
+Open `my-site/vault/` in Obsidian to write content. Files with `publish: true` in frontmatter appear on the live site.
+
+Zero runtime dependencies — the scaffolder uses Node.js built-ins only.
+
+## How it changes the behavior of the system
+
+The create package is not imported by running sites — it only runs once at project setup time. Its output determines:
+
+- Which version of `@karaoke-cms/astro` and the theme packages are installed (pinned to the same version as the create package, since packages ship in lockstep)
+- The initial `karaoke.config.ts` shape: which theme, which modules, vault location
+- The initial vault structure: two sample posts so the site is not empty on first `dev`
+- Whether search and comments infrastructure is included in `karaoke.config.ts`

package/karaoke-create-vault/.obsidian/workspace.json

@@ -0,0 +1,227 @@
+{
+  "main": {
+    "id": "bf48daa9b3525d37",
+    "type": "split",
+    "children": [
+      {
+        "id": "4d1b0940e2f6130e",
+        "type": "tabs",
+        "children": [
+          {
+            "id": "d663da17c7b12a45",
+            "type": "leaf",
+            "state": {
+              "type": "markdown",
+              "state": {
+                "file": "docs/getting-started.md",
+                "mode": "source",
+                "source": false
+              },
+              "icon": "lucide-file",
+              "title": "getting-started"
+            }
+          },
+          {
+            "id": "52e565c48d7a7c39",
+            "type": "leaf",
+            "state": {
+              "type": "markdown",
+              "state": {
+                "file": "karaoke-cms/manual/configuration.md",
+                "mode": "source",
+                "source": false
+              },
+              "icon": "lucide-file",
+              "title": "configuration"
+            }
+          }
+        ],
+        "currentTab": 1
+      }
+    ],
+    "direction": "vertical"
+  },
+  "left": {
+    "id": "f848878ad9626a8e",
+    "type": "split",
+    "children": [
+      {
+        "id": "ea3061d9ba4255be",
+        "type": "tabs",
+        "children": [
+          {
+            "id": "94f03deca1f3d6ef",
+            "type": "leaf",
+            "state": {
+              "type": "file-explorer",
+              "state": {
+                "sortOrder": "alphabetical",
+                "autoReveal": false
+              },
+              "icon": "lucide-folder-closed",
+              "title": "Files"
+            }
+          },
+          {
+            "id": "b92a29ffd5bd2fcd",
+            "type": "leaf",
+            "state": {
+              "type": "search",
+              "state": {
+                "query": "",
+                "matchingCase": false,
+                "explainSearch": false,
+                "collapseAll": false,
+                "extraContext": false,
+                "sortOrder": "alphabetical"
+              },
+              "icon": "lucide-search",
+              "title": "Search"
+            }
+          },
+          {
+            "id": "2fa9963b38cc204e",
+            "type": "leaf",
+            "state": {
+              "type": "bookmarks",
+              "state": {},
+              "icon": "lucide-bookmark",
+              "title": "Bookmarks"
+            }
+          }
+        ]
+      }
+    ],
+    "direction": "horizontal",
+    "width": 300
+  },
+  "right": {
+    "id": "068d5dd11487213f",
+    "type": "split",
+    "children": [
+      {
+        "id": "b36a87ef12a5b05e",
+        "type": "tabs",
+        "children": [
+          {
+            "id": "5040cbb52c2ed323",
+            "type": "leaf",
+            "state": {
+              "type": "backlink",
+              "state": {
+                "collapseAll": false,
+                "extraContext": false,
+                "sortOrder": "alphabetical",
+                "showSearch": false,
+                "searchQuery": "",
+                "backlinkCollapsed": false,
+                "unlinkedCollapsed": true
+              },
+              "icon": "links-coming-in",
+              "title": "Backlinks"
+            }
+          },
+          {
+            "id": "262dc809ddada450",
+            "type": "leaf",
+            "state": {
+              "type": "outgoing-link",
+              "state": {
+                "linksCollapsed": false,
+                "unlinkedCollapsed": true
+              },
+              "icon": "links-going-out",
+              "title": "Outgoing links"
+            }
+          },
+          {
+            "id": "27e78afa43f86c41",
+            "type": "leaf",
+            "state": {
+              "type": "tag",
+              "state": {
+                "sortOrder": "frequency",
+                "useHierarchy": true,
+                "showSearch": false,
+                "searchQuery": ""
+              },
+              "icon": "lucide-tags",
+              "title": "Tags"
+            }
+          },
+          {
+            "id": "b25127a84b56f576",
+            "type": "leaf",
+            "state": {
+              "type": "all-properties",
+              "state": {
+                "sortOrder": "frequency",
+                "showSearch": false,
+                "searchQuery": ""
+              },
+              "icon": "lucide-archive",
+              "title": "All properties"
+            }
+          },
+          {
+            "id": "9144cec5db6c0b0e",
+            "type": "leaf",
+            "state": {
+              "type": "outline",
+              "state": {
+                "followCursor": false,
+                "showSearch": false,
+                "searchQuery": ""
+              },
+              "icon": "lucide-list",
+              "title": "Outline"
+            }
+          },
+          {
+            "id": "d5b8fda7e074d1fc",
+            "type": "leaf",
+            "state": {
+              "type": "file-properties",
+              "state": {
+                "file": "karaoke-cms/manual/configuration.md"
+              },
+              "icon": "lucide-info",
+              "title": "File properties for configuration"
+            }
+          }
+        ],
+        "currentTab": 5
+      }
+    ],
+    "direction": "horizontal",
+    "width": 300
+  },
+  "left-ribbon": {
+    "hiddenItems": {
+      "switcher:Open quick switcher": false,
+      "graph:Open graph view": false,
+      "canvas:Create new canvas": false,
+      "daily-notes:Open today's daily note": false,
+      "templates:Insert template": false,
+      "command-palette:Open command palette": false,
+      "bases:Create new base": false,
+      "templater-obsidian:Templater": false
+    }
+  },
+  "active": "52e565c48d7a7c39",
+  "lastOpenFiles": [
+    "karaoke-cms/templates/index.md",
+    "karaoke-cms/config/index.md",
+    "karaoke-cms/templates/docs-header.md",
+    "karaoke-cms/templates/blog-header.md",
+    "karaoke-cms/templates/index-by-foldernote.md",
+    "karaoke-cms/manual/content.md",
+    "karaoke-cms/manual/configuration.md",
+    "blog/hello-world.md",
+    "karaoke-cms/templates",
+    "karaoke-cms/index.md",
+    "blog/draft-post.md",
+    "docs/testing.md",
+    "docs/getting-started.md"
+  ]
+}

package/karaoke-create-vault/karaoke-cms/config/index.md

@@ -0,0 +1,14 @@
+---
+title: "Config"
+---
+
+# Config
+
+Configuration files for your karaoke-cms vault.
+
+| File | Purpose |
+|------|---------|
+| `collections.yaml` | Which collections are visible in dev vs production |
+| `menus.yaml` | Site navigation: header menu, footer columns, and their entries |
+
+Edit these files to change what appears on your site and in the navigation. Changes take effect on the next dev server restart or build.

package/karaoke-create-vault/karaoke-cms/config/menus.yaml

@@ -0,0 +1,58 @@
+# menus.yaml — define named menus for your site.
+#
+# Each menu has an orientation (horizontal or vertical) and a list of entries.
+# Entries are sorted by weight (ascending). Submenus are defined by nesting entries.
+#
+# when: collection:name — hide entry when the collection is disabled or has no
+#                         published posts. Omit `when` to always show.
+#
+# If this file is absent, karaoke-cms generates a default main menu (Blog/Docs/Tags)
+# and a default footer menu (RSS) from your active collections.
+
+menus:
+  main:
+    orientation: horizontal
+    entries:
+      - text: Blog
+        href: /blog
+        weight: 10
+        when: collection:blog
+      - text: Docs
+        href: /docs
+        weight: 20
+        when: collection:docs
+      - text: Tags
+        href: /tags
+        weight: 30
+      - text: karaoke-cms
+        href: /karaoke-cms
+        weight: 40
+        when: collection:karaoke-cms
+
+  footer-2:
+    orientation: vertical
+    entries:
+      - text: karaoke-cms
+        href: /karaoke-cms/manual/index
+        weight: 10
+        when: collection:karaoke-cms
+        entries:
+          - text: Manual
+            href: /karaoke-cms/manual/index
+            weight: 10
+            when: collection:karaoke-cms
+          - text: Config
+            href: /karaoke-cms/config/index
+            weight: 20
+            when: collection:karaoke-cms
+          - text: Templates
+            href: /karaoke-cms/templates/index
+            weight: 30
+            when: collection:karaoke-cms
+
+  footer:
+    orientation: vertical
+    entries:
+      - text: RSS
+        href: /rss.xml
+        weight: 10

package/karaoke-create-vault/karaoke-cms/templates/index.md

@@ -0,0 +1,15 @@
+---
+title: "Templates"
+---
+
+# Templates
+
+Obsidian templates for common note types. Use with the [Templater](https://github.com/SilentVoid13/Templater) plugin.
+
+| Template | Use for |
+|----------|---------|
+| `blog-header.md` | New blog posts — sets `title`, `date`, `publish: false` |
+| `docs-header.md` | New documentation pages |
+| `index-by-foldernote.md` | Folder index notes (requires the folder-notes Obsidian plugin) |
+
+In Templater settings, set the template folder to `karaoke-cms/templates`.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@karaoke-cms/create",
   "type": "module",
-  "version": "0.6.3",
+  "version": "0.9.1",
   "description": "Scaffold a new karaoke-cms project",
   "bin": {
     "create-karaoke-cms": "./src/index.js"
@@ -24,6 +24,6 @@
     "vitest": "^4.1.1"
   },
   "scripts": {
-    "test": "vitest run test/templates.test.js"
+    "test": "vitest run test/templates.test.js test/index.test.js"
   }
 }

package/src/index.js

@@ -13,7 +13,7 @@ import { fileURLToPath } from 'url';
 import { spawnSync } from 'child_process';
 import {
   packageJson, astroConfig, karaokeConfig, contentConfig,
-  envDts, tsConfig, gitignore, envDefault, cloudflareRedirects,
+  envDts, tsConfig, gitignore, envDefault, cloudflareRedirects, slugify,
 } from './templates.js';
 
 // ── ANSI helpers ─────────────────────────────────────────────────────────────
@@ -108,9 +108,11 @@ async function main() {
     .replace(/\b\w/g, c => c.toUpperCase());
 
   const title = await ask('Site title', defaultTitle);
-  const siteUrl = await ask('Site URL', 'https://my-site.pages.dev');
   const description = await ask('Description', 'Our team knowledge base.');
-  const theme = await askChoice('Theme', ['default', 'minimal'], 0);
+  const themeChoice = await askChoice('Theme', ['default', 'minimal', 'blog'], 0);
+  const theme = themeChoice === 'default' || themeChoice === 'minimal'
+    ? themeChoice
+    : `@karaoke-cms/theme-${themeChoice}`;
   const search = await askYesNo('Enable search? (Pagefind)', true);
   const commentsEnabled = await askYesNo('Enable comments? (requires Giscus setup)', false);
 
@@ -124,17 +126,18 @@ async function main() {
     comments = { repo, repoId, category, categoryId };
   }
 
-  rl.close();
-
   // ── Scaffold ────────────────────────────────────────────────────────────────
   console.log(`\n  Scaffolding ${BOLD}${dir}${R}...\n`);
 
   mkdirSync(join(targetDir, 'src'), { recursive: true });
   mkdirSync(join(targetDir, 'public'), { recursive: true });
 
+  // siteUrl placeholder — replaced with the real *.pages.dev URL after deploy
+  const siteUrl = 'https://your-site.pages.dev';
+
   // Config and project files from templates
   const files = {
-    'package.json':           packageJson({ name: dir, astroVersion }),
+    'package.json':           packageJson({ name: dir, astroVersion, theme }),
     'astro.config.mjs':       astroConfig({ siteUrl }),
     'karaoke.config.ts':      karaokeConfig({ title, description, theme, search, comments }),
     'src/content.config.ts':  contentConfig(),
@@ -172,12 +175,36 @@ async function main() {
     console.log(`  ${GRAY}  (git init skipped — install git and run it manually)${R}`);
   }
 
-  // ── Done ────────────────────────────────────────────────────────────────────
+  // ── npm install ──────────────────────────────────────────────────────────────
+  console.log(`\n  Installing dependencies...\n`);
+  const installResult = spawnSync('npm', ['install'], { cwd: targetDir, stdio: 'inherit' });
+  if (installResult.status !== 0) {
+    console.log(`  ${GRAY}(install failed — run npm install manually)${R}`);
+  }
+
+  // ── Deploy prompt ────────────────────────────────────────────────────────────
+  const deployNow = await askYesNo('Publish a live preview to Cloudflare Pages now?', false);
+
+  rl.close();
+
+  let liveUrl = null;
+  if (deployNow) {
+    const projectName = `${slugify(dir)}-preview`;
+    liveUrl = await deployToCloudflare(targetDir, projectName);
+  }
+
+  // ── Success screen ───────────────────────────────────────────────────────────
   console.log(`\n${GREEN}✓${R} Done! Created ${BOLD}${dir}/${R}\n`);
-  console.log(`  Next steps:\n`);
-  console.log(`  ${CYAN}cd ${dir}${R}`);
-  console.log(`  ${CYAN}npm install${R}`);
-  console.log(`  ${CYAN}npm run dev${R}    ${GRAY}→ http://localhost:4321${R}\n`);
+  if (liveUrl) {
+    console.log(`  ${BOLD}🎤 Live:${R}      ${liveUrl}`);
+    console.log(`  ${BOLD}💻 Dev:${R}       ${CYAN}cd ${dir} && npm run dev${R}`);
+    console.log(`  ${BOLD}🔄 Redeploy:${R}  ${CYAN}npm run deploy${R}\n`);
+  } else {
+    console.log(`  Next steps:\n`);
+    console.log(`  ${CYAN}cd ${dir}${R}`);
+    console.log(`  ${CYAN}npm run dev${R}    ${GRAY}→ http://localhost:4321${R}`);
+    console.log(`  ${CYAN}npm run deploy${R} ${GRAY}→ publish to Cloudflare Pages${R}\n`);
+  }
   console.log(`  ${GRAY}Open ${BOLD}${dir}/vault/${R}${GRAY} in Obsidian to write content.${R}\n`);
 }
 
@@ -185,3 +212,60 @@ main().catch(err => {
   console.error(`\n${RED}✗${R} ${err.message}`);
   process.exit(1);
 });
+
+// ── Cloudflare Pages deploy ───────────────────────────────────────────────────
+export async function deployToCloudflare(targetDir, projectName) {
+  console.log(`\n  ${BOLD}Deploying to Cloudflare Pages...${R}\n`);
+
+  // 1. Check if logged in
+  const whoami = spawnSync('npx', ['wrangler', 'whoami', '--json'],
+    { cwd: targetDir, encoding: 'utf8' });
+
+  if (whoami.status !== 0 || whoami.stdout.includes('You are not authenticated')) {
+    console.log(`  ${CYAN}Opening Cloudflare login...${R}`);
+    const login = spawnSync('npx', ['wrangler', 'login'],
+      { cwd: targetDir, stdio: 'inherit' });
+    if (login.status !== 0) {
+      console.log(`  ${GRAY}Login cancelled — run 'npm run deploy' when ready.${R}`);
+      return null;
+    }
+  }
+
+  // 2. Build
+  console.log(`  ${CYAN}Building...${R}`);
+  const build = spawnSync('npm', ['run', 'build'],
+    { cwd: targetDir, stdio: 'inherit' });
+  if (build.status !== 0) {
+    console.log(`  ${RED}Build failed — run 'npm run deploy' when ready.${R}`);
+    return null;
+  }
+
+  // 3. Create Pages project — best-effort, ignore failure (project may already exist on re-run)
+  const accountId = process.env.CLOUDFLARE_ACCOUNT_ID;
+  const createArgs = ['wrangler', 'pages', 'project', 'create', projectName,
+    '--production-branch', 'main'];
+  if (accountId) createArgs.push('--account-id', accountId);
+  spawnSync('npx', createArgs, { cwd: targetDir, stdio: 'pipe' });
+
+  // 4. Deploy — stdio: inherit so wrangler output + interactive prompts (e.g. account picker) are visible
+  console.log(`  ${CYAN}Uploading...${R}`);
+  const deployArgs = ['wrangler', 'pages', 'deploy', 'dist',
+    `--project-name=${projectName}`];
+  if (accountId) deployArgs.push('--account-id', accountId);
+  const deploy = spawnSync('npx', deployArgs, { cwd: targetDir, stdio: 'inherit' });
+
+  if (deploy.status !== 0) {
+    console.log(`  ${RED}Deploy failed — run 'npm run deploy' when ready.${R}`);
+    return null;
+  }
+
+  // 5. URL is deterministic — no need to parse wrangler stdout
+  const liveUrl = `https://${projectName}.pages.dev`;
+
+  // 6. Write real URL back to astro.config.mjs (replaces placeholder set during scaffold)
+  const configPath = join(targetDir, 'astro.config.mjs');
+  const configSrc = readFileSync(configPath, 'utf8');
+  writeFileSync(configPath, configSrc.replace('https://your-site.pages.dev', liveUrl));
+
+  return liveUrl;
+}

package/src/templates.js

@@ -5,9 +5,31 @@
  */
 
 /**
- * @param {{ name: string, astroVersion: string }} opts
+ * Compute a Cloudflare-safe project slug from a directory name.
+ * Rules: lowercase, spaces/underscores → hyphens, non-alphanumeric stripped,
+ * truncated to 24 chars (leaves room for the -preview suffix within CF's 28-char limit).
+ * @param {string} dir
  */
-export function packageJson({ name, astroVersion }) {
+export function slugify(dir) {
+  return dir
+    .toLowerCase()
+    .replace(/[\s_]+/g, '-')
+    .replace(/[^a-z0-9-]/g, '')
+    .slice(0, 24);
+}
+
+/**
+ * @param {{ name: string, astroVersion: string, theme?: string }} opts
+ */
+export function packageJson({ name, astroVersion, theme }) {
+  const projectSlug = slugify(name);
+  const dependencies = {
+    '@karaoke-cms/astro': `^${astroVersion}`,
+    astro: '^6.0.0',
+  };
+  if (theme?.startsWith('@')) {
+    dependencies[theme] = `^${astroVersion}`;
+  }
   return JSON.stringify({
     name,
     private: true,
@@ -17,10 +39,11 @@ export function packageJson({ name, astroVersion }) {
       dev: 'astro dev',
       build: 'astro build',
       preview: 'astro preview',
+      deploy: `astro build && npx wrangler pages deploy dist --project-name=${projectSlug}-preview`,
     },
-    dependencies: {
-      '@karaoke-cms/astro': `^${astroVersion}`,
-      astro: '^6.0.0',
+    dependencies,
+    devDependencies: {
+      wrangler: '^3',
     },
   }, null, 2) + '\n';
 }