npm - @natjswenson/devlog - Versions diffs - 0.5.2 → 0.8.1 - Mend

@natjswenson/devlog 0.5.2 → 0.8.1

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.

Files changed (16) hide show

package/SKILL.md +112 -14
package/bin/devlog.js +441 -7
package/config.example.json +6 -0
package/evals/fixtures/good-post.md +10 -6
package/evals/fixtures/irreproducible-post.md +7 -3
package/image-style/font.ttf +0 -0
package/image-style/style-guide.example.md +107 -0
package/lib/config_ops.mjs +5 -2
package/lib/core.mjs +12 -1
package/lib/cover_gen.mjs +124 -0
package/lib/lint_post.mjs +48 -2
package/lib/publish_entry.mjs +115 -3
package/lib/render_cover.mjs +156 -0
package/lib/scan.mjs +6 -0
package/package.json +4 -1
package/skill-invariants.json +26 -1

package/image-style/style-guide.example.md ADDED Viewed

@@ -0,0 +1,107 @@
+# Cover image style guide
+This is the fallback style guide devlog uses when composing a post's cover image. It is
+generic. Replace it with your own — the more specific the visual direction, the more
+consistent your covers will look across ~50+ posts.
+devlog reads this file, plus (when available) the `n` most recently published covers as
+reference images, before composing a new cover. **Actually look at the reference images
+before composing** — the style guide alone under-specifies layout/spacing; the references
+are how a from-scratch visual language stays consistent from post to post.
+## What you're composing
+A single self-contained HTML document (inline `<style>`, inline SVG for any artwork) that
+renders, at exactly 1600×900px, as a cover image for one dev log entry. Compose from these
+fields only — never open the post's raw markdown file, never reference any section other
+than `## Shipped` (no `## Changelog`, no gotchas, no sources):
+- `title`
+- `tags`
+- `summary`
+- the `## Shipped` section's text
+## The point of this cover: one custom illustration, not a repeated headline
+**A cover that just re-renders the title in large text is a failure, no matter how clean
+the typography is.** The title is already the `<h1>` on the post page one scroll down —
+the cover's job is to give the reader something to *look at*, a specific visual idea that
+came from *this* post's content and would look wrong on any other post.
+Before writing any HTML, do this thinking step explicitly:
+1. Read the title, summary, and `## Shipped` text.
+2. Identify the one concrete technical concept or moment the post is actually about —
+   not the project name, not "a bug fix," but the specific mechanism: a lock rejecting a
+   key that doesn't fit, a git tag being distrusted like any other user input, one broken
+   link in a chain, a filter separating signal from noise, a clock catching a stale
+   timestamp, two paths diverging and one being cut off.
+3. Design ONE illustration — built from inline SVG shapes (lines, arcs, polygons,
+   simple geometric forms) — that depicts that concept. Not a photo, not a stock icon,
+   not a screenshot: a small original line-art scene, in the spirit of an editorial
+   illustration or a technical diagram, using only the palette below.
+4. That illustration is the dominant visual element of the cover — roughly half the
+   canvas, not a thumbnail in the corner. Title, kicker, and summary text support it;
+   they do not replace it.
+**Two different posts should never produce visually similar covers.** If your instinct is
+to reach for a generic circle/square/checkmark because you're not sure what else to draw,
+that's a sign to go back to step 2 and find the more specific concept — a post about
+retrying a flaky network call and a post about deduplicating bank transactions should not
+end up with the same shape family.
+## Technical requirements (non-negotiable)
+- Start the document with a literal `<!DOCTYPE html>` declaration, always.
+- `html, body { margin: 0; width: 1600px; height: 900px; }` — the render is a
+  viewport-clipped screenshot at exactly this size; content that overflows this box is
+  simply never captured, so keep everything inside it.
+- Reference the bundled font only by its fixed name, with a fallback:
+  `font-family: 'DevlogCoverFont', sans-serif;` — never embed font bytes yourself, never
+  reference any other font file. The renderer injects the real font after your markup is
+  parsed.
+- No external resources of any kind — no `<link>`, no `@import`, no remote `<img src>`,
+  no web fonts, no raster images. All artwork is inline SVG built from basic shapes
+  (`<path>`, `<circle>`, `<rect>`, `<line>`, `<polygon>`, `<polyline>`) — everything must
+  be inline HTML/CSS/SVG, hand-composed, not fetched or embedded from anywhere.
+## Visual direction
+The site (natejswenson.com) is a minimalist, monospace, terminal-styled dev log. Covers
+should feel like they belong to the same publication as the site itself — technical
+editorial illustrations, not marketing graphics and not a repeated template:
+- **Palette:** background `#0a0a0b` (near-black), foreground/line-art color `#ededed`,
+  secondary/dim `#8a8a8a`, one accent color `#fff503` (yellow) for the single most
+  important element of the illustration — the thing being emphasized, not a decoration.
+  Prefer 2-3 colors on a page (black, white, one accent), not a rainbow. Prefer flat,
+  limited color and solid/line fills over large smooth gradients — the render is
+  compressed with lossy PNG palette quantization afterward, and gradients band visibly
+  under that compression while flat fills don't.
+- **Typography:** `'DevlogCoverFont'` (a monospace face) for any on-image text — kicker,
+  title, date. Keep the title modest in size (it is not the main event); a short kicker
+  (project + date) is enough context. Terminal/code aesthetic glyphs (`$`, `>`, `//`,
+  brackets) are fair game as small accents, not as the illustration itself.
+- **Composition:** the illustration occupies the dominant visual weight of the canvas —
+  centered or offset to one side, large enough to read at a glance, with the
+  title/kicker in the remaining negative space (not overlapping the artwork). Plenty of
+  breathing room around the illustration; don't crowd it with text or decoration.
+- **Restraint in execution, not in ambition:** the illustration should be a real, specific
+  scene (multiple shapes composed together to depict one concept), not a single
+  primitive. But avoid clutter — every shape in the illustration should serve the one
+  concept, not decorate around it.
+## Never do
+- Don't make the title the largest, most prominent element on the cover — the
+  illustration is.
+- Don't restate the version number as the headline ("v0.6.0" as the big text) — use the
+  post's actual title, and keep it secondary to the artwork.
+- Don't reuse the same illustration, shape family, or visual metaphor across different
+  posts — go back to the post's actual content and find what's specific to it.
+- Don't fall back to a generic circle/square/checkmark/arrow when stuck — that's the
+  exact failure mode this guide exists to prevent. Spend the extra step finding the
+  concrete mechanism the post describes.
+- Don't use a gradient as a full-bleed background.
+- Don't embed a photograph, stock image, or anything requiring an external fetch — the
+  illustration is drawn from inline SVG primitives, not sourced from anywhere.
+- Don't reference any font other than `'DevlogCoverFont'` (with its `sans-serif`
+  fallback).

