@karaoke-cms/create 0.6.2 → 0.9.0

package/karaoke-create-vault/karaoke-cms/manual/content.md

@@ -0,0 +1,38 @@
+---
+title: "Writing Content"
+---
+
+# Writing Content
+
+> **Handbook — dev only.**
+
+## Frontmatter fields
+
+```yaml
+---
+title: "My Post"            # required — build fails without it
+publish: true               # required to appear on site (default: false)
+date: 2026-01-15            # optional — YYYY-MM-DD, used for sorting
+author: "Name"              # optional — string or array ["Alice", "Bob"]
+description: "..."          # optional — used in OG meta tags and RSS
+tags: [writing, tutorial]   # optional — enables tag pages at /tags/[tag]
+---
+```
+
+## Privacy model
+
+Every file is **private by default**. `publish: false` (or a missing `publish` field) means the file stays in your vault and never enters the build — not in HTML, not in RSS, not in the sitemap, not in the Pagefind search index.
+
+Only `publish: true` files appear on your site.
+
+## Wikilinks
+
+Use `[[slug]]` syntax to link between notes. karaoke-cms resolves wikilinks automatically:
+
+- `[[blog/hello-world]]` → `/blog/hello-world/`
+- `[[docs/getting-started]]` → `/docs/getting-started/`
+- `[[docs/getting-started|Getting Started]]` → link text "Getting Started"
+
+## AI enrichment (optional)
+
+Run `npx @karaoke-cms/enrich` to auto-generate `tags`, `description`, and `reading_time` for published notes using OpenAI or Anthropic. Skips already-enriched notes via a local cache.

package/karaoke-create-vault/karaoke-cms/manual/deployment.md

