@jackwener/opencli 1.8.0 → 1.8.1

package/clis/geogebra/add-point.js

@@ -0,0 +1,27 @@
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import { ensureApplet, ggbEval, normalizeCoords, normalizeLabel, requireGgbSuccess } from './utils.js';
+
+cli({
+  site: 'geogebra',
+  name: 'add-point',
+  access: 'write',
+  description: 'Create a point with given label and coordinates',
+  domain: 'www.geogebra.org',
+  strategy: Strategy.PUBLIC,
+  browser: true,
+  navigateBefore: false,
+  example: 'opencli geogebra add-point --name A --coords 1,2',
+  args: [
+    { name: 'name', required: true, help: 'Point label (e.g. A, B, P1)' },
+    { name: 'coords', required: true, help: 'Coordinates as x,y (e.g. "1,2")' },
+  ],
+  columns: ['name', 'x', 'y'],
+  func: async (page, kwargs) => {
+    const name = normalizeLabel(kwargs.name, 'name');
+    const [x, y] = normalizeCoords(kwargs.coords);
+    const cmd = `${name}=(${x},${y})`;
+    await ensureApplet(page);
+    const result = requireGgbSuccess(await ggbEval(page, cmd), `Failed to create point: ${cmd}`);
+    return [{ name, x, y }];
+  },
+});

package/clis/geogebra/add-polygon.js

@@ -0,0 +1,25 @@
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import { ensureApplet, ggbEval, normalizeLabelList, requireGgbSuccess } from './utils.js';
+
+cli({
+  site: 'geogebra',
+  name: 'add-polygon',
+  access: 'write',
+  description: 'Create a polygon from a list of point labels',
+  domain: 'www.geogebra.org',
+  strategy: Strategy.PUBLIC,
+  browser: true,
+  navigateBefore: false,
+  example: 'opencli geogebra add-polygon --points A,B,C',
+  args: [
+    { name: 'points', required: true, help: 'Comma-separated point labels (e.g. "A,B,C" or "A,B,C,D")' },
+  ],
+  columns: ['label', 'vertices'],
+  func: async (page, kwargs) => {
+    const points = normalizeLabelList(kwargs.points, 'points', 3, 50);
+    const cmd = `Polygon(${points.join(',')})`;
+    await ensureApplet(page);
+    const result = requireGgbSuccess(await ggbEval(page, cmd), `Failed to create polygon: ${cmd}`);
+    return [{ label: result.label, vertices: points.join(',') }];
+  },
+});

package/clis/geogebra/eval.js

@@ -0,0 +1,35 @@
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import { ArgumentError } from '@jackwener/opencli/errors';
+import { ensureApplet, ggbEval, requireGgbSuccess } from './utils.js';
+
+cli({
+  site: 'geogebra',
+  name: 'eval',
+  access: 'write',
+  description: 'Execute one or more GeoGebra command strings (semicolon-separated)',
+  domain: 'www.geogebra.org',
+  strategy: Strategy.PUBLIC,
+  browser: true,
+  navigateBefore: false,
+  example: 'opencli geogebra eval "A=(0,0);B=(4,0);c=Circle(A,B);d=Circle(B,A);C=Intersect(c,d,1);Polygon(A,B,C)"',
+  args: [
+    { name: 'command', positional: true, required: true, help: 'GeoGebra command string (use ; to chain multiple commands)' },
+  ],
+  columns: ['command', 'result'],
+  func: async (page, kwargs) => {
+    const commands = String(kwargs.command).split(';').map(s => s.trim()).filter(Boolean);
+    if (commands.length === 0) {
+      throw new ArgumentError('command must contain at least one GeoGebra command');
+    }
+    await ensureApplet(page);
+    const results = [];
+    for (const command of commands) {
+      const result = requireGgbSuccess(await ggbEval(page, command), `Failed to execute GeoGebra command: ${command}`);
+      results.push({
+        command,
+        result: `ok (${result.label || 'no label'})`,
+      });
+    }
+    return results;
+  },
+});

package/clis/geogebra/geogebra.test.js

