sparkecoder 0.1.125 → 0.1.127

package/dist/skills/default/slack-messaging.md

@@ -0,0 +1,268 @@
+---
+name: Slack Messaging
+description: Send Slack DMs to a user by email, or post to a specific channel by name (not just by ID). Wraps Slack's lookup APIs around the messenger tool so you don't need to know cryptic IDs ahead of time.
+platforms: ["darwin", "linux"]
+version: 1
+lastUpdated: "2026-05-22"
+---
+
+# Slack Messaging Skill
+
+Most of the time you already have the right Slack `channel`/`thread_ts` from
+the inbound event pill (`[SLACK channel=C0B5... thread=1779... user=…]`) — in
+that case **just call `messenger({channel:'slack', to:<channelId>, threadTs:<ts>, text:…})`** and you're done.
+
+This skill is for the cases the inbound pill **doesn't** give you:
+
+1. **DM a specific person by email** (e.g. "DM @ryan@studyfetch.com when the build's done")
+2. **Post to a named channel** when you only know its name (`#general`, not `C0123…`)
+3. **Reply in the same channel you're currently in** when you don't have the ID handy (rare — but useful for proactive worker → channel updates)
+
+## Architecture
+
+`messenger` already does the *sending*. It accepts any Slack channel id
+(`C…` for channels, `G…` for legacy private, `D…` for DMs, or even a user
+id `U…` which Slack auto-routes to a DM). What this skill teaches is how to
+**resolve a human-friendly identifier into the right id** using the bot's
+own credentials, then hand it to `messenger`.
+
+```
+email / channel-name  ──curl Slack API──▶  channel id  ──messenger──▶  posted
+```
+
+The bot token is in the app config — read it once and reuse it across the
+turn. **Do not echo the token in any user-visible output, any log line, or
+any Slack message you send.**
+
+Config file location is OS-dependent. Use this resolver:
+
+```bash
+# OS-aware sparkecoder.config.json path
+if [[ -f "$HOME/Library/Application Support/sparkecoder/sparkecoder.config.json" ]]; then
+  CONFIG="$HOME/Library/Application Support/sparkecoder/sparkecoder.config.json"   # macOS
+elif [[ -f "${XDG_DATA_HOME:-$HOME/.local/share}/sparkecoder/sparkecoder.config.json" ]]; then
+  CONFIG="${XDG_DATA_HOME:-$HOME/.local/share}/sparkecoder/sparkecoder.config.json"  # Linux
+elif [[ -f "$APPDATA/sparkecoder/sparkecoder.config.json" ]]; then
+  CONFIG="$APPDATA/sparkecoder/sparkecoder.config.json"                              # Windows (Git Bash)
+else
+  echo "no sparkecoder config found" >&2; exit 1
+fi
+TOKEN=$(jq -r '.slack.botToken // empty' "$CONFIG")
+```
+
+If `$TOKEN` is empty, Slack isn't configured on this host — `task_failed`
+with that as the reason instead of trying to mint a workaround.
+
+## Required scopes
+
+The bot needs these scopes added in the Slack app config. If a call fails
+with `missing_scope`, that's the cause — surface the scope name to the user
+so they can add it in the Slack dashboard:
+
+| Use case | Scopes |
+|---|---|
+| Look up a user by email | `users:read`, `users:read.email` |
+| Send a DM to that user | `chat:write` *(bots can DM any user in workspaces they're a member of)* |
+| Look up a channel by name | `channels:read` (public), `groups:read` (private) |
+| Post in a channel | `chat:write` + bot must be a member of that channel |
+
+## Resolve an unknown user id → name + email
+
+When you see a bare `U0123…` (or `<@U0123…>`) and you don't already have
+the name/email from the channel pill or a previous lookup, call
+`users.info`. The cache the host process maintains will also be warmed
+by your call — so subsequent inbound messages from that person arrive
+pre-enriched. Requires `users:read`; email field also needs
+`users:read.email`.
+
+```bash
+# id → { name, real_name, email }
+INFO=$(curl -s -G "https://slack.com/api/users.info" \
+  -H "Authorization: Bearer $TOKEN" \
+  --data-urlencode "user=U05C6RWBDPC")
+echo "$INFO" | jq '{
+  ok,
+  name: (.user.profile.display_name_normalized // .user.profile.real_name // .user.name),
+  realName: .user.profile.real_name,
+  email: .user.profile.email,
+  isBot: .user.is_bot
+}'
+```
+
+Use this when:
+- A workflow stamped a notification with someone's id but no name
+- The orchestrator handed you a `<@U…>` token from a thread you weren't part of
+- You want to verify an id is even a real user before pinging them
+
+## Find someone by name (no email handy)
+
+`users.list` returns every workspace member. Cheap one-time scan for
+matching display name or real name. Cache the result for the rest of the
+turn so you don't re-list:
+
+```bash
+# Dump the directory once
+USERS_JSON=$(curl -s "https://slack.com/api/users.list?limit=1000" \
+  -H "Authorization: Bearer $TOKEN")
+
+# Find by exact or partial display/real name
+echo "$USERS_JSON" | jq -r --arg q "ryan" '
+  .members
+  | map(select(.deleted | not))
+  | map(select(.is_bot | not))
+  | .[]
+  | select(
+      (.profile.display_name_normalized // "" | ascii_downcase | contains($q | ascii_downcase))
+      or (.profile.real_name // "" | ascii_downcase | contains($q | ascii_downcase))
+    )
+  | "\(.id)\t\(.profile.real_name // .name)\t\(.profile.email // "(no email)")"
+'
+```
+
+If multiple matches come back, **ask the user** which one — don't pick.
+
+## DM a user by their email
+
+```bash
+# 1. Resolve email → Slack user id (U…)
+USER_ID=$(curl -s -G "https://slack.com/api/users.lookupByEmail" \
+  -H "Authorization: Bearer $TOKEN" \
+  --data-urlencode "email=ryan@studyfetch.com" \
+  | jq -r 'if .ok then .user.id else "ERROR:" + .error end')
+
+# If you get ERROR:users_not_found  →  the email isn't in this workspace.
+# If you get ERROR:missing_scope    →  needs users:read.email.
+
+[[ "$USER_ID" == ERROR:* ]] && echo "Slack lookup failed: ${USER_ID#ERROR:}" && exit 1
+```
+
+Then hand the user id to messenger as the destination. Slack accepts a
+user id where a channel id is expected and auto-opens the DM:
+
+```
+messenger({
+  action: 'post',
+  channel: 'slack',
+  to: '<U_FROM_ABOVE>',
+  text: 'Build done ✅ https://…'
+})
+```
+
+Both `chat.postMessage` and the messenger wrapper handle the DM open
+internally — no separate `conversations.open` call needed.
+
+### Multiple recipients
+
+For broadcast, loop and post one DM per recipient — Slack has no built-in
+"DM list" primitive. Limit to ≤10 in one turn to stay polite; do the rest
+in a follow-up task if there are more.
+
+## Post in a channel by name
+
+```bash
+# 1. Find the channel id from its name. types= covers public AND private
+# channels the bot has been invited to. exclude_archived saves noise.
+CHANNEL_ID=$(curl -s -G "https://slack.com/api/conversations.list" \
+  -H "Authorization: Bearer $TOKEN" \
+  --data-urlencode "types=public_channel,private_channel" \
+  --data-urlencode "exclude_archived=true" \
+  --data-urlencode "limit=1000" \
+  | jq -r --arg name "general" '
+      if .ok then
+        (.channels[] | select(.name == $name) | .id) // ("ERROR:not_found:" + $name)
+      else
+        "ERROR:" + .error
+      end
+    ')
+
+[[ "$CHANNEL_ID" == ERROR:* ]] && echo "channel lookup failed: ${CHANNEL_ID#ERROR:}" && exit 1
+```
+
+`#` prefix is **not** part of the actual name in the API — pass `general`,
+not `#general`. The leading `#` is just UI sugar.
+
+Then:
+```
+messenger({ action: 'post', channel: 'slack', to: '<CHANNEL_ID>', text: '…' })
+```
+
+If posting returns `not_in_channel`, the bot hasn't been invited. Tell the
+user: "@invite the bot to `#<name>` then I'll retry."
+
+## Reply in the channel you're currently in
+
+If you're being driven by an inbound Slack event (the message you're
+responding to was tagged `[SLACK channel=C0B5… thread=… user=…]`),
+**always use that exact `channel` and `thread_ts`** — that keeps the
+conversation threaded in the right place.
+
+```
+messenger({ action: 'post', channel: 'slack', to: 'C0B5CESSBGD', threadTs: '1779420529.312919', text: '…' })
+```
+
+If you genuinely don't have the channel id in scope (e.g. you're a worker
+that wasn't spawned with a slack ref but you know the channel name), use
+the lookup recipe above. **Do not** spam the channel from a worker
+session unless the user explicitly asked — workers normally hand results
+back to the orchestrator, which decides whether to post.
+
+## Error catalogue (verbatim Slack codes)
+
+| Slack `error` | What it means | What to do |
+|---|---|---|
+| `users_not_found` | No user with that email in this workspace | Stop. Tell the user the email isn't in the workspace. |
+| `missing_scope` | Bot is missing a scope | Tell the user which scope; they add it and reinstall the app |
+| `not_in_channel` | Bot isn't a member | Ask the user to invite the bot |
+| `channel_not_found` | ID doesn't exist or isn't visible | Re-lookup; the channel may be archived |
+| `invalid_auth` / `token_revoked` | Token is bad or revoked | Bail; tell user to refresh the bot token in settings |
+| `rate_limited` | You're being throttled | Wait (`Retry-After` header, seconds), then retry once |
+
+## Don'ts
+
+- **Don't** put the bot token in any output, log line, or Slack message you
+  send. Read it from config, use it in curl/messenger, never echo it.
+- **Don't** call `conversations.list` more than once per task — it's slow
+  and rate-limited. Cache the result in a shell variable for the turn.
+- **Don't** invent channel names or emails. Look them up; if the lookup
+  fails, say so instead of fabricating an ID.
+- **Don't** loop messenger to bypass Slack throttling. If you hit
+  `rate_limited`, back off.
+- **Don't** use this skill for the inbound-message reply case — the
+  channel/thread is already on the inbound pill, just use it directly.
+
+## Quick recipes
+
+> All recipes assume `$TOKEN` was set via the OS-aware resolver block above.
+> Don't re-fetch the token each call.
+
+**"DM Ryan when this finishes":**
+```bash
+USER_ID=$(curl -s -G "https://slack.com/api/users.lookupByEmail" \
+  -H "Authorization: Bearer $TOKEN" \
+  --data-urlencode "email=ryan@studyfetch.com" | jq -r '.user.id // empty')
+[[ -z "$USER_ID" ]] && echo "ryan not in workspace" && exit 1
+# then: messenger({ action:'post', channel:'slack', to: USER_ID, text: '…' })
+```
+
+**"Post the daily summary to #standup":**
+```bash
+CHANNEL_ID=$(curl -s -G "https://slack.com/api/conversations.list" \
+  -H "Authorization: Bearer $TOKEN" \
+  --data-urlencode "types=public_channel,private_channel" \
+  --data-urlencode "limit=1000" \
+  | jq -r '.channels[] | select(.name=="standup") | .id')
+[[ -z "$CHANNEL_ID" ]] && echo "no #standup channel visible to the bot" && exit 1
+# then: messenger({ action:'post', channel:'slack', to: CHANNEL_ID, text: '…' })
+```
+
+**"DM each engineer their open PRs":**
+```bash
+for email in alice@x.com bob@x.com carol@x.com; do
+  uid=$(curl -s -G "https://slack.com/api/users.lookupByEmail" \
+    -H "Authorization: Bearer $TOKEN" \
+    --data-urlencode "email=$email" | jq -r '.user.id // empty')
+  [[ -z "$uid" ]] && echo "$email: not in workspace" && continue
+  echo "$email → $uid"
+done
+# then issue messenger calls per row
+```

