@sqlanvil/cli 1.9.0 → 1.10.0

package/bundle.js

@@ -43792,7 +43792,7 @@ function collectEvaluationQueries(queryOrAction, concatenate, queryModifier = (q
         .filter(validationQuery => !!validationQuery.query);
 }
 
-const version = "1.9.0";
+const version = "1.10.0";
 const dataformVersion = "3.0.60";
 
 async function build(compiledGraph, runConfig, dbadapter) {
@@ -44459,6 +44459,53 @@ function assertConnectionCredentialsAvailable(graph, connections) {
     }));
 }
 
+function loadDuckdb() {
+    try {
+        return nativeRequire("@duckdb/node-api");
+    }
+    catch (e) {
+        throw new Error(`This feature requires the optional "@duckdb/node-api" dependency, which failed to load: ` +
+            `${e.message}`);
+    }
+}
+async function runAsync(conn, sql) {
+    await conn.run(sql);
+}
+async function allAsync(conn, sql) {
+    const reader = await conn.runAndReadAll(sql);
+    return reader.getRowObjects();
+}
+async function withDuckdb(fn, dbPath = ":memory:") {
+    const { DuckDBInstance } = loadDuckdb();
+    const instance = await DuckDBInstance.create(dbPath);
+    const conn = await instance.connect();
+    const done = () => {
+        var _a, _b;
+        try {
+            (_a = conn.closeSync) === null || _a === void 0 ? void 0 : _a.call(conn);
+        }
+        catch (e) {
+        }
+        try {
+            (_b = instance.closeSync) === null || _b === void 0 ? void 0 : _b.call(instance);
+        }
+        catch (e) {
+        }
+    };
+    try {
+        if (!process.env.HOME) {
+            await runAsync(conn, `SET home_directory='${os__namespace.tmpdir()}'`);
+        }
+        const result = await fn(conn);
+        done();
+        return result;
+    }
+    catch (e) {
+        done();
+        throw e;
+    }
+}
+
 const PG_ATTACH_ALIAS = "pg";
 const SECRET_NAME = "sa_export";
 function buildAttachSql(pg) {
@@ -44522,48 +44569,6 @@ function buildCopySql(selectSql, uri, format, options = {}) {
     const optionList = [`FORMAT ${fmt}`, ...extraOptions].join(", ");
     return `COPY (SELECT * FROM postgres_query('${PG_ATTACH_ALIAS}', $sa$${selectSql}$sa$)) TO '${target}' (${optionList})`;
 }
-function loadDuckdb() {
-    try {
-        return nativeRequire("@duckdb/node-api");
-    }
-    catch (e) {
-        throw new Error(`Exporting on Postgres/Supabase requires the optional "@duckdb/node-api" dependency, which ` +
-            `failed to load: ${e.message}`);
-    }
-}
-async function runAsync(conn, sql) {
-    await conn.run(sql);
-}
-async function withConnection(fn) {
-    const { DuckDBInstance } = loadDuckdb();
-    const instance = await DuckDBInstance.create(":memory:");
-    const conn = await instance.connect();
-    const done = () => {
-        var _a, _b;
-        try {
-            (_a = conn.closeSync) === null || _a === void 0 ? void 0 : _a.call(conn);
-        }
-        catch (e) {
-        }
-        try {
-            (_b = instance.closeSync) === null || _b === void 0 ? void 0 : _b.call(instance);
-        }
-        catch (e) {
-        }
-    };
-    try {
-        if (!process.env.HOME) {
-            await runAsync(conn, `SET home_directory='${os__namespace.tmpdir()}'`);
-        }
-        const result = await fn(conn);
-        done();
-        return result;
-    }
-    catch (e) {
-        done();
-        throw e;
-    }
-}
 async function runDuckdbExport(args) {
     const { spec, selectSql, pg, storage, actionName } = args;
     const uri = resolveExportUri(spec, actionName, { wildcard: false });
@@ -44572,7 +44577,7 @@ async function runDuckdbExport(args) {
         throw new Error(`No "${scheme}" storage credentials found in .df-credentials.json (storage.${scheme}) for ` +
             `export to ${uri}.`);
     }
-    return withConnection(async (conn) => {
+    return withDuckdb(async (conn) => {
         await runAsync(conn, "INSTALL postgres; LOAD postgres; INSTALL httpfs; LOAD httpfs;");
         await runAsync(conn, buildAttachSql(pg));
         if (scheme !== "local") {
@@ -45204,6 +45209,343 @@ function resolveCredentials(envCredentials, cliCredentials, defaultFilename) {
     return envCredentials || defaultFilename;
 }
 
+function key(target) {
+    return targetStringifier.stringify(target);
+}
+function enumName(enumObject, value) {
+    if (value === undefined || value === null) {
+        return "UNKNOWN";
+    }
+    const match = Object.keys(enumObject).find(k => enumObject[k] === value);
+    return match || String(value);
+}
+function tableType$1(enumType) {
+    switch (enumType) {
+        case sqlanvil.TableType.VIEW:
+            return "view";
+        case sqlanvil.TableType.INCREMENTAL:
+            return "incremental";
+        default:
+            return "table";
+    }
+}
+function toMillis(value) {
+    if (value === undefined || value === null) {
+        return 0;
+    }
+    if (typeof value === "number") {
+        return value;
+    }
+    if (typeof value.toNumber === "function") {
+        return value.toNumber();
+    }
+    return Number(value) || 0;
+}
+function actionRow(action, type) {
+    const descriptor = action.actionDescriptor || {};
+    return {
+        target_key: key(action.target),
+        database: action.target.database || "",
+        schema: action.target.schema || "",
+        name: action.target.name || "",
+        readable_name: targetAsReadableString(action.target),
+        type,
+        tags: JSON.stringify(action.tags || []),
+        disabled: !!action.disabled,
+        file_name: action.fileName || "",
+        description: descriptor.description || ""
+    };
+}
+function pushDeps(action, out) {
+    for (const dep of action.dependencyTargets || []) {
+        out.push({
+            from_target_key: key(action.target),
+            to_target_key: key(dep),
+            from_readable: targetAsReadableString(action.target),
+            to_readable: targetAsReadableString(dep)
+        });
+    }
+}
+function pushColumns(action, out) {
+    const columns = (action.actionDescriptor && action.actionDescriptor.columns) || [];
+    for (const column of columns) {
+        out.push({
+            target_key: key(action.target),
+            readable_name: targetAsReadableString(action.target),
+            column_name: (column.path || []).join("."),
+            description: column.description || ""
+        });
+    }
+}
+function catalogRows(compiledGraph) {
+    const actions = [];
+    const dependencies = [];
+    const columns = [];
+    const add = (action, type) => {
+        actions.push(actionRow(action, type));
+        pushDeps(action, dependencies);
+        pushColumns(action, columns);
+    };
+    for (const table of compiledGraph.tables || []) {
+        add(table, tableType$1(table.enumType));
+    }
+    for (const operation of compiledGraph.operations || []) {
+        add(operation, "operation");
+    }
+    for (const assertion of compiledGraph.assertions || []) {
+        add(assertion, "assertion");
+    }
+    for (const exp of compiledGraph.exports || []) {
+        add(exp, "export");
+    }
+    for (const declaration of compiledGraph.declarations || []) {
+        add(declaration, "declaration");
+    }
+    return { actions, dependencies, columns };
+}
+function runRows(runResult, runId) {
+    const runStatus = enumName(sqlanvil.RunResult.ExecutionStatus, runResult.status);
+    return (runResult.actions || []).map(action => {
+        const start = toMillis(action.timing && action.timing.startTimeMillis);
+        const end = toMillis(action.timing && action.timing.endTimeMillis);
+        const failedTask = (action.tasks || []).find(t => !!t.errorMessage);
+        return {
+            run_id: runId,
+            run_status: runStatus,
+            target_key: key(action.target),
+            readable_name: targetAsReadableString(action.target),
+            status: enumName(sqlanvil.ActionResult.ExecutionStatus, action.status),
+            start_millis: start,
+            end_millis: end,
+            duration_millis: start && end ? end - start : 0,
+            error_message: (failedTask && failedTask.errorMessage) || ""
+        };
+    });
+}
+
+let tmpCounter = 0;
+async function writeParquet(rows, outPath, columns) {
+    await fs__namespace.ensureDir(path__namespace.dirname(outPath));
+    const tmp = path__namespace.join(os__namespace.tmpdir(), `sa_artifact_${process.pid}_${Date.now()}_${tmpCounter++}.json`);
+    const payload = rows.length > 0 ? rows : [columns.reduce((o, c) => ((o[c] = null), o), {})];
+    const whereFalse = rows.length > 0 ? "" : " WHERE false";
+    await fs__namespace.writeFile(tmp, JSON.stringify(payload));
+    try {
+        await withDuckdb(async (conn) => {
+            await runAsync(conn, `COPY (SELECT * FROM read_json_auto('${tmp}')${whereFalse}) TO '${outPath}' (FORMAT parquet)`);
+        });
+    }
+    finally {
+        await fs__namespace.remove(tmp).catch(() => undefined);
+    }
+}
+async function queryParquet(sql, views) {
+    return withDuckdb(async (conn) => {
+        for (const view of views) {
+            await runAsync(conn, `create view ${view.name} as select * from read_parquet('${view.glob}')`);
+        }
+        return allAsync(conn, sql);
+    });
+}
+
+const TARGET_DIR = "target";
+const ACTION_COLUMNS = [
+    "target_key",
+    "database",
+    "schema",
+    "name",
+    "readable_name",
+    "type",
+    "tags",
+    "disabled",
+    "file_name",
+    "description"
+];
+const DEPENDENCY_COLUMNS = ["from_target_key", "to_target_key", "from_readable", "to_readable"];
+const COLUMN_COLUMNS = ["target_key", "readable_name", "column_name", "description"];
+const RUN_COLUMNS = [
+    "run_id",
+    "run_status",
+    "target_key",
+    "readable_name",
+    "status",
+    "start_millis",
+    "end_millis",
+    "duration_millis",
+    "error_message"
+];
+async function writeArtifacts(compiledGraph, projectDir, options = {}) {
+    const targetDir = path__namespace.join(projectDir, TARGET_DIR);
+    const catalogDir = path__namespace.join(targetDir, "catalog");
+    const { actions, dependencies, columns } = catalogRows(compiledGraph);
+    await writeParquet(actions, path__namespace.join(catalogDir, "actions.parquet"), ACTION_COLUMNS);
+    await writeParquet(dependencies, path__namespace.join(catalogDir, "dependencies.parquet"), DEPENDENCY_COLUMNS);
+    await writeParquet(columns, path__namespace.join(catalogDir, "columns.parquet"), COLUMN_COLUMNS);
+    if (options.runResult) {
+        const runId = options.runId !== undefined ? options.runId : Date.now();
+        await writeParquet(runRows(options.runResult, runId), path__namespace.join(targetDir, "runs", `run_${runId}.parquet`), RUN_COLUMNS);
+    }
+    return { targetDir };
+}
+async function safeWriteArtifacts(compiledGraph, projectDir, options = {}) {
+    try {
+        await writeArtifacts(compiledGraph, projectDir, options);
+    }
+    catch (e) {
+        if (options.warn) {
+            options.warn(`Artifacts skipped: ${e.message}`);
+        }
+    }
+}
+
+function escapeHtml(value) {
+    return String(value === null || value === undefined ? "" : value)
+        .replace(/&/g, "&")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;");
+}
+async function buildDocsModel(views, generatedAt) {
+    const hasRuns = views.some(v => v.name === "runs");
+    const actions = await queryParquet("select readable_name, type, tags, description from actions order by type, readable_name", views);
+    const dependencies = await queryParquet("select from_readable, to_readable from dependencies", views);
+    const columns = await queryParquet("select readable_name, column_name, description from columns order by readable_name, column_name", views);
+    let latestRun;
+    const statusByModel = new Map();
+    if (hasRuns) {
+        const head = await queryParquet("select max(run_id) as run_id from runs", views);
+        const runId = head[0] && head[0].run_id !== null ? Number(head[0].run_id) : undefined;
+        if (runId !== undefined) {
+            const overall = await queryParquet(`select run_status from runs where run_id = ${runId} limit 1`, views);
+            latestRun = { runId, status: overall[0] ? overall[0].run_status : "UNKNOWN" };
+            const statuses = await queryParquet(`select readable_name, status from runs where run_id = ${runId}`, views);
+            for (const row of statuses) {
+                statusByModel.set(row.readable_name, row.status);
+            }
+        }
+    }
+    const dependsOn = new Map();
+    for (const dep of dependencies) {
+        dependsOn.set(dep.from_readable, (dependsOn.get(dep.from_readable) || []).concat(dep.to_readable));
+    }
+    const byTypeMap = new Map();
+    const models = actions.map(a => {
+        byTypeMap.set(a.type, (byTypeMap.get(a.type) || 0) + 1);
+        let tags = [];
+        try {
+            tags = JSON.parse(a.tags || "[]");
+        }
+        catch (e) {
+            tags = [];
+        }
+        return {
+            readable: a.readable_name,
+            type: a.type,
+            tags,
+            description: a.description || "",
+            status: statusByModel.get(a.readable_name),
+            dependsOn: dependsOn.get(a.readable_name) || []
+        };
+    });
+    return {
+        generatedAt,
+        summary: {
+            total: models.length,
+            byType: Array.from(byTypeMap.entries())
+                .map(([type, n]) => ({ type, n }))
+                .sort((x, y) => x.type.localeCompare(y.type))
+        },
+        latestRun,
+        models,
+        columns: columns.map(c => ({
+            readable: c.readable_name,
+            column: c.column_name,
+            description: c.description || ""
+        }))
+    };
+}
+function renderDocsHtml(model) {
+    const summaryLine = `${model.summary.total} models — ` +
+        model.summary.byType.map(t => `${t.n} ${t.type}`).join(", ");
+    const runLine = model.latestRun
+        ? `Last run: <strong>${escapeHtml(model.latestRun.status)}</strong> (run ${model.latestRun.runId})`
+        : "No runs recorded yet.";
+    const statusBadge = (status) => {
+        if (!status) {
+            return "";
+        }
+        const cls = status === "SUCCESSFUL" ? "ok" : status === "FAILED" ? "fail" : "muted";
+        return `<span class="badge ${cls}">${escapeHtml(status)}</span>`;
+    };
+    const modelRows = model.models
+        .map(m => `<tr data-search="${escapeHtml((m.readable + " " + m.type + " " + m.tags.join(" ")).toLowerCase())}">
+      <td><code>${escapeHtml(m.readable)}</code></td>
+      <td>${escapeHtml(m.type)}</td>
+      <td>${m.tags.map(t => `<span class="tag">${escapeHtml(t)}</span>`).join(" ")}</td>
+      <td>${statusBadge(m.status)}</td>
+      <td>${m.dependsOn.map(d => `<code>${escapeHtml(d)}</code>`).join("<br>")}</td>
+      <td>${escapeHtml(m.description)}</td>
+    </tr>`)
+        .join("\n");
+    const columnRows = model.columns
+        .map(c => `<tr><td><code>${escapeHtml(c.readable)}</code></td><td><code>${escapeHtml(c.column)}</code></td><td>${escapeHtml(c.description)}</td></tr>`)
+        .join("\n");
+    return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>SQLAnvil catalog</title>
+<style>
+  :root { color-scheme: light dark; }
+  body { font: 14px/1.5 -apple-system, system-ui, sans-serif; margin: 2rem; max-width: 1100px; }
+  h1 { margin: 0 0 .25rem; }
+  .meta { color: #888; margin-bottom: 1.5rem; }
+  table { border-collapse: collapse; width: 100%; margin: 1rem 0 2rem; }
+  th, td { text-align: left; padding: .4rem .6rem; border-bottom: 1px solid #8884; vertical-align: top; }
+  th { font-weight: 600; }
+  code { font-size: 12px; }
+  .tag { background: #8883; border-radius: 4px; padding: 0 .35rem; font-size: 12px; }
+  .badge { border-radius: 4px; padding: 0 .4rem; font-size: 12px; font-weight: 600; }
+  .badge.ok { background: #1a7f37; color: #fff; }
+  .badge.fail { background: #b62324; color: #fff; }
+  .badge.muted { background: #8884; }
+  #q { padding: .4rem .6rem; width: 320px; max-width: 100%; margin-bottom: .5rem; }
+</style>
+</head>
+<body>
+  <h1>SQLAnvil catalog</h1>
+  <div class="meta">${escapeHtml(summaryLine)} &middot; ${runLine} &middot; generated ${escapeHtml(model.generatedAt)}</div>
+
+  <input id="q" type="search" placeholder="Filter models…" oninput="filterModels(this.value)">
+  <table id="models">
+    <thead><tr><th>Model</th><th>Type</th><th>Tags</th><th>Last run</th><th>Depends on</th><th>Description</th></tr></thead>
+    <tbody>
+${modelRows}
+    </tbody>
+  </table>
+
+  <h2>Columns</h2>
+  <table>
+    <thead><tr><th>Model</th><th>Column</th><th>Description</th></tr></thead>
+    <tbody>
+${columnRows || '<tr><td colspan="3" class="meta">No documented columns.</td></tr>'}
+    </tbody>
+  </table>
+
+<script>
+  function filterModels(q) {
+    q = q.toLowerCase();
+    for (const tr of document.querySelectorAll('#models tbody tr')) {
+      tr.style.display = tr.getAttribute('data-search').includes(q) ? '' : 'none';
+    }
+  }
+</script>
+</body>
+</html>
+`;
+}
+
 function targetKey(target) {
     return [target.database, target.schema, target.name].filter(Boolean).join(".");
 }
@@ -47964,6 +48306,11 @@ const timeoutOption = option("timeout", {
     default: null,
     coerce: (rawTimeoutString) => rawTimeoutString ? parseDuration__default["default"](rawTimeoutString) : null
 });
+const noArtifactsOption = option("no-artifacts", {
+    describe: "Skip writing the queryable Parquet artifacts under target/ (catalog on compile; run history " +
+        "on run).",
+    type: "boolean"
+});
 const keepShadowOption = option("keep-shadow", {
     describe: "If set, `validate` leaves its temporary shadow schema(s) in place instead of dropping them " +
         "(debugging aid).",
@@ -48132,6 +48479,106 @@ async function runValidate(argv) {
     const results = await validate(prunedGraph, deps, { keepShadow: argv[keepShadowOption.name] });
     return printValidationResults(results, argv[jsonOutputOption.name]);
 }
+function resolveArtifactViews(projectDir) {
+    const catalogDir = path__namespace.join(projectDir, TARGET_DIR, "catalog");
+    const runsDir = path__namespace.join(projectDir, TARGET_DIR, "runs");
+    const views = [];
+    for (const name of ["actions", "dependencies", "columns"]) {
+        const file = path__namespace.join(catalogDir, `${name}.parquet`);
+        if (fs__namespace$1.existsSync(file)) {
+            views.push({ name, glob: file });
+        }
+    }
+    const hasRuns = fs__namespace$1.existsSync(runsDir) && fs__namespace$1.readdirSync(runsDir).some(f => f.endsWith(".parquet"));
+    if (hasRuns) {
+        views.push({ name: "runs", glob: path__namespace.join(runsDir, "*.parquet") });
+    }
+    return { views, hasCatalog: views.some(v => v.name === "actions"), hasRuns };
+}
+function printArtifactRows(rows) {
+    if (!rows || rows.length === 0) {
+        print("(0 rows)");
+        return;
+    }
+    const cols = Object.keys(rows[0]);
+    const widths = cols.map(c => Math.max(c.length, ...rows.map(r => String(r[c] === null || r[c] === undefined ? "" : r[c]).length)));
+    const fmtRow = (vals) => vals.map((v, i) => v.padEnd(widths[i])).join("  ");
+    print(fmtRow(cols));
+    print(fmtRow(widths.map(w => "-".repeat(w))));
+    for (const row of rows) {
+        print(fmtRow(cols.map(c => String(row[c] === null || row[c] === undefined ? "" : row[c]))));
+    }
+    print(`\n(${rows.length} row${rows.length === 1 ? "" : "s"})`);
+}
+const NO_ARTIFACTS = "No artifacts found under target/. Run `sqlanvil compile` (or `run`) first.";
+async function runQuery(projectDir, sql, json) {
+    const { views, hasCatalog } = resolveArtifactViews(projectDir);
+    if (!hasCatalog) {
+        printError(NO_ARTIFACTS);
+        return 1;
+    }
+    const rows = await queryParquet(sql, views);
+    if (json) {
+        print(prettyJsonStringify(rows));
+    }
+    else {
+        printArtifactRows(rows);
+    }
+    return 0;
+}
+async function runInspect(projectDir, json) {
+    const { views, hasCatalog, hasRuns } = resolveArtifactViews(projectDir);
+    if (!hasCatalog) {
+        printError(NO_ARTIFACTS);
+        return 1;
+    }
+    const actionsByType = await queryParquet("select type, count(*) as n from actions group by type order by type", views);
+    let latestRun = null;
+    let failures = [];
+    if (hasRuns) {
+        const latest = await queryParquet("select run_id, run_status, " +
+            "count(*) filter (where status = 'SUCCESSFUL') as succeeded, " +
+            "count(*) filter (where status = 'FAILED') as failed, " +
+            "max(end_millis) - min(start_millis) as wall_ms " +
+            "from runs where run_id = (select max(run_id) from runs) group by run_id, run_status", views);
+        latestRun = latest[0] || null;
+        failures = await queryParquet("select readable_name, error_message from runs " +
+            "where run_id = (select max(run_id) from runs) and status = 'FAILED' limit 20", views);
+    }
+    if (json) {
+        print(prettyJsonStringify({ actionsByType, latestRun, failures }));
+        return 0;
+    }
+    print("Actions by type:");
+    printArtifactRows(actionsByType);
+    if (!hasRuns || !latestRun) {
+        print("\nNo runs recorded yet.");
+    }
+    else {
+        print(`\nLatest run (${latestRun.run_status}): ${latestRun.succeeded} succeeded, ` +
+            `${latestRun.failed} failed, ${latestRun.wall_ms}ms`);
+        if (failures.length > 0) {
+            print("\nFailures:");
+            printArtifactRows(failures);
+        }
+    }
+    return 0;
+}
+async function runDocs(projectDir) {
+    const { views, hasCatalog } = resolveArtifactViews(projectDir);
+    if (!hasCatalog) {
+        printError(NO_ARTIFACTS);
+        return 1;
+    }
+    const model = await buildDocsModel(views, new Date().toISOString());
+    const html = renderDocsHtml(model);
+    const outDir = path__namespace.join(projectDir, TARGET_DIR, "docs");
+    fs__namespace$1.mkdirSync(outDir, { recursive: true });
+    const outFile = path__namespace.join(outDir, "index.html");
+    fs__namespace$1.writeFileSync(outFile, html);
+    printSuccess(`Wrote catalog to ${outFile}`);
+    return 0;
+}
 function runCli() {
     const builtYargs = createYargsCli({
         commands: [
@@ -48262,6 +48709,7 @@ function runCli() {
                     compileTagsOption,
                     compileIncludeDepsOption,
                     compileIncludeDependentsOption,
+                    noArtifactsOption,
                     option(verboseOptionName, {
                         describe: "Enable verbose compilation output. Example usage: 'sqlanvil compile --verbose'",
                         type: "boolean",
@@ -48308,6 +48756,9 @@ function runCli() {
                             printCompiledGraphErrors(compiledGraph.graphErrors, argv[quietCompileOption.name]);
                             return true;
                         }
+                        if (!argv[noArtifactsOption.name]) {
+                            await safeWriteArtifacts(compiledGraph, projectDir, { warn: print });
+                        }
                         return false;
                     }
                     const graphHasErrors = await compileAndPrint();
@@ -48458,6 +48909,7 @@ function runCli() {
                     timeoutOption,
                     tagsOption,
                     bigqueryJobLabelsOption,
+                    noArtifactsOption,
                     ...ProjectConfigOptions.allYargsOptions
                 ],
                 processFn: async (argv) => {
@@ -48572,9 +49024,47 @@ function runCli() {
                     runner.onChange(printExecutedGraph);
                     const runResult = await runner.result();
                     printExecutedGraph(runResult);
+                    if (!argv[noArtifactsOption.name]) {
+                        await safeWriteArtifacts(compiledGraph, argv[projectDirOption.name], {
+                            runResult,
+                            runId: Date.now(),
+                            warn: print
+                        });
+                    }
                     return runResult.status === sqlanvil.RunResult.ExecutionStatus.SUCCESSFUL ? 0 : 1;
                 }
             },
+            {
+                format: `query [sql] [${projectDirOption.name}]`,
+                description: "Run SQL over the project's queryable artifacts in target/ (views: actions, " +
+                    "dependencies, columns, runs), via the bundled DuckDB.",
+                positionalOptions: [
+                    positionalOption("sql", { describe: 'SQL to run, e.g. "select type, count(*) from actions group by 1".' }, (argv) => {
+                        if (!argv.sql) {
+                            throw new Error('Provide a SQL query, e.g. sqlanvil query "select * from actions".');
+                        }
+                    }),
+                    projectDirOption
+                ],
+                options: [jsonOutputOption],
+                processFn: async (argv) => runQuery(argv[projectDirOption.name], argv.sql, argv[jsonOutputOption.name])
+            },
+            {
+                format: `inspect [${projectDirOption.name}]`,
+                description: "Summarize the project's artifacts: action counts by type, the latest run's status/" +
+                    "timing, and recent failures.",
+                positionalOptions: [projectDirOption],
+                options: [jsonOutputOption],
+                processFn: async (argv) => runInspect(argv[projectDirOption.name], argv[jsonOutputOption.name])
+            },
+            {
+                format: `docs [${projectDirOption.name}]`,
+                description: "Generate a self-contained HTML catalog of the project (models, columns, dependencies, " +
+                    "last-run status) at target/docs/index.html, from the artifacts.",
+                positionalOptions: [projectDirOption],
+                options: [],
+                processFn: async (argv) => runDocs(argv[projectDirOption.name])
+            },
             {
                 format: `format [${projectDirMustExistOption.name}]`,
                 description: "Format the sqlanvil project's files.",

package/package.json

@@ -63,7 +63,7 @@
     "bin": {
         "sqlanvil": "bundle.js"
     },
-    "version": "1.9.0",
+    "version": "1.10.0",
     "name": "@sqlanvil/cli",
     "description": "sqlanvil command line interface.",
     "main": "bundle.js"