@north-light/api 0.3.580 → 0.3.587

package/dist/daemon/api/handlers/validate.d.ts

@@ -0,0 +1,23 @@
+import { isRecord } from '../../../shared/predicates.js';
+import type { RequestContext } from '../router.js';
+export { isRecord };
+export type Violation = {
+    field: string;
+    problem: string;
+    received?: unknown;
+};
+/** Reject the request with every violation collected so far. `subject` names
+ *  what was being parsed, e.g. "review comment request". */
+export declare function invalidRequest(subject: string, violations: Violation[]): never;
+/** Narrow a request body to an object and reject any field outside `allowed`.
+ *  A non-object body yields `{}` so the caller's field reads all miss and
+ *  report their own violations rather than throwing. */
+export declare function objectBody(body: unknown, allowed: readonly string[], violations: Violation[]): Record<string, unknown>;
+/** A required field that must be a string carrying at least one non-whitespace
+ *  character — whitespace alone is not a value. */
+export declare function requiredString(body: Record<string, unknown>, field: string, violations: Violation[]): string | undefined;
+/** `requiredString`'s rule when present; absence is allowed. */
+export declare function optionalString(body: Record<string, unknown>, field: string, violations: Violation[]): string | undefined;
+/** A path parameter that must be present and satisfy `accepts`. `problem`
+ *  describes the shape the caller failed to supply. */
+export declare function requireParam(ctx: RequestContext, field: string, problem: string, accepts: (value: string) => boolean, violations: Violation[]): string | undefined;

package/dist/daemon/api/handlers/validate.js

@@ -0,0 +1,58 @@
+// Shared wire-request validation for the daemon's `/v1` handlers.
+//
+// A handler collects `Violation`s while parsing a request, then calls
+// `invalidRequest` once so a caller sees every problem with its body in a
+// single 400 rather than one per round trip.
+import { ApiError } from '../../../api/index.js';
+import { isRecord } from '../../../shared/predicates.js';
+export { isRecord };
+/** Reject the request with every violation collected so far. `subject` names
+ *  what was being parsed, e.g. "review comment request". */
+export function invalidRequest(subject, violations) {
+    throw new ApiError(400, 'invalid_request', `${subject} is invalid`, { violations });
+}
+/** Narrow a request body to an object and reject any field outside `allowed`.
+ *  A non-object body yields `{}` so the caller's field reads all miss and
+ *  report their own violations rather than throwing. */
+export function objectBody(body, allowed, violations) {
+    if (!isRecord(body)) {
+        violations.push({ field: 'body', problem: 'must be an object', received: body });
+        return {};
+    }
+    for (const key of Object.keys(body)) {
+        if (!allowed.includes(key))
+            violations.push({ field: key, problem: 'is not allowed', received: body[key] });
+    }
+    return body;
+}
+/** A required field that must be a string carrying at least one non-whitespace
+ *  character — whitespace alone is not a value. */
+export function requiredString(body, field, violations) {
+    const value = body[field];
+    if (typeof value !== 'string' || value.trim() === '') {
+        violations.push({ field, problem: 'must be a non-empty string', ...(value === undefined ? {} : { received: value }) });
+        return undefined;
+    }
+    return value;
+}
+/** `requiredString`'s rule when present; absence is allowed. */
+export function optionalString(body, field, violations) {
+    const value = body[field];
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== 'string' || value.trim() === '') {
+        violations.push({ field, problem: 'must be a non-empty string', received: value });
+        return undefined;
+    }
+    return value;
+}
+/** A path parameter that must be present and satisfy `accepts`. `problem`
+ *  describes the shape the caller failed to supply. */
+export function requireParam(ctx, field, problem, accepts, violations) {
+    const value = ctx.params[field];
+    if (value === undefined || !accepts(value)) {
+        violations.push({ field, problem, ...(value === undefined ? {} : { received: value }) });
+        return undefined;
+    }
+    return value;
+}

package/dist/daemon/api/map.d.ts

