@telepat/snoopy 0.1.13 → 0.1.15

package/README.md

@@ -1,10 +1,11 @@
-<p align="center"><img src="./snoopy-logo.webp" width="128" alt="Snoopy"></p>
+<p align="center"><img src="./assets/avatar/snoopy-logo.webp" width="128" alt="Snoopy"></p>
 <h1 align="center">Snoopy</h1>
-<hr>
-<p align="center"><em>Sniff out the conversations that matter.</em></p>
+<p align="center"><em>Monitor online conversations for high-intent signals with AI. Plain language criteria, continuous scanning, zero infrastructure.</em></p>
 
 <p align="center">
   <a href="https://docs.telepat.io/snoopy">📖 Docs</a>
+  · <a href="./README.md">🇺🇸 English</a>
+  · <a href="./README.zh-CN.md">🇨🇳 简体中文</a>
 </p>
 
 <p align="center">
@@ -14,269 +15,123 @@
   <a href="https://github.com/telepat-io/snoopy/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-yellow.svg" alt="License"></a>
 </p>
 
-Snoopy helps you monitor Reddit for high-intent conversations that match your business goals.
+Snoopy monitors online conversations for high-intent signals that match your business goals.
 
-Define what you care about in plain language, let Snoopy create a monitoring job, and continuously scan and qualify posts/comments so you can focus on response and outreach.
+Define what you care about in plain language, let Snoopy create a monitoring job, and continuously scan and qualify conversations so you can focus on response and outreach.
 
-## Why Use Snoopy
+Built for founders, marketers, and sales teams who need to find genuine opportunities in online communities without manually scrolling.
 
-- Turn broad Reddit traffic into a focused stream of opportunities.
-- Define qualification logic once, then run continuously.
-- Trigger manual runs when you want quick validation.
-- Track run analytics (discovered/new/qualified items, token usage, cost estimate).
-- Run cross-platform with startup-on-reboot support.
+## Features
 
-## What It Does
+- **Plain language job creation** — Describe what you're looking for in plain language. Snoopy builds an AI-assisted monitoring job. No regex, no keyword configs.
+- **AI qualification, not keyword matching** — Conversations are evaluated against your intent. Snoopy understands context — not just pattern matching.
+- **Feedback-driven prompt learning** — Review results, submit valid/invalid feedback, and consolidate updates so your qualification prompt gets smarter over time.
+- **Continuous daemon monitoring** — Set a cron schedule and let Snoopy scan in the background. `snoopy daemon start`
+- **Code-driven efficiency** — Deterministic code handles scraping, scheduling, state management, and SQLite persistence. Tokens only spent on qualification.
+- **Local & private** — SQLite database on your machine. No cloud dependency. Export to CSV or JSON on demand.
+- **Cost-aware analytics** — Token usage, cost estimates, and qualified items per run. `snoopy analytics --days 7`
+- **Agent & CI ready** — MCP server, direct SQLite access, non-interactive mode, machine-readable output.
+- **Cross-platform** — macOS, Linux, Windows. Startup-on-reboot. `snoopy startup install`
 
-- Interactive job creation flow from natural-language criteria.
-- AI-assisted clarification and job spec generation.
-- Qualification against your prompt for posts (and comments when enabled).
-- Local SQLite persistence for jobs, runs, and scan items.
-- Built-in daemon for scheduled scanning (cron expressions).
-- On-demand CSV export of qualified results per job.
-- Explicit opt-in startup registration for macOS, Linux, and Windows.
-- Health checks via the doctor command.
-
-## Install
-
-Requirements:
-- Node.js 20+
-- npm 10+
+## Quick Start
 
-From npm:
+Requirements: Node.js 20+, npm 10+.
 
 ```bash
 npm install -g @telepat/snoopy
-snoopy --help
-```
-
-From source:
-
-```bash
-npm install
-npm run build
-npm link
-```
-
-For first-time onboarding (OpenRouter key setup, first `job add`, and verification), see [Installation & Setup](docs/getting-started/installation.md).
-
-## Development
-
-Run without a global install (contributors):
-
-```bash
-npm run dev -- --help
-```
-
-Core validation commands:
-
-```bash
-npm run lint
-npm run build
-npm test
-```
-
-To refresh coverage locally:
-
-```bash
-npm test -- --coverage
 ```
 
