@doriandev/devcc 0.1.2

package/dist/devcc/processes/ManagedProcess.js

@@ -0,0 +1,80 @@
+/**
+ * Types and pure helpers describing a process Dev Command Center knows about.
+ *
+ * `ownership` is the safety boundary: `"managed"` processes were launched by us
+ * and may be signalled; `"detected"` processes were merely observed on the host
+ * and must never be killed by devcc.
+ */
+export const DEFAULT_READINESS = {
+    timeoutMs: 30_000,
+    intervalMs: 250,
+};
+export const DEFAULT_CRASH_POLICY = {
+    maxCrashRestarts: 5,
+    crashBackoffMs: 1_000,
+    maxCrashBackoffMs: 30_000,
+    healthyAfterMs: 30_000,
+};
+export const ACTIVE_STATUSES = ["starting", "running", "stopping"];
+export function isActive(status) {
+    return ACTIVE_STATUSES.includes(status);
+}
+const TRANSITIONS = {
+    stopped: ["starting"],
+    starting: ["running", "failed", "stopping", "stopped"],
+    running: ["stopping", "stopped", "failed"],
+    stopping: ["stopped", "failed"],
+    failed: ["starting"],
+};
+/** Whether a status change is legal. Keeps the manager's bookkeeping honest. */
+export function canTransition(from, to) {
+    if (from === to)
+        return false;
+    return TRANSITIONS[from].includes(to);
+}
+/** Build the initial snapshot for a definition. */
+export function createManagedProcess(definition, ownership = "managed") {
+    return {
+        id: definition.id,
+        name: definition.name,
+        command: definition.command,
+        args: definition.args ? [...definition.args] : undefined,
+        cwd: definition.cwd,
+        status: "stopped",
+        kind: definition.kind ?? "service",
+        ownership,
+        url: definition.url,
+        port: definition.port,
+        restarts: 0,
+        crashRestarts: 0,
+        dependsOn: definition.dependsOn ? [...definition.dependsOn] : [],
+        ready: false,
+    };
+}
+/**
+ * Exponential backoff for automatic restarts.
+ *
+ * `attempt` is 1-based: the first restart waits `base`, the second `2 * base`,
+ * and so on, capped at `max`. Keeping this a pure function makes the policy
+ * testable without spawning anything.
+ */
+export function crashBackoffDelay(attempt, base = DEFAULT_CRASH_POLICY.crashBackoffMs, max = DEFAULT_CRASH_POLICY.maxCrashBackoffMs) {
+    if (attempt <= 0)
+        return 0;
+    const safeBase = Math.max(0, base);
+    const exponent = Math.min(attempt - 1, 30);
+    return Math.min(Math.max(0, max), safeBase * 2 ** exponent);
+}
+/** Whether a crashed process should be brought back up automatically. */
+export function shouldAutoRestart(definition, snapshot) {
+    if (!definition.restartOnCrash)
+        return false;
+    const limit = definition.maxCrashRestarts ?? DEFAULT_CRASH_POLICY.maxCrashRestarts;
+    return snapshot.crashRestarts < limit;
+}
+/** Human-readable one-liner of what will actually be executed. */
+export function describeCommand(process) {
+    const args = process.args ?? [];
+    return args.length > 0 ? `${process.command} ${args.join(" ")}` : process.command;
+}
+//# sourceMappingURL=ManagedProcess.js.map

package/dist/devcc/processes/ManagedProcess.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ManagedProcess.js","sourceRoot":"","sources":["../../../src/devcc/processes/ManagedProcess.ts"],"names":[],"mappings":"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"}

package/dist/devcc/processes/ProcessManager.d.ts

