@pikku/core 0.12.147 → 0.12.148

package/dist/contributors/contributors.types.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Where a target gets a contributor's bindings from. `env` is plain
+ * environment variables, which every target has; `cloudflare` is Cloudflare
+ * worker bindings, which only the Cloudflare deploy provides.
+ */
+export type ContributorBindingSource = 'env' | 'cloudflare';
+/** The database the generated app uses, as contributors see it at build time. */
+export type ContributorDb = {
+    /** The SQL engine the app's database runs on. MySQL is not represented. */
+    engine: 'sqlite' | 'postgres';
+    /** Column coercion map from `pikku db generate`, keyed by table then column. */
+    coercionMap?: Record<string, Record<string, 'date' | 'bool' | 'json'>>;
+};
+/**
+ * Build-time facts about the app being generated. Handed to `when` while the
+ * generator selects contributors and, as plain data, to `run`.
+ */
+export interface ContributorPlatform {
+    /** Service names the app (dev) or the deploy unit requires. */
+    serviceNames: string[];
+    /** True when the app uses the queue, so a contributor can provide or skip a queue service. */
+    needsQueue: boolean;
+    /** True when the app uses workflows, so a contributor can provide or skip workflow services. */
+    needsWorkflow: boolean;
+    /** True when the app uses AI agents, so a contributor can provide or skip agent services. */
+    needsAgent: boolean;
+    /**
+     * Baseline services the generated entry already holds before any
+     * contributor runs. They satisfy a contributor's `needs`, are read as
+     * `runtime.<name>`, and a contributor may provide the same key to replace
+     * them. Undefined means none.
+     */
+    runtimeServices?: string[];
+    /** The app's database, when it uses SQLite or Postgres. Unset otherwise. */
+    db?: ContributorDb;
+}
+export interface Contributor<TServices = any, TPlatform extends ContributorPlatform = ContributorPlatform> {
+    /**
+     * Service keys `run` sets on `services`. May be empty for a contributor that
+     * only decorates services another contributor provides.
+     */
+    provides?: string[];
+    /**
+     * Service keys this contributor reads, from `runtime` or from `services`
+     * set by another contributor. A dotted key (`logSources.stage`) is met by a
+     * contributor providing it exactly or providing a prefix of it
+     * (`logSources`). Contributors that provide a need run first.
+     */
+    needs?: string[];
+    /**
+     * Binding sources the target must be able to supply for this contributor to
+     * apply. Defaults to `['env']`. A contributor the project opted in to whose
+     * `requires` the target cannot meet is a build error.
+     */
+    requires?: ContributorBindingSource[];
+    /** Build-time only. A contributor returning false is left out entirely. */
+    when?(platform: TPlatform): boolean;
+    /** Constructs services. Runtime `env` guards belong here, not in `when`. */
+    run(services: TServices, env: Record<string, string | undefined>, runtime: Record<string, any>, platform: TPlatform): void | Promise<void>;
+    /** Runtime setup, called where the server lifecycle runs. */
+    onServerStart?(services: TServices): void | Promise<void>;
+    /** Teardown, called in reverse `needs` order where the server lifecycle runs. */
+    onServerStop?(services: TServices): void | Promise<void>;
+}
+/** The per-target forms of one named contributor: a `dev` variant and a `deploy` variant. */
+export interface ContributorVariants<TServices = any, TPlatform extends ContributorPlatform = ContributorPlatform> {
+    /** The contributor `pikku dev` applies. Omit it to leave this contributor out of dev. */
+    dev?: Contributor<TServices, TPlatform>;
+    /** The contributor a deploy build applies. Omit it to leave this contributor out of deploys. */
+    deploy?: Contributor<TServices, TPlatform>;
+}
+/** The build a contributor is selected for: `pikku dev`, or a deploy. */
+export type ContributorTarget = 'dev' | 'deploy';
+export interface NamedContributor<TServices = any, TPlatform extends ContributorPlatform = ContributorPlatform> {
+    name: string;
+    contributor: Contributor<TServices, TPlatform>;
+}

package/dist/contributors/contributors.types.js

@@ -0,0 +1 @@
+export {};

