@pikku/core 0.12.107 → 0.12.112

package/dist/analytics/compose-analytics-identity.js

@@ -0,0 +1,33 @@
+/**
+ * Runs resolvers in order, each seeing what the ones before it produced.
+ *
+ * Order is meaningful rather than incidental: a resolver that mints a cookie
+ * may only do so once consent has been read, so the resolver reading consent
+ * has to come first. Put the other way round, the minter sees no consent, mints
+ * nothing, and the app collects nothing — silently, which is why this threads
+ * state through instead of merging independent results.
+ *
+ * A later resolver wins a key it sets, so a minter's freshly created id
+ * replaces the absent one the cookie reader could not find.
+ */
+export const composeAnalyticsIdentity = (...resolvers) => {
+    return (wire, initial) => {
+        let resolved = initial ?? {};
+        for (const resolver of resolvers) {
+            const next = resolver(wire, resolved);
+            if (!next)
+                continue;
+            resolved = {
+                ...resolved,
+                ...next,
+                ...(next.vendorIds === undefined && resolved.vendorIds === undefined
+                    ? {}
+                    : { vendorIds: { ...resolved.vendorIds, ...next.vendorIds } }),
+                ...(next.consent === undefined && resolved.consent === undefined
+                    ? {}
+                    : { consent: { ...resolved.consent, ...next.consent } }),
+            };
+        }
+        return Object.keys(resolved).length === 0 ? undefined : resolved;
+    };
+};

package/dist/analytics/cookie-analytics-identity.d.ts

@@ -0,0 +1,24 @@
+import type { AnalyticsIdentityResolver } from './analytics.types.js';
+export interface CookieAnalyticsIdentityOptions {
+    /** Identity key to read it from, e.g. `{ gaClientId: '_ga' }`. */
+    vendorIds?: Record<string, string>;
+    /**
+     * Consent purpose to the cookie that grants it. The purpose is true only when
+     * the cookie is present and is not a recognised denial (`'0'`, `'false'`,
+     * `'denied'`), so a consent tool that writes a refusal rather than deleting
+     * the cookie is read as a refusal.
+     */
+    consent?: Record<string, string>;
+}
+/**
+ * Reads the browser-originated half of the identity off first-party cookies.
+ *
+ * Covers the common case only. A consent tool that packs every purpose into one
+ * encoded blob needs its own resolver — which is why the resolver is a function
+ * and this is a helper rather than the mechanism.
+ *
+ * Resolves nothing off an HTTP wire, which is correct: a cron task and a queue
+ * worker have no browser behind them, so any vendor id they produced would be
+ * invented.
+ */
+export declare const cookieAnalyticsIdentity: (options: CookieAnalyticsIdentityOptions) => AnalyticsIdentityResolver;

package/dist/analytics/cookie-analytics-identity.js

@@ -0,0 +1,37 @@
+const DENIALS = new Set(['0', 'false', 'denied', 'deny', 'no']);
+/**
+ * Reads the browser-originated half of the identity off first-party cookies.
+ *
+ * Covers the common case only. A consent tool that packs every purpose into one
+ * encoded blob needs its own resolver — which is why the resolver is a function
+ * and this is a helper rather than the mechanism.
+ *
+ * Resolves nothing off an HTTP wire, which is correct: a cron task and a queue
+ * worker have no browser behind them, so any vendor id they produced would be
+ * invented.
+ */
+export const cookieAnalyticsIdentity = (options) => {
+    return (wire) => {
+        const request = wire.http?.request;
+        if (!request)
+            return undefined;
+        const vendorIds = {};
+        for (const [key, cookieName] of Object.entries(options.vendorIds ?? {})) {
+            const value = request.cookie(cookieName);
+            if (value) {
+                vendorIds[key] = value;
+            }
+        }
+        const consent = {};
+        for (const [purpose, cookieName] of Object.entries(options.consent ?? {})) {
+            const value = request.cookie(cookieName);
+            if (value !== null) {
+                consent[purpose] = !DENIALS.has(value.toLowerCase());
+            }
+        }
+        return {
+            ...(Object.keys(vendorIds).length === 0 ? {} : { vendorIds }),
+            ...(Object.keys(consent).length === 0 ? {} : { consent }),
+        };
+    };
+};

