feat: add Altimate provider with /login command and credential valida…

docs/docs/getting-started.md

@@ -81,6 +81,50 @@ Add a warehouse connection to `.altimate-code/connections.json`. Here's a quick
 
 For all warehouse types (Snowflake, BigQuery, Databricks, PostgreSQL, Redshift, DuckDB, MySQL, SQL Server) and advanced options (key-pair auth, ADC, SSH tunneling), see the [Warehouses reference](configure/warehouses.md).
 
+### Connecting to Altimate
+
+If you have an Altimate platform account, run `/connect` in the TUI, select **Altimate**, and enter your credentials in this format:
+
+```text
+instance-url::instance-name::api-key
+```
+
+For example: `https://api.getaltimate.com::acme::your-api-key`
+
+- **Instance URL** — `https://api.myaltimate.com` or `https://api.getaltimate.com` depending on your dashboard domain
+- **Instance Name** — the subdomain from your Altimate dashboard URL (e.g. `acme` from `https://acme.app.myaltimate.com`)
+- **API Key** — go to **Settings > API Keys** in your Altimate dashboard and click **Copy**
+
+Credentials are validated against the Altimate API before being saved. If you prefer to configure credentials directly (e.g. for CI or environment variable substitution), you can also create `~/.altimate/altimate.json` manually — if that file exists it takes priority over the TUI-entered credentials.
+
+**`altimate.json` schema:**
+
+```json
+{
+ "altimateUrl": "https://api.myaltimate.com",
+ "altimateInstanceName": "acme",
+ "altimateApiKey": "your-api-key",
+ "mcpServerUrl": "https://mcpserver.getaltimate.com/sse"
+}
+```
+
+| Field | Required | Description |
+|---|---|---|
+| `altimateUrl` | Yes | Full base URL of the Altimate API |
+| `altimateInstanceName` | Yes | Your tenant/instance identifier |
+| `altimateApiKey` | Yes | API key from **Settings > API Keys** |
+| `mcpServerUrl` | No | Custom MCP server URL (defaults to the hosted endpoint) |
+
+You can use `${env:VAR_NAME}` syntax to reference environment variables instead of hardcoding secrets:
+
+```json
+{
+ "altimateUrl": "https://api.myaltimate.com",
+ "altimateInstanceName": "acme",
+ "altimateApiKey": "${env:ALTIMATE_API_KEY}"
+}
+```
+
 ## Step 4: Choose an Agent Mode
 
 altimate offers specialized agent modes for different workflows:

packages/opencode/src/altimate/api/client.ts

@@ -54,13 +54,103 @@ export namespace AltimateApi {
  return Filesystem.exists(credentialsPath())
  }
 
