orbitmap 0.4.4 → 0.5.0

package/dist/adapters/local/shapes.d.ts

@@ -8,18 +8,20 @@
  *
  * Pure functions only: no file I/O, no validation (that is `rules.ts`).
  */
-import type { AreaFile, DocumentRecord, IntentRecord, MissionRecord, TaskRecord, WorkspaceFile } from './types.js';
+import type { AreaFile, DocumentRecord, IntentRecord, IssueRecord, MissionRecord, TaskRecord, WorkspaceFile } from './types.js';
 /**
  * The API splits an entity number into `task_number` (the bare code) and
  * `display_number` (`TS-<code>`); locally we store the prefixed form.
  */
 export declare function stripEntityPrefix(entityNumber: string): string;
-/** The implicit local agent, in the `/context` agent shape. */
+/**
+ * The implicit local agent, in the `/context` agent shape. Since API 10.0.0 the agent
+ * block is a bare identity ping — the `introduction` field is gone.
+ */
 export declare function agentShape(): {
     id: string;
     name: string;
     slug: string;
-    introduction: string;
 };
 /** Workspace as embedded in `areas` list items. */
 export declare function workspaceShape(workspace: WorkspaceFile): {
@@ -85,40 +87,181 @@ export declare function areaOverviewEnvelope(area: AreaFile, tasks: readonly Tas
 };
 /** Number of `##` headings in a document body (the API's `sections_count`). */
 export declare function countSections(body: string): number;
-/** Document entry as embedded in `/context` and task detail. */
+/** Document entry as embedded in task detail (`workspace_knowledge`). */
 export declare function documentEntry(document: DocumentRecord, body: string): Record<string, unknown>;
+/**
+ * Extract the handle-tier TL;DR from an intent/mission field — a 1:1 port of the
+ * provider's `App\Support\TldrParser`, so both adapters summarize identically.
+ *
+ * An explicit TL;DR is everything before the first `---` rule on its own line. Without
+ * a rule, the first paragraph is truncated to {@link TLDR_MAX_LENGTH} code points on a
+ * word boundary and flagged as `missing` (the lazy-backfill signal).
+ */
+export declare function extractTldr(field: string | null | undefined): {
+    tldr: string | null;
+    missing: boolean;
+};
+/**
+ * `meta.more` — one entry per handle type, how to fetch deeper. Locked copy from the
+ * IN-vnz6fs design (the provider carries it verbatim); do not paraphrase.
+ */
+export declare const CONTEXT_MORE: Readonly<Record<string, string>>;
+/** An intent as the store hands it out: frontmatter + the body (= `outcome`). */
+export interface IntentFileLike {
+    frontmatter: IntentRecord;
+    body: string;
+}
+/**
+ * The missions worth matching against: the active one, the latest closed one (recency
+ * of outcome context) and the next {@link CONTEXT_NEXT_MISSIONS_CAP} in manual order —
+ * the provider's `selectMissions`, over local records.
+ */
+export declare function selectContextMissions(missions: readonly MissionRecord[]): MissionRecord[];
+/**
+ * The deduped union of the provider's four mechanical intent lists, over local files.
+ * Deliberately NO status filter anywhere — a closed intent is valid matching context.
+ *
+ * Two local substitutions, both because the file store lacks a dimension the server has:
+ *
+ * - Lists (b) "what this agent touched last" and (d) "what anyone moved recently" are
+ *   the same list here: intents carry no work-log tail locally (only tasks have a
+ *   `## Work Log`, spec §4.5) and there is exactly one agent, so `updated_at` DESC is
+ *   the closest analogue of both recency signals.
+ * - List (c), the backlog head, orders by `intent_number` (creation order): local
+ *   intents have no manual `sort_order`.
+ */
+export declare function selectContextIntents(intents: readonly IntentFileLike[], missionNumbers: readonly string[]): IntentFileLike[];
+/** One `missions[]` entry: handle + outcome TL;DR. */
+export declare function contextMissionEntry(mission: MissionRecord): Record<string, unknown>;
+/**
+ * One `intents[]` entry: handle, mission, areas and the three TL;DRs. `areas` is the
+ * caller-resolved slug list — declared (`frontmatter.areas`) beats task-derived, both
+ * computed by the adapter, exactly like the provider's declared-over-derived rule.
+ */
+export declare function contextIntentEntry(file: IntentFileLike, areas: readonly string[]): Record<string, unknown>;
+/**
+ * `workitems[]` — standalone mission work only: tasks and issues hanging directly off
+ * a mission (`mission` set, `intent` null), never subtasks. Intent-linked work is
+ * deliberately absent — it is reached through its intent on demand.
+ */
+export declare function contextWorkitemEntries(tasks: ReadonlyArray<{
+    frontmatter: TaskRecord;
+    area: string | null;
+}>, issues: ReadonlyArray<{
+    frontmatter: IssueRecord;
+}>): Array<Record<string, unknown>>;
+/**
+ * `documents[]` metadata entry. `when_to_use` is the `context` column renamed on the
+ * wire (API 10.0.0); `scope` is always `workspace` locally — local documents belong to
+ * the workspace (spec §4.1), never to one area.
+ */
+export declare function contextDocumentEntry(document: DocumentRecord): Record<string, unknown>;
 export interface ContextInput {
     workspace: WorkspaceFile;
+    /** The resolved context area — its presence selects the area branch of the response. */
     area?: AreaFile;
-    activeMission?: MissionRecord | null;
-    tasks: readonly TaskRecord[];
-    documents: readonly Record<string, unknown>[];
+    missions: Array<Record<string, unknown>>;
+    intents: Array<Record<string, unknown>>;
+    workitems: Array<Record<string, unknown>>;
+    /** Every area of the workspace (the local "reach"), already ordered by name. */
+    areas: readonly AreaFile[];
+    documents: Array<Record<string, unknown>>;
 }
-/** `GET /context` envelope. */
+/**
+ * `GET /context` envelope (API 10.0.0). Identity first — `agent`, then `area` (area
+ * branch) or `workspace` (workspace branch) — followed by the matching material:
+ * missions, intents, workitems, areas, documents metadata and `meta.more`. The old
+ * `tasks` / `active_mission` / `open_intents` / `agent.introduction` are gone.
+ */
 export declare function contextEnvelope(input: ContextInput): {
     data: Record<string, unknown>;
 };
 /**
- * One row of `GET /tasks`.
- *
- * `area` is present **only** in the workspace-scoped listing (no `X-Orbitmap-Area`), exactly
- * as the API does it: the area-scoped rows are unchanged, so nothing that reads them today
- * sees a new key.
+ * Rows per page when the caller named no `--limit`, and the ceiling one may ask for.
+ * Both are the API's own numbers (`LIMIT_HELP`: "Rows per page (default 30, max 100)"),
+ * reimplemented here because in local mode there is no server to apply them.
  */
-export declare function taskListItem(task: TaskRecord, description: string | null, area?: AreaFile): Record<string, unknown>;
+export declare const DEFAULT_LIST_LIMIT = 30;
+export declare const MAX_LIST_LIMIT = 100;
+/** One area's contribution to a page: what it showed, and what it holds. */
+export interface PerAreaCount {
+    slug: string | null;
+    shown: number;
+    total: number;
+}
 /**
- * `GET /tasks` envelope.
+ * `meta.applied_filters` — the caller's question, echoed back.
  *
- * Area scope keeps its historical `meta: { count }` byte for byte. Workspace scope adds
- * `scope: 'workspace'` (the marker commands branch on) plus the workspace identity — the
- * same two extra keys the API emits.
+ * ALWAYS present and ALWAYS complete: a short list must never be ambiguous between
+ * "nothing exists" and "you did not ask for it" (IN-nahetc). `null` means the dimension
+ * does not apply to this list (intents and missions have no area; only tasks have an
+ * assignee), never "no filter" — that is spelled `all` / `any`.
  */
-export declare function tasksListEnvelope(items: Array<Record<string, unknown>>, workspace?: WorkspaceFile): {
+export interface AppliedListFilters {
+    areas: string | null;
+    status: string | null;
+    hidden_by_status: number;
+    assignee: string | null;
+    intent: string | null;
+    mission: string | null;
+    limit: number;
+}
+/** The list envelope every local list answers with. */
+export interface ListEnvelope {
     data: Array<Record<string, unknown>>;
     meta: Record<string, unknown>;
-};
-/** The `task` block of the task-detail envelope. */
-export declare function taskShape(task: TaskRecord, area: AreaFile, description: string | null): Record<string, unknown>;
+}
+export interface ListEnvelopeInput {
+    /** Every row matching every filter, in list order — BEFORE paging. */
+    rows: ReadonlyArray<Record<string, unknown>>;
+    workspace: WorkspaceFile;
+    /** Where this page starts (decoded from `cursor`). */
+    offset: number;
+    /** Rows in this page. */
+    limit: number;
+    filters: AppliedListFilters;
+    /**
+     * How to read a row's area slug for `per_area`. Omit for a list with no area dimension
+     * (intents, missions, and local documents, which are workspace-scoped by §4.1): `per_area`
+     * is then `[]`, exactly as the provider answers for `/intents` and `/missions`.
+     */
+    areaOf?: (row: Record<string, unknown>) => string | null;
+}
+/**
+ * The 9.0.0 list envelope, built once for every local list.
+ *
+ * Paging is a plain offset encoded as the opaque `next_cursor` (local mode has no keyset
+ * to page on, and the cursor is documented as opaque). `total` counts everything the
+ * filters matched, so the truncation line and `--all` behave exactly as they do against
+ * the API; `per_area` splits that total per area and reports how much of each is on THIS
+ * page.
+ */
+export declare function listEnvelope(input: ListEnvelopeInput): ListEnvelope;
+/** The area slug an area-scoped row carries in its `area` block, or `null`. */
+export declare function rowAreaSlug(row: Record<string, unknown>): string | null;
+/**
+ * One row of `GET /tasks`.
+ *
+ * Every row carries its `area` since API 9.0.0 — the list spans the whole workspace, so
+ * "which area is this?" has to be answerable from the row — plus `agent_id` and
+ * `assigned_user_id`: the list stopped being caller-only, so "mine, someone else's, or free"
+ * has to be answerable from the row too.
+ */
+export declare function taskListItem(task: TaskRecord, description: string | null, area: AreaFile): Record<string, unknown>;
+/**
+ * `GET /tasks` envelope — {@link listEnvelope} with the task defaults, kept as a named
+ * builder because `tasks.ts` is the only caller that needs no extra arguments.
+ */
+export declare function tasksListEnvelope(input: ListEnvelopeInput): ListEnvelope;
+/**
+ * The `task` block of the task-detail envelope.
+ *
+ * `logCount` feeds the freshness pair's second half (API 10.1.0): `last_log_id` is the
+ * id of the newest `logs[]` entry, whose ids are `<task_number>-log-<n>` (see
+ * {@link workLogEntryShape}) — so the newest is simply `-log-<logCount>`, or `null`
+ * when the task has no log yet.
+ */
+export declare function taskShape(task: TaskRecord, area: AreaFile, description: string | null, logCount?: number): Record<string, unknown>;
 /** Compact task shape used for subtasks and dependency references. */
 export declare function taskSummary(task: TaskRecord): Record<string, unknown>;
 export interface TaskDetailInput {