@waica/cli 0.3.0

package/dist/mcp/template/src/tiles/block.tile.json

@@ -0,0 +1,21 @@
+{
+  "waicaPrefab": 1,
+  "type": "tile",
+  "components": [
+    {
+      "type": "Sprite",
+      "props": {
+        "width": 2,
+        "height": 2,
+        "color": 2508371
+      }
+    },
+    {
+      "type": "Solid",
+      "props": {
+        "width": 2,
+        "height": 2
+      }
+    }
+  ]
+}

package/dist/mcp/template/src/tiles/decor.tile.json

@@ -0,0 +1,14 @@
+{
+  "waicaPrefab": 1,
+  "type": "tile",
+  "components": [
+    {
+      "type": "Sprite",
+      "props": {
+        "width": 1,
+        "height": 1,
+        "color": 9358054
+      }
+    }
+  ]
+}

package/dist/mcp/template/src/tiles/platform.tile.json

@@ -0,0 +1,21 @@
+{
+  "waicaPrefab": 1,
+  "type": "tile",
+  "components": [
+    {
+      "type": "Sprite",
+      "props": {
+        "width": 3,
+        "height": 0.5,
+        "color": 2792847
+      }
+    },
+    {
+      "type": "Solid",
+      "props": {
+        "width": 3,
+        "height": 0.5
+      }
+    }
+  ]
+}

package/dist/mcp/template/src/ui/coin-counter.html

@@ -0,0 +1,12 @@
+<style>
+  .coin-counter {
+    position: absolute;
+    top: 12px;
+    left: 12px;
+    font: 600 20px system-ui, sans-serif;
+    color: #ffd166;
+    text-shadow: 0 1px 3px #000a;
+    user-select: none;
+  }
+</style>
+<div class="coin-counter">🪙 {{points}}</div>

package/dist/mcp/template/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "strict": true,
+    "verbatimModuleSyntax": true,
+    "isolatedModules": true,
+    "skipLibCheck": true,
+    "noEmit": true,
+    "types": ["vite/client"]
+  },
+  "include": ["src"]
+}

package/dist/mcp/template/vite.config.ts

@@ -0,0 +1,3 @@
+import { defineConfig } from 'vite'
+
+export default defineConfig({})

package/dist/mcp/validation.js

