contextdevkit 1.8.0

package/templates/contextkit/runtime/providers/media/nano-banana.mjs

@@ -0,0 +1,110 @@
+/**
+ * Nano Banana — image generation via Google AI Studio's Imagen API
+ * (ADR-0024).
+ *
+ * Authentication: a single API key in `GOOGLE_AI_API_KEY` (get one at
+ * https://aistudio.google.com/apikey). The adapter shells out to
+ * `node:fetch` — no Google SDK.
+ *
+ * Pricing (dated 2026-06-02 — verify at https://ai.google.dev/pricing):
+ *   Imagen 3 fast:     ~$0.020 per image
+ *   Imagen 3 standard: ~$0.040 per image
+ *   The adapter charges the standard floor; the real bill is on Google.
+ *
+ * Model id is configurable via `options.model`; default is the most
+ * capable image model at write time.
+ */
+import { writeFileSync, mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+import {
+  MediaProviderError, MEDIA_ERROR_CODES,
+  assertCredentials, noteCostOrThrow,
+} from './_adapter.mjs';
+
+export const id = 'nano-banana';
+export const kind = 'image';
+export const envVar = 'GOOGLE_AI_API_KEY';
+export const requiredEnv = ['GOOGLE_AI_API_KEY'];
+
+const DEFAULT_MODEL = 'imagen-3.0-generate-002';
+const COST_ESTIMATE_USD = 0.04;
+const ENDPOINT = (model) => `https://generativelanguage.googleapis.com/v1beta/models/${model}:predict`;
+
+/**
+ * Generate an image and write it to disk.
+ *
+ * @param {object} input
+ * @param {string} input.prompt           required
+ * @param {string} input.outPath          required — absolute or cwd-relative
+ * @param {object} [input.options]
+ * @param {string} [input.options.model]          default DEFAULT_MODEL
+ * @param {string} [input.options.aspectRatio]    "1:1" | "16:9" | "9:16" | "3:4" | "4:3"
+ * @param {number} [input.options.sampleCount]    1..4 — only the first is written
+ * @returns {Promise<{ outPath, durationMs, costEstimateUsd, providerRequestId }>}
+ */
+export async function generate({ prompt, outPath, options = {} }) {
+  if (!prompt || typeof prompt !== 'string') {
+    throw new MediaProviderError(MEDIA_ERROR_CODES.BAD_INPUT, 'generate(): `prompt` is required');
+  }
+  if (!outPath || typeof outPath !== 'string') {
+    throw new MediaProviderError(MEDIA_ERROR_CODES.BAD_INPUT, 'generate(): `outPath` is required');
+  }
+  assertCredentials(requiredEnv);
+  noteCostOrThrow(COST_ESTIMATE_USD);
+
+  const model = options.model || DEFAULT_MODEL;
+  const body = {
+    instances: [{ prompt }],
+    parameters: {
+      sampleCount: Math.max(1, Math.min(4, options.sampleCount || 1)),
+      ...(options.aspectRatio ? { aspectRatio: options.aspectRatio } : {}),
+    },
+  };
+
+  const t0 = Date.now();
+  let resp;
+  try {
+    resp = await fetch(`${ENDPOINT(model)}?key=${encodeURIComponent(process.env[envVar])}`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(body),
+    });
+  } catch (err) {
+    throw new MediaProviderError(MEDIA_ERROR_CODES.PROVIDER_ERROR, `network error calling Imagen: ${err.message}`);
+  }
+  const providerRequestId = resp.headers.get('x-request-id') || undefined;
+
+  const raw = await resp.text();
+  let payload;
+  try { payload = JSON.parse(raw); } catch { payload = null; }
+
+  if (resp.status === 429) {
+    throw new MediaProviderError(MEDIA_ERROR_CODES.RATE_LIMIT, `Imagen rate-limited: ${raw.slice(0, 200)}`, { providerRequestId });
+  }
+  if (resp.status === 400 && /safety|policy/i.test(raw)) {
+    throw new MediaProviderError(MEDIA_ERROR_CODES.CONTENT_POLICY, `Imagen refused prompt for content policy: ${raw.slice(0, 200)}`, { providerRequestId });
+  }
+  if (!resp.ok) {
+    throw new MediaProviderError(MEDIA_ERROR_CODES.PROVIDER_ERROR, `Imagen returned ${resp.status}: ${raw.slice(0, 200)}`, { providerRequestId });
+  }
+
+  const pred = payload?.predictions?.[0];
+  const b64 = pred?.bytesBase64Encoded;
+  if (!b64) {
+    throw new MediaProviderError(MEDIA_ERROR_CODES.PROVIDER_ERROR, 'Imagen response missing predictions[0].bytesBase64Encoded', { providerRequestId });
+  }
+
+  try {
+    mkdirSync(dirname(outPath), { recursive: true });
+    writeFileSync(outPath, Buffer.from(b64, 'base64'));
+  } catch (err) {
+    throw new MediaProviderError(MEDIA_ERROR_CODES.IO, `failed to write image to ${outPath}: ${err.message}`);
+  }
+
+  return {
+    outPath,
+    durationMs: Date.now() - t0,
+    costEstimateUsd: COST_ESTIMATE_USD,
+    providerRequestId,
+  };
+}

