@atom63/cli 0.0.0-stage → 0.1.0-beta.1
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/LICENSE +27 -0
- package/README.md +88 -2
- package/generated/agent-index.json +32310 -0
- package/package.json +40 -3
- package/src/agents-md.mjs +77 -0
- package/src/bin.mjs +154 -0
- package/src/commands.mjs +172 -0
- package/src/core.mjs +502 -0
- package/src/format.mjs +232 -0
- package/src/mcp.mjs +75 -0
- package/src/rules.mjs +89 -0
- package/src/synonyms.mjs +531 -0
- package/src/templates.mjs +347 -0
package/src/format.mjs
ADDED
|
@@ -0,0 +1,232 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Human-readable text for each envelope type. `--json` bypasses all of this;
|
|
3
|
+
* the text form is for people and for agents that read terminal output.
|
|
4
|
+
*/
|
|
5
|
+
|
|
6
|
+
const list = values => (values.length > 0 ? values.join(', ') : '—')
|
|
7
|
+
|
|
8
|
+
function searchResults({ query, results }) {
|
|
9
|
+
if (results.length === 0) return `No results for "${query}".`
|
|
10
|
+
return results
|
|
11
|
+
.map(
|
|
12
|
+
result =>
|
|
13
|
+
`${result.kind.padEnd(9)} ${result.id} — ${result.summary}\n → ${result.next}`
|
|
14
|
+
)
|
|
15
|
+
.join('\n')
|
|
16
|
+
}
|
|
17
|
+
|
|
18
|
+
function componentDetail(data) {
|
|
19
|
+
const lines = [
|
|
20
|
+
data.docsMarkdown.trim(),
|
|
21
|
+
'',
|
|
22
|
+
'## Examples',
|
|
23
|
+
'',
|
|
24
|
+
`${list(data.examples)}`,
|
|
25
|
+
'',
|
|
26
|
+
`Read one with: atom63 example ${data.slug} <story>`,
|
|
27
|
+
]
|
|
28
|
+
return lines.join('\n')
|
|
29
|
+
}
|
|
30
|
+
|
|
31
|
+
function exampleSource(data) {
|
|
32
|
+
return [
|
|
33
|
+
`// ${data.file} — ${data.story} (also: ${list(data.stories.filter(story => story !== data.story))})`,
|
|
34
|
+
data.imports,
|
|
35
|
+
'',
|
|
36
|
+
data.code,
|
|
37
|
+
].join('\n')
|
|
38
|
+
}
|
|
39
|
+
|
|
40
|
+
function tokenDetail(data) {
|
|
41
|
+
const lines = [`${data.cssVar} (${data.type}, ${data.layer} layer)`]
|
|
42
|
+
if (data.figma) lines.push(`Figma: ${data.figma.collection} / ${data.figma.path}`)
|
|
43
|
+
if (data.swift) lines.push(`Swift: ${data.swift}`)
|
|
44
|
+
lines.push('Values:')
|
|
45
|
+
for (const { scope, value } of data.values) lines.push(` ${scope}: ${value}`)
|
|
46
|
+
return lines.join('\n')
|
|
47
|
+
}
|
|
48
|
+
|
|
49
|
+
function rulesText({ rules }) {
|
|
50
|
+
return rules
|
|
51
|
+
.map(
|
|
52
|
+
(rule, position) =>
|
|
53
|
+
`${position + 1}. ${rule.rule}\n Why: ${rule.why}${rule.check ? `\n Checked by: check:craft (${[rule.check].flat().join(', ')})` : ''}`
|
|
54
|
+
)
|
|
55
|
+
.join('\n\n')
|
|
56
|
+
}
|
|
57
|
+
|
|
58
|
+
function manifestText({ commands, errorCodes }) {
|
|
59
|
+
const usage = command =>
|
|
60
|
+
[
|
|
61
|
+
`atom63 ${command.name}`,
|
|
62
|
+
...command.args.map(arg => (arg.optional ? `[${arg.name}]` : `<${arg.name}>`)),
|
|
63
|
+
...command.flags.map(
|
|
64
|
+
flag => `[--${flag.name}${flag.type === 'boolean' ? '' : ` <${flag.type}>`}]`
|
|
65
|
+
),
|
|
66
|
+
].join(' ')
|
|
67
|
+
return [
|
|
68
|
+
...commands.map(command => `${usage(command)}\n ${command.summary}`),
|
|
69
|
+
'',
|
|
70
|
+
'Every command takes --json for a typed { type, data } envelope.',
|
|
71
|
+
`Error codes: ${errorCodes.join(', ')}`,
|
|
72
|
+
].join('\n')
|
|
73
|
+
}
|
|
74
|
+
|
|
75
|
+
function templateList({ templates }) {
|
|
76
|
+
if (templates.length === 0) return 'No templates.'
|
|
77
|
+
return templates
|
|
78
|
+
.map(
|
|
79
|
+
entry =>
|
|
80
|
+
`${entry.kind.padEnd(6)} ${entry.id} (${entry.readiness}) — ${entry.description}\n → atom63 template ${entry.id}`
|
|
81
|
+
)
|
|
82
|
+
.join('\n')
|
|
83
|
+
}
|
|
84
|
+
|
|
85
|
+
function templateDetail(data) {
|
|
86
|
+
return [
|
|
87
|
+
`# ${data.title} (${data.kind}, ${data.readiness})`,
|
|
88
|
+
'',
|
|
89
|
+
data.description,
|
|
90
|
+
'',
|
|
91
|
+
`Components: ${list(data.componentsUsed)}`,
|
|
92
|
+
`Blocks: ${list(data.blocksUsed)}`,
|
|
93
|
+
'',
|
|
94
|
+
...[...data.files, ...data.blockFiles].flatMap(file => [
|
|
95
|
+
`// ${file.path}`,
|
|
96
|
+
file.source.trimEnd(),
|
|
97
|
+
'',
|
|
98
|
+
]),
|
|
99
|
+
'Templates are copy-only: no package ships them. Paste the files above, keeping their',
|
|
100
|
+
'pages/ and blocks/ folders so the relative imports resolve, or install them with either of:',
|
|
101
|
+
` ${data.next}`,
|
|
102
|
+
` ${data.registry}`,
|
|
103
|
+
`They import: ${list(data.packages)}.`,
|
|
104
|
+
].join('\n')
|
|
105
|
+
}
|
|
106
|
+
|
|
107
|
+
function templateCopied(data) {
|
|
108
|
+
return [
|
|
109
|
+
`Copied ${data.id} into ${data.directory}:`,
|
|
110
|
+
...data.written.map(file => ` wrote ${file}`),
|
|
111
|
+
...data.skipped.map(file => ` kept ${file} (exists)`),
|
|
112
|
+
'',
|
|
113
|
+
...data.next,
|
|
114
|
+
].join('\n')
|
|
115
|
+
}
|
|
116
|
+
|
|
117
|
+
function buildKit(data) {
|
|
118
|
+
const section = (title, items, line) =>
|
|
119
|
+
items.length > 0 ? [`## ${title}`, ...items.map(line), ''] : []
|
|
120
|
+
return [
|
|
121
|
+
`# Kit for "${data.idea}"`,
|
|
122
|
+
'',
|
|
123
|
+
...(data.phone
|
|
124
|
+
? [
|
|
125
|
+
'## Phone screen',
|
|
126
|
+
data.phone.use,
|
|
127
|
+
data.phone.files,
|
|
128
|
+
'',
|
|
129
|
+
'```tsx',
|
|
130
|
+
...data.phone.imports,
|
|
131
|
+
'',
|
|
132
|
+
data.phone.snippet,
|
|
133
|
+
'```',
|
|
134
|
+
`→ ${data.phone.next}`,
|
|
135
|
+
'',
|
|
136
|
+
]
|
|
137
|
+
: []),
|
|
138
|
+
...(data.amount
|
|
139
|
+
? [
|
|
140
|
+
'## Display amount',
|
|
141
|
+
data.amount.use,
|
|
142
|
+
'',
|
|
143
|
+
'```tsx',
|
|
144
|
+
...data.amount.imports,
|
|
145
|
+
'',
|
|
146
|
+
data.amount.snippet,
|
|
147
|
+
'```',
|
|
148
|
+
`→ ${data.amount.next}`,
|
|
149
|
+
'',
|
|
150
|
+
]
|
|
151
|
+
: []),
|
|
152
|
+
...(data.density
|
|
153
|
+
? [
|
|
154
|
+
'## Compact density',
|
|
155
|
+
data.density.use,
|
|
156
|
+
'',
|
|
157
|
+
'```tsx',
|
|
158
|
+
...data.density.imports,
|
|
159
|
+
'',
|
|
160
|
+
data.density.snippet,
|
|
161
|
+
'```',
|
|
162
|
+
`→ ${data.density.next}`,
|
|
163
|
+
'',
|
|
164
|
+
]
|
|
165
|
+
: []),
|
|
166
|
+
...section(
|
|
167
|
+
'Pages',
|
|
168
|
+
data.pages,
|
|
169
|
+
entry => `- ${entry.id}: ${entry.description}\n → ${entry.next}`
|
|
170
|
+
),
|
|
171
|
+
...section(
|
|
172
|
+
'Blocks',
|
|
173
|
+
data.blocks,
|
|
174
|
+
entry => `- ${entry.id}: ${entry.description}\n → ${entry.next}`
|
|
175
|
+
),
|
|
176
|
+
...section(
|
|
177
|
+
'Components',
|
|
178
|
+
data.components,
|
|
179
|
+
entry => `- ${entry.slug}: ${entry.summary}\n → ${entry.next}`
|
|
180
|
+
),
|
|
181
|
+
...section(
|
|
182
|
+
'Ground',
|
|
183
|
+
data.ground ? [data.ground] : [],
|
|
184
|
+
entry => `- Neutral ${entry.surface}, page ${entry.page}: ${entry.note}`
|
|
185
|
+
),
|
|
186
|
+
...section(
|
|
187
|
+
'Foundation',
|
|
188
|
+
data.foundation,
|
|
189
|
+
entry => `- ${entry.name} (${entry.from}): ${entry.use}`
|
|
190
|
+
),
|
|
191
|
+
...section('Rules', data.rules, rule => `- ${rule}`),
|
|
192
|
+
]
|
|
193
|
+
.join('\n')
|
|
194
|
+
.trimEnd()
|
|
195
|
+
}
|
|
196
|
+
|
|
197
|
+
function buildPlaybook(data) {
|
|
198
|
+
return [
|
|
199
|
+
...data.steps.map((step, position) => `${position + 1}. ${step}`),
|
|
200
|
+
'',
|
|
201
|
+
'Foundation:',
|
|
202
|
+
...data.foundation.map(entry => `- ${entry.name} (${entry.from}): ${entry.use}`),
|
|
203
|
+
].join('\n')
|
|
204
|
+
}
|
|
205
|
+
|
|
206
|
+
const renderers = {
|
|
207
|
+
'search.results': searchResults,
|
|
208
|
+
'token.results': searchResults,
|
|
209
|
+
'component.detail': componentDetail,
|
|
210
|
+
'example.source': exampleSource,
|
|
211
|
+
'token.detail': tokenDetail,
|
|
212
|
+
'docs.page': data => data.markdown.trim(),
|
|
213
|
+
'template.list': templateList,
|
|
214
|
+
'template.detail': templateDetail,
|
|
215
|
+
'template.copied': templateCopied,
|
|
216
|
+
'build.kit': buildKit,
|
|
217
|
+
'build.playbook': buildPlaybook,
|
|
218
|
+
'agents.md': data => data.markdown,
|
|
219
|
+
rules: rulesText,
|
|
220
|
+
manifest: manifestText,
|
|
221
|
+
error: ({ code, message, suggestions }) =>
|
|
222
|
+
[
|
|
223
|
+
`${message} (${code})`,
|
|
224
|
+
...(suggestions.length > 0 ? [`Did you mean: ${suggestions.join(', ')}?`] : []),
|
|
225
|
+
].join('\n'),
|
|
226
|
+
}
|
|
227
|
+
|
|
228
|
+
export function formatEnvelope({ type, data }) {
|
|
229
|
+
const render = renderers[type]
|
|
230
|
+
if (!render) throw new Error(`No text renderer for ${type}`)
|
|
231
|
+
return render(data)
|
|
232
|
+
}
|
package/src/mcp.mjs
ADDED
|
@@ -0,0 +1,75 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The MCP server: every query command in the command table becomes a tool
|
|
3
|
+
* with the same name, input and response types, so an MCP host and the CLI
|
|
4
|
+
* give the same answers. Served over stdio by `atom63 mcp`.
|
|
5
|
+
*
|
|
6
|
+
* A tool result carries the CLI's readable text as `content` and the typed
|
|
7
|
+
* `{ type, data }` envelope as `structuredContent`. A failed query is an
|
|
8
|
+
* `isError` result whose envelope holds the stable error `code`.
|
|
9
|
+
*/
|
|
10
|
+
import { McpServer } from '@modelcontextprotocol/server'
|
|
11
|
+
import { serveStdio } from '@modelcontextprotocol/server/stdio'
|
|
12
|
+
import * as z from 'zod/v4'
|
|
13
|
+
|
|
14
|
+
import { commands } from './commands.mjs'
|
|
15
|
+
import { AtomError, loadIndex } from './core.mjs'
|
|
16
|
+
import { formatEnvelope } from './format.mjs'
|
|
17
|
+
|
|
18
|
+
const packageVersion = '0.0.0'
|
|
19
|
+
|
|
20
|
+
/** A zod object schema for a command's positional arguments and flags. */
|
|
21
|
+
export function inputSchema(command) {
|
|
22
|
+
const shape = {}
|
|
23
|
+
for (const arg of command.args) {
|
|
24
|
+
const field = z.string().min(1).describe(arg.description)
|
|
25
|
+
shape[arg.name] = arg.optional ? field.optional() : field
|
|
26
|
+
}
|
|
27
|
+
for (const flag of command.flags) {
|
|
28
|
+
let field
|
|
29
|
+
if (flag.type === 'number') field = z.number().int().positive()
|
|
30
|
+
else if (flag.type === 'boolean') field = z.boolean()
|
|
31
|
+
else if (flag.choices) field = z.enum(flag.choices)
|
|
32
|
+
else field = z.string()
|
|
33
|
+
shape[flag.name] = field.describe(flag.description).optional()
|
|
34
|
+
}
|
|
35
|
+
return z.object(shape)
|
|
36
|
+
}
|
|
37
|
+
|
|
38
|
+
const result = (envelope, isError = false) => ({
|
|
39
|
+
content: [{ type: 'text', text: formatEnvelope(envelope) }],
|
|
40
|
+
structuredContent: envelope,
|
|
41
|
+
...(isError ? { isError: true } : {}),
|
|
42
|
+
})
|
|
43
|
+
|
|
44
|
+
/** A new server instance with the selected read-only query tools. */
|
|
45
|
+
export function createAtomServer(index = loadIndex(), { tools } = {}) {
|
|
46
|
+
const server = new McpServer({ name: 'atom63', version: packageVersion })
|
|
47
|
+
const allowed = tools ? new Set(tools) : null
|
|
48
|
+
for (const command of commands.filter(
|
|
49
|
+
candidate => !candidate.writes && (!allowed || allowed.has(candidate.name))
|
|
50
|
+
)) {
|
|
51
|
+
server.registerTool(
|
|
52
|
+
command.name,
|
|
53
|
+
{
|
|
54
|
+
title: `atom63 ${command.name}`,
|
|
55
|
+
description: `${command.summary} Returns ${command.returns.join(' or ')}.`,
|
|
56
|
+
inputSchema: inputSchema(command),
|
|
57
|
+
annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
|
|
58
|
+
},
|
|
59
|
+
async input => {
|
|
60
|
+
try {
|
|
61
|
+
return result(command.run(index, input ?? {}))
|
|
62
|
+
} catch (error) {
|
|
63
|
+
if (error instanceof AtomError) return result(error.toEnvelope(), true)
|
|
64
|
+
throw error
|
|
65
|
+
}
|
|
66
|
+
}
|
|
67
|
+
)
|
|
68
|
+
}
|
|
69
|
+
return server
|
|
70
|
+
}
|
|
71
|
+
|
|
72
|
+
/** Serve over stdio until the host closes the connection. */
|
|
73
|
+
export function serve({ tools } = {}) {
|
|
74
|
+
return serveStdio(() => createAtomServer(undefined, { tools }))
|
|
75
|
+
}
|
package/src/rules.mjs
ADDED
|
@@ -0,0 +1,89 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The rules an agent follows when it builds UI with Atom63. `atom63 rules`
|
|
3
|
+
* prints them, and the AGENTS.md snippet is generated from the same table.
|
|
4
|
+
* `check` names the repo check that enforces a rule mechanically, when one
|
|
5
|
+
* exists.
|
|
6
|
+
*/
|
|
7
|
+
export const rules = [
|
|
8
|
+
{
|
|
9
|
+
id: 'query-first',
|
|
10
|
+
rule: 'Query the design system before writing UI: start a screen from the closest page template, then search for components, read their contracts, and start from story examples.',
|
|
11
|
+
why: 'The templates, catalog, contracts and examples are the reviewed answers; guessing reinvents them with drift.',
|
|
12
|
+
},
|
|
13
|
+
{
|
|
14
|
+
id: 'compose-before-create',
|
|
15
|
+
rule: 'Compose existing components before writing new ones. Add a component to the system with `pnpm ds:new`, not by copying another.',
|
|
16
|
+
why: 'A new component must be wired into contracts, recipes, docs and tests; the scaffold does that, a copy does not.',
|
|
17
|
+
},
|
|
18
|
+
{
|
|
19
|
+
id: 'contract-values',
|
|
20
|
+
rule: "Pass only the axis values a component's contract lists (sizes, variants, orientations), and rely on its defaults.",
|
|
21
|
+
why: 'Recipes, the SwiftUI renderer and the Figma variables are built for exactly those values.',
|
|
22
|
+
},
|
|
23
|
+
{
|
|
24
|
+
id: 'tokens-only',
|
|
25
|
+
rule: 'Take every color, space, radius, shadow and duration from `--a63-*` tokens, and look a name up with `atom63 token` before using it. No literal colors and no Tailwind palette utilities.',
|
|
26
|
+
why: 'Tokens follow the theme, brand, mode and density; literals break all four, and a token name that does not exist resolves to nothing.',
|
|
27
|
+
check: ['raw-color', 'unknown-token'],
|
|
28
|
+
},
|
|
29
|
+
{
|
|
30
|
+
id: 'accent-sparingly',
|
|
31
|
+
rule: 'Use the accent for one or two cues per view; the main action may be neutral. Give a view at most one `variant="primary"` Button. Selection is neutral by default; set `tone="accent"` on a selection, Slider or Progress only when it is one of those cues. Where the product draws its main action or its links in its brand colour, keep `variant="primary"` and `variant="link"`: sparing means one or two cues, not none.',
|
|
32
|
+
why: 'An accent on every control points at nothing. Button `default` is a high-emphasis neutral solid; `primary` is for a main action in the brand colour. The vibe measures warn at more than one primary Button per file. Taking the accent off a product whose main action is brand-coloured loses the cue the product relies on.',
|
|
33
|
+
},
|
|
34
|
+
{
|
|
35
|
+
id: 'quiet-secondary-actions',
|
|
36
|
+
rule: 'Draw secondary actions in toolbars, list rows and card headers as `variant="ghost"` Buttons with `tone="muted"`, icon-only at `icon-sm` or `icon-xs` in dense rows. Keep the main action at full contrast.',
|
|
37
|
+
why: 'Muted ghost actions rest in the secondary text colour, with no box, and go to full contrast on hover, focus and press, so a row of actions stays calm and still answers the pointer.',
|
|
38
|
+
},
|
|
39
|
+
{
|
|
40
|
+
id: 'one-boundary',
|
|
41
|
+
rule: "One boundary per element: border, fill or shadow, not two. Don't nest outlined containers.",
|
|
42
|
+
why: 'Each extra edge is another line to read past. Card `filled` and `elevated` and Button `raised` give a fill or a shadow without the border.',
|
|
43
|
+
},
|
|
44
|
+
{
|
|
45
|
+
id: 'on-media-colors',
|
|
46
|
+
rule: 'Controls drawn over photos or video use the `--a63-on-media-*` and `--a63-media-*` tokens.',
|
|
47
|
+
why: 'Theme colors are meaningless on an unknown picture; these hold contrast on any image.',
|
|
48
|
+
},
|
|
49
|
+
{
|
|
50
|
+
id: 'content-colors',
|
|
51
|
+
rule: 'Draw content that carries its own colours (illustrations, game pieces, map and chart series, story rings, category marks) with the `--a63-category-{hue}` palette: 18 hues, each with `-subtle` and `-subtle-foreground`, as utilities such as `bg-category-green` and `text-category-green-subtle-foreground`. For another shade, mix two tokens with `color-mix(in oklch, var(--a63-category-green) 75%, var(--a63-text-primary))`, never a colour keyword or value.',
|
|
52
|
+
why: 'The palette follows the theme and the mode, so content stays legible in dark mode. A literal colour, or a keyword such as `black` inside `color-mix()`, fails `raw-color` and makes a vibe case invalid.',
|
|
53
|
+
check: ['raw-color'],
|
|
54
|
+
},
|
|
55
|
+
{
|
|
56
|
+
id: 'logical-directions',
|
|
57
|
+
rule: 'Use logical properties and utilities (`margin-inline-start`, `ps-4`, `text-start`, `border-s`), not left and right.',
|
|
58
|
+
why: 'Layouts must mirror in right-to-left languages.',
|
|
59
|
+
check: 'physical-properties',
|
|
60
|
+
},
|
|
61
|
+
{
|
|
62
|
+
id: 'focus-visible',
|
|
63
|
+
rule: 'Draw focus rings on `:focus-visible` (`focus-visible:` in Tailwind), never on `:focus`.',
|
|
64
|
+
why: 'A pointer press should not leave a keyboard focus ring behind.',
|
|
65
|
+
check: 'focus-visible',
|
|
66
|
+
},
|
|
67
|
+
{
|
|
68
|
+
id: 'focus-ring-outline',
|
|
69
|
+
rule: 'Draw focus rings as an `outline` (`focus-visible:outline-*` in Tailwind), not a `box-shadow` or `ring-*`. Inset it with a negative `outline-offset` where a parent clips it.',
|
|
70
|
+
why: "A component's own box-shadow replaces a shadow ring, and forced-colors mode drops shadows.",
|
|
71
|
+
check: 'focus-ring-outline',
|
|
72
|
+
},
|
|
73
|
+
{
|
|
74
|
+
id: 'theme-agnostic',
|
|
75
|
+
rule: 'Never branch on light or dark mode in component code; let tokens and `UIProvider` resolve the mode.',
|
|
76
|
+
why: 'Themes and brands change the palette too; a mode check covers one axis of four.',
|
|
77
|
+
check: 'mode-branch',
|
|
78
|
+
},
|
|
79
|
+
{
|
|
80
|
+
id: 'as-child-spreads-props',
|
|
81
|
+
rule: 'A component you pass with `asChild` (or as `render`) must spread the props it receives onto the element it renders and forward its ref.',
|
|
82
|
+
why: 'The part merges its class, data attributes and ref into that element; a wrapper that drops them renders unstyled.',
|
|
83
|
+
},
|
|
84
|
+
{
|
|
85
|
+
id: 'accessible-by-default',
|
|
86
|
+
rule: 'Keep the native semantics components render (buttons, links, labels, dialogs) and give every icon-only control an accessible name.',
|
|
87
|
+
why: 'Every story runs axe in CI; code that removes semantics fails it.',
|
|
88
|
+
},
|
|
89
|
+
]
|