@@ -0,0 +1,323 @@
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { discoverArchetypes, pickArchetype } from './archetypes.js';
+import { PackageResolver, mixedSourceWarnings, provenanceRows, } from './package-resolver.js';
+import { directFiles, requireWaicaProject } from './project-path.js';
+function add(context, severity, code, message, file, ref) {
+    context.findings.push({ severity, code, message, file, ...(ref ? { ref } : {}) });
+}
+async function parseJson(projectPath, relative, findings) {
+    try {
+        return JSON.parse(await readFile(path.join(projectPath, relative), 'utf8'));
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return undefined;
+        add({ findings }, 'error', 'unparseable-json', `Cannot parse JSON: ${error.message}`, relative);
+        return undefined;
+    }
+}
+async function projectComponentCandidates(projectPath) {
+    const names = new Set();
+    for (const directory of ['components', 'roles', 'states']) {
+        for (const file of await directFiles(path.join(projectPath, 'src', directory), '.ts')) {
+            const source = await readFile(path.join(projectPath, 'src', directory, file), 'utf8');
+            for (const match of source.matchAll(/\bcomponentName\s*=\s*['"]([^'"]+)['"]/g)) {
+                const name = match[1];
+                if (name)
+                    names.add(name);
+            }
+        }
+    }
+    return names;
+}
+function checkComponent(component, file, ref, context) {
+    if (context.knownComponents.has(component.type))
+        return;
+    if (context.projectComponents.has(component.type)) {
+        add(context, 'info', 'unknown-component', `Component "${component.type}" is project-owned, not validated.`, file, ref);
+        return;
+    }
+    add(context, 'error', 'unknown-component', `Unknown component "${component.type}".`, file, ref);
+}
+function componentList(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value.filter((entry) => !!entry && typeof entry === 'object' && typeof entry.type === 'string');
+}
+function objectRecord(value) {
+    return value && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : {};
+}
+function machineStates(component) {
+    return objectRecord(component.props?.states);
+}
+function escapedRegex(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+async function projectRoleStateSources(projectPath) {
+    const sources = new Map();
+    for (const file of await directFiles(path.join(projectPath, 'src/roles'), '.ts')) {
+        const source = await readFile(path.join(projectPath, 'src/roles', file), 'utf8');
+        for (const match of source.matchAll(/\bdefine(?:Role|States)\s*\(\s*(['"])([^'"]+)\1/g)) {
+            const role = match[2];
+            if (!role)
+                continue;
+            sources.set(role, [...(sources.get(role) ?? []), source.slice(match.index)]);
+        }
+    }
+    return sources;
+}
+function roleSourceHasState(source, state) {
+    const statesMarkers = [...source.matchAll(/\bstates\s*:/g)];
+    const candidate = statesMarkers.at(-1);
+    const registration = candidate ? source.slice(candidate.index) : source;
+    return new RegExp(`\\b${escapedRegex(state)}\\s*:`).test(registration);
+}
+/** Mirrors flat state files and textually recognizes project role registrations. */
+function stateCodeExists(role, state, context) {
+    const roleStates = context.manifest.bundle.roles[role]?.states;
+    const logicStates = context.manifest.bundle.logicSets?.[role];
+    return ((!!roleStates && Object.hasOwn(roleStates, state)) ||
+        (!!logicStates && Object.hasOwn(logicStates, state)) ||
+        context.stateFiles.has(state) ||
+        (context.roleStateSources.get(role) ?? []).some((source) => roleSourceHasState(source, state)));
+}
+function validateStateMachines(components, file, ref, context) {
+    const animated = components.find((component) => component.type === 'AnimatedSprite');
+    const clips = animated
+        ? new Set(Object.keys(objectRecord(animated.props?.clips)))
+        : undefined;
+    for (const machine of components.filter((component) => component.type === 'StateMachine')) {
+        const states = machineStates(machine);
+        const realNames = Object.keys(states).filter((name) => name !== '*');
+        const role = typeof machine.props?.role === 'string' ? machine.props.role : '';
+        const initial = typeof machine.props?.initial === 'string' && machine.props.initial
+            ? machine.props.initial
+            : (realNames[0] ?? '');
+        for (const name of realNames) {
+            const definition = objectRecord(states[name]);
+            const clip = typeof definition.clip === 'string' ? definition.clip : name;
+            if (clips && !clips.has(clip)) {
+                add(context, 'warning', 'missing-clip', `State "${name}" uses missing animation clip "${clip}".`, file, ref ?? name);
+            }
+            const transitions = Array.isArray(definition.transitions) ? definition.transitions : [];
+            for (const transition of transitions) {
+                if (!transition || typeof transition !== 'object')
+                    continue;
+                const to = transition.to;
+                const on = transition.on;
+                if (typeof to === 'string' && to !== '*' && !Object.hasOwn(states, to)) {
+                    add(context, 'warning', 'dangling-transition-target', `State "${name}" transitions to missing state "${to}".`, file, ref ?? name);
+                }
+                if (typeof on === 'string' && on.startsWith('input:')) {
+                    const action = on.slice('input:'.length);
+                    if (!context.bindings[action]?.length) {
+                        add(context, 'warning', 'input-action-unbound', `Input action "${action}" has no bindings.`, file, action);
+                    }
+                }
+            }
+            if (name !== initial) {
+                const reachable = Object.values(states).some((candidate) => (Array.isArray(candidate?.transitions) ? candidate.transitions : []).some((transition) => transition?.to === name));
+                if (!reachable) {
+                    add(context, 'warning', 'unreachable-state', `Nothing transitions to state "${name}" and it is not initial.`, file, ref ?? name);
+                }
+            }
+            if (!stateCodeExists(role, name, context)) {
+                add(context, 'info', 'no-state-code', `State "${name}" has no built-in code, project role registration or src/states/${name}.ts.`, file, ref ?? name);
+            }
+        }
+    }
+}
+function resolvedEntityComponents(entity, prefab) {
+    const overrides = objectRecord(entity.overrides);
+    const inherited = componentList(prefab?.components).map((component) => ({
+        type: component.type,
+        props: {
+            ...objectRecord(component.props),
+            ...objectRecord(overrides[component.type]),
+        },
+    }));
+    return [...inherited, ...componentList(entity.components)];
+}
+function validatePrefab(prefab, file, ref, context) {
+    const components = componentList(prefab.components);
+    for (const component of components)
+        checkComponent(component, file, ref, context);
+    validateStateMachines(components, file, ref, context);
+}
+function validateScene(scene, file, prefabs, uiNames, context) {
+    const rawEntities = Array.isArray(scene.entities) ? scene.entities : [];
+    const entities = rawEntities
+        .map((entity, index) => ({ entity, index }))
+        .filter((entry) => !!entry.entity && typeof entry.entity === 'object' && !Array.isArray(entry.entity));
+    const entityNames = new Set(entities
+        .map(({ entity }) => (typeof entity.name === 'string' ? entity.name : ''))
+        .filter(Boolean));
+    const follow = scene.camera?.follow;
+    if (typeof follow === 'string' && follow && !entityNames.has(follow)) {
+        add(context, 'warning', 'camera-follow-unknown-entity', `Camera follows unknown entity "${follow}".`, file, follow);
+    }
+    for (const ui of Array.isArray(scene.ui) ? scene.ui : []) {
+        if (typeof ui === 'string' && !uiNames.has(ui)) {
+            add(context, 'warning', 'unknown-ui-piece', `Unknown UI piece "${ui}".`, file, ui);
+        }
+    }
+    for (const { entity, index } of entities) {
+        const entityRef = typeof entity.name === 'string' && entity.name ? entity.name : `entity[${index}]`;
+        const inline = componentList(entity.components);
+        for (const component of inline)
+            checkComponent(component, file, entityRef, context);
+        const prefabRef = typeof entity.prefab === 'string' ? entity.prefab : undefined;
+        const overrides = objectRecord(entity.overrides);
+        let prefab;
+        if (prefabRef) {
+            prefab = prefabs.get(prefabRef);
+            if (!prefab) {
+                add(context, 'error', 'broken-prefab-ref', `Entity "${entityRef}" references missing prefab "${prefabRef}".`, file, prefabRef);
+            }
+            else {
+                const componentTypes = new Set(componentList(prefab.components).map((component) => component.type));
+                for (const override of Object.keys(overrides)) {
+                    if (!componentTypes.has(override)) {
+                        add(context, 'warning', 'override-key-not-in-prefab', `Override "${override}" is not a component in prefab "${prefabRef}".`, file, prefabRef);
+                    }
+                }
+            }
+        }
+        // Re-evaluate inherited state behavior only when this entity actually
+        // changes a StateMachine or AnimatedSprite. Unrelated overrides keep the
+        // prefab-level finding as the single source of truth.
+        const stateTypes = new Set(['StateMachine', 'AnimatedSprite']);
+        const changesStateBehavior = inline.some((component) => stateTypes.has(component.type)) ||
+            Object.keys(overrides).some((type) => stateTypes.has(type));
+        if (changesStateBehavior) {
+            validateStateMachines(resolvedEntityComponents(entity, prefab), file, entityRef, context);
+        }
+    }
+}
+function statBindings(html) {
+    // GameUi binds text nodes only: attributes, comments, style and script
+    // contents are not runtime bindings and must not create validator findings.
+    const textOnly = html
+        .replace(/<!--[\s\S]*?-->/g, '')
+        .replace(/<(style|script)\b[^>]*>[\s\S]*?<\/\1>/gi, '')
+        .replace(/<[^>]*>/g, ' ');
+    const names = new Set();
+    for (const match of textOnly.matchAll(/\{\{\s*([\w-]+)\s*\}\}/g)) {
+        if (match[1])
+            names.add(match[1]);
+    }
+    return names;
+}
+export async function validateProject(projectPath) {
+    const check = await requireWaicaProject(projectPath);
+    const findings = [];
+    const fixedPaths = [
+        'package.json',
+        'src/game.json',
+        'src/controls.json',
+        'src/stats.json',
+        'public/waica.params.json',
+    ];
+    const fixed = new Map();
+    for (const relative of fixedPaths) {
+        fixed.set(relative, await parseJson(projectPath, relative, findings));
+    }
+    const game = objectRecord(fixed.get('src/game.json'));
+    const gameWasUnparseable = findings.some((finding) => finding.code === 'unparseable-json' && finding.file === 'src/game.json');
+    const activeId = typeof game.archetype === 'string' && game.archetype
+        ? game.archetype
+        : gameWasUnparseable
+            ? 'platformer'
+            : null;
+    const resolver = new PackageResolver(projectPath);
+    const discoveryWarnings = [];
+    const [engine, behaviors, archetypes, projectComponents, roleStateSources] = await Promise.all([
+        resolver.load('@waica/engine'),
+        resolver.load('@waica/behaviors'),
+        discoverArchetypes(projectPath, resolver, discoveryWarnings, activeId ? [activeId] : []),
+        projectComponentCandidates(projectPath),
+        projectRoleStateSources(projectPath),
+    ]);
+    const manifest = pickArchetype(archetypes, activeId, projectPath).manifest;
+    const controls = objectRecord(objectRecord(fixed.get('src/controls.json')).bindings);
+    const bindings = {};
+    for (const [name, value] of Object.entries(controls)) {
+        if (Array.isArray(value) && value.every((entry) => typeof entry === 'string')) {
+            bindings[name] = value;
+        }
+    }
+    const stateFiles = new Set((await directFiles(path.join(projectPath, 'src/states'), '.ts')).map((file) => file.slice(0, -'.ts'.length)));
+    const context = {
+        findings,
+        manifest,
+        knownComponents: new Set(Object.keys(manifest.registry.components)),
+        projectComponents,
+        stateFiles,
+        roleStateSources,
+        bindings,
+    };
+    const prefabs = new Map();
+    for (const [directory, type] of [
+        ['characters', 'character'],
+        ['objects', 'object'],
+        ['tiles', 'tile'],
+    ]) {
+        const suffix = `.${type}.json`;
+        for (const file of await directFiles(path.join(projectPath, 'src', directory), suffix)) {
+            const relative = `src/${directory}/${file}`;
+            const parsed = await parseJson(projectPath, relative, findings);
+            if (!parsed || typeof parsed !== 'object')
+                continue;
+            const ref = `${directory}/${file.slice(0, -suffix.length)}`;
+            const prefab = parsed;
+            prefabs.set(ref, prefab);
+            validatePrefab(prefab, relative, ref, context);
+        }
+    }
+    const uiFiles = await directFiles(path.join(projectPath, 'src/ui'), '.html');
+    const uiNames = new Set(uiFiles.map((file) => file.slice(0, -'.html'.length)));
+    const declaredStats = new Set(Object.keys(objectRecord(objectRecord(fixed.get('src/stats.json')).stats)));
+    for (const file of uiFiles) {
+        const relative = `src/ui/${file}`;
+        const html = await readFile(path.join(projectPath, relative), 'utf8');
+        for (const stat of statBindings(html)) {
+            if (!declaredStats.has(stat)) {
+                add(context, 'warning', 'undeclared-stat', `UI references undeclared stat "${stat}"; runtime writes may still create it.`, relative, stat);
+            }
+        }
+    }
+    const sceneFiles = await directFiles(path.join(projectPath, 'src/scenes'), '.scene.json');
+    for (const file of sceneFiles) {
+        const relative = `src/scenes/${file}`;
+        const parsed = await parseJson(projectPath, relative, findings);
+        if (!parsed || typeof parsed !== 'object')
+            continue;
+        validateScene(parsed, relative, prefabs, uiNames, context);
+    }
+    const params = objectRecord(fixed.get('public/waica.params.json'));
+    for (const [entity, rawComponents] of Object.entries(params)) {
+        for (const component of Object.keys(objectRecord(rawComponents))) {
+            checkComponent({ type: component }, 'public/waica.params.json', entity, context);
+        }
+    }
+    const summary = {
+        errors: findings.filter((finding) => finding.severity === 'error').length,
+        warnings: findings.filter((finding) => finding.severity === 'warning').length,
+        infos: findings.filter((finding) => finding.severity === 'info').length,
+    };
+    const provenance = provenanceRows([engine, behaviors, ...archetypes.map((entry) => entry.loaded)]);
+    return {
+        findings,
+        summary,
+        ok: summary.errors === 0,
+        notes: [
+            ...check.notes,
+            'The shipped runtime loads src/scenes/main.scene.json; other scenes are validated but are not loaded automatically.',
+        ],
+        provenance,
+        warnings: [...discoveryWarnings, ...mixedSourceWarnings(provenance)],
+    };
+}

package/dist/mcp/workspace-loader.js

@@ -0,0 +1,14 @@
+let mappings = {};
+let parentPrefixes = [];
+export function initialize(data) {
+    mappings = data.mappings;
+    parentPrefixes = data.parentPrefixes;
+}
+export function resolve(specifier, context, nextResolve) {
+    const mapped = mappings[specifier];
+    const parentURL = context.parentURL;
+    const bundledParent = parentURL !== undefined && parentPrefixes.some((prefix) => parentURL.startsWith(prefix));
+    return mapped && bundledParent
+        ? Promise.resolve({ url: mapped, shortCircuit: true })
+        : nextResolve(specifier, context);
+}

package/dist/mcp/workspace-runtime.js

@@ -0,0 +1,109 @@
+import { access, readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+const here = path.dirname(fileURLToPath(import.meta.url));
+const WORKSPACE_DIRECTORIES = {
+    '@waica/engine': 'engine',
+    '@waica/behaviors': 'behaviors',
+    '@waica/archetype-platformer': 'archetype-platformer',
+};
+let workspaceHooks;
+let workspacePackages;
+async function exists(target) {
+    try {
+        await access(target);
+        return true;
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return false;
+        throw error;
+    }
+}
+/**
+ * The server runs both from `packages/mcp/dist` and from the copy the waica CLI
+ * bundles under its own `dist`, so the checkout root is searched for rather than
+ * assumed at a fixed depth. An unrelated pnpm workspace is harmless: the built
+ * engine files below are what actually gate the hook.
+ */
+async function findWorkspaceRoot() {
+    for (let current = here;; current = path.dirname(current)) {
+        if (await exists(path.join(current, 'pnpm-workspace.yaml')))
+            return current;
+        const parent = path.dirname(current);
+        if (parent === current)
+            return undefined;
+    }
+}
+async function isPackageNamed(packageRoot, packageName) {
+    try {
+        const manifest = JSON.parse(await readFile(path.join(packageRoot, 'package.json'), 'utf8'));
+        return manifest.name === packageName;
+    }
+    catch {
+        return false;
+    }
+}
+async function loadWorkspacePackages() {
+    const found = new Map();
+    const repositoryRoot = await findWorkspaceRoot();
+    if (repositoryRoot === undefined)
+        return found;
+    for (const [packageName, directory] of Object.entries(WORKSPACE_DIRECTORIES)) {
+        const packageRoot = path.join(repositoryRoot, 'packages', directory);
+        if ((await exists(path.join(packageRoot, 'dist/index.js'))) &&
+            (await isPackageNamed(packageRoot, packageName))) {
+            found.set(packageName, packageRoot);
+        }
+    }
+    return found;
+}
+/**
+ * The built checkout copy of a bundled package, when the server runs from this
+ * repository. The waica CLI vendors its own copies under `dist`, so without
+ * this a workspace-linked project would look like a mismatch against them
+ * instead of like the very same package.
+ */
+export async function workspacePackageRoot(packageName) {
+    workspacePackages ??= loadWorkspacePackages();
+    return (await workspacePackages).get(packageName);
+}
+/**
+ * Built workspace packages still import one another by bare package name while
+ * checkout exports point at source TypeScript. Map only imports whose parent is
+ * already inside one of those built dist trees. Project-anchored resolution is
+ * deliberately outside this scope and therefore remains authoritative.
+ */
+export async function prepareWorkspaceRuntime() {
+    const repositoryRoot = await findWorkspaceRoot();
+    if (repositoryRoot === undefined)
+        return;
+    const files = {
+        '@waica/engine': path.join(repositoryRoot, 'packages/engine/dist/index.js'),
+        '@waica/behaviors': path.join(repositoryRoot, 'packages/behaviors/dist/index.js'),
+        '@waica/archetype-platformer': path.join(repositoryRoot, 'packages/archetype-platformer/dist/index.js'),
+        '@waica/archetype-platformer/manifest': path.join(repositoryRoot, 'packages/archetype-platformer/dist/manifest.js'),
+    };
+    if (!(await Promise.all(Object.values(files).map(exists))).every(Boolean))
+        return;
+    const mappings = Object.fromEntries(Object.entries(files).map(([specifier, file]) => [specifier, pathToFileURL(file).href]));
+    const parentPrefixes = ['engine', 'behaviors', 'archetype-platformer'].map((directory) => `${pathToFileURL(path.join(repositoryRoot, 'packages', directory, 'dist')).href}/`);
+    const moduleApi = await import('node:module');
+    if (typeof moduleApi.registerHooks === 'function') {
+        workspaceHooks = moduleApi.registerHooks({
+            resolve(specifier, context, nextResolve) {
+                const mapped = mappings[specifier];
+                const parentURL = context.parentURL;
+                const bundledParent = parentURL !== undefined && parentPrefixes.some((prefix) => parentURL.startsWith(prefix));
+                return mapped && bundledParent
+                    ? { url: mapped, shortCircuit: true }
+                    : nextResolve(specifier, context);
+            },
+        });
+        return;
+    }
+    moduleApi.register(new URL('./workspace-loader.js', import.meta.url), {
+        parentURL: import.meta.url,
+        data: { mappings, parentPrefixes },
+    });
+}