@walterra/pi-charts 0.0.2 → 0.0.4

package/README.md

@@ -23,13 +23,13 @@ Renders a Vega-Lite specification as a PNG image.
 
 ### Parameters
 
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `spec` | string | ✅ | Vega-Lite JSON specification |
-| `tsv_data` | string | | Optional TSV data to replace spec.data.values |
-| `width` | number | | Chart width in pixels (default: 600) |
-| `height` | number | | Chart height in pixels (default: 400) |
-| `save_path` | string | | Optional file path to save the PNG |
+| Parameter   | Type   | Required | Description                                   |
+| ----------- | ------ | -------- | --------------------------------------------- |
+| `spec`      | string | ✅       | Vega-Lite JSON specification                  |
+| `tsv_data`  | string |          | Optional TSV data to replace spec.data.values |
+| `width`     | number |          | Chart width in pixels (default: 600)          |
+| `height`    | number |          | Chart height in pixels (default: 400)         |
+| `save_path` | string |          | Optional file path to save the PNG            |
 
 ### Example
 
@@ -38,22 +38,22 @@ Renders a Vega-Lite specification as a PNG image.
   "$schema": "https://vega.github.io/schema/vega-lite/v5.json",
   "data": {
     "values": [
-      {"category": "A", "value": 28},
-      {"category": "B", "value": 55},
-      {"category": "C", "value": 43}
+      { "category": "A", "value": 28 },
+      { "category": "B", "value": 55 },
+      { "category": "C", "value": 43 }
     ]
   },
   "mark": "bar",
   "encoding": {
-    "x": {"field": "category", "type": "nominal"},
-    "y": {"field": "value", "type": "quantitative"}
+    "x": { "field": "category", "type": "nominal" },
+    "y": { "field": "value", "type": "quantitative" }
   }
 }
 ```
 
 ## Reference Documentation
 
-See [vega-lite-reference.md](./extensions/vega-chart/vega-lite-reference.md) for comprehensive documentation on:
+See [vega-lite-reference.md](./extensions/vega-chart/vega-lite-reference.md) for documentation on:
 
 - Data types and encoding channels
 - All mark types and properties

package/extensions/vega-chart/index.ts

@@ -10,13 +10,13 @@
  * - Data-driven: Inline data or separate TSV input
  */
 
-import type { ExtensionAPI } from '@mariozechner/pi-coding-agent';
-import { Type } from '@sinclair/typebox';
 import { execSync } from 'node:child_process';
 import { readFileSync, unlinkSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import type { ExtensionAPI } from '@mariozechner/pi-coding-agent';
+import { Type } from '@sinclair/typebox';
 
 // Compute reference path using ESM import.meta.url
 const VEGA_REFERENCE_PATH = join(dirname(fileURLToPath(import.meta.url)), 'vega-lite-reference.md');
@@ -72,14 +72,14 @@ Reference: https://vega.github.io/vega-lite/docs/`,
       tsv_data: Type.Optional(
         Type.String({
           description: 'Optional TSV data - if provided, replaces spec.data.values',
-        }),
+        })
       ),
       width: Type.Optional(Type.Number({ description: 'Chart width in pixels (default: 600)' })),
       height: Type.Optional(Type.Number({ description: 'Chart height in pixels (default: 400)' })),
       save_path: Type.Optional(
         Type.String({
           description: 'Optional file path to save the PNG chart (in addition to displaying it)',
-        }),
+        })
       ),
     }),
 
@@ -102,6 +102,23 @@ Reference: https://vega.github.io/vega-lite/docs/`,
         return { content: [{ type: 'text', text: 'Cancelled' }], details: {} };
       }
 
