@unbase-app/cli 0.0.0-stage → 0.3.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 +38 -0
- package/LICENSE +21 -0
- package/README.md +239 -2
- package/agents/astro.md +179 -0
- package/agents/next.md +129 -0
- package/agents/vite-react.md +126 -0
- package/bin/unbase.mjs +147 -0
- package/lib/analytics.mjs +142 -0
- package/lib/args.mjs +49 -0
- package/lib/build.mjs +71 -0
- package/lib/compare.mjs +103 -0
- package/lib/config-edit.mjs +634 -0
- package/lib/doctor.mjs +37 -0
- package/lib/errors.mjs +15 -0
- package/lib/feature.mjs +23 -0
- package/lib/frameworks/astro.mjs +535 -0
- package/lib/frameworks/index.mjs +57 -0
- package/lib/frameworks/next.mjs +358 -0
- package/lib/frameworks/vite-react.mjs +329 -0
- package/lib/init.mjs +186 -0
- package/lib/next-config.mjs +142 -0
- package/lib/pm.mjs +109 -0
- package/lib/readers.mjs +2138 -0
- package/lib/site.mjs +153 -0
- package/lib/uninstall.mjs +140 -0
- package/lib/versions.mjs +81 -0
- package/lib/vite-config.mjs +296 -0
- package/package.json +44 -4
|
@@ -0,0 +1,126 @@
|
|
|
1
|
+
# Unbase in a Vite + React site: the steps for an agent or a developer
|
|
2
|
+
|
|
3
|
+
For a single-page app made with Vite, React and React Router as a library (`react-router-dom`, the
|
|
4
|
+
`<Routes>` in `src/App.tsx`), as Lovable makes them. React Router's framework mode
|
|
5
|
+
(`@react-router/dev`, `app/routes.ts`) is another framework, which has no package yet.
|
|
6
|
+
|
|
7
|
+
`npx @unbase-app/cli init` adds what a fixed change can add: the package, its line in
|
|
8
|
+
`vite.config`, and `comment-modus.json`. What is left needs judgement about this site's code, and
|
|
9
|
+
is yours. You add code. You never move or rewrite the site's content: Unbase edits a text where it
|
|
10
|
+
is written, in a page, a component or a data file, so moving text into JSON gains nothing and
|
|
11
|
+
risks the site.
|
|
12
|
+
|
|
13
|
+
Work through the steps, run `npx @unbase-app/cli doctor`, fix what it names, and run it again until it
|
|
14
|
+
passes. Every finding names a file and the step below that fixes it. `doctor --json` gives the
|
|
15
|
+
same as data.
|
|
16
|
+
|
|
17
|
+
These are conventions, not an Unbase runtime: everything here is plain Vite and React that a
|
|
18
|
+
developer would write, it renders the same with or without Unbase, and you can follow it while a
|
|
19
|
+
site is first written.
|
|
20
|
+
|
|
21
|
+
## 1. Install
|
|
22
|
+
|
|
23
|
+
`npx @unbase-app/cli init` (add `--yes` without a terminal). It is safe to run again: a second run
|
|
24
|
+
changes nothing, and a package that is older than the version init pins is moved up to it. It adds:
|
|
25
|
+
|
|
26
|
+
- `@unbase-app/vite` as a devDependency, and `unbase()` last in `plugins` in `vite.config`, with
|
|
27
|
+
`import { unbase } from "@unbase-app/vite"`. One plugin that keeps draft pages out of production
|
|
28
|
+
builds, and turns on comments on the live site with `?comment` once the site is linked.
|
|
29
|
+
`--no-comments` writes `unbase({ comments: false })`.
|
|
30
|
+
- `comment-modus.json` with `"project": null`. Unbase fills in the project when the site is
|
|
31
|
+
connected; until then comment mode stays off. Do not invent a value.
|
|
32
|
+
- `@unbase-app/cli` as a devDependency, so this file and `doctor` are pinned by the lockfile.
|
|
33
|
+
|
|
34
|
+
A site with the draft-pages kit's own plugin (`unbasePages()` from `@jens4m/unbase-pages/vite`)
|
|
35
|
+
gets `unbase()` in its place: `@unbase-app/vite` carries the kit, and two kits in one build would
|
|
36
|
+
stop it. `@jens4m/unbase-pages` is then unused; remove it from `package.json`.
|
|
37
|
+
|
|
38
|
+
If init says it cannot edit `vite.config` safely, make the same change by hand: the import, and
|
|
39
|
+
`unbase()` as the last entry of `plugins`.
|
|
40
|
+
|
|
41
|
+
## 2. Site settings
|
|
42
|
+
|
|
43
|
+
Unbase sets the site's name, description, language, tab icon and share image where a Vite app
|
|
44
|
+
keeps them: as values in the `<head>` of `index.html`. It changes a value in place and nothing
|
|
45
|
+
else. It reads, as plain values written in the file:
|
|
46
|
+
|
|
47
|
+
- `<title>`: the site's name in Unbase. An `og:title` or `twitter:title` with the same text
|
|
48
|
+
follows it.
|
|
49
|
+
- `<meta name="description" content="…">`. `og:description` and `twitter:description` with the
|
|
50
|
+
same text follow it.
|
|
51
|
+
- `<html lang="…">`.
|
|
52
|
+
- one `<link rel="icon" href="…">` (and one with `media="(prefers-color-scheme: dark)"` for the
|
|
53
|
+
dark icon). A new icon is uploaded into `public/`; when the link names a `type`, a picture of
|
|
54
|
+
that type.
|
|
55
|
+
- `<meta property="og:image" content="…">`, with a `twitter:image` that says the same.
|
|
56
|
+
|
|
57
|
+
Nothing to add when `index.html` has them. A setting `index.html` does not have is not offered:
|
|
58
|
+
add the tag with the value the site already uses if you want it settable, never an invented one.
|
|
59
|
+
Keep the values literal: a `%VITE_…%` placeholder, or a head library that sets them at runtime,
|
|
60
|
+
is code Unbase leaves alone.
|
|
61
|
+
|
|
62
|
+
There are no page settings on a single-page app: every route is `index.html`, so a route has no
|
|
63
|
+
`<head>` of its own. Do not add a head library or a per-route settings file for Unbase.
|
|
64
|
+
|
|
65
|
+
## 3. Draft pages
|
|
66
|
+
|
|
67
|
+
Nothing to add when the routes are JSX in the router: `unbase()` keeps every page Unbase marks as a
|
|
68
|
+
draft (in `unbase.pages.json`, which Unbase writes) out of production builds, and stops the build
|
|
69
|
+
when it cannot. Unbase finds a page as
|
|
70
|
+
|
|
71
|
+
```tsx
|
|
72
|
+
<Route path="/pricing" element={<Pricing />} />
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
in a file that imports `react-router-dom` (or `react-router`): a literal `path`, one component in
|
|
76
|
+
`element`, that component imported (or `lazy(() => import(…))`) from its own file. A page that
|
|
77
|
+
cannot be a draft is fine (a dynamic route such as `/blog/:slug`, a page another file imports, a
|
|
78
|
+
route with child routes); doctor lists them. Routes written as objects
|
|
79
|
+
(`createBrowserRouter([{ path, element }])`) are not read: their pages have no draft and no place in
|
|
80
|
+
comment mode's page tree. Do not rewrite a router for Unbase.
|
|
81
|
+
|
|
82
|
+
## 4. Comments on the site
|
|
83
|
+
|
|
84
|
+
Nothing to add. Once Unbase links the site (`comment-modus.json` names the project), every build
|
|
85
|
+
puts a few lines in `index.html` that load comment mode only with `?comment`, and writes
|
|
86
|
+
`version.json` and `comment-modus/pages.json` beside it. Comment mode needs Unbase's two public
|
|
87
|
+
values where the site is built, `PUBLIC_SUPABASE_URL` and `PUBLIC_SUPABASE_ANON_KEY`; Unbase sets
|
|
88
|
+
them on Vercel when the site is connected there. Do not put them in the repository.
|
|
89
|
+
|
|
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
|
|
107
|
+
|
|
108
|
+
`npx @unbase-app/cli doctor` builds the site once (production, with `vite build` into a folder of its own)
|
|
109
|
+
and says, per feature, what Unbase will say:
|
|
110
|
+
|
|
111
|
+
- **Visual editing**: nothing to install on Vite + React; the site has to build.
|
|
112
|
+
- **Comments on the site**: the package, its line, the link to a project, the loader and the two
|
|
113
|
+
files in the build.
|
|
114
|
+
- **Page management**: the kit, the drafts, the pages Unbase finds in the router, and the site
|
|
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`.
|
|
118
|
+
|
|
119
|
+
`missing` is yours to fix. `waiting` is outside this repository (Unbase linking the project, a
|
|
120
|
+
package release) and does not fail the run. Then commit on a new branch.
|
|
121
|
+
|
|
122
|
+
## Leaving
|
|
123
|
+
|
|
124
|
+
`npx @unbase-app/cli uninstall` takes out what init added, after the drafts are published or deleted, and
|
|
125
|
+
compares the built `index.html` before and after. `index.html`'s settings stay as they are: they
|
|
126
|
+
are the site's own.
|
package/bin/unbase.mjs
ADDED
|
@@ -0,0 +1,147 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
// ============================================================================
|
|
3
|
+
// unbase — adds Unbase to a site (Astro, Vite + React, Next.js: lib/frameworks), checks it, and takes it out again.
|
|
4
|
+
//
|
|
5
|
+
// unbase init [--comments | --no-comments] [--project <id>] [--pointer[=FILE] | --no-pointer]
|
|
6
|
+
// [--no-install] [--tarballs <dir>] [--yes] [--json] [--dir <path>]
|
|
7
|
+
// unbase doctor [--no-build] [--json] [--dir <path>]
|
|
8
|
+
// unbase uninstall [--yes] [--no-build] [--no-install] [--json] [--dir <path>]
|
|
9
|
+
//
|
|
10
|
+
// Exit codes: 0 passed, 1 failed, 2 could not run. Never asks without a
|
|
11
|
+
// terminal: a choice without its flag is an error. Never calls Unbase.
|
|
12
|
+
// ============================================================================
|
|
13
|
+
|
|
14
|
+
import { createInterface } from "node:readline/promises";
|
|
15
|
+
import { doctor } from "../lib/doctor.mjs";
|
|
16
|
+
import { COULD_NOT_RUN, CouldNotRun } from "../lib/errors.mjs";
|
|
17
|
+
import { FRAMEWORKS } from "../lib/frameworks/index.mjs";
|
|
18
|
+
import { init } from "../lib/init.mjs";
|
|
19
|
+
import { parseArgs } from "../lib/args.mjs";
|
|
20
|
+
import { uninstall } from "../lib/uninstall.mjs";
|
|
21
|
+
import { SELF } from "../lib/versions.mjs";
|
|
22
|
+
|
|
23
|
+
const USAGE = `unbase ${SELF.version}: Unbase in a site (${FRAMEWORKS.map((f) => f.name).join(", ")})
|
|
24
|
+
|
|
25
|
+
unbase init Add the framework's package (or move it up to the pinned version; a site
|
|
26
|
+
from before 03-11 moves across to it), its line in the framework's config
|
|
27
|
+
(${FRAMEWORKS.map((f) => f.configFiles[0].replace(/\.[a-z]+$/, "")).join(", ")}), and comment-modus.json
|
|
28
|
+
--comments | --no-comments comments on the live site (?comment); default: in, or as the
|
|
29
|
+
site has it
|
|
30
|
+
--project <id or slug> link comment mode to an Unbase project now
|
|
31
|
+
--pointer[=AGENTS.md|CLAUDE.md] | --no-pointer
|
|
32
|
+
a line pointing the site's coding agent at Unbase's conventions
|
|
33
|
+
--no-install change package.json only; install yourself
|
|
34
|
+
--tarballs <dir> install packages from npm pack tarballs in <dir> (testing)
|
|
35
|
+
--yes the defaults for every choice not given
|
|
36
|
+
unbase doctor Check every feature as Unbase will read it
|
|
37
|
+
--no-build skip the production build and the checks that need it
|
|
38
|
+
unbase uninstall Take it all out again, and compare the built pages before and after
|
|
39
|
+
--yes do it without asking
|
|
40
|
+
--no-build skip the comparison
|
|
41
|
+
--no-install change package.json only
|
|
42
|
+
|
|
43
|
+
All: --json (for programs), --dir <path> (the site's folder; default: here)
|
|
44
|
+
Exit codes: 0 passed, 1 failed, 2 could not run.
|
|
45
|
+
After init: node_modules/${SELF.name}/AGENTS.md has the steps left to do.`;
|
|
46
|
+
|
|
47
|
+
const COMMANDS = { init, doctor, uninstall };
|
|
48
|
+
|
|
49
|
+
function makeIo(json) {
|
|
50
|
+
const interactive = !json && !!process.stdin.isTTY && !!process.stdout.isTTY;
|
|
51
|
+
return {
|
|
52
|
+
json,
|
|
53
|
+
interactive,
|
|
54
|
+
progress: (line) => (json ? undefined : process.stderr.write(`${line}\n`)),
|
|
55
|
+
async ask(question, fallback) {
|
|
56
|
+
const rl = createInterface({ input: process.stdin, output: process.stdout });
|
|
57
|
+
try {
|
|
58
|
+
const answer = (await rl.question(`${question} ${fallback ? "[Y/n]" : "[y/N]"} `)).trim().toLowerCase();
|
|
59
|
+
return answer ? answer.startsWith("y") : fallback;
|
|
60
|
+
} finally {
|
|
61
|
+
rl.close();
|
|
62
|
+
}
|
|
63
|
+
},
|
|
64
|
+
};
|
|
65
|
+
}
|
|
66
|
+
|
|
67
|
+
const MARK = { ok: "✓", missing: "✗", waiting: "…", info: "·", skipped: "–" };
|
|
68
|
+
const FEATURE = { on: "On", off: "Off", waiting: "Waiting", "not-installed": "Not installed" };
|
|
69
|
+
|
|
70
|
+
function render(r) {
|
|
71
|
+
const out = [];
|
|
72
|
+
if (r.command === "init") {
|
|
73
|
+
out.push(r.changed ? `Unbase added to ${r.site}` : `Nothing to change: Unbase is already in ${r.site}`);
|
|
74
|
+
for (const p of r.packages) {
|
|
75
|
+
const what =
|
|
76
|
+
p.action === "added"
|
|
77
|
+
? `+ ${p.name} ${p.version}`
|
|
78
|
+
: p.action === "updated"
|
|
79
|
+
? `↑ ${p.name} ${p.from} → ${p.to}`
|
|
80
|
+
: p.action === "removed"
|
|
81
|
+
? `- ${p.name}${p.replacedBy ? ` (replaced by ${p.replacedBy})` : ""}`
|
|
82
|
+
: `= ${p.name} ${p.have} (kept${p.note ? `: ${p.note}` : ""})`;
|
|
83
|
+
out.push(` ${what}${p.dev ? " (dev)" : ""}`);
|
|
84
|
+
}
|
|
85
|
+
for (const f of r.files) {
|
|
86
|
+
out.push(` ${f.action} ${f.file}`);
|
|
87
|
+
for (const c of f.changes) out.push(` ${c}`);
|
|
88
|
+
}
|
|
89
|
+
if (r.comments) out.push(r.project ? ` comments: linked to "${r.project}"` : " comments: waiting for the project (Unbase fills in comment-modus.json when the site is connected)");
|
|
90
|
+
out.push("", "Next:", ...r.next.map((n) => ` - ${n}`));
|
|
91
|
+
} else if (r.command === "doctor") {
|
|
92
|
+
for (const f of r.features) {
|
|
93
|
+
out.push(`${f.name}: ${FEATURE[f.state]}`);
|
|
94
|
+
for (const c of f.checks) {
|
|
95
|
+
out.push(` ${MARK[c.state]} ${c.message}`);
|
|
96
|
+
if (c.state === "missing" || c.state === "waiting") {
|
|
97
|
+
if (c.file) out.push(` file: ${c.file}`);
|
|
98
|
+
if (c.step) out.push(` fix: ${c.step}`);
|
|
99
|
+
}
|
|
100
|
+
if (c.detail && c.state !== "ok") out.push(...String(c.detail).split("\n").map((l) => ` | ${l}`));
|
|
101
|
+
}
|
|
102
|
+
}
|
|
103
|
+
const s = r.summary;
|
|
104
|
+
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
|
+
} else if (r.command === "uninstall") {
|
|
106
|
+
if (r.refused === "drafts") out.push(r.message, ...r.drafts.map((d) => ` ${d}`));
|
|
107
|
+
else {
|
|
108
|
+
for (const f of r.files ?? []) {
|
|
109
|
+
out.push(` ${f.action} ${f.file}`);
|
|
110
|
+
for (const c of f.changes) out.push(` ${c}`);
|
|
111
|
+
}
|
|
112
|
+
out.push("", r.message);
|
|
113
|
+
for (const d of r.comparison?.differences ?? []) {
|
|
114
|
+
out.push(` ${d.page}: ${d.change}`);
|
|
115
|
+
if (d.before) out.push(` before: …${d.before}…`, ` after: …${d.after}…`);
|
|
116
|
+
}
|
|
117
|
+
}
|
|
118
|
+
}
|
|
119
|
+
return out.join("\n");
|
|
120
|
+
}
|
|
121
|
+
|
|
122
|
+
async function main(argv) {
|
|
123
|
+
let json = argv.includes("--json");
|
|
124
|
+
try {
|
|
125
|
+
const { command, flags } = parseArgs(argv);
|
|
126
|
+
if (command === "help") {
|
|
127
|
+
console.log(USAGE);
|
|
128
|
+
return 0;
|
|
129
|
+
}
|
|
130
|
+
if (command === "version") {
|
|
131
|
+
console.log(SELF.version);
|
|
132
|
+
return 0;
|
|
133
|
+
}
|
|
134
|
+
json = !!flags.json;
|
|
135
|
+
const result = await COMMANDS[command](flags, makeIo(json));
|
|
136
|
+
console.log(json ? JSON.stringify(result, null, 2) : render(result));
|
|
137
|
+
return result.exitCode;
|
|
138
|
+
} catch (e) {
|
|
139
|
+
const known = e instanceof CouldNotRun;
|
|
140
|
+
const error = { code: known ? e.code : "internal", message: e.message, ...(known && e.file ? { file: e.file } : {}) };
|
|
141
|
+
if (json) console.log(JSON.stringify({ command: argv[0] ?? null, ok: false, exitCode: COULD_NOT_RUN, error }, null, 2));
|
|
142
|
+
else console.error(`unbase: ${e.message}${known ? "" : `\n${e.stack}`}${error.code === "usage" ? "\n\nRun unbase --help for the commands and flags." : ""}`);
|
|
143
|
+
return COULD_NOT_RUN;
|
|
144
|
+
}
|
|
145
|
+
}
|
|
146
|
+
|
|
147
|
+
process.exitCode = await main(process.argv.slice(2));
|
|
@@ -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
|
+
}
|
package/lib/args.mjs
ADDED
|
@@ -0,0 +1,49 @@
|
|
|
1
|
+
// ============================================================================
|
|
2
|
+
// Flags. Every choice is a flag (`--comments` / `--no-comments`, `--yes`):
|
|
3
|
+
// without a terminal a missing one is an error, never a question. Unknown
|
|
4
|
+
// flags are an error too, so a typo in a script fails instead of being
|
|
5
|
+
// ignored.
|
|
6
|
+
// ============================================================================
|
|
7
|
+
|
|
8
|
+
import { CouldNotRun } from "./errors.mjs";
|
|
9
|
+
|
|
10
|
+
/** Per command: flag → "bool" | "value" | "optional-value". */
|
|
11
|
+
export const FLAGS = {
|
|
12
|
+
init: { comments: "bool", "no-comments": "bool", project: "value", pointer: "optional-value", "no-pointer": "bool", "no-install": "bool", tarballs: "value", yes: "bool", json: "bool", dir: "value" },
|
|
13
|
+
doctor: { json: "bool", "no-build": "bool", dir: "value" },
|
|
14
|
+
uninstall: { yes: "bool", json: "bool", "no-build": "bool", "no-install": "bool", dir: "value" },
|
|
15
|
+
};
|
|
16
|
+
|
|
17
|
+
/** @returns {{ command: string | null, flags: Record<string, string | true> }} */
|
|
18
|
+
export function parseArgs(argv) {
|
|
19
|
+
const [command, ...rest] = argv;
|
|
20
|
+
if (!command || command === "--help" || command === "-h" || command === "help") return { command: "help", flags: {} };
|
|
21
|
+
if (command === "--version" || command === "-v") return { command: "version", flags: {} };
|
|
22
|
+
const known = FLAGS[command];
|
|
23
|
+
if (!known) throw new CouldNotRun("usage", `Unknown command "${command}". Commands: init, doctor, uninstall.`);
|
|
24
|
+
/** @type {Record<string, string | true>} */
|
|
25
|
+
const flags = {};
|
|
26
|
+
for (let i = 0; i < rest.length; i++) {
|
|
27
|
+
const arg = rest[i];
|
|
28
|
+
if (!arg.startsWith("--")) throw new CouldNotRun("usage", `Unexpected argument "${arg}" for ${command}.`);
|
|
29
|
+
const [name, inline] = arg.slice(2).split(/=(.*)/s, 2);
|
|
30
|
+
const kind = known[name];
|
|
31
|
+
if (!kind) throw new CouldNotRun("usage", `Unknown flag --${name} for ${command}. Flags: ${Object.keys(known).map((f) => `--${f}`).join(", ")}.`);
|
|
32
|
+
if (kind === "bool") {
|
|
33
|
+
if (inline !== undefined) throw new CouldNotRun("usage", `--${name} takes no value.`);
|
|
34
|
+
flags[name] = true;
|
|
35
|
+
} else if (inline !== undefined) {
|
|
36
|
+
flags[name] = inline;
|
|
37
|
+
} else if (kind === "value") {
|
|
38
|
+
const next = rest[i + 1];
|
|
39
|
+
if (next === undefined || next.startsWith("--")) throw new CouldNotRun("usage", `--${name} needs a value.`);
|
|
40
|
+
flags[name] = next;
|
|
41
|
+
i++;
|
|
42
|
+
} else {
|
|
43
|
+
flags[name] = true;
|
|
44
|
+
}
|
|
45
|
+
}
|
|
46
|
+
if (flags.comments && flags["no-comments"]) throw new CouldNotRun("usage", "Use --comments or --no-comments, not both.");
|
|
47
|
+
if (flags.pointer && flags["no-pointer"]) throw new CouldNotRun("usage", "Use --pointer or --no-pointer, not both.");
|
|
48
|
+
return { command, flags };
|
|
49
|
+
}
|
package/lib/build.mjs
ADDED
|
@@ -0,0 +1,71 @@
|
|
|
1
|
+
// ============================================================================
|
|
2
|
+
// A production build of the site, as its host would make it, into a folder
|
|
3
|
+
// of our own (so the site's dist/ is left alone), and the HTML it wrote. How
|
|
4
|
+
// is the framework's (frameworks/*.mjs `build`).
|
|
5
|
+
// UNBASE_DEPLOY_CONTEXT=production makes the draft-pages kit treat it as Live
|
|
6
|
+
// whatever the environment says.
|
|
7
|
+
// ============================================================================
|
|
8
|
+
|
|
9
|
+
import { spawnSync } from "node:child_process";
|
|
10
|
+
import { existsSync, mkdtempSync, readdirSync, readFileSync, rmSync } from "node:fs";
|
|
11
|
+
import { tmpdir } from "node:os";
|
|
12
|
+
import { join, relative, sep } from "node:path";
|
|
13
|
+
|
|
14
|
+
function htmlUnder(dir) {
|
|
15
|
+
const out = new Map();
|
|
16
|
+
const walk = (d) => {
|
|
17
|
+
for (const e of readdirSync(d, { withFileTypes: true })) {
|
|
18
|
+
const p = join(d, e.name);
|
|
19
|
+
if (e.isDirectory()) walk(p);
|
|
20
|
+
else if (e.name.endsWith(".html")) out.set(relative(dir, p).split(sep).join("/"), readFileSync(p, "utf8"));
|
|
21
|
+
}
|
|
22
|
+
};
|
|
23
|
+
if (existsSync(dir)) walk(dir);
|
|
24
|
+
return out;
|
|
25
|
+
}
|
|
26
|
+
|
|
27
|
+
/**
|
|
28
|
+
* Builds the site with its own framework. Returns ok, the build's output (for messages), the HTML
|
|
29
|
+
* per file, and the folder (removed by `dispose`).
|
|
30
|
+
*/
|
|
31
|
+
export function buildSite(site, { label = "build" } = {}) {
|
|
32
|
+
const { name, build } = site.framework;
|
|
33
|
+
const bin = join(site.root, "node_modules", ".bin", process.platform === "win32" ? `${build.bin}.cmd` : build.bin);
|
|
34
|
+
if (!existsSync(bin)) return { ok: false, output: `${name} is not installed in node_modules: install the site's dependencies first.`, html: new Map(), dir: null, dispose() {} };
|
|
35
|
+
const dir = mkdtempSync(join(tmpdir(), `unbase-${label}-`));
|
|
36
|
+
const r = spawnSync(bin, build.args(dir), {
|
|
37
|
+
cwd: site.root,
|
|
38
|
+
encoding: "utf8",
|
|
39
|
+
env: { ...process.env, UNBASE_DEPLOY_CONTEXT: "production", ...build.env, FORCE_COLOR: "0", NO_COLOR: "1" },
|
|
40
|
+
maxBuffer: 256 * 1024 * 1024,
|
|
41
|
+
shell: process.platform === "win32",
|
|
42
|
+
});
|
|
43
|
+
const output = `${r.stdout ?? ""}${r.stderr ?? ""}`;
|
|
44
|
+
let html = htmlUnder(dir);
|
|
45
|
+
if (!html.size) for (const alt of build.output ?? []) if (!html.size) html = htmlUnder(join(site.root, alt));
|
|
46
|
+
return {
|
|
47
|
+
ok: r.status === 0,
|
|
48
|
+
output,
|
|
49
|
+
html,
|
|
50
|
+
dir,
|
|
51
|
+
/** Every JS file of the build, for telling what a script tag loads. */
|
|
52
|
+
file: (p) => {
|
|
53
|
+
try {
|
|
54
|
+
return readFileSync(join(dir, p), "utf8");
|
|
55
|
+
} catch {
|
|
56
|
+
return null;
|
|
57
|
+
}
|
|
58
|
+
},
|
|
59
|
+
dispose() {
|
|
60
|
+
rmSync(dir, { recursive: true, force: true });
|
|
61
|
+
},
|
|
62
|
+
};
|
|
63
|
+
}
|
|
64
|
+
|
|
65
|
+
/** The last lines of a build's output, for a message. */
|
|
66
|
+
export const tailOf = (output, n = 15) =>
|
|
67
|
+
output
|
|
68
|
+
.split("\n")
|
|
69
|
+
.filter((l) => l.trim())
|
|
70
|
+
.slice(-n)
|
|
71
|
+
.join("\n");
|
package/lib/compare.mjs
ADDED
|
@@ -0,0 +1,103 @@
|
|
|
1
|
+
// ============================================================================
|
|
2
|
+
// Two builds' pages, compared: what a visitor gets, before and after
|
|
3
|
+
// uninstall. What only the packages put in a page is taken out first (comment
|
|
4
|
+
// mode's markers and its loader scripts, and the analytics beacon), and what
|
|
5
|
+
// differs between any two builds (asset hashes, Astro's scope and island ids,
|
|
6
|
+
// white space, comments). Anything else that differs is a difference.
|
|
7
|
+
// ============================================================================
|
|
8
|
+
|
|
9
|
+
/** comment-modus's loader and the head script that keeps its toolbar across pages carry its name. */
|
|
10
|
+
const COMMENTS = /comment-modus/;
|
|
11
|
+
/** The analytics beacon (@unbase-app/analytics) carries the flag it sets on the window. */
|
|
12
|
+
const BEACON = /__unbaseAnalytics/;
|
|
13
|
+
/** Every script of ours. */
|
|
14
|
+
const OURS = /comment-modus|__unbaseAnalytics/;
|
|
15
|
+
|
|
16
|
+
/**
|
|
17
|
+
* The page without our scripts (`ours`: by default all of them): inline ones that carry the mark
|
|
18
|
+
* always; a script file that carries it only with `files` (Astro may bundle the loader and the
|
|
19
|
+
* beacon with the site's own page scripts into one file, which then stays after uninstall).
|
|
20
|
+
*/
|
|
21
|
+
function withoutOurScripts(html, file, files = true, ours = OURS) {
|
|
22
|
+
return html.replace(/<script\b([^>]*)>([\s\S]*?)<\/script>/g, (whole, attrs, body) => {
|
|
23
|
+
if (ours.test(body)) return "";
|
|
24
|
+
const src = /\bsrc=["']?([^"'\s>]+)/.exec(attrs)?.[1];
|
|
25
|
+
if (files && src && src.startsWith("/") && ours.test(file(src.replace(/^\/+/, "").replace(/[?#].*$/, "")) ?? "")) return "";
|
|
26
|
+
return whole;
|
|
27
|
+
});
|
|
28
|
+
}
|
|
29
|
+
|
|
30
|
+
/** A start tag with its attributes in name order: a minifier that sorts them by how often they occur reorders them once data-c is gone. */
|
|
31
|
+
const TAG = /<([a-zA-Z][\w:-]*)((?:\s+[^\s=>\/"']+(?:\s*=\s*(?:"[^"]*"|'[^']*'|[^\s"'>]+))?)*)\s*(\/?)>/g;
|
|
32
|
+
const ATTR = /([^\s=>\/"']+)(?:\s*=\s*("[^"]*"|'[^']*'|[^\s"'>]+))?/g;
|
|
33
|
+
const sortedAttributes = (html) =>
|
|
34
|
+
html.replace(TAG, (whole, tag, attrs, slash) => {
|
|
35
|
+
if (!attrs?.trim()) return whole;
|
|
36
|
+
const list = [...attrs.matchAll(ATTR)].map((m) => (m[2] === undefined ? m[1] : `${m[1]}=${m[2]}`)).sort();
|
|
37
|
+
return `<${tag} ${list.join(" ")}${slash}>`;
|
|
38
|
+
});
|
|
39
|
+
|
|
40
|
+
export function normalise(html, file = () => null, files = true) {
|
|
41
|
+
return sortedAttributes(withoutOurScripts(html, file, files).replace(/\sdata-c="[^"]*"/g, ""))
|
|
42
|
+
.replace(/<!--[\s\S]*?-->/g, "")
|
|
43
|
+
.replace(/\sdata-astro-cid-[a-z0-9]+(="[^"]*")?/g, "")
|
|
44
|
+
.replace(/data-astro-cid-[a-z0-9]+/g, "data-astro-cid")
|
|
45
|
+
.replace(/\b(astro-island[^>]*?)\s(uid|prefix)="[^"]*"/g, "$1")
|
|
46
|
+
.replace(/(\/_astro\/[^"'\s),?]*?)\.[A-Za-z0-9_-]{6,}\.([a-z0-9]+)/g, "$1.$2")
|
|
47
|
+
.replace(/[ \t\n\r\f]+/g, " ")
|
|
48
|
+
.replace(/> </g, "><")
|
|
49
|
+
.trim();
|
|
50
|
+
}
|
|
51
|
+
|
|
52
|
+
const tokens = (html) => html.split(/([<>"'=\s])/).filter(Boolean);
|
|
53
|
+
|
|
54
|
+
/**
|
|
55
|
+
* Whether `a` equals `b` outside the places where two builds of the same code (`b`, `b2`) differ
|
|
56
|
+
* themselves: an id a component makes at random on every render is noise, not a change.
|
|
57
|
+
*/
|
|
58
|
+
function sameBesideNoise(a, b, b2) {
|
|
59
|
+
const ta = tokens(a);
|
|
60
|
+
const tb = tokens(b);
|
|
61
|
+
const t2 = tokens(b2);
|
|
62
|
+
if (ta.length !== tb.length || tb.length !== t2.length) return false;
|
|
63
|
+
for (let i = 0; i < tb.length; i++) if (ta[i] !== tb[i] && tb[i] === t2[i]) return false;
|
|
64
|
+
return true;
|
|
65
|
+
}
|
|
66
|
+
|
|
67
|
+
/**
|
|
68
|
+
* The pages that differ, with the first place they differ; [] when none. With `again` (a second
|
|
69
|
+
* build of the after state), what differs between the two after builds counts as noise. `pre`: the
|
|
70
|
+
* framework's own normalising, before the shared one (frameworks/*.mjs `normalise`).
|
|
71
|
+
*/
|
|
72
|
+
export function comparePages(before, after, again = null, pre = (html) => html) {
|
|
73
|
+
const diffs = [];
|
|
74
|
+
const paths = [...new Set([...before.html.keys(), ...after.html.keys()])].sort();
|
|
75
|
+
for (const p of paths) {
|
|
76
|
+
const a = before.html.has(p) ? pre(before.html.get(p)) : undefined;
|
|
77
|
+
const b = after.html.has(p) ? pre(after.html.get(p)) : undefined;
|
|
78
|
+
if (a === undefined || b === undefined) {
|
|
79
|
+
diffs.push({ page: p, change: a === undefined ? "only after" : "only before" });
|
|
80
|
+
continue;
|
|
81
|
+
}
|
|
82
|
+
// The loader's script file either goes (it held only the loader) or stays (bundled with the site's own page scripts).
|
|
83
|
+
const nb = normalise(b, after.file);
|
|
84
|
+
const candidates = [normalise(a, before.file, false), normalise(a, before.file)];
|
|
85
|
+
if (candidates.includes(nb)) continue;
|
|
86
|
+
const b2 = again?.html.has(p) ? pre(again.html.get(p)) : undefined;
|
|
87
|
+
if (b2 !== undefined) {
|
|
88
|
+
const n2 = normalise(b2, again.file);
|
|
89
|
+
if (candidates.some((na) => sameBesideNoise(na, nb, n2))) continue;
|
|
90
|
+
}
|
|
91
|
+
const na = candidates[1];
|
|
92
|
+
let i = 0;
|
|
93
|
+
while (i < na.length && na[i] === nb[i]) i++;
|
|
94
|
+
diffs.push({ page: p, change: "changed", before: na.slice(Math.max(0, i - 60), i + 120), after: nb.slice(Math.max(0, i - 60), i + 120) });
|
|
95
|
+
}
|
|
96
|
+
return { pages: paths.length, diffs };
|
|
97
|
+
}
|
|
98
|
+
|
|
99
|
+
/** Whether a page carries comment mode's loader (inline, or in a script file it loads). */
|
|
100
|
+
export const hasOurScript = (html, file = () => null) => withoutOurScripts(html, file, true, COMMENTS) !== html;
|
|
101
|
+
|
|
102
|
+
/** Whether a page carries the analytics beacon (inline, or in a script file it loads). */
|
|
103
|
+
export const hasBeacon = (html, file = () => null) => withoutOurScripts(html, file, true, BEACON) !== html;
|