package/dist/tools/index.d.ts

@@ -1,7 +1,7 @@
 import * as ai from 'ai';
 import { ToolSet } from 'ai';
-import { B as BashToolProgress, W as WriteFileProgress, S as SearchToolProgress } from '../search-CVVfuBPZ.js';
-export { b as BashToolOptions, d as SearchToolOptions, e as WriteFileToolOptions, c as createBashTool, f as createSearchTool, a as createWriteFileTool } from '../search-CVVfuBPZ.js';
+import { B as BashToolProgress, W as WriteFileProgress, S as SearchToolProgress } from '../search-DOzC4ojH.js';
+export { b as BashToolOptions, d as SearchToolOptions, e as WriteFileToolOptions, c as createBashTool, f as createSearchTool, a as createWriteFileTool } from '../search-DOzC4ojH.js';
 
 interface TaskCompletionSignal {
     status: 'completed' | 'failed';
@@ -110,7 +110,7 @@ interface TodoToolOptions {
     workingDirectory: string;
 }
 declare function createTodoTool(options: TodoToolOptions): ai.Tool<{
-    action: "clear" | "add" | "list" | "mark" | "save_plan" | "list_plans" | "get_plan" | "delete_plan";
+    action: "list" | "add" | "mark" | "clear" | "save_plan" | "list_plans" | "get_plan" | "delete_plan";
     status?: "completed" | "pending" | "in_progress" | "cancelled" | undefined;
     items?: {
         content: string;

package/dist/tools/index.js

@@ -3374,8 +3374,10 @@ async function loadAllSkills(directories) {
 }
 async function loadSkillContent(skillName, directories) {
   const allSkills = await loadAllSkills(directories);
+  const normalize2 = (s) => s.toLowerCase().replace(/[^a-z0-9]+/g, " ").trim();
+  const wanted = normalize2(skillName);
   const skill = allSkills.find(
-    (s) => s.name.toLowerCase() === skillName.toLowerCase()
+    (s) => normalize2(s.name) === wanted || normalize2(basename(s.filePath, extname4(s.filePath))) === wanted
   );
   if (!skill) {
     return null;