@altimateai/altimate-code 0.9.3 → 0.9.4

package/CHANGELOG.md

@@ -5,6 +5,29 @@ 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

package/package.json

@@ -7,20 +7,20 @@
   "scripts": {
     "postinstall": "bun ./postinstall.mjs || node ./postinstall.mjs"
   },
-  "version": "0.9.3",
+  "version": "0.9.4",
   "license": "MIT",
   "dependencies": {
     "@altimateai/altimate-core": "0.5.1"
   },
   "optionalDependencies": {
-    "@altimateai/altimate-code-darwin-x64-baseline": "0.9.3",
-    "@altimateai/altimate-code-linux-arm64": "0.9.3",
-    "@altimateai/altimate-code-darwin-x64": "0.9.3",
-    "@altimateai/altimate-code-windows-x64-baseline": "0.9.3",
-    "@altimateai/altimate-code-linux-x64": "0.9.3",
-    "@altimateai/altimate-code-linux-x64-baseline": "0.9.3",
-    "@altimateai/altimate-code-darwin-arm64": "0.9.3",
-    "@altimateai/altimate-code-windows-x64": "0.9.3"
+    "@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