package/dist/contributors/define-contributors.d.ts

@@ -0,0 +1,7 @@
+import type { ContributorPlatform, ContributorVariants } from './contributors.types.js';
+/**
+ * Registers an addon's contributors by name. A project opts in to a name with
+ * `wireAddon({ contributors: ['name'] })`; only the selected variant for the
+ * build target is bundled.
+ */
+export declare const defineContributors: <const T extends Record<string, ContributorVariants<any, ContributorPlatform>>>(contributors: T) => T;

package/dist/contributors/define-contributors.js

@@ -0,0 +1,6 @@
+/**
+ * Registers an addon's contributors by name. A project opts in to a name with
+ * `wireAddon({ contributors: ['name'] })`; only the selected variant for the
+ * build target is bundled.
+ */
+export const defineContributors = (contributors) => contributors;

package/dist/contributors/index.d.ts

@@ -0,0 +1,4 @@
+export { defineContributors } from './define-contributors.js';
+export { ContributorDependencyError, DEFAULT_CONTRIBUTOR_BINDING_SOURCES, orderContributors, resolveContributors, selectContributors, } from './resolve-contributors.js';
+export type { SkippedContributor } from './resolve-contributors.js';
+export type { Contributor, ContributorBindingSource, ContributorDb, ContributorPlatform, ContributorTarget, ContributorVariants, NamedContributor, } from './contributors.types.js';

package/dist/contributors/index.js

@@ -0,0 +1,2 @@
+export { defineContributors } from './define-contributors.js';
+export { ContributorDependencyError, DEFAULT_CONTRIBUTOR_BINDING_SOURCES, orderContributors, resolveContributors, selectContributors, } from './resolve-contributors.js';

package/dist/contributors/resolve-contributors.d.ts

@@ -0,0 +1,51 @@
+import type { ContributorBindingSource, ContributorPlatform, NamedContributor } from './contributors.types.js';
+export declare class ContributorDependencyError extends Error {
+    constructor(message: string);
+}
+export declare const DEFAULT_CONTRIBUTOR_BINDING_SOURCES: readonly ContributorBindingSource[];
+export interface SkippedContributor {
+    name: string;
+    /**
+     * `when` returned false; the target cannot supply its `requires` (checked
+     * only once `when` passed, so this one is a contributor the build wanted);
+     * or it was `optional` and nothing meets a need of it.
+     */
+    reason: 'when' | 'requires' | 'needs';
+}
+/**
+ * Drops contributors whose `when` is false or whose `requires` the target
+ * cannot supply. The clash and ordering checks run on what is left, so an
+ * exclusive pair of `when`s never clashes.
+ */
+export declare const selectContributors: <T extends NamedContributor<any, any>>(contributors: readonly T[], options: {
+    platform: ContributorPlatform;
+    supported?: readonly ContributorBindingSource[];
+}) => {
+    selected: T[];
+    skipped: SkippedContributor[];
+};
+/**
+ * Orders contributors so each runs after every contributor providing one of
+ * its `needs`. Contributors without needs keep their input order.
+ *
+ * Throws a `ContributorDependencyError` for a repeated name, a need nothing
+ * provides, a key two contributors both provide, or a cycle. A key listed in
+ * `options.runtime` is a baseline service: it meets a need and a contributor
+ * may provide it too, replacing it.
+ */
+export declare const orderContributors: <T extends NamedContributor<any, any>>(contributors: readonly T[], options?: {
+    runtime?: readonly string[];
+}) => T[];
+/**
+ * Filters by `when`/`requires`, then checks clashes and orders what is left.
+ * Names in `optional` are dropped, rather than failing the build, when a need
+ * of theirs is met by nothing.
+ */
+export declare const resolveContributors: <T extends NamedContributor<any, any>>(contributors: readonly T[], options: {
+    platform: ContributorPlatform;
+    supported?: readonly ContributorBindingSource[];
+    optional?: ReadonlySet<string>;
+}) => {
+    ordered: T[];
+    skipped: SkippedContributor[];
+};

package/dist/contributors/resolve-contributors.js