@@ -0,0 +1,112 @@
+import { TypedEmitter } from "../core/events.js";
+import type { LogStore } from "../logs/LogBuffer.js";
+import { DevccError } from "../utils/errors.js";
+import type { ScopedLogger } from "../utils/logger.js";
+import { type StartPlan } from "./graph.js";
+import { type ManagedProcess, type ProcessDefinition } from "./ManagedProcess.js";
+export declare const DEFAULT_KILL_GRACE_MS = 5000;
+export type ProcessManagerEvents = {
+    /** Any change to a process snapshot (status, pid, exit code, ...). */
+    "process:changed": [ManagedProcess];
+    /** The set of known processes changed (added or removed). */
+    "process:list": [ManagedProcess[]];
+    "process:started": [ManagedProcess];
+    "process:exit": [ManagedProcess];
+    /** An automatic restart was scheduled after a crash. */
+    "process:retry": [ManagedProcess, number];
+    /** The readiness check passed (or timed out and was reported anyway). */
+    "process:ready": [ManagedProcess];
+    "process:error": [DevccError];
+};
+export interface ProcessManagerOptions {
+    logs: LogStore;
+    logger: ScopedLogger;
+    /** Default cwd for definitions that don't specify one. */
+    rootDir: string;
+    env?: NodeJS.ProcessEnv;
+}
+/**
+ * Owns every child process devcc launches.
+ *
+ * Design notes:
+ * - Commands are always `spawn(executable, args[])`; nothing is ever passed to a
+ *   shell, so arguments containing spaces or quotes are safe by construction.
+ * - Children are spawned `detached`, which makes each one a process-group leader.
+ *   Stopping signals the whole group (`kill(-pgid)`) so dev servers that fork
+ *   workers do not leave orphans behind.
+ * - Stopping escalates SIGTERM -> SIGKILL after a grace period.
+ */
+export declare class ProcessManager extends TypedEmitter<ProcessManagerEvents> {
+    private readonly definitions;
+    private readonly snapshots;
+    private readonly runtimes;
+    /** Pending automatic-restart timers, keyed by process id. */
+    private readonly retryTimers;
+    /** In-flight readiness checks, so a stop can cancel the probe loop. */
+    private readonly readiness;
+    private readonly logs;
+    private readonly logger;
+    private readonly rootDir;
+    private readonly baseEnv;
+    private disposed;
+    constructor(options: ProcessManagerOptions);
+    /** Register (or replace, while stopped) a process definition. */
+    register(definition: ProcessDefinition): ManagedProcess;
+    registerAll(definitions: readonly ProcessDefinition[]): void;
+    /** Remove a stopped process. Refuses while it is still running. */
+    unregister(id: string): void;
+    list(): ManagedProcess[];
+    get(id: string): ManagedProcess | undefined;
+    getDefinition(id: string): ProcessDefinition | undefined;
+    isRunning(id: string): boolean;
+    /**
+     * Start a process.
+     *
+     * A start the user asked for clears the crash budget; the automatic restart
+     * path passes `auto` so a crash loop cannot refill its own budget.
+     */
+    start(id: string, options?: {
+        auto?: boolean;
+    }): Promise<ManagedProcess>;
+    /**
+     * Resolve once the process is ready (readiness passed or timed out), or
+     * immediately if it is not starting. Used to sequence dependent starts.
+     */
+    waitForReady(id: string): Promise<ManagedProcess | undefined>;
+    /**
+     * Start several processes honouring `dependsOn`: each wave waits for the
+     * previous one to become ready. Failures in one wave are reported and the
+     * next wave still starts, since an unrelated process should not be blocked.
+     */
+    startAll(ids?: readonly string[]): Promise<StartPlan>;
+    private beginReadinessCheck;
+    private cancelReadiness;
+    private isActiveRuntime;
+    private markReady;
+    /**
+     * Stop a managed process and everything it spawned.
+     * Resolves once the child has actually exited (or the grace period elapsed).
+     */
+    stop(id: string, graceMs?: number): Promise<void>;
+    restart(id: string): Promise<ManagedProcess>;
+    /** Start every definition marked `autoStart`. Failures are reported, not thrown. */
+    startAutoStart(): Promise<void>;
+    /**
+     * Stop everything devcc launched. Called on shutdown; never touches processes
+     * that were only detected.
+     */
+    stopAll(graceMs?: number): Promise<void>;
+    private handleExit;
+    /**
+     * Schedule an automatic restart for a crashed process, if its definition opted
+     * in and it still has budget left. Backoff doubles per consecutive crash, so a
+     * process that is broken rather than flaky stops thrashing quickly.
+     */
+    private considerAutoRestart;
+    private cancelRetry;
+    private finishRuntime;
+    /** Signal the child's process group when we have one, else the child alone. */
+    private signal;
+    private update;
+}
+//# sourceMappingURL=ProcessManager.d.ts.map

package/dist/devcc/processes/ProcessManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ProcessManager.d.ts","sourceRoot":"","sources":["../../../src/devcc/processes/ProcessManager.ts"],"names":[],"mappings":"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"}