package/dist/analytics/define-analytics-events.d.ts

@@ -0,0 +1,22 @@
+import type { StandardSchemaV1 } from '@standard-schema/spec';
+/**
+ * The schema for one event's props. The generated ingest rebuilds each member
+ * of the union as `z.object(schema.shape)` so it can attach the event name, so
+ * a schema with no `shape` — a union, a primitive, a schema from a library
+ * that does not expose one — is not something an event can be declared with,
+ * and saying so here fails at the declaration rather than in generated code.
+ */
+export type AnalyticsEventPropsSchema = StandardSchemaV1 & {
+    shape: Record<string, unknown>;
+};
+/** Events keyed by name; each value is the schema for that event's props. */
+export type AnalyticsEventDefinitions = Record<string, AnalyticsEventPropsSchema>;
+/**
+ * Declare what a module can measure. Call it as often as suits the project; the
+ * CLI unions every declaration into the ingest schema.
+ *
+ * It must stay an exported const — the schema pipeline reads the value by name.
+ * It registers nothing at runtime: where events go is an `AnalyticsService` on
+ * singleton services.
+ */
+export declare const defineAnalyticsEvents: <const Events extends AnalyticsEventDefinitions>(events: Events) => Events;

package/dist/analytics/define-analytics-events.js

@@ -0,0 +1,9 @@
+/**
+ * Declare what a module can measure. Call it as often as suits the project; the
+ * CLI unions every declaration into the ingest schema.
+ *
+ * It must stay an exported const — the schema pipeline reads the value by name.
+ * It registers nothing at runtime: where events go is an `AnalyticsService` on
+ * singleton services.
+ */
+export const defineAnalyticsEvents = (events) => events;

package/dist/analytics/fan-out-analytics.d.ts

@@ -0,0 +1,15 @@
+import type { AnalyticsService, AnalyticsSink } from './analytics.types.js';
+/**
+ * One `AnalyticsService` over several destinations.
+ *
+ * A composite rather than a change to the interface, so a single-destination
+ * app never meets it and a sink is the same class whether it runs alone or
+ * beside three others.
+ *
+ * Settled, not awaited in sequence: `flush()` runs inside the invocation, so a
+ * vendor that is slow must not add its latency to the request and a vendor that
+ * is down must not cost the others their events. A destination that throws is
+ * reported by the caller's existing flush guard, which already treats analytics
+ * as best-effort.
+ */
+export declare const fanOutAnalytics: (sinks: ReadonlyArray<AnalyticsSink | AnalyticsService>) => AnalyticsService;

package/dist/analytics/fan-out-analytics.js

@@ -0,0 +1,36 @@
+/**
+ * One `AnalyticsService` over several destinations.
+ *
+ * A composite rather than a change to the interface, so a single-destination
+ * app never meets it and a sink is the same class whether it runs alone or
+ * beside three others.
+ *
+ * Settled, not awaited in sequence: `flush()` runs inside the invocation, so a
+ * vendor that is slow must not add its latency to the request and a vendor that
+ * is down must not cost the others their events. A destination that throws is
+ * reported by the caller's existing flush guard, which already treats analytics
+ * as best-effort.
+ */
+export const fanOutAnalytics = (sinks) => {
+    const resolved = sinks.map((sink) => 'service' in sink ? sink : { service: sink });
+    return {
+        async write(batch) {
+            if (batch.length === 0)
+                return;
+            const results = await Promise.allSettled(
+            // `accepts` is app code and runs inside this map. Thrown
+            // synchronously it would escape before `allSettled` was ever called,
+            // and every destination after it in the list would lose the batch.
+            resolved.map(async ({ service, accepts }) => {
+                const records = accepts ? batch.filter(accepts) : batch;
+                if (records.length === 0)
+                    return;
+                await service.write(records);
+            }));
+            const failures = results.filter((result) => result.status === 'rejected');
+            if (failures.length > 0) {
+                throw new AggregateError(failures.map((failure) => failure.reason), `${failures.length} of ${resolved.length} analytics destinations failed`);
+            }
+        },
+    };
+};

