@stephenyang/stephen 0.1.0 → 0.1.1

package/README.md

@@ -1,377 +1,572 @@
 # stephen
 
-`stephen` is a personal TypeScript CLI built for agent-friendly workflows first and interactive terminal use second.
+`stephen` is a personal TypeScript CLI for scriptable, agent-friendly workflows. It returns structured JSON by default and provides table output for list-style commands when human inspection is more convenient.
 
-The current flagship command is `ak`, a local API key manager. The CLI also includes a conservative Windows disk cleanup command for low-risk cache cleanup.
+Current npm package:
 
-Roadmap work is underway for a new `video` command group focused on browser-assisted media detection, media downloads, and local video compression.
+```bash
+npm install -g @stephenyang/stephen
+```
+
+After installation:
 
-`ak` provides:
+```bash
+stephen --help
+```
 
-- SQLite-backed local storage
-- encrypted key persistence
-- `sha1(key)` record IDs for compatibility with existing backend lookup behavior
-- JSON-first output for scripts and agents
-- table output for human inspection
-- deterministic command contracts and exit codes
+## Command Overview
 
-## Design Philosophy
+```text
+stephen ak       Manage local API key records
+stephen config   Manage local CLI configuration
+stephen disk     Preview or run conservative disk cleanup
+stephen video    Sniff, download, and compress video media
+stephen 36kr     Fetch 36kr article details and channel lists
+stephen toutiao  Fetch Toutiao channels, searches, author feeds, and article details
+stephen hn       Fetch Hacker News top/new/best/search lists
+```
 
-`stephen` follows a few strong rules:
+Output rules:
 
-- Machine-readable by default: commands return JSON unless table mode is explicitly requested.
-- Local-first: commands should work offline and avoid unnecessary remote coupling.
-- Secrets stay protected: sensitive values are encrypted at rest and masked in normal output.
-- Small, composable layers: parsing, domain logic, storage, and rendering should stay separate.
-- Test before behavior: production behavior is expected to be developed with TDD.
+- JSON is the default output format. Successful responses usually look like `{ "ok": true, "data": ... }`.
+- Errors are rendered as JSON, usually `{ "ok": false, "error": { "code": "...", "message": "..." } }`.
+- List and summary commands support `-t` / `--table`, equivalent to `--format table`.
+- Detail commands stay JSON-only so downstream scripts can consume the full structure.
 
-## Project Layout
+## Requirements
 
-```text
-src/   source code
-docs/  local design notes and references
-tests/ automated tests
+- Node.js 22+
+- npm
+- `curl`: used by `36kr` with browser-like request headers
+- Playwright Chromium: required by `toutiao` and browser-based `video` sniffing
+- `ffmpeg`: required by `video compress`
+
+Install the Playwright browser:
+
+```bash
+npx playwright install chromium
 ```
 
-Key modules for `ak`:
+## `ak` API Key Manager
 
-- `src/ak/schema.ts`: validation, field parsing, and masking helpers
-- `src/ak/crypto.ts`: SHA-1 IDs, prefix indexing, and encryption helpers
-- `src/ak/runtime.ts`: local config loading and storage path resolution
-- `src/ak/repository.ts`: SQLite persistence
-- `src/ak/service.ts`: orchestration and domain behavior
-- `src/ak/output.ts`: JSON and table rendering
-- `src/ak/command.ts`: Commander-based CLI wiring
+`ak` stores API key records in a local SQLite database. Keys are encrypted at rest and masked by default in normal output. Record IDs are generated as `sha1(key)`, so records can be retrieved by either ID or original key.
 
-Key modules for `disk cleanup`:
+Record fields:
 
-- `src/disk/types.ts`: shared report shapes
-- `src/disk/runtime.ts`: filesystem and process integration
-- `src/disk/service.ts`: conservative cleanup orchestration
-- `src/disk/output.ts`: JSON and table rendering
-- `src/disk/command.ts`: Commander-based CLI wiring
+```text
+env
+userId
+userName
+email
+phone
+key
+```
 
-## Getting Started
+Recommended environment names:
 
-Requirements:
+```text
+bzy-pre
+bzy-prod
+op-pre
+op-prod
+gitee
+github
+gitlab
+```
 
-- Node.js 22+
-- npm
+Custom machine-friendly `env` values are also supported.
 
-Install dependencies:
+### Common Commands
+
+Add a record:
 
 ```bash
