mossbear 0.1.0-alpha.113 → 0.1.0-alpha.115

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 (128) hide show
  1. package/dist/action-queue.d.ts.map +1 -1
  2. package/dist/action-queue.js +22 -1
  3. package/dist/action-queue.js.map +1 -1
  4. package/dist/agent-comment-client.d.ts +1 -37
  5. package/dist/agent-comment-client.d.ts.map +1 -1
  6. package/dist/agent-comment-client.js +0 -50
  7. package/dist/agent-comment-client.js.map +1 -1
  8. package/dist/artifacts/artifact-comments-client.d.ts +3 -77
  9. package/dist/artifacts/artifact-comments-client.d.ts.map +1 -1
  10. package/dist/artifacts/artifact-comments-client.js +3 -103
  11. package/dist/artifacts/artifact-comments-client.js.map +1 -1
  12. package/dist/artifacts/classify.d.ts +1 -1
  13. package/dist/artifacts/classify.js +1 -1
  14. package/dist/artifacts/delivered-skill-twins.d.ts.map +1 -1
  15. package/dist/artifacts/delivered-skill-twins.js +1 -0
  16. package/dist/artifacts/delivered-skill-twins.js.map +1 -1
  17. package/dist/artifacts/global-delivery.d.ts.map +1 -1
  18. package/dist/artifacts/global-delivery.js +4 -1
  19. package/dist/artifacts/global-delivery.js.map +1 -1
  20. package/dist/artifacts/global-namespace.d.ts.map +1 -1
  21. package/dist/artifacts/global-namespace.js +6 -4
  22. package/dist/artifacts/global-namespace.js.map +1 -1
  23. package/dist/artifacts/publication.d.ts +75 -0
  24. package/dist/artifacts/publication.d.ts.map +1 -0
  25. package/dist/artifacts/publication.js +163 -0
  26. package/dist/artifacts/publication.js.map +1 -0
  27. package/dist/artifacts/sidecar.d.ts +4 -32
  28. package/dist/artifacts/sidecar.d.ts.map +1 -1
  29. package/dist/artifacts/sidecar.js +15 -174
  30. package/dist/artifacts/sidecar.js.map +1 -1
  31. package/dist/artifacts/sync-acquisition.d.ts +51 -0
  32. package/dist/artifacts/sync-acquisition.d.ts.map +1 -0
  33. package/dist/artifacts/sync-acquisition.js +84 -0
  34. package/dist/artifacts/sync-acquisition.js.map +1 -0
  35. package/dist/artifacts/sync-artifacts.d.ts +49 -91
  36. package/dist/artifacts/sync-artifacts.d.ts.map +1 -1
  37. package/dist/artifacts/sync-artifacts.js +10 -773
  38. package/dist/artifacts/sync-artifacts.js.map +1 -1
  39. package/dist/artifacts/sync-execution.d.ts +1 -1
  40. package/dist/artifacts/sync-execution.d.ts.map +1 -1
  41. package/dist/artifacts/sync-execution.js +15 -0
  42. package/dist/artifacts/sync-execution.js.map +1 -1
  43. package/dist/artifacts/sync-report.d.ts +91 -1
  44. package/dist/artifacts/sync-report.d.ts.map +1 -1
  45. package/dist/artifacts/sync-report.js +661 -0
  46. package/dist/artifacts/sync-report.js.map +1 -1
  47. package/dist/commands/comment.d.ts +1 -1
  48. package/dist/commands/comment.d.ts.map +1 -1
  49. package/dist/commands/comment.js +7 -10
  50. package/dist/commands/comment.js.map +1 -1
  51. package/dist/commands/comments.d.ts.map +1 -1
  52. package/dist/commands/comments.js +1 -4
  53. package/dist/commands/comments.js.map +1 -1
  54. package/dist/commands/mcp.d.ts.map +1 -1
  55. package/dist/commands/mcp.js +2 -4
  56. package/dist/commands/mcp.js.map +1 -1
  57. package/dist/commands/publish.d.ts +3 -1
  58. package/dist/commands/publish.d.ts.map +1 -1
  59. package/dist/commands/publish.js +103 -162
  60. package/dist/commands/publish.js.map +1 -1
  61. package/dist/commands/recommend-dismissal.d.ts.map +1 -1
  62. package/dist/commands/recommend-dismissal.js +3 -2
  63. package/dist/commands/recommend-dismissal.js.map +1 -1
  64. package/dist/commands/search.d.ts +1 -1
  65. package/dist/commands/search.d.ts.map +1 -1
  66. package/dist/commands/search.js +3 -5
  67. package/dist/commands/search.js.map +1 -1
  68. package/dist/context/materialize.d.ts +2 -0
  69. package/dist/context/materialize.d.ts.map +1 -1
  70. package/dist/context/materialize.js +23 -4
  71. package/dist/context/materialize.js.map +1 -1
  72. package/dist/guides/init-import.d.ts +2 -12
  73. package/dist/guides/init-import.d.ts.map +1 -1
  74. package/dist/guides/init-import.js +2 -21
  75. package/dist/guides/init-import.js.map +1 -1
  76. package/dist/guides/payload.d.ts +1 -1
  77. package/dist/guides/payload.js +1 -1
  78. package/dist/hook-logger.d.ts +2 -0
  79. package/dist/hook-logger.d.ts.map +1 -1
  80. package/dist/hook-logger.js +32 -4
  81. package/dist/hook-logger.js.map +1 -1
  82. package/dist/http-retry.d.ts.map +1 -1
  83. package/dist/http-retry.js +30 -1
  84. package/dist/http-retry.js.map +1 -1
  85. package/dist/lifecycle/publish-from-branch.d.ts.map +1 -1
  86. package/dist/lifecycle/publish-from-branch.js +121 -178
  87. package/dist/lifecycle/publish-from-branch.js.map +1 -1
  88. package/dist/mcp/client.d.ts +113 -1
  89. package/dist/mcp/client.d.ts.map +1 -1
  90. package/dist/mcp/client.js +220 -1
  91. package/dist/mcp/client.js.map +1 -1
  92. package/dist/mcp/operations.d.ts +2 -25
  93. package/dist/mcp/operations.d.ts.map +1 -1
  94. package/dist/mcp/operations.js +24 -62
  95. package/dist/mcp/operations.js.map +1 -1
  96. package/dist/mcp/server.d.ts.map +1 -1
  97. package/dist/mcp/server.js +12 -11
  98. package/dist/mcp/server.js.map +1 -1
  99. package/dist/mossbear-paths.d.ts +0 -15
  100. package/dist/mossbear-paths.d.ts.map +1 -1
  101. package/dist/mossbear-paths.js +0 -15
  102. package/dist/mossbear-paths.js.map +1 -1
  103. package/dist/skill-identity.d.ts +8 -0
  104. package/dist/skill-identity.d.ts.map +1 -1
  105. package/dist/skill-identity.js +60 -0
  106. package/dist/skill-identity.js.map +1 -1
  107. package/dist/state/machine-cache.d.ts +2 -2
  108. package/dist/state/machine-cache.d.ts.map +1 -1
  109. package/dist/state/machine-cache.js +3 -4
  110. package/dist/state/machine-cache.js.map +1 -1
  111. package/dist/usage/snapshot-state.d.ts +2 -2
  112. package/package.json +4 -4
  113. package/dist/finding-dismissals-client.d.ts +0 -28
  114. package/dist/finding-dismissals-client.d.ts.map +0 -1
  115. package/dist/finding-dismissals-client.js +0 -25
  116. package/dist/finding-dismissals-client.js.map +0 -1
  117. package/dist/guides/guide-baseline.d.ts +0 -58
  118. package/dist/guides/guide-baseline.d.ts.map +0 -1
  119. package/dist/guides/guide-baseline.js +0 -133
  120. package/dist/guides/guide-baseline.js.map +0 -1
  121. package/dist/search-client.d.ts +0 -59
  122. package/dist/search-client.d.ts.map +0 -1
  123. package/dist/search-client.js +0 -130
  124. package/dist/search-client.js.map +0 -1
  125. package/dist/session-digest-client.d.ts +0 -36
  126. package/dist/session-digest-client.d.ts.map +0 -1
  127. package/dist/session-digest-client.js +0 -60
  128. package/dist/session-digest-client.js.map +0 -1
