@decocms/blocks-cli 7.49.0 → 7.50.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decocms/blocks-cli",
-  "version": "7.49.0",
+  "version": "7.50.0",
   "type": "module",
   "description": "Deco codegen (generate-blocks, generate-schema, generate-invoke) and Fresh-to-TanStack migration tooling",
   "repository": {
@@ -17,6 +17,7 @@
     "deco-audit-observability": "./scripts/audit-observability-config.ts",
     "deco-migrate-blocks-to-kv": "./scripts/migrate-blocks-to-kv.ts",
     "deco-sync-blocks-to-kv": "./scripts/sync-blocks-to-kv.ts",
+    "deco-pull-decofile": "./scripts/pull-decofile.ts",
     "deco-upgrade-6-to-7": "./scripts/upgrade-6-to-7.ts",
     "deco-reconcile": "./scripts/reconcile.ts"
   },
@@ -32,7 +33,7 @@
     "lint:unused": "knip"
   },
   "dependencies": {
-    "@decocms/blocks": "7.49.0",
+    "@decocms/blocks": "7.50.0",
     "ts-morph": "^27.0.0",
     "tsx": "^4.22.5"
   },

package/scripts/migrate/phase-scaffold.ts

@@ -9,6 +9,7 @@ import { generateCacheConfig } from "./templates/cache-config";
 import { generateCiFiles } from "./templates/ci-yml";
 import { generateCommerceInit } from "./templates/commerce-init";
 import { generateCommerceLoaders } from "./templates/commerce-loaders";
+import { generateContentSyncYml } from "./templates/content-sync-yml";
 import { generateMigrationPolicyPointerRule } from "./templates/cursor-rules";
 import { generateHooks } from "./templates/hooks";
 import { generateKnipConfig } from "./templates/knip-config";
@@ -130,6 +131,15 @@ export function scaffold(ctx: MigrationContext): void {
   // live storefront (@decocms/parity). Inert until PARITY_PROD_URL is set.
   writeFile(ctx, ".github/workflows/parity.yml", generateParityYml(ctx.siteName));
 
+  // Daily content pull from the still-live storefront (`<origin>/.decofile` ->
+  // `.deco/blocks` -> PR). Replaces the legacy cross-repo-PAT push sync; inert
+  // until the operator sets the repo variable CONTENT_SYNC_ORIGIN.
+  writeFile(
+    ctx,
+    ".github/workflows/content-sync.yml",
+    generateContentSyncYml(CANONICAL_BUN_VERSION),
+  );
+
   // Server entry files (server.ts, worker-entry.ts, router.tsx, runtime.ts, context.ts)
   writeMultiFile(ctx, generateServerEntry(ctx));
 

package/scripts/migrate/phase-verify.ts

@@ -26,6 +26,7 @@ const REQUIRED_FILES = [
   ".github/workflows/playwright.yml",
   ".github/workflows/react-doctor.yml",
   ".github/workflows/parity.yml",
+  ".github/workflows/content-sync.yml",
   "tools/gates/no-suppressions.sh",
   "playwright.config.ts",
   "knip.config.ts",

package/scripts/migrate/templates/ci-workflows.test.ts

@@ -1,5 +1,6 @@
 import { describe, expect, it } from "vitest";
 import { generateCiFiles } from "./ci-yml";
+import { generateContentSyncYml } from "./content-sync-yml";
 import { generateMainPushGuardYml } from "./main-push-guard-yml";
 import { generateParityYml } from "./parity-yml";
 import { generatePlaywrightFiles } from "./playwright-yml";
@@ -123,3 +124,45 @@ describe("generateParityYml", () => {
     expect(yml).toContain("secrets.ANTHROPIC_API_KEY"); // optional LLM key
   });
 });
+
+describe("generateContentSyncYml", () => {
+  const yml = generateContentSyncYml("bun@1.3.5");
+
+  it("pulls on a daily cron, gated on CONTENT_SYNC_ORIGIN", () => {
+    expect(yml).toContain("name: content-sync");
+    expect(yml).toContain('BUN_VERSION: "1.3.5"'); // bun@ prefix stripped
+    expect(yml).toContain('- cron: "0 6 * * *"');
+    expect(yml).toContain("vars.CONTENT_SYNC_ORIGIN");
+    expect(yml).toContain("scripts/pull-decofile.ts");
+    expect(yml).toContain("--fail-on-plaintext-secret");
+  });
+
+  it("only ever needs GITHUB_TOKEN — no cross-repo credential", () => {
+    expect(yml).toContain("secrets.GITHUB_TOKEN");
+    expect(yml).not.toMatch(/secrets\.(?!GITHUB_TOKEN)[A-Z_]+/);
+    expect(yml).toContain("permissions:");
+    expect(yml).toContain("concurrency:");
+  });
+
+  it("guards the diff to .deco/blocks and builds before opening the PR", () => {
+    const guardIdx = yml.indexOf("Guard");
+    const buildIdx = yml.indexOf("Validar (generate + build)");
+    const prIdx = yml.indexOf("gh pr create");
+    expect(guardIdx).toBeGreaterThan(-1);
+    expect(guardIdx).toBeLessThan(buildIdx);
+    expect(buildIdx).toBeLessThan(prIdx);
+    expect(yml).toContain("grep -v '^\\.deco/blocks/'");
+    expect(yml).toContain("git add .deco/blocks");
+  });
+
+  it("is de-projectized — no real site/customer names", () => {
+    expect(yml).not.toMatch(/oficina|miess|colombo/i);
+  });
+
+  it("runs the site's own installed CLI, or a pinned one when given", () => {
+    expect(yml).toContain("bunx tsx node_modules/@decocms/blocks-cli/scripts/pull-decofile.ts");
+    const pinned = generateContentSyncYml("1.3.5", "7.50.0");
+    expect(pinned).toContain("bunx -y @decocms/blocks-cli@7.50.0 deco-pull-decofile");
+    expect(pinned).not.toContain("node_modules/@decocms/blocks-cli");
+  });
+});

package/scripts/migrate/templates/content-sync-yml.ts

