@pikku/core 0.11.2 → 0.12.1

package/dist/services/in-memory-workflow-service.js

@@ -0,0 +1,287 @@
+import { randomUUID } from 'crypto';
+import { PikkuWorkflowService } from '../wirings/workflow/pikku-workflow-service.js';
+/**
+ * In-memory implementation of WorkflowService for inline-only execution
+ *
+ * This is a lightweight workflow service that stores all state in memory.
+ * It only supports inline execution (no queue workers) and is ideal for:
+ * - CLI tools that need workflow-like step orchestration
+ * - Testing and development
+ * - Single-process applications without persistence requirements
+ *
+ * @example
+ * ```typescript
+ * const workflowService = new InMemoryWorkflowService()
+ * await workflowService.startWorkflow('myWorkflow', input, { type: 'cli' }, rpc, { inline: true })
+ * ```
+ */
+export class InMemoryWorkflowService extends PikkuWorkflowService {
+    runs = new Map();
+    steps = new Map(); // keyed by `${runId}:${stepName}`
+    stepData = new Map(); // keyed by stepId
+    stepHistory = new Map(); // keyed by runId
+    runState = new Map(); // keyed by runId
+    branchKeys = new Map(); // keyed by stepId
+    workflowVersions = new Map(); // keyed by `${name}:${graphHash}`
+    async createRun(workflowName, input, inline, graphHash, wire) {
+        const runId = randomUUID();
+        const now = new Date();
+        const run = {
+            id: runId,
+            workflow: workflowName,
+            status: 'running',
+            input,
+            inline,
+            graphHash,
+            wire,
+            createdAt: now,
+            updatedAt: now,
+        };
+        this.runs.set(runId, run);
+        this.stepHistory.set(runId, []);
+        this.runState.set(runId, {});
+        if (inline) {
+            this.registerInlineRun(runId);
+        }
+        return runId;
+    }
+    async getRun(id) {
+        return this.runs.get(id) || null;
+    }
+    async getRunHistory(runId) {
+        return this.stepHistory.get(runId) || [];
+    }
+    async updateRunStatus(id, status, output, error) {
+        const run = this.runs.get(id);
+        if (run) {
+            run.status = status;
+            run.updatedAt = new Date();
+            if (output !== undefined)
+                run.output = output;
+            if (error !== undefined)
+                run.error = error;
+        }
+    }
+    async insertStepState(runId, stepName, rpcName, data, stepOptions) {
+        const stepId = randomUUID();
+        const now = new Date();
+        const step = {
+            stepId,
+            status: 'pending',
+            attemptCount: 1,
+            retries: stepOptions?.retries,
+            retryDelay: stepOptions?.retryDelay,
+            createdAt: now,
+            updatedAt: now,
+        };
+        const key = `${runId}:${stepName}`;
+        this.steps.set(key, step);
+        this.stepData.set(stepId, { rpcName, data, stepName });
+        // Add to history
+        const history = this.stepHistory.get(runId) || [];
+        history.push({ ...step, stepName });
+        this.stepHistory.set(runId, history);
+        return step;
+    }
+    async getStepState(runId, stepName) {
+        const key = `${runId}:${stepName}`;
+        const step = this.steps.get(key);
+        if (!step) {
+            return {
+                stepId: '',
+                status: 'pending',
+                attemptCount: 0,
+                createdAt: new Date(),
+                updatedAt: new Date(),
+            };
+        }
+        return step;
+    }
+    async setStepRunning(stepId) {
+        for (const step of this.steps.values()) {
+            if (step.stepId === stepId) {
+                step.status = 'running';
+                step.runningAt = new Date();
+                step.updatedAt = new Date();
+                break;
+            }
+        }
+    }
+    async setStepScheduled(stepId) {
+        for (const step of this.steps.values()) {
+            if (step.stepId === stepId) {
+                step.status = 'scheduled';
+                step.scheduledAt = new Date();
+                step.updatedAt = new Date();
+                break;
+            }
+        }
+    }
+    async setStepResult(stepId, result) {
+        for (const step of this.steps.values()) {
+            if (step.stepId === stepId) {
+                step.status = 'succeeded';
+                step.result = result;
+                step.succeededAt = new Date();
+                step.updatedAt = new Date();
+                break;
+            }
+        }
+    }
+    async setStepError(stepId, error) {
+        for (const step of this.steps.values()) {
+            if (step.stepId === stepId) {
+                step.status = 'failed';
+                step.error = {
+                    name: error.name,
+                    message: error.message,
+                    stack: error.stack,
+                };
+                step.failedAt = new Date();
+                step.updatedAt = new Date();
+                break;
+            }
+        }
+    }
+    async createRetryAttempt(failedStepId, status) {
+        // Find the failed step
+        let failedStep;
+        let runId;
+        let stepName;
+        for (const [key, step] of this.steps.entries()) {
+            if (step.stepId === failedStepId) {
+                failedStep = step;
+                const parts = key.split(':');
+                runId = parts[0];
+                stepName = parts.slice(1).join(':');
+                break;
+            }
+        }
+        if (!failedStep || !runId || !stepName) {
+            throw new Error(`Step not found: ${failedStepId}`);
+        }
+        const failedStepData = this.stepData.get(failedStepId);
+        const newStepId = randomUUID();
+        const now = new Date();
+        const newStep = {
+            stepId: newStepId,
+            status,
+            attemptCount: failedStep.attemptCount + 1,
+            retries: failedStep.retries,
+            retryDelay: failedStep.retryDelay,
+            createdAt: now,
+            updatedAt: now,
+        };
+        if (status === 'running') {
+            newStep.runningAt = now;
+        }
+        const key = `${runId}:${stepName}`;
+        this.steps.set(key, newStep);
+        // Copy step data to new step
+        if (failedStepData) {
+            this.stepData.set(newStepId, { ...failedStepData });
+        }
+        // Add to history
+        const history = this.stepHistory.get(runId) || [];
+        history.push({ ...newStep, stepName });
+        this.stepHistory.set(runId, history);
+        return newStep;
+    }
+    async withRunLock(_id, fn) {
+        // In-memory service doesn't need locking for inline execution
+        return fn();
+    }
+    async withStepLock(_runId, _stepName, fn) {
+        // In-memory service doesn't need locking for inline execution
+        return fn();
+    }
+    async close() {
+        // Clear all in-memory state
+        this.runs.clear();
+        this.steps.clear();
+        this.stepData.clear();
+        this.stepHistory.clear();
+        this.runState.clear();
+        this.branchKeys.clear();
+        this.workflowVersions.clear();
+    }
+    // Graph workflow methods
+    async getCompletedGraphState(runId) {
+        const completedNodeIds = [];
+        const failedNodeIds = [];
+        const prefix = `${runId}:`;
+        for (const [key, step] of this.steps.entries()) {
+            if (!key.startsWith(prefix))
+                continue;
+            const nodeId = key.substring(prefix.length);
+            if (step.status === 'succeeded') {
+                completedNodeIds.push(nodeId);
+            }
+            else if (step.status === 'failed') {
+                const maxAttempts = (step.retries ?? 0) + 1;
+                if (step.attemptCount >= maxAttempts) {
+                    failedNodeIds.push(nodeId);
+                }
+            }
+        }
+        const branchKeys = {};
+        for (const [stepId, branchKey] of this.branchKeys.entries()) {
+            const stepData = this.stepData.get(stepId);
+            if (stepData) {
+                branchKeys[stepData.stepName] = branchKey;
+            }
+        }
+        return { completedNodeIds, failedNodeIds, branchKeys };
+    }
+    async getNodesWithoutSteps(runId, nodeIds) {
+        const existingSteps = new Set();
+        const prefix = `${runId}:`;
+        for (const [key] of this.steps.entries()) {
+            if (key.startsWith(prefix)) {
+                existingSteps.add(key.substring(prefix.length));
+            }
+        }
+        return nodeIds.filter((id) => !existingSteps.has(id));
+    }
+    async getNodeResults(runId, nodeIds) {
+        const results = {};
+        for (const nodeId of nodeIds) {
+            const key = `${runId}:${nodeId}`;
+            const step = this.steps.get(key);
+            if (step?.result !== undefined) {
+                results[nodeId] = step.result;
+            }
+        }
+        return results;
+    }
+    async setBranchKey(runId, nodeId, branchKey) {
+        const key = `${runId}:${nodeId}`;
+        const step = this.steps.get(key);
+        if (step) {
+            this.branchKeys.set(step.stepId, branchKey);
+        }
+    }
+    async setBranchTaken(stepId, branchKey) {
+        this.branchKeys.set(stepId, branchKey);
+    }
+    async updateRunState(runId, name, value) {
+        const state = this.runState.get(runId) || {};
+        state[name] = value;
+        this.runState.set(runId, state);
+    }
+    async getRunState(runId) {
+        return this.runState.get(runId) || {};
+    }
+    async upsertWorkflowVersion(name, graphHash, graph, source) {
+        this.workflowVersions.set(`${name}:${graphHash}`, {
+            graph,
+            source,
+        });
+    }
+    async getWorkflowVersion(name, graphHash) {
+        const version = this.workflowVersions.get(`${name}:${graphHash}`);
+        if (!version)
+            return null;
+        return { graph: version.graph, source: version.source };
+    }
+}

