@bhargavvc/sdd-cc 1.35.0 → 1.42.4

package/sdk/src/query-failure-classification.ts

@@ -0,0 +1,42 @@
+import { SDDToolsError } from './sdd-tools-error.js';
+
+export interface QueryFailureSignal {
+  kind: 'timeout' | 'failure';
+  message: string;
+  timeoutMs?: number;
+}
+
+export function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+function parseTimeoutMs(message: string): number | undefined {
+  const m = message.match(/timed out after\s+(\d+)ms/i);
+  if (!m) return undefined;
+  const n = Number.parseInt(m[1], 10);
+  return Number.isFinite(n) ? n : undefined;
+}
+
+function isTimeoutMessage(message: string): boolean {
+  return /timed out after/i.test(message);
+}
+
+export function timeoutMessage(command: string, args: string[], timeoutMs: number): string {
+  return `sdd-tools timed out after ${timeoutMs}ms: ${command} ${args.join(' ')}`;
+}
+
+export function toFailureSignal(error: unknown): QueryFailureSignal {
+  if (error instanceof SDDToolsError && error.classification) {
+    return {
+      kind: error.classification.kind,
+      message: error.message,
+      timeoutMs: error.classification.timeoutMs,
+    };
+  }
+
+  const message = errorMessage(error);
+  if (isTimeoutMessage(message)) {
+    return { kind: 'timeout', message, timeoutMs: parseTimeoutMs(message) };
+  }
+  return { kind: 'failure', message };
+}

package/sdk/src/query-hotpath-methods.ts

@@ -0,0 +1,48 @@
+import type { InitNewProjectInfo, PhaseOpInfo, PhasePlanIndex } from './types.js';
+
+export interface QueryHotpathMethodsDeps {
+  dispatchNativeHotpath: (
+    legacyCommand: string,
+    legacyArgs: string[],
+    registryCommand: string,
+    registryArgs: string[],
+    mode: 'json' | 'raw',
+  ) => Promise<unknown>;
+}
+
+/**
+ * Module owning typed hot-path method projection for SDDTools facade.
+ */
+export class QueryHotpathMethods {
+  constructor(private readonly deps: QueryHotpathMethodsDeps) {}
+
+  phaseComplete(phase: string): Promise<string> {
+    return this.deps.dispatchNativeHotpath('phase', ['complete', phase], 'phase.complete', [phase], 'raw') as Promise<string>;
+  }
+
+  commit(message: string, files?: string[]): Promise<string> {
+    const args = [message];
+    if (files?.length) args.push('--files', ...files);
+    return this.deps.dispatchNativeHotpath('commit', args, 'commit', args, 'raw') as Promise<string>;
+  }
+
+  initPhaseOp(phaseNumber: string): Promise<PhaseOpInfo> {
+    return this.deps.dispatchNativeHotpath('init', ['phase-op', phaseNumber], 'init.phase-op', [phaseNumber], 'json') as Promise<PhaseOpInfo>;
+  }
+
+  configGet(key: string): Promise<string | null> {
+    return this.deps.dispatchNativeHotpath('config-get', [key], 'config-get', [key], 'json') as Promise<string | null>;
+  }
+
+  phasePlanIndex(phaseNumber: string): Promise<PhasePlanIndex> {
+    return this.deps.dispatchNativeHotpath('phase-plan-index', [phaseNumber], 'phase-plan-index', [phaseNumber], 'json') as Promise<PhasePlanIndex>;
+  }
+
+  initNewProject(): Promise<InitNewProjectInfo> {
+    return this.deps.dispatchNativeHotpath('init', ['new-project'], 'init.new-project', [], 'json') as Promise<InitNewProjectInfo>;
+  }
+
+  configSet(key: string, value: string): Promise<string> {
+    return this.deps.dispatchNativeHotpath('config-set', [key, value], 'config-set', [key, value], 'raw') as Promise<string>;
+  }
+}

package/sdk/src/query-native-direct-adapter.test.ts

