create-caspian-app 1.5.8 → 1.6.0

package/dist/settings/dev-hold.ts

@@ -0,0 +1,223 @@
+/**
+ * Dev-stack reload hold.
+ *
+ * The file watcher cannot tell an agent's write from a human's save — chokidar
+ * sees an inode change, not a writer. So the agent declares itself instead: a
+ * hold file marks "an agent is mid-run", and while it is active the change
+ * coordinator in `bs-config.ts` keeps queueing changes without restarting the
+ * Python server or reloading the browser. Releasing the hold drains the whole
+ * run as ONE restart and ONE reload.
+ *
+ * Why this matters: the coordinator batches on a 1500 ms quiet period, which is
+ * tuned for a human's burst-save. An agent's gap between two edits is a tool
+ * round-trip — always wider than that window — so without a hold every single
+ * edit costs a full process restart plus a reload of every open tab, and each
+ * reload re-runs the route's Prisma queries against a pool that was just
+ * discarded. Against a remote database that is the churn this file prevents.
+ *
+ * The signal is set by Claude Code hooks (`PreToolUse` acquires and refreshes,
+ * `Stop`/`SessionEnd` release), so it does not depend on a model remembering to
+ * call anything. The manual escape hatches are `npm run dev:hold`,
+ * `npm run dev:resume`, and `npm run dev:hold:status`.
+ *
+ * This module is deliberately dependency-free and written in erasable-only
+ * TypeScript so Node can run it directly (`node settings/dev-hold.ts acquire`)
+ * with a cold start fast enough to sit in front of every agent edit.
+ */
+
+import { mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+/**
+ * A hold that stops being refreshed is treated as abandoned. This is the valve
+ * that keeps a crashed agent or a killed session from freezing the dev stack:
+ * the worst case degrades to today's behaviour, never to a dead server.
+ */
+export const STALE_HOLD_MS = 120_000;
+
+/**
+ * Even a continuously refreshed hold drains eventually, so a very long agent run
+ * still gets periodic restarts instead of none at all.
+ */
+export const MAX_HOLD_MS = 600_000;
+
+const MODULE_DIR = dirname(fileURLToPath(import.meta.url));
+
+/** Resolved from this file, not from `cwd`, so hook shells cannot misplace it. */
+export const WORKSPACE_ROOT = join(MODULE_DIR, "..");
+
+/**
+ * Lives in `.casp/` on purpose: `npm run dev` deletes that directory at startup,
+ * so a fresh dev stack can never inherit a stale hold from a previous session.
+ *
+ * Resolved per call rather than at import so `CASPIAN_DEV_HOLD_PATH` can point a
+ * test (or a second stack) at its own file instead of the live one.
+ */
+export function getHoldPath(): string {
+  return (
+    process.env.CASPIAN_DEV_HOLD_PATH ||
+    join(WORKSPACE_ROOT, ".casp", "dev-hold.json")
+  );
+}
+
+export type DevHold = {
+  /** Who asked for the hold, for the terminal message only. */
+  owner: string;
+  /** Process that acquired it, for debugging a hold nobody expected. */
+  pid: number;
+  /** First acquire — drives the absolute cap. */
+  acquiredAt: number;
+  /** Most recent acquire — drives the stale check. */
+  touchedAt: number;
+  /** How many edits this run has queued, so the terminal can show progress. */
+  edits: number;
+};
+
+export type DevHoldStatus =
+  | { active: false; reason: "none"; hold: null }
+  | { active: false; reason: "stale" | "expired"; hold: DevHold }
+  | { active: true; reason: "held"; hold: DevHold };
+
+function isDevHold(value: unknown): value is DevHold {
+  if (typeof value !== "object" || value === null) return false;
+  const candidate = value as Partial<DevHold>;
+  return (
+    typeof candidate.owner === "string" &&
+    typeof candidate.pid === "number" &&
+    typeof candidate.acquiredAt === "number" &&
+    typeof candidate.touchedAt === "number" &&
+    typeof candidate.edits === "number"
+  );
+}
+
+/** Returns the parsed hold, or null when absent or unreadable. */
+export function readDevHold(): DevHold | null {
+  try {
+    const parsed: unknown = JSON.parse(readFileSync(getHoldPath(), "utf-8"));
+    return isDevHold(parsed) ? parsed : null;
+  } catch {
+    // Missing, half-written, or corrupt all mean the same thing to a caller:
+    // there is no hold it can trust, so fall through to normal reloading.
+    return null;
+  }
+}
+
+/**
+ * Decide whether the coordinator should defer. Both expiry rules fail open —
+ * an unreadable, stale, or over-long hold reports inactive rather than blocking
+ * the dev stack forever.
+ */
+export function evaluateDevHold(now: number = Date.now()): DevHoldStatus {
+  const hold = readDevHold();
+  if (!hold) return { active: false, reason: "none", hold: null };
+
+  if (now - hold.touchedAt > STALE_HOLD_MS) {
+    return { active: false, reason: "stale", hold };
+  }
+
+  if (now - hold.acquiredAt > MAX_HOLD_MS) {
+    return { active: false, reason: "expired", hold };
+  }
+
+  return { active: true, reason: "held", hold };
+}
+
+/** True when reloads should be deferred right now. */
+export function isDevHoldActive(now: number = Date.now()): boolean {
+  return evaluateDevHold(now).active;
+}
+
+/**
+ * Create the hold, or refresh an existing one. Refreshing keeps `acquiredAt` so
+ * the absolute cap measures the whole run rather than restarting on every edit.
+ *
+ * A capped-out hold is deliberately still carried over. If a new edit started a
+ * fresh window instead, an agent editing steadily would re-hold before the
+ * coordinator's next 1500 ms tick and the cap would reset forever without ever
+ * forcing a drain. Carrying it keeps the run expired — so reloads resume — until
+ * an explicit release ends the run. A stale hold is a different case: nothing
+ * refreshed it, so its owner is gone and the next edit legitimately starts over.
+ */
+export function acquireDevHold(
+  owner: string = "agent",
+  now: number = Date.now(),
+): DevHold {
+  const previous = evaluateDevHold(now);
+  const carryOver =
+    previous.reason === "held" || previous.reason === "expired"
+      ? previous.hold
+      : null;
+
+  const hold: DevHold = {
+    owner,
+    pid: process.pid,
+    acquiredAt: carryOver ? carryOver.acquiredAt : now,
+    touchedAt: now,
+    edits: carryOver ? carryOver.edits + 1 : 1,
+  };
+
+  mkdirSync(dirname(getHoldPath()), { recursive: true });
+  writeFileSync(getHoldPath(), `${JSON.stringify(hold, null, 2)}\n`, "utf-8");
+  return hold;
+}
+
+/** Drop the hold. Idempotent, so a duplicate `Stop` hook is harmless. */
+export function releaseDevHold(): DevHold | null {
+  const hold = readDevHold();
+  rmSync(getHoldPath(), { force: true });
+  return hold;
+}
+
+function describeStatus(status: DevHoldStatus): string {
+  if (status.reason === "none") return "inactive - no hold file";
+
+  const ageSeconds = Math.round((Date.now() - status.hold.acquiredAt) / 1000);
+  const summary = `owner=${status.hold.owner} pid=${status.hold.pid} edits=${status.hold.edits} age=${ageSeconds}s`;
+
+  if (status.reason === "stale") {
+    return `inactive - hold went stale (no refresh for over ${STALE_HOLD_MS / 1000}s); ${summary}`;
+  }
+  if (status.reason === "expired") {
+    return `inactive - hold passed the ${MAX_HOLD_MS / 1000}s cap; ${summary}`;
+  }
+  return `ACTIVE - browser reloads and Python restarts are deferred; ${summary}`;
+}
+
+function runCli(argv: string[]): number {
+  const command = argv[0] ?? "status";
+  const quiet = argv.includes("--quiet");
+  const log = (message: string) => {
+    if (!quiet) console.log(message);
+  };
+
+  if (command === "acquire") {
+    const hold = acquireDevHold(process.env.CASPIAN_DEV_HOLD_OWNER || "agent");
+    log(`[dev-hold] Held after ${hold.edits} edit(s); reloads deferred.`);
+    return 0;
+  }
+
+  if (command === "release") {
+    const hold = releaseDevHold();
+    log(
+      hold
+        ? `[dev-hold] Released after ${hold.edits} edit(s); the dev stack will reload once.`
+        : "[dev-hold] No hold was active.",
+    );
+    return 0;
+  }
+
+  if (command === "status") {
+    console.log(`[dev-hold] ${describeStatus(evaluateDevHold())}`);
+    return 0;
+  }
+
+  console.error(`[dev-hold] Unknown command: ${command}`);
+  console.error("[dev-hold] Usage: dev-hold.ts <acquire|release|status> [--quiet]");
+  return 1;
+}
+
+// Only act as a CLI when executed directly; `bs-config.ts` imports the helpers.
+if (process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1]) {
+  process.exit(runCli(process.argv.slice(2)));
+}

