@north-light/api 0.0.0 → 0.3.415

package/dist/api/dto/crons.d.ts

@@ -0,0 +1,164 @@
+import type { IsoTime, NodeIdDTO } from './common.js';
+export type CronScopeDTO = 'profile' | 'global';
+export type CronOverlapDTO = 'skip' | 'queue' | 'replace';
+export type CronOnOutputDTO = 'silent' | 'on-failure' | 'always' | 'on-change';
+export type CronStateDTO = 'active' | 'paused';
+export type CronRunStateDTO = 'idle' | 'running';
+/** Is this a safe single path segment for `routes.cron*()` interpolation?
+ *  Cron ids are server-minted UUIDs, but the route builders carry no logic, so
+ *  every interpolated id is gated here first (the `isSafeNodeId` discipline). */
+export declare function isSafeCronId(id: string): boolean;
+/** The last settled run, carried on every cron projection so `cron list` shows
+ *  recent health without a `cron show` per row. Null until the first run. */
+export interface CronLastRunDTO {
+    /** When the run settled (UTC). */
+    finished: IsoTime | null;
+    /** -1 = timeout kill; null = no exit observed (process error / skip marker). */
+    exit_code: number | null;
+    /** What the sink did with the output, or why it didn't. */
+    delivered: string | null;
+}
+/** A cron row projection (`GET /v1/crons`). */
+export interface CronDTO {
+    cron_id: string;
+    /** Agent-legible label; how the cron shows in list. */
+    name: string;
+    /** Provenance only — the node that armed it, if any; never a cascade anchor. */
+    created_by: NodeIdDTO | null;
+    /** The bash command each fire runs. */
+    command: string;
+    /** The grant the cron runs under (checked at every fire, call and birth); null only for the terminal on a runtime with no issuer. */
+    grant_id: string | null;
+    /** The scopes the cron is bounded to; null = the grant's whole current set (a person-armed terminal cron). */
+    scopes: string[] | null;
+    /** The run of the node that armed it, when a node did. */
+    origin_run_id: string | null;
+    /** The shell and any spawned node stay isolated when armed from an isolated node. */
+    isolated: boolean;
+    /** Next occurrence (UTC). */
+    fire_at: IsoTime;
+    /** Recur JSON (interval or cron); null for a one-shot. */
+    recur: string | null;
+    /** IANA zone for a calendar cadence; null otherwise. */
+    tz: string | null;
+    /** Clock bound; the row is deleted when passed. Null = no bound. */
+    expires_at: IsoTime | null;
+    /** Opt-in node coupling (cascades on that node's deletion); null = detached. */
+    anchor_node: NodeIdDTO | null;
+    cancel_on_wake: boolean;
+    /** Execution context, snapshotted at arm time. */
+    cwd: string;
+    profile: string | null;
+    scope: CronScopeDTO;
+    /** Names of the extra env vars snapshotted onto the row — KEYS ONLY: the
+     *  values are the caller's to know and may be secrets. */
+    env_keys: string[];
+    run_timeout_s: number;
+    overlap: CronOverlapDTO;
+    on_output: CronOnOutputDTO;
+    /** Where deliveries go — the raw sink spec (`node:<id>` | `spawn:<kind>` |
+     *  `human`), or null when the disposition never delivers. */
+    sink: string | null;
+    tier: string;
+    state: CronStateDTO;
+    /** True while the row is parked by the exit-75 owed-gate disposition: the
+     *  last scheduled run declared "owed but not currently eligible", so the
+     *  occurrence was not spent. A daemon poke re-dues it now; otherwise a
+     *  recurring row re-checks at its natural `fire_at` slot (the backstop) and
+     *  a held one-shot waits for a poke until `expires_at` deletes it. `state`
+     *  stays honest (active|paused) — renderers derive; an active held row must
+     *  never present as paused. */
+    held: boolean;
+    run_state: CronRunStateDTO;
+    /** Recent health: the most recent settled run, or null if it never ran. */
+    last_run: CronLastRunDTO | null;
+    created: IsoTime;
+    updated: IsoTime;
+}
+/** `GET /v1/crons` query. `profile` is the CALLER's profile, which is what
+ *  scoping means here: a profile-scoped cron belongs to its profile, a global
+ *  one is canvas-home-wide. Omitting `profile` means the caller stands outside
+ *  every profile (a plain shell, or a provenance read such as "which crons did
+ *  node X arm") and sees the whole canvas home. This is a namespacing
+ *  boundary between profiles, not a security boundary. */
+export interface ListCronsQuery {
+    profile?: string;
+}
+/** Caller identity for the per-cron routes (show/pause/resume/run/cancel).
+ *  Same rule as `ListCronsQuery`: a cron outside the caller's scope is 404,
+ *  and an absent profile sees everything. */
+export interface CronScopeQuery {
+    profile?: string | null;
+}
+/** Cancellation-only query. `run_id` is set automatically inside a cron run,
+ * letting crtrd distinguish a run ending itself from an external cancellation
+ * that must terminate an in-flight process. */
+export interface CancelCronQuery extends CronScopeQuery {
+    run_id?: string;
+}
+/** One settled run-log entry (`GET /v1/crons/:cronId`, `POST /v1/crons/:cronId/run`). */
+export interface CronRunDTO {
+    run_id: string;
+    started: IsoTime;
+    finished: IsoTime | null;
+    duration_ms: number | null;
+    /** null = no exit observed (spawn/process error, or a skip marker); -1 = timeout kill. */
+    exit_code: number | null;
+    stdout_head: string | null;
+    stderr_head: string | null;
+    /** What the sink did with this run's output, or why it didn't. */
+    delivered: string | null;
+}
+/** `POST /v1/crons/poke` — the bare daemon-level eligibility poke. Re-dues
+ *  every held active cron now; paused rows keep their held state. Idempotent
+ *  and free when nothing is held. */
+export interface PokeCronsResult {
+    /** How many held rows were re-dued — for the caller's log line. */
+    unparked: number;
+    /** The poke receipt instant (UTC). */
+    at: IsoTime;
+}
+/** `GET /v1/crons/:cronId` — one cron with its run-log ring (most recent first). */
+export interface CronShowDTO {
+    cron: CronDTO;
+    runs: CronRunDTO[];
+}
+/** `POST /v1/crons` — arm one cron. The CLI resolves timing client-side
+ *  (parseWhen/parseCadence) and sends the settled `fire_at`/`recur`/`tz`;
+ *  the server mints the cron_id and applies spec defaults for everything
+ *  omitted. */
+export interface ArmCronRequest {
+    name: string;
+    command: string;
+    fire_at: IsoTime;
+    recur?: string | null;
+    tz?: string | null;
+    created_by?: NodeIdDTO | null;
+    isolated?: boolean;
+    /** Execution context, snapshotted at arm time — chosen by the client, else
+     *  inherited from the creating node; never re-resolved at run time. Omitted
+     *  means the daemon's default: the cron's own folder for an isolated
+     *  cron, else the app's files directory. A runtime whose cron runs are
+     *  sandboxed refuses (400 `cwd_not_mounted`) a chosen cwd the run's mounts do
+     *  not reach, so a cron is never armed with a directory it cannot start in. */
+    cwd?: string;
+    /** `cwd` is the caller's own current directory rather than a choice. A
+     *  sandboxed runtime then replaces it with the default when the run cannot
+     *  reach it, instead of refusing. */
+    cwd_is_default?: boolean;
+    /** Extra env for every run, as a JSON object of string values. */
+    env_json?: string | null;
+    profile?: string | null;
+    /** `profile` (default when a profile is resolved) requires a profile. */
+    scope?: CronScopeDTO;
+    on_output?: CronOnOutputDTO;
+    /** Raw sink spec: `node:<id>` | `spawn:<kind>` | `human`. Required by the
+     *  always/on-change dispositions; meaningless otherwise. */
+    sink?: string | null;
+    tier?: string;
+    expires_at?: IsoTime | null;
+    anchor_node?: NodeIdDTO | null;
+    cancel_on_wake?: boolean;
+    run_timeout_s?: number;
+    overlap?: CronOverlapDTO;
+}

