@strav/flag 0.4.31 → 1.0.0-alpha.42

package/README.md

@@ -1,65 +1,131 @@
 # @strav/flag
 
-Feature flags for the [Strav](https://www.npmjs.com/package/@strav/core) framework. Define, scope, and toggle features with database persistence, in-memory drivers, and per-user/team targeting.
+Feature flags for [Strav 1.x](https://github.com/strav-dev/strav-1.x). Define
+flags, scope them per user / team / tenant, persist resolutions in-memory or in
+Postgres, and gate routes with an HTTP middleware. Mirrors the shape of
+`@strav/cache` — kernel-free core in the root, drivers and integrations under
+subpaths.
 
 ## Install
 
 ```bash
 bun add @strav/flag
-bun strav install flag
 ```
 
-Requires `@strav/core` as a peer dependency.
-
-## Setup
+## Quick start
 
 ```ts
-import { FlagProvider } from '@strav/flag'
+import { FlagManager, FlagProvider } from '@strav/flag'
 
-app.use(new FlagProvider())
-```
+// Wire the provider (in-memory store by default).
+new FlagProvider({
+  define(flags) {
+    flags.define('beta-ui', (scope) => scope.startsWith('User:1'))
+    flags.define('upload-limit', 25)
+  },
+})
 
-## Usage
+// Resolve and read.
+const flags = app.resolve(FlagManager)
 
-```ts
-import { flag } from '@strav/flag'
+if (await flags.active('beta-ui', user)) { ... }
+if (await flags.for(team).active('analytics')) { ... }
+
+const limit = await flags.value('upload-limit')  // 25
+```
+
+## Drivers
 
-// Check if a feature is active
-if (await flag.active('dark-mode')) {
-  // feature is enabled
-}
+| Subpath                 | Driver                | Use case                               |
+| ----------------------- | --------------------- | -------------------------------------- |
+| (root)                  | `MemoryFlagStore`     | dev / tests / single-process apps      |
+| `@strav/flag/postgres`  | `PostgresFlagStore`   | multi-node deployments (cross-process) |
 
-// Scoped to a user or team
-if (await flag.for(user).active('beta-dashboard')) {
-  // enabled for this user
-}
+Swap providers — both register under the same `FlagManager` token:
 
-// Rich values
-const limit = await flag.value('upload-limit', 10)
+```ts
+import { PostgresFlagProvider, applyFlagMigration } from '@strav/flag/postgres'
+
+// Migration:
+await applyFlagMigration(db)
+
+// Provider:
+providers: [
+  new PostgresFlagProvider({
+    define(flags) {
+      flags.define('beta-ui', (scope) => scope.startsWith('User:'))
+    },
+  }),
+]
 ```
 
-## Middleware
+## HTTP guard
 
 ```ts
-import { ensureFeature } from '@strav/flag'
+import { ensureFeature } from '@strav/flag/http'
 
-router.get('/beta', ensureFeature('beta-dashboard'), betaHandler)
+router.get('/beta', ensureFeature('beta-ui'), betaHandler)
+router.group(
+  { middleware: [authMiddleware(), ensureFeature('analytics')] },
+  (r) => r.get('/insights', insights),
+)
 ```
 
-## Drivers
-
-- **Database** — persistent feature flags in `_strav_features`
-- **Array** — in-memory driver for testing
+Default scope is `ctx.auth?.user`. Pass `scopeFrom` for team / tenant / custom
+subjects.
 
 ## CLI
 
 ```bash
-bun strav flag:setup    # Create the features table
+bun strav flag:list                          # list stored flags + values
+bun strav flag:activate beta-ui              # global on
+bun strav flag:activate beta-ui '"control"' --scope User:42
+bun strav flag:deactivate beta-ui --scope User:42
+bun strav flag:purge beta-ui                 # drop stored values → re-resolve
 ```
 
-## Documentation
+Register the commands provider alongside the flag provider:
+
+```ts
+import { FlagConsoleProvider } from '@strav/flag/console'
 
-See the full [Flag guide](../../guides/flag.md).
+providers: [
+  new FlagProvider({ /* … */ }),
+  new FlagConsoleProvider(),
+]
+```
+
+## Strict scopes
+
+```ts
+// config/flag.ts
+export default { strictScopes: true }
+```
+
+With `strictScopes: true`, reading a flag without a scope throws
+`MissingScopeError` instead of silently evaluating the global value. Catches the
+common bug where middleware forgets to pass `ctx.auth.user`. Writes keep the
+loose semantics — `activateForEveryone()` makes a global write explicit.
+
+## Audit hook
+
+`activate` / `deactivate` accept an optional `actor: { type, id }` that flows
+into the `flag:updated` event payload alongside `previous` (the prior stored
+value). Subscribe via `EventBus` to wire an audit log without coupling
+`@strav/flag` to `@strav/audit`:
+
+```ts
+app.resolve(EventBus).on('flag:updated', (e) => {
+  if (!e.actor) return
+  auditLog.record({
+    actor: e.actor,
+    on: 'feature_flag',
+    feature: e.feature,
+    scope: e.scope,
+    diff: { from: e.previous, to: e.value },
+  })
+})
+```
 
 ## License
 

package/package.json

@@ -1,33 +1,46 @@
 {
   "name": "@strav/flag",
-  "version": "0.4.31",
+  "version": "1.0.0-alpha.42",
+  "description": "Strav feature-flag primitive — FlagManager + scope-aware resolution + in-memory store, with Postgres store, HTTP middleware, and CLI commands shipped under subpaths. Mirrors @strav/cache: kernel-free core in the root, every backend/integration under its own subpath.",
   "type": "module",
-  "description": "Feature flags for the Strav framework",
-  "license": "MIT",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
   "exports": {
     ".": "./src/index.ts",
-    "./*": "./src/*.ts"
-  },
-  "strav": {
-    "commands": "src/commands"
+    "./memory": "./src/drivers/memory/index.ts",
+    "./postgres": "./src/drivers/postgres/index.ts",
+    "./http": "./src/http/index.ts",
+    "./console": "./src/console/index.ts"
   },
   "files": [
-    "src/",
-    "stubs/",
-    "package.json",
-    "tsconfig.json"
+    "src",
+    "README.md"
   ],
+  "engines": {
+    "bun": ">=1.3.14"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@strav/kernel": "1.0.0-alpha.42"
+  },
   "peerDependencies": {
-    "@strav/kernel": "0.4.31",
-    "@strav/database": "0.4.31",
-    "@strav/http": "0.4.31",
-    "@strav/cli": "0.4.31"
+    "@strav/cli": "1.0.0-alpha.42",
+    "@strav/database": "1.0.0-alpha.42",
+    "@strav/http": "1.0.0-alpha.42",
+    "@types/bun": ">=1.3.14"
   },
-  "scripts": {
-    "test": "bun test tests/",
-    "typecheck": "tsc --noEmit"
+  "peerDependenciesMeta": {
+    "@strav/cli": {
+      "optional": true
+    },
+    "@strav/database": {
+      "optional": true
+    },
+    "@strav/http": {
+      "optional": true
+    }
   },
-  "devDependencies": {
-    "commander": "^14.0.3"
-  }
+  "devDependencies": null
 }

package/src/console/flag_activate.ts

@@ -0,0 +1,60 @@
+/**
+ * `bun strav flag:activate <feature> [value] [--scope <Type:id>]` —
+ * turn a flag on, optionally with a rich JSON value, for a specific
+ * scope or globally (default).
+ *
+ * The scope format mirrors the on-disk serialization (`User:42`,
+ * `Team:7`) — passing one is sufficient because the operator pins the
+ * scope manually; the runtime resolver pulls scopes off live request
+ * state, where the type prefix is derived automatically.
+ */
+
+import { Command, type ExecuteArgs, ExitCode } from '@strav/cli'
+import { FlagError } from '../flag_error.ts'
+import { FlagManager } from '../flag_manager.ts'
+
+export class FlagActivate extends Command {
+  static signature = 'flag:activate {feature} {value?} {--scope=}'
+  static description = 'Turn a flag on, optionally with a JSON value, for a scope or globally.'
+  static providers = ['config', 'logger', 'flag']
+
+  override async execute({ args, flags: cli }: ExecuteArgs): Promise<number> {
+    const flags = this.app.resolve(FlagManager)
+    const feature = args.feature as string
+    const raw = args.value as string | undefined
+    const scope = cli.scope as string | undefined
+
+    const value = raw !== undefined ? parseValue(raw) : true
+
+    if (scope === undefined) {
+      await flags.activateForEveryone(feature, value)
+      this.success(`Activated "${feature}" globally${raw ? ` = ${raw}` : ''}.`)
+    } else {
+      await flags.activate(feature, value, scopeFromKey(scope))
+      this.success(`Activated "${feature}" for ${scope}${raw ? ` = ${raw}` : ''}.`)
+    }
+    return ExitCode.Success
+  }
+}
+
+function parseValue(raw: string): unknown {
+  try {
+    return JSON.parse(raw)
+  } catch {
+    return raw
+  }
+}
+
+// CLI helper: turn `User:42` into a fake Scopeable so the manager
+// serializes it back to the same `User:42` key. The runtime
+// resolution path always works on live objects with `id`; this is the
+// inverse used only at the CLI boundary.
+function scopeFromKey(key: string): { id: string | number; featureScope: () => string } {
+  const colon = key.indexOf(':')
+  if (colon <= 0) {
+    throw new FlagError(`--scope must look like "Type:id" (e.g. "User:42"); got "${key}".`)
+  }
+  const type = key.slice(0, colon)
+  const id: string | number = key.slice(colon + 1)
+  return { id, featureScope: () => type }
+}

package/src/console/flag_console_provider.ts

@@ -0,0 +1,25 @@
+/**
+ * `FlagConsoleProvider` — declares the `flag:*` console commands.
+ *
+ * Apps register it alongside the flag provider:
+ *
+ *   providers: [
+ *     new FlagProvider(),        // or PostgresFlagProvider from @strav/flag/postgres
+ *     new FlagConsoleProvider(),
+ *   ]
+ *
+ * Separate provider so apps without a CLI don't pay the cost of
+ * resolving commands at boot — same pattern as `CacheConsoleProvider`
+ * and `QueueConsoleProvider`.
+ */
+
+import { ConsoleProvider } from '@strav/cli'
+import { FlagActivate } from './flag_activate.ts'
+import { FlagDeactivate } from './flag_deactivate.ts'
+import { FlagList } from './flag_list.ts'
+import { FlagPurge } from './flag_purge.ts'
+
+export class FlagConsoleProvider extends ConsoleProvider {
+  override readonly name = 'console.flag'
+  override readonly commands = [FlagList, FlagPurge, FlagActivate, FlagDeactivate] as const
+}

package/src/console/flag_deactivate.ts

@@ -0,0 +1,37 @@
+/**
+ * `bun strav flag:deactivate <feature> [--scope <Type:id>]` — turn a
+ * flag off for a specific scope or globally (default).
+ */
+
+import { Command, type ExecuteArgs, ExitCode } from '@strav/cli'
+import { FlagError } from '../flag_error.ts'
+import { FlagManager } from '../flag_manager.ts'
+
+export class FlagDeactivate extends Command {
+  static signature = 'flag:deactivate {feature} {--scope=}'
+  static description = 'Turn a flag off for a scope or globally.'
+  static providers = ['config', 'logger', 'flag']
+
+  override async execute({ args, flags: cli }: ExecuteArgs): Promise<number> {
+    const flags = this.app.resolve(FlagManager)
+    const feature = args.feature as string
+    const scope = cli.scope as string | undefined
+
+    if (scope === undefined) {
+      await flags.deactivateForEveryone(feature)
+      this.success(`Deactivated "${feature}" globally.`)
+    } else {
+      await flags.deactivate(feature, scopeFromKey(scope))
+      this.success(`Deactivated "${feature}" for ${scope}.`)
+    }
+    return ExitCode.Success
+  }
+}
+
+function scopeFromKey(key: string): { id: string | number; featureScope: () => string } {
+  const colon = key.indexOf(':')
+  if (colon <= 0) {
+    throw new FlagError(`--scope must look like "Type:id" (e.g. "User:42"); got "${key}".`)
+  }
+  return { id: key.slice(colon + 1), featureScope: () => key.slice(0, colon) }
+}

package/src/console/flag_list.ts

@@ -0,0 +1,32 @@
+/**
+ * `bun strav flag:list` — list every feature with at least one stored
+ * value and its per-scope evaluations. Read-only.
+ */
+
+import { Command, type ExecuteArgs, ExitCode } from '@strav/cli'
+import { FlagManager } from '../flag_manager.ts'
+
+export class FlagList extends Command {
+  static signature = 'flag:list'
+  static description = 'List stored feature flags and their per-scope values.'
+  static providers = ['config', 'logger', 'flag']
+
+  override async execute(_args: ExecuteArgs): Promise<number> {
+    const flags = this.app.resolve(FlagManager)
+    const names = await flags.stored()
+    if (names.length === 0) {
+      this.info('No stored feature flags.')
+      return ExitCode.Success
+    }
+    this.info(`Stored feature flags (${names.length}):`)
+    for (const name of names) {
+      const records = await flags.driver().allFor(name)
+      this.info(`  ${name} (${records.length} scope${records.length === 1 ? '' : 's'})`)
+      for (const r of records) {
+        const printed = typeof r.value === 'boolean' ? String(r.value) : JSON.stringify(r.value)
+        this.info(`    ${r.scope} → ${printed}`)
+      }
+    }
+    return ExitCode.Success
+  }
+}

package/src/console/flag_purge.ts

@@ -0,0 +1,38 @@
+/**
+ * `bun strav flag:purge [feature] [--all] [--force]` — drop stored
+ * flag values so resolvers re-evaluate. Without `--force`, prompts
+ * before running.
+ */
+
+import { Command, type ExecuteArgs, ExitCode } from '@strav/cli'
+import { FlagManager } from '../flag_manager.ts'
+
+export class FlagPurge extends Command {
+  static signature = 'flag:purge {feature?} {--all} {--force}'
+  static description = 'Drop stored flag values (forces re-resolution on next read).'
+  static providers = ['config', 'logger', 'flag']
+
+  override async execute({ args, flags: cli }: ExecuteArgs): Promise<number> {
+    const flags = this.app.resolve(FlagManager)
+    const feature = args.feature as string | undefined
+    const all = cli.all === true || !feature
+
+    if (cli.force !== true) {
+      const target = all ? 'EVERY feature flag' : `feature "${feature}"`
+      const ok = await this.confirm(`Purge ${target}? This drops stored values for all scopes.`)
+      if (!ok) {
+        this.info('Aborted.')
+        return ExitCode.Success
+      }
+    }
+
+    if (all) {
+      await flags.purgeAll()
+      this.success('All feature flags purged.')
+    } else {
+      await flags.purge(feature as string)
+      this.success(`Feature "${feature}" purged.`)
+    }
+    return ExitCode.Success
+  }
+}

package/src/console/index.ts

@@ -0,0 +1,5 @@
+export { FlagActivate } from './flag_activate.ts'
+export { FlagConsoleProvider } from './flag_console_provider.ts'
+export { FlagDeactivate } from './flag_deactivate.ts'
+export { FlagList } from './flag_list.ts'
+export { FlagPurge } from './flag_purge.ts'

package/src/drivers/memory/index.ts

@@ -0,0 +1 @@
+export { MemoryFlagStore } from './memory_flag_store.ts'

package/src/drivers/memory/memory_flag_store.ts

@@ -0,0 +1,94 @@
+/**
+ * `MemoryFlagStore` — in-process feature flag store backed by a single
+ * `Map`. Right driver for dev / tests / per-process resolutions that
+ * don't need cross-process visibility. Wrong driver for multi-node
+ * deployments — each node sees its own copy of every flag.
+ */
+
+import type { FeatureStore } from '../../feature_store.ts'
+import type { ScopeKey, StoredFeature } from '../../types.ts'
+
+interface Entry {
+  value: unknown
+  createdAt: Date
+  updatedAt: Date
+}
+
+export class MemoryFlagStore implements FeatureStore {
+  readonly name = 'memory'
+  private readonly data = new Map<string, Entry>()
+
+  private key(feature: string, scope: ScopeKey): string {
+    return `${feature}\0${scope}`
+  }
+
+  async get(feature: string, scope: ScopeKey): Promise<unknown | undefined> {
+    return this.data.get(this.key(feature, scope))?.value
+  }
+
+  async getMany(features: string[], scope: ScopeKey): Promise<Map<string, unknown>> {
+    const result = new Map<string, unknown>()
+    for (const f of features) {
+      const e = this.data.get(this.key(f, scope))
+      if (e !== undefined) result.set(f, e.value)
+    }
+    return result
+  }
+
+  async set(feature: string, scope: ScopeKey, value: unknown): Promise<void> {
+    const k = this.key(feature, scope)
+    const existing = this.data.get(k)
+    const now = new Date()
+    this.data.set(k, {
+      value,
+      createdAt: existing?.createdAt ?? now,
+      updatedAt: now,
+    })
+  }
+
+  async setMany(
+    entries: Array<{ feature: string; scope: ScopeKey; value: unknown }>,
+  ): Promise<void> {
+    for (const e of entries) await this.set(e.feature, e.scope, e.value)
+  }
+
+  async forget(feature: string, scope: ScopeKey): Promise<void> {
+    this.data.delete(this.key(feature, scope))
+  }
+
+  async purge(feature: string): Promise<void> {
+    const prefix = `${feature}\0`
+    for (const k of this.data.keys()) {
+      if (k.startsWith(prefix)) this.data.delete(k)
+    }
+  }
+
+  async purgeAll(): Promise<void> {
+    this.data.clear()
+  }
+
+  async featureNames(): Promise<string[]> {
+    const names = new Set<string>()
+    for (const k of this.data.keys()) {
+      const sep = k.indexOf('\0')
+      if (sep > 0) names.add(k.slice(0, sep))
+    }
+    return [...names].sort()
+  }
+
+  async allFor(feature: string): Promise<StoredFeature[]> {
+    const prefix = `${feature}\0`
+    const out: StoredFeature[] = []
+    for (const [k, e] of this.data) {
+      if (!k.startsWith(prefix)) continue
+      out.push({
+        feature,
+        scope: k.slice(prefix.length),
+        value: e.value,
+        createdAt: e.createdAt,
+        updatedAt: e.updatedAt,
+      })
+    }
+    return out
+  }
+}

package/src/drivers/postgres/apply_flag_migration.ts

@@ -0,0 +1,32 @@
+/**
+ * `applyFlagMigration` — emit the DDL `PostgresFlagStore` requires.
+ *
+ *   strav_flags (
+ *     feature    text        NOT NULL,
+ *     scope      text        NOT NULL,
+ *     value      jsonb       NOT NULL,
+ *     created_at timestamptz NOT NULL DEFAULT now(),
+ *     updated_at timestamptz NOT NULL DEFAULT now(),
+ *     PRIMARY KEY (feature, scope)
+ *   )
+ *
+ * Not registered with the SchemaRegistry — the table shape (composite
+ * PK, jsonb value column) doesn't fit the schema DSL cleanly, and
+ * the table is package-internal infrastructure rather than an app
+ * model. Call from a migration `up()`; `DROP TABLE` in `down()`.
+ */
+
+import type { DatabaseExecutor } from '@strav/database'
+
+export async function applyFlagMigration(db: DatabaseExecutor): Promise<void> {
+  await db.execute(
+    `CREATE TABLE IF NOT EXISTS "strav_flags" (
+       "feature"    text        NOT NULL,
+       "scope"      text        NOT NULL,
+       "value"      jsonb       NOT NULL,
+       "created_at" timestamptz NOT NULL DEFAULT now(),
+       "updated_at" timestamptz NOT NULL DEFAULT now(),
+       PRIMARY KEY ("feature", "scope")
+     )`,
+  )
+}

package/src/drivers/postgres/index.ts

@@ -0,0 +1,10 @@
+export { applyFlagMigration } from './apply_flag_migration.ts'
+export {
+  PostgresFlagProvider,
+  type PostgresFlagProviderOptions,
+} from './postgres_flag_provider.ts'
+export {
+  type PostgresFlagDatabase,
+  PostgresFlagStore,
+  type PostgresFlagStoreOptions,
+} from './postgres_flag_store.ts'

package/src/drivers/postgres/postgres_flag_provider.ts

@@ -0,0 +1,49 @@
+/**
+ * `PostgresFlagProvider` — wires `FlagManager` with `PostgresFlagStore`.
+ * Apps register this INSTEAD OF `FlagProvider` to swap the in-memory
+ * store for the cross-process Postgres backplane. Both providers
+ * register under the same `FlagManager` token, so app code injecting
+ * the manager doesn't change between dev and prod.
+ *
+ * Schema creation is migration-driven (`applyFlagMigration`); the
+ * provider does NOT auto-create on boot.
+ */
+
+import { type Application, ConfigRepository, EventBus, ServiceProvider } from '@strav/kernel'
+import { FlagManager } from '../../flag_manager.ts'
+import type { FlagConfig } from '../../types.ts'
+import { type PostgresFlagDatabase, PostgresFlagStore } from './postgres_flag_store.ts'
+
+export interface PostgresFlagProviderOptions {
+  /** Run after the manager is created, before `boot` returns. Use for `define`. */
+  define?: (flags: FlagManager) => void | Promise<void>
+}
+
+export class PostgresFlagProvider extends ServiceProvider {
+  override readonly name = 'flag'
+  override readonly dependencies = ['config', 'database']
+
+  constructor(private readonly options: PostgresFlagProviderOptions = {}) {
+    super()
+  }
+
+  override register(app: Application): void {
+    app.singleton(FlagManager, (c) => {
+      // Resolve `Database` by string token to keep `@strav/database` an
+      // optional peer-dep — apps using `MemoryFlagStore` shouldn't
+      // pay for `@strav/database` in their bundle.
+      const db = c.resolve<PostgresFlagDatabase>('database' as never)
+      const cfg = (c.resolve(ConfigRepository).get('flag') as FlagConfig | undefined) ?? {}
+      return new FlagManager({
+        store: new PostgresFlagStore({ db }),
+        events: c.resolve(EventBus),
+        config: cfg,
+      })
+    })
+  }
+
+  override async boot(app: Application): Promise<void> {
+    const flags = app.resolve(FlagManager)
+    if (this.options.define) await this.options.define(flags)
+  }
+}