@foundrykit/cli 2.0.12 → 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
@@ -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,93 @@ 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
+ ## Foundry hub
86
+
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.
90
+
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
+ ```
100
+
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.
123
+
124
+ ```bash
125
+ printf %s "$TOKEN" | foundrykit connect sentry --token-stdin --config org=umi --config team=web --json
126
+ foundrykit provision --yes --json
127
+ ```
128
+
69
129
  ## Notes
70
130
 
71
131
  - The CLI currently targets Next.js projects.
72
- - Installation paths and the registry URL are controlled by
73
- `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.
74
139
 
75
140
  ## License
76
141