@pikku/inspector 0.12.41 → 0.12.43

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

@@ -4,12 +4,21 @@ import { extractStringLiteral } from './extract-node-value.js';
 /**
  * Extracts an array of strings from an object property.
  */
+/**
+ * Unwraps `x as const` / `x as any` / `x satisfies T` down to the underlying
+ * expression. Without this a cast makes the value invisible to the inspector,
+ * so it is silently dropped from meta rather than validated — and `as const` on
+ * an array is idiomatic enough that this is easy to hit by accident.
+ */
+const unwrapAs = (node) => ts.isAsExpression(node) || ts.isSatisfiesExpression(node)
+    ? unwrapAs(node.expression)
+    : node;
 export const getArrayPropertyValue = (obj, propertyName) => {
     const property = obj.properties.find((p) => ts.isPropertyAssignment(p) &&
         ts.isIdentifier(p.name) &&
         p.name.text === propertyName);
     if (property && ts.isPropertyAssignment(property)) {
-        const initializer = property.initializer;
+        const initializer = unwrapAs(property.initializer);
         if (ts.isArrayLiteralExpression(initializer)) {
             return initializer.elements
                 .filter(ts.isStringLiteral)
@@ -18,6 +27,44 @@ export const getArrayPropertyValue = (obj, propertyName) => {
     }
     return null;
 };
+/**
+ * Extracts a string->string record from an object property.
+ *
+ * `getPropertyValue` falls through to `getText()` for an object literal, which
+ * returns the raw source text rather than the record — so callers that need the
+ * entries (e.g. oauth2 `additionalParams`) must use this instead.
+ */
+export const getRecordPropertyValue = (obj, propertyName) => {
+    const property = obj.properties.find((p) => ts.isPropertyAssignment(p) &&
+        ts.isIdentifier(p.name) &&
+        p.name.text === propertyName);
+    if (!property || !ts.isPropertyAssignment(property)) {
+        return null;
+    }
+    const initializer = property.initializer;
+    if (!ts.isObjectLiteralExpression(initializer)) {
+        return null;
+    }
+    const record = {};
+    for (const prop of initializer.properties) {
+        if (!ts.isPropertyAssignment(prop)) {
+            continue;
+        }
+        const key = ts.isIdentifier(prop.name)
+            ? prop.name.text
+            : ts.isStringLiteral(prop.name)
+                ? prop.name.text
+                : null;
+        if (key === null) {
+            continue;
+        }
+        if (ts.isStringLiteral(prop.initializer) ||
+            ts.isNoSubstitutionTemplateLiteral(prop.initializer)) {
+            record[key] = prop.initializer.text;
+        }
+    }
+    return Object.keys(record).length > 0 ? record : null;
+};
 /**
  * Wiring identity fields (`name`, `secretId`, `variableId`, …) are read
  * STATICALLY from source — a const or variable reference is keyed by its

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

@@ -80,6 +80,11 @@ export async function loadAddonFunctionsMeta(logger, state) {
         return;
     const require = createRequire(join(state.rootDir, 'package.json'));
     for (const [namespace, decl] of wireAddonDeclarations) {
+        // 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)
+            continue;
         try {
             const metaPath = require.resolve(`${decl.package}/.pikku/function/pikku-functions-meta.gen.json`);
             const raw = await readFile(metaPath, 'utf-8');
@@ -108,32 +113,99 @@ export async function loadAddonFunctionsMeta(logger, state) {
                 const secretsRaw = await readFile(secretsMetaPath, 'utf-8');
                 const secretsMeta = JSON.parse(secretsRaw);
                 for (const [key, def] of Object.entries(secretsMeta)) {
-                    const existing = state.secrets.definitions.find((d) => d.name === key);
+                    // secretOverrides key on the SECRET ID (the string the addon passes to
+                    // getSecret — its typed map is keyed by secretId, e.g.
+                    // `getSecret('MAILGUN_CREDENTIALS')`), NOT the logical meta key, so the
+                    // runtime aliaser (which also keys on secretId) and this merge agree.
+                    // The resolved id is the real project secret; the addon's secretId is
+                    // the default when no override is given. Two instances with different
+                    // overrides therefore surface two distinct project secrets. `key` is
+                    // the fallback for older meta that predates the secretId field.
+                    const secretId = def.secretId ?? key;
+                    const resolvedSecretId = decl.secretOverrides?.[secretId] ?? secretId;
+                    const existing = state.secrets.definitions.find((d) => (d.secretId ?? d.name) === resolvedSecretId);
                     if (!existing) {
-                        state.secrets.definitions.push(def);
-                        logger.debug(`Loaded addon secret '${key}' from ${decl.package}`);
+                        state.secrets.definitions.push({
+                            ...def,
+                            secretId: resolvedSecretId,
+                        });
+                        logger.debug(`Loaded addon secret '${resolvedSecretId}' from ${decl.package}`);
                     }
                 }
             }
             catch {
                 // No secrets meta — that's fine
             }
+            // Load addon scopes meta. Without this an addon's own scopes never reach
+            // the host's ScopeId union or its declared set, so the pikku_scopes FK
+            // would refuse to grant one.
+            try {
+                const scopesMetaPath = require.resolve(`${decl.package}/.pikku/scopes/pikku-scopes-meta.gen.json`);
+                const scopesRaw = await readFile(scopesMetaPath, 'utf-8');
+                const scopesMeta = JSON.parse(scopesRaw);
+                for (const [key, def] of Object.entries(scopesMeta)) {
+                    const existing = state.scopes.definitions.find((d) => d.name === key);
+                    if (!existing) {
+                        state.scopes.definitions.push(def);
+                        logger.debug(`Loaded addon scope '${key}' from ${decl.package}`);
+                    }
+                }
+            }
+            catch {
+                // No scopes meta — that's fine
+            }
             // Load addon variables meta
             try {
                 const variablesMetaPath = require.resolve(`${decl.package}/.pikku/variables/pikku-variables-meta.gen.json`);
                 const variablesRaw = await readFile(variablesMetaPath, 'utf-8');
                 const variablesMeta = JSON.parse(variablesRaw);
                 for (const [key, def] of Object.entries(variablesMeta)) {
-                    const existing = state.variables.definitions.find((d) => d.name === key);
+                    // variableOverrides key on the VARIABLE ID (the string the addon reads
+                    // via its typed map, keyed by variableId), same as secretOverrides key
+                    // on secretId — so the runtime aliaser and this merge agree. `key` is
+                    // the fallback for older meta without a variableId field.
+                    const variableId = def.variableId ?? key;
+                    const resolvedVariableId = decl.variableOverrides?.[variableId] ?? variableId;
+                    const existing = state.variables.definitions.find((d) => (d.variableId ?? d.name) === resolvedVariableId);
                     if (!existing) {
-                        state.variables.definitions.push(def);
-                        logger.debug(`Loaded addon variable '${key}' from ${decl.package}`);
+                        state.variables.definitions.push({
+                            ...def,
+                            variableId: resolvedVariableId,
+                        });
+                        logger.debug(`Loaded addon variable '${resolvedVariableId}' from ${decl.package}`);
                     }
                 }
             }
             catch {
                 // No variables meta — that's fine
             }
+            // Load addon credentials meta. Without this an addon's OAuth2/wire
+            // credentials never reach the consuming app's CREDENTIAL_OAUTH2_CONFIGS,
+            // so the credential-oauth provider and BetterAuthCredentialService can't
+            // resolve them — the addon's Connect flow and status silently no-op.
+            try {
+                const credentialsMetaPath = require.resolve(`${decl.package}/.pikku/credentials/pikku-credentials-meta.gen.json`);
+                const credentialsRaw = await readFile(credentialsMetaPath, 'utf-8');
+                const credentialsMeta = JSON.parse(credentialsRaw);
+                for (const [key, def] of Object.entries(credentialsMeta)) {
+                    // Each instance's credentialOverrides remap the addon's logical
+                    // credential name to a project credential — same mechanic as secrets
+                    // and variables above. The credential name doubles as the better-auth
+                    // providerId (accounts keyed by providerId+userId), so two instances
+                    // with different overrides surface two distinct OAuth providers rather
+                    // than sharing one account pool. The logical name is the default when
+                    // no override is given.
+                    const resolvedName = decl.credentialOverrides?.[key] ?? key;
+                    const existing = state.credentials.definitions.find((d) => d.name === resolvedName);
+                    if (!existing) {
+                        state.credentials.definitions.push({ ...def, name: resolvedName });
+                        logger.debug(`Loaded addon credential '${resolvedName}' from ${decl.package}`);
+                    }
+                }
+            }
+            catch {
+                // No credentials meta — that's fine
+            }
             // Load addon serverlessIncompatible service names from pikku-addon-meta.gen.json
             let loadedParentServices = false;
             try {
@@ -215,6 +287,9 @@ export async function loadAddonSchemas(logger, state) {
         return;
     const require = createRequire(join(state.rootDir, 'package.json'));
     for (const [namespace, decl] of wireAddonDeclarations) {
+        // Remote addons carry no local schemas — their funcs run on the host.
+        if (decl.remote)
+            continue;
         try {
             const metaPath = require.resolve(`${decl.package}/.pikku/function/pikku-functions-meta.gen.json`);
             const schemasDir = join(dirname(metaPath), '..', 'schemas', 'schemas');

package/dist/utils/nested-project-filter.d.ts

@@ -0,0 +1 @@
+export declare const createNestedProjectFilter: (rootDir: string) => (fileName: string) => boolean;

package/dist/utils/nested-project-filter.js

@@ -0,0 +1,29 @@
+import { existsSync } from 'fs';
+import { dirname, join } from 'path';
+export const createNestedProjectFilter = (rootDir) => {
+    const cache = new Map();
+    return (fileName) => {
+        const pending = [];
+        let dir = dirname(fileName);
+        let nested = false;
+        while (dir.startsWith(rootDir) && dir !== rootDir) {
+            const cached = cache.get(dir);
+            if (cached !== undefined) {
+                nested = cached;
+                break;
+            }
+            pending.push(dir);
+            if (existsSync(join(dir, 'pikku.config.json'))) {
+                nested = true;
+                break;
+            }
+            const parent = dirname(dir);
+            if (parent === dir)
+                break;
+            dir = parent;
+        }
+        for (const d of pending)
+            cache.set(d, nested);
+        return nested;
+    };
+};

package/dist/utils/permissions.d.ts

@@ -16,28 +16,8 @@ export declare function extractPermissionPikkuNames(node: ts.Expression, checker
  * Returns the initializer node for the 'permissions' property if it exists
  */
 export declare function getPermissionsNode(obj: ts.ObjectLiteralExpression): ts.Expression | undefined;
-/**
- * Check if a route matches a pattern with wildcards
- * Pattern can be exact match or use * as wildcard
- * e.g., '/api/*' matches '/api/users', '/api/posts/123', etc.
- */
-export declare function routeMatchesPattern(route: string, pattern: string): boolean;
-/**
- * Resolve permissions for an HTTP wiring based on:
- * 1. Global HTTP permissions (addHTTPPermission('*', [...]))
- * 2. Route-specific HTTP permissions (addHTTPPermission('/pattern', [...]))
- * 3. Tag-based permissions (addPermission('tag', [...]))
- * 4. Explicit wiring permissions (wireHTTP({ permissions: [...] }))
- * Returns undefined if no permissions are found, otherwise returns array with at least one item
- */
-export declare function resolveHTTPPermissions(state: InspectorState, route: string, tags: string[] | undefined, explicitPermissionsNode: ts.Expression | undefined, checker: ts.TypeChecker): PermissionMetadata[] | undefined;
 /**
  * Convenience wrapper: Extract permissions node from object and resolve
  * Use this in add-* files for cleaner code
  */
-export declare function resolvePermissions(state: InspectorState, obj: ts.ObjectLiteralExpression, tags: string[] | undefined, checker: ts.TypeChecker): PermissionMetadata[] | undefined;
-/**
- * Convenience wrapper for HTTP: Extract permissions and resolve with HTTP-specific logic
- * Use this in add-http-route.ts for cleaner code
- */
-export declare function resolveHTTPPermissionsFromObject(state: InspectorState, route: string, obj: ts.ObjectLiteralExpression, tags: string[] | undefined, checker: ts.TypeChecker): PermissionMetadata[] | undefined;
+export declare function resolvePermissions(state: InspectorState, obj: ts.ObjectLiteralExpression, _tags: string[] | undefined, checker: ts.TypeChecker): PermissionMetadata[] | undefined;

package/dist/utils/permissions.js

@@ -57,122 +57,31 @@ export function getPermissionsNode(obj) {
     return permissionsProp?.initializer;
 }
 /**
- * Check if a route matches a pattern with wildcards
- * Pattern can be exact match or use * as wildcard
- * e.g., '/api/*' matches '/api/users', '/api/posts/123', etc.
+ * Resolve the explicit permission references declared on a function (or agent).
+ * Permissions are function-scoped only: a `permissions: { group: [fn] }` object
+ * is flattened to `{ type: 'wire', name }` references used at filter time.
+ * Returns undefined if none are declared, otherwise an array with ≥1 item.
  */
-export function routeMatchesPattern(route, pattern) {
-    if (route === pattern)
-        return true;
-    // Convert pattern to regex: replace * with .*
-    const regexPattern = pattern
-        .replace(/[.+?^${}()|[\]\\]/g, '\\$&') // Escape regex special chars except *
-        .replace(/\*/g, '.*'); // Replace * with .*
-    const regex = new RegExp(`^${regexPattern}$`);
-    return regex.test(route);
-}
-/**
- * Resolve permissions for an HTTP wiring based on:
- * 1. Global HTTP permissions (addHTTPPermission('*', [...]))
- * 2. Route-specific HTTP permissions (addHTTPPermission('/pattern', [...]))
- * 3. Tag-based permissions (addPermission('tag', [...]))
- * 4. Explicit wiring permissions (wireHTTP({ permissions: [...] }))
- * Returns undefined if no permissions are found, otherwise returns array with at least one item
- */
-export function resolveHTTPPermissions(state, route, tags, explicitPermissionsNode, checker) {
-    const resolved = [];
-    // 1. HTTP route permission groups (includes '*' for global)
-    for (const [pattern, _groupMeta] of state.http.routePermissions.entries()) {
-        if (routeMatchesPattern(route, pattern)) {
-            // Just reference the group by route pattern
-            resolved.push({
-                type: 'http',
-                route: pattern,
-            });
-        }
-    }
-    // 2. Tag-based permission groups
-    if (tags && tags.length > 0) {
-        for (const tag of tags) {
-            if (state.permissions.tagPermissions.has(tag)) {
-                // Just reference the group by tag
-                resolved.push({
-                    type: 'tag',
-                    tag,
-                });
-            }
-        }
-    }
-    // 3. Explicit wire permissions (inline is OK here)
-    if (explicitPermissionsNode) {
-        const permissionNames = extractPermissionPikkuNames(explicitPermissionsNode, checker, state.rootDir);
-        for (const name of permissionNames) {
-            const def = state.permissions.definitions[name];
-            resolved.push({
-                type: 'wire',
-                name,
-                inline: def?.exportedName === null,
-            });
-        }
+function resolveExplicitPermissions(state, explicitPermissionsNode, checker) {
+    if (!explicitPermissionsNode) {
+        return undefined;
     }
-    return resolved.length > 0 ? resolved : undefined;
-}
-/**
- * Resolve tag-based and explicit permissions (common logic for wires and functions)
- * 1. Tag-based permissions (addPermission('tag', [...]))
- * 2. Explicit permissions (wireHTTP/pikkuFunc({ permissions: [...] }))
- */
-function resolveTagAndExplicitPermissions(state, tags, explicitPermissionsNode, checker) {
     const resolved = [];
-    // 1. Tag-based permission groups
-    if (tags && tags.length > 0) {
-        for (const tag of tags) {
-            if (state.permissions.tagPermissions.has(tag)) {
-                // Just reference the group by tag
-                resolved.push({
-                    type: 'tag',
-                    tag,
-                });
-            }
-        }
-    }
-    // 2. Explicit permissions (inline is OK here - used directly in wire/function)
-    if (explicitPermissionsNode) {
-        const permissionNames = extractPermissionPikkuNames(explicitPermissionsNode, checker, state.rootDir);
-        for (const name of permissionNames) {
-            const def = state.permissions.definitions[name];
-            resolved.push({
-                type: 'wire',
-                name,
-                inline: def?.exportedName === null,
-            });
-        }
+    const permissionNames = extractPermissionPikkuNames(explicitPermissionsNode, checker, state.rootDir);
+    for (const name of permissionNames) {
+        const def = state.permissions.definitions[name];
+        resolved.push({
+            type: 'wire',
+            name,
+            inline: def?.exportedName === null,
+        });
     }
-    return resolved;
-}
-/**
- * Resolve permissions for a function based on:
- * 1. Tag-based permissions (addPermission('tag', [...]))
- * 2. Explicit function permissions (pikkuFunc({ permissions: [...] }))
- * Returns undefined if no permissions are found, otherwise returns array with at least one item
- */
-function resolveFunctionPermissionsInternal(state, tags, explicitPermissionsNode, checker) {
-    const resolved = resolveTagAndExplicitPermissions(state, tags, explicitPermissionsNode, checker);
     return resolved.length > 0 ? resolved : undefined;
 }
 /**
  * Convenience wrapper: Extract permissions node from object and resolve
  * Use this in add-* files for cleaner code
  */
-export function resolvePermissions(state, obj, tags, checker) {
-    const explicitPermissionsNode = getPermissionsNode(obj);
-    return resolveFunctionPermissionsInternal(state, tags, explicitPermissionsNode, checker);
-}
-/**
- * Convenience wrapper for HTTP: Extract permissions and resolve with HTTP-specific logic
- * Use this in add-http-route.ts for cleaner code
- */
-export function resolveHTTPPermissionsFromObject(state, route, obj, tags, checker) {
-    const explicitPermissionsNode = getPermissionsNode(obj);
-    return resolveHTTPPermissions(state, route, tags, explicitPermissionsNode, checker);
+export function resolvePermissions(state, obj, _tags, checker) {
+    return resolveExplicitPermissions(state, getPermissionsNode(obj), checker);
 }

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

@@ -19,7 +19,7 @@ export declare function stampAuthHandlerServices(state: InspectorState | Omit<In
  * Only extracts type:'wire' variants (individual middleware/permissions).
  * Skips type:'http' and type:'tag' (reference groups, not individuals).
  */
-export declare function extractWireNames(list?: MiddlewareMetadata[] | PermissionMetadata[]): string[];
+export declare function extractWireNames(list?: Array<MiddlewareMetadata | PermissionMetadata>): string[];
 /**
  * Aggregates all required services from wired functions, middleware, and permissions.
  * Must be called after AST traversal completes.
@@ -31,11 +31,32 @@ export declare function aggregateRequiredServices(state: InspectorState | Omit<I
 export declare function validateSecretOverrides(logger: InspectorLogger, state: InspectorState | Omit<InspectorState, 'typesLookup'>): void;
 export declare function validateCredentialOverrides(logger: InspectorLogger, state: InspectorState | Omit<InspectorState, 'typesLookup'>): void;
 export declare function validateVariableOverrides(logger: InspectorLogger, state: InspectorState | Omit<InspectorState, 'typesLookup'>): void;
+/**
+ * A `wireRemoteAddon` package ships types only — its handlers run on the host —
+ * so it MUST be a devDependency, not a production dependency (a prod dep would
+ * drag in the runtime deps remote consumption exists to avoid). This is the
+ * mirror image of `wireAddon`, which requires a production dependency.
+ */
+export declare function validateRemoteAddonDependencies(logger: InspectorLogger, state: InspectorState | Omit<InspectorState, 'typesLookup'>): void;
+/**
+ * The auth a `wireRemoteAddon` consumer binds must reference a slot the consumer
+ * actually declares: a `credentialId` must be a wired credential, a `secretId`
+ * a wired secret. A custom `resolve()` and a public (omitted) surface are not
+ * statically checkable and are left to runtime.
+ */
+export declare function validateRemoteAddonAuth(logger: InspectorLogger, state: InspectorState | Omit<InspectorState, 'typesLookup'>): void;
 export declare function computeResolvedIOTypes(state: InspectorState): void;
 export declare function computeMiddlewareGroupsMeta(state: InspectorState): void;
 export declare function computePermissionsGroupsMeta(state: InspectorState): void;
 export declare function computeRequiredSchemas(state: InspectorState, options: InspectorOptions): void;
 export declare function validateAgentModels(logger: InspectorLogger, state: InspectorState | Omit<InspectorState, 'typesLookup'>): void;
+/**
+ * A `pikkuWorkflowGraph` node that references the `graph:` namespace (e.g.
+ * `graph:editFields`) needs @pikku/addon-graph wired — otherwise the RPC never
+ * registers and codegen fails deep in type-checking with an opaque error. Fail
+ * early with an actionable message pointing at `scaffold: { graph: true }`.
+ */
+export declare function validateWorkflowGraphAddons(logger: InspectorLogger, state: InspectorState): void;
 /**
  * Validates that Zod schemas and wiring side-effects (wireHTTPRoutes,
  * addPermission, addHTTPMiddleware, etc.) do not coexist in the same file.
@@ -46,3 +67,11 @@ export declare function validateAgentModels(logger: InspectorLogger, state: Insp
  */
 export declare function validateSchemaWiringSeparation(logger: InspectorLogger, state: InspectorState): void;
 export declare function computeDiagnostics(state: InspectorState): void;
+/**
+ * Validates that every scope referenced by a function is declared via
+ * `wireScope`. Runs after all visitors, so declaration order does not matter.
+ *
+ * A `*` suffix is a wildcard requirement: `admin:*` requires the `admin` scope
+ * to be declared, and grants its whole subtree.
+ */
+export declare function validateScopeReferences(logger: InspectorLogger, state: InspectorState | Omit<InspectorState, 'typesLookup'>): void;