@shirlytaylor73/smart-search 0.2.0-beta.1

package/npm/scripts/sync-python-version.js

@@ -0,0 +1,22 @@
+const fs = require("node:fs");
+const path = require("node:path");
+
+const packageRoot = path.resolve(__dirname, "..", "..");
+const packageJson = JSON.parse(
+  fs.readFileSync(path.join(packageRoot, "package.json"), "utf8")
+);
+const pyprojectPath = path.join(packageRoot, "pyproject.toml");
+const pyproject = fs.readFileSync(pyprojectPath, "utf8");
+const versionPattern = /^version = ".*"$/m;
+
+if (!versionPattern.test(pyproject)) {
+  console.error("Could not find the project.version field in pyproject.toml.");
+  process.exit(1);
+}
+
+const updated = pyproject.replace(versionPattern, `version = "${packageJson.version}"`);
+if (updated !== pyproject) {
+  fs.writeFileSync(pyprojectPath, updated);
+}
+
+console.log(`Synced pyproject.toml to ${packageJson.version}.`);

package/npm/scripts/test-wrapper-repair.js

@@ -0,0 +1,137 @@
+const assert = require("node:assert");
+const fs = require("node:fs");
+const path = require("node:path");
+const vm = require("node:vm");
+
+const wrapperPath = path.resolve(__dirname, "..", "bin", "smart-search.js");
+const wrapperSource = fs.readFileSync(wrapperPath, "utf8");
+
+function runWrapper({ runtimeExists, repairStatus = 0, repairCreatesRuntime = true }) {
+  let repairedRuntimeExists = runtimeExists;
+  const spawnSyncCalls = [];
+  const spawnCalls = [];
+  const exits = [];
+  const stderr = [];
+
+  const fakeFs = {
+    existsSync(filePath) {
+      const normalized = filePath.replaceAll("\\", "/");
+      if (
+        normalized.endsWith("/.smart-search-python/Scripts/python.exe") ||
+        normalized.endsWith("/.smart-search-python/bin/python")
+      ) {
+        return repairedRuntimeExists;
+      }
+      return fs.existsSync(filePath);
+    }
+  };
+
+  const fakeProcess = {
+    ...process,
+    argv: ["node", wrapperPath, "--version"],
+    env: {},
+    cwd: () => "C:\\caller",
+    exit(code) {
+      exits.push(code);
+      throw new Error(`process.exit(${code})`);
+    },
+    kill() {}
+  };
+
+  const fakeChildProcess = {
+    spawnSync(command, args, options) {
+      spawnSyncCalls.push({ command, args, options });
+      if (repairStatus instanceof Error) {
+        return { error: repairStatus };
+      }
+      if (repairCreatesRuntime) {
+        repairedRuntimeExists = true;
+      }
+      return { status: repairStatus };
+    },
+    spawn(command, args, options) {
+      spawnCalls.push({ command, args, options });
+      return {
+        on() {
+          return this;
+        }
+      };
+    }
+  };
+
+  const context = {
+    __dirname: path.dirname(wrapperPath),
+    console: { error(message = "") { stderr.push(String(message)); }, log() {} },
+    process: fakeProcess,
+    require(moduleName) {
+      if (moduleName === "node:child_process") {
+        return fakeChildProcess;
+      }
+      if (moduleName === "node:fs") {
+        return fakeFs;
+      }
+      if (moduleName === "node:path") {
+        return path;
+      }
+      return require(moduleName);
+    }
+  };
+
+  try {
+    vm.runInNewContext(wrapperSource, context, { filename: wrapperPath });
+  } catch (error) {
+    if (!String(error.message).startsWith("process.exit(")) {
+      throw error;
+    }
+  }
+
+  return { spawnSyncCalls, spawnCalls, exits, stderr };
+}
+
+const healthy = runWrapper({ runtimeExists: true });
+assert.strictEqual(healthy.spawnSyncCalls.length, 0);
+assert.strictEqual(healthy.spawnCalls.length, 1);
+
+const repaired = runWrapper({ runtimeExists: false });
+assert.strictEqual(repaired.spawnSyncCalls.length, 1);
+assert(
+  repaired.spawnSyncCalls[0].args[0].replaceAll("\\", "/").endsWith("/npm/scripts/postinstall.js"),
+  "missing runtime should invoke package postinstall repair"
+);
+assert.strictEqual(repaired.spawnCalls.length, 1);
+assert.deepStrictEqual(Array.from(repaired.spawnCalls[0].args.slice(0, 2)), ["-m", "smart_search.cli"]);
+assert.strictEqual(repaired.exits.length, 0);
+
+const failedRepair = runWrapper({
+  runtimeExists: false,
+  repairStatus: 1,
+  repairCreatesRuntime: false
+});
+assert.strictEqual(failedRepair.spawnSyncCalls.length, 1);
+assert.strictEqual(failedRepair.spawnCalls.length, 0);
+assert.deepStrictEqual(failedRepair.exits, [1]);
+assert(
+  failedRepair.stderr.includes("  npm install -g @shirlytaylor73/smart-search"),
+  "failed repair should recommend reinstalling the stable package"
+);
+assert(
+  !failedRepair.stderr.some((message) => message.includes("@next")),
+  "failed repair should not recommend the next release tag"
+);
+
+const repairSpawnError = runWrapper({
+  runtimeExists: false,
+  repairStatus: new Error("postinstall unavailable"),
+  repairCreatesRuntime: false
+});
+assert.strictEqual(repairSpawnError.spawnSyncCalls.length, 1);
+assert.strictEqual(repairSpawnError.spawnCalls.length, 0);
+assert.deepStrictEqual(repairSpawnError.exits, [5]);
+assert(
+  repairSpawnError.stderr.includes("  npm install -g @shirlytaylor73/smart-search"),
+  "repair spawn errors should recommend reinstalling the stable package"
+);
+assert(
+  !repairSpawnError.stderr.some((message) => message.includes("@next")),
+  "repair spawn errors should not recommend the next release tag"
+);

