@thomas-huang/caosi 0.1.0

package/README.md

@@ -0,0 +1,110 @@
+# caosi
+
+[中文](README.zh-CN.md)
+
+A local converter between LLM client protocols and named upstream providers. Point Claude Code, Codex, or Gemini CLI at `http://127.0.0.1:9999/{provider_name}`. Same protocol is passed through; OpenAI Chat, OpenAI Responses, Claude Messages, and Gemini are converted when they differ.
+
+caosi is a converter, not a gateway.
+
+## Install
+
+```bash
+npm install -g @thomas-huang/caosi
+caosi --version
+```
+
+Needs Node.js 18+ on macOS, Linux, or Windows (amd64). The npm package downloads a native binary from GitHub Releases.
+
+## Run
+
+The first start writes a sample Provider File and exits. That is intentional: caosi will not listen on an empty config.
+
+```bash
+caosi
+```
+
+Edit `~/.caosi/providers.jsonc`. Set `api_key` and `base_url`. If Claude Code will talk to an OpenAI-compatible upstream, keep `model` (for example `deepseek-chat`) so the upstream does not see `claude-*`.
+
+Start again:
+
+```bash
+caosi
+curl -s http://127.0.0.1:9999/health
+```
+
+## Point Claude Code at it
+
+```bash
+export ANTHROPIC_BASE_URL=http://127.0.0.1:9999/deepseek
+export ANTHROPIC_API_KEY=dummy
+claude
+```
+
+Replace `deepseek` with your Provider Name. caosi ignores the client key and uses the Provider's `api_key`. Claude Code sends `/v1/messages`; caosi converts when the upstream is not Claude.
+
+## Codex / OpenAI and Gemini CLI
+
+OpenAI SDK, Chat Completions, and Codex:
+
+```bash
+export OPENAI_BASE_URL=http://127.0.0.1:9999/deepseek/v1
+export OPENAI_API_KEY=dummy
+```
+
+Gemini CLI (`~/.gemini/.env` or the environment):
+
+```bash
+export GEMINI_API_BASE=http://127.0.0.1:9999/deepseek
+```
+
+## Provider File
+
+`~/.caosi/providers.jsonc` is JSONC keyed by Provider Name (the first URL path segment). `health` is reserved.
+
+```jsonc
+{
+  "deepseek": {
+    "base_url": "https://api.deepseek.com",
+    "protocol": "openai_chat",
+    "api_key": "sk-...",
+    "model": "deepseek-chat"
+  }
+}
+```
+
+| `protocol` | Upstream wire protocol |
+|---|---|
+| `openai_chat` | OpenAI Chat Completions |
+| `openai_responses` | OpenAI Responses |
+| `claude_messages` | Claude Messages |
+| `gemini` | Gemini generateContent |
+
+- `model` is optional: when set, it replaces the client's model name on the upstream request.
+- `headers` is optional extra request headers (for example OpenRouter).
+- `base_url` is a prefix. caosi does not strip `/v1`. Use the root the upstream actually expects (`https://api.deepseek.com`, not `https://api.deepseek.com/v1`).
+
+## Listen, health, reload
+
+- Loopback only: `127.0.0.1` (or `::1` via `--listen`). Default port `9999` (`--port`).
+- `GET /health`
+- Saving `providers.jsonc` hot-reloads; a bad file keeps the last good config.
+- Flags: `--config-dir`, `--port`, `--listen`, `--log-level`, `--version`.
+
+## What it does not do
+
+No Web UI, OAuth, failover, key pools, or rewriting your Claude Code / Codex / Gemini config files.
+
+## Without Node.js
+
+Download the binary for your OS from [GitHub Releases](https://github.com/thomas-huang/caosi/releases), rename it to `caosi` (or `caosi.exe` on Windows), and put it on your `PATH`. Checksums are in `checksums.txt` on each release.
+
+## Contributors
+
+```bash
+go install github.com/thomas-huang/caosi/cmd/caosi@latest
+go test ./...
+```
+
+Domain language: [CONTEXT.md](CONTEXT.md). Decisions: [docs/adr](docs/adr).
+
+To cut a release, push a tag `vX.Y.Z` (first public: `v0.1.0`). GitHub Actions builds the five binaries, writes checksums, creates the Release, and publishes `@thomas-huang/caosi` to npm with GitHub OIDC trusted publishing (no access token). On npmjs.com, add a GitHub Actions trusted publisher for package `@thomas-huang/caosi`: repository `thomas-huang/caosi`, workflow filename `release.yml`.

package/bin/caosi.js

@@ -0,0 +1,32 @@
+#!/usr/bin/env node
+
+const fs = require("node:fs");
+const path = require("node:path");
+const { spawn } = require("node:child_process");
+
+const binaryName = process.platform === "win32" ? "caosi.exe" : "caosi";
+const binaryPath = path.join(__dirname, "..", "vendor", binaryName);
+
+if (!fs.existsSync(binaryPath)) {
+  console.error(
+    "caosi: bundled binary is missing. Reinstall with `npm install -g @thomas-huang/caosi` after a GitHub Release exists, or run `npm rebuild @thomas-huang/caosi`."
+  );
+  process.exit(1);
+}
+
+const child = spawn(binaryPath, process.argv.slice(2), {
+  stdio: "inherit"
+});
+
+child.on("exit", (code, signal) => {
+  if (signal) {
+    process.kill(process.pid, signal);
+    return;
+  }
+  process.exit(code ?? 1);
+});
+
+child.on("error", (err) => {
+  console.error(`caosi: failed to start bundled binary: ${err.message}`);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@thomas-huang/caosi",
+  "version": "0.1.0",
+  "description": "Local converter between LLM client protocols and named upstream providers",
+  "license": "MIT",
+  "homepage": "https://github.com/thomas-huang/caosi",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/thomas-huang/caosi.git"
+  },
+  "bugs": {
+    "url": "https://github.com/thomas-huang/caosi/issues"
+  },
+  "bin": {
+    "caosi": "bin/caosi.js"
+  },
+  "files": [
+    "bin/caosi.js",
+    "scripts/postinstall.js",
+    "README.md"
+  ],
+  "scripts": {
+    "postinstall": "node ./scripts/postinstall.js"
+  },
+  "keywords": [
+    "caosi",
+    "llm",
+    "converter",
+    "openai",
+    "claude",
+    "gemini",
+    "anthropic"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}

package/scripts/postinstall.js

@@ -0,0 +1,126 @@
+#!/usr/bin/env node
+
+const crypto = require("node:crypto");
+const fs = require("node:fs");
+const os = require("node:os");
+const path = require("node:path");
+
+const packageRoot = path.join(__dirname, "..");
+const pkg = JSON.parse(fs.readFileSync(path.join(packageRoot, "package.json"), "utf8"));
+const vendorDir = path.join(packageRoot, "vendor");
+
+const repoBaseUrl =
+  process.env.CAOSI_NPM_BASE_URL || "https://github.com/thomas-huang/caosi/releases/download";
+const version = String(pkg.version || "").trim();
+const versionTag = version.startsWith("v") ? version : `v${version}`;
+
+function resolveAssetName() {
+  switch (process.platform) {
+    case "darwin":
+      if (process.arch === "arm64") return "caosi-darwin-arm64";
+      if (process.arch === "x64") return "caosi-darwin-amd64";
+      break;
+    case "linux":
+      if (process.arch === "arm64") return "caosi-linux-arm64";
+      if (process.arch === "x64") return "caosi-linux-amd64";
+      break;
+    case "win32":
+      if (process.arch === "x64") return "caosi-windows-amd64.exe";
+      break;
+    default:
+      break;
+  }
+  throw new Error(`unsupported platform ${process.platform}/${process.arch}`);
+}
+
+function skipDownload() {
+  if (process.env.CAOSI_SKIP_DOWNLOAD === "1") {
+    return "CAOSI_SKIP_DOWNLOAD=1";
+  }
+  if (version === "" || version === "0.0.0-dev" || version === "dev") {
+    return `package version ${version || "(empty)"} has no GitHub Release`;
+  }
+  return "";
+}
+
+async function download(url, destination) {
+  const response = await fetch(url, {
+    headers: {
+      "user-agent": `caosi-npm/${version}`
+    },
+    redirect: "follow"
+  });
+  if (!response.ok) {
+    throw new Error(`download failed for ${url}: HTTP ${response.status}`);
+  }
+  const buf = Buffer.from(await response.arrayBuffer());
+  fs.writeFileSync(destination, buf);
+}
+
+function parseChecksums(text) {
+  const map = new Map();
+  for (const line of text.split(/\r?\n/)) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    const match = trimmed.match(/^([a-f0-9]{64})\s+\*?(.+)$/i);
+    if (!match) {
+      throw new Error(`invalid checksums line: ${line}`);
+    }
+    map.set(match[2], match[1].toLowerCase());
+  }
+  return map;
+}
+
+function sha256(filePath) {
+  const hash = crypto.createHash("sha256");
+  hash.update(fs.readFileSync(filePath));
+  return hash.digest("hex");
+}
+
+async function main() {
+  const reason = skipDownload();
+  if (reason) {
+    console.log(`caosi: skipping binary download (${reason})`);
+    return;
+  }
+
+  const assetName = resolveAssetName();
+  const binaryName = process.platform === "win32" ? "caosi.exe" : "caosi";
+  const targetPath = path.join(vendorDir, binaryName);
+  const checksumsUrl = `${repoBaseUrl}/${versionTag}/checksums.txt`;
+
+  fs.mkdirSync(vendorDir, { recursive: true });
+
+  const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "caosi-npm-"));
+  const checksumsPath = path.join(tempDir, "checksums.txt");
+  const downloadPath = path.join(tempDir, assetName);
+
+  try {
+    console.log(`caosi: downloading ${assetName} for ${process.platform}/${process.arch}`);
+    await download(checksumsUrl, checksumsPath);
+    const checksums = parseChecksums(fs.readFileSync(checksumsPath, "utf8"));
+    const expectedSha = checksums.get(assetName);
+    if (!expectedSha) {
+      throw new Error(`checksums.txt does not contain ${assetName}`);
+    }
+
+    await download(`${repoBaseUrl}/${versionTag}/${assetName}`, downloadPath);
+    const actualSha = sha256(downloadPath);
+    if (actualSha !== expectedSha) {
+      throw new Error(`checksum mismatch for ${assetName}`);
+    }
+
+    fs.copyFileSync(downloadPath, targetPath);
+    if (process.platform !== "win32") {
+      fs.chmodSync(targetPath, 0o755);
+    }
+    console.log(`caosi: installed binary to ${path.relative(packageRoot, targetPath)}`);
+  } finally {
+    fs.rmSync(tempDir, { recursive: true, force: true });
+  }
+}
+
+main().catch((err) => {
+  console.error(`caosi: postinstall failed: ${err.message}`);
+  process.exit(1);
+});