@quenty/studio-bridge 0.7.1 → 0.8.0

package/dist/src/commands/formatters.test.js

@@ -0,0 +1,211 @@
+/**
+ * Unit tests for per-command CLI formatters.
+ * Tests the formatResult callbacks in isolation with mock data.
+ */
+import { describe, it, expect } from 'vitest';
+import { execCommand } from './console/exec/exec.js';
+import { logsCommand, formatLogsText } from './console/logs/logs.js';
+import { listCommand, formatSessionsTable } from './process/list/list.js';
+import { infoCommand, formatStateText } from './process/info/info.js';
+import { queryCommand, formatQueryText } from './explorer/query/query.js';
+import { screenshotCommand } from './viewport/screenshot/screenshot.js';
+describe('exec formatter', () => {
+    const format = execCommand.cli.format;
+    it('joins output lines', () => {
+        const result = { success: true, output: ['Hello', 'World'], summary: 'ok' };
+        expect(format(result)).toBe('Hello\nWorld');
+    });
+    it('appends error when present', () => {
+        const result = {
+            success: false,
+            output: ['partial'],
+            error: 'boom',
+            summary: 'fail',
+        };
+        expect(format(result)).toBe('partial\nboom');
+    });
+    it('falls back to summary when no output lines', () => {
+        const result = {
+            success: true,
+            output: [],
+            summary: 'Script executed successfully',
+        };
+        expect(format(result)).toBe('Script executed successfully');
+    });
+    it('handles error with no output', () => {
+        const result = {
+            success: false,
+            output: [],
+            error: 'boom',
+            summary: 'fail',
+        };
+        expect(format(result)).toBe('boom');
+    });
+});
+describe('logs formatter', () => {
+    it('returns summary when no entries', () => {
+        const result = {
+            entries: [],
+            total: 0,
+            bufferCapacity: 100,
+            summary: '0 entries',
+        };
+        expect(formatLogsText(result)).toBe('0 entries');
+    });
+    it('formats timestamped log lines', () => {
+        const result = {
+            entries: [
+                { level: 'Print', body: 'Hello', timestamp: 1000000 },
+                { level: 'Error', body: 'Boom', timestamp: 1001000 },
+            ],
+            total: 2,
+            bufferCapacity: 100,
+            summary: '2 entries',
+        };
+        const text = formatLogsText(result);
+        expect(text).toContain('Hello');
+        expect(text).toContain('Boom');
+        expect(text).toContain('(2 of 2 entries)');
+    });
+    it('is wired into command definition', () => {
+        expect(logsCommand.cli.format).toBe(formatLogsText);
+    });
+});
+describe('list formatter', () => {
+    it('returns summary when no sessions', () => {
+        const result = { sessions: [], summary: 'No active sessions.' };
+        expect(formatSessionsTable(result)).toBe('No active sessions.');
+    });
+    it('formats session table', () => {
+        const result = {
+            sessions: [
+                {
+                    sessionId: 'abcdefgh-1234',
+                    placeName: 'TestPlace',
+                    state: 'Edit',
+                    context: 'edit',
+                    pluginVersion: '1.0.0',
+                    capabilities: [],
+                    connectedAt: new Date(),
+                    origin: 'user',
+                    instanceId: 'inst-1',
+                    placeId: 123,
+                    gameId: 456,
+                },
+            ],
+            summary: '1 session(s) connected.',
+        };
+        const text = formatSessionsTable(result);
+        expect(text).toContain('Session');
+        expect(text).toContain('abcdefg'); // truncated session ID
+        expect(text).toContain('TestPlace');
+        expect(text).toContain('Edit');
+    });
+    it('is wired into command definition', () => {
+        expect(listCommand.cli.format).toBe(formatSessionsTable);
+    });
+});
+describe('info formatter', () => {
+    it('formats key-value pairs', () => {
+        const result = {
+            state: 'Edit',
+            placeName: 'MyPlace',
+            placeId: 123,
+            gameId: 456,
+            summary: 'Mode: Edit, Place: MyPlace (123)',
+        };
+        const text = formatStateText(result);
+        expect(text).toContain('Mode:');
+        expect(text).toContain('MyPlace');
+        expect(text).toContain('123');
+        expect(text).toContain('456');
+    });
+    it('is wired into command definition', () => {
+        expect(infoCommand.cli.format).toBe(formatStateText);
+    });
+});
+describe('query formatter', () => {
+    it('formats a simple node', () => {
+        const result = {
+            node: {
+                name: 'Workspace',
+                className: 'Workspace',
+                path: 'game.Workspace',
+            },
+            summary: 'Workspace (Workspace) at game.Workspace',
+        };
+        const text = formatQueryText(result);
+        expect(text).toContain('Workspace');
+    });
+    it('formats nested children with indentation', () => {
+        const result = {
+            node: {
+                name: 'Workspace',
+                className: 'Workspace',
+                path: 'game.Workspace',
+                children: [
+                    {
+                        name: 'Part',
+                        className: 'Part',
+                        path: 'game.Workspace.Part',
+                    },
+                ],
+            },
+            summary: 'Workspace',
+        };
+        const text = formatQueryText(result);
+        const lines = text.split('\n');
+        // Root should not be indented
+        expect(lines[0]).toMatch(/^Workspace/);
+        // Child should be indented
+        expect(lines[1]).toMatch(/^ {2}Part/);
+    });
+    it('formats properties and attributes', () => {
+        const result = {
+            node: {
+                name: 'Part',
+                className: 'Part',
+                path: 'game.Workspace.Part',
+                properties: { Size: [4, 1, 2] },
+                attributes: { Health: 100 },
+            },
+            summary: 'Part',
+        };
+        const text = formatQueryText(result);
+        expect(text).toContain('Size:');
+        expect(text).toContain('@Health:');
+    });
+    it('is wired into command definition', () => {
+        expect(queryCommand.cli.format).toBe(formatQueryText);
+    });
+});
+describe('screenshot formatter', () => {
+    it('format returns summary only', () => {
+        const format = screenshotCommand.cli.format;
+        const result = {
+            data: 'base64...',
+            width: 800,
+            height: 600,
+            summary: 'Screenshot captured (800x600)',
+        };
+        expect(format(result)).toBe('Screenshot captured (800x600)');
+    });
+    it('json override omits data field', () => {
+        const json = screenshotCommand.cli.json;
+        const result = {
+            data: 'base64...',
+            width: 800,
+            height: 600,
+            summary: 'Screenshot captured (800x600)',
+        };
+        const parsed = JSON.parse(json(result));
+        expect(parsed).not.toHaveProperty('data');
+        expect(parsed.width).toBe(800);
+        expect(parsed.height).toBe(600);
+        expect(parsed.summary).toBe('Screenshot captured (800x600)');
+    });
+    it('has binaryField set to data', () => {
+        expect(screenshotCommand.cli.binaryField).toBe('data');
+    });
+});
+//# sourceMappingURL=formatters.test.js.map

