@runsnative/mcp-server 0.1.0

package/dist/remote-provider.js

@@ -0,0 +1,339 @@
+import { mkdirSync, readFileSync, writeFileSync, existsSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { homedir } from 'node:os';
+import { McpError, ErrorCode } from '@modelcontextprotocol/sdk/types.js';
+// ---------------------------------------------------------------------------
+// Helpers — copied from content.ts to avoid importing filesystem-bound code
+// ---------------------------------------------------------------------------
+function extractSection(text, heading) {
+    const sections = text.split(/(?=^## )/m);
+    for (const section of sections) {
+        const headingLine = section.split(/\r?\n/)[0] ?? '';
+        if (headingLine.trim() === `## ${heading}`) {
+            const newlineIdx = section.indexOf('\n');
+            return newlineIdx !== -1 ? section.slice(newlineIdx).trim() : '';
+        }
+    }
+    return '';
+}
+function stripFrontmatter(raw) {
+    const match = raw.match(/^---\r?\n[\s\S]*?\r?\n---\r?\n/);
+    if (!match)
+        return raw;
+    return raw.slice(match[0].length);
+}
+// ---------------------------------------------------------------------------
+// RemoteContentProvider — fetches from the MCP API Worker with offline cache.
+//
+// Cache strategy: stale-while-revalidate keyed by manifest version.
+//   - On initialize(): fetch /mcp/manifest → compare version to cached manifest
+//   - Version match → cache is fresh, serve from cache
+//   - Version mismatch or no cached manifest → set cacheStale = true, refresh on first access
+//   - Network error at initialize() → leave cacheStale = false (use cache as-is)
+//
+// Per-call:
+//   - Cache hit + !cacheStale → return from cache
+//   - Cache miss or stale → fetch from Worker, write to cache, return
+//   - Network error + cache hit → return from cache
+//   - Network error + no cache → throw McpError
+//
+// 402 handling:
+//   - tenantExpired = true, extract payment_url from body
+//   - Throw agent-friendly McpError
+//   - Subsequent calls drop Bearer token (anonymous mode for session)
+// ---------------------------------------------------------------------------
+export class RemoteContentProvider {
+    baseUrl;
+    token;
+    cacheDir;
+    cacheStale = false;
+    tenantExpired = false;
+    bootstrapUrl = undefined;
+    constructor(baseUrl = process.env['RUNSNATIVE_API_URL'] ?? 'https://api.runsnative.org/mcp', token = process.env['RUNSNATIVE_TENANT_TOKEN'], cacheDir = process.env['RUNSNATIVE_CACHE_DIR'] ?? join(homedir(), '.runsnative', 'cache')) {
+        this.baseUrl = baseUrl;
+        this.token = token;
+        this.cacheDir = cacheDir;
+    }
+    // ── Startup: version-check manifest ────────────────────────────────────────
+    async initialize() {
+        try {
+            const res = await this.fetchApi('/manifest');
+            if (!res.ok)
+                return; // non-2xx at startup → skip, cache is usable as-is
+            const manifest = await res.json();
+            this.bootstrapUrl = manifest.bootstrap_url;
+            const cachedVersion = this.readCachedManifestVersion();
+            if (cachedVersion === null || cachedVersion !== manifest.version) {
+                this.cacheStale = true;
+                // Write the fresh manifest to cache
+                this.writeCache('manifest.json', JSON.stringify(manifest));
+            }
+            // version matches → cache is fresh, cacheStale stays false
+        }
+        catch {
+            // Network unavailable at startup — use cache as-is, do not mark stale
+        }
+    }
+    // ── ContentProvider interface ───────────────────────────────────────────────
+    async getComponent(name, tab) {
+        const cachePath = join('components', name, `${tab}.md`);
+        return this.fetchText(`/components/${name}/${tab}`, cachePath);
+    }
+    async listComponents(includeDrafts = false) {
+        const manifest = await this.getManifest();
+        return manifest.components
+            .filter(e => includeDrafts || e.status === 'ready')
+            .map(e => ({
+            name: e.name,
+            title: e.title,
+            element_tag: e.element_tag,
+            surface: e.surface,
+            status: e.status,
+            purpose: e.purpose,
+        }))
+            .sort((a, b) => a.name.localeCompare(b.name));
+    }
+    async getFoundation(name) {
+        const cachePath = join('foundations', `${name}.md`);
+        return this.fetchText(`/foundations/${name}`, cachePath);
+    }
+    async listFoundations() {
+        const manifest = await this.getManifest();
+        return manifest.foundations
+            .map(e => ({
+            foundation: e.name,
+            title: e.title,
+            description: e.description,
+        }))
+            .sort((a, b) => a.foundation.localeCompare(b.foundation));
+    }
+    async searchDocs(query, limit = 5) {
+        const encoded = encodeURIComponent(query);
+        const cachePath = join('search', `${encoded}-${limit}.json`);
+        try {
+            const res = await this.fetchApi(`/search?q=${encoded}&limit=${limit}`);
+            await this.handle402(res);
+            if (res.ok) {
+                const results = await res.json();
+                this.writeCache(cachePath, JSON.stringify(results));
+                return results;
+            }
+        }
+        catch (err) {
+            if (err instanceof McpError)
+                throw err;
+            // Network error — fall through to cache
+        }
+        const cached = this.readCache(cachePath);
+        if (cached !== null)
+            return JSON.parse(cached);
+        // No cache and no network for search — return empty rather than hard error
+        return [];
+    }
+    async listExercises(includeDrafts = false) {
+        const manifest = await this.getManifest();
+        return manifest.exercises
+            .filter(e => includeDrafts || e.status === 'ready')
+            .map(e => ({
+            name: e.name,
+            title: e.title,
+            tagline: e.tagline,
+            activity_type: e.activity_type,
+            difficulty: e.difficulty,
+            estimated_minutes: e.estimated_minutes,
+            status: e.status,
+        }))
+            .sort((a, b) => a.name.localeCompare(b.name));
+    }
+    async getExerciseDetail(name) {
+        const cachePath = join('exercises', name, 'index.json');
+        try {
+            const res = await this.fetchApi(`/exercises/${name}`);
+            await this.handle402(res);
+            if (res.ok) {
+                const data = await res.json();
+                this.writeCache(cachePath, JSON.stringify(data));
+                return {
+                    exercise: data.exercise,
+                    title: data.title,
+                    overview: data.overview,
+                    steps: data.steps,
+                };
+            }
+            if (res.status === 404) {
+                throw new RangeError(`Exercise "${name}" not found.`);
+            }
+        }
+        catch (err) {
+            if (err instanceof McpError || err instanceof RangeError)
+                throw err;
+            // Network error — fall through to cache
+        }
+        const cached = this.readCache(cachePath);
+        if (cached !== null) {
+            const data = JSON.parse(cached);
+            return { exercise: data.exercise, title: data.title, overview: data.overview, steps: data.steps };
+        }
+        throw new McpError(ErrorCode.InternalError, `Network unavailable and content not cached: exercises/${name}/index`);
+    }
+    async getExerciseStep(name, step) {
+        const cachePath = join('exercises', name, 'steps', `${step}.json`);
+        try {
+            const res = await this.fetchApi(`/exercises/${name}/steps/${step}`);
+            await this.handle402(res);
+            if (res.ok) {
+                const data = await res.json();
+                this.writeCache(cachePath, JSON.stringify(data));
+                return this.buildStepContent(data);
+            }
+            if (res.status === 404) {
+                throw new RangeError(`Step ${step} not found in exercise "${name}".`);
+            }
+        }
+        catch (err) {
+            if (err instanceof McpError || err instanceof RangeError)
+                throw err;
+            // Network error — fall through to cache
+        }
+        const cached = this.readCache(cachePath);
+        if (cached !== null)
+            return this.buildStepContent(JSON.parse(cached));
+        throw new McpError(ErrorCode.InternalError, `Network unavailable and content not cached: exercises/${name}/steps/${step}`);
+    }
+    // Recipes are not yet served by the remote Worker. Return empty list so
+    // list_composition_patterns degrades gracefully; throw a clear error on
+    // get_composition_pattern so the agent knows what's missing.
+    async listRecipes() {
+        return [];
+    }
+    async getRecipe(name) {
+        throw new McpError(ErrorCode.InternalError, `Composition pattern "${name}" is not available from the remote content API yet. ` +
+            `Connect a local content tree via RUNSNATIVE_CONTENT_ROOT to access recipes.`);
+    }
+    // ── Private helpers ─────────────────────────────────────────────────────────
+    async fetchApi(path) {
+        const headers = {};
+        if (this.token && !this.tenantExpired) {
+            headers['Authorization'] = `Bearer ${this.token}`;
+        }
+        return fetch(`${this.baseUrl}${path}`, { headers });
+    }
+    async handle402(res) {
+        if (res.status !== 402)
+            return;
+        this.tenantExpired = true;
+        let paymentUrl = 'https://runsnative.org/billing';
+        try {
+            const body = await res.clone().json();
+            if (typeof body['payment_url'] === 'string')
+                paymentUrl = body['payment_url'];
+        }
+        catch { /* ignore parse failure */ }
+        throw new McpError(ErrorCode.InternalError, `Your RunsNative tenant access has ended. Visit ${paymentUrl} to reactivate. Until then, this MCP server is operating in anonymous mode.`);
+    }
+    async fetchText(apiPath, cachePath) {
+        // Cache hit when not stale → serve from cache
+        if (!this.cacheStale) {
+            const cached = this.readCache(cachePath);
+            if (cached !== null)
+                return cached;
+        }
+        try {
+            const res = await this.fetchApi(apiPath);
+            await this.handle402(res);
+            if (res.ok) {
+                const text = await res.text();
+                this.writeCache(cachePath, text);
+                return text;
+            }
+            if (res.status === 404) {
+                const segments = apiPath.split('/').filter(Boolean);
+                throw new RangeError(`Content not found: ${apiPath}. Check the ${segments[0] ?? 'resource'} name and tab are correct.`);
+            }
+        }
+        catch (err) {
+            if (err instanceof McpError || err instanceof RangeError)
+                throw err;
+            // Network error — fall through to cache
+        }
+        const cached = this.readCache(cachePath);
+        if (cached !== null)
+            return cached;
+        throw new McpError(ErrorCode.InternalError, `Network unavailable and content not cached: ${apiPath}`);
+    }
+    async getManifest() {
+        const cachePath = 'manifest.json';
+        if (!this.cacheStale) {
+            const cached = this.readCache(cachePath);
+            if (cached !== null)
+                return JSON.parse(cached);
+        }
+        try {
+            const res = await this.fetchApi('/manifest');
+            await this.handle402(res);
+            if (res.ok) {
+                const manifest = await res.json();
+                this.writeCache(cachePath, JSON.stringify(manifest));
+                this.cacheStale = false;
+                return manifest;
+            }
+        }
+        catch (err) {
+            if (err instanceof McpError)
+                throw err;
+            // Network error — fall through to cache
+        }
+        const cached = this.readCache(cachePath);
+        if (cached !== null)
+            return JSON.parse(cached);
+        throw new McpError(ErrorCode.InternalError, 'Network unavailable and manifest not cached. Cannot list components/foundations/exercises.');
+    }
+    buildStepContent(data) {
+        const body = stripFrontmatter(data.content);
+        const goal = extractSection(data.content, 'Goal') || extractSection(body, 'Goal');
+        return {
+            exercise: data.exercise,
+            step: data.step,
+            title: data.title,
+            goal,
+            content: data.content,
+        };
+    }
+    // ── Cache I/O ───────────────────────────────────────────────────────────────
+    readCachedManifestVersion() {
+        const raw = this.readCache('manifest.json');
+        if (raw === null)
+            return null;
+        try {
+            const manifest = JSON.parse(raw);
+            return manifest.version ?? null;
+        }
+        catch {
+            return null;
+        }
+    }
+    cachePath(relativePath) {
+        return join(this.cacheDir, relativePath);
+    }
+    readCache(relativePath) {
+        const fullPath = this.cachePath(relativePath);
+        if (!existsSync(fullPath))
+            return null;
+        try {
+            return readFileSync(fullPath, 'utf8');
+        }
+        catch {
+            return null;
+        }
+    }
+    writeCache(relativePath, content) {
+        const fullPath = this.cachePath(relativePath);
+        try {
+            mkdirSync(dirname(fullPath), { recursive: true });
+            writeFileSync(fullPath, content, 'utf8');
+        }
+        catch {
+            // Cache write failure is non-fatal — content was already served
+        }
+    }
+}

package/dist/test/validate.js

@@ -0,0 +1,315 @@
+/**
+ * Phase 5 validation: two use cases against the stub MCP.
+ *
+ * Run after building: node dist/test/validate.js
+ *
+ * Use case A — Q&A: get_component("button", "usage") returns content that
+ *   lets an agent answer "How do I use a button in RunsNative?"
+ *
+ * Use case B — Authoring: get_component("button", "code") returns content
+ *   that lets an agent generate correct <run-button> markup.
+ */
+import { getComponent, validateContentRoot, listComponentMeta, getFoundation, listFoundations, searchDocs, listExerciseMeta, getExerciseDetail, getExerciseStep, } from '../content.js';
+import { handleInferTheme } from '../tools/infer-theme.js';
+validateContentRoot();
+let passed = 0;
+let failed = 0;
+function check(label, fn) {
+    try {
+        fn();
+        console.log(`  ✓ ${label}`);
+        passed++;
+    }
+    catch (err) {
+        console.error(`  ✗ ${label}`);
+        console.error(`    ${err.message}`);
+        failed++;
+    }
+}
+function assert(condition, message) {
+    if (!condition)
+        throw new Error(message);
+}
+console.log('\nUse case A — Q&A (usage tab)');
+{
+    const content = await getComponent('button', 'usage');
+    check('returns non-empty content', () => assert(content.length > 100, 'content too short'));
+    check('covers variants', () => assert(content.includes('variant'), 'missing variant documentation'));
+    check('covers disabled state', () => assert(content.includes('disabled'), 'missing disabled state'));
+    check('covers loading state', () => assert(content.includes('loading'), 'missing loading state'));
+    check('has do/don\'t guidance', () => assert(content.includes('Do') && content.includes("Don't"), 'missing do/don\'t section'));
+    check('tab frontmatter present', () => assert(content.includes('tab: usage'), 'missing tab frontmatter'));
+}
+console.log('\nUse case B — Authoring (code tab)');
+{
+    const content = await getComponent('button', 'code');
+    check('returns non-empty content', () => assert(content.length > 100, 'content too short'));
+    check('contains element tag run-button', () => assert(content.includes('run-button'), 'missing run-button element tag'));
+    check('lists variant property', () => assert(content.includes('variant'), 'missing variant in API'));
+    check('lists disabled property', () => assert(content.includes('disabled'), 'missing disabled in API'));
+    check('lists run-click event', () => assert(content.includes('run-click'), 'missing run-click event'));
+    check('contains markup example', () => assert(content.includes('<run-button'), 'missing markup example'));
+    check('has @cem-inject placeholder', () => assert(content.includes('@cem-inject'), 'missing @cem-inject placeholder'));
+}
+console.log('\nCompound validation (tabs usage tab)');
+{
+    const content = await getComponent('tabs', 'usage');
+    check('returns non-empty content', () => assert(content.length > 100, 'content too short'));
+    check('references run-tabs', () => assert(content.includes('run-tabs'), 'missing run-tabs element tag'));
+    check('references run-tab', () => assert(content.includes('run-tab'), 'missing run-tab constituent'));
+    check('references run-tab-panel', () => assert(content.includes('run-tab-panel'), 'missing run-tab-panel constituent'));
+    check('explains panel pairing', () => assert(content.includes('panel') && content.includes('name'), 'missing panel/name pairing explanation'));
+}
+console.log('\nError handling');
+{
+    check('throws RangeError for unknown component', async () => {
+        try {
+            await getComponent('nonexistent-component-xyz', 'usage');
+            throw new Error('should have thrown');
+        }
+        catch (err) {
+            assert(err instanceof RangeError, `expected RangeError, got ${err.constructor.name}`);
+        }
+    });
+    check('throws RangeError for unknown tab', async () => {
+        try {
+            await getComponent('button', 'notreal');
+            throw new Error('should have thrown');
+        }
+        catch (err) {
+            assert(err instanceof RangeError, `expected RangeError, got ${err.constructor.name}`);
+        }
+    });
+}
+// ---------------------------------------------------------------------------
+// list_components
+// ---------------------------------------------------------------------------
+console.log('\nlist_components');
+{
+    const ready = await listComponentMeta(false);
+    const all = await listComponentMeta(true);
+    check('ready list is non-empty', () => assert(ready.length > 0, 'no ready components found'));
+    check('includes button', () => assert(ready.some((c) => c.name === 'button'), 'button not in ready list'));
+    check('includes checkbox', () => assert(ready.some((c) => c.name === 'checkbox'), 'checkbox not in ready list'));
+    check('all list is larger than ready list', () => assert(all.length > ready.length, 'draft filtering not working'));
+    check('every component has a name and title', () => {
+        for (const c of ready) {
+            assert(typeof c.name === 'string' && c.name.length > 0, `component missing name`);
+            assert(typeof c.title === 'string' && c.title.length > 0, `${c.name} missing title`);
+        }
+    });
+    check('every component has a purpose field', () => {
+        for (const c of ready) {
+            assert(typeof c.purpose === 'string', `${c.name} missing purpose field`);
+        }
+    });
+    check('drafts contain stub components', () => {
+        const drafts = all.filter((c) => c.status === 'draft');
+        assert(drafts.length > 5, `expected >5 draft components, got ${drafts.length}`);
+    });
+}
+// ---------------------------------------------------------------------------
+// get_foundation
+// ---------------------------------------------------------------------------
+console.log('\nget_foundation');
+{
+    const spacing = await getFoundation('spacing');
+    check('spacing returns non-empty content', () => assert(spacing.length > 100, 'content too short'));
+    check('spacing contains token table', () => assert(spacing.includes('--run-space'), 'missing spacing token'));
+    check('spacing frontmatter present', () => assert(spacing.includes('foundation: spacing'), 'missing frontmatter'));
+    const color = await getFoundation('color');
+    check('color returns non-empty content', () => assert(color.length > 100, 'color content too short'));
+    check('color contains color tokens', () => assert(color.includes('--run-color'), 'missing color token'));
+    check('throws RangeError for unknown foundation', async () => {
+        try {
+            await getFoundation('nonexistent-foundation-xyz');
+            throw new Error('should have thrown');
+        }
+        catch (err) {
+            assert(err instanceof RangeError, `expected RangeError, got ${err.constructor.name}`);
+        }
+    });
+}
+// ---------------------------------------------------------------------------
+// listFoundations
+// ---------------------------------------------------------------------------
+console.log('\nlistFoundations');
+{
+    const foundations = await listFoundations();
+    check('returns 7 foundations', () => assert(foundations.length === 7, `expected 7 foundations, got ${foundations.length}`));
+    check('includes color', () => assert(foundations.some((f) => f.foundation === 'color'), 'missing color'));
+    check('includes typography', () => assert(foundations.some((f) => f.foundation === 'typography'), 'missing typography'));
+    check('each foundation has title and description', () => {
+        for (const f of foundations) {
+            assert(typeof f.title === 'string' && f.title.length > 0, `${f.foundation} missing title`);
+            assert(typeof f.description === 'string', `${f.foundation} missing description`);
+        }
+    });
+}
+// ---------------------------------------------------------------------------
+// search_docs
+// ---------------------------------------------------------------------------
+console.log('\nsearch_docs');
+{
+    const results = await searchDocs('spacing token padding', 3);
+    check('returns results for spacing query', () => assert(results.length > 0, 'no results for spacing query'));
+    check('result limit respected', () => assert(results.length <= 3, `expected ≤3 results, got ${results.length}`));
+    check('results have required fields', () => {
+        for (const r of results) {
+            assert(typeof r.name === 'string' && r.name.length > 0, 'result missing name');
+            assert(typeof r.excerpt === 'string' && r.excerpt.length > 0, 'result missing excerpt');
+            assert(r.score > 0, 'result has zero score');
+        }
+    });
+    check('results are sorted by score desc', () => {
+        for (let i = 1; i < results.length; i++) {
+            assert(results[i - 1].score >= results[i].score, 'results not sorted by score');
+        }
+    });
+    const empty = await searchDocs('', 5);
+    check('empty query returns empty results', () => assert(empty.length === 0, 'empty query should return no results'));
+    const limit1 = await searchDocs('button variant', 1);
+    check('limit: 1 returns at most 1 result', () => assert(limit1.length <= 1, `expected ≤1 result, got ${limit1.length}`));
+}
+// ---------------------------------------------------------------------------
+// infer_theme
+// ---------------------------------------------------------------------------
+console.log('\ninfer_theme');
+{
+    // Normal case: dark skin via data-theme attribute
+    const darkResult = await handleInferTheme({ html: '<div data-theme="dark"><run-button>Click</run-button></div>' });
+    const dark = JSON.parse(darkResult.content[0].text);
+    check('detects dark skin from data-theme', () => assert(dark.skin === 'dark', `expected dark, got ${dark.skin}`));
+    check('dark detection has medium or high confidence', () => assert(dark.confidence === 'medium' || dark.confidence === 'high', `unexpected confidence: ${dark.confidence}`));
+    // Token overrides
+    const tokenHtml = '<style>:root { --run-color-bg-base: #000; --run-color-text-primary: #fff; }</style>';
+    const tokenResult = await handleInferTheme({ html: tokenHtml });
+    const tokenData = JSON.parse(tokenResult.content[0].text);
+    check('extracts CSS custom property overrides', () => assert(Object.keys(tokenData.token_overrides).length >= 2, `expected ≥2 overrides, got ${Object.keys(tokenData.token_overrides).length}`));
+    // Fallback stub: no skin signals
+    const plainResult = await handleInferTheme({ html: '<div><p>Hello</p></div>' });
+    const plain = JSON.parse(plainResult.content[0].text);
+    check('returns null skin for unstyled markup', () => assert(plain.skin === null, `expected null, got ${plain.skin}`));
+    check('fallback has low confidence', () => assert(plain.confidence === 'low', `expected low, got ${plain.confidence}`));
+    check('fallback reasoning is non-empty', () => assert(typeof plain.reasoning === 'string' && plain.reasoning.length > 0, 'missing reasoning'));
+    // Edge case: high-contrast skin
+    const hcResult = await handleInferTheme({ html: '<html data-skin="high-contrast"><body></body></html>' });
+    const hc = JSON.parse(hcResult.content[0].text);
+    check('detects high-contrast skin', () => assert(hc.skin === 'high-contrast', `expected high-contrast, got ${hc.skin}`));
+    // Error: empty html
+    check('throws for empty html', async () => {
+        try {
+            await handleInferTheme({ html: '' });
+            throw new Error('should have thrown');
+        }
+        catch (err) {
+            assert(err.message.includes('empty') || err.message.includes('html'), `unexpected error: ${err.message}`);
+        }
+    });
+}
+// ---------------------------------------------------------------------------
+// list_exercises
+// ---------------------------------------------------------------------------
+console.log('\nlist_exercises');
+{
+    const ready = await listExerciseMeta(false);
+    const all = await listExerciseMeta(true);
+    check('returns all three ready exercises', () => assert(ready.length === 3, `expected 3 ready exercises, got ${ready.length}`));
+    check('each exercise has required fields', () => {
+        for (const ex of ready) {
+            assert(typeof ex.name === 'string' && ex.name.length > 0, `exercise missing name`);
+            assert(typeof ex.title === 'string' && ex.title.length > 0, `${ex.name} missing title`);
+            assert(typeof ex.activity_type === 'string' && ex.activity_type.length > 0, `${ex.name} missing activity_type`);
+            assert(typeof ex.difficulty === 'string' && ex.difficulty.length > 0, `${ex.name} missing difficulty`);
+            assert(typeof ex.estimated_minutes === 'number' && ex.estimated_minutes > 0, `${ex.name} missing estimated_minutes`);
+        }
+    });
+    check('include_drafts: false excludes drafts', () => {
+        const drafts = all.filter((ex) => ex.status === 'draft');
+        // No draft exercises authored yet, so all.length >= ready.length is sufficient
+        assert(all.length >= ready.length, 'all list should be at least as large as ready list');
+    });
+}
+// ---------------------------------------------------------------------------
+// start_exercise
+// ---------------------------------------------------------------------------
+console.log('\nstart_exercise');
+{
+    const detail = await getExerciseDetail('vibe-with-runsnative');
+    check('overview returned', () => {
+        assert(typeof detail.overview === 'string' && detail.overview.length > 20, 'overview missing or too short');
+    });
+    check('step list present with correct count', () => {
+        assert(Array.isArray(detail.steps) && detail.steps.length === 4, `expected 4 steps for vibe-with-runsnative, got ${detail.steps.length}`);
+        for (const s of detail.steps) {
+            assert(typeof s.step === 'number' && s.step >= 1, `step has invalid step number`);
+            assert(typeof s.slug === 'string' && s.slug.length > 0, `step missing slug`);
+            assert(typeof s.title === 'string' && s.title.length > 0, `step missing title`);
+        }
+    });
+    check('unknown exercise throws RangeError', async () => {
+        try {
+            await getExerciseDetail('nonexistent-exercise-xyz');
+            throw new Error('should have thrown');
+        }
+        catch (err) {
+            assert(err instanceof RangeError, `expected RangeError, got ${err.constructor.name}`);
+        }
+    });
+}
+// ---------------------------------------------------------------------------
+// get_step
+// ---------------------------------------------------------------------------
+console.log('\nget_step');
+{
+    const step1 = await getExerciseStep('vibe-with-runsnative', 1);
+    check('step 1 returned with content', () => {
+        assert(step1.step === 1, `expected step 1, got ${step1.step}`);
+        assert(typeof step1.goal === 'string' && step1.goal.length > 10, 'goal missing or too short');
+        assert(typeof step1.content === 'string' && step1.content.length > 50, 'content missing or too short');
+    });
+    const lastStep = await getExerciseStep('vibe-with-runsnative', 4);
+    check('last step returned', () => {
+        assert(lastStep.step === 4, `expected step 4, got ${lastStep.step}`);
+        assert(typeof lastStep.title === 'string' && lastStep.title.length > 0, 'last step missing title');
+    });
+    check('out-of-range step throws RangeError', async () => {
+        try {
+            await getExerciseStep('vibe-with-runsnative', 99);
+            throw new Error('should have thrown');
+        }
+        catch (err) {
+            assert(err instanceof RangeError, `expected RangeError, got ${err.constructor.name}`);
+        }
+    });
+}
+// ---------------------------------------------------------------------------
+// Exercise ↔ live-site wiring (RUN-354)
+//
+// Regression guard for the RUN-326 defect class: exercises that referenced
+// abstract placeholders and component tags that do not resolve against the
+// live Harlow Pets site (`run-text-field`, the invented `slot="tab"` on
+// run-tab, the invented `activation="automatic"`). RUN-354 wired the three
+// exercises to the real site at http://localhost:3250; these assertions stop
+// them silently drifting back to placeholders or invented APIs.
+// ---------------------------------------------------------------------------
+console.log('\nexercise wiring (RUN-354)');
+{
+    // Tokens that do not resolve anywhere (live site, component knowledge base,
+    // or real run-tabs API). Each is a concrete RUN-326 bug RUN-354 corrected.
+    const INVALID_TOKENS = ['run-text-field', 'slot="tab"', 'activation="automatic"', '"automatic"'];
+    for (const meta of await listExerciseMeta(false)) {
+        const detail = await getExerciseDetail(meta.name);
+        let surfaced = detail.overview;
+        for (let i = 1; i <= detail.steps.length; i++) {
+            surfaced += '\n' + (await getExerciseStep(meta.name, i)).content;
+        }
+        check(`${meta.name}: references the live Harlow Pets site (localhost:3250)`, () => assert(surfaced.includes('localhost:3250'), `no http://localhost:3250 reference in surfaced content — exercise is not wired to the live site`));
+        for (const token of INVALID_TOKENS) {
+            check(`${meta.name}: free of non-resolving token ${token}`, () => assert(!surfaced.includes(token), `surfaced content contains "${token}" — a placeholder/invented reference that does not resolve against the live site`));
+        }
+    }
+}
+console.log(`\n${passed + failed} checks: ${passed} passed, ${failed} failed`);
+if (failed > 0)
+    process.exit(1);