@bhargavvc/sdd-cc 1.30.1 → 1.42.3

package/sdk/src/query/query-error-taxonomy.test.ts

@@ -0,0 +1,39 @@
+import { describe, it, expect } from 'vitest';
+import {
+  fallbackDispatchErrorFromSignal,
+  fallbackFailureError,
+  internalError,
+  nativeDispatchErrorFromSignal,
+  nativeFailureError,
+  nativeTimeoutError,
+  unknownCommandError,
+  validationError,
+} from './query-error-taxonomy.js';
+
+describe('query-error-taxonomy', () => {
+  it('builds unknown_command error', () => {
+    const err = unknownCommandError({
+      message: 'Error: Unknown command: "x"',
+      normalized: 'x',
+      attempted: ['x'],
+      hints: ['h1'],
+    });
+    expect(err.kind).toBe('unknown_command');
+    expect(err.code).toBe(10);
+    expect(err.details).toMatchObject({ normalized: 'x', attempted: ['x'], hints: ['h1'] });
+  });
+
+  it('builds native/fallback/validation/internal errors', () => {
+    expect(nativeFailureError({ message: 'boom', command: 'state.load', args: [] }).kind).toBe('native_failure');
+    expect(nativeTimeoutError({ message: 'timeout', command: 'state.load', args: [], timeoutMs: 30000 }).kind).toBe('native_timeout');
+    expect(fallbackFailureError({ message: 'spawn', command: 'state', args: ['load'] }).kind).toBe('fallback_failure');
+    expect(validationError({ message: 'bad', details: { r: 'x' } }).kind).toBe('validation_error');
+    expect(internalError({ message: 'bad' }).kind).toBe('internal_error');
+  });
+
+  it('projects dispatch errors from failure signals', () => {
+    expect(nativeDispatchErrorFromSignal({ kind: 'failure', message: 'boom' }, 'state.load', []).kind).toBe('native_failure');
+    expect(nativeDispatchErrorFromSignal({ kind: 'timeout', message: 'timeout', timeoutMs: 1000 }, 'state.load', []).kind).toBe('native_timeout');
+    expect(fallbackDispatchErrorFromSignal({ kind: 'failure', message: 'spawn' }, 'state', ['load']).kind).toBe('fallback_failure');
+  });
+});

package/sdk/src/query/query-error-taxonomy.ts

@@ -0,0 +1,117 @@
+import type { QueryDispatchError } from './query-dispatch-contract.js';
+import type { QueryFailureSignal } from '../query-failure-classification.js';
+import { fallbackErrorDetails, nativeErrorDetails, unknownCommandDetails } from './query-error-details-schema.js';
+export function unknownCommandError(input: {
+  message: string;
+  normalized: string;
+  attempted: string[];
+  hints: string[];
+}): QueryDispatchError {
+  return {
+    kind: 'unknown_command',
+    code: 10,
+    message: input.message,
+    details: unknownCommandDetails({
+      normalized: input.normalized,
+      attempted: input.attempted,
+      hints: input.hints,
+    }) as unknown as Record<string, unknown>,
+  };
+}
+
+export function nativeFailureError(input: {
+  message: string;
+  command: string;
+  args: string[];
+}): QueryDispatchError {
+  return {
+    kind: 'native_failure',
+    code: 1,
+    message: `Error: ${input.message}`,
+    details: nativeErrorDetails({
+      command: input.command,
+      args: input.args,
+    }) as unknown as Record<string, unknown>,
+  };
+}
+
+export function nativeTimeoutError(input: {
+  message: string;
+  command: string;
+  args: string[];
+  timeoutMs?: number;
+}): QueryDispatchError {
+  return {
+    kind: 'native_timeout',
+    code: 1,
+    message: `Error: ${input.message}`,
+    details: nativeErrorDetails({
+      command: input.command,
+      args: input.args,
+      ...(input.timeoutMs !== undefined ? { timeout_ms: input.timeoutMs } : {}),
+    }) as unknown as Record<string, unknown>,
+  };
+}
+
+export function fallbackFailureError(input: {
+  message: string;
+  command: string;
+  args: string[];
+  backend?: 'cjs';
+}): QueryDispatchError {
+  return {
+    kind: 'fallback_failure',
+    code: 1,
+    message: `Error: sdd-tools.cjs fallback failed: ${input.message}`,
+    details: fallbackErrorDetails({
+      command: input.command,
+      args: input.args,
+      backend: input.backend ?? 'cjs',
+    }) as unknown as Record<string, unknown>,
+  };
+}
+
+export function validationError(input: {
+  message: string;
+  code?: number;
+  details?: Record<string, unknown>;
+}): QueryDispatchError {
+  return {
+    kind: 'validation_error',
+    code: input.code ?? 10,
+    message: input.message,
+    details: input.details,
+  };
+}
+
+export function internalError(input: {
+  message: string;
+  code?: number;
+  details?: Record<string, unknown>;
+}): QueryDispatchError {
+  return {
+    kind: 'internal_error',
+    code: input.code ?? 1,
+    message: input.message,
+    details: input.details,
+  };
+}
+
+export function nativeDispatchErrorFromSignal(
+  signal: QueryFailureSignal,
+  command: string,
+  args: string[],
+): QueryDispatchError {
+  if (signal.kind === 'timeout') {
+    return nativeTimeoutError({ message: signal.message, command, args, timeoutMs: signal.timeoutMs });
+  }
+  return nativeFailureError({ message: signal.message, command, args });
+}
+
+export function fallbackDispatchErrorFromSignal(
+  signal: QueryFailureSignal,
+  command: string,
+  args: string[],
+): QueryDispatchError {
+  return fallbackFailureError({ message: signal.message, command, args, backend: 'cjs' });
+}