@@ -0,0 +1,46 @@
+---
+title: "Deployment"
+---
+
+# Deployment
+
+> **Handbook — dev only.**
+
+## Cloudflare Pages (recommended)
+
+1. Push your project to a GitHub repo
+2. Go to [Cloudflare Pages](https://pages.cloudflare.com) → Create a project → Connect to your repo
+3. Build settings:
+   - **Build command:** `npm run build`
+   - **Build output directory:** `dist`
+   - **Node.js version:** 22
+4. Deploy
+
+On every push to `main`, Cloudflare Pages rebuilds and redeploys automatically.
+
+## GitHub Actions (privacy gate)
+
+The included `deploy.yml` workflow runs `assert-privacy` on every build to verify that no private content leaks into `dist/`. If a private note accidentally gets into the build, the deploy fails before it reaches production.
+
+## Custom domain
+
+In Cloudflare Pages → your project → Custom domains → Add a domain. Update `site:` in `astro.config.mjs` to match:
+
+```js
+export default defineConfig({
+  site: 'https://your-domain.com',
+  // ...
+});
+```
+
+## Environment variables
+
+If you use `@karaoke-cms/enrich` in CI:
+
+| Variable | Purpose |
+|----------|---------|
+| `OPENAI_API_KEY` | Required if `ENRICH_PROVIDER=openai` (default) |
+| `ANTHROPIC_API_KEY` | Required if `ENRICH_PROVIDER=anthropic` |
+| `ENRICH_ENABLED` | Set to `true` to enable AI enrichment in CI |
+| `CLOUDFLARE_API_TOKEN` | For Cloudflare Pages deploy via GitHub Actions |
+| `CLOUDFLARE_ACCOUNT_ID` | For Cloudflare Pages deploy via GitHub Actions |

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

@@ -0,0 +1,41 @@
+---
+title: "Handbook"
+---
+
+# karaoke-cms Handbook
+
+> **Handbook — dev only.** This section is visible at `/karaoke-cms` in dev mode and never ships to production.
+
+karaoke-cms is an Astro framework for publishing Obsidian vaults as static sites. Private-by-default: only files with `publish: true` in frontmatter appear on your site.
+
+## How it works
+
+```
+Obsidian vault (this directory)
+  ↓  write notes with publish: true
+  ↓  push to main
+  ↓  GitHub Actions: astro build + assert-privacy
+  ↓  Cloudflare Pages
+  ↓  live site
+```
+
+Your vault is also your deploy pipeline config, your documentation, and your content collection — all in one place.
+
+## Handbook sections
+
+- [[content]] — Writing content and frontmatter
+- [[configuration]] — karaoke.config.ts reference
+- [[deployment]] — Deploying to Cloudflare Pages
+- [[privacy]] — How publish:true works
+
+## Collections
+
+This vault has three content collections:
+
+| Collection | Mode | Purpose |
+|------------|------|---------|
+| `blog/` | dev + prod | Published blog posts |
+| `docs/` | dev + prod | Published documentation |
+| `karaoke-cms/` | dev only | This handbook — never ships |
+
+Edit `content/karaoke-cms/config/collections.yaml` to add your own collections or change their visibility.

package/karaoke-create-vault/karaoke-cms/manual/privacy.md

@@ -0,0 +1,37 @@
+---
+title: "Privacy"
+---
+
+# Privacy Model
+
+> **Handbook — dev only.**
+
+## The rule
+
+**Every file is private by default.** Only files with `publish: true` in frontmatter appear on your site.
+
+A file without `publish: true` never enters the build — not in HTML, RSS, sitemap, or the Pagefind search index.
+
+## How it's enforced
+
+Two independent layers:
+
+1. **Astro content filter** — `getCollection('blog', ({ data }) => data.publish === true)` filters at the query level. Pages only receive published entries.
+
+2. **assert-privacy** — a post-build check that scans `dist/` for known private note titles and content. If any private content leaks, the build fails before deploy.
+
+The collection mode system adds a third layer: `karaoke-cms/` is excluded from `makeCollections()` in production entirely. Even if a handbook page had `publish: true`, it would never enter the prod build graph.
+
+## What "private" means
+
+| Field | Builds? | Searchable? | In RSS? | In sitemap? |
+|-------|---------|-------------|---------|-------------|
+| `publish: true` | Yes | Yes | Yes | Yes |
+| `publish: false` | No | No | No | No |
+| missing | No | No | No | No |
+
+## Audit your site
+
+After every build, `assert-privacy.js` outputs a summary of what shipped. Check it in your CI logs.
+
+For a manual check: `node node_modules/@karaoke-cms/assert-privacy/dist/index.js dist`

package/karaoke-create-vault/karaoke-cms/templates/blog-header.md

@@ -0,0 +1,9 @@
+---
+title: ""            # required — build fails without it
+publish: false               # required to appear on site (default: false)
+date: 2026-01-15            # optional — YYYY-MM-DD, used for sorting
+author: ""              # optional — string or array ["Alice", "Bob"]
+description: ""          # optional — used in OG meta tags and RSS
+tags: [general]   # optional — enables tag pages at /tags/[tag]
+notetype: blog
+---

package/karaoke-create-vault/karaoke-cms/templates/docs-header.md

@@ -0,0 +1,9 @@
+---
+title: ""            # required — build fails without it
+publish: false               # required to appear on site (default: false)
+date: 2026-01-15            # optional — YYYY-MM-DD, used for sorting
+author: ""              # optional — string or array ["Alice", "Bob"]
+description: ""          # optional — used in OG meta tags and RSS
+tags: [general]   # optional — enables tag pages at /tags/[tag]
+notetype: blog
+---

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

@@ -0,0 +1,8 @@
+---
+title: ""            # required — build fails without it
+publish: false               # required to appear on site (default: false)
+date: 2026-01-15            # optional — YYYY-MM-DD, used for sorting
+author: ""              # optional — string or array ["Alice", "Bob"]
+description: "..."          # optional — used in OG meta tags and RSS
+tags: [general]   # optional — enables tag pages at /tags/[tag]
+---

package/package.json

@@ -1,13 +1,14 @@
 {
   "name": "@karaoke-cms/create",
   "type": "module",
-  "version": "0.6.2",
+  "version": "0.9.0",
   "description": "Scaffold a new karaoke-cms project",
   "bin": {
     "create-karaoke-cms": "./src/index.js"
   },
   "files": [
-    "src/"
+    "src/",
+    "karaoke-create-vault/"
   ],
   "engines": {
     "node": ">=22.12.0"

package/src/index.js

@@ -7,12 +7,13 @@
  */
 
 import { createInterface } from 'readline';
-import { existsSync, mkdirSync, writeFileSync, readFileSync } from 'fs';
+import { existsSync, mkdirSync, writeFileSync, readFileSync, cpSync } from 'fs';
 import { join, resolve } from 'path';
+import { fileURLToPath } from 'url';
+import { spawnSync } from 'child_process';
 import {
   packageJson, astroConfig, karaokeConfig, contentConfig,
-  envDts, tsConfig, gitignore, cloudflareRedirects,
-  helloWorld, draftPost, gettingStarted,
+  envDts, tsConfig, gitignore, envDefault, cloudflareRedirects,
 } from './templates.js';
 
 // ── ANSI helpers ─────────────────────────────────────────────────────────────
@@ -109,7 +110,10 @@ async function main() {
   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);
 
@@ -128,25 +132,20 @@ async function main() {
   // ── Scaffold ────────────────────────────────────────────────────────────────
   console.log(`\n  Scaffolding ${BOLD}${dir}${R}...\n`);
 
-  const date = new Date().toISOString().split('T')[0];
-
   mkdirSync(join(targetDir, 'src'), { recursive: true });
-  mkdirSync(join(targetDir, 'content/blog'), { recursive: true });
-  mkdirSync(join(targetDir, 'content/docs'), { recursive: true });
   mkdirSync(join(targetDir, 'public'), { recursive: true });
 
+  // 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(),
     'src/env.d.ts':           envDts(),
     'tsconfig.json':          tsConfig(),
     '.gitignore':             gitignore(),
+    '.env.default':           envDefault(),
     'public/_redirects':      cloudflareRedirects(),
-    'content/blog/hello-world.md':      helloWorld({ date }),
-    'content/blog/draft-post.md':       draftPost({ date }),
-    'content/docs/getting-started.md':  gettingStarted({ date }),
   };
 
   for (const [file, content] of Object.entries(files)) {
@@ -154,13 +153,35 @@ async function main() {
     console.log(`  ${GREEN}+${R} ${file}`);
   }
 
+  // Vault content: copy the real Obsidian vault into vault/ subdirectory
+  const vaultSrc = fileURLToPath(new URL('../karaoke-create-vault', import.meta.url));
+  cpSync(vaultSrc, join(targetDir, 'vault'), { recursive: true });
+  console.log(`  ${GREEN}+${R} vault/ (Obsidian vault)`);
+
+  // ── Git init ────────────────────────────────────────────────────────────────
+  const gitOk = (() => {
+    const run = (args) => spawnSync('git', args, { cwd: targetDir, encoding: 'utf8' }).status === 0;
+    return (
+      run(['init']) &&
+      run(['add', '-A']) &&
+      run(['-c', 'user.name=karaoke-cms', '-c', 'user.email=setup@karaoke-cms.org',
+           'commit', '-m', 'chore: initial karaoke-cms setup'])
+    );
+  })();
+
+  if (gitOk) {
+    console.log(`  ${GREEN}+${R} git repository initialized`);
+  } else {
+    console.log(`  ${GRAY}  (git init skipped — install git and run it manually)${R}`);
+  }
+
   // ── Done ────────────────────────────────────────────────────────────────────
   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`);
-  console.log(`  ${GRAY}Open ${BOLD}${dir}/${R}${GRAY} in Obsidian as a vault to write content.${R}\n`);
+  console.log(`  ${GRAY}Open ${BOLD}${dir}/vault/${R}${GRAY} in Obsidian to write content.${R}\n`);
 }
 
 main().catch(err => {

package/src/templates.js

@@ -5,9 +5,16 @@
  */
 
 /**
- * @param {{ name: string, astroVersion: string }} opts
+ * @param {{ name: string, astroVersion: string, theme?: string }} opts
  */
-export function packageJson({ name, astroVersion }) {
+export function packageJson({ name, astroVersion, theme }) {
+  const dependencies = {
+    '@karaoke-cms/astro': `^${astroVersion}`,
+    astro: '^6.0.0',
+  };
+  if (theme?.startsWith('@')) {
+    dependencies[theme] = `^${astroVersion}`;
+  }
   return JSON.stringify({
     name,
     private: true,
@@ -18,10 +25,7 @@ export function packageJson({ name, astroVersion }) {
       build: 'astro build',
       preview: 'astro preview',
     },
-    dependencies: {
-      '@karaoke-cms/astro': `^${astroVersion}`,
-      astro: '^6.0.0',
-    },
+    dependencies,
   }, null, 2) + '\n';
 }
 
@@ -66,8 +70,12 @@ export function karaokeConfig({ title, description, theme, search, comments }) {
     : '';
 
   return `import type { KaraokeConfig } from '@karaoke-cms/astro';
+import { loadEnv } from '@karaoke-cms/astro/env';
+
+const env = loadEnv(new URL('.', import.meta.url));
 
 const config: KaraokeConfig = {
+  vault: env.KARAOKE_VAULT,
   title: ${JSON.stringify(title)},
   description: ${JSON.stringify(description)},
   theme: ${JSON.stringify(theme)},${modulesStr}
@@ -79,8 +87,11 @@ export default config;
 
 export function contentConfig() {
   return `import { makeCollections } from '@karaoke-cms/astro/collections';
+import { loadEnv } from '@karaoke-cms/astro/env';
+
+const env = loadEnv(new URL('..', import.meta.url));
 
-export const collections = makeCollections(new URL('..', import.meta.url));
+export const collections = makeCollections(new URL('..', import.meta.url), env.KARAOKE_VAULT);
 `;
 }
 
@@ -103,82 +114,24 @@ node_modules/
 dist/
 .astro/
 .env
-.env.*
+.env.local
+.env.*.local
+# Obsidian workspace state (personal, not shared)
+.obsidian/workspace.json
+.obsidian/workspace-mobile.json
 `;
 }
 
-export function cloudflareRedirects() {
-  return `/* /404.html 404\n`;
-}
-
-/** @param {{ date: string }} opts */
-export function helloWorld({ date }) {
-  return `---
-title: "Hello World"
-publish: true
-date: ${date}
-author: "The Team"
-description: "Our first published post."
----
-
-Welcome! This post has \`publish: true\` so it appears on the site.
-
-## How publishing works
-
-1. Write Markdown in Obsidian (or any editor)
-2. Add \`publish: true\` to the frontmatter when ready to share
-3. Push to \`main\` — GitHub Actions builds and deploys automatically
-
-Posts without \`publish: true\` stay private in your vault.
+export function envDefault() {
+  return `# Obsidian vault location — open this folder in Obsidian to write content.
+# Override in .env (gitignored) to point to a vault elsewhere on your machine.
+# Absolute path: KARAOKE_VAULT=/Users/you/Obsidian/my-vault
+# Relative path: KARAOKE_VAULT=../my-obsidian-vault
+KARAOKE_VAULT=./vault/
 `;
 }
 
-/** @param {{ date: string }} opts */
-export function draftPost({ date }) {
-  return `---
-title: "Draft Post"
-publish: false
-date: ${date}
----
-
-This post has \`publish: false\`. It lives in your vault but never appears on the site.
-
-Change it to \`publish: true\` when you're ready to share it.
-`;
+export function cloudflareRedirects() {
+  return `/* /404.html 404\n`;
 }
 
-/** @param {{ date: string }} opts */
-export function gettingStarted({ date }) {
-  return `---
-title: "Getting Started"
-publish: true
-date: ${date}
-description: "How to set up and use your karaoke-cms site."
----
-
-## Setup
-
-1. Open this folder in Obsidian as a vault
-2. Edit \`karaoke.config.ts\` — set your title, theme, and modules
-3. Set your Cloudflare Pages URL in \`astro.config.mjs\`
-4. Push to \`main\` — your site is live
-
-## Writing content
-
-- Blog posts go in \`content/blog/\`
-- Documentation goes in \`content/docs/\`
-- Set \`publish: true\` to make a file public
-
-## Frontmatter reference
-
-\`\`\`yaml
----
-title: "My Post"        # required
-publish: true           # required to appear on site
-date: 2026-01-15        # optional, YYYY-MM-DD
-author: "Name"          # optional
-description: "..."      # optional, used in OG tags and RSS
----
-\`\`\`
-`;
-}