+      const getErrorMessage = (err: unknown): string => {
+        if (err instanceof Error) return err.message;
+        if (typeof err === 'string') return err;
+        if (err && typeof err === 'object' && 'message' in err) {
+          return String((err as { message?: unknown }).message);
+        }
+        return 'Unknown error';
+      };
+
+      const getErrorStderr = (err: unknown): string | undefined => {
+        if (err && typeof err === 'object' && 'stderr' in err) {
+          const stderr = (err as { stderr?: unknown }).stderr;
+          return typeof stderr === 'string' ? stderr : undefined;
+        }
+        return undefined;
+      };
+
       try {
         // Check Python and dependencies, auto-install if needed using uv
         const ensureDependencies = (): { success: boolean; error?: string } => {
@@ -159,30 +176,44 @@ Reference: https://vega.github.io/vega-lite/docs/`,
           try {
             execSync(checkCmd, { encoding: 'utf-8', stdio: 'pipe' });
             return { success: true };
-          } catch (err: any) {
+          } catch (err: unknown) {
+            const errorMsg = getErrorMessage(err);
             return {
               success: false,
-              error: `Failed to setup Python environment with uv.\nPlease run manually: uv run --with altair --with pandas --with vl-convert-python python3\n\nError: ${err.message}`,
+              error: `Failed to setup Python environment with uv.\nPlease run manually: uv run --with altair --with pandas --with vl-convert-python python3\n\nError: ${errorMsg}`,
             };
           }
         };
 
         const deps = ensureDependencies();
         if (!deps.success) {
+          const errorText = deps.error ?? 'Dependencies not installed';
           return {
-            content: [{ type: 'text', text: deps.error! }],
+            content: [{ type: 'text', text: errorText }],
             details: { error: 'Dependencies not installed' },
             isError: true,
           };
         }
 
         // Parse and validate the spec
-        let vegaSpec: any;
+        type VegaSpec = {
+          $schema?: string;
+          width?: number;
+          height?: number;
+          data?: { values?: unknown[] };
+          [key: string]: unknown;
+        };
+
+        let vegaSpec: VegaSpec;
         try {
-          vegaSpec = JSON.parse(spec);
+          const parsed = JSON.parse(spec);
+          if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+            throw new Error('Spec must be a JSON object');
+          }
+          vegaSpec = parsed as VegaSpec;
         } catch (e) {
           return {
-            content: [{ type: 'text', text: `Invalid JSON in spec: ${e}` }],
+            content: [{ type: 'text', text: `Invalid JSON in spec: ${getErrorMessage(e)}` }],
             details: { error: 'Invalid JSON' },
             isError: true,
           };
@@ -239,7 +270,7 @@ print('OK')
             encoding: 'utf-8',
             timeout: 60000, // Longer timeout for first run when uv downloads packages
             maxBuffer: 10 * 1024 * 1024,
-          },
+          }
         );
 
         if (!result.includes('OK')) {
@@ -260,9 +291,9 @@ print('OK')
             mkdirSync(dirname(save_path), { recursive: true });
             copyFileSync(tmpPng, save_path);
             savedPath = save_path;
-          } catch (saveErr: any) {
+          } catch (saveErr: unknown) {
             // Don't fail the whole operation, just note the error
-            console.error(`Failed to save to ${save_path}: ${saveErr.message}`);
+            console.error(`Failed to save to ${save_path}: ${getErrorMessage(saveErr)}`);
           }
         }
 
@@ -279,7 +310,9 @@ print('OK')
 
         const dataPoints = tsv_data
           ? tsv_data.trim().split('\n').length - 1
-          : vegaSpec.data?.values?.length || 0;
+          : Array.isArray(vegaSpec.data?.values)
+            ? vegaSpec.data?.values.length
+            : 0;
 
         const textMsg = savedPath
           ? `Rendered Vega-Lite chart (${dataPoints} data points) - saved to ${savedPath}`
@@ -292,9 +325,9 @@ print('OK')
           ],
           details: { dataPoints, width: vegaSpec.width, height: vegaSpec.height, savedPath },
         };