package/dist/api/dto/crons.js

@@ -0,0 +1,10 @@
+// Cron DTOs (the cron-spec scheduler — arm/list/show/run/pause/resume/cancel).
+/** Is this a safe single path segment for `routes.cron*()` interpolation?
+ *  Cron ids are server-minted UUIDs, but the route builders carry no logic, so
+ *  every interpolated id is gated here first (the `isSafeNodeId` discipline). */
+export function isSafeCronId(id) {
+    return typeof id === 'string'
+        && id !== '' && id !== '.' && id !== '..'
+        && !/[\\/\0\s?#%]/u.test(id)
+        && Buffer.byteLength(id, 'utf8') <= 128;
+}

package/dist/api/dto/custom-objects.d.ts

@@ -0,0 +1,66 @@
+export interface CustomEventSpecDTO {
+    level: number;
+    supersedes?: boolean;
+}
+export type CustomReceiverDTO = 'queue' | {
+    url: string;
+} | {
+    argv: string[];
+    cwd: string;
+};
+export interface RegisterCustomObjectRequestDTO {
+    kind: string;
+    name: string;
+    owner?: string;
+    description: string;
+    events: Record<string, CustomEventSpecDTO>;
+    receiver?: CustomReceiverDTO;
+    rotate_token?: boolean;
+}
+export interface RegisterCustomObjectResponseDTO {
+    id: string;
+    name: string;
+    token?: string;
+}
+export interface PublishCustomObjectRequestDTO {
+    event: string;
+    summary: string;
+    state?: unknown;
+    cause?: string;
+}
+export interface PublishCustomObjectResponseDTO {
+    message_id: string | null;
+    delivered: number;
+    depth: number;
+}
+/** Pending deliveries replay on every connection until acknowledged, regardless of `after`. Blank-line heartbeats arrive every 15 seconds. */
+export interface QueueLineDTO {
+    /** Acknowledge this delivery by its delivery_id. */
+    delivery_id: string;
+    /** The source event id to pass as `publish({ cause: line.message_id })` when reacting. */
+    message_id: string;
+    /** Durable ordering number, not an acknowledgement checkpoint. */
+    seq: number;
+    event: string;
+    level: number;
+    object: {
+        id: string;
+        type: string;
+        name: string;
+        owner: string | null;
+    };
+    actor: string | null;
+    attrs: Record<string, unknown>;
+    summary?: string;
+    state?: unknown;
+    pointer?: string;
+    depth: number;
+    created_at: string;
+}
+export interface AckCustomDeliveriesRequestDTO {
+    delivery_ids: string[];
+}
+export interface AckCustomDeliveriesResponseDTO {
+    acknowledged: number;
+    unknown?: string[];
+}

package/dist/api/dto/custom-objects.js

@@ -0,0 +1 @@
+export {};

package/dist/api/dto/delivery.d.ts

@@ -0,0 +1,71 @@
+import type { NodeSubjectDTO } from './nodes.js';
+export type DeliveryActivity = 'boot' | 'system-prompt' | 'compact' | 'persona' | 'file-read' | 'command' | 'pre-command' | 'slash-command' | 'names'
+/** Dry run only: a live node's workspace-open arrives inside its boot. */
+ | 'workspace-open'
+/** Dry run only: what reading the document named by `subject` delivers alongside it. */
+ | 'document-read';
+export interface DeliveryRequest {
+    expected_execution_id?: string;
+    activity: DeliveryActivity;
+    subject?: string;
+    inherited?: boolean;
+    dry_run?: boolean;
+    subject_override?: Partial<NodeSubjectDTO>;
+}
+/** A node that does not exist, for `POST /v1/delivery/dry-run`. Unset fields
+ *  come from `node` when one is named, else from defaults. */
+export interface HypotheticalNodeDTO {
+    cwd?: string;
+    /** Profile id or name; null for no profile. Defaults to the profile pinned to `cwd`. */
+    profile?: string | null;
+    grantee?: string;
+    kind?: string;
+    mode?: 'base' | 'orchestrator';
+    lifecycle?: 'terminal' | 'resident';
+    has_manager?: boolean;
+    depth?: number;
+}
+/** `POST /v1/delivery/dry-run` — a person's dry run of one delivery activity,
+ *  for a live node (`node`), a node that does not exist (`hypothetical`), or a
+ *  live node dialled away from (both). Writes nothing. */
+export interface DeliveryDryRunRequest {
+    activity: DeliveryActivity;
+    subject?: string;
+    node?: string;
+    hypothetical?: HypotheticalNodeDTO;
+    subject_override?: Partial<NodeSubjectDTO>;
+}
+/** One resolvable inline memory reference — the broker's `RefMeta`. Metadata
+ *  only, never the document body or its source path. */
+export interface DeliveryRefDTO {
+    name: string;
+    kind: 'knowledge' | 'preference';
+    scope: 'node' | 'project' | 'profile' | 'user' | 'builtin';
+    shortForm: string;
+    gatewayVisible: boolean;
+}
+export interface DeliveryCommandDTO {
+    name: string;
+    command_name: string;
+    description: string;
+    canonical_body: string;
+    execution_body: string;
+}
+export interface DeliveryResponse {
+    content: string;
+    inherited?: boolean;
+    commands?: DeliveryCommandDTO[];
+    blocks?: string[];
+    execution_body?: string;
+    refs?: DeliveryRefDTO[];
+    names?: string[];
+    plan?: unknown;
+}
+export interface BackgroundedJobRequest {
+    command: string;
+    job_dir: string;
+    log_path: string;
+}
+export interface BackgroundedJobDTO {
+    id: string;
+}

package/dist/api/dto/delivery.js

@@ -0,0 +1,7 @@
+// Delivery DTOs — `POST /v1/nodes/:id/delivery`, the broker's one route for
+// rule-driven document delivery, plus the backgrounded-job record route.
+//
+// PURITY (spec §3.1): Node built-ins + `src/api/*` only (type-only imports).
+// Never reach into src/core here: the publish-api job compiles this package
+// alone, and core modules pull in workspace packages it does not build.
+export {};

package/dist/api/dto/docs.d.ts

@@ -0,0 +1,135 @@
+import type { ObjectDTO, PrivacyName } from './objects.js';
+export declare const RULE_ON: readonly ["boot", "workspace-open", "file-read", "document-read", "command", "pre-command", "slash-command"];
+export type RuleOnName = typeof RULE_ON[number];
+export declare const RULE_DELIVER: readonly ["name", "preview", "content"];
+export type RuleDeliverName = typeof RULE_DELIVER[number];
+export interface DeliveryRuleDTO {
+    on: RuleOnName;
+    match?: string[];
+    match_frontmatter?: Record<string, unknown>;
+    if?: unknown;
+    deliver: RuleDeliverName;
+}
+/** The `--owner` value: whose document it is. */
+export type DocOwnerFlag = 'node' | 'user' | 'profile' | `profile:${string}` | 'app' | 'repo' | `repo:${string}`;
+export declare const DOC_KINDS: readonly ["knowledge", "preference"];
+export type DocKindName = typeof DOC_KINDS[number];
+export interface DocWriteRequest {
+    name: string;
+    body: string;
+    preview: string;
+    owner?: DocOwnerFlag;
+    kind?: DocKindName;
+    summary?: string;
+    privacy?: PrivacyName;
+    rules?: DeliveryRuleDTO[];
+    why_it_exists?: string;
+    unlisted?: boolean;
+    lint_ignore?: string[];
+    extensions?: Record<string, Record<string, unknown>>;
+    /** The caller's cwd, for `--owner repo` resolution. */
+    cwd?: string;
+}
+/** `name` is canonical: `<owner-handle>/<name>`. */
+/** `unresolved_links`: names that match nothing in the writer's view. `remote_links`: names whose
+ *  first segment is no owner on this runtime — on another runtime, or misspelled. */
+export interface DocLinkReportDTO {
+    unresolved_links?: string[];
+    remote_links?: string[];
+}
+export interface DocWrittenDTO extends DocLinkReportDTO {
+    id: string;
+    name: string;
+}
+export declare const DOC_UNSET_FIELDS: readonly ["summary", "why_it_exists", "unlisted", "lint_ignore", "extensions", "rules"];
+export type DocUnsetField = typeof DOC_UNSET_FIELDS[number];
+export interface DocEditRequest {
+    body?: string;
+    replace?: Array<{
+        old: string;
+        new: string;
+    }>;
+    rationale: string;
+    /** The heads key the edit was made from. Absent → the caller's last read of the document. */
+    base?: string;
+    verbatim?: boolean;
+    preview?: string;
+    summary?: string;
+    privacy?: PrivacyName;
+    rules?: DeliveryRuleDTO[];
+    why_it_exists?: string;
+    unlisted?: boolean;
+    lint_ignore?: string[];
+    extensions?: Record<string, Record<string, unknown>>;
+    unset?: DocUnsetField[];
+}
+export interface DocEditedDTO extends DocLinkReportDTO {
+    id: string;
+    name: string;
+    revision: number;
+}
+/** Body of the 409 `stale_revision` error's `details`. */
+export interface DocStaleDTO {
+    stale: {
+        revision: number;
+        heads_key: string;
+    };
+}
+export interface DocMoveRequest {
+    new_name?: string;
+    owner?: DocOwnerFlag;
+    cwd?: string;
+}
+export interface DocMovedDTO {
+    id: string;
+    name: string;
+}
+export interface DocDeletedDTO {
+    id: string;
+    name: string;
+}
+export interface DocHistoryQuery {
+    diff?: number;
+}
+export interface DocRevisionDTO {
+    rev_id: string;
+    number: number;
+    author_id: string | null;
+    rationale: string | null;
+    verbatim: boolean;
+    created_at: string;
+    parents: string[];
+}
+export interface DocHistoryDTO {
+    object: ObjectDTO;
+    revisions: DocRevisionDTO[];
+    diff?: string;
+}
+export interface DocLintRequest {
+    owner?: DocOwnerFlag;
+    cwd?: string;
+}
+export interface DocLintFindingDTO {
+    name: string;
+    severity: 'error' | 'warning';
+    rule: string;
+    message: string;
+}
+export interface DocLintDTO {
+    findings: DocLintFindingDTO[];
+}
+export interface ReconcilePackagesDTO {
+    created: number;
+    updated: number;
+    deleted: number;
+    /** plugins whose handle another owner holds; their documents are not on the canvas */
+    conflicts: Array<{
+        plugin: string;
+        message: string;
+    }>;
+    /** package files that are not documents (unparseable frontmatter, a name another file holds) */
+    invalid: Array<{
+        path: string;
+        error: string;
+    }>;
+}

package/dist/api/dto/docs.js

@@ -0,0 +1,8 @@
+// Document DTOs — the `/v1/docs` write verbs behind `crtr doc`, plus the
+// package-document reconcile route.
+//
+// PURITY (spec §3.1): Node built-ins + `src/api/*` only.
+export const RULE_ON = ['boot', 'workspace-open', 'file-read', 'document-read', 'command', 'pre-command', 'slash-command'];
+export const RULE_DELIVER = ['name', 'preview', 'content'];
+export const DOC_KINDS = ['knowledge', 'preference'];
+export const DOC_UNSET_FIELDS = ['summary', 'why_it_exists', 'unlisted', 'lint_ignore', 'extensions', 'rules'];

package/dist/api/dto/files.d.ts

@@ -0,0 +1,21 @@
+export type FileEncoding = 'utf8' | 'base64';
+export interface FilePeekDTO {
+    path: string;
+    content: string;
+    truncated: boolean;
+}
+export interface FileWriteDTO {
+    path: string;
+    bytes_written: number;
+}
+export interface FileEntryDTO {
+    name: string;
+    type: 'file' | 'dir' | 'other';
+    size: number;
+    modified: string;
+}
+export interface FileListDTO {
+    path: string;
+    entries: FileEntryDTO[];
+    truncated: boolean;
+}

package/dist/api/dto/files.js

@@ -0,0 +1 @@
+export {};

package/dist/api/dto/focus.d.ts

@@ -0,0 +1,24 @@
+import type { NodeIdDTO } from './common.js';
+/** One viewer row: a node's single on-screen pane in a tmux session. */
+export interface FocusDTO {
+    focus_id: string;
+    pane: string | null;
+    session: string | null;
+    node_id: NodeIdDTO;
+}
+/** `POST /v1/focuses` body — register a viewer pane as a node's focus row.
+ *  UNIQUE(node_id): returns the existing row (no insert) when the pane or node
+ *  is already registered. `window` is accepted for the call contract but not
+ *  stored (the table keys on pane + session). */
+export interface RegisterFocusRequest {
+    node_id: NodeIdDTO;
+    pane: string;
+    session: string | null;
+    window: string | null;
+}
+/** `PATCH /v1/focuses/{focus_id}` body — re-point a viewer row's pane + its
+ *  derived session cache after the pane moves. */
+export interface SetFocusPaneRequest {
+    pane: string | null;
+    session: string | null;
+}

package/dist/api/dto/focus.js

@@ -0,0 +1,10 @@
+// Focus DTOs (the viewer registry — canvas.db `focuses` table). A FOCUS is one
+// durable on-screen viewport bound to one node (UNIQUE node_id ⇒ ≤1 per node).
+// The wire shape mirrors the internal `FocusRow` 1:1 — the registry is a flat
+// pane↔node binding with no projection to reshape.
+//
+// The reads GC lazily server-side (a row whose pane is gone is pruned on read),
+// so a returned row is always live. The mutations are the tmux-driven CLI
+// surfaces' (surface-tmux-spread, focus placement) writes: the tmux verbs run
+// LOCALLY in the caller's session; only the canvas.db focus rows route here.
+export {};

package/dist/api/dto/grants.d.ts

@@ -0,0 +1,28 @@
+/** A provider's setup state for the account (directory spec, "Provider setup state"). */
+export type SetupState = 'not_started' | 'pending' | 'ready' | 'failed';
+/** One provider the grantee requires, as the directory's grant sync carried it. */
+export interface ProviderDependency {
+    state: SetupState;
+    /** The provider's own sentence for `pending` and `failed` (its `message_pending` / `message_failed`); absent for `not_started` and `ready`. */
+    message?: string;
+    /** Absolute URL of the directory's setup page for this provider and this app (`<issuer>/connect/setup/<provider>?client_id=<grantee>`); the app may append `return_to` (its own registered redirect origin) so Continue brings the person back. */
+    next: string;
+}
+export interface GrantGetDTO {
+    sub: string;
+    grantee: string;
+    client_id: string;
+    grant: string;
+    exp: number;
+    rev: number;
+    resolved_scopes: {
+        scope: string;
+        mode: 'always' | 'ask';
+    }[];
+    spend_cap: number | null;
+    payer: 'user';
+    /** `{ <provider id>: ProviderDependency }` as the directory's grant sync carried it; `{}` when the grantee has none. The daemon performs no `requires` check: an app follows this with the SDK grant watch (`oauth.watchGrants`, or `grant.get` with `wait`/`since`) and refuses its own operation with `provider_setup_pending`. When an entry's `state` is not `ready`, show its `message` (the provider's own sentence, when it has one) and send the person to its `next` (the directory's setup page) — never copy the provider's prose into the app. */
+    dependencies: Record<string, ProviderDependency>;
+    /** Opaque; changes exactly when `rev`, `resolved_scopes`, `spend_cap`, `payer` or `dependencies` changes (never on a periodic sync alone or a new token). Pass it back as `since` with `wait` to hold the read until it changes. */
+    version: string;
+}

package/dist/api/dto/grants.js

@@ -0,0 +1 @@
+export {};