package/dist/src/commands/formatters.test.js.map

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

package/dist/src/commands/framework/action-loader.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Scans co-located `.luau` action files from the command directory tree
+ * and returns their source contents for pushing to plugin sessions.
+ *
+ * Each command directory may contain a `.luau` file with the same stem
+ * as its `.ts` file (e.g. `exec.luau` next to `exec.ts`). These files
+ * are Luau modules that register action handlers in the plugin's
+ * ActionRouter at runtime.
+ */
+export interface ActionSource {
+    /** Action module name (derived from the filename, e.g. "exec"). */
+    name: string;
+    /** Full Luau source code of the action module. */
+    source: string;
+    /** Relative path within the commands directory (for diagnostics). */
+    relativePath: string;
+    /** SHA-256 hex digest of the source content. */
+    hash: string;
+}
+/**
+ * Recursively scan `baseDir` for `.luau` files and return their contents
+ * as `ActionSource` entries. Only files that end in `.luau` are included.
+ */
+export declare function loadActionSourcesAsync(baseDir?: string): Promise<ActionSource[]>;
+//# sourceMappingURL=action-loader.d.ts.map

package/dist/src/commands/framework/action-loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"action-loader.d.ts","sourceRoot":"","sources":["../../../../src/commands/framework/action-loader.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAOH,MAAM,WAAW,YAAY;IAC3B,mEAAmE;IACnE,IAAI,EAAE,MAAM,CAAC;IACb,kDAAkD;IAClD,MAAM,EAAE,MAAM,CAAC;IACf,qEAAqE;IACrE,YAAY,EAAE,MAAM,CAAC;IACrB,gDAAgD;IAChD,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;GAGG;AACH,wBAAsB,sBAAsB,CAC1C,OAAO,CAAC,EAAE,MAAM,GACf,OAAO,CAAC,YAAY,EAAE,CAAC,CAMzB"}