@@ -0,0 +1,175 @@
+import { describe, expect, it, vi } from 'vitest';
+import { ArgumentError, CommandExecutionError, EmptyResultError } from '@jackwener/opencli/errors';
+import { getRegistry } from '@jackwener/opencli/registry';
+import { ensureApplet, ggbEval, ggbGetProperty, ggbListObjects, ggbWaitForObjectCount } from './utils.js';
+import './add-circle.js';
+import './add-line.js';
+import './add-point.js';
+import './add-polygon.js';
+import './eval.js';
+import './hexagon.js';
+import './info.js';
+import './list.js';
+import './triangle.js';
+
+function createPageMock(url = 'https://www.geogebra.org/geometry') {
+  return {
+    goto: vi.fn().mockResolvedValue(undefined),
+    evaluate: vi.fn(),
+    getCurrentUrl: vi.fn().mockResolvedValue(url),
+    wait: vi.fn().mockResolvedValue(undefined),
+    screenshot: vi.fn().mockResolvedValue(undefined),
+  };
+}
+
+describe('ensureApplet', () => {
+  it('skips navigation when already on the geometry page', async () => {
+    const page = createPageMock('https://www.geogebra.org/geometry');
+    page.evaluate.mockResolvedValue(true);
+    await ensureApplet(page);
+    expect(page.goto).not.toHaveBeenCalled();
+  });
+
+  it('unwraps Browser Bridge evaluate envelopes while checking applet readiness', async () => {
+    const page = createPageMock('https://www.geogebra.org/geometry');
+    page.evaluate.mockResolvedValue({ session: 1, data: true });
+    await ensureApplet(page);
+    expect(page.goto).not.toHaveBeenCalled();
+  });
+
+  it('navigates when not on the geometry page', async () => {
+    const page = createPageMock('https://example.com');
+    page.evaluate.mockResolvedValue(true);
+    await ensureApplet(page);
+    expect(page.goto).toHaveBeenCalledWith('https://www.geogebra.org/geometry');
+  });
+
+  it('throws when ggbApplet never becomes available', async () => {
+    const page = createPageMock();
+    page.evaluate.mockResolvedValue(false);
+    await expect(ensureApplet(page)).rejects.toThrow(CommandExecutionError);
+  });
+});
+
+describe('ggbEval', () => {
+  it('calls evalCommandGetLabels and evalCommand', async () => {
+    const page = createPageMock();
+    page.evaluate.mockResolvedValue({ ok: true, label: 'A', beforeCount: 0, afterCount: 1, error: null });
+    const result = await ggbEval(page, 'A=(1,2)');
+    expect(result).toEqual({ ok: true, label: 'A', beforeCount: 0, afterCount: 1, error: null });
+    expect(page.evaluate).toHaveBeenCalledTimes(1);
+  });
+
+  it('throws typed errors for malformed evaluate results', async () => {
+    const page = createPageMock();
+    page.evaluate.mockResolvedValue({ nope: true });
+    await expect(ggbEval(page, 'A=(1,2)')).rejects.toThrow(CommandExecutionError);
+  });
+});
+
+describe('ggbGetProperty', () => {
+  it('requests a property from the applet', async () => {
+    const page = createPageMock();
+    page.evaluate.mockResolvedValue('point');
+    const result = await ggbGetProperty(page, 'A', 'type');
+    expect(result).toBe('point');
+  });
+});
+
+describe('ggbListObjects', () => {
+  it('normalizes object rows from the applet', async () => {
+    const page = createPageMock();
+    page.evaluate.mockResolvedValue([
+      { name: 'A', type: 'point', value: '(0, 0)', visible: true },
+      { name: 't1', type: 'polygon', value: '', visible: true },
+    ]);
+    const result = await ggbListObjects(page);
+    expect(result).toHaveLength(2);
+    expect(page.evaluate).toHaveBeenCalledTimes(1);
+  });
+
+  it('unwraps Browser Bridge envelopes for object rows', async () => {
+    const page = createPageMock();
+    page.evaluate.mockResolvedValue({ session: 1, data: [{ name: 'A', type: 'point', value: '(0, 0)', visible: true }] });
+    const result = await ggbListObjects(page);
+    expect(result).toEqual([{ name: 'A', type: 'point', value: '(0, 0)', visible: true }]);
+  });
+
+  it('throws typed error when object names exist but property extraction fails', async () => {
+    const page = createPageMock();
+    page.evaluate.mockResolvedValue({ error: 'getObjectType failed', name: 'A' });
+    await expect(ggbListObjects(page)).rejects.toThrow(CommandExecutionError);
+  });
+});
+
+describe('ggbWaitForObjectCount', () => {
+  it('returns the detected object count', async () => {
+    const page = createPageMock();
+    page.evaluate.mockResolvedValue(4);
+    const result = await ggbWaitForObjectCount(page, 4);
+    expect(result).toBe(4);
+  });
+});
+
+describe('geogebra command typed boundaries', () => {
+  it('validates add-point args before navigating', async () => {
+    const command = getRegistry().get('geogebra/add-point');
+    const page = createPageMock('https://example.com');
+    await expect(command.func(page, { name: 'A', coords: 'bad' })).rejects.toThrow(ArgumentError);
+    expect(page.goto).not.toHaveBeenCalled();
+  });
+
+  it('validates triangle size before navigating instead of silently defaulting', async () => {
+    const command = getRegistry().get('geogebra/triangle');
+    const page = createPageMock('https://example.com');
+    await expect(command.func(page, { size: 'not-a-number' })).rejects.toThrow(ArgumentError);
+    expect(page.goto).not.toHaveBeenCalled();
+  });
+
+  it('fails eval command execution instead of returning a success row for failed commands', async () => {
+    const command = getRegistry().get('geogebra/eval');
+    const page = createPageMock('https://www.geogebra.org/geometry');
+    page.evaluate
+      .mockResolvedValueOnce(true)
+      .mockResolvedValueOnce({ ok: false, label: '', beforeCount: 0, afterCount: 0, error: 'Unknown command' });
+    await expect(command.func(page, { command: 'NotACommand(' })).rejects.toThrow(CommandExecutionError);
+  });
+
+  it('creates add-line rows from validated labels', async () => {
+    const command = getRegistry().get('geogebra/add-line');
+    const page = createPageMock('https://www.geogebra.org/geometry');
+    page.evaluate
+      .mockResolvedValueOnce(true)
+      .mockResolvedValueOnce({ ok: true, label: 'f', beforeCount: 2, afterCount: 3, error: null });
+    await expect(command.func(page, { points: 'A,B', type: 'segment' })).resolves.toEqual([
+      { label: 'f', type: 'segment', points: 'A,B' },
+    ]);
+  });
+
+  it('does not turn object property extraction failures into empty list results', async () => {
+    const command = getRegistry().get('geogebra/list');
+    const page = createPageMock('https://www.geogebra.org/geometry');
+    page.evaluate
+      .mockResolvedValueOnce(true)
+      .mockResolvedValueOnce({ error: 'getObjectType failed', name: 'A' });
+    await expect(command.func(page, {})).rejects.toThrow(CommandExecutionError);
+  });
+
+  it('does not turn malformed info existence probes into not-found results', async () => {
+    const command = getRegistry().get('geogebra/info');
+    const page = createPageMock('https://www.geogebra.org/geometry');
+    page.evaluate
+      .mockResolvedValueOnce(true)
+      .mockResolvedValueOnce({ nope: true });
+    await expect(command.func(page, { name: 'A' })).rejects.toThrow(CommandExecutionError);
+  });
+
+  it('maps explicit false info existence probes to EmptyResultError', async () => {
+    const command = getRegistry().get('geogebra/info');
+    const page = createPageMock('https://www.geogebra.org/geometry');
+    page.evaluate
+      .mockResolvedValueOnce(true)
+      .mockResolvedValueOnce({ ok: true, exists: false });
+    await expect(command.func(page, { name: 'A' })).rejects.toThrow(EmptyResultError);
+  });
+});