package/dist/settings/fix.py

@@ -1,113 +1,113 @@
-"""Safe auto-fixer for the app (`npm run check:fix`).
-
-Removes genuinely dead imports and applies ruff's other safe fixes, then runs
-the gate to report what remains. The catch it exists to handle: `pyproject.toml`
-marks `F401` unfixable so a plain `ruff check --fix` (which anyone might run)
-can never silently delete a component import that is used only as an `<x-*>` tag
-(casp resolves those from module globals at render time). That safety also
-blocks auto-removal of *ordinary* dead imports, so this script re-enables F401
-removal — but only for files that contain no component-tag import, so component
-imports are never at risk.
-
-Flow:
-  1. Format first (`format.py`): `ruff format` for Python, djLint for the markup
-     inside `html(r\"\"\"...\"\"\")`. Formatting settles layout before anything
-     inspects the code, so the fixer and the gate report on the final shape
-     rather than on lines the formatter is about to move.
-  2. List F401 findings under the project config (respects include/exclude).
-  3. Split the owning files into "component-guarded" (has >=1 import used as an
-     `<x-*>` tag) and the rest.
-  4. Remove dead imports only in the non-guarded files, via an isolated ruff run
-     (`--isolated` makes F401 fixable again; `--select F401` limits it to import
-     removal; explicit file args keep the run scoped).
-  5. Apply every other safe fix under the real project config.
-  6. Run the gate (`check.py`) and exit with its status.
-"""
-
-from __future__ import annotations
-
-import json
-import subprocess
-import sys
-from pathlib import Path
-
-import _component_imports as ci
-
-PROJECT_ROOT = Path(__file__).resolve().parents[1]
-
-
-def _run(cmd: list[str]) -> subprocess.CompletedProcess[str]:
-    return subprocess.run(
-        cmd,
-        cwd=PROJECT_ROOT,
-        capture_output=True,
-        text=True,
-        encoding="utf-8",
-        errors="replace",
-    )
-
-
-def _ruff(*args: str) -> subprocess.CompletedProcess[str]:
-    return _run([sys.executable, "-m", "ruff", "check", *args])
-
-
-def _remove_dead_imports() -> list[str]:
-    """Delete genuinely unused imports; never touch component-tag imports.
-
-    Returns the list of files that were auto-fixed.
-    """
-    proc = _ruff(".", "--select", "F401", "--output-format", "json")
-    try:
-        findings = json.loads(proc.stdout or "[]")
-    except json.JSONDecodeError:
-        return []
-
-    guarded: set[str] = set()
-    owning_files: set[str] = set()
-    for f in findings:
-        path = f.get("filename", "")
-        if not path:
-            continue
-        owning_files.add(path)
-        if ci.is_component_tag_f401(f.get("message", ""), path):
-            guarded.add(path)
-
-    # A file with even one template-driven import is skipped whole: we can't
-    # remove just its dead imports without risking the load-bearing ones, and
-    # the gate still reports any real deadwood there for manual removal.
-    fixable_files = sorted(owning_files - guarded)
-    if fixable_files:
-        _ruff(*fixable_files, "--select", "F401", "--fix-only", "--isolated")
-    return fixable_files
-
-
-def _format() -> None:
-    """Run the formatter, but never let it block the fixer or the gate.
-
-    A formatting problem (a missing djLint, an unformattable block) must not
-    stop dead imports from being removed or the gate from reporting. `format.py`
-    prints its own summary, including anything it skipped.
-    """
-    subprocess.run(
-        [sys.executable, str(PROJECT_ROOT / "settings" / "format.py")],
-        cwd=PROJECT_ROOT,
-    )
-
-
-def main() -> int:
-    _format()
-    _remove_dead_imports()
-    # Every other safe fix under the real project config. F401 stays unfixable
-    # here (dead imports were already handled above), so component imports are
-    # untouched.
-    _ruff(".", "--fix-only")
-
-    gate = subprocess.run(
-        [sys.executable, str(PROJECT_ROOT / "settings" / "check.py")],
-        cwd=PROJECT_ROOT,
-    )
-    return gate.returncode
-
-
-if __name__ == "__main__":
-    raise SystemExit(main())
+"""Safe auto-fixer for the app (`npm run test:fix`).
+
+Removes genuinely dead imports and applies ruff's other safe fixes, then runs
+the gate to report what remains. The catch it exists to handle: `pyproject.toml`
+marks `F401` unfixable so a plain `ruff check --fix` (which anyone might run)
+can never silently delete a component import that is used only as an `<x-*>` tag
+(casp resolves those from module globals at render time). That safety also
+blocks auto-removal of *ordinary* dead imports, so this script re-enables F401
+removal — but only for files that contain no component-tag import, so component
+imports are never at risk.
+
+Flow:
+  1. Format first (`format.py`): `ruff format` for Python, djLint for the markup
+     inside `html(r\"\"\"...\"\"\")`. Formatting settles layout before anything
+     inspects the code, so the fixer and the gate report on the final shape
+     rather than on lines the formatter is about to move.
+  2. List F401 findings under the project config (respects include/exclude).
+  3. Split the owning files into "component-guarded" (has >=1 import used as an
+     `<x-*>` tag) and the rest.
+  4. Remove dead imports only in the non-guarded files, via an isolated ruff run
+     (`--isolated` makes F401 fixable again; `--select F401` limits it to import
+     removal; explicit file args keep the run scoped).
+  5. Apply every other safe fix under the real project config.
+  6. Run the gate (`check.py`) and exit with its status.
+"""
+
+from __future__ import annotations
+
+import json
+import subprocess
+import sys
+from pathlib import Path
+
+import _component_imports as ci
+
+PROJECT_ROOT = Path(__file__).resolve().parents[1]
+
+
+def _run(cmd: list[str]) -> subprocess.CompletedProcess[str]:
+    return subprocess.run(
+        cmd,
+        cwd=PROJECT_ROOT,
+        capture_output=True,
+        text=True,
+        encoding="utf-8",
+        errors="replace",
+    )
+
+
+def _ruff(*args: str) -> subprocess.CompletedProcess[str]:
+    return _run([sys.executable, "-m", "ruff", "check", *args])
+
+
+def _remove_dead_imports() -> list[str]:
+    """Delete genuinely unused imports; never touch component-tag imports.
+
+    Returns the list of files that were auto-fixed.
+    """
+    proc = _ruff(".", "--select", "F401", "--output-format", "json")
+    try:
+        findings = json.loads(proc.stdout or "[]")
+    except json.JSONDecodeError:
+        return []
+
+    guarded: set[str] = set()
+    owning_files: set[str] = set()
+    for f in findings:
+        path = f.get("filename", "")
+        if not path:
+            continue
+        owning_files.add(path)
+        if ci.is_component_tag_f401(f.get("message", ""), path):
+            guarded.add(path)
+
+    # A file with even one template-driven import is skipped whole: we can't
+    # remove just its dead imports without risking the load-bearing ones, and
+    # the gate still reports any real deadwood there for manual removal.
+    fixable_files = sorted(owning_files - guarded)
+    if fixable_files:
+        _ruff(*fixable_files, "--select", "F401", "--fix-only", "--isolated")
+    return fixable_files
+
+
+def _format() -> None:
+    """Run the formatter, but never let it block the fixer or the gate.
+
+    A formatting problem (a missing djLint, an unformattable block) must not
+    stop dead imports from being removed or the gate from reporting. `format.py`
+    prints its own summary, including anything it skipped.
+    """
+    subprocess.run(
+        [sys.executable, str(PROJECT_ROOT / "settings" / "format.py")],
+        cwd=PROJECT_ROOT,
+    )
+
+
+def main() -> int:
+    _format()
+    _remove_dead_imports()
+    # Every other safe fix under the real project config. F401 stays unfixable
+    # here (dead imports were already handled above), so component imports are
+    # untouched.
+    _ruff(".", "--fix-only")
+
+    gate = subprocess.run(
+        [sys.executable, str(PROJECT_ROOT / "settings" / "check.py")],
+        cwd=PROJECT_ROOT,
+    )
+    return gate.returncode
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())