@vielzeug/codex 1.0.2

package/dist/tools/refine.js

@@ -0,0 +1,329 @@
+import { ToolError } from '../errors.js';
+import { parseArgs } from './schema.js';
+import { text } from './shared.js';
+// Every tool in this file is refine-specific — named with a `refine-` prefix so the
+// tool list itself signals which tools are generic (packages.ts) vs. bound to one
+// package's structured component metadata (this file). Backed by the real Custom
+// Elements Manifest generated from refine's build output — never hand-duplicated data,
+// so it can't drift the way the old ore-directives/spell-validators/sandbox tools did.
+const REFINE_UNAVAILABLE = 'Refine component metadata is unavailable in this snapshot. If using the monorepo, build /refine first then run prepare:data. Published releases include this data automatically.';
+/** Every refine tool needs at least one bundled component; throws UNAVAILABLE otherwise. */
+function requireAnyComponent(context) {
+    if (context.refineComponents.length === 0)
+        throw new ToolError('UNAVAILABLE', REFINE_UNAVAILABLE);
+    return context.refineComponents;
+}
+/** Resolves one component by tag name, or throws UNAVAILABLE/NOT_FOUND. */
+function requireComponent(context, tagName) {
+    const components = requireAnyComponent(context);
+    const decl = components.find((d) => d.tagName === tagName);
+    if (!decl) {
+        throw new ToolError('NOT_FOUND', `Component "${tagName}" not found. Available tags: ${context.refineComponentTags.join(', ')}`);
+    }
+    return decl;
+}
+// ---------------------------------------------------------------------------
+// refine-list-components
+// ---------------------------------------------------------------------------
+const listComponentsSchema = { properties: {}, type: 'object' };
+export const listComponentsTool = {
+    description: 'List all @vielzeug/refine web component tags from bundled Custom Elements Manifest (CEM) metadata. Returns a JSON array with tagName, description, and attrs (name, type, default). Use this to discover available components before calling refine-get-component for full details. Returns isError if refine was not built before data generation.',
+    inputSchema: listComponentsSchema,
+    name: 'refine-list-components',
+    run(_args, context) {
+        const components = requireAnyComponent(context);
+        const tags = components
+            .filter((d) => d.tagName)
+            .map((d) => ({
+            attrs: (d.attributes ?? []).map((a) => ({
+                name: a.name,
+                type: a.type?.text ?? 'string',
+                ...(a.default !== undefined && { default: a.default }),
+            })),
+            description: d.description ?? '',
+            tagName: d.tagName,
+        }));
+        return text(JSON.stringify(tags, null, 2));
+    },
+};
+// ---------------------------------------------------------------------------
+// refine-get-component
+// ---------------------------------------------------------------------------
+const getComponentSchema = {
+    properties: {
+        tagName: {
+            description: 'HTML custom element tag, e.g. "ore-button"',
+            maxLength: 100,
+            minLength: 1,
+            type: 'string',
+        },
+    },
+    required: ['tagName'],
+    type: 'object',
+};
+export const getComponentTool = {
+    description: 'Get the full Custom Elements Manifest (CEM) declaration for a single @vielzeug/refine component by its HTML tag name (e.g. "ore-button"). Returns a JSON object with attributes, events, slots, CSS parts, CSS properties, and member methods. Call refine-list-components first to get valid tag names.',
+    inputSchema: getComponentSchema,
+    name: 'refine-get-component',
+    run(args, context) {
+        const { tagName } = parseArgs(getComponentSchema, args);
+        const declaration = requireComponent(context, tagName);
+        return text(JSON.stringify(declaration, null, 2));
+    },
+};
+// ---------------------------------------------------------------------------
+// refine-generate-template helpers
+// ---------------------------------------------------------------------------
+function attributeSnippet(attr) {
+    const typeText = attr.type?.text ?? '';
+    if (typeText === 'boolean')
+        return attr.name;
+    // Literal union e.g. 'primary' | 'secondary' — use the first literal
+    const firstLiteral = /^['"](\S+?)['"]/.exec(typeText);
+    if (firstLiteral)
+        return `${attr.name}="${firstLiteral[1]}"`;
+    if (attr.default !== undefined && attr.default !== 'undefined' && attr.default !== '')
+        return `${attr.name}="${attr.default}"`;
+    return `${attr.name}=""`;
+}
+function buildTemplate(decl, scenario) {
+    const tag = decl.tagName ?? '';
+    const attrs = decl.attributes ?? [];
+    const slots = decl.slots ?? [];
+    const events = decl.events ?? [];
+    const primary = attrs.filter((a) => a.default === undefined);
+    const optional = attrs.filter((a) => a.default !== undefined);
+    let attrStr = '';
+    for (const a of primary)
+        attrStr += `\n  ${attributeSnippet(a)}`;
+    const namedSlots = slots.filter((s) => s.name && s.name !== '');
+    const hasDefaultSlot = slots.length === 0 || slots.some((s) => !s.name || s.name === '');
+    let inner = '';
+    for (const s of namedSlots)
+        inner += `\n  <span slot="${s.name}">${s.description ?? s.name}</span>`;
+    if (hasDefaultSlot)
+        inner += '\n  Content goes here';
+    let comments = '';
+    if (optional.length > 0) {
+        comments += '\n  <!-- Optional attributes:';
+        for (const a of optional)
+            comments += `\n    ${attributeSnippet(a)}  (default: ${a.default ?? 'unset'})`;
+        comments += '\n  -->';
+    }
+    if (events.length > 0) {
+        comments += `\n  <!-- Events: ${events.map((e) => e.name).join(', ')} -->`;
+    }
+    const header = scenario ? `<!-- ${scenario} -->\n` : '';
+    return `${header}<${tag}${attrStr}>${comments}${inner ? inner + '\n' : ''}</${tag}>`;
+}
+// ---------------------------------------------------------------------------
+// refine-generate-template
+// ---------------------------------------------------------------------------
+const generateTemplateSchema = {
+    properties: {
+        scenario: {
+            default: '',
+            description: 'Optional usage context to include as a leading comment, e.g. "primary call-to-action button"',
+            maxLength: 200,
+            type: 'string',
+        },
+        tagName: {
+            description: 'HTML custom element tag, e.g. "ore-button"',
+            maxLength: 100,
+            minLength: 1,
+            type: 'string',
+        },
+    },
+    required: ['tagName'],
+    type: 'object',
+};
+export const generateTemplateTool = {
+    description: 'Generate a ready-to-use HTML template for a @vielzeug/refine component. Returns a snippet with required attributes filled with type-appropriate placeholders, optional attributes in a comment block, and all named slots scaffolded. Use this as the starting point for AI-generated declarative UI — avoids hallucinated attribute names. Call refine-list-components first to get valid tag names.',
+    inputSchema: generateTemplateSchema,
+    name: 'refine-generate-template',
+    run(args, context) {
+        const { scenario, tagName } = parseArgs(generateTemplateSchema, args);
+        const decl = requireComponent(context, tagName);
+        return text(buildTemplate(decl, scenario || undefined));
+    },
+};
+// ---------------------------------------------------------------------------
+// refine-get-tokens
+// ---------------------------------------------------------------------------
+const getTokensSchema = {
+    properties: {
+        filter: {
+            default: '',
+            description: 'Optional prefix to filter token names, e.g. "--refine-color". Case-insensitive.',
+            maxLength: 100,
+            type: 'string',
+        },
+    },
+    type: 'object',
+};
+export const getTokensTool = {
+    description: 'List all CSS custom properties (design tokens) exposed by @vielzeug/refine components. Returns a JSON array of { name, description, default, component } objects sorted by name. Pass an optional filter prefix (e.g. "--refine-color") to narrow results. Use when generating dynamic themes or inline styles in AI-driven UI.',
+    inputSchema: getTokensSchema,
+    name: 'refine-get-tokens',
+    run(args, context) {
+        const { filter } = parseArgs(getTokensSchema, args);
+        const components = requireAnyComponent(context);
+        const rawFilter = filter.toLowerCase();
+        // Components are iterated in stable bundled order (the order refine's CEM manifest declares
+        // them in), so first-seen-wins below is deterministic run-to-run, not arbitrary. Shared design
+        // tokens (e.g. "--refine-color-primary") are typically declared identically on every component
+        // that uses them, so keeping the first occurrence and dropping later duplicates is harmless in
+        // the common case. If two components ever document the *same* token name with genuinely
+        // different descriptions/defaults, only the first-encountered one is returned here — that's an
+        // intentional simplification (one row per token name, not per component), not a bug.
+        const seen = new Set();
+        const tokens = [];
+        for (const decl of components) {
+            const componentId = decl.tagName ?? decl.name ?? 'unknown';
+            for (const prop of decl.cssProperties ?? []) {
+                if (!prop.name || seen.has(prop.name))
+                    continue;
+                if (rawFilter && !prop.name.toLowerCase().startsWith(rawFilter))
+                    continue;
+                seen.add(prop.name);
+                tokens.push({
+                    component: componentId,
+                    ...(prop.default !== undefined && { default: prop.default }),
+                    ...(prop.description && { description: prop.description }),
+                    name: prop.name,
+                });
+            }
+        }
+        tokens.sort((a, b) => a.name.localeCompare(b.name));
+        return text(JSON.stringify(tokens, null, 2));
+    },
+};
+// ---------------------------------------------------------------------------
+// refine-validate-usage helpers
+//
+// Regex-based, deliberately — this validates a single AI-generated custom-element usage
+// snippet (one tag + attributes + slots), not arbitrary HTML documents. A real HTML parser
+// would be more correct for pathological input (attribute values containing raw `>`) but
+// adds a runtime dependency for a narrow, already-adequate check; not worth it here.
+// ---------------------------------------------------------------------------
+const SAFE_HTML_ATTRS = new Set([
+    'class',
+    'contenteditable',
+    'dir',
+    'draggable',
+    'exportparts',
+    'hidden',
+    'id',
+    'lang',
+    'part',
+    'slot',
+    'style',
+    'tabindex',
+    'title',
+]);
+const SAFE_ATTR_PREFIXES = ['aria-', 'data-', 'on'];
+/** Escapes regex metacharacters so a string can be safely interpolated into a `new RegExp(...)` pattern. */
+function escapeRegExp(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+function parseTagAttributes(html, tagName) {
+    // `tagName` is always resolved through `requireComponent` first (a fixed, real-component-tag
+    // allowlist — see every caller below), so it can never actually carry regex metacharacters or
+    // attacker-controlled content today. Escaping it here is defense-in-depth, not a fix for a
+    // currently-reachable exploit: it keeps this function safe to call with untrusted input on its
+    // own terms, independent of what its current callers happen to guarantee.
+    const pattern = new RegExp(`<${escapeRegExp(tagName)}((?:\\s[^>]*)?)(?:>|/>)`, 'i');
+    const match = pattern.exec(html);
+    if (!match)
+        return null;
+    const attrStr = match[1] ?? '';
+    const result = new Map();
+    const attrRe = /([\w-]+)(?:\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s/>]*)))?/g;
+    let m;
+    while ((m = attrRe.exec(attrStr)) !== null) {
+        const [, name, dq, sq, bare] = m;
+        if (name)
+            result.set(name.toLowerCase(), dq ?? sq ?? bare ?? '');
+    }
+    return result;
+}
+function parseSlotNames(html) {
+    const slots = [];
+    const re = /\bslot=["']([^"']+)["']/gi;
+    let m;
+    while ((m = re.exec(html)) !== null) {
+        if (m[1])
+            slots.push(m[1]);
+    }
+    return slots;
+}
+// ---------------------------------------------------------------------------
+// refine-validate-usage
+// ---------------------------------------------------------------------------
+const validateUsageSchema = {
+    properties: {
+        html: {
+            description: 'HTML fragment containing the component usage to validate (max 5000 chars)',
+            maxLength: 5_000,
+            minLength: 1,
+            type: 'string',
+        },
+        tagName: {
+            description: 'HTML custom element tag to validate against, e.g. "ore-button"',
+            maxLength: 100,
+            minLength: 1,
+            type: 'string',
+        },
+    },
+    required: ['html', 'tagName'],
+    type: 'object',
+};
+export const validateUsageTool = {
+    description: 'Validate AI-generated HTML against a @vielzeug/refine component spec. Checks for unknown attributes and unrecognised slot names. Returns a JSON array of { type, message } objects — an empty array means the usage is valid. Use this to close the generate → validate → fix loop before rendering.',
+    inputSchema: validateUsageSchema,
+    name: 'refine-validate-usage',
+    run(args, context) {
+        const { html, tagName } = parseArgs(validateUsageSchema, args);
+        const decl = requireComponent(context, tagName);
+        const issues = [];
+        const knownAttrs = new Set((decl.attributes ?? []).map((a) => a.name.toLowerCase()));
+        const knownSlots = new Set((decl.slots ?? []).map((s) => s.name).filter(Boolean));
+        const foundAttrs = parseTagAttributes(html, tagName);
+        if (!foundAttrs) {
+            issues.push({ message: `Could not find opening <${tagName}> tag in the provided HTML.`, type: 'error' });
+        }
+        else {
+            for (const attr of foundAttrs.keys()) {
+                if (SAFE_HTML_ATTRS.has(attr))
+                    continue;
+                if (SAFE_ATTR_PREFIXES.some((p) => attr.startsWith(p)))
+                    continue;
+                if (!knownAttrs.has(attr)) {
+                    issues.push({
+                        message: `Unknown attribute "${attr}" on <${tagName}>. Known: ${[...knownAttrs].join(', ') || 'none'}.`,
+                        type: 'error',
+                    });
+                }
+            }
+        }
+        if (knownSlots.size > 0) {
+            for (const slot of parseSlotNames(html)) {
+                if (!knownSlots.has(slot)) {
+                    issues.push({
+                        message: `Unknown slot "${slot}" on <${tagName}>. Known slots: ${[...knownSlots].join(', ')}.`,
+                        type: 'error',
+                    });
+                }
+            }
+        }
+        return text(JSON.stringify(issues, null, 2));
+    },
+};
+export const refineTools = [
+    listComponentsTool,
+    getComponentTool,
+    generateTemplateTool,
+    getTokensTool,
+    validateUsageTool,
+];
+//# sourceMappingURL=refine.js.map

