@gr8ful/spf 0.13.0 → 0.14.0

package/README.md

@@ -839,6 +839,22 @@ Getting each channel's URL:
 - **webhook** — any endpoint that accepts a JSON POST of the event: Discord,
   n8n, Zapier, a homegrown receiver.
 
+One webhook, many `spf` instances: if several repos' `spf watch` (or
+`spf run`) all post to the same Slack/Teams/webhook endpoint, set
+`notifications.project` to a short label so messages from each are
+distinguishable — it prefixes every title (`[api] watch: reconcileOrphans
+error`) and adds a `repo` field. Left unset, it falls back to `watch.repo`,
+so most `spf watch` setups need nothing extra; set it explicitly when
+`watch.repo` is blank or two watched repos share a basename.
+
+```yaml
+notifications:
+  events: attention
+  project: api            # optional; defaults to watch.repo
+  channels:
+    - kind: slack
+```
+
 Delivery never blocks or fails a run: an unconfigured/misconfigured channel
 is skipped with one warning, and a failed POST logs one line and is
 swallowed — never changes a run's exit code. One thing worth knowing under

package/assets/skill/references/config.md

@@ -277,6 +277,7 @@ default; adding it is entirely additive.
 |---|---|---|
 | `events` | `"off"` \| `"errors"` \| `"attention"` \| `"all"` | The whole filter, narrowest to widest. `off` (default): nothing. `errors`: only true failures — failed runs/phases (`run_failed`/`phase_failed`), `watch_error`. `attention`: `errors` plus anything needing a human but not itself a failure — a blocked issue (`issue_blocked`) or a spec needing feedback (`spec_needs_feedback`). `all`: every curated milestone (run started, issue claimed, PR opened, ...) plus `attention` and `errors`. |
 | `timeout_ms` | int | Per-request timeout for a channel's HTTP POST. Default `5000`. |
+| `project` | string | Label prefixed onto every outbound title (`[api] watch: ...`) and added as a `repo` field — for disambiguating multiple `spf` instances that share one webhook. Default `""`, which falls back to `watch.repo`. |
 | `channels[]` | array | See below. |
 
 `channels[].kind`: `"slack"` \| `"teams"` \| `"webhook"`. `channels[].events`

package/dist/cli/commands/doctor.js

@@ -1023,6 +1023,15 @@ export async function doctorCommand(argv) {
             const label = ch.name ? `${ch.kind} (${ch.name})` : ch.kind;
             check(report, `notifications: ${label}`, Boolean(process.env[envKey]), process.env[envKey] ? `${envKey} set` : `${envKey} is not set`);
         }
+        // See `NotificationsConfigSchema.project`'s doc comment / `resolveNotifier`'s
+        // same fallback — informational only (never fails doctor), since an
+        // unset project tag is harmless unless this webhook ends up shared.
+        if (cfg.notifications.channels.length > 0) {
+            const project = cfg.notifications.project.trim() || cfg.watch.repo.trim();
+            check(report, "notifications.project", true, project
+                ? `tag: "${project}"`
+                : "not set, and watch.repo is empty — outbound messages won't carry a repo/project tag; if this webhook is ever shared across multiple spf instances, set notifications.project to tell them apart", project ? "info" : "warn");
+        }
     }
     return finish(report, flags["json"]);
 }

package/dist/cli/interview.js

@@ -527,6 +527,15 @@ export async function runInterview(asker, ctx) {
             const timeoutMs = await asker.text("notifications.timeout_ms", { default: "5000" });
             if (timeoutMs !== "5000")
                 notifications.timeout_ms = Number(timeoutMs);
+            // Only matters when one Slack/Teams/webhook endpoint is shared across
+            // several `spf` instances — defaults to watch.repo (resolveNotifier's
+            // own fallback), so most single-repo setups can just accept it and
+            // write nothing extra into the generated config.
+            const repoDefault = watch?.repo || "";
+            asker.note("Tags every outbound title/field so messages are distinguishable if this webhook is shared across repos — defaults to watch.repo.");
+            const project = await asker.text("notifications.project", { default: repoDefault });
+            if (project !== repoDefault)
+                notifications.project = project;
         }
     }
     // ── 6. review + confirm ─────────────────────────────────────────────────────

package/dist/core/data_types.d.ts

@@ -1099,6 +1099,7 @@ export declare const NotificationsConfigSchema: v.ObjectSchema<{
         readonly events: v.OptionalSchema<v.NullableSchema<v.PicklistSchema<["off", "errors", "attention", "all"], undefined>, undefined>, undefined>;
         readonly name: v.OptionalSchema<v.StringSchema<undefined>, "">;
     }, undefined>, undefined>, () => never[]>;
