@smoothbricks/cli 0.7.0 → 0.9.0

package/dist/wrangler/prepare-env.js

@@ -0,0 +1,253 @@
+/**
+ * Composable primitives for writing a project's own `prepare-env` script — the
+ * provisioning half of the wrangler setup flow (the `wrangler` monorepo pack owns
+ * the build-time half: the `wrangler-types` target + `.dev.vars.example`).
+ *
+ * `wrangler types --env-file .dev.vars.example` emits a machine-readable manifest
+ * that distinguishes committed public **vars** (literal-typed in `[env.<env>.vars]`)
+ * from **secrets** (string-typed, names in `.dev.vars.example`, values never in the
+ * repo). `readManifest` reads that split back so a script knows what to prompt for;
+ * the toml editors clone/blank/fill env blocks; the wrangler shell-outs provision.
+ *
+ * Import from a target's `scripts/prepare-env.ts`:
+ *   import * as pe from '@smoothbricks/cli/wrangler/prepare-env';
+ * Scaffold a starter with:  smoo wrangler scaffold <project>
+ *
+ * Prompt-agnostic by design: the module does the toml + wrangler work; the script
+ * brings its own prompts (e.g. @clack/prompts). Bun-only (uses `bun`'s `$`).
+ */
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { $ } from 'bun';
+import { parse } from 'smol-toml';
+// ── runtime narrowing (wrangler JSON + parsed toml are external data — no casts) ─
+export function isRecord(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+function escapeRe(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+// ── pure wrangler.toml editors (no I/O — unit-testable) ──────────────────────
+/** First `[env.<name>]` header, or `null` when the config declares no envs (top-level bindings only). */
+export function firstWranglerEnv(toml) {
+    const match = toml.match(/^\s*\[env\.([A-Za-z0-9_-]+)/m);
+    return match ? match[1] : null;
+}
+/** True if the toml declares `[env.<env>]`. */
+export function hasEnvBlock(toml, env) {
+    return new RegExp(`^\\[env\\.${escapeRe(env)}\\]`, 'm').test(toml);
+}
+/** A `[env.<env>.vars]` value, or null if unset/empty. Reads committed public config. */
+export function getVar(toml, env, name) {
+    const block = envRecord(toml, env);
+    const vars = isRecord(block?.vars) ? block.vars : {};
+    const value = vars[name];
+    return typeof value === 'string' && value ? value : null;
+}
+/** Set a `[env.<env>.vars]` value, preserving any trailing comment. Throws if the key isn't present (scaffold first). */
+export function setVar(toml, env, name, value) {
+    const re = new RegExp(`(\\[env\\.${escapeRe(env)}\\.vars\\][\\s\\S]*?\\n${escapeRe(name)} = )"[^"]*"`);
+    if (!re.test(toml)) {
+        throw new Error(`vars key "${name}" not found under [env.${env}.vars]`);
+    }
+    return toml.replace(re, (_m, prefix) => `${prefix}${JSON.stringify(value)}`);
+}
+/** The id written for `[[env.<env>.kv_namespaces]]` binding, or null if absent/empty. */
+export function getKvId(toml, env, binding) {
+    const block = envRecord(toml, env);
+    const rows = isRecord(block) && Array.isArray(block.kv_namespaces) ? block.kv_namespaces : [];
+    for (const row of rows) {
+        if (isRecord(row) && row.binding === binding && typeof row.id === 'string') {
+            return row.id || null;
+        }
+    }
+    return null;
+}
+/** Rewrite the `id = ...` line of the `[[env.<env>.kv_namespaces]]` table whose binding matches. Throws if absent. */
+export function setKvId(toml, env, binding, id, title) {
+    const re = new RegExp(`(\\[\\[env\\.${escapeRe(env)}\\.kv_namespaces\\]\\]\\s*\\n\\s*binding = "${escapeRe(binding)}"\\s*\\n\\s*id = )[^\\n]*`);
+    if (!re.test(toml)) {
+        throw new Error(`kv_namespaces binding "${binding}" not found under [env.${env}]`);
+    }
+    return toml.replace(re, `$1"${id}" # ${title}`);
+}
+/**
+ * Append a copy of the whole `[env.<from>]` … block-group (every `[env.<from>...]`
+ * table up to the next non-`from` env or EOF) rewritten for `<to>`. Returns the new
+ * toml. Throws if `<from>` is absent or `<to>` already exists (blank/fill instead).
+ */
+export function cloneEnvBlock(toml, from, to) {
+    if (!hasEnvBlock(toml, from))
+        throw new Error(`source [env.${from}] not found`);
+    if (hasEnvBlock(toml, to))
+        throw new Error(`target [env.${to}] already exists — blank/fill it instead`);
+    const lines = toml.split('\n');
+    const isFromHeader = (l) => new RegExp(`^\\[+env\\.${escapeRe(from)}(\\.|\\])`).test(l);
+    const isAnyEnvHeader = (l) => /^\[+env\.[A-Za-z0-9_-]+(\.|\])/.test(l);
+    const out = [];
+    let capturing = false;
+    for (const line of lines) {
+        if (isFromHeader(line)) {
+            capturing = true;
+            out.push(line);
+        }
+        else if (capturing && isAnyEnvHeader(line) && !isFromHeader(line)) {
+            capturing = false; // a different env began — stop
+        }
+        else if (capturing) {
+            out.push(line);
+        }
+    }
+    const cloned = out
+        .map((l) => l.replace(new RegExp(`(\\[+env\\.)${escapeRe(from)}(\\.|\\])`, 'g'), `$1${to}$2`))
+        .join('\n');
+    return `${toml.replace(/\s*$/, '')}\n\n${cloned}\n`;
+}
+/** Blank every `NAME = "..."` under `[env.<env>.vars]` whose key is in `keys` (env-specific values to re-fill). */
+export function blankEnvVars(toml, env, keys) {
+    let out = toml;
+    for (const key of keys) {
+        const re = new RegExp(`(\\[env\\.${escapeRe(env)}\\.vars\\][\\s\\S]*?\\n${escapeRe(key)} = )"[^"]*"`);
+        if (re.test(out))
+            out = out.replace(re, '$1""');
+    }
+    return out;
+}
+/** Blank every `id = ...` line under the env's `[[env.<env>.kv_namespaces]]` tables (per-env resource ids). */
+export function blankKvIds(toml, env) {
+    const re = new RegExp(`(\\[\\[env\\.${escapeRe(env)}\\.kv_namespaces\\]\\]\\s*\\n\\s*binding = "[^"]*"\\s*\\n\\s*id = )[^\\n]*`, 'g');
+    return toml.replace(re, '$1""');
+}
+/** Parse-guard: throws if `toml` no longer parses, so a bad edit can't be written to disk. */
+export function assertToml(toml) {
+    parse(toml);
+}
+/** Persist a toml string after confirming it still parses. */
+export function saveToml(path, toml) {
+    assertToml(toml);
+    writeFileSync(path, toml);
+}
+function envRecord(toml, env) {
+    const parsed = parse(toml);
+    const envs = isRecord(parsed) && isRecord(parsed.env) ? parsed.env : {};
+    const block = envs[env];
+    return isRecord(block) ? block : null;
+}
+/** Secret NAMES from a `.dev.vars.example` file (KEY=... / KEY="..."), ignoring comments/blanks. */
+export function parseDevVarsExample(text) {
+    const names = [];
+    for (const raw of text.split('\n')) {
+        const line = raw.trim();
+        if (!line || line.startsWith('#'))
+            continue;
+        const m = line.match(/^([A-Za-z_][A-Za-z0-9_]*)\s*=/);
+        if (m)
+            names.push(m[1]);
+    }
+    return names;
+}
+/**
+ * Read the vars/secrets split for `env` from `<root>/wrangler.toml` (public var
+ * keys) + `<root>/.dev.vars.example` (secret names). This is the "what to prompt
+ * for" manifest a prepare-env script derives its work from.
+ */
+export function readManifest(root, env) {
+    const toml = readFileSync(join(root, 'wrangler.toml'), 'utf8');
+    const block = envRecord(toml, env);
+    const varsRec = isRecord(block?.vars) ? block.vars : {};
+    const vars = Object.keys(varsRec);
+    const kvRows = isRecord(block) && Array.isArray(block.kv_namespaces) ? block.kv_namespaces : [];
+    const kvBindings = kvRows.flatMap((row) => (isRecord(row) && typeof row.binding === 'string' ? [row.binding] : []));
+    const examplePath = join(root, '.dev.vars.example');
+    const secrets = existsSync(examplePath) ? parseDevVarsExample(readFileSync(examplePath, 'utf8')) : [];
+    return { kvBindings, vars, secrets };
+}
+// ── PEM (a standard, reusable) ───────────────────────────────────────────────
+/** True if `value` looks like a PEM block (any `-----BEGIN ...-----`). */
+export function isPem(value) {
+    return /-----BEGIN [A-Z ]+-----/.test(value);
+}
+/** Read a `.pem` file (expanding a leading `~`) and assert it's a PEM block. Throws otherwise. */
+export function readPemFile(path) {
+    const resolved = path.replace(/^~/, process.env.HOME ?? '~');
+    const content = readFileSync(resolved, 'utf8');
+    if (!isPem(content))
+        throw new Error(`${path} is not a PEM (no -----BEGIN block)`);
+    return content;
+}
+/** Heuristic: does this secret name suggest file input (PEM/key)? Used to preselect a file prompt — never to change semantics. */
+export function looksLikeFileSecret(name) {
+    return /_PEM$|_KEY$|_CERT$/.test(name);
+}
+function asKvNamespaces(json) {
+    if (!Array.isArray(json))
+        return [];
+    const out = [];
+    for (const row of json) {
+        if (isRecord(row) && typeof row.id === 'string' && typeof row.title === 'string') {
+            out.push({ id: row.id, title: row.title });
+        }
+    }
+    return out;
+}
+function asSecretNames(json) {
+    if (!Array.isArray(json))
+        return [];
+    return json.flatMap((row) => (isRecord(row) && typeof row.name === 'string' ? [row.name] : []));
+}
+/** Best-effort ERROR line from a Bun ShellError (thrown on non-zero exit). */
+export function errText(err) {
+    if (!isRecord(err))
+        return 'unknown error';
+    const stderr = 'stderr' in err && err.stderr != null ? String(err.stderr) : '';
+    const exit = 'exitCode' in err ? String(err.exitCode) : '?';
+    return stderr.split('\n').find((l) => l.includes('ERROR')) ?? `exit ${exit}`;
+}
+/** Live KV namespaces on the account (`kv namespace list` emits a pure JSON array); `[]` when offline/unauthenticated. */
+export async function listNamespaces(cwd) {
+    try {
+        return asKvNamespaces(await $ `bunx wrangler kv namespace list`.cwd(cwd).quiet().json());
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Reuse the namespace whose title exactly matches `logical`, else create it. The
+ * id always comes from the structured `list` JSON (create prints freeform text),
+ * so we re-list rather than scrape. Returns the id, or null on failure.
+ */
+export async function ensureNamespace(logical, existing, cwd) {
+    const match = existing.find((n) => n.title === logical);
+    if (match)
+        return match.id;
+    try {
+        await $ `bunx wrangler kv namespace create ${logical}`.cwd(cwd).quiet();
+    }
+    catch (err) {
+        return errText(err).includes('already') ? (await reList(logical, cwd)) : null;
+    }
+    return reList(logical, cwd);
+}
+async function reList(logical, cwd) {
+    return (await listNamespaces(cwd)).find((n) => n.title === logical)?.id ?? null;
+}
+/** Current secret names on the worker for `env`; `[]` when none/unreachable (Cloudflare allows setting pre-deploy). */
+export async function listSecretNames(env, cwd) {
+    try {
+        return asSecretNames(await $ `bunx wrangler secret list --format json --env ${env}`.cwd(cwd).quiet().json());
+    }
+    catch {
+        return [];
+    }
+}
+/** `wrangler secret put <name> --env <env>` piping `value` on stdin (never a CLI arg). Returns success. */
+export async function putSecret(name, value, env, cwd) {
+    try {
+        await $ `bunx wrangler secret put ${name} --env ${env} < ${Buffer.from(value)}`.cwd(cwd).quiet();
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/wrangler/scaffold.d.ts

@@ -0,0 +1,7 @@
+export interface ScaffoldOptions {
+    /** Overwrite an existing scripts/prepare-env.ts. */
+    force?: boolean;
+}
+/** Write the starter script + wire the `prepare-env` nx target. Returns the script path. */
+export declare function scaffold(root: string, project: string, options?: ScaffoldOptions): string;
+//# sourceMappingURL=scaffold.d.ts.map

package/dist/wrangler/scaffold.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scaffold.d.ts","sourceRoot":"","sources":["../../src/wrangler/scaffold.ts"],"names":[],"mappings":"AAYA,MAAM,WAAW,eAAe;IAC9B,oDAAoD;IACpD,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAmMD,4FAA4F;AAC5F,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,eAAoB,GAAG,MAAM,CA2B7F"}

package/dist/wrangler/scaffold.js

@@ -0,0 +1,228 @@
+/**
+ * `smoo wrangler scaffold <project>` — write a starter `scripts/prepare-env.ts`
+ * into a wrangler project and wire its `prepare-env` nx target. The generated
+ * script imports the `@smoothbricks/cli/wrangler/prepare-env` primitives and
+ * derives its work at runtime from the project's manifest (wrangler.toml [vars] +
+ * .dev.vars.example), so it never drifts from what the worker declares.
+ */
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { join, relative } from 'node:path';
+import { getOrCreateRecord, recordProperty, writeJsonObject } from '../lib/json.js';
+import { getWorkspacePackageManifests } from '../lib/workspace.js';
+/** Locate a workspace package by nx name, package name, or relative path; must have a wrangler.toml. */
+function resolveProject(root, project) {
+    const manifests = getWorkspacePackageManifests(root);
+    const match = manifests.find((m) => {
+        const nx = recordProperty(m.json, 'nx');
+        const nxName = nx && typeof nx.name === 'string' ? nx.name : null;
+        return nxName === project || m.name === project || relative(root, m.path) === project;
+    });
+    if (!match) {
+        const known = manifests.map((m) => recordProperty(m.json, 'nx')?.name ?? m.name).join(', ');
+        throw new Error(`project "${project}" not found. Known: ${known}`);
+    }
+    const dir = match.path; // WorkspacePackageManifest.path is absolute
+    if (!existsSync(join(dir, 'wrangler.toml'))) {
+        throw new Error(`"${project}" has no wrangler.toml — not a wrangler project`);
+    }
+    return { dir, label: relative(root, dir), packageJsonPath: match.packageJsonPath, json: match.json };
+}
+/** The generated starter script — generic, manifest-driven, prompt-batteries included. */
+function renderScript(projectName) {
+    return `#!/usr/bin/env bun
+/**
+ * Prepare a deploy environment for ${projectName}. Generated by \`smoo wrangler scaffold\`.
+ *
+ * Provisions what \`wrangler deploy\` assumes already exists, idempotently:
+ *   - KV namespaces the worker binds (ids written into wrangler.toml)
+ *   - public [env.<env>.vars] (committed config the deploy applies)
+ *   - secrets (wrangler secret put; values never touch the repo)
+ *
+ * Work is derived from the manifest (wrangler.toml [vars] + .dev.vars.example),
+ * so it stays in sync with what the worker declares. Customize the app-specific
+ * bits below (KV title convention; any secret that feeds >1 binding).
+ *
+ * Usage:
+ *   bun scripts/prepare-env.ts <env>            # provision (staging | production | …)
+ *   bun scripts/prepare-env.ts <env> --check    # report state, no writes
+ */
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import * as p from '@clack/prompts';
+import * as pe from '@smoothbricks/cli/wrangler/prepare-env';
+
+const ROOT = resolve(import.meta.dir, '..');
+const WRANGLER = resolve(ROOT, 'wrangler.toml');
+const readToml = () => readFileSync(WRANGLER, 'utf8');
+
+// App-specific: the account-level logical title for a KV binding. Default is
+// lowercase + underscores→dashes; edit if your namespaces are named differently.
+function kvTitle(binding: string, env: string): string {
+  return \`\${binding.toLowerCase().replace(/_/g, '-')}-\${env}\`;
+}
+
+function bail<T>(v: T | symbol): asserts v is T {
+  if (p.isCancel(v)) {
+    p.cancel('Aborted — anything already provisioned stays; re-run to continue (idempotent).');
+    process.exit(1);
+  }
+}
+
+async function checkMode(env: string): Promise<void> {
+  const toml = readToml();
+  const { kvBindings, vars, secrets } = pe.readManifest(ROOT, env);
+  p.log.info(\`env block [env.\${env}]: \${pe.hasEnvBlock(toml, env) ? '✓ present' : '✗ missing'}\`);
+  const live = await pe.listNamespaces(ROOT);
+  for (const binding of kvBindings) {
+    const inToml = pe.getKvId(toml, env, binding);
+    const liveId = live.find((n) => n.title === kvTitle(binding, env))?.id ?? null;
+    p.log.message(\`  KV \${binding}: \${!liveId ? '✗ not created' : inToml === liveId ? \`✓ \${liveId}\` : \`⚠ drift (live \${liveId}, toml \${inToml ?? 'unset'})\`}\`);
+  }
+  for (const name of vars) {
+    p.log.message(\`  var \${name}: \${pe.getVar(toml, env, name) ? '✓ set' : '✗ empty'}\`);
+  }
+  const set = await pe.listSecretNames(env, ROOT);
+  for (const name of secrets) {
+    p.log.message(\`  secret \${name}: \${set.includes(name) ? '✓ set' : '✗ missing'}\`);
+  }
+}
+
+async function main(): Promise<void> {
+  const env = process.argv.slice(2).find((a) => !a.startsWith('-'));
+  if (!env) {
+    console.error('usage: bun scripts/prepare-env.ts <env> [--check]');
+    process.exit(1);
+  }
+  const check = process.argv.includes('--check');
+  p.intro(\`${projectName} · prepare \${env}\${check ? ' (check)' : ''}\`);
+
+  if (check) {
+    await checkMode(env);
+    p.outro(\`check complete for "\${env}" — nothing changed\`);
+    return;
+  }
+
+  let toml = readToml();
+
+  // 0. Env block. If missing, offer to clone an existing env and blank its
+  //    per-env values (KV ids), then fill below.
+  if (!pe.hasEnvBlock(toml, env)) {
+    const from = pe.firstWranglerEnv(toml);
+    if (from && (await p.confirm({ message: \`No [env.\${env}] — clone from [env.\${from}]?\` })) === true) {
+      toml = pe.blankKvIds(pe.cloneEnvBlock(toml, from, env), env);
+      pe.saveToml(WRANGLER, toml);
+      p.log.success(\`cloned [env.\${from}] → [env.\${env}] (KV ids blanked; edit domain-specific vars below)\`);
+    } else {
+      p.log.warn(\`Add an [env.\${env}] block to wrangler.toml first, then re-run.\`);
+      return;
+    }
+  }
+
+  const { kvBindings, vars, secrets } = pe.readManifest(ROOT, env);
+
+  // 1. KV namespaces → ids into the toml.
+  const live = await pe.listNamespaces(ROOT);
+  for (const binding of kvBindings) {
+    const s = p.spinner();
+    s.start(\`KV \${binding}\`);
+    const id = await pe.ensureNamespace(kvTitle(binding, env), live, ROOT);
+    if (!id) { s.stop(\`✗ \${binding}\`); continue; }
+    toml = pe.setKvId(toml, env, binding, id, kvTitle(binding, env));
+    pe.saveToml(WRANGLER, toml);
+    s.stop(\`✓ \${binding} → \${id}\`);
+  }
+
+  // 2. Public vars → [env.<env>.vars] (committed, applied by deploy). Enter keeps
+  //    current; a same-named env var overrides (CI).
+  if ((await p.confirm({ message: \`Set public vars for "\${env}"?\` })) === true) {
+    for (const name of vars) {
+      const current = pe.getVar(toml, env, name);
+      const preset = process.env[name]?.trim();
+      let value: string;
+      if (preset) {
+        value = preset;
+        p.log.info(\`\${name}: from environment\`);
+      } else {
+        const raw = await p.text({ message: \`\${name}:\`, placeholder: current ? 'Enter to keep current' : 'Enter to skip', initialValue: current ?? '' });
+        bail(raw);
+        value = raw.trim();
+      }
+      if (!value || value === current) continue;
+      toml = pe.setVar(toml, env, name, value);
+      pe.saveToml(WRANGLER, toml);
+    }
+  }
+
+  // 3. Secrets → wrangler secret put (values never in the repo). File-or-paste;
+  //    PEM validated by content. Skip-if-set unless you choose to replace.
+  const alreadySet = await pe.listSecretNames(env, ROOT);
+  if ((await p.confirm({ message: \`Set secrets for "\${env}"?\` })) === true) {
+    for (const name of secrets) {
+      const preset = process.env[name]?.trim();
+      if (alreadySet.includes(name) && !preset) {
+        const replace = await p.confirm({ message: \`\${name} already set — replace?\`, initialValue: false });
+        bail(replace);
+        if (!replace) { p.log.info(\`kept \${name}\`); continue; }
+      }
+      let value: string;
+      if (preset) {
+        value = preset;
+      } else if (pe.looksLikeFileSecret(name)) {
+        const path = await p.text({ message: \`\${name} — path to file:\`, placeholder: 'Enter to skip' });
+        bail(path);
+        if (!path.trim()) continue;
+        value = pe.readPemFile(path.trim());
+      } else {
+        const raw = await p.password({ message: \`\${name}:\` });
+        bail(raw);
+        value = raw.trim();
+        if (!value) continue;
+        if (pe.isPem(value) === false && /KEY|PEM|CERT/.test(name) && value.startsWith('~')) {
+          value = pe.readPemFile(value);
+        }
+      }
+      const s = p.spinner();
+      s.start(\`secret \${name}\`);
+      const ok = await pe.putSecret(name, value, env, ROOT);
+      s.stop(\`\${ok ? '✓' : '✗'} \${name}\`);
+    }
+    // Verify: re-list and flag any we set that didn't land.
+    const after = await pe.listSecretNames(env, ROOT);
+    const missing = secrets.filter((n) => !after.includes(n));
+    if (missing.length) p.log.warn(\`not listed afterwards — verify manually: \${missing.join(', ')}\`);
+  }
+
+  p.outro(\`"\${env}" prepared — re-run anytime (idempotent) · inspect with --check · then deploy\`);
+}
+
+if (import.meta.main) {
+  await main();
+}
+`;
+}
+/** Write the starter script + wire the `prepare-env` nx target. Returns the script path. */
+export function scaffold(root, project, options = {}) {
+    const { dir, label, packageJsonPath, json } = resolveProject(root, project);
+    const scriptsDir = join(dir, 'scripts');
+    const scriptPath = join(scriptsDir, 'prepare-env.ts');
+    const existed = existsSync(scriptPath);
+    if (existed && !options.force) {
+        throw new Error(`${label}/scripts/prepare-env.ts already exists — pass --force to overwrite`);
+    }
+    mkdirSync(scriptsDir, { recursive: true });
+    writeFileSync(scriptPath, renderScript(project));
+    console.log(`${existed ? 'overwrote' : 'created'}      ${label}/scripts/prepare-env.ts`);
+    // Wire the nx target (idempotent).
+    const nx = getOrCreateRecord(json, 'nx');
+    const targets = getOrCreateRecord(nx, 'targets');
+    if (!recordProperty(targets, 'prepare-env')) {
+        targets['prepare-env'] = {
+            executor: 'nx:run-commands',
+            options: { command: 'bun scripts/prepare-env.ts', cwd: '{projectRoot}' },
+        };
+        writeJsonObject(packageJsonPath, json);
+        console.log(`updated       ${label}/package.json prepare-env target`);
+    }
+    console.log(`\nnext: fill secret NAMES in ${label}/.dev.vars.example, then\n  bunx nx run ${project}:prepare-env -- <env>`);
+    return scriptPath;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@smoothbricks/cli",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "type": "module",
   "description": "SmoothBricks monorepo automation CLI",
   "bin": {
@@ -33,6 +33,13 @@
       "development": "./src/monorepo/git-config.ts",
       "import": "./dist/monorepo/git-config.js",
       "default": "./dist/monorepo/git-config.js"
+    },
+    "./wrangler/prepare-env": {
+      "types": "./dist/wrangler/prepare-env.d.ts",
+      "bun": "./src/wrangler/prepare-env.ts",
+      "development": "./src/wrangler/prepare-env.ts",
+      "import": "./dist/wrangler/prepare-env.js",
+      "default": "./dist/wrangler/prepare-env.js"
     }
   },
   "files": [
@@ -51,6 +58,7 @@
     "publint": "^0.3.18",
     "semver": "^7.7.4",
     "sherif": "^1.11.1",
+    "smol-toml": "^1.6.1",
     "tslib": "^2.8.1"
   },
   "devDependencies": {

package/src/cli.ts

@@ -3,6 +3,7 @@ import { variants } from './generate/index.js';
 import { cliPackageVersion } from './lib/cli-package.js';
 import { findRepoRoot } from './lib/run.js';
 import { resolvePrConflicts } from './pr/index.js';
+import { scaffold } from './wrangler/scaffold.js';
 
 export async function runCli(argv = process.argv.slice(2)): Promise<void> {
   const program = buildProgram();
@@ -354,6 +355,15 @@ function buildProgram(): Command {
       }
     });
 
+  const wrangler = program.command('wrangler').description('Cloudflare wrangler project helpers');
+  wrangler
+    .command('scaffold <project>')
+    .description('Write a starter scripts/prepare-env.ts (manifest-driven) and wire its nx target')
+    .option('--force', 'overwrite an existing scripts/prepare-env.ts')
+    .action(async (project: string, options: { force?: boolean }) => {
+      scaffold(await findRepoRoot(), project, { force: options.force });
+    });
+
   return program;
 }
 

package/src/monorepo/managed-files.test.ts

@@ -1,5 +1,13 @@
 import { describe, expect, it } from 'bun:test';
-import { LOCAL_SECTION_MARKER, splitLocalSectionForTest } from './managed-files.js';
+import fc from 'fast-check';
+import {
+  extractInlineLocalBlocksForTest,
+  INLINE_LOCAL_BEGIN,
+  INLINE_LOCAL_END,
+  LOCAL_SECTION_MARKER,
+  reinsertInlineLocalBlocksForTest,
+  splitLocalSectionForTest,
+} from './managed-files.js';
 
 const MANAGED = '# managed content\npath merge=driver\n';
 
@@ -26,3 +34,95 @@ describe('managed-file local sections', () => {
     expect(localTail.startsWith(LOCAL_SECTION_MARKER)).toBe(true);
   });
 });
+
+describe('managed-file inline local blocks', () => {
+  it('content with no inline markers extracts as fully managed, no blocks', () => {
+    const { withoutInline, blocks } = extractInlineLocalBlocksForTest(MANAGED);
+    expect(withoutInline).toBe(MANAGED);
+    expect(blocks).toEqual([]);
+  });
+
+  it('a wrapped block is extracted and removed, anchored on the preceding line', () => {
+    const current = ['a:', '  - one', '  - two', INLINE_LOCAL_BEGIN, '  - repo-owned', INLINE_LOCAL_END, 'b:'].join(
+      '\n',
+    );
+    const { withoutInline, blocks } = extractInlineLocalBlocksForTest(current);
+    expect(withoutInline).toBe(['a:', '  - one', '  - two', 'b:'].join('\n'));
+    expect(blocks).toEqual([{ anchor: '  - two', lines: '  - repo-owned' }]);
+  });
+
+  it('multiple blocks each anchor to their own preceding line', () => {
+    const current = [
+      'x',
+      INLINE_LOCAL_BEGIN,
+      'first',
+      INLINE_LOCAL_END,
+      'y',
+      INLINE_LOCAL_BEGIN,
+      'second',
+      INLINE_LOCAL_END,
+      'z',
+    ].join('\n');
+    const { withoutInline, blocks } = extractInlineLocalBlocksForTest(current);
+    expect(withoutInline).toBe(['x', 'y', 'z'].join('\n'));
+    expect(blocks).toEqual([
+      { anchor: 'x', lines: 'first' },
+      { anchor: 'y', lines: 'second' },
+    ]);
+  });
+
+  it('a begin marker with no preceding line throws rather than silently dropping content', () => {
+    const current = [INLINE_LOCAL_BEGIN, 'orphan', INLINE_LOCAL_END].join('\n');
+    expect(() => extractInlineLocalBlocksForTest(current)).toThrow(/no preceding anchor/);
+  });
+
+  it('an unterminated begin marker throws rather than silently dropping content', () => {
+    const current = ['a', INLINE_LOCAL_BEGIN, 'unterminated'].join('\n');
+    expect(() => extractInlineLocalBlocksForTest(current)).toThrow(/no matching/);
+  });
+
+  it('reinserting into fresh content with no blocks is a no-op', () => {
+    expect(reinsertInlineLocalBlocksForTest(MANAGED, [])).toBe(MANAGED);
+  });
+
+  it('reinserting splices the block back after its anchor in freshly rendered content', () => {
+    const fresh = ['a:', '  - one', '  - two', 'b:'].join('\n');
+    const result = reinsertInlineLocalBlocksForTest(fresh, [{ anchor: '  - two', lines: '  - repo-owned' }]);
+    expect(result).toBe(
+      ['a:', '  - one', '  - two', INLINE_LOCAL_BEGIN, '  - repo-owned', INLINE_LOCAL_END, 'b:'].join('\n'),
+    );
+  });
+
+  it("reinserting refuses when the anchor no longer appears — never silently drops the repo's customization", () => {
+    const fresh = ['a:', '  - one', 'b:'].join('\n'); // '  - two' is gone
+    expect(() => reinsertInlineLocalBlocksForTest(fresh, [{ anchor: '  - two', lines: '  - repo-owned' }])).toThrow(
+      /no longer matches/,
+    );
+  });
+
+  it('property: extract then reinsert round-trips to the original for unique, single-occurrence anchors', () => {
+    // Lines that can serve as anchors: non-empty, not a marker, and each drawn
+    // from a small alphabet so uniqueness is checkable — the round-trip only
+    // holds when an anchor line occurs exactly once in the managed section
+    // (reinsert finds the FIRST occurrence by design, same as the real file
+    // shape: comments/patterns are unique in practice).
+    const linePool = fc.constantFrom('alpha', 'beta', 'gamma', 'delta', 'epsilon', 'zeta');
+    fc.assert(
+      fc.property(
+        fc.uniqueArray(linePool, { minLength: 1, maxLength: 6 }),
+        fc.array(fc.string(), { maxLength: 3 }),
+        (anchors, blockLinesFlat) => {
+          const blockLines = blockLinesFlat.length > 0 ? [blockLinesFlat.join('|') || 'x'] : ['x'];
+          const fresh = anchors.join('\n');
+          const withBlocks = anchors
+            .map((anchor) => [anchor, INLINE_LOCAL_BEGIN, ...blockLines, INLINE_LOCAL_END].join('\n'))
+            .join('\n');
+          const { withoutInline, blocks } = extractInlineLocalBlocksForTest(withBlocks);
+          expect(withoutInline).toBe(fresh);
+          const reinserted = reinsertInlineLocalBlocksForTest(fresh, blocks);
+          expect(reinserted).toBe(withBlocks);
+        },
+      ),
+    );
+  });
+});