@unbase-app/cli 0.2.0 → 0.4.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/AGENTS.md CHANGED
@@ -1,10 +1,11 @@
1
1
  # Unbase in a site: the steps for an agent or a developer
2
2
 
3
3
  `npx @unbase-app/cli init` adds what a fixed change can add: the packages, their lines in the
4
- framework's config, and the files they need. What is left needs judgement about this site's code,
5
- and is yours. You add code. You never move or rewrite the site's content: Unbase edits a text where
6
- it is written, in a page, a component or a content file, so moving text into JSON gains nothing and
7
- risks the site.
4
+ framework's config, the files they need, and the analytics collector (`https://unbase.app`) in the
5
+ Content-Security-Policy of `vercel.json` and `public/_headers`. What is left needs judgement about
6
+ this site's code, and is yours. You add code. You never move or rewrite the site's content: Unbase
7
+ edits a text where it is written, in a page, a component or a content file, so moving text into
8
+ JSON gains nothing and risks the site.
8
9
 
9
10
  ## Your framework's steps
10
11
 
@@ -31,7 +32,31 @@ These are conventions, not an Unbase runtime: everything the steps ask for is pl
31
32
  framework that a developer would write, it renders the same with or without Unbase, and you can
32
33
  follow it while a site is first written.
33
34
 
35
+ ## Renaming, duplicating and deleting pages
36
+
37
+ Don't move, copy or delete a page by hand: use the CLI, which does it by Unbase's own rule and so
38
+ makes exactly the changes Unbase's editor would (the page's files, the links to it, its route
39
+ file, `unbase.pages.json`).
40
+
41
+ ```bash
42
+ npx @unbase-app/cli page list # what each page can do here, and why not
43
+ npx @unbase-app/cli page rename /funding /financiering [--name "Financiering"] [--not-live]
44
+ npx @unbase-app/cli page duplicate /pricing [/pricing-2027] [--name "Pricing 2027"]
45
+ npx @unbase-app/cli page delete /old-offer [--redirect /pricing | --not-found] [--not-live]
46
+ ```
47
+
48
+ - Run it with `--dry-run --json` first; it writes the files in the working tree and commits nothing.
49
+ - A page counts as live unless you pass `--not-live` (only for a page that was never on the live
50
+ site). A live page renamed or deleted leaves a redirect in `unbase.pages.json`; never write
51
+ that redirect into the framework's config yourself, and never remove one.
52
+ - A refusal exits 1 with its reason and what it means. `no_redirects`: the site's Unbase package
53
+ is too old to apply redirects; run `npx @unbase-app/cli init` to update it, never `--not-live`
54
+ for a page that was live. `content_bound`, `unparsed`: leave it to a person or Unbase's Operator.
55
+ - `unlinked` lists files that still name a deleted page's address (a link built at runtime, or one
56
+ the rule leaves alone): change those by hand where the site's text allows it.
57
+
34
58
  ## Leaving
35
59
 
