@mrkt_frwd/leaf 0.1.0 → 0.1.1

package/README.md

@@ -1,16 +1,67 @@
 # @mrkt_frwd/leaf
 
-Take a self-contained HTML page apart into editable CSS and JS, put it back, and
-prove it is the same file.
+**Take a self-contained HTML page apart into editable CSS and JS, put it back, and
+prove it is the same bytes.**
 
 ```bash
-npx leaf unpack page.html --output-dir ./out
-npx leaf pack ./out --out page.html
-npx leaf check page.html
+npx @mrkt_frwd/leaf unpack page.html --output-dir ./out
+npx @mrkt_frwd/leaf pack ./out --out page.html
 ```
 
-Leaf never rebuilds the document from a parse tree — it cuts block bodies out by
-byte offset and puts them back. Unchanged in, unchanged out, verified against
-every page in the studio. `docs/getting-started.md` has the rest.
+## What it is for
 
-MIT.
+Single-file pages are wonderful to ship and miserable to edit — one 40 KB file
+with the stylesheet, the shaders and the app logic in it. Leaf splits that into
+real files you can open in an editor, and puts it back together byte for byte.
+
+## The claim, and the evidence for it
+
+Run against a real 22,891-byte page:
+
+```
+$ npx @mrkt_frwd/leaf unpack engines/job.html --output-dir ./out
+unpacked job.html → ./out
+sha256 7d3437b28d34…  4 part(s)
+  parts/00-script-importmap.json     104 B
+  parts/01-style.css              7970 B
+  parts/02-script.js              2128 B
+  parts/03-script-module.js       3671 B
+
+$ npx @mrkt_frwd/leaf pack ./out --out rebuilt.html
+packed → rebuilt.html
+sha256 7d3437b28d34…  22891 B
+identical to the source it was unpacked from
+```
+
+Same digest on both ends, confirmed independently with `shasum` and `cmp`.
+
+## Why byte-exact and not "close enough"
+
+A round trip that is *nearly* right is the worst available outcome. It returns a
+page that still loads, still looks plausible, and has quietly lost a newline
+inside a shader or a tab inside a template literal. You find out weeks later.
+
+So Leaf does not re-serialise a parse tree. It records where each block sat and
+what surrounded it, edits nothing, and reassembles from the original shell. And
+it reports the digest rather than a success message — when the bytes do not
+match, it says so instead of claiming victory.
+
+This replaced twenty-one hand-written repack scripts that each failed the same
+way: nearly.
+
+## Commands
+
+```
+leaf unpack <page.html> --output-dir <dir>   take it apart
+leaf pack <dir> [--out <page.html>]          put it back, report the digest
+leaf check <page.html>                       is it genuinely self-contained?
+```
+
+`check` answers a different question worth asking: does this page actually fetch
+nothing from another origin, or does it only look like it?
+
+## Requirements
+
+Node 18+. No dependencies.
+
+MIT © Joe Asare. Built at [Joe Asare Studio](https://joeasare.com).

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@mrkt_frwd/leaf",
-  "version": "0.1.0",
-  "description": "Leaf — take a self-contained HTML page apart into editable CSS and JS, put it back, and prove it is the same file.",
+  "version": "0.1.1",
+  "description": "Leaf \u2014 take a self-contained HTML page apart into editable CSS and JS, put it back, and prove it is the same file.",
   "type": "module",
   "exports": {
     ".": "./src/index.mjs"
@@ -16,5 +16,13 @@
   "engines": {
     "node": ">=20"
   },
-  "license": "MIT"
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mrktfrwd/leaf.git"
+  },
+  "homepage": "https://joeasare.com/engines/leaf",
+  "scripts": {
+    "test": "node src/test-leaf.mjs"
+  }
 }

package/src/test-leaf.mjs

