@pikku/core 0.12.146 → 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/function/function-runner.js

@@ -62,6 +62,13 @@ async function resolveSession(wire, singletonServices, sessionService) {
  * @param packageName - The addon package it belongs to; `null` for the app.
  */
 export const addFunction = (funcName, funcConfig, packageName = null) => {
+    if (funcConfig.disabled) {
+        throw new Error(`Function '${funcName}' is disabled` +
+            (typeof funcConfig.disabled === 'string'
+                ? ` (${funcConfig.disabled})`
+                : '') +
+            ' and cannot be registered.');
+    }
     pikkuState(packageName, 'function', 'functions').set(funcName, funcConfig);
 };
 export const getFunctionNames = (packageName = null) => {

package/dist/function/functions.types.d.ts

@@ -128,6 +128,14 @@ export type CorePikkuFunctionConfig<PikkuFunction extends CorePikkuFunction<any,
     version?: number;
     /** Filters this function in and out of a build — see the `tags` option on `pikku all`. It has no effect at runtime. */
     tags?: string[];
+    /**
+     * Switches the function off: `true`, or a string saying why. The build
+     * leaves it out of every map, client and wiring, and refuses (PKU562)
+     * anything that still references it, so marking a function believed dead
+     * proves it. The source keeps type-checking; deleting the flag turns it
+     * back on.
+     */
+    disabled?: true | string;
     /** Makes the function callable from outside as `POST /rpc/<name>`. Without a session requirement, a permission or an addon gate, that means callable by anyone. */
     expose?: boolean;
     /**

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/types/state.types.d.ts

@@ -15,7 +15,7 @@ import type { CoreScheduledTask, ScheduledTasksMeta } from '../wirings/scheduler
 import type { CoreWorkflow, WorkflowsRuntimeMeta } from '../wirings/workflow/workflow.types.js';
 import type { CoreFeature } from '../wirings/workflow/scenario.types.js';
 import type { CoreTrigger, CoreTriggerSource, TriggerMeta, TriggerSourceMeta } from '../wirings/trigger/trigger.types.js';
-import type { CreateConfig, CreateSingletonServices, CreateWireServices, CoreConfig, CoreSingletonServices, CoreServices, CoreUserSession } from './core.types.js';
+import type { CreateConfig, CreateSingletonServices, CreateWireServices, CoreSingletonServices } from './core.types.js';
 import type { FunctionsMeta } from '../function/function-meta.types.js';
 import type { CorePikkuMiddleware, CorePikkuMiddlewareGroup } from '../middleware/middleware.types.js';
 import type { CorePikkuChannelMiddleware } from '../wirings/channel/channel.types.js';
@@ -168,10 +168,11 @@ export interface PikkuPackageState {
         permissions: Record<string, CorePermissionGroup | CorePikkuPermission[]>;
     };
     package: {
+        /** Every package's own factories, each typed where it is defined. */
         factories: {
-            createConfig?: CreateConfig<CoreConfig>;
-            createSingletonServices?: CreateSingletonServices<CoreConfig, CoreSingletonServices>;
-            createWireServices?: CreateWireServices<CoreSingletonServices, CoreServices, CoreUserSession>;
+            createConfig?: CreateConfig<any>;
+            createSingletonServices?: CreateSingletonServices<any, any>;
+            createWireServices?: CreateWireServices<any, any, any>;
         } | null;
         singletonServices: CoreSingletonServices | null;
         /** The pikkuBetterAuth factory, self-registered when auth.ts is evaluated.

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

@@ -1,3 +1,13 @@
+import { PikkuError } from '../../errors/error-handler.js';
 import type { PikkuRawWire } from '../../types/core.types.js';
 export declare const addonMayReach: (caller: string, funcName: string) => boolean;
 export declare const addonCallerOf: (wire: PikkuRawWire) => string | undefined;
+export declare class AddonNotUsedError extends PikkuError {
+    constructor(caller: string, target: string);
+}
+/**
+ * The name an addon's call resolves to on this host, through its `uses`.
+ *
+ * knowledge: decisions/security/an-addon-may-reach-only-itself-and-the-addons-it-uses.md
+ */
+export declare const mapAddonCall: (caller: string | undefined, funcName: string) => string;

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

@@ -1,4 +1,5 @@
 import { ForbiddenError } from '../../errors/errors.js';
+import { PikkuError, addError } from '../../errors/error-handler.js';
 import { ADDON_HEADER } from '../../middleware/addon-scope-cap.js';
 import { pikkuState } from '../../pikku-state.js';
 export const addonMayReach = (caller, funcName) => {
@@ -19,3 +20,31 @@ export const addonCallerOf = (wire) => {
     }
     return name;
 };
+export class AddonNotUsedError extends PikkuError {
+    constructor(caller, target) {
+        super(`Addon '${caller}' called '${target}' but does not list it in its wireAddon 'uses'.`);
+    }
+}
+addError(AddonNotUsedError, {
+    status: 403,
+    message: 'Addon called another addon it does not use.',
+});
+/**
+ * The name an addon's call resolves to on this host, through its `uses`.
+ *
+ * knowledge: decisions/security/an-addon-may-reach-only-itself-and-the-addons-it-uses.md
+ */
+export const mapAddonCall = (caller, funcName) => {
+    if (!caller)
+        return funcName;
+    const colon = funcName.indexOf(':');
+    if (colon === -1)
+        return funcName;
+    const prefix = funcName.slice(0, colon);
+    if (prefix === caller)
+        return funcName;
+    const mapped = pikkuState(null, 'addons', 'packages').get(caller)?.uses?.[prefix];
+    if (mapped)
+        return `${mapped}${funcName.slice(colon)}`;
+    throw new AddonNotUsedError(caller, funcName);
+};

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/define-plugin.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Where an addon screen shows in Studio's navigation. Leave it out and the
+ * screen is routed but not listed.
+ */
+export type StudioNav = {
+    area: 'rail' | 'team' | 'project' | 'account';
+    /** The icon's name. */
+    icon: string;
+    order: number;
+    /** Names a function of the addon that returns a count shown on the entry. */
+    badge?: string;
+};
+type StudioScreenBase = {
+    /** The route path, under the prefix its `scope` gives it. */
+    path: string;
+    /** A message key in the addon's catalog, `messages/{locale}.json`. It is also the nav label. */
+    title: string;
+    nav?: StudioNav;
+    /** Takes over the core screen at the same path. Only first-party addons may use it. */
+    replaces?: boolean;
+    /** `'bare'` renders the screen without the shell. */
+    layout?: 'bare';
+    /** Hides the screen and its nav for viewers without access. The addon's functions must enforce the same scopes: hiding a screen is not access control. */
+    scopes?: string[];
+} & ({
+    /** `'studio'` gives `/<path>`, `'team'` gives `/<team>/<path>`. */
+    scope: 'studio' | 'team';
+    needsApp?: never;
+} | {
+    /** `/<team>/<project>[/<target>]/<path>`. */
+    scope: 'project';
+    /** The screen needs the project's app running. Defaults to `false`. */
+    needsApp?: boolean;
+});
+/** A screen rendered by the host from the addon's source. */
+export type StudioComponentScreen = StudioScreenBase & {
+    component: () => Promise<{
+        default: unknown;
+    }>;
+};
+/** A static program the host serves in a sandboxed iframe. */
+export type StudioAppScreen = StudioScreenBase & {
+    /** Directory of the built program, relative to the addon package. */
+    app: string;
+};
+/** 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 `definePlugin`: the addon's title, a message key, and its screens. */
+export type StudioManifest = {
+    title: string;
+    screens: StudioScreen[];
+};
+/**
+ * Declares the screens and nav an addon brings to Pikku Studio. Read
+ * statically by `pikku all`, so every field must be a literal. Titles are
+ * message keys in the addon's own catalog, `messages/{locale}.json`: a key
+ * missing from `messages/en.json` fails the build.
+ */
+export declare const definePlugin: (manifest: StudioManifest) => StudioManifest;
+/** @deprecated Renamed to `definePlugin`. */
+export declare const pikkuStudio: typeof definePlugin;
+export {};

package/dist/wirings/addon/define-plugin.js

@@ -0,0 +1,9 @@
+/**
+ * Declares the screens and nav an addon brings to Pikku Studio. Read
+ * statically by `pikku all`, so every field must be a literal. Titles are
+ * message keys in the addon's own catalog, `messages/{locale}.json`: a key
+ * missing from `messages/en.json` fails the build.
+ */
+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 { defineScreens } from './define-screens.js';
-export type { ScreensManifest, AddonScreen, AddonComponentScreen, AddonAppScreen, } from './define-screens.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 { defineScreens } from './define-screens.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,18 +46,22 @@ 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 `defineScreens`) in the host under
-     * `/addons/<name>`. Without it the addon's screens are ignored. The package
-     * must declare at least one, or `pikku all` rejects the wiring.
+     * 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.
      */
     ui?: boolean;
     /** Required of every function in the addon, on top of the function's own. */
     scopes?: string[];
     /**
-     * The other addons this one may call, as `{ '<package>': '<name>' }`: the
-     * package it was written against, and the name that package is wired under
-     * in this app. The addon calls `'<package>:<function>'`; anything it did not
-     * list is refused, whatever else the app has wired.
+     * The other addons this one may call, as `{ '<alias>': '<name>' }`: the name
+     * the addon calls another by, and the name that addon is wired under in this
+     * app — by `wireAddon` or `wireRemoteAddon`, either serves. The alias is the
+     * one the addon's package.json declares under `pikku.uses`
+     * (`{ "stripe": "@acme/addon-stripe@^1.0.0" }`), or, for an addon that lists
+     * plain names, the package name itself. The addon calls
+     * `'<alias>:<function>'`; anything it did not declare, or this app did not
+     * map, is refused, whatever else the app has wired.
      */
     uses?: Record<string, string>;
     /** Points a secret the addon reads at a different key in this deployment, so two instances can hold different credentials. */
@@ -96,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/dist/wirings/agent/agent-rpc.js

@@ -1,4 +1,5 @@
 import { pikkuState } from '../../pikku-state.js';
+import { mapAddonCall } from '../addon/addon-reach.js';
 import { runAgent, resumeAgentSync } from './agent-runner.js';
 import { streamAgent, resumeAgent, interruptAgent } from './agent-stream.js';
 import { wrapChannelWithAGUI } from './agent-agui.js';
@@ -31,10 +32,10 @@ export const createAgentRPC = (wire, options) => {
         }),
     });
     return {
-        run: async (agentName, input) => asRunResult(await runAgent(agentName, input, params())),
+        run: async (agentName, input) => asRunResult(await runAgent(mapAddonCall(wire.addonNamespace, agentName), input, params())),
         stream: async (agentName, input, streamOptions) => {
             let currentRunId;
-            await streamAgent(agentName, input, wrapChannelWithAGUI(streamingChannel(), {
+            await streamAgent(mapAddonCall(wire.addonNamespace, agentName), input, wrapChannelWithAGUI(streamingChannel(), {
                 threadId: input.threadId,
                 getRunId: () => currentRunId,
             }), params(), undefined, {
@@ -49,7 +50,9 @@ export const createAgentRPC = (wire, options) => {
             await resumeAgent({ runId, ...input }, wrapChannelWithAGUI(streamingChannel(), { runId }), params(), streamOptions);
         },
         interrupt: async (runId, reason) => interruptAgent({ runId, ...(reason ? { reason } : {}) }, { sessionService: options.sessionService }),
-        approve: async (runId, approvals, expectedAgentName) => asRunResult(await resumeAgentSync(runId, approvals, { sessionService: options.sessionService }, expectedAgentName)),
+        approve: async (runId, approvals, expectedAgentName) => asRunResult(await resumeAgentSync(runId, approvals, { sessionService: options.sessionService }, expectedAgentName === undefined
+            ? undefined
+            : mapAddonCall(wire.addonNamespace, expectedAgentName))),
     };
 };
 /**

package/dist/wirings/rpc/rpc-runner.d.ts

@@ -1,3 +1,4 @@
+import { AddonNotUsedError } from '../addon/addon-reach.js';
 import type { CoreServices, PikkuRawWire } from '../../types/core.types.js';
 import type { SessionService } from '../../services/user-session-service.js';
 import type { CoreUserSession } from '../../types/core.types.js';
@@ -29,9 +30,7 @@ export declare class RemoteAddonFailedError extends PikkuError {
 export declare class RemoteAddonTimeoutError extends PikkuError {
     constructor(namespace: string, fnName: string, timeoutMs: number);
 }
-export declare class AddonNotUsedError extends PikkuError {
-    constructor(caller: string, target: string);
-}
+export { AddonNotUsedError };
 export declare const resolveNamespace: (namespacedFunction: string) => ResolvedFunction | null;
 export declare class ContextAwareRPCService {
     private services;

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

@@ -1,4 +1,4 @@
-import { addonCallerOf, addonMayReach } from '../addon/addon-reach.js';
+import { AddonNotUsedError, addonCallerOf, addonMayReach, mapAddonCall, } from '../addon/addon-reach.js';
 import { forwardStepName, isCompensationStepName, } from '../../compensation-name.js';
 import { addonInstanceForNamespace } from '../addon/addon-runner.js';
 import { isAddonFunctionExposed } from '../addon/wire-addon.js';
@@ -166,15 +166,7 @@ const remoteAddonResponseError = async (res, namespace, fnName, logger) => {
     logger.error(`Remote addon '${namespace}:${fnName}' answered ${res.status}: ${body.slice(0, 1000)}`);
     return new RemoteAddonFailedError(namespace, fnName);
 };
-export class AddonNotUsedError extends PikkuError {
-    constructor(caller, target) {
-        super(`Addon '${caller}' called '${target}' but does not list it in its wireAddon 'uses'.`);
-    }
-}
-addError(AddonNotUsedError, {
-    status: 403,
-    message: 'Addon called another addon it does not use.',
-});
+export { AddonNotUsedError };
 export const resolveNamespace = (namespacedFunction) => {
     const colonIndex = namespacedFunction.indexOf(':');
     if (colonIndex === -1) {
@@ -367,18 +359,7 @@ export class ContextAwareRPCService {
         });
     }
     mapUsedAddon(funcName) {
-        const caller = this.wire.addonNamespace;
-        if (!caller)
-            return funcName;
-        const colon = funcName.indexOf(':');
-        const prefix = funcName.slice(0, colon);
-        if (prefix === caller)
-            return funcName;
-        const uses = pikkuState(null, 'addons', 'packages').get(caller)?.uses;
-        const mapped = uses?.[prefix];
-        if (mapped)
-            return `${mapped}${funcName.slice(colon)}`;
-        throw new AddonNotUsedError(caller, funcName);
+        return mapAddonCall(this.wire.addonNamespace, funcName);
     }
     /**
      * Resolution half of an addon RPC call: never executes anything, so an

package/dist/wirings/workflow/graph/graph-runner.js

@@ -737,7 +737,7 @@ async function invokeGraphNodeRpc(workflowService, rpcService, runId, stepId, no
 export async function executeGraphStep(workflowService, rpcService, runId, stepId, nodeId, rpcName, data, graphName) {
     try {
         let result;
-        const subWorkflowMeta = pikkuState(null, 'workflows', 'meta')[rpcName];
+        const subWorkflowMeta = getWorkflowMeta(rpcName);
         const agentMeta = subWorkflowMeta
             ? undefined
             : pikkuState(null, 'agent', 'agentsMeta')[rpcName];
@@ -801,7 +801,7 @@ async function executeGraphNodeInline(workflowService, rpcService, runId, graphN
     await workflowService.setStepRunning(stepState.stepId);
     try {
         let result;
-        const subWorkflowMeta = pikkuState(null, 'workflows', 'meta')[rpcName];
+        const subWorkflowMeta = getWorkflowMeta(rpcName);
         const agentMeta = subWorkflowMeta
             ? undefined
             : pikkuState(null, 'agent', 'agentsMeta')[rpcName];

package/dist/wirings/workflow/pikku-workflow-service.js

@@ -691,8 +691,7 @@ export class PikkuWorkflowService {
             if (!run) {
                 throw new Error(`Workflow run not found: ${runId}`);
             }
-            const meta = pikkuState(null, 'workflows', 'meta');
-            const workflowMeta = meta[run.workflow];
+            const workflowMeta = resolveWorkflowMeta(run.workflow)?.meta;
             const isGraphWorkflow = workflowMeta?.source === 'graph';
             let graphNodeId;
             if (isGraphWorkflow && workflowMeta?.nodes) {
@@ -709,7 +708,7 @@ export class PikkuWorkflowService {
                 result = await executeGraphStep(this, rpcService, runId, stepState.stepId, graphNodeId, workflowMeta.nodes[graphNodeId].rpcName, data, run.workflow);
             }
             else {
-                if (meta[rpcName]) {
+                if (resolveWorkflowMeta(rpcName)) {
                     result = await startQueuedChildStep({
                         startWorkflow: (...args) => this.startWorkflow(...args),
                         setStepChildRunId: (...args) => this.setStepChildRunId(...args),
@@ -860,7 +859,7 @@ export class PikkuWorkflowService {
             if (resolvedStepOptions.virtualUser) {
                 return resolvedStepOptions.virtualUser.invoke(rpcName, data);
             }
-            if (pikkuState(null, 'workflows', 'meta')[rpcName]) {
+            if (resolveWorkflowMeta(rpcName)) {
                 return runInlineChildStep({
                     startWorkflow: (...args) => this.startWorkflow(...args),
                     setStepChildRunId: (...args) => this.setStepChildRunId(...args),

package/dist/wirings/workflow/workflow-compensation.js

@@ -2,6 +2,7 @@ import { DEFAULT_STEP_RETRIES, NO_COMPENSATE_STATE_PREFIX, WORKFLOW_TERMINAL_STA
 import { pikkuState } from '../../pikku-state.js';
 import { resolveNamespace } from '../rpc/rpc-runner.js';
 import { runningStepLease } from './workflow-step-lease.js';
+import { isWorkflowName } from './workflow-meta-resolver.js';
 import { planUnwind } from './workflow-unwind-plan.js';
 const ENTERABLE = new Set([
     'running',
@@ -177,8 +178,7 @@ export const functionHasCompensation = (rpcName) => {
             ?.compensate === true
         : false;
 };
-export const isChildWorkflowRecord = (record) => !!record.rpcName &&
-    pikkuState(null, 'workflows', 'meta')[record.rpcName] !== undefined;
+export const isChildWorkflowRecord = (record) => !!record.rpcName && isWorkflowName(record.rpcName);
 export const recordHasCompensation = (record) => isChildWorkflowRecord(record)
     ? !!record.childRunId
     : !!record.rpcName && functionHasCompensation(record.rpcName);

package/dist/wirings/workflow/workflow-meta-resolver.d.ts

@@ -9,3 +9,8 @@ export type ResolvedWorkflowMeta = {
  * `namespace:name` form — against the addon package that claims the namespace.
  */
 export declare const resolveWorkflowMeta: (name: string) => ResolvedWorkflowMeta | null;
+/**
+ * Whether a step's rpcName names a workflow — the app's, or an addon's by
+ * `namespace:name` — and so starts a child run rather than an RPC.
+ */
+export declare const isWorkflowName: (name: string) => boolean;

package/dist/wirings/workflow/workflow-meta-resolver.js

@@ -29,3 +29,8 @@ export const resolveWorkflowMeta = (name) => {
         resolvedName: localName,
     };
 };
+/**
+ * Whether a step's rpcName names a workflow — the app's, or an addon's by
+ * `namespace:name` — and so starts a child run rather than an RPC.
+ */
+export const isWorkflowName = (name) => resolveWorkflowMeta(name) !== null;

package/dist/wirings/workflow/workflow-queue-routing.js

@@ -1,6 +1,7 @@
 import { getSingletonServices, pikkuState } from '../../pikku-state.js';
 import { getDurationInMilliseconds } from '../../time-utils.js';
 import { DEFAULT_STEP_RETRIES, forwardStepName } from './workflow-constants.js';
+import { isWorkflowName } from './workflow-meta-resolver.js';
 const toKebab = (s) => s.replace(/([a-z0-9])([A-Z])/g, '$1-$2').toLowerCase();
 export const resolveWorkflowConfig = () => {
     const workflow = getSingletonServices().config?.workflow;
@@ -54,8 +55,7 @@ export const stepDispatchTarget = async (rpcName, stepName, parentIsInline) => {
         }
         return 'queue';
     }
-    const isWorkflow = pikkuState(null, 'workflows', 'meta')[rpcName] !== undefined;
-    if (!isWorkflow || !hasQueue) {
+    if (!isWorkflowName(rpcName) || !hasQueue) {
         return 'inline';
     }
     return (await parentIsInline()) ? 'inline' : 'queue';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/core",
-  "version": "0.12.146",
+  "version": "0.12.148",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/pikkujs/pikku.git",
@@ -24,6 +24,7 @@
   },
   "sideEffects": [
     "./dist/errors/errors.js",
+    "./dist/wirings/addon/addon-reach.js",
     "./dist/wirings/addon/remote-addon-auth.js",
     "./dist/wirings/agent/agent-rpc.js",
     "./dist/wirings/rpc/rpc-runner.js",
@@ -92,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",
@@ -118,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"

package/dist/wirings/addon/define-screens.d.ts

@@ -1,34 +0,0 @@
-type AddonScreenBase = {
-    /** Where the screen mounts under the addon, e.g. `/` or `/:id`. */
-    path: string;
-    title: string;
-    /** Lists the screen in the host's navigation. */
-    nav?: boolean;
-    /** Required of the viewer to see the screen. The addon's functions must enforce the same scopes: hiding a screen is not access control. */
-    scopes?: string[];
-};
-/** A screen rendered by the host from the addon's source. */
-export type AddonComponentScreen = AddonScreenBase & {
-    component: () => Promise<{
-        default: unknown;
-    }>;
-};
-/** A static program the host serves in a sandboxed iframe. */
-export type AddonAppScreen = AddonScreenBase & {
-    /** Directory of the built program, relative to the addon package. */
-    app: string;
-};
-/** One screen an addon ships: either a component the host renders or a static app it serves in a sandboxed iframe. */
-export type AddonScreen = AddonComponentScreen | AddonAppScreen;
-/** The manifest passed to `defineScreens`: the addon's title, optional icon and its screens. */
-export type ScreensManifest = {
-    title: string;
-    icon?: string;
-    screens: AddonScreen[];
-};
-/**
- * Declares the screens an addon ships, which the host mounts when it is wired
- * with `ui: true`. Read statically by `pikku all`, so `path`, `title`, `nav`, `scopes` and `app` must be literals.
- */
-export declare const defineScreens: (manifest: ScreensManifest) => ScreensManifest;
-export {};

package/dist/wirings/addon/define-screens.js

@@ -1,5 +0,0 @@
-/**
- * Declares the screens an addon ships, which the host mounts when it is wired
- * with `ui: true`. Read statically by `pikku all`, so `path`, `title`, `nav`, `scopes` and `app` must be literals.
- */
-export const defineScreens = (manifest) => manifest;