@webpresso/agent-kit 0.21.0

package/dist/esm/blueprint/sync/client.d.ts

@@ -0,0 +1,64 @@
+/**
+ * BlueprintSyncClient — webpresso HTTP client for the webpresso platform API.
+ *
+ * Implements `BlueprintPlatformClient` (types.ts) using the Fetch API.
+ *
+ * Design:
+ *  - WP_BLUEPRINT_PLATFORM_DISABLED=1: every method is a no-op / empty result.
+ *  - Token from SyncCredentials (loaded via loadSyncCredentials() in auth.ts).
+ *  - Idempotency: auto-generates a UUID eventId when payload.eventId is empty.
+ *  - Retry: max 3 attempts on 5xx / network errors, exponential backoff.
+ *  - 401: throws AuthError immediately — no retry (token invalid, re-auth needed).
+ *  - 409: treated as success (idempotent duplicate, platform silently ignores).
+ *  - 429: retried with backoff, counts toward the 3-attempt limit.
+ *  - listTemplates: reads from WP_BLUEPRINT_TEMPLATES_URL; returns [] on error.
+ *  - Structured log on every pushEvent call.
+ */
+import type { SyncCredentials } from './auth.js';
+import type { BlueprintPlatformClient, BlueprintPlatformEvent, BlueprintSnapshot, BlueprintTemplateEntry } from './types.js';
+export declare class AuthError extends Error {
+    constructor(message: string);
+}
+export declare class SyncDisabledError extends Error {
+    constructor(message: string);
+}
+export interface RetryOptions {
+    /** Base delay in ms for exponential backoff (default: 200). */
+    readonly baseDelayMs?: number;
+    /** Maximum number of attempts (default: 3). */
+    readonly maxAttempts?: number;
+}
+export declare class BlueprintSyncClient implements BlueprintPlatformClient {
+    private readonly creds;
+    private readonly fetchFn;
+    private readonly retryOpts;
+    constructor(creds: SyncCredentials, fetchFn?: typeof globalThis.fetch, retryOptions?: RetryOptions);
+    pushEvent(payload: BlueprintPlatformEvent): Promise<void>;
+    getSnapshot(opts?: {
+        readonly slug?: string;
+    }): Promise<BlueprintSnapshot>;
+    listTemplates(): Promise<readonly BlueprintTemplateEntry[]>;
+    healthCheck(): Promise<{
+        readonly ok: boolean;
+        readonly latencyMs: number;
+    }>;
+    private authHeaders;
+    /**
+     * Perform a single fetch without retry logic.
+     * Throws on non-ok responses (except 409 which is treated as success).
+     */
+    private fetchOnce;
+    /**
+     * Perform a fetch with retry logic (max 3 attempts, exponential backoff).
+     *
+     * - 401: throw AuthError immediately (no retry).
+     * - 409: return immediately (idempotent success).
+     * - 429 / 5xx: retry with exponential backoff.
+     * - Network errors: retry with exponential backoff, then throw with offline context.
+     *
+     * The `onAttempt` callback fires after EACH attempt (including the final one)
+     * with the HTTP status and duration. On network error, status = 0.
+     */
+    private retryFetch;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/esm/blueprint/sync/client.js

@@ -0,0 +1,232 @@
+/**
+ * BlueprintSyncClient — webpresso HTTP client for the webpresso platform API.
+ *
+ * Implements `BlueprintPlatformClient` (types.ts) using the Fetch API.
+ *
+ * Design:
+ *  - WP_BLUEPRINT_PLATFORM_DISABLED=1: every method is a no-op / empty result.
+ *  - Token from SyncCredentials (loaded via loadSyncCredentials() in auth.ts).
+ *  - Idempotency: auto-generates a UUID eventId when payload.eventId is empty.
+ *  - Retry: max 3 attempts on 5xx / network errors, exponential backoff.
+ *  - 401: throws AuthError immediately — no retry (token invalid, re-auth needed).
+ *  - 409: treated as success (idempotent duplicate, platform silently ignores).
+ *  - 429: retried with backoff, counts toward the 3-attempt limit.
+ *  - listTemplates: reads from WP_BLUEPRINT_TEMPLATES_URL; returns [] on error.
+ *  - Structured log on every pushEvent call.
+ */
+import { randomUUID } from 'node:crypto';
+// ---------------------------------------------------------------------------
+// Error classes
+// ---------------------------------------------------------------------------
+export class AuthError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'AuthError';
+    }
+}
+export class SyncDisabledError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'SyncDisabledError';
+    }
+}
+const DEFAULT_RETRY = {
+    baseDelayMs: 200,
+    maxAttempts: 3,
+};
+const DEFAULT_TEMPLATES_URL = 'https://raw.githubusercontent.com/webpresso/webpresso/main/catalog/blueprint-templates/index.json';
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function isDisabled() {
+    return process.env['WP_BLUEPRINT_PLATFORM_DISABLED'] === '1';
+}
+function resolveEventId(id) {
+    return id.length > 0 ? id : randomUUID();
+}
+function isRetryableStatus(status) {
+    return status === 429 || (status >= 500 && status <= 599);
+}
+function emptySnapshot() {
+    return { blueprints: [], fetchedAt: new Date().toISOString() };
+}
+// ---------------------------------------------------------------------------
+// BlueprintSyncClient
+// ---------------------------------------------------------------------------
+export class BlueprintSyncClient {
+    creds;
+    fetchFn;
+    retryOpts;
+    constructor(creds, fetchFn = globalThis.fetch, retryOptions = {}) {
+        this.creds = creds;
+        this.fetchFn = fetchFn;
+        this.retryOpts = { ...DEFAULT_RETRY, ...retryOptions };
+    }
+    // -------------------------------------------------------------------------
+    // pushEvent
+    // -------------------------------------------------------------------------
+    async pushEvent(payload) {
+        if (isDisabled())
+            return;
+        const eventId = resolveEventId(payload.eventId);
+        const body = { ...payload, eventId };
+        const url = `${this.creds.platformUrl}/v1/blueprint-events`;
+        await this.retryFetch(url, {
+            method: 'POST',
+            headers: this.authHeaders(),
+            body: JSON.stringify(body),
+        }, (status, durationMs) => {
+            console.log(JSON.stringify({
+                level: 'info',
+                eventType: payload.type,
+                eventId,
+                httpStatus: status,
+                durationMs,
+            }));
+        });
+    }
+    // -------------------------------------------------------------------------
+    // getSnapshot
+    // -------------------------------------------------------------------------
+    async getSnapshot(opts) {
+        if (isDisabled())
+            return emptySnapshot();
+        const path = opts?.slug != null && opts.slug.length > 0
+            ? `/v1/blueprints/${encodeURIComponent(opts.slug)}`
+            : '/v1/blueprints';
+        const url = `${this.creds.platformUrl}${path}`;
+        const response = await this.fetchOnce(url, {
+            method: 'GET',
+            headers: this.authHeaders(),
+        });
+        const json = (await response.json());
+        return json;
+    }
+    // -------------------------------------------------------------------------
+    // listTemplates
+    // -------------------------------------------------------------------------
+    async listTemplates() {
+        if (isDisabled())
+            return [];
+        const url = process.env['WP_BLUEPRINT_TEMPLATES_URL'] ?? DEFAULT_TEMPLATES_URL;
+        try {
+            const response = await this.fetchFn(url, { method: 'GET' });
+            if (!response.ok)
+                return [];
+            const json = (await response.json());
+            return json;
+        }
+        catch {
+            return [];
+        }
+    }
+    // -------------------------------------------------------------------------
+    // healthCheck
+    // -------------------------------------------------------------------------
+    async healthCheck() {
+        if (isDisabled())
+            return { ok: false, latencyMs: 0 };
+        const url = `${this.creds.platformUrl}/health`;
+        const start = Date.now();
+        try {
+            const response = await this.fetchFn(url, {
+                method: 'GET',
+                headers: this.authHeaders(),
+            });
+            const latencyMs = Date.now() - start;
+            return { ok: response.ok, latencyMs };
+        }
+        catch {
+            return { ok: false, latencyMs: 0 };
+        }
+    }
+    // -------------------------------------------------------------------------
+    // Internal helpers
+    // -------------------------------------------------------------------------
+    authHeaders() {
+        return {
+            Authorization: `Bearer ${this.creds.token}`,
+            'Content-Type': 'application/json',
+        };
+    }
+    /**
+     * Perform a single fetch without retry logic.
+     * Throws on non-ok responses (except 409 which is treated as success).
+     */
+    async fetchOnce(url, init) {
+        const response = await this.fetchFn(url, init);
+        if (response.status === 401) {
+            throw new AuthError(`401 Unauthorized — re-authentication required for ${url}`);
+        }
+        if (!response.ok && response.status !== 409) {
+            throw new Error(`HTTP ${response.status} from ${url}`);
+        }
+        return response;
+    }
+    /**
+     * Perform a fetch with retry logic (max 3 attempts, exponential backoff).
+     *
+     * - 401: throw AuthError immediately (no retry).
+     * - 409: return immediately (idempotent success).
+     * - 429 / 5xx: retry with exponential backoff.
+     * - Network errors: retry with exponential backoff, then throw with offline context.
+     *
+     * The `onAttempt` callback fires after EACH attempt (including the final one)
+     * with the HTTP status and duration. On network error, status = 0.
+     */
+    async retryFetch(url, init, onAttempt) {
+        const { maxAttempts, baseDelayMs } = this.retryOpts;
+        let lastError;
+        for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+            const start = Date.now();
+            try {
+                const response = await this.fetchFn(url, init);
+                const durationMs = Date.now() - start;
+                onAttempt?.(response.status, durationMs);
+                if (response.status === 401) {
+                    throw new AuthError(`401 Unauthorized — re-authentication required for ${url}`);
+                }
+                if (response.status === 409) {
+                    return response; // idempotent — treat as success
+                }
+                if (isRetryableStatus(response.status)) {
+                    lastError = new Error(`HTTP ${response.status} from ${url}`);
+                    if (attempt < maxAttempts) {
+                        await sleep(baseDelayMs * 2 ** (attempt - 1));
+                        continue;
+                    }
+                    throw lastError;
+                }
+                if (!response.ok) {
+                    throw new Error(`HTTP ${response.status} from ${url}`);
+                }
+                return response;
+            }
+            catch (error) {
+                if (error instanceof AuthError)
+                    throw error;
+                const durationMs = Date.now() - start;
+                onAttempt?.(0, durationMs);
+                lastError = error;
+                if (attempt < maxAttempts) {
+                    await sleep(baseDelayMs * 2 ** (attempt - 1));
+                    continue;
+                }
+                // Final attempt failed — wrap with offline context if it looks like a
+                // network error (not an HTTP error we re-threw above).
+                const msg = error instanceof Error ? error.message : String(error);
+                const isNetworkError = !msg.startsWith('HTTP ');
+                if (isNetworkError) {
+                    throw new Error(`Network error (offline?): ${msg}. Check connectivity and retry.`);
+                }
+                throw error;
+            }
+        }
+        // Unreachable, but satisfies TypeScript's exhaustive analysis.
+        throw lastError;
+    }
+}
+//# sourceMappingURL=client.js.map