-      } catch (error: any) {
+      } catch (error: unknown) {
         // Try to extract Python error details
-        const errorMsg = error.stderr || error.message;
+        const errorMsg = getErrorStderr(error) ?? getErrorMessage(error);
         return {
           content: [{ type: 'text', text: `Error rendering chart: ${errorMsg}` }],
           details: { error: errorMsg },

package/extensions/vega-chart/vega-lite-reference.md

@@ -1,6 +1,6 @@
 # Vega-Lite Visualization Reference
 
-A comprehensive reference for creating data visualizations using Vega-Lite specifications. This guide follows best practices from the [UW Interactive Data Lab Visualization Curriculum](https://idl.uw.edu/visualization-curriculum/intro.html) and established visualization research.
+Reference for creating data visualizations using Vega-Lite specifications. This guide follows best practices from the [UW Interactive Data Lab Visualization Curriculum](https://idl.uw.edu/visualization-curriculum/intro.html) and established visualization research.
 
 ## Prerequisites
 
@@ -23,7 +23,7 @@ If dependencies cannot be installed, the tool returns an error with instructions
 
 ## Philosophy
 
-> "A visualization is a mapping from data to visual properties. The key insight is that this mapping should be **declarative** rather than imperative."
+At its core, a visualization maps data to visual properties. Instead of specifying step-by-step drawing instructions (imperative), you describe what the visualization should represent (declarative).
 
 Vega-Lite embodies a **grammar of graphics**: you describe _what_ you want to visualize, not _how_ to draw it. This enables:
 
@@ -648,7 +648,12 @@ Control how scales/axes/legends are shared or independent.
   },
   "mark": { "type": "bar", "cornerRadius": 3 },
   "encoding": {
-    "x": { "field": "month", "type": "ordinal", "title": null, "axis": { "labelAngle": 0 } },
+    "x": {
+      "field": "month",
+      "type": "ordinal",
+      "title": null,
+      "axis": { "labelAngle": 0 }
+    },
     "y": {
       "field": "revenue",
       "type": "quantitative",
@@ -664,7 +669,11 @@ Control how scales/axes/legends are shared or independent.
 ```json
 {
   "$schema": "https://vega.github.io/schema/vega-lite/v5.json",
-  "title": { "text": "Daily Temperature", "subtitle": "December 2025", "anchor": "start" },
+  "title": {
+    "text": "Daily Temperature",
+    "subtitle": "December 2025",
+    "anchor": "start"
+  },
   "width": 600,
   "height": 200,
   "data": {
@@ -679,14 +688,26 @@ Control how scales/axes/legends are shared or independent.
   "layer": [
     { "mark": { "type": "area", "opacity": 0.2, "color": "#e45756" } },
     { "mark": { "type": "line", "color": "#e45756", "strokeWidth": 2 } },
-    { "mark": { "type": "point", "color": "#e45756", "filled": true, "size": 50 } },
+    {
+      "mark": {
+        "type": "point",
+        "color": "#e45756",
+        "filled": true,
+        "size": 50
+      }
+    },
     {
       "mark": { "type": "rule", "strokeDash": [4, 4], "color": "#999" },
       "encoding": { "y": { "datum": 20 } }
     }
   ],
   "encoding": {
-    "x": { "field": "date", "type": "temporal", "title": null, "axis": { "format": "%b %d" } },
+    "x": {
+      "field": "date",
+      "type": "temporal",
+      "title": null,
+      "axis": { "format": "%b %d" }
+    },
     "y": {
       "field": "temp",
       "type": "quantitative",
@@ -718,11 +739,21 @@ Control how scales/axes/legends are shared or independent.
   },
   "layer": [
     {
-      "mark": { "type": "line", "strokeWidth": 2.5, "point": { "filled": true, "size": 50 } }
+      "mark": {
+        "type": "line",
+        "strokeWidth": 2.5,
+        "point": { "filled": true, "size": 50 }
+      }
     },
     {
       "transform": [{ "filter": "datum.date == '2025-03'" }],
-      "mark": { "type": "text", "align": "left", "dx": 8, "fontSize": 12, "fontWeight": "bold" },
+      "mark": {
+        "type": "text",
+        "align": "left",
+        "dx": 8,
+        "fontSize": 12,
+        "fontWeight": "bold"
+      },
       "encoding": { "text": { "field": "team" } }
     }
   ],
@@ -824,7 +855,12 @@ Control how scales/axes/legends are shared or independent.
   "mark": "bar",
   "encoding": {
     "x": { "field": "month", "type": "ordinal", "title": null },
-    "y": { "field": "sales", "type": "quantitative", "stack": "zero", "title": "Sales" },
+    "y": {
+      "field": "sales",
+      "type": "quantitative",
+      "stack": "zero",
+      "title": "Sales"
+    },
     "color": { "field": "category", "type": "nominal", "title": null }
   }
 }
@@ -961,14 +997,22 @@ Use sorted bar chart instead - see "Never Use Pie or Donut Charts" in Best Pract
       "mark": "bar",
       "encoding": {
         "x": { "field": "date", "type": "temporal" },
-        "y": { "field": "precipitation", "type": "quantitative", "title": "Precipitation (mm)" }
+        "y": {
+          "field": "precipitation",
+          "type": "quantitative",
+          "title": "Precipitation (mm)"
+        }
       }
     },
     {
       "mark": { "type": "line", "color": "firebrick" },
       "encoding": {
         "x": { "field": "date", "type": "temporal" },
-        "y": { "field": "temperature", "type": "quantitative", "title": "Temperature (°C)" }
+        "y": {
+          "field": "temperature",
+          "type": "quantitative",
+          "title": "Temperature (°C)"
+        }
       }
     }
   ],
@@ -1108,7 +1152,12 @@ Legends force eye movement. Label directly on the chart:
       "encoding": { "color": { "field": "series", "legend": null } }
     },
     {
-      "mark": { "type": "text", "align": "left", "dx": 8, "fontWeight": "bold" },
+      "mark": {
+        "type": "text",
+        "align": "left",
+        "dx": 8,
+        "fontWeight": "bold"
+      },
       "transform": [{ "filter": "datum.date == '2025-12-29'" }],
       "encoding": {
         "x": { "field": "date", "type": "temporal" },
@@ -1588,10 +1637,3 @@ Before finalizing any chart, verify:
 - [Vega-Lite Examples](https://vega.github.io/vega-lite/examples/)
 - [UW Visualization Curriculum](https://idl.uw.edu/visualization-curriculum/intro.html)
 - [Altair Documentation](https://altair-viz.github.io/)
-
-### Visual Design References
-
-- _Sémiologie Graphique_ (1967) — semiotics of graphics, visual variables
-- _The Visual Display of Quantitative Information_ (1983) — data-ink ratio, minimalist approach
-- _The Functional Art_, _How Charts Lie_ — clarity over minimalism, communicative approach
-- _Visualization Analysis and Design_ (2014) — systematic approach to visualization design

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@walterra/pi-charts",
-  "version": "0.0.2",
+  "version": "0.0.4",
   "description": "Vega-Lite chart extension for pi coding agent - render data visualizations as inline images",
   "type": "module",
   "files": [
@@ -10,7 +10,8 @@
   "pi": {
     "extensions": [
       "./extensions/vega-chart/index.ts"
-    ]
+    ],
+    "video": "https://www.rafelsberger.at/assets/pi-charts-sm-0003.mp4"
   },
   "repository": {
     "type": "git",
@@ -18,6 +19,7 @@
     "directory": "packages/pi-charts"
   },
   "keywords": [
+    "pi-package",
     "pi",
     "pi-coding-agent",
     "extension",