diff --git a/AGENTS.md b/AGENTS.md index 3b21ee9..5b83534 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -35,6 +35,7 @@ Keep code readable by a literate technical user in a single sitting. Prefer the - Source, build, and dist never overlap. Source directories hold only hand-authored code. `build/` (top-level, mirroring `packages/` and `pages/` — e.g. `build/packages/kdbx/`, `build/pages/0x67/`) holds intermediate, always-regenerated compiler and bundler output. `dist/` (top-level) holds the final distributables. Neither `build/` nor `dist/` is ever committed; deleting either never loses anything that can't be regenerated by `npm run build`. - One version number, at the repo root. Packages under `packages/` don't carry independent versions — they aren't published. - Biome lint and format are enforced with no exceptions. `npm run lint` must be clean before a change is done. +- Comments in code that actually ships — each package's `src/` (`packages/*/src/`), and each page's `page.ts`, `logic.ts`, and `page.css` — are compact, because every dist file ships this text verbatim (see [Reproducing a build][reproducing] / the build pipeline: nothing minifies or strips comments), so a wordy comment is wordy in every user's download, not just in the editor. Content that fits on one line is an end-of-line comment (e.g., `//`) where the language has one; content that genuinely needs two or more lines, or where the language has no end-of-line form at all (CSS only has `/* */`), is a block comment. This is decided on the *final*, trimmed wording, not the original — if trimming a block down to its essential point leaves only one line, it becomes an end-of-line comment wherever that's available, not a one-line block. A block comment is compact: the opening delimiter is immediately followed by content on the same line, continuation lines carry no `* ` gutter and are indented to match the surrounding code (not offset for an asterisk), and the closing delimiter sits at the end of the last content line, never alone on its own line. Multi-line comments are trimmed to their essential point — the non-obvious why, spec/RFC citations, security rationale — not restated context, illustrative examples, or a treatise. None of this applies to `tools/`, `e2e/`, `*.test.ts`, or any other test/tooling code: nothing there ships in a dist file, so ordinary, fuller commenting is fine. Biome does not enforce any of this — it's a manual review point, not a lint failure. ## Quality requirements diff --git a/e2e/cloud-google-drive-iframe.test.ts b/e2e/cloud-google-drive-iframe.test.ts index 1e8f8d9..35dce6a 100644 --- a/e2e/cloud-google-drive-iframe.test.ts +++ b/e2e/cloud-google-drive-iframe.test.ts @@ -54,11 +54,11 @@ test('embedded 0x67 iframe fills its container, and its own footer stays hidden' const { frameHeight, availableHeight } = await page.evaluate(() => { const iframe = document.getElementById('app-frame') as HTMLIFrameElement; const header = document.querySelector('.host-header') as HTMLElement; - const sponsorCta = document.querySelector('.sponsor-cta') as HTMLElement; + const footerLinks = document.querySelector('.footer-links') as HTMLElement; const footer = document.querySelector('footer') as HTMLElement; const claimedByOthers = header.getBoundingClientRect().height + - sponsorCta.getBoundingClientRect().height + + footerLinks.getBoundingClientRect().height + footer.getBoundingClientRect().height; return { frameHeight: iframe.getBoundingClientRect().height, @@ -69,7 +69,7 @@ test('embedded 0x67 iframe fills its container, and its own footer stays hidden' assert.ok( Math.abs(frameHeight - availableHeight) < 3, `iframe height (${frameHeight}px) should fill the space left over after ` + - `the header/sponsor-cta/footer (${availableHeight}px), not collapse`, + `the header/footer-links/footer (${availableHeight}px), not collapse`, ); const outerFooterVisible = await page.evaluate(() => { diff --git a/pages/0x67/build.json b/pages/0x67/build.json index 8ae25d5..0f20e4d 100644 --- a/pages/0x67/build.json +++ b/pages/0x67/build.json @@ -1,6 +1,7 @@ { "template": "page.html", - "styles": ["page.css"], + "styles": ["../shared/footer.css", "page.css"], "scripts": ["../../build/pages/0x67/bundle.js"], + "footer": "../shared/footer.html", "output": "../../dist/0x67.html" } diff --git a/pages/0x67/page.css b/pages/0x67/page.css index 6c7919f..9a1eee0 100644 --- a/pages/0x67/page.css +++ b/pages/0x67/page.css @@ -1376,44 +1376,8 @@ input.attachment-name:focus { layout's justify-content:center) ============================================================ */ -.sponsor-cta { - flex-shrink: 0; - padding: 0.4rem 1rem 0; - font-size: 0.8rem; - color: var(--text); - text-align: center; -} - -footer { - flex-shrink: 0; - padding: 0.4rem 1rem; - border-top: 1px solid var(--border); - font-size: 0.75rem; - color: var(--muted); - text-align: center; -} - -footer a { - color: var(--accent); - text-decoration: none; -} - -.sponsor-cta a { - color: var(--accent); - font-weight: 600; - text-decoration: none; -} - -footer a:hover { - text-decoration: underline; -} - -.sponsor-cta a:hover { - text-decoration: underline; -} - /* Embedded: the host page has its own footer, so hide this copy. */ -body.embedded .sponsor-cta, +body.embedded .footer-links, body.embedded footer { display: none; } diff --git a/pages/0x67/page.html b/pages/0x67/page.html index 57aaddd..252cfc8 100644 --- a/pages/0x67/page.html +++ b/pages/0x67/page.html @@ -403,10 +403,7 @@