@@ -0,0 +1,158 @@
+export class ContributorDependencyError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ContributorDependencyError';
+    }
+}
+export const DEFAULT_CONTRIBUTOR_BINDING_SOURCES = ['env'];
+const satisfies = (provided, need) => provided === need || need.startsWith(`${provided}.`);
+/**
+ * Drops contributors whose `when` is false or whose `requires` the target
+ * cannot supply. The clash and ordering checks run on what is left, so an
+ * exclusive pair of `when`s never clashes.
+ */
+export const selectContributors = (contributors, options) => {
+    const supported = options.supported ?? DEFAULT_CONTRIBUTOR_BINDING_SOURCES;
+    const selected = [];
+    const skipped = [];
+    for (const entry of contributors) {
+        const requires = entry.contributor.requires ?? DEFAULT_CONTRIBUTOR_BINDING_SOURCES;
+        // `when` first: a contributor that is not meant for this build is never
+        // reported as one the target failed to support.
+        if (entry.contributor.when?.(options.platform) === false) {
+            skipped.push({ name: entry.name, reason: 'when' });
+        }
+        else if (!requires.every((source) => supported.includes(source))) {
+            skipped.push({ name: entry.name, reason: 'requires' });
+        }
+        else {
+            selected.push(entry);
+        }
+    }
+    return { selected, skipped };
+};
+/**
+ * Orders contributors so each runs after every contributor providing one of
+ * its `needs`. Contributors without needs keep their input order.
+ *
+ * Throws a `ContributorDependencyError` for a repeated name, a need nothing
+ * provides, a key two contributors both provide, or a cycle. A key listed in
+ * `options.runtime` is a baseline service: it meets a need and a contributor
+ * may provide it too, replacing it.
+ */
+export const orderContributors = (contributors, options = {}) => {
+    const runtime = options.runtime ?? [];
+    const names = new Set();
+    for (const { name } of contributors) {
+        if (names.has(name)) {
+            throw new ContributorDependencyError(`Contributor '${name}' is selected more than once.`);
+        }
+        names.add(name);
+    }
+    const owners = new Map();
+    for (const entry of contributors) {
+        for (const key of entry.contributor.provides ?? []) {
+            const owner = owners.get(key);
+            if (owner && owner !== entry) {
+                throw new ContributorDependencyError(`Contributors '${owner.name}' and '${entry.name}' both provide '${key}'. Each service key has one provider.`);
+            }
+            owners.set(key, entry);
+        }
+    }
+    const dependencies = new Map();
+    for (const entry of contributors) {
+        const deps = new Set();
+        // A contributor that provides what it needs (`provides: ['x'], needs: ['x']`,
+        // even for a baseline x) depends on itself, which is a cycle; a decorator
+        // declares empty `provides` and reads x from `services`/`runtime` instead.
+        for (const need of entry.contributor.needs ?? []) {
+            const providers = contributors.filter((other) => (other.contributor.provides ?? []).some((key) => satisfies(key, need)));
+            const fromRuntime = runtime.some((key) => satisfies(key, need));
+            if (providers.length === 0 && !fromRuntime) {
+                const near = contributors
+                    .filter((other) => (other.contributor.provides ?? []).some((key) => key.startsWith(`${need}.`)))
+                    .map((other) => other.name);
+                const hint = near.length > 0
+                    ? ` ${near.join(', ')} provide${near.length === 1 ? 's' : ''} keys under it, but not '${need}' itself.`
+                    : runtime.length > 0
+                        ? ` No contributor provides it, and the runtime only has: ${runtime.join(', ')}.`
+                        : ` No contributor provides it, and this runtime provides none.`;
+                throw new ContributorDependencyError(`Contributor '${entry.name}' needs '${need}', which nothing provides.${hint}`);
+            }
+            for (const provider of providers)
+                deps.add(provider);
+        }
+        dependencies.set(entry, [...deps]);
+    }
+    const ordered = [];
+    const placed = new Set();
+    while (ordered.length < contributors.length) {
+        const next = contributors.find((entry) => !placed.has(entry) &&
+            dependencies.get(entry).every((dep) => placed.has(dep)));
+        if (!next) {
+            throw new ContributorDependencyError(`Contributors depend on each other in a cycle: ${findCycle(contributors.filter((c) => !placed.has(c)), dependencies)
+                .map((c) => c.name)
+                .join(' -> ')}`);
+        }
+        placed.add(next);
+        ordered.push(next);
+    }
+    return ordered;
+};
+/**
+ * Drops, repeatedly, the `optional` contributors whose `needs` nothing left
+ * provides, so one that only decorates a service (a wrapper around
+ * `services.kysely`) applies when the service exists and is not an error when
+ * it does not.
+ */
+const dropUnmetOptional = (selected, optional, runtime) => {
+    let kept = [...selected];
+    const dropped = [];
+    for (;;) {
+        const unmet = kept.find((entry) => optional.has(entry.name) &&
+            (entry.contributor.needs ?? []).some((need) => !runtime.some((key) => satisfies(key, need)) &&
+                !kept.some((other) => other !== entry &&
+                    (other.contributor.provides ?? []).some((key) => satisfies(key, need)))));
+        if (!unmet)
+            return { kept, dropped };
+        kept = kept.filter((entry) => entry !== unmet);
+        dropped.push({ name: unmet.name, reason: 'needs' });
+    }
+};
+/**
+ * Filters by `when`/`requires`, then checks clashes and orders what is left.
+ * Names in `optional` are dropped, rather than failing the build, when a need
+ * of theirs is met by nothing.
+ */
+export const resolveContributors = (contributors, options) => {
+    const { selected, skipped } = selectContributors(contributors, options);
+    const { kept, dropped } = dropUnmetOptional(selected, options.optional ?? new Set(), options.platform.runtimeServices ?? []);
+    return {
+        ordered: orderContributors(kept, {
+            runtime: options.platform.runtimeServices,
+        }),
+        skipped: [...skipped, ...dropped],
+    };
+};
+const findCycle = (remaining, dependencies) => {
+    const pending = new Set(remaining);
+    const visit = (node, path) => {
+        const at = path.indexOf(node);
+        if (at >= 0)
+            return [...path.slice(at), node];
+        for (const dep of dependencies.get(node) ?? []) {
+            if (!pending.has(dep))
+                continue;
+            const cycle = visit(dep, [...path, node]);
+            if (cycle)
+                return cycle;
+        }
+        return undefined;
+    };
+    for (const node of remaining) {
+        const cycle = visit(node, []);
+        if (cycle)
+            return cycle;
+    }
+    return remaining;
+};