@@ -0,0 +1,35 @@
+import { describe, expect, it } from 'vitest';
+import { SDDToolsError } from './sdd-tools-error.js';
+import { QueryNativeDirectAdapter } from './query-native-direct-adapter.js';
+
+describe('QueryNativeDirectAdapter', () => {
+  it('wraps native failures as typed failure errors', async () => {
+    const adapter = new QueryNativeDirectAdapter({
+      timeoutMs: 1000,
+      dispatch: async () => {
+        throw new Error('boom');
+      },
+      createNativeTimeoutError: (message, command, args) => SDDToolsError.timeout(message, command, args),
+      createNativeFailureError: (message, command, args, cause) => SDDToolsError.failure(message, command, args, 1, '', { cause }),
+    });
+
+    await expect(adapter.dispatchJson('state', ['load'], 'state.load', [])).rejects.toMatchObject({
+      classification: SDDToolsError.failure('x', 'state', ['load'], 1).classification,
+      command: 'state',
+    });
+  });
+
+  it('preserves timeout errors', async () => {
+    const timeoutErr = SDDToolsError.timeout('timeout', 'state', ['load']);
+    const adapter = new QueryNativeDirectAdapter({
+      timeoutMs: 1000,
+      dispatch: async () => {
+        throw timeoutErr;
+      },
+      createNativeTimeoutError: (message, command, args) => SDDToolsError.timeout(message, command, args),
+      createNativeFailureError: (message, command, args, cause) => SDDToolsError.failure(message, command, args, 1, '', { cause }),
+    });
+
+    await expect(adapter.dispatchJson('state', ['load'], 'state.load', [])).rejects.toBe(timeoutErr);
+  });
+});

package/sdk/src/query-native-direct-adapter.ts

@@ -0,0 +1,70 @@
+import { formatQueryRawOutput } from './query-raw-output-projection.js';
+import { SDDToolsError } from './sdd-tools-error.js';
+import { errorMessage, timeoutMessage } from './query-failure-classification.js';
+import type { QueryNativeErrorFactory } from './query-tools-error-factory.js';
+import type { QueryResult } from './query/utils.js';
+
+export interface QueryNativeDirectAdapterDeps extends QueryNativeErrorFactory {
+  timeoutMs: number;
+  dispatch: (registryCommand: string, registryArgs: string[]) => Promise<QueryResult>;
+}
+
+/**
+ * Adapter Module for direct native registry dispatch with timeout policy.
+ */
+export class QueryNativeDirectAdapter {
+  constructor(private readonly deps: QueryNativeDirectAdapterDeps) {}
+
+  async dispatchResult(legacyCommand: string, legacyArgs: string[], registryCommand: string, registryArgs: string[]): Promise<QueryResult> {
+    try {
+      return await this.withTimeout(legacyCommand, legacyArgs, this.deps.dispatch(registryCommand, registryArgs));
+    } catch (error) {
+      throw this.toNativeDispatchError(legacyCommand, legacyArgs, error);
+    }
+  }
+
+  async dispatchJson(legacyCommand: string, legacyArgs: string[], registryCommand: string, registryArgs: string[]): Promise<unknown> {
+    return this.dispatchData(legacyCommand, legacyArgs, registryCommand, registryArgs);
+  }
+
+  async dispatchRaw(legacyCommand: string, legacyArgs: string[], registryCommand: string, registryArgs: string[]): Promise<string> {
+    const data = await this.dispatchData(legacyCommand, legacyArgs, registryCommand, registryArgs);
+    return formatQueryRawOutput(registryCommand, data).trim();
+  }
+
+  private async dispatchData(
+    legacyCommand: string,
+    legacyArgs: string[],
+    registryCommand: string,
+    registryArgs: string[],
+  ): Promise<unknown> {
+    const result = await this.dispatchResult(legacyCommand, legacyArgs, registryCommand, registryArgs);
+    return result.data;
+  }
+
+  private toNativeDispatchError(legacyCommand: string, legacyArgs: string[], error: unknown): SDDToolsError {
+    if (error instanceof SDDToolsError) return error;
+    return this.deps.createNativeFailureError(errorMessage(error), legacyCommand, legacyArgs, error);
+  }
+
+  private async withTimeout<T>(legacyCommand: string, legacyArgs: string[], work: Promise<T>): Promise<T> {
+    let timeoutId: ReturnType<typeof setTimeout> | undefined;
+    const timeoutPromise = new Promise<never>((_, reject) => {
+      timeoutId = setTimeout(() => {
+        reject(
+          this.deps.createNativeTimeoutError(
+            timeoutMessage(legacyCommand, legacyArgs, this.deps.timeoutMs),
+            legacyCommand,
+            legacyArgs,
+          ),
+        );
+      }, this.deps.timeoutMs);
+    });
+
+    try {
+      return await Promise.race([work, timeoutPromise]);
+    } finally {
+      if (timeoutId !== undefined) clearTimeout(timeoutId);
+    }
+  }
+}

package/sdk/src/query-native-hotpath-adapter.test.ts

