@pikku/core 0.12.9 → 0.12.11

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

@@ -0,0 +1,89 @@
+import { pikkuState } from '../../../pikku-state.js'
+import type { CLIMeta } from '../cli.types.js'
+import { parseCLIArguments, generateCommandHelp } from '../command-parser.js'
+import { runCLICommand } from '../cli-runner.js'
+import type { CoreSingletonServices, CreateWireServices } from '../../../types/core.types.js'
+
+/**
+ * Handles raw CLI input from a WebSocket channel.
+ * Parses the args, resolves the command, and either returns help or executes it.
+ */
+export async function handleRawCLI({
+  programName,
+  args,
+  singletonServices,
+  createWireServices,
+}: {
+  programName: string
+  args: string[]
+  singletonServices: CoreSingletonServices
+  createWireServices?: CreateWireServices
+}): Promise<{ help?: string; result?: unknown; error?: string }> {
+  const allCLIMeta = pikkuState(null, 'cli', 'meta') as CLIMeta | undefined
+  if (!allCLIMeta) {
+    return { error: 'CLI metadata not found' }
+  }
+
+  const programMeta = allCLIMeta.programs[programName]
+  if (!programMeta) {
+    return { error: `Program "${programName}" not found` }
+  }
+
+  // Handle empty input or explicit help
+  if (
+    args.length === 0 ||
+    args.includes('--help') ||
+    args.includes('-h') ||
+    args[0] === 'help'
+  ) {
+    const helpArgs = args.filter(
+      (a) => a !== 'help' && a !== '--help' && a !== '-h'
+    )
+    const helpText = generateCommandHelp(programName, allCLIMeta, helpArgs)
+    return { help: helpText }
+  }
+
+  // Parse the args
+  const parsed = parseCLIArguments(args, programName, allCLIMeta)
+
+  // If there are errors or the command resolves to a group (no function), show help
+  if (parsed.errors.length > 0 || parsed.commandPath.length === 0) {
+    const helpText = generateCommandHelp(
+      programName,
+      allCLIMeta,
+      parsed.commandPath
+    )
+    return { help: helpText }
+  }
+
+  // Check if the resolved command has a pikkuFuncId (is executable)
+  let current: { pikkuFuncId?: string; subcommands?: Record<string, any> } | undefined = programMeta.commands[parsed.commandPath[0]]
+  for (let i = 1; i < parsed.commandPath.length; i++) {
+    current = current?.subcommands?.[parsed.commandPath[i]]
+  }
+  if (!current?.pikkuFuncId) {
+    // It's a group command — show help scoped to that group
+    const helpText = generateCommandHelp(
+      programName,
+      allCLIMeta,
+      parsed.commandPath
+    )
+    return { help: helpText }
+  }
+
+  // Execute the command
+  const data = { ...parsed.positionals, ...parsed.options }
+
+  try {
+    const result = await runCLICommand({
+      program: programName,
+      commandPath: parsed.commandPath,
+      data,
+      singletonServices,
+      createWireServices,
+    })
+    return { result }
+  } catch (e: unknown) {
+    return { error: (e as Error).message }
+  }
+}

package/src/wirings/cli/channel/index.ts

@@ -1 +1,2 @@
 export { executeCLIViaChannel } from './cli-channel-runner.js'
+export { handleRawCLI } from './cli-raw-channel-runner.js'

package/src/wirings/credential/credential.types.ts

@@ -0,0 +1,28 @@
+import type { OAuth2CredentialConfig } from '../secret/secret.types.js'
+
+export type CoreCredential<T = unknown> = {
+  name: string
+  displayName: string
+  description?: string
+  type: 'singleton' | 'wire'
+  schema: T
+  oauth2?: OAuth2CredentialConfig & {
+    appCredentialSecretId: string
+  }
+}
+
+export type CredentialDefinitionMeta = {
+  name: string
+  displayName: string
+  description?: string
+  type: 'singleton' | 'wire'
+  schema?: Record<string, unknown> | string
+  oauth2?: OAuth2CredentialConfig & {
+    appCredentialSecretId: string
+  }
+  sourceFile?: string
+}
+
+export type CredentialDefinitionsMeta = Record<string, CredentialDefinitionMeta>
+
+export type CredentialDefinitions = CredentialDefinitionMeta[]

