@natjswenson/devlog 0.1.6 → 0.1.7

package/CHANGELOG.md

@@ -0,0 +1,71 @@
+# Changelog
+
+All notable changes to `@natjswenson/devlog` are documented here.
+
+## 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/README.md

@@ -2,6 +2,8 @@
 
 [![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 your daily git commits into a published dev log — and a React example for displaying it on your site.
 
@@ -9,7 +11,7 @@ A Claude Code skill that turns your daily git commits into a published dev log
 
 ## Live example
 
-The skill is in production at [natejswenson.com/devlog](https://natejswenson.com/devlog), publishing entries 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.
+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
 
@@ -24,30 +26,46 @@ npx @natjswenson/devlog init
 ```
 
 That command:
-- Creates `<your-username>/daily-dev-log` on GitHub
+- 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.
+
+to see your dev log rendered locally at `http://localhost:5173`.
 
 ## Prerequisites
 
 - **Node 18+** — for the CLI and preview app
-- **GitHub CLI** (`gh`), authenticated — used to create your dev-log repo and push entries
+- **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 slash command
-└── config.json       # Your settings (target repo, projects, etc)
+├── SKILL.md          # The /devlog slash-command instructions
+└── config.json       # Your settings (mode 0600)
 
-github.com/<you>/daily-dev-log/   # Created by `init`, populated by /devlog
+github.com/<you>/daily-dev-log/   # Created by init, populated by /devlog
 ├── myproject/
 │   ├── manifest.json
 │   ├── 2026-05-01.md
@@ -55,19 +73,14 @@ github.com/<you>/daily-dev-log/   # Created by `init`, populated by /devlog
 └── ...
 ```
 
-## Manual setup (if you'd rather not use the CLI)
+## Manual setup (if you prefer)
 
-1. **Create your dev-log repo:**
-   ```sh
-   gh repo create <you>/daily-dev-log --public --add-readme
-   ```
-2. **Install the skill:**
-   ```sh
-   mkdir -p ~/.claude/skills/devlog
-   curl -o ~/.claude/skills/devlog/SKILL.md \
-     https://raw.githubusercontent.com/natejswenson/devlog/main/SKILL.md
-   ```
-3. **Write your config** at `~/.claude/skills/devlog/config.json` — copy [`config.example.json`](./config.example.json) and fill in.
+```sh
+gh repo create <you>/daily-dev-log --public --add-readme
+mkdir -p ~/.claude/skills/devlog
+curl -o ~/.claude/skills/devlog/SKILL.md https://raw.githubusercontent.com/natejswenson/devlog/main/SKILL.md
+# Then copy config.example.json → ~/.claude/skills/devlog/config.json and fill it in
+```
 
 ## Add to your site
 
@@ -77,7 +90,7 @@ github.com/<you>/daily-dev-log/   # Created by `init`, populated by /devlog
 cp -r examples/react/ your-site/src/devlog/
 ```
 
-Edit `your-site/src/devlog/devlog-config.js` to point at your repo, then mount:
+Edit `your-site/src/devlog/devlog-config.js` to point at your repo, then:
 
 ```jsx
 import DevLogPage from './devlog/DevLogPage.jsx';
@@ -89,15 +102,15 @@ 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/`. Done — you have a public dev log at your own URL. See [`preview/README.md`](./preview/README.md).
+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, anything)
+### 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>/main/`:
+The dev-log repo has this layout, all served as raw files from `https://raw.githubusercontent.com/<owner>/<repo>/<branch>/`:
 
 ```
 <repo>/
@@ -117,7 +130,13 @@ The dev-log repo has this layout, all served as raw files from `https://raw.gith
 }
 ```
 
+Strict validation rules (entries that don't match are silently dropped by the React example):
+- `date` matches `YYYY-MM-DD`
+- `file` matches `^[a-zA-Z0-9._-]+\.md$`
+- `title` and `summary` are non-empty strings
+
 **Entry markdown:**
+
 ```markdown
 ---
 title: "Concise day summary"
@@ -144,39 +163,62 @@ That's the entire contract.
 
 | Field | Type | Description |
 |---|---|---|
-| `targetRepo` | `"<owner>/<repo>"` | Repo where dev log entries are published. **You create this — `init` does it for you, or `gh repo create` manually.** |
-| `branch` | string (optional) | Branch in the dev-log repo. Defaults to `main`. |
-| `gitAuthor` | string | Used as `git log --author=...` to find your commits. |
-| `githubUser` | string | Your GitHub username (for constructing commit links). |
+| `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 | Used as `git log --author=...` to find your commits. Whitespace OK; no shell metacharacters. |
+| `githubUser` | string | Your GitHub username. |
 | `projects` | array | One entry per project you want dev logs for. |
-| `projects[].key` | string | Subdirectory name in the dev-log repo. |
-| `projects[].label` | string (optional) | Display name for the project tab in the UI. Defaults to `key`. |
-| `projects[].path` | string | Local filesystem path to the project. |
-| `projects[].remote` | `"<owner>/<repo>"` | The project's GitHub remote, used to mark public commits and link them. |
+| `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. |
+
+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.
 
-See [`config.example.json`](./config.example.json) for a complete template.
+**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 4 — generate the entry).
-- **Tweak the UI:** override the `--devlog-*` CSS variables in `examples/react/DevLogPage.css` to match your theme. Or build your own UI against the data contract above.
-- **Add more projects:** edit `~/.claude/skills/devlog/config.json` directly.
+- **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 probably inside a checkout of this repo. The local `package.json` collides with the published name. Run `npx` from anywhere else (e.g. `cd ~ && npx @natjswenson/devlog ...`).
-
-**Init prompt shows `78` after the placeholder text:** that's an artifact of capturing terminal output (cursor save/restore escapes); in a real terminal you won't see it.
+**`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 ...`.
 
-**Preview is blank / no tabs / no entries:** check the browser console. If you see *"does not provide an export named …"* errors related to `react-dom/client`, `style-to-js`, or `react-markdown`, you're on a pre-0.1.3 release — upgrade with `npm cache clean --force && rm -rf ~/.npm/_npx && npx --yes @natjswenson/devlog@latest preview`.
+**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.
 
-**`npm publish` (if you fork/republish your own copy) fails with 403:** npm requires 2FA or a granular access token with bypass-2FA enabled for write operations. Easiest path: enable 2FA, install an authenticator app, and pass `--otp=<code>` to `npm publish`.
+**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
 
