@quenty/studio-bridge 0.7.1 → 0.8.0

package/src/commands/framework/arg-builder.test.ts

@@ -0,0 +1,298 @@
+/**
+ * Unit tests for the arg builder DSL and schema converters.
+ */
+
+import { describe, it, expect } from 'vitest';
+import { arg, toYargsOptions, toJsonSchema } from './arg-builder.js';
+
+describe('arg.positional', () => {
+  it('creates a positional arg definition', () => {
+    const def = arg.positional({ description: 'Source code' });
+    expect(def.kind).toBe('positional');
+    expect(def.description).toBe('Source code');
+  });
+
+  it('defaults to string type', () => {
+    const def = arg.positional({ description: 'test' });
+    expect(def.type).toBe('string');
+  });
+
+  it('respects explicit number type', () => {
+    const def = arg.positional({ description: 'test', type: 'number' });
+    expect(def.type).toBe('number');
+  });
+
+  it('defaults to required', () => {
+    const def = arg.positional({ description: 'test' });
+    expect(def.required).toBe(true);
+  });
+
+  it('allows optional positionals', () => {
+    const def = arg.positional({ description: 'test', required: false });
+    expect(def.required).toBe(false);
+  });
+
+  it('supports choices', () => {
+    const def = arg.positional({
+      description: 'Direction',
+      choices: ['head', 'tail'] as const,
+    });
+    expect(def.choices).toEqual(['head', 'tail']);
+  });
+});
+
+describe('arg.option', () => {
+  it('creates an option arg definition', () => {
+    const def = arg.option({ description: 'Max count' });
+    expect(def.kind).toBe('option');
+    expect(def.description).toBe('Max count');
+  });
+
+  it('defaults to string type', () => {
+    const def = arg.option({ description: 'test' });
+    expect(def.type).toBe('string');
+  });
+
+  it('supports number type', () => {
+    const def = arg.option({ description: 'test', type: 'number' });
+    expect(def.type).toBe('number');
+  });
+
+  it('supports alias', () => {
+    const def = arg.option({ description: 'test', alias: 'n' });
+    expect(def.alias).toBe('n');
+  });
+
+  it('supports default value', () => {
+    const def = arg.option({
+      description: 'test',
+      type: 'number',
+      default: 50,
+    });
+    expect(def.default).toBe(50);
+  });
+
+  it('supports required flag', () => {
+    const def = arg.option({ description: 'test', required: true });
+    expect(def.required).toBe(true);
+  });
+
+  it('supports choices', () => {
+    const def = arg.option({
+      description: 'Mode',
+      choices: ['text', 'json'] as const,
+    });
+    expect(def.choices).toEqual(['text', 'json']);
+  });
+
+  it('supports array flag', () => {
+    const def = arg.option({ description: 'Levels', array: true });
+    expect(def.array).toBe(true);
+  });
+});
+
+describe('arg.flag', () => {
+  it('creates a flag arg definition', () => {
+    const def = arg.flag({ description: 'Include children' });
+    expect(def.kind).toBe('flag');
+    expect(def.type).toBe('boolean');
+  });
+
+  it('defaults to false', () => {
+    const def = arg.flag({ description: 'test' });
+    expect(def.default).toBe(false);
+  });
+
+  it('allows default true', () => {
+    const def = arg.flag({ description: 'test', default: true });
+    expect(def.default).toBe(true);
+  });
+
+  it('supports alias', () => {
+    const def = arg.flag({ description: 'test', alias: 'c' });
+    expect(def.alias).toBe('c');
+  });
+});
+
+describe('toYargsOptions', () => {
+  it('separates positionals from options', () => {
+    const result = toYargsOptions({
+      code: arg.positional({ description: 'Source' }),
+      count: arg.option({ description: 'Max', type: 'number' }),
+      verbose: arg.flag({ description: 'Verbose' }),
+    });
+
+    expect(result.positionals).toHaveLength(1);
+    expect(result.positionals[0].name).toBe('code');
+    expect(Object.keys(result.options)).toEqual(['count', 'verbose']);
+  });
+
+  it('converts positional fields', () => {
+    const result = toYargsOptions({
+      path: arg.positional({
+        description: 'DataModel path',
+        choices: ['Workspace', 'ServerStorage'] as const,
+      }),
+    });
+
+    const pos = result.positionals[0];
+    expect(pos.options.describe).toBe('DataModel path');
+    expect(pos.options.type).toBe('string');
+    expect(pos.options.demandOption).toBe(true);
+    expect(pos.options.choices).toEqual(['Workspace', 'ServerStorage']);
+  });
+
+  it('converts option fields', () => {
+    const result = toYargsOptions({
+      count: arg.option({
+        description: 'Number of entries',
+        type: 'number',
+        alias: 'n',
+        default: 50,
+      }),
+    });
+
+    const opt = result.options.count;
+    expect(opt.describe).toBe('Number of entries');
+    expect(opt.type).toBe('number');
+    expect(opt.alias).toBe('n');
+    expect(opt.default).toBe(50);
+  });
+
+  it('converts flag fields', () => {
+    const result = toYargsOptions({
+      json: arg.flag({ description: 'Output JSON', alias: 'j' }),
+    });
+
+    const opt = result.options.json;
+    expect(opt.describe).toBe('Output JSON');
+    expect(opt.type).toBe('boolean');
+    expect(opt.alias).toBe('j');
+    expect(opt.default).toBe(false);
+  });
+
+  it('omits undefined optional fields from options', () => {
+    const result = toYargsOptions({
+      name: arg.option({ description: 'Name' }),
+    });
+
+    const opt = result.options.name;
+    expect(opt).not.toHaveProperty('alias');
+    expect(opt).not.toHaveProperty('default');
+    expect(opt).not.toHaveProperty('choices');
+    expect(opt).not.toHaveProperty('array');
+  });
+
+  it('returns empty arrays for no args', () => {
+    const result = toYargsOptions({});
+    expect(result.positionals).toEqual([]);
+    expect(result.options).toEqual({});
+  });
+});
+
+describe('toJsonSchema', () => {
+  it('generates a valid object schema', () => {
+    const schema = toJsonSchema({
+      code: arg.positional({ description: 'Source code' }),
+    });
+
+    expect(schema.type).toBe('object');
+    expect(schema.additionalProperties).toBe(false);
+    expect(schema.properties.code).toBeDefined();
+  });
+
+  it('includes required positionals in required array', () => {
+    const schema = toJsonSchema({
+      code: arg.positional({ description: 'Source code' }),
+    });
+
+    expect(schema.required).toEqual(['code']);
+  });
+
+  it('includes required options in required array', () => {
+    const schema = toJsonSchema({
+      target: arg.option({ description: 'Target', required: true }),
+    });
+
+    expect(schema.required).toEqual(['target']);
+  });
+
+  it('omits required array when no args are required', () => {
+    const schema = toJsonSchema({
+      count: arg.option({ description: 'Count', type: 'number' }),
+      verbose: arg.flag({ description: 'Verbose' }),
+    });
+
+    expect(schema).not.toHaveProperty('required');
+  });
+
+  it('maps string type', () => {
+    const schema = toJsonSchema({
+      name: arg.option({ description: 'Name' }),
+    });
+
+    expect(schema.properties.name.type).toBe('string');
+  });
+
+  it('maps number type', () => {
+    const schema = toJsonSchema({
+      count: arg.option({ description: 'Count', type: 'number' }),
+    });
+
+    expect(schema.properties.count.type).toBe('number');
+  });
+
+  it('maps boolean type for flags', () => {
+    const schema = toJsonSchema({
+      verbose: arg.flag({ description: 'Verbose' }),
+    });
+
+    expect(schema.properties.verbose.type).toBe('boolean');
+  });
+
+  it('maps array options', () => {
+    const schema = toJsonSchema({
+      levels: arg.option({ description: 'Log levels', array: true }),
+    });
+
+    expect(schema.properties.levels.type).toBe('array');
+    expect(schema.properties.levels.items).toEqual({ type: 'string' });
+  });
+
+  it('maps choices to enum', () => {
+    const schema = toJsonSchema({
+      direction: arg.option({
+        description: 'Direction',
+        choices: ['head', 'tail'] as const,
+      }),
+    });
+
+    expect(schema.properties.direction.enum).toEqual(['head', 'tail']);
+  });
+
+  it('includes default values', () => {
+    const schema = toJsonSchema({
+      count: arg.option({ description: 'Count', type: 'number', default: 50 }),
+    });
+
+    expect(schema.properties.count.default).toBe(50);
+  });
+
+  it('includes description on all properties', () => {
+    const schema = toJsonSchema({
+      code: arg.positional({ description: 'Source code' }),
+      count: arg.option({ description: 'Max entries', type: 'number' }),
+      json: arg.flag({ description: 'JSON output' }),
+    });
+
+    expect(schema.properties.code.description).toBe('Source code');
+    expect(schema.properties.count.description).toBe('Max entries');
+    expect(schema.properties.json.description).toBe('JSON output');
+  });
+
+  it('returns empty properties for no args', () => {
+    const schema = toJsonSchema({});
+    expect(schema.properties).toEqual({});
+    expect(schema).not.toHaveProperty('required');
+  });
+});

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