+ function resolveEnvVars(obj: unknown): unknown {
+ if (typeof obj === "string") {
+ return obj.replace(/\$\{env:([^}]+)\}/g, (_, envVar) => {
+ const value = process.env[envVar]
+ if (value === undefined) throw new Error(`Environment variable ${envVar} not found`)
+ return value
+ })
+ }
+ if (Array.isArray(obj)) return obj.map(resolveEnvVars)
+ if (obj && typeof obj === "object")
+ return Object.fromEntries(Object.entries(obj).map(([k, v]) => [k, resolveEnvVars(v)]))
+ return obj
+ }
+
  export async function getCredentials(): Promise<AltimateCredentials> {
  const p = credentialsPath()
  if (!(await Filesystem.exists(p))) {
  throw new Error(`Altimate credentials not found at ${p}`)
  }
- const raw = JSON.parse(await Filesystem.readText(p))
- return AltimateCredentials.parse(raw)
+ const raw = resolveEnvVars(JSON.parse(await Filesystem.readText(p)))
+ const creds = AltimateCredentials.parse(raw)
+ return {
+ ...creds,
+ altimateUrl: creds.altimateUrl.replace(/\/+$/, ""),
+ }
+ }
+
+ export function parseAltimateKey(value: string): {
+ altimateUrl: string
+ altimateInstanceName: string
+ altimateApiKey: string
+ } | null {
+ const parts = value.trim().split("::")
+ if (parts.length < 3) return null
+ const url = parts[0].trim()
+ const instance = parts[1].trim()
+ const key = parts.slice(2).join("::").trim()
+ if (!url || !instance || !key) return null
+ if (!url.startsWith("http://") && !url.startsWith("https://")) return null
+ return { altimateUrl: url, altimateInstanceName: instance, altimateApiKey: key }
+ }
+
+ export async function saveCredentials(creds: {
+ altimateUrl: string
+ altimateInstanceName: string
+ altimateApiKey: string
+ mcpServerUrl?: string
+ }): Promise<void> {
+ await Filesystem.writeJson(
+ credentialsPath(),
+ { ...creds, altimateUrl: creds.altimateUrl.replace(/\/+$/, "") },
+ 0o600,
+ )
+ }
+
+ const VALID_TENANT_REGEX = /^[a-z_][a-z0-9_-]*$/
+
+ /** Validates credentials against the Altimate API.
+ * Mirrors AltimateSettingsHelper.validateSettings from altimate-mcp-engine. */
+ export async function validateCredentials(creds: {
+ altimateUrl: string
+ altimateInstanceName: string
+ altimateApiKey: string
+ }): Promise<{ ok: true } | { ok: false; error: string }> {
+ if (!VALID_TENANT_REGEX.test(creds.altimateInstanceName)) {
+ return {
+ ok: false,
+ error:
+ "Invalid instance name (must be lowercase letters, numbers, underscores, hyphens, starting with letter or underscore)",
+ }
+ }
+ try {
+ const url = `${creds.altimateUrl.replace(/\/+$/, "")}/dbt/v3/validate-credentials`
+ const res = await fetch(url, {
+ method: "GET",
+ headers: {
+ "x-tenant": creds.altimateInstanceName,
+ Authorization: `Bearer ${creds.altimateApiKey}`,
+ "Content-Type": "application/json",
+ },
+ })
+ if (res.status === 401) {
+ const body = await res.text()
+ return { ok: false, error: `Invalid API key - ${body}` }
+ }
+ if (res.status === 403) {
+ const body = await res.text()
+ return { ok: false, error: `Invalid instance name - ${body}` }
+ }
+ if (!res.ok) {
+ return { ok: false, error: `Connection failed (${res.status} ${res.statusText})` }
+ }
+ return { ok: true }
+ } catch (err) {
+ const detail = err instanceof Error ? err.message : String(err)
+ return { ok: false, error: `Could not reach Altimate API: ${detail}` }
+ }
  }
 
  async function request(creds: AltimateCredentials, method: string, endpoint: string, body?: unknown) {

packages/opencode/src/altimate/plugin/altimate.ts

@@ -0,0 +1,15 @@
+import type { Hooks, PluginInput } from "@opencode-ai/plugin"
+
+export async function AltimateAuthPlugin(_input: PluginInput): Promise<Hooks> {
+ return {
+ auth: {
+ provider: "altimate-backend",
+ methods: [
+ {
+ type: "api",
+ label: "Connect to Altimate",
+ },
+ ],
+ },
+ }
+}

packages/opencode/src/cli/cmd/tui/component/dialog-provider.tsx

@@ -13,6 +13,9 @@ import { DialogModel } from "./dialog-model"
 import { useKeyboard } from "@opentui/solid"
 import { Clipboard } from "@tui/util/clipboard"
 import { useToast } from "../ui/toast"
+// altimate_change start — import AltimateApi for direct credential file write
+import { AltimateApi } from "../../../../altimate/api/client"
+// altimate_change end
 
 const PROVIDER_PRIORITY: Record<string, number> = {
  opencode: 0,
@@ -210,6 +213,9 @@ function ApiMethod(props: ApiMethodProps) {
  const sdk = useSDK()
  const sync = useSync()
  const { theme } = useTheme()
+ // altimate_change start — altimate-backend: validation error signal
+ const [validationError, setValidationError] = createSignal<string | null>(null)
+ // altimate_change end
 
  return (
  <DialogPrompt
@@ -239,10 +245,51 @@ function ApiMethod(props: ApiMethodProps) {
  </text>
  </box>
  ),
+ // altimate_change start — altimate-backend credential format description
+ "altimate-backend": (
+ <box gap={1}>
+ <text fg={theme.textMuted}>
+ Enter your Altimate credentials in this format:
+ </text>
+ <text fg={theme.text}>
+ instance-url::instance-name::api-key
+ </text>
+ <text fg={theme.textMuted}>
+ e.g. https://api.getaltimate.com::mycompany::abc123
+ </text>
+ <Show when={validationError()}>
+ <text fg={theme.error}>{validationError()!}</text>
+ </Show>
+ </box>
+ ),
+ // altimate_change end
  }[props.providerID] ?? undefined
  }
  onConfirm={async (value) => {
  if (!value) return
+ // altimate_change start — altimate-backend: validate then write credentials file directly
+ if (props.providerID === "altimate-backend") {
+ const parsed = AltimateApi.parseAltimateKey(value)
+ if (!parsed) {
+ setValidationError("Invalid format — use: instance-url::instance-name::api-key")
+ return
+ }
+ const validation = await AltimateApi.validateCredentials(parsed)
+ if (!validation.ok) {
+ setValidationError(validation.error)
+ return
+ }
+ try {
+ await AltimateApi.saveCredentials(parsed)
+ await sdk.client.instance.dispose()
+ await sync.bootstrap()
+ dialog.replace(() => <DialogModel providerID={props.providerID} />)
+ } catch (err) {
+ setValidationError(err instanceof Error ? err.message : "Failed to save credentials")
+ }
+ return
+ }
+ // altimate_change end
  await sdk.client.auth.set({
  providerID: props.providerID,
  auth: {

packages/opencode/src/plugin/index.ts

@@ -15,6 +15,9 @@ import { gitlabAuthPlugin as GitlabAuthPlugin } from "@gitlab/opencode-gitlab-au
 // altimate_change start — snowflake cortex plugin import
 import { SnowflakeCortexAuthPlugin } from "../altimate/plugin/snowflake"
 // altimate_change end
+// altimate_change start — altimate backend auth plugin
+import { AltimateAuthPlugin } from "../altimate/plugin/altimate"
+// altimate_change end
 
 export namespace Plugin {
  const log = Log.create({ service: "plugin" })
@@ -25,8 +28,8 @@ export namespace Plugin {
  // GitlabAuthPlugin uses a different version of @opencode-ai/plugin (from npm)
  // vs the workspace version, causing a type mismatch on internal HeyApiClient.
  // The types are structurally compatible at runtime.
- // altimate_change start — snowflake cortex internal plugin
- const INTERNAL_PLUGINS: PluginInstance[] = [CodexAuthPlugin, CopilotAuthPlugin, GitlabAuthPlugin as unknown as PluginInstance, SnowflakeCortexAuthPlugin]
+ // altimate_change start — snowflake cortex and altimate backend internal plugins
+ const INTERNAL_PLUGINS: PluginInstance[] = [CodexAuthPlugin, CopilotAuthPlugin, GitlabAuthPlugin as unknown as PluginInstance, SnowflakeCortexAuthPlugin, AltimateAuthPlugin]
  // altimate_change end
 
  const state = Instance.state(async () => {

packages/opencode/src/provider/provider.ts

@@ -18,6 +18,7 @@ import { iife } from "@/util/iife"
 import { Global } from "../global"
 import path from "path"
 import { Filesystem } from "../util/filesystem"
+import { AltimateApi } from "../altimate/api/client"
 
 // Direct imports for bundled providers
 import { createAmazonBedrock, type AmazonBedrockProviderSettings } from "@ai-sdk/amazon-bedrock"
@@ -181,6 +182,51 @@ export namespace Provider {
  options: hasKey ? {} : { apiKey: "public" },
  }
  },
+ // altimate_change start — Altimate backend provider: ~/.altimate/altimate.json first, auth store (TUI-configured) as fallback
+ "altimate-backend": async () => {
+ // Path 1: ~/.altimate/altimate.json (primary — manual file or env-var substitution, never overwritten)
+ const isConfigured = await AltimateApi.isConfigured()
+ if (isConfigured) {
+ try {
+ const creds = await AltimateApi.getCredentials()
+ return {
+ autoload: true,
+ options: {
+ baseURL: `${creds.altimateUrl.replace(/\/+$/, "")}/agents/v1`,
+ apiKey: creds.altimateApiKey,
+ headers: {
+ "x-tenant": creds.altimateInstanceName,
+ },
+ },
+ }
+ } catch {
+ // Suppress stale auth so the generic Auth.all() merge doesn't leave an invalid provider
+ await Auth.remove(ProviderID.make("altimate-backend")).catch(() => {})
+ return { autoload: false }
+ }
+ }
+ // Path 2: auth store (populated by TUI entry, file not yet written)
+ const auth = await Auth.get(ProviderID.make("altimate-backend"))
+ if (auth?.type === "api") {
+ const parsed = AltimateApi.parseAltimateKey(auth.key)
+ if (parsed) {
+ return {
+ autoload: true,
+ options: {
+ baseURL: `${parsed.altimateUrl.replace(/\/+$/, "")}/agents/v1`,
+ apiKey: parsed.altimateApiKey,
+ headers: {
+ "x-tenant": parsed.altimateInstanceName,
+ },
+ },
+ }
+ }
+ // Invalid key format — remove stale auth entry
+ await Auth.remove(ProviderID.make("altimate-backend")).catch(() => {})
+ }
+ return { autoload: false }
+ },
+ // altimate_change end
  openai: async () => {
  return {
  autoload: false,
@@ -973,6 +1019,45 @@ export namespace Provider {
  }
  // altimate_change end
 
+ // altimate_change start — register altimate-backend as an OpenAI-compatible provider
+ if (!database["altimate-backend"]) {
+ const backendModels: Record<string, Model> = {
+ "altimate-default": {
+ id: ModelID.make("altimate-default"),
+ providerID: ProviderID.make("altimate-backend"),
+ name: "Altimate AI",
+ family: "openai",
+ api: { id: "altimate-default", url: "", npm: "@ai-sdk/openai-compatible" },
+ status: "active",
+ headers: {},
+ options: {},
+ cost: { input: 0, output: 0, cache: { read: 0, write: 0 } },
+ limit: { context: 200000, output: 128000 },
+ capabilities: {
+ temperature: true,
+ reasoning: false,
+ attachment: false,
+ toolcall: true,
+ input: { text: true, audio: false, image: true, video: false, pdf: false },
+ output: { text: true, audio: false, image: false, video: false, pdf: false },
+ interleaved: false,
+ },
+ release_date: "2025-01-01",
+ variants: {},
+ },
+ }
+ database["altimate-backend"] = {
+ id: ProviderID.make("altimate-backend"),
+ name: "Altimate",
+ source: "custom",
+ env: [],
+ options: {},
+ models: backendModels,
+ }
+ }
+ // altimate_change end
+
+
  function mergeProvider(providerID: ProviderID, provider: Partial<Info>) {
  const existing = providers[providerID]
  if (existing) {

packages/opencode/src/util/filesystem.ts

@@ -55,6 +55,9 @@ export namespace Filesystem {
  try {
  if (mode) {
  await writeFile(p, content, { mode })
+ // altimate_change start — upstream_fix: writeFile { mode } option does not reliably set permissions; explicit chmod ensures correct mode is applied
+ await chmod(p, mode)
+ // altimate_change end
  } else {
  await writeFile(p, content)
  }
@@ -63,6 +66,9 @@ export namespace Filesystem {
  await mkdir(dirname(p), { recursive: true })
  if (mode) {
  await writeFile(p, content, { mode })
+ // altimate_change start — upstream_fix: writeFile { mode } option does not reliably set permissions; explicit chmod ensures correct mode is applied
+ await chmod(p, mode)
+ // altimate_change end
  } else {
  await writeFile(p, content)
  }