package/lib/config_ops.mjs CHANGED Viewed

@@ -3,11 +3,14 @@
 // reading/writing ~/.claude/skills/devlog/config.json atomically.
 import { validateConfig, expandHome } from './core.mjs';
-export function addProject(config, { key, path, remote, label, tagPrefix, pathFilter }) {
+export function addProject(config, { key, path, remote, label, tagPrefix, pathFilter, private: isPrivate }) {
   if (config.projects.some((p) => p.key === key)) {
     throw new Error(`Project key "${key}" is already registered.`);
   }
-  const project = { key, path: expandHome(path), remote };
+  const project = { key, path: expandHome(path) };
+  // remote is required unless the project is private (see core.mjs validateConfig).
+  if (remote) project.remote = remote;
+  if (isPrivate) project.private = true;
   if (label) project.label = label;
   // Only persist tagPrefix when it differs from the default `v` (keeps configs clean).
   if (tagPrefix && tagPrefix !== 'v') project.tagPrefix = tagPrefix;

package/lib/core.mjs CHANGED Viewed

@@ -154,7 +154,18 @@ export function validateConfig(config) {
     if (typeof p.path !== 'string' || SHELL_QUOTE_BREAK.test(p.path)) {
       throw new Error(`project.path invalid (must contain no shell metacharacters): ${JSON.stringify(p.path)}`);
     }
-    if (!RE_OWNER_REPO.test(p.remote)) {
+    if ('private' in p && typeof p.private !== 'boolean') {
+      throw new Error(`project.private must be a boolean if present: ${JSON.stringify(p.private)}`);
+    }
+    // A private project has no safe public commit surface, so `remote` is
+    // optional (it's never used to build a commit link — see scan.mjs's
+    // isPublic). If supplied anyway, for the maintainer's own reference, it
+    // must still be well-formed.
+    if (p.private) {
+      if ('remote' in p && p.remote !== undefined && !RE_OWNER_REPO.test(p.remote)) {
+        throw new Error(`project.remote must match <owner>/<repo>: ${JSON.stringify(p.remote)}`);
+      }
+    } else if (!RE_OWNER_REPO.test(p.remote)) {
       throw new Error(`project.remote must match <owner>/<repo>: ${JSON.stringify(p.remote)}`);
     }
     if ('pathFilter' in p) {

package/lib/cover_gen.mjs ADDED Viewed

@@ -0,0 +1,124 @@
+// Style guide + reference-image lookup for cover-image composition. Deterministic,
+// no LLM/agent involvement — the agent calls `devlog cover-context` (bin/devlog.js),
+// which wraps these two functions.
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { CONFIG_DIR } from './core.mjs';
+const IMAGE_STYLE_DIR = join(CONFIG_DIR, 'image-style');
+const STYLE_GUIDE_PATH = join(IMAGE_STYLE_DIR, 'style-guide.md');
+function slugFromFile(file) {
+  return String(file || '').replace(/\.md$/, '');
+}
+// Pure. Reads the installed style guide. There is no graceful degradation here — Claude
+// has nothing to compose from without it; callers (devlog cover-context) catch the throw
+// and surface it as a distinct error, never blocking the rest of publish.
+export function loadStyleGuide() {
+  if (!existsSync(STYLE_GUIDE_PATH)) {
+    throw new Error(`Cover style guide not found at ${STYLE_GUIDE_PATH} — run \`devlog init\` to install it.`);
+  }
+  return readFileSync(STYLE_GUIDE_PATH, 'utf8');
+}
+// Read one project's manifest.json out of an already-established clone.
+// Two distinct missing-manifest cases (mirrors fetchExistingEntries()'s empty/failed split
+// in lib/scan.mjs): a project directory that doesn't exist at all (never published a
+// release yet) is zero entries, not an error. A project directory that DOES exist but
+// whose manifest.json is missing or fails to parse is a genuine anomaly — surfaced via
+// status: 'failed' so the caller can throw a clear, named error rather than silently
+// dropping that project's entries from a merged result.
+function readProjectManifest(cloneDir, projectKey) {
+  const projectDir = join(cloneDir, projectKey);
+  if (!existsSync(projectDir)) {
+    return { entries: [], status: 'empty' };
+  }
+  const manifestPath = join(projectDir, 'manifest.json');
+  if (!existsSync(manifestPath)) {
+    return { entries: [], status: 'failed', reason: `manifest.json missing for project "${projectKey}" (expected at ${manifestPath})` };
+  }
+  let manifest;
+  try {
+    manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
+  } catch (e) {
+    return { entries: [], status: 'failed', reason: `manifest.json for project "${projectKey}" failed to parse: ${e.message}` };
+  }
+  if (!manifest || !Array.isArray(manifest.entries)) {
+    return { entries: [], status: 'failed', reason: `manifest.json for project "${projectKey}" is malformed (expected { "entries": [...] })` };
+  }
+  return { entries: manifest.entries, status: 'ok' };
+}
+// Cross-project manifest enumeration/merge — the one mechanism shared by
+// getRecentCovers() (below) and `devlog backfill-covers list` (bin/devlog.js). There is no
+// merged/aggregated manifest file anywhere in daily-dev-log (confirmed: exactly one
+// manifest.json per project directory) — every project's own manifest.json is read
+// individually and tagged with `project` as it's read, mirroring getAllEntries() in
+// natejswenson.io/src/lib/devlog.js (the site's own equivalent per-project-manifest merge;
+// its own empty-vs-corrupt handling is indirect/local-overlay-based, not the same
+// mechanism as this direct directory check, though it reaches the same outcome for the
+// directory-absent case).
+export function mergeManifestEntries(cloneDir, config) {
+  const merged = [];
+  for (const p of (config.projects || [])) {
+    const { entries, status, reason } = readProjectManifest(cloneDir, p.key);
+    if (status === 'failed') throw new Error(reason);
+    for (const e of entries) merged.push({ ...e, project: p.key });
+  }
+  return merged;
+}
+// Staged-but-uncommitted covers from earlier in the same backfill session, freshest first
+// by file mtime. Resolved under stagingDir's per-project subdirectory
+// (<stagingDir>/<project>/<slug>.png) — never a flat <stagingDir>/<slug>.png, since slugs
+// are not globally unique across projects.
+function listStagedCovers(stagingDir) {
+  if (!stagingDir || !existsSync(stagingDir)) return [];
+  const out = [];
+  for (const d of readdirSync(stagingDir, { withFileTypes: true })) {
+    if (!d.isDirectory()) continue; // skips the top-level index.html contact sheet
+    const projectDir = join(stagingDir, d.name);
+    for (const f of readdirSync(projectDir)) {
+      if (!f.endsWith('.png')) continue;
+      const full = join(projectDir, f);
+      out.push({ project: d.name, slug: f.replace(/\.png$/, ''), path: full, mtimeMs: statSync(full).mtimeMs });
+    }
+  }
+  out.sort((a, b) => b.mtimeMs - a.mtimeMs);
+  return out.map(({ project, slug, path }) => ({ project, slug, path }));
+}
+// Pure given its inputs. Returns the N most recently published covers across every
+// configured project (newest by manifest `date`), as local paths inside the already-
+// established clone. When stagingDir is given and fewer than n published covers exist,
+// tops up the result with covers already staged this session (freshest-first) — what lets
+// a from-scratch backfill session bootstrap its own visual consistency instead of every
+// candidate composing from the style guide alone. Returns [] when neither source has
+// anything yet (the true first-cover case) — never throws for that, never pads.
+export function getRecentCovers({ cloneDir, config, stagingDir = null, n = 3 }) {
+  const merged = mergeManifestEntries(cloneDir, config);
+  const covered = merged
+    .filter((e) => e && e.cover && e.file)
+    .map((e) => ({ project: e.project, slug: slugFromFile(e.file), date: e.date }))
+    .sort((a, b) => (a.date < b.date ? 1 : a.date > b.date ? -1 : 0));
+  const result = covered.slice(0, n).map(({ project, slug }) => ({
+    project,
+    slug,
+    path: join(cloneDir, project, `${slug}.png`),
+  }));
+  if (result.length < n) {
+    const seen = new Set(result.map((r) => `${r.project}/${r.slug}`));
+    for (const staged of listStagedCovers(stagingDir)) {
+      if (result.length >= n) break;
+      const key = `${staged.project}/${staged.slug}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+      result.push(staged);
+    }
+  }
+  return result;
+}

package/lib/lint_post.mjs CHANGED Viewed

@@ -10,6 +10,23 @@ export const REQUIRED_SECTIONS = ['Shipped', 'Gotchas', 'Sources'];
 const RE_DATE = /^\d{4}-\d{2}-\d{2}$/;
+export const TAG_PATTERN = /^[a-z0-9][a-z0-9-]*$/;
+// First-occurrence wins: keeps the first casing seen, drops later
+// case-insensitive duplicates. A same-case repeat is the reachable case in
+// practice — TAG_PATTERN already forbids the case-differing variant outright.
+export function dedupeCaseInsensitive(tags) {
+  const seen = new Set();
+  const out = [];
+  for (const t of tags) {
+    const key = t.toLowerCase();
+    if (seen.has(key)) continue;
+    seen.add(key);
+    out.push(t);
+  }
+  return out;
+}
 // Minimal frontmatter parser: `--- ... ---` fence, `key: value` lines, flow
 // arrays for tags. Prototype-free target object; unknown keys are kept (the
 // contract does not forbid extras) but only allowlisted keys are checked.
@@ -79,6 +96,12 @@ export function findUntaggedFences(body) {
   return untagged;
 }
+// Ignore differences that don't change the destination: trailing slash and
+// URL fragment.
+export function normalizeUrl(url) {
+  return url.replace(/#.*$/, '').replace(/\/+$/, '');
+}
 export function extractSourceUrls(sectionContent) {
   const urls = new Set();
   for (const m of sectionContent.matchAll(/\]\((https?:\/\/[^)\s]+)\)/g)) {
@@ -115,8 +138,18 @@ export function lintPost(content, { minSources = 3, filename = null } = {}) {
       add('title-style', 'Title must be essay-style, not a "release vX.Y.Z" label.');
     }
   }
-  if (Array.isArray(data.tags) && (data.tags.length < 2 || data.tags.length > 5)) {
-    add('tags-count', `Expected 2-5 topic tags, got ${data.tags.length}.`);
+  if (Array.isArray(data.tags) && (data.tags.length < 5 || data.tags.length > 10)) {
+    add('tags-count', `Expected 5-10 topic tags, got ${data.tags.length}.`);
+  }
+  if (Array.isArray(data.tags)) {
+    for (const t of data.tags) {
+      if (typeof t === 'string' && !TAG_PATTERN.test(t)) {
+        add('tags-character-pattern', `Tag "${t}" must be lowercase alphanumeric/hyphens only (^[a-z0-9][a-z0-9-]*$).`);
+      }
+    }
+    if (dedupeCaseInsensitive(data.tags).length !== data.tags.length) {
+      add('tags-duplicate', 'Tags contain a case-insensitive duplicate.');
+    }
   }
   if (filename && typeof data.version === 'string' && data.version) {
     const expected = `${data.version}.md`;
@@ -142,6 +175,19 @@ export function lintPost(content, { minSources = 3, filename = null } = {}) {
     if (urls.size < minSources) {
       add('sources-count', `Need at least ${minSources} distinct source URLs; found ${urls.size}.`);
     }
+    // The contract requires claims to carry their citation where they're made,
+    // not only in the bibliography: every Sources URL must also be cited
+    // inline somewhere else in the body.
+    const inline = new Set();
+    for (const s of sections) {
+      if (s.heading === 'Sources') continue;
+      for (const u of extractSourceUrls(s.content)) inline.add(normalizeUrl(u));
+    }
+    for (const u of urls) {
+      if (!inline.has(normalizeUrl(u))) {
+        add('sources-inline', `Source ${u} is listed in \`## Sources\` but never cited inline in the body — cite it where its claim is made, or drop it from Sources.`);
+      }
+    }
   }
   for (const line of findUntaggedFences(body)) {

package/lib/publish_entry.mjs CHANGED Viewed

@@ -2,11 +2,33 @@
 // manifest. This is the code-enforced immutability guard: a cut release's
 // entry is never overwritten, and manifest mutation is no longer done by
 // hand-editing JSON in the agent loop.
-import { existsSync, mkdirSync, readFileSync, copyFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, writeFileSync, copyFileSync, statSync, openSync, readSync, closeSync } from 'node:fs';
 import { join } from 'node:path';
 import { RE_PROJECT_KEY, RE_FINAL_RELEASE, atomicWriteJSON } from './core.mjs';
 import { parseFrontmatter } from './lint_post.mjs';
+const PNG_MAGIC = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+function isValidPng(path) {
+  let fd;
+  try {
+    fd = openSync(path, 'r');
+    const buf = Buffer.alloc(8);
+    const n = readSync(fd, buf, 0, 8, 0);
+    return n === 8 && buf.equals(PNG_MAGIC);
+  } catch {
+    return false;
+  } finally {
+    if (fd !== undefined) closeSync(fd);
+  }
+}
+function assertSafeSlug(slug) {
+  if (typeof slug !== 'string' || slug === '' || slug.includes('/') || slug.includes('..') || /[\x00-\x1f]/.test(slug)) {
+    throw new Error(`Invalid slug: ${JSON.stringify(slug)}`);
+  }
+}
 // Newest-first by date; same-date ties break by version, highest first.
 // Without the tiebreak, several releases cut on one day render oldest-on-top
 // in the feed (stable sort keeps insertion order), burying the newest post
@@ -33,7 +55,7 @@ function sortEntries(entries) {
     String(b.date).localeCompare(String(a.date)) || compareVersionsDesc(a, b));
 }
-export function publishEntry({ cloneDir, project, version, entryPath }) {
+export function publishEntry({ cloneDir, project, version, entryPath, coverImageBuffer }) {
   if (!RE_PROJECT_KEY.test(project) || project.includes('..')) {
     throw new Error(`Invalid project key: ${JSON.stringify(project)}`);
   }
@@ -58,6 +80,17 @@ export function publishEntry({ cloneDir, project, version, entryPath }) {
   mkdirSync(projectDir, { recursive: true });
   copyFileSync(entryPath, destPath);
+  // Cover write happens between the .md write and the manifest mutation, matching the
+  // existing .md-then-manifest crash-recovery convention: a process death after this write
+  // but before the manifest mutation leaves an orphaned <version>.png with no matching
+  // `cover` field — harmless inert clutter (the manifest is the sole source of truth for
+  // "does this post have a cover"), not a correctness bug, and needs no cleanup logic.
+  let coverFile = null;
+  if (coverImageBuffer) {
+    coverFile = `${version}.png`;
+    writeFileSync(join(projectDir, coverFile), coverImageBuffer);
+  }
   const manifestPath = join(projectDir, 'manifest.json');
   let manifest = { entries: [] };
   if (existsSync(manifestPath)) {
@@ -79,11 +112,90 @@ export function publishEntry({ cloneDir, project, version, entryPath }) {
       title: String(data.title),
       summary: String(data.summary),
       version,
+      tags: Array.isArray(data.tags) ? data.tags : [],
+      ...(coverFile ? { cover: { file: coverFile, bytes: coverImageBuffer.length } } : {}),
     });
     manifest.entries = sortEntries(manifest.entries);
     atomicWriteJSON(manifestPath, manifest);
     manifestUpdated = true;
   }
-  return { written: destPath, manifestUpdated };
+  return { written: destPath, manifestUpdated, coverWritten: !!coverFile };
+}
+// Backfill path only: add a cover to an entry that was already published without one.
+// Never writes/reads <slug>.md, never pushes a new manifest row — its only mutation is the
+// `cover` field of an already-existing entry, keyed by that entry's version/file stem.
+//
+// Three-way branch, in order:
+//   1. force: true            -> ALWAYS overwrite the clone-destination PNG unconditionally,
+//                                 no magic-byte check, no adoption logic. This is what
+//                                 "force" means: --force is used precisely when a row
+//                                 already has `cover`, so an ungated adoption check would
+//                                 otherwise silently skip the write exactly when the caller
+//                                 most clearly intends to overwrite.
+//   2. !force, row has cover  -> throw/refuse before any write.
+//   3. !force, row lacks cover -> the only branch where magic-byte adopt-or-discard logic
+//                                 applies. Kept as cheap, harmless insurance for a resume
+//                                 scenario that is NOT reachable via commit-covers's actual
+//                                 call pattern (commit-covers always establishes a fresh
+//                                 clone and performs exactly one commit+push at the very
+//                                 end, so a crash mid-run never leaves this orphan
+//                                 discoverable by a later invocation) — not a claim that
+//                                 this state occurs in practice.
+export function addCoverToExistingEntry({ cloneDir, project, slug, coverImageBuffer, force = false }) {
+  if (!RE_PROJECT_KEY.test(project) || project.includes('..')) {
+    throw new Error(`Invalid project key: ${JSON.stringify(project)}`);
+  }
+  assertSafeSlug(slug);
+  if (!coverImageBuffer || !Buffer.isBuffer(coverImageBuffer)) {
+    throw new Error('coverImageBuffer is required and must be a Buffer');
+  }
+  if (!existsSync(cloneDir)) throw new Error(`Clone directory not found: ${cloneDir}`);
+  const projectDir = join(cloneDir, project);
+  const manifestPath = join(projectDir, 'manifest.json');
+  if (!existsSync(manifestPath)) {
+    throw new Error(`No manifest found for project "${project}" at ${manifestPath}`);
+  }
+  const manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
+  if (!manifest || !Array.isArray(manifest.entries)) {
+    throw new Error(`Malformed manifest at ${manifestPath}: expected { "entries": [...] }.`);
+  }
+  const idx = manifest.entries.findIndex(
+    (e) => e && (e.version === slug || (e.file && e.file.replace(/\.md$/, '') === slug))
+  );
+  if (idx === -1) {
+    throw new Error(`No manifest row for ${project}/${slug} — cannot add a cover to an entry that doesn't exist.`);
+  }
+  const entry = manifest.entries[idx];
+  if (entry.cover && !force) {
+    throw new Error(`${project}/${slug} already has a cover — pass force: true to overwrite.`);
+  }
+  const coverFile = `${slug}.png`;
+  const destPath = join(projectDir, coverFile);
+  mkdirSync(projectDir, { recursive: true });
+  let written;
+  if (force) {
+    writeFileSync(destPath, coverImageBuffer);
+    written = destPath;
+  } else if (existsSync(destPath) && isValidPng(destPath)) {
+    // Adopt the existing file as the completed result of a hypothetical interrupted prior
+    // write. coverImageBuffer (the staging-dir source the caller already read — a
+    // different file from this clone-destination path) is NOT rewritten over it.
+    written = destPath;
+  } else {
+    writeFileSync(destPath, coverImageBuffer);
+    written = destPath;
+  }
+  const bytes = statSync(written).size;
+  manifest.entries[idx] = { ...entry, cover: { file: coverFile, bytes } };
+  atomicWriteJSON(manifestPath, manifest);
+  return { written, manifestUpdated: true };
 }

package/lib/render_cover.mjs ADDED Viewed

@@ -0,0 +1,156 @@
+// Rasterize a Claude-composed HTML/CSS cover into a fixed-size PNG.
+//
+// This is the one genuinely deterministic, testable function in the cover-generation
+// path — composing the HTML itself is agent behavior, not a library call (see SKILL.md
+// Step 5 / devlog cover-context). Uses headless Chromium (the `playwright` package,
+// never `playwright-core` — the CLI needs the full package so
+// `npx playwright install chromium` works).
+import { chromium } from 'playwright';
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import sharp from 'sharp';
+export const COVER_FONT_FAMILY = 'DevlogCoverFont';
+export const DEFAULT_RENDER_TIMEOUT_MS = 15000;
+const FONT_PATH = join(homedir(), '.claude', 'skills', 'devlog', 'image-style', 'font.ttf');
+const QUANTIZE_TARGET_BYTES = 500 * 1024;
+// Deterministic Node code, never agent-authored text: reads the installed font file and
+// builds a base64 data URI. The font's bytes never pass through Claude's own text
+// generation — a qualitatively different (and much less reliable, at this size) operation
+// than Claude directly viewing reference cover images.
+function readFontBase64(fontPath) {
+  if (!existsSync(fontPath)) {
+    throw new Error(`Cover font not found at ${fontPath} — run \`devlog init\` to install it.`);
+  }
+  let bytes;
+  try {
+    bytes = readFileSync(fontPath);
+  } catch (e) {
+    throw new Error(`Cover font at ${fontPath} could not be read: ${e.message}`);
+  }
+  if (bytes.length === 0) {
+    throw new Error(`Cover font at ${fontPath} is empty (0 bytes) — reinstall it with \`devlog init\`.`);
+  }
+  return bytes.toString('base64');
+}
+// Lossy palette quantization toward a ~300-500KB target. Best-effort: never throws for
+// size reasons, just returns the smallest of the attempts tried. Quantization affects
+// color depth/file size only, never pixel dimensions.
+async function quantize(pngBuffer) {
+  const attempts = [
+    { palette: true, quality: 90, effort: 8 },
+    { palette: true, quality: 70, colors: 128, effort: 8 },
+    { palette: true, quality: 50, colors: 64, effort: 8 },
+  ];
+  let best = pngBuffer;
+  for (const opts of attempts) {
+    let out;
+    try {
+      out = await sharp(pngBuffer).png(opts).toBuffer();
+    } catch {
+      continue; // this attempt's options weren't accepted; fall through to the next
+    }
+    if (out.length < best.length) best = out;
+    if (out.length <= QUANTIZE_TARGET_BYTES) return out;
+  }
+  return best;
+}
+/**
+ * @param {string} html full, self-contained HTML document (must start with <!DOCTYPE html>)
+ * @param {{width:number, height:number, timeoutMs?:number, fontPath?:string, executablePath?:string}} opts
+ * @returns {Promise<Buffer>} PNG bytes, exactly {width}x{height} pixels
+ *
+ * Throws on exactly three realistic failure modes: a render timeout; Chromium not being
+ * installed; a missing/unreadable installed font file. Does NOT throw on malformed HTML —
+ * Chromium's HTML5 parser is deliberately fault-tolerant and recovers into some DOM
+ * regardless of input; a poorly composed document renders wrong, it doesn't fail to render.
+ */
+export async function renderCoverImage(html, opts = {}) {
+  const {
+    width,
+    height,
+    timeoutMs = DEFAULT_RENDER_TIMEOUT_MS,
+    fontPath = FONT_PATH,
+    executablePath,
+    // Test-only seam, not part of the documented contract: lets tests inject a fake
+    // launch() to spy on page.setContent/addStyleTag/evaluate/screenshot call order
+    // without spinning up real Chromium. Defaults to the real playwright launcher.
+    launch = executablePath ? (o) => chromium.launch({ ...o, executablePath }) : (o) => chromium.launch(o),
+  } = opts;
+  if (typeof html !== 'string' || html.trim() === '') {
+    throw new Error('renderCoverImage: html must be a non-empty string');
+  }
+  if (!Number.isInteger(width) || !Number.isInteger(height) || width <= 0 || height <= 0) {
+    throw new Error('renderCoverImage: width/height must be positive integers');
+  }
+  // Read + validate the font BEFORE ever launching Chromium — a missing/corrupt font is a
+  // plain, cheap filesystem check and shouldn't cost a browser launch to detect.
+  const fontBase64 = readFontBase64(fontPath);
+  let browser;
+  try {
+    browser = await launch(undefined);
+  } catch (e) {
+    throw new Error(
+      `Chromium is not installed (or failed to launch) — run \`npx playwright install chromium\`. (${e.message})`
+    );
+  }
+  try {
+    const page = await browser.newPage({ viewport: { width, height } });
+    // Parse Claude's document exactly as authored first, in standards mode — never a raw
+    // string prepend of the font-face rule, which would force quirks mode (per the HTML5
+    // tree-construction algorithm, any non-whitespace content before the DOCTYPE token
+    // does) and risks a same-specificity shadow from Claude's own CSS.
+    await page.setContent(html, { waitUntil: 'load', timeout: timeoutMs });
+    // Inject the real font into the already-parsed document via the DOM API. Landing here
+    // — added after the page's own stylesheets are already parsed — also means this rule
+    // wins any cascade tie against markup referencing the same family, by document order.
+    const fontFaceCss =
+      `@font-face { font-family: '${COVER_FONT_FAMILY}'; ` +
+      `src: url(data:font/ttf;base64,${fontBase64}) format('truetype'); }`;
+    await page.addStyleTag({ content: fontFaceCss });
+    // Merely declaring @font-face does not synchronously start the load — Chromium only
+    // triggers the fetch/decode once a style-recalc discovers text resolving to that
+    // family, and that recalc isn't guaranteed to have run yet. document.fonts.load()
+    // explicitly kicks off the load so the immediately-following document.fonts.ready
+    // check is guaranteed to cover it, closing a real race where the ready-promise could
+    // otherwise resolve before the embedded font has actually finished decoding.
+    const fontsReady = (async () => {
+      await page.evaluate((family) => document.fonts.load(`1em '${family}'`), COVER_FONT_FAMILY);
+      await page.evaluate(() => document.fonts.ready);
+    })();
+    // Attach a no-op handler immediately so a late rejection (e.g. the timeout branch below
+    // wins the race, then this promise itself rejects after the page is torn down) never
+    // surfaces as an unhandled rejection — the race below is still driven by this same
+    // promise reference.
+    fontsReady.catch(() => {});
+    await Promise.race([
+      fontsReady,
+      new Promise((_, reject) =>
+        setTimeout(
+          () => reject(new Error(`renderCoverImage: timed out after ${timeoutMs}ms waiting on font load`)),
+          timeoutMs
+        )
+      ),
+    ]);
+    // Viewport-clipped screenshot (fullPage omitted/false, Playwright's default) — never
+    // fullPage: true, which would capture the whole scrollable page rather than just the
+    // viewport. This is what guarantees the output is always exactly {width, height}
+    // regardless of whether the composed HTML's content overflows it.
+    const png = await page.screenshot({ type: 'png', timeout: timeoutMs });
+    return await quantize(png);
+  } finally {
+    await browser.close();
+  }
+}