@pikku/inspector 0.12.82 → 0.12.83

package/CHANGELOG.md

@@ -1,3 +1,55 @@
+## 0.12.83
+
+### Patch Changes
+
+- 6db6a14: A wiring can now decide whether an addon's credential is per-user or deployment-wide
+
+  `wireAddon`'s `credentialOverrides` takes an object as well as a rename string:
+
+  ```ts
+  wireAddon({
+    name: 'gmail',
+    package: '@pikku/addon-gmail',
+    credentialOverrides: {
+      gmailOAuth: { mode: 'wire' }, // each user connects their own
+      calendarOAuth: { name: 'CAL', mode: 'singleton' },
+    },
+  })
+  ```
+
+  An addon author declares a default with `defineCredential`; the deployment decides, so one addon serves both a per-user product and a single team account.
+
+  The wire credential service now resolves each credential by what it _is_ rather than by what a lookup returned: `wire` reads only the user's value, `singleton` reads the deployment's. A per-user credential can no longer pick up a platform-level value because the user has not connected — which, before, would have quietly run someone's request against the deployment's own account.
+
+  A credential is never read from the secret vault. The wire credential service no longer takes a `SecretService` at all, so the only way a credential arrives is the one its mode names — the user's own value, or the deployment's.
+
+  Modes are resolved at generation time into the credentials meta, so the console's connect flow reflects the wiring rather than the addon's default.
+
+  Two credentials that resolve to one name are rejected unless they agree on the mode. Generation writes a single metadata entry per name, so a `wire` credential aliased onto a `singleton` one used to take whichever wiring was read last — a per-user credential served from the deployment's own account, or a deployment credential handed out per user. The inspector reports the collision against both wirings by name, and `buildCredentialResolutions` refuses it at runtime too.
+
+  A mode-only override is checked against the credential it names. `{ mode: 'wire' }` renames nothing, so nothing was validated: an override naming a credential that does not exist was dropped in silence and the credential kept the mode its author declared.
+
+  A credential the wiring resolves as `singleton` is no longer read out of the user's own store. Per-user values are imported first and a name already present is left alone, so a value stored under a singleton's name — from an earlier wiring, or a connect flow since rewired — decided what the deployment's own slot resolved to. It is now skipped by mode, the same way a `wire` credential is kept away from the deployment's value.
+
+  The project's own credentials are registered into pikku state from the generated credentials file, so `wire.getCredential` resolves an app-level singleton the same way it resolves an addon's.
+
+  `pikku new addon` no longer requires a `pikku.config.json` in the working directory. Scaffolding an addon is something you do before a project config exists, so the command now reads one when it is there and falls back to the working directory when it is not.
+
+  An addon's `pikkuAddonWireServices` factory now declares the same service contract its singleton factory does: what it destructures off the parent's bag is required, and what it returns is built by the addon. Before, a service an addon built per wire was demanded from the consumer, and a wire-only addon declared no contract at all. A nested callback that names its own parameter after the factory's is no longer read as the factory's own: what it destructured went onto the addon's contract, so a consumer was asked for a service the addon never wanted from them.
+
+  An OAuth2 credential now implies its app secret, so nobody hand-writes one. The client id and secret an OAuth app needs is the same shape every time — `OAuth2AppCredential`, which is what the runtime already reads it as — so the inspector registers a secret for each credential's `appCredentialSecretId`. A hand-written `defineSecret` covering that id still wins, so an author who wants their own description or `docsUrl` keeps it. The derived secret is optional, matching what every hand-written declaration chose: an addon that also authenticates by API key must still deploy without an OAuth app configured.
+
+  `optional` now means a secret is not reported as missing. `getMissing()` filtered on "not configured" alone, so a secret whose declaration said absence was supported still showed up on the list of things a deployment had to go and supply — burying the ones that genuinely were. `getAllStatus()` still reports it, flagged `optional`.
+
+  An OAuth2 secret carries its declaration's `optional` through code generation, to the app credential and to the token store alike: nobody connects without the client id and secret, so a deployment allowed to omit the app is never asked for its tokens either. That branch never looked at the flag before.
+
+  `credentialOAuthProviders` treats an app secret that resolves `undefined` as unconfigured. An optional secret resolves rather than throws, so the absence arrived past the `catch` that was meant to skip the provider — and `.reveal()` on it threw a `TypeError` that took every `getSession` down with it, which is the exact failure that code exists to prevent.
+
+- Updated dependencies [cb8f57e]
+- Updated dependencies [cb8f57e]
+- Updated dependencies [6db6a14]
+  - @pikku/core@0.12.114
+
 ## 0.12.82
 
 ### Patch Changes

