pm-slack 2026.6.2 → 2026.6.4

package/dist/index.js

@@ -13,9 +13,24 @@
  *   PM_SLACK_WEBHOOK      (required) Slack incoming webhook URL
  *   PM_SLACK_CHANNEL      (optional) Override channel, e.g. #pm-alerts
  *   PM_SLACK_MIN_PRIORITY (optional) Minimum priority to notify (1=critical … 4=low), default 1 (critical only; set 4 for all)
- *   PM_SLACK_EVENTS       (optional) Comma-separated subset of hook events: create,close,block (default: all)
+ *   PM_SLACK_EVENTS       (optional) Comma-separated subset of hook events:
+ *                                    create,close,block,cancel,open,start,unblock,reopen (default: all).
+ *                                    Status-name aliases (e.g. "canceled","in_progress") are accepted.
+ *   PM_SLACK_FORMAT       (optional) Default notification format: "blockkit" (default) or "text"
+ *   PM_SLACK_ASSIGNEE_MAP (optional) Comma list of "name=slackId" pairs mapping a pm item's
+ *                                    assignee to a Slack @mention, e.g. "alice=U123,bob=U456".
+ *   PM_SLACK_MENTION_ASSIGNEE (optional) Set to 0/false to disable assignee @mentions even when a map is set
+ *                                    (mentions auto-enable in the hook whenever PM_SLACK_ASSIGNEE_MAP is non-empty).
+ *   PM_SLACK_ROUTES       (optional) JSON array of routing rules to send specific
+ *                                    events/types/statuses to different webhooks/channels.
+ *                                    Each rule: { "match": "<selector>", "webhook"?: "...", "channel"?: "..." }
+ *                                    Selector forms: an event ("create"|"close"|"block"),
+ *                                    "type:<itemType>" (case-insensitive), or "status:<status>".
+ *                                    First matching rule wins; unset fields fall back to the defaults.
  */
 import https from "node:https";
+import fs from "node:fs";
+import path from "node:path";
 const defineExtension = ((extension) => extension);
 // ---------------------------------------------------------------------------
 // EXIT_CODE / CommandError (re-implemented locally)
