@starlove/orbit 1.4.1 → 2.0.0

package/lib/core/text.js

@@ -0,0 +1,113 @@
+/**
+ * The small rules every use case shares for what people and agents send:
+ * names on one line, slugs, priorities and types read the way the API has
+ * always read them, each refusal with its error code.
+ */
+import { OrbitError } from "./errors.js";
+/**
+ * What a field holds as text: a string as it is, a number or boolean written
+ * out, anything else (an object, null, nothing) as "". Input is never
+ * stringified as "[object Object]".
+ */
+export function asText(value) {
+    if (typeof value === "string")
+        return value;
+    if (typeof value === "number" || typeof value === "boolean" || typeof value === "bigint")
+        return String(value);
+    return "";
+}
+/** A board slug: lowercase letters, digits and single dashes, at most 80 characters. */
+export function slugify(value) {
+    return String(value)
+        .toLowerCase()
+        .trim()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, 80);
+}
+/** True for a slug slugify leaves as it is. */
+export function isSlug(value) {
+    return typeof value === "string" && value !== "" && slugify(value) === value;
+}
+/** A name as one clean line: line breaks and control characters become spaces. */
+export function cleanName(value) {
+    return asText(value ?? "")
+        .replace(/[\u0000-\u001f\u007f-\u009f\u2028\u2029]+/g, " ")
+        .replace(/\s+/g, " ")
+        .trim();
+}
+/** A string with something in it, trimmed; otherwise `missing_<field>`. */
+export function requiredString(value, field) {
+    if (typeof value !== "string" || value.trim() === "")
+        throw new OrbitError(`missing_${field}`);
+    return value.trim();
+}
+/** A lane's name: required, and one clean line. */
+export function laneNameOf(value) {
+    const name = cleanName(requiredString(value, "name"));
+    if (!name)
+        throw new OrbitError("missing_name");
+    return name;
+}
+/** 0 to 4, rounded; anything unreadable is med (2). */
+export function normalizePriority(value) {
+    const number = Number(value ?? 2);
+    if (!Number.isFinite(number))
+        return 2;
+    return Math.max(0, Math.min(4, Math.round(number)));
+}
+const TICKET_TYPES = ["epic", "feature", "task", "bug"];
+export function normalizeTicketType(value) {
+    const type = asText(value || "task").toLowerCase().trim();
+    if (!TICKET_TYPES.includes(type))
+        throw new OrbitError("invalid_ticket_type");
+    return type;
+}
+export function normalizeEntryType(value) {
+    const type = asText(value || "").toLowerCase().trim();
+    if (type !== "decision" && type !== "lesson")
+        throw new OrbitError("invalid_project_entry_type");
+    return type;
+}
+const ROLES = ["ai_ready", "in_progress", "review", "done"];
+/** A lane's role in the agent flow, or null for none. */
+export function normalizeStateRole(value) {
+    if (value === null || value === undefined || value === "")
+        return null;
+    const role = asText(value).toLowerCase().trim();
+    if (!ROLES.includes(role))
+        throw new OrbitError("invalid_state_role");
+    return role;
+}
+/** `existing`, then a blank line, then `note`; just `existing` when the note is empty. */
+export function appendNote(existing, note) {
+    const text = asText(note ?? "").trim();
+    if (!text)
+        return existing;
+    return [existing.trim(), text].filter(Boolean).join("\n\n");
+}
+/** At most `max` characters; `max` 0 means no cap. */
+export function cap(value, max) {
+    const text = asText(value ?? "");
+    return max && text.length > max ? text.slice(0, max) : text;
+}
+/** A whole number above zero, else `fallback`. */
+export function positiveInt(value, fallback) {
+    const n = Number(value);
+    return Number.isInteger(n) && n > 0 ? n : fallback;
+}
+/** A whole number from zero, else `fallback`. */
+export function nonNegativeInt(value, fallback) {
+    const n = Number(value);
+    return Number.isInteger(n) && n >= 0 ? n : fallback;
+}
+/** An optional string field, trimmed; "" when absent. */
+export function optionalString(value) {
+    if (value === undefined || value === null)
+        return "";
+    return asText(value).trim();
+}
+/** A field that is a string when given, else "" (the API's `body.x || ""`). */
+export function textOr(value, fallback = "") {
+    return typeof value === "string" && value !== "" ? value : value === undefined || value === null || value === "" ? fallback : asText(value);
+}