-npm install
+stephen ak add -e github -k ghp_xxx -n Stephen -m stephen@example.com
 ```
 
-Run tests:
+Get a record by key or ID:
 
 ```bash
-npm test
+stephen ak get -e github -k ghp_xxx
+stephen ak get --id fdb441954fd4573a72fb5a52ce359e0d77c3fa0e
 ```
 
-Run coverage:
+List records:
 
 ```bash
-npm run coverage
+stephen ak list
+stephen ak list -e github
+stephen ak list -q ste -f userName,email
+stephen ak list -q ghp_ -f key -t
 ```
 
-Build the CLI:
+Update metadata:
 
 ```bash
-npm run build
+stephen ak update -e github -k ghp_xxx -n StephenYang
+stephen ak update --id fdb441954fd4573a72fb5a52ce359e0d77c3fa0e -m new@example.com
 ```
 
-## Roadmap
+Delete a record:
 
-Planned next major capability: `video`
+```bash
+stephen ak delete --id fdb441954fd4573a72fb5a52ce359e0d77c3fa0e --yes
+```
 
-- `video sniff`: inspect a page or media URL and return candidate downloadable video resources in JSON by default
-- `video download`: download supported media inputs including page URLs, `m3u8` streams, and direct `mp4` links
-- `video compress`: compress local video with `ffmpeg`
+### `ak` Options
 
-Current direction for `video`:
+```text
+-e, --env <env>             Environment
+-u, --user-id <userId>      User ID
+-n, --user-name <userName>  User name
+-m, --email <email>         Email
+-p, --phone <phone>         Phone number
+-k, --key <key>             API key
+-q, --query <query>         Fuzzy query
+-f, --field <field>         Search fields, comma-separated
+--id <id>                   Record ID
+--limit <limit>             List limit, default 50, max 100
+--raw-key                   Show the full key
+--format <json|table>       Output format
+-t, --table                 Table output
+```
 
-- browser-first detection for sites that only reveal media requests during real page execution
-- HTTP-based fallback detection for simpler pages and direct media links
-- a unified candidate model so `sniff` and `download` can handle `m3u8` and `mp4` consistently
-- `ffmpeg`-backed compression with default `mp4` output, `h265` video, `aac` audio, and `64k` default audio bitrate
-- explicit parameter support for resolution, video bitrate, audio bitrate, concurrency, request headers, and output selection
+Query rules:
 
-Planned defaults:
+- `userId`, `userName`, `email`, and `phone` support fuzzy search.
+- `key` search only supports low-sensitivity prefix matching.
+- Keys are masked unless `--raw-key` is passed.
 
-- JSON output first, with optional table mode when it improves readability
-- `video sniff` mode default: `auto`, preferring browser-based detection before HTTP fallback
-- `video compress` output default: `mp4`
-- `video compress` video codec default: `h265`
-- `video compress` audio codec default: `aac`
-- `video compress` audio bitrate default: `64k`
-- resolution unchanged unless the user passes an explicit resize option
+## `config` Local Configuration
 
-Supporting documents:
+`config` manages local machine configuration. Currently supported key:
 
-- [2026-04-27-video-command-solution-report.md](/D:/Development/Stephen/PersonalCli/docs/2026-04-27-video-command-solution-report.md)
-- [2026-04-27-video-command-implementation-plan.md](/D:/Development/Stephen/PersonalCli/docs/2026-04-27-video-command-implementation-plan.md)
+```text
+ak.dbPath
+```
 
-## `ak` Command
+List all config entries:
 
-The `ak` command manages API key records with these fields:
+```bash
+stephen config list
+stephen config list -t
+```
 
-- `env`
-- `userId`
-- `userName`
-- `email`
-- `phone`
-- `key`
+Get one config entry:
 
-Recommended environments:
+```bash
+stephen config get ak.dbPath
+```
 
-- `bzy-pre`
-- `bzy-prod`
-- `op-pre`
-- `op-prod`
-- `gitee`
-- `github`
-- `gitlab`
+Set the API key database path:
 
-`env` now accepts custom machine-friendly values. The built-in values above remain the recommended defaults and are shown in CLI help and validation messages.
+```bash
+stephen config set ak.dbPath /Users/stephen/iDrive/stephen/ak.db
+```
 
-### Examples
+`ak.dbPath` resolution priority:
 
-Add a record:
+1. Local config file value `ak.dbPath`
+2. `STEPHEN_AK_DB_PATH`
+3. Legacy environment variable `STEPHEN_CLI_AK_DB_PATH`
+4. Default `env-paths` data directory
+
+## `disk cleanup`
+
+`disk cleanup` provides conservative Windows disk cleanup. It previews by default and does not delete anything unless `--apply` is passed.
+
+Cleanup levels:
+
+```text
+safe    Default level for common safe caches
+dev     safe + common developer caches
+system  safe + Windows system cleanup actions; apply mode requires --confirm
+deep    dev + system, and reports the largest 100 Downloads entries without deleting them
+```
+
+Common commands:
 
 ```bash
