@tideworthy/tidysites 0.1.10 → 0.1.12

package/README.md

@@ -22,8 +22,9 @@ nothing else; it lives in `.tidysites/key`, which is kept out of git.
 | `tidysites status` | what changed here since the pull |
 | `tidysites validate` | every file against the content model, with the file and the field in each message |
 | `tidysites push [--prune] [--force] [--dry] [--only pages]` | validate, then write the created and updated entries back (with `--prune`, delete the entries whose files are gone), then pull |
-| `tidysites shot <path or url> [--mobile] [--tablet] [--desktop] [--wide] [--all] [--first-screen] [--live]` | a screenshot of a page of the preview site, the live site, or any address, saved under `.tidysites/shots/`; none of the width flags means desktop and mobile; a port compares all four. A page taller than 2400px comes in 1600px bands (`<name>-band-01.jpg`, …), top to bottom, that an image reader can take in one at a time |
-| `tidysites measure <path or url> [--mobile] [--tablet] [--desktop] [--wide] [--all] [--full]` | the page as the browser lays it out: every heading, paragraph, button, picture and section box with its computed type (size, line height, weight, family, colour) and box (position, size, padding, margin, background), saved as JSON under `.tidysites/measures/` and printed. Measure the old page and the new one at the same width and style to the numbers |
+| `tidysites shot <path or url> [--mobile] [--tablet] [--desktop] [--wide] [--all] [--first-screen] [--live]` | a screenshot of a page of the preview site, the live site, or any address, saved under `.tidysites/shots/`; none of the width flags means desktop and mobile; a port compares all four. A page taller than 2400px comes in 1600px bands (`<name>-band-01.jpg`, …), top to bottom, that an image reader can take in one at a time. `--menu` opens every navigation menu (burgers, `<details>`, hover dropdowns) before the capture; `--open a,b` clicks those selectors and `--hover a,b` shows the submenus under them, for a popup, a tab or one dropdown |
+| `tidysites measure <path or url> [--mobile] [--tablet] [--desktop] [--wide] [--all] [--full]` | the page as the browser lays it out: every heading, paragraph, button, picture and section box with its computed type (size, line height, weight, family, colour) and box (position, size, padding, margin, background), saved as JSON under `.tidysites/measures/` and printed. Measure the old page and the new one at the same width and style to the numbers. The same `--menu`, `--open` and `--hover` as `shot`, so a dropdown's open type is measured |
+| `tidysites speed <path or url> [--mobile\|--desktop] [--live] [--against <url>]` | PageSpeed Insights (Google's Lighthouse) for a page of the preview or live site, or any address: scores, lab and field metrics, the largest-paint element and the opportunities with the files they name, saved under `.tidysites/speed/`. `--against <url>` tests the old page in the same call for a side-by-side. Run it on the live site before calling a build done; what the content cannot fix goes in the report |
 | `tidysites redirect [add <old path> <new path> \| rm <old path>]` | the website's redirects: an old address that must keep working after a port goes here; they ship with the next publish |
 | `tidysites pages` | every address the website renders |
 | `tidysites page <path> [--html]` | the rendered page, section by section, with the key each section carries |
@@ -59,6 +60,8 @@ out of a file is cleared on the website at the next push. `id` and
 a file you changed and have not pushed; it keeps the file and the difference
 shows in `status`.
 
+Styling: a row's `.css` file is scoped to that row (every rule is prefixed with the row's own selector), so it cannot style the rest of the page; rules for the whole page, the sections and the theme's classes go in `business/business.css`.
+
 Images: an image field, a hero's image or a Columns image slot takes
 `{ "$media": { "url": "https://...", "alt": "what it shows" } }` and the
 push fetches the file into the website's library; a file the library already

package/bin/tidysites.mjs

@@ -7,8 +7,9 @@
  *   status                                    what changed here since the pull
  *   validate                                  check the files against the content model
  *   push [--prune] [--force] [--dry]          write the changes back, then pull
