dingtalk-pingo 0.0.0-stage → 0.2.0

package/README.md

@@ -1,3 +1,336 @@
-# Temporary Holding Version
+# dingtalk-pingo
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Send text and Markdown messages from your terminal, scripts, or AI coding
+agents straight to your phone through a DingTalk robot — no server, no
+polling, no runtime dependencies beyond Node itself.
+
+```bash
+pingo send --type success --message "Build finished, 42 tests passing."
+```
+
+## Why
+
+You're running a long task over SSH/tmux, or an AI coding agent (Kiro,
+Codex, Claude Code, ...) is working unattended, and you want to know when
+it's actually done — without watching a terminal. `pingo` is a single CLI
+command any script or agent can call to push a one-off notification to
+your phone via DingTalk's one-to-one robot messaging API.
+
+It is deliberately one-directional and stateless: it sends a message and
+exits. It does not receive messages, does not run as a background
+service, and does not poll anything.
+
+## Who this is for
+
+- Developers who use DingTalk and want build/deploy/test notifications
+  pushed to their phone from shell scripts, CI, or cron.
+- People running AI coding agents unattended who want a reliable "it's
+  done" / "it needs your input" signal, without a chat-based control
+  loop.
+- Anyone who wants a minimal, auditable CLI for DingTalk robot messaging
+  instead of a heavier notification framework.
+
+## Install
+
+Requires Node.js 18+.
+
+```bash
+npm install -g dingtalk-pingo
+```
+
+This installs a single `pingo` command. The package ships as one bundled
+file with no runtime dependencies.
+
+## Set up your own DingTalk robot
+
+Pingo sends through **your own** DingTalk enterprise-internal app and
+robot — there is no shared or hosted robot. You need:
+
+1. A DingTalk enterprise account at <https://open.dingtalk.com/>.
+2. An enterprise-internal application, which gives you an **AppKey**
+   (`clientId`) and **AppSecret** (`clientSecret`).
+3. A robot created under that application, which gives you a
+   **robotCode**.
+4. Your own DingTalk **userId** (the recipient) — the person the robot
+   will message.
+5. Robot permission to send one-to-one ("private chat") messages, granted
+   to the application in the DingTalk admin console.
+
+Exact steps change over time; follow DingTalk's current documentation at
+<https://open.dingtalk.com/> and verify the "send one-to-one messages in
+batch" API (`robot/oToMessages/batchSend`) works for your app before
+relying on it.
+
+## Configure
+
+Create `~/.pingo/config.yaml` (on Windows: `%USERPROFILE%\.pingo\config.yaml`)
+and restrict its permissions, since it holds a secret:
+
+```bash
+mkdir -p ~/.pingo
+chmod 700 ~/.pingo
+touch ~/.pingo/config.yaml
+chmod 600 ~/.pingo/config.yaml
+```
+
+```yaml
+device:
+  id: work-mac
+  name: Work Mac
+  icon: "🏢"                        # shown in Markdown/text messages
+  avatar: "https://example.com/work-mac.png"   # optional, card messages only (http(s) URL)
+
+card:
+  templateId: "<your card template id>"   # optional; enables card messages (see "Card messages")
+
+dingtalk:
+  clientId: <your AppKey>
+  clientSecret: <your AppSecret>   # or: clientSecretEnv: DINGTALK_CLIENT_SECRET
+  robotCode: <your robotCode>
+  userId: <your DingTalk userId>
+
+message:
+  defaultType: info
+  preferredFormat: card            # card | markdown | text (default: card if card.templateId is set, else markdown)
+  fallbackFormat: text
+  timeoutMs: 10000
+
+templates:                          # optional: override the built-in templates
+  success:
+    title: "{typeIcon} {deviceIcon} {device} · done"
+```
+
+Credentials can also come from environment variables, which take
+precedence over the file: `DINGTALK_CLIENT_ID`, `DINGTALK_CLIENT_SECRET`,
+`DINGTALK_ROBOT_CODE`, `DINGTALK_USER_ID`, plus `PINGO_DEVICE_ID`,
+`PINGO_DEVICE_NAME`, `PINGO_DEVICE_ICON`, `PINGO_DEVICE_AVATAR` for device
+identity and `PINGO_CARD_TEMPLATE_ID` for the card template. This is
+useful in CI or containers where you don't want a config file at all.
+
+If you run multiple machines against the same robot (e.g. a work laptop
+and a home desktop), give each one a distinct `device` block so messages
+on your phone are easy to tell apart.
+
+> All machines sharing one DingTalk app share one AppSecret — there is no
+> per-device key isolation in this tool. Treat the secret accordingly and
+> rotate it if it may have leaked.
+
+## Usage
+
+```bash
+pingo doctor                 # self-check: config, permissions, can we get a token?
+pingo config validate        # validate config and show where it was loaded from
+pingo config show            # print merged config (secrets masked)
+
+pingo send --type info --message "Stage 1 complete"
+pingo send --type success --title "Deploy finished" \
+  --message "Build and tests passed" --agent kiro --project payment-sdk
+pingo send --type warning --action-required --message "Please review the token permission change"
+pingo send --markdown ./report.md --type success     # body from a Markdown file
+pingo send --message "preview this" --dry-run         # preview only, no credentials needed
+pingo send --message "x" --json                       # machine-readable output
+
+pingo send --title "Checkout page" --message "After the fix" --image ./shot.png
+pingo send --message "Repro recording" --video ./repro.mp4
+pingo send --message "PR is ready" --link "Open PR=https://github.com/org/repo/pull/1"
+pingo update <cardId> --type success --title "Tests passing" --message "195/195"
+```
+
+Run `pingo --help` for the full option list.
+
+## Card messages
+
+With a card template configured, every message is a DingTalk card whose
+header shows the sender — the machine's avatar and name, plus the agent and
+project — so messages from several machines sharing one robot are easy to
+tell apart. Below the header come the title, the Markdown body, any images
+and optional link buttons.
+
+To enable cards:
+
+1. Grant your app the **`Card.Instance.Write`** permission in the DingTalk
+   developer console.
+2. Create a message card template in the card editor at
+   <https://open-dev.dingtalk.com/fe/card>, linked to your app. There is no
+   public API for creating templates; it is done in the web editor. Lay it out
+   as "avatar + sender name" on the first row, the title below, then a
+   Markdown/rich-text block and a button group. Bind these variables (names and
+   types must match exactly):
+
+   - `avatar` — plain text (image URL)
+   - `senderName` — plain text
+   - `title` — plain text
+   - `content` — rich text (Markdown)
+   - `btns` — button group
+   - optional: `date` — plain text (shown when `--date` is used)
+   - optional: `chart` — chart variable (shown when `--chart` is used)
+
+3. Publish the template, then set `card.templateId` (and optionally
+   `device.avatar`) in `~/.pingo/config.yaml`.
+
+Card-only options:
+
+- `--date "<text>"` fills the `date` variable (Pingo does not format it).
+- `--chart <file.json>` fills the `chart` variable. The file holds a chart
+  object: `type` is `lineChart`, `histogram` or `pieChart`, `data` is a
+  non-empty array, `config` is optional. See DingTalk's
+  [chart variable](https://open.dingtalk.com/document/isvapp/chart-variable)
+  protocol. Example: `{"type":"lineChart","data":[{"x":"N0","type":"line","y":48}]}`.
+- Both are rejected with `--format markdown|text`, and both work with
+  `pingo update`.
+- Tables: put a Markdown table in `--message`/`--markdown`. It renders only if
+  the template's `content` component uses DingTalk's newer Markdown variable;
+  the older one has no table support.
+
+Templates belong to your own DingTalk app; Pingo does not ship one. If the
+card is rejected (wrong template ID, missing permission), Pingo falls back to
+a Markdown message and says why in its output. Timeouts are never retried or
+downgraded, to avoid duplicate messages.
+
+`pingo send --json` returns a `cardId` for card messages. `pingo update
+<cardId>` changes that card in place: `--type`/`--title` regenerate the title;
+`--message`/`--markdown`/`--image`/`--action-required` replace the whole body
+(pass the full text); `--agent`/`--project` update the sender line; `--link`
+replaces the buttons. Unspecified fields are left as they were. An update never
+falls back to sending a new message.
+
+## Sending images and videos
+
+- `--image <file>`: png, jpg, gif or bmp; up to 5 per message, 10 MiB each;
+  the file content must match the extension. In a card, images appear inside
+  the card; in Markdown/text messages they follow as separate image messages.
+- `--video <file.mp4>`: one mp4 per message, up to 19 MiB (DingTalk's upload
+  limit is just under 20 MiB). It is sent as a separate video message right
+  after the main message. The duration is read from the mp4 itself.
+- `--cover <image>`: video cover. Without it, Pingo grabs a frame with `ffmpeg`
+  if it is installed (optional, not a dependency); otherwise it generates a
+  plain gradient cover whose colour is derived from `device.id`.
+- `--image` / `--video` always come with `--message` or `--markdown`.
+- Files are uploaded to DingTalk's media service before anything is sent; if an
+  upload fails, nothing is sent. If a later part of a multi-part send fails,
+  the output lists what was and was not delivered, and nothing is resent.
+
+Screenshots and screen recordings can capture more than intended — check them
+for secrets or private data before sending.
+
+## AI agent skills
+
+The package ships two [Agent Skills](https://developers.openai.com/codex/skills/create-skill)
+(a folder with a `SKILL.md`) that teach an AI coding agent when and how
+to call `pingo`:
+
+- **`pingo`** — send a one-off message, report, or "done" summary when you
+  explicitly ask the agent to ("send me this via pingo", "notify me on
+  DingTalk when finished"). It never notifies on its own.
+- **`pingo-follow`** — opt-in, session-scoped follow-up. After you turn it
+  on (for example `/pingo-follow`, or `/pingo-follow only notify me when
+  you need my review`), the agent notifies you only at major milestones,
+  blockers, or when your approval is needed, and stays silent otherwise.
+  Turning it on does not itself send a DingTalk message.
+
+Install them into the tools you use:
+
+```bash
+pingo skills install                       # interactive: choose Kiro / Claude Code / Codex
+pingo skills install --tool kiro,claude    # non-interactive (required when there is no terminal)
+pingo skills uninstall                     # removes only links created by this package
+```
+
+`install` creates symlinks `~/.kiro/skills/<name>`, `~/.claude/skills/<name>`,
+and `~/.codex/skills/<name>` that point at the skills shipped inside this
+package. It never overwrites or deletes anything it did not create: if a
+path already exists and is not one of its own links, it is reported as a
+conflict and skipped (exit code 2). Re-running `install` is safe, and it
+repairs links that went stale after you changed Node versions or moved the
+global `node_modules` directory. Start a new session in the tool afterwards
+so it discovers the skills.
+
+How to invoke them explicitly: type `/pingo-follow` in Kiro and Claude
+Code, or `$pingo-follow` (or `/skills`) in Codex.
+
+## Exit codes
+
+| Code | Meaning |
+|---|---|
+| 0 | DingTalk accepted the request (not the same as the user having read it) |
+| 1 | Usage error |
+| 2 | Missing or invalid configuration, or a skill-install conflict |
+| 3 | Authentication failed |
+| 4 | Invalid content (missing required fields, or too long) |
+| 5 | DingTalk temporarily unavailable or rate-limited (retried twice) |
+| 6 | Result unknown — **the message may have already been sent**; don't resend |
+
+## Message format limits (measured against the live API)
+
+- Markdown does **not** support tables or task-list checkboxes
+  (`- [ ]`); use plain lists instead.
+- The request body limit is roughly 20000 bytes; Pingo enforces an 8000-byte
+  local limit on `msgParam` and rejects oversized content up front rather
+  than letting DingTalk reject it (no automatic splitting yet). Each CJK
+  character costs roughly 3 bytes.
+- DingTalk accepts a request with a missing title/body without erroring —
+  it sends the literal placeholder text `#title#` / `#text#` to the
+  phone. Pingo validates required fields locally so that can't happen.
+- Markdown is only downgraded to plain text when DingTalk rejects it as
+  an invalid format; a request whose result is unknown (e.g. a timeout)
+  is never retried, to avoid duplicate messages.
+
+## Development
+
+```bash
+npm test             # unit tests (requires Node ≥ 24 to run .ts directly)
+npm run typecheck
+npm run build         # produce dist/pingo.js
+npm run check:dist    # verify dist/pingo.js matches the current source
+```
+
+If you change anything under `src/`, run `npm run build` and commit the
+updated `dist/pingo.js` — `npm run check:dist` verifies they match, and
+`prepublishOnly` runs the full check before `npm publish`.
+
+## Status
+
+Version 0.2 adds card messages, in-place card updates, images, mp4 videos and
+link buttons. Text/Markdown sending, cards, card updates, image upload and
+sending, and video sending were each verified against a live DingTalk robot;
+everything is covered by unit tests. How reliably each AI tool follows
+`pingo-follow` has not been verified end to end yet (see below). File
+attachments are not supported.
+
+## Known limitations
+
+- **Skill directories.** `~/.kiro/skills`, `~/.claude/skills` and
+  `~/.codex/skills` are the locations `pingo skills install` uses. Kiro
+  and Claude Code document their skill folders; for Codex the official
+  pages describe the `SKILL.md` format and `$skill` / `/skills`
+  invocation but `~/.codex/skills` could not be confirmed as the default
+  directory from documentation — it matches the directory Codex uses on
+  the author's machine. If your Codex setup reads skills from somewhere
+  else, link `skills/pingo*` there yourself.
+- **`pingo-follow` is advisory.** It is plain instructions, not a
+  background service. Its on/off state lives only in the agent's
+  conversation context, so it can be lost after a context compaction,
+  a crash, or a new session (a new session always starts with it off).
+  Delivery is best-effort. How strictly each tool honors "only when
+  explicitly enabled" is unverified.
+- **Explicit-only invocation is not enforced by the tool.** Claude Code
+  has a `disable-model-invocation` frontmatter field that would stop the
+  model from loading a skill on its own, but it also hides the skill's
+  description from the model, which would break natural-language
+  activation such as "follow this task and notify me when done". It is
+  therefore not used here, and it could not be confirmed that Kiro or
+  Codex honor it. The
+  skill's description and body tell the agent to activate only on an
+  explicit request; that is guidance, not a hard guarantee.
+- **Skill links follow the package location.** The links point at the
+  globally installed package. After changing Node version or moving the
+  global `node_modules` directory, re-run `pingo skills install` to
+  repair them.
+- **Cards and notifications.** Whether updating a card in place re-notifies
+  the phone, and what the chat list shows as the preview of a card message,
+  are not yet verified; `pingo-follow` therefore sends approval requests and
+  final reports as new messages.
+- **Card body limit.** The card body uses the same conservative 8000-byte local
+  limit as Markdown; DingTalk's real limit for cards has not been measured.
+- **Videos.** Only mp4 has been tested. Videos are never embedded in cards.
+- **No file attachments** yet.