package/lib/core/tickets.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Cards and their comments: making, changing, archiving, restoring and
+ * deleting a card, and the discussion on it. Every change records an event,
+ * keeps the card's search document current and moves its epic's
+ * `updated_at`, so the epic sorts near its sub-cards' work.
+ */
+import type { BoardCtx } from "./context.ts";
+import type { Comment, Id, OrbitEvent, Ticket, TicketType } from "./model.ts";
+import type { TicketView } from "./views.ts";
+import type { BoardReader } from "../store/types.ts";
+/** The card's epic, checked: on this board, not itself or its own descendant, and the card isn't an epic. */
+export declare function checkParent(r: BoardReader, value: unknown, type: TicketType, ticketId?: string): Promise<Id | null>;
+export interface NewTicketInput {
+    board_id?: unknown;
+    title?: unknown;
+    description?: unknown;
+    type?: unknown;
+    parent_ticket_id?: unknown;
+    ai_plan?: unknown;
+    plan_artifact_path?: unknown;
+    implementation_summary?: unknown;
+    implementation_artifact_path?: unknown;
+    implementation_updates?: unknown;
+    nebula_url?: unknown;
+    state_id?: unknown;
+    priority?: unknown;
+    labels?: unknown;
+}
+/** Makes a card, in its lane or the board's default lane. */
+export declare function createTicket(c: BoardCtx, input: NewTicketInput): Promise<TicketView>;
+declare const EDITABLE: readonly ["title", "description", "type", "parent_ticket_id", "ai_plan", "plan_artifact_path", "implementation_summary", "implementation_artifact_path", "implementation_updates", "nebula_url", "state_id", "priority"];
+export type TicketUpdate = Partial<Record<(typeof EDITABLE)[number] | "labels", unknown>>;
+/** Reads a card on this board, or `ticket_not_found`. */
+export declare function ticketOn(r: BoardReader, ticketId: Id): Promise<Ticket>;
+/**
+ * Changes a card's fields; `labels` (names) replaces its labels. Moving a card
+ * into a done lane deletes the relations that made it a blocker: the relation
+ * is the record of what still blocks.
+ */
+export declare function updateTicket(c: BoardCtx, ticketId: Id, input: TicketUpdate): Promise<TicketView>;
+/** Puts a card in the archive: off the board, out of search and of agents' work, its data kept. */
+export declare function archiveTicket(c: BoardCtx, ticketId: Id): Promise<TicketView>;
+export declare function restoreTicket(c: BoardCtx, ticketId: Id): Promise<TicketView>;
+/** Deletes an archived card for good, with its comments, links and images; its events stay. */
+export declare function deleteTicket(c: BoardCtx, ticketId: Id): Promise<{
+    ok: true;
+    deleted_id: Id;
+}>;
+/** Adds a comment to a card: a person's, or an agent's note. */
+export declare function createComment(c: BoardCtx, ticketId: Id, input: {
+    body?: unknown;
+    author?: unknown;
+    kind?: unknown;
+}): Promise<Comment>;
+/** Hides a comment from agents, or shows it again: it leaves (or rejoins) everything an agent can read or search. */
+export declare function setCommentHidden(c: BoardCtx, ticketId: Id, commentId: Id, input: {
+    omitted_for_ai?: unknown;
+    omittedForAi?: unknown;
+}): Promise<Comment>;
+/** One event of a card's history, its data parsed as `body`. */
+export type HistoryEntry = OrbitEvent & {
+    body: unknown;
+};
+/**
+ * A card's moves between lanes, oldest first: moves, takes that moved it (into
+ * In Progress), asks and finishes, each event's data parsed as `body`.
+ */
+export declare function ticketHistory(c: BoardCtx, ticketId: Id): Promise<HistoryEntry[]>;
+export {};

package/lib/core/tickets.js

