@veedubin/neuralgentics 0.9.2 → 0.9.3

package/dist/cli.d.ts

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+/**
+ * CLI entry point for the `neuralgentics` command — TypeScript port of the
+ * Python `neuralgentics-cli/src/neuralgentics/cli.py`.
+ *
+ * Single-command bootstrap: pass `--init` (or the positional alias `init`)
+ * to download + place the neuralgentics OpenCode plugin into `--target`.
+ *
+ * Uses Node.js `util.parseArgs` for argv parsing (Node 20+ built-in).
+ */
+declare function main(argv: string[]): Promise<number>;
+export { main };
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA;;;;;;;;GAQG;AAqGH,iBAAe,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAuEnD;AAwBD,OAAO,EAAE,IAAI,EAAE,CAAC"}

package/dist/cli.js

@@ -0,0 +1,180 @@
+#!/usr/bin/env node
+/**
+ * CLI entry point for the `neuralgentics` command — TypeScript port of the
+ * Python `neuralgentics-cli/src/neuralgentics/cli.py`.
+ *
+ * Single-command bootstrap: pass `--init` (or the positional alias `init`)
+ * to download + place the neuralgentics OpenCode plugin into `--target`.
+ *
+ * Uses Node.js `util.parseArgs` for argv parsing (Node 20+ built-in).
+ */
+import { parseArgs } from "node:util";
+import { CLI_VERSION, runInit, NeuralgenticsError } from "./neuralgentics/init.js";
+/** Sentinel for `--version` with no argument (distinguishes bare vs. with-arg). */
+const CLI_VERSION_SENTINEL = "__cli__";
+function parseArgv(argv) {
+    const { values } = parseArgs({
+        args: argv,
+        options: {
+            init: { type: "boolean", default: false },
+            version: { type: "string" },
+            target: { type: "string", short: "t", default: "." },
+            force: { type: "boolean", default: false },
+            "dry-run": { type: "boolean", default: false },
+            yes: { type: "boolean", short: "y", default: false },
+            repo: { type: "string", default: "Veedubin/neuralgentics" },
+            offline: { type: "boolean", default: false },
+            "with-backend": { type: "boolean", default: false },
+        },
+        allowPositionals: true,
+    });
+    // version handling: bare --version is intercepted in main() before
+    // parseArgs runs. Here we only see --version=<X.Y.Z> or --version X.Y.Z.
+    const version = values.version ?? "latest";
+    // Reconstruct positionals by re-parsing (parseArgs doesn't return them
+    // when tokens:false). We use a lightweight scan instead.
+    const positionals = [];
+    const knownFlags = new Set([
+        "--init", "--force", "--dry-run", "--yes", "-y", "--offline",
+        "--with-backend", "-h", "--help",
+    ]);
+    const valueFlags = new Set(["--version", "--target", "-t", "--repo"]);
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a.startsWith("--") && a.includes("="))
+            continue; // --foo=bar form
+        if (knownFlags.has(a))
+            continue;
+        if (valueFlags.has(a)) {
+            i++;
+            continue;
+        }
+        if (a.startsWith("-"))
+            continue;
+        // Bare `--version` (already handled in main) — skip its potential next.
+        positionals.push(a);
+    }
+    const command = positionals.length > 0 ? positionals[0] : undefined;
+    return {
+        init: values.init === true,
+        target: values.target ?? ".",
+        force: values.force === true,
+        dryRun: values["dry-run"] === true,
+        yes: values.yes === true,
+        repo: values.repo ?? "Veedubin/neuralgentics",
+        version,
+        offline: values.offline === true,
+        withBackend: values["with-backend"] === true,
+        command,
+    };
+}
+function printHelp() {
+    process.stdout.write(`Usage: neuralgentics [init] [options]\n` +
+        `\n` +
+        `Bootstrapper CLI for the neuralgentics OpenCode plugin.\n` +
+        `\n` +
+        `Options:\n` +
+        `  --init              Bootstrap the target directory with the neuralgentics plugin.\n` +
+        `  --version [VER]     With no arg: print CLI version and exit. With arg: plugin version to install.\n` +
+        `  --target, -t DIR    Directory to bootstrap (default: current directory).\n` +
+        `  --force             Overwrite existing .opencode/ files even if user-modified.\n` +
+        `  --dry-run           Preview all actions without writing anything.\n` +
+        `  --yes, -y           Skip all confirmation prompts.\n` +
+        `  --repo REPO         GitHub repository to download from (default: Veedubin/neuralgentics).\n` +
+        `  --offline           Use a bundled tarball instead of downloading (not yet available).\n` +
+        `  --with-backend      Set up database containers (podman-compose / docker).\n` +
+        `  -h, --help          Show this help and exit.\n` +
+        `\n` +
+        `Positional alias: \`neuralgentics init\` is equivalent to \`--init\`.\n`);
+}
+function formatError(err) {
+    return `[ERROR] ${err.message}\nSuggestion: ${err.remediation}`;
+}
+async function main(argv) {
+    // Handle -h / --help before parseArgs (which doesn't know these).
+    if (argv.includes("-h") || argv.includes("--help")) {
+        printHelp();
+        return 0;
+    }
+    // Handle bare `--version` (no following value) BEFORE parseArgs, because
+    // `parseArgs` with type:string requires a value and errors on bare form.
+    const bareVersionIdx = argv.indexOf("--version");
+    if (bareVersionIdx !== -1) {
+        const next = argv[bareVersionIdx + 1];
+        if (next === undefined || next.startsWith("-")) {
+            // Bare `--version` — print CLI version and exit 0.
+            process.stdout.write(`neuralgentics ${CLI_VERSION}\n`);
+            return 0;
+        }
+    }
+    let parsed;
+    try {
+        parsed = parseArgv(argv);
+    }
+    catch (exc) {
+        process.stderr.write(`[ERROR] ${exc instanceof Error ? exc.message : String(exc)}\n` +
+            `Run \`neuralgentics --help\` for usage.\n`);
+        return 2;
+    }
+    // --version with an explicit argument: install plugin v<version>.
+    // (Bare form was handled above.) parsed.version is "latest" or "X.Y.Z".
+    // If the user passed `--version=X.Y.Z`, parsed.version is that value.
+    if (parsed.version !== "latest") {
+        // Only treat as "print version" if it was the sentinel — which we already
+        // handled above. Otherwise it's a plugin version to install.
+    }
+    // init requested via --init or the positional `init` alias.
+    const initRequested = parsed.init || parsed.command === "init";
+    if (!initRequested) {
+        printHelp();
+        return 0;
+    }
+    const opts = {
+        init: true,
+        target: parsed.target,
+        force: parsed.force,
+        dryRun: parsed.dryRun,
+        yes: parsed.yes,
+        repo: parsed.repo,
+        version: parsed.version,
+        offline: parsed.offline,
+        withBackend: parsed.withBackend,
+    };
+    try {
+        return await runInit(opts);
+    }
+    catch (err) {
+        if (err instanceof NeuralgenticsError) {
+            process.stderr.write(formatError(err) + "\n");
+            return err.exitCode;
+        }
+        if (err instanceof Error) {
+            process.stderr.write(`[ERROR] ${err.message}\n`);
+            return 1;
+        }
+        process.stderr.write(`[ERROR] ${String(err)}\n`);
+        return 1;
+    }
+}
+// Entry point — only run when invoked directly (not when imported).
+const isDirectInvocation = process.argv[1] && (process.argv[1].endsWith("cli.js") ||
+    process.argv[1].endsWith("cli") ||
+    process.argv[1].endsWith("neuralgentics"));
+if (isDirectInvocation) {
+    main(process.argv.slice(2))
+        .then((code) => {
+        process.exitCode = code;
+    })
+        .catch((err) => {
+        if (err instanceof NeuralgenticsError) {
+            process.stderr.write(formatError(err) + "\n");
+            process.exitCode = err.exitCode;
+        }
+        else {
+            process.stderr.write(`[ERROR] ${err instanceof Error ? err.message : String(err)}\n`);
+            process.exitCode = 1;
+        }
+    });
+}
+export { main };
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}

