npm - @natjswenson/devlog - Versions diffs - 0.4.0 → 0.4.1 - Mend

@natjswenson/devlog 0.4.0 → 0.4.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 (4) hide show

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@natjswenson/devlog",
-  "version": "0.4.0",
+  "version": "0.4.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",

package/CHANGELOG.md DELETED Viewed

@@ -1,164 +0,0 @@
-# Changelog
-All notable changes to `@natjswenson/devlog` are documented here.
-## 0.4.0 (2026-06-28) — researched, end-to-end implementation-guide posts
-**Changed**
-- `/devlog` now writes each release entry as a researched, cited, end-to-end
-  implementation guide rather than a narrative summary of what shipped. Step 6
-  derives the engineering topic(s) the work touched, researches them against
-  reputable outside sources (cited inline and in a `## Sources` section), and
-  writes a setup → build → use → verify walkthrough with multiple
-  copy-paste-reusable, language-tagged code blocks that together form a complete,
-  runnable whole (right-sized: roughly 3-6 essential blocks for a substantive
-  feature, fewer for a small change, never padded). A short `## Shipped` hook
-  still opens the post and `## Changelog` still closes it. Updated the skill
-  description and the Step 6 / 6a-6c guidance accordingly.
-**Added**
-- `deepDive` config block: `topicDomains` (default: AI, DevOps/SRE, software
-  engineering) and `minSources` (default 2) to steer topic selection and the
-  citation floor. Repo-agnostic; user-supplied values live in `config.json`.
-## 0.3.1 (2026-06-20) — fetch tags before discovering releases
-**Fixed**
-- `/devlog` now runs a best-effort `git fetch --tags --quiet` per project at the
-  start of release discovery (Step 3), before listing tags. Releases are
-  commonly cut by CI on the remote (a version-driven GitHub Release on green
-  `main`/`master`), so the tag is born on the remote; a local clone that hadn't
-  fetched would list only stale local tags and silently report "no new release"
-  for a release that was already live. The fetch is best-effort: on failure
-  (offline, no remote, auth prompt) it notes the failure and proceeds on local
-  tags rather than aborting. `--tags` takes no untrusted input and `project.path`
-  is validated + single-quoted per Step 0.5.
-## 0.3.0 (2026-06-18) — release-focused entries, written in your voice
-**Changed (behavior)**
-- `/devlog` now generates one entry **per version release** (a semver git tag) instead of
-  one entry per day. An entry summarizes the commits in a release's tag range
-  (`<prevTag>..<thisTag>`), scoped by `pathFilter` when present. The run is **idempotent**:
-  a release's entry is written once and never overwritten, and re-running produces nothing
-  until a new tag is cut. The per-day "Update — HH:MM" append mode is removed.
-- Entries are keyed by version: `<project-key>/<version>.md` (e.g. `v0.2.0.md`), with a
-  `version` field added to the frontmatter and to each `manifest.json` entry. Entry sections
-  are now **What Shipped / What's Next / Commits**. The entry `date` is the tag's commit date.
-**Added**
-- **Voice-driven publishing.** Entries are written in the user's voice using a voice profile
-  resolved in this order: `config.voicePath` → `~/.claude/skills/ghostwriter/voice` (if
-  installed) → a bundled fallback at `~/.claude/skills/devlog/voice/`. devlog reads
-  `voice-profile.md` and `voice-notes.md` (overrides) — and never `algorithm.md`, since
-  LinkedIn reach tuning does not apply to a dev log.
-- `voicePath` (top-level, optional) and `projects[].tagPrefix` (optional, default `v`) config
-  fields, with security validation in both `bin/devlog.js` and SKILL.md. `tagPrefix` lets each
-  project in a monorepo detect its own releases (e.g. `devlog-v`, `ghostwriter-v`).
-- `init` prompts for the voice directory and release tag prefix, and installs the bundled
-  voice template. `config` shows the voice path and each project's tag pattern.
-- The React example carries the optional `version` field through frontmatter parsing and
-  manifest validation.
-**Migration note:** existing per-day `YYYY-MM-DD.md` entries are left untouched; new entries
-are per-release. To detect a monorepo project's releases, set its `tagPrefix`.
-## 0.2.0 (2026-06-08) — monorepo subdirectory filtering
-**Added**
-- `projects[].pathFilter` config field: scope a project's commits to a repo-relative
-  subdirectory (e.g. `skills/devlog`). Lets several logical projects share one monorepo
-  `path`/`remote` while each collects only its own subtree's commits. `git log` gains a
-  `-- <pathFilter>` pathspec; commit links still resolve to `<remote>/commit/<hash>`.
-- SKILL.md documents the field, its security validation (no leading `-`/`/`, no `..`,
-  single-quoted), and the multi-skill monorepo workflow.
-- `bin/devlog.js` validates `pathFilter` and shows it as `scope:` in `devlog config`.
-## 0.1.9 (2026-06-05) — accessibility fix
-**Accessibility**
-- The drop-in React component (`examples/react/DevLogPage.jsx`) now exposes the expand/collapse entries as a proper disclosure control. Previously they were mouse-only — a bare `onClick` on `<article>` with no `role`, `tabIndex`, `aria-expanded`, or keyboard handler, so keyboard and screen-reader users could not operate the feed.
-  - The header carries `role="button"`, `tabIndex={0}`, `aria-expanded`, and `aria-controls` for screen-reader toggle semantics.
-  - `Enter`/`Space` toggle the focused entry (`preventDefault` on Space stops page scroll).
-  - `:focus-visible` outline makes keyboard focus visible.
-  - The toggle moved from the whole card to the header, so links inside an expanded entry are no longer nested in an interactive ancestor and text selection in the body works normally.
-- Visuals are unchanged: padding/hover/cursor moved from `.devlog-entry` to `.devlog-header`, with the redundant content padding zeroed so spacing matches.
-## 0.1.8 (2026-05-01) — final hardening pass
-Closes the four Low-Hardening findings from the second adversarial verification:
-- **L-1:** `validateConfig` now bounds `projects[].label` length (≤200 chars) and rejects control characters. Label apostrophes/quotes/etc are intentionally allowed since label is React text content only — never shell-interpolated. The validator includes an explicit invariant comment to keep this guarantee load-bearing.
-- **L-2:** `atomicWriteJSON` uses `wx` (exclusive create) flag, preventing symlink-attack scenarios on shared filesystems where another local user could pre-create the tmp file.
-- **L-3:** `atomicWriteJSON` tmp filename now also includes `Date.now()` for additional uniqueness across rapid sequential calls.
-- **L-4:** SKILL.md Step 5 explicitly instructs the LLM to treat fetched dev-log content as data, not instructions — defense against indirect prompt injection from hostile dev-log markdown.
-Verification: a second 6-perspective adversarial agent against HEAD reports zero Critical/High/Medium-Active vulnerabilities remain.
-## 0.1.7 (2026-05-01) — security hardening + UX improvements
-**Security**
-- Tightened `SHELL_METACHARS` to additionally reject whitespace, single-quote, square brackets, equals, and percent
-- Project paths now cannot start with `-` (would be parsed as flag)
-- Added strict validation of the `branch` field (no leading dash, no `..` as a path component)
-- Atomic `config.json` writes (write-to-tmp + rename)
-- CLI no longer forwards arbitrary `VITE_*` env vars to the spawned vite — only `VITE_DEVLOG_*` plus `PATH`/`HOME`/etc.
-- Added `Content-Security-Policy` meta tag to the preview app
-- Explicit `urlTransform` in `react-markdown` rejects `data:`, `blob:`, `javascript:`, `vbscript:`, `file:`, and any non-http(s)/mailto scheme
-- `react-markdown` invoked with `skipHtml` for explicit defense-in-depth
-- `SKILL.md` instructs the LLM to single-quote every interpolated config value (defense-in-depth on top of validation)
-- Production preview builds without env vars show a clear "Setup required" screen instead of attempting demo fetches that would 404
-- `config.json` written with mode `0600`, `~/.claude/skills/devlog/` created with mode `0700`
-- Pinned all dependencies to exact versions (no `^` ranges) to eliminate resolution drift
-**UX**
-- `init` now loops to register multiple projects in a single setup
-- New `add-project` subcommand: `npx @natjswenson/devlog add-project` — register a project without editing config.json by hand
-- New `config` subcommand: `npx @natjswenson/devlog config` — view current config with validation status
-- Init detects when `gh` is authenticated as a different user than `githubUser` and warns
-- Better next-step messaging after init (color, concrete commands)
-- All error messages now include actionable hints (`log.hint`)
-**Docs**
-- New `SECURITY.md` — threat model, audit history, ruled-out attack scenarios, vulnerability reporting flow
-- New `CHANGELOG.md` (this file)
-- README updated with new subcommands and security guarantees section
-## 0.1.6 (2026-05-01) — initial security audit fixes
-Addressed 1 Critical + 3 High findings from the first round of the 6-agent siege:
-- SKILL.md now requires runtime allowlist validation of every config value before shell interpolation
-- CLI switched from `execSync` with template strings to `spawnSync` with argv arrays for any user-input-bearing call
-- `gh repo create` regex hardened against leading-dash flag injection
-- `gitAuthor` validator now rejects shell metachars
-- Schema validation added for `manifest.json`, `VITE_DEVLOG_PROJECTS`, frontmatter (allowlist + `Object.create(null)`)
-- `optimizeDeps` includes for vite to fix react-markdown / react-dom CJS interop in npx layouts
-- Preview vite server bound to localhost only, CORS disabled
-## 0.1.5 (2026-05-01)
-- Corrected live-site URL in README (`natejswenson.com` not `.io`)
-## 0.1.4 (2026-05-01)
-- README troubleshooting section, npm + license badges
-- SKILL.md uses `<config.branch || 'main'>` consistently in push/URL output
-## 0.1.3 (2026-05-01)
-- Expanded `optimizeDeps.include` to cover react/react-dom for npx-installed layouts
-## 0.1.2 (2026-05-01)
-- First `optimizeDeps` fix for `style-to-js` CJS/ESM interop (react-markdown rendering)
-## 0.1.1 (2026-05-01)
-- `projects[].label` and `branch` config fields (optional, with safe defaults)
-## 0.1.0 (2026-05-01)
-- Initial release
-- CLI: `init`, `preview`
-- React drop-in components: `DevLogPage`, `useDevLogEntries`
-- Standalone deployable Vite preview app with snarky demo mode

