@modelworks/quack 0.0.0-stage → 0.2.8

package/dist/project.js

@@ -0,0 +1,147 @@
+/**
+ * Project-level `.quack/` directory management: init, config/state read/write.
+ *
+ * @module
+ */
+import fs from "node:fs";
+import path from "node:path";
+/** The `.quack/` directory name, placed at the project root. */
+export const QUACK_DIR = ".quack";
+/** Path to the `.quack/` directory in the current working directory. */
+export function quackDir() {
+    return path.join(process.cwd(), QUACK_DIR);
+}
+/** Path to `.quack/config.json`. */
+export function configPath() {
+    return path.join(quackDir(), "config.json");
+}
+/** Path to `.quack/state.json`. */
+export function statePath() {
+    return path.join(quackDir(), "state.json");
+}
+/** Does a `.quack/` directory exist in the current project? */
+export function isQuackProject() {
+    return fs.existsSync(quackDir()) && fs.existsSync(configPath());
+}
+/** Assert the current directory is a quack project; throw a friendly error if not. */
+export function requireQuackProject() {
+    if (!isQuackProject()) {
+        throw new Error("Not a quack project. Run `quack init` first.");
+    }
+}
+/** Empty config template. `default_agent` defaults to `opencode`. */
+function emptyConfig() {
+    return { version: 1, default_agent: "opencode", circuits: [] };
+}
+/** Empty state template. */
+function emptyState() {
+    return { circuits: {} };
+}
+/** `.gitignore` contents for `.quack/` — ignores `state.json` (runs/ is committed). */
+const GITIGNORE_CONTENTS = "state.json\ndebug.log\n";
+/**
+ * `quack init` — create the `.quack/` directory with empty config,
+ * state, and `.gitignore`.
+ *
+ * Errors if `.quack/` already exists, unless `force` is `true`.
+ */
+export function initProject(force = false) {
+    const dir = quackDir();
+    if (fs.existsSync(dir)) {
+        if (!force) {
+            throw new Error("Already a quack project. Use `--force` to overwrite.");
+        }
+        fs.rmSync(dir, { recursive: true });
+    }
+    fs.mkdirSync(dir, { recursive: true });
+    fs.mkdirSync(path.join(dir, "runs"), { recursive: true });
+    fs.writeFileSync(configPath(), JSON.stringify(emptyConfig(), null, 2) + "\n");
+    fs.writeFileSync(statePath(), JSON.stringify(emptyState(), null, 2) + "\n");
+    fs.writeFileSync(path.join(dir, ".gitignore"), GITIGNORE_CONTENTS);
+    console.log(`Initialized quack project in ${dir}`);
+}
+// ---------------------------------------------------------------------------
+// Config read/write (`.quack/config.json` — committable)
+// ---------------------------------------------------------------------------
+/** Read the project config. Throws if `.quack/` doesn't exist. */
+export function readConfig() {
+    requireQuackProject();
+    const raw = fs.readFileSync(configPath(), "utf8");
+    return JSON.parse(raw);
+}
+/** Write the project config (atomic-ish: write then sync). */
+export function writeConfig(config) {
+    requireQuackProject();
+    fs.writeFileSync(configPath(), JSON.stringify(config, null, 2) + "\n");
+}
+// ---------------------------------------------------------------------------
+// State read/write (`.quack/state.json` — gitignored, per-user)
+// ---------------------------------------------------------------------------
+/**
+ * Read the project state.
+ *
+ * Returns an empty state if `.quack/` doesn't exist or `state.json`
+ * is missing (e.g. a freshly cloned repo where only `config.json`
+ * was committed). The caller is responsible for auto-syncing state
+ * from config when needed.
+ */
+export function readState() {
+    if (!isQuackProject()) {
+        return emptyState();
+    }
+    try {
+        const raw = fs.readFileSync(statePath(), "utf8");
+        return JSON.parse(raw);
+    }
+    catch {
+        return emptyState();
+    }
+}
+/** Write the project state. */
+export function writeState(state) {
+    requireQuackProject();
+    fs.writeFileSync(statePath(), JSON.stringify(state, null, 2) + "\n");
+}
+// ---------------------------------------------------------------------------
+// Convenience operations
+// ---------------------------------------------------------------------------
+/** Add a circuit entry to the config (no-op if already present). Returns `true` if added. */
+export function addCircuitToConfig(entry) {
+    const config = readConfig();
+    if (config.circuits.some((c) => c.circuit_uid === entry.circuit_uid)) {
+        return false;
+    }
+    config.circuits.push(entry);
+    writeConfig(config);
+    return true;
+}
+/** Remove a circuit from config by `circuit_uid`. Returns `true` if removed. */
+export function removeCircuitFromConfig(circuitUid) {
+    const config = readConfig();
+    const before = config.circuits.length;
+    config.circuits = config.circuits.filter((c) => c.circuit_uid !== circuitUid);
+    if (config.circuits.length === before)
+        return false;
+    writeConfig(config);
+    return true;
+}
+/** Upsert a circuit's state entry (keyed by `circuit_uid`). */
+export function upsertCircuitState(entry) {
+    const state = readState();
+    state.circuits[entry.circuit_uid] = entry;
+    writeState(state);
+}
+/** Remove a circuit's state entry. Returns `true` if removed. */
+export function removeCircuitState(circuitUid) {
+    const state = readState();
+    if (!(circuitUid in state.circuits))
+        return false;
+    delete state.circuits[circuitUid];
+    writeState(state);
+    return true;
+}
+/** Get a circuit's state entry, or `null` if not present. */
+export function getCircuitState(circuitUid) {
+    const state = readState();
+    return state.circuits[circuitUid] ?? null;
+}

