dbt-sugar 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dat Nguyen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,78 @@
-# Temporary Holding Version
+<p align="center">
+  <img src="docs/assets/logo.svg" alt="dbt sugar logo" width="220" height="88">
+</p>
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+<p align="center"><b>A live local page for dbt v2 runs: what's running, what's next, what to fix, and Dinor Sugar, a pixel dinosaur forever chasing the dbt logo.</b></p>
+
+<p align="center">
+  <a href="https://github.com/datnguye/dbt-sugar/actions/workflows/ci.yml"><img src="https://github.com/datnguye/dbt-sugar/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <a href="docs/spec.md"><img src="https://img.shields.io/badge/docs-spec-blue?style=flat&logo=gitbook&logoColor=white" alt="docs"></a>
+  <img src="https://img.shields.io/badge/dbt-v2%20(Fusion)-FF694B?logo=dbt&logoColor=white" alt="dbt v2">
+  <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT"></a>
+  <a href="https://nodejs.org"><img src="https://img.shields.io/badge/Node-22%2B-339933.svg?style=flat&logo=node.js&logoColor=white" alt="node"></a>
+</p>
+
+Run `sugar -- dbt build` and a page opens next to your terminal. It shows the phases dbt has finished, a `done/total` progress bar, the nodes running right now (and whether they are slower than last time), what's queued and what each one is waiting on, and a short list of suggestions to make the project healthier. Dinor Sugar, a pixel dinosaur, chases the dbt logo while things go well, sweats at warnings, panics when an error lets the logo escape, and catches it (sunglasses on) when everything is green. It cannot fix your SQL, but it does try.
+
+Everything comes from files dbt v2 already writes: `logs/otel*.jsonl`, `logs/dbt.log` and `target/manifest.json`. No API keys, no accounts, nothing leaves your machine.
+
+<p align="center">
+  <img src="docs/assets/img/demo.gif" alt="dbt sugar: two dbt projects replaying live, the project switcher, a failed run with its blocked nodes, and the Diff tab generating base artifacts for a branch" width="880">
+</p>
+
+## Why dbt sugar?
+
+dbt v2 (Fusion) is fast, and its terminal output scrolls by just as fast. When a build has hundreds of nodes, the questions are always the same: *what is it doing now*, *what is it stuck behind*, *will that model that failed yesterday take half the DAG down with it again*, and *what should I fix first*. dbt sugar answers those from the OTel log, live, and remembers past runs in a small local DuckDB file so "slower than usual" and "flaky" actually mean something.
+
+## Install
+
+```bash
+npm install -g dbt-sugar
+```
+
+Requires Node.js 22+ and dbt v2 (Fusion).
+
+## Quickstart
+
+```bash
+sugar -- dbt build --select +orders   # run dbt and watch it at http://127.0.0.1:4322
+sugar                                  # watch runs started elsewhere in this project
+sugar -d ./project_a -d ./project_b    # several projects; switch between them from the header
+```
+
+When sugar starts dbt for you it sets `DBT_OTEL_FILE_NAME=otel.jsonl`. For runs you start yourself, set it too, since dbt only writes the OTel log when asked. Running several dbt processes at once (hello, agents)? Give each its own log folder, for example `DBT_LOG_PATH=logs/run-$$`, so their `dbt.log` lines don't interleave; `sugar -- dbt …` does this for you. Sugar reads `logs/` and its subfolders and shows each invocation separately.
+
+History lives in `~/.dbt-sugar/history.duckdb` (or `$DBT_SUGAR_HOME`). It stores run and node metadata only, no SQL, no data. `sugar --help` lists every option.
+
+## Review a branch: the Diff tab
+
+Big PRs are where reviewers lose the plot. The **Diff** tab compares your branch's `target/manifest.json` with the one from `main` and shows what actually changed: added, modified and removed nodes with the reason (SQL, materialization, contract, columns and their types, dependencies, tests), a SQL diff, what sits downstream, a short review checklist, and the `dbt build --select …+` command that rebuilds exactly that.
+
+The breaking stuff floats to the top: models removed while something still uses them, column changes on enforced contracts, incremental config changes that need a `--full-refresh`.
+
+Pick the **base** branch (defaults to the repo's default branch, e.g. `origin/main`) and the **compare** side (defaults to your current branch's working tree) right on the page. If there are no dbt artifacts for that commit yet, the page shows the exact command and a **Generate** button: sugar checks the commit out into a temporary git worktree and runs `dbt parse --target-path ~/.dbt-sugar/base/<sha>/<project>` there, then removes the worktree. Artifacts are cached per commit, so it only happens once. Run the shown command yourself if you prefer; the page picks the result up either way.
+
+It needs whatever `dbt parse` needs (a profile) and reuses your installed `dbt_packages`. The working-tree side is your `target/manifest.json`; if you've never parsed, the page offers Generate for that side too, writing only into sugar's cache (never your `target/` or `logs/`). Nothing has to have run: the Diff tab only needs git and a parse.
+
+## Use it as a library
+
+The page is one consumer. The same pieces are exported for hosts such as [Agent Cage](https://github.com/datnguye/agent-cage) that watch many dbt processes:
+
+```js
+import { createDbtSource, createSnapshotBuilder } from 'dbt-sugar';
+import { mascotSvg } from 'dbt-sugar/mascot';
+
+const source = createDbtSource({ projectDir: '/path/to/project' });
+const builder = createSnapshotBuilder({ sources: [source], store: null });
+const snapshot = await builder.build();
+```
+
+`store` is optional: pass `null` to skip history, the bundled DuckDB store (`createStore`), or anything with `saveRun`, `previousRun` and `stats`. The full behaviour lives in the **[spec](docs/spec.md)**; how the pieces fit together, from `sugar` starting up to a Diff click in the page, is in **[architecture](docs/architecture.html)** (an animated page; open it in a browser).
+
+## Contributing
+
+Bugs, ideas and new suggestion rules are welcome; see the **[Contributing Guide](CONTRIBUTING.md)** and the **[decision records](docs/decisions/README.md)**. `npm run verify` runs the same gates as CI: syntax and layering checks, unit and e2e tests at 100% coverage, and Playwright against a replay of a real jaffle-shop build (`npm run playground` to watch that replay yourself).
+
+## License
+
+[MIT](./LICENSE) © Dat Nguyen

package/package.json

@@ -1,6 +1,62 @@
 {
   "name": "dbt-sugar",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "A live local page for dbt v2 runs: what's running, what's next, what to fix, a diff for reviewers, and Dinor Sugar chasing the dbt logo.",
+  "keywords": [
+    "dbt",
+    "dbt-fusion",
+    "dbt-v2",
+    "opentelemetry",
+    "monitoring",
+    "dashboard",
+    "cli"
+  ],
+  "homepage": "https://github.com/datnguye/dbt-sugar#readme",
+  "bugs": {
+    "url": "https://github.com/datnguye/dbt-sugar/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/datnguye/dbt-sugar.git"
+  },
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.js",
+    "./mascot": "./src/web/lib/mascot.js",
+    "./view": "./src/web/lib/view.js",
+    "./style.css": "./src/web/style.css",
+    "./package.json": "./package.json"
+  },
+  "bin": {
+    "sugar": "src/bin/sugar.js"
+  },
+  "files": [
+    "src",
+    "!src/scripts",
+    "LICENSE",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "start": "node src/bin/sugar.js",
+    "playground": "node test/playground/run.js",
+    "check": "node src/scripts/check.mjs",
+    "test": "node --test --experimental-test-coverage --test-coverage-include='src/**' --test-coverage-exclude='src/bin/**' --test-coverage-exclude='src/scripts/**' --test-coverage-exclude='src/web/app.js' --test-coverage-lines=100 --test-coverage-branches=100 --test-coverage-functions=100 'test/unit/**/*.test.js' 'test/e2e/*.test.js'",
+    "test:unit": "node --test 'test/unit/**/*.test.js'",
+    "test:ui": "playwright test",
+    "verify": "npm run check && npm test && npm run test:ui",
+    "demo:gif": "node src/scripts/demo-gif.mjs",
+    "prepare": "git config core.hooksPath .githooks 2>/dev/null || true",
+    "ux:shots": "node src/scripts/ux-shots.mjs",
+    "spec-guard": "node src/scripts/spec-guard.mjs"
+  },
+  "devDependencies": {
+    "@playwright/test": "^1.56.1"
+  },
+  "dependencies": {
+    "@duckdb/node-api": "2.0.0-r.1"
+  }
+}

