@pikku/core 0.12.72 → 0.12.77

package/src/errors/errors.ts

@@ -1,6 +1,3 @@
-/**
- * The server cannot or will not process the request due to client error (e.g., malformed request syntax).
- */
 import { addError, PikkuError } from './error-handler.js'
 
 export class InvalidMiddlewareWireError extends PikkuError {}
@@ -27,10 +24,6 @@ addError(LocalEnvironmentOnlyError, {
   message: 'This operation is only available in local development mode',
 })
 
-/**
- * The server cannot or will not process the request due to client error (e.g., malformed request syntax).
- * @group Error
- */
 export class BadRequestError extends PikkuError {}
 addError(BadRequestError, {
   status: 400,
@@ -39,20 +32,8 @@ addError(BadRequestError, {
     'The server cannot or will not process the request due to client error (e.g., malformed request syntax).',
 })
 
-/**
- * Authentication is required and has failed or has not yet been provided.
- * @group Error
- */
 export class UnauthorizedError extends PikkuError {}
-/**
- * More specific error to why it's unauthorized.
- * @group Error
- */
 export class MissingSessionError extends PikkuError {}
-/**
- * More specific error to why it's unauthorized.
- * @group Error
- */
 export class InvalidSessionError extends PikkuError {}
 
 addError(UnauthorizedError, {
@@ -66,10 +47,6 @@ addError(InvalidSessionError, {
   message: 'The session provided is not valid.',
 })
 
-/**
- * Reserved for future use, often related to digital payment or subscription services.
- * @group Error
- */
 export class PaymentRequiredError extends PikkuError {}
 addError(PaymentRequiredError, {
   status: 402,
@@ -77,10 +54,6 @@ addError(PaymentRequiredError, {
     'Reserved for future use, often related to digital payment or subscription services.',
 })
 
-/**
- * The client does not have permission to access the requested resource.
- * @group Error
- */
 export class ForbiddenError extends PikkuError {}
 addError(ForbiddenError, {
   status: 403,
@@ -88,11 +61,6 @@ addError(ForbiddenError, {
     'The client does not have permission to access the requested resource.',
 })
 
-/**
- * A required credential is missing. The payload contains metadata
- * about the credential so the client can initiate a connect flow.
- * @group Error
- */
 export class MissingCredentialError extends PikkuError {
   public payload: {
     error: 'missing_credential'
@@ -120,11 +88,6 @@ addError(MissingCredentialError, {
   message: 'A required credential is not configured.',
 })
 
-/**
- * The session does not hold a scope required by the function. The payload
- * names the missing scope so the client can surface what to request.
- * @group Error
- */
 export class MissingScopeError extends PikkuError {
   public payload: {
     error: 'missing_scope'
@@ -144,20 +107,12 @@ addError(MissingScopeError, {
   message: 'The session does not hold a scope required by this function.',
 })
 
-/**
- * The session is readonly and cannot access a non-readonly function.
- * @group Error
- */
 export class ReadonlySessionError extends PikkuError {}
 addError(ReadonlySessionError, {
   status: 403,
   message: 'The session is readonly and cannot access this function.',
 })
 
-/**
- * The request was made from an origin that is not permitted to access this resource.
- * @group Error
- */
 export class InvalidOriginError extends PikkuError {}
 addError(InvalidOriginError, {
   status: 403,
@@ -165,25 +120,13 @@ addError(InvalidOriginError, {
     'The request was made from an origin that is not permitted to access this resource.',
 })
 
-/**
- * The server cannot find the requested resource.
- * @group Error
- */
 export class NotFoundError extends PikkuError {}
-/**
- * The server cannot find the requested route.
- * @group Error
- */
 addError(NotFoundError, {
   status: 404,
   mcpCode: -32601,
   message: 'The server cannot find the requested resource.',
 })
 
-/**
- * The request method is known by the server but is not supported by the resource.
- * @group Error
- */
 export class MethodNotAllowedError extends PikkuError {}
 addError(MethodNotAllowedError, {
   status: 405,
@@ -191,10 +134,6 @@ addError(MethodNotAllowedError, {
     'The request method is known by the server but is not supported by the resource.',
 })
 
-/**
- * The requested resource cannot produce a response matching the list of acceptable values in the request's headers.
- * @group Error
- */
 export class NotAcceptableError extends PikkuError {}
 addError(NotAcceptableError, {
   status: 406,
@@ -202,30 +141,18 @@ addError(NotAcceptableError, {
     "The requested resource cannot produce a response matching the list of acceptable values in the request's headers.",
 })
 
-/**
- * The client must authenticate itself to get the requested response.
- * @group Error
- */
 export class ProxyAuthenticationRequiredError extends PikkuError {}
 addError(ProxyAuthenticationRequiredError, {
   status: 407,
   message: 'The client must authenticate itself to get the requested response.',
 })
 
-/**
- * The server request expired
- * @group Error
- */
 export class RequestTimeoutError extends PikkuError {}
 addError(RequestTimeoutError, {
   status: 408,
   message: 'The request timeout has expired.',
 })
 
-/**
- * The request could not be completed due to a conflict with the current state of the target resource.
- * @group Error
- */
 export class ConflictError extends PikkuError {}
 addError(ConflictError, {
   status: 409,
@@ -233,10 +160,6 @@ addError(ConflictError, {
     'The request could not be completed due to a conflict with the current state of the target resource.',
 })
 
-/**
- * The resource that is being accessed is no longer available and will not be available again.
- * @group Error
- */
 export class GoneError extends PikkuError {}
 addError(GoneError, {
   status: 410,
@@ -244,10 +167,6 @@ addError(GoneError, {
     'The resource that is being accessed is no longer available and will not be available again.',
 })
 
-/**
- * The request did not specify the length of its content, which is required by the requested resource.
- * @group Error
- */
 export class LengthRequiredError extends PikkuError {}
 addError(LengthRequiredError, {
   status: 411,
@@ -255,10 +174,6 @@ addError(LengthRequiredError, {
     'The request did not specify the length of its content, which is required by the requested resource.',
 })
 
-/**
- * The server does not meet one of the preconditions that the requester put on the request.
- * @group Error
- */
 export class PreconditionFailedError extends PikkuError {}
 addError(PreconditionFailedError, {
   status: 412,
@@ -266,10 +181,6 @@ addError(PreconditionFailedError, {
     'The server does not meet one of the preconditions that the requester put on the request.',
 })
 
-/**
- * The request is larger than the server is willing or able to process.
- * @group Error
- */
 export class PayloadTooLargeError extends PikkuError {}
 addError(PayloadTooLargeError, {
   status: 413,
@@ -277,10 +188,6 @@ addError(PayloadTooLargeError, {
     'The request is larger than the server is willing or able to process.',
 })
 
-/**
- * The URI requested by the client is longer than the server is willing to interpret.
- * @group Error
- */
 export class URITooLongError extends PikkuError {}
 addError(URITooLongError, {
   status: 414,
@@ -288,10 +195,6 @@ addError(URITooLongError, {
     'The URI requested by the client is longer than the server is willing to interpret.',
 })
 
-/**
- * The server does not support the media format of the requested data.
- * @group Error
- */
 export class UnsupportedMediaTypeError extends PikkuError {}
 addError(UnsupportedMediaTypeError, {
   status: 415,
@@ -299,10 +202,6 @@ addError(UnsupportedMediaTypeError, {
     'The server does not support the media format of the requested data.',
 })
 
-/**
- * The client has asked for a portion of the file, but the server cannot supply that portion.
- * @group Error
- */
 export class RangeNotSatisfiableError extends PikkuError {}
 addError(RangeNotSatisfiableError, {
   status: 416,
@@ -310,10 +209,6 @@ addError(RangeNotSatisfiableError, {
     'The client has asked for a portion of the file, but the server cannot supply that portion.',
 })
 
-/**
- * The server cannot meet the requirements of the Expect request-header field.
- * @group Error
- */
 export class ExpectationFailedError extends PikkuError {}
 addError(ExpectationFailedError, {
   status: 417,
@@ -321,10 +216,6 @@ addError(ExpectationFailedError, {
     'The server cannot meet the requirements of the Expect request-header field.',
 })
 
-/**
- * Indicates that the server understood the content type of the request content, and the syntax of the request content was correct, but it was unable to process the contained instructions.
- * @group Error
- */
 export class UnprocessableContentError extends PikkuError {}
 addError(UnprocessableContentError, {
   status: 422,
@@ -332,10 +223,6 @@ addError(UnprocessableContentError, {
     'The server understood the content type of the request content, and the syntax of the request content was correct, but it was unable to process the contained instructions..',
 })
 
-/**
- * Indicates that the server understood the content type of the request content, and the syntax of the request content was correct, but it was unable to process the contained instructions.
- * @group Error
- */
 export class LockedError extends PikkuError {}
 addError(LockedError, {
   status: 423,
@@ -343,10 +230,6 @@ addError(LockedError, {
     "The resource is locked, meaning it can't be accessed. Its response body should contain information in WebDAV's XML format.",
 })
 
-/**
- * The user has sent too many requests in a given amount of time ("rate limiting").
- * @group Error
- */
 export class TooManyRequestsError extends PikkuError {}
 addError(TooManyRequestsError, {
   status: 429,
@@ -354,10 +237,6 @@ addError(TooManyRequestsError, {
     'The user has sent too many requests in a given amount of time ("rate limiting").',
 })
 
-/**
- * A generic error message, given when no more specific message is suitable.
- * @group Error
- */
 export class InternalServerError extends PikkuError {}
 addError(InternalServerError, {
   status: 500,
@@ -365,10 +244,6 @@ addError(InternalServerError, {
     'A generic error message, given when no more specific message is suitable.',
 })
 
-/**
- * The server does not recognize the request method and cannot support it.
- * @group Error
- */
 export class NotImplementedError extends PikkuError {}
 addError(NotImplementedError, {
   status: 501,
@@ -376,10 +251,6 @@ addError(NotImplementedError, {
     'The server does not recognize the request method and cannot support it.',
 })
 
-/**
- * The server was acting as a gateway or proxy and received an invalid response from the upstream server.
- * @group Error
- */
 export class BadGatewayError extends PikkuError {}
 addError(BadGatewayError, {
   status: 502,
@@ -387,20 +258,12 @@ addError(BadGatewayError, {
     'The server was acting as a gateway or proxy and received an invalid response from the upstream server.',
 })
 
-/**
- * The server is currently unavailable (overloaded or down).
- * @group Error
- */
 export class ServiceUnavailableError extends PikkuError {}
 addError(ServiceUnavailableError, {
   status: 503,
   message: 'The server is currently unavailable (overloaded or down).',
 })
 
-/**
- * The server was acting as a gateway or proxy and did not receive a timely response from the upstream server.
- * @group Error
- */
 export class GatewayTimeoutError extends PikkuError {}
 addError(GatewayTimeoutError, {
   status: 504,
@@ -408,10 +271,6 @@ addError(GatewayTimeoutError, {
     'The server was acting as a gateway or proxy and did not receive a timely response from the upstream server.',
 })
 
-/**
- * The server does not support the HTTP protocol version used in the request.
- * @group Error
- */
 export class HTTPVersionNotSupportedError extends PikkuError {}
 addError(HTTPVersionNotSupportedError, {
   status: 505,
@@ -419,10 +278,6 @@ addError(HTTPVersionNotSupportedError, {
     'The server does not support the HTTP protocol version used in the request.',
 })
 
-/**
- * The server took too long to complete the request, reaching the maximum compute time allowed.
- * @group Error
- */
 export class MaxComputeTimeReachedError extends PikkuError {}
 addError(MaxComputeTimeReachedError, {
   status: 524,
@@ -430,10 +285,6 @@ addError(MaxComputeTimeReachedError, {
     'The server took too long to complete the request, reaching the maximum compute time allowed.',
 })
 
-/**
- * A required schema was not found during validation.
- * @group Error
- */
 export class MissingSchemaError extends PikkuError {}
 addError(MissingSchemaError, {
   status: 500,
@@ -441,10 +292,18 @@ addError(MissingSchemaError, {
     'A required schema was not found. Ensure schema generation has been run.',
 })
 
-/**
- * An AI provider has not been configured. Set up an AI provider (e.g. OpenAI, Anthropic) to use agent features.
- * @group Error
- */
+export class WeakKeyMaterialError extends PikkuError {
+  constructor(name: string, minimumLength: number, actualLength: number) {
+    super(
+      `${name} must be at least ${minimumLength} characters of high-entropy key material, got ${actualLength}. Generate one with \`openssl rand -base64 32\` and redeploy every service that shares it.`
+    )
+  }
+}
+addError(WeakKeyMaterialError, {
+  status: 500,
+  message: 'A configured secret does not carry enough entropy to be used.',
+})
+
 export class AIProviderNotConfiguredError extends PikkuError {
   constructor() {
     super(
@@ -458,10 +317,6 @@ addError(AIProviderNotConfiguredError, {
     'No AI provider configured. Please set up an AI provider (e.g. OpenAI, Anthropic) and provide a valid API key to use this agent.',
 })
 
-/**
- * The AI provider API key is missing or invalid.
- * @group Error
- */
 export class AIProviderAuthError extends PikkuError {
   constructor(message?: string) {
     super(
@@ -475,3 +330,64 @@ addError(AIProviderAuthError, {
   message:
     'AI provider API key is missing or invalid. Please check your API key configuration.',
 })
+
+/**
+ * An administrative operation targeted a role that is declared in code.
+ *
+ * System roles ship with the product: the console may show and grant them, but
+ * renaming, re-scoping or deleting one would let a UI action silently change
+ * what a declared persona means, and what every scenario written against that
+ * role is actually testing.
+ * @group Error
+ */
+export class SystemRoleImmutableError extends PikkuError {
+  public payload: {
+    error: 'system_role_immutable'
+    role: string
+    operation: string
+  }
+
+  constructor(role: string, operation: string) {
+    super(
+      `Cannot ${operation} '${role}': it is a system role, declared in code with defineSystemRole. ` +
+        `Edit the declaration, or create a separate role in the console.`
+    )
+    this.payload = {
+      error: 'system_role_immutable',
+      role,
+      operation,
+    }
+  }
+}
+addError(SystemRoleImmutableError, {
+  status: 409,
+  message: 'This role is declared in code and cannot be changed here.',
+})
+
+/**
+ * A role was created with the name of a role declared in code.
+ *
+ * Shadowing is refused rather than merged: two rows answering to one name make
+ * "does Susan hold `buyer`?" depend on which one the store happened to return.
+ * @group Error
+ */
+export class SystemRoleShadowedError extends PikkuError {
+  public payload: {
+    error: 'system_role_shadowed'
+    role: string
+  }
+
+  constructor(role: string) {
+    super(
+      `Cannot create role '${role}': a system role of that name is declared in code.`
+    )
+    this.payload = {
+      error: 'system_role_shadowed',
+      role,
+    }
+  }
+}
+addError(SystemRoleShadowedError, {
+  status: 409,
+  message: 'A system role of that name is already declared in code.',
+})

package/src/function/abort-scope.test.ts

@@ -0,0 +1,97 @@
+import { describe, test } from 'node:test'
+import assert from 'node:assert/strict'
+
+import {
+  AbandonedError,
+  beginChanges,
+  getAbortScope,
+  runInAbortScope,
+  type AbortScope,
+} from './abort-scope.js'
+
+describe('beginChanges', () => {
+  test('is a no-op outside a scope, so a function need not know how it was called', async () => {
+    await beginChanges()
+    assert.equal(getAbortScope(), undefined)
+  })
+
+  test('lets the mutation proceed while the caller is still there', async () => {
+    let declared = false
+    const scope: AbortScope = {
+      abandoned: false,
+      onBeginChanges: () => {
+        declared = true
+      },
+    }
+
+    let mutated = false
+    await runInAbortScope(scope, async () => {
+      await beginChanges()
+      mutated = true
+    })
+
+    assert.equal(mutated, true)
+    assert.equal(declared, true)
+  })
+
+  test('stops the mutation when the caller has gone, and reports why', async () => {
+    let mutated = false
+    const scope: AbortScope = { abandoned: true, reason: 'speech' }
+
+    await assert.rejects(
+      () =>
+        runInAbortScope(scope, async () => {
+          await beginChanges()
+          mutated = true
+        }),
+      (error: unknown) => {
+        assert.ok(error instanceof AbandonedError)
+        assert.match(error.message, /speech/)
+        return true
+      }
+    )
+
+    // The whole point: the irreversible line never ran.
+    assert.equal(mutated, false)
+  })
+
+  test('survives the await boundaries a real function has', async () => {
+    // AsyncLocalStorage is the reason this works — the checkpoint is usually
+    // several awaits deep inside helpers that never took the scope as an
+    // argument.
+    const scope: AbortScope = { abandoned: true }
+    const nestedHelper = async () => {
+      await new Promise((resolve) => setImmediate(resolve))
+      await beginChanges()
+    }
+
+    await assert.rejects(
+      () =>
+        runInAbortScope(scope, async () => {
+          await new Promise((resolve) => setImmediate(resolve))
+          return nestedHelper()
+        }),
+      AbandonedError
+    )
+  })
+
+  test('reads the scope live, so an interrupt mid-function is still caught', async () => {
+    let aborted = false
+    const scope: AbortScope = {
+      get abandoned() {
+        return aborted
+      },
+    }
+
+    await assert.rejects(
+      () =>
+        runInAbortScope(scope, async () => {
+          // Plenty of interruptible work happens before the checkpoint.
+          await new Promise((resolve) => setImmediate(resolve))
+          aborted = true
+          await beginChanges()
+        }),
+      AbandonedError
+    )
+  })
+})

package/src/function/abort-scope.ts

@@ -0,0 +1,80 @@
+import { AsyncLocalStorage } from 'node:async_hooks'
+
+/**
+ * Raised by {@link beginChanges} when the caller has gone away before anything
+ * was changed. Distinct from a failure: nothing happened, so there is nothing
+ * to report, retry or apologise for.
+ */
+export class AbandonedError extends Error {
+  constructor(reason?: string) {
+    super(
+      reason
+        ? `Aborted before making changes: ${reason}`
+        : 'Aborted before making changes'
+    )
+    this.name = 'AbandonedError'
+  }
+}
+
+export interface AbortScope {
+  /** Whether whatever asked for this work has gone away. */
+  readonly abandoned: boolean
+  /** Why, when known — an interrupt reason, a disconnect, a cancellation. */
+  readonly reason?: string
+  /** Called by `beginChanges()` once a function commits to mutating. */
+  onBeginChanges?: () => void
+}
+
+/**
+ * The ambient "is my caller still there?" signal.
+ *
+ * Ambient rather than a parameter because the question is the same one for
+ * every wiring — an agent run that was interrupted, an HTTP request whose
+ * client disconnected, a cancelled workflow — and threading it through every
+ * signature would mean changing every function that merely sits between the
+ * wiring and the mutation.
+ */
+const scopeStorage = new AsyncLocalStorage<AbortScope>()
+
+/** Run `fn` with an abort scope that `beginChanges()` will observe. */
+export const runInAbortScope = <T>(scope: AbortScope, fn: () => T): T =>
+  scopeStorage.run(scope, fn)
+
+/** The current scope, if the caller is running inside one. */
+export const getAbortScope = (): AbortScope | undefined =>
+  scopeStorage.getStore()
+
+/**
+ * Declare that everything after this line changes something.
+ *
+ * ```ts
+ * const plan = await computePlan(input)   // interruptible, costs nothing to redo
+ * await beginChanges()
+ * await db.deleteProject(input.projectId) // past the point of no return
+ * ```
+ *
+ * Two things happen here. If the caller has already gone away it throws, so the
+ * mutation never runs and the interrupt is clean — nothing happened, and the
+ * user is told nothing because there is nothing to tell. If the caller is still
+ * there it marks this call as mutating, so an interrupt landing *after* this
+ * point produces an `undelivered` note on the thread rather than silently
+ * discarding work that did happen.
+ *
+ * It throws rather than returning a boolean on purpose: `if (await ...)` invites
+ * ignoring the answer, and the failure mode of ignoring it is a mutation nobody
+ * asked for.
+ *
+ * Entirely cooperative, and safe to call anywhere — outside a scope it is a
+ * no-op, so a function does not need to know how it was invoked. A function
+ * that never calls it keeps the conservative default: if it is not marked
+ * `readonly`, an interrupt assumes it changed something and says so. The tool
+ * that forgot to call this is exactly the one that cannot be assumed harmless.
+ */
+export const beginChanges = async (): Promise<void> => {
+  const scope = scopeStorage.getStore()
+  if (!scope) return
+  if (scope.abandoned) {
+    throw new AbandonedError(scope.reason)
+  }
+  scope.onBeginChanges?.()
+}

package/src/function/function-runner.test.ts

@@ -19,7 +19,6 @@ beforeEach(() => {
   resetPikkuState()
 })
 
-// Helper function to add function with metadata for tests
 const addTestFunction = (funcName: string, funcConfig: any) => {
   addFunction(funcName, funcConfig)
   // Convert tags to middleware metadata (tags are organizational only; they no
@@ -62,7 +61,6 @@ describe('runPikkuFunc - Integration Tests', () => {
     addTagMiddleware('wiringTag', [createMiddleware('wiringTag')])
     addTagMiddleware('funcTag', [createMiddleware('funcTag')])
 
-    // Register function with middleware and tags
     addTestFunction('testFunc', {
       func: async () => {
         executionOrder.push('main')
@@ -235,7 +233,6 @@ describe('runPikkuFunc - Integration Tests', () => {
       await next()
     }
 
-    // Add same middleware to tag and directly
     addTagMiddleware('testTag', [duplicatedMiddleware])
 
     addTestFunction('testFunc', {
@@ -252,7 +249,6 @@ describe('runPikkuFunc - Integration Tests', () => {
       wire: {},
     })
 
-    // Should only execute once due to deduplication
     assert.equal(executionCount, 1)
   })
 
@@ -402,7 +398,6 @@ describe('runPikkuFunc - Integration Tests', () => {
     )
 
     assert.equal(result, 'success')
-    // Permissions run after middleware (middleware can set/modify session)
     assert.deepEqual(executionOrder, [
       'funcMiddleware',
       'funcPermission',
@@ -435,7 +430,6 @@ describe('runPikkuFunc - Integration Tests', () => {
 
     assert.deepEqual(receivedServices, mockServices)
     assert.equal(receivedData, testData)
-    // Check that wire has rpc service and session
     assert.ok(receivedWire.rpc)
     assert.equal(receivedWire.session, undefined)
   })
@@ -452,7 +446,6 @@ describe('runPikkuFunc - Integration Tests', () => {
     })
 
     const asyncCreateWireServices = async () => {
-      // Simulate async service creation
       await new Promise((resolve) => setTimeout(resolve, 1))
       return wireServices
     }