@@ -1,4 +1,3 @@
1
- import { withCount } from '../plural.js';
2
1
  /**
3
2
  * The docs phase of `mossbear refresh`: keep a repo's subscribed bundles in step with
4
3
  * the canonical docs on the server, in both directions.
@@ -14,7 +13,7 @@ import { withCount } from '../plural.js';
14
13
  *
15
14
  * That classification comes from two sources, in this order:
16
15
  *
17
- * 1. **The baseline in `.mossbear/docs.json`** (`sidecar.ts`) — the hash of the
16
+ * 1. **The baseline in the machine cache** (`sidecar.ts`) — the hash of the
18
17
  * bytes we last wrote. Free, exact, works offline, and settles every file
19
18
  * that is still the copy we put there.
20
19
  * 2. **The doc's version history** (`classify.ts`) — the server saves a
@@ -47,40 +46,34 @@ import { withCount } from '../plural.js';
47
46
  * Kept free of citty/console so it unit-tests against a mocked client.
48
47
  */
49
48
  import { readdir, readFile, realpath, stat, unlink as deleteFile } from 'node:fs/promises';
50
- import { homedir } from 'node:os';
51
49
  import { basename, join, relative, resolve } from 'node:path';
52
- import { MAX_CONTEXT_CONTENT_BYTES, MAX_RAW_GUIDE_CONTENT_BYTES, } from '@mossbear/protocol';
50
+ import { MAX_RAW_GUIDE_CONTENT_BYTES } from '@mossbear/protocol';
53
51
  import { materializedBody, removeContextFile } from '../context/materialize.js';
54
52
  import { defaultPullDir } from '../context/pull.js';
55
- import { ContextHttpError } from '../dashboard-error.js';
56
53
  import { errText } from '../err-text.js';
57
54
  import { isPathWithin } from '../guides/path-contains.js';
58
55
  import { safeArtifactFileName } from '../mcp/write-items.js';
59
56
  import { MOSSBEAR_GLOBAL_DIR, MOSSBEAR_MACHINE_CACHE } from '../mossbear-paths.js';
60
57
  import { openMachineCache, readMachineCache } from '../state/machine-cache.js';
61
- import { displayWidth, severityPrefix, terminalWidth, wrapHanging, wrapText, } from '../terminal.js';
62
58
  import { deliveredCommentsForArtifact, } from './artifact-comments.js';
63
- import { MAX_BUNDLE_PULL } from './bundle-pull-limit.js';
64
59
  import { classifyLocalFile } from './classify.js';
65
60
  import { releasesClaudeMdMapping } from './claude-md-import.js';
66
61
  import { createCommittedProbe, readTrackedPaths, } from './committed.js';
67
- import { formatSkillTwinLines, parseSkillFilePath, } from './delivered-skill-twins.js';
68
- import { displayFileName } from './display-path.js';
69
- import { deliveryRootDir, } from './global-namespace.js';
62
+ import { parseSkillFilePath, } from './delivered-skill-twins.js';
70
63
  import { openGlobalSync } from './global-sync.js';
71
- import { MOSSBEAR_CONTEXT_DIR, classifyArtifactPlacement } from './guide-projection.js';
72
- import { readBundlePages } from './published-artifacts.js';
64
+ import { MOSSBEAR_CONTEXT_DIR } from './guide-projection.js';
73
65
  import { planRekey, readMappedFileForProof, rekeyProof, } from './rekey.js';
74
66
  import { readGitChangeReport, resolveRelinkTarget } from './relink.js';
75
67
  import { readRepoProjectId } from './repo-config.js';
76
68
  import { retirementAuthority, } from './retirement-authority.js';
77
69
  import { StateFileUnreadableError, fromSidecarPath, hashContent, indexByArtifactId, readSidecar, readTombstones, toSidecarPath, } from './sidecar.js';
70
+ import { acquireSubscribedArtifacts } from './sync-acquisition.js';
78
71
  import { openArtifactExecution, openPassMappings } from './sync-execution.js';
79
72
  import { artifactsWriteScope, deliveredRoot, planRelink, placementWritesFor, planRetirement, declaredLandingKey, mayMoveLiteralCopy, mayMoveMirroredDocument, } from './sync-plan.js';
80
73
  import { assembleArtifactsSyncResult, stateUnreadableResult, } from './sync-report.js';
81
74
  import { createTrackedPaths } from './tracked-paths.js';
82
75
  export { MAX_BUNDLE_PULL } from './bundle-pull-limit.js';