package/dist/analytics/index.d.ts

@@ -0,0 +1,13 @@
+export type { AnalyticsClientContext, AnalyticsEventBase, AnalyticsEventMeta, AnalyticsEventsMeta, AnalyticsEventInput, AnalyticsIdentity, AnalyticsLog, AnalyticsIdentityResolver, AnalyticsRecord, AnalyticsService, AnalyticsSink, } from './analytics.types.js';
+export { createInvocationAnalytics, flattenAnalyticsEvent, } from './analytics.js';
+export { LoggerAnalyticsService } from './logger-analytics-service.js';
+export { defineAnalyticsEvents } from './define-analytics-events.js';
+export type { AnalyticsEventDefinitions, AnalyticsEventPropsSchema, } from './define-analytics-events.js';
+export { fanOutAnalytics } from './fan-out-analytics.js';
+export { cookieAnalyticsIdentity } from './cookie-analytics-identity.js';
+export type { CookieAnalyticsIdentityOptions } from './cookie-analytics-identity.js';
+export { mintCookie, randomDigits } from './mint-cookie.js';
+export type { MintCookieOptions } from './mint-cookie.js';
+export { composeAnalyticsIdentity } from './compose-analytics-identity.js';
+export { anonymousAnalyticsIdentity } from './anonymous-analytics-identity.js';
+export type { AnonymousAnalyticsIdentityOptions } from './anonymous-analytics-identity.js';

package/dist/analytics/index.js

@@ -0,0 +1,8 @@
+export { createInvocationAnalytics, flattenAnalyticsEvent, } from './analytics.js';
+export { LoggerAnalyticsService } from './logger-analytics-service.js';
+export { defineAnalyticsEvents } from './define-analytics-events.js';
+export { fanOutAnalytics } from './fan-out-analytics.js';
+export { cookieAnalyticsIdentity } from './cookie-analytics-identity.js';
+export { mintCookie, randomDigits } from './mint-cookie.js';
+export { composeAnalyticsIdentity } from './compose-analytics-identity.js';
+export { anonymousAnalyticsIdentity } from './anonymous-analytics-identity.js';

package/dist/analytics/logger-analytics-service.d.ts

@@ -0,0 +1,14 @@
+import type { Logger } from '../services/logger.js';
+import type { AnalyticsRecord, AnalyticsService } from './analytics.types.js';
+/**
+ * What an app gets before it has chosen a store. There is deliberately no noop:
+ * a validated wire with nowhere for the events to go is indistinguishable from
+ * a broken one.
+ *
+ * At `debug` so attaching a real store does not report every event twice.
+ */
+export declare class LoggerAnalyticsService implements AnalyticsService {
+    private readonly logger;
+    constructor(logger: Logger);
+    write(batch: AnalyticsRecord[]): Promise<void>;
+}

package/dist/analytics/logger-analytics-service.js

@@ -0,0 +1,23 @@
+/**
+ * What an app gets before it has chosen a store. There is deliberately no noop:
+ * a validated wire with nowhere for the events to go is indistinguishable from
+ * a broken one.
+ *
+ * At `debug` so attaching a real store does not report every event twice.
+ */
+export class LoggerAnalyticsService {
+    logger;
+    constructor(logger) {
+        this.logger = logger;
+    }
+    async write(batch) {
+        for (const event of batch) {
+            this.logger.debug(`analytics: ${event.name}`, {
+                ...event.props,
+                userId: event.userIdentity.userId,
+                source: event.source,
+                ...(event.at === undefined ? {} : { at: event.at }),
+            });
+        }
+    }
+}

package/dist/analytics/mint-cookie.d.ts

