@gr8ful/spf 0.2.1 → 0.4.0

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

@@ -0,0 +1,17 @@
+/**
+ * Microsoft Teams via a Power Automate "Workflows" webhook, posting an
+ * Adaptive Card. This is the ONLY supported path: the legacy Office 365
+ * connector webhook (a bare `MessageCard`/`@type` POST straight to a
+ * channel-configured URL) has been retired by Microsoft. Set up: in the
+ * target channel, add a Workflows webhook template (naming has shifted
+ * between Microsoft revisions — search for one along the lines of "Post to
+ * a channel when a webhook request is received") and copy the generated URL.
+ * https://support.microsoft.com/en-us/office/post-a-workflow-when-a-webhook-request-is-received-in-microsoft-teams-8ae491c7-0394-4861-ba59-055e33f75498
+ */
+import type { NotificationChannel, NotifyEvent } from "./channel.ts";
+export declare class TeamsChannel implements NotificationChannel {
+    private readonly webhookUrl;
+    readonly label: string;
+    constructor(webhookUrl: string, name?: string);
+    send(event: NotifyEvent, timeoutMs: number): Promise<void>;
+}

package/dist/core/notify/teams_channel.js

@@ -0,0 +1,38 @@
+export class TeamsChannel {
+    webhookUrl;
+    label;
+    constructor(webhookUrl, name = "") {
+        this.webhookUrl = webhookUrl;
+        this.label = name ? `teams (${name})` : "teams";
+    }
+    async send(event, timeoutMs) {
+        const color = event.level === "error" ? "attention" : "good";
+        const facts = event.fields.map(([title, value]) => ({ title, value }));
+        const card = {
+            type: "AdaptiveCard",
+            $schema: "http://adaptivecards.io/schemas/adaptive-card.json",
+            version: "1.4",
+            body: [
+                { type: "TextBlock", text: event.title, weight: "bolder", size: "medium", color, wrap: true },
+                ...(event.detail ? [{ type: "TextBlock", text: event.detail.slice(0, 2900), wrap: true }] : []),
+                ...(facts.length > 0 ? [{ type: "FactSet", facts }] : []),
+            ],
+            ...(event.url
+                ? { actions: [{ type: "Action.OpenUrl", title: "Open", url: event.url }] }
+                : {}),
+        };
+        const body = {
+            type: "message",
+            attachments: [{ contentType: "application/vnd.microsoft.card.adaptive", contentUrl: null, content: card }],
+        };
+        const response = await fetch(this.webhookUrl, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify(body),
+            signal: AbortSignal.timeout(timeoutMs),
+        });
+        if (!response.ok) {
+            throw new Error(`teams webhook -> ${response.status}: ${(await response.text().catch(() => "")).slice(0, 300)}`);
+        }
+    }
+}

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

@@ -0,0 +1,13 @@
+/**
+ * A generic webhook: `POST` the `NotifyEvent` as raw JSON, no vendor shape.
+ * Covers Discord/n8n/Zapier/a homegrown receiver with no new channel module
+ * each time, and is what `notify.test.ts` posts against a real local
+ * `node:http` receiver instead of mocking `fetch`.
+ */
+import type { NotificationChannel, NotifyEvent } from "./channel.ts";
+export declare class WebhookChannel implements NotificationChannel {
+    private readonly url;
+    readonly label: string;
+    constructor(url: string, name?: string);
+    send(event: NotifyEvent, timeoutMs: number): Promise<void>;
+}

package/dist/core/notify/webhook_channel.js

@@ -0,0 +1,19 @@
+export class WebhookChannel {
+    url;
+    label;
+    constructor(url, name = "") {
+        this.url = url;
+        this.label = name ? `webhook (${name})` : "webhook";
+    }
+    async send(event, timeoutMs) {
+        const response = await fetch(this.url, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify(event),
+            signal: AbortSignal.timeout(timeoutMs),
+        });
+        if (!response.ok) {
+            throw new Error(`webhook -> ${response.status}: ${(await response.text().catch(() => "")).slice(0, 300)}`);
+        }
+    }
+}

package/dist/core/refine.d.ts