@@ -0,0 +1,311 @@
+/**
+ * Cards and their comments: making, changing, archiving, restoring and
+ * deleting a card, and the discussion on it. Every change records an event,
+ * keeps the card's search document current and moves its epic's
+ * `updated_at`, so the epic sorts near its sub-cards' work.
+ */
+import { cardLinkFromInput } from "./card-paths.js";
+import { OrbitError } from "./errors.js";
+import { record, reindex, searchDocument, touchTicket } from "./history.js";
+import { normalizeNebulaUrl } from "./nebula-link.js";
+import { normalizePriority, normalizeTicketType, requiredString, textOr, asText } from "./text.js";
+import { Lanes, ticketView } from "./views.js";
+const LABEL_COLOR = "#64748b";
+/** The label with this name, made when the board has none. */
+async function ensureLabel(w, c, labels, name) {
+    const existing = labels.find((label) => label.name === name);
+    if (existing)
+        return existing;
+    const label = { id: c.ids.next(), board_id: c.board.id, name, color: LABEL_COLOR, created_at: c.clock.now() };
+    await w.labels.insert(label);
+    labels.push(label);
+    return label;
+}
+/** The card's epic, checked: on this board, not itself or its own descendant, and the card isn't an epic. */
+export async function checkParent(r, value, type, ticketId = "") {
+    if (value === undefined || value === null || value === "")
+        return null;
+    if (type === "epic")
+        throw new OrbitError("epic_cannot_have_parent");
+    if (value === ticketId)
+        throw new OrbitError("ticket_cannot_parent_itself");
+    const parent = await r.tickets.get(asText(value));
+    if (!parent)
+        throw new OrbitError("invalid_parent_ticket");
+    // The whole chain up, not one hop: A under B under C under A is a cycle too.
+    const seen = new Set();
+    let ancestor = parent;
+    let guard = 0;
+    while (ancestor) {
+        if (ticketId && ancestor.id === ticketId)
+            throw new OrbitError("ticket_parent_cycle");
+        const next = ancestor.parent_ticket_id;
+        if (!next || seen.has(next) || guard++ > 1000)
+            break;
+        seen.add(next);
+        ancestor = await r.tickets.get(next);
+    }
+    return parent.id;
+}
+/** Makes a card, in its lane or the board's default lane. */
+export async function createTicket(c, input) {
+    if (input.board_id && input.board_id !== c.board.id)
+        throw new OrbitError("board_id_mismatch");
+    const title = requiredString(input.title, "title");
+    const view = await c.data.write(async (w) => {
+        const lanes = await Lanes.of(w);
+        const stateId = input.state_id ? asText(input.state_id) : (lanes.list.find((s) => s.is_default) ?? lanes.list[0])?.id;
+        if (!stateId)
+            throw new OrbitError("board_has_no_states");
+        if (!lanes.get(stateId))
+            throw new OrbitError("invalid_state");
+        const type = normalizeTicketType(input.type || (input.parent_ticket_id ? "feature" : "task"));
+        const parentId = await checkParent(w, input.parent_ticket_id, type);
+        const nebulaUrl = normalizeNebulaUrl(input.nebula_url);
+        const at = c.clock.now();
+        const ticket = await w.tickets.create({
+            id: c.ids.next(),
+            board_id: c.board.id,
+            title,
+            description: textOr(input.description),
+            type,
+            parent_ticket_id: parentId,
+            ai_plan: textOr(input.ai_plan),
+            plan_artifact_path: cardLinkFromInput(c, c.board.id, input.plan_artifact_path),
+            implementation_summary: textOr(input.implementation_summary),
+            implementation_artifact_path: cardLinkFromInput(c, c.board.id, input.implementation_artifact_path),
+            implementation_updates: textOr(input.implementation_updates),
+            nebula_url: nebulaUrl,
+            state_id: stateId,
+            priority: normalizePriority(input.priority),
+            created_by: c.actor.name,
+            created_at: at,
+            updated_at: at,
+            archived_at: null
+        });
+        const names = Array.isArray(input.labels) ? input.labels : [];
+        if (names.length) {
+            const labels = await w.labels.list();
+            for (const name of names) {
+                const label = await ensureLabel(w, c, labels, requiredString(name, "label"));
+                await w.ticketLabels.add(ticket.id, label.id);
+            }
+        }
+        await record(w, c, "ticket_created", ticket.id, { title, type, parent_ticket_id: parentId });
+        await w.search.index(ticket.id, searchDocument(ticket, []));
+        await touchTicket(w, parentId, at);
+        return ticketView(ticket, lanes, c.board);
+    });
+    c.changed(c.board.id);
+    return view;
+}
+const EDITABLE = [
+    "title",
+    "description",
+    "type",
+    "parent_ticket_id",
+    "ai_plan",
+    "plan_artifact_path",
+    "implementation_summary",
+    "implementation_artifact_path",
+    "implementation_updates",
+    "nebula_url",
+    "state_id",
+    "priority"
+];
+/** Reads a card on this board, or `ticket_not_found`. */
+export async function ticketOn(r, ticketId) {
+    const ticket = await r.tickets.get(ticketId);
+    if (!ticket)
+        throw new OrbitError("ticket_not_found");
+    return ticket;
+}
+/**
+ * Changes a card's fields; `labels` (names) replaces its labels. Moving a card
+ * into a done lane deletes the relations that made it a blocker: the relation
+ * is the record of what still blocks.
+ */
+export async function updateTicket(c, ticketId, input) {
+    const view = await c.data.write(async (w) => {
+        const before = await ticketOn(w, ticketId);
+        const lanes = await Lanes.of(w);
+        const type = input.type !== undefined ? normalizeTicketType(input.type) : before.type;
+        // Each field as it will be stored; the same values drive the event, so history shows what was saved.
+        const applied = {};
+        for (const field of EDITABLE) {
+            const value = input[field];
+            if (value === undefined)
+                continue;
+            if (field === "type")
+                applied.type = type;
+            else if (field === "title")
+                applied.title = requiredString(value, "title");
+            else if (field === "priority")
+                applied.priority = normalizePriority(value);
+            else if (field === "nebula_url")
+                applied.nebula_url = normalizeNebulaUrl(value);
+            else if (field === "parent_ticket_id")
+                applied.parent_ticket_id = await checkParent(w, value, type, before.id);
+            else if (field === "plan_artifact_path" || field === "implementation_artifact_path")
+                applied[field] = cardLinkFromInput(c, c.board.id, value);
+            else
+                applied[field] = value;
+        }
+        // An epic has no parent, said or not.
+        if (type === "epic" && applied.parent_ticket_id === undefined)
+            applied.parent_ticket_id = null;
+        const labelNames = Array.isArray(input.labels) ? input.labels : null;
+        const fields = Object.keys(applied);
+        if (!fields.length && !labelNames)
+            return ticketView(before, lanes, c.board);
+        if (applied.state_id && !lanes.get(asText(applied.state_id)))
+            throw new OrbitError("invalid_state");
+        const at = c.clock.now();
+        let after = before;
+        if (fields.length)
+            after = await w.tickets.update(ticketId, { ...applied, updated_at: at });
+        if (labelNames) {
+            const labels = await w.labels.list();
+            const ids = [];
+            for (const raw of labelNames) {
+                const name = String(raw ?? "").trim().replace(/\s+/g, " ");
+                if (!name)
+                    continue;
+                const label = await ensureLabel(w, c, labels, name);
+                if (!ids.includes(label.id))
+                    ids.push(label.id);
+            }
+            await w.ticketLabels.set(ticketId, ids);
+            if (!fields.length)
+                after = await w.tickets.update(ticketId, { updated_at: at });
+        }
+        if (before.state_id !== after.state_id) {
+            if (lanes.roleOf(after) === "done" && lanes.roleOf(before) !== "done") {
+                for (const relation of await w.relations.list(ticketId)) {
+                    const blocker = (relation.source_ticket_id === ticketId && relation.type === "blocks") || (relation.target_ticket_id === ticketId && relation.type === "blocked_by");
+                    if (blocker)
+                        await w.relations.remove(relation.id);
+                }
+            }
+            await record(w, c, "state_changed", ticketId, { from: lanes.nameOf(before), to: lanes.nameOf(after), actor_type: c.actor.type, actor_id: c.actor.id });
+        }
+        else {
+            const body = { ...applied };
+            if (labelNames)
+                body.labels = labelNames;
+            if (Object.keys(body).length)
+                await record(w, c, "ticket_updated", ticketId, body);
+        }
+        await reindex(w, ticketId);
+        // Both epics changed on a move between them: one lost a sub-card, the other gained one.
+        await touchTicket(w, before.parent_ticket_id, at);
+        if (after.parent_ticket_id && after.parent_ticket_id !== before.parent_ticket_id)
+            await touchTicket(w, after.parent_ticket_id, at);
+        return ticketView(after, lanes, c.board);
+    });
+    c.changed(c.board.id);
+    return view;
+}
+async function setArchived(c, ticketId, archive) {
+    const { view, changed } = await c.data.write(async (w) => {
+        const ticket = await ticketOn(w, ticketId);
+        const lanes = await Lanes.of(w);
+        if (Boolean(ticket.archived_at) === archive)
+            return { view: ticketView(ticket, lanes, c.board), changed: false };
+        const at = c.clock.now();
+        const after = await w.tickets.update(ticketId, { archived_at: archive ? at : null, updated_at: at });
+        await record(w, c, archive ? "ticket_archived" : "ticket_restored", ticketId, { title: ticket.title });
+        await touchTicket(w, ticket.parent_ticket_id, at);
+        return { view: ticketView(after, lanes, c.board), changed: true };
+    });
+    if (changed)
+        c.changed(c.board.id);
+    return view;
+}
+/** Puts a card in the archive: off the board, out of search and of agents' work, its data kept. */
+export function archiveTicket(c, ticketId) {
+    return setArchived(c, ticketId, true);
+}
+export function restoreTicket(c, ticketId) {
+    return setArchived(c, ticketId, false);
+}
+/** Deletes an archived card for good, with its comments, links and images; its events stay. */
+export async function deleteTicket(c, ticketId) {
+    const paths = await c.data.write(async (w) => {
+        const ticket = await ticketOn(w, ticketId);
+        if (!ticket.archived_at)
+            throw new OrbitError("ticket_not_archived");
+        const images = await w.attachments.list(ticketId);
+        await record(w, c, "ticket_deleted", ticketId, { title: ticket.title, type: ticket.type, board_id: c.board.id });
+        await w.tickets.remove(ticketId);
+        await touchTicket(w, ticket.parent_ticket_id, c.clock.now());
+        return images.map((image) => `attachments/${image.stored_path}`);
+    });
+    for (const path of paths)
+        await c.blobs.remove(c.board.id, path);
+    c.changed(c.board.id);
+    return { ok: true, deleted_id: ticketId };
+}
+/** Adds a comment to a card: a person's, or an agent's note. */
+export async function createComment(c, ticketId, input) {
+    const comment = await c.data.write(async (w) => {
+        const ticket = await ticketOn(w, ticketId);
+        const body = requiredString(input.body, "body");
+        const at = c.clock.now();
+        const made = {
+            id: c.ids.next(),
+            ticket_id: ticketId,
+            author: typeof input.author === "string" && input.author ? input.author : c.actor.name,
+            kind: typeof input.kind === "string" && input.kind ? input.kind : c.actor.type === "agent" ? "agent_note" : "human_comment",
+            body,
+            omitted_for_ai: 0,
+            created_at: at
+        };
+        await w.comments.insert(made);
+        await w.tickets.update(ticketId, { updated_at: at });
+        await record(w, c, "comment_created", ticketId, { kind: made.kind });
+        await reindex(w, ticketId);
+        await touchTicket(w, ticket.parent_ticket_id, at);
+        return made;
+    });
+    c.changed(c.board.id);
+    return comment;
+}
+/** Hides a comment from agents, or shows it again: it leaves (or rejoins) everything an agent can read or search. */
+export async function setCommentHidden(c, ticketId, commentId, input) {
+    const comment = await c.data.write(async (w) => {
+        const ticket = await ticketOn(w, ticketId);
+        const existing = await w.comments.get(commentId);
+        if (existing?.ticket_id !== ticketId)
+            throw new OrbitError("comment_not_found");
+        const hidden = input.omitted_for_ai ?? input.omittedForAi;
+        if (typeof hidden !== "boolean")
+            throw new OrbitError("omitted_for_ai_required");
+        const at = c.clock.now();
+        const after = await w.comments.update(commentId, { omitted_for_ai: hidden ? 1 : 0 });
+        await w.tickets.update(ticketId, { updated_at: at });
+        await record(w, c, "comment_ai_omission_changed", ticketId, { comment_id: commentId, omitted_for_ai: hidden });
+        await reindex(w, ticketId);
+        await touchTicket(w, ticket.parent_ticket_id, at);
+        return after;
+    });
+    c.changed(c.board.id);
+    return comment;
+}
+/**
+ * A card's moves between lanes, oldest first: moves, takes that moved it (into
+ * In Progress), asks and finishes, each event's data parsed as `body`.
+ */
+export async function ticketHistory(c, ticketId) {
+    return c.data.read(async (r) => {
+        await ticketOn(r, ticketId);
+        const events = await r.events.list({ ticketId, types: ["state_changed", "agent_claimed", "checkpoint_requested", "agent_completed"] });
+        const entries = events.map((event) => ({ ...event, body: JSON.parse(event.body_json) }));
+        // A take that left the card where it was (a takeover in place) moved nothing.
+        return entries.filter((entry) => entry.type !== "agent_claimed" || movedLanes(entry.body));
+    });
+}
+function movedLanes(body) {
+    const { from, to } = (body ?? {});
+    return typeof to === "string" && to !== "" && from !== to;
+}

package/lib/core/trello.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Trello's board export, read as an Orbit export: lists become lanes (roles
+ * guessed from their names), cards become cards with their checklists,
+ * links and due dates in the description, labels and comments come along.
+ * Pure: it only reshapes the data it is given.
+ */
+import type { Clock, Ids } from "./context.ts";
+type Raw = Record<string, unknown>;
+export declare function looksLikeTrello(value: unknown): value is Raw;
+/** A Trello export as an Orbit export, for the board `target` names (or one named from Trello's). */
+export declare function trelloToSnapshot(trello: Raw, target: {
+    id?: string;
+    slug?: string;
+    repo_url?: string;
+    default_branch?: string;
+}, clock: Clock, ids: Ids): Raw;
+export {};