@hegemonart/get-design-done 1.31.0 → 1.32.0

package/scripts/lib/cli/index.ts

@@ -1,167 +1,29 @@
-// scripts/lib/cli/index.ts — Plan 21-09 Task 7 (SDK-21).
+// scripts/lib/cli/index.ts — GDD-DEPRECATION-SHIM (Plan 31-5-06, SDK-05, D-02).
 //
-// Main dispatcher for the `gdd-sdk` CLI. Invoked by `bin/gdd-sdk` (the
-// CJS trampoline) with `--experimental-strip-types` so TS runs without
-// a build step.
+// Thin deprecation shim. The real implementation moved to sdk/cli/index.ts
+// in Plan 31-5-04 (SDK consolidation). This file is re-created at the OLD
+// path so undocumented EXTERNAL importers (anyone who reached into
+// node_modules/@hegemonart/get-design-done/scripts/lib/cli/index.ts directly)
+// keep working for one minor grace window.
 //
-// Responsibilities:
-//   * Parse argv via parseArgs().
-//   * Route by first positional to the matching subcommand module.
-//   * Print top-level USAGE on bare `gdd-sdk` / `-h` / `--help`.
-//   * Exit with the subcommand's return code. Unknown subcommands
-//     exit 3 and print USAGE to stderr.
+// REMOVED IN v1.33.0 (D-02). Grace window: 1.31.5 ships with shims →
+// 1.32.0 still has them → 1.33.0 removes them. Internal callers already use
+// the sdk/ path (Plan 31-5-04/05) — this shim is external-only; 31-5-10's
+// no-stale-internal-refs guard excludes files carrying the
+// GDD-DEPRECATION-SHIM marker above.
 //
-// The bottom of this file has the `main()` bootstrap that the trampoline
-// invokes. It catches any accidental throw (subcommands are contracted
-// not to throw) and translates to exit code 3.
+// Runs under --experimental-strip-types (the runtime `bin/gdd-sdk` and the
+// test suite both use it), so `export *` re-export is strip-types-clean.
 
-import { parseArgs, type ParsedArgs } from './parse-args.ts';
-import { runCommand } from './commands/run.ts';
-import { stageCommand } from './commands/stage.ts';
-import { queryCommand } from './commands/query.ts';
-import { auditCommand } from './commands/audit.ts';
-import { initCommand } from './commands/init.ts';
+import { emitWarning } from 'node:process';
 
