@pikku/cli 0.12.145 → 0.12.151

package/dist/src/functions/wirings/analytics/serialize-analytics.js

@@ -0,0 +1,141 @@
+/**
+ * The declarations flattened to one entry per event, which is how every reader
+ * wants them: an event name belongs to exactly one declaration — the inspector
+ * refuses a second — so keying by name loses nothing and spares each caller the
+ * walk.
+ */
+export const buildAnalyticsEventsMeta = (declarations) => {
+    const meta = {};
+    for (const declaration of declarations) {
+        for (const name of declaration.events) {
+            const props = declaration.props?.[name];
+            meta[name] = {
+                name,
+                file: declaration.file,
+                variable: declaration.variable,
+                ...(props ? { props } : {}),
+            };
+        }
+    }
+    return meta;
+};
+/** So two modules can both export `analyticsEvents` without colliding. */
+const alias = (index) => `events${index}`;
+/**
+ * Generate the ingest wire and its schemas. No middleware is emitted: an origin
+ * lock is not a security boundary and rejects every native client, so which
+ * guard belongs here is the project's call.
+ */
+export const serializeAnalytics = (leaf, declarations, globalHTTPPrefix = '') => {
+    const imports = declarations
+        .map((declaration, index) => `import { ${declaration.variable} as ${alias(index)} } from '${declaration.specifier}'`)
+        .join('\n');
+    const members = declarations
+        .flatMap((declaration, index) => declaration.events.map((event) => `  z\n    .object(${alias(index)}['${event}'].shape)\n    .extend({ name: z.literal('${event}') }),`))
+        .join('\n');
+    const schemas = `/**
+ * Auto-generated analytics ingest schemas
+ * Do not edit manually - regenerate with 'npx pikku'
+ */
+import { z } from 'zod'
+${imports}
+
+/**
+ * The name is the declaration's key, reattached here as the discriminator —
+ * last, so a declaration that happens to carry a 'name' prop of its own
+ * cannot overwrite the literal the union discriminates on.
+ */
+export const AnalyticsEventSchema = z.discriminatedUnion('name', [
+${members}
+])
+
+export type AnalyticsEvent = z.infer<typeof AnalyticsEventSchema>
+
+/**
+ * Batched because a browser sends these on unload, where one request survives
+ * and several may not. Capped so an unauthenticated request cannot ask for
+ * unbounded work.
+ */
+export const AnalyticsIngest = z.object({
+  events: z
+    .array(
+      z.object({
+        at: z.number().int().optional(),
+        event: AnalyticsEventSchema,
+      })
+    )
+    .min(1)
+    .max(50),
+})
+
+export const AnalyticsIngestOutput = z.object({
+  accepted: z.number(),
+})
+`;
+    const functions = `/**
+ * Auto-generated analytics ingest
+ * Do not edit manually - regenerate with 'npx pikku'
+ */
+import { pikkuSessionlessFunc } from '${leaf('function')}'
+import { wireHTTP } from '${leaf('http')}'
+import {
+  AnalyticsIngest,
+  AnalyticsIngestOutput,
+} from './analytics.schemas.gen.js'
+
+export type { AnalyticsEvent } from './analytics.schemas.gen.js'
+
+/**
+ * Re-exported so an app reaches the whole analytics surface through one
+ * specifier. Where events go is wired next to where they are declared, and
+ * making that import '@pikku/core/analytics' while the event type comes from
+ * '#pikku/analytics' splits one concern across two names.
+ */
+export {
+  fanOutAnalytics,
+  cookieAnalyticsIdentity,
+  composeAnalyticsIdentity,
+  anonymousAnalyticsIdentity,
+  mintCookie,
+  randomDigits,
+  LoggerAnalyticsService,
+} from '@pikku/core/analytics'
+export type {
+  AnalyticsIdentity,
+  AnalyticsIdentityResolver,
+  AnalyticsRecord,
+  AnalyticsService,
+  AnalyticsSink,
+} from '@pikku/core/analytics'
+
+/**
+ * Unauthenticated by necessity: anonymous visitors are most of what this
+ * measures. Identity is stamped from the session and never read from the body,
+ * so no caller can attribute events to someone else. An anonymous visitor is
+ * identified only where the app wired a resolver that mints one — nothing here
+ * stores anything on a device by itself.
+ */
+export const analyticsIngest = pikkuSessionlessFunc({
+  auth: false,
+  tags: ['analytics'],
+  description: 'Records product-analytics events from a client.',
+  input: AnalyticsIngest,
+  output: AnalyticsIngestOutput,
+  func: async ({ analytics }, { events }) => {
+    for (const { at, event } of events) {
+      await analytics!.record(event, { at })
+    }
+    return { accepted: events.length }
+  },
+})
+
+wireHTTP({
+  route: '${globalHTTPPrefix}/analytics',
+  method: 'post',
+  auth: false,
+  tags: ['analytics'],
+  func: analyticsIngest,
+})
+`;
+    return { schemas, functions };
+};