Choose an icon

- - + diff --git a/pages/cloud-google-drive/build.json b/pages/cloud-google-drive/build.json index bdc5a17..036f7bb 100644 --- a/pages/cloud-google-drive/build.json +++ b/pages/cloud-google-drive/build.json @@ -1,6 +1,7 @@ { "template": "page.html", - "styles": ["page.css"], + "styles": ["../shared/footer.css", "page.css"], "scripts": ["../../build/pages/cloud-google-drive/bundle.js"], + "footer": "../shared/footer.html", "output": "../../dist/cloud-google-drive.html" } diff --git a/pages/cloud-google-drive/page.css b/pages/cloud-google-drive/page.css index 1cd1cda..8522605 100644 --- a/pages/cloud-google-drive/page.css +++ b/pages/cloud-google-drive/page.css @@ -98,32 +98,6 @@ body { min-height: 0; } -.sponsor-cta { - flex-shrink: 0; - padding: 0.4rem 1rem 0; - font-size: 0.85rem; - color: var(--text); - text-align: center; -} - -footer { - flex-shrink: 0; - padding: 0.4rem 1rem; - border-top: 1px solid var(--border); - font-size: 0.8rem; - color: var(--muted); - text-align: center; -} - -footer a { - color: var(--accent); -} - -.sponsor-cta a { - color: var(--accent); - font-weight: 600; -} - /* ============================================================ Buttons and shared bits ============================================================ */ diff --git a/pages/cloud-google-drive/page.html b/pages/cloud-google-drive/page.html index a9fac3e..60ef8c5 100644 --- a/pages/cloud-google-drive/page.html +++ b/pages/cloud-google-drive/page.html @@ -59,10 +59,7 @@

Open from Google Drive

- - + diff --git a/pages/index/build.json b/pages/index/build.json index bfc5616..371b266 100644 --- a/pages/index/build.json +++ b/pages/index/build.json @@ -1,6 +1,7 @@ { "template": "page.html", - "styles": ["page.css"], + "styles": ["../shared/footer.css", "page.css"], "scripts": [], + "footer": "../shared/footer.html", "output": "../../dist/index.html" } diff --git a/pages/index/page.css b/pages/index/page.css index a80ed83..4106d21 100644 --- a/pages/index/page.css +++ b/pages/index/page.css @@ -139,25 +139,3 @@ a:hover { margin-bottom: 2rem; text-align: left; } - -.links { - display: flex; - gap: 1.5rem; - justify-content: center; -} - -.sponsor-cta { - margin-top: 2rem; - font-size: 0.9rem; - color: var(--text); -} - -.sponsor-cta a { - font-weight: 600; -} - -footer { - margin-top: 4rem; - font-size: 0.8rem; - color: var(--border); -} diff --git a/pages/index/page.html b/pages/index/page.html index fac4974..620efa2 100644 --- a/pages/index/page.html +++ b/pages/index/page.html @@ -26,16 +26,8 @@

Your passwords.
Your storage.
Your browser.