package/dist/src/commands/framework/action-loader.js

@@ -0,0 +1,46 @@
+/**
+ * Scans co-located `.luau` action files from the command directory tree
+ * and returns their source contents for pushing to plugin sessions.
+ *
+ * Each command directory may contain a `.luau` file with the same stem
+ * as its `.ts` file (e.g. `exec.luau` next to `exec.ts`). These files
+ * are Luau modules that register action handlers in the plugin's
+ * ActionRouter at runtime.
+ */
+import { createHash } from 'crypto';
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import { resolvePackagePath } from '@quenty/nevermore-template-helpers';
+/**
+ * Recursively scan `baseDir` for `.luau` files and return their contents
+ * as `ActionSource` entries. Only files that end in `.luau` are included.
+ */
+export async function loadActionSourcesAsync(baseDir) {
+    const dir = baseDir ?? resolvePackagePath(import.meta.url, 'src', 'commands');
+    const actions = [];
+    await scanDirAsync(dir, dir, actions);
+    return actions;
+}
+async function scanDirAsync(baseDir, currentDir, results) {
+    let entries;
+    try {
+        entries = await fs.readdir(currentDir, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    for (const entry of entries) {
+        const fullPath = path.join(currentDir, entry.name);
+        if (entry.isDirectory()) {
+            await scanDirAsync(baseDir, fullPath, results);
+        }
+        else if (entry.name.endsWith('.luau')) {
+            const source = await fs.readFile(fullPath, 'utf-8');
+            const name = path.basename(entry.name, '.luau');
+            const relativePath = path.relative(baseDir, fullPath);
+            const hash = createHash('sha256').update(source).digest('hex');
+            results.push({ name, source, relativePath, hash });
+        }
+    }
+}
+//# sourceMappingURL=action-loader.js.map

package/dist/src/commands/framework/action-loader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"action-loader.js","sourceRoot":"","sources":["../../../../src/commands/framework/action-loader.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC;AACpC,OAAO,KAAK,EAAE,MAAM,aAAa,CAAC;AAClC,OAAO,KAAK,IAAI,MAAM,MAAM,CAAC;AAC7B,OAAO,EAAE,kBAAkB,EAAE,MAAM,oCAAoC,CAAC;AAaxE;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,sBAAsB,CAC1C,OAAgB;IAEhB,MAAM,GAAG,GAAG,OAAO,IAAI,kBAAkB,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE,KAAK,EAAE,UAAU,CAAC,CAAC;IAE9E,MAAM,OAAO,GAAmB,EAAE,CAAC;IACnC,MAAM,YAAY,CAAC,GAAG,EAAE,GAAG,EAAE,OAAO,CAAC,CAAC;IACtC,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,KAAK,UAAU,YAAY,CACzB,OAAe,EACf,UAAkB,EAClB,OAAuB;IAEvB,IAAI,OAAO,CAAC;IACZ,IAAI,CAAC;QACH,OAAO,GAAG,MAAM,EAAE,CAAC,OAAO,CAAC,UAAU,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAC;IAClE,CAAC;IAAC,MAAM,CAAC;QACP,OAAO;IACT,CAAC;IAED,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;QAC5B,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;QACnD,IAAI,KAAK,CAAC,WAAW,EAAE,EAAE,CAAC;YACxB,MAAM,YAAY,CAAC,OAAO,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAC;QACjD,CAAC;aAAM,IAAI,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC;YACxC,MAAM,MAAM,GAAG,MAAM,EAAE,CAAC,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;YACpD,MAAM,IAAI,GAAG,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;YAChD,MAAM,YAAY,GAAG,IAAI,CAAC,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;YACtD,MAAM,IAAI,GAAG,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;YAC/D,OAAO,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,YAAY,EAAE,IAAI,EAAE,CAAC,CAAC;QACrD,CAAC;IACH,CAAC;AACH,CAAC"}

package/dist/src/commands/framework/action-loader.test.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Tests for action-loader: scanning .luau files and computing content hashes.
+ */
+export {};
+//# sourceMappingURL=action-loader.test.d.ts.map

package/dist/src/commands/framework/action-loader.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"action-loader.test.d.ts","sourceRoot":"","sources":["../../../../src/commands/framework/action-loader.test.ts"],"names":[],"mappings":"AAAA;;GAEG"}

package/dist/src/commands/framework/action-loader.test.js

@@ -0,0 +1,89 @@
+/**
+ * Tests for action-loader: scanning .luau files and computing content hashes.
+ */
+import { createHash } from 'crypto';
+import * as fs from 'fs/promises';
+import * as os from 'os';
+import * as path from 'path';
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { loadActionSourcesAsync } from './action-loader.js';
+let tmpDir;
+beforeEach(async () => {
+    tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'action-loader-'));
+});
+afterEach(async () => {
+    await fs.rm(tmpDir, { recursive: true, force: true });
+});
+function sha256(content) {
+    return createHash('sha256').update(content).digest('hex');
+}
+describe('loadActionSourcesAsync', () => {
+    it('loads .luau files from a flat directory', async () => {
+        const source = 'local M = {} return M';
+        await fs.writeFile(path.join(tmpDir, 'hello.luau'), source);
+        const results = await loadActionSourcesAsync(tmpDir);
+        expect(results).toHaveLength(1);
+        expect(results[0].name).toBe('hello');
+        expect(results[0].source).toBe(source);
+        expect(results[0].relativePath).toBe('hello.luau');
+    });
+    it('computes SHA-256 hash of source content', async () => {
+        const source = 'return function() end';
+        await fs.writeFile(path.join(tmpDir, 'test.luau'), source);
+        const results = await loadActionSourcesAsync(tmpDir);
+        expect(results).toHaveLength(1);
+        expect(results[0].hash).toBe(sha256(source));
+    });
+    it('different content produces different hashes', async () => {
+        await fs.writeFile(path.join(tmpDir, 'a.luau'), 'version 1');
+        await fs.writeFile(path.join(tmpDir, 'b.luau'), 'version 2');
+        const results = await loadActionSourcesAsync(tmpDir);
+        expect(results).toHaveLength(2);
+        const hashA = results.find((r) => r.name === 'a').hash;
+        const hashB = results.find((r) => r.name === 'b').hash;
+        expect(hashA).not.toBe(hashB);
+    });
+    it('identical content produces identical hashes', async () => {
+        const source = 'local x = 42';
+        const subDir = path.join(tmpDir, 'sub');
+        await fs.mkdir(subDir);
+        await fs.writeFile(path.join(tmpDir, 'a.luau'), source);
+        await fs.writeFile(path.join(subDir, 'b.luau'), source);
+        const results = await loadActionSourcesAsync(tmpDir);
+        expect(results).toHaveLength(2);
+        const hashA = results.find((r) => r.name === 'a').hash;
+        const hashB = results.find((r) => r.name === 'b').hash;
+        expect(hashA).toBe(hashB);
+    });
+    it('recursively scans subdirectories', async () => {
+        const subDir = path.join(tmpDir, 'nested', 'deep');
+        await fs.mkdir(subDir, { recursive: true });
+        await fs.writeFile(path.join(subDir, 'deep.luau'), 'return nil');
+        const results = await loadActionSourcesAsync(tmpDir);
+        expect(results).toHaveLength(1);
+        expect(results[0].name).toBe('deep');
+        expect(results[0].relativePath).toBe(path.join('nested', 'deep', 'deep.luau'));
+    });
+    it('ignores non-.luau files', async () => {
+        await fs.writeFile(path.join(tmpDir, 'script.lua'), 'not included');
+        await fs.writeFile(path.join(tmpDir, 'module.ts'), 'not included');
+        await fs.writeFile(path.join(tmpDir, 'action.luau'), 'included');
+        const results = await loadActionSourcesAsync(tmpDir);
+        expect(results).toHaveLength(1);
+        expect(results[0].name).toBe('action');
+    });
+    it('returns empty array for empty directory', async () => {
+        const results = await loadActionSourcesAsync(tmpDir);
+        expect(results).toHaveLength(0);
+    });
+    it('returns empty array for non-existent directory', async () => {
+        const results = await loadActionSourcesAsync(path.join(tmpDir, 'nope'));
+        expect(results).toHaveLength(0);
+    });
+    it('hash is a 64-character hex string (SHA-256)', async () => {
+        await fs.writeFile(path.join(tmpDir, 'check.luau'), 'content');
+        const results = await loadActionSourcesAsync(tmpDir);
+        expect(results[0].hash).toMatch(/^[0-9a-f]{64}$/);
+    });
+});
+//# sourceMappingURL=action-loader.test.js.map

