From 898393167ee1deaeeb5cbc0574c63a234aef992a Mon Sep 17 00:00:00 2001 From: Dustin VanKrimpen Date: Fri, 3 Jul 2026 13:52:57 -0400 Subject: [PATCH 1/2] Reset dashboard content store per run; document concurrency limits The dashboard runs Astro with a fixed root and only varies WHEREFORE_SRC, so Astro's .astro content store is shared across projects. Because question ids (Q-001...) are identical in every project, a store left over from a different --src collided and Astro logged "Duplicate id" warnings. Clear data-store.json at the start of each dev/build so every run is scoped to the current --src, silencing the warnings for the sequential view-A-then-B flow. Document the narrow remaining concurrency limit in the package README (concurrent dev servers are fine since each serves from its own in-memory store; parallel builds against the shared npx install can cross-contaminate output -- serialize them or use a per-project install), with a pointer from the top-level README. Co-Authored-By: Claude Opus 4.8 (1M context) --- README.md | 4 ++++ packages/wherefore-dashboard/README.md | 13 +++++++++++++ .../bin/wherefore-dashboard.js | 17 +++++++++++++++++ 3 files changed, 34 insertions(+) diff --git a/README.md b/README.md index ac33c65..51ff60b 100644 --- a/README.md +++ b/README.md @@ -119,6 +119,10 @@ from any directory containing a `wherefore/` folder. See the [package README](packages/wherefore-dashboard/README.md) for build options, local preview, and deploying to Cloudflare Pages. +Running several projects at the same time? See +[Running several projects at once](packages/wherefore-dashboard/README.md#running-several-projects-at-once) +-- concurrent `dev` is fine; concurrent `build`s want per-project installs. + ## Running the dashboard from source If you have this repo cloned and want to run the dashboard from the local source diff --git a/packages/wherefore-dashboard/README.md b/packages/wherefore-dashboard/README.md index 61ea592..986a7e9 100644 --- a/packages/wherefore-dashboard/README.md +++ b/packages/wherefore-dashboard/README.md @@ -71,6 +71,19 @@ npm install --save-dev @dustinvk/wherefore-dashboard Bumping the dashboard later is a one-line change in your `package.json`. +## Running several projects at once + +The dashboard caches per install, not per project. That has one consequence worth knowing: + +- **Multiple `dev` servers at once is fine.** Browsing two or more projects side by side works -- + each `dev` server renders its own project. You may see harmless `Duplicate id "Q-..."` warnings + in the logs; they do not affect what is served. +- **Avoid running multiple `build`s at once against the same `npx` install.** Parallel builds of + different projects (e.g. a multi-repo CI job or script) share one on-disk cache and can + cross-contaminate each other's output. Either serialize the builds, or install the dashboard as a + per-project devDependency (see above) and build via an npm script so each project uses its own + isolated copy. + ## Deploy to Cloudflare Pages - Build command: `npx @dustinvk/wherefore-dashboard build` diff --git a/packages/wherefore-dashboard/bin/wherefore-dashboard.js b/packages/wherefore-dashboard/bin/wherefore-dashboard.js index 1f5e83d..234eb12 100755 --- a/packages/wherefore-dashboard/bin/wherefore-dashboard.js +++ b/packages/wherefore-dashboard/bin/wherefore-dashboard.js @@ -9,6 +9,19 @@ import { tmpdir } from 'node:os'; const __dirname = dirname(fileURLToPath(import.meta.url)); const PACKAGE_ROOT = resolve(__dirname, '..'); +async function resetContentStore() { + // Astro persists its content-layer data store under the package root, not under --src: + // dev -> /.astro/data-store.json + // build -> /node_modules/.astro/data-store.json (cacheDir default) + // Question ids (Q-001, ...) are identical in every project, so a store left over from a + // different --src collides and Astro logs "Duplicate id". Clear it so each run is scoped to + // the current --src. The store is cheap to rebuild for a markdown viewer. + await Promise.all([ + rm(resolve(PACKAGE_ROOT, '.astro', 'data-store.json'), { force: true }), + rm(resolve(PACKAGE_ROOT, 'node_modules', '.astro', 'data-store.json'), { force: true }), + ]); +} + const USAGE = `wherefore-dashboard -- build or preview a static dashboard from a wherefore/ directory Usage: @@ -66,6 +79,8 @@ if (command === 'build') { process.env.WHEREFORE_SRC = src; if (flags.title) process.env.WHEREFORE_TITLE = flags.title; + await resetContentStore(); + const workDir = resolve(tmpdir(), `wherefore-dashboard-${Date.now()}`); process.chdir(PACKAGE_ROOT); @@ -89,6 +104,8 @@ if (command === 'build') { process.env.WHEREFORE_SRC = src; if (flags.title) process.env.WHEREFORE_TITLE = flags.title; + await resetContentStore(); + const server = await dev({ root: PACKAGE_ROOT }); process.on('SIGINT', async () => { await server.stop(); From 11a07aed7131d80579173dbd666f2afd9baa87ae Mon Sep 17 00:00:00 2001 From: Dustin VanKrimpen Date: Fri, 3 Jul 2026 13:56:36 -0400 Subject: [PATCH 2/2] Bump @dustinvk/wherefore-dashboard to 0.1.2 Ships the per-run content-store reset (duplicate-id fix) and the concurrency docs to npx users. Co-Authored-By: Claude Opus 4.8 (1M context) --- packages/wherefore-dashboard/package-lock.json | 4 ++-- packages/wherefore-dashboard/package.json | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/packages/wherefore-dashboard/package-lock.json b/packages/wherefore-dashboard/package-lock.json index 773d54e..1b93e91 100644 --- a/packages/wherefore-dashboard/package-lock.json +++ b/packages/wherefore-dashboard/package-lock.json @@ -1,12 +1,12 @@ { "name": "@dustinvk/wherefore-dashboard", - "version": "0.1.0", + "version": "0.1.2", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "@dustinvk/wherefore-dashboard", - "version": "0.1.0", + "version": "0.1.2", "license": "MIT", "dependencies": { "astro": "^5.0.0" diff --git a/packages/wherefore-dashboard/package.json b/packages/wherefore-dashboard/package.json index 51201a0..0b3b4b8 100644 --- a/packages/wherefore-dashboard/package.json +++ b/packages/wherefore-dashboard/package.json @@ -1,6 +1,6 @@ { "name": "@dustinvk/wherefore-dashboard", - "version": "0.1.1", + "version": "0.1.2", "description": "Build tool that reads a wherefore/ directory and emits a static dashboard.", "author": "Dustin VanKrimpen", "license": "MIT",