@pikku/inspector 0.12.109 → 0.12.111

package/dist/utils/addon-dependencies.js

@@ -0,0 +1,91 @@
+import { existsSync, readFileSync } from 'fs';
+import { dirname, join, parse } from 'path';
+import { parseRemoteAddonPackage } from './remote-addon-sdk.js';
+/** An alias becomes a namespace prefix and part of a generated type name. */
+const ALIAS = /^[A-Za-z][A-Za-z0-9_-]*$/;
+/** The names a wiring's `uses` may map: the declared aliases, or the listed names. */
+export const declaredAddonNames = (declared) => declared.form === 'list'
+    ? declared.names
+    : declared.form === 'map'
+        ? declared.dependencies.map((d) => d.alias)
+        : [];
+/** Reads the `pikku.uses` value of an addon's package.json. */
+export const parseAddonDependencies = (uses) => {
+    if (uses === undefined || uses === null)
+        return { form: 'none' };
+    if (Array.isArray(uses)) {
+        return {
+            form: 'list',
+            names: uses.filter((u) => typeof u === 'string'),
+        };
+    }
+    if (typeof uses !== 'object') {
+        return {
+            form: 'map',
+            dependencies: [],
+            invalid: [
+                `pikku.uses must be an object of { "<alias>": "<package>@<range>" }, got ${JSON.stringify(uses)}.`,
+            ],
+        };
+    }
+    const dependencies = [];
+    const invalid = [];
+    for (const [alias, spec] of Object.entries(uses)) {
+        if (!ALIAS.test(alias)) {
+            invalid.push(`pikku.uses names '${alias}', which is not a valid alias. An alias starts with a letter and holds only letters, digits, '-' and '_'.`);
+            continue;
+        }
+        if (typeof spec !== 'string') {
+            invalid.push(`pikku.uses.${alias} must be a string '<package>@<range>', got ${JSON.stringify(spec)}.`);
+            continue;
+        }
+        let parsed;
+        try {
+            parsed = parseRemoteAddonPackage(spec);
+        }
+        catch (e) {
+            invalid.push(`pikku.uses.${alias}: ${e instanceof Error ? e.message : String(e)}`);
+            continue;
+        }
+        if (!parsed.range) {
+            invalid.push(`pikku.uses.${alias} is '${spec}', which has no version range. Write '${parsed.name}@^1.0.0': the app that wires this addon is checked against it.`);
+            continue;
+        }
+        dependencies.push({ alias, package: parsed.name, range: parsed.range });
+    }
+    return { form: 'map', dependencies, invalid };
+};
+/** The `pikku.uses` an addon's package.json declares. `none` when there is no readable package.json. */
+export const readAddonDependencies = (packageDir) => {
+    let pkg;
+    try {
+        pkg = JSON.parse(readFileSync(join(packageDir, 'package.json'), 'utf-8'));
+    }
+    catch {
+        return { form: 'none' };
+    }
+    return parseAddonDependencies(pkg?.pikku?.uses);
+};
+/**
+ * The directory `packageName` is installed in, looking in `node_modules` from
+ * each of `dirs` upwards, as Node's resolution would. Null when it is not
+ * installed.
+ */
+export const findInstalledPackageDir = (dirs, packageName) => {
+    for (const start of dirs) {
+        const root = parse(start).root;
+        let dir = start;
+        while (dir) {
+            const candidate = join(dir, 'node_modules', packageName);
+            if (existsSync(join(candidate, 'package.json')))
+                return candidate;
+            if (dir === root)
+                break;
+            const parent = dirname(dir);
+            if (parent === dir)
+                break;
+            dir = parent;
+        }
+    }
+    return null;
+};

package/dist/utils/contract-hashes.js