package/dist/services/index.d.ts

@@ -1,14 +1,29 @@
 /**
  * @module @pikku/core
  */
-export * from './content-service.js';
-export * from './jwt-service.js';
-export * from './logger.js';
-export * from './secret-service.js';
-export * from './variables-service.js';
-export * from './schema-service.js';
-export * from './user-session-service.js';
-export * from './scheduler-service.js';
-export * from './local-secrets.js';
-export * from './local-variables.js';
-export * from './logger-console.js';
+export { LogLevel } from './logger.js';
+export { ScopedSecretService } from './scoped-secret-service.js';
+export { PikkuSessionService, createMiddlewareSessionWireProps, createFunctionSessionWireProps, } from './user-session-service.js';
+export { TypedSecretService } from './typed-secret-service.js';
+export { TypedVariablesService } from './typed-variables-service.js';
+export { LocalSecretService } from './local-secrets.js';
+export { LocalVariablesService } from './local-variables.js';
+export { ConsoleLogger } from './logger-console.js';
+export { InMemoryWorkflowService } from './in-memory-workflow-service.js';
+export { InMemoryTriggerService } from './in-memory-trigger-service.js';
+export { InMemoryAIRunStateService } from './in-memory-ai-run-state-service.js';
+export type { ContentService } from './content-service.js';
+export type { JWTService } from './jwt-service.js';
+export type { Logger } from './logger.js';
+export type { SecretService } from './secret-service.js';
+export type { VariablesService } from './variables-service.js';
+export type { SchemaService } from './schema-service.js';
+export type { SessionService } from './user-session-service.js';
+export type { ScheduledTaskSummary, ScheduledTaskInfo, SchedulerService, } from './scheduler-service.js';
+export type { TriggerService } from './trigger-service.js';
+export type { DeploymentService, DeploymentConfig, DeploymentInfo, DeploymentServiceConfig, } from './deployment-service.js';
+export type { AIStorageService } from './ai-storage-service.js';
+export type { AIAgentRunnerParams, AIAgentRunnerResult, AIAgentStepResult, AIAgentRunnerService, } from './ai-agent-runner-service.js';
+export type { CreateRunInput, AIRunStateService, } from './ai-run-state-service.js';
+export type { CredentialStatus, CredentialMeta, } from './typed-secret-service.js';
+export type { VariableStatus, VariableMeta } from './typed-variables-service.js';

