@heroku/sdk 0.1.0-beta.0

package/dist/resources/platform/dyno/index.js

@@ -0,0 +1,26 @@
+import { extendResource } from '../../../core/extend-resource.js';
+export async function scaleDynos(ctx, appIdentity, updates, options = {}) {
+    options.signal?.throwIfAborted();
+    const platform = options.signal ? ctx.platform.withOptions({ signal: options.signal }) : ctx.platform;
+    if (Array.isArray(updates)) {
+        return platform.formation.batchUpdate(appIdentity, { updates });
+    }
+    const { type, ...body } = updates;
+    return platform.formation.update(appIdentity, type, body);
+}
+export async function restartDynos(ctx, appIdentity, target, options = {}) {
+    options.signal?.throwIfAborted();
+    if (!target) {
+        await ctx.platform.dyno.restartAll(appIdentity);
+        return;
+    }
+    if ('dyno' in target) {
+        await ctx.platform.dyno.restart(appIdentity, target.dyno);
+        return;
+    }
+    await ctx.platform.dyno.restartFormation(appIdentity, target.type);
+}
+export const dynoExtensions = extendResource('platform', 'dyno', ctx => ({
+    restart: (appIdentity, target, options) => (restartDynos(ctx, appIdentity, target, options)),
+    scale: ((appIdentity, updates, options) => scaleDynos(ctx, appIdentity, updates, options)),
+}));

package/dist/resources/platform/dyno.d.ts

@@ -0,0 +1,45 @@
+import type { Formation } from '@heroku/types/3.sdk';
+import type { ResourceCtx } from '../../core/extend-resource.js';
+import type { StickyRouteOptions } from '../../core/create-client.js';
+export type DynoOptions = {
+    signal?: AbortSignal;
+};
+export type ScaleDynosUpdate = {
+    dyno_size?: {
+        id?: string;
+        name?: string;
+    };
+    quantity?: number | string;
+    size?: string;
+    type: string;
+};
+export type RestartDynosTarget = {
+    dyno: string;
+} | {
+    type: string;
+};
+type FormationClient = {
+    batchUpdate(appIdentity: string, body: {
+        updates: ScaleDynosUpdate[];
+    }): Promise<Formation[]>;
+    update(appIdentity: string, type: string, body: Omit<ScaleDynosUpdate, 'type'>): Promise<Formation>;
+};
+type ScalePlatform = {
+    formation: FormationClient;
+    withOptions(opts: StickyRouteOptions): ScalePlatform;
+};
+export declare function scaleDynos(ctx: {
+    platform: ScalePlatform;
+}, appIdentity: string, updates: ScaleDynosUpdate, options?: DynoOptions): Promise<Formation>;
+export declare function scaleDynos(ctx: {
+    platform: ScalePlatform;
+}, appIdentity: string, updates: ScaleDynosUpdate[], options?: DynoOptions): Promise<Formation[]>;
+export declare function restartDynos(ctx: Pick<ResourceCtx, 'platform'>, appIdentity: string, target?: RestartDynosTarget, options?: DynoOptions): Promise<void>;
+export declare const dynoExtensions: import("../../index.js").ResourceExtension<"platform", "dyno", {
+    restart: (appIdentity: string, target?: RestartDynosTarget, options?: DynoOptions) => Promise<void>;
+    scale: {
+        (appIdentity: string, updates: ScaleDynosUpdate, options?: DynoOptions): Promise<Formation>;
+        (appIdentity: string, updates: ScaleDynosUpdate[], options?: DynoOptions): Promise<Formation[]>;
+    };
+}>;
+export {};

package/dist/resources/platform/dyno.js

@@ -0,0 +1,26 @@
+import { extendResource } from '../../core/extend-resource.js';
+export async function scaleDynos(ctx, appIdentity, updates, options = {}) {
+    options.signal?.throwIfAborted();
+    const platform = options.signal ? ctx.platform.withOptions({ signal: options.signal }) : ctx.platform;
+    if (Array.isArray(updates)) {
+        return platform.formation.batchUpdate(appIdentity, { updates });
+    }
+    const { type, ...body } = updates;
+    return platform.formation.update(appIdentity, type, body);
+}
+export async function restartDynos(ctx, appIdentity, target, options = {}) {
+    options.signal?.throwIfAborted();
+    if (!target) {
+        await ctx.platform.dyno.restartAll(appIdentity);
+        return;
+    }
+    if ('dyno' in target) {
+        await ctx.platform.dyno.restart(appIdentity, target.dyno);
+        return;
+    }
+    await ctx.platform.dyno.restartFormation(appIdentity, target.type);
+}
+export const dynoExtensions = extendResource('platform', 'dyno', ctx => ({
+    restart: (appIdentity, target, options) => (restartDynos(ctx, appIdentity, target, options)),
+    scale: ((appIdentity, updates, options) => scaleDynos(ctx, appIdentity, updates, options)),
+}));

