yaver-feedback-react-native 0.9.0 → 0.9.3

package/dist/DogfoodRuntime.d.ts

@@ -0,0 +1,124 @@
+/**
+ * Embeddable Dogfood orchestration for React Native hosts.
+ *
+ * The SDK deliberately does not own the host's button, WebView, navigation, or
+ * Yaver transport. It owns the failure-prone lifecycle underneath them:
+ * explicit trigger -> prepare -> start -> ready, bounded log retention,
+ * generation-safe Retry, and deterministic cleanup of partial sessions.
+ *
+ * Yaver mobile uses this class for Yaver-on-Yaver. Third-party apps use the
+ * same class with their own project descriptor and a driver backed by
+ * P2PClient (or another authenticated Yaver transport).
+ */
+export type DogfoodLane = 'browser' | 'hermes' | 'webrtc';
+export type DogfoodPhase = 'idle' | 'preparing' | 'starting' | 'compiling' | 'ready' | 'failed' | 'stopping' | 'stopped';
+export interface DogfoodProject {
+    name: string;
+    workDir: string;
+    framework: string;
+    lane: DogfoodLane;
+    /** Optional source URL for drivers that can clone missing source. */
+    repositoryUrl?: string;
+    /** Optional native target from /remote-runtime/capabilities for WebRTC. */
+    nativeTargetId?: string;
+}
+export interface DogfoodLaneOption {
+    lane: DogfoodLane;
+    label: string;
+    supported: boolean;
+    default: boolean;
+    reason?: string;
+}
+/** One framework-to-lane matrix for Yaver and third-party consumers. */
+export declare function dogfoodLaneOptions(framework: string, capabilities?: {
+    nativeRuntimeAvailable?: boolean;
+    selfDevelopment?: boolean;
+}): DogfoodLaneOption[];
+export declare function defaultDogfoodLane(framework: string): DogfoodLane;
+export interface DogfoodLogLine {
+    text: string;
+    at: number;
+    stream?: 'stdout' | 'stderr' | 'system';
+}
+export interface DogfoodFailure {
+    code: string;
+    error: string;
+    remedy: string;
+    retryable: boolean;
+    fixPrompt?: string;
+}
+export interface DogfoodResult {
+    lane: DogfoodLane;
+    url?: string;
+    sessionId?: string;
+    metadata?: Record<string, unknown>;
+}
+export interface DogfoodSnapshot {
+    phase: DogfoodPhase;
+    attempt: number;
+    project: DogfoodProject;
+    message: string;
+    logs: readonly DogfoodLogLine[];
+    startedAt?: number;
+    lastOutputAt?: number;
+    result?: DogfoodResult;
+    failure?: DogfoodFailure;
+}
+export interface DogfoodRunContext {
+    project: DogfoodProject;
+    attempt: number;
+    /** Raw package-manager/compiler output. ANSI is intentionally preserved. */
+    log(line: string | DogfoodLogLine): void;
+    setPhase(phase: Extract<DogfoodPhase, 'preparing' | 'starting' | 'compiling'>, message: string): void;
+    /**
+     * Register cleanup immediately after acquiring a resource.
+     *
+     * `session` cleanups run on failure/stop. `transient` cleanups also run when
+     * ownership is handed to another screen (normally an SSE subscription).
+     */
+    registerCleanup(cleanup: () => void | Promise<void>, scope?: 'session' | 'transient'): void;
+    isCurrent(): boolean;
+}
+export interface DogfoodDriver {
+    prepare?(context: DogfoodRunContext): Promise<void>;
+    start(context: DogfoodRunContext): Promise<DogfoodResult>;
+}
+export interface DogfoodControllerOptions {
+    maxLogLines?: number;
+    onChange?: (snapshot: DogfoodSnapshot) => void;
+}
+export declare class DogfoodRuntimeError extends Error {
+    readonly failure: DogfoodFailure;
+    constructor(failure: DogfoodFailure);
+}
+export declare function validateDogfoodProject(project: DogfoodProject): DogfoodFailure | null;
+/** Convert one /dev/events frame into console lines without hiding raw output. */
+export declare function runtimeLogLinesFromDevEvent(event: any): string[];
+/** Backwards-friendly name for consumers that discovered this via Dogfood. */
+export declare const dogfoodLogLinesFromDevEvent: typeof runtimeLogLinesFromDevEvent;
+export declare class DogfoodController {
+    readonly project: DogfoodProject;
+    private readonly driver;
+    private generation;
+    private cleanups;
+    private runPromise;
+    private readonly maxLogLines;
+    private readonly onChange?;
+    private state;
+    constructor(project: DogfoodProject, driver: DogfoodDriver, options?: DogfoodControllerOptions);
+    snapshot(): DogfoodSnapshot;
+    /** Nothing starts until the host calls this method from its explicit action. */
+    trigger(): Promise<DogfoodResult>;
+    retry(): Promise<DogfoodResult>;
+    private run;
+    /** Stop the active/partial run and release every resource. Idempotent. */
+    stop(): Promise<void>;
+    /**
+     * Transfer the live session to a host-owned preview screen. Stream/timer
+     * cleanups run; session cleanup is discarded because the receiving screen
+     * now owns it.
+     */
+    handoff(): Promise<DogfoodResult | undefined>;
+    private runCleanups;
+    private replace;
+}

