@solidactions/cli 3.21.0 → 3.22.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.
Files changed (44) hide show
  1. package/README.md +3 -3
  2. package/dist/command-manifest.json +1 -1
  3. package/dist/commands/connection-list.js +1 -1
  4. package/dist/commands/crew-env-delete.js +2 -2
  5. package/dist/commands/crew-env-list.js +2 -2
  6. package/dist/commands/crew-env-push.js +5 -2
  7. package/dist/commands/crew-env-set.js +2 -2
  8. package/dist/commands/deploy.js +41 -26
  9. package/dist/commands/doc-pull.js +432 -88
  10. package/dist/commands/doc-push.js +54 -3
  11. package/dist/commands/doc-upload.js +5 -2
  12. package/dist/commands/env-delete.js +12 -5
  13. package/dist/commands/env-list.js +12 -7
  14. package/dist/commands/env-map.js +7 -5
  15. package/dist/commands/env-pull.js +5 -6
  16. package/dist/commands/env-push.js +10 -6
  17. package/dist/commands/env-reset.js +12 -8
  18. package/dist/commands/env-set.js +15 -11
  19. package/dist/commands/login.js +8 -7
  20. package/dist/commands/oauth-action-list.js +2 -2
  21. package/dist/commands/oauth-action-platforms.js +2 -2
  22. package/dist/commands/oauth-action-search.js +2 -2
  23. package/dist/commands/oauth-action-view.js +2 -2
  24. package/dist/commands/project-create.js +1 -1
  25. package/dist/commands/project-list.js +2 -2
  26. package/dist/commands/project-logs.js +7 -3
  27. package/dist/commands/project-view.js +26 -9
  28. package/dist/commands/pull.js +4 -2
  29. package/dist/commands/run-list.js +24 -3
  30. package/dist/commands/run-start.js +12 -9
  31. package/dist/commands/run-view.js +2 -2
  32. package/dist/commands/schedule-delete.js +5 -10
  33. package/dist/commands/schedule-list.js +5 -10
  34. package/dist/commands/schedule-set.js +39 -44
  35. package/dist/commands/schedule-state.js +12 -16
  36. package/dist/commands/state.js +3 -3
  37. package/dist/commands/webhook-list.js +12 -4
  38. package/dist/commands/webhook-secret.js +12 -4
  39. package/dist/commands/workflow-view.js +3 -3
  40. package/dist/commands/workspaces.js +53 -2
  41. package/dist/utils/api.js +35 -2
  42. package/dist/utils/crew.js +6 -1
  43. package/dist/utils/project-ref.js +91 -0
  44. package/package.json +2 -2