package/dist/resources/platform/log-session/index.d.ts

@@ -0,0 +1,102 @@
+import type { ResourceCtx } from '../../../core/extend-resource.js';
+import { parseHerokuLogLine } from './parser.js';
+export { type AttachmentAttachedEvent, type AttachmentDetachedEvent, type AttachmentUpdatedEvent, type HerokuLogEvent, parseHerokuLogLine, type ProvisioningCompletedEvent, type ScaledToEntry, type ScaledToEvent, type StartingProcessEvent, type StateChangedEvent, } from './parser.js';
+export type StreamLogsOptions = {
+    /** Limit output to a single dyno (e.g. `web.1` on Cedar, `web-abc-123` on Fir). */
+    dyno?: string;
+    /**
+     * Number of recent lines to fetch before tailing. Cedar-generation
+     * apps only — silently ignored on Fir.
+     */
+    lines?: number;
+    /**
+     * Maximum number of consecutive transport-error reconnects (TCP
+     * reset, proxy `terminated`, EOF mid-stream, etc.) before the
+     * iterator gives up and surfaces the error. Counter resets the
+     * moment a real line yields again. Defaults to 5.
+     */
+    maxConsecutiveTransportErrors?: number;
+    /**
+     * Cap on the per-attempt backoff after exponential growth.
+     * Defaults to 5000ms.
+     */
+    maxRetryDelayMs?: number;
+    /**
+     * Fires once per session creation, before the SDK opens the
+     * `logplex_url` stream. Receives the resolved generation so the
+     * caller can surface generation-specific UX (e.g. "Fetching
+     * logs..." for Fir, where provisioning the stream takes a moment).
+     *
+     * Fires on every recreate when tailing.
+     */
+    onSessionCreated?: (info: {
+        generation: 'cedar' | 'fir' | undefined;
+        isRecreate: boolean;
+    }) => Promise<void> | void;
+    /**
+     * When `tail` is true, watch for the platform's idle timeout and
+     * recreate the log session to keep streaming. Defaults to true.
+     * Set to false if you want a single bounded stream and surface the
+     * disconnect to the caller.
+     */
+    recreateSession?: boolean;
+    /**
+     * Initial backoff between reconnect attempts after a transport
+     * error; doubles each attempt up to {@link maxRetryDelayMs}.
+     * Defaults to 500ms.
+     */
+    retryBaseDelayMs?: number;
+    /**
+     * If `recreateSession` is true, the SDK forces a recreate after
+     * this many milliseconds without seeing data. Defaults to
+     * 15 minutes (matches the Fir platform timeout).
+     */
+    sessionTimeoutMs?: number;
+    signal?: AbortSignal;
+    /** Limit output to a single source (e.g. `app`, `heroku`). */
+    source?: string;
+    /**
+     * If true, the platform keeps the stream open and pushes lines as
+     * they arrive. The platform may close the connection on its own
+     * cadence (Fir is documented to time out around 15 minutes); when
+     * `recreateSession` is also true, the SDK transparently opens a
+     * new session and continues yielding lines.
+     *
+     * Defaults to false. Note: Fir-generation apps always tail (the
+     * platform doesn't support a bounded log session there), so the
+     * SDK forces `tail: true` for Fir regardless of what the caller
+     * asked for.
+     */
+    tail?: boolean;
+    /**
+     * Limit output to a process type (e.g. `web`, `worker`). On Cedar
+     * the underlying API combines `dyno` and `type` into a single
+     * field; the SDK handles that translation for you.
+     */
+    type?: string;
+};
+/**
+ * Stream logs for an app, yielding one line at a time.
+ *
+ * Creates a log session via `logSession.create`, opens the resulting
+ * `logplex_url`, and parses the chunked plain-text response into
+ * newline-delimited entries. Use `tail: true` to keep the stream
+ * open; `recreateSession: true` (the default when tailing) makes the
+ * SDK transparently re-open a new session after the platform's idle
+ * timeout, so the iterator keeps yielding without the caller having
+ * to handle the reconnect.
+ *
+ * The iterator terminates cleanly when:
+ *   - the platform closes a non-tailing stream (all lines yielded)
+ *   - `signal` is aborted (an `AbortError` propagates)
+ *   - `recreateSession` is false and the platform closes a tail
+ *
+ * The iterator throws on:
+ *   - non-2xx response from the logplex URL
+ *   - errors thrown by `logSession.create` (auth, app-not-found, etc.)
+ */
+export declare function streamLogs(ctx: Pick<ResourceCtx, 'platform'>, appIdentity: string, options?: StreamLogsOptions): AsyncGenerator<string, void, unknown>;
+export declare const logSessionExtensions: import("../../../index.js").ResourceExtension<"platform", "logSession", {
+    parseHerokuLogLine: typeof parseHerokuLogLine;
+    streamLogs: (appIdentity: string, options?: StreamLogsOptions) => AsyncGenerator<string, void, unknown>;
+}>;