package/src/wirings/credential/index.ts

@@ -0,0 +1,8 @@
+export { wireCredential } from './wire-credential.js'
+export { validateAndBuildCredentialDefinitionsMeta } from './validate-credential-definitions.js'
+export type {
+  CoreCredential,
+  CredentialDefinitionMeta,
+  CredentialDefinitionsMeta,
+  CredentialDefinitions,
+} from './credential.types.js'

package/src/wirings/credential/validate-credential-definitions.ts

@@ -0,0 +1,64 @@
+import type {
+  CredentialDefinitions,
+  CredentialDefinitionsMeta,
+} from './credential.types.js'
+
+export interface SchemaRefLike {
+  variableName: string
+  sourceFile: string
+}
+
+export function validateAndBuildCredentialDefinitionsMeta(
+  definitions: CredentialDefinitions,
+  schemaLookup: Map<string, SchemaRefLike>
+): CredentialDefinitionsMeta {
+  const meta: CredentialDefinitionsMeta = {}
+
+  for (const def of definitions) {
+    const existing = meta[def.name]
+
+    if (existing) {
+      if (def.schema && existing.schema) {
+        const defSchemaRef = schemaLookup.get(def.schema as string)
+        const existingSchemaRef = schemaLookup.get(existing.schema as string)
+
+        if (defSchemaRef && existingSchemaRef) {
+          if (
+            defSchemaRef.variableName !== existingSchemaRef.variableName ||
+            defSchemaRef.sourceFile !== existingSchemaRef.sourceFile
+          ) {
+            throw new Error(
+              `Credential '${def.name}' is defined with different schemas.\n` +
+                `  First definition: ${existing.sourceFile} (schema: ${existingSchemaRef.variableName})\n` +
+                `  Second definition: ${def.sourceFile} (schema: ${defSchemaRef.variableName})\n` +
+                `Credentials sharing a name must use the same schema.`
+            )
+          }
+        }
+      }
+
+      if (def.type !== existing.type) {
+        throw new Error(
+          `Credential '${def.name}' is defined with different types.\n` +
+            `  First definition: ${existing.sourceFile} (type: ${existing.type})\n` +
+            `  Second definition: ${def.sourceFile} (type: ${def.type})\n` +
+            `Credentials sharing a name must use the same type.`
+        )
+      }
+
+      continue
+    }
+
+    meta[def.name] = {
+      name: def.name,
+      displayName: def.displayName,
+      description: def.description,
+      type: def.type,
+      schema: def.schema,
+      oauth2: def.oauth2,
+      sourceFile: def.sourceFile,
+    }
+  }
+
+  return meta
+}

package/src/wirings/credential/wire-credential.ts

