@deckspec/cli 0.1.0 → 0.1.2

package/dist/commands/validate.js

@@ -0,0 +1,37 @@
+import { resolve, dirname } from "node:path";
+import { loadDeckFile, validateDeck } from "@deckspec/dsl";
+import { extractThemeName, resolveThemePatternsDir, compileTsxCached } from "@deckspec/renderer";
+/**
+ * Validates a deck YAML file.
+ * Prints per-slide results to stdout and exits with code 1 if any errors.
+ */
+export async function validateCommand(filePath) {
+    const raw = await loadDeckFile(filePath);
+    const basePath = dirname(resolve(filePath));
+    const themeName = extractThemeName(raw);
+    const patternsDir = resolveThemePatternsDir(themeName);
+    const result = await validateDeck(raw, { basePath, patternsDir, compileTsx: compileTsxCached });
+    if (result.deckError) {
+        console.error("\u2717 Deck structure is invalid:");
+        for (const issue of result.deckError.issues) {
+            console.error(`  ${issue.path.join(".")}: ${issue.message}`);
+        }
+        process.exit(1);
+    }
+    for (const slideResult of result.results) {
+        if (slideResult.valid) {
+            console.log(`\u2713 slides[${slideResult.index}]: valid`);
+        }
+        else {
+            for (const issue of slideResult.errors.issues) {
+                const detail = issue.message;
+                console.error(`\u2717 slides[${slideResult.index}]: ${detail}`);
+            }
+        }
+    }
+    if (!result.valid) {
+        process.exit(1);
+    }
+    console.log(`\nAll ${result.results.length} slide(s) passed validation.`);
+}
+//# sourceMappingURL=validate.js.map

package/dist/commands/validate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.js","sourceRoot":"","sources":["../../src/commands/validate.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAC7C,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAC3D,OAAO,EAAE,gBAAgB,EAAE,uBAAuB,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAEjG;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,QAAgB;IACpD,MAAM,GAAG,GAAG,MAAM,YAAY,CAAC,QAAQ,CAAC,CAAC;IACzC,MAAM,QAAQ,GAAG,OAAO,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC;IAC5C,MAAM,SAAS,GAAG,gBAAgB,CAAC,GAAG,CAAC,CAAC;IACxC,MAAM,WAAW,GAAG,uBAAuB,CAAC,SAAS,CAAC,CAAC;IAEvD,MAAM,MAAM,GAAG,MAAM,YAAY,CAAC,GAAG,EAAE,EAAE,QAAQ,EAAE,WAAW,EAAE,UAAU,EAAE,gBAAgB,EAAE,CAAC,CAAC;IAEhG,IAAI,MAAM,CAAC,SAAS,EAAE,CAAC;QACrB,OAAO,CAAC,KAAK,CAAC,mCAAmC,CAAC,CAAC;QACnD,KAAK,MAAM,KAAK,IAAI,MAAM,CAAC,SAAS,CAAC,MAAM,EAAE,CAAC;YAC5C,OAAO,CAAC,KAAK,CAAC,KAAK,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC;QAC/D,CAAC;QACD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;IAED,KAAK,MAAM,WAAW,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC;QACzC,IAAI,WAAW,CAAC,KAAK,EAAE,CAAC;YACtB,OAAO,CAAC,GAAG,CAAC,iBAAiB,WAAW,CAAC,KAAK,UAAU,CAAC,CAAC;QAC5D,CAAC;aAAM,CAAC;YACN,KAAK,MAAM,KAAK,IAAI,WAAW,CAAC,MAAO,CAAC,MAAM,EAAE,CAAC;gBAC/C,MAAM,MAAM,GAAG,KAAK,CAAC,OAAO,CAAC;gBAC7B,OAAO,CAAC,KAAK,CAAC,iBAAiB,WAAW,CAAC,KAAK,MAAM,MAAM,EAAE,CAAC,CAAC;YAClE,CAAC;QACH,CAAC;IACH,CAAC;IAED,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC;QAClB,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;IAED,OAAO,CAAC,GAAG,CAAC,SAAS,MAAM,CAAC,OAAO,CAAC,MAAM,8BAA8B,CAAC,CAAC;AAC5E,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { validateCommand } from "./commands/validate.js";
+export { renderCommand } from "./commands/render.js";
+export { lockCommand } from "./commands/lock.js";
+export { patternsCommand } from "./commands/patterns.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC"}