-stephen ak add -e bzy-pre -k op_sk_abcdef123456 -n Stephen
-stephen ak add -e team-a-prod -k op_sk_abcdef123456 -n Stephen
+stephen disk cleanup
+stephen disk cleanup -t
+stephen disk cleanup --level dev
+stephen disk cleanup --level deep
+stephen disk cleanup --apply
+stephen disk cleanup --level system --apply --confirm
+stephen disk cleanup --apply --disable-hibernate
 ```
 
-Get a record:
+Notes:
+
+- `--apply` is required before cleanup actions are executed.
+- `system` and `deep` require `--confirm` in apply mode.
+- Downloads is never deleted; `deep` only reports the largest files and directories for manual review.
+
+## `video`
+
+`video` can sniff video candidates from pages or media URLs, download `mp4` / `m3u8`, and compress local videos with `ffmpeg`.
+
+### Sniff
 
 ```bash
-stephen ak get -e bzy-pre -k op_sk_abcdef123456
-stephen ak get --id fdb441954fd4573a72fb5a52ce359e0d77c3fa0e
+stephen video sniff https://example.com/watch/123
+stephen video sniff https://example.com/watch/123 -t
+stephen video sniff https://example.com/watch/123 --mode browser
+stephen video sniff https://cdn.example.com/video.mp4 --mode http
 ```
 
-List records:
+Modes:
+
+```text
+auto     Default; try browser sniffing first, then HTTP fallback
+browser  Use Playwright to capture page network requests
+http     Inspect direct URLs, HTML, and scripts without browser execution
+```
+
+Proxy examples:
 
 ```bash
-stephen ak list -e bzy-pre
-stephen ak list -q ste -f userName,email
-stephen ak list -q op_sk_ab -f key -t
+stephen video sniff https://example.com/watch/123 --proxy http://127.0.0.1:7890
+stephen video sniff https://example.com/watch/123 --skip-proxy
 ```
 
-Update metadata:
+### Download
 
 ```bash
-stephen ak update -e bzy-pre -k op_sk_abcdef123456 -m new@example.com
+stephen video download https://cdn.example.com/video.mp4
+stephen video download https://cdn.example.com/master.m3u8
+stephen video download https://example.com/watch/123 --mode browser
+stephen video download https://example.com/watch/123 --output-dir ./downloads
 ```
 
-Delete a record:
+Download behavior:
+
+- Direct `mp4` URLs are downloaded directly.
+- `m3u8` playlists are fetched with their segments and merged into one output.
+- Page URLs are sniffed first, then a compatible candidate is downloaded.
+
+### Compress
 
 ```bash