package/dist/src/functions/wirings/auth/pikku-command-auth.d.ts

@@ -1,7 +1,7 @@
 export declare const pikkuAuth: import("#pikku/function").PikkuFunctionConfig<{
     bootstrap?: boolean;
-}, void, "rpc" | "session", import("#pikku/function").PikkuFunctionSessionless<{
+}, void, "rpc" | "session", import("#pikku/function").PikkuFunction<{
     bootstrap?: boolean;
-}, void, "rpc" | "session", import("#pikku/function").WiredServices, unknown> | import("#pikku/function").PikkuFunction<{
+}, void, "rpc" | "session", import("#pikku/function").WiredServices> | import("#pikku/function").PikkuFunctionSessionless<{
     bootstrap?: boolean;
-}, void, "rpc" | "session", import("#pikku/function").WiredServices>, undefined, undefined>;
+}, void, "rpc" | "session", import("#pikku/function").WiredServices, unknown>, undefined, undefined>;

package/dist/src/functions/wirings/auth/pikku-command-auth.js

@@ -32,7 +32,7 @@ export const pikkuAuth = pikkuSessionlessFunc({
         // has no OAuth providers — still generates its /auth/* wiring.
         if (!state.auth.definition)
             return;
-        const { wiring, secrets, middleware } = serializeAuthGen(state.auth.definition, state.auth.providers, authFile, (name) => getLeafImportPath(authFile, name, config), packageMappings ?? {}, state.auth.hasUserSessionMiddleware ?? false, Boolean(config.scaffold?.console));
+        const { wiring, secrets, middleware } = serializeAuthGen(state.auth.definition, state.auth.providers, authFile, (name) => getLeafImportPath(authFile, name, config), packageMappings ?? {}, Boolean(config.scaffold?.console));
         // The secrets file sits alongside authFile so re-inspection rediscovers it.
         // It is kept separate from the wiring file because the CLI forbids Zod
         // schemas and HTTP wiring (wireHTTPRoutes) in the same file (PKU490).
@@ -40,12 +40,8 @@ export const pikkuAuth = pikkuSessionlessFunc({
         await writeFileInDir(logger, authFile, wiring);
         await writeFileInDir(logger, secretsFile, secrets);
         // Stateless split: session middleware in its own file (see serializeAuthGen).
-        // Skip it when the project registers its own betterAuthStatelessSession — the
-        // generated default-map one would run first and pre-empt the user's custom
-        // mapSession (pikkujs/pikku#754). Remove a stale file so it can't linger and
-        // double-register.
         const middlewareFile = join(dirname(authFile), 'auth-middleware.gen.ts');
-        if (middleware && !state.auth.userStatelessSession) {
+        if (middleware) {
             await writeFileInDir(logger, middlewareFile, middleware);
         }
         else if (existsSync(middlewareFile)) {

package/dist/src/functions/wirings/auth/serialize-auth-gen.d.ts

@@ -18,4 +18,4 @@ export interface AuthGenOutput {
      * `session.cookieCache` is enabled (stateless path); undefined otherwise. */
     middleware?: string;
 }
-export declare const serializeAuthGen: (definition: AuthDefinition, providers: string[], authFile: string, leaf: (name: string) => string, packageMappings: Record<string, string>, hasUserSessionMiddleware?: boolean, includeConsoleToken?: boolean) => AuthGenOutput;
+export declare const serializeAuthGen: (definition: AuthDefinition, providers: string[], authFile: string, leaf: (name: string) => string, packageMappings: Record<string, string>, includeConsoleToken?: boolean) => AuthGenOutput;

package/dist/src/functions/wirings/auth/serialize-auth-gen.js

@@ -36,12 +36,7 @@ function variableSchemaName(name, field) {
 // External consoles (served from another origin) cannot carry the session
 // cookie, so they authenticate with 'Authorization: Bearer <PIKKU_CONSOLE_TOKEN>'.
 // The expected token resolves through the secrets service per request and the
-// middleware is a no-op while the secret is unset. Emitted alongside the session
-// middleware in one addGlobalMiddleware call. This used to be an
-// addHTTPMiddleware('*') call and had to be a single one, because the inspector
-// keys route-middleware groups by pattern and a second '*' registration would
-// silently displace it; global middleware is an append-only list, so that
-// hazard is gone.
+// middleware is a no-op while the secret is unset.
 //
 // The session carries the two scope roots the console's functions gate
 // themselves on. Without them this token authenticates but authorizes nothing:
@@ -65,7 +60,7 @@ const consoleTokenMiddlewareLines = () => [
     `    },`,
     `  }),`,
 ];
-export const serializeAuthGen = (definition, providers, authFile, leaf, packageMappings, hasUserSessionMiddleware = false, includeConsoleToken = false) => {
+export const serializeAuthGen = (definition, providers, authFile, leaf, packageMappings, includeConsoleToken = false) => {
     const known = providers.filter((p) => p in PROVIDER_REGISTRY);
     const basePath = definition.basePath;
     // Side-effect import of the user's auth file so `pikkuBetterAuth` runs and
@@ -143,25 +138,21 @@ export const serializeAuthGen = (definition, providers, authFile, leaf, packageM
     // file's auth.wiring import (the full better-auth server) isn't dragged into
     // every unit — only the auth unit bundles it.
     const stateless = definition.cookieCache;
-    // Emit the generated global betterAuthSession() only when it's the stateful
-    // path AND the user hasn't registered their own global betterAuthSession(...).
-    // A user registration means they want to customize it (mapSession/impersonation/
-    // apiKey); the generated default-map one would run first and pre-empt theirs via
-    // the `if (session) next()` short-circuit, so we step aside. Mirrors the
-    // stateless skip (state.auth.userStatelessSession, pikkujs/pikku#754).
-    const emitStatefulSession = !stateless && !hasUserSessionMiddleware;
+    // The generated session middleware is always emitted, at `lowest` priority. An
+    // app's own registration defaults to `medium`, so it resolves the session
+    // first and this one short-circuits on `if (session) next()`. That is what
+    // pikkujs/pikku#754 needed: the CLI used to detect a user registration and
+    // skip generating at all, which silently dropped anything emitted alongside.
+    const emitStatefulSession = !stateless;
     const wiring = [
         '// AUTO-GENERATED by pikku CLI — do not edit',
         '',
         emitStatefulSession
-            ? `import { pikkuSessionlessFunc } from '${leaf('function')}'\nimport { wireHTTPRoutes } from '${leaf('http')}'\nimport { addGlobalMiddleware } from '@pikku/core/middleware'`
+            ? `import { pikkuSessionlessFunc } from '${leaf('function')}'\nimport { wireHTTPRoutes } from '${leaf('http')}'\nimport { addGlobalMiddleware${includeConsoleToken ? ', authBearer' : ''} } from '@pikku/core/middleware'`
             : `import { pikkuSessionlessFunc } from '${leaf('function')}'\nimport { wireHTTPRoutes } from '${leaf('http')}'`,
         emitStatefulSession
             ? `import { createAuthHandler, betterAuthSession } from '@pikku/better-auth'`
             : `import { createAuthHandler } from '@pikku/better-auth'`,
-        ...(emitStatefulSession && includeConsoleToken
-            ? [`import { authBearer } from '@pikku/core/middleware'`]
-            : []),
         `import '${configImportPath}'`,
         '',
         // createAuthHandler is called once at module load; the exported handler is a
@@ -179,12 +170,7 @@ export const serializeAuthGen = (definition, providers, authFile, leaf, packageM
     if (emitStatefulSession) {
         // Stateful: betterAuthSession calls services.auth(), so it stays here with
         // the auth.wiring import.
-        if (includeConsoleToken) {
-            wiring.push(`addGlobalMiddleware([`, `  betterAuthSession(),`, ...consoleTokenMiddlewareLines(), `])`, '');
-        }
-        else {
-            wiring.push(`addGlobalMiddleware([betterAuthSession()])`, '');
-        }
+        wiring.push(`addGlobalMiddleware([`, `  betterAuthSession({ priority: 'lowest' }),`, ...(includeConsoleToken ? consoleTokenMiddlewareLines() : []), `])`, '');
     }
     // `pikku` tag marks these as scaffold plumbing (not user-authored wiring) so
     // visualizers like the console's woven build view can hide them.
@@ -223,20 +209,13 @@ export const serializeAuthGen = (definition, providers, authFile, leaf, packageM
         const middleware = [
             '// AUTO-GENERATED by pikku CLI — do not edit',
             '',
-            `import { addGlobalMiddleware } from '@pikku/core/middleware'`,
+            `import { addGlobalMiddleware${includeConsoleToken ? ', authBearer' : ''} } from '@pikku/core/middleware'`,
             `import { betterAuthStatelessSession } from '@pikku/better-auth'`,
-            ...(includeConsoleToken
-                ? [`import { authBearer } from '@pikku/core/middleware'`]
-                : []),
             '',
-            ...(includeConsoleToken
-                ? [
-                    `addGlobalMiddleware([`,
-                    `  betterAuthStatelessSession(),`,
-                    ...consoleTokenMiddlewareLines(),
-                    `])`,
-                ]
-                : [`addGlobalMiddleware([betterAuthStatelessSession()])`]),
+            `addGlobalMiddleware([`,
+            `  betterAuthStatelessSession({ priority: 'lowest' }),`,
+            ...(includeConsoleToken ? consoleTokenMiddlewareLines() : []),
+            `])`,
             '',
         ];
         output.middleware = middleware.join('\n');

package/dist/src/functions/wirings/channels/pikku-command-channel-types.d.ts

@@ -1 +1 @@
-export declare const pikkuChannelTypes: import("#pikku/function").PikkuFunctionConfig<void, void, "rpc" | "session", import("#pikku/function").PikkuFunctionSessionless<void, void, "rpc" | "session", import("#pikku/function").WiredServices, unknown> | import("#pikku/function").PikkuFunction<void, void, "rpc" | "session", import("#pikku/function").WiredServices>, undefined, undefined>;
+export declare const pikkuChannelTypes: import("#pikku/function").PikkuFunctionConfig<void, void, "rpc" | "session", import("#pikku/function").PikkuFunction<void, void, "rpc" | "session", import("#pikku/function").WiredServices> | import("#pikku/function").PikkuFunctionSessionless<void, void, "rpc" | "session", import("#pikku/function").WiredServices, unknown>, undefined, undefined>;

package/dist/src/functions/wirings/channels/pikku-command-channels-map.d.ts

@@ -1 +1 @@
-export declare const pikkuChannelsMap: import("#pikku/function").PikkuFunctionConfig<void, void, "rpc" | "session", import("#pikku/function").PikkuFunctionSessionless<void, void, "rpc" | "session", import("#pikku/function").WiredServices, unknown> | import("#pikku/function").PikkuFunction<void, void, "rpc" | "session", import("#pikku/function").WiredServices>, undefined, undefined>;
+export declare const pikkuChannelsMap: import("#pikku/function").PikkuFunctionConfig<void, void, "rpc" | "session", import("#pikku/function").PikkuFunction<void, void, "rpc" | "session", import("#pikku/function").WiredServices> | import("#pikku/function").PikkuFunctionSessionless<void, void, "rpc" | "session", import("#pikku/function").WiredServices, unknown>, undefined, undefined>;

package/dist/src/functions/wirings/channels/pikku-command-channels.d.ts

@@ -1 +1 @@
-export declare const pikkuCommandChannels: import("#pikku/function").PikkuFunctionConfig<void, boolean | undefined, "rpc" | "session", import("#pikku/function").PikkuFunctionSessionless<void, boolean | undefined, "rpc" | "session", import("#pikku/function").WiredServices, unknown> | import("#pikku/function").PikkuFunction<void, boolean | undefined, "rpc" | "session", import("#pikku/function").WiredServices>, undefined, undefined>;
+export declare const pikkuCommandChannels: import("#pikku/function").PikkuFunctionConfig<void, boolean | undefined, "rpc" | "session", import("#pikku/function").PikkuFunction<void, boolean | undefined, "rpc" | "session", import("#pikku/function").WiredServices> | import("#pikku/function").PikkuFunctionSessionless<void, boolean | undefined, "rpc" | "session", import("#pikku/function").WiredServices, unknown>, undefined, undefined>;

package/dist/src/functions/wirings/cli/pikku-command-cli-entry.d.ts

@@ -1 +1 @@
-export declare const pikkuCLIEntry: import("#pikku/function").PikkuFunctionConfig<void, boolean, "rpc" | "session", import("#pikku/function").PikkuFunctionSessionless<void, boolean, "rpc" | "session", import("#pikku/function").WiredServices, unknown> | import("#pikku/function").PikkuFunction<void, boolean, "rpc" | "session", import("#pikku/function").WiredServices>, undefined, undefined>;
+export declare const pikkuCLIEntry: import("#pikku/function").PikkuFunctionConfig<void, boolean, "rpc" | "session", import("#pikku/function").PikkuFunction<void, boolean, "rpc" | "session", import("#pikku/function").WiredServices> | import("#pikku/function").PikkuFunctionSessionless<void, boolean, "rpc" | "session", import("#pikku/function").WiredServices, unknown>, undefined, undefined>;

package/dist/src/functions/wirings/cli/pikku-command-cli-types.d.ts

@@ -1,5 +1,5 @@
 type CLITypesCommandInput = {
     bootstrap?: boolean;
 };
-export declare const pikkuCLITypes: import("#pikku/function").PikkuFunctionConfig<CLITypesCommandInput, void, "rpc" | "session", import("#pikku/function").PikkuFunctionSessionless<CLITypesCommandInput, void, "rpc" | "session", import("#pikku/function").WiredServices, unknown> | import("#pikku/function").PikkuFunction<CLITypesCommandInput, void, "rpc" | "session", import("#pikku/function").WiredServices>, undefined, undefined>;
+export declare const pikkuCLITypes: import("#pikku/function").PikkuFunctionConfig<CLITypesCommandInput, void, "rpc" | "session", import("#pikku/function").PikkuFunction<CLITypesCommandInput, void, "rpc" | "session", import("#pikku/function").WiredServices> | import("#pikku/function").PikkuFunctionSessionless<CLITypesCommandInput, void, "rpc" | "session", import("#pikku/function").WiredServices, unknown>, undefined, undefined>;
 export {};

package/dist/src/functions/wirings/cli/pikku-command-cli.d.ts

@@ -1 +1 @@
-export declare const pikkuCLI: import("#pikku/function").PikkuFunctionConfig<void, boolean | undefined, "rpc" | "session", import("#pikku/function").PikkuFunctionSessionless<void, boolean | undefined, "rpc" | "session", import("#pikku/function").WiredServices, unknown> | import("#pikku/function").PikkuFunction<void, boolean | undefined, "rpc" | "session", import("#pikku/function").WiredServices>, undefined, undefined>;
+export declare const pikkuCLI: import("#pikku/function").PikkuFunctionConfig<void, boolean | undefined, "rpc" | "session", import("#pikku/function").PikkuFunction<void, boolean | undefined, "rpc" | "session", import("#pikku/function").WiredServices> | import("#pikku/function").PikkuFunctionSessionless<void, boolean | undefined, "rpc" | "session", import("#pikku/function").WiredServices, unknown>, undefined, undefined>;

package/dist/src/functions/wirings/console/pikku-command-console-functions.d.ts

@@ -1 +1 @@
-export declare const pikkuConsoleFunctions: import("#pikku/function").PikkuFunctionConfig<void, boolean, "rpc" | "session", import("#pikku/function").PikkuFunctionSessionless<void, boolean, "rpc" | "session", import("#pikku/function").WiredServices, unknown> | import("#pikku/function").PikkuFunction<void, boolean, "rpc" | "session", import("#pikku/function").WiredServices>, undefined, undefined>;
+export declare const pikkuConsoleFunctions: import("#pikku/function").PikkuFunctionConfig<void, boolean, "rpc" | "session", import("#pikku/function").PikkuFunction<void, boolean, "rpc" | "session", import("#pikku/function").WiredServices> | import("#pikku/function").PikkuFunctionSessionless<void, boolean, "rpc" | "session", import("#pikku/function").WiredServices, unknown>, undefined, undefined>;

package/dist/src/functions/wirings/console/pikku-command-nodes-meta.d.ts

@@ -1 +1 @@
-export declare const pikkuNodesMeta: import("#pikku/function").PikkuFunctionConfig<void, boolean | undefined, "rpc" | "session", import("#pikku/function").PikkuFunctionSessionless<void, boolean | undefined, "rpc" | "session", import("#pikku/function").WiredServices, unknown> | import("#pikku/function").PikkuFunction<void, boolean | undefined, "rpc" | "session", import("#pikku/function").WiredServices>, undefined, undefined>;
+export declare const pikkuNodesMeta: import("#pikku/function").PikkuFunctionConfig<void, boolean | undefined, "rpc" | "session", import("#pikku/function").PikkuFunction<void, boolean | undefined, "rpc" | "session", import("#pikku/function").WiredServices> | import("#pikku/function").PikkuFunctionSessionless<void, boolean | undefined, "rpc" | "session", import("#pikku/function").WiredServices, unknown>, undefined, undefined>;

package/dist/src/functions/wirings/credentials/pikku-command-credentials.d.ts

@@ -1 +1 @@
-export declare const pikkuCredentials: import("#pikku/function").PikkuFunctionConfig<void, void, "rpc" | "session", import("#pikku/function").PikkuFunctionSessionless<void, void, "rpc" | "session", import("#pikku/function").WiredServices, unknown> | import("#pikku/function").PikkuFunction<void, void, "rpc" | "session", import("#pikku/function").WiredServices>, undefined, undefined>;
+export declare const pikkuCredentials: import("#pikku/function").PikkuFunctionConfig<void, void, "rpc" | "session", import("#pikku/function").PikkuFunction<void, void, "rpc" | "session", import("#pikku/function").WiredServices> | import("#pikku/function").PikkuFunctionSessionless<void, void, "rpc" | "session", import("#pikku/function").WiredServices, unknown>, undefined, undefined>;

package/dist/src/functions/wirings/emails/pikku-command-emails.d.ts

@@ -1,6 +1,6 @@
 import type { PikkuCLIConfig } from '../../../../types/config.js';
 import type { CLILogger } from '../../../services/cli-logger.service.js';
-export declare const pikkuEmails: import("#pikku/function").PikkuFunctionConfig<void, boolean | undefined, "rpc" | "session", import("#pikku/function").PikkuFunctionSessionless<void, boolean | undefined, "rpc" | "session", import("#pikku/function").WiredServices, unknown> | import("#pikku/function").PikkuFunction<void, boolean | undefined, "rpc" | "session", import("#pikku/function").WiredServices>, undefined, undefined>;
+export declare const pikkuEmails: import("#pikku/function").PikkuFunctionConfig<void, boolean | undefined, "rpc" | "session", import("#pikku/function").PikkuFunction<void, boolean | undefined, "rpc" | "session", import("#pikku/function").WiredServices> | import("#pikku/function").PikkuFunctionSessionless<void, boolean | undefined, "rpc" | "session", import("#pikku/function").WiredServices, unknown>, undefined, undefined>;
 export declare function generateEmailsArtifacts(logger: CLILogger, config: Pick<PikkuCLIConfig, 'outDir'> & {
     emailTemplatesDir?: string;
 }): Promise<true | undefined>;

package/dist/src/functions/wirings/errors/pikku-command-error-types.d.ts

@@ -1 +1 @@
-export declare const pikkuErrorTypes: import("#pikku/function").PikkuFunctionConfig<void, void, "rpc" | "session", import("#pikku/function").PikkuFunctionSessionless<void, void, "rpc" | "session", import("#pikku/function").WiredServices, unknown> | import("#pikku/function").PikkuFunction<void, void, "rpc" | "session", import("#pikku/function").WiredServices>, undefined, undefined>;
+export declare const pikkuErrorTypes: import("#pikku/function").PikkuFunctionConfig<void, void, "rpc" | "session", import("#pikku/function").PikkuFunction<void, void, "rpc" | "session", import("#pikku/function").WiredServices> | import("#pikku/function").PikkuFunctionSessionless<void, void, "rpc" | "session", import("#pikku/function").WiredServices, unknown>, undefined, undefined>;

package/dist/src/functions/wirings/flags/pikku-command-feature-flags-scaffold.d.ts

@@ -0,0 +1 @@
+export declare const pikkuFeatureFlagsScaffold: import("#pikku/function").PikkuFunctionConfig<void, boolean, "rpc" | "session", import("#pikku/function").PikkuFunction<void, boolean, "rpc" | "session", import("#pikku/function").WiredServices> | import("#pikku/function").PikkuFunctionSessionless<void, boolean, "rpc" | "session", import("#pikku/function").WiredServices, unknown>, undefined, undefined>;

package/dist/src/functions/wirings/flags/pikku-command-feature-flags-scaffold.js

@@ -0,0 +1,36 @@
+import { pikkuSessionlessFunc } from '#pikku/function';
+import { getLeafImportPath } from '../../../utils/leaf-import-path.js';
+import { writeFileInDir } from '../../../utils/file-writer.js';
+import { logCommandInfoAndTime } from '../../../middleware/log-command-info-and-time.js';
+import { removeLegacyScaffoldFile } from '../../../utils/remove-legacy-scaffold-file.js';
+import { serializeFeatureFlagsScaffold } from './serialize-feature-flags-scaffold.js';
+import { isDeployCodegen } from '../../../utils/is-deploy-codegen.js';
+export const pikkuFeatureFlagsScaffold = pikkuSessionlessFunc({
+    func: async ({ logger, config, variables, getInspectorState }) => {
+        if (await isDeployCodegen(variables)) {
+            return false;
+        }
+        if (!config.scaffold?.featureFlags || !config.featureFlagsFile) {
+            return false;
+        }
+        const { featureFlags } = await getInspectorState();
+        // Refuse rather than emit a wire whose response type is an empty union:
+        // `Record<never, boolean>` compiles and is useless, and a client would
+        // discover the project declared nothing by reading an empty object.
+        if (featureFlags.definitions.length === 0) {
+            logger.error(`scaffold.featureFlags is enabled but no defineFeatureFlags declaration was found. ` +
+                `Add one in a source directory: \`defineFeatureFlags({ newCheckout: { description: 'The new checkout' } })\`.`);
+            return false;
+        }
+        const leaf = (name) => getLeafImportPath(config.featureFlagsFile, name, config);
+        await writeFileInDir(logger, config.featureFlagsFile, serializeFeatureFlagsScaffold(leaf, config.globalHTTPPrefix || ''));
+        await removeLegacyScaffoldFile(config.featureFlagsFile);
+        return true;
+    },
+    middleware: [
+        logCommandInfoAndTime({
+            commandStart: 'Generating Feature Flag Wire',
+            commandEnd: 'Generated Feature Flag Wire',
+        }),
+    ],
+});

package/dist/src/functions/wirings/flags/pikku-command-flags.d.ts

@@ -0,0 +1,7 @@
+export declare const pikkuFlags: import("#pikku/function").PikkuFunctionConfig<{
+    bootstrap?: boolean;
+}, void, "rpc" | "session", import("#pikku/function").PikkuFunction<{
+    bootstrap?: boolean;
+}, void, "rpc" | "session", import("#pikku/function").WiredServices> | import("#pikku/function").PikkuFunctionSessionless<{
+    bootstrap?: boolean;
+}, void, "rpc" | "session", import("#pikku/function").WiredServices, unknown>, undefined, undefined>;

package/dist/src/functions/wirings/flags/pikku-command-flags.js

@@ -0,0 +1,36 @@
+import { pikkuSessionlessFunc } from '#pikku/function';
+import { writeFileInDir } from '../../../utils/file-writer.js';
+import { logCommandInfoAndTime } from '../../../middleware/log-command-info-and-time.js';
+import { serializeFlagsTypes } from './serialize-flags-types.js';
+import { validateAndBuildFeatureFlagDefinitionsMeta } from '@pikku/core/flag';
+export const pikkuFlags = pikkuSessionlessFunc({
+    func: async ({ logger, config, getInspectorState }, data) => {
+        const { flagsFile, flagsMetaJsonFile } = config;
+        if (!flagsFile) {
+            return;
+        }
+        // Same cold-start reasoning as Roles: on a bare .pikku this runs before the
+        // function leaf exists, so it takes the zero state. The file only has to
+        // exist so a function can import FeatureFlagName; the real Flags step
+        // regenerates it with the declarations once setup has run.
+        const bootstrap = data?.bootstrap ?? false;
+        const state = await getInspectorState(false, bootstrap, bootstrap);
+        // Validate before writing anything, and emit the union from the same
+        // validated set the sidecar is built from. Two derivations of one
+        // vocabulary can disagree, and a conflicting redeclaration used to throw
+        // only after the .ts had already been written — leaving a union describing
+        // a set the sidecar never got.
+        const meta = validateAndBuildFeatureFlagDefinitionsMeta(state.featureFlags.definitions);
+        const content = serializeFlagsTypes({ definitions: Object.values(meta) });
+        await writeFileInDir(logger, flagsFile, content);
+        if (flagsMetaJsonFile) {
+            await writeFileInDir(logger, flagsMetaJsonFile, JSON.stringify(meta, null, 2));
+        }
+    },
+    middleware: [
+        logCommandInfoAndTime({
+            commandStart: 'Creating PikkuFlags types',
+            commandEnd: 'Created PikkuFlags types',
+        }),
+    ],
+});

package/dist/src/functions/wirings/flags/serialize-feature-flags-scaffold.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Generate the read wire a client asks for its own flags on.
+ *
+ * Generated into the app rather than shipped in an addon because the map is
+ * keyed by the app's own `FeatureFlagName`. An addon merges its declarations
+ * through the metadata sidecar but never sees the host's union, so the same
+ * endpoint written there could only return `Record<string, boolean>` — losing
+ * the one thing generating a union was for.
+ *
+ * No middleware, on the same terms as the analytics ingest: who may ask is the
+ * project's call, and the answer is already per-caller.
+ */
+export declare const serializeFeatureFlagsScaffold: (leaf: (name: string) => string, globalHTTPPrefix?: string) => string;

package/dist/src/functions/wirings/flags/serialize-feature-flags-scaffold.js

@@ -0,0 +1,73 @@
+/**
+ * Generate the read wire a client asks for its own flags on.
+ *
+ * Generated into the app rather than shipped in an addon because the map is
+ * keyed by the app's own `FeatureFlagName`. An addon merges its declarations
+ * through the metadata sidecar but never sees the host's union, so the same
+ * endpoint written there could only return `Record<string, boolean>` — losing
+ * the one thing generating a union was for.
+ *
+ * No middleware, on the same terms as the analytics ingest: who may ask is the
+ * project's call, and the answer is already per-caller.
+ */
+export const serializeFeatureFlagsScaffold = (leaf, globalHTTPPrefix = '') => `/**
+ * Auto-generated feature flag read wire
+ * Do not edit manually - regenerate with 'npx pikku'
+ */
+import { pikkuSessionlessFunc } from '${leaf('function')}'
+import { wireHTTP } from '${leaf('http')}'
+import {
+  FEATURE_FLAGS,
+  FEATURE_FLAGS_FALLBACK,
+  type FeatureFlagName,
+} from '${leaf('scopes')}'
+import { resolveFlagsForClient } from '@pikku/core/flag'
+
+/**
+ * Every declared flag resolved for the caller, in one request.
+ *
+ * Asked once per session and read from memory after — a flag is checked
+ * wherever a component renders, and a request each would put the network in
+ * front of a paint.
+ *
+ * Unauthenticated by necessity: a signed-out visitor still renders a page, and
+ * a flag it cannot hold resolves false rather than being withheld. The session
+ * is the server's, never read from the body, so no caller can ask what someone
+ * else would see.
+ *
+ * Booleans, not the two halves of a flag's state. \`show\` is their collapse,
+ * and sending \`available\` apart from \`capable\` would tell every visitor which
+ * features exist but are dark.
+ */
+export const featureFlagsForCaller = pikkuSessionlessFunc<
+  null,
+  Record<FeatureFlagName, boolean>
+>({
+  auth: false,
+  tags: ['feature-flags'],
+  description: 'Resolves every declared feature flag for the calling session.',
+  func: async ({ featureFlags }, _data, { session }) => {
+    // No source wired resolves against the compiled declaration, the same
+    // fallback a source uses on a cold start. Availability fails open, so a
+    // project that has not chosen a store yet does not have its clients start
+    // hiding every flagged feature — but \`anyOf\` is still read off the
+    // session, so a scoped flag is not handed to a caller who cannot hold it.
+    const snapshot = featureFlags
+      ? await featureFlags.snapshot()
+      : FEATURE_FLAGS_FALLBACK
+    return resolveFlagsForClient(
+      FEATURE_FLAGS,
+      session,
+      snapshot
+    ) as Record<FeatureFlagName, boolean>
+  },
+})
+
+wireHTTP({
+  route: '${globalHTTPPrefix}/feature-flags',
+  method: 'get',
+  auth: false,
+  tags: ['feature-flags'],
+  func: featureFlagsForCaller,
+})
+`;

package/dist/src/functions/wirings/flags/serialize-flags-types.d.ts

@@ -0,0 +1,14 @@
+import type { FeatureFlagDefinitions } from '@pikku/core/flag';
+export interface SerializeFlagsOptions {
+    definitions: FeatureFlagDefinitions;
+}
+/**
+ * Generates the `FeatureFlagName` union and flag metadata from
+ * `defineFeatureFlags` declarations.
+ *
+ * The union is what makes `featureFlag: 'sandboxes'` on a function checkable. A
+ * typo in a flag name would otherwise fail open — an unknown key is absent from
+ * every snapshot, and an absent key is available — so the misspelled gate would
+ * silently never close.
+ */
+export declare const serializeFlagsTypes: ({ definitions }: SerializeFlagsOptions) => string;

package/dist/src/functions/wirings/flags/serialize-flags-types.js

@@ -0,0 +1,68 @@
+import { tsLiteral } from '../../../utils/ts-literal.js';
+/**
+ * Generates the `FeatureFlagName` union and flag metadata from
+ * `defineFeatureFlags` declarations.
+ *
+ * The union is what makes `featureFlag: 'sandboxes'` on a function checkable. A
+ * typo in a flag name would otherwise fail open — an unknown key is absent from
+ * every snapshot, and an absent key is available — so the misspelled gate would
+ * silently never close.
+ */
+export const serializeFlagsTypes = ({ definitions }) => {
+    const names = [...new Set(definitions.map((d) => d.name))].sort();
+    const union = names.length > 0
+        ? `\n${names.map((name) => `  | ${tsLiteral(name)}`).join('\n')}`
+        : ' never';
+    return `/**
+ * This file was generated by the @pikku/cli
+ */
+import type { DeclaredFlag, FeatureFlagDefinitionsMeta } from '@pikku/core/flag'
+import {
+  compiledFallbackSnapshot,
+  flattenFeatureFlagDefinitions,
+} from '@pikku/core/flag'
+import definitions from './pikku-flags-meta.gen.json' with { type: 'json' }
+
+/** Every feature flag declared in this application. */
+export type FeatureFlagName =${union}
+
+/**
+ * The declared flag set, for a FeatureFlagStore to sync into its store.
+ *
+ * Derived from the metadata sidecar rather than inlined, so the import above
+ * forces tsc to emit the .json alongside this file — an addon publishes only
+ * its compiled output, and a host reads that .json to merge the addon's flags
+ * into its own union.
+ *
+ * Additive on removal: a deleted declaration leaves the row marked
+ * \`declared: false\` rather than switching a feature off on deploy. Use
+ * \`pikku flags prune\` to remove them.
+ */
+export const FEATURE_FLAGS: DeclaredFlag[] = flattenFeatureFlagDefinitions(
+  Object.values(definitions as FeatureFlagDefinitionsMeta)
+)
+
+/**
+ * Declared flags, keyed by name. Rendered by the console beside each switch.
+ *
+ * Keyed by \`FeatureFlagName\` so a misspelled lookup is a type error, which is
+ * the whole point of generating the union. The assertion is what
+ * \`Object.fromEntries\` costs — it returns an index signature — and it is
+ * sound here because both this object and the union are built from
+ * \`FEATURE_FLAGS\`, so every key of the union is present.
+ */
+export const FEATURE_FLAGS_META = Object.fromEntries(
+  FEATURE_FLAGS.map((flag) => [flag.name, flag])
+) as Record<FeatureFlagName, DeclaredFlag>
+
+/**
+ * What a flag source falls back to when its backing store cannot be read: every
+ * declared flag on, no rollout, no overrides.
+ *
+ * Failing open is deliberate. A flag store is not an authorization boundary —
+ * \`scopes:\` is — so an unreadable config must not take the product down with
+ * it.
+ */
+export const FEATURE_FLAGS_FALLBACK = compiledFallbackSnapshot(FEATURE_FLAGS)
+`;
+};

package/dist/src/functions/wirings/functions/pikku-command-addon-types.d.ts

@@ -1,5 +1,5 @@
 type AddonTypesCommandInput = {
     bootstrap?: boolean;
 };
-export declare const pikkuAddonTypes: import("#pikku/function").PikkuFunctionConfig<AddonTypesCommandInput, void, "rpc" | "session", import("#pikku/function").PikkuFunctionSessionless<AddonTypesCommandInput, void, "rpc" | "session", import("#pikku/function").WiredServices, unknown> | import("#pikku/function").PikkuFunction<AddonTypesCommandInput, void, "rpc" | "session", import("#pikku/function").WiredServices>, undefined, undefined>;
+export declare const pikkuAddonTypes: import("#pikku/function").PikkuFunctionConfig<AddonTypesCommandInput, void, "rpc" | "session", import("#pikku/function").PikkuFunction<AddonTypesCommandInput, void, "rpc" | "session", import("#pikku/function").WiredServices> | import("#pikku/function").PikkuFunctionSessionless<AddonTypesCommandInput, void, "rpc" | "session", import("#pikku/function").WiredServices, unknown>, undefined, undefined>;
 export {};