@loreto-labs/skill-echarts 0.1.0

package/README.md

@@ -0,0 +1,32 @@
+# Building Branded Echarts Visualizations — CLI + MCP
+
+A self-contained command-line tool **and** MCP server for the Loreto skill `building-branded-echarts-visualizations`.
+
+## Install
+
+```bash
+npx @loreto-labs/skill-echarts install   # copies the skill into ~/.claude/skills + adds /echarts
+```
+
+## Use the CLI
+
+```bash
+loreto-echarts --help
+loreto-echarts info
+loreto-echarts render --brand onyx --chart bar --out chart.svg
+loreto-echarts test
+```
+
+## Use as an MCP server
+
+Add to your MCP client config:
+
+```json
+{
+  "mcpServers": {
+    "echarts": { "command": "loreto-echarts-mcp" }
+  }
+}
+```
+
+Generated by loreto-skill-cli.

package/actions.mjs

@@ -0,0 +1,112 @@
+// Adapter: building-branded-echarts-visualizations
+//
+// Skill-specific CLI sub-commands + MCP tools. These wrap the skill's own
+// `renderChart()` export — the framework turns each entry into both a CLI
+// command and an MCP tool with no extra code.
+//
+// An adapter only declares WHAT the skill can do; the framework handles
+// argument parsing, help text, MCP schema generation, and dispatch.
+
+import { readFileSync, writeFileSync, mkdirSync, readdirSync, existsSync } from 'node:fs';
+import { join, dirname, resolve, basename } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { spawnSync } from 'node:child_process';
+
+const listJson = (dir) =>
+  existsSync(dir) ? readdirSync(dir).filter((f) => f.endsWith('.json')).sort() : [];
+
+function resolveBrand(skillDir, name) {
+  if (name.endsWith('.json') || name.includes('/')) return resolve(name);
+  return join(skillDir, 'brands', `${name}.json`);
+}
+
+function resolveChart(skillDir, name) {
+  if (name.endsWith('.json') || name.includes('/')) return resolve(name);
+  const dir = join(skillDir, 'examples');
+  const files = listJson(dir);
+  // Match exact (01_bar), or by suffix after the numeric prefix (bar -> 01_bar.json).
+  const hit =
+    files.find((f) => f === `${name}.json`) ||
+    files.find((f) => f.replace(/^\d+_/, '') === `${name}.json`);
+  return hit ? join(dir, hit) : join(dir, `${name}.json`);
+}
+
+export async function makeActions(ctx) {
+  const { skillDir } = ctx;
+  const scriptsDir = join(skillDir, 'scripts');
+  // Lazy: `echarts` is a large module graph, so only load it when a command
+  // that actually renders is run — `brands`/`examples`/`info`/`install` stay instant.
+  const loadRenderChart = async () =>
+    (await import(pathToFileURL(join(scriptsDir, 'render.mjs')).href)).renderChart;
+
+  return [
+    {
+      name: 'render',
+      summary: 'Render one branded chart to SVG (+ PNG)',
+      args: [
+        { name: 'brand', required: true, help: 'Brand theme name (onyx, apricot) or path to a brand JSON' },
+        { name: 'chart', required: true, help: 'Example name (bar, 01_bar) or path to a chart-spec JSON' },
+        { name: 'out', help: 'Output .svg path (default: ./<chart>.svg)' },
+        { name: 'png', type: 'boolean', default: true, help: 'Also emit a 2x PNG (use --no-png to skip)' },
+      ],
+      async run(opts) {
+        const renderChart = await loadRenderChart();
+        const brandPath = resolveBrand(skillDir, opts.brand);
+        const chartPath = resolveChart(skillDir, opts.chart);
+        if (!existsSync(brandPath)) throw new Error(`Brand not found: ${brandPath}`);
+        if (!existsSync(chartPath)) throw new Error(`Chart spec not found: ${chartPath}`);
+
+        const brand = JSON.parse(readFileSync(brandPath, 'utf8'));
+        const spec = JSON.parse(readFileSync(chartPath, 'utf8'));
+        const out = resolve(opts.out || `${basename(chartPath, '.json')}.svg`);
+        mkdirSync(dirname(out), { recursive: true });
+
+        const { svg, png } = await renderChart({ brand, brandPath, spec, png: opts.png });
+        writeFileSync(out, svg);
+        const written = [`SVG → ${out} (${svg.length.toLocaleString()} bytes)`];
+        if (opts.png && png) {
+          const p = out.replace(/\.svg$/, '.png');
+          writeFileSync(p, png);
+          written.push(`PNG → ${p} (${png.length.toLocaleString()} bytes)`);
+        }
+        return { text: `Rendered ${brand.name || opts.brand} / ${basename(chartPath)}\n  ${written.join('\n  ')}` };
+      },
+    },
+
+    {
+      name: 'render-all',
+      summary: 'Render every example chart for every bundled brand into a gallery',
+      args: [],
+      run() {
+        const r = spawnSync('node', ['render-all.mjs'], { cwd: scriptsDir, encoding: 'utf8' });
+        if (r.error) throw new Error(r.error.message);
+        if (r.status !== 0) throw new Error(r.stderr || `render-all exited ${r.status}`);
+        return { text: (r.stdout || '').trim() };
+      },
+    },
+
+    {
+      name: 'brands',
+      summary: 'List the brand themes bundled with this skill',
+      args: [],
+      run() {
+        const files = listJson(join(skillDir, 'brands'));
+        const rows = files.map((f) => {
+          const b = JSON.parse(readFileSync(join(skillDir, 'brands', f), 'utf8'));
+          return `  ${basename(f, '.json').padEnd(10)} ${b.name || ''} (${b.mode || 'light'})`;
+        });
+        return { text: ['Brands:', ...rows].join('\n') };
+      },
+    },
+
+    {
+      name: 'examples',
+      summary: 'List the example chart specs bundled with this skill',
+      args: [],
+      run() {
+        const files = listJson(join(skillDir, 'examples'));
+        return { text: ['Examples:', ...files.map((f) => `  ${basename(f, '.json')}`)].join('\n') };
+      },
+    },
+  ];
+}

