gsd-remix 1.0.0

package/sdk/src/workstream-utils.ts

@@ -0,0 +1,33 @@
+/**
+ * Workstream utility functions for multi-workstream project support.
+ *
+ * When --ws <name> is provided, all .planning/ paths are routed to
+ * .planning/workstreams/<name>/ instead.
+ */
+
+import { posix } from 'node:path';
+
+/**
+ * Validate a workstream name.
+ * Allowed: alphanumeric, hyphens, underscores, dots.
+ * Disallowed: empty, spaces, slashes, special chars, path traversal.
+ */
+export function validateWorkstreamName(name: string): boolean {
+  if (!name || name.length === 0) return false;
+  // Only allow alphanumeric, hyphens, underscores, dots
+  // Must not be ".." or start with ".." (path traversal)
+  if (name === '..' || name.startsWith('../')) return false;
+  return /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/.test(name);
+}
+
+/**
+ * Return the relative planning directory path.
+ *
+ * - Without workstream: `.planning`
+ * - With workstream: `.planning/workstreams/<name>`
+ */
+export function relPlanningPath(workstream?: string): string {
+  if (!workstream) return '.planning';
+  // Use POSIX segments so the same logical path string is used on all platforms (Windows included).
+  return posix.join('.planning', 'workstreams', workstream);
+}

package/sdk/src/ws-flag.test.ts