package/dist/lifecycle.d.ts

@@ -15,3 +15,22 @@ export declare const pikkuServerLifecycle: <SS extends CoreSingletonServices = C
  * @returns A function that removes the handlers.
  */
 export declare const onShutdownSignals: (run: (signal: NodeJS.Signals) => void | Promise<void>, signals?: NodeJS.Signals[]) => (() => void);
+/** A contributor's `onServerStart` / `onServerStop`, as the generated platform-services file lists it. */
+export interface ContributorServerHook {
+    name: string;
+    run: (services: any) => void | Promise<void>;
+}
+/**
+ * Composes the server lifecycle around the app's own: contributor start hooks
+ * run first, in order, then the app's `beforeStart`; the app's `afterStart` and
+ * `beforeStop` are unchanged; after the app's `afterStop` the stop hooks run
+ * (already in reverse run order, as the generated file lists them).
+ *
+ * A start hook that throws aborts startup with an error naming the contributor.
+ * Every stop hook is attempted even if an earlier one (or the app's
+ * `afterStop`) threw; the failures are then thrown together, each named.
+ */
+export declare const composeServerLifecycle: <SS extends CoreSingletonServices = CoreSingletonServices>(app: ServerLifecycle<SS> | undefined, hooks: {
+    start?: readonly ContributorServerHook[];
+    stop?: readonly ContributorServerHook[];
+}) => ServerLifecycle<SS>;

package/dist/lifecycle.js

@@ -67,3 +67,57 @@ export const onShutdownSignals = (run, signals = ['SIGINT', 'SIGTERM']) => {
             proc.off(signal, handler);
     };
 };
