@pikku/core 0.12.18 → 0.12.20

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/services/workflow-service.ts

@@ -1,6 +1,7 @@
 import type { SerializedError } from '../types/core.types.js'
 import type {
   WorkflowRun,
+  WorkflowPlannedStep,
   WorkflowRunWire,
   WorkflowRunStatus,
   StepState,
@@ -19,7 +20,11 @@ export interface WorkflowService {
     input: any,
     inline: boolean,
     graphHash: string,
-    wire: WorkflowRunWire
+    wire: WorkflowRunWire,
+    options?: {
+      deterministic?: boolean
+      plannedSteps?: WorkflowPlannedStep[]
+    }
   ): Promise<string>
   getRun(id: string): Promise<WorkflowRun | null>
   getRunStatus(id: string): Promise<WorkflowRunStatus | null>

package/src/wirings/cli/channel/cli-channel-runner.ts

@@ -3,10 +3,12 @@ import type { CorePikkuCLIRender, CLIMeta } from '../cli.types.js'
 import { generateCommandHelp, parseCLIArguments } from '../command-parser.js'
 
 /**
- * Default JSON renderer for CLI output
+ * Default JSON renderer for CLI output. Emits single-line NDJSON so
+ * the output stays machine-parseable when the CLI is run with
+ * `--output json`; pretty-printing here would break NDJSON consumers.
  */
 const defaultJSONRenderer: CorePikkuCLIRender<any> = (_services, data) => {
-  console.log(JSON.stringify(data, null, 2))
+  console.log(JSON.stringify(data))
 }
 
 /**

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

@@ -45,10 +45,12 @@ export class CLIError extends Error {
 }
 
 /**
- * Default JSON renderer for CLI output
+ * Default JSON renderer for CLI output. Emits single-line NDJSON so
+ * the output stays machine-parseable when the CLI is run with
+ * `--output json`; pretty-printing here would break NDJSON consumers.
  */
 const defaultJSONRenderer: CorePikkuCLIRender<any> = (_services, data) => {
-  console.log(JSON.stringify(data, null, 2))
+  console.log(JSON.stringify(data))
 }
 
 /**

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,

package/src/wirings/workflow/graph/graph-runner.ts

@@ -852,7 +852,11 @@ export async function runWorkflowGraph(
     triggerInput,
     inline ?? false,
     meta.graphHash,
-    wire ?? { type: 'unknown' }
+    wire ?? { type: 'unknown' },
+    {
+      deterministic: meta.deterministic,
+      plannedSteps: meta.plannedSteps,
+    }
   )
 
   if (inline) {

package/src/wirings/workflow/index.ts

@@ -42,6 +42,7 @@ export type {
 export type {
   WorkflowService,
   WorkflowServiceConfig,
+  WorkflowPlannedStep,
   WorkflowRunWire,
   WorkflowStatus,
   WorkflowVersionStatus,

package/src/wirings/workflow/pikku-workflow-service.ts

@@ -49,6 +49,7 @@ import type {
   PikkuWorkflowWire,
   StepState,
   StepStatus,
+  WorkflowPlannedStep,
   WorkflowRun,
   WorkflowRunStatus,
   WorkflowRunWire,
@@ -272,7 +273,11 @@ export abstract class PikkuWorkflowService implements WorkflowService {
     input: any,
     inline: boolean,
     graphHash: string,
-    wire: WorkflowRunWire
+    wire: WorkflowRunWire,
+    options?: {
+      deterministic?: boolean
+      plannedSteps?: WorkflowPlannedStep[]
+    }
   ): Promise<string>
 
   /**
@@ -323,6 +328,8 @@ export abstract class PikkuWorkflowService implements WorkflowService {
       status: run.status,
       startedAt: run.createdAt,
       completedAt: terminalStatuses.has(run.status) ? run.updatedAt : undefined,
+      deterministic: run.deterministic,
+      plannedSteps: run.plannedSteps,
       steps,
       output: run.status === 'completed' ? run.output : undefined,
       error: run.error
@@ -689,7 +696,11 @@ export abstract class PikkuWorkflowService implements WorkflowService {
       input,
       shouldInline,
       workflowMeta.graphHash,
-      wire
+      wire,
+      {
+        deterministic: workflowMeta.deterministic,
+        plannedSteps: workflowMeta.plannedSteps,
+      }
     )
 
     if (shouldInline) {

package/src/wirings/workflow/workflow.types.ts

@@ -53,6 +53,11 @@ export interface WorkflowServiceConfig {
   sleeperRPCName: string
 }
 
+export interface WorkflowPlannedStep {
+  /** Human-readable step label for UI timeline */
+  stepName: string
+}
+
 /**
  * Workflow run status
  */
@@ -99,6 +104,10 @@ export interface WorkflowRun {
   inline?: boolean
   /** Graph hash of the workflow definition at run creation time */
   graphHash?: string
+  /** True when the workflow has a static, pre-computable step timeline */
+  deterministic?: boolean
+  /** Static planned steps snapshot captured at run start */
+  plannedSteps?: WorkflowPlannedStep[]
   /** Wire origin info (how this run was started) */
   wire: WorkflowRunWire
   /** Creation timestamp */
@@ -146,6 +155,8 @@ export interface WorkflowRunStatus {
   status: WorkflowStatus
   startedAt: Date
   completedAt?: Date
+  deterministic?: boolean
+  plannedSteps?: WorkflowPlannedStep[]
   steps: Array<{
     name: string
     status: StepStatus
@@ -270,6 +281,10 @@ export interface WorkflowRuntimeMeta {
   entryNodeIds?: string[]
   /** Hash of graph topology (nodes, edges, input mappings) */
   graphHash?: string
+  /** True when the workflow has a static, pre-computable step timeline */
+  deterministic?: boolean
+  /** Static planned steps metadata for deterministic workflows */
+  plannedSteps?: WorkflowPlannedStep[]
 }
 
 /**