package/dist/tools/refine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"refine.js","sourceRoot":"","sources":["../../src/tools/refine.ts"],"names":[],"mappings":"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"}

package/dist/tools/schema.js

@@ -0,0 +1,37 @@
+import { ToolError } from '../errors.js';
+/** A property shared by every tool that takes a package slug — one definition, reused everywhere. */
+export const PACKAGE_SLUG_PROPERTY = {
+    description: 'Package folder name, e.g. "ripple"',
+    maxLength: 100,
+    minLength: 1,
+    type: 'string',
+};
+/** Validates + trims raw MCP tool arguments against a `ToolSchema`. Throws `ToolError('INVALID_ARG', ...)` on the first violation. */
+export function parseArgs(schema, raw) {
+    const result = {};
+    for (const [key, prop] of Object.entries(schema.properties)) {
+        const required = schema.required?.includes(key) ?? false;
+        const value = raw[key];
+        if (value === undefined || value === '') {
+            if (required)
+                throw new ToolError('INVALID_ARG', `${key}: required non-empty string.`);
+            if (prop.default !== undefined)
+                result[key] = prop.default;
+            continue;
+        }
+        if (typeof value !== 'string')
+            throw new ToolError('INVALID_ARG', `${key}: must be a string.`);
+        const trimmed = value.trim();
+        if (required && trimmed.length === 0)
+            throw new ToolError('INVALID_ARG', `${key}: required non-empty string.`);
+        if (prop.minLength !== undefined && trimmed.length < prop.minLength)
+            throw new ToolError('INVALID_ARG', `${key}: must be at least ${prop.minLength} characters.`);
+        if (prop.maxLength !== undefined && trimmed.length > prop.maxLength)
+            throw new ToolError('INVALID_ARG', `${key}: exceeds ${prop.maxLength} character limit. Shorten the value.`);
+        if (prop.enum && !prop.enum.includes(trimmed))
+            throw new ToolError('INVALID_ARG', `${key}: must be one of ${prop.enum.join(', ')}.`);
+        result[key] = trimmed;
+    }
+    return result;
+}
+//# sourceMappingURL=schema.js.map