@@ -2,10 +2,11 @@
2
2
  /**
3
3
  * solidactions doc pull <folder> [dest]
4
4
  *
5
- * Downloads a Docs folder tree from SA-Docs into a local markdown tree (the
5
+ * Downloads a Docs folder tree from SA-Docs into a local file tree (the
6
6
  * inverse of `doc push`): BFS-walks the folder via `docs_read` `list`,
7
7
  * bulk-fetches doc bodies via `docs_read` `bulk_read`, and writes each doc as
8
- * <dest>/<relative-folder>/<sanitized-title>.md plus a revision manifest
8
+ * <dest>/<relative-folder>/<sanitized-title>.md — visual docs as `.html` and
9
+ * canvases as `.canvas.json` — plus a revision manifest
9
10
  * (<dest>/.solidactions-docs.json) recording id/title/current_revision_id
10
11
  * per file for later diffing.
11
12
  *
@@ -166,7 +167,13 @@ async function listTree(config, folderPath) {
166
167
  queue.push({ folder_path: folder.folder_path, relative: childRelative });
167
168
  }
168
169
  for (const doc of result.data?.docs ?? []) {
169
- rows.push({ id: doc.id, title: doc.title, relative });
170
+ rows.push({
171
+ id: doc.id,
172
+ title: doc.title,
173
+ relative,
174
+ docType: doc.doc_type == null ? null : (doc.doc_type.slug ?? null),
175
+ docTypeKnown: Object.prototype.hasOwnProperty.call(doc, 'doc_type'),
176
+ });
170
177
  }
171
178
  }
172
179
  return { ok: true, rows };
@@ -224,6 +231,39 @@ async function fetchBodies(config, rows) {
224
231
  }
225
232
  return { fetched, warnings };
226
233
  }
234
+ /**
235
+ * Fill in the doc type for fetched docs whose list row did not carry a
236
+ * `doc_type` key (cli#157): one `read_doc {id}` per unknown doc. A doc whose
237
+ * type still cannot be read keeps `null` (written as .md) with a warning.
238
+ */
239
+ async function backfillDocTypes(config, fetched) {
240
+ const warnings = [];
241
+ for (const doc of fetched) {
242
+ if (doc.docTypeKnown)
243
+ continue;
244
+ let slug = null;
245
+ let readOk = false;
246
+ try {
247
+ const result = await (0, mcp_1.callDocsTool)(config, { action: 'read_doc', id: doc.id });
248
+ if (result.ok) {
249
+ readOk = true;
250
+ slug = result.data?.doc_type?.slug ?? null;
251
+ }
252
+ }
253
+ catch {
254
+ readOk = false;
255
+ }
256
+ // A successful read that simply reports no type (doc_type: null) is a
257
+ // valid untyped doc, not a failure — warn only when the type could
258
+ // not be read at all.
259
+ if (!readOk) {
260
+ warnings.push(`warn: could not read the type of doc ${doc.id} (${doc.title}); writing it as .md`);
261
+ }
262
+ doc.docType = slug;
263
+ doc.docTypeKnown = true;
264
+ }
265
+ return warnings;
266
+ }
227
267
  /**
228
268
  * Allocate the first free `<base>[ -N]<ext>` name not present in `used`,
229
269
  * recording the winner in `used`.
@@ -231,7 +271,8 @@ async function fetchBodies(config, rows) {
231
271
  function allocateName(used, base, ext) {
232
272
  let candidate = base;
233
273
  let suffix = 2;
234
- while (used.has(`${candidate}${ext}`)) {
274
+ const usedFolded = new Set([...used].map((name) => name.toLowerCase()));
275
+ while (usedFolded.has(`${candidate}${ext}`.toLowerCase())) {
235
276
  candidate = `${base}-${suffix}`;
236
277
  suffix++;
237
278
  }
@@ -265,9 +306,11 @@ function isCollisionVariant(file, base, ext) {
265
306
  * name still forces a suffix. When the tracked title is unchanged and the
266
307
  * tracked path is a collision variant of that title in the same folder,
267
308
  * the doc keeps that exact path (R2-I2); a renamed/stale path still
268
- * reallocates. Folder pulls pass nothing and behave exactly as before.
309
+ * reallocates. Folder pulls reserve only paths whose title, directory and
310
+ * extension stay unchanged, keeping their exact spelling regardless of list
311
+ * order without reserving the old names of docs that move away.
269
312
  */
