@pikku/core 0.12.96 → 0.12.98

package/src/services/typed-variables-service.ts

@@ -1,3 +1,4 @@
+import type { StandardSchemaV1 } from '@standard-schema/spec'
 import type { VariablesService } from './variables-service.js'
 
 export interface VariableStatus {
@@ -5,13 +6,35 @@ export interface VariableStatus {
   name: string
   displayName: string
   isConfigured: boolean
+  /** Whether the declaration answers for itself when the host sets nothing. */
+  hasDefault: boolean
 }
 
 export type VariableMeta = {
   name: string
   displayName: string
+  /**
+   * The shape the variable was declared with. It is the schema itself rather
+   * than a description of it, because a default is only knowable by running it:
+   * `undefined` goes in and, if the declaration carries one, the default comes
+   * back out.
+   *
+   * A thunk is accepted, and is what code generation emits. The generated file
+   * and the file declaring the schema import each other, so reading the schema
+   * while the modules are still initializing throws — deferring the read until
+   * a variable is actually asked for is what keeps the cycle harmless.
+   */
+  schema?: StandardSchemaV1 | (() => StandardSchemaV1)
 }
 
+const isPromise = (value: unknown): value is Promise<unknown> =>
+  typeof (value as Promise<unknown> | undefined)?.then === 'function'
+
+/**
+ * A declared default is the answer to a variable nobody set, so it is resolved
+ * here rather than in `VariablesService`: the store knows what a host has put
+ * in it, and only this layer knows what was declared.
+ */
 export class TypedVariablesService<
   TMap = Record<string, unknown>,
 > implements VariablesService {
@@ -25,13 +48,23 @@ export class TypedVariablesService<
   ): Promise<TMap[K] | undefined> | TMap[K] | undefined
   get<T = string>(name: string): Promise<T | undefined> | T | undefined
   get(name: string): Promise<unknown> | unknown {
-    return this.variables.get(name)
+    const stored = this.variables.get(name)
+    if (isPromise(stored)) {
+      return stored.then((value) =>
+        value === undefined ? this.resolveDefault(name) : value
+      )
+    }
+    return stored === undefined ? this.resolveDefault(name) : stored
   }
 
   getVariables<T extends Record<string, unknown> = Record<string, unknown>>(
     names: (keyof T & string)[]
   ): Promise<Partial<T>> | Partial<T> {
-    return this.variables.getVariables<T>(names)
+    const stored = this.variables.getVariables<T>(names)
+    if (isPromise(stored)) {
+      return stored.then((values) => this.withDefaults(names, values))
+    }
+    return this.withDefaults(names, stored)
   }
 
   getAll():
@@ -62,14 +95,72 @@ export class TypedVariablesService<
         name: meta.name,
         displayName: meta.displayName,
         isConfigured: all[variableId] !== undefined,
+        hasDefault: (await this.resolveDefault(variableId)) !== undefined,
       })
     }
 
     return results
   }
 
+  /**
+   * What a deployment still has to be told. A variable that defaults is not on
+   * this list — it has a value, just not one anybody has to supply.
+   */
   async getMissing(): Promise<VariableStatus[]> {
     const all = await this.getAllStatus()
-    return all.filter((v) => !v.isConfigured)
+    return all.filter((v) => !v.isConfigured && !v.hasDefault)
+  }
+
+  /**
+   * The value the declaration answers with when the host set nothing, or
+   * `undefined` when it does not answer for itself.
+   */
+  private resolveDefault(name: string): Promise<unknown> | unknown {
+    const declared = this.variablesMeta[name]?.schema
+    if (!declared) {
+      return undefined
+    }
+    const schema = typeof declared === 'function' ? declared() : declared
+    const result = schema['~standard'].validate(undefined)
+    if (isPromise(result)) {
+      return result.then(unwrapDefault)
+    }
+    return unwrapDefault(result)
+  }
+
+  /**
+   * Kept synchronous when the defaults resolve synchronously, so a caller that
+   * did not await `getVariables` before does not have to start.
+   */
+  private withDefaults<T extends Record<string, unknown>>(
+    names: (keyof T & string)[],
+    values: Partial<T>
+  ): Promise<Partial<T>> | Partial<T> {
+    const out: Record<string, unknown> = { ...values }
+    const pending: Promise<void>[] = []
+    for (const name of names) {
+      if (out[name] !== undefined) continue
+      const fallback = this.resolveDefault(name)
+      if (isPromise(fallback)) {
+        pending.push(
+          fallback.then((value) => {
+            if (value !== undefined) out[name] = value
+          })
+        )
+      } else if (fallback !== undefined) {
+        out[name] = fallback
+      }
+    }
+    if (pending.length > 0) {
+      return Promise.all(pending).then(() => out as Partial<T>)
+    }
+    return out as Partial<T>
   }
 }
+
+/**
+ * A schema with no default rejects `undefined`, which is not a failure here —
+ * it is the answer that there is nothing to fall back to.
+ */
+const unwrapDefault = (result: StandardSchemaV1.Result<unknown>) =>
+  result.issues ? undefined : result.value

package/src/wirings/virtual-user/virtual-user-scaffold.test.ts

@@ -244,6 +244,65 @@ describe('startVirtualUserRun', () => {
     assert.equal(started[0].disposition, 'accountable')
   })
 
