@pikku/core 0.9.12-next.0 → 0.10.1

package/src/wirings/cli/command-parser.ts

@@ -33,7 +33,7 @@ export function parseCLIArguments(
     errors: [],
   }
 
-  const meta = allMeta[programName]
+  const meta = allMeta.programs[programName]
   if (!meta) {
     result.errors.push(`Program not found: ${programName}`)
     return result
@@ -66,10 +66,43 @@ export function parseCLIArguments(
     }
   }
 
+  // If no command was parsed, check for a default command
+  // Only use default if user didn't provide any non-flag arguments
+  const hasNonFlagArgs = args.some(
+    (arg, idx) => idx >= currentIndex && !arg.startsWith('-')
+  )
+  if (result.commandPath.length === 0 && meta.commands && !hasNonFlagArgs) {
+    for (const [name, cmd] of Object.entries(meta.commands)) {
+      if (cmd.isDefault) {
+        result.commandPath.push(name)
+        currentMeta = {
+          program: currentMeta.program,
+          commands: cmd.subcommands || {},
+          options: {
+            ...currentMeta.options,
+            ...cmd.options,
+          },
+          defaultRenderName: cmd.renderName || currentMeta.defaultRenderName,
+        }
+        break
+      }
+    }
+  }
+
   // Get the final command metadata
   const commandMeta = getCommandMeta(meta, result.commandPath)
   if (!commandMeta) {
-    result.errors.push(`Unknown command: ${result.commandPath.join(' ')}`)
+    // If we have no command path but there are non-flag args, the first arg is likely an unknown command
+    if (
+      result.commandPath.length === 0 &&
+      hasNonFlagArgs &&
+      args.length > 0 &&
+      !args[0].startsWith('-')
+    ) {
+      result.errors.push(`Unknown command: ${args[0]}`)
+    } else {
+      result.errors.push(`Unknown command: ${result.commandPath.join(' ')}`)
+    }
     return result
   }
 
