@foundrykit/cli 2.0.11 → 3.0.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 CHANGED
@@ -1,75 +1,142 @@
1
1
  # @foundrykit/cli
2
2
 
3
- The FoundryKit CLI initializes projects and installs components from the
4
- FoundryKit registry.
3
+ Command-line tool for initializing FoundryKit in a project and installing
4
+ components from the FoundryKit registry. Exposes the `foundrykit` binary.
5
+
6
+ ## Installation
7
+
8
+ Run directly with your package runner:
9
+
10
+ ```bash
11
+ npx @foundrykit/cli init
12
+ # or
13
+ pnpm dlx @foundrykit/cli init
14
+ ```
15
+
16
+ Or install it as a dev dependency:
17
+
18
+ ```bash
19
+ pnpm add -D @foundrykit/cli
20
+ ```
5
21
 
6
22
  ## Commands
7
23
 
8
24
  ### `init`
9
25
 
10
- Creates `foundrykit.config.json`, installs the utility helper, prepares target
11
- directories, and updates package scripts for a Next.js project.
26
+ Scaffolds `foundrykit.json` and `foundrykit.lock.json`, installs the utility helper, prepares target
27
+ directories, and updates package scripts.
12
28
 
13
29
  ```bash
14
- foundrykit init
30
+ foundrykit init [--force] [--skip-install] [--skip-prompts]
15
31
  ```
16
32
 
17
33
  ### `list`
18
34
 
19
- Lists available registry components.
35
+ Lists available registry components and blocks.
20
36
 
21
37
  ```bash
22
38
  foundrykit list
23
- foundrykit list -c primitives
24
- foundrykit list -s button
39
+ foundrykit list -c primitives # filter by category
40
+ foundrykit list -s button # search by name/description
25
41
  ```
26
42
 
27
43
  ### `add`
28
44
 
29
- Fetches a component from the registry, installs its files, installs any missing
30
- package dependencies, and prints a usage hint.
45
+ Fetches a component or block from the registry, installs its files and any
46
+ missing dependencies. Runs interactively when no id is given.
31
47
 
32
48
  ```bash
33
- foundrykit add hero-minimal
34
- foundrykit add button -o
49
+ foundrykit add [id] [--with-animation] [-p <path>] [-o]
35
50
  ```
36
51
 
52
+ `--path` places a newly added component's own files under that directory;
53
+ dependencies go where your settings (or the lock, if already installed) put
54
+ them.
55
+
37
56
  ### `update`
38
57
 
39
- Reinstalls a component with overwrite semantics using the same registry-backed
40
- installation flow as `add`.
58
+ Updates tracked components (omit the id to update all).
41
59
 
42
60
  ```bash
43
- foundrykit update hero-minimal
61
+ foundrykit update [id] [-o] [-f] [--overwrite]
44
62
  ```
45
63
 
46
- ### `doctor`
64
+ `update` updates files where the lock recorded them, including components
65
+ added with `add --path`; that is why `update --path` was removed.
66
+
67
+ ### Edited and untracked files (`add` and `update`)
47
68
 
48
- Validates that:
69
+ Files you have edited locally are left alone; pass `--overwrite` to replace
70
+ them. Files the CLI can't verify (not yet tracked in the lock) prompt in a
71
+ terminal and are skipped otherwise. A file you choose to keep is remembered and
72
+ skipped on later runs until you pass `--overwrite`, which covers files edited
73
+ locally or not yet tracked. `--overwrite` doesn't apply to the registry
74
+ dependencies installed alongside the component you add or update.
49
75
 
50
- - `package.json` exists
51
- - Next.js is detected
52
- - `foundrykit.config.json` exists and has the expected shape
53
- - the configured registry URL is reachable
76
+ ### `doctor`
77
+
78
+ Checks project health: `package.json`, Next.js detection, a valid
79
+ `foundrykit.json`, `foundrykit.lock.json`, and registry reachability.
54
80
 
