@solidactions/cli 3.23.0 → 3.25.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.
@@ -24,6 +24,9 @@ exports.sha256Hex = exports.DOCS_MANIFEST = void 0;
24
24
  exports.sanitizeSegment = sanitizeSegment;
25
25
  exports.sanitizeTitle = sanitizeTitle;
26
26
  exports.docPullWithConfig = docPullWithConfig;
27
+ exports.decideOutcomes = decideOutcomes;
28
+ exports.buildManifest = buildManifest;
29
+ exports.manifestProblem = manifestProblem;
27
30
  exports.docPull = docPull;
28
31
  const fs_1 = __importDefault(require("fs"));
29
32
  const path_1 = __importDefault(require("path"));
@@ -32,17 +35,19 @@ const chalk_1 = __importDefault(require("chalk"));
32
35
  const prompts_1 = __importDefault(require("prompts"));
33
36
  const api_1 = require("../utils/api");
34
37
  const mcp_1 = require("../utils/mcp");
38
+ const source_provenance_1 = require("../utils/source-provenance");
35
39
  const docs_manifest_1 = require("../utils/docs-manifest");
36
40
  Object.defineProperty(exports, "DOCS_MANIFEST", { enumerable: true, get: function () { return docs_manifest_1.DOCS_MANIFEST; } });
37
41
  Object.defineProperty(exports, "sha256Hex", { enumerable: true, get: function () { return docs_manifest_1.sha256Hex; } });
38
- /** Extension appended to a media file's sanitized title when the title itself has none. */
39
- const MIME_EXTENSIONS = {
40
- 'image/png': '.png',
41
- 'image/jpeg': '.jpg',
42
- 'image/gif': '.gif',
43
- 'image/webp': '.webp',
44
- 'application/pdf': '.pdf',
45
- };
42
+ const doc_pull_writes_1 = require("../utils/doc-pull-writes");
43
+ /** Extension appended to a media file's sanitized title when the title itself has none. A Map: a server MIME is never an inherited name (PM ruling 14). */
44
+ const MIME_EXTENSIONS = new Map([
45
+ ['image/png', '.png'],
46
+ ['image/jpeg', '.jpg'],
47
+ ['image/gif', '.gif'],
48
+ ['image/webp', '.webp'],
49
+ ['application/pdf', '.pdf'],
50
+ ]);
46
51
  const CHUNK_SIZE = 50;
47
52
  /** Characters that are unsafe as filesystem path segments, plus control chars. */
48
53
  // eslint-disable-next-line no-control-regex
