@altimateai/altimate-code 0.9.2 → 0.9.4

package/CHANGELOG.md

@@ -5,6 +5,52 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.9.4] - 2026-07-31
+
+Onboarding UX + first-run OAuth reliability. Ships the CLI's first-run scan + activation menu (Altimate LLM Gateway top of picker; bundled jaffle-shop DuckDB sample for users with no warehouse yet), then hardens the sign-in flow that path leads into.
+
+### Added
+
+- **First-run scan + activation menu.** Fresh installs land on a curated 6-provider picker with Altimate LLM Gateway on top, then a Yes/No "Scan your environment?" gate that reads local config files (`.dbt/profiles.yml`, `dbt_project.yml`, `.git/config`) and routes into one of four branches — warehouse found, dbt-only, git-repo-no-dbt, nothing yet. The last branch offers to materialize a bundled jaffle-shop DuckDB sample dbt project (`~/altimate-sample-dbt/` by default; a suffixed variant if the name is taken) so a user with no warehouse can try Altimate against real data, real dbt models, without touching production. Every branch ends on a numbered "What would you like to do?" menu wired to real skills. (#1001)
+- **Bundled jaffle-shop DuckDB sample project.** Ships with a pre-compiled `target/manifest.json` so `/discover` and `/review` work without dbt-core / dbt-duckdb installed. `dbt build` needs `pip install dbt-duckdb duckdb-cli` (or `pipx install --include-deps dbt-duckdb` / `uv tool install dbt-core --with dbt-duckdb` if you hit PEP 668). (#1001)
+
+### Fixed
+
+- **Loopback OAuth sign-in is resilient to port collisions and long-SSO windows.** The Altimate LLM Gateway callback server now walks 7317-7325 on `EADDRINUSE` (a squatting dev tool on 7317 no longer wedges sign-in) and reports the actual bound port in the redirect. The pending-flow window extended from 5 min to 15 min so corporate SSO + MFA can finish. Two `authorize()` calls arriving concurrently now share one startup promise — both see the actually-bound port instead of one racing past on a stale/undefined value. (#1053)
+- **CI test-isolation leak that turned six `permission/next.test.ts` tilde-expansion tests red.** `mcp/lifecycle.test.ts` was spying on `os.homedir()` in `beforeEach` with no `mockRestore`; the mock leaked forward into the next test file bun loaded, poisoning the tilde-expansion suite with a tmp path. Captured the spy handle and restored it in `afterEach`. Root-fix on the class, not the symptom. (#1053)
+- **`HOME` recovery message is portable and doesn't tell users to write as root.** The prior text pointed at `/Users/you altimate-code` (macOS-only) and suggested `sudo HOME=…` which writes root-owned files a normal-user run then can't modify. Primary guidance is now "re-run without sudo" (install to a per-user prefix, or use nvm/asdf); secondary is `sudo -E HOME="$HOME" altimate-code` with an explicit `chown` recovery hint. (#1053)
+- **PEP 668 install fallbacks actually expose a `dbt` binary.** `pipx install dbt-duckdb` and `uv tool install dbt-duckdb` both succeed but neither publishes the `dbt` entry point (it ships with `dbt-core`, a dependency). Users who followed the fallback after `pip` refused with `externally-managed-environment` hit a second dead end at their point of maximum frustration. Fixed to `pipx install --include-deps dbt-duckdb` and `uv tool install dbt-core --with dbt-duckdb`. The venv option also now asks for the absolute path — `~/.venvs/dbt/bin/dbt` wouldn't expand under the CLI's single-quoted validation. (#1053)
+- **Scan disclosure is honest about telemetry.** The first-run scan's docs previously claimed "nothing leaves your computer". The scan itself doesn't send credentials, model contents, queries, or schema — but it does emit an anonymous environment summary (dbt-detected, warehouse-configured, etc.) through the standard telemetry pipeline if telemetry is enabled. Disclosure updated; `OPENCODE_DISABLE_TELEMETRY=1` remains the offline-strict switch. (#1053)
+- **`sample_setup` error metadata no longer collides with success shape.** The unreachable `suffix: -1` sentinel was reverted to `0`; `success: false` is the disambiguator for metadata consumers, and the error `output` string separately begins `status: error` for the LLM template's failure branch. (#1053)
+- **The auth plugin no longer leaks state-bearing authorize URLs into log files.** An earlier revision wrote the authorize URL to `process.stderr` as a fallback for SSH/tmux users; the auth plugin runs inside a TUI worker whose stdio is redirected to the log file (`packages/opencode/src/cli/tui/worker.ts`), so the write never reached the terminal it was written for. Removed. The TUI's auth dialog already renders the URL as a clickable link and binds `c` to copy it to the clipboard. (#1053)
+
+### Changed
+
+- **`useConnected` and the home-tips visibility gate now share one predicate.** The "is any provider connected?" logic was duplicated in `component/use-connected.tsx` and `feature-plugins/home/tips.tsx`; both now call `isAnyProviderConnected` from `packages/tui/src/util/connected.ts` so a future edit to one can't drift them apart. Behavior unchanged (a semantically identical refactor). Non-`opencode` providers count as connected regardless of `cost` metadata (BYOK / self-hosted / custom-registration path); the `opencode` provider still requires a nonzero-cost model to count. (#1053)
+
+## [0.9.3] - 2026-07-24
+
+Focused polish on the `altimate review` dbt PR reviewer — plus TUI startup UX
+and audit-trail hardening on the signed verdict envelope.
+
+### Added
+
+- **Grain-key `not_null` completeness detector.** For every column named in a `unique_combination_of_columns` test (or the `dbt_utils` equivalent), the reviewer now checks that a `not_null` test or constraint exists on the same column — without it, a NULL grain value silently passes the uniqueness guardrail. Supports contracted models (`constraints:` with `contract.enforced: true`), column-level `data_tests:` / `tests:`, and model-level primary-key constraints. Case-folds column names for Snowflake compatibility. Delivered +11 real findings on the internal 5-PR corpus. (#1029)
+- **`--explain-tier` flag.** Pass `--explain-tier` to surface the classifier's tier-reason list on the verdict envelope so you can see why a diff was rated `trivial`, `lite`, or `full`. Full-tier verdicts also now include the reason line in the PR comment by default (no flag required), so a `REQUEST_CHANGES` on a schema.yml diff is never unexplained. (#1027)
+- **`--force-tier` flag.** *[EXPERIMENTAL / bench debug]* Bypass the classifier with `--force-tier=trivial|lite|full`. The signed envelope carries `tierForced: true` and the classifier's original decision, so an auditor always sees the bypass — the flag can't be used silently. (#1027)
+- **`riskTierPathTokens` config in `.altimate/review.yml`.** Configure named token categories (including `preset:finops` for the built-in cost/billing keyword list) to promote matching files to full review tier. Previously the FinOps preset was hardcoded and always on; it is now opt-in via this config. A typo in a category value surfaces in both stderr and the verdict envelope `tierReasons[]` (and the PR comment) so it can't kill your opt-in silently. (#1028)
+- **`engine.cliVersion` in the signed verdict envelope.** The altimate-code release that generated each verdict is now stamped into `engine.cliVersion` and covered by the HMAC signature — auditors reconstructing decisions from stored envelopes months later can identify which policy version applied.
+- **`staleManifest` flag on the verdict envelope.** When a change-affecting source file has been modified after the manifest was written, the signed envelope now carries `staleManifest: true`. A stderr warning alone is easy for CI to swallow; the envelope field is durable and part of the signed body.
+- **Bootstrap phase labels in the TUI.** While the agent initializes, the busy spinner now shows what it is actually doing ("Loading config…", "Discovering tools…", "Thinking…") matching the convention users already know from other agent UIs. Phase events are also emitted as trace spans for server-side latency profiling. (#1002)
+
+### Changed
+
+- **Risky dbt metadata surfaces never auto-approve.** PRs that touch `data_tests:`, `tests:`, `constraints:`, `contract:`, or `unique_combination_of_columns` in schema.yml under `models/marts/` — or files under any configured `riskTierPathTokens` category — are always promoted to `full` review tier. A small metadata diff can no longer slip through on `trivial` classification. Grounded in a corpus study where two PRs auto-approved with 8–11 human-visible findings each. **CI in `gate` mode may see exit-code changes on affected PRs.** (#1028)
+- **`--no-ai` flag now actually disables the LLM lane.** A yargs `boolean-negation` conflict caused a bare `--no-ai` to silently fall into the help path (exit 0, no review ran). The flag is fixed; CI scripts using `--no-ai` since v0.8.x should verify behavior on upgrade — those runs may have been executing the AI lane and getting billed. (#1027)
+- **`altimate review` auto-discovers `target/manifest.json`.** When `--manifest` is not passed and the config-relative path doesn't resolve, the reviewer walks up from `cwd` to the nearest `dbt_project.yml` and uses its adjacent `target/manifest.json`. Discovery is logged to stderr; explicit `--manifest` still wins. Removes the most common "review did nothing" support case for mono-repo invocations. (#1027)
+- **schema.yml test-removal detection is now column-aware.** The detector parses both sides of the diff structurally (YAML parse rather than diff-line pattern) and keys removals by `(model, column, test)` — eliminating false cancellations where a sibling column re-added the same test type. (#1027)
+- **Stale-manifest detection now runs for local working-tree reviews too.** Previously gated behind `--head`, so the local workflow "`dbt compile` once, edit for an hour, then `altimate review`" — where staleness bites in practice — silently under-warned. The check is limited to files that could materially change the manifest (models, schema.yml, seeds, macros, dbt config) so noise stays bounded.
+
 ## [0.9.2] - 2026-07-20
 
 ### Added

package/package.json

@@ -7,20 +7,20 @@
   "scripts": {
     "postinstall": "bun ./postinstall.mjs || node ./postinstall.mjs"
   },
-  "version": "0.9.2",
+  "version": "0.9.4",
   "license": "MIT",
   "dependencies": {
     "@altimateai/altimate-core": "0.5.1"
   },
   "optionalDependencies": {
-    "@altimateai/altimate-code-linux-arm64": "0.9.2",
-    "@altimateai/altimate-code-linux-x64-baseline": "0.9.2",
-    "@altimateai/altimate-code-linux-x64": "0.9.2",
-    "@altimateai/altimate-code-windows-x64": "0.9.2",
-    "@altimateai/altimate-code-darwin-x64-baseline": "0.9.2",
-    "@altimateai/altimate-code-darwin-arm64": "0.9.2",
-    "@altimateai/altimate-code-darwin-x64": "0.9.2",
-    "@altimateai/altimate-code-windows-x64-baseline": "0.9.2"
+    "@altimateai/altimate-code-darwin-x64-baseline": "0.9.4",
+    "@altimateai/altimate-code-linux-arm64": "0.9.4",
+    "@altimateai/altimate-code-darwin-x64": "0.9.4",
+    "@altimateai/altimate-code-windows-x64-baseline": "0.9.4",
+    "@altimateai/altimate-code-linux-x64": "0.9.4",
+    "@altimateai/altimate-code-linux-x64-baseline": "0.9.4",
+    "@altimateai/altimate-code-darwin-arm64": "0.9.4",
+    "@altimateai/altimate-code-windows-x64": "0.9.4"
   },
   "peerDependencies": {
     "pg": ">=8",

package/sample-projects/jaffle-shop-duckdb/README.md

@@ -0,0 +1,81 @@
+# Jaffle Shop — altimate-code starter sample
+
+Everything below runs against a local DuckDB file — no cloud warehouse, no
+credentials, no network calls.
+
+## What's in here
+
+```
+dbt_project.yml         dbt project config
+profiles.yml            DuckDB profile — path is project-relative
+sample-manifest.json    version metadata used by altimate-code to detect
+                        stale copies on upgrade
+models/
+  staging/
+    stg_customers.sql   renames raw customer columns to snake_case
+    stg_orders.sql      renames raw order columns
+    schema.yml          column descriptions + unique/not_null tests
+  marts/
+    customers.sql       one row per customer, joins in order counts
+    orders.sql          one row per order, joins in customer names
+    schema.yml          column descriptions + tests + relationships
+seeds/
+  raw_customers.csv     3 rows of test data
+  raw_orders.csv        4 rows of test data
+target/
+  manifest.json         PRE-COMPILED dbt manifest — ships with the sample so
+                        altimate-code's static workflows (/discover, /review)
+                        work without dbt-core / dbt-duckdb installed
+```
+
+## What to try
+
+**If you got here via altimate-code's activation menu**, the chat is already
+offering you a numbered menu — pick a number (or say what else you want to
+do). Every option is wired to a real workflow:
+
+- **See what breaks downstream before you change a model** — try `customers`
+  or `orders`.
+- **Review the SQL in this project with every finding explained** — targets
+  the mart models.
+- **Build & query it** — altimate-code detects whether dbt-core + dbt-duckdb
+  are installed, offers to reuse an existing dbt binary if you paste its
+  path, and walks you through the run. Auto-registers the DuckDB file as a
+  warehouse so `sql_execute` connects to the database dbt just built.
+
+**If you `cd`'d into `~/altimate-sample-dbt/` from a different shell** — no
+activation menu, no LLM in the loop. You can drive dbt yourself:
+
+```bash
+# Three PyPI packages that do different jobs:
+#   - dbt-core:   provides the `dbt` binary (the entry point)
+#   - dbt-duckdb: adapter — teaches dbt-core how to talk to DuckDB
+#   - duckdb-cli: standalone `duckdb` binary the ad-hoc query line uses
+# `pip install dbt-duckdb` pulls dbt-core as a dependency, so pip is fine.
+# `pipx install dbt-duckdb` does NOT — pipx only exposes entry points from the
+# named package, and dbt-duckdb has none. Use `--include-deps` if you go pipx.
+pip install dbt-duckdb duckdb-cli         # PEP 668 alternatives below
+cd ~/altimate-sample-dbt                  # wherever you materialized the sample
+dbt seed                                  # load the CSVs into DuckDB
+dbt build                                 # run models + tests
+duckdb target/jaffle.duckdb -c 'select * from customers'
+```
+
+If plain `pip` fails with `externally-managed-environment` (PEP 668, common
+on modern macOS Homebrew and Debian/Ubuntu Python), use one of these instead:
+
+```bash
+pipx install --include-deps dbt-duckdb && pipx install duckdb-cli
+# or
+uv tool install dbt-core --with dbt-duckdb && uv tool install duckdb-cli
+```
+
+Once `dbt` is discoverable (venv, pipx, conda, uv, poetry, homebrew — the CLI
+walks every common Python env manager), altimate-code's "Build & query"
+option surfaces the same actions inside the chat.
+
+## Bringing your own project
+
+When you're ready to switch to your real dbt project, `cd` into it and run
+altimate-code again. The scan will pick up your `dbt_project.yml` and offer
+to connect its warehouse.

package/sample-projects/jaffle-shop-duckdb/dbt_project.yml

@@ -0,0 +1,16 @@
+name: "jaffle_shop"
+version: "1.0.0"
+
+profile: "jaffle_shop"
+
+model-paths: ["models"]
+seed-paths: ["seeds"]
+target-path: "target"
+clean-targets: ["target", "dbt_packages"]
+
+models:
+  jaffle_shop:
+    staging:
+      +materialized: view
+    marts:
+      +materialized: table

package/sample-projects/jaffle-shop-duckdb/models/marts/customers.sql

@@ -0,0 +1,9 @@
+select
+    c.customer_id,
+    c.first_name,
+    c.last_name,
+    count(o.order_id) as order_count,
+    coalesce(sum(o.amount), 0) as total_amount
+from {{ ref('stg_customers') }} c
+left join {{ ref('stg_orders') }} o on c.customer_id = o.customer_id
+group by c.customer_id, c.first_name, c.last_name

package/sample-projects/jaffle-shop-duckdb/models/marts/orders.sql

@@ -0,0 +1,8 @@
+select
+    o.order_id,
+    o.customer_id,
+    c.first_name || ' ' || c.last_name as customer_name,
+    o.order_date,
+    o.amount
+from {{ ref('stg_orders') }} o
+join {{ ref('stg_customers') }} c on o.customer_id = c.customer_id

package/sample-projects/jaffle-shop-duckdb/models/marts/schema.yml

@@ -0,0 +1,32 @@
+version: 2
+
+models:
+  - name: customers
+    description: One row per customer with total order count and revenue.
+    columns:
+      - name: customer_id
+        description: Primary key.
+        data_tests:
+          - unique
+          - not_null
+      - name: order_count
+        description: Number of orders placed by the customer (0 when none).
+        data_tests:
+          - not_null
+      - name: total_amount
+        description: Sum of all order amounts (0 when none).
+        data_tests:
+          - not_null
+
+  - name: orders
+    description: One row per order with a joined customer name.
+    columns:
+      - name: order_id
+        description: Primary key.
+        data_tests:
+          - unique
+          - not_null
+      - name: customer_id
+        description: Foreign key to `stg_customers`.
+        data_tests:
+          - not_null

package/sample-projects/jaffle-shop-duckdb/models/staging/schema.yml

@@ -0,0 +1,27 @@
+version: 2
+
+models:
+  - name: stg_customers
+    description: Renamed customer columns from the raw seed.
+    columns:
+      - name: customer_id
+        description: Primary key of the customer.
+        data_tests:
+          - unique
+          - not_null
+
+  - name: stg_orders
+    description: Renamed order columns from the raw seed.
+    columns:
+      - name: order_id
+        description: Primary key of the order.
+        data_tests:
+          - unique
+          - not_null
+      - name: customer_id
+        description: Foreign key to `stg_customers`.
+        data_tests:
+          - not_null
+          - relationships:
+              to: ref('stg_customers')
+              field: customer_id

package/sample-projects/jaffle-shop-duckdb/models/staging/stg_customers.sql

@@ -0,0 +1,5 @@
+select
+    id as customer_id,
+    first_name,
+    last_name
+from {{ ref('raw_customers') }}

package/sample-projects/jaffle-shop-duckdb/models/staging/stg_orders.sql

@@ -0,0 +1,6 @@
+select
+    id as order_id,
+    customer_id,
+    order_date,
+    amount
+from {{ ref('raw_orders') }}

package/sample-projects/jaffle-shop-duckdb/profiles.yml

@@ -0,0 +1,14 @@
+# DuckDB profile — everything runs locally against a single file at
+# `target/jaffle.duckdb` (created on first `dbt build`). No cloud credentials.
+# `path:` is unqualified, so dbt-duckdb resolves it against the PROCESS
+# working directory at build time — NOT the project directory. Run
+# `dbt build` from the materialized sample dir (`cd <sample-path>`) and
+# the database lands at `<sample-path>/target/jaffle.duckdb`.
+# Run it from anywhere else and dbt writes to `$PWD/target/jaffle.duckdb`.
+jaffle_shop:
+  target: dev
+  outputs:
+    dev:
+      type: duckdb
+      path: "target/jaffle.duckdb"
+      threads: 1

package/sample-projects/jaffle-shop-duckdb/sample-manifest.json

@@ -0,0 +1,27 @@
+{
+  "$comment": "Metadata about this sample project. Distinct from dbt's target/manifest.json — this is our own version stamp for conflict detection on the materialized copy at ~/altimate-sample-dbt/. If you edit any source file below, run ./regenerate.sh and commit the refreshed target/manifest.json alongside your change.",
+  "name": "jaffle-shop-duckdb",
+  "version": "1.0.0",
+  "kind": "altimate-starter-sample",
+  "source": "packages/opencode/sample-projects/jaffle-shop-duckdb",
+  "requires": {
+    "dbt-core": ">=1.7 <2.0",
+    "dbt-duckdb": ">=1.7 <2.0"
+  },
+  "notes": [
+    "Renamed profile from the original test fixture: `test_jaffle_shop` → `jaffle_shop`.",
+    "DuckDB target file resolves project-relative at `target/jaffle.duckdb`; no host paths bake into the profile.",
+    "target/manifest.json ships pre-compiled so static workflows (/discover, /review) work without dbt installed."
+  ],
+  "$assets_comment": "Single source of truth for the file list shipped to end users. `packages/opencode/src/altimate/onboarding/materialize.ts` copies these into the user's home; `packages/opencode/script/publish.ts` copies the same list into the wrapper npm package at release time; `packages/opencode/test/altimate/onboarding/publish-parity.test.ts` cross-checks both consumers use the same list. Adding a new sample file? Add it here — everything else picks it up automatically.",
+  "assets": [
+    { "from": "README.md", "kind": "file", "required": true },
+    { "from": "dbt_project.yml", "kind": "file", "required": true },
+    { "from": "profiles.yml", "kind": "file", "required": true },
+    { "from": "sample-manifest.json", "kind": "file", "required": true },
+    { "from": ".gitignore", "kind": "file", "required": false },
+    { "from": "models", "kind": "dir", "required": true },
+    { "from": "seeds", "kind": "dir", "required": true },
+    { "from": "target/manifest.json", "kind": "file", "required": true }
+  ]
+}

package/sample-projects/jaffle-shop-duckdb/seeds/raw_customers.csv

@@ -0,0 +1,4 @@
+id,first_name,last_name
+1,Alice,Smith
+2,Bob,Jones
+3,Carol,White

package/sample-projects/jaffle-shop-duckdb/seeds/raw_orders.csv

@@ -0,0 +1,5 @@
+id,customer_id,order_date,amount
+1,1,2024-01-15,100
+2,1,2024-02-20,200
+3,2,2024-01-10,150
+4,3,2024-03-05,300