-// ---------------------------------------------------------------------------
-// Top-level USAGE.
-// ---------------------------------------------------------------------------
-
-export const USAGE = `gdd-sdk <command> [flags]
-
-Commands:
-  run              Run the full design pipeline headlessly.
-  stage <name>     Run a single stage (brief|explore|plan|design|verify|discuss).
-  query <op>       Typed STATE.md read operations.
-  audit            Probe connections + dry-run verify.
-  init             Bootstrap a new project.
-
-Use 'gdd-sdk <command> -h' for command-specific flags.
-
-Exit codes (general):
-  0  success
-  1  halted / regression / already-initialized
-  2  awaiting-gate / partial (init)
-  3  argument / config error
-`;
-
-// ---------------------------------------------------------------------------
-// Deps.
-// ---------------------------------------------------------------------------
-
-export interface DispatcherDeps {
-  readonly stdout?: NodeJS.WritableStream;
-  readonly stderr?: NodeJS.WritableStream;
-  readonly commands?: {
-    readonly run?: typeof runCommand;
-    readonly stage?: typeof stageCommand;
-    readonly query?: typeof queryCommand;
-    readonly audit?: typeof auditCommand;
-    readonly init?: typeof initCommand;
-  };
-}
-
-// ---------------------------------------------------------------------------
-// Dispatcher.
-// ---------------------------------------------------------------------------
-
-/**
- * Dispatch a parsed ParsedArgs to the appropriate subcommand. Exported
- * for tests (they can construct a ParsedArgs manually and assert the
- * exit code + captured stdout/stderr).
- */
-export async function dispatch(
-  parsed: ParsedArgs,
-  deps: DispatcherDeps = {},
-): Promise<number> {
-  const stdout = deps.stdout ?? process.stdout;
-  const stderr = deps.stderr ?? process.stderr;
-  const commands = {
-    run: deps.commands?.run ?? runCommand,
-    stage: deps.commands?.stage ?? stageCommand,
-    query: deps.commands?.query ?? queryCommand,
-    audit: deps.commands?.audit ?? auditCommand,
-    init: deps.commands?.init ?? initCommand,
-  };
-
-  // Bare invocation or top-level help → USAGE.
-  if (parsed.subcommand === null) {
-    stdout.write(USAGE);
-    return 0;
-  }
-  if (
-    (parsed.flags['help'] === true || parsed.flags['h'] === true) &&
-    // Top-level --help (no subcommand recognized yet; --help before the
-    // first positional lands here). Subcommands also honor --help
-    // themselves, so this branch only fires for `gdd-sdk --help`.
-    parsed.positionals.length === 0 &&
-    !KNOWN_SUBCOMMANDS.has(parsed.subcommand)
-  ) {
-    stdout.write(USAGE);
-    return 0;
-  }
-
-  switch (parsed.subcommand) {
-    case 'run':
-      return await commands.run(parsed, { stdout, stderr });
-    case 'stage':
-      return await commands.stage(parsed, { stdout, stderr });
-    case 'query':
-      return await commands.query(parsed, { stdout, stderr });
-    case 'audit':
-      return await commands.audit(parsed, { stdout, stderr });
-    case 'init':
-      return await commands.init(parsed, { stdout, stderr });
-    default:
-      stderr.write(
-        `gdd-sdk: unknown subcommand "${parsed.subcommand}"\n${USAGE}`,
-      );
-      return 3;
-  }
-}
-
-const KNOWN_SUBCOMMANDS: ReadonlySet<string> = new Set([
-  'run',
-  'stage',
-  'query',
-  'audit',
-  'init',
-]);
-
-// ---------------------------------------------------------------------------
-// Bootstrap entry point — called by bin/gdd-sdk trampoline.
-// ---------------------------------------------------------------------------
-
-/**
- * Top-level main. Parses process.argv.slice(2), dispatches, prints
- * USAGE + exit 3 on any uncaught error. Exported so tests can invoke
- * it directly (bypassing the trampoline).
- */
-export async function main(
-  argv: readonly string[] = process.argv.slice(2),
-  deps: DispatcherDeps = {},
-): Promise<number> {
-  const parsed = parseArgs(argv);
-  return await dispatch(parsed, deps);
-}
-
-// ---------------------------------------------------------------------------
-// When executed directly by the trampoline, invoke main() + exit.
-// ---------------------------------------------------------------------------
-
-// Only self-invoke when this module IS the entry point. We detect that
-// by checking process.argv[1] (trampoline passes this file's path).
-//
-// `import.meta.url` is the POSIX idiom but this TS runs under --experimental-strip-types
-// as Node16 modules — we use process.argv to stay ESM/CJS-agnostic.
-
-const entryPath: string = (process.argv[1] ?? '').replace(/\\/g, '/');
-if (entryPath.endsWith('/scripts/lib/cli/index.ts')) {
-  main().then(
-    (code) => process.exit(code),
-    (err) => {
-      // eslint-disable-next-line no-console
-      console.error('gdd-sdk: unexpected error:', err);
-      process.exit(3);
-    },
+let warned = false;
+if (!warned) {
+  warned = true;
+  emitWarning(
+    'scripts/lib/cli/index.ts is deprecated; import sdk/cli instead. Removed in v1.33.0.',
+    'DeprecationWarning',
   );
 }
+
+export * from '../../../sdk/cli/index.ts';

package/scripts/lib/connection-probe/index.cjs

@@ -42,7 +42,7 @@
 const { writeFileSync, readFileSync, existsSync, mkdirSync, renameSync } = require('node:fs');
 const { dirname, isAbsolute, resolve, join } = require('node:path');
 
-const { delayMs } = require('../jittered-backoff.cjs');
+const { delayMs } = require('../../../sdk/primitives/jittered-backoff.cjs');
 
 const DEFAULT_STATE_PATH = '.design/telemetry/connection-state.json';
 

package/scripts/lib/discuss-parallel-runner/aggregator.ts

@@ -27,7 +27,7 @@ import type {
   SessionResult,
   SessionRunnerOptions,
 } from '../session-runner/types.ts';
-import { ValidationError } from '../gdd-errors/index.ts';
+import { ValidationError } from '../../../sdk/errors/index.ts';
 import { getLogger } from '../logger/index.ts';
 
 import type {

package/scripts/lib/discuss-parallel-runner/index.ts

@@ -27,7 +27,7 @@
 // Consumers: `discuss` skill (Plan 21-08 / future) + `gdd-sdk discuss`
 // CLI subcommand (Plan 21-09).
 
-import { OperationFailedError } from '../gdd-errors/index.ts';
+import { OperationFailedError } from '../../../sdk/errors/index.ts';
 import { getLogger } from '../logger/index.ts';
 import { resolveConcurrency } from '../parallelism-engine/concurrency-tuner.cjs';
 

package/scripts/lib/error-classifier.cjs

@@ -1,232 +1,29 @@
-// scripts/lib/error-classifier.cjs
-//
-// Plan 20-14 — classify raw errors into a recovery-action vocabulary.
-//
-// Plan 20-04 shipped the GDDError taxonomy (ValidationError /
-// StateConflictError / OperationFailedError). This module is one layer
-// lower: it maps LOW-LEVEL errors (fetch rejections, Anthropic API
-// responses, Node errno rejections) onto a small enum that recovery
-// code can switch on without needing to know which SDK produced the
-// error.
-//
-// Consumers (e.g. budget-enforcer retry, figma probe retry, MCP
-// transport) check `classify(err).reason` and decide whether to retry,
-// compress, surface, or fail.
+'use strict';
+// scripts/lib/error-classifier.cjs — GDD-DEPRECATION-SHIM (Plan 31-5-06, SDK-05, D-02).
 //
-// Classification rules — evaluated in order; first match wins:
-//   1. HTTP 429  OR  message ~ /rate.?limit/       → RATE_LIMITED      (retryable)
-//   2. HTTP 413  OR  /context.?(length|window|overflow)/
-//                OR  /context_length_exceeded/     → CONTEXT_OVERFLOW  (retryable with compression)
-//   3. HTTP 401/403                                → AUTH_ERROR        (NOT retryable)
-//   4. /tool not found|unknown tool/               → TOOL_NOT_FOUND    (NOT retryable)
-//   5. HTTP 5xx  OR  errno ECONNRESET/ETIMEDOUT/EAI_AGAIN/ECONNREFUSED
-//                OR  /network|timeout|socket/       → NETWORK_TRANSIENT (retryable)
-//   6. HTTP 4xx (non-auth, non-rate, non-overflow) → VALIDATION        (NOT retryable)
-//   7. HTTP >= 400 with no other match             → NETWORK_PERMANENT (NOT retryable)
-//   8. Anything else (null, undefined, plain Error) → UNKNOWN          (NOT retryable)
+// Thin deprecation shim. The real implementation moved to
+// sdk/primitives/error-classifier.cjs in Plan 31-5-04 (SDK consolidation).
+// This file is re-created at the OLD path so undocumented EXTERNAL importers
+// (anyone who reached into node_modules/@hegemonart/get-design-done/scripts/
+// lib/error-classifier.cjs directly) keep working for one minor grace window.
 //
-// Rule order matters: the tool-not-found string can land inside
-// otherwise-validation-shaped errors, so it's checked early. Anthropic
-// "context_length_exceeded" returns HTTP 400 in some surfaces and HTTP
-// 413 in others — rule 2 catches it either way.
+// REMOVED IN v1.33.0 (D-02). Grace window: 1.31.5 ships with shims →
+// 1.32.0 still has them → 1.33.0 removes them. Internal callers already use
+// the sdk/ path (Plan 31-5-04/05) — this shim is external-only and 31-5-10's
+// no-stale-internal-refs guard excludes files carrying the GDD-DEPRECATION-SHIM
+// marker above.
 //
-// Reference: `reference/error-recovery.md` describes the protocol layer
-// that sits on top of this module.
-
-'use strict';
-
-/**
- * @readonly
- * @enum {string}
- */
-const FailoverReason = Object.freeze({
-  RATE_LIMITED: 'rate_limited',
-  CONTEXT_OVERFLOW: 'context_overflow',
-  AUTH_ERROR: 'auth_error',
-  NETWORK_TRANSIENT: 'network_transient',
-  NETWORK_PERMANENT: 'network_permanent',
-  TOOL_NOT_FOUND: 'tool_not_found',
-  VALIDATION: 'validation',
-  UNKNOWN: 'unknown',
-});
-
-/** Suggested actions per reason — keyed by FailoverReason. */
-const SUGGESTED_ACTIONS = Object.freeze({
-  [FailoverReason.RATE_LIMITED]:
-    'consult scripts/lib/rate-guard.cjs → blockUntilReady(provider); then retry with scripts/lib/jittered-backoff.cjs',
-  [FailoverReason.CONTEXT_OVERFLOW]:
-    'compress context (drop oldest non-system turns; target 50% reduction) and retry once',
-  [FailoverReason.AUTH_ERROR]:
-    'surface to user — do not retry; credentials or OAuth session need refresh',
-  [FailoverReason.NETWORK_TRANSIENT]:
-    'retry with scripts/lib/jittered-backoff.cjs; max 3 attempts',
-  [FailoverReason.NETWORK_PERMANENT]:
-    'surface to user; do not retry — endpoint is wrong or resource is gone',
-  [FailoverReason.TOOL_NOT_FOUND]:
-    'do not retry; verify tool name and MCP registration',
-  [FailoverReason.VALIDATION]:
-    'do not retry same input; surface validation detail to caller',
-  [FailoverReason.UNKNOWN]:
-    'surface to user — cannot determine safe recovery action',
-});
-
-/** Which reasons are safe to retry by policy. */
-const RETRYABLE = Object.freeze({
-  [FailoverReason.RATE_LIMITED]: true,
-  [FailoverReason.CONTEXT_OVERFLOW]: true,
-  [FailoverReason.NETWORK_TRANSIENT]: true,
-  [FailoverReason.AUTH_ERROR]: false,
-  [FailoverReason.NETWORK_PERMANENT]: false,
-  [FailoverReason.TOOL_NOT_FOUND]: false,
-  [FailoverReason.VALIDATION]: false,
-  [FailoverReason.UNKNOWN]: false,
-});
-
-/** Extract a numeric HTTP status from an error shape. Returns null on miss. */
-function statusOf(err) {
-  if (err === null || err === undefined) return null;
-  if (typeof err !== 'object') return null;
-  // Direct status / statusCode field.
-  if (Number.isFinite(err.status)) return Number(err.status);
-  if (Number.isFinite(err.statusCode)) return Number(err.statusCode);
-  // Fetch / node-fetch responses wrap status under .response.
-  if (err.response && typeof err.response === 'object') {
-    if (Number.isFinite(err.response.status)) return Number(err.response.status);
-    if (Number.isFinite(err.response.statusCode)) return Number(err.response.statusCode);
-  }
-  return null;
-}
-
-/** Extract a string message; tolerant of anything. */
-function messageOf(err) {
-  if (err === null || err === undefined) return '';
-  if (typeof err === 'string') return err;
-  if (typeof err === 'object') {
-    // Gather every string-ish field in priority order; join with ' | ' so
-    // classification regexes can match against any of them without the
-    // caller needing to know which SDK shaped the error. OpenAI-style
-    // wraps the interesting discriminator in `error.code` while keeping
-    // a generic top-level message; the join lets both contribute.
-    const parts = [];
-    if (typeof err.message === 'string' && err.message.length > 0) parts.push(err.message);
-    if (err.error && typeof err.error === 'object') {
-      if (typeof err.error.code === 'string') parts.push(err.error.code);
-      if (typeof err.error.type === 'string') parts.push(err.error.type);
-      if (typeof err.error.message === 'string') parts.push(err.error.message);
-    }
-    // Only use top-level `code` when it is NOT an errno (errnoOf handles
-    // those). Errnos always match /^E[A-Z0-9_]+$/, so filter them out.
-    if (typeof err.code === 'string' && !/^E[A-Z0-9_]+$/.test(err.code)) {
-      parts.push(err.code);
-    }
-    if (parts.length > 0) return parts.join(' | ');
-  }
-  return '';
-}
-
-/** Extract a low-level errno code (ECONNRESET, ETIMEDOUT, ...). */
-function errnoOf(err) {
-  if (err === null || err === undefined || typeof err !== 'object') return '';
-  if (typeof err.code === 'string' && /^E[A-Z0-9_]+$/.test(err.code)) return err.code;
-  // fetch native in newer Node wraps the cause
-  if (err.cause && typeof err.cause === 'object') {
-    const code = err.cause.code;
-    if (typeof code === 'string' && /^E[A-Z0-9_]+$/.test(code)) return code;
-  }
-  return '';
-}
-
-/**
- * Classify a raw error into a {@link FailoverReason}.
- *
- * @param {unknown} err
- * @returns {{reason: string, retryable: boolean, suggestedAction: string, raw: unknown}}
- */
-function classify(err) {
-  const status = statusOf(err);
-  const message = messageOf(err).toLowerCase();
-  const errno = errnoOf(err);
-
-  // 1. Rate limit.
-  if (status === 429 || /rate.?limit/.test(message) || /too many requests/.test(message)) {
-    return build(FailoverReason.RATE_LIMITED, err);
-  }
-
-  // 2. Context overflow. Anthropic returns 400 with type=invalid_request and
-  //    message containing "prompt is too long"; OpenAI returns 400 with
-  //    code=context_length_exceeded; some edge surfaces use 413.
-  if (
-    status === 413 ||
-    /context_length_exceeded/.test(message) ||
-    /context.{0,10}(length|window|overflow|too.?long)/.test(message) ||
-    /prompt is too long/.test(message) ||
-    /maximum context length/.test(message)
-  ) {
-    return build(FailoverReason.CONTEXT_OVERFLOW, err);
-  }
-
-  // 3. Auth.
-  if (status === 401 || status === 403) {
-    return build(FailoverReason.AUTH_ERROR, err);
-  }
-  if (
-    /not authenticated/.test(message) ||
-    /invalid[_ ]api[_ ]key/.test(message) ||
-    /unauthorized/.test(message) ||
-    /authentication/.test(message)
-  ) {
-    return build(FailoverReason.AUTH_ERROR, err);
-  }
-
-  // 4. Tool not found.
-  if (/tool not found/.test(message) || /unknown tool/.test(message) || /no such tool/.test(message)) {
-    return build(FailoverReason.TOOL_NOT_FOUND, err);
-  }
-
-  // 5. Network transient: 5xx or low-level errno.
-  if (typeof status === 'number' && status >= 500 && status < 600) {
-    return build(FailoverReason.NETWORK_TRANSIENT, err);
-  }
-  if (
-    errno === 'ECONNRESET' ||
-    errno === 'ETIMEDOUT' ||
-    errno === 'EAI_AGAIN' ||
-    errno === 'ECONNREFUSED' ||
-    errno === 'ENETUNREACH' ||
-    errno === 'EPIPE'
-  ) {
-    return build(FailoverReason.NETWORK_TRANSIENT, err);
-  }
-  if (/\bsocket\b/.test(message) || /network/.test(message) || /\btimeout\b/.test(message)) {
-    return build(FailoverReason.NETWORK_TRANSIENT, err);
-  }
-
-  // 6. Other 4xx → validation.
-  if (typeof status === 'number' && status >= 400 && status < 500) {
-    return build(FailoverReason.VALIDATION, err);
-  }
-
-  // 7. Other >= 400 (e.g. 6xx exotic gateway codes).
-  if (typeof status === 'number' && status >= 400) {
-    return build(FailoverReason.NETWORK_PERMANENT, err);
-  }
-
-  // 8. Fallthrough.
-  return build(FailoverReason.UNKNOWN, err);
-}
-
-function build(reason, raw) {
-  return {
-    reason,
-    retryable: RETRYABLE[reason] === true,
-    suggestedAction: SUGGESTED_ACTIONS[reason],
-    raw,
-  };
+// Emits a DeprecationWarning exactly ONCE per process: the module-level
+// `warned` flag plus Node's module cache (this file is evaluated once per
+// process regardless of how many times it is required).
+
+let warned = false;
+if (!warned) {
+  warned = true;
+  process.emitWarning(
+    'scripts/lib/error-classifier.cjs is deprecated; import sdk/primitives/error-classifier instead. Removed in v1.33.0.',
+    'DeprecationWarning',
+  );
 }
 
-module.exports = {
-  FailoverReason,
-  classify,
-  SUGGESTED_ACTIONS,
-  RETRYABLE,
-};
+module.exports = require('../../sdk/primitives/error-classifier.cjs');