270
- async function planDocs(docs, config, reserved) {
313
+ async function planDocs(docs, config, reserved, previousManifest) {
271
314
  const planned = [];
272
315
  const warnings = [];
273
316
  const usedNamesByDir = new Map();
@@ -276,24 +319,18 @@ async function planDocs(docs, config, reserved) {
276
319
  usedNamesByDir.set(dir, new Set(names));
277
320
  }
278
321
  }
279
- for (const doc of docs) {
280
- const dirRel = doc.relative;
281
- let used = usedNamesByDir.get(dirRel);
282
- if (!used) {
283
- used = new Set();
284
- usedNamesByDir.set(dirRel, used);
285
- }
286
- // The pulled doc keeps its own tracked name: free it in its own
287
- // directory so allocation below can hand it back. Names other ids
288
- // own stay reserved.
289
- const ownRelPath = reserved?.pathById.get(doc.id);
290
- if (ownRelPath !== undefined) {
291
- const slash = ownRelPath.lastIndexOf('/');
292
- const ownDir = slash === -1 ? '' : ownRelPath.slice(0, slash);
293
- if (ownDir === dirRel) {
294
- used.delete(slash === -1 ? ownRelPath : ownRelPath.slice(slash + 1));
295
- }
322
+ const pathById = reserved?.pathById ?? new Map();
323
+ const titleById = reserved?.titleById ?? new Map();
324
+ if (!reserved && previousManifest) {
325
+ for (const [rel, entry] of Object.entries(previousManifest.docs)) {
326
+ if (pathById.has(entry.id))
327
+ continue;
328
+ pathById.set(entry.id, rel);
329
+ titleById.set(entry.id, entry.title);
296
330
  }
331
+ }
332
+ const prepared = [];
333
+ for (const doc of docs) {
297
334
  const media = isMediaCandidate(doc) ? await resolveMedia(config, doc) : { isMedia: false };
298
335
  if (media.warning)
299
336
  warnings.push(media.warning);
@@ -311,32 +348,11 @@ async function planDocs(docs, config, reserved) {
311
348
  ext = (media.mime && MIME_EXTENSIONS[media.mime]) ?? '';
312
349
  }
313
350
  }
314
- // Unchanged title keeps its existing collision-assigned path (R2-I2):
315
- // the tracked path must be in this same folder and be the base name
316
- // or a `-N` collision variant of it. A stale/renamed path (e.g. the
317
- // `renamed.md` merge fixture) falls through to reallocation below.
318
- const ownTitle = reserved?.titleById.get(doc.id);
319
- let fileName;
320
- let relPath;
321
- if (ownRelPath !== undefined && ownTitle !== undefined && ownTitle === doc.title) {
322
- const slash = ownRelPath.lastIndexOf('/');
323
- const ownDir = slash === -1 ? '' : ownRelPath.slice(0, slash);
324
- const ownFile = slash === -1 ? ownRelPath : ownRelPath.slice(slash + 1);
325
- if (ownDir === dirRel && isCollisionVariant(ownFile, base, ext)) {
326
- fileName = ownFile;
327
- relPath = ownRelPath;
328
- used.add(ownFile);
329
- }
330
- else {
331
- const allocated = allocateName(used, base, ext);
332
- fileName = allocated;
333
- relPath = dirRel ? `${dirRel}/${fileName}` : fileName;
334
- }
351
+ else if (doc.docType === 'visual') {
352
+ ext = '.html';
335
353
  }
336
- else {
337
- const allocated = allocateName(used, base, ext);
338
- fileName = allocated;
339
- relPath = dirRel ? `${dirRel}/${fileName}` : fileName;
354
+ else if (doc.docType === 'canvas') {
355
+ ext = '.canvas.json';
340
356
  }
341
357
  let bodySha256;
342
358
  let mediaBytes = null;
@@ -355,6 +371,41 @@ async function planDocs(docs, config, reserved) {
355
371
  else {
356
372
  bodySha256 = (0, docs_manifest_1.sha256Hex)(doc.body);
357
373
  }
374
+ prepared.push({ doc, media, base, ext, bodySha256, mediaBytes });
375
+ }
376
+ const stablePath = (doc, base, ext) => {
377
+ const ownRelPath = pathById.get(doc.id);
378
+ if (ownRelPath === undefined || titleById.get(doc.id) !== doc.title)
379
+ return undefined;
380
+ const slash = ownRelPath.lastIndexOf('/');
381
+ const ownDir = slash === -1 ? '' : ownRelPath.slice(0, slash);
382
+ const ownFile = slash === -1 ? ownRelPath : ownRelPath.slice(slash + 1);
383
+ return ownDir === doc.relative && isCollisionVariant(ownFile, base, ext) ? ownRelPath : undefined;
384
+ };
385
+ if (!reserved) {
386
+ for (const { doc, base, ext } of prepared) {
387
+ const rel = stablePath(doc, base, ext);
388
+ if (rel === undefined)
389
+ continue;
390
+ const used = usedNamesByDir.get(doc.relative) ?? new Set();
391
+ used.add(path_1.default.posix.basename(rel));
392
+ usedNamesByDir.set(doc.relative, used);
393
+ }
394
+ }
395
+ for (const { doc, media, base, ext, bodySha256, mediaBytes } of prepared) {
396
+ const dirRel = doc.relative;
397
+ const used = usedNamesByDir.get(dirRel) ?? new Set();
398
+ usedNamesByDir.set(dirRel, used);
399
+ const ownRelPath = pathById.get(doc.id);
400
+ if (reserved && ownRelPath !== undefined && path_1.default.posix.dirname(ownRelPath) === (dirRel || '.')) {
401
+ // Exact ownership matters: freeing Page.md must not free page.md
402
+ // when another tracked doc owns that differently cased name.
403
+ used.delete(path_1.default.posix.basename(ownRelPath));
404
+ }
405
+ const keptPath = stablePath(doc, base, ext);
406
+ const fileName = keptPath === undefined ? allocateName(used, base, ext) : path_1.default.posix.basename(keptPath);
407
+ const relPath = keptPath ?? (dirRel ? `${dirRel}/${fileName}` : fileName);
408
+ used.add(fileName);
358
409
  planned.push({ doc, relPath, dirRel, fileName, isMedia: media.isMedia, mediaBytes, bodySha256 });
359
410
  }
360
411
  return { planned, warnings };
@@ -362,9 +413,10 @@ async function planDocs(docs, config, reserved) {
362
413
  /**
363
414
  * Write every planned doc to disk under `destination` and build the
364
415
  * manifest docs map. The only step in the whole pull that creates
365
- * directories or writes/overwrites files — called only after any
366
- * unpushed-local-changes conflict has already refused, so it never clobbers
367
- * a file the caller decided to keep.
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.
368
420
  */
369
421
  function commitDocs(destination, planned) {
370
422
  const manifestDocs = {};
@@ -372,14 +424,7 @@ function commitDocs(destination, planned) {
372
424
  for (const p of planned) {
373
425
  const dirAbs = p.dirRel ? path_1.default.join(destination, ...p.dirRel.split('/')) : destination;
374
426
  fs_1.default.mkdirSync(dirAbs, { recursive: true });
375
- // A destination path that already exists as a directory would make writeFileSync
376
- // throw EISDIR mid-walk, after earlier docs were written and before the manifest
377
- // is saved — a half-pulled tree with a stale sidecar. Fail cleanly instead.
378
427
  const targetAbs = path_1.default.join(dirAbs, p.fileName);
379
- if (fs_1.default.existsSync(targetAbs) && !fs_1.default.statSync(targetAbs).isFile()) {
380
- 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`));
381
- process.exit(1);
382
- }
383
428
  if (p.isMedia) {
384
429
  if (p.mediaBytes) {
385
430
  fs_1.default.writeFileSync(targetAbs, p.mediaBytes);
@@ -483,6 +528,8 @@ async function docPullWithConfig(folderPath, dest, options, config) {
483
528
  id: data.id,
484
529
  title: data.title,
485
530
  relative: '',
531
+ docType: data.doc_type?.slug ?? null,
532
+ docTypeKnown: true,
486
533
  body: data.body ?? '',
487
534
  current_revision_id: data.current_revision_id ?? null,
488
535
  properties: data.properties ?? {},
@@ -500,7 +547,77 @@ async function docPullWithConfig(folderPath, dest, options, config) {
500
547
  return;
501
548
  }
502
549
  const { fetched, warnings: fetchWarnings } = await fetchBodies(config, rows);
503
- await report(destination, folderPath, fetched, options, config, fetchWarnings, previousManifest, usedSingleDocFallback);
550
+ const typeWarnings = await backfillDocTypes(config, fetched);
551
+ await report(destination, folderPath, fetched, options, config, [...fetchWarnings, ...typeWarnings], previousManifest, usedSingleDocFallback);
552
+ }
553
+ /**
554
+ * Safety guards shared by deletion propagation and rename cleanup (cli#157):
555
+ * lexical containment in the destination, a regular file, physical
556
+ * containment of the real parent directory (no symlink escape), and never a
557
+ * file this pull just wrote. The only code in the CLI that deletes files —
558
+ * never act on a path it did not create.
559
+ */
560
+ function isSafeToRemoveTrackedFile(absPath, destPrefix, realDest, writtenIdentities) {
561
+ // Containment: a hand-edited or corrupt manifest key such as "../../etc/passwd"
562
+ // would otherwise resolve outside the pull destination.
563
+ if (!absPath.startsWith(destPrefix))
564
+ return false;
565
+ // Only ever remove regular files. A directory here means a corrupt manifest;
566
+ // rmSync would throw mid-pull, leaving a half-deleted tree.
567
+ let stat;
568
+ try {
569
+ stat = fs_1.default.statSync(absPath);
570
+ }
571
+ catch {
572
+ return false;
573
+ }
574
+ if (!stat.isFile())
575
+ return false;
576
+ // Physical containment: the lexical check above only guards the string. If
577
+ // an intermediate path segment is a symlink to a directory OUTSIDE the
578
+ // destination, statSync/rmSync all follow it transparently.
579
+ let realParent;
580
+ try {
581
+ realParent = fs_1.default.realpathSync(path_1.default.dirname(absPath));
582
+ }
583
+ catch {
584
+ return false;
585
+ }
586
+ if (realParent !== realDest && !realParent.startsWith(realDest + path_1.default.sep))
587
+ return false;
588
+ // Identity: never delete a file this pull just wrote.
589
+ if (writtenIdentities.has(`${stat.dev}:${stat.ino}`))
590
+ return false;
591
+ return true;
592
+ }
593
+ /** Resolve directory aliases even when a planned file or its parent does not exist yet. */
594
+ function physicalTargetPath(absPath) {
595
+ const missing = [];
596
+ let existing = absPath;
597
+ while (true) {
598
+ try {
599
+ return path_1.default.join(fs_1.default.realpathSync(existing), ...missing.reverse());
600
+ }
601
+ catch (error) {
602
+ if (error.code !== 'ENOENT')
603
+ throw error;
604
+ try {
605
+ if (fs_1.default.lstatSync(existing).isSymbolicLink()) {
606
+ existing = path_1.default.resolve(path_1.default.dirname(existing), fs_1.default.readlinkSync(existing));
607
+ continue;
608
+ }
609
+ }
610
+ catch (linkError) {
611
+ if (linkError.code !== 'ENOENT')
612
+ throw linkError;
613
+ }
614
+ const parent = path_1.default.dirname(existing);
615
+ if (parent === existing)
616
+ throw error;
617
+ missing.push(path_1.default.basename(existing));
618
+ existing = parent;
619
+ }
620
+ }
504
621
  }
505
622
  /** Write the docs + manifest to disk and print the result (chalk lines or --json). */
506
623
  async function report(destination, folderPath, fetched, options, config, extraWarnings, previousManifest, usedSingleDocFallback) {
@@ -528,7 +645,208 @@ async function report(destination, folderPath, fetched, options, config, extraWa
528
645
  }
529
646
  reserved = { usedNames, pathById, titleById };
530
647
  }
531
- const { planned, warnings } = await planDocs(fetched, config, reserved);
648
+ const { planned, warnings } = await planDocs(fetched, config, reserved, previousManifest);
649
+ const renameMoves = [];
650
+ if (previousManifest) {
651
+ const pathById = new Map();
652
+ for (const [relPath, entry] of Object.entries(previousManifest.docs)) {
653
+ if (!pathById.has(entry.id))
654
+ pathById.set(entry.id, relPath);
655
+ }
656
+ for (const p of planned) {
657
+ const old = pathById.get(p.doc.id);
658
+ if (old === undefined || old === p.relPath)
659
+ continue;
660
+ const absOld = path_1.default.join(destination, ...old.split('/'));
661
+ let sourceStat = null;
662
+ try {
663
+ const stat = fs_1.default.statSync(absOld);
664
+ if (stat.isFile())
665
+ sourceStat = stat;
666
+ }
667
+ catch {
668
+ sourceStat = null;
669
+ }
670
+ let modified = false;
671
+ let targetIsSource = false;
672
+ if (sourceStat !== null) {
673
+ const entry = previousManifest.docs[old];
674
+ let currentHash = null;
675
+ try {
676
+ currentHash = (0, docs_manifest_1.sha256Hex)(fs_1.default.readFileSync(absOld));
677
+ }
678
+ catch {
679
+ currentHash = null;
680
+ }
681
+ modified = currentHash === null || currentHash !== entry.body_sha256;
682
+ try {
683
+ const targetStat = fs_1.default.statSync(path_1.default.join(destination, ...p.relPath.split('/')));
684
+ targetIsSource = targetStat.dev === sourceStat.dev && targetStat.ino === sourceStat.ino;
685
+ }
686
+ catch {
687
+ targetIsSource = false;
688
+ }
689
+ }
690
+ renameMoves.push({
691
+ oldRel: old,
692
+ newRel: p.relPath,
693
+ id: p.doc.id,
694
+ title: p.doc.title,
695
+ sourcePresent: sourceStat !== null,
696
+ sourceIdentity: sourceStat === null ? null : `${sourceStat.dev}:${sourceStat.ino}`,
697
+ modified,
698
+ // A failed media download plans a new path but writes nothing there.
699
+ replacementWritten: !p.isMedia || p.mediaBytes !== null,
700
+ targetIsSource,
701
+ });
702
+ }
703
+ const plannedPaths = new Map(planned.map((p) => [p.relPath, p]));
704
+ const plannedByIdentity = new Map();
705
+ const plannedByPhysicalPath = new Map();
706
+ for (const p of planned) {
707
+ const physicalPath = physicalTargetPath(path_1.default.resolve(destination, ...p.relPath.split('/')));
708
+ const physicalTargets = plannedByPhysicalPath.get(physicalPath) ?? [];
709
+ physicalTargets.push(p);
710
+ plannedByPhysicalPath.set(physicalPath, physicalTargets);
711
+ try {
712
+ const stat = fs_1.default.statSync(path_1.default.join(destination, ...p.relPath.split('/')));
713
+ if (!stat.isFile())
714
+ continue;
715
+ const identity = `${stat.dev}:${stat.ino}`;
716
+ const targets = plannedByIdentity.get(identity) ?? [];
717
+ targets.push(p);
718
+ plannedByIdentity.set(identity, targets);
719
+ }
720
+ catch {
721
+ // An absent target cannot alias a present source.
722
+ continue;
723
+ }
724
+ }
725
+ // Path claims matter even without a source (a failed download restores
726
+ // its old tracking). Present sources also need protection from writes
727
+ // through another name, hard link, symlink or directory component alias.
728
+ const plannedTargetForSource = (m) => plannedPaths.get(m.oldRel)
729
+ ?? plannedByPhysicalPath.get(physicalTargetPath(path_1.default.resolve(destination, ...m.oldRel.split('/'))))?.find((p) => p.doc.id !== m.id)
730
+ ?? (m.sourceIdentity === null
731
+ ? undefined
732
+ : plannedByIdentity.get(m.sourceIdentity)?.find((p) => p.doc.id !== m.id));
733
+ // Edited sources cannot be discarded by --overwrite during a rename.
734
+ // Report a cross-doc collision first, including an alias's actual path.
735
+ for (const m of renameMoves) {
736
+ if (!m.modified)
737
+ continue;
738
+ const taker = plannedTargetForSource(m);
739
+ if (!taker)
740
+ continue;
741
+ const oldTitle = previousManifest.docs[m.oldRel]?.title ?? `#${m.id}`;
742
+ 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`));
743
+ process.stderr.write(chalk_1.default.red(`Move or rename the edited ${m.oldRel} (or push it first) and pull again.\n`));
744
+ process.exit(1);
745
+ }
746
+ // A rename whose replacement will not be written keeps its old file and
747
+ // tracking (b) — which is only possible while no other doc in this pull
748
+ // claims the old path. Otherwise refuse (cli#157 issuecomment-5962867475):
749
+ // no relocation or re-allocation of names.
750
+ for (const m of renameMoves) {
751
+ if (m.replacementWritten)
752
+ continue;
753
+ const taker = plannedTargetForSource(m);
754
+ if (!taker)
755
+ continue;
756
+ 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`));
757
+ process.stderr.write(chalk_1.default.red('Nothing was written. Pull again once the download succeeds.\n'));
758
+ process.exit(1);
759
+ }
760
+ // An edited source whose replacement will not be written cannot move
761
+ // and must not lose its tracking: refuse, with or without --overwrite.
762
+ for (const m of renameMoves) {
763
+ if (m.replacementWritten || !m.modified)
764
+ continue;
765
+ 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`));
766
+ 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`));
767
+ process.exit(1);
768
+ }
769
+ const blocked = renameMoves.filter((m) => m.modified);
770
+ if (blocked.length > 0) {
771
+ for (const m of blocked) {
772
+ 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`));
773
+ process.stderr.write(chalk_1.default.red(`Nothing was written. Push ${m.oldRel} first (or move it aside) and pull again.\n`));
774
+ }
775
+ process.exit(1);
776
+ }
777
+ // Two writes through different names of one file cannot both retain
778
+ // their own doc's bytes and hash. Refuse compositions involving a
779
+ // rename or legacy case-folded names that already alias one file.
780
+ // Other non-rename-only target handling is outside this rule.
781
+ // Physical paths cover absent targets under aliased directories, where
782
+ // there is no inode yet to compare.
783
+ const renamedIds = new Set(renameMoves.map((m) => m.id));
784
+ for (const targets of [...plannedByIdentity.values(), ...plannedByPhysicalPath.values()]) {
785
+ const writes = targets.filter((p) => !p.isMedia || p.mediaBytes !== null);
786
+ if (writes.length < 2)
787
+ continue;
788
+ const foldedPaths = new Set(writes.map((p) => p.relPath.toLowerCase()));
789
+ if (!writes.some((p) => renamedIds.has(p.doc.id)) && foldedPaths.size === writes.length)
790
+ continue;
791
+ const [first, second] = writes;
792
+ 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`));
793
+ process.stderr.write(chalk_1.default.red('Nothing was written. Move the aliased files apart and pull again.\n'));
794
+ process.exit(1);
795
+ }
796
+ // A rename target that is a symbolic link would be written through, to
797
+ // a file this pull does not own (possibly outside the destination):
798
+ // refuse, with or without --overwrite.
799
+ for (const m of renameMoves) {
800
+ if (!m.replacementWritten)
801
+ continue;
802
+ let isLink = false;
803
+ try {
804
+ isLink = fs_1.default.lstatSync(path_1.default.join(destination, ...m.newRel.split('/'))).isSymbolicLink();
805
+ }
806
+ catch {
807
+ isLink = false;
808
+ }
809
+ if (!isLink)
810
+ continue;
811
+ 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`));
812
+ process.stderr.write(chalk_1.default.red(`Replace ${m.newRel} with a regular file (or remove it) and pull again.\n`));
813
+ process.exit(1);
814
+ }
815
+ // A rename target holding an untracked local file (not in the previous
816
+ // manifest) would be overwritten: refuse unless --overwrite, whatever
817
+ // the source's state. A file already holding exactly the bytes this
818
+ // pull writes loses nothing and is adopted. A target tracked by another
819
+ // doc with a recorded hash is protected by the unpushed-local-changes
820
+ // check below; one tracked without a hash cannot be verified there, so
821
+ // it is checked here like an untracked file. A target that is the
822
+ // source itself is governed by the source rules above.
823
+ if (!options.overwrite) {
824
+ for (const m of renameMoves) {
825
+ if (!m.replacementWritten || m.targetIsSource)
826
+ continue;
827
+ const targetEntry = previousManifest.docs[m.newRel];
828
+ if (targetEntry !== undefined && targetEntry.body_sha256 != null)
829
+ continue;
830
+ const absNew = path_1.default.join(destination, ...m.newRel.split('/'));
831
+ let existing;
832
+ try {
833
+ if (!fs_1.default.statSync(absNew).isFile())
834
+ continue;
835
+ existing = fs_1.default.readFileSync(absNew);
836
+ }
837
+ catch {
838
+ continue;
839
+ }
840
+ if ((0, docs_manifest_1.sha256Hex)(existing) === plannedPaths.get(m.newRel)?.bodySha256)
841
+ continue;
842
+ const state = targetEntry === undefined ? 'exists locally but is not tracked' : `holds local bytes with no recorded hash (tracked for doc ${targetEntry.id})`;
843
+ 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`));
844
+ process.stderr.write(chalk_1.default.red(`Move ${m.newRel} aside and pull again, or pass --overwrite to replace it.\n`));
845
+ process.exit(1);
846
+ }
847
+ }
848
+ }
849
+ const handledOldPaths = new Set(renameMoves.map((m) => m.oldRel));
532
850
  // Unpushed-local-changes protection: now that the server walk is known, refuse only