package/templates/contextkit/runtime/providers/media/veo.mjs

@@ -0,0 +1,162 @@
+/**
+ * Veo — video generation via Google AI Studio's Veo API (ADR-0024).
+ *
+ * Authentication: same single API key as nano-banana — `GOOGLE_AI_API_KEY`.
+ *
+ * Pricing (dated 2026-06-02 — verify at https://ai.google.dev/pricing):
+ *   Veo 3 generate:  ~$0.50 per second of video
+ *   Typical 8 s clip: ~$4.00
+ *   The adapter charges per requested duration; the real bill is on Google.
+ *
+ * Veo's generation is *long-running*: the initial POST returns an
+ * operation name; the adapter polls until `done: true` then downloads
+ * the resulting video.
+ */
+import { writeFileSync, mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+import {
+  MediaProviderError, MEDIA_ERROR_CODES,
+  assertCredentials, noteCostOrThrow,
+} from './_adapter.mjs';
+
+export const id = 'veo';
+export const kind = 'video';
+export const envVar = 'GOOGLE_AI_API_KEY';
+export const requiredEnv = ['GOOGLE_AI_API_KEY'];
+
+const DEFAULT_MODEL = 'veo-3.0-generate-preview';
+const COST_PER_SECOND_USD = 0.50;
+const POLL_INTERVAL_MS = 5000;
+const POLL_TIMEOUT_MS = 5 * 60 * 1000;
+const PREDICT_ENDPOINT = (model) => `https://generativelanguage.googleapis.com/v1beta/models/${model}:predictLongRunning`;
+const OPERATION_ENDPOINT = (op) => `https://generativelanguage.googleapis.com/v1beta/${op}`;
+
+const sleep = (ms) => new Promise((res) => setTimeout(res, ms));
+
+/**
+ * Generate a video and write it to disk.
+ *
+ * @param {object} input
+ * @param {string} input.prompt
+ * @param {string} input.outPath
+ * @param {object} [input.options]
+ * @param {string} [input.options.model]          default DEFAULT_MODEL
+ * @param {number} [input.options.durationSeconds]  default 8 (Veo's typical max)
+ * @param {string} [input.options.aspectRatio]    "16:9" | "9:16"
+ * @returns {Promise<{ outPath, durationMs, costEstimateUsd, providerRequestId }>}
+ */
+export async function generate({ prompt, outPath, options = {} }) {
+  if (!prompt || typeof prompt !== 'string') {
+    throw new MediaProviderError(MEDIA_ERROR_CODES.BAD_INPUT, 'generate(): `prompt` is required');
+  }
+  if (!outPath || typeof outPath !== 'string') {
+    throw new MediaProviderError(MEDIA_ERROR_CODES.BAD_INPUT, 'generate(): `outPath` is required');
+  }
+  assertCredentials(requiredEnv);
+
+  const duration = Math.max(1, Math.min(60, options.durationSeconds || 8));
+  const estimate = duration * COST_PER_SECOND_USD;
+  noteCostOrThrow(estimate);
+
+  const model = options.model || DEFAULT_MODEL;
+  const apiKey = encodeURIComponent(process.env[envVar]);
+  const body = {
+    instances: [{ prompt }],
+    parameters: {
+      durationSeconds: duration,
+      ...(options.aspectRatio ? { aspectRatio: options.aspectRatio } : {}),
+    },
+  };
+
+  const t0 = Date.now();
+  let initResp;
+  try {
+    initResp = await fetch(`${PREDICT_ENDPOINT(model)}?key=${apiKey}`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(body),
+    });
+  } catch (err) {
+    throw new MediaProviderError(MEDIA_ERROR_CODES.PROVIDER_ERROR, `network error calling Veo: ${err.message}`);
+  }
+  const initRaw = await initResp.text();
+  let initPayload;
+  try { initPayload = JSON.parse(initRaw); } catch { initPayload = null; }
+  const providerRequestId = initResp.headers.get('x-request-id') || undefined;
+
+  if (initResp.status === 429) {
+    throw new MediaProviderError(MEDIA_ERROR_CODES.RATE_LIMIT, `Veo rate-limited: ${initRaw.slice(0, 200)}`, { providerRequestId });
+  }
+  if (initResp.status === 400 && /safety|policy/i.test(initRaw)) {
+    throw new MediaProviderError(MEDIA_ERROR_CODES.CONTENT_POLICY, `Veo refused prompt for content policy: ${initRaw.slice(0, 200)}`, { providerRequestId });
+  }
+  if (!initResp.ok) {
+    throw new MediaProviderError(MEDIA_ERROR_CODES.PROVIDER_ERROR, `Veo init returned ${initResp.status}: ${initRaw.slice(0, 200)}`, { providerRequestId });
+  }
+
+  const opName = initPayload?.name;
+  if (!opName) {
+    throw new MediaProviderError(MEDIA_ERROR_CODES.PROVIDER_ERROR, 'Veo response missing `name` (operation id)', { providerRequestId });
+  }
+
+  let opPayload = null;
+  const deadline = Date.now() + POLL_TIMEOUT_MS;
+  while (Date.now() < deadline) {
+    await sleep(POLL_INTERVAL_MS);
+    let pollResp;
+    try {
+      pollResp = await fetch(`${OPERATION_ENDPOINT(opName)}?key=${apiKey}`);
+    } catch (err) {
+      continue;
+    }
+    if (!pollResp.ok) continue;
+    const pollRaw = await pollResp.text();
+    try { opPayload = JSON.parse(pollRaw); } catch { continue; }
+    if (opPayload?.done) break;
+  }
+
+  if (!opPayload?.done) {
+    throw new MediaProviderError(MEDIA_ERROR_CODES.PROVIDER_ERROR, `Veo operation ${opName} did not complete within ${POLL_TIMEOUT_MS / 1000}s`, { providerRequestId });
+  }
+
+  if (opPayload.error) {
+    throw new MediaProviderError(MEDIA_ERROR_CODES.PROVIDER_ERROR, `Veo operation failed: ${JSON.stringify(opPayload.error).slice(0, 300)}`, { providerRequestId });
+  }
+
+  // Veo's response shape: either bytesBase64Encoded inline, or a URI to fetch.
+  const resp = opPayload?.response;
+  const sample = resp?.generatedVideos?.[0] || resp?.videos?.[0] || resp?.predictions?.[0];
+  const b64 = sample?.bytesBase64Encoded || sample?.video?.bytesBase64Encoded;
+  const uri = sample?.uri || sample?.video?.uri;
+  let bytes;
+  if (b64) {
+    bytes = Buffer.from(b64, 'base64');
+  } else if (uri) {
+    try {
+      const dl = await fetch(`${uri}${uri.includes('?') ? '&' : '?'}key=${apiKey}`);
+      if (!dl.ok) {
+        throw new MediaProviderError(MEDIA_ERROR_CODES.PROVIDER_ERROR, `Veo video download returned ${dl.status}`);
+      }
+      bytes = Buffer.from(await dl.arrayBuffer());
+    } catch (err) {
+      if (err instanceof MediaProviderError) throw err;
+      throw new MediaProviderError(MEDIA_ERROR_CODES.PROVIDER_ERROR, `Veo video download error: ${err.message}`);
+    }
+  } else {
+    throw new MediaProviderError(MEDIA_ERROR_CODES.PROVIDER_ERROR, 'Veo response missing video data (no bytesBase64Encoded or uri)');
+  }
+
+  try {
+    mkdirSync(dirname(outPath), { recursive: true });
+    writeFileSync(outPath, bytes);
+  } catch (err) {
+    throw new MediaProviderError(MEDIA_ERROR_CODES.IO, `failed to write video to ${outPath}: ${err.message}`);
+  }
+
+  return {
+    outPath,
+    durationMs: Date.now() - t0,
+    costEstimateUsd: estimate,
+    providerRequestId,
+  };
+}