package/dist/resources/platform/log-session/index.js

@@ -0,0 +1,223 @@
+import { HerokuApiClient } from '@heroku/heroku-fetch';
+import createDebug from 'debug';
+import { extendResource } from '../../../core/extend-resource.js';
+import { getGeneration } from '../app/index.js';
+import { parseHerokuLogLine } from './parser.js';
+export { parseHerokuLogLine, } from './parser.js';
+const debug = createDebug('heroku:sdk:resources:log-session');
+const DEFAULT_FIR_SESSION_TIMEOUT_MS = 15 * 60 * 1000;
+// Maximum consecutive transport errors before we give up — protects
+// against a persistently broken upstream (DNS, TLS, etc.) busy-looping
+// forever. The counter resets on every successful yield.
+const MAX_CONSECUTIVE_TRANSPORT_ERRORS = 5;
+// Initial backoff between recreate attempts; doubles up to a cap so
+// a bad-network burst doesn't hammer the platform.
+const TRANSPORT_RETRY_BASE_DELAY_MS = 500;
+const TRANSPORT_RETRY_MAX_DELAY_MS = 5000;
+/**
+ * Stream logs for an app, yielding one line at a time.
+ *
+ * Creates a log session via `logSession.create`, opens the resulting
+ * `logplex_url`, and parses the chunked plain-text response into
+ * newline-delimited entries. Use `tail: true` to keep the stream
+ * open; `recreateSession: true` (the default when tailing) makes the
+ * SDK transparently re-open a new session after the platform's idle
+ * timeout, so the iterator keeps yielding without the caller having
+ * to handle the reconnect.
+ *
+ * The iterator terminates cleanly when:
+ *   - the platform closes a non-tailing stream (all lines yielded)
+ *   - `signal` is aborted (an `AbortError` propagates)
+ *   - `recreateSession` is false and the platform closes a tail
+ *
+ * The iterator throws on:
+ *   - non-2xx response from the logplex URL
+ *   - errors thrown by `logSession.create` (auth, app-not-found, etc.)
+ */
+export async function* streamLogs(ctx, appIdentity, options = {}) {
+    const { dyno, lines, maxConsecutiveTransportErrors = MAX_CONSECUTIVE_TRANSPORT_ERRORS, maxRetryDelayMs = TRANSPORT_RETRY_MAX_DELAY_MS, retryBaseDelayMs = TRANSPORT_RETRY_BASE_DELAY_MS, sessionTimeoutMs = DEFAULT_FIR_SESSION_TIMEOUT_MS, signal, source, tail = false, type, } = options;
+    signal?.throwIfAborted();
+    const generation = await getGeneration(ctx, appIdentity, { signal });
+    const isFir = generation === 'fir';
+    // Fir doesn't support a bounded session; the platform always streams.
+    const effectiveTail = isFir ? true : tail;
+    const recreateSession = options.recreateSession ?? effectiveTail;
+    const createOpts = buildCreateOpts({
+        dyno, isFir, lines, source, tail: effectiveTail, type,
+    });
+    // The recreate loop is inherently sequential: each session must
+    // close before we ask for the next one.
+    /* eslint-disable no-await-in-loop */
+    let isRecreate = false;
+    let consecutiveTransportErrors = 0;
+    while (true) {
+        debug('streamLogs creating session app=%s generation=%s tail=%s', appIdentity, generation ?? '<unknown>', effectiveTail);
+        const session = await ctx.platform.logSession.create(appIdentity, createOpts);
+        if (!session.logplex_url) {
+            throw new Error('Log session response did not include a logplex_url.');
+        }
+        await options.onSessionCreated?.({ generation, isRecreate });
+        isRecreate = true;
+        debug('streamLogs session=%s opening stream', session.id);
+        let timedOut = false;
+        let timeoutHandle;
+        try {
+            // Logplex URLs hit a region-specific stream host (e.g.
+            // virginia.sessions.logs.heroku.com). The token is embedded in
+            // the URL, so we use a custom-service client with no auth and
+            // a per-call baseUrl; this also picks up heroku-fetch's
+            // env-var proxy support.
+            const parsed = new URL(session.logplex_url);
+            const logplexClient = new HerokuApiClient({
+                baseUrl: parsed.origin,
+                service: 'custom',
+                token: '',
+            });
+            const response = await logplexClient.stream(`${parsed.pathname}${parsed.search}`);
+            if (!response.body) {
+                throw new Error('Logplex stream returned no body.');
+            }
+            const reader = response.body.getReader();
+            const decoder = new TextDecoder();
+            let pending = '';
+            // Force a recreate after sessionTimeoutMs of silence; ignored
+            // when not tailing.
+            const armTimeout = () => {
+                if (!recreateSession)
+                    return;
+                if (timeoutHandle)
+                    clearTimeout(timeoutHandle);
+                timeoutHandle = setTimeout(() => {
+                    timedOut = true;
+                    debug('streamLogs session=%s timed out after %dms', session.id, sessionTimeoutMs);
+                    reader.cancel().catch(() => { });
+                }, sessionTimeoutMs);
+            };
+            armTimeout();
+            try {
+                while (true) {
+                    const { done, value } = await reader.read();
+                    if (done)
+                        break;
+                    armTimeout();
+                    pending += decoder.decode(value, { stream: true });
+                    let newlineIndex = pending.indexOf('\n');
+                    while (newlineIndex !== -1) {
+                        const line = pending.slice(0, newlineIndex);
+                        pending = pending.slice(newlineIndex + 1);
+                        if (line.length > 0) {
+                            consecutiveTransportErrors = 0;
+                            yield line;
+                        }
+                        newlineIndex = pending.indexOf('\n');
+                    }
+                }
+                // Flush any trailing partial line that didn't end in '\n'.
+                const trailing = pending + decoder.decode();
+                if (trailing.length > 0) {
+                    consecutiveTransportErrors = 0;
+                    yield trailing;
+                }
+            }
+            finally {
+                if (timeoutHandle)
+                    clearTimeout(timeoutHandle);
+                reader.releaseLock();
+            }
+            if (timedOut) {
+                debug('streamLogs session=%s recreating after timeout', session.id);
+                continue;
+            }
+            if (!recreateSession) {
+                return;
+            }
+            debug('streamLogs session=%s remote closed; recreating', session.id);
+        }
+        catch (error) {
+            if (timeoutHandle)
+                clearTimeout(timeoutHandle);
+            if (signal?.aborted)
+                throw error;
+            if (timedOut)
+                continue;
+            // When recreating, treat any transport-level failure (TCP
+            // reset, proxy `terminated`, EOF mid-stream, the documented
+            // Fir timeout, etc.) as recoverable: open a fresh session and
+            // keep yielding. Without this the iterator dies on the first
+            // network blip and tail consumers (e.g. the vscode resource
+            // explorer) silently lose updates.
+            //
+            // To keep a permanently-broken upstream from busy-looping, cap
+            // consecutive errors and back off between attempts. The counter
+            // resets the moment we yield a real line again.
+            if (recreateSession && consecutiveTransportErrors < maxConsecutiveTransportErrors) {
+                consecutiveTransportErrors++;
+                const delay = Math.min(retryBaseDelayMs * (2 ** (consecutiveTransportErrors - 1)), maxRetryDelayMs);
+                debug('streamLogs session=%s transport error (%d/%d); reconnecting after %dms: %s', session.id, consecutiveTransportErrors, maxConsecutiveTransportErrors, delay, error.message);
+                await waitOrAbort(delay, signal);
+                continue;
+            }
+            throw error;
+        }
+    }
+    /* eslint-enable no-await-in-loop */
+}
+/**
+ * Resolves after `ms` milliseconds, or rejects if the signal aborts
+ * first. Used between recreate attempts so a persistent transport
+ * failure doesn't busy-loop the platform's session-create endpoint.
+ */
+async function waitOrAbort(ms, signal) {
+    if (!signal) {
+        await new Promise(resolve => {
+            setTimeout(resolve, ms);
+        });
+        return;
+    }
+    await new Promise((resolve, reject) => {
+        if (signal.aborted) {
+            reject(signal.reason);
+            return;
+        }
+        const handle = setTimeout(() => {
+            signal.removeEventListener('abort', onAbort);
+            resolve();
+        }, ms);
+        const onAbort = () => {
+            clearTimeout(handle);
+            reject(signal.reason);
+        };
+        signal.addEventListener('abort', onAbort, { once: true });
+    });
+}
+/**
+ * Translate the SDK's consumer-facing options into the shape the
+ * platform's `log-sessions` endpoint expects per generation:
+ *   - Cedar's session takes a single `dyno` field that historically
+ *     accepted either a process type or a specific dyno; we collapse
+ *     `dyno || type` for the caller. `lines` and `tail` are honored.
+ *   - Fir's session takes `dyno` and `type` separately and ignores
+ *     `lines`; the stream always tails.
+ */
+function buildCreateOpts(options) {
+    const createOpts = { source: options.source };
+    if (options.isFir) {
+        if (options.dyno)
+            createOpts.dyno = options.dyno;
+        if (options.type)
+            createOpts.type = options.type;
+    }
+    else {
+        const cedarDyno = options.dyno ?? options.type;
+        if (cedarDyno)
+            createOpts.dyno = cedarDyno;
+        if (options.lines !== undefined)
+            createOpts.lines = options.lines;
+        createOpts.tail = options.tail;
+    }
+    return createOpts;
+}
+export const logSessionExtensions = extendResource('platform', 'logSession', ctx => ({
+    parseHerokuLogLine,
+    streamLogs: (appIdentity, options) => streamLogs(ctx, appIdentity, options),
+}));

