@zenera/cli 1.1.25 → 1.1.26

package/dist/resources.d.ts

@@ -0,0 +1,215 @@
+import { runProcess } from '@zenera/neo';
+import { type OwnedContainer } from './podman.ts';
+type Exec = typeof runProcess;
+export interface HostProcess {
+    pid: number;
+    /** `vm` holds the machine's memory; the others run beside it */
+    role: 'vm' | 'hypervisor' | 'network';
+    name: string;
+    /** in RAM this moment */
+    rss: number;
+    /** macOS: what Activity Monitor's Memory column shows — RAM, compressed and swapped */
+    footprint?: number;
+    peak?: number;
+    /** cumulative, since it started */
+    cpuSeconds: number;
+}
+export interface GuestMemory {
+    total: number;
+    free: number;
+    available: number;
+    swapTotal: number;
+    swapFree: number;
+    cpus: number;
+}
+export interface ContainerStat {
+    id: string;
+    name: string;
+    cpuNano: number;
+    /** wall clock of the reading, in nanoseconds */
+    systemNano: number;
+    /** percent of one core, averaged over the container's whole life */
+    avgCpu: number;
+    memory: number;
+    limit: number;
+    pids: number;
+    netIn: number;
+    netOut: number;
+    blockIn: number;
+    blockOut: number;
+}
+export interface Sample {
+    at: number;
+    platform: NodeJS.Platform;
+    engine: string;
+    ready: boolean;
+    machine?: string;
+    host: {
+        memory: number;
+        cpus: number;
+        processes: HostProcess[];
+    };
+    guest?: GuestMemory;
+    stats: ContainerStat[];
+    owned: OwnedContainer[];
+    /** running containers whose zen run is gone */
+    orphans: string[];
+    /** session id -> project name */
+    projects: ReadonlyMap<string, string>;
+    problems: string[];
+}
+export interface ProcessView {
+    pid: number;
+    role: HostProcess['role'];
+    name: string;
+    /** the footprint where there is one, else what is in RAM */
+    memory: number;
+    rss: number;
+    footprint?: number;
+    peak?: number;
+    /** percent of one core over the interval; absent on the first sample */
+    cpu?: number;
+}
+export interface MachineView {
+    name?: string;
+    total: number;
+    /** held by programs: total minus available */
+    used: number;
+    /** page cache and other memory Linux gives back on demand */
+    cache: number;
+    free: number;
+    available: number;
+    swapTotal: number;
+    swapUsed: number;
+    cpus: number;
+    /**
+     * macOS counts this much for the machine beyond what anything inside uses,
+     * cache included: memory used once, freed inside, and never handed back.
+     */
+    held?: number;
+}
+export interface ContainerView {
+    name: string;
+    id: string;
+    kind: 'zen' | 'faker' | 'other';
+    project?: string;
+    orphaned: boolean;
+    /** percent of one core */
+    cpu: number;
+    /** whether `cpu` is over the last interval or the container's whole life */
+    cpuOver: 'interval' | 'lifetime';
+    memory: number;
+    /** absent when the container may use the whole machine */
+    limit?: number;
+    pids: number;
+    netIn: number;
+    netOut: number;
+    blockIn: number;
+    blockOut: number;
+    createdAt?: string;
+}
+export interface ResourceView {
+    at: string;
+    /** seconds between the two samples the cpu figures are taken over */
+    interval?: number;
+    platform: NodeJS.Platform;
+    engine: string;
+    ready: boolean;
+    host: {
+        memory: number;
+        cpus: number;
+        vm?: ProcessView;
+        helpers: ProcessView[];
+    };
+    machine?: MachineView;
+    containers: ContainerView[];
+    /** containers that exist but are not running, which cost disk and no memory */
+    stopped: number;
+    totals: {
+        running: number;
+        zen: number;
+        faker: number;
+        other: number;
+        orphaned: number;
+        memory: number;
+        cpu: number;
+    };
+    hints: string[];
+    problems: string[];
+}
+export interface SamplerOptions {
+    engine?: string;
+    exec?: Exec;
+    /** so the tests can be macOS on Linux and the other way round */
+    platform?: NodeJS.Platform;
+    /** session id -> {dir, project}; read from the registry when absent */
+    owners?: () => Promise<Owners>;
+    now?: () => number;
+}
+export interface Owners {
+    dirs: ReadonlyMap<string, string>;
+    names: ReadonlyMap<string, string>;
+}
+/** Reads one sample at a time and remembers the last, so each view has an interval. */
+export declare class ResourceSampler {
+    #private;
+    readonly engine: string;
+    constructor(opts?: SamplerOptions);
+    next(): Promise<ResourceView>;
+    sample(): Promise<Sample>;
+}
+/** Every session on this machine, by id: where it lives and which project it is in. */
+export declare function registryOwners(): Promise<Owners>;
+export declare function parseInfo(stdout: string): GuestMemory | undefined;
+export declare function parseStats(stdout: string): ContainerStat[];
+interface PsRow {
+    pid: number;
+    rss: number;
+    cpuSeconds: number;
+    ageSeconds: number;
+    command: string;
+}
+export declare function parsePs(stdout: string): PsRow[];
+/** `[[dd-]hh:]mm:ss[.cc]` — how `ps` prints both cpu time and elapsed time. */
+export declare function clock(text: string): number;
+/**
+ * Picks the machine out of every process on the host. A Mac can run more than
+ * one virtual machine through the same framework, so the Apple service and
+ * the network helper are matched to the hypervisor by when they started.
+ */
+export declare function machineProcesses(rows: readonly PsRow[]): HostProcess[];
+/** `footprint -f bytes` output: one block per process. */
+export declare function parseFootprint(stdout: string): Map<number, {
+    footprint: number;
+    peak?: number;
+}>;
+export declare function viewOf(now: Sample, before?: Sample): ResourceView;
+export type Tone = 'plain' | 'strong' | 'dim' | 'good' | 'warn' | 'bad' | 'accent' | 'heading';
+export interface Span {
+    readonly text: string;
+    readonly tone?: Tone;
+}
+export type Line = readonly Span[];
+export type Sort = 'memory' | 'cpu' | 'name';
+export declare const SORTS: readonly Sort[];
+export interface LayoutOptions {
+    width: number;
+    /** the most lines to return; containers are cut first, with a count of the rest */
+    rows?: number;
+    /** a note beside every figure saying what it means, and a sentence under each heading */
+    explain: boolean;
+    sort?: Sort;
+    /** seconds between refreshes, for the live screen's header */
+    live?: number;
+    /** wrap a long note onto the next line instead of letting the edge cut it */
+    wrapNotes?: boolean;
+    /**
+     * The sentence under each heading and the column legend. On by default
+     * with `explain`; the live screen turns it off before it cuts any figure.
+     */
+    intros?: boolean;
+}
+export declare function pct(n: number): string;
+export declare function layout(view: ResourceView, o: LayoutOptions): Line[];
+export {};
+//# sourceMappingURL=resources.d.ts.map