package/templates/contextkit/runtime/providers/review/_adapter.mjs

@@ -0,0 +1,71 @@
+/**
+ * Review-provider adapter contract — ADR-0021.
+ *
+ * Each `*.mjs` file in this directory (except this one and `detect.mjs`) is a
+ * concrete adapter. An adapter is a thin shell around an external CLI binary
+ * the user already has installed (`gh`, `glab`, `bb`, `tea` …). No SDK
+ * dependencies. No HTTP clients. No network probes during detection.
+ *
+ * Five contract points (recorded inline so a new adapter author reads them
+ * before opening the file):
+ *
+ *   1. No SDK dependency. Adapters `child_process.spawn` their CLI.
+ *   2. `detectsRemote` is a pure function over the `origin` URL.
+ *   3. `createPullRequest` returns `{ url, number }` or throws ProviderError
+ *      with `code` and a human-readable `message`.
+ *   4. A missing CLI is a refusal, not a fallback. No silent degradation.
+ *   5. The selected adapter is recorded in `contextkit/config.json` →
+ *      `providers.review`. `detect.mjs` auto-resolves on first use.
+ *
+ * Adapter shape (all five fields required):
+ *
+ *   export const id = 'gh';
+ *   export const cliBinary = 'gh';
+ *   export const detectsRemote = (remoteUrl) => /github\.com/.test(remoteUrl);
+ *   export async function createPullRequest({ title, body, baseBranch }) { … }
+ *   export async function listOpenReviewComments({ prNumber }) { … }
+ *   export async function postReviewComment({ prNumber, body }) { … }
+ *
+ * Additions to the contract require an ADR-style paragraph in this file and
+ * a matching selfcheck assertion. The current surface is the minimum useful.
+ */
+
+/**
+ * Typed error every adapter throws on a failure path.
+ *
+ * @param {string} code     short stable code (e.g. 'CLI_MISSING', 'AUTH', 'REMOTE_REJECTED')
+ * @param {string} message  human-readable message (no stack-leaking)
+ */
+export class ProviderError extends Error {
+  constructor(code, message) {
+    super(message);
+    this.name = 'ProviderError';
+    this.code = code;
+  }
+}
+
+/**
+ * Validate the shape of an adapter module. Used by selfcheck and by
+ * `detect.mjs` before treating a discovered file as a real adapter.
+ *
+ * @param {object} mod  the imported module
+ * @returns {{ ok: true } | { ok: false, reasons: string[] }}
+ */
+export function validateAdapter(mod) {
+  const reasons = [];
+  if (typeof mod.id !== 'string' || mod.id.length === 0) {
+    reasons.push('missing or empty `id` export');
+  }
+  if (typeof mod.cliBinary !== 'string' || mod.cliBinary.length === 0) {
+    reasons.push('missing or empty `cliBinary` export');
+  }
+  if (typeof mod.detectsRemote !== 'function') {
+    reasons.push('missing `detectsRemote(remoteUrl)` export');
+  }
+  for (const fn of ['createPullRequest', 'listOpenReviewComments', 'postReviewComment']) {
+    if (typeof mod[fn] !== 'function') {
+      reasons.push(`missing async \`${fn}(...)\` export`);
+    }
+  }
+  return reasons.length === 0 ? { ok: true } : { ok: false, reasons };
+}

