@pikku/core 0.12.71 → 0.12.74

package/dist/services/http-personas.js

@@ -0,0 +1,233 @@
+import { readScenarioHttpResponse } from './personas-service.js';
+import { runConversation } from '../wirings/actor-flow/run-conversation.js';
+import { createCookieJar, } from '../wirings/workflow/scenario-cookie-jar.js';
+import { getSingletonServices } from '../pikku-state.js';
+import { AIProviderNotConfiguredError } from '../errors/errors.js';
+/**
+ * Default HTTP-backed persona. Signs in lazily on first invoke via the Better
+ * Auth actor plugin (`POST /auth/sign-in/actor` with `{ email, secret }` —
+ * the plugin upserts the actor-flagged user row and mints a session whose
+ * `actor` flag flows into audits/analytics). Holds the session cookies for
+ * its lifetime; a 401 mid-run re-logs-in once (long health-check runs can
+ * outlive a session).
+ */
+export class HttpPersona {
+    name;
+    persona;
+    config;
+    jar;
+    /**
+     * Whether `login()` has succeeded since the last time the session was
+     * dropped. The jar cannot answer this — a target may set a cookie before
+     * anyone signs in, and it would then look like a session that was never
+     * established.
+     */
+    signedIn = false;
+    constructor(name, persona, config) {
+        this.name = name;
+        this.persona = persona;
+        this.config = config;
+        this.jar = createCookieJar(config.apiUrl);
+    }
+    get email() {
+        return this.persona.email;
+    }
+    async invoke(rpcName, data) {
+        const res = await this.invokeRaw(rpcName, data);
+        if (!res.ok) {
+            throw new Error(`[scenario] '${rpcName}' as '${this.name}' returned ${res.status}: ${res.serialized.slice(0, 300)}`);
+        }
+        return res.body;
+    }
+    async invokeRaw(rpcName, data, options) {
+        if (!this.signedIn) {
+            await this.login();
+        }
+        let res = await this.postRpc(rpcName, data, options?.headers);
+        if (res.status === 401) {
+            // Session expired mid-run — re-login once and retry.
+            this.signOut();
+            await this.login();
+            res = await this.postRpc(rpcName, data, options?.headers);
+        }
+        return readScenarioHttpResponse(res);
+    }
+    async converse(options) {
+        const { aiAgentRunner } = getSingletonServices();
+        if (!aiAgentRunner) {
+            throw new AIProviderNotConfiguredError();
+        }
+        const model = options.model ?? this.config.model;
+        if (!model) {
+            throw new Error(`[scenario] persona '${this.name}' converse needs a model — pass options.model or set 'model' on the personas service`);
+        }
+        const threadId = globalThis.crypto.randomUUID();
+        const resourceId = `persona:${this.name}`;
+        return runConversation({
+            persona: this.persona,
+            personaId: this.name,
+            agentName: options.agent,
+            task: options.task,
+            evaluate: options.evaluate,
+            approvals: options.approvals,
+            model,
+            maxTurns: options.maxTurns,
+            llm: (params) => aiAgentRunner.run(params),
+            target: {
+                run: (message) => this.agentRun(options.agent, message, threadId, resourceId),
+                approve: (runId, decisions) => this.agentApprove(options.agent, runId, decisions),
+            },
+        });
+    }
+    /**
+     * The roles the stage says this session holds.
+     *
+     * Read from better-auth's `get-session`, which is what most pikku apps are
+     * running and where its admin plugin puts `role` — on the user, as a
+     * comma-separated list. A target that answers something else returns `null`
+     * rather than an empty list, because "this stage does not report roles" and
+     * "this person has none" call for opposite responses from the caller.
+     */
+    async sessionRoles() {
+        if (!this.signedIn) {
+            await this.login();
+        }
+        const sessionPath = this.config.sessionPath ?? '/auth/get-session';
+        const res = await this.jar.fetch(`${this.config.apiUrl}${sessionPath}`);
+        if (!res.ok) {
+            return null;
+        }
+        const text = await res.text().catch(() => '');
+        if (!text) {
+            return null;
+        }
+        let payload;
+        try {
+            payload = JSON.parse(text);
+        }
+        catch {
+            return null;
+        }
+        const user = payload?.user;
+        const role = user?.role;
+        if (typeof role === 'string') {
+            return role
+                .split(',')
+                .map((name) => name.trim())
+                .filter(Boolean);
+        }
+        if (Array.isArray(role)) {
+            return role.filter((name) => typeof name === 'string');
+        }
+        // The session came back and carried a user, but no role field — that is a
+        // stage reporting "none", not a stage that cannot report.
+        return user ? [] : null;
+    }
+    /** Start/continue the target agent's run over HTTP as this persona. */
+    async agentRun(agentName, message, threadId, resourceId) {
+        const raw = await this.postAgent(`agent/${agentName}`, {
+            message,
+            threadId,
+            resourceId,
+        });
+        return normalizeAgentReply(raw);
+    }
+    /** Answer the target agent's pending approvals over HTTP and continue. */
+    async agentApprove(agentName, runId, decisions) {
+        const raw = await this.postAgent(`agent/${agentName}/approve`, {
+            runId,
+            approvals: decisions,
+        });
+        return normalizeAgentReply(raw);
+    }
+    // knowledge: decisions/internals/scenario-agent-calls-sign-in-on-401-only.md
+    async postAgent(subPath, body) {
+        const rpcPath = this.config.rpcPath ?? '/rpc';
+        const url = `${this.config.apiUrl}${rpcPath}/${subPath}`;
+        const send = () => this.jar.fetch(url, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify(body),
+        });
+        let res = await send();
+        if (res.status === 401) {
+            this.signOut();
+            await this.login();
+            res = await send();
+        }
+        if (!res.ok) {
+            const text = (await res.text().catch(() => '')).slice(0, 300);
+            throw new Error(`[scenario] agent call '${subPath}' as '${this.name}' returned ${res.status}: ${text}`);
+        }
+        if (res.status === 204)
+            return undefined;
+        const text = await res.text();
+        return text ? JSON.parse(text) : undefined;
+    }
+    async postRpc(rpcName, data, extraHeaders) {
+        const rpcPath = this.config.rpcPath ?? '/rpc';
+        return this.jar.fetch(`${this.config.apiUrl}${rpcPath}/${rpcName}`, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json', ...extraHeaders },
+            body: JSON.stringify({ data }),
+        });
+    }
+    /** Drop the session, so the next call signs in again before it goes out. */
+    signOut() {
+        this.jar.clear();
+        this.signedIn = false;
+    }
+    async login() {
+        const signInPath = this.config.signInPath ?? '/auth/sign-in/actor';
+        const res = await this.jar.fetch(`${this.config.apiUrl}${signInPath}`, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify({
+                email: this.persona.email,
+                name: this.persona.name,
+                secret: this.config.secret,
+            }),
+        });
+        if (!res.ok) {
+            const body = (await res.text().catch(() => '')).slice(0, 300);
+            throw new Error(`[scenario] persona sign-in failed for '${this.name}' (${res.status}): ${body}`);
+        }
+        // What proves a session was established is this response setting a cookie,
+        // not the jar being non-empty — the target may have set one earlier.
+        if (res.headers.getSetCookie().length === 0) {
+            throw new Error(`[scenario] persona sign-in for '${this.name}' returned no session cookie`);
+        }
+        this.signedIn = true;
+    }
+}
+/** Normalize an agentRun/agentApprove HTTP response into a TargetAgentReply. */
+function normalizeAgentReply(raw) {
+    const r = (raw ?? {});
+    const pending = Array.isArray(r.pendingApprovals)
+        ? r.pendingApprovals.map((p) => ({
+            toolCallId: String(p.toolCallId),
+            toolName: String(p.toolName),
+            args: p.args,
+            reason: typeof p.reason === 'string' ? p.reason : undefined,
+        }))
+        : undefined;
+    return {
+        text: typeof r.text === 'string' ? r.text : '',
+        runId: typeof r.runId === 'string' ? r.runId : '',
+        status: r.status === 'completed' || r.status === 'suspended'
+            ? r.status
+            : undefined,
+        pendingApprovals: pending,
+    };
+}
+/**
+ * Build the injected `personas` service from the declared personas: id → lazy
+ * HTTP persona. Wire the result as the `personas` singleton service.
+ */
+export function createHttpPersonas(config) {
+    const personas = {};
+    for (const [id, persona] of Object.entries(config.personas)) {
+        personas[id] = new HttpPersona(id, persona, config);
+    }
+    return personas;
+}