package/dist/services/index.js

@@ -1,16 +1,14 @@
 /**
  * @module @pikku/core
  */
-// Interfaces
-export * from './content-service.js';
-export * from './jwt-service.js';
-export * from './logger.js';
-export * from './secret-service.js';
-export * from './variables-service.js';
-export * from './schema-service.js';
-export * from './user-session-service.js';
-export * from './scheduler-service.js';
-// Local implementations
-export * from './local-secrets.js';
-export * from './local-variables.js';
-export * from './logger-console.js';
+export { LogLevel } from './logger.js';
+export { ScopedSecretService } from './scoped-secret-service.js';
+export { PikkuSessionService, createMiddlewareSessionWireProps, createFunctionSessionWireProps, } from './user-session-service.js';
+export { TypedSecretService } from './typed-secret-service.js';
+export { TypedVariablesService } from './typed-variables-service.js';
+export { LocalSecretService } from './local-secrets.js';
+export { LocalVariablesService } from './local-variables.js';
+export { ConsoleLogger } from './logger-console.js';
+export { InMemoryWorkflowService } from './in-memory-workflow-service.js';
+export { InMemoryTriggerService } from './in-memory-trigger-service.js';
+export { InMemoryAIRunStateService } from './in-memory-ai-run-state-service.js';

