@strav/cache 1.0.0-alpha.29 → 1.0.0-alpha.30

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@strav/cache",
-  "version": "1.0.0-alpha.29",
+  "version": "1.0.0-alpha.30",
   "description": "Strav cache layer — Cache abstraction + MemoryCache (in-process) + PostgresCache (cross-process ledger) + RedisCache (Bun.RedisClient, all data structures incl. tagged sets) + MemcachedCache (text-protocol client over Bun.connect). Atomic increments, distributed locks, tagged invalidation. Mirrors @strav/broadcast: kernel-free core in the root, every driver under its own subpath.",
   "type": "module",
   "main": "./src/index.ts",
@@ -10,7 +10,8 @@
     "./memory": "./src/drivers/memory/index.ts",
     "./postgres": "./src/drivers/postgres/index.ts",
     "./redis": "./src/drivers/redis/index.ts",
-    "./memcached": "./src/drivers/memcached/index.ts"
+    "./memcached": "./src/drivers/memcached/index.ts",
+    "./console": "./src/console/index.ts"
   },
   "files": [
     "src",
@@ -23,10 +24,11 @@
     "access": "public"
   },
   "dependencies": {
-    "@strav/kernel": "1.0.0-alpha.29"
+    "@strav/cli": "1.0.0-alpha.30",
+    "@strav/kernel": "1.0.0-alpha.30"
   },
   "peerDependencies": {
-    "@strav/database": "1.0.0-alpha.29",
+    "@strav/database": "1.0.0-alpha.30",
     "@types/bun": ">=1.3.14"
   },
   "peerDependenciesMeta": {

package/src/console/cache_clear.ts

@@ -0,0 +1,44 @@
+/**
+ * `bun strav cache:clear [--force]` — flush every key from the
+ * active cache store.
+ *
+ * Mirrors `Cache.flush()` directly. Confirms before running unless
+ * `--force` is set (CI / scripted teardown). Driver-specific
+ * notes:
+ *
+ *   - `MemoryCache` — clears the in-process map; only affects this
+ *     process.
+ *   - `RedisCache` — `SCAN` + `DEL` under the configured `prefix`
+ *     so other apps sharing the Redis DB are untouched.
+ *   - `PostgresCache` — `TRUNCATE` of the cache ledger table.
+ *   - `MemcachedCache` — `FLUSH_ALL` (server-wide).
+ *
+ * Use scoped invalidation (`cache.tags(...).flush()`,
+ * `cache.forget(key)`) in production code paths; `cache:clear` is
+ * the deploy-time / dev tool.
+ */
+
+import { Command, type ExecuteArgs, ExitCode } from '@strav/cli'
+import { Cache } from '../cache.ts'
+
+export class CacheClear extends Command {
+  static signature = 'cache:clear {--force}'
+  static description = 'Flush every entry from the active cache store.'
+  static providers = ['config', 'logger', 'cache']
+
+  override async execute({ flags }: ExecuteArgs): Promise<number> {
+    if (flags.force !== true) {
+      const ok = await this.confirm(
+        'Flush every entry from the active cache store? This is irreversible.',
+      )
+      if (!ok) {
+        this.info('Aborted.')
+        return ExitCode.Success
+      }
+    }
+    const cache = this.app.resolve(Cache)
+    await cache.flush()
+    this.success('Cache flushed.')
+    return ExitCode.Success
+  }
+}

package/src/console/cache_console_provider.ts

@@ -0,0 +1,20 @@
+/**
+ * `CacheConsoleProvider` — declares the `cache:*` commands.
+ *
+ * Apps add it to `bootstrap/providers.ts` alongside the cache
+ * provider (`CacheProvider` for in-memory, `RedisCacheProvider`,
+ * `PostgresCacheProvider`, or `MemcachedCacheProvider`). Separate
+ * provider so apps that don't ship a CLI don't pay the cost of
+ * resolving commands at boot — same pattern as
+ * `QueueConsoleProvider` and `RagConsoleProvider`.
+ */
+
+import { ConsoleProvider } from '@strav/cli'
+import { CacheClear } from './cache_clear.ts'
+import { CacheForget } from './cache_forget.ts'
+import { CacheList } from './cache_list.ts'
+
+export class CacheConsoleProvider extends ConsoleProvider {
+  override readonly name = 'console.cache'
+  override readonly commands = [CacheClear, CacheForget, CacheList] as const
+}

package/src/console/cache_forget.ts

@@ -0,0 +1,28 @@
+/**
+ * `bun strav cache:forget <key>` — drop one cache entry.
+ *
+ * Exit code 0 when a key was removed; 0 with a warning when nothing
+ * matched (no key to forget is not an error — apps script this from
+ * deploy hooks where the entry may or may not be live).
+ */
+
+import { Command, type ExecuteArgs, ExitCode } from '@strav/cli'
+import { Cache } from '../cache.ts'
+
+export class CacheForget extends Command {
+  static signature = 'cache:forget {key}'
+  static description = 'Delete a single cache entry by key.'
+  static providers = ['config', 'logger', 'cache']
+
+  override async execute({ args }: ExecuteArgs): Promise<number> {
+    const key = args.key as string
+    const cache = this.app.resolve(Cache)
+    const removed = await cache.forget(key)
+    if (removed) {
+      this.success(`Forgot "${key}".`)
+    } else {
+      this.warn(`No entry for "${key}".`)
+    }
+    return ExitCode.Success
+  }
+}

package/src/console/cache_list.ts

@@ -0,0 +1,42 @@
+/**
+ * `bun strav cache:list` — print the active cache driver + key
+ * config knobs.
+ *
+ * Diagnostic only. Useful for verifying that `config/cache.ts`
+ * parses cleanly and that the deployed binary picked up the
+ * intended driver (Redis vs in-memory in CI, etc.). No mutations.
+ */
+
+import { Command, type ExecuteArgs, ExitCode } from '@strav/cli'
+import { ConfigRepository } from '@strav/kernel'
+
+export class CacheList extends Command {
+  static signature = 'cache:list'
+  static description = 'Show the active cache driver and its configuration.'
+  static providers = ['config', 'logger', 'cache']
+
+  override async execute(_args: ExecuteArgs): Promise<number> {
+    const cfg = this.app.resolve(ConfigRepository).get('cache') as
+      | (Record<string, unknown> & { driver?: string })
+      | undefined
+
+    if (cfg === undefined) {
+      this.info('No `config.cache` entry. The cache provider booted with defaults.')
+      return ExitCode.Success
+    }
+
+    const driver = cfg.driver ?? '(unset)'
+    this.info(`Driver: ${driver}`)
+    for (const [key, value] of Object.entries(cfg)) {
+      if (key === 'driver') continue
+      const printed =
+        typeof value === 'string' && key.toLowerCase().includes('password')
+          ? '***'
+          : typeof value === 'object'
+            ? JSON.stringify(value)
+            : String(value)
+      this.info(`  ${key}: ${printed}`)
+    }
+    return ExitCode.Success
+  }
+}

package/src/console/index.ts

@@ -0,0 +1,4 @@
+export { CacheClear } from './cache_clear.ts'
+export { CacheConsoleProvider } from './cache_console_provider.ts'
+export { CacheForget } from './cache_forget.ts'
+export { CacheList } from './cache_list.ts'