@@ -0,0 +1,43 @@
+import { describe, it, expect, vi } from 'vitest';
+import { QueryNativeHotpathAdapter } from './query-native-hotpath-adapter.js';
+
+describe('QueryNativeHotpathAdapter', () => {
+  it('uses native Adapter when native query enabled', async () => {
+    const native = {
+      dispatchJson: vi.fn().mockResolvedValue({ ok: true }),
+      dispatchRaw: vi.fn().mockResolvedValue('ok'),
+    } as never;
+
+    const adapter = new QueryNativeHotpathAdapter(
+      () => true,
+      native,
+      vi.fn(),
+      vi.fn(),
+    );
+
+    await expect(adapter.dispatch('state', ['load'], 'state.load', [], 'json')).resolves.toEqual({ ok: true });
+    await expect(adapter.dispatch('commit', ['m'], 'commit', ['m'], 'raw')).resolves.toEqual('ok');
+    expect((native as { dispatchJson: ReturnType<typeof vi.fn> }).dispatchJson).toHaveBeenCalledWith('state', ['load'], 'state.load', []);
+    expect((native as { dispatchRaw: ReturnType<typeof vi.fn> }).dispatchRaw).toHaveBeenCalledWith('commit', ['m'], 'commit', ['m']);
+  });
+
+  it('uses fallback when native query disabled', async () => {
+    const execJsonFallback = vi.fn().mockResolvedValue({ from: 'fallback-json' });
+    const execRawFallback = vi.fn().mockResolvedValue('fallback-raw');
+
+    const adapter = new QueryNativeHotpathAdapter(
+      () => false,
+      {
+        dispatchJson: vi.fn(),
+        dispatchRaw: vi.fn(),
+      } as never,
+      execJsonFallback,
+      execRawFallback,
+    );
+
+    await expect(adapter.dispatch('state', ['load'], 'state.load', [], 'json')).resolves.toEqual({ from: 'fallback-json' });
+    await expect(adapter.dispatch('commit', ['m'], 'commit', ['m'], 'raw')).resolves.toEqual('fallback-raw');
+    expect(execJsonFallback).toHaveBeenCalledWith('state', ['load']);
+    expect(execRawFallback).toHaveBeenCalledWith('commit', ['m']);
+  });
+});

package/sdk/src/query-native-hotpath-adapter.ts

@@ -0,0 +1,45 @@
+import type { QueryNativeDirectAdapter } from './query-native-direct-adapter.js';
+
+/**
+ * Adapter Module for runner hot-path native commands.
+ */
+export class QueryNativeHotpathAdapter {
+  constructor(
+    private readonly shouldUseNativeQuery: () => boolean,
+    private readonly nativeDirect: QueryNativeDirectAdapter,
+    private readonly execJsonFallback: (legacyCommand: string, legacyArgs: string[]) => Promise<unknown>,
+    private readonly execRawFallback: (legacyCommand: string, legacyArgs: string[]) => Promise<string>,
+  ) {}
+
+  async dispatch(
+    legacyCommand: string,
+    legacyArgs: string[],
+    registryCommand: string,
+    registryArgs: string[],
+    mode: 'json' | 'raw',
+  ): Promise<unknown> {
+    if (!this.shouldUseNativeQuery()) {
+      return this.dispatchFallback(legacyCommand, legacyArgs, mode);
+    }
+
+    return this.dispatchNative(legacyCommand, legacyArgs, registryCommand, registryArgs, mode);
+  }
+
+  private dispatchFallback(legacyCommand: string, legacyArgs: string[], mode: 'json' | 'raw'): Promise<unknown> {
+    return mode === 'raw'
+      ? this.execRawFallback(legacyCommand, legacyArgs)
+      : this.execJsonFallback(legacyCommand, legacyArgs);
+  }
+
+  private dispatchNative(
+    legacyCommand: string,
+    legacyArgs: string[],
+    registryCommand: string,
+    registryArgs: string[],
+    mode: 'json' | 'raw',
+  ): Promise<unknown> {
+    return mode === 'raw'
+      ? this.nativeDirect.dispatchRaw(legacyCommand, legacyArgs, registryCommand, registryArgs)
+      : this.nativeDirect.dispatchJson(legacyCommand, legacyArgs, registryCommand, registryArgs);
+  }
+}

package/sdk/src/query-raw-output-projection.test.ts

