@bevel-software/platform-core-frontend 0.7.3 → 0.7.5

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.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@bevel-software/platform-core-frontend",
3
- "version": "0.7.3",
3
+ "version": "0.7.5",
4
4
  "description": "Open-source core UI of the Bevel platform (raw TS/TSX source): workspace explorer/viewer, branches & change requests, Library, secrets, tools, access control.",
5
5
  "type": "module",
6
6
  "main": "./src/index.ts",
@@ -41,7 +41,7 @@
41
41
  "tailwind-merge": "^3.5.0",
42
42
  "xlsx": "^0.18.5",
43
43
  "yaml": "^2.9.0",
44
- "@bevel-software/platform-shared": "0.7.3"
44
+ "@bevel-software/platform-shared": "0.7.5"
45
45
  },
46
46
  "devDependencies": {
47
47
  "@testing-library/jest-dom": "^6.9.1",
@@ -236,8 +236,12 @@ function renderPage(
236
236
  mine: number[] = [],
237
237
  bus: EventBusContextValue = makeFakeBus(),
238
238
  routerState?: Record<string, unknown>,
239
+ /** Catalog-state overrides — e.g. `{ loading: true }` for the early case. */
240
+ library?: Partial<LibraryContextValue>,
241
+ /** Props the canonical /workspace mount passes; the legacy route passes none. */
242
+ pageProps?: { provisional?: boolean },
239
243
  ) {
240
- libraryMock.value = libraryValue(owned, crs, mine);
244
+ libraryMock.value = { ...libraryValue(owned, crs, mine), ...library };
241
245
  return render(
242
246
  <MemoryRouter
243
247
  initialEntries={[
@@ -253,7 +257,10 @@ function renderPage(
253
257
  leave the one assertion that matters unmakeable. */}
254
258
  <LibraryToastProvider>
255
259
  <Routes>
256
- <Route path="/skills-and-tools/skills/:name" element={<SkillPage />} />
260
+ <Route
261
+ path="/skills-and-tools/skills/:name"
262
+ element={<SkillPage {...(pageProps ?? {})} />}
263
+ />
257
264
  </Routes>
258
265
  </LibraryToastProvider>
259
266
  </EventBusContext.Provider>
@@ -608,6 +615,62 @@ describe('SkillPage', () => {
608
615
  await screen.findByText(/doesn't exist, or you don't have access to it/),
609
616
  ).toBeInTheDocument();
610
617
  });
618
+
619
+ /**
620
+ * The name can be PROVISIONAL. A URL the catalog hasn't answered for is
621
+ * resolved by reading the folder name, which is the skill's id only when no
622
+ * frontmatter declares one — so a failed fetch under a loading catalog is
623
+ * not evidence the skill is missing, just that we asked with the wrong name.
624
+ * GroupPage already refuses to decide this early; this is the same call.
625
+ */
626
+ describe('a PROVISIONAL name — one the route guessed from the URL', () => {
627
+ // The route reads the folder name when the catalog can't resolve a URL,
628
+ // and that is the id only when no frontmatter declares one. So a failed
629
+ // lookup may just mean we asked with the wrong name.
630
+ const early = { loading: true, items: [] };
631
+ const failed = { loading: false, error: "Couldn't load the catalog.", items: [] };
632
+
633
+ it.each([
634
+ ['still loading', early],
635
+ // `loading: false` also describes a catalog that FAILED — "we couldn't
636
+ // ask" is not "there is no such skill", so absence stays unconcluded and
637
+ // a valid declared-id skill never turns into a permanent error page.
638
+ ['failed to load', failed],
639
+ ])('holds the "doesn\'t exist" verdict while the catalog %s', async (_label, lib) => {
640
+ apiMock.getSkill.mockRejectedValueOnce(new Error('nope'));
641
+ renderPage(false, [], [], makeFakeBus(), undefined, lib, { provisional: true });
642
+
643
+ await waitFor(() => expect(apiMock.getSkill).toHaveBeenCalled());
644
+ expect(
645
+ screen.queryByText(/doesn't exist, or you don't have access to it/),
646
+ ).not.toBeInTheDocument();
647
+ // …and says so as a LOADING state, not a blank page: an empty render
648
+ // would satisfy the assertion above while telling the reader nothing.
649
+ expect(screen.getByRole('tabpanel')).toHaveAttribute('aria-busy', 'true');
650
+ });
651
+
652
+ it('does conclude absence once the catalog has answered', async () => {
653
+ apiMock.getSkill.mockRejectedValueOnce(new Error('nope'));
654
+ renderPage(false, [], [], makeFakeBus(), undefined, { loading: false, error: null }, {
655
+ provisional: true,
656
+ });
657
+
658
+ expect(
659
+ await screen.findByText(/doesn't exist, or you don't have access to it/),
660
+ ).toBeInTheDocument();
661
+ });
662
+
663
+ it('never holds it for a name the catalog confirmed', async () => {
664
+ // A confirmed name's detail error is real — report it immediately, even
665
+ // mid-refresh. Suppressing it would hide a genuine access failure.
666
+ apiMock.getSkill.mockRejectedValueOnce(new Error('nope'));
667
+ renderPage(false, [], [], makeFakeBus(), undefined, early);
668
+
669
+ expect(
670
+ await screen.findByText(/doesn't exist, or you don't have access to it/),
671
+ ).toBeInTheDocument();
672
+ });
673
+ });
611
674
  });
612
675
 
613
676
  describe('SkillPage: proposing a change', () => {
@@ -168,6 +168,224 @@ describe('WorkspaceItemRoute', () => {
168
168
  );
169
169
  });
170
170
 
171
+ /**
172
+ * A group may carry CATEGORY folders: `skills.service` walks until it finds
173
+ * a `SKILL.md` and treats that folder as the skill, so `Groups/Engineering/
174
+ * coding/create-ticket/SKILL.md` is a skill named `create-ticket`.
175
+ *
176
+ * Reading the first segment below the group asked for the category —
177
+ * "coding", which no skill answers to — so every nested skill listed
178
+ * perfectly and then reported "doesn't exist, or you don't have access to
179
+ * it" on click. Every fixture here used to be flat, which is exactly why
180
+ * that shipped.
181
+ */
182
+ describe('a skill nested under a category folder', () => {
183
+ const NESTED: LibraryData = {
184
+ ...CATALOG,
185
+ skills: [
186
+ { name: 'create-ticket', description: '', path: 'Groups/Engineering/coding/create-ticket' },
187
+ {
188
+ name: 'architecture-review',
189
+ description: '',
190
+ path: 'Groups/Engineering/review/architecture-review',
191
+ },
192
+ ],
193
+ };
194
+
195
+ beforeEach(() => {
196
+ dataMock.useLibraryData.mockReturnValue(NESTED);
197
+ });
198
+
199
+ it('resolves its SKILL.md to the folder holding it, not the category', async () => {
200
+ renderAt(itemUrl('Groups/Engineering/coding/create-ticket/SKILL.md'));
201
+ expect(await screen.findByLabelText('skill-page')).toHaveTextContent(
202
+ 'create-ticket::SKILL.md',
203
+ );
204
+ });
205
+
206
+ it('resolves a bundled file below a category folder', async () => {
207
+ renderAt(itemUrl('Groups/Engineering/review/architecture-review/check-vocab.mjs'));
208
+ expect(await screen.findByLabelText('skill-page')).toHaveTextContent(
209
+ 'architecture-review::check-vocab.mjs',
210
+ );
211
+ });
212
+
213
+ it('resolves a bare nested skill folder to SKILL.md', async () => {
214
+ renderAt(itemUrl('Groups/Engineering/coding/create-ticket'));
215
+ expect(await screen.findByLabelText('skill-page')).toHaveTextContent(
216
+ 'create-ticket::SKILL.md',
217
+ );
218
+ });
219
+
220
+ it('resolves a nested SKILL.md with no catalog at all', async () => {
221
+ // The SKILL.md rule reads the URL alone, so the just-created case above
222
+ // keeps working at depth: the folder holding SKILL.md IS the skill.
223
+ dataMock.useLibraryData.mockReturnValue({ ...CATALOG, loading: true, skills: [], tools: [] });
224
+ renderAt(itemUrl('Groups/Engineering/coding/brand-new-skill/SKILL.md'));
225
+ expect(await screen.findByLabelText('skill-page')).toHaveTextContent(
226
+ 'brand-new-skill::SKILL.md',
227
+ );
228
+ });
229
+
230
+ it('resolves a `.tool` filed under a category folder, by its catalog slug', async () => {
231
+ // `walkFiles` finds manuals at ANY depth, so this is a real listed tool;
232
+ // matching only the group's top level listed it and 404'd the click. The
233
+ // slug is the manual's declared `id`, which need not match the filename —
234
+ // so a fixture whose slug equals its filename would prove nothing.
235
+ dataMock.useLibraryData.mockReturnValue({
236
+ ...NESTED,
237
+ tools: [
238
+ {
239
+ slug: 'internal_deploy',
240
+ name: 'internal_deploy',
241
+ path: 'Groups/Engineering/coding/deploy.tool',
242
+ type: 'mcp' as const,
243
+ setup: null,
244
+ canWrite: false,
245
+ variables: [],
246
+ },
247
+ ],
248
+ });
249
+ renderAt(itemUrl('Groups/Engineering/coding/deploy.tool'));
250
+ expect(await screen.findByLabelText('tool-page')).toHaveTextContent('internal_deploy');
251
+ });
252
+
253
+ it("sends a category folder's own access.md to the group page", async () => {
254
+ // The same answer a stray file at the group's top level gets. Before, it
255
+ // fell through to a SkillPage named after the category.
256
+ renderAt(itemUrl('Groups/Engineering/coding/access.md'));
257
+ await waitFor(() =>
258
+ expect(screen.getByLabelText('pathname')).toHaveTextContent(
259
+ '/skills-and-tools/groups/Engineering',
260
+ ),
261
+ );
262
+ });
263
+
264
+ it('waits for the catalog rather than guessing a category is the skill', async () => {
265
+ // A bare nested folder is ambiguous without the catalog. Guessing sent
266
+ // SkillPage after a skill named "coding" and flashed a not-found error;
267
+ // the catalog is what settles it, so hold the slot until it lands.
268
+ dataMock.useLibraryData.mockReturnValue({ ...NESTED, loading: true, skills: [], tools: [] });
269
+ renderAt(itemUrl('Groups/Engineering/coding/create-ticket'));
270
+ expect(await screen.findByRole('button', { name: /^All groups/ })).toBeInTheDocument();
271
+ expect(screen.queryByLabelText('skill-page')).toBeNull();
272
+ });
273
+
274
+ it('sends a bare CATEGORY folder to its group, not to a skill page', async () => {
275
+ // A category is not a skill, and `coding` names none. What tells it apart
276
+ // from a just-created skill the catalog hasn't caught up with is that the
277
+ // catalog knows skills UNDER it.
278
+ renderAt(itemUrl('Groups/Engineering/coding'));
279
+ await waitFor(() =>
280
+ expect(screen.getByLabelText('pathname')).toHaveTextContent(
281
+ '/skills-and-tools/groups/Engineering',
282
+ ),
283
+ );
284
+ expect(screen.queryByLabelText('skill-page')).toBeNull();
285
+ });
286
+
287
+ it('still opens a folder the catalog has no skills under — a stale new skill', async () => {
288
+ renderAt(itemUrl('Groups/Engineering/coding/brand-new-skill'));
289
+ expect(await screen.findByLabelText('skill-page')).toHaveTextContent(
290
+ 'brand-new-skill::SKILL.md',
291
+ );
292
+ });
293
+
294
+ it('opens a bundled file of a skill the catalog has not caught up with', async () => {
295
+ // STALE, not failed: the catalog loaded fine, it just predates the skill.
296
+ // Concluding "nothing owns this file, so it is not a page" bounced the
297
+ // reader to the group — the very symptom this change exists to remove,
298
+ // reached through a different unsettled state. Absence proves nothing;
299
+ // only positive evidence (a known category above it) redirects.
300
+ renderAt(itemUrl('Groups/Engineering/coding/brand-new-skill/notes.md'));
301
+ expect(await screen.findByLabelText('skill-page')).toHaveTextContent(
302
+ 'brand-new-skill::notes.md',
303
+ );
304
+ });
305
+
306
+ it('still routes a known category by its CACHED skills after a failed refresh', async () => {
307
+ // `useLibraryData` keeps the previous entries when a refresh fails, and
308
+ // what the catalog KNOWS stays true — a category is still a category.
309
+ dataMock.useLibraryData.mockReturnValue({
310
+ ...NESTED,
311
+ error: "Couldn't refresh the catalog.",
312
+ });
313
+ renderAt(itemUrl('Groups/Engineering/coding'));
314
+ await waitFor(() =>
315
+ expect(screen.getByLabelText('pathname')).toHaveTextContent(
316
+ '/skills-and-tools/groups/Engineering',
317
+ ),
318
+ );
319
+ });
320
+
321
+ it('does not let a prefix-sharing sibling claim a bundled file', async () => {
322
+ // Ownership compares whole segments: `create-ticket-v2` shares a string
323
+ // prefix with `create-ticket` and must not swallow its files.
324
+ dataMock.useLibraryData.mockReturnValue({
325
+ ...NESTED,
326
+ skills: [
327
+ ...NESTED.skills,
328
+ {
329
+ name: 'create-ticket-v2',
330
+ description: '',
331
+ path: 'Groups/Engineering/coding/create-ticket-v2',
332
+ },
333
+ ],
334
+ });
335
+ renderAt(itemUrl('Groups/Engineering/coding/create-ticket-v2/notes.md'));
336
+ expect(await screen.findByLabelText('skill-page')).toHaveTextContent(
337
+ 'create-ticket-v2::notes.md',
338
+ );
339
+ });
340
+ });
341
+
342
+ /**
343
+ * A skill's id is its frontmatter `id`/`name`, and only FALLS BACK to the
344
+ * folder name — so the URL cannot be trusted to spell it. The catalog can.
345
+ */
346
+ it('resolves a skill whose declared id differs from its folder name', async () => {
347
+ dataMock.useLibraryData.mockReturnValue({
348
+ ...CATALOG,
349
+ skills: [{ name: 'deck-builder', description: '', path: 'Groups/Sales/create-sales-deck' }],
350
+ });
351
+ renderAt(itemUrl('Groups/Sales/create-sales-deck/SKILL.md'));
352
+ expect(await screen.findByLabelText('skill-page')).toHaveTextContent('deck-builder::SKILL.md');
353
+ });
354
+
355
+ it("keeps a SKILL.md bundled INSIDE a skill as that skill's file", async () => {
356
+ // `skills.service` stops at the first `SKILL.md` and treats that folder as
357
+ // the skill, so a nested one is a bundled asset — never a skill called
358
+ // `examples`.
359
+ renderAt(itemUrl('Groups/Sales/create-sales-deck/examples/SKILL.md'));
360
+ expect(await screen.findByLabelText('skill-page')).toHaveTextContent(
361
+ 'create-sales-deck::examples/SKILL.md',
362
+ );
363
+ });
364
+
365
+ /**
366
+ * A failed catalog is "we couldn't ask", not "no such item" — the same
367
+ * distinction GroupPage draws. Reading it as proof that nothing owns the
368
+ * file would bounce every bundled-file deep link to the group page during a
369
+ * transient outage, losing the URL; the skill detail comes from a different
370
+ * endpoint and can still answer.
371
+ */
372
+ it('keeps a bundled-file deep link on the skill page when the catalog failed', async () => {
373
+ dataMock.useLibraryData.mockReturnValue({
374
+ ...CATALOG,
375
+ loading: false,
376
+ error: "Couldn't load the catalog.",
377
+ skills: [],
378
+ tools: [],
379
+ });
380
+ // The file's own folder is the best available reading without a catalog
381
+ // (an asset nested deeper simply cannot be attributed) — the point is that
382
+ // the reader stays on a skill page instead of being bounced to the group.
383
+ renderAt(itemUrl('Groups/Sales/create-sales-deck/notes.md'));
384
+ expect(await screen.findByLabelText('skill-page')).toHaveTextContent(
385
+ 'create-sales-deck::notes.md',
386
+ );
387
+ });
388
+
171
389
  it('a non-default branch never renders an item page', async () => {
172
390
  renderAt(itemUrl('Groups/Sales/create-sales-deck/SKILL.md', 'razvan/some-draft'));
173
391
  await waitFor(() =>
@@ -56,6 +56,7 @@ import { isBinaryFile } from '../../../workspace/components/renderers';
56
56
  export function SkillPage({
57
57
  name: nameProp,
58
58
  activeFile,
59
+ provisional = false,
59
60
  }: {
60
61
  /**
61
62
  * Both provided when the page is mounted at its CANONICAL address — the
@@ -66,6 +67,14 @@ export function SkillPage({
66
67
  */
67
68
  name?: string;
68
69
  activeFile?: string;
70
+ /**
71
+ * Whether `name` is a GUESS the catalog never confirmed — read off the URL's
72
+ * folder name, which is the skill's id only when no frontmatter declares
73
+ * one. A failed lookup for a provisional name is not evidence of absence
74
+ * until the catalog has actually answered; it may simply be the wrong name.
75
+ * Default `false`: a caller that says nothing is naming a skill it knows.
76
+ */
77
+ provisional?: boolean;
69
78
  } = {}) {
70
79
  const { name: rawName = '' } = useParams<{ name: string }>();
71
80
  const name = nameProp ?? safeDecode(rawName);
@@ -377,7 +386,18 @@ export function SkillPage({
377
386
  </Button>
378
387
  );
379
388
 
380
- if (!detail.loading && (detail.error || !skill)) {
389
+ // "Doesn't exist" is a VERDICT, and a provisional name has not earned one:
390
+ // the route guessed it from the URL's folder name, so a failed lookup may
391
+ // just mean we asked with the wrong name. Only the catalog can correct that,
392
+ // and only a SUCCESSFUL catalog response counts — `loading: false` also
393
+ // describes a catalog that failed, which is "we couldn't ask", not "there is
394
+ // no such skill". The same distinction GroupPage draws a few files over.
395
+ //
396
+ // A confirmed name (the catalog resolved this URL to it) is unaffected: its
397
+ // detail error is real and gets reported immediately.
398
+ const catalogAnswered = !data.loading && !data.error;
399
+ const mayConcludeAbsence = !provisional || catalogAnswered;
400
+ if (!detail.loading && mayConcludeAbsence && (detail.error || !skill)) {
381
401
  return (
382
402
  <Article>
383
403
  {backLink}
@@ -42,26 +42,137 @@ export function WorkspaceItemRoute() {
42
42
  return <Navigate to={LIBRARY_ROOT} replace />;
43
43
  }
44
44
 
45
- const [, , group, entry, ...rest] = segments;
46
- if (!group || !entry) {
45
+ const [, , group, ...tail] = segments;
46
+ const last = tail[tail.length - 1];
47
+ if (!group || !last) {
47
48
  return <Navigate to={LIBRARY_ROOT} replace />;
48
49
  }
50
+ const repoRel = `${GROUPS_DIR}/${group}/${tail.join('/')}`;
49
51
 
50
- if (rest.length === 0 && entry.toLowerCase().endsWith('.tool')) {
51
- const repoRel = `${GROUPS_DIR}/${group}/${entry}`;
52
+ /**
53
+ * `key={name}` is load-bearing. A provisional name gets CORRECTED once the
54
+ * catalog lands (folder name → declared id), and without a remount the page
55
+ * would render once with the new name still holding the old name's failed
56
+ * detail state — the "doesn't exist" flash, one frame before the corrected
57
+ * request even starts. Remounting discards it.
58
+ */
59
+ const skillPage = (name: string, activeFile: string, provisional: boolean) => (
60
+ <SkillPage key={name} name={name} activeFile={activeFile} provisional={provisional} />
61
+ );
62
+
63
+ // A `.tool` is a tool page wherever it sits. The backend finds manuals at
64
+ // ANY depth below `Groups/` (`walkFiles` over the whole tree), so a manual
65
+ // filed inside a category folder is a real, listed tool — matching only at
66
+ // the group's top level would list it and then 404 the click.
67
+ if (last.toLowerCase().endsWith('.tool')) {
52
68
  const catalogSlug = data.items.find(
53
69
  (i) => i.kind === 'integration' && i.path === repoRel,
54
70
  )?.id;
55
- return <ToolPage slug={catalogSlug ?? entry.slice(0, -'.tool'.length)} />;
71
+ return <ToolPage slug={catalogSlug ?? last.slice(0, -'.tool'.length)} />;
72
+ }
73
+
74
+ // THE CATALOG IS THE AUTHORITY on which folder is a skill and what its id
75
+ // is. Groups may nest (`Groups/Engineering/coding/create-ticket/SKILL.md`),
76
+ // and a skill's id is its frontmatter `id`/`name` — only FALLING BACK to the
77
+ // folder name — so neither the depth nor the id can be read off the URL with
78
+ // certainty. Take the DEEPEST skill whose folder contains this path: a
79
+ // category folder is never itself a skill, so the deepest match is the owner,
80
+ // and a `SKILL.md` bundled inside a skill (`<skill>/examples/SKILL.md`)
81
+ // stays that skill's file instead of inventing a skill called `examples`.
82
+ const owner = deepestSkillOwning(data.items, repoRel);
83
+ if (owner) {
84
+ const file = repoRel.slice(owner.path.length + 1);
85
+ return skillPage(owner.id, file || 'SKILL.md', false);
56
86
  }
57
87
 
58
- // A direct FILE in the group folder (`access.md`, a stray upload) is the
59
- // group's business, not a page of its own.
60
- if (rest.length === 0 && /\.[a-z0-9]+$/i.test(entry)) {
88
+ // Not in the catalog. A `SKILL.md` still names its own skill structurally —
89
+ // the folder holding it — and that is deliberately catalog-FREE: a skill
90
+ // created a moment ago opens from its URL alone, before any reload lands.
91
+ // (`Groups/<group>/SKILL.md` makes the group folder itself the skill, which
92
+ // is what the backend's walk would report for it.)
93
+ if (last === 'SKILL.md') {
94
+ return skillPage(tail.length >= 2 ? tail[tail.length - 2]! : group, 'SKILL.md', true);
95
+ }
96
+
97
+ // Everything below is decided on POSITIVE evidence only. What the catalog
98
+ // KNOWS is trustworthy whenever it is there — cached entries survive a
99
+ // failed refresh — but what it does NOT know proves nothing: it may be
100
+ // loading, stale (a skill created seconds ago), or have failed outright.
101
+ // Reading absence as "this is not a page" is what bounced valid deep links
102
+ // to the group, so this no longer draws that inference at all.
103
+
104
+ // A folder with catalog skills UNDER it is a category, not a skill. That is
105
+ // the discriminator between a category folder and a just-created skill whose
106
+ // reload hasn't landed: the former has known descendants, the latter has
107
+ // none. A category has no page of its own; its group does.
108
+ if (!hasExtension(last) && containsCatalogSkill(data.items, repoRel)) {
61
109
  return <Navigate to={pathForGroup(group)} replace />;
62
110
  }
63
111
 
64
- return <SkillPage name={entry} activeFile={rest.join('/') || 'SKILL.md'} />;
112
+ // A FILE is the group's business when it cannot be a skill's file: either it
113
+ // sits directly in the group folder (structurally never inside a skill), or
114
+ // its own folder is a known category. `access.md` at either level, a stray
115
+ // upload. A file under an UNKNOWN folder is left alone — that folder is most
116
+ // likely a skill the catalog hasn't caught up with.
117
+ const parentRel = repoRel.slice(0, repoRel.length - last.length - 1);
118
+ if (hasExtension(last) && (tail.length === 1 || containsCatalogSkill(data.items, parentRel))) {
119
+ return <Navigate to={pathForGroup(group)} replace />;
120
+ }
121
+
122
+ // Nothing positive settled it. While the catalog is still loading, WAIT: the
123
+ // evidence above may be one render away, and guessing flashes a page for a
124
+ // name that is about to change. The layout and its sidebar are already on
125
+ // screen around this.
126
+ if (data.loading) return null;
127
+
128
+ // Read the URL structurally — a file belongs to the folder holding it, a
129
+ // bare folder names itself, the same rule the backend applies when no
130
+ // frontmatter declares an id. Provisional: the catalog never confirmed it,
131
+ // so SkillPage must not turn a failed lookup into "doesn't exist" until the
132
+ // catalog has actually answered.
133
+ return hasExtension(last)
134
+ ? skillPage(tail.length >= 2 ? tail[tail.length - 2]! : group, last, true)
135
+ : skillPage(last, 'SKILL.md', true);
136
+ }
137
+
138
+ /** Whether a path segment names a file rather than a folder. */
139
+ function hasExtension(segment: string): boolean {
140
+ return /\.[a-z0-9]+$/i.test(segment);
141
+ }
142
+
143
+ /**
144
+ * Whether the catalog knows any skill BELOW this path — i.e. whether it is a
145
+ * container. Only meaningful once the catalog has actually loaded.
146
+ */
147
+ function containsCatalogSkill(
148
+ items: readonly { kind: string; path: string }[],
149
+ repoRel: string,
150
+ ): boolean {
151
+ return items.some((i) => i.kind === 'skill' && i.path.startsWith(`${repoRel}/`));
152
+ }
153
+
154
+ /**
155
+ * The catalog skill whose folder contains `repoRel`, deepest first — the skill
156
+ * a bundled file belongs to. Deepest wins because a category folder is never a
157
+ * skill itself, so between `Groups/E/coding` and `Groups/E/coding/create-ticket`
158
+ * only the latter can be a real entry; taking the shallower match would hand
159
+ * the file to whichever skill sat nearest the group root.
160
+ *
161
+ * Compares on whole segments (`path + '/'`), never a bare `startsWith`: a
162
+ * sibling named `create-ticket-v2` shares a prefix with `create-ticket` and
163
+ * must not claim its files.
164
+ */
165
+ function deepestSkillOwning(
166
+ items: readonly { kind: string; id: string; path: string }[],
167
+ repoRel: string,
168
+ ): { id: string; path: string } | null {
169
+ let best: { id: string; path: string } | null = null;
170
+ for (const item of items) {
171
+ if (item.kind !== 'skill') continue;
172
+ if (repoRel !== item.path && !repoRel.startsWith(`${item.path}/`)) continue;
173
+ if (!best || item.path.length > best.path.length) best = { id: item.id, path: item.path };
174
+ }
175
+ return best;
65
176
  }
66
177
 
67
178
  /** A malformed escape is a bad link, not a crash — fall back to the raw segment. */