@foundrykit/cli 2.0.12 → 3.1.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
@@ -23,7 +23,7 @@ pnpm add -D @foundrykit/cli
23
23
 
24
24
  ### `init`
25
25
 
26
- Scaffolds `foundrykit.config.json`, installs the utility helper, prepares target
26
+ Scaffolds `foundrykit.json` and `foundrykit.lock.json`, installs the utility helper, prepares target
27
27
  directories, and updates package scripts.
28
28
 
29
29
  ```bash
@@ -49,28 +49,116 @@ missing dependencies. Runs interactively when no id is given.
49
49
  foundrykit add [id] [--with-animation] [-p <path>] [-o]
50
50
  ```
51
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
+
52
56
  ### `update`
53
57
 
54
- Reinstalls installed components (omit the id to update all).
58
+ Updates tracked components (omit the id to update all).
55
59
 
56
60
  ```bash
57
- foundrykit update [id] [-o] [-f] [-p <path>]
61
+ foundrykit update [id] [-o] [-f] [--overwrite]
58
62
  ```
59
63
 
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`)
68
+
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.
75
+
60
76
  ### `doctor`
61
77
 
62
78
  Checks project health: `package.json`, Next.js detection, a valid
63
- `foundrykit.config.json`, and registry reachability.
79
+ `foundrykit.json`, `foundrykit.lock.json`, and registry reachability.
64
80
 
65
81
  ```bash
66
82
  foundrykit doctor
67
83
  ```
68
84
 
85
+ ### `upgrade`
86
+
87
+ Finds codemods that apply to this project, lists them, asks which to run,
88
+ rewrites the code, then runs your package manager's install. Codemods ship
89
+ inside the CLI, so run it through `npx` to always get the newest set:
90
+
91
+ ```bash
92
+ npx @foundrykit/cli@latest upgrade [--dry-run] [-y] [--no-install]
93
+ ```
94
+
95
+ Current codemods:
96
+
97
+ - `@foundrykit/advanced-forms-plugin` → `@foundrykit/form-plugin`
98
+ - `@foundrykit/advanced-seo-plugin` → `@foundrykit/seo-plugin`
99
+
100
+ Each swaps the dependency in every `package.json` (new version range, scripts
101
+ too) and rewrites imports, subpaths and admin import-map paths in source,
102
+ docs and styles. `node_modules`, build output, `CHANGELOG.md` and lockfiles
103
+ are left alone. It warns before touching a repo with uncommitted changes, and
104
+ running it twice changes nothing. Afterwards, Payload sites should run
105
+ `payload generate:importmap`. `advancedSeoPlugin` still works as a deprecated
106
+ alias of `seoPlugin`, so it isn't renamed.
107
+
108
+ ## Foundry hub
109
+
110
+ `login`, `link`, `connect`, `connections` and `provision` talk to the Foundry
111
+ hub, which holds the provider credentials and creates a project's GitHub repo,
112
+ Sentry project and Dokploy services.
113
+
114
+ ```bash
115
+ foundrykit login [--hub <url>] [--no-browser] # device flow; approve the code in the hub
116
+ foundrykit whoami
117
+ foundrykit link <org>/<project> [--hub <url>] # writes hub.project (and hub.url) to foundrykit.json
118
+ foundrykit connect <github|dokploy|sentry> [--owner <o>] [--label <l>] [--token-stdin] [--config k=v ...]
119
+ foundrykit connections # connections you can see and which one the linked project resolves to
120
+ foundrykit provision [--dry-run] [--yes] [--adopt] [--push | --no-push]
121
+ foundrykit logout [--hub <url>]
122
+ ```
123
+
124
+ `provision` shows the plan, asks (or needs `--yes`), applies it on the hub,
125
+ then, if the project has no `origin` remote, asks whether to add
126
+ `https://github.com/<repo>.git` as `origin` and push `HEAD:prod`. Pushing to
127
+ `prod` deploys. `--yes` answers yes to both questions, so it also adds the
128
+ remote and pushes; `--no-push` skips the push, `--push` pushes without
129
+ asking. An existing `origin` is left alone, and outside a git repo the push is
130
+ skipped with the commands to run.
131
+
132
+ **Hub URL**, first match wins: `--hub` (login, logout, link),
133
+ `FOUNDRYKIT_HUB_URL`, `hub.url` in `foundrykit.json`, then
134
+ `https://foundrykit.dokploy.umisites.com`. Trailing slashes are ignored. A cloned repo can set
135
+ `hub.url`, so `login` asks before signing in to a hub URL that only comes
136
+ from `foundrykit.json` (default No); without a TTY or with `--json` it
137
+ refuses, and you pass `--hub <url>` instead. `connect` names the hub it sends
138
+ the token to. Plain `http://` to anything but localhost prints a warning.
139
+
140
+ **Credentials** are saved to `~/.foundrykit/credentials.json` (mode `0600`),
141
+ one entry per hub URL. `logout` removes the entry.
142
+
143
+ **Scripts and agents**: every hub command takes `--json` (one JSON document on
144
+ stdout; errors are `{ "error": { "code", "message" } }`, same exit codes).
145
+ Nothing prompts without a TTY. Tokens are never flags: pass them on stdin.
146
+
147
+ ```bash
148
+ printf %s "$TOKEN" | foundrykit connect sentry --token-stdin --config org=umi --config team=web --json
149
+ foundrykit provision --yes --json
150
+ ```
151
+
69
152
  ## Notes
70
153
 
71
154
  - The CLI currently targets Next.js projects.
72
- - Installation paths and the registry URL are controlled by
73
- `foundrykit.config.json`.
155
+ - Installation paths and the registry URL are controlled by `foundrykit.json`.
156
+ - `foundrykit.lock.json` records installed components and a fingerprint of each
157
+ installed file. Commit both files.
158
+ - Projects with the old `foundrykit.config.json` migrate automatically on the
159
+ next `add`, `update` or `init --force` (no network needed); the legacy file is
160
+ deleted. `doctor` reports a pending migration; `doctor` and
161
+ `list` never write.
74
162
 
75
163
  ## License
76
164