package/clis/geogebra/hexagon.js

@@ -0,0 +1,62 @@
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import { CommandExecutionError } from '@jackwener/opencli/errors';
+import os from 'node:os';
+import path from 'node:path';
+import { ensureApplet, ggbEval, ggbListObjects, ggbWaitForObjectCount, normalizeNumber, requireGgbSuccess } from './utils.js';
+
+/**
+ * Draw a regular hexagon on the GeoGebra Geometry canvas.
+ * Creates center point, vertex, and the regular polygon in one session.
+ */
+cli({
+  site: 'geogebra',
+  name: 'hexagon',
+  access: 'write',
+  description: 'Draw a regular hexagon centered at the origin',
+  domain: 'www.geogebra.org',
+  strategy: Strategy.PUBLIC,
+  browser: true,
+  navigateBefore: false,
+  example: 'opencli geogebra hexagon --size 3',
+  args: [
+    { name: 'size', required: false, default: '2', help: 'Radius of the hexagon (default: 2)' },
+  ],
+  columns: ['step', 'result'],
+  func: async (page, kwargs) => {
+    const size = normalizeNumber(kwargs.size, 'size', { defaultValue: 2, positive: true });
+    await ensureApplet(page);
+    const results = [];
+
+    const vertices = [
+      ['V1', `(${size},0)`],
+      ['V2', `(${size}*cos(pi/3),${size}*sin(pi/3))`],
+      ['V3', `(${size}*cos(2*pi/3),${size}*sin(2*pi/3))`],
+      ['V4', `(-${size},0)`],
+      ['V5', `(${size}*cos(4*pi/3),${size}*sin(4*pi/3))`],
+      ['V6', `(${size}*cos(5*pi/3),${size}*sin(5*pi/3))`],
+    ];
+    for (const [name, coords] of vertices) {
+      const result = requireGgbSuccess(await ggbEval(page, `${name}=${coords}`), `Failed to create point ${name}`);
+      results.push({ step: `${name}=${coords}`, result: `ok (${result.label || name})` });
+    }
+
+    const polygon = requireGgbSuccess(await ggbEval(page, 'Hexagon=Polygon(V1,V2,V3,V4,V5,V6)'), 'Failed to create hexagon polygon');
+    results.push({ step: 'Hexagon=Polygon(V1,V2,V3,V4,V5,V6)', result: `ok (${polygon.label || 'hexagon created'})` });
+
+    const objectCount = await ggbWaitForObjectCount(page, 7);
+    const objects = await ggbListObjects(page);
+    const screenshotPath = path.join(os.tmpdir(), 'opencli-geogebra-hexagon.png');
+    try {
+      await page.screenshot({ path: screenshotPath });
+    } catch (err) {
+      throw new CommandExecutionError(`Failed to capture GeoGebra screenshot: ${err?.message || err}`);
+    }
+
+    if (Array.isArray(objects) && objects.length > 0) {
+      results.push({ step: `canvas has ${objectCount} objects`, result: objects.map(o => `${o.name}(${o.type})`).join(', ') });
+    }
+    results.push({ step: 'screenshot', result: screenshotPath });
+
+    return results;
+  },
+});