@@ -0,0 +1,184 @@
+/**
+ * Scaffolds `.github/workflows/content-sync.yml` — the secure content channel
+ * from the still-live Fresh/Deno storefront into the migrated repo.
+ *
+ * Replaces the legacy push-based sync (a workflow in the *legacy* repo holding a
+ * cross-repo PAT, `rsync --delete` + `git push` straight into this repo's main).
+ * That token is a code-write door, not a content channel: whoever controls the
+ * legacy repo or the token can land arbitrary files here, unreviewed.
+ *
+ * Direction is inverted — this repo pulls, on its own schedule, with its own
+ * `GITHUB_TOKEN`, and gates the result:
+ *   - `pull-decofile.ts` fetches `<origin>/.decofile` (public, unauthenticated)
+ *     and writes `.deco/blocks/`, denying the `Site` block and anything holding
+ *     encrypted credentials, and aborting on a plaintext credential;
+ *   - a path guard fails the run if anything outside `.deco/blocks/` changed;
+ *   - `bun run generate && bun run build` runs IN THIS JOB, before the PR. It
+ *     has to be here: a PR opened with `GITHUB_TOKEN` does not trigger
+ *     `pull_request` workflows, so gating on the PR's own CI would need a PAT
+ *     and would never fire on its own.
+ *
+ * Inert until the operator sets the repo variable `CONTENT_SYNC_ORIGIN` (same
+ * one-knob pattern as parity.yml's `PARITY_PROD_URL`) — the job skips cleanly.
+ *
+ * Docs: docs/content-sync.md
+ *
+ * @param bunVersion  Pinned bun version, in lockstep with package.json.
+ * @param cliVersion  Optional `@decocms/blocks-cli` version to run the pull
+ *   with, via `bunx`. Omit for a freshly scaffolded site: the site's own
+ *   installed copy is by definition in-version, so the local file path is used.
+ *   Pass a version for a site still on an older `@decocms/*` — pinning only the
+ *   sync step gets the script without bumping the runtime the site builds
+ *   against (blocks-cli pins `@decocms/blocks` exactly, so bumping the devDep
+ *   drags a second runtime version into the tree). Drop it when the site bumps.
+ */
+export function generateContentSyncYml(bunVersion: string, cliVersion?: string): string {
+  const bun = bunVersion.replace(/^bun@/, "");
+  const pullCmd = cliVersion
+    ? `bunx -y @decocms/blocks-cli@${cliVersion} deco-pull-decofile`
+    : "bunx tsx node_modules/@decocms/blocks-cli/scripts/pull-decofile.ts";
+  return `name: content-sync
+
+# Puxa o conteúdo publicado na loja de produção (Fresh/Deno) para \`.deco/blocks\`
+# e abre um PR. Sem token cross-repo: o repo legado não tem permissão nenhuma
+# aqui — este repo busca sozinho, valida e só então mergeia.
+#
+# Configuração (uma vez): variável de repo \`CONTENT_SYNC_ORIGIN\` = origin da
+# loja de produção (ex.: https://www.minhaloja.com.br). Sem ela o job pula limpo.
+# Para revisão humana em vez de merge automático, mude \`AUTO_MERGE\` para "false".
+#
+# Depois de ligar isto, APAGUE o workflow de push no repo legado e REVOGUE o
+# token cross-repo — o pull não fecha aquela porta sozinho. Ver docs/content-sync.md.
+
+on:
+  schedule:
+    # 06:00 UTC = 03:00 BRT, fora do horário de publicação do CMS.
+    - cron: "0 6 * * *"
+  workflow_dispatch:
+    inputs:
+      origin:
+        description: "Origin da loja de produção (sobrepõe CONTENT_SYNC_ORIGIN)"
+        required: false
+      prune:
+        description: "Apagar blocos que não existem mais em produção"
+        type: boolean
+        default: true
+      dry_run:
+        description: "Só relatório, não escreve nem abre PR"
+        type: boolean
+        default: false
+
+permissions:
+  contents: write
+  pull-requests: write
+
+# Publicações do CMS acontecem em rajada; uma sync por vez, sem cancelar a que
+# já está no gate de build.
+concurrency:
+  group: content-sync
+  cancel-in-progress: false
+
+env:
+  BUN_VERSION: "${bun}"
+  AUTO_MERGE: "true"
+  # Chaves de bloco que a sync NUNCA sobrescreve. Blocos com secret encriptado
+  # já são protegidos por shape pelo script (as credenciais deste repo vivem no
+  # bloco de app dele, que não existe nesse layout em produção).
+  DENY_KEYS: "Site,site"
+
+jobs:
+  sync:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Resolve origin
+        id: cfg
+        env:
+          INPUT_ORIGIN: \${{ github.event.inputs.origin }}
+          VAR_ORIGIN: \${{ vars.CONTENT_SYNC_ORIGIN }}
+        run: |
+          origin="\${INPUT_ORIGIN:-$VAR_ORIGIN}"
+          if [ -z "$origin" ]; then
+            echo "::notice::variável de repo CONTENT_SYNC_ORIGIN não configurada — content-sync inerte."
+            echo "skip=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "origin=$origin" >> "$GITHUB_OUTPUT"
+          fi
+
+      - uses: actions/checkout@v4
+        if: steps.cfg.outputs.skip != 'true'
+
+      - uses: oven-sh/setup-bun@v2
+        if: steps.cfg.outputs.skip != 'true'
+        with:
+          bun-version: \${{ env.BUN_VERSION }}
+
+      - name: Install
+        if: steps.cfg.outputs.skip != 'true'
+        run: bun install --frozen-lockfile
+
+      - name: Pull decofile de produção
+        if: steps.cfg.outputs.skip != 'true'
+        env:
+          ORIGIN: \${{ steps.cfg.outputs.origin }}
+          PRUNE: \${{ github.event.inputs.prune == 'false' && ' ' || '--prune' }}
+          DRY_RUN: \${{ github.event.inputs.dry_run == 'true' && '--dry-run' || ' ' }}
+        run: |
+          ${pullCmd} \\
+            --origin "$ORIGIN" \\
+            --out .deco/blocks \\
+            --deny "$DENY_KEYS" \\
+            --fail-on-plaintext-secret \\
+            --github $PRUNE $DRY_RUN
+
+      - name: Guard — só .deco/blocks pode mudar
+        id: guard
+        if: steps.cfg.outputs.skip != 'true' && github.event.inputs.dry_run != 'true'
+        run: |
+          {
+            git -c core.quotepath=false diff --name-only HEAD
+            git -c core.quotepath=false ls-files --others --exclude-standard
+          } | sort -u > /tmp/content-sync-changed.txt
+          offending="$(grep -v '^\\.deco/blocks/' /tmp/content-sync-changed.txt || true)"
+          if [ -n "$offending" ]; then
+            echo "::error::a sync mexeu fora de .deco/blocks — abortando:"
+            echo "$offending"
+            exit 1
+          fi
+          if [ ! -s /tmp/content-sync-changed.txt ]; then
+            echo "::notice::conteúdo já está em dia, nada a sincronizar."
+            echo "changed=false" >> "$GITHUB_OUTPUT"
+          else
+            echo "changed=true" >> "$GITHUB_OUTPUT"
+            echo "$(wc -l < /tmp/content-sync-changed.txt) arquivo(s) de bloco alterado(s)"
+          fi
+
+      # Gate de verdade. Roda AQUI porque PR aberto com GITHUB_TOKEN não dispara
+      # o workflow de \`pull_request\` — gatear no CI do PR exigiria um PAT.
+      - name: Validar (generate + build)
+        if: steps.guard.outputs.changed == 'true'
+        run: bun run generate && bun run build
+
+      - name: Abrir PR (e mergear se AUTO_MERGE)
+        if: steps.guard.outputs.changed == 'true'
+        env:
+          GH_TOKEN: \${{ secrets.GITHUB_TOKEN }}
+          ORIGIN: \${{ steps.cfg.outputs.origin }}
+        run: |
+          branch="content-sync/$(date -u +%Y-%m-%dT%H%M%SZ)"
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git checkout -b "$branch"
+          git add .deco/blocks
+          git commit -m "chore(content): sync .deco/blocks de $ORIGIN"
+          git push origin "$branch"
+          url="$(gh pr create \\
+            --title "chore(content): sync .deco/blocks de produção" \\
+            --body "Conteúdo puxado de \\\`$ORIGIN/.decofile\\\` pelo workflow \\\`content-sync\\\`. Só \\\`.deco/blocks/**\\\` mudou (guard) e \\\`generate + build\\\` passou antes deste PR existir." \\
+            --head "$branch")"
+          echo "PR: $url"
+          if [ "$AUTO_MERGE" = "true" ]; then
+            gh pr merge "$url" --squash --delete-branch || \\
+              echo "::notice::merge automático bloqueado (branch protection?) — PR aberto para revisão: $url"
+          fi
+`;
+}

