castle-web-cli 0.4.213 → 0.4.215
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/dist/agent-prompts.d.ts +14 -0
- package/dist/agent-prompts.js +110 -31
- package/dist/agent.d.ts +12 -0
- package/dist/agent.js +175 -36
- package/dist/api.d.ts +8 -0
- package/dist/castle-host/host.d.ts +45 -0
- package/dist/castle-host/host.js +108 -0
- package/dist/castleJson.d.ts +12 -0
- package/dist/castleJson.js +58 -0
- package/dist/cloudGit.d.ts +261 -0
- package/dist/cloudGit.js +1705 -0
- package/dist/cloudGitServe.d.ts +41 -0
- package/dist/cloudGitServe.js +321 -0
- package/dist/gitRemote.d.ts +4 -1
- package/dist/gitRemote.js +4 -2
- package/dist/ide.js +45 -5
- package/dist/index.js +149 -2
- package/dist/init.js +1 -1
- package/dist/install.js +27 -22
- package/dist/routerFences.d.ts +6 -0
- package/dist/routerFences.js +70 -3
- package/dist/routerStops.d.ts +22 -0
- package/dist/routerStops.js +29 -0
- package/dist/save-deck.js +1 -0
- package/dist/shell/assets/{index-CcJiCq02.js → index-DIRq6YrV.js} +46 -46
- package/dist/shell/index.html +1 -1
- package/kits/base/castle.json +1 -1
- package/kits/base/package-lock.json +1 -1
- package/kits/base/sdk/castle.d.ts +2 -2
- package/kits/base/sdk/commands.d.ts +15 -0
- package/kits/base/sdk/multiplayer.d.ts +106 -2
- package/kits/base/sdk/multiplayer.js +422 -12
- package/kits/base/sdk/multiplayerProtocol.d.ts +54 -2
- package/kits/base/sdk/server/platformHandle.d.ts +54 -0
- package/kits/base/sdk/server/wrapper.d.ts +79 -1
- package/kits/base/sdk/server/wrapper.js +372 -0
- package/kits/base/sdk/transport.js +1 -0
- package/package.json +2 -2
package/dist/castle-host/host.js
CHANGED
|
@@ -40,6 +40,7 @@ const COMMAND_NAMES = [
|
|
|
40
40
|
"portal.info",
|
|
41
41
|
"haptics.play",
|
|
42
42
|
"multiplayer.getSession",
|
|
43
|
+
"multiplayer.joinDestination",
|
|
43
44
|
"voice.getState",
|
|
44
45
|
"voice.requestJoin",
|
|
45
46
|
"voice.leave",
|
|
@@ -142,6 +143,13 @@ function runCommand(ctx, command, params, caps, options) {
|
|
|
142
143
|
if (command === "multiplayer.getSession" && caps.getMultiplayerSession) {
|
|
143
144
|
return caps.getMultiplayerSession(multiplayerSessionRequest(params), ctx);
|
|
144
145
|
}
|
|
146
|
+
if (command === "multiplayer.joinDestination") {
|
|
147
|
+
const request = multiplayerDestinationRequest(params);
|
|
148
|
+
if (!caps.joinMultiplayerDestination) {
|
|
149
|
+
return Promise.resolve(unavailableDestinationResult());
|
|
150
|
+
}
|
|
151
|
+
return caps.joinMultiplayerDestination(request, ctx, options.signal);
|
|
152
|
+
}
|
|
145
153
|
if (isPlatformCommand(command)) {
|
|
146
154
|
return runPlatformCommand(ctx, command, params, caps);
|
|
147
155
|
}
|
|
@@ -263,6 +271,76 @@ function multiplayerSessionResult(value) {
|
|
|
263
271
|
}
|
|
264
272
|
return { status: "ok", url, nonce, sessionId, soloReason: null };
|
|
265
273
|
}
|
|
274
|
+
function multiplayerDestinationRequest(params) {
|
|
275
|
+
const routeId = asDestinationRouteId(params.routeId);
|
|
276
|
+
const slot = asBoundedText(params.slot, "slot", "multiplayer.joinDestination", 128, 128);
|
|
277
|
+
try {
|
|
278
|
+
encodeURIComponent(slot);
|
|
279
|
+
}
|
|
280
|
+
catch {
|
|
281
|
+
throw new HostCommandError("INVALID_ARGUMENT", "Castle command multiplayer.joinDestination requires slot to be valid text.", "multiplayer.joinDestination");
|
|
282
|
+
}
|
|
283
|
+
return {
|
|
284
|
+
routeId,
|
|
285
|
+
slot,
|
|
286
|
+
};
|
|
287
|
+
}
|
|
288
|
+
function asDestinationRouteId(value) {
|
|
289
|
+
const routeId = asString(value, "routeId", "multiplayer.joinDestination");
|
|
290
|
+
if (/^[A-Za-z0-9_-]{1,64}$/.test(routeId))
|
|
291
|
+
return routeId;
|
|
292
|
+
throw new HostCommandError("INVALID_ARGUMENT", "Castle command multiplayer.joinDestination requires a valid routeId.", "multiplayer.joinDestination");
|
|
293
|
+
}
|
|
294
|
+
function unavailableDestinationResult() {
|
|
295
|
+
return {
|
|
296
|
+
status: "unavailable",
|
|
297
|
+
url: null,
|
|
298
|
+
nonce: null,
|
|
299
|
+
sessionId: null,
|
|
300
|
+
audience: null,
|
|
301
|
+
};
|
|
302
|
+
}
|
|
303
|
+
export async function describeCauldronMultiplayerDestination(gql, ctx, routeId) {
|
|
304
|
+
const validatedRouteId = asDestinationRouteId(routeId);
|
|
305
|
+
const deckId = requireDeckId(ctx, "multiplayer.joinDestination");
|
|
306
|
+
const data = await graphql(gql, CAULDRON_MULTIPLAYER_DESTINATION_DESCRIPTION_QUERY, { deckId, routeId: validatedRouteId }, "multiplayer.joinDestination");
|
|
307
|
+
const description = data.describeCauldronMultiplayerDestination;
|
|
308
|
+
const access = asDestinationAudience(description?.access);
|
|
309
|
+
const configRevision = asOptionalString(description?.configRevision);
|
|
310
|
+
if (!configRevision) {
|
|
311
|
+
throw new HostCommandError("CAULDRON_DESTINATION_UNAVAILABLE", "Castle returned an invalid destination description.", "multiplayer.joinDestination");
|
|
312
|
+
}
|
|
313
|
+
return { access, configRevision };
|
|
314
|
+
}
|
|
315
|
+
export async function acquireCauldronMultiplayerDestination(gql, ctx, params, expectedConfigRevision) {
|
|
316
|
+
const request = multiplayerDestinationRequest({ ...params });
|
|
317
|
+
const deckId = requireDeckId(ctx, "multiplayer.joinDestination");
|
|
318
|
+
const data = await graphql(gql, CAULDRON_MULTIPLAYER_DESTINATION_SESSION_QUERY, {
|
|
319
|
+
deckId,
|
|
320
|
+
routeId: request.routeId,
|
|
321
|
+
slot: request.slot,
|
|
322
|
+
expectedConfigRevision: asString(expectedConfigRevision, "expectedConfigRevision", "multiplayer.joinDestination"),
|
|
323
|
+
partyId: ctx.partyId ?? null,
|
|
324
|
+
}, "multiplayer.joinDestination");
|
|
325
|
+
const session = data.getCauldronMultiplayerDestinationSession;
|
|
326
|
+
const sessionId = asOptionalString(session?.sessionId);
|
|
327
|
+
const url = asOptionalString(session?.url);
|
|
328
|
+
const nonce = asOptionalString(session?.nonce);
|
|
329
|
+
if (!sessionId || !url || !nonce)
|
|
330
|
+
return unavailableDestinationResult();
|
|
331
|
+
return {
|
|
332
|
+
status: "ok",
|
|
333
|
+
sessionId,
|
|
334
|
+
url,
|
|
335
|
+
nonce,
|
|
336
|
+
audience: asDestinationAudience(session?.audience),
|
|
337
|
+
};
|
|
338
|
+
}
|
|
339
|
+
function asDestinationAudience(value) {
|
|
340
|
+
if (value === "player" || value === "party" || value === "public")
|
|
341
|
+
return value;
|
|
342
|
+
throw new HostCommandError("CAULDRON_DESTINATION_UNAVAILABLE", "Castle returned an invalid destination audience.", "multiplayer.joinDestination");
|
|
343
|
+
}
|
|
266
344
|
// A reason this SDK does not know reads as the catch-all: the deck still
|
|
267
345
|
// learns it is solo, just not why. This does not cover a ghost older than the
|
|
268
346
|
// field: that rejects the whole query as invalid, so ghost deploys before any
|
|
@@ -2293,6 +2371,36 @@ const CAULDRON_MULTIPLAYER_SESSION_QUERY = `
|
|
|
2293
2371
|
}
|
|
2294
2372
|
}
|
|
2295
2373
|
`;
|
|
2374
|
+
const CAULDRON_MULTIPLAYER_DESTINATION_DESCRIPTION_QUERY = `
|
|
2375
|
+
query CastleCauldronMultiplayerDestinationDescription($deckId: ID!, $routeId: String!) {
|
|
2376
|
+
describeCauldronMultiplayerDestination(deckId: $deckId, routeId: $routeId) {
|
|
2377
|
+
access
|
|
2378
|
+
configRevision
|
|
2379
|
+
}
|
|
2380
|
+
}
|
|
2381
|
+
`;
|
|
2382
|
+
const CAULDRON_MULTIPLAYER_DESTINATION_SESSION_QUERY = `
|
|
2383
|
+
query CastleCauldronMultiplayerDestinationSession(
|
|
2384
|
+
$deckId: ID!
|
|
2385
|
+
$routeId: String!
|
|
2386
|
+
$slot: String!
|
|
2387
|
+
$expectedConfigRevision: String!
|
|
2388
|
+
$partyId: ID
|
|
2389
|
+
) {
|
|
2390
|
+
getCauldronMultiplayerDestinationSession(
|
|
2391
|
+
deckId: $deckId
|
|
2392
|
+
routeId: $routeId
|
|
2393
|
+
slot: $slot
|
|
2394
|
+
expectedConfigRevision: $expectedConfigRevision
|
|
2395
|
+
partyId: $partyId
|
|
2396
|
+
) {
|
|
2397
|
+
sessionId
|
|
2398
|
+
url
|
|
2399
|
+
nonce
|
|
2400
|
+
audience
|
|
2401
|
+
}
|
|
2402
|
+
}
|
|
2403
|
+
`;
|
|
2296
2404
|
const CAULDRON_STORAGE_GET_QUERY = `
|
|
2297
2405
|
query CastleCauldronStorageGet(
|
|
2298
2406
|
$deckId: ID!
|
package/dist/castleJson.d.ts
CHANGED
|
@@ -21,11 +21,13 @@ export interface CastleJson {
|
|
|
21
21
|
agent?: {
|
|
22
22
|
plan?: 'on' | 'off';
|
|
23
23
|
askCalls?: 'on' | 'off';
|
|
24
|
+
playtest?: 'on' | 'off';
|
|
24
25
|
};
|
|
25
26
|
server?: {
|
|
26
27
|
main?: string;
|
|
27
28
|
tickRate?: number;
|
|
28
29
|
maxPlayers?: number;
|
|
30
|
+
destinations?: ServerDestinationConfig[];
|
|
29
31
|
};
|
|
30
32
|
voice?: {
|
|
31
33
|
enabled?: boolean;
|
|
@@ -39,11 +41,21 @@ export declare const DEFAULT_SERVER_TICK_RATE = 20;
|
|
|
39
41
|
export declare const DEFAULT_SERVER_MAX_PLAYERS = 8;
|
|
40
42
|
export declare const SERVER_TICK_RATE_CAP = 30;
|
|
41
43
|
export declare const SERVER_MAX_PLAYERS_CAP = 24;
|
|
44
|
+
export declare const SERVER_DESTINATIONS_CAP = 16;
|
|
45
|
+
export interface ServerDestinationConfig {
|
|
46
|
+
routeId: string;
|
|
47
|
+
access: 'player' | 'party' | 'public';
|
|
48
|
+
selection: 'exact' | 'find';
|
|
49
|
+
persistence: 'transient' | 'world';
|
|
50
|
+
characters?: 'shared';
|
|
51
|
+
maxPlayers: number;
|
|
52
|
+
}
|
|
42
53
|
export interface ResolvedServerConfig {
|
|
43
54
|
entry: string;
|
|
44
55
|
tickRate: number;
|
|
45
56
|
maxPlayers: number;
|
|
46
57
|
voiceEnabled: boolean;
|
|
58
|
+
destinations?: ServerDestinationConfig[];
|
|
47
59
|
}
|
|
48
60
|
export declare function resolveServerConfig(dir: string): ResolvedServerConfig | null;
|
|
49
61
|
export declare function deckStarterScene(dir: string): string;
|
package/dist/castleJson.js
CHANGED
|
@@ -30,6 +30,7 @@ export const DEFAULT_SERVER_TICK_RATE = 20;
|
|
|
30
30
|
export const DEFAULT_SERVER_MAX_PLAYERS = 8;
|
|
31
31
|
export const SERVER_TICK_RATE_CAP = 30;
|
|
32
32
|
export const SERVER_MAX_PLAYERS_CAP = 24;
|
|
33
|
+
export const SERVER_DESTINATIONS_CAP = 16;
|
|
33
34
|
// A deck may keep its source under `code/`, so both roots are candidates.
|
|
34
35
|
const DEFAULT_SERVER_ENTRIES = [
|
|
35
36
|
'server/index.js',
|
|
@@ -52,8 +53,65 @@ export function resolveServerConfig(dir) {
|
|
|
52
53
|
tickRate: clampNumber(server?.tickRate, DEFAULT_SERVER_TICK_RATE, 0, SERVER_TICK_RATE_CAP),
|
|
53
54
|
maxPlayers: Math.floor(clampNumber(server?.maxPlayers, DEFAULT_SERVER_MAX_PLAYERS, 1, SERVER_MAX_PLAYERS_CAP)),
|
|
54
55
|
voiceEnabled: castleJson?.voice?.enabled !== false,
|
|
56
|
+
...(server?.destinations === undefined
|
|
57
|
+
? {}
|
|
58
|
+
: { destinations: validateServerDestinations(server.destinations) }),
|
|
55
59
|
};
|
|
56
60
|
}
|
|
61
|
+
function validateServerDestinations(value) {
|
|
62
|
+
if (!Array.isArray(value) || value.length > SERVER_DESTINATIONS_CAP) {
|
|
63
|
+
throw new Error(`server.destinations must be an array of at most ${SERVER_DESTINATIONS_CAP} routes.`);
|
|
64
|
+
}
|
|
65
|
+
const routeIds = new Set();
|
|
66
|
+
return value.map((candidate, index) => {
|
|
67
|
+
if (!candidate || typeof candidate !== 'object' || Array.isArray(candidate)) {
|
|
68
|
+
throw invalidDestination(index, 'must be an object');
|
|
69
|
+
}
|
|
70
|
+
const route = candidate;
|
|
71
|
+
const routeId = route.routeId;
|
|
72
|
+
if (typeof routeId !== 'string' || !/^[A-Za-z0-9_-]{1,64}$/.test(routeId)) {
|
|
73
|
+
throw invalidDestination(index, 'routeId must match [A-Za-z0-9_-] and be 1 through 64 characters');
|
|
74
|
+
}
|
|
75
|
+
if (routeIds.has(routeId))
|
|
76
|
+
throw invalidDestination(index, `routeId "${routeId}" is duplicated`);
|
|
77
|
+
routeIds.add(routeId);
|
|
78
|
+
if (route.access !== 'player' && route.access !== 'party' && route.access !== 'public') {
|
|
79
|
+
throw invalidDestination(index, 'access must be player, party, or public');
|
|
80
|
+
}
|
|
81
|
+
if (route.selection !== 'exact' && route.selection !== 'find') {
|
|
82
|
+
throw invalidDestination(index, 'selection must be exact or find');
|
|
83
|
+
}
|
|
84
|
+
if (route.persistence !== 'transient' && route.persistence !== 'world') {
|
|
85
|
+
throw invalidDestination(index, 'persistence must be transient or world');
|
|
86
|
+
}
|
|
87
|
+
if (route.persistence === 'world' && route.selection === 'find') {
|
|
88
|
+
throw invalidDestination(index, 'persistent worlds require selection "exact"');
|
|
89
|
+
}
|
|
90
|
+
if (route.characters !== undefined && route.characters !== 'shared') {
|
|
91
|
+
throw invalidDestination(index, 'characters must be shared when present');
|
|
92
|
+
}
|
|
93
|
+
if (route.characters === 'shared' &&
|
|
94
|
+
(route.persistence !== 'world' || route.selection !== 'exact')) {
|
|
95
|
+
throw invalidDestination(index, 'shared characters require selection "exact" and persistence "world"');
|
|
96
|
+
}
|
|
97
|
+
if (!Number.isInteger(route.maxPlayers) ||
|
|
98
|
+
route.maxPlayers < 1 ||
|
|
99
|
+
route.maxPlayers > SERVER_MAX_PLAYERS_CAP) {
|
|
100
|
+
throw invalidDestination(index, `maxPlayers must be an integer from 1 through ${SERVER_MAX_PLAYERS_CAP}`);
|
|
101
|
+
}
|
|
102
|
+
return {
|
|
103
|
+
routeId,
|
|
104
|
+
access: route.access,
|
|
105
|
+
selection: route.selection,
|
|
106
|
+
persistence: route.persistence,
|
|
107
|
+
...(route.characters === 'shared' ? { characters: 'shared' } : {}),
|
|
108
|
+
maxPlayers: route.maxPlayers,
|
|
109
|
+
};
|
|
110
|
+
});
|
|
111
|
+
}
|
|
112
|
+
function invalidDestination(index, message) {
|
|
113
|
+
return new Error(`server.destinations[${index}] ${message}.`);
|
|
114
|
+
}
|
|
57
115
|
function isSafeServerEntry(dir, entry) {
|
|
58
116
|
if (!/\.(?:js|ts|mjs)$/.test(entry))
|
|
59
117
|
return false;
|
|
@@ -0,0 +1,261 @@
|
|
|
1
|
+
import { type GitResult } from './gitRemote.js';
|
|
2
|
+
export type CommitReason = 'turn' | 'task' | 'leave' | 'manual' | 'sync';
|
|
3
|
+
export declare const COMMIT_REASONS: readonly CommitReason[];
|
|
4
|
+
export declare const AGENT_TRAILER_KEY = "Castle-Agent";
|
|
5
|
+
export declare const EXIT_OK = 0;
|
|
6
|
+
export declare const EXIT_ERROR = 1;
|
|
7
|
+
/** Not a sandbox, or a deck `git attach` never set up: nothing was done. */
|
|
8
|
+
export declare const EXIT_NOT_ENABLED = 2;
|
|
9
|
+
/** A merge with the remote is waiting on the agent; nothing was committed. */
|
|
10
|
+
export declare const EXIT_CONFLICT = 3;
|
|
11
|
+
export declare class CloudGitError extends Error {
|
|
12
|
+
readonly exitCode: number;
|
|
13
|
+
constructor(message: string, exitCode?: number);
|
|
14
|
+
}
|
|
15
|
+
export declare const CLOUD_EXCLUDES: string[];
|
|
16
|
+
export declare const LOOSE_OBJECT_LIMIT = 200;
|
|
17
|
+
export declare const STALE_GIT_LOCK_MS = 60000;
|
|
18
|
+
export declare const DECK_LOCK_FILE: string;
|
|
19
|
+
/** Written by `git sync` on a conflict; the serve turns it into an agent turn. */
|
|
20
|
+
export declare const CONFLICT_MARKER_FILE: string;
|
|
21
|
+
/** Written by `git attach` when it took the remote's version over a differing cloud copy. */
|
|
22
|
+
export declare const ADOPTED_MARKER_FILE: string;
|
|
23
|
+
/** Every marker the serve turns into an agent turn. */
|
|
24
|
+
export declare const AGENT_MARKER_FILES: readonly string[];
|
|
25
|
+
/** The serve's note that task agents (or the router) are working in the deck; see deckBusy. */
|
|
26
|
+
export declare const BUSY_FILE: string;
|
|
27
|
+
/** The remote has (or may have) work that waits to be merged until the deck is idle. */
|
|
28
|
+
export declare const SYNC_PENDING_FILE: string;
|
|
29
|
+
/** The conflicted merge in progress, in .git beside MERGE_HEAD. */
|
|
30
|
+
export declare const MERGE_STATE_FILE = "castle-merge.json";
|
|
31
|
+
/**
|
|
32
|
+
* Where `git attach` saves the cloud copy's files before taking the remote's version: one
|
|
33
|
+
* directory per attach. Under .git so no name a deck file may have (`*.pem`, `credentials`) is
|
|
34
|
+
* refused as a credential by the checkpoint, and never part of the working tree.
|
|
35
|
+
*/
|
|
36
|
+
export declare const ATTACH_BACKUPS_DIR: string;
|
|
37
|
+
/** Backups written by an attach whose agent notice has not been written yet. */
|
|
38
|
+
export declare const ADOPT_PENDING_FILE: string;
|
|
39
|
+
/** A leave commit found a merge waiting: the edits on disk stay uncommitted until it concludes. */
|
|
40
|
+
export declare const LEAVE_PENDING_FILE: string;
|
|
41
|
+
export declare const ATTACH_BACKUP_MAX_AGE_MS: number;
|
|
42
|
+
export declare const ATTACH_BACKUP_KEEP = 10;
|
|
43
|
+
export declare const DEADLINE_ENV = "CASTLE_GIT_DEADLINE";
|
|
44
|
+
export declare const AGENT_ROLE_ENV = "CASTLE_AGENT_ROLE";
|
|
45
|
+
export interface GitRunOptions {
|
|
46
|
+
timeoutMs?: number;
|
|
47
|
+
/** A scratch index instead of the repo's own. */
|
|
48
|
+
indexFile?: string;
|
|
49
|
+
}
|
|
50
|
+
export interface CloudGitDeps {
|
|
51
|
+
git: (args: string[], cwd: string, opts?: GitRunOptions) => GitResult;
|
|
52
|
+
/** The signed-in user, from the sandbox-scoped `me`. */
|
|
53
|
+
whoAmI: () => Promise<{
|
|
54
|
+
userId: string;
|
|
55
|
+
username: string;
|
|
56
|
+
} | null>;
|
|
57
|
+
env: NodeJS.ProcessEnv;
|
|
58
|
+
log: (message: string) => void;
|
|
59
|
+
warn: (message: string) => void;
|
|
60
|
+
now: () => number;
|
|
61
|
+
sleep: (ms: number) => void;
|
|
62
|
+
pid: number;
|
|
63
|
+
hostname: () => string;
|
|
64
|
+
isAlive: (pid: number) => boolean;
|
|
65
|
+
/** Whether this command has been asked to stop (SIGTERM). Lets pending signals in first. */
|
|
66
|
+
stopRequested: () => Promise<boolean>;
|
|
67
|
+
}
|
|
68
|
+
/** A process's start time (in clock ticks since boot, from /proc), which tells a reused pid apart. */
|
|
69
|
+
export declare function processStartTime(pid: number): string | null;
|
|
70
|
+
export declare function cloudGitRunner(baseEnv?: NodeJS.ProcessEnv): CloudGitDeps['git'];
|
|
71
|
+
export declare function defaultCloudGitDeps(whoAmI: CloudGitDeps['whoAmI']): CloudGitDeps;
|
|
72
|
+
interface Ctx {
|
|
73
|
+
dir: string;
|
|
74
|
+
deps: CloudGitDeps;
|
|
75
|
+
startedAt: number;
|
|
76
|
+
/** Epoch ms by which the command must be done (DEADLINE_ENV); none when not set. */
|
|
77
|
+
deadline?: number;
|
|
78
|
+
}
|
|
79
|
+
export declare function mergeInProgress(dir: string): boolean;
|
|
80
|
+
export declare function isSandboxEnv(env: NodeJS.ProcessEnv): boolean;
|
|
81
|
+
/** Whether `git attach` set this deck up: its own `.git` directory, marked in its config. */
|
|
82
|
+
export declare function isAttached(dir: string, git?: CloudGitDeps['git']): boolean;
|
|
83
|
+
/**
|
|
84
|
+
* The serve's switch: the gate env castle-www sets on the serve, AND a deck that attach
|
|
85
|
+
* actually set up. An attach that failed leaves the deck on the old version store.
|
|
86
|
+
*/
|
|
87
|
+
export declare function cloudGitMode(dir: string, env?: NodeJS.ProcessEnv): boolean;
|
|
88
|
+
/** cloudGitMode without blocking the caller's event loop. */
|
|
89
|
+
export declare function cloudGitModeAsync(dir: string, env?: NodeJS.ProcessEnv): Promise<boolean>;
|
|
90
|
+
export declare function deckBusy(ctx: {
|
|
91
|
+
dir: string;
|
|
92
|
+
deps: Pick<CloudGitDeps, 'hostname' | 'isAlive'>;
|
|
93
|
+
}): boolean;
|
|
94
|
+
export declare function deckTasksBusy(ctx: {
|
|
95
|
+
dir: string;
|
|
96
|
+
deps: Pick<CloudGitDeps, 'hostname' | 'isAlive'>;
|
|
97
|
+
}): boolean;
|
|
98
|
+
/** The serve's side of deckBusy. */
|
|
99
|
+
export declare function setDeckBusy(dir: string, busy: boolean, opts?: {
|
|
100
|
+
tasks: boolean;
|
|
101
|
+
}): void;
|
|
102
|
+
/**
|
|
103
|
+
* An exclusive lock on `file`, returning its release. The lock is created exclusively (O_EXCL),
|
|
104
|
+
* names its holder (pid, container hostname, process start time) and a random token, and is
|
|
105
|
+
* released only by the holder whose token it still carries. A stale one is taken over through
|
|
106
|
+
* takeOverStaleLock. Until its content is written a lock reads as unreadable, which a waiter
|
|
107
|
+
* judges only by age -- a holder is not taken over in that instant.
|
|
108
|
+
*/
|
|
109
|
+
export declare function acquireLockFile(file: string, deps: CloudGitDeps, waitMs?: number): () => void;
|
|
110
|
+
export declare function clearStaleGitLocks(ctx: {
|
|
111
|
+
dir: string;
|
|
112
|
+
deps: Pick<CloudGitDeps, 'now' | 'warn'>;
|
|
113
|
+
}): string[];
|
|
114
|
+
export declare function noreplyEmail(userId: string, username: string): string;
|
|
115
|
+
/** A username as a git author name: no control characters or angle brackets, never empty. */
|
|
116
|
+
export declare function safeAuthorName(username: string): string;
|
|
117
|
+
/** How a conflicted path was left: markers for the agent, or the other computer's side taken. */
|
|
118
|
+
export type ConflictResolution = 'markers' | 'took-laptop' | 'laptop-deleted' | 'manual';
|
|
119
|
+
export interface ConflictedFile {
|
|
120
|
+
path: string;
|
|
121
|
+
/** Blob ids of the stages git left: base (1), this sandbox (2), the other computer (3). */
|
|
122
|
+
stages: {
|
|
123
|
+
base?: string;
|
|
124
|
+
ours?: string;
|
|
125
|
+
theirs?: string;
|
|
126
|
+
};
|
|
127
|
+
kind: 'text' | 'binary' | 'modify-delete';
|
|
128
|
+
resolution: ConflictResolution;
|
|
129
|
+
}
|
|
130
|
+
/** `.git/castle-merge.json`: the conflicted merge in progress. */
|
|
131
|
+
export interface MergeState {
|
|
132
|
+
at: string;
|
|
133
|
+
/** This sandbox's commit when the merge started. */
|
|
134
|
+
head: string;
|
|
135
|
+
mergeHead: string;
|
|
136
|
+
files: ConflictedFile[];
|
|
137
|
+
instruction: string;
|
|
138
|
+
}
|
|
139
|
+
export declare function readMergeState(dir: string): MergeState | null;
|
|
140
|
+
export interface ConflictReport {
|
|
141
|
+
at: string;
|
|
142
|
+
files: string[];
|
|
143
|
+
theirs: string[];
|
|
144
|
+
ours: string[];
|
|
145
|
+
instruction: string;
|
|
146
|
+
}
|
|
147
|
+
export interface ConflictSummary {
|
|
148
|
+
files: Pick<ConflictedFile, 'path' | 'resolution'>[];
|
|
149
|
+
theirs: string[];
|
|
150
|
+
ours: string[];
|
|
151
|
+
/** This sandbox's commit when the merge started, where its version of every file is. */
|
|
152
|
+
head: string;
|
|
153
|
+
}
|
|
154
|
+
export declare function conflictInstruction(summary: ConflictSummary): string;
|
|
155
|
+
export interface CommitOptions {
|
|
156
|
+
message?: string;
|
|
157
|
+
reason?: CommitReason;
|
|
158
|
+
paths?: string[];
|
|
159
|
+
/** Conclude the merge in progress (the only commit that may while one is). */
|
|
160
|
+
resolve?: boolean;
|
|
161
|
+
}
|
|
162
|
+
export interface CommitOutcome {
|
|
163
|
+
sha: string | null;
|
|
164
|
+
}
|
|
165
|
+
export declare function packIfNeeded(ctx: Ctx): boolean;
|
|
166
|
+
export interface LeavePending {
|
|
167
|
+
at: string;
|
|
168
|
+
/** What `git status` showed as changed when the user left. */
|
|
169
|
+
paths: string[];
|
|
170
|
+
}
|
|
171
|
+
export declare function readLeavePending(dir: string): LeavePending | null;
|
|
172
|
+
/**
|
|
173
|
+
* How a sync may touch the working tree: `full` fetches and merges castle/main into it;
|
|
174
|
+
* `push-only` (mid-task, or a commit of named paths) pushes main only as a fast-forward and
|
|
175
|
+
* otherwise leaves the remote's work for the board-idle commit to merge.
|
|
176
|
+
*/
|
|
177
|
+
export type SyncMode = 'full' | 'push-only';
|
|
178
|
+
export interface SyncOutcome {
|
|
179
|
+
/** What happened with castle/main. `deferred`: it has work that waits for the deck to be idle. */
|
|
180
|
+
merge: 'none' | 'fast-forward' | 'merged' | 'conflict' | 'seeded' | 'deferred';
|
|
181
|
+
pushed: boolean;
|
|
182
|
+
}
|
|
183
|
+
export interface DraftDifference {
|
|
184
|
+
path: string;
|
|
185
|
+
/** How the cloud copy differs from castle/main: `deleted` means it lacks a file the remote has. */
|
|
186
|
+
change: 'modified' | 'added' | 'deleted';
|
|
187
|
+
}
|
|
188
|
+
export declare function adoptedInstruction(backupDirs: string[]): string;
|
|
189
|
+
export interface AdoptOutcome {
|
|
190
|
+
/** Where the cloud copy's differing files were saved; null when it matched the remote. */
|
|
191
|
+
backup: string | null;
|
|
192
|
+
}
|
|
193
|
+
interface SyncAfter {
|
|
194
|
+
sync: SyncOutcome | null;
|
|
195
|
+
/** Set when the commit landed but the sync after it failed (the next one retries). */
|
|
196
|
+
syncError?: string;
|
|
197
|
+
}
|
|
198
|
+
export type CommitCommandOutcome = CommitOutcome & SyncAfter;
|
|
199
|
+
/**
|
|
200
|
+
* `castle-web commit`: commit, then sync. With named paths, or while the deck is busy, the
|
|
201
|
+
* sync only pushes (see SyncMode). The serve's commits skip the network when they committed
|
|
202
|
+
* nothing and there is nothing to push and no laptop push waiting.
|
|
203
|
+
*/
|
|
204
|
+
export declare function cloudCommit(dir: string, opts: CommitOptions, deps: CloudGitDeps): Promise<CommitCommandOutcome>;
|
|
205
|
+
/**
|
|
206
|
+
* `castle-web git sync`: commit work in progress, bring in castle/main, push. While the deck
|
|
207
|
+
* is busy it only notes that a sync is waiting: the board-idle commit does it.
|
|
208
|
+
*/
|
|
209
|
+
export declare function cloudSync(dir: string, deps: CloudGitDeps): Promise<SyncOutcome>;
|
|
210
|
+
export type RestoreOutcome = CommitOutcome & SyncAfter;
|
|
211
|
+
/**
|
|
212
|
+
* Restore the deck to an earlier commit as a NEW commit on top: history is never rewritten,
|
|
213
|
+
* so the restore can itself be restored away. Work in progress is committed first, so
|
|
214
|
+
* nothing on disk is lost by restoring.
|
|
215
|
+
*/
|
|
216
|
+
export declare function cloudRestore(dir: string, target: string, deps: CloudGitDeps): Promise<RestoreOutcome>;
|
|
217
|
+
export declare function writeCloudExcludes(dir: string): void;
|
|
218
|
+
export interface AttachOutcome {
|
|
219
|
+
repo: 'existing' | 'created';
|
|
220
|
+
outcome: 'seeded' | 'adopted' | 'synced';
|
|
221
|
+
sync?: SyncOutcome;
|
|
222
|
+
/** For `adopted`: where the cloud copy's differing files were saved, if any differed. */
|
|
223
|
+
backup?: string;
|
|
224
|
+
}
|
|
225
|
+
/** `castle-web git attach <dir> --remote <url>`. */
|
|
226
|
+
export declare function cloudAttach(dir: string, remoteUrl: string, deps: CloudGitDeps): Promise<AttachOutcome>;
|
|
227
|
+
export type GitChangeKind = 'added' | 'changed' | 'deleted';
|
|
228
|
+
export interface GitVersionEntry {
|
|
229
|
+
id: string;
|
|
230
|
+
parentId: string | null;
|
|
231
|
+
createdAt: string;
|
|
232
|
+
message: string;
|
|
233
|
+
author: string;
|
|
234
|
+
/** The Castle-Agent trailer's value when an agent made the commit. */
|
|
235
|
+
agent: string | null;
|
|
236
|
+
changes: {
|
|
237
|
+
path: string;
|
|
238
|
+
kind: GitChangeKind;
|
|
239
|
+
}[];
|
|
240
|
+
later: false;
|
|
241
|
+
}
|
|
242
|
+
export declare function parseGitLog(output: string): GitVersionEntry[];
|
|
243
|
+
export declare function parseStatus(output: string): {
|
|
244
|
+
path: string;
|
|
245
|
+
kind: GitChangeKind;
|
|
246
|
+
}[];
|
|
247
|
+
/**
|
|
248
|
+
* The Versions panel's picture with git on: the log and `git status` as pending. Async, since
|
|
249
|
+
* the IDE server's event loop must not wait on git, and without optional locks, so a panel
|
|
250
|
+
* refresh never holds the index lock a commit needs.
|
|
251
|
+
*/
|
|
252
|
+
export declare function gitVersionHistory(dir: string, env?: NodeJS.ProcessEnv): Promise<{
|
|
253
|
+
versions: GitVersionEntry[];
|
|
254
|
+
pending: {
|
|
255
|
+
path: string;
|
|
256
|
+
kind: GitChangeKind;
|
|
257
|
+
}[];
|
|
258
|
+
}>;
|
|
259
|
+
export declare function printGitLog(dir: string, from?: string, git?: CloudGitDeps['git']): void;
|
|
260
|
+
export declare function printGitShow(dir: string, target: string, git?: CloudGitDeps['git']): void;
|
|
261
|
+
export {};
|