@solidactions/cli 1.28.0 → 1.30.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.
@@ -0,0 +1,570 @@
1
+ "use strict";
2
+ /**
3
+ * solidactions docs pull <folder> [dest]
4
+ *
5
+ * Downloads a Docs folder tree from SA-Docs into a local markdown tree (the
6
+ * inverse of `docs push`): BFS-walks the folder via `docs_vault list`,
7
+ * bulk-fetches doc bodies via `docs_vault bulk_read`, and writes each doc as
8
+ * <dest>/<relative-folder>/<sanitized-title>.md plus a revision manifest
9
+ * (<dest>/.solidactions-docs.json) recording id/title/current_revision_id
10
+ * per file for later diffing.
11
+ *
12
+ * Media docs (blob-backed, empty body) are two-stage classified: a
13
+ * candidate filter on the bulk_read row's properties, then an authoritative
14
+ * confirm against `GET /api/v1/docs/{id}/media` — a 404 `media_not_found`
15
+ * means the candidate was a false positive and it's written as markdown
16
+ * like any other doc.
17
+ */
18
+ var __importDefault = (this && this.__importDefault) || function (mod) {
19
+ return (mod && mod.__esModule) ? mod : { "default": mod };
20
+ };
21
+ Object.defineProperty(exports, "__esModule", { value: true });
22
+ exports.sha256Hex = exports.DOCS_MANIFEST = void 0;
23
+ exports.sanitizeSegment = sanitizeSegment;
24
+ exports.sanitizeTitle = sanitizeTitle;
25
+ exports.docsPullWithConfig = docsPullWithConfig;
26
+ exports.docsPull = docsPull;
27
+ const fs_1 = __importDefault(require("fs"));
28
+ const path_1 = __importDefault(require("path"));
29
+ const axios_1 = __importDefault(require("axios"));
30
+ const chalk_1 = __importDefault(require("chalk"));
31
+ const prompts_1 = __importDefault(require("prompts"));
32
+ const api_1 = require("../utils/api");
33
+ const mcp_1 = require("../utils/mcp");
34
+ const docs_manifest_1 = require("../utils/docs-manifest");
35
+ Object.defineProperty(exports, "DOCS_MANIFEST", { enumerable: true, get: function () { return docs_manifest_1.DOCS_MANIFEST; } });
36
+ Object.defineProperty(exports, "sha256Hex", { enumerable: true, get: function () { return docs_manifest_1.sha256Hex; } });
37
+ /** Extension appended to a media file's sanitized title when the title itself has none. */
38
+ const MIME_EXTENSIONS = {
39
+ 'image/png': '.png',
40
+ 'image/jpeg': '.jpg',
41
+ 'image/gif': '.gif',
42
+ 'image/webp': '.webp',
43
+ 'application/pdf': '.pdf',
44
+ };
45
+ const CHUNK_SIZE = 50;
46
+ /** Characters that are unsafe as filesystem path segments, plus control chars. */
47
+ // eslint-disable-next-line no-control-regex
48
+ const UNSAFE_CHARS = /[/\\:*?"<>|\x00-\x1f]/g;
49
+ /**
50
+ * Replace filesystem-unsafe characters (/ \ : * ? " < > | and control chars)
51
+ * with underscores so a server-provided name (doc title or folder name) is
52
+ * safe to use as a single filesystem path segment. Also neutralizes bare
53
+ * `.` and `..` segments (which would otherwise resolve to the current or
54
+ * parent directory — a path-traversal risk for folder names in particular).
55
+ */
56
+ function sanitizeSegment(name) {
57
+ const replaced = name.replace(UNSAFE_CHARS, '_');
58
+ if (replaced === '.')
59
+ return '_';
60
+ if (replaced === '..')
61
+ return '__';
62
+ return replaced;
63
+ }
64
+ /**
65
+ * Replace filesystem-unsafe characters (/ \ : * ? " < > | and control chars)
66
+ * in a doc title with underscores so it can be used as a file basename.
67
+ */
68
+ function sanitizeTitle(title) {
69
+ return sanitizeSegment(title);
70
+ }
71
+ /**
72
+ * A doc is a media *candidate* when the bulk_read row carries blob metadata
73
+ * and an empty body. This is a cheap pre-filter, not authoritative — the
74
+ * media endpoint confirm can still return a false positive (see
75
+ * `resolveMedia`).
76
+ */
77
+ function isMediaCandidate(doc) {
78
+ const props = doc.properties;
79
+ return Boolean(props.blob_sha && props.mime && props.size) && doc.body === '';
80
+ }
81
+ /**
82
+ * Authoritatively confirm a media candidate against `GET /api/v1/docs/{id}/media`
83
+ * and, if confirmed, download the returned signed URL (no auth headers — it's
84
+ * a pre-signed R2 URL). Returns `{ isMedia: false }` for the false-positive
85
+ * 404 `media_not_found` case, in which the caller falls back to the D1
86
+ * markdown write path.
87
+ */
88
+ async function resolveMedia(config, doc) {
89
+ const confirm = await axios_1.default.get(`${config.host}/api/v1/docs/${doc.id}/media`, {
90
+ headers: (0, api_1.getApiHeaders)(config),
91
+ validateStatus: () => true,
92
+ });
93
+ if (confirm.status === 404 && confirm.data?.code === 'media_not_found') {
94
+ return { isMedia: false };
95
+ }
96
+ if (confirm.status !== 200) {
97
+ const code = confirm.data?.code ?? 'unknown_error';
98
+ const message = confirm.data?.message ?? 'media confirm request failed';
99
+ process.stderr.write(chalk_1.default.red(`error: ${code}: ${message}\n`));
100
+ process.exit(1);
101
+ }
102
+ const { url, mime } = confirm.data;
103
+ const download = await axios_1.default.get(url, { responseType: 'arraybuffer', validateStatus: () => true });
104
+ if (download.status !== 200) {
105
+ return { isMedia: true, mime, bytes: null, warning: `warn: failed to download media for doc ${doc.id} (${doc.title}): HTTP ${download.status}` };
106
+ }
107
+ return { isMedia: true, mime, bytes: Buffer.from(download.data) };
108
+ }
109
+ /**
110
+ * Compare each manifest-tracked file against its recorded `body_sha256` to
111
+ * find unpushed local edits. An entry without a hash (old manifest) or whose
112
+ * file is missing locally is never reported as modified — graceful
113
+ * degradation to "no detection" rather than a false refusal.
114
+ */
115
+ function detectLocalModifications(destination, manifest) {
116
+ const modified = [];
117
+ for (const [relPath, entry] of Object.entries(manifest.docs)) {
118
+ if (entry.body_sha256 == null)
119
+ continue;
120
+ const absPath = path_1.default.join(destination, relPath);
121
+ // Only hash regular files. A corrupt manifest key naming a directory would
122
+ // otherwise throw EISDIR and abort the pull before it starts.
123
+ let stat;
124
+ try {
125
+ stat = fs_1.default.statSync(absPath);
126
+ }
127
+ catch {
128
+ continue; // missing locally — graceful degradation, never a false refusal
129
+ }
130
+ if (!stat.isFile())
131
+ continue;
132
+ const currentHash = (0, docs_manifest_1.sha256Hex)(fs_1.default.readFileSync(absPath));
133
+ if (currentHash !== entry.body_sha256) {
134
+ modified.push(relPath);
135
+ }
136
+ }
137
+ return modified;
138
+ }
139
+ /** The last non-empty path segment of a '/'-separated folder path. */
140
+ function lastSegment(folderPath) {
141
+ const segments = folderPath.split('/').filter(Boolean);
142
+ return segments[segments.length - 1] ?? folderPath;
143
+ }
144
+ /**
145
+ * BFS-walk `folderPath` via `docs_vault list`, collecting every doc row with
146
+ * its relative folder path. Returns null (with the list error message
147
+ * already known to the caller) if the root list call fails.
148
+ */
149
+ async function listTree(config, folderPath) {
150
+ const rows = [];
151
+ const queue = [{ folder_path: folderPath, relative: '' }];
152
+ let first = true;
153
+ while (queue.length > 0) {
154
+ const { folder_path, relative } = queue.shift();
155
+ const result = await (0, mcp_1.callDocsTool)(config, 'docs_vault', { action: 'list', folder_path });
156
+ if (!result.ok) {
157
+ // A subfolder returned by the server itself failed to list is surfaced the
158
+ // same way as a root failure — only the root failure triggers the
159
+ // single-doc fallback (isRoot distinguishes the two).
160
+ return { ok: false, isRoot: first, code: result.data?.code ?? 'unknown_error', message: result.data?.message ?? 'MCP returned an error with no message' };
161
+ }
162
+ first = false;
163
+ for (const folder of result.data?.folders ?? []) {
164
+ const safeName = sanitizeSegment(folder.name);
165
+ const childRelative = relative ? `${relative}/${safeName}` : safeName;
166
+ queue.push({ folder_path: folder.folder_path, relative: childRelative });
167
+ }
168
+ for (const doc of result.data?.docs ?? []) {
169
+ rows.push({ id: doc.id, title: doc.title, relative });
170
+ }
171
+ }
172
+ return { ok: true, rows };
173
+ }
174
+ /** The bulk_read row status that means "body/revision were returned successfully". */
175
+ const BULK_READ_OK_STATUS = 'found';
176
+ /**
177
+ * Fetch bodies + revisions for every collected row via bulk_read, chunked at
178
+ * CHUNK_SIZE ids. A row whose status isn't `BULK_READ_OK_STATUS` (e.g. a
179
+ * server-side `error` or `not_found`), or a requested id absent from the
180
+ * response entirely, is soft-skipped: a warning naming the doc, no file
181
+ * written, no manifest entry — mirroring the media download soft-skip.
182
+ */
183
+ async function fetchBodies(config, rows) {
184
+ const byId = new Map();
185
+ for (const row of rows)
186
+ byId.set(row.id, row);
187
+ const fetched = [];
188
+ const warnings = [];
189
+ for (let i = 0; i < rows.length; i += CHUNK_SIZE) {
190
+ const chunk = rows.slice(i, i + CHUNK_SIZE);
191
+ const result = await (0, mcp_1.callDocsTool)(config, 'docs_vault', {
192
+ action: 'bulk_read',
193
+ items: chunk.map((r) => ({ id: r.id })),
194
+ });
195
+ if (!result.ok) {
196
+ const code = result.data?.code ?? 'unknown_error';
197
+ const message = result.data?.message ?? 'MCP returned an error with no message';
198
+ process.stderr.write(chalk_1.default.red(`error: ${code}: ${message}\n`));
199
+ process.exit(1);
200
+ }
201
+ const resultRows = result.data?.results ?? [];
202
+ const seenIds = new Set();
203
+ for (const row of resultRows) {
204
+ const original = byId.get(row.id);
205
+ if (!original)
206
+ continue;
207
+ seenIds.add(row.id);
208
+ if (row.status !== BULK_READ_OK_STATUS) {
209
+ warnings.push(`warn: skipping doc ${row.id} (${original.title}): bulk_read returned status "${row.status ?? 'unknown'}"`);
210
+ continue;
211
+ }
212
+ fetched.push({
213
+ ...original,
214
+ body: row.body ?? '',
215
+ current_revision_id: row.current_revision_id ?? null,
216
+ properties: row.properties ?? {},
217
+ });
218
+ }
219
+ for (const requested of chunk) {
220
+ if (!seenIds.has(requested.id)) {
221
+ warnings.push(`warn: skipping doc ${requested.id} (${requested.title}): missing from bulk_read results`);
222
+ }
223
+ }
224
+ }
225
+ return { fetched, warnings };
226
+ }
227
+ /**
228
+ * Resolve every fetched doc into a `PlannedDoc` — final relative path and
229
+ * content hash — confirming/downloading media as needed. This is the only
230
+ * place that talks to the media confirm/download endpoints; it performs no
231
+ * filesystem writes.
232
+ */
233
+ async function planDocs(docs, config) {
234
+ const planned = [];
235
+ const warnings = [];
236
+ const usedNamesByDir = new Map();
237
+ for (const doc of docs) {
238
+ const dirRel = doc.relative;
239
+ let used = usedNamesByDir.get(dirRel);
240
+ if (!used) {
241
+ used = new Set();
242
+ usedNamesByDir.set(dirRel, used);
243
+ }
244
+ const media = isMediaCandidate(doc) ? await resolveMedia(config, doc) : { isMedia: false };
245
+ if (media.warning)
246
+ warnings.push(media.warning);
247
+ const sanitized = sanitizeTitle(doc.title);
248
+ let base = sanitized;
249
+ let ext = '.md';
250
+ if (media.isMedia) {
251
+ const titleExt = path_1.default.extname(sanitized);
252
+ if (titleExt) {
253
+ base = sanitized.slice(0, -titleExt.length);
254
+ ext = titleExt;
255
+ }
256
+ else {
257
+ base = sanitized;
258
+ ext = (media.mime && MIME_EXTENSIONS[media.mime]) ?? '';
259
+ }
260
+ }
261
+ let candidate = base;
262
+ let suffix = 2;
263
+ while (used.has(`${candidate}${ext}`)) {
264
+ candidate = `${base}-${suffix}`;
265
+ suffix++;
266
+ }
267
+ used.add(`${candidate}${ext}`);
268
+ const fileName = `${candidate}${ext}`;
269
+ const relPath = dirRel ? `${dirRel}/${fileName}` : fileName;
270
+ let bodySha256;
271
+ let mediaBytes = null;
272
+ if (media.isMedia) {
273
+ if (media.bytes) {
274
+ mediaBytes = media.bytes;
275
+ bodySha256 = (0, docs_manifest_1.sha256Hex)(media.bytes);
276
+ }
277
+ else {
278
+ // Download failure: warning already recorded above; the doc is still
279
+ // tracked (manifest entry written by commitDocs) but there is nothing
280
+ // to write to disk.
281
+ bodySha256 = null;
282
+ }
283
+ }
284
+ else {
285
+ bodySha256 = (0, docs_manifest_1.sha256Hex)(doc.body);
286
+ }
287
+ planned.push({ doc, relPath, dirRel, fileName, isMedia: media.isMedia, mediaBytes, bodySha256 });
288
+ }
289
+ return { planned, warnings };
290
+ }
291
+ /**
292
+ * Write every planned doc to disk under `destination` and build the
293
+ * manifest docs map. The only step in the whole pull that creates
294
+ * directories or writes/overwrites files — called only after any
295
+ * unpushed-local-changes conflict has already refused, so it never clobbers
296
+ * a file the caller decided to keep.
297
+ */
298
+ function commitDocs(destination, planned) {
299
+ const manifestDocs = {};
300
+ const files = [];
301
+ for (const p of planned) {
302
+ const dirAbs = p.dirRel ? path_1.default.join(destination, ...p.dirRel.split('/')) : destination;
303
+ fs_1.default.mkdirSync(dirAbs, { recursive: true });
304
+ // A destination path that already exists as a directory would make writeFileSync
305
+ // throw EISDIR mid-walk, after earlier docs were written and before the manifest
306
+ // is saved — a half-pulled tree with a stale sidecar. Fail cleanly instead.
307
+ const targetAbs = path_1.default.join(dirAbs, p.fileName);
308
+ if (fs_1.default.existsSync(targetAbs) && !fs_1.default.statSync(targetAbs).isFile()) {
309
+ process.stderr.write(chalk_1.default.red(`error: "${p.relPath}" exists and is not a regular file — cannot write doc ${p.doc.id} (${p.doc.title}).\n`));
310
+ process.exit(1);
311
+ }
312
+ if (p.isMedia) {
313
+ if (p.mediaBytes) {
314
+ fs_1.default.writeFileSync(targetAbs, p.mediaBytes);
315
+ files.push({ path: p.relPath, action: 'written' });
316
+ }
317
+ // else: download failure, warning already recorded by planDocs; skip the
318
+ // write but still record the manifest entry below so the doc isn't lost.
319
+ }
320
+ else {
321
+ fs_1.default.writeFileSync(targetAbs, p.doc.body, 'utf8');
322
+ files.push({ path: p.relPath, action: 'written' });
323
+ }
324
+ manifestDocs[p.relPath] = {
325
+ id: p.doc.id,
326
+ title: p.doc.title,
327
+ current_revision_id: p.doc.current_revision_id,
328
+ media: p.isMedia,
329
+ body_sha256: p.bodySha256,
330
+ };
331
+ }
332
+ return { manifestDocs, files };
333
+ }
334
+ /**
335
+ * Core implementation — accepts an injected config so tests can point at a
336
+ * stub server without touching the filesystem config.
337
+ */
338
+ async function docsPullWithConfig(folderPath, dest, options, config) {
339
+ const destInput = dest ?? `./${lastSegment(folderPath)}`;
340
+ const destination = path_1.default.resolve(destInput);
341
+ // Captured once, before the walk, so deletion propagation (below) can diff
342
+ // against the folder tree as it stood before this pull. Already read below
343
+ // for overwrite protection — hoisted here rather than read twice.
344
+ const previousManifest = fs_1.default.existsSync(destination) ? (0, docs_manifest_1.readManifest)(destination) : null;
345
+ let usedSingleDocFallback = false;
346
+ // Overwrite-confirm: warn + confirm on a non-empty destination before any network I/O.
347
+ // The unpushed-local-changes conflict refusal (detectLocalModifications) happens later,
348
+ // in report() — only once the server walk is known can it tell a real conflict (the
349
+ // doc still exists remotely) from an edited orphan (kept + warned, no flag needed).
350
+ if (fs_1.default.existsSync(destination)) {
351
+ if (!fs_1.default.statSync(destination).isDirectory()) {
352
+ process.stderr.write(chalk_1.default.red(`error: destination "${destination}" exists and is not a directory.\n`));
353
+ process.exit(1);
354
+ }
355
+ const entries = fs_1.default.readdirSync(destination);
356
+ if (entries.length > 0 && !options.yes && !options.overwrite) {
357
+ console.log(chalk_1.default.yellow(`Destination "${destination}" is not empty (${entries.length} items).`));
358
+ console.log(chalk_1.default.yellow('Pulling will overwrite existing files.'));
359
+ const response = await (0, prompts_1.default)({
360
+ type: 'confirm',
361
+ name: 'proceed',
362
+ message: 'Continue?',
363
+ initial: false,
364
+ });
365
+ if (!response.proceed) {
366
+ console.log(chalk_1.default.gray('Cancelled.'));
367
+ process.exit(0);
368
+ }
369
+ }
370
+ }
371
+ // Manifest-clobber protection: a manifest tracking a DIFFERENT folder than the one
372
+ // being pulled must never be silently replaced — every file it tracks would become
373
+ // untracked, and detectLocalModifications only protects tracked files. This must run
374
+ // before any network I/O (listTree/planDocs) and before detectLocalModifications, since
375
+ // a mismatched manifest can't meaningfully speak for the folder being pulled anyway.
376
+ // --overwrite already means "discard local-edit protection", so it bypasses this too.
377
+ if (previousManifest !== null && previousManifest.folder_path !== folderPath && !options.overwrite) {
378
+ process.stderr.write(chalk_1.default.red(`error: "${destination}" already tracks "${previousManifest.folder_path}".\n`));
379
+ process.stderr.write(chalk_1.default.red(`Pulling "${folderPath}" here would replace its manifest, and local edits to the\n`));
380
+ process.stderr.write(chalk_1.default.red('previously tracked files would no longer be protected from being overwritten.\n'));
381
+ process.stderr.write(chalk_1.default.red('Pull into a different directory, or pass --overwrite to replace the manifest.\n'));
382
+ process.exit(1);
383
+ }
384
+ let rows;
385
+ const listResult = await listTree(config, folderPath);
386
+ if (listResult.ok) {
387
+ rows = listResult.rows;
388
+ }
389
+ else if (listResult.isRoot && listResult.code === 'folder_path_not_found') {
390
+ // Single-doc fallback: the target might be a doc path, not a folder.
391
+ usedSingleDocFallback = true;
392
+ const dir = path_1.default.dirname(folderPath);
393
+ const title = path_1.default.basename(folderPath);
394
+ const readArgs = { action: 'read', path: dir === '.' ? { title } : { folder_path: dir, title } };
395
+ const readResult = await (0, mcp_1.callDocsTool)(config, 'docs_vault', readArgs);
396
+ if (!readResult.ok) {
397
+ const readCode = readResult.data?.code ?? 'unknown_error';
398
+ const readMessage = readResult.data?.message ?? 'MCP returned an error with no message';
399
+ process.stderr.write(chalk_1.default.red(`error: ${listResult.code}: ${listResult.message}\n`));
400
+ process.stderr.write(chalk_1.default.red(`error: ${readCode}: ${readMessage}\n`));
401
+ process.exit(1);
402
+ }
403
+ const data = readResult.data;
404
+ const fetched = [{
405
+ id: data.id,
406
+ title: data.title,
407
+ relative: '',
408
+ body: data.body ?? '',
409
+ current_revision_id: data.current_revision_id ?? null,
410
+ properties: data.properties ?? {},
411
+ }];
412
+ await report(destination, folderPath, fetched, options, config, [], previousManifest, usedSingleDocFallback);
413
+ return;
414
+ }
415
+ else {
416
+ process.stderr.write(chalk_1.default.red(`error: ${listResult.code}: ${listResult.message}\n`));
417
+ process.exit(1);
418
+ return;
419
+ }
420
+ const { fetched, warnings: fetchWarnings } = await fetchBodies(config, rows);
421
+ await report(destination, folderPath, fetched, options, config, fetchWarnings, previousManifest, usedSingleDocFallback);
422
+ }
423
+ /** Write the docs + manifest to disk and print the result (chalk lines or --json). */
424
+ async function report(destination, folderPath, fetched, options, config, extraWarnings, previousManifest, usedSingleDocFallback) {
425
+ const { planned, warnings } = await planDocs(fetched, config);
426
+ // Unpushed-local-changes protection: now that the server walk is known, refuse only
427
+ // for a file whose doc still exists remotely — i.e. its relative path is part of this
428
+ // pull's plan and would be overwritten by commitDocs below. A modified file whose
429
+ // relPath is NOT in the plan is an orphan, not a conflict: it is left alone here and
430
+ // the deletion-propagation block further down keeps it and warns (no --overwrite
431
+ // needed). This check must run before commitDocs — nothing may be written to disk
432
+ // before a real conflict has had the chance to refuse.
433
+ if (previousManifest && !options.overwrite) {
434
+ const modified = detectLocalModifications(destination, previousManifest);
435
+ const plannedPaths = new Set(planned.map((p) => p.relPath));
436
+ const conflicts = modified.filter((relPath) => plannedPaths.has(relPath));
437
+ if (conflicts.length > 0) {
438
+ const noun = conflicts.length === 1 ? 'file has' : 'files have';
439
+ process.stderr.write(chalk_1.default.red(`${conflicts.length} ${noun} unpushed local changes:\n`));
440
+ for (const file of conflicts) {
441
+ process.stderr.write(chalk_1.default.red(` ${file}\n`));
442
+ }
443
+ process.stderr.write(chalk_1.default.red('push your changes first, or pass --overwrite to discard them.\n'));
444
+ process.exit(1);
445
+ }
446
+ }
447
+ fs_1.default.mkdirSync(destination, { recursive: true });
448
+ const { manifestDocs, files } = commitDocs(destination, planned);
449
+ // Identity of every file this pull actually wrote, keyed by dev:ino. Used by the
450
+ // deletion-propagation loop below to recognize an "orphan" that is really just the
451
+ // same file this pull wrote under a different manifest key (e.g. a case-only title
452
+ // rename on a case-insensitive filesystem) — that file must never be deleted.
453
+ const writtenIdentities = new Set();
454
+ for (const file of files) {
455
+ try {
456
+ const stat = fs_1.default.statSync(path_1.default.join(destination, ...file.path.split('/')));
457
+ writtenIdentities.add(`${stat.dev}:${stat.ino}`);
458
+ }
459
+ catch {
460
+ continue;
461
+ }
462
+ }
463
+ const manifest = { folder_path: folderPath, docs: manifestDocs };
464
+ (0, docs_manifest_1.writeManifest)(destination, manifest);
465
+ for (const warning of [...extraWarnings, ...warnings]) {
466
+ process.stderr.write(chalk_1.default.yellow(`${warning}\n`));
467
+ }
468
+ const removed = [];
469
+ const keptModified = [];
470
+ // Deletion propagation is only safe when the old manifest describes the SAME
471
+ // folder we just pulled. Otherwise every tracked file looks like an orphan and
472
+ // the unmodified ones would be deleted. The single-doc fallback writes a
473
+ // one-entry manifest, so it can never speak for a folder's contents either.
474
+ const canPropagateDeletions = previousManifest !== null &&
475
+ !usedSingleDocFallback &&
476
+ previousManifest.folder_path === folderPath;
477
+ if (previousManifest !== null && !canPropagateDeletions) {
478
+ if (usedSingleDocFallback) {
479
+ process.stderr.write(chalk_1.default.yellow("deletions not propagated: single-doc pull cannot speak for a folder's contents\n"));
480
+ }
481
+ else if (previousManifest.folder_path !== folderPath) {
482
+ process.stderr.write(chalk_1.default.yellow(`deletions not propagated: this directory tracks "${previousManifest.folder_path}", not "${folderPath}"\n`));
483
+ }
484
+ }
485
+ const keptModifiedMedia = new Set();
486
+ if (canPropagateDeletions) {
487
+ const destPrefix = path_1.default.resolve(destination) + path_1.default.sep;
488
+ const realDest = fs_1.default.realpathSync(destination);
489
+ for (const [relPath, entry] of Object.entries(previousManifest.docs)) {
490
+ if (manifestDocs[relPath])
491
+ continue;
492
+ const absPath = path_1.default.resolve(destination, ...relPath.split('/'));
493
+ // Containment: a hand-edited or corrupt manifest key such as "../../etc/passwd"
494
+ // would otherwise resolve outside the pull destination. `docs pull` never writes
495
+ // such a key (titles are sanitized), but this loop is the only code in the CLI
496
+ // that deletes files — never let it act on a path it did not create.
497
+ if (!absPath.startsWith(destPrefix))
498
+ continue;
499
+ // Only ever remove regular files. A directory here means a corrupt manifest;
500
+ // rmSync would throw mid-pull, leaving a half-deleted tree.
501
+ //
502
+ // The whole entry is guarded: the new manifest is already on disk by now, so an
503
+ // uncaught throw would abort the report, silently skip every later orphan, and
504
+ // print a raw stack trace instead of this command's normal error format. One bad
505
+ // entry must cost only that entry.
506
+ try {
507
+ const stat = fs_1.default.statSync(absPath);
508
+ if (!stat.isFile())
509
+ continue;
510
+ // Physical containment: the lexical check above only guards the string. If
511
+ // an intermediate path segment (e.g. "sub" in "sub/x.png") is a symlink to a
512
+ // directory OUTSIDE the destination, statSync/readFileSync/rmSync all follow
513
+ // it transparently. Resolve the real parent directory and require it to
514
+ // physically live under the real destination before ever touching the file.
515
+ const realParent = fs_1.default.realpathSync(path_1.default.dirname(absPath));
516
+ if (realParent !== realDest && !realParent.startsWith(realDest + path_1.default.sep))
517
+ continue;
518
+ // Identity: never delete a file this pull just wrote. A case-only title
519
+ // rename on a case-insensitive filesystem (or a hand-edited manifest with a
520
+ // hardlinked entry) can make an "orphan" key resolve to the very file the
521
+ // new manifest just wrote under a different key — bytes trivially match.
522
+ const identity = `${stat.dev}:${stat.ino}`;
523
+ if (writtenIdentities.has(identity))
524
+ continue;
525
+ const currentHash = (0, docs_manifest_1.sha256Hex)(fs_1.default.readFileSync(absPath));
526
+ if (entry.body_sha256 != null && entry.body_sha256 === currentHash) {
527
+ fs_1.default.rmSync(absPath);
528
+ removed.push(relPath);
529
+ }
530
+ else {
531
+ keptModified.push(relPath);
532
+ if (entry.media)
533
+ keptModifiedMedia.add(relPath);
534
+ }
535
+ }
536
+ catch {
537
+ // Vanished mid-run, unreadable, or refuses inspection: never delete blind.
538
+ continue;
539
+ }
540
+ }
541
+ }
542
+ if (options.json) {
543
+ console.log(JSON.stringify({ manifest, files, removed, kept_modified: keptModified }));
544
+ process.exit(0);
545
+ }
546
+ console.log(chalk_1.default.green(`pulled ${files.length} doc${files.length === 1 ? '' : 's'} → ${destination}`));
547
+ for (const file of files) {
548
+ console.log(chalk_1.default.gray(` ${file.path}`));
549
+ }
550
+ for (const file of removed) {
551
+ console.log(chalk_1.default.gray(`- removed (deleted remotely): ${file}`));
552
+ }
553
+ for (const file of keptModified) {
554
+ process.stderr.write(chalk_1.default.yellow(`! kept ${file} — deleted remotely but modified locally\n`));
555
+ if (keptModifiedMedia.has(file)) {
556
+ process.stderr.write(chalk_1.default.yellow(' (it is now untracked; use `solidactions docs upload` to re-create it)\n'));
557
+ }
558
+ else {
559
+ process.stderr.write(chalk_1.default.yellow(' (it is now untracked; `docs push` will re-create it)\n'));
560
+ }
561
+ }
562
+ process.exit(0);
563
+ }
564
+ /**
565
+ * Entry point called from index.ts.
566
+ */
567
+ async function docsPull(folder, dest, options) {
568
+ const config = await (0, api_1.requireConfigWithWorkspace)();
569
+ await docsPullWithConfig(folder, dest, options, config);
570
+ }