dingtalk-pingo 0.0.0-stage → 0.1.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.1.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,95 @@
+---
+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 description 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 and images
+
+The `pingo` CLI does not currently support sending images — sending an
+image is not supported yet. If the user asks to send a screenshot:
+
+1. You may capture the screenshot with whatever tooling you already have
+   and inspect or describe its contents.
+2. Send a text/Markdown description instead of the image.
+3. Clearly tell the user that the image itself was **not sent** — image
+   support is not implemented yet. Do not imply the picture went through.
+
+## 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.
+- 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,113 @@
+---
+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.
+
+## 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.