@@ -0,0 +1,49 @@
+import type { CoreCredential } from './credential.types.js'
+
+/**
+ * No-op function for declaring credentials.
+ * This exists purely for TypeScript type checking and will be tree-shaken.
+ * The CLI extracts metadata via AST parsing.
+ *
+ * @example
+ * ```typescript
+ * // Per-user API key
+ * wireCredential({
+ *   name: 'stripe',
+ *   displayName: 'Stripe API Key',
+ *   type: 'wire',
+ *   schema: z.object({ apiKey: z.string() }),
+ * })
+ *
+ * // Per-user OAuth
+ * wireCredential({
+ *   name: 'google-sheets',
+ *   displayName: 'Google Sheets',
+ *   type: 'wire',
+ *   schema: z.object({ accessToken: z.string(), refreshToken: z.string() }),
+ *   oauth2: {
+ *     appCredentialSecretId: 'GOOGLE_OAUTH_APP',
+ *     authorizationUrl: 'https://accounts.google.com/o/oauth2/v2/auth',
+ *     tokenUrl: 'https://oauth2.googleapis.com/token',
+ *     scopes: ['https://www.googleapis.com/auth/spreadsheets'],
+ *     tokenSecretId: 'GOOGLE_OAUTH_TOKENS',
+ *   }
+ * })
+ *
+ * // Platform-level OAuth (singleton)
+ * wireCredential({
+ *   name: 'slack',
+ *   displayName: 'Slack',
+ *   type: 'singleton',
+ *   schema: z.object({ accessToken: z.string(), refreshToken: z.string() }),
+ *   oauth2: {
+ *     appCredentialSecretId: 'SLACK_OAUTH_APP',
+ *     authorizationUrl: 'https://slack.com/oauth/v2/authorize',
+ *     tokenUrl: 'https://slack.com/api/oauth.v2.access',
+ *     scopes: ['chat:write', 'channels:read'],
+ *     tokenSecretId: 'SLACK_OAUTH_TOKENS',
+ *   }
+ * })
+ * ```
+ */
+export const wireCredential = <T>(_config: CoreCredential<T>): void => {}

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

@@ -33,6 +33,10 @@ import {
 } from '../../pikku-state.js'
 import { PikkuSessionService } from '../../services/user-session-service.js'
 import { getErrorResponse } from '../../errors/error-handler.js'
+import {
+  PikkuCredentialWireService,
+  createMiddlewareCredentialWireProps,
+} from '../../services/credential-wire-service.js'
 import { handleHTTPError } from '../../handle-error.js'
 import { pikkuState } from '../../pikku-state.js'
 import { PikkuFetchHTTPResponse } from './pikku-fetch-http-response.js'
