@krapwoo/ds-viewer 0.6.10 → 0.6.11

package/README.md

@@ -72,6 +72,23 @@ loser then serves a workspace that no longer describes it, which Expo reports as
 with `--workspace-dir .ds-viewer-second`. A lock left behind by a crashed `dev` never blocks the
 next one.
 
+`.ds-viewer/` belongs to the running server, and it repairs it. If something outside the server
+deletes the generated files while it is serving, it says so and writes them back, rather than
+leaving Expo to report an unresolvable `main` field — which names your project's `package.json`, a
+file that is fine and that you never touched:
+
+```
+Something outside this server deleted package.json, app.json, tsconfig.json, metro.config.js,
+entry.tsx from .ds-viewer/. Rewriting them — your project is fine, this is the catalog's own
+generated workspace. If the catalog looks broken, reload the page.
+```
+
+Metro picks the files back up without a restart. The repair is capped at five per run: if
+something is deleting continuously, repairing forever would only hide it, so past the cap the
+server stops and keeps reporting. If you ever see that message, what else was running at the time
+would be useful on [issue #41](https://github.com/krapwoo/design-system-viewer/issues/41) — the
+cause is not yet identified.
+
 `ds-viewer.config.ts` fields: `name`, `logo` (optional — a path to an image asset, shown in the
 sidebar beside the name, or in place of it for a wide wordmark; validated at `sync`/`dev` time
 and bundled into the preview workspace), `components`, `exclude`, `tokens`, `pages`, `groupOrder`, `starterKit` (new-project only —

package/dist/cli/dev.js

@@ -6,7 +6,7 @@ import { execFile } from 'node:child_process';
 import { promisify } from 'node:util';
 import { resolveConfig } from "./config.js";
 import { sync } from "./sync.js";
-import { clearDevLock, liveDevLock, workspacePath, writeDevLock, writeWorkspace } from "./workspace.js";
+import { clearDevLock, liveDevLock, missingWorkspaceFiles, workspacePath, writeDevLock, writeWorkspace } from "./workspace.js";
 import { findFreePort } from "./port.js";
 import { globBaseFolder } from "./glob.js";
 import { buildVersionStatus, createVersionController, defaultPreferencesDir, readPersonalAutoCheck, resolveAutoCheck, runUpdateCheck, statusFromCheck, writeUpdateFile, writeVersionFile, } from "./updateCheck.js";
@@ -326,6 +326,42 @@ export async function performRestart(handoff, deps = {}) {
  *  component/token/page changes to re-run `sync`. Metro's own HMR updates the rendered component
  *  when its source changes, but not the generated props table or page list (Task 17 Step 4 relies
  *  on this: editing `Button.tsx` must update its props table, not just hot-reload the component). */
+/** How often a running `dev` checks that its own workspace still exists. Cheap (five `existsSync`
+ *  calls), and slow enough to be invisible: the failure it covers is rare, and noticing within a
+ *  few seconds is soon enough to repair before the next page load. */
+const WORKSPACE_WATCH_INTERVAL_MS = 4000;
+/** How many times one `dev` run will rewrite a workspace that keeps losing files. Past this,
+ *  something is deleting continuously and repairing again would only hide it. */
+const WORKSPACE_REPAIR_LIMIT = 5;
+/** One pass of the workspace integrity check. Returns what it did, so the caller owns the repair
+ *  budget and the tests can drive it without a timer.
+ *
+ *  `updateEndpoint` is the caller's own, passed through unchanged: rebuilding it here from the
+ *  Metro port would point the repaired catalog at the wrong server, silently breaking the update
+ *  panel while telling the developer everything is fine. */
+export function repairWorkspaceIfMissing(deps) {
+    const { config, updateEndpoint, versionStatus, sync, reclaimLock, log = console.warn } = deps;
+    const missing = missingWorkspaceFiles(config);
+    if (missing.length === 0)
+        return { missing, repaired: false };
+    log(`Something outside this server deleted ${missing.join(', ')} from ${config.workspaceDir ?? DEFAULT_WORKSPACE_DIR}/. ` +
+        "Rewriting them — your project is fine, this is the catalog's own generated workspace. " +
+        'If the catalog looks broken, reload the page.');
+    writeWorkspace(config, updateEndpoint);
+    // `entry.tsx` imports both of these, so a rewrite that skips them resolves nothing. Both come
+    // from one status, the way `refreshUpdateFile` writes them, so a repair cannot leave
+    // `version.json` announcing an update that `update.json` denies.
+    const status = versionStatus();
+    if (!existsSync(workspacePath(config, 'update.json'))) {
+        const update = status.update ? { ...status.update, checkedAt: status.lastCheckedAt ?? new Date().toISOString() } : undefined;
+        writeUpdateFile(config.projectRoot, update, config.workspaceDir);
+    }
+    if (!existsSync(workspacePath(config, 'version.json')))
+        writeVersionFile(config.projectRoot, status, config.workspaceDir);
+    reclaimLock();
+    sync(config);
+    return { missing, repaired: true };
+}
 export async function dev(initialConfig, devOptions = {}) {
     assertLocalInstall(initialConfig.projectRoot);
     const ownVersion = readOwnVersion(import.meta.dirname);
@@ -505,8 +541,60 @@ export async function dev(initialConfig, devOptions = {}) {
         shell: process.platform === 'win32',
         detached: true,
     });
+    // This process owns its workspace: nothing else should remove the files that define it. When
+    // they vanish anyway, Metro reports it as `Cannot resolve entry file: the 'main' field defined
+    // in your package.json points to an unresolvable or non-existent path` — which names the
+    // *project's* package.json, a file that is fine and that the developer did not touch. The cause
+    // is still unidentified (issue #41), so this does not pretend to prevent it; it notices, says
+    // plainly what happened, and writes the files back, because `writeWorkspace` is idempotent and
+    // already knows how.
+    //
+    // Capped rather than endless: if something is deleting continuously, rewriting forever would
+    // hide it behind a repair loop. After the cap this stops repairing and keeps saying so, which
+    // leaves the evidence visible.
+    let repairs = 0;
+    const workspaceWatch = setInterval(() => {
+        if (watchersPaused)
+            return; // an update is rewriting the workspace on purpose.
+        if (repairs >= WORKSPACE_REPAIR_LIMIT) {
+            const missing = missingWorkspaceFiles(config);
+            if (missing.length > 0) {
+                console.warn(`The catalog workspace is still losing files (missing ${missing.join(', ')}). Not rewriting them again — ` +
+                    'something outside this server is deleting them. Please report what else was running at https://github.com/krapwoo/design-system-viewer/issues/41');
+            }
+            return;
+        }
+        // Counted as an attempt, not a success: a workspace that cannot be rewritten (a permission
+        // error, a sync failure) would otherwise retry every four seconds forever.
+        if (missingWorkspaceFiles(config).length > 0)
+            repairs += 1;
+        try {
+            // `updateEndpoint` is passed through, never rebuilt: the endpoint listens on its own
+            // ephemeral port, so deriving one from Metro's port here would repair the files and break
+            // the update panel in the same breath.
+            repairWorkspaceIfMissing({
+                config, updateEndpoint, versionStatus: version.getVersionStatus, sync,
+                // Only if no one else took it meanwhile: between losing the lock and this tick, a second
+                // `dev` can legitimately have started and be serving the directory. Overwriting its lock
+                // would leave two servers each believing they own it.
+                reclaimLock: () => {
+                    const other = liveDevLock(config);
+                    if (other && other.pid !== process.pid) {
+                        console.warn(`Not reclaiming ${config.workspaceDir ?? DEFAULT_WORKSPACE_DIR}/: pid ${other.pid} owns it now.`);
+                        return;
+                    }
+                    writeDevLock(config, { pid: process.pid, port });
+                },
+            });
+        }
+        catch (error) {
+            console.warn(`Could not rewrite the workspace: ${error.message}`);
+        }
+    }, WORKSPACE_WATCH_INTERVAL_MS);
+    workspaceWatch.unref?.();
     child.on('error', (error) => console.warn(`Could not start Expo: ${error.message}`));
     child.on('exit', (code) => {
+        clearInterval(workspaceWatch);
         for (const watcher of watchers)
             watcher.close();
         endpointServer?.close();

package/dist/cli/workspace.js

@@ -151,6 +151,18 @@ export function liveDevLock(config, ownPid = process.pid) {
         return undefined;
     return lock;
 }
+/** The files `writeWorkspace` always writes: the ones that define the workspace to Expo and Metro.
+ *  `babel.config.js` is conditional and the update files are written separately, so neither counts
+ *  as missing here. */
+export const WORKSPACE_DEFINING_FILES = ['package.json', 'app.json', 'tsconfig.json', 'metro.config.js', 'entry.tsx'];
+/** Which of those a workspace has lost. A running `dev` owns these files and nothing else should
+ *  remove them, so a non-empty answer means something outside this process deleted them — see
+ *  issue #41, where the cause is still unidentified. Reported rather than diagnosed: the point is
+ *  that the server can say what happened instead of leaving Expo to blame the project's own
+ *  `package.json` with `Cannot resolve entry file`. */
+export function missingWorkspaceFiles(config) {
+    return WORKSPACE_DEFINING_FILES.filter((name) => !existsSync(workspacePath(config, name)));
+}
 /** Writes the self-contained Expo web workspace at `.ds-viewer/` (design §2 "The preview
  *  workspace and `npx ds-viewer dev`"). Rewritten freely on every `dev` run — nothing here is
  *  user-owned.
@@ -158,9 +170,9 @@ export function liveDevLock(config, ownPid = process.pid) {
  *  `updateEndpoint` is the caller's own, inlined into `entry.tsx`. Without one (a render check's
  *  throwaway server, `--no-update-endpoint`) the catalog is served with no endpoint at all, so it
  *  makes no calls: the shell polls `/version` from every page, so inlining a *different* server's
- *  endpoint here would have every page call it from the wrong origin. Two `dev` servers share this
- *  one directory, so the last writer decides — see the README on running a render check beside an
- *  open catalog. */
+ *  endpoint here would have every page call it from the wrong origin. Each `dev` owns its own
+ *  workspace directory (`dev-lock.json`), so a render check beside an open catalog writes to
+ *  `.ds-viewer-render/` rather than this one — see the README. */
 export function writeWorkspace(config, updateEndpoint) {
     const workspace = workspacePath(config);
     mkdirSync(workspace, { recursive: true });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@krapwoo/ds-viewer",
-  "version": "0.6.10",
+  "version": "0.6.11",
   "license": "MIT",
   "type": "module",
   "description": "A browsable, always-current catalog for an Expo / React Native design system.",