dingtalk-pingo 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,247 @@
-# 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: "🏢"
+
+dingtalk:
+  clientId: <your AppKey>
+  clientSecret: <your AppSecret>   # or: clientSecretEnv: DINGTALK_CLIENT_SECRET
+  robotCode: <your robotCode>
+  userId: <your DingTalk userId>
+
+message:
+  defaultType: info
+  preferredFormat: markdown        # markdown | text
+  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` for device identity. 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
+```
+
+Run `pingo --help` for the full option list.
+
+## 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
+
+This is an early release: the CLI, configuration, templates, and
+single-recipient text/Markdown sending are implemented and covered by
+unit tests, plus manual verification against a live DingTalk robot. The
+`pingo` and `pingo-follow` skills and `pingo skills install` are
+implemented and covered by unit tests; how reliably each AI tool follows
+`pingo-follow` has not been verified end to end yet (see below).
+Image/screenshot sending is not implemented yet.
+
+## 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.
+- **No image sending yet.** The `pingo` skill tells the agent to send a
+  text description instead and to say plainly that the image was not
+  sent.