package/dist/services/local-content.d.ts

@@ -1,4 +1,4 @@
-import { ContentService, Logger } from '@pikku/core/services';
+import type { ContentService, Logger } from '@pikku/core/services';
 export interface LocalContentConfig {
     localFileUploadPath: string;
     uploadUrlPrefix: string;
@@ -20,6 +20,7 @@ export declare class LocalContent implements ContentService {
     writeFile(assetKey: string, stream: ReadableStream | NodeJS.ReadableStream): Promise<boolean>;
     copyFile(assetKey: string, fromAbsolutePath: string): Promise<boolean>;
     readFile(assetKey: string): Promise<ReadableStream | NodeJS.ReadableStream>;
+    readFileAsBuffer(assetKey: string): Promise<Buffer>;
     deleteFile(assetKey: string): Promise<boolean>;
     private createDirectoryForFile;
 }

package/dist/services/local-content.js

@@ -1,5 +1,5 @@
 import { createReadStream, createWriteStream, promises } from 'fs';
-import { mkdir } from 'fs/promises';
+import { mkdir, readFile } from 'fs/promises';
 import { pipeline } from 'stream/promises';
 export class LocalContent {
     config;
@@ -69,6 +69,11 @@ export class LocalContent {
             throw e;
         }
     }
+    async readFileAsBuffer(assetKey) {
+        const filePath = `${this.config.localFileUploadPath}/${assetKey}`;
+        this.logger.debug(`Reading file as buffer: ${assetKey}`);
+        return readFile(filePath);
+    }
     async deleteFile(assetKey) {
         this.logger.debug(`deleting key: ${assetKey}`);
         try {

package/dist/services/local-secrets.d.ts

@@ -1,16 +1,19 @@
-import { SecretService } from './secret-service.js';
-import { VariablesService } from './variables-service.js';
+import type { SecretService } from './secret-service.js';
+import type { VariablesService } from './variables-service.js';
 /**
  * Service for retrieving secrets from environment variables.
+ * Supports storing secrets locally in memory for CLI operations.
  */
 export declare class LocalSecretService implements SecretService {
     private variables;
+    private localSecrets;
     /**
      * Creates an instance of LocalSecretService.
      */
     constructor(variables?: VariablesService);
     /**
      * Retrieves a secret by key.
+     * Checks local storage first, then falls back to environment variables.
      * @param key - The key of the secret to retrieve.
      * @returns A promise that resolves to the secret value.
      * @throws {Error} If the secret is not found.
@@ -18,9 +21,29 @@ export declare class LocalSecretService implements SecretService {
     getSecretJSON<R>(key: string): Promise<R>;
     /**
      * Retrieves a secret by key.
+     * Checks local storage first, then falls back to environment variables.
      * @param key - The key of the secret to retrieve.
      * @returns A promise that resolves to the secret value.
      * @throws {Error} If the secret is not found.
      */
     getSecret(key: string): Promise<string>;
+    /**
+     * Stores a JSON value as a secret in local storage.
+     * @param key - The key to store the secret under.
+     * @param value - The JSON value to store.
+     * @returns A promise that resolves when the secret is stored.
+     */
+    setSecretJSON(key: string, value: unknown): Promise<void>;
+    /**
+     * Checks if a secret exists without throwing.
+     * @param key - The key of the secret to check.
+     * @returns A promise that resolves to true if the secret exists.
+     */
+    hasSecret(key: string): Promise<boolean>;
+    /**
+     * Deletes a secret from local storage.
+     * @param key - The key of the secret to delete.
+     * @returns A promise that resolves when the secret is deleted.
+     */
+    deleteSecret(key: string): Promise<void>;
 }

package/dist/services/local-secrets.js

@@ -1,9 +1,11 @@
 import { LocalVariablesService } from './local-variables.js';
 /**
  * Service for retrieving secrets from environment variables.
+ * Supports storing secrets locally in memory for CLI operations.
  */
 export class LocalSecretService {
     variables;
+    localSecrets = new Map();
     /**
      * Creates an instance of LocalSecretService.
      */
@@ -12,11 +14,18 @@ export class LocalSecretService {
     }
     /**
      * Retrieves a secret by key.
+     * Checks local storage first, then falls back to environment variables.
      * @param key - The key of the secret to retrieve.
      * @returns A promise that resolves to the secret value.
      * @throws {Error} If the secret is not found.
      */
     async getSecretJSON(key) {
+        // Check local storage first
+        const localValue = this.localSecrets.get(key);
+        if (localValue) {
+            return JSON.parse(localValue);
+        }
+        // Fall back to environment variables
         const value = await this.variables.get(key);
         if (value) {
             return JSON.parse(value);
@@ -25,15 +34,51 @@ export class LocalSecretService {
     }
     /**
      * Retrieves a secret by key.
+     * Checks local storage first, then falls back to environment variables.
      * @param key - The key of the secret to retrieve.
      * @returns A promise that resolves to the secret value.
      * @throws {Error} If the secret is not found.
      */
     async getSecret(key) {
+        // Check local storage first
+        const localValue = this.localSecrets.get(key);
+        if (localValue) {
+            return localValue;
+        }
+        // Fall back to environment variables
         const value = await this.variables.get(key);
         if (value) {
             return value;
         }
         throw new Error(`Secret Not Found: ${key}`);
     }
+    /**
+     * Stores a JSON value as a secret in local storage.
+     * @param key - The key to store the secret under.
+     * @param value - The JSON value to store.
+     * @returns A promise that resolves when the secret is stored.
+     */
+    async setSecretJSON(key, value) {
+        this.localSecrets.set(key, JSON.stringify(value));
+    }
+    /**
+     * Checks if a secret exists without throwing.
+     * @param key - The key of the secret to check.
+     * @returns A promise that resolves to true if the secret exists.
+     */
+    async hasSecret(key) {
+        if (this.localSecrets.has(key)) {
+            return true;
+        }
+        const value = await this.variables.get(key);
+        return value !== undefined && value !== null && value !== '';
+    }
+    /**
+     * Deletes a secret from local storage.
+     * @param key - The key of the secret to delete.
+     * @returns A promise that resolves when the secret is deleted.
+     */
+    async deleteSecret(key) {
+        this.localSecrets.delete(key);
+    }
 }

package/dist/services/local-variables.d.ts

@@ -1,7 +1,12 @@
-import { VariablesService } from './variables-service.js';
+import type { VariablesService } from './variables-service.js';
 export declare class LocalVariablesService implements VariablesService {
     private variables;
     constructor(variables?: Record<string, string | undefined>);
     getAll(): Promise<Record<string, string | undefined>> | Record<string, string | undefined>;
     get(name: string): Promise<string | undefined> | string | undefined;
+    getJSON<T = unknown>(name: string): T | undefined;
+    set(name: string, value: string): void;
+    setJSON(name: string, value: unknown): void;
+    has(name: string): boolean;
+    delete(name: string): void;
 }

package/dist/services/local-variables.js

@@ -9,4 +9,22 @@ export class LocalVariablesService {
     get(name) {
         return this.variables[name];
     }
+    getJSON(name) {
+        const value = this.variables[name];
+        if (value === undefined)
+            return undefined;
+        return JSON.parse(value);
+    }
+    set(name, value) {
+        this.variables[name] = value;
+    }
+    setJSON(name, value) {
+        this.variables[name] = JSON.stringify(value);
+    }
+    has(name) {
+        return name in this.variables && this.variables[name] !== undefined;
+    }
+    delete(name) {
+        delete this.variables[name];
+    }
 }

package/dist/services/logger-console.d.ts

@@ -1,4 +1,5 @@
-import { Logger, LogLevel } from './logger.js';
+import type { Logger } from './logger.js';
+import { LogLevel } from './logger.js';
 /**
  * A logger implementation that logs messages to the console.
  */

package/dist/services/scheduler-service.d.ts

@@ -1,4 +1,4 @@
-import { CoreUserSession } from '../types/core.types.js';
+import type { CoreUserSession } from '../types/core.types.js';
 /**
  * Minimal metadata for listing scheduled tasks
  */
@@ -60,4 +60,12 @@ export declare abstract class SchedulerService {
      * Close any open connections
      */
     abstract close(): Promise<void>;
+    /**
+     * Start recurring scheduled tasks
+     */
+    start(): Promise<void>;
+    /**
+     * Stop recurring scheduled tasks
+     */
+    stop(): Promise<void>;
 }

package/dist/services/scheduler-service.js

@@ -3,4 +3,12 @@
  * Implementations use queue backends (pg-boss, BullMQ) for distributed scheduling
  */
 export class SchedulerService {
+    /**
+     * Start recurring scheduled tasks
+     */
+    async start() { }
+    /**
+     * Stop recurring scheduled tasks
+     */
+    async stop() { }
 }

package/dist/services/schema-service.d.ts

@@ -21,4 +21,10 @@ export interface SchemaService {
      * @returns {Set<string>} A set containing the names of all available schemas.
      */
     getSchemaNames: () => Set<string>;
+    /**
+     * Retrieves the property keys from a compiled JSON schema.
+     * @param {string} schemaName - The name of the schema.
+     * @returns {string[]} An array of property keys, or empty array if schema not found.
+     */
+    getSchemaKeys: (schemaName: string) => string[];
 }

package/dist/services/scoped-secret-service.d.ts

@@ -0,0 +1,16 @@
+import type { SecretService } from './secret-service.js';
+/**
+ * A read-only wrapper around SecretService that restricts access
+ * to only a defined set of allowed secret keys.
+ */
+export declare class ScopedSecretService implements SecretService {
+    private secrets;
+    private allowedKeys;
+    constructor(secrets: SecretService, allowedKeys: Set<string>);
+    private assertAllowed;
+    getSecret(key: string): Promise<string>;
+    getSecretJSON<T = {}>(key: string): Promise<T>;
+    hasSecret(key: string): Promise<boolean>;
+    setSecretJSON(_key: string, _value: unknown): Promise<void>;
+    deleteSecret(_key: string): Promise<void>;
+}

package/dist/services/scoped-secret-service.js

@@ -0,0 +1,35 @@
+/**
+ * A read-only wrapper around SecretService that restricts access
+ * to only a defined set of allowed secret keys.
+ */
+export class ScopedSecretService {
+    secrets;
+    allowedKeys;
+    constructor(secrets, allowedKeys) {
+        this.secrets = secrets;
+        this.allowedKeys = allowedKeys;
+    }
+    assertAllowed(key) {
+        if (!this.allowedKeys.has(key)) {
+            throw new Error(`Access denied to secret key: ${key}`);
+        }
+    }
+    async getSecret(key) {
+        this.assertAllowed(key);
+        return this.secrets.getSecret(key);
+    }
+    async getSecretJSON(key) {
+        this.assertAllowed(key);
+        return this.secrets.getSecretJSON(key);
+    }
+    async hasSecret(key) {
+        this.assertAllowed(key);
+        return this.secrets.hasSecret(key);
+    }
+    async setSecretJSON(_key, _value) {
+        throw new Error('setSecretJSON is not allowed in scoped secret service');
+    }
+    async deleteSecret(_key) {
+        throw new Error('deleteSecret is not allowed in scoped secret service');
+    }
+}