@@ -0,0 +1,167 @@
+import type { ManagedWorktree, NodeMeta, NodeRow, NodeRuntime, SubscriptionRef } from '../../core/canvas/types.js';
+import type { ReviewComment, ReviewCommentEvent, ReviewErrorCode, ReviewRecord, ReviewResult } from '../../core/review/types.js';
+import { type Cron, type CronRunRecord } from '../../core/canvas/crons.js';
+import type { ProfileEntry } from '../../core/profiles/manifest.js';
+import type { ReviveResult } from '../../core/runtime/revive.js';
+import type { CloseNodeResult } from '../../core/runtime/close.js';
+import { type PushResult } from '../../core/feed/feed.js';
+import type { PageFeedback, PageFeedbackComment } from '../../core/human/feedback.js';
+import type { CanvasImportResult } from '../../migrations/activation.js';
+import type { CloseResultDTO, CronDTO, CronRunDTO, ErrorBody, NodeEdgesDTO, NodeOutcomeDTO, RunOutcomeDTO, NodeOutcomeSummaryDTO, NodePathsDTO, NodeStatusDTO, OutcomeDeliveryDTO, NodeSummaryDTO, NodeDetailDTO, NodeWorktreeDTO, ProfileDTO, ReviewCommentDTO, ReviewCommentEventDTO, ReviewDTO, FeedbackResultDTO, GraphNodeDTO, PageFeedbackCommentDTO, PageFeedbackDTO, PushReportResultDTO, ReviveResultDTO, MigrateStateDTO, SubscriptionDTO } from '../../api/index.js';
+export declare function toMigrateStateDTO(result: CanvasImportResult, options: {
+    resumed: boolean;
+    resumeError?: string;
+}): MigrateStateDTO;
+/** Project the list-row outcome, or null while this node remains unsettled. */
+export declare function toNodeOutcomeSummaryDTO(node: NodeRuntime): NodeOutcomeSummaryDTO | null;
+/** Project the full outcome, or null while this node remains unsettled. */
+export declare function toNodeOutcomeDTO(node: Pick<NodeMeta, 'node_id' | 'final_report'> & NodeRuntime): Promise<NodeOutcomeDTO | null>;
+export declare function toRunOutcomeDTO(node: Pick<NodeMeta, 'node_id' | 'final_report'> & NodeRuntime): Promise<RunOutcomeDTO | null>;
+/** The outcome-delivery fields exposed by the API. The delivery store supplies this projection directly. */
+export interface OutcomeDeliveryDTOInput {
+    nodeId: string;
+    state: 'armed' | 'pending' | 'running' | 'accepted' | 'permanent_failed';
+    actionName: string;
+    attempt: number;
+    nextAttemptAt: number;
+    acceptedAt: number | null;
+    permanentFailedAt: number | null;
+    lastFailure: {
+        kind: 'exit' | 'signal' | 'timeout' | 'spawn_error' | 'grant_refused';
+        exitCode?: number;
+        signal?: string;
+        message?: string;
+    } | null;
+    createdAt: number;
+    updatedAt: number;
+}
+/** Project a durable delivery row without exposing its execution coordinates or stderr tail. */
+export declare function toOutcomeDeliveryDTO(row: OutcomeDeliveryDTOInput): OutcomeDeliveryDTO;
+/** Project the queryable row (what `listNodes` yields) into a summary DTO. */
+export declare function toGraphNodeDTO(row: {
+    node_id: string;
+    name: string;
+    description: string | null;
+    cycles: number | null;
+    kind: string;
+    status: NodeStatusDTO;
+    frozen_at: string | null;
+    pi_pid: number | null;
+    telemetry_context_tokens: number | null;
+    telemetry_last_activity: string | null;
+    fault: NodeRow['fault'];
+    streaming: boolean;
+}): GraphNodeDTO;
+export declare function toNodeSummaryDTO(row: NodeRow, paused?: boolean): Promise<NodeSummaryDTO>;
+/** The subscription/child edges a detail projection needs. The handler gathers
+ *  these from `subscriptionsOf`/`subscribersOf` + a children query and passes
+ *  them in, so this module stays a pure projection with no db reach. */
+export interface NodeEdgesInput {
+    /** Publishers this node subscribes to (`subscriptionsOf(id)`). */
+    subscribesTo: readonly SubscriptionRef[];
+    /** Subscribers to this node's output — its managers (`subscribersOf(id)`). */
+    subscribers: readonly SubscriptionRef[];
+    /** Node ids this node spawned (children). */
+    children: readonly string[];
+}
+/** Project a node's spine + subscription edges (absorbs `managers`/`paths`). */
+export declare function toNodeEdgesDTO(meta: NodeMeta, edges: NodeEdgesInput): NodeEdgesDTO;
+/** Absolute filesystem paths for a node (absorbs the `paths` read).
+ *  App assignment comes from the authoritative node row. */
+export declare function toNodePathsDTO(nodeId: string, grantee: string): Promise<NodePathsDTO>;
+/** Project a node's managed git worktree, if any. */
+export declare function toNodeWorktreeDTO(w: ManagedWorktree): NodeWorktreeDTO;
+/** Project the hydrated node view (`getNode` → `NodeMeta`) into a detail DTO.
+ *  The summary fields come from the meta's runtime half (hydrated from the
+ *  authoritative row); the identity extras (description/cycles/session) come
+ *  from the meta's identity half. Edges are gathered by the handler. */
+export declare function toNodeDetailDTO(meta: NodeMeta, edges: NodeEdgesInput): Promise<NodeDetailDTO>;
+/** Project a `reviveNode` result. `revived` is true only when a fresh launch
+ *  actually happened — the double-revive no-op (already-alive) returns without a
+ *  `launch` handle, so its absence is the "nothing relaunched" signal. `status`
+ *  is the caller's post-revive row read. */
+export declare function toReviveResultDTO(nodeId: string, result: ReviveResult, status: NodeStatusDTO, ready: boolean): ReviveResultDTO;
+/** Project a `closeNode` cascade result. Field names align 1:1. */
+export declare function toCloseResultDTO(result: CloseNodeResult): CloseResultDTO;
+/** Project a feed `push` result into a push-report result. `transitioned` is
+ *  supplied by the handler only for a `final` push (the server-side lifecycle
+ *  flip); an update/urgent push omits it. */
+export declare function toReportResultDTO(result: PushResult, transitioned?: {
+    from: string;
+    to: string;
+}, autoDroppedWorktreePath?: string): PushReportResultDTO;
+/** Project a subscription ref as seen from one endpoint. */
+export declare function toSubscriptionDTO(ref: SubscriptionRef): SubscriptionDTO;
+/** Project a cron row into its DTO — a straight column projection minus the
+ *  internal lease plumbing (run_pid/run_lease_owner/env_json/last_output_hash/
+ *  queued stay server-side); the sink JSON is rendered back to its display
+ *  spec. `lastRun` is the most recent settled run — the recent health every
+ *  cron projection carries so `cron list` needs no `cron show` per row. */
+export declare function toCronDTO(c: Cron, lastRun?: CronRunRecord | null): CronDTO;
+/** Project one settled run-log record into its DTO — a straight projection
+ *  minus the redundant cron_id (the route already names the cron). */
+export declare function toCronRunDTO(r: CronRunRecord): CronRunDTO;
+/** Project a profile-manifest entry into its DTO. `default_dir` (the directory
+ *  this profile is pinned as default for) is a reverse lookup not carried on the
+ *  entry, so it is left null here — a caller that needs it resolves it
+ *  separately. Project entries are cloned: the manifest entry is shared cache
+ *  state, so handing out its objects would let a DTO consumer mutate it. */
+export declare function toProfileDTO(entry: ProfileEntry): ProfileDTO;
+/** Extra daemon-derived review fields whose source is outside the canonical row. */
+export interface ReviewDTOExtras {
+    /** Deterministic destination of an approved review's immutable result. */
+    result_path?: string;
+}
+/** Project the canonical review row without exposing fork/session/store coordinates. */
+export declare function toReviewDTO(row: ReviewRecord, extras?: ReviewDTOExtras): ReviewDTO;
+/** Project one daemon-owned comment, omitting absent node identities on human actions. */
+export declare function toReviewCommentDTO(comment: ReviewComment): ReviewCommentDTO;
+/** Project one ticket-attached page feedback comment. */
+export declare function toPageFeedbackCommentDTO(comment: PageFeedbackComment): PageFeedbackCommentDTO;
+/** Project one ticket's page feedback state. */
+export declare function toPageFeedbackDTO(feedback: PageFeedback): PageFeedbackDTO;
+/** Project one immutable review-comment audit event. */
+export declare function toReviewCommentEventDTO(event: ReviewCommentEvent): ReviewCommentEventDTO;
+/** Project the immutable snake_case review result to the existing camelCase feedback wire shape. */
+export declare function toFeedbackResultDTO(result: ReviewResult): FeedbackResultDTO;
+/** The only internal review-error to public HTTP projection. Every internal
+ * review failure is listed explicitly so handlers never need to invent a status
+ * or public code. */
+export declare const REVIEW_ERROR_MAP: Readonly<Record<ReviewErrorCode, {
+    status: number;
+    code: string;
+}>>;
+/** The single error-mapping function (spec §8). Projects any thrown value into
+ *  `{ status, code }`:
+ *   - a CrtrError → status by its `exitCode` class, `code` its machine code;
+ *   - a feed `FinalizationError` → 409 `already_finalized` /
+ *     `finalization_forbidden`, or 404 `node_not_found`;
+ *   - a `NodeIdConflictError` (a `--node-id`/`node_id` spawn at an id that
+ *     already exists) → 409 `node_id_exists`;
+ *   - a `WorktreeError` → its own code at 400 (404 for `unknown_node`), with
+ *     `next` + git `detail` preserved as CrtrError details;
+ *   - `reviveNode`'s finalization-latch throw → 409 `already_finalized`;
+ *   - an "unknown node" throw (reviveNode / transition / getNode-null handler) →
+ *     404 `node_not_found`;
+ *   - a `transition` illegal-move throw → 409 `illegal_transition`;
+ *   - anything already carrying a numeric `status` + string `code` (an
+ *     `ApiError`-shaped throw) → used verbatim;
+ *   - anything else → 500 `internal`.
+ *  The recognized plain-`Error` cases match on the throw sites' messages (the
+ *  only signal those sites carry); the source sites are named above so a message
+ *  change there is caught by the A-11 tests. */
+export declare function errorToStatus(thrown: unknown): {
+    status: number;
+    code: string;
+};
+/** Build the uniform JSON error body (spec §8) for a thrown value, using
+ *  `errorToStatus` for the status/code. Structured `details` are surfaced for a
+ *  CrtrError or ApiError (they let the client reconstruct the error verbatim). A 500 still
+ *  omits `details` for hygiene, but NO LONGER strips the message to a bare
+ *  `internal error`: it surfaces the bounded cause (`boundedCause`) so a caller
+ *  is never left with a causeless internal, while the router logs the full
+ *  error (with stack) server-side. */
+export declare function toErrorBody(thrown: unknown): {
+    status: number;
+    body: ErrorBody;
+};