package/dist/esm/blueprint/sync/replica.d.ts

@@ -0,0 +1,55 @@
+/**
+ * ReplicaManager — pull-on-demand replica freshness guard.
+ *
+ * Checks a TTL before calling getSnapshot() and implements a single-flight
+ * pattern so that concurrent calls within the same process share the
+ * in-flight pull promise (no thundering herd).
+ *
+ * Design decisions resolved 2026-05-12:
+ *  Q3: 30 s TTL default; configurable via WP_BLUEPRINT_REPLICA_TTL_S.
+ *  CEO review § 7: single-flight via module-level Map<key, Promise<void>>.
+ *  WP_BLUEPRINT_PLATFORM_DISABLED=1: ensureFresh is always a no-op.
+ */
+import type { Database } from '#db/sqlite.js';
+import type { BlueprintPlatformClient } from './types.js';
+export interface ReplicaState {
+    readonly lastPulledAt: number;
+    readonly pullCount: number;
+    readonly consecutiveFailures: number;
+}
+export interface ReplicaOptions {
+    readonly ttlSeconds?: number;
+    readonly client: BlueprintPlatformClient;
+    readonly db: Database;
+}
+export declare class ReplicaManager {
+    private readonly opts;
+    private lastPulledAt;
+    private pullCount;
+    private consecutiveFailures;
+    constructor(opts: ReplicaOptions);
+    /**
+     * Check freshness and pull if stale.
+     *
+     * Single-flight: concurrent calls within the same process share the
+     * in-flight pull promise keyed by slug.
+     */
+    ensureFresh(opts?: {
+        readonly slug?: string;
+    }): Promise<void>;
+    /**
+     * Force a pull regardless of TTL (e.g. used by `wp setup --sync`).
+     * Does NOT participate in single-flight — each forcePull is independent.
+     */
+    forcePull(opts?: {
+        readonly slug?: string;
+    }): Promise<void>;
+    /** Current replica state for observability. */
+    getState(): ReplicaState;
+    private scheduleWithSingleFlight;
+    private doActualPull;
+    private initSchema;
+    private persistMeta;
+    private persistFailure;
+}
+//# sourceMappingURL=replica.d.ts.map