+    readonly project: v.OptionalSchema<v.StringSchema<undefined>, "">;
 }, undefined>;
 export type NotificationsConfig = v.InferOutput<typeof NotificationsConfigSchema>;
 /**
@@ -1443,6 +1444,7 @@ export declare const SFConfigSchema: v.ObjectSchema<{
             readonly events: v.OptionalSchema<v.NullableSchema<v.PicklistSchema<["off", "errors", "attention", "all"], undefined>, undefined>, undefined>;
             readonly name: v.OptionalSchema<v.StringSchema<undefined>, "">;
         }, undefined>, undefined>, () => never[]>;
+        readonly project: v.OptionalSchema<v.StringSchema<undefined>, "">;
     }, undefined>, () => {
         events: "all" | "attention" | "errors" | "off";
         timeout_ms: number;
@@ -1452,6 +1454,7 @@ export declare const SFConfigSchema: v.ObjectSchema<{
             events?: "all" | "attention" | "errors" | "off" | null | undefined;
             name: string;
         }[];
+        project: string;
     }>;
     readonly review: v.OptionalSchema<v.ObjectSchema<{
         readonly require_human_signoff: v.OptionalSchema<v.BooleanSchema<undefined>, false>;

package/dist/core/data_types.js

@@ -834,6 +834,13 @@ export const NotificationsConfigSchema = v.object({
     events: v.optional(NotifyScopeSchema, "off"),
     timeout_ms: v.optional(v.number(), 5_000),
     channels: v.optional(v.array(NotifyChannelSchema), () => []),
+    // Prefixed onto every outbound title (e.g. "[api] watch: ..." ) and added
+    // as a `repo` field, so one Slack/Teams/webhook endpoint shared across
+    // several `spf watch` instances (one per repo) can tell them apart.
+    // Empty means "derive from watch.repo" (see `resolveNotifier`) — set this
+    // explicitly only when that repo string isn't a good enough label, e.g.
+    // it's blank, or two watched repos share a basename.
+    project: v.optional(v.string(), ""),
 });
 /**
  * `simple_sdlc`'s human-signoff gate — see the ACCEPTED ADVERSARIAL

package/dist/core/notify/notifier.d.ts

@@ -18,13 +18,14 @@ export declare class Notifier {
     private readonly timeoutMs;
     private readonly dryRun;
     private readonly log;
+    private readonly project;
     private pending;
     constructor(channels: Array<{
         channel: NotificationChannel;
         scope: NotifyScope;
-    }>, timeoutMs: number, dryRun: boolean, log?: (message: string) => void);
+    }>, timeoutMs: number, dryRun: boolean, log?: (message: string) => void, project?: string);
     /** Sync, fire-and-forget — every call site is sync and must stay that way. */
-    send(event: NotifyEvent): void;
+    send(rawEvent: NotifyEvent): void;
     /** Await every in-flight send — call before process exit so a slow webhook isn't dropped mid-flight. */
     flush(): Promise<void>;
     /**

package/dist/core/notify/notifier.js

@@ -25,15 +25,21 @@ export class Notifier {
     timeoutMs;
     dryRun;
     log;
+    project;
     pending = new Set();
-    constructor(channels, timeoutMs, dryRun, log = (m) => console.error(m)) {
+    constructor(channels, timeoutMs, dryRun, log = (m) => console.error(m), 
+    // See `NotificationsConfigSchema.project`'s doc comment — empty disables
+    // tagging entirely, so a single-repo setup's outbound JSON is unchanged.
+    project = "") {
         this.channels = channels;
         this.timeoutMs = timeoutMs;
         this.dryRun = dryRun;
         this.log = log;
+        this.project = project;
     }
     /** Sync, fire-and-forget — every call site is sync and must stay that way. */