package/dist/resources/platform/log-session/parser.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Parsed Heroku platform log events emitted by the runtime as
+ * plain-text lines on the `heroku` source. The event shapes are
+ * derived from the line patterns in {@link parseHerokuLogLine}.
+ *
+ * Each variant has a `kind` discriminator. Consumers should
+ * switch on `kind` to narrow.
+ */
+export type HerokuLogEvent = AttachmentAttachedEvent | AttachmentDetachedEvent | AttachmentUpdatedEvent | ProvisioningCompletedEvent | ScaledToEvent | StartingProcessEvent | StateChangedEvent;
+export type StateChangedEvent = {
+    /** Dyno or process token (e.g. `web.1` on Cedar, `web-abc-123` on Fir). */
+    dynoName: string;
+    from: string;
+    kind: 'state-changed';
+    /** Source token from the line prefix (e.g. `app`, `heroku`). */
+    source: string;
+    to: string;
+};
+export type AttachmentAttachedEvent = {
+    /** Config var name the attachment was bound to (e.g. `LOGDNA`). */
+    configVar: string;
+    kind: 'attachment-attached';
+    /** Stable platform reference (e.g. `logdna-deep-31633`). */
+    ref: string;
+};
+export type AttachmentDetachedEvent = {
+    configVar: string;
+    kind: 'attachment-detached';
+    ref: string;
+};
+export type AttachmentUpdatedEvent = {
+    /** Config var that was updated (e.g. `DATABASE`). */
+    configVar: string;
+    kind: 'attachment-updated';
+    /** Add-on service name from the line bracket (e.g. `heroku-postgres`). */
+    service: string;
+};
+export type ProvisioningCompletedEvent = {
+    kind: 'provisioning-completed';
+    ref: string;
+};
+/**
+ * A single `Scaled to ...` line can list multiple dyno types in one
+ * shot (e.g. `Scaled to web@2:Standard-1X worker@1:Standard-2X`).
+ * Each entry in `entries` is one dyno type from that line.
+ */
+export type ScaledToEvent = {
+    entries: ScaledToEntry[];
+    kind: 'scaled-to';
+};
+export type ScaledToEntry = {
+    /** Dyno type (e.g. `web`). */
+    dynoType: string;
+    /** Resulting dyno count. */
+    quantity: number;
+    /** Dyno size (e.g. `Standard-1X`). */
+    size: string;
+};
+export type StartingProcessEvent = {
+    /** Command without surrounding backticks (e.g. `npm start`). */
+    command: string;
+    dynoName: string;
+    kind: 'starting-process';
+    source: string;
+};
+/**
+ * Parse a single log line into a structured Heroku platform event,
+ * or `undefined` if the line does not match any known event pattern.
+ *
+ * Pure function — no I/O, no side effects. Compose with
+ * {@link streamLogs} to react to runtime events while still
+ * forwarding raw lines to a UI.
+ */
+export declare function parseHerokuLogLine(line: string): HerokuLogEvent | undefined;