package/dist/neuralgentics/download.d.ts

@@ -0,0 +1,101 @@
+/**
+ * GitHub release download, SHA256 verification, and tarball extraction —
+ * TypeScript port of `neuralgentics-cli/src/neuralgentics/download.py`.
+ *
+ * Uses Node 20+ built-ins only:
+ *   - Native `fetch()` for HTTP (no `httpx`/`axios`).
+ *   - `crypto.createHash('sha256')` for verification.
+ *   - `child_process.execSync('tar -xzf ...')` for extraction.
+ *
+ * Public API:
+ *   - `resolveVersion` — turn `"latest"` or `"X.Y.Z"` into a concrete semver
+ *     string, calling the GitHub API for `"latest"`. Cached for 1 hour in
+ *     `~/.cache/neuralgentics/version_cache.json`.
+ *   - `downloadTarball` — fetch `neuralgentics-{version}.tar.gz` and
+ *     `checksums.txt` from a GitHub release into a per-pid temp dir.
+ *   - `verifySha256` — parse `checksums.txt` and compare the tarball's
+ *     actual SHA256 against it.
+ *   - `extractTarball` — extract the tarball to `dest` with
+ *     `--strip-components=1` semantics via `tar -xzf`.
+ */
+/** Base class for all neuralgentics CLI errors (mirrors `errors.py`). */
+export declare class NeuralgenticsError extends Error {
+    readonly exitCode: number;
+    readonly remediation: string;
+    constructor(message: string, remediation?: string);
+}
+/** An HTTP request failed (connect error, bad status, etc.). */
+export declare class NetworkError extends NeuralgenticsError {
+    readonly exitCode = 6;
+    readonly remediation = "Check your network connection and verify the version exists on the GitHub releases page.";
+    constructor(message: string, remediation?: string);
+}
+/** Downloaded artifact's SHA256 did not match the published checksum. */
+export declare class Sha256Mismatch extends NeuralgenticsError {
+    readonly exitCode = 7;
+    readonly remediation = "Re-run. If the problem persists, report it on GitHub issues \u2014 the download may be tampered.";
+    constructor(message: string, remediation?: string);
+}
+/** The downloaded tarball could not be extracted. */
+export declare class TarballCorrupt extends NeuralgenticsError {
+    readonly exitCode = 8;
+    readonly remediation = "Check disk space and re-download. The archive may be corrupt.";
+    constructor(message: string, remediation?: string);
+}
+/** A file expected after extraction was missing. */
+export declare class ExtractionFailed extends NeuralgenticsError {
+    readonly exitCode = 9;
+    readonly remediation = "Check the release assets on GitHub \u2014 the archive may be incomplete.";
+    constructor(message: string, remediation?: string);
+}
+/** The requested plugin version does not exist on GitHub. */
+export declare class VersionNotFound extends NeuralgenticsError {
+    readonly exitCode = 14;
+    readonly remediation = "Check available versions at the GitHub releases page. Use 'latest' for the most recent release.";
+    constructor(message: string, remediation?: string);
+}
+/**
+ * Resolve `version` to a concrete `X.Y.Z` string.
+ *
+ * - If `version === "latest"`, query the GitHub API
+ *   `GET /repos/{repo}/releases/latest` and return `tag_name` with the
+ *   leading `v` stripped. Cached for 1 hour in
+ *   `~/.cache/neuralgentics/version_cache.json` (keyed by `repo`).
+ * - Otherwise, validate `version` matches `X.Y.Z` and return it as-is.
+ */
+export declare function resolveVersion(version: string, repo: string, githubToken?: string): Promise<string>;
+/** Result of `downloadTarball`: the local paths to the tarball + checksums. */
+export interface DownloadedTarball {
+    tarballPath: string;
+    checksumsPath: string;
+}
+/**
+ * Download `neuralgentics-{version}.tar.gz` and `checksums.txt`.
+ *
+ * Returns the local paths. Files are written to a per-pid, per-version temp
+ * directory under `os.tmpdir()`. On any exception the temp directory is
+ * removed.
+ */
+export declare function downloadTarball(version: string, repo: string, githubToken?: string): Promise<DownloadedTarball>;
+/**
+ * Verify `tarballPath` against the entry in `checksumsPath`.
+ *
+ * `checksums.txt` lines have the form `<sha>  <filename>` (two spaces, GNU
+ * coreutils format). Raises `Sha256Mismatch` if the file is missing from
+ * checksums or the computed hash doesn't match.
+ */
+export declare function verifySha256(tarballPath: string, checksumsPath: string): Promise<void>;
+/**
+ * Extract `tarballPath` into `dest` with `--strip-components=1` semantics.
+ *
+ * The release tarball has a single top-level directory
+ * (`neuralgentics-{version}/`); this function flattens that one level so
+ * files land directly under `dest` (e.g. `dest/.opencode/agents/coder.md`).
+ *
+ * Uses `tar -xzf` via `child_process.execSync` (available on all Linux/Mac).
+ * After extraction, verifies that `dest/.opencode/agents/coder.md` exists —
+ * a known required file from the archive layout. Raises `ExtractionFailed`
+ * if missing, `TarballCorrupt` if the archive can't be opened.
+ */
+export declare function extractTarball(tarballPath: string, dest: string): Promise<void>;
+//# sourceMappingURL=download.d.ts.map