package/dist/services/in-memory-queue-service.d.ts

@@ -1,22 +1,8 @@
 import type { QueueService, JobOptions } from '../wirings/queue/queue.types.js';
-/**
- * In-process queue for local/dev runs. Schedules jobs on the macrotask queue
- * (setTimeout) so dispatch is genuinely asynchronous — the same timing shape as
- * a real queue — and redelivers a failed job up to `options.attempts` times with
- * backoff, so a transiently-failing workflow step recovers exactly as it would
- * on pg-boss/bullmq instead of being silently dropped on its first error.
- *
- * Payloads are JSON round-tripped on the way in, because every real backend
- * puts the job on a wire (SQS body, Redis value, jsonb column) and the worker
- * therefore never sees the caller's live object. Doing it here keeps dev
- * behaviour honest, and keeps the callers — who cannot know which backend they
- * are talking to — from having to serialise defensively.
- */
 export declare class InMemoryQueueService implements QueueService {
     readonly supportsResults = false;
     private jobCounter;
     add<T>(queueName: string, data: T, options?: JobOptions): Promise<string>;
-    /** Delay before the next redelivery, honoring the job's backoff policy. */
     private backoffDelay;
     getJob(): Promise<null>;
 }

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

@@ -1,17 +1,5 @@
 import { runQueueJob } from '../wirings/queue/queue-runner.js';
