@decocms/blocks-cli 7.0.0

package/scripts/migrate.ts

@@ -0,0 +1,282 @@
+#!/usr/bin/env tsx
+
+/**
+ * Migration Script: Fresh/Deno/Preact → TanStack Start/React/Cloudflare Workers
+ *
+ * Converts a Deco storefront from the old Fresh/Deno stack to the new TanStack Start stack.
+ * Part of the @decocms/start framework — run from a site's root directory.
+ *
+ * Usage (from your Fresh site directory):
+ *   npx -p @decocms/start deco-migrate [options]
+ *
+ * Options:
+ *   --source <dir>    Source directory (default: current directory)
+ *   --dry-run         Preview changes without writing files
+ *   --verbose         Show detailed output
+ *   --help            Show this help message
+ *
+ * Phases:
+ *   1. Analyze  — Scan source site, categorize files, detect patterns
+ *   2. Scaffold — Create target structure (configs, routes, infra files)
+ *   3. Transform — Convert source files (imports, JSX, Fresh APIs, Deno-isms, Tailwind)
+ *   4. Cleanup  — Delete old artifacts, move static → public
+ *   5. Report   — Generate MIGRATION_REPORT.md with findings
+ *   6. Verify   — Smoke test the migrated output
+ */
+
+import { execSync } from "node:child_process";
+import * as path from "node:path";
+import { banner, green, red, stat, yellow } from "./migrate/colors";
+import { loadConfig, validateConfig } from "./migrate/config";
+import { analyze } from "./migrate/phase-analyze";
+import { cleanup } from "./migrate/phase-cleanup";
+import { cleanupAudit } from "./migrate/phase-cleanup-audit";
+import { compile } from "./migrate/phase-compile";
+import { report } from "./migrate/phase-report";
+import { scaffold } from "./migrate/phase-scaffold";
+import { transform } from "./migrate/phase-transform";
+import { verify } from "./migrate/phase-verify";
+import { detectSourceLayout, explainNonClassicLayout } from "./migrate/source-layout";
+import { createContext, logPhase } from "./migrate/types";
+
+function parseArgs(args: string[]): {
+  source: string;
+  dryRun: boolean;
+  verbose: boolean;
+  help: boolean;
+  strict: boolean;
+  withBuild: boolean;
+  noCompile: boolean;
+  noCleanupAudit: boolean;
+} {
+  let source = ".";
+  let dryRun = false;
+  let verbose = false;
+  let help = false;
+  let strict = false;
+  let withBuild = false;
+  let noCompile = false;
+  let noCleanupAudit = false;
+
+  for (let i = 0; i < args.length; i++) {
+    switch (args[i]) {
+      case "--source":
+        source = args[++i];
+        break;
+      case "--dry-run":
+        dryRun = true;
+        break;
+      case "--verbose":
+        verbose = true;
+        break;
+      case "--strict":
+        strict = true;
+        break;
+      case "--with-build":
+        withBuild = true;
+        break;
+      case "--no-compile":
+        noCompile = true;
+        break;
+      case "--no-cleanup-audit":
+        noCleanupAudit = true;
+        break;
+      case "--help":
+      case "-h":
+        help = true;
+        break;
+    }
+  }
+
+  return {
+    source,
+    dryRun,
+    verbose,
+    help,
+    strict,
+    withBuild,
+    noCompile,
+    noCleanupAudit,
+  };
+}
+
+function showHelp() {
+  console.log(`
+  @decocms/start — Migration Script: Fresh/Deno → TanStack Start
+
+  Usage:
+    npx -p @decocms/start deco-migrate [options]
+
+  Options:
+    --source <dir>        Source directory (default: .)
+    --dry-run             Preview changes without writing files
+    --verbose             Show detailed output for every file
+    --strict              Fail (exit 2) when typecheck/build report errors
+    --with-build          Also run \`vite build\` after typecheck (slower)
+    --no-compile          Skip the post-bootstrap compile phase entirely
+    --no-cleanup-audit    Skip the post-migration cleanup audit (run separately
+                          via \`deco-post-cleanup\` if needed)
+    --help, -h            Show this help message
+
+  Examples:
+    npx -p @decocms/start deco-migrate --dry-run --verbose
+    npx -p @decocms/start deco-migrate --source ./my-site
+    npx -p @decocms/start deco-migrate --strict --with-build
+    npx -p @decocms/start deco-migrate
+  `);
+}
+
+async function main() {
+  const opts = parseArgs(process.argv.slice(2));
+
+  if (opts.help) {
+    showHelp();
+    process.exit(0);
+  }
+
+  const sourceDir = path.resolve(opts.source);
+
+  banner("@decocms/start — Migrate: Fresh/Deno → TanStack Start");
+  stat("Source", sourceDir);
+  stat("Mode", opts.dryRun ? yellow("DRY RUN") : green("EXECUTE"));
+  stat("Verbose", opts.verbose ? "yes" : "no");
+
+  // Load optional per-site config from `.deco-migrate.config.json`. Drives
+  // section-conventions hardcoded lists today; future fields will tune
+  // import rewrites, scaffolding, etc.
+  const siteConfig = loadConfig(sourceDir);
+  if (siteConfig) {
+    validateConfig(siteConfig);
+    stat("Config", green(".deco-migrate.config.json (loaded)"));
+  }
+
+  const ctx = createContext(sourceDir, {
+    dryRun: opts.dryRun,
+    verbose: opts.verbose,
+    config: siteConfig,
+  });
+
+  // Phase 0: Source-layout detection (early-abort for unsupported layouts).
+  // The analyzer assumes a classic root layout (sections/, islands/, ...);
+  // running it on a modern src/ layout silently yields a near-empty
+  // migration. Detect-and-abort here so the user gets an actionable error
+  // before we touch any files.
+  const layout = detectSourceLayout(sourceDir);
+  if (layout !== "classic") {
+    console.error(red(`Error: ${layout} source layout`));
+    console.error("");
+    console.error(explainNonClassicLayout(layout, sourceDir));
+    process.exit(2);
+  }
+
+  try {
+    // Phase 1: Analyze source
+    analyze(ctx);
+
+    // Phase 2: Scaffold target structure
+    scaffold(ctx);
+
+    // Phase 3: Transform source files
+    transform(ctx);
+
+    // Phase 4: Cleanup old artifacts
+    cleanup(ctx);
+
+    // Phase 5: Generate report
+    report(ctx);
+
+    // Phase 6: Verify (smoke test)
+    const ok = verify(ctx);
+    if (!ok) {
+      process.exit(2);
+    }
+
+    // Phase 7: Bootstrap (install + generate)
+    if (!ctx.dryRun) {
+      bootstrap(ctx);
+    }
+
+    // Phase 8: Compile (typecheck + optional build)
+    // Skipped in dry-run, when --no-compile is passed, or when bootstrap
+    // didn't install dependencies (handled inside `compile`).
+    if (!opts.noCompile) {
+      const compileResult = compile(ctx, {
+        strict: opts.strict,
+        withBuild: opts.withBuild,
+      });
+      if (compileResult.shouldFail) {
+        process.exit(2);
+      }
+    }
+
+    // Phase 9: Post-migration cleanup audit
+    // Read-only scan that catches residual debt the migration script
+    // can't (or won't) fix. Always informational unless --strict is on,
+    // in which case warning-severity findings exit 2.
+    if (!opts.noCleanupAudit) {
+      const auditFailed = cleanupAudit(ctx, { strict: opts.strict });
+      if (auditFailed) {
+        process.exit(2);
+      }
+    }
+  } catch (error) {
+    console.error(`\n  ${red("Migration failed:")}`, error);
+    process.exit(1);
+  }
+}
+
+function bootstrap(ctx: { sourceDir: string }) {
+  logPhase("Bootstrap (install + generate)");
+
+  let failures = 0;
+  const run = (cmd: string, label: string, critical = false) => {
+    console.log(`  Running: ${label}...`);
+    try {
+      execSync(cmd, { cwd: ctx.sourceDir, stdio: "pipe" });
+      console.log(`  ${green("✓")} ${label}`);
+    } catch (e: any) {
+      failures++;
+      const icon = critical ? red("✗") : yellow("⚠");
+      console.log(`  ${icon} ${label} failed: ${e.message?.split("\n")[0]}`);
+      if (critical) {
+        console.log(`\n  ${red("Bootstrap aborted.")} Fix the error above and run manually.\n`);
+        return false;
+      }
+    }
+    return true;
+  };
+
+  // bun is the fleet-wide canonical package manager for decocms storefronts.
+  // We hardcode it here (instead of sniffing process.env.npm_execpath) so a
+  // freshly-migrated site always commits a bun.lock and never accidentally
+  // ships a package-lock.json that drifts vs bun.lock under CF Workers Builds.
+  // See MIGRATION_TOOLING_PLAN.md and the package-json template for the
+  // matching `packageManager` field that pins the version.
+  const pm = "bun";
+  if (!run(`${pm} install`, "Install dependencies", true)) return;
+  run("bunx tsx node_modules/@decocms/start/scripts/generate-blocks.ts", "Generate CMS blocks");
+  // generate-invoke emits src/server/invoke.gen.ts with top-level
+  // createServerFn declarations + the forwardResponseCookies bridge that
+  // propagates VTEX Set-Cookie headers (orderFormId, segment, sc…) to the
+  // browser. Without this file, the site falls back to the proxy
+  // `~/runtime.ts` route which hits /deco/invoke and used to drop cookies,
+  // making the cart appear empty at /checkout after addItemToCart. The
+  // upstream invoke handler now also forwards cookies correctly, but
+  // running the generator gives every freshly-migrated site the canonical
+  // RPC path so VTEX hooks (useCart, useUser, useWishlist) work end-to-end.
+  run(
+    "bunx tsx node_modules/@decocms/start/scripts/generate-invoke.ts",
+    "Generate VTEX invoke server functions",
+  );
+  run("bunx tsr generate", "Generate TanStack routes");
+
+  if (failures > 0) {
+    console.log(
+      `\n  ${yellow("Bootstrap completed with warnings.")} Check errors above before running dev.\n`,
+    );
+  } else {
+    console.log(`\n  ${green("Ready!")} Run \`${pm} run dev\` to start the dev server.\n`);
+  }
+}
+
+main();

