@sqlanvil/cli 1.23.0 → 1.25.0

package/README.md

@@ -4,7 +4,7 @@
 
 SQLAnvil is an open-source fork of [Dataform OSS](https://github.com/dataform-co/dataform) (Apache 2.0), extended with first-class PostgreSQL, Supabase, and MySQL/MariaDB support. Define your data transformations in SQLX, have SQLAnvil compile them to idiomatic SQL for your warehouse, and run, validate, and document the whole DAG from one CLI.
 
-> **SQLAnvil is not affiliated with or endorsed by Google.** The Dataform name and related marks are trademarks of Google LLC. See [NOTICE](NOTICE) for attribution.
+> **SQLAnvil is not affiliated with or endorsed by Google.** The Dataform name and related marks are trademarks of Google LLC. See [NOTICE](https://github.com/SQLAnvil/sqlanvil/blob/main/NOTICE) for attribution.
 
 ---
 
@@ -86,7 +86,7 @@ Full documentation at **[sqlanvil.com/docs](https://sqlanvil.com/docs/)**.
 - [Validate](https://sqlanvil.com/docs/guides/validate/) · [Named Environments](https://sqlanvil.com/docs/guides/environments/) · [Artifacts & Catalog](https://sqlanvil.com/docs/guides/artifacts/)
 - [Configs Reference](https://sqlanvil.com/docs/reference/configs/) · [What's New](https://sqlanvil.com/docs/whats-new/)
 
-Writing sqlanvil projects with an AI agent? Point it at [`AGENTS.md`](AGENTS.md) — it corrects
+Writing sqlanvil projects with an AI agent? Point it at [`AGENTS.md`](https://github.com/SQLAnvil/sqlanvil/blob/main/AGENTS.md) — it corrects
 the Dataform/BigQuery priors that otherwise produce broken sqlanvil code. Contributor/design
 docs live in the separate [`sqlanvil/docs`](https://github.com/sqlanvil/docs) repo.
 
@@ -123,12 +123,12 @@ bazel test //core/... //cli/...
 ```
 
 A Docker-based build container (`./scripts/docker-bazel`) remains available as an optional
-hermetic environment. See [contributing.md](contributing.md) for full instructions.
+hermetic environment. See [contributing.md](https://github.com/SQLAnvil/sqlanvil/blob/main/contributing.md) for full instructions.
 
 ---
 
 ## License
 
-Apache License 2.0. See [LICENSE](LICENSE) and [NOTICE](NOTICE).
+Apache License 2.0. See [LICENSE](https://github.com/SQLAnvil/sqlanvil/blob/main/LICENSE) and [NOTICE](https://github.com/SQLAnvil/sqlanvil/blob/main/NOTICE).
 
 SQLAnvil is a derivative of Dataform OSS (originally developed by Dataform Co and contributed to by Google LLC). It has been fully renamed and extended with first-class PostgreSQL/Supabase/MySQL support. Licensed under Apache License 2.0.

package/bundle.js

@@ -49315,10 +49315,25 @@ function unknownToValueShallow(raw) {
 })();
 
 const nativeRequire = typeof __webpack_require__ === "function" ? __non_webpack_require__ : require;
+function globToRegExp(pattern) {
+    const escaped = pattern.replace(/[.*+?^${}()|[\]\\]/g, "\\$&").replace(/\\\*/g, ".*");
+    return new RegExp(`^${escaped}$`);
+}
 function matchPatterns(patterns, values) {
     const fullyQualifiedActions = [];
     patterns.forEach(pattern => {
-        if (pattern.includes(".")) {
+        if (pattern.includes("*")) {
+            const regExp = globToRegExp(pattern);
+            const scope = pattern.includes(".")
+                ? values
+                : values.map(value => value.split(".").slice(-1)[0]);
+            values.forEach((value, i) => {
+                if (regExp.test(scope[i])) {
+                    fullyQualifiedActions.push(value);
+                }
+            });
+        }
+        else if (pattern.includes(".")) {
             if (values.includes(pattern)) {
                 fullyQualifiedActions.push(pattern);
             }
@@ -50606,7 +50621,7 @@ function collectEvaluationQueries(queryOrAction, concatenate, queryModifier = (q
         .filter(validationQuery => !!validationQuery.query);
 }
 
-const version = "1.23.0";
+const version = "1.25.0";
 const dataformVersion = "3.0.61";
 
 async function build(compiledGraph, runConfig, dbadapter) {
@@ -50987,6 +51002,142 @@ async function test$1(dbadapter, timeoutMs = 10000) {
     }
 }
 
+function claudeMdBridgeContents() {
+    return "@AGENTS.md\n";
+}
+function agentsMdContents(options) {
+    const { warehouse, defaultDataset, version, converted } = options;
+    const isPostgresLike = warehouse === "postgres" || warehouse === "supabase";
+    const isSupabase = warehouse === "supabase";
+    const isMysql = warehouse === "mysql";
+    const sections = [];
+    sections.push(`<!-- generated by sqlanvil ${version} — this file is yours; edit freely -->
+
+# SQLAnvil project — guide for coding agents
+
+This is a **SQLAnvil** data project (warehouse: **${warehouse}**, default dataset/schema:
+\`${defaultDataset}\`). SQLAnvil is a fork of Dataform, so Dataform instincts are mostly
+right: \`.sqlx\` files, \`config {}\` blocks, \`\${ref()}\`, \`\${self()}\`, declarations,
+assertions, tags, incremental tables, and \`pre_operations\`/\`post_operations\` all work the
+same. The rules below are where the differences bite.
+
+## The essentials
+
+- The CLI is \`sqlanvil\` (\`npm i -g @sqlanvil/cli\`) — there is no \`dataform\` CLI and no
+  npm scripts in this project.
+- \`workflow_settings.yaml\` pins \`sqlanvilCoreVersion:\` — sqlanvil's OWN SemVer line, NOT
+  \`dataformCoreVersion:\`.
+- Credentials live in the gitignored \`.df-credentials.json\`. Never commit it; never put
+  secrets in \`workflow_settings.yaml\`.
+- The statement separator in \`operations\` / \`pre_operations\` / \`post_operations\` is
+  \`---\` on its own line — NEVER \`;\`. Dollar-quoted bodies (\`$$ … ; … $$\`) survive
+  intact. A \`table\`/\`view\` model body is exactly ONE \`SELECT\` — no \`---\`.
+- Procedures, functions, triggers, grants, extensions → \`type: "operations"\` (there is no
+  dedicated action type).
+- Two different \`uniqueKey\`s: top-level \`uniqueKey\` on an incremental is the merge/upsert
+  key; \`assertions: { uniqueKey }\` generates a data-quality assertion. They are independent.
+- Always reference tables with \`\${ref("name")}\` — never hardcoded paths. Declare external
+  tables (\`type: "declaration"\`) before ref'ing them.
+- Document every table: \`description:\` + \`columns: {}\` compile to real comments.
+
+## Commands
+
+\`\`\`bash
+sqlanvil compile .
+sqlanvil validate . --credentials .df-credentials.json   # planner-checks the whole DAG without executing — run this before every run
+sqlanvil run . --credentials .df-credentials.json
+sqlanvil run . --credentials .df-credentials.json --actions <name> --include-deps
+sqlanvil test . --credentials .df-credentials.json
+\`\`\`
+
+\`target/\` holds compile/run artifacts (queryable via \`sqlanvil query\`/\`inspect\`) — keep
+it gitignored.`);
+    if (isPostgresLike) {
+        sections.push(`## ${isSupabase ? "Supabase/PostgreSQL" : "PostgreSQL"} specifics
+
+- \`.df-credentials.json\` is a FLAT object with exactly \`host port database user password
+  sslMode defaultSchema\` — not nested under a key, not \`username\`/\`databaseName\`/\`ssl\`.${isSupabase
+            ? `
+  Use the Session pooler host (\`aws-…pooler.supabase.com\`, user \`postgres.<project-ref>\`,
+  port 5432): the direct \`db.<ref>.supabase.co\` host is IPv6-only and fails on most networks.`
+            : ""}
+- Storage, indexes, and partitioning are first-class in the \`postgres: {}\` config block —
+  never hand-roll \`CREATE INDEX\` or \`SET (fillfactor …)\` in \`post_operations\`.
+- Index \`method\` is a NUMERIC enum (\`BTREE=0, HASH=1, GIN=2, GIST=3, BRIN=4\`) — omit it
+  for btree; the string \`method: "btree"\` fails the config check. \`opclass\` is a single
+  string, not an array.
+- No BigQuery-isms: \`bigquery: {}\`, \`partitionBy\`, \`clusterBy\`, \`OPTIONS(...)\` — use
+  \`postgres: { partition: {...}, indexes: [...] }\` (partition \`kind\`: RANGE=0, LIST=1,
+  HASH=2).
+- Materialized views: \`type: "view", materialized: true\` (+ optional \`postgres: {
+  refreshPolicy: "on_dependency_change", noData, indexes }\`). Default is drop+recreate each
+  run; in-place refresh does not pick up definition changes.
+- One-time DDL on incrementals (e.g. \`ADD PRIMARY KEY\`) must be wrapped in
+  \`\${when(!incremental(), \\\`…\\\`)}\` — an unwrapped \`post_operations\` block re-runs on
+  EVERY append and errors the second time.
+- Read tables in OTHER warehouses via named \`connections:\` in \`workflow_settings.yaml\`
+  plus a \`connection:\`-tagged declaration with \`columnTypes\` in POSTGRES types — scaffold
+  it with \`sqlanvil introspect <connection> <schema.table>\`. Never hand-write FDW/foreign
+  tables.${isSupabase
+            ? `
+- Supabase extras: the \`supabase: {}\` block (\`enableRls\`, \`vectors\`) and dedicated
+  action types \`rlsPolicy\`, \`realtimePublication\`, \`vectorIndex\`. \`enableRls\` only
+  flips RLS on — declare policies via \`rlsPolicy\` actions.`
+            : ""}`);
+    }
+    if (isMysql) {
+        sections.push(`## MySQL/MariaDB specifics (several Postgres rules INVERT here)
+
+- \`.df-credentials.json\` is a FLAT object with exactly \`host port database user password
+  sslMode\` — no \`defaultSchema\` (MySQL's "schema" IS the database).
+- Use the \`mysql: {}\` config block for indexes, table options (\`engine\`, \`charset\`,
+  \`rowFormat\`), and partitioning — never \`postgres: {}\` (wrong dialect, silently ignored).
+- An incremental's \`uniqueKey\` compiles to \`INSERT … ON DUPLICATE KEY UPDATE\` and the
+  adapter AUTO-CREATES the matching unique index — do not add your own PK/unique index for
+  the merge.
+- \`materialized: true\` is an emulated snapshot (drop + CTAS each run), not a native
+  matview; no \`refreshPolicy\`/\`noData\`.
+- Backtick-quote identifiers in raw DDL; never \`DELIMITER\` (client-only directive — the
+  \`---\` separator already keeps \`;\` bodies intact).
+- A mysql warehouse cannot read cross-warehouse \`connections:\` (single write warehouse;
+  MySQL works as a SOURCE for a Postgres/Supabase project, not the other way).`);
+    }
+    const commentMechanics = isPostgresLike
+        ? "`COMMENT ON TABLE|VIEW|MATERIALIZED VIEW|COLUMN`"
+        : isMysql
+            ? "table/column comments (tables + incrementals only — MySQL views can't carry comments)"
+            : "table + column descriptions (nested fields included)";
+    const constraintNote = warehouse === "bigquery"
+        ? "append `NOT ENFORCED` (BigQuery stores them as catalog metadata for query engines)"
+        : "real enforced constraints";
+    sections.push(`## Metadata for AI/BI engines
+
+- \`description:\` + \`columns: {}\` persist into the warehouse catalog on every run as
+  ${commentMechanics} — BI copilots and text-to-SQL agents read them back from there. Name
+  join targets in column descriptions (\`customer_id: "Foreign key to
+  public.customers.customer_id."\`).
+- PK/FK constraints go in \`post_operations\` (no config field for them) — ${constraintNote};
+  on an incremental, wrap the \`ALTER\` in \`\${when(!incremental(), \\\`…\\\`)}\`.
+- \`assertions: { uniqueKey | uniqueKeys: [[…],[…]], nonNull, rowConditions }\` make key
+  claims TESTED on every run (\`uniqueKey\` and \`uniqueKeys\` are mutually exclusive).
+- Guide: https://sqlanvil.com/docs/guides/metadata/`);
+    if (converted) {
+        sections.push(`## This project was converted from Dataform
+
+- Work the to-do list in \`migration-report.md\` (machine-readable twin:
+  \`migration-report.json\`). Inline \`SQLANVIL-MIGRATE:\` markers flag every rewritten or
+  questionable spot.
+- \`sqlanvil validate\` is the completion loop — converge on all-PASS.
+- The original Dataform repo was read-only during conversion and remains the rollback path.`);
+    }
+    sections.push(`---
+
+Docs: https://sqlanvil.com/docs (agent bundle: https://sqlanvil.com/llms.txt) · Full
+authoring skill: \`npx skills add SQLAnvil/agent-skills\` · Hosted CI/scheduling:
+https://app.sqlanvil.com (remote MCP server at \`/api/mcp\`).`);
+    return sections.join("\n\n") + "\n";
+}
+
 const gitIgnoreContents = `
 ${CREDENTIALS_FILENAME}
 .df-credentials*.json
@@ -51084,6 +51235,20 @@ async function init(projectDir, projectConfig, options = {}) {
     filesWritten.push(workflowSettingsYamlPath);
     fs__namespace$1.writeFileSync(gitignorePath, gitIgnoreContents);
     filesWritten.push(gitignorePath);
+    const agentsMdPath = path__namespace.join(projectDir, "AGENTS.md");
+    if (!fs__namespace$1.existsSync(agentsMdPath)) {
+        fs__namespace$1.writeFileSync(agentsMdPath, agentsMdContents({
+            warehouse,
+            defaultDataset: workflowSettings.defaultDataset || "public",
+            version
+        }));
+        filesWritten.push(agentsMdPath);
+    }
+    const claudeMdPath = path__namespace.join(projectDir, "CLAUDE.md");
+    if (!fs__namespace$1.existsSync(claudeMdPath)) {
+        fs__namespace$1.writeFileSync(claudeMdPath, claudeMdBridgeContents());
+        filesWritten.push(claudeMdPath);
+    }
     if (!isBigQuery) {
         fs__namespace$1.writeFileSync(path__namespace.join(projectDir, CREDENTIALS_FILENAME), (_a = options.credentialsJson) !== null && _a !== void 0 ? _a : (warehouse === "mysql" ? mysqlCredentialsTemplate() : postgresCredentialsTemplate(warehouse)));
         filesWritten.push(path__namespace.join(projectDir, CREDENTIALS_FILENAME));
@@ -54409,7 +54574,8 @@ ${description}    columnTypes: {
         ],
     };
 }
-function convertTarget(source, jsMode) {
+function convertTarget(source, jsMode, dialect = "postgres") {
+    const dialectPass = dialect === "postgres";
     const span = jsMode ? null : findConfigBlock(source);
     const findings = [];
     const lines = source.split("\n");
@@ -54447,7 +54613,7 @@ function convertTarget(source, jsMode) {
                 line = line.replace(/,/, " ");
             }
         }
-        if (inConfig && commentingConfigBlockDepth === 0) {
+        if (dialectPass && inConfig && commentingConfigBlockDepth === 0) {
             const m = CONFIG_BQ_KEYS.exec(line);
             if (m) {
                 const note = `BigQuery-only setting — not applicable on Postgres (partitioning/clustering → postgres: {}; project qualifiers drop)`;
@@ -54471,7 +54637,7 @@ function convertTarget(source, jsMode) {
             out.push(`// ${line}`);
             continue;
         }
-        if (!inConfig || jsMode) {
+        if (dialectPass && (!inConfig || jsMode)) {
             for (const rule of SQL_RULES) {
                 rule.pattern.lastIndex = 0;
                 if (!rule.pattern.test(line))
@@ -54523,6 +54689,7 @@ function readSourceConfig(srcDir) {
     const s = (k) => (typeof raw[k] === "string" ? raw[k] : null);
     return {
         defaultProject: (_a = s("defaultProject")) !== null && _a !== void 0 ? _a : s("defaultDatabase"),
+        defaultLocation: s("defaultLocation"),
         defaultDataset: (_c = (_b = s("defaultDataset")) !== null && _b !== void 0 ? _b : s("defaultSchema")) !== null && _c !== void 0 ? _c : "dataform",
         defaultAssertionDataset: (_d = s("defaultAssertionDataset")) !== null && _d !== void 0 ? _d : s("assertionSchema"),
         vars: (_e = raw.vars) !== null && _e !== void 0 ? _e : null,
@@ -54530,7 +54697,7 @@ function readSourceConfig(srcDir) {
     };
 }
 async function migrateDataform(opts) {
-    var _a, _b, _c, _d, _e, _f, _g, _h;
+    var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o;
     const srcDir = path__namespace.resolve(opts.srcDir);
     const outDir = path__namespace.resolve(opts.outDir);
     if (containsPath(srcDir, outDir)) {
@@ -54542,11 +54709,14 @@ async function migrateDataform(opts) {
     if (fs__namespace$1.existsSync(outDir) && fs__namespace$1.readdirSync(outDir).length > 0) {
         throw new Error(`Output directory ${outDir} is not empty.`);
     }
+    const targetWarehouse = (_a = opts.targetWarehouse) !== null && _a !== void 0 ? _a : "supabase";
+    const isBigQueryTarget = targetWarehouse === "bigquery";
     const sourceConfig = readSourceConfig(srcDir);
     const writer = new OutWriter(outDir);
     skippedForSafety = new Set();
     const files = walkFiles(srcDir);
     const report = {
+        targetWarehouse,
         generator: `sqlanvil migrate-dataform ${version}`,
         sourceDir: srcDir,
         sourceConfig: sourceConfig.raw,
@@ -54568,16 +54738,16 @@ async function migrateDataform(opts) {
             : { type: null, schema: null, database: null, name: null, description: null };
         sqlxFiles.push({ rel, source, parsed });
         report.inventory.sqlxFiles++;
-        const t = (_a = parsed.type) !== null && _a !== void 0 ? _a : "(none)";
-        report.inventory.byType[t] = ((_b = report.inventory.byType[t]) !== null && _b !== void 0 ? _b : 0) + 1;
+        const t = (_b = parsed.type) !== null && _b !== void 0 ? _b : "(none)";
+        report.inventory.byType[t] = ((_c = report.inventory.byType[t]) !== null && _c !== void 0 ? _c : 0) + 1;
     }
     const resolveDatabase = (db) => { var _a; return !db || db === "<defaultDatabase>" ? (_a = sourceConfig.defaultProject) !== null && _a !== void 0 ? _a : "UNKNOWN_PROJECT" : db; };
     const declarationSchemas = new Set();
     const targetSchemas = new Set();
     const connectionMap = new Map();
-    for (const f of sqlxFiles) {
+    for (const f of isBigQueryTarget ? [] : sqlxFiles) {
         if (f.parsed.type === "declaration") {
-            const dataset = (_c = f.parsed.schema) !== null && _c !== void 0 ? _c : sourceConfig.defaultDataset;
+            const dataset = (_d = f.parsed.schema) !== null && _d !== void 0 ? _d : sourceConfig.defaultDataset;
             const project = resolveDatabase(f.parsed.database);
             declarationSchemas.add(dataset);
             const name = connectionNameFor(project);
@@ -54598,7 +54768,7 @@ async function migrateDataform(opts) {
             }
         }
         else if (f.parsed.type) {
-            targetSchemas.add((_d = f.parsed.schema) !== null && _d !== void 0 ? _d : sourceConfig.defaultDataset);
+            targetSchemas.add((_e = f.parsed.schema) !== null && _e !== void 0 ? _e : sourceConfig.defaultDataset);
         }
     }
     report.connections = [...connectionMap.values()].sort((a, b) => a.name.localeCompare(b.name));
@@ -54610,8 +54780,20 @@ async function migrateDataform(opts) {
         }
         if (rel.endsWith(".sqlx")) {
             const info = sqlxFiles.find(f => f.rel === rel);
+            if (isBigQueryTarget) {
+                const { content, findings } = convertTarget(info.source, false, "none");
+                writer.write(rel, content);
+                report.files.push({
+                    file: rel,
+                    action: info.parsed.type === "declaration" ? "declaration" : "target",
+                    type: (_f = info.parsed.type) !== null && _f !== void 0 ? _f : "(none)",
+                    status: findings.length === 0 ? "clean" : "rewritten",
+                    findings,
+                });
+                continue;
+            }
             if (info.parsed.type === "declaration") {
-                const dataset = (_e = info.parsed.schema) !== null && _e !== void 0 ? _e : sourceConfig.defaultDataset;
+                const dataset = (_g = info.parsed.schema) !== null && _g !== void 0 ? _g : sourceConfig.defaultDataset;
                 const project = resolveDatabase(info.parsed.database);
                 const connection = connectionNameFor(project);
                 const { content, findings } = convertDeclaration(info.source, info.parsed, connection, dataset, rel);
@@ -54631,7 +54813,7 @@ async function migrateDataform(opts) {
                 report.files.push({
                     file: rel,
                     action: "target",
-                    type: (_f = info.parsed.type) !== null && _f !== void 0 ? _f : "(none)",
+                    type: (_h = info.parsed.type) !== null && _h !== void 0 ? _h : "(none)",
                     status: findings.length === 0
                         ? "clean"
                         : findings.some(f => f.kind === "flag")
@@ -54645,10 +54827,10 @@ async function migrateDataform(opts) {
         if (rel.endsWith(".js") && (rel.startsWith("definitions/") || rel.startsWith("includes/"))) {
             report.inventory.jsFiles++;
             const source = fs__namespace$1.readFileSync(abs, "utf8");
-            const { content, findings } = convertTarget(source, true);
+            const { content, findings } = convertTarget(source, true, isBigQueryTarget ? "none" : "postgres");
             writer.write(rel, content);
             const isIncludes = rel.startsWith("includes/");
-            if (isIncludes && findings.length > 0) {
+            if (isIncludes && findings.length > 0 && !isBigQueryTarget) {
                 report.warnings.push(`includes helper ${rel} emits BigQuery-flavored SQL — review its ${findings.length} finding(s)`);
             }
             report.files.push({
@@ -54667,11 +54849,12 @@ async function migrateDataform(opts) {
         writer.write(rel, fs__namespace$1.readFileSync(abs));
         report.files.push({ file: rel, action: "copied", status: "clean", findings: [] });
     }
-    const settings = {
-        warehouse: "supabase",
+    const settings = isBigQueryTarget
+        ? Object.assign(Object.assign(Object.assign({}, (sourceConfig.defaultProject ? { defaultProject: sourceConfig.defaultProject } : {})), (sourceConfig.defaultLocation ? { defaultLocation: sourceConfig.defaultLocation } : {})), { defaultDataset: sourceConfig.defaultDataset, defaultAssertionDataset: (_j = sourceConfig.defaultAssertionDataset) !== null && _j !== void 0 ? _j : "sqlanvil_assertions", sqlanvilCoreVersion: (_k = opts.coreVersion) !== null && _k !== void 0 ? _k : version }) : {
+        warehouse: targetWarehouse,
         defaultDataset: sourceConfig.defaultDataset.toLowerCase(),
-        defaultAssertionDataset: ((_g = sourceConfig.defaultAssertionDataset) !== null && _g !== void 0 ? _g : "sqlanvil_assertions").toLowerCase(),
-        sqlanvilCoreVersion: (_h = opts.coreVersion) !== null && _h !== void 0 ? _h : version,
+        defaultAssertionDataset: ((_l = sourceConfig.defaultAssertionDataset) !== null && _l !== void 0 ? _l : "sqlanvil_assertions").toLowerCase(),
+        sqlanvilCoreVersion: (_m = opts.coreVersion) !== null && _m !== void 0 ? _m : version,
     };
     if (sourceConfig.vars)
         settings.vars = sourceConfig.vars;
@@ -54690,6 +54873,22 @@ async function migrateDataform(opts) {
         }));
     }
     writer.write("workflow_settings.yaml", jsYaml.dump(settings));
+    if (!fs__namespace$1.existsSync(path__namespace.join(outDir, "AGENTS.md"))) {
+        writer.write("AGENTS.md", agentsMdContents({
+            warehouse: targetWarehouse,
+            defaultDataset: settings.defaultDataset,
+            version: (_o = opts.coreVersion) !== null && _o !== void 0 ? _o : version,
+            converted: true
+        }));
+        report.files.push({ file: "AGENTS.md", action: "generated", status: "clean", findings: [] });
+    }
+    else {
+        report.warnings.push("Source AGENTS.md copied as-is — its guidance targets Dataform; consider replacing it with the sqlanvil version (`sqlanvil init --bare` in an empty dir generates one).");
+    }
+    if (!fs__namespace$1.existsSync(path__namespace.join(outDir, "CLAUDE.md"))) {
+        writer.write("CLAUDE.md", claudeMdBridgeContents());
+        report.files.push({ file: "CLAUDE.md", action: "generated", status: "clean", findings: [] });
+    }
     report.skippedForSafety = [...skippedForSafety].sort();
     if (skippedForSafety.size > 0) {
         report.warnings.push(`Skipped ${skippedForSafety.size} file(s)/dir(s) for safety (credentials, build artifacts, VCS) — see skippedForSafety`);
@@ -54716,28 +54915,38 @@ function renderReportMd(r) {
         lines.push(`  - ${t}: ${n}`);
     }
     lines.push("");
-    lines.push(`## Source connections (${r.connections.length})`);
-    lines.push("");
-    lines.push(`Declarations keep reading BigQuery through named \`connections:\` in workflow_settings.yaml ` +
-        `(mode: runner-extract — no Vault, no wrappers). Each declaration needs \`columnTypes\` ` +
-        `before it can extract; scaffold them with \`sqlanvil introspect\`:`);
-    lines.push("");
-    for (const c of r.connections) {
-        lines.push(`- **${c.name}** — project \`${c.project}\`, ${c.declarationCount} declaration(s) across ` +
-            `${c.datasets.length} dataset(s): ${c.datasets.slice(0, 8).map(d => `\`${d}\``).join(", ")}` +
-            (c.datasets.length > 8 ? ", …" : ""));
-        lines.push(`  - \`${c.introspectExample}\``);
+    if (r.targetWarehouse === "bigquery") {
+        lines.push(`## Same-warehouse conversion (BigQuery → BigQuery)`);
+        lines.push("");
+        lines.push(`This is a tooling swap: the project keeps running on the SAME BigQuery warehouse. SQL ` +
+            `bodies, \`bigquery: {}\` config blocks, and declarations passed through untouched; ` +
+            `only the compile global was renamed (\`dataform.projectConfig\` → ` +
+            `\`sqlanvil.projectConfig\`) and the settings file converted.`);
     }
-    if (r.overlappingSchemas.length > 0) {
+    else {
+        lines.push(`## Source connections (${r.connections.length})`);
         lines.push("");
-        lines.push(`## ⚠ Schemas that are BOTH source and target`);
+        lines.push(`Declarations keep reading BigQuery through named \`connections:\` in workflow_settings.yaml ` +
+            `(mode: runner-extract — no Vault, no wrappers). Each declaration needs \`columnTypes\` ` +
+            `before it can extract; scaffold them with \`sqlanvil introspect\`:`);
         lines.push("");
-        lines.push(`These schemas have declarations AND materializing actions: ${r.overlappingSchemas
-            .map(s => `\`${s}\``)
-            .join(", ")}. ` +
-            `Their declared tables are probably produced by this pipeline (or a sibling) — once those ` +
-            `producers move to Postgres, convert the declarations to plain local declarations instead ` +
-            `of BigQuery connections.`);
+        for (const c of r.connections) {
+            lines.push(`- **${c.name}** — project \`${c.project}\`, ${c.declarationCount} declaration(s) across ` +
+                `${c.datasets.length} dataset(s): ${c.datasets.slice(0, 8).map(d => `\`${d}\``).join(", ")}` +
+                (c.datasets.length > 8 ? ", …" : ""));
+            lines.push(`  - \`${c.introspectExample}\``);
+        }
+        if (r.overlappingSchemas.length > 0) {
+            lines.push("");
+            lines.push(`## ⚠ Schemas that are BOTH source and target`);
+            lines.push("");
+            lines.push(`These schemas have declarations AND materializing actions: ${r.overlappingSchemas
+                .map(s => `\`${s}\``)
+                .join(", ")}. ` +
+                `Their declared tables are probably produced by this pipeline (or a sibling) — once those ` +
+                `producers move to Postgres, convert the declarations to plain local declarations instead ` +
+                `of BigQuery connections.`);
+        }
     }
     lines.push("");
     lines.push(`## Target files (${targets.length})`);
@@ -54759,7 +54968,9 @@ function renderReportMd(r) {
     lines.push("");
     lines.push(`## Declarations (${declarations.length})`);
     lines.push("");
-    lines.push(`Every declaration was rewritten to ride its connection. The BigQuery data does not move.`);
+    lines.push(r.targetWarehouse === "bigquery"
+        ? `Declarations are unchanged — the sources are native to the warehouse.`
+        : `Every declaration was rewritten to ride its connection. The BigQuery data does not move.`);
     if (r.warnings.length > 0) {
         lines.push("");
         lines.push(`## Warnings`);
@@ -54770,12 +54981,23 @@ function renderReportMd(r) {
     lines.push("");
     lines.push(`## Finish the migration`);
     lines.push("");
-    lines.push(`1. \`sqlanvil compile\` — should already succeed.`);
-    lines.push(`2. Scaffold \`columnTypes\` for the declarations you actually read (see connections above).`);
-    lines.push(`3. \`sqlanvil validate\` against your Postgres/Supabase warehouse — PASS/FAILURE/BLOCKED per ` +
-        `model is the migration to-do list. Work the flagged files until validate is green.`);
-    lines.push(`4. This report is machine-readable (migration-report.json) — pointing an AI agent at it plus ` +
-        `the \`SQLANVIL-MIGRATE:\` markers is the fastest path through the dialect work.`);
+    if (r.targetWarehouse === "bigquery") {
+        lines.push(`1. \`sqlanvil compile\` — should already succeed.`);
+        lines.push(`2. Credentials: \`gcloud auth application-default login\` (ADC), or a service-account ` +
+            `key in a gitignored \`.df-credentials.json\`.`);
+        lines.push(`3. \`sqlanvil validate\` — dry-runs every model against BigQuery without executing; ` +
+            `all-PASS means the swap is complete.`);
+        lines.push(`4. Compare \`sqlanvil compile\` output with \`dataform compile\` on the source for a ` +
+            `sample of actions — they should match apart from the compile-global rename.`);
+    }
+    else {
+        lines.push(`1. \`sqlanvil compile\` — should already succeed.`);
+        lines.push(`2. Scaffold \`columnTypes\` for the declarations you actually read (see connections above).`);
+        lines.push(`3. \`sqlanvil validate\` against your Postgres/Supabase warehouse — PASS/FAILURE/BLOCKED per ` +
+            `model is the migration to-do list. Work the flagged files until validate is green.`);
+        lines.push(`4. This report is machine-readable (migration-report.json) — pointing an AI agent at it plus ` +
+            `the \`SQLANVIL-MIGRATE:\` markers is the fastest path through the dialect work.`);
+    }
     lines.push("");
     return lines.join("\n");
 }
@@ -55316,6 +55538,7 @@ const CREDS_PASSWORD_QUESTION = "Password? (leave empty to fill in later)";
 const CREDS_SSLMODE_QUESTION = "SSL mode? (disable/require)";
 const CONVERT_SOURCE_QUESTION = "Path to the Dataform project to convert (read-only, never modified)?";
 const CONVERT_OUT_QUESTION = "Directory for the converted sqlanvil project (created; must be empty)?";
+const CONVERT_TARGET_QUESTION = "Target warehouse? (bigquery = keep running on BigQuery, tooling swap only; supabase/postgres = move off BigQuery)";
 const SUPABASE_POOLER_HINT = "Use the SESSION POOLER connection (Supabase Dashboard -> Connect -> Session pooler): host " +
     "aws-<n>-<region>.pooler.supabase.com, user postgres.<project-ref>. The direct " +
     "db.<ref>.supabase.co host is IPv6-only and unreachable from most networks.";
@@ -55434,13 +55657,22 @@ async function runConvertFlow() {
         throw new Error("No usable source directory provided.");
     }
     const outDir = actuallyResolve(askRequired(CONVERT_OUT_QUESTION));
+    const targetWarehouse = askChoice(CONVERT_TARGET_QUESTION, ["bigquery", "supabase", "postgres"], "bigquery");
     print("\nConverting...\n");
-    const report = await migrateDataform({ srcDir, outDir });
+    const report = await migrateDataform({ srcDir, outDir, targetWarehouse });
     printMigrationSummary(report, outDir);
+    if (targetWarehouse === "bigquery") {
+        print("\nNext steps:");
+        print(`  1. sqlanvil compile ${outDir}`);
+        print("  2. Credentials: gcloud auth application-default login (ADC), or a service-account " +
+            `key in a gitignored ${CREDENTIALS_FILENAME}.`);
+        print(`  3. sqlanvil validate ${outDir}  (dry-runs every model against BigQuery; all-PASS = swap complete)`);
+        return 0;
+    }
     if (askYesNo(INIT_CONFIGURE_CREDS_QUESTION, true)) {
         const credentialsPath = path__namespace.join(outDir, CREDENTIALS_FILENAME);
         ensureGitignoreCoversCredentials(outDir);
-        fs__namespace$1.writeFileSync(credentialsPath, collectCredentials("supabase"));
+        fs__namespace$1.writeFileSync(credentialsPath, collectCredentials(targetWarehouse));
         printSuccess(`Credentials written to ${credentialsPath}`);
     }
     print("\nNext steps:");
@@ -56829,6 +57061,14 @@ const interactiveOption = option("interactive", {
     type: "boolean",
     default: false
 });
+const targetWarehouseOption = option("target-warehouse", {
+    describe: "Where the CONVERTED project runs: supabase/postgres = move off BigQuery (sources become " +
+        "named connections, SQL gets the dialect pass); bigquery = keep the SAME warehouse — a " +
+        "tooling swap with SQL and bigquery:{} blocks untouched.",
+    type: "string",
+    choices: ["supabase", "postgres", "bigquery"],
+    default: "supabase"
+});
 const warehouseOption = option("warehouse", {
     describe: "Target warehouse for the new project.",
     type: "string",
@@ -57695,10 +57935,12 @@ function runCli() {
             },
             {
                 format: "migrate-dataform <source-dir> <out-dir>",
-                description: "Convert a Dataform/BigQuery project into a sqlanvil-on-Postgres project. The source " +
-                    "directory is READ-ONLY; the converted project + migration-report.{md,json} land in " +
-                    "<out-dir> (must be empty). Sources stay in BigQuery as named connections; target SQL " +
-                    "gets safe rewrites + inline SQLANVIL-MIGRATE markers for dialect review.",
+                description: "Convert a Dataform/BigQuery project to sqlanvil. The source directory is READ-ONLY; " +
+                    "the converted project + migration-report.{md,json} land in <out-dir> (must be empty). " +
+                    "Default target (supabase/postgres) MOVES the warehouse: sources stay in BigQuery as " +
+                    "named connections and target SQL gets safe rewrites + inline SQLANVIL-MIGRATE markers. " +
+                    "--target-warehouse bigquery is a TOOLING SWAP: the project keeps running on the same " +
+                    "BigQuery warehouse, SQL and bigquery:{} blocks untouched.",
                 positionalOptions: [
                     positionalOption("source-dir", {
                         describe: "The Dataform project to convert (never modified)."
@@ -57707,11 +57949,12 @@ function runCli() {
                         describe: "Where the converted sqlanvil project is written (created; must be empty)."
                     })
                 ],
-                options: [],
+                options: [targetWarehouseOption],
                 processFn: async (argv) => {
                     const report = await migrateDataform({
                         srcDir: argv["source-dir"],
-                        outDir: argv["out-dir"]
+                        outDir: argv["out-dir"],
+                        targetWarehouse: argv[targetWarehouseOption.name]
                     });
                     printMigrationSummary(report, argv["out-dir"]);
                     print(`Next: sqlanvil compile ${argv["out-dir"]}`);

package/package.json

@@ -46,7 +46,14 @@
         "**/wrap-ansi": "7.0.0",
         "**/string-width": "4.1.0"
     },
-    "homepage": "https://github.com/sqlanvil/sqlanvil",
+    "homepage": "https://sqlanvil.com",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/sqlanvil/sqlanvil.git"
+    },
+    "bugs": {
+        "url": "https://github.com/sqlanvil/sqlanvil/issues"
+    },
     "license": "Apache-2.0",
     "keywords": [
         "sqlanvil",
@@ -64,7 +71,7 @@
     "bin": {
         "sqlanvil": "bundle.js"
     },
-    "version": "1.23.0",
+    "version": "1.25.0",
     "name": "@sqlanvil/cli",
     "description": "sqlanvil command line interface.",
     "main": "bundle.js"