package/src/bin/sugar.js

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+import { createRequire } from 'node:module';
+import { run } from '../cli/start.js';
+
+const { version } = createRequire(import.meta.url)('../../package.json');
+run(process.argv.slice(2), { version });

package/src/cli/args.js

@@ -0,0 +1,50 @@
+import { parseArgs } from 'node:util';
+
+const LOOPBACK = new Set(['127.0.0.1', 'localhost', '::1']);
+
+export const USAGE = `Usage: sugar [options] [-- <dbt command>]
+
+Watch dbt v2 runs live in the browser: what's running, what's next, what to fix.
+
+Options:
+  -d, --project-dir <dir>  dbt project to watch (repeatable; default .)
+      --no-diff            turn off the Diff tab (pick branches and build their artifacts on the page)
+  -p, --port <n>           port to listen on (default 4322, 0 = any free port)
+      --host <h>           loopback address to bind (default 127.0.0.1)
+      --no-open            do not open the browser
+  -h, --help               show this help
+  -v, --version            print the version
+
+Examples:
+  sugar -- dbt build --select +orders   run dbt and watch it (sets DBT_OTEL_FILE_NAME)
+  sugar                                 watch dbt runs started elsewhere
+
+Runs started elsewhere need DBT_OTEL_FILE_NAME=otel.jsonl (or any otel*.jsonl name,
+one per process when several dbt processes run at once).`;
+
+export function parseCli(argv) {
+  const dash = argv.indexOf('--');
+  const own = dash === -1 ? argv : argv.slice(0, dash);
+  const command = dash === -1 ? [] : argv.slice(dash + 1);
+  const { values } = parseArgs({
+    args: own,
+    allowNegative: true,
+    options: {
+      'project-dir': { type: 'string', short: 'd', multiple: true },
+      diff: { type: 'boolean', default: true },
+      port: { type: 'string', short: 'p' },
+      host: { type: 'string', default: '127.0.0.1' },
+      open: { type: 'boolean', default: true },
+      help: { type: 'boolean', short: 'h', default: false },
+      version: { type: 'boolean', short: 'v', default: false }
+    }
+  });
+  const port = values.port === undefined ? 4322 : Number(values.port);
+  if (!Number.isInteger(port) || port < 0 || port > 65535) throw new Error(`--port must be 0-65535, got "${values.port}"`);
+  if (!LOOPBACK.has(values.host)) throw new Error(`--host must be a loopback address (${[...LOOPBACK].join(', ')})`);
+  const projectDirs = values['project-dir'] ?? ['.'];
+  if (command.length && projectDirs.length > 1) throw new Error('running a dbt command needs exactly one --project-dir');
+  if (dash !== -1 && !command.length) throw new Error('nothing to run after --');
+  const diff = values.diff ? {} : null;
+  return { host: values.host, open: values.open, help: values.help, version: values.version, port, portExplicit: values.port !== undefined, projectDirs, command, diff };
+}