@@ -0,0 +1,39 @@
+import type { Issue, IssueAuthoringProvider } from "./issues/provider.ts";
+import type { RefinedIssue, SFConfig } from "./data_types.ts";
+export interface PublishedIssue {
+    /** The `RefinedIssue.key` this came from — a run-local id, never a tracker id. */
+    key: string;
+    issue: Issue;
+    kind: RefinedIssue["kind"];
+    /** A node nothing else names as `parent` — the independently-workable unit `spf:refined` goes on. */
+    isLeaf: boolean;
+}
+/**
+ * `IssueAuthoringProvider` has a real implementation only on `GitHubProvider`
+ * today — see `jira_provider.ts`'s module comment on why Jira isn't wired up
+ * yet. Throws rather than returning `null` so a `code` phase calling this
+ * (`steps.publishIssues()`) fails the phase with a clear, specific reason —
+ * the same "fail loudly, never silently do nothing" contract
+ * `agents.validate()` uses for an unconfigured quality suite.
+ */
+export declare function resolveAuthoringProvider(cfg: SFConfig): IssueAuthoringProvider;
+export interface PublishOptions {
+    labelPrefix: string;
+    /** The originating spec issue's id, for every created issue's `## Parent` back-reference. `null`/omitted for a manual run with no source issue. */
+    specIssueId?: string | null;
+}
+/**
+ * Create every node in `issues`, in dependency order, with its
+ * `<prefix>:type:<kind>` label (plus `<prefix>:refined` on leaves only —
+ * see `WatchState`'s doc comment in `provider.ts`), link each to its parent
+ * via the tracker's native hierarchy, and render real `#n` references into
+ * `## Blocked by`. Returns what it created, in creation order.
+ *
+ * Not transactional: if a create or link call throws partway through, the
+ * nodes already published stay published, orphaned from whatever hadn't run
+ * yet. No rollback is attempted — the gate already ran, so this only fails
+ * on a live tracker error (rate limit, network), which a human re-running
+ * the spec (once the marker's `refined` list explains what already exists)
+ * can sort out same as any other `spf watch` failure.
+ */
+export declare function publish(tracker: IssueAuthoringProvider, issues: RefinedIssue[], opts: PublishOptions): Promise<PublishedIssue[]>;

package/dist/core/refine.js