Every file on the hosted site is a verbatim copy of a published release artifact. Download the release, verify the published checksum, and trust what you audit. - -
- GitHub -
- - - + diff --git a/pages/local/build.json b/pages/local/build.json index 48d95fe..363a4c9 100644 --- a/pages/local/build.json +++ b/pages/local/build.json @@ -1,6 +1,7 @@ { "template": "page.html", - "styles": ["page.css"], + "styles": ["../shared/footer.css", "page.css"], "scripts": ["../../build/pages/local/bundle.js"], + "footer": "../shared/footer.html", "output": "../../dist/local.html" } diff --git a/pages/local/page.css b/pages/local/page.css index bbeaec7..2d60340 100644 --- a/pages/local/page.css +++ b/pages/local/page.css @@ -102,32 +102,6 @@ a:hover { text-decoration: underline; } -.sponsor-cta { - flex-shrink: 0; - padding: 0.4rem 1rem 0; - font-size: 0.85rem; - color: var(--text); - text-align: center; -} - -footer { - flex-shrink: 0; - padding: 0.4rem 1rem; - border-top: 1px solid var(--border); - font-size: 0.8rem; - color: var(--muted); - text-align: center; -} - -footer a { - color: var(--accent); -} - -.sponsor-cta a { - color: var(--accent); - font-weight: 600; -} - .description { color: var(--muted); } diff --git a/pages/local/page.html b/pages/local/page.html index 7f9e12a..a173778 100644 --- a/pages/local/page.html +++ b/pages/local/page.html @@ -54,10 +54,7 @@

Open a database from this computer

- - + diff --git a/pages/shared/footer.css b/pages/shared/footer.css new file mode 100644 index 0000000..32e7c66 --- /dev/null +++ b/pages/shared/footer.css @@ -0,0 +1,39 @@ +/* ============================================================ + Shared footer partial (pages/shared/footer.html) + ============================================================ */ + +footer { + flex-shrink: 0; + padding: 0.4rem 1rem; + border-top: 1px solid var(--border); + font-size: 0.8rem; + color: var(--muted); + text-align: center; +} + +footer a { + color: var(--accent); + text-decoration: none; +} + +footer a:hover { + text-decoration: underline; +} + +.footer-links { + flex-shrink: 0; + padding: 0.4rem 1rem 0; + font-size: 0.85rem; + color: var(--text); + text-align: center; +} + +.footer-links a { + color: var(--accent); + font-weight: 600; + text-decoration: none; +} + +.footer-links a:hover { + text-decoration: underline; +} diff --git a/pages/shared/footer.html b/pages/shared/footer.html new file mode 100644 index 0000000..44d1b62 --- /dev/null +++ b/pages/shared/footer.html @@ -0,0 +1,7 @@ +

+ ♥ Sponsor + · MIT Licensed + · FAQ + · Source +