package/dist/proxy.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Local HTTP reverse proxy.
+ *
+ * Forwards every request to the same path on `apiBase`, injecting
+ * `Authorization: Bearer <token>` and streaming the response body.
+ * On 401, refreshes the access token and retries once.
+ *
+ * @module
+ */
+import type { ProxyHandle, ProxyOptions } from "./types.js";
+/**
+ * Start a local HTTP reverse proxy on a random port (`127.0.0.1`).
+ *
+ * Resolves with a handle containing the assigned port and a `close()`
+ * method. The proxy lives for as long as quack runs; `launch.ts` closes
+ * it when the spawned opencode process exits.
+ */
+export declare function startProxy(opts: ProxyOptions): Promise<ProxyHandle>;

package/dist/proxy.js

@@ -0,0 +1,203 @@
+/**
+ * Local HTTP reverse proxy.
+ *
+ * Forwards every request to the same path on `apiBase`, injecting
+ * `Authorization: Bearer <token>` and streaming the response body.
+ * On 401, refreshes the access token and retries once.
+ *
+ * @module
+ */
+import http from "node:http";
+/**
+ * Start a local HTTP reverse proxy on a random port (`127.0.0.1`).
+ *
+ * Resolves with a handle containing the assigned port and a `close()`
+ * method. The proxy lives for as long as quack runs; `launch.ts` closes
+ * it when the spawned opencode process exits.
+ */
+export function startProxy(opts) {
+    return new Promise((resolve, reject) => {
+        const server = http.createServer(async (req, res) => {
+            const startTime = Date.now();
+            // Flush debug lines immediately so we see them even if the request hangs.
+            const debug = (line) => {
+                if (opts.onDebug)
+                    opts.onDebug(line);
+            };
+            // TCP-level connection log — fires for EVERY request, even before
+            // HTTP parsing. This tells us if the request reached the proxy at all.
+            if (opts.onDebug) {
+                opts.onDebug(`[tcp] connection: ${req.method} ${req.url} from ${req.socket.remoteAddress}:${req.socket.remotePort}`);
+            }
+            try {
+                const targetUrl = new URL(req.url ?? "/", opts.apiBase);
+                // Debug: log incoming request immediately (before body reading).
+                debug(`=== ${new Date().toISOString()} ===`);
+                debug(`${req.method} ${req.url}`);
+                debug(`→ forwarded to ${targetUrl.href}`);
+                debug(`content-length: ${req.headers["content-length"] ?? "(none)"}`);
+                debug(`transfer-encoding: ${req.headers["transfer-encoding"] ?? "(none)"}`);
+                // Read the full request body before forwarding (needed for 401 retry).
+                const chunks = [];
+                for await (const chunk of req)
+                    chunks.push(chunk);
+                const body = chunks.length > 0 ? Buffer.concat(chunks) : null;
+                debug(`body read: ${body ? body.length + " bytes" : "(empty)"}`);
+                // Build forwarded headers — strip client auth + host, inject our own.
+                const headers = {};
+                for (const [key, value] of Object.entries(req.headers)) {
+                    const lower = key.toLowerCase();
+                    if (lower === "authorization" || lower === "host")
+                        continue;
+                    headers[key] = Array.isArray(value) ? value.join(", ") : value ?? "";
+                }
+                headers.authorization = `Bearer ${opts.getAccessToken()}`;
+                headers.host = targetUrl.host;
+                if (opts.onDebug) {
+                    debug(`--- request headers (incoming) ---`);
+                    for (const [k, v] of Object.entries(req.headers)) {
+                        const val = Array.isArray(v) ? v.join(", ") : v ?? "";
+                        // Mask the real token in the debug log.
+                        const masked = k.toLowerCase() === "authorization"
+                            ? `Bearer ${val.slice(7, 12)}...`
+                            : val;
+                        debug(`  ${k}: ${masked}`);
+                    }
+                    debug(`--- request body ---`);
+                    debug(body ? body.toString("utf8").slice(0, 2000) : "(empty)");
+                }
+                // Forward request.
+                let upstream = await fetch(targetUrl, {
+                    method: req.method,
+                    headers,
+                    body: body ?? undefined,
+                });
+                // Token refresh on 401 — retry once.
+                if (upstream.status === 401) {
+                    debug(`--- 401 received, refreshing token and retrying ---`);
+                    const refreshed = await opts.refreshToken();
+                    if (refreshed) {
+                        headers.authorization = `Bearer ${opts.getAccessToken()}`;
+                        upstream = await fetch(targetUrl, {
+                            method: req.method,
+                            headers,
+                            body: body ?? undefined,
+                        });
+                    }
+                }
+                // Forward response status + headers.
+                res.statusCode = upstream.status;
+                for (const [key, value] of upstream.headers) {
+                    res.setHeader(key, value);
+                }
+                // Capture the circuit run UID for history saving.
+                const runUid = upstream.headers.get("x-circuit-run-uid");
+                const onRunComplete = opts.onRunComplete;
+                if (opts.onDebug) {
+                    const elapsed = Date.now() - startTime;
+                    debug(`--- response ${upstream.status} (${elapsed}ms) ---`);
+                    debug(`--- response headers ---`);
+                    for (const [k, v] of upstream.headers) {
+                        debug(`  ${k}: ${v}`);
+                    }
+                }
+                // Stream the response body (SSE, NDJSON, JSON).
+                // Cast: `@types/node`'s `Readable.fromWeb` and the global
+                // `ReadableStream` from `fetch` have structurally incompatible
+                // `pipeThrough` types. Runtime is correct.
+                if (upstream.body) {
+                    if (opts.onDebug) {
+                        // Capture streamed body for debug logging.
+                        let bodyBytes = 0;
+                        const decoder = new TextDecoder();
+                        let debugBody = "";
+                        const reader = upstream.body.getReader();
+                        const pump = async () => {
+                            try {
+                                for (;;) {
+                                    const { done, value } = await reader.read();
+                                    if (done)
+                                        break;
+                                    bodyBytes += value.length;
+                                    if (debugBody.length < 2000) {
+                                        debugBody += decoder.decode(value, { stream: true });
+                                    }
+                                    res.write(value);
+                                }
+                                res.end();
+                            }
+                            catch (err) {
+                                debug(`--- stream error: ${err.message} ---`);
+                                if (!res.writableEnded)
+                                    res.end();
+                            }
+                            debug(`--- response body (${bodyBytes} bytes) ---`);
+                            debug(debugBody.slice(0, 2000) + (bodyBytes > 2000 ? "..." : ""));
+                            const totalMs = Date.now() - startTime;
+                            debug(`=== END ${req.method} ${req.url} ${upstream.status} (${totalMs}ms) ===\n`);
+                            // Fire-and-forget: save run history after stream completes.
+                            if (runUid && onRunComplete)
+                                onRunComplete(runUid);
+                        };
+                        pump();
+                    }
+                    else {
+                        const reader = upstream.body.getReader();
+                        const pumpPlain = async () => {
+                            try {
+                                for (;;) {
+                                    const { done, value } = await reader.read();
+                                    if (done)
+                                        break;
+                                    res.write(value);
+                                }
+                                res.end();
+                            }
+                            catch {
+                                if (!res.writableEnded)
+                                    res.end();
+                            }
+                            // Fire-and-forget: save run history after stream completes.
+                            if (runUid && onRunComplete)
+                                onRunComplete(runUid);
+                        };
+                        pumpPlain();
+                    }
+                }
+                else {
+                    res.end();
+                    if (opts.onDebug) {
+                        debug(`--- response body (empty) ---`);
+                        const totalMs = Date.now() - startTime;
+                        debug(`=== END ${req.method} ${req.url} ${upstream.status} (${totalMs}ms) ===\n`);
+                    }
+                    // Fire-and-forget: save run history even for empty-body responses.
+                    if (runUid && onRunComplete)
+                        onRunComplete(runUid);
+                }
+                opts.onLog?.(req.method ?? "?", targetUrl.pathname, upstream.status);
+            }
+            catch (err) {
+                debug(`--- proxy error: ${err.message} ---`);
+                if (!res.headersSent) {
+                    res.statusCode = 502;
+                    res.setHeader("content-type", "application/json");
+                    res.end(JSON.stringify({
+                        error: "proxy_error",
+                        message: err.message,
+                    }));
+                }
+            }
+        });
+        server.listen(0, "127.0.0.1", () => {
+            const addr = server.address();
+            if (!addr || typeof addr === "object" && !("port" in addr)) {
+                reject(new Error("Could not bind proxy port"));
+                return;
+            }
+            const port = addr.port;
+            resolve({ port, close: () => server.close() });
+        });
+        server.on("error", reject);
+    });
+}

