@gntik-ai/cli 0.0.0-canary-20261102051407

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.
Files changed (3) hide show
  1. package/README.md +141 -0
  2. package/dist/index.js +1712 -0
  3. package/package.json +36 -0
package/README.md ADDED
@@ -0,0 +1,141 @@
1
+ # @gntik-ai/cli
2
+
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
+ ```