@ggterm/core 0.3.2 → 0.3.4

package/dist/cli-plot.js

@@ -14599,7 +14599,7 @@ var exports_serve = {};
 __export(exports_serve, {
   handleServe: () => handleServe
 });
-import { watch, writeFileSync as writeFileSync3, unlinkSync } from "fs";
+import { watch, readFileSync as readFileSync3, writeFileSync as writeFileSync3, unlinkSync, existsSync as existsSync3 } from "fs";
 import { join as join3 } from "path";
 import { createServer } from "http";
 import { spawn } from "child_process";
@@ -14629,6 +14629,18 @@ function handleServe(port) {
   ensureHistoryDirs();
   const clients = new Set;
   let debounceTimer = null;
+  function broadcast(payload) {
+    const sseData = `data: ${payload}
+
+`;
+    for (const client of clients) {
+      try {
+        client.write(sseData);
+      } catch {
+        clients.delete(client);
+      }
+    }
+  }
   const plotsDir = getPlotsDir();
   watch(plotsDir, (_event, filename) => {
     if (!filename || !filename.endsWith(".json"))
@@ -14637,20 +14649,28 @@ function handleServe(port) {
       clearTimeout(debounceTimer);
     debounceTimer = setTimeout(() => {
       const payload = getLatestPayload();
-      if (!payload)
-        return;
-      const sseData = `data: ${payload}
-
-`;
-      for (const client of clients) {
-        try {
-          client.write(sseData);
-        } catch {
-          clients.delete(client);
-        }
-      }
+      if (payload)
+        broadcast(payload);
     }, 150);
   });
+  const vegaLitePath = join3(getGGTermDir(), "last-plot-vegalite.json");
+  let styleDebounce = null;
+  watch(getGGTermDir(), (_event, filename) => {
+    if (filename !== "last-plot-vegalite.json")
+      return;
+    if (styleDebounce)
+      clearTimeout(styleDebounce);
+    styleDebounce = setTimeout(() => {
+      if (!existsSync3(vegaLitePath))
+        return;
+      try {
+        const spec = JSON.parse(readFileSync3(vegaLitePath, "utf-8"));
+        const latestId = getLatestPlotId();
+        const provenance = latestId ? { id: latestId, description: "Styled plot", timestamp: new Date().toISOString(), geomTypes: [] } : { id: "styled", description: "Styled plot", timestamp: new Date().toISOString(), geomTypes: [] };
+        broadcast(JSON.stringify({ type: "plot", spec, provenance }));
+      } catch {}
+    }, 200);
+  });
   const server = createServer((req, res) => {
     const url = new URL(req.url || "/", `http://localhost:${p}`);
     if (url.pathname === "/events") {
@@ -14693,6 +14713,15 @@ function handleServe(port) {
     res.writeHead(200, { "content-type": "text/html; charset=utf-8" });
     res.end(CLIENT_HTML);
   });
+  server.on("error", (err) => {
+    if (err.code === "EADDRINUSE") {
+      console.error(`Port ${p} is already in use.`);
+      console.error(`Kill the existing server: lsof -ti:${p} | xargs kill`);
+      console.error(`Or use a different port: npx ggterm-plot serve ${p + 1}`);
+      process.exit(1);
+    }
+    throw err;
+  });
   server.listen(p, () => {
     const url = `http://localhost:${p}`;
     console.log(`ggterm live viewer running at ${url}`);
@@ -15177,13 +15206,13 @@ var init_serve = __esm(() => {
 // src/cli-plot.ts
 init_src();
 init_history();
-import { readFileSync as readFileSync3, writeFileSync as writeFileSync4, existsSync as existsSync3 } from "fs";
+import { readFileSync as readFileSync4, writeFileSync as writeFileSync4, existsSync as existsSync4 } from "fs";
 import { join as join4 } from "path";
 
 // src/init.ts
 import { mkdirSync as mkdirSync2, writeFileSync as writeFileSync2, readFileSync as readFileSync2, existsSync as existsSync2, readdirSync as readdirSync2, statSync } from "fs";
 import { join as join2, extname } from "path";
-var SKILLS_VERSION = "0.2.7";
+var SKILLS_VERSION = "0.3.2";
 var SKILLS = {
   "data-load": {
     files: {
@@ -15197,73 +15226,41 @@ allowed-tools: Bash(npx:*), Read, Write
 
 Load data into arrays of records for use with ggterm plotting and analysis.
 
-## Quick Patterns by Format
-
-### CSV
+## Built-in Datasets (No files needed!)
 
-\`\`\`typescript
-import { parse } from 'csv-parse/sync'
-import { readFileSync } from 'fs'
+ggterm includes built-in datasets that can be used directly by name:
 
-const text = readFileSync('data.csv', 'utf-8')
-const data = parse(text, {
-  columns: true,        // First row as headers
-  cast: true,           // Auto-convert numbers
-  skip_empty_lines: true
-})
-\`\`\`
-
-**Alternative with d3-dsv** (lighter weight):
+| Dataset | Rows | Columns |
+|---------|------|---------|
+| \`iris\` | 150 | sepal_length, sepal_width, petal_length, petal_width, species |
+| \`mtcars\` | 16 | mpg, cyl, hp, wt, name |
 
-\`\`\`typescript
-import { csvParse, autoType } from 'd3-dsv'
+Use them directly in plot commands:
 
-const data = csvParse(readFileSync('data.csv', 'utf-8'), autoType)
+\`\`\`bash
+npx ggterm-plot iris sepal_length sepal_width species "Iris Dataset" point
+npx ggterm-plot mtcars mpg hp cyl "Motor Trend Cars" point
 \`\`\`
 
-### JSON
+**IMPORTANT**: When the user asks about iris, mtcars, or bundled/built-in datasets, use these names directly with \`npx ggterm-plot\`. Do NOT try to generate CSV files or install Python packages.
 
-\`\`\`typescript
-import { readFileSync } from 'fs'
+## External Files
 
-// JSON array
-const data = JSON.parse(readFileSync('data.json', 'utf-8'))
-\`\`\`
-
-### JSONL (Newline-delimited JSON)
-
-\`\`\`typescript
-const data = readFileSync('data.jsonl', 'utf-8')
-  .trim()
-  .split('\\n')
-  .map(line => JSON.parse(line))
+\`\`\`bash
+npx ggterm-plot data.csv x_column y_column color_column "Title" point
+npx ggterm-plot data.json x_column y_column
+npx ggterm-plot data.jsonl x_column y_column
 \`\`\`
 
 ## Verification
 
-After loading, always verify the data structure:
+Inspect any data file to see columns and types:
 
-\`\`\`typescript
-console.log(\`Loaded \${data.length} rows\`)
-console.log('Columns:', Object.keys(data[0]))
-console.log('Sample row:', data[0])
+\`\`\`bash
+npx ggterm-plot inspect data.csv
 \`\`\`
 
-## Integration with ggterm
-
-Once data is loaded, pass directly to ggterm:
-
-\`\`\`typescript
-import { gg, geom_point } from '@ggterm/core'
-
-const data = loadData('measurements.csv')
-
-const plot = gg(data)
-  .aes({ x: 'time', y: 'value' })
-  .geom(geom_point())
-
-console.log(plot.render({ width: 80, height: 24 }))
-\`\`\`
+$ARGUMENTS
 `
     }
   },
@@ -15277,62 +15274,77 @@ allowed-tools: Bash(npx:ggterm-plot*), Read
 
 # Terminal Plotting with ggterm
 
-Create plots using the CLI tool. Start by inspecting the data, then plot.
+Create plots using the CLI tool. Supports both built-in datasets and external files.
+
+## Built-in Datasets
 
-## Step 1: Inspect Data (Recommended)
+ggterm includes datasets that work by name — no CSV files needed:
+
+| Dataset | Rows | Columns |
+|---------|------|---------|
+| \`iris\` | 150 | sepal_length, sepal_width, petal_length, petal_width, species |
+| \`mtcars\` | 16 | mpg, cyl, hp, wt, name |
 
 \`\`\`bash
-npx ggterm-plot inspect <data.csv>
+npx ggterm-plot iris sepal_length sepal_width species "Iris" point
+npx ggterm-plot mtcars mpg hp cyl "Cars" point
 \`\`\`
 
-Shows column names, types (numeric/categorical/date), unique counts, and sample values.
+**IMPORTANT**: When the user mentions iris, mtcars, or asks for demo/sample data, use these built-in names directly. Do NOT look for CSV files or generate data.
+
+## Live Plot Viewer
 
-## Step 2: Get Suggestions (Optional)
+Start the companion viewer for high-resolution interactive plots:
 
 \`\`\`bash
-npx ggterm-plot suggest <data.csv>
+npx ggterm-plot serve        # default port 4242
+npx ggterm-plot serve 8080   # custom port
 \`\`\`
 
-Returns ready-to-run plot commands based on column types.
+When serve is running, plots auto-display in the browser/Wave panel instead of ASCII art.
 
-## Step 3: Create Plot
+## CLI Command
 
 \`\`\`bash
-npx ggterm-plot <data.csv> <x> <y> [color] [title] [geom]
+npx ggterm-plot <data> <x> <y> [color] [title] [geom]
 \`\`\`
 
 Arguments:
-- \`data.csv\` - Path to CSV file
+- \`data\` - Built-in dataset name (\`iris\`, \`mtcars\`) OR path to CSV/JSON/JSONL file
 - \`x\` - Column name for x-axis
 - \`y\` - Column name for y-axis (use \`-\` for histogram)
 - \`color\` - Column name for color (optional, use \`-\` to skip)
 - \`title\` - Plot title (optional, use \`-\` to skip)
-- \`geom\` - Geometry type: \`point\` (default), \`line\`, \`histogram\`, \`boxplot\`, \`bar\`, \`violin\`, \`area\`, etc.
+- \`geom\` - Geometry type: \`point\` (default), \`line\`, \`histogram\`, \`boxplot\`, \`bar\`, \`violin\`, \`density\`, \`area\`, etc.
 
-## Examples
+## Inspect & Suggest (for external files)
 
-Scatter plot:
 \`\`\`bash
-npx ggterm-plot data.csv sepal_length sepal_width species "Iris Dataset" point
+npx ggterm-plot inspect <data.csv>
+npx ggterm-plot suggest <data.csv>
 \`\`\`
 
-Histogram:
+## Examples
+
+Built-in data:
 \`\`\`bash
-npx ggterm-plot data.csv sepal_width - - "Sepal Width Distribution" histogram
+npx ggterm-plot iris sepal_length sepal_width species "Iris Dataset" point
+npx ggterm-plot iris petal_length - species "Petal Length" histogram
+npx ggterm-plot mtcars mpg hp cyl "MPG vs HP" point
 \`\`\`
 
-Box plot:
+External files:
 \`\`\`bash
-npx ggterm-plot data.csv treatment response_time - "Response by Treatment" boxplot
+npx ggterm-plot data.csv x y color "Title" point
+npx ggterm-plot data.json date value - "Time Series" line
 \`\`\`
 
 ## Workflow
 
-1. Identify the data file from $ARGUMENTS or ask user
-2. Run \`inspect\` to see column names and types
-3. Run \`suggest\` to get recommended visualizations (or choose based on user request)
-4. Run the plot command
-5. Briefly describe what the plot shows
+1. If user asks for iris/mtcars/demo data, use built-in dataset names directly
+2. For external files: run \`inspect\` to see columns, then \`suggest\` for recommendations
+3. Run the plot command
+4. Briefly describe what the plot shows
 
 $ARGUMENTS
 
@@ -15345,6 +15357,11 @@ $ARGUMENTS
 | Distribution of 1 variable | \`histogram\` | Frequency distribution |
 | Distribution by group | \`boxplot\` | Compare medians |
 | Category comparison | \`bar\` | Counts per category |
+| Smoothed distribution | \`density\` | Kernel density estimate |
+| Density shape | \`violin\` | Distribution shape |
+| Stacked distributions | \`ridgeline\` | Joy plot |
+| Filled region | \`area\` | Cumulative or stacked |
+| Cumulative distribution | \`ecdf\` | Empirical CDF |
 `
     }
   },
@@ -15465,7 +15482,7 @@ $ARGUMENTS
       "SKILL.md": `---
 name: ggterm-customize
 description: Customize plot aesthetics using natural language. Use when the user wants to change colors, fonts, titles, labels, themes, or any visual aspect of a plot before publication.
-allowed-tools: Read, Write
+allowed-tools: Read, Write, Bash(npx:*)
 ---
 
 # Natural Language Plot Customization
@@ -15522,7 +15539,7 @@ $ARGUMENTS
       "SKILL.md": `---
 name: ggterm-style
 description: Apply publication-quality style presets to plots. Use when the user wants to style a plot like Wilke, Tufte, Nature, The Economist, or apply minimal/publication styling.
-allowed-tools: Read, Write
+allowed-tools: Read, Write, Bash(npx:*)
 ---
 
 # Plot Style Presets
@@ -15547,47 +15564,6 @@ Apply expert-curated style presets to Vega-Lite specifications for publication-q
 3. Write the updated spec
 4. Inform user they can export with \`/ggterm-publish\`
 
-## Style Configurations
-
-### Wilke Style (Recommended Default)
-
-\`\`\`javascript
-const wilkeStyle = {
-  config: {
-    font: "Helvetica Neue, Helvetica, Arial, sans-serif",
-    background: "white",
-    view: { stroke: null },
-    title: { fontSize: 14, fontWeight: "normal", anchor: "start" },
-    axis: { grid: false, labelFontSize: 11, titleFontSize: 12 },
-    axisY: { grid: true, gridColor: "#ebebeb" }
-  }
-}
-\`\`\`
-
-### Tufte Style
-
-\`\`\`javascript
-const tufteStyle = {
-  config: {
-    font: "Georgia, serif",
-    view: { stroke: null },
-    axis: { domain: false, grid: false, ticks: false }
-  }
-}
-\`\`\`
-
-### Economist Style
-
-\`\`\`javascript
-const economistStyle = {
-  config: {
-    background: "#d5e4eb",
-    axis: { grid: true, gridColor: "#ffffff" },
-    axisX: { grid: false, domain: true }
-  }
-}
-\`\`\`
-
 ## Response Format
 
 After applying a style:
@@ -15624,18 +15600,6 @@ Generate analysis reports with embedded terminal visualizations.
 3. **Visualizations** - Embedded plots with interpretations
 4. **Findings** - Key insights from the analysis
 
-## Embedding Plots
-
-\`\`\`markdown
-## Visualization
-
-\\\`\\\`\\\`
-[terminal plot output here]
-\\\`\\\`\\\`
-
-**Interpretation**: The scatter plot shows [describe the relationship observed].
-\`\`\`
-
 ## Width Guidelines
 
 | Context | Width | Height |
@@ -15765,6 +15729,63 @@ function handleInit() {
     console.log(`ggterm v${SKILLS_VERSION} ready`);
     console.log("");
   }
+  const claudeMdPath = join2(cwd, "CLAUDE.md");
+  const claudeMdContent = `# ggterm Data Analysis Project
+
+This project uses ggterm (@ggterm/core) for data visualization.
+
+## IMPORTANT: Built-in Datasets
+
+ggterm has built-in datasets that work by name — NO CSV files or Python packages needed:
+
+\`\`\`bash
+npx ggterm-plot iris sepal_length sepal_width species "Iris" point
+npx ggterm-plot mtcars mpg hp cyl "Cars" point
+\`\`\`
+
+| Dataset | Rows | Columns |
+|---------|------|---------|
+| \`iris\` | 150 | sepal_length, sepal_width, petal_length, petal_width, species |
+| \`mtcars\` | 16 | mpg, cyl, hp, wt, name |
+
+When asked about iris, mtcars, or sample data, use these names directly as the first argument to \`npx ggterm-plot\`. Do NOT search for CSV files or generate data.
+
+## Plotting Commands
+
+\`\`\`bash
+npx ggterm-plot <data> <x> <y> [color] [title] [geom]
+npx ggterm-plot serve              # Start live viewer (port 4242)
+npx ggterm-plot inspect <file>     # Show column types
+npx ggterm-plot suggest <file>     # Suggest visualizations
+npx ggterm-plot history            # List previous plots
+npx ggterm-plot export <id> out.html  # Export plot
+\`\`\`
+
+## Geom Types
+
+point, line, histogram, boxplot, bar, violin, density, area, ridgeline, heatmap, scatter, ecdf, smooth, and 50+ more.
+
+## Live Viewer
+
+When \`npx ggterm-plot serve\` is running, plots auto-display in the browser/Wave panel as high-resolution interactive Vega-Lite visualizations instead of ASCII art.
+`;
+  const GGTERM_MARKER = "# ggterm Data Analysis Project";
+  let shouldWriteClaudeMd = !existsSync2(claudeMdPath);
+  if (!shouldWriteClaudeMd) {
+    try {
+      const existing = readFileSync2(claudeMdPath, "utf-8");
+      shouldWriteClaudeMd = existing.startsWith(GGTERM_MARKER);
+    } catch {}
+  }
+  if (shouldWriteClaudeMd) {
+    writeFileSync2(claudeMdPath, claudeMdContent);
+    console.log("  ✓ CLAUDE.md (project instructions for Claude Code)");
+    console.log("");
+  }
+  console.log("Built-in datasets:");
+  console.log("  • iris (150 rows: sepal_length, sepal_width, petal_length, petal_width, species)");
+  console.log("  • mtcars (16 rows: mpg, cyl, hp, wt, name)");
+  console.log("");
   const dataFiles = findDataFiles(cwd);
   if (dataFiles.length > 0) {
     console.log("Data files:");
@@ -15792,9 +15813,9 @@ function handleInit() {
   }
   if (needsInstall) {
     console.log("Try:");
-    console.log('  "Show me a scatter plot of x vs y from data.csv"');
-    console.log('  "Create a histogram of the age column"');
-    console.log('  "Style this like Tufte and export as PNG"');
+    console.log('  npx ggterm-plot iris sepal_length sepal_width species "Iris" point');
+    console.log("  npx ggterm-plot serve   # Start live viewer");
+    console.log('  "Plot the iris dataset"  # Ask Claude Code');
     console.log("");
   }
 }
@@ -15802,10 +15823,10 @@ function handleInit() {
 // src/cli-plot.ts
 function isServeRunning() {
   const markerPath = join4(getGGTermDir(), "serve.json");
-  if (!existsSync3(markerPath))
+  if (!existsSync4(markerPath))
     return false;
   try {
-    const info = JSON.parse(readFileSync3(markerPath, "utf-8"));
+    const info = JSON.parse(readFileSync4(markerPath, "utf-8"));
     process.kill(info.pid, 0);
     return true;
   } catch {
@@ -15880,7 +15901,7 @@ var GEOM_TYPES = [
 var datePattern = /^\d{4}-\d{2}-\d{2}/;
 function fileExists(path) {
   try {
-    readFileSync3(path);
+    readFileSync4(path);
     return true;
   } catch {
     return false;
@@ -16025,7 +16046,7 @@ Make sure the file path is correct and the file exists.`);
   }
   let text;
   try {
-    text = readFileSync3(dataFile, "utf-8");
+    text = readFileSync4(dataFile, "utf-8");
   } catch (err) {
     console.error(`
 Error: Cannot read file: ${dataFile}`);

package/dist/init.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../src/init.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAmkBH,wBAAgB,UAAU,IAAI,IAAI,CAyFjC"}
+{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../src/init.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAkgBH,wBAAgB,UAAU,IAAI,IAAI,CAyJjC"}

package/dist/serve.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"serve.d.ts","sourceRoot":"","sources":["../src/serve.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AA0eH,wBAAgB,WAAW,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAmG/C"}
+{"version":3,"file":"serve.d.ts","sourceRoot":"","sources":["../src/serve.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AA0eH,wBAAgB,WAAW,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAkI/C"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ggterm/core",
-  "version": "0.3.2",
+  "version": "0.3.4",
   "description": "Grammar of Graphics engine for terminals",
   "type": "module",
   "main": "./dist/index.js",