package/dist/types.d.ts

@@ -0,0 +1,239 @@
+/**
+ * Shared types for @modelworks/quack.
+ *
+ * @module
+ */
+/**
+ * Stored OAuth credentials for the authenticated user.
+ *
+ * Persisted at `~/.config/quack/credentials.json` (chmod 0600).
+ * The `api_base` field is stored here so token refresh hits the
+ * right server (supports `QUACK_API_BASE` / `--api-base` overrides).
+ */
+export interface Credentials {
+    access_token: string;
+    refresh_token: string;
+    /** Unix timestamp (seconds) when the access token expires. */
+    expires_at: number;
+    token_type: string;
+    user_uid: string;
+    /** Base URL of the ModelWorks API, e.g. `https://modelworks.ai`. */
+    api_base: string;
+}
+/**
+ * Dynamic Client Registration record.
+ *
+ * Persisted at `~/.config/quack/client.json`. Created once on first
+ * `quack login`, reused on subsequent logins.
+ */
+export interface ClientRegistration {
+    client_id: string;
+}
+/**
+ * One entry in `.quack/config.json`'s `circuits` array.
+ *
+ * Committable and shareable across a team — contains only public
+ * metadata, no user-specific state.
+ */
+export interface CircuitConfigEntry {
+    url: string;
+    circuit_uid: string;
+    name: string;
+    /** ISO 8601 timestamp when the circuit was added. */
+    added_at: string;
+}
+/**
+ * One entry in `.quack/state.json`'s `circuits` map, keyed by `circuit_uid`.
+ *
+ * Gitignored, per-user — a snapshot from `quack add` / `quack refresh`
+ * / `quack opencode` auto-sync. Holds everything `quack opencode`
+ * needs to build the opencode config without re-fetching.
+ */
+export interface CircuitStateEntry {
+    circuit_uid: string;
+    /** The RUNNING version resolved at add/refresh time. */
+    version_uid: string;
+    circuit_name: string;
+    /** Owner's username (e.g. `alice`), for display as `<username>/<circuit_name>`. */
+    owner_username: string;
+    /**
+     * Adapter types the circuit supports, e.g.
+     * `["OPEN_AI_SSE", "MODELWORKS_HTTP", "MCP"]`.
+     *
+     * Discovered from the circuit version's `json_blob` `adapters`
+     * array when visible (public/owner), or from listing existing
+     * adaptors when `json_blob` is hidden (protected, non-owner).
+     */
+    adapters: string[];
+    /**
+     * UID (`ca-xxx`) of the temporal OpenAI SSE adaptor quack created
+     * for this circuit, or `null` if the circuit isn't SSE-compatible.
+     */
+    sse_adaptor_uid: string | null;
+    /**
+     * Map of adapter type → adaptor UID (`ca-xxx`) for each temporal
+     * adaptor quack created. Currently only `OPEN_AI_SSE` is created
+     * by quack, but existing adaptors discovered via the list endpoint
+     * are also stored here.
+     */
+    adaptor_uids: Record<string, string>;
+    /** ISO 8601 timestamp of the last resolution. */
+    resolved_at: string;
+}
+/**
+ * `.quack/config.json` — the project-level, committable config.
+ */
+export interface QuackConfig {
+    version: number;
+    /**
+     * Agent to launch when the user runs bare `quack` (no args).
+     * Optional — if absent, the fallback chain (last_agent →
+     * interactive pick → error) resolves the agent.
+     */
+    default_agent?: string;
+    /**
+     * Circuit UID (`c-xxx`) to use as the default model in OpenCode.
+     * Team-shared — committed to `config.json`. Set via `quack circuit use`
+     * or auto-set to the first SSE-compatible circuit on `quack circuit add`.
+     * At launch, resolved to an OpenCode model ID and injected as `model`.
+     */
+    default_circuit?: string;
+    circuits: CircuitConfigEntry[];
+}
+/**
+ * `.quack/state.json` — the per-user, gitignored cached state.
+ */
+export interface QuackState {
+    circuits: Record<string, CircuitStateEntry>;
+    /**
+     * The last agent successfully launched by bare `quack`.
+     * Per-user convenience — used as a fallback when
+     * `default_agent` is not set in config.json.
+     */
+    last_agent?: string;
+}
+/**
+ * Parsed circuit URL or bare UID.
+ */
+export interface ParsedCircuitRef {
+    circuit_uid: string;
+    version_uid: string | null;
+}
+/**
+ * A circuit version record as returned by the ModelWorks API
+ * (`GET /circuits/<uid>/versions` or `GET /circuit-versions/<uid>`).
+ *
+ * Only the fields quack reads are typed here. `json_blob` is optional
+ * because it's hidden for protected circuits when the caller is not
+ * the owner (see `circuit_version.rs` visibility rules).
+ */
+export interface CircuitVersionPublic {
+    uid: string;
+    circuit_uid: string;
+    state: string;
+    json_blob: string | null;
+    updated_at: string;
+}
+/**
+ * A circuit record as returned by `GET /circuits/<uid>`.
+ */
+export interface CircuitPublic {
+    uid: string;
+    name: string;
+    user_uid: string;
+    is_private: boolean;
+    is_protected: boolean;
+}
+/**
+ * A circuit adaptor record as returned by
+ * `GET /circuit-adaptors/by-circuit-version/<version_uid>`.
+ */
+export interface CircuitAdaptorPublic {
+    uid: string;
+    circuit_version_uid: string;
+    adapter_type: string;
+    user_uid: string | null;
+    user_token_uid: string | null;
+}
+/**
+ * A circuit run record stored locally at `.quack/runs/cr-xxx.json`.
+ *
+ * Committed to the repo (team-shared). Contains only public metadata —
+ * no request body, no response body, nothing sensitive.
+ */
+export interface RunRecord {
+    run_uid: string;
+    circuit_uid: string;
+    circuit_name: string;
+    owner_username: string;
+    caller_username: string;
+    version_uid: string;
+    status: string;
+    created_at: string;
+    completed_at: string;
+    duration_ms: number | null;
+    cost_credits: number | null;
+    input_tokens: number | null;
+    output_tokens: number | null;
+}
+/**
+ * Handle to a running local proxy.
+ */
+export interface ProxyHandle {
+    port: number;
+    close: () => void;
+}
+/**
+ * Options for {@link startProxy}.
+ */
+export interface ProxyOptions {
+    /** Upstream API base URL, e.g. `https://modelworks.ai`. */
+    apiBase: string;
+    /** Returns the current access token (refreshed if needed before calling). */
+    getAccessToken: () => string;
+    /** Refreshes the access token. Returns `true` on success. */
+    refreshToken: () => Promise<boolean>;
+    /** Optional request logger for `--verbose`. */
+    onLog?: (method: string, path: string, status: number) => void;
+    /** Optional debug logger — full request/response details to a string sink. */
+    onDebug?: (entry: string) => void;
+    /**
+     * Called after a response stream completes, if the response included
+     * an `X-Circuit-Run-Uid` header. Fire-and-forget — the proxy does not
+     * await this. Used to fetch and save the run record locally.
+     */
+    onRunComplete?: (runUid: string) => void;
+}
+/**
+ * The OpenCode config that quack injects via `OPENCODE_CONFIG_CONTENT`.
+ *
+ * Only the two top-level keys quack touches are typed here.
+ */
+export interface OpenCodeConfig {
+    $schema?: string;
+    /** Default model ID, e.g. `circuit-wandb-glm-52/wandb-glm-52`. */
+    model?: string;
+    mcp?: {
+        servers: Record<string, OpenCodeMcpServer>;
+    };
+    providers?: Record<string, OpenCodeProvider>;
+}
+export interface OpenCodeMcpServer {
+    type: "remote";
+    url: string;
+    oauth: false;
+    protocol: "auto" | "2026-07-28" | "legacy";
+    headers?: Record<string, string>;
+}
+export interface OpenCodeProvider {
+    name: string;
+    package: string;
+    env?: string[];
+    settings: {
+        baseURL: string;
+        apiKey?: string;
+    };
+    models: Record<string, {
+        name: string;
+    }>;
+}

