@gntik-ai/cli 0.0.0-stage → 0.5.0
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/README.md +140 -2
- package/dist/index.js +1712 -0
- package/package.json +33 -3
package/README.md
CHANGED
|
@@ -1,3 +1,141 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @gntik-ai/cli
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
`gntik-ui` sets up a product on the gntik-ui design system, adds components (from npm) and
|
|
4
|
+
blocks/page templates (copied in), ejects a component's source, and browses the registry.
|
|
5
|
+
Every command has `--json` with a stable shape, so agents can drive it as well as people.
|
|
6
|
+
No runtime dependencies; Node ≥ 22.
|
|
7
|
+
|
|
8
|
+
```bash
|
|
9
|
+
# Packages are public on npmjs.org: pnpm add @gntik-ai/ui
|
|
10
|
+
pnpm dlx @gntik-ai/cli init
|
|
11
|
+
npx @gntik-ai/cli add button dialog
|
|
12
|
+
```
|
|
13
|
+
|
|
14
|
+
## Commands
|
|
15
|
+
|
|
16
|
+
| Command | What it does |
|
|
17
|
+
| --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
18
|
+
| `init [--brand gntik\|musematic]` | Detects framework (Vite `vite.config.*`, Next `next.config.*`, else generic), package manager (lockfile, walking up; then `packageManager`) and CSS entry (`src/index.css`, `src/styles.css`, `app/globals.css`, …). Puts `@import "tailwindcss"`, the Geist fonts and `@import "@gntik-ai/ui/styles.css"` at the top of the CSS entry, writes `gntik-ui.json`, prints the ThemeProvider + `themeScript` wiring (Next: `providers.tsx` + `layout.tsx` with `suppressHydrationWarning`; Vite: `main.tsx` + a `transformIndexHtml` plugin) and installs `@gntik-ai/ui @gntik-ai/tokens @fontsource/geist @fontsource/geist-mono` (+ Tailwind v4 as dev deps when missing). |
|
|
19
|
+
| `add <id...>` | Components/layouts: installs their package if missing and prints the import line. Blocks/templates: copies them and their `registryDependencies` (recursively) into the configured dirs, rewriting imports. |
|
|
20
|
+
| `eject <id> [--no-deps]` | Copies a component's source (plus doc file and, unless `--no-deps`, its registry dependencies) into the components dir, and lists the imports in your code to switch to the local copy. |
|
|
21
|
+
| `list [--kind k] [--group g]` | Table, or JSON. |
|
|
22
|
+
| `search <query> [--kind k] [--limit n]` | Fuzzy match on id, name, group and description; every term must match. |
|
|
23
|
+
| `docs <id>` | Description, status, package, files, dependencies, and the keyboard table parsed from the item's `*.doc.ts`. |
|
|
24
|
+
| `upgrade [paths...]` | Runs the `@gntik-ai/codemods` transforms for the breaking changes between two versions. Dry run unless `--apply`. See [Upgrading](#upgrading). |
|
|
25
|
+
|
|
26
|
+
Options: `--json`, `--cwd <dir>`, `--registry <dir|file|url>`, `--dry-run` (init/add/eject/upgrade),
|
|
27
|
+
`--overwrite`, `--no-install`, `--yes` (accepted; the CLI never prompts), `--help`, `--version`.
|
|
28
|
+
|
|
29
|
+
### Registry
|
|
30
|
+
|
|
31
|
+
`kit-registry.json` lives at the kit repo root (`{ version: 1, items: [...] }`, see
|
|
32
|
+
`src/registry.ts`). Source order: `--registry`, `$GNTIK_UI_REGISTRY`, `"registry"` in
|
|
33
|
+
`gntik-ui.json`, then `https://raw.githubusercontent.com/gntik-ai/gntik-ui/main/`. A local
|
|
34
|
+
checkout dir or a `kit-registry.json` path works too; files are read relative to it.
|
|
35
|
+
|
|
36
|
+
### Copying and import rewriting
|
|
37
|
+
|
|
38
|
+
Targets in the registry (`components/…`, `blocks/…`, `templates/…`) map through the
|
|
39
|
+
`aliases` in `gntik-ui.json`:
|
|
40
|
+
|
|
41
|
+
```json
|
|
42
|
+
{
|
|
43
|
+
"version": 1,
|
|
44
|
+
"framework": "vite",
|
|
45
|
+
"packageManager": "pnpm",
|
|
46
|
+
"css": "src/index.css",
|
|
47
|
+
"brand": "gntik",
|
|
48
|
+
"aliases": {
|
|
49
|
+
"components": "src/components",
|
|
50
|
+
"blocks": "src/components/blocks",
|
|
51
|
+
"templates": "src/components/templates"
|
|
52
|
+
}
|
|
53
|
+
}
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
Relative imports between files copied in the same run are re-pointed at their new location;
|
|
57
|
+
relative imports into kit code that is not copied become package imports
|
|
58
|
+
(`'../../components/Button'` → `'@gntik-ai/ui'`). Files that exist with different content are
|
|
59
|
+
**conflicts**: nothing is written and the exit code is 4 unless `--overwrite`. Identical files
|
|
60
|
+
are reported as `identical` and left alone.
|
|
61
|
+
|
|
62
|
+
### Upgrading
|
|
63
|
+
|
|
64
|
+
```bash
|
|
65
|
+
pnpm add -D @gntik-ai/codemods # once; upgrade loads it from the project
|
|
66
|
+
npx gntik-ui upgrade --list # every codemod, and which ones this upgrade selects
|
|
67
|
+
npx gntik-ui upgrade # dry run: files it would change + warnings
|
|
68
|
+
npx gntik-ui upgrade --apply # write the changes
|
|
69
|
+
npx gntik-ui upgrade src --codemod chip-text-aliases --apply
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
The CLI stays dependency-free: `upgrade` imports `@gntik-ai/codemods` from the project's
|
|
73
|
+
`node_modules` (walking up from `--cwd`); when it is missing it prints the install command for
|
|
74
|
+
the detected package manager and exits 1 (`CODEMODS`). `--from` defaults to the `@gntik-ai/*`
|
|
75
|
+
versions declared in `package.json` (per package; every codemod when none are declared, e.g.
|
|
76
|
+
`workspace:*`), `--to` to `latest`; a codemod is selected when the upgrade crosses its
|
|
77
|
+
`toVersion`. `--codemod <id>` (repeatable or comma-separated) runs exactly those, whatever the
|
|
78
|
+
versions; `--skip-codemod <id>` leaves some out. Paths limit the run to files/dirs; by default the
|
|
79
|
+
whole project is scanned without `node_modules`, `dist`, `build`, `.next`, … Report-only codemods
|
|
80
|
+
(`link-underline-default`) never write; their findings are `reports`.
|
|
81
|
+
|
|
82
|
+
| Codemod | Package | What it does |
|
|
83
|
+
| --------------------------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
84
|
+
| `templates-renamed-ids` | templates | `FlowBuilderPage` → `WorkflowBuilderPage`, `MfaChallengePage` → `MfaPage`, `flowBuilderTemplateMeta` → `workflowBuilderTemplateMeta`, `mfaChallengeTemplateMeta` → `mfaTemplateMeta` (imports, references, re-exports). |
|
|
85
|
+
| `flow-builder-controlled-console` | blocks | `<FlowBuilder consoleEntries={x}>` without `onConsoleChange` → `defaultConsoleEntries={x}` (spread props: reported, left alone). |
|
|
86
|
+
| `chip-text-aliases` | tokens | In a class string/template with `bg-<tone>/NN` and `text-<tone>-text` (primary, success, warning, destructive) → `text-<tone>-chip-text`. |
|
|
87
|
+
| `link-underline-default` | ui | Report only: `<Link>` from `@gntik-ai/ui` without `underline` (now underlined by default). |
|
|
88
|
+
|
|
89
|
+
## Exit codes
|
|
90
|
+
|
|
91
|
+
`0` ok · `1` error (registry unreadable, install failed, codemods missing, a file failed to transform) · `2` usage · `3` unknown item · `4` conflicts.
|
|
92
|
+
|
|
93
|
+
## JSON shapes
|
|
94
|
+
|
|
95
|
+
Every `--json` response is one object with `ok` and `command`; failures add
|
|
96
|
+
`error: { code: "USAGE"|"NOT_FOUND"|"CONFLICT"|"REGISTRY"|"INSTALL"|"CODEMODS"|"ERROR", message }`.
|
|
97
|
+
|
|
98
|
+
```ts
|
|
99
|
+
type Summary = { id; kind: 'component'|'layout'|'block'|'template'; name; package; group; status; description };
|
|
100
|
+
type Install = { packages: string[]; dev: string[]; commands: string[]; ran: boolean; exitCode: number | null };
|
|
101
|
+
type File = { id; source; target; status: 'create'|'identical'|'conflict'|'overwrite' };
|
|
102
|
+
|
|
103
|
+
list → { ok, command, registry, count, items: Summary[] }
|
|
104
|
+
search → { ok, command, query, count, items: (Summary & { score: number })[] }
|
|
105
|
+
docs → { ok, command, item: Summary & { files, dependencies, registryDependencies, docs: string|null },
|
|
106
|
+
primitive: string|null, pattern: string|null, keyboard: { key, behaviour }[] }
|
|
107
|
+
add → { ok, command, dryRun, configured, items: { id, kind, package, mode: 'copy'|'package', requested }[],
|
|
108
|
+
files: File[], written: string[], conflicts: string[], rewrites: { file, from, to }[],
|
|
109
|
+
warnings: string[], imports: string[], install: Install }
|
|
110
|
+
eject → { ok, command, dryRun, configured, id, items: string[], files, written, conflicts, rewrites, warnings,
|
|
111
|
+
localImport: string, exports: string[], usages: { file, line, names, replacement }[],
|
|
112
|
+
nextSteps: string[], install: Install }
|
|
113
|
+
init → { ok, command, dryRun, project: { framework, packageManager, css, cssExisted, entry, src },
|
|
114
|
+
config, changes: { file, action: 'create'|'patch'|'unchanged' }[],
|
|
115
|
+
snippet: { file, code }[], warnings: string[], install: Install }
|
|
116
|
+
upgrade → { ok, command, dryRun, from: string | Record<pkg, version> | null, to: string,
|
|
117
|
+
codemods: { installed, version: string|null, install: string|null },
|
|
118
|
+
transforms: Codemod[], scanned, files: { file, status: 'modified'|'unchanged'|'error', transforms: string[],
|
|
119
|
+
reports: { transform, line, message }[], error? }[], changed: string[],
|
|
120
|
+
reports: { file, line, transform, message }[], errors: { file, message }[] }
|
|
121
|
+
upgrade --list → { ok, command, dryRun, from, to, codemods, transforms: (Codemod & { selected: boolean })[] }
|
|
122
|
+
// Codemod = { id, package, fromVersion, toVersion, reportOnly, description }
|
|
123
|
+
// codemods missing → { ok: false, …, codemods: { installed: false, version: null, install: "pnpm add -D @gntik-ai/codemods" } }
|
|
124
|
+
```
|
|
125
|
+
|
|
126
|
+
Paths in output are project-relative (posix). With `--json`, installer output is captured, not
|
|
127
|
+
streamed, so stdout stays a single JSON document.
|
|
128
|
+
|
|
129
|
+
## For agents
|
|
130
|
+
|
|
131
|
+
- Plan with `--dry-run --json`, check `conflicts` and `install.commands`, then run without `--dry-run`.
|
|
132
|
+
- `--no-install` when the agent manages dependencies itself; run `install.commands` later.
|
|
133
|
+
- `search <words> --json --limit 5` → `docs <id> --json` → `add <id> --json`.
|
|
134
|
+
|
|
135
|
+
## Develop
|
|
136
|
+
|
|
137
|
+
```bash
|
|
138
|
+
pnpm --filter @gntik-ai/cli test # vitest (node env, temp projects via mkdtemp)
|
|
139
|
+
pnpm --filter @gntik-ai/cli build # tsdown → dist/index.js
|
|
140
|
+
node dist/index.js list --registry ../.. --json
|
|
141
|
+
```
|