package/src/cli/browser.js

@@ -0,0 +1,14 @@
+import { spawn } from 'node:child_process';
+
+export function openBrowser(url, platform = process.platform, run = spawn) {
+  const [command, args] =
+    platform === 'darwin' ? ['open', [url]] : platform === 'win32' ? ['cmd', ['/c', 'start', '', url]] : ['xdg-open', [url]];
+  try {
+    const child = run(command, args, { stdio: 'ignore', detached: true });
+    child.on('error', () => {});
+    child.unref();
+  } catch {
+    return false;
+  }
+  return true;
+}

package/src/cli/start.js

@@ -0,0 +1,139 @@
+import { spawn as spawnProcess } from 'node:child_process';
+import crypto from 'node:crypto';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createSnapshotBuilder } from '../core/builder.js';
+import { sugarHome } from '../core/home.js';
+import { REF } from '../dbt/base.js';
+import { createDbtSource } from '../dbt/source.js';
+import { createServer } from '../server/http.js';
+import { createWatcher } from '../server/watch.js';
+import { parseCli, USAGE } from './args.js';
+import { openBrowser } from './browser.js';
+
+const PORT_TRIES = 10;
+const WEB_DIR = path.join(path.dirname(fileURLToPath(import.meta.url)), '..', 'web');
+
+export async function openStore({ env, load = () => import('../history/store.js') }) {
+  try {
+    const { createStore } = await load();
+    return createStore({ dir: sugarHome(env) });
+  } catch {
+    return null;
+  }
+}
+
+async function listenWithFallback(server, options, port = options.port) {
+  try {
+    return await server.listen(port, options.host);
+  } catch (error) {
+    const last = options.portExplicit || options.port === 0 ? options.port : options.port + PORT_TRIES - 1;
+    if (error.code !== 'EADDRINUSE' || port >= last) throw error;
+    return listenWithFallback(server, options, port + 1);
+  }
+}
+
+export function runDbt(command, { cwd, env, logDir, spawn = spawnProcess, now = Date.now, onExit }) {
+  const logPath = env.DBT_LOG_PATH || path.join(logDir, `sugar-${now()}-${process.pid}`);
+  const child = spawn(command[0], command.slice(1), { cwd, stdio: 'inherit', env: { ...env, DBT_LOG_PATH: logPath, DBT_OTEL_FILE_NAME: env.DBT_OTEL_FILE_NAME || 'otel.jsonl' } });
+  let done = false;
+  const finish = (code) => {
+    if (done) return;
+    done = true;
+    onExit(code);
+  };
+  child.on('error', () => finish(127));
+  child.on('exit', (code) => finish(code ?? 1));
+  return child;
+}
+
+function validRef(ref) {
+  return ref === null || (typeof ref === 'string' && REF.test(ref));
+}
+
+export function applySelection(sources, { project, action = 'select', side = null, base = null, head = null } = {}) {
+  const source = sources.find((s) => s.dir === project);
+  if (!source) return false;
+  if (action === 'build') return source.buildDiff(side);
+  if (action !== 'select' || !validRef(base) || !validRef(head)) return false;
+  return source.selectDiff({ base, head });
+}
+
+export async function start(options, { env = process.env, log = console.log, open = openBrowser, spawn = spawnProcess, store = openStore, now = Date.now } = {}) {
+  const diff = options.diff && { ...options.diff, cacheDir: path.join(sugarHome(env), 'base') };
+  const sources = options.projectDirs.map((projectDir) => createDbtSource({ projectDir, env, diff, archiveRoot: path.join(sugarHome(env), 'runs'), onChange: () => refresh() }));
+  const history = await store({ env });
+  const builder = createSnapshotBuilder({ sources, store: history, now });
+  const server = createServer({ publicDir: WEB_DIR, token: crypto.randomBytes(16).toString('hex'), onSelect: (body) => applySelection(sources, body) });
+  let pending = null;
+  let again = false;
+  function refresh() {
+    if (pending) {
+      again = true;
+      return pending;
+    }
+    pending = builder.build().then(server.publish).finally(() => {
+      pending = null;
+      if (again) {
+        again = false;
+        refresh();
+      }
+    });
+    return pending;
+  }
+  await refresh();
+  const port = await listenWithFallback(server, options);
+  const watcher = createWatcher({
+    dirs: () => sources.flatMap((s) => s.watchDirs()),
+    onChange() {
+      refresh();
+      watcher.sync();
+    }
+  });
+  const url = `http://${options.host === '::1' ? '[::1]' : options.host}:${port}/`;
+  log(`🍬 dbt sugar is open at ${url}`);
+  for (const source of sources) log(`   watching ${source.name}: ${source.logDir}`);
+  log(history ? `   history: ${history.file}` : '   history: off (DuckDB unavailable)');
+  if (options.open) open(url);
+  const app = { url, port, exitCode: null, refresh };
+  if (options.command.length) {
+    app.child = runDbt(options.command, {
+      cwd: sources[0].dir,
+      logDir: sources[0].logDir,
+      env,
+      spawn,
+      onExit(code) {
+        app.exitCode = code;
+        refresh();
+        log(code === 127 ? `sugar: could not start "${options.command[0]}"` : `   ${options.command[0]} exited with ${code}; the page stays open, Ctrl-C to quit`);
+      }
+    });
+  }
+  app.close = async () => {
+    watcher.close();
+    await server.close();
+  };
+  return app;
+}
+
+export async function run(argv, { log = console.log, error = console.error, exit = process.exit, version = '0.0.0', ...deps } = {}) {
+  let options;
+  try {
+    options = parseCli(argv);
+  } catch (problem) {
+    error(`sugar: ${problem.message}\n\n${USAGE}`);
+    return exit(2);
+  }
+  if (options.help) return log(USAGE);
+  if (options.version) return log(version);
+  try {
+    const app = await start(options, { log, ...deps });
+    const stop = () => app.close().then(() => exit(app.exitCode ?? 0));
+    process.once('SIGINT', stop);
+    process.once('SIGTERM', stop);
+    return app;
+  } catch (problem) {
+    error(problem.code === 'EADDRINUSE' ? `sugar: port ${options.port} is busy; try --port 0` : `sugar: ${problem.message}`);
+    return exit(1);
+  }
+}