55
81
  ```bash
56
82
  foundrykit doctor
57
83
  ```
58
84
 
59
- ## Registry Contract
85
+ ## Foundry hub
60
86
 
61
- The CLI uses the registry configured in `foundrykit.config.json`.
87
+ `login`, `link`, `connect`, `connections` and `provision` talk to the Foundry
88
+ hub, which holds the provider credentials and creates a project's GitHub repo,
89
+ Sentry project and Dokploy services.
62
90
 
63
- Canonical endpoints:
91
+ ```bash
92
+ foundrykit login [--hub <url>] [--no-browser] # device flow; approve the code in the hub
93
+ foundrykit whoami
94
+ foundrykit link <org>/<project> [--hub <url>] # writes hub.project (and hub.url) to foundrykit.json
95
+ foundrykit connect <github|dokploy|sentry> [--owner <o>] [--label <l>] [--token-stdin] [--config k=v ...]
96
+ foundrykit connections # connections you can see and which one the linked project resolves to
97
+ foundrykit provision [--dry-run] [--yes] [--adopt] [--push | --no-push]
98
+ foundrykit logout [--hub <url>]
99
+ ```
64
100
 
65
- - `GET {registry}/registry`
66
- - `GET {registry}/registry/{id}`
101
+ `provision` shows the plan, asks (or needs `--yes`), applies it on the hub,
102
+ then, if the project has no `origin` remote, asks whether to add
103
+ `https://github.com/<repo>.git` as `origin` and push `HEAD:prod`. Pushing to
104
+ `prod` deploys. `--yes` answers yes to both questions, so it also adds the
105
+ remote and pushes; `--no-push` skips the push, `--push` pushes without
106
+ asking. An existing `origin` is left alone, and outside a git repo the push is
107
+ skipped with the commands to run.
108
+
109
+ **Hub URL**, first match wins: `--hub` (login, logout, link),
110
+ `FOUNDRYKIT_HUB_URL`, `hub.url` in `foundrykit.json`, then
111
+ `http://localhost:3003`. Trailing slashes are ignored. A cloned repo can set
112
+ `hub.url`, so `login` asks before signing in to a hub URL that only comes
113
+ from `foundrykit.json` (default No); without a TTY or with `--json` it
114
+ refuses, and you pass `--hub <url>` instead. `connect` names the hub it sends
115
+ the token to. Plain `http://` to anything but localhost prints a warning.
116
+
117
+ **Credentials** are saved to `~/.foundrykit/credentials.json` (mode `0600`),
118
+ one entry per hub URL. `logout` removes the entry.
119
+
120
+ **Scripts and agents**: every hub command takes `--json` (one JSON document on
121
+ stdout; errors are `{ "error": { "code", "message" } }`, same exit codes).
122
+ Nothing prompts without a TTY. Tokens are never flags: pass them on stdin.
67
123
 
68
- Legacy `/api/components` endpoints may still exist on the host for
69
- compatibility, but the CLI should be considered a `/registry` consumer.
124
+ ```bash
125
+ printf %s "$TOKEN" | foundrykit connect sentry --token-stdin --config org=umi --config team=web --json
126
+ foundrykit provision --yes --json
127
+ ```
70
128
 
71
129
  ## Notes
72
130
 
73
131
  - The CLI currently targets Next.js projects.
74
- - `test` runs in non-watch mode by default for CI friendliness.
75
- - Installation paths are controlled by `foundrykit.config.json`.
132
+ - Installation paths and the registry URL are controlled by `foundrykit.json`.
133
+ - `foundrykit.lock.json` records installed components and a fingerprint of each
134
+ installed file. Commit both files.
135
+ - Projects with the old `foundrykit.config.json` migrate automatically on the
136
+ next `add`, `update` or `init --force` (no network needed); the legacy file is
137
+ deleted. `doctor` reports a pending migration; `doctor` and
138
+ `list` never write.
139
+
140
+ ## License
141
+
142
+ MIT