+  // The case NODE_ENV cannot answer: a staging environment that is a production
+  // mirror runs NODE_ENV=production too, and refusing every disposition there
+  // refuses them on the one environment they exist to be used on.
+  test('a non-production environment allows a probing disposition', async () => {
+    const { store, started } = runStore()
+    await startVirtualUserRun({
+      store,
+      personas,
+      config: { nodeEnv: 'production' },
+      environments: { staging: {}, production: { production: true } },
+      environment: 'staging',
+      persona: 'susan',
+      disposition: 'adversarial',
+    })
+    assert.equal(started[0].disposition, 'adversarial')
+  })
+
+  test('the configured production environment still refuses one', async () => {
+    const { store, started } = runStore()
+    await assert.rejects(
+      startVirtualUserRun({
+        store,
+        personas,
+        config: { nodeEnv: 'development' },
+        environments: { staging: {}, production: { production: true } },
+        environment: 'production',
+        persona: 'susan',
+        disposition: 'adversarial',
+      }),
+      /Only the 'accountable' disposition may run against production/
+    )
+    assert.equal(started.length, 0)
+  })
+
+  // An environment nobody can name is one whose data nobody can vouch for.
+  // PIKKU_ENV is cleared rather than passed as undefined: it is the default the
+  // parameter falls back to, so leaving it set would test the wrong thing.
+  test('an unresolved environment is treated as production', async () => {
+    const { store, started } = runStore()
+    const pikkuEnv = process.env.PIKKU_ENV
+    delete process.env.PIKKU_ENV
+    try {
+      await assert.rejects(
+        startVirtualUserRun({
+          store,
+          personas,
+          config: { nodeEnv: 'development' },
+          environments: { staging: {}, production: { production: true } },
+          persona: 'susan',
+          disposition: 'adversarial',
+        }),
+        /Only the 'accountable' disposition may run against production/
+      )
+    } finally {
+      if (pikkuEnv !== undefined) process.env.PIKKU_ENV = pikkuEnv
+    }
+    assert.equal(started.length, 0)
+  })
+
   test('refuses a persona that is declared as acted upon', async () => {
     const { store, started } = runStore()
     await assert.rejects(

package/src/wirings/virtual-user/virtual-user-scaffold.ts

@@ -11,6 +11,7 @@ import { prepareVirtualUserRun } from './prepare-virtual-user-run.js'
 import { runVirtualUser as runVirtualUserEngine } from './run-virtual-user.js'
 import { personaVirtualUserTarget } from './virtual-user-target.js'
 import type { SchemaMap } from './virtual-user-derive.js'
+import type { PersonaEnvironment } from '../persona/persona-environments.js'
 import { PRODUCTION_DISPOSITION } from './virtual-user.types.js'
 import type {
   StepRecord,
@@ -160,8 +161,13 @@ export interface StartVirtualUserRunParams {
   /**
    * The app's config, read only for `nodeEnv` — structural because an
    * application's Config is its own interface and need not declare it at all.
+   * The fallback signal, used only by a project that configures no environments.
    */
   config: { nodeEnv?: string } | undefined
+  /** `environments` from pikku.config.json, as generated beside the personas. */
+  environments?: Readonly<Record<string, PersonaEnvironment>>
+  /** Which of them this process is. Defaults to `PIKKU_ENV`. */
+  environment?: string
   persona: string
   disposition?: string
   seed?: number
@@ -181,6 +187,33 @@ export interface StartedVirtualUserRun {
   memory: Record<string, string>
 }
 
+/**
+ * Whether this process is running against production, for the disposition rule.
+ *
+ * The configured environment wins over `NODE_ENV` because they answer different
+ * questions. A deployment whose staging is a production *mirror* runs
+ * `NODE_ENV=production` there too — keying on it refuses every disposition on
+ * the one environment they exist to be used on. `PIKKU_ENV` names which of the
+ * configured environments this is, which is the question actually being asked,
+ * and it is the same signal `personaEnvironmentRefusal` already checks at
+ * sign-in.
+ *
+ * Unresolved is treated as production: an environment nobody can name is one
+ * whose data nobody can vouch for. `NODE_ENV` remains the answer only for a
+ * project that configures no environments at all, which has no production
+ * environment declared for this to be wrong about.
+ */
+const isProductionRun = (
+  config: { nodeEnv?: string } | undefined,
+  environments: Readonly<Record<string, PersonaEnvironment>> | undefined,
+  environment: string | undefined
+): boolean => {
+  if (!environments || Object.keys(environments).length === 0) {
+    return config?.nodeEnv === 'production'
+  }
+  return environment ? Boolean(environments[environment]?.production) : true
+}
+
 /**
  * Resolves a request against the declaration and records the run.
  *
@@ -192,6 +225,8 @@ export const startVirtualUserRun = async ({
   store,
   personas,
   config,
+  environments,
+  environment = process.env.PIKKU_ENV,
   persona: personaId,
   disposition: requested,
   seed: requestedSeed,
@@ -210,8 +245,8 @@ export const startVirtualUserRun = async ({
   // does wrong, which is not a thing to do to real customers' data. Checked
   // against the effective disposition, so an override cannot smuggle one in.
   if (
-    config?.nodeEnv === 'production' &&
-    disposition !== PRODUCTION_DISPOSITION
+    disposition !== PRODUCTION_DISPOSITION &&
+    isProductionRun(config, environments, environment)
   ) {
     throw new Error(
       `Only the '${PRODUCTION_DISPOSITION}' disposition may run against production; "${personaId}" is ${disposition}`