83
- export { findUnmanagedPaths } from './sync-report.js';
76
+ export { artifactsSyncResultIsRoutine, findUnmanagedPaths, formatArtifactsRetirementLines, formatArtifactsSyncLine, formatStandingCountLine, globalDeliveryLines, shellQuotePosix, } from './sync-report.js';
84
77
  /**
85
78
  * The run-level half of a sync's outcome — everything
86
79
  * `formatArtifactsRetirementLines` renders, and nothing else. Mostly retirement,
@@ -620,113 +613,7 @@ export async function syncSubscribedArtifacts(client, bundles, root, options) {
620
613
  kind: 'placement',
621
614
  claimed: claimedStoredPaths,
622
615
  };
623
- /**
624
- * Pull every subscribed bundle **before** reconciling any of them.
625
- *
626
- * The pull used to open each bundle's own iteration, which is fine while a
627
- * landing path is derived from the bundle being processed. It is not fine once
628
- * the path comes from the item: two subscribed bundles may legally hold
629
- * different items declaring the same path (uniqueness is scoped to bundle
630
- * membership, not to the user — `schema-mossbear.ts` → `guide_files.path`), and
631
- * that has to be settled by looking at the whole subscription rather than by
632
- * whichever bundle `bundles` happens to list first.
633
- */
634
- const pulled = [];
635
- for (const subscribed of bundles) {
636
- let items = [];
637
- // False until a read completes, which is right: a pull that fails, on its
638
- // first page or a later one, keeps nothing it read, and the failure gates
639
- // retirement on its own.
640
- let truncated = false;
641
- let untrustedNote = null;
642
- let error;
643
- try {
644
- // **Paged to the end**, so a bundle whose tombstones push it past one
645
- // read is still delivered whole and still retires what left it. Against
646
- // a server that cannot page this is the one read it always was.
647
- //
648
- // Two limits a multi-request read has that one read did not. Each page
649
- // counts its comments as delivered when it is served, so a read that
650
- // fails on a later page has counted comments nobody is shown. And the
651
- // pages are not one snapshot: a row created mid-read behind the cursor is
652
- // missed while the read still counts as complete. That can retire an
653
- // unedited file whose item was just re-keyed — only ever a file this sync
654
- // wrote and nobody has changed since, delivered again on the next pass.
655
- const read = await readBundlePages(client, {
656
- bundleId: subscribed.id,
657
- ...(comments === 'none' ? { comments: 'none' } : {}),
658
- });
659
- // **Newest first, whichever way it was read.** Pages arrive in id order,
660
- // and this phase was written against the unpaged read's order: two new
661
- // pathless items with one name settle which takes `<name>.md` by which is
662
- // planned first, and the per-doc outcomes are reported in this order.
663
- // Sorting keeps both as they were for distinct timestamps; ties, which
664
- // the unpaged read left in the server's own order, stay in id order. An
665
- // old server's page is already newest first and keeps its order exactly.
666
- const response = read.pages
667
- .flatMap((page) => page.artifacts)
668
- .sort((a, b) => b.updatedAt.localeCompare(a.updatedAt));
669
- // **A tombstoned artifact leaves this phase's delivered set**
670
- // (`artifact-ownership-and-delivery-plan.md` → D28). The repository that
671
- // publishes it deleted the file, so what the item still carries is the
672
- // last revision rather than a current one — and a file left at a
673
- // discovery root keeps feeding deleted guidance into every agent that
674
- // reads this repo, which is the failure the decision exists to stop.
675
- //
676
- // **Dropped at the pull rather than handled as a case**, so this needs no
677
- // removal policy of its own: absence from the delivered set is already
678
- // how this phase learns a file is gone, and every rule that governs
679
- // taking one away applies unchanged — a locally edited copy is kept and
680
- // named, never unlinked; `--no-prune` still keeps it; a failed or
681
- // truncated pull retires nothing; and each removal is reported. It is
682
- // the same shape as a guide switched off, which also reaches disk by
683
- // leaving this response.
684
- //
685
- // **It is not the only place that has to know.** This phase filters here
686
- // because it must also *retire* the mapping, which is a decision only it
687
- // makes. The other write-to-disk doors — `mossbear pull` and the MCP
688
- // `pull` tool — have no retirement behind them, and they are
689
- // covered at the one funnel they share (`../mcp/write-items.ts`). An
690
- // earlier form of this comment claimed nothing downstream had to know,
691
- // which was true of neither.
692
- //
693
- // Settled before the filter — see `truncated`.
694
- truncated = read.atCeiling;
695
- items = response.filter((item) => item.removed !== true);
696
- untrustedNote = read.pages.find((page) => page.untrusted)?.untrusted?.note ?? null;
697
- }
698
- catch (err) {
699
- // A 404 here means the bundle itself is gone — deleted upstream while this
700
- // repo still subscribes to it. Named by slug because that is what the user
701
- // will find in their committed config; the id is what we asked with. Local
702
- // files are deliberately untouched: a failed pull skips reconciliation and
703
- // gates retirement off.
704
- error =
705
- err instanceof ContextHttpError && err.status === 404
706
- ? `bundle no longer exists on the server — remove "${subscribed.slug}" from "bundles" in .mossbear/config.json to stop syncing it (local files are left in place)`
707
- : errText(err);
708
- }
709
- pulled.push({
710
- bundleId: subscribed.id,
711
- bundle: subscribed.dirName,
712
- dir: defaultPullDir(subscribed.dirName, root),
713
- // Absent or empty reads as one untargeted delivery rather than none: a
714
- // caller that does not know the scopes (`mossbear pull`, the interactive
715
- // picker) still delivers, and it delivers the way it always has.
716
- targets: subscribed.targets && subscribed.targets.length > 0
717
- ? subscribed.targets
718
- : [{ scope: 'repo', deliver: null }],
719
- home: subscribed.home ?? null,
720
- muted: new Set(subscribed.muted ?? []),
721
- accountMuted: new Set(subscribed.accountMuted ?? []),
722
- readOnly: subscribed.readOnly === true,
723
- published: subscribed.published === true || subscribed.readOnly === true,
724
- items,
725
- truncated,
726
- untrustedNote,
727
- error,
728
- });
729
- }
616
+ const pulled = await acquireSubscribedArtifacts({ client, bundles, root, comments });
730
617
  /**
731
618
  * **Before anything is planned or relinked**, records whose guide now carries
732
619
  * a different id follow it (`./rekey.ts`). A pull from a server that has not
@@ -756,7 +643,7 @@ export async function syncSubscribedArtifacts(client, bundles, root, options) {
756
643
  bundle: entry.bundle,
757
644
  items: entry.items,
758
645
  readable: entry.error === undefined,
759
- complete: entry.error === undefined && !entry.truncated,
646
+ complete: entry.error === undefined && entry.inventory === 'complete',
760
647
  })),
761
648
  tombstones,
762
649
  homeProjectId,
@@ -897,7 +784,8 @@ export async function syncSubscribedArtifacts(client, bundles, root, options) {
897
784
  });
898
785
  const { movedAway, moveUnlinkFailed } = execution;
899
786
  for (const entry of pulled) {
900
- const { bundleId, bundle, dir, items, truncated, targets, home, muted, accountMuted, readOnly, published, } = entry;
787
+ const { bundleId, bundle, dir, items, targets, home, muted, accountMuted, readOnly, published, } = entry;
788
+ const truncated = entry.inventory === 'truncated';
901
789
  let error = entry.error;
902
790
  const bundleExecution = execution.openBundle();
903
791
  /** Items this subscriber switched off, named in the report rather than dropped in silence. */
@@ -1191,657 +1079,6 @@ export async function syncSubscribedArtifacts(client, bundles, root, options) {
1191
1079
  }
1192
1080
  return result;
1193
1081
  }