-stephen ak delete --id fdb441954fd4573a72fb5a52ce359e0d77c3fa0e --yes
+stephen video compress ./input.mov
+stephen video compress ./input.mov --output-path ./output.mp4
+stephen video compress ./input.mov --resolution 1280x720
+stephen video compress ./input.mov --video-bitrate 1800k --audio-bitrate 64k
+stephen video compress ./input.mov -t
+```
+
+Default compression settings:
+
+```text
+container      mp4
+video codec    libx265
+audio codec    aac
+audio bitrate  64k
 ```
 
-### Output Rules
+## `36kr`
 
-- Default output is JSON.
-- `-t` or `--format table` switches to table rendering.
-- `--raw-key` shows the full key.
-- Without `--raw-key`, the key is masked.
+`36kr` uses curl to request 36kr pages and pagination APIs with browser-like headers. It supports article details and two information channels.
 
-### Query Rules
+### Article Details
 
-- `-q` / `--query` enables fuzzy search
-- `-f` / `--field` selects searchable fields
-- fuzzy search is supported for `userId`, `userName`, `email`, and `phone`
-- `key` search is prefix-based only through a low-sensitivity prefix index
+Pass the article ID; the CLI builds the article detail URL:
+
+```bash
+stephen 36kr article 3853011900142848
+```
 
-### Short Flags
+Output includes:
 
-- `-e` => `--env`
-- `-u` => `--user-id`
-- `-n` => `--user-name`
-- `-m` => `--email`
-- `-p` => `--phone`
-- `-k` => `--key`
-- `-q` => `--query`
-- `-f` => `--field`
-- `-t` => table output
+```text
+id
+url
+title
+summary
+author
+publishTime
+content.html
+content.paragraphs
+coverImage
+images
+imageSources
+stats
+organizations
+newestArticles
+relatedArticles
+latestArticles
+nextArticle
+request
+```
 
-## Storage Model
+### Channel Lists
 
-Runtime storage uses local SQLite. The full key is encrypted before persistence, while a small prefix index supports limited prefix search for `key`.
+Supported channels:
 
-The database path resolves in this order:
+```text
+AI
+technology
+```
 
-1. local config file `<config dir>/config.json` with `ak.dbPath`
-2. `STEPHEN_AK_DB_PATH`
-3. legacy `STEPHEN_CLI_AK_DB_PATH`
-4. default `env-paths` data directory
+Examples:
 
-This keeps `ak` local-first while letting each machine point to a different synced directory such as iDrive.
+```bash
+stephen 36kr list AI
+stephen 36kr list technology --pages 3
+stephen 36kr list AI --pages 2 -t
+```
 
-### iDrive Setup
+Notes:
 
-For a synced setup, keep the config local and point the database file into the local iDrive folder on each machine.
+- `--pages` must be between 1 and 20.
+- The first page is parsed from `https://36kr.com/information/<channel>/`.
+- Later pages use the `pageCallback` from the page and call the 36kr pagination API.
 
-PowerShell example:
+List output includes:
 
-```powershell
-$env:STEPHEN_AK_DB_PATH = 'D:\iDrive\stephen\ak.db'
+```text
+channel
+items[].id
+items[].title
+items[].summary
+items[].authorName
+items[].publishTime
+items[].url
+meta.fetchedPages
+meta.totalItems
+meta.hasNextPage
+meta.nextPageCallback
+request
 ```
 
-Local config file example:
+## `toutiao`
+
+`toutiao` uses Playwright Chromium to collect Toutiao page data. This is useful for pages that require real browser execution, scrolling, or response interception.
 
-```json
-{
-  "ak": {
-    "dbPath": "D:\\iDrive\\stephen\\ak.db"
-  }
-}
+### Channels and Keyword Feeds
+
+Supported sources:
+
+```text
+tech
+AI
+光刻机
+芯片
+半导体
 ```
 
-If both are present, the local config file wins. `config get` and `config list` will still show the environment variable in `envValue`, but the effective `source` becomes `"config"`. `STEPHEN_CLI_AK_DB_PATH` is still accepted as a legacy fallback for existing machines.
+Examples:
+
+```bash
+stephen toutiao list tech
+stephen toutiao list AI --pages 2
+stephen toutiao list 光刻机 -t
+stephen toutiao list 芯片 --pages 3 -t
+stephen toutiao list 半导体
+```
 
