@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 ADDED
@@ -0,0 +1,27 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 You Zhang (ATOM63)
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.
22
+
23
+ ---
24
+
25
+ The MIT license above covers the code and documentation in this repository. It does not grant
26
+ any right to use the ATOM63 name, the ATOM63 logo or other ATOM63 brand marks, including the
27
+ artwork in packages/brand. All rights to them are reserved.
package/README.md CHANGED
@@ -1,3 +1,89 @@
1
- # Temporary Holding Version
1
+ # @atom63/cli
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Query the Atom63 design system from the command line or an MCP host: components, their contracts
4
+ (including the shared web and iOS contract), tokens with their Figma and Swift names, story
5
+ examples, docs pages and the rules for building UI with the system. The plan and its decisions
6
+ are in [`docs/design-system/agent-interface-plan.md`](../../docs/design-system/agent-interface-plan.md).
7
+
8
+ Released on the `beta` tag with the other packages, starting at `0.1.0-beta.0`. Status by step:
9
+
10
+ 1. **Agent index and query core.** `generated/agent-index.json` holds every answer, so queries
11
+ need no repo, network or build. `src/core.mjs` exposes `search`, `component`, `example`,
12
+ `token`, `docsPage` and `rules`. Each returns `{ type, data }` or throws an `AtomError` with a
13
+ stable `code`.
14
+ 2. **The `atom63` command.** See below.
15
+ 3. **`atom63 mcp`**, an MCP server over stdio. See below.
16
+ 4. **`atom63 agents`**, the AGENTS.md section generated from `src/rules.mjs`. It covers how to
17
+ query the system and the rules with their reasons, and sits between `atom63:agents` markers so
18
+ it can be kept in sync. Paste it into a consuming project's AGENTS.md. This repo's own
19
+ `AGENTS.md` embeds it, and `pnpm check:agents-md` fails when it is stale.
20
+ 5. **Templates.** The index holds every page and block in `@atom63/templates`, with its source
21
+ files and the components and blocks it uses (derived from its imports). `atom63 template`
22
+ lists or shows them (a shown template carries its blocks' files too, since templates are
23
+ copy-only and ship in no package), `atom63 copy` writes one and the blocks it uses into a
24
+ project, and
25
+ `atom63 build <idea>` returns a kit: the closest pages and blocks, the components they use,
26
+ the foundation and the rules. `search` finds templates too.
27
+
28
+ ## Usage
29
+
30
+ In this repo, run it through the root script:
31
+
32
+ ```bash
33
+ pnpm atom63 build billing settings page
34
+ pnpm atom63 template settings-page
35
+ pnpm atom63 copy settings-page src/templates
36
+ pnpm atom63 search date picker
37
+ pnpm atom63 component dialog
38
+ pnpm atom63 example badge Sizes
39
+ pnpm atom63 token --a63-surface-page
40
+ pnpm atom63 docs theme-system
41
+ pnpm atom63 rules
42
+ pnpm atom63 manifest --json
43
+ ```
44
+
45
+ In another project, install it as a dev dependency and run it with `pnpm exec`:
46
+
47
+ ```bash
48
+ pnpm add -D @atom63/cli@beta
49
+ pnpm exec atom63 build billing settings page
50
+ ```
51
+
52
+ Every command takes `--json` and prints one typed envelope on stdout, `{ "type": …, "data": … }`.
53
+ Failures print `{ "type": "error", "data": { "code", "message", "suggestions" } }`. The exit code
54
+ is 0 for an answer, 1 for a failed query (for example an unknown component) and 2 for a wrong
55
+ command line. `manifest` lists every command, argument, flag, response type and error code.
56
+ Error codes are append-only: once shipped, a code keeps its meaning. The command table in
57
+ `src/commands.mjs` defines the CLI and the manifest, and it will define the MCP tools too.
58
+
59
+ ## MCP
60
+
61
+ `atom63 mcp` serves the same commands as MCP tools over stdio, built with
62
+ `@modelcontextprotocol/server` v2. Each tool has the command's name and a typed input schema, and
63
+ it is marked read-only; `copy`, which writes files, is left out. The result carries the CLI's text as `content` and the `{ type, data }`
64
+ envelope as `structuredContent`. A failed query is an `isError` result that holds the error
65
+ `code`.
66
+
67
+ This repo's `.mcp.json` registers the server for Claude Code; approve it once when Claude Code
68
+ asks. In another project, add it by hand, for example:
69
+
70
+ ```bash
71
+ claude mcp add atom63 -- node /path/to/atom63-design-system/packages/cli/src/bin.mjs mcp
72
+ ```
73
+
74
+ ## Keeping the index current
75
+
76
+ The index is generated from the component catalog and docs helpers in `apps/docs`, the contracts
77
+ in `@atom63/ui-foundation`, the token manifest in `@atom63/styles`, the Swift token map and the
78
+ co-located stories. CI fails when it is stale:
79
+
80
+ ```bash
81
+ pnpm --filter @atom63/cli generate:index
82
+ pnpm check:agent-index
83
+ ```
84
+
85
+ Search quality is pinned by the golden queries in `src/core.test.mjs`. When a query should find a
86
+ component by another word, add it to `synonyms` in `src/synonyms.mjs` and to the golden list.
87
+ When it should find a token, docs page, story example or template that no component name leads to
88
+ (`gradient`, `price cents`, `bottom sheet`), add a `topics` entry there instead; its entries
89
+ rank first, in order, with a note that says what to use, and the topic golden list pins them.