@slock-ai/computer 0.0.13-alpha.0 → 0.0.14

package/dist/lib/index.d.ts

@@ -0,0 +1,250 @@
+/**
+ * IPC error code family — the seed that `ServiceClient.request` and
+ * `ServiceClient.events` propagate. Forward-only post v9-sign: additions
+ * are additive minor library bumps; renames / removals are major.
+ *
+ * Full §7.3 enumeration (SETUP/ATTACH/MIGRATE/UPGRADE/SERVICE families)
+ * lands in a follow-up reconcile commit that also unifies the codes
+ * currently emitted via `ComputerServiceError` across services/*.
+ */
+declare const IPC_ERROR_CODES: readonly ["IPC_FRAME_TOO_LARGE", "IPC_PROTOCOL_VERSION_UNSUPPORTED", "IPC_HEARTBEAT_TIMEOUT", "IPC_MALFORMED_FRAME", "IPC_REQUEST_TIMEOUT", "IPC_REQUEST_CANCELED", "IPC_CLIENT_CLOSED"];
+type IpcErrorCode = (typeof IPC_ERROR_CODES)[number];
+/**
+ * Runtime narrow guard — exposed so consumers can pattern-match without
+ * pulling in a generic `as` cast. The CI gate (§7.4) over a final
+ * `ERROR_CODES` union will subsume this once the reconcile lands.
+ */
+declare function isIpcErrorCode(value: unknown): value is IpcErrorCode;
+/**
+ * Caller-facing options for `ServiceClient.request`. Pairs active cancel
+ * (`signal` — primary G-stage unmount path) with passive deadline
+ * (`timeoutMs` — library-side safety net). On either path the client
+ * emits an IPC `cancel` frame for the in-flight request id and rejects
+ * the returned promise with `IPC_REQUEST_CANCELED` or
+ * `IPC_REQUEST_TIMEOUT` respectively (§4.4).
+ */
+interface RequestOptions {
+    signal?: AbortSignal;
+    timeoutMs?: number;
+}
+/**
+ * Typed RPC table — keys are kebab-case wire literals (§5.5), values are
+ * per-method `{ params, result }` pairs. The v9 sign-lock seed listed
+ * here is the §3.2 6-method floor; new methods are additive minor bumps
+ * (extending this map). Param/result payload shapes are intentionally
+ * `unknown` in this seed — they are pinned in the follow-up commit that
+ * lands the state-reader surface (`readServiceStatus` / `readRunnerStatus`
+ * / `listRunners`) alongside the IPC handler signatures.
+ */
+interface RequestMethodMap {
+    "service-status": {
+        params: void;
+        result: unknown;
+    };
+    "runner-status": {
+        params: {
+            serverId: string;
+        };
+        result: unknown;
+    };
+    "list-runners": {
+        params: void;
+        result: unknown;
+    };
+    "upgrade-start": {
+        params: {
+            target?: string;
+        };
+        result: unknown;
+    };
+    "reset-service": {
+        params: void;
+        result: unknown;
+    };
+    "reset-runner": {
+        params: {
+            serverId: string;
+        };
+        result: unknown;
+    };
+}
+/**
+ * Server-pushed event over `ServiceClient.events`. The discriminant field
+ * is `kind` (§5.5 — established at v9.7 sign); values are past-participle
+ * kebab-case literals. The 6-kind enumeration is the v9.8 §4.4 floor.
+ *
+ * Payload shapes finalize alongside §4 IPC impl (PR-impl-2, liuliu-owned);
+ * the discriminator is locked here so consumers can write exhaustive
+ * switches today.
+ *
+ * Note: v9.8 §4.4 has an example block still showing the v9.7-pre field
+ * name `topic` + present-tense values; §5.5 is the byte-pin source of
+ * truth (`kind` + past-participle). The §4.4 example will be reconciled
+ * in a follow-up doc-clean pass.
+ */
+type ServiceEvent = {
+    kind: "service-state-changed";
+    payload: unknown;
+} | {
+    kind: "runner-state-changed";
+    payload: unknown;
+} | {
+    kind: "runner-attached";
+    payload: unknown;
+} | {
+    kind: "runner-detached";
+    payload: unknown;
+} | {
+    kind: "upgrade-log-appended";
+    payload: unknown;
+} | {
+    kind: "heartbeat";
+    payload: unknown;
+};
+/**
+ * Library-side error envelope thrown by `ServiceClient`. `code` is a
+ * member of the §7 closed-set; `cause` is retained in-process only and
+ * MUST NOT cross IPC / CLI fail boundaries (§7.4 redaction).
+ */
+declare class ServiceClientError extends Error {
+    readonly code: IpcErrorCode;
+    readonly cause?: unknown;
+    constructor(code: IpcErrorCode, message: string, cause?: unknown);
+}
+/**
+ * Typed IPC client. The implementation in PR-impl-2 §4 satisfies this
+ * interface; this commit only locks the surface.
+ *
+ * Termination semantics (§4.7):
+ *   - `events` completes naturally (`Symbol.asyncIterator` return) on any
+ *     socket-close path (graceful local/remote, transient, TCP RST). The
+ *     `for-await` loop exits without throwing — idiomatic reconnect is a
+ *     plain outer `while (!stopped) { … }` wrap, no try/catch.
+ *   - `events` THROWS `ServiceClientError` only on protocol-level
+ *     failures: handshake mismatch, frame parse, frame > 1 MiB.
+ * The disjoint split lets consumers distinguish "retry" (iterator end)
+ * from "give up" (throw) without runtime classification.
+ */
+interface ServiceClient {
+    events: AsyncIterable<ServiceEvent>;
+    request<M extends keyof RequestMethodMap>(method: M, params: RequestMethodMap[M]["params"], options?: RequestOptions): Promise<RequestMethodMap[M]["result"]>;
+    close(): Promise<void>;
+}
+/**
+ * Connection options. `protocolVersion` lets a consumer opt-in to a
+ * specific handshake version; the service negotiates highest mutually
+ * supported (§4.3) and may reject with `IPC_PROTOCOL_VERSION_UNSUPPORTED`.
+ */
+interface ConnectServiceOptions {
+    protocolVersion?: number;
+}
+/**
+ * Open a typed IPC connection to the Computer service. Throws
+ * `ServiceClientError` on handshake failure. Concrete implementation
+ * lands in PR-impl-2 §4 (liuliu-owned); the type is locked here so
+ * `apps/slock-computer-app` and other library consumers can type-check
+ * call sites before the transport ships.
+ */
+type ConnectService = (installRoot: string, options?: ConnectServiceOptions) => Promise<ServiceClient>;
+
+/**
+ * Per-runner lifecycle states (§3.2). One state at a time per runner.
+ *
+ *   starting  — spawned, not yet reporting ready
+ *   running   — healthy, reporting heartbeats
+ *   degraded  — alive but not satisfying health invariants (e.g. crash
+ *               budget near breach, see §1/§2)
+ *   crashed   — observed exit / fatal signal
+ *   stopped   — intentional stop (operator-driven via `runners stop` or
+ *               supervisor shutdown)
+ */
+declare const RUNNER_STATE_VALUES: readonly ["starting", "running", "degraded", "crashed", "stopped"];
+type RunnerState = (typeof RUNNER_STATE_VALUES)[number];
+declare function isRunnerState(value: unknown): value is RunnerState;
+/**
+ * Service (supervisor) lifecycle states (§3.2). Mirrors runner shape but
+ * narrower — the service is a singleton per install root.
+ *
+ *   starting  — pidfile written, socket not yet listening
+ *   running   — socket listening, heartbeat active
+ *   degraded  — service alive but one or more invariants violated
+ *               (e.g. SERVICE_DEGRADED §7.3 crash-budget breach)
+ *   stopping  — graceful shutdown in flight (SERVICE_SHUTTING_DOWN
+ *               §7.3 emitted to clients)
+ *   stopped   — pidfile cleared, socket closed
+ */
+declare const SERVICE_STATE_VALUES: readonly ["starting", "running", "degraded", "stopping", "stopped"];
+type ServiceState = (typeof SERVICE_STATE_VALUES)[number];
+declare function isServiceState(value: unknown): value is ServiceState;
+
+type UpgradeTrigger = "cli" | "web" | "tray";
+/**
+ * v8.3.3 §4.4 (6) closed-set, verbatim 7 values. Adding / renaming /
+ * deleting any value requires an RFC bump (locked discipline). This
+ * constant array is the runtime source of truth for `assertUpgradeLogEntry`
+ * membership check; the type alias below mirrors it.
+ */
+declare const UPGRADE_ERROR_CODES: readonly ["UPGRADE_DEPS_CHANGED", "UPGRADE_NETWORK_FAILED", "UPGRADE_INTEGRITY_FAILED", "UPGRADE_SWAP_FAILED", "UPGRADE_RESTART_FAILED", "UPGRADE_NO_TARGET", "UPGRADE_ALREADY_RUNNING"];
+type UpgradeErrorCode = (typeof UPGRADE_ERROR_CODES)[number];
+interface UpgradeBundle {
+    computerVersion: string;
+    /**
+     * Forensic-only per v8.3.2 cleanup. May be omitted; consumers MUST
+     * NOT treat presence/absence as a user-facing contract. The bundled
+     * daemon version plumbing (read from Computer package
+     * `dependencies["@slock-ai/daemon"]`) lands as a follow-up; until
+     * then writers emit just `computerVersion` and downstream readers
+     * default to "unknown" when the field is absent.
+     */
+    bundledDaemonVersion?: string;
+}
+/**
+ * v8.3.3 audit-log entry shape, discriminated on `outcome`. Splitting
+ * the union means:
+ *   - `outcome: "ok"` forbids `errorCode` at the type level
+ *     (`errorCode?: never`)
+ *   - `outcome: "err"` requires `errorCode: UpgradeErrorCode` (closed-set
+ *     7-value membership enforced by TS)
+ *
+ * Together with the runtime `assertUpgradeLogEntry` guard below, this
+ * eliminates the prior "caller-discipline only" silent contract drift
+ * (Hao caveat msg=308d99db — `errorCode?: string` allowed any string +
+ * silent omission on `err` paths).
+ */
+type UpgradeLogEntry = UpgradeLogEntryOk | UpgradeLogEntryErr;
+interface UpgradeLogEntryOk {
+    /** ISO timestamp via formatUpgradeLogTimestamp(); caller may omit to auto-fill. */
+    at?: string;
+    fromBundle: UpgradeBundle;
+    toBundle: UpgradeBundle;
+    channel: string;
+    trigger: UpgradeTrigger;
+    outcome: "ok";
+    /** Forbidden on ok entries — discriminated-union enforcement. */
+    errorCode?: never;
+}
+interface UpgradeLogEntryErr {
+    at?: string;
+    fromBundle: UpgradeBundle;
+    toBundle: UpgradeBundle;
+    channel: string;
+    trigger: UpgradeTrigger;
+    outcome: "err";
+    /** Required iff outcome === "err"; one of the v8.3.3 closed 7-value set. */
+    errorCode: UpgradeErrorCode;
+}
+/**
+ * Runtime assertion: `entry` is a valid `UpgradeLogEntry`. Throws
+ * `TypeError` with an actionable message on contract violation. Defense
+ * in depth against JS-interop callers, JSON-deserialized payloads, and
+ * future type-system escapes.
+ *
+ * Validations:
+ *   - `outcome === "ok"` AND `errorCode` is set → reject
+ *   - `outcome === "err"` AND `errorCode` is missing → reject
+ *   - `outcome === "err"` AND `errorCode` not in 7-value closed set → reject
+ *   - Both bundle objects must have a non-empty `computerVersion` string
+ */
+declare function assertUpgradeLogEntry(entry: UpgradeLogEntry): void;
+
+export { type ConnectService, type ConnectServiceOptions, IPC_ERROR_CODES, type IpcErrorCode, RUNNER_STATE_VALUES, type RequestMethodMap, type RequestOptions, type RunnerState, SERVICE_STATE_VALUES, type ServiceClient, ServiceClientError, type ServiceEvent, type ServiceState, UPGRADE_ERROR_CODES, type UpgradeBundle, type UpgradeErrorCode, type UpgradeLogEntry, type UpgradeLogEntryErr, type UpgradeLogEntryOk, type UpgradeTrigger, assertUpgradeLogEntry, isIpcErrorCode, isRunnerState, isServiceState };