package/dist/esm/blueprint/sync/replica.js

@@ -0,0 +1,139 @@
+/**
+ * ReplicaManager — pull-on-demand replica freshness guard.
+ *
+ * Checks a TTL before calling getSnapshot() and implements a single-flight
+ * pattern so that concurrent calls within the same process share the
+ * in-flight pull promise (no thundering herd).
+ *
+ * Design decisions resolved 2026-05-12:
+ *  Q3: 30 s TTL default; configurable via WP_BLUEPRINT_REPLICA_TTL_S.
+ *  CEO review § 7: single-flight via module-level Map<key, Promise<void>>.
+ *  WP_BLUEPRINT_PLATFORM_DISABLED=1: ensureFresh is always a no-op.
+ */
+// ---------------------------------------------------------------------------
+// Module-level single-flight registry
+//
+// Keyed by `slug ?? '*'`. If 6 parallel pll agents all expire the TTL at
+// the same instant, only one getSnapshot() call goes out — the rest await
+// the same Promise<void>.
+// ---------------------------------------------------------------------------
+const inflight = new Map();
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+const DEFAULT_TTL_S = 30;
+function getEnvTtl() {
+    const raw = process.env['WP_BLUEPRINT_REPLICA_TTL_S'];
+    if (!raw)
+        return DEFAULT_TTL_S;
+    const parsed = Number(raw);
+    return Number.isFinite(parsed) && parsed >= 0 ? parsed : DEFAULT_TTL_S;
+}
+function isPlatformDisabled() {
+    return process.env['WP_BLUEPRINT_PLATFORM_DISABLED'] === '1';
+}
+// ---------------------------------------------------------------------------
+// ReplicaManager
+// ---------------------------------------------------------------------------
+export class ReplicaManager {
+    opts;
+    lastPulledAt = 0;
+    pullCount = 0;
+    consecutiveFailures = 0;
+    constructor(opts) {
+        this.opts = opts;
+        this.initSchema();
+    }
+    /**
+     * Check freshness and pull if stale.
+     *
+     * Single-flight: concurrent calls within the same process share the
+     * in-flight pull promise keyed by slug.
+     */
+    async ensureFresh(opts) {
+        if (isPlatformDisabled())
+            return;
+        const ttlMs = (this.opts.ttlSeconds ?? getEnvTtl()) * 1000;
+        const ageMs = Date.now() - this.lastPulledAt;
+        if (ageMs < ttlMs)
+            return; // still fresh
+        return this.scheduleWithSingleFlight(opts?.slug, () => this.doActualPull(opts?.slug));
+    }
+    /**
+     * Force a pull regardless of TTL (e.g. used by `wp setup --sync`).
+     * Does NOT participate in single-flight — each forcePull is independent.
+     */
+    async forcePull(opts) {
+        return this.doActualPull(opts?.slug);
+    }
+    /** Current replica state for observability. */
+    getState() {
+        return {
+            lastPulledAt: this.lastPulledAt,
+            pullCount: this.pullCount,
+            consecutiveFailures: this.consecutiveFailures,
+        };
+    }
+    // ── Private ───────────────────────────────────────────────────────────────
+    scheduleWithSingleFlight(slug, work) {
+        const key = slug ?? '*';
+        const existing = inflight.get(key);
+        if (existing !== undefined)
+            return existing;
+        const pull = work().finally(() => {
+            inflight.delete(key);
+        });
+        inflight.set(key, pull);
+        return pull;
+    }
+    async doActualPull(slug) {
+        try {
+            await this.opts.client.getSnapshot(slug !== undefined ? { slug } : undefined);
+            const now = Date.now();
+            this.lastPulledAt = now;
+            this.pullCount++;
+            this.consecutiveFailures = 0;
+            this.persistMeta(now);
+        }
+        catch (err) {
+            this.consecutiveFailures++;
+            this.persistFailure();
+            throw err;
+        }
+    }
+    // ── SQLite replica_meta schema ────────────────────────────────────────────
+    initSchema() {
+        this.opts.db.exec(`
+      CREATE TABLE IF NOT EXISTS replica_meta (
+        key   TEXT PRIMARY KEY,
+        value TEXT NOT NULL
+      )
+    `);
+        // Load persisted state if present
+        const row = this.opts.db
+            .prepare('SELECT key, value FROM replica_meta')
+            .all();
+        for (const { key, value } of row) {
+            if (key === 'last_pulled_at')
+                this.lastPulledAt = Number(value);
+            if (key === 'pull_count')
+                this.pullCount = Number(value);
+            if (key === 'consecutive_failures')
+                this.consecutiveFailures = Number(value);
+        }
+    }
+    persistMeta(now) {
+        const upsert = this.opts.db.prepare('INSERT INTO replica_meta (key, value) VALUES (?, ?) ON CONFLICT(key) DO UPDATE SET value = excluded.value');
+        const run = this.opts.db.transaction(() => {
+            upsert.run('last_pulled_at', String(now));
+            upsert.run('pull_count', String(this.pullCount));
+            upsert.run('consecutive_failures', String(this.consecutiveFailures));
+        });
+        run();
+    }
+    persistFailure() {
+        const upsert = this.opts.db.prepare('INSERT INTO replica_meta (key, value) VALUES (?, ?) ON CONFLICT(key) DO UPDATE SET value = excluded.value');
+        upsert.run('consecutive_failures', String(this.consecutiveFailures));
+    }
+}
+//# sourceMappingURL=replica.js.map

