@koda-sl/baker-bridge 0.68.1 → 0.68.3

package/plugins/reports/skills/build/references/report-contracts.md

@@ -1,103 +0,0 @@
-# Report Contracts
-
-Use this reference when creating or repairing Baker company Reports.
-
-## Ownership
-
-- Convex owns Report lifecycle and dashboard listing state.
-- Scaffold owns report files and Nitro runtime behavior.
-- The sandbox supervisor builds `reports` through the locked `reports-build` wrapper and serves promoted built Nitro output on port `3001`; do not use `nitro dev` for Reports.
-- Dashboard owns visibility and links to the sandbox `reportsHost`.
-- V1 reports are internal dashboard/sandbox live assets, not public generated-site deployment output.
-
-## Required files
-
-For slug `{slug}`:
-
-```text
-reports/server/routes/reports/data/{slug}.get.ts
-reports/public/{slug}/index.html
-reports/public/{slug}/_definition.md
-```
-
-Slug format: lowercase alphanumeric words separated by hyphens.
-
-## `_definition.md`
-
-Frontmatter is the metadata contract consumed by watcher/upsert.
-
-```markdown
----
-title: "Campaign Performance Weekly"
-description: "Weekly spend, conversions, and cost per lead by campaign"
-status: draft
----
-```
-
-Allowed statuses: `draft`, `active`, `error`, `archived`. Optional `errorMessage` is surfaced with error report definitions.
-
-Keep frontmatter minimal and put business context, data-source notes, refresh notes, evolution, and source breadcrumbs in the Markdown body. Set `status: active` only when the endpoint, dashboard, metadata, and live smoke test are ready.
-
-## Endpoint pattern
-
-Default to `runReportBaker(event, args)` so `?fresh=true` maps to Baker `--no-cache`.
-
-```ts
-import { defineHandler } from "nitro";
-import { runReportBaker } from "../../../utils/baker.ts";
-
-export default defineHandler(async (event) => {
-  const start = Date.now();
-  const result = await runReportBaker<Row[]>(event, ["ads", "google", "query", "--preset", "campaign-performance"]);
-
-  if (!result.ok) {
-    return { ok: false, error: result.error };
-  }
-
-  return {
-    ok: true,
-    data: result.data,
-    meta: { durationMs: Date.now() - start, cached: result.cached ?? false },
-  };
-});
-```
-
-For multi-call orchestration, read `freshRequested(event)` once and pass `{ noCache }` to every cacheable Baker call. Do not pass `noCache` to Baker commands that do not support `--no-cache`. Refresh invalidation is whole-report: `/reports/{slug}/?fresh=true` propagates to same-origin `/reports/data/{slug}` fetches, and Baker CLI cache is bypassed with `--no-cache`; HTTP responses remain `no-store`.
-
-Google Ads query rows arrive from Baker CLI with flat dotted keys such as `campaign.name`, `campaign.advertising_channel_type`, `metrics.cost_micros`, and `segments.conversion_action_name`. `runReportBaker` preserves those flat keys and explicitly adds nested aliases for compatibility with existing reports. In new or repaired Google Ads report endpoints, adapt rows with `googleAdsRow(raw)` from `reports/server/utils/googleAdsRow.ts` before returning report data; the adapter preserves the input row as `row.raw`. Do not use top-level aliases such as `row.name` or `row.spend`; derive those explicitly from the Google Ads fields.
-
-## HTML dashboard pattern
-
-The page is served by the generic route at `/reports/{slug}/`, which injects a whole-report Refresh control. Keep dashboard JS simple:
-
-- Fetch `/reports/data/{slug}` without manually appending `fresh=true`.
-- Let the injected bootstrap propagate `?fresh=true` from the page URL to same-origin report fetches.
-- Do not implement a second custom refresh button unless the user explicitly asks for custom UX.
-- Keep chart data available in tables for accessibility.
-
-## Validation
-
-Run from the scaffold harness root:
-
-```bash
-pnpm run verify
-```
-
-Do not invoke `__tooling__/lefthook/base/validate-reports.mjs` directly. `pnpm run verify` is the supported contract and runs report validation with the correct working directory, plus typecheck and Nitro build checks.
-
-The report validator checks report slug shape, `_definition.md` frontmatter/status, required dashboard files, active report endpoints, and legacy dashboard fetches. Legacy `/reports/{slug}` data fetches/routes must be fixed manually to use `/reports/data/{slug}`. The validator reports these issues but does not mutate source files or execute report data endpoints.
-
-Before marking a new or active report done, smoke-test the built runtime:
-
-```bash
-node __tooling__/scripts/smoke-reports-runtime.mjs --slug {slug}
-```
-
-In a running company sandbox, the supervisor serves Reports at port `3001`, so direct probes are also valid:
-
-```bash
-curl -fsS http://localhost:3001/reports/{slug}/ >/tmp/report.html
-curl -fsS http://localhost:3001/reports/data/{slug} | tee /tmp/report-data.json
-```
-
-Endpoint `{ "ok": false, ... }`, visible dashboard error cards, failed Baker CLI calls, provider API errors, or smoke script failures are blocking. Fix the endpoint/query and rerun the smoke test before claiming success.

package/plugins/reports/skills/build/scripts/report-paths.mjs

@@ -1,19 +0,0 @@
-const REPORT_SLUG_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
-
-function titleFromSlug(slug) {
-  return slug.replace(/-/g, " ").replace(/\b\w/g, (letter) => letter.toUpperCase());
-}
-
-function paths(slug) {
-  return {
-    definition: `reports/public/${slug}/_definition.md`,
-    dashboard: `reports/public/${slug}/index.html`,
-    endpoint: `reports/server/routes/reports/data/${slug}.get.ts`,
-  };
-}
-
-export const ReportFileContract = {
-  isValidSlug: (slug) => REPORT_SLUG_RE.test(slug),
-  titleFromSlug,
-  paths,
-};