1194
- /**
1195
- * Report lines for everything that happened **outside** the bundle folders —
1196
- * printed by the sync command after the per-bundle lines, which cannot carry
1197
- * them: those are scoped to one folder and name files by basename.
1198
- *
1199
- * Once a doc lands at its own declared path this is no longer a guide-projection
1200
- * report, so it says "files outside the bundle folders" rather than "projected
1201
- * guide files". It covers removals, failed removals, and — since slice 2 — the
1202
- * two ways a file is *kept*: unsafe to remove, and `--no-prune`. A kept file
1203
- * that nothing names is indistinguishable from one nothing noticed.
1204
- *
1205
- * Empty when nothing out-of-dir happened.
1206
- *
1207
- * Takes only the fields it reads, not a whole `ArtifactsSyncResult`. A formatter that
1208
- * demands the entire return value forces every caller — and every test fixture —
1209
- * to fabricate parts it never looks at, which is how adding `plan` to
1210
- * `ArtifactsSyncResult` broke two test files that only ever wanted these seven lists.
1211
- */
1212
- /** How a delivery root is named to the user: by the path, never by its key. */
1213
- function deliveryRootLabel(root, homeDir = homedir()) {
1214
- return deliveryRootDir(root, homeDir);
1215
- }
1216
- /**
1217
- * What global delivery refused and what it kept, named.
1218
- *
1219
- * **Silence here is the failure mode this exists for.** A skill Mossbear
1220
- * declined to write because the directory was already someone else's, and a
1221
- * delivered file left behind because it no longer matches what we recorded, are
1222
- * both states the user can only act on if they are told — and both are invisible
1223
- * from inside the repo they are syncing.
1224
- *
1225
- * Nothing is printed for a root that was never consented to: that is not an
1226
- * event, and repeating it every sync would be nagging about a decision already
1227
- * made. `mossbear status` is where the consent state lives.
1228
- */
1229
- export function globalDeliveryLines(outcomes) {
1230
- const lines = [];
1231
- for (const outcome of outcomes) {
1232
- if (outcome.skippedForConsent)
1233
- continue;
1234
- const where = deliveryRootLabel(outcome.root);
1235
- // **Counted apart, because they are different sentences.** A guide that was
1236
- // refused did not arrive; a member that was refused arrived beside a guide
1237
- // that did. Counting them together makes the header's number wrong about the
1238
- // very thing it names — a skill delivered with one script missing would be
1239
- // reported as a guide nobody got.
1240
- const refusedSkills = outcome.refused.filter((entry) => entry.kind === 'skill');
1241
- const refusedMembers = outcome.refused.filter((entry) => entry.kind === 'member');
1242
- // Escaped, because a name reaches here from a guide's declared path and one
1243
- // carrying ANSI escapes could forge the lines after it (`display-path.ts`).
1244
- const refusalLine = ({ name, reason }) => ` ${displayFileName(name)} — ${reason}`;
1245
- if (refusedSkills.length > 0) {
1246
- lines.push(` ${withCount(refusedSkills.length, 'guide')} scoped to every repo ${refusedSkills.length === 1 ? 'was' : 'were'} not delivered to ${where}:`);
1247
- lines.push(...refusedSkills.map(refusalLine));
1248
- }
1249
- if (refusedMembers.length > 0) {
1250
- lines.push(` ${withCount(refusedMembers.length, 'file')} belonging to a delivered guide could not be written to ${where}:`);
1251
- lines.push(...refusedMembers.map(refusalLine));
1252
- }
1253
- // Named, because a removal from a home directory is the change a user most
1254
- // needs to hear about: the switch turned off, this machine opted out, or a
1255
- // guide stopped being delivered, and the skill left every session with it.
1256
- if (outcome.removed.length > 0) {
1257
- lines.push(` removed ${withCount(outcome.removed.length, 'file')} Mossbear had delivered to ${where}:`);
1258
- lines.push(...outcome.removed.map((path) => ` ${displayFileName(path)}`));
1259
- }
1260
- if (outcome.kept.length > 0) {
1261
- lines.push(` ${withCount(outcome.kept.length, 'file')} in ${where} ${outcome.kept.length === 1 ? 'was' : 'were'} kept:`);
1262
- for (const { path, reason } of outcome.kept) {
1263
- lines.push(` ${displayFileName(path)} — ${reason}`);
1264
- }
1265
- }
1266
- }
1267
- return lines;
1268
- }
1269
- export function formatArtifactsRetirementLines(result, options = {}) {
1270
- const lines = [];
1271
- for (const reason of result.deliveryRefusals ?? [])
1272
- lines.push(...wrapHanging(reason, ' = ', ' ').split('\n'));
1273
- if (result.stateUnreadable) {
1274
- // First line and, in this state, the only one — every other list is empty.
1275
- // Names the file and the code because the reader is standing at a terminal
1276
- // in the repo and that is what they need to go look at; says what was *not*
1277
- // done, so nothing is inferred from the silence that follows; and ends in
1278
- // the one action that clears it. No cause is named beyond the code: a
1279
- // permissions problem, a directory in the file's place and an I/O error all
1280
- // arrive here identically — naming one would be a cause this branch cannot
1281
- // distinguish.
1282
- lines.push(` couldn't read ${result.stateUnreadable.path} (${result.stateUnreadable.code}) — artifacts were not synced, so nothing was written over it; make the file readable and run \`mossbear refresh\``);
1283
- return lines;
1284
- }
1285
- lines.push(...globalDeliveryLines(result.globalDelivery));
1286
- if (result.globalRetired.length > 0) {
1287
- // Said once, in the pass that removed them. The sentence names what the
1288
- // directory was for and where the answer now lives, and does not say where
1289
- // each guide went: that depends on a consent this branch does not read.
1290
- lines.push(` removed ${withCount(result.globalRetired.length, 'file')} from ${MOSSBEAR_GLOBAL_DIR} — a guide scoped to every repo is no longer kept there, where nothing read it; \`mossbear status\` shows where each one is delivered:`);
1291
- lines.push(...listNames(result.globalRetired));
1292
- }
1293
- if (result.globalKept.length > 0) {
1294
- lines.push(` ${withCount(result.globalKept.length, 'file')} in ${MOSSBEAR_GLOBAL_DIR} ${result.globalKept.length === 1 ? 'was' : 'were'} kept:`);
1295
- for (const { path, reason } of result.globalKept) {
1296
- lines.push(` ${displayFileName(path)} — ${reason}`);
1297
- }
1298
- }
1299
- if (result.skillTwins) {
1300
- lines.push(...formatSkillTwinLines(result.skillTwins.results, result.skillTwins.retired));
1301
- }
1302
- const derived = withMirrorOutcome(result.aliasMirrors, 'derived');
1303
- if (derived.length > 0) {
1304
- // Says what it did and where the bytes came from: this is a write into a
1305
- // tracked file the reader did not ask for in this run, so "which file won"
1306
- // is the first thing they need — and the `git diff` that follows is theirs
1307
- // to read.
1308
- for (const entry of derived) {
1309
- lines.push(` rewrote ${displayFileName(entry.path)} from ${displayFileName(entry.source ?? '')} — they hold the same guide`);
1310
- }
1311
- }
1312
- for (const entry of withMirrorOutcome(result.aliasMirrors, 'held-uncommitted')) {
1313
- lines.push(` kept your ${displayFileName(entry.path)} — it has uncommitted changes, so it was not rewritten from ${displayFileName(entry.source ?? '')}`);
1314
- }
1315
- for (const entry of withMirrorOutcome(result.aliasMirrors, 'no-local-source')) {
1316
- // The divergent pair as it looks from here. Named rather than skipped: the
1317
- // files hold different rules and only the person who wrote them can say
1318
- // which is right.
1319
- lines.push(` left ${entry.path} as they are — these files hold one guide and differ, and neither an uncommitted edit nor git history shows which one to copy from${entry.error === undefined ? '' : ` (${entry.error})`}`);
1320
- }
1321
- for (const entry of withMirrorOutcome(result.aliasMirrors, 'several-edited')) {
1322
- lines.push(` left ${entry.path} as they are — these files hold one guide and more than one of them has been edited`);
1323
- }
1324
- for (const entry of withMirrorOutcome(result.aliasMirrors, 'failed')) {
1325
- lines.push(`${severityPrefix('failed')}could not rewrite ${displayFileName(entry.path)}${entry.error === undefined ? '' : ` — ${entry.error}`}`);
1326
- }
1327
- for (const entry of withMirrorOutcome(result.aliasMirrors, 'unsafe-path')) {
1328
- lines.push(`${severityPrefix('failed')}refused ${displayFileName(entry.path)}${entry.error === undefined ? '' : ` — ${entry.error}`}`);
1329
- }
1330
- if (result.claudeMdSwap?.outcome === 'swapped') {
1331
- // A write into a tracked file the reader did not ask for in this run, so it
1332
- // says what changed and why, in one line; the `git diff` is theirs to read.
1333
- lines.push(' replaced CLAUDE.md, a copy of AGENTS.md, with `@AGENTS.md` — Claude now reads AGENTS.md through it, and it no longer goes stale');
1334
- }
1335
- else if (result.claudeMdSwap?.outcome === 'held-uncommitted') {
1336
- lines.push(
1337
- // Both causes land here — an uncommitted edit, and git having no answer
1338
- // — so the line names what they share: git could not give the bytes back.
1339
- ' left CLAUDE.md as it is — it is a copy of AGENTS.md that Claude reads instead, and git could not give it back if replaced; replace it with the line `@AGENTS.md`');
1340
- }
1341
- else if (result.claudeMdSwap?.outcome === 'failed') {
1342
- lines.push(`${severityPrefix('failed')}could not replace CLAUDE.md with \`@AGENTS.md\`${result.claudeMdSwap.error === undefined ? '' : ` — ${result.claudeMdSwap.error}`}`);
1343
- }
1344
- if (result.gitFallback) {
1345
- // Said, rather than left to be inferred from an absence. The fallback is
1346
- // deliberate and it is today's behaviour — but a reader who believes
1347
- // uncommitted work is being held back, and is wrong about that, is worse off
1348
- // than one who never expected the rule to apply.
1349
- lines.push(' git could not report committed content here; delivery still protects tracked paths before writing');
1350
- }
1351
- if (result.trackedContext.length > 0) {
1352
- // Named as committed rather than as a mistake: a repo that committed these
1353
- // before the ignore rule existed did nothing wrong, and telling someone they
1354
- // misconfigured something they never configured is what
1355
- // `error-messaging.md` rules out. What they need is the sentence
1356
- // that says the files are duplicated and the command that stops it.
1357
- lines.push(` ${withCount(result.trackedContext.length, 'pulled artifact')} committed to this repo — already in your Mossbear account, so this history is a second copy that will go stale:`);
1358
- lines.push(...listNames(result.trackedContext));
1359
- // `--cached`, and the sentence says what that means, because the difference
1360
- // between this and `git rm` is the user's files. Mossbear never runs it: the
1361
- // command is offered, never taken.
1362
- lines.push(` stop committing them, keeping the files: git rm --cached -r ${CONTEXT_DIR_PREFIX}`);
1363
- lines.push(' or declare a path with mossbear publish <path>; copies outside their home bundle or published path may become a new item');
1364
- }
1365
- if (result.retired.length > 0) {
1366
- lines.push(` removed ${withCount(result.retired.length, 'file')} outside the bundle folders, no longer in any subscribed bundle:`);
1367
- lines.push(...listNames(result.retired));
1368
- }
1369
- for (const path of result.retireFailed) {
1370
- lines.push(`${severityPrefix('failed')}could not remove ${displayFileName(path)} — remove it by hand.`);
1371
- }
1372
- if (result.releasedGitOwned.length > 0) {
1373
- // Said once, in the pass that stopped tracking these files, in the shape
1374
- // `strandedForeign` uses. What is true of all of them is that git delivers
1375
- // this path and Mossbear no longer maintains what is at it; what is *not*
1376
- // said is that they are inert, because some of them sit at discovery roots
1377
- // and are still read on every session — and it is not said that they do,
1378
- // because a mapped document at an ordinary tracked path does not. The
1379
- // branch cannot tell those apart, so the line names neither.
1380
- lines.push(` ${withCount(result.releasedGitOwned.length, 'file')} outside the bundle folders ${result.releasedGitOwned.length === 1 ? 'is' : 'are'} no longer in any subscribed bundle — left exactly as found, since git tracks this repo's files, and no longer tracked by Mossbear:`);
1381
- lines.push(...listNames(result.releasedGitOwned));
1382
- // `openPassMappings.applyRetirement` records suppression with each release,
1383
- // and its completion persists it before this result is returned. `rm` is
1384
- // capped the same way
1385
- // `listNames` caps the names above it: a hundred-file `rm` line is not
1386
- // more pasteable than a hundred-file list is more readable.
1387
- const width = terminalWidth();
1388
- const comment = "Mossbear recorded this, so `mossbear link` won't offer them back with these exact bytes — name one directly to adopt it fresh anyway. Mossbear will not remove them for you; when you are ready:";
1389
- for (const wrapped of wrapText(comment, Math.max(width - 6, MIN_WRAP_WIDTH))) {
1390
- lines.push(` ${wrapped}`);
1391
- }
1392
- const cleanupTargets = result.releasedGitOwned
1393
- .slice(0, ORPHAN_NAME_LIMIT)
1394
- .map((path) => shellQuotePosix(displayFileName(path)));
1395
- const cleanupMore = result.releasedGitOwned.length - cleanupTargets.length;
1396
- lines.push(...wrapCommandLine('rm --', cleanupTargets, width));
1397
- if (cleanupMore > 0)
1398
- lines.push(` # +${cleanupMore} more listed above`);
1399
- }
1400
- const rekeyed = result.rekeyed ?? [];
1401
- if (rekeyed.length > 0) {
1402
- lines.push(` ~ ${withCount(rekeyed.length, 'placement record')} now ${rekeyed.length === 1 ? 'names its' : 'name their'} guide by its new id`);
1403
- }
1404
- for (const entry of result.rekeyAmbiguous ?? []) {
1405
- lines.push(` ! ${displayFileName(entry.path)} names an id the server no longer uses`);
1406
- for (const wrapped of wrapText('More than one guide could be it, so the record was not changed.', Math.max(terminalWidth() - 4, MIN_WRAP_WIDTH))) {
1407
- lines.push(` ${wrapped}`);
1408
- }
1409
- }
1410
- for (const entry of result.relinked) {
1411
- lines.push(` followed ${displayFileName(entry.from)} → ${displayFileName(entry.to)} (moved locally; the mapping now points there)`);
1412
- }
1413
- for (const entry of result.relinkUnresolved) {
1414
- const detail = entry.reason === 'ambiguous'
1415
- ? `several files could be it (${(entry.candidates ?? []).map(displayFileName).join(', ')})`
1416
- : entry.reason === 'no-git'
1417
- ? 'this is not a git work tree, so there is nothing to search'
1418
- : entry.reason === 'unstaged-move'
1419
- ? // Named with its candidate, because it is almost always right and a
1420
- // bare "not found" would waste what we do know. Not adopted: git
1421
- // reports an untracked file the same way whether it appeared a
1422
- // second ago or a year ago, so the matching bytes are a
1423
- // coincidence this cannot rule out.
1424
- `${displayFileName((entry.candidates ?? [])[0] ?? '')} has the same content and may be it — git cannot say whether it is new, so confirm it`
1425
- : 'no moved or newly added file matches it';
1426
- lines.push(`${severityPrefix('degraded')}${displayFileName(entry.path)} is missing and was not rewritten — ${detail}.`);
1427
- lines.push(` point the mapping at its new home with: mossbear artifacts relink ${displayFileName(entry.path)} ${entry.reason === 'unstaged-move'
1428
- ? displayFileName((entry.candidates ?? [])[0] ?? '<path>')
1429
- : '<path>'}`);
1430
- }
1431
- if (result.keptOutOfDir.length > 0 && options.standing !== 'count') {
1432
- lines.push(` ${withCount(result.keptOutOfDir.length, 'file')} outside the bundle folders ${result.keptOutOfDir.length === 1 ? 'is' : 'are'} no longer in any subscribed bundle, kept, not safe to remove (edited locally, unreadable, or linked outside the repo):`);
1433
- lines.push(...listNames(result.keptOutOfDir));
1434
- }
1435
- if (result.keptUnprunedOutOfDir.length > 0) {
1436
- lines.push(` ${withCount(result.keptUnprunedOutOfDir.length, 'file')} outside the bundle folders ${result.keptUnprunedOutOfDir.length === 1 ? 'is' : 'are'} no longer in any subscribed bundle, kept (--no-prune):`);
1437
- lines.push(...listNames(result.keptUnprunedOutOfDir));
1438
- }
1439
- // Grouped by the bundle each mapping names, because that is the unit of the
1440
- // one action that resolves it — and an ungrouped list would repeat the same
1441
- // sentence once per file.
1442
- const unsubscribedByBundle = new Map();
1443
- for (const { path, bundle } of result.keptUnsubscribed) {
1444
- unsubscribedByBundle.set(bundle, [...(unsubscribedByBundle.get(bundle) ?? []), path]);
1445
- }
1446
- for (const [bundle, paths] of unsubscribedByBundle) {
1447
- // Not "your config is wrong": `mossbear pull --once` produces this on
1448
- // purpose, and a pull whose config write failed already warned at the time.
1449
- // Say what was kept and what makes these files sync again; the sync has no
1450
- // way to tell those two origins apart, so it names neither.
1451
- lines.push(` ${withCount(paths.length, 'file')} came from "${bundle}", which this repo does not subscribe to — kept, since a sync only sees what left the bundles it subscribes to:`);
1452
- lines.push(...listNames(paths));
1453
- // The picker, not `mossbear pull <label>`. A mapping records a *label*, and
1454
- // `resolveBundleByName` matches an exact id or an exact slug and nothing
1455
- // else (`bundle-by-name.ts:45-56`) — so a label the docs phase wrote as a
1456
- // suffixed `dirName` (`delivery.ts:92`) resolves to "no bundle named", and a
1457
- // bare slug two bundles share resolves to ambiguous. The mapping carries no
1458
- // id to print instead, so naming a command built from the label would be
1459
- // advice that errors in exactly the collision cases this report exists for.
1460
- lines.push(' to sync them again: mossbear pull, then pick it from the list');
1461
- }
1462
- return lines;
1463
- }
1464
- /** How many names to print before summarizing the rest. */
1465
- const ORPHAN_NAME_LIMIT = 10;
1466
- /** Never wrap a comment narrower than this, however small the terminal reports. */
1467
- const MIN_WRAP_WIDTH = 20;
1468
- /**
1469
- * Name the files, capped — but say how many were withheld, never truncate in
1470
- * silence.
1471
- */
1472
- function withMirrorOutcome(mirrors, outcome) {
1473
- return mirrors.filter((entry) => entry.outcome === outcome);
1474
- }
1475
- function listNames(names) {
1476
- const shown = names
1477
- .slice(0, ORPHAN_NAME_LIMIT)
1478
- .map((name) => ` ${displayFileName(name)}`);
1479
- const rest = names.length - shown.length;
1480
- return rest > 0 ? [...shown, ` …and ${rest} more`] : shown;
1481
- }
1482
- /**
1483
- * Quote a path for a POSIX shell, so a pasted cleanup command cannot be
1484
- * talked into deleting or running anything else.
1485
- *
1486
- * `displayFileName` only neutralizes control characters — it leaves a space,
1487
- * a leading `-`, or a `$(...)` untouched, and any of those in an otherwise
1488
- * ordinary repo-relative filename would still reach the shell raw once
1489
- * printed bare into a suggested `rm` line. Single-quoting is what closes
1490
- * that: nothing inside single quotes is special to a POSIX shell except the
1491
- * quote character itself, escaped here by closing, inserting an escaped
1492
- * quote, and reopening.
1493
- */
1494
- export function shellQuotePosix(path) {
1495
- return `'${path.replace(/'/g, `'\\''`)}'`;
1496
- }
1497
- /**
1498
- * Wrap a shell command across lines a terminal will not mangle, one whole
1499
- * argument per break and a trailing `\` continuation — never a hard cut
1500
- * inside a quoted path, which `wrapText`'s whitespace-only splitting would
1501
- * risk for the sentence beside it but must not risk for a command a reader
1502
- * pastes verbatim.
1503
- */
1504
- function wrapCommandLine(head, args, width) {
1505
- const indent = ' ';
1506
- const continued = `${indent} `;
1507
- const lines = [];
1508
- let current = `${indent}${head}`;
1509
- for (const arg of args) {
1510
- const candidate = `${current} ${arg}`;
1511
- if (current === `${indent}${head}` || displayWidth(candidate) <= width) {
1512
- current = candidate;
1513
- }
1514
- else {
1515
- lines.push(`${current} \\`);
1516
- current = `${continued}${arg}`;
1517
- }
1518
- }
1519
- lines.push(current);
1520
- return lines;
1521
- }
1522
- /** Docs with a given outcome. */
1523
- function withOutcome(docs, outcome) {
1524
- return docs.filter((doc) => doc.outcome === outcome);
1525
- }
1526
- /**
1527
- * One legible block per bundle for the sync output (Planning Principle 9 — what
1528
- * moved is never ambiguous). Failures read as warnings; a successful sync says
1529
- * how many files moved in each direction, and names everything that needs the
1530
- * user: conflicts, refusals, and files the bundle no longer contains.
1531
- */
1532
- /**
1533
- * True when {@link formatArtifactsSyncLine} would say only that nothing moved.
1534
- *
1535
- * What `mossbear refresh --quiet` uses to tell a receipt from a report. A bundle
1536
- * whose every doc is `in-sync` prints a headline and nothing under it; the
1537
- * moment any doc was written, pushed, refused, held or failed, the formatter
1538
- * adds a count or a comment beneath, and that is the run's account of a change in
1539
- * this repo.
1540
- *
1541
- * Two checks, because the formatter reports in two places. The headline counts
1542
- * doc outcomes, so those are enumerated: `in-sync`, and a `git-owned` doc with
1543
- * no error — the one silent outcome, since it names the ordinary case of a
1544
- * project guide sitting in its own repo. Everything else — kept, pruned,
1545
- * unmanaged and stranded files, skipped orphan checks, conflicts — lands as a
1546
- * line *under* the headline, and there are a dozen such branches. Rather than
1547
- * list each field and drift the first time one is added, the second check asks
1548
- * the formatter itself: a result that renders to more than the headline is
1549
- * not routine, whatever put the extra line there.
1550
- */
1551
- export function artifactsSyncResultIsRoutine(result, options = {}) {
1552
- if (result.error !== undefined)
1553
- return false;
1554
- if (result.truncated)
1555
- return false;
1556
- const headlineOnly = result.docs.every((doc) => doc.outcome === 'in-sync' ||
1557
- (doc.outcome === 'git-owned' && doc.error === undefined) ||
1558
- (doc.outcome === 'out-of-scope' && options.standing === 'count'));
1559
- return headlineOnly && !formatArtifactsSyncLine(result, options).includes('\n');
1560
- }
1561
- /**
1562
- * The one line that stands for every standing list a sync left out under
1563
- * `standing: 'count'`, or nothing when there are none.
1564
- *
1565
- * **Names no command.** Every command that would list these sets in full
1566
- * either may write to the account (`refresh` publishes from the published
1567
- * branch on every run) or changes this repo's subscriptions (`pull`), and the
1568
- * reader here is usually an agent. The full lists still print wherever a person
1569
- * runs a sync with `--verbose`; this line only says they exist and that
1570
- * nothing about them changed.
1571
- */
1572
- export function formatStandingCountLine(report, width = terminalWidth()) {
1573
- const homeOnly = report.results.reduce((sum, result) => sum + (result.error ? 0 : withOutcome(result.docs, 'out-of-scope').length), 0);
1574
- const kept = report.keptOutOfDir.length +
1575
- report.results.reduce((sum, result) => sum + (result.error ? 0 : result.orphansKept.length), 0);
1576
- const parts = [];
1577
- if (homeOnly > 0) {
1578
- parts.push(`${withCount(homeOnly, 'artifact')} ${homeOnly === 1 ? 'belongs' : 'belong'} to your home directory, not this repo`);
1579
- }
1580
- if (kept > 0) {
1581
- parts.push(`${withCount(kept, 'file')} no longer in a bundle ${kept === 1 ? 'was' : 'were'} kept`);
1582
- }
1583
- if (parts.length === 0)
1584
- return [];
1585
- return wrapHanging(`left as before: ${parts.join('; ')}`, ' = ', ' ', width).split('\n');
1586
- }
1587
- export function formatArtifactsSyncLine(result, options = {}) {
1588
- if (result.error) {
1589
- const failed = [
1590
- `${severityPrefix('failed')}bundle "${result.bundle}" — ${result.error} — skipping.`,
1591
- ];
1592
- // A bundle can fail *after* writing some of its docs — the pull succeeds,
1593
- // several items materialize, and a later one throws. Returning here named
1594
- // none of them, so `mossbear refresh` reported only "skipping" for a run that had
1595
- // already changed files in the repo. Raised by Codex on PR #565.
1596
- if (result.wroteOutsideDir.length > 0) {
1597
- failed.push(` ${withCount(result.wroteOutsideDir.length, 'file')} ${result.wroteOutsideDir.length === 1 ? 'was' : 'were'} already written at their own path before it failed:`);
1598
- failed.push(...listNames(result.wroteOutsideDir));
1599
- }
1600
- return failed.join('\n');
1601
- }
1602
- const created = withOutcome(result.docs, 'created').length;
1603
- const pulled = withOutcome(result.docs, 'pulled').length;
1604
- const pushedFromCommitted = withOutcome(result.docs, 'pushed-committed');
1605
- const pushed = withOutcome(result.docs, 'pushed').length + pushedFromCommitted.length;
1606
- const inSync = withOutcome(result.docs, 'in-sync').length;
1607
- const skipped = result.items - result.docs.length;
1608
- const moved = [];
1609
- if (created > 0)
1610
- moved.push(`${created} new`);
1611
- if (pulled > 0)
1612
- moved.push(`${pulled} updated`);
1613
- if (pushed > 0)
1614
- moved.push(`${pushed} pushed`);
1615
- if (inSync > 0)
1616
- moved.push(`${inSync} unchanged`);
1617
- const skippedNote = skipped > 0
1618
- ? ` (${withCount(skipped, 'artifact')} without text content skipped, e.g. assets)`
1619
- : '';
1620
- const truncatedNote = result.truncated
1621
- ? ` — comment: hit the ${MAX_BUNDLE_PULL}-artifact limit, older artifacts may be unpulled`
1622
- : '';
1623
- const lines = [
1624
- ` synced "${result.bundle}" → ${result.dir}: ${moved.length > 0 ? moved.join(', ') : 'nothing to do'}${skippedNote}${truncatedNote}`,
1625
- ];
1626
- if (result.wroteOutsideDir.length > 0) {
1627
- // The `→ <dir>` above is this bundle's folder, and a doc at its own declared
1628
- // path did not go there. Name those files: created and pulled docs are
1629
- // otherwise only counted, so the destination line would be the only thing
1630
- // the user is told about where the write landed, and it would be wrong.
1631
- lines.push(` ${result.wroteOutsideDir.length} of them landed at their own path, outside this folder — written by this sync, not by you:`);
1632
- lines.push(...listNames(result.wroteOutsideDir));
1633
- // Said because the commonest reader is an agent mid-task, and these are the
1634
- // files that reach it as unexplained entries in `git status`. Naming where
1635
- // they came from is what stops the two wrong answers: sweeping them into an
1636
- // unrelated commit, or reverting content someone else published.
1637
- lines.push(' they came from the bundle, so they are not part of your own change — commit them on their own, or leave them');
1638
- }
1639
- const conflicted = withOutcome(result.docs, 'both-changed');
1640
- if (conflicted.length > 0) {
1641
- lines.push(` ${withCount(conflicted.length, 'artifact')} changed both locally and on the server — left untouched:`);
1642
- lines.push(...listNames(conflicted.map((doc) => doc.path)));
1643
- // **The two resolutions are not reachable from the same verb.** `remote`
1644
- // takes the server's copy, which any delivery may do; `local` publishes
1645
- // yours, which only `complete` does — every other operation refuses it by
1646
- // name (`lifecycle/operations.ts`, the `--conflict local` gate). One
1647
- // line naming both against one command sent the reader to a combination the
1648
- // CLI rejects, which is the remedy-that-does-nothing failure this repo's
1649
- // error-messaging rules exist to prevent.
1650
- lines.push(" take the server's copy: mossbear refresh --conflict remote", ' send yours instead: mossbear complete --conflict local');
1651
- }
1652
- const unverified = withOutcome(result.docs, 'unverified');
1653
- if (unverified.length > 0) {
1654
- lines.push(` ${withCount(unverified.length, 'artifact')} ${unverified.length === 1 ? 'differs' : 'differ'} from the last synced copy but could not be checked against the artifact's full history — left untouched in both directions:`);
1655
- lines.push(...listNames(unverified.map((doc) => doc.path)));
1656
- lines.push(' resolve with: mossbear refresh --conflict remote (or edit the artifact in the dashboard)');
1657
- }
1658
- const notPushed = withOutcome(result.docs, 'not-pushed');
1659
- if (notPushed.length > 0) {
1660
- lines.push(` ${withCount(notPushed.length, 'locally-edited artifact')} ${notPushed.length === 1 ? 'was' : 'were'} left as found — this run does not publish:`);
1661
- lines.push(...listNames(notPushed.map((doc) => doc.path)));
1662
- // Names a remedy that works. There is no flag any more: an edit travels
1663
- // back when the session ends, which is `mossbear complete` and only it
1664
- // (`lifecycle/operations.ts` → the contract table), and a line still
1665
- // offering `--push-docs` would send the reader after an argument the CLI
1666
- // rejects.
1667
- lines.push(' they travel back when this session ends: mossbear complete');
1668
- }
1669
- // Named, not just counted like every other `pushed` doc. Until Decision 14 an
1670
- // edit to one of these was refused with "commit them and re-run", a remedy its
1671
- // author often could not reach; saying where the bytes came from is what
1672
- // replaces that sentence.
1673
- //
1674
- // **The reason says "Mossbear keeps these", not "git does not track these",
1675
- // and the difference is a rule.** This branch never asks git — the classifier
1676
- // decides on the path alone — so tracked-ness is a cause it cannot
1677
- // distinguish, and this repo's error-messaging rules forbid naming one.
1678
- // It is not hypothetical either: a repo that force-added its documents
1679
- // before the ignore rule shipped still has them in the index, which is the
1680
- // population the tracked-file sweep below exists to find. Their edit publishes
1681
- // from disk exactly the same way, so "an edit publishes without a commit" is
1682
- // true of every file this line can name, and "git does not track these" is
1683
- // false of some of them.
1684
- //
1685
- // The classifier decides which ones, the same one the push rule asks
1686
- // (`sync-plan.ts` → `committedPushBody`), so the report cannot come to name a
1687
- // different set of files than the rule acted on. That holds despite this call
1688
- // passing one fewer argument — a `ArtifactResult` carries the path it landed at and
1689
- // not the item's root — because `record` is settled on the path alone, which
1690
- // `ArtifactRecord` says is the point rather than an accident.
1691
- const pushedFromDisk = withOutcome(result.docs, 'pushed').filter((doc) => classifyArtifactPlacement({ storedPath: doc.path }).record === 'server');
1692
- if (pushedFromDisk.length > 0) {
1693
- lines.push(` ${pushedFromDisk.length} of those were published from the file on disk — Mossbear keeps these, so an edit publishes without a commit:`);
1694
- lines.push(...listNames(pushedFromDisk.map((doc) => doc.path)));
1695
- }
1696
- if (pushedFromCommitted.length > 0) {
1697
- lines.push(` ${pushedFromCommitted.length} of those were published from their committed version — the newer edits on disk stayed here:`);
1698
- lines.push(...listNames(pushedFromCommitted.map((doc) => doc.path)));
1699
- lines.push(' commit them and re-run to publish those edits too');
1700
- }
1701
- const uncommitted = withOutcome(result.docs, 'uncommitted');
1702
- if (uncommitted.length > 0) {
1703
- lines.push(` ${withCount(uncommitted.length, 'artifact')} ${uncommitted.length === 1 ? 'has' : 'have'} changes git has not recorded — left exactly as found, in both directions:`);
1704
- lines.push(...listNames(uncommitted.map((doc) => doc.path)));
1705
- lines.push(' commit them and re-run — Mossbear exchanges committed content');
1706
- }
1707
- const unpushable = withOutcome(result.docs, 'unpushable');
1708
- if (unpushable.length > 0) {
1709
- lines.push(` ${withCount(unpushable.length, 'locally-edited artifact')} cannot be pushed — the artifact carries no version, so a safe update is impossible. Edit ${unpushable.length === 1 ? 'it' : 'them'} in the dashboard instead:`);
1710
- lines.push(...listNames(unpushable.map((doc) => doc.path)));
1711
- }
1712
- for (const invalid of withOutcome(result.docs, 'invalid-path')) {
1713
- lines.push(`${severityPrefix('failed', ' ')}guide "${displayFileName(invalid.path)}" was not materialized — ${invalid.error ?? 'unsafe projection path'}`);
1714
- }
1715
- const outOfScope = withOutcome(result.docs, 'out-of-scope');
1716
- if (outOfScope.length > 0 && options.standing !== 'count') {
1717
- lines.push(` ${withCount(outOfScope.length, 'artifact')} ${outOfScope.length === 1 ? 'belongs' : 'belong'} to your home directory, not this repo, and ${outOfScope.length === 1 ? 'was' : 'were'} not materialized here:`);
1718
- lines.push(...listNames(outOfScope.map((doc) => doc.path)));
1719
- lines.push(' edit them where they live (under your home directory) — a copy in the repo would fork them the moment you changed it');
1720
- }
1721
- // Only the ones carrying a reason. A `git-owned` skip is silent by design —
1722
- // it names the ordinary case, a project guide sitting correctly in its own
1723
- // repo — but the planner attaches an error when the run asked to publish, and
1724
- // an explicit request must never be dropped without a word.
1725
- const gitOwnedRefused = withOutcome(result.docs, 'git-owned').filter((doc) => doc.error !== undefined);
1726
- if (gitOwnedRefused.length > 0) {
1727
- lines.push(` ${withCount(gitOwnedRefused.length, 'edit')} ${gitOwnedRefused.length === 1 ? 'was' : 'were'} not published — ${gitOwnedRefused.length === 1 ? 'this file is' : 'these files are'} delivered by git, not by sync:`);
1728
- lines.push(...listNames(gitOwnedRefused.map((doc) => doc.path)));
1729
- lines.push(' commit the edit: it publishes once it lands on the published branch, and `mossbear publish` sends it sooner');
1730
- lines.push(" or `mossbear promote` to take the server's copy into this repo instead");
1731
- }
1732
- const readOnlyRefused = withOutcome(result.docs, 'read-only');
1733
- if (readOnlyRefused.length > 0) {
1734
- lines.push(` ${withCount(readOnlyRefused.length, 'edit')} ${readOnlyRefused.length === 1 ? 'was' : 'were'} not published — ${readOnlyRefused.length === 1 ? 'this artifact comes' : 'these artifacts come'} from a bundle another workspace publishes, delivered read-only:`);
1735
- lines.push(...listNames(readOnlyRefused.map((doc) => doc.path)));
1736
- lines.push(' your local copy is left exactly as it is');
1737
- }
1738
- const notHomeRepo = withOutcome(result.docs, 'not-home-repo');
1739
- if (notHomeRepo.length > 0) {
1740
- lines.push(` ${withCount(notHomeRepo.length, 'edit')} ${notHomeRepo.length === 1 ? 'was' : 'were'} not published — ${notHomeRepo.length === 1 ? 'this artifact is' : 'these artifacts are'} published from their bundle's home repository:`);
1741
- lines.push(...listNames(notHomeRepo.map((doc) => doc.path)));
1742
- lines.push(' open a pull request in that repository; your local copy is left exactly as it is');
1743
- }
1744
- const gitPublished = withOutcome(result.docs, 'git-published');
1745
- if (gitPublished.length > 0) {
1746
- lines.push(` ${withCount(gitPublished.length, 'edit')} ${gitPublished.length === 1 ? 'was' : 'were'} not published — ${gitPublished.length === 1 ? 'this artifact is' : 'these artifacts are'} published from a git repository:`);
1747
- lines.push(...listNames(gitPublished.map((doc) => doc.path)));
1748
- lines.push(' make the change there, commit it, and `mossbear publish` it from that repo; your local copy is left exactly as it is');
1749
- }
1750
- const placementConflicted = withOutcome(result.docs, 'placement-conflict');
1751
- if (placementConflicted.length > 0) {
1752
- lines.push(` ${withCount(placementConflicted.length, 'artifact')} ${placementConflicted.length === 1 ? 'has' : 'have'} two placement records at different paths — left untouched until one is removed:`);
1753
- lines.push(...listNames(placementConflicted.map((doc) => doc.path)));
1754
- lines.push(' edit .mossbear/placement.jsonl (or .mossbear/context/placement.jsonl) and delete the line naming the wrong path, then re-sync');
1755
- }
1756
- const tooLarge = withOutcome(result.docs, 'too-large');
1757
- if (tooLarge.length > 0) {
1758
- lines.push(` ${withCount(tooLarge.length, 'locally-edited artifact')} ${tooLarge.length === 1 ? 'exceeds' : 'exceed'} the ${Math.floor(MAX_CONTEXT_CONTENT_BYTES / 1024)} KB content limit and ${tooLarge.length === 1 ? 'was' : 'were'} not pushed:`);
1759
- lines.push(...listNames(tooLarge.map((doc) => doc.path)));
1760
- }
1761
- for (const failed of withOutcome(result.docs, 'push-failed')) {
1762
- lines.push(`${severityPrefix('failed', ' ')}could not push ${displayFileName(failed.path)} — ${failed.error ?? 'unknown error'}`);
1763
- }
1764
- if (result.orphanCheck === 'skipped-truncated') {
1765
- lines.push(` bundle hit the ${MAX_BUNDLE_PULL}-artifact ceiling — orphan detection skipped (cannot tell removed from unreturned)`);
1766
- }
1767
- else if (result.orphanCheck === 'skipped-unreadable') {
1768
- lines.push(`${severityPrefix('degraded', ' ')}could not read ${result.dir} — orphan detection skipped (files removed upstream may still be on disk)`);
1769
- }
1770
- else if (result.orphanCheck === 'skipped-unsafe-path') {
1771
- lines.push(`${severityPrefix('degraded', ' ')}${result.dir} resolves outside this repo's .mossbear/context — orphan detection skipped (refusing to sweep a linked directory)`);
1772
- }
1773
- if (result.orphansKept.length > 0 && options.standing !== 'count') {
1774
- lines.push(` ${withCount(result.orphansKept.length, 'file')} no longer in the bundle, kept, not safe to remove (edited locally, unreadable, or linked outside the repo):`);
1775
- lines.push(...listNames(result.orphansKept));
1776
- }
1777
- if (result.pruned.length > 0) {
1778
- lines.push(` removed ${withCount(result.pruned.length, 'file')} no longer in the bundle:`);
1779
- lines.push(...listNames(result.pruned));
1780
- }
1781
- if (result.keptUnpruned.length > 0) {
1782
- // Removal is the default, so reaching here means --no-prune: say the
1783
- // files were kept deliberately rather than pointing at a flag to run.
1784
- lines.push(` ${withCount(result.keptUnpruned.length, 'file')} no longer in the bundle, kept (--no-prune):`);
1785
- lines.push(...listNames(result.keptUnpruned));
1786
- }
1787
- if (result.unmanaged.length > 0) {
1788
- // Named, not warned about, and never acted on: the directory is the user's
1789
- // to put files in. Saying so is what keeps "Mossbear manages this folder" from
1790
- // being read as "Mossbear owns everything in it".
1791
- lines.push(` ${withCount(result.unmanaged.length, 'file')} in this folder ${result.unmanaged.length === 1 ? 'is' : 'are'} not from the bundle — left alone:`);
1792
- lines.push(...listNames(result.unmanaged));
1793
- }
1794
- if (result.strandedForeign.length > 0) {
1795
- // Said once, in the pass that also stopped tracking these files. The line
1796
- // names what is true — the guide lives in another repo — and what the user
1797
- // can do about it, which is to delete a copy nothing here maintains any
1798
- // more. It must not say the files are inert: they sit at discovery roots,
1799
- // so every agent in this repo still reads them, and that is the whole
1800
- // reason the line exists.
1801
- lines.push(` ${withCount(result.strandedForeign.length, 'file')} here ${result.strandedForeign.length === 1 ? 'is a copy' : 'are copies'} of a guide that belongs to a different repo — left exactly as found, and no longer tracked:`);
1802
- lines.push(...listNames(result.strandedForeign));
1803
- lines.push(' delete them when you are ready — agents in this repo still read them, and nothing keeps them up to date now');
1804
- }
1805
- if (result.strandedLiteral.length > 0) {
1806
- // Said once, in the pass that stopped tracking these files. The document is
1807
- // still delivered — the line says where — so what is left for the user is
1808
- // only the old copy, which is theirs to keep or delete.
1809
- lines.push(` ${withCount(result.strandedLiteral.length, 'file')} here ${result.strandedLiteral.length === 1 ? 'is an old copy' : 'are old copies'} of an artifact this repo is not the home of — left exactly as found, and no longer tracked:`);
1810
- lines.push(...listNames(result.strandedLiteral));
1811
- lines.push(' the artifact itself now lands under .mossbear/context/ instead — delete the old copy whenever you like');
1812
- }
1813
- if (result.strandedTwins.length > 0) {
1814
- // Named and left alone. The two ways a repo ends up with one of these — the
1815
- // guide's scope was changed, or an older CLI wrote a repo copy of a guide
1816
- // that was already global — are indistinguishable from here, so the line
1817
- // names neither: error copy must never state a cause the branch cannot
1818
- // distinguish. Nor does it say where the guide is kept now: since
1819
- // `global-delivery-dual-write-close` that depends on a consent this
1820
- // renderer does not read, and for a user who declined, this twin may be
1821
- // the only copy on the machine. It says what is true in every case — the
1822
- // sync no longer maintains this file — and where the answer lives.
1823
- lines.push(` ${withCount(result.strandedTwins.length, 'file')} ${result.strandedTwins.length === 1 ? 'is an old copy' : 'are old copies'} of a guide that is no longer delivered here — left exactly as found:`);
1824
- lines.push(...listNames(result.strandedTwins));
1825
- // **Never "nothing reads them".** They sit at a discovery root, so every
1826
- // agent in this repo still loads them — that is the whole reason this line
1827
- // exists, and telling the user they are inert is what would leave outdated
1828
- // guidance steering their sessions.
1829
- lines.push(' your agents here still read them, and nothing here keeps them up to date — `mossbear status` shows where the guide is delivered now; delete them whenever you like; Mossbear will not remove a file from your repo for you');
1830
- }
1831
- if (result.pruneFailed.length > 0) {
1832
- lines.push(`${severityPrefix('failed', ' ')}could not remove ${withCount(result.pruneFailed.length, 'file')}:`);
1833
- lines.push(...listNames(result.pruneFailed));
1834
- }
1835
- if (result.mutedArtifacts.length > 0) {
1836
- lines.push(` ${withCount(result.mutedArtifacts.length, 'artifact')} you muted ${result.mutedArtifacts.length === 1 ? 'was' : 'were'} not delivered:`);
1837
- lines.push(...listNames(result.mutedArtifacts));
1838
- }
1839
- if (result.migrateFailed.length > 0) {
1840
- lines.push(`${severityPrefix('failed', ' ')}could not move ${withCount(result.migrateFailed.length, 'guide file')} out of this folder, so ${result.migrateFailed.length === 1 ? 'it is' : 'they are'} not being read as guidance yet — remove ${result.migrateFailed.length === 1 ? 'it' : 'them'} by hand and re-sync:`);
1841
- lines.push(...listNames(result.migrateFailed));
1842
- }
1843
- return lines.join('\n');
1844
- }
1845
1082
  /** Whether a mute set names this item, by its own id or the guide it rides. */
1846
1083
  function switchedOff(set, item) {
1847
1084
  return set.has(item.id) || (item.guideId != null && set.has(item.guideId));