@mossbear/protocol 0.1.0-alpha.39 → 0.1.0-alpha.41

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,63 @@
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 Claude Code alongside anything else holds `CLAUDE.md` and
7
+ * `AGENTS.md` with the same rules in both, and today each imports as its own
8
+ * 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 `CLAUDE.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 alias set a discovery-root-relative path belongs to, or `null` when the
54
+ * path has no alias — which is most paths, and is not an error.
55
+ *
56
+ * Takes the path alone because a set never spans roots: the caller compares
57
+ * `root` itself (Decision 5 keys on *same root, different path*, which is what
58
+ * leaves a project skill and its `~/.claude/skills` twin as two guides). Doing
59
+ * it here instead would need the root passed to every call and would still not
60
+ * be able to enforce it, since one path's identity says nothing about another's.
61
+ */
62
+ export declare function aliasPathIdentity(path: string): AliasPathIdentity | null;
63
+ //# 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;AAEhE,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;AAaD;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,iBAAiB,GAAG,IAAI,CAsBxE"}
@@ -0,0 +1,80 @@
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 Claude Code alongside anything else holds `CLAUDE.md` and
7
+ * `AGENTS.md` with the same rules in both, and today each imports as its own
8
+ * 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
+ import { AGENT_GUIDANCE_FILES } from './agentGuidancePaths.js';
29
+ /** Group key for the root instruction files — `AGENTS.md` and its twins. */
30
+ export const ROOT_INSTRUCTIONS_ALIAS_GROUP = 'root-instructions';
31
+ /** Group-key prefix for one skill's `SKILL.md` under either skills directory. */
32
+ export const SKILL_ALIAS_GROUP_PREFIX = 'skill:';
33
+ /**
34
+ * The skills directories that hold the same skill under two names
35
+ * (`packages/projections/src/detect-format.ts:7-14` classifies both as
36
+ * `skill-md`). Order is the preference order below.
37
+ */
38
+ const SKILL_DIRS = ['.agents/skills/', '.claude/skills/'];
39
+ /**
40
+ * Normalized for comparison the same way `detectFormat` normalizes
41
+ * (`packages/projections/src/detect-format.ts:3-5`): backslashes folded,
42
+ * repeated separators collapsed, lowercased. `AGENTS.md` and `agents.md` are
43
+ * two strings and one file on macOS and Windows, and an exact-match rule here
44
+ * would put the same file in two alias sets.
45
+ */
46
+ function normalize(path) {
47
+ return path.replaceAll('\\', '/').replace(/\/+/g, '/').toLowerCase();
48
+ }
49
+ /**
50
+ * The alias set a discovery-root-relative path belongs to, or `null` when the
51
+ * path has no alias — which is most paths, and is not an error.
52
+ *
53
+ * Takes the path alone because a set never spans roots: the caller compares
54
+ * `root` itself (Decision 5 keys on *same root, different path*, which is what
55
+ * leaves a project skill and its `~/.claude/skills` twin as two guides). Doing
56
+ * it here instead would need the root passed to every call and would still not
57
+ * be able to enforce it, since one path's identity says nothing about another's.
58
+ */
59
+ export function aliasPathIdentity(path) {
60
+ const normalized = normalize(path);
61
+ const rootFileRank = AGENT_GUIDANCE_FILES.findIndex((candidate) => candidate.toLowerCase() === normalized);
62
+ if (rootFileRank !== -1) {
63
+ return { group: ROOT_INSTRUCTIONS_ALIAS_GROUP, rank: rootFileRank };
64
+ }
65
+ for (const [rank, dir] of SKILL_DIRS.entries()) {
66
+ if (!normalized.startsWith(dir))
67
+ continue;
68
+ if (!normalized.endsWith('/skill.md'))
69
+ return null;
70
+ const name = normalized.slice(dir.length, normalized.length - '/skill.md'.length);
71
+ // A `SKILL.md` directly under `skills/` has no skill name and is not a
72
+ // skill discovery would import as one; a nested `a/b/SKILL.md` is one skill
73
+ // named `a/b` in both directories alike, so the whole remainder is the key.
74
+ if (name.length === 0)
75
+ return null;
76
+ return { group: `${SKILL_ALIAS_GROUP_PREFIX}${name}`, rank };
77
+ }
78
+ return null;
79
+ }
80
+ //# sourceMappingURL=aliasPaths.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"aliasPaths.js","sourceRoot":"","sources":["../src/aliasPaths.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,EAAE,oBAAoB,EAAE,MAAM,yBAAyB,CAAA;AAE9D,4EAA4E;AAC5E,MAAM,CAAC,MAAM,6BAA6B,GAAG,mBAAmB,CAAA;AAEhE,iFAAiF;AACjF,MAAM,CAAC,MAAM,wBAAwB,GAAG,QAAQ,CAAA;AAEhD;;;;GAIG;AACH,MAAM,UAAU,GAA0B,CAAC,iBAAiB,EAAE,iBAAiB,CAAC,CAAA;AAuBhF;;;;;;GAMG;AACH,SAAS,SAAS,CAAC,IAAY;IAC7B,OAAO,IAAI,CAAC,UAAU,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,WAAW,EAAE,CAAA;AACtE,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,iBAAiB,CAAC,IAAY;IAC5C,MAAM,UAAU,GAAG,SAAS,CAAC,IAAI,CAAC,CAAA;IAElC,MAAM,YAAY,GAAG,oBAAoB,CAAC,SAAS,CACjD,CAAC,SAAS,EAAE,EAAE,CAAC,SAAS,CAAC,WAAW,EAAE,KAAK,UAAU,CACtD,CAAA;IACD,IAAI,YAAY,KAAK,CAAC,CAAC,EAAE,CAAC;QACxB,OAAO,EAAE,KAAK,EAAE,6BAA6B,EAAE,IAAI,EAAE,YAAY,EAAE,CAAA;IACrE,CAAC;IAED,KAAK,MAAM,CAAC,IAAI,EAAE,GAAG,CAAC,IAAI,UAAU,CAAC,OAAO,EAAE,EAAE,CAAC;QAC/C,IAAI,CAAC,UAAU,CAAC,UAAU,CAAC,GAAG,CAAC;YAAE,SAAQ;QACzC,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,WAAW,CAAC;YAAE,OAAO,IAAI,CAAA;QAClD,MAAM,IAAI,GAAG,UAAU,CAAC,KAAK,CAAC,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,MAAM,GAAG,WAAW,CAAC,MAAM,CAAC,CAAA;QACjF,uEAAuE;QACvE,4EAA4E;QAC5E,4EAA4E;QAC5E,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,IAAI,CAAA;QAClC,OAAO,EAAE,KAAK,EAAE,GAAG,wBAAwB,GAAG,IAAI,EAAE,EAAE,IAAI,EAAE,CAAA;IAC9D,CAAC;IAED,OAAO,IAAI,CAAA;AACb,CAAC"}
@@ -0,0 +1,2 @@
1
+ export {};
2
+ //# sourceMappingURL=aliasPaths.test.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"aliasPaths.test.d.ts","sourceRoot":"","sources":["../src/aliasPaths.test.ts"],"names":[],"mappings":""}
@@ -0,0 +1,41 @@
1
+ import { describe, expect, it } from 'vitest';
2
+ import { ROOT_INSTRUCTIONS_ALIAS_GROUP, aliasPathIdentity } from './aliasPaths.js';
3
+ describe('aliasPathIdentity', () => {
4
+ it('puts the three root instruction files in one set, AGENTS.md preferred', () => {
5
+ const agents = aliasPathIdentity('AGENTS.md');
6
+ const claude = aliasPathIdentity('CLAUDE.md');
7
+ const cursor = aliasPathIdentity('.cursorrules');
8
+ expect(agents?.group).toBe(ROOT_INSTRUCTIONS_ALIAS_GROUP);
9
+ expect(claude?.group).toBe(ROOT_INSTRUCTIONS_ALIAS_GROUP);
10
+ expect(cursor?.group).toBe(ROOT_INSTRUCTIONS_ALIAS_GROUP);
11
+ expect(agents?.rank).toBeLessThan(claude?.rank ?? Infinity);
12
+ expect(claude?.rank).toBeLessThan(cursor?.rank ?? Infinity);
13
+ });
14
+ it('reads a differently-cased file name as the same file', () => {
15
+ expect(aliasPathIdentity('agents.md')?.group).toBe(ROOT_INSTRUCTIONS_ALIAS_GROUP);
16
+ });
17
+ it('pairs one skill across the two skills directories, .agents preferred', () => {
18
+ const agents = aliasPathIdentity('.agents/skills/review/SKILL.md');
19
+ const claude = aliasPathIdentity('.claude/skills/review/SKILL.md');
20
+ expect(agents?.group).toBe('skill:review');
21
+ expect(claude?.group).toBe('skill:review');
22
+ expect(agents?.rank).toBeLessThan(claude?.rank ?? Infinity);
23
+ });
24
+ it('gives two differently-named skills different sets', () => {
25
+ expect(aliasPathIdentity('.agents/skills/review/SKILL.md')?.group).not.toBe(aliasPathIdentity('.claude/skills/deploy/SKILL.md')?.group);
26
+ });
27
+ it('reads two spellings of one path as one file, not a set of two', () => {
28
+ // Same group *and* same file: a caller grouping by group key must still see
29
+ // one path here, or the collapse would write an alias row for the path that
30
+ // already holds the body.
31
+ expect(aliasPathIdentity('AGENTS.md')).toEqual(aliasPathIdentity('agents.md'));
32
+ expect(aliasPathIdentity('.claude//skills/review/SKILL.md')).toEqual(aliasPathIdentity('.claude/skills/review/SKILL.md'));
33
+ });
34
+ it('leaves a skill member file, a nested rules file and an ordinary doc unaliased', () => {
35
+ expect(aliasPathIdentity('.claude/skills/review/scripts/run.sh')).toBeNull();
36
+ expect(aliasPathIdentity('.claude/rules/style.md')).toBeNull();
37
+ expect(aliasPathIdentity('docs/architecture.md')).toBeNull();
38
+ expect(aliasPathIdentity('.agents/skills/SKILL.md')).toBeNull();
39
+ });
40
+ });
41
+ //# sourceMappingURL=aliasPaths.test.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"aliasPaths.test.js","sourceRoot":"","sources":["../src/aliasPaths.test.ts"],"names":[],"mappings":"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"}
package/dist/index.d.ts CHANGED
@@ -5,6 +5,7 @@
5
5
  * This package must remain importable outside the CLI package.
6
6
  */
7
7
  export * from './agentGuidancePaths.js';
8
+ export * from './aliasPaths.js';
8
9
  export * from './bundleSlug.js';
9
10
  export * from './contextKinds.js';
10
11
  export * from './pairing.js';
@@ -1 +1 @@
1
- {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,cAAc,yBAAyB,CAAA;AACvC,cAAc,iBAAiB,CAAA;AAC/B,cAAc,mBAAmB,CAAA;AACjC,cAAc,cAAc,CAAA;AAC5B,cAAc,cAAc,CAAA;AAC5B,cAAc,YAAY,CAAA;AAC1B,cAAc,cAAc,CAAA"}
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,cAAc,yBAAyB,CAAA;AACvC,cAAc,iBAAiB,CAAA;AAC/B,cAAc,iBAAiB,CAAA;AAC/B,cAAc,mBAAmB,CAAA;AACjC,cAAc,cAAc,CAAA;AAC5B,cAAc,cAAc,CAAA;AAC5B,cAAc,YAAY,CAAA;AAC1B,cAAc,cAAc,CAAA"}
package/dist/index.js CHANGED
@@ -5,6 +5,7 @@
5
5
  * This package must remain importable outside the CLI package.
6
6
  */
7
7
  export * from './agentGuidancePaths.js';
8
+ export * from './aliasPaths.js';
8
9
  export * from './bundleSlug.js';
9
10
  export * from './contextKinds.js';
10
11
  export * from './pairing.js';
package/dist/index.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,cAAc,yBAAyB,CAAA;AACvC,cAAc,iBAAiB,CAAA;AAC/B,cAAc,mBAAmB,CAAA;AACjC,cAAc,cAAc,CAAA;AAC5B,cAAc,cAAc,CAAA;AAC5B,cAAc,YAAY,CAAA;AAC1B,cAAc,cAAc,CAAA"}
1
+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,cAAc,yBAAyB,CAAA;AACvC,cAAc,iBAAiB,CAAA;AAC/B,cAAc,iBAAiB,CAAA;AAC/B,cAAc,mBAAmB,CAAA;AACjC,cAAc,cAAc,CAAA;AAC5B,cAAc,cAAc,CAAA;AAC5B,cAAc,YAAY,CAAA;AAC1B,cAAc,cAAc,CAAA"}