@@ -0,0 +1,144 @@
+/**
+ * Publish logic for the refine lane: turn a gated `RefineOutput.issues` list
+ * (a product spec decomposed into a feature/story tree — see
+ * `RefinedIssueSchema` in `data_types.ts`) into real tracker issues, in
+ * dependency order, with the right labels and parent/child links. Nothing
+ * else: no marker bookkeeping, no `transition()`, no comment posted back
+ * onto the spec issue. Those are watch-lifecycle concerns `core/watch.ts`'s
+ * `runSpec` owns, exactly the way `runIssue` (the build lane) owns
+ * `openPr`/`transition` rather than a chain step doing it — this file is
+ * "given issues and a tracker, create them correctly," the one part
+ * `to-tickets` (the skill this lane's prompt is ported from) leaves
+ * entirely unspecified, and the part that makes a re-run duplicate every
+ * ticket (see `WatchMarker.refined`'s doc comment in `provider.ts` for how
+ * `runSpec` closes that gap using what this module returns).
+ */
+import { GitHubProvider } from "./issues/github_provider.js";
+/**
+ * `IssueAuthoringProvider` has a real implementation only on `GitHubProvider`
+ * today — see `jira_provider.ts`'s module comment on why Jira isn't wired up
+ * yet. Throws rather than returning `null` so a `code` phase calling this
+ * (`steps.publishIssues()`) fails the phase with a clear, specific reason —
+ * the same "fail loudly, never silently do nothing" contract
+ * `agents.validate()` uses for an unconfigured quality suite.
+ */
+export function resolveAuthoringProvider(cfg) {
+    if (cfg.watch.issue_provider !== "github") {
+        throw new Error(`watch.issue_provider ${JSON.stringify(cfg.watch.issue_provider)} does not support issue authoring — ` +
+            `the refine lane needs "github" (see jira_provider.ts's module comment on why Jira isn't wired up yet)`);
+    }
+    if (!cfg.watch.repo.trim()) {
+        throw new Error(`watch.repo is not configured — add it to spf.config.yaml's watch: section, e.g. "owner/name"`);
+    }
+    const token = process.env["GITHUB_TOKEN"];
+    if (!token) {
+        throw new Error('GITHUB_TOKEN is not set — the refine lane needs a classic PAT with "repo" scope (or "public_repo" for a public-only repo)');
+    }
+    return new GitHubProvider(cfg.watch.repo, cfg.watch.label_prefix, token);
+}
+function typeLabel(labelPrefix, kind) {
+    return `${labelPrefix}:type:${kind}`;
+}
+/**
+ * The body GitHub actually stores: the refiner's own `## What to build` /
+ * `## Acceptance criteria` text, plus a `## Parent` back-reference to the
+ * source spec (when there is one — a bare `spf refine` run with no
+ * `--issue` has none), plus a `## Blocked by` section with real `#n`
+ * references — `to-tickets`' own template shape, ported. Every `blocked_by`
+ * key is guaranteed to already be in `byKey` by the time this runs:
+ * `topoOrder` visits a node's dependencies before the node itself.
+ */
+function renderBody(node, byKey, specIssueId) {
+    const parts = [node.body.trim()];
+    if (specIssueId)
+        parts.push(`## Parent\n\nDecomposed from #${specIssueId}.`);
+    if (node.blocked_by.length > 0) {
+        const refs = node.blocked_by.map((key) => {
+            const published = byKey.get(key);
+            // Defensive only: gates.refinementWellFormed already rejects a
+            // blocked_by key that doesn't resolve to another node in the list.
+            return published ? `#${published.issue.id}` : key;
+        });
+        parts.push(`## Blocked by\n\n${refs.map((r) => `- ${r}`).join("\n")}`);
+    }
+    else {
+        parts.push(`## Blocked by\n\nNone (can start immediately).`);
+    }
+    return parts.join("\n\n");
+}
+/**
+ * Order nodes so every `parent` and every `blocked_by` reference is already
+ * published (a real issue, in `byKey`) before the node that names it —
+ * required both for the sub-issue link (the parent must exist first) and
+ * for `renderBody`'s `#n` references. `gates.refinementWellFormed` has
+ * already rejected a cyclic input by the time `publish()` ever runs; the
+ * `visiting` check here is a defensive backstop against a caller that
+ * skipped the gate, not the primary line of defense.
+ */
+function topoOrder(issues) {
+    const byKey = new Map(issues.map((i) => [i.key, i]));
+    const ordered = [];
+    const done = new Set();
+    const visiting = new Set();
+    function visit(node) {
+        if (done.has(node.key))
+            return;
+        if (visiting.has(node.key)) {
+            throw new Error(`refine: dependency cycle detected at key ${JSON.stringify(node.key)} — gates.refinementWellFormed should have caught this before publish ran`);
+        }
+        visiting.add(node.key);
+        for (const depKey of [node.parent, ...node.blocked_by]) {
+            if (!depKey)
+                continue;
+            const dep = byKey.get(depKey);
+            if (dep)
+                visit(dep);
+        }
+        visiting.delete(node.key);
+        done.add(node.key);
+        ordered.push(node);
+    }
+    for (const issue of issues)
+        visit(issue);
+    return ordered;
+}
+/**
+ * Create every node in `issues`, in dependency order, with its
+ * `<prefix>:type:<kind>` label (plus `<prefix>:refined` on leaves only —
+ * see `WatchState`'s doc comment in `provider.ts`), link each to its parent
+ * via the tracker's native hierarchy, and render real `#n` references into
+ * `## Blocked by`. Returns what it created, in creation order.
+ *
+ * Not transactional: if a create or link call throws partway through, the
+ * nodes already published stay published, orphaned from whatever hadn't run
+ * yet. No rollback is attempted — the gate already ran, so this only fails
+ * on a live tracker error (rate limit, network), which a human re-running
+ * the spec (once the marker's `refined` list explains what already exists)
+ * can sort out same as any other `spf watch` failure.
+ */
+export async function publish(tracker, issues, opts) {
+    const ordered = topoOrder(issues);
+    const childKeys = new Set(issues.filter((i) => i.parent).map((i) => i.parent));
+    const byKey = new Map();
+    const created = [];
+    for (const node of ordered) {
+        const isLeaf = !childKeys.has(node.key);
+        const labels = [typeLabel(opts.labelPrefix, node.kind)];
+        if (isLeaf)
+            labels.push(`${opts.labelPrefix}:refined`);
+        const body = renderBody(node, byKey, opts.specIssueId);
+        const issue = await tracker.createIssue({ title: node.title, body, labels });
+        const published = { key: node.key, issue, kind: node.kind, isLeaf };
+        byKey.set(node.key, published);
+        created.push(published);
+        if (node.parent) {
+            const parent = byKey.get(node.parent);
+            // topoOrder guarantees the parent was visited (and thus published)
+            // first; a missing entry here would mean the gate let an
+            // unresolved parent through, which refinementWellFormed rejects.
+            if (parent)
+                await tracker.linkChild(parent.issue, issue);
+        }
+    }
+    return created;
+}