@@ -0,0 +1,39 @@
+import { describe, it, expect } from 'vitest';
+import { formatQueryRawOutput } from './query-raw-output-projection.js';
+
+describe('formatQueryRawOutput', () => {
+  it('formats commit hash', () => {
+    expect(formatQueryRawOutput('commit', { committed: true, hash: 'abc123' })).toBe('abc123');
+  });
+
+  it('returns committed when hash missing', () => {
+    expect(formatQueryRawOutput('commit', { committed: true })).toBe('committed');
+  });
+
+  it('formats skipped commit reason', () => {
+    expect(formatQueryRawOutput('commit', { committed: false, reason: 'skipped' })).toBe('skipped');
+  });
+
+  it('formats nothing-to-commit reason', () => {
+    expect(formatQueryRawOutput('commit', { committed: false, reason: 'nothing_to_commit' })).toBe('nothing');
+  });
+
+  it('formats config-set key=value', () => {
+    expect(formatQueryRawOutput('config-set', { updated: true, key: 'mode', value: 'yolo' })).toBe('mode=yolo');
+  });
+
+  it('formats state.begin-phase boolean result', () => {
+    expect(formatQueryRawOutput('state.begin-phase', { updated: ['x'] })).toBe('true');
+    expect(formatQueryRawOutput('state.begin-phase', { updated: [] })).toBe('false');
+  });
+
+  it('formats state begin-phase alias', () => {
+    expect(formatQueryRawOutput('state begin-phase', { updated: ['x'] })).toBe('true');
+    expect(formatQueryRawOutput('state begin-phase', { updated: [] })).toBe('false');
+  });
+
+  it('never returns undefined for non-JSON top-level values', () => {
+    expect(formatQueryRawOutput('commit', undefined)).toBe('undefined');
+    expect(formatQueryRawOutput('commit', Symbol('x'))).toBe('Symbol(x)');
+  });
+});

package/sdk/src/query-raw-output-projection.ts

@@ -0,0 +1,74 @@
+import { formatStateLoadRawStdout } from './query/state-project-load.js';
+
+function safeStringify(value: unknown): string {
+  const out = JSON.stringify(value, null, 2);
+  return out ?? String(value);
+}
+
+/**
+ * Raw output projection for native query results.
+ * Owns CLI-facing string contracts for raw mode commands.
+ */
+export function formatQueryRawOutput(registryCommand: string, data: unknown): string {
+  if (registryCommand === 'state.load') {
+    return formatStateLoadRawStdout(data);
+  }
+
+  if (registryCommand === 'commit') {
+    if (data == null || typeof data !== 'object' || Array.isArray(data)) {
+      return safeStringify(data);
+    }
+    const d = data as Record<string, unknown>;
+    if (d.committed === true) {
+      return d.hash != null ? String(d.hash) : 'committed';
+    }
+    if (d.committed === false) {
+      const r = String(d.reason ?? '');
+      if (
+        r.includes('commit_docs') ||
+        r.includes('skipped') ||
+        r.includes('gitignored') ||
+        r === 'skipped_commit_docs_false'
+      ) {
+        return 'skipped';
+      }
+      if (r.includes('nothing') || r.includes('nothing_to_commit')) {
+        return 'nothing';
+      }
+      return r || 'nothing';
+    }
+    return safeStringify(data);
+  }
+
+  if (registryCommand === 'config-set') {
+    if (data == null || typeof data !== 'object' || Array.isArray(data)) {
+      return safeStringify(data);
+    }
+    const d = data as Record<string, unknown>;
+    if ((d.updated === true || d.set === true) && d.key !== undefined) {
+      const v = d.value;
+      if (v === null || v === undefined) {
+        return `${d.key}=`;
+      }
+      if (typeof v === 'object') {
+        return `${d.key}=${JSON.stringify(v)}`;
+      }
+      return `${d.key}=${String(v)}`;
+    }
+    return safeStringify(data);
+  }
+
+  if (registryCommand === 'state.begin-phase' || registryCommand === 'state begin-phase') {
+    if (data == null || typeof data !== 'object' || Array.isArray(data)) {
+      return safeStringify(data);
+    }
+    const d = data as Record<string, unknown>;
+    const u = d.updated as string[] | undefined;
+    return Array.isArray(u) && u.length > 0 ? 'true' : 'false';
+  }
+
+  if (typeof data === 'string') {
+    return data;
+  }
+  return safeStringify(data);
+}

package/sdk/src/query-runtime-bridge.test.ts