-Stable: see [npm](https://www.npmjs.com/package/@natjswenson/devlog). The package follows semver — bug fixes in patch releases (0.1.x), behavior changes in minor (0.x.0).
+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
 

package/SECURITY.md

@@ -0,0 +1,100 @@
+# Security policy
+
+## Reporting a vulnerability
+
+Please report security issues privately rather than opening a public GitHub issue.
+
+- **Email:** open a GitHub security advisory at https://github.com/natejswenson/devlog/security/advisories/new
+- **Response time:** target within 72 hours
+
+Please do not file public issues, post on social media, or share PoCs publicly until a fix has shipped.
+
+## Scope
+
+In scope:
+- The published npm package `@natjswenson/devlog` (any version)
+- The CLI (`bin/devlog.js`)
+- The Claude Code skill (`SKILL.md`)
+- The Vite preview app (`preview/`)
+- The React drop-in components (`examples/react/`)
+
+Out of scope:
+- The user's own `daily-dev-log` repo content (that's on the user)
+- The user's GitHub account, gh CLI, or local dev environment
+- The Claude Code product itself
+- Vulnerabilities that require an attacker to already have arbitrary code execution on the user's machine
+- Social engineering, phishing, or attacks on the npm registry / GitHub itself
+
+## Threat model
+
+### Trust boundaries
+
+The package crosses three trust boundaries:
+
+1. **npm → adopter's machine.** The package is distributed via the npm registry. Adopters trust npm not to ship a tampered tarball. Out of our scope; defense relies on npm's signing and provenance.
+
+2. **`config.json` → shell commands.** The Claude Code skill (`SKILL.md`) reads `~/.claude/skills/devlog/config.json` and uses values in shell commands run via Claude's bash tool. The skill's Step 0.5 enforces strict allowlist validation on every field BEFORE interpolation, and instructs the LLM to single-quote all values when interpolating. This is the most security-critical boundary.
+
+3. **`daily-dev-log` repo content → adopter's deployed site.** Markdown entries published via `/devlog` are fetched from `raw.githubusercontent.com` and rendered by `react-markdown` 9.x. Raw HTML is disabled. URLs are restricted to `http(s)://`, `mailto:`, `#`, and relative paths via an explicit `urlTransform`.
+
+### Attacker capabilities
+
+| Attacker | Has access to | Out of reach |
+|---|---|---|
+| Random LinkedIn reader | npm tarball, GitHub repo, README | Adopter's machine, gh token, dev-log content |
+| Adopter who edits config.json | Their own filesystem, gh token | Other adopters' machines |
+| Contributor with PR rights to dev-log repo | Markdown content rendered by adopter's site | Adopter's local files, gh token |
+
+### What's protected
+
+- **Command injection in the CLI:** every shell call that includes user input uses `spawnSync` with argv arrays (no shell). The four hardcoded `execSync` calls (`gh --version`, `gh auth status`, `gh api user --jq .login`, `git config --global user.name`) take no user input.
+
+- **Command injection via the skill:** the skill validates every config value against an allowlist before interpolation, instructs the LLM to single-quote every value, and uses `git -C <path>` form rather than `cd <path> && git ...` to reduce shell-composition surface.
+
+- **Path traversal:** project keys, manifest filenames, and project paths are all pattern-matched. Project paths additionally cannot start with `-` (would be parsed as a flag). Manifest filenames must match `^[a-zA-Z0-9._-]+\.md$`.
+
+- **XSS via markdown:** `react-markdown` 9 with `skipHtml`, plus an explicit `urlTransform` allowlisting only `http(s)://`, `mailto:`, `#`, and relative URLs. Schemes like `data:`, `blob:`, `javascript:`, `vbscript:`, `file:` are replaced with `#`.
+
+- **Prototype pollution via frontmatter:** the parser uses `Object.create(null)` and only writes to keys in `{title, date, project, summary}` — so `__proto__: x` in a hostile entry has no effect.
+
+- **Schema confusion:** every external JSON document (manifest, parsed env-var projects array) is validated against a strict schema before use. Malformed input is rejected, not "fixed."
+
+- **Demo-mode side effects in production:** the global `window.fetch` override is gated to `import.meta.env.DEV`. Production builds without env vars show a clear "Setup required" screen instead of broken-looking entries.
+
+- **Env var leakage to client-side:** the CLI passes only `VITE_DEVLOG_*` variables (plus `PATH`/`HOME`/etc. needed for Vite to run) to the spawned vite process. Adopter's other `VITE_*` shell vars do NOT leak into the preview bundle.
+
+- **Vite dev server exposure:** explicit `server.host: 'localhost'` + `cors: false`. The dev server cannot be reached from other machines on the LAN by default.
+
+- **Atomic config writes:** `config.json` is written to a sibling `.tmp.<pid>` file then renamed atomically. Readers never see partial state.
+
+- **Tight `.gitignore`:** excludes `.npmrc`, `.env*`, `*.pem`, `*.key`, `.vscode/`, `.idea/`, `coverage/` so future contributors can't accidentally publish secrets via the `files` whitelist in package.json.
+
+- **Pinned dependencies:** every dependency is pinned to an exact version (no `^` ranges) to eliminate resolution drift across installs.
+
+### What's NOT protected (intentional risk acceptance)
+
+- **Adopter editing config.json with malicious values.** The skill validates at runtime and refuses to run on bad input — but a sufficiently determined user can bypass any client-side guard by directly running shell commands themselves. The package can't protect against the adopter attacking their own machine.
+
+- **Adopter installing a typosquatted package.** Always verify the scope is `@natjswenson` (no extra `e`).
+
+- **GitHub raw URL paths.** A manifest entry's `file` field is restricted to `^[a-zA-Z0-9._-]+\.md$`, but the project key is part of the URL path. The schema validator on project keys rejects `..`, `/`, and other traversal characters.
+
+## Reproducible attack scenarios that have been ruled out
+
+Each of the following has been tested against the current code and shown to be ineffective. Reports of these scenarios will be acknowledged but treated as "already addressed."
+
+1. `gitAuthor: "Nate\"; rm -rf ~; #"` in config.json → blocked by Step 0.5 validation in skill, rejected by CLI prompt validator.
+2. `path: "/tmp/$(id)"` in config.json → blocked by SHELL_METACHARS regex.
+3. `targetRepo: "-h"` or `--template <evil-repo>` → rejected by `^[a-z0-9][a-z0-9._-]*$` regex requiring leading alphanumeric.
+4. `__proto__: pwned` in entry frontmatter → ignored by allowlist + `Object.create(null)` parser.
+5. `[click me](javascript:alert(1))` in entry markdown → react-markdown's default sanitizer + our `urlTransform` rewrite to `#`.
+6. `[click](data:text/html,<script>...)` in entry markdown → rewritten to `#` by `urlTransform`.
+7. Manifest entry with `file: "../../../other-repo/secret.md"` → rejected by `^[a-zA-Z0-9._-]+\.md$` schema.
+8. Concurrent editor seeing a half-written `config.json` → atomic rename guarantees readers see either the old or new file, never a partial write.
+9. `VITE_API_KEY=secret npx ... preview` leaking through into the preview bundle → blocked by env-var allowlist in CLI.
+
+## Audit history
+
+| Date | Version | Audit | Result |
+|---|---|---|---|
+| 2026-05-01 | 0.1.5 → 0.1.7 | 6-agent siege (Boundary Attacker, Insider Threat, Infrastructure Prober, Betrayed Consumer, Fresh Attacker, Chain Analyst) | 1 Critical + 3 High + 7 Medium + 4 Low → 0 Critical + 0 High + 0 Medium-Active in 0.1.7 |

