@pikku/cli 0.12.82 → 0.12.83

package/dist/src/functions/wirings/functions/serialize-function-types.js

@@ -1,13 +1,16 @@
 /**
  * Generates core function, middleware, and permission type definitions
  */
-export const serializeFunctionTypes = (userSessionTypeImport, userSessionTypeName, singletonServicesTypeImport, singletonServicesTypeName, wireServicesTypeImport, wireServicesTypeName, rpcMapTypeImport, requiredServicesTypeImport, configTypeImport, packageName, workflowTypesImport, nodeCategories) => {
+export const serializeFunctionTypes = (userSessionTypeImport, userSessionTypeName, singletonServicesTypeImport, singletonServicesTypeName, wireServicesTypeImport, wireServicesTypeName, rpcMapTypeImport, requiredServicesTypeImport, configTypeImport, packageName, workflowTypesImport, nodeCategories, scopesTypeImport) => {
     const packageNameValue = packageName ? `'${packageName}'` : 'null';
     const nodeCategoryType = nodeCategories?.length
         ? nodeCategories.map((c) => `'${c}'`).join(' | ')
         : 'string';
     const workflowImport = workflowTypesImport ||
         `import type { TypedWorkflow, TypedScenario } from '../workflow/pikku-workflow-types.gen.js'`;
+    // Falls back to `string` when a project has no scopes codegen, so that
+    // `scopes` stays usable rather than resolving to an unbound type name.
+    const scopesImport = scopesTypeImport || `type ScopeId = string`;
     return `/**
  * Core function, middleware, and permission types for all wirings
  */
@@ -18,11 +21,11 @@ import { pikkuAuth as pikkuAuthCore } from '@pikku/core/function'
 import {
   addTagMiddleware as addTagMiddlewareCore,
   addGlobalMiddleware as addGlobalMiddlewareCore,
-  addTagPermission as addTagPermissionCore,
   addGlobalPermission as addGlobalPermissionCore,
 } from '@pikku/core/middleware'
 import { pikkuState as __pikkuState, CreateWireServices } from '@pikku/core/internal'
 import type { NodeType } from '@pikku/core/node'
+${scopesImport}
 import type { StandardSchemaV1 } from '@standard-schema/spec'
 import { CorePikkuFunction, CorePikkuFunctionSessionless } from '@pikku/core/function'
 
@@ -329,7 +332,7 @@ export type PikkuFunctionConfig<
   PikkuFunc extends PikkuFunction<In, Out, RequiredWires> | PikkuFunctionSessionless<In, Out, RequiredWires> = PikkuFunction<In, Out, RequiredWires> | PikkuFunctionSessionless<In, Out, RequiredWires>,
   InputSchema extends StandardSchemaV1 | undefined = undefined,
   OutputSchema extends StandardSchemaV1 | undefined = undefined
-> = CorePikkuFunctionConfig<PikkuFunc, PikkuPermission<In>, PikkuMiddleware, InputSchema, OutputSchema>
+> = CorePikkuFunctionConfig<PikkuFunc, PikkuPermission<In>, PikkuMiddleware, InputSchema, OutputSchema, ScopeId>
 
 /**
  * Configuration object for Pikku functions with Zod schema validation.
@@ -351,7 +354,12 @@ export type PikkuFunctionConfigWithSchema<
 > = Omit<
   CorePikkuFunctionConfig<
     | PikkuFunction<SchemaInferred<InputSchema>, SchemaInferred<OutputSchema>, RequiredWires>
-    | PikkuFunctionSessionless<SchemaInferred<InputSchema>, SchemaInferred<OutputSchema>, RequiredWires>
+    | PikkuFunctionSessionless<SchemaInferred<InputSchema>, SchemaInferred<OutputSchema>, RequiredWires>,
+    CorePikkuPermission<any>,
+    PikkuMiddleware,
+    undefined,
+    undefined,
+    ScopeId
   >,
   'func' | 'input' | 'output' | 'permissions' | 'approvalDescription'
 > & {
@@ -681,16 +689,6 @@ export const addGlobalMiddleware = (middleware: PikkuMiddleware[]) => {
   addGlobalMiddlewareCore(middleware as any, ${packageNameValue})
 }
 
-/**
- * Tag-scoped permissions. Applies to any wiring that carries the matching tag.
- *
- * @example
- * addTagPermission('admin', [adminPermission])
- */
-export const addTagPermission = <In = unknown>(tag: string, permissions: CorePermissionGroup<PikkuPermission<In>> | PikkuPermission<In>[]) => {
-  addTagPermissionCore(tag, permissions as any, ${packageNameValue})
-}
-
 /**
  * Wire-agnostic global permissions. Runs at the top of every wiring's
  * permission resolution — before wire-, tag-, and function-level entries.
@@ -704,7 +702,7 @@ export const addGlobalPermission = <In = unknown>(permissions: CorePermissionGro
   addGlobalPermissionCore(permissions as any, ${packageNameValue})
 }
 
-export { wireAddon } from '@pikku/core/rpc'
-export type { WireAddonConfig } from '@pikku/core/rpc'
+export { wireAddon, wireRemoteAddon } from '@pikku/core/rpc'
+export type { WireAddonConfig, WireRemoteAddonConfig, RemoteAddonAuth } from '@pikku/core/rpc'
 `;
 };

package/dist/src/functions/wirings/functions/serialize-pikku-types-hub.d.ts

@@ -1,4 +1,4 @@
 /**
  * Generates the main pikku-types.gen.ts file as a re-export hub
  */
-export declare const serializePikkuTypesHub: (functionTypesImportPath: string, httpTypesImportPath: string | null, channelTypesImportPath: string | null, triggerTypesImportPath: string | null, schedulerTypesImportPath: string | null, queueTypesImportPath: string | null, mcpTypesImportPath: string | null, cliTypesImportPath: string | null, nodeTypesImportPath: string | null, secretTypesImportPath: string | null, addonTypesImportPath: string | null, authTypesImportPath?: string | null) => string;
+export declare const serializePikkuTypesHub: (functionTypesImportPath: string, httpTypesImportPath: string | null, channelTypesImportPath: string | null, triggerTypesImportPath: string | null, schedulerTypesImportPath: string | null, queueTypesImportPath: string | null, mcpTypesImportPath: string | null, cliTypesImportPath: string | null, nodeTypesImportPath: string | null, secretTypesImportPath: string | null, addonTypesImportPath: string | null, authTypesImportPath?: string | null, scopeTypesImportPath?: string | null) => string;

package/dist/src/functions/wirings/functions/serialize-pikku-types-hub.js

@@ -1,7 +1,7 @@
 /**
  * Generates the main pikku-types.gen.ts file as a re-export hub
  */
-export const serializePikkuTypesHub = (functionTypesImportPath, httpTypesImportPath, channelTypesImportPath, triggerTypesImportPath, schedulerTypesImportPath, queueTypesImportPath, mcpTypesImportPath, cliTypesImportPath, nodeTypesImportPath, secretTypesImportPath, addonTypesImportPath, authTypesImportPath = null) => {
+export const serializePikkuTypesHub = (functionTypesImportPath, httpTypesImportPath, channelTypesImportPath, triggerTypesImportPath, schedulerTypesImportPath, queueTypesImportPath, mcpTypesImportPath, cliTypesImportPath, nodeTypesImportPath, secretTypesImportPath, addonTypesImportPath, authTypesImportPath = null, scopeTypesImportPath = null) => {
     const exports = [
         {
             comment: 'Core function, middleware, and permission types',
@@ -16,8 +16,12 @@ export const serializePikkuTypesHub = (functionTypesImportPath, httpTypesImportP
         { comment: 'CLI wiring types', path: cliTypesImportPath },
         { comment: 'Node wiring types', path: nodeTypesImportPath },
         { comment: 'Secret definition types', path: secretTypesImportPath },
+        { comment: 'Scope definition types', path: scopeTypesImportPath },
         { comment: 'Addon types', path: addonTypesImportPath },
-        { comment: 'Auth types (typed pikkuBetterAuth re-export)', path: authTypesImportPath },
+        {
+            comment: 'Auth types (typed pikkuBetterAuth re-export)',
+            path: authTypesImportPath,
+        },
     ];
     const exportStatements = exports
         .filter((e) => e.path)

package/dist/src/functions/wirings/graph/pikku-command-graph-wirings.d.ts

@@ -0,0 +1 @@
+export declare const pikkuGraphWirings: import("#pikku").PikkuFunctionConfig<void, boolean, "rpc" | "session", import("#pikku").PikkuFunctionSessionless<void, boolean, "rpc" | "session", import("#pikku").Services> | import("#pikku").PikkuFunction<void, boolean, "rpc" | "session", import("#pikku").Services>, undefined, undefined>;

package/dist/src/functions/wirings/graph/pikku-command-graph-wirings.js

@@ -0,0 +1,21 @@
+import { pikkuSessionlessFunc } from '#pikku';
+import { getFileImportRelativePath } from '../../../utils/file-import-path.js';
+import { writeFileInDir } from '../../../utils/file-writer.js';
+import { logCommandInfoAndTime } from '../../../middleware/log-command-info-and-time.js';
+import { serializeGraphWirings } from './serialize-graph-wirings.js';
+export const pikkuGraphWirings = pikkuSessionlessFunc({
+    func: async ({ logger, config }) => {
+        if (config.scaffold?.graph && config.graphWiringsFile) {
+            const pathToPikkuTypes = getFileImportRelativePath(config.graphWiringsFile, config.typesDeclarationFile, config.packageMappings);
+            await writeFileInDir(logger, config.graphWiringsFile, serializeGraphWirings(pathToPikkuTypes));
+            return true;
+        }
+        return false;
+    },
+    middleware: [
+        logCommandInfoAndTime({
+            commandStart: 'Generating Graph Wirings',
+            commandEnd: 'Generated Graph Wirings',
+        }),
+    ],
+});

package/dist/src/functions/wirings/graph/serialize-graph-wirings.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Wire @pikku/addon-graph so `pikkuWorkflowGraph` nodes can reference its native
+ * transform functions (e.g. `graph:editFields`).
+ */
+export declare const serializeGraphWirings: (pathToPikkuTypes: string) => string;

package/dist/src/functions/wirings/graph/serialize-graph-wirings.js

@@ -0,0 +1,14 @@
+/**
+ * Wire @pikku/addon-graph so `pikkuWorkflowGraph` nodes can reference its native
+ * transform functions (e.g. `graph:editFields`).
+ */
+export const serializeGraphWirings = (pathToPikkuTypes) => {
+    return `/**
+ * @pikku/addon-graph wiring
+ * Do not edit manually - regenerate with 'npx pikku'
+ */
+import { wireAddon } from '${pathToPikkuTypes}'
+
+wireAddon({ name: 'graph', package: '@pikku/addon-graph' })
+`;
+};

package/dist/src/functions/wirings/http/serialize-http-types.js

@@ -6,7 +6,7 @@ export const serializeHTTPTypes = (functionTypesImportPath) => {
  * HTTP-specific type definitions for tree-shaking optimization
  */
 
-import { AssertHTTPWiringParams, wireHTTP as wireHTTPCore, addHTTPMiddleware as addHTTPMiddlewareCore, addHTTPPermission as addHTTPPermissionCore, wireHTTPRoutes as wireHTTPRoutesCore, defineHTTPRoutes as defineHTTPRoutesCore } from '@pikku/core/http'
+import { AssertHTTPWiringParams, wireHTTP as wireHTTPCore, addHTTPMiddleware as addHTTPMiddlewareCore, wireHTTPRoutes as wireHTTPRoutesCore, defineHTTPRoutes as defineHTTPRoutesCore } from '@pikku/core/http'
 import type { PikkuFunction, PikkuFunctionSessionless, PikkuPermission, PikkuMiddleware, PikkuFunctionConfig } from '${functionTypesImportPath}'
 import type { CoreHTTPFunctionWiring, HTTPMethod, HTTPRouteBaseConfig } from '@pikku/core/http'
 
@@ -60,32 +60,6 @@ export const addHTTPMiddleware = (
   addHTTPMiddlewareCore(routeOrMiddleware as any, middleware as any)
 }
 
-/**
- * Registers HTTP permissions either globally or for a specific route pattern.
- *
- * When a string route pattern is provided along with permissions, the permissions
- * are applied only to that route. Permissions can be passed as an array or as a
- * permission group object.
- *
- * @param pattern - Route pattern string (e.g., '*' for all routes, '/api/*' for specific routes)
- * @param permissions - The permissions to apply for the specified route pattern
- *
- * @example
- * \`\`\`typescript
- * // Add global HTTP permissions
- * addHTTPPermission('*', { global: globalPermission })
- *
- * // Add route-specific permissions
- * addHTTPPermission('/api/admin/*', { admin: adminPermission })
- * \`\`\`
- */
-export const addHTTPPermission = <In = unknown>(
-  pattern: string,
-  permissions: Record<string, PikkuPermission<In>> | PikkuPermission<In>[]
-) => {
-  addHTTPPermissionCore(pattern, permissions as any)
-}
-
 /**
  * Route configuration for wireHTTPRoutes with proper typing
  */
@@ -94,7 +68,6 @@ type HTTPRouteConfig = HTTPRouteBaseConfig & {
   route: string
   func: PikkuFunctionConfig<any, any, any, any, any, any>
   auth?: boolean
-  permissions?: Record<string, PikkuPermission | PikkuPermission[]>
   middleware?: PikkuMiddleware[]
   sse?: boolean
 }
@@ -114,14 +87,13 @@ type TypedHTTPRouteContract<T extends TypedHTTPRouteMap = TypedHTTPRouteMap> = T
 }
 
 /**
- * Group config with typed middleware/permissions
+ * Group config with typed middleware
  */
 type TypedHTTPRoutesGroupConfig = {
   basePath?: string
   tags?: string[]
   auth?: boolean
   middleware?: PikkuMiddleware[]
-  permissions?: Record<string, PikkuPermission | PikkuPermission[]>
 }
 
 /**

package/dist/src/functions/wirings/package/pikku-command-package-types.d.ts

@@ -1,2 +1,3 @@
 export declare const pikkuSecretDefinitionTypes: import("#pikku").PikkuFunctionConfig<void, void, "rpc" | "session", import("#pikku").PikkuFunctionSessionless<void, void, "rpc" | "session", import("#pikku").Services> | import("#pikku").PikkuFunction<void, void, "rpc" | "session", import("#pikku").Services>, undefined, undefined>;
+export declare const pikkuScopeDefinitionTypes: import("#pikku").PikkuFunctionConfig<void, void, "rpc" | "session", import("#pikku").PikkuFunctionSessionless<void, void, "rpc" | "session", import("#pikku").Services> | import("#pikku").PikkuFunction<void, void, "rpc" | "session", import("#pikku").Services>, undefined, undefined>;
 export declare const pikkuVariableDefinitionTypes: import("#pikku").PikkuFunctionConfig<void, void, "rpc" | "session", import("#pikku").PikkuFunctionSessionless<void, void, "rpc" | "session", import("#pikku").Services> | import("#pikku").PikkuFunction<void, void, "rpc" | "session", import("#pikku").Services>, undefined, undefined>;

package/dist/src/functions/wirings/package/pikku-command-package-types.js

@@ -1,7 +1,7 @@
 import { pikkuVoidFunc } from '#pikku';
 import { writeFileInDir } from '../../../utils/file-writer.js';
 import { logCommandInfoAndTime } from '../../../middleware/log-command-info-and-time.js';
-import { serializeSecretDefinitionTypes, serializeVariableDefinitionTypes, } from './serialize-package-types.js';
+import { serializeScopeDefinitionTypes, serializeSecretDefinitionTypes, serializeVariableDefinitionTypes, } from './serialize-package-types.js';
 export const pikkuSecretDefinitionTypes = pikkuVoidFunc({
     func: async ({ logger, config }) => {
         const { secretTypesFile } = config;
@@ -15,6 +15,19 @@ export const pikkuSecretDefinitionTypes = pikkuVoidFunc({
         }),
     ],
 });
+export const pikkuScopeDefinitionTypes = pikkuVoidFunc({
+    func: async ({ logger, config }) => {
+        const { scopeTypesFile } = config;
+        const content = serializeScopeDefinitionTypes();
+        await writeFileInDir(logger, scopeTypesFile, content);
+    },
+    middleware: [
+        logCommandInfoAndTime({
+            commandStart: 'Creating Scope definition types',
+            commandEnd: 'Created Scope definition types',
+        }),
+    ],
+});
 export const pikkuVariableDefinitionTypes = pikkuVoidFunc({
     func: async ({ logger, config }) => {
         const { variableTypesFile } = config;

package/dist/src/functions/wirings/package/serialize-package-types.d.ts

@@ -1,2 +1,3 @@
 export declare const serializeSecretDefinitionTypes: () => string;
+export declare const serializeScopeDefinitionTypes: () => string;
 export declare const serializeVariableDefinitionTypes: () => string;

package/dist/src/functions/wirings/package/serialize-package-types.js

@@ -3,6 +3,11 @@ export const serializeSecretDefinitionTypes = () => {
 export type { CoreSecret, SecretDefinitionMeta, SecretDefinitionsMeta } from '@pikku/core/secret'
 `;
 };
+export const serializeScopeDefinitionTypes = () => {
+    return `export { wireScope } from '@pikku/core/scope'
+export type { CoreScopes, CoreScopeNode, FlatScope, ScopeDefinitionMeta, ScopeDefinitionsMeta } from '@pikku/core/scope'
+`;
+};
 export const serializeVariableDefinitionTypes = () => {
     return `export { wireVariable } from '@pikku/core/variable'
 export type { CoreVariable, VariableDefinitionMeta, VariableDefinitionsMeta } from '@pikku/core/variable'

package/dist/src/functions/wirings/permissions/pikku-command-permissions.js

@@ -8,10 +8,8 @@ export const pikkuPermissions = pikkuSessionlessFunc({
         const { permissions } = state;
         const { permissionsFile, packageMappings } = config;
         let filesGenerated = false;
-        const hasHTTPGroups = state.http.routePermissions.size > 0;
-        const hasTagGroups = state.permissions.tagPermissions.size > 0;
         const hasIndividual = Object.keys(state.permissions.definitions).length > 0;
-        if (hasHTTPGroups || hasTagGroups || hasIndividual) {
+        if (hasIndividual) {
             const metaData = state.permissionsGroupsMeta;
             await writeFileInDir(logger, config.permissionsGroupsMetaJsonFile, JSON.stringify(metaData, null, 2));
             await writeFileInDir(logger, permissionsFile, serializePermissionsImports(permissionsFile, permissions, state.http, packageMappings));

package/dist/src/functions/wirings/permissions/serialize-permissions-imports.d.ts

@@ -1,2 +1,7 @@
 import type { InspectorPermissionState, InspectorHTTPState, InspectorState } from '@pikku/inspector';
-export declare const serializePermissionsImports: (outputPath: string, permissionsState: InspectorPermissionState, httpState: InspectorHTTPState, packageMappings?: Record<string, string>, fullState?: InspectorState) => string;
+/**
+ * Permissions are function-scoped only — they are imported and passed inline
+ * wherever a function declares them, so there are no permission groups to
+ * register at module evaluation. This generator therefore emits nothing.
+ */
+export declare const serializePermissionsImports: (_outputPath: string, _permissionsState: InspectorPermissionState, _httpState: InspectorHTTPState, _packageMappings?: Record<string, string>, _fullState?: InspectorState) => string;

package/dist/src/functions/wirings/permissions/serialize-permissions-imports.js

@@ -1,65 +1,8 @@
-import { getFileImportRelativePath } from '../../../utils/file-import-path.js';
-export const serializePermissionsImports = (outputPath, permissionsState, httpState, packageMappings = {}, fullState) => {
-    const serializedImports = [];
-    const serializedFactoryCalls = [];
-    // Collect factory imports and calls for HTTP permission groups
-    const httpFactories = new Map();
-    for (const [, groupMeta] of httpState.routePermissions.entries()) {
-        if (groupMeta.exportName && groupMeta.isFactory) {
-            const filePath = getFileImportRelativePath(outputPath, groupMeta.sourceFile, packageMappings);
-            httpFactories.set(groupMeta.exportName, {
-                exportName: groupMeta.exportName,
-                filePath,
-            });
-        }
-    }
-    // Collect factory imports and calls for tag permission groups
-    const tagFactories = new Map();
-    for (const [, groupMeta] of permissionsState.tagPermissions.entries()) {
-        if (groupMeta.exportName && groupMeta.isFactory) {
-            const filePath = getFileImportRelativePath(outputPath, groupMeta.sourceFile, packageMappings);
-            tagFactories.set(groupMeta.exportName, {
-                exportName: groupMeta.exportName,
-                filePath,
-            });
-        }
-    }
-    // Collect direct (non-factory) side-effect imports for HTTP permission groups
-    const directImports = new Set();
-    for (const [, groupMeta] of httpState.routePermissions.entries()) {
-        if (!groupMeta.isFactory) {
-            const filePath = getFileImportRelativePath(outputPath, groupMeta.sourceFile, packageMappings);
-            directImports.add(filePath);
-        }
-    }
-    // Collect direct (non-factory) side-effect imports for tag permission groups
-    for (const [, groupMeta] of permissionsState.tagPermissions.entries()) {
-        if (!groupMeta.isFactory) {
-            const filePath = getFileImportRelativePath(outputPath, groupMeta.sourceFile, packageMappings);
-            directImports.add(filePath);
-        }
-    }
-    // Combine all factories and deduplicate by exportName (same factory might be used in multiple groups)
-    const allFactories = new Map([...httpFactories, ...tagFactories]);
-    // Add direct side-effect imports (non-factory addPermission calls)
-    if (directImports.size > 0) {
-        serializedImports.push('/* Side-effect imports for direct addPermission calls */');
-        for (const filePath of directImports) {
-            serializedImports.push(`import '${filePath}'`);
-        }
-    }
-    // Add factory imports and calls
-    if (allFactories.size > 0) {
-        serializedImports.push('/* Call permission group factories to register at module evaluation */');
-        // Import factories
-        for (const [exportName, { filePath }] of allFactories) {
-            serializedImports.push(`import { ${exportName} } from '${filePath}'`);
-        }
-        // Call factories
-        for (const [exportName] of allFactories) {
-            serializedFactoryCalls.push(`${exportName}()`);
-        }
-    }
-    // Return combined output
-    return [...serializedImports, ...serializedFactoryCalls].join('\n');
+/**
+ * Permissions are function-scoped only — they are imported and passed inline
+ * wherever a function declares them, so there are no permission groups to
+ * register at module evaluation. This generator therefore emits nothing.
+ */
+export const serializePermissionsImports = (_outputPath, _permissionsState, _httpState, _packageMappings = {}, _fullState) => {
+    return '';
 };

package/dist/src/functions/wirings/rpc/pikku-command-rpc-map.d.ts

@@ -1,2 +1,7 @@
 export declare const pikkuRPCInternalMap: import("#pikku").PikkuFunctionConfig<void, void, "rpc" | "session", import("#pikku").PikkuFunctionSessionless<void, void, "rpc" | "session", import("#pikku").Services> | import("#pikku").PikkuFunction<void, void, "rpc" | "session", import("#pikku").Services>, undefined, undefined>;
 export declare const pikkuRPCExposedMap: import("#pikku").PikkuFunctionConfig<void, void, "rpc" | "session", import("#pikku").PikkuFunctionSessionless<void, void, "rpc" | "session", import("#pikku").Services> | import("#pikku").PikkuFunction<void, void, "rpc" | "session", import("#pikku").Services>, undefined, undefined>;
+/**
+ * The `remote: true` surface — what a `wireRemoteAddon` consumer imports.
+ * Mirrors the exposed map but is fed from `rpc.remoteMeta`.
+ */
+export declare const pikkuRPCRemoteMap: import("#pikku").PikkuFunctionConfig<void, void, "rpc" | "session", import("#pikku").PikkuFunctionSessionless<void, void, "rpc" | "session", import("#pikku").Services> | import("#pikku").PikkuFunction<void, void, "rpc" | "session", import("#pikku").Services>, undefined, undefined>;

package/dist/src/functions/wirings/rpc/pikku-command-rpc-map.js

@@ -35,3 +35,23 @@ export const pikkuRPCExposedMap = pikkuSessionlessFunc({
         }),
     ],
 });
+/**
+ * The `remote: true` surface — what a `wireRemoteAddon` consumer imports.
+ * Mirrors the exposed map but is fed from `rpc.remoteMeta`.
+ */
+export const pikkuRPCRemoteMap = pikkuSessionlessFunc({
+    func: async ({ logger, config, getInspectorState }) => {
+        const { functions, rpc, resolvedIOTypes } = await getInspectorState();
+        const { rpcRemoteMapDeclarationFile, packageMappings, workflowMapDeclarationFile, agentMapDeclarationFile, } = config;
+        const workflowMapPath = getFileImportRelativePath(rpcRemoteMapDeclarationFile, workflowMapDeclarationFile, packageMappings);
+        const agentMapPath = getFileImportRelativePath(rpcRemoteMapDeclarationFile, agentMapDeclarationFile, packageMappings);
+        const content = serializeTypedRPCMap(logger, rpcRemoteMapDeclarationFile, packageMappings, functions.typesMap, rpc.remoteMeta, resolvedIOTypes, rpc.wireAddonDeclarations, workflowMapPath, agentMapPath);
+        await writeFileInDir(logger, rpcRemoteMapDeclarationFile, content);
+    },
+    middleware: [
+        logCommandInfoAndTime({
+            commandStart: 'Creating RPC remote map',
+            commandEnd: 'Created RPC remote map',
+        }),
+    ],
+});

package/dist/src/functions/wirings/rpc/serialize-typed-rpc-map.d.ts

@@ -3,6 +3,7 @@ import type { Logger } from '@pikku/core/services';
 type WireAddonDeclarations = Map<string, {
     package: string;
     rpcEndpoint?: string;
+    remote?: boolean;
 }>;
 export declare const serializeTypedRPCMap: (logger: Logger, relativeToPath: string, packageMappings: Record<string, string>, typesMap: TypesMap, rpcMeta: Record<string, string>, resolvedIOTypes: Record<string, {
     inputType: string;

package/dist/src/functions/wirings/rpc/serialize-typed-rpc-map.js

@@ -106,9 +106,14 @@ function generateAddonImports(wireAddonDeclarations, relativeToPath) {
     }
     let imports = '\n// Addon package RPC maps\n';
     for (const [namespace, decl] of wireAddonDeclarations.entries()) {
-        // Import the RPCMap from each addon package's internal RPC map
-        // Use .js extension - package.json exports will resolve to .d.ts for types
-        imports += `import type { RPCMap as ${toPascalCase(namespace)}RPCMap } from '${decl.package}/.pikku/rpc/pikku-rpc-wirings-map.internal.gen.js'\n`;
+        // Import the RPCMap from each addon package's RPC map.
+        // A `wireRemoteAddon` namespace imports the addon's `.remote.gen` map (only
+        // its `remote: true` surface); a local `wireAddon` imports `.internal.gen`.
+        // Use .js extension — package.json exports resolve it to .d.ts for types.
+        const mapFile = decl.remote
+            ? 'pikku-rpc-wirings-map.remote.gen.js'
+            : 'pikku-rpc-wirings-map.internal.gen.js';
+        imports += `import type { RPCMap as ${toPascalCase(namespace)}RPCMap } from '${decl.package}/.pikku/rpc/${mapFile}'\n`;
     }
     return imports;
 }

package/dist/src/functions/wirings/scopes/pikku-command-scopes.d.ts

@@ -0,0 +1,7 @@
+export declare const pikkuScopes: import("#pikku").PikkuFunctionConfig<{
+    bootstrap?: boolean;
+}, void, "rpc" | "session", import("#pikku").PikkuFunctionSessionless<{
+    bootstrap?: boolean;
+}, void, "rpc" | "session", import("#pikku").Services> | import("#pikku").PikkuFunction<{
+    bootstrap?: boolean;
+}, void, "rpc" | "session", import("#pikku").Services>, undefined, undefined>;

package/dist/src/functions/wirings/scopes/pikku-command-scopes.js

@@ -0,0 +1,34 @@
+import { pikkuSessionlessFunc } from '#pikku';
+import { writeFileInDir } from '../../../utils/file-writer.js';
+import { logCommandInfoAndTime } from '../../../middleware/log-command-info-and-time.js';
+import { serializeScopesTypes } from './serialize-scopes-types.js';
+import { validateAndBuildScopeDefinitionsMeta } from '@pikku/core/scope';
+export const pikkuScopes = pikkuSessionlessFunc({
+    func: async ({ logger, config, getInspectorState }, data) => {
+        const { scopesFile, scopesMetaJsonFile } = config;
+        if (!scopesFile) {
+            return;
+        }
+        // On a cold .pikku this runs before pikku-types.gen.ts exists, so it must
+        // take the zero state rather than a full inspect — inspecting here would
+        // try to import the project's zod schemas, which resolve '#pikku' and fail.
+        // The file only has to exist so function types can import ScopeId; the real
+        // Scopes step regenerates it with the declarations once setup has run.
+        const bootstrap = data?.bootstrap ?? false;
+        const state = await getInspectorState(false, bootstrap, bootstrap);
+        const content = serializeScopesTypes({
+            definitions: state.scopes.definitions,
+        });
+        await writeFileInDir(logger, scopesFile, content);
+        if (scopesMetaJsonFile) {
+            const meta = validateAndBuildScopeDefinitionsMeta(state.scopes.definitions);
+            await writeFileInDir(logger, scopesMetaJsonFile, JSON.stringify(meta, null, 2));
+        }
+    },
+    middleware: [
+        logCommandInfoAndTime({
+            commandStart: 'Creating PikkuScopes types',
+            commandEnd: 'Created PikkuScopes types',
+        }),
+    ],
+});

package/dist/src/functions/wirings/scopes/serialize-scopes-types.d.ts

@@ -0,0 +1,15 @@
+import type { ScopeDefinitions } from '@pikku/core/scope';
+export interface SerializeScopesOptions {
+    definitions: ScopeDefinitions;
+}
+/**
+ * Generates the `ScopeId` union and scope metadata from `wireScope`
+ * declarations.
+ *
+ * The union carries every declared node plus a wildcard form for each node that
+ * has descendants — `admin:*` is requirable when `admin` has children, but a
+ * leaf's wildcard would grant nothing beyond the leaf itself, so it is omitted.
+ * The bare `*` is never emitted: it is a valid grant but never a sensible
+ * requirement.
+ */
+export declare const serializeScopesTypes: ({ definitions, }: SerializeScopesOptions) => string;

package/dist/src/functions/wirings/scopes/serialize-scopes-types.js

@@ -0,0 +1,86 @@
+import { flattenScopeDefinitions } from '@pikku/core/scope';
+const quote = (value) => `'${value.replace(/'/g, "\\'")}'`;
+/**
+ * Generates the `ScopeId` union and scope metadata from `wireScope`
+ * declarations.
+ *
+ * The union carries every declared node plus a wildcard form for each node that
+ * has descendants — `admin:*` is requirable when `admin` has children, but a
+ * leaf's wildcard would grant nothing beyond the leaf itself, so it is omitted.
+ * The bare `*` is never emitted: it is a valid grant but never a sensible
+ * requirement.
+ */
+export const serializeScopesTypes = ({ definitions, }) => {
+    const flat = flattenScopeDefinitions(definitions);
+    const ids = flat.map((s) => s.id);
+    const hasChildren = (id) => ids.some((other) => other.startsWith(`${id}:`));
+    const requirable = [
+        ...ids,
+        ...ids.filter(hasChildren).map((id) => `${id}:*`),
+    ].sort();
+    const union = requirable.length > 0
+        ? `\n${requirable.map((id) => `  | ${quote(id)}`).join('\n')}`
+        : ' never';
+    const displayNames = [...flat]
+        .sort((a, b) => a.id.localeCompare(b.id))
+        .flatMap((scope) => {
+        const displayName = definitions.find((d) => d.name === scope.id)?.displayName;
+        return displayName ? [`  ${quote(scope.id)}: ${quote(displayName)},`] : [];
+    });
+    return `/**
+ * This file was generated by the @pikku/cli
+ */
+import type { FlatScope, ScopeDefinitionsMeta } from '@pikku/core/scope'
+import { flattenScopeDefinitions } from '@pikku/core/scope'
+import definitions from './pikku-scopes-meta.gen.json' with { type: 'json' }
+
+/**
+ * Every scope a function can require.
+ *
+ * A \`:*\` entry requires the scope and all of its descendants. Held grants are
+ * matched against this by \`verifyScopes\` — \`admin:*\` on a session satisfies
+ * any \`admin:...\` requirement.
+ */
+export type ScopeId =${union}
+
+export interface ScopeMeta {
+  id: ScopeId
+  displayName?: string
+  description?: string
+}
+
+/**
+ * The declared scope set, for a ScopeService to sync into its store.
+ *
+ * Derived from the metadata sidecar rather than inlined, so that the import
+ * above forces tsc to emit the .json alongside this file. An addon publishes
+ * only its compiled output, and a host reads that .json to merge the addon's
+ * scopes into its own \`ScopeId\` union and declared set — an uncopied sidecar
+ * would leave the addon's scopes ungrantable.
+ *
+ * Additive: removing a declaration leaves an inert row rather than revoking a
+ * grant mid-deploy. Use \`pikku scopes prune\` to remove them deliberately.
+ */
+export const SCOPES: FlatScope[] = flattenScopeDefinitions(
+  Object.values(definitions as ScopeDefinitionsMeta)
+)
+
+const DISPLAY_NAMES: Record<string, string> = {
+${displayNames.join('\n')}
+}
+
+/** Declared scopes, keyed by id. Rendered by the console when granting. */
+export const SCOPES_META: Record<string, ScopeMeta> = Object.fromEntries(
+  SCOPES.map((scope) => [
+    scope.id,
+    {
+      id: scope.id as ScopeId,
+      ...(DISPLAY_NAMES[scope.id]
+        ? { displayName: DISPLAY_NAMES[scope.id] }
+        : {}),
+      ...(scope.description ? { description: scope.description } : {}),
+    },
+  ])
+)
+`;
+};

package/dist/src/functions/wirings/secrets/serialize-secrets-types.js

@@ -32,6 +32,8 @@ export const serializeSecretsTypes = ({ definitions, schemaLookup, secretsFile,
     const imports = [];
     imports.push(`import { TypedSecretService as CoreTypedSecretService, type CredentialMeta } from '@pikku/core/services'`);
     imports.push(`import type { SecretService } from '@pikku/core/services'`);
+    imports.push(`import type { SecretDefinitionsMeta } from '@pikku/core/secret'`);
+    imports.push(`import secretsMeta from './pikku-secrets-meta.gen.json' with { type: 'json' }`);
     if (needsZod) {
         imports.push(`import type { z } from 'zod'`);
     }
@@ -45,6 +47,17 @@ export const serializeSecretsTypes = ({ definitions, schemaLookup, secretsFile,
     }
     return `${imports.join('\n')}
 
+/**
+ * Every secret declared in this package.
+ *
+ * Read from the metadata sidecar rather than inlined, so that the import above
+ * forces tsc to emit the .json alongside this file. An addon publishes only its
+ * compiled output, and a host reads that .json to discover the addon's declared
+ * secrets — an uncopied sidecar leaves them invisible to the host.
+ */
+export const SECRETS_META: SecretDefinitionsMeta =
+  secretsMeta as SecretDefinitionsMeta
+
 export interface CredentialsMap {
 ${mapEntries.join('\n')}
 }