-## `config` Command
+Notes:
 
-The `config` command manages local CLI configuration values.
+- `tech` uses the Toutiao technology channel.
+- `AI`, `光刻机`, `芯片`, and `半导体` use Toutiao search feeds.
+- `--pages` must be between 1 and 5.
 
-Current supported keys:
+List output includes:
 
-- `ak.dbPath`
+```text
+source
+keyword
+items[].id
+items[].title
+items[].abstract
+items[].authorName
+items[].commentCount
+items[].publishTime
+items[].url
+items[].sourceUrl
+hasMore
+next
+meta
+```
 
-### Examples
+### Article Details
 
-List all config values and their effective sources:
+Pass either an article ID or URL:
 
 ```bash
-stephen config list
+stephen toutiao article 1234567890
+stephen toutiao article https://www.toutiao.com/article/1234567890/
 ```
 
-Get one config value:
+Output includes:
+
+```text
+id
+url
+title
+authorName
+publishTimeText
+content.text
+content.paragraphs
+request
+```
+
+### Author Feeds
+
+Pass either an author token or author homepage URL:
 
 ```bash
-stephen config get ak.dbPath
+stephen toutiao author MS4wLjABAAAAVuJhKsIQSKk3hYJ17wPrQUnUnNT7WadBo4T-QiyRk0A
+stephen toutiao author 'https://www.toutiao.com/c/user/token/MS4wLjABAAAAVuJhKsIQSKk3hYJ17wPrQUnUnNT7WadBo4T-QiyRk0A/?source=profile'
+stephen toutiao author MS4wLjABAAAAVuJhKsIQSKk3hYJ17wPrQUnUnNT7WadBo4T-QiyRk0A --pages 2 -t
 ```
 
-Set one config value in the local config file:
+Fetch article details for the author feed:
 
 ```bash
-stephen config set ak.dbPath D:\iDrive\stephen\ak.db
+stephen toutiao author MS4wLjABAAAAVuJhKsIQSKk3hYJ17wPrQUnUnNT7WadBo4T-QiyRk0A --with-content
 ```
 
-`config set` always writes the local config file. If `STEPHEN_AK_DB_PATH` or the legacy `STEPHEN_CLI_AK_DB_PATH` is also set, the file config still has higher priority for the effective runtime value, and `config get` / `config list` will show `source: "config"`.
+Notes:
 
-The persisted record shape is conceptually:
+- `--pages` must be between 1 and 5.
+- Without `--with-content`, the command returns only the author article list.
+- With `--with-content`, article details are fetched and returned in the `articles` field.
 