package/dist/core/runner.d.ts

@@ -12,6 +12,7 @@ import { type GitHandle } from "./git_helper.ts";
 import { Console } from "./console.ts";
 import { Tracer } from "./tracer.ts";
 import { type AgentCall, type EnvelopeBase, type Phase, type PhaseParams, type SFConfig } from "./data_types.ts";
+import type { Notifier } from "./notify/notifier.ts";
 interface AgentMapEntry {
     session_id: string;
     model: string;
@@ -32,12 +33,18 @@ export interface RunInit {
     sfDir: string | null;
     /** Absolute. Resolved once, upstream, by paths.resolveDataPaths(). */
     dataDir: string;
+    /** The CLI chain name, for a notification's title — see session.ts. */
+    chainName?: string;
+    /** `null`/omitted when notifications are off (the default) or no channel resolved. */
+    notifier?: Notifier | null;
 }
 export declare class Run {
     cfg: SFConfig;
     adw_id: string;
     tracer: Tracer;
     console: Console;
+    /** `null` when notifications are off — `run.notify?.send(...)` at any future call site. */
+    notify: Notifier | null;
     engineer: string;
     phases: Phase[];
     tokens: number;

package/dist/core/runner.js

@@ -48,6 +48,8 @@ export class Run {
     adw_id;
     tracer;
     console;
+    /** `null` when notifications are off — `run.notify?.send(...)` at any future call site. */
+    notify;
     engineer;
     phases = [];
     tokens = 0;
@@ -68,7 +70,8 @@ export class Run {
         this.cfg = init.cfg;
         this.adw_id = init.adwId;
         this.tracer = init.tracer;
-        this.console = new Console(init.tracer, init.adwId);
+        this.notify = init.notifier ?? null;
+        this.console = new Console(init.tracer, init.adwId, this.notify, init.chainName || "adw");
         this.engineer = init.engineer;
         this.seq = init.tracer.maxPhaseSeq(init.adwId);
         this.repo_root = init.repoRoot;

package/dist/core/session.js

@@ -10,6 +10,7 @@ import * as paths from "./paths.js";
 import { Run } from "./runner.js";
 import { Tracer } from "./tracer.js";
 import { engineerName, newId } from "./utils.js";
+import { resolveNotifier } from "./notify/notifier.js";
 /**
  * A killed run still closes its own trace.
  *
@@ -52,6 +53,8 @@ export function ensure(cfg, adwId, cwd, chainName) {
         repoRoot: anchor.repo_root,
         sfDir: anchor.spf_dir,
         dataDir: dataPaths.data_dir,
+        chainName: chainName || "adw",
+        notifier: resolveNotifier(cfg),
     });
     const scriptPath = process.argv[1] || "adw";
     tracer.sessionStart(id, run.engineer, chainName || "adw");

package/dist/core/watch.d.ts

@@ -1,11 +1,27 @@
 import type { GitHandle } from "./git_helper.ts";
 import type { CodeHostProvider, Issue, IssueProvider } from "./issues/provider.ts";
+import type { NotifyEvent } from "./notify/channel.ts";
 export interface ChainRunResult {
     accepted: boolean;
     adwId: string;
     /** Shown to the engineer via a `blocked` comment on a failed/no-op run. */
     detail: string;
 }
+/** One issue the refine lane created — enough for `finishSpec`'s summary comment and the marker's idempotency record. */
+export interface RefinedIssueRef {
+    id: string;
+    title: string;
+    kind: string;
+    isLeaf: boolean;
+}
+export interface RefineRunResult {
+    accepted: boolean;
+    adwId: string;
+    /** Shown to the engineer via a `blocked` comment on a failed/no-op run. */
+    detail: string;
+    /** What `steps.publishIssues()` created, read back from its side-channel file — see `cli/commands/watch.ts`'s `runRefine`. Empty when `!accepted`. */
+    created: RefinedIssueRef[];
+}
 export interface WatchDeps {
     provider: IssueProvider;
     codeHost: CodeHostProvider;
@@ -16,6 +32,23 @@ export interface WatchDeps {
     chain: string;
     baseBranch: string;
     concurrency: number;
+    /**
+     * The second lane — decomposing a `<prefix>:spec-ready` product spec
+     * instead of building a `<prefix>:ready` issue. `false` (the default) is
+     * a complete no-op: `claimSpecs`/`reconcileRefining` return immediately,
+     * so an existing `spf watch` config sees no new poll traffic at all until
+     * this is turned on. See `WatchConfigSchema`'s `refine` field.
+     */
+    refineEnabled: boolean;
+    refineConcurrency: number;
+    refineChain: string;
+    /** Same shape as `runChain`, for the refine lane — see its own doc comment for why the two aren't unified into one callback. */
+    runRefine: (opts: {
+        prompt: string;
+        cwd: string;
+        adwId: string;
+        issueId: string;
+    }) => Promise<RefineRunResult>;
     worktreesDir: string;
     /**
      * Symlink (or otherwise wire up) `<worktreePath>/.spf/data` to the MAIN
@@ -36,12 +69,34 @@ export interface WatchDeps {
         adwId: string;
     }) => Promise<ChainRunResult>;
     log: (message: string) => void;
+    /**
+     * Structured push, alongside `log`'s plain string — a required field, like
+     * `log`, so a test must consciously supply one (a no-op fake is fine).
+     * Fired only at meaningful state transitions (claim, PR, done, blocked,
+     * error) — NOT at routine self-healing (an orphan resume/retry, a lost
+     * claim race, a cleanup warning), which recovers on its own and would
+     * just be noise in a channel.
+     */
+    notify: (event: NotifyEvent) => void;
 }
 export interface WatchRunState {
     inflight: Set<string>;
+    /**
+     * Separate from `inflight` — not a defensive copy of the same set, a
+     * genuinely different budget. The refine lane's `claimSpecs` caps against
+     * `refineConcurrency`, independent of the build lane's `concurrency`; a
+     * shared set would conflate "how many specs are being refined" with "how
+     * many issues are being built" and make either budget impossible to
+     * enforce on its own. The two never collide on an id in practice (a
+     * `spec-ready` issue and a `ready` issue are never the same issue), but
+     * that isn't why this is separate — the budgets are what require it.
+     */
+    refining: Set<string>;
 }
 export declare function createWatchState(): WatchRunState;
 export declare function branchNameFor(issue: Issue): string;
+/** Same idea as `branchNameFor`, for the refine lane's throwaway worktree — a spec never gets a PR, so this branch is only ever fetched-from-and-thrown-away, never pushed. */
+export declare function refineBranchNameFor(issue: Issue): string;
 /**
  * Any issue labeled `working` that THIS process isn't tracking is an
  * orphan — a daemon restart, or another instance's claim this process
@@ -49,9 +104,19 @@ export declare function branchNameFor(issue: Issue): string;
  * merged) PR; otherwise retry up to `MAX_ORPHAN_ATTEMPTS`, then give up.
  */
 export declare function reconcileOrphans(deps: WatchDeps, state: WatchRunState): Promise<void>;
+/**
+ * The refine lane's own `reconcileOrphans` — a `refining`-labeled spec this
+ * process isn't tracking is either a completed publish that crashed before
+ * its own `transition(issue, "done")` ran (resume: finish it, no re-run),
+ * or a genuine orphan (retry up to `MAX_ORPHAN_ATTEMPTS`, then give up).
+ * A no-op entirely when `watch.refine` is off — see `WatchDeps.refineEnabled`.
+ */
+export declare function reconcileRefining(deps: WatchDeps, state: WatchRunState): Promise<void>;
 /** Poll every `review`-labeled issue's PR for merged (-> done) or closed-without-merging (-> blocked). */
 export declare function finishReviews(deps: WatchDeps): Promise<void>;
 /** Claim as many `ready` issues as the concurrency budget allows, and kick off `runIssue` for each in the background. */
 export declare function claimNewWork(deps: WatchDeps, state: WatchRunState): Promise<void>;
-/** One poll tick: reconcile, finish, claim — each independently caught, so one phase's error never blocks the rest. */
+/** Claim as many `spec-ready` specs as `refineConcurrency` allows, and kick off `runSpec` for each in the background. A no-op when `watch.refine` is off. */
+export declare function claimSpecs(deps: WatchDeps, state: WatchRunState): Promise<void>;
+/** One poll tick: reconcile both lanes, finish reviews, then claim both lanes — each stage independently caught, so one stage's error never blocks the rest. */
 export declare function tick(deps: WatchDeps, state: WatchRunState): Promise<void>;