@@ -69,6 +74,21 @@ function sanitizeSegment(name) {
69
74
  function sanitizeTitle(title) {
70
75
  return sanitizeSegment(title);
71
76
  }
77
+ /** Server-derived text (a title, code, message, or a path built from titles and folder names) as printed (cli#189). Display only. */
78
+ function shown(value) {
79
+ return (0, source_provenance_1.sanitizeDisplayText)(value, 1024) ?? '(untitled)';
80
+ }
81
+ /**
82
+ * Command error boundary (cli#189): an escaping error — a filesystem throw
83
+ * embedding a server-derived path, or a server-bearing exception like
84
+ * `McpRpcError` — prints through shown() like every other server-derived
85
+ * message. Keeps the diagnostic meaning; exits 1, as the top-level handler
86
+ * would.
87
+ */
88
+ function reportWriteError(error) {
89
+ process.stderr.write(chalk_1.default.red(`error: ${shown(error instanceof Error ? error.message : String(error))}\n`));
90
+ process.exit(1);
91
+ }
72
92
  /**
73
93
  * A doc is a media *candidate* when the bulk_read row carries blob metadata
74
94
  * and an empty body. This is a cheap pre-filter, not authoritative — the
@@ -94,16 +114,20 @@ async function resolveMedia(config, doc) {
94
114
  if (confirm.status === 404 && confirm.data?.code === 'media_not_found') {
95
115
  return { isMedia: false };
96
116
  }
117
+ if (confirm.status === 401) {
118
+ process.stderr.write(chalk_1.default.red((0, api_1.authFailedLine)(config.host)) + '\n');
119
+ process.exit(1);
120
+ }
97
121
  if (confirm.status !== 200) {
98
122
  const code = confirm.data?.code ?? 'unknown_error';
99
123
  const message = confirm.data?.message ?? 'media confirm request failed';
100
- process.stderr.write(chalk_1.default.red(`error: ${code}: ${message}\n`));
124
+ process.stderr.write(chalk_1.default.red(`error: ${shown(code)}: ${shown(message)}\n`));
101
125
  process.exit(1);
102
126
  }
103
127
  const { url, mime } = confirm.data;
104
128
  const download = await axios_1.default.get(url, { responseType: 'arraybuffer', validateStatus: () => true });
105
129
  if (download.status !== 200) {
106
- return { isMedia: true, mime, bytes: null, warning: `warn: failed to download media for doc ${doc.id} (${doc.title}): HTTP ${download.status}` };
130
+ return { isMedia: true, mime, bytes: null, warning: `warn: failed to download media for doc ${doc.id} (${shown(doc.title)}): HTTP ${download.status}` };
107
131
  }
108
132
  return { isMedia: true, mime, bytes: Buffer.from(download.data) };
109
133
  }
@@ -113,7 +137,7 @@ async function resolveMedia(config, doc) {
113
137
  * file is missing locally is never reported as modified — graceful
114
138
  * degradation to "no detection" rather than a false refusal.
115
139
  */
116
- function detectLocalModifications(destination, manifest) {
140
+ function detectLocalModifications(destination, manifest, seen) {
117
141
  const modified = [];
118
142
  for (const [relPath, entry] of Object.entries(manifest.docs)) {
119
143
  if (entry.body_sha256 == null)
@@ -125,18 +149,25 @@ function detectLocalModifications(destination, manifest) {
125
149
  try {
126
150
  stat = fs_1.default.statSync(absPath);
127
151
  }
128
- catch {
152
+ catch (error) {
153
+ if (error.code === 'ENOENT')
154
+ observe(seen, relPath, { kind: 'absent' });
129
155
  continue; // missing locally — graceful degradation, never a false refusal
130
156
  }
131
157
  if (!stat.isFile())
132
158
  continue;
133
159
  const currentHash = (0, docs_manifest_1.sha256Hex)(fs_1.default.readFileSync(absPath));
160
+ observe(seen, relPath, { kind: 'sha256', sha256: currentHash });
134
161
  if (currentHash !== entry.body_sha256) {
135
162
  modified.push(relPath);
136
163
  }
137
164
  }
138
165
  return modified;
139
166
  }
167
+ function observe(seen, relPath, state) {
168
+ if (!seen.has(relPath))
169
+ seen.set(relPath, state);
170
+ }
140
171
  /** The last non-empty path segment of a '/'-separated folder path. */
141
172
  function lastSegment(folderPath) {
142
173
  const segments = folderPath.split('/').filter(Boolean);
@@ -151,6 +182,23 @@ async function listTree(config, folderPath) {
151
182
  const rows = [];
152
183
  const queue = [{ folder_path: folderPath, relative: '' }];
153
184
  let first = true;
185
+ // Per parent folder: the segment each sanitised name was given, and the keys taken, so folders that differ
186
+ // only by case or normalisation (or take a reserved name) get distinct segments (cli#168).
187
+ const segmentsByParent = new Map();
188
+ const segmentFor = (parent, sanitized) => {
189
+ const taken = segmentsByParent.get(parent) ?? { given: new Map(), keys: new Set() };
190
+ segmentsByParent.set(parent, taken);
191
+ const known = taken.given.get(sanitized);
192
+ if (known !== undefined)
193
+ return known;
194
+ const start = (0, doc_pull_writes_1.isReservedName)(sanitized, docs_manifest_1.DOCS_MANIFEST) ? `_${sanitized}` : sanitized;
195
+ let segment = start;
196
+ for (let suffix = 2; taken.keys.has((0, doc_pull_writes_1.nameKey)(segment)); suffix++)
197
+ segment = `${start}-${suffix}`;
198
+ taken.given.set(sanitized, segment);
199
+ taken.keys.add((0, doc_pull_writes_1.nameKey)(segment));
200
+ return segment;
201
+ };
154
202
  while (queue.length > 0) {
155
203
  const { folder_path, relative } = queue.shift();
156
204
  const result = await (0, mcp_1.callDocsTool)(config, { action: 'list', folder_path });
@@ -162,7 +210,7 @@ async function listTree(config, folderPath) {
162
210
  }
163
211
  first = false;
164
212
  for (const folder of result.data?.folders ?? []) {
165
- const safeName = sanitizeSegment(folder.name);
213
+ const safeName = segmentFor(relative, sanitizeSegment(folder.name));
166
214
  const childRelative = relative ? `${relative}/${safeName}` : safeName;
167
215
  queue.push({ folder_path: folder.folder_path, relative: childRelative });
168
216
  }
@@ -182,17 +230,20 @@ async function listTree(config, folderPath) {
182
230
  const BULK_READ_OK_STATUS = 'found';
183
231
  /**
184
232
  * Fetch bodies + revisions for every collected row via bulk_read, chunked at
185
- * CHUNK_SIZE ids. A row whose status isn't `BULK_READ_OK_STATUS` (e.g. a
186
- * server-side `error` or `not_found`), or a requested id absent from the
187
- * response entirely, is soft-skipped: a warning naming the doc, no file
188
- * written, no manifest entry — mirroring the media download soft-skip.
233
+ * CHUNK_SIZE ids. A row whose status isn't `BULK_READ_OK_STATUS` (`error`,
234
+ * `not_found`, an unknown or a missing status), a `found` row without a
235
+ * string body (no `body` key, or `null`; `""` is content), or a requested id
236
+ * absent from the response entirely, is a doc the server still lists but whose
237
+ * content could not be fetched: it is returned in `failed`, never treated as gone
238
+ * (cli#209). Its file and tracking are left as they were, and the pull names
239
+ * it on one line and exits 1.
189
240
  */
190
241
  async function fetchBodies(config, rows) {
191
242
  const byId = new Map();
192
243
  for (const row of rows)
193
244
  byId.set(row.id, row);
194
245
  const fetched = [];
195
- const warnings = [];
246
+ const failed = [];
196
247
  for (let i = 0; i < rows.length; i += CHUNK_SIZE) {
197
248
  const chunk = rows.slice(i, i + CHUNK_SIZE);
198
249
  const result = await (0, mcp_1.callDocsTool)(config, {
@@ -202,34 +253,29 @@ async function fetchBodies(config, rows) {
202
253
  if (!result.ok) {
203
254
  const code = result.data?.code ?? 'unknown_error';
204
255
  const message = result.data?.message ?? 'MCP returned an error with no message';
205
- process.stderr.write(chalk_1.default.red(`error: ${code}: ${message}\n`));
256
+ process.stderr.write(chalk_1.default.red(`error: ${shown(code)}: ${shown(message)}\n`));
206
257
  process.exit(1);
207
258
  }
208
259
  const resultRows = result.data?.results ?? [];
209
- const seenIds = new Set();
260
+ const fetchedIds = new Set();
210
261
  for (const row of resultRows) {
211
262
  const original = byId.get(row.id);
212
- if (!original)
263
+ if (!original || row.status !== BULK_READ_OK_STATUS || typeof row.body !== 'string')
213
264
  continue;
214
- seenIds.add(row.id);
215
- if (row.status !== BULK_READ_OK_STATUS) {
216
- warnings.push(`warn: skipping doc ${row.id} (${original.title}): bulk_read returned status "${row.status ?? 'unknown'}"`);
217
- continue;
218
- }
265
+ fetchedIds.add(row.id);
219
266
  fetched.push({
220
267
  ...original,
221
- body: row.body ?? '',
268
+ body: row.body,
222
269
  current_revision_id: row.current_revision_id ?? null,
223
270
  properties: row.properties ?? {},
224
271
  });
225
272
  }
226
273
  for (const requested of chunk) {
227
- if (!seenIds.has(requested.id)) {
228
- warnings.push(`warn: skipping doc ${requested.id} (${requested.title}): missing from bulk_read results`);
229
- }
274
+ if (!fetchedIds.has(requested.id))
275
+ failed.push(requested);
230
276
  }
231
277
  }
232
- return { fetched, warnings };
278
+ return { fetched, failed };
233
279
  }
234
280
  /**
235
281
  * Fill in the doc type for fetched docs whose list row did not carry a
@@ -257,23 +303,27 @@ async function backfillDocTypes(config, fetched) {
257
303
  // valid untyped doc, not a failure — warn only when the type could
258
304
  // not be read at all.
259
305
  if (!readOk) {
260
- warnings.push(`warn: could not read the type of doc ${doc.id} (${doc.title}); writing it as .md`);
306
+ warnings.push(`warn: could not read the type of doc ${doc.id} (${shown(doc.title)}); writing it as .md`);
261
307
  }
262
308
  doc.docType = slug;
263
309
  doc.docTypeKnown = true;
264
310
  }
265
311
  return warnings;
266
312
  }
313
+ /** A name the pull keeps for itself (the manifest, its lock, the temp-file prefix) takes a leading `_`; the usual `-N` suffix cannot leave a reserved prefix. */
314
+ const withoutReservedName = (base, ext) => ((0, doc_pull_writes_1.isReservedName)(`${base}${ext}`, docs_manifest_1.DOCS_MANIFEST) ? `_${base}` : base);
267
315
  /**
268
316
  * Allocate the first free `<base>[ -N]<ext>` name not present in `used`,
269
- * recording the winner in `used`.
317
+ * recording the winner in `used`. Names are compared by `nameKey` (NFC, case-folded), so two
318
+ * docs that differ only by case or by Unicode normalisation never share a file (cli#168).
270
319
  */
271
320
  function allocateName(used, base, ext) {
272
- let candidate = base;
321
+ const first = withoutReservedName(base, ext);
322
+ let candidate = first;
273
323
  let suffix = 2;
274
- const usedFolded = new Set([...used].map((name) => name.toLowerCase()));
275
- while (usedFolded.has(`${candidate}${ext}`.toLowerCase())) {
276
- candidate = `${base}-${suffix}`;
324
+ const usedKeys = new Set([...used].map(doc_pull_writes_1.nameKey));
325
+ while (usedKeys.has((0, doc_pull_writes_1.nameKey)(`${candidate}${ext}`))) {
326
+ candidate = `${first}-${suffix}`;
277
327
  suffix++;
278
328
  }
279
329
  const fileName = `${candidate}${ext}`;
@@ -309,8 +359,10 @@ function isCollisionVariant(file, base, ext) {
309
359
  * reallocates. Folder pulls reserve only paths whose title, directory and
310
360
  * extension stay unchanged, keeping their exact spelling regardless of list
311
361
  * order without reserving the old names of docs that move away.
362
+ * `heldPaths` are the tracked paths of listed docs whose content could not be
363
+ * fetched (cli#209): they keep their file and entry, so no doc is given one.
312
364
  */
313
- async function planDocs(docs, config, reserved, previousManifest) {
365
+ async function planDocs(docs, config, reserved, previousManifest, heldPaths = []) {
314
366
  const planned = [];
315
367
  const warnings = [];
316
368
  const usedNamesByDir = new Map();
@@ -319,6 +371,13 @@ async function planDocs(docs, config, reserved, previousManifest) {
319
371
  usedNamesByDir.set(dir, new Set(names));
320
372
  }
321
373
  }
374
+ for (const rel of heldPaths) {
375
+ const slash = rel.lastIndexOf('/');
376
+ const dir = slash === -1 ? '' : rel.slice(0, slash);
377
+ const used = usedNamesByDir.get(dir) ?? new Set();
378
+ used.add(rel.slice(slash + 1));
379
+ usedNamesByDir.set(dir, used);
380
+ }
322
381
  const pathById = reserved?.pathById ?? new Map();
323
382
  const titleById = reserved?.titleById ?? new Map();
324
383
  if (!reserved && previousManifest) {
@@ -345,7 +404,7 @@ async function planDocs(docs, config, reserved, previousManifest) {
345
404
  }
346
405
  else {
347
406
  base = sanitized;
348
- ext = (media.mime && MIME_EXTENSIONS[media.mime]) ?? '';
407
+ ext = (media.mime && MIME_EXTENSIONS.get(media.mime)) ?? '';
349
408
  }
350
409
  }
351
410
  else if (doc.docType === 'visual') {
@@ -363,7 +422,7 @@ async function planDocs(docs, config, reserved, previousManifest) {
363
422
  }
364
423
  else {
365
424
  // Download failure: warning already recorded above; the doc is still
366
- // tracked (manifest entry written by commitDocs) but there is nothing
425
+ // tracked (manifest entry recorded after the writes) but there is nothing
367
426
  // to write to disk.
368
427
  bodySha256 = null;
369
428
  }
@@ -380,7 +439,7 @@ async function planDocs(docs, config, reserved, previousManifest) {
380
439
  const slash = ownRelPath.lastIndexOf('/');
381
440
  const ownDir = slash === -1 ? '' : ownRelPath.slice(0, slash);
382
441
  const ownFile = slash === -1 ? ownRelPath : ownRelPath.slice(slash + 1);
383
- return ownDir === doc.relative && isCollisionVariant(ownFile, base, ext) ? ownRelPath : undefined;
442
+ return ownDir === doc.relative && !(0, doc_pull_writes_1.isReservedName)(ownFile, docs_manifest_1.DOCS_MANIFEST) && isCollisionVariant(ownFile, base, ext) ? ownRelPath : undefined;
384
443
  };
385
444
  if (!reserved) {
386
445
  for (const { doc, base, ext } of prepared) {
@@ -410,42 +469,16 @@ async function planDocs(docs, config, reserved, previousManifest) {
410
469
  }
411
470
  return { planned, warnings };
412
471
  }
413
- /**
414
- * Write every planned doc to disk under `destination` and build the
415
- * manifest docs map. The only step in the whole pull that creates
416
- * directories or writes/overwrites files — called only after every refusal
417
- * (unpushed local changes, rename conflicts, a target that is not a regular
418
- * file) has had its chance, so it never stops half-way or clobbers a file
419
- * the caller decided to keep.
420
- */
421
- function commitDocs(destination, planned) {
422
- const manifestDocs = {};
423
- const files = [];
424
- for (const p of planned) {
425
- const dirAbs = p.dirRel ? path_1.default.join(destination, ...p.dirRel.split('/')) : destination;
426
- fs_1.default.mkdirSync(dirAbs, { recursive: true });
427
- const targetAbs = path_1.default.join(dirAbs, p.fileName);
428
- if (p.isMedia) {
429
- if (p.mediaBytes) {
430
- fs_1.default.writeFileSync(targetAbs, p.mediaBytes);
431
- files.push({ path: p.relPath, action: 'written' });
432
- }
433
- // else: download failure, warning already recorded by planDocs; skip the
434
- // write but still record the manifest entry below so the doc isn't lost.
435
- }
436
- else {
437
- fs_1.default.writeFileSync(targetAbs, p.doc.body, 'utf8');
438
- files.push({ path: p.relPath, action: 'written' });
439
- }
440
- manifestDocs[p.relPath] = {
441
- id: p.doc.id,
442
- title: p.doc.title,
443
- current_revision_id: p.doc.current_revision_id,
444
- media: p.isMedia,
445
- body_sha256: p.bodySha256,
446
- };
447
- }
448
- return { manifestDocs, files };
472
+ /** The manifest entry for a planned doc, in the shape the manifest stores. Writes nothing. */
473
+ function manifestEntryFor(p) {
474
+ // A failed media download writes nothing, but its entry (no hash) is still how the doc is tracked.
475
+ return {
476
+ id: p.doc.id,
477
+ title: p.doc.title,
478
+ current_revision_id: p.doc.current_revision_id,
479
+ media: p.isMedia,
480
+ body_sha256: p.bodySha256,
481
+ };
449
482
  }
450
483
  /**
451
484
  * Manifest-clobber protection, against the RESOLVED folder: the argument itself for a folder
@@ -456,19 +489,82 @@ function refuseManifestClobber(previousManifest, resolvedFolder, argument, desti
456
489
  if (previousManifest === null || previousManifest.folder_path === resolvedFolder || options.overwrite) {
457
490
  return;
458
491
  }
459
- process.stderr.write(chalk_1.default.red(`error: "${destination}" already tracks "${previousManifest.folder_path}".\n`));
460
- process.stderr.write(chalk_1.default.red(`Pulling "${argument}" here would replace its manifest, and local edits to the\n`));
492
+ process.stderr.write(chalk_1.default.red(`error: "${shown(destination)}" already tracks "${shown(previousManifest.folder_path)}".\n`));
493
+ process.stderr.write(chalk_1.default.red(`Pulling "${shown(argument)}" here would replace its manifest, and local edits to the\n`));
461
494
  process.stderr.write(chalk_1.default.red('previously tracked files would no longer be protected from being overwritten.\n'));
462
495
  process.stderr.write(chalk_1.default.red('Pull into a different directory, or pass --overwrite to replace the manifest.\n'));
463
496
  process.exit(1);
464
497
  }
498
+ /** True when `abs` is an existing directory; any stat failure is left to the destination checks below. */
499
+ function isExistingDirectory(abs) {
500
+ try {
501
+ return fs_1.default.statSync(abs).isDirectory();
502
+ }
503
+ catch {
504
+ return false;
505
+ }
506
+ }
507
+ /**
508
+ * Take the destination's lock (spec §1.4): one O_EXCL file, `<destination>/.solidactions-docs.json.lock`, holding this
509
+ * pid. An existing one refuses with nothing else changed; it is never removed or liveness-tested except by the pull that
510
+ * created it, so a killed pull's lock stays until the user deletes it.
511
+ */
512
+ function takeLock(destination, lock) {
513
+ try {
514
+ (0, doc_pull_writes_1.acquireLock)(destination, docs_manifest_1.DOCS_MANIFEST);
515
+ }
516
+ catch (error) {
517
+ if (error instanceof doc_pull_writes_1.LockHeldError) {
518
+ process.stderr.write(chalk_1.default.red(`error: ${shown(path_1.default.join(destination, error.lockName))} exists: another doc pull may be writing to ${shown(destination)}. If none is running, delete that file and pull again.\n`));
519
+ process.exit(1);
520
+ }
521
+ try {
522
+ fs_1.default.readdirSync(destination);
523
+ }
524
+ catch (readError) {
525
+ process.stderr.write(chalk_1.default.red(`error: cannot read ${shown(destination)}: ${shown(readError.message)}\n`));
526
+ process.exit(1);
527
+ }
528
+ process.stderr.write(chalk_1.default.red(`error: cannot write ${shown((0, doc_pull_writes_1.lockNameFor)(docs_manifest_1.DOCS_MANIFEST))}: ${shown(error.message)} — nothing was changed.\n`));
529
+ process.exit(1);
530
+ }
531
+ lock.destination = destination;
532
+ }
465
533
  /**
466
534
  * Core implementation — accepts an injected config so tests can point at a
467
535
  * stub server without touching the filesystem config.
468
536
  */
469
537
  async function docPullWithConfig(folderPath, dest, options, config) {
538
+ // The lock taken below is removed on every way out: a process.exit anywhere in the pull (refusal, error, a "no"
539
+ // at the prompt) runs the exit listener, and an interrupt exits through it too. Only a SIGKILL leaves it (spec §1.6).
540
+ const lock = { destination: null };
541
+ const releaseHeld = () => {
542
+ if (lock.destination !== null)
543
+ (0, doc_pull_writes_1.releaseLock)(lock.destination, docs_manifest_1.DOCS_MANIFEST);
544
+ lock.destination = null;
545
+ };
546
+ const onInterrupt = () => process.exit(130);
547
+ const onTerminate = () => process.exit(143);
548
+ process.on('exit', releaseHeld);
549
+ process.on('SIGINT', onInterrupt);
550
+ process.on('SIGTERM', onTerminate);
551
+ try {
552
+ await pullInto(folderPath, dest, options, config, lock);
553
+ }
554
+ finally {
555
+ process.removeListener('exit', releaseHeld);
556
+ process.removeListener('SIGINT', onInterrupt);
557
+ process.removeListener('SIGTERM', onTerminate);
558
+ releaseHeld();
559
+ }
560
+ }
561
+ async function pullInto(folderPath, dest, options, config, lock) {
470
562
  const destInput = dest ?? `./${lastSegment(folderPath)}`;
471
563
  const destination = path_1.default.resolve(destInput);
564
+ // cli#168: take the lock before anything reads the destination, so the plan below is built on a manifest
565
+ // no other pull can change while this one runs (spec §1.3 step 1, §1.4).
566
+ if (isExistingDirectory(destination))
567
+ takeLock(destination, lock);
472
568
  // Captured once, before the walk, so deletion propagation (below) can diff
473
569
  // against the folder tree as it stood before this pull. Already read below
474
570
  // for overwrite protection — hoisted here rather than read twice.
@@ -479,13 +575,26 @@ async function docPullWithConfig(folderPath, dest, options, config) {
479
575
  // in report() — only once the server walk is known can it tell a real conflict (the
480
576
  // doc still exists remotely) from an edited orphan (kept + warned, no flag needed).
481
577
  if (fs_1.default.existsSync(destination)) {
482
- if (!fs_1.default.statSync(destination).isDirectory()) {
483
- process.stderr.write(chalk_1.default.red(`error: destination "${destination}" exists and is not a directory.\n`));
578
+ let entries;
579
+ try {
580
+ if (!fs_1.default.statSync(destination).isDirectory()) {
581
+ process.stderr.write(chalk_1.default.red(`error: destination "${shown(destination)}" exists and is not a directory.\n`));
582
+ process.exit(1);
583
+ }
584
+ entries = fs_1.default.readdirSync(destination).filter((name) => name !== (0, doc_pull_writes_1.lockNameFor)(docs_manifest_1.DOCS_MANIFEST));
585
+ }
586
+ catch (error) {
587
+ // cli#191: one line naming the destination, never a raw scandir stack.
588
+ process.stderr.write(chalk_1.default.red(`error: cannot read ${shown(destination)}: ${shown(error.message)}\n`));
484
589
  process.exit(1);
485
590
  }
486
- const entries = fs_1.default.readdirSync(destination);
487
591
  if (entries.length > 0 && !options.yes && !options.overwrite) {
488
- console.log(chalk_1.default.yellow(`Destination "${destination}" is not empty (${entries.length} items).`));
592
+ if (process.stdin.isTTY !== true) {
593
+ // cli#176: nobody can answer the prompt; a script must not read "Cancelled" as success.
594
+ process.stderr.write(chalk_1.default.red(`error: ${shown(destination)} is not empty and there is no terminal to confirm the pull; pass -y to pull into it.\n`));
595
+ process.exit(1);
596
+ }
597
+ console.log(chalk_1.default.yellow(`Destination "${shown(destination)}" is not empty (${entries.length} items).`));
489
598
  console.log(chalk_1.default.yellow("Pulling overwrites tracked files; local files the folder doesn't track are refused unless --overwrite."));
490
599
  const response = await (0, prompts_1.default)({
491
600
  type: 'confirm',
@@ -519,36 +628,32 @@ async function docPullWithConfig(folderPath, dest, options, config) {
519
628
  if (!readResult.ok) {
520
629
  const readCode = readResult.data?.code ?? 'unknown_error';
521
630
  const readMessage = readResult.data?.message ?? 'MCP returned an error with no message';
522
- process.stderr.write(chalk_1.default.red(`error: ${listResult.code}: ${listResult.message}\n`));
523
- process.stderr.write(chalk_1.default.red(`error: ${readCode}: ${readMessage}\n`));
631
+ process.stderr.write(chalk_1.default.red(`error: ${shown(listResult.code)}: ${shown(listResult.message)}\n`));
632
+ process.stderr.write(chalk_1.default.red(`error: ${shown(readCode)}: ${shown(readMessage)}\n`));
524
633
  process.exit(1);
525
634
  }
526
635
  const data = readResult.data;
527
- const fetched = [{
528
- id: data.id,
529
- title: data.title,
530
- relative: '',
531
- docType: data.doc_type?.slug ?? null,
532
- docTypeKnown: true,
533
- body: data.body ?? '',
534
- current_revision_id: data.current_revision_id ?? null,
535
- properties: data.properties ?? {},
536
- }];
636
+ const row = { id: data.id, title: data.title, relative: '', docType: data.doc_type?.slug ?? null, docTypeKnown: true };
637
+ // An answer without a string body (no `body` key, or `null`) is a failed fetch, as in a folder pull (cli#209).
638
+ const hasBody = typeof data.body === 'string';
639
+ const fetched = hasBody
640
+ ? [{ ...row, body: data.body, current_revision_id: data.current_revision_id ?? null, properties: data.properties ?? {} }]
641
+ : [];
537
642
  // The doc's real folder, not the argument (cli#153): a later `doc push` creates
538
643
  // untracked files under the manifest's folder_path.
539
644
  const docFolder = typeof data.folder_path === 'string' ? data.folder_path : (dir === '.' ? '' : dir);
540
645
  refuseManifestClobber(previousManifest, docFolder, folderPath, destination, options);
541
- await report(destination, docFolder, fetched, options, config, [], previousManifest, usedSingleDocFallback);
646
+ await report(destination, docFolder, fetched, options, config, [], previousManifest, usedSingleDocFallback, new Set([data.id]), lock, hasBody ? [] : [row]);
542
647
  return;
543
648
  }
544
649
  else {
545
- process.stderr.write(chalk_1.default.red(`error: ${listResult.code}: ${listResult.message}\n`));
650
+ process.stderr.write(chalk_1.default.red(`error: ${shown(listResult.code)}: ${shown(listResult.message)}\n`));
546
651
  process.exit(1);
547
652
  return;
548
653
  }
549
- const { fetched, warnings: fetchWarnings } = await fetchBodies(config, rows);
654
+ const { fetched, failed } = await fetchBodies(config, rows);
550
655
  const typeWarnings = await backfillDocTypes(config, fetched);
551
- await report(destination, folderPath, fetched, options, config, [...fetchWarnings, ...typeWarnings], previousManifest, usedSingleDocFallback);
656
+ await report(destination, folderPath, fetched, options, config, typeWarnings, previousManifest, usedSingleDocFallback, new Set(rows.map((row) => row.id)), lock, failed);
552
657
  }
553
658
  /**
554
659
  * Safety guards shared by deletion propagation and rename cleanup (cli#157):
@@ -635,8 +740,8 @@ function linkOnTheWay(destination, rel) {
635
740
  return null;
636
741
  }
637
742
  function refuseLink(rel, link, doc) {
638
- const where = link === rel ? '' : ` (or sits under one: ${link})`;
639
- process.stderr.write(chalk_1.default.red(`error: ${rel} is a symbolic link${where}; this pull would write doc ${doc.id} ("${doc.title}") through it.\n`));
743
+ const where = link === rel ? '' : ` (or sits under one: ${shown(link)})`;
744
+ process.stderr.write(chalk_1.default.red(`error: ${shown(rel)} is a symbolic link${where}; this pull would write doc ${doc.id} ("${shown(doc.title)}") through it.\n`));
640
745
  process.stderr.write(chalk_1.default.red('Replace it with a regular file or folder and pull again.\n'));
641
746
  process.exit(1);
642
747
  }
@@ -644,7 +749,7 @@ function refuseLink(rel, link, doc) {
644
749
  function explainUnresolvable(label, error) {
645
750
  const code = error.code ?? 'ERROR';
646
751
  const reason = code === 'ELOOP' ? 'too many symbolic links (ELOOP). Fix or remove the link and pull again.' : `${code} ${error.message}.`;
647
- process.stderr.write(chalk_1.default.red(`error: cannot resolve ${label}: ${reason}\n`));
752
+ process.stderr.write(chalk_1.default.red(`error: cannot resolve ${shown(label)}: ${shown(reason)}\n`));
648
753
  process.exit(1);
649
754
  }
650
755
  /** physicalTargetPath, but a resolution error becomes one line (spec §2.3). A planned target with a link on the way gets the symbolic-link refusal. */
@@ -665,7 +770,7 @@ function resolveOrExplain(destination, rel, target) {
665
770
  /**
666
771
  * Refuse, before any write, a pull that would write a planned doc through a
667
772
  * symbolic link or to a place that resolves outside the destination. Covers
668
- * every planned doc, including a failed media download: commitDocs still
773
+ * every planned doc, including a failed media download: the write still
669
774
  * creates its directory. Also refuse, unless `--overwrite`, a planned write
670
775
  * over a regular file the pull does not own (cli#167): one the previous
671
776
  * manifest does not track with a hash and whose bytes differ from the
@@ -673,7 +778,7 @@ function resolveOrExplain(destination, rel, target) {
673
778
  * rename's own source file (a case-only retitle on a case-insensitive
674
779
  * filesystem) is never "untracked".
675
780
  */
676
- function checkPlannedWrites(destination, planned, previousManifest, options, renameMoves) {
781
+ function checkPlannedWrites(destination, planned, previousManifest, options, renameMoves, seen) {
677
782
  // First, so a destination that is itself a looping link gets one line, not a raw ELOOP from the sidecar check below.
678
783
  let realDest;
679
784
  try {
@@ -701,7 +806,7 @@ function checkPlannedWrites(destination, planned, previousManifest, options, ren
701
806
  const physical = resolveOrExplain(destination, p.relPath, p.doc);
702
807
  // Belt and braces behind linkOnTheWay, which refuses every link first; kept in case the physical path ever diverges without one.
703
808
  if (physical !== realDest && !physical.startsWith(realDest + path_1.default.sep)) {
704
- process.stderr.write(chalk_1.default.red(`error: ${p.relPath} resolves outside the destination (${physical}); this pull would write doc ${p.doc.id} ("${p.doc.title}") there.\n`));
809
+ process.stderr.write(chalk_1.default.red(`error: ${shown(p.relPath)} resolves outside the destination (${shown(physical)}); this pull would write doc ${p.doc.id} ("${shown(p.doc.title)}") there.\n`));
705
810
  process.exit(1);
706
811
  }
707
812
  }
@@ -711,7 +816,7 @@ function checkPlannedWrites(destination, planned, previousManifest, options, ren
711
816
  for (const p of planned) {
712
817
  if (p.isMedia && p.mediaBytes === null)
713
818
  continue; // a failed download writes nothing
714
- const tracked = previousManifest?.docs[p.relPath];
819
+ const tracked = (0, docs_manifest_1.entryAt)(previousManifest, p.relPath);
715
820
  if (tracked !== undefined && tracked.body_sha256 != null)
716
821
  continue; // checked as unpushed local changes
717
822
  const targetAbs = path_1.default.join(destination, ...p.relPath.split('/'));
@@ -725,11 +830,14 @@ function checkPlannedWrites(destination, planned, previousManifest, options, ren
725
830
  }
726
831
  catch (error) {
727
832
  const code = error.code ?? 'ERROR';
728
- if (code === 'ENOENT')
833
+ if (code === 'ENOENT') {
834
+ observe(seen, p.relPath, { kind: 'absent' });
729
835
  continue; // absent: nothing to overwrite here
836
+ }
730
837
  untracked.push(`${p.relPath} (cannot be read: ${code})`); // present but unverifiable: not owned
731
838
  continue;
732
839
  }
840
+ observe(seen, p.relPath, { kind: 'sha256', sha256: (0, docs_manifest_1.sha256Hex)(current) });
733
841
  if ((0, docs_manifest_1.sha256Hex)(current) === p.bodySha256)
734
842
  continue;
735
843
  const ownSource = renameMoves.find((m) => m.id === p.doc.id)?.sourceIdentity;
@@ -741,13 +849,370 @@ function checkPlannedWrites(destination, planned, previousManifest, options, ren
741
849
  const one = untracked.length === 1;
742
850
  process.stderr.write(chalk_1.default.red(`${untracked.length} ${one ? 'file exists' : 'files exist'} locally but ${one ? 'is' : 'are'} not tracked:\n`));
743
851
  for (const rel of untracked)
744
- process.stderr.write(chalk_1.default.red(` ${rel}\n`));
852
+ process.stderr.write(chalk_1.default.red(` ${shown(rel)}\n`));
745
853
  process.stderr.write(chalk_1.default.red('Move them aside and pull again, or pass --overwrite to replace them.\n'));
746
854
  process.exit(1);
747
855
  }
748
856
  }
857
+ /** True when anything at all (a link included) is at `abs`. */
858
+ function entryExists(abs) {
859
+ try {
860
+ fs_1.default.lstatSync(abs);
861
+ return true;
862
+ }
863
+ catch {
864
+ return false;
865
+ }
866
+ }
867
+ /** The error code and Node's description of a filesystem failure, without the path Node appends: `EACCES: permission denied`. */
868
+ function describeError(error) {
869
+ const match = /^[A-Z0-9]+: ([^,]+)/.exec(error instanceof Error ? error.message : '');
870
+ return match === null ? errnoOf(error) : `${errnoOf(error)}: ${match[1]}`;
871
+ }
872
+ /** What `lstat` finds at `rel`: nothing (only ENOENT), the entry, or why it cannot be checked. */
873
+ function inspect(destination, rel) {
874
+ try {
875
+ return { kind: 'entry', stat: fs_1.default.lstatSync(path_1.default.join(destination, ...rel.split('/'))) };
876
+ }
877
+ catch (error) {
878
+ return errnoOf(error) === 'ENOENT' ? { kind: 'absent' } : { kind: 'error', reason: `cannot check it (${describeError(error)})` };
879
+ }
880
+ }
881
+ /**
882
+ * What is at a path a doc's outcome depends on (cli#168, issuecomment-6025529901): `absent` only on ENOENT; a regular file
883
+ * (no link) and the hash of its bytes; otherwise a refusal naming why the pull cannot vouch for it.
884
+ */
885
+ function localState(destination, rel) {
886
+ const found = inspect(destination, rel);
887
+ if (found.kind === 'absent')
888
+ return found;
889
+ if (found.kind === 'error')
890
+ return { kind: 'refused', reason: found.reason };
891
+ if (found.stat.isDirectory())
892
+ return { kind: 'refused', reason: 'is a folder, not a file' };
893
+ if (found.stat.isSymbolicLink())
894
+ return { kind: 'refused', reason: 'is a symbolic link, not a file' };
895
+ if (!found.stat.isFile())
896
+ return { kind: 'refused', reason: 'is not a regular file' };
897
+ try {
898
+ return { kind: 'file', hash: (0, docs_manifest_1.sha256Hex)(fs_1.default.readFileSync(path_1.default.join(destination, ...rel.split('/')))) };
899
+ }
900
+ catch (error) {
901
+ return { kind: 'refused', reason: `cannot read it (${describeError(error)})` };
902
+ }
903
+ }
904
+ /**
905
+ * One outcome per planned doc, after the writes: the files this pull placed, and for every other doc what its
906
+ * manifest entry should be (cli#183, cli#190, cli#167). A failed download keeps the tracking it had while the file at its
907
+ * path is the one the entry names; a doc the pull never got to keeps its earlier entry. An earlier entry with a hash is
908
+ * kept only while a file is at its path: a missing file drops the doc's tracking with a warning (manager ruling on cli#168,
909
+ * issuecomment-6013479498, I1(b)), so the gate never meets a kept entry with a hash for a missing file.
910
+ * "Missing" is only ENOENT: every path an outcome depends on is classified by `localState`, and an inspection error or a
911
+ * non-regular entry there makes the outcome carry a `refusal`, which the gate refuses the manifest with, so no tracking is
912
+ * dropped or relabelled (cli#168, issuecomment-6025529901).
913
+ * `pendingWarnings` receives the `! …` lines printed after a successful pull.
914
+ */
915
+ function decideOutcomes(destination, planned, placedPaths, stopped, previousManifest, folderPath, renameMoves, listedIds, pendingWarnings) {
916
+ const outcomes = [];
917
+ const earlierById = new Map();
918
+ if (previousManifest !== null && previousManifest.folder_path === folderPath) {
919
+ for (const [relPath, entry] of Object.entries(previousManifest.docs)) {
920
+ const earlier = earlierById.get(entry.id) ?? new Map();
921
+ earlier.set(relPath, entry);
922
+ earlierById.set(entry.id, earlier);
923
+ }
924
+ }
925
+ const renamedIds = new Set(renameMoves.map((m) => m.id));
926
+ const plannedIds = new Set(planned.map((q) => q.doc.id));
927
+ const failedDownload = (p) => p.isMedia && p.mediaBytes === null;
928
+ for (const p of planned) {
929
+ const entry = manifestEntryFor(p);
930
+ if (!failedDownload(p)) {
931
+ if (placedPaths.has(p.relPath)) {
932
+ // A stopped pull never removes a renamed doc's old twin, so that file keeps its tracking too (listed first, so
933
+ // the next pull sees the rename and finishes it). A twin that is gone keeps no entry (I1(b)); one the pull
934
+ // cannot vouch for keeps its entry and refuses the manifest. A complete pull retires the old entry (cli#157),
935
+ // but an old name it cannot even check could hold edits nobody verified, so that refuses too; a folder or a
936
+ // link there is still nothing to keep or remove.
937
+ const move = renameMoves.find((m) => m.id === p.doc.id);
938
+ const oldEntry = move === undefined ? undefined : (0, docs_manifest_1.entryAt)(previousManifest, move.oldRel);
939
+ const outcome = { id: p.doc.id, kind: 'placed', placed: new Map([[p.relPath, entry]]), kept: new Map() };
940
+ if (move?.sourceError !== undefined) {
941
+ if (oldEntry !== undefined)
942
+ outcome.kept.set(move.oldRel, oldEntry);
943
+ outcome.refusal = { rel: move.oldRel, reason: move.sourceError };
944
+ }
945
+ else if (move !== undefined && oldEntry !== undefined && stopped) {
946
+ const old = localState(destination, move.oldRel);
947
+ if (old.kind !== 'absent')
948
+ outcome.kept.set(move.oldRel, oldEntry);
949
+ if (old.kind === 'refused')
950
+ outcome.refusal = { rel: move.oldRel, reason: old.reason };
951
+ }
952
+ else if (move !== undefined && oldEntry !== undefined) {
953
+ const old = inspect(destination, move.oldRel);
954
+ if (old.kind === 'error')
955
+ outcome.refusal = { rel: move.oldRel, reason: old.reason };
956
+ }
957
+ outcomes.push(outcome);
958
+ }
959
+ else {
960
+ outcomes.push({ id: p.doc.id, kind: 'refused', placed: new Map(), kept: new Map(earlierById.get(p.doc.id)) });
961
+ }
962
+ continue;
963
+ }
964
+ if (renamedIds.has(p.doc.id))
965
+ continue; // decided with its rename below
966
+ // cli#183: a failed download at a path the previous manifest tracked for the same doc keeps
967
+ // that entry unchanged (revision and hash), as a failed rename does: nothing was written,
968
+ // so the manifest must not claim a newer revision or drop the hash of the file still there.
969
+ // The entry is kept only while the file is the one it names: exactly its hash (INV-C), or no file for an entry
970
+ // with no hash. A missing file drops the tracking (I1(b)).
971
+ //
972
+ // cli#167: a media doc whose download failed must not be tracked over a
973
+ // local file the previous manifest does not track, with a hash, for that
974
+ // same doc: nothing is written, so the manifest would claim bytes the
975
+ // pull never gave it. A rename keeps its restore-old-entry handling below.
976
+ //
977
+ // cli#190: if that local file is another doc's (tracked with a hash at this path), that
978
+ // doc's tracking is kept when it is still on the server and not moved by this pull.
979
+ //
980
+ // An inspection error or a non-regular entry at the path is never "absent": the doc keeps its earlier entries
981
+ // and the gate refuses the manifest. The previous owner's entry is never replaced by this doc's id with no hash.
982
+ const tracked = (0, docs_manifest_1.entryAt)(previousManifest, p.relPath);
983
+ const local = localState(destination, p.relPath);
984
+ if (local.kind === 'refused') {
985
+ outcomes.push({ id: p.doc.id, kind: 'refused', placed: new Map(), kept: new Map(earlierById.get(p.doc.id)), refusal: { rel: p.relPath, reason: local.reason } });
986
+ continue;
987
+ }
988
+ const ownEntry = tracked !== undefined && tracked.id === p.doc.id ? tracked : undefined;
989
+ if (ownEntry !== undefined && (ownEntry.body_sha256 == null ? local.kind === 'absent' : local.kind === 'file' && local.hash === ownEntry.body_sha256)) {
990
+ outcomes.push({ id: p.doc.id, kind: 'kept-previous', placed: new Map(), kept: new Map([[p.relPath, ownEntry]]) });
991
+ continue;
992
+ }
993
+ if (ownEntry !== undefined && ownEntry.body_sha256 != null && local.kind === 'absent') {
994
+ outcomes.push({ id: p.doc.id, kind: 'dropped', placed: new Map(), kept: new Map() });
995
+ pendingWarnings.push(`! doc ${p.doc.id} ("${shown(p.doc.title)}") failed to download and ${shown(p.relPath)} is not present locally; not tracking it — pull again later.`);
996
+ continue;
997
+ }
998
+ const otherOwner = tracked !== undefined && tracked.id !== p.doc.id ? tracked : undefined;
999
+ if (local.kind === 'absent' && otherOwner === undefined) {
1000
+ outcomes.push({ id: p.doc.id, kind: 'placed', placed: new Map([[p.relPath, entry]]), kept: new Map() });
1001
+ continue;
1002
+ }
1003
+ const otherDoc = otherOwner !== undefined && otherOwner.body_sha256 != null ? otherOwner : undefined;
1004
+ outcomes.push({ id: p.doc.id, kind: 'dropped', placed: new Map(), kept: new Map() });
1005
+ if (otherDoc !== undefined && local.kind === 'file' && local.hash === otherDoc.body_sha256 && listedIds.has(otherDoc.id) && !plannedIds.has(otherDoc.id)) {
1006
+ outcomes.push({ id: otherDoc.id, kind: 'kept-previous', placed: new Map(), kept: new Map([[p.relPath, otherDoc]]) });
1007
+ pendingWarnings.push(`! doc ${p.doc.id} ("${shown(p.doc.title)}") failed to download and ${shown(p.relPath)} holds doc ${otherDoc.id}'s file ("${shown(otherDoc.title)}"); still tracking it as doc ${otherDoc.id} — pull again later`);
1008
+ continue;
1009
+ }
1010
+ // A pull that stopped keeps every earlier entry of a doc it has no outcome for, so it takes no tracking from that doc.
1011
+ const lost = otherOwner === undefined || stopped ? '' : ` Doc ${otherOwner.id} ("${shown(otherOwner.title)}") was tracked at ${shown(p.relPath)} before and is no longer tracked there.`;
1012
+ if (local.kind === 'absent') {
1013
+ pendingWarnings.push(`! doc ${p.doc.id} ("${shown(p.doc.title)}") failed to download and ${shown(p.relPath)} is not present locally; not tracking it — pull again later.${lost}`);
1014
+ }
1015
+ else {
1016
+ pendingWarnings.push(`! doc ${p.doc.id} ("${shown(p.doc.title)}") failed to download and ${shown(p.relPath)} holds a local file; not tracking it — pull again later.${lost}`);
1017
+ }
1018
+ }
1019
+ // A rename whose replacement is NOT written (a failed media download plans a new path but
1020
+ // writes nothing) keeps its old file and its old manifest entry: deleting it would destroy
1021
+ // the only good copy. An old entry with a hash whose file is gone is not kept (I1(b)): the doc is then not
1022
+ // tracked at all, neither at the old path nor (with no hash) at a new path that may hold an untracked file. The
1023
+ // refusals in `report` guarantee no other doc in this pull claims that old path.
1024
+ for (const m of renameMoves) {
1025
+ if (m.replacementWritten)
1026
+ continue;
1027
+ const oldEntry = (0, docs_manifest_1.entryAt)(previousManifest, m.oldRel);
1028
+ const local = m.sourceError === undefined ? localState(destination, m.oldRel) : { kind: 'refused', reason: m.sourceError };
1029
+ if (local.kind === 'refused') {
1030
+ outcomes.push({ id: m.id, kind: 'refused', placed: new Map(), kept: new Map(earlierById.get(m.id)), refusal: { rel: m.oldRel, reason: local.reason } });
1031
+ continue;
1032
+ }
1033
+ if (oldEntry !== undefined && oldEntry.body_sha256 != null && local.kind === 'absent') {
1034
+ outcomes.push({ id: m.id, kind: 'dropped', placed: new Map(), kept: new Map() });
1035
+ pendingWarnings.push(`! doc ${m.id} ("${shown(m.title)}") failed to download and ${shown(m.oldRel)} is not present locally; not tracking it — pull again later.`);
1036
+ continue;
1037
+ }
1038
+ outcomes.push({ id: m.id, kind: 'kept-previous', placed: new Map(), kept: oldEntry === undefined ? new Map() : new Map([[m.oldRel, oldEntry]]) });
1039
+ if (local.kind === 'file') {
1040
+ pendingWarnings.push(`! kept ${shown(m.oldRel)} — doc ${m.id} download failed; still tracked as ${shown(m.oldRel)}`);
1041
+ }
1042
+ else {
1043
+ pendingWarnings.push(`! doc ${m.id} download failed; still tracked as ${shown(m.oldRel)}, which is not present locally`);
1044
+ }
1045
+ }
1046
+ return outcomes;
1047
+ }
1048
+ /**
1049
+ * The manifest as a pure function of the previous manifest, the outcomes and whether this pull speaks for one doc
1050
+ * (spec §1.3, rule 3). A single-doc pull, or one that stopped before it could propagate deletions, keeps every earlier
1051
+ * entry whose doc has no outcome (cli#153); an outcome's own doc never gets its earlier entries back. Bytes this run
1052
+ * placed always win: an earlier entry at a name a placed entry holds, or one equal to it under `nameKey`, is dropped, and
1053
+ * the doc that lost it gets a "no longer tracked there" line in `pendingWarnings` (a doc's own old twin loses silently).
1054
+ * The overlap is settled here, before anything is collapsed by name, so no retained entry can stand for placed bytes.
1055
+ * Entries are collected in a Map and published as a null-prototype dictionary, so every path is an own key (PM ruling 14).
1056
+ */
1057
+ function buildManifest(folderPath, previousManifest, outcomes, keepUnlisted, pendingWarnings) {
1058
+ const placedByKey = new Map();
1059
+ for (const outcome of outcomes) {
1060
+ for (const [relPath, entry] of outcome.placed)
1061
+ placedByKey.set((0, doc_pull_writes_1.nameKey)(relPath), { relPath, entry });
1062
+ }
1063
+ const docs = new Map();
1064
+ const warned = new Set();
1065
+ const keep = (relPath, entry) => {
1066
+ const winner = placedByKey.get((0, doc_pull_writes_1.nameKey)(relPath));
1067
+ if (winner === undefined) {
1068
+ docs.set(relPath, entry);
1069
+ return;
1070
+ }
1071
+ if (winner.entry.id !== entry.id && !warned.has(relPath)) {
1072
+ warned.add(relPath);
1073
+ pendingWarnings.push(`! ${shown(winner.relPath)} now holds the file this pull wrote for doc ${winner.entry.id} ("${shown(winner.entry.title)}"); doc ${entry.id} ("${shown(entry.title)}") was tracked at ${shown(relPath)} before and is no longer tracked there`);
1074
+ }
1075
+ };
1076
+ if (keepUnlisted && previousManifest !== null && previousManifest.folder_path === folderPath) {
1077
+ const outcomeIds = new Set(outcomes.map((outcome) => outcome.id));
1078
+ for (const [relPath, entry] of Object.entries(previousManifest.docs)) {
1079
+ if (!outcomeIds.has(entry.id))
1080
+ keep(relPath, entry);
1081
+ }
1082
+ }
1083
+ for (const outcome of outcomes) {
1084
+ for (const [relPath, entry] of outcome.kept)
1085
+ keep(relPath, entry);
1086
+ for (const [relPath, entry] of outcome.placed)
1087
+ docs.set(relPath, entry);
1088
+ }
1089
+ return { folder_path: folderPath, docs: (0, docs_manifest_1.docsFrom)(docs) };
1090
+ }
1091
+ /** The error code of a filesystem failure, for the gate's wording. */
1092
+ const errnoOf = (error) => error.code ?? 'ERROR';
1093
+ /**
1094
+ * INV-C as a runtime gate (spec §1.2, rule 4), checked just before the manifest is written, on the FINAL manifest: no two
1095
+ * of its paths may be one entry on some filesystem, every file this run placed must be in it with the hash this run wrote
1096
+ * (PM ruling 14: a placed file the manifest would not record refuses), and every entry with a hash must be one this run
1097
+ * can vouch for:
1098
+ * - A file this run placed (`placedFiles`): it must be a regular file with the `dev:ino` this run renamed in, and the
1099
+ * entry must be the hash of the bytes it wrote. The bytes are read back; only a permission failure (EACCES, or EPERM,
1100
+ * the same failure on some platforms) on that same file (a write-only mode it kept from the file it replaced) falls
1101
+ * back to the hash this run wrote.
1102
+ * - An entry kept for a doc this run acted on (a kept-previous outcome, or the old twin of a placed rename): lstat must
1103
+ * show a regular file (no link, no folder) whose bytes hash to the entry. A missing file refuses like any other lstat
1104
+ * or read failure: `decideOutcomes` keeps no such entry.
1105
+ * - An entry carried unchanged for a doc this run did not write (a refused doc's, or one it never listed) was not
1106
+ * touched by this run, and is not read: a folder or an edited file at that name is the refusal's own state.
1107
+ * The three exceptions to PM ruling 13 (a refused doc's carried entry is not read; a kept entry's missing file is NOT
1108
+ * one; EPERM like EACCES for a placed file) are the manager ruling on cli#168, issuecomment-6013479498.
1109
+ * First of all, an outcome's own `refusal` (a path it depends on that `decideOutcomes` could not vouch for: an inspection
1110
+ * error or a non-regular entry, cli#168 issuecomment-6025529901) is the problem.
1111
+ * Returns the first problem, or null.
1112
+ */
1113
+ function manifestProblem(destination, manifest, outcomes, placedFiles) {
1114
+ for (const outcome of outcomes) {
1115
+ if (outcome.refusal !== undefined)
1116
+ return outcome.refusal;
1117
+ }
1118
+ const byKey = new Map();
1119
+ for (const rel of Object.keys(manifest.docs)) {
1120
+ const key = (0, doc_pull_writes_1.nameKey)(rel);
1121
+ const other = byKey.get(key);
1122
+ if (other !== undefined)
1123
+ return { rel, reason: `the same file as ${other} on a case-insensitive or Unicode-normalising filesystem` };
1124
+ byKey.set(key, rel);
1125
+ }
1126
+ for (const [rel, placed] of placedFiles) {
1127
+ const entry = (0, docs_manifest_1.entryAt)(manifest, rel);
1128
+ if (entry === undefined)
1129
+ return { rel, reason: 'this pull wrote it but the manifest would not record it' };
1130
+ if (entry.body_sha256 !== placed.hash)
1131
+ return { rel, reason: 'its bytes are not the ones the manifest would record' };
1132
+ }
1133
+ const verified = new Set();
1134
+ for (const outcome of outcomes) {
1135
+ if (outcome.kind === 'refused')
1136
+ continue;
1137
+ for (const rel of outcome.kept.keys())
1138
+ verified.add(rel);
1139
+ }
1140
+ for (const [rel, entry] of Object.entries(manifest.docs)) {
1141
+ if (entry.body_sha256 == null)
1142
+ continue;
1143
+ const placed = placedFiles.get(rel);
1144
+ if (placed === undefined && !verified.has(rel))
1145
+ continue;
1146
+ const abs = path_1.default.join(destination, ...rel.split('/'));
1147
+ let stat;
1148
+ try {
1149
+ stat = fs_1.default.lstatSync(abs);
1150
+ }
1151
+ catch (error) {
1152
+ if (errnoOf(error) !== 'ENOENT')
1153
+ return { rel, reason: `it cannot be checked (${errnoOf(error)})` };
1154
+ return { rel, reason: placed !== undefined ? 'the file this pull wrote is not there' : 'the file it tracks is not there' };
1155
+ }
1156
+ if (!stat.isFile())
1157
+ return { rel, reason: 'it is not a regular file now' };
1158
+ if (placed !== undefined && (placed.hash !== entry.body_sha256 || placed.identity !== `${stat.dev}:${stat.ino}`))
1159
+ return { rel, reason: 'its bytes are not the ones the manifest would record' };
1160
+ let actual;
1161
+ try {
1162
+ actual = (0, docs_manifest_1.sha256Hex)(fs_1.default.readFileSync(abs));
1163
+ }
1164
+ catch (error) {
1165
+ if (placed === undefined || (errnoOf(error) !== 'EACCES' && errnoOf(error) !== 'EPERM'))
1166
+ return { rel, reason: `it cannot be read back (${errnoOf(error)})` };
1167
+ actual = placed.hash;
1168
+ }
1169
+ if (actual !== entry.body_sha256)
1170
+ return { rel, reason: 'its bytes are not the ones the manifest would record' };
1171
+ }
1172
+ return null;
1173
+ }
1174
+ /**
1175
+ * The one line naming every listed doc whose content could not be fetched (cli#209), printed once the manifest step is
1176
+ * done; the caller exits 1. Nothing when every doc was fetched.
1177
+ */
1178
+ function reportFetchFailed(fetchFailed) {
1179
+ if (fetchFailed.length === 0)
1180
+ return;
1181
+ const names = fetchFailed.map((row) => `${row.id} ("${shown(row.title)}")`).join(', ');
1182
+ process.stderr.write(chalk_1.default.red(`error: could not fetch ${fetchFailed.length} doc(s) from the server: ${names} — their local files and tracking were left as they were; pull again.\n`));
1183
+ }
1184
+ /**
1185
+ * The line for the error or refusal the writes stopped at, then exit 1 (spec §1.5). `tracked` says the manifest
1186
+ * recorded the files written before the stop; when it did not, the manifest's own line already said so.
1187
+ */
1188
+ function reportStop(stop, planned, placed, writes, tracked) {
1189
+ const { relPath } = stop.write;
1190
+ const tail = tracked ? ` — ${placed.length} of ${writes.length} files were updated and are tracked` : '';
1191
+ if (stop.error instanceof doc_pull_writes_1.LinkOnTheWayError) {
1192
+ const linked = planned.find((q) => q.relPath === relPath);
1193
+ if (linked !== undefined)
1194
+ refuseLink(relPath, stop.error.component, linked.doc);
1195
+ }
1196
+ if (stop.error instanceof doc_pull_writes_1.PublicationRefusedError) {
1197
+ process.stderr.write(chalk_1.default.red(`error: ${shown(relPath)} changed after doc pull checked it${tail}${tracked ? '. Pull again, or pass --overwrite to replace it.' : ''}\n`));
1198
+ }
1199
+ else if (stop.error instanceof doc_pull_writes_1.UnsupportedTargetError) {
1200
+ // Ruling 9: a folder at a target is left alone, never moved or deleted.
1201
+ process.stderr.write(chalk_1.default.red(`error: ${shown(relPath)} is a folder (doc pull writes a file there)${tail}${tracked ? '. Move it aside and pull again.' : ''}\n`));
1202
+ }
1203
+ else {
1204
+ process.stderr.write(chalk_1.default.red(`error: cannot write ${shown(relPath)}: ${shown(stop.error.message)}${tail}${tracked ? '; pull again.' : ''}\n`));
1205
+ }
1206
+ process.exit(1);
1207
+ }
749
1208
  /** Write the docs + manifest to disk and print the result (chalk lines or --json). */
750
- async function report(destination, folderPath, fetched, options, config, extraWarnings, previousManifest, usedSingleDocFallback) {
1209
+ async function report(destination, folderPath, fetched, options, config, extraWarnings, previousManifest, usedSingleDocFallback, listedIds, lock, fetchFailed) {
1210
+ // A listed doc whose content could not be fetched (cli#209) is refused: its earlier entries are carried unchanged
1211
+ // and its file is not touched, so no other doc is planned at those paths. A doc with no earlier entry is not tracked.
1212
+ const fetchFailedIds = new Set(fetchFailed.map((row) => row.id));
1213
+ const heldEntries = new Map(previousManifest !== null && previousManifest.folder_path === folderPath
1214
+ ? Object.entries(previousManifest.docs).filter(([, entry]) => fetchFailedIds.has(entry.id))
1215
+ : []);
751
1216
  // Single-doc fallback merging into a manifest that tracks the same folder
752
1217
  // must not steal a filename another tracked doc owns (cli#153 C1): the
753
1218
  // pulled doc reuses its own tracked path, and the allocator avoids every
@@ -772,7 +1237,23 @@ async function report(destination, folderPath, fetched, options, config, extraWa
772
1237
  }
773
1238
  reserved = { usedNames, pathById, titleById };
774
1239
  }
775
- const { planned, warnings } = await planDocs(fetched, config, reserved, previousManifest);
1240
+ const { planned, warnings } = await planDocs(fetched, config, reserved, previousManifest, [...heldEntries.keys()]);
1241
+ const seen = new Map();
1242
+ // Two docs whose names are one entry on some filesystem (case, Unicode normalisation) can never both keep
1243
+ // their own bytes: refuse before anything is written (cli#168).
1244
+ const plannedByKey = new Map();
1245
+ for (const p of planned) {
1246
+ if (p.isMedia && p.mediaBytes === null)
1247
+ continue; // a failed download writes nothing
1248
+ const key = (0, doc_pull_writes_1.nameKey)(p.relPath);
1249
+ const other = plannedByKey.get(key);
1250
+ if (other !== undefined) {
1251
+ process.stderr.write(chalk_1.default.red(`error: ${shown(other.relPath)} (doc ${other.doc.id}) and ${shown(p.relPath)} (doc ${p.doc.id}) would be the same file on a case-insensitive or Unicode-normalising filesystem; this pull would write different docs through those names.\n`));
1252
+ process.stderr.write(chalk_1.default.red('Nothing was written. Rename one of the docs on the server and pull again.\n'));
1253
+ process.exit(1);
1254
+ }
1255
+ plannedByKey.set(key, p);
1256
+ }
776
1257
  // Same doc id under a different path is a rename (PM ruling 2, cli#157):
777
1258
  // the previous manifest tracks a planned doc under a DIFFERENT path `old`,
778
1259
  // whatever is on disk at `old` (cli#157 FR4-C1). What is at `old` decides
@@ -798,26 +1279,30 @@ async function report(destination, folderPath, fetched, options, config, extraWa
798
1279
  continue;
799
1280
  const absOld = path_1.default.join(destination, ...old.split('/'));
800
1281
  let sourceStat = null;
1282
+ let sourceError;
801
1283
  try {
802
1284
  const stat = fs_1.default.statSync(absOld);
803
1285
  if (stat.isFile())
804
1286
  sourceStat = stat;
805
1287
  }
806
- catch {
1288
+ catch (error) {
807
1289
  sourceStat = null;
1290
+ // Only ENOENT is "no source"; any other failure is a source nobody could check for edits.
1291
+ if (errnoOf(error) !== 'ENOENT')
1292
+ sourceError = `cannot check it (${describeError(error)})`;
808
1293
  }
809
1294
  let modified = false;
810
1295
  let targetIsSource = false;
1296
+ let currentHash = null;
811
1297
  if (sourceStat !== null) {
812
- const entry = previousManifest.docs[old];
813
- let currentHash = null;
1298
+ const entry = (0, docs_manifest_1.entryAt)(previousManifest, old);
814
1299
  try {
815
1300
  currentHash = (0, docs_manifest_1.sha256Hex)(fs_1.default.readFileSync(absOld));
816
1301
  }
817
1302
  catch {
818
1303
  currentHash = null;
819
1304
  }
820
- modified = currentHash === null || currentHash !== entry.body_sha256;
1305
+ modified = currentHash === null || currentHash !== entry?.body_sha256;
821
1306
  try {
822
1307
  const targetStat = fs_1.default.statSync(path_1.default.join(destination, ...p.relPath.split('/')));
823
1308
  targetIsSource = targetStat.dev === sourceStat.dev && targetStat.ino === sourceStat.ino;
@@ -833,10 +1318,12 @@ async function report(destination, folderPath, fetched, options, config, extraWa
833
1318
  title: p.doc.title,
834
1319
  sourcePresent: sourceStat !== null,
835
1320
  sourceIdentity: sourceStat === null ? null : `${sourceStat.dev}:${sourceStat.ino}`,
1321
+ sourceHash: currentHash,
836
1322
  modified,
837
1323
  // A failed media download plans a new path but writes nothing there.
838
1324
  replacementWritten: !p.isMedia || p.mediaBytes !== null,
839
1325
  targetIsSource,
1326
+ ...(sourceError === undefined ? {} : { sourceError }),
840
1327
  });
841
1328
  }
842
1329
  const plannedPaths = new Map(planned.map((p) => [p.relPath, p]));
@@ -869,6 +1356,17 @@ async function report(destination, folderPath, fetched, options, config, extraWa
869
1356
  ?? (m.sourceIdentity === null
870
1357
  ? undefined
871
1358
  : plannedByIdentity.get(m.sourceIdentity)?.find((p) => p.doc.id !== m.id));
1359
+ // Rule 5 (spec §1.1) at every rename-source decision: a source already holding the bytes this pull writes for its
1360
+ // doc, or for the doc whose write lands on that file, holds no edit (an interrupted pull placed them, and the old
1361
+ // name aliases the placed file or another doc's write took it). Real edits are still refused below.
1362
+ const plannedByDocId = new Map(planned.map((p) => [p.doc.id, p]));
1363
+ for (const m of renameMoves) {
1364
+ if (!m.modified || m.sourceHash === null)
1365
+ continue;
1366
+ const pulledHere = [plannedByDocId.get(m.id), plannedTargetForSource(m)];
1367
+ if (pulledHere.some((q) => q !== undefined && q.bodySha256 !== null && q.bodySha256 === m.sourceHash))
1368
+ m.modified = false;
1369
+ }
872
1370
  // Edited sources cannot be discarded by --overwrite during a rename.
873
1371
  // Report a cross-doc collision first, including an alias's actual path.
874
1372
  for (const m of renameMoves) {
@@ -877,9 +1375,9 @@ async function report(destination, folderPath, fetched, options, config, extraWa
877
1375
  const taker = plannedTargetForSource(m);
878
1376
  if (!taker)
879
1377
  continue;
880
- const oldTitle = previousManifest.docs[m.oldRel]?.title ?? `#${m.id}`;
881
- process.stderr.write(chalk_1.default.red(`error: ${m.oldRel} holds unpublished edits for doc ${m.id} ("${oldTitle}", now written as ${m.newRel}), but this pull would write doc ${taker.doc.id} ("${taker.doc.title}") to ${taker.relPath}, the same file.\n`));
882
- process.stderr.write(chalk_1.default.red(`Move or rename the edited ${m.oldRel} (or push it first) and pull again.\n`));
1378
+ const oldTitle = (0, docs_manifest_1.entryAt)(previousManifest, m.oldRel)?.title ?? `#${m.id}`;
1379
+ process.stderr.write(chalk_1.default.red(`error: ${shown(m.oldRel)} holds unpublished edits for doc ${m.id} ("${shown(oldTitle)}", now written as ${shown(m.newRel)}), but this pull would write doc ${taker.doc.id} ("${shown(taker.doc.title)}") to ${shown(taker.relPath)}, the same file.\n`));
1380
+ process.stderr.write(chalk_1.default.red(`Move or rename the edited ${shown(m.oldRel)} (or push it first) and pull again.\n`));
883
1381
  process.exit(1);
884
1382
  }
885
1383
  // A rename whose replacement will not be written keeps its old file and
@@ -892,7 +1390,7 @@ async function report(destination, folderPath, fetched, options, config, extraWa
892
1390
  const taker = plannedTargetForSource(m);
893
1391
  if (!taker)
894
1392
  continue;
895
- process.stderr.write(chalk_1.default.red(`error: doc ${m.id} ("${m.title}") failed to download to ${m.newRel}, so ${m.oldRel} must keep its previous file and tracking, but this pull would put doc ${taker.doc.id} ("${taker.doc.title}") at ${taker.relPath}, the same file.\n`));
1393
+ process.stderr.write(chalk_1.default.red(`error: doc ${m.id} ("${shown(m.title)}") failed to download to ${shown(m.newRel)}, so ${shown(m.oldRel)} must keep its previous file and tracking, but this pull would put doc ${taker.doc.id} ("${shown(taker.doc.title)}") at ${shown(taker.relPath)}, the same file.\n`));
896
1394
  process.stderr.write(chalk_1.default.red('Nothing was written. Pull again once the download succeeds.\n'));
897
1395
  process.exit(1);
898
1396
  }
@@ -901,15 +1399,15 @@ async function report(destination, folderPath, fetched, options, config, extraWa
901
1399
  for (const m of renameMoves) {
902
1400
  if (m.replacementWritten || !m.modified)
903
1401
  continue;
904
- process.stderr.write(chalk_1.default.red(`error: ${m.oldRel} holds unpublished edits for doc ${m.id}, which is now ${m.newRel}, but its download failed.\n`));
905
- process.stderr.write(chalk_1.default.red(`Nothing was written. Push ${m.oldRel} first (or move it aside), then pull again once the download succeeds.\n`));
1402
+ process.stderr.write(chalk_1.default.red(`error: ${shown(m.oldRel)} holds unpublished edits for doc ${m.id}, which is now ${shown(m.newRel)}, but its download failed.\n`));
1403
+ process.stderr.write(chalk_1.default.red(`Nothing was written. Push ${shown(m.oldRel)} first (or move it aside), then pull again once the download succeeds.\n`));
906
1404
  process.exit(1);
907
1405
  }
908
1406
  const blocked = renameMoves.filter((m) => m.modified);
909
1407
  if (blocked.length > 0) {
910
1408
  for (const m of blocked) {
911
- process.stderr.write(chalk_1.default.red(`error: ${m.oldRel} holds unpublished edits for doc ${m.id} ("${m.title}"), which is now written as ${m.newRel}.\n`));
912
- process.stderr.write(chalk_1.default.red(`Nothing was written. Push ${m.oldRel} first (or move it aside) and pull again.\n`));
1409
+ process.stderr.write(chalk_1.default.red(`error: ${shown(m.oldRel)} holds unpublished edits for doc ${m.id} ("${shown(m.title)}"), which is now written as ${shown(m.newRel)}.\n`));
1410
+ process.stderr.write(chalk_1.default.red(`Nothing was written. Push ${shown(m.oldRel)} first (or move it aside) and pull again.\n`));
913
1411
  }
914
1412
  process.exit(1);
915
1413
  }
@@ -928,7 +1426,7 @@ async function report(destination, folderPath, fetched, options, config, extraWa
928
1426
  if (!writes.some((p) => renamedIds.has(p.doc.id)) && foldedPaths.size === writes.length)
929
1427
  continue;
930
1428
  const [first, second] = writes;
931
- process.stderr.write(chalk_1.default.red(`error: ${first.relPath} (doc ${first.doc.id}) and ${second.relPath} (doc ${second.doc.id}) are the same file on this filesystem; this pull would write different docs through those names.\n`));
1429
+ process.stderr.write(chalk_1.default.red(`error: ${shown(first.relPath)} (doc ${first.doc.id}) and ${shown(second.relPath)} (doc ${second.doc.id}) are the same file on this filesystem; this pull would write different docs through those names.\n`));
932
1430
  process.stderr.write(chalk_1.default.red('Nothing was written. Move the aliased files apart and pull again.\n'));
933
1431
  process.exit(1);
934
1432
  }
@@ -947,8 +1445,8 @@ async function report(destination, folderPath, fetched, options, config, extraWa
947
1445
  }
948
1446
  if (!isLink)
949
1447
  continue;
950
- process.stderr.write(chalk_1.default.red(`error: ${m.newRel} is a symbolic link; this pull would write doc ${m.id} ("${m.title}", renamed from ${m.oldRel}) through it.\n`));
951
- process.stderr.write(chalk_1.default.red(`Replace ${m.newRel} with a regular file (or remove it) and pull again.\n`));
1448
+ process.stderr.write(chalk_1.default.red(`error: ${shown(m.newRel)} is a symbolic link; this pull would write doc ${m.id} ("${shown(m.title)}", renamed from ${shown(m.oldRel)}) through it.\n`));
1449
+ process.stderr.write(chalk_1.default.red(`Replace ${shown(m.newRel)} with a regular file (or remove it) and pull again.\n`));
952
1450
  process.exit(1);
953
1451
  }
954
1452
  // A rename target holding an untracked local file (not in the previous
@@ -963,7 +1461,7 @@ async function report(destination, folderPath, fetched, options, config, extraWa
963
1461
  for (const m of renameMoves) {
964
1462
  if (!m.replacementWritten || m.targetIsSource)
965
1463
  continue;
966
- const targetEntry = previousManifest.docs[m.newRel];
1464
+ const targetEntry = (0, docs_manifest_1.entryAt)(previousManifest, m.newRel);
967
1465
  if (targetEntry !== undefined && targetEntry.body_sha256 != null)
968
1466
  continue;
969
1467
  const absNew = path_1.default.join(destination, ...m.newRel.split('/'));
@@ -976,15 +1474,19 @@ async function report(destination, folderPath, fetched, options, config, extraWa
976
1474
  }
977
1475
  catch (error) {
978
1476
  const code = error.code ?? 'ERROR';
979
- if (code === 'ENOENT')
1477
+ if (code === 'ENOENT') {
1478
+ observe(seen, m.newRel, { kind: 'absent' });
980
1479
  continue;
1480
+ }
981
1481
  unreadable = ` (cannot be read: ${code})`; // present but unverifiable: not owned
982
1482
  }
1483
+ if (existing !== null)
1484
+ observe(seen, m.newRel, { kind: 'sha256', sha256: (0, docs_manifest_1.sha256Hex)(existing) });
983
1485
  if (existing !== null && (0, docs_manifest_1.sha256Hex)(existing) === plannedPaths.get(m.newRel)?.bodySha256)
984
1486
  continue;
985
1487
  const state = (targetEntry === undefined ? 'exists locally but is not tracked' : `holds local bytes with no recorded hash (tracked for doc ${targetEntry.id})`) + unreadable;
986
- process.stderr.write(chalk_1.default.red(`error: ${m.newRel} ${state}; this pull would overwrite it with doc ${m.id} ("${m.title}", renamed from ${m.oldRel}).\n`));
987
- process.stderr.write(chalk_1.default.red(`Move ${m.newRel} aside and pull again, or pass --overwrite to replace it.\n`));
1488
+ process.stderr.write(chalk_1.default.red(`error: ${shown(m.newRel)} ${state}; this pull would overwrite it with doc ${m.id} ("${shown(m.title)}", renamed from ${shown(m.oldRel)}).\n`));
1489
+ process.stderr.write(chalk_1.default.red(`Move ${shown(m.newRel)} aside and pull again, or pass --overwrite to replace it.\n`));
988
1490
  process.exit(1);
989
1491
  }
990
1492
  }
@@ -992,65 +1494,112 @@ async function report(destination, folderPath, fetched, options, config, extraWa
992
1494
  const handledOldPaths = new Set(renameMoves.map((m) => m.oldRel));
993
1495
  // After the rename block (which keeps its own messages for rename cases) and before anything
994
1496
  // else that reads or writes the plan: no planned write may go through a link or outside.
995
- checkPlannedWrites(destination, planned, previousManifest, options, renameMoves);
1497
+ checkPlannedWrites(destination, planned, previousManifest, options, renameMoves, seen);
996
1498
  // Unpushed-local-changes protection: now that the server walk is known, refuse only
997
1499
  // for a file whose doc still exists remotely — i.e. its relative path is part of this
998
- // pull's plan and would be overwritten by commitDocs below. A modified file whose
1500
+ // pull's plan and would be overwritten by the writes below. A modified file whose
999
1501
  // relPath is NOT in the plan is an orphan, not a conflict: it is left alone here and
1000
1502
  // the deletion-propagation block further down keeps it and warns (no --overwrite
1001
- // needed). This check must run before commitDocs — nothing may be written to disk
1503
+ // needed). This check must run before any write — nothing may be written to disk
1002
1504
  // before a real conflict has had the chance to refuse.
1003
1505
  if (previousManifest && !options.overwrite) {
1004
- const modified = detectLocalModifications(destination, previousManifest);
1005
- const plannedPaths = new Set(planned.map((p) => p.relPath));
1006
- const conflicts = modified.filter((relPath) => plannedPaths.has(relPath));
1506
+ const modified = detectLocalModifications(destination, previousManifest, seen);
1507
+ const plannedByPath = new Map(planned.map((p) => [p.relPath, p]));
1508
+ // A file already holding the bytes this pull would write is never a conflict (spec §1.3): the next pull
1509
+ // after an interrupted or failed one adopts what that one placed.
1510
+ const conflicts = modified.filter((relPath) => {
1511
+ const p = plannedByPath.get(relPath);
1512
+ if (p === undefined)
1513
+ return false;
1514
+ const state = seen.get(relPath);
1515
+ return !(p.bodySha256 !== null && state?.kind === 'sha256' && state.sha256 === p.bodySha256);
1516
+ });
1007
1517
  if (conflicts.length > 0) {
1008
1518
  const noun = conflicts.length === 1 ? 'file has' : 'files have';
1009
1519
  process.stderr.write(chalk_1.default.red(`${conflicts.length} ${noun} unpushed local changes:\n`));
1010
1520
  for (const file of conflicts) {
1011
- process.stderr.write(chalk_1.default.red(` ${file}\n`));
1521
+ process.stderr.write(chalk_1.default.red(` ${shown(file)}\n`));
1012
1522
  }
1013
1523
  process.stderr.write(chalk_1.default.red('push your changes first, or pass --overwrite to discard them.\n'));
1014
1524
  process.exit(1);
1015
1525
  }
1016
1526
  }
1017
- // A destination path that already exists as a directory would make writeFileSync
1018
- // throw EISDIR mid-walk, after earlier docs were written and before the manifest
1019
- // is saved — a half-pulled tree with a stale sidecar. Refuse before any write.
1527
+ // A destination path that already exists as a directory would make the write fail mid-walk, after earlier
1528
+ // docs were written. Refuse before any write.
1020
1529
  for (const p of planned) {
1021
1530
  const targetAbs = path_1.default.join(destination, ...p.relPath.split('/'));
1022
1531
  if (fs_1.default.existsSync(targetAbs) && !fs_1.default.statSync(targetAbs).isFile()) {
1023
- 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`));
1532
+ process.stderr.write(chalk_1.default.red(`error: "${shown(p.relPath)}" exists and is not a regular file — cannot write doc ${p.doc.id} (${shown(p.doc.title)}).\n`));
1024
1533
  process.exit(1);
1025
1534
  }
1026
1535
  }
1536
+ // The state each target was authorized in is the state the checks above saw (spec §1.3 step 2); the write
1537
+ // refuses a target that is no longer in it (INV-B). Nothing is read again here. A target no check saw
1538
+ // is authorized as absent, so anything found there is refused.
1539
+ const faults = (0, doc_pull_writes_1.faultsFromEnv)();
1540
+ faults.afterChecks(destination);
1541
+ const writes = [];
1542
+ for (const p of planned) {
1543
+ const data = p.isMedia ? p.mediaBytes : p.doc.body;
1544
+ if (data === null)
1545
+ continue; // a failed media download writes nothing
1546
+ const authorized = options.overwrite ? { kind: 'any' } : (seen.get(p.relPath) ?? { kind: 'absent' });
1547
+ writes.push({ relPath: p.relPath, dirRel: p.dirRel, data, authorized });
1548
+ }
1549
+ // Every throw below can carry a server-derived path (a title-named file): the command
1550
+ // boundary in `docPull` prints it sanitised.
1027
1551
  fs_1.default.mkdirSync(destination, { recursive: true });
1552
+ if (lock.destination === null) {
1553
+ // A destination made just now was planned as new, with no manifest: take its lock, then check that no other
1554
+ // pull wrote one while this one was running (spec §1.3 step 1). The plan is built on the manifest read under
1555
+ // the lock, or the pull refuses before any write.
1556
+ takeLock(destination, lock);
1557
+ if (entryExists(path_1.default.join(destination, docs_manifest_1.DOCS_MANIFEST))) {
1558
+ process.stderr.write(chalk_1.default.red(`error: another doc pull wrote to ${shown(destination)} while this one was running — nothing was changed. Pull again.\n`));
1559
+ process.exit(1);
1560
+ }
1561
+ }
1028
1562
  const destPrefix = path_1.default.resolve(destination) + path_1.default.sep;
1029
1563
  const realDest = fs_1.default.realpathSync(destination);
1030
- const { manifestDocs, files } = commitDocs(destination, planned);
1031
- // cli#167: a media doc whose download failed must not be tracked over a
1032
- // local file the previous manifest does not track, with a hash, for that
1033
- // same doc: nothing was written, so the manifest would claim bytes the
1034
- // pull never gave it. A rename keeps its restore-old-entry handling below.
1035
- const renamedIds = new Set(renameMoves.map((m) => m.id));
1036
- for (const p of planned) {
1037
- if (!p.isMedia || p.mediaBytes !== null || renamedIds.has(p.doc.id))
1038
- continue;
1039
- const tracked = previousManifest?.docs[p.relPath];
1040
- if (tracked !== undefined && tracked.id === p.doc.id && tracked.body_sha256 != null)
1041
- continue;
1042
- let holdsLocalFile = false;
1564
+ // Write in plan order, stopping at the first error or refusal; then record exactly what was written, once (spec §1.3).
1565
+ const { placed, stop } = (0, doc_pull_writes_1.writeAll)(destination, writes, faults);
1566
+ faults.afterWrites(destination);
1567
+ const pendingWarnings = [];
1568
+ const outcomes = decideOutcomes(destination, planned, new Set(placed.map((write) => write.relPath)), stop !== null, previousManifest, folderPath, renameMoves, listedIds, pendingWarnings);
1569
+ for (const row of fetchFailed) {
1570
+ outcomes.push({ id: row.id, kind: 'refused', placed: new Map(), kept: new Map([...heldEntries].filter(([, entry]) => entry.id === row.id)) });
1571
+ }
1572
+ const manifest = buildManifest(folderPath, previousManifest, outcomes, usedSingleDocFallback || stop !== null, pendingWarnings);
1573
+ const updated = `${placed.length} of ${writes.length} files were updated`;
1574
+ let manifestRecorded = false;
1575
+ const problem = manifestProblem(destination, manifest, outcomes, new Map(placed.map((write) => [write.relPath, { hash: (0, docs_manifest_1.sha256Hex)(write.data), identity: write.identity }])));
1576
+ if (problem !== null) {
1577
+ process.stderr.write(chalk_1.default.red(`error: doc pull stopped before recording a manifest that would not match the files (${shown(problem.rel)}: ${shown(problem.reason)}) — ${updated}; the manifest was not changed.\n`));
1578
+ }
1579
+ else {
1043
1580
  try {
1044
- holdsLocalFile = fs_1.default.statSync(path_1.default.join(destination, ...p.relPath.split('/'))).isFile();
1581
+ faults.beforeManifestTemp();
1582
+ (0, docs_manifest_1.writeManifest)(destination, manifest, faults.beforeManifestRename);
1583
+ manifestRecorded = true;
1045
1584
  }
1046
- catch {
1047
- holdsLocalFile = false;
1585
+ catch (error) {
1586
+ process.stderr.write(chalk_1.default.red(`error: cannot write ${docs_manifest_1.DOCS_MANIFEST}: ${shown(error.message)} — ${updated}; the manifest was not changed.\n`));
1048
1587
  }
1049
- if (!holdsLocalFile)
1050
- continue;
1051
- delete manifestDocs[p.relPath];
1052
- process.stderr.write(chalk_1.default.yellow(`! doc ${p.doc.id} ("${p.doc.title}") failed to download and ${p.relPath} holds a local file; not tracking it — pull again later\n`));
1053
1588
  }
1589
+ // The tracking decisions describe the manifest just recorded, so they come before the error of a pull that stopped
1590
+ // (spec §1.5); a manifest that was not recorded changed no tracking, so says nothing.
1591
+ if (manifestRecorded) {
1592
+ for (const line of pendingWarnings)
1593
+ process.stderr.write(chalk_1.default.yellow(`${line}\n`));
1594
+ }
1595
+ if (stop !== null || !manifestRecorded)
1596
+ reportFetchFailed(fetchFailed);
1597
+ if (stop !== null)
1598
+ reportStop(stop, planned, placed, writes, manifestRecorded);
1599
+ if (!manifestRecorded)
1600
+ process.exit(1);
1601
+ const files = placed
1602
+ .map((write) => ({ path: write.relPath, action: 'written' }));
1054
1603
  // Identity of every file this pull actually wrote, keyed by dev:ino. Used by the
1055
1604
  // deletion-propagation loop below to recognize an "orphan" that is really just the
1056
1605
  // same file this pull wrote under a different manifest key (e.g. a case-only title
@@ -1071,32 +1620,13 @@ async function report(destination, folderPath, fetched, options, config, extraWa
1071
1620
  continue;
1072
1621
  }
1073
1622
  }
1074
- // Rename cleanup (PM ruling 2, cli#157): each unmodified old twin is gone
1075
- // now that the new file is written — but never one this pull just wrote
1076
- // for another doc (e.g. a new markdown doc that now takes `page.md`).
1077
- // Edited sources were all refused before any write, even with --overwrite.
1078
- // A twin whose replacement was NOT written (a failed media download plans
1079
- // a new path but writes nothing) keeps its old file and its old manifest
1080
- // entry — deleting it would destroy the only good copy. Without an old
1081
- // file the old entry is still kept, so the doc is not tracked (with no
1082
- // hash) at a new path that may hold an untracked file. The refusals above
1083
- // guarantee no other doc in this pull claims that old path.
1623
+ // Rename cleanup (PM ruling 2, cli#157), after publication only: each unmodified old twin is
1624
+ // gone now that the new file is written — but never one this pull just wrote for another
1625
+ // doc (e.g. a new markdown doc that now takes `page.md`). Edited sources were all refused
1626
+ // before any write, even with --overwrite. A twin whose replacement was not written was
1627
+ // kept above.
1084
1628
  for (const m of renameMoves) {
1085
- if (!m.replacementWritten) {
1086
- delete manifestDocs[m.newRel];
1087
- const oldEntry = previousManifest?.docs[m.oldRel];
1088
- if (oldEntry !== undefined) {
1089
- manifestDocs[m.oldRel] = oldEntry;
1090
- }
1091
- if (m.sourcePresent) {
1092
- process.stderr.write(chalk_1.default.yellow(`! kept ${m.oldRel} — doc ${m.id} download failed; still tracked as ${m.oldRel}\n`));
1093
- }
1094
- else {
1095
- process.stderr.write(chalk_1.default.yellow(`! doc ${m.id} download failed; still tracked as ${m.oldRel}, which is not present locally\n`));
1096
- }
1097
- continue;
1098
- }
1099
- if (!m.sourcePresent)
1629
+ if (!m.replacementWritten || !m.sourcePresent)
1100
1630
  continue;
1101
1631
  const absOld = path_1.default.resolve(destination, ...m.oldRel.split('/'));
1102
1632
  // cli#167 M2: the old path is the same file as one this pull just
@@ -1115,7 +1645,7 @@ async function report(destination, folderPath, fetched, options, config, extraWa
1115
1645
  }
1116
1646
  const writtenPath = oldIdentity === null ? undefined : writtenPathByIdentity.get(oldIdentity);
1117
1647
  if (writtenPath !== undefined) {
1118
- process.stderr.write(chalk_1.default.yellow(`! kept ${m.oldRel}: it is the same file as ${writtenPath} (a link); the extra name is not tracked — remove it yourself if you don't need it\n`));
1648
+ process.stderr.write(chalk_1.default.yellow(`! kept ${shown(m.oldRel)}: it is the same file as ${shown(writtenPath)} (a link); the extra name is not tracked — remove it yourself if you don't need it\n`));
1119
1649
  }
1120
1650
  }
1121
1651
  if (!isSafeToRemoveTrackedFile(absOld, destPrefix, realDest, writtenIdentities))
@@ -1127,16 +1657,6 @@ async function report(destination, folderPath, fetched, options, config, extraWa
1127
1657
  continue;
1128
1658
  }
1129
1659
  }
1130
- let docs = manifestDocs;
1131
- if (usedSingleDocFallback && previousManifest !== null && previousManifest.folder_path === folderPath) {
1132
- // A single-doc pull speaks for one doc only: keep every other tracked entry (cli#153),
1133
- // dropping any stale key that pointed at this same doc id.
1134
- const pulledIds = new Set(Object.values(manifestDocs).map((entry) => entry.id));
1135
- docs = Object.fromEntries(Object.entries(previousManifest.docs).filter(([, entry]) => !pulledIds.has(entry.id)));
1136
- Object.assign(docs, manifestDocs);
1137
- }
1138
- const manifest = { folder_path: folderPath, docs };
1139
- (0, docs_manifest_1.writeManifest)(destination, manifest);
1140
1660
  for (const warning of [...extraWarnings, ...warnings]) {
1141
1661
  process.stderr.write(chalk_1.default.yellow(`${warning}\n`));
1142
1662
  }
@@ -1154,18 +1674,21 @@ async function report(destination, folderPath, fetched, options, config, extraWa
1154
1674
  process.stderr.write(chalk_1.default.yellow("deletions not propagated: single-doc pull cannot speak for a folder's contents\n"));
1155
1675
  }
1156
1676
  else if (previousManifest.folder_path !== folderPath) {
1157
- process.stderr.write(chalk_1.default.yellow(`deletions not propagated: this directory tracks "${previousManifest.folder_path}", not "${folderPath}"\n`));
1677
+ process.stderr.write(chalk_1.default.yellow(`deletions not propagated: this directory tracks "${shown(previousManifest.folder_path)}", not "${shown(folderPath)}"\n`));
1158
1678
  }
1159
1679
  }
1160
1680
  const keptModifiedMedia = new Set();
1161
1681
  if (canPropagateDeletions) {
1162
1682
  for (const [relPath, entry] of Object.entries(previousManifest.docs)) {
1163
- if (manifestDocs[relPath])
1683
+ if ((0, docs_manifest_1.entryAt)(manifest, relPath) !== undefined)
1164
1684
  continue;
1165
1685
  // Rename cleanup (cli#157) already handled this path: never a
1166
1686
  // "deleted remotely" orphan warning for it.
1167
1687
  if (handledOldPaths.has(relPath))
1168
1688
  continue;
1689
+ // A doc the server listed in this pull was not deleted remotely, whatever its outcome (cli#209).
1690
+ if (listedIds.has(entry.id))
1691
+ continue;
1169
1692
  const absPath = path_1.default.resolve(destination, ...relPath.split('/'));
1170
1693
  // The whole entry is guarded: the new manifest is already on disk by now, so an
1171
1694
  // uncaught throw would abort the report, silently skip every later orphan, and
@@ -1192,18 +1715,19 @@ async function report(destination, folderPath, fetched, options, config, extraWa
1192
1715
  }
1193
1716
  }
1194
1717
  if (options.json) {
1195
- console.log(JSON.stringify({ manifest, files, removed, kept_modified: keptModified }));
1196
- process.exit(0);
1718
+ console.log((0, source_provenance_1.escapeJsonDisplayText)(JSON.stringify({ manifest, files, removed, kept_modified: keptModified })));
1719
+ reportFetchFailed(fetchFailed);
1720
+ process.exit(fetchFailed.length > 0 ? 1 : 0);
1197
1721
  }
1198
- console.log(chalk_1.default.green(`pulled ${files.length} doc${files.length === 1 ? '' : 's'} → ${destination}`));
1722
+ console.log(chalk_1.default.green(`pulled ${files.length} doc${files.length === 1 ? '' : 's'} → ${shown(destination)}`));
1199
1723
  for (const file of files) {
1200
- console.log(chalk_1.default.gray(` ${file.path}`));
1724
+ console.log(chalk_1.default.gray(` ${shown(file.path)}`));
1201
1725
  }
1202
1726
  for (const file of removed) {
1203
- console.log(chalk_1.default.gray(`- removed (deleted remotely): ${file}`));
1727
+ console.log(chalk_1.default.gray(`- removed (deleted remotely): ${shown(file)}`));
1204
1728
  }
1205
1729
  for (const file of keptModified) {
1206
- process.stderr.write(chalk_1.default.yellow(`! kept ${file} — deleted remotely but modified locally\n`));
1730
+ process.stderr.write(chalk_1.default.yellow(`! kept ${shown(file)} — deleted remotely but modified locally\n`));
1207
1731
  if (keptModifiedMedia.has(file)) {
1208
1732
  process.stderr.write(chalk_1.default.yellow(' (it is now untracked; use `solidactions doc upload` to re-create it)\n'));
1209
1733
  }
@@ -1211,12 +1735,24 @@ async function report(destination, folderPath, fetched, options, config, extraWa
1211
1735
  process.stderr.write(chalk_1.default.yellow(' (it is now untracked; `doc push` will re-create it)\n'));
1212
1736
  }
1213
1737
  }
1214
- process.exit(0);
1738
+ reportFetchFailed(fetchFailed);
1739
+ process.exit(fetchFailed.length > 0 ? 1 : 0);
1215
1740
  }
1216
1741
  /**
1217
1742
  * Entry point called from index.ts.
1743
+ *
1744
+ * Command-level error boundary (cli#189): any error escaping the command's
1745
+ * work — a server-bearing exception like `McpRpcError` as well as a
1746
+ * filesystem throw — prints one sanitised red `error: ` line and exits 1.
1747
+ * The command's own `process.exit` calls terminate the process and never
1748
+ * reach this catch.
1218
1749
  */
1219
1750
  async function docPull(folder, dest, options) {
1220
- const config = await (0, api_1.requireConfigWithWorkspace)();
1221
- await docPullWithConfig(folder, dest, options, config);
1751
+ try {
1752
+ const config = await (0, api_1.requireConfigWithWorkspace)();
1753
+ await docPullWithConfig(folder, dest, options, config);
1754
+ }
1755
+ catch (error) {
1756
+ reportWriteError(error);
1757
+ }
1222
1758
  }