dingtalk-pingo 0.0.0-stage → 0.2.0

package/package.json

@@ -1,6 +1,38 @@
 {
   "name": "dingtalk-pingo",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "Send text and Markdown messages from your terminal, scripts, or AI coding agents to your phone through a DingTalk robot.",
+  "keywords": [
+    "dingtalk",
+    "notification",
+    "cli",
+    "robot",
+    "markdown",
+    "ai-agent"
+  ],
+  "type": "module",
+  "bin": {
+    "pingo": "dist/pingo.js"
+  },
+  "files": [
+    "dist/pingo.js",
+    "skills/",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "node --test \"tests/**/*.test.ts\"",
+    "typecheck": "tsc --noEmit",
+    "build": "node scripts/build.mjs",
+    "check:dist": "node scripts/build.mjs --check",
+    "prepublishOnly": "npm run typecheck && npm test && npm run check:dist"
+  },
+  "devDependencies": {
+    "@types/node": "26.6.6",
+    "esbuild": "0.28.2",
+    "typescript": "7.0.2",
+    "yaml": "2.9.1"
+  }
+}

package/skills/pingo/SKILL.md

@@ -0,0 +1,130 @@
+---
+name: pingo
+description: Send a text, Markdown report, or screenshot from this session to the user's phone via DingTalk, using the `pingo` CLI. Use when the user explicitly asks to send/notify/report something "via Pingo" or "to DingTalk" (e.g. "send me this via pingo", "notify me on DingTalk when done", "pingo this screenshot"). Do not use for routine progress updates, successful tool calls, or when the user has not asked for a notification.
+---
+
+# Pingo — send a message to the user's phone via DingTalk
+
+`pingo` is a local CLI. It sends one message per invocation to the
+user's phone through their own DingTalk robot, then exits. It does not
+run in the background and it does not receive messages.
+
+## When to use this skill
+
+Only when the user explicitly asks for it: phrases like "send me this
+via pingo", "notify me on DingTalk", "pingo this", "text me when done".
+
+Do not use this skill on your own initiative. A request to "summarize
+this" or "let me know the status" is not, by itself, a request to send
+a DingTalk notification — only act on an explicit ask for one.
+
+For ongoing, rule-based notifications across a whole session (only
+notifying on major milestones, blockers, or approvals), use the
+`pingo-follow` skill instead. This skill is for one-off sends.
+
+## How to send
+
+```bash
+pingo send --type <success|warning|error|info> --message "..."
+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 comes from a Markdown file
+pingo send --message "x" --json                       # machine-readable result
+```
+
+- `--type` picks the icon/semantics: `success`, `warning`, `error`, `info`.
+- `--action-required` marks a message as needing the user's decision —
+  use it together with `warning` when you need the user to approve or
+  decide something, not for routine failures.
+- `--agent`, `--project`, `--task` are optional context fields shown in
+  the message body.
+- Prefer `--markdown` for structured reports (multi-step summaries, test
+  results); use `--message` for short one-line updates.
+
+## Three usage patterns
+
+1. **Send now.** The user asks for an immediate message (e.g. a
+   screenshot or a quick status). Send it right away and report the
+   result.
+2. **Send once when the current task finishes.** The user asks to be
+   notified "when done". This is a one-time promise scoped to the
+   current session, not a persistent background job: if you exit or your
+   context is reset before the task finishes, the message will not be
+   sent. Say so if asked whether this is guaranteed.
+3. **Report failure honestly.** If sending fails, say so — never claim a
+   message was sent when it was not.
+
+## Content limits (measured against the live DingTalk API)
+
+- Markdown does **not** support tables or task-list checkbox syntax.
+  Use plain bullet or numbered lists instead.
+- There is a local limit of roughly 8000 bytes per message; keep content
+  short and actionable for a phone screen rather than relying on the CLI
+  to split it.
+- Never put secrets, access tokens, card numbers, or long raw logs in a
+  message body.
+
+## Screenshots, images and videos
+
+`pingo` can attach local images and one mp4 video to a message:
+
+```bash
+pingo send --title "Checkout page" --message "Current layout after the fix" --image ./shot.png
+pingo send --message "Repro recording" --video ./repro.mp4 [--cover ./frame.jpg]
+```
+
+- `--image` accepts png / jpg / gif / bmp, up to 5 images, each up to 10 MiB.
+  The file content must match its extension.
+- `--video` accepts one `.mp4` up to 19 MiB. It is sent as a separate video
+  message right after the main message. Without `--cover`, Pingo grabs a frame
+  with `ffmpeg` if it is installed, otherwise it generates a plain cover.
+- `--image` and `--video` do not replace the text: always pass `--message` or
+  `--markdown` with a short explanation.
+
+To send a screenshot: capture it with whatever tooling you already have, save
+it to a file, then pass the file with `--image`.
+
+**Before sending any screenshot or recording, check it for sensitive
+content** — secrets, access tokens, passwords, customer data, private
+messages, or anything else visible on screen that should not leave the
+machine. A screenshot can capture far more than intended. If you are not
+sure it is safe, ask the user first instead of sending it.
+
+## Links and cards
+
+- Add buttons with `--link "Text=https://..."` (up to 3, http(s) only), for
+  example a PR, a CI log or a deployment URL.
+- If the user's config has a card template (`card.templateId`), messages are
+  sent as cards automatically: the sender (machine, agent, project) is shown at
+  the top. You do not need to choose a format; if the card is rejected, Pingo
+  falls back to Markdown on its own and says so in its output.
+- Card-only extras: `--date "<text>"` sets the card's time line, and
+  `--chart <file.json>` adds a chart (`type` is `lineChart`, `histogram` or
+  `pieChart`; `data` is a non-empty array). Both only work with cards, not
+  Markdown/text.
+- For tabular data, put a Markdown table in `--message` or `--markdown`
+  (`| a | b |` rows with a `| :- | -: |` separator row).
+- `pingo send --json` returns a `cardId` for card messages. One-off sends do not
+  need it; `pingo-follow` uses it to update a card in place.
+
+## Handling failures
+
+- A non-zero exit code means the message was not confirmed sent.
+  Report the exit code and the CLI's error message to the user; never
+  claim success on failure.
+- Exit code `6` means the result is unknown — the message **may have
+  already been sent**. Do not retry; tell the user to check their phone
+  instead.
+- A send with images or a video can be partly delivered: the output (and
+  `--json` `sent` / `failed`) lists what went out and what did not. Do not
+  resend the parts that were already sent; tell the user what is missing.
+- If sending keeps failing, suggest the user run `pingo doctor` to check
+  configuration, permissions, and whether a token can be obtained.
+
+## What this skill does not do
+
+- It does not keep monitoring the task after a one-off send completes.
+- It does not decide on its own what counts as "important" — that
+  judgment belongs to `pingo-follow`, and only after the user opts in.
+- Installing this skill does not grant permission to notify proactively.