@@ -0,0 +1,87 @@
+#!/usr/bin/env node
+/**
+ * Leaf's promise is narrow and total: unpack a page, change nothing, pack it, get the
+ * same bytes. A round trip that is *nearly* right is the worst possible outcome, so the
+ * tests below recompute the digest from the rebuilt file rather than trusting a
+ * success message the code printed about itself.
+ *
+ *   node src/test-leaf.mjs
+ */
+import assert from 'assert';
+import crypto from 'crypto';
+import { unpack, pack, check, findBlocks } from './index.mjs';
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+
+const fails = [];
+const it = (n, f) => { try { f(); console.log(`  ok  ${n}`); } catch (e) { fails.push(n); console.log(`  FAIL ${n}\n       ${e.message}`); } };
+const sha = (b) => crypto.createHash('sha256').update(b).digest('hex');
+const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'leaf-'));
+
+const PAGE = `<!doctype html>
+<html lang="en"><head><meta charset="utf-8"><title>t</title>
+<style>
+  body { color: red }
+  /* a tab and a trailing space follow:	 */
+</style>
+<script type="importmap">{"imports":{"three":"/x.js"}}</script>
+</head><body><h1>hi</h1>
+<script>
+const s = \`a
+	b \`;
+</script>
+</body></html>`;
+
+console.log('\n  LEAF\n  ----------------------------------');
+
+it('a round trip returns the identical bytes', () => {
+  const src = path.join(tmp, 'p.html');
+  fs.writeFileSync(src, PAGE);
+  const out = path.join(tmp, 'out');
+  unpack(src, out);
+  const rebuilt = path.join(tmp, 'r.html');
+  pack(out, { outFile: rebuilt });
+  assert.equal(sha(fs.readFileSync(rebuilt)), sha(fs.readFileSync(src)), 'digests differ');
+});
+
+it('whitespace inside a template literal survives', () => {
+  const src = path.join(tmp, 'w.html');
+  fs.writeFileSync(src, PAGE);
+  const out = path.join(tmp, 'wout');
+  unpack(src, out);
+  pack(out, { outFile: path.join(tmp, 'w2.html') });
+  const back = fs.readFileSync(path.join(tmp, 'w2.html'), 'utf8');
+  assert.ok(back.includes('\`a\n\tb \`'), 'a tab or newline was normalised away');
+});
+
+it('a mutated part changes the digest — pack does not paper over it', () => {
+  const src = path.join(tmp, 'm.html');
+  fs.writeFileSync(src, PAGE);
+  const out = path.join(tmp, 'mout');
+  unpack(src, out);
+  const parts = fs.readdirSync(path.join(out, 'parts'));
+  const css = parts.find((f) => f.endsWith('.css'));
+  const p = path.join(out, 'parts', css);
+  fs.writeFileSync(p, fs.readFileSync(p, 'utf8').replace('red', 'blue'));
+  pack(out, { outFile: path.join(tmp, 'm2.html') });
+  assert.notEqual(sha(fs.readFileSync(path.join(tmp, 'm2.html'))), sha(fs.readFileSync(src)),
+    'an edited part must not produce the original digest');
+});
+
+it('findBlocks reports blocks in document order', () => {
+  const offs = findBlocks(PAGE).map((b) => b.contentStart);
+  assert.deepEqual(offs, [...offs].sort((a, b) => a - b));
+});
+
+it('check names a page that fetches from another origin', () => {
+  const remote = PAGE.replace('<h1>hi</h1>', '<img src="https://cdn.example.com/a.png">');
+  const f = path.join(tmp, 'x.html');
+  fs.writeFileSync(f, remote);
+  assert.equal(check(f).selfContained, false);
+  assert.equal(check(path.join(tmp, 'p.html')).selfContained, true);
+});
+
+fs.rmSync(tmp, { recursive: true, force: true });
+if (fails.length) { console.error(`\n  ${fails.length} failure(s)\n`); process.exit(1); }
+console.log('\n  all leaf checks passed\n');