package/LICENSE DELETED Viewed

@@ -1,21 +0,0 @@
-MIT License
-Copyright (c) 2026 Nate Swenson
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.

package/README.md DELETED Viewed

@@ -1,240 +0,0 @@
-# devlog
-[![npm](https://img.shields.io/npm/v/@natjswenson/devlog?color=blue)](https://www.npmjs.com/package/@natjswenson/devlog)
-[![license](https://img.shields.io/npm/l/@natjswenson/devlog)](./LICENSE)
-[![security](https://img.shields.io/badge/security-audited-green)](./SECURITY.md)
-[![vulnerabilities](https://img.shields.io/badge/npm%20audit-0%20issues-brightgreen)](#security)
-A Claude Code skill that turns each version release (a git tag) into a published dev log entry, written in your own voice — and a React example for displaying it on your site.
-> **Build in public, by release.** Tag a release like you always do. Run `/devlog`. Each new version shows up on your site as a narrative entry — in your voice — not raw commit messages.
-## Live example
-The skill is in production at [natejswenson.com/devlog](https://natejswenson.com/devlog), publishing to [github.com/natejswenson/daily-dev-log](https://github.com/natejswenson/daily-dev-log). What you see on that page is exactly what `npx @natjswenson/devlog preview` renders for you locally.
-## How it works
-1. **You ship a release** — tag it (e.g. `git tag v0.3.0`), like you already do.
-2. **Run `/devlog` in Claude Code.** The skill finds tags that don't yet have an entry, summarizes each release's changes into a narrative markdown entry written in your voice, and pushes it to your dev-log GitHub repo. It's idempotent — re-running does nothing until you cut a new release.
-3. **Your site fetches it.** Static `manifest.json` + per-release markdown files served from `raw.githubusercontent.com` — no backend needed.
-**In your voice.** Entries are written using a voice profile, resolved in this order: your `config.voicePath` → [ghostwriter](../ghostwriter)'s `voice/` dir if installed → a bundled default. devlog reads `voice-profile.md` (and `voice-notes.md` overrides) — never ghostwriter's `algorithm.md`, since LinkedIn reach tuning doesn't apply to a dev log.
-## Quick start
-```sh
-npx @natjswenson/devlog init
-```
-That command:
-- Creates `<your-username>/daily-dev-log` on GitHub (or uses an existing one)
-- Installs the skill at `~/.claude/skills/devlog/`
-- Writes `~/.claude/skills/devlog/config.json` with your answers
-- Lets you register one or more projects in a single run
-Then:
-```sh
-npx @natjswenson/devlog preview
-```
-to see your dev log rendered locally at `http://localhost:5173`.
-## Prerequisites
-- **Node 18+** — for the CLI and preview app
-- **GitHub CLI** (`gh`), authenticated with `gh auth login` — used to create your dev-log repo and push entries
-- **Claude Code** — to run the `/devlog` skill
-## Commands
-| Command | What it does |
-|---|---|
-| `npx @natjswenson/devlog init` | One-time setup: create dev-log repo, install skill, write config |
-| `npx @natjswenson/devlog add-project` | Register an additional project without editing config.json by hand |
-| `npx @natjswenson/devlog config` | Show your current config with validation status |
-| `npx @natjswenson/devlog preview` | Run a local preview at `http://localhost:5173` |
-| `npx @natjswenson/devlog --help` | Usage |
-| `npx @natjswenson/devlog --version` | Version |
-> **Tip:** run from any directory *outside* a clone of this repo. Running inside the repo causes a `package.json` name collision and `npx` fails with `command not found`.
-## What you end up with
-```
-~/.claude/skills/devlog/
-├── SKILL.md          # The /devlog slash-command instructions
-├── config.json       # Your settings (mode 0600)
-└── voice/            # Bundled fallback voice profile (last resort)
-    ├── voice-profile.md
-    └── voice-notes.md
-github.com/<you>/daily-dev-log/   # Created by init, populated by /devlog
-├── myproject/
-│   ├── manifest.json
-│   ├── v0.3.0.md
-│   ├── v0.2.0.md
-│   └── ...
-└── ...
-```
-## Manual setup (if you prefer)
-```sh
-gh repo create <you>/daily-dev-log --public --add-readme
-mkdir -p ~/.claude/skills/devlog/voice
-curl -o ~/.claude/skills/devlog/SKILL.md https://raw.githubusercontent.com/natejswenson/devlog/main/SKILL.md
-# Optional fallback voice profile (used when voicePath and ghostwriter are both absent):
-curl -o ~/.claude/skills/devlog/voice/voice-profile.md https://raw.githubusercontent.com/natejswenson/devlog/main/voice/voice-profile.example.md
-curl -o ~/.claude/skills/devlog/voice/voice-notes.md https://raw.githubusercontent.com/natejswenson/devlog/main/voice/voice-notes.example.md
-# Then copy config.example.json → ~/.claude/skills/devlog/config.json and fill it in
-```
-## Add to your site
-### React (drop-in)
-```sh
-cp -r examples/react/ your-site/src/devlog/
-```
-Edit `your-site/src/devlog/devlog-config.js` to point at your repo, then:
-```jsx
-import DevLogPage from './devlog/DevLogPage.jsx';
-<DevLogPage project="myproject" />
-```
-Full instructions: [`examples/react/README.md`](./examples/react/README.md).
-### No site yet?
-The `preview/` directory is a complete deployable Vite app. Set `VITE_DEVLOG_OWNER` / `VITE_DEVLOG_REPO` / `VITE_DEVLOG_PROJECTS` env vars on Vercel, Netlify, or Cloudflare Pages, build with `vite build`, deploy `dist/`. See [`preview/README.md`](./preview/README.md).
-### Other stacks (Next, Astro, plain HTML)
-It's static JSON and Markdown on GitHub. Build whatever UI you want — see the **Data contract** below.
-## Data contract
-The dev-log repo has this layout, all served as raw files from `https://raw.githubusercontent.com/<owner>/<repo>/<branch>/`:
-```
-<repo>/
-└── <project-key>/
-    ├── manifest.json          # Index of all entries (newest first)
-    ├── v0.3.0.md              # One entry per release (named by version)
-    ├── v0.2.0.md
-    └── ...
-```
-**`manifest.json`:**
-```json
-{
-  "entries": [
-    { "date": "2026-06-08", "file": "v0.2.0.md", "title": "...", "summary": "...", "version": "v0.2.0" }
-  ]
-}
-```
-Strict validation rules (entries that don't match are silently dropped by the React example):
-- `date` matches `YYYY-MM-DD` (the release/tag date)
-- `file` matches `^[a-zA-Z0-9._-]+\.md$`
-- `title` and `summary` are non-empty strings
-- `version` (optional) matches `^[a-zA-Z0-9._-]+$`
-**Entry markdown:**
-```markdown
----
-title: "Concise release summary"
-date: 2026-06-08
-project: myproject
-version: v0.2.0
-summary: "1-2 sentence summary"
----
-## What Shipped
-Narrative paragraphs, written in your voice.
-## What's Next
-Forward-looking note.
-## Commits
-- commit message ([abc1234](https://github.com/.../commit/abc1234567...))
-```
-That's the entire contract.
-## Configuration reference
-`~/.claude/skills/devlog/config.json`:
-| Field | Type | Description |
-|---|---|---|
-| `targetRepo` | `"<owner>/<repo>"` | Repo where dev log entries are published. Must match `^[a-z0-9][a-z0-9._-]*\/[a-z0-9][a-z0-9._-]*$`. |
-| `branch` | string (optional) | Branch in the dev-log repo. Defaults to `main`. Must not contain `..` or start with `-`. |
-| `gitAuthor` | string | Your name. Retained for backward compatibility; it is **not** currently rendered on entries (the author filter was removed, and release notes summarize all commits in a tag range). Still **required** by config validation — it must be present and non-empty (don't drop it). Whitespace OK; no shell metacharacters. |
-| `githubUser` | string | Your GitHub username. |
-| `voicePath` | string (optional) | Directory holding `voice-profile.md` (and optionally `voice-notes.md`) used to write entries in your voice. A leading `~` is expanded. If unset, devlog uses ghostwriter's `voice/` if installed, else the bundled default. Read only — never shell-interpolated. |
-| `projects` | array | One entry per project you want dev logs for. |
-| `projects[].key` | string | Subdirectory name in the dev-log repo. Strict token: `^[a-z0-9][a-z0-9._-]*$`, no `..`. |
-| `projects[].label` | string (optional) | Display name for the tab. Defaults to `key`. |
-| `projects[].path` | string | Local filesystem path to the project. Whitespace OK. |
-| `projects[].remote` | `"<owner>/<repo>"` | The project's GitHub remote. Used to mark public commits and link them. |
-| `projects[].pathFilter` | string (optional) | Repo-relative subdir scoping this project's commits in a monorepo (e.g. `skills/devlog`). |
-| `projects[].tagPrefix` | string (optional) | Prefix of the git tags that mark this project's releases (e.g. `devlog-v`). Defaults to `v`. Used in `git tag --list '<tagPrefix>*'`. |
-See [`config.example.json`](./config.example.json) for a complete template, or run `npx @natjswenson/devlog config` to inspect your current config with validation.
-## Security
-The package is designed to be safe to install on a developer's machine and have ambient gh/git credentials. See [SECURITY.md](./SECURITY.md) for the full threat model and audit history.
-**At a glance:**
-- ✓ All shell calls in the CLI use `spawnSync` with argv arrays (no shell, no injection surface)
-- ✓ The skill validates every config field against an allowlist before interpolating into shell commands; instructs the LLM to single-quote interpolated values
-- ✓ Markdown rendering uses `react-markdown` with `skipHtml` and an allowlist `urlTransform` (only http(s)/mailto allowed; data:, javascript:, vbscript:, file:, blob: all neutralized)
-- ✓ Frontmatter parser uses `Object.create(null)` + key allowlist (no prototype pollution)
-- ✓ All external JSON is schema-validated before use (manifest, env-var projects array)
-- ✓ Vite dev server bound to `localhost`, CORS off
-- ✓ Demo-mode `window.fetch` override gated to dev builds only
-- ✓ `config.json` written atomically (tmp + rename), mode 0600
-- ✓ All dependencies pinned to exact versions
-- ✓ `npm audit`: 0 known vulnerabilities
-**To report a vulnerability:** open a [GitHub security advisory](https://github.com/natejswenson/devlog/security/advisories/new). Do not open a public issue.
-## Customization
-- **Tweak the entry template:** edit `~/.claude/skills/devlog/SKILL.md` (Step 6 — generate the entry).
-- **Tweak your voice:** edit the `voice-profile.md` / `voice-notes.md` in your `voicePath` (or `~/.claude/skills/devlog/voice/`).
-- **Tweak the UI:** override the `--devlog-*` CSS variables in `examples/react/DevLogPage.css` to match your theme.
-- **Add more projects:** `npx @natjswenson/devlog add-project` (no manual JSON editing required).
-## Troubleshooting
-**`sh: devlog: command not found` when running `npx`:** you're inside a checkout of this repo. The local `package.json` name collides with the published one. Run `npx` from somewhere else, e.g. `cd ~ && npx @natjswenson/devlog ...`.
-**Init prompts show `78` after placeholder text:** that's an artifact of how some output capture tools render `\x1b7`/`\x1b8` (cursor save/restore) escape sequences. In a real interactive terminal, you won't see it.
-**Preview is blank / no tabs / no entries:** check the browser console. If you see CJS interop errors related to `react-dom/client`, `style-to-js`, or `react-markdown`, you're on a pre-0.1.6 release — upgrade with `npm cache clean --force && rm -rf ~/.npm/_npx && npx --yes @natjswenson/devlog@latest preview`.
-**Init can't find `gh`:** install via [cli.github.com](https://cli.github.com/) and run `gh auth login`.
-**`Config validation failed: ...`** — the validator rejected something in your `config.json`. Run `npx @natjswenson/devlog config` for a detailed diagnosis. Common causes:
-- A field has shell metacharacters (`;` `&` `|` `` ` `` `$` etc) — see SKILL.md for the full list
-- A project key contains `..` or `/`
-- A path doesn't exist on disk
-**Preview shows "Setup required":** you deployed the preview app standalone but didn't set the env vars. Set `VITE_DEVLOG_OWNER`, `VITE_DEVLOG_REPO`, `VITE_DEVLOG_PROJECTS` (JSON-stringified array) in your hosting environment.
-## Versioning
-Releases are documented in [CHANGELOG.md](./CHANGELOG.md). The package follows semver — bug fixes/security patches in patch releases (0.1.x), behavior changes in minor (0.x.0).
-## License
-MIT