package/skills/pingo-follow/SKILL.md

@@ -0,0 +1,132 @@
+---
+name: pingo-follow
+description: Enable or disable proactive DingTalk notifications for the current session only, sent via the `pingo` CLI at major milestones, blockers, or when human approval is needed. Use only when the user explicitly asks to "follow" this session, enable Pingo follow-up, or stop such notifications (e.g. "/pingo-follow", "follow this task and notify me when done", "/pingo-follow off"). Never activate proactive notifications on your own.
+---
+
+# Pingo Follow — session-scoped proactive notifications
+
+This skill makes an agent proactively send DingTalk messages (via the
+`pingo` CLI) at significant points during the *current session only* —
+but only after the user explicitly opts in. There is no persistent
+state file: "follow" is a rule you hold in your own context for this
+conversation, nothing more.
+
+## Activation
+
+Invoke this skill only on an explicit request. Typical phrasing:
+`/pingo-follow`, `/pingo-follow only notify me when you need my review
+or the task is finished`, or in hosts that use `$`-mentions,
+`$pingo-follow`. To turn it off: `/pingo-follow off` or an equivalent
+explicit request (exact slash-command support varies by host — confirm
+the working syntax for the current tool if unsure).
+
+**Never turn this on by yourself.** A user saying "let me know when
+it's done" in passing is a request for the `pingo` skill's one-off
+"send once when finished" pattern, not a request for ongoing
+session-wide monitoring — only treat it as `pingo-follow` activation
+when the user names following/monitoring the session explicitly.
+
+When you turn follow on: confirm the rules you will use in the chat
+only. Activating follow does not send a DingTalk message — the first
+message is the one earned by an actual event.
+Calling this skill again while already active updates the rules for
+this session; it does not restart or duplicate anything.
+
+## Default notification rules
+
+Notify (via `pingo send`) when:
+
+- The task reaches a final, substantive conclusion → `success`.
+- A major milestone with real delivery value is reached → `success` or
+  `info`.
+- A major error makes the task unable to continue, or there is a
+  significant security/compatibility risk → `error` / `warning`.
+- The user must make a decision, approve something, or grant
+  authorization before you can continue → `warning` with
+  `--action-required`.
+
+Stay silent for:
+
+- Routine file edits, ordinary tool calls, normal progress updates.
+- Test failures or errors you can diagnose and fix yourself without
+  user input.
+
+## Custom rules take priority
+
+- "Only notify me for A or B" is a **strict allowlist** — it replaces
+  the default rules above; nothing else gets notified unless the user
+  says so.
+- "Pay extra attention to A" raises A's priority on top of the default
+  rules; it does not remove the defaults.
+- If a custom rule is ambiguous, ask the user in this conversation
+  before acting on it — never widen the scope of notifications on your
+  own guess.
+
+## Judgment checklist
+
+Before sending, ask:
+
+1. Does this affect whether the main goal can continue?
+2. Does the user need to make an explicit decision here?
+3. Is this an agreed, key delivery milestone?
+4. Is there a major security, compatibility, data, or release risk?
+5. Does this match a condition the user specified for this session?
+
+## Anti-spam and deduplication
+
+- Do not send a new message for the same root cause twice.
+- Do not message on every tool call or every conversation turn.
+- Merge multiple minor, same-category updates into one message instead
+  of sending several.
+- Do not let a general "avoid repeat notifications" habit suppress a
+  genuinely new request for human approval — those always go through.
+
+## One card per followed task
+
+When the user's Pingo config sends cards, keep a followed task to a single
+card where it makes sense:
+
+1. The first time something is worth notifying, send it with
+   `pingo send --json ...` and keep the returned `cardId` in this
+   conversation (never write it to a file).
+2. For later progress milestones of the same task, update that card in place
+   instead of sending another message:
+   `pingo update <cardId> --type info --title "Tests passing" --message "..."`.
+   `--message` / `--markdown` replace the whole body, so pass the full text.
+3. **Always send a new message** (not an update) when the user's approval or
+   decision is needed (`--action-required`) and for the final completion
+   report — these must reach the user's phone as a fresh notification.
+4. If `pingo send --json` returned no `cardId` (the message fell back to
+   Markdown or text), keep sending new messages as usual.
+5. If `pingo update` fails, report it; do not silently send a duplicate.
+
+## Turning it off and session boundaries
+
+- Turning follow off stops proactive notifications for the current
+  session only; it never affects other sessions.
+- When the task being followed completes, send one final summary
+  message and consider follow finished for that task — re-enable it
+  explicitly for a new task.
+- A new session always starts with follow off by default. If you
+  cannot reliably confirm whether follow was left on (e.g. after a
+  context compaction or restart), default to off rather than guessing
+  it is still active.
+- Never write a "follow is enabled" marker into a global rules/config
+  file such as `AGENTS.md`. This is session-scoped, in-context state
+  only — nothing is persisted to disk by this skill.
+
+## Follow is not an automatic approval
+
+Enabling follow only means you notify at the right moments — it does
+not expand your authority. Deployments, data deletion, permission
+changes, or security/payment-sensitive design changes still go through
+whatever approval process already applies. Send the notification, then
+wait for the user to act from their terminal; do not proceed on their
+behalf just because you reported it.
+
+## Known limitations
+
+Follow state lives only in this conversation's context. It is not
+guaranteed to survive a context compaction, an agent crash, a
+disconnected session, or a host that does not reliably support slash
+commands — delivery is best-effort, not guaranteed, in this version.