castle-web-cli 0.4.214 → 0.4.216

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.
@@ -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;
@@ -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;
@@ -1,4 +1,5 @@
1
1
  import { type GitResult } from './gitRemote.js';
2
+ import type { GitMirrorState } from './api.js';
2
3
  export type CommitReason = 'turn' | 'task' | 'leave' | 'manual' | 'sync';
3
4
  export declare const COMMIT_REASONS: readonly CommitReason[];
4
5
  export declare const AGENT_TRAILER_KEY = "Castle-Agent";
@@ -8,6 +9,13 @@ export declare const EXIT_ERROR = 1;
8
9
  export declare const EXIT_NOT_ENABLED = 2;
9
10
  /** A merge with the remote is waiting on the agent; nothing was committed. */
10
11
  export declare const EXIT_CONFLICT = 3;
12
+ /**
13
+ * GIT_HISTORY_UNAVAILABLE: the deck's refs name commits whose objects are gone (a cold resume,
14
+ * whose checkpoint carries no `.git/objects`) and neither the Castle remote, the S3 mirror nor
15
+ * the snapshot bundle could bring them back. Nothing was changed; the next command retries.
16
+ */
17
+ export declare const EXIT_HISTORY_UNAVAILABLE = 4;
18
+ export declare const HISTORY_UNAVAILABLE_CODE = "GIT_HISTORY_UNAVAILABLE";
11
19
  export declare class CloudGitError extends Error {
12
20
  readonly exitCode: number;
13
21
  constructor(message: string, exitCode?: number);
@@ -20,6 +28,11 @@ export declare const DECK_LOCK_FILE: string;
20
28
  export declare const CONFLICT_MARKER_FILE: string;
21
29
  /** Written by `git attach` when it took the remote's version over a differing cloud copy. */
22
30
  export declare const ADOPTED_MARKER_FILE: string;
31
+ /** Written when a rehydrate gave up local commits nobody had (see recoverLostHistory). */
32
+ export declare const HISTORY_RECOVERED_FILE: string;
33
+ export declare const RECOVERED_COMMIT_MESSAGE = "Edits restored after lost history";
34
+ /** Written with it, once: the notice and instruction the serve turns into an agent turn. */
35
+ export declare const HISTORY_LOST_MARKER_FILE: string;
23
36
  /** Every marker the serve turns into an agent turn. */
24
37
  export declare const AGENT_MARKER_FILES: readonly string[];
25
38
  /** The serve's note that task agents (or the router) are working in the deck; see deckBusy. */
@@ -41,10 +54,22 @@ export declare const LEAVE_PENDING_FILE: string;
41
54
  export declare const ATTACH_BACKUP_MAX_AGE_MS: number;
42
55
  export declare const ATTACH_BACKUP_KEEP = 10;
43
56
  export declare const DEADLINE_ENV = "CASTLE_GIT_DEADLINE";
57
+ export declare const AGENT_ROLE_ENV = "CASTLE_AGENT_ROLE";
44
58
  export interface GitRunOptions {
45
59
  timeoutMs?: number;
46
60
  /** A scratch index instead of the repo's own. */
47
61
  indexFile?: string;
62
+ /** Extra environment for this one command (on top of cloudGitEnv's). */
63
+ env?: Record<string, string>;
64
+ /** Written to the command's stdin. */
65
+ input?: string;
66
+ }
67
+ export interface DownloadOptions {
68
+ timeoutMs: number;
69
+ /** The exact size the file must have (the download stops once past it); null: not checked. */
70
+ bytes: number | null;
71
+ /** Hex SHA-256 the file must have; null: not checked. */
72
+ sha256: string | null;
48
73
  }
49
74
  export interface CloudGitDeps {
50
75
  git: (args: string[], cwd: string, opts?: GitRunOptions) => GitResult;
@@ -63,11 +88,26 @@ export interface CloudGitDeps {
63
88
  isAlive: (pid: number) => boolean;
64
89
  /** Whether this command has been asked to stop (SIGTERM). Lets pending signals in first. */
65
90
  stopRequested: () => Promise<boolean>;
91
+ /** Ghost's `gitMirrorState` for a deck. Absent: never asked (the floor stays castle/main). */
92
+ mirrorState?: (deckId: string, opts: {
93
+ includeBundles: boolean;
94
+ timeoutMs: number;
95
+ }) => Promise<GitMirrorState | null>;
96
+ /** Fetches one mirror bundle to `dest`, verifying its size and sha256; throws otherwise. */
97
+ download?: (url: string, dest: string, opts: DownloadOptions) => Promise<void>;
98
+ /** Starts a detached `castle-web git rehydrate` for a deck (spawnDetachedRehydrate). */
99
+ spawnRehydrate?: (dir: string, env: NodeJS.ProcessEnv) => void;
66
100
  }
67
101
  /** A process's start time (in clock ticks since boot, from /proc), which tells a reused pid apart. */
68
102
  export declare function processStartTime(pid: number): string | null;
69
103
  export declare function cloudGitRunner(baseEnv?: NodeJS.ProcessEnv): CloudGitDeps['git'];
70
- export declare function defaultCloudGitDeps(whoAmI: CloudGitDeps['whoAmI']): CloudGitDeps;
104
+ /**
105
+ * Downloads `url` to `dest`, checking its exact size and SHA-256 where the mirror recorded them
106
+ * (a bundle listed by an older mirror run has neither); removes `dest` on any failure.
107
+ */
108
+ export declare const UNSIZED_DOWNLOAD_MAX_BYTES: number;
109
+ export declare function downloadVerified(url: string, dest: string, opts: DownloadOptions): Promise<void>;
110
+ export declare function defaultCloudGitDeps(whoAmI: CloudGitDeps['whoAmI'], extra?: Pick<CloudGitDeps, 'mirrorState'>): CloudGitDeps;
71
111
  interface Ctx {
72
112
  dir: string;
73
113
  deps: CloudGitDeps;
@@ -75,7 +115,10 @@ interface Ctx {
75
115
  /** Epoch ms by which the command must be done (DEADLINE_ENV); none when not set. */
76
116
  deadline?: number;
77
117
  }
118
+ export declare function repairGitSkeleton(dir: string): void;
78
119
  export declare function mergeInProgress(dir: string): boolean;
120
+ /** A merge (or a recovered one's conflict markers) waits on the agent: only `--resolve` commits. */
121
+ export declare function mergeWaiting(dir: string): boolean;
79
122
  export declare function isSandboxEnv(env: NodeJS.ProcessEnv): boolean;
80
123
  /** Whether `git attach` set this deck up: its own `.git` directory, marked in its config. */
81
124
  export declare function isAttached(dir: string, git?: CloudGitDeps['git']): boolean;
@@ -90,8 +133,14 @@ export declare function deckBusy(ctx: {
90
133
  dir: string;
91
134
  deps: Pick<CloudGitDeps, 'hostname' | 'isAlive'>;
92
135
  }): boolean;
136
+ export declare function deckTasksBusy(ctx: {
137
+ dir: string;
138
+ deps: Pick<CloudGitDeps, 'hostname' | 'isAlive'>;
139
+ }): boolean;
93
140
  /** The serve's side of deckBusy. */
94
- export declare function setDeckBusy(dir: string, busy: boolean): void;
141
+ export declare function setDeckBusy(dir: string, busy: boolean, opts?: {
142
+ tasks: boolean;
143
+ }): void;
95
144
  /**
96
145
  * An exclusive lock on `file`, returning its release. The lock is created exclusively (O_EXCL),
97
146
  * names its holder (pid, container hostname, process start time) and a random token, and is
@@ -128,6 +177,11 @@ export interface MergeState {
128
177
  mergeHead: string;
129
178
  files: ConflictedFile[];
130
179
  instruction: string;
180
+ /**
181
+ * Left by a rehydrate that gave up lost history mid-merge: no MERGE_HEAD any more, but the
182
+ * files still have markers, and the next commit must be a `--resolve`.
183
+ */
184
+ recovered?: boolean;
131
185
  }
132
186
  export declare function readMergeState(dir: string): MergeState | null;
133
187
  export interface ConflictReport {
@@ -156,6 +210,63 @@ export interface CommitOutcome {
156
210
  sha: string | null;
157
211
  }
158
212
  export declare function packIfNeeded(ctx: Ctx): boolean;
213
+ /** Every object the deck's local state reaches that the S3 mirror is not known to have. */
214
+ export declare const SNAPSHOT_BUNDLE_FILE: string;
215
+ export declare const SNAPSHOT_KEY_FILE: string;
216
+ /** main as ghost last reported the deck's S3 mirror had it: the bundle's floor. Only moves forward. */
217
+ export declare const MIRRORED_REF = "refs/castle/mirrored";
218
+ /**
219
+ * One rehydrate at a time. Not named `*.lock`: clearStaleGitLocks removes those at the top of
220
+ * .git after a minute, and a rehydrate runs far longer than that.
221
+ */
222
+ export declare const REHYDRATE_LOCK_FILE: string;
223
+ /** Failed rehydrates and when the next background one may start (exponential backoff). */
224
+ export declare const REHYDRATE_STATE_FILE: string;
225
+ /** Where a background rehydrate writes its output. */
226
+ export declare const REHYDRATE_LOG_FILE: string;
227
+ /** `off` stops commands from starting a background rehydrate (tests). */
228
+ export declare const BACKGROUND_REHYDRATE_ENV = "CASTLE_GIT_BACKGROUND_REHYDRATE";
229
+ export declare const SNAPSHOT_CAP_BYTES: number;
230
+ /** A smaller cap, for tests. */
231
+ export declare const SNAPSHOT_CAP_ENV = "CASTLE_GIT_SNAPSHOT_CAP_BYTES";
232
+ /** Whether the deck's history is being rebuilt: refs name objects that are not here. */
233
+ export declare function historyLoading(dir: string, git?: CloudGitDeps['git']): boolean;
234
+ interface RehydrateState {
235
+ failures: number;
236
+ lastFailureAt: string;
237
+ nextAttemptAt: number;
238
+ lastError: string;
239
+ /** The container (and its boot) the failures happened in: another's backoff does not apply. */
240
+ host: string;
241
+ bootId: string | null;
242
+ }
243
+ /** This container's rehydrate backoff; state another host (or boot) wrote does not count. */
244
+ export declare function readRehydrateState(dir: string, host?: string): RehydrateState | null;
245
+ /** Starts `castle-web git rehydrate` for the deck in its own session, its output to REHYDRATE_LOG_FILE. */
246
+ export declare function spawnDetachedRehydrate(dir: string, env: NodeJS.ProcessEnv): void;
247
+ export interface HistoryRecovered {
248
+ at: string;
249
+ lost: {
250
+ ref: string;
251
+ sha: string;
252
+ }[];
253
+ /** Where main now points: the checkpoint's castle/main, or the remote's main as a fallback. */
254
+ newHead: string | null;
255
+ /** The lost tips the snapshot had deliberately left out (over the cap). */
256
+ skippedOverCap: string[];
257
+ /** A merge was in progress; its conflicted files wait for the agent (castle-merge.json). */
258
+ conflict: boolean;
259
+ keptBundle: string | null;
260
+ reason: string;
261
+ tried: string[];
262
+ /** Whether the commit of the kept files has landed. */
263
+ committed: boolean;
264
+ }
265
+ export declare function recoveredConflictInstruction(files: string[] | null): string;
266
+ export declare function historyLostInstruction(lost: string[]): string;
267
+ export type RehydrateOutcome = 'complete' | 'rebuilt';
268
+ /** `castle-web git rehydrate --dir <deck>`: rebuild a cold-resumed deck's git history. */
269
+ export declare function cloudRehydrate(dir: string, deps: CloudGitDeps): Promise<RehydrateOutcome>;
159
270
  export interface LeavePending {
160
271
  at: string;
161
272
  /** What `git status` showed as changed when the user left. */
@@ -173,6 +284,12 @@ export interface SyncOutcome {
173
284
  merge: 'none' | 'fast-forward' | 'merged' | 'conflict' | 'seeded' | 'deferred';
174
285
  pushed: boolean;
175
286
  }
287
+ /**
288
+ * The remote's main as local main last took it in: what a recovery may start the deck again
289
+ * from. castle/main can be ahead of it -- fetched, but its merge deferred while tasks were busy,
290
+ * or refused -- and starting from castle/main would revert whatever came in with it.
291
+ */
292
+ export declare const INTEGRATED_REF = "refs/castle/integrated";
176
293
  export interface DraftDifference {
177
294
  path: string;
178
295
  /** How the cloud copy differs from castle/main: `deleted` means it lacks a file the remote has. */
@@ -248,6 +365,7 @@ export declare function gitVersionHistory(dir: string, env?: NodeJS.ProcessEnv):
248
365
  path: string;
249
366
  kind: GitChangeKind;
250
367
  }[];
368
+ loading?: boolean;
251
369
  }>;
252
370
  export declare function printGitLog(dir: string, from?: string, git?: CloudGitDeps['git']): void;
253
371
  export declare function printGitShow(dir: string, target: string, git?: CloudGitDeps['git']): void;