@starlove/orbit 1.4.1 → 2.0.0

package/lib/core/errors.js

@@ -0,0 +1,160 @@
+/**
+ * Orbit's errors. Each carries a code, the same codes Orbit's answers have
+ * always used (`invalid_state`, `board_not_found`...), and a kind that says
+ * what went wrong in words any transport understands. The core and the storage
+ * adapters throw them; each transport maps the kind to its own form: an HTTP
+ * status (`HTTP_STATUS` below), an MCP tool error, a CLI exit code.
+ *
+ * `message` is what people and agents read. It is the code itself unless a
+ * clearer sentence was given, which is what Orbit's answers and the command
+ * language ("Orbit refused: invalid state.") already show.
+ */
+/** Every code Orbit raises, with its kind. */
+export const ERROR_CODES = {
+    // Boards
+    board_not_found: "not_found",
+    board_id_required: "invalid",
+    board_id_mismatch: "invalid",
+    board_slug_taken: "conflict",
+    board_slug_confirmation_required: "invalid",
+    board_has_no_states: "invalid",
+    board_files_busy: "conflict",
+    board_file_missing: "conflict",
+    unsafe_board_db_path: "conflict",
+    missing_name: "invalid",
+    // Lanes
+    state_not_found: "not_found",
+    invalid_state: "invalid",
+    invalid_state_order: "invalid",
+    invalid_state_role: "invalid",
+    state_has_tickets: "conflict",
+    cannot_delete_last_state: "conflict",
+    cannot_rename_ai_ready_lane: "conflict",
+    ai_ready_lane_must_be_named_ai_ready: "conflict",
+    missing_in_progress_state: "invalid",
+    missing_review_state: "invalid",
+    missing_next_state: "invalid",
+    // Cards
+    ticket_not_found: "not_found",
+    missing_title: "invalid",
+    invalid_ticket_type: "invalid",
+    invalid_number: "invalid",
+    invalid_nebula_url: "invalid",
+    ticket_id_or_number_or_title_required: "invalid",
+    missing_ticket_id: "invalid",
+    ticket_not_archived: "conflict",
+    invalid_parent_ticket: "invalid",
+    epic_cannot_have_parent: "invalid",
+    ticket_cannot_parent_itself: "invalid",
+    ticket_parent_cycle: "invalid",
+    missing_label: "invalid",
+    // Comments
+    comment_not_found: "not_found",
+    missing_body: "invalid",
+    omitted_for_ai_required: "invalid",
+    // Relations
+    relation_not_found: "not_found",
+    relation_exists: "conflict",
+    relation_self: "invalid",
+    relation_redundant_with_parent: "invalid",
+    hierarchy_uses_parent_ticket_id: "invalid",
+    blocker_target_already_done: "invalid",
+    blocker_source_already_done: "invalid",
+    invalid_relation_type: "invalid",
+    missing_source_ticket_id: "invalid",
+    missing_target_ticket_id: "invalid",
+    // Journal
+    board_entry_not_found: "not_found",
+    invalid_project_entry_type: "invalid",
+    missing_entry_title: "invalid",
+    entry_not_struck: "conflict",
+    // Agents
+    forbidden: "forbidden",
+    missing_message: "invalid",
+    missing_summary: "invalid",
+    invalid_since: "invalid",
+    // Review verdicts
+    review_verdict_not_found: "not_found",
+    missing_verdict: "invalid",
+    invalid_review_verdict: "invalid",
+    invalid_blocking_findings: "invalid",
+    invalid_optional_findings: "invalid",
+    invalid_evidence_commands: "invalid",
+    invalid_supersedes_prior_review_id: "invalid",
+    superseded_review_ticket_mismatch: "invalid",
+    // Images
+    attachment_not_found: "not_found",
+    attachment_file_missing: "not_found",
+    empty_attachment: "invalid",
+    invalid_attachment_path: "invalid",
+    attachment_too_large: "too_large",
+    unsupported_attachment_type: "unsupported_type",
+    attachment_type_mismatch: "unsupported_type",
+    // Markdown artifacts
+    artifact_not_found: "not_found",
+    artifact_path_required: "invalid",
+    artifact_path_outside_allowed_roots: "invalid",
+    artifact_root_unavailable: "invalid",
+    artifact_not_file: "invalid",
+    artifact_too_large: "too_large",
+    unsupported_artifact_type: "unsupported_type",
+    // Import and export
+    invalid_import_snapshot: "invalid",
+    snapshot_missing_board: "invalid",
+    import_requires_empty_board_or_replace_existing: "conflict",
+    import_would_delete_hidden_comments: "conflict",
+    // Requests (raised by the HTTP transport)
+    not_found: "not_found",
+    method_not_allowed: "method_not_allowed",
+    invalid_json: "invalid",
+    invalid_body: "invalid",
+    payload_too_large: "too_large",
+    cross_site_request: "forbidden",
+    folder_picker_unavailable: "not_supported",
+    // Storage (raised by adapters; see docs/ARCHITECTURE.md)
+    duplicate_id: "conflict",
+    ticket_number_taken: "conflict",
+    state_name_taken: "conflict",
+    label_name_taken: "conflict",
+    invalid_reference: "invalid",
+    invalid_blob_path: "invalid",
+    blob_exists: "conflict",
+    write_closed: "internal",
+    storage_busy: "unavailable",
+    storage_full: "unavailable",
+    storage_failed: "internal",
+    // Data folders (raised when a store opens; see docs/ARCHITECTURE.md, "Adapter notes")
+    data_needs_migration: "unavailable",
+    data_from_newer_orbit: "unavailable",
+    // `orbit migrate`: a source it can't read, or a folder it won't write into
+    migration_source_unreadable: "invalid",
+    migration_target_in_use: "conflict"
+};
+/** The HTTP status each kind answers with: the statuses Orbit's API has always used for these codes. */
+export const HTTP_STATUS = {
+    invalid: 400,
+    unauthorized: 401,
+    forbidden: 403,
+    not_found: 404,
+    method_not_allowed: 405,
+    conflict: 409,
+    too_large: 413,
+    unsupported_type: 415,
+    not_supported: 501,
+    unavailable: 503,
+    internal: 500
+};
+export class OrbitError extends Error {
+    code;
+    kind;
+    constructor(code, options = {}) {
+        super(options.message ?? code, options.cause === undefined ? undefined : { cause: options.cause });
+        this.name = "OrbitError";
+        this.code = code;
+        this.kind = ERROR_CODES[code];
+    }
+}
+/** True for an OrbitError, from this copy of Orbit or another (a host may bundle its own). */
+export function isOrbitError(value) {
+    return value instanceof OrbitError || (value instanceof Error && value.name === "OrbitError" && typeof value.code === "string" && typeof value.kind === "string");
+}

