ftown 0.25.3 → 0.26.0

package/dist/coordination/wiring.d.ts

@@ -0,0 +1,48 @@
+import type { Activity } from '../attention-events.js';
+import type { PullRequestState } from '../pull-request-status-protocol.js';
+import type { Session } from '../types.js';
+import type { BoardDeps, BoardServiceApi, CardStoreApi, CardStoreDeps, DigestProvider, MailEventSink, TreeEventKind, TreeEventLogApi, TreeEventLogDeps } from './contract.js';
+export interface CoordinationSessionStore {
+    loadSession(id: string): Promise<Session | null>;
+    saveSession(session: Session): Promise<void>;
+    listSessions(): Promise<Session[]>;
+    sessionDir(id: string): string;
+}
+export interface CoordinationAttentionStore {
+    list(id: string): Promise<{
+        activity: Activity;
+        openCount: number;
+    }>;
+}
+export interface CoordinationPrStatusResult {
+    state: PullRequestState;
+    stale: boolean;
+    checkedAt: string | null;
+}
+export interface CoordinationMailStore {
+    unreadCount(id: string): Promise<number>;
+}
+export interface CoordinationDeps {
+    store: CoordinationSessionStore;
+    attention: CoordinationAttentionStore;
+    prStatus: (url: string) => Promise<CoordinationPrStatusResult | null>;
+    mail: CoordinationMailStore;
+    publishSession: (s: Session) => void;
+    now: () => number;
+    /** Optional factory seams for unit tests using *Api fakes. */
+    createCards?: (deps: CardStoreDeps) => CardStoreApi;
+    createEvents?: (deps: TreeEventLogDeps) => TreeEventLogApi;
+    createBoard?: (deps: BoardDeps) => BoardServiceApi;
+}
+export interface Coordination {
+    cards: CardStoreApi;
+    events: TreeEventLogApi;
+    board: BoardServiceApi;
+    digest: DigestProvider;
+    mailSink: MailEventSink;
+    emit(session: Session, kind: TreeEventKind, summary: string, ref?: string): Promise<void>;
+    onSessionExit(sessionId: string): Promise<void>;
+    onSessionStart(sessionId: string): void;
+}
+export declare function rootOf(session: Pick<Session, 'id' | 'parentSessionId'>): string;
+export declare function createCoordination(deps: CoordinationDeps): Coordination;

package/dist/coordination/wiring.js