package/SKILL.md

@@ -51,20 +51,38 @@ Validate that `targetRepo`, `gitAuthor`, `githubUser`, and `projects` (non-empty
 
 **Critical:** every value below gets interpolated into shell commands. If any value contains shell metacharacters or breaks the expected shape, **STOP** and tell the user their config is malformed. Do not "fix" it — refuse to run.
 
+The CLI's `init` and `add-project` commands enforce these patterns at write time. The skill MUST re-enforce them at runtime because the user can edit `config.json` by hand at any time.
+
 | Field | Required pattern |
 |---|---|
 | `targetRepo` | Matches `^[a-zA-Z0-9][a-zA-Z0-9._-]*\/[a-zA-Z0-9][a-zA-Z0-9._-]*$` (owner/repo, no leading dash) |
-| `branch` (optional) | Matches `^[a-zA-Z0-9][a-zA-Z0-9._/-]*$` (no leading dash, no `..`); defaults to `main` |
-| `gitAuthor` | Must NOT contain any of: `;` `&` `|` `` ` `` `$` `(` `)` `<` `>` `{` `}` `*` `?` `!` `#` `~` `"` `\` newline, carriage return |
+| `branch` (optional) | Matches `^[a-zA-Z0-9][a-zA-Z0-9._/-]*$` (no leading dash, no `..` as a path component); defaults to `main` |
+| `gitAuthor` | Must NOT contain any of: `;` `&` `\|` `` ` `` `$` `(` `)` `<` `>` `{` `}` `[` `]` `*` `?` `!` `#` `~` `"` `'` `\` newline, CR. (Whitespace, dots, hyphens, equals, percent are fine — names like "Nate Swenson" and "O.G. Lastname" must validate.) |
 | `githubUser` | Matches `^[a-zA-Z0-9][a-zA-Z0-9-]*$` |
 | `projects[].key` | Matches `^[a-zA-Z0-9][a-zA-Z0-9._-]*$` AND must not contain `..` |
-| `projects[].path` | Must NOT contain shell metacharacters (same set as gitAuthor) AND must point to an existing directory |
+| `projects[].path` | Must NOT contain the shell-quote-break set (same as gitAuthor), MUST NOT start with `-`, AND must point to an existing directory. Whitespace allowed (paths legitimately contain spaces). |
+| `projects[].label` (optional) | Same character constraints as `gitAuthor` — used as display text, never as a shell argument |
 | `projects[].remote` | Same pattern as `targetRepo` |
 
 If any field fails validation, stop with:
-> Config field `<field>` failed security validation: `<value>`. Edit `~/.claude/skills/devlog/config.json` and retry.
+> Config field `<field>` failed security validation: `<value>`. Edit `~/.claude/skills/devlog/config.json` and retry, or run `npx @natjswenson/devlog config` to inspect.
+
+**Shell-quoting rule (defense-in-depth):**
+
+Even with values validated, when interpolating into a shell command, ALWAYS wrap the value in single quotes (`'...'`). Single-quoted shell strings have no metacharacter expansion. Since validation above forbids embedded single quotes, this is always safe. Example:
+
+```bash
+# Right
+git -C '<project.path>' log --author='<config.gitAuthor>' --since=midnight ...
+
+# Also right (separate flags after `=`)
+git -C '<project.path>' log "--author=<config.gitAuthor>" --since=midnight ...
+
+# Wrong — no quotes
+git -C <project.path> log ...
+```
 
-Once validated, the values are safe to interpolate into the shell commands below. Even so, **prefer `git -C <path>` form over `cd <path> && git ...`** (reduces shell-escape complexity) and **use the Write tool, not bash heredocs, when writing JSON or markdown files** (avoids accidentally re-injecting attacker-controlled content into shell).
+Once validated AND single-quoted, the values are safe to interpolate into the shell commands below. Even so, **prefer `git -C <path>` form over `cd <path> && git ...`** (reduces shell-escape complexity) and **use the Write tool, not bash heredocs, when writing JSON or markdown files** (avoids accidentally re-injecting attacker-controlled content into shell).
 
 ## Step 1: Determine scope
 
@@ -73,10 +91,10 @@ Once validated, the values are safe to interpolate into the shell commands below
 
 ## Step 2: Gather today's commits
 
-For each project in scope, run (use `git -C` to avoid `cd` shell-composition):
+For each project in scope, run (use `git -C` to avoid `cd` shell-composition; single-quote interpolated values):
 
 ```bash
-git -C <project.path> log --author=<config.gitAuthor> --since=midnight --format=%H|%s|%D --all
+git -C '<project.path>' log "--author=<config.gitAuthor>" --since=midnight --format='%H|%s|%D' --all
 ```
 
 If no commits are found for a project, skip it. If no commits are found across all projects, inform the user and stop.
@@ -86,8 +104,8 @@ If no commits are found for a project, skip it. If no commits are found across a
 For each commit, check if it's on the `main` branch and if the remote is public:
 
 ```bash
-git -C <project.path> remote get-url origin
-git -C <project.path> branch --contains <hash> -r 2>/dev/null | grep -q 'origin/main'
+git -C '<project.path>' remote get-url origin
+git -C '<project.path>' branch --contains <hash> -r 2>/dev/null | grep -q 'origin/main'
 ```
 
 - If the remote URL matches `<project.remote>` (i.e. `github.com/<project.remote>` or the SSH equivalent) and the commit is on `origin/main`, it's a public commit — include a link using `https://github.com/<project.remote>/commit/<hash>`.
@@ -154,8 +172,9 @@ Clone the repo once, write all project entries, then push.
 mktemp -d
 # → record the printed path, e.g. /var/folders/.../tmp.abc123
 
-# Step 6.2: clone (use --depth=1 to limit blast radius if remote is huge)
-git -C <abs-tmp-path> clone --depth=1 https://github.com/<config.targetRepo>.git
+# Step 6.2: clone (use --depth=1 to limit blast radius if remote is huge;
+# the targetRepo value has been validated to match <owner>/<repo> already)
+git -C '<abs-tmp-path>' clone --depth=1 'https://github.com/<config.targetRepo>.git'
 ```
 
 Write entries and manifest using the **Write tool** (not bash heredocs — avoids re-injecting content into shell):
@@ -166,16 +185,18 @@ Write entries and manifest using the **Write tool** (not bash heredocs — avoid
   - Entry object: `{ "date": "YYYY-MM-DD", "file": "YYYY-MM-DD.md", "title": "...", "summary": "..." }`
   - If appending to existing entry, update title/summary only if changed
   - If manifest doesn't exist, create it as `{ "entries": [...] }`
+  - **Sanitize fetched title/summary:** if appending to an existing entry, the fetched values are external content — never echo them through bash without escaping. Use the Write tool with the values as JSON literals.
 
-Then commit and push:
+Then commit and push (single-quote all interpolated values):
 
 ```bash
-git -C <abs-tmp-path>/<repo-name> add .
-git -C <abs-tmp-path>/<repo-name> commit -m "devlog: add entries for YYYY-MM-DD"
-git -C <abs-tmp-path>/<repo-name> push origin <config.branch || 'main'>
+git -C '<abs-tmp-path>/<repo-name>' add .
+git -C '<abs-tmp-path>/<repo-name>' commit -m 'devlog: add entries for YYYY-MM-DD'
+# Use --no-tags to avoid pushing any local tags that happened to be in the temp clone
+git -C '<abs-tmp-path>/<repo-name>' push --no-tags origin '<config.branch || main>'
 
 # Cleanup — pass the absolute path explicitly
-rm -rf <abs-tmp-path>
+rm -rf '<abs-tmp-path>'
 ```
 
 ## Step 7: Confirm

package/bin/devlog.js

@@ -1,14 +1,31 @@
 #!/usr/bin/env node
 import { spawn, spawnSync, execSync } from 'node:child_process';
-import { existsSync, mkdirSync, readFileSync, writeFileSync, copyFileSync } from 'node:fs';
-import { homedir } from 'node:os';
+import { existsSync, mkdirSync, readFileSync, writeFileSync, copyFileSync, renameSync, unlinkSync } from 'node:fs';
+import { homedir, tmpdir } from 'node:os';
 import { dirname, join, resolve, basename } from 'node:path';
-import { fileURLToPath, pathToFileURL } from 'node:url';
+import { fileURLToPath } from 'node:url';
 import { createRequire } from 'node:module';
 import prompts from 'prompts';
 import kleur from 'kleur';
 
-const SHELL_METACHARS = /[;&|`$()<>{}*?!#~"\\\n\r]/;
+// ─── shared validators (single source of truth, also used by SKILL.md guidance) ───
+//
+// 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.
+const SHELL_QUOTE_BREAK = /[;&|`$()<>{}[\]*?!#~"'\\\n\r]/;
+const RE_GH_USER = /^[a-z0-9][a-z0-9-]*$/i;
+const RE_REPO_NAME = /^[a-z0-9][a-z0-9._-]*$/i;
+const RE_OWNER_REPO = /^[a-z0-9][a-z0-9._-]*\/[a-z0-9][a-z0-9._-]*$/i;
+const RE_PROJECT_KEY = /^[a-z0-9][a-z0-9._-]*$/i;
+const RE_BRANCH = /^[a-z0-9][a-z0-9._/-]*$/i;
+const FORBIDDEN_BRANCH_PARTS = /(^|\/)\.\.($|\/)/; // reject `..` as a path component
 
 const require = createRequire(import.meta.url);
 const PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
@@ -24,6 +41,7 @@ const log = {
   warn: (msg) => console.log(kleur.yellow('! ') + msg),
   err: (msg) => console.error(kleur.red('✗ ') + msg),
   step: (msg) => console.log(kleur.cyan('→ ') + msg),
+  hint: (msg) => console.log(kleur.dim('  ' + msg)),
 };
 
 function readPackageVersion() {
@@ -31,8 +49,7 @@ function readPackageVersion() {
   return pkg.version;
 }
 
-// Runs a hardcoded shell command (no user input). Use tryExecArgs for any
-// command whose arguments include user-supplied values.
+// Hardcoded shell command, no user input. Use tryExecArgs for anything user-supplied.
 function tryExec(cmd) {
   try {
     return execSync(cmd, { stdio: ['ignore', 'pipe', 'pipe'], encoding: 'utf8' }).trim();
@@ -59,31 +76,91 @@ function expandHome(p) {
   return p;
 }
 
+// Atomic write: write to sibling tmp file then rename.
+// Prevents readers from seeing a half-written config if process is killed mid-write.
+function atomicWriteJSON(path, data) {
+  const tmp = path + '.tmp.' + process.pid;
+  writeFileSync(tmp, JSON.stringify(data, null, 2) + '\n', { mode: 0o600 });
+  try {
+    renameSync(tmp, path);
+  } catch (e) {
+    try { unlinkSync(tmp); } catch {}
+    throw e;
+  }
+}
+
+// Validate a config object before writing. Throws with a user-facing message on failure.
+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 (!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 ('label' in p && typeof p.label !== 'string') {
+      throw new Error(`project.label must be a string if present`);
+    }
+  }
+  return config;
+}
+
+function readConfig() {
+  if (!existsSync(CONFIG_PATH)) return null;
+  const raw = readFileSync(CONFIG_PATH, 'utf8');
+  return JSON.parse(raw);
+}
+
 async function preflight() {
   const nodeMajor = parseInt(process.versions.node.split('.')[0], 10);
   if (nodeMajor < 18) {
     log.err(`Node 18+ required (you have ${process.versions.node}).`);
+    log.hint('Update Node: https://nodejs.org/');
     process.exit(1);
   }
-
-  const ghVersion = tryExec('gh --version');
-  if (!ghVersion) {
+  if (!tryExec('gh --version')) {
     log.err('GitHub CLI (`gh`) is not installed.');
-    log.info('Install: https://cli.github.com/');
+    log.hint('Install: https://cli.github.com/   then run `gh auth login`');
     process.exit(1);
   }
-
-  const ghAuth = tryExec('gh auth status');
-  if (!ghAuth) {
+  if (!tryExec('gh auth status')) {
     log.err('GitHub CLI is not authenticated.');
-    log.info('Run: gh auth login');
+    log.hint('Run: gh auth login');
     process.exit(1);
   }
 }
 
 function detectGhUser() {
-  const out = tryExec('gh api user --jq .login');
-  return out || null;
+  return tryExec('gh api user --jq .login') || null;
 }
 
 function detectGitName() {
@@ -104,128 +181,158 @@ async function confirmOverwrite(label, path) {
     name: 'ok',
     message: `${label} already exists at ${path}. Overwrite?`,
     initial: false,
-  });
+  }, { onCancel: () => process.exit(1) });
   return ok === true;
 }
 
-async function cmdInit() {
-  log.info(kleur.bold('\ndevlog setup\n'));
-  await preflight();
+// ─── prompt validators (reused across init and add-project) ──────────────────
+const VALIDATORS = {
+  gitAuthor: (v) => {
+    if (v.trim().length === 0) return 'Required';
+    if (SHELL_QUOTE_BREAK.test(v)) return 'Invalid characters (no quotes, backticks, dollar signs, semicolons, parens, or shell metacharacters)';
+    return true;
+  },
+  githubUser: (v) => RE_GH_USER.test(v.trim()) || 'Invalid username (must start with letter/digit, alphanumeric + hyphens only)',
+  targetRepoName: (v) => RE_REPO_NAME.test(v.trim()) || 'Invalid repo name (must start with letter/digit, no leading dash)',
+  path: (v) => {
+    if (SHELL_QUOTE_BREAK.test(v)) return 'Invalid characters (no quotes, backticks, dollar signs, semicolons, parens, or shell metacharacters)';
+    if (v.trim().startsWith('-')) return 'Path cannot start with a dash';
+    return existsSync(expandHome(v)) || 'Path does not exist';
+  },
+  projectKey: (v) => {
+    const t = v.trim();
+    if (!RE_PROJECT_KEY.test(t)) return 'Invalid key (must start with letter/digit, alphanumeric + ._- only)';
+    if (t.includes('..')) return 'Invalid key (no `..`)';
+    return true;
+  },
+  ownerRepo: (v) => RE_OWNER_REPO.test(v.trim()) || 'Expected <owner>/<repo>, no leading dash, alphanumeric + ._- only',
+  label: (v) => {
+    if (typeof v === 'string' && SHELL_QUOTE_BREAK.test(v)) return 'Label has shell metacharacters (cosmetic field, but kept clean defensively)';
+    return true;
+  },
+};
 
-  const defaults = {
-    gitAuthor: detectGitName() || '',
-    githubUser: detectGhUser() || '',
-    targetRepoName: 'daily-dev-log',
-  };
+// Prompt for a single project's fields. Returns { key, path, remote, label } or null on cancel.
+async function promptForProject(defaults = {}) {
+  const initialPath = defaults.path || process.cwd();
+  const initialKey = defaults.key || basename(expandHome(initialPath));
+  const initialRemote = defaults.remote || detectProjectRemote(expandHome(initialPath)) || '';
 
   const answers = await prompts([
     {
       type: 'text',
-      name: 'gitAuthor',
-      message: 'Your name (used to filter `git log --author`):',
-      initial: defaults.gitAuthor,
-      validate: (v) => {
-        if (v.trim().length === 0) return 'Required';
-        if (SHELL_METACHARS.test(v)) return 'Invalid characters (no quotes, backticks, or shell metacharacters)';
-        return true;
-      },
+      name: 'path',
+      message: 'Project absolute path:',
+      initial: initialPath,
+      validate: VALIDATORS.path,
     },
     {
       type: 'text',
-      name: 'githubUser',
-      message: 'Your GitHub username:',
-      initial: defaults.githubUser,
-      validate: (v) => /^[a-z0-9][a-z0-9-]*$/i.test(v.trim()) || 'Invalid username (must start with letter/digit, alphanumeric + hyphens only)',
+      name: 'key',
+      message: 'Project key (used as dev-log subdir name):',
+      initial: (_p, values) => basename(expandHome(values.path || initialKey)),
+      validate: VALIDATORS.projectKey,
     },
     {
       type: 'text',
-      name: 'targetRepoName',
-      message: 'Name of the repo where dev logs will be published:',
-      initial: defaults.targetRepoName,
-      validate: (v) => /^[a-z0-9][a-z0-9._-]*$/i.test(v.trim()) || 'Invalid repo name (must start with letter/digit, no leading dash)',
+      name: 'label',
+      message: 'Project display label (optional, defaults to key):',
+      initial: '',
+      validate: VALIDATORS.label,
     },
     {
-      type: 'confirm',
-      name: 'registerProject',
-      message: 'Register a project now? (you can add more later by editing config.json)',
-      initial: true,
+      type: 'text',
+      name: 'remote',
+      message: 'Project GitHub remote (<owner>/<repo>):',
+      initial: (_p, values) => detectProjectRemote(expandHome(values.path)) || initialRemote,
+      validate: VALIDATORS.ownerRepo,
     },
   ], { onCancel: () => process.exit(1) });
 
-  let projectAnswers = null;
-  if (answers.registerProject) {
-    const cwd = process.cwd();
-    const cwdRemote = detectProjectRemote(cwd);
-    projectAnswers = await prompts([
-      {
-        type: 'text',
-        name: 'path',
-        message: 'Project absolute path:',
-        initial: cwd,
-        validate: (v) => {
-          if (SHELL_METACHARS.test(v)) return 'Invalid characters (no quotes, backticks, or shell metacharacters)';
-          return existsSync(expandHome(v)) || 'Path does not exist';
-        },
-      },
-      {
-        type: 'text',
-        name: 'key',
-        message: 'Project key (used as dev-log subdir name):',
-        initial: (prev) => basename(expandHome(prev || cwd)),
-        validate: (v) => {
-          const t = v.trim();
-          if (!/^[a-z0-9][a-z0-9._-]*$/i.test(t)) return 'Invalid key (must start with letter/digit, alphanumeric + ._- only)';
-          if (t.includes('..')) return 'Invalid key (no `..`)';
-          return true;
-        },
-      },
-      {
-        type: 'text',
-        name: 'remote',
-        message: 'Project GitHub remote (<owner>/<repo>):',
-        initial: (_prev, values) => detectProjectRemote(expandHome(values.path)) || cwdRemote || `${answers.githubUser}/${basename(expandHome(values.path))}`,
-        validate: (v) => /^[a-z0-9][a-z0-9._-]*\/[a-z0-9][a-z0-9._-]*$/i.test(v.trim()) || 'Expected <owner>/<repo>, no leading dash',
-      },
-    ], { onCancel: () => process.exit(1) });
+  const out = {
+    key: answers.key.trim(),
+    path: expandHome(answers.path),
+    remote: answers.remote.trim(),
+  };
+  if (answers.label && answers.label.trim()) out.label = answers.label.trim();
+  return out;
+}
+
+// ─── init ────────────────────────────────────────────────────────────────────
+async function cmdInit() {
+  log.info(kleur.bold('\ndevlog setup\n'));
+  await preflight();
+
+  const defaults = {
+    gitAuthor: detectGitName() || '',
+    githubUser: detectGhUser() || '',
+    targetRepoName: 'daily-dev-log',
+  };
+
+  const answers = await prompts([
+    { type: 'text', name: 'gitAuthor', message: 'Your name (used to filter `git log --author`):', initial: defaults.gitAuthor, validate: VALIDATORS.gitAuthor },
+    { type: 'text', name: 'githubUser', message: 'Your GitHub username:', initial: defaults.githubUser, validate: VALIDATORS.githubUser },
+    { type: 'text', name: 'targetRepoName', message: 'Name of the repo where dev logs will be published:', initial: defaults.targetRepoName, validate: VALIDATORS.targetRepoName },
+  ], { onCancel: () => process.exit(1) });
+
+  // Optionally register projects in a loop. First time defaults to "yes".
+  const projects = [];
+  let registerAnother = true;
+  let firstPrompt = true;
+  while (registerAnother) {
+    const { add } = await prompts({
+      type: 'confirm',
+      name: 'add',
+      message: firstPrompt ? 'Register a project now?' : 'Register another project?',
+      initial: firstPrompt,
+    }, { onCancel: () => process.exit(1) });
+    firstPrompt = false;
+    if (!add) break;
+    const p = await promptForProject();
+    if (projects.find((x) => x.key === p.key)) {
+      log.warn(`Skipped (duplicate key): ${p.key}`);
+      continue;
+    }
+    projects.push(p);
+    log.ok(`Registered: ${p.key}`);
   }
 
   const targetRepo = `${answers.githubUser}/${answers.targetRepoName}`;
-  const config = {
+  const config = validateConfig({
     targetRepo,
+    branch: 'main',
     gitAuthor: answers.gitAuthor,
     githubUser: answers.githubUser,
-    projects: projectAnswers ? [{
-      key: projectAnswers.key,
-      path: expandHome(projectAnswers.path),
-      remote: projectAnswers.remote,
-    }] : [],
-  };
+    projects,
+  });
+
+  // Sanity check: warn if the gh-authenticated user differs from githubUser.
+  // Common mistake on machines with multiple gh logins.
+  const ghUser = detectGhUser();
+  if (ghUser && ghUser !== config.githubUser) {
+    log.warn(`gh is authenticated as "${ghUser}" but config.githubUser is "${config.githubUser}".`);
+    log.hint('Run `gh auth login` to switch accounts, or update config.githubUser.');
+  }
 
   log.info('\n' + kleur.bold('Summary:'));
   log.info(`  Target repo:    ${kleur.cyan(`github.com/${targetRepo}`)}`);
   log.info(`  Git author:     ${config.gitAuthor}`);
   log.info(`  GitHub user:    ${config.githubUser}`);
-  log.info(`  Projects:       ${config.projects.length === 0 ? '(none — add later)' : config.projects.map(p => p.key).join(', ')}`);
+  log.info(`  Branch:         ${config.branch}`);
+  log.info(`  Projects:       ${config.projects.length === 0 ? '(none — add later with `devlog add-project`)' : config.projects.map((p) => p.key).join(', ')}`);
   log.info(`  Skill location: ${CONFIG_DIR}`);
 
-  const { proceed } = await prompts({
-    type: 'confirm',
-    name: 'proceed',
-    message: 'Continue?',
-    initial: true,
-  }, { onCancel: () => process.exit(1) });
+  const { proceed } = await prompts({ type: 'confirm', name: 'proceed', message: 'Continue?', initial: true }, { onCancel: () => process.exit(1) });
   if (!proceed) process.exit(0);
-
   log.info('');
 
+  // Repo create — argv form, no shell.
   const repoExists = tryExecArgs('gh', ['repo', 'view', targetRepo, '--json', 'name']) !== null;
   if (repoExists) {
     log.warn(`Repo github.com/${targetRepo} already exists. Will use it as-is.`);
   } else {
     log.step(`Creating github.com/${targetRepo}...`);
-    const r = spawnSync('gh', ['repo', 'create', targetRepo, '--public', '--description', 'Daily dev log', '--add-readme'], {
-      stdio: 'inherit',
-    });
+    const r = spawnSync('gh', ['repo', 'create', targetRepo, '--public', '--description', 'Daily dev log', '--add-readme'], { stdio: 'inherit' });
     if (r.status !== 0) {
       log.err('Failed to create repo. Check `gh` permissions.');
       process.exit(1);
@@ -234,7 +341,7 @@ async function cmdInit() {
   }
 
   if (!existsSync(CONFIG_DIR)) {
-    mkdirSync(CONFIG_DIR, { recursive: true });
+    mkdirSync(CONFIG_DIR, { recursive: true, mode: 0o700 });
     log.ok(`Created ${CONFIG_DIR}`);
   }
 
@@ -246,44 +353,131 @@ async function cmdInit() {
   }
 
   if (await confirmOverwrite('config.json', CONFIG_PATH)) {
-    writeFileSync(CONFIG_PATH, JSON.stringify(config, null, 2) + '\n');
+    atomicWriteJSON(CONFIG_PATH, config);
     log.ok(`Wrote config → ${CONFIG_PATH}`);
   } else {
     log.warn('Skipped config.json');
   }
 
-  log.info('\n' + kleur.bold().green('Done.') + '\n');
+  log.info('\n' + kleur.bold().green('Setup complete.') + '\n');
   log.info('Next steps:');
-  log.info(`  1. ${config.projects.length === 0 ? 'Edit config.json to register projects' : '(Optional) edit config.json to register more projects'}`);
-  log.info('  2. Make some commits in a registered project');
-  log.info('  3. In Claude Code, run: /devlog');
-  log.info('  4. Preview locally: npx @natjswenson/devlog preview');
+  if (config.projects.length === 0) {
+    log.info(`  1. Add a project: ${kleur.cyan('npx @natjswenson/devlog add-project')}`);
+    log.info('  2. Make some commits in the project');
+  } else {
+    log.info('  1. Make some commits in a registered project');
+  }
+  log.info(`  2. In Claude Code, run: ${kleur.cyan('/devlog')}`);
+  log.info(`  3. Preview locally: ${kleur.cyan('npx @natjswenson/devlog preview')}`);
   log.info('');
 }
 
-async function cmdPreview() {
+// ─── add-project ─────────────────────────────────────────────────────────────
+async function cmdAddProject() {
+  log.info(kleur.bold('\ndevlog add-project\n'));
+  if (!existsSync(CONFIG_PATH)) {
+    log.err(`No config found at ${CONFIG_PATH}`);
+    log.hint('Run `npx @natjswenson/devlog init` first.');
+    process.exit(1);
+  }
+
+  let config;
+  try {
+    config = readConfig();
+    validateConfig(config);
+  } catch (e) {
+    log.err(`Existing config is invalid: ${e.message}`);
+    log.hint(`Edit ${CONFIG_PATH} or run \`devlog init\` to recreate.`);
+    process.exit(1);
+  }
+
+  if (config.projects.length > 0) {
+    log.info(kleur.dim('Currently registered projects:'));
+    for (const p of config.projects) log.info(kleur.dim(`  - ${p.key}  (${p.path})`));
+    log.info('');
+  }
+
+  const newProject = await promptForProject();
+  if (config.projects.find((p) => p.key === newProject.key)) {
+    log.err(`Project key "${newProject.key}" is already registered.`);
+    log.hint('Pick a different key, or remove the existing entry first.');
+    process.exit(1);
+  }
+
+  const newConfig = validateConfig({ ...config, projects: [...config.projects, newProject] });
+  atomicWriteJSON(CONFIG_PATH, newConfig);
+  log.ok(`Added "${newProject.key}" to config.`);
+  log.info('');
+  log.info(`Run ${kleur.cyan('/devlog ' + newProject.key)} in Claude Code to publish an entry for this project.`);
+  log.info('');
+}
+
+// ─── config (view) ───────────────────────────────────────────────────────────
+async function cmdConfig() {
   if (!existsSync(CONFIG_PATH)) {
     log.err(`No config found at ${CONFIG_PATH}`);
-    log.info('Run `npx @natjswenson/devlog init` first.');
+    log.hint('Run `npx @natjswenson/devlog init` first.');
     process.exit(1);
   }
 
   let config;
   try {
-    config = JSON.parse(readFileSync(CONFIG_PATH, 'utf8'));
+    config = readConfig();
   } catch (e) {
-    log.err(`Failed to parse config: ${e.message}`);
+    log.err(`Failed to read config: ${e.message}`);
     process.exit(1);
   }
 
-  const [owner, repo] = (config.targetRepo || '').split('/');
-  if (!owner || !repo) {
-    log.err('config.targetRepo is not in <owner>/<repo> format');
+  let validationStatus;
+  try {
+    validateConfig(config);
+    validationStatus = kleur.green('valid');
+  } catch (e) {
+    validationStatus = kleur.red('INVALID — ' + e.message);
+  }
+
+  log.info('');
+  log.info(kleur.bold(`Config: ${CONFIG_PATH}`));
+  log.info(`Status:        ${validationStatus}`);
+  log.info(`Target repo:   ${kleur.cyan(`github.com/${config.targetRepo || '?'}`)}`);
+  log.info(`Branch:        ${config.branch || 'main'}`);
+  log.info(`Git author:    ${config.gitAuthor || '?'}`);
+  log.info(`GitHub user:   ${config.githubUser || '?'}`);
+  log.info(`Projects (${(config.projects || []).length}):`);
+  for (const p of config.projects || []) {
+    log.info(`  ${kleur.cyan(p.key)}${p.label ? `  (${p.label})` : ''}`);
+    log.info(kleur.dim(`    path:   ${p.path}`));
+    log.info(kleur.dim(`    remote: github.com/${p.remote}`));
+  }
+  log.info('');
+}
+
+// ─── preview ─────────────────────────────────────────────────────────────────
+async function cmdPreview() {
+  if (!existsSync(CONFIG_PATH)) {
+    log.err(`No config found at ${CONFIG_PATH}`);
+    log.hint('Run `npx @natjswenson/devlog init` first.');
     process.exit(1);
   }
 
-  const projects = (config.projects || []).map((p) => ({ key: p.key, label: p.label || p.key }));
+  let config;
+  try {
+    config = readConfig();
+    validateConfig(config);
+  } catch (e) {
+    log.err(`Config validation failed: ${e.message}`);
+    log.hint(`Edit ${CONFIG_PATH} or run \`devlog config\` to inspect.`);
+    process.exit(1);
+  }
+
+  const [owner, repo] = config.targetRepo.split('/');
   const branch = config.branch || 'main';
+  const projects = config.projects.map((p) => ({ key: p.key, label: p.label || p.key }));
+
+  if (projects.length === 0) {
+    log.warn('No projects registered. The preview will show an empty state.');
+    log.hint(`Run \`npx @natjswenson/devlog add-project\` to register one.`);
+  }
 
   log.step(`Launching preview against github.com/${config.targetRepo}...`);
 
@@ -291,11 +485,20 @@ async function cmdPreview() {
   const vitePkg = JSON.parse(readFileSync(vitePkgPath, 'utf8'));
   const viteBin = resolve(dirname(vitePkgPath), vitePkg.bin?.vite || 'bin/vite.js');
 
+  // Filter env to only PATH/HOME/etc plus VITE_DEVLOG_* we set explicitly.
+  // This prevents adopters' arbitrary VITE_* vars (e.g. VITE_API_KEY for an
+  // unrelated project in their shell) from being inlined into preview source.
+  const SAFE_ENV_KEYS = ['PATH', 'HOME', 'USER', 'SHELL', 'LANG', 'LC_ALL', 'TERM', 'TMPDIR', 'NODE_PATH', 'NODE_OPTIONS'];
+  const safeEnv = {};
+  for (const k of SAFE_ENV_KEYS) {
+    if (process.env[k] !== undefined) safeEnv[k] = process.env[k];
+  }
+
   const proc = spawn(process.execPath, [viteBin], {
     cwd: PREVIEW_DIR,
     stdio: 'inherit',
     env: {
-      ...process.env,
+      ...safeEnv,
       VITE_DEVLOG_OWNER: owner,
       VITE_DEVLOG_REPO: repo,
       VITE_DEVLOG_BRANCH: branch,
@@ -305,25 +508,36 @@ async function cmdPreview() {
   proc.on('exit', (code) => process.exit(code ?? 0));
 }
 
+// ─── help ────────────────────────────────────────────────────────────────────
 function printHelp() {
   console.log(`
-${kleur.bold('@natjswenson/devlog')} — daily dev log generator
+${kleur.bold('@natjswenson/devlog')} v${readPackageVersion()} — daily dev log generator
 
 Usage:
-  npx @natjswenson/devlog init       Set up the skill, create your dev-log repo, write config
-  npx @natjswenson/devlog preview    Run a local preview of your published dev log
-  npx @natjswenson/devlog --help
-  npx @natjswenson/devlog --version
-
-Docs: https://github.com/natejswenson/devlog
+  ${kleur.cyan('npx @natjswenson/devlog init')}           One-time setup: create your dev-log repo, install the skill, write config
+  ${kleur.cyan('npx @natjswenson/devlog add-project')}    Register an additional project in your config
+  ${kleur.cyan('npx @natjswenson/devlog config')}         Show your current config (with validation)
+  ${kleur.cyan('npx @natjswenson/devlog preview')}        Run a local preview of your published dev log
+  ${kleur.cyan('npx @natjswenson/devlog --help')}
+  ${kleur.cyan('npx @natjswenson/devlog --version')}
+
+Docs:    https://github.com/natejswenson/devlog
+Issues:  https://github.com/natejswenson/devlog/issues
 `);
 }
 
+// ─── dispatch ────────────────────────────────────────────────────────────────
 const arg = process.argv[2];
 switch (arg) {
   case 'init':
     cmdInit();
     break;
+  case 'add-project':
+    cmdAddProject();
+    break;
+  case 'config':
+    cmdConfig();
+    break;
   case 'preview':
     cmdPreview();
     break;

package/examples/react/DevLogPage.jsx

@@ -7,6 +7,17 @@ import './DevLogPage.css';
 
 const ENTRIES_PER_PAGE = 10;
 
+// Strict allowlist of URL schemes permitted in markdown links/images.
+// react-markdown 9's default sanitizer already blocks `javascript:`,
+// `vbscript:`, `file:`. We narrow further: only http/https/mailto.
+// Anything else (data:, blob:, ftp:, custom schemes) is replaced with `#`.
+const SAFE_URL_SCHEME = /^(https?:|mailto:|#|\/|\.\.?\/|[^:]*$)/i;
+function safeUrlTransform(url) {
+  if (typeof url !== 'string') return '#';
+  if (SAFE_URL_SCHEME.test(url)) return url;
+  return '#';
+}
+
 function formatDate(dateStr) {
   if (typeof dateStr !== 'string') return '';
   const parts = dateStr.split('-');
@@ -143,7 +154,11 @@ export default function DevLogPage({
                     <div className="devlog-content-inner">
                       {isExpanded && content && (
                         <div className="devlog-content" onClick={(e) => e.stopPropagation()}>
-                          <ReactMarkdown remarkPlugins={[remarkGfm]}>
+                          <ReactMarkdown
+                            remarkPlugins={[remarkGfm]}
+                            urlTransform={safeUrlTransform}
+                            skipHtml
+                          >
                             {content}
                           </ReactMarkdown>
                         </div>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@natjswenson/devlog",
-  "version": "0.1.6",
+  "version": "0.1.7",
   "description": "Daily dev log generator — Claude Code skill + preview app for publishing git-based dev logs to your site",
   "license": "MIT",
   "author": "Nate Swenson",
@@ -29,6 +29,8 @@
     "preview/",
     "examples/",
     "SKILL.md",
+    "SECURITY.md",
+    "CHANGELOG.md",
     "config.example.json",
     "README.md",
     "LICENSE"
@@ -36,14 +38,17 @@
   "engines": {
     "node": ">=18"
   },
+  "scripts": {
+    "audit": "npm audit --audit-level=moderate"
+  },
   "dependencies": {
-    "@vitejs/plugin-react": "^4.3.0",
-    "kleur": "^4.1.5",
-    "prompts": "^2.4.2",
-    "react": "^18.3.0",
-    "react-dom": "^18.3.0",
-    "react-markdown": "^9.0.0",
-    "remark-gfm": "^4.0.0",
-    "vite": "^5.4.0"
+    "@vitejs/plugin-react": "6.0.1",
+    "kleur": "4.1.5",
+    "prompts": "2.4.2",
+    "react": "18.3.1",
+    "react-dom": "18.3.1",
+    "react-markdown": "9.1.0",
+    "remark-gfm": "4.0.1",
+    "vite": "8.0.10"
   }
 }

package/preview/App.jsx

@@ -6,6 +6,7 @@ const owner = import.meta.env.VITE_DEVLOG_OWNER;
 const repo = import.meta.env.VITE_DEVLOG_REPO;
 const branch = import.meta.env.VITE_DEVLOG_BRANCH || 'main';
 const projectsRaw = import.meta.env.VITE_DEVLOG_PROJECTS;
+const isDev = import.meta.env.DEV;
 
 const isDemo = !owner || !repo;
 
@@ -60,16 +61,39 @@ function NoProjectsScreen() {
         Env vars say you have a repo (<code>{owner}/{repo}</code>) but no projects.
         That's like buying a stage and forgetting to invite a band.
       </p>
-      <p>Add at least one project to your config:</p>
+      <p>Add a project the easy way:</p>
+      <pre>npx @natjswenson/devlog add-project</pre>
+      <p>Or edit your config directly:</p>
       <pre>{`{
+  "targetRepo": "${owner}/${repo}",
+  "branch": "${branch}",
   "projects": [
-    { "key": "myproject", "path": "...", "remote": "${owner}/myproject" }
+    { "key": "myproject", "label": "My Project", "path": "...", "remote": "${owner}/myproject" }
   ]
 }`}</pre>
+      <p>Then re-run <code>npx @natjswenson/devlog preview</code>.</p>
+    </div>
+  );
+}
+
+// Production builds without env vars: show a clear "setup required" screen,
+// not the demo banner with broken fetches (since installDemoFetch is gated to DEV).
+function SetupRequiredScreen() {
+  return (
+    <div className="empty-screen">
+      <h1>Setup required</h1>
+      <p>
+        This preview was built without the env vars that point it at a dev-log repo.
+        Set these in your hosting environment (Vercel/Netlify/Cloudflare/wherever):
+      </p>
+      <pre>{`VITE_DEVLOG_OWNER=your-github-username
+VITE_DEVLOG_REPO=daily-dev-log
+VITE_DEVLOG_BRANCH=main
+VITE_DEVLOG_PROJECTS=[{"key":"myproject","label":"My Project"}]`}</pre>
       <p>
-        Then run <code>npx @natjswenson/devlog preview</code> again, or set
-        <code> VITE_DEVLOG_PROJECTS</code> directly in <code>preview/.env.local</code>.
+        Or, if you're trying this locally, the friendlier path is:
       </p>
+      <pre>npx @natjswenson/devlog init &amp;&amp; npx @natjswenson/devlog preview</pre>
     </div>
   );
 }
@@ -77,6 +101,12 @@ function NoProjectsScreen() {
 export default function App() {
   const [activeKey, setActiveKey] = useState((projects && projects[0]?.key) || DEMO_PROJECT_KEY);
 
+  // Production build with no env vars: show actionable setup screen
+  // (demo fetch override is DEV-only, so demo entries would 404 here).
+  if (isDemo && !isDev) {
+    return <SetupRequiredScreen />;
+  }
+
   if (!isDemo && !projects) {
     return <NoProjectsScreen />;
   }

package/preview/index.html

@@ -3,6 +3,20 @@
   <head>
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <!--
+      Content-Security-Policy: defense-in-depth for the preview app.
+      - 'self' for scripts/styles (no inline JS, no eval)
+      - 'unsafe-inline' for styles only — required by Vite's HMR runtime in dev
+        and react-markdown's prismjs (none used here, but standard practice)
+      - connect to raw.githubusercontent.com for entry fetches; api.github.com
+        for any future repo metadata; demo-mode.local for the in-browser fetch
+        override that powers demo mode without env vars
+      - no objects, no frames, no plugins
+      Production build: replace 'unsafe-inline' with hashes/nonces if you
+      configure Vite to emit them.
+    -->
+    <meta http-equiv="Content-Security-Policy" content="default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' data: https:; connect-src 'self' https://raw.githubusercontent.com https://api.github.com https://demo-mode.local; object-src 'none'; frame-src 'none'; base-uri 'self'; form-action 'none';" />
+    <meta name="referrer" content="no-referrer-when-downgrade" />
     <title>devlog preview</title>
     <style>
       :root {