@@ -0,0 +1,203 @@
+/**
+ * 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 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 {
+    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: {
+    description: string;
+    type?: 'string' | 'number';
+    alias?: string;
+    required?: boolean;
+    default?: string | number;
+    choices?: readonly string[];
+    array?: boolean;
+  }): ArgDefinition {
+    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: {
+    description: string;
+    alias?: string;
+    default?: boolean;
+  }): ArgDefinition {
+    return {
+      kind: 'flag',
+      type: 'boolean',
+      description: config.description,
+      alias: config.alias,
+      default: config.default ?? false,
+    };
+  },
+};
+
+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 function toYargsOptions(
+  args: Record<string, ArgDefinition>
+): YargsArgConfig {
+  const positionals: YargsPositional[] = [];
+  const options: Record<string, Record<string, unknown>> = {};
+
+  for (const [name, def] of Object.entries(args)) {
+    if (def.kind === 'positional') {
+      positionals.push({
+        name,
+        options: {
+          describe: def.description,
+          type: def.type as 'string' | 'number',
+          demandOption: def.required,
+          ...(def.choices ? { choices: def.choices } : {}),
+        },
+      });
+    } else {
+      const opt: Record<string, unknown> = {
+        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 };
+}
+
+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 function toJsonSchema(
+  args: Record<string, ArgDefinition>
+): JsonSchemaOutput {
+  const properties: Record<string, Record<string, unknown>> = {};
+  const required: string[] = [];
+
+  for (const [name, def] of Object.entries(args)) {
+    const prop: Record<string, unknown> = {
+      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: JsonSchemaOutput = {
+    type: 'object',
+    properties,
+    additionalProperties: false,
+  };
+
+  if (required.length > 0) {
+    schema.required = required;
+  }
+
+  return schema;
+}

package/src/commands/framework/command-registry.test.ts

@@ -0,0 +1,204 @@
+/**
+ * Unit tests for the CommandRegistry.
+ */
+
+import { describe, it, expect } from 'vitest';
+import { CommandRegistry } from './command-registry.js';
+import { defineCommand } from './define-command.js';
+
+function makeCommand(
+  overrides: Partial<{
+    group: string | null;
+    name: string;
+    category: 'execution' | 'infrastructure';
+    safety: 'read' | 'mutate' | 'none';
+    scope: 'session' | 'connection' | 'standalone';
+  }> = {}
+) {
+  const scope = overrides.scope ?? 'session';
+
+  const base = {
+    group:
+      overrides.group === undefined
+        ? ('console' as string | null)
+        : overrides.group,
+    name: overrides.name ?? 'exec',
+    description: 'Test command',
+    category: overrides.category ?? ('execution' as const),
+    safety: overrides.safety ?? ('mutate' as const),
+    args: {},
+  };
+
+  if (scope === 'session') {
+    return defineCommand({
+      ...base,
+      scope: 'session',
+      handler: async () => ({}),
+    });
+  } else if (scope === 'connection') {
+    return defineCommand({
+      ...base,
+      scope: 'connection',
+      handler: async () => ({}),
+    });
+  } else {
+    return defineCommand({
+      ...base,
+      scope: 'standalone',
+      handler: async () => ({}),
+    });
+  }
+}
+
+describe('CommandRegistry', () => {
+  describe('register / getAll', () => {
+    it('registers and retrieves commands', () => {
+      const registry = new CommandRegistry();
+      const cmd = makeCommand();
+      registry.register(cmd);
+
+      expect(registry.getAll()).toHaveLength(1);
+      expect(registry.getAll()[0]).toBe(cmd);
+    });
+
+    it('maintains insertion order', () => {
+      const registry = new CommandRegistry();
+      const a = makeCommand({ name: 'alpha' });
+      const b = makeCommand({ name: 'beta' });
+      const c = makeCommand({ name: 'charlie' });
+
+      registry.register(a);
+      registry.register(b);
+      registry.register(c);
+
+      const names = registry.getAll().map((d) => d.name);
+      expect(names).toEqual(['alpha', 'beta', 'charlie']);
+    });
+
+    it('returns empty array when no commands registered', () => {
+      const registry = new CommandRegistry();
+      expect(registry.getAll()).toEqual([]);
+    });
+  });
+
+  describe('getByGroup', () => {
+    it('filters by group name', () => {
+      const registry = new CommandRegistry();
+      registry.register(makeCommand({ group: 'console', name: 'exec' }));
+      registry.register(makeCommand({ group: 'console', name: 'logs' }));
+      registry.register(makeCommand({ group: 'process', name: 'list' }));
+
+      const consoleCommands = registry.getByGroup('console');
+      expect(consoleCommands).toHaveLength(2);
+      expect(consoleCommands.map((c) => c.name)).toEqual(['exec', 'logs']);
+    });
+
+    it('returns empty array for unknown group', () => {
+      const registry = new CommandRegistry();
+      registry.register(makeCommand({ group: 'console', name: 'exec' }));
+
+      expect(registry.getByGroup('nonexistent')).toEqual([]);
+    });
+  });
+
+  describe('getGroups', () => {
+    it('returns unique group names', () => {
+      const registry = new CommandRegistry();
+      registry.register(makeCommand({ group: 'console', name: 'exec' }));
+      registry.register(makeCommand({ group: 'console', name: 'logs' }));
+      registry.register(makeCommand({ group: 'process', name: 'list' }));
+
+      const groups = registry.getGroups();
+      expect(groups).toEqual(['console', 'process']);
+    });
+
+    it('excludes null group (top-level commands)', () => {
+      const registry = new CommandRegistry();
+      registry.register(
+        makeCommand({ group: null, name: 'serve', scope: 'standalone' })
+      );
+      registry.register(makeCommand({ group: 'console', name: 'exec' }));
+
+      const groups = registry.getGroups();
+      expect(groups).toEqual(['console']);
+    });
+
+    it('returns empty array when no groups', () => {
+      const registry = new CommandRegistry();
+      expect(registry.getGroups()).toEqual([]);
+    });
+  });
+
+  describe('getTopLevel', () => {
+    it('returns commands with null group', () => {
+      const registry = new CommandRegistry();
+      registry.register(
+        makeCommand({ group: null, name: 'serve', scope: 'standalone' })
+      );
+      registry.register(
+        makeCommand({ group: null, name: 'mcp', scope: 'standalone' })
+      );
+      registry.register(makeCommand({ group: 'console', name: 'exec' }));
+
+      const topLevel = registry.getTopLevel();
+      expect(topLevel).toHaveLength(2);
+      expect(topLevel.map((c) => c.name)).toEqual(['serve', 'mcp']);
+    });
+
+    it('returns empty array when no top-level commands', () => {
+      const registry = new CommandRegistry();
+      registry.register(makeCommand({ group: 'console', name: 'exec' }));
+
+      expect(registry.getTopLevel()).toEqual([]);
+    });
+  });
+
+  describe('getByCategory', () => {
+    it('filters by category', () => {
+      const registry = new CommandRegistry();
+      registry.register(makeCommand({ name: 'exec', category: 'execution' }));
+      registry.register(
+        makeCommand({ name: 'list', category: 'infrastructure' })
+      );
+      registry.register(makeCommand({ name: 'logs', category: 'execution' }));
+
+      const execution = registry.getByCategory('execution');
+      expect(execution).toHaveLength(2);
+      expect(execution.map((c) => c.name)).toEqual(['exec', 'logs']);
+    });
+  });
+
+  describe('get', () => {
+    it('finds by group and name', () => {
+      const registry = new CommandRegistry();
+      const cmd = makeCommand({ group: 'console', name: 'exec' });
+      registry.register(cmd);
+
+      expect(registry.get('console', 'exec')).toBe(cmd);
+    });
+
+    it('finds top-level commands with null group', () => {
+      const registry = new CommandRegistry();
+      const cmd = makeCommand({
+        group: null,
+        name: 'serve',
+        scope: 'standalone',
+      });
+      registry.register(cmd);
+
+      expect(registry.get(null, 'serve')).toBe(cmd);
+    });
+
+    it('returns undefined for missing command', () => {
+      const registry = new CommandRegistry();
+      expect(registry.get('console', 'nonexistent')).toBeUndefined();
+    });
+
+    it('returns undefined when group matches but name does not', () => {
+      const registry = new CommandRegistry();
+      registry.register(makeCommand({ group: 'console', name: 'exec' }));
+
+      expect(registry.get('console', 'logs')).toBeUndefined();
+    });
+  });
+});