package/lib/core/files.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Images on cards, and the markdown files a card links to (a plan, a report).
+ * Their bytes live in the BlobStore: images under `attachments/`, markdown
+ * under `artifacts/`. Bytes are written before the record that names them and
+ * removed after the record is gone, so a failure leaves an unused file, never
+ * a card whose image has no bytes.
+ */
+import type { BoardCtx } from "./context.ts";
+import type { Attachment, Id } from "./model.ts";
+export declare const MAX_IMAGE_BYTES: number;
+export declare const MAX_MARKDOWN_BYTES: number;
+export { DOWNLOAD_TYPE, isShownImage, unsupportedTypeMessage } from "./image-types.ts";
+/** The image type the bytes themselves say, from their first bytes, or null when they look like none Orbit keeps. */
+export declare function sniffImage(bytes: Uint8Array): string | null;
+/**
+ * The type an imported or migrated image is stored as: the type its bytes
+ * say when that is one Orbit shows, whatever the file claimed; otherwise (an
+ * SVG, bytes no image type matches, or bytes that aren't what they claim)
+ * `DOWNLOAD_TYPE`, so the file is kept but only ever offered as a download.
+ * Without bytes, the type it claims, when Orbit shows that type.
+ */
+export declare function storedImageType(declared: unknown, bytes: Uint8Array | null): string;
+export interface AttachmentView extends Attachment {
+    missing: boolean;
+    /** True when Orbit won't show it as an image (an SVG, or a type it can't vouch for): the app offers it as a file to download. */
+    download_only: boolean;
+    content_url: string | null;
+    filesystem_size_bytes: number | null;
+}
+export declare function listAttachments(c: BoardCtx, ticketId: Id): Promise<{
+    attachments: AttachmentView[];
+}>;
+/** An image's bytes and type, and its name. A type Orbit won't show comes back as `DOWNLOAD_TYPE`, with `download_only` set. */
+export declare function attachmentContent(c: BoardCtx, ticketId: Id, attachmentId: Id): Promise<{
+    bytes: Uint8Array;
+    mime_type: string;
+    download_only: boolean;
+    original_name: string;
+}>;
+/** Adds an image to a card. Its bytes must be the type it says: a PNG named image/jpeg is refused. */
+export declare function createAttachment(c: BoardCtx, ticketId: Id, input: {
+    bytes: Uint8Array;
+    mime_type?: unknown;
+    original_name?: unknown;
+}): Promise<AttachmentView>;
+export declare function deleteAttachment(c: BoardCtx, ticketId: Id, attachmentId: Id): Promise<{
+    ok: true;
+    deleted_id: Id;
+}>;
+/** An image as an export carries it: its bytes as base64 when asked for and present. */
+export declare function exportedAttachment(c: BoardCtx, attachment: Attachment, includeBytes: boolean): Promise<AttachmentView & {
+    data_base64: string | null;
+    included: boolean;
+}>;
+/**
+ * An image an import brings, its bytes stored when it carries them; the
+ * record to write. Its bytes are sniffed as an upload's are, and stored under
+ * `storedImageType`: an SVG or a file that isn't what it says is kept as a
+ * download only.
+ */
+export declare function importedAttachment(c: BoardCtx, row: Record<string, unknown>, ticketId: Id): Promise<Attachment>;
+export interface StoredArtifact {
+    ticket_id: Id;
+    /** Relative to the board's artifacts. */
+    path: string;
+    /** Where the file is on this machine, for the person's own app; never for an agent. */
+    absolute_path?: string;
+    size_bytes: number;
+}
+/** Saves markdown for a card (a plan, a report) beside the board: `tickets/<card id>/<name>.md`. */
+export declare function writeArtifact(c: BoardCtx, ticketId: Id, input: {
+    filename?: unknown;
+    path?: unknown;
+    content?: unknown;
+}): Promise<StoredArtifact>;
+/** Reads a markdown file in the board's artifacts. */
+export declare function readArtifact(c: BoardCtx, ticketId: Id, requested: unknown): Promise<StoredArtifact & {
+    content: string;
+}>;