package/dist/src/commands/framework/action-loader.test.js.map

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

package/dist/src/commands/framework/arg-builder.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Argument definition DSL and schema converters.
+ *
+ * `arg.positional()`, `arg.option()`, and `arg.flag()` produce `ArgDefinition`
+ * objects that carry enough metadata to generate both yargs options and
+ * JSON Schema properties for MCP tools.
+ */
+export type ArgKind = 'positional' | 'option' | 'flag';
+export type ArgType = 'string' | 'number' | 'boolean';
+export interface ArgDefinition {
+    kind: ArgKind;
+    type: ArgType;
+    description: string;
+    required?: boolean;
+    default?: unknown;
+    alias?: string;
+    choices?: readonly string[];
+    array?: boolean;
+}
+export declare const arg: {
+    /**
+     * Define a positional argument. Required by default.
+     *
+     * ```ts
+     * args: { code: arg.positional({ description: 'Luau source code' }) }
+     * ```
+     */
+    positional(config: {
+        description: string;
+        type?: "string" | "number";
+        required?: boolean;
+        choices?: readonly string[];
+    }): ArgDefinition;
+    /**
+     * Define a named option (`--name <value>`).
+     *
+     * ```ts
+     * args: { count: arg.option({ description: 'Max entries', type: 'number' }) }
+     * ```
+     */
+    option(config: {
+        description: string;
+        type?: "string" | "number";
+        alias?: string;
+        required?: boolean;
+        default?: string | number;
+        choices?: readonly string[];
+        array?: boolean;
+    }): ArgDefinition;
+    /**
+     * Define a boolean flag (`--verbose`, `--json`).
+     *
+     * ```ts
+     * args: { children: arg.flag({ description: 'Include children' }) }
+     * ```
+     */
+    flag(config: {
+        description: string;
+        alias?: string;
+        default?: boolean;
+    }): ArgDefinition;
+};
+export interface YargsPositional {
+    name: string;
+    options: {
+        describe: string;
+        type: 'string' | 'number';
+        demandOption?: boolean;
+        choices?: readonly string[];
+    };
+}
+export interface YargsArgConfig {
+    positionals: YargsPositional[];
+    options: Record<string, Record<string, unknown>>;
+}
+/**
+ * Convert an args record into yargs-compatible positional and option configs.
+ */
+export declare function toYargsOptions(args: Record<string, ArgDefinition>): YargsArgConfig;
+export interface JsonSchemaOutput {
+    type: 'object';
+    properties: Record<string, Record<string, unknown>>;
+    required?: string[];
+    additionalProperties: false;
+}
+/**
+ * Convert an args record into a JSON Schema object suitable for MCP tool
+ * `inputSchema`. Positional args that are required become `required` in
+ * the schema. Options with `required: true` are also included.
+ */
+export declare function toJsonSchema(args: Record<string, ArgDefinition>): JsonSchemaOutput;
+//# sourceMappingURL=arg-builder.d.ts.map