package/dist/tools/schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../src/tools/schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AA6BzC,qGAAqG;AACrG,MAAM,CAAC,MAAM,qBAAqB,GAAiB;IACjD,WAAW,EAAE,oCAAoC;IACjD,SAAS,EAAE,GAAG;IACd,SAAS,EAAE,CAAC;IACZ,IAAI,EAAE,QAAQ;CACf,CAAC;AAWF,sIAAsI;AACtI,MAAM,UAAU,SAAS,CAAuB,MAAS,EAAE,GAA4B;IACrF,MAAM,MAAM,GAA2B,EAAE,CAAC;IAE1C,KAAK,MAAM,CAAC,GAAG,EAAE,IAAI,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,UAAU,CAAC,EAAE,CAAC;QAC5D,MAAM,QAAQ,GAAG,MAAM,CAAC,QAAQ,EAAE,QAAQ,CAAC,GAAG,CAAC,IAAI,KAAK,CAAC;QACzD,MAAM,KAAK,GAAG,GAAG,CAAC,GAAG,CAAC,CAAC;QAEvB,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,EAAE,EAAE,CAAC;YACxC,IAAI,QAAQ;gBAAE,MAAM,IAAI,SAAS,CAAC,aAAa,EAAE,GAAG,GAAG,8BAA8B,CAAC,CAAC;YAEvF,IAAI,IAAI,CAAC,OAAO,KAAK,SAAS;gBAAE,MAAM,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC;YAE3D,SAAS;QACX,CAAC;QAED,IAAI,OAAO,KAAK,KAAK,QAAQ;YAAE,MAAM,IAAI,SAAS,CAAC,aAAa,EAAE,GAAG,GAAG,qBAAqB,CAAC,CAAC;QAE/F,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC;QAE7B,IAAI,QAAQ,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;YAAE,MAAM,IAAI,SAAS,CAAC,aAAa,EAAE,GAAG,GAAG,8BAA8B,CAAC,CAAC;QAE/G,IAAI,IAAI,CAAC,SAAS,KAAK,SAAS,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,SAAS;YACjE,MAAM,IAAI,SAAS,CAAC,aAAa,EAAE,GAAG,GAAG,sBAAsB,IAAI,CAAC,SAAS,cAAc,CAAC,CAAC;QAE/F,IAAI,IAAI,CAAC,SAAS,KAAK,SAAS,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,SAAS;YACjE,MAAM,IAAI,SAAS,CAAC,aAAa,EAAE,GAAG,GAAG,aAAa,IAAI,CAAC,SAAS,sCAAsC,CAAC,CAAC;QAE9G,IAAI,IAAI,CAAC,IAAI,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC;YAC3C,MAAM,IAAI,SAAS,CAAC,aAAa,EAAE,GAAG,GAAG,oBAAoB,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAExF,MAAM,CAAC,GAAG,CAAC,GAAG,OAAO,CAAC;IACxB,CAAC;IAED,OAAO,MAAsB,CAAC;AAChC,CAAC"}

