Expose app dev session files for agents - #8926

import { Writable } from 'stream';
/**
 * A stable error code for JSON consumers when a long-running command refuses to start because another instance of
 * it is already running for the same project.
 */
export declare const DEV_INSTANCE_ALREADY_RUNNING_CODE = "dev_instance_already_running";
/**
 * Describes a running instance of a long-running command such as `app dev` or `theme dev`.
 * It's written to `.shopify/dev/<slug>.json` so agents and other tools can discover the instance.
 */
export interface DevInstanceInfo {
    schemaVersion: 1;
    /** Identifies this run, including when the OS reuses a PID. */
    sessionId: string;
    /** The command that owns the instance, for example `app dev`. */
    command: string;
    /** Distinguishes instances of the same command in the same directory, for example the app configuration file. */
    key?: string;
    pid: number;
    status: 'starting' | 'running';
    startedAt: string;
    updatedAt: string;
    /** The project directory the instance runs for. */
    directory: string;
    /** The JSON Lines file the instance appends its output to. */
    logFile: string;
    /** Command-specific, JSON-serializable details such as URLs and ports. */
    details: {
        [key: string]: unknown;
    };
}
/** One line of a dev instance's JSON Lines log. */
export interface DevInstanceLogEntry {
    timestamp: string;
    /** What produced the line, for example a process prefix like `web` or `extensions`. */
    source: string;
    /** The stream the line was written to, when it comes from a process. */
    stream?: 'stdout' | 'stderr';
    level?: 'debug' | 'info' | 'warning' | 'error';
    message: string;
}
export interface DevInstancePaths {
    /** The folder that holds every dev instance of the project: `.shopify/dev`. */
    folder: string;
    /** The instance description. */
    infoFile: string;
    /** The lock directory, owned by `proper-lockfile`. */
    lockFile: string;
    /** The JSON Lines log. */
    logFile: string;
}
export interface DevInstanceIdentity {
    /** The command that owns the instance, for example `app dev`. */
    command: string;
    /** The project directory. */
    directory: string;
    /** Distinguishes several instances of the same command in the same directory. */
    key?: string;
}
export interface AcquireDevInstanceOptions extends DevInstanceIdentity {
    /** Initial command-specific details. */
    details?: {
        [key: string]: unknown;
    };
}
export interface DevInstanceUpdate {
    status?: DevInstanceInfo['status'];
    /** Merged into the existing details. */
    details?: {
        [key: string]: unknown;
    };
}
export interface DevInstance {
    readonly info: DevInstanceInfo;
    readonly paths: DevInstancePaths;
    /** Aborts when this session loses its lock or output fails. Consumers must stop their owned work. */
    readonly abortSignal: AbortSignal;
    /** Updates and persists the instance description. */
    update: (changes: DevInstanceUpdate) => Promise<void>;
    /** Appends one entry to the JSON Lines log. */
    log: (entry: Omit<DevInstanceLogEntry, 'timestamp'>) => Promise<void>;
    /**
     * Wraps a stream so every line written to it is also appended to the log, without ANSI styling.
     * The returned stream forwards the original bytes to `target` unchanged.
     */
    tee: (target: Writable, options: {
        source: string;
        stream: 'stdout' | 'stderr';
    }) => Writable;
    /** Closes the log, removes the instance description and releases the lock. Safe to call more than once. */
    release: () => Promise<void>;
}
/**
 * Returns the files used by a dev instance. Every instance of a project shares `.shopify/dev`,
 * with one `<slug>.json`, `<slug>.lock` and `<slug>.jsonl` per command and key.
 *
 * @param identity - The command, directory and optional key of the instance.
 * @returns The paths of the instance files.
 */
export declare function devInstancePaths(identity: DevInstanceIdentity): DevInstancePaths;
/**
 * Marks this process as the running instance of a long-running command for a project.
 *
 * Mutual exclusion uses `proper-lockfile`: an atomic `mkdir` lock whose mtime this process refreshes as a heartbeat.
 * An exclusive startup directory serializes abandoned-lock recovery. An interrupted startup requires explicit
 * cleanup of that directory. A live owner blocks takeover, including when its heartbeat is stale.
 *
 * @param options - The instance identity, initial details.
 * @returns The acquired instance.
 * @throws AbortError with code {@link DEV_INSTANCE_ALREADY_RUNNING_CODE} when another live instance holds the lock.
 */
export declare function acquireDevInstance(options: AcquireDevInstanceOptions): Promise<DevInstance>;
/**
 * Returns the running instance of a command for a project, if there is one.
 *
 * @param identity - The command, directory and optional key of the instance.
 * @returns The instance description, or undefined when no live instance holds the lock.
 */
export declare function readDevInstance(identity: DevInstanceIdentity): Promise<DevInstanceInfo | undefined>;
/**
 * Lists every running dev instance of a project, across commands and keys.
 *
 * @param directory - The project directory.
 * @returns The descriptions of the live instances.
 */
export declare function listDevInstances(directory: string): Promise<DevInstanceInfo[]>;
/**
 * Checks whether a process exists. A process owned by another user counts as alive.
 *
 * @param pid - The process ID.
 * @returns True when the process exists.
 */
export declare function isProcessAlive(pid: number): boolean;