package/templates/contextkit/runtime/providers/review/detect.mjs

@@ -0,0 +1,115 @@
+/**
+ * Resolve which review-provider adapter to use for the current repo — ADR-0021.
+ *
+ * Order:
+ *   1. `contextkit/config.json` → `providers.review` (if set, win).
+ *   2. Auto-detect from `git remote get-url origin` by asking each adapter's
+ *      `detectsRemote`. Records the resolution back to `config.json`.
+ *   3. Refuse with a clear error if nothing matches. No silent fallback.
+ *
+ * Zero deps. The adapter modules themselves are zero-dep (they shell out to
+ * the user's CLI).
+ */
+import { spawnSync } from 'node:child_process';
+import { readFileSync, writeFileSync, readdirSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { validateAdapter, ProviderError } from './_adapter.mjs';
+import { PLATFORM_DIR } from '../../config/paths.mjs';
+
+const here = dirname(fileURLToPath(import.meta.url));
+
+function readOriginUrl(cwd) {
+  const result = spawnSync('git', ['remote', 'get-url', 'origin'], {
+    cwd,
+    encoding: 'utf8',
+    shell: false,
+  });
+  if (result.status !== 0) return null;
+  return (result.stdout || '').trim() || null;
+}
+
+function loadAdapterModules() {
+  const files = readdirSync(here)
+    .filter(name => name.endsWith('.mjs'))
+    .filter(name => !name.startsWith('_'))
+    .filter(name => name !== 'detect.mjs');
+  return Promise.all(
+    files.map(async (file) => {
+      const url = pathToFileURL(join(here, file)).href;
+      const mod = await import(url);
+      const verdict = validateAdapter(mod);
+      if (!verdict.ok) {
+        throw new ProviderError(
+          'BAD_ADAPTER',
+          `adapter ${file} failed contract validation: ${verdict.reasons.join('; ')}`,
+        );
+      }
+      return { file, mod };
+    }),
+  );
+}
+
+function readConfig(configPath) {
+  try {
+    const raw = readFileSync(configPath, 'utf8').replace(/^/, '');
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+
+function writeConfig(configPath, config) {
+  try {
+    writeFileSync(configPath, JSON.stringify(config, null, 2) + '\n', 'utf8');
+  } catch {
+    /* best-effort — do not break the calling command on a config-write race */
+  }
+}
+
+/**
+ * Resolve the review-provider adapter for `cwd`.
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.cwd]         project root (defaults to process.cwd())
+ * @param {string} [opts.configPath]  override path to contextkit/config.json
+ * @returns {Promise<{ id: string, source: 'config' | 'detected', adapter: object }>}
+ */
+export async function resolveAdapter({ cwd = process.cwd(), configPath } = {}) {
+  const resolvedConfigPath = configPath || join(cwd, PLATFORM_DIR, 'config.json');
+  const config = readConfig(resolvedConfigPath) || {};
+  const adapters = await loadAdapterModules();
+
+  const fromConfig = config?.providers?.review;
+  if (fromConfig) {
+    const hit = adapters.find(a => a.mod.id === fromConfig);
+    if (!hit) {
+      throw new ProviderError(
+        'CONFIGURED_ADAPTER_NOT_FOUND',
+        `contextkit/config.json names review provider "${fromConfig}" but no matching adapter is installed`,
+      );
+    }
+    return { id: hit.mod.id, source: 'config', adapter: hit.mod };
+  }
+
+  const originUrl = readOriginUrl(cwd);
+  if (!originUrl) {
+    throw new ProviderError(
+      'NO_ORIGIN',
+      'no `origin` remote configured — cannot auto-detect a review provider. Set `providers.review` in contextkit/config.json.',
+    );
+  }
+  const detected = adapters.find(a => a.mod.detectsRemote(originUrl));
+  if (!detected) {
+    throw new ProviderError(
+      'NO_MATCHING_ADAPTER',
+      `no review adapter matched origin "${originUrl}". Set \`providers.review\` in contextkit/config.json or add an adapter to contextkit/runtime/providers/review/.`,
+    );
+  }
+
+  config.providers = config.providers || {};
+  config.providers.review = detected.mod.id;
+  writeConfig(resolvedConfigPath, config);
+
+  return { id: detected.mod.id, source: 'detected', adapter: detected.mod };
+}

package/templates/contextkit/runtime/providers/review/gh.mjs

@@ -0,0 +1,103 @@
+/**
+ * GitHub adapter for the review-provider contract — ADR-0021.
+ *
+ * Shells out to the `gh` CLI. The user is expected to have authenticated
+ * via `gh auth login` before any command that hits the network. We do not
+ * store credentials.
+ */
+import { spawnSync } from 'node:child_process';
+import { ProviderError } from './_adapter.mjs';
+
+export const id = 'gh';
+export const cliBinary = 'gh';
+
+/**
+ * Pure detection from the `origin` URL — no network call.
+ *
+ * @param {string} remoteUrl  output of `git remote get-url origin`
+ * @returns {boolean}
+ */
+export const detectsRemote = (remoteUrl) => {
+  if (typeof remoteUrl !== 'string') return false;
+  return /github\.com[:/]/.test(remoteUrl);
+};
+
+function runGh(args, { stdin } = {}) {
+  const result = spawnSync('gh', args, {
+    input: stdin,
+    encoding: 'utf8',
+    shell: false,
+  });
+  if (result.error && result.error.code === 'ENOENT') {
+    throw new ProviderError(
+      'CLI_MISSING',
+      '`gh` CLI not found on PATH. Install from https://cli.github.com/ or switch `providers.review` in contextkit/config.json.',
+    );
+  }
+  if (result.status !== 0) {
+    const stderr = (result.stderr || '').trim();
+    const code = /not authenticated/i.test(stderr) ? 'AUTH'
+      : /not found/i.test(stderr) ? 'NOT_FOUND'
+      : 'REMOTE_REJECTED';
+    throw new ProviderError(code, `gh ${args.join(' ')} failed: ${stderr || result.status}`);
+  }
+  return result.stdout || '';
+}
+
+/**
+ * Create a pull request on GitHub.
+ *
+ * @param {{ title: string, body: string, baseBranch?: string }} input
+ * @returns {Promise<{ url: string, number: number }>}
+ */
+export async function createPullRequest({ title, body, baseBranch }) {
+  if (!title) throw new ProviderError('BAD_INPUT', 'createPullRequest: `title` is required');
+  const args = ['pr', 'create', '--title', title, '--body-file', '-'];
+  if (baseBranch) args.push('--base', baseBranch);
+  const stdout = runGh(args, { stdin: body || '' });
+  const url = stdout.trim().split('\n').filter(Boolean).pop() || '';
+  const match = /\/pull\/(\d+)/.exec(url);
+  if (!match) {
+    throw new ProviderError('PARSE', `could not parse PR number from gh output: ${stdout}`);
+  }
+  return { url, number: Number(match[1]) };
+}
+
+/**
+ * List open review comments on a PR.
+ *
+ * @param {{ prNumber: number }} input
+ * @returns {Promise<Array<{ id: number, body: string, path?: string, line?: number }>>}
+ */
+export async function listOpenReviewComments({ prNumber }) {
+  if (!Number.isInteger(prNumber)) {
+    throw new ProviderError('BAD_INPUT', 'listOpenReviewComments: `prNumber` must be an integer');
+  }
+  const stdout = runGh(['api', `repos/{owner}/{repo}/pulls/${prNumber}/comments`]);
+  try {
+    const raw = JSON.parse(stdout);
+    return raw.map(c => ({
+      id: c.id,
+      body: c.body,
+      path: c.path,
+      line: c.line ?? c.original_line ?? null,
+    }));
+  } catch (e) {
+    throw new ProviderError('PARSE', `gh returned non-JSON for review comments: ${e.message}`);
+  }
+}
+
+/**
+ * Post a top-level review comment on a PR.
+ *
+ * @param {{ prNumber: number, body: string }} input
+ * @returns {Promise<{ ok: true }>}
+ */
+export async function postReviewComment({ prNumber, body }) {
+  if (!Number.isInteger(prNumber)) {
+    throw new ProviderError('BAD_INPUT', 'postReviewComment: `prNumber` must be an integer');
+  }
+  if (!body) throw new ProviderError('BAD_INPUT', 'postReviewComment: `body` is required');
+  runGh(['pr', 'comment', String(prNumber), '--body-file', '-'], { stdin: body });
+  return { ok: true };
+}