@xvml/cli 0.1.0

package/dist/bin/xvml.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { runCli } from '../src/cli.js';
+runCli();

package/dist/src/agent.js

@@ -0,0 +1,85 @@
+import { Anthropic } from '@anthropic-ai/sdk';
+import fs from 'fs/promises';
+import path from 'path';
+import { fileURLToPath } from 'url';
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+// Loaded once per process, cached here.
+let cachedSpec = null;
+async function loadSpec() {
+    if (cachedSpec)
+        return cachedSpec;
+    // ts-node:  src/agent.ts  → __dirname = .../src/   → ../XVML_SPEC.md = project root
+    // compiled: dist/src/agent.js → __dirname = .../dist/src/ → ../../XVML_SPEC.md = dist/ (copied by build)
+    const candidates = [
+        path.resolve(__dirname, '../XVML_SPEC.md'),
+        path.resolve(__dirname, '../../XVML_SPEC.md'),
+    ];
+    for (const p of candidates) {
+        try {
+            cachedSpec = await fs.readFile(p, 'utf-8');
+            return cachedSpec;
+        }
+        catch { /* try next */ }
+    }
+    throw new Error(`XVML_SPEC.md not found. Searched:\n${candidates.join('\n')}\n` +
+        'Run "npm run build" to copy XVML_SPEC.md into dist/.');
+}
+const SYSTEM_PROMPT_PREFIX = `\
+You are a XVML page generator. XVML (eXpressive Visual Markup Language) is a plain-text format that renders as live UI.
+
+Below is the complete XVML specification — every command, its arguments, and the HTML it produces.
+You must follow it exactly. Output only valid XVML. No markdown fences, no explanation, no prose.
+
+Rules you must never break:
+- Every command starts with @ on its own line
+- String arguments use double quotes: "value"
+- Modifier/keyword arguments are bare words: primary, muted, striped
+- Block commands must be closed with @end (or @@end inside @codeblock)
+- Do NOT use @if @each @bind @on:click @event @agent — they are reserved and cause parse errors
+- Do NOT emit raw HTML — only XVML commands
+- Always start the file with @page, optionally preceded by @spec and @meta
+- Put content inside @card ... @end blocks
+- Use @cols for side-by-side layouts, @layout inline for inline button rows
+- Use @stats / @stat-row for metric grids
+- Use @table for tabular data (first @row is the header)
+- For @alert: variant keyword (info/warn/error/success) comes BEFORE the message string
+- For @stat: value (big display number) is the first string, label is the second
+- For @field: type keyword (email/password/text/number) comes before the label string
+- For @codeblock: close with @@end (not @end) if the code inside contains @end lines
+
+--- XVML_SPEC.md ---
+`;
+export async function askClaude(task, options = {}) {
+    const key = process.env['ANTHROPIC_API_KEY'];
+    if (!key) {
+        throw new Error('ANTHROPIC_API_KEY is not set.\n' +
+            'Export it before running: export ANTHROPIC_API_KEY=sk-ant-...');
+    }
+    const spec = await loadSpec();
+    const system = SYSTEM_PROMPT_PREFIX + spec;
+    const client = new Anthropic({ apiKey: key });
+    const response = await client.messages.create({
+        model: options.model ?? 'claude-sonnet-4-6',
+        max_tokens: 4096,
+        temperature: 0,
+        system,
+        messages: [
+            {
+                role: 'user',
+                content: `Generate a XVML page for the following task:\n\n${task}`,
+            },
+        ],
+    });
+    const block = response.content[0];
+    if (block.type !== 'text')
+        throw new Error('Unexpected non-text response from Claude');
+    return block.text.trim();
+}
+// Derive a safe filename slug from the task description.
+export function slugify(task) {
+    return task
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '')
+        .slice(0, 48) || 'page';
+}

package/dist/src/cli.js