@@ -73,7 +73,7 @@ export function buildCurrentContracts(functionsMeta, allSchemas, typesMap) {
     for (const [funcId, meta] of Object.entries(functionsMeta)) {
         // A webhook receive has no callers but its own route, so there is no
         // contract for a version to protect.
-        if (meta.remote === true || meta.webhookReceive) {
+        if (meta.webhookReceive) {
             continue;
         }
         const parsed = parseVersionedId(funcId);
@@ -253,7 +253,7 @@ export function updateManifest(existing, currentContracts) {
 export function extractContractsFromMeta(functionsMeta) {
     const result = new Map();
     for (const [funcId, meta] of Object.entries(functionsMeta)) {
-        if (meta.remote === true || meta.webhookReceive || !meta.contractHash) {
+        if (meta.webhookReceive || !meta.contractHash) {
             continue;
         }
         const parsed = parseVersionedId(funcId);

package/dist/utils/find-unused-functions.d.ts

@@ -0,0 +1,20 @@
+import type { InspectorState } from '../types.js';
+export interface UnusedFunction {
+    pikkuFuncId: string;
+    name?: string;
+    sourceFile?: string;
+}
+/**
+ * The app's own functions that nothing uses: not wired to any transport, not
+ * exposed, published or offered to MCP, and not called by name. Addon
+ * functions are never judged: an addon project's own functions are all addon
+ * functions, and a consumer's state holds no addon functions in
+ * `functions.meta`. Neither are scenarios, inline wiring functions or disabled
+ * functions. A workflow is a function like any other: it is used when it is
+ * wired, exposed, or started by a literal name — `rpc.startWorkflow`,
+ * `workflowService.startWorkflow` / `runToCompletion`, `rpc.invoke`, another
+ * workflow's step, or the generated client helpers.
+ */
+export declare const findUnusedFunctions: (state: InspectorState, { addon }?: {
+    addon?: boolean;
+}) => UnusedFunction[];

package/dist/utils/find-unused-functions.js

@@ -0,0 +1,132 @@
+/** Scenarios and their steps are run by the scenario runner, never wired or called. */
+const RUN_BY_SCENARIOS = new Set([
+    'pikkuScenario',
+    'pikkuScenarioStep',
+    'pikkuPlatformScenarioStep',
+    'pikkuAddonScenarioStep',
+]);
+/** Sections that describe functions rather than use them. */
+const NOT_USES = new Set([
+    'functions',
+    'schemas',
+    'schemaLookup',
+    'serviceAggregation',
+    'nodes',
+    'resolvedIOTypes',
+    'addonFunctions',
+    'remoteAddonFunctions',
+    'program',
+    'stats',
+]);
+/** Keys under which a wiring names the function it runs. */
+const FUNCTION_KEYS = new Set(['pikkuFuncId', 'rpcName', 'receive']);
+const collectUses = (value, into, seen, key) => {
+    if (typeof value === 'string') {
+        if (key && FUNCTION_KEYS.has(key))
+            into.add(value);
+        return;
+    }
+    if (!value || typeof value !== 'object' || seen.has(value))
+        return;
+    seen.add(value);
+    if (value instanceof Map) {
+        for (const child of value.values())
+            collectUses(child, into, seen);
+        return;
+    }
+    if (value instanceof Set)
+        return;
+    if (Array.isArray(value)) {
+        for (const child of value) {
+            if (key === 'tools' && typeof child === 'string')
+                into.add(child);
+            else
+                collectUses(child, into, seen);
+        }
+        return;
+    }
+    // Only plain data: the TypeScript inspector's state also holds compiler
+    // objects (types, nodes) whose getters throw when read.
+    const proto = Object.getPrototypeOf(value);
+    if (proto !== Object.prototype && proto !== null)
+        return;
+    for (const [childKey, child] of Object.entries(value)) {
+        collectUses(child, into, seen, childKey);
+    }
+};
+/**
+ * The app's own functions that nothing uses: not wired to any transport, not
+ * exposed, published or offered to MCP, and not called by name. Addon
+ * functions are never judged: an addon project's own functions are all addon
+ * functions, and a consumer's state holds no addon functions in
+ * `functions.meta`. Neither are scenarios, inline wiring functions or disabled
+ * functions. A workflow is a function like any other: it is used when it is
+ * wired, exposed, or started by a literal name — `rpc.startWorkflow`,
+ * `workflowService.startWorkflow` / `runToCompletion`, `rpc.invoke`, another
+ * workflow's step, or the generated client helpers.
+ */
+export const findUnusedFunctions = (state, { addon = false } = {}) => {
+    if (addon)
+        return [];
+    const uses = new Set(state.serviceAggregation.usedFunctions);
+    for (const name of state.rpc.invokedFunctions)
+        uses.add(name);
+    for (const id of Object.values(state.rpc.exposedMeta))
+        uses.add(id);
+    const seen = new WeakSet();
+    for (const [section, value] of Object.entries(state)) {
+        if (NOT_USES.has(section) || section === 'rpc' || section === 'workflows')
+            continue;
+        collectUses(value, uses, seen);
+    }
+    // A workflow's own meta and graph name the workflow itself; only what its
+    // steps call counts as a use.
+    const { meta: workflowsMeta, graphMeta } = state.workflows;
+    for (const entries of [workflowsMeta, graphMeta]) {
+        for (const [workflowName, entry] of Object.entries(entries ?? {})) {
+            const calls = new Set();
+            collectUses(entry, calls, seen);
+            calls.delete(workflowName);
+            if (entry?.pikkuFuncId)
+                calls.delete(entry.pikkuFuncId);
+            for (const call of calls)
+                uses.add(call);
+        }
+    }
+    // Workflows started by name: client helpers, `startWorkflow` and
+    // `runToCompletion` calls, and each function's own `rpc.startWorkflow`.
+    const startedWorkflows = new Set(state.workflows.invokedWorkflows);
+    for (const meta of Object.values(state.functions.meta)) {
+        for (const name of meta.startsWorkflows ?? [])
+            startedWorkflows.add(name);
+    }
+    for (const workflowName of startedWorkflows)
+        uses.add(workflowName);
+    // A workflow named by its workflow name, by any of the above or by
+    // `rpc.invoke` and step calls, uses the function behind it.
+    for (const [workflowName, entry] of Object.entries(workflowsMeta)) {
+        if (uses.has(workflowName) && entry?.pikkuFuncId)
+            uses.add(entry.pikkuFuncId);
+    }
+    const unused = [];
+    for (const [pikkuFuncId, meta] of Object.entries(state.functions.meta)) {
+        if (meta.functionType !== 'user')
+            continue;
+        if (meta.funcWrapper && RUN_BY_SCENARIOS.has(meta.funcWrapper))
+            continue;
+        if (meta.expose || meta.remote || meta.mcp)
+            continue;
+        // A generated scaffold is rewritten on every run, so `disabled` cannot be
+        // added to it; what it leaves unwired it leaves for the project to wire.
+        if (meta.sourceFile?.endsWith('.gen.ts'))
+            continue;
+        if (uses.has(pikkuFuncId) || (meta.name && uses.has(meta.name)))
+            continue;
+        unused.push({
+            pikkuFuncId,
+            ...(meta.name ? { name: meta.name } : {}),
+            ...(meta.sourceFile ? { sourceFile: meta.sourceFile } : {}),
+        });
+    }
+    return unused;
+};

package/dist/utils/find-wire-remote-addon-specs.d.ts

@@ -0,0 +1,17 @@
+/** A `wireRemoteAddon({ package })` found in source, with the line its literal sits on. */
+export type WireRemoteAddonSpec = {
+    /** The `name` option, when it is a literal. */
+    namespace?: string;
+    /** The literal as written, e.g. `@scope/name@^1.4.0`. */
+    spec: string;
+    name: string;
+    range?: string;
+    /** 1-based line of the literal. */
+    line: number;
+};
+/**
+ * Every `wireRemoteAddon({ package: '<literal>' })` in one file. A `package`
+ * that is not a literal, or that does not parse, is skipped: the inspection
+ * reports those.
+ */
+export declare const findWireRemoteAddonSpecs: (fileName: string, sourceText: string) => WireRemoteAddonSpec[];

package/dist/utils/find-wire-remote-addon-specs.js

@@ -0,0 +1,53 @@
+import * as ts from 'typescript';
+import { parseRemoteAddonPackage } from './remote-addon-sdk.js';
+/**
+ * Every `wireRemoteAddon({ package: '<literal>' })` in one file. A `package`
+ * that is not a literal, or that does not parse, is skipped: the inspection
+ * reports those.
+ */
+export const findWireRemoteAddonSpecs = (fileName, sourceText) => {
+    if (!sourceText.includes('wireRemoteAddon'))
+        return [];
+    const sourceFile = ts.createSourceFile(fileName, sourceText, ts.ScriptTarget.Latest, true);
+    const found = [];
+    const visit = (node) => {
+        if (ts.isCallExpression(node) &&
+            ts.isIdentifier(node.expression) &&
+            node.expression.text === 'wireRemoteAddon' &&
+            node.arguments[0] &&
+            ts.isObjectLiteralExpression(node.arguments[0])) {
+            let namespace;
+            let literal;
+            for (const prop of node.arguments[0].properties) {
+                if (!ts.isPropertyAssignment(prop) || !ts.isIdentifier(prop.name))
+                    continue;
+                if (prop.name.text === 'name' &&
+                    ts.isStringLiteralLike(prop.initializer)) {
+                    namespace = prop.initializer.text;
+                }
+                else if (prop.name.text === 'package' &&
+                    ts.isStringLiteralLike(prop.initializer)) {
+                    literal = prop.initializer;
+                }
+            }
+            if (literal) {
+                try {
+                    const { name, range } = parseRemoteAddonPackage(literal.text);
+                    found.push({
+                        namespace,
+                        spec: literal.text,
+                        name,
+                        range,
+                        line: sourceFile.getLineAndCharacterOfPosition(literal.getStart(sourceFile)).line + 1,
+                    });
+                }
+                catch {
+                    // reported by the inspection
+                }
+            }
+        }
+        ts.forEachChild(node, visit);
+    };
+    visit(sourceFile);
+    return found;
+};

package/dist/utils/get-property-value.js

@@ -202,7 +202,10 @@ export const getCommonWireMetaData = (obj, wiringType, wiringName, logger, check
         if (ts.isPropertyAssignment(prop) && ts.isIdentifier(prop.name)) {
             const propName = prop.name.text;
             if (propName === 'disabled' &&
-                prop.initializer.kind === ts.SyntaxKind.TrueKeyword) {
+                (prop.initializer.kind === ts.SyntaxKind.TrueKeyword ||
+                    ((ts.isStringLiteral(prop.initializer) ||
+                        ts.isNoSubstitutionTemplateLiteral(prop.initializer)) &&
+                        prop.initializer.text !== ''))) {
                 metadata.disabled = true;
             }
             else if (propName === 'title') {

package/dist/utils/load-addon-functions-meta.js

@@ -1,8 +1,10 @@
 import { existsSync } from 'fs';
 import { readFile, readdir } from 'fs/promises';
-import { join, dirname, parse, relative } from 'path';
+import { join, dirname, relative } from 'path';
 import { addonResolutionDirs, createAddonResolver, } from './addon-resolution.js';
 import { ErrorCode } from '../error-codes.js';
+import { checkLockedSdk } from './remote-addon-sdk.js';
+import { declaredAddonNames, findInstalledPackageDir, readAddonDependencies, } from './addon-dependencies.js';
 const isHTTPRouteConfig = (value) => typeof value === 'object' &&
     value !== null &&
     'method' in value &&
@@ -91,24 +93,6 @@ const resolveAddonMeta = (require, packageName, baseName) => {
     }
     return null;
 };
-const findInstalledPackageDir = (dirs, packageName) => {
-    for (const start of dirs) {
-        const root = parse(start).root;
-        let dir = start;
-        while (dir) {
-            const candidate = join(dir, 'node_modules', packageName);
-            if (existsSync(join(candidate, 'package.json')))
-                return candidate;
-            if (dir === root)
-                break;
-            const parent = dirname(dir);
-            if (parent === dir)
-                break;
-            dir = parent;
-        }
-    }
-    return null;
-};
 export const describeMissingAddonMeta = (namespace, packageName, dirs, declFile) => {
     const caller = declFile
         ? relative(dirs[dirs.length - 1], declFile) || declFile
@@ -182,27 +166,12 @@ export const namespaceAddonWebhookSources = (sources, namespace) => {
  * package's function metadata so that wiring handlers (channels, HTTP routes,
  * schedules, etc.) can look up addon function types during the routes sweep.
  */
-const loadScreensManifest = async (require, packageName) => {
+const loadStudioMeta = async (require, packageName) => {
     const path = resolveAddonMeta(require, packageName, 'screens/pikku-screens-meta');
     if (!path)
         return null;
     return JSON.parse(await readFile(path, 'utf-8'));
 };
-const readAddonNeeds = async (dirs, packageName) => {
-    const dir = findInstalledPackageDir(dirs, packageName);
-    if (!dir)
-        return [];
-    try {
-        const pkg = JSON.parse(await readFile(join(dir, 'package.json'), 'utf-8'));
-        const uses = pkg?.pikku?.uses;
-        return Array.isArray(uses)
-            ? uses.filter((u) => typeof u === 'string')
-            : [];
-    }
-    catch {
-        return [];
-    }
-};
 const isContributorRef = (value) => !!value &&
     typeof value === 'object' &&
     typeof value.module === 'string' &&
@@ -239,6 +208,56 @@ export const readAddonContributors = async (dirs, packageName) => {
         contributors: declared.map(({ module, export: name }) => name === undefined ? { module } : { module, export: name }),
     };
 };
+/**
+ * A versioned remote addon's function metadata comes from the SDK `pikku addon
+ * sync` extracted, and only when it matches the lock — a stale or missing SDK
+ * is reported by `validateRemoteAddonDependencies`, not loaded half-way.
+ */
+const loadRemoteAddonSdkMeta = async (state, namespace, packageName, range) => {
+    let locked;
+    try {
+        locked = checkLockedSdk(state.rootDir, packageName, range);
+    }
+    catch {
+        return;
+    }
+    if (!locked.ok)
+        return;
+    const metaPath = join(locked.dir, 'function', 'pikku-functions-meta.gen.json');
+    if (!existsSync(metaPath))
+        return;
+    (state.remoteAddonFunctions ??= {})[namespace] = JSON.parse(await readFile(metaPath, 'utf-8'));
+};
+/**
+ * Reads the addons a wired package says it calls (`pikku.uses` in its
+ * package.json) onto its declaration, and reports each one this wiring leaves
+ * unmapped. Whether a mapping points at the right package, and whether the
+ * wiring maps a name the package never declared, is `validateAddonUses`' call
+ * once every wiring is known.
+ */
+const recordDeclaredUses = (logger, namespace, decl, dirs) => {
+    const packageDir = findInstalledPackageDir(dirs, decl.package);
+    if (!packageDir)
+        return;
+    const declared = readAddonDependencies(packageDir);
+    if (declared.form === 'none')
+        return;
+    if (declared.form === 'map') {
+        for (const message of declared.invalid) {
+            logger.critical(ErrorCode.ADDON_DEPENDENCY_INVALID, `${decl.package} (wired as '${namespace}'): ${message}`);
+        }
+        decl.dependencies = declared.dependencies;
+    }
+    decl.declaredUses = declaredAddonNames(declared);
+    for (const needed of decl.declaredUses) {
+        if (decl.uses?.[needed])
+            continue;
+        const dependency = decl.dependencies?.find((d) => d.alias === needed);
+        logger.critical(ErrorCode.ADDON_NEEDS_NOT_MAPPED, dependency
+            ? `${decl.package} calls ${dependency.package}@${dependency.range} as '${needed}', but wireAddon('${namespace}') does not map it. Wire ${dependency.package} and add uses: { '${needed}': '<name>' } to this wireAddon.`
+            : `${decl.package} needs ${needed}, but wireAddon('${namespace}') does not map it. Wire ${needed} and add uses: { '${needed}': '<name>' } to this wireAddon.`);
+    }
+};
 export async function loadAddonFunctionsMeta(logger, state) {
     const { wireAddonDeclarations } = state.rpc;
     if (wireAddonDeclarations.size === 0)
@@ -247,8 +266,12 @@ export async function loadAddonFunctionsMeta(logger, state) {
         // Remote addons (wireRemoteAddon) ship as a devDependency: types only.
         // Their functions, secrets, variables, schemas and services live on the
         // HOST that runs them — never load or require any of that here.
-        if (decl.remote)
+        if (decl.remote) {
+            if (decl.range) {
+                await loadRemoteAddonSdkMeta(state, namespace, decl.package, decl.range);
+            }
             continue;
+        }
         const dirs = addonResolutionDirs(state.rootDir, decl.file);
         const require = createAddonResolver(dirs);
         try {
@@ -262,16 +285,12 @@ export async function loadAddonFunctionsMeta(logger, state) {
             catch (error) {
                 logger.error(`wireAddon('${namespace}'): ${error instanceof Error ? error.message : error}`);
             }
-            for (const needed of await readAddonNeeds(dirs, decl.package)) {
-                if (!decl.uses?.[needed]) {
-                    logger.critical(ErrorCode.ADDON_NEEDS_NOT_MAPPED, `${decl.package} needs ${needed}, but wireAddon('${namespace}') does not map it. Wire ${needed} and add uses: { '${needed}': '<name>' } to this wireAddon.`);
-                }
-            }
+            recordDeclaredUses(logger, namespace, decl, dirs);
             if (decl.ui) {
                 let manifest;
                 let unreadable = false;
                 try {
-                    manifest = await loadScreensManifest(require, decl.package);
+                    manifest = await loadStudioMeta(require, decl.package);
                 }
                 catch (e) {
                     logger.critical(ErrorCode.ADDON_UI_HAS_NO_SCREENS, `wireAddon('${namespace}') sets ui: true, but the screens manifest of ${decl.package} could not be read: ${e instanceof Error ? e.message : e}`);
@@ -281,11 +300,11 @@ export async function loadAddonFunctionsMeta(logger, state) {
                     // reported above; the addon's functions and scopes still load
                 }
                 else if (!manifest || manifest.screens.length === 0) {
-                    logger.critical(ErrorCode.ADDON_UI_HAS_NO_SCREENS, `wireAddon('${namespace}') sets ui: true, but ${decl.package} declares no screens. Add a defineScreens call to the package, or drop ui.`);
+                    logger.critical(ErrorCode.ADDON_UI_HAS_NO_SCREENS, `wireAddon('${namespace}') sets ui: true, but ${decl.package} declares no screens. Add a pikkuStudio call to the package, or drop ui.`);
                 }
                 else {
                     ;
-                    (state.addonScreens ??= {})[namespace] = {
+                    (state.addonStudio ??= {})[namespace] = {
                         ...manifest,
                         scopes: [
                             ...new Set([...(manifest.scopes ?? []), ...(decl.scopes ?? [])]),
@@ -347,13 +366,17 @@ export async function loadAddonFunctionsMeta(logger, state) {
                     }
                 }
             }
-            // Same reasoning as mcp: a listed name the addon does not publish is a
-            // function the app believes callable and never is.
+            // Same reasoning as mcp: a listed name the addon does not publish, or
+            // does not declare `expose: true`, is a function the app believes
+            // callable and never is.
             if (Array.isArray(decl.expose)) {
                 for (const funcName of decl.expose) {
                     if (!Object.hasOwn(meta, funcName)) {
                         logger.critical(ErrorCode.ADDON_EXPOSE_FUNCTION_NOT_FOUND, `wireAddon('${namespace}') lists '${funcName}' under expose, but ${decl.package} publishes no such function.`);
                     }
+                    else if (meta[funcName]?.expose !== true) {
+                        logger.critical(ErrorCode.ADDON_EXPOSE_FUNCTION_NOT_FOUND, `wireAddon('${namespace}') lists '${funcName}' under expose, but ${decl.package} does not declare it expose: true, so it stays unexposed.`);
+                    }
                 }
             }
             // Load addon secrets meta

package/dist/utils/post-process.js

@@ -7,6 +7,7 @@ import { relative } from 'node:path';
 import { AUTH_HANDLER_FUNC_ID, DYNAMIC_SCENARIO_STEP_TARGET, } from './inspector-constants.js';
 import { flattenScopeDefinitions } from '@pikku/core/scope';
 import { addonResolutionDirs } from './addon-resolution.js';
+import { ADDONS_LOCK_FILE, checkLockedSdk, readAddonsLock, } from './remote-addon-sdk.js';
 /**
  * Stamp the inspected authorize/callbacks service set onto the generated auth
  * handler's function meta.
@@ -238,8 +239,9 @@ export function aggregateRequiredServices(state) {
     // nothing, so they are found by id: the route accepts into the queue through
     // incomingWebhookService and the worker records attempts through it.
     const hasWebhookSources = Object.values(state.triggers?.webhookSourceMeta ?? {}).some(({ method, route }) => state.functions.meta[`http:${method}:${route}`] !== undefined);
-    if (hasWebhookSources ||
-        state.functions.meta['queue:pikku-incoming-webhooks'] !== undefined) {
+    const wiresIncomingWebhooks = hasWebhookSources ||
+        state.functions.meta['queue:pikku-incoming-webhooks'] !== undefined;
+    if (wiresIncomingWebhooks) {
         requiredServices.add('incomingWebhookService');
         requiredServices.add('queueService');
     }
@@ -332,6 +334,12 @@ export function aggregateRequiredServices(state) {
             addonFnServices.set(`${namespace}:${id}`, meta?.services?.services);
         }
     }
+    // An addon forwarding `incomingWebhookService` (pikku-admin lists receipts)
+    // reads it when the app has one; it never makes the app keep receipts. Only
+    // the app's own webhook sources do, so only they bring in the service and its
+    // tables — otherwise an app with no webhook wired fails to boot on a
+    // `webhook_receipt` table nothing writes to.
+    const readOnlyIfPresent = (service) => service === 'incomingWebhookService' && !wiresIncomingWebhooks;
     const parentDeclared = state.addonRequiredParentServices ?? [];
     const parentDeclaredSet = new Set(parentDeclared);
     const defaultServices = new Set([
@@ -353,6 +361,9 @@ export function aggregateRequiredServices(state) {
             continue;
         }
         for (const service of services) {
+            if (readOnlyIfPresent(service)) {
+                continue;
+            }
             if (parentDeclaredSet.has(service)) {
                 requiredServices.add(service);
             }
@@ -364,7 +375,9 @@ export function aggregateRequiredServices(state) {
     }
     if (usesAddonFn && addonFactoryNeeded) {
         for (const service of parentDeclared) {
-            requiredServices.add(service);
+            if (!readOnlyIfPresent(service)) {
+                requiredServices.add(service);
+            }
         }
     }
     // 8. When this project IS an addon, what it needs from its parent is whatever
@@ -401,6 +414,11 @@ export function validateSecretOverrides(logger, state) {
     // passes to getSecret — so validate against secretId, falling back to name for
     // older meta without a secretId field.
     const secretIds = new Set(state.secrets.definitions.map((d) => d.secretId ?? d.name));
+    // auth-secrets.gen.ts declares it, but that file is written after the first
+    // inspection of a fresh project, so its defineSecret is not seen yet — the
+    // same fallback validateSecretUsage takes.
+    if (state.auth?.definition)
+        secretIds.add('BETTER_AUTH_SECRET');
     for (const [namespace, addonDecl] of wireAddonDeclarations.entries()) {
         for (const [logicalName, resolvedName] of Object.entries(addonDecl.secretOverrides ?? {})) {
             if (!secretIds.has(resolvedName)) {
@@ -424,13 +442,20 @@ export function validateAddonUses(logger, state) {
     if (!wireAddonDeclarations || wireAddonDeclarations.size === 0)
         return;
     for (const [namespace, addonDecl] of wireAddonDeclarations.entries()) {
-        for (const [pkg, target] of Object.entries(addonDecl.uses ?? {})) {
+        for (const [name, target] of Object.entries(addonDecl.uses ?? {})) {
+            if (addonDecl.declaredUses && !addonDecl.declaredUses.includes(name)) {
+                logger.critical(ErrorCode.ADDON_USES_NOT_DECLARED, `Addon '${namespace}' maps '${name}' to '${target}', but ${addonDecl.package} does not declare '${name}' in the pikku.uses of its package.json. It declares: ${addonDecl.declaredUses.join(', ') || 'nothing'}. Remove '${name}' from uses, or have the addon declare it.`);
+                continue;
+            }
+            const expected = addonDecl.dependencies?.find((d) => d.alias === name)?.package ?? name;
             const wired = wireAddonDeclarations.get(target);
             if (!wired) {
-                logger.critical(ErrorCode.ADDON_USES_NOT_WIRED, `Addon '${namespace}' uses '${pkg}' as '${target}', but no addon is wired under the name '${target}'. Wired: ${Array.from(wireAddonDeclarations.keys()).join(', ')}`);
+                logger.critical(ErrorCode.ADDON_USES_NOT_WIRED, `Addon '${namespace}' uses '${name}' as '${target}', but no addon is wired under the name '${target}'. Wired: ${Array.from(wireAddonDeclarations.keys()).join(', ')}`);
             }
-            else if (wired.package !== pkg) {
-                logger.critical(ErrorCode.ADDON_USES_NOT_WIRED, `Addon '${namespace}' uses '${pkg}' as '${target}', but '${target}' is wired from '${wired.package}'.`);
+            else if (wired.package !== expected) {
+                logger.critical(ErrorCode.ADDON_USES_NOT_WIRED, expected === name
+                    ? `Addon '${namespace}' uses '${name}' as '${target}', but '${target}' is wired from '${wired.package}'.`
+                    : `Addon '${namespace}' calls ${expected} as '${name}', mapped to '${target}', but '${target}' is wired from '${wired.package}'.`);
             }
         }
     }
@@ -607,8 +632,33 @@ export function validateRemoteAddonDependencies(logger, state) {
         manifests.set(path, manifest);
         return manifest;
     };
+    // A versioned remote addon's contract is the SDK `pikku all`
+    // downloaded, so what has to hold is that the SDK on disk is the one the
+    // lock pins, not that a package is installed.
+    let lock;
     for (const [namespace, decl] of wireAddonDeclarations.entries()) {
-        if (!decl.remote)
+        if (!decl.remote || !decl.range)
+            continue;
+        if (lock === undefined) {
+            try {
+                lock = readAddonsLock(state.rootDir);
+            }
+            catch (e) {
+                lock = e instanceof Error ? e : new Error(String(e));
+            }
+        }
+        const reason = lock instanceof Error
+            ? lock.message
+            : (() => {
+                const locked = checkLockedSdk(state.rootDir, decl.package, decl.range, lock);
+                return locked.ok ? null : locked.reason;
+            })();
+        if (reason === null)
+            continue;
+        logger.critical(ErrorCode.REMOTE_ADDON_NOT_DEV_DEPENDENCY, `Remote addon '${namespace}' ('${decl.package}@${decl.range}') has no SDK matching ${ADDONS_LOCK_FILE}: ${reason}. Run 'pikku all' to download it.`);
+    }
+    for (const [namespace, decl] of wireAddonDeclarations.entries()) {
+        if (!decl.remote || decl.range)
             continue;
         const pkgJsonPath = join(addonResolutionDirs(state.rootDir, decl.file)[0], 'package.json');
         const pkgJson = readManifest(pkgJsonPath);