castle-web-cli 0.4.218 → 0.4.220

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.js CHANGED
@@ -47,7 +47,7 @@ import { createPlaywrightPlaytestExecutor } from './native/playtest-executor.js'
47
47
  import { createRemotePlaytestExecutor } from './native/playtest-remote.js';
48
48
  import { runPlaytest, } from './native/playtest.js';
49
49
  import { AGENT_ROLE_ENV, cloudGitMode } from './cloudGit.js';
50
- import { createServeGitHooks } from './cloudGitServe.js';
50
+ import { createServeGitHooks, createServeMarkerPoll } from './cloudGitServe.js';
51
51
  export const AGENT_WS_PATH = '/__castle/agent';
52
52
  const DEFAULT_SETTINGS = {
53
53
  // Both roles run the claude CLI routed through OpenRouter at the slug below.
@@ -4158,6 +4158,15 @@ export function createAgentServer(opts) {
4158
4158
  routerBusy: () => routerQueue.isRunning(),
4159
4159
  enqueueInstruction: (text) => routerQueue.handleUserMessage(text, undefined, undefined, undefined, true),
4160
4160
  });
4161
+ // Markers that need no git (the saved copy of the deck is newer than this folder) become
4162
+ // router turns with git off too; with git on, the hooks above consume them.
4163
+ const markerPoll = gitHooks
4164
+ ? null
4165
+ : createServeMarkerPoll({
4166
+ deckDir,
4167
+ addLog,
4168
+ enqueueInstruction: (text) => routerQueue.handleUserMessage(text, undefined, undefined, undefined, true),
4169
+ });
4161
4170
  const taskStore = createTaskStore({
4162
4171
  deckDir,
4163
4172
  deckLabel,
@@ -4378,6 +4387,7 @@ export function createAgentServer(opts) {
4378
4387
  }
4379
4388
  function shutdown() {
4380
4389
  gitHooks?.stop();
4390
+ markerPoll?.stop();
4381
4391
  taskStore.shutdown();
4382
4392
  for (const child of [...taskChildren, ...routerChildren]) {
4383
4393
  try {
package/dist/api.d.ts CHANGED
@@ -166,6 +166,8 @@ export declare function saveCauldronServerBundle(deckId: string, uploadId: strin
166
166
  export interface WebDeckSource {
167
167
  deckId: string;
168
168
  archiveUrl: string;
169
+ /** Unique per saved version: every save mints a new one (webSourceSync.ts compares it). */
170
+ s3Key: string;
169
171
  updatedAt: string;
170
172
  }
171
173
  export interface DeckMeta {
@@ -177,7 +179,7 @@ export interface DeckMeta {
177
179
  }
178
180
  export declare function deckMeta(deckId: string): Promise<DeckMeta | null>;
179
181
  export declare function webDeckSource(deckId: string): Promise<WebDeckSource | null>;
180
- export declare function saveWebDeckSource(deckId: string, uploadId: string): Promise<WebDeckSource>;
182
+ export declare function saveWebDeckSource(deckId: string, uploadId: string, expectedS3Key?: string | null): Promise<WebDeckSource>;
181
183
  export type CloudDeckKit = 'PHYSICS_2D' | 'PHYSICS_3D' | 'MULTIPLAYER_2D' | 'MULTIPLAYER_3D' | 'TURN_BASED' | 'NONE';
182
184
  export interface RegisteredCloudDeck {
183
185
  deckId: string;
package/dist/api.js CHANGED
@@ -286,18 +286,29 @@ export async function deckMeta(deckId) {
286
286
  export async function webDeckSource(deckId) {
287
287
  const data = await graphql(`query($deckId: ID!) {
288
288
  webDeckSource(deckId: $deckId) {
289
- deckId archiveUrl updatedAt
289
+ deckId archiveUrl s3Key updatedAt
290
290
  }
291
291
  }`, { deckId });
292
292
  handleAPIError(data);
293
293
  return pickData(data, 'webDeckSource');
294
294
  }
295
- export async function saveWebDeckSource(deckId, uploadId) {
296
- const data = await graphql(`mutation($deckId: ID!, $uploadId: ID!) {
295
+ // `expectedS3Key` is the save precondition: omitted (undefined) means no check, null means
296
+ // "there must be no saved source yet", and a key means "the saved source must still be this
297
+ // one" -- otherwise Ghost refuses with WEB_DECK_SOURCE_STALE. The argument is left out of the
298
+ // document entirely when omitted, so the request is exactly what older CLIs sent.
299
+ export async function saveWebDeckSource(deckId, uploadId, expectedS3Key) {
300
+ const checked = expectedS3Key !== undefined;
301
+ const data = await graphql(checked
302
+ ? `mutation($deckId: ID!, $uploadId: ID!, $expectedS3Key: String) {
303
+ saveWebDeckSource(deckId: $deckId, uploadId: $uploadId, expectedS3Key: $expectedS3Key) {
304
+ deckId archiveUrl s3Key updatedAt
305
+ }
306
+ }`
307
+ : `mutation($deckId: ID!, $uploadId: ID!) {
297
308
  saveWebDeckSource(deckId: $deckId, uploadId: $uploadId) {
298
- deckId archiveUrl updatedAt
309
+ deckId archiveUrl s3Key updatedAt
299
310
  }
300
- }`, { deckId, uploadId });
311
+ }`, checked ? { deckId, uploadId, expectedS3Key } : { deckId, uploadId });
301
312
  handleAPIError(data);
302
313
  return pickData(data, 'saveWebDeckSource');
303
314
  }
@@ -33,8 +33,15 @@ export declare const HISTORY_RECOVERED_FILE: string;
33
33
  export declare const RECOVERED_COMMIT_MESSAGE = "Edits restored after lost history";
34
34
  /** Written with it, once: the notice and instruction the serve turns into an agent turn. */
35
35
  export declare const HISTORY_LOST_MARKER_FILE: string;
36
+ /**
37
+ * Written by `source-status --notify` when the deck's saved copy is newer than this folder
38
+ * (webSourceSync.ts). Not a git marker: the serve consumes it with git off too.
39
+ */
40
+ export declare const WEB_SOURCE_NEWER_MARKER_FILE: string;
36
41
  /** Every marker the serve turns into an agent turn. */
37
42
  export declare const AGENT_MARKER_FILES: readonly string[];
43
+ /** The markers the serve consumes whether or not git is on (CASTLE_GIT). */
44
+ export declare const UNGATED_AGENT_MARKER_FILES: readonly string[];
38
45
  /** The serve's note that task agents (or the router) are working in the deck; see deckBusy. */
39
46
  export declare const BUSY_FILE: string;
40
47
  /** The remote has (or may have) work that waits to be merged until the deck is idle. */
package/dist/cloudGit.js CHANGED
@@ -82,8 +82,20 @@ export const HISTORY_RECOVERED_FILE = path.join('.castle', 'agent', 'git-history
82
82
  export const RECOVERED_COMMIT_MESSAGE = 'Edits restored after lost history';
83
83
  /** Written with it, once: the notice and instruction the serve turns into an agent turn. */
84
84
  export const HISTORY_LOST_MARKER_FILE = path.join('.castle', 'agent', 'git-history-lost.json');
85
+ /**
86
+ * Written by `source-status --notify` when the deck's saved copy is newer than this folder
87
+ * (webSourceSync.ts). Not a git marker: the serve consumes it with git off too.
88
+ */
89
+ export const WEB_SOURCE_NEWER_MARKER_FILE = path.join('.castle', 'agent', 'web-source-newer.json');
85
90
  /** Every marker the serve turns into an agent turn. */
86
- export const AGENT_MARKER_FILES = [CONFLICT_MARKER_FILE, ADOPTED_MARKER_FILE, HISTORY_LOST_MARKER_FILE];
91
+ export const AGENT_MARKER_FILES = [
92
+ CONFLICT_MARKER_FILE,
93
+ ADOPTED_MARKER_FILE,
94
+ HISTORY_LOST_MARKER_FILE,
95
+ WEB_SOURCE_NEWER_MARKER_FILE,
96
+ ];
97
+ /** The markers the serve consumes whether or not git is on (CASTLE_GIT). */
98
+ export const UNGATED_AGENT_MARKER_FILES = [WEB_SOURCE_NEWER_MARKER_FILE];
87
99
  /** The serve's note that task agents (or the router) are working in the deck; see deckBusy. */
88
100
  export const BUSY_FILE = path.join('.castle', 'agent', 'git-busy.json');
89
101
  /** The remote has (or may have) work that waits to be merged until the deck is idle. */
@@ -37,5 +37,30 @@ export declare function runCastleWeb(args: string[], cwd: string, env?: NodeJS.P
37
37
  code: number;
38
38
  output: string;
39
39
  }>;
40
+ type MarkerSink = Pick<ServeGitHooksOptions, 'addLog' | 'enqueueInstruction'>;
41
+ /**
42
+ * One `.castle/agent/*.json` marker `{ notice?, instruction }` becomes a chat line and a hidden
43
+ * router turn. The file is deleted before anything else, so a throw can never turn one marker
44
+ * into a loop of turns. True when a turn was queued.
45
+ */
46
+ export declare function consumeAgentMarker(deckDir: string, rel: string, sink: MarkerSink, beforeTurn?: () => void): boolean;
47
+ export interface ServeMarkerPoll {
48
+ /** Check for markers now (the poll does this on its own). */
49
+ check(): void;
50
+ stop(): void;
51
+ }
52
+ /**
53
+ * The marker poll for a serve without git (createServeGitHooks returns null): the markers that
54
+ * need no git (UNGATED_AGENT_MARKER_FILES, e.g. the saved-copy-is-newer notice) still become
55
+ * router turns. With git on, the git hooks' own poll consumes these along with the git ones, so
56
+ * exactly one poll runs either way. A file rather than an env var because a reused serve never
57
+ * sees new env, and the first check runs at start for a marker left while the serve was down.
58
+ */
59
+ export declare function createServeMarkerPoll(opts: MarkerSink & {
60
+ deckDir: string;
61
+ pollMs?: number;
62
+ files?: readonly string[];
63
+ }): ServeMarkerPoll;
40
64
  /** Null unless the serve runs with CASTLE_GIT=on. Whether the deck is attached is asked per commit. */
41
65
  export declare function createServeGitHooks(opts: ServeGitHooksOptions): ServeGitHooks | null;
66
+ export {};
@@ -2,7 +2,7 @@ import { spawn } from 'child_process';
2
2
  import * as fs from 'fs';
3
3
  import * as path from 'path';
4
4
  import { fileURLToPath } from 'url';
5
- import { AGENT_MARKER_FILES, cloudGitModeAsync, CONFLICT_MARKER_FILE, DEADLINE_ENV, EXIT_CONFLICT, EXIT_NOT_ENABLED, mergeWaiting, readLeavePending, readMergeState, setDeckBusy, } from './cloudGit.js';
5
+ import { AGENT_MARKER_FILES, cloudGitModeAsync, CONFLICT_MARKER_FILE, DEADLINE_ENV, EXIT_CONFLICT, EXIT_NOT_ENABLED, mergeWaiting, readLeavePending, readMergeState, setDeckBusy, UNGATED_AGENT_MARKER_FILES, } from './cloudGit.js';
6
6
  // The serve's half of git in the cloud sandbox (castle-sandboxes docs/git-remotes-phase2.md):
7
7
  // - `commit --reason turn` when the router settles with the task board idle,
8
8
  // - `commit --reason task` when the task board goes idle,
@@ -110,6 +110,61 @@ function taskMessage(titles) {
110
110
  const more = titles.length > MAX_TITLES_IN_MESSAGE ? ` (+${titles.length - MAX_TITLES_IN_MESSAGE} more)` : '';
111
111
  return `${titles.length === 1 ? 'Task' : 'Tasks'}: ${shown}${more}`;
112
112
  }
113
+ /**
114
+ * One `.castle/agent/*.json` marker `{ notice?, instruction }` becomes a chat line and a hidden
115
+ * router turn. The file is deleted before anything else, so a throw can never turn one marker
116
+ * into a loop of turns. True when a turn was queued.
117
+ */
118
+ export function consumeAgentMarker(deckDir, rel, sink, beforeTurn) {
119
+ const file = path.join(deckDir, rel);
120
+ let report;
121
+ try {
122
+ report = JSON.parse(fs.readFileSync(file, 'utf-8'));
123
+ }
124
+ catch (e) {
125
+ if (e.code !== 'ENOENT')
126
+ fs.rmSync(file, { force: true });
127
+ return false;
128
+ }
129
+ fs.rmSync(file, { force: true });
130
+ if (typeof report.instruction !== 'string' || !report.instruction)
131
+ return false;
132
+ sink.addLog(typeof report.notice === 'string' && report.notice ? report.notice : CONFLICT_NOTICE);
133
+ beforeTurn?.();
134
+ sink.enqueueInstruction(report.instruction);
135
+ return true;
136
+ }
137
+ /**
138
+ * The marker poll for a serve without git (createServeGitHooks returns null): the markers that
139
+ * need no git (UNGATED_AGENT_MARKER_FILES, e.g. the saved-copy-is-newer notice) still become
140
+ * router turns. With git on, the git hooks' own poll consumes these along with the git ones, so
141
+ * exactly one poll runs either way. A file rather than an env var because a reused serve never
142
+ * sees new env, and the first check runs at start for a marker left while the serve was down.
143
+ */
144
+ export function createServeMarkerPoll(opts) {
145
+ const files = opts.files ?? UNGATED_AGENT_MARKER_FILES;
146
+ const check = () => {
147
+ for (const rel of files) {
148
+ try {
149
+ consumeAgentMarker(opts.deckDir, rel, opts);
150
+ }
151
+ catch (err) {
152
+ console.error(`[serve] could not read the agent marker ${rel}: ${String(err)}`);
153
+ }
154
+ }
155
+ };
156
+ const poll = setInterval(check, opts.pollMs ?? CONFLICT_POLL_MS);
157
+ poll.unref();
158
+ // Not synchronously: the caller wires the router queue up after creating this.
159
+ const first = setImmediate(check);
160
+ return {
161
+ check,
162
+ stop() {
163
+ clearInterval(poll);
164
+ clearImmediate(first);
165
+ },
166
+ };
167
+ }
113
168
  /** Null unless the serve runs with CASTLE_GIT=on. Whether the deck is attached is asked per commit. */
114
169
  export function createServeGitHooks(opts) {
115
170
  const env = opts.env ?? process.env;
@@ -190,26 +245,12 @@ export function createServeGitHooks(opts) {
190
245
  drain();
191
246
  }
192
247
  function consumeMarker(rel) {
193
- const file = path.join(opts.deckDir, rel);
194
- let report;
195
- try {
196
- report = JSON.parse(fs.readFileSync(file, 'utf-8'));
197
- }
198
- catch (e) {
199
- if (e.code !== 'ENOENT')
200
- fs.rmSync(file, { force: true });
201
- return;
202
- }
203
- // Consumed first, so a throw below can never turn one marker into a loop of turns.
204
- fs.rmSync(file, { force: true });
205
- if (typeof report.instruction !== 'string' || !report.instruction)
206
- return;
207
- opts.addLog(typeof report.notice === 'string' && report.notice ? report.notice : CONFLICT_NOTICE);
208
- if (rel === CONFLICT_MARKER_FILE) {
209
- resolverInFlight = true;
210
- lastRaisedAt = now();
211
- }
212
- opts.enqueueInstruction(report.instruction);
248
+ consumeAgentMarker(opts.deckDir, rel, opts, () => {
249
+ if (rel === CONFLICT_MARKER_FILE) {
250
+ resolverInFlight = true;
251
+ lastRaisedAt = now();
252
+ }
253
+ });
213
254
  }
214
255
  function checkConflict() {
215
256
  for (const rel of AGENT_MARKER_FILES)
@@ -1,4 +1,21 @@
1
1
  export declare function getDeck(dir: string, options?: {
2
2
  deckId?: string;
3
3
  force?: boolean;
4
+ side?: boolean;
5
+ json?: boolean;
4
6
  }): Promise<void>;
7
+ /** A save time as a folder name: `20260818-132107` (UTC), or null if unparseable. */
8
+ export declare function savedSourceStamp(updatedAt: string): string | null;
9
+ /**
10
+ * The saved-source root inside `deckDir`, created if needed, or an error naming why it is not
11
+ * safe to write into: `.castle`, `.castle/agent`, `.castle/agent/saved-source` and every stamped
12
+ * copy must be real directories (never symlinks), and the root must resolve inside the deck.
13
+ * The folder is written by whatever runs in the deck, so a link here could aim the replace and
14
+ * the prune at files outside it.
15
+ */
16
+ export declare function prepareSavedSourceRoot(deckDir: string): string;
17
+ /**
18
+ * Removes all but the `keep` newest stamped copies; returns what it removed. Only real
19
+ * directories named like a stamp are candidates: anything else there is left alone.
20
+ */
21
+ export declare function pruneSavedSources(root: string, keep?: number): string[];
package/dist/get-deck.js CHANGED
@@ -6,6 +6,7 @@ import * as api from './api.js';
6
6
  import { normalizeDeckPackageJson } from './normalize.js';
7
7
  import { archiveSource, downloadSourceArchive, runTar, SOURCE_ARCHIVE_EXCLUDES, } from './save-deck.js';
8
8
  import { readCastleJson } from './castleJson.js';
9
+ import { SAVED_SOURCE_DIR, SAVED_SOURCE_KEEP, writeSyncMarker } from './webSourceSync.js';
9
10
  // Refreshing a deck already in the target replaces its source, so a file deleted
10
11
  // upstream actually disappears here -- untarring over the old tree would leave it
11
12
  // behind. What survives is exactly what the source archive doesn't carry, and it
@@ -48,6 +49,10 @@ function newestSourceMtime(dir) {
48
49
  //
49
50
  // Deps are left to `castle-web install`, like a git pull leaves them to you.
50
51
  export async function getDeck(dir, options = {}) {
52
+ if (options.side) {
53
+ await getDeckSide(dir, options);
54
+ return;
55
+ }
51
56
  const targetDir = path.resolve(dir);
52
57
  const localDeckId = readCastleJson(targetDir)?.deckId;
53
58
  const deckId = options.deckId ?? localDeckId;
@@ -113,8 +118,152 @@ export async function getDeck(dir, options = {}) {
113
118
  }
114
119
  catch { /* nothing to clean */ }
115
120
  }
121
+ // The folder's lineage is now exactly this saved version (webSourceSync.ts).
122
+ writeSyncMarker(targetDir, deckId, source, 'get-deck');
116
123
  if (normalizeDeckPackageJson(targetDir)) {
117
124
  console.log(`Repointed package.json at this machine's sdk/cli`);
118
125
  }
119
126
  console.log(`${refreshing ? 'Updated' : 'Extracted to'} ${targetDir}`);
120
127
  }
128
+ /** A save time as a folder name: `20260818-132107` (UTC), or null if unparseable. */
129
+ export function savedSourceStamp(updatedAt) {
130
+ const ms = Date.parse(updatedAt);
131
+ if (!Number.isFinite(ms))
132
+ return null;
133
+ return new Date(ms).toISOString().slice(0, 19).replace(/[-:]/g, '').replace('T', '-');
134
+ }
135
+ const STAMP_RE = /^\d{8}-\d{6}$/;
136
+ function lstatIfPresent(file) {
137
+ try {
138
+ return fs.lstatSync(file);
139
+ }
140
+ catch (e) {
141
+ if (e.code === 'ENOENT')
142
+ return null;
143
+ throw e;
144
+ }
145
+ }
146
+ /**
147
+ * The saved-source root inside `deckDir`, created if needed, or an error naming why it is not
148
+ * safe to write into: `.castle`, `.castle/agent`, `.castle/agent/saved-source` and every stamped
149
+ * copy must be real directories (never symlinks), and the root must resolve inside the deck.
150
+ * The folder is written by whatever runs in the deck, so a link here could aim the replace and
151
+ * the prune at files outside it.
152
+ */
153
+ export function prepareSavedSourceRoot(deckDir) {
154
+ let current = deckDir;
155
+ for (const part of SAVED_SOURCE_DIR.split(path.sep)) {
156
+ current = path.join(current, part);
157
+ const stat = lstatIfPresent(current);
158
+ if (!stat) {
159
+ fs.mkdirSync(current);
160
+ continue;
161
+ }
162
+ if (stat.isSymbolicLink() || !stat.isDirectory()) {
163
+ throw new Error(`Refusing to use ${current}: it is ${stat.isSymbolicLink() ? 'a symlink' : 'not a directory'}.`);
164
+ }
165
+ }
166
+ const realDeck = fs.realpathSync(deckDir);
167
+ const realRoot = fs.realpathSync(current);
168
+ if (path.relative(realDeck, realRoot).startsWith('..') || path.isAbsolute(path.relative(realDeck, realRoot))) {
169
+ throw new Error(`Refusing to use ${current}: it resolves outside the deck (${realRoot}).`);
170
+ }
171
+ for (const name of fs.readdirSync(current)) {
172
+ if (!STAMP_RE.test(name))
173
+ continue;
174
+ const stat = fs.lstatSync(path.join(current, name));
175
+ if (stat.isSymbolicLink() || !stat.isDirectory()) {
176
+ throw new Error(`Refusing to use ${path.join(current, name)}: it is ${stat.isSymbolicLink() ? 'a symlink' : 'not a directory'}.`);
177
+ }
178
+ }
179
+ return current;
180
+ }
181
+ /**
182
+ * Removes all but the `keep` newest stamped copies; returns what it removed. Only real
183
+ * directories named like a stamp are candidates: anything else there is left alone.
184
+ */
185
+ export function pruneSavedSources(root, keep = SAVED_SOURCE_KEEP) {
186
+ let names;
187
+ try {
188
+ names = fs.readdirSync(root).filter((name) => {
189
+ if (!STAMP_RE.test(name))
190
+ return false;
191
+ const stat = lstatIfPresent(path.join(root, name));
192
+ return stat !== null && stat.isDirectory() && !stat.isSymbolicLink();
193
+ });
194
+ }
195
+ catch {
196
+ return [];
197
+ }
198
+ const removed = names.sort().reverse().slice(keep);
199
+ for (const name of removed)
200
+ fs.rmSync(path.join(root, name), { recursive: true, force: true });
201
+ return removed;
202
+ }
203
+ // `get-deck <dir> --side`: the deck's current saved source, fetched beside the folder into
204
+ // `.castle/agent/saved-source/<stamp>/` for comparing -- not installed, not served, and nothing
205
+ // of the folder's own (its source files, its sync marker) is touched. Excluded from the source
206
+ // archive and kept by deck persistence, like the rest of `.castle/agent/`.
207
+ async function getDeckSide(dir, options) {
208
+ const targetDir = path.resolve(dir);
209
+ const localDeckId = readCastleJson(targetDir)?.deckId;
210
+ if (!fs.existsSync(targetDir) || !fs.statSync(targetDir).isDirectory()) {
211
+ console.error(`--side fetches the saved copy beside an existing deck folder; ${targetDir} does not exist.`);
212
+ process.exit(1);
213
+ }
214
+ const deckId = options.deckId ?? localDeckId;
215
+ if (!deckId) {
216
+ console.error(`No deckId. Either pass --deck-id <id> or run from a directory whose castle.json has one.`);
217
+ process.exit(1);
218
+ }
219
+ if (localDeckId && deckId !== localDeckId) {
220
+ console.error(`This directory holds deck ${localDeckId}, but --deck-id ${deckId} was passed.`);
221
+ process.exit(1);
222
+ }
223
+ const source = await api.webDeckSource(deckId);
224
+ if (!source) {
225
+ console.error(`No source archive on server for deck ${deckId}.`);
226
+ process.exit(1);
227
+ }
228
+ const stamp = savedSourceStamp(source.updatedAt);
229
+ if (!stamp) {
230
+ console.error(`Unreadable save time from the server (${source.updatedAt}).`);
231
+ process.exit(1);
232
+ }
233
+ // With --json, stdout is the one result line.
234
+ const log = options.json ? (line) => console.error(line) : (line) => console.log(line);
235
+ let root;
236
+ try {
237
+ root = prepareSavedSourceRoot(targetDir);
238
+ }
239
+ catch (e) {
240
+ console.error(e instanceof Error ? e.message : String(e));
241
+ process.exit(1);
242
+ }
243
+ const dest = path.join(root, stamp);
244
+ const tmpFile = await downloadSourceArchive(source, 'castle-side', log);
245
+ // Extracted beside the destination and renamed in, so a failed extract never leaves a
246
+ // half-written copy under a real stamp (and tmp may be another filesystem).
247
+ const staging = path.join(root, `.partial-${nanoid(8)}`);
248
+ try {
249
+ fs.mkdirSync(staging, { recursive: true });
250
+ await runTar(['-xzf', tmpFile, '-C', staging]);
251
+ fs.rmSync(dest, { recursive: true, force: true });
252
+ fs.renameSync(staging, dest);
253
+ }
254
+ finally {
255
+ fs.rmSync(staging, { recursive: true, force: true });
256
+ try {
257
+ fs.unlinkSync(tmpFile);
258
+ }
259
+ catch { /* nothing to clean */ }
260
+ }
261
+ for (const name of pruneSavedSources(root))
262
+ log(`Removed the older saved copy ${name}`);
263
+ if (options.json) {
264
+ console.log(JSON.stringify({ path: dest, s3Key: source.s3Key, updatedAt: source.updatedAt }));
265
+ }
266
+ else {
267
+ console.log(`Saved copy (saved ${source.updatedAt}) fetched to ${dest}`);
268
+ }
269
+ }
@@ -51,3 +51,41 @@ export interface GitInitResult {
51
51
  export declare function gitInit(dirArg: string, opts: {
52
52
  environment: GitEnvironment;
53
53
  }, deps: GitInitDeps): Promise<GitInitResult>;
54
+ export type GitSetupOutcome = 'configured' | 'unchanged' | 'kept' | 'removed' | 'absent';
55
+ export interface GitSetupDeps {
56
+ git(args: string[], cwd: string): GitResult;
57
+ }
58
+ /**
59
+ * Points git at this CLI for the Castle git hosts in the user's global config, or removes
60
+ * that. A helper someone set for a Castle host themselves is left alone ('kept') unless
61
+ * `force`, since it can't be put back; `remove` takes out only what this wrote.
62
+ */
63
+ export declare function gitSetup(opts: {
64
+ remove?: boolean;
65
+ force?: boolean;
66
+ }, deps: GitSetupDeps): Record<GitEnvironment, GitSetupOutcome>;
67
+ /**
68
+ * The deck a `git clone` argument names: a deck id, its git URL, or its editor URL
69
+ * (castle.xyz/create/<deckId>). A git URL also says which environment it is on.
70
+ */
71
+ export declare function parseDeckTarget(target: string): {
72
+ deckId: string;
73
+ environment?: GitEnvironment;
74
+ };
75
+ export interface GitCloneDeps {
76
+ token: string | null;
77
+ envToken: string | undefined;
78
+ git(args: string[], cwd: string): GitResult;
79
+ castleWebOnPath(): boolean;
80
+ log(message: string): void;
81
+ warn(message: string): void;
82
+ }
83
+ export interface GitCloneResult {
84
+ deckId: string;
85
+ dir: string;
86
+ remoteUrl: string;
87
+ }
88
+ /** Clones a deck's Castle repo, with the remote named `castle` and the credential helper in the clone's config. */
89
+ export declare function gitClone(target: string, dirArg: string | undefined, opts: {
90
+ environment?: GitEnvironment;
91
+ }, deps: GitCloneDeps, cwd?: string): GitCloneResult;