@@ -299,6 +303,7 @@ const executeRoute = async (
   }
 ) => {
   const userSession = new PikkuSessionService<CoreUserSession>()
+  const credentialWire = new PikkuCredentialWireService()
   const { params, route, meta } = matchedRoute
   const { singletonServices, createWireServices, skipUserSession, requestId } =
     services
@@ -377,6 +382,7 @@ const executeRoute = async (
     setSession: (s: any) => userSession.setInitial(s),
     getSession: () => userSession.get(),
     hasSessionChanged: () => userSession.sessionChanged,
+    ...createMiddlewareCredentialWireProps(credentialWire),
   }
 
   result = await runPikkuFunc(
@@ -396,6 +402,7 @@ const executeRoute = async (
       tags: route.tags,
       wire,
       sessionService: userSession,
+      credentialWireService: credentialWire,
       packageName: meta.packageName,
     }
   )

package/src/wirings/oauth2/index.ts

@@ -1,3 +1,4 @@
 export { OAuth2Client } from './oauth2-client.js'
-export { wireOAuth2Credential } from './wire-oauth2-credential.js'
+export { createOAuth2Handler } from './oauth2-routes.js'
+export type { CreateOAuth2HandlerOptions } from './oauth2-routes.js'
 export type { OAuth2AppCredential, OAuth2Token } from './oauth2.types.js'

package/src/wirings/oauth2/oauth2-client.ts

@@ -30,7 +30,8 @@ import type { SecretService } from '../../services/secret-service.js'
  * })
  * ```
  */
-const DEFAULT_TIMEOUT_MS = 30000
+const DEFAULT_TIMEOUT_MS = 30_000
+const TOKEN_EXPIRY_BUFFER_MS = 60_000
 
 /**
  * Helper to fetch with a timeout using AbortController.
@@ -145,18 +146,15 @@ export class OAuth2Client {
    * Uses a promise lock to prevent concurrent refresh attempts.
    */
   private async refreshAndGetToken(): Promise<string> {
-    // If already refreshing, wait for that to complete
     if (this.refreshPromise) {
       const token = await this.refreshPromise
       return token.accessToken
     }
 
-    // Start refresh
     this.refreshPromise = this.doRefreshToken()
 
     try {
       const token = await this.refreshPromise
-      this.cachedToken = token
       return token.accessToken
     } finally {
       this.refreshPromise = null
@@ -211,9 +209,8 @@ export class OAuth2Client {
       scope: data.scope,
     }
 
-    // Cache and persist the refreshed token
-    this.cachedToken = token
     await this.secrets.setSecretJSON(this.oauth2Config.tokenSecretId, token)
+    this.cachedToken = token
 
     return token
   }
@@ -225,8 +222,7 @@ export class OAuth2Client {
     if (!token.expiresAt) {
       return true // No expiry info, assume valid
     }
-    // Add 60 second buffer to account for clock skew
-    return token.expiresAt > Date.now() + 60000
+    return token.expiresAt > Date.now() + TOKEN_EXPIRY_BUFFER_MS
   }
 
   /**

package/src/wirings/oauth2/oauth2-routes.ts

@@ -0,0 +1,234 @@
+import type { CredentialService } from '../../services/credential-service.js'
+import type { SecretService } from '../../services/secret-service.js'
+import type { JWTService } from '../../services/jwt-service.js'
+import type { CredentialDefinitionsMeta } from '../credential/credential.types.js'
+import type { OAuth2Token } from './oauth2.types.js'
+import { OAuth2Client } from './oauth2-client.js'
+
+const TOKEN_EXPIRY_BUFFER_MS = 60_000
+
+export type CreateOAuth2HandlerOptions = {
+  credentialsMeta: CredentialDefinitionsMeta
+  basePath?: string
+}
+
+type OAuth2RouteContext = {
+  credentialsMeta: CredentialDefinitionsMeta
+  basePath: string
+}
+
+function getCredentialMeta(ctx: OAuth2RouteContext, name: string) {
+  const meta = ctx.credentialsMeta[name]
+  if (!meta) {
+    throw new Error(`Credential '${name}' not found`)
+  }
+  if (!meta.oauth2) {
+    throw new Error(`Credential '${name}' is not an OAuth2 credential`)
+  }
+  return meta
+}
+
+/**
+ * Creates OAuth2 route handlers for user credential management.
+ *
+ * Returns individual handler functions for connect/callback/disconnect/status
+ * that handle the OAuth2 authorization code flow and store tokens in CredentialService.
+ *
+ * @example
+ * ```typescript
+ * const oauth2 = createOAuth2Handler({ credentialsMeta })
+ *
+ * const oauth2Routes = defineHTTPRoutes({
+ *   auth: true,
+ *   basePath: '/credentials',
+ *   routes: {
+ *     connect: { method: 'get', route: '/:name/connect', func: oauth2.connect },
+ *     callback: { method: 'get', route: '/:name/callback', func: oauth2.callback, auth: false },
+ *     disconnect: { method: 'delete', route: '/:name', func: oauth2.disconnect },
+ *     status: { method: 'get', route: '/:name/status', func: oauth2.status },
+ *   },
+ * })
+ *
+ * wireHTTPRoutes({ routes: { credentials: oauth2Routes } })
+ * ```
+ */
+export const createOAuth2Handler = (options: CreateOAuth2HandlerOptions) => {
+  const basePath = options.basePath ?? '/credentials'
+  const ctx: OAuth2RouteContext = {
+    credentialsMeta: options.credentialsMeta,
+    basePath,
+  }
+
+  const connectHandler = async (
+    services: {
+      secrets: SecretService
+      jwt: JWTService
+      credentialService: CredentialService
+    },
+    _data: any,
+    wire: any
+  ) => {
+    const { name } = wire.http.request.params()
+    const meta = getCredentialMeta(ctx, name)
+    const queryParams = wire.http.request.query()
+    const redirectUrl = queryParams.redirect_url || queryParams.redirect
+
+    const oauth2Client = new OAuth2Client(
+      meta.oauth2!,
+      meta.oauth2!.appCredentialSecretId,
+      services.secrets
+    )
+
+    const userId = wire.session?.userId
+    if (!userId) {
+      throw new Error('Authentication required for OAuth2 connect')
+    }
+
+    const state = await services.jwt.encode(
+      { value: 10, unit: 'minute' },
+      {
+        userId,
+        credentialName: name,
+        redirectUrl,
+      }
+    )
+
+    let origin = wire.http.request.header('origin')
+    if (!origin) {
+      const host = wire.http.request.header('host')
+      if (!host) {
+        throw new Error(
+          'Unable to determine request origin for OAuth2 callback'
+        )
+      }
+      const protocol = wire.http.request.header('x-forwarded-proto') || 'http'
+      origin = `${protocol}://${host}`
+    }
+    const callbackUrl = `${origin}${basePath}/${name}/callback`
+    const authUrl = await oauth2Client.getAuthorizationUrl(state, callbackUrl)
+
+    return Response.redirect(authUrl, 302)
+  }
+
+  const callbackHandler = async (
+    services: {
+      secrets: SecretService
+      jwt: JWTService
+      credentialService: CredentialService
+      logger: any
+    },
+    _data: any,
+    wire: any
+  ) => {
+    const { name } = wire.http.request.params()
+    const meta = getCredentialMeta(ctx, name)
+    const queryParams = wire.http.request.query()
+    const code = queryParams.code as string | undefined
+    const state = queryParams.state as string | undefined
+
+    if (!code || !state) {
+      throw new Error('Missing code or state parameter')
+    }
+
+    let statePayload: {
+      userId: string
+      credentialName: string
+      redirectUrl?: string
+    }
+    try {
+      statePayload = await services.jwt.decode(state)
+    } catch {
+      throw new Error('Invalid or expired OAuth2 state')
+    }
+
+    if (statePayload.credentialName !== name) {
+      throw new Error('Credential name mismatch in state')
+    }
+
+    const oauth2Client = new OAuth2Client(
+      meta.oauth2!,
+      meta.oauth2!.appCredentialSecretId,
+      services.secrets
+    )
+
+    let origin = wire.http.request.header('origin')
+    if (!origin) {
+      const host = wire.http.request.header('host')
+      if (!host) {
+        throw new Error(
+          'Unable to determine request origin for OAuth2 callback'
+        )
+      }
+      const protocol = wire.http.request.header('x-forwarded-proto') || 'http'
+      origin = `${protocol}://${host}`
+    }
+    const callbackUrl = `${origin}${basePath}/${name}/callback`
+    const tokens = await oauth2Client.exchangeCode(code, callbackUrl)
+
+    await services.credentialService.set(name, tokens, statePayload.userId)
+
+    services.logger.info(
+      `OAuth2 tokens stored for user '${statePayload.userId}', credential '${name}'`
+    )
+
+    if (statePayload.redirectUrl) {
+      return Response.redirect(statePayload.redirectUrl, 302)
+    } else {
+      return { success: true, credentialName: name }
+    }
+  }
+
+  const disconnectHandler = async (
+    services: { credentialService: CredentialService; logger: any },
+    _data: any,
+    wire: any
+  ) => {
+    const { name } = wire.http.request.params()
+    const userId = wire.session?.userId
+    if (!userId) {
+      throw new Error('Authentication required')
+    }
+    await services.credentialService.delete(name, userId)
+    services.logger.info(
+      `OAuth2 credential '${name}' disconnected for user '${userId}'`
+    )
+    return { success: true }
+  }
+
+  const statusHandler = async (
+    services: { credentialService: CredentialService },
+    _data: any,
+    wire: any
+  ) => {
+    const { name } = wire.http.request.params()
+    const userId = wire.session?.userId
+    if (!userId) {
+      throw new Error('Authentication required')
+    }
+
+    const credential = await services.credentialService.get<OAuth2Token>(
+      name,
+      userId
+    )
+
+    if (!credential) {
+      return { connected: false }
+    }
+
+    return {
+      connected: true,
+      hasRefreshToken: !!credential.refreshToken,
+      expiresAt: credential.expiresAt,
+      isExpired: credential.expiresAt
+        ? credential.expiresAt < Date.now() + TOKEN_EXPIRY_BUFFER_MS
+        : false,
+    }
+  }
+
+  return {
+    connect: { func: connectHandler } as any,
+    callback: { func: callbackHandler } as any,
+    disconnect: { func: disconnectHandler } as any,
+    status: { func: statusHandler } as any,
+  }
+}

