@natjswenson/devlog 0.4.2 → 0.5.1

package/lib/core.mjs

@@ -0,0 +1,206 @@
+// Shared config validation, IO, and process helpers for the devlog CLI.
+// Single source of truth: bin/devlog.js re-exports the validators from here so
+// external importers (tests, SKILL.md guidance) keep one canonical definition.
+import { spawnSync } from 'node:child_process';
+import { existsSync, readFileSync, writeFileSync, renameSync, unlinkSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+// SHELL_QUOTE_BREAK matches characters that can break out of a single-quoted
+// shell string OR are dangerous if quoting is omitted. The skill instructs the
+// LLM to single-quote every interpolated value; rejecting these chars upstream
+// guarantees that single-quoting is sufficient. Whitespace, dots, hyphens,
+// equals, and similar are NOT rejected — they're literal inside '...' and are
+// legitimate in human-readable fields like names and paths.
+//
+// For strict-token fields (project keys, repo names, branch names), separate
+// allowlist regexes apply additional structural constraints.
+export const SHELL_QUOTE_BREAK = /[;&|`$()<>{}[\]*?!#~"'\\\n\r]/;
+export const RE_GH_USER = /^[a-z0-9][a-z0-9-]*$/i;
+export const RE_REPO_NAME = /^[a-z0-9][a-z0-9._-]*$/i;
+export const RE_OWNER_REPO = /^[a-z0-9][a-z0-9._-]*\/[a-z0-9][a-z0-9._-]*$/i;
+export const RE_PROJECT_KEY = /^[a-z0-9][a-z0-9._-]*$/i;
+export const RE_BRANCH = /^[a-z0-9][a-z0-9._/-]*$/i;
+// Repo-relative subdir used to scope `git log` to one skill in a monorepo.
+// Same shape as a branch: no leading dash/slash, no shell metacharacters.
+export const RE_PATH_FILTER = /^[a-z0-9][a-z0-9._/-]*$/i;
+// Git tag prefix that marks a project's releases (e.g. `v` or `devlog-v`).
+// Interpolated into `git tag --list '<tagPrefix>*'`; same safety as a path filter.
+export const RE_TAG_PREFIX = /^[a-z0-9][a-z0-9._/-]*$/i;
+export const FORBIDDEN_BRANCH_PARTS = /(^|\/)\.\.($|\/)/; // reject `..` as a path component
+
+// A final-release version label: `v` + digits and dots only. Prereleases
+// (v1.0.0-rc.1) and build metadata (v1.0.0+build) are excluded by design —
+// they must never get an entry or serve as a range base.
+export const RE_FINAL_RELEASE = /^v[0-9]+(\.[0-9]+)*$/;
+
+export const CONFIG_DIR = join(homedir(), '.claude', 'skills', 'devlog');
+export const CONFIG_PATH = join(CONFIG_DIR, 'config.json');
+
+export const DEEP_DIVE_DEFAULTS = Object.freeze({
+  topicDomains: Object.freeze(['AI', 'DevOps/SRE', 'software engineering']),
+  minSources: 3,
+});
+
+export function expandHome(p) {
+  if (!p) return p;
+  if (p === '~') return homedir();
+  if (p.startsWith('~/')) return join(homedir(), p.slice(2));
+  return p;
+}
+
+// argv-style invocation; no shell, so user-supplied args cannot inject.
+// Returns trimmed stdout on exit 0, null otherwise.
+export function execArgs(cmd, args, opts = {}) {
+  const r = spawnArgs(cmd, args, opts);
+  return r.status === 0 ? r.stdout : null;
+}
+
+// Like execArgs but returns { status, stdout, stderr } for callers that need
+// to distinguish failure modes (e.g. a gh 404 vs a network error).
+export function spawnArgs(cmd, args, opts = {}) {
+  try {
+    const r = spawnSync(cmd, args, { stdio: ['ignore', 'pipe', 'pipe'], encoding: 'utf8', ...opts });
+    return {
+      status: r.status ?? 1,
+      stdout: (r.stdout || '').trim(),
+      stderr: (r.stderr || '').trim(),
+    };
+  } catch (e) {
+    return { status: 1, stdout: '', stderr: String(e && e.message || e) };
+  }
+}
+
+// Atomic write: write to sibling tmp file then rename.
+// Prevents readers from seeing a half-written config if process is killed mid-write.
+// Uses `wx` (exclusive create) flag to prevent symlink-attack on shared filesystems
+// — if an attacker pre-creates the tmp file, our write fails rather than following
+// the symlink to a sensitive target.
+export function atomicWriteJSON(path, data) {
+  const tmp = path + '.tmp.' + process.pid + '.' + Date.now();
+  writeFileSync(tmp, JSON.stringify(data, null, 2) + '\n', { mode: 0o600, flag: 'wx' });
+  try {
+    renameSync(tmp, path);
+  } catch (e) {
+    try { unlinkSync(tmp); } catch {}
+    throw e;
+  }
+}
+
+export function readConfig(path = CONFIG_PATH) {
+  if (!existsSync(path)) return null;
+  return JSON.parse(readFileSync(path, 'utf8'));
+}
+
+// Validate a config object before writing. Throws with a user-facing message on failure.
+export function validateConfig(config) {
+  if (!config || typeof config !== 'object') throw new Error('Config must be an object');
+  const required = ['targetRepo', 'gitAuthor', 'githubUser', 'projects'];
+  for (const k of required) {
+    if (!(k in config)) throw new Error(`Missing required field: ${k}`);
+  }
+  if (!RE_OWNER_REPO.test(config.targetRepo)) {
+    throw new Error(`targetRepo must match <owner>/<repo>: got ${JSON.stringify(config.targetRepo)}`);
+  }
+  if (typeof config.gitAuthor !== 'string' || config.gitAuthor.length === 0 || SHELL_QUOTE_BREAK.test(config.gitAuthor)) {
+    throw new Error(`gitAuthor must be non-empty and contain no shell metacharacters: got ${JSON.stringify(config.gitAuthor)}`);
+  }
+  if (!RE_GH_USER.test(config.githubUser)) {
+    throw new Error(`githubUser must match GitHub username pattern: got ${JSON.stringify(config.githubUser)}`);
+  }
+  if ('branch' in config) {
+    if (!RE_BRANCH.test(config.branch) || FORBIDDEN_BRANCH_PARTS.test(config.branch)) {
+      throw new Error(`branch must be a valid git branch name (no leading dash, no '..'): got ${JSON.stringify(config.branch)}`);
+    }
+  }
+  if ('voicePath' in config) {
+    // Optional: directory holding the voice profile used to write entries. Read by
+    // the skill with the Read tool only — never shell-interpolated — so the only
+    // hard requirement is no shell metacharacters and no leading dash. A leading `~`
+    // is allowed (the skill expands it); we test the expanded form so an absolute
+    // path has no `~` left to trip the shell-quote-break check. Existence is checked
+    // at prompt time (and at runtime, with a fallback chain), not here.
+    const expanded = typeof config.voicePath === 'string' ? expandHome(config.voicePath) : config.voicePath;
+    if (typeof config.voicePath !== 'string' || SHELL_QUOTE_BREAK.test(expanded) || expanded.trim().startsWith('-')) {
+      throw new Error(`voicePath must be a path with no shell metacharacters and no leading dash: got ${JSON.stringify(config.voicePath)}`);
+    }
+  }
+  if ('deepDive' in config) {
+    const d = config.deepDive;
+    if (!d || typeof d !== 'object' || Array.isArray(d)) throw new Error('deepDive must be an object');
+    if ('minSources' in d) {
+      if (!Number.isInteger(d.minSources) || d.minSources < 1 || d.minSources > 10) {
+        throw new Error(`deepDive.minSources must be an integer 1-10: got ${JSON.stringify(d.minSources)}`);
+      }
+    }
+    if ('topicDomains' in d) {
+      if (!Array.isArray(d.topicDomains) || d.topicDomains.length === 0
+        || d.topicDomains.some((t) => typeof t !== 'string' || t.length === 0 || t.length > 100 || /[\x00-\x1f]/.test(t))) {
+        throw new Error('deepDive.topicDomains must be a non-empty array of short strings');
+      }
+    }
+  }
+  if (!Array.isArray(config.projects)) {
+    throw new Error('projects must be an array');
+  }
+  const seenKeys = new Set();
+  for (const p of config.projects) {
+    if (!p || typeof p !== 'object') throw new Error('Each project must be an object');
+    if (!RE_PROJECT_KEY.test(p.key) || p.key.includes('..')) {
+      throw new Error(`project.key invalid: ${JSON.stringify(p.key)}`);
+    }
+    if (seenKeys.has(p.key)) throw new Error(`Duplicate project key: ${JSON.stringify(p.key)}`);
+    seenKeys.add(p.key);
+    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)) {
+      throw new Error(`project.remote must match <owner>/<repo>: ${JSON.stringify(p.remote)}`);
+    }
+    if ('pathFilter' in p) {
+      // Optional: scope this project's commits to a repo subdirectory (e.g. a
+      // single skill in a monorepo). Interpolated into `git log -- <pathFilter>`,
+      // so enforce the same no-metacharacter / no-`..` safety as branch names.
+      if (typeof p.pathFilter !== 'string' || !RE_PATH_FILTER.test(p.pathFilter) || FORBIDDEN_BRANCH_PARTS.test(p.pathFilter)) {
+        throw new Error(`project.pathFilter must be a repo-relative subdir (no leading dash/slash, no '..', no shell metacharacters): ${JSON.stringify(p.pathFilter)}`);
+      }
+    }
+    if ('tagPrefix' in p) {
+      // Optional: the prefix of the git tags that mark this project's releases
+      // (e.g. `devlog-v`). Interpolated into `git tag --list '<tagPrefix>*'`, so
+      // enforce the same no-metacharacter / no-`..` safety as path filters.
+      if (typeof p.tagPrefix !== 'string' || !RE_TAG_PREFIX.test(p.tagPrefix) || FORBIDDEN_BRANCH_PARTS.test(p.tagPrefix)) {
+        throw new Error(`project.tagPrefix must be a tag prefix (no leading dash/slash, no '..', no shell metacharacters): ${JSON.stringify(p.tagPrefix)}`);
+      }
+    }
+    if ('label' in p) {
+      // Label is rendered as React text content only — never shell-interpolated,
+      // never used in URLs, never used as a filesystem path. React escapes all
+      // text content. Therefore: any string is safe. Apostrophes (e.g.
+      // "Mom I'm Bored") and unicode are legitimate label content.
+      // INVARIANT: if a future change makes label flow into shell or innerHTML,
+      // tighten this validation to SHELL_QUOTE_BREAK at the same time.
+      if (typeof p.label !== 'string') throw new Error(`project.label must be a string if present`);
+      if (p.label.length > 200) throw new Error(`project.label too long (max 200 chars)`);
+      if (/[\x00-\x1f]/.test(p.label)) throw new Error(`project.label contains control characters`);
+    }
+  }
+  return config;
+}
+
+// Resolve the effective deepDive settings (user values over defaults).
+export function resolveDeepDive(config) {
+  const d = (config && config.deepDive) || {};
+  return {
+    topicDomains: Array.isArray(d.topicDomains) && d.topicDomains.length ? d.topicDomains : [...DEEP_DIVE_DEFAULTS.topicDomains],
+    minSources: Number.isInteger(d.minSources) ? d.minSources : DEEP_DIVE_DEFAULTS.minSources,
+  };
+}
+
+// True when a git remote URL points at <owner>/<repo> on any common transport
+// (https://github.com/o/r.git, git@github.com:o/r.git, ssh://git@github.com/o/r).
+export function remoteUrlMatches(url, ownerRepo) {
+  if (!url || !ownerRepo) return false;
+  const m = url.match(/[:/]([^/:]+\/[^/]+?)(?:\.git)?$/);
+  return !!m && m[1].toLowerCase() === ownerRepo.toLowerCase();
+}

package/lib/lint_post.mjs

@@ -0,0 +1,152 @@
+// Deterministic post-contract lint. This is the mechanically-checkable subset
+// of the how-to quality contract in SKILL.md Step 6; the judgment calls
+// (reproducibility, gotcha quality, voice) belong to the self-review rubric
+// and the eval judge, not here.
+import { basename } from 'node:path';
+import { RE_FINAL_RELEASE } from './core.mjs';
+
+export const FRONTMATTER_KEYS = ['title', 'date', 'project', 'version', 'tags', 'summary'];
+export const REQUIRED_SECTIONS = ['Shipped', 'Gotchas', 'Sources'];
+
+const RE_DATE = /^\d{4}-\d{2}-\d{2}$/;
+
+// 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.
+export function parseFrontmatter(content) {
+  const lines = content.split('\n');
+  if (lines[0]?.trim() !== '---') return { data: null, body: content };
+  const end = lines.findIndex((l, i) => i > 0 && l.trim() === '---');
+  if (end === -1) return { data: null, body: content };
+
+  const data = Object.create(null);
+  for (const line of lines.slice(1, end)) {
+    const m = /^([A-Za-z_][A-Za-z0-9_-]*):\s*(.*)$/.exec(line);
+    if (!m) continue;
+    data[m[1]] = parseScalar(m[2]);
+  }
+  return { data, body: lines.slice(end + 1).join('\n') };
+}
+
+function parseScalar(raw) {
+  const v = raw.trim();
+  if ((v.startsWith('"') && v.endsWith('"') && v.length >= 2)
+    || (v.startsWith("'") && v.endsWith("'") && v.length >= 2)) {
+    return v.slice(1, -1);
+  }
+  if (v.startsWith('[') && v.endsWith(']')) {
+    const inner = v.slice(1, -1).trim();
+    if (inner === '') return [];
+    return inner.split(',').map((t) => parseScalar(t));
+  }
+  return v;
+}
+
+// Split the body into sections keyed by `## ` heading, ignoring headings
+// inside fenced code blocks. Returns [{ heading, content }].
+export function splitSections(body) {
+  const sections = [];
+  let current = null;
+  let inFence = false;
+  for (const line of body.split('\n')) {
+    if (/^```/.test(line)) inFence = !inFence;
+    const h = !inFence && /^##\s+(.+?)\s*$/.exec(line);
+    if (h && !line.startsWith('###')) {
+      current = { heading: h[1], content: [] };
+      sections.push(current);
+    } else if (current) {
+      current.content.push(line);
+    }
+  }
+  return sections.map((s) => ({ heading: s.heading, content: s.content.join('\n') }));
+}
+
+// Every opening code fence must carry a language tag. Returns 1-based line
+// numbers of untagged openers.
+export function findUntaggedFences(body) {
+  const untagged = [];
+  let inFence = false;
+  body.split('\n').forEach((line, i) => {
+    const m = /^```(.*)$/.exec(line);
+    if (!m) return;
+    if (!inFence) {
+      if (m[1].trim() === '') untagged.push(i + 1);
+      inFence = true;
+    } else {
+      inFence = false;
+    }
+  });
+  return untagged;
+}
+
+export function extractSourceUrls(sectionContent) {
+  const urls = new Set();
+  for (const m of sectionContent.matchAll(/\]\((https?:\/\/[^)\s]+)\)/g)) {
+    urls.add(m[1]);
+  }
+  return urls;
+}
+
+// Lint a post. Returns { ok, findings: [{ rule, message }] }.
+export function lintPost(content, { minSources = 3, filename = null } = {}) {
+  const findings = [];
+  const add = (rule, message) => findings.push({ rule, message });
+
+  const { data, body } = parseFrontmatter(content);
+  if (!data) {
+    add('frontmatter-missing', 'Post must start with a `---` frontmatter block.');
+    return { ok: false, findings };
+  }
+
+  for (const key of FRONTMATTER_KEYS) {
+    const v = data[key];
+    const empty = v === undefined || v === '' || (Array.isArray(v) && v.length === 0);
+    if (empty) add(`frontmatter-${key}`, `Frontmatter field \`${key}\` is missing or empty.`);
+  }
+
+  if (typeof data.date === 'string' && data.date && !RE_DATE.test(data.date)) {
+    add('date-format', `\`date\` must be YYYY-MM-DD: got ${JSON.stringify(data.date)}.`);
+  }
+  if (typeof data.version === 'string' && data.version && !RE_FINAL_RELEASE.test(data.version)) {
+    add('version-format', `\`version\` must match v<digits.digits...>: got ${JSON.stringify(data.version)}.`);
+  }
+  if (typeof data.title === 'string' && data.title) {
+    if (/^release\s+v/i.test(data.title) || data.title.trim() === data.version) {
+      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 (filename && typeof data.version === 'string' && data.version) {
+    const expected = `${data.version}.md`;
+    if (basename(filename) !== expected) {
+      add('filename-version', `Filename must be \`${expected}\` (got \`${basename(filename)}\`).`);
+    }
+  }
+
+  const sections = splitSections(body);
+  const byHeading = new Map(sections.map((s) => [s.heading, s]));
+  for (const name of REQUIRED_SECTIONS) {
+    if (!byHeading.has(name)) add(`section-${name.toLowerCase()}`, `Missing required \`## ${name}\` section.`);
+  }
+
+  const gotchas = byHeading.get('Gotchas');
+  if (gotchas && gotchas.content.replace(/\s/g, '').length < 40) {
+    add('gotchas-empty', 'The `## Gotchas` section is present but effectively empty.');
+  }
+
+  const sources = byHeading.get('Sources');
+  if (sources) {
+    const urls = extractSourceUrls(sources.content);
+    if (urls.size < minSources) {
+      add('sources-count', `Need at least ${minSources} distinct source URLs; found ${urls.size}.`);
+    }
+  }
+
+  for (const line of findUntaggedFences(body)) {
+    add('fence-untagged', `Code fence at body line ${line} has no language tag.`);
+  }
+
+  return { ok: findings.length === 0, findings };
+}

package/lib/publish_entry.mjs

@@ -0,0 +1,71 @@
+// Move a drafted entry into the target-repo clone and update the project's
+// 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 { join } from 'node:path';
+import { RE_PROJECT_KEY, RE_FINAL_RELEASE, atomicWriteJSON } from './core.mjs';
+import { parseFrontmatter } from './lint_post.mjs';
+
+// Newest-first by date; ties keep insertion order (Array.prototype.sort is
+// stable). Date order is normally also version order, but a backported tag
+// (v1.9.1 tagged after v2.0.0) can diverge — sorting by date matches how the
+// feed renders.
+function sortEntries(entries) {
+  return entries.slice().sort((a, b) => String(b.date).localeCompare(String(a.date)));
+}
+
+export function publishEntry({ cloneDir, project, version, entryPath }) {
+  if (!RE_PROJECT_KEY.test(project) || project.includes('..')) {
+    throw new Error(`Invalid project key: ${JSON.stringify(project)}`);
+  }
+  if (!RE_FINAL_RELEASE.test(version)) {
+    throw new Error(`Invalid version label (must be v<digits.digits...>): ${JSON.stringify(version)}`);
+  }
+  if (!existsSync(cloneDir)) throw new Error(`Clone directory not found: ${cloneDir}`);
+  if (!existsSync(entryPath)) throw new Error(`Entry draft not found: ${entryPath}`);
+
+  const projectDir = join(cloneDir, project);
+  const destPath = join(projectDir, `${version}.md`);
+  if (existsSync(destPath)) {
+    throw new Error(`Entry ${project}/${version}.md already exists — a cut release is immutable, refusing to overwrite.`);
+  }
+
+  const content = readFileSync(entryPath, 'utf8');
+  const { data } = parseFrontmatter(content);
+  if (!data || !data.title || !data.date || !data.summary) {
+    throw new Error('Entry frontmatter must include title, date, and summary (run lint-post first).');
+  }
+
+  mkdirSync(projectDir, { recursive: true });
+  copyFileSync(entryPath, destPath);
+
+  const manifestPath = join(projectDir, 'manifest.json');
+  let manifest = { entries: [] };
+  if (existsSync(manifestPath)) {
+    manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
+    if (!manifest || !Array.isArray(manifest.entries)) {
+      throw new Error(`Malformed manifest at ${manifestPath}: expected { "entries": [...] }.`);
+    }
+  }
+
+  const file = `${version}.md`;
+  // Idempotent: legacy manifests may already reference this file/version even
+  // when the .md was missing — never duplicate an index row.
+  const already = manifest.entries.some((e) => e && (e.file === file || e.version === version));
+  let manifestUpdated = false;
+  if (!already) {
+    manifest.entries.push({
+      date: String(data.date),
+      file,
+      title: String(data.title),
+      summary: String(data.summary),
+      version,
+    });
+    manifest.entries = sortEntries(manifest.entries);
+    atomicWriteJSON(manifestPath, manifest);
+    manifestUpdated = true;
+  }
+
+  return { written: destPath, manifestUpdated };
+}

package/lib/scan.mjs

@@ -0,0 +1,229 @@
+// Release discovery: turns config + local git state into a JSON plan of the
+// entries /devlog should write. Replaces the hand-rolled bash steps the skill
+// used to run — tag names never pass through a shell here (spawnSync argv only),
+// and the semver/range logic is unit-testable.
+import { existsSync } from 'node:fs';
+import {
+  SHELL_QUOTE_BREAK,
+  RE_FINAL_RELEASE,
+  execArgs,
+  spawnArgs,
+  remoteUrlMatches,
+  resolveDeepDive,
+} from './core.mjs';
+
+const DIFFSTAT_MAX_CHARS = 5000;
+
+// The version label is the substring of the tag starting at the first `v`
+// that is followed by a digit: `devlog-v0.2.0` → `v0.2.0`, `v1.4.0` → `v1.4.0`.
+// Returns null when the tag has no such sequence (e.g. `version-bump`).
+export function deriveVersionLabel(tag) {
+  const m = /v(?=\d)/.exec(tag);
+  return m ? tag.slice(m.index) : null;
+}
+
+// Tag names come from `git tag --list` and are attacker-influenceable (anyone
+// who can push a tag controls them). Even though this module never puts them
+// through a shell, unsafe names are excluded outright so downstream consumers
+// (the skill, filenames, URLs) never see them.
+export function isSafeTagName(tag) {
+  return typeof tag === 'string' && tag.length > 0 && tag.length <= 200
+    && !SHELL_QUOTE_BREAK.test(tag) && !tag.startsWith('-');
+}
+
+export function isFinalRelease(label) {
+  return typeof label === 'string' && RE_FINAL_RELEASE.test(label);
+}
+
+// Partition a descending (`--sort=-v:refname`) tag list into final releases
+// and skipped tags with reasons. Order is preserved, so releases[i + 1] is the
+// range base (prevTag) of releases[i].
+export function selectReleases(tags) {
+  const releases = [];
+  const skipped = [];
+  for (const tag of tags) {
+    if (!isSafeTagName(tag)) {
+      skipped.push({ tag, reason: 'unsafe-name' });
+      continue;
+    }
+    const version = deriveVersionLabel(tag);
+    if (!version) {
+      skipped.push({ tag, reason: 'non-release' });
+      continue;
+    }
+    if (!isFinalRelease(version)) {
+      const reason = version.includes('-') ? 'prerelease'
+        : version.includes('+') ? 'build-metadata' : 'non-final';
+      skipped.push({ tag, reason });
+      continue;
+    }
+    releases.push({ tag, version });
+  }
+  return { releases, skipped };
+}
+
+function git(projectPath, args) {
+  return execArgs('git', ['-C', projectPath, ...args]);
+}
+
+// Scan one project's local clone. Pure git — the caller supplies the set of
+// entry filenames that already exist in the target repo (existingFiles), so
+// this function stays testable against throwaway fixture repos.
+export function scanProject(project, { branch = 'main', fetch = true, existingFiles = new Set() } = {}) {
+  const out = {
+    key: project.key,
+    label: project.label || project.key,
+    remote: project.remote,
+    path: project.path,
+    pathFilter: project.pathFilter || null,
+    tagPrefix: project.tagPrefix || 'v',
+    tagFetch: 'skipped',
+    newReleases: [],
+    skippedTags: [],
+    error: null,
+  };
+
+  if (!existsSync(project.path)) {
+    out.error = 'path-missing';
+    return out;
+  }
+
+  if (fetch) {
+    // Best-effort: releases are commonly cut by CI on the remote, so the tag is
+    // born there. Offline / no-remote / auth failures degrade to local tags.
+    const r = spawnArgs('git', ['-C', project.path, 'fetch', '--tags', '--quiet']);
+    out.tagFetch = r.status === 0 ? 'ok' : 'failed';
+  }
+
+  const listed = git(project.path, ['tag', '--list', `${out.tagPrefix}*`, '--sort=-v:refname']);
+  const tags = listed ? listed.split('\n').filter(Boolean) : [];
+  const { releases, skipped } = selectReleases(tags);
+  out.skippedTags.push(...skipped);
+
+  // Publicness scaffolding, computed once per project.
+  const originUrl = git(project.path, ['remote', 'get-url', 'origin']);
+  const remoteMatches = remoteUrlMatches(originUrl, project.remote);
+  const publishedRef = `refs/remotes/origin/${branch}`;
+  const hasPublishedRef = git(project.path, ['rev-parse', '--verify', '--quiet', publishedRef]) !== null;
+
+  const isPublic = (rev) => {
+    if (!remoteMatches || !hasPublishedRef) return false;
+    return spawnArgs('git', ['-C', project.path, 'merge-base', '--is-ancestor', rev, publishedRef]).status === 0;
+  };
+
+  for (let i = 0; i < releases.length; i++) {
+    const { tag, version } = releases[i];
+    if (existingFiles.has(`${version}.md`)) {
+      out.skippedTags.push({ tag, reason: 'entry-exists' });
+      continue;
+    }
+
+    // prevTag comes from the FILTERED final-release list only — never a raw
+    // prerelease or non-release tag — so ranges are always release-to-release.
+    const prevTag = releases[i + 1]?.tag ?? null;
+    const range = prevTag ? `${prevTag}..${tag}` : tag;
+    const logArgs = ['log', range, '--format=%H|%s|%cs'];
+    if (project.pathFilter) logArgs.push('--', project.pathFilter);
+    const logOut = git(project.path, logArgs);
+    if (logOut === null) {
+      out.skippedTags.push({ tag, reason: 'log-failed' });
+      continue;
+    }
+
+    const lines = logOut.split('\n').filter(Boolean);
+    if (lines.length === 0) {
+      // Nothing shipped for this project in that version (common under
+      // pathFilter in a monorepo when the tag belongs to another subdir).
+      out.skippedTags.push({ tag, reason: 'empty-range' });
+      continue;
+    }
+
+    // Fast path: if the tag's commit is on the published branch, every commit
+    // in the range (all reachable from the tag) is public — one git call
+    // instead of one per commit.
+    const tagPublic = isPublic(`${tag}^{commit}`);
+    const commits = lines.map((line) => {
+      const [hash, subject, date] = splitLogLine(line);
+      return { hash, subject, date, public: tagPublic || isPublic(hash) };
+    });
+
+    const release = {
+      tag,
+      version,
+      date: git(project.path, ['log', '-1', '--format=%cs', `${tag}^{commit}`]) || null,
+      prevTag,
+      commits,
+    };
+
+    if (prevTag) {
+      const diffArgs = ['diff', '--stat', '--stat-count=40', range];
+      if (project.pathFilter) diffArgs.push('--', project.pathFilter);
+      const stat = git(project.path, diffArgs);
+      if (stat) release.diffstat = stat.slice(0, DIFFSTAT_MAX_CHARS);
+    }
+
+    out.newReleases.push(release);
+  }
+
+  return out;
+}
+
+// `%H|%s|%cs` — the subject may itself contain `|`, so split off the leading
+// hash and trailing date and keep everything between as the subject.
+function splitLogLine(line) {
+  const first = line.indexOf('|');
+  const last = line.lastIndexOf('|');
+  const hash = line.slice(0, first);
+  const subject = line.slice(first + 1, last);
+  const date = line.slice(last + 1);
+  return [hash, subject, date];
+}
+
+// Which entry files already exist in the target repo for one project — a
+// single `gh api` directory listing (vs. the old one-probe-per-tag pattern).
+// Returns { files: Set, status: 'ok' | 'empty' | 'failed' }: a 404 means the
+// project has no entries yet; any other failure is surfaced so the caller
+// knows the entry-exists filter may be incomplete (publish-entry still refuses
+// overwrites against the fresh clone, so a stale scan cannot clobber anything).
+export function fetchExistingEntries(targetRepo, branch, projectKey) {
+  const r = spawnArgs('gh', ['api', `repos/${targetRepo}/contents/${projectKey}?ref=${branch}`, '--jq', '.[].name']);
+  if (r.status === 0) {
+    return { files: new Set(r.stdout.split('\n').filter(Boolean)), status: 'ok' };
+  }
+  if (/HTTP 404|Not Found/i.test(r.stderr)) {
+    return { files: new Set(), status: 'empty' };
+  }
+  return { files: new Set(), status: 'failed' };
+}
+
+// Full scan across the configured projects. `getExisting` is injectable for
+// tests; production uses fetchExistingEntries against the GitHub API.
+export function scanAll(config, { projectKey = null, fetch = true, getExisting = fetchExistingEntries } = {}) {
+  const branch = config.branch || 'main';
+  let projects = config.projects;
+  if (projectKey) {
+    projects = projects.filter((p) => p.key === projectKey);
+    if (projects.length === 0) {
+      return {
+        error: `unknown-project: ${projectKey}`,
+        availableKeys: config.projects.map((p) => p.key),
+      };
+    }
+  }
+
+  const results = projects.map((project) => {
+    const existing = getExisting(config.targetRepo, branch, project.key);
+    const scanned = scanProject(project, { branch, fetch, existingFiles: existing.files });
+    scanned.existenceCheck = existing.status;
+    return scanned;
+  });
+
+  return {
+    targetRepo: config.targetRepo,
+    branch,
+    deepDive: resolveDeepDive(config),
+    voicePath: config.voicePath || null,
+    projects: results,
+    totalNewReleases: results.reduce((n, p) => n + p.newReleases.length, 0),
+  };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@natjswenson/devlog",
-  "version": "0.4.2",
+  "version": "0.5.1",
   "description": "Release dev log generator \u2014 Claude Code skill + preview app for publishing version-release dev logs, written in your voice, to your site",
   "license": "MIT",
   "author": "Nate Swenson",
@@ -27,6 +27,9 @@
   },
   "files": [
     "bin/",
+    "lib/",
+    "evals/",
+    "skill-invariants.json",
     "preview/",
     "examples/",
     "voice/",