package/dist/index.js

@@ -0,0 +1,5 @@
+export { validateCommand } from "./commands/validate.js";
+export { renderCommand } from "./commands/render.js";
+export { lockCommand } from "./commands/lock.js";
+export { patternsCommand } from "./commands/patterns.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC"}

package/package.json

@@ -1,6 +1,11 @@
 {
   "name": "@deckspec/cli",
-  "version": "0.1.0",
+  "version": "0.1.2",
+  "files": [
+    "dist",
+    "src",
+    "templates"
+  ],
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -13,9 +18,9 @@
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
     "zod": "^3.23.0",
-    "@deckspec/dsl": "0.1.0",
-    "@deckspec/schema": "0.1.0",
-    "@deckspec/renderer": "0.1.0"
+    "@deckspec/dsl": "0.1.2",
+    "@deckspec/renderer": "0.1.2",
+    "@deckspec/schema": "0.1.2"
   },
   "license": "Apache-2.0",
   "repository": {

package/src/cli.ts

@@ -6,11 +6,13 @@ import { approveCommand } from "./commands/approve.js";
 import { lockCommand } from "./commands/lock.js";
 import { patternsCommand } from "./commands/patterns.js";
 import { devCommand } from "./commands/dev.js";
+import { initCommand } from "./commands/init.js";
 
 const USAGE = `
 Usage: deckspec <command> [options]
 
 Commands:
+  init [dir] [--theme <name>]  Scaffold a new DeckSpec project
   validate <file>           Validate a deck YAML file
   render <file> -o <output> Render a deck YAML file to HTML
   approve <file> [options]  Approve/reject slides or archive/activate decks
@@ -103,8 +105,23 @@ async function main(): Promise<void> {
     }
 
     case "dev": {
-      const dir = args[1] || process.cwd();
-      await devCommand(dir);
+      let devDir = process.cwd();
+      let devPort: number | undefined;
+      const devArgs = args.slice(1);
+      for (let i = 0; i < devArgs.length; i++) {
+        if (devArgs[i] === "--port" && devArgs[i + 1]) {
+          devPort = parseInt(devArgs[i + 1], 10);
+          i++;
+        } else if (!devArgs[i].startsWith("-")) {
+          devDir = devArgs[i];
+        }
+      }
+      await devCommand(devDir, { port: devPort });
+      break;
+    }
+
+    case "init": {
+      await initCommand(args.slice(1));
       break;
     }
 

package/src/commands/dev.ts

@@ -5,7 +5,7 @@ import type { Deck, Slide } from "@deckspec/schema";
 import { readdir, readFile, stat } from "node:fs/promises";
 import { renderDeck, renderDashboard, renderSlide, renderThemeDetail, loadThemeCSS, loadThemeTokens, extractThemeName, resolveThemePatternsDir, resolveThemePatternsSrcDir, compileTsxCached, clearCompileCache, type DeckWithPreviews, type ThemeSummary } from "@deckspec/renderer";
 
-const PORT = 3002;
+let PORT = 3002;
 
 /** SSE clients for live reload */
 const sseClients = new Set<ServerResponse>();
@@ -308,8 +308,9 @@ async function handleRequest(
   }
 }
 
-export async function devCommand(dir: string): Promise<void> {
+export async function devCommand(dir: string, options?: { port?: number }): Promise<void> {
   const baseDir = resolve(dir);
+  if (options?.port != null) PORT = options.port;
 
   // Try dynamic import of chokidar for file watching
   let watcherActive = false;

package/src/commands/init.ts

@@ -0,0 +1,276 @@
+import { resolve, join, dirname, basename, relative } from "node:path";
+import { fileURLToPath } from "node:url";
+import {
+  mkdir,
+  readdir,
+  copyFile,
+  writeFile,
+  stat,
+} from "node:fs/promises";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+/** Directories to skip when copying a theme. */
+const SKIP_DIRS = new Set(["dist", "node_modules", ".turbo"]);
+
+/**
+ * Recursively copy a directory, skipping entries in SKIP_DIRS.
+ */
+async function copyDirRecursive(src: string, dest: string): Promise<void> {
+  await mkdir(dest, { recursive: true });
+  const entries = await readdir(src, { withFileTypes: true });
+
+  for (const entry of entries) {
+    const srcPath = join(src, entry.name);
+    const destPath = join(dest, entry.name);
+
+    if (entry.isDirectory()) {
+      if (SKIP_DIRS.has(entry.name)) continue;
+      await copyDirRecursive(srcPath, destPath);
+    } else {
+      await copyFile(srcPath, destPath);
+    }
+  }
+}
+
+/**
+ * List pattern directory names under a theme's patterns/ folder.
+ * Excludes _lib and index.ts; returns only directories.
+ */
+async function listPatternNames(patternsDir: string): Promise<string[]> {
+  let entries;
+  try {
+    entries = await readdir(patternsDir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  return entries
+    .filter((e) => e.isDirectory() && !e.name.startsWith("_"))
+    .map((e) => e.name)
+    .sort();
+}
+
+/**
+ * Resolve the templates directory bundled with the CLI package.
+ * Works both in dev (src/commands/) and installed (dist/commands/).
+ *
+ * __dirname is packages/cli/dist/commands or packages/cli/src/commands
+ * Go up 2 levels to packages/cli/, then into templates/
+ */
+function resolveTemplatesDir(): string {
+  return resolve(__dirname, "..", "..", "templates");
+}
+
+function generateSampleDeck(theme: string): string {
+  return `meta:
+  title: "My Presentation"
+  theme: ${theme}
+  state: active
+slides:
+  - file: title-center
+    vars:
+      title: "Welcome"
+      subtitle: "A presentation built with DeckSpec"
+
+  - file: feature-metrics
+    vars:
+      headline: "Key Numbers"
+      metrics:
+        - label: "Slides"
+          value: "3"
+        - label: "Patterns"
+          value: "17+"
+        - label: "Build Steps"
+          value: "0"
+
+  - file: three-pillars
+    vars:
+      label: "How It Works"
+      heading: "Three Simple Steps"
+      pillars:
+        - title: "Write"
+          value: "YAML"
+          description: "Define your content in a simple, structured format."
+        - title: "Validate"
+          value: "Zod"
+          description: "Schemas catch mistakes before you ever see the output."
+        - title: "Render"
+          value: "HTML"
+          description: "Patterns produce standalone HTML — no dependencies."
+`;
+}
+
+function generatePackageJson(): string {
+  return JSON.stringify(
+    {
+      private: true,
+      type: "module",
+      dependencies: {
+        "@deckspec/cli": "^0.1.0",
+      },
+    },
+    null,
+    2,
+  ) + "\n";
+}
+
+function generateGitignore(): string {
+  return `node_modules/
+dist/
+output/
+tmp/
+*.tsbuildinfo
+`;
+}
+
+function generateClaudeMd(theme: string, patterns: string[]): string {
+  const patternList = patterns.map((p) => `- \`${p}\``).join("\n");
+
+  return `# DeckSpec Project
+
+Programmable presentations. YAML で書く。Zod で守る。React で描く。
+
+## YAML DSL Spec
+
+A deck is defined by a single \`deck.yaml\` file:
+
+\`\`\`yaml
+meta:
+  title: "Presentation Title"
+  theme: ${theme}
+  state: active          # active | archived
+slides:
+  - file: pattern-name   # pattern from themes/${theme}/patterns/
+    vars:
+      key: "value"       # content injected into the pattern
+\`\`\`
+
+### Slide Fields
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| \`file\` | yes | Pattern name (resolved from theme) or relative path |
+| \`vars\` | yes | Content variables — validated by the pattern's Zod schema |
+| \`state\` | no | \`generated\` (default) / \`approved\` / \`locked\` |
+
+## Available Patterns (theme: ${theme})
+
+${patternList}
+
+Each pattern lives in \`themes/${theme}/patterns/<name>/index.tsx\` and exports:
+- \`export const schema\` — Zod schema defining accepted \`vars\`
+- \`export default Component\` — React component for SSR
+
+Check each pattern's \`examples.yaml\` (if present) for usage examples.
+
+## Commands
+
+\`\`\`bash
+npx deckspec validate decks/sample/deck.yaml        # Validate YAML against Zod schemas
+npx deckspec render decks/sample/deck.yaml -o out    # Render to standalone HTML
+npx deckspec dev                                     # Live preview at http://localhost:3002
+npx deckspec patterns                                # List all patterns with schemas
+\`\`\`
+
+## Creating a New Slide
+
+1. Pick a pattern from the list above
+2. Add a slide entry to \`deck.yaml\` with \`file:\` and \`vars:\`
+3. Run \`npx deckspec validate\` to check your YAML
+4. Run \`npx deckspec dev\` to preview
+
+## Creating a Deck-Local Pattern
+
+If no existing pattern fits, create a custom one:
+
+1. Create \`decks/<deck>/patterns/<name>/index.tsx\`
+2. Export \`schema\` (Zod) and \`default\` (React component)
+3. Reference it in \`deck.yaml\` with \`file: <name>\`
+4. Deck-local patterns are compiled on-the-fly with esbuild — no build step needed
+
+## Theme Design Reference
+
+See \`themes/${theme}/design.md\` for the theme's design principles, color palette, and typography rules.
+`;
+}
+
+/**
+ * deckspec init [dir] --theme <name>
+ */
+export async function initCommand(args: string[]): Promise<void> {
+  // Parse arguments
+  let targetDir = ".";
+  let themeName = "noir-display";
+
+  const themeIdx = args.indexOf("--theme");
+  if (themeIdx !== -1) {
+    const val = args[themeIdx + 1];
+    if (!val) {
+      console.error("Error: --theme requires a value.");
+      process.exit(1);
+    }
+    themeName = val;
+  }
+
+  // First positional arg (not a flag) is the target directory
+  for (const arg of args) {
+    if (arg === "--theme") break;
+    if (!arg.startsWith("-")) {
+      targetDir = arg;
+      break;
+    }
+  }
+
+  const root = resolve(targetDir);
+  const templatesDir = resolveTemplatesDir();
+  const themeSrc = join(templatesDir, themeName);
+
+  // Verify theme exists
+  try {
+    const s = await stat(themeSrc);
+    if (!s.isDirectory()) throw new Error();
+  } catch {
+    console.error(`Error: Theme "${themeName}" not found at ${themeSrc}`);
+    process.exit(1);
+  }
+
+  console.log(`Initializing DeckSpec project in ${root}`);
+  console.log(`  Theme: ${themeName}`);
+
+  // 1. Copy theme
+  const themeDest = join(root, "themes", themeName);
+  console.log(`  Copying theme to themes/${themeName}/`);
+  await copyDirRecursive(themeSrc, themeDest);
+
+  // 2. Create sample deck
+  const deckDir = join(root, "decks", "sample");
+  await mkdir(deckDir, { recursive: true });
+  const deckPath = join(deckDir, "deck.yaml");
+  await writeFile(deckPath, generateSampleDeck(themeName));
+  console.log("  Created decks/sample/deck.yaml");
+
+  // 3. Create package.json
+  const pkgPath = join(root, "package.json");
+  await writeFile(pkgPath, generatePackageJson());
+  console.log("  Created package.json");
+
+  // 4. Create CLAUDE.md
+  const patterns = await listPatternNames(join(themeDest, "patterns"));
+  const claudePath = join(root, "CLAUDE.md");
+  await writeFile(claudePath, generateClaudeMd(themeName, patterns));
+  console.log("  Created CLAUDE.md");
+
+  // 5. Create .gitignore
+  const gitignorePath = join(root, ".gitignore");
+  await writeFile(gitignorePath, generateGitignore());
+  console.log("  Created .gitignore");
+
+  console.log("");
+  console.log("Done! Next steps:");
+  console.log("");
+  console.log(`  cd ${relative(process.cwd(), root) || "."}`);
+  console.log("  npm install");
+  console.log("  npx deckspec dev");
+  console.log("");
+}