36
- `npx @unbase-app/cli uninstall` takes out what init added, after the drafts are published or deleted, and
37
- compares every built page before and after.
60
+ `npx @unbase-app/cli uninstall` takes out what init added, after the drafts are published or deleted
61
+ and the redirects in `unbase.pages.json` are in the site's own config, and compares every built
62
+ page before and after.
package/README.md CHANGED
@@ -6,6 +6,7 @@ Adds [Unbase](https://unbase.app) to an Astro, Vite + React or Next.js site, che
6
6
  npx @unbase-app/cli init # the framework's package, its line in its config, comment-modus.json
7
7
  npx @unbase-app/cli doctor # per feature: on, or what is missing, where, and how to fix it
8
8
  npx @unbase-app/cli uninstall # all of it out again; the built pages compared before and after
9
+ npx @unbase-app/cli page … # rename, duplicate or delete a page, as Unbase's editor does
9
10
  ```
10
11
 
11
12
  Always with the package's name: the unscoped `unbase` on npm is another product's package, so a
@@ -13,9 +14,11 @@ bare `npx @unbase-app/cli` outside a site that has this CLI installed would fetc
13
14
 
14
15
  Unbase works on a connected site without any of this: the canvas, comments on the canvas,
15
16
  publishing, and visual editing (on Astro, nothing installed). What has to live in the site's own
16
- code is what this adds: comments on the live site (`?comment`), and page management (draft pages
17
- kept off Live, page and site settings). The packages change how the site is edited and built, never
18
- how it renders, and nothing here calls Unbase.
17
+ code is what this adds: comments on the live site (`?comment`), page management (draft pages
18
+ kept off Live, page and site settings), and analytics (Unbase's beacon, a pageview from every page
19
+ of a production build, no cookies). The packages change how the site is edited and built, never
20
+ how it renders, but for the beacon's script, which renders nothing. The CLI itself never calls
21
+ Unbase.
19
22
 
20
23
  Astro, Vite + React with React Router as a library (what Lovable makes: *Vite + React*, below),
21
24
  and Next.js; each framework's own steps are in `agents/<framework>.md`. Node 18.17 or newer for the
@@ -42,7 +45,7 @@ the framework's own file, [`agents/astro.md`](./agents/astro.md) or
42
45
  | Flag | |
43
46
  |---|---|
44
47
  | `--comments` / `--no-comments` | Comments on the live site, with `?comment` (`@jens4m/comment-modus`, inside `@unbase-app/astro`). Default: in, or as the site has it when Unbase is in it already |
45
- | `--project <id or slug>` | Link comment mode to an Unbase project now (see *Linking*) |
48
+ | `--project <id or slug>` | Link comment mode and analytics to an Unbase project now (see *Linking*) |
46
49
  | `--pointer[=AGENTS.md\|CLAUDE.md]` / `--no-pointer` | One line in the site's `AGENTS.md` (or `CLAUDE.md`) pointing its agent at this package's `AGENTS.md`. Default: no |
47
50
  | `--no-install` | Write `package.json` only; install yourself |
48
51
  | `--tarballs <dir>` | Install the packages from `npm pack` tarballs in `<dir>`, for testing a release before it is on npm |
@@ -54,7 +57,7 @@ versions:
54
57
 
55
58
  | Package | Version | |
56
59
  |---|---|---|
57
- | `@unbase-app/astro` | 0.1.0 | Unbase in an Astro site, one integration: comment mode (`@jens4m/comment-modus` 1.9.0: comments on the live site; it writes the content schemas Unbase reads) and the draft-pages kit (`@unbase-app/pages` 0.3.0: draft pages kept out of production builds) |
60
+ | `@unbase-app/astro` | 0.3.0 | Unbase in an Astro site, one integration: comment mode (`@jens4m/comment-modus` 1.9.0: comments on the live site; it writes the content schemas Unbase reads), the draft-pages kit (`@unbase-app/pages` 0.4.0: draft pages kept out of production builds, and the redirects a moved page leaves applied) and the analytics beacon (`@unbase-app/analytics` 0.1.0) |
58
61
  | `@unbase-app/cli` | this one | devDependency: `AGENTS.md` and `doctor`, pinned |
59
62
 
60
63
  In `astro.config`, found and changed through its syntax tree, never by text substitution:
@@ -81,7 +84,7 @@ second run changes nothing. It touches no content.
81
84
 
82
85
  ### Vite + React
83
86
 
84
- One package, `@unbase-app/vite` (a devDependency, beside `vite`), at 0.1.0: the draft-pages kit and
87
+ One package, `@unbase-app/vite` (a devDependency, beside `vite`), at 0.3.0: the draft-pages kit, the analytics beacon and
85
88
  comment mode's loader in one Vite plugin. In `vite.config`, through its syntax tree (Lovable's
86
89
  `defineConfig(({ mode }) => ({ … }))` and `plugins: [ … ].filter(Boolean)` included):
87
90
 
@@ -99,7 +102,7 @@ Unbase reads and writes as it is; it has no page settings, so nothing is written
99
102
 
100
103
  ### Next.js
101
104
 
102
- On a Next.js site `init` adds `@unbase-app/next` and wraps the config `next.config` hands Next.js in
105
+ On a Next.js site `init` adds `@unbase-app/next` (0.3.0) and wraps the config `next.config` hands Next.js in
103
106
  `withUnbase(…)` (through its syntax tree; a CommonJS config gets the `require`), writes
104
107
  `comment-modus.json`, and on a Next.js from 15.3 to 16.2 imports the comments' loader in
105
108
  `instrumentation-client.ts` (from 16.3 `withUnbase` injects it). `doctor` builds with `next build`
@@ -108,11 +111,32 @@ into the site's own `.next` and reads it; page settings need nothing installed (
108
111
  `uninstall` takes it all out and compares the prerendered pages, with Next.js's scripts and hashed
109
112
  asset names left out. The steps: [`agents/next.md`](./agents/next.md).
110
113
 
114
+ ### Analytics
115
+
116
+ The beacon comes with the framework's package, on by default (`@unbase-app/analytics`): every page
117
+ of a production build sends a pageview to Unbase once the site is linked, never in a dev server.
118
+ `analytics: false` in the package's call (`unbase({ … })`, `withUnbase(nextConfig, { … })`) leaves
119
+ it out; init never writes that, and keeps it when a site has it.
120
+
121
+ What init adds for it is the collector's origin, `https://unbase.app`, in `connect-src` wherever
122
+ the site sets a Content-Security-Policy it can edit safely: `vercel.json`'s `headers` and
123
+ `public/_headers` (Netlify, Cloudflare Pages), each value changed in place and the rest of the file
124
+ as it was; with no `connect-src`, one made of `default-src`'s sources and the origin. A CSP set
125
+ anywhere else (next.config's `headers()`, a middleware, a `<meta http-equiv>`, `netlify.toml`,
126
+ Astro's `csp` option) is named in `next` and `csp.elsewhere`, never edited. `uninstall` takes the
127
+ origin out of the two files again, to the letter. The reading and the editing are Unbase's own
128
+ (`lib/readers.mjs`, `csp`), the same code `read_install` uses for its Analytics row.
129
+
130
+ On Astro and Vite the package reads `comment-modus.json` itself, so `--no-comments` still writes
131
+ it for analytics, and `--project` links analytics alone. On Next.js the beacon comes with the
132
+ comments' client module: one link for both, and `--no-comments` leaves both out.
133
+
111
134
  ### Linking
112
135
 
113
- comment mode needs the site's Unbase project, which a site added before Unbase knows it does not
114
- have yet. So init writes `comment-modus.json` with `"project": null`, and the config only turns
115
- comment mode on once that file names the project: until then the site builds and renders as before.
136
+ comment mode and analytics need the site's Unbase project, which a site added before Unbase knows it
137
+ does not have yet. So init writes `comment-modus.json` with `"project": null`, and the config only
138
+ turns comment mode (and analytics) on once that file names the project: until then the site builds
139
+ and renders as before.
116
140
  Unbase fills the value in when the site is connected (one JSON value, never a change to the
117
141
  config), or `init --project <id>` does. `comment-modus.json` is the same file comment-modus's own
118
142
  CLI reads.
@@ -159,8 +183,10 @@ and per check what is missing, the file, and the step in `agents/astro.md` that
159
183
  Features: **Visual editing** (Astro, the site builds), **Comments on the site** (the package, its
160
184
  line, the link, the markers, the loader), **Page management** (the kit, the drafts in
161
185
  `unbase.pages.json`, the kit running in a production build, the content schemas, the route files
162
- and the site settings and that the layout reads them). `--no-build` skips the build and what needs
163
- it.
186
+ and the site settings and that the layout reads them), **Analytics** (the package at a version that
187
+ brings it, not `analytics: false`, the link, before Next.js 16.3 the client module's import, and the
188
+ CSP of `vercel.json` and `public/_headers` allowing `https://unbase.app`; a CSP set elsewhere is
189
+ named as `info`). `--no-build` skips the build and what needs it.
164
190
 
165
191
  The markers are comment mode's `data-c`: a pin on the live site takes its title and source file
166
192
  from them, so with comments they belong in the production build. A site without comment mode, or
@@ -171,10 +197,13 @@ an older comment-modus that ignores `"preview"`.
171
197
  ## `unbase uninstall`
172
198
 
173
199
  Refuses while `unbase.pages.json` holds a draft, and lists them: without the kit a draft is built
174
- and goes live, so each is published or deleted in Unbase first. Then it builds the site, removes
200
+ and goes live, so each is published or deleted in Unbase first. It refuses too while the file
201
+ sends old addresses on (`redirects`, left by renaming or deleting a live page), and lists them:
202
+ only the package applies them, so they go into the site's own redirects first. Then it builds the site, removes
175
203
  the packages, their lines in `astro.config`, `comment-modus.json`, `unbase.pages.json`,
176
- `src/content/.schemas/` and the pointer line, builds again, and compares every page's HTML. Taken
177
- out first: comment mode's markers and loader, and what differs between any two builds (asset
204
+ `src/content/.schemas/`, the collector in the CSP of `vercel.json` and `public/_headers`, and the
205
+ pointer line, builds again, and compares every page's HTML. Taken out first: comment mode's markers
206
+ and loader, the analytics beacon, and what differs between any two builds (asset
178
207
  hashes, Astro's ids, white space, attribute order). When pages still differ it builds the after
179
208
  state once more, and what differs between those two builds (an id a component makes at random on
180
209
  every render) is noise, not a change. "No differences in the built pages" is the pass. `--yes` without
@@ -182,6 +211,54 @@ a terminal; `--no-build` skips the comparison; `--no-install` writes `package.js
182
211
 
183
212
  The route files, the settings file and the layout's reads stay: they are the site's own code.
184
213
 
214
+ ## `unbase page`
215
+
216
+ Renames, duplicates and deletes a page by the kit's own rule (`planPage` in `@unbase-app/pages`'s
217
+ core, bundled here), so the files change exactly as they do when Unbase's editor does it: the
218
+ same files always give the same changes. It writes them in the working tree and commits nothing;
219
+ review them with `git diff` and commit them yourself.
220
+
221
+ ```bash
222
+ npx @unbase-app/cli page rename /funding /financiering --name Financiering
223
+ npx @unbase-app/cli page duplicate /pricing /pricing-2027
224
+ npx @unbase-app/cli page delete /old-offer --redirect /pricing
225
+ npx @unbase-app/cli page list
226
+ ```
227
+
228
+ | Command | |
229
+ |---|---|
230
+ | `page rename <from> <to> [--name <name>] [--not-live]` | A new address: the page's files move (on Next.js its folder, on React Router the route's `path`), every quoted link to it or below it in code and content follows, its route file's `pad` too, and the pages under it come along. `--name` sets its name in Unbase (`<to>` the same as `<from>`: only the name) |
231
+ | `page duplicate <path> [<to>] [--name <name>]` | A copy, by default at the first free `<path>-copy`, with its own copy of what only the page owns (its modules and content); a draft where the kit is installed. Named "… (copy)" when the original has a name |
232
+ | `page delete <path> [--redirect <to> \| --not-found] [--not-live]` | Its file and what only it owns; shared parts stay. The links to it are listed, not changed. Visitors to the old address go to the page above it, `--redirect`'s page, or with `--not-found` nowhere |
233
+ | `page list [--not-live]` | Per page: whether it can be renamed, duplicated and deleted here, and if not, why |
234
+
235
+ Every one takes `--dry-run` (print the changes, write nothing), `--json` and `--dir`.
236
+
237
+ **Live pages.** A page counts as live unless `--not-live` says it was never on the live site. A
238
+ live page renamed or deleted leaves a redirect in `unbase.pages.json` (old address → new), which
239
+ the framework's package applies at build from `@unbase-app/astro` 0.3.0, `@unbase-app/vite` 0.3.0
240
+ and `@unbase-app/next` 0.3.0 on (`@unbase-app/pages` 0.4.0). On a site with an older one, or none,
241
+ a live rename or delete is refused (`no_redirects`) instead of breaking the old address: run
242
+ `unbase init` to update, or pass `--not-live` for a page that never was live.
243
+
244
+ **Refusals** exit 1 with the reason and what it means (`--json`: `reason`, `detail`, `message`):
245
+
246
+ | Reason | |
247
+ |---|---|
248
+ | `home` | Home can be duplicated, not renamed or deleted |
249
+ | `nested` | Delete: pages are under it; delete those first |
250
+ | `taken` | The new address is a page already, or the site's own redirects send it on |
251
+ | `address` | Not an address the page can have (plain segments, not under itself), or `--redirect` is not a page |
252
+ | `no_redirects` | A live page leaves a redirect, and this site's build does not apply them (above) |
253
+ | `content_bound` | Duplicate: its content is a collection of its own, and a copy needs code the kit does not write. Unbase's Operator can do it |
254
+ | `content_unregistered` | It reads content by a name no content file goes by |
255
+ | `template` | The page is made by a dynamic route: change it where its data is |
256
+ | `unparsed` | The kit cannot trace the page's route to its file |
257
+ | `missing` | The code makes no page at this address |
258
+ | `same` | Nothing to change |
259
+ | `invalid` | `unbase.pages.json` is not valid |
260
+ | `framework` | Not Astro, Next.js or Vite + React Router |
261
+
185
262
  ## For programs
186
263
 
187
264
  - **Never asks without a terminal.** A choice without its flag is an error (exit 2) naming the
@@ -189,14 +266,23 @@ The route files, the settings file and the layout's reads stay: they are the sit
189
266
  - **`--json`** on every command. `init`: `packages` (name, the pinned `version`, dev, and `action`:
190
267
  `added`, `updated` with `from` and `to`, or `kept`, with a `note` when the one there is newer)
191
268
  and `files` (file, `created`, `changed` or `removed`, and the changes; the lockfile too when
192
- the package manager ran). `doctor`: `features`, each
269
+ the package manager ran); `analytics` (on, unless the config says `analytics: false`) and `csp`
270
+ (`files` it allowed the collector in, `invalid` ones it could not read, and `elsewhere`: each
271
+ `{ file, why }` that may set a CSP it does not edit). `doctor`: `features`, each
193
272
  with `state` (`on`, `off`, `waiting`, `not-installed`) and `checks` (`id`, `state`, `message`,
194
273
  and for a `missing` or `waiting` check `missing`, `file`, `step`). `uninstall`: `files`
195
274
  (every file it touched, the lockfile included), `packages`, `comparison` (`pages`,
196
- `differences`, `secondBuild`), or `refused: "drafts"` with `drafts`.
275
+ `differences`, `secondBuild`), or `refused: "drafts"` with `drafts`, or `refused: "redirects"`
276
+ with `redirects`. `page`: `files` (each
277
+ `path` and `action`: `created`, `changed`, `moved` or `copied` with `from`, or `deleted`),
278
+ `links` (files whose links it rewrote), `unlinked` (files that still name the old address),
279
+ `redirects` (what changed in `unbase.pages.json`: source → destination, `null` for one that
280
+ went), `moves` (the addresses), `dryRun`; refused: `reason`, `detail`, `message`. `page list`:
281
+ `pages`, each with `rename`, `duplicate` and `delete` as `{ ok }` or `{ ok: false, reason }`,
282
+ and `redirects` (whether the site's build applies them).
197
283
  An error: `{ ok: false, exitCode: 2, error: { code, message, file? } }`.
198
284
  - **Exit codes:** `0` passed, `1` failed (doctor found something missing; uninstall refused or
199
- found a difference), `2` could not run (usage, no Astro site, a config it cannot edit safely, an
285
+ found a difference; a page action refused), `2` could not run (usage, no Astro site, a config it cannot edit safely, an
200
286
  install that failed).
201
287
  - **No login, no project, no network** beyond the package manager's install: it never calls Unbase,
202
288
  and the versions are pinned.
package/agents/astro.md CHANGED
@@ -141,7 +141,22 @@ Nothing to add: `unbase()` brings the kit, which keeps every page Unbase marks a
141
141
  cannot. It runs after every other integration by itself; don't add `unbasePages()` beside it. A page
142
142
  that cannot be a draft (a dynamic route, a page another file imports) is fine; doctor lists them.
143
143
 
144
- ## 6. Check
144
+ ## 6. Analytics
145
+
146
+ Nothing to add for the beacon itself: the package brings it, on by default, and every page of a
147
+ production build sends a pageview to Unbase once the site is linked to its project (no cookies,
148
+ nothing stored on the visitor's device; never in the dev server). `analytics: false` in `unbase({ … })`
149
+ leaves it out; keep that only if the site's owner asked for it.
150
+
151
+ What can stop it is the site's own **Content-Security-Policy**: the beacon posts to
152
+ `https://unbase.app`, so a CSP needs that origin in `connect-src` (or in `default-src` when there
153
+ is no `connect-src`). `init` adds it where the site sets the CSP in `vercel.json` (its `headers`) or
154
+ `public/_headers`, and doctor checks both. A CSP set anywhere else (next.config's `headers()`, a
155
+ middleware, a `<meta http-equiv>`, `netlify.toml`, Astro's own `csp` option) is yours: doctor names the file; add
156
+ `https://unbase.app` to its `connect-src`, and change nothing else in it.
157
+ The beacon is bundled with the site's own page scripts, so `script-src` needs nothing new.
158
+
159
+ ## 7. Check
145
160
 
146
161
  `npx @unbase-app/cli doctor` builds the site once and says, per feature, what Unbase will say:
147
162
 
@@ -151,12 +166,14 @@ that cannot be a draft (a dynamic route, a page another file imports) is fine; d
151
166
  `componentMarker: "preview"` in `unbase()`).
152
167
  - **Page management**: the kit, the drafts, the route files and the site settings, and that the
153
168
  layout reads them.
169
+ - **Analytics**: the package new enough, not `analytics: false`, the link to a project, and the
170
+ CSP allowing `https://unbase.app`.
154
171
 
155
172
  `missing` is yours to fix. `waiting` is outside this repository (Unbase linking the project, a
156
173
  package release) and does not fail the run. Then commit on a new branch.
157
174
 
158
175
  ## Leaving
159
176
 
160
- `npx @unbase-app/cli uninstall` takes out what init added, after the drafts are published or deleted, and
161
- compares every built page before and after. The route files, the settings file and the layout's
177
+ `npx @unbase-app/cli uninstall` takes out what init added (the collector in the CSP too), after the drafts
178
+ are published or deleted, and compares every built page before and after. The route files, the settings file and the layout's
162
179
  reads stay: they are the site's own code and keep working.
package/agents/next.md CHANGED
@@ -95,7 +95,25 @@ a draft is fine; doctor lists them with the reason:
95
95
 
96
96
  Drafts need Next.js 15.4 or later (the check after the compile).
97
97
 
98
- ## 5. Check
98
+ ## 5. Analytics
99
+
100
+ Nothing to add for the beacon itself: the package brings it, on by default, and every page of a
101
+ production build sends a pageview to Unbase once the site is linked to its project (no cookies,
102
+ nothing stored on the visitor's device; never in the dev server). `analytics: false` in `withUnbase(nextConfig, { analytics: false })`
103
+ leaves it out; keep that only if the site's owner asked for it.
104
+
105
+ What can stop it is the site's own **Content-Security-Policy**: the beacon posts to
106
+ `https://unbase.app`, so a CSP needs that origin in `connect-src` (or in `default-src` when there
107
+ is no `connect-src`). `init` adds it where the site sets the CSP in `vercel.json` (its `headers`) or
108
+ `public/_headers`, and doctor checks both. A CSP set anywhere else (next.config's `headers()`, a
109
+ middleware, a `<meta http-equiv>`, `netlify.toml`) is yours: doctor names the file; add
110
+ `https://unbase.app` to its `connect-src`, and change nothing else in it.
111
+ The beacon comes with the comments' client module (step 2), so it needs the same link to a project
112
+ and, before Next.js 16.3, the same import in `instrumentation-client`: on Next.js, a site without
113
+ comments on the live site has no analytics either. It is bundled into the site's own chunks, so
114
+ `script-src` needs nothing new.
115
+
116
+ ## 6. Check
99
117
 
100
118
  `npx @unbase-app/cli doctor` builds the site once and says, per feature, what Unbase will say:
101
119
 
@@ -104,6 +122,8 @@ Drafts need Next.js 15.4 or later (the check after the compile).
104
122
  loader on the page and in the build.
105
123
  - **Page management**: the package, the drafts, `withUnbase` running in a production build, which
106
124
  pages can be drafts, and which pages' settings Unbase can set.
125
+ - **Analytics**: the package new enough, not `analytics: false`, the link to a project, the client
126
+ module on the page, and the CSP allowing `https://unbase.app`.
107
127
 
108
128
  `missing` is yours to fix. `waiting` is outside this repository (Unbase linking the project, a
109
129
  package release) and does not fail the run. Then commit on a new branch.
@@ -87,7 +87,23 @@ puts a few lines in `index.html` that load comment mode only with `?comment`, an
87
87
  values where the site is built, `PUBLIC_SUPABASE_URL` and `PUBLIC_SUPABASE_ANON_KEY`; Unbase sets
88
88
  them on Vercel when the site is connected there. Do not put them in the repository.
89
89
 
90
- ## 5. Check
90
+ ## 5. Analytics
91
+
92
+ Nothing to add for the beacon itself: the package brings it, on by default, and every page of a
93
+ production build sends a pageview to Unbase once the site is linked to its project (no cookies,
94
+ nothing stored on the visitor's device; never in the dev server). `analytics: false` in `unbase({ … })`
95
+ leaves it out; keep that only if the site's owner asked for it.
96
+
97
+ What can stop it is the site's own **Content-Security-Policy**: the beacon posts to
98
+ `https://unbase.app`, so a CSP needs that origin in `connect-src` (or in `default-src` when there
99
+ is no `connect-src`). `init` adds it where the site sets the CSP in `vercel.json` (its `headers`) or
100
+ `public/_headers`, and doctor checks both. A CSP set anywhere else (next.config's `headers()`, a
101
+ middleware, a `<meta http-equiv>`, `netlify.toml`) is yours: doctor names the file; add
102
+ `https://unbase.app` to its `connect-src`, and change nothing else in it.
103
+ The beacon is an inline script in the built `index.html`, as comment mode's loader is: a CSP without
104
+ `'unsafe-inline'` in `script-src` needs the script's hash there.
105
+
106
+ ## 6. Check
91
107
 
92
108
  `npx @unbase-app/cli doctor` builds the site once (production, with `vite build` into a folder of its own)
93
109
  and says, per feature, what Unbase will say:
@@ -97,6 +113,8 @@ and says, per feature, what Unbase will say:
97
113
  files in the build.
98
114
  - **Page management**: the kit, the drafts, the pages Unbase finds in the router, and the site
99
115
  settings in `index.html`.
116
+ - **Analytics**: the package new enough, not `analytics: false`, the link to a project, and the
117
+ CSP allowing `https://unbase.app`.
100
118
 
101
119
  `missing` is yours to fix. `waiting` is outside this repository (Unbase linking the project, a
102
120
  package release) and does not fail the run. Then commit on a new branch.
package/bin/unbase.mjs CHANGED
@@ -6,6 +6,11 @@
6
6
  // [--no-install] [--tarballs <dir>] [--yes] [--json] [--dir <path>]
7
7
  // unbase doctor [--no-build] [--json] [--dir <path>]
8
8
  // unbase uninstall [--yes] [--no-build] [--no-install] [--json] [--dir <path>]
9
+ // unbase page rename <from> <to> [--name <name>] [--not-live]
10
+ // duplicate <path> [<to>] [--name <name>]
11
+ // delete <path> [--redirect <to> | --not-found] [--not-live]
12
+ // list [--not-live]
13
+ // [--dry-run] [--json] [--dir <path>]
9
14
  //
10
15
  // Exit codes: 0 passed, 1 failed, 2 could not run. Never asks without a
11
16
  // terminal: a choice without its flag is an error. Never calls Unbase.
@@ -17,6 +22,7 @@ import { COULD_NOT_RUN, CouldNotRun } from "../lib/errors.mjs";
17
22
  import { FRAMEWORKS } from "../lib/frameworks/index.mjs";
18
23
  import { init } from "../lib/init.mjs";
19
24
  import { parseArgs } from "../lib/args.mjs";
25
+ import { page } from "../lib/page.mjs";
20
26
  import { uninstall } from "../lib/uninstall.mjs";
21
27
  import { SELF } from "../lib/versions.mjs";
22
28
 
@@ -39,12 +45,24 @@ const USAGE = `unbase ${SELF.version}: Unbase in a site (${FRAMEWORKS.map((f) =>
39
45
  --yes do it without asking
40
46
  --no-build skip the comparison
41
47
  --no-install change package.json only
48
+ unbase page Rename, duplicate or delete a page by the kit's rule, the changes Unbase's
49
+ editor makes; written in the working tree, never committed
50
+ rename <from> <to> a new address (the links and its route file follow)
51
+ duplicate <path> [<to>] a copy, by default at <path>-copy; a draft where the site has drafts
52
+ delete <path> its file and what only it owns; links to it are listed
53
+ list what each page can do here, and why not
54
+ --name <name> the page's name in Unbase (rename, duplicate)
55
+ --redirect <to> | --not-found
56
+ delete: where visitors to the old address go (default: the page
57
+ above it)
58
+ --not-live the page was never on the live site: no redirect is left
59
+ --dry-run print the changes, write nothing
42
60
 
43
61
  All: --json (for programs), --dir <path> (the site's folder; default: here)
44
62
  Exit codes: 0 passed, 1 failed, 2 could not run.
45
63
  After init: node_modules/${SELF.name}/AGENTS.md has the steps left to do.`;
46
64
 
47
- const COMMANDS = { init, doctor, uninstall };
65
+ const COMMANDS = { init, doctor, uninstall, page };
48
66
 
49
67
  function makeIo(json) {
50
68
  const interactive = !json && !!process.stdin.isTTY && !!process.stdout.isTTY;
@@ -104,6 +122,7 @@ function render(r) {
104
122
  out.push("", r.ok ? `Passed: ${s.on} on${s.waiting ? `, ${s.waiting} waiting on something outside this repository` : ""}${s.notInstalled ? `, ${s.notInstalled} not installed` : ""}.` : `Failed: ${s.off} feature(s) need a change in the site.`);
105
123
  } else if (r.command === "uninstall") {
106
124
  if (r.refused === "drafts") out.push(r.message, ...r.drafts.map((d) => ` ${d}`));
125
+ else if (r.refused === "redirects") out.push(r.message, ...Object.entries(r.redirects).map(([from, to]) => ` ${from} → ${to}`));
107
126
  else {
108
127
  for (const f of r.files ?? []) {
109
128
  out.push(` ${f.action} ${f.file}`);
@@ -115,14 +134,45 @@ function render(r) {
115
134
  if (d.before) out.push(` before: …${d.before}…`, ` after: …${d.after}…`);
116
135
  }
117
136
  }
137
+ } else if (r.command === "page") {
138
+ out.push(...renderPage(r));
118
139
  }
119
140
  return out.join("\n");
120
141
  }
121
142
 
143
+ const CHANGE = { created: "+", changed: "~", moved: "→", copied: "+", deleted: "-" };
144
+
145
+ function renderPage(r) {
146
+ const out = [];
147
+ if (r.action === "list") {
148
+ const cell = (c) => (c.ok ? "yes" : `no (${c.reason})`);
149
+ for (const p of r.pages) {
150
+ out.push(`${p.path}${p.name ? ` "${p.name}"` : ""}${p.draft ? " draft" : ""}`);
151
+ out.push(` rename ${cell(p.rename)} · duplicate ${cell(p.duplicate)} · delete ${cell(p.delete)}`);
152
+ }
153
+ out.push("", r.live ? "Every page counted as live (--not-live: as never live)." : "No page counted as live.");
154
+ out.push(
155
+ r.redirects
156
+ ? "This site's build applies the redirects a live rename or delete leaves."
157
+ : `This site's build does not apply redirects yet, so a live page cannot be renamed or deleted with one${r.package ? `: ${r.package} ${r.since} or later does` : ""}.`,
158
+ );
159
+ return out;
160
+ }
161
+ if (!r.ok) return [`unbase page ${r.action} ${r.path}: refused (${r.reason})`, ` ${r.message}`];
162
+ out.push(`${r.message}${r.dryRun ? " (dry run: nothing written)" : ""}`);
163
+ out.push(` files: ${r.files.length}`);
164
+ for (const f of r.files) out.push(` ${CHANGE[f.action] ?? "~"} ${f.path}${f.from ? ` (${f.action} from ${f.from})` : f.action === "deleted" ? " (deleted)" : ""}`);
165
+ if (r.links.length) out.push(` links rewritten: ${r.links.length}`, ...r.links.map((l) => ` ${l}`));
166
+ if (r.unlinked.length) out.push(` links left: ${r.unlinked.length} (they still name ${r.path}; change them yourself)`, ...r.unlinked.map((l) => ` ${l}`));
167
+ const redirects = Object.entries(r.redirects);
168
+ if (redirects.length) out.push(` redirects in unbase.pages.json: ${redirects.length}`, ...redirects.map(([from, to]) => ` ${from} → ${to ?? "(removed)"}`));
169
+ return out;
170
+ }
171
+
122
172
  async function main(argv) {
123
173
  let json = argv.includes("--json");
124
174
  try {
125
- const { command, flags } = parseArgs(argv);
175
+ const { command, flags, args } = parseArgs(argv);
126
176
  if (command === "help") {
127
177
  console.log(USAGE);
128
178
  return 0;
@@ -132,7 +182,7 @@ async function main(argv) {
132
182
  return 0;
133
183
  }
134
184
  json = !!flags.json;
135
- const result = await COMMANDS[command](flags, makeIo(json));
185
+ const result = await COMMANDS[command](flags, makeIo(json), args);
136
186
  console.log(json ? JSON.stringify(result, null, 2) : render(result));
137
187
  return result.exitCode;
138
188
  } catch (e) {
@@ -0,0 +1,142 @@
1
+ // ============================================================================
2
+ // Analytics in the CLI (docs/plan-analytics.md, AN2). Unbase's beacon comes
3
+ // inside each framework's package from the version ANALYTICS_FROM names, on
4
+ // by default, for the project comment-modus.json names; `analytics: false` in
5
+ // the package's call leaves it out. What the CLI adds around it is the site's
6
+ // Content-Security-Policy, with Unbase's own CSP reader (lib/readers.mjs
7
+ // `csp`, the code read_install and an install run use):
8
+ //
9
+ // init the collector's origin added to `connect-src` where the site
10
+ // sets a CSP the CLI can edit safely (vercel.json,
11
+ // public/_headers), and every other place that may set one
12
+ // named, never edited (next.config's headers(), a middleware,
13
+ // a <meta http-equiv>, netlify.toml, Astro's `csp`)
14
+ // uninstall the origin taken out of those two files again
15
+ // doctor a fourth feature, Analytics: the package new enough, not
16
+ // `analytics: false`, the project linked, the CSP allowing the
17
+ // collector
18
+ //
19
+ // The framework modules call these with what they read of their own config.
20
+ // ============================================================================
21
+
22
+ import { check, featureState } from "./feature.mjs";
23
+ import { csp } from "./readers.mjs";
24
+ import { ANALYTICS_FROM, compareVersions, versionIn } from "./versions.mjs";
25
+
26
+ /** The collector's origin, as a CSP allows it. */
27
+ export const COLLECTOR_ORIGIN = csp.COLLECTOR_ORIGIN;
28
+
29
+ /** Where a site's files may set a CSP besides the two the CLI edits: paths worth reading. */
30
+ const MAY_SET = /\.(m?[jt]sx?|c[jt]s|astro|html?|vue|svelte|toml|ya?ml)$/;
31
+
32
+ /** Every other place the site may set a CSP: [{ file, why }], for init and doctor to name. */
33
+ export function cspElsewhereIn(site) {
34
+ const out = [];
35
+ for (const file of site.appPaths) {
36
+ if (!MAY_SET.test(file) || file.includes("node_modules/")) continue;
37
+ const why = csp.cspElsewhere(file, site.text(file));
38
+ if (why) out.push({ file, why });
39
+ }
40
+ return out;
41
+ }
42
+
43
+ /** A policy as a change line names it: the header, and the path it is set for. */
44
+ const named = (p) => `Content-Security-Policy${p.source ? ` for ${p.source}` : ""}`;
45
+
46
+ /**
47
+ * The CSP files as init (`add`) or uninstall leaves them: each one that changes, as
48
+ * { file, action: "changed", changes, text }, and what could not be read (`invalid`). Writes nothing.
49
+ */
50
+ export function planCsp(site, { add }) {
51
+ const files = [];
52
+ const invalid = [];
53
+ for (const file of csp.CSP_FILES) {
54
+ const text = site.text(file);
55
+ if (text === null) continue;
56
+ const read = csp.policiesIn(file, text);
57
+ if (read.invalid) {
58
+ invalid.push(file);
59
+ continue;
60
+ }
61
+ const next = add ? csp.withCollectorIn(file, text) : csp.withoutCollectorIn(file, text);
62
+ if (next === text) continue;
63
+ const after = csp.policiesIn(file, next).policies;
64
+ const changed = read.policies.filter((p, i) => after[i]?.value !== p.value);
65
+ files.push({ file, action: "changed", changes: changed.map((p) => `${named(p)}: connect-src ${add ? "+" : "−"} ${COLLECTOR_ORIGIN}`), text: next });
66
+ }
67
+ return { files, invalid };
68
+ }
69
+
70
+ /** The lines init adds to `next` for the CSPs it found but does not edit. */
71
+ export const elsewhereSteps = (elsewhere) => elsewhere.map((e) => `Allow ${COLLECTOR_ORIGIN} in connect-src in ${e.file} (${e.why}), which sets a Content-Security-Policy the CLI does not edit.`);
72
+
73
+ /**
74
+ * doctor's Analytics feature. `umbrella`: the framework's package { name }; `version`: the one the
75
+ * site has, or null; `configured`: its call is in the config; `option`: its `analytics` option
76
+ * there (true when absent, false, or null when not literal); `project`: the linked project, or null; `before`: a site from before K5 (the
77
+ * pair, no framework package); `step`: the agents file's Analytics step; `install`: its Install
78
+ * step; `config`: the config's file name; `loader`: Next.js before 16.3, whether the client module
79
+ * that brings the beacon is imported (null where not asked).
80
+ */
81
+ export function analyticsFeature(site, { umbrella, version, configured, option, project, before, step, install, config, loader = null }) {
82
+ const checks = [];
83
+ const from = ANALYTICS_FROM[umbrella.name];
84
+ const done = (chose = false) => ({ id: "analytics", name: "Analytics", state: featureState(checks, chose), checks });
85
+
86
+ if (before) {
87
+ checks.push(check("package", "info", `Analytics comes with ${umbrella.name} ${from}: \`npx @unbase-app/cli init\` moves the site across to it.`));
88
+ return done(true);
89
+ }
90
+ if (!version && !configured) {
91
+ checks.push(check("package", "missing", `${umbrella.name} is not a dependency, and analytics comes with it.`, { missing: `${umbrella.name} ${from} or later`, file: "package.json", step: install }));
92
+ return done();
93
+ }
94
+ const have = versionIn(version);
95
+ if (have && compareVersions(have, from) < 0)
96
+ checks.push(check("version", "missing", `${umbrella.name} ${have} has no analytics; ${from} brings it: \`npx @unbase-app/cli init\` updates it.`, { missing: `${umbrella.name} ${from} or later`, file: "package.json", step: install }));
97
+ else if (!configured) checks.push(check("config", "missing", `${config} does not use ${umbrella.name}, which brings analytics.`, { missing: `${umbrella.name}'s line in ${config}`, file: config, step: install }));
98
+ else checks.push(check("package", "ok", `${umbrella.name} ${have ?? version} brings the analytics beacon: a pageview to Unbase from every page of a production build, no cookies.`));
99
+ if (option === false) {
100
+ checks.push(check("option", "info", `${config} says \`analytics: false\`: no beacon. Take the option out to count visits in Unbase.`));
101
+ return done(true);
102
+ }
103
+ if (option === null) checks.push(check("option", "info", `${config} passes options doctor cannot read; \`analytics: false\` among them would leave the beacon out.`));
104
+ if (loader === false) checks.push(check("loader", "missing", `Next.js before 16.3 runs the beacon only when instrumentation-client imports the client module.`, { missing: "the client module's import", file: "instrumentation-client.ts", step }));
105
+
106
+ if (project) checks.push(check("link", "ok", `Counting for the Unbase project "${project}".`));
107
+ else
108
+ checks.push(
109
+ check("link", "waiting", "Not linked to an Unbase project yet, so analytics stays off. Unbase fills in `project` in comment-modus.json when the site is connected; or run `unbase init --project <id or slug>`.", {
110
+ missing: "project in comment-modus.json",
111
+ file: "comment-modus.json",
112
+ }),
113
+ );
114
+
115
+ // The CSP: the two files the CLI edits are read; elsewhere is named.
116
+ let any = false;
117
+ for (const file of csp.CSP_FILES) {
118
+ const text = site.text(file);
119
+ if (text === null) continue;
120
+ const read = csp.policiesIn(file, text);
121
+ if (read.invalid) {
122
+ checks.push(check("csp", "info", `${file} cannot be read as its format, so doctor cannot see whether its Content-Security-Policy allows ${COLLECTOR_ORIGIN}.`, { file }));
123
+ continue;
124
+ }
125
+ for (const p of read.policies) {
126
+ any = true;
127
+ checks.push(
128
+ csp.policyAllows(p.value)
129
+ ? check("csp", "ok", `${file}: the ${named(p)} allows ${COLLECTOR_ORIGIN}.`, { file })
130
+ : check("csp", "missing", `${file}: the ${named(p)} does not allow ${COLLECTOR_ORIGIN} in connect-src, so the browser blocks every pageview. \`npx @unbase-app/cli init\` adds it.`, {
131
+ missing: `${COLLECTOR_ORIGIN} in connect-src`,
132
+ file,
133
+ step,
134
+ }),
135
+ );
136
+ }
137
+ }
138
+ for (const e of cspElsewhereIn(site))
139
+ checks.push(check("csp-elsewhere", "info", `${e.file} may set a Content-Security-Policy (${e.why}), which doctor does not read: allow ${COLLECTOR_ORIGIN} in its connect-src.`, { file: e.file, step }));
140
+ if (!any) checks.push(check("csp", "ok", `No Content-Security-Policy in ${csp.CSP_FILES.join(" or ")}.`));
141
+ return done();
142
+ }