package/scripts/smoke-otlp-errorlog.ts

@@ -0,0 +1,46 @@
+/**
+ * One-shot smoke: emit an error log record through
+ * `createOtlpHttpLogAdapter` and POST it to the deployed
+ * `deco-otel-ingest` `/v1/logs`. Verifies the wire format end-to-end.
+ *
+ * Run with: `npx tsx scripts/smoke-otlp-errorlog.ts`
+ * Expected output: `{"inserted":1}` echoed by the ingestor.
+ */
+
+import { createOtlpHttpLogAdapter } from "@decocms/blocks/sdk/otelHttpLog";
+
+async function main() {
+  const sink = createOtlpHttpLogAdapter({
+    endpoint: "https://deco-otel-ingest.deco-cx.workers.dev/v1/logs",
+    resourceAttributes: {
+      "service.name": "smoke-otlp-errorlog",
+      "service.version": "5.1.1-dev",
+      "deco.runtime.version": "5.1.1-dev",
+      "deployment.environment": "smoke",
+    },
+    scopeName: "@decocms/start",
+    scopeVersion: "5.1.1-dev",
+    minFlushIntervalMs: 0,
+    onError: (kind, err) => {
+      console.error(`[smoke] onError(${kind}):`, err);
+      process.exitCode = 1;
+    },
+  });
+
+  sink.adapter.log("error", "smoke error from otelHttpLog exporter", {
+    stage: "smoke",
+    reason: "wire-format-validation",
+    durationMs: 27,
+    ok: false,
+  });
+
+  console.log("pending records:", sink.pendingRecordCount());
+
+  await sink.flush();
+  console.log("flush complete");
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

package/scripts/smoke-otlp-meter.ts

@@ -0,0 +1,48 @@
+/**
+ * One-shot smoke: serialize a real OTLP/HTTP metrics payload through the
+ * `createOtlpHttpMeterAdapter` exporter and POST it to the deployed
+ * `deco-otel-ingest` `/v1/metrics`. Verifies the wire format end-to-end
+ * (exporter → ingestor → ClickHouse) without standing up a Worker.
+ *
+ * Not part of the standard test suite — committed for repeatability.
+ * Run with:
+ *
+ *   npx tsx scripts/smoke-otlp-meter.ts
+ *
+ * Expected output: `{"inserted":{"sum":1,"gauge":1,"histogram":1}}`.
+ */
+
+import { createOtlpHttpMeterAdapter } from "@decocms/blocks/sdk/otelHttpMeter";
+
+async function main() {
+  const meter = createOtlpHttpMeterAdapter({
+    endpoint: "https://deco-otel-ingest.deco-cx.workers.dev/v1/metrics",
+    resourceAttributes: {
+      "service.name": "smoke-otlp-meter",
+      "service.version": "5.1.1-dev",
+      "deco.runtime.version": "5.1.1-dev",
+      "deployment.environment": "smoke",
+    },
+    scopeName: "@decocms/start",
+    scopeVersion: "5.1.1-dev",
+    minFlushIntervalMs: 0,
+    onError: (kind, err) => {
+      console.error(`[smoke] onError(${kind}):`, err);
+      process.exitCode = 1;
+    },
+  });
+
+  meter.counterInc("deco.http.requests", 1, { method: "GET", status_class: "2xx" });
+  meter.gaugeSet("deco.metrics.flush.buffer_size", 1, { kind: "smoke" });
+  meter.histogramRecord("outbound_request_duration_ms", 27, { provider: "smoke", status_class: "2xx" });
+
+  console.log("pending datapoints:", meter.pendingDatapointCount());
+
+  await meter.flush();
+  console.log("flush complete");
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

package/scripts/sync-blocks-to-kv.ts

@@ -0,0 +1,153 @@
+#!/usr/bin/env tsx
+/**
+ * CI fast-deploy content sync: push the site's current decofile to KV when
+ * content changed, WITHOUT a worker redeploy.
+ *
+ * Because the runtime swaps whole snapshots (not per-block), this always writes
+ * the FULL current decofile (`decofile:current`) and bumps `index:revision`.
+ * The default mode first checks whether any `.deco/blocks/*.json` changed since
+ * a base ref — if nothing changed, it exits 0 without writing (the "content
+ * unchanged → nothing to do" path). `--all` skips that check and always syncs
+ * (use post-deploy for bootstrap/paranoia).
+ *
+ * After writing, it optionally purges the edge cache for the changed pages.
+ *
+ * Usage (in CI, on push to main):
+ *   CF_ACCOUNT_ID=... CF_KV_NAMESPACE_ID=... CF_API_TOKEN=... \
+ *     npx -p @decocms/start deco-sync-blocks-to-kv --write \
+ *       --since "$GITHUB_BEFORE" --purge-url https://site.example --purge-token "$PURGE_TOKEN"
+ *   # bootstrap (always write the whole snapshot):
+ *   ... deco-sync-blocks-to-kv --write --all
+ *
+ * Options:
+ *   --all                 Always sync (skip the git-diff content check)
+ *   --since <ref>         Base git ref for the diff (default: HEAD~1)
+ *   --blocks-dir <dir>    Input blocks dir (default: .deco/blocks)
+ *   --purge-url <origin>  Site origin to POST /_cache/purge after sync
+ *   --purge-token <tok>   Purge bearer token (or PURGE_TOKEN env)
+ *   --write               Perform writes (otherwise dry-run, exit 0)
+ *   --help, -h            Show this help
+ *
+ * Env: CF_ACCOUNT_ID, CF_KV_NAMESPACE_ID, CF_API_TOKEN (required with --write)
+ *
+ * Exit codes: 0 ok / no-op / dry-run; 2 error (bad dir, missing env, verify failed)
+ */
+
+import { execSync } from "node:child_process";
+import * as path from "node:path";
+import { createKvRestClient, kvConfigFromEnv } from "./lib/cf-kv-rest";
+import { buildSnapshot, verifySnapshotInKv, writeSnapshotToKv } from "./lib/kv-snapshot";
+import { readDecofileFromDir } from "./lib/read-decofile";
+import { changedBlockFiles, changedBlockKeys, purgePathsForChangedKeys } from "./lib/sync-helpers";
+
+function parseArgs(argv: string[]) {
+  const has = (f: string) => argv.includes(f);
+  const val = (f: string, d: string) => {
+    const i = argv.indexOf(f);
+    return i >= 0 && argv[i + 1] ? argv[i + 1] : d;
+  };
+  return {
+    help: has("--help") || has("-h"),
+    all: has("--all"),
+    write: has("--write"),
+    since: val("--since", "HEAD~1"),
+    blocksDir: val("--blocks-dir", ".deco/blocks"),
+    purgeUrl: val("--purge-url", ""),
+    purgeToken: val("--purge-token", process.env.PURGE_TOKEN ?? ""),
+  };
+}
+
+function gitChangedFiles(since: string, blocksDir: string): string[] {
+  const out = execSync(`git diff --name-only ${since} HEAD`, { encoding: "utf-8" });
+  return changedBlockFiles(out, blocksDir);
+}
+
+async function purgeCache(origin: string, token: string, paths: string[]): Promise<void> {
+  const res = await fetch(new URL("/_cache/purge", origin).toString(), {
+    method: "POST",
+    headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json" },
+    body: JSON.stringify({ paths }),
+  });
+  if (!res.ok) {
+    console.warn(`warning: purge failed: ${res.status} ${await res.text()}`);
+  } else {
+    console.log(`purged ${paths.length} path(s): ${paths.join(", ")}`);
+  }
+}
+
+async function main() {
+  const opts = parseArgs(process.argv.slice(2));
+  if (opts.help) {
+    console.log("Usage: deco-sync-blocks-to-kv [--all] [--since <ref>] [--write] [--purge-url <origin>]");
+    process.exit(0);
+  }
+
+  const blocksDir = path.resolve(process.cwd(), opts.blocksDir);
+  const blocksDirRel = opts.blocksDir;
+
+  // Decide whether there's anything to sync.
+  let changedKeys: string[] = [];
+  if (!opts.all) {
+    let changed: string[];
+    try {
+      changed = gitChangedFiles(opts.since, blocksDirRel);
+    } catch (e) {
+      console.error(`error: git diff failed: ${e instanceof Error ? e.message : String(e)}`);
+      process.exit(2);
+    }
+    if (changed.length === 0) {
+      console.log(`no ${blocksDirRel} changes since ${opts.since} — nothing to sync.`);
+      process.exit(0);
+    }
+    changedKeys = changedBlockKeys(changed);
+    console.log(`${changed.length} changed block file(s) since ${opts.since}.`);
+  }
+
+  let blocks: Record<string, unknown>;
+  try {
+    blocks = readDecofileFromDir(blocksDir).blocks;
+  } catch (e) {
+    console.error(`error: ${e instanceof Error ? e.message : String(e)}`);
+    process.exit(2);
+  }
+
+  const snap = buildSnapshot(blocks);
+  const purgePaths = opts.all
+    ? ["/"]
+    : purgePathsForChangedKeys(blocks, changedKeys);
+  console.log(`decofile: ${snap.count} blocks, revision ${snap.revision}`);
+
+  if (!opts.write) {
+    console.log(`\nDry-run only. Would write snapshot + revision and purge: ${purgePaths.join(", ")}`);
+    process.exit(0);
+  }
+
+  let client: ReturnType<typeof createKvRestClient>;
+  try {
+    client = createKvRestClient(kvConfigFromEnv());
+  } catch (e) {
+    console.error(`error: ${e instanceof Error ? e.message : String(e)}`);
+    process.exit(2);
+  }
+
+  try {
+    await writeSnapshotToKv(client, snap);
+    const verify = await verifySnapshotInKv(client, snap.revision);
+    if (!verify.ok) {
+      console.error(`error: KV verify failed — ${verify.reason}`);
+      process.exit(2);
+    }
+  } catch (e) {
+    console.error(`error: ${e instanceof Error ? e.message : String(e)}`);
+    process.exit(2);
+  }
+  console.log(`synced decofile:current (rev ${snap.revision}) → KV.`);
+
+  if (opts.purgeUrl && opts.purgeToken) {
+    await purgeCache(opts.purgeUrl, opts.purgeToken, purgePaths);
+  } else if (opts.purgeUrl) {
+    console.warn("warning: --purge-url given without a token (PURGE_TOKEN/--purge-token) — skipping purge.");
+  }
+}
+
+main();