@@ -0,0 +1,44 @@
+import type { SerializeOptions } from 'cookie';
+import type { CoreUserSession, PikkuWire } from '../types/core.types.js';
+type AnyWire = PikkuWire<any, any, any, CoreUserSession>;
+export interface MintCookieOptions {
+    /** Cookie attributes. Long-lived and first-party is the usual shape. */
+    cookie: SerializeOptions;
+    /**
+     * Purposes that must all be `true` before anything is written. Writing the
+     * cookie IS the act consent governs, so a minter that runs before the banner
+     * is answered has already done the thing the send gate was meant to prevent.
+     */
+    requires?: string[];
+    consent?: Record<string, boolean>;
+    /**
+     * Replace the cookie already on the device rather than returning it.
+     *
+     * For the case where the request itself carries something newer than what is
+     * stored — Meta's `_fbc` derives from the `fbclid` on the current URL, and
+     * keeping an older click would attribute the conversion to the wrong ad.
+     */
+    overwrite?: boolean;
+}
+/**
+ * Reads a first-party cookie, creating and setting it when absent.
+ *
+ * This is how an app tracks a visitor with no vendor SDK on the page: the
+ * identifiers GA4 and Meta key on are ordinary first-party cookies in a
+ * documented format, and nothing requires a browser script to be the one that
+ * writes them. It is the mechanism behind server-side tagging, and the reason
+ * pikku can offer it as a wired service rather than a second container to run.
+ *
+ * Minted once per wire, not once per call. The resolver runs for every event,
+ * and a second mint within one request would hand the same visitor two
+ * identities — which reads downstream as two people rather than as a bug.
+ *
+ * Writes nothing on a wire with no HTTP response, and nothing once the response
+ * has been sent; a cron task and a queue worker have no browser to store it,
+ * and a stream's headers are long gone. Both return undefined rather than
+ * pretending.
+ */
+export declare const mintCookie: (wire: AnyWire, name: string, options: MintCookieOptions, mint: () => string) => string | undefined;
+/** Cryptographically random digits, the shape both vendor formats use. */
+export declare const randomDigits: (length: number) => string;
+export {};

package/dist/analytics/mint-cookie.js

@@ -0,0 +1,55 @@
+const minted = new WeakMap();
+const permitted = (requires, consent) => {
+    if (!requires || requires.length === 0)
+        return true;
+    return requires.every((purpose) => consent?.[purpose] === true);
+};
+/**
+ * Reads a first-party cookie, creating and setting it when absent.
+ *
+ * This is how an app tracks a visitor with no vendor SDK on the page: the
+ * identifiers GA4 and Meta key on are ordinary first-party cookies in a
+ * documented format, and nothing requires a browser script to be the one that
+ * writes them. It is the mechanism behind server-side tagging, and the reason
+ * pikku can offer it as a wired service rather than a second container to run.
+ *
+ * Minted once per wire, not once per call. The resolver runs for every event,
+ * and a second mint within one request would hand the same visitor two
+ * identities — which reads downstream as two people rather than as a bug.
+ *
+ * Writes nothing on a wire with no HTTP response, and nothing once the response
+ * has been sent; a cron task and a queue worker have no browser to store it,
+ * and a stream's headers are long gone. Both return undefined rather than
+ * pretending.
+ */
+export const mintCookie = (wire, name, options, mint) => {
+    const existing = options.overwrite
+        ? null
+        : wire.http?.request?.cookie(name);
+    if (existing)
+        return existing;
+    const cache = minted.get(wire) ?? new Map();
+    const already = cache.get(name);
+    if (already)
+        return already;
+    const response = wire.http?.response;
+    if (!response)
+        return undefined;
+    if (!permitted(options.requires, options.consent))
+        return undefined;
+    const value = mint();
+    response.cookie(name, value, options.cookie);
+    cache.set(name, value);
+    minted.set(wire, cache);
+    return value;
+};
+/** Cryptographically random digits, the shape both vendor formats use. */
+export const randomDigits = (length) => {
+    const bytes = new Uint8Array(length);
+    crypto.getRandomValues(bytes);
+    let digits = '';
+    for (const byte of bytes) {
+        digits += String(byte % 10);
+    }
+    return digits;
+};

package/dist/dev/hot-reload.d.ts

