plotters-skill 0.1.0

package/SKILL.md

@@ -0,0 +1,535 @@
+---
+name: plotters-skill
+description: 'Generate charts and plots with the plotters-skill API (matplotlib pyplot-like). Use when: creating histograms, pie charts, line charts, scatter plots, bar charts, area charts, box plots, candlestick charts, subplots, or animated GIFs from data in TypeScript or JavaScript.'
+argument-hint: 'Describe the chart you want, including data and style preferences'
+---
+
+# PlottersSkill — Copilot Skill
+
+PlottersSkill is a high-performance plotting library with a **matplotlib pyplot-like API**.
+It works in both Node.js (native addon) and the browser (WASM/SVG).
+
+## API Reference
+
+### Top-level functions
+
+| Function | pyplot equivalent | Description |
+|----------|-------------------|-------------|
+| `figure()` | `plt.figure()` | Create a single figure |
+| `axes()` | `fig, ax = plt.subplots()` | Create flexible Cartesian axes (mix line, scatter, bar, step, area) |
+| `subplots(nrows, ncols)` | `plt.subplots(nrows, ncols)` | Create a uniform NxM grid of figures |
+| `gridFigure()` | `plt.subplot_mosaic()` | Create a flexible grid where each row can have different column counts |
+
+### Creating a figure
+
+```typescript
+import { figure } from 'plotters-skill';
+
+const fig = figure();
+```
+
+### Axes — flexible mixed-series chart
+
+`axes()` creates a single Cartesian chart on which you can freely mix `plot`,
+`scatter`, `bar`, `step`, and `fillBetween` — like matplotlib's `Axes` object.
+
+```typescript
+import { axes } from 'plotters-skill';
+
+const ax = axes();
+ax.figsize(900, 540);
+ax.title('Mixed Series');
+ax.xlabel('x');
+ax.ylabel('y');
+
+// Line series
+ax.plot([0, 1, 2, 3, 4], [10, 25, 18, 30, 22], {
+  color: 'steelblue', lineWidth: 2, label: 'Trend',
+});
+
+// Scatter series
+ax.scatter([0, 1, 2, 3, 4], [12, 20, 22, 28, 25], {
+  color: 'coral', markerSize: 6, label: 'Actual',
+});
+
+// Vertical bars
+ax.bar([0, 1, 2, 3, 4], [8, 18, 14, 24, 20], {
+  color: 'green', barWidth: 0.6, label: 'Sales',
+});
+
+// Step function
+ax.step([0, 1, 2, 3, 4], [9, 22, 16, 28, 21], {
+  color: 'orange', lineWidth: 2, label: 'Threshold',
+});
+
+// Filled area
+ax.fillBetween([0, 1, 2, 3, 4], [15, 30, 22, 35, 28], {
+  y2: 5, alpha: 0.2, color: 'cyan', label: 'Range',
+});
+
+ax.savefig('mixed.png');
+```
+
+#### Axes methods
+
+| Method | pyplot equivalent | Description |
+|--------|-------------------|-------------|
+| `ax.plot(x, y, opts?)` | `ax.plot()` | Line series |
+| `ax.scatter(x, y, opts?)` | `ax.scatter()` | Scatter / point markers |
+| `ax.bar(x, heights, opts?)` | `ax.bar()` | Vertical bar chart |
+| `ax.step(x, y, opts?)` | `ax.step()` | Step function |
+| `ax.fillBetween(x, y1, opts?)` | `ax.fill_between()` | Filled area |
+| `ax.xlim(min, max)` | `ax.set_xlim()` | Fix x-axis range |
+| `ax.ylim(min, max)` | `ax.set_ylim()` | Fix y-axis range |
+| `ax.margin(px)` | `ChartBuilder.margin()` | Chart margin in pixels |
+| `ax.xLabelAreaSize(px)` | — | X-axis label area size |
+| `ax.yLabelAreaSize(px)` | — | Y-axis label area size |
+| `ax.grid(show)` | `ax.grid()` | Show/hide mesh grid |
+| `ax.legend(show)` | `ax.legend()` | Show/hide legend |
+| `ax.clear()` | `ax.cla()` | Clear all series |
+
+#### ChartBuilder configuration
+
+These methods directly expose plotters' `ChartBuilder` API for maximum
+flexibility over chart layout.
+
+| Method | plotters equivalent | Description |
+|--------|---------------------|-------------|
+| `ax.buildCartesian2d(xMin, xMax, yMin, yMax)` | `ChartBuilder.build_cartesian_2d()` | Set axis ranges (alternative to xlim+ylim) |
+| `ax.marginTop(px)` | `ChartBuilder.margin_top()` | Top margin |
+| `ax.marginBottom(px)` | `ChartBuilder.margin_bottom()` | Bottom margin |
+| `ax.marginLeft(px)` | `ChartBuilder.margin_left()` | Left margin |
+| `ax.marginRight(px)` | `ChartBuilder.margin_right()` | Right margin |
+| `ax.topXLabelAreaSize(px)` | `ChartBuilder.top_x_label_area_size()` | Top X-axis label area size |
+| `ax.rightYLabelAreaSize(px)` | `ChartBuilder.right_y_label_area_size()` | Right Y-axis label area size |
+| `ax.captionFontSize(size)` | `ChartBuilder.caption(..., font_size)` | Caption/title font size |
+| `ax.captionFontFamily(family)` | `ChartBuilder.caption(..., family)` | Caption/title font family |
+
+#### `configureMesh(options)` — grid & axis appearance
+
+Maps directly to plotters' `chart.configure_mesh()`. Pass an options object
+with any subset of fields:
+
+```typescript
+ax.configureMesh({
+  xLabels: 10,            // number of x-axis labels
+  yLabels: 5,             // number of y-axis labels
+  disableXMesh: false,    // hide x grid lines
+  disableYMesh: true,     // hide y grid lines
+  disableAxes: false,     // hide all axes
+  disableXAxis: false,    // hide x axis
+  disableYAxis: false,    // hide y axis
+  boldLineColor: '#333',  // bold grid line colour
+  boldLineAlpha: 0.4,     // bold grid line opacity
+  lightLineColor: '#ccc', // light grid line colour
+  lightLineAlpha: 0.1,    // light grid line opacity
+  axisColor: '#000',      // axis line colour
+  labelFontSize: 14,      // axis tick label size
+  axisDescFontSize: 16,   // axis description font size
+  xLabelFontSize: 12,     // x-axis label font size (overrides labelFontSize)
+  yLabelFontSize: 12,     // y-axis label font size (overrides labelFontSize)
+  tickMarkSize: 5,        // tick mark size in pixels
+  xMaxLightLines: 10,     // max minor grid lines between x-axis labels
+  yMaxLightLines: 10,     // max minor grid lines between y-axis labels
+});
+```
+
+#### `configureSeriesLabels(options)` — legend style
+
+Maps directly to plotters' `chart.configure_series_labels()`:
+
+```typescript
+ax.configureSeriesLabels({
+  position: 'upper-left',        // UpperLeft, UpperRight, LowerLeft, LowerRight, etc.
+  backgroundColor: '#ffffff',    // legend box background colour
+  backgroundAlpha: 0.9,          // legend box opacity
+  borderColor: '#000000',        // legend box border colour
+  fontSize: 14,                  // legend label font size
+  margin: 10,                    // margin around legend box
+  legendAreaSize: 30,            // size of the legend marker area
+});
+```
+
+Valid positions: `upper-left`, `upper-right`, `lower-left`, `lower-right`,
+`upper-middle`, `middle-left`, `middle-right`, `lower-middle`, `middle`.
+
+### Histogram — `fig.hist(data, options?)`
+
+Call `hist()` multiple times to overlay datasets on the same axes — just like
+`ax.hist()` in matplotlib. Each call auto-cycles through the tab10 palette
+(C0 blue, C1 orange, C2 green, …) unless you set `color` explicitly.
+
+```typescript
+// Single histogram
+fig.hist([1, 2, 2, 3, 3, 3, 4, 5], {
+  bins: 10,           // number of bins (default: 10)
+  color: 'steelblue', // bar colour: name, CSS name, or hex '#RRGGBB'
+  alpha: 0.7,         // opacity 0.0–1.0
+  label: 'values',    // legend label
+  rangeMin: 0,        // clip data range min
+  rangeMax: 100,      // clip data range max
+});
+```
+
+```typescript
+// Overlaid histograms — colors auto-cycle (C0, C1, …)
+const fig = figure();
+fig.hist(datasetA, { bins: 20, alpha: 0.5, label: 'Dataset A' }); // C0 blue
+fig.hist(datasetB, { bins: 20, alpha: 0.5, label: 'Dataset B' }); // C1 orange
+fig.hist(datasetC, { bins: 20, alpha: 0.5, label: 'Dataset C' }); // C2 green
+fig.title('Distribution Comparison');
+fig.xlabel('Value');
+fig.ylabel('Frequency');
+fig.savefig('comparison.png');
+```
+
+### Pie / Donut — `fig.pie(values, options?)`
+
+```typescript
+fig.pie([30, 25, 20, 15, 10], {
+  labels: ['A', 'B', 'C', 'D', 'E'],
+  colors: ['steelblue', 'coral', 'gold', 'teal', 'salmon'],
+  startAngle: 90,        // starting angle in degrees
+  donutHole: 60,         // inner radius for donut chart
+  labelOffset: 1.2,      // label offset relative to radius
+  showPercentages: true,  // draw percentage labels inside slices
+});
+```
+
+### Box Plot — `fig.boxplot(datasets, options?)`
+
+Similar to `plt.boxplot(x)` in matplotlib. Each inner array produces one box
+showing median, quartiles, whiskers, and optional outlier points.
+
+```typescript
+fig.boxplot(
+  [
+    [72, 75, 78, 80, 82, 85, 87, 90, 92, 95, 98],
+    [55, 60, 63, 65, 68, 70, 72, 74, 76, 78, 80],
+    [88, 90, 91, 93, 94, 95, 96, 97, 98, 99, 100],
+  ],
+  {
+    tickLabels: ['Midterm', 'Quiz', 'Final'], // category axis labels
+    color: 'steelblue',  // box colour (auto-cycles if omitted)
+    label: 'Scores',     // legend label
+    showMeans: true,      // show mean marker (cross), like showmeans=True
+    showFliers: true,     // show outlier points, like showfliers=True
+  },
+);
+```
+
+### Area Chart — `fig.fillBetween(x, y1, options?)`
+
+Similar to `plt.fill_between(x, y1, y2=0)` in matplotlib. Fills the region
+between a curve and a baseline. Call multiple times to overlay areas.
+
+```typescript
+// Single area
+fig.fillBetween(
+  [0, 1, 2, 3, 4, 5, 6, 7, 8, 9],
+  [10, 15, 22, 35, 50, 72, 95, 130, 170, 220],
+  {
+    y2: 0,              // baseline value (default: 0)
+    color: 'steelblue', // fill colour (auto-cycles if omitted)
+    alpha: 0.35,        // fill opacity 0.0–1.0 (default: 0.3)
+    label: 'Revenue',   // legend label
+  },
+);
+```
+
+```typescript
+// Overlapping areas — colors auto-cycle (C0, C1, …)
+const fig = figure();
+fig.fillBetween(x, seriesA, { alpha: 0.3, label: 'Product A' });
+fig.fillBetween(x, seriesB, { alpha: 0.3, label: 'Product B' });
+fig.title('Sales Comparison');
+fig.xlabel('Month');
+fig.ylabel('Revenue');
+fig.savefig('area-comparison.png');
+```
+
+### Candlestick — `fig.candlestick(data, options?)`
+
+Similar to `mplfinance.plot(df, type='candle')`. Each inner array has 4 values:
+`[open, high, low, close]`. Bullish candles (close >= open) are drawn in the up
+colour, bearish candles in the down colour.
+
+```typescript
+fig.candlestick(
+  [
+    [115.34, 117.25, 114.59, 115.91],
+    [116.17, 117.61, 116.05, 117.57],
+    [118.09, 118.44, 116.99, 117.65],
+    [117.39, 118.75, 116.71, 117.52],
+    [117.14, 120.82, 117.09, 120.22],
+  ],
+  {
+    labels: ['Mar 15', 'Mar 18', 'Mar 19', 'Mar 20', 'Mar 21'], // x-axis date labels
+    upColor: 'green',    // bullish candle colour (default: teal)
+    downColor: 'red',    // bearish candle colour (default: red)
+    width: 15,           // candle body width in pixels
+    label: 'MSFT',       // legend label
+  },
+);
+```
+
+### Line Chart — `fig.plot(x, y, options?)`
+
+Similar to `plt.plot(x, y)`. Call `plot()` multiple times to overlay lines on
+the same axes — each call auto-cycles through the tab10 palette unless you set
+`color` explicitly.
+
+```typescript
+// Single line
+fig.plot([0, 1, 2, 3, 4], [10, 25, 18, 30, 22], {
+  color: 'steelblue', // line colour (auto-cycles if omitted)
+  lineWidth: 2,       // line width in pixels (default: 2)
+  label: 'Revenue',   // legend label
+});
+```
+
+```typescript
+// Multi-series overlay — colours auto-cycle (C0, C1, C2)
+const fig = figure();
+fig.plot(months, seriesA, { label: 'Product A' });
+fig.plot(months, seriesB, { label: 'Product B' });
+fig.plot(months, seriesC, { label: 'Product C' });
+fig.title('Sales Trend');
+fig.xlabel('Month');
+fig.ylabel('Sales');
+fig.savefig('multi-line.png');
+```
+
+### Clearing a figure — `fig.clear()`
+
+Removes all plot elements (histograms, pies, lines, etc.) while keeping the
+title, axis labels, and dimensions. Use this for real-time/animated charts.
+
+```typescript
+fig.clear();
+fig.plot(newX, newY, { color: 'blue' });
+fig.savefig('updated.png');
+```
+
+### Animated GIF — `fig.savegif(path, options)` (Node.js only)
+
+Similar to `matplotlib.animation.FuncAnimation` + `writer='pillow'`. Each frame
+is an array of `{ x, y }` line series rendered as a GIF animation frame.
+
+```typescript
+const allX = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9];
+const allY = [10, 25, 18, 30, 22, 45, 35, 50, 40, 55];
+
+// Progressive reveal: each frame adds one more data point
+const frames = [];
+for (let i = 2; i <= allX.length; i++) {
+  frames.push([{ x: allX.slice(0, i), y: allY.slice(0, i) }]);
+}
+
+const fig = figure();
+fig.figsize(640, 400);
+fig.title('Animated Line');
+fig.xlabel('Time');
+fig.ylabel('Value');
+fig.savegif('animation.gif', { frames, delayMs: 200 });
+```
+
+### Canvas animation (WASM / browser)
+
+In the browser, drive animation with `requestAnimationFrame`. Use `clear()`
+and `plot()` each frame — no special animation API is needed.
+
+```typescript
+const fig = figure();
+fig.figsize(800, 400);
+fig.title('Real-Time Monitor');
+
+let i = 2;
+function animate() {
+  fig.clear();
+  fig.plot(x.slice(0, i), y.slice(0, i), { color: 'blue', label: 'CPU' });
+  fig.draw(canvas);
+  i++;
+  if (i <= x.length) requestAnimationFrame(animate);
+}
+animate();
+```
+
+### Setting labels and title
+
+```typescript
+fig.title('My Chart');
+fig.xlabel('Value');
+fig.ylabel('Frequency');
+fig.figsize(1024, 768);  // width × height in pixels
+```
+
+### Axis ranges, margin, grid — ChartBuilder wrapper
+
+These methods expose plotters' `ChartBuilder` flexibility through a pyplot-like
+API. They correspond to `ax.set_xlim()`, `ax.set_ylim()`, and `ax.grid()` in
+matplotlib.
+
+```typescript
+fig.xlim(-1, 1);      // fix x-axis range (like ax.set_xlim)
+fig.ylim(-0.1, 1);    // fix y-axis range (like ax.set_ylim)
+fig.margin(5);         // chart margin in pixels (plotters ChartBuilder.margin)
+fig.grid(false);       // hide mesh grid lines (like ax.grid(False))
+```
+
+Example — the classic y = x² chart from the plotters ChartBuilder docs:
+
+```typescript
+const fig = figure();
+fig.figsize(800, 600);
+fig.title('y = x²');
+fig.xlim(-1, 1);
+fig.ylim(-0.1, 1);
+fig.xlabel('x');
+fig.ylabel('y');
+
+const x = Array.from({ length: 101 }, (_, i) => -1 + i * 0.02);
+const y = x.map(v => v * v);
+fig.plot(x, y, { color: 'red', label: 'y = x²' });
+fig.savefig('quadratic.png');
+```
+
+Settings persist through `clear()` calls — ideal for fixed-axis animations:
+
+```typescript
+const fig = figure();
+fig.ylim(0, 100);   // set once, kept across frames
+function animate() {
+  fig.clear();
+  fig.plot(newX, newY);
+  fig.draw(canvas);
+  requestAnimationFrame(animate);
+}
+```
+
+### Saving output (Node.js)
+
+```typescript
+fig.savefig('output.png');
+```
+
+### Subplots — uniform grid
+
+Similar to `fig, axs = plt.subplots(nrows, ncols)` in matplotlib.
+
+**Important:** `ax()` extracts the figure from the grid. Configure it, then
+put it back with `setAx()`. This is required because of Rust ownership rules
+across the FFI boundary.
+
+```typescript
+import { subplots } from 'plotters-skill';
+
+const grid = subplots(2, 2);
+grid.figsize(1200, 800);
+grid.suptitle('2×2 Grid');
+
+let ax = grid.ax(0, 0);
+ax.title('Distribution');
+ax.hist(data, { bins: 15, color: 'steelblue' });
+grid.setAx(0, 0, ax);
+
+ax = grid.ax(0, 1);
+ax.pie([30, 25, 20], { labels: ['A', 'B', 'C'] });
+grid.setAx(0, 1, ax);
+
+ax = grid.ax(1, 0);
+ax.hist(otherData, { bins: 10, color: 'coral' });
+grid.setAx(1, 0, ax);
+
+ax = grid.ax(1, 1);
+ax.pie([50, 50], { labels: ['Yes', 'No'] });
+grid.setAx(1, 1, ax);
+
+grid.savefig('grid.png');
+```
+
+### GridFigure — flexible row layout
+
+Similar to `plt.subplot_mosaic()` — each row can have a different number of
+columns.
+
+```typescript
+import { gridFigure } from 'plotters-skill';
+
+const grid = gridFigure();
+grid.addRow(2);  // row 0: two columns
+grid.addRow(1);  // row 1: one full-width column
+grid.figsize(1200, 800);
+grid.suptitle('Mixed Layout');
+
+let ax = grid.ax(0, 0);
+ax.hist(data, { bins: 10 });
+grid.setAx(0, 0, ax);
+
+ax = grid.ax(0, 1);
+ax.pie(values, { labels: ['A', 'B', 'C'] });
+grid.setAx(0, 1, ax);
+
+ax = grid.ax(1, 0);
+ax.hist(otherData, { bins: 20, color: 'coral' });
+grid.setAx(1, 0, ax);
+
+grid.savefig('grid.png');
+```
+
+### Named colours
+
+Supports matplotlib tab10 palette (`c0`–`c9`, `blue`, `orange`, `green`, `red`,
+`purple`, `brown`, `pink`, `gray`, `olive`, `cyan`), common CSS names
+(`steelblue`, `coral`, `tomato`, `gold`, `navy`, `teal`, `salmon`, `black`,
+`white`), and hex codes (`#4682B4`).
+
+## Full example — histogram + pie in a grid
+
+```typescript
+import { subplots } from 'plotters-skill';
+
+const data: number[] = Array.from({ length: 1000 }, () => Math.random() * 100);
+
+const grid = subplots(1, 2);
+grid.figsize(1200, 500);
+grid.suptitle('Dashboard');
+
+let ax = grid.ax(0, 0);
+ax.title('Random Distribution');
+ax.xlabel('Value');
+ax.ylabel('Count');
+ax.hist(data, { bins: 25, color: 'steelblue', alpha: 0.8 });
+grid.setAx(0, 0, ax);
+
+ax = grid.ax(0, 1);
+ax.title('Categories');
+ax.pie([40, 30, 20, 10], {
+  labels: ['Web', 'Mobile', 'Desktop', 'Other'],
+  colors: ['steelblue', 'coral', 'gold', 'teal'],
+});
+grid.setAx(0, 1, ax);
+
+grid.savefig('dashboard.png');
+```
+
+## CLI Usage
+
+```bash
+# Install skill for all AI tools (Copilot, Claude, generic agents)
+npx plotters-skill install-skill
+
+# Install for a specific tool only
+npx plotters-skill install-skill --target copilot   # → .github/skills/plotters-skill/SKILL.md
+npx plotters-skill install-skill --target claude     # → .claude/skills/plotters-skill/SKILL.md
+npx plotters-skill install-skill --target agents     # → .agents/skills/plotters-skill/SKILL.md
+
+# Install into a different project directory
+npx plotters-skill install-skill /path/to/project
+
+# Run a script with the addon pre-imported
+npx plotters-skill eval my_chart.js
+
+# Run inline code
+npx plotters-skill eval-inline "const fig = figure(); fig.hist([1,2,3]); fig.savefig('out.png');"
+```

