@aexol/spectral 0.0.1

package/CHANGELOG.md

@@ -0,0 +1,106 @@
+# Changelog
+
+All notable changes to `@aexol/spectral` are documented here.
+Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+## [Unreleased]
+
+### Added
+- Admin OpenRouter catalog picker in `/studio/admin/models` (Base Models tab):
+  search across 368 models from `https://openrouter.ai/api/v1/models` and add
+  to the whitelist with one click. Picker marks models already present in the
+  whitelist (disabled add) regardless of their enabled state.
+- `Query.adminOpenRouterCatalog: [OpenRouterModel!]!` — admin-gated, with a
+  1h in-memory TTL cache of the upstream catalog.
+- `Mutation.adminCreateBaseModel(input: BaseModelCreateInput!): BaseModel!`
+  with duplicate guard on `(provider, modelId)`. Defaults `enabled=true`.
+- Verbatim `modelId` routing for `provider="openrouter"` in the backend
+  inference proxy: no `${provider}/${modelId}` rebuild — picker-sourced rows
+  carry the canonical OR ID and are sent through unchanged. Legacy rebuild
+  fallback is preserved for older naive-provider rows
+  (`provider="deepseek"`, `"google"`, etc.).
+- Per-session model selection: choose AI model from a whitelist managed by
+  admins. Selection persists per session in localStorage and is sent in the
+  `prompt` envelope to apply via pi `setModel()`.
+- New SQLite column `sessions.model_id` for cross-restart recovery of
+  selected model.
+- Synthetic pi providers `spectral-proxy-anthropic` and
+  `spectral-proxy-openai`, registered at `PiBridge` start, that point pi's
+  `ModelRegistry` at the backend's `/v1` proxy. `AuthStorage.inMemory()` and
+  `ModelRegistry.inMemory()` skip on-disk pi credentials in `serve` mode.
+- Backend `/v1/messages` and `/v1/chat/completions` machine-JWT auth branch
+  with raw `modelId` resolution against the `BaseModel` whitelist.
+- TTL-cached `fetchAllowedModels` GraphQL query used by `spectral serve` to
+  discover the team's allowed models from the backend at startup.
+- Startup info log on `spectral serve`:
+  `✓ Inference routed via backend proxy (N model(s) available)`.
+
+### Changed
+- Soft-remove a model from the whitelist by reusing the existing per-row
+  `Switch` toggle (no separate Remove button). Disabled rows remain visible
+  in the admin table and can be re-enabled with the same Switch.
+- Available models are now read from a backend-managed `BaseModel` table
+  (synced from https://models.dev/api.json by admins) instead of a
+  hardcoded frontend whitelist.
+- `spectral serve` inference now routes through the backend proxy
+  (centralized API keys) instead of reading `~/.pi/agent/auth.json`. CLI
+  machines no longer need provider API keys locally; the backend manages
+  them. The per-machine machine JWT carries auth, and the per-team
+  `BaseModel` whitelist gates which models can be used.
+
+### Fixed
+- Admin "Add from OpenRouter" picker GraphQL syntax error
+  (`Expected Name, found String "modalities"`). Mutations
+  `adminCreateBaseModel` and `adminUpdateBaseModel` now pass their input
+  objects via Zeus `$()` variables instead of inline serialization,
+  so nested array fields (`modalities`, `supportedParameters`) parse
+  correctly server-side.
+
+### Removed
+- Hardcoded `landing/config/model-whitelist.ts` allowlist (replaced by
+  the DB-backed whitelist).
+
+### Migration
+- `spectral` (CLI / TUI subprocess mode): no change — still uses local
+  `~/.pi/agent/auth.json`.
+- `spectral serve`: ensure the backend has the relevant provider keys
+  configured (`ANTHROPIC_API_KEY`, `OPENROUTER_API_KEY`, etc.). Local
+  `~/.pi/agent/auth.json` is ignored when running `serve`.
+
+## [0.1.0] — 2026-04-29
+
+Initial release.
+
+### Added
+- `spectral login` — interactive authentication. Verifies the team API key
+  against the Aexol MCP backend before persisting credentials to
+  `~/.spectral/config.json` (mode `0600`).
+- `spectral logout` — removes stored credentials. Idempotent.
+- `spectral serve` — always-on agent that connects this machine to the
+  Aexol relay over a single long-lived WebSocket.
+  - Registers a machine identity with your team on first run; reuses the
+    issued JWT on subsequent runs.
+  - Reconnects automatically with exponential backoff.
+  - Graceful shutdown on `SIGINT` / `SIGTERM`: drains in-flight responses
+    and closes the relay cleanly before exiting.
+  - `--machine-name <name>` overrides the default `os.hostname()`.
+- Browser-driven sessions through the Aexol web UI:
+  - Machine picker for switching between paired devices.
+  - Multi-tab sync of project and session lifecycle changes (create,
+    rename, delete) via a per-machine meta channel.
+  - Stuck-turn watchdog re-enables the composer after 60s of silence.
+- Local-first storage: projects, sessions, and messages live in a SQLite
+  database at `~/.spectral/sessions.db`. They never leave the machine.
+- Bundled Aexol MCP extension auto-loaded for the local TUI path so
+  `spectral` (no subcommand) acts as a fully-configured pi session.
+- Plain pi pass-through: any flag that isn't a Spectral subcommand is
+  forwarded verbatim to `pi`.
+
+### Notes
+- Backend storage is identity + machine metadata only. Message content,
+  code, and model API keys never leave your machine.
+- One SQLite database per machine — switching machines in the browser
+  shows a different project list, by design.
+- Pi auth tokens (Anthropic, OpenAI, Cerebras, Google, custom endpoints)
+  are managed by pi itself in `~/.pi/agent/auth.json` and are not read or
+  transmitted by Spectral.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aexol
+
+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

@@ -0,0 +1,213 @@
+# @aexol/spectral
+
+> Coding agent that never sleeps.
+
+## What is Spectral?
+
+Spectral is the always-on coding agent for [Aexol](https://aexol.com). You install
+it on every machine you want to code on, run `spectral serve`, and your devices
+appear in the Aexol web UI as live agents you can drive from any browser tab — no
+port forwarding, no SSH, no exposing localhost.
+
+Under the hood, Spectral is a thin branded wrapper around
+[pi](https://www.npmjs.com/package/@mariozechner/pi-coding-agent) by Mario
+Zechner, plus a relay client that connects each machine to Aexol's backend.
+Browsers talk to your machines through that relay; the backend never sees your
+code or your messages — those stay on the device. Model API keys are handled
+differently depending on which command you run (see
+[How inference is routed](#how-inference-is-routed)).
+
+## Install
+
+```bash
+npm install -g @aexol/spectral
+```
+
+Requires Node.js **20 or newer**.
+
+## Quickstart
+
+1. **Authenticate**
+
+   ```bash
+   spectral login
+   ```
+
+   You'll be prompted for your Aexol MCP URL (defaults to `https://api.aexol.ai/mcp`)
+   and a team API key (`sk-aexol-team-…`). Credentials are written to
+   `~/.spectral/config.json` with mode `0600`.
+
+2. **Start the agent**
+
+   ```bash
+   spectral serve
+   ```
+
+   This registers the machine with your team, opens a long-lived WebSocket to
+   the Aexol relay, and stays up. Reconnects are automatic with exponential
+   backoff. Leave it running — that's the point.
+
+3. **Open the browser**
+
+   Visit the Aexol web UI. Your machine appears in the picker; pick it and you
+   can create projects, open sessions, and chat with the agent on that machine
+   from any tab.
+
+You can also run Spectral as a plain local TUI without the relay — just invoke
+`spectral` (no subcommand) and it acts as a normal pi terminal session with the
+Aexol MCP extension auto-loaded.
+
+## Commands
+
+| Command            | Description                                                                   |
+|--------------------|-------------------------------------------------------------------------------|
+| `spectral`         | Local TUI. Forwards all flags to pi; loads the bundled Aexol MCP extension.   |
+| `spectral login`   | Interactive auth. Verifies the key against the MCP backend and stores it.     |
+| `spectral logout`  | Removes `~/.spectral/config.json`. Idempotent.                                |
+| `spectral serve`   | Connect this machine to the Aexol relay. Stays up; survives reconnects.       |
+| `spectral --version` | Print version.                                                              |
+| `spectral --help`  | Print Spectral header, then pi's full help.                                   |
+
+### `spectral serve` flags
+
+| Flag                       | Description                                                       |
+|----------------------------|-------------------------------------------------------------------|
+| `--machine-name <name>`    | Override the display name (default: `os.hostname()`).             |
+
+Anything that isn't a Spectral subcommand is forwarded verbatim to pi, so any
+pi flag you know works. Example: `spectral -p "summarize this repo"`.
+
+## How it works
+
+```
+   ┌────────────────┐         ┌─────────────────┐         ┌────────────────┐
+   │  Browser tab   │────────▶│  Aexol backend  │◀────────│  spectral serve │
+   │ (Aexol web UI) │  WSS    │     (relay)     │   WSS   │ (your machine)  │
+   └────────────────┘         └─────────────────┘         └────────────────┘
+                                       │
+                              identity + routing only
+                              (no message content, no code)
+```
+
+- Your machine runs `spectral serve` and registers with the relay using a
+  machine JWT issued at first run.
+- Browser sessions for that machine open a WebSocket to the backend. The
+  backend forwards every frame to your machine and back — it never reads or
+  stores message content.
+- All your local state — projects, sessions, messages, pi auth tokens —
+  lives on the device. The backend only knows machine identity (id, display
+  name, hostname, last-seen) and team membership.
+
+## How inference is routed
+
+Spectral has two distinct execution paths, and they handle model API keys
+differently. This is intentional — pick the one that matches your security
+model.
+
+```
+spectral (CLI / TUI mode)            spectral serve (relay mode)
+─────────────────────────            ─────────────────────────────
+pi reads ~/.pi/agent/auth.json   →   pi runs in-process via PiBridge
+   ↓                                    ↓
+local Anthropic / OpenAI keys        ALL inference → backend `/v1` proxy
+   ↓                                    ↓
+direct call to provider              backend uses centralized API keys
+                                        ↓
+                                     scoped to team's BaseModel whitelist
+```
+
+- **`spectral` (CLI subprocess mode)** — pi runs as a normal subprocess and
+  uses whatever provider keys you've stored locally in `~/.pi/agent/auth.json`
+  (Anthropic, OpenAI, Cerebras, Google, custom OpenAI-compatible endpoints).
+  Spectral never reads or transmits these. This is the classic local-only
+  flow.
+- **`spectral serve` (relay mode)** — pi runs in-process inside the serve
+  daemon. All inference traffic is proxied through the Aexol backend's
+  `/v1/messages` and `/v1/chat/completions` endpoints, authenticated with the
+  per-machine machine JWT. The backend holds the upstream provider keys and
+  enforces a per-team `BaseModel` whitelist server-side. The local
+  `~/.pi/agent/auth.json` is **not read** in this mode (`AuthStorage.inMemory()`).
+
+Why two paths? `spectral serve` is designed for shared / managed machines
+where the team controls which models are usable and operators don't want
+provider keys sitting on every box. `spectral` (no subcommand) is the
+unmanaged TUI path and behaves like a vanilla pi install.
+
+## Configuration
+
+| Path / variable                           | Purpose                                                |
+|-------------------------------------------|--------------------------------------------------------|
+| `~/.spectral/config.json`                 | Aexol MCP URL + team API key. Created by `spectral login`. Mode `0600`. |
+| `~/.spectral/machine.json`                | Machine identity + relay JWT. Created on first `spectral serve`.        |
+| `~/.spectral/sessions.db`                 | Local SQLite for projects, sessions, messages.         |
+| `SPECTRAL_CONFIG_DIR`                     | Override the directory above.                          |
+| `SPECTRAL_MCP_URL`                        | Override the MCP URL at login time.                    |
+| `SPECTRAL_BACKEND_URL`                    | Override the backend HTTP base for `spectral serve`.   |
+| `SPECTRAL_RELAY_URL`                      | Override the derived relay WebSocket URL.              |
+
+Pi's own auth state for the local TUI path (Anthropic, OpenAI, etc.) lives
+in `~/.pi/agent/auth.json` on the same machine. Spectral never reads it and
+never sends it anywhere. Note that `spectral serve` does **not** use this
+file — it routes inference through the backend proxy instead (see
+[How inference is routed](#how-inference-is-routed)).
+
+## Multiple machines
+
+You can run `spectral serve` on as many machines as you like under one team —
+each gets its own machine identity and its own SQLite. The browser picker
+lists all of them; switching machines shows that machine's project list and
+session history. Switching is a hard context change: the previous selection
+is cleared so you don't accidentally talk to the wrong device.
+
+## Troubleshooting
+
+- **My machine isn't showing up in the browser picker.**
+  Make sure `spectral serve` is still running (it logs reconnect attempts to
+  stderr). If `spectral login` was run a long time ago and the team key was
+  rotated, re-run `spectral login`.
+
+- **WebSocket keeps disconnecting.**
+  The relay client reconnects automatically with exponential backoff. Brief
+  network blips are expected and handled. If the backoff loop is constant,
+  check that your team API key is still valid and that your network allows
+  outbound WebSocket connections to the configured backend.
+
+- **`better-sqlite3` errors on first `spectral serve`.**
+  This usually means the native module didn't compile during install. Try
+  `cd ~/.spectral && npm rebuild better-sqlite3`, or reinstall Spectral after
+  ensuring you have a working C/C++ toolchain (`make`, a C compiler, Python).
+
+- **I want to revoke a machine.**
+  Stop `spectral serve` on that device. Machine revocation from the Aexol UI
+  is on the roadmap; today the most reliable approach is to rotate the team
+  API key, which invalidates every machine's relay JWT for that team.
+
+## Privacy & data
+
+- **Model API keys**:
+  - For `spectral` (CLI / TUI mode): live ONLY on the machine, in pi's own
+    `~/.pi/agent/auth.json`. Never read or transmitted by Spectral.
+  - For `spectral serve` (relay mode): live on the **backend**, not the
+    machine. The local machine holds only its machine JWT; provider keys
+    are managed centrally and scoped to the team's `BaseModel` whitelist.
+- **Code, messages, file contents, generated artifacts** live ONLY on the
+  machine, in `~/.spectral/sessions.db` and the working directory you point
+  `spectral serve` at.
+- **The backend stores**: machine identity (id, display name, hostname,
+  last-seen timestamps), the relay JWT issued at registration, and team
+  membership. For `spectral serve`, it also holds the centralized provider
+  API keys used to fulfil inference requests on behalf of authorized
+  machines.
+- **The backend does not store**: prompts, responses, tool calls, files,
+  artifacts, or any other message-channel content.
+
+## License
+
+MIT — see [LICENSE](./LICENSE).
+
+## Links
+
+- Website: <https://aexol.com>
+- Source is currently hosted in an internal Aexol repository; public mirror TBD.
+- Issues: please file them with your Aexol contact (a public issue tracker
+  is not yet available).

package/dist/cli.js

@@ -0,0 +1,206 @@
+#!/usr/bin/env node
+/**
+ * @aexol/spectral — Coding agent that never sleeps
+ *
+ * Thin branding wrapper around @mariozechner/pi-coding-agent (pi).
+ *
+ * Delegation strategy: SUBPROCESS spawn of pi's bin.
+ *
+ * Why subprocess and not in-process import?
+ *  - pi's CLI entry has top-level side effects (TUI bootstrap, signal handlers,
+ *    raw stdin mode). Running it in-process means our wrapper process owns those,
+ *    and any future pre-processing we add (skills, system prompts) becomes
+ *    entangled with pi's lifecycle.
+ *  - A child process gives us clean exit-code propagation, clean SIGINT
+ *    forwarding, and a stable boundary for future iterations to inject things
+ *    like extra args, env vars, or post-run hooks without monkey-patching pi.
+ *  - stdio: "inherit" gives pi direct TTY access, so its TUI renders correctly
+ *    and raw stdin works as expected.
+ *
+ * Subcommand routing:
+ *  - `spectral login`  → interactive auth flow (writes ~/.spectral/config.json)
+ *  - `spectral logout` → deletes ~/.spectral/config.json
+ *  - `spectral --version` / `--help` → branded short-circuits, no auth needed.
+ *  - anything else → pre-flight: require ~/.spectral/config.json, then spawn pi
+ *    with the bundled Aexol MCP extension auto-loaded.
+ */
+import { spawn } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { constants as osConstants } from "node:os";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { requireLogin } from "./preflight.js";
+const __dirname = dirname(fileURLToPath(import.meta.url));
+// ---- Read our own version ----------------------------------------------------
+const pkgPath = resolve(__dirname, "..", "package.json");
+const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+const VERSION = pkg.version;
+const TAGLINE = "Coding agent that never sleeps";
+// ---- Resolve pi's bin --------------------------------------------------------
+// pi exports `.` as ESM only and does not export `./package.json`, so
+// require.resolve(...) is unreliable across Node versions. Instead we walk
+// upward from this file's location looking for a `node_modules/<pi>/package.json`.
+function resolvePiBin() {
+    const piPkgRel = "node_modules/@mariozechner/pi-coding-agent/package.json";
+    let dir = __dirname;
+    let piPkgJsonPath;
+    for (let i = 0; i < 20; i++) {
+        const candidate = resolve(dir, piPkgRel);
+        try {
+            readFileSync(candidate, "utf8");
+            piPkgJsonPath = candidate;
+            break;
+        }
+        catch {
+            /* keep walking */
+        }
+        const parent = dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    if (!piPkgJsonPath) {
+        throw new Error("Unable to locate @mariozechner/pi-coding-agent in any ancestor node_modules.");
+    }
+    const piPkg = JSON.parse(readFileSync(piPkgJsonPath, "utf8"));
+    let binRel;
+    if (typeof piPkg.bin === "string") {
+        binRel = piPkg.bin;
+    }
+    else if (piPkg.bin && typeof piPkg.bin === "object") {
+        binRel = piPkg.bin.pi ?? Object.values(piPkg.bin)[0];
+    }
+    if (!binRel) {
+        throw new Error("Unable to locate pi bin in @mariozechner/pi-coding-agent package.json");
+    }
+    return resolve(dirname(piPkgJsonPath), binRel);
+}
+/** Absolute path to the bundled aexol-mcp extension, sitting next to this file in dist/. */
+function resolveAexolExtensionPath() {
+    return resolve(__dirname, "extensions", "aexol-mcp.js");
+}
+// ---- Branded helpers ---------------------------------------------------------
+function printVersion() {
+    process.stdout.write(`spectral ${VERSION} — ${TAGLINE}\n`);
+}
+function printHeader() {
+    process.stdout.write([
+        `spectral ${VERSION}`,
+        TAGLINE,
+        "",
+        "Subcommands:",
+        "  spectral login    Authenticate with the Aexol MCP backend",
+        "  spectral logout   Remove stored Aexol credentials",
+        "  spectral serve    Connect this machine to the Aexol relay backend",
+        "  spectral bind     Link this directory to an Aexol Studio project",
+        "  spectral unbind   Remove the Aexol Studio project binding",
+        "",
+        "Powered by pi (@mariozechner/pi-coding-agent).",
+        "All other flags are forwarded to pi. Run: spectral <pi-args>",
+        "",
+    ].join("\n"));
+}
+// ---- Delegate to pi ----------------------------------------------------------
+function delegateToPi(args) {
+    const piBin = resolvePiBin();
+    const child = spawn(process.execPath, [piBin, ...args], {
+        stdio: "inherit",
+        env: process.env,
+    });
+    // Forward common termination signals to pi so its TUI can clean up.
+    const signals = ["SIGINT", "SIGTERM", "SIGHUP", "SIGQUIT"];
+    for (const sig of signals) {
+        process.on(sig, () => {
+            if (!child.killed) {
+                try {
+                    child.kill(sig);
+                }
+                catch {
+                    /* ignore */
+                }
+            }
+        });
+    }
+    child.on("exit", (code, signal) => {
+        if (signal) {
+            const sigNum = osConstants.signals[signal] ?? 0;
+            process.exit(128 + sigNum);
+        }
+        process.exit(code ?? 0);
+    });
+    child.on("error", (err) => {
+        process.stderr.write(`spectral: failed to launch pi: ${err.message}\n`);
+        process.exit(1);
+    });
+    // spawn returns; keep the type system happy.
+    // We never actually reach here because of the exit handlers above, but
+    // TypeScript needs a `never` terminator.
+    return undefined;
+}
+// ---- Main --------------------------------------------------------------------
+async function main() {
+    const args = process.argv.slice(2);
+    const first = args[0];
+    // Branded short-circuits: never require login.
+    if (first === "--version" || first === "-v") {
+        printVersion();
+        process.exit(0);
+    }
+    if (first === "--help" || first === "-h") {
+        printHeader();
+        // Spawn pi to append its own help, then bail. delegateToPi is
+        // annotated `: never` because its child.on("exit") handler calls
+        // process.exit, but the function itself returns synchronously after
+        // spawn — so we must not fall through to the pre-flight check below.
+        delegateToPi(args);
+        return;
+    }
+    // Subcommands. Dynamic import keeps the cold-start path light when users
+    // are just running pi.
+    if (first === "login") {
+        const { runLogin } = await import("./commands/login.js");
+        await runLogin();
+        process.exit(0);
+    }
+    if (first === "logout") {
+        const { runLogout } = await import("./commands/logout.js");
+        await runLogout();
+        process.exit(0);
+    }
+    if (first === "serve") {
+        const { runServeCli } = await import("./commands/serve.js");
+        // runServeCli does the pre-flight login check itself and keeps the
+        // process alive on the bound socket; signal handlers it installs handle
+        // graceful shutdown. We intentionally don't process.exit here.
+        await runServeCli(args.slice(1));
+        return;
+    }
+    if (first === "bind") {
+        const { runBind } = await import("./commands/bind.js");
+        await runBind(args.slice(1));
+        process.exit(0);
+    }
+    if (first === "unbind") {
+        const { runUnbind } = await import("./commands/unbind.js");
+        await runUnbind();
+        process.exit(0);
+    }
+    // Pre-flight: every other invocation requires authenticated state. We do NOT
+    // auto-launch the login flow — that would fight pi's stdio inheritance and
+    // hide auth state changes from the user.
+    await requireLogin();
+    // Resolve and inject the Aexol MCP extension. Sanity-check existence so we
+    // fail with a clear message if someone publishes a broken bundle.
+    const extPath = resolveAexolExtensionPath();
+    if (!existsSync(extPath)) {
+        process.stderr.write(`spectral: bundled Aexol MCP extension not found at ${extPath}. This is a packaging bug.\n`);
+        process.exit(1);
+    }
+    const finalArgs = ["--extension", extPath, ...args];
+    delegateToPi(finalArgs);
+}
+main().catch((err) => {
+    const msg = err instanceof Error ? err.message : String(err);
+    process.stderr.write(`spectral: ${msg}\n`);
+    process.exit(1);
+});

package/dist/commands/bind.js

@@ -0,0 +1,96 @@
+/**
+ * `spectral bind` — link the current directory to an Aexol Studio project.
+ *
+ * Usage:
+ *   spectral bind <project-id> [--team-id <id>] [--name <name>] [--force]
+ *
+ * Writes `.aexol/aexol.jsonc` so that `spectral` knows which Studio project
+ * this repository belongs to. By default it refuses to overwrite an existing
+ * binding; pass `--force` to rebind.
+ */
+import pc from "picocolors";
+import { readStudioBinding, writeStudioBinding, } from "../studio-binding.js";
+export async function runBind(args) {
+    // ---- Parse args ----------------------------------------------------------
+    let projectId = "";
+    let teamId;
+    let name;
+    let force = false;
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i];
+        if (a === "--team-id") {
+            const next = args[i + 1];
+            if (!next) {
+                process.stderr.write(pc.red("--team-id requires a value\n"));
+                process.exit(1);
+            }
+            teamId = next;
+            i++;
+        }
+        else if (a.startsWith("--team-id=")) {
+            teamId = a.slice("--team-id=".length);
+        }
+        else if (a === "--name") {
+            const next = args[i + 1];
+            if (!next) {
+                process.stderr.write(pc.red("--name requires a value\n"));
+                process.exit(1);
+            }
+            name = next;
+            i++;
+        }
+        else if (a.startsWith("--name=")) {
+            name = a.slice("--name=".length);
+        }
+        else if (a === "--force") {
+            force = true;
+        }
+        else if (a.startsWith("-")) {
+            process.stderr.write(pc.red(`Unknown flag: ${a}\n`));
+            process.exit(1);
+        }
+        else if (!projectId) {
+            projectId = a;
+        }
+        else {
+            process.stderr.write(pc.red(`Unexpected argument: ${a}\n`));
+            process.exit(1);
+        }
+    }
+    if (!projectId) {
+        process.stderr.write(pc.red("Usage: spectral bind <project-id> [--team-id <id>] [--name <name>] [--force]\n"));
+        process.exit(1);
+    }
+    // ---- Check existing ------------------------------------------------------
+    let existing = null;
+    try {
+        existing = await readStudioBinding();
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        process.stderr.write(pc.red(`Failed to read existing binding: ${msg}\n`));
+        process.exit(1);
+    }
+    if (existing && !force) {
+        const existingName = existing.name ?? "(unnamed)";
+        process.stderr.write(pc.yellow(`Already bound to project ${existingName} (${existing.projectId}). Use --force to rebind.\n`));
+        process.exit(0);
+    }
+    // ---- Write ---------------------------------------------------------------
+    const binding = {
+        $schema: "https://aexol.ai/schemas/studio-binding.json",
+        projectId,
+        ...(teamId ? { teamId } : {}),
+        ...(name ? { name } : {}),
+    };
+    try {
+        await writeStudioBinding(binding);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        process.stderr.write(pc.red(`Failed to write binding: ${msg}\n`));
+        process.exit(1);
+    }
+    const displayName = name ?? projectId;
+    process.stdout.write(pc.green(`✓ Bound to Studio project: ${displayName} (${projectId})\n`));
+}