@pikku/core 0.12.19 → 0.12.20

package/src/function/function-runner.ts

@@ -72,6 +72,54 @@ async function resolveSession(
  * @param parentServices - The parent/caller's singleton services (used as base)
  * @returns The package's singleton services
  */
+/**
+ * Find the consumer-defined namespace (from wireAddon) for a given addon package.
+ * Returns null if the package isn't registered as an addon.
+ */
+const findAddonNamespaceForPackage = (packageName: string): string | null => {
+  const addons = pikkuState(null, 'addons', 'packages')
+  if (!addons) return null
+  for (const [namespace, cfg] of addons.entries()) {
+    if (cfg?.package === packageName) return namespace
+  }
+  return null
+}
+
+/**
+ * Wrap a workflow service so that bare workflow names passed from inside an
+ * addon function are auto-prefixed with the addon's consumer-facing namespace.
+ * Without this, `runToCompletion('myWorkflow')` from inside an addon misses
+ * the workflow registered under the addon's package scope and throws
+ * WorkflowNotFoundError — forcing addons to hardcode their consumer-defined
+ * namespace, which couples the addon to its caller.
+ *
+ * Explicit `'ns:name'` and bare names that already exist in root meta are
+ * unaffected; only bare names that would otherwise miss resolution get
+ * prefixed.
+ */
+const wrapWorkflowServiceForPackage = <T extends object>(
+  service: T,
+  packageName: string
+): T => {
+  return new Proxy(service, {
+    get(target, prop, receiver) {
+      if (prop === 'startWorkflow' || prop === 'runToCompletion') {
+        const original = Reflect.get(target, prop, receiver) as Function
+        return function (this: any, name: string, ...rest: any[]) {
+          if (typeof name === 'string' && !name.includes(':')) {
+            const namespace = findAddonNamespaceForPackage(packageName)
+            if (namespace) {
+              name = `${namespace}:${name}`
+            }
+          }
+          return original.call(this, name, ...rest)
+        }
+      }
+      return Reflect.get(target, prop, receiver)
+    },
+  })
+}
+
 const getOrCreatePackageSingletonServices = async (
   packageName: string,
   parentServices: CoreSingletonServices
@@ -101,6 +149,18 @@ const getOrCreatePackageSingletonServices = async (
     parentServices
   )
 
+  // Wrap workflowService so that bare names used inside the addon's functions
+  // resolve to workflows registered under the addon's package scope.
+  if (
+    packageServices.workflowService &&
+    typeof packageServices.workflowService === 'object'
+  ) {
+    packageServices.workflowService = wrapWorkflowServiceForPackage(
+      packageServices.workflowService as object,
+      packageName
+    ) as typeof packageServices.workflowService
+  }
+
   // Cache the services
   pikkuState(packageName, 'package', 'singletonServices', packageServices)
 
@@ -378,11 +438,16 @@ export const runPikkuFunc = async <In = any, Out = any>(
         wireServices && Object.keys(wireServices).length > 0
           ? { ...resolvedSingletonServices, ...wireServices }
           : resolvedSingletonServices
+      const callerPackageName = packageName
       Object.defineProperty(resolvedWire, 'rpc', {
         get() {
-          const rpc = rpcService.getContextRPCService(services, resolvedWire, {
-            sessionService,
-          })
+          const rpc = rpcService.getContextRPCService(
+            services,
+            resolvedWire,
+            { sessionService },
+            0,
+            callerPackageName
+          )
           Object.defineProperty(resolvedWire, 'rpc', {
             value: rpc,
             writable: true,

package/src/index.ts

@@ -98,7 +98,16 @@ export type { QueueService } from './wirings/queue/queue.types.js'
 export type { JWTService } from './services/jwt-service.js'
 export type { SecretService } from './services/secret-service.js'
 export type { VariablesService } from './services/variables-service.js'
-export type { ContentService } from './services/content-service.js'
+export type {
+  ContentService,
+  SignContentKeyArgs,
+  SignURLArgs,
+  GetUploadURLArgs,
+  UploadURLResult,
+  BucketKeyArgs,
+  WriteFileArgs,
+  CopyFileArgs,
+} from './services/content-service.js'
 export type { DeploymentService } from './services/deployment-service.js'
 export type { WorkflowService } from './services/workflow-service.js'
 export type { GatewayService } from './services/gateway-service.js'

package/src/services/content-service.ts

@@ -1,81 +1,109 @@
-export interface ContentService {
+/**
+ * Arguments for signing a content key into a time-limited URL.
+ */
+export interface SignContentKeyArgs<TBucket extends string = string> {
+  bucket: TBucket
+  contentKey: string
+  dateLessThan: Date
+  dateGreaterThan?: Date
+}
+
+/**
+ * Arguments for signing an arbitrary URL.
+ */
+export interface SignURLArgs {
+  url: string
+  dateLessThan: Date
+  dateGreaterThan?: Date
+}
+
+/**
+ * Arguments for minting a presigned upload URL.
+ */
+export interface GetUploadURLArgs<TBucket extends string = string> {
+  bucket: TBucket
+  fileKey: string
+  contentType: string
+  size?: number
+}
+
+/**
+ * Result of minting a presigned upload URL.
+ */
+export interface UploadURLResult {
+  uploadUrl: string
+  assetKey: string
+  uploadHeaders?: Record<string, string>
+  uploadMethod?: 'PUT' | 'POST'
+}
+
+/**
+ * Arguments for an operation that targets a single object by key.
+ */
+export interface BucketKeyArgs<TBucket extends string = string> {
+  bucket: TBucket
+  key: string
+}
+
+/**
+ * Arguments for writing a stream to storage.
+ */
+export interface WriteFileArgs<
+  TBucket extends string = string,
+> extends BucketKeyArgs<TBucket> {
+  stream: ReadableStream | NodeJS.ReadableStream
+}
+
+/**
+ * Arguments for copying a local file into storage.
+ */
+export interface CopyFileArgs<
+  TBucket extends string = string,
+> extends BucketKeyArgs<TBucket> {
+  fromAbsolutePath: string
+}
+
+export interface ContentService<TBucket extends string = string> {
   /**
    * Signs a content key to generate a secure, time-limited access URL.
-   * @param contentKey - The key representing the content object.
-   * @param dateLessThan - The expiration time for the signed URL.
-   * @param dateGreaterThan - (Optional) Start time before which access is denied.
    */
-  signContentKey(
-    contentKey: string,
-    dateLessThan: Date,
-    dateGreaterThan?: Date
-  ): Promise<string>
+  signContentKey(args: SignContentKeyArgs<TBucket>): Promise<string>
 
   /**
    * Signs an arbitrary URL to generate a secure, time-limited access URL.
-   * @param url - The full URL that needs signing.
-   * @param dateLessThan - The expiration time for the signed URL.
-   * @param dateGreaterThan - (Optional) Start time before which access is denied.
    */
-  signURL(
-    url: string,
-    dateLessThan: Date,
-    dateGreaterThan?: Date
-  ): Promise<string>
+  signURL(args: SignURLArgs): Promise<string>
 
   /**
    * Generates a signed URL for uploading a file directly to storage.
-   * @param fileKey - The desired key/location of the uploaded file.
-   * @param contentType - The MIME type of the file.
-   * @returns A signed upload URL and the finalized asset key.
+   * Bucket policy (size limits, MIME allowlist) is enforced by the implementation.
    */
-  getUploadURL(
-    fileKey: string,
-    contentType: string
-  ): Promise<{
-    uploadUrl: string
-    assetKey: string
-    uploadHeaders?: Record<string, string>
-    uploadMethod?: 'PUT' | 'POST'
-  }>
+  getUploadURL(args: GetUploadURLArgs<TBucket>): Promise<UploadURLResult>
 
   /**
    * Deletes a file from the storage backend.
-   * @param fileName - The name or key of the file to delete.
-   * @returns A boolean indicating success.
    */
-  deleteFile(fileName: string): Promise<boolean>
+  deleteFile(args: BucketKeyArgs<TBucket>): Promise<boolean>
 
   /**
-   * Uploads a file stream to storage under a specified asset key.
-   * @param assetKey - The key where the file will be saved.
-   * @param stream - A readable stream of the file contents.
-   * @returns A boolean indicating success.
+   * Uploads a file stream to storage under the specified bucket + key.
    */
-  writeFile(
-    assetKey: string,
-    stream: ReadableStream | NodeJS.ReadableStream
-  ): Promise<boolean>
+  writeFile(args: WriteFileArgs<TBucket>): Promise<boolean>
 
   /**
-   * Copies a file from a local absolute path into storage under a new asset key.
-   * @param assetKey - The destination key.
-   * @param fromAbsolutePath - The local absolute file path.
-   * @returns A boolean indicating success.
+   * Copies a file from a local absolute path into storage.
    */
-  copyFile(assetKey: string, fromAbsolutePath: string): Promise<boolean>
+  copyFile(args: CopyFileArgs<TBucket>): Promise<boolean>
 
   /**
    * Reads a file from storage as a readable stream.
-   * @param assetKey - The key of the file to read.
-   * @returns A readable file stream.
    */
-  readFile(assetKey: string): Promise<ReadableStream | NodeJS.ReadableStream>
+  readFile(
+    args: BucketKeyArgs<TBucket>
+  ): Promise<ReadableStream | NodeJS.ReadableStream>
 
   /**
    * Reads an entire file from storage into a Buffer.
-   * @param assetKey - The key of the file to read.
-   * @returns The file contents as a Buffer.
    */
-  readFileAsBuffer(assetKey: string): Promise<Buffer>
+  readFileAsBuffer(args: BucketKeyArgs<TBucket>): Promise<Buffer>
 }

package/src/services/index.ts

@@ -25,7 +25,16 @@ export { InMemoryQueueService } from './in-memory-queue-service.js'
 export { InMemoryTriggerService } from './in-memory-trigger-service.js'
 export { InMemoryAIRunStateService } from './in-memory-ai-run-state-service.js'
 export { LocalGatewayService } from './local-gateway-service.js'
-export type { ContentService } from './content-service.js'
+export type {
+  ContentService,
+  SignContentKeyArgs,
+  SignURLArgs,
+  GetUploadURLArgs,
+  UploadURLResult,
+  BucketKeyArgs,
+  WriteFileArgs,
+  CopyFileArgs,
+} from './content-service.js'
 export type { JWTService } from './jwt-service.js'
 export type { Logger } from './logger.js'
 export type { SecretService } from './secret-service.js'

package/src/services/local-content.ts

@@ -1,7 +1,18 @@
 import { createReadStream, createWriteStream, promises } from 'fs'
 import { mkdir, readFile } from 'fs/promises'
 import { resolve, normalize } from 'path'
-import type { ContentService, JWTService, Logger } from '@pikku/core/services'
+import type {
+  BucketKeyArgs,
+  ContentService,
+  CopyFileArgs,
+  GetUploadURLArgs,
+  JWTService,
+  Logger,
+  SignContentKeyArgs,
+  SignURLArgs,
+  UploadURLResult,
+  WriteFileArgs,
+} from '@pikku/core/services'
 import { pipeline } from 'stream/promises'
 import type { Readable } from 'stream'
 
@@ -20,15 +31,20 @@ export class LocalContent implements ContentService {
     private jwt?: JWTService
   ) {}
 
-  private safePath(assetKey: string): string {
+  private safePath(bucket: string, key: string): string {
     const base = resolve(this.config.localFileUploadPath)
-    const target = resolve(base, normalize(assetKey))
+    const scoped = resolve(base, normalize(bucket))
+    const target = resolve(scoped, normalize(key))
     if (!target.startsWith(base + '/') && target !== base) {
       throw new Error('Invalid asset key')
     }
     return target
   }
 
+  private joinKey(bucket: string, key: string): string {
+    return `${bucket}/${key}`
+  }
+
   public async init() {}
 
   private async signParams(
@@ -58,105 +74,105 @@ export class LocalContent implements ContentService {
     return params.toString()
   }
 
-  public async signURL(
-    url: string,
-    dateLessThan: Date,
-    dateGreaterThan?: Date
-  ): Promise<string> {
-    const params = await this.signParams(dateLessThan, dateGreaterThan)
-    return `${url}?${params}`
+  public async signURL(args: SignURLArgs): Promise<string> {
+    const params = await this.signParams(
+      args.dateLessThan,
+      args.dateGreaterThan
+    )
+    return `${args.url}?${params}`
   }
 
-  public async signContentKey(
-    assetKey: string,
-    dateLessThan: Date,
-    dateGreaterThan?: Date
-  ): Promise<string> {
+  public async signContentKey(args: SignContentKeyArgs): Promise<string> {
+    const fullKey = this.joinKey(args.bucket, args.contentKey)
     const base = this.config.server
-      ? `${this.config.server}${this.config.assetUrlPrefix}/${assetKey}`
-      : `${this.config.assetUrlPrefix}/${assetKey}`
-    return this.signURL(base, dateLessThan, dateGreaterThan)
+      ? `${this.config.server}${this.config.assetUrlPrefix}/${fullKey}`
+      : `${this.config.assetUrlPrefix}/${fullKey}`
+    return this.signURL({
+      url: base,
+      dateLessThan: args.dateLessThan,
+      dateGreaterThan: args.dateGreaterThan,
+    })
   }
 
-  public async getUploadURL(assetKey: string) {
-    this.logger.debug(`Going to upload with key: ${assetKey}`)
+  public async getUploadURL(args: GetUploadURLArgs): Promise<UploadURLResult> {
+    const fullKey = this.joinKey(args.bucket, args.fileKey)
+    this.logger.debug(`Going to upload with key: ${fullKey}`)
     return {
-      uploadUrl: `${this.config.uploadUrlPrefix}/${assetKey}`,
-      assetKey,
+      uploadUrl: `${this.config.uploadUrlPrefix}/${fullKey}`,
+      assetKey: fullKey,
     }
   }
 
-  public async writeFile(
-    assetKey: string,
-    stream: ReadableStream | NodeJS.ReadableStream
-  ): Promise<boolean> {
-    this.logger.debug(`Writing file: ${assetKey}`)
+  public async writeFile(args: WriteFileArgs): Promise<boolean> {
+    this.logger.debug(`Writing file: ${args.bucket}/${args.key}`)
 
-    const path = this.safePath(assetKey)
+    const path = this.safePath(args.bucket, args.key)
 
     try {
       await this.createDirectoryForFile(path)
       const fileStream = createWriteStream(path)
-      // Use pipeline to properly manage stream piping and errors
-      await pipeline(stream as Readable, fileStream)
+      await pipeline(args.stream as Readable, fileStream)
       return true
     } catch (e) {
       console.error(e)
-      this.logger.error(`Error writing content ${assetKey}`, e)
+      this.logger.error(`Error writing content ${args.bucket}/${args.key}`, e)
       return false
     }
   }
 
-  public async copyFile(
-    assetKey: string,
-    fromAbsolutePath: string
-  ): Promise<boolean> {
-    this.logger.debug(`Writing file: ${assetKey}`)
+  public async copyFile(args: CopyFileArgs): Promise<boolean> {
+    this.logger.debug(`Writing file: ${args.bucket}/${args.key}`)
     try {
-      const path = this.safePath(assetKey)
+      const path = this.safePath(args.bucket, args.key)
       await this.createDirectoryForFile(path)
-      await promises.copyFile(fromAbsolutePath, path)
+      await promises.copyFile(args.fromAbsolutePath, path)
+      return true
     } catch (e) {
       console.error(e)
-      this.logger.error(`Error inserting content ${assetKey}`, e)
+      this.logger.error(`Error inserting content ${args.bucket}/${args.key}`, e)
     }
     return false
   }
 
   public async readFile(
-    assetKey: string
+    args: BucketKeyArgs
   ): Promise<ReadableStream | NodeJS.ReadableStream> {
-    this.logger.debug(`Getting key: ${assetKey}`)
+    this.logger.debug(`Getting key: ${args.bucket}/${args.key}`)
 
-    const filePath = this.safePath(assetKey)
+    const filePath = this.safePath(args.bucket, args.key)
 
     try {
       const stream = createReadStream(filePath)
-      // Handle early stream errors (like file not found, permission denied, etc.)
       stream.on('error', (err) => {
-        this.logger.error(`Error getting content ${assetKey}`, err)
+        this.logger.error(
+          `Error getting content ${args.bucket}/${args.key}`,
+          err
+        )
       })
 
       return stream
     } catch (e) {
-      this.logger.error(`Error setting up stream for ${assetKey}`, e)
+      this.logger.error(
+        `Error setting up stream for ${args.bucket}/${args.key}`,
+        e
+      )
       throw e
     }
   }
 
-  public async readFileAsBuffer(assetKey: string): Promise<Buffer> {
-    const filePath = this.safePath(assetKey)
-    this.logger.debug(`Reading file as buffer: ${assetKey}`)
+  public async readFileAsBuffer(args: BucketKeyArgs): Promise<Buffer> {
+    const filePath = this.safePath(args.bucket, args.key)
+    this.logger.debug(`Reading file as buffer: ${args.bucket}/${args.key}`)
     return readFile(filePath)
   }
 
-  public async deleteFile(assetKey: string): Promise<boolean> {
-    this.logger.debug(`deleting key: ${assetKey}`)
+  public async deleteFile(args: BucketKeyArgs): Promise<boolean> {
+    this.logger.debug(`deleting key: ${args.bucket}/${args.key}`)
     try {
-      await promises.unlink(this.safePath(assetKey))
+      await promises.unlink(this.safePath(args.bucket, args.key))
       return true
     } catch (e: any) {
-      this.logger.error(`Error deleting content ${assetKey}`, e)
+      this.logger.error(`Error deleting content ${args.bucket}/${args.key}`, e)
     }
     return false
   }

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

@@ -54,7 +54,25 @@ export const resolveNamespace = (
   }
 }
 
-const getPikkuFunctionName = (rpcName: string): string => {
+/**
+ * Resolve a bare (non-namespaced) RPC name to its pikkuFuncId, preferring
+ * the caller's addon package when provided. Returns the function name plus
+ * the package scope that resolved it (null = root), so callers can thread
+ * the scope into runPikkuFunc without a second lookup.
+ */
+const resolvePikkuFunction = (
+  rpcName: string,
+  packageName: string | null = null
+): { pikkuFuncId: string; packageName: string | null } => {
+  // Addon-scoped calls: try the caller's package function meta first.
+  // (RPC meta only lives in root; addon functions are registered under their package.)
+  if (packageName) {
+    const pkgFunctions = pikkuState(packageName, 'function', 'meta')
+    const pkgMeta = pkgFunctions?.[rpcName]
+    if (pkgMeta) {
+      return { pikkuFuncId: pkgMeta.pikkuFuncId || rpcName, packageName }
+    }
+  }
   const rpc = pikkuState(null, 'rpc', 'meta')
   let rpcMeta = rpc[rpcName]
   if (!rpcMeta) {
@@ -66,7 +84,7 @@ const getPikkuFunctionName = (rpcName: string): string => {
   if (!rpcMeta) {
     throw new RPCNotFoundError(rpcName)
   }
-  return rpcMeta
+  return { pikkuFuncId: rpcMeta, packageName: null }
 }
 
 // Context-aware RPC client for use within services
@@ -77,7 +95,8 @@ export class ContextAwareRPCService {
     private options: {
       requiresAuth?: boolean
       sessionService?: SessionService<CoreUserSession>
-    }
+    },
+    private packageName: string | null = null
   ) {}
 
   public async rpcExposed(funcName: string, data: any): Promise<any> {
@@ -131,17 +150,22 @@ export class ContextAwareRPCService {
       }
     }
 
-    // Try local function, then fall back to deployment service (remote)
+    // Bare name: resolve via caller's package scope first (if any), then root.
+    // Note: intra-addon bare calls do NOT re-apply the addon's external
+    // addonConfig.auth/tags — those gates are only applied on the external
+    // 'namespace:func' boundary via invokeAddonFunction.
     try {
+      const resolved = resolvePikkuFunction(funcName, this.packageName)
       return await runPikkuFunc<In, Out>(
         'rpc',
         funcName,
-        getPikkuFunctionName(funcName),
+        resolved.pikkuFuncId,
         {
           auth: this.options.requiresAuth,
           singletonServices: this.services,
           data: () => data,
           wire: updatedWire,
+          packageName: resolved.packageName,
         }
       )
     } catch (e) {
@@ -232,17 +256,14 @@ export class ContextAwareRPCService {
     }
 
     try {
-      return await runPikkuFunc<In, Out>(
-        'rpc',
-        rpcName,
-        getPikkuFunctionName(rpcName),
-        {
-          auth: this.options.requiresAuth,
-          singletonServices: this.services,
-          data: () => data,
-          wire: mergedWire,
-        }
-      )
+      const resolved = resolvePikkuFunction(rpcName, this.packageName)
+      return await runPikkuFunc<In, Out>('rpc', rpcName, resolved.pikkuFuncId, {
+        auth: this.options.requiresAuth,
+        singletonServices: this.services,
+        data: () => data,
+        wire: mergedWire,
+        packageName: resolved.packageName,
+      })
     } catch (e) {
       if (e instanceof RPCNotFoundError && this.services.deploymentService) {
         const session =
@@ -406,14 +427,20 @@ export class PikkuRPCService<
           sessionService?: SessionService<CoreUserSession>
         }
       | undefined,
-    depth: number = 0
+    depth: number = 0,
+    packageName: string | null = null
   ): TypedRPC {
     const options =
       typeof requiresAuthOrOptions === 'object' &&
       requiresAuthOrOptions !== null
         ? requiresAuthOrOptions
         : { requiresAuth: requiresAuthOrOptions }
-    const serviceRPC = new ContextAwareRPCService(services, wire, options)
+    const serviceRPC = new ContextAwareRPCService(
+      services,
+      wire,
+      options,
+      packageName
+    )
     return {
       depth,
       global: false,