@pikku/core 0.12.145 → 0.12.147

package/dist/crypto-utils.d.ts

@@ -24,10 +24,10 @@ export declare const encryptJSON: (secret: string, value: unknown) => Promise<st
  */
 export declare const decryptJSON: <T>(secret: string, token: string) => Promise<T>;
 /**
- * Namespaces the remote-RPC session key so the same deployment secret used for
+ * Namespaces the mesh-RPC session key so the same deployment secret used for
  * another purpose derives a different key. See knowledge/crypto.md.
  */
-export declare const REMOTE_SESSION_INFO = "pikku:remote-session";
+export declare const MESH_SESSION_INFO = "pikku:mesh-session";
 /** Shortest key material, in characters, that the `*WithKeyMaterial` helpers accept. */
 export declare const MIN_KEY_MATERIAL_LENGTH = 32;
 /**
@@ -44,7 +44,7 @@ export declare const assertStrongKeyMaterial: (name: string, keyMaterial: string
  * high-entropy key material by HKDF-SHA256, with a fresh random salt per call.
  *
  * `info` domain-separates the derived key, so the same deployment secret used for
- * two purposes (e.g. {@link REMOTE_SESSION_INFO}) yields two unrelated keys.
+ * two purposes (e.g. {@link MESH_SESSION_INFO}) yields two unrelated keys.
  *
  * @param name - The key material's name, for the weak-key error.
  * @param keyMaterial - At least {@link MIN_KEY_MATERIAL_LENGTH} characters.

package/dist/crypto-utils.js

@@ -109,10 +109,10 @@ export const decryptJSON = async (secret, token) => {
     return JSON.parse(decoder.decode(new Uint8Array(decrypted)));
 };
 /**
- * Namespaces the remote-RPC session key so the same deployment secret used for
+ * Namespaces the mesh-RPC session key so the same deployment secret used for
  * another purpose derives a different key. See knowledge/crypto.md.
  */
-export const REMOTE_SESSION_INFO = 'pikku:remote-session';
+export const MESH_SESSION_INFO = 'pikku:mesh-session';
 /** Shortest key material, in characters, that the `*WithKeyMaterial` helpers accept. */
 export const MIN_KEY_MATERIAL_LENGTH = 32;
 /**
@@ -143,7 +143,7 @@ const expandKeyMaterial = async (keyMaterial, info, salt) => {
  * high-entropy key material by HKDF-SHA256, with a fresh random salt per call.
  *
  * `info` domain-separates the derived key, so the same deployment secret used for
- * two purposes (e.g. {@link REMOTE_SESSION_INFO}) yields two unrelated keys.
+ * two purposes (e.g. {@link MESH_SESSION_INFO}) yields two unrelated keys.
  *
  * @param name - The key material's name, for the weak-key error.
  * @param keyMaterial - At least {@link MIN_KEY_MATERIAL_LENGTH} characters.

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

@@ -165,7 +165,7 @@ export type FunctionMeta = FunctionRuntimeMeta & Partial<{
     exportedName: string;
     /**
      * RPC names this function's own body calls by literal name through
-     * `rpc.invoke(...)` / `rpc.remote(...)`. The deploy planner binds the
+     * `rpc.invoke(...)` / `rpc.mesh(...)`. The deploy planner binds the
      * function's unit to each callee's unit from this; a call with a computed
      * name is not listed, and is warned about instead.
      */

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/{remote.d.ts → mesh.d.ts}

@@ -2,7 +2,7 @@ import type { JWTService } from './services/jwt-service.js';
 import type { SecretService } from './services/secret-service.js';
 /**
  * Authorization headers carrying a JWT-signed session and traceId for
- * `pikkuRemoteAuthMiddleware` on the receiving end. Used by every deployment
+ * `pikkuMeshAuthMiddleware` on the receiving end. Used by every deployment
  * service regardless of transport (HTTP, Lambda Invoke, service bindings).
  */