package/dist/neuralgentics/download.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"download.d.ts","sourceRoot":"","sources":["../../src/neuralgentics/download.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AA8BH,yEAAyE;AACzE,qBAAa,kBAAmB,SAAQ,KAAK;IAC3C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAK;IAC9B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAgD;gBAChE,OAAO,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM;CAOlD;AAED,gEAAgE;AAChE,qBAAa,YAAa,SAAQ,kBAAkB;IAClD,QAAQ,CAAC,QAAQ,KAAK;IACtB,QAAQ,CAAC,WAAW,8FACyE;gBACjF,OAAO,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM;CAIlD;AAED,yEAAyE;AACzE,qBAAa,cAAe,SAAQ,kBAAkB;IACpD,QAAQ,CAAC,QAAQ,KAAK;IACtB,QAAQ,CAAC,WAAW,sGAC4E;gBACpF,OAAO,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM;CAIlD;AAED,qDAAqD;AACrD,qBAAa,cAAe,SAAQ,kBAAkB;IACpD,QAAQ,CAAC,QAAQ,KAAK;IACtB,QAAQ,CAAC,WAAW,mEAAmE;gBAC3E,OAAO,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM;CAIlD;AAED,oDAAoD;AACpD,qBAAa,gBAAiB,SAAQ,kBAAkB;IACtD,QAAQ,CAAC,QAAQ,KAAK;IACtB,QAAQ,CAAC,WAAW,8EAAyE;gBACjF,OAAO,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM;CAIlD;AAED,6DAA6D;AAC7D,qBAAa,eAAgB,SAAQ,kBAAkB;IACrD,QAAQ,CAAC,QAAQ,MAAM;IACvB,QAAQ,CAAC,WAAW,qGACgF;gBACxF,OAAO,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM;CAIlD;AAMD;;;;;;;;GAQG;AACH,wBAAsB,cAAc,CAClC,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EACZ,WAAW,CAAC,EAAE,MAAM,GACnB,OAAO,CAAC,MAAM,CAAC,CAgBjB;AA4ED,+EAA+E;AAC/E,MAAM,WAAW,iBAAiB;IAChC,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;GAMG;AACH,wBAAsB,eAAe,CACnC,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EACZ,WAAW,CAAC,EAAE,MAAM,GACnB,OAAO,CAAC,iBAAiB,CAAC,CAgC5B;AAwCD;;;;;;GAMG;AACH,wBAAsB,YAAY,CAAC,WAAW,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAQ5F;AAoCD;;;;;;;;;;;GAWG;AACH,wBAAsB,cAAc,CAAC,WAAW,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAkBrF"}