package/src/commands/render.ts

@@ -1,5 +1,5 @@
-import { writeFile } from "node:fs/promises";
-import { resolve, dirname } from "node:path";
+import { writeFile, mkdir } from "node:fs/promises";
+import { resolve, dirname, extname, join } from "node:path";
 import { loadDeckFile, validateDeck } from "@deckspec/dsl";
 import type { Deck } from "@deckspec/schema";
 import { renderDeck, loadThemeCSS, extractThemeName, resolveThemePatternsDir, resolveThemePatternsSrcDir, compileTsxCached } from "@deckspec/renderer";
@@ -45,6 +45,15 @@ export async function renderCommand(
   const patternsSrcDir = resolveThemePatternsSrcDir(themeName);
   const html = await renderDeck(deck, themeCSS, { basePath, patternsDir, patternsSrcDir });
 
-  await writeFile(outputPath, html, "utf-8");
-  console.log(`\u2713 Rendered ${result.results.length} slide(s) to ${outputPath}`);
+  // If outputPath has no .html extension, treat it as a directory
+  let finalPath = outputPath;
+  if (extname(outputPath) !== ".html") {
+    finalPath = join(outputPath, "index.html");
+    await mkdir(outputPath, { recursive: true });
+  } else {
+    await mkdir(dirname(outputPath), { recursive: true });
+  }
+
+  await writeFile(finalPath, html, "utf-8");
+  console.log(`\u2713 Rendered ${result.results.length} slide(s) to ${finalPath}`);
 }

