@pikku/core 0.12.72 → 0.12.77

package/dist/errors/errors.js

@@ -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 {
 }
@@ -26,10 +23,6 @@ addError(LocalEnvironmentOnlyError, {
     status: 403,
     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, {
@@ -37,22 +30,10 @@ addError(BadRequestError, {
     mcpCode: -32600,
     message: '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, {
@@ -64,31 +45,18 @@ addError(InvalidSessionError, {
     status: 401,
     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,
     message: '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,
     message: '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 {
     payload;
     constructor(credentialName, credentialType, connectUrl) {
@@ -105,11 +73,6 @@ addError(MissingCredentialError, {
     status: 403,
     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 {
     payload;
     constructor(scope) {
@@ -124,285 +87,178 @@ addError(MissingScopeError, {
     status: 403,
     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,
     message: '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,
     message: '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,
     message: "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,
     message: '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,
     message: '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,
     message: '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,
     message: '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,
     message: '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,
     message: '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,
     message: '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,
     message: '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,
     message: '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,
     message: '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,
     message: "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,
     message: '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,
     message: '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,
     message: '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,
     message: '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,
     message: '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,
     message: '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,
     message: '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,
     message: '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, minimumLength, actualLength) {
+        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('No AI provider configured. Please set up an AI provider (e.g. OpenAI, Anthropic) and provide a valid API key to use this agent.');
@@ -412,10 +268,6 @@ addError(AIProviderNotConfiguredError, {
     status: 503,
     message: '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) {
         super(message ||
@@ -426,3 +278,49 @@ addError(AIProviderAuthError, {
     status: 401,
     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 {
+    payload;
+    constructor(role, operation) {
+        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 {
+    payload;
+    constructor(role) {
+        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/dist/function/abort-scope.d.ts

@@ -0,0 +1,47 @@
+/**
+ * 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 declare class AbandonedError extends Error {
+    constructor(reason?: string);
+}
+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;
+}
+/** Run `fn` with an abort scope that `beginChanges()` will observe. */
+export declare const runInAbortScope: <T>(scope: AbortScope, fn: () => T) => T;
+/** The current scope, if the caller is running inside one. */
+export declare const getAbortScope: () => AbortScope | undefined;
+/**
+ * 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 declare const beginChanges: () => Promise<void>;

package/dist/function/abort-scope.js

@@ -0,0 +1,63 @@
+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) {
+        super(reason
+            ? `Aborted before making changes: ${reason}`
+            : 'Aborted before making changes');
+        this.name = 'AbandonedError';
+    }
+}
+/**
+ * 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();
+/** Run `fn` with an abort scope that `beginChanges()` will observe. */
+export const runInAbortScope = (scope, fn) => scopeStorage.run(scope, fn);
+/** The current scope, if the caller is running inside one. */
+export const getAbortScope = () => 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 () => {
+    const scope = scopeStorage.getStore();
+    if (!scope)
+        return;
+    if (scope.abandoned) {
+        throw new AbandonedError(scope.reason);
+    }
+    scope.onBeginChanges?.();
+};