@@ -3,7 +3,6 @@ export { reloadGeneratedMeta, reconcileAddonRegistry } from './reload-meta.js';
 interface PikkuDevReloaderOptions {
     srcDirectories: string[];
     logger: Logger;
-    pikkuDir?: string;
 }
 export interface PikkuDevReloaderHandle {
     close: () => void;

package/dist/dev/hot-reload.js

@@ -1,5 +1,4 @@
 import { watch } from 'node:fs';
-import { stat } from 'node:fs/promises';
 import { basename, join, resolve, relative } from 'node:path';
 import { pikkuState } from '../pikku-state.js';
 import { clearMiddlewareCache } from '../middleware-runner.js';
@@ -14,24 +13,6 @@ const isFunctionConfig = (value) => {
         'func' in value &&
         typeof value.func === 'function');
 };
-const findCompiledFile = async (tsFile, srcDir, pikkuDir) => {
-    const rel = relative(srcDir, tsFile).replace(/\.ts$/, '.js');
-    const candidates = [
-        join(pikkuDir, 'dist', rel),
-        join(srcDir, rel),
-        tsFile.replace(/\.ts$/, '.js'),
-    ];
-    for (const candidate of candidates) {
-        try {
-            await stat(candidate);
-            return candidate;
-        }
-        catch {
-            // not found, try next
-        }
-    }
-    return null;
-};
 const isWatchedTsFile = (filename) => {
     return (filename.endsWith('.ts') &&
         !filename.endsWith('.test.ts') &&
@@ -55,9 +36,8 @@ const reloadFailureReason = (error) => {
     return `  ${error.stack ?? error.message}`;
 };
 export async function pikkuDevReloader(options) {
-    const { srcDirectories, logger, pikkuDir = '.pikku' } = options;
+    const { srcDirectories, logger } = options;
     const absSrcDirs = srcDirectories.map((d) => resolve(d));
-    const absPikkuDir = resolve(pikkuDir);
     const watchers = [];
     const functionsMap = pikkuState(null, 'function', 'functions');
     const moduleRunner = createModuleRunner();
@@ -68,15 +48,14 @@ export async function pikkuDevReloader(options) {
         const srcDir = absSrcDirs.find((d) => changedTsFile.startsWith(d));
         if (!srcDir)
             return;
-        const compiledFile = await findCompiledFile(changedTsFile, srcDir, absPikkuDir);
-        const importPath = compiledFile ?? changedTsFile;
-        const result = await moduleRunner.run(importPath);
+        // knowledge: decisions/internals/hot-reload-reads-the-changed-source-never-a-compiled-copy.md
+        const result = await moduleRunner.run(changedTsFile);
         if (!result.ok) {
             // Keeping the old code leaves the process disagreeing with the file on
             // disk, and the only symptom is stale output from a function that looks
             // correct in the editor — so the reason has to be printed here, where it
             // is still known, rather than left for the developer to reconstruct.
-            logger.error(`Failed to import: ${relative(process.cwd(), importPath)} (keeping old code)\n` +
+            logger.error(`Failed to import: ${relative(process.cwd(), changedTsFile)} (keeping old code)\n` +
                 reloadFailureReason(result.error));
             return;
         }

package/dist/dev/module-runner.js

@@ -1,6 +1,6 @@
-import { readFile } from 'node:fs/promises';
+import { readFileSync, statSync } from 'node:fs';
 import { createRequire } from 'node:module';
-import { dirname, resolve } from 'node:path';
+import { dirname, isAbsolute, join, resolve, sep } from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { compileFunction } from 'node:vm';
 let transformSync;
@@ -18,7 +18,78 @@ const loadTransform = async () => {
  *  is correct, and no amount of re-reading it will reveal that the reloader —
  *  not the file — is what cannot cope. */
 export const isTopLevelAwaitLimitation = (error) => /top-level await/i.test(error.message);
+const TYPESCRIPT_FILE = /\.(m|c)?tsx?$/;
+const isFile = (path) => {
+    try {
+        return statSync(path).isFile();
+    }
+    catch {
+        return false;
+    }
+};
+/** Where a relative specifier's TypeScript source lives, for the specifiers a
+ *  plain `require` cannot resolve. A TS project writes `./sibling.js` for a file
+ *  that only exists as `./sibling.ts`, and a reloaded module is the source, so
+ *  every one of its relative imports arrives in that unresolvable form. */
+const findTypeScriptSource = (specifier, importerDir) => {
+    if (!specifier.startsWith('.') && !isAbsolute(specifier))
+        return undefined;
+    const base = resolve(importerDir, specifier);
+    const withoutJs = base.replace(/\.(m|c)?js$/, '');
+    const candidates = [
+        `${withoutJs}.ts`,
+        `${withoutJs}.tsx`,
+        `${withoutJs}.mts`,
+        `${withoutJs}.cts`,
+        join(base, 'index.ts'),
+        join(base, 'index.tsx'),
+    ];
+    return candidates.find(isFile);
+};
+const isProjectTypeScript = (path) => TYPESCRIPT_FILE.test(path) && !path.includes(`${sep}node_modules${sep}`);
+/** JSX is a syntax esbuild only parses when asked, so a `.tsx` helper handed to
+ *  the `ts` loader fails to compile and the file importing it keeps its old
+ *  code. */
+const loaderFor = (path) => {
+    if (path.endsWith('.tsx'))
+        return 'tsx';
+    if (TYPESCRIPT_FILE.test(path))
+        return 'ts';
+    if (path.endsWith('.jsx'))
+        return 'jsx';
+    return 'js';
+};
+const evaluateModule = (absPath, cache) => {
+    const cached = cache.get(absPath);
+    if (cached)
+        return cached;
+    const source = readFileSync(absPath, 'utf-8');
+    const { code } = transformSync(source, {
+        loader: loaderFor(absPath),
+        format: 'cjs',
+        sourcefile: absPath,
+    });
+    const fn = compileFunction(code, ['require', 'exports', 'module', '__filename', '__dirname'], { filename: absPath });
+    const moduleObj = { exports: {} };
+    // Seeded before evaluation so an import cycle terminates the way CJS's own
+    // cache makes it terminate, and overwritten after because esbuild's `cjs`
+    // emit assigns a fresh `module.exports` on the way out.
+    cache.set(absPath, moduleObj.exports);
+    fn(createRequireForFile(absPath, cache), moduleObj.exports, moduleObj, absPath, dirname(absPath));
+    cache.set(absPath, moduleObj.exports);
+    return moduleObj.exports;
+};
 /** The `require` a reloaded module is run with.
+ *
+ *  Resolution goes through the host first, so every package binds to the
+ *  instance the rest of the process holds and a user file's `wire*` side
+ *  effect mutates live state rather than a private copy.
+ *
+ *  A resolved TypeScript file outside `node_modules` is the project's own
+ *  source, and is compiled here instead of handed back to the host: both hosts
+ *  cache what they load, so a helper edited alongside the function importing it
+ *  would otherwise keep answering with the version loaded at startup — the same
+ *  stale-code-under-a-successful-reload the reloader exists to avoid.
  *
  *  On Bun, `createRequire`'s referrer stops being honoured somewhere in a
  *  long-running process: the same relative specifier that resolves in a fresh
@@ -27,47 +98,55 @@ export const isTopLevelAwaitLimitation = (error) => /top-level await/i.test(erro
  *  is left serving the previous code from an edit that looked applied. Bun's
  *  own resolver still answers correctly when handed the importer's directory
  *  outright, so the specifier is resolved to an absolute path first and the
- *  referrer never has to survive the trip. Anything Bun's resolver declines —
- *  builtins among them — falls through to `require` unchanged.
+ *  referrer never has to survive the trip.
+ *
+ *  What neither host resolves is a relative `./sibling.js` whose only file on
+ *  disk is `./sibling.ts` — node's `require` has no `.js → .ts` rewrite, and
+ *  the reloader hands it source. Those, and only those, are compiled here.
  */
-const createRequireForFile = (absPath) => {
+const createRequireForFile = (absPath, cache) => {
     const base = createRequire(pathToFileURL(absPath));
     const bun = globalThis.Bun;
-    if (!bun)
-        return base;
     const importerDir = dirname(absPath);
-    const resolveThroughBun = (specifier) => {
+    const resolveThroughHost = (specifier) => {
+        if (bun) {
+            try {
+                return bun.resolveSync(specifier, importerDir);
+            }
+            catch {
+                return undefined;
+            }
+        }
         try {
-            return bun.resolveSync(specifier, importerDir);
+            return base.resolve(specifier);
         }
         catch {
-            return specifier;
+            return undefined;
         }
     };
     // Only resolution is delegated; the require itself stays outside the guard so
     // a module that throws while evaluating reports its own error rather than
     // being retried under a second specifier.
-    const bunRequire = ((specifier) => base(resolveThroughBun(specifier)));
-    return Object.assign(bunRequire, base);
+    const loadingRequire = ((specifier) => {
+        const resolved = resolveThroughHost(specifier) ??
+            findTypeScriptSource(specifier, importerDir);
+        if (!resolved)
+            return base(specifier);
+        if (isProjectTypeScript(resolved))
+            return evaluateModule(resolved, cache);
+        return base(resolved);
+    });
+    return Object.assign(loadingRequire, base);
 };
 export const createModuleRunner = () => {
     const registry = new Map();
     const run = async (filePath) => {
         const absPath = resolve(filePath);
         try {
-            const transform = await loadTransform();
-            const source = await readFile(absPath, 'utf-8');
-            const { code } = transform(source, {
-                loader: absPath.endsWith('.ts') ? 'ts' : 'js',
-                format: 'cjs',
-                sourcefile: absPath,
-            });
-            const fn = compileFunction(code, ['require', 'exports', 'module', '__filename', '__dirname'], { filename: absPath });
-            const require = createRequireForFile(absPath);
-            const moduleObj = { exports: {} };
-            fn(require, moduleObj.exports, moduleObj, absPath, dirname(absPath));
-            registry.set(absPath, moduleObj.exports);
-            return { ok: true, exports: moduleObj.exports };
+            await loadTransform();
+            const exports = evaluateModule(absPath, new Map());
+            registry.set(absPath, exports);
+            return { ok: true, exports };
         }
         catch (thrown) {
             // A bad edit, or the one known limitation: a file using top-level

package/dist/errors/errors.d.ts

@@ -35,6 +35,13 @@ export declare class MissingScopeError extends PikkuError {
     };
     constructor(scope: string);
 }
+export declare class FeatureUnavailableError extends PikkuError {
+    payload: {
+        error: 'feature_unavailable';
+        feature: string;
+    };
+    constructor(feature: string);
+}
 export declare class ReadonlySessionError extends PikkuError {
 }
 export declare class InvalidOriginError extends PikkuError {

package/dist/errors/errors.js

@@ -87,6 +87,23 @@ addError(MissingScopeError, {
     status: 403,
     message: 'The session does not hold a scope required by this function.',
 });
+export class FeatureUnavailableError extends PikkuError {
+    payload;
+    constructor(feature) {
+        super(`Feature is currently unavailable: ${feature}`);
+        this.payload = {
+            error: 'feature_unavailable',
+            feature,
+        };
+    }
+}
+// 503 and not 403: a killed feature is a server-side, temporary, not-your-fault
+// condition, and it should be retryable and monitorable as one. A 403 here
+// would page the wrong team and tell the caller to fix something they cannot.
+addError(FeatureUnavailableError, {
+    status: 503,
+    message: 'This feature is switched off.',
+});
 export class ReadonlySessionError extends PikkuError {
 }
 addError(ReadonlySessionError, {

package/dist/function/function-meta.types.d.ts

@@ -25,6 +25,8 @@ export type FunctionRuntimeMeta = {
     outputSchemaName: string | null;
     /** Scopes the session must hold to run this function. All are required (AND). */
     scopes?: string[];
+    /** The feature this function belongs to. Checked for availability only. */
+    featureFlag?: string;
     expose?: boolean;
     /**
      * A sessionless function's own `auth: true`. `sessionless` carries the