package/dist/neuralgentics/download.js

@@ -0,0 +1,348 @@
+/**
+ * GitHub release download, SHA256 verification, and tarball extraction —
+ * TypeScript port of `neuralgentics-cli/src/neuralgentics/download.py`.
+ *
+ * Uses Node 20+ built-ins only:
+ *   - Native `fetch()` for HTTP (no `httpx`/`axios`).
+ *   - `crypto.createHash('sha256')` for verification.
+ *   - `child_process.execSync('tar -xzf ...')` for extraction.
+ *
+ * Public API:
+ *   - `resolveVersion` — turn `"latest"` or `"X.Y.Z"` into a concrete semver
+ *     string, calling the GitHub API for `"latest"`. Cached for 1 hour in
+ *     `~/.cache/neuralgentics/version_cache.json`.
+ *   - `downloadTarball` — fetch `neuralgentics-{version}.tar.gz` and
+ *     `checksums.txt` from a GitHub release into a per-pid temp dir.
+ *   - `verifySha256` — parse `checksums.txt` and compare the tarball's
+ *     actual SHA256 against it.
+ *   - `extractTarball` — extract the tarball to `dest` with
+ *     `--strip-components=1` semantics via `tar -xzf`.
+ */
+import { createHash } from "node:crypto";
+import { execSync } from "node:child_process";
+import { promises as fs } from "node:fs";
+import * as path from "node:path";
+import * as os from "node:os";
+/** Base URL for the GitHub REST API. */
+const GITHUB_API = "https://api.github.com";
+/** Base URL for GitHub release asset downloads (not rate-limited). */
+const GITHUB_DOWNLOAD = "https://github.com";
+/** Cache file for `latest` version resolution (1-hour TTL). */
+const CACHE_DIR = path.join(os.homedir(), ".cache", "neuralgentics");
+const CACHE_FILE = path.join(CACHE_DIR, "version_cache.json");
+/** Cache TTL in seconds (1 hour). */
+const CACHE_TTL = 3600;
+/** Read chunk size for SHA256 computation (64 KiB). */
+const CHUNK_SIZE = 64 * 1024;
+/** Regex for a valid `X.Y.Z` semver (no pre-release suffix). */
+const SEMVER_RE = /^\d+\.\d+\.\d+$/;
+/** The known required file inside the extracted tarball layout. */
+const REQUIRED_EXTRACTED_FILE = path.join(".opencode", "agents", "coder.md");
+/** Base class for all neuralgentics CLI errors (mirrors `errors.py`). */
+export class NeuralgenticsError extends Error {
+    exitCode = 1;
+    remediation = "See the documentation for troubleshooting.";
+    constructor(message, remediation) {
+        super(message);
+        this.name = "NeuralgenticsError";
+        if (remediation !== undefined) {
+            this.remediation = remediation;
+        }
+    }
+}
+/** An HTTP request failed (connect error, bad status, etc.). */
+export class NetworkError extends NeuralgenticsError {
+    exitCode = 6;
+    remediation = "Check your network connection and verify the version exists on the GitHub releases page.";
+    constructor(message, remediation) {
+        super(message, remediation);
+        this.name = "NetworkError";
+    }
+}
+/** Downloaded artifact's SHA256 did not match the published checksum. */
+export class Sha256Mismatch extends NeuralgenticsError {
+    exitCode = 7;
+    remediation = "Re-run. If the problem persists, report it on GitHub issues — the download may be tampered.";
+    constructor(message, remediation) {
+        super(message, remediation);
+        this.name = "Sha256Mismatch";
+    }
+}
+/** The downloaded tarball could not be extracted. */
+export class TarballCorrupt extends NeuralgenticsError {
+    exitCode = 8;
+    remediation = "Check disk space and re-download. The archive may be corrupt.";
+    constructor(message, remediation) {
+        super(message, remediation);
+        this.name = "TarballCorrupt";
+    }
+}
+/** A file expected after extraction was missing. */
+export class ExtractionFailed extends NeuralgenticsError {
+    exitCode = 9;
+    remediation = "Check the release assets on GitHub — the archive may be incomplete.";
+    constructor(message, remediation) {
+        super(message, remediation);
+        this.name = "ExtractionFailed";
+    }
+}
+/** The requested plugin version does not exist on GitHub. */
+export class VersionNotFound extends NeuralgenticsError {
+    exitCode = 14;
+    remediation = "Check available versions at the GitHub releases page. Use 'latest' for the most recent release.";
+    constructor(message, remediation) {
+        super(message, remediation);
+        this.name = "VersionNotFound";
+    }
+}
+/**
+ * Resolve `version` to a concrete `X.Y.Z` string.
+ *
+ * - If `version === "latest"`, query the GitHub API
+ *   `GET /repos/{repo}/releases/latest` and return `tag_name` with the
+ *   leading `v` stripped. Cached for 1 hour in
+ *   `~/.cache/neuralgentics/version_cache.json` (keyed by `repo`).
+ * - Otherwise, validate `version` matches `X.Y.Z` and return it as-is.
+ */
+export async function resolveVersion(version, repo, githubToken) {
+    if (version === "latest") {
+        const cached = await readCachedLatest(repo);
+        if (cached !== null)
+            return cached;
+        const tag = await fetchLatestTag(repo, githubToken);
+        const resolved = tag.startsWith("v") ? tag.slice(1) : tag;
+        if (!SEMVER_RE.test(resolved)) {
+            throw new VersionNotFound(`GitHub returned a non-semver tag name ${JSON.stringify(tag)} for ${repo}.`);
+        }
+        await writeCachedLatest(repo, resolved);
+        return resolved;
+    }
+    if (SEMVER_RE.test(version))
+        return version;
+    throw new VersionNotFound(`Version ${JSON.stringify(version)} is not a valid X.Y.Z semver.`);
+}
+async function readCachedLatest(repo) {
+    try {
+        const raw = await fs.readFile(CACHE_FILE, "utf-8");
+        const data = JSON.parse(raw);
+        const entry = data[repo];
+        if (!entry || typeof entry.ts !== "number" || typeof entry.version !== "string") {
+            return null;
+        }
+        if (Date.now() / 1000 - entry.ts > CACHE_TTL)
+            return null;
+        return entry.version;
+    }
+    catch {
+        return null;
+    }
+}
+async function writeCachedLatest(repo, version) {
+    try {
+        await fs.mkdir(CACHE_DIR, { recursive: true });
+        let data = {};
+        try {
+            const raw = await fs.readFile(CACHE_FILE, "utf-8");
+            data = JSON.parse(raw);
+        }
+        catch {
+            data = {};
+        }
+        data[repo] = { ts: Date.now() / 1000, version };
+        await fs.writeFile(CACHE_FILE, JSON.stringify(data), "utf-8");
+    }
+    catch {
+        // Best-effort cache; ignore write failures.
+    }
+}
+function resolveToken(githubToken) {
+    return githubToken ?? process.env.GITHUB_TOKEN;
+}
+async function fetchLatestTag(repo, githubToken) {
+    const url = `${GITHUB_API}/repos/${repo}/releases/latest`;
+    const headers = { Accept: "application/vnd.github+json" };
+    const token = resolveToken(githubToken);
+    if (token)
+        headers["Authorization"] = `Bearer ${token}`;
+    let resp;
+    try {
+        resp = await fetch(url, { headers, redirect: "follow" });
+    }
+    catch (exc) {
+        throw new NetworkError(`Failed to reach GitHub API at ${url}: ${exc instanceof Error ? exc.message : String(exc)}`, "Check your network connection and that the repository exists.");
+    }
+    if (resp.status === 404) {
+        throw new VersionNotFound(`No releases found for ${repo}.`);
+    }
+    if (!resp.ok) {
+        throw new NetworkError(`GitHub API returned ${resp.status} ${resp.statusText} for ${url}.`);
+    }
+    let body;
+    try {
+        body = await resp.json();
+    }
+    catch (exc) {
+        throw new NetworkError(`GitHub API returned invalid JSON for ${url}: ${exc instanceof Error ? exc.message : String(exc)}.`);
+    }
+    if (body === null || typeof body !== "object" || Array.isArray(body)) {
+        throw new VersionNotFound(`GitHub API response for ${repo} had no 'tag_name' field.`);
+    }
+    const tag = body.tag_name;
+    if (typeof tag !== "string" || tag.length === 0) {
+        throw new VersionNotFound(`GitHub API response for ${repo} had no 'tag_name' field.`);
+    }
+    return tag;
+}
+/**
+ * Download `neuralgentics-{version}.tar.gz` and `checksums.txt`.
+ *
+ * Returns the local paths. Files are written to a per-pid, per-version temp
+ * directory under `os.tmpdir()`. On any exception the temp directory is
+ * removed.
+ */
+export async function downloadTarball(version, repo, githubToken) {
+    if (!SEMVER_RE.test(version)) {
+        throw new VersionNotFound(`Version ${JSON.stringify(version)} is not a valid X.Y.Z semver.`);
+    }
+    const tmpDir = path.join(os.tmpdir(), `neuralgentics-${process.pid}-${version}`);
+    await fs.mkdir(tmpDir, { recursive: true });
+    const tarballPath = path.join(tmpDir, `neuralgentics-${version}.tar.gz`);
+    const checksumsPath = path.join(tmpDir, "checksums.txt");
+    const base = `${GITHUB_DOWNLOAD}/${repo}/releases/download/v${version}`;
+    const tarballUrl = `${base}/neuralgentics-${version}.tar.gz`;
+    const checksumsUrl = `${base}/checksums.txt`;
+    const headers = {};
+    const token = resolveToken(githubToken);
+    if (token)
+        headers["Authorization"] = `Bearer ${token}`;
+    try {
+        await streamDownload(tarballUrl, tarballPath, headers);
+        await streamDownload(checksumsUrl, checksumsPath, headers);
+    }
+    catch (exc) {
+        // Cleanup the temp dir on any failure so we don't leave partial files.
+        try {
+            const entries = await fs.readdir(tmpDir);
+            await Promise.all(entries.map((e) => fs.unlink(path.join(tmpDir, e)).catch(() => { })));
+            await fs.rmdir(tmpDir).catch(() => { });
+        }
+        catch {
+            // Best-effort cleanup.
+        }
+        throw exc;
+    }
+    return { tarballPath, checksumsPath };
+}
+async function streamDownload(url, dest, headers) {
+    let resp;
+    try {
+        resp = await fetch(url, { headers, redirect: "follow" });
+    }
+    catch (exc) {
+        throw new NetworkError(`Failed to download ${url}: ${exc instanceof Error ? exc.message : String(exc)}`, "Check your network connection and retry.");
+    }
+    if (!resp.ok) {
+        throw new NetworkError(`Failed to download ${url}: ${resp.status} ${resp.statusText}.`, "Check your network connection and that the version exists on the GitHub releases page.");
+    }
+    const body = resp.body;
+    if (body === null) {
+        throw new NetworkError(`Failed to download ${url}: empty response body.`);
+    }
+    const fileHandle = await fs.open(dest, "w");
+    try {
+        const reader = body.getReader();
+        // eslint-disable-next-line no-constant-condition
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            if (value)
+                await fileHandle.write(value);
+        }
+    }
+    finally {
+        await fileHandle.close();
+    }
+}
+/**
+ * Verify `tarballPath` against the entry in `checksumsPath`.
+ *
+ * `checksums.txt` lines have the form `<sha>  <filename>` (two spaces, GNU
+ * coreutils format). Raises `Sha256Mismatch` if the file is missing from
+ * checksums or the computed hash doesn't match.
+ */
+export async function verifySha256(tarballPath, checksumsPath) {
+    const expected = await lookupChecksum(checksumsPath, path.basename(tarballPath));
+    const actual = await sha256OfFile(tarballPath);
+    if (actual !== expected) {
+        throw new Sha256Mismatch(`SHA256 verification failed for ${path.basename(tarballPath)}. Expected: ${expected}, got: ${actual}.`);
+    }
+}
+async function lookupChecksum(checksumsPath, filename) {
+    const text = await fs.readFile(checksumsPath, "utf-8");
+    for (const rawLine of text.split(/\r?\n/)) {
+        const line = rawLine.trim();
+        if (!line || line.startsWith("#"))
+            continue;
+        const parts = line.split(/\s+/);
+        if (parts.length !== 2)
+            continue;
+        const [sha, rawName] = parts;
+        // The checksum file may prefix the name with `*` (binary mode) or `./`.
+        const name = rawName.replace(/^\*/, "").replace(/^\.\//, "");
+        if (name === filename && /^[0-9a-f]{64}$/.test(sha)) {
+            return sha;
+        }
+    }
+    throw new Sha256Mismatch(`${filename} not found in ${path.basename(checksumsPath)}.`);
+}
+async function sha256OfFile(filePath) {
+    const hash = createHash("sha256");
+    const handle = await fs.open(filePath, "r");
+    try {
+        const buffer = Buffer.alloc(CHUNK_SIZE);
+        // eslint-disable-next-line no-constant-condition
+        while (true) {
+            const { bytesRead } = await handle.read(buffer, 0, CHUNK_SIZE, null);
+            if (bytesRead === 0)
+                break;
+            hash.update(buffer.subarray(0, bytesRead));
+        }
+    }
+    finally {
+        await handle.close();
+    }
+    return hash.digest("hex");
+}
+/**
+ * Extract `tarballPath` into `dest` with `--strip-components=1` semantics.
+ *
+ * The release tarball has a single top-level directory
+ * (`neuralgentics-{version}/`); this function flattens that one level so
+ * files land directly under `dest` (e.g. `dest/.opencode/agents/coder.md`).
+ *
+ * Uses `tar -xzf` via `child_process.execSync` (available on all Linux/Mac).
+ * After extraction, verifies that `dest/.opencode/agents/coder.md` exists —
+ * a known required file from the archive layout. Raises `ExtractionFailed`
+ * if missing, `TarballCorrupt` if the archive can't be opened.
+ */
+export async function extractTarball(tarballPath, dest) {
+    await fs.mkdir(dest, { recursive: true });
+    try {
+        execSync(`tar -xzf "${tarballPath}" -C "${dest}" --strip-components=1`, {
+            stdio: "pipe",
+            timeout: 60_000,
+        });
+    }
+    catch (exc) {
+        throw new TarballCorrupt(`Failed to extract tarball: ${exc instanceof Error ? exc.message : String(exc)}`);
+    }
+    const required = path.join(dest, REQUIRED_EXTRACTED_FILE);
+    try {
+        await fs.access(required);
+    }
+    catch {
+        throw new ExtractionFailed(`${REQUIRED_EXTRACTED_FILE} not found after extraction.`);
+    }
+}
+//# sourceMappingURL=download.js.map