@anhlp/alp-client 0.0.0-stage → 0.0.1-beta.10

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (78) hide show
  1. package/LICENSE +202 -0
  2. package/NOTICE +7 -0
  3. package/README.md +45 -2
  4. package/dist/acp-probe.d.ts +45 -0
  5. package/dist/acp-probe.js +46 -0
  6. package/dist/antigravity-probe.d.ts +33 -0
  7. package/dist/antigravity-probe.js +101 -0
  8. package/dist/command.d.ts +5 -0
  9. package/dist/command.js +35 -0
  10. package/dist/doctor.d.ts +21 -0
  11. package/dist/doctor.js +850 -0
  12. package/dist/index.d.ts +216 -0
  13. package/dist/index.js +702 -0
  14. package/dist/integration-lock.d.ts +37 -0
  15. package/dist/integration-lock.js +199 -0
  16. package/dist/ipc.d.ts +42 -0
  17. package/dist/ipc.js +69 -0
  18. package/dist/library-test.d.ts +94 -0
  19. package/dist/library-test.js +37 -0
  20. package/dist/mcp-probe.d.ts +24 -0
  21. package/dist/mcp-probe.js +147 -0
  22. package/dist/portable.d.ts +20 -0
  23. package/dist/portable.js +36 -0
  24. package/dist/prompt.d.ts +32 -0
  25. package/dist/prompt.js +59 -0
  26. package/dist/render.d.ts +6 -0
  27. package/dist/render.js +123 -0
  28. package/dist/rpc/client.d.ts +82 -0
  29. package/dist/rpc/client.js +292 -0
  30. package/dist/rpc/errors.d.ts +42 -0
  31. package/dist/rpc/errors.js +34 -0
  32. package/dist/rpc/framing.d.ts +21 -0
  33. package/dist/rpc/framing.js +57 -0
  34. package/dist/rpc/handshake.d.ts +24 -0
  35. package/dist/rpc/handshake.js +10 -0
  36. package/dist/rpc/reconnect.d.ts +97 -0
  37. package/dist/rpc/reconnect.js +227 -0
  38. package/dist/rpc/registry.d.ts +227 -0
  39. package/dist/rpc/registry.js +223 -0
  40. package/dist/rpc/terminal-directory.d.ts +24 -0
  41. package/dist/rpc/terminal-directory.js +70 -0
  42. package/dist/rpc/timers.d.ts +11 -0
  43. package/dist/rpc/timers.js +11 -0
  44. package/dist/service.d.ts +50 -0
  45. package/dist/service.js +145 -0
  46. package/dist/setup.d.ts +8 -0
  47. package/dist/setup.js +273 -0
  48. package/dist/supervise.d.ts +14 -0
  49. package/dist/supervise.js +91 -0
  50. package/dist/websocket.d.ts +51 -0
  51. package/dist/websocket.js +190 -0
  52. package/package.json +174 -4
  53. package/src/acp-probe.js +53 -0
  54. package/src/antigravity-probe.js +113 -0
  55. package/src/command.js +20 -0
  56. package/src/doctor.d.ts +21 -0
  57. package/src/doctor.js +912 -0
  58. package/src/index.js +813 -0
  59. package/src/integration-lock.js +203 -0
  60. package/src/ipc.js +92 -0
  61. package/src/library-test.js +41 -0
  62. package/src/mcp-probe.js +118 -0
  63. package/src/portable.js +30 -0
  64. package/src/prompt.js +64 -0
  65. package/src/render.js +139 -0
  66. package/src/rpc/client.js +296 -0
  67. package/src/rpc/errors.js +54 -0
  68. package/src/rpc/framing.js +61 -0
  69. package/src/rpc/handshake.js +21 -0
  70. package/src/rpc/reconnect.js +226 -0
  71. package/src/rpc/registry.js +229 -0
  72. package/src/rpc/terminal-directory.js +61 -0
  73. package/src/rpc/timers.js +16 -0
  74. package/src/service.js +158 -0
  75. package/src/setup.js +316 -0
  76. package/src/supervise.d.ts +14 -0
  77. package/src/supervise.js +97 -0
  78. package/src/websocket.js +259 -0