package/dist/src/commands/framework/arg-builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"arg-builder.d.ts","sourceRoot":"","sources":["../../../../src/commands/framework/arg-builder.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,MAAM,OAAO,GAAG,YAAY,GAAG,QAAQ,GAAG,MAAM,CAAC;AACvD,MAAM,MAAM,OAAO,GAAG,QAAQ,GAAG,QAAQ,GAAG,SAAS,CAAC;AAEtD,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,OAAO,CAAC;IACd,IAAI,EAAE,OAAO,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5B,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,eAAO,MAAM,GAAG;IACd;;;;;;OAMG;uBACgB;QACjB,WAAW,EAAE,MAAM,CAAC;QACpB,IAAI,CAAC,EAAE,QAAQ,GAAG,QAAQ,CAAC;QAC3B,QAAQ,CAAC,EAAE,OAAO,CAAC;QACnB,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;KAC7B,GAAG,aAAa;IAUjB;;;;;;OAMG;mBACY;QACb,WAAW,EAAE,MAAM,CAAC;QACpB,IAAI,CAAC,EAAE,QAAQ,GAAG,QAAQ,CAAC;QAC3B,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,QAAQ,CAAC,EAAE,OAAO,CAAC;QACnB,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;QAC1B,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;QAC5B,KAAK,CAAC,EAAE,OAAO,CAAC;KACjB,GAAG,aAAa;IAajB;;;;;;OAMG;iBACU;QACX,WAAW,EAAE,MAAM,CAAC;QACpB,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,OAAO,CAAC,EAAE,OAAO,CAAC;KACnB,GAAG,aAAa;CASlB,CAAC;AAEF,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE;QACP,QAAQ,EAAE,MAAM,CAAC;QACjB,IAAI,EAAE,QAAQ,GAAG,QAAQ,CAAC;QAC1B,YAAY,CAAC,EAAE,OAAO,CAAC;QACvB,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;KAC7B,CAAC;CACH;AAED,MAAM,WAAW,cAAc;IAC7B,WAAW,EAAE,eAAe,EAAE,CAAC;IAC/B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CAClD;AAED;;GAEG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,GAClC,cAAc,CA6BhB;AAED,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,QAAQ,CAAC;IACf,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACpD,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,oBAAoB,EAAE,KAAK,CAAC;CAC7B;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAC1B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,GAClC,gBAAgB,CA0ClB"}