- *   shot <path|url> [--mobile] [--tablet] [--desktop] [--wide] [--all] [--first-screen]   screenshot to .tidysites/shots (none = desktop and mobile); a tall page comes in 1600px bands
- *   measure <path|url> [--mobile] [--tablet] [--desktop] [--wide] [--all] [--full]   the computed type and boxes of a page: the numbers to style to and diff
+ *   shot <path|url> [--mobile] [--tablet] [--desktop] [--wide] [--all] [--first-screen] [--menu] [--open sel,..] [--hover sel,..]   screenshot to .tidysites/shots (none = desktop and mobile); a tall page comes in 1600px bands; --menu opens every navigation menu first
+ *   measure <path|url> [--mobile] [--tablet] [--desktop] [--wide] [--all] [--full] [--menu] [--open sel,..] [--hover sel,..]   the computed type and boxes of a page: the numbers to style to and diff
+ *   speed <path|url> [--mobile|--desktop] [--live] [--against <url>]   PageSpeed Insights for a page, and the old page beside it
  *   redirect [add <old> <new> | rm <old>]      the website's redirects (an old address that must keep working goes here)
  *   pages                                     every address the website renders
  *   page <path> [--html]                      the rendered page, section by section
@@ -189,9 +190,13 @@ async function pull({ dir, cfg }, collections = null, { overwrite = new Set(), m
 	// website's version underneath it, so status shows the difference and a push carries the new stamp.
 	const files = {};
 	const kept = [];
+	const removedHere = readRemoved(dir);
+	const heldBack = [];
 	for (const [collection, entries] of Object.entries(doc.content)) {
 		for (const e of entries) {
 			const key = `${collection}/${e.slug ?? e.id}`;
+			// Removed here with `tidysites rm` and not pruned yet: the website still has it, the folder does not get it back.
+			if (removedHere.has(key) && !overwrite.has(key)) { heldBack.push(key); continue; }
 			const mine = local[key];
 			const was = prev?.entries?.[key];
 			// An entry this push just wrote is the website's now: its file takes the website's version ($media
@@ -244,6 +249,7 @@ async function pull({ dir, cfg }, collections = null, { overwrite = new Set(), m
 	for (const c of doc.collections.filter((c) => c.count)) say(`  ${c.slug.padEnd(20)} ${c.count}`);
 	if (snap.menus) say(`  ${'menus'.padEnd(20)} ${Object.keys(snap.menus).length}`);
 	for (const k of kept) say(`  kept your unpushed changes in ${k}`);
+	if (heldBack.length) say(`  ${heldBack.length} entr${heldBack.length === 1 ? 'y' : 'ies'} you removed here stay removed (the website still has them until \`push --prune\`)`);
 }
 
 /** The menus alone: files and the snapshot's menus, the entries untouched. */
@@ -339,6 +345,8 @@ async function push(ctx) {
 			process.exit(1);
 		}
 		say(`Pushed: ${r.content.created} created, ${r.content.updated} updated${r.images ? `, ${r.images} image${r.images === 1 ? '' : 's'} added` : ''}${r.images_reused ? `, ${r.images_reused} already in the library` : ''}${r.removed ? `, ${r.removed} removed` : ''}.`);
+		// Removed from the website now: the folder stops holding them back.
+		if (removeKeys.length) { const rem = readRemoved(ctx.dir); for (const k of removeKeys) rem.delete(k); writeRemoved(ctx.dir, rem); }
 		if (r.missing?.length) say(`Not found to remove: ${r.missing.map((m) => `${m.collection}/${m.slug}`).join(', ')}`);
 	}
 	for (const name of menus) {
@@ -363,7 +371,7 @@ async function shot(ctx, target = positional[0] ?? '/', opts = {}) {
 	// --desktop, --mobile, --tablet, --wide, any of them together; --all for every width; none = desktop and mobile.
 	const picked = ['desktop', 'mobile', 'tablet', 'wide'].filter((v) => flags[v]);
 	const view = flags.all ? 'all' : picked.length ? picked.join(',') : (opts.view ?? 'both');
-	const args = { site_id: ctx.cfg.site, view, full_page: !(flags['first-screen'] || opts.firstScreen), ...(isUrl ? { url: target } : { path: target, site: flags.live ? 'live' : 'preview' }) };
+	const args = { site_id: ctx.cfg.site, view, full_page: !(flags['first-screen'] || opts.firstScreen), ...openStates(), ...(isUrl ? { url: target } : { path: target, site: flags.live ? 'live' : 'preview' }) };
 	const { json, images } = await tool(ctx.cfg, 'screenshot_website', args);
 	const outDir = join(ctx.dir, META, 'shots');
 	mkdirSync(outDir, { recursive: true });
@@ -382,13 +390,23 @@ async function shot(ctx, target = positional[0] ?? '/', opts = {}) {
 	if (!images.length) say(json ? JSON.stringify(json).slice(0, 500) : 'No image came back.');
 }
 
+/** What a shot or a measure opens first: --menu (every navigation menu), --open <selector,...> (clicked), --hover <selector,...> (their submenus shown). */
+function openStates() {
+	const list = (v) => (v ? String(v).split(',').map((x) => x.trim()).filter(Boolean) : []);
+	const out = {};
+	if (flags.menu) out.menu = true;
+	if (flags.open) out.open = list(flags.open);
+	if (flags.hover) out.hover = list(flags.hover);
+	return out;
+}
+
 /** The computed type and boxes of a page, old or new, at one or several widths: the numbers a port styles to. */
 async function measure(ctx) {
 	const target = positional[0] ?? '/';
 	const isUrl = /^https?:\/\//.test(target);
 	const picked = ['desktop', 'mobile', 'tablet', 'wide'].filter((v) => flags[v]);
 	const view = flags.all ? 'all' : picked.length ? picked.join(',') : 'desktop';
-	const args = { site_id: ctx.cfg.site, view, ...(isUrl ? { url: target } : { path: target, site: flags.live ? 'live' : 'preview' }) };
+	const args = { site_id: ctx.cfg.site, view, ...openStates(), ...(isUrl ? { url: target } : { path: target, site: flags.live ? 'live' : 'preview' }) };
 	const { json } = await tool(ctx.cfg, 'measure_website', args);
 	if (!json?.views) fail('No measurements came back.');
 	const outDir = join(ctx.dir, META, 'measures');
@@ -417,6 +435,39 @@ async function measure(ctx) {
 	}
 }
 
+/** PageSpeed Insights for a page of the website (or any address), and the old page beside it with --against. */
+async function speed(ctx) {
+	const target = positional[0] ?? '/';
+	const isUrl = /^https?:\/\//.test(target);
+	const strategy = flags.mobile && !flags.desktop ? 'mobile' : flags.desktop && !flags.mobile ? 'desktop' : 'both';
+	const args = { site_id: ctx.cfg.site, strategy, ...(isUrl ? { url: target } : { path: target, site: flags.live ? 'live' : 'preview' }), ...(flags.against ? { compare_url: String(flags.against) } : {}) };
+	say(`Testing${flags.against ? ' both pages' : ''} with PageSpeed Insights (a minute or two)...`);
+	const { json } = await tool(ctx.cfg, 'speed_website', args);
+	if (!json?.page) fail('No result came back.');
+	const outDir = join(ctx.dir, META, 'speed');
+	mkdirSync(outDir, { recursive: true });
+	const stamp = new Date().toISOString().replace(/[-:.]/g, '').slice(4, 18);
+	const base = (isUrl ? new URL(target).hostname + new URL(target).pathname : target).replace(/[^a-z0-9]+/gi, '-').replace(/^-|-$/g, '') || 'home';
+	const file = join(outDir, `${base}-${stamp}.json`);
+	writeFileSync(file, JSON.stringify(json, null, '\t'));
+	const n = (v, unit = '') => (v === null || v === undefined ? '—' : `${v}${unit}`);
+	const line = (r) => r.error ? `    ${r.strategy.padEnd(8)} ${r.error}` : `    ${r.strategy.padEnd(8)} perf ${n(r.scores.performance)}  a11y ${n(r.scores.accessibility)}  best ${n(r.scores.best_practices)}  seo ${n(r.scores.seo)}   LCP ${n(r.lab.lcp_ms, 'ms')}  FCP ${n(r.lab.fcp_ms, 'ms')}  TBT ${n(r.lab.tbt_ms, 'ms')}  CLS ${n(r.lab.cls)}  ${r.lab.total_bytes ? Math.round(r.lab.total_bytes / 1024) + ' KB' : '—'} in ${n(r.lab.requests)} requests${r.field ? `   field: LCP ${n(r.field.lcp_ms, 'ms')} INP ${n(r.field.inp_ms, 'ms')} CLS ${n(r.field.cls)} (${r.field.overall})` : ''}`;
+	say(`\n${json.target}`);
+	for (const r of json.page) say(line(r));
+	if (json.compare) { say(`\n${json.compare_url}  (the page it is compared with)`); for (const r of json.compare) say(line(r)); }
+	for (const r of json.page) {
+		if (r.error) continue;
+		say(`\n  ${r.strategy}: what to change`);
+		if (r.lcp_element) say(`    largest paint: ${r.lcp_element.replace(/\s+/g, ' ').slice(0, 160)}`);
+		for (const o of r.opportunities.slice(0, 8)) {
+			say(`    • ${o.title}${o.savings_ms ? ` (${o.savings_ms} ms)` : ''}${o.savings_kb ? ` (${o.savings_kb} KB)` : ''}`);
+			for (const it of o.items.slice(0, 4)) say(`        ${it}`);
+		}
+		for (const d of r.diagnostics.slice(0, 8)) say(`    · ${d}`);
+	}
+	say(`\nSaved to ${relative(process.cwd(), file)}. Full reports: ${json.page.filter((r) => !r.error).map((r) => r.report_url).join('  ')}`);
+}
+
 /** The website's redirects: list them, add one, remove one. They ship with the next publish. */
 async function redirect(ctx) {
 	const sub = positional[0];
@@ -556,12 +607,21 @@ function rmCmd({ dir }) {
 				const f = join(colDir, `${sl}.${ext}`);
 				if (existsSync(f)) { rmSync(f); hit = true; }
 			}
-			if (hit) { removed++; say(`- ${collection}/${sl}`); } else say(`${collection}/${sl}: no such entry file`);
+			if (hit) { removed++; say(`- ${collection}/${sl}`); rememberRemoved(dir, `${collection}/${sl}`); } else say(`${collection}/${sl}: no such entry file`);
 		}
 	}
 	say(`${removed} entr${removed === 1 ? 'y' : 'ies'} removed from the folder; \`tidysites push --prune\` removes them from the website.`);
 }
 
+/**
+ * Entries removed here and not yet pruned from the website. A pull (the one after a failed push included) does not
+ * write them back; `push --prune` removes them from the website and forgets them. The list lives beside the snapshot.
+ */
+const REMOVED_FILE = 'removed.json';
+function readRemoved(dir) { return new Set(readJson(join(dir, META, REMOVED_FILE)) ?? []); }
+function writeRemoved(dir, set) { writeFileSync(join(dir, META, REMOVED_FILE), JSON.stringify([...set].sort(), null, '\t')); }
+function rememberRemoved(dir, key) { const s = readRemoved(dir); s.add(key); writeRemoved(dir, s); }
+
 async function publish(ctx) {
 	if (!flags.yes) fail('Publishing makes the live site a copy of the preview site. Look at it first (`tidysites shot /`), then run `tidysites publish --yes`.');
 	// A website live on the client's own domain is never published from here: the website refuses (409 live_domain) and says who may.
@@ -616,6 +676,8 @@ async function main() {
 		}
 		case 'measure':
 			return measure(config());
+		case 'speed':
+			return speed(config());
 		case 'redirect':
 		case 'redirects':
 			return redirect(config());

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tideworthy/tidysites",
-  "version": "0.1.10",
+  "version": "0.1.12",
   "description": "Pull a Tidysites website to files, edit, validate against its content model, push it back, screenshot the result.",
   "type": "module",
   "bin": {