package/scripts/pull-decofile.test.ts

@@ -0,0 +1,258 @@
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import {
+  DEFAULT_DENY,
+  fetchDecofile,
+  findPlaintextSecrets,
+  hasEncryptedSecretRef,
+  matchesGlob,
+  writeDecofileToDir,
+} from "./pull-decofile";
+
+function tmpBlocksDir(files: Record<string, unknown> = {}): string {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), "pull-decofile-"));
+  const out = path.join(dir, ".deco", "blocks");
+  fs.mkdirSync(out, { recursive: true });
+  for (const [file, content] of Object.entries(files)) {
+    fs.writeFileSync(path.join(out, file), `${JSON.stringify(content, null, 2)}\n`);
+  }
+  return out;
+}
+
+const ls = (dir: string) => fs.readdirSync(dir).sort();
+const read = (dir: string, file: string) =>
+  JSON.parse(fs.readFileSync(path.join(dir, file), "utf-8")) as Record<string, unknown>;
+
+describe("matchesGlob", () => {
+  it("matches whole keys with a * wildcard", () => {
+    expect(matchesGlob("Site", "Site")).toBe(true);
+    expect(matchesGlob("Sitemap", "Site")).toBe(false);
+    expect(matchesGlob("pages-Home", "pages-*")).toBe(true);
+    expect(matchesGlob("deco-vtex", "deco-*")).toBe(true);
+    // dots are literal, not "any char"
+    expect(matchesGlob("axb", "a.b")).toBe(false);
+  });
+});
+
+describe("hasEncryptedSecretRef", () => {
+  it("finds a {name, encrypted} ref at any depth", () => {
+    expect(hasEncryptedSecretRef({ appKey: { name: "BANANA", encrypted: "3a714de1" } })).toBe(true);
+    expect(hasEncryptedSecretRef({ a: [{ b: { name: "X", encrypted: "y" } }] })).toBe(true);
+    expect(hasEncryptedSecretRef({ name: "X", encrypted: "" })).toBe(false);
+    expect(hasEncryptedSecretRef({ sections: [{ __resolveType: "site/x.tsx" }] })).toBe(false);
+  });
+});
+
+describe("findPlaintextSecrets", () => {
+  it("flags credential-shaped props holding a raw string", () => {
+    expect(findPlaintextSecrets({ appToken: "abcdefghijklmnop" })).toEqual(["appToken"]);
+    expect(findPlaintextSecrets({ nested: { api_key: "abcdefghijklmnop" } })).toEqual([
+      "nested.api_key",
+    ]);
+    expect(findPlaintextSecrets({ list: [{ password: "abcdefghijklmnop" }] })).toEqual([
+      "list[0].password",
+    ]);
+  });
+
+  it("ignores a bare `key` prop — CMS content is full of them", () => {
+    // real shape: every VTEX PLP loader block carries selectedFacets[].key
+    expect(
+      findPlaintextSecrets({ selectedFacets: [{ key: "productClusterIds", value: "140" }] }),
+    ).toEqual([]);
+    // …but a qualified key still counts
+    expect(findPlaintextSecrets({ apiKey: "abcdefghijklmnop" })).toEqual(["apiKey"]);
+    expect(findPlaintextSecrets({ "private-key": "abcdefghijklmnop" })).toEqual(["private-key"]);
+  });
+
+  it("does not flag encrypted refs, urls, prose or short values", () => {
+    expect(findPlaintextSecrets({ appKey: { name: "X", encrypted: "abcdefghijklmnop" } })).toEqual(
+      [],
+    );
+    expect(findPlaintextSecrets({ tokenUrl: "https://x.com/very/long/path" })).toEqual([]);
+    expect(findPlaintextSecrets({ secret: "short" })).toEqual([]);
+    expect(findPlaintextSecrets({ password: "uma frase com espacos" })).toEqual([]);
+    expect(findPlaintextSecrets({ apiKey: "{{ FROM_ENV_VAR_HERE }}" })).toEqual([]);
+  });
+});
+
+describe("writeDecofileToDir", () => {
+  it("writes one single-encoded file per block and skips unchanged ones", () => {
+    const out = tmpBlocksDir();
+    const remote = {
+      "pages-Home": { name: "Home", path: "/", sections: [] },
+      "pages-A B": { name: "A B", path: "/a-b", sections: [] },
+    };
+
+    const first = writeDecofileToDir(remote, { out });
+    expect(first.added.sort()).toEqual(["pages-A B", "pages-Home"]);
+    expect(ls(out)).toEqual(["pages-A%20B.json", "pages-Home.json"]);
+    expect(read(out, "pages-Home.json").path).toBe("/");
+
+    const second = writeDecofileToDir(remote, { out });
+    expect(second.unchanged).toBe(2);
+    expect(second.added).toEqual([]);
+    expect(second.updated).toEqual([]);
+  });
+
+  it("compares content, not bytes — minified or reordered locals are not churn", () => {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), "pull-decofile-"));
+    const out = path.join(dir, "blocks");
+    fs.mkdirSync(out, { recursive: true });
+    // how the Studio daemon / old sync bot write it: one minified line, no newline
+    fs.writeFileSync(path.join(out, "pages-Home.json"), '{"sections":[],"path":"/","name":"Home"}');
+
+    const report = writeDecofileToDir(
+      { "pages-Home": { name: "Home", path: "/", sections: [] } },
+      { out },
+    );
+    expect(report.unchanged).toBe(1);
+    expect(report.updated).toEqual([]);
+    // untouched: no reformat commit
+    expect(fs.readFileSync(path.join(out, "pages-Home.json"), "utf-8")).toBe(
+      '{"sections":[],"path":"/","name":"Home"}',
+    );
+
+    // a real content change does get written, pretty-printed
+    const changed = writeDecofileToDir({ "pages-Home": { name: "Home v2", path: "/" } }, { out });
+    expect(changed.updated).toEqual(["pages-Home"]);
+    expect(fs.readFileSync(path.join(out, "pages-Home.json"), "utf-8")).toContain('\n  "name"');
+  });
+
+  it("denies keys by glob, defaulting to the Site block", () => {
+    const out = tmpBlocksDir({ "Site.json": { seo: { title: "local" } } });
+    const report = writeDecofileToDir(
+      { Site: { seo: { title: "prod" } }, "pages-Home": { path: "/" } },
+      { out },
+    );
+    expect(DEFAULT_DENY).toContain("Site");
+    expect(report.denied).toEqual(["Site"]);
+    expect(read(out, "Site.json").seo).toEqual({ title: "local" });
+
+    const custom = writeDecofileToDir({ "pages-Home": { path: "/x" } }, { out, deny: ["pages-*"] });
+    expect(custom.denied).toEqual(["pages-Home"]);
+  });
+
+  it("never overwrites a block that carries an encrypted secret", () => {
+    const out = tmpBlocksDir({
+      "deco-vtex.json": { account: "loja", appKey: { name: "KEY", encrypted: "local" } },
+    });
+    const report = writeDecofileToDir(
+      { "deco-vtex": { account: "outra", appKey: { name: "KEY", encrypted: "prod" } } },
+      { out },
+    );
+    expect(report.protectedSecretBlocks).toEqual(["deco-vtex"]);
+    expect(read(out, "deco-vtex.json").account).toBe("loja");
+
+    const forced = writeDecofileToDir(
+      { "deco-vtex": { account: "outra", appKey: { name: "KEY", encrypted: "prod" } } },
+      { out, allowSecretBlocks: true },
+    );
+    expect(forced.updated).toEqual(["deco-vtex"]);
+  });
+
+  it("overwrites a legacy double-encoded filename in place instead of duplicating it", () => {
+    const out = tmpBlocksDir({ "pages-A%2520B.json": { name: "old", path: "/a-b" } });
+    const report = writeDecofileToDir({ "pages-A B": { name: "new", path: "/a-b" } }, { out });
+    expect(report.updated).toEqual(["pages-A B"]);
+    expect(ls(out)).toEqual(["pages-A%2520B.json"]);
+    expect(read(out, "pages-A%2520B.json").name).toBe("new");
+  });
+
+  it("collapses colliding encodings onto the canonical name", () => {
+    const out = tmpBlocksDir({
+      "pages-A%2520B.json": { name: "stale", path: "/a-b" },
+      "pages-A%20B.json": { name: "also stale", path: "/a-b" },
+    });
+    const report = writeDecofileToDir({ "pages-A B": { name: "new", path: "/a-b" } }, { out });
+    expect(report.updated).toEqual(["pages-A B"]);
+    expect(ls(out)).toEqual(["pages-A%20B.json"]);
+    expect(read(out, "pages-A%20B.json").name).toBe("new");
+  });
+
+  it("prunes blocks absent upstream, but keeps denied and secret-bearing ones", () => {
+    const out = tmpBlocksDir({
+      "pages-Gone.json": { name: "gone", path: "/gone" },
+      "pages-Home.json": { name: "home", path: "/" },
+      "Site.json": { seo: {} },
+      "deco-vtex.json": { appKey: { name: "KEY", encrypted: "local" } },
+    });
+    const report = writeDecofileToDir(
+      { "pages-Home": { name: "home", path: "/" } },
+      {
+        out,
+        prune: true,
+      },
+    );
+    expect(report.removed).toEqual(["pages-Gone"]);
+    expect(report.denied).toEqual(["Site"]);
+    expect(report.protectedSecretBlocks).toEqual(["deco-vtex"]);
+    expect(ls(out)).toEqual(["Site.json", "deco-vtex.json", "pages-Home.json"]);
+  });
+
+  it("--dry-run touches nothing", () => {
+    const out = tmpBlocksDir({ "pages-Gone.json": { path: "/gone" } });
+    const report = writeDecofileToDir(
+      { "pages-Home": { path: "/" } },
+      {
+        out,
+        prune: true,
+        dryRun: true,
+      },
+    );
+    expect(report.added).toEqual(["pages-Home"]);
+    expect(report.removed).toEqual(["pages-Gone"]);
+    expect(ls(out)).toEqual(["pages-Gone.json"]);
+  });
+
+  it("skips non-object payload values and reports plaintext secrets", () => {
+    const out = tmpBlocksDir();
+    const report = writeDecofileToDir(
+      { broken: "not a block", leak: { appToken: "abcdefghijklmnop" } },
+      { out },
+    );
+    expect(report.skipped).toEqual(["broken"]);
+    expect(report.plaintextSecrets).toEqual(["leak.appToken"]);
+  });
+});
+
+describe("fetchDecofile", () => {
+  afterEach(() => vi.unstubAllGlobals());
+
+  const stub = (body: string, init: { status?: number; headers?: Record<string, string> } = {}) => {
+    vi.stubGlobal(
+      "fetch",
+      vi.fn(
+        async () =>
+          new Response(body, {
+            status: init.status ?? 200,
+            headers: { "content-type": "application/json", ...init.headers },
+          }),
+      ),
+    );
+  };
+
+  it("returns the parsed decofile plus the ETag revision", async () => {
+    stub(JSON.stringify({ "pages-Home": { path: "/" } }), { headers: { etag: '"abc123"' } });
+    const result = await fetchDecofile("https://x.com/.decofile");
+    expect(result.blocks).toEqual({ "pages-Home": { path: "/" } });
+    expect(result.revision).toBe('"abc123"');
+  });
+
+  it("rejects a non-200, a non-JSON content-type, a non-object payload and an oversized body", async () => {
+    stub("{}", { status: 500 });
+    await expect(fetchDecofile("https://x.com/.decofile")).rejects.toThrow(/responded 500/);
+
+    stub("<html>", { headers: { "content-type": "text/html" } });
+    await expect(fetchDecofile("https://x.com/.decofile")).rejects.toThrow(/expected JSON/);
+
+    stub("[]");
+    await expect(fetchDecofile("https://x.com/.decofile")).rejects.toThrow(/an array/);
+
+    stub(JSON.stringify({ a: { b: 1 } }));
+    await expect(fetchDecofile("https://x.com/.decofile", { maxBytes: 4 })).rejects.toThrow(
+      /over the 4 byte cap/,
+    );
+  });
+});