-    send(event) {
+    send(rawEvent) {
+        const event = this.project ? tagEvent(rawEvent, this.project) : rawEvent;
         for (const { channel, scope } of this.channels) {
             if (!scopeAllows(scope, event.level))
                 continue;
@@ -79,6 +85,23 @@ export class Notifier {
         }
     }
 }
+/**
+ * Prefixes `event.title` with `[project]` and adds a `repo` field, so a
+ * webhook shared by several `spf watch` instances reads clearly even
+ * collapsed to one line (Slack's notification/thread-list view only shows
+ * `title`, never `fields`). Skips the field when one's already there
+ * (`watch_started`/`watch_stopped` already carry their own `repo` field —
+ * see `cli/commands/watch.ts`) rather than emit a duplicate key with the
+ * same value.
+ */
+function tagEvent(event, project) {
+    const hasRepo = event.fields.some(([key]) => key === "repo");
+    return {
+        ...event,
+        title: `[${project}] ${event.title}`,
+        fields: hasRepo ? event.fields : [["repo", project], ...event.fields],
+    };
+}
 function makeChannel(kind, url, name) {
     switch (kind) {
         case "slack":
@@ -121,7 +144,13 @@ export function resolveNotifier(cfg, opts = {}) {
     }
     if (resolved.length === 0)
         return null;
-    const notifier = new Notifier(resolved, nc.timeout_ms, Boolean(opts.dryRun), log);
+    // See `NotificationsConfigSchema.project`'s doc comment: an explicit
+    // `notifications.project` wins; otherwise fall back to `watch.repo`
+    // (present whenever `spf watch` is what's sending — the common case for a
+    // shared webhook), and empty (a one-off `spf run` with no watch.repo set)
+    // disables tagging, same as today.
+    const project = nc.project.trim() || cfg.watch.repo.trim();
+    const notifier = new Notifier(resolved, nc.timeout_ms, Boolean(opts.dryRun), log, project);
     LIVE.push(notifier);
     return notifier;
 }

package/dist/core/utils.d.ts

@@ -24,11 +24,11 @@ export declare function newId(length?: number): string;
  * retry before it's allowed to throw. Node's global `fetch` (undici) pools
  * keep-alive connections across calls; Atlassian's Cloud APIs (Jira,
  * Bitbucket) close idle ones from their end, which surfaces here as
- * `ECONNRESET` the next time a long-lived poller (`spf watch`) reuses one —
- * a stale-socket race, not a real problem with the request. Only retries
- * error codes that mean "the transport failed," never an HTTP error status
- * (a 4xx/5xx response is not a thrown error here, and must keep surfacing
- * on the first attempt so callers see it immediately).
+ * `ECONNRESET`/`UND_ERR_SOCKET` the next time a long-lived poller (`spf
+ * watch`) reuses one — a stale-socket race, not a real problem with the
+ * request. Only retries error codes that mean "the transport failed," never
+ * an HTTP error status (a 4xx/5xx response is not a thrown error here, and
+ * must keep surfacing on the first attempt so callers see it immediately).
  */
 export declare function fetchRetryTransient(input: string, init?: RequestInit): Promise<Response>;
 /** `process.kill(pid, 0)` sends no signal — it throws iff `pid` isn't running (or isn't ours to signal), the standard Node liveness probe. */

package/dist/core/utils.js

@@ -31,18 +31,25 @@ export function operatorEnv() {
 export function newId(length = 8) {
     return randomBytes(Math.floor(length / 2)).toString("hex");
 }
-/** Transport-level blips worth one silent retry — see `fetchRetryTransient` below. */
-const TRANSIENT_FETCH_CODES = new Set(["ECONNRESET", "ETIMEDOUT", "EPIPE", "ECONNREFUSED", "EAI_AGAIN"]);
+/**
+ * Transport-level blips worth one silent retry — see `fetchRetryTransient`
+ * below. `UND_ERR_SOCKET` is undici's own code for the same stale-keep-alive
+ * race as `ECONNRESET` (the far end closes a pooled socket between calls);
+ * without it here, every `spf watch` poll tick that lands on one of those
+ * sockets surfaces as a bare, undiagnosable "fetch failed (UND_ERR_SOCKET)"
+ * notification instead of being retried away like its `ECONNRESET` sibling.
+ */
+const TRANSIENT_FETCH_CODES = new Set(["ECONNRESET", "ETIMEDOUT", "EPIPE", "ECONNREFUSED", "EAI_AGAIN", "UND_ERR_SOCKET"]);
 /**
  * `fetch`, but a transport-level blip on the FIRST attempt gets one silent
  * retry before it's allowed to throw. Node's global `fetch` (undici) pools
  * keep-alive connections across calls; Atlassian's Cloud APIs (Jira,
  * Bitbucket) close idle ones from their end, which surfaces here as
- * `ECONNRESET` the next time a long-lived poller (`spf watch`) reuses one —
- * a stale-socket race, not a real problem with the request. Only retries
- * error codes that mean "the transport failed," never an HTTP error status
- * (a 4xx/5xx response is not a thrown error here, and must keep surfacing
- * on the first attempt so callers see it immediately).
+ * `ECONNRESET`/`UND_ERR_SOCKET` the next time a long-lived poller (`spf
+ * watch`) reuses one — a stale-socket race, not a real problem with the
+ * request. Only retries error codes that mean "the transport failed," never
+ * an HTTP error status (a 4xx/5xx response is not a thrown error here, and
+ * must keep surfacing on the first attempt so callers see it immediately).
  */
 export async function fetchRetryTransient(input, init) {
     try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gr8ful/spf",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "description": "Super Portable Factory — a global CLI for repeatable agents-plus-code workflows (ADWs)",
   "type": "module",
   "license": "MIT",