package/clis/geogebra/info.js

@@ -0,0 +1,72 @@
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import { CommandExecutionError, EmptyResultError } from '@jackwener/opencli/errors';
+import { ensureApplet, ggbGetProperty, normalizeLabel, unwrapBridgeEnvelope } from './utils.js';
+
+cli({
+  site: 'geogebra',
+  name: 'info',
+  access: 'read',
+  description: 'Get detailed properties of a GeoGebra object',
+  domain: 'www.geogebra.org',
+  strategy: Strategy.PUBLIC,
+  browser: true,
+  navigateBefore: false,
+  example: 'opencli geogebra info --name A',
+  args: [
+    { name: 'name', required: true, help: 'Object label (e.g. A, c1, poly1)' },
+  ],
+  columns: ['property', 'value'],
+  func: async (page, kwargs) => {
+    const objName = normalizeLabel(kwargs.name, 'name');
+    await ensureApplet(page);
+
+    let exists;
+    try {
+      exists = unwrapBridgeEnvelope(await page.evaluate(`
+        (name => {
+          try {
+            if (typeof ggbApplet === 'undefined' || typeof ggbApplet.getObjectType !== 'function') {
+              return { error: 'ggbApplet is not ready' };
+            }
+            return { ok: true, exists: ggbApplet.getObjectType(name) !== '' };
+          } catch (err) {
+            return { error: err?.message || String(err) };
+          }
+        })
+        (${JSON.stringify(objName)})
+      `));
+    } catch (err) {
+      throw new CommandExecutionError(`Failed to inspect GeoGebra object: ${err?.message || err}`);
+    }
+    if (!exists || typeof exists !== 'object' || Array.isArray(exists)) {
+      throw new CommandExecutionError('GeoGebra object existence probe returned malformed result');
+    }
+    if (exists.error) {
+      throw new CommandExecutionError(`Failed to inspect GeoGebra object: ${exists.error}`);
+    }
+    if (exists.ok !== true || typeof exists.exists !== 'boolean') {
+      throw new CommandExecutionError('GeoGebra object existence probe returned malformed result');
+    }
+    if (exists.exists === false) {
+      throw new EmptyResultError(`geogebra info ${objName}`, `Object "${objName}" not found on the canvas.`);
+    }
+
+    const properties = ['type', 'value', 'definition', 'command', 'caption', 'visible', 'color'];
+    const rows = [];
+    for (const prop of properties) {
+      const val = await ggbGetProperty(page, objName, prop);
+      rows.push({ property: prop, value: String(val ?? '') });
+    }
+
+    // For point-like objects, also include coordinates
+    const objType = await ggbGetProperty(page, objName, 'type');
+    if (objType === 'point') {
+      const x = await ggbGetProperty(page, objName, 'xcoord');
+      const y = await ggbGetProperty(page, objName, 'ycoord');
+      rows.push({ property: 'x', value: String(x ?? '') });
+      rows.push({ property: 'y', value: String(y ?? '') });
+    }
+
+    return rows;
+  },
+});

package/clis/geogebra/list.js

