@decocms/blocks-cli 7.0.0

package/scripts/migrate/types.ts

@@ -0,0 +1,244 @@
+export type Platform =
+  | "vtex"
+  | "vnda"
+  | "shopify"
+  | "wake"
+  | "linx"
+  | "nuvemshop"
+  | "magento"
+  | "custom";
+
+export interface FileRecord {
+  /** Relative path from source root */
+  path: string;
+  /** Absolute path */
+  absPath: string;
+  /** File category */
+  category:
+    | "section"
+    | "island"
+    | "component"
+    | "sdk"
+    | "loader"
+    | "action"
+    | "route"
+    | "app"
+    | "static"
+    | "config"
+    | "generated"
+    | "other";
+  /** Whether this file is a re-export wrapper */
+  isReExport?: boolean;
+  /** The target of the re-export if applicable */
+  reExportTarget?: string;
+  /** Detected patterns in this file */
+  patterns: DetectedPattern[];
+  /** Action to take */
+  action: "transform" | "delete" | "move" | "scaffold" | "manual-review";
+  /** Target path in new structure (relative to project root) */
+  targetPath?: string;
+  /** Notes for the report */
+  notes?: string;
+}
+
+export type DetectedPattern =
+  | "preact-hooks"
+  | "preact-signals"
+  | "fresh-runtime"
+  | "fresh-server"
+  | "deco-hooks"
+  | "deco-context"
+  | "deco-web"
+  | "deco-blocks"
+  | "apps-imports"
+  | "site-imports"
+  | "class-attr"
+  | "onInput-handler"
+  | "deno-lint-ignore"
+  | "npm-prefix"
+  | "ts-extension-import"
+  | "component-children"
+  | "jsx-types"
+  | "asset-function"
+  | "head-component"
+  | "define-app"
+  | "invoke-proxy"
+  | "use-component"
+  | "sections-component-loader";
+
+/** Metadata extracted from a section file during analysis */
+export interface SectionMeta {
+  /** Relative path from source root (e.g. "sections/Header/Header.tsx") */
+  path: string;
+  /** Has export const loader or export function loader */
+  hasLoader: boolean;
+  /** Loader is async */
+  loaderIsAsync: boolean;
+  /** Has export function LoadingFallback */
+  hasLoadingFallback: boolean;
+  /** Is a header section (by filename) */
+  isHeader: boolean;
+  /** Is a footer section (by filename) */
+  isFooter: boolean;
+  /** Is a theme section (by filename) */
+  isTheme: boolean;
+  /** Is a shelf/carousel/listing section (by filename or content) */
+  isListing: boolean;
+  /** Has JSDoc @title */
+  hasTitle: boolean;
+  /** Has JSDoc @description */
+  hasDescription: boolean;
+  /** Loader uses ctx.device or similar device detection */
+  loaderUsesDevice: boolean;
+  /** Loader uses request URL / search params */
+  loaderUsesUrl: boolean;
+  /** Loader is an Account section (sections/Account/*) */
+  isAccountSection: boolean;
+  /** Loader only sets ctx.response.status (no real prop enrichment) */
+  isStatusOnly: boolean;
+  /** Loader sets isMobile (boolean) rather than device (string) */
+  usesMobileBoolean: boolean;
+}
+
+/** Classification of an island file */
+export interface IslandClassification {
+  /** Relative path from source root */
+  path: string;
+  /** "wrapper" = thin re-export/bridge, "standalone" = has real logic */
+  type: "wrapper" | "standalone";
+  /** If wrapper, the target component path */
+  wrapsComponent?: string;
+  /** If standalone, the suggested target path under src/ */
+  suggestedTarget: string;
+  /** Line count (used as heuristic) */
+  lineCount: number;
+}
+
+/** Information about a loader file */
+export interface LoaderInfo {
+  /** Relative path from source root */
+  path: string;
+  /** Has export const cache (SWR) */
+  hasCache: boolean;
+  /** Has export const cacheKey */
+  hasCacheKey: boolean;
+  /** Maps to a known @decocms/apps equivalent */
+  appsEquivalent: string | null;
+  /** Is a custom loader that needs dynamic import in commerce-loaders */
+  isCustom: boolean;
+  /** Detected platform relevance (vtex, shopify, etc.) */
+  platformRelevance: Platform | null;
+}
+
+export interface MigrationContext {
+  sourceDir: string;
+  siteName: string;
+  platform: Platform;
+  /** VTEX account name (e.g. "casaevideonewio") — extracted from source code */
+  vtexAccount: string | null;
+  gtmId: string | null;
+
+  /**
+   * Per-site config loaded from `.deco-migrate.config.json`. `null` means
+   * no config file was present — defaults apply throughout. Imported
+   * lazily as `MigrateConfig` to avoid a circular dependency between
+   * `types.ts` and `config.ts`.
+   */
+  config?: import("./config").MigrateConfig | null;
+
+  /** deno.json import map entries */
+  importMap: Record<string, string>;
+
+  /** npm dependencies discovered from inline npm: imports in source files */
+  discoveredNpmDeps: Record<string, string>;
+
+  /** Theme colors extracted from .deco/blocks CMS config */
+  themeColors: Record<string, string>;
+  /** Font family from CMS config */
+  fontFamily: string | null;
+
+  /** All categorized source files */
+  files: FileRecord[];
+
+  /** Section metadata extracted during analysis */
+  sectionMetas: SectionMeta[];
+  /** Island classifications */
+  islandClassifications: IslandClassification[];
+  /** Map from island path → wrapped component import path (for wrapper islands) */
+  islandWrapperTargets: Map<string, string>;
+  /** Loader inventory */
+  loaderInventory: LoaderInfo[];
+
+  /** Files created by scaffold phase */
+  scaffoldedFiles: string[];
+  /** Files transformed */
+  transformedFiles: string[];
+  /** Files deleted */
+  deletedFiles: string[];
+  /** Files moved */
+  movedFiles: Array<{ from: string; to: string }>;
+  /** Items requiring manual review */
+  manualReviewItems: ReviewItem[];
+  /** Framework findings */
+  frameworkFindings: string[];
+
+  dryRun: boolean;
+  verbose: boolean;
+}
+
+export interface ReviewItem {
+  file: string;
+  reason: string;
+  severity: "info" | "warning" | "error";
+}
+
+export interface TransformResult {
+  content: string;
+  changed: boolean;
+  notes: string[];
+}
+
+export function createContext(
+  sourceDir: string,
+  opts: {
+    dryRun?: boolean;
+    verbose?: boolean;
+    config?: import("./config").MigrateConfig | null;
+  } = {},
+): MigrationContext {
+  return {
+    sourceDir,
+    siteName: "",
+    platform: "custom",
+    vtexAccount: null,
+    gtmId: null,
+    config: opts.config ?? null,
+    importMap: {},
+    discoveredNpmDeps: {},
+    themeColors: {},
+    fontFamily: null,
+    files: [],
+    sectionMetas: [],
+    islandClassifications: [],
+    islandWrapperTargets: new Map(),
+    loaderInventory: [],
+    scaffoldedFiles: [],
+    transformedFiles: [],
+    deletedFiles: [],
+    movedFiles: [],
+    manualReviewItems: [],
+    frameworkFindings: [],
+    dryRun: opts.dryRun ?? false,
+    verbose: opts.verbose ?? false,
+  };
+}
+
+export function log(ctx: MigrationContext, msg: string) {
+  if (ctx.verbose) console.log(`  ${msg}`);
+}
+
+export function logPhase(phase: string) {
+  console.log(`\n${"=".repeat(60)}`);
+  console.log(`  Phase: ${phase}`);
+  console.log(`${"=".repeat(60)}\n`);
+}

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