+const describeError = (error) => error instanceof Error ? error.message : String(error);
+/**
+ * Composes the server lifecycle around the app's own: contributor start hooks
+ * run first, in order, then the app's `beforeStart`; the app's `afterStart` and
+ * `beforeStop` are unchanged; after the app's `afterStop` the stop hooks run
+ * (already in reverse run order, as the generated file lists them).
+ *
+ * A start hook that throws aborts startup with an error naming the contributor.
+ * Every stop hook is attempted even if an earlier one (or the app's
+ * `afterStop`) threw; the failures are then thrown together, each named.
+ */
+export const composeServerLifecycle = (app, hooks) => ({
+    beforeStart: async (services) => {
+        for (const hook of hooks.start ?? []) {
+            try {
+                await hook.run(services);
+            }
+            catch (error) {
+                throw new Error(`Contributor '${hook.name}' failed in onServerStart: ${describeError(error)}`, { cause: error });
+            }
+        }
+        await app?.beforeStart?.(services);
+    },
+    afterStart: (services) => app?.afterStart?.(services),
+    beforeStop: (services) => app?.beforeStop?.(services),
+    afterStop: async (services) => {
+        const failures = [];
+        const errors = [];
+        let hookFailed = false;
+        try {
+            await app?.afterStop?.(services);
+        }
+        catch (error) {
+            failures.push(`the app's afterStop: ${describeError(error)}`);
+            errors.push(error);
+        }
+        for (const hook of hooks.stop ?? []) {
+            try {
+                await hook.run(services);
+            }
+            catch (error) {
+                hookFailed = true;
+                failures.push(`contributor '${hook.name}' onServerStop: ${describeError(error)}`);
+                errors.push(error);
+            }
+        }
+        if (errors.length === 1 && failures.length === 1 && !hookFailed) {
+            throw errors[0];
+        }
+        if (errors.length > 0) {
+            throw new AggregateError(errors, `Server stop failed: ${failures.join('; ')}`);
+        }
+    },
+});

package/dist/wirings/addon/addon-runner.js

@@ -105,6 +105,13 @@ const scopeWebhookService = (service, namespace) => {
     scopedWebhookServices.add(scoped);
     return scoped;
 };