package/plugins/reports/skills/build/scripts/scaffold-report.mjs

@@ -1,108 +0,0 @@
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { dirname, join, resolve } from "node:path";
-import { fileURLToPath, pathToFileURL } from "node:url";
-import { ReportFileContract } from "./report-paths.mjs";
-
-function endpointTemplate() {
-  return `import { defineHandler } from "nitro";
-import { runReportBaker } from "../../../utils/baker.ts";
-
-export default defineHandler(async (event) => {
-  const start = Date.now();
-
-  // TODO: replace with the Baker command for this report.
-  // runReportBaker maps ?fresh=true to Baker --no-cache for commands that support it.
-  const result = await runReportBaker(event, ["TODO", "replace", "with", "baker", "args"]);
-
-  if (!result.ok) {
-    return { ok: false, error: result.error };
-  }
-
-  return {
-    ok: true,
-    data: result.data,
-    meta: {
-      durationMs: Date.now() - start,
-      cached: result.cached ?? false,
-    },
-  };
-});
-`;
-}
-
-const scriptDir = dirname(fileURLToPath(import.meta.url));
-
-function readTemplate(name) {
-  return readFileSync(resolve(scriptDir, "..", "templates", name), "utf8");
-}
-
-const TEMPLATE_TOKEN_RE = /__[A-Z0-9_]+__/g;
-
-function renderTemplate(template, values) {
-  let rendered = template;
-  for (const [key, value] of Object.entries(values)) {
-    rendered = rendered.replaceAll(`__${key.toUpperCase()}__`, value);
-  }
-
-  const unresolved = rendered.match(TEMPLATE_TOKEN_RE);
-  if (unresolved) {
-    throw new Error(`Unresolved template token(s): ${[...new Set(unresolved)].join(", ")}`);
-  }
-
-  return rendered;
-}
-
-function pageTemplate(slug, title) {
-  return renderTemplate(readTemplate("report-index.html"), { slug, title });
-}
-
-function definitionTemplate(slug, title, today = new Date().toISOString().slice(0, 10)) {
-  return renderTemplate(readTemplate("report-definition.md"), { slug, title, today });
-}
-
-export function createReportFiles(slug, projectRoot = process.cwd()) {
-  if (!ReportFileContract.isValidSlug(slug)) {
-    throw new Error(`Invalid slug "${slug}". Must match /^[a-z0-9]+(-[a-z0-9]+)*$/`);
-  }
-
-  const paths = ReportFileContract.paths(slug);
-  const pageDir = join(projectRoot, "reports", "public", slug);
-  const dashboardPath = join(pageDir, "index.html");
-  const endpointPath = resolve(projectRoot, paths.endpoint);
-  const definitionPath = resolve(projectRoot, paths.definition);
-
-  if (existsSync(pageDir)) {
-    throw new Error(`Dashboard page already exists: ${pageDir}`);
-  }
-
-  if (existsSync(endpointPath)) {
-    throw new Error(`Endpoint already exists: ${endpointPath}`);
-  }
-
-  const title = ReportFileContract.titleFromSlug(slug);
-
-  mkdirSync(pageDir, { recursive: true });
-  mkdirSync(dirname(endpointPath), { recursive: true });
-  writeFileSync(dashboardPath, pageTemplate(slug, title));
-  writeFileSync(definitionPath, definitionTemplate(slug, title));
-  writeFileSync(endpointPath, endpointTemplate());
-
-  return { slug, files: [endpointPath, dashboardPath, definitionPath] };
-}
-
-const isDirectRun = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
-if (isDirectRun) {
-  const slug = process.argv[2];
-
-  if (!slug) {
-    console.error("Usage: node scaffold-report.mjs <slug>");
-    process.exit(1);
-  }
-
-  try {
-    process.stdout.write(`${JSON.stringify(createReportFiles(slug), null, 2)}\n`);
-  } catch (error) {
-    process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
-    process.exit(1);
-  }
-}

package/plugins/reports/skills/build/templates/report-definition.md

@@ -1,22 +0,0 @@
----
-title: "__TITLE__"
-description: ""
-status: draft
----
-
-## Why This Report Exists
-
-TODO: describe the question this report answers and the decision it supports.
-
-## Data and Refresh
-
-- **Data endpoint**: TODO: list the Baker commands or local data sources used by `/reports/data/__SLUG__`.
-- **Refresh policy**: manual via the injected Refresh control using `?fresh=true`; smoke with the built Reports runtime before marking active.
-
-## Evolution
-
-- __TODAY__: created
-
-## Sources
-
-- TODO: link to personas, campaigns, audits, competitors, or docs that motivated this report.

package/plugins/reports/skills/build/templates/report-index.html

@@ -1,20 +0,0 @@
-<!DOCTYPE html>
-<html lang="en">
-<head>
-  <meta charset="UTF-8">
-  <meta name="viewport" content="width=device-width, initial-scale=1.0">
-  <title>__TITLE__</title>
-</head>
-<body>
-  <main>
-    <h1>__TITLE__</h1>
-    <p>
-      TODO: replace this placeholder with the real Report Dashboard authored for this company.
-    </p>
-    <p>
-      Fetch report data from <code>/reports/data/__SLUG__</code>. The reports runtime serves this file at
-      <code>/reports/__SLUG__/</code> and injects the refresh control.
-    </p>
-  </main>
-</body>
-</html>