@sdt-tools/cli 0.2.0 → 0.2.6

package/dist/chunk-ZWY4ZRHL.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/util/ai-explain.ts"],"sourcesContent":["/**\n * `--explain` flag helper — shared across every command that produces a\n * structured report (compare, diagnose, review, impact, cost-estimate,\n * lineage, lint, pr-comment, test, …).\n *\n * Each consumer calls `attachExplainFlag(cmd, { feature, systemPrompt })`\n * during command construction, then awaits `runExplain(buildPrompt, opts)`\n * after the structured output has been printed. The helper:\n *\n *   - declares the `--explain` (alias `--ai-explain`) flag,\n *   - reads the configured AI provider via `@sdt-tools/core/ai`,\n *   - calls `complete()` with a stable system prompt + the consumer's\n *     prompt body,\n *   - prints the narration to stdout under an \"AI explanation:\" header,\n *   - gracefully degrades when no provider is configured (a friendly\n *     hint pointing at `sdt ai status` is printed; non-zero exit code is\n *     NOT set — `--explain` is best-effort decoration on top of the\n *     structured output).\n *\n * Mirrors `Databricks/packages/cli/src/util/ai-explain.ts`.\n */\nimport type { Command } from 'commander';\nimport { ai } from '@sdt-tools/core';\nimport { logger } from './logger.js';\n\nexport interface ExplainContext {\n  /**\n   * Stable feature identifier surfaced to the AI usage telemetry so we\n   * can analyze which command surfaces actually drive AI traffic.\n   * Convention: `<command>.explain` (e.g. `diagnose.explain`).\n   */\n  feature: string;\n  /**\n   * System prompt setting the assistant's persona. Each command picks\n   * the wording that matches its role (senior DBA / senior data eng /\n   * release-manager / etc.). The default is a generic Snowflake-savvy\n   * narrator suitable for most commands.\n   */\n  systemPrompt?: string;\n}\n\nconst DEFAULT_SYSTEM_PROMPT = `You are a senior Snowflake DBA reviewing structured output from the SDT CLI. Narrate it for a teammate who has not seen the underlying SQL. Be concrete and specific — reference identifiers by name. Group related items together. Skip information that is already obvious from the structured output; add the missing intent, risks, and follow-up actions. 4-10 sentences total unless the data warrants more.`;\n\n/**\n * Attach the `--explain` flag to a command. Idempotent — safe to call on\n * any command, including ones that already define `--explain`\n * (commander will throw, so we guard against double-attach).\n */\nexport function attachExplainFlag(cmd: Command, description?: string): Command {\n  const hasExplain = cmd.options.some((o) => o.long === '--explain' || o.long === '--ai-explain');\n  if (hasExplain) return cmd;\n  cmd.option(\n    '--explain',\n    description ??\n      'After the structured output, call the configured AI provider to narrate the result in plain English. Requires `sdt ai` to be configured.',\n    false,\n  );\n  return cmd;\n}\n\n/**\n * Run the AI narration step. Call this AFTER the structured output is\n * printed so the user sees the deterministic result first and the AI\n * commentary second.\n *\n * `opts.explain` is the parsed value of the `--explain` flag — when\n * falsy, this is a no-op. The consumer passes a `buildPrompt` callback\n * that returns the user message body; the callback is only invoked when\n * `--explain` is on, so consumers don't pay the prompt-construction cost\n * when AI is off.\n */\nexport async function runExplain(\n  ctx: ExplainContext,\n  opts: { explain?: boolean },\n  buildPrompt: () => string,\n): Promise<void> {\n  if (!opts.explain) return;\n  const system = ctx.systemPrompt ?? DEFAULT_SYSTEM_PROMPT;\n  logger.info('');\n  logger.info('AI explanation:');\n  try {\n    const reply = await ai.complete(\n      [\n        { role: 'system', content: system },\n        { role: 'user', content: buildPrompt() },\n      ],\n      { feature: ctx.feature },\n    );\n    for (const line of reply.text.split('\\n')) logger.info('  ' + line);\n  } catch (err) {\n    logger.error('  --explain failed: ' + (err instanceof Error ? err.message : String(err)));\n    logger.error(\n      '  Run `sdt ai status` to verify your AI provider is configured (`sdt ai test` to send a probe).',\n    );\n  }\n}\n"],"mappings":";;;;;AAsBA,SAAS,UAAU;AAmBnB,IAAM,wBAAwB;AAOvB,SAAS,kBAAkB,KAAc,aAA+B;AAC7E,QAAM,aAAa,IAAI,QAAQ,KAAK,CAAC,MAAM,EAAE,SAAS,eAAe,EAAE,SAAS,cAAc;AAC9F,MAAI,WAAY,QAAO;AACvB,MAAI;AAAA,IACF;AAAA,IACA,eACE;AAAA,IACF;AAAA,EACF;AACA,SAAO;AACT;AAaA,eAAsB,WACpB,KACA,MACA,aACe;AACf,MAAI,CAAC,KAAK,QAAS;AACnB,QAAM,SAAS,IAAI,gBAAgB;AACnC,SAAO,KAAK,EAAE;AACd,SAAO,KAAK,iBAAiB;AAC7B,MAAI;AACF,UAAM,QAAQ,MAAM,GAAG;AAAA,MACrB;AAAA,QACE,EAAE,MAAM,UAAU,SAAS,OAAO;AAAA,QAClC,EAAE,MAAM,QAAQ,SAAS,YAAY,EAAE;AAAA,MACzC;AAAA,MACA,EAAE,SAAS,IAAI,QAAQ;AAAA,IACzB;AACA,eAAW,QAAQ,MAAM,KAAK,MAAM,IAAI,EAAG,QAAO,KAAK,OAAO,IAAI;AAAA,EACpE,SAAS,KAAK;AACZ,WAAO,MAAM,0BAA0B,eAAe,QAAQ,IAAI,UAAU,OAAO,GAAG,EAAE;AACxF,WAAO;AAAA,MACL;AAAA,IACF;AAAA,EACF;AACF;","names":[]}