package/src/core/builder.js

@@ -0,0 +1,67 @@
+import { diffManifests } from './diff.js';
+import { runView } from './snapshot.js';
+import { suggest } from './suggest.js';
+
+const RECENT_RUNS = 10;
+
+function byActivity(a, b) {
+  const live = (r) => (r.status === 'running' ? 0 : 1);
+  return live(a) - live(b) || b.startedAt - a.startedAt;
+}
+
+function safely(promise, fallback) {
+  return promise.then(
+    (value) => value,
+    () => fallback
+  );
+}
+
+function diffView({ base, head, git, manifest: worktree }, memo) {
+  if (!base) return null;
+  const { manifest: baseManifest, ...info } = base;
+  const manifest = head ? head.manifest : worktree;
+  const view = { ...info, side: 'base', head: head?.ref ? { ref: head.ref, sha: head.sha, status: head.status } : null, compareSource: head?.source ?? 'target', compareWarning: head?.warning ?? null, git, baseAt: baseManifest?.generatedAt ?? null, currentAt: manifest?.generatedAt ?? null, result: null };
+  if (!baseManifest) return view;
+  if (head && head.status !== 'ready') return { ...view, status: head.status, error: head.error, side: 'head', out: head.out, warning: head.warning };
+  if (!manifest) return { ...view, status: 'error', error: 'no target/manifest.json yet: run dbt parse or dbt build' };
+  if (memo.base !== baseManifest || memo.current !== manifest) Object.assign(memo, { base: baseManifest, current: manifest, result: diffManifests(baseManifest, manifest) });
+  return { ...view, result: memo.result };
+}
+
+export function createSnapshotBuilder({ sources, store = null, now = Date.now }) {
+  const saved = new Set();
+  const memos = new Map(sources.map((source) => [source, {}]));
+
+  async function project(source) {
+    const data = source.read();
+    for (const run of data.runs.filter((r) => r.status !== 'running' && !saved.has(r.id))) {
+      saved.add(run.id);
+      if (store) await safely(store.saveRun(source.dir, run), null);
+    }
+    const ordered = [...data.runs].sort(byActivity).slice(0, RECENT_RUNS);
+    const runs = [];
+    for (const run of ordered) {
+      const previous = store ? await safely(store.previousRun(source.dir, run.command, run.startedAt), null) : null;
+      runs.push({ ...runView(run, { manifest: data.manifest, previous }), log: run.log ?? data.log.get(run.invocationId) ?? [] });
+    }
+    const history = store ? await safely(store.stats(source.dir), {}) : {};
+    return {
+      name: source.name,
+      dir: source.dir,
+      otel: data.found,
+      untracked: data.untracked ?? null,
+      version: data.manifest?.version ?? null,
+      runs,
+      suggestions: suggest({ run: ordered[0] ?? null, manifest: data.manifest, history }),
+      diff: diffView(data, memos.get(source))
+    };
+  }
+
+  return {
+    async build() {
+      const projects = [];
+      for (const source of sources) projects.push(await project(source));
+      return { generatedAt: now(), history: Boolean(store), projects };
+    }
+  };
+}

