@stacksjs/defaults 0.72.85 → 0.72.89

package/app/Actions/Dashboard/Operations/MigrationReconcileAction.ts

@@ -12,7 +12,10 @@ export default new Action({
   apiResponse: true,
   async handle(request: RequestInstance) {
     const input = request.all() as Record<string, unknown>
-    const plan = await migrationPlan()
+    // Fresh, not cached: the revision below is an optimistic-concurrency gate,
+    // and checking a caller's token against a plan computed up to a TTL ago
+    // would admit exactly the drift the gate is here to catch.
+    const plan = await migrationPlan({ fresh: true })
     if (stringValue(input.revision) !== plan.revision)
       return response.json({ message: 'The migration state changed. Refresh before reconciling.' }, 409)
     if (stringValue(input.confirmation) !== `reconcile ${plan.environment}`)

package/app/Actions/Dashboard/Operations/cached-computation.test.ts

@@ -0,0 +1,128 @@
+import { describe, expect, it } from 'bun:test'
+import { cachedComputation } from './cached-computation'
+
+function counter() {
+  let calls = 0
+  let clock = 1_000
+  const cache = cachedComputation({
+    ttlMs: 30_000,
+    now: () => clock,
+    compute: async () => {
+      calls += 1
+      return `value-${calls}`
+    },
+  })
+  return {
+    cache,
+    calls: () => calls,
+    advance: (ms: number) => { clock += ms },
+  }
+}
+
+describe('cachedComputation', () => {
+  it('computes once and serves the same value inside the window', async () => {
+    const { cache, calls } = counter()
+
+    expect(await cache.get()).toBe('value-1')
+    expect(await cache.get()).toBe('value-1')
+    expect(await cache.get()).toBe('value-1')
+    expect(calls()).toBe(1)
+  })
+
+  it('recomputes once the value has aged past the TTL', async () => {
+    const { cache, calls, advance } = counter()
+
+    await cache.get()
+    advance(29_999)
+    expect(await cache.get()).toBe('value-1')
+    expect(calls()).toBe(1)
+
+    advance(1)
+    expect(await cache.get()).toBe('value-2')
+    expect(calls()).toBe(2)
+  })
+
+  it('recomputes on demand and reseeds the cache with that value', async () => {
+    const { cache, calls } = counter()
+
+    await cache.get()
+    expect(await cache.get({ fresh: true })).toBe('value-2')
+    expect(calls()).toBe(2)
+
+    // The forced read is not a one-off: later readers get what it computed,
+    // rather than the value it replaced.
+    expect(await cache.get()).toBe('value-2')
+    expect(calls()).toBe(2)
+  })
+
+  it('recomputes after an explicit invalidation', async () => {
+    const { cache, calls } = counter()
+
+    await cache.get()
+    cache.invalidate()
+    expect(await cache.get()).toBe('value-2')
+    expect(calls()).toBe(2)
+  })
+
+  it('collapses concurrent readers onto one computation', async () => {
+    // The case this exists for: both operations pages loading at once used to
+    // run the same model-versus-schema diff twice for identical output.
+    let calls = 0
+    let release: (value: string) => void = () => {}
+    const gate = new Promise<string>((resolve) => { release = resolve })
+    const cache = cachedComputation({
+      ttlMs: 30_000,
+      compute: async () => {
+        calls += 1
+        return await gate
+      },
+    })
+
+    const readers = [cache.get(), cache.get(), cache.get()]
+    release('shared')
+
+    expect(await Promise.all(readers)).toEqual(['shared', 'shared', 'shared'])
+    expect(calls).toBe(1)
+  })
+
+  it('does not wedge later readers onto a computation that failed', async () => {
+    let attempt = 0
+    const cache = cachedComputation({
+      ttlMs: 30_000,
+      compute: async () => {
+        attempt += 1
+        if (attempt === 1)
+          throw new Error('first attempt failed')
+        return 'recovered'
+      },
+    })
+
+    await expect(cache.get()).rejects.toThrow('first attempt failed')
+    expect(await cache.get()).toBe('recovered')
+    expect(attempt).toBe(2)
+  })
+
+  it('does not let a forced read adopt a computation that started before it', async () => {
+    // `fresh` exists for callers gating a write on the answer. Joining a read
+    // already in flight would hand back a value computed before whatever made
+    // them ask, which is the staleness the flag is there to avoid.
+    let calls = 0
+    const releases: Array<(value: string) => void> = []
+    const cache = cachedComputation({
+      ttlMs: 30_000,
+      compute: async () => {
+        calls += 1
+        return await new Promise<string>((resolve) => { releases.push(resolve) })
+      },
+    })
+
+    const slowReader = cache.get()
+    const forced = cache.get({ fresh: true })
+    expect(calls).toBe(2)
+
+    releases[0]('stale')
+    releases[1]('current')
+    expect(await slowReader).toBe('stale')
+    expect(await forced).toBe('current')
+  })
+})

package/app/Actions/Dashboard/Operations/cached-computation.ts

@@ -0,0 +1,76 @@
+/**
+ * A single cached value with a time budget and no duplicate work in flight.
+ *
+ * Written for the dashboard's migration plan, which costs a full
+ * model-versus-schema diff plus a ledger audit to produce. Two read endpoints
+ * built one per request, so a page load cost seconds and moving between the
+ * two pages paid it again.
+ *
+ * Kept separate from the plan itself so the caching rules can be tested
+ * without a database behind them: pass a `now` and the TTL boundary is exact
+ * rather than a sleep.
+ */
+export interface CachedComputationOptions<T> {
+  /** How long a computed value may be handed to a reader, in milliseconds. */
+  ttlMs: number
+  compute: () => Promise<T>
+  /** Injectable clock. Tests drive the TTL boundary with it. */
+  now?: () => number
+}
+
+export interface CachedComputation<T> {
+  /**
+   * Return the cached value, computing one if there is none or it has aged
+   * out. `fresh` forces a recomputation and reseeds the cache with it - for
+   * callers whose answer gates a write and so cannot be a moment old.
+   */
+  get: (options?: { fresh?: boolean }) => Promise<T>
+  /** Forget the cached value. The next `get` recomputes. */
+  invalidate: () => void
+}
+
+export function cachedComputation<T>(options: CachedComputationOptions<T>): CachedComputation<T> {
+  const now = options.now ?? Date.now
+  let cached: { value: T, computedAt: number } | null = null
+  let inFlight: Promise<T> | null = null
+
+  async function run(): Promise<T> {
+    // Callers arriving mid-computation join the one already running instead of
+    // starting a second. Without this the two operations pages loading
+    // together ran the same expensive diff concurrently for identical output.
+    if (inFlight)
+      return await inFlight
+
+    inFlight = options.compute()
+    try {
+      const value = await inFlight
+      cached = { value, computedAt: now() }
+      return value
+    }
+    finally {
+      // Cleared on failure too, so one rejected computation does not wedge
+      // every later caller onto the same rejected promise.
+      inFlight = null
+    }
+  }
+
+  return {
+    async get(getOptions: { fresh?: boolean } = {}): Promise<T> {
+      if (getOptions.fresh) {
+        cached = null
+        // Deliberately not joined to an in-flight read: that one may have
+        // started before whatever made this caller ask for a fresh value.
+        inFlight = null
+        return await run()
+      }
+
+      if (cached && now() - cached.computedAt < options.ttlMs)
+        return cached.value
+
+      return await run()
+    },
+    invalidate(): void {
+      cached = null
+    },
+  }
+}

package/app/Actions/Dashboard/Operations/migration-operations.test.ts

@@ -0,0 +1,60 @@
+import { describe, expect, it } from 'bun:test'
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+/**
+ * The migration plan is cached, so which callers opt out of that cache is a
+ * correctness property rather than a preference.
+ *
+ * `revision` is an optimistic-concurrency token: a caller sends back the
+ * revision it reviewed, and the server refuses the write if the plan has
+ * moved since. Compare that token against a plan computed up to a TTL ago and
+ * the gate admits exactly the drift it exists to catch. These read the source
+ * because the alternative is standing a database up to prove a call shape.
+ */
+const directory = import.meta.dir
+
+function source(file: string): string {
+  return readFileSync(join(directory, file), 'utf8')
+}
+
+describe('migration plan cache wiring', () => {
+  it('gates every write on a freshly computed plan', () => {
+    const gates = [
+      ['migration-operations.ts', 'applyMigrationPlan'],
+      ['MigrationReconcileAction.ts', 'MigrationReconcileAction'],
+    ] as const
+
+    for (const [file, gate] of gates) {
+      const text = source(file)
+      const calls = [...text.matchAll(/migrationPlan\(([^)]*)\)/g)]
+        .map(match => match[1].trim())
+        // The declaration itself, not a call.
+        .filter(argument => !argument.startsWith('options:'))
+
+      expect(calls.length, `${gate} should still ask for a plan`).toBeGreaterThan(0)
+      for (const argument of calls)
+        expect(argument, `${gate} must gate on a fresh plan`).toContain('fresh: true')
+    }
+  })
+
+  it('lets the read-only index endpoints use the cache', () => {
+    for (const file of ['ChangeIndexAction.ts', 'MigrationIndexAction.ts']) {
+      const calls = [...source(file).matchAll(/migrationPlan\(([^)]*)\)/g)].map(match => match[1].trim())
+      expect(calls.length, `${file} should still ask for a plan`).toBeGreaterThan(0)
+      for (const argument of calls)
+        expect(argument, `${file} should not force a recomputation per request`).toBe('')
+    }
+  })
+
+  it('drops the cached state after anything that moves the schema or ledger', () => {
+    const text = source('migration-operations.ts')
+
+    // After the migrate subprocess succeeds, and after a real (non-dry-run)
+    // ledger reconcile. Either one leaves the cached reading describing a
+    // state that no longer exists.
+    const invalidations = text.match(/invalidateMigrationPlan\(\)/g) ?? []
+    expect(invalidations.length).toBeGreaterThanOrEqual(3)
+    expect(text).toContain('reconcileMigrationLedger({ dryRun: false })')
+  })
+})

package/app/Actions/Dashboard/Operations/migration-operations.ts

@@ -1,5 +1,6 @@
 import process from 'node:process'
 import { auditMigrationLedger, previewPendingMigrations, reconcileMigrationLedger } from '@stacksjs/database'
+import { cachedComputation } from './cached-computation'
 
 export interface MigrationPlanOperation {
   kind: string
@@ -18,7 +19,55 @@ export class MigrationOperationError extends Error {
 
 const destructiveKinds = new Set(['drop_table', 'drop_column', 'alter_column', 'truncate_table'])
 
-export async function migrationPlan() {
+export type MigrationPlan = Awaited<ReturnType<typeof computeMigrationPlan>>
+
+/**
+ * How long a computed plan may be served to a reader.
+ *
+ * Building one costs a full model-versus-schema diff plus a ledger audit -
+ * measured at 2.3s and 1.4s against 93 models, versus 14ms for a normal
+ * dashboard endpoint. `/operations/migrations` and `/operations/changes` both
+ * built one per request, so opening either page cost seconds and moving
+ * between them paid it twice.
+ *
+ * Thirty seconds is long enough to cover a page load, a tab switch between
+ * the two operations pages, and a couple of refreshes, and short enough that
+ * editing a model and reloading shows the new plan without a manual step.
+ * Anything that changes the schema from inside the dashboard invalidates
+ * explicitly, so the window only ever hides changes made elsewhere.
+ */
+const PLAN_TTL_MS = 30_000
+
+const planCache = cachedComputation({ ttlMs: PLAN_TTL_MS, compute: () => computeMigrationPlan() })
+
+/**
+ * The ledger repair preview, cached on the same terms as the plan.
+ *
+ * `MigrationIndexAction` asks for both on every request, and a dry-run
+ * reconcile reads the same ledger the plan already audited - about 1.3s of
+ * the endpoint's cost, for a report that cannot have changed while the plan
+ * it sits next to has not.
+ */
+const reconciliationCache = cachedComputation({
+  ttlMs: PLAN_TTL_MS,
+  compute: () => reconcileMigrationLedger({ dryRun: true }),
+})
+
+/**
+ * Drop the cached view of migration state.
+ *
+ * Applying a migration or reconciling the ledger changes the very state these
+ * describe, so holding them for the rest of the TTL would show an operator
+ * the work they just did as still pending. Both go together: the plan and the
+ * repair preview are two readings of one state, and keeping one while
+ * dropping the other would put the page into a shape neither describes.
+ */
+export function invalidateMigrationPlan(): void {
+  planCache.invalidate()
+  reconciliationCache.invalidate()
+}
+
+async function computeMigrationPlan() {
   const [rawOperations, ledger] = await Promise.all([
     previewPendingMigrations(),
     auditMigrationLedger(),
@@ -41,6 +90,11 @@ export async function migrationPlan() {
     revision,
     applied: ledger.recordedCount,
     ledger,
+    // Stamped so a reader can tell how old the plan it is looking at is.
+    // Deliberately outside the `revision` hash above: revision identifies the
+    // schema state being approved, and must not change just because the same
+    // state was computed again a minute later.
+    computedAt: new Date().toISOString(),
     summary: {
       pending: operations.length,
       destructive: operations.filter(operation => operation.destructive).length,
@@ -50,8 +104,20 @@ export async function migrationPlan() {
   }
 }
 
+/**
+ * The model-derived schema plan and the migration ledger's health.
+ *
+ * Served from a short-lived cache by default. Pass `fresh` when the answer is
+ * about to gate a write: `revision` is an optimistic-concurrency token, and
+ * comparing a caller's token against a cached plan would let a change that
+ * landed during the window through the gate it exists to close.
+ */
+export async function migrationPlan(options: { fresh?: boolean } = {}): Promise<MigrationPlan> {
+  return await planCache.get(options)
+}
+
 export async function applyMigrationPlan(input: { revision: string, confirmation: string }): Promise<{ message: string }> {
-  const plan = await migrationPlan()
+  const plan = await migrationPlan({ fresh: true })
   if (input.revision !== plan.revision)
     throw new MigrationOperationError('The migration plan changed. Refresh and review the new plan before applying it.')
   if (input.confirmation !== `migrate ${plan.environment}`)
@@ -72,9 +138,22 @@ export async function applyMigrationPlan(input: { revision: string, confirmation
   ])
   if (exitCode !== 0)
     throw new MigrationOperationError(stderr.trim() || stdout.trim() || 'The migration command failed.')
+  // The schema just moved, so every cached plan describing the old one is
+  // wrong. Without this the operations pages would keep showing the applied
+  // work as pending for the rest of the TTL.
+  invalidateMigrationPlan()
   return { message: `Applied ${plan.operations.length} planned schema operation${plan.operations.length === 1 ? '' : 's'}.` }
 }
 
 export async function reconcileMigrationLedgerPlan(apply = false) {
-  return await reconcileMigrationLedger({ dryRun: !apply })
+  // A dry run reports what it would repair and changes nothing, so it is
+  // cacheable. A real one rewrites the ledger that the plan's `applied`,
+  // `drift` and `ledgerIssues` are read from, so it runs for real every time
+  // and drops what the old ledger produced.
+  if (!apply)
+    return await reconciliationCache.get()
+
+  const result = await reconcileMigrationLedger({ dryRun: false })
+  invalidateMigrationPlan()
+  return result
 }

package/app/Actions/Locale/SetLocaleAction.ts

@@ -1,9 +1,9 @@
 import { createLocaleSwitchResponse } from '@stacksjs/i18n'
 import { existsSync } from 'node:fs'
-import { projectPath } from '@stacksjs/path'
+import { siteConfigPath } from '@stacksjs/path'
 
 async function loadSiteI18n(): Promise<{ locales: string[], defaultLocale: string } | null> {
-  const sitePath = projectPath('site.config.ts')
+  const sitePath = siteConfigPath()
   if (!existsSync(sitePath))
     return null
 

package/ide/vscode/package.json

@@ -2,7 +2,7 @@
   "publisher": "Stacks",
   "name": "vscode-stacks",
   "displayName": "Stacks",
-  "version": "0.72.85",
+  "version": "0.72.89",
   "description": "A modern Stacks development environment.",
   "license": "MIT",
   "funding": "https://github.com/sponsors/chrisbbreuer",

package/package.json

@@ -2,7 +2,7 @@
   "name": "@stacksjs/defaults",
   "type": "module",
   "sideEffects": false,
-  "version": "0.72.85",
+  "version": "0.72.89",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/stacksjs/stacks.git",
@@ -51,7 +51,7 @@
   "dependencies": {
     "@iconify-json/f7": "^1.2.2",
     "@iconify-json/hugeicons": "^1.2.27",
-    "@stacksjs/mobile": "^0.72.85",
+    "@stacksjs/mobile": "^0.72.89",
     "@stacksjs/sanitizer": "^0.2.113"
   },
   "scripts": {

package/project/bootstrap

@@ -92,10 +92,16 @@ ensure_pantry() {
   echo "Pantry installed to ${INSTALL_DIR}/pantry"
 }
 
+is_stacks_app() {
+  [ -f "package.json" ] \
+    && [ -x "buddy" ] \
+    && grep -Eq '"stacks"[[:space:]]*:' package.json
+}
+
 # --- Main ---
 
 # If we are outside a project, create one from the latest stable release.
-if [ ! -d "storage/framework/core" ]; then
+if [ ! -d "storage/framework/core" ] && ! is_stacks_app; then
   if [ -z "$PROJECT_NAME" ]; then
     PROJECT_NAME="${STACKS_PROJECT:-stacks}"
 
@@ -142,7 +148,7 @@ if [ ! -d "storage/framework/core" ]; then
 fi
 
 # Detect if we're in a Stacks project
-if [ ! -d "storage/framework/core" ]; then
+if [ ! -d "storage/framework/core" ] && ! is_stacks_app; then
   echo "Error: not inside a Stacks project."
   exit 1
 fi