package/dist/DogfoodRuntime.js

@@ -0,0 +1,273 @@
+"use strict";
+/**
+ * Embeddable Dogfood orchestration for React Native hosts.
+ *
+ * The SDK deliberately does not own the host's button, WebView, navigation, or
+ * Yaver transport. It owns the failure-prone lifecycle underneath them:
+ * explicit trigger -> prepare -> start -> ready, bounded log retention,
+ * generation-safe Retry, and deterministic cleanup of partial sessions.
+ *
+ * Yaver mobile uses this class for Yaver-on-Yaver. Third-party apps use the
+ * same class with their own project descriptor and a driver backed by
+ * P2PClient (or another authenticated Yaver transport).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DogfoodController = exports.dogfoodLogLinesFromDevEvent = exports.DogfoodRuntimeError = void 0;
+exports.dogfoodLaneOptions = dogfoodLaneOptions;
+exports.defaultDogfoodLane = defaultDogfoodLane;
+exports.validateDogfoodProject = validateDogfoodProject;
+exports.runtimeLogLinesFromDevEvent = runtimeLogLinesFromDevEvent;
+/** One framework-to-lane matrix for Yaver and third-party consumers. */
+function dogfoodLaneOptions(framework, capabilities = {}) {
+    const normalized = String(framework || '').trim().toLowerCase();
+    const reactNative = normalized === 'expo' || normalized === 'react-native';
+    const browserCapable = reactNative || [
+        'flutter', 'web', 'next', 'nextjs', 'vite', 'remix', 'svelte', 'vue', 'angular',
+    ].includes(normalized);
+    const nativeAvailable = capabilities.nativeRuntimeAvailable === true;
+    const hermesReason = reactNative
+        ? undefined
+        : 'Hermes is available only for Expo and React Native projects.';
+    const browserReason = browserCapable
+        ? undefined
+        : 'The browser lane is available for browser-capable projects such as React Native, Expo, Flutter, and web apps.';
+    return [
+        { lane: 'browser', label: 'Browser lane', supported: browserCapable, default: browserCapable, reason: browserReason },
+        { lane: 'hermes', label: 'Hermes', supported: !hermesReason, default: false, reason: hermesReason },
+        {
+            lane: 'webrtc', label: 'WebRTC native', supported: nativeAvailable, default: false,
+            reason: nativeAvailable ? undefined : 'No native simulator, emulator, or device runtime is available on this machine.',
+        },
+    ];
+}
+function defaultDogfoodLane(framework) {
+    return dogfoodLaneOptions(framework).find((option) => option.default && option.supported)?.lane || 'browser';
+}
+class DogfoodRuntimeError extends Error {
+    constructor(failure) {
+        super(failure.error);
+        this.name = 'DogfoodRuntimeError';
+        this.failure = failure;
+    }
+}
+exports.DogfoodRuntimeError = DogfoodRuntimeError;
+function validateDogfoodProject(project) {
+    const framework = String(project.framework || '').trim().toLowerCase();
+    if (!String(project.workDir || '').trim()) {
+        return {
+            code: 'DOGFOOD_PROJECT_PATH_REQUIRED',
+            error: 'Dogfood needs the project directory on the selected machine.',
+            remedy: 'Choose or clone the project source, then trigger Dogfood again.',
+            retryable: false,
+        };
+    }
+    if (project.lane === 'hermes' && framework !== 'expo' && framework !== 'react-native') {
+        return {
+            code: 'DOGFOOD_HERMES_FRAMEWORK_UNSUPPORTED',
+            error: `Hermes cannot run a ${framework || 'non-React-Native'} project.`,
+            remedy: framework === 'flutter'
+                ? 'Use the browser lane (Flutter web) or WebRTC for a native Flutter runtime.'
+                : 'Use the browser or WebRTC lane, or select an Expo/React Native project.',
+            retryable: false,
+        };
+    }
+    return null;
+}
+/** Convert one /dev/events frame into console lines without hiding raw output. */
+function runtimeLogLinesFromDevEvent(event) {
+    if (!event || typeof event !== 'object')
+        return [];
+    if (event.type === 'log' && typeof event.logLine === 'string') {
+        return event.logLine.trimEnd() ? [event.logLine.trimEnd()] : [];
+    }
+    if (event.type === 'snapshot' && Array.isArray(event.snapshot?.recentLogs)) {
+        return event.snapshot.recentLogs
+            .map((line) => String(line).trimEnd())
+            .filter(Boolean);
+    }
+    if (event.type === 'progress' || event.type === 'phase') {
+        const phase = typeof event.phase === 'string' ? event.phase.replace(/_/g, ' ') : 'working';
+        const pct = typeof event.pct === 'number' ? ` ${Math.round(event.pct)}%` : '';
+        const file = typeof event.currentFile === 'string' && event.currentFile
+            ? ` · ${String(event.currentFile).split('/').slice(-2).join('/')}`
+            : '';
+        return [`${phase}${pct}${file}`.trim()];
+    }
+    if (event.type === 'error') {
+        return String(event.message || 'Dev server failed')
+            .split('\n')
+            .map((line) => line.trimEnd())
+            .filter(Boolean);
+    }
+    if (typeof event.message === 'string' && event.message.trim() &&
+        ['starting', 'building', 'phase', 'ready', 'reload', 'stopped'].includes(String(event.type))) {
+        return [event.message.trimEnd()];
+    }
+    return [];
+}
+/** Backwards-friendly name for consumers that discovered this via Dogfood. */
+exports.dogfoodLogLinesFromDevEvent = runtimeLogLinesFromDevEvent;
+function failureFrom(error) {
+    if (error instanceof DogfoodRuntimeError)
+        return error.failure;
+    const candidate = error;
+    return {
+        code: typeof candidate?.code === 'string' ? candidate.code : 'DOGFOOD_START_FAILED',
+        error: error instanceof Error ? error.message : String(error || 'Dogfood could not start.'),
+        remedy: typeof candidate?.remedy === 'string'
+            ? candidate.remedy
+            : 'Fix the named project or runtime failure, then retry Dogfood.',
+        retryable: candidate?.retryable !== false,
+        fixPrompt: typeof candidate?.fixPrompt === 'string' ? candidate.fixPrompt : undefined,
+    };
+}
+class DogfoodController {
+    constructor(project, driver, options = {}) {
+        this.generation = 0;
+        // Cleanup ownership is per attempt. An old async attempt may finish after
+        // Stop + Retry has already acquired a new runtime; a shared list lets that
+        // obsolete attempt tear down the newer session. Generation-keyed ownership
+        // makes that race impossible while keeping Stop able to release everything.
+        this.cleanups = new Map();
+        this.runPromise = null;
+        this.project = project;
+        this.driver = driver;
+        this.maxLogLines = Math.max(20, options.maxLogLines ?? 200);
+        this.onChange = options.onChange;
+        this.state = { phase: 'idle', attempt: 0, project, message: 'Ready to dogfood', logs: [] };
+    }
+    snapshot() {
+        return { ...this.state, logs: [...this.state.logs] };
+    }
+    /** Nothing starts until the host calls this method from its explicit action. */
+    trigger() {
+        if (this.runPromise)
+            return this.runPromise;
+        const promise = this.run();
+        this.runPromise = promise;
+        void promise.finally(() => {
+            if (this.runPromise === promise)
+                this.runPromise = null;
+        }).catch(() => { });
+        return promise;
+    }
+    retry() {
+        return this.trigger();
+    }
+    async run() {
+        const generation = ++this.generation;
+        const attempt = this.state.attempt + 1;
+        await this.runCleanups('all');
+        const invalid = validateDogfoodProject(this.project);
+        if (invalid) {
+            this.replace({ phase: 'failed', attempt, project: this.project, message: invalid.error, logs: [], failure: invalid });
+            throw new DogfoodRuntimeError(invalid);
+        }
+        this.replace({
+            phase: 'preparing', attempt, project: this.project,
+            message: `Preparing ${this.project.name}…`, logs: [], startedAt: Date.now(),
+        });
+        const context = {
+            project: this.project,
+            attempt,
+            log: (line) => {
+                if (generation !== this.generation)
+                    return;
+                const entry = typeof line === 'string'
+                    ? { text: line, at: Date.now(), stream: 'stdout' }
+                    : { ...line, at: line.at || Date.now() };
+                if (!entry.text.trim())
+                    return;
+                const logs = [...this.state.logs, entry].slice(-this.maxLogLines);
+                this.replace({ ...this.state, logs, lastOutputAt: entry.at });
+            },
+            setPhase: (phase, message) => {
+                if (generation === this.generation)
+                    this.replace({ ...this.state, phase, message });
+            },
+            registerCleanup: (cleanup, scope = 'session') => {
+                if (generation !== this.generation) {
+                    void Promise.resolve(cleanup()).catch(() => { });
+                    return;
+                }
+                const owned = this.cleanups.get(generation) || [];
+                owned.push({ fn: cleanup, scope });
+                this.cleanups.set(generation, owned);
+            },
+            isCurrent: () => generation === this.generation,
+        };
+        try {
+            await this.driver.prepare?.(context);
+            if (!context.isCurrent())
+                throw new DogfoodRuntimeError({
+                    code: 'DOGFOOD_ATTEMPT_REPLACED', error: 'A newer Dogfood attempt replaced this one.',
+                    remedy: 'Wait for the newer attempt.', retryable: true,
+                });
+            context.setPhase('starting', `Starting ${this.project.name} on the ${this.project.lane} lane…`);
+            const result = await this.driver.start(context);
+            if (!context.isCurrent()) {
+                await this.runCleanups('all', generation);
+                throw new DogfoodRuntimeError({
+                    code: 'DOGFOOD_ATTEMPT_REPLACED', error: 'A newer Dogfood attempt replaced this one.',
+                    remedy: 'Wait for the newer attempt.', retryable: true,
+                });
+            }
+            this.replace({ ...this.state, phase: 'ready', message: `${this.project.name} is ready`, result, failure: undefined });
+            return result;
+        }
+        catch (error) {
+            const failure = failureFrom(error);
+            await this.runCleanups('all', generation);
+            if (generation === this.generation) {
+                this.replace({ ...this.state, phase: 'failed', message: failure.error, failure, result: undefined });
+            }
+            throw error instanceof DogfoodRuntimeError ? error : new DogfoodRuntimeError(failure);
+        }
+    }
+    /** Stop the active/partial run and release every resource. Idempotent. */
+    async stop() {
+        ++this.generation;
+        this.runPromise = null;
+        this.replace({ ...this.state, phase: 'stopping', message: `Stopping ${this.project.name}…` });
+        await this.runCleanups('all');
+        this.replace({ ...this.state, phase: 'stopped', message: `${this.project.name} stopped`, result: undefined });
+    }
+    /**
+     * Transfer the live session to a host-owned preview screen. Stream/timer
+     * cleanups run; session cleanup is discarded because the receiving screen
+     * now owns it.
+     */
+    async handoff() {
+        if (this.state.phase !== 'ready')
+            return undefined;
+        await this.runCleanups('transient', this.generation);
+        // The receiving screen now owns the live session. Forget its session
+        // cleanup without touching cleanups belonging to any other generation.
+        this.cleanups.delete(this.generation);
+        return this.state.result;
+    }
+    async runCleanups(which, generation) {
+        const generations = generation === undefined ? [...this.cleanups.keys()] : [generation];
+        const selected = [];
+        for (const key of generations) {
+            const owned = this.cleanups.get(key) || [];
+            selected.push(...(which === 'all' ? owned : owned.filter((item) => item.scope === 'transient')));
+            const retained = which === 'all' ? [] : owned.filter((item) => item.scope !== 'transient');
+            if (retained.length)
+                this.cleanups.set(key, retained);
+            else
+                this.cleanups.delete(key);
+        }
+        for (const cleanup of selected.reverse()) {
+            try {
+                await cleanup.fn();
+            }
+            catch { /* cleanup is best-effort but never skipped */ }
+        }
+    }
+    replace(next) {
+        this.state = next;
+        this.onChange?.(this.snapshot());
+    }
+}
+exports.DogfoodController = DogfoodController;