@@ -77,35 +92,181 @@ function readStrOption(options, key) {
 // ---------------------------------------------------------------------------
 // Event parsing
 // ---------------------------------------------------------------------------
-const ALL_EVENTS = ["create", "close", "block"];
+const ALL_EVENTS = [
+    "create",
+    "close",
+    "block",
+    "cancel",
+    "open",
+    "start",
+    "unblock",
+    "reopen",
+];
+/**
+ * Friendly aliases accepted in PM_SLACK_EVENTS / `--on` so callers can write the
+ * status name they think in (e.g. "canceled"/"cancelled" → cancel,
+ * "in_progress" → start). Aliases normalize to a canonical EventKind.
+ */
+const EVENT_ALIASES = {
+    created: "create",
+    closed: "close",
+    done: "close",
+    complete: "close",
+    completed: "close",
+    resolved: "close",
+    blocked: "block",
+    canceled: "cancel",
+    cancelled: "cancel",
+    opened: "open",
+    in_progress: "start",
+    "in-progress": "start",
+    started: "start",
+    unblocked: "unblock",
+    reopened: "reopen",
+};
+function normalizeEvent(token) {
+    const t = token.trim().toLowerCase();
+    if (ALL_EVENTS.includes(t))
+        return t;
+    return EVENT_ALIASES[t] ?? null;
+}
 function parseEvents(spec) {
     if (!spec)
         return new Set(ALL_EVENTS);
     const parsed = spec
         .split(",")
-        .map((e) => e.trim().toLowerCase())
-        .filter((e) => ALL_EVENTS.includes(e));
+        .map((e) => normalizeEvent(e))
+        .filter((e) => e !== null);
     return parsed.length > 0 ? new Set(parsed) : new Set(ALL_EVENTS);
 }
+// ---------------------------------------------------------------------------
+// Format parsing
+// ---------------------------------------------------------------------------
+const ALL_FORMATS = ["blockkit", "text"];
+/**
+ * Normalize a format spec to a known MessageFormat. Accepts a few friendly
+ * aliases ("block"/"blocks" → blockkit, "plain"/"txt" → text). Falls back to
+ * the supplied default when the spec is empty or unrecognized.
+ */
+function parseFormat(spec, fallback = "blockkit") {
+    if (!spec)
+        return fallback;
+    const v = spec.trim().toLowerCase();
+    if (v === "blockkit" || v === "block" || v === "blocks" || v === "rich")
+        return "blockkit";
+    if (v === "text" || v === "plain" || v === "txt")
+        return "text";
+    return fallback;
+}
+// ---------------------------------------------------------------------------
+// Routing
+//
+// PM_SLACK_ROUTES is an optional JSON array of rules that send specific events,
+// item types, or statuses to a different webhook/channel. Routing is purely
+// additive: with no rules configured, behavior is identical to before.
+// ---------------------------------------------------------------------------
+function parseRoutes(spec) {
+    if (!spec || !spec.trim())
+        return [];
+    let raw;
+    try {
+        raw = JSON.parse(spec);
+    }
+    catch {
+        console.error("[pm-slack] PM_SLACK_ROUTES is not valid JSON — routing disabled");
+        return [];
+    }
+    if (!Array.isArray(raw)) {
+        console.error("[pm-slack] PM_SLACK_ROUTES must be a JSON array — routing disabled");
+        return [];
+    }
+    const rules = [];
+    for (const entry of raw) {
+        if (!entry || typeof entry !== "object")
+            continue;
+        const e = entry;
+        const match = typeof e.match === "string" ? e.match.trim() : "";
+        if (!match)
+            continue;
+        const webhook = typeof e.webhook === "string" && e.webhook.trim() ? e.webhook.trim() : undefined;
+        const channel = typeof e.channel === "string" && e.channel.trim() ? e.channel.trim() : undefined;
+        if (!webhook && !channel)
+            continue; // a rule with no override is meaningless
+        rules.push({ match, webhook, channel });
+    }
+    return rules;
+}
+/**
+ * Does a single route rule match this event/item? Selector forms:
+ *   - bare event name: "create" | "close" | "block"
+ *   - "type:<itemType>"   (case-insensitive on item.type)
+ *   - "status:<status>"   (case-insensitive on item.status)
+ *   - "*" / "all"         (matches everything — useful as a catch-all)
+ */
+function ruleMatches(rule, event, item) {
+    const sel = rule.match.toLowerCase();
+    if (sel === "*" || sel === "all")
+        return true;
+    if (sel.startsWith("type:")) {
+        return (item.type ?? "").toLowerCase() === sel.slice("type:".length).trim();
+    }
+    if (sel.startsWith("status:")) {
+        return (item.status ?? "").toLowerCase() === sel.slice("status:".length).trim();
+    }
+    return sel === event;
+}
+/**
+ * Resolve the destination (webhook + channel) for an event/item given the
+ * configured routes and the default webhook/channel. First matching rule wins;
+ * any field a rule omits falls back to the default. Returns null only when no
+ * webhook can be resolved at all.
+ */
+function selectRoute(event, item, routes, defaultWebhook, defaultChannel) {
+    for (const rule of routes) {
+        if (ruleMatches(rule, event, item)) {
+            const webhookUrl = rule.webhook ?? defaultWebhook;
+            if (!webhookUrl)
+                return null;
+            return { webhookUrl, channel: rule.channel ?? defaultChannel };
+        }
+    }
+    if (!defaultWebhook)
+        return null;
+    return { webhookUrl: defaultWebhook, channel: defaultChannel };
+}
 function loadConfig() {
     const webhookUrl = process.env.PM_SLACK_WEBHOOK ?? "";
-    if (!webhookUrl) {
+    const routes = parseRoutes(process.env.PM_SLACK_ROUTES);
+    // A default webhook is not strictly required if routing rules carry their own
+    // webhook(s); only bail out when there is no webhook source at all.
+    const routesHaveWebhook = routes.some((r) => r.webhook);
+    if (!webhookUrl && !routesHaveWebhook) {
         console.error("[pm-slack] PM_SLACK_WEBHOOK not set — notifications disabled");
         return null;
     }
-    // Validate URL
-    try {
-        new URL(webhookUrl);
-    }
-    catch {
-        console.error("[pm-slack] PM_SLACK_WEBHOOK is not a valid URL — notifications disabled");
-        return null;
+    // Validate the default URL when present (route webhooks are validated lazily).
+    if (webhookUrl) {
+        try {
+            new URL(webhookUrl);
+        }
+        catch {
+            console.error("[pm-slack] PM_SLACK_WEBHOOK is not a valid URL — notifications disabled");
+            return null;
+        }
     }
     const channel = process.env.PM_SLACK_CHANNEL?.trim() || undefined;
     const rawPriority = parseInt(process.env.PM_SLACK_MIN_PRIORITY ?? "1", 10);
     const minPriority = rawPriority >= 1 && rawPriority <= 4 ? rawPriority : 1;
     const events = parseEvents(process.env.PM_SLACK_EVENTS);
-    return { webhookUrl, channel, minPriority, events };
+    const format = parseFormat(process.env.PM_SLACK_FORMAT);
+    const assigneeMap = parseAssigneeMap(process.env.PM_SLACK_ASSIGNEE_MAP);
+    // Mentions are auto-enabled in the hook whenever a non-empty map is present;
+    // PM_SLACK_MENTION_ASSIGNEE=0/false can force them off even with a map.
+    const mentionEnv = (process.env.PM_SLACK_MENTION_ASSIGNEE ?? "").trim().toLowerCase();
+    const mentionAssignee = mentionEnv === "0" || mentionEnv === "false" || mentionEnv === "no" || mentionEnv === "off"
+        ? false
+        : assigneeMap.size > 0;
+    return { webhookUrl, channel, minPriority, events, format, routes, assigneeMap, mentionAssignee };
 }
 // ---------------------------------------------------------------------------
 // Priority helpers
@@ -126,6 +287,89 @@ function meetsMinPriority(item, minPriority) {
     return item.priority <= minPriority;
 }
 // ---------------------------------------------------------------------------
+// Assignee → Slack @mention mapping
+//
+// PM_SLACK_ASSIGNEE_MAP maps a pm item's assignee to a Slack user/group id so
+// notifications can @-mention the responsible person. Format is a comma-list of
+// `name=id` pairs, e.g. PM_SLACK_ASSIGNEE_MAP="alice=U123,bob=U456". Slack
+// renders <@U123> as a user mention and <!subteam^S123> for groups; we accept a
+// raw id (wrapped as <@id>) or a pre-wrapped token (kept verbatim). Mapping is
+// opt-in and additive — when unset, output is byte-identical to before.
+// ---------------------------------------------------------------------------
+/** Parse PM_SLACK_ASSIGNEE_MAP into a case-insensitive name→id lookup. */
+function parseAssigneeMap(spec) {
+    const map = new Map();
+    if (!spec || !spec.trim())
+        return map;
+    for (const pair of spec.split(",")) {
+        const eq = pair.indexOf("=");
+        if (eq <= 0)
+            continue;
+        const name = pair.slice(0, eq).trim().toLowerCase();
+        const id = pair.slice(eq + 1).trim();
+        if (name && id)
+            map.set(name, id);
+    }
+    return map;
+}
+/**
+ * Resolve an item's assignee to a Slack mention token using the map. Returns a
+ * ready-to-embed mention string (e.g. `<@U123>`) or undefined when there's no
+ * assignee or no mapping. A raw id is wrapped as `<@id>`; a token already
+ * containing `<` is passed through unchanged (supports `<!subteam^S123>` etc).
+ */
+function resolveAssigneeMention(item, map) {
+    const assignee = item.assignee?.trim();
+    if (!assignee || map.size === 0)
+        return undefined;
+    const id = map.get(assignee.toLowerCase());
+    if (!id)
+        return undefined;
+    return id.startsWith("<") ? id : `<@${id}>`;
+}
+// ---------------------------------------------------------------------------
+// Item URL extraction (for Block Kit action buttons)
+//
+// pm has no canonical URL field, so read a defensive set of common field names
+// off the item; the first valid http(s) URL wins. Used to render an "Open item"
+// / "View on GitHub" action button in the Block Kit notification (Feature 3).
+// ---------------------------------------------------------------------------
+function isHttpUrl(value) {
+    if (typeof value !== "string")
+        return false;
+    const v = value.trim();
+    if (!v)
+        return false;
+    try {
+        const u = new URL(v);
+        return u.protocol === "http:" || u.protocol === "https:";
+    }
+    catch {
+        return false;
+    }
+}
+/** Resolve a primary URL for the item, plus whether it points at GitHub. */
+function resolveItemUrl(item, override) {
+    const candidates = [
+        override,
+        item.github_url,
+        item.githubUrl,
+        item.html_url,
+        item.htmlUrl,
+        item.url,
+        item.source_url,
+        item.sourceUrl,
+        item.link,
+    ];
+    for (const c of candidates) {
+        if (isHttpUrl(c)) {
+            const url = c.trim();
+            return { url, isGithub: /(^|\.)github\.com$/i.test(new URL(url).hostname) };
+        }
+    }
+    return undefined;
+}
+// ---------------------------------------------------------------------------
 // Plain-text message formatting (fallback)
 // ---------------------------------------------------------------------------
 function itemTypeLabel(item) {
@@ -135,26 +379,47 @@ const EVENT_META = {
     create: { verb: "created", emoji: "🆕" },
     close: { verb: "closed", emoji: "✅" },
     block: { verb: "is blocked", emoji: "🚫" },
+    cancel: { verb: "canceled", emoji: "🛑" },
+    open: { verb: "opened", emoji: "📂" },
+    start: { verb: "started", emoji: "🔄" },
+    unblock: { verb: "unblocked", emoji: "🔓" },
+    reopen: { verb: "reopened", emoji: "♻️" },
 };
 function eventReason(item, event) {
     if (event === "close") {
         return item.close_reason?.trim() || item.closedReason?.trim() || undefined;
     }
+    if (event === "cancel") {
+        // pm persists the cancel reason in close_reason; honor a dedicated
+        // cancel_reason first if a future pm version introduces one.
+        return (item.cancel_reason?.trim() ||
+            item.cancelReason?.trim() ||
+            item.close_reason?.trim() ||
+            item.closedReason?.trim() ||
+            undefined);
+    }
     if (event === "block") {
         return item.blocked_reason?.trim() || item.blockedReason?.trim() || undefined;
     }
     return undefined;
 }
-function buildTextMessage(item, event, channel) {
+function buildTextMessage(item, event, channel, mention) {
     const type = itemTypeLabel(item);
     const meta = EVENT_META[event];
     let msg = `*[${type}]* ${item.title} ${meta.verb} ${meta.emoji}`;
     if (event === "create") {
         msg += `\nPriority: ${priorityLabel(item.priority)} • Type: ${type} • By: ${item.author ?? "unknown"}`;
     }
-    else {
+    else if (event === "close" || event === "cancel" || event === "block") {
+        // Terminal/blocked transitions carry a reason field.
         msg += `\nReason: ${eventReason(item, event) ?? "no reason given"}`;
     }
+    else {
+        // Status transitions without a reason (open/start/unblock/reopen).
+        msg += `\nStatus: ${item.status ?? meta.verb}${item.assignee ? ` • Assignee: ${item.assignee}` : ""}`;
+    }
+    if (mention)
+        msg += `\nAssignee: ${mention}`;
     if (channel)
         msg += `\n_Channel: ${channel}_`;
     return msg;
@@ -178,6 +443,12 @@ function buildItemBlockKit(item, event, opts = {}) {
         fields.push({ type: "mrkdwn", text: `*Status:*\n${item.status}` });
     if (item.author)
         fields.push({ type: "mrkdwn", text: `*By:*\n${item.author}` });
+    // Assignee mention (Feature 2): show the @mention when mapped, else the raw
+    // assignee name so the field is still useful without a configured map.
+    if (opts.mention)
+        fields.push({ type: "mrkdwn", text: `*Assignee:*\n${opts.mention}` });
+    else if (item.assignee)
+        fields.push({ type: "mrkdwn", text: `*Assignee:*\n${item.assignee}` });
     blocks.push({ type: "section", fields });
     const reason = eventReason(item, event);
     if (reason) {
@@ -192,6 +463,24 @@ function buildItemBlockKit(item, event, opts = {}) {
             text: { type: "mrkdwn", text: opts.note },
         });
     }
+    // Action buttons (Feature 3): a link button to the item / GitHub URL when one
+    // is present on the item. Block Kit "actions" with a url-bearing button needs
+    // no interactivity backend — it opens the URL directly. Plain-text path is
+    // unaffected (this only runs for the blockkit format).
+    if (opts.link) {
+        const label = opts.link.isGithub ? "View on GitHub" : "Open item";
+        blocks.push({
+            type: "actions",
+            elements: [
+                {
+                    type: "button",
+                    text: { type: "plain_text", text: label, emoji: true },
+                    url: opts.link.url,
+                    action_id: opts.link.isGithub ? "pm_slack_open_github" : "pm_slack_open_item",
+                },
+            ],
+        });
+    }
     const footerBits = [
         `pm item ${item.id} ${meta.verb}`,
         opts.channel ? `channel ${opts.channel}` : null,
@@ -200,9 +489,32 @@ function buildItemBlockKit(item, event, opts = {}) {
         type: "context",
         elements: [{ type: "mrkdwn", text: `🤖 pm-slack · ${footerBits.join(" · ")}` }],
     });
-    const fallback = buildTextMessage(item, event, opts.channel);
+    const fallback = buildTextMessage(item, event, opts.channel, opts.mention);
     return { blocks, fallback };
 }
+/**
+ * Build a ready-to-post SlackPayload for an item event in the requested format.
+ * - "blockkit": rich Block Kit blocks + plain-text fallback in `text`.
+ * - "text":     plain mrkdwn only (no `blocks`), for minimal/legacy channels.
+ */
+function buildItemPayload(item, event, format, opts = {}) {
+    if (format === "text") {
+        const text = buildTextMessage(item, event, opts.channel, opts.mention);
+        const body = opts.note && opts.note.trim() ? `${text}\n${opts.note.trim()}` : text;
+        return {
+            text: body,
+            mrkdwn: true,
+            ...(opts.channel ? { channel: opts.channel } : {}),
+        };
+    }
+    const { blocks, fallback } = buildItemBlockKit(item, event, opts);
+    return {
+        text: fallback,
+        blocks,
+        mrkdwn: true,
+        ...(opts.channel ? { channel: opts.channel } : {}),
+    };
+}
 // ---------------------------------------------------------------------------
 // Slack HTTP POST
 // ---------------------------------------------------------------------------
@@ -246,6 +558,245 @@ function postToSlack(webhookUrl, payload) {
     });
 }
 // ---------------------------------------------------------------------------
+// Digest: reading the pm store + activity aggregation
+//
+// The digest reads items directly from the pm store (`<pm_root>/<dir>/*.toon`
+// and `*.json`) using a tiny scalar parser — we only need a handful of
+// top-level fields (id/title/type/status/priority/timestamps/reasons). This
+// avoids a runtime dependency on the pm SDK service layer (registerService is
+// limited and corrupts output, #96) and keeps the package dependency-free.
+// ---------------------------------------------------------------------------
+/** Directories under a pm root that hold items, by convention. */
+const ITEM_DIRS = ["tasks", "features", "issues", "epics", "stories", "bugs", "decisions", "items"];
+/**
+ * Minimal parser for a stored pm item file. Handles the toon scalar form
+ * (`key: value`, optionally quoted) and JSON. Only top-level scalar fields are
+ * extracted; nested/array sections are ignored. Returns null when no id found.
+ */
+function parseStoredItem(content, ext) {
+    if (ext === ".json") {
+        try {
+            const obj = JSON.parse(content);
+            const node = (obj.item ?? obj);
+            if (typeof node.id !== "string")
+                return null;
+            return node;
+        }
+        catch {
+            return null;
+        }
+    }
+    // toon: line-oriented `key: value`. Stop reading a key when it introduces a
+    // block/array (e.g. `notes[1]{...}:`); we only want flat scalars.
+    const out = {};
+    for (const rawLine of content.split(/\r?\n/)) {
+        const line = rawLine;
+        if (!line || /^\s/.test(line))
+            continue; // skip indented (nested) lines
+        const m = /^([A-Za-z_][A-Za-z0-9_]*)\s*:\s*(.*)$/.exec(line);
+        if (!m)
+            continue;
+        const key = m[1];
+        let value = m[2].trim();
+        if (value === "" || value === '""') {
+            out[key] = "";
+            continue;
+        }
+        // Strip surrounding double quotes (toon quotes strings with embedded chars).
+        if (value.startsWith('"') && value.endsWith('"') && value.length >= 2) {
+            value = value.slice(1, -1).replace(/\\"/g, '"');
+        }
+        out[key] = value;
+    }
+    if (typeof out.id !== "string")
+        return null;
+    if (typeof out.priority === "string" && /^\d+$/.test(out.priority)) {
+        out.priority = parseInt(out.priority, 10);
+    }
+    return out;
+}
+/** Read all items from a pm root. Best-effort: unreadable files are skipped. */
+function readStoreItems(pmRoot) {
+    const items = [];
+    for (const dir of ITEM_DIRS) {
+        const full = path.join(pmRoot, dir);
+        let entries;
+        try {
+            entries = fs.readdirSync(full);
+        }
+        catch {
+            continue;
+        }
+        for (const name of entries) {
+            const ext = path.extname(name);
+            if (ext !== ".toon" && ext !== ".json")
+                continue;
+            try {
+                const content = fs.readFileSync(path.join(full, name), "utf8");
+                const item = parseStoredItem(content, ext);
+                if (item)
+                    items.push(item);
+            }
+            catch {
+                // skip unreadable item
+            }
+        }
+    }
+    return items;
+}
+/**
+ * Resolve a `--since <date>` / `--days <n>` window into an epoch-ms cutoff.
+ * `since` (ISO date or datetime) wins when both are given; otherwise `days`
+ * back from `now`. Defaults to 7 days. Returns the cutoff in ms.
+ */
+function resolveWindow(since, days, now = Date.now()) {
+    if (since) {
+        const t = Date.parse(since);
+        if (!Number.isNaN(t)) {
+            return { cutoffMs: t, label: `since ${since}` };
+        }
+    }
+    const d = days !== undefined && Number.isFinite(days) && days > 0 ? Math.floor(days) : 7;
+    return { cutoffMs: now - d * 24 * 60 * 60 * 1000, label: `last ${d} day${d === 1 ? "" : "s"}` };
+}
+function statusIsClosed(status) {
+    const s = (status ?? "").toLowerCase();
+    return s === "closed" || s === "done" || s === "resolved" || s === "complete" || s === "completed";
+}
+/**
+ * Aggregate store items into digest buckets for the window. An item counts as:
+ *   - created     if created_at >= cutoff
+ *   - closed      if it is in a closed/done status AND updated_at >= cutoff
+ *   - blocked     if status === blocked AND updated_at >= cutoff
+ *   - in_progress if status === in_progress AND updated_at >= cutoff
+ * An item may appear in multiple buckets (e.g. created and blocked).
+ */
+function aggregateDigest(items, cutoffMs, windowLabel) {
+    const buckets = {
+        created: [],
+        closed: [],
+        blocked: [],
+        in_progress: [],
+    };
+    for (const item of items) {
+        const created = item.created_at ? Date.parse(item.created_at) : NaN;
+        const updated = item.updated_at ? Date.parse(item.updated_at) : created;
+        const status = (item.status ?? "").toLowerCase();
+        if (!Number.isNaN(created) && created >= cutoffMs)
+            buckets.created.push(item);
+        if (statusIsClosed(status) && !Number.isNaN(updated) && updated >= cutoffMs)
+            buckets.closed.push(item);
+        if (status === "blocked" && !Number.isNaN(updated) && updated >= cutoffMs)
+            buckets.blocked.push(item);
+        if (status === "in_progress" && !Number.isNaN(updated) && updated >= cutoffMs)
+            buckets.in_progress.push(item);
+    }
+    const counts = {
+        created: buckets.created.length,
+        closed: buckets.closed.length,
+        blocked: buckets.blocked.length,
+        in_progress: buckets.in_progress.length,
+    };
+    const total = counts.created + counts.closed + counts.blocked + counts.in_progress;
+    return { windowLabel, cutoffMs, counts, buckets, total };
+}
+const DIGEST_BUCKET_META = {
+    created: { label: "Created", emoji: "🆕" },
+    closed: { label: "Closed", emoji: "✅" },
+    blocked: { label: "Blocked", emoji: "🚫" },
+    in_progress: { label: "In progress", emoji: "🔄" },
+};
+const DIGEST_ORDER = ["created", "closed", "in_progress", "blocked"];
+/** A short "id title" line per item, capped so the digest stays readable. */
+function digestItemLines(items, max = 5) {
+    const lines = items.slice(0, max).map((i) => `• ${i.id} — ${i.title ?? "(untitled)"}`);
+    if (items.length > max)
+        lines.push(`• …and ${items.length - max} more`);
+    return lines;
+}
+function buildDigestText(summary, channel) {
+    const head = `*pm activity digest* (${summary.windowLabel}) — ${summary.total} update${summary.total === 1 ? "" : "s"}`;
+    const parts = [head];
+    for (const bucket of DIGEST_ORDER) {
+        const items = summary.buckets[bucket];
+        if (items.length === 0)
+            continue;
+        const meta = DIGEST_BUCKET_META[bucket];
+        parts.push(`\n${meta.emoji} *${meta.label}* (${items.length})`);
+        parts.push(digestItemLines(items).join("\n"));
+    }
+    if (summary.total === 0)
+        parts.push("\n_No activity in this window._");
+    if (channel)
+        parts.push(`\n_Channel: ${channel}_`);
+    return parts.join("\n");
+}
+function buildDigestBlockKit(summary, channel) {
+    const blocks = [];
+    blocks.push({
+        type: "header",
+        text: { type: "plain_text", text: `📊 pm activity digest`, emoji: true },
+    });
+    blocks.push({
+        type: "context",
+        elements: [
+            {
+                type: "mrkdwn",
+                text: `${summary.windowLabel} · ${summary.total} update${summary.total === 1 ? "" : "s"}`,
+            },
+        ],
+    });
+    // Counts grid.
+    const fields = DIGEST_ORDER.map((bucket) => {
+        const meta = DIGEST_BUCKET_META[bucket];
+        return { type: "mrkdwn", text: `${meta.emoji} *${meta.label}:*\n${summary.counts[bucket]}` };
+    });
+    blocks.push({ type: "section", fields });
+    for (const bucket of DIGEST_ORDER) {
+        const items = summary.buckets[bucket];
+        if (items.length === 0)
+            continue;
+        const meta = DIGEST_BUCKET_META[bucket];
+        blocks.push({ type: "divider" });
+        blocks.push({
+            type: "section",
+            text: {
+                type: "mrkdwn",
+                text: `${meta.emoji} *${meta.label}* (${items.length})\n${digestItemLines(items).join("\n")}`,
+            },
+        });
+    }
+    if (summary.total === 0) {
+        blocks.push({
+            type: "section",
+            text: { type: "mrkdwn", text: "_No activity in this window._" },
+        });
+    }
+    const footerBits = [`pm digest · ${summary.windowLabel}`, channel ? `channel ${channel}` : null].filter(Boolean);
+    blocks.push({
+        type: "context",
+        elements: [{ type: "mrkdwn", text: `🤖 pm-slack · ${footerBits.join(" · ")}` }],
+    });
+    const fallback = buildDigestText(summary, channel);
+    return { blocks, fallback };
+}
+function buildDigestPayload(summary, format, channel) {
+    if (format === "text") {
+        return {
+            text: buildDigestText(summary, channel),
+            mrkdwn: true,
+            ...(channel ? { channel } : {}),
+        };
+    }
+    const { blocks, fallback } = buildDigestBlockKit(summary, channel);
+    return {
+        text: fallback,
+        blocks,
+        mrkdwn: true,
+        ...(channel ? { channel } : {}),
+    };
+}
+// ---------------------------------------------------------------------------
 // Event detection (afterCommand hook)
 // ---------------------------------------------------------------------------
 /** Commands that create a new item */
@@ -254,23 +805,74 @@ const CREATE_COMMANDS = new Set(["add", "create", "new"]);
 const CLOSE_COMMANDS = new Set(["close", "done", "complete", "finish", "resolve"]);
 /** Commands that update an item's status or attributes */
 const UPDATE_COMMANDS = new Set(["update", "edit", "set", "status"]);
+/** Lifecycle-alias commands that move an item to in_progress (start). */
+const START_COMMANDS = new Set(["claim", "start-task", "start", "begin"]);
+/** Lifecycle-alias commands that move an item back to open (e.g. pause). */
+const OPEN_COMMANDS = new Set(["pause-task", "release", "reopen", "publish"]);
+/** Map a (normalized) status string to the EventKind for a transition into it. */
+function statusToEvent(status) {
+    switch ((status ?? "").toLowerCase()) {
+        case "blocked":
+            return "block";
+        case "canceled":
+        case "cancelled":
+            return "cancel";
+        case "closed":
+        case "done":
+        case "resolved":
+        case "complete":
+        case "completed":
+            return "close";
+        case "in_progress":
+        case "in-progress":
+            return "start";
+        case "open":
+            return "open";
+        default:
+            return null;
+    }
+}
+/**
+ * Detect the lifecycle event for a completed command. Strategy:
+ *   1. Create/close commands map directly.
+ *   2. Status-changing commands (update/set/lifecycle aliases) derive the event
+ *      from the *resulting* status (preferring the explicit --status option,
+ *      falling back to the result item's status).
+ *   3. When the result carries the prior status (`previousStatus`), refine
+ *      open→reopen (from a closed/canceled state) and open→unblock (from
+ *      blocked) so terminal-recovery transitions are distinguishable.
+ */
 function detectEvent(ctx) {
     const cmd = ctx.command?.toLowerCase() ?? "";
     if (CREATE_COMMANDS.has(cmd))
         return "create";
     if (CLOSE_COMMANDS.has(cmd))
         return "close";
-    if (UPDATE_COMMANDS.has(cmd)) {
-        const newStatus = ctx.options?.["status"] ??
-            ctx.result?.item?.status ??
-            "";
-        if (newStatus.toLowerCase() === "blocked")
-            return "block";
-        const resultItem = ctx.result?.item;
-        if (resultItem?.status?.toLowerCase() === "blocked")
-            return "block";
+    const result = ctx.result;
+    const resultStatus = result?.item?.status;
+    const prevStatus = (result?.previousStatus ?? result?.previous_status ?? "").toLowerCase();
+    // Lifecycle aliases imply a target status even without --status.
+    let event = null;
+    if (START_COMMANDS.has(cmd))
+        event = "start";
+    else if (OPEN_COMMANDS.has(cmd))
+        event = cmd === "reopen" ? "reopen" : "open";
+    if (!event && UPDATE_COMMANDS.has(cmd)) {
+        const optStatus = ctx.options?.["status"];
+        event = statusToEvent(optStatus) ?? statusToEvent(resultStatus);
     }
-    return null;
+    if (!event)
+        return null;
+    // Refine an "open" transition using the prior status when available:
+    //   blocked  -> open  => unblock
+    //   closed/canceled -> open => reopen
+    if (event === "open" && prevStatus) {
+        if (prevStatus === "blocked")
+            return "unblock";
+        if (["closed", "canceled", "cancelled", "done", "resolved"].includes(prevStatus))
+            return "reopen";
+    }
+    return event;
 }
 function extractItem(ctx) {
     const result = ctx.result;
@@ -289,7 +891,7 @@ function extractItem(ctx) {
 // ---------------------------------------------------------------------------
 export default defineExtension({
     name: "pm-slack",
-    version: "2026.6.2",
+    version: "2026.6.4",
     activate(api) {
         // -----------------------------------------------------------------------
         // afterCommand hook — fires after every pm-cli command completes.
@@ -322,15 +924,22 @@ export default defineExtension({
                         console.error(`[pm-slack] Item priority ${item.priority} below minimum ${config.minPriority} — skipping`);
                         return;
                     }
-                    const { blocks, fallback } = buildItemBlockKit(item, event, {
-                        channel: config.channel,
-                    });
-                    await postToSlack(config.webhookUrl, {
-                        text: fallback,
-                        blocks,
-                        mrkdwn: true,
-                        channel: config.channel,
+                    // Resolve destination via routing rules (falls back to defaults).
+                    const target = selectRoute(event, item, config.routes, config.webhookUrl, config.channel);
+                    if (!target) {
+                        console.error(`[pm-slack] No webhook resolved for event "${event}" — skipping`);
+                        return;
+                    }
+                    const mention = config.mentionAssignee
+                        ? resolveAssigneeMention(item, config.assigneeMap)
+                        : undefined;
+                    const link = resolveItemUrl(item);
+                    const payload = buildItemPayload(item, event, config.format, {
+                        channel: target.channel,
+                        mention,
+                        link,
                     });
+                    await postToSlack(target.webhookUrl, payload);
                     console.error(`[pm-slack] Notification sent for event "${event}" on item ${item.id}`);
                 }
                 catch (err) {
@@ -386,9 +995,14 @@ export default defineExtension({
                     { long: "--title", value_name: "title", description: "Title shown in the Block Kit header (defaults to the --text first line)" },
                     { long: "--channel", value_name: "name", description: "Channel name shown in the message (e.g. #pm-alerts). Overrides PM_SLACK_CHANNEL." },
                     { long: "--thread", value_name: "ts", description: "Slack thread timestamp (thread_ts) to reply into a thread" },
-                    { long: "--on", value_name: "events", description: "Comma list of lifecycle events for the message template (create,close,block). Default: create" },
+                    { long: "--on", value_name: "events", description: "Comma list of lifecycle events for the message template (create,close,block,cancel,open,start,unblock,reopen). Default: create" },
+                    { long: "--format", value_name: "fmt", description: "Message format: blockkit (default) or text. Overrides PM_SLACK_FORMAT." },
+                    { long: "--assignee", value_name: "name", description: "Assignee name shown on the message (mapped to a Slack @mention via PM_SLACK_ASSIGNEE_MAP)" },
+                    { long: "--mention-assignee", description: "Resolve the assignee to a Slack @mention using PM_SLACK_ASSIGNEE_MAP" },
+                    { long: "--url", value_name: "url", description: "Add a Block Kit action button linking to this URL (e.g. a GitHub item)" },
                     { long: "--webhook", value_name: "url", description: "Slack incoming webhook URL (overrides PM_SLACK_WEBHOOK env var)" },
-                    { long: "--dry-run", description: "Print the message and Block Kit payload without posting to Slack" },
+                    { long: "--dry-run", description: "Print the message and payload without posting to Slack" },
+                    { long: "--json", description: "Emit the result/payload as JSON (machine-readable)" },
                 ],
                 async run(ctx) {
                     const options = ctx.options ?? {};
@@ -396,6 +1010,8 @@ export default defineExtension({
                     const webhookUrl = readStrOption(options, "webhook") ?? process.env.PM_SLACK_WEBHOOK ?? "";
                     const channel = (readStrOption(options, "channel") ?? process.env.PM_SLACK_CHANNEL?.trim()) || undefined;
                     const threadTs = readStrOption(options, "thread");
+                    const asJson = ctx.global?.json === true || readBoolOption(options, "json");
+                    const format = parseFormat(readStrOption(options, "format") ?? process.env.PM_SLACK_FORMAT);
                     // `--on` selects the message template. First event wins for the header verb.
                     const events = parseEvents(readStrOption(options, "on") ?? "create");
                     const event = (ALL_EVENTS.find((e) => events.has(e)) ?? "create");
@@ -404,27 +1020,35 @@ export default defineExtension({
                     if (!title) {
                         throw new CommandError("Provide a --title or --text to send (e.g. `pm slack notify --text 'hello'`)", EXIT_CODE.USAGE);
                     }
-                    // Synthesize a minimal item from the flags so we can reuse the Block
-                    // Kit builder. This command is for ad-hoc posts, not item lookups.
-                    const item = { id: "manual", title, type: "Note" };
-                    const { blocks, fallback } = buildItemBlockKit(item, event, {
-                        channel,
-                        note: text && text !== title ? text : undefined,
-                    });
+                    // Synthesize a minimal item from the flags so we can reuse the
+                    // message builder. This command is for ad-hoc posts, not item lookups.
+                    const assignee = readStrOption(options, "assignee");
+                    const url = readStrOption(options, "url");
+                    const item = { id: "manual", title, type: "Note", ...(assignee ? { assignee } : {}) };
+                    const assigneeMap = parseAssigneeMap(process.env.PM_SLACK_ASSIGNEE_MAP);
+                    // Mention when explicitly requested, or implicitly when an assignee
+                    // maps to a Slack id (so the @mention is opt-in but ergonomic).
+                    const wantMention = readBoolOption(options, "mention-assignee") || assigneeMap.size > 0;
+                    const mention = wantMention ? resolveAssigneeMention(item, assigneeMap) : undefined;
+                    const link = resolveItemUrl(item, url);
                     const payload = {
-                        text: fallback,
-                        blocks,
-                        mrkdwn: true,
-                        ...(channel ? { channel } : {}),
+                        ...buildItemPayload(item, event, format, {
+                            channel,
+                            note: text && text !== title ? text : undefined,
+                            mention,
+                            link,
+                        }),
                         ...(threadTs ? { thread_ts: threadTs } : {}),
                     };
                     if (dryRun) {
-                        console.error("--- DRY RUN (message not posted) ---");
-                        process.stdout.write(fallback + "\n");
-                        console.error("--- Block Kit payload ---");
-                        process.stdout.write(JSON.stringify(payload, null, 2) + "\n");
-                        console.error("--- END ---");
-                        return { dryRun: true, event, channel, thread_ts: threadTs, blocks, fallback };
+                        if (!asJson) {
+                            console.error("--- DRY RUN (message not posted) ---");
+                            process.stdout.write(payload.text + "\n");
+                            console.error(`--- ${format} payload ---`);
+                            process.stdout.write(JSON.stringify(payload, null, 2) + "\n");
+                            console.error("--- END ---");
+                        }
+                        return { dryRun: true, event, format, channel, thread_ts: threadTs, payload };
                     }
                     if (!webhookUrl) {
                         // Graceful no-op: warn and exit 0 so a missing webhook never blocks
@@ -445,17 +1069,167 @@ export default defineExtension({
                     return { posted: true, event, channel, thread_ts: threadTs };
                 },
             });
+            // ---------------------------------------------------------------------
+            // command — `pm slack test` : build and PRINT a sample notification in
+            // the chosen format WITHOUT posting. Fully offline; the package is
+            // testable with no Slack credentials. Honors --json for machine reads.
+            // ---------------------------------------------------------------------
+            api.registerCommand({
+                name: "slack test",
+                description: "Preview a sample pm-slack notification in the chosen format without posting (offline)",
+                intent: "Preview Slack notification formatting offline (no webhook, no network)",
+                examples: [
+                    "pm slack test --format blockkit",
+                    "pm slack test --format text --on close",
+                    "pm slack test --on block --json",
+                    "pm slack test --on cancel",
+                    "PM_SLACK_ASSIGNEE_MAP='alice=U123' pm slack test --on start --mention-assignee",
+                ],
+                flags: [
+                    { long: "--format", value_name: "fmt", description: "Message format: blockkit (default) or text. Overrides PM_SLACK_FORMAT." },
+                    { long: "--on", value_name: "event", description: "Lifecycle event to preview (create,close,block,cancel,open,start,unblock,reopen). Default: create" },
+                    { long: "--title", value_name: "title", description: "Sample item title (default: a representative example)" },
+                    { long: "--channel", value_name: "name", description: "Channel hint to show in the preview (overrides PM_SLACK_CHANNEL)" },
+                    { long: "--mention-assignee", description: "Resolve the sample assignee to a Slack @mention via PM_SLACK_ASSIGNEE_MAP" },
+                    { long: "--url", value_name: "url", description: "Add a Block Kit action button linking to this URL (default: a sample GitHub URL)" },
+                    { long: "--json", description: "Emit the preview payload as JSON" },
+                    { long: "--dry-run", description: "Accepted for symmetry; this command never posts." },
+                ],
+                async run(ctx) {
+                    const options = ctx.options ?? {};
+                    // `--json` is consumed by pm as a global flag, so prefer global.json;
+                    // also honor a local --json for robustness across runtimes.
+                    const asJson = ctx.global?.json === true || readBoolOption(options, "json");
+                    const format = parseFormat(readStrOption(options, "format") ?? process.env.PM_SLACK_FORMAT);
+                    const channel = (readStrOption(options, "channel") ?? process.env.PM_SLACK_CHANNEL?.trim()) || undefined;
+                    const events = parseEvents(readStrOption(options, "on") ?? "create");
+                    const event = (ALL_EVENTS.find((e) => events.has(e)) ?? "create");
+                    const t = readStrOption(options, "title");
+                    // A representative sample item per event so the preview is realistic.
+                    const sample = {
+                        create: { id: "pm-1a2b", title: t ?? "Add OAuth login flow", type: "Feature", priority: 2, status: "open", author: "alice", assignee: "alice", github_url: "https://github.com/unbraind/pm-slack/issues/1" },
+                        close: { id: "pm-3c4d", title: t ?? "Fix login redirect bug", type: "Issue", priority: 1, status: "closed", author: "bob", assignee: "bob", close_reason: "Fixed in commit abc123", github_url: "https://github.com/unbraind/pm-slack/issues/2" },
+                        block: { id: "pm-5e6f", title: t ?? "Dashboard redesign", type: "Epic", priority: 2, status: "blocked", author: "carol", assignee: "carol", blocked_reason: "Waiting on design approval" },
+                        cancel: { id: "pm-7g8h", title: t ?? "Legacy export pipeline", type: "Task", priority: 3, status: "canceled", author: "dave", assignee: "dave", close_reason: "Superseded by new pipeline" },
+                        open: { id: "pm-9i0j", title: t ?? "Publish onboarding guide", type: "Task", priority: 3, status: "open", author: "erin", assignee: "erin" },
+                        start: { id: "pm-1k2l", title: t ?? "Implement rate limiter", type: "Feature", priority: 2, status: "in_progress", author: "frank", assignee: "frank", github_url: "https://github.com/unbraind/pm-slack/pull/3" },
+                        unblock: { id: "pm-3m4n", title: t ?? "Payment reconciliation", type: "Issue", priority: 1, status: "open", author: "grace", assignee: "grace" },
+                        reopen: { id: "pm-5o6p", title: t ?? "Flaky integration test", type: "Bug", priority: 2, status: "open", author: "heidi", assignee: "heidi" },
+                    };
+                    const item = sample[event];
+                    const assigneeMap = parseAssigneeMap(process.env.PM_SLACK_ASSIGNEE_MAP);
+                    const wantMention = readBoolOption(options, "mention-assignee") || assigneeMap.size > 0;
+                    const mention = wantMention ? resolveAssigneeMention(item, assigneeMap) : undefined;
+                    const link = resolveItemUrl(item, readStrOption(options, "url"));
+                    const payload = buildItemPayload(item, event, format, { channel, mention, link });
+                    // In JSON mode, pm renders the returned object — don't also write to
+                    // stdout (that would corrupt the JSON stream). In human mode, print a
+                    // readable preview to stdout/stderr.
+                    if (!asJson) {
+                        console.error(`--- PREVIEW (${format}, event=${event}) — nothing posted ---`);
+                        process.stdout.write(payload.text + "\n");
+                        console.error(`--- ${format} payload ---`);
+                        process.stdout.write(JSON.stringify(payload, null, 2) + "\n");
+                        console.error("--- END ---");
+                    }
+                    return { preview: true, event, format, channel, payload };
+                },
+            });
+            // ---------------------------------------------------------------------
+            // command — `pm slack digest` : summarize recent activity (created /
+            // closed / blocked / in-progress) over a --since/--days window into a
+            // single notification. Reads the pm store directly; --dry-run prints
+            // without posting.
+            // ---------------------------------------------------------------------
+            api.registerCommand({
+                name: "slack digest",
+                description: "Post (or preview) a single summary of recent pm activity over a time window",
+                intent: "Summarize recent pm activity (created/closed/blocked/in-progress) into one Slack message",
+                examples: [
+                    "pm slack digest --days 7 --dry-run",
+                    "pm slack digest --since 2026-06-01 --format text --dry-run",
+                    "pm slack digest --days 1 --format blockkit --json --dry-run",
+                ],
+                flags: [
+                    { long: "--since", value_name: "date", description: "Only include activity at/after this ISO date (e.g. 2026-06-01)" },
+                    { long: "--days", value_name: "n", description: "Look back N days from now (default 7; ignored when --since is given)" },
+                    { long: "--format", value_name: "fmt", description: "Message format: blockkit (default) or text. Overrides PM_SLACK_FORMAT." },
+                    { long: "--channel", value_name: "name", description: "Channel to post to (overrides PM_SLACK_CHANNEL)" },
+                    { long: "--webhook", value_name: "url", description: "Slack incoming webhook URL (overrides PM_SLACK_WEBHOOK)" },
+                    { long: "--dry-run", description: "Build and print the digest without posting to Slack" },
+                    { long: "--json", description: "Emit the digest summary/payload as JSON" },
+                ],
+                async run(ctx) {
+                    const options = ctx.options ?? {};
+                    const dryRun = readBoolOption(options, "dry-run");
+                    const asJson = ctx.global?.json === true || readBoolOption(options, "json");
+                    const format = parseFormat(readStrOption(options, "format") ?? process.env.PM_SLACK_FORMAT);
+                    const channel = (readStrOption(options, "channel") ?? process.env.PM_SLACK_CHANNEL?.trim()) || undefined;
+                    const webhookUrl = readStrOption(options, "webhook") ?? process.env.PM_SLACK_WEBHOOK ?? "";
+                    const since = readStrOption(options, "since");
+                    const daysStr = readStrOption(options, "days");
+                    const days = daysStr !== undefined ? parseInt(daysStr, 10) : undefined;
+                    if (daysStr !== undefined && (days === undefined || Number.isNaN(days) || days <= 0)) {
+                        throw new CommandError(`--days must be a positive integer (got "${daysStr}")`, EXIT_CODE.USAGE);
+                    }
+                    const pmRoot = ctx.pm_root ?? path.join(process.cwd(), ".agents", "pm");
+                    const { cutoffMs, label } = resolveWindow(since, days);
+                    const items = readStoreItems(pmRoot);
+                    const summary = aggregateDigest(items, cutoffMs, label);
+                    const payload = buildDigestPayload(summary, format, channel);
+                    if (dryRun) {
+                        if (!asJson) {
+                            console.error(`--- DRY RUN digest (${format}, ${label}) — nothing posted ---`);
+                            process.stdout.write(payload.text + "\n");
+                            console.error(`--- ${format} payload ---`);
+                            process.stdout.write(JSON.stringify(payload, null, 2) + "\n");
+                            console.error("--- END ---");
+                        }
+                        return { dryRun: true, format, channel, counts: summary.counts, total: summary.total, window: label, payload };
+                    }
+                    // Real post requested: a webhook is mandatory. Fail cleanly (exit 1).
+                    if (!webhookUrl) {
+                        throw new CommandError("No Slack webhook configured: set PM_SLACK_WEBHOOK or pass --webhook (or use --dry-run to preview).", EXIT_CODE.GENERIC_FAILURE);
+                    }
+                    try {
+                        await postToSlack(webhookUrl, payload);
+                    }
+                    catch (err) {
+                        const message = err instanceof Error ? err.message : String(err);
+                        throw new CommandError(`Failed to post digest to Slack: ${message}`, EXIT_CODE.GENERIC_FAILURE);
+                    }
+                    return { posted: true, format, channel, counts: summary.counts, total: summary.total, window: label };
+                },
+            });
         }
     },
 });
 // Exported for unit tests (Block Kit builder + helpers).
 export const __test__ = {
     buildItemBlockKit,
+    buildItemPayload,
     buildTextMessage,
     parseEvents,
+    normalizeEvent,
+    parseFormat,
+    parseRoutes,
+    ruleMatches,
+    selectRoute,
     detectEvent,
+    statusToEvent,
     extractItem,
     meetsMinPriority,
+    parseAssigneeMap,
+    resolveAssigneeMention,
+    resolveItemUrl,
+    isHttpUrl,
+    EVENT_META,
+    parseStoredItem,
+    resolveWindow,
+    aggregateDigest,
+    buildDigestText,
+    buildDigestBlockKit,
+    buildDigestPayload,
     EXIT_CODE,
     CommandError,
 };