@@ -0,0 +1,252 @@
+import { Command } from 'commander';
+import chalk from 'chalk';
+import fs from 'fs/promises';
+import { watch as fsWatch } from 'fs';
+import path from 'path';
+import fse from 'fs-extra';
+import { renderFile, outputPath } from './renderer.js';
+import { parse, ParseError } from './parser.js';
+import { askClaude, slugify } from './agent.js';
+const XVMLRC_DEFAULT = JSON.stringify({ outDir: 'docs', spec: 1 }, null, 2);
+async function findVmlFiles(dir) {
+    const SKIP = new Set(['node_modules', 'docs', 'dist', '.git']);
+    const files = [];
+    const entries = await fs.readdir(dir, { withFileTypes: true });
+    for (const entry of entries) {
+        if (SKIP.has(entry.name) || entry.name.startsWith('.'))
+            continue;
+        const full = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+            files.push(...await findVmlFiles(full));
+        }
+        else if (entry.name.endsWith('.xvml')) {
+            files.push(full);
+        }
+    }
+    return files;
+}
+async function doRender(file) {
+    const out = outputPath(file);
+    const html = await renderFile(file);
+    await fse.outputFile(out, html, 'utf-8');
+    console.log(`${chalk.green('✓')} ${chalk.dim(file)} → ${chalk.cyan(out)}`);
+}
+async function doCheck(file) {
+    try {
+        const source = await fs.readFile(file, 'utf-8');
+        parse(source);
+        console.log(`${chalk.green('✓')} ${file}`);
+        return true;
+    }
+    catch (err) {
+        if (err instanceof ParseError) {
+            console.error(`${chalk.red('✕')} ${file}: ${chalk.red(err.message)}`);
+        }
+        else {
+            const msg = err instanceof Error ? err.message : String(err);
+            console.error(`${chalk.red('✕')} ${file}: ${msg}`);
+        }
+        return false;
+    }
+}
+export function buildCli() {
+    const program = new Command();
+    program
+        .name('xvml')
+        .description('Renders .xvml files into deterministic self-contained HTML')
+        .version('1.0.0');
+    // xvml render <file> [--watch]
+    program
+        .command('render <file>')
+        .description('Render a .xvml file to docs/<file>.html')
+        .option('-w, --watch', 're-render on file change')
+        .action(async (file, opts) => {
+        try {
+            await doRender(file);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            console.error(`${chalk.red('Error:')} ${msg}`);
+            process.exit(1);
+        }
+        if (opts.watch) {
+            console.log(chalk.dim(`Watching ${file} for changes…`));
+            let debounce = null;
+            fsWatch(file, { persistent: true }, () => {
+                if (debounce)
+                    clearTimeout(debounce);
+                debounce = setTimeout(async () => {
+                    try {
+                        await doRender(file);
+                    }
+                    catch (err) {
+                        const msg = err instanceof Error ? err.message : String(err);
+                        console.error(`${chalk.red('Error:')} ${msg}`);
+                    }
+                }, 100);
+            });
+        }
+    });
+    // xvml check <file|glob...>
+    program
+        .command('check <patterns...>')
+        .description('Check .xvml files for spec compliance')
+        .action(async (patterns) => {
+        let passed = 0;
+        let failed = 0;
+        for (const pattern of patterns) {
+            const stat = await fs.stat(pattern).catch(() => null);
+            if (stat?.isDirectory()) {
+                const files = await findVmlFiles(pattern);
+                for (const f of files) {
+                    (await doCheck(f)) ? passed++ : failed++;
+                }
+            }
+            else if (pattern.endsWith('.xvml')) {
+                (await doCheck(pattern)) ? passed++ : failed++;
+            }
+        }
+        const total = passed + failed;
+        if (total === 0) {
+            console.log(chalk.yellow('No .xvml files found.'));
+            return;
+        }
+        console.log(`\n${chalk.bold(String(total))} file${total === 1 ? '' : 's'} checked — ` +
+            `${chalk.green(String(passed))} passed, ${failed > 0 ? chalk.red(String(failed)) : chalk.dim('0')} failed`);
+        if (failed > 0)
+            process.exit(1);
+    });
+    // xvml build
+    program
+        .command('build')
+        .description('Render all .xvml files in the project to docs/')
+        .action(async () => {
+        const cwd = process.cwd();
+        const files = await findVmlFiles(cwd);
+        if (files.length === 0) {
+            console.log(chalk.yellow('No .xvml files found.'));
+            return;
+        }
+        let ok = 0;
+        let fail = 0;
+        for (const file of files) {
+            try {
+                await doRender(file);
+                ok++;
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                console.error(`${chalk.red('✕')} ${file}: ${msg}`);
+                fail++;
+            }
+        }
+        console.log(`\n${chalk.bold(String(files.length))} file${files.length === 1 ? '' : 's'} built — ` +
+            `${chalk.green(String(ok))} ok${fail > 0 ? `, ${chalk.red(String(fail))} failed` : ''}`);
+        if (fail > 0)
+            process.exit(1);
+    });
+    // xvml ask "task description" [--out filename] [--model model-id]
+    program
+        .command('ask <task>')
+        .description('Ask Claude to generate a XVML page, then render it')
+        .option('-o, --out <filename>', 'output filename without extension (default: slugified task)')
+        .option('-m, --model <model>', 'Claude model ID', 'claude-sonnet-4-6')
+        .option('--print', 'print generated XVML to stdout without saving or rendering')
+        .action(async (task, opts) => {
+        const spinner = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+        let spinIdx = 0;
+        const spinInterval = setInterval(() => {
+            process.stdout.write(`\r${chalk.cyan(spinner[spinIdx++ % spinner.length])} Asking Claude…`);
+        }, 80);
+        let xvml;
+        try {
+            xvml = await askClaude(task, { model: opts.model });
+        }
+        catch (err) {
+            clearInterval(spinInterval);
+            process.stdout.write('\r');
+            const msg = err instanceof Error
+                ? err.message
+                : typeof err === 'object' && err !== null && 'message' in err
+                    ? String(err['message'])
+                    : String(err);
+            console.error(`${chalk.red('Error:')} ${msg}`);
+            process.exit(1);
+        }
+        clearInterval(spinInterval);
+        process.stdout.write('\r');
+        if (opts.print) {
+            console.log(xvml);
+            return;
+        }
+        // Validate before writing — fail fast with a clear parse error.
+        try {
+            parse(xvml);
+        }
+        catch (err) {
+            const msg = err instanceof ParseError ? err.message : String(err);
+            console.error(`${chalk.red('Parse error in generated XVML:')} ${msg}`);
+            console.error(chalk.dim('Generated XVML:\n') + chalk.dim(xvml));
+            process.exit(1);
+        }
+        const slug = opts.out ?? slugify(task);
+        const xvmlPath = path.join('examples', `${slug}.xvml`);
+        await fse.outputFile(xvmlPath, xvml, 'utf-8');
+        console.log(`${chalk.green('✓')} ${chalk.dim('saved')} ${chalk.cyan(xvmlPath)}`);
+        try {
+            await doRender(xvmlPath);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            console.error(`${chalk.red('Render error:')} ${msg}`);
+            process.exit(1);
+        }
+    });
+    // xvml init
+    program
+        .command('init')
+        .description('Create CLAUDE.md and .xvmlrc in the current directory')
+        .action(async () => {
+        const cwd = process.cwd();
+        const xvmlrcPath = path.join(cwd, '.xvmlrc');
+        if (await fse.pathExists(xvmlrcPath)) {
+            console.log(chalk.yellow('.xvmlrc already exists — skipping'));
+        }
+        else {
+            await fs.writeFile(xvmlrcPath, XVMLRC_DEFAULT, 'utf-8');
+            console.log(`${chalk.green('✓')} Created ${chalk.cyan('.xvmlrc')}`);
+        }
+        const claudePath = path.join(cwd, 'CLAUDE.md');
+        if (await fse.pathExists(claudePath)) {
+            console.log(chalk.yellow('CLAUDE.md already exists — skipping'));
+        }
+        else {
+            const content = [
+                '# xvml',
+                '',
+                '- All UI pages must be written as `.xvml` files, never raw `.html`',
+                '- After creating any `.xvml` file, always run: `xvml render <file>`',
+                '- Output rendered files go to `/docs` folder',
+                '- TypeScript only, strict mode, no `any` types',
+                '- No external CDN in rendered HTML output',
+                '- Rendered HTML must be fully self-contained (CSS + JS inline)',
+                '- Deterministic rendering — same `.xvml` input always produces identical HTML',
+                '- Temperature `0` on all Claude API calls',
+            ].join('\n');
+            await fs.writeFile(claudePath, content, 'utf-8');
+            console.log(`${chalk.green('✓')} Created ${chalk.cyan('CLAUDE.md')}`);
+        }
+    });
+    return program;
+}
+export function runCli() {
+    buildCli().parseAsync(process.argv).catch((err) => {
+        const msg = err instanceof Error
+            ? err.message
+            : typeof err === 'object' && err !== null && 'message' in err
+                ? String(err['message'])
+                : String(err);
+        console.error(`${chalk.red('Error:')} ${msg}`);
+        process.exit(1);
+    });
+}