package/lib/core/files.js

@@ -0,0 +1,262 @@
+/**
+ * Images on cards, and the markdown files a card links to (a plan, a report).
+ * Their bytes live in the BlobStore: images under `attachments/`, markdown
+ * under `artifacts/`. Bytes are written before the record that names them and
+ * removed after the record is gone, so a failure leaves an unused file, never
+ * a card whose image has no bytes.
+ */
+import { ARTIFACTS } from "./card-paths.js";
+import { DOWNLOAD_TYPE, IMAGE_EXTENSIONS, isShownImage, unsupportedTypeMessage } from "./image-types.js";
+import { fromBase64, fromUtf8, sha256Hex, toBase64, utf8 } from "./bytes.js";
+import { isAgent } from "./context.js";
+import { OrbitError } from "./errors.js";
+import { record, touchTicket } from "./history.js";
+import { ticketOn } from "./tickets.js";
+import { asText } from "./text.js";
+export const MAX_IMAGE_BYTES = 10 * 1024 * 1024;
+export const MAX_MARKDOWN_BYTES = 512 * 1024;
+export { DOWNLOAD_TYPE, isShownImage, unsupportedTypeMessage } from "./image-types.js";
+const startsWith = (bytes, prefix, at = 0) => prefix.every((byte, i) => bytes[at + i] === byte);
+const ascii = (text) => Array.from(text, (ch) => ch.charCodeAt(0));
+/** The image type the bytes themselves say, from their first bytes, or null when they look like none Orbit keeps. */
+export function sniffImage(bytes) {
+    if (startsWith(bytes, [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]))
+        return "image/png";
+    if (startsWith(bytes, [0xff, 0xd8, 0xff]))
+        return "image/jpeg";
+    if (startsWith(bytes, ascii("GIF87a")) || startsWith(bytes, ascii("GIF89a")))
+        return "image/gif";
+    if (startsWith(bytes, ascii("RIFF")) && startsWith(bytes, ascii("WEBP"), 8))
+        return "image/webp";
+    if (startsWith(bytes, ascii("BM")))
+        return "image/bmp";
+    if (startsWith(bytes, ascii("ftyp"), 4) && (startsWith(bytes, ascii("avif"), 8) || startsWith(bytes, ascii("avis"), 8)))
+        return "image/avif";
+    const head = fromUtf8(bytes.subarray(0, 1024)).replace(/^\uFEFF/, "").trimStart();
+    if (head.startsWith("<") && /<svg[\s>]/i.test(fromUtf8(bytes.subarray(0, 64 * 1024))))
+        return "image/svg+xml";
+    return null;
+}
+function imageMime(value) {
+    const mime = (asText(value ?? "").split(";")[0] ?? "").trim().toLowerCase();
+    if (!IMAGE_EXTENSIONS.has(mime))
+        throw new OrbitError("unsupported_attachment_type", { message: unsupportedTypeMessage(mime) });
+    return mime;
+}
+function safeOriginalName(value) {
+    const name = asText(value || "image").replace(/[\0\r\n]/g, "").trim();
+    return name.slice(0, 240) || "image";
+}
+function extensionOf(name) {
+    const base = name.split(/[\\/]/).pop() ?? "";
+    const dot = base.lastIndexOf(".");
+    return dot > 0 ? base.slice(dot).toLowerCase() : "";
+}
+function storedPathFor(ticketId, attachmentId, mime, originalName) {
+    const fromName = extensionOf(originalName);
+    const shown = IMAGE_EXTENSIONS.get(mime);
+    const ext = shown ? (fromName === shown || (mime === "image/jpeg" && fromName === ".jpeg") ? fromName : shown) : ".bin";
+    return `tickets/${ticketId}/${attachmentId}${ext}`;
+}
+/**
+ * The type an imported or migrated image is stored as: the type its bytes
+ * say when that is one Orbit shows, whatever the file claimed; otherwise (an
+ * SVG, bytes no image type matches, or bytes that aren't what they claim)
+ * `DOWNLOAD_TYPE`, so the file is kept but only ever offered as a download.
+ * Without bytes, the type it claims, when Orbit shows that type.
+ */
+export function storedImageType(declared, bytes) {
+    if (bytes) {
+        const sniffed = sniffImage(bytes);
+        return sniffed && isShownImage(sniffed) ? sniffed : DOWNLOAD_TYPE;
+    }
+    const mime = (asText(declared ?? "").split(";")[0] ?? "").trim().toLowerCase();
+    return isShownImage(mime) ? mime : DOWNLOAD_TYPE;
+}
+const blobPath = (attachment) => `attachments/${attachment.stored_path}`;
+async function viewOf(c, attachment) {
+    const size = await c.blobs.size(c.board.id, blobPath(attachment)).catch(() => null);
+    const missing = size === null;
+    return {
+        ...attachment,
+        missing,
+        download_only: !isShownImage(attachment.mime_type),
+        content_url: missing ? null : `/api/tickets/${encodeURIComponent(attachment.ticket_id)}/attachments/${encodeURIComponent(attachment.id)}/content`,
+        filesystem_size_bytes: size
+    };
+}
+export async function listAttachments(c, ticketId) {
+    const attachments = await c.data.read(async (r) => {
+        await ticketOn(r, ticketId);
+        return r.attachments.list(ticketId);
+    });
+    return { attachments: await Promise.all(attachments.map((attachment) => viewOf(c, attachment))) };
+}
+/** An image's bytes and type, and its name. A type Orbit won't show comes back as `DOWNLOAD_TYPE`, with `download_only` set. */
+export async function attachmentContent(c, ticketId, attachmentId) {
+    const attachment = await c.data.read(async (r) => {
+        await ticketOn(r, ticketId);
+        return r.attachments.get(attachmentId);
+    });
+    if (attachment?.ticket_id !== ticketId)
+        throw new OrbitError("attachment_not_found");
+    const bytes = await c.blobs.get(c.board.id, blobPath(attachment));
+    if (!bytes)
+        throw new OrbitError("attachment_file_missing");
+    const shown = isShownImage(attachment.mime_type);
+    return { bytes, mime_type: shown ? attachment.mime_type : DOWNLOAD_TYPE, download_only: !shown, original_name: attachment.original_name };
+}
+/** Adds an image to a card. Its bytes must be the type it says: a PNG named image/jpeg is refused. */
+export async function createAttachment(c, ticketId, input) {
+    await c.data.read((r) => ticketOn(r, ticketId));
+    const mime = imageMime(input.mime_type);
+    const bytes = input.bytes;
+    if (bytes.length === 0)
+        throw new OrbitError("empty_attachment");
+    if (bytes.length > MAX_IMAGE_BYTES)
+        throw new OrbitError("attachment_too_large");
+    if (sniffImage(bytes) !== mime)
+        throw new OrbitError("attachment_type_mismatch", { message: `These bytes aren't ${mime}.` });
+    const originalName = safeOriginalName(input.original_name);
+    const id = c.ids.next();
+    const storedPath = storedPathFor(ticketId, id, mime, originalName);
+    const sha256 = await sha256Hex(bytes);
+    await c.blobs.put(c.board.id, `attachments/${storedPath}`, bytes, { exclusive: true });
+    try {
+        const attachment = await c.data.write(async (w) => {
+            const ticket = await ticketOn(w, ticketId);
+            const at = c.clock.now();
+            const made = { id, ticket_id: ticketId, board_id: c.board.id, original_name: originalName, stored_path: storedPath, mime_type: mime, size_bytes: bytes.length, sha256, created_by: c.actor.name, created_at: at };
+            await w.attachments.insert(made);
+            await w.tickets.update(ticketId, { updated_at: at });
+            await record(w, c, "attachment_created", ticketId, { attachment_id: id, original_name: originalName, mime_type: mime, size_bytes: bytes.length, sha256 });
+            await touchTicket(w, ticket.parent_ticket_id, at);
+            return made;
+        });
+        c.changed(c.board.id);
+        return await viewOf(c, attachment);
+    }
+    catch (error) {
+        await c.blobs.remove(c.board.id, `attachments/${storedPath}`).catch(() => undefined);
+        throw error;
+    }
+}
+export async function deleteAttachment(c, ticketId, attachmentId) {
+    const removed = await c.data.write(async (w) => {
+        const ticket = await ticketOn(w, ticketId);
+        const attachment = await w.attachments.get(attachmentId);
+        if (attachment?.ticket_id !== ticketId)
+            throw new OrbitError("attachment_not_found");
+        await w.attachments.remove(attachmentId);
+        const at = c.clock.now();
+        await w.tickets.update(ticketId, { updated_at: at });
+        await record(w, c, "attachment_deleted", ticketId, { attachment_id: attachmentId, original_name: attachment.original_name });
+        await touchTicket(w, ticket.parent_ticket_id, at);
+        return attachment;
+    });
+    await c.blobs.remove(c.board.id, blobPath(removed)).catch(() => undefined);
+    c.changed(c.board.id);
+    return { ok: true, deleted_id: attachmentId };
+}
+/** An image as an export carries it: its bytes as base64 when asked for and present. */
+export async function exportedAttachment(c, attachment, includeBytes) {
+    const view = await viewOf(c, attachment);
+    if (!includeBytes || view.missing)
+        return { ...view, data_base64: null, included: false };
+    const bytes = await c.blobs.get(c.board.id, blobPath(attachment));
+    if (!bytes)
+        return { ...view, missing: true, content_url: null, filesystem_size_bytes: null, data_base64: null, included: false };
+    return { ...view, data_base64: toBase64(bytes), included: true, missing: false };
+}
+/**
+ * An image an import brings, its bytes stored when it carries them; the
+ * record to write. Its bytes are sniffed as an upload's are, and stored under
+ * `storedImageType`: an SVG or a file that isn't what it says is kept as a
+ * download only.
+ */
+export async function importedAttachment(c, row, ticketId) {
+    const id = typeof row.id === "string" && row.id ? row.id : c.ids.next();
+    const bytes = typeof row.data_base64 === "string" && row.data_base64 ? fromBase64(row.data_base64) : null;
+    if (bytes && bytes.length > MAX_IMAGE_BYTES)
+        throw new OrbitError("attachment_too_large");
+    const mime = storedImageType(row.mime_type || "image/png", bytes);
+    const originalName = safeOriginalName(row.original_name);
+    const storedPath = storedPathFor(ticketId, id, mime, originalName);
+    let size = Number(row.size_bytes || 0);
+    let sha = asText(row.sha256 || "");
+    if (bytes) {
+        size = bytes.length;
+        sha = await sha256Hex(bytes);
+        await c.blobs.put(c.board.id, `attachments/${storedPath}`, bytes);
+    }
+    return {
+        id,
+        ticket_id: ticketId,
+        board_id: c.board.id,
+        original_name: originalName,
+        stored_path: storedPath,
+        mime_type: mime,
+        size_bytes: size,
+        sha256: sha,
+        created_by: typeof row.created_by === "string" && row.created_by ? row.created_by : "import",
+        created_at: typeof row.created_at === "string" && row.created_at ? row.created_at : c.clock.now()
+    };
+}
+// Markdown artifacts
+const MARKDOWN_EXTENSIONS = new Set([".md", ".markdown", ".txt"]);
+function cleanArtifactPath(value) {
+    const text = asText(value ?? "").trim();
+    if (!text || text.includes("\0"))
+        throw new OrbitError("artifact_path_required");
+    return text.replace(/\\/g, "/");
+}
+function markdownName(value) {
+    const raw = cleanArtifactPath(value || "artifact.md");
+    const name = (raw.split("/").pop() ?? "").replace(/[^A-Za-z0-9._-]+/g, "-") || "artifact.md";
+    if (!MARKDOWN_EXTENSIONS.has(extensionOf(name)))
+        throw new OrbitError("unsupported_artifact_type");
+    return name;
+}
+/** Saves markdown for a card (a plan, a report) beside the board: `tickets/<card id>/<name>.md`. */
+export async function writeArtifact(c, ticketId, input) {
+    const ticket = await c.data.read((r) => ticketOn(r, ticketId));
+    const bytes = utf8(asText(input.content ?? ""));
+    if (bytes.length > MAX_MARKDOWN_BYTES)
+        throw new OrbitError("artifact_too_large");
+    const path = `tickets/${ticket.id}/${markdownName(input.filename || input.path || "artifact.md")}`;
+    await c.blobs.put(c.board.id, ARTIFACTS + path, bytes);
+    return withLocation(c, { ticket_id: ticket.id, path, size_bytes: bytes.length });
+}
+function withLocation(c, answer) {
+    if (isAgent(c.actor) || !c.blobs.location)
+        return answer;
+    return { ...answer, absolute_path: c.blobs.location(c.board.id, ARTIFACTS + answer.path) };
+}
+/** The path inside the board's artifacts that `requested` names: relative to them, or this machine's full path to one. */
+function artifactPath(c, requested) {
+    let path = requested;
+    const root = c.blobs.location?.(c.board.id, ARTIFACTS.slice(0, -1));
+    if (root && (path === root || path.startsWith(`${root}/`)))
+        path = path.slice(root.length + 1);
+    else if (/^([a-z]:)?\//i.test(path))
+        throw new OrbitError("artifact_path_outside_allowed_roots");
+    path = path.replace(/^(\.\/)+/, "");
+    if (path.startsWith(ARTIFACTS))
+        path = path.slice(ARTIFACTS.length);
+    if (!path || path.split("/").some((segment) => segment === ".." || segment === "." || segment === ""))
+        throw new OrbitError("artifact_path_outside_allowed_roots");
+    return path;
+}
+/** Reads a markdown file in the board's artifacts. */
+export async function readArtifact(c, ticketId, requested) {
+    const ticket = await c.data.read((r) => ticketOn(r, ticketId));
+    const path = artifactPath(c, cleanArtifactPath(requested));
+    if (!MARKDOWN_EXTENSIONS.has(extensionOf(path)))
+        throw new OrbitError("unsupported_artifact_type");
+    const bytes = await c.blobs.get(c.board.id, ARTIFACTS + path);
+    if (!bytes)
+        throw new OrbitError("artifact_not_found");
+    if (bytes.length > MAX_MARKDOWN_BYTES)
+        throw new OrbitError("artifact_too_large");
+    return { ...withLocation(c, { ticket_id: ticket.id, path, size_bytes: bytes.length }), content: fromUtf8(bytes) };
+}

package/lib/core/history.d.ts

@@ -0,0 +1,20 @@
+/**
+ * History and search, as every write keeps them: each change appends an event
+ * (the live stream, an agent's `changes` and the quick menu's sessions read
+ * them), and each change to a card's text replaces its search document.
+ */
+import type { Ctx } from "./context.ts";
+import type { Comment, Id, OrbitEvent, Ticket } from "./model.ts";
+import type { BoardWriter, SearchDocument } from "../store/types.ts";
+/** Appends an event by the acting actor, now. */
+export declare function record(w: BoardWriter, c: Ctx, type: string, ticketId: Id | null, body: Record<string, unknown>): Promise<OrbitEvent>;
+/**
+ * A card's search document: its text, and the comments agents may read. A
+ * comment hidden from agents is never given to the index, so no search can
+ * find it.
+ */
+export declare function searchDocument(ticket: Ticket, comments: readonly Comment[]): SearchDocument;
+/** Rebuilds one card's search document from what the write sees. */
+export declare function reindex(w: BoardWriter, ticketId: Id): Promise<void>;
+/** Moves a card's `updated_at` without an event: an epic follows its sub-cards' changes, so it sorts near them. */
+export declare function touchTicket(w: BoardWriter, ticketId: Id | null | undefined, at: string): Promise<void>;

package/lib/core/history.js

@@ -0,0 +1,53 @@
+/**
+ * History and search, as every write keeps them: each change appends an event
+ * (the live stream, an agent's `changes` and the quick menu's sessions read
+ * them), and each change to a card's text replaces its search document.
+ */
+import { isOrbitError } from "./errors.js";
+/** Appends an event by the acting actor, now. */
+export async function record(w, c, type, ticketId, body) {
+    const event = {
+        id: c.ids.next(),
+        ticket_id: ticketId,
+        actor: c.actor.name,
+        type,
+        body_json: JSON.stringify(body),
+        created_at: c.clock.now()
+    };
+    await w.events.append(event);
+    return event;
+}
+/**
+ * A card's search document: its text, and the comments agents may read. A
+ * comment hidden from agents is never given to the index, so no search can
+ * find it.
+ */
+export function searchDocument(ticket, comments) {
+    return {
+        title: ticket.title,
+        description: ticket.description,
+        type: ticket.type,
+        details: [ticket.ai_plan, ticket.implementation_summary, ticket.implementation_updates].filter(Boolean).join("\n"),
+        comments: comments.filter((comment) => !comment.omitted_for_ai).map((comment) => comment.body).join("\n")
+    };
+}
+/** Rebuilds one card's search document from what the write sees. */
+export async function reindex(w, ticketId) {
+    const ticket = await w.tickets.get(ticketId);
+    if (!ticket)
+        return;
+    await w.search.index(ticketId, searchDocument(ticket, await w.comments.list(ticketId)));
+}
+/** Moves a card's `updated_at` without an event: an epic follows its sub-cards' changes, so it sorts near them. */
+export async function touchTicket(w, ticketId, at) {
+    if (!ticketId)
+        return;
+    try {
+        await w.tickets.update(ticketId, { updated_at: at });
+    }
+    catch (error) {
+        // An epic deleted since keeps its id on its sub-cards; there's nothing to move.
+        if (!(isOrbitError(error) && error.code === "ticket_not_found"))
+            throw error;
+    }
+}

package/lib/core/image-types.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Which attachments Orbit shows as images, apart from the rest of the core
+ * so a client (the HTTP client, an object URL) can ask without loading it.
+ */
+/**
+ * The image types Orbit shows: raster formats a browser draws without running
+ * anything. An SVG can carry script, so Orbit neither takes a new one nor
+ * shows an old one; see `storedImageType` in `files.ts`.
+ */
+export declare const IMAGE_EXTENSIONS: Map<string, string>;
+/** What an upload of another type is told, naming the type it sent (`mime`, already lowercased, without parameters). */
+export declare function unsupportedTypeMessage(mime: string): string;
+/** What a file Orbit won't show is stored and served as: bytes to download, never a page. */
+export declare const DOWNLOAD_TYPE = "application/octet-stream";
+/** True for a type Orbit shows as an image; any other attachment is a file to download. */
+export declare function isShownImage(mime: string): boolean;

package/lib/core/image-types.js

@@ -0,0 +1,36 @@
+/**
+ * Which attachments Orbit shows as images, apart from the rest of the core
+ * so a client (the HTTP client, an object URL) can ask without loading it.
+ */
+/**
+ * The image types Orbit shows: raster formats a browser draws without running
+ * anything. An SVG can carry script, so Orbit neither takes a new one nor
+ * shows an old one; see `storedImageType` in `files.ts`.
+ */
+export const IMAGE_EXTENSIONS = new Map([
+    ["image/png", ".png"],
+    ["image/jpeg", ".jpg"],
+    ["image/gif", ".gif"],
+    ["image/webp", ".webp"],
+    ["image/avif", ".avif"]
+]);
+const TYPE_NAMES = new Map([
+    ["image/svg+xml", "SVG"],
+    ["image/bmp", "BMP"],
+    ["image/x-ms-bmp", "BMP"],
+    ["image/tiff", "TIFF"],
+    ["image/heic", "HEIC"],
+    ["image/x-icon", "ICO"],
+    ["image/vnd.microsoft.icon", "ICO"]
+]);
+/** What an upload of another type is told, naming the type it sent (`mime`, already lowercased, without parameters). */
+export function unsupportedTypeMessage(mime) {
+    const named = TYPE_NAMES.get(mime) ?? (/^[a-z0-9][a-z0-9.+-]{0,60}\/[a-z0-9][a-z0-9.+-]{0,60}$/.test(mime) ? mime : mime ? "that type" : "a file without a type");
+    return `Orbit takes PNG, JPEG, GIF, WebP and AVIF images, not ${named}.`;
+}
+/** What a file Orbit won't show is stored and served as: bytes to download, never a page. */
+export const DOWNLOAD_TYPE = "application/octet-stream";
+/** True for a type Orbit shows as an image; any other attachment is a file to download. */
+export function isShownImage(mime) {
+    return IMAGE_EXTENSIONS.has(mime);
+}