@geekjourneyx/findo 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,9 @@
+# Changelog
+
+## v1.0.0
+
+- Initial stable CLI contract.
+- Add Bocha web search, Volcengine web-grounded answer, and Zhihu search/hotlist adapters.
+- Add JSON envelope, source status, stable error codes, and release gates.
+- Add GitHub Actions CI and tag-triggered cross-platform release builds.
+- Add npm global installer package for the matching GitHub Release binary.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Findo contributors
+
+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,178 @@
+<div align="center">
+
+# Findo
+
+**Search Chinese web sources from one Go CLI.**
+
+<img src="assets/banner.webp" alt="Findo - Chinese web sources from one Go CLI" width="100%">
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](./LICENSE)
+[![Go](https://img.shields.io/badge/Go-1.23+-00ADD8.svg)](./go.mod)
+
+</div>
+
+Findo queries Bocha, Volcengine Ark, and Zhihu through provider APIs, then returns normalized terminal output or automation-safe JSON. It is built for developers, AI agents, and research workflows that need Chinese internet retrieval without scraping, browser sessions, or hidden side effects.
+
+## Install
+
+Recommended:
+
+```bash
+npm install -g @geekjourneyx/findo
+findo version
+```
+
+The npm package installs the matching GitHub Release binary for your platform and verifies it against `SHA256SUMS`.
+
+Alternative Go install:
+
+```bash
+go install github.com/geekjourneyx/findo/cmd/findo@v1.0.0
+```
+
+Prebuilt binaries and checksums are available on the [GitHub Releases](https://github.com/geekjourneyx/findo/releases) page.
+
+From a local checkout:
+
+```bash
+make build
+./findo version
+```
+
+## Configure
+
+Set the credentials for the providers you want to use:
+
+| Provider | Environment variables |
+| --- | --- |
+| Bocha | `BOCHA_API_KEY` |
+| Volcengine Ark | `ARK_API_KEY` or `VOLCENGINE_API_KEY` |
+| Zhihu | `ZHIHU_ACCESS_SECRET` or `ZHIHU_API_KEY` |
+
+Configuration precedence is:
+
+1. CLI flags
+2. Environment variables
+3. Config file
+4. Built-in defaults
+
+## Quick Start
+
+```bash
+findo version
+findo sources --json
+
+BOCHA_API_KEY=... findo bocha "AI Agent 商业化" --json
+ARK_API_KEY=... findo volc "瑞幸咖啡 2026 门店数是否可信" --json
+ZHIHU_ACCESS_SECRET=... findo zhihu "AI 搜索" --json
+ZHIHU_ACCESS_SECRET=... findo zhihu web "ChatGPT 桌面版" --json
+ZHIHU_ACCESS_SECRET=... findo hot zhihu --json
+```
+
+Human output defaults to a table. Use `--json` for scripts, agents, CI, and downstream tools.
+
+## Output
+
+Retrieval commands return a stable envelope. A successful JSON response looks like this:
+
+```json
+{
+  "version": "1.0.0",
+  "query": {
+    "text": "AI Agent 商业化",
+    "mode": "search",
+    "sources": ["bocha_web"],
+    "limit": 10
+  },
+  "status": "ok",
+  "results": [
+    {
+      "source": "bocha_web",
+      "title": "Example result title",
+      "url": "https://example.com/article",
+      "snippet": "A normalized summary from the provider response."
+    }
+  ],
+  "source_status": [
+    {
+      "source": "bocha_web",
+      "status": "ok",
+      "results": 1,
+      "effective_limit": 10,
+      "duration_ms": 842,
+      "error": null
+    }
+  ],
+  "errors": []
+}
+```
+
+Exit codes are part of the public contract:
+
+| Code | Meaning |
+| --- | --- |
+| `0` | Success |
+| `1` | Partial success |
+| `2` | Invalid argument |
+| `3` | Config error |
+| `4` | Credential missing |
+| `5` | Source error |
+| `6` | Timeout |
+| `7` | No results |
+| `9` | Internal error |
+
+## Sources
+
+| Source ID | Command | Provider | Capability |
+| --- | --- | --- | --- |
+| `bocha_web` | `findo bocha` | Bocha | Web search |
+| `volcengine_answer` | `findo volc` | Volcengine Ark | Web-grounded answer |
+| `zhihu_search` | `findo zhihu` | Zhihu | In-site search |
+| `zhihu_web` | `findo zhihu web` | Zhihu | Global web search |
+| `zhihu_hot` | `findo hot zhihu` | Zhihu | Hotlist |
+
+Zhihu global search supports provider-specific filters:
+
+```bash
+findo zhihu web "ChatGPT 桌面版" \
+  --filter 'host=="example.com"' \
+  --search-db realtime \
+  --json
+```
+
+`--filter` and `--search-db` are only valid for `findo zhihu web`.
+
+## Automation Contract
+
+Findo keeps the automation contract narrow and predictable:
+
+- stdout is reserved for results.
+- stderr is reserved for diagnostics.
+- JSON output keeps source IDs, source status, error codes, and exit codes stable.
+- Provider behavior stays behind typed Go adapters.
+- Built-in timeout defaults to `45s`; override it with `--timeout` when a workflow needs a different budget.
+
+## Development
+
+```bash
+make build
+make test
+make lint
+make release-check
+```
+
+The normal test suite does not require real provider credentials. Real API smoke checks are separate:
+
+```bash
+make smoke-bocha
+make smoke-volcengine
+make smoke-zhihu
+```
+
+## Non-Goals
+
+Findo v1.0.0 intentionally does not implement browser scraping, cache, reranking, plugin runtime, MCP, stdin query input, Bocha image search, or Zhihu direct answer. Those boundaries keep the CLI small, testable, and stable.
+
+## License
+
+[MIT](./LICENSE)

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@geekjourneyx/findo",
+  "version": "1.0.0",
+  "description": "Install the findo CLI from the matching GitHub Release bundle.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/geekjourneyx/findo.git"
+  },
+  "homepage": "https://github.com/geekjourneyx/findo#readme",
+  "bugs": {
+    "url": "https://github.com/geekjourneyx/findo/issues"
+  },
+  "bin": {
+    "findo": "scripts/run.js"
+  },
+  "scripts": {
+    "pack:check": "npm pack --json --dry-run",
+    "postinstall": "node scripts/install.js"
+  },
+  "files": [
+    "scripts/install.js",
+    "scripts/run.js",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/scripts/install.js

@@ -0,0 +1,274 @@
+const crypto = require("crypto");
+const fs = require("fs");
+const http = require("http");
+const https = require("https");
+const os = require("os");
+const path = require("path");
+const { execFileSync } = require("child_process");
+const { fileURLToPath } = require("url");
+const zlib = require("zlib");
+
+const pkg = require("../package.json");
+
+const VERSION = pkg.version;
+const REPO = "geekjourneyx/findo";
+const PACKAGE_NAME = pkg.name;
+
+const TARGETS = {
+  darwin: {
+    x64: { goos: "darwin", goarch: "amd64", archive: "tar.gz" },
+    arm64: { goos: "darwin", goarch: "arm64", archive: "tar.gz" },
+  },
+  linux: {
+    x64: { goos: "linux", goarch: "amd64", archive: "tar.gz" },
+    arm64: { goos: "linux", goarch: "arm64", archive: "tar.gz" },
+  },
+  win32: {
+    x64: { goos: "windows", goarch: "amd64", archive: "zip" },
+    arm64: { goos: "windows", goarch: "arm64", archive: "zip" },
+  },
+};
+
+const target = TARGETS[process.platform]?.[process.arch];
+const releaseBaseUrl =
+  process.env.FINDO_RELEASE_BASE_URL ||
+  `https://github.com/${REPO}/releases/download/v${VERSION}`;
+const binaryName = process.platform === "win32" ? "findo.exe" : "findo";
+const binDir = path.join(__dirname, "..", "bin");
+const destination = path.join(binDir, binaryName);
+
+if (!target) {
+  console.error(
+    [
+      `Unsupported platform for ${PACKAGE_NAME}: ${process.platform}-${process.arch}`,
+      "Supported npm install targets are:",
+      "  - darwin-x64",
+      "  - darwin-arm64",
+      "  - linux-x64",
+      "  - linux-arm64",
+      "  - win32-x64",
+      "  - win32-arm64",
+    ].join("\n")
+  );
+  process.exit(1);
+}
+
+const archiveName = `findo_${VERSION}_${target.goos}_${target.goarch}.${target.archive}`;
+
+function hasScheme(value) {
+  return (
+    /^[a-zA-Z][a-zA-Z0-9+.-]*:/.test(value) && !path.win32.isAbsolute(value)
+  );
+}
+
+function resolveAssetLocation(base, name) {
+  if (!hasScheme(base)) {
+    return path.join(base, name);
+  }
+
+  return base.endsWith("/") ? `${base}${name}` : `${base}/${name}`;
+}
+
+function downloadToFile(source, destinationPath) {
+  if (!hasScheme(source)) {
+    fs.copyFileSync(source, destinationPath);
+    return Promise.resolve();
+  }
+
+  if (source.startsWith("file://")) {
+    fs.copyFileSync(fileURLToPath(source), destinationPath);
+    return Promise.resolve();
+  }
+
+  return new Promise((resolve, reject) => {
+    const client = source.startsWith("https:") ? https : http;
+
+    client
+      .get(source, (response) => {
+        if (
+          (response.statusCode === 301 ||
+            response.statusCode === 302 ||
+            response.statusCode === 307 ||
+            response.statusCode === 308) &&
+          response.headers.location
+        ) {
+          response.resume();
+          downloadToFile(response.headers.location, destinationPath).then(
+            resolve,
+            reject
+          );
+          return;
+        }
+
+        if (response.statusCode !== 200) {
+          response.resume();
+          reject(
+            new Error(
+              `download failed with status ${response.statusCode}: ${source}`
+            )
+          );
+          return;
+        }
+
+        const file = fs.createWriteStream(destinationPath);
+        response.pipe(file);
+        file.on("finish", () => file.close(resolve));
+        file.on("error", reject);
+      })
+      .on("error", reject);
+  });
+}
+
+function sha256(filePath) {
+  const hash = crypto.createHash("sha256");
+  hash.update(fs.readFileSync(filePath));
+  return hash.digest("hex");
+}
+
+function expectedChecksum(checksumsPath, filename) {
+  const line = fs
+    .readFileSync(checksumsPath, "utf8")
+    .split(/\r?\n/)
+    .find((entry) => entry.trim().endsWith(` ${filename}`));
+
+  if (!line) {
+    throw new Error(`SHA256SUMS does not contain an entry for ${filename}`);
+  }
+
+  return line.trim().split(/\s+/)[0].toLowerCase();
+}
+
+function extractArchive(archivePath, extractDir) {
+  if (archiveName.endsWith(".tar.gz")) {
+    extractTarGz(archivePath, extractDir);
+    return;
+  }
+
+  if (archiveName.endsWith(".zip") && process.platform === "win32") {
+    const archiveLiteral = powershellSingleQuoted(archivePath);
+    const extractLiteral = powershellSingleQuoted(extractDir);
+    execFileSync("powershell.exe", [
+      "-NoProfile",
+      "-Command",
+      `Expand-Archive -LiteralPath ${archiveLiteral} -DestinationPath ${extractLiteral} -Force`,
+    ]);
+    return;
+  }
+
+  throw new Error(`unsupported archive format for this platform: ${archiveName}`);
+}
+
+function powershellSingleQuoted(value) {
+  return `'${String(value).replace(/'/g, "''")}'`;
+}
+
+function readTarString(buffer, start, length) {
+  return buffer
+    .subarray(start, start + length)
+    .toString("utf8")
+    .replace(/\0.*$/, "");
+}
+
+function extractTarGz(archivePath, extractDir) {
+  const data = zlib.gunzipSync(fs.readFileSync(archivePath));
+  let offset = 0;
+
+  while (offset + 512 <= data.length) {
+    const header = data.subarray(offset, offset + 512);
+    if (header.every((byte) => byte === 0)) {
+      break;
+    }
+
+    const name = readTarString(header, 0, 100);
+    const prefix = readTarString(header, 345, 155);
+    const fullName = prefix ? `${prefix}/${name}` : name;
+    const sizeText = readTarString(header, 124, 12).trim();
+    const size = sizeText ? parseInt(sizeText, 8) : 0;
+    const typeflag = readTarString(header, 156, 1) || "0";
+    const bodyOffset = offset + 512;
+    const nextOffset = bodyOffset + Math.ceil(size / 512) * 512;
+
+    const destinationPath = path.resolve(extractDir, fullName);
+    const extractRoot = path.resolve(extractDir);
+    if (
+      destinationPath !== extractRoot &&
+      !destinationPath.startsWith(`${extractRoot}${path.sep}`)
+    ) {
+      throw new Error(`refusing to extract path outside target directory: ${fullName}`);
+    }
+
+    if (typeflag === "5") {
+      fs.mkdirSync(destinationPath, { recursive: true });
+    } else if (typeflag === "0") {
+      fs.mkdirSync(path.dirname(destinationPath), { recursive: true });
+      fs.writeFileSync(destinationPath, data.subarray(bodyOffset, bodyOffset + size));
+    }
+
+    offset = nextOffset;
+  }
+}
+
+function findBinary(root) {
+  const entries = fs.readdirSync(root, { withFileTypes: true });
+  for (const entry of entries) {
+    const fullPath = path.join(root, entry.name);
+    if (entry.isDirectory()) {
+      const found = findBinary(fullPath);
+      if (found) {
+        return found;
+      }
+    } else if (entry.isFile() && entry.name === binaryName) {
+      return fullPath;
+    }
+  }
+  return "";
+}
+
+async function install() {
+  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "findo-npm-"));
+  const archivePath = path.join(tmpDir, archiveName);
+  const checksumsPath = path.join(tmpDir, "SHA256SUMS");
+  const extractDir = path.join(tmpDir, "extract");
+
+  try {
+    fs.mkdirSync(binDir, { recursive: true });
+    fs.mkdirSync(extractDir, { recursive: true });
+
+    await downloadToFile(
+      resolveAssetLocation(releaseBaseUrl, archiveName),
+      archivePath
+    );
+    await downloadToFile(
+      resolveAssetLocation(releaseBaseUrl, "SHA256SUMS"),
+      checksumsPath
+    );
+
+    const expected = expectedChecksum(checksumsPath, archiveName);
+    const actual = sha256(archivePath);
+    if (expected !== actual) {
+      throw new Error(`checksum mismatch for ${archiveName}`);
+    }
+
+    extractArchive(archivePath, extractDir);
+    const extractedBinary = findBinary(extractDir);
+    if (!extractedBinary) {
+      throw new Error(`archive does not contain ${binaryName}`);
+    }
+
+    fs.copyFileSync(extractedBinary, destination);
+    if (process.platform !== "win32") {
+      fs.chmodSync(destination, 0o755);
+    }
+
+    console.log(
+      `Installed findo ${VERSION} from ${resolveAssetLocation(releaseBaseUrl, archiveName)}`
+    );
+  } finally {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  }
+}
+
+install().catch((error) => {
+  console.error(`Failed to install ${PACKAGE_NAME}: ${error.message}`);
+  process.exit(1);
+});

package/scripts/run.js

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+
+const fs = require("fs");
+const path = require("path");
+const { execFileSync } = require("child_process");
+
+const ext = process.platform === "win32" ? ".exe" : "";
+const binaryPath = path.join(__dirname, "..", "bin", `findo${ext}`);
+
+if (!fs.existsSync(binaryPath)) {
+  console.error(
+    "findo binary is missing. Reinstall with `npm install -g @geekjourneyx/findo`."
+  );
+  process.exit(1);
+}
+
+try {
+  execFileSync(binaryPath, process.argv.slice(2), { stdio: "inherit" });
+} catch (error) {
+  if (typeof error.status === "number") {
+    process.exit(error.status);
+  }
+
+  console.error(`Failed to launch findo: ${error.message}`);
+  process.exit(1);
+}