package/dist/resources/platform/log-session/parser.js

@@ -0,0 +1,71 @@
+// On real platform input these patterns are mutually exclusive — each
+// line begins with a single verb (Attach/Detach/Update, State changed,
+// Starting process, Scaled to, ...completed provisioning), so the
+// order of `if` blocks in `parseHerokuLogLine` does not affect the
+// outcome. Order is for readability, not correctness.
+const STATE_CHANGED = /([a-zA-Z0-9-]+)\[([a-zA-Z0-9-.]+)\]: State changed from (\w+) to (\w+)/;
+const ATTACHMENT_UPDATED = /\[([a-zA-Z0-9-]+)\]: Update ([A-Z0-9_]+) by/;
+const ATTACHMENT_DETACHED = /Detach ([A-Z0-9_]+) \(@ref:([a-zA-Z0-9-]+)/;
+const ATTACHMENT_ATTACHED = /Attach ([A-Z0-9_]+) \(@ref:([a-zA-Z0-9-]+)/;
+const PROVISIONING_COMPLETED = /@ref:([a-zA-Z0-9-]+) completed provisioning/;
+const SCALED_TO_LINE = /\bScaled to ([a-zA-Z@:0-9_\- ]+)/;
+const SCALED_TO_ENTRY = /([a-zA-Z]+)@([0-9]+):([a-zA-Z0-9_-]+)/g;
+const STARTING_PROCESS = /([a-zA-Z0-9-]+)\[([a-zA-Z0-9-.]+)\]: Starting process with command `(.*?)`/;
+/**
+ * Parse a single log line into a structured Heroku platform event,
+ * or `undefined` if the line does not match any known event pattern.
+ *
+ * Pure function — no I/O, no side effects. Compose with
+ * {@link streamLogs} to react to runtime events while still
+ * forwarding raw lines to a UI.
+ */
+export function parseHerokuLogLine(line) {
+    const stateChanged = STATE_CHANGED.exec(line);
+    if (stateChanged) {
+        const [, source, dynoName, from, to] = stateChanged;
+        return {
+            dynoName, from, kind: 'state-changed', source, to,
+        };
+    }
+    const attachmentUpdated = ATTACHMENT_UPDATED.exec(line);
+    if (attachmentUpdated) {
+        const [, service, configVar] = attachmentUpdated;
+        return { configVar, kind: 'attachment-updated', service };
+    }
+    const attachmentDetached = ATTACHMENT_DETACHED.exec(line);
+    if (attachmentDetached) {
+        const [, configVar, ref] = attachmentDetached;
+        return { configVar, kind: 'attachment-detached', ref };
+    }
+    const attachmentAttached = ATTACHMENT_ATTACHED.exec(line);
+    if (attachmentAttached) {
+        const [, configVar, ref] = attachmentAttached;
+        return { configVar, kind: 'attachment-attached', ref };
+    }
+    const provisioningCompleted = PROVISIONING_COMPLETED.exec(line);
+    if (provisioningCompleted) {
+        return { kind: 'provisioning-completed', ref: provisioningCompleted[1] };
+    }
+    const scaledToLine = SCALED_TO_LINE.exec(line);
+    if (scaledToLine) {
+        const entries = [];
+        for (const match of scaledToLine[1].matchAll(SCALED_TO_ENTRY)) {
+            entries.push({
+                dynoType: match[1],
+                quantity: Number.parseInt(match[2], 10),
+                size: match[3],
+            });
+        }
+        if (entries.length > 0) {
+            return { entries, kind: 'scaled-to' };
+        }
+    }
+    const startingProcess = STARTING_PROCESS.exec(line);
+    if (startingProcess) {
+        const [, source, dynoName, command] = startingProcess;
+        return {
+            command, dynoName, kind: 'starting-process', source,
+        };
+    }
+    return undefined;
+}

package/dist/resources/platform/log-session.d.ts

@@ -0,0 +1,81 @@
+import type { ResourceCtx } from '../../core/extend-resource.js';
+export type StreamLogsOptions = {
+    /** Limit output to a single dyno (e.g. `web.1` on Cedar, `web-abc-123` on Fir). */
+    dyno?: string;
+    /**
+     * Number of recent lines to fetch before tailing. Cedar-generation
+     * apps only — silently ignored on Fir.
+     */
+    lines?: number;
+    /**
+     * Fires once per session creation, before the SDK opens the
+     * `logplex_url` stream. Receives the resolved generation so the
+     * caller can surface generation-specific UX (e.g. "Fetching
+     * logs..." for Fir, where provisioning the stream takes a moment).
+     *
+     * Fires on every recreate when tailing.
+     */
+    onSessionCreated?: (info: {
+        generation: 'cedar' | 'fir' | undefined;
+        isRecreate: boolean;
+    }) => Promise<void> | void;
+    /**
+     * When `tail` is true, watch for the platform's idle timeout and
+     * recreate the log session to keep streaming. Defaults to true.
+     * Set to false if you want a single bounded stream and surface the
+     * disconnect to the caller.
+     */
+    recreateSession?: boolean;
+    /**
+     * If `recreateSession` is true, the SDK forces a recreate after
+     * this many milliseconds without seeing data. Defaults to
+     * 15 minutes (matches the Fir platform timeout).
+     */
+    sessionTimeoutMs?: number;
+    signal?: AbortSignal;
+    /** Limit output to a single source (e.g. `app`, `heroku`). */
+    source?: string;
+    /**
+     * If true, the platform keeps the stream open and pushes lines as
+     * they arrive. The platform may close the connection on its own
+     * cadence (Fir is documented to time out around 15 minutes); when
+     * `recreateSession` is also true, the SDK transparently opens a
+     * new session and continues yielding lines.
+     *
+     * Defaults to false. Note: Fir-generation apps always tail (the
+     * platform doesn't support a bounded log session there), so the
+     * SDK forces `tail: true` for Fir regardless of what the caller
+     * asked for.
+     */
+    tail?: boolean;
+    /**
+     * Limit output to a process type (e.g. `web`, `worker`). On Cedar
+     * the underlying API combines `dyno` and `type` into a single
+     * field; the SDK handles that translation for you.
+     */
+    type?: string;
+};
+/**
+ * Stream logs for an app, yielding one line at a time.
+ *
+ * Creates a log session via `logSession.create`, opens the resulting
+ * `logplex_url`, and parses the chunked plain-text response into
+ * newline-delimited entries. Use `tail: true` to keep the stream
+ * open; `recreateSession: true` (the default when tailing) makes the
+ * SDK transparently re-open a new session after the platform's idle
+ * timeout, so the iterator keeps yielding without the caller having
+ * to handle the reconnect.
+ *
+ * The iterator terminates cleanly when:
+ *   - the platform closes a non-tailing stream (all lines yielded)
+ *   - `signal` is aborted (an `AbortError` propagates)
+ *   - `recreateSession` is false and the platform closes a tail
+ *
+ * The iterator throws on:
+ *   - non-2xx response from the logplex URL
+ *   - errors thrown by `logSession.create` (auth, app-not-found, etc.)
+ */
+export declare function streamLogs(ctx: Pick<ResourceCtx, 'platform'>, appIdentity: string, options?: StreamLogsOptions): AsyncGenerator<string, void, unknown>;
+export declare const logSessionExtensions: import("../../index.js").ResourceExtension<"platform", "logSession", {
+    streamLogs: (appIdentity: string, options?: StreamLogsOptions) => AsyncGenerator<string, void, unknown>;
+}>;