@@ -0,0 +1,35 @@
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import { ArgumentError, EmptyResultError } from '@jackwener/opencli/errors';
+import { ensureApplet, ggbListObjects } from './utils.js';
+
+cli({
+  site: 'geogebra',
+  name: 'list',
+  access: 'read',
+  description: 'List all geometric objects on the GeoGebra canvas',
+  domain: 'www.geogebra.org',
+  strategy: Strategy.PUBLIC,
+  browser: true,
+  navigateBefore: false,
+  args: [
+    { name: 'type', required: false, help: 'Filter by object type (e.g. "point", "line", "circle")' },
+  ],
+  columns: ['name', 'type', 'value', 'visible'],
+  func: async (page, kwargs) => {
+    const filterType = kwargs.type == null || kwargs.type === ''
+      ? ''
+      : String(kwargs.type).trim().toLowerCase();
+    if (filterType && !/^[a-z-]+$/.test(filterType)) {
+      throw new ArgumentError('type must be a GeoGebra object type like point, line, or circle');
+    }
+    await ensureApplet(page);
+    const objects = await ggbListObjects(page, filterType);
+    if (!Array.isArray(objects) || objects.length === 0) {
+      throw new EmptyResultError(
+        'geogebra list',
+        'No objects found on the canvas. Fresh runs start a blank session; use one "eval" call, or inspect an already-bound tab through the browser workspace commands.',
+      );
+    }
+    return objects;
+  },
+});

package/clis/geogebra/triangle.js

@@ -0,0 +1,60 @@
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import { CommandExecutionError } from '@jackwener/opencli/errors';
+import os from 'node:os';
+import path from 'node:path';
+import { ensureApplet, ggbEval, ggbListObjects, ggbWaitForObjectCount, normalizeNumber, requireGgbSuccess } from './utils.js';
+
+cli({
+  site: 'geogebra',
+  name: 'triangle',
+  access: 'write',
+  description: 'Draw an equilateral triangle from a horizontal base segment',
+  domain: 'www.geogebra.org',
+  strategy: Strategy.PUBLIC,
+  browser: true,
+  navigateBefore: false,
+  example: 'opencli geogebra triangle --size 4',
+  args: [
+    { name: 'size', required: false, default: '2', help: 'Side length of the triangle (default: 2)' },
+  ],
+  columns: ['step', 'result'],
+  func: async (page, kwargs) => {
+    const size = normalizeNumber(kwargs.size, 'size', { defaultValue: 2, positive: true });
+    await ensureApplet(page);
+    const results = [];
+
+    const r1 = requireGgbSuccess(await ggbEval(page, 'A=(0,0)'), 'Failed to create point A');
+    results.push({ step: 'base point A=(0,0)', result: `ok (${r1.label || 'A'})` });
+
+    const r2 = requireGgbSuccess(await ggbEval(page, `B=(${size},0)`), 'Failed to create point B');
+    results.push({ step: `base point B=(${size},0)`, result: `ok (${r2.label || 'B'})` });
+
+    const r3 = requireGgbSuccess(await ggbEval(page, 'c=Circle(A,B)'), 'Failed to create circle c');
+    results.push({ step: 'c=Circle(A,B)', result: `ok (${r3.label || 'c'})` });
+
+    const r4 = requireGgbSuccess(await ggbEval(page, 'd=Circle(B,A)'), 'Failed to create circle d');
+    results.push({ step: 'd=Circle(B,A)', result: `ok (${r4.label || 'd'})` });
+
+    const r5 = requireGgbSuccess(await ggbEval(page, 'C=Intersect(c,d,1)'), 'Failed to create point C');
+    results.push({ step: 'C=Intersect(c,d,1)', result: `ok (${r5.label || 'C'})` });
+
+    const r6 = requireGgbSuccess(await ggbEval(page, 'Polygon(A,B,C)'), 'Failed to create triangle polygon');
+    results.push({ step: 'Polygon(A,B,C)', result: `ok (${r6.label || 'triangle created'})` });
+
+    const objectCount = await ggbWaitForObjectCount(page, 5);
+    const objects = await ggbListObjects(page);
+    const screenshotPath = path.join(os.tmpdir(), 'opencli-geogebra-triangle.png');
+    try {
+      await page.screenshot({ path: screenshotPath });
+    } catch (err) {
+      throw new CommandExecutionError(`Failed to capture GeoGebra screenshot: ${err?.message || err}`);
+    }
+    results.push({
+      step: `canvas has ${objectCount} objects`,
+      result: objects.map((obj) => `${obj.name}(${obj.type})`).join(', '),
+    });
+    results.push({ step: 'screenshot', result: screenshotPath });
+
+    return results;
+  },
+});