@atom63/cli 0.1.0-beta.1 → 0.1.0-beta.2

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": "@atom63/cli",
3
- "version": "0.1.0-beta.1",
3
+ "version": "0.1.0-beta.2",
4
4
  "description": "Query the Atom63 design system from the command line or an MCP host: components, contracts, tokens, examples and docs",
5
5
  "license": "MIT",
6
6
  "repository": {
package/src/agents-md.mjs CHANGED
@@ -16,7 +16,8 @@ const cliQueries = [
16
16
  '',
17
17
  '- `atom63 build <idea>`: a kit for what you are building: the closest page templates and blocks, the components they use, the foundation and the rules. For a phone screen it leads with `AppView layout="phone"` and a snippet to start from.',
18
18
  '- `atom63 template <id>` and `atom63 copy <id> <dir>`: read a page or block template, then copy it and the blocks it uses into your project to adapt.',
19
- '- `atom63 search <words>`: find a component, template, docs page, story example or token.',
19
+ '- `atom63 search <words>`: find a component, template, docs page, story example, token or public API name (a SwiftUI type or the export of a package entry point).',
20
+ '- `atom63 api <name>`: a SwiftUI type (`AtomWidgetCard`) or a JavaScript export (`MediaLightbox`, `KeyIdea`) with its import line and docs, and for an MDX block its purpose, an example and its props; an entry point (`@atom63/ui-react/media`, `Atom63UI`) with everything it exports.',
20
21
  '- `atom63 component <slug>`: the import line, contract (axes, defaults, slots, states, web and iOS), related components and examples.',
21
22
  '- `atom63 example <slug> [story]`: a known-good usage sample to start from.',
22
23
  '- `atom63 token <name or words>`: a token with its values per theme and mode, Figma path and Swift name.',
package/src/commands.mjs CHANGED
@@ -8,7 +8,7 @@
8
8
  * input and returns an envelope, or throws an AtomError.
9
9
  */
10
10
  import { agentsBlock } from './agents-md.mjs'
11
- import { component, docsPage, example, rules, search, searchKinds, token } from './core.mjs'
11
+ import { api, component, docsPage, example, rules, search, searchKinds, token } from './core.mjs'
12
12
  import { build, copy, template, templateKinds } from './templates.mjs'
13
13
 
14
14
  export const commands = [
@@ -91,6 +91,20 @@ export const commands = [
91
91
  returns: ['token.detail', 'token.results'],
92
92
  run: (index, { query }) => token(index, query),
93
93
  },
94
+ {
95
+ name: 'api',
96
+ summary:
97
+ 'A public API name or an entry point: a SwiftUI type with its declaration, doc comment and members, or a JavaScript export with its import line and docs page (for an MDX block, its purpose, an example and its props); an entry point (e.g. @atom63/ui-react/media, @atom63/mdx/blocks, Atom63UI) with everything it exports.',
98
+ args: [
99
+ {
100
+ name: 'name',
101
+ description: 'e.g. AtomWidgetCard, MediaLightbox, KeyIdea or @atom63/ui-react/media.',
102
+ },
103
+ ],
104
+ flags: [],
105
+ returns: ['api.detail', 'api.entry'],
106
+ run: (index, { name }) => api(index, name),
107
+ },
94
108
  {
95
109
  name: 'docs',
96
110
  summary: 'A docs page as Markdown.',
@@ -149,6 +163,7 @@ export const errorCodes = [
149
163
  'token.not_found',
150
164
  'docs.not_found',
151
165
  'template.not_found',
166
+ 'api.not_found',
152
167
  ]
153
168
 
154
169
  /** The self-describing manifest an agent reads once to learn the interface. */
package/src/core.mjs CHANGED
@@ -123,7 +123,7 @@ function synonymBoost(query, slug) {
123
123
  let best = 0
124
124
  for (const term of words(query)) {
125
125
  const rank = (synonyms[term] ?? []).indexOf(slug)
126
- if (rank !== -1) best = Math.max(best, 30 - rank * 8)
126
+ if (rank !== -1) best = Math.max(best, 40 - rank * 8)
127
127
  }
128
128
  return best
129
129
  }
@@ -169,11 +169,42 @@ function synonymTokens(query) {
169
169
 
170
170
  /* ── Commands ────────────────────────────────────────────────────────────── */
171
171
 
172
- export const searchKinds = ['component', 'template', 'token', 'doc', 'example']
172
+ export const searchKinds = ['component', 'template', 'token', 'doc', 'example', 'api']
173
+
174
+ const firstSentence = text => /^.*?\.(?=\s|$)/.exec(text)?.[0] ?? text
175
+
176
+ /** The last segment of an entry point: `@atom63/ui-react/media/lightbox` → `lightbox`. */
177
+ const entryTail = module => module.split('/').at(-1)
173
178
 
174
179
  /**
175
- * One ranked list across components, templates, tokens, docs pages and story
176
- * examples.
180
+ * Every public API name an agent can look up: the Swift types of Atom63UI and
181
+ * the values each published JavaScript entry point exports.
182
+ */
183
+ function apiSymbols(index) {
184
+ const covered = new Set(index.components.flatMap(component => component.exports.values))
185
+ return [
186
+ ...index.api.ios.types.map(type => ({
187
+ name: type.name,
188
+ summary: firstSentence(type.summary) || `${type.declaration} (${index.api.ios.module})`,
189
+ // Swift types do not compete with the web component of the same name.
190
+ inSearch: true,
191
+ })),
192
+ ...index.api.web.flatMap(entry =>
193
+ entry.values.map(name => ({
194
+ name,
195
+ summary: `import { ${name} } from '${entry.module}'`,
196
+ // A catalog component's own exports are found through the component.
197
+ inSearch: !covered.has(name),
198
+ }))
199
+ ),
200
+ ]
201
+ }
202
+
203
+ /**
204
+ * One ranked list across components, templates, tokens, docs pages, story
205
+ * examples and public API names (Swift types and entry point exports).
206
+ * An API name joins on a name match only, and below components and docs
207
+ * unless it matches exactly or kind is `api`.
177
208
  * Tokens only join when the query looks like one (`--…`), kind is `token`, a
178
209
  * topic names them, or a query term names them through a synonym ("gradient"),
179
210
  * so a thousand variables cannot bury the components.
@@ -277,6 +308,51 @@ export function search(index, query, { kind, limit = 10 } = {}) {
277
308
  }
278
309
  }
279
310
 
311
+ if (wants('api')) {
312
+ const entries = [
313
+ {
314
+ module: index.api.ios.module,
315
+ names: [index.api.ios.module, 'ios', 'swiftui', 'swift'],
316
+ summary: `the SwiftUI package: ${index.api.ios.types.length} public types`,
317
+ },
318
+ ...index.api.web.map(entry => ({
319
+ module: entry.module,
320
+ names: [entry.module, entryTail(entry.module)],
321
+ summary: `entry point: ${entry.values.length} exports, docs ${entry.docs}`,
322
+ })),
323
+ ]
324
+ for (const entry of entries) {
325
+ const total = score(query, terms, { names: entry.names })
326
+ if (total >= 50) {
327
+ results.push({
328
+ kind: 'api',
329
+ id: entry.module,
330
+ label: entry.module,
331
+ summary: entry.summary,
332
+ score: total * 0.9,
333
+ next: `atom63 api ${entry.module}`,
334
+ })
335
+ }
336
+ }
337
+ const listed = new Set()
338
+ for (const symbol of apiSymbols(index)) {
339
+ if (!symbol.inSearch || listed.has(symbol.name)) continue
340
+ const value = score(query, terms, { names: [symbol.name] })
341
+ // Outside `--kind api`, a name must start with the query: hundreds of
342
+ // contract constants contain short words such as "ios" or "tab".
343
+ if (value < (kind === 'api' ? 50 : 70)) continue
344
+ listed.add(symbol.name)
345
+ results.push({
346
+ kind: 'api',
347
+ id: symbol.name,
348
+ label: symbol.name,
349
+ summary: symbol.summary,
350
+ score: value >= 100 || kind === 'api' ? value : value * 0.4,
351
+ next: `atom63 api ${symbol.name}`,
352
+ })
353
+ }
354
+ }
355
+
280
356
  const allTokens = kind === 'token' || (!kind && query.trim().startsWith('--'))
281
357
  if (wants('token')) {
282
358
  for (const token of index.tokens) {
@@ -480,6 +556,89 @@ export function token(index, query) {
480
556
  return { type: 'token.results', data }
481
557
  }
482
558
 
559
+ /**
560
+ * A public API name or an entry point. A Swift type comes back with its
561
+ * declaration, doc comment, members and the component it renders; a
562
+ * JavaScript export with the entry points that export it, their import lines
563
+ * and docs pages. An entry point (`@atom63/ui-react/media`, `Atom63UI`) comes
564
+ * back with everything it exports.
565
+ */
566
+ export function api(index, name) {
567
+ if (!name?.trim()) throw new AtomError('api.not_found', 'Pass an API name or an entry point.')
568
+ const wanted = name.trim()
569
+ const { ios, web } = index.api
570
+ if (wanted === ios.module || /^(ios|swiftui)$/i.test(wanted)) {
571
+ return {
572
+ type: 'api.entry',
573
+ data: {
574
+ module: ios.module,
575
+ platform: 'ios',
576
+ docs: ios.docs,
577
+ import: `import ${ios.module}`,
578
+ symbols: ios.types.map(type => ({
579
+ name: type.name,
580
+ kind: type.kind,
581
+ summary: type.summary,
582
+ })),
583
+ },
584
+ }
585
+ }
586
+ const entry = web.find(candidate => candidate.module === wanted)
587
+ if (entry) {
588
+ return {
589
+ type: 'api.entry',
590
+ data: {
591
+ module: entry.module,
592
+ platform: 'web',
593
+ docs: entry.docs,
594
+ import: `import { … } from '${entry.module}'`,
595
+ symbols: entry.values.map(value => ({ name: value, kind: 'value', summary: '' })),
596
+ },
597
+ }
598
+ }
599
+
600
+ const same = candidate => candidate.toLowerCase() === wanted.toLowerCase()
601
+ const exact = candidate => candidate === wanted
602
+ const pick = list => (list.some(exact) ? list.filter(exact) : list.filter(same))
603
+ const swiftName = pick(ios.types.map(type => type.name))[0]
604
+ const webName = pick([...new Set(web.flatMap(candidate => candidate.values))])[0]
605
+ if (!swiftName && !webName) {
606
+ throw new AtomError(
607
+ 'api.not_found',
608
+ `No public API "${wanted}".`,
609
+ closest(wanted, [ios.module, ...apiSymbols(index).map(symbol => symbol.name)])
610
+ )
611
+ }
612
+ const componentOf = new Map(
613
+ index.components.flatMap(component =>
614
+ component.exports.values.map(value => [value, component.slug])
615
+ )
616
+ )
617
+ const swift = ios.types.find(type => type.name === swiftName)
618
+ return {
619
+ type: 'api.detail',
620
+ data: {
621
+ name: swiftName ?? webName,
622
+ ios: swift ? { ...swift, module: ios.module, docs: ios.docs } : null,
623
+ web: webName
624
+ ? web
625
+ .filter(candidate => candidate.values.includes(webName))
626
+ .map(candidate => ({
627
+ module: candidate.module,
628
+ import: `import { ${webName} } from '${candidate.module}'`,
629
+ docs: candidate.docs,
630
+ // What the docs page says about this export: purpose, example and props.
631
+ reference: candidate.sections?.[webName] ?? null,
632
+ // Only ui-react's catalog components; @atom63/mdx has its own `Tabs`.
633
+ component: candidate.module.startsWith('@atom63/ui-react')
634
+ ? (componentOf.get(webName) ?? null)
635
+ : null,
636
+ }))
637
+ : [],
638
+ },
639
+ }
640
+ }
641
+
483
642
  /** A docs page's Markdown by slug. */
484
643
  export function docsPage(index, slug) {
485
644
  const page = index.docs.find(doc => doc.slug === slug)
package/src/format.mjs CHANGED
@@ -203,7 +203,55 @@ function buildPlaybook(data) {
203
203
  ].join('\n')
204
204
  }
205
205
 
206
+ function apiDetail({ name, ios, web }) {
207
+ const lines = [`# ${name}`]
208
+ if (ios) {
209
+ lines.push(
210
+ '',
211
+ `SwiftUI (${ios.module}): ${ios.declaration}`,
212
+ `Source: ${ios.source}`,
213
+ ...(ios.summary ? ['', ios.summary] : []),
214
+ ...(ios.component
215
+ ? ['', `Renders the ${ios.component} contract: atom63 component ${ios.component}`]
216
+ : []),
217
+ ...(ios.members.length > 0
218
+ ? ['', 'Members:', ...ios.members.map(member => ` ${member.declaration}`)]
219
+ : []),
220
+ '',
221
+ `Guide: atom63 docs ${ios.docs}`
222
+ )
223
+ }
224
+ for (const entry of web) {
225
+ lines.push(
226
+ '',
227
+ entry.import,
228
+ entry.component
229
+ ? `Component: atom63 component ${entry.component}`
230
+ : `Docs: atom63 docs ${entry.docs}`
231
+ )
232
+ }
233
+ // Entries that re-export a name share its docs section; print it once.
234
+ const reference = web.find(entry => entry.reference)?.reference
235
+ if (reference) lines.push('', reference)
236
+ return lines.join('\n')
237
+ }
238
+
239
+ function apiEntry({ module, import: importLine, docs, symbols }) {
240
+ return [
241
+ `# ${module}`,
242
+ '',
243
+ importLine,
244
+ `Docs: atom63 docs ${docs}`,
245
+ '',
246
+ ...symbols.map(symbol => (symbol.summary ? `${symbol.name} — ${symbol.summary}` : symbol.name)),
247
+ '',
248
+ 'Read one with: atom63 api <name>',
249
+ ].join('\n')
250
+ }
251
+
206
252
  const renderers = {
253
+ 'api.detail': apiDetail,
254
+ 'api.entry': apiEntry,
207
255
  'search.results': searchResults,
208
256
  'token.results': searchResults,
209
257
  'component.detail': componentDetail,