+const authFromAppServices = () => {
+    const auth = pikkuState(null, 'package', 'singletonServices')?.auth;
+    if (typeof auth !== 'function') {
+        throw new Error('auth was called before the app had finished creating its singleton services');
+    }
+    return auth();
+};
 export const getOrCreatePackageSingletonServices = async (packageName, parentServices, addonInstance) => {
     addonInstance ??= addonInstanceForNamespace(findAddonNamespaceForPackage(packageName) ?? undefined, packageName);
     const cacheKey = addonInstance?.namespace ?? packageName;
@@ -114,6 +121,10 @@ export const getOrCreatePackageSingletonServices = async (packageName, parentSer
     }
     const factories = pikkuState(packageName, 'package', 'factories');
     let existingServices = parentServices;
+    if (typeof existingServices.auth !== 'function' &&
+        pikkuState(null, 'package', 'authFactory')) {
+        existingServices = { ...existingServices, auth: authFromAppServices };
+    }
     if (addonInstance?.secretOverrides && parentServices.secrets) {
         existingServices = {
             ...existingServices,

package/dist/wirings/addon/{pikku-studio.d.ts → define-plugin.d.ts}

@@ -45,7 +45,7 @@ export type StudioAppScreen = StudioScreenBase & {
 };
 /** One screen an addon ships: either a component the host renders or a static app it serves in a sandboxed iframe. */
 export type StudioScreen = StudioComponentScreen | StudioAppScreen;
-/** The manifest passed to `pikkuStudio`: the addon's title, a message key, and its screens. */
+/** The manifest passed to `definePlugin`: the addon's title, a message key, and its screens. */
 export type StudioManifest = {
     title: string;
     screens: StudioScreen[];
@@ -56,5 +56,7 @@ export type StudioManifest = {
  * message keys in the addon's own catalog, `messages/{locale}.json`: a key
  * missing from `messages/en.json` fails the build.
  */
-export declare const pikkuStudio: (manifest: StudioManifest) => StudioManifest;
+export declare const definePlugin: (manifest: StudioManifest) => StudioManifest;
+/** @deprecated Renamed to `definePlugin`. */
+export declare const pikkuStudio: typeof definePlugin;
 export {};

package/dist/wirings/addon/{pikku-studio.js → define-plugin.js}

@@ -4,4 +4,6 @@
  * message keys in the addon's own catalog, `messages/{locale}.json`: a key
  * missing from `messages/en.json` fails the build.
  */
-export const pikkuStudio = (manifest) => manifest;
+export const definePlugin = (manifest) => manifest;
+/** @deprecated Renamed to `definePlugin`. */
+export const pikkuStudio = definePlugin;

package/dist/wirings/addon/index.d.ts

@@ -1,7 +1,7 @@
 export { wireAddon } from './wire-addon.js';
 export type { WireAddonConfig } from './wire-addon.js';
-export { pikkuStudio } from './pikku-studio.js';
-export type { StudioManifest, StudioScreen, StudioComponentScreen, StudioAppScreen, StudioNav, } from './pikku-studio.js';
+export { definePlugin, pikkuStudio } from './define-plugin.js';
+export type { StudioManifest, StudioScreen, StudioComponentScreen, StudioAppScreen, StudioNav, } from './define-plugin.js';
 export { wireRemoteAddon } from './wire-remote-addon.js';
 export type { WireRemoteAddonConfig, RemoteAddonAuth, } from './wire-remote-addon.js';
 export { resolveRemoteAddonToken, RemoteAddonAuthError, } from './remote-addon-auth.js';

package/dist/wirings/addon/index.js

@@ -1,4 +1,4 @@
 export { wireAddon } from './wire-addon.js';
-export { pikkuStudio } from './pikku-studio.js';
+export { definePlugin, pikkuStudio } from './define-plugin.js';
 export { wireRemoteAddon } from './wire-remote-addon.js';
 export { resolveRemoteAddonToken, RemoteAddonAuthError, } from './remote-addon-auth.js';

package/dist/wirings/addon/wire-addon.d.ts

@@ -46,7 +46,7 @@ export type WireAddonConfig = {
     /** Filters this addon in and out of a build — see the `tags` option on `pikku all`. It has no effect at runtime. */
     tags?: string[];
     /**
-     * Mounts the screens the addon ships (see `pikkuStudio`) in the host, each at
+     * Mounts the screens the addon ships (see `definePlugin`) in the host, each at
      * the path its `scope` gives it. Without it the addon's screens are ignored.
      * The package must declare at least one, or `pikku all` rejects the wiring.
      */
@@ -100,6 +100,12 @@ export type WireAddonConfig = {
     contentGrants?: Record<string, 'read' | 'write'>;
     /** Hands over the whole `ContentService` unscoped. The value is the reason, recorded in the deploy manifest. */
     globalContent?: string;
+    /**
+     * The contributors this project takes from the addon (those it registers with
+     * `defineContributors`), by name. None unless listed: an addon never injects
+     * services into a project that did not ask for them.
+     */
+    contributors?: string[];
 };
 /**
  * Installs an addon into this project: its functions, wirings and scopes become

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/core",
-  "version": "0.12.147",
+  "version": "0.12.148",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/pikkujs/pikku.git",
@@ -93,6 +93,7 @@
     "./state": "./dist/pikku-state.js",
     "./classification": "./dist/classification/index.js",
     "./utils": "./dist/utils.js",
+    "./contributors": "./dist/contributors/index.js",
     "./lifecycle": "./dist/lifecycle.js",
     "./schema": "./dist/schema.js",
     "./testing": "./dist/testing/index.js",
@@ -119,7 +120,7 @@
   },
   "devDependencies": {
     "@ag-ui/core": "0.0.59",
-    "@pikku/deploy": "^0.12.17",
+    "@pikku/deploy": "^0.12.18",
     "@types/node": "^26.6.5",
     "esbuild": "~0.28.2",
     "tsx": "^4.23.15"