533
851
  // for a file whose doc still exists remotely — i.e. its relative path is part of this
534
852
  // pull's plan and would be overwritten by commitDocs below. A modified file whose
@@ -550,7 +868,19 @@ async function report(destination, folderPath, fetched, options, config, extraWa
550
868
  process.exit(1);
551
869
  }
552
870
  }
871
+ // A destination path that already exists as a directory would make writeFileSync
872
+ // throw EISDIR mid-walk, after earlier docs were written and before the manifest
873
+ // is saved — a half-pulled tree with a stale sidecar. Refuse before any write.
874
+ for (const p of planned) {
875
+ const targetAbs = path_1.default.join(destination, ...p.relPath.split('/'));
876
+ if (fs_1.default.existsSync(targetAbs) && !fs_1.default.statSync(targetAbs).isFile()) {
877
+ 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`));
878
+ process.exit(1);
879
+ }
880
+ }
553
881
  fs_1.default.mkdirSync(destination, { recursive: true });
882
+ const destPrefix = path_1.default.resolve(destination) + path_1.default.sep;
883
+ const realDest = fs_1.default.realpathSync(destination);
554
884
  const { manifestDocs, files } = commitDocs(destination, planned);
555
885
  // Identity of every file this pull actually wrote, keyed by dev:ino. Used by the
556
886
  // deletion-propagation loop below to recognize an "orphan" that is really just the
@@ -566,6 +896,43 @@ async function report(destination, folderPath, fetched, options, config, extraWa
566
896
  continue;
567
897
  }
568
898
  }
899
+ // Rename cleanup (PM ruling 2, cli#157): each unmodified old twin is gone
900
+ // now that the new file is written — but never one this pull just wrote
901
+ // for another doc (e.g. a new markdown doc that now takes `page.md`).
902
+ // Edited sources were all refused before any write, even with --overwrite.
903
+ // A twin whose replacement was NOT written (a failed media download plans
904
+ // a new path but writes nothing) keeps its old file and its old manifest
905
+ // entry — deleting it would destroy the only good copy. Without an old
906
+ // file the old entry is still kept, so the doc is not tracked (with no
907
+ // hash) at a new path that may hold an untracked file. The refusals above
908
+ // guarantee no other doc in this pull claims that old path.
909
+ for (const m of renameMoves) {
910
+ if (!m.replacementWritten) {
911
+ delete manifestDocs[m.newRel];
912
+ const oldEntry = previousManifest?.docs[m.oldRel];
913
+ if (oldEntry !== undefined) {
914
+ manifestDocs[m.oldRel] = oldEntry;
915
+ }
916
+ if (m.sourcePresent) {
917
+ process.stderr.write(chalk_1.default.yellow(`! kept ${m.oldRel} — doc ${m.id} download failed; still tracked as ${m.oldRel}\n`));
918
+ }
919
+ else {
920
+ process.stderr.write(chalk_1.default.yellow(`! doc ${m.id} download failed; still tracked as ${m.oldRel}, which is not present locally\n`));
921
+ }
922
+ continue;
923
+ }
924
+ if (!m.sourcePresent)
925
+ continue;
926
+ const absOld = path_1.default.resolve(destination, ...m.oldRel.split('/'));
927
+ if (!isSafeToRemoveTrackedFile(absOld, destPrefix, realDest, writtenIdentities))
928
+ continue;
929
+ try {
930
+ fs_1.default.rmSync(absOld);
931
+ }
932
+ catch {
933
+ continue;
934
+ }
935
+ }
569
936
  let docs = manifestDocs;
570
937
  if (usedSingleDocFallback && previousManifest !== null && previousManifest.folder_path === folderPath) {
571
938
  // A single-doc pull speaks for one doc only: keep every other tracked entry (cli#153),
@@ -598,43 +965,20 @@ async function report(destination, folderPath, fetched, options, config, extraWa
598
965
  }
599
966
  const keptModifiedMedia = new Set();
600
967
  if (canPropagateDeletions) {
601
- const destPrefix = path_1.default.resolve(destination) + path_1.default.sep;
602
- const realDest = fs_1.default.realpathSync(destination);
603
968
  for (const [relPath, entry] of Object.entries(previousManifest.docs)) {
604
969
  if (manifestDocs[relPath])
605
970
  continue;
606
- const absPath = path_1.default.resolve(destination, ...relPath.split('/'));
607
- // Containment: a hand-edited or corrupt manifest key such as "../../etc/passwd"
608
- // would otherwise resolve outside the pull destination. `doc pull` never writes
609
- // such a key (titles are sanitized), but this loop is the only code in the CLI
610
- // that deletes files — never let it act on a path it did not create.
611
- if (!absPath.startsWith(destPrefix))
971
+ // Rename cleanup (cli#157) already handled this path: never a
972
+ // "deleted remotely" orphan warning for it.
973
+ if (handledOldPaths.has(relPath))
612
974
  continue;
613
- // Only ever remove regular files. A directory here means a corrupt manifest;
614
- // rmSync would throw mid-pull, leaving a half-deleted tree.
615
- //
975
+ const absPath = path_1.default.resolve(destination, ...relPath.split('/'));
616
976
  // The whole entry is guarded: the new manifest is already on disk by now, so an
617
977
  // uncaught throw would abort the report, silently skip every later orphan, and
618
978
  // print a raw stack trace instead of this command's normal error format. One bad
619
979
  // entry must cost only that entry.
620
980
  try {
621
- const stat = fs_1.default.statSync(absPath);
622
- if (!stat.isFile())
623
- continue;
624
- // Physical containment: the lexical check above only guards the string. If
625
- // an intermediate path segment (e.g. "sub" in "sub/x.png") is a symlink to a
626
- // directory OUTSIDE the destination, statSync/readFileSync/rmSync all follow
627
- // it transparently. Resolve the real parent directory and require it to
628
- // physically live under the real destination before ever touching the file.
629
- const realParent = fs_1.default.realpathSync(path_1.default.dirname(absPath));
630
- if (realParent !== realDest && !realParent.startsWith(realDest + path_1.default.sep))
631
- continue;
632
- // Identity: never delete a file this pull just wrote. A case-only title
633
- // rename on a case-insensitive filesystem (or a hand-edited manifest with a
634
- // hardlinked entry) can make an "orphan" key resolve to the very file the
635
- // new manifest just wrote under a different key — bytes trivially match.
636
- const identity = `${stat.dev}:${stat.ino}`;
637
- if (writtenIdentities.has(identity))
981
+ if (!isSafeToRemoveTrackedFile(absPath, destPrefix, realDest, writtenIdentities))
638
982
  continue;
639
983
  const currentHash = (0, docs_manifest_1.sha256Hex)(fs_1.default.readFileSync(absPath));
640
984
  if (entry.body_sha256 != null && entry.body_sha256 === currentHash) {