package/dist/add/add-file-with-factory.js

@@ -11,13 +11,16 @@ const wrapperFunctionMap = {
     pikkuServerLifecycle: 'ServerLifecycle',
 };
 /**
- * What an addon's `pikkuAddonServices` factory takes from the parent: the names
- * destructured off its second parameter, either in the parameter list or from a
- * `const { … } = existingServices` in the body.
+ * What an addon's services factory takes from the parent: the names
+ * destructured off the parameter carrying the parent's bag, either in the
+ * parameter list or from a `const { … } = existingServices` in the body.
+ *
+ * `pikkuAddonServices` receives it second, after the config;
+ * `pikkuAddonWireServices` receives it first, ahead of the wire.
  */
-const extractForwardedServices = (functionNode) => {
+const extractForwardedServices = (functionNode, servicesParamIndex) => {
     const forwarded = [];
-    const secondParam = functionNode.parameters[1];
+    const secondParam = functionNode.parameters[servicesParamIndex];
     if (!secondParam)
         return forwarded;
     const collectBinding = (pattern) => {
@@ -43,6 +46,22 @@ const extractForwardedServices = (functionNode) => {
     const body = functionNode.body;
     if (!ts.isBlock(body))
         return forwarded;
+    /**
+     * A nested callback is free to name its own parameter `services` too. Its
+     * destructuring belongs to that parameter, not the factory's, so descending
+     * into it would put a service on the addon's contract the factory never
+     * asked the parent for.
+     */
+    const shadowsParam = (node) => {
+        if (!ts.isFunctionLike(node))
+            return false;
+        return node.parameters.some((parameter) => bindsName(parameter.name));
+    };
+    const bindsName = (name) => {
+        if (ts.isIdentifier(name))
+            return name.text === paramName;
+        return name.elements.some((element) => !ts.isOmittedExpression(element) && bindsName(element.name));
+    };
     const visit = (node) => {
         if (ts.isVariableDeclaration(node) &&
             ts.isObjectBindingPattern(node.name) &&
@@ -50,7 +69,10 @@ const extractForwardedServices = (functionNode) => {
             ts.isIdentifier(node.initializer) &&
             node.initializer.text === paramName) {
             collectBinding(node.name);
+            return;
         }
+        if (shadowsParam(node))
+            return;
         ts.forEachChild(node, visit);
     };
     ts.forEachChild(body, visit);
@@ -143,10 +165,15 @@ export const addFileWithFactory = (node, checker, methods = new Map(), expectedT
                             state.wireServicesMeta.set(variableName, servicesMeta.services);
                         }
                         // Extract existing services an addon needs from the parent
-                        // (second parameter of pikkuAddonServices callback)
-                        if (wrapperFunctionName === 'pikkuAddonServices' && functionNode) {
+                        // (second parameter of pikkuAddonServices callback). A wire
+                        // factory reads the same parent bag and returns services of its
+                        // own, so it declares the same contract — a service it builds per
+                        // wire is one the addon owns, not one its consumer owes.
+                        if ((wrapperFunctionName === 'pikkuAddonServices' ||
+                            wrapperFunctionName === 'pikkuAddonWireServices') &&
+                            functionNode) {
                             state.addonServicesFactorySeen = true;
-                            const forwarded = new Set(extractForwardedServices(functionNode));
+                            const forwarded = new Set(extractForwardedServices(functionNode, wrapperFunctionName === 'pikkuAddonWireServices' ? 0 : 1));
                             for (const name of forwarded) {
                                 state.addonRequiredParentServices.push(name);
                             }

package/dist/add/add-wire-addon.js

@@ -30,6 +30,54 @@ function parseStringRecord(obj) {
     }
     return result;
 }
+/**
+ * `credentialOverrides` takes either a rename string or an object that also
+ * decides where the value is read from, so it cannot use `parseStringRecord`.
+ * A non-literal member is dropped rather than guessed at — the wiring is read
+ * statically, and a value this cannot see must not be reported as a mode.
+ */
+function parseCredentialOverrideRecord(obj) {
+    const result = {};
+    for (const prop of obj.properties) {
+        if (!ts.isPropertyAssignment(prop))
+            continue;
+        const keyNode = prop.name;
+        const key = ts.isIdentifier(keyNode)
+            ? keyNode.text
+            : ts.isStringLiteral(keyNode)
+                ? keyNode.text
+                : undefined;
+        if (!key)
+            continue;
+        if (ts.isStringLiteral(prop.initializer)) {
+            result[key] = prop.initializer.text;
+            continue;
+        }
+        if (!ts.isObjectLiteralExpression(prop.initializer))
+            continue;
+        const override = {};
+        for (const member of prop.initializer.properties) {
+            if (!ts.isPropertyAssignment(member))
+                continue;
+            const memberKey = ts.isIdentifier(member.name)
+                ? member.name.text
+                : ts.isStringLiteral(member.name)
+                    ? member.name.text
+                    : undefined;
+            if (!memberKey || !ts.isStringLiteral(member.initializer))
+                continue;
+            if (memberKey === 'name')
+                override.name = member.initializer.text;
+            else if (memberKey === 'mode' &&
+                (member.initializer.text === 'wire' ||
+                    member.initializer.text === 'singleton')) {
+                override.mode = member.initializer.text;
+            }
+        }
+        result[key] = override;
+    }
+    return result;
+}
 /**
  * Detect wireAddon({ name: '...', package: '...' }) call expressions and
  * populate state.rpc.wireAddonDeclarations and state.rpc.usedAddons.
@@ -98,7 +146,7 @@ export function addWireAddon(node, state, logger) {
         }
         else if (key === 'credentialOverrides' &&
             ts.isObjectLiteralExpression(prop.initializer)) {
-            credentialOverrides = parseStringRecord(prop.initializer);
+            credentialOverrides = parseCredentialOverrideRecord(prop.initializer);
         }
         else if (key === 'secretGrants') {
             secretGrants = parseStringArray(prop.initializer);

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 export { inspect, getInitialInspectorState } from './inspector.js';
 export type { TypesMap } from './types-map.js';
-export type { AddonConfig, AuthDefinition, InspectorDiagnostic, InspectorFilters, InspectorHTTPState, InspectorLogger, InspectorMiddlewareState, InspectorOptions, InspectorPermissionState, InspectorState, MetaInputTypes, MiddlewareGroupMeta, MiddlewareRegistration, SchemaRef, } from './types.js';
+export type { AddonConfig, AuthDefinition, CredentialOverrideMeta, InspectorDiagnostic, InspectorFilters, InspectorHTTPState, InspectorLogger, InspectorMiddlewareState, InspectorOptions, InspectorPermissionState, InspectorState, MetaInputTypes, MiddlewareGroupMeta, MiddlewareRegistration, SchemaRef, } from './types.js';
 export type { FilesAndMethodsErrors } from './utils/get-files-and-methods.js';
 export { ErrorCode } from './error-codes.js';
 export type { DiagnosticSeverity, CodedDiagnostic } from './error-codes.js';

package/dist/inspector.js

@@ -7,7 +7,7 @@ import { getFilesAndMethods } from './utils/get-files-and-methods.js';
 import { findCommonAncestor } from './utils/find-root-dir.js';
 import { createSourceFileCacheHost } from './source-file-cache.js';
 import { createNestedProjectFilter } from './utils/nested-project-filter.js';
-import { aggregateRequiredServices, stampAuthHandlerServices, validateAgentModels, validateAgentToolReferences, validateAgentScorerReferences, validateSecretOverrides, validateVariableOverrides, validateCredentialOverrides, validateRemoteAddonDependencies, validateRemoteAddonAuth, validateScopeReferences, validateSystemRoleScopes, validatePersonaRoles, computeResolvedIOTypes, computeMiddlewareGroupsMeta, computePermissionsGroupsMeta, computeRequiredSchemas, validateNoSecretAliasServices, validateSecretUsage, computeDiagnostics, validateSchemaReferences, validateSchemaWiringSeparation, validateScenarioServices, validateScenarioSteps, validateWorkflowGraphAddons, } from './utils/post-process.js';
+import { aggregateRequiredServices, stampAuthHandlerServices, validateAgentModels, validateAgentToolReferences, validateAgentScorerReferences, validateSecretOverrides, validateVariableOverrides, validateCredentialOverrides, validateRemoteAddonDependencies, validateRemoteAddonAuth, validateScopeReferences, validateSystemRoleScopes, validatePersonaRoles, computeResolvedIOTypes, computeMiddlewareGroupsMeta, computePermissionsGroupsMeta, computeRequiredSchemas, validateNoSecretAliasServices, registerDerivedOAuth2AppSecrets, validateSecretUsage, computeDiagnostics, validateSchemaReferences, validateSchemaWiringSeparation, validateScenarioServices, validateScenarioSteps, validateWorkflowGraphAddons, } from './utils/post-process.js';
 import { validateExposedFunctionsGated } from './utils/validate-exposed-functions-gated.js';
 import { validateTagsResolveToMiddleware } from './utils/validate-tags-resolve-to-middleware.js';
 import { annotateHttpRouteAuth } from './utils/annotate-http-route-auth.js';
@@ -397,6 +397,7 @@ export const inspect = async (logger, routeFiles, options = {}) => {
         computeMiddlewareGroupsMeta(state);
         computePermissionsGroupsMeta(state);
         validateNoSecretAliasServices(logger, checker, state);
+        registerDerivedOAuth2AppSecrets(state);
         validateSecretUsage(logger, state);
         computeDiagnostics(state);
         validateSchemaWiringSeparation(logger, state);

package/dist/types.d.ts

@@ -469,6 +469,14 @@ export interface InspectorFeature {
     hasBefore: boolean;
     hasAfter: boolean;
 }
+/**
+ * A `wireAddon` credential override as it survives static reading: a rename
+ * string, or the object form that also decides how the value resolves.
+ */
+export type CredentialOverrideMeta = string | {
+    name?: string;
+    mode?: 'singleton' | 'wire';
+};
 export interface InspectorState {
     rootDir: string;
     singletonServicesTypeImportMap: PathToNameAndType;
@@ -600,7 +608,7 @@ export interface InspectorState {
             authSecretId?: string;
             secretOverrides?: Record<string, string>;
             variableOverrides?: Record<string, string>;
-            credentialOverrides?: Record<string, string>;
+            credentialOverrides?: Record<string, CredentialOverrideMeta>;
             /** Secrets the app lends this instance, named as the addon reads them. */
             secretGrants?: string[];
             /** Credentials the app lends this instance, named as the addon reads them. */

package/dist/utils/post-process.d.ts

@@ -161,6 +161,12 @@ export declare function validateNoSecretAliasServices(logger: InspectorLogger, c
  * at first request rather than at deploy; a non-literal key is a read the
  * manifest cannot cover, so a per-unit scope cannot be narrowed around it.
  */
+/**
+ * Registers the app secrets the project's OAuth2 credentials imply, so a
+ * deployment is asked for the client id and secret every connect flow needs
+ * without an author restating a shape the runtime already fixes.
+ */
+export declare function registerDerivedOAuth2AppSecrets(state: InspectorState | Omit<InspectorState, 'typesLookup'>): void;
 export declare function validateSecretUsage(logger: InspectorLogger, state: InspectorState | Omit<InspectorState, 'typesLookup'>): void;
 export declare function computeDiagnostics(state: InspectorState): void;
 /**

package/dist/utils/post-process.js

@@ -4,6 +4,7 @@ import { join } from 'node:path';
 import { extractTypeKeys } from './type-utils.js';
 import { ErrorCode } from '../error-codes.js';
 import { findSecretAliasServices } from './secret-alias-services.js';
+import { deriveOAuth2AppSecrets } from '@pikku/core/secret';
 import { resolveCoreType } from './resolve-core-type.js';
 import { relative } from 'node:path';
 import { AUTH_HANDLER_FUNC_ID } from '../add/add-auth.js';
@@ -385,15 +386,42 @@ export function validateCredentialOverrides(logger, state) {
     if (!wireAddonDeclarations || wireAddonDeclarations.size === 0)
         return;
     const credentialNames = new Set(state.credentials?.definitions.map((d) => d.name) ?? []);
+    /** Only a rename has a target to check; a mode-only override renames nothing. */
+    const renameTarget = (override) => typeof override === 'string' ? override : override.name;
+    const overrideMode = (override) => typeof override === 'string' ? undefined : override.mode;
+    /**
+     * Which declaration set each resolved name's mode. Credential generation
+     * writes one shared metadata entry per name, so two declarations that map
+     * onto one name with opposite modes leave whichever ran last in the file the
+     * console reads — and the other addon silently gets the wrong resolution.
+     */
+    const modeClaims = new Map();
     for (const [namespace, addonDecl] of wireAddonDeclarations.entries()) {
-        for (const [logicalName, resolvedName] of Object.entries(addonDecl.credentialOverrides ?? {})) {
+        for (const [logicalName, override] of Object.entries(addonDecl.credentialOverrides ?? {})) {
+            // A mode-only override still names a credential — the addon's own. It
+            // has to exist, or generation resolves nothing and the credential keeps
+            // its default mode with no sign that the wiring asked for another.
+            const renamed = renameTarget(override);
+            const resolvedName = renamed ?? logicalName;
             if (!credentialNames.has(resolvedName)) {
                 const availableCredentials = Array.from(credentialNames);
-                logger.critical(ErrorCode.INVALID_VALUE, `Credential override '${logicalName}' -> '${resolvedName}' in addon '${namespace}' (${addonDecl.package}) targets a credential that does not exist. Available credentials: ${availableCredentials.join(', ') || 'none'}`);
+                const target = renamed
+                    ? `'${logicalName}' -> '${resolvedName}'`
+                    : `'${logicalName}'`;
+                logger.critical(ErrorCode.INVALID_VALUE, `Credential override ${target} in addon '${namespace}' (${addonDecl.package}) targets a credential that does not exist. Available credentials: ${availableCredentials.join(', ') || 'none'}`);
             }
+            const mode = overrideMode(override);
+            if (!mode)
+                continue;
+            const claim = modeClaims.get(resolvedName);
+            if (claim && claim.mode !== mode) {
+                logger.critical(ErrorCode.INVALID_VALUE, `Credential '${resolvedName}' is wired '${claim.mode}' by '${claim.logicalName}' in addon '${claim.namespace}' and '${mode}' by '${logicalName}' in addon '${namespace}'. One credential holds one mode, so the second wiring would silently take the first's resolution. Give them separate names, or wire both the same way.`);
+            }
+            modeClaims.set(resolvedName, { mode, namespace, logicalName });
         }
         for (const logicalName of addonDecl.credentialGrants ?? []) {
-            const resolvedName = addonDecl.credentialOverrides?.[logicalName] ?? logicalName;
+            const override = addonDecl.credentialOverrides?.[logicalName];
+            const resolvedName = (override ? renameTarget(override) : undefined) ?? logicalName;
             if (!credentialNames.has(resolvedName)) {
                 const availableCredentials = Array.from(credentialNames);
                 logger.critical(ErrorCode.INVALID_VALUE, `Credential grant '${logicalName}' in addon '${namespace}' (${addonDecl.package}) targets a credential that does not exist. Available credentials: ${availableCredentials.join(', ') || 'none'}`);
@@ -1029,6 +1057,15 @@ export function validateNoSecretAliasServices(logger, checker, state) {
  * at first request rather than at deploy; a non-literal key is a read the
  * manifest cannot cover, so a per-unit scope cannot be narrowed around it.
  */
+/**
+ * Registers the app secrets the project's OAuth2 credentials imply, so a
+ * deployment is asked for the client id and secret every connect flow needs
+ * without an author restating a shape the runtime already fixes.
+ */
+export function registerDerivedOAuth2AppSecrets(state) {
+    const derived = deriveOAuth2AppSecrets(state.credentials?.definitions ?? [], state.secrets.definitions);
+    state.secrets.definitions.push(...derived);
+}
 export function validateSecretUsage(logger, state) {
     const declared = new Set(state.secrets.definitions.map((d) => d.secretId));
     for (const definition of state.secrets.definitions) {

package/dist/utils/resolve-addon-package.d.ts

@@ -1,3 +1,4 @@
+import type { CredentialOverrideMeta } from '../types.js';
 import * as ts from 'typescript';
 /**
  * Resolve the addon package name from an imported identifier.
@@ -12,5 +13,5 @@ export declare const resolveAddonName: (identifier: ts.Identifier, checker: ts.T
     rpcEndpoint?: string;
     secretOverrides?: Record<string, string>;
     variableOverrides?: Record<string, string>;
-    credentialOverrides?: Record<string, string>;
+    credentialOverrides?: Record<string, CredentialOverrideMeta>;
 }>) => string | null;

package/dist/utils/serialize-inspector-state.d.ts

@@ -1,3 +1,4 @@
+import type { CredentialOverrideMeta } from '../types.js';
 import type { SecretUsage } from './extract-secret-usage.js';
 import type { JSONValue } from '@pikku/core/utils';
 import type { InspectorDiagnostic, InspectorFeature, InspectorState } from '../types.js';
@@ -197,7 +198,7 @@ export interface SerializableInspectorState {
                 authSecretId?: string;
                 secretOverrides?: Record<string, string>;
                 variableOverrides?: Record<string, string>;
-                credentialOverrides?: Record<string, string>;
+                credentialOverrides?: Record<string, CredentialOverrideMeta>;
                 secretGrants?: string[];
                 credentialGrants?: string[];
                 globalSecrets?: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/inspector",
-  "version": "0.12.82",
+  "version": "0.12.83",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/pikkujs/pikku.git",
@@ -55,10 +55,10 @@
     "zod-to-ts": "^2.1.0"
   },
   "peerDependencies": {
-    "@pikku/core": "^0.12.113"
+    "@pikku/core": "^0.12.114"
   },
   "devDependencies": {
-    "@pikku/core": "^0.12.113",
+    "@pikku/core": "^0.12.114",
     "@types/node": "^24.13.3"
   },
   "engines": {