@@ -0,0 +1,104 @@
+#!/usr/bin/env tsx
+/**
+ * One-shot fast-deploy migration: populate Cloudflare KV from a site's
+ * bundled decofile so the worker can serve content KV-first.
+ *
+ * Reads `.deco/blocks/*.json` (the same merge the block generator does),
+ * writes `decofile:current` + `index:revision` to the site's KV namespace via
+ * the REST API, then reads both keys back to verify. Run ONCE per site before
+ * flipping it to KV-first (i.e. before adding the `DECO_KV` binding +
+ * deploying the fast-deploy framework version).
+ *
+ * Usage (from the site root):
+ *   # dry-run (default): reads blocks, prints what would be written, no writes
+ *   CF_ACCOUNT_ID=... CF_KV_NAMESPACE_ID=... CF_API_TOKEN=... \
+ *     npx -p @decocms/start deco-migrate-blocks-to-kv
+ *   # apply:
+ *   ... npx -p @decocms/start deco-migrate-blocks-to-kv --write
+ *
+ * Options:
+ *   --blocks-dir <dir>   Input blocks dir (default: .deco/blocks)
+ *   --write              Perform the KV 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 / dry-run; 2 error (bad dir, missing env, verify failed)
+ */
+
+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";
+
+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"),
+    write: has("--write"),
+    blocksDir: val("--blocks-dir", ".deco/blocks"),
+  };
+}
+
+async function main() {
+  const opts = parseArgs(process.argv.slice(2));
+  if (opts.help) {
+    console.log(
+      "Usage: deco-migrate-blocks-to-kv [--blocks-dir .deco/blocks] [--write]\n" +
+        "Env: CF_ACCOUNT_ID, CF_KV_NAMESPACE_ID, CF_API_TOKEN",
+    );
+    process.exit(0);
+  }
+
+  const blocksDir = path.resolve(process.cwd(), opts.blocksDir);
+
+  let blocks: Record<string, unknown>;
+  try {
+    const result = readDecofileFromDir(blocksDir);
+    blocks = result.blocks;
+    if (result.collisions.length) {
+      console.warn(`warning: ${result.collisions.length} filename collision(s) resolved by tie-break`);
+    }
+  } catch (e) {
+    console.error(`error: ${e instanceof Error ? e.message : String(e)}`);
+    process.exit(2);
+  }
+
+  const snap = buildSnapshot(blocks);
+  console.log(`decofile: ${snap.count} blocks, revision ${snap.revision}, ${snap.snapshot.length} bytes`);
+
+  if (!opts.write) {
+    console.log("\nDry-run only. Re-run with --write to populate KV.");
+    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(`\nwrote + verified decofile:current (rev ${snap.revision}) → KV.`);
+  console.log("Next: add the DECO_KV binding in wrangler.toml and deploy the fast-deploy build.");
+}
+
+main();

package/scripts/migrate-post-cleanup.ts

@@ -0,0 +1,191 @@
+#!/usr/bin/env tsx
+/**
+ * Post-Migration Cleanup Audit
+ *
+ * Read-only audit that scans a migrated site for dead code and obsolete
+ * boilerplate that the framework now owns. Mirrors the human checklist at
+ * `.agents/skills/deco-to-tanstack-migration/references/post-migration-cleanup.md`
+ * but turns it into something CI can actually run.
+ *
+ * Usage (from a migrated site directory):
+ *   npx -p @decocms/start deco-post-cleanup
+ *   npx -p @decocms/start deco-post-cleanup --json
+ *
+ * Options:
+ *   --source <dir>   Site directory to audit (default: current directory)
+ *   --json           Emit machine-readable JSON instead of pretty text
+ *   --strict         Exit code 2 if any warning-severity findings exist
+ *   --help, -h       Show this help
+ *
+ * This script is intentionally read-only. Auto-fix support (`--fix`) is
+ * a planned follow-up — see the SKILL doc.
+ */
+
+import * as path from "node:path";
+import { banner, bold, cyan, gray, green, red, yellow } from "./migrate/colors";
+import { realFsAdapter, realFsWriter, runAudit } from "./migrate/post-cleanup/runner";
+import type { AuditReport, Severity } from "./migrate/post-cleanup/types";
+
+interface CliOpts {
+  source: string;
+  json: boolean;
+  strict: boolean;
+  help: boolean;
+  fix: boolean;
+}
+
+function parseArgs(args: string[]): CliOpts {
+  let source = ".";
+  let json = false;
+  let strict = false;
+  let help = false;
+  let fix = false;
+  for (let i = 0; i < args.length; i++) {
+    switch (args[i]) {
+      case "--source":
+        source = args[++i];
+        break;
+      case "--json":
+        json = true;
+        break;
+      case "--strict":
+        strict = true;
+        break;
+      case "--fix":
+        fix = true;
+        break;
+      case "--help":
+      case "-h":
+        help = true;
+        break;
+    }
+  }
+  return { source, json, strict, help, fix };
+}
+
+function showHelp() {
+  console.log(`
+  @decocms/start — Post-Migration Cleanup Audit
+
+  Scans a migrated site for dead code and obsolete boilerplate that the
+  framework now owns. Read-only — prints findings, does not modify files.
+
+  Usage:
+    npx -p @decocms/start deco-post-cleanup [options]
+
+  Options:
+    --source <dir>   Site directory to audit (default: .)
+    --fix            Auto-apply mechanical fixes for the safe rules
+                     (dead-lib-shims, dead-runtime-shim, local-widgets-types,
+                     vtex-shim-regression swap subset, obsolete-vite-plugins,
+                     local-framework-duplicate auto-fixable subset,
+                     lockfile-multiple, package-manager-missing).
+                     Other rules — including htmx-residue, lockfile-missing,
+                     lockfile-drift, and the warn-only entries of
+                     local-framework-duplicate — stay detect-only.
+    --json           Emit machine-readable JSON instead of pretty text
+    --strict         Exit code 2 if any warning-severity findings exist
+    --help, -h       Show this help
+
+  Examples:
+    npx -p @decocms/start deco-post-cleanup
+    npx -p @decocms/start deco-post-cleanup --source ./my-site --json
+    npx -p @decocms/start deco-post-cleanup --fix
+    npx -p @decocms/start deco-post-cleanup --fix --strict   # fail CI if anything left
+
+  See: .agents/skills/deco-to-tanstack-migration/references/post-migration-cleanup.md
+  `);
+}
+
+function severityColor(sev: Severity, text: string): string {
+  if (sev === "warning") return yellow(text);
+  return gray(text);
+}
+
+function printText(report: AuditReport, fixMode: boolean): void {
+  banner(fixMode ? "Post-Migration Cleanup Audit (--fix)" : "Post-Migration Cleanup Audit");
+  console.log(`  ${gray("Site:")} ${bold(report.site)}`);
+  console.log(`  ${gray("Findings:")} ${bold(String(report.totalFindings))}`);
+  if (fixMode) {
+    console.log(`  ${gray("Auto-fixed:")} ${bold(String(report.totalFixActions))}`);
+  }
+  console.log("");
+
+  let idx = 0;
+  for (const summary of report.rules) {
+    idx++;
+    const count = summary.findings.length;
+    const fixCount = summary.fixes?.length ?? 0;
+    const headColor = count === 0 ? green : yellow;
+    const suffix = fixMode
+      ? gray(`(${count} found, ${fixCount} fixed${summary.supportsAutoFix ? "" : ", manual"})`)
+      : gray(`(${count} found)`);
+    console.log(`${headColor(`[${idx}] ${summary.title}`)} ${suffix}`);
+    for (const f of summary.findings) {
+      const tag = severityColor(f.severity, `[${f.severity.toUpperCase()}]`);
+      console.log(`    ${tag} ${bold(f.file)} — ${f.message}`);
+      if (f.fix && !summary.fixes) {
+        console.log(`        ${gray("fix:")} ${f.fix}`);
+      }
+    }
+    if (summary.fixes) {
+      for (const a of summary.fixes) {
+        console.log(`    ${cyan("[FIXED]")} ${bold(a.file)} — ${a.detail}`);
+      }
+    }
+    if (count === 0) console.log(`    ${gray("(nothing to clean up)")}`);
+    console.log("");
+  }
+
+  const warnings = report.rules
+    .flatMap((r) => r.findings)
+    .filter((f) => f.severity === "warning").length;
+  const infos = report.totalFindings - warnings;
+  const tail = fixMode
+    ? `${report.totalFindings} finding(s) — ${cyan(`${report.totalFixActions} auto-fixed`)}, ${yellow(`${warnings} warning(s)`)}, ${gray(`${infos} info`)}`
+    : `${report.totalFindings} finding(s) — ${yellow(`${warnings} warning(s)`)}, ${gray(`${infos} info`)}`;
+  console.log(`${bold("Summary:")} ${tail}`);
+  if (report.totalFindings > 0) {
+    const hint = fixMode
+      ? "  Some rules require manual fixes — see post-migration-cleanup.md."
+      : "  Run with --fix to auto-correct the safe rules, or see post-migration-cleanup.md.";
+    console.log(gray(hint));
+  }
+}
+
+function printJson(report: AuditReport): void {
+  console.log(JSON.stringify(report, null, 2));
+}
+
+function shouldFail(report: AuditReport, strict: boolean): boolean {
+  if (!strict) return false;
+  return report.rules.some((r) => r.findings.some((f) => f.severity === "warning"));
+}
+
+async function main() {
+  const opts = parseArgs(process.argv.slice(2));
+  if (opts.help) {
+    showHelp();
+    process.exit(0);
+  }
+
+  const siteDir = path.resolve(opts.source);
+  const report = runAudit(siteDir, realFsAdapter, {
+    writer: opts.fix ? realFsWriter : undefined,
+  });
+
+  if (opts.json) {
+    printJson(report);
+  } else {
+    printText(report, opts.fix);
+  }
+
+  if (shouldFail(report, opts.strict)) {
+    process.exit(2);
+  }
+}
+
+main().catch((err) => {
+  console.error(red(`Audit failed: ${(err as Error).message}`));
+  process.exit(1);
+});