package/dist/esm/blueprint/sync/types.d.ts

@@ -0,0 +1,178 @@
+/**
+ * BlueprintPlatformClient — public OSS boundary between webpresso and the
+ * private webpresso platform-api.
+ *
+ * Platform team implements this interface; webpresso ships the types.
+ * The platform URL is injected at runtime via `WP_BLUEPRINT_PLATFORM_URL`.
+ *
+ * Design decisions (resolved 2026-05-12, platform team design session):
+ *  Q1: Buffer locally, push on reconnect. `eventId` provides idempotency.
+ *  Q2: OAuth device flow; token injected as `getToken()` at construction.
+ *  Q3: 30s replica TTL; consumer calls `getSnapshot()` when TTL expires.
+ *  Q4: No markdown — platform is canonical; only structured data.
+ *  Q5: GitHub-hosted templates; `listTemplates()` reads from a GitHub URL.
+ *  Q6: Types + client in webpresso (OSS); implementation in monorepo.
+ *  Q7: Import existing blueprints on first auth via `pushEvent` bulk call.
+ */
+/**
+ * The public interface that every platform-api adapter must satisfy.
+ *
+ * Consumers obtain a concrete implementation via dependency injection:
+ *
+ * ```ts
+ * import type { BlueprintPlatformClient } from 'webpresso/blueprint/sync/types'
+ *
+ * class MyAdapter implements BlueprintPlatformClient { ... }
+ * ```
+ */
+export interface BlueprintPlatformClient {
+    /**
+     * Push a mutation event to the platform.
+     *
+     * Idempotent: the platform returns 200 and skips re-applying an event whose
+     * `eventId` has already been processed for this `repoId`.  Callers should
+     * persist unacknowledged events locally and retry when reconnected (Q1).
+     */
+    pushEvent(payload: BlueprintPlatformEvent): Promise<void>;
+    /**
+     * Pull the current state from the platform replica.
+     *
+     * Called by the local TTL-refresh logic (default TTL: 30 s, Q3).
+     * When `opts.slug` is supplied only that blueprint's data is returned;
+     * omitting it returns the full repo snapshot.
+     */
+    getSnapshot(opts?: {
+        readonly slug?: string;
+    }): Promise<BlueprintSnapshot>;
+    /**
+     * Enumerate available blueprint templates from the configured GitHub source
+     * (Q5).  Returns an empty array when the template source is unreachable.
+     */
+    listTemplates(): Promise<readonly BlueprintTemplateEntry[]>;
+    /**
+     * Check connectivity and OAuth token validity.
+     *
+     * Returns `ok: false` and a non-zero `latencyMs` on network failure or
+     * auth errors so callers can surface status to the user without crashing.
+     */
+    healthCheck(): Promise<{
+        readonly ok: boolean;
+        readonly latencyMs: number;
+    }>;
+}
+/**
+ * The 8 mutation operations that can occur on a blueprint or its tasks.
+ *
+ * Exhaustiveness is enforced in `types.test.ts` via a compile-time switch
+ * with a `never` default branch.
+ */
+export type BlueprintEventType = 'blueprint.created' | 'blueprint.status_changed' | 'blueprint.archived' | 'blueprint.finalized' | 'blueprint.metadata_updated' | 'task.created' | 'task.status_changed' | 'runner.event';
+/**
+ * A single mutation event delivered to the platform.
+ *
+ * `eventId` is a UUID v4 generated by the client.  The platform treats the
+ * `(repoId, eventId)` pair as a unique key: a second push with the same pair
+ * returns 200 and is silently ignored (Q1 idempotency).
+ */
+export interface BlueprintPlatformEvent {
+    /** UUID v4, client-generated, used as the idempotency key. */
+    readonly eventId: string;
+    /** Signed repo identifier supplied by the platform during OAuth (Q2). */
+    readonly repoId: string;
+    /** ISO 8601 timestamp of when the mutation occurred on the client. */
+    readonly occurredAt: string;
+    /** Discriminant that matches the `payload.type` field. */
+    readonly type: BlueprintEventType;
+    /** Structured payload whose shape is determined by `type`. */
+    readonly payload: BlueprintEventPayload;
+}
+/**
+ * Discriminated union on `type` — one variant per `BlueprintEventType`.
+ *
+ * Adding a new event type to `BlueprintEventType` without adding a
+ * corresponding variant here will surface as a TypeScript compile error in
+ * any exhaustive switch that uses `never` as the default branch.
+ */
+export type BlueprintEventPayload = {
+    readonly type: 'blueprint.created';
+    readonly slug: string;
+    readonly title: string;
+    readonly complexity: string;
+    readonly status: string;
+} | {
+    readonly type: 'blueprint.status_changed';
+    readonly slug: string;
+    readonly fromStatus: string;
+    readonly toStatus: string;
+} | {
+    readonly type: 'blueprint.archived';
+    readonly slug: string;
+} | {
+    readonly type: 'blueprint.finalized';
+    readonly slug: string;
+} | {
+    readonly type: 'blueprint.metadata_updated';
+    readonly slug: string;
+    /** Sparse map of the fields that changed (key = field name, value = new value). */
+    readonly changes: Readonly<Record<string, unknown>>;
+} | {
+    readonly type: 'task.created';
+    readonly blueprintSlug: string;
+    readonly taskId: string;
+    readonly title: string;
+} | {
+    readonly type: 'task.status_changed';
+    readonly blueprintSlug: string;
+    readonly taskId: string;
+    readonly fromStatus: string;
+    readonly toStatus: string;
+} | {
+    readonly type: 'runner.event';
+    readonly blueprintSlug: string;
+    /** Matches the `handle` field of the RunnerEvent from Wave 1 runner work. */
+    readonly executionHandle: string;
+    /** Monotonically increasing position in the runner event stream. */
+    readonly sequence: number;
+    /**
+     * Discriminant that mirrors `RunnerEvent.type` (e.g. 'started',
+     * 'progress', 'stdout', 'completed', 'failed').
+     */
+    readonly kind: string;
+};
+/**
+ * Full or partial replica of blueprint state returned by `getSnapshot()`.
+ */
+export interface BlueprintSnapshot {
+    readonly blueprints: readonly SnapshotBlueprint[];
+    /** ISO 8601 timestamp of when the platform generated this snapshot. */
+    readonly fetchedAt: string;
+}
+/** A single blueprint's state as stored in the platform replica. */
+export interface SnapshotBlueprint {
+    readonly slug: string;
+    readonly title: string;
+    readonly status: string;
+    readonly complexity: string;
+    readonly tasks: readonly SnapshotTask[];
+}
+/** A single task within a blueprint snapshot. */
+export interface SnapshotTask {
+    readonly id: string;
+    readonly title: string;
+    readonly status: string;
+    /** Task IDs that must complete before this task can start. */
+    readonly dependsOn: readonly string[];
+}
+/**
+ * A single entry in the GitHub-hosted blueprint template catalog (Q5).
+ *
+ * `url` points to the raw markdown source on GitHub from which
+ * `wp blueprint new --template <slug>` fetches the scaffold.
+ */
+export interface BlueprintTemplateEntry {
+    readonly name: string;
+    readonly slug: string;
+    readonly url: string;
+    readonly description?: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/esm/blueprint/sync/types.js

@@ -0,0 +1,18 @@
+/**
+ * BlueprintPlatformClient — public OSS boundary between webpresso and the
+ * private webpresso platform-api.
+ *
+ * Platform team implements this interface; webpresso ships the types.
+ * The platform URL is injected at runtime via `WP_BLUEPRINT_PLATFORM_URL`.
+ *
+ * Design decisions (resolved 2026-05-12, platform team design session):
+ *  Q1: Buffer locally, push on reconnect. `eventId` provides idempotency.
+ *  Q2: OAuth device flow; token injected as `getToken()` at construction.
+ *  Q3: 30s replica TTL; consumer calls `getSnapshot()` when TTL expires.
+ *  Q4: No markdown — platform is canonical; only structured data.
+ *  Q5: GitHub-hosted templates; `listTemplates()` reads from a GitHub URL.
+ *  Q6: Types + client in webpresso (OSS); implementation in monorepo.
+ *  Q7: Import existing blueprints on first auth via `pushEvent` bulk call.
+ */
+export {};
+//# sourceMappingURL=types.js.map