npm - better-dsh - Versions diffs - 0.2.5 → 0.3.0 - Mend

better-dsh 0.2.5 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (999) hide show

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/guides/operate-teams-meeting-pipeline.md DELETED Viewed

@@ -1,295 +0,0 @@
----
-title: "Operate the Teams Meeting Pipeline"
-description: "Runbook, go-live checklist, and operator worksheet for the Microsoft Teams meeting pipeline"
----
-# Operate the Teams Meeting Pipeline
-Use this guide after you have already enabled the feature from [Teams Meetings](/user-guide/messaging/teams-meetings).
-This page covers:
-- operator CLI flows
-- routine subscription maintenance
-- failure triage
-- go-live checks
-- rollout worksheet
-## Core Operator Commands
-### Validate the config snapshot
-```bash
-hermes teams-pipeline validate
-```
-Use this first after any config change.
-### Inspect token health
-```bash
-hermes teams-pipeline token-health
-hermes teams-pipeline token-health --force-refresh
-```
-Use `--force-refresh` when you suspect stale auth state.
-### Inspect subscriptions
-```bash
-hermes teams-pipeline subscriptions
-```
-### Renew near-expiry subscriptions
-```bash
-hermes teams-pipeline maintain-subscriptions
-hermes teams-pipeline maintain-subscriptions --dry-run
-```
-### Automating subscription renewal (REQUIRED for production)
-**Microsoft Graph subscriptions expire in at most 72 hours.** If nothing renews them, meeting notifications silently stop after 3 days and the pipeline looks "broken." This is the #1 operational failure mode for any Graph-backed integration.
-You MUST run `maintain-subscriptions` on a schedule. Pick one of these three options:
-#### Option 1: Hermes cron (recommended if you already run the Hermes gateway)
-Hermes ships a built-in cron scheduler. The `--no-agent` mode runs a script as the job (rather than using an LLM), and `--script` must point at a file under `~/.hermes/scripts/`. First create the script:
-```bash
-mkdir -p ~/.hermes/scripts
-cat > ~/.hermes/scripts/maintain-teams-subscriptions.sh <<'EOF'
-#!/usr/bin/env bash
-exec hermes teams-pipeline maintain-subscriptions
-EOF
-chmod +x ~/.hermes/scripts/maintain-teams-subscriptions.sh
-```
-Then register a script-only cron job that runs every 12 hours (gives 6x headroom against the 72h expiry window):
-```bash
-hermes cron create "0 */12 * * *" \
-  --name "teams-pipeline-maintain-subscriptions" \
-  --no-agent \
-  --script maintain-teams-subscriptions.sh \
-  --deliver local
-```
-Verify it was registered and inspect the next run time:
-```bash
-hermes cron list
-hermes cron status        # scheduler status
-```
-#### Option 2: systemd timer (recommended for Linux production deployments)
-Create `/etc/systemd/system/hermes-teams-pipeline-maintain.service`:
-```ini
-[Unit]
-Description=Hermes Teams pipeline subscription maintenance
-After=network-online.target
-[Service]
-Type=oneshot
-User=hermes
-EnvironmentFile=/etc/hermes/env
-ExecStart=/usr/local/bin/hermes teams-pipeline maintain-subscriptions
-```
-And `/etc/systemd/system/hermes-teams-pipeline-maintain.timer`:
-```ini
-[Unit]
-Description=Run Hermes Teams pipeline subscription maintenance every 12 hours
-[Timer]
-OnBootSec=5min
-OnUnitActiveSec=12h
-Persistent=true
-[Install]
-WantedBy=timers.target
-```
-Enable:
-```bash
-sudo systemctl daemon-reload
-sudo systemctl enable --now hermes-teams-pipeline-maintain.timer
-systemctl list-timers hermes-teams-pipeline-maintain.timer
-```
-#### Option 3: Plain crontab
-```cron
-0 */12 * * * /usr/local/bin/hermes teams-pipeline maintain-subscriptions >> /var/log/hermes/teams-pipeline-maintain.log 2>&1
-```
-Make sure the cron environment has the `MSGRAPH_*` credentials. Simplest fix: source `~/.hermes/.env` at the top of a wrapper script that crontab calls.
-#### Verifying renewal is working
-After you've set up the schedule, check renewal activity after the first scheduled run:
-```bash
-hermes teams-pipeline subscriptions   # should show expirationDateTime advanced
-hermes teams-pipeline maintain-subscriptions --dry-run   # should show "0 expiring soon" most of the time
-```
-If you ever see your Graph webhook mysteriously "stop working" after exactly ~72 hours, this is the first thing to check: did the renewal job actually run?
-### Inspect recent jobs
-```bash
-hermes teams-pipeline list
-hermes teams-pipeline list --status failed
-hermes teams-pipeline show <job-id>
-```
-### Replay a stored job
-```bash
-hermes teams-pipeline run <job-id>
-```
-### Dry-run meeting artifact fetches
-```bash
-hermes teams-pipeline fetch --meeting-id <meeting-id>
-hermes teams-pipeline fetch --join-web-url "<join-url>"
-hermes teams-pipeline fetch --join-web-url "<join-url>" --organizer-user-id <entra-user-id>
-```
-Pass `--organizer-user-id` (the organizer's Microsoft Entra user ID) to resolve
-through the organizer-scoped `/users/{id}/onlineMeetings` Graph path. This is
-required for Teams `/meet/` short URLs, which Graph rejects on the
-`/communications/onlineMeetings` endpoint. Webhook-driven jobs derive the
-organizer automatically from the notification's `@odata.id`.
-## Routine Runbook
-### After first setup
-Run these in order:
-```bash
-hermes teams-pipeline validate
-hermes teams-pipeline token-health --force-refresh
-hermes teams-pipeline subscriptions
-```
-Then trigger or wait for a real meeting event and confirm:
-```bash
-hermes teams-pipeline list
-hermes teams-pipeline show <job-id>
-```
-### Daily or periodic checks
-- run `hermes teams-pipeline maintain-subscriptions --dry-run`
-- inspect `hermes teams-pipeline list --status failed`
-- verify the Teams delivery target is still the correct chat or channel
-### Before changing webhook URLs or delivery targets
-- update the public notification URL or Teams target config
-- run `hermes teams-pipeline validate`
-- renew or recreate affected subscriptions
-- confirm new events land in the expected sink
-## Failure Triage
-### No jobs are being created
-Check:
-- `msgraph_webhook` is enabled
-- the public notification URL points to `/msgraph/webhook`
-- the client state in the subscription matches `MSGRAPH_WEBHOOK_CLIENT_STATE`
-- subscriptions still exist remotely and are not expired
-### Jobs stay in retry or fail before summarization
-Check:
-- transcript permissions and availability
-- recording permissions and artifact availability
-- `ffmpeg` availability if recording fallback is enabled
-- Graph token health
-### Summaries are produced but not delivered to Teams
-Check:
-- `platforms.teams.enabled: true`
-- `delivery_mode`
-- `incoming_webhook_url` for webhook mode
-- `chat_id` or `team_id` plus `channel_id` for Graph mode
-- Teams auth config if Graph posting is used
-### Duplicate or unexpected replays
-Check:
-- whether you manually replayed a job with `hermes teams-pipeline run`
-- whether the sink record already exists for that meeting
-- whether you intentionally enabled a resend path in your local config
-## Go-Live Checklist
-- [ ] Graph credentials are present and correct
-- [ ] `msgraph_webhook` is enabled and reachable from the public internet
-- [ ] `MSGRAPH_WEBHOOK_CLIENT_STATE` is set and matches subscriptions
-- [ ] transcript subscription is created
-- [ ] recording subscription is created if STT fallback is required
-- [ ] `ffmpeg` is installed if recording fallback is enabled
-- [ ] Teams outbound delivery target is configured and verified
-- [ ] Notion and Linear sinks are configured only if actually needed
-- [ ] `hermes teams-pipeline validate` returns an OK snapshot
-- [ ] `hermes teams-pipeline token-health --force-refresh` succeeds
-- [ ] **`maintain-subscriptions` is scheduled** (Hermes cron, systemd timer, or crontab — see [Automating subscription renewal](#automating-subscription-renewal-required-for-production)). Without this, Graph subscriptions silently expire within 72 hours.
-- [ ] a real end-to-end meeting event has produced a stored job
-- [ ] at least one summary has reached the intended delivery sink
-## Delivery-Mode Decision Guide
-| Mode | Use when | Tradeoff |
-|------|----------|----------|
-| `incoming_webhook` | you only need simple posting into Teams | simplest setup, less control |
-| `graph` | you need channel or chat posting through Graph | more control, more auth and target config |
-## Operator Worksheet
-Fill this out before rollout:
-| Item | Value |
-|------|-------|
-| Public notification URL | |
-| Graph tenant ID | |
-| Graph client ID | |
-| Webhook client state | |
-| Transcript resource subscription | |
-| Recording resource subscription | |
-| Teams delivery mode | |
-| Teams chat ID or team/channel | |
-| Notion database ID | |
-| Linear team ID | |
-| Store path override, if any | |
-| Owner for daily checks | |
-## Change Review Worksheet
-Use this before changing the deployment:
-| Question | Answer |
-|----------|--------|
-| Are we changing the public webhook URL? | |
-| Are we rotating Graph credentials? | |
-| Are we changing Teams delivery mode? | |
-| Are we moving to a new Teams chat or channel? | |
-| Do subscriptions need to be recreated or renewed? | |
-| Do we need a fresh end-to-end verification run? | |
-## Related Docs
-- [Teams Meetings setup](/user-guide/messaging/teams-meetings)
-- [Microsoft Teams bot setup](/user-guide/messaging/teams)

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/guides/pipe-script-output.md DELETED Viewed

@@ -1,249 +0,0 @@
----
-sidebar_position: 12
-title: "Pipe Script Output to Messaging Platforms"
-description: "Send text from any shell script, cron job, CI hook, or monitoring daemon to Telegram, Discord, Slack, Signal, and other platforms using `hermes send`."
----
-# Pipe Script Output to Messaging Platforms
-`hermes send` is a small, scriptable CLI that pushes a message to any
-messaging platform Hermes is already configured for. Think of it as a
-cross-platform `curl` for notifications — you don't need a running
-gateway, you don't need an LLM, and you don't need to re-paste bot tokens
-into each of your scripts.
-Use it for:
-- System monitoring (memory, disk, GPU temp, long-running job finished)
-- CI/CD notifications (deploy done, test failure)
-- Cron scripts that need to ping you with results
-- Quick one-shot messages from a terminal
-- Piping any tool's output anywhere (`make | hermes send --to slack:#builds`)
-The command reuses the same credentials and platform adapters that `hermes
-gateway` already uses, so there's no second configuration surface to
-maintain.
----
-## Quick Start
-```bash
-# Plain text to the home channel for a platform
-hermes send --to telegram "deploy finished"
-# Pipe in stdout from anything
-echo "RAM 92%" | hermes send --to telegram:-1001234567890
-# Send a file
-hermes send --to discord:#ops --file /tmp/report.md
-# Attach a subject/header line
-hermes send --to slack:#eng --subject "[CI] build.log" --file build.log
-# Thread target (Telegram topic, Discord thread)
-hermes send --to telegram:-1001234567890:17585 "threaded reply"
-# List every configured target
-hermes send --list
-# Filter by platform
-hermes send --list telegram
-```
----
-## Argument Reference
-| Flag | Description |
-|------|-------------|
-| `-t, --to TARGET` | Destination. See [target formats](#target-formats). |
-| `message` (positional) | Message text. Omit to read from `--file` or stdin. |
-| `-f, --file PATH` | Read the body from a file. `--file -` forces stdin. |
-| `-s, --subject LINE` | Prepend a header/subject line before the body. |
-| `-l, --list` | List available targets. Optional positional platform filter. |
-| `-q, --quiet` | No stdout on success (exit code only — ideal for scripts). |
-| `--json` | Emit the raw JSON result of the send. |
-| `-h, --help` | Show the built-in help text. |
-### Target Formats
-| Format | Example | Meaning |
-|--------|---------|---------|
-| `platform` | `telegram` | Send to the platform's configured home channel |
-| `platform:chat_id` | `telegram:-1001234567890` | Specific numeric chat / group / user |
-| `platform:chat_id:thread_id` | `telegram:-1001234567890:17585` | Specific thread or Telegram forum topic |
-| `platform:#channel` | `discord:#ops` | Human-friendly channel name (resolved against the channel directory) |
-| `platform:+E164` | `signal:+15551234567` | Phone-addressed platforms: Signal, SMS, WhatsApp |
-Any platform Hermes ships adapters for works as a target:
-`telegram`, `discord`, `slack`, `signal`, `sms`, `whatsapp`, `matrix`,
-`mattermost`, `feishu`, `dingtalk`, `wecom`, `weixin`, `email`, and
-others.
-### Exit Codes
-| Code | Meaning |
-|------|---------|
-| `0` | Send (or list) succeeded |
-| `1` | Delivery failed at the platform level (auth, permissions, network) |
-| `2` | Usage / argument / config error |
-Exit codes follow the standard Unix convention so your scripts can
-branch on them the same way they would on `curl` or `grep`.
----
-## Message Body Resolution
-`hermes send` resolves the message body in this order:
-1. **Positional argument** — `hermes send --to telegram "hi"`
-2. **`--file PATH`** — `hermes send --to telegram --file msg.txt`
-3. **Piped stdin** — `echo hi | hermes send --to telegram`
-When stdin is a TTY (no pipe), Hermes does **not** wait for input — you'll
-get a clear usage error instead. This keeps scripts from hanging if they
-accidentally omit the body.
----
-## Real-World Examples
-### Monitoring: Memory / Disk Alerts
-Replace ad-hoc `curl https://api.telegram.org/...` calls in your watchdogs
-with a single portable line:
-```bash
-#!/usr/bin/env bash
-ram_pct=$(free | awk '/^Mem:/ {printf "%d", $3 * 100 / $2}')
-if [ "$ram_pct" -ge 85 ]; then
-  hermes send --to telegram --subject "⚠ MEMORY WARNING" \
-    "RAM ${ram_pct}% on $(hostname)"
-fi
-```
-Because `hermes send` reuses your Hermes config, the same script works on
-any host where Hermes is installed — no need to export bot tokens into
-each machine's environment manually.
-:::tip Don't alert the gateway about itself
-For watchdogs that might fire when the gateway itself is struggling (OOM
-alerts, disk-full alerts), keep using a minimal `curl` call instead of
-`hermes send`. If the Python interpreter can't load because the box is
-thrashing, you still want that alert to go out.
-:::
-### CI / CD: Build and Test Results
-```bash
-# In .github/workflows/deploy.yml or any CI script
-if ./scripts/deploy.sh; then
-  hermes send --to slack:#deploys "✅ ${CI_COMMIT_SHA:0:7} deployed"
-else
-  tail -n 100 deploy.log | hermes send \
-    --to slack:#deploys --subject "❌ deploy failed"
-  exit 1
-fi
-```
-### Cron: Daily Report
-```bash
-# Crontab entry
-0 9 * * * /usr/local/bin/generate-metrics.sh \
-  | /home/me/.hermes/bin/hermes send \
-      --to telegram --subject "Daily metrics $(date +%Y-%m-%d)"
-```
-### Long-Running Tasks: Ping When Done
-```bash
-./train.py --epochs 200 && \
-  hermes send --to telegram "training done" || \
-  hermes send --to telegram "training failed (exit $?)"
-```
-### Scripting with `--json` and `--quiet`
-```bash
-# Hard-fail a script if delivery fails; don't clutter logs on success
-hermes send --to telegram --quiet "keepalive" || {
-  echo "Telegram delivery failed" >&2
-  exit 1
-}
-# Capture the message ID for later editing / threading
-msg_id=$(hermes send --to discord:#ops --json "build started" \
-  | jq -r .message_id)
-```
----
-## Does `hermes send` Need the Gateway Running?
-**Usually no.** For any bot-token platform — Telegram, Discord, Slack,
-Signal, SMS, WhatsApp Cloud API, and most others — `hermes send` calls
-the platform's REST endpoint directly using credentials from
-`~/.hermes/.env` and `~/.hermes/config.yaml`. It's a standalone subprocess
-that exits as soon as the message is delivered.
-A live gateway is only required for **plugin platforms** that rely on a
-persistent adapter connection (for example, a custom plugin that keeps
-a long-lived WebSocket open). In that case you'll get a clear error
-pointing at the gateway; start it with `hermes gateway start` and retry.
----
-## Listing and Discovering Targets
-Before sending to a specific channel, you can inspect what's available:
-```bash
-# Every target across every configured platform
-hermes send --list
-# Just Telegram targets
-hermes send --list telegram
-# Machine-readable
-hermes send --list --json
-```
-The listing is built from `~/.hermes/channel_directory.json`, which the
-gateway refreshes every few minutes while it's running. If you see
-"no channels discovered yet", start the gateway once (`hermes gateway
-start`) so it can populate the cache.
-Human-friendly names (`discord:#ops`, `slack:#engineering`) are resolved
-against this cache at send time, so you don't need to memorize numeric
-IDs.
----
-## Comparison with Other Approaches
-| Approach | Multi-platform | Reuses Hermes creds | Needs gateway | Best for |
-|----------|----------------|---------------------|---------------|----------|
-| `hermes send` | ✅ | ✅ | No (bot-token) | Everything below |
-| Raw `curl` to each platform | Each scripted separately | Manual | No | Critical watchdogs |
-| `cron` job with `--deliver` | ✅ | ✅ | No | Scheduled agent tasks |
-`hermes send` is intentionally the simplest possible surface. If you need
-an agent to decide what to say, schedule a cron job — the agent's final
-response is auto-delivered to the configured `deliver:` target (the agent
-no longer fires messages itself). If you need a scheduled run with LLM-generated content,
-use `cronjob(action='create', prompt=...)` with `deliver='telegram:...'`.
-If you just need to pipe a raw string, reach for `hermes send`.
----
-## Related
-- [Automate Anything with Cron](/guides/automate-with-cron) —
-  scheduled jobs whose output auto-delivers to any platform.
-- [Gateway Internals](/developer-guide/gateway-internals) —
-  the delivery router that `hermes send` shares with cron delivery.
-- [Messaging Platform Setup](/user-guide/messaging/) —
-  one-time configuration for each platform.