@celljs/ta-protocol 4.6.0 → 4.7.0

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 (47) hide show
  1. package/README.en.md +11 -0
  2. package/README.md +4 -3
  3. package/esm/common/index.d.ts +2 -0
  4. package/esm/common/index.js +2 -0
  5. package/esm/common/index.js.map +1 -1
  6. package/esm/common/location.d.ts +45 -0
  7. package/esm/common/location.js +175 -0
  8. package/esm/common/location.js.map +1 -0
  9. package/esm/common/remote-protocol.d.ts +85 -0
  10. package/esm/common/remote-protocol.js +3 -0
  11. package/esm/common/remote-protocol.js.map +1 -0
  12. package/esm/common/ta-extension-host.d.ts +2 -0
  13. package/esm/common/ta-extension-host.js.map +1 -1
  14. package/esm/common/ta-protocol.d.ts +9 -2
  15. package/esm/common/ta-protocol.js.map +1 -1
  16. package/lib/common/index.d.ts +2 -0
  17. package/lib/common/index.d.ts.map +1 -1
  18. package/lib/common/index.js +2 -0
  19. package/lib/common/index.js.map +1 -1
  20. package/lib/common/location.d.ts +46 -0
  21. package/lib/common/location.d.ts.map +1 -0
  22. package/lib/common/location.js +178 -0
  23. package/lib/common/location.js.map +1 -0
  24. package/lib/common/location.spec.d.ts +2 -0
  25. package/lib/common/location.spec.d.ts.map +1 -0
  26. package/lib/common/location.spec.js +58 -0
  27. package/lib/common/location.spec.js.map +1 -0
  28. package/lib/common/remote-protocol.d.ts +86 -0
  29. package/lib/common/remote-protocol.d.ts.map +1 -0
  30. package/lib/common/remote-protocol.js +6 -0
  31. package/lib/common/remote-protocol.js.map +1 -0
  32. package/lib/common/ta-extension-host.d.ts +2 -0
  33. package/lib/common/ta-extension-host.d.ts.map +1 -1
  34. package/lib/common/ta-extension-host.js.map +1 -1
  35. package/lib/common/ta-protocol.d.ts +9 -2
  36. package/lib/common/ta-protocol.d.ts.map +1 -1
  37. package/lib/common/ta-protocol.js.map +1 -1
  38. package/lib/common/ta-protocol.spec.js +2 -0
  39. package/lib/common/ta-protocol.spec.js.map +1 -1
  40. package/package.json +1 -1
  41. package/src/common/index.ts +2 -0
  42. package/src/common/location.spec.ts +62 -0
  43. package/src/common/location.ts +177 -0
  44. package/src/common/remote-protocol.ts +76 -0
  45. package/src/common/ta-extension-host.ts +2 -0
  46. package/src/common/ta-protocol.spec.ts +2 -0
  47. package/src/common/ta-protocol.ts +9 -2
