@natjswenson/devlog 0.12.0 → 0.13.0

package/CHANGELOG.md

@@ -2,6 +2,38 @@
 
 All notable changes to `@natjswenson/devlog` are documented here.
 
+## 0.13.0 (2026-07-29) — a publish run now proves the entry is live
+
+Publishing reported success on a post that was never reachable. The content, cover
+and manifest all landed correctly, the push succeeded, every command returned `ok`,
+and the entry 404'd for an hour because the site's own project registry had never
+been told the project existed. A push is not a route, and this release stops the
+skill treating the two as the same thing.
+
+- **Added: `publish-entry` returns `firstEntryForProject`.** True when the call
+  created a project's first live entry, which is exactly when a rendering site needs
+  a new registry row. A project holding only tombstones still counts as first, since
+  a retired entry never implied a route. Previously nothing distinguished a project's
+  first publish from its fiftieth, so the one moment registration is required looked
+  identical to every run where it isn't.
+- **Added: `siteUrl` config field** (settable, optional, trailing slash stripped,
+  http(s) only) plus `siteUrl` in the scan output. The repo name is not the site name
+  — a repo named `example.io` is commonly served at `example.com` — so a publish run
+  had no way to reach the page it had just published.
+- **Added: SKILL.md Generate step 5b (register a project the site has never
+  rendered).** Find the site's registry, add the project, and *build the clone to
+  confirm the route exists* before pushing. Also warns that registry position can
+  decide feed order: a site sorting by date alone falls back to load order for
+  same-date entries, so a project appended last can render its newest entry last.
+- **Added: SKILL.md Generate step 6 (verify the entry is live).** Poll the published
+  URL until it returns 200 before reporting success; on a persistent 404, check the
+  registry first, then the host's build log, and report it as **not live**. With no
+  `siteUrl` configured, the run must say the entry is pushed but unverified rather
+  than call it published.
+- **Changed: the confirmation block leads with the verified live URL**, with the repo
+  blob URL demoted to secondary, and prints the failure on the `Live:` line rather
+  than a URL that may 404.
+
 ## 0.12.0 (2026-07-28) — five composition slots; stop defaulting to before/after
 
 Minor rather than patch: this adds three new named composition slots, so covers

package/SKILL.md

@@ -41,12 +41,19 @@ Map the user's request onto the CLI — never hand-edit `config.json`:
 | Show config | `npx -y @natjswenson/devlog@latest config --json` |
 | Add a project | `npx -y @natjswenson/devlog@latest add-project --yes --path <abs-path> [--key K] [--remote O/R] [--label L] [--tag-prefix P] [--path-filter F] [--private]` |
 | Remove a project | `npx -y @natjswenson/devlog@latest remove-project <key> --yes` |
-| Change a setting | `npx -y @natjswenson/devlog@latest set <field> <value>` (settable: `targetRepo`, `branch`, `targetDir`, `gitAuthor`, `githubUser`, `voicePath`, `deepDive.minSources`, `deepDive.topicDomains`) |
+| Change a setting | `npx -y @natjswenson/devlog@latest set <field> <value>` (settable: `targetRepo`, `branch`, `targetDir`, `gitAuthor`, `githubUser`, `siteUrl`, `voicePath`, `deepDive.minSources`, `deepDive.topicDomains`) |
 
 `targetDir` is the subdirectory of `targetRepo` that holds the devlog content tree
 (e.g. `content/devlog` when the target is the site repo itself); unset/empty means the
 repo root. Set it with `set targetDir content/devlog`, clear it with `set targetDir ''`.
 