@@ -0,0 +1,216 @@
1
+ export function alpHome(env?: NodeJS.ProcessEnv): string;
2
+ /** Windows uses named pipes; long Unix homes get a short socket in the temp directory. */
3
+ export function daemonPaths(home: any): {
4
+ home: any;
5
+ lock: string;
6
+ socket: string;
7
+ log: string;
8
+ install: string;
9
+ };
10
+ export function assertPrivateDirectory(directory: any, { create }?: {
11
+ create?: boolean | undefined;
12
+ }): Promise<void>;
13
+ export function assertPrivateSocket(socketPath: any): Promise<import("fs").Stats | undefined>;
14
+ /**
15
+ * Finds alpd.js for a client that cannot locate it beside itself, such as the Paseo
16
+ * plugin, which Paseo re-bundles: the first existing candidate, then where alpd last
17
+ * recorded itself ($ALP_HOME/alpd.json), then the ALP CLI (`alp`) on PATH and in the usual install
18
+ * directories (`binDirectories`; a test passes [] so the caller's own install is not found).
19
+ */
20
+ export function findDaemonEntry({ home, env, candidates, binDirectories }?: {
21
+ home?: string | undefined;
22
+ env?: NodeJS.ProcessEnv | undefined;
23
+ candidates?: (string | undefined)[] | undefined;
24
+ binDirectories?: string[] | undefined;
25
+ }): Promise<any>;
26
+ /**
27
+ * Integration names are single lowercase path segments: they name `<home>/integrations/<name>.lock`,
28
+ * its guard and `<home>/<name>.json`. Returns the name, or throws a TypeError.
29
+ * @param {unknown} name
30
+ * @returns {string}
31
+ */
32
+ export function assertIntegrationName(name: unknown): string;
33
+ /**
34
+ * Returns a stable identifier for the current OS boot session,
35
+ * or undefined if unavailable on the platform or inaccessible.
36
+ *
37
+ * On Linux, reads /proc/sys/kernel/random/boot_id.
38
+ * On Darwin (macOS), queries sysctl kern.bootsessionuuid.
39
+ *
40
+ * @returns {string | undefined}
41
+ */
42
+ export function bootId(): string | undefined;
43
+ /**
44
+ * Internal/testing seam: resets or sets the cached boot identifier.
45
+ * @param {string | undefined | null} [id]
46
+ */
47
+ export function _setBootIdForTest(id?: string | undefined | null): void;
48
+ /** Wall-clock boot time; a lock from an earlier boot is stale even if its pid is reused. */
49
+ export function bootTime(): number;
50
+ /**
51
+ * Evaluates whether a lock record belongs to the current boot session.
52
+ *
53
+ * When both the lock and the current environment supply a bootId (Linux
54
+ * /proc/sys/kernel/random/boot_id or macOS kern.bootsessionuuid), identity is
55
+ * determined by exact bootId match, which is immune to wall-clock jumps.
56
+ *
57
+ * For legacy locks or environments without a bootId, falls back to checking
58
+ * whether wall-clock bootTime is within a 30-second window.
59
+ *
60
+ * @param {{ bootId?: string, bootTime?: number }} [lock]
61
+ * @param {{ bootId?: string, bootTime?: number }} [current]
62
+ * @returns {boolean}
63
+ */
64
+ export function isSameBoot(lock?: {
65
+ bootId?: string;
66
+ bootTime?: number;
67
+ }, { bootId: curBootId, bootTime: curBootTime }?: {
68
+ bootId?: string;
69
+ bootTime?: number;
70
+ }): boolean;
71
+ export function readLock(home: any): Promise<any>;
72
+ export function lockAlive(lock: any): boolean;
73
+ /**
74
+ * Takes alpd's single-instance lock for `home`: exclusive create; a lock whose pid or boot is
75
+ * gone is stale and replaced. alpd takes it to run; `alp backup` and `alp restore` take it with
76
+ * `maintenance` set, so no alpd starts on data they read or replace (ALPD §68).
77
+ * @param {string} home
78
+ * @param {{ version: string, protocolVersion: number, socket: string, maintenance?: string }} contents
79
+ */
80
+ export function acquireDaemonLock(home: string, contents: {
81
+ version: string;
82
+ protocolVersion: number;
83
+ socket: string;
84
+ maintenance?: string;
85
+ }): Promise<{
86
+ version: string;
87
+ protocolVersion: number;
88
+ socket: string;
89
+ maintenance?: string;
90
+ uid: number;
91
+ ready: boolean;
92
+ bootId?: string | undefined;
93
+ pid: number;
94
+ startedAt: string;
95
+ startedUptime: number;
96
+ bootTime: number;
97
+ }>;
98
+ /** Lets go of alpd's lock if this process holds it. */
99
+ export function releaseDaemonLock(home: any): Promise<void>;
100
+ /**
101
+ * The transport to alpd's socket without the handshake, for an AlpRpcClient or a reconnecting
102
+ * client whose onConnect runs `hello`. `connect` is this plus `hello`.
103
+ * @param {string} socketPath
104
+ * @param {import('./ipc.js').SocketTransportOptions} [options]
105
+ */
106
+ export function connectSocket(socketPath: string, options?: import("./ipc.js").SocketTransportOptions): Promise<import("./rpc/client.js").AlpTransport>;
107
+ /**
108
+ * Connects and performs the version handshake.
109
+ * @param {string} socketPath
110
+ * @param {{ name: string, version: string }} [client]
111
+ * @param {import('./rpc/client.js').AlpRpcClientOptions & import('./ipc.js').SocketTransportOptions} [options]
112
+ * @returns {Promise<AlpClient>}
113
+ */
114
+ export function connect(socketPath: string, client?: {
115
+ name: string;
116
+ version: string;
117
+ }, options?: import("./rpc/client.js").AlpRpcClientOptions & import("./ipc.js").SocketTransportOptions): Promise<AlpClient>;
118
+ export function readDaemonLifecycle(home: any): Promise<{
119
+ token: string;
120
+ pid: number;
121
+ bootTime: number;
122
+ action: string;
123
+ } | undefined>;
124
+ /** Serializes requested starts and stops, including the time before alpd has a lock.
125
+ * Rename publishes a fully populated directory: an existing nonempty directory cannot
126
+ * be replaced. Reaping/release unlinks only its unique owner token, then rmdir; even
127
+ * racing stale reapers cannot remove a successor's nonempty directory.
128
+ */
129
+ export function withDaemonLifecycle(home: any, action: any, run: any, { joinStart, signal }?: {
130
+ joinStart?: boolean | undefined;
131
+ signal?: AbortSignal | undefined;
132
+ }): Promise<any>;
133
+ /**
134
+ * The time a start of alpd waits for it to become ready, in ms: ALP_DAEMON_START_TIMEOUT_MS when it
135
+ * is a positive whole number of at most one hour, else DAEMON_START_TIMEOUT_MS.
136
+ * @param {NodeJS.ProcessEnv} [env]
137
+ */
138
+ export function daemonStartTimeoutMs(env?: NodeJS.ProcessEnv): number;
139
+ /**
140
+ * Returns the socket of a ready daemon, starting one when none runs.
141
+ * `entry` is the daemon script; it is started through its own detaching launcher so the
142
+ * daemon outlives the client that started it.
143
+ */
144
+ export function ensureDaemon({ home, entry, env, execPath, timeoutMs, lifecycleLocked, signal }?: {
145
+ home?: string | undefined;
146
+ entry?: string | undefined;
147
+ env?: NodeJS.ProcessEnv | undefined;
148
+ execPath?: string | undefined;
149
+ timeoutMs?: number | undefined;
150
+ lifecycleLocked?: boolean | undefined;
151
+ signal?: AbortSignal | undefined;
152
+ }): Promise<any>;
153
+ /**
154
+ * The entry of integration `name`: an environment override, a descriptor under the home or a
155
+ * distribution root, or an `alp-<name>-integration` binary. Discovery never returns an entry for
156
+ * `dashboard`: that is alp dashboard's service, which ships with the CLI and is started with its
157
+ * explicit entry; nor for `web`, its name before the rename (t-81b0.5). Everything once registered
158
+ * under `web` (the descriptor `integrations/web.json`, the
159
+ * `alp-web-integration` binary, `ALP_WEB_INTEGRATION`) is the Paseo integration from before its
160
+ * rename to `paseo`, which must never run under the web lock. `ALP_WEB_INTEGRATION` is read for
161
+ * `paseo` only, after `ALP_PASEO_INTEGRATION`, for one release (like the alp-web-integration alias).
162
+ * @param {string} [name]
163
+ * @param {{ home?: string, env?: NodeJS.ProcessEnv, binDirectories?: string[], roots?: string[] }} [options]
164
+ */
165
+ export function discoverIntegration(name?: string, options?: {
166
+ home?: string;
167
+ env?: NodeJS.ProcessEnv;
168
+ binDirectories?: string[];
169
+ roots?: string[];
170
+ }): Promise<string | undefined>;
171
+ export function integrationAlive(lock: any): boolean;
172
+ /**
173
+ * Starts integration `name` (default `dashboard`) detached with `--service` (then `args`) unless its lock
174
+ * already names a live owner, then waits until its ready lock and `<home>/<name>.json` name the same
175
+ * pid. `entry` names the script to run with this Node and skips descriptor, environment and PATH
176
+ * discovery; `dashboard` is never discovered, so it needs its entry. `"dashboard": { "enabled": false }`
177
+ * in the home's settings.json (or `web.enabled`, its key before the rename) refuses `dashboard` only.
178
+ * @param {string | { name?: string, entry?: string, home?: string, args?: string[] }} [nameOrOptions]
179
+ */
180
+ export function startIntegration(nameOrOptions?: string | {
181
+ name?: string;
182
+ entry?: string;
183
+ home?: string;
184
+ args?: string[];
185
+ }): Promise<any>;
186
+ export * from "./portable.js";
187
+ export { createSocketTransport } from "./ipc.js";
188
+ /**
189
+ * One JSON-RPC 2.0 connection to alpd over a Unix socket or named pipe; events arrive as `event`
190
+ * notifications. The engine is the portable AlpRpcClient; this keeps the socket constructor the
191
+ * CLI, alpd's tests and the Paseo plugin use.
192
+ */
193
+ export class AlpClient extends AlpRpcClient {
194
+ /**
195
+ * @param {import('node:net').Socket} socket a connected or connecting socket; the client owns it
196
+ * @param {import('./rpc/client.js').AlpRpcClientOptions & import('./ipc.js').SocketTransportOptions} [options]
197
+ */
198
+ constructor(socket: import("node:net").Socket, { maxFrame, maxBufferedBytes, ...options }?: import("./rpc/client.js").AlpRpcClientOptions & import("./ipc.js").SocketTransportOptions);
199
+ /** Host features captured by connect's handshake. @type {readonly string[]} */
200
+ capabilities: readonly string[];
201
+ /** Limits captured by connect's handshake. @type {import('@anhlp/alp-protocol').AttachmentLimits | undefined} */
202
+ attachmentLimits: import("@anhlp/alp-protocol").AttachmentLimits | undefined;
203
+ /** @type {{ readonly maxCount: number; readonly maxBytes: number; readonly maxTotalBytes: number } | undefined} */
204
+ promptImageLimits: {
205
+ readonly maxCount: number;
206
+ readonly maxBytes: number;
207
+ readonly maxTotalBytes: number;
208
+ } | undefined;
209
+ /** @type {import('@anhlp/alp-protocol').TerminalLimits | undefined} */
210
+ terminalLimits: import("@anhlp/alp-protocol").TerminalLimits | undefined;
211
+ }
212
+ /** How long a start waits for alpd to be ready by default: generous, as a loaded host can take a while. */
213
+ export const DAEMON_START_TIMEOUT_MS: 60000;
214
+ import { AlpRpcClient } from './rpc/client.js';
215
+ export { PROTOCOL_VERSION, MAX_FRAME, AlpRpcError, encodeFrame } from "@anhlp/alp-protocol";
216
+ export { connectWebSocket, createWebSocketTransport, redactUrl, CLOSE_CODE } from "./websocket.js";