@@ -0,0 +1,177 @@
1
+ /**
2
+ * Where a conversation works: a directory of the machine of ta serve, as a path, or a directory of another
3
+ * machine that ta serve reaches with ssh, as `ssh://<host>/<absolute path>`. `<host>` is what ssh takes:
4
+ * a Host of ~/.ssh/config, or `[user@]host[:port]`. Without a path (`ssh://<host>`) it is the home
5
+ * directory there, which TaRemoteServer.resolveLocation turns into a path.
6
+ */
7
+ export namespace TaLocation {
8
+ export const SSH = 'ssh://';
9
+
10
+ /** A directory of another machine. */
11
+ export interface Remote {
12
+ host: string;
13
+ /** Absolute, with `/`; empty for the home directory. */
14
+ path: string;
15
+ }
16
+
17
+ /** Letters, digits and `_ . @ : % + - [ ]`, not first a `-`: ssh must not read a host as an option. */
18
+ const HOST = /^(?!-)[\w.@:%+[\]-]+$/;
19
+
20
+ export function isRemote(location: string): boolean {
21
+ return location.startsWith(SSH);
22
+ }
23
+
24
+ /** undefined for a path of the machine of ta serve; throws for an `ssh://` location that is not one. */
25
+ export function parse(location: string): Remote | undefined {
26
+ if (!isRemote(location)) {
27
+ return undefined;
28
+ }
29
+ const rest = location.slice(SSH.length);
30
+ const slash = rest.indexOf('/');
31
+ const host = slash < 0 ? rest : rest.slice(0, slash);
32
+ const path = slash < 0 ? '' : normalize(rest.slice(slash));
33
+ if (!isHost(host)) {
34
+ throw new Error(`${JSON.stringify(location)} names no host: write ssh://<host>/<path>, the host as ssh takes it.`);
35
+ }
36
+ return { host, path };
37
+ }
38
+
39
+ export function isHost(host: string): boolean {
40
+ return HOST.test(host);
41
+ }
42
+
43
+ /** What {@link readHost} makes of what the user typed. */
44
+ export type HostInput = { host: string } | { error: 'empty' | 'invalid' } | { error: 'options'; options: string[] };
45
+
46
+ /** Options of ssh without a value, which change nothing for Ta. */
47
+ const FLAGS = /^-[46AaCfGgKkMNnqsTtVvXxYy]+$/;
48
+
49
+ /**
50
+ * A host as the user may write it: `dev`, `me@dev`, `me@dev:2222`, `ssh://me@dev:2222/path`, or the
51
+ * command line they use (`ssh -p 2222 me@dev`, `ssh me@dev -p 2222 -l root`). Options that a host
52
+ * cannot hold (`-i`, `-J`, `-o ProxyCommand=…`) belong in ~/.ssh/config: they come back as `options`.
53
+ */
54
+ export function readHost(input: string): HostInput {
55
+ const words = input.trim().split(/\s+/).filter(Boolean);
56
+ if (words[0] === 'ssh') {
57
+ words.shift();
58
+ }
59
+ let destination: string | undefined;
60
+ let port: string | undefined;
61
+ let user: string | undefined;
62
+ const options: string[] = [];
63
+ for (let i = 0; i < words.length; i++) {
64
+ const word = words[i];
65
+ const glued = /^-([pl])(.+)$/.exec(word);
66
+ if (word === '-p' || word === '-l' || glued) {
67
+ const value = glued ? glued[2] : words[++i];
68
+ if (value === undefined) {
69
+ return { error: 'invalid' };
70
+ }
71
+ if ((glued ? glued[1] : word[1]) === 'p') {
72
+ port = value;
73
+ } else {
74
+ user = value;
75
+ }
76
+ } else if (word === '-o' || word.startsWith('-o')) {
77
+ const value = word === '-o' ? words[++i] : word.slice(2);
78
+ const option = /^(port|user)\s*=?\s*(.+)$/i.exec(value ?? '');
79
+ if (!option) {
80
+ options.push(`-o ${value ?? ''}`.trim());
81
+ } else if (option[1].toLowerCase() === 'port') {
82
+ port = option[2];
83
+ } else {
84
+ user = option[2];
85
+ }
86
+ } else if (FLAGS.test(word)) {
87
+ // No value, nothing for Ta.
88
+ } else if (word.startsWith('-')) {
89
+ options.push(/^-[bBcDeEFiIJLmOQRSwW]$/.test(word) && words[i + 1] !== undefined ? `${word} ${words[++i]}` : word);
90
+ } else if (destination === undefined) {
91
+ destination = word;
92
+ } else {
93
+ // A command to run there: not a host.
94
+ return { error: 'invalid' };
95
+ }
96
+ }
97
+ if (options.length > 0) {
98
+ return { error: 'options', options };
99
+ }
100
+ if (!destination) {
101
+ return { error: 'empty' };
102
+ }
103
+ let host = destination.replace(/^ssh:\/\//, '').replace(/\/.*$/, '');
104
+ if (user && !host.includes('@')) {
105
+ host = `${user}@${host}`;
106
+ }
107
+ if (port) {
108
+ if (!/^\d{1,5}$/.test(port) || /:\d+$/.test(host)) {
109
+ return { error: 'invalid' };
110
+ }
111
+ host = port === '22' ? host : `${host}:${port}`;
112
+ }
113
+ return isHost(host) ? { host } : { error: 'invalid' };
114
+ }
115
+
116
+ /** `ssh://<host><path>`; `path` absolute, or empty for the home directory. */
117
+ export function ssh(host: string, path = ''): string {
118
+ return `${SSH}${host}${path ? normalize(path) : ''}`;
119
+ }
120
+
121
+ /** The host of a remote location; undefined for this machine. */
122
+ export function host(location: string): string | undefined {
123
+ return isRemote(location) ? parse(location)?.host : undefined;
124
+ }
125
+
126
+ /** The path inside its machine. */
127
+ export function path(location: string): string {
128
+ return parse(location)?.path ?? location;
129
+ }
130
+
131
+ /** The directory above; undefined at a root (`/`, `C:\\`, the root of a host). */
132
+ export function parent(location: string): string | undefined {
133
+ const remote = parse(location);
134
+ if (remote) {
135
+ const above = remote.path ? parentPath(remote.path) : undefined;
136
+ return above === undefined ? undefined : ssh(remote.host, above);
137
+ }
138
+ return parentPath(location);
139
+ }
140
+
141
+ export function child(location: string, name: string): string {
142
+ const remote = parse(location);
143
+ if (remote) {
144
+ return ssh(remote.host, childPath(remote.path || '/', name));
145
+ }
146
+ return childPath(location, name);
147
+ }
148
+
149
+ /** The last name of the path; the host for its home directory. */
150
+ export function basename(location: string): string {
151
+ const remote = parse(location);
152
+ const path = (remote ? remote.path : location).replace(/[\\/]+$/, '');
153
+ const name = path.slice(Math.max(path.lastIndexOf('/'), path.lastIndexOf('\\')) + 1);
154
+ return name || remote?.host || location;
155
+ }
156
+
157
+ function parentPath(path: string): string | undefined {
158
+ const trimmed = path.replace(/[\\/]+$/, '');
159
+ const at = Math.max(trimmed.lastIndexOf('/'), trimmed.lastIndexOf('\\'));
160
+ if (at < 0) {
161
+ return undefined;
162
+ }
163
+ const head = trimmed.slice(0, at);
164
+ return head === '' || /^[A-Za-z]:$/.test(head) ? head + trimmed[at] : head;
165
+ }
166
+
167
+ function childPath(path: string, name: string): string {
168
+ const separator = path.includes('/') || !path.includes('\\') ? '/' : '\\';
169
+ return path.endsWith(separator) ? path + name : path + separator + name;
170
+ }
171
+
172
+ /** One `/` between names, none at the end but for the root. */
173
+ function normalize(path: string): string {
174
+ const squeezed = `/${path}`.replace(/\/+/g, '/');
175
+ return squeezed.length > 1 ? squeezed.replace(/\/$/, '') : squeezed;
176
+ }
177
+ }
@@ -0,0 +1,76 @@
1
+ export const TaRemoteServer = Symbol('TaRemoteServer');
2
+ export const TA_REMOTE_SERVICE = 'TaRemoteServer';
3
+
4
+ /** A machine ta serve can reach with ssh. */
5
+ export interface TaRemoteHost {
6
+ /** What follows `ssh://` in a location (TaLocation). */
7
+ host: string;
8
+ /** A Host of ~/.ssh/config, or one opened before. */
9
+ source: 'config' | 'recent';
10
+ /** ta serve is connected to it now. */
11
+ connected: boolean;
12
+ }
13
+
14
+ /**
15
+ * What ssh asks while it connects (a password, a passphrase, whether to trust a new host key), for
16
+ * whoever is there to answer: `confirm` takes `yes` or `no`, `secret` is not shown as typed.
17
+ */
18
+ export interface TaRemotePrompt {
19
+ promptId: string;
20
+ host: string;
21
+ kind: 'secret' | 'confirm' | 'text';
22
+ message: string;
23
+ }
24
+
25
+ /** What happens with the remote machines, to the connections that called TaRemoteServer.watch. */
26
+ export type TaRemoteEvent =
27
+ | { type: 'prompt'; prompt: TaRemotePrompt }
28
+ /** Answered, by this client or another, or ssh no longer waits. */
29
+ | { type: 'prompt_closed'; promptId: string }
30
+ /** A step of connecting that takes a while: the first connection installs things there. */
31
+ | { type: 'progress'; host: string; step: TaRemoteStep; detail?: string }
32
+ /** Connected to the host, or no longer. */
33
+ | { type: 'connection'; host: string; connected: boolean; error?: string };
34
+
35
+ /**
36
+ * The steps of connecting to a host: ssh signs in, then Ta looks at what the host has, installs Node.js
37
+ * there when it has none (`detail`: the version), copies its small server, and starts it.
38
+ */
39
+ export type TaRemoteStep = 'connecting' | 'checking' | 'installing-node' | 'copying-server' | 'starting';
40
+
41
+ /** A port of another machine, reachable on the machine of ta serve. */
42
+ export interface TaForwardedPort {
43
+ host: string;
44
+ /** On the other machine. */
45
+ remotePort: number;
46
+ /** On the machine of ta serve, at 127.0.0.1. */
47
+ localPort: number;
48
+ }
49
+
50
+ /**
51
+ * Other machines that conversations work on, as VS Code's Remote SSH: the agent runs with ta serve, and
52
+ * its commands and files are there, through the `ssh` of the machine of ta serve with its configuration.
53
+ */
54
+ export interface TaRemoteServer {
55
+ /** The Hosts of ~/.ssh/config without wildcards, and those added or opened before, the latest first. */
56
+ listHosts(): Promise<TaRemoteHost[]>;
57
+ /** Keeps a host in the list (`recent`), without connecting to it. */
58
+ addHost(host: string): Promise<void>;
59
+ /** Disconnects from a host and drops it from the list; one of ~/.ssh/config stays there. */
60
+ removeHost(host: string): Promise<void>;
61
+ /** The location with the path of the home directory when it has none; connects to the host. */
62
+ resolveLocation(location: string): Promise<string>;
63
+ /**
64
+ * A port of the machine of `cwd` on the machine of ta serve, for a page served there: the same port
65
+ * when `cwd` is a directory of this machine. It stays open while ta serve runs.
66
+ */
67
+ forwardPort(port: number, cwd?: string): Promise<TaForwardedPort>;
68
+ listForwardedPorts(): Promise<TaForwardedPort[]>;
69
+ closeForwardedPort(host: string, remotePort: number): Promise<void>;
70
+ /** This connection hears TaClient.onRemoteEvent from now; resolves to the prompts that wait. */
71
+ watch(): Promise<TaRemotePrompt[]>;
72
+ /** The answer to a prompt; `null` cancels it. False when it no longer waits. */
73
+ answer(promptId: string, value: string | null): Promise<boolean>;
74
+ /** Ends the connection to the host, its processes and forwarded ports there. */
75
+ disconnect(host: string): Promise<void>;
76
+ }
@@ -11,6 +11,8 @@ export interface TaExtensionHost
11
11
  Pick<TaPackageServer, 'getExtensionData' | 'setExtensionData' | 'listPackages'> {
12
12
  /** The agent directory of Ta (`~/.ta/agent`): its `extensions/` holds the packages of the user. */
13
13
  readonly agentDir: string;
14
+ /** Where the conversation of a session file works, as clients name it (a path or an `ssh://` location), without opening it; undefined when it cannot be read. */
15
+ sessionCwd(sessionFile: string): Promise<string | undefined>;
14
16
  /** Keys of the data of a package that changed, by a page or by the server, as they change; `cwd` for a key of a directory. */
15
17
  onExtensionData(listener: (name: string, key: string, cwd?: string) => void): () => void;
16
18
  }
@@ -2,6 +2,7 @@ import { describe, expect, it } from 'bun:test';
2
2
  import { TA_AUTH_SERVICE, TaAuthServer } from './auth-protocol';
3
3
  import { TA_PACKAGE_SERVICE, TaPackageServer } from './package-protocol';
4
4
  import { TA_RELAY_SERVICE, TaRelayServer } from './relay-protocol';
5
+ import { TA_REMOTE_SERVICE, TaRemoteServer } from './remote-protocol';
5
6
  import { TA_SETTINGS_SERVICE, TaSettingsServer } from './settings-protocol';
6
7
  import { type PiCommandMethod, TA_CLIENT_SERVICE, TA_SERVER_SERVICE, TaClient, TaErrorCode, TaMessageContext, TaServer } from './ta-protocol';
7
8
  import { TA_TERMINAL_SERVICE, TA_WORKSPACE_SERVICE, TaTerminalServer, TaWorkspaceServer } from './workspace-protocol';
@@ -31,6 +32,7 @@ describe('ta protocol', () => {
31
32
  expect(TaPackageServer.description).toBe(TA_PACKAGE_SERVICE);
32
33
  expect(TaAuthServer.description).toBe(TA_AUTH_SERVICE);
33
34
  expect(TaRelayServer.description).toBe(TA_RELAY_SERVICE);
35
+ expect(TaRemoteServer.description).toBe(TA_REMOTE_SERVICE);
34
36
  });
35
37
 
36
38
  it('has a method of TaServer for each command of pi', () => {
@@ -1,5 +1,6 @@
1
1
  import type { TaAuthEvent } from './auth-protocol';
2
2
  import type { ImageContent, JsonAgentSessionEvent, RpcCommand, RpcExtensionUIRequest, RpcExtensionUIResponse, RpcResponse, ThinkingLevel } from './pi-types';
3
+ import type { TaRemoteEvent } from './remote-protocol';
3
4
 
4
5
  export const TaServer = Symbol('TaServer');
5
6
  export const TaClient = Symbol('TaClient');
@@ -28,6 +29,10 @@ export interface TaServerInfo {
28
29
  * `setWorkingDirectory`, else the working directory of `ta serve`, or of its execution environment.
29
30
  */
30
31
  cwd: string;
32
+ /** The user who runs `ta serve`, as the system names them: whose Ta the client is signed in to. */
33
+ user: string;
34
+ /** The name of the machine of `ta serve`, without a `.local` suffix. */
35
+ host: string;
31
36
  }
32
37
 
33
38
  /** The stable `code` of each failure of a {@link TaServer} call. */
@@ -91,7 +96,7 @@ export interface TaClientToolDefinition {
91
96
  }
92
97
 
93
98
  export interface TaOpenSessionOptions {
94
- /** Working directory of the session, on the machine of the server. */
99
+ /** Working directory of the session: a path of the machine of the server, or an `ssh://` location of another (TaLocation). */
95
100
  cwd: string;
96
101
  /** Opens this session file; default: a new session. */
97
102
  sessionFile?: string;
@@ -253,7 +258,7 @@ export interface TaClientToolResult {
253
258
  * The sessions of `ta serve`, over JSON-RPC 2.0 on a WebSocket. Besides opening, attaching and answering,
254
259
  * each method is the command of pi's RPC mode with the same name in camelCase, on the open session
255
260
  * `sessionId` (see PiCommandMethod). The same WebSocket carries the other services of ta serve, each
256
- * under its own name: TaWorkspaceServer, TaTerminalServer, TaSettingsServer and TaPackageServer.
261
+ * under its own name: TaWorkspaceServer, TaTerminalServer, TaSettingsServer, TaPackageServer, TaRemoteServer and others.
257
262
  */
258
263
  export interface TaServer {
259
264
  getServerInfo(): Promise<TaServerInfo>;
@@ -337,4 +342,6 @@ export interface TaClient {
337
342
  onExtensionData(name: string, keys: string[], cwd?: string): Promise<void>;
338
343
  /** What happens during a sign-in this connection started (TaAuthServer.login). */
339
344
  onAuthEvent(loginId: string, event: TaAuthEvent): Promise<void>;
345
+ /** What happens with the remote machines, once this connection called TaRemoteServer.watch. */
346
+ onRemoteEvent(event: TaRemoteEvent): Promise<void>;
340
347
  }