@@ -0,0 +1,150 @@
+import { describe, it, expect, vi } from 'vitest';
+import { QueryRuntimeBridge } from './query-runtime-bridge.js';
+import { SDDToolsError } from './sdd-tools-error.js';
+
+describe('QueryRuntimeBridge observability', () => {
+  it('emits query_dispatch success event with transport decision', async () => {
+    const onDispatchEvent = vi.fn();
+    const executionPolicy = {
+      execute: vi.fn(async (request: { onTransportDecision?: (d: unknown) => void }) => {
+        request.onTransportDecision?.({ dispatchMode: 'subprocess', reason: 'workstream_forced' });
+        return { ok: true };
+      }),
+    };
+
+    const bridge = new QueryRuntimeBridge(
+      { has: () => true } as never,
+      executionPolicy as never,
+      { dispatch: vi.fn() } as never,
+      () => true,
+      { onDispatchEvent },
+    );
+
+    await bridge.execute({
+      legacyCommand: 'state',
+      legacyArgs: ['load'],
+      registryCommand: 'state.load',
+      registryArgs: [],
+      mode: 'json',
+      projectDir: '/tmp',
+      workstream: 'ws-1',
+    });
+
+    expect(onDispatchEvent).toHaveBeenCalledWith(
+      expect.objectContaining({
+        type: 'query_dispatch',
+        command: 'state.load',
+        dispatchMode: 'subprocess',
+        reason: 'workstream_forced',
+        outcome: 'success',
+      }),
+    );
+  });
+
+  it('emits query_dispatch error event with errorKind', async () => {
+    const onDispatchEvent = vi.fn();
+    const executionPolicy = {
+      execute: vi.fn(async () => {
+        throw SDDToolsError.timeout('timeout', 'state', ['load'], '', 500);
+      }),
+    };
+
+    const bridge = new QueryRuntimeBridge(
+      { has: () => true } as never,
+      executionPolicy as never,
+      { dispatch: vi.fn() } as never,
+      () => true,
+      { onDispatchEvent },
+    );
+
+    await expect(
+      bridge.execute({
+        legacyCommand: 'state',
+        legacyArgs: ['load'],
+        registryCommand: 'state.load',
+        registryArgs: [],
+        mode: 'json',
+        projectDir: '/tmp',
+      }),
+    ).rejects.toThrow();
+
+    expect(onDispatchEvent).toHaveBeenCalledWith(
+      expect.objectContaining({
+        type: 'query_dispatch',
+        command: 'state.load',
+        outcome: 'error',
+        errorKind: 'timeout',
+      }),
+    );
+  });
+
+  it('emits hotpath event', async () => {
+    const onDispatchEvent = vi.fn();
+    const bridge = new QueryRuntimeBridge(
+      { has: () => true } as never,
+      { execute: vi.fn() } as never,
+      { dispatch: vi.fn(async () => 'ok') } as never,
+      () => true,
+      { onDispatchEvent },
+    );
+
+    await bridge.dispatchHotpath('commit', ['msg'], 'commit', ['msg'], 'raw');
+
+    expect(onDispatchEvent).toHaveBeenCalledWith(
+      expect.objectContaining({
+        type: 'query_hotpath_dispatch',
+        command: 'commit',
+        dispatchMode: 'native_hotpath',
+        outcome: 'success',
+      }),
+    );
+  });
+
+  it('emits subprocess hotpath event when native query is disabled', async () => {
+    const onDispatchEvent = vi.fn();
+    const bridge = new QueryRuntimeBridge(
+      { has: () => true } as never,
+      { execute: vi.fn() } as never,
+      { dispatch: vi.fn(async () => 'ok') } as never,
+      () => false,
+      { onDispatchEvent, allowFallbackToSubprocess: true },
+    );
+
+    await bridge.dispatchHotpath('commit', ['msg'], 'commit', ['msg'], 'raw');
+
+    expect(onDispatchEvent).toHaveBeenCalledWith(
+      expect.objectContaining({
+        type: 'query_hotpath_dispatch',
+        command: 'commit',
+        dispatchMode: 'subprocess',
+        reason: 'native_disabled',
+        outcome: 'success',
+      }),
+    );
+  });
+
+  it('blocks subprocess hotpath when fallback is disabled', async () => {
+    const onDispatchEvent = vi.fn();
+    const bridge = new QueryRuntimeBridge(
+      { has: () => true } as never,
+      { execute: vi.fn() } as never,
+      { dispatch: vi.fn(async () => 'ok') } as never,
+      () => false,
+      { onDispatchEvent, allowFallbackToSubprocess: false },
+    );
+
+    await expect(
+      bridge.dispatchHotpath('commit', ['msg'], 'commit', ['msg'], 'raw'),
+    ).rejects.toThrow("Subprocess fallback disabled");
+
+    expect(onDispatchEvent).toHaveBeenCalledWith(
+      expect.objectContaining({
+        type: 'query_hotpath_dispatch',
+        command: 'commit',
+        dispatchMode: 'subprocess',
+        reason: 'policy_blocked',
+        outcome: 'error',
+      }),
+    );
+  });
+});