package/src/core/diff.js

@@ -0,0 +1,163 @@
+const DIFFABLE = new Set(['model', 'snapshot', 'seed', 'source', 'exposure', 'analysis', 'unit_test', 'test']);
+const RANK = { model: 0, snapshot: 1, seed: 2, source: 3, exposure: 4, analysis: 5, unit_test: 6, test: 7 };
+const TEST_TYPES = new Set(['test', 'unit_test']);
+const BUILDABLE = new Set(['model', 'snapshot', 'seed']);
+const CODE_LIMIT = 1500;
+const CONTEXT = 3;
+const CONFIG_LABEL = { materialized: 'materialized', uniqueKey: 'unique_key', strategy: 'incremental_strategy', onSchemaChange: 'on_schema_change', contract: 'contract.enforced' };
+
+export function lineDiff(before, after) {
+  const a = before ? before.split('\n') : [];
+  const b = after ? after.split('\n') : [];
+  if (a.length > CODE_LIMIT || b.length > CODE_LIMIT) return null;
+  const table = Array.from({ length: a.length + 1 }, () => new Uint16Array(b.length + 1));
+  for (let i = a.length - 1; i >= 0; i -= 1) {
+    for (let j = b.length - 1; j >= 0; j -= 1) table[i][j] = a[i] === b[j] ? table[i + 1][j + 1] + 1 : Math.max(table[i + 1][j], table[i][j + 1]);
+  }
+  const ops = [];
+  let i = 0;
+  let j = 0;
+  while (i < a.length || j < b.length) {
+    if (i < a.length && j < b.length && a[i] === b[j]) {
+      ops.push({ op: ' ', text: a[i] });
+      i += 1;
+      j += 1;
+    } else if (j < b.length && (i === a.length || table[i][j + 1] >= table[i + 1][j])) {
+      ops.push({ op: '+', text: b[j] });
+      j += 1;
+    } else {
+      ops.push({ op: '-', text: a[i] });
+      i += 1;
+    }
+  }
+  return ops;
+}
+
+function gap(n) {
+  return { op: '…', text: `${n} unchanged line${n === 1 ? '' : 's'}` };
+}
+
+export function hunks(ops) {
+  const near = ops.map((_, k) => ops.slice(Math.max(0, k - CONTEXT), k + CONTEXT + 1).some((o) => o.op !== ' '));
+  const out = [];
+  let skipped = 0;
+  ops.forEach((o, k) => {
+    if (near[k]) {
+      if (skipped) out.push(gap(skipped));
+      skipped = 0;
+      out.push(o);
+    } else skipped += 1;
+  });
+  if (skipped) out.push(gap(skipped));
+  return out;
+}
+
+function own(manifest, node) {
+  return DIFFABLE.has(node.type) && (!node.package || !manifest.project || node.package === manifest.project);
+}
+
+function descendants(manifest, id) {
+  const seen = new Set();
+  const queue = [...manifest.nodes.get(id).children];
+  while (queue.length) {
+    const next = queue.shift();
+    if (seen.has(next)) continue;
+    seen.add(next);
+    queue.push(...(manifest.nodes.get(next)?.children ?? []));
+  }
+  return [...seen].filter((d) => manifest.nodes.has(d) && !TEST_TYPES.has(manifest.nodes.get(d).type));
+}
+
+function columnChanges(before, after) {
+  const added = Object.keys(after).filter((c) => !(c in before));
+  const removed = Object.keys(before).filter((c) => !(c in after));
+  const typed = Object.keys(after).filter((c) => c in before && before[c].type !== after[c].type).map((c) => ({ name: c, from: before[c].type, to: after[c].type }));
+  return { added, removed, typed };
+}
+
+function compare(base, current, b, c) {
+  const reasons = [];
+  if ((b.checksum ?? b.code) !== (c.checksum ?? c.code)) reasons.push('code');
+  const config = Object.keys(CONFIG_LABEL).filter((k) => b.config[k] !== c.config[k]).map((k) => ({ field: CONFIG_LABEL[k], from: b.config[k], to: c.config[k] }));
+  if (config.length) reasons.push('config');
+  const columns = columnChanges(b.columns, c.columns);
+  if (columns.added.length || columns.removed.length || columns.typed.length) reasons.push('columns');
+  const deps = { added: c.parents.filter((p) => !b.parents.includes(p)), removed: b.parents.filter((p) => !c.parents.includes(p)) };
+  if (deps.added.length || deps.removed.length) reasons.push('deps');
+  if (b.description !== c.description) reasons.push('description');
+  const tests = { from: base.testsOf.get(b.id) ?? 0, to: current.testsOf.get(c.id) ?? 0 };
+  if (tests.from !== tests.to) reasons.push('tests');
+  return { reasons, config, columns, deps, tests };
+}
+
+function breakingOf(change, base, current, b, c) {
+  const notes = [];
+  if (change.change === 'removed') {
+    const users = descendants(base, b.id).length;
+    if (users) notes.push(`removed while ${users} node${users === 1 ? '' : 's'} in the base depended on it`);
+    return notes;
+  }
+  if (change.change !== 'modified') return notes;
+  const contract = b.config.contract || c.config.contract;
+  const { removed, typed } = change.columns;
+  if (contract && (removed.length || typed.length)) notes.push(`enforced contract changes: ${[...removed.map((r) => `-${r}`), ...typed.map((t) => `${t.name} ${t.from ?? '?'} → ${t.to ?? '?'}`)].join(', ')}`);
+  else if (removed.length && change.downstream) notes.push(`drops ${removed.join(', ')}; ${change.downstream} downstream node${change.downstream === 1 ? '' : 's'} may still select ${removed.length === 1 ? 'it' : 'them'}`);
+  const incremental = [b.config.materialized, c.config.materialized].includes('incremental');
+  if (incremental && change.config.some((c) => ['materialized', 'unique_key', 'incremental_strategy', 'on_schema_change'].includes(c.field))) notes.push('incremental config changed: plan a --full-refresh');
+  if (!b.config.contract && c.config.contract) notes.push('contract now enforced: the build fails if column types drift');
+  return notes;
+}
+
+function byReview(a, b) {
+  return Math.sign(b.breaking.length) - Math.sign(a.breaking.length) || RANK[a.type] - RANK[b.type] || a.name.localeCompare(b.name);
+}
+
+export function diffManifests(base, current) {
+  const ids = new Set([...base.nodes.values()].filter((n) => own(base, n)).map((n) => n.id));
+  for (const n of current.nodes.values()) if (own(current, n)) ids.add(n.id);
+  const changes = [];
+  for (const id of ids) {
+    const b = base.nodes.get(id);
+    const c = current.nodes.get(id);
+    const node = c ?? b;
+    const kind = !b ? 'added' : !c ? 'removed' : 'modified';
+    const detail = kind === 'modified' ? compare(base, current, b, c) : { reasons: [], config: [], columns: { added: [], removed: [], typed: [] }, deps: { added: [], removed: [] }, tests: null };
+    if (kind === 'modified' && !detail.reasons.length) continue;
+    const code = kind === 'removed' ? null : lineDiff(kind === 'added' ? '' : b.code, c.code);
+    const change = {
+      id,
+      name: node.name,
+      type: node.type,
+      file: node.file,
+      change: kind,
+      ...detail,
+      code: code && (kind === 'added' || detail.reasons.includes('code')) && (b?.code || c.code) ? hunks(code) : null,
+      downstream: descendants(kind === 'removed' ? base : current, id).length
+    };
+    change.breaking = breakingOf(change, base, current, b, c);
+    changes.push(change);
+  }
+  changes.sort(byReview);
+  const changed = new Set(changes.map((c) => c.id));
+  const impacted = new Map();
+  for (const change of changes.filter((c) => c.change !== 'removed' && !TEST_TYPES.has(c.type))) {
+    for (const id of descendants(current, change.id)) {
+      if (!changed.has(id) && !impacted.has(id)) impacted.set(id, { id, name: current.nodes.get(id).name, type: current.nodes.get(id).type, via: change.name });
+    }
+  }
+  const models = changes.filter((c) => c.type === 'model' && c.change !== 'removed');
+  const checklist = [
+    ...models.filter((c) => !current.testsOf.get(c.id)).map((c) => `${c.name} has no tests`),
+    ...models.filter((c) => c.change === 'added' && !current.nodes.get(c.id).description.trim()).map((c) => `${c.name} is new and has no description`),
+    ...changes.filter((c) => c.breaking.some((n) => n.includes('full-refresh'))).map((c) => `${c.name}: run with --full-refresh after merge`)
+  ];
+  const build = changes.filter((c) => c.change !== 'removed' && BUILDABLE.has(c.type)).map((c) => `${c.name}+`);
+  const count = (kind) => changes.filter((c) => c.change === kind).length;
+  return {
+    summary: { added: count('added'), modified: count('modified'), removed: count('removed'), impacted: impacted.size, breaking: changes.filter((c) => c.breaking.length).length, tests: changes.filter((c) => TEST_TYPES.has(c.type)).length },
+    changes,
+    impacted: [...impacted.values()].sort((a, b) => (RANK[a.type] ?? 9) - (RANK[b.type] ?? 9) || a.name.localeCompare(b.name)),
+    checklist,
+    command: build.length ? `dbt build --select ${build.join(' ')}` : null
+  };
+}

package/src/core/home.js

@@ -0,0 +1,6 @@
+import os from 'node:os';
+import path from 'node:path';
+
+export function sugarHome(env = process.env, home = os.homedir()) {
+  return env.DBT_SUGAR_HOME || path.join(home, '.dbt-sugar');
+}

package/src/core/mood.js

@@ -0,0 +1,11 @@
+export const MOODS = ['waiting', 'running', 'worried', 'alarmed', 'success', 'failed'];
+
+export function moodOf({ status, counts, warnings }) {
+  const started = counts.success + counts.warn + counts.error + counts.skipped + counts.running;
+  if (status === 'running') {
+    if (counts.error) return 'alarmed';
+    if (counts.warn || warnings) return 'worried';
+    return started ? 'running' : 'waiting';
+  }
+  return status === 'error' || counts.error || counts.skipped ? 'failed' : 'success';
+}