package/dist/src/index.js

@@ -0,0 +1,4 @@
+// Programmatic API — use this when importing @xvml/cli as a library rather than a CLI tool.
+export { renderSource, renderFile, outputPath } from './renderer.js';
+export { parse, ParseError } from './parser.js';
+export { askClaude, slugify } from './agent.js';

package/dist/src/parser.js

@@ -0,0 +1,256 @@
+export class ParseError extends Error {
+    line;
+    constructor(message, line) {
+        super(line !== undefined ? `Line ${line}: ${message}` : message);
+        this.line = line;
+        this.name = 'ParseError';
+    }
+}
+const BLOCK_COMMANDS = new Set([
+    'card', 'section', 'cols', 'stat-row', 'stats', 'list', 'table', 'codeblock', 'theme',
+]);
+const DOC_DIRECTIVE_COMMANDS = new Set([
+    'spec', 'file', 'meta', 'renderer', 'page',
+]);
+const RESERVED_COMMANDS = new Set([
+    'if', 'each', 'bind', 'on:click', 'event', 'agent',
+]);
+const KNOWN_COMMANDS = new Set([
+    // layout
+    'page', 'card', 'end', 'section', 'layout', 'cols',
+    // content
+    'title', 'subtitle', 'text', 'divider', 'badge',
+    // navigation / presentation
+    'nav', 'avatar',
+    // form
+    'field', 'button', 'checkbox', 'select', 'link',
+    // data
+    'table', 'row', 'stat', 'stat-row', 'stats', 'progress', 'list', 'item',
+    // code
+    'codeblock', 'constraint', 'alert',
+    // meta
+    'spec', 'file', 'meta', 'import', 'theme', 'renderer',
+]);
+// Theme names — keywords that identify themes, not page names
+const THEME_KEYWORDS = new Set(['light', 'dark', 'system']);
+function parseArgs(argStr, lineNum) {
+    const args = [];
+    let i = 0;
+    while (i < argStr.length) {
+        const ch = argStr[i];
+        if (ch === ' ' || ch === '\t') {
+            i++;
+            continue;
+        }
+        if (ch === '"') {
+            // Quoted string
+            let j = i + 1;
+            while (j < argStr.length && argStr[j] !== '"')
+                j++;
+            if (j >= argStr.length)
+                throw new ParseError('Unterminated string argument', lineNum);
+            args.push({ type: 'string', value: argStr.slice(i + 1, j) });
+            i = j + 1;
+        }
+        else {
+            // Bare token — may be keyword, number, or key=value / key="value"
+            let j = i;
+            while (j < argStr.length && argStr[j] !== ' ' && argStr[j] !== '\t' && argStr[j] !== '=')
+                j++;
+            if (j < argStr.length && argStr[j] === '=') {
+                // key=value or key="value"
+                const key = argStr.slice(i, j);
+                j++; // skip '='
+                if (j < argStr.length && argStr[j] === '"') {
+                    // key="quoted value"
+                    let k = j + 1;
+                    while (k < argStr.length && argStr[k] !== '"')
+                        k++;
+                    if (k >= argStr.length)
+                        throw new ParseError(`Unterminated value for key "${key}"`, lineNum);
+                    args.push({ type: 'keyvalue', key, value: argStr.slice(j + 1, k) });
+                    i = k + 1;
+                }
+                else {
+                    // key=bare_value
+                    let k = j;
+                    while (k < argStr.length && argStr[k] !== ' ' && argStr[k] !== '\t')
+                        k++;
+                    args.push({ type: 'keyvalue', key, value: argStr.slice(j, k) });
+                    i = k;
+                }
+            }
+            else {
+                const token = argStr.slice(i, j);
+                const num = Number(token);
+                if (token !== '' && !isNaN(num)) {
+                    args.push({ type: 'number', value: num });
+                }
+                else {
+                    args.push({ type: 'keyword', value: token });
+                }
+                i = j;
+            }
+        }
+    }
+    return args;
+}
+function parseThemeVars(rawLines, lineNum) {
+    const vars = {};
+    for (const line of rawLines) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        const a = parseArgs(trimmed, lineNum);
+        const k = a[0];
+        const v = a[1];
+        if (k?.type === 'string' && v?.type === 'string') {
+            vars[k.value] = v.value;
+        }
+    }
+    return vars;
+}
+function handleDocDirective(doc, cmd, args) {
+    switch (cmd) {
+        case 'spec': {
+            const a = args[0];
+            if (a?.type === 'number')
+                doc.specVersion = a.value;
+            break;
+        }
+        case 'file': {
+            const a = args[0];
+            if (a?.type === 'string')
+                doc.filePath = a.value;
+            break;
+        }
+        case 'meta': {
+            const k = args[0];
+            const v = args[1];
+            if (k?.type === 'string' && v?.type === 'string') {
+                doc.metaTags.push({ key: k.value, value: v.value });
+            }
+            break;
+        }
+        case 'renderer': {
+            for (const a of args) {
+                if (a.type === 'keyword')
+                    doc.rendererFlags.add(a.value);
+            }
+            break;
+        }
+        case 'page': {
+            // First arg may be a quoted title OR a bare page-name keyword.
+            // Any light/dark/system keyword is the theme; other keywords become the title.
+            let title = 'Page';
+            let theme = '';
+            for (const a of args) {
+                if (a.type === 'string') {
+                    title = a.value;
+                }
+                else if (a.type === 'keyword') {
+                    if (THEME_KEYWORDS.has(a.value)) {
+                        theme = a.value;
+                    }
+                    else {
+                        // bare page-name keyword → capitalize
+                        title = a.value.charAt(0).toUpperCase() + a.value.slice(1);
+                    }
+                }
+            }
+            doc.page = { title, theme };
+            break;
+        }
+    }
+}
+export function parse(source) {
+    const doc = {
+        specVersion: 1,
+        filePath: null,
+        metaTags: [],
+        rendererFlags: new Set(),
+        page: null,
+        themes: [],
+        body: [],
+    };
+    const lines = source.split('\n');
+    const stack = [];
+    let rawMode = false;
+    let themeMode = false;
+    for (let idx = 0; idx < lines.length; idx++) {
+        const lineNum = idx + 1;
+        const raw = lines[idx];
+        const trimmed = raw.trim();
+        if (trimmed === '')
+            continue;
+        if (trimmed.startsWith('@#'))
+            continue;
+        if (rawMode) {
+            // @@end is the exclusive raw-mode sentinel so literal @end can appear inside codeblocks.
+            if (trimmed === '@@end') {
+                rawMode = false;
+                stack.pop();
+            }
+            else {
+                stack[stack.length - 1]?.rawLines.push(raw);
+            }
+            continue;
+        }
+        if (themeMode) {
+            if (trimmed === '@end') {
+                themeMode = false;
+                const themeNode = stack.pop();
+                if (themeNode) {
+                    const nameArg = themeNode.args[0];
+                    const name = nameArg?.type === 'string' ? nameArg.value : 'default';
+                    doc.themes.push({ name, vars: parseThemeVars(themeNode.rawLines, lineNum) });
+                }
+            }
+            else if (!trimmed.startsWith('@')) {
+                stack[stack.length - 1]?.rawLines.push(trimmed);
+            }
+            continue;
+        }
+        if (!trimmed.startsWith('@'))
+            continue;
+        const spaceIdx = trimmed.indexOf(' ');
+        const cmdRaw = spaceIdx === -1 ? trimmed.slice(1) : trimmed.slice(1, spaceIdx);
+        const argStr = spaceIdx === -1 ? '' : trimmed.slice(spaceIdx + 1).trim();
+        const cmd = cmdRaw.toLowerCase();
+        if (cmd === 'end') {
+            if (stack.length === 0)
+                throw new ParseError('@end without open block', lineNum);
+            stack.pop();
+            continue;
+        }
+        if (RESERVED_COMMANDS.has(cmd)) {
+            throw new ParseError(`@${cmd} is reserved for future XVML versions`, lineNum);
+        }
+        if (!KNOWN_COMMANDS.has(cmd)) {
+            throw new ParseError(`Unknown command: @${cmd}`, lineNum);
+        }
+        const args = parseArgs(argStr, lineNum);
+        if (DOC_DIRECTIVE_COMMANDS.has(cmd)) {
+            handleDocDirective(doc, cmd, args);
+            continue;
+        }
+        const node = { command: cmd, args, children: [], rawLines: [] };
+        if (stack.length > 0) {
+            stack[stack.length - 1].children.push(node);
+        }
+        else {
+            doc.body.push(node);
+        }
+        if (BLOCK_COMMANDS.has(cmd)) {
+            stack.push(node);
+            if (cmd === 'codeblock')
+                rawMode = true;
+            if (cmd === 'theme')
+                themeMode = true;
+        }
+    }
+    if (stack.length > 0) {
+        throw new ParseError(`Unclosed block: @${stack[stack.length - 1].command}`);
+    }
+    return doc;
+}