fimo 0.2.1 → 0.2.2
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 +55 -305
- package/dist/cli/bundle.json +2 -2
- package/package.json +1 -1
- package/templates/react-router/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,344 +1,94 @@
|
|
|
1
|
-
|
|
1
|
+
<p align="center">
|
|
2
|
+
<a href="https://fimo.ai">
|
|
3
|
+
<img src="https://fimo.ai/favicon-orange-apple-touch-icon.png" height="80" alt="Fimo" />
|
|
4
|
+
</a>
|
|
5
|
+
</p>
|
|
2
6
|
|
|
3
|
-
Fimo
|
|
7
|
+
<h3 align="center">Fimo</h3>
|
|
4
8
|
|
|
5
|
-
|
|
6
|
-
- `fimo/ui` — React runtime (providers, components, `useTranslations`).
|
|
7
|
-
- `fimo/vite` — Vite plugin that composes Fimo's build-time plugins and auto-regenerates the schema/form TS clients.
|
|
9
|
+
<p align="center">Make your website autonomous.</p>
|
|
8
10
|
|
|
9
|
-
|
|
11
|
+
<p align="center">
|
|
12
|
+
Build your site with any coding agent — Fimo owns everything after the build:
|
|
13
|
+
content, editing, environments, and hosting.
|
|
14
|
+
</p>
|
|
10
15
|
|
|
11
|
-
|
|
12
|
-
// package.json (scaffolded by `fimo create`)
|
|
13
|
-
{
|
|
14
|
-
"scripts": {
|
|
15
|
-
"dev": "vite",
|
|
16
|
-
"build": "vite build",
|
|
17
|
-
"preview": "vite preview",
|
|
18
|
-
},
|
|
19
|
-
"dependencies": { "fimo": "^0.0.1", "react": "...", "react-router": "..." },
|
|
20
|
-
"devDependencies": { "vite": "...", "oxlint": "...", "typescript": "..." },
|
|
21
|
-
}
|
|
22
|
-
```
|
|
23
|
-
|
|
24
|
-
```ts
|
|
25
|
-
// vite.config.ts
|
|
26
|
-
import { defineConfig } from 'vite';
|
|
27
|
-
import { fimo } from 'fimo/vite';
|
|
28
|
-
export default defineConfig({ plugins: [fimo()] });
|
|
29
|
-
```
|
|
30
|
-
|
|
31
|
-
```ts
|
|
32
|
-
// src/main.tsx
|
|
33
|
-
import { AppRoutesProvider } from 'fimo/ui';
|
|
34
|
-
```
|
|
35
|
-
|
|
36
|
-
The vite plugin:
|
|
16
|
+
---
|
|
37
17
|
|
|
38
|
-
|
|
39
|
-
- Registers the SEO, data-id, overlay, preview-script, and translations plugins.
|
|
40
|
-
- Watches `src/{schemas,forms}/**/*.json` and regenerates the corresponding `.ts` clients on change. No separate prebuild script needed.
|
|
18
|
+
## Usage
|
|
41
19
|
|
|
42
|
-
|
|
20
|
+
Install the CLI:
|
|
43
21
|
|
|
44
|
-
```
|
|
45
|
-
|
|
46
|
-
pnpm -F fimo start -- <command>
|
|
47
|
-
# e.g.
|
|
48
|
-
pnpm -F fimo start -- login
|
|
49
|
-
pnpm -F fimo start -- create my-site
|
|
50
|
-
pnpm -F fimo start -- deploy --publish
|
|
51
|
-
pnpm -F fimo start -- invite
|
|
52
|
-
pnpm -F fimo start -- referral link
|
|
53
|
-
pnpm -F fimo start -- referral stats
|
|
22
|
+
```bash
|
|
23
|
+
npm i -g fimo
|
|
54
24
|
```
|
|
55
25
|
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
```sh
|
|
59
|
-
# from the monorepo root
|
|
60
|
-
pnpm install-cli
|
|
61
|
-
```
|
|
62
|
-
|
|
63
|
-
That one command:
|
|
64
|
-
|
|
65
|
-
1. Builds the CLI (three-way tsc build for `dist/{cli,ui,vite,scripts}`).
|
|
66
|
-
2. Makes `apps/cli/dist/cli/index.js` executable.
|
|
67
|
-
3. Creates a symlink at `~/.local/bin/fimo` pointing at the built entry.
|
|
68
|
-
4. Warns if `~/.local/bin` is not on your `PATH`.
|
|
69
|
-
|
|
70
|
-
Add `~/.local/bin` to your shell rc if the script warned you:
|
|
71
|
-
|
|
72
|
-
```sh
|
|
73
|
-
export PATH="$HOME/.local/bin:$PATH"
|
|
74
|
-
```
|
|
75
|
-
|
|
76
|
-
Verify:
|
|
77
|
-
|
|
78
|
-
```sh
|
|
79
|
-
fimo --help
|
|
80
|
-
```
|
|
81
|
-
|
|
82
|
-
After that `fimo create my-site`, `fimo deploy`, etc. work from any directory.
|
|
83
|
-
|
|
84
|
-
> The symlink points at the built entry inside the monorepo, so after `git pull` just re-run `pnpm install-cli` (or `pnpm -F cli build`) to refresh — the symlink itself stays valid.
|
|
85
|
-
|
|
86
|
-
### Why this works anywhere
|
|
87
|
-
|
|
88
|
-
- The **project template** lives at `apps/cli/templates/<framework>/` (currently just `react-router/`) and the **`.claude/` starter** lives under `apps/cli/assets/agents-starter/`. The CLI resolves both relative to its own file location (via `import.meta.url`, see `apps/cli/src/runtime/templates.ts`). There is no cross-package runtime path — `fimo` needs nothing outside the CLI package.
|
|
89
|
-
- The scaffolded homepage is intentionally a single-page starter so `fimo create` produces something visible and editable immediately, rather than a blank screen.
|
|
90
|
-
- That homepage is intentionally disposable. Real generations should replace its content/style instead of iterating on the default Fimo-branded design. Run `fimo check-starter` against a generated project to catch leaked starter copy.
|
|
91
|
-
|
|
92
|
-
## Previewing the scaffold without `fimo create`
|
|
93
|
-
|
|
94
|
-
- The source for the scaffolded project is checked in at `apps/cli/templates/react-router/`, so you can inspect the exact files that `fimo create` copies without creating a project first.
|
|
95
|
-
- There is not currently a dedicated one-command preview flow for that template inside the monorepo. To render it as a website, you still need to run the template itself or scaffold a project from it.
|
|
96
|
-
|
|
97
|
-
## Environment variables
|
|
98
|
-
|
|
99
|
-
| Variable | Default | Purpose |
|
|
100
|
-
| -------------- | ----------------------- | -------------------------------------------------------------------------------------------- |
|
|
101
|
-
| `FIMO_API_URL` | `http://localhost:3000` | Base URL of the Fimo HTTP API (management + tenant). Point at staging/prod to test remotely. |
|
|
102
|
-
| `FIMO_WEB_URL` | `http://localhost:5173` | Base URL of the Fimo web app. The login flow opens `<FIMO_WEB_URL>/auth/cli` in the browser. |
|
|
103
|
-
|
|
104
|
-
### Pointing the CLI at another environment (staging, prod, preview)
|
|
105
|
-
|
|
106
|
-
Export both vars before running any command so login, API calls, and the browser callback all target the same environment:
|
|
107
|
-
|
|
108
|
-
```sh
|
|
109
|
-
export FIMO_API_URL="<staging-api-base-url>"
|
|
110
|
-
export FIMO_WEB_URL="<staging-web-base-url>"
|
|
26
|
+
Log in and scaffold a new project:
|
|
111
27
|
|
|
28
|
+
```bash
|
|
112
29
|
fimo login
|
|
113
|
-
fimo create my-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
Credentials are scoped per-backend (hashed on `apiUrl`). `fimo login` writes to `~/.config/fimo/credentials/<host>-<hash>.json`; switching `FIMO_API_URL` and re-running `fimo login` writes a fresh slot without disturbing the old one.
|
|
117
|
-
|
|
118
|
-
## Active organization
|
|
119
|
-
|
|
120
|
-
`fimo login` automatically persists your personal org (or the first org you belong to) as the **active organization** in `credentials.json`. `fimo create` uses it — no prompt.
|
|
121
|
-
|
|
122
|
-
To switch:
|
|
123
|
-
|
|
124
|
-
```sh
|
|
125
|
-
fimo switch
|
|
126
|
-
```
|
|
127
|
-
|
|
128
|
-
`fimo whoami` prints the currently active organization. `fimo create --org <id>` still works for one-off overrides.
|
|
129
|
-
|
|
130
|
-
## Envs (M07 — branch = env)
|
|
131
|
-
|
|
132
|
-
Every project has one or more **envs** (`main`, `feat/seo`, `release/v1.4.2`, …). Each `fimo` command auto-targets the env from the **current git branch**, falling back to `main` when there's no branch:
|
|
133
|
-
|
|
134
|
-
```sh
|
|
135
|
-
git checkout feat/seo
|
|
136
|
-
fimo cms entries list BlogPost # → env: feat/seo (from git branch)
|
|
137
|
-
|
|
138
|
-
git checkout main
|
|
139
|
-
fimo cms entries list BlogPost # → env: main (from git branch)
|
|
140
|
-
```
|
|
141
|
-
|
|
142
|
-
A `release/<tag>` checkout maps to the well-known `prod` shorthand and is **read-only** — mutating commands refuse to run:
|
|
143
|
-
|
|
144
|
-
```sh
|
|
145
|
-
git checkout release/v1.4.2
|
|
146
|
-
fimo cms entries create BlogPost --body '{...}' # ✗ refuses (read-only env 'prod')
|
|
147
|
-
fimo cms entries list BlogPost # ok (read-only)
|
|
148
|
-
```
|
|
149
|
-
|
|
150
|
-
### Override with `--env <name>`
|
|
151
|
-
|
|
152
|
-
The `--env` root flag overrides the auto-target for one invocation:
|
|
153
|
-
|
|
154
|
-
```sh
|
|
155
|
-
fimo --env staging cms entries list BlogPost
|
|
156
|
-
fimo --env release/v1 cms entries get BlogPost the-launch-day
|
|
30
|
+
fimo create my-site
|
|
31
|
+
cd my-site
|
|
157
32
|
```
|
|
158
33
|
|
|
159
|
-
|
|
34
|
+
`fimo create` sets up the project, pushes the first commit, and wires it to your Fimo account. Open it in your coding agent and start building.
|
|
160
35
|
|
|
161
|
-
|
|
162
|
-
→ env: staging (from --env)
|
|
163
|
-
```
|
|
164
|
-
|
|
165
|
-
Behind the scenes the CLI sends `X-Fimo-Env: <env>` on every request; the server's `resolveEnv` middleware picks it up. Branch and override names are validated client-side against the canonical regex (`/^[a-zA-Z0-9._/-]+$/`, ≤255 chars).
|
|
166
|
-
|
|
167
|
-
### Common errors
|
|
168
|
-
|
|
169
|
-
| Error | Hint |
|
|
170
|
-
| ------------------------------------------------------- | ----------------------------------------------------------------------------- |
|
|
171
|
-
| `You are not in a Fimo project.` | `cd` into a directory containing `.fimo.settings.json`, or run `fimo create`. |
|
|
172
|
-
| `In a git repository but no branch could be detected …` | Detached HEAD — `git checkout main` or pass `--env <name>`. |
|
|
173
|
-
| `--env value '...' is invalid` | Env names must match `/^[a-zA-Z0-9._/-]+$/` and not start with `-`. |
|
|
174
|
-
| `Env '...' not found on the server.` | `fimo branch` to list envs; `fimo branch <name>` to create one. |
|
|
175
|
-
|
|
176
|
-
## Git-shaped CLI (M08)
|
|
177
|
-
|
|
178
|
-
The `fimo` command set mirrors git's shape — same verbs, multi-surface semantics:
|
|
179
|
-
|
|
180
|
-
```sh
|
|
181
|
-
fimo branch # list envs (current marked with *)
|
|
182
|
-
fimo branch -v # + show archived + preview URLs
|
|
183
|
-
fimo branch feat/seo # create env off current
|
|
184
|
-
fimo branch -d feat/old # archive (refuses if unmerged)
|
|
185
|
-
fimo branch -D feat/old # force-delete
|
|
186
|
-
fimo branch -m feat/typo feat/fixed # rename
|
|
187
|
-
|
|
188
|
-
fimo checkout feat/seo # switch env + git branch
|
|
189
|
-
fimo checkout -b feat/new # create + switch
|
|
190
|
-
|
|
191
|
-
fimo switch feat/seo # alias for `fimo checkout`
|
|
192
|
-
fimo organizations switch # (the old `fimo switch` org switcher moved here)
|
|
193
|
-
|
|
194
|
-
fimo pull # sync current env from parent
|
|
195
|
-
fimo pull --from main # explicit parent override
|
|
196
|
-
|
|
197
|
-
fimo diff # current vs main, across all surfaces
|
|
198
|
-
fimo diff feat/seo main # explicit
|
|
199
|
-
fimo diff --surface schemas # filter to one surface
|
|
200
|
-
fimo diff --surface code # drops to `git diff` locally
|
|
201
|
-
fimo diff --json # raw JSON for pipes/agents
|
|
202
|
-
|
|
203
|
-
fimo merge feat/seo # multi-surface merge (refuses on main)
|
|
204
|
-
fimo merge feat/seo --allow-direct-merge # override the protected-flow gate
|
|
205
|
-
fimo merge feat/seo -y # parent-wins for every conflict
|
|
206
|
-
|
|
207
|
-
fimo status # the showcase: 8 surfaces in one report
|
|
208
|
-
fimo status --short # one line per surface
|
|
209
|
-
fimo status --vs main # explicit comparison target
|
|
210
|
-
fimo status --code --content # surface filters (any combo)
|
|
211
|
-
fimo status --json # raw JSON
|
|
212
|
-
|
|
213
|
-
fimo publish --version 1.4.2 # tag release/v1.4.2 + trigger prod swap
|
|
214
|
-
|
|
215
|
-
fimo agents list # (M13 stub — full impl lands with the agent system)
|
|
216
|
-
```
|
|
217
|
-
|
|
218
|
-
### Surfaces
|
|
219
|
-
|
|
220
|
-
Every multi-surface command spans the same 8 surfaces in the same canonical order:
|
|
221
|
-
|
|
222
|
-
```
|
|
223
|
-
code · schemas · content · translations · routes · assets · forms · activations
|
|
224
|
-
```
|
|
225
|
-
|
|
226
|
-
The renderer prints them grouped, with `+` (added) / `-` (removed) / `~` (changed) / `!` (conflict) glyphs and a dim summary line per section. Each surface check has a 2 s soft timeout — a slow surface renders as `(surface check timed out)` and the rest of the report still draws.
|
|
36
|
+
## AI coding tools
|
|
227
37
|
|
|
228
|
-
|
|
38
|
+
Fimo ships skills and rules for your AI coding tools (Claude Code, Cursor, Codex, Gemini, and more) so the agent knows how to work in a Fimo project. `fimo create` installs them for you — add or refresh them any time:
|
|
229
39
|
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
### `NO_COLOR` / `--no-color`
|
|
233
|
-
|
|
234
|
-
The CLI honors the [NO_COLOR](https://no-color.org/) standard. Every multi-surface command also accepts a per-invocation `--no-color` flag for piping into tools that don't strip ANSI escapes.
|
|
235
|
-
|
|
236
|
-
## Inviting users
|
|
237
|
-
|
|
238
|
-
`fimo invite` opens an interactive flow that mirrors the UI sharing dialogs:
|
|
239
|
-
|
|
240
|
-
- choose whether to invite someone to an **organization** or a **project**
|
|
241
|
-
- enter the invitee email
|
|
242
|
-
- pick the organization role (`member`, `admin`, `owner`) or project access level (`view`, `comment`, `edit`, `full`)
|
|
243
|
-
|
|
244
|
-
Examples:
|
|
245
|
-
|
|
246
|
-
```sh
|
|
247
|
-
# interactive
|
|
248
|
-
fimo invite
|
|
249
|
-
|
|
250
|
-
# invite to the active organization
|
|
251
|
-
fimo invite --target organization --email jane@acme.com --role admin
|
|
252
|
-
|
|
253
|
-
# invite to the current project from .fimo.settings.json
|
|
254
|
-
fimo invite --target project --email jane@acme.com --role edit
|
|
255
|
-
|
|
256
|
-
# invite to a specific project
|
|
257
|
-
fimo invite --target project --project <projectId> --email jane@acme.com --role full
|
|
40
|
+
```bash
|
|
41
|
+
fimo skills install
|
|
258
42
|
```
|
|
259
43
|
|
|
260
|
-
##
|
|
44
|
+
## Local development
|
|
261
45
|
|
|
262
|
-
|
|
46
|
+
A Fimo project is a standard Vite app — run it like any other:
|
|
263
47
|
|
|
264
|
-
```
|
|
265
|
-
|
|
48
|
+
```bash
|
|
49
|
+
npm install
|
|
50
|
+
npm run dev
|
|
266
51
|
```
|
|
267
52
|
|
|
268
|
-
|
|
53
|
+
Manage content, schemas, media, and translations from the CLI:
|
|
269
54
|
|
|
270
|
-
```
|
|
271
|
-
|
|
55
|
+
```bash
|
|
56
|
+
fimo schemas push # sync your content models
|
|
57
|
+
fimo entries list # browse content
|
|
58
|
+
fimo assets upload <file> # add media (or `fimo assets generate` with AI)
|
|
59
|
+
fimo translations list # manage locales
|
|
272
60
|
```
|
|
273
61
|
|
|
274
|
-
##
|
|
62
|
+
## Deploying
|
|
275
63
|
|
|
276
|
-
|
|
64
|
+
Push your current environment and refresh its preview:
|
|
277
65
|
|
|
278
|
-
```
|
|
279
|
-
fimo
|
|
66
|
+
```bash
|
|
67
|
+
fimo deploy -m "your message"
|
|
280
68
|
```
|
|
281
69
|
|
|
282
|
-
|
|
283
|
-
|
|
284
|
-
- total referrals
|
|
285
|
-
- signed up referrals
|
|
286
|
-
- activated referrals
|
|
287
|
-
- AI credits earned
|
|
288
|
-
|
|
289
|
-
## Publishing a test tarball (R2)
|
|
70
|
+
Go live to production:
|
|
290
71
|
|
|
291
|
-
|
|
292
|
-
|
|
293
|
-
```sh
|
|
294
|
-
# from apps/cli
|
|
295
|
-
pnpm publish-cli
|
|
296
|
-
# or from anywhere:
|
|
297
|
-
pnpm -F fimo publish-cli
|
|
72
|
+
```bash
|
|
73
|
+
fimo publish --version 1.0.0
|
|
298
74
|
```
|
|
299
75
|
|
|
300
|
-
|
|
301
|
-
|
|
302
|
-
1. `pnpm -F fimo build` → compiles TS and refreshes the bundled template.
|
|
303
|
-
2. `pnpm pack` → produces `apps/cli/fimo-<version>.tgz` (~175 KB).
|
|
304
|
-
3. `wrangler r2 object put` → uploads it to `r2://<bucket>/cli/fimo-<version>.tgz` **and** `r2://<bucket>/cli/fimo-latest.tgz`.
|
|
305
|
-
|
|
306
|
-
### Env vars
|
|
307
|
-
|
|
308
|
-
| Variable | Default | Purpose |
|
|
309
|
-
| ----------------------- | --------------- | -------------------------- |
|
|
310
|
-
| `FIMO_CLI_R2_BUCKET` | `fimo-cli-test` | Target R2 bucket name |
|
|
311
|
-
| `CLOUDFLARE_API_TOKEN` | — | wrangler auth (standard) |
|
|
312
|
-
| `CLOUDFLARE_ACCOUNT_ID` | — | wrangler account selection |
|
|
313
|
-
|
|
314
|
-
### Overrides
|
|
315
|
-
|
|
316
|
-
```sh
|
|
317
|
-
# different bucket
|
|
318
|
-
FIMO_CLI_R2_BUCKET=fimo-cli-staging pnpm -F fimo publish-cli
|
|
76
|
+
Environments work like git branches:
|
|
319
77
|
|
|
320
|
-
|
|
321
|
-
|
|
78
|
+
```bash
|
|
79
|
+
fimo branch staging # create an environment
|
|
80
|
+
fimo checkout staging # switch to it
|
|
81
|
+
fimo diff staging main # compare two environments
|
|
82
|
+
fimo merge staging # merge one into another
|
|
83
|
+
fimo status # see where things stand
|
|
322
84
|
```
|
|
323
85
|
|
|
324
|
-
|
|
86
|
+
Connect a custom domain:
|
|
325
87
|
|
|
326
|
-
|
|
327
|
-
|
|
328
|
-
```sh
|
|
329
|
-
# always-latest
|
|
330
|
-
npm install -g https://pub-41cdea46386f4b238d8c528c4327dfc1.r2.dev/cli/fimo-latest.tgz
|
|
331
|
-
|
|
332
|
-
# pin a specific version
|
|
333
|
-
npm install -g https://pub-41cdea46386f4b238d8c528c4327dfc1.r2.dev/cli/fimo-0.0.1.tgz
|
|
334
|
-
|
|
335
|
-
fimo --help
|
|
88
|
+
```bash
|
|
89
|
+
fimo domains add example.com
|
|
336
90
|
```
|
|
337
91
|
|
|
338
|
-
|
|
339
|
-
|
|
340
|
-
> `publish-cli` uploads both `cli/fimo-<version>.tgz` and `cli/fimo-latest.tgz` on every run.
|
|
341
|
-
|
|
342
|
-
## Credentials
|
|
92
|
+
## Documentation
|
|
343
93
|
|
|
344
|
-
|
|
94
|
+
Full documentation lives at **[docs.fimo.ai](https://docs.fimo.ai)**. Run `fimo --help` to see every command.
|
package/dist/cli/bundle.json
CHANGED
package/package.json
CHANGED