package/index.js

@@ -0,0 +1,153 @@
+#!/usr/bin/env node
+// plotters-skill CLI
+// Commands:
+//   install-skill [--target <tool>] [dir]  Install SKILL.md for AI coding tools
+//   eval <file.js>                         Run a JS file with the addon pre-imported
+//   eval-inline <code>                     Run inline JS code with the addon pre-imported
+
+const { execFileSync } = require('node:child_process');
+const fs = require('node:fs');
+const path = require('node:path');
+const os = require('node:os');
+
+const PKG_ROOT = path.resolve(__dirname);
+const SKILL_SRC = path.join(PKG_ROOT, 'SKILL.md');
+
+// The preamble that gets prepended to inline scripts and eval'd files.
+// It imports the native addon so user code can call figure(), etc. directly.
+const PREAMBLE = `const { figure, JsFigure } = require(${JSON.stringify(
+  path.join(PKG_ROOT, 'node', 'index.js')
+)});\n`;
+
+// Where each AI tool looks for skill files (relative to project root).
+const SKILL_TARGETS = {
+  copilot: '.github/skills/plotters-skill',
+  claude:  '.claude/skills/plotters-skill',
+  agents:  '.agents/skills/plotters-skill',
+};
+const ALL_TARGETS = Object.keys(SKILL_TARGETS);
+
+function usage() {
+  console.log(`
+plotters-skill CLI
+
+Usage:
+  plotters-skill install-skill [options] [dir]
+      Install SKILL.md so AI tools can discover the plotters-skill API.
+
+      dir  Project root directory (default: current working directory)
+
+      Options:
+        --target <tool>   Install for a specific tool: copilot, claude, agents, or all (default: all)
+                          copilot → .github/skills/plotters-skill/SKILL.md
+                          claude  → .claude/skills/plotters-skill/SKILL.md
+                          agents  → .agents/skills/plotters-skill/SKILL.md
+                          all     → installs for all three
+
+  plotters-skill eval <file.js>        Execute a JS file with the addon pre-imported
+  plotters-skill eval-inline <code>    Execute inline JS code with the addon pre-imported
+  plotters-skill --help                Show this help message
+`.trim());
+}
+
+function installSkill(args) {
+  if (!fs.existsSync(SKILL_SRC)) {
+    console.error('Error: SKILL.md not found in package.');
+    process.exit(1);
+  }
+
+  let target = 'all';
+  let dir = process.cwd();
+
+  // Parse arguments
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--target' && args[i + 1]) {
+      target = args[++i];
+    } else if (!args[i].startsWith('-')) {
+      dir = path.resolve(args[i]);
+    }
+  }
+
+  const targets = target === 'all' ? ALL_TARGETS : [target];
+  for (const t of targets) {
+    const relDir = SKILL_TARGETS[t];
+    if (!relDir) {
+      console.error(`Error: unknown target '${t}'. Choose from: ${ALL_TARGETS.join(', ')}, all`);
+      process.exit(1);
+    }
+    const destDir = path.join(dir, relDir);
+    fs.mkdirSync(destDir, { recursive: true });
+    const dest = path.join(destDir, 'SKILL.md');
+    fs.copyFileSync(SKILL_SRC, dest);
+    console.log(`  ✅ ${t}: ${path.relative(dir, dest)}`);
+  }
+  console.log('\nDone! AI tools will discover plotters-skill automatically.');
+}
+
+function findNode() {
+  return process.execPath; // re-use the current Node.js binary
+}
+
+function evalFile(filePath) {
+  if (!filePath) {
+    console.error('Error: eval requires a file path.');
+    process.exit(1);
+  }
+  const resolved = path.resolve(filePath);
+  if (!fs.existsSync(resolved)) {
+    console.error(`Error: file not found: ${resolved}`);
+    process.exit(1);
+  }
+  const userCode = fs.readFileSync(resolved, 'utf-8');
+  runCode(PREAMBLE + userCode, resolved);
+}
+
+function evalInline(code) {
+  if (!code) {
+    console.error('Error: eval-inline requires a code string.');
+    process.exit(1);
+  }
+  runCode(PREAMBLE + code, '<inline>');
+}
+
+function runCode(fullCode, label) {
+  const tmpFile = path.join(
+    os.tmpdir(),
+    `plotters-skill-${Date.now()}-${Math.random().toString(36).slice(2)}.cjs`
+  );
+  try {
+    fs.writeFileSync(tmpFile, fullCode, 'utf-8');
+    const node = findNode();
+    execFileSync(node, [tmpFile], { stdio: 'inherit' });
+  } catch (err) {
+    if (err.status) process.exit(err.status);
+    throw err;
+  } finally {
+    try { fs.unlinkSync(tmpFile); } catch { /* ignore */ }
+  }
+}
+
+// --- main ---
+const args = process.argv.slice(2);
+const cmd = args[0];
+
+switch (cmd) {
+  case 'install-skill':
+    installSkill(args.slice(1));
+    break;
+  case 'eval':
+    evalFile(args[1]);
+    break;
+  case 'eval-inline':
+    evalInline(args.slice(1).join(' '));
+    break;
+  case '--help':
+  case '-h':
+  case undefined:
+    usage();
+    break;
+  default:
+    console.error(`Unknown command: ${cmd}`);
+    usage();
+    process.exit(1);
+}