@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.
@@ -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");
@@ -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;