+ diff --git a/tools/build/inliner/src/build.ts b/tools/build/inliner/src/build.ts index f1699cf..b3bfa33 100644 --- a/tools/build/inliner/src/build.ts +++ b/tools/build/inliner/src/build.ts @@ -6,14 +6,16 @@ import { computeVersionLabel, renderVersionFragment } from './version-label.ts'; const STYLES_SENTINEL = ''; const SCRIPTS_SENTINEL = ''; +const FOOTER_SENTINEL = ''; const VERSION_SENTINEL = ''; /** - * Reads the manifest at `manifestPath`, inlines all styles and scripts into the - * HTML template in the order listed, writes the output file, and returns its - * SHA-256 checksum (hex-encoded) alongside the resolved output path. + * Reads the manifest at `manifestPath`, inlines all styles and scripts plus the + * shared footer partial into the HTML template in the order listed, writes the + * output file, and returns its SHA-256 checksum (hex-encoded) alongside the + * resolved output path. * - * Throws if either sentinel is absent from the template, or if any listed file + * Throws if any sentinel is absent from the template, or if any listed file * cannot be read. */ export function build(manifestPath: string): { checksum: string; outputPath: string } { @@ -28,12 +30,26 @@ export function build(manifestPath: string): { checksum: string; outputPath: str if (!template.includes(SCRIPTS_SENTINEL)) { throw new Error(`Template is missing the required sentinel: ${SCRIPTS_SENTINEL}`); } - if (!template.includes(VERSION_SENTINEL)) { - throw new Error(`Template is missing the required sentinel: ${VERSION_SENTINEL}`); + if (!template.includes(FOOTER_SENTINEL)) { + throw new Error(`Template is missing the required sentinel: ${FOOTER_SENTINEL}`); } const css = manifest.styles.map((f) => readFileSync(join(base, f), 'utf8')).join('\n'); const js = manifest.scripts.map((f) => readFileSync(join(base, f), 'utf8')).join('\n'); + const footer = readFileSync(join(base, manifest.footer), 'utf8'); + + const withFooter = template + .replace(STYLES_SENTINEL, ``) + .replace(SCRIPTS_SENTINEL, ``) + .replace(FOOTER_SENTINEL, footer); + + // VERSION may live directly in the template or inside the just-inlined + // footer partial (the real page templates only carry it via the footer), + // so this check runs after FOOTER inlining rather than alongside the rest. + if (!withFooter.includes(VERSION_SENTINEL)) { + throw new Error(`Template is missing the required sentinel: ${VERSION_SENTINEL}`); + } + const version = renderVersionFragment( computeVersionLabel({ refType: process.env.GITHUB_REF_TYPE, @@ -43,10 +59,7 @@ export function build(manifestPath: string): { checksum: string; outputPath: str process.env.KEEPASS_WEB_COMMIT_DATE, ); - const html = template - .replace(STYLES_SENTINEL, ``) - .replace(SCRIPTS_SENTINEL, ``) - .replace(VERSION_SENTINEL, version); + const html = withFooter.replace(VERSION_SENTINEL, version); const outputPath = join(base, manifest.output); mkdirSync(dirname(outputPath), { recursive: true }); diff --git a/tools/build/inliner/src/types.ts b/tools/build/inliner/src/types.ts index a6e051b..f9c398c 100644 --- a/tools/build/inliner/src/types.ts +++ b/tools/build/inliner/src/types.ts @@ -8,12 +8,20 @@ * load order — it is the author's responsibility to list dependencies first. */ export interface Manifest { - /** HTML template. Must contain exactly one , one , and one sentinel. */ + /** + * HTML template. Must contain exactly one , one , + * and one sentinel. A sentinel must appear + * exactly once across the template and/or the inlined footer partial — + * it's resolved after FOOTER inlining, so the footer partial may supply it + * instead of the template. + */ readonly template: string; /** CSS files, concatenated in order and inlined at . */ readonly styles: readonly string[]; /** JS files, concatenated in order and inlined at . */ readonly scripts: readonly string[]; + /** HTML partial inlined at , before is resolved. */ + readonly footer: string; /** Output path for the produced distributable, relative to the manifest. */ readonly output: string; } diff --git a/tools/build/inliner/tests/build.test.ts b/tools/build/inliner/tests/build.test.ts index c13508a..7569942 100644 --- a/tools/build/inliner/tests/build.test.ts +++ b/tools/build/inliner/tests/build.test.ts @@ -98,42 +98,73 @@ function runCLI( }); } -const SENTINELS = ''; +const SENTINELS = ''; + +// Every successful build now needs a footer partial on disk and a `footer` +// manifest field pointing at it — this writes both with placeholder content. +function writeDefaultFooter(dir: string): void { + write(dir, 'footer.html', ''); +} // --------------------------------------------------------------------------- // build() // --------------------------------------------------------------------------- -test('inlines style and script into the template', () => { +test('inlines style, script, and footer into the template', () => { const dir = tempDir(); write(dir, 'template.html', `${SENTINELS}`); write(dir, 'style.css', 'body { color: red; }'); write(dir, 'script.js', 'console.log(1);'); + writeDefaultFooter(dir); manifest(dir, { template: 'template.html', styles: ['style.css'], scripts: ['script.js'], + footer: 'footer.html', output: 'out.html', }); const { checksum, outputPath } = withVersionEnv({}, () => build(join(dir, 'build.json'))); const expected = - 'development build'; + 'development build'; assert.equal(readFileSync(join(dir, 'out.html'), 'utf8'), expected); assert.equal(checksum, sha256(expected)); assert.equal(outputPath, join(dir, 'out.html')); }); +test('the footer partial may supply the only sentinel', () => { + const dir = tempDir(); + write(dir, 'template.html', ''); + write(dir, 'footer.html', ''); + manifest(dir, { + template: 'template.html', + styles: [], + scripts: [], + footer: 'footer.html', + output: 'out.html', + }); + + withVersionEnv({}, () => build(join(dir, 'build.json'))); + + const result = readFileSync(join(dir, 'out.html'), 'utf8'); + assert.equal( + result, + '', + ); +}); + test('concatenates multiple CSS files in manifest order', () => { const dir = tempDir(); write(dir, 'template.html', SENTINELS); write(dir, 'a.css', '.a {}'); write(dir, 'b.css', '.b {}'); + writeDefaultFooter(dir); manifest(dir, { template: 'template.html', styles: ['a.css', 'b.css'], scripts: [], + footer: 'footer.html', output: 'out.html', }); @@ -148,10 +179,12 @@ test('concatenates multiple JS files in manifest order', () => { write(dir, 'template.html', SENTINELS); write(dir, 'a.js', 'const a = 1;'); write(dir, 'b.js', 'const b = 2;'); + writeDefaultFooter(dir); manifest(dir, { template: 'template.html', styles: [], scripts: ['a.js', 'b.js'], + footer: 'footer.html', output: 'out.html', }); @@ -164,10 +197,12 @@ test('concatenates multiple JS files in manifest order', () => { test('creates the output directory when it does not exist', () => { const dir = tempDir(); write(dir, 'template.html', SENTINELS); + writeDefaultFooter(dir); manifest(dir, { template: 'template.html', styles: [], scripts: [], + footer: 'footer.html', output: 'deep/nested/out.html', }); @@ -197,11 +232,29 @@ test('throws when the SCRIPTS sentinel is absent from the template', () => { ); }); -test('throws when the VERSION sentinel is absent from the template', () => { +test('throws when the FOOTER sentinel is absent from the template', () => { const dir = tempDir(); - write(dir, 'template.html', ''); + write(dir, 'template.html', ''); manifest(dir, { template: 'template.html', styles: [], scripts: [], output: 'out.html' }); + assert.throws( + () => build(join(dir, 'build.json')), + /missing the required sentinel: /, + ); +}); + +test('throws when the VERSION sentinel is absent from both the template and the footer partial', () => { + const dir = tempDir(); + write(dir, 'template.html', ''); + write(dir, 'footer.html', ''); + manifest(dir, { + template: 'template.html', + styles: [], + scripts: [], + footer: 'footer.html', + output: 'out.html', + }); + assert.throws( () => build(join(dir, 'build.json')), /missing the required sentinel: /, @@ -211,7 +264,14 @@ test('throws when the VERSION sentinel is absent from the template', () => { test('VERSION sentinel: renders a linked tag and locale-formatting script when built from a tag', () => { const dir = tempDir(); write(dir, 'template.html', SENTINELS); - manifest(dir, { template: 'template.html', styles: [], scripts: [], output: 'out.html' }); + writeDefaultFooter(dir); + manifest(dir, { + template: 'template.html', + styles: [], + scripts: [], + footer: 'footer.html', + output: 'out.html', + }); withVersionEnv( { @@ -238,7 +298,14 @@ test('VERSION sentinel: renders a linked tag and locale-formatting script when b test('VERSION sentinel: falls back to a linked short sha when there is no exact tag', () => { const dir = tempDir(); write(dir, 'template.html', SENTINELS); - manifest(dir, { template: 'template.html', styles: [], scripts: [], output: 'out.html' }); + writeDefaultFooter(dir); + manifest(dir, { + template: 'template.html', + styles: [], + scripts: [], + footer: 'footer.html', + output: 'out.html', + }); const sha = `${'b'.repeat(39)}c`; withVersionEnv({ GITHUB_REF_TYPE: 'branch', GITHUB_REF_NAME: 'main', GITHUB_SHA: sha }, () => @@ -257,7 +324,14 @@ test('VERSION sentinel: falls back to a linked short sha when there is no exact test('VERSION sentinel: renders an unlinked "development build" with no env vars set', () => { const dir = tempDir(); write(dir, 'template.html', SENTINELS); - manifest(dir, { template: 'template.html', styles: [], scripts: [], output: 'out.html' }); + writeDefaultFooter(dir); + manifest(dir, { + template: 'template.html', + styles: [], + scripts: [], + footer: 'footer.html', + output: 'out.html', + }); withVersionEnv({}, () => build(join(dir, 'build.json'))); @@ -279,7 +353,14 @@ test('CLI: exits 1 and prints usage when no manifest path is given', async () => test('CLI: exits 0 and prints sha256 checksum and output path on success', async () => { const dir = tempDir(); write(dir, 'template.html', SENTINELS); - manifest(dir, { template: 'template.html', styles: [], scripts: [], output: 'out.html' }); + writeDefaultFooter(dir); + manifest(dir, { + template: 'template.html', + styles: [], + scripts: [], + footer: 'footer.html', + output: 'out.html', + }); const { code, stdout } = await runCLI([join(dir, 'build.json')]); assert.equal(code, 0);