package/dist/lib/index.js

@@ -0,0 +1,107 @@
+// src/lib/types.ts
+var IPC_ERROR_CODES = [
+  "IPC_FRAME_TOO_LARGE",
+  "IPC_PROTOCOL_VERSION_UNSUPPORTED",
+  "IPC_HEARTBEAT_TIMEOUT",
+  "IPC_MALFORMED_FRAME",
+  "IPC_REQUEST_TIMEOUT",
+  "IPC_REQUEST_CANCELED",
+  "IPC_CLIENT_CLOSED"
+];
+function isIpcErrorCode(value) {
+  return typeof value === "string" && IPC_ERROR_CODES.includes(value);
+}
+var ServiceClientError = class extends Error {
+  code;
+  cause;
+  constructor(code, message, cause) {
+    super(message);
+    this.name = "ServiceClientError";
+    this.code = code;
+    if (cause !== void 0) this.cause = cause;
+  }
+};
+
+// src/lib/state.ts
+var RUNNER_STATE_VALUES = [
+  "starting",
+  "running",
+  "degraded",
+  "crashed",
+  "stopped"
+];
+function isRunnerState(value) {
+  return typeof value === "string" && RUNNER_STATE_VALUES.includes(value);
+}
+var SERVICE_STATE_VALUES = [
+  "starting",
+  "running",
+  "degraded",
+  "stopping",
+  "stopped"
+];
+function isServiceState(value) {
+  return typeof value === "string" && SERVICE_STATE_VALUES.includes(value);
+}
+
+// src/upgradeLog.ts
+import { chmod, mkdir, open } from "fs/promises";
+
+// src/paths.ts
+import { createHash } from "crypto";
+import os from "os";
+import path from "path";
+
+// src/upgradeLog.ts
+var UPGRADE_ERROR_CODES = [
+  "UPGRADE_DEPS_CHANGED",
+  "UPGRADE_NETWORK_FAILED",
+  "UPGRADE_INTEGRITY_FAILED",
+  "UPGRADE_SWAP_FAILED",
+  "UPGRADE_RESTART_FAILED",
+  "UPGRADE_NO_TARGET",
+  "UPGRADE_ALREADY_RUNNING"
+];
+var UPGRADE_ERROR_CODE_SET = new Set(UPGRADE_ERROR_CODES);
+function assertUpgradeLogEntry(entry) {
+  const e = entry;
+  if (e.outcome === "ok") {
+    if (e.errorCode !== void 0) {
+      throw new TypeError(
+        `UpgradeLogEntry contract violation: outcome="ok" must not carry errorCode (got "${e.errorCode}").`
+      );
+    }
+  } else if (e.outcome === "err") {
+    if (e.errorCode === void 0) {
+      throw new TypeError(
+        `UpgradeLogEntry contract violation: outcome="err" requires errorCode from the v8.3.3 closed-set (${UPGRADE_ERROR_CODES.join(" | ")}).`
+      );
+    }
+    if (!UPGRADE_ERROR_CODE_SET.has(e.errorCode)) {
+      throw new TypeError(
+        `UpgradeLogEntry contract violation: errorCode "${e.errorCode}" is not in the v8.3.3 closed 7-value set (${UPGRADE_ERROR_CODES.join(" | ")}).`
+      );
+    }
+  } else {
+    throw new TypeError(
+      `UpgradeLogEntry contract violation: outcome must be "ok" or "err" (got "${e.outcome}").`
+    );
+  }
+  if (typeof e.fromBundle?.computerVersion !== "string" || e.fromBundle.computerVersion.length === 0) {
+    throw new TypeError(`UpgradeLogEntry contract violation: fromBundle.computerVersion must be a non-empty string.`);
+  }
+  if (typeof e.toBundle?.computerVersion !== "string" || e.toBundle.computerVersion.length === 0) {
+    throw new TypeError(`UpgradeLogEntry contract violation: toBundle.computerVersion must be a non-empty string.`);
+  }
+}
+export {
+  IPC_ERROR_CODES,
+  RUNNER_STATE_VALUES,
+  SERVICE_STATE_VALUES,
+  ServiceClientError,
+  UPGRADE_ERROR_CODES,
+  assertUpgradeLogEntry,
+  isIpcErrorCode,
+  isRunnerState,
+  isServiceState
+};

package/package.json

@@ -1,11 +1,18 @@
 {
   "name": "@slock-ai/computer",
-  "version": "0.0.13-alpha.0",
+  "version": "0.0.14",
   "description": "Slock Computer — standalone human/local-machine control-plane CLI (login + attach). Distinct from the agent-facing @slock-ai/cli.",
   "type": "module",
   "bin": {
     "slock-computer": "dist/index.js"
   },
+  "exports": {
+    "./lib": {
+      "types": "./dist/lib/index.d.ts",
+      "default": "./dist/lib/index.js"
+    },
+    "./package.json": "./package.json"
+  },
   "files": [
     "dist"
   ],
@@ -21,7 +28,7 @@
     "commander": "^12.1.0",
     "proper-lockfile": "^4.1.2",
     "undici": "^7.24.7",
-    "@slock-ai/daemon": "0.54.2-alpha.0"
+    "@slock-ai/daemon": "0.55.0"
   },
   "devDependencies": {
     "@types/node": "^25.5.0",