package/npm/scripts/test.js

@@ -0,0 +1,76 @@
+const { spawnSync } = require("node:child_process");
+const fs = require("node:fs");
+const path = require("node:path");
+
+const packageRoot = path.resolve(__dirname, "..", "..");
+const venvDir = path.join(packageRoot, ".smart-search-python");
+const pythonPath =
+  process.platform === "win32"
+    ? path.join(venvDir, "Scripts", "python.exe")
+    : path.join(venvDir, "bin", "python");
+
+function run(command, args, options = {}) {
+  const result = spawnSync(command, args, {
+    cwd: packageRoot,
+    stdio: "inherit",
+    shell: options.shell || false,
+    windowsHide: true
+  });
+  if (result.error) {
+    console.error(result.error.message);
+    process.exit(1);
+  }
+  if (result.status !== 0) {
+    process.exit(result.status || 1);
+  }
+}
+
+function capture(command, args) {
+  const result = spawnSync(command, args, {
+    cwd: packageRoot,
+    encoding: "utf8",
+    windowsHide: true
+  });
+  if (result.error) {
+    console.error(result.error.message);
+    process.exit(1);
+  }
+  if (result.status !== 0) {
+    process.stdout.write(result.stdout || "");
+    process.stderr.write(result.stderr || "");
+    process.exit(result.status || 1);
+  }
+  return result.stdout || "";
+}
+
+function runNpm(args) {
+  if (process.env.npm_execpath) {
+    run(process.execPath, [process.env.npm_execpath, ...args]);
+    return;
+  }
+  run("npm", args, { shell: process.platform === "win32" });
+}
+
+if (!fs.existsSync(pythonPath)) {
+  console.error("Missing .smart-search-python runtime. Run npm install first.");
+  process.exit(1);
+}
+
+run(pythonPath, ["-m", "pip", "install", "--disable-pip-version-check", "-e", ".[dev]"]);
+run(pythonPath, ["-m", "pytest"]);
+run(process.execPath, ["npm/scripts/test-wrapper-repair.js"]);
+run(process.execPath, ["npm/bin/smart-search.js", "--help"]);
+const routeJson = capture(process.execPath, [
+  "npm/bin/smart-search.js",
+  "diagnose",
+  "route",
+  "深度搜索一下最近的比特币行情",
+  "--format",
+  "json"
+]);
+const routeResult = JSON.parse(routeJson);
+if (routeResult.query !== "深度搜索一下最近的比特币行情") {
+  console.error("npm wrapper must preserve non-ASCII CLI arguments and JSON output as UTF-8.");
+  process.exit(1);
+}
+runNpm(["pack", "--dry-run"]);

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@shirlytaylor73/smart-search",
+  "version": "0.2.0-beta.1",
+  "description": "CLI-first provider-independent web and documentation retrieval for AI agents.",
+  "license": "MIT",
+  "homepage": "https://github.com/ShirlyTaylor73/smartsearch#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ShirlyTaylor73/smartsearch.git"
+  },
+  "bugs": {
+    "url": "https://github.com/ShirlyTaylor73/smartsearch/issues"
+  },
+  "bin": {
+    "smart-search": "npm/bin/smart-search.js"
+  },
+  "files": [
+    "npm/",
+    "skills/smart-search-cli/**",
+    "src/smart_search/**/*.py",
+    "src/smart_search/assets/skills/smart-search-cli/**",
+    "pyproject.toml",
+    "README.md",
+    "README.zh-CN.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "postinstall": "node npm/scripts/postinstall.js",
+    "test": "node npm/scripts/test.js",
+    "set-version": "node npm/scripts/set-package-version.js",
+    "sync:python-version": "node npm/scripts/sync-python-version.js",
+    "version": "node npm/scripts/sync-python-version.js && git add pyproject.toml package.json package-lock.json",
+    "pack:dry": "npm pack --dry-run",
+    "publish:dry": "npm publish --dry-run --access public"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/pyproject.toml

@@ -0,0 +1,36 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "smart-search"
+version = "0.2.0-beta.1"
+description = "CLI-first provider-independent web and documentation retrieval for AI agents."
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+    "httpx[socks]>=0.28.0",
+    "InquirerPy>=0.3.4,<0.4",
+    "pyfiglet>=1.0,<2",
+    "rich>=13.9,<16",
+    "tenacity>=8.0.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0.0",
+    "pytest-asyncio>=0.23.0",
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+smart_search = [
+    "assets/skills/smart-search-cli/SKILL.md",
+    "assets/skills/smart-search-cli/agents/*.yaml",
+    "assets/skills/smart-search-cli/references/*.md",
+]
+
+[project.scripts]
+smart-search = "smart_search.cli:main"

package/skills/smart-search-cli/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: smart-search-cli
+description: "CLI-first web and documentation retrieval through four provider-independent capability namespaces."
+---
+
+# Smart Search CLI
+
+Use the local `smart-search` command. Choose an operation by task intent; never choose or manage providers.
+
+## Query operations
+
+- `smart-search search answer QUERY --format json`: generate a web-backed answer.
+- `smart-search search sources QUERY --limit 5 --format json`: retrieve source-first web results.
+- `smart-search search similar URL --limit 5 --format json`: find similar pages.
+- `smart-search docs resolve NAME [QUERY] --format json`: resolve a library/documentation source.
+- `smart-search docs search QUERY [--source SOURCE] --format json`: search technical docs or repository knowledge.
+- `smart-search docs tree REPO [--path PATH] [--ref REF] --format json`: inspect repository structure.
+- `smart-search docs read REPO PATH [--ref REF] --format content`: read a repository file.
+- `smart-search fetch content URL --format content`: retrieve readable page/PDF content.
+- `smart-search fetch extract URL --format json`: retrieve structured data or raw evidence.
+- `smart-search map site URL --limit 50 --format json`: discover URLs and link structure within a site.
+
+## Selection rules
+
+- Use `search answer` for a direct current-web answer.
+- Use `search sources` when the agent needs candidate URLs or filtering.
+- Use `docs` for libraries, APIs, SDKs, repositories, directory trees, and files.
+- Use `fetch content` after a URL is known and readable evidence is required.
+- Use `fetch extract` only when structured fields/evidence are required.
+- Use `map site` only for site URL discovery; it is not page extraction or repository structure.
+
+Provider selection, credentials, ordering, feature matching, timeout, and fallback are configuration concerns and MUST NOT be managed by the agent.
+
+## Output and errors
+
+- Default to `--format json` for results and `--format content` for long readable bodies.
+- Treat `config_error` as a maintainer configuration issue.
+- Treat `capability_error` as an unsupported operation/feature combination; do not retry with provider-specific commands.
+- Use `doctor` or `diagnose` only when the user explicitly asks for troubleshooting.
+
+The calling agent owns research orchestration; future paper/vertical retrieval is handled separately.

package/skills/smart-search-cli/agents/openai.yaml

@@ -0,0 +1,3 @@
+display_name: Smart Search CLI
+short_description: Source-backed web research via CLI
+default_prompt: Use $smart-search-cli to research this current web question.

package/skills/smart-search-cli/references/cli-contract.md

@@ -0,0 +1,7 @@
+# CLI Contract
+
+Public query namespaces are `search`, `docs`, `fetch`, and `map`.
+
+Operations: `search answer|sources|similar`, `docs resolve|search|tree|read`, `fetch content|extract`, and `map site`.
+
+All operations return `ok`, `capability`, `operation`, `content`, `sources`, and `elapsed_ms`; failures add `error_type` and `error`. Provider details are debug-only.

package/skills/smart-search-cli/references/cli-core.md

@@ -0,0 +1,5 @@
+# CLI Core
+
+Use operation names to express task intent. Do not select providers or fallback paths. Use JSON for structured results and content format for long bodies.
+
+Research planning, decomposition, evidence comparison, and final writing belong to the calling agent.

package/skills/smart-search-cli/references/command-patterns.md

@@ -0,0 +1,12 @@
+# Command Patterns
+
+```bash
+smart-search search answer "QUESTION" --format json
+smart-search search sources "QUERY" --limit 5 --format json
+smart-search docs search "QUERY" --source owner/repo --format json
+smart-search docs tree owner/repo --path src --format json
+smart-search docs read owner/repo README.md --format content
+smart-search fetch content URL --format content
+smart-search fetch extract URL --format json
+smart-search map site URL --limit 50 --format json
+```

package/skills/smart-search-cli/references/provider-routing.md

@@ -0,0 +1,3 @@
+# Operation Routing
+
+Provider ordering, supported features, timeouts, credentials, and fallback are configured internally per operation. Fallback never crosses operation boundaries: tree is not search, structured extract is not readable content, and site map is not repository structure.

package/skills/smart-search-cli/references/regression-release.md

@@ -0,0 +1,28 @@
+# Regression and Release
+
+Maintainers run `smart-search dev regression`, relevant pytest suites,
+`npm test`, and verify that the public and packaged skill directories are
+byte-identical before release.
+
+## Release Lanes
+
+- The fork-owned package is `@shirlytaylor73/smart-search`.
+- Beta releases are started manually with `workflow_dispatch`, an exact
+  `0.2.0-beta.N` version, and npm dist-tag `next`.
+- Stable `v0.2.0` and later `vX.Y.Z` Git tags publish npm dist-tag
+  `latest`.
+- GitHub Actions authenticates with the repository secret `NPM_TOKEN` and
+  publishes with npm provenance.
+- Stable release notes live at `.github/releases/vX.Y.Z.md`.
+- npm versions are immutable; published versions cannot be renamed in place.
+
+## Release Verification
+
+- Confirm package metadata and tags with
+  `npm view @shirlytaylor73/smart-search --json`.
+- Install the exact beta or stable package and run
+  `smart-search --version`, `smart-search dev regression`, and
+  `smart-search diagnose smoke --mode mock --format json`.
+- Verify the Windows npm/mise wrapper emits UTF-8 JSON with a non-ASCII query
+  piped through `ConvertFrom-Json`.
+

package/skills/smart-search-cli/references/setup-config.md

@@ -0,0 +1,3 @@
+# Setup and Configuration
+
+Maintainers use `smart-search setup`, `config`, `doctor`, and `diagnose`. Agents must not modify credentials, operation provider order, feature support, or fallback configuration.

package/src/smart_search/__init__.py

@@ -0,0 +1 @@
+__all__ = []

package/src/smart_search/assets/skills/smart-search-cli/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: smart-search-cli
+description: "CLI-first web and documentation retrieval through four provider-independent capability namespaces."
+---
+
+# Smart Search CLI
+
+Use the local `smart-search` command. Choose an operation by task intent; never choose or manage providers.
+
+## Query operations
+
+- `smart-search search answer QUERY --format json`: generate a web-backed answer.
+- `smart-search search sources QUERY --limit 5 --format json`: retrieve source-first web results.
+- `smart-search search similar URL --limit 5 --format json`: find similar pages.
+- `smart-search docs resolve NAME [QUERY] --format json`: resolve a library/documentation source.
+- `smart-search docs search QUERY [--source SOURCE] --format json`: search technical docs or repository knowledge.
+- `smart-search docs tree REPO [--path PATH] [--ref REF] --format json`: inspect repository structure.
+- `smart-search docs read REPO PATH [--ref REF] --format content`: read a repository file.
+- `smart-search fetch content URL --format content`: retrieve readable page/PDF content.
+- `smart-search fetch extract URL --format json`: retrieve structured data or raw evidence.
+- `smart-search map site URL --limit 50 --format json`: discover URLs and link structure within a site.
+
+## Selection rules
+
+- Use `search answer` for a direct current-web answer.
+- Use `search sources` when the agent needs candidate URLs or filtering.
+- Use `docs` for libraries, APIs, SDKs, repositories, directory trees, and files.
+- Use `fetch content` after a URL is known and readable evidence is required.
+- Use `fetch extract` only when structured fields/evidence are required.
+- Use `map site` only for site URL discovery; it is not page extraction or repository structure.
+
+Provider selection, credentials, ordering, feature matching, timeout, and fallback are configuration concerns and MUST NOT be managed by the agent.
+
+## Output and errors
+
+- Default to `--format json` for results and `--format content` for long readable bodies.
+- Treat `config_error` as a maintainer configuration issue.
+- Treat `capability_error` as an unsupported operation/feature combination; do not retry with provider-specific commands.
+- Use `doctor` or `diagnose` only when the user explicitly asks for troubleshooting.
+
+The calling agent owns research orchestration; future paper/vertical retrieval is handled separately.

package/src/smart_search/assets/skills/smart-search-cli/agents/openai.yaml

@@ -0,0 +1,3 @@
+display_name: Smart Search CLI
+short_description: Source-backed web research via CLI
+default_prompt: Use $smart-search-cli to research this current web question.

package/src/smart_search/assets/skills/smart-search-cli/references/cli-contract.md

@@ -0,0 +1,7 @@
+# CLI Contract
+
+Public query namespaces are `search`, `docs`, `fetch`, and `map`.
+
+Operations: `search answer|sources|similar`, `docs resolve|search|tree|read`, `fetch content|extract`, and `map site`.
+
+All operations return `ok`, `capability`, `operation`, `content`, `sources`, and `elapsed_ms`; failures add `error_type` and `error`. Provider details are debug-only.

package/src/smart_search/assets/skills/smart-search-cli/references/cli-core.md

@@ -0,0 +1,5 @@
+# CLI Core
+
+Use operation names to express task intent. Do not select providers or fallback paths. Use JSON for structured results and content format for long bodies.
+
+Research planning, decomposition, evidence comparison, and final writing belong to the calling agent.

package/src/smart_search/assets/skills/smart-search-cli/references/command-patterns.md

@@ -0,0 +1,12 @@
+# Command Patterns
+
+```bash
+smart-search search answer "QUESTION" --format json
+smart-search search sources "QUERY" --limit 5 --format json
+smart-search docs search "QUERY" --source owner/repo --format json
+smart-search docs tree owner/repo --path src --format json
+smart-search docs read owner/repo README.md --format content
+smart-search fetch content URL --format content
+smart-search fetch extract URL --format json
+smart-search map site URL --limit 50 --format json
+```

package/src/smart_search/assets/skills/smart-search-cli/references/provider-routing.md

@@ -0,0 +1,3 @@
+# Operation Routing
+
+Provider ordering, supported features, timeouts, credentials, and fallback are configured internally per operation. Fallback never crosses operation boundaries: tree is not search, structured extract is not readable content, and site map is not repository structure.

package/src/smart_search/assets/skills/smart-search-cli/references/regression-release.md

@@ -0,0 +1,28 @@
+# Regression and Release
+
+Maintainers run `smart-search dev regression`, relevant pytest suites,
+`npm test`, and verify that the public and packaged skill directories are
+byte-identical before release.
+
+## Release Lanes
+
+- The fork-owned package is `@shirlytaylor73/smart-search`.
+- Beta releases are started manually with `workflow_dispatch`, an exact
+  `0.2.0-beta.N` version, and npm dist-tag `next`.
+- Stable `v0.2.0` and later `vX.Y.Z` Git tags publish npm dist-tag
+  `latest`.
+- GitHub Actions authenticates with the repository secret `NPM_TOKEN` and
+  publishes with npm provenance.
+- Stable release notes live at `.github/releases/vX.Y.Z.md`.
+- npm versions are immutable; published versions cannot be renamed in place.
+
+## Release Verification
+
+- Confirm package metadata and tags with
+  `npm view @shirlytaylor73/smart-search --json`.
+- Install the exact beta or stable package and run
+  `smart-search --version`, `smart-search dev regression`, and
+  `smart-search diagnose smoke --mode mock --format json`.
+- Verify the Windows npm/mise wrapper emits UTF-8 JSON with a non-ASCII query
+  piped through `ConvertFrom-Json`.
+

package/src/smart_search/assets/skills/smart-search-cli/references/setup-config.md

@@ -0,0 +1,3 @@
+# Setup and Configuration
+
+Maintainers use `smart-search setup`, `config`, `doctor`, and `diagnose`. Agents must not modify credentials, operation provider order, feature support, or fallback configuration.