@@ -360,7 +393,7 @@ export function generateCommandHelp(
   commandPath: string[] = []
 ): string {
   const lines: string[] = []
-  const meta = allMeta[programName]
+  const meta = allMeta.programs[programName]
 
   if (!meta) {
     return `Program not found: ${programName}`
@@ -374,7 +407,8 @@ export function generateCommandHelp(
 
     for (const [name, cmd] of Object.entries(meta.commands)) {
       const desc = cmd.description || ''
-      lines.push(`  ${name.padEnd(20)} ${desc}`)
+      const defaultMarker = cmd.isDefault ? ' (default)' : ''
+      lines.push(`  ${name.padEnd(20)} ${desc}${defaultMarker}`)
     }
 
     if (Object.keys(meta.options).length > 0) {

package/src/wirings/cli/index.ts

@@ -7,6 +7,7 @@ export {
   runCLICommand,
   pikkuCLIRender,
   executeCLI,
+  CLIError,
 } from './cli-runner.js'
 
 export { parseCLIArguments, generateCommandHelp } from './command-parser.js'

package/src/wirings/http/http-runner.ts

@@ -12,6 +12,7 @@ import {
   CorePikkuFunction,
   CorePikkuFunctionSessionless,
   CorePikkuPermission,
+  CorePermissionGroup,
 } from '../../function/functions.types.js'
 import {
   CoreUserSession,
@@ -75,6 +76,44 @@ export const addHTTPMiddleware = <PikkuMiddleware extends CorePikkuMiddleware>(
   return middleware
 }
 
+/**
+ * Registers HTTP permissions for a specific route pattern.
+ *
+ * This function registers permissions at runtime that will be applied to
+ * HTTP routes matching the specified pattern.
+ *
+ * For tree-shaking benefits, wrap in a factory function:
+ * `export const x = () => addHTTPPermission('pattern', [...])`
+ *
+ * @template PikkuPermission The permission type.
+ * @param {string} pattern - Route pattern (e.g., '*' for all routes, '/api/*' for specific routes).
+ * @param {CorePermissionGroup | CorePikkuPermission[]} permissions - Permissions for this route pattern.
+ *
+ * @returns {CorePermissionGroup | CorePikkuPermission[]} The permissions (for chaining/wrapping).
+ *
+ * @example
+ * ```typescript
+ * // Recommended: tree-shakeable
+ * export const httpGlobalPermissions = () => addHTTPPermission('*', [
+ *   authenticatedPermission,
+ *   rateLimitPermission
+ * ])
+ *
+ * // Also works: no tree-shaking
+ * export const apiPermissions = addHTTPPermission('/api/*', [
+ *   adminPermission
+ * ])
+ * ```
+ */
+export const addHTTPPermission = <PikkuPermission extends CorePikkuPermission>(
+  pattern: string,
+  permissions: CorePermissionGroup | CorePikkuPermission[]
+): CorePermissionGroup | CorePikkuPermission[] => {
+  const httpGroups = pikkuState('permissions', 'httpGroup')
+  httpGroups[pattern] = permissions
+  return permissions
+}
+
 /**
  * Adds a new route to the global HTTP route registry.
  *
@@ -320,9 +359,10 @@ const executeRoute = async (
       auth: route.auth !== false,
       userSession,
       data,
-      permissions: route.permissions,
       inheritedMiddleware: meta.middleware,
       wireMiddleware: route.middleware,
+      inheritedPermissions: meta.permissions,
+      wirePermissions: route.permissions,
       coerceDataFromSchema: options.coerceDataFromSchema,
       tags: route.tags,
       interaction,

package/src/wirings/http/http.types.ts

@@ -8,6 +8,7 @@ import type {
   CreateSessionServices,
   CorePikkuMiddleware,
   MiddlewareMetadata,
+  PermissionMetadata,
 } from '../../types/core.types.js'
 import type {
   CorePikkuFunction,
@@ -251,7 +252,8 @@ export type HTTPWiringMeta = {
   docs?: PikkuDocs
   tags?: string[]
   sse?: true
-  middleware?: MiddlewareMetadata[] // Pre-resolved middleware chain (global + route + tag + explicit + efunc)
+  middleware?: MiddlewareMetadata[] // Pre-resolved middleware chain (global + route + tag + explicit)
+  permissions?: PermissionMetadata[] // Pre-resolved permission chain (global + route + tag + explicit)
 }
 export type HTTPWiringsMeta = Record<HTTPMethod, Record<string, HTTPWiringMeta>>
 

package/src/wirings/http/index.ts

@@ -2,6 +2,12 @@ export * from './pikku-fetch-http-request.js'
 export * from './pikku-fetch-http-response.js'
 export * from './log-http-routes.js'
 
-export { fetch, fetchData, wireHTTP, addHTTPMiddleware } from './http-runner.js'
+export {
+  fetch,
+  fetchData,
+  wireHTTP,
+  addHTTPMiddleware,
+  addHTTPPermission,
+} from './http-runner.js'
 
 export type * from './http.types.js'

package/src/wirings/mcp/mcp-endpoint-registry.ts

@@ -1,4 +1,4 @@
-import { MCPResourceMeta, MCPToolMeta, MCPPromptMeta } from '@pikku/core'
+import { MCPResourceMeta, MCPToolMeta, MCPPromptMeta } from '@pikku/core/mcp'
 
 export interface MCPToolEndpoint {
   name: string

package/src/wirings/mcp/mcp-runner.ts

@@ -276,6 +276,8 @@ async function runMCPPikkuFunc(
         data: () => request.params,
         inheritedMiddleware: meta?.middleware,
         wireMiddleware: mcp.middleware,
+        inheritedPermissions: meta?.permissions,
+        wirePermissions: mcp.permissions,
         tags: mcp.tags,
         interaction,
       }

package/src/wirings/mcp/mcp.types.ts

@@ -1,12 +1,40 @@
 import {
+  CorePermissionGroup,
   CorePikkuFunctionConfig,
   CorePikkuFunctionSessionless,
+  CorePikkuPermission,
 } from '../../function/functions.types.js'
 import {
   CorePikkuMiddleware,
   MiddlewareMetadata,
+  PermissionMetadata,
 } from '../../types/core.types.js'
 
+/**
+ * Extract URI parameters from MCP resource URI template.
+ * E.g., "user/{userId}/post/{postId}" => "userId" | "postId"
+ */
+type ExtractMCPURIParams<S extends string> =
+  S extends `${string}{${infer Param}}/${infer Rest}`
+    ? Param | ExtractMCPURIParams<Rest>
+    : S extends `${string}{${infer Param}}`
+      ? Param
+      : never
+
+/**
+ * Type-level assertion that MCP resource URI parameters are present in the input type.
+ * This ensures compile-time safety for URI parameter validation.
+ */
+export type AssertMCPResourceURIParams<In, URI extends string> =
+  ExtractMCPURIParams<URI> extends keyof In
+    ? unknown
+    : [
+        'Error: MCP Resource URI parameters',
+        ExtractMCPURIParams<URI>,
+        'not in input type',
+        keyof In,
+      ]
+
 export type PikkuMCP<Tools extends string = any> = {
   // elicitInput: <Input>(message: string) => Promise<{ action: string, content: Input }>
   uri?: string
@@ -21,11 +49,12 @@ export type PikkuMCP<Tools extends string = any> = {
  */
 export type MCPResourceMeta = Record<
   string,
-  Omit<CoreMCPResource, 'func' | 'middleware'> & {
+  Omit<CoreMCPResource, 'func' | 'middleware' | 'permissions'> & {
     pikkuFuncName: string
     inputSchema: string | null
     outputSchema: string | null
     middleware?: MiddlewareMetadata[] // Pre-resolved middleware chain (tag + explicit)
+    permissions?: PermissionMetadata[] // Pre-resolved permission chain (tag + explicit)
   }
 >
 
@@ -34,11 +63,12 @@ export type MCPResourceMeta = Record<
  */
 export type MCPToolMeta = Record<
   string,
-  Omit<CoreMCPTool, 'func' | 'middleware'> & {
+  Omit<CoreMCPTool, 'func' | 'middleware' | 'permissions'> & {
     pikkuFuncName: string
     inputSchema: string | null
     outputSchema: string | null
     middleware?: MiddlewareMetadata[] // Pre-resolved middleware chain (tag + explicit)
+    permissions?: PermissionMetadata[] // Pre-resolved permission chain (tag + explicit)
   }
 >
 
@@ -47,7 +77,7 @@ export type MCPToolMeta = Record<
  */
 export type MCPPromptMeta = Record<
   string,
-  Omit<CoreMCPPrompt, 'func' | 'middleware'> & {
+  Omit<CoreMCPPrompt, 'func' | 'middleware' | 'permissions'> & {
     pikkuFuncName: string
     inputSchema: string | null
     outputSchema: string | null
@@ -57,6 +87,7 @@ export type MCPPromptMeta = Record<
       required: boolean
     }>
     middleware?: MiddlewareMetadata[] // Pre-resolved middleware chain (tag + explicit)
+    permissions?: PermissionMetadata[] // Pre-resolved permission chain (tag + explicit)
   }
 >
 
@@ -64,55 +95,60 @@ export type MCPPromptMeta = Record<
  * Represents an MCP resource with specific properties.
  */
 export type CoreMCPResource<
-  PikkuFunction = CorePikkuFunctionConfig<
+  PikkuFunctionConfig = CorePikkuFunctionConfig<
     CorePikkuFunctionSessionless<any, any>
   >,
+  PikkuPermission = CorePikkuPermission<any, any>,
   PikkuMiddleware = CorePikkuMiddleware<any>,
 > = {
   uri: string
   title: string
-  description?: string
+  description: string
   mimeType?: string
   size?: number
   streaming?: boolean
-  func: PikkuFunction
+  func: PikkuFunctionConfig
   tags?: string[]
   middleware?: PikkuMiddleware[]
+  permissions?: CorePermissionGroup<PikkuPermission>
 }
 
 /**
  * Represents an MCP tool with specific properties.
  */
 export type CoreMCPTool<
-  PikkuFunction = CorePikkuFunctionConfig<
+  PikkuFunctionConfig = CorePikkuFunctionConfig<
     CorePikkuFunctionSessionless<any, any>
   >,
+  PikkuPermission = CorePikkuPermission<any, any>,
   PikkuMiddleware = CorePikkuMiddleware<any>,
 > = {
   name: string
   title?: string
   description: string
-  annotations?: Record<string, any>
-  func: PikkuFunction
+  func: PikkuFunctionConfig
   tags?: string[]
   streaming?: boolean
   middleware?: PikkuMiddleware[]
+  permissions?: CorePermissionGroup<PikkuPermission>
 }
 
 /**
  * Represents an MCP prompt with specific properties.
  */
 export type CoreMCPPrompt<
-  PikkuFunction = CorePikkuFunctionConfig<
+  PikkuFunctionConfig = CorePikkuFunctionConfig<
     CorePikkuFunctionSessionless<any, MCPPromptResponse>
   >,
+  PikkuPermission = CorePikkuPermission<any, any>,
   PikkuMiddleware = CorePikkuMiddleware<any>,
 > = {
   name: string
-  description?: string
-  func: PikkuFunction
+  description: string
+  func: PikkuFunctionConfig
   tags?: string[]
   middleware?: PikkuMiddleware[]
+  permissions?: CorePermissionGroup<PikkuPermission>
 }
 
 export type JsonRpcRequest = {

package/src/wirings/queue/queue-runner.ts

@@ -171,6 +171,7 @@ export async function runQueueJob({
       {
         singletonServices,
         getAllServices,
+        auth: false,
         data: () => job.data,
         inheritedMiddleware: processorMeta.middleware,
         wireMiddleware: queueWorker.middleware,

package/src/wirings/scheduler/scheduler-runner.ts

@@ -137,6 +137,7 @@ export async function runScheduledTask({
         singletonServices,
         getAllServices,
         userSession,
+        auth: false,
         data: () => undefined,
         inheritedMiddleware: meta.middleware,
         wireMiddleware: task.middleware,

package/src/wirings/scheduler/scheduler.types.ts

@@ -30,14 +30,14 @@ export type ScheduledTasksMeta<UserSession extends CoreUserSession = any> =
  * Represents a core scheduled task.
  */
 export type CoreScheduledTask<
-  PikkuFunction = CorePikkuFunctionConfig<
+  PikkuFunctionConfig = CorePikkuFunctionConfig<
     CorePikkuFunctionSessionless<void, void>
   >,
   PikkuMiddleware = CorePikkuMiddleware<any>,
 > = {
   name: string
   schedule: string
-  func: PikkuFunction
+  func: PikkuFunctionConfig
   docs?: PikkuDocs
   tags?: string[]
   middleware?: PikkuMiddleware[]