package/sdk/src/query/query-fallback-bridge-adapter.test.ts

@@ -0,0 +1,32 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { mkdir, rm, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { runFallbackBridge } from './query-fallback-bridge-adapter.js';
+
+describe('query-fallback-bridge-adapter', () => {
+  let tmpDir: string;
+  let fixtureDir: string;
+
+  beforeEach(async () => {
+    tmpDir = join(tmpdir(), `fallback-bridge-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+    fixtureDir = join(tmpDir, 'fixtures');
+    await mkdir(fixtureDir, { recursive: true });
+  });
+
+  afterEach(async () => {
+    await rm(tmpDir, { recursive: true, force: true });
+  });
+
+  it('includes stderr text when bridge subprocess fails', async () => {
+    const scriptPath = join(fixtureDir, 'fail.cjs');
+    await writeFile(scriptPath, "process.stderr.write('bridge boom'); process.exit(2);", { mode: 0o755 });
+
+    await expect(runFallbackBridge({
+      projectDir: tmpDir,
+      sddToolsPath: scriptPath,
+      normCmd: 'state',
+      normArgs: ['load'],
+    })).rejects.toThrow(/bridge boom/);
+  });
+});

package/sdk/src/query/query-fallback-bridge-adapter.ts

@@ -0,0 +1,54 @@
+import { execFile } from 'node:child_process';
+import { classifyFallbackOutput } from './query-fallback-output-classifier.js';
+
+export interface FallbackBridgeRunInput {
+  projectDir: string;
+  sddToolsPath: string;
+  normCmd: string;
+  normArgs: string[];
+  ws?: string;
+}
+
+export interface FallbackBridgeOutput {
+  mode: 'json' | 'text';
+  output: unknown;
+  stderr: string;
+}
+
+function dottedCommandToCjsArgv(normCmd: string, normArgs: string[]): string[] {
+  if (normCmd.includes('.')) return [...normCmd.split('.'), ...normArgs];
+  return [normCmd, ...normArgs];
+}
+
+function execBridge(input: FallbackBridgeRunInput): Promise<{ stdout: string; stderr: string }> {
+  const cjsArgv = dottedCommandToCjsArgv(input.normCmd, input.normArgs);
+  const wsSuffix = input.ws ? ['--ws', input.ws] : [];
+  const fullArgv = [input.sddToolsPath, ...cjsArgv, ...wsSuffix];
+
+  return new Promise((resolve, reject) => {
+    execFile(
+      process.execPath,
+      fullArgv,
+      { cwd: input.projectDir, maxBuffer: 10 * 1024 * 1024, timeout: 30_000, killSignal: 'SIGKILL', env: { ...process.env } },
+      (err, stdout, stderr) => {
+        const stdoutText = stdout?.toString() ?? '';
+        const stderrText = stderr?.toString() ?? '';
+        if (err) {
+          if (stderrText.trim()) {
+            reject(new Error(`${err.message}\n${stderrText.trimEnd()}`));
+            return;
+          }
+          reject(err);
+          return;
+        }
+        resolve({ stdout: stdoutText, stderr: stderrText });
+      },
+    );
+  });
+}
+
+export async function runFallbackBridge(input: FallbackBridgeRunInput): Promise<FallbackBridgeOutput> {
+  const { stdout, stderr } = await execBridge(input);
+  const classified = await classifyFallbackOutput(stdout, input.projectDir);
+  return { ...classified, stderr };
+}

package/sdk/src/query/query-fallback-executor.test.ts

@@ -0,0 +1,82 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { mkdir, rm, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { runCjsFallbackDispatch } from './query-fallback-executor.js';
+
+describe('runCjsFallbackDispatch', () => {
+  let tmpDir: string;
+  let fixtureDir: string;
+
+  beforeEach(async () => {
+    tmpDir = join(tmpdir(), `fallback-exec-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+    fixtureDir = join(tmpDir, 'fixtures');
+    await mkdir(fixtureDir, { 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('returns json output', async () => {
+    const script = await createScript('json.cjs', "process.stdout.write(JSON.stringify({ok:true}));");
+    const result = await runCjsFallbackDispatch({
+      projectDir: tmpDir,
+      sddToolsPath: script,
+      normCmd: 'state',
+      normArgs: ['load'],
+    });
+    expect(result.ok).toBe(true);
+    if (!result.ok) throw new Error('expected success');
+    expect(result.stdout).toBe('{\n  "ok": true\n}\n');
+  });
+
+  it('returns text output with trailing newline', async () => {
+    const script = await createScript('text.cjs', "process.stdout.write('USAGE: help text');");
+    const result = await runCjsFallbackDispatch({
+      projectDir: tmpDir,
+      sddToolsPath: script,
+      normCmd: 'phase',
+      normArgs: ['add', '--help'],
+    });
+    expect(result.ok).toBe(true);
+    if (!result.ok) throw new Error('expected success');
+    expect(result.stdout).toBe('USAGE: help text\n');
+  });
+
+  it('passes ws flag to cjs command', async () => {
+    const script = await createScript('ws.cjs', "const args=process.argv.slice(2); process.stdout.write(JSON.stringify({args}));");
+    const result = await runCjsFallbackDispatch({
+      projectDir: tmpDir,
+      sddToolsPath: script,
+      normCmd: 'state',
+      normArgs: ['load'],
+      ws: 'ws-1',
+      pickField: 'args',
+    });
+    expect(result.ok).toBe(true);
+    if (!result.ok) throw new Error('expected success');
+    expect(result.stdout).toBe('[\n  "state",\n  "load",\n  "--ws",\n  "ws-1"\n]\n');
+  });
+
+  it('returns structured error when subprocess fails', async () => {
+    const result = await runCjsFallbackDispatch({
+      projectDir: tmpDir,
+      sddToolsPath: join(fixtureDir, 'missing.cjs'),
+      normCmd: 'state',
+      normArgs: ['load'],
+    });
+    expect(result.ok).toBe(false);
+    if (result.ok) throw new Error('expected failure');
+    expect(result.error.code).toBe(1);
+    expect(result.error.kind).toBe('fallback_failure');
+    expect(result.error.message).toContain('fallback failed');
+    expect(result.error.details).toMatchObject({ command: 'state', args: ['load'], backend: 'cjs' });
+  });
+});

package/sdk/src/query/query-fallback-executor.ts

@@ -0,0 +1,44 @@
+import { formatSuccess } from './query-dispatch-formatting.js';
+import type { QueryDispatchResult } from './query-dispatch-contract.js';
+import { mapFallbackDispatchError, toDispatchFailure } from './query-dispatch-error-mapper.js';
+import { runFallbackBridge } from './query-fallback-bridge-adapter.js';
+import { fallbackBridgeNotices } from './query-dispatch-observability.js';
+
+export interface RunCjsFallbackDispatchInput {
+  projectDir: string;
+  sddToolsPath: string;
+  normCmd: string;
+  normArgs: string[];
+  ws?: string;
+  pickField?: string;
+}
+
+
+function formatFallbackOutput(data: unknown, mode: 'json' | 'text', pickField?: string): string | undefined {
+  if (mode === 'text') {
+    const text = String(data ?? '');
+    if (!text.trim()) return undefined;
+  }
+  return formatSuccess(data, mode, pickField);
+}
+
+export async function runCjsFallbackDispatch(input: RunCjsFallbackDispatchInput): Promise<QueryDispatchResult> {
+  const { projectDir, sddToolsPath, normCmd, normArgs, ws, pickField } = input;
+  const stderr = fallbackBridgeNotices(normCmd);
+
+  try {
+    const fallback = await runFallbackBridge({ projectDir, sddToolsPath, normCmd, normArgs, ws });
+    if (fallback.stderr.trim()) stderr.push(fallback.stderr.trimEnd());
+    return {
+      ok: true,
+      stderr,
+      stdout: formatFallbackOutput(fallback.output, fallback.mode, pickField) ?? '',
+      exit_code: 0,
+    };
+  } catch (err) {
+    return toDispatchFailure(
+      mapFallbackDispatchError(err, normCmd, normArgs),
+      stderr,
+    );
+  }
+}

package/sdk/src/query/query-fallback-output-classifier.test.ts

@@ -0,0 +1,36 @@
+import { describe, it, expect } from 'vitest';
+import { mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { classifyFallbackOutput } from './query-fallback-output-classifier.js';
+
+describe('query-fallback-output-classifier', () => {
+  it('classifies json output', async () => {
+    const out = await classifyFallbackOutput('{"ok":true}', process.cwd());
+    expect(out.mode).toBe('json');
+  });
+
+  it('classifies text output on invalid json', async () => {
+    const out = await classifyFallbackOutput('USAGE', process.cwd());
+    expect(out.mode).toBe('text');
+  });
+
+  it('resolves @file json output', async () => {
+    const dir = await mkdtemp(join(tmpdir(), 'classifier-'));
+    try {
+      const file = join(dir, 'payload.json');
+      await writeFile(file, '{"from":"file"}', 'utf-8');
+      const out = await classifyFallbackOutput('@file:payload.json', dir);
+      expect(out.mode).toBe('json');
+      expect(out.output).toEqual({ from: 'file' });
+    } finally {
+      await rm(dir, { recursive: true, force: true });
+    }
+  });
+
+  it('classifies empty output as text', async () => {
+    const out = await classifyFallbackOutput('   ', process.cwd());
+    expect(out.mode).toBe('text');
+    expect(out.output).toBe('   ');
+  });
+});

package/sdk/src/query/query-fallback-output-classifier.ts

@@ -0,0 +1,31 @@
+import { readFile } from 'node:fs/promises';
+
+export interface FallbackOutputClassification {
+  mode: 'json' | 'text';
+  output: unknown;
+}
+
+async function parseCliQueryJsonOutput(raw: string, projectDir: string): Promise<unknown> {
+  const trimmed = raw.trim();
+  if (trimmed === '') return null;
+  let jsonStr = trimmed;
+  if (jsonStr.startsWith('@file:')) {
+    const rel = jsonStr.slice(6).trim();
+    const { resolvePathUnderProject } = await import('./helpers.js');
+    const filePath = await resolvePathUnderProject(projectDir, rel);
+    jsonStr = await readFile(filePath, 'utf-8');
+  }
+  return JSON.parse(jsonStr);
+}
+
+export async function classifyFallbackOutput(raw: string, projectDir: string): Promise<FallbackOutputClassification> {
+  if (raw.trim() === '') {
+    return { mode: 'text', output: raw };
+  }
+  try {
+    const output = await parseCliQueryJsonOutput(raw, projectDir);
+    return { mode: 'json', output };
+  } catch {
+    return { mode: 'text', output: raw };
+  }
+}

package/sdk/src/query/query-fallback-policy.test.ts

@@ -0,0 +1,13 @@
+import { describe, it, expect } from 'vitest';
+import { canUseCjsFallback, describeFallbackDisabledPolicy } from './query-fallback-policy.js';
+
+describe('query-fallback-policy', () => {
+  it('describes disabled fallback policy', () => {
+    expect(describeFallbackDisabledPolicy()).toContain('SDD_QUERY_FALLBACK=registered');
+  });
+
+  it('reports fallback capability', () => {
+    expect(canUseCjsFallback({ cjsFallbackEnabled: true })).toBe(true);
+    expect(canUseCjsFallback({ cjsFallbackEnabled: false })).toBe(false);
+  });
+});

package/sdk/src/query/query-fallback-policy.ts

@@ -0,0 +1,11 @@
+export interface FallbackPolicyState {
+  cjsFallbackEnabled: boolean;
+}
+
+export function describeFallbackDisabledPolicy(): string {
+  return 'CJS fallback is disabled (SDD_QUERY_FALLBACK=registered).';
+}
+
+export function canUseCjsFallback(policy: FallbackPolicyState): boolean {
+  return policy.cjsFallbackEnabled;
+}

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

@@ -0,0 +1,16 @@
+import type { QueryRegistry } from './registry.js';
+import type { QueryResult } from './utils.js';
+
+export interface QueryNativeDispatchAdapter {
+  dispatch(command: string, args: string[]): Promise<QueryResult>;
+}
+
+export function createQueryNativeDispatchAdapter(
+  registry: QueryRegistry,
+  projectDir: string,
+  ws?: string,
+): QueryNativeDispatchAdapter {
+  return {
+    dispatch: (command, args) => registry.dispatch(command, args, projectDir, ws),
+  };
+}

package/sdk/src/query/query-policy-capability.test.ts

@@ -0,0 +1,10 @@
+import { describe, it, expect } from 'vitest';
+import { QUERY_POLICY_SNAPSHOT, supportsMutationCommand, supportsRawOutputCommand } from './query-policy-capability.js';
+
+describe('query-policy-capability', () => {
+  it('exposes snapshot + predicates', () => {
+    expect(QUERY_POLICY_SNAPSHOT.mutation_commands.length).toBeGreaterThan(0);
+    expect(supportsMutationCommand('state.update')).toBe(true);
+    expect(supportsRawOutputCommand('state.load')).toBe(true);
+  });
+});

package/sdk/src/query/query-policy-capability.ts

@@ -0,0 +1,26 @@
+import {
+  QUERY_MUTATION_COMMANDS_FROM_DEFINITIONS,
+  TRANSPORT_RAW_COMMANDS_FROM_DEFINITIONS,
+  COMMAND_MUTATION_SET,
+  COMMAND_RAW_OUTPUT_SET,
+} from './command-definition.js';
+
+export const QUERY_MUTATION_COMMAND_LIST: readonly string[] = QUERY_MUTATION_COMMANDS_FROM_DEFINITIONS;
+export const TRANSPORT_RAW_COMMANDS: readonly string[] = TRANSPORT_RAW_COMMANDS_FROM_DEFINITIONS;
+
+export const QUERY_POLICY_SNAPSHOT = {
+  mutation_commands: QUERY_MUTATION_COMMAND_LIST,
+  raw_output_commands: TRANSPORT_RAW_COMMANDS,
+} as const;
+
+export function supportsMutationCommand(command: string): boolean {
+  return COMMAND_MUTATION_SET.has(command);
+}
+
+export function supportsRawOutputCommand(command: string): boolean {
+  return COMMAND_RAW_OUTPUT_SET.has(command);
+}
+
+export function isQueryMutationCommand(command: string): boolean {
+  return COMMAND_MUTATION_SET.has(command);
+}

package/sdk/src/query/query-policy-snapshot.test.ts

@@ -0,0 +1,9 @@
+import { describe, it, expect } from 'vitest';
+import { QUERY_POLICY_SNAPSHOT, QUERY_MUTATION_COMMAND_LIST, TRANSPORT_RAW_COMMANDS } from './query-policy-capability.js';
+
+describe('query-policy-snapshot', () => {
+  it('exposes policy constants through one snapshot interface', () => {
+    expect(QUERY_POLICY_SNAPSHOT.mutation_commands).toBe(QUERY_MUTATION_COMMAND_LIST);
+    expect(QUERY_POLICY_SNAPSHOT.raw_output_commands).toBe(TRANSPORT_RAW_COMMANDS);
+  });
+});

package/sdk/src/query/query-registry-capability.test.ts

@@ -0,0 +1,14 @@
+import { describe, it, expect } from 'vitest';
+import { supportsMutationCommand, supportsRawOutputCommand } from './query-policy-capability.js';
+
+describe('query-registry-capability', () => {
+  it('reports mutation command capability', () => {
+    expect(supportsMutationCommand('state.update')).toBe(true);
+    expect(supportsMutationCommand('state.json')).toBe(false);
+  });
+
+  it('reports raw output capability', () => {
+    expect(supportsRawOutputCommand('state.load')).toBe(true);
+    expect(supportsRawOutputCommand('state.json')).toBe(false);
+  });
+});

package/sdk/src/query/query-runtime-context.ts

@@ -0,0 +1,44 @@
+import { findProjectRoot } from './helpers.js';
+import { validateWorkstreamName } from '../workstream-utils.js';
+import { readActiveWorkstream } from './active-workstream-store.js';
+
+export interface QueryRuntimeContextInput {
+  projectDir: string;
+  ws?: string;
+}
+
+export interface QueryRuntimeContext {
+  projectDir: string;
+  ws?: string;
+}
+
+/**
+ * Resolve the runtime context for a query invocation.
+ *
+ * Workstream resolution priority:
+ *   1. `--ws <name>` flag (input.ws)
+ *   2. `SDD_WORKSTREAM` environment variable
+ *   3. `.planning/active-workstream` file
+ *   4. Root `.planning/` (no workstream)
+ */
+export function resolveQueryRuntimeContext(input: QueryRuntimeContextInput): QueryRuntimeContext {
+  const projectDir = findProjectRoot(input.projectDir);
+
+  if (input.ws !== undefined) {
+    return {
+      projectDir,
+      ws: validateWorkstreamName(input.ws) ? input.ws : undefined,
+    };
+  }
+
+  const envWs = process.env.SDD_WORKSTREAM;
+  if (envWs && validateWorkstreamName(envWs)) {
+    return { projectDir, ws: envWs };
+  }
+
+  const fileWs = readActiveWorkstream(projectDir);
+  return {
+    projectDir,
+    ws: fileWs ?? undefined,
+  };
+}

package/sdk/src/query/query-unknown-command-hints.test.ts

@@ -0,0 +1,9 @@
+import { describe, it, expect } from 'vitest';
+import { UNKNOWN_COMMAND_HINTS } from './query-unknown-command-hints.js';
+
+describe('query-unknown-command-hints', () => {
+  it('exports stable hint catalog', () => {
+    expect(UNKNOWN_COMMAND_HINTS.length).toBeGreaterThan(1);
+    expect(UNKNOWN_COMMAND_HINTS[0]).toContain('registered `sdd-sdk query`');
+  });
+});

package/sdk/src/query/query-unknown-command-hints.ts

@@ -0,0 +1,5 @@
+export const UNKNOWN_COMMAND_HINTS: readonly string[] = [
+  'Use a registered `sdd-sdk query` subcommand (see sdk/src/query/QUERY-HANDLERS.md).',
+  'Invoke `node …/sdd-tools.cjs` for CJS-only operations.',
+  'Unset SDD_QUERY_FALLBACK or set it to a non-restricted value to enable fallback.',
+] as const;