@mossbear/protocol 0.1.0-alpha.100

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 (143) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +7 -0
  3. package/dist/agentGuidancePaths.d.ts +101 -0
  4. package/dist/agentGuidancePaths.d.ts.map +1 -0
  5. package/dist/agentGuidancePaths.js +185 -0
  6. package/dist/agentGuidancePaths.js.map +1 -0
  7. package/dist/agentGuidancePaths.test.d.ts +2 -0
  8. package/dist/agentGuidancePaths.test.d.ts.map +1 -0
  9. package/dist/agentGuidancePaths.test.js +91 -0
  10. package/dist/agentGuidancePaths.test.js.map +1 -0
  11. package/dist/aliasPaths.d.ts +100 -0
  12. package/dist/aliasPaths.d.ts.map +1 -0
  13. package/dist/aliasPaths.js +148 -0
  14. package/dist/aliasPaths.js.map +1 -0
  15. package/dist/aliasPaths.test.d.ts +2 -0
  16. package/dist/aliasPaths.test.d.ts.map +1 -0
  17. package/dist/aliasPaths.test.js +80 -0
  18. package/dist/aliasPaths.test.js.map +1 -0
  19. package/dist/artifact.test.d.ts +2 -0
  20. package/dist/artifact.test.d.ts.map +1 -0
  21. package/dist/artifact.test.js +374 -0
  22. package/dist/artifact.test.js.map +1 -0
  23. package/dist/bundleSlug.d.ts +177 -0
  24. package/dist/bundleSlug.d.ts.map +1 -0
  25. package/dist/bundleSlug.js +233 -0
  26. package/dist/bundleSlug.js.map +1 -0
  27. package/dist/bundleSlug.test.d.ts +2 -0
  28. package/dist/bundleSlug.test.d.ts.map +1 -0
  29. package/dist/bundleSlug.test.js +197 -0
  30. package/dist/bundleSlug.test.js.map +1 -0
  31. package/dist/commentAnchor.d.ts +34 -0
  32. package/dist/commentAnchor.d.ts.map +1 -0
  33. package/dist/commentAnchor.js +122 -0
  34. package/dist/commentAnchor.js.map +1 -0
  35. package/dist/commentAnchor.test.d.ts +2 -0
  36. package/dist/commentAnchor.test.d.ts.map +1 -0
  37. package/dist/commentAnchor.test.js +48 -0
  38. package/dist/commentAnchor.test.js.map +1 -0
  39. package/dist/contextKinds.d.ts +165 -0
  40. package/dist/contextKinds.d.ts.map +1 -0
  41. package/dist/contextKinds.js +148 -0
  42. package/dist/contextKinds.js.map +1 -0
  43. package/dist/contextKinds.test.d.ts +2 -0
  44. package/dist/contextKinds.test.d.ts.map +1 -0
  45. package/dist/contextKinds.test.js +137 -0
  46. package/dist/contextKinds.test.js.map +1 -0
  47. package/dist/frameDocument.d.ts +71 -0
  48. package/dist/frameDocument.d.ts.map +1 -0
  49. package/dist/frameDocument.js +140 -0
  50. package/dist/frameDocument.js.map +1 -0
  51. package/dist/frameDocument.test.d.ts +2 -0
  52. package/dist/frameDocument.test.d.ts.map +1 -0
  53. package/dist/frameDocument.test.js +84 -0
  54. package/dist/frameDocument.test.js.map +1 -0
  55. package/dist/frameProtocol.d.ts +11 -0
  56. package/dist/frameProtocol.d.ts.map +1 -0
  57. package/dist/frameProtocol.js +11 -0
  58. package/dist/frameProtocol.js.map +1 -0
  59. package/dist/index.d.ts +24 -0
  60. package/dist/index.d.ts.map +1 -0
  61. package/dist/index.js +24 -0
  62. package/dist/index.js.map +1 -0
  63. package/dist/limits.d.ts +19 -0
  64. package/dist/limits.d.ts.map +1 -0
  65. package/dist/limits.js +19 -0
  66. package/dist/limits.js.map +1 -0
  67. package/dist/markdownSections.d.ts +58 -0
  68. package/dist/markdownSections.d.ts.map +1 -0
  69. package/dist/markdownSections.js +102 -0
  70. package/dist/markdownSections.js.map +1 -0
  71. package/dist/markdownSections.test.d.ts +2 -0
  72. package/dist/markdownSections.test.d.ts.map +1 -0
  73. package/dist/markdownSections.test.js +95 -0
  74. package/dist/markdownSections.test.js.map +1 -0
  75. package/dist/pairing.d.ts +183 -0
  76. package/dist/pairing.d.ts.map +1 -0
  77. package/dist/pairing.js +175 -0
  78. package/dist/pairing.js.map +1 -0
  79. package/dist/pairing.test.d.ts +2 -0
  80. package/dist/pairing.test.d.ts.map +1 -0
  81. package/dist/pairing.test.js +105 -0
  82. package/dist/pairing.test.js.map +1 -0
  83. package/dist/photos.d.ts +146 -0
  84. package/dist/photos.d.ts.map +1 -0
  85. package/dist/photos.js +127 -0
  86. package/dist/photos.js.map +1 -0
  87. package/dist/publicModelCatalog.d.ts +19 -0
  88. package/dist/publicModelCatalog.d.ts.map +1 -0
  89. package/dist/publicModelCatalog.generated.d.ts +2 -0
  90. package/dist/publicModelCatalog.generated.d.ts.map +1 -0
  91. package/dist/publicModelCatalog.generated.js +489 -0
  92. package/dist/publicModelCatalog.generated.js.map +1 -0
  93. package/dist/publicModelCatalog.js +68 -0
  94. package/dist/publicModelCatalog.js.map +1 -0
  95. package/dist/publicModelCatalog.test.d.ts +2 -0
  96. package/dist/publicModelCatalog.test.d.ts.map +1 -0
  97. package/dist/publicModelCatalog.test.js +88 -0
  98. package/dist/publicModelCatalog.test.js.map +1 -0
  99. package/dist/publicModelNativeAliases.d.ts +5 -0
  100. package/dist/publicModelNativeAliases.d.ts.map +1 -0
  101. package/dist/publicModelNativeAliases.js +8 -0
  102. package/dist/publicModelNativeAliases.js.map +1 -0
  103. package/dist/schemas.d.ts +10745 -0
  104. package/dist/schemas.d.ts.map +1 -0
  105. package/dist/schemas.js +4572 -0
  106. package/dist/schemas.js.map +1 -0
  107. package/dist/schemas.test.d.ts +2 -0
  108. package/dist/schemas.test.d.ts.map +1 -0
  109. package/dist/schemas.test.js +1617 -0
  110. package/dist/schemas.test.js.map +1 -0
  111. package/dist/steeringOverTime.d.ts +30 -0
  112. package/dist/steeringOverTime.d.ts.map +1 -0
  113. package/dist/steeringOverTime.js +19 -0
  114. package/dist/steeringOverTime.js.map +1 -0
  115. package/dist/types.d.ts +109 -0
  116. package/dist/types.d.ts.map +1 -0
  117. package/dist/types.js +12 -0
  118. package/dist/types.js.map +1 -0
  119. package/dist/usageOnly.d.ts +190 -0
  120. package/dist/usageOnly.d.ts.map +1 -0
  121. package/dist/usageOnly.js +53 -0
  122. package/dist/usageOnly.js.map +1 -0
  123. package/dist/usageOnly.test.d.ts +2 -0
  124. package/dist/usageOnly.test.d.ts.map +1 -0
  125. package/dist/usageOnly.test.js +203 -0
  126. package/dist/usageOnly.test.js.map +1 -0
  127. package/dist/version.d.ts +47 -0
  128. package/dist/version.d.ts.map +1 -0
  129. package/dist/version.js +125 -0
  130. package/dist/version.js.map +1 -0
  131. package/dist/version.test.d.ts +2 -0
  132. package/dist/version.test.d.ts.map +1 -0
  133. package/dist/version.test.js +86 -0
  134. package/dist/version.test.js.map +1 -0
  135. package/dist/whatSyncs.d.ts +62 -0
  136. package/dist/whatSyncs.d.ts.map +1 -0
  137. package/dist/whatSyncs.js +228 -0
  138. package/dist/whatSyncs.js.map +1 -0
  139. package/dist/whatSyncs.test.d.ts +2 -0
  140. package/dist/whatSyncs.test.d.ts.map +1 -0
  141. package/dist/whatSyncs.test.js +113 -0
  142. package/dist/whatSyncs.test.js.map +1 -0
  143. package/package.json +52 -0
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Mossbear
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md ADDED
@@ -0,0 +1,7 @@
1
+ # @mossbear/protocol
2
+
3
+ Shared types and Valibot wire schemas for [Mossbear](https://app.mossbear.io) — the contract between the [`mossbear` CLI](https://www.npmjs.com/package/mossbear) and the Mossbear dashboard (action-sync payloads, raw guide-file payloads, context-bundle payloads).
4
+
5
+ You normally don't install this directly; it ships as a dependency of `mossbear`.
6
+
7
+ Source: https://github.com/mossbear-io/mossbear (`packages/protocol`)
@@ -0,0 +1,101 @@
1
+ /**
2
+ * The one list of paths that are *agent guidance* rather than ordinary content,
3
+ * and the predicate that reads it.
4
+ *
5
+ * **Why this is in the protocol package and not next to either caller.** Two
6
+ * boundaries need the same answer and they live on opposite sides of the wire:
7
+ * the CLI refuses to *write* context into a discovery location
8
+ * (`packages/cli/src/mcp/write-scope.ts`), and the server refuses to *accept* a
9
+ * document that declares one as its path (the context-items create route). Both
10
+ * already depend on `@mossbear/protocol`, and it is the only place they meet.
11
+ *
12
+ * Keeping a copy on each side would be two lists that must be updated together,
13
+ * and the failure mode is silent and one-directional: a format added to one and
14
+ * missed on the other is a hole nobody sees until an agent writes through it.
15
+ * One list, two boundaries — a future call site should not be able to forget
16
+ * this (Planning Principle 14).
17
+ *
18
+ * Deliberately **wider than any single discovery scan**. The question here is
19
+ * not "what should I scan?" but "what must I refuse?", and those diverge safely
20
+ * in only one direction — a root that discovery picks up and this list misses
21
+ * reopens the fork, while the reverse merely refuses a path a user can rename.
22
+ */
23
+ /**
24
+ * Directories whose contents are auto-discovered as guide files, relative to a
25
+ * repo root. Covers both the project and global root lists
26
+ * (`packages/cli/src/rules/discover.ts:98-105`).
27
+ */
28
+ export declare const AGENT_GUIDANCE_DIRS: ReadonlyArray<string>;
29
+ /**
30
+ * Guide files auto-discovered at a repo root
31
+ * (`packages/cli/src/rules/discover.ts:90-97`, `:104`).
32
+ */
33
+ export declare const AGENT_GUIDANCE_FILES: ReadonlyArray<string>;
34
+ /**
35
+ * True when `fileName` — a single path segment, not a path — is one of the
36
+ * guide files discovered at a repo root.
37
+ *
38
+ * Case-insensitive, because the claim is about a **file** and not a string:
39
+ * `AGENTS.md` and `agents.md` are two strings and one file on macOS and
40
+ * Windows, so an exact-match check lets the second one through to the same
41
+ * inode the first one was refused for.
42
+ */
43
+ export declare function isAgentGuidanceFileName(fileName: string): boolean;
44
+ /**
45
+ * True when a repo-relative POSIX path is agent guidance — either it *is* a
46
+ * discovered guide file at the root, or it lives inside a discovered directory.
47
+ *
48
+ * Takes the whole path rather than a segment because both halves of the rule
49
+ * have to be applied together to be worth anything: refusing `AGENTS.md` while
50
+ * accepting `.agents/notes.md` just moves the same write one directory down,
51
+ * and the next import scans that directory.
52
+ *
53
+ * Expects the caller to have already validated the shape of the path
54
+ * (`SafeRelativePosixPathSchema`) — it does no traversal checking of its own,
55
+ * and a `..` segment would defeat the head comparison below.
56
+ */
57
+ export declare function isAgentGuidancePath(path: string): boolean;
58
+ /**
59
+ * True when a repo-relative path names Mossbear's own state rather than user
60
+ * content — `.mossbear/config.json` and friends, but not the content subtrees.
61
+ *
62
+ * Checked on the **resolved** spelling, not the raw one (Codex, PR #564).
63
+ * `docs/../.mossbear/config.json` does not start with `.mossbear/`, and
64
+ * `.mossbear/context/../../.mossbear/config.json` looks like an allowed
65
+ * subtree — both resolve to `.mossbear/config.json`, which is what actually
66
+ * gets written.
67
+ *
68
+ * Lives here rather than in the CLI for the same reason the discovery lists do:
69
+ * the server refuses a document that *declares* one of these paths and the CLI
70
+ * refuses one it would *write*, and two copies of the rule is one
71
+ * symlink-escape's worth of drift away from each other (Planning Principle 14).
72
+ */
73
+ export declare function isReservedStatePath(candidate: string): boolean;
74
+ /**
75
+ * True when a repo-relative path is inside git's own directory — `.git/config`,
76
+ * `.git/hooks/pre-commit`, the `.git` gitfile a worktree or submodule keeps, or
77
+ * a nested repository's `.git/` further down.
78
+ *
79
+ * **Git itself refuses to track such a path** (`verify_path` rejects any `.git`
80
+ * component), so a project item declaring one can never be delivered by
81
+ * `git clone` or `git merge` — which is the only way a project item is supposed
82
+ * to reach a working tree. The one thing left that could write it is
83
+ * `mossbear promote`, and the write is not inert: git reads `.git/config` on the
84
+ * next `git status` and runs whatever `core.fsmonitor`, `core.hooksPath` or
85
+ * `core.pager` names, with no commit for anyone to review. A shared bundle is
86
+ * writable by every member of its workspace and by any agent holding a
87
+ * member's token, so the path has to be refused where it is declared and again
88
+ * where it would be written, the same two halves `isReservedStatePath` has.
89
+ *
90
+ * Any `.git` segment, anywhere, under git's own NTFS-aware fold
91
+ * (`is_ntfs_dotgit` in git's `path.c`), because the writer may be a Windows
92
+ * machine even when the server is not: Win32 strips trailing dots and spaces
93
+ * from a segment, resolves the 8.3 short name `GIT~1`, and reads `:` as an
94
+ * alternate data stream on the segment before it — so `.git /config`,
95
+ * `.git./config`, `GIT~1/config` and `.git:x/config` all land in the real
96
+ * `.git/`. Case-folded for the same reason. `.gitignore`, `.github/` and
97
+ * `docs/git.md` are ordinary paths: after the fold the segment has to be
98
+ * exactly `.git` or `git~1`.
99
+ */
100
+ export declare function isGitInternalPath(candidate: string): boolean;
101
+ //# sourceMappingURL=agentGuidancePaths.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"agentGuidancePaths.d.ts","sourceRoot":"","sources":["../src/agentGuidancePaths.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,EAAE,aAAa,CAAC,MAAM,CAIrD,CAAA;AAED;;;GAGG;AACH,eAAO,MAAM,oBAAoB,EAAE,aAAa,CAAC,MAAM,CAItD,CAAA;AAED;;;;;;;;GAQG;AACH,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAIjE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAYzD;AAkDD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAK9D;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAO5D"}
@@ -0,0 +1,185 @@
1
+ /**
2
+ * The one list of paths that are *agent guidance* rather than ordinary content,
3
+ * and the predicate that reads it.
4
+ *
5
+ * **Why this is in the protocol package and not next to either caller.** Two
6
+ * boundaries need the same answer and they live on opposite sides of the wire:
7
+ * the CLI refuses to *write* context into a discovery location
8
+ * (`packages/cli/src/mcp/write-scope.ts`), and the server refuses to *accept* a
9
+ * document that declares one as its path (the context-items create route). Both
10
+ * already depend on `@mossbear/protocol`, and it is the only place they meet.
11
+ *
12
+ * Keeping a copy on each side would be two lists that must be updated together,
13
+ * and the failure mode is silent and one-directional: a format added to one and
14
+ * missed on the other is a hole nobody sees until an agent writes through it.
15
+ * One list, two boundaries — a future call site should not be able to forget
16
+ * this (Planning Principle 14).
17
+ *
18
+ * Deliberately **wider than any single discovery scan**. The question here is
19
+ * not "what should I scan?" but "what must I refuse?", and those diverge safely
20
+ * in only one direction — a root that discovery picks up and this list misses
21
+ * reopens the fork, while the reverse merely refuses a path a user can rename.
22
+ */
23
+ /**
24
+ * Directories whose contents are auto-discovered as guide files, relative to a
25
+ * repo root. Covers both the project and global root lists
26
+ * (`packages/cli/src/rules/discover.ts:98-105`).
27
+ */
28
+ export const AGENT_GUIDANCE_DIRS = [
29
+ '.agents',
30
+ '.claude',
31
+ '.cursor',
32
+ ];
33
+ /**
34
+ * Guide files auto-discovered at a repo root
35
+ * (`packages/cli/src/rules/discover.ts:90-97`, `:104`).
36
+ */
37
+ export const AGENT_GUIDANCE_FILES = [
38
+ 'AGENTS.md',
39
+ 'CLAUDE.md',
40
+ '.cursorrules',
41
+ ];
42
+ /**
43
+ * True when `fileName` — a single path segment, not a path — is one of the
44
+ * guide files discovered at a repo root.
45
+ *
46
+ * Case-insensitive, because the claim is about a **file** and not a string:
47
+ * `AGENTS.md` and `agents.md` are two strings and one file on macOS and
48
+ * Windows, so an exact-match check lets the second one through to the same
49
+ * inode the first one was refused for.
50
+ */
51
+ export function isAgentGuidanceFileName(fileName) {
52
+ return AGENT_GUIDANCE_FILES.some((candidate) => candidate.toLowerCase() === fileName.toLowerCase());
53
+ }
54
+ /**
55
+ * True when a repo-relative POSIX path is agent guidance — either it *is* a
56
+ * discovered guide file at the root, or it lives inside a discovered directory.
57
+ *
58
+ * Takes the whole path rather than a segment because both halves of the rule
59
+ * have to be applied together to be worth anything: refusing `AGENTS.md` while
60
+ * accepting `.agents/notes.md` just moves the same write one directory down,
61
+ * and the next import scans that directory.
62
+ *
63
+ * Expects the caller to have already validated the shape of the path
64
+ * (`SafeRelativePosixPathSchema`) — it does no traversal checking of its own,
65
+ * and a `..` segment would defeat the head comparison below.
66
+ */
67
+ export function isAgentGuidancePath(path) {
68
+ const segments = path.split('/').filter((segment) => segment.length > 0);
69
+ if (segments.length === 0)
70
+ return false;
71
+ const head = segments[0];
72
+ if (head !== undefined && segments.length > 1) {
73
+ const lowered = head.toLowerCase();
74
+ if (AGENT_GUIDANCE_DIRS.some((dir) => dir === lowered))
75
+ return true;
76
+ }
77
+ const last = segments[segments.length - 1];
78
+ return last !== undefined && isAgentGuidanceFileName(last);
79
+ }
80
+ /**
81
+ * Mossbear's own state directory, minus the two subtrees that are content.
82
+ *
83
+ * **Deny the control files, not the directory.** `.mossbear/context/` and
84
+ * `.mossbear/evals/` are content trees the user commits and reviews, and
85
+ * refusing them would break the shadow tree eval criteria already materialize
86
+ * into.
87
+ */
88
+ const MOSSBEAR_CONTENT_SUBTREES = [
89
+ '.mossbear/context/',
90
+ '.mossbear/evals/',
91
+ ];
92
+ /**
93
+ * State files Mossbear keeps *inside* a content subtree.
94
+ *
95
+ * The context folder's placement record sits at the top of the folder it
96
+ * describes, so it shares the folder's ignore rule and its fate; that puts it
97
+ * under a subtree documents may otherwise land in, and a document declaring
98
+ * this path would overwrite the record.
99
+ */
100
+ const MOSSBEAR_CONTENT_STATE_FILES = [
101
+ '.mossbear/context/placement.jsonl',
102
+ ];
103
+ /**
104
+ * Resolve `.` and `..` over a POSIX path's segments, without `node:path`.
105
+ *
106
+ * Hand-rolled because this module is imported by the dashboard as well as the
107
+ * CLI, and a `node:path` import would follow the schemas into the web bundle.
108
+ * It only has to be right for relative paths, which is all the callers pass —
109
+ * a leading `..` that escapes is preserved rather than dropped, so a caller
110
+ * checking a prefix still sees it did not match.
111
+ */
112
+ function normalizePosixRelative(path) {
113
+ const out = [];
114
+ for (const segment of path.split('/')) {
115
+ if (segment === '' || segment === '.')
116
+ continue;
117
+ if (segment === '..') {
118
+ if (out.length > 0 && out[out.length - 1] !== '..')
119
+ out.pop();
120
+ else
121
+ out.push('..');
122
+ continue;
123
+ }
124
+ out.push(segment);
125
+ }
126
+ return out.join('/');
127
+ }
128
+ /**
129
+ * True when a repo-relative path names Mossbear's own state rather than user
130
+ * content — `.mossbear/config.json` and friends, but not the content subtrees.
131
+ *
132
+ * Checked on the **resolved** spelling, not the raw one (Codex, PR #564).
133
+ * `docs/../.mossbear/config.json` does not start with `.mossbear/`, and
134
+ * `.mossbear/context/../../.mossbear/config.json` looks like an allowed
135
+ * subtree — both resolve to `.mossbear/config.json`, which is what actually
136
+ * gets written.
137
+ *
138
+ * Lives here rather than in the CLI for the same reason the discovery lists do:
139
+ * the server refuses a document that *declares* one of these paths and the CLI
140
+ * refuses one it would *write*, and two copies of the rule is one
141
+ * symlink-escape's worth of drift away from each other (Planning Principle 14).
142
+ */
143
+ export function isReservedStatePath(candidate) {
144
+ const normalized = normalizePosixRelative(candidate.replace(/\\/g, '/')).toLowerCase();
145
+ if (!normalized.startsWith('.mossbear/'))
146
+ return false;
147
+ if (MOSSBEAR_CONTENT_STATE_FILES.includes(normalized))
148
+ return true;
149
+ return !MOSSBEAR_CONTENT_SUBTREES.some((subtree) => normalized.startsWith(subtree));
150
+ }
151
+ /**
152
+ * True when a repo-relative path is inside git's own directory — `.git/config`,
153
+ * `.git/hooks/pre-commit`, the `.git` gitfile a worktree or submodule keeps, or
154
+ * a nested repository's `.git/` further down.
155
+ *
156
+ * **Git itself refuses to track such a path** (`verify_path` rejects any `.git`
157
+ * component), so a project item declaring one can never be delivered by
158
+ * `git clone` or `git merge` — which is the only way a project item is supposed
159
+ * to reach a working tree. The one thing left that could write it is
160
+ * `mossbear promote`, and the write is not inert: git reads `.git/config` on the
161
+ * next `git status` and runs whatever `core.fsmonitor`, `core.hooksPath` or
162
+ * `core.pager` names, with no commit for anyone to review. A shared bundle is
163
+ * writable by every member of its workspace and by any agent holding a
164
+ * member's token, so the path has to be refused where it is declared and again
165
+ * where it would be written, the same two halves `isReservedStatePath` has.
166
+ *
167
+ * Any `.git` segment, anywhere, under git's own NTFS-aware fold
168
+ * (`is_ntfs_dotgit` in git's `path.c`), because the writer may be a Windows
169
+ * machine even when the server is not: Win32 strips trailing dots and spaces
170
+ * from a segment, resolves the 8.3 short name `GIT~1`, and reads `:` as an
171
+ * alternate data stream on the segment before it — so `.git /config`,
172
+ * `.git./config`, `GIT~1/config` and `.git:x/config` all land in the real
173
+ * `.git/`. Case-folded for the same reason. `.gitignore`, `.github/` and
174
+ * `docs/git.md` are ordinary paths: after the fold the segment has to be
175
+ * exactly `.git` or `git~1`.
176
+ */
177
+ export function isGitInternalPath(candidate) {
178
+ const normalized = normalizePosixRelative(candidate.replace(/\\/g, '/'));
179
+ return normalized.split('/').some((segment) => {
180
+ const streamless = segment.split(':')[0] ?? '';
181
+ const folded = streamless.replace(/[. ]+$/, '').toLowerCase();
182
+ return folded === '.git' || folded === 'git~1';
183
+ });
184
+ }
185
+ //# sourceMappingURL=agentGuidancePaths.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"agentGuidancePaths.js","sourceRoot":"","sources":["../src/agentGuidancePaths.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,2 @@
1
+ export {};
2
+ //# sourceMappingURL=agentGuidancePaths.test.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"agentGuidancePaths.test.d.ts","sourceRoot":"","sources":["../src/agentGuidancePaths.test.ts"],"names":[],"mappings":""}
@@ -0,0 +1,91 @@
1
+ import { describe, expect, it } from 'vitest';
2
+ import { isAgentGuidanceFileName, isAgentGuidancePath, isGitInternalPath, isReservedStatePath, } from './agentGuidancePaths.js';
3
+ describe('isAgentGuidancePath', () => {
4
+ it("refuses a path that would become the repo's guidance file", () => {
5
+ expect(isAgentGuidancePath('AGENTS.md')).toBe(true);
6
+ expect(isAgentGuidancePath('CLAUDE.md')).toBe(true);
7
+ expect(isAgentGuidancePath('.cursorrules')).toBe(true);
8
+ });
9
+ it('refuses the same file spelled in another case', () => {
10
+ // Two strings, one file on macOS and Windows — an exact-match check would
11
+ // refuse the first and hand the second the same inode.
12
+ expect(isAgentGuidancePath('agents.md')).toBe(true);
13
+ expect(isAgentGuidancePath('Claude.MD')).toBe(true);
14
+ });
15
+ it('refuses a path inside a directory that is scanned for guidance', () => {
16
+ // Refusing AGENTS.md while allowing this would just move the same write
17
+ // one directory down, and the next import scans that directory.
18
+ expect(isAgentGuidancePath('.agents/style.md')).toBe(true);
19
+ expect(isAgentGuidancePath('.claude/skills/x/SKILL.md')).toBe(true);
20
+ expect(isAgentGuidancePath('.cursor/rules/x.md')).toBe(true);
21
+ });
22
+ it('allows an ordinary document path', () => {
23
+ expect(isAgentGuidancePath('docs/api-notes.md')).toBe(false);
24
+ expect(isAgentGuidancePath('README.md')).toBe(false);
25
+ // Nested, because discovery scans these directories at the repo root.
26
+ expect(isAgentGuidancePath('docs/agents/overview.md')).toBe(false);
27
+ });
28
+ });
29
+ describe('isAgentGuidanceFileName', () => {
30
+ it('answers about one segment, not a path', () => {
31
+ expect(isAgentGuidanceFileName('AGENTS.md')).toBe(true);
32
+ expect(isAgentGuidanceFileName('notes.md')).toBe(false);
33
+ });
34
+ });
35
+ describe('isReservedStatePath', () => {
36
+ it("refuses Mossbear's own control files", () => {
37
+ expect(isReservedStatePath('.mossbear/config.json')).toBe(true);
38
+ expect(isReservedStatePath('.mossbear/docs.json')).toBe(true);
39
+ });
40
+ it('refuses them however they are spelled', () => {
41
+ // Checked on the resolved spelling: both of these are written to
42
+ // `.mossbear/config.json` whatever the caller typed.
43
+ expect(isReservedStatePath('docs/../.mossbear/config.json')).toBe(true);
44
+ expect(isReservedStatePath('.mossbear/context/../../.mossbear/config.json')).toBe(true);
45
+ });
46
+ it('refuses the placement record kept inside the context folder', () => {
47
+ expect(isReservedStatePath('.mossbear/context/placement.jsonl')).toBe(true);
48
+ expect(isReservedStatePath('.mossbear/context/../context/Placement.jsonl')).toBe(true);
49
+ expect(isReservedStatePath('.mossbear/context/notes/placement.jsonl')).toBe(false);
50
+ });
51
+ it('allows the content trees the user commits and reviews', () => {
52
+ expect(isReservedStatePath('.mossbear/context/note.md')).toBe(false);
53
+ expect(isReservedStatePath('.mossbear/evals/AGENTS.md')).toBe(false);
54
+ });
55
+ it('allows an ordinary path', () => {
56
+ expect(isReservedStatePath('docs/notes.md')).toBe(false);
57
+ });
58
+ });
59
+ describe('isGitInternalPath', () => {
60
+ it("refuses git's own directory, where a written file is read and acted on", () => {
61
+ expect(isGitInternalPath('.git/config')).toBe(true);
62
+ expect(isGitInternalPath('.git/hooks/pre-commit')).toBe(true);
63
+ // The gitfile a worktree or submodule checkout keeps in place of the directory.
64
+ expect(isGitInternalPath('.git')).toBe(true);
65
+ // A nested repository's directory is git's too.
66
+ expect(isGitInternalPath('vendor/lib/.git/config')).toBe(true);
67
+ });
68
+ it('refuses it however it is spelled', () => {
69
+ expect(isGitInternalPath('docs/../.git/config')).toBe(true);
70
+ expect(isGitInternalPath('.GIT/config')).toBe(true);
71
+ expect(isGitInternalPath('.git\\config')).toBe(true);
72
+ });
73
+ it("refuses the spellings Windows folds onto .git, the way git's own check does", () => {
74
+ // Win32 drops trailing dots and spaces from a segment, resolves the 8.3
75
+ // short name, and treats `:` as a stream on the segment before it — so each
76
+ // of these writes into the real `.git/` on a Windows checkout.
77
+ expect(isGitInternalPath('.git /config')).toBe(true);
78
+ expect(isGitInternalPath('.git./config')).toBe(true);
79
+ expect(isGitInternalPath('.git. . /config')).toBe(true);
80
+ expect(isGitInternalPath('GIT~1/config')).toBe(true);
81
+ expect(isGitInternalPath('git~1')).toBe(true);
82
+ expect(isGitInternalPath('.git:$INDEX_ALLOCATION/config')).toBe(true);
83
+ });
84
+ it('allows the ordinary paths that merely start with the same letters', () => {
85
+ expect(isGitInternalPath('.gitignore')).toBe(false);
86
+ expect(isGitInternalPath('.github/CONTRIBUTING.md')).toBe(false);
87
+ expect(isGitInternalPath('.gitmodules')).toBe(false);
88
+ expect(isGitInternalPath('docs/git.md')).toBe(false);
89
+ });
90
+ });
91
+ //# sourceMappingURL=agentGuidancePaths.test.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"agentGuidancePaths.test.js","sourceRoot":"","sources":["../src/agentGuidancePaths.test.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,100 @@
1
+ /**
2
+ * **Which paths are the same rules under two names** — the alias sets
3
+ * (`alias-instruction-file-identity-plan.md` → Decision 5, *same
4
+ * root, different path*).
5
+ *
6
+ * A repo that uses Cursor alongside anything else can hold `.cursorrules` and
7
+ * `AGENTS.md` with the same rules in both, and without this each imports as its
8
+ * own guide with nothing keeping them together. This module is the one definition
9
+ * of "these two paths are one rule", so the server can collapse an identical
10
+ * pair into a single guide and the CLI can derive the mirror in the checkout
11
+ * from the same list.
12
+ *
13
+ * **Why the protocol package.** Both sides need the identical answer and they
14
+ * sit on opposite sides of the wire — the import route decides which payloads
15
+ * collapse, and the CLI's docs phase decides which files to derive. Same
16
+ * argument as {@link ./agentGuidancePaths.ts}, and the same failure mode from
17
+ * keeping a copy on each side: a path added to one and missed on the other is
18
+ * silent in exactly one direction, since the server would merge a pair the CLI
19
+ * then never mirrors.
20
+ *
21
+ * **Not a discovery list.** Discovery decides what to scan
22
+ * (`packages/cli/src/rules/discover.ts:93-105`); this decides which of the
23
+ * scanned paths are interchangeable. The two overlap without either being a
24
+ * subset of the other: `.claude/rules/*.md` is discovered and has no alias, and
25
+ * a future `~/.agents/skills` root is an alias of `.claude/skills` before any
26
+ * scan reaches it.
27
+ */
28
+ /** Group key for the root instruction files — `AGENTS.md` and its twins. */
29
+ export declare const ROOT_INSTRUCTIONS_ALIAS_GROUP = "root-instructions";
30
+ /** Group-key prefix for one skill's `SKILL.md` under either skills directory. */
31
+ export declare const SKILL_ALIAS_GROUP_PREFIX = "skill:";
32
+ /**
33
+ * One path's place in an alias set: which set it belongs to, and how strongly
34
+ * it is preferred as the set's canonical file.
35
+ *
36
+ * `rank` is a preference, not a truth — every path in a set holds the same
37
+ * bytes by the time anything consults it, so this only decides which row keeps
38
+ * the body and which become aliases of it, **and only when the set is new**: a
39
+ * set with a guide already stored keeps the body where that guide has it,
40
+ * whichever path that is. Lower wins, and the vendor-neutral standard wins: `AGENTS.md` over `.cursorrules`, and
41
+ * `.agents/skills/` over `.claude/skills/`. That is the same direction
42
+ * `cross-harness-global-guidance` takes for delivery, so a repo does not end up
43
+ * with its canonical body under one vendor's directory and its delivery under
44
+ * another's.
45
+ */
46
+ export type AliasPathIdentity = {
47
+ /** Stable key shared by every path in the set. */
48
+ group: string;
49
+ /** Preference as the canonical body; lower is preferred. */
50
+ rank: number;
51
+ };
52
+ /**
53
+ * The comparison key for a path: separators folded, repeats collapsed,
54
+ * lowercased — the way `detectFormat` normalizes
55
+ * (`packages/projections/src/detect-format.ts:3-5`). `AGENTS.md` and `agents.md`
56
+ * are two strings and one file on macOS and Windows, and an exact-match rule
57
+ * would put the same file in two alias sets.
58
+ *
59
+ * **Exported because a stored path has to be compared the same way.** A guide
60
+ * is stored at the spelling its file had, so `.claude/skills/Review/SKILL.md`
61
+ * and `.agents/skills/review/SKILL.md` are one set under
62
+ * {@link aliasPathIdentity} and two strings to anything that compares the
63
+ * paths themselves. The import route looks a set's other half up on the server
64
+ * and must ask it with this function, or it finds nothing and forks a second
65
+ * guide; this is the one place that decides when two spellings are one path.
66
+ */
67
+ export declare function aliasPathKey(path: string): string;
68
+ /**
69
+ * The alias set a discovery-root-relative path belongs to, or `null` when the
70
+ * path has no alias — which is most paths, and is not an error.
71
+ *
72
+ * Takes the path alone because a set never spans roots: the caller compares
73
+ * `root` itself (Decision 5 keys on *same root, different path*, which is what
74
+ * leaves a project skill and its `~/.claude/skills` twin as two guides). Doing
75
+ * it here instead would need the root passed to every call and would still not
76
+ * be able to enforce it, since one path's identity says nothing about another's.
77
+ */
78
+ export declare function aliasPathIdentity(path: string): AliasPathIdentity | null;
79
+ /**
80
+ * The **other** paths in one path's alias set — the file's twins, whether or
81
+ * not they exist on disk or on the server.
82
+ *
83
+ * {@link aliasPathIdentity} answers "which set is this path in"; this answers
84
+ * "what else is in it". The import route needs the second question because a
85
+ * set's other half is routinely absent from the request that carries this half:
86
+ * a file already managed as a guide is excluded from the payload, so the only
87
+ * way to find it is to name the path it would sit at and look it up. Returns
88
+ * `[]` for a path with no alias, which is most paths and is not an error.
89
+ *
90
+ * Case is carried over from the caller's path rather than normalized away:
91
+ * `aliasPathIdentity` lowercases to compare, but these strings are used to
92
+ * *look rows up*, and a stored path is stored as it was written. So the skill
93
+ * name and the `SKILL.md` segment keep the spelling they arrived with, and only
94
+ * the directory prefix comes from the list — which is the half that is fixed.
95
+ * Comparing what comes back is
96
+ * the caller's job, and it does so through {@link aliasPathKey}: the stored twin
97
+ * may be spelled some other way than the string built here.
98
+ */
99
+ export declare function aliasPathSiblings(path: string): string[];
100
+ //# sourceMappingURL=aliasPaths.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"aliasPaths.d.ts","sourceRoot":"","sources":["../src/aliasPaths.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAIH,4EAA4E;AAC5E,eAAO,MAAM,6BAA6B,sBAAsB,CAAA;AAoBhE,iFAAiF;AACjF,eAAO,MAAM,wBAAwB,WAAW,CAAA;AAShD;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAC9B,kDAAkD;IAClD,KAAK,EAAE,MAAM,CAAA;IACb,4DAA4D;IAC5D,IAAI,EAAE,MAAM,CAAA;CACb,CAAA;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEjD;AAWD;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,iBAAiB,GAAG,IAAI,CAsBxE;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAqBxD"}