-export declare function buildRemoteHeaders(jwt: JWTService | undefined, secrets: SecretService | undefined, funcName: string, session?: unknown, traceId?: string): Promise<Record<string, string>>;
+export declare function buildMeshHeaders(jwt: JWTService | undefined, secrets: SecretService | undefined, funcName: string, session?: unknown, traceId?: string): Promise<Record<string, string>>;

package/dist/{remote.js → mesh.js}

@@ -1,43 +1,43 @@
-import { assertStrongKeyMaterial, encryptWithKeyMaterial, REMOTE_SESSION_INFO, } from './crypto-utils.js';
+import { assertStrongKeyMaterial, encryptWithKeyMaterial, MESH_SESSION_INFO, } from './crypto-utils.js';
 /**
- * An unset secret means remote auth is not configured, so the call goes out
+ * An unset secret means mesh auth is not configured, so the call goes out
  * unauthenticated. A secrets backend that fails is a different thing: sending
  * the call anyway would only earn a 401 from the peer with no hint why.
  */
-const readRemoteSecret = async (secrets) => {
+const readMeshSecret = async (secrets) => {
     if (!secrets) {
         return undefined;
     }
     try {
-        if (!(await secrets.hasSecret('PIKKU_REMOTE_SECRET'))) {
+        if (!(await secrets.hasSecret('PIKKU_MESH_SECRET'))) {
             return undefined;
         }
-        return (await secrets.getSecret('PIKKU_REMOTE_SECRET')).reveal();
+        return (await secrets.getSecret('PIKKU_MESH_SECRET')).reveal();
     }
     catch (cause) {
-        throw new Error('Could not read PIKKU_REMOTE_SECRET from the secrets service; refusing to send an unauthenticated remote call', { cause });
+        throw new Error('Could not read PIKKU_MESH_SECRET from the secrets service; refusing to send an unauthenticated mesh call', { cause });
     }
 };
 /**
  * Authorization headers carrying a JWT-signed session and traceId for
- * `pikkuRemoteAuthMiddleware` on the receiving end. Used by every deployment
+ * `pikkuMeshAuthMiddleware` on the receiving end. Used by every deployment
  * service regardless of transport (HTTP, Lambda Invoke, service bindings).
  */
-export async function buildRemoteHeaders(jwt, secrets, funcName, session, traceId) {
+export async function buildMeshHeaders(jwt, secrets, funcName, session, traceId) {
     const headers = {
         'content-type': 'application/json',
         ...(traceId && { 'x-request-id': traceId }),
     };
-    const secret = await readRemoteSecret(secrets);
+    const secret = await readMeshSecret(secrets);
     if (secret && jwt) {
-        assertStrongKeyMaterial('PIKKU_REMOTE_SECRET', secret);
+        assertStrongKeyMaterial('PIKKU_MESH_SECRET', secret);
         const sessionEnc = session
-            ? await encryptWithKeyMaterial('PIKKU_REMOTE_SECRET', secret, REMOTE_SESSION_INFO, {
+            ? await encryptWithKeyMaterial('PIKKU_MESH_SECRET', secret, MESH_SESSION_INFO, {
                 session,
             })
             : undefined;
         const token = await jwt.encode({ value: 5, unit: 'minute' }, {
-            aud: 'pikku-remote',
+            aud: 'pikku-mesh',
             fn: funcName,
             iat: Math.floor(Date.now() / 1000),
             session: sessionEnc,

package/dist/middleware/index.d.ts

@@ -1,9 +1,9 @@
 export { authAPIKey } from './auth-apikey.js';
 export { authCookie } from './auth-cookie.js';
 export { authBearer } from './auth-bearer.js';
-export { addonScopeCap, ADDON_HEADER, } from './addon-scope-cap.js';
+export { addonScopeCap, ADDON_HEADER } from './addon-scope-cap.js';
 export { remoteJobsSecret } from './remote-jobs-secret.js';
-export { pikkuRemoteAuthMiddleware } from './remote-auth.js';
+export { pikkuMeshAuthMiddleware } from './mesh-auth.js';
 export { cors } from './cors.js';
 export { requireOrigin, isAllowedOrigin, toOrigin } from './require-origin.js';
 export { telemetryOuter, telemetryInner } from './telemetry.js';

package/dist/middleware/index.js

@@ -1,9 +1,9 @@
 export { authAPIKey } from './auth-apikey.js';
 export { authCookie } from './auth-cookie.js';
 export { authBearer } from './auth-bearer.js';
-export { addonScopeCap, ADDON_HEADER, } from './addon-scope-cap.js';
+export { addonScopeCap, ADDON_HEADER } from './addon-scope-cap.js';
 export { remoteJobsSecret } from './remote-jobs-secret.js';
-export { pikkuRemoteAuthMiddleware } from './remote-auth.js';
+export { pikkuMeshAuthMiddleware } from './mesh-auth.js';
 export { cors } from './cors.js';
 export { requireOrigin, isAllowedOrigin, toOrigin } from './require-origin.js';
 export { telemetryOuter, telemetryInner } from './telemetry.js';

package/dist/middleware/{remote-auth.d.ts → mesh-auth.d.ts}

@@ -1,19 +1,19 @@
 /**
  * Authenticates calls between deployments of the same app, on the generated
- * remote-RPC route. Once `PIKKU_REMOTE_SECRET` is set it requires a
- * `Bearer` JWT with audience `pikku-remote`; a token bound to a function (`fn`)
- * is only accepted on that function's `/remote/rpc/<fn>` path, and any session
+ * mesh-RPC route. Once `PIKKU_MESH_SECRET` is set it requires a
+ * `Bearer` JWT with audience `pikku-mesh`; a token bound to a function (`fn`)
+ * is only accepted on that function's `/mesh/rpc/<fn>` path, and any session
  * it carries is decrypted with the secret and set on the wire.
  *
- * Without the secret it lets non-remote paths through and refuses
- * `/remote/rpc/*`, so the remote surface fails closed.
+ * Without the secret it lets non-mesh paths through and refuses
+ * `/mesh/rpc/*`, so the mesh surface fails closed.
  *
  * @throws {UnauthorizedError} On a missing, malformed, mis-addressed or
  * undecryptable token.
  * @throws {WeakKeyMaterialError} When the secret is too short to use.
  * @throws {Error} When the secret is set but no JWT service is configured.
  */
-export declare const pikkuRemoteAuthMiddleware: import("./middleware.types.js").CorePikkuMiddleware<import("../types/core.types.js").CoreSingletonServices<{
+export declare const pikkuMeshAuthMiddleware: import("./middleware.types.js").CorePikkuMiddleware<import("../types/core.types.js").CoreSingletonServices<{
     logLevel?: import("../services/logger.js").LogLevel;
     secrets?: {
         requireAllowedHosts?: boolean;

package/dist/middleware/{remote-auth.js → mesh-auth.js}

@@ -1,47 +1,47 @@
 import { UnauthorizedError } from '../errors/errors.js';
 import { pikkuMiddleware } from './middleware-factories.js';
-import { assertStrongKeyMaterial, decryptWithKeyMaterial, REMOTE_SESSION_INFO, } from '../crypto-utils.js';
-const REMOTE_RPC_PREFIX = '/remote/rpc/';
+import { assertStrongKeyMaterial, decryptWithKeyMaterial, MESH_SESSION_INFO, } from '../crypto-utils.js';
+const MESH_RPC_PREFIX = '/mesh/rpc/';
 /**
- * Whether this request targets the remote-RPC surface. Compared case-insensitively
+ * Whether this request targets the mesh-RPC surface. Compared case-insensitively
  * because the router matches routes that way (path-to-regexp defaults to
- * `sensitive: false`), so `/Remote/RPC/fn` reaches the same handler as
- * `/remote/rpc/fn`. A case-sensitive check here let a case-varied path slip
+ * `sensitive: false`), so `/Mesh/RPC/fn` reaches the same handler as
+ * `/mesh/rpc/fn`. A case-sensitive check here let a case-varied path slip
  * past the trust gate and the token's `fn` binding while still being dispatched.
  */
-const isRemoteRpcPath = (path) => path.toLowerCase().startsWith(REMOTE_RPC_PREFIX);
+const isMeshRpcPath = (path) => path.toLowerCase().startsWith(MESH_RPC_PREFIX);
 /**
  * Authenticates calls between deployments of the same app, on the generated
- * remote-RPC route. Once `PIKKU_REMOTE_SECRET` is set it requires a
- * `Bearer` JWT with audience `pikku-remote`; a token bound to a function (`fn`)
- * is only accepted on that function's `/remote/rpc/<fn>` path, and any session
+ * mesh-RPC route. Once `PIKKU_MESH_SECRET` is set it requires a
+ * `Bearer` JWT with audience `pikku-mesh`; a token bound to a function (`fn`)
+ * is only accepted on that function's `/mesh/rpc/<fn>` path, and any session
  * it carries is decrypted with the secret and set on the wire.
  *
- * Without the secret it lets non-remote paths through and refuses
- * `/remote/rpc/*`, so the remote surface fails closed.
+ * Without the secret it lets non-mesh paths through and refuses
+ * `/mesh/rpc/*`, so the mesh surface fails closed.
  *
  * @throws {UnauthorizedError} On a missing, malformed, mis-addressed or
  * undecryptable token.
  * @throws {WeakKeyMaterialError} When the secret is too short to use.
  * @throws {Error} When the secret is set but no JWT service is configured.
  */
-export const pikkuRemoteAuthMiddleware = pikkuMiddleware(async ({ secrets, jwt }, { http, setInitialSession }, next) => {
+export const pikkuMeshAuthMiddleware = pikkuMiddleware(async ({ secrets, jwt }, { http, setInitialSession }, next) => {
     if (!http?.request || !secrets) {
         return next();
     }
     let secret;
     try {
-        secret = (await secrets.getSecret('PIKKU_REMOTE_SECRET')).reveal();
+        secret = (await secrets.getSecret('PIKKU_MESH_SECRET')).reveal();
     }
     catch {
-        if (isRemoteRpcPath(http.request.path())) {
+        if (isMeshRpcPath(http.request.path())) {
             throw new UnauthorizedError();
         }
         return next();
     }
-    assertStrongKeyMaterial('PIKKU_REMOTE_SECRET', secret);
+    assertStrongKeyMaterial('PIKKU_MESH_SECRET', secret);
     if (!jwt) {
-        throw new Error('PIKKU_REMOTE_SECRET set but JWT service missing');
+        throw new Error('PIKKU_MESH_SECRET set but JWT service missing');
     }
     const authHeader = http.request.header('authorization') ||
         http.request.header('Authorization');
@@ -59,20 +59,20 @@ export const pikkuRemoteAuthMiddleware = pikkuMiddleware(async ({ secrets, jwt }
     catch {
         throw new UnauthorizedError();
     }
-    if (payload?.aud !== 'pikku-remote') {
+    if (payload?.aud !== 'pikku-mesh') {
         throw new UnauthorizedError();
     }
-    if (payload?.fn && isRemoteRpcPath(http.request.path())) {
+    if (payload?.fn && isMeshRpcPath(http.request.path())) {
         // The prefix length is the same in any case, so slicing the raw path
         // keeps the requested function name in its original case for the compare.
-        const fn = decodeURIComponent(http.request.path().slice(REMOTE_RPC_PREFIX.length));
+        const fn = decodeURIComponent(http.request.path().slice(MESH_RPC_PREFIX.length));
         if (fn && payload.fn !== fn) {
             throw new UnauthorizedError();
         }
     }
     if (payload?.session) {
         try {
-            const decrypted = await decryptWithKeyMaterial('PIKKU_REMOTE_SECRET', secret, REMOTE_SESSION_INFO, payload.session);
+            const decrypted = await decryptWithKeyMaterial('PIKKU_MESH_SECRET', secret, MESH_SESSION_INFO, payload.session);
             if (decrypted?.session && setInitialSession) {
                 setInitialSession(decrypted.session);
             }

package/dist/types/core.types.d.ts

@@ -255,16 +255,16 @@ export type PikkuWire<In = unknown, Out = unknown, HasInitialSession extends boo
      * sets it; services that log fall back to the singleton logger.
      */
     logger: Logger;
-    /** Trace ID for distributed tracing — propagated across remote RPC calls via the x-request-id header */
+    /** Trace ID for distributed tracing — propagated across mesh RPC calls via the x-request-id header */
     traceId: string;
     functionId: string;
     addonNamespace: string;
     http: PikkuHTTP<In>;
     mcp: PikkuMCP<MCPTools>;
-    channel: [IsChannel] extends [null] ? PikkuChannel<unknown, Out, TypedRPC['remote']> : PikkuChannel<unknown, Out, TypedRPC['remote']> | undefined;
+    channel: [IsChannel] extends [null] ? PikkuChannel<unknown, Out, TypedRPC['mesh']> : PikkuChannel<unknown, Out, TypedRPC['mesh']> | undefined;
     scheduledTask: PikkuScheduledTask;
     queue: PikkuQueue;
-    cli: PikkuCLI<TypedRPC['remote']>;
+    cli: PikkuCLI<TypedRPC['mesh']>;
     workflow: TypedWorkflow;
     scenario: TypedScenario;
     virtualUsers: TScenarioVirtualUsers;

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';
@@ -42,7 +42,7 @@ export interface PikkuPackageState {
             rpcEndpoint?: string;
             auth?: boolean;
             tags?: string[];
-            /** Which functions `rpc.exposed` may call: unset/`true` keeps the addon's own `expose`, `false` none, a list exactly those */
+            /** Which functions `rpc.exposed` may call, from those the addon declared `expose: true`: `true` all of them, a list those named, unset/`false` none */
             expose?: boolean | string[];
             /** Required of every function in this package, on top of the function's own */
             scopes?: string[];
@@ -78,10 +78,14 @@ export interface PikkuPackageState {
             } | {
                 secretId: string;
             } | {
-                resolve: (services: any, wire: any) => string | Promise<string>;
+                resolve: (services: any, wire: any) => string | null | Promise<string | null>;
             };
-            /** Map consumer-facing fn name → remote fn name (wireRemoteAddon) */
+            /** Map consumer-facing base fn name → remote fn name (wireRemoteAddon); `@vN` is appended after */
             remoteName?: (fn: string) => string;
+            /** Milliseconds a remote addon call may take before it is aborted (wireRemoteAddon) */
+            remoteTimeoutMs?: number;
+            /** Extra headers sent on every call to the hosted addon (wireRemoteAddon) */
+            remoteHeaders?: (services: any, wire: any) => Record<string, string> | Promise<Record<string, string>>;
         }>;
     };
     http: {
@@ -164,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/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 { pikkuStudio } from './pikku-studio.js';
+export type { StudioManifest, StudioScreen, StudioComponentScreen, StudioAppScreen, StudioNav, } from './pikku-studio.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 { pikkuStudio } from './pikku-studio.js';
 export { wireRemoteAddon } from './wire-remote-addon.js';
 export { resolveRemoteAddonToken, RemoteAddonAuthError, } from './remote-addon-auth.js';

package/dist/wirings/addon/pikku-studio.d.ts

@@ -0,0 +1,60 @@
+/**
+ * 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 `pikkuStudio`: 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 pikkuStudio: (manifest: StudioManifest) => StudioManifest;
+export {};

package/dist/wirings/addon/pikku-studio.js

@@ -0,0 +1,7 @@
+/**
+ * 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 pikkuStudio = (manifest) => manifest;

package/dist/wirings/addon/remote-addon-auth.d.ts

@@ -10,7 +10,12 @@ export type RemoteAddonAuthBinding = {
 } | {
     secretId: string;
 } | {
-    resolve: (services: CoreServices, wire: PikkuRawWire) => string | SecretValue<string> | Promise<string | SecretValue<string>>;
+    /**
+     * `null` says this call carries no credential, for a host whose surface
+     * is public to anonymous callers. An empty or undefined token still
+     * throws, so a resolver that lost its token does not go out anonymous.
+     */
+    resolve: (services: CoreServices, wire: PikkuRawWire) => string | SecretValue<string> | null | Promise<string | SecretValue<string> | null>;
 };
 /**
  * Thrown (401) when a remote addon's token cannot be resolved: the binding needs credential
@@ -21,5 +26,8 @@ export declare class RemoteAddonAuthError extends PikkuError {
     readonly namespace: string;
     constructor(namespace: string, detail: string);
 }
-/** Returns `null` only when no auth is bound; an empty resolved token throws. */
+/**
+ * Returns `null` when no auth is bound or `resolve` answers `null`; any other
+ * empty token throws.
+ */
 export declare function resolveRemoteAddonToken(auth: RemoteAddonAuthBinding | undefined, services: CoreServices, wire: PikkuRawWire, namespace: string): Promise<string | null>;

package/dist/wirings/addon/remote-addon-auth.js

@@ -16,7 +16,10 @@ addError(RemoteAddonAuthError, {
     status: 401,
     message: 'Remote addon authentication could not be resolved.',
 });
-/** Returns `null` only when no auth is bound; an empty resolved token throws. */
+/**
+ * Returns `null` when no auth is bound or `resolve` answers `null`; any other
+ * empty token throws.
+ */
 export async function resolveRemoteAddonToken(auth, services, wire, namespace) {
     if (!auth) {
         return null;
@@ -33,6 +36,8 @@ export async function resolveRemoteAddonToken(auth, services, wire, namespace) {
     }
     else if (typeof auth.resolve === 'function') {
         token = await auth.resolve(services, wire);
+        if (token === null)
+            return null;
     }
     // The wire is where a secret is meant to end up, so unwrap it here rather
     // than at each branch — `resolve` and `getCredential` may hand one back too.

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

@@ -0,0 +1,13 @@
+/** A `wireRemoteAddon` `package` value split into the package name and the optional semver range after it. */
+export type RemoteAddonPackageSpec = {
+    /** The package name, e.g. `@pikkustudio/addon-cloud-api`. */
+    name: string;
+    /** The semver range, e.g. `^1.4.0`. Absent when the spec names only the package. */
+    range?: string;
+};
+/**
+ * Splits `@scope/name@^1.4.0` into its name and range at the last `@` after
+ * the first character, so a scope's leading `@` is never taken for the
+ * separator. Throws when either half is empty.
+ */
+export declare const parseRemoteAddonPackage: (spec: string) => RemoteAddonPackageSpec;

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

@@ -0,0 +1,21 @@
+/**
+ * Splits `@scope/name@^1.4.0` into its name and range at the last `@` after
+ * the first character, so a scope's leading `@` is never taken for the
+ * separator. Throws when either half is empty.
+ */
+export const parseRemoteAddonPackage = (spec) => {
+    const trimmed = spec.trim();
+    const at = trimmed.lastIndexOf('@');
+    if (at <= 0) {
+        if (!trimmed || trimmed === '@') {
+            throw new Error(`'${spec}' is not a package name`);
+        }
+        return { name: trimmed };
+    }
+    const name = trimmed.slice(0, at);
+    const range = trimmed.slice(at + 1).trim();
+    if (!range) {
+        throw new Error(`'${spec}' ends in '@' with no version range after it. Write '${name}@^1.0.0', or drop the '@'.`);
+    }
+    return { name, range };
+};