@@ -0,0 +1,285 @@
+/**
+ * Tests for --ws (workstream) flag support.
+ *
+ * Validates:
+ * - CLI parsing of --ws flag
+ * - Workstream name validation
+ * - GSDOptions.workstream propagation
+ * - GSDTools workstream-aware invocation
+ * - Config path resolution with workstream
+ * - ContextEngine workstream-aware planning dir
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { mkdir, writeFile, rm } from 'node:fs/promises';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+
+// ─── Workstream name validation ─────────────────────────────────────────────
+
+import { validateWorkstreamName } from './workstream-utils.js';
+
+describe('validateWorkstreamName', () => {
+  it('accepts alphanumeric names', () => {
+    expect(validateWorkstreamName('frontend')).toBe(true);
+    expect(validateWorkstreamName('backend2')).toBe(true);
+  });
+
+  it('accepts names with hyphens', () => {
+    expect(validateWorkstreamName('my-feature')).toBe(true);
+  });
+
+  it('accepts names with underscores', () => {
+    expect(validateWorkstreamName('my_feature')).toBe(true);
+  });
+
+  it('accepts names with dots', () => {
+    expect(validateWorkstreamName('v1.0')).toBe(true);
+  });
+
+  it('rejects empty strings', () => {
+    expect(validateWorkstreamName('')).toBe(false);
+  });
+
+  it('rejects names with spaces', () => {
+    expect(validateWorkstreamName('my feature')).toBe(false);
+  });
+
+  it('rejects names with slashes', () => {
+    expect(validateWorkstreamName('my/feature')).toBe(false);
+  });
+
+  it('rejects names with special characters', () => {
+    expect(validateWorkstreamName('feat@ure')).toBe(false);
+    expect(validateWorkstreamName('feat!ure')).toBe(false);
+    expect(validateWorkstreamName('feat#ure')).toBe(false);
+  });
+
+  it('rejects path traversal attempts', () => {
+    expect(validateWorkstreamName('..')).toBe(false);
+    expect(validateWorkstreamName('../etc')).toBe(false);
+  });
+});
+
+// ─── relPlanningPath helper ─────────────────────────────────────────────────
+
+import { relPlanningPath } from './workstream-utils.js';
+
+describe('relPlanningPath', () => {
+  it('returns .planning/ in flat mode (no workstream)', () => {
+    expect(relPlanningPath()).toBe('.planning');
+    expect(relPlanningPath(undefined)).toBe('.planning');
+  });
+
+  it('returns .planning/workstreams/<name>/ with workstream', () => {
+    expect(relPlanningPath('frontend')).toBe('.planning/workstreams/frontend');
+    expect(relPlanningPath('api-v2')).toBe('.planning/workstreams/api-v2');
+  });
+});
+
+// ─── CLI --ws flag parsing ──────────────────────────────────────────────────
+
+import { parseCliArgs } from './cli.js';
+
+describe('parseCliArgs --ws flag', () => {
+  it('parses --ws flag', () => {
+    const result = parseCliArgs(['run', 'build auth', '--ws', 'frontend']);
+
+    expect(result.ws).toBe('frontend');
+  });
+
+  it('ws is undefined when not provided', () => {
+    const result = parseCliArgs(['run', 'build auth']);
+
+    expect(result.ws).toBeUndefined();
+  });
+
+  it('works with other flags', () => {
+    const result = parseCliArgs([
+      'run', 'build auth',
+      '--ws', 'backend',
+      '--model', 'claude-sonnet-4-6',
+      '--project-dir', '/tmp/test',
+    ]);
+
+    expect(result.ws).toBe('backend');
+    expect(result.model).toBe('claude-sonnet-4-6');
+    expect(result.projectDir).toBe('/tmp/test');
+  });
+});
+
+// ─── GSDOptions.workstream ──────────────────────────────────────────────────
+
+describe('GSDOptions.workstream', () => {
+  it('GSD class accepts workstream option', async () => {
+    // This is a compile-time check -- if the type is wrong, TS will fail
+    const { GSD } = await import('./index.js');
+    const gsd = new GSD({
+      projectDir: '/tmp/test-ws',
+      workstream: 'frontend',
+    });
+    // If we get here without a type error, the option is accepted
+    expect(gsd).toBeDefined();
+  });
+});
+
+// ─── GSDTools workstream injection ──────────────────────────────────────────
+
+describe('GSDTools workstream injection', () => {
+  let tmpDir: string;
+  let fixtureDir: string;
+
+  beforeEach(async () => {
+    tmpDir = join(tmpdir(), `gsd-ws-test-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+    fixtureDir = join(tmpDir, 'fixtures');
+    await mkdir(fixtureDir, { recursive: true });
+    await mkdir(join(tmpDir, '.planning'), { recursive: true });
+  });
+
+  afterEach(async () => {
+    await rm(tmpDir, { recursive: true, force: true });
+  });
+
+  async function createScript(name: string, code: string): Promise<string> {
+    const scriptPath = join(fixtureDir, name);
+    await writeFile(scriptPath, code, { mode: 0o755 });
+    return scriptPath;
+  }
+
+  it('passes --ws flag to gsd-tools.cjs when workstream is set', async () => {
+    const { GSDTools } = await import('./gsd-tools.js');
+
+    // Script echoes its arguments as JSON
+    const scriptPath = await createScript(
+      'echo-args.cjs',
+      'process.stdout.write(JSON.stringify(process.argv.slice(2)));',
+    );
+
+    const tools = new GSDTools({
+      projectDir: tmpDir,
+      gsdToolsPath: scriptPath,
+      workstream: 'frontend',
+    });
+
+    const result = await tools.exec('state', ['load']) as string[];
+
+    // Should contain --ws frontend in the arguments
+    expect(result).toContain('--ws');
+    expect(result).toContain('frontend');
+  });
+
+  it('does not pass --ws when workstream is undefined', async () => {
+    const { GSDTools } = await import('./gsd-tools.js');
+
+    const scriptPath = await createScript(
+      'echo-args-no-ws.cjs',
+      'process.stdout.write(JSON.stringify(process.argv.slice(2)));',
+    );
+
+    const tools = new GSDTools({
+      projectDir: tmpDir,
+      gsdToolsPath: scriptPath,
+    });
+
+    const result = await tools.exec('state', ['load']) as string[];
+
+    expect(result).not.toContain('--ws');
+  });
+});
+
+// ─── Config workstream-aware path ───────────────────────────────────────────
+
+import { loadConfig } from './config.js';
+
+describe('loadConfig with workstream', () => {
+  let tmpDir: string;
+
+  beforeEach(async () => {
+    tmpDir = join(tmpdir(), `gsd-config-ws-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+    await mkdir(tmpDir, { recursive: true });
+  });
+
+  afterEach(async () => {
+    await rm(tmpDir, { recursive: true, force: true });
+  });
+
+  it('loads config from workstream path when workstream is provided', async () => {
+    const wsDir = join(tmpDir, '.planning', 'workstreams', 'frontend');
+    await mkdir(wsDir, { recursive: true });
+    await writeFile(
+      join(wsDir, 'config.json'),
+      JSON.stringify({ model_profile: 'performance' }),
+    );
+
+    const config = await loadConfig(tmpDir, 'frontend');
+
+    expect(config.model_profile).toBe('performance');
+  });
+
+  it('falls back to root config when workstream config is missing', async () => {
+    // Create root config but no workstream config
+    await mkdir(join(tmpDir, '.planning'), { recursive: true });
+    await writeFile(
+      join(tmpDir, '.planning', 'config.json'),
+      JSON.stringify({ model_profile: 'balanced' }),
+    );
+
+    const config = await loadConfig(tmpDir, 'frontend');
+
+    expect(config.model_profile).toBe('balanced');
+  });
+
+  it('loads from root .planning/ when workstream is undefined', async () => {
+    await mkdir(join(tmpDir, '.planning'), { recursive: true });
+    await writeFile(
+      join(tmpDir, '.planning', 'config.json'),
+      JSON.stringify({ model_profile: 'economy' }),
+    );
+
+    const config = await loadConfig(tmpDir);
+
+    expect(config.model_profile).toBe('economy');
+  });
+});
+
+// ─── ContextEngine workstream-aware planning dir ────────────────────────────
+
+describe('ContextEngine with workstream', () => {
+  let tmpDir: string;
+
+  beforeEach(async () => {
+    tmpDir = join(tmpdir(), `gsd-ctx-ws-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+    await mkdir(tmpDir, { recursive: true });
+  });
+
+  afterEach(async () => {
+    await rm(tmpDir, { recursive: true, force: true });
+  });
+
+  it('resolves files from workstream planning dir', async () => {
+    const { ContextEngine } = await import('./context-engine.js');
+    const { PhaseType } = await import('./types.js');
+
+    const wsDir = join(tmpDir, '.planning', 'workstreams', 'backend');
+    await mkdir(wsDir, { recursive: true });
+    await writeFile(join(wsDir, 'STATE.md'), '# State\nPhase: 01');
+
+    const engine = new ContextEngine(tmpDir, undefined, undefined, 'backend');
+    const files = await engine.resolveContextFiles(PhaseType.Execute);
+
+    expect(files.state).toContain('Phase: 01');
+  });
+
+  it('resolves files from root .planning/ without workstream', async () => {
+    const { ContextEngine } = await import('./context-engine.js');
+    const { PhaseType } = await import('./types.js');
+
+    await mkdir(join(tmpDir, '.planning'), { recursive: true });
+    await writeFile(join(tmpDir, '.planning', 'STATE.md'), '# State\nPhase: 02');
+
+    const engine = new ContextEngine(tmpDir);
+    const files = await engine.resolveContextFiles(PhaseType.Execute);
+
+    expect(files.state).toContain('Phase: 02');
+  });
+});

package/sdk/src/ws-transport.test.ts

@@ -0,0 +1,161 @@
+import { describe, it, expect, afterEach } from 'vitest';
+import { WebSocket } from 'ws';
+import { WSTransport } from './ws-transport.js';
+import { GSDEventType, type GSDEvent, type GSDEventBase } from './types.js';
+
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+
+function makeBase(overrides: Partial<GSDEventBase> = {}): Omit<GSDEventBase, 'type'> {
+  return {
+    timestamp: '2025-06-15T14:30:45.123Z',
+    sessionId: 'test-session',
+    ...overrides,
+  };
+}
+
+/** Connect a WS client and resolve once open. */
+function connectClient(port: number): Promise<WebSocket> {
+  return new Promise((resolve, reject) => {
+    const ws = new WebSocket(`ws://127.0.0.1:${port}`);
+    ws.on('open', () => resolve(ws));
+    ws.on('error', reject);
+  });
+}
+
+/** Wait for the next message on a WS client. */
+function waitForMessage(ws: WebSocket): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const timeout = setTimeout(() => reject(new Error('message timeout')), 5000);
+    ws.once('message', (data) => {
+      clearTimeout(timeout);
+      resolve(data.toString());
+    });
+  });
+}
+
+// Track transports for cleanup
+const activeTransports: WSTransport[] = [];
+
+afterEach(() => {
+  for (const t of activeTransports) {
+    try { t.close(); } catch { /* ignore */ }
+  }
+  activeTransports.length = 0;
+});
+
+// ─── Tests ───────────────────────────────────────────────────────────────────
+
+describe('WSTransport', () => {
+  it('start() creates a server on the specified port', async () => {
+    const transport = new WSTransport({ port: 0 }); // dynamic port
+    activeTransports.push(transport);
+
+    await transport.start();
+
+    // Server is listening — we can connect a client
+    const address = (transport as any).server?.address();
+    expect(address).toBeTruthy();
+    expect(typeof address.port).toBe('number');
+    expect(address.port).toBeGreaterThan(0);
+  });
+
+  it('onEvent broadcasts JSON to connected client', async () => {
+    const transport = new WSTransport({ port: 0 });
+    activeTransports.push(transport);
+    await transport.start();
+
+    const address = (transport as any).server?.address();
+    const client = await connectClient(address.port);
+
+    const event: GSDEvent = {
+      ...makeBase(),
+      type: GSDEventType.SessionInit,
+      model: 'claude-sonnet-4-20250514',
+      tools: ['Read', 'Write'],
+      cwd: '/tmp/test',
+    } as GSDEvent;
+
+    const msgPromise = waitForMessage(client);
+    transport.onEvent(event);
+
+    const received = await msgPromise;
+    const parsed = JSON.parse(received);
+
+    expect(parsed.type).toBe('session_init');
+    expect(parsed.model).toBe('claude-sonnet-4-20250514');
+    expect(parsed.tools).toEqual(['Read', 'Write']);
+
+    client.close();
+  });
+
+  it('onEvent handles no connected clients without error', async () => {
+    const transport = new WSTransport({ port: 0 });
+    activeTransports.push(transport);
+    await transport.start();
+
+    // No clients connected — should not throw
+    expect(() => {
+      transport.onEvent({
+        ...makeBase(),
+        type: GSDEventType.MilestoneStart,
+        phaseCount: 2,
+        prompt: 'test',
+      } as GSDEvent);
+    }).not.toThrow();
+  });
+
+  it('close() shuts down the server', async () => {
+    const transport = new WSTransport({ port: 0 });
+    // Don't push to activeTransports — we close manually
+
+    await transport.start();
+    const address = (transport as any).server?.address();
+    expect(address).toBeTruthy();
+
+    transport.close();
+
+    // Server should be null after close
+    expect((transport as any).server).toBeNull();
+
+    // Connecting should fail
+    await expect(connectClient(address.port)).rejects.toThrow();
+  });
+
+  it('close() before start() does not throw', () => {
+    const transport = new WSTransport({ port: 0 });
+    expect(() => transport.close()).not.toThrow();
+  });
+
+  it('broadcasts to multiple connected clients', async () => {
+    const transport = new WSTransport({ port: 0 });
+    activeTransports.push(transport);
+    await transport.start();
+
+    const address = (transport as any).server?.address();
+    const client1 = await connectClient(address.port);
+    const client2 = await connectClient(address.port);
+
+    const event: GSDEvent = {
+      ...makeBase(),
+      type: GSDEventType.MilestoneComplete,
+      success: true,
+      totalCostUsd: 5.0,
+      totalDurationMs: 120000,
+      phasesCompleted: 3,
+    } as GSDEvent;
+
+    const msg1Promise = waitForMessage(client1);
+    const msg2Promise = waitForMessage(client2);
+
+    transport.onEvent(event);
+
+    const [msg1, msg2] = await Promise.all([msg1Promise, msg2Promise]);
+
+    expect(JSON.parse(msg1).type).toBe('milestone_complete');
+    expect(JSON.parse(msg2).type).toBe('milestone_complete');
+    expect(JSON.parse(msg1).success).toBe(true);
+
+    client1.close();
+    client2.close();
+  });
+});