@@ -0,0 +1,143 @@
+import { BoardService } from './board.js';
+import { CardStore } from './card-store.js';
+import { TreeEventLog } from './tree-events.js';
+export function rootOf(session) {
+    return session.parentSessionId ?? session.id;
+}
+function sameBlockedOn(a, b) {
+    if (a === undefined && b === undefined)
+        return true;
+    if (a === undefined || b === undefined)
+        return false;
+    return a.kind === b.kind && a.text === b.text && a.ref === b.ref;
+}
+function statusChanged(current, previous) {
+    if (!previous)
+        return true;
+    if (current.state !== previous.state)
+        return true;
+    if (current.headline !== previous.headline)
+        return true;
+    return !sameBlockedOn(current.blockedOn, previous.blockedOn);
+}
+function formatStatusSummary(card) {
+    const base = `${card.state}: ${card.headline}`;
+    if (card.state === 'blocked' && card.blockedOn) {
+        return `${base} — blocked on ${card.blockedOn.kind}: ${card.blockedOn.text}`;
+    }
+    return base;
+}
+export function createCoordination(deps) {
+    const events = (deps.createEvents ?? ((d) => new TreeEventLog(d)))({
+        sessionDir: (id) => deps.store.sessionDir(id),
+        now: deps.now,
+    });
+    const exitedSessions = new Set();
+    function onSessionStart(sessionId) {
+        exitedSessions.delete(sessionId);
+    }
+    async function emit(session, kind, summary, ref) {
+        if (kind === 'exit') {
+            if (exitedSessions.has(session.id))
+                return;
+            exitedSessions.add(session.id);
+        }
+        try {
+            const rootId = rootOf(session);
+            await events.append(rootId, {
+                sessionId: session.id,
+                sessionName: session.name,
+                kind,
+                summary,
+                ...(ref !== undefined ? { ref } : {}),
+            });
+        }
+        catch (error) {
+            console.warn('[Coordination] Failed to emit tree event:', error instanceof Error ? error.message : String(error));
+        }
+    }
+    async function onSessionExit(sessionId) {
+        if (exitedSessions.has(sessionId))
+            return;
+        await deps.store
+            .loadSession(sessionId)
+            .then((session) => {
+            if (session && (session.status === 'completed' || session.status === 'error')) {
+                return emit(session, 'exit', `exited: ${session.status}`);
+            }
+        })
+            .catch((error) => {
+            console.warn('[Coordination] Failed to load session on exit:', error instanceof Error ? error.message : String(error));
+        });
+    }
+    const cards = (deps.createCards ?? ((d) => new CardStore(d)))({
+        loadSession: (id) => deps.store.loadSession(id),
+        saveSession: (session) => deps.store.saveSession(session),
+        now: deps.now,
+        onChange: async (saved, previous) => {
+            try {
+                deps.publishSession(saved);
+            }
+            catch (error) {
+                console.warn('[Coordination] Failed to publish session update:', error instanceof Error ? error.message : String(error));
+            }
+            if (saved.card && statusChanged(saved.card, previous)) {
+                await emit(saved, 'status', formatStatusSummary(saved.card));
+            }
+        },
+    });
+    const board = (deps.createBoard ?? ((d) => new BoardService(d)))({
+        loadSession: (id) => deps.store.loadSession(id),
+        listSessions: () => deps.store.listSessions(),
+        attention: async (id) => {
+            const page = await deps.attention.list(id);
+            return { activity: page.activity, openCount: page.openCount };
+        },
+        prStatus: (url) => deps.prStatus(url),
+        unreadMail: (id) => deps.mail.unreadCount(id),
+        events,
+        now: deps.now,
+    });
+    const digestCursors = new Map();
+    const digest = {
+        async digestFor(recipientSessionId) {
+            try {
+                const sessions = await deps.store.listSessions();
+                const hasChildren = sessions.some((s) => s.parentSessionId === recipientSessionId && s.id !== recipientSessionId);
+                if (!hasChildren)
+                    return null;
+                let since = digestCursors.get(recipientSessionId);
+                if (since === undefined) {
+                    since = await events.head(recipientSessionId);
+                    digestCursors.set(recipientSessionId, since);
+                }
+                const result = await board.digest(recipientSessionId, since);
+                digestCursors.set(recipientSessionId, result.cursor);
+                return result.line;
+            }
+            catch {
+                return null;
+            }
+        },
+    };
+    const mailSink = {
+        async onAccepted(message, recipient) {
+            try {
+                if (message.type !== 'result')
+                    return;
+                const sender = await deps.store.loadSession(message.from);
+                if (!sender)
+                    return;
+                if (rootOf(sender) !== recipient.id)
+                    return;
+                const firstLine = (message.body.split(/\r?\n/, 1)[0] ?? '').slice(0, 200);
+                await emit(sender, 'result', firstLine);
+            }
+            catch (error) {
+                console.warn('[Coordination] Failed to handle accepted mail event:', error instanceof Error ? error.message : String(error));
+            }
+        },
+    };
+    return { cards, events, board, digest, mailSink, emit, onSessionExit, onSessionStart };
+}
+//# sourceMappingURL=wiring.js.map

package/dist/coordination/wiring.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"wiring.js","sourceRoot":"","sources":["../../src/coordination/wiring.ts"],"names":[],"mappings":"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"}

package/dist/coordination-cli.d.ts

@@ -0,0 +1,34 @@
+import { type Board, type BoardWaitCondition, type CardPatch, type CardProgress, type TreeEvent } from './coordination/contract.js';
+/** One local-API call; injectable so tests need no bridge. */
+export type CoordinationApiFn = (method: string, path: string, body?: unknown) => Promise<unknown>;
+export interface CoordinationCliDeps {
+    api: CoordinationApiFn;
+    now: () => number;
+    env: NodeJS.ProcessEnv;
+    log: (text: string) => void;
+    errorLog: (text: string) => void;
+}
+export declare const WAIT_DEFAULT_TIMEOUT_SECONDS = 300;
+export declare const WAIT_MAX_TIMEOUT_SECONDS = 300;
+/** Usage problem: message printed, exit code 2. */
+export declare class UsageError extends Error {
+    readonly usage?: string | undefined;
+    constructor(message: string, usage?: string | undefined);
+}
+export declare function parseProgress(value: string): CardProgress;
+export interface StatusSetFlags {
+    state?: string;
+    headline?: string;
+    /** string value, false for --no-progress, undefined when absent */
+    progress?: string | boolean;
+    on?: string;
+    text?: string;
+    /** string value, false for --no-next, undefined when absent */
+    next?: string | boolean;
+}
+export declare function buildCardPatch(flags: StatusSetFlags): CardPatch;
+/** Pure wait-condition evaluation over a fetched board and the events that arrived. */
+export declare function evaluateWaitCondition(condition: BoardWaitCondition, board: Board, events: readonly TreeEvent[]): boolean;
+export declare function runStatus(argv: string[], deps?: Partial<CoordinationCliDeps>): Promise<number>;
+export declare function runBoard(argv: string[], deps?: Partial<CoordinationCliDeps>): Promise<number>;
+export declare function runEvents(argv: string[], deps?: Partial<CoordinationCliDeps>): Promise<number>;