@slock-ai/computer 0.0.16-alpha.0 → 0.0.17

package/dist/lib/index.d.ts

@@ -11,7 +11,7 @@ interface ServerStatusRow {
     serverMachineId: string;
     serverUrl: string;
     attachedAt: string | null;
-    daemonLogPath: string;
+    serverRunnerLogPath: string;
     daemon: DaemonState;
     /** v6 §11 health enum surfaced in `status` table (PR-H §3.3). */
     health: ServerHealth;
@@ -28,6 +28,33 @@ interface ComputerStatusReport {
     servers: ServerStatusRow[];
 }
 
+interface LegacyMachineRosterEntry {
+    daemonId: string;
+    apiKeyFingerprint: string;
+    machineName: string;
+    hostname: string | null;
+    lastSeenAt: string | null;
+}
+type LegacyMachineRosterResult = {
+    status: "success";
+    entries: LegacyMachineRosterEntry[];
+} | {
+    status: "auth_required";
+} | {
+    status: "not_authorized";
+} | {
+    status: "disabled";
+} | {
+    status: "error";
+    code: string;
+};
+declare class LegacyMachinesClient {
+    private readonly baseUrl;
+    private readonly accessToken;
+    constructor(baseUrl: string, accessToken: string);
+    private url;
+    list(serverSlug: string): Promise<LegacyMachineRosterResult>;
+}
 interface RunnerListItem {
     agentId: string;
     name: string;
@@ -354,55 +381,66 @@ interface UpgradeStartResult {
     targetVersion: string;
 }
 /**
- * Identity record for a legacy `@slock-ai/daemon` machine candidate that
- * `detectLegacyMigration` discovered locally on this Computer install
- * root. The shape is identity-only — it never carries credentials.
+ * Identity record for a legacy `@slock-ai/daemon` machine candidate
+ * surfaced by `detectLegacyMigration`. Each candidate is the result of
+ * intersecting (a) local `<installRoot>/machines/machine-<fp>/owner.json`
+ * evidence with (b) the server's `GET /api/computer/legacy-machines`
+ * roster on `apiKeyFingerprint` for the logged-in user + target server.
+ * The shape is identity-only — it never carries credentials.
+ *
+ * `apiKeyFingerprint` is the v9.9 intersection key —
+ * `sha256(apiKey).slice(0,16)`. The same value is computed locally by
+ * the legacy daemon (`packages/daemon/src/machineLock.ts`) and stored
+ * server-side on `daemons.api_key_fingerprint` (handshake-backfilled).
+ * Stable as long as the legacy api key is unchanged.
  *
- * `machineId` is the legacy daemon's lock-id (`machine-<sha256(apiKey)
- * [0..15]>`). It is stable across legacy daemon restarts but changes if
- * the user rotates the api key. The id is what the user would see in
- * `<installRoot>/machines/` directory listings, and is what
- * `AdoptLegacyService.migrate()` uses to find the lock owner file
- * during migration.
+ * `daemonId` is the server's `daemons.id` UUID (display + post-migration
+ * identity). It is NOT a join key — fingerprint is. Cody redline
+ * msg=ec68c27f: server daemonId / machineName are display-only.
  *
- * `machineName` is the host display name observed in the legacy
- * daemon's `daemon.lock/owner.json` (typically `os.hostname()` at
- * legacy daemon spawn time). Best-effort, may be undefined for stale
- * lock files.
+ * `localPath` is the absolute path of the local owner.json that
+ * supplied the fingerprint side of the intersection. Surfaced so the
+ * picker can show the operator which on-disk legacy install they are
+ * about to adopt, and so the manual `--migrate-from` flag's three-gate
+ * validator (path-readable / owner.json-parseable / fingerprint-in-roster)
+ * can return a candidate that points at the same path the operator
+ * passed.
  *
- * `serverUrl` is the API server the legacy daemon was attached to.
- * Used by the migrate prompt to surface "you are about to migrate
- * machine X attached to <server>" before the user accepts.
+ * `machineName` / `hostname` / `lastSeenAt` come from the server roster
+ * row — display-only, used for picker presentation. May be empty for
+ * stale rows; the picker tolerates blanks.
  */
 interface LegacyMachineCandidate {
-    machineId: string;
-    machineName?: string;
-    serverUrl?: string;
+    apiKeyFingerprint: string;
+    daemonId: string;
+    localPath: string;
+    machineName: string;
+    hostname?: string;
+    lastSeenAt?: string;
 }
 /**
- * §X migration detection result — the discriminated union returned by
- * `detectLegacyMigration(installRoot, loggedInUserId)`.
+ * §X.2 migration detection result — the discriminated union returned by
+ * `detectLegacyMigration(installRoot, target)`.
  *
- * Per RFC §X.2:
- *   - `match`: exactly one local legacy daemon machine. The setup flow
- *     SHOULD prompt the user to migrate before falling back to fresh
- *     setup. Migration itself is delegated to `AdoptLegacyService.
- *     migrate()` (preserved as internal helper per §X.6 — 11 typed
- *     errors / 4 events / Result discriminator byte-identical).
- *   - `no-match`: zero local legacy daemon machines. Fresh setup
- *     proceeds without any migrate prompt.
- *   - `ambiguous`: two or more local legacy daemon machines. Per §X.2
- *     "no auto-listed-pick fallback" — fresh setup proceeds without
- *     any migrate prompt; the user is expected to start the legacy
- *     daemon they want migrated first to disambiguate.
+ * Per RFC v9.9 §X.2:
+ *   - `candidates`: zero-or-more legacy daemons survived the
+ *     local-owner-json ∩ server-roster intersection. Empty intersection
+ *     is a valid `candidates` result with `candidates.length === 0` —
+ *     the setup flow's fresh-attach trigger #1 (§X.4). One-or-more
+ *     candidates → setup picker prompts the operator (TTY) or falls
+ *     through to fresh attach (non-TTY).
+ *   - `server-unavailable`: roster fetch failed (network / auth /
+ *     server gate off / 5xx). Setup falls through to fresh attach
+ *     under the documented "best-effort detection" discipline — a
+ *     transiently unreachable server must NOT block fresh setup.
  *
- * Fingerprint discipline (best-effort non-authoritative — Hao
- * `msg=4d170194`): the candidate set is computed from local
- * `<installRoot>/machines/machine-*` directory state. It identifies
- * "this host has legacy daemon installs" — it does NOT prove ownership.
- * Final adoption still walks the existing
- * `AdoptLegacyService.migrate()` credential validation path; a match
- * is a prompt-gate, not a trust-gate.
+ * Fingerprint discipline (Cody msg=ec68c27f redline):
+ *   - `apiKeyFingerprint` is treated as a sensitive identity. It is
+ *     scoped to this caller's authenticated request and never logged.
+ *   - The intersection is the trust-gate: a candidate proves the
+ *     server has a roster row keyed by the same fingerprint that
+ *     appears in the local owner.json. Final adoption still walks
+ *     `AdoptLegacyService.migrate()` credential validation.
  */
 /**
  * Closed set of `MigrationDetection.kind` discriminator values. Mirrors
@@ -412,48 +450,110 @@ interface LegacyMachineCandidate {
  * `as` cast (state-machine-modeling discipline — correlated/mutex
  * properties land as a closed-set state-enum).
  */
-declare const MIGRATION_DETECTION_KINDS: readonly ["match", "no-match", "ambiguous"];
+declare const MIGRATION_DETECTION_KINDS: readonly ["candidates", "server-unavailable"];
 type MigrationDetectionKind = (typeof MIGRATION_DETECTION_KINDS)[number];
 /** Runtime narrow guard for `MigrationDetection.kind`. */
 declare function isMigrationDetectionKind(value: unknown): value is MigrationDetectionKind;
 type MigrationDetection = {
-    kind: "match";
-    machineId: string;
-    machineName?: string;
-    serverUrl?: string;
-} | {
-    kind: "no-match";
-} | {
-    kind: "ambiguous";
+    kind: "candidates";
     candidates: LegacyMachineCandidate[];
+} | {
+    kind: "server-unavailable";
 };
 
 /**
- * Detect whether `installRoot` already contains legacy
- * `@slock-ai/daemon` machine state that could be migrated to a
- * Computer attachment under the logged-in user.
+ * Roster fetcher contract — `LegacyMachinesClient.list(serverSlug)`
+ * satisfies this structurally. Defining it as an interface here lets
+ * tests stub the network call without instantiating undici.
+ */
+interface LegacyMachineRosterClient {
+    list(serverSlug: string): Promise<LegacyMachineRosterResult>;
+}
+/**
+ * Detect whether the logged-in user has a legacy `@slock-ai/daemon`
+ * machine on the target server that matches a local install on this
+ * host (intersection on `apiKeyFingerprint`).
+ *
+ * Returns:
+ *   - `{ kind: "candidates"; candidates: LegacyMachineCandidate[] }` —
+ *     zero-or-more mutually-known legacy daemons. Empty list is the
+ *     §X.4 fresh-attach trigger #1; non-empty drives the picker.
+ *   - `{ kind: "server-unavailable" }` — roster fetch failed
+ *     transiently. Caller falls through to fresh attach.
  *
- * Returns a discriminated `MigrationDetection`:
- *   - `match` (exactly one candidate) — caller SHOULD prompt the user
- *     to migrate before fresh setup (§X.2 step 3).
- *   - `no-match` (zero candidates) — caller proceeds with fresh
- *     setup, NO prompt (§X.2 step 5).
- *   - `ambiguous` (two-or-more candidates) — caller proceeds with
- *     fresh setup, NO prompt (§X.2 step 5; "no auto-listed-pick
- *     fallback").
+ * Lib-pure: no env reads, no terminal IO, no `process.exit`. Local
+ * filesystem errors are swallowed; only the roster-fetch outcome can
+ * change the discriminator.
+ */
+declare function detectLegacyMigration(installRoot: string, serverSlug: string, client: LegacyMachineRosterClient): Promise<MigrationDetection>;
+/**
+ * Manual `--migrate-from <path>` validator — the three-gate chain that
+ * RFC v9.9 §X.4 specifies for the manual escape hatch when the picker's
+ * intersection set is non-empty but the operator wants to migrate a
+ * different on-disk install.
  *
- * Lib-pure: no env reads, no terminal IO, no process.exit. Filesystem
- * errors are swallowed and treated as "no evidence" (per the doc-
- * block above).
+ * Gates (executed in order, hard-fail on first failure):
+ *   1. `MIGRATE_FROM_NOT_FOUND` — `path` does not exist or is not a
+ *      readable directory / file. Accepts either the `machines/
+ *      machine-<fp>/` directory or its `daemon.lock/owner.json`
+ *      directly; the latter is what doctor / forensic flows surface.
+ *   2. `MIGRATE_FROM_INVALID` — owner.json is unreadable, malformed,
+ *      or missing a 16-hex-char `apiKeyFingerprint` field.
+ *   3. `MIGRATE_FROM_NOT_OWNED` — owner.json's fingerprint is not in
+ *      the supplied roster (the logged-in user does not have a
+ *      legacy daemon row with this fingerprint on the target server,
+ *      or the row is already migrated / NULL-fingerprinted).
  *
- * @param installRoot The Slock home (`SLOCK_HOME`) to scan. Resolved
- *   by the CLI wrapper via `resolveSlockHome`.
- * @param loggedInUserId Reserved for the server-roster intersection
- *   (forward-compat per §X.2 step 1). v0 does not consume this value;
- *   accept the typed argument so consumers of this function can
- *   already pass it.
- */
-declare function detectLegacyMigration(installRoot: string, loggedInUserId: string): Promise<MigrationDetection>;
+ * On success returns the same `LegacyMachineCandidate` shape the
+ * picker emits, so the setup driver's adoption call is the same code
+ * path on both branches.
+ */
+type ManualPathValidation = {
+    ok: true;
+    candidate: LegacyMachineCandidate;
+} | {
+    ok: false;
+    code: "MIGRATE_FROM_NOT_FOUND" | "MIGRATE_FROM_INVALID" | "MIGRATE_FROM_NOT_OWNED";
+};
+declare function validateManualMigratePath(inputPath: string, roster: LegacyMachineRosterEntry[]): Promise<ManualPathValidation>;
+
+type PickerSelection = {
+    kind: "candidate";
+    index: number;
+} | {
+    kind: "fresh";
+} | {
+    kind: "manual";
+    path: string;
+};
+/**
+ * Closed-set enumeration of the §X.4 fresh-attach triggers. Used in
+ * setup info() lines so QA can grep for "fresh trigger: <name>" and
+ * test mocks can assert that ONLY these inputs route to fresh attach
+ * (Cody NIT `msg=9102a817`). The picker function itself only emits
+ * `explicit-zero` / `eof`; the other three are decided upstream in
+ * `runSetup` before the picker ever fires.
+ */
+declare const MIGRATION_FRESH_TRIGGERS: readonly ["empty-intersection", "explicit-zero", "eof", "non-tty", "server-unavailable"];
+type MigrationFreshTrigger = (typeof MIGRATION_FRESH_TRIGGERS)[number];
+/**
+ * Pure picker grammar — extracted so it can be exercised by unit tests
+ * without stubbing global stdin/stdout. RFC v9.9 §X.4 (post-Jianwei FAIL
+ * `msg=ecc2e57e` / Cody NIT `msg=9102a817`):
+ *   - `1`..`N` / `<Enter>` → adopt that candidate (1-indexed; Enter picks
+ *     the first candidate, since the operator already saw the
+ *     intersection list).
+ *   - `0` → fresh attach (Trigger #2: explicit-zero).
+ *   - EOF (Ctrl-D / closed stdin) → fresh attach (Trigger #2: eof).
+ *   - `m` / `M` → emits `manual` and prompts for path on the next line.
+ *   - Anything else → reprompt. The picker NEVER silently falls through
+ *     to fresh attach on unrecognized input — that was the B1/B4 contract
+ *     drift that QA rejected.
+ */
+declare function pickMigrationCandidateFromInput(candidates: LegacyMachineCandidate[], read: () => Promise<{
+    line: string;
+    eof: boolean;
+}>, write: (s: string) => void): Promise<PickerSelection>;
 
 /**
  * Read the Computer-level aggregate status from `installRoot`. Identical
@@ -551,4 +651,4 @@ interface UpgradeLogEntryErr {
  */
 declare function assertUpgradeLogEntry(entry: UpgradeLogEntry): void;
 
-export { type ComputerStatusReport, type ConnectService, type ConnectServiceOptions, type DaemonState, IPC_ERROR_CODES, type IpcErrorCode, type LegacyMachineCandidate, type ListRunnersResult, MIGRATION_DETECTION_KINDS, type MigrationDetection, type MigrationDetectionKind, RUNNER_STATE_VALUES, type RequestMethodMap, type RequestOptions, type ResetRunnerResult, type ResetServiceResult, type RunnerListItem as RunnerInfo, type RunnerListPerServer, type RunnerState, type RunnerStatusResult, SERVICE_STATE_VALUES, STATE_READER_ERROR_CODES, type ServerHealth, type ServerStatusRow, type ServiceClient, ServiceClientError, type ServiceEvent, type ServiceState, type ServiceStatusResult, StateReaderError, type StateReaderErrorCode, UPGRADE_ERROR_CODES, type UpgradeBundle, type UpgradeErrorCode, type UpgradeLogEntry, type UpgradeLogEntryErr, type UpgradeLogEntryOk, type UpgradeStartResult, type UpgradeTrigger, assertUpgradeLogEntry, detectLegacyMigration, isIpcErrorCode, isMigrationDetectionKind, isRunnerState, isServiceState, listRunners, readRunnerStatus, readServiceStatus };
+export { type ComputerStatusReport, type ConnectService, type ConnectServiceOptions, type DaemonState, IPC_ERROR_CODES, type IpcErrorCode, type LegacyMachineCandidate, type LegacyMachineRosterClient, type LegacyMachineRosterEntry, type LegacyMachineRosterResult, LegacyMachinesClient, type ListRunnersResult, MIGRATION_DETECTION_KINDS, MIGRATION_FRESH_TRIGGERS, type ManualPathValidation, type MigrationDetection, type MigrationDetectionKind, type MigrationFreshTrigger, type PickerSelection, RUNNER_STATE_VALUES, type RequestMethodMap, type RequestOptions, type ResetRunnerResult, type ResetServiceResult, type RunnerListItem as RunnerInfo, type RunnerListPerServer, type RunnerState, type RunnerStatusResult, SERVICE_STATE_VALUES, STATE_READER_ERROR_CODES, type ServerHealth, type ServerStatusRow, type ServiceClient, ServiceClientError, type ServiceEvent, type ServiceState, type ServiceStatusResult, StateReaderError, type StateReaderErrorCode, UPGRADE_ERROR_CODES, type UpgradeBundle, type UpgradeErrorCode, type UpgradeLogEntry, type UpgradeLogEntryErr, type UpgradeLogEntryOk, type UpgradeStartResult, type UpgradeTrigger, assertUpgradeLogEntry, detectLegacyMigration, isIpcErrorCode, isMigrationDetectionKind, isRunnerState, isServiceState, listRunners, pickMigrationCandidateFromInput, readRunnerStatus, readServiceStatus, validateManualMigratePath };