package/bin/cli.mjs

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { runCli } from '../runtime/cli-runner.mjs';
+runCli(import.meta.url);

package/bin/mcp.mjs

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+import { loadBundle } from '../runtime/cli-runner.mjs';
+import { runMcp } from '../runtime/mcp-runner.mjs';
+const { ctx, actions } = await loadBundle(import.meta.url);
+await runMcp(ctx, actions);

package/command.md

@@ -0,0 +1,9 @@
+---
+description: Building Branded Echarts Visualizations — invoke the Loreto skill (installed in ~/.claude/skills)
+---
+
+Use the **building-branded-echarts-visualizations** skill (in ~/.claude/skills/building-branded-echarts-visualizations/SKILL.md) for this request.
+
+You can also drive its bundled CLI directly, e.g. `loreto-echarts --help`.
+
+$ARGUMENTS

package/loreto.skill.json

@@ -0,0 +1,16 @@
+{
+  "slug": "building-branded-echarts-visualizations",
+  "name": "Building Branded Echarts Visualizations",
+  "version": "0.1.0",
+  "bin": "loreto-echarts",
+  "command": "echarts",
+  "description": "Turns a company's brand styles (color codes + fonts) into polished, on-brand Apache ECharts data visualizations — bar, line, area, pie/donut, scatter, KPI cards, heatmap, radar, treemap, and full dashboards — rendered server-side to SVG and PNG. Use when you need \"branded charts\", \"on-brand data viz\", \"style ECharts to our brand\", \"company-branded dashboards\", \"charts that match our brand guidelines\", or to produce a reusable chart theme from a brand's palette and typography. You give it a brand token file (hex colors, font families, optional webfont URLs) and a chart spec (type + data); it emits a styled SVG (font-accurate) plus a PNG. Bundled Node scripts do the rendering — no browser needed. Invoke it by NAMING a theme — e.g. \"apply the Apricot style to all of our analytics charts\" or \"render this data in the Onyx theme\" — and it resolves the named style to its brand file and applies it to every chart. Bundled themes: onyx, apricot (list with `ls brands/`).",
+  "skillDir": "skill",
+  "hasActions": true,
+  "test": {
+    "cmd": [
+      "python3",
+      "tests/test_building_branded_echarts_visualizations.py"
+    ]
+  }
+}

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@loreto-labs/skill-echarts",
+  "version": "0.1.0",
+  "description": "CLI + MCP for the Loreto skill: Building Branded ECharts Visualizations — render on-brand charts to SVG/PNG.",
+  "keywords": [
+    "loreto",
+    "claude",
+    "skill",
+    "echarts",
+    "charts",
+    "mcp",
+    "cli",
+    "dataviz"
+  ],
+  "type": "module",
+  "license": "MIT",
+  "author": "Loreto <info@loreto.io>",
+  "homepage": "https://loreto.io",
+  "bin": {
+    "loreto-echarts": "bin/cli.mjs",
+    "loreto-echarts-mcp": "bin/mcp.mjs"
+  },
+  "files": [
+    "bin",
+    "runtime",
+    "skill",
+    "actions.mjs",
+    "loreto.skill.json",
+    "command.md"
+  ],
+  "dependencies": {
+    "echarts": "^5.5.1",
+    "@resvg/resvg-js": "^2.6.2"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/runtime/actions-core.mjs

@@ -0,0 +1,115 @@
+// actions-core.mjs — universal actions every Loreto skill bundle gets for free,
+// regardless of whether the skill ships executable code. These wrap the skill
+// package (SKILL.md, references/, tests/) so the same CLI works for a pure
+// knowledge skill and for a code-bearing one like echarts.
+
+import { readFileSync, existsSync, readdirSync, mkdirSync, cpSync, writeFileSync } from 'node:fs';
+import { join, basename } from 'node:path';
+import { homedir } from 'node:os';
+import { spawnSync } from 'node:child_process';
+
+function refsDir(ctx) {
+  return join(ctx.skillDir, 'references');
+}
+
+export function makeCoreActions(ctx) {
+  const { manifest, skillDir } = ctx;
+
+  return [
+    {
+      name: 'info',
+      summary: 'Print this skill\'s name, version, and description',
+      args: [],
+      run() {
+        const lines = [
+          `${manifest.name}  (v${manifest.version || '0.0.0'})`,
+          `slug:    ${manifest.slug}`,
+          `command: /${manifest.command}`,
+          '',
+          (manifest.description || '').trim(),
+        ];
+        return { text: lines.join('\n') };
+      },
+    },
+
+    {
+      name: 'docs',
+      summary: 'Print the skill\'s SKILL.md (the agent-facing instructions)',
+      args: [],
+      run() {
+        const p = join(skillDir, 'SKILL.md');
+        if (!existsSync(p)) return { text: 'No SKILL.md found in this bundle.' };
+        return { text: readFileSync(p, 'utf8') };
+      },
+    },
+
+    {
+      name: 'refs',
+      summary: 'List reference docs, or print one with --name <file>',
+      args: [{ name: 'name', help: 'Reference filename to print (e.g. chart-type-recipes.md)' }],
+      run(opts) {
+        const dir = refsDir(ctx);
+        if (!existsSync(dir)) return { text: 'This skill has no references/ folder.' };
+        const files = readdirSync(dir).filter((f) => f.endsWith('.md')).sort();
+        if (!opts.name) {
+          return { text: ['References:', ...files.map((f) => `  - ${f}`)].join('\n') };
+        }
+        const match = files.find((f) => f === opts.name || f === `${opts.name}.md`);
+        if (!match) return { text: `No reference named "${opts.name}". Available: ${files.join(', ')}` };
+        return { text: readFileSync(join(dir, match), 'utf8') };
+      },
+    },
+
+    {
+      name: 'install',
+      summary: 'Install the skill into ~/.claude/skills and register the /slash command',
+      args: [
+        { name: 'dir', help: 'Target Claude config dir', default: join(homedir(), '.claude') },
+        { name: 'dry-run', type: 'boolean', help: 'Show what would happen without writing' },
+        { name: 'force', type: 'boolean', help: 'Overwrite an existing install' },
+      ],
+      run(opts) {
+        const claudeDir = opts['dir'];
+        const skillsTarget = join(claudeDir, 'skills', manifest.slug);
+        const cmdTarget = join(claudeDir, 'commands', `${manifest.command}.md`);
+        const cmdSource = join(ctx.bundleDir, 'command.md');
+        const plan = [
+          `skill   → ${skillsTarget}`,
+          `command → ${cmdTarget}  (invoke with /${manifest.command})`,
+        ];
+        if (opts['dry-run']) {
+          return { text: ['[dry-run] would install:', ...plan.map((l) => '  ' + l)].join('\n') };
+        }
+        if (existsSync(skillsTarget) && !opts.force) {
+          return { text: `Already installed at ${skillsTarget}. Re-run with --force to overwrite.` };
+        }
+        mkdirSync(join(claudeDir, 'skills'), { recursive: true });
+        mkdirSync(join(claudeDir, 'commands'), { recursive: true });
+        cpSync(skillDir, skillsTarget, { recursive: true });
+        if (existsSync(cmdSource)) {
+          writeFileSync(cmdTarget, readFileSync(cmdSource, 'utf8'));
+        }
+        return { text: ['Installed:', ...plan.map((l) => '  ' + l)].join('\n') };
+      },
+    },
+
+    {
+      name: 'test',
+      summary: 'Run the skill\'s bundled test script',
+      args: [],
+      run() {
+        const t = manifest.test;
+        if (!t || !t.cmd || !t.cmd.length) return { text: 'This skill bundles no test command.' };
+        const [bin, ...rest] = t.cmd;
+        const r = spawnSync(bin, rest, { cwd: ctx.skillDir, stdio: 'inherit' });
+        if (r.error) return { text: `Could not run test (${bin}): ${r.error.message}` };
+        if (r.status !== 0) {
+          const e = new Error(`test exited with code ${r.status}`);
+          e.exitCode = r.status || 1;
+          throw e;
+        }
+        return { text: `\nTest passed (${basename(bin)} ${rest.join(' ')}).` };
+      },
+    },
+  ];
+}

package/runtime/argparse.mjs

@@ -0,0 +1,70 @@
+// argparse.mjs — tiny, zero-dependency flag + positional parser.
+//
+// Supports:  --key value   --flag   --no-flag   and bare positionals.
+// `spec` maps a flag name to { boolean, alias }.
+
+export function parseArgv(argv, spec = {}) {
+  const aliases = {};
+  for (const [name, s] of Object.entries(spec)) {
+    if (s.alias) aliases[s.alias] = name;
+  }
+  const out = { _: [] };
+  for (let i = 0; i < argv.length; i++) {
+    const tok = argv[i];
+    if (tok === '--') {
+      out._.push(...argv.slice(i + 1));
+      break;
+    }
+    if (tok.startsWith('--') || tok.startsWith('-')) {
+      let key = tok.replace(/^-+/, '');
+      let value = undefined;
+      const eq = key.indexOf('=');
+      if (eq !== -1) {
+        value = key.slice(eq + 1);
+        key = key.slice(0, eq);
+      }
+      let negated = false;
+      if (key.startsWith('no-')) {
+        negated = true;
+        key = key.slice(3);
+      }
+      if (aliases[key]) key = aliases[key];
+      const s = spec[key] || {};
+      if (s.boolean) {
+        out[key] = !negated;
+      } else if (value !== undefined) {
+        out[key] = value;
+      } else {
+        out[key] = argv[++i];
+      }
+    } else {
+      out._.push(tok);
+    }
+  }
+  return out;
+}
+
+// Build a flag spec object from an action's `args` schema.
+export function specFromArgs(args = []) {
+  const spec = {};
+  for (const a of args) spec[a.name] = { boolean: a.type === 'boolean', alias: a.alias };
+  return spec;
+}
+
+// Coerce parsed flags + positionals into a clean options object, applying
+// defaults and mapping leading positionals onto required args by order.
+export function coerce(parsed, args = []) {
+  const opts = {};
+  const positional = [...parsed._];
+  for (const a of args) {
+    if (a.name in parsed) {
+      opts[a.name] = parsed[a.name];
+    } else if (a.required && positional.length) {
+      opts[a.name] = positional.shift();
+    } else if (a.default !== undefined) {
+      opts[a.name] = a.default;
+    }
+  }
+  opts._ = positional;
+  return opts;
+}

package/runtime/cli-runner.mjs

@@ -0,0 +1,112 @@
+// cli-runner.mjs — the generic CLI dispatcher every bundle's bin/cli.mjs delegates to.
+//
+// It discovers the bundle from the bin file's location, loads the manifest,
+// merges universal actions with any skill-specific actions (actions.mjs), and
+// dispatches the first positional as the sub-command. `mcp` hands off to the
+// stdio MCP server so the *same* action set is exposed to MCP clients.
+
+import { readFileSync, existsSync } from 'node:fs';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { dirname, resolve, join } from 'node:path';
+import { parseArgv, specFromArgs, coerce } from './argparse.mjs';
+import { makeCoreActions } from './actions-core.mjs';
+
+export async function loadBundle(binUrl) {
+  const bundleDir = resolve(dirname(fileURLToPath(binUrl)), '..');
+  const manifest = JSON.parse(readFileSync(join(bundleDir, 'loreto.skill.json'), 'utf8'));
+  const skillDir = join(bundleDir, manifest.skillDir || 'skill');
+  const ctx = { bundleDir, skillDir, manifest };
+
+  let skillActions = [];
+  const actionsPath = join(bundleDir, 'actions.mjs');
+  if (existsSync(actionsPath)) {
+    const mod = await import(pathToFileURL(actionsPath).href);
+    skillActions = await mod.makeActions(ctx);
+  }
+  // Skill-specific actions first so they take precedence in help ordering.
+  const actions = [...skillActions, ...makeCoreActions(ctx)];
+  return { ctx, actions };
+}
+
+function printHelp(manifest, actions) {
+  const lines = [
+    `${manifest.name}`,
+    (manifest.description || '').trim().split('\n')[0],
+    '',
+    `Usage:  ${manifest.bin} <command> [options]`,
+    '',
+    'Commands:',
+  ];
+  for (const a of actions) {
+    lines.push(`  ${a.name.padEnd(12)} ${a.summary}`);
+  }
+  lines.push(`  ${'mcp'.padEnd(12)} Start the MCP server (stdio) exposing these as tools`);
+  lines.push('');
+  lines.push(`Run "${manifest.bin} <command> --help" for command options.`);
+  return lines.join('\n');
+}
+
+function printActionHelp(manifest, action) {
+  const lines = [`${manifest.bin} ${action.name} — ${action.summary}`, ''];
+  if (action.args.length) {
+    lines.push('Options:');
+    for (const a of action.args) {
+      const flag = a.type === 'boolean' ? `--${a.name}` : `--${a.name} <value>`;
+      const req = a.required ? ' (required)' : '';
+      lines.push(`  ${flag.padEnd(22)} ${a.help || ''}${req}`);
+    }
+  } else {
+    lines.push('(no options)');
+  }
+  return lines.join('\n');
+}
+
+export async function runCli(binUrl) {
+  const { ctx, actions } = await loadBundle(binUrl);
+  const { manifest } = ctx;
+  const argv = process.argv.slice(2);
+  const cmd = argv[0];
+
+  if (!cmd || cmd === 'help' || cmd === '--help' || cmd === '-h') {
+    console.log(printHelp(manifest, actions));
+    return;
+  }
+
+  if (cmd === 'mcp') {
+    const { runMcp } = await import('./mcp-runner.mjs');
+    await runMcp(ctx, actions);
+    return;
+  }
+
+  const action = actions.find((a) => a.name === cmd);
+  if (!action) {
+    console.error(`Unknown command: ${cmd}\n`);
+    console.error(printHelp(manifest, actions));
+    process.exit(2);
+  }
+
+  const rest = argv.slice(1);
+  if (rest.includes('--help') || rest.includes('-h')) {
+    console.log(printActionHelp(manifest, action));
+    return;
+  }
+
+  const parsed = parseArgv(rest, specFromArgs(action.args));
+  const opts = coerce(parsed, action.args);
+
+  for (const a of action.args) {
+    if (a.required && (opts[a.name] === undefined || opts[a.name] === '')) {
+      console.error(`Missing required option: --${a.name}\n`);
+      console.error(printActionHelp(manifest, action));
+      process.exit(2);
+    }
+  }
+
+  try {
+    const res = await action.run(opts, ctx);
+    if (res && res.text) console.log(res.text);
+  } catch (e) {
+    console.error(`Error: ${e.message}`);
+    process.exit(e.exitCode || 1);
+  }
+}

package/runtime/mcp-runner.mjs

@@ -0,0 +1,96 @@
+// mcp-runner.mjs — a minimal, dependency-free MCP server over stdio.
+//
+// Implements just enough of the Model Context Protocol (JSON-RPC 2.0,
+// newline-delimited messages) to expose each skill action as an MCP tool:
+//   initialize · tools/list · tools/call · ping · notifications/*
+//
+// Production note: for the shipped product this can be swapped for the official
+// @modelcontextprotocol/sdk; the action→tool mapping below is the stable part.
+
+const PROTOCOL_VERSION = '2024-11-05';
+
+function inputSchema(action) {
+  const properties = {};
+  const required = [];
+  for (const a of action.args || []) {
+    properties[a.name] = {
+      type: a.type === 'boolean' ? 'boolean' : 'string',
+      description: a.help || '',
+    };
+    if (a.required) required.push(a.name);
+  }
+  return { type: 'object', properties, required };
+}
+
+function toolName(ctx, action) {
+  // Namespaced so multiple skill MCP servers can coexist in one client.
+  return `${ctx.manifest.command}.${action.name}`;
+}
+
+export async function runMcp(ctx, actions) {
+  // `mcp`, `install`, and `test` are operational CLI concerns; expose the rest
+  // (skill capabilities + read-only introspection) as tools.
+  const exposed = actions.filter((a) => !['install'].includes(a.name));
+
+  const send = (msg) => process.stdout.write(JSON.stringify(msg) + '\n');
+  const reply = (id, result) => send({ jsonrpc: '2.0', id, result });
+  const fail = (id, code, message) => send({ jsonrpc: '2.0', id, error: { code, message } });
+
+  async function handle(req) {
+    const { id, method, params } = req;
+    if (method === 'initialize') {
+      return reply(id, {
+        protocolVersion: PROTOCOL_VERSION,
+        capabilities: { tools: {} },
+        serverInfo: { name: `loreto-skill:${ctx.manifest.slug}`, version: ctx.manifest.version || '0.0.0' },
+      });
+    }
+    if (method === 'ping') return reply(id, {});
+    if (method && method.startsWith('notifications/')) return; // no response for notifications
+    if (method === 'tools/list') {
+      return reply(id, {
+        tools: exposed.map((a) => ({
+          name: toolName(ctx, a),
+          description: a.summary,
+          inputSchema: inputSchema(a),
+        })),
+      });
+    }
+    if (method === 'tools/call') {
+      const name = params?.name;
+      const action = exposed.find((a) => toolName(ctx, a) === name || a.name === name);
+      if (!action) return fail(id, -32602, `Unknown tool: ${name}`);
+      try {
+        const res = await action.run(params?.arguments || {}, ctx);
+        const text = (res && res.text) || '(no output)';
+        return reply(id, { content: [{ type: 'text', text }], isError: false });
+      } catch (e) {
+        return reply(id, { content: [{ type: 'text', text: `Error: ${e.message}` }], isError: true });
+      }
+    }
+    if (id !== undefined) return fail(id, -32601, `Method not found: ${method}`);
+  }
+
+  let buffer = '';
+  process.stdin.setEncoding('utf8');
+  process.stdin.on('data', (chunk) => {
+    buffer += chunk;
+    let nl;
+    while ((nl = buffer.indexOf('\n')) !== -1) {
+      const line = buffer.slice(0, nl).trim();
+      buffer = buffer.slice(nl + 1);
+      if (!line) continue;
+      let req;
+      try {
+        req = JSON.parse(line);
+      } catch {
+        continue;
+      }
+      Promise.resolve(handle(req)).catch((e) => {
+        if (req && req.id !== undefined) fail(req.id, -32603, e.message);
+      });
+    }
+  });
+  // Keep the process alive until stdin closes.
+  await new Promise((resolve) => process.stdin.on('end', resolve));
+}