@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.
- package/README.en.md +11 -0
- package/README.md +4 -3
- package/esm/common/index.d.ts +2 -0
- package/esm/common/index.js +2 -0
- package/esm/common/index.js.map +1 -1
- package/esm/common/location.d.ts +45 -0
- package/esm/common/location.js +175 -0
- package/esm/common/location.js.map +1 -0
- package/esm/common/remote-protocol.d.ts +85 -0
- package/esm/common/remote-protocol.js +3 -0
- package/esm/common/remote-protocol.js.map +1 -0
- package/esm/common/ta-extension-host.d.ts +2 -0
- package/esm/common/ta-extension-host.js.map +1 -1
- package/esm/common/ta-protocol.d.ts +9 -2
- package/esm/common/ta-protocol.js.map +1 -1
- package/lib/common/index.d.ts +2 -0
- package/lib/common/index.d.ts.map +1 -1
- package/lib/common/index.js +2 -0
- package/lib/common/index.js.map +1 -1
- package/lib/common/location.d.ts +46 -0
- package/lib/common/location.d.ts.map +1 -0
- package/lib/common/location.js +178 -0
- package/lib/common/location.js.map +1 -0
- package/lib/common/location.spec.d.ts +2 -0
- package/lib/common/location.spec.d.ts.map +1 -0
- package/lib/common/location.spec.js +58 -0
- package/lib/common/location.spec.js.map +1 -0
- package/lib/common/remote-protocol.d.ts +86 -0
- package/lib/common/remote-protocol.d.ts.map +1 -0
- package/lib/common/remote-protocol.js +6 -0
- package/lib/common/remote-protocol.js.map +1 -0
- package/lib/common/ta-extension-host.d.ts +2 -0
- package/lib/common/ta-extension-host.d.ts.map +1 -1
- package/lib/common/ta-extension-host.js.map +1 -1
- package/lib/common/ta-protocol.d.ts +9 -2
- package/lib/common/ta-protocol.d.ts.map +1 -1
- package/lib/common/ta-protocol.js.map +1 -1
- package/lib/common/ta-protocol.spec.js +2 -0
- package/lib/common/ta-protocol.spec.js.map +1 -1
- package/package.json +1 -1
- package/src/common/index.ts +2 -0
- package/src/common/location.spec.ts +62 -0
- package/src/common/location.ts +177 -0
- package/src/common/remote-protocol.ts +76 -0
- package/src/common/ta-extension-host.ts +2 -0
- package/src/common/ta-protocol.spec.ts +2 -0
- 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
|
|
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
|
|
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
|
}
|