package/dist/tools/shared.js

@@ -0,0 +1,27 @@
+import { ToolError } from '../errors.js';
+import { normalisePackage } from '../search.js';
+// ---------------------------------------------------------------------------
+// Result helpers
+// ---------------------------------------------------------------------------
+export function text(value) {
+    return { content: [{ text: value, type: 'text' }] };
+}
+export function buildToolContext(data) {
+    return {
+        bySlug: new Map(data.packages.map((pkg) => [pkg.slug, pkg])),
+        normalisedPackages: data.packages.map(normalisePackage),
+        refineComponents: data.refineComponents,
+        refineComponentTags: data.refineComponents.filter((d) => d.tagName).map((d) => d.tagName),
+    };
+}
+export function knownSlugs(context) {
+    return [...context.bySlug.keys()].join(', ');
+}
+/** Looks up a package by slug or throws `ToolError('NOT_FOUND', ...)` — the one place every tool resolves a slug. */
+export function requirePackage(context, slug) {
+    const pkg = context.bySlug.get(slug);
+    if (!pkg)
+        throw new ToolError('NOT_FOUND', `Package "${slug}" not found. Available slugs: ${knownSlugs(context)}`);
+    return pkg;
+}
+//# sourceMappingURL=shared.js.map

package/dist/tools/shared.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shared.js","sourceRoot":"","sources":["../../src/tools/shared.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AACzC,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAGhD,8EAA8E;AAC9E,iBAAiB;AACjB,8EAA8E;AAE9E,MAAM,UAAU,IAAI,CAAC,KAAa;IAChC,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,EAAE,CAAC;AACtD,CAAC;AAeD,MAAM,UAAU,gBAAgB,CAAC,IAAiB;IAChD,OAAO;QACL,MAAM,EAAE,IAAI,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC,CAAC;QAC5D,kBAAkB,EAAE,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,gBAAgB,CAAC;QACvD,gBAAgB,EAAE,IAAI,CAAC,gBAAgB;QACvC,mBAAmB,EAAE,IAAI,CAAC,gBAAgB,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAiB,CAAC;KACpG,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,OAAoB;IAC7C,OAAO,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC/C,CAAC;AAED,qHAAqH;AACrH,MAAM,UAAU,cAAc,CAAC,OAAoB,EAAE,IAAY;IAC/D,MAAM,GAAG,GAAG,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAErC,IAAI,CAAC,GAAG;QAAE,MAAM,IAAI,SAAS,CAAC,WAAW,EAAE,YAAY,IAAI,iCAAiC,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;IAEnH,OAAO,GAAG,CAAC;AACb,CAAC"}