-## Releases
-
-Versioning and changelogs are managed automatically by [release-please](https://github.com/googleapis/release-please).
-
-**How it works:**
-1. Merge commits to `main` following [Conventional Commits](https://www.conventionalcommits.org/) (`fix:`, `feat:`, `feat!:`, etc.).
-2. release-please maintains an open "Release PR" that accumulates version bumps and CHANGELOG entries.
-3. Merge the Release PR to cut a release: `package.json` version is bumped, `CHANGELOG.md` is updated, a git tag is created, and the package is published to npm automatically.
-
-**Commit types and semver mapping (while version < 1.0.0):**
-- `fix:` → patch bump
-- `feat:` → patch bump (minor bump is suppressed pre-1.0)
-- `feat!:` or `fix!:` (breaking change) → minor bump (major bump is suppressed pre-1.0)
-
-No manual `git tag` or `npm version` steps are needed.
-
-## Quick Start
-
-Note:
-- Snoopy uses Reddit public JSON endpoints by default.
-- Optional Reddit OAuth fallback credentials can be configured in `snoopy settings` for environments where unauthenticated access is blocked.
-- `snoopy settings` shows a full settings menu so you can jump directly to any setting and save once.
-- If keychain storage is unavailable, configure secrets with environment variables (`SNOOPY_OPENROUTER_API_KEY`, `SNOOPY_REDDIT_CLIENT_SECRET`).
-
-1. Start interactive setup and create your first job:
+1. Create your first monitoring job:
 
 ```bash
 snoopy job add
 ```
 
-`job add` now runs an immediate first scan after saving the job so you can validate results right away.
-Snoopy pauses scheduled scans for that new job during this first run attempt, then enables scheduling when it ends (including interruption/failure cases).
-
-2. List jobs:
-
-```bash
-snoopy jobs list
-```
-
-3. Run one job immediately (limit to 5 new items while testing):
+2. Run a quick test scan:
 
 ```bash
 snoopy job run --limit 5
-snoopy job run <jobRef> --limit 5
-```
-
-If another run is already active for the same job, Snoopy marks the new attempt as `skipped` with an `already active` message.
-Duplicate candidates matching an existing scan item are treated as already scanned and do not fail the run.
-
-If `<jobRef>` is omitted for `job run`, `job enable`, `job disable`, `job delete`, `start`, `stop`, `errors`, or `results`, Snoopy shows your job list and lets you pick with up/down arrows and Enter.
-
-4. View run history:
-
-```bash
-snoopy job runs <jobRef>
 ```
 
-5. View analytics globally or for one job:
+3. Start the background daemon:
 
 ```bash
-snoopy analytics
-snoopy analytics <jobRef>
-snoopy analytics --days 7
+snoopy daemon start
 ```
 
-6. Browse results in the interactive viewer:
+4. View results:
 
 ```bash
 snoopy results
-snoopy results <jobRef>
+snoopy export --json --last-run
 ```
 
-7. Regenerate qualified results files (all jobs or one job):
+For full onboarding, see [Installation & Setup](https://docs.telepat.io/snoopy/getting-started/installation) and [Quick Start](https://docs.telepat.io/snoopy/getting-started/quickstart).
 
-```bash
-snoopy export
-snoopy export <jobRef> --json --last-run
-```
+## Requirements
 
-8. Consume unconsumed qualified results (read-once, most recent first):
+- Node.js 20+
+- npm 10+
+- macOS, Linux, or Windows
 
-```bash
-snoopy consume
-snoopy consume <jobRef> --limit 10
-snoopy consume <jobRef> --json --dry-run
-```
+## How It Works
 
-9. Inspect one run's detailed log output:
+Snoopy uses Reddit public JSON endpoints (with optional OAuth fallback) to scan posts and comments against an AI-assisted qualification prompt. Matches are stored in a local SQLite database. The built-in daemon runs jobs on cron schedules, and results can be exported as CSV or JSON on demand.
 
-```bash
-snoopy logs
-snoopy logs <runId>
-snoopy logs <runId> --raw
-```
+## Using With AI Agents
 
-When `runId` is omitted for `logs`, Snoopy first prompts for a job, then prompts for a run from that job (up/down arrows + Enter).
+Snoopy is built for headless automation and agent-driven monitoring:
 
-10. Show recent errors for one job:
+- **Non-interactive CLI** — Most commands support omitting `<jobRef>` to get an interactive picker, but automation can pass refs directly for zero-prompt execution.
+- **Machine-readable output** — `snoopy export --json --last-run` and `snoopy consume --json` produce structured data for downstream agents.
+- **Feedback loop for continuous quality** — Agents can run `snoopy feedback review --json`, collect human feedback, submit with `snoopy feedback submit`, and finalize with `snoopy feedback consolidate`.
+- **Direct database access** — SQLite at `~/.snoopy/snoopy.db` (or `$SNOOPY_ROOT_DIR/snoopy.db`) with a documented schema. Agents can insert jobs, query results, and update lifecycle flags directly.
+- **Environment variables** — `SNOOPY_OPENROUTER_API_KEY`, `SNOOPY_REDDIT_CLIENT_SECRET`, and `SNOOPY_ROOT_DIR` remove all interactive credential prompts.
+- **Agent docs** — [Agent Operations](https://docs.telepat.io/snoopy/guides/agent-operations) provides a complete runbook for automation, including SQL schema, lifecycle flags, and recommended workflows.
 
-```bash
-snoopy errors <jobRef>
-```
+## Feedback Workflow
 
-11. Enable daemon mode:
+Use the feedback commands to improve qualification quality over time:
 
 ```bash
-snoopy daemon start
-snoopy daemon reload
-```
+# 1) Review unvalidated qualified results (agent-safe JSON)
+snoopy feedback review --json --limit 10
 
-## Most Used Commands
-
-- `job add`
-- `job list`
-- `job run [jobRef] --limit <N>`
-- `job runs [jobRef]`
-- `analytics [jobRef] --days <N>`
-- `results [jobRef]`
-- `export [jobRef] --csv|--json [--last-run]`
-- `consume [jobRef] [--limit <N>] [--json] [--dry-run]`
-- `logs [runId]`
-- `errors [jobRef] --hours <N>`
-- `start [jobRef]` / `stop [jobRef]`
-- `delete [jobRef]`
-- `daemon start|stop|status`
-- `daemon reload`
-- `startup status`
-- `doctor`
-
-## Run Logs
-
-- Each job run writes a dedicated log file under `~/.snoopy/logs/`.
-- Files are named `run-<runId>.log`.
-- `snoopy logs` now supports guided selection (job first, then run) and shows a pretty timeline by default with post/comment text snippets, qualification result + justification, and clickable post/comment links.
-- Use `snoopy logs [runId] --raw` to print the full raw log file content, including full JSON request/response payloads for Reddit and OpenRouter calls.
-- Rich TTY manual runs (`snoopy job run <jobRef>`) show compact multi-line scan blocks with indented fields, clickable links, and qualification justifications.
-- In rich terminals, scan field labels are colorized and qualification status is highlighted (`qualified` in green, `not qualified` in red, `pending` in yellow).
-- Run logs older than 5 days are deleted automatically on daemon startup and after each job run.
-- Deleting a job also deletes all associated per-run log files for that job.
-
-## Results Exports
-
-- Export files are generated on demand with `export`.
-- Files are written under `~/.snoopy/results/`.
-- Each export writes a timestamped file like `<YYYYMMDD-HHmmss>_<job-slug>.<ext>`.
-- Use `--csv` (default) or `--json` to choose output format.
-- Use `--last-run` to export only qualified rows from each job's most recent run.
-- Export files are regenerated from database truth on each export command.
-
-## Live E2E Smoke Test
-
-Use the built-in smoke harness to verify create -> run(5) -> delete:
+# 2) Submit per-result feedback
+snoopy feedback submit <resultId> --valid
+snoopy feedback submit <resultId> --invalid --reason "Not actually a buying signal"
 
-```bash
-npm run e2e:smoke
+# 3) Consolidate feedback into an updated qualification prompt
+snoopy feedback consolidate
 ```
 
-Optional env vars:
-- `SNOOPY_E2E_LIMIT` (default `5`)
-- `SNOOPY_E2E_SUBREDDITS` (default `startups,entrepreneur`)
-- `SNOOPY_E2E_KEEP_JOB=true` to skip cleanup for debugging
+Interactive `snoopy feedback review` sessions also prompt to run consolidation before exiting early.
 
-## Full Documentation
+## Security And Trust
 
-- [Documentation Index](docs/index.md)
-- [Getting Started Overview](docs/getting-started/overview.md)
-- [Installation & Setup](docs/getting-started/installation.md)
-- [Quick Start](docs/getting-started/quickstart.md)
-- [CLI Reference](docs/reference/cli-reference.md)
-- [Database Schema](docs/reference/database-schema.md)
-- [Agent Operations](docs/guides/agent-operations.md)
-- [Scheduling, Cron, Daemon, and Startup](docs/guides/scheduling-and-startup.md)
-- [Security and Secret Storage](docs/technical/security.md)
-- [E2E Smoke Testing Guide](docs/technical/e2e-testing.md)
-- [Contributing](docs/contributing/development.md)
+- Secrets are stored in the OS keychain by default (via `keytar`). Falls back to an encrypted file if keychain is unavailable.
+- Environment variables override stored secrets and are recommended for CI and containerized environments.
+- Reddit OAuth credentials are optional; public JSON endpoints are used by default.
+- Run logs older than 5 days are deleted automatically.
 
-## Docs Site
+To report a security issue, open a private report through the repository security flow.
 
-Serve the Docusaurus docs site locally:
+## Documentation And Support
 
-```bash
-npm run docs:start
-```
+- [Documentation site](https://docs.telepat.io/snoopy)
+- [Installation & Setup](https://docs.telepat.io/snoopy/getting-started/installation)
+- [Quick Start](https://docs.telepat.io/snoopy/getting-started/quickstart)
+- [CLI Reference](https://docs.telepat.io/snoopy/reference/cli-reference)
+- [Agent Operations](https://docs.telepat.io/snoopy/guides/agent-operations)
+- [Scheduling & Daemon](https://docs.telepat.io/snoopy/guides/scheduling-and-startup)
+- [Security](https://docs.telepat.io/snoopy/technical/security)
+- [Repository](https://github.com/telepat-io/snoopy)
+- [npm package](https://www.npmjs.com/package/@telepat/snoopy)
 
-Build and preview the static docs site:
+## Contributing
 
-```bash
-npm run docs:build
-npm run docs:serve
-```
+Contributions are welcome. See [Development](https://docs.telepat.io/snoopy/contributing/development) for setup, workflow, and quality gates.
 
-Deploy to GitHub Pages:
-
-```bash
-GITHUB_OWNER=telepat-io GITHUB_REPO=snoopy npm run docs:deploy
-```
+## License
 
-Docs changes pushed to `main` under `docs/` or `website/` are also rebuilt and published to GitHub Pages automatically via GitHub Actions.
+MIT. See [LICENSE](./LICENSE).

package/README.zh-CN.md

@@ -0,0 +1,137 @@
+<p align="center"><img src="./assets/avatar/snoopy-logo.webp" width="128" alt="Snoopy"></p>
+<h1 align="center">Snoopy</h1>
+<p align="center"><em>使用 AI 监控在线对话中的高意向信号——自然语言标准，持续扫描，零基础设施。</em></p>
+
+<p align="center">
+  <a href="https://docs.telepat.io/snoopy">📖 文档</a>
+  · <a href="./README.md">🇺🇸 English</a>
+  · <a href="./README.zh-CN.md">🇨🇳 简体中文</a>
+</p>
+
+<p align="center">
+  <a href="https://github.com/telepat-io/snoopy/actions/workflows/ci.yml"><img src="https://github.com/telepat-io/snoopy/actions/workflows/ci.yml/badge.svg?branch=main" alt="Build"></a>
+  <a href="https://codecov.io/gh/telepat-io/snoopy"><img src="https://codecov.io/gh/telepat-io/snoopy/graph/badge.svg" alt="Codecov"></a>
+  <a href="https://www.npmjs.com/package/@telepat/snoopy"><img src="https://img.shields.io/npm/v/@telepat/snoopy" alt="npm"></a>
+  <a href="https://github.com/telepat-io/snoopy/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-yellow.svg" alt="License"></a>
+</p>
+
+Snoopy 监控在线对话中的高意向信号，匹配您的业务目标。
+
+用自然语言定义您关心的内容，让 Snoopy 创建监控任务，持续扫描和评估对话，让您专注于回复和外联。
+
+专为需要发现真正机会而无需手动浏览在线社区的创始人、营销人员和销售团队打造。
+
+## 功能特性
+
+- **自然语言任务创建** — 用自然语言描述您正在寻找的内容。Snoopy 构建 AI 辅助的监控任务。无需正则表达式，无需关键字配置。
+- **AI 评估，而非关键词匹配** — 对话会对照您的意图进行评估。Snoopy 理解上下文——不仅仅是模式匹配。
+- **反馈驱动的提示词进化** — 审阅结果、提交有效/无效反馈，并执行 consolidate，让评估提示词随时间持续优化。
+- **持续守护进程监控** — 设置 cron 计划，让 Snoopy 在后台扫描。`snoopy daemon start`
+- **代码驱动的高效率** — 确定性代码处理数据抓取、调度、状态管理和 SQLite 持久化。Token 仅用于评估。
+- **本地化与隐私保护** — SQLite 数据库存储在您的机器上。无云依赖。按需导出为 CSV 或 JSON。
+- **成本感知分析** — 每次运行的 Token 使用量、成本估算和符合条件的项目。`snoopy analytics --days 7`
+- **智能体与 CI 就绪** — MCP 服务器、直接 SQLite 访问、非交互模式、机器可读输出。
+- **跨平台** — macOS、Linux、Windows。支持开机自启。`snoopy startup install`
+
+## 快速开始
+
+环境要求：Node.js 20+、npm 10+。
+
+```bash
+npm install -g @telepat/snoopy
+```
+
+1. 创建第一个监控任务：
+
+```bash
+snoopy job add
+```
+
+2. 运行快速测试扫描：
+
+```bash
+snoopy job run --limit 5
+```
+
+3. 启动后台守护进程：
+
+```bash
+snoopy daemon start
+```
+
+4. 查看结果：
+
+```bash
+snoopy results
+snoopy export --json --last-run
+```
+
+完整入门流程请参阅[安装与设置](https://docs.telepat.io/snoopy/getting-started/installation)和[快速开始](https://docs.telepat.io/snoopy/getting-started/quickstart)。
+
+## 环境要求
+
+- Node.js 20+
+- npm 10+
+- macOS、Linux 或 Windows
+
+## 工作原理
+
+Snoopy 使用 Reddit 公开 JSON 端点（可选 OAuth 回退）扫描帖子和评论，并通过 AI 辅助的评估提示进行匹配。结果存储在本地 SQLite 数据库中。内置守护进程按 cron 表达式运行任务，结果可按需导出为 CSV 或 JSON。
+
+## 与 AI Agent 一起使用
+
+Snoopy 专为无界面自动化和智能体驱动的监控设计：
+
+- **非交互式 CLI** — 大多数命令支持省略 `<jobRef>` 以交互式选择，但自动化可以直接传入 ref 实现零提示执行。
+- **机器可读输出** — `snoopy export --json --last-run` 和 `snoopy consume --json` 生成结构化数据，供下游智能体消费。
+- **持续质量反馈闭环** — 智能体可执行 `snoopy feedback review --json`，收集人工反馈后调用 `snoopy feedback submit`，最后执行 `snoopy feedback consolidate`。
+- **直接数据库访问** — SQLite 位于 `~/.snoopy/snoopy.db`（或 `$SNOOPY_ROOT_DIR/snoopy.db`），拥有完整文档化的 schema。智能体可以直接插入任务、查询结果并更新生命周期标志。
+- **环境变量** — `SNOOPY_OPENROUTER_API_KEY`、`SNOOPY_REDDIT_CLIENT_SECRET` 和 `SNOOPY_ROOT_DIR` 可移除所有交互式凭证提示。
+- **Agent 文档** — [Agent Operations](https://docs.telepat.io/snoopy/guides/agent-operations) 提供完整的自动化手册，包括 SQL schema、生命周期标志和推荐工作流。
+
+## 反馈工作流
+
+使用反馈命令持续提升评估质量：
+
+```bash
+# 1）审阅未验证的合格结果（适合智能体的 JSON）
+snoopy feedback review --json --limit 10
+
+# 2）逐条提交反馈
+snoopy feedback submit <resultId> --valid
+snoopy feedback submit <resultId> --invalid --reason "这不是实际购买意图"
+
+# 3）合并反馈并更新评估提示词
+snoopy feedback consolidate
+```
+
+在交互式 `snoopy feedback review` 中，若提前退出会提示是否先执行 consolidate。
+
+## 安全与信任
+
+- 密钥默认保存在 OS 钥匙串中（通过 `keytar`）。如果钥匙串不可用，则回退到加密文件。
+- 环境变量会覆盖已存储的密钥，推荐用于 CI 和容器化环境。
+- Reddit OAuth 凭证为可选；默认使用公开 JSON 端点。
+- 运行日志超过 5 天会自动删除。
+
+如需报告安全问题，请通过仓库安全报告通道私下提交。
+
+## 文档与支持
+
+- [文档站点](https://docs.telepat.io/snoopy)
+- [安装与设置](https://docs.telepat.io/snoopy/getting-started/installation)
+- [快速开始](https://docs.telepat.io/snoopy/getting-started/quickstart)
+- [CLI 参考](https://docs.telepat.io/snoopy/reference/cli-reference)
+- [Agent Operations](https://docs.telepat.io/snoopy/guides/agent-operations)
+- [调度与守护进程](https://docs.telepat.io/snoopy/guides/scheduling-and-startup)
+- [安全](https://docs.telepat.io/snoopy/technical/security)
+- [仓库](https://github.com/telepat-io/snoopy)
+- [npm 包](https://www.npmjs.com/package/@telepat/snoopy)
+
+## 贡献
+
+欢迎贡献。请参阅[开发指南](https://docs.telepat.io/snoopy/contributing/development)了解环境搭建、工作流和质量门禁。
+
+## 许可证
+
+MIT。详见 [LICENSE](./LICENSE)。

package/dist/src/agent/install.d.ts

@@ -0,0 +1,18 @@
+export type AgentRuntime = 'claude' | 'claude-desktop' | 'chatgpt' | 'gemini' | 'codex' | 'cursor' | 'vscode' | 'opencode' | 'generic-mcp';
+type AgentInstallResult = {
+    runtime: AgentRuntime;
+    installed: boolean;
+    configPath: string;
+    message: string;
+};
+type AgentStatusEntry = {
+    runtime: AgentRuntime;
+    installed: boolean;
+    configPath: string;
+};
+export declare function agentInstall(runtime: string): Promise<AgentInstallResult>;
+export declare function agentUninstall(runtime: string): Promise<AgentInstallResult>;
+export declare function agentStatus(): Promise<{
+    runtimes: AgentStatusEntry[];
+}>;
+export {};