package/src/wirings/oauth2/oauth2.types.ts

@@ -40,30 +40,3 @@ export type OAuth2Config = {
   /** Additional query parameters for authorization URL */
   additionalParams?: Record<string, string>
 }
-
-/**
- * Configuration for wireOAuth2Credential.
- * Combines standard credential fields with OAuth2-specific config.
- */
-export type CoreOAuth2Credential = {
-  /** Unique identifier for this credential */
-  name: string
-  /** Human-readable name for UI display */
-  displayName: string
-  /** Optional description for UI */
-  description?: string
-  /** Key used with SecretService to retrieve app credentials (clientId/clientSecret) */
-  secretId: string
-  /** Where access/refresh tokens are stored */
-  tokenSecretId: string
-  /** OAuth2 authorization URL */
-  authorizationUrl: string
-  /** OAuth2 token exchange URL */
-  tokenUrl: string
-  /** Required scopes */
-  scopes: string[]
-  /** Use PKCE flow */
-  pkce?: boolean
-  /** Additional query parameters for authorization URL */
-  additionalParams?: Record<string, string>
-}

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

@@ -1,4 +1,8 @@
-import type { PikkuWorkflowService } from '../pikku-workflow-service.js'
+import {
+  type PikkuWorkflowService,
+  WorkflowAsyncException,
+  WorkflowSuspendedException,
+} from '../pikku-workflow-service.js'
 import type { GraphWireState, PikkuGraphWire } from './workflow-graph.types.js'
 import { pikkuState, getSingletonServices } from '../../../pikku-state.js'
 import type { WorkflowRuntimeMeta, WorkflowRunWire } from '../workflow.types.js'
