@telepat/snoopy 0.1.12 → 0.1.14

package/README.md

@@ -1,276 +1,112 @@
-<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>
 <p align="center"><em>Sniff out the conversations that matter.</em></p>
 
-[![Build](https://img.shields.io/github/actions/workflow/status/telepat-io/snoopy/ci.yml?branch=main&label=build)](https://github.com/telepat-io/snoopy/actions/workflows/ci.yml)
-[![Coverage](https://codecov.io/gh/telepat-io/snoopy/graph/badge.svg)](https://codecov.io/gh/telepat-io/snoopy)
-[![npm](https://img.shields.io/npm/v/@telepat/snoopy)](https://www.npmjs.com/package/@telepat/snoopy)
+<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>
 
-📖 [Full documentation](https://docs.telepat.io/ideon/)
+<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 helps you monitor Reddit for high-intent conversations 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 posts and comments so you can focus on response and outreach.
 
-## Why Use Snoopy
+## What It Solves
 
 - 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).
+- Track run analytics (discovered, new, qualified items, token usage, cost estimate).
 - Run cross-platform with startup-on-reboot support.
 
-## What It Does
-
-- 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:
+3. Start the background daemon:
 
 ```bash
-snoopy job runs <jobRef>
-```
-
-5. View analytics globally or for one job:
-
-```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>
-```
-
-7. Regenerate qualified results files (all jobs or one job):
-
-```bash
-snoopy export
-snoopy export <jobRef> --json --last-run
-```
-
-8. Consume unconsumed qualified results (read-once, most recent first):
-
-```bash
-snoopy consume
-snoopy consume <jobRef> --limit 10
-snoopy consume <jobRef> --json --dry-run
-```
-
-9. Inspect one run's detailed log output:
-
-```bash
-snoopy logs
-snoopy logs <runId>
-snoopy logs <runId> --raw
+snoopy export --json --last-run
 ```
 
-When `runId` is omitted for `logs`, Snoopy first prompts for a job, then prompts for a run from that job (up/down arrows + Enter).
-
-10. Show recent errors for 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 errors <jobRef>
-```
+## Requirements
 
-11. Enable daemon mode:
+- Node.js 20+
+- npm 10+
+- macOS, Linux, or Windows
 
-```bash
-snoopy daemon start
-snoopy daemon reload
-```
+## How It Works
 
-## 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:
+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
-npm run e2e:smoke
-```
+## Using With AI Agents
 
-Optional env vars:
-- `SNOOPY_E2E_LIMIT` (default `5`)
-- `SNOOPY_E2E_SUBREDDITS` (default `startups,entrepreneur`)
-- `SNOOPY_E2E_KEEP_JOB=true` to skip cleanup for debugging
+Snoopy is built for headless automation and agent-driven monitoring:
 
-## Full Documentation
+- **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.
+- **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.
 
-- [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)
+## Security And Trust
 
-## Docs Site
+- 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.
 
-Serve the Docusaurus docs site locally:
+To report a security issue, open a private report through the repository security flow.
 
-```bash
-npm run docs:start
-```
+## Documentation And Support
 
-Build and preview the static docs site:
+- [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)
 
-```bash
-npm run docs:build
-npm run docs:serve
-```
+## Contributing
 
-Deploy to GitHub Pages:
+Contributions are welcome. See [Development](https://docs.telepat.io/snoopy/contributing/development) for setup, workflow, and quality gates.
 
-```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,112 @@
+<p align="center"><img src="./assets/avatar/snoopy-logo.webp" width="128" alt="Snoopy"></p>
+<h1 align="center">Snoopy</h1>
+<p align="center"><em>嗅出重要的对话。</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 帮助你监控 Reddit，找到与业务目标高度相关的对话。
+
+用自然语言定义你关心的内容，让 Snoopy 创建监控任务，然后持续扫描和评估帖子和评论，让你专注于回复和外联。
+
+## 它能解决什么问题
+
+- 将广泛的 Reddit 流量转化为聚焦的机会流。
+- 一次性定义评估逻辑，然后持续运行。
+- 需要快速验证时触发手动运行。
+- 跟踪运行分析数据（发现、新增、符合条件的项目、token 用量、成本估算）。
+- 跨平台运行，支持开机自启。
+
+## 快速开始
+
+环境要求：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` 生成结构化数据，供下游智能体消费。
+- **直接数据库访问** — 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、生命周期标志和推荐工作流。
+
+## 安全与信任
+
+- 密钥默认保存在 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 {};