package/scripts/pull-decofile.ts

@@ -0,0 +1,557 @@
+#!/usr/bin/env tsx
+/**
+ * @decocms/blocks-cli — pull the production decofile into `.deco/blocks/`
+ *
+ * Secure replacement for the legacy push-based content sync, where a workflow
+ * in the *legacy* Fresh repo held a cross-repo PAT and pushed straight into the
+ * migrated repo's `main` (`rsync --delete` + `git push`). That token is a code
+ * -write door into the new repo, not a content channel.
+ *
+ * This inverts the direction: the migrated repo *pulls* the decofile from the
+ * live site (`GET <origin>/.decofile`, public and unauthenticated) on a daily
+ * cron, materialises one file per block, and opens a PR. No cross-repo token,
+ * no write permission handed to anyone, and the content passes a build gate
+ * before reaching `main`. See `docs/content-sync.md`.
+ *
+ * Three filters decide what may be overwritten:
+ *   1. `--deny <globs>`      — deny by block key (default: the `Site` block).
+ *   2. encrypted-secret shape — any block carrying a `{name, encrypted}` secret
+ *      ref anywhere in its tree is left alone. That is what protects the
+ *      credentials the migration moves onto the new site's own app block
+ *      (e.g. `deco-vtex`), which do not exist in that layout upstream.
+ *      Opt out with `--allow-secret-blocks`.
+ *   3. `--fail-on-plaintext-secret` — aborts if an accepted block carries what
+ *      looks like a *plaintext* credential, so a leak upstream is never
+ *      committed into git.
+ *
+ * Usage (from a site root):
+ *   tsx pull-decofile.ts --origin https://www.minhaloja.com.br --prune
+ *   tsx pull-decofile.ts --url https://www.minhaloja.com.br/.decofile --dry-run --json
+ *
+ * Exit codes:
+ *   0 — done (with or without changes)
+ *   1 — `--fail-on-plaintext-secret` and at least one plaintext finding
+ *   2 — usage / network / payload validation error (nothing was written)
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { decodeBlockNameWithPasses } from "./lib/blocks-dedupe";
+
+/** Block keys never overwritten by a sync unless `--deny` is overridden. */
+export const DEFAULT_DENY = ["Site", "site"];
+
+const DEFAULT_MAX_BYTES = 64 * 1024 * 1024;
+const DEFAULT_TIMEOUT_MS = 60_000;
+
+/**
+ * Property names whose *string* value would be a credential in the clear.
+ * A bare `key` is deliberately NOT here: CMS content is full of `key` props
+ * that are nothing of the sort (`selectedFacets[].key` on every VTEX PLP
+ * loader — 331 false positives on a real site), and a gate that cries wolf is a
+ * gate nobody keeps on.
+ * `key` only counts when qualified (`apiKey`, `appKey`, `privateKey`, …).
+ */
+const SECRET_PROP_RE =
+  /(?:^|_)(?:(?:api|app|access|private|public|client|secret|auth)_?keys?|tokens?|secrets?|passwords?|passwd|pwd)$/;
+
+/** `appToken` -> `app_token`, so one snake_case regex covers both styles. */
+function normalizeProp(prop: string): string {
+  return prop
+    .replace(/([a-z0-9])([A-Z])/g, "$1_$2")
+    .replace(/-/g, "_")
+    .toLowerCase();
+}
+
+export interface PullOptions {
+  /** Directory that holds one JSON file per block (usually `.deco/blocks`). */
+  out: string;
+  /** Glob patterns (`*` wildcard) matched against the block key. */
+  deny?: string[];
+  /** Overwrite blocks that carry an encrypted secret ref (default: false). */
+  allowSecretBlocks?: boolean;
+  /** Delete local blocks that no longer exist upstream (default: false). */
+  prune?: boolean;
+  /** Compute the report without touching the filesystem. */
+  dryRun?: boolean;
+}
+
+export interface PullReport {
+  added: string[];
+  updated: string[];
+  unchanged: number;
+  removed: string[];
+  /** Keys skipped by the deny glob. */
+  denied: string[];
+  /** Keys skipped because the local/remote block carries an encrypted secret. */
+  protectedSecretBlocks: string[];
+  /** Keys skipped because the payload value was not a JSON object. */
+  skipped: string[];
+  /** `<key>.<prop path>` of every plaintext credential found in a written block. */
+  plaintextSecrets: string[];
+  /** Blocks present in the remote payload. */
+  remoteBlocks: number;
+  revision?: string;
+  bytes?: number;
+}
+
+export interface FetchResult {
+  blocks: Record<string, unknown>;
+  revision?: string;
+  bytes: number;
+}
+
+// ---------------------------------------------------------------- pure helpers
+
+/** `*`-only glob match against a whole block key. */
+export function matchesGlob(key: string, pattern: string): boolean {
+  const rx = new RegExp(
+    `^${pattern.replace(/[.*+?^${}()|[\]\\]/g, (c) => (c === "*" ? "[\\s\\S]*" : `\\${c}`))}$`,
+  );
+  return rx.test(key);
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/**
+ * True iff the block carries a Deco encrypted-secret ref anywhere in its tree.
+ * Prod serves those as `{"name": "MY_TOKEN", "encrypted": "3a714de1c8…"}`.
+ */
+export function hasEncryptedSecretRef(value: unknown): boolean {
+  if (Array.isArray(value)) return value.some(hasEncryptedSecretRef);
+  if (!isPlainObject(value)) return false;
+  if (typeof value.name === "string" && typeof value.encrypted === "string" && value.encrypted) {
+    return true;
+  }
+  return Object.values(value).some(hasEncryptedSecretRef);
+}
+
+/**
+ * Property paths whose name looks credential-shaped and whose value is a raw
+ * string — i.e. a secret in the clear rather than an `{name, encrypted}` ref.
+ * URLs and values with whitespace are excluded (endpoints, prose, templates).
+ */
+export function findPlaintextSecrets(value: unknown, prefix = ""): string[] {
+  const found: string[] = [];
+  const walk = (node: unknown, at: string): void => {
+    if (Array.isArray(node)) {
+      for (const [i, item] of node.entries()) walk(item, `${at}[${i}]`);
+      return;
+    }
+    if (!isPlainObject(node)) return;
+    for (const [prop, child] of Object.entries(node)) {
+      const at2 = at ? `${at}.${prop}` : prop;
+      if (
+        typeof child === "string" &&
+        child.length >= 12 &&
+        SECRET_PROP_RE.test(normalizeProp(prop)) &&
+        !/\s/.test(child) &&
+        !/^https?:\/\//i.test(child) &&
+        !/^\{\{.*\}\}$/.test(child)
+      ) {
+        found.push(at2);
+        continue;
+      }
+      walk(child, at2);
+    }
+  };
+  walk(value, prefix);
+  return found;
+}
+
+/** Fully URL-decode a block key or filename stem, for cross-scheme matching. */
+function canonicalKey(keyOrFile: string): string {
+  return decodeBlockNameWithPasses(keyOrFile).name;
+}
+
+/**
+ * Serialised on-disk form of a block: pretty-printed, so a PR diff shows the
+ * sections/props that actually changed instead of one 3 MB line.
+ */
+function serialize(block: unknown): string {
+  return `${JSON.stringify(block, null, 2)}\n`;
+}
+
+/**
+ * Key-sorted JSON, for *comparison only*. Writers of `.deco/blocks` disagree on
+ * formatting (the Studio daemon and the old bot minify, a hand-made sync PR
+ * pretty-prints) and on key order, so a byte compare reports a diff on a block
+ * whose content is identical — 124 of 432 blocks on a real site's first run.
+ * Compare semantically, write only real content changes.
+ */
+function stableStringify(value: unknown): string {
+  if (Array.isArray(value)) return `[${value.map(stableStringify).join(",")}]`;
+  if (!isPlainObject(value)) return JSON.stringify(value) ?? "null";
+  const entries = Object.keys(value)
+    .sort()
+    .map((k) => `${JSON.stringify(k)}:${stableStringify(value[k])}`);
+  return `{${entries.join(",")}}`;
+}
+
+// ------------------------------------------------------------------ fetch side
+
+/** Download and validate the remote decofile. Throws on any bad payload. */
+export async function fetchDecofile(
+  url: string,
+  opts: { maxBytes?: number; timeoutMs?: number } = {},
+): Promise<FetchResult> {
+  const maxBytes = opts.maxBytes ?? DEFAULT_MAX_BYTES;
+  const res = await fetch(url, {
+    redirect: "follow",
+    headers: { accept: "application/json" },
+    signal: AbortSignal.timeout(opts.timeoutMs ?? DEFAULT_TIMEOUT_MS),
+  });
+  if (!res.ok) throw new Error(`${url} responded ${res.status} ${res.statusText}`);
+
+  const contentType = res.headers.get("content-type") ?? "";
+  if (!contentType.includes("json")) {
+    throw new Error(`${url} served "${contentType || "no content-type"}", expected JSON`);
+  }
+  const declared = Number(res.headers.get("content-length") ?? Number.NaN);
+  if (Number.isFinite(declared) && declared > maxBytes) {
+    throw new Error(`${url} is ${declared} bytes, over the ${maxBytes} byte cap`);
+  }
+
+  const body = await res.text();
+  if (body.length > maxBytes) {
+    throw new Error(`${url} is ${body.length} bytes, over the ${maxBytes} byte cap`);
+  }
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(body);
+  } catch (e) {
+    throw new Error(`${url} did not return valid JSON: ${(e as Error).message}`);
+  }
+  if (!isPlainObject(parsed)) {
+    throw new Error(
+      `${url} returned ${Array.isArray(parsed) ? "an array" : typeof parsed}, expected a decofile object`,
+    );
+  }
+
+  return { blocks: parsed, revision: res.headers.get("etag") ?? undefined, bytes: body.length };
+}
+
+// ------------------------------------------------------------------ write side
+
+/**
+ * Materialise `remote` into `opts.out`, one file per block.
+ *
+ * Filenames are `encodeURIComponent(key) + ".json"` — the single-decode scheme
+ * the runtime's `parseBlockId` expects. When a file for the same *logical* key
+ * already exists under a different encoding (the `deco-sync-bot` wrote
+ * double-encoded names), that existing file is overwritten in place instead of
+ * a second, colliding one being created.
+ */
+export function writeDecofileToDir(remote: Record<string, unknown>, opts: PullOptions): PullReport {
+  const out = path.resolve(opts.out);
+  const deny = opts.deny ?? DEFAULT_DENY;
+  const report: PullReport = {
+    added: [],
+    updated: [],
+    unchanged: 0,
+    removed: [],
+    denied: [],
+    protectedSecretBlocks: [],
+    skipped: [],
+    plaintextSecrets: [],
+    remoteBlocks: Object.keys(remote).length,
+  };
+
+  fs.mkdirSync(out, { recursive: true });
+
+  // Index what is already on disk by fully-decoded key, so we overwrite legacy
+  // double-encoded filenames instead of duplicating them. A key can map to
+  // several files (the `deco-sync-bot` wrote `pages-A%2520B.json` where the
+  // manual sync wrote `pages-A%20B.json`).
+  const existingByKey = new Map<string, string[]>();
+  for (const file of fs.readdirSync(out)) {
+    if (!file.endsWith(".json")) continue;
+    const key = canonicalKey(file);
+    const list = existingByKey.get(key);
+    if (list) list.push(file);
+    else existingByKey.set(key, [file]);
+  }
+
+  const seen = new Set<string>();
+
+  for (const [key, block] of Object.entries(remote)) {
+    const canonical = canonicalKey(key);
+    seen.add(canonical);
+
+    if (deny.some((p) => matchesGlob(key, p) || matchesGlob(canonical, p))) {
+      report.denied.push(key);
+      continue;
+    }
+    if (!isPlainObject(block)) {
+      report.skipped.push(key);
+      continue;
+    }
+    if (!opts.allowSecretBlocks && hasEncryptedSecretRef(block)) {
+      report.protectedSecretBlocks.push(key);
+      continue;
+    }
+
+    // One existing file → write it in place (smallest diff, no rename churn).
+    // Several → converge on the canonical single-encoded name and drop the
+    // others: leaving a stale duplicate behind is not cosmetic, `pickWinner`
+    // in generate-blocks prefers the *more*-encoded filename, so the stale one
+    // would win the build.
+    const existing = existingByKey.get(canonical) ?? [];
+    const canonicalFile = `${encodeURIComponent(key)}.json`;
+    const file = existing.length === 1 ? existing[0] : canonicalFile;
+    const target = path.join(out, file);
+    // encodeURIComponent cannot emit a separator, but assert the boundary
+    // anyway: this writes to a git repo from a remote payload.
+    if (path.dirname(path.resolve(target)) !== out) {
+      throw new Error(`refusing to write block "${key}" outside ${out}`);
+    }
+
+    const secrets = findPlaintextSecrets(block);
+    for (const at of secrets) report.plaintextSecrets.push(`${key}.${at}`);
+
+    const duplicates = existing.filter((f) => f !== file);
+    if (!opts.dryRun) {
+      for (const dup of duplicates) fs.rmSync(path.join(out, dup));
+    }
+
+    const next = serialize(block);
+    const current = fs.existsSync(target) ? fs.readFileSync(target, "utf-8") : null;
+    let currentParsed: unknown;
+    try {
+      currentParsed = current === null ? undefined : JSON.parse(current);
+    } catch {
+      currentParsed = undefined; // unparseable local file — overwrite it
+    }
+    const sameContent =
+      current !== null && stableStringify(currentParsed) === stableStringify(block);
+    if (sameContent && duplicates.length === 0) {
+      report.unchanged++;
+      continue;
+    }
+    if (!opts.dryRun) fs.writeFileSync(target, next);
+    (current === null ? report.added : report.updated).push(key);
+  }
+
+  if (opts.prune) {
+    for (const [key, files] of existingByKey) {
+      if (seen.has(key)) continue;
+      if (deny.some((p) => matchesGlob(key, p))) {
+        report.denied.push(key);
+        continue;
+      }
+      // A local-only block holding credentials is site-owned (the migration put
+      // them there); upstream never had it, so its absence must not delete it.
+      if (!opts.allowSecretBlocks) {
+        const local = files.map((f) => {
+          try {
+            return JSON.parse(fs.readFileSync(path.join(out, f), "utf-8")) as unknown;
+          } catch {
+            return null;
+          }
+        });
+        if (local.some(hasEncryptedSecretRef)) {
+          report.protectedSecretBlocks.push(key);
+          continue;
+        }
+      }
+      if (!opts.dryRun) {
+        for (const f of files) fs.rmSync(path.join(out, f));
+      }
+      report.removed.push(key);
+    }
+  }
+
+  return report;
+}
+
+// -------------------------------------------------------------------- CLI
+
+interface CliOptions extends PullOptions {
+  url?: string;
+  maxBytes: number;
+  timeoutMs: number;
+  failOnPlaintextSecret: boolean;
+  json: boolean;
+  github: boolean;
+  help: boolean;
+}
+
+function parseArgs(argv: string[]): CliOptions {
+  const opts: CliOptions = {
+    out: ".deco/blocks",
+    maxBytes: DEFAULT_MAX_BYTES,
+    timeoutMs: DEFAULT_TIMEOUT_MS,
+    failOnPlaintextSecret: false,
+    json: false,
+    github: false,
+    help: false,
+  };
+  for (let i = 0; i < argv.length; i++) {
+    const flag = argv[i];
+    switch (flag) {
+      case "--url":
+        opts.url = argv[++i];
+        break;
+      case "--origin": {
+        const origin = (argv[++i] ?? "").replace(/\/+$/, "");
+        opts.url = origin ? `${origin}/.decofile` : undefined;
+        break;
+      }
+      case "--out":
+        opts.out = argv[++i] ?? opts.out;
+        break;
+      case "--deny":
+        opts.deny = (argv[++i] ?? "")
+          .split(",")
+          .map((s) => s.trim())
+          .filter(Boolean);
+        break;
+      case "--allow-secret-blocks":
+        opts.allowSecretBlocks = true;
+        break;
+      case "--prune":
+        opts.prune = true;
+        break;
+      case "--dry-run":
+        opts.dryRun = true;
+        break;
+      case "--fail-on-plaintext-secret":
+        opts.failOnPlaintextSecret = true;
+        break;
+      case "--max-bytes":
+        opts.maxBytes = Number(argv[++i]);
+        break;
+      case "--timeout-ms":
+        opts.timeoutMs = Number(argv[++i]);
+        break;
+      case "--json":
+        opts.json = true;
+        break;
+      case "--github":
+        opts.github = true;
+        break;
+      case "--help":
+      case "-h":
+        opts.help = true;
+        break;
+    }
+  }
+  return opts;
+}
+
+function showHelp(): void {
+  console.log(`
+  @decocms/blocks-cli — pull the production decofile into .deco/blocks/
+
+  Usage:
+    tsx pull-decofile.ts --origin https://www.minhaloja.com.br [options]
+
+  Options:
+    --origin <url>               Site origin; fetches <origin>/.decofile
+    --url <url>                  Full decofile URL (alternative to --origin)
+    --out <dir>                  Blocks directory (default: .deco/blocks)
+    --deny <globs>               Comma-separated key globs never overwritten
+                                 (default: ${DEFAULT_DENY.join(",")})
+    --allow-secret-blocks        Also overwrite blocks holding encrypted secrets
+    --prune                      Delete local blocks absent upstream
+    --dry-run                    Report only, write nothing
+    --fail-on-plaintext-secret   Exit 1 if a written block holds a raw credential
+    --max-bytes <n>              Payload cap (default: ${DEFAULT_MAX_BYTES})
+    --timeout-ms <n>             Fetch timeout (default: ${DEFAULT_TIMEOUT_MS})
+    --json                       Emit the report as JSON
+    --github                     Emit ::notice::/::error:: lines for Actions
+    --help, -h                   This message
+
+  Exit codes:
+    0   done          1   plaintext secret gate          2   usage/network error
+`);
+}
+
+function reportToText(report: PullReport): string {
+  const lines = [
+    `remote blocks: ${report.remoteBlocks}${report.bytes ? ` (${report.bytes} bytes)` : ""}${report.revision ? ` revision ${report.revision}` : ""}`,
+    `added ${report.added.length}  updated ${report.updated.length}  unchanged ${report.unchanged}  removed ${report.removed.length}`,
+    `denied ${report.denied.length}  secret-protected ${report.protectedSecretBlocks.length}  skipped ${report.skipped.length}`,
+  ];
+  for (const [label, keys] of [
+    ["added", report.added],
+    ["updated", report.updated],
+    ["removed", report.removed],
+  ] as const) {
+    for (const key of keys.slice(0, 50)) lines.push(`  ${label}: ${key}`);
+    if (keys.length > 50) lines.push(`  ${label}: … and ${keys.length - 50} more`);
+  }
+  return lines.join("\n");
+}
+
+async function main(): Promise<void> {
+  const opts = parseArgs(process.argv.slice(2));
+  if (opts.help) {
+    showHelp();
+    process.exit(0);
+  }
+  if (!opts.url) {
+    console.error("pull-decofile: --origin or --url is required (see --help)");
+    process.exit(2);
+  }
+
+  let fetched: FetchResult;
+  try {
+    fetched = await fetchDecofile(opts.url, { maxBytes: opts.maxBytes, timeoutMs: opts.timeoutMs });
+  } catch (e) {
+    console.error(`pull-decofile: ${(e as Error).message}`);
+    process.exit(2);
+  }
+
+  let report: PullReport;
+  try {
+    report = writeDecofileToDir(fetched.blocks, opts);
+  } catch (e) {
+    console.error(`pull-decofile: ${(e as Error).message}`);
+    process.exit(2);
+  }
+  report.revision = fetched.revision;
+  report.bytes = fetched.bytes;
+
+  process.stdout.write(
+    `${opts.json ? JSON.stringify({ url: opts.url, ...report }, null, 2) : reportToText(report)}\n`,
+  );
+
+  if (opts.github) {
+    process.stdout.write(
+      `::notice::decofile sync — +${report.added.length} ~${report.updated.length} -${report.removed.length} (${report.remoteBlocks} blocks upstream)\n`,
+    );
+    for (const at of report.plaintextSecrets) {
+      process.stdout.write(
+        `::error title=plaintext-secret::${at} looks like a credential in the clear\n`,
+      );
+    }
+  }
+
+  if (report.plaintextSecrets.length > 0 && opts.failOnPlaintextSecret) {
+    console.error(
+      `pull-decofile: ${report.plaintextSecrets.length} plaintext credential(s) in the pulled content — refusing to commit it. Move them to encrypted secrets upstream, or deny the block with --deny.`,
+    );
+    process.exit(1);
+  }
+  process.exit(0);
+}
+
+const isCjsEntry =
+  typeof require !== "undefined" && typeof module !== "undefined" && require.main === module;
+let isEsmEntry = false;
+try {
+  isEsmEntry =
+    typeof process !== "undefined" &&
+    Array.isArray(process.argv) &&
+    process.argv[1] !== undefined &&
+    import.meta.url === `file://${process.argv[1]}`;
+} catch {
+  // ignore in CJS
+}
+if (isCjsEntry || isEsmEntry) {
+  void main();
+}