@@ -489,6 +493,11 @@ export async function executeGraphStep(
     } else {
       result = await rpcService.rpcWithWire(rpcName, data, {
         graph: graphWire,
+        workflow: workflowService.createWorkflowWire(
+          graphName,
+          runId,
+          rpcService
+        ),
       })
     }
 
@@ -498,6 +507,12 @@ export async function executeGraphStep(
 
     return result
   } catch (error) {
+    if (
+      error instanceof WorkflowAsyncException ||
+      error instanceof WorkflowSuspendedException
+    ) {
+      throw error
+    }
     if (error instanceof ChildWorkflowStartedException) {
       throw error
     }
@@ -619,6 +634,11 @@ async function executeGraphNodeInline(
     } else {
       result = await rpcService.rpcWithWire(rpcName, input, {
         graph: graphWire,
+        workflow: workflowService.createWorkflowWire(
+          graphName,
+          runId,
+          rpcService
+        ),
       })
     }
 
@@ -631,6 +651,12 @@ async function executeGraphNodeInline(
 
     await workflowService.setStepResult(stepState.stepId, result)
   } catch (error) {
+    if (
+      error instanceof WorkflowAsyncException ||
+      error instanceof WorkflowSuspendedException
+    ) {
+      throw error
+    }
     if (error instanceof RPCNotFoundError) {
       await workflowService.setStepError(stepState.stepId, error as Error)
       await workflowService.updateRunStatus(runId, 'suspended', undefined, {
@@ -855,6 +881,12 @@ export async function runWorkflowGraph(
           entryNodes
         )
       } catch (error) {
+        if (
+          error instanceof WorkflowAsyncException ||
+          error instanceof WorkflowSuspendedException
+        ) {
+          return
+        }
         await workflowService.updateRunStatus(runId, 'failed', undefined, {
           message: (error as Error).message,
           stack: (error as Error).stack || '',