-```ts
-interface AkRecord {
-  id: string;              // sha1(key)
-  env: string;             // recommended values exist, custom values allowed
-  userId: string | null;
-  userName: string | null;
-  email: string | null;
-  phone: string | null;
-  keyCiphertext: string;
-  keySearchPrefix: string;
-  createdAt: string;
-  updatedAt: string;
-}
+## `hn` Hacker News
+
+`hn` supports Hacker News story lists and search. JSON is the default output format, and list output supports `-t`.
+
+Top stories:
+
+```bash
+stephen hn top
+stephen hn top --limit 10 -t
 ```
 
-## `disk cleanup` Command
+New stories:
 
-The `disk cleanup` command provides layered Windows cleanup. It previews by default, uses JSON output by default, and avoids deleting user data such as Downloads.
+```bash
+stephen hn new
+stephen hn new --limit 20
+```
 
-Cleanup levels:
+Best stories:
 
-- `safe`: current conservative cache cleanup. This is the default.
-- `dev`: `safe` plus common developer caches.
-- `system`: `safe` plus Windows system cleanup actions. Applying this level requires `--confirm`.
-- `deep`: `dev` plus `system`, and reports the top 100 largest Downloads files/folders without deleting them. Applying this level requires `--confirm`.
+```bash
+stephen hn best
+stephen hn best --limit 20 -t
+```
 
-`safe` targets:
+Search:
 
-- `%USERPROFILE%\AppData\Local\npm-cache`
-- `%USERPROFILE%\AppData\Local\NuGet`
-- `%USERPROFILE%\.cache`
-- `%USERPROFILE%\.m2`
-- `%USERPROFILE%\AppData\Local\Temp`
-- `%SystemRoot%\SoftwareDistribution\Download`
+```bash
+stephen hn search openai
+stephen hn search "browser automation" --sort date --limit 20 -t
+```
 
-Additional `dev` targets:
+Options:
 
-- `%USERPROFILE%\.gradle\caches`
-- `%USERPROFILE%\.pnpm-store`
-- `%USERPROFILE%\AppData\Local\pnpm\store`
-- `%USERPROFILE%\AppData\Local\Yarn\Cache`
-- `%USERPROFILE%\AppData\Local\pip\Cache`
+```text
+--limit <limit>              Number of items, 1 to 100
+--sort <relevance|date>      Search sort, default relevance
+--format <json|table>        Output format
+-t, --table                  Table output
+```
 
-Additional `system` actions:
+Output includes:
 
-- `%SystemRoot%\Temp`
-- `dism.exe /Online /Cleanup-Image /StartComponentCleanup`
+```text
+items[].id
+items[].title
+items[].author
+items[].score
+items[].commentCount
+items[].time
+items[].url
+meta
+```
 
-### Examples
+## Commands With Table Output
 
-Preview cleanup results in JSON:
+These commands are useful for quick human inspection:
 
 ```bash
-stephen disk cleanup
+stephen ak list -t
+stephen config list -t
+stephen disk cleanup -t
+stephen video sniff <url> -t
+stephen video download <url> -t
+stephen video compress <file> -t
+stephen 36kr list AI -t
+stephen toutiao list tech -t
+stephen toutiao author <token-or-url> -t
+stephen hn top -t
+stephen hn new -t
+stephen hn best -t
+stephen hn search openai -t
 ```
 
-Preview developer cleanup:
+## Development
+
+Install dependencies:
 
 ```bash
-stephen disk cleanup --level dev
+npm install
 ```
 
-Preview deep cleanup, including Downloads top 100 entries:
+Type check:
 
 ```bash
-stephen disk cleanup --level deep
+npm run check
+```
+
+Run tests:
+
+```bash
+npm test
 ```
 
-Apply safe cleanup:
+Run coverage:
 
 ```bash
-stephen disk cleanup --apply
+npm run coverage
 ```
 
-Apply system cleanup after explicit confirmation:
+Build:
 
 ```bash
-stephen disk cleanup --level system --apply --confirm
+npm run build
 ```
 
-Apply cleanup and disable Windows hibernation:
+Run the built CLI locally:
 
 ```bash
-stephen disk cleanup --apply --disable-hibernate
+node dist/index.js --help
 ```
 
-Render cleanup targets as a table:
+Preview the npm package:
 
 ```bash
-stephen disk cleanup -t
+npm pack --dry-run
 ```
 
-### Output Rules
+## Publishing
 
-- Default output is JSON.
-- `-t` or `--format table` switches to table rendering.
-- Preview mode is the default.
-- `--apply` is required before any cleanup is executed.
-- `--confirm` is required for `system --apply` and `deep --apply`.
-- Downloads is never deleted; `deep` only lists the largest 100 files/folders.
+The current package is a scoped public package:
 
-## Verification Standard
+```text
+@stephenyang/stephen
+```
 
-Before calling work complete:
+Publish:
 
-- run `npm test`
-- run `npm run coverage`
-- run `npm run build`
+```bash
+npm publish --access public
+```
+
+Verify after publishing:
 
-The project targets full unit coverage for the implemented modules.
+```bash
+npm view @stephenyang/stephen version --json
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stephenyang/stephen",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "A personal TypeScript CLI for agent-friendly workflows.",
   "homepage": "https://gitee.com/ywmblue/personal-cli",
   "bugs": {