@microtronics/studio-cli 1.2.0-alpha.2 → 1.2.0-alpha.4

package/dist/studio-cli.d.ts

@@ -1,9 +1,19 @@
+import { AtCommandHandler } from '@microtronics/device-master';
+import { DdeModel } from '@microtronics/device-master';
+import { DdeRecord } from '@microtronics/device-master';
 import { Document as Document_2 } from 'yaml';
+import { EventEmitter } from 'node:events';
+import { ITimeSource } from '@microtronics/device-master';
+import { ITransport } from '@microtronics/device-master';
 import { LineCounter } from 'yaml';
+import { LocalApiRequest } from '@microtronics/device-master';
+import { LocalApiResponse } from '@microtronics/device-master';
+import { MemoryStorage } from '@microtronics/device-master';
 import { ParsedNode } from 'yaml';
 import { Range as Range_2 } from 'yaml';
 import { SemVer } from 'semver';
 import { URI } from 'vscode-uri';
+import { UtoMaster } from '@microtronics/device-master';
 
 export declare namespace APM {
     export enum TagPhase {
@@ -395,6 +405,18 @@ declare interface components {
     pathItems: never;
 }
 
+/** One tag whose device stamp overtook the mirror and was therefore pulled. */
+export declare interface ContainerChange {
+    tag: number;
+    /** DDE container name, when the tag maps to one. */
+    container: string | null;
+    alias?: string;
+    /** Device stamp40 the mirror now holds. */
+    stamp: number;
+    /** Decoded record, for tags that map to a DDE container. */
+    decoded?: DdeRecord | null;
+}
+
 declare const createPawnCC: PawnModuleFactory;
 
 declare const createPawnDbg: PawnModuleFactory;
@@ -1776,6 +1798,8 @@ export declare namespace DefaultFiles {
         legacyAutoUplinkInc: string;
         reportTemplate: string;
         dloCfg: string;
+        devMirror: string;
+        devDeviceLog: string;
     };
     export const filePaths: {
         studio: {
@@ -1801,6 +1825,11 @@ export declare namespace DefaultFiles {
                 };
             };
             libdeps: string;
+            dev: {
+                path: string;
+                mirror: string;
+                deviceLog: string;
+            };
         };
         dist: {
             path: string;
@@ -2037,6 +2066,23 @@ export declare namespace Dependencies {
     export function unlinkLibraryApmParts(cwd: URI, fs: LocalFS, logger: Log.Logger, libraryName: string): Promise<void>;
 }
 
+/**
+ * Start a `studio dev` session and its local HTTP server.
+ *
+ * Build → connect USB → flash → parse `dist/dde/dde.xml` → serve the myDatanet-compatible
+ * `/api/**` surface plus `/dev/**` and `/events` on localhost.
+ */
+export declare function dev(cwd: URI, fs: LocalFS, options: DevOptions): Promise<DevResult>;
+
+/** Diagnostics of the last `build()`, as served by `/dev/status` and `/dev/build`. */
+export declare interface DevBuildState {
+    running: boolean;
+    ok: boolean | null;
+    at: number | null;
+    message?: string;
+    diagnostics?: Package.MergedDiagnostics;
+}
+
 /**
  * Development installation information
  */
@@ -2054,8 +2100,266 @@ export declare interface DevelopmentInstallInfo {
     registrationCodeNeeded?: boolean;
 }
 
+/** An error carrying the process exit code the CLI should terminate with. */
+export declare class DevError extends Error {
+    readonly exitCode: DevExitCode;
+    constructor(message: string, exitCode: DevExitCode);
+}
+
+/**
+ * Exit codes for `studio dev` / `studio device`. 0–3 mirror
+ * {@link import('../myDatanetClient').RunExitCode}; 7–9 are dev-mode specific.
+ */
+export declare enum DevExitCode {
+    Success = 0,
+    BuildFailed = 1,
+    DeviceNotFound = 2,
+    UsbFailed = 3,
+    ModelMissing = 7,
+    UnknownContainer = 8,
+    WriteForbidden = 9
+}
+
 export declare const DeviceProfiles: any;
 
+/**
+ * The pair of transports (UTO data + AT debug) needed to talk to a connected device,
+ * plus a way to release the underlying link.
+ */
+declare interface DeviceTransports {
+    uto: ITransport;
+    /** Absent when the caller asked for the UTO interface only (`needDebug: false`). */
+    debug?: ITransport;
+    close(): Promise<void>;
+}
+
+/** One ring-buffer record, as served by `GET /dev/logs` and the SSE `log` event. */
+export declare interface DevLogRecord {
+    /** Monotonic sequence number; `GET /dev/logs?since=<seq>` returns everything after it. */
+    seq: number;
+    /** Wall-clock ms. */
+    ts: number;
+    source: DevLogSource;
+    text: string;
+    /** Base64 payload, only for records whose bytes could not be decoded to text. */
+    raw?: string;
+}
+
+/** Where a log record came from. */
+export declare type DevLogSource = 'rm2mlog' | 'at' | 'uto' | 'pov';
+
+export declare interface DevOptions {
+    serial: string;
+    host?: string;
+    port?: number;
+    /** Allow a non-loopback `host` without a bearer token. */
+    allowRemote?: boolean;
+    /** Rebuild, flash and sync on source changes. */
+    watch?: boolean;
+    /** Build before connecting (default `true`). */
+    build?: boolean;
+    /** Flash `dist/dlo/main.amx` after connecting (default `true`). */
+    flash?: boolean;
+    pollIntervalMs?: number;
+    /** How long a write waits for the device to confirm, in ms. */
+    waitMs?: number;
+    logFile?: string;
+    /** Bearer token required by the server; absent ⇒ `Authorization` is ignored. */
+    token?: string;
+    part?: APM.Part[];
+    debug?: boolean;
+    env?: Globals.ENV;
+    apiToken?: string | null;
+    logger?: Log.Logger;
+    /** Spawn `npm run dev -w pov/<name>` with `MYDATANET_HOST` pointing at this server. */
+    pov?: string | boolean;
+    /** Persist the mirror to `.studio/dev/mirror.json` (default `true`). */
+    persistMirror?: boolean;
+    /** Test/replay seams, forwarded to {@link DevSession}. */
+    transportFactory?: TransportFactory;
+    createDevice?: DevSessionOptions['createDevice'];
+}
+
+export declare interface DevResult {
+    url: string;
+    port: number;
+    session: DevSession;
+    apmId: string;
+    close(): Promise<void>;
+}
+
+export declare interface DevServer {
+    url: string;
+    port: number;
+    close(): Promise<void>;
+}
+
+/**
+ * One `studio dev` session: owns the USB link, the project's DDE model, the `IStorage`
+ * mirror and the myDatanet-compatible API handler, and fans device activity out as events.
+ *
+ * Events: `log` ({@link DevLogRecord}), `state`, `sync`, `build`, `uto`,
+ * `container-changed` ({@link ContainerChange}), `error`.
+ */
+export declare class DevSession extends EventEmitter {
+    readonly logStream: LogStream;
+    private readonly opts;
+    private readonly logger;
+    private readonly timeSource;
+    private device;
+    private mirror;
+    private model;
+    private mapper;
+    private apiHandler;
+    private poller;
+    private stateManager;
+    private localData;
+    private offlineSync;
+    private buildState;
+    private lastSyncAt;
+    private firmwareVersion;
+    private mirrorSaveTimer;
+    private stopped;
+    private readonly lock;
+    constructor(options: DevSessionOptions);
+    get serial(): string;
+    get connected(): boolean;
+    /**
+     * Read by {@link StampPoller}: true while a flash, sync, write or AT command owns the
+     * UTO link, so a poll tick cannot interleave with a multi-frame transfer.
+     */
+    get busy(): boolean;
+    /** The parsed project DDE. */
+    get ddeModel(): DdeModel;
+    get storage(): MemoryStorage;
+    /**
+     * Build (optional) → load the model → connect USB → flash (optional) → start the stamp
+     * poller. Rejects with a {@link DevError} whose `exitCode` the CLI exits with.
+     */
+    start(): Promise<void>;
+    /** Read and parse `dist/dde/dde.xml`. Missing → {@link DevExitCode.ModelMissing}. */
+    private loadModel;
+    private connect;
+    private startPoller;
+    private tagLabel;
+    private get utoMaster();
+    private get atHandler();
+    /** Assemble the {@link LocalApiContext} and bind the router to it. */
+    private buildApiHandler;
+    /**
+     * Serve one `/api/**` request. A successful write additionally triggers an immediate
+     * poll tick and waits (bounded by `waitMs`) until the device's own stamp for the
+     * written tag has reached the pushed stamp — proof the device accepted the frame.
+     * When it does not, `x-mt-mirror: stale` is added; `?async=1` skips the wait entirely.
+     */
+    handleApi(req: LocalApiRequest): Promise<LocalApiResponse>;
+    /**
+     * The `uto_data` tag a request writes, or `null` for a read / an `?async=1` write /
+     * a path whose container cannot be resolved.
+     */
+    private writtenTag;
+    /**
+     * Poll until the device reports a stamp ≥ `pushedStamp` for `tag`, or the wait budget
+     * runs out. Returns `false` on timeout.
+     */
+    private awaitDeviceStamp;
+    /** Run the project build; records diagnostics in {@link DevBuildState}. */
+    build(): Promise<DevBuildState>;
+    /**
+     * Upload an AMX to the device (defaults to `dist/dlo/main.amx`).
+     *
+     * `uploadToDevice` owns its own connection, and a USB device is single-owner, so the
+     * session's link is released for the duration and reopened afterwards. The tag table
+     * can change with a new app, so DEVINFO is re-read before the poller resumes.
+     */
+    flash(file?: string): Promise<UploadResult>;
+    /**
+     * Reopen the USB link after a flash. The device is rebooting — and some devices don't even
+     * drop the USB connection — so a failure here is expected and retried for a while rather
+     * than reported immediately; a final failure is logged and leaves `connected: false`.
+     */
+    private reconnect;
+    private reportReconnectFailure;
+    /** Full `OfflineSyncManager` sync, or a targeted pull of the given tags. */
+    sync(tags?: number[]): Promise<{
+        tags: number[];
+        at: number;
+    }>;
+    /** One AT command; queued behind a flash, which closes the AT handler's transport. */
+    at(cmd: string): Promise<string>;
+    /** Last known rm2m state; fetches one when nothing has been read yet. */
+    state(): Promise<unknown>;
+    /** Live local-data values. */
+    localDataSnapshot(): unknown;
+    /** Trigger a measurement and return its outcome plus the fresh values. */
+    measure(): Promise<unknown>;
+    status(): DevStatus;
+    /** Force one poll pass (used by the watcher and by `POST /dev/sync`). */
+    tick(): Promise<ContainerChange[]>;
+    /** The mirror's current stamp40 for a tag, or 0. */
+    mirrorStamp(tag: number): Promise<number>;
+    /** Run `fn` as the sole owner of the UTO link (see {@link UtoLock}). */
+    private withLink;
+    private closeDevice;
+    stop(): Promise<void>;
+}
+
+export declare interface DevSessionOptions {
+    cwd: URI;
+    fs: LocalFS;
+    /** 16-character hex device serial. */
+    serial: string;
+    /** Overrides how the USB transports are obtained (tests, later `--replay`). */
+    transportFactory?: TransportFactory;
+    /**
+     * Test seam: supply the connected device (UtoMaster + AtCommandHandler) instead of
+     * opening USB. The unit tests use it because `UtoMaster.init()` needs the real WASM
+     * UTO wire protocol, which a byte-level mock cannot produce.
+     */
+    createDevice?: (serial: string) => Promise<OpenDevice>;
+    /** Stamp-poll interval in ms; `0` disables polling. */
+    pollIntervalMs?: number;
+    /** Flash `dist/dlo/main.amx` to the device on start. */
+    flash: boolean;
+    /** Build the project on start. */
+    build: boolean;
+    part?: APM.Part[];
+    logger: Log.Logger;
+    timeSource?: ITimeSource;
+    env?: Globals.ENV;
+    apiToken?: string | null;
+    /** How long a write waits for the device to confirm, in ms. `0` disables the wait. */
+    waitMs?: number;
+    /** JSONL log file for every {@link DevLogRecord}. */
+    logFile?: string;
+    /** Persist the mirror to `.studio/dev/mirror.json`. */
+    persistMirror?: boolean;
+    debug?: boolean;
+    /** Test seam: replaces the AMX upload {@link flash} performs. */
+    uploadToDevice?: typeof uploadToDevice;
+    /** How long UTO work waits for the link while a flash owns it, in ms. */
+    lockWaitMs?: number;
+}
+
+/** `GET /dev/status` payload. */
+export declare interface DevStatus {
+    serial: string;
+    connected: boolean;
+    apmId: string;
+    firmwareVersion: string | null;
+    model: {
+        containers: Array<{
+            name: string;
+            alias?: string;
+            kind: string;
+            tag: number | null;
+        }>;
+    };
+    lastSync: number | null;
+    buildState: DevBuildState;
+    poll: StampPollerStatus;
+}
+
 export declare namespace DFILES {
     export enum Type {
         static = "static",
@@ -2598,7 +2902,8 @@ export declare namespace Log {
         done = 1,
         info = 2,
         warning = 3,
-        error = 4
+        error = 4,
+        debug = 5
     }
     export const LOG_PREFIX: {
         1: string;
@@ -2606,17 +2911,25 @@ export declare namespace Log {
         2: string;
         3: string;
         4: string;
+        5: string;
     };
     export class Logger {
         private _logHandler;
         private _silent;
+        private _debugEnabled;
         constructor(logOutput?: {
             log: (...args: any[]) => void;
         });
         _log(type: LogMessageType, msg: any, ...args: any[]): void;
         set silent(value: boolean);
+        /** Redirect where log lines go (e.g. stderr while stdout carries machine-readable output). */
+        set output(logOutput: {
+            log: (...args: any[]) => void;
+        });
         log(msg: any, ...args: any[]): void;
+        /** Only prints when {@link debugEnabled} is set (the `--debug` flag). */
         debug(msg: any, ...args: any[]): void;
+        set debugEnabled(value: boolean);
         error(msg: any, ...args: any[]): void;
         info(msg: any, ...args: any[]): void;
         warn(msg: any, ...args: any[]): void;
@@ -2624,6 +2937,58 @@ export declare namespace Log {
     }
 }
 
+/**
+ * Ring buffer of device log records with SSE fan-out.
+ *
+ * Fed by two taps:
+ * - `UtoMaster`'s `'utoFrame'` event, filtered to {@link UtoTag.LOG} (rm2mlog).
+ * - `AtCommandHandler`'s `'data'` event, which the handler emits for every decoded
+ *   chunk of debug-channel RX (its documented "raw monitoring" hook) — this is where
+ *   a DLO's live `printf` output arrives.
+ *
+ * The LOG payload layout is not modelled: the record's leading bytes are decoded
+ * best-effort (cp1252, then UTF-8) and cut at the first NUL. A payload that does not
+ * decode to text is stored as base64 in {@link DevLogRecord.raw} with a hex preview as
+ * its `text`, so nothing is silently dropped.
+ */
+declare class LogStream extends EventEmitter {
+    private readonly buffer;
+    private readonly capacity;
+    private readonly logFile;
+    private readonly logger;
+    private seq;
+    private disposers;
+    /** Serialises the JSONL appends so records cannot interleave mid-line. */
+    private writeChain;
+    /** `mkdir -p` of the log file's directory, done once instead of per record. */
+    private logDirReady;
+    constructor(opts?: {
+        capacity?: number;
+        logFile?: string;
+        logger?: Log.Logger;
+    });
+    /** Append a record, evict the oldest when full, emit `record` and mirror to `--log-file`. */
+    push(source: DevLogSource, text: string, raw?: Uint8Array): DevLogRecord;
+    private appendToFile;
+    /** Records after `since`, newest last, at most `limit` (`<= 0` ⇒ the default limit). */
+    since(since?: number, limit?: number): DevLogRecord[];
+    /** The highest sequence number handed out so far. */
+    get lastSeq(): number;
+    /** Tap rm2mlog frames off the UTO channel. */
+    attachUtoMaster(utoMaster: UtoMaster): void;
+    /**
+     * Tap the AT/debug channel RX, where a DLO's live `printf` output arrives.
+     *
+     * A `DebugMaster` parses the raw byte stream (console frames, the `!`/`?`/`~`/`$`
+     * level prefixes and the DLO file/line tags) instead of dumping unformatted chunks.
+     */
+    attachAtHandler(atHandler: AtCommandHandler): void;
+    /** Decode a device payload best-effort; keep the bytes when it is not text. */
+    private pushDecoded;
+    /** Detach the taps and await the pending JSONL appends, so no record is lost. */
+    dispose(): Promise<void>;
+}
+
 export declare namespace Manifest {
     /**
      * The source filename where the information is stored in
@@ -2928,6 +3293,20 @@ export declare interface MyDatanetUserInfo {
     customers?: MyDatanetCustomer[];
 }
 
+/**
+ * A connected device: the UTO/AT primitives plus the raw transports, ready to use.
+ * Call `close()` exactly once when done to dispose the AtCommandHandler/UtoMaster and
+ * release the underlying transports.
+ */
+declare interface OpenDevice {
+    utoMaster: UtoMaster;
+    /** Only present when the debug interface was claimed (`needDebug`, the default). */
+    atHandler?: AtCommandHandler;
+    transports: DeviceTransports;
+    serial: string;
+    close(): Promise<void>;
+}
+
 /**
  * Packs the given directory into a deployable package using the specified configuration.
  *
@@ -5335,6 +5714,42 @@ export declare namespace Registry {
     } | {};
 }
 
+/** `GET /dev/status`'s `poll` section. */
+export declare interface StampPollerStatus {
+    intervalMs: number;
+    lastTick: number | null;
+    lastChange: number | null;
+    errors: number;
+    paused: boolean;
+}
+
+/**
+ * Opens the transports for a device given its serial number. The default (WebUSB) factory
+ * is used by {@link openDevice} unless a test/consumer supplies its own.
+ */
+declare type TransportFactory = (serial: string, needDebug?: boolean) => Promise<DeviceTransports>;
+
+/**
+ * Upload result interface
+ */
+declare interface UploadResult {
+    success: boolean;
+    message: string;
+}
+
+/**
+ * Upload an AMX binary file to a USB device
+ * @param serialNumber - The serial number of the target device
+ * @param fileUri - The URI to the AMX file
+ * @param fs - The filesystem interface for file operations
+ * @param logger - The logger instance for output
+ * @param debugLog - Enable debug logging
+ * @param retryMs - Total ms budget to retry a transient device-open failure (see
+ *   {@link isTransientUsbOpenError}); `0` (the default) attempts once.
+ * @returns Promise resolving to an UploadResult
+ */
+declare function uploadToDevice(serialNumber: string, fileUri: URI, fs: LocalFS, logger: Log.Logger, debugLog?: boolean, retryMs?: number): Promise<UploadResult>;
+
 declare function uriToMemFsPath(path: URI): string;
 
 declare interface XMLField {