package/templates/noir-display/components/card/index.tsx

@@ -0,0 +1,31 @@
+import type { ReactElement, ReactNode, CSSProperties } from "react";
+
+interface CardProps {
+  children: ReactNode;
+  highlight?: boolean;
+  style?: CSSProperties;
+}
+
+/**
+ * Dark card with subtle border and rounded corners.
+ */
+export function Card({ children, highlight, style }: CardProps): ReactElement {
+  return (
+    <div
+      style={{
+        backgroundColor: "var(--color-card-background)",
+        borderRadius: "var(--radius)",
+        border: highlight
+          ? "1px solid var(--color-primary)"
+          : "1px solid var(--color-border)",
+        padding: "32px",
+        display: "flex",
+        flexDirection: "column",
+        gap: 12,
+        ...style,
+      }}
+    >
+      {children}
+    </div>
+  );
+}

package/templates/noir-display/components/index.ts

@@ -0,0 +1,2 @@
+export { SlideHeader } from "./slide-header/index.js";
+export { Card } from "./card/index.js";

package/templates/noir-display/components/slide-header/index.tsx

@@ -0,0 +1,47 @@
+import type { ReactElement } from "react";
+
+interface SlideHeaderProps {
+  label?: string;
+  heading: string;
+  headingSize?: number;
+}
+
+/**
+ * Minimal slide header — optional muted label + display heading.
+ * Apple-style: label is small muted text, heading is large semibold.
+ */
+export function SlideHeader({
+  label,
+  heading,
+  headingSize = 40,
+}: SlideHeaderProps): ReactElement {
+  return (
+    <div style={{ display: "flex", flexDirection: "column", gap: 8 }}>
+      {label && (
+        <span
+          style={{
+            fontSize: 14,
+            fontWeight: 600,
+            letterSpacing: "-0.016em",
+            color: "var(--color-accent)",
+          }}
+        >
+          {label}
+        </span>
+      )}
+      <h2
+        style={{
+          fontFamily: "var(--font-heading)",
+          fontSize: headingSize,
+          fontWeight: 600,
+          lineHeight: 1.1,
+          letterSpacing: headingSize >= 48 ? "-0.015em" : "-0.009em",
+          color: "var(--color-foreground)",
+          margin: 0,
+        }}
+      >
+        {heading}
+      </h2>
+    </div>
+  );
+}