package/sdk/src/ws-transport.ts

@@ -0,0 +1,93 @@
+/**
+ * WebSocket Transport — broadcasts GSD events as JSON over WebSocket.
+ *
+ * Implements TransportHandler. Starts a WebSocketServer on a given port
+ * and JSON-serializes each event to all connected clients.
+ */
+
+import { WebSocketServer, WebSocket } from 'ws';
+import type { GSDEvent, TransportHandler } from './types.js';
+
+export interface WSTransportOptions {
+  port: number;
+}
+
+export class WSTransport implements TransportHandler {
+  private readonly port: number;
+  private server: WebSocketServer | null = null;
+  private closing = false;
+
+  constructor(options: WSTransportOptions) {
+    this.port = options.port;
+  }
+
+  /**
+   * Start the WebSocket server on the configured port.
+   * Resolves once the server is listening.
+   */
+  async start(): Promise<void> {
+    if (this.closing) return;
+
+    return new Promise<void>((resolve, reject) => {
+      try {
+        this.server = new WebSocketServer({ port: this.port });
+        this.server.on('listening', () => resolve());
+        this.server.on('error', (err) => reject(err));
+      } catch (err) {
+        reject(err);
+      }
+    });
+  }
+
+  /**
+   * Broadcast a GSD event as JSON to all connected clients.
+   * Never throws — wraps each client.send in try/catch.
+   */
+  onEvent(event: GSDEvent): void {
+    try {
+      if (!this.server) return;
+
+      const payload = JSON.stringify(event);
+
+      for (const client of this.server.clients) {
+        if (client.readyState === WebSocket.OPEN) {
+          try {
+            client.send(payload);
+          } catch {
+            // Ignore individual client send errors
+          }
+        }
+      }
+    } catch {
+      // TransportHandler contract: onEvent must never throw
+    }
+  }
+
+  /**
+   * Close all client connections and shut down the server.
+   * Safe to call before start() — sets a closing flag.
+   */
+  close(): void {
+    this.closing = true;
+
+    if (!this.server) return;
+
+    // Terminate all clients
+    for (const client of this.server.clients) {
+      try {
+        client.terminate();
+      } catch {
+        // Ignore client close errors
+      }
+    }
+
+    // Close the server
+    try {
+      this.server.close();
+    } catch {
+      // Ignore server close errors
+    }
+
+    this.server = null;
+  }
+}

package/sdk/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "outDir": "dist",
+    "rootDir": "src",
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true
+  },
+  "include": ["src/**/*.ts"],
+  "exclude": ["src/**/*.test.ts", "src/**/*.integration.test.ts", "dist", "node_modules"]
+}