package/dist/types.js

@@ -0,0 +1,6 @@
+/**
+ * Shared types for @modelworks/quack.
+ *
+ * @module
+ */
+export {};

package/package.json

@@ -1,6 +1,52 @@
 {
   "name": "@modelworks/quack",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.8",
+  "description": "Launch AI coding agents (OpenCode, and more) with ModelWorks circuits as model providers. OAuth login, local proxy with auth injection, run history, and git-like project config.",
+  "type": "module",
+  "bin": {
+    "quack": "dist/bin.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "prebuild": "node scripts/build-info.mjs",
+    "build": "tsc",
+    "prepublishOnly": "node scripts/build-info.mjs && tsc",
+    "dev": "tsc --watch",
+    "test": "tsc -p tsconfig.test.json && node --test dist-test/test/*.test.js",
+    "test:run": "node --test dist-test/test/*.test.js"
+  },
+  "devDependencies": {
+    "@types/node": "^22.20.5",
+    "typescript": "^5.5.0"
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT",
+  "keywords": [
+    "modelworks",
+    "opencode",
+    "ai",
+    "circuit",
+    "proxy",
+    "mcp",
+    "cli",
+    "launcher"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/modelworks-ai/quack.git"
+  },
+  "homepage": "https://github.com/modelworks-ai/quack",
+  "bugs": {
+    "url": "https://github.com/modelworks-ai/quack/issues"
+  },
+  "dependencies": {
+    "commander": "^15.0.0"
+  }
+}