package/dist/src/commands/framework/arg-builder.js

@@ -0,0 +1,137 @@
+/**
+ * Argument definition DSL and schema converters.
+ *
+ * `arg.positional()`, `arg.option()`, and `arg.flag()` produce `ArgDefinition`
+ * objects that carry enough metadata to generate both yargs options and
+ * JSON Schema properties for MCP tools.
+ */
+export const arg = {
+    /**
+     * Define a positional argument. Required by default.
+     *
+     * ```ts
+     * args: { code: arg.positional({ description: 'Luau source code' }) }
+     * ```
+     */
+    positional(config) {
+        return {
+            kind: 'positional',
+            type: config.type ?? 'string',
+            description: config.description,
+            required: config.required ?? true,
+            choices: config.choices,
+        };
+    },
+    /**
+     * Define a named option (`--name <value>`).
+     *
+     * ```ts
+     * args: { count: arg.option({ description: 'Max entries', type: 'number' }) }
+     * ```
+     */
+    option(config) {
+        return {
+            kind: 'option',
+            type: config.type ?? 'string',
+            description: config.description,
+            alias: config.alias,
+            required: config.required,
+            default: config.default,
+            choices: config.choices,
+            array: config.array,
+        };
+    },
+    /**
+     * Define a boolean flag (`--verbose`, `--json`).
+     *
+     * ```ts
+     * args: { children: arg.flag({ description: 'Include children' }) }
+     * ```
+     */
+    flag(config) {
+        return {
+            kind: 'flag',
+            type: 'boolean',
+            description: config.description,
+            alias: config.alias,
+            default: config.default ?? false,
+        };
+    },
+};
+/**
+ * Convert an args record into yargs-compatible positional and option configs.
+ */
+export function toYargsOptions(args) {
+    const positionals = [];
+    const options = {};
+    for (const [name, def] of Object.entries(args)) {
+        if (def.kind === 'positional') {
+            positionals.push({
+                name,
+                options: {
+                    describe: def.description,
+                    type: def.type,
+                    demandOption: def.required,
+                    ...(def.choices ? { choices: def.choices } : {}),
+                },
+            });
+        }
+        else {
+            const opt = {
+                describe: def.description,
+                type: def.type,
+            };
+            if (def.alias)
+                opt.alias = def.alias;
+            if (def.default !== undefined)
+                opt.default = def.default;
+            if (def.choices)
+                opt.choices = def.choices;
+            if (def.array)
+                opt.array = def.array;
+            options[name] = opt;
+        }
+    }
+    return { positionals, options };
+}
+/**
+ * Convert an args record into a JSON Schema object suitable for MCP tool
+ * `inputSchema`. Positional args that are required become `required` in
+ * the schema. Options with `required: true` are also included.
+ */
+export function toJsonSchema(args) {
+    const properties = {};
+    const required = [];
+    for (const [name, def] of Object.entries(args)) {
+        const prop = {
+            description: def.description,
+        };
+        if (def.array) {
+            prop.type = 'array';
+            prop.items = { type: def.type };
+        }
+        else {
+            prop.type = def.type;
+        }
+        if (def.choices) {
+            prop.enum = [...def.choices];
+        }
+        if (def.default !== undefined) {
+            prop.default = def.default;
+        }
+        properties[name] = prop;
+        if (def.required) {
+            required.push(name);
+        }
+    }
+    const schema = {
+        type: 'object',
+        properties,
+        additionalProperties: false,
+    };
+    if (required.length > 0) {
+        schema.required = required;
+    }
+    return schema;
+}
+//# sourceMappingURL=arg-builder.js.map

package/dist/src/commands/framework/arg-builder.js.map

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