+`siteUrl` is the public base URL that repo is *served* at, with no trailing slash — used
+to verify a published entry actually renders (Generate step 6). **The repo name is not the
+site name**: a repo called `example.io` is commonly served at `example.com`, so take this
+from a working page, not from the repo. Without it a run can push but cannot confirm
+anything went live. Set with `set siteUrl 'https://example.com'`, clear with
+`set siteUrl ''`.
+
 For **add-project**: resolve the path first (the repo the user named, or the cwd), then
 detect what the CLI will use — key = directory basename, remote = `git -C '<path>' remote
 get-url origin`. In a monorepo, suggest a `--path-filter` (the project's subdir) and a
@@ -412,7 +419,65 @@ rm -rf '<abs-tmp>'
 
 If the push fails, report the error and stop — do not retry automatically.
 
-### Step 6: Confirm
+### Step 5b: Register a project the site has never rendered before
+
+`publish-entry` returns **`firstEntryForProject: true`** when the call created that
+project's first live entry. **A push is not a route.** A site that renders the devlog
+almost always keeps its own registry deciding *which* content directories become pages;
+content on disk that the registry doesn't list is built right past, and the entry 404s
+while every command in this skill reports success. Publishing a project's first entry is
+therefore a two-part job, and the CLI can only do the first part.
+
+When `firstEntryForProject` is true, **before the push**:
+
+1. Find the registry in the clone. It is a source file, not content — grep the site's
+   `src/` for the existing project keys (`grep -rn '<a-known-project-key>' <clone>/src`).
+   In an Astro/Next-style site it is typically a `PROJECTS` array the entry loader maps
+   over.
+2. Add the new project, matching the shape of the neighbouring rows exactly.
+3. **Build the site in the clone and confirm the route exists** (`npm ci && npx astro
+   build`, then check the output directory contains the new `<project>/<version>` path).
+   A registry edit that doesn't produce a route is not done.
+4. Run the site's own test suite if it has one, and commit the registry change together
+   with the content in the same push.
+
+If you cannot find a registry, say so plainly rather than assuming there isn't one; the
+verification in Step 6 is what actually settles it.
+
+**Registry position can decide feed order, not just visibility.** If the site sorts
+entries by date alone, same-date entries fall back to their load order, which is registry
+order — so a project appended to the end can render its newest entry last. After the build
+in step 3, check that the new entry appears where its date and publish numeral say it
+should, and report it if not.
+
+### Step 6: Verify the entry is actually live
+
+**Do not report a publish as successful until the published URL returns 200.** The push
+succeeding, the manifest updating, and the site serving the post are three different
+things, and this skill has previously reported success on all of the first two while the
+post 404'd.
+
+When `siteUrl` is set in config (it is echoed in the scan output):
+
+```bash
+curl -s -o /dev/null -w '%{http_code}' -L '<siteUrl>/devlog/<project>/<version>/'
+```
+
+Poll every ~45s for up to ~5 minutes; deploys are not instant. Then:
+
+- **200** → done, report the live URL as the primary link.
+- **Still 404 after the window** → the deploy failed or the entry is not routed. Check
+  `firstEntryForProject`/the registry from Step 5b first, since that is the most common
+  cause, then the host's build log. Report it as **not live**, with what you checked.
+- **`siteUrl` unset** → say the entry is pushed but unverified, give the repo URL, and
+  offer to set it: `npx -y @natjswenson/devlog@latest set siteUrl 'https://example.com'`.
+  Never describe an unverified push as published.
+
+The `/devlog/<project>/<version>/` path is this skill's default convention. If the site
+routes differently, take the pattern from a URL of an already-published entry rather than
+assuming this one.
+
+### Step 7: Confirm
 
 ```
 Release dev log entries published
@@ -420,13 +485,13 @@ Release dev log entries published
   Project: <key>
   Releases: <version>, ...
   Judged weaknesses: <residuals from Step 4, or "none">
-  URL: https://github.com/<targetRepo>/blob/<branch>/<targetDir-prefix><key>/<version>.md
+  Live: <siteUrl>/devlog/<key>/<version>/  (verified 200)
+  Source: https://github.com/<targetRepo>/blob/<branch>/<targetDir-prefix><key>/<version>.md
 ```
 
-(`<targetDir-prefix>` is `<targetDir>/` when set, empty otherwise.) When the target is
-a site repo that auto-deploys on push (e.g. Cloudflare Pages watching `main`), the
-publish push itself triggers the rebuild — mention that the entry goes live with the
-next deploy.
+(`<targetDir-prefix>` is `<targetDir>/` when set, empty otherwise.) Report the **verified
+live URL** as the primary link; the repo blob URL is the secondary one. If Step 6 could
+not verify, say so on the `Live:` line instead of printing a URL that may 404.
 
 ## Security rules
 

package/lib/config_ops.mjs

@@ -34,6 +34,7 @@ const SETTERS = {
   targetDir: (c, v) => (v === '' ? omit(c, 'targetDir') : { ...c, targetDir: v }),
   gitAuthor: (c, v) => ({ ...c, gitAuthor: v }),
   githubUser: (c, v) => ({ ...c, githubUser: v }),
+  siteUrl: (c, v) => (v === '' ? omit(c, 'siteUrl') : { ...c, siteUrl: v.replace(/\/+$/, '') }),
   voicePath: (c, v) => (v === '' ? omit(c, 'voicePath') : { ...c, voicePath: expandHome(v) }),
   'deepDive.minSources': (c, v) => {
     const n = Number(v);

package/lib/core.mjs

@@ -125,6 +125,19 @@ export function validateConfig(config) {
       throw new Error(`targetDir must be a relative path like "content/devlog" (no leading/trailing slash, no '..'): got ${JSON.stringify(config.targetDir)}`);
     }
   }
+  if ('siteUrl' in config) {
+    // Optional: the public base URL the target repo is served at, used only to
+    // confirm a published entry actually renders. The repo name is not the site
+    // name (a repo called `example.io` can be served at `example.com`), and
+    // pushing content is not the same as the site serving it, so this is the
+    // only way a publish run can verify itself rather than assume.
+    // Interpolated into a shell curl, hence the tight charset.
+    if (typeof config.siteUrl !== 'string'
+      || !/^https?:\/\/[A-Za-z0-9.-]+(:\d+)?(\/[A-Za-z0-9._~/-]*)?$/.test(config.siteUrl)
+      || config.siteUrl.endsWith('/')) {
+      throw new Error(`siteUrl must be an http(s) URL with no trailing slash, e.g. "https://example.com": got ${JSON.stringify(config.siteUrl)}`);
+    }
+  }
   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

package/lib/publish_entry.mjs

@@ -221,6 +221,14 @@ export function publishEntry({ cloneDir, project, version, entryPath, coverImage
   }
 
   const file = `${version}.md`;
+  // Whether this project had any live entry before this call. A site that
+  // renders the devlog typically keeps its own registry of which projects to
+  // render (content on disk is not the same as a route), and that registry is
+  // the thing a first-ever publish silently misses: the entry lands, the build
+  // walks past it, and the post 404s while every check reports success.
+  // Reported back so the caller can require registration exactly once per
+  // project, instead of relying on whoever is publishing to remember.
+  const hadLiveEntries = manifest.entries.some((e) => e && !e.removed);
   // 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));
@@ -247,7 +255,13 @@ export function publishEntry({ cloneDir, project, version, entryPath, coverImage
     manifestUpdated = true;
   }
 
-  return { written: destPath, manifestUpdated, coverWritten: !!coverFile, no };
+  return {
+    written: destPath,
+    manifestUpdated,
+    coverWritten: !!coverFile,
+    no,
+    firstEntryForProject: manifestUpdated && !hadLiveEntries,
+  };
 }
 
 // Editorially retire a release: after an entry is manually moved, consolidated,

package/lib/scan.mjs

@@ -288,6 +288,11 @@ export function scanAll(config, { projectKey = null, fetch = true, getExisting =
     // skill appends it to the publish clone path (`--clone <clone>/<targetDir>`).
     targetDir: config.targetDir || '',
     branch,
+    // Public base URL the target repo is served at, when configured — the skill
+    // uses it to confirm a published entry actually renders. null means the run
+    // can push but cannot verify, which the skill has to say out loud rather
+    // than report an unverified publish as a success.
+    siteUrl: config.siteUrl || null,
     deepDive: resolveDeepDive(config),
     voicePath: config.voicePath || null,
     projects: results,

package/package.json

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