-/**
- * In-process queue for local/dev runs. Schedules jobs on the macrotask queue
- * (setTimeout) so dispatch is genuinely asynchronous — the same timing shape as
- * a real queue — and redelivers a failed job up to `options.attempts` times with
- * backoff, so a transiently-failing workflow step recovers exactly as it would
- * on pg-boss/bullmq instead of being silently dropped on its first error.
- *
- * Payloads are JSON round-tripped on the way in, because every real backend
- * puts the job on a wire (SQS body, Redis value, jsonb column) and the worker
- * therefore never sees the caller's live object. Doing it here keeps dev
- * behaviour honest, and keeps the callers — who cannot know which backend they
- * are talking to — from having to serialise defensively.
- */
+// knowledge: decisions/internals/the-dev-queue-copies-prod-timing-and-serialization-semantics.md
 export class InMemoryQueueService {
     supportsResults = false;
     jobCounter = 0;
@@ -36,7 +24,6 @@ export class InMemoryQueueService {
             }
             catch (e) {
                 if (attemptsMade < maxAttempts) {
-                    // Transient failure — redeliver with backoff, mirroring a real queue.
                     setTimeout(runAttempt, this.backoffDelay(options?.backoff, attemptsMade));
                 }
                 else {
@@ -48,7 +35,6 @@ export class InMemoryQueueService {
         setTimeout(runAttempt, delay);
         return jobId;
     }
-    /** Delay before the next redelivery, honoring the job's backoff policy. */
     backoffDelay(backoff, attemptsMade) {
         const baseDelay = typeof backoff === 'object' ? (backoff.delay ?? 50) : 50;
         if (backoff === 'exponential' ||

package/dist/services/in-memory-trigger-service.d.ts

@@ -1,22 +1,4 @@
 import { PikkuTriggerService } from '../wirings/trigger/pikku-trigger-service.js';
-/**
- * In-memory TriggerService implementation.
- *
- * Reads both `wireTrigger` declarations and `wireTriggerSource` registrations
- * from pikkuState. Only starts triggers that have both a declaration and a source.
- * On fire, invokes target via `ContextAwareRPCService`.
- *
- * Single owner — one process runs triggers, no distributed claiming.
- *
- * @example
- * ```typescript
- * const triggerService = new InMemoryTriggerService()
- * await triggerService.start()
- *
- * // On shutdown
- * await triggerService.stop()
- * ```
- */
 export declare class InMemoryTriggerService extends PikkuTriggerService {
     start(): Promise<void>;
 }

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

@@ -1,23 +1,6 @@
 import { PikkuTriggerService } from '../wirings/trigger/pikku-trigger-service.js';
 import { getSingletonServices } from '../pikku-state.js';
-/**
- * In-memory TriggerService implementation.
- *
- * Reads both `wireTrigger` declarations and `wireTriggerSource` registrations
- * from pikkuState. Only starts triggers that have both a declaration and a source.
- * On fire, invokes target via `ContextAwareRPCService`.
- *
- * Single owner — one process runs triggers, no distributed claiming.
- *
- * @example
- * ```typescript
- * const triggerService = new InMemoryTriggerService()
- * await triggerService.start()
- *
- * // On shutdown
- * await triggerService.stop()
- * ```
- */
+// knowledge: decisions/internals/local-trigger-and-gateway-services-assume-a-single-process.md
 export class InMemoryTriggerService extends PikkuTriggerService {
     async start() {
         const singletonServices = getSingletonServices();

package/dist/services/in-memory-workflow-service.d.ts

@@ -1,21 +1,6 @@
 import { PikkuWorkflowService } from '../wirings/workflow/pikku-workflow-service.js';
 import type { SerializedError } from '../types/core.types.js';
 import type { WorkflowPlannedStep, WorkflowQueueOptions, WorkflowRun, WorkflowRunService, WorkflowRunWire, StepState, StepStatus, WorkflowStatus, WorkflowVersionStatus, WorkflowStepOptions } from '../wirings/workflow/workflow.types.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 declare class InMemoryWorkflowService extends PikkuWorkflowService implements WorkflowRunService {
     constructor(options?: WorkflowQueueOptions);
     private sleepTimers;
@@ -65,7 +50,6 @@ export declare class InMemoryWorkflowService extends PikkuWorkflowService implem
         failedNodeIds: string[];
         branchKeys: Record<string, string>;
     }>;
-    getNodesWithoutSteps(runId: string, nodeIds: string[]): Promise<string[]>;
     protected listStepStates(runId: string): Promise<Array<StepState & {
         stepName: string;
     }>>;

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

@@ -1,21 +1,7 @@
 import { randomUUID } from 'crypto';
 import { PikkuWorkflowService } from '../wirings/workflow/pikku-workflow-service.js';
 import { isExpectedError } from '../errors/error-handler.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 })
- * ```
- */
+// knowledge: decisions/internals/the-in-memory-workflow-service-is-inline-only-and-single-process.md
 export class InMemoryWorkflowService extends PikkuWorkflowService {
     constructor(options = {}) {
         super({ ...options, wireQueues: false });
@@ -99,7 +85,7 @@ export class InMemoryWorkflowService extends PikkuWorkflowService {
         const key = `${runId}:${stepName}`;
         this.steps.set(key, step);
         this.stepData.set(stepId, { rpcName, data, stepName });
-        // Add to history (same reference so mutations are reflected)
+        // knowledge: decisions/internals/in-memory-workflow-history-aliases-the-live-step-object.md
         const history = this.stepHistory.get(runId) || [];
         history.push(step);
         this.stepHistory.set(runId, history);
@@ -170,7 +156,6 @@ export class InMemoryWorkflowService extends PikkuWorkflowService {
         }
     }
     async createRetryAttemptImpl(failedStepId, status) {
-        // Find the failed step
         let failedStep;
         let runId;
         let stepName;
@@ -205,11 +190,10 @@ export class InMemoryWorkflowService extends PikkuWorkflowService {
         }
         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 (same reference so mutations are reflected)
+        // knowledge: decisions/internals/in-memory-workflow-history-aliases-the-live-step-object.md
         const history = this.stepHistory.get(runId) || [];
         history.push(newStep);
         this.stepHistory.set(runId, history);
@@ -265,11 +249,10 @@ export class InMemoryWorkflowService extends PikkuWorkflowService {
         return existed;
     }
     async withRunLock(_id, fn) {
-        // In-memory service doesn't need locking for inline execution
+        // knowledge: decisions/internals/the-in-memory-workflow-service-is-inline-only-and-single-process.md
         return fn();
     }
     async withStepLock(_runId, _stepName, fn) {
-        // In-memory service doesn't need locking for inline execution
         return fn();
     }
     async close() {
@@ -277,7 +260,6 @@ export class InMemoryWorkflowService extends PikkuWorkflowService {
             clearTimeout(timer);
         }
         this.sleepTimers.clear();
-        // Clear all in-memory state
         this.runs.clear();
         this.steps.clear();
         this.stepData.clear();
@@ -286,7 +268,6 @@ export class InMemoryWorkflowService extends PikkuWorkflowService {
         this.branchKeys.clear();
         this.workflowVersions.clear();
     }
-    // Graph workflow methods
     async getCompletedGraphState(runId) {
         const completedNodeIds = [];
         const failedNodeIds = [];
@@ -314,16 +295,6 @@ export class InMemoryWorkflowService extends PikkuWorkflowService {
         }
         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 listStepStates(runId) {
         const prefix = `${runId}:`;
         const steps = [];

package/dist/services/index.d.ts

@@ -1,6 +1,3 @@
-/**
- * @module @pikku/core
- */
 export { LogLevel } from './logger.js';
 export { ScopedSecretService } from './scoped-secret-service.js';
 export { PikkuSessionService, createMiddlewareSessionWireProps, createFunctionSessionWireProps, } from './user-session-service.js';
@@ -19,9 +16,8 @@ export { InMemoryTriggerService } from './in-memory-trigger-service.js';
 export { InMemoryAIRunStateService } from './in-memory-ai-run-state-service.js';
 export { LocalGatewayService } from './local-gateway-service.js';
 export type { ContentService, SignContentKeyArgs, SignURLArgs, GetUploadURLArgs, UploadURLResult, BucketKeyArgs, WriteFileArgs, CopyFileArgs, } from './content-service.js';
-export type { ScenarioActor, ScenarioActorConfig, ScenarioActorOf, ScenarioActors, ScenarioInvokeOptions, ScenarioRpcMap, ScenarioHttpResponse, } from './scenario-actors-service.js';
-export { readScenarioHttpResponse } from './scenario-actors-service.js';
-export { HttpScenarioActor, createHttpScenarioActors, type HttpScenarioActorsConfig, } from './http-scenario-actors.js';
+export type { ScenarioPersona, ResolvedPersona, ScenarioPersonaOf, ScenarioPersonas, ScenarioInvokeOptions, ScenarioRpcMap, ScenarioHttpResponse, } from './personas-service.js';
+export type { HttpPersonasConfig } from './http-personas.js';
 export type { JWTService } from './jwt-service.js';
 export type { EmailService, EmailTemplateReference, SendEmailInput, SendEmailResult, SendHTMLEmailInput, SendTemplateEmailInput, SendTextEmailInput, } from './email-service.js';
 export { DEFAULT_WEBHOOK_RETRIES, DEFAULT_WEBHOOK_SIGNATURE_HEADER, PIKKU_OUTGOING_WEBHOOK_QUEUE_NAME, WebhookService, type SendWebhookInput, type SendWebhookResult, type WebhookAttemptRecord, type WebhookAttemptResult, type WebhookDeliveryRecord, type WebhookDeliveryWithAttempts, type WebhookJobData, type WebhookServiceConfig, } from './webhook-service.js';
@@ -46,9 +42,12 @@ export type { VariableStatus, VariableMeta } from './typed-variables-service.js'
 export type { MetaService } from './meta-service.js';
 export type { SessionStore } from './session-store.js';
 export type { ScopeService, Role } from './scope-service.js';
+export { assertRoleIsMutable, assertRoleNameAvailable, roleLockReason, } from './system-role-guard.js';
+export type { IsSystemRole } from './system-role-guard.js';
 export { NoopAuditService, createInvocationAudit, resolveAuditActorFromWire, resolveAuditConfig, } from './audit-service.js';
 export type { AuditActor, AuditConfig, AuditDurability, AuditEvent, AuditEventBatch, AuditLog, AuditLogWriteInput, AuditOutcome, AuditService, AuditSource, ResolvedAuditConfig, } from './audit-service.js';
 export { InMemorySessionStore } from './in-memory-session-store.js';
 export type { MCPMeta, RPCMetaRecord, ServiceMeta, ServicesMetaRecord, MiddlewareDefinitionMeta, MiddlewareInstanceMeta, GroupMeta, MiddlewareGroupsMeta, PermissionDefinitionMeta, PermissionsGroupsMeta, FunctionsMeta, FunctionMeta, MiddlewareMeta, PermissionMeta, AgentsMeta, AgentMeta, EmailsMeta, EmailTemplateMeta, EmailTemplateLocaleMeta, EmailTemplateAssets, } from './meta-service.js';
 export type { CoverageService, CoverageSnapshot, LineHits, ScriptCoverage, FunctionCoverage, CoverageRange, CoverageStatus, FunctionCoverageEntry, FunctionCoverageReport, CoverageFunctionMeta, } from './v8-coverage-service.js';
 export { StubTracker, createStubProxy, getStubTracker, isTestRun, stub, spy, type StubCall, } from './stub-tracker.js';
+export { SecretHostNotAllowedError, assertSecretAllowedForHost, } from './secret-host-binding.js';

package/dist/services/index.js

@@ -1,6 +1,3 @@
-/**
- * @module @pikku/core
- */
 export { LogLevel } from './logger.js';
 export { ScopedSecretService } from './scoped-secret-service.js';
 export { PikkuSessionService, createMiddlewareSessionWireProps, createFunctionSessionWireProps, } from './user-session-service.js';
@@ -18,10 +15,10 @@ export { InMemoryQueueService } from './in-memory-queue-service.js';
 export { InMemoryTriggerService } from './in-memory-trigger-service.js';
 export { InMemoryAIRunStateService } from './in-memory-ai-run-state-service.js';
 export { LocalGatewayService } from './local-gateway-service.js';
-export { readScenarioHttpResponse } from './scenario-actors-service.js';
-export { HttpScenarioActor, createHttpScenarioActors, } from './http-scenario-actors.js';
 export { DEFAULT_WEBHOOK_RETRIES, DEFAULT_WEBHOOK_SIGNATURE_HEADER, PIKKU_OUTGOING_WEBHOOK_QUEUE_NAME, WebhookService, } from './webhook-service.js';
 export { TypedCredentialService } from './typed-credential-service.js';
+export { assertRoleIsMutable, assertRoleNameAvailable, roleLockReason, } from './system-role-guard.js';
 export { NoopAuditService, createInvocationAudit, resolveAuditActorFromWire, resolveAuditConfig, } from './audit-service.js';
 export { InMemorySessionStore } from './in-memory-session-store.js';
 export { StubTracker, createStubProxy, getStubTracker, isTestRun, stub, spy, } from './stub-tracker.js';
+export { SecretHostNotAllowedError, assertSecretAllowedForHost, } from './secret-host-binding.js';

package/dist/services/istanbul-coverage-service.d.ts

@@ -1,9 +1,5 @@
 import type { CoverageService, CoverageSnapshot } from './v8-coverage-service.js';
-/**
- * Reads istanbul-instrumented counters from the `__coverage__` global —
- * the coverage backend for runtimes without V8 precise coverage (e.g. Bun,
- * where source files are instrumented at load time by a Bun loader plugin).
- */
+/** The coverage backend for runtimes without V8 precise coverage, e.g. Bun. */
 export declare class IstanbulCoverageService implements CoverageService {
     start(): Promise<void>;
     takeCoverage(): Promise<CoverageSnapshot>;

package/dist/services/istanbul-coverage-service.js

@@ -1,9 +1,5 @@
 const getCoverageGlobal = () => globalThis.__coverage__;
-/**
- * Reads istanbul-instrumented counters from the `__coverage__` global —
- * the coverage backend for runtimes without V8 precise coverage (e.g. Bun,
- * where source files are instrumented at load time by a Bun loader plugin).
- */
+/** The coverage backend for runtimes without V8 precise coverage, e.g. Bun. */
 export class IstanbulCoverageService {
     async start() { }
     async takeCoverage() {
@@ -15,9 +11,7 @@ export class IstanbulCoverageService {
                 hits = new Map();
                 lineHits.set(file.path, hits);
             }
-            // istanbul line semantics: a statement's count belongs to its start
-            // line only, so an enclosing multi-line statement never masks an
-            // unexecuted inner statement (e.g. a throw inside a taken if).
+            // knowledge: decisions/internals/istanbul-statement-counts-attach-to-the-start-line-only.md
             for (const [id, location] of Object.entries(file.statementMap)) {
                 const count = file.s[id] ?? 0;
                 const line = location.start.line;

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

@@ -1,21 +1,6 @@
 import type { RelativeTimeInput } from '../time-utils.js';
-/**
- * Interface for handling JSON Web Tokens (JWT).
- */
 export interface JWTService {
-    /**
-     * Encodes a payload into a JWT.
-     * @param expiresIn - The expiration time of the token.
-     * @param payload - The payload to encode.
-     * @returns A promise that resolves to the encoded JWT.
-     */
     encode: <T extends any>(expiresIn: RelativeTimeInput, payload: T) => Promise<string>;
-    /**
-     * Decodes a JWT into its payload.
-     * @param hash - The JWT to decode.
-     * @param invalidHashError - An optional error to throw if the hash is invalid.
-     * @param debug - An optional flag for debugging.
-     * @returns A promise that resolves to the decoded payload.
-     */
+    /** `invalidHashError` replaces the implementation's own error when the hash does not verify. */
     decode: <T>(hash: string, invalidHashError?: Error, debug?: boolean) => Promise<T>;
 }

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

@@ -6,11 +6,22 @@ export interface LocalContentConfig {
     server?: string;
     sizeLimit?: string;
 }
+/**
+ * The representation of an asset that gets bound into a signed URL's
+ * signature, and that a server can reconstruct from an incoming request:
+ * the decoded path, without origin or query string.
+ *
+ * Both sides must derive it the same way, so signer and verifier share this
+ * function. Percent escapes are decoded so that a client re-encoding an
+ * optional character still matches; a malformed escape is left verbatim
+ * rather than throwing, which keeps both sides in agreement.
+ */
+export declare const signedContentPath: (urlOrPath: string) => string;
 export declare class LocalContent implements ContentService {
     private config;
     private logger;
-    private jwt?;
-    constructor(config: LocalContentConfig, logger: Logger, jwt?: JWTService | undefined);
+    private jwt;
+    constructor(config: LocalContentConfig, logger: Logger, jwt: JWTService);
     private safePath;
     private joinKey;
     init(): Promise<void>;