@modelworks/quack 0.0.0-stage → 0.2.8

package/dist/history.js

@@ -0,0 +1,154 @@
+/**
+ * Run history — save and list circuit run records locally.
+ *
+ * After each circuit request through the proxy, the run UID (from the
+ * `X-Circuit-Run-Uid` response header) is used to fetch the full run
+ * record from the API and save it as a JSON file under `.quack/runs/`.
+ * These files are committed to the repo (team-shared).
+ *
+ * @module
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { quackDir } from "./project.js";
+/** Path to `.quack/runs/` directory. */
+export function runsDir() {
+    return path.join(quackDir(), "runs");
+}
+/** Path to a single run file. */
+export function runFilePath(runUid) {
+    return path.join(runsDir(), `${runUid}.json`);
+}
+/**
+ * Fetch a circuit run record from the API and map it to a `RunRecord`.
+ *
+ * Retries up to 3 times with a 500ms delay if the run hasn't reached a
+ * terminal state (COMPLETED/EXCEPTION/FAILED) — the engine might not
+ * have finalized the DB record the instant the stream ends.
+ */
+export async function fetchRunFromApi(runUid, credentials, stateCircuits, callerUsername) {
+    const base = credentials.api_base;
+    const token = credentials.access_token;
+    for (let attempt = 0; attempt < 3; attempt++) {
+        try {
+            const res = await fetch(`${base}/api/circuit-runs/${runUid}`, {
+                headers: { Authorization: `Bearer ${token}` },
+            });
+            if (!res.ok) {
+                if (attempt < 2) {
+                    await sleep(500);
+                    continue;
+                }
+                return null;
+            }
+            const body = (await res.json());
+            const run = body.payload;
+            if (!run)
+                return null;
+            const state = run.state ?? "UNKNOWN";
+            const terminal = ["COMPLETED", "Completed", "EXCEPTION", "FAILED"];
+            if (!terminal.includes(state) && attempt < 2) {
+                await sleep(500);
+                continue;
+            }
+            const circuitUid = run.circuit_uid ?? "";
+            const versionUid = run.circuit_version_uid ?? "";
+            const createdAt = run.created_at ?? "";
+            const endedAt = run.ended_at ?? "";
+            // Parse result_blob for cost/tokens/duration.
+            const resultBlob = run.result_blob;
+            let costCredits = null;
+            let inputTokens = null;
+            let outputTokens = null;
+            let durationMs = null;
+            if (resultBlob) {
+                const billingEntries = resultBlob.billing_entries;
+                if (billingEntries && billingEntries.length > 0) {
+                    costCredits = billingEntries[0].cost ?? null;
+                    inputTokens = billingEntries[0].total_input_tokens ?? null;
+                    outputTokens = billingEntries[0].total_output_tokens ?? null;
+                }
+                const perfReports = resultBlob.performance_reports;
+                if (perfReports) {
+                    // Take the first performance report's time_taken.
+                    const firstKey = Object.keys(perfReports)[0];
+                    if (firstKey) {
+                        durationMs = perfReports[firstKey].time_taken ?? null;
+                    }
+                }
+            }
+            // Resolve circuit_name and owner_username from state.
+            const stateEntry = stateCircuits[circuitUid];
+            const circuitName = stateEntry?.circuit_name ?? circuitUid;
+            const ownerUsername = stateEntry?.owner_username ?? "";
+            return {
+                run_uid: runUid,
+                circuit_uid: circuitUid,
+                circuit_name: circuitName,
+                owner_username: ownerUsername,
+                caller_username: callerUsername,
+                version_uid: versionUid,
+                status: state,
+                created_at: createdAt,
+                completed_at: endedAt,
+                duration_ms: durationMs,
+                cost_credits: costCredits,
+                input_tokens: inputTokens,
+                output_tokens: outputTokens,
+            };
+        }
+        catch {
+            if (attempt < 2) {
+                await sleep(500);
+                continue;
+            }
+            return null;
+        }
+    }
+    return null;
+}
+/** Save a run record to `.quack/runs/cr-xxx.json`. */
+export function saveRunRecord(record) {
+    const dir = runsDir();
+    fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(runFilePath(record.run_uid), JSON.stringify(record, null, 2) + "\n");
+}
+/**
+ * List all run records, sorted by `created_at` descending.
+ *
+ * Reads every `*.json` file in `.quack/runs/` and parses them.
+ * Returns an empty array if the directory doesn't exist.
+ */
+export function listRunRecords() {
+    const dir = runsDir();
+    if (!fs.existsSync(dir))
+        return [];
+    const records = [];
+    for (const file of fs.readdirSync(dir)) {
+        if (!file.endsWith(".json"))
+            continue;
+        try {
+            const raw = fs.readFileSync(path.join(dir, file), "utf8");
+            records.push(JSON.parse(raw));
+        }
+        catch {
+            // Skip malformed files.
+        }
+    }
+    records.sort((a, b) => (b.created_at ?? "").localeCompare(a.created_at ?? ""));
+    return records;
+}
+/** Get a single run record by UID, or `null` if not found. */
+export function getRunRecord(runUid) {
+    const file = runFilePath(runUid);
+    try {
+        const raw = fs.readFileSync(file, "utf8");
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/dist/install.d.ts

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+/**
+ * quack installer — Node phase.
+ *
+ * Called by `install/install.sh` after the bash bootstrap has:
+ *   1. Ensured Node 18+ is available (system or bundled at `~/.quack/node`)
+ *   2. Downloaded and extracted the `@modelworks/quack` npm tarball to a temp dir
+ *
+ * This script (from the extracted tarball's `dist/install.js`):
+ *   1. Copies `dist/` to `~/.quack/dist`
+ *   2. Creates the `~/.quack/bin/quack` wrapper
+ *   3. Configures PATH (shell config file)
+ *   4. Handles GitHub Actions (`$GITHUB_PATH`)
+ *   5. Prints a success summary
+ *
+ * Each step shows a spinner while running, then ✓ (green) or ✗ (red).
+ *
+ * Usage:
+ *   node dist/install.js [--target <dir>] [--no-modify-path] [--version <ver>] [--bundled-node]
+ *
+ * @module
+ */
+export {};

package/dist/install.js

@@ -0,0 +1,326 @@
+#!/usr/bin/env node
+/**
+ * quack installer — Node phase.
+ *
+ * Called by `install/install.sh` after the bash bootstrap has:
+ *   1. Ensured Node 18+ is available (system or bundled at `~/.quack/node`)
+ *   2. Downloaded and extracted the `@modelworks/quack` npm tarball to a temp dir
+ *
+ * This script (from the extracted tarball's `dist/install.js`):
+ *   1. Copies `dist/` to `~/.quack/dist`
+ *   2. Creates the `~/.quack/bin/quack` wrapper
+ *   3. Configures PATH (shell config file)
+ *   4. Handles GitHub Actions (`$GITHUB_PATH`)
+ *   5. Prints a success summary
+ *
+ * Each step shows a spinner while running, then ✓ (green) or ✗ (red).
+ *
+ * Usage:
+ *   node dist/install.js [--target <dir>] [--no-modify-path] [--version <ver>] [--bundled-node]
+ *
+ * @module
+ */
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import { fileURLToPath } from "node:url";
+// ---------------------------------------------------------------------------
+// ANSI colors
+// ---------------------------------------------------------------------------
+const isTTY = process.stderr.isTTY ?? false;
+const C = isTTY
+    ? {
+        reset: "\x1b[0m",
+        bold: "\x1b[1m",
+        dim: "\x1b[2m",
+        red: "\x1b[31m",
+        green: "\x1b[32m",
+        yellow: "\x1b[33m",
+        blue: "\x1b[34m",
+        gray: "\x1b[90m",
+        hide: "\x1b[?25l",
+        show: "\x1b[?25h",
+        clearLine: "\x1b[2K",
+    }
+    : {
+        reset: "",
+        bold: "",
+        dim: "",
+        red: "",
+        green: "",
+        yellow: "",
+        blue: "",
+        gray: "",
+        hide: "",
+        show: "",
+        clearLine: "",
+    };
+// ---------------------------------------------------------------------------
+// Spinner
+// ---------------------------------------------------------------------------
+const FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+class Spinner {
+    timer = null;
+    frame = 0;
+    msg = "";
+    start(msg) {
+        this.msg = msg;
+        this.stop();
+        if (isTTY)
+            process.stderr.write(C.hide);
+        this.timer = setInterval(() => {
+            process.stderr.write(`\r${C.clearLine}${C.gray}${FRAMES[this.frame % FRAMES.length]}${C.reset} ${this.msg}`);
+            this.frame++;
+        }, 80);
+    }
+    succeed(msg) {
+        this.stop();
+        process.stderr.write(`\r${C.clearLine}${C.green}✓${C.reset} ${msg ?? this.msg}\n`);
+    }
+    fail(msg) {
+        this.stop();
+        process.stderr.write(`\r${C.clearLine}${C.red}✗${C.reset} ${msg ?? this.msg}\n`);
+    }
+    warn(msg) {
+        this.stop();
+        process.stderr.write(`\r${C.clearLine}${C.yellow}!${C.reset} ${msg}\n`);
+    }
+    stop() {
+        if (this.timer) {
+            clearInterval(this.timer);
+            this.timer = null;
+        }
+        if (isTTY)
+            process.stderr.write(C.show);
+    }
+}
+function parseArgs(argv) {
+    const args = { noModifyPath: false, bundledNode: false };
+    for (let i = 0; i < argv.length; i++) {
+        switch (argv[i]) {
+            case "--target":
+                args.target = argv[++i];
+                break;
+            case "--no-modify-path":
+                args.noModifyPath = true;
+                break;
+            case "--version":
+                args.version = argv[++i];
+                break;
+            case "--bundled-node":
+                args.bundledNode = true;
+                break;
+            case "--help":
+            case "-h":
+                console.log("Usage: quack-install [--target <dir>] [--no-modify-path] [--version <ver>] [--bundled-node]");
+                process.exit(0);
+                break;
+        }
+    }
+    return args;
+}
+// ---------------------------------------------------------------------------
+// File helpers
+// ---------------------------------------------------------------------------
+/** Recursively copy a directory. */
+function copyDir(src, dest) {
+    fs.mkdirSync(dest, { recursive: true });
+    for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+        const srcPath = path.join(src, entry.name);
+        const destPath = path.join(dest, entry.name);
+        if (entry.isDirectory()) {
+            copyDir(srcPath, destPath);
+        }
+        else {
+            fs.copyFileSync(srcPath, destPath);
+        }
+    }
+}
+function configurePath(binDir) {
+    // Already on PATH?
+    const pathParts = (process.env.PATH ?? "").split(":");
+    if (pathParts.includes(binDir)) {
+        return { added: false, already: true, noConfig: false };
+    }
+    const home = os.homedir();
+    const shell = path.basename(process.env.SHELL ?? "");
+    const xdgConfig = process.env.XDG_CONFIG_HOME ?? path.join(home, ".config");
+    let configFiles;
+    let pathCmd;
+    switch (shell) {
+        case "fish":
+            configFiles = [path.join(home, ".config/fish/config.fish")];
+            pathCmd = `fish_add_path ${binDir}`;
+            break;
+        case "zsh":
+            configFiles = [
+                path.join(process.env.ZDOTDIR ?? home, ".zshrc"),
+                path.join(process.env.ZDOTDIR ?? home, ".zshenv"),
+                path.join(xdgConfig, "zsh/.zshrc"),
+                path.join(xdgConfig, "zsh/.zshenv"),
+            ];
+            pathCmd = `export PATH="${binDir}:$PATH"`;
+            break;
+        case "bash":
+            configFiles = [
+                path.join(home, ".bashrc"),
+                path.join(home, ".bash_profile"),
+                path.join(home, ".profile"),
+            ];
+            pathCmd = `export PATH="${binDir}:$PATH"`;
+            break;
+        default:
+            configFiles = [
+                path.join(home, ".bashrc"),
+                path.join(home, ".bash_profile"),
+                path.join(home, ".profile"),
+            ];
+            pathCmd = `export PATH="${binDir}:$PATH"`;
+    }
+    // Find first existing config file.
+    const configFile = configFiles.find((f) => fs.existsSync(f));
+    if (!configFile) {
+        return { added: false, already: false, noConfig: true };
+    }
+    // Already in config?
+    const content = fs.readFileSync(configFile, "utf8");
+    if (content.includes(pathCmd)) {
+        return { added: false, already: true, noConfig: false };
+    }
+    // Append.
+    fs.appendFileSync(configFile, `\n# quack\n${pathCmd}\n`);
+    return { added: true, already: false, noConfig: false, file: configFile };
+}
+// ---------------------------------------------------------------------------
+// Wrapper script
+// ---------------------------------------------------------------------------
+const WRAPPER_SCRIPT = `#!/bin/sh
+# quack wrapper — resolves Node (system or bundled) and launches quack.
+set -e
+SELF_DIR="$(cd "$(dirname "$0")" && pwd)"
+QUACK_HOME="$(cd "$SELF_DIR/.." && pwd)"
+if command -v node >/dev/null 2>&1; then
+  NODE_BIN="node"
+elif [ -x "$QUACK_HOME/node/node" ]; then
+  NODE_BIN="$QUACK_HOME/node/node"
+else
+  echo "quack: Node 18+ not found. Reinstall:" >&2
+  echo "  curl -fsSL https://raw.githubusercontent.com/modelworks-ai/quack/main/install/install.sh | bash" >&2
+  exit 1
+fi
+exec "$NODE_BIN" "$QUACK_HOME/dist/bin.js" "$@"
+`;
+// ---------------------------------------------------------------------------
+// Summary
+// ---------------------------------------------------------------------------
+function printSummary(args, binDir) {
+    const version = args.version ?? "latest";
+    const shell = path.basename(process.env.SHELL ?? "");
+    console.log("");
+    console.log(`  ${C.green}${C.bold}╔══════════════════════════════════════╗${C.reset}`);
+    console.log(`  ${C.green}${C.bold}║          quack installed! 🦆           ║${C.reset}`);
+    console.log(`  ${C.green}${C.bold}╚══════════════════════════════════════╝${C.reset}`);
+    console.log("");
+    console.log(`  ${C.dim}Version:${C.reset}  ${version}`);
+    console.log(`  ${C.dim}Location:${C.reset} ${binDir}/quack`);
+    if (args.bundledNode) {
+        console.log(`  ${C.dim}Node:${C.reset}     bundled`);
+    }
+    console.log("");
+    console.log(`  ${C.bold}Next steps:${C.reset}`);
+    console.log(`    quack login                              ${C.dim}# Authenticate via OAuth${C.reset}`);
+    console.log(`    cd <project> && quack init               ${C.dim}# Initialize a project${C.reset}`);
+    console.log(`    quack add <circuit-url>                  ${C.dim}# Add a circuit${C.reset}`);
+    console.log(`    quack opencode                           ${C.dim}# Launch OpenCode${C.reset}`);
+    console.log("");
+    if (!args.noModifyPath) {
+        console.log(`  ${C.dim}Open a new terminal or run:${C.reset}`);
+        if (shell) {
+            console.log(`  ${C.dim}  source ~/.${shell}rc  # or restart your shell${C.reset}`);
+        }
+        console.log(`  ${C.dim}to use quack.${C.reset}`);
+    }
+    else {
+        console.log(`  ${C.dim}Add to PATH: export PATH="${binDir}:$PATH"${C.reset}`);
+    }
+    console.log("");
+    console.log(`  ${C.dim}Docs: https://github.com/modelworks-ai/quack${C.reset}`);
+    console.log("");
+}
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+async function main() {
+    const args = parseArgs(process.argv.slice(2));
+    const installDir = args.target ?? path.join(os.homedir(), ".quack");
+    const binDir = path.join(installDir, "bin");
+    const distDir = path.join(installDir, "dist");
+    // Source dist files are in the same directory as this script (the
+    // extracted tarball's dist/).
+    const sourceDist = path.dirname(fileURLToPath(import.meta.url));
+    const spinner = new Spinner();
+    // Step 1: Copy dist to install dir.
+    spinner.start("Installing quack...");
+    try {
+        fs.mkdirSync(installDir, { recursive: true });
+        fs.mkdirSync(binDir, { recursive: true });
+        fs.rmSync(distDir, { recursive: true, force: true });
+        copyDir(sourceDist, distDir);
+        spinner.succeed(`Installed to ${installDir}`);
+    }
+    catch (err) {
+        spinner.fail("Installation failed");
+        console.error(err);
+        process.exit(1);
+    }
+    // Step 2: Create wrapper.
+    spinner.start("Creating wrapper script...");
+    try {
+        fs.writeFileSync(path.join(binDir, "quack"), WRAPPER_SCRIPT, {
+            mode: 0o755,
+        });
+        spinner.succeed(`Created ${path.join(binDir, "quack")}`);
+    }
+    catch (err) {
+        spinner.fail("Failed to create wrapper");
+        console.error(err);
+        process.exit(1);
+    }
+    // Step 3: Configure PATH.
+    if (!args.noModifyPath) {
+        spinner.start("Configuring PATH...");
+        try {
+            const result = configurePath(binDir);
+            if (result.added) {
+                spinner.succeed(`Added to PATH in ${result.file}`);
+            }
+            else if (result.already) {
+                spinner.succeed("Already on PATH");
+            }
+            else if (result.noConfig) {
+                spinner.warn(`No shell config found. Add manually:\n    export PATH="${binDir}:$PATH"`);
+            }
+        }
+        catch (err) {
+            spinner.fail("PATH configuration failed");
+            console.error(err);
+        }
+    }
+    // Step 4: GitHub Actions.
+    if (process.env.GITHUB_ACTIONS === "true" && process.env.GITHUB_PATH) {
+        spinner.start("Adding to $GITHUB_PATH...");
+        try {
+            fs.appendFileSync(process.env.GITHUB_PATH, binDir + "\n");
+            spinner.succeed(`Added ${binDir} to $GITHUB_PATH`);
+        }
+        catch {
+            spinner.warn("Could not write to $GITHUB_PATH");
+        }
+    }
+    // Summary.
+    printSummary(args, binDir);
+}
+main().catch((err) => {
+    console.error(`${C.red}Error: ${err.message}${C.reset}`);
+    process.exit(1);
+});

package/dist/project.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Project-level `.quack/` directory management: init, config/state read/write.
+ *
+ * @module
+ */
+import type { CircuitConfigEntry, CircuitStateEntry, QuackConfig, QuackState } from "./types.js";
+/** The `.quack/` directory name, placed at the project root. */
+export declare const QUACK_DIR = ".quack";
+/** Path to the `.quack/` directory in the current working directory. */
+export declare function quackDir(): string;
+/** Path to `.quack/config.json`. */
+export declare function configPath(): string;
+/** Path to `.quack/state.json`. */
+export declare function statePath(): string;
+/** Does a `.quack/` directory exist in the current project? */
+export declare function isQuackProject(): boolean;
+/** Assert the current directory is a quack project; throw a friendly error if not. */
+export declare function requireQuackProject(): void;
+/**
+ * `quack init` — create the `.quack/` directory with empty config,
+ * state, and `.gitignore`.
+ *
+ * Errors if `.quack/` already exists, unless `force` is `true`.
+ */
+export declare function initProject(force?: boolean): void;
+/** Read the project config. Throws if `.quack/` doesn't exist. */
+export declare function readConfig(): QuackConfig;
+/** Write the project config (atomic-ish: write then sync). */
+export declare function writeConfig(config: QuackConfig): void;
+/**
+ * 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 declare function readState(): QuackState;
+/** Write the project state. */
+export declare function writeState(state: QuackState): void;
+/** Add a circuit entry to the config (no-op if already present). Returns `true` if added. */
+export declare function addCircuitToConfig(entry: CircuitConfigEntry): boolean;
+/** Remove a circuit from config by `circuit_uid`. Returns `true` if removed. */
+export declare function removeCircuitFromConfig(circuitUid: string): boolean;
+/** Upsert a circuit's state entry (keyed by `circuit_uid`). */
+export declare function upsertCircuitState(entry: CircuitStateEntry): void;
+/** Remove a circuit's state entry. Returns `true` if removed. */
+export declare function removeCircuitState(circuitUid: string): boolean;
+/** Get a circuit's state entry, or `null` if not present. */
+export declare function getCircuitState(circuitUid: string): CircuitStateEntry | null;