@tomradex/domain 0.0.0-stage → 0.2.16

package/dist/schema.js

@@ -0,0 +1,56 @@
+import { z } from "zod";
+export const itemKindSchema = z.enum(["ticket", "epic"]);
+export const workTypeSchema = z.enum(["coding", "general"]);
+export const itemStatusSchema = z.enum(["backlog", "todo", "doing", "verifying", "done", "cancelled"]);
+// Agents read a bare 0–4 as "1 is most urgent" unless told otherwise.
+export const prioritySchema = z.literal([0, 1, 2, 3, 4]).describe("0 none, 1 low, 2 medium, 3 high, 4 urgent — higher is more urgent");
+export const listItemsFilterSchema = z.object({
+    projectId: z.string().optional(),
+    boardId: z.string().optional(),
+    status: itemStatusSchema.optional(),
+    kind: itemKindSchema.optional(),
+    workType: workTypeSchema.optional(),
+    priority: prioritySchema.optional(),
+    label: z.string().optional(),
+    parentId: z.string().nullable().optional().describe("The parent item's id or key, e.g. TOM-12; null for none"),
+    search: z.string().optional()
+});
+export const fieldValueSchema = z.union([z.string(), z.number()]);
+/** A key set to null clears the value. */
+export const fieldsPatchSchema = z.record(z.string(), fieldValueSchema.nullable());
+export const filterClauseSchema = z.object({
+    field: z.string(),
+    op: z.enum(["in", "not-in", "contains", "gte", "lte"]),
+    values: z.array(fieldValueSchema.nullable())
+});
+export const sortKeySchema = z.object({ field: z.string(), dir: z.enum(["asc", "desc"]) });
+export const createItemSchema = z.object({
+    playbookId: z.string().min(1).nullable().optional(),
+    title: z.string().min(1),
+    body: z.string().nullable().optional(),
+    kind: itemKindSchema.optional(),
+    workType: workTypeSchema.optional(),
+    status: itemStatusSchema.optional(),
+    priority: prioritySchema.optional(),
+    labels: z.array(z.string()).optional(),
+    parentId: z.string().nullable().optional().describe("The parent item's id or key, e.g. TOM-12; null for none"),
+    projectId: z.string().optional(),
+    boardId: z.string().optional(),
+    fields: fieldsPatchSchema.optional()
+});
+export const patchSchema = z.object({
+    playbookId: z.string().min(1).nullable().optional(),
+    title: z.string().optional(),
+    body: z.string().nullable().optional(),
+    kind: itemKindSchema.optional(),
+    workType: workTypeSchema.optional(),
+    status: itemStatusSchema.optional(),
+    priority: prioritySchema.optional(),
+    labels: z.array(z.string()).optional(),
+    blocks: z.array(z.string()).optional().describe("Ids or keys of the items this one blocks"),
+    parentId: z.string().nullable().optional().describe("The parent item's id or key, e.g. TOM-12; null for none"),
+    rank: z.number().optional(),
+    boardId: z.string().optional().describe("Move the item to this workstream (list_workstreams)"),
+    fields: fieldsPatchSchema.optional()
+});
+//# sourceMappingURL=schema.js.map

package/dist/types.d.ts

@@ -0,0 +1,311 @@
+import type { Layout, ViewQuery } from "./query.js";
+import type { TicketEvidence } from "./delivery.js";
+export type ItemKind = "ticket" | "epic";
+export type WorkType = "coding" | "general";
+export type ItemStatus = "backlog" | "todo" | "doing" | "verifying" | "done" | "cancelled";
+export declare const ITEM_STATUSES: readonly ItemStatus[];
+/** 0 None · 1 Low · 2 Medium (default) · 3 High · 4 Urgent. */
+export type Priority = 0 | 1 | 2 | 3 | 4;
+export declare const DEFAULT_PRIORITY: Priority;
+/** Who wrote a change. Human edits are 'human'; every agent or plugin write is 'ai:<source>'. */
+/** Who wrote: a person, a model, or a sync reading evidence in from outside (`sync:git` — a merge moved the ticket). */
+export type Author = "human" | `ai:${string}` | `sync:${string}`;
+/** Derived from updatedBy + humanLocked; never stored. */
+export type Provenance = "human" | "ai" | "sync" | "locked";
+/** A stored custom-field value. Dates are ISO `YYYY-MM-DD`; selects hold the option id. */
+export type FieldValue = string | number;
+export interface Item {
+    evidence: TicketEvidence;
+    id: string;
+    projectId: string;
+    /** The board that owns this issue. Dragging never changes it. */
+    boardId: string;
+    /** Per-project sequence behind the human key. Never reused. */
+    keyNum: number;
+    /** Display key, e.g. TOM-142. */
+    key: string;
+    title: string;
+    body: string | null;
+    kind: ItemKind;
+    workType: WorkType;
+    playbookId: string | null;
+    status: ItemStatus;
+    priority: Priority;
+    parentId: string | null;
+    rank: number;
+    labels: string[];
+    /** Ids of the items this one blocks. */
+    blocks: string[];
+    /** Ids of the items that block this one — the inverse of their `blocks`. */
+    blockedBy: string[];
+    /** Custom field values by field id. Built-in fields are the columns above. */
+    fields: Record<string, FieldValue>;
+    updatedAt: number;
+    updatedBy: Author;
+    version: number;
+    /** When set, AI writes may not touch title/body. */
+    humanLocked: boolean;
+}
+/** `fields` merges: a key set to null clears that value, absent keys are left alone. */
+export type Patch = Partial<Pick<Item, "title" | "body" | "kind" | "workType" | "playbookId" | "status" | "priority" | "parentId" | "rank" | "boardId" | "labels" | "blocks" | "humanLocked">> & {
+    fields?: Record<string, FieldValue | null>;
+};
+export type OplogEntity = "item" | "board" | "view";
+/**
+ * 'delete' is reversible — the row carries the snapshot undo restores from.
+ * 'purge' is a human-only permanent destroy: the entity's own history goes with
+ * it and the tombstone carries no snapshot, so undo walks straight past it.
+ * 'rank' is one item's manual position in one view — logged so it travels and
+ * can be undone, kept apart so history reads as decisions, not drags.
+ * 'merge' is a note a sync left behind: the same field changed on two machines,
+ * `before` holds the value that lost and `after` the one that stands. Undo
+ * steps over it; taking the loser back is an ordinary edit.
+ */
+export type OplogOp = "create" | "update" | "delete" | "purge" | "rank" | "merge";
+export interface OplogEntry {
+    seq: number;
+    entity: OplogEntity;
+    entityId: string;
+    op: OplogOp;
+    baseVersion: number | null;
+    before: unknown | null;
+    after: unknown | null;
+    by: Author;
+    at: number;
+    /** The agent run this write belongs to; null for a write made outside one. */
+    runId: string | null;
+    /** The machine that made the write; `device:deviceSeq` is the op's identity across machines. */
+    device: string;
+    /** The op's position in its own machine's sequence; null only for rows written before devices existed. */
+    deviceSeq: number | null;
+    /** The fields the op changed (the whole entity for a create); what the folder's log carries. */
+    patch: Record<string, unknown> | null;
+    /** The extension that made the write; null for the app itself. Local to this machine. */
+    via: string | null;
+}
+export interface UndoResult {
+    entry: OplogEntry;
+    /** One line describing what was reverted, for the toast. */
+    summary: string;
+}
+/** Result of reverting one agent run. `kept` names writes left in place because someone edited the entity afterwards. */
+export interface UndoRunResult {
+    reverted: number;
+    /** `entity` is an oplog entity, or what another undo provider calls its own (a file, a setting). */
+    kept: {
+        entity: string;
+        entityId: string;
+        label: string;
+        reason: string;
+    }[];
+}
+/**
+ * One record of the project's history as the timeline shows it: a backlog
+ * write, a file operation, or anything a plugin logs through its own undo
+ * provider. `ref` (`provider:id`) names it to `oplog.revert` and `oplog.rollback`.
+ */
+export interface UndoRecord {
+    ref: string;
+    provider: string;
+    id: string;
+    /** What kind of thing it touched: `item`, `board`, `view`, `file`, or a plugin's own. */
+    entity: string;
+    entityId: string;
+    /** What happened to it: an oplog op, or a file op (`write`, `mkdir`, `move`, `copy`, `remove`, `import`). */
+    op: string;
+    /** The entity's name for a sentence: an issue key, a view name, a file path. */
+    label: string;
+    /** A second name when the op has one — where a file moved or was copied to. */
+    target: string | null;
+    by: Author;
+    at: number;
+    runId: string | null;
+    /** The machine that made it; a record from another machine is history, never undoable here. */
+    device: string;
+    /** False for purges, merge notes and other machines' writes. */
+    undoable: boolean;
+    /** Set while the record sits in the redo stack; a new write anywhere clears that stack. */
+    undoneAt: number | null;
+}
+/** One step the timeline took: the record it acted on and a line for the toast. */
+export interface UndoStep {
+    record: UndoRecord;
+    summary: string;
+}
+/** Moving the timeline's cursor to a record: the steps taken, and why it stopped short when it did. */
+export interface RollbackResult {
+    steps: UndoStep[];
+    stopped: string | null;
+}
+export interface CreateItemInput {
+    projectId?: string;
+    boardId: string;
+    title: string;
+    body?: string | null;
+    kind?: ItemKind;
+    workType?: WorkType;
+    playbookId?: string | null;
+    status?: ItemStatus;
+    priority?: Priority;
+    parentId?: string | null;
+    rank?: number;
+    labels?: string[];
+    fields?: Record<string, FieldValue | null>;
+    by: Author;
+}
+export interface ListItemsFilter {
+    projectId?: string;
+    boardId?: string;
+    status?: ItemStatus;
+    kind?: ItemKind;
+    workType?: WorkType;
+    priority?: Priority;
+    parentId?: string | null;
+    label?: string;
+    /** Words that must all appear in title or body, as substrings in any script; matches come most relevant first. */
+    search?: string;
+    /** At most this many rows, from the front of the order: the most relevant when searching. */
+    limit?: number;
+    /** When no item has every search term, fall back to items with some of them, best matches first. */
+    widen?: boolean;
+}
+export interface Project {
+    id: string;
+    name: string;
+    description: string | null;
+    /** Prefix of the human issue key, e.g. 'TOM' in TOM-142. */
+    keyPrefix: string;
+    archived: boolean;
+    /** The tour a first run opens with: this machine's own, never in the account's catalog. */
+    sample?: boolean;
+    createdAt: number;
+    updatedAt: number;
+}
+export interface CreateProjectInput {
+    name: string;
+    description?: string | null;
+    keyPrefix?: string;
+    /** The language the seeded workstream and views are named in: "en" (the default) or "zh". */
+    locale?: string;
+}
+export type ProjectPatch = Partial<Pick<Project, "name" | "description" | "archived">>;
+/**
+ * A board is a workstream — an option of the built-in Workstream field. Every
+ * issue belongs to exactly one; a drag on a Workstream column writes it like
+ * any other field.
+ */
+export interface Board {
+    id: string;
+    projectId: string;
+    name: string;
+    icon: string;
+    note: string | null;
+    rank: number;
+    /** The code repository this workstream stands for, if any; several workstreams may share one. */
+    repoId: string | null;
+    /** Where in that repository the workstream's code lives; '' for the root. */
+    repoPath: string;
+    createdAt: number;
+    updatedAt: number;
+}
+export interface CreateBoardInput {
+    projectId: string;
+    name: string;
+    icon?: string;
+    note?: string | null;
+    rank?: number;
+    repoId?: string | null;
+    repoPath?: string;
+}
+export type BoardPatch = Partial<Pick<Board, "name" | "icon" | "note" | "rank" | "repoId" | "repoPath">>;
+/**
+ * A code repository a project's workstreams stand for. Shared: the remote URL
+ * is its identity everywhere. Where it is checked out on this machine is the
+ * catalog's business, never a row here.
+ */
+export interface Repo {
+    id: string;
+    projectId: string;
+    remote: string;
+    name: string;
+    defaultBranch: string;
+    createdAt: number;
+    updatedAt: number;
+}
+export interface CreateRepoInput {
+    projectId: string;
+    remote: string;
+    name?: string;
+    defaultBranch?: string;
+}
+export type RepoPatch = Partial<Pick<Repo, "name" | "defaultBranch" | "remote">>;
+/** A saved, named way of looking at the project's backlog: one layout and one query. */
+export interface View {
+    id: string;
+    projectId: string;
+    name: string;
+    icon: string;
+    layout: Layout;
+    query: ViewQuery;
+    rank: number;
+    createdAt: number;
+    updatedAt: number;
+}
+export interface CreateViewInput {
+    projectId: string;
+    name: string;
+    icon?: string;
+    layout?: Layout;
+    query?: Partial<ViewQuery>;
+    rank?: number;
+}
+export type ViewPatch = Partial<Pick<View, "name" | "icon" | "layout" | "query" | "rank">>;
+export type BuiltInTheme = "light" | "dark" | "matcha" | "dawn";
+export type ThemePreference = "system" | BuiltInTheme | `custom:${string}`;
+export declare const THEME_TOKEN_NAMES: readonly ["bg", "surface", "surface-warm", "fg", "fg-2", "muted", "meta", "border", "border-soft", "accent", "accent-on", "accent-light", "accent-active", "success", "warn", "danger", "tag-bg-faint", "tag-bg-soft", "tag-bg-base", "tag-bg-strong", "tag-fg"];
+export type ThemeTokenName = (typeof THEME_TOKEN_NAMES)[number];
+export declare const THEME_FONT_NAMES: readonly ["font-display", "font-body", "font-mono"];
+export type ThemeFontName = (typeof THEME_FONT_NAMES)[number];
+export declare const THEME_FONT_SIZE_NAMES: readonly ["text-xs", "text-sm", "text-base", "text-md", "text-lg", "text-xl", "text-2xl"];
+export declare const THEME_FONT_WEIGHT_NAMES: readonly ["font-weight-regular", "font-weight-medium"];
+export declare const THEME_TYPOGRAPHY_NAMES: readonly ["font-display", "font-body", "font-mono", "text-xs", "text-sm", "text-base", "text-md", "text-lg", "text-xl", "text-2xl", "font-weight-regular", "font-weight-medium"];
+export type ThemeTypographyName = (typeof THEME_TYPOGRAPHY_NAMES)[number];
+export interface CustomTheme {
+    id: `custom:${string}`;
+    name: string;
+    base: BuiltInTheme;
+    icon: "i-sun" | "i-moon" | "i-leaf" | "i-tag" | "i-bug" | "i-board" | "i-stack" | "i-sliders";
+    tokens: Record<ThemeTokenName, string>;
+    fonts: Record<ThemeTypographyName, string>;
+}
+export type ThemeAutomationMode = "none" | "system" | "schedule" | "shuffle";
+export interface ThemeScheduleRule {
+    start: string;
+    end: string;
+    theme: Exclude<ThemePreference, "system">;
+}
+export interface ThemeAutomation {
+    mode: ThemeAutomationMode;
+    defaultTheme: Exclude<ThemePreference, "system">;
+    schedule: ThemeScheduleRule[];
+    shuffleMinutes: number;
+}
+/**
+ * 'system' follows the OS locale, falling back to English when no language
+ * the app has matches it; otherwise a language tag — one the app ships
+ * ("en", "zh", "zh-Hant", "ja", "es", "de", "fr", "ru") or one a language pack adds.
+ */
+export type LanguagePreference = "system" | (string & {});
+export interface LlmSettings {
+    apiKey: string;
+    baseURL: string;
+    model: string;
+}
+/** Settings are sections keyed by id; plugins register their own. */
+export interface AppSettings {
+    theme: ThemePreference;
+    language: LanguagePreference;
+    llm?: LlmSettings;
+    [section: string]: unknown;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.js

@@ -0,0 +1,8 @@
+export const ITEM_STATUSES = ["backlog", "todo", "doing", "verifying", "done", "cancelled"];
+export const DEFAULT_PRIORITY = 2;
+export const THEME_TOKEN_NAMES = ["bg", "surface", "surface-warm", "fg", "fg-2", "muted", "meta", "border", "border-soft", "accent", "accent-on", "accent-light", "accent-active", "success", "warn", "danger", "tag-bg-faint", "tag-bg-soft", "tag-bg-base", "tag-bg-strong", "tag-fg"];
+export const THEME_FONT_NAMES = ["font-display", "font-body", "font-mono"];
+export const THEME_FONT_SIZE_NAMES = ["text-xs", "text-sm", "text-base", "text-md", "text-lg", "text-xl", "text-2xl"];
+export const THEME_FONT_WEIGHT_NAMES = ["font-weight-regular", "font-weight-medium"];
+export const THEME_TYPOGRAPHY_NAMES = [...THEME_FONT_NAMES, ...THEME_FONT_SIZE_NAMES, ...THEME_FONT_WEIGHT_NAMES];
+//# sourceMappingURL=types.js.map

package/dist/words.d.ts

@@ -0,0 +1,39 @@
+import { type Dictionaries, type LanguageTag } from "./language.js";
+/**
+ * What the backend says to a person, kept as one book of templates per
+ * package. A template names its values as {{slot}}; the code picks which
+ * template to use and fills it, so a translation is data and nothing more.
+ * Prompts written for an agent are not words: they stay in code, in English.
+ */
+/** The languages Tomrade's own code writes in, each complete. Any other language reads English, or what an installed language pack brings. */
+export type WordsLocale = "en" | "zh";
+export declare const wordsLocale: (locale: unknown) => WordsLocale;
+/** The `{{slot}}` names a template asks for. */
+export type Slots<S extends string> = S extends `${string}{{${infer V}}}${infer R}` ? V | Slots<R> : never;
+type Fill<S extends string> = [Slots<S>] extends [never] ? [] : [vars: Record<Slots<S>, string | number>];
+type SameSlots<A extends string, B extends string> = [Slots<A>] extends [Slots<B>] ? ([Slots<B>] extends [Slots<A>] ? true : false) : false;
+/** Each translation is complete and names exactly the slots its English does. */
+type Translation<E extends Record<string, string>, Z> = {
+    [K in keyof E]: K extends keyof Z ? (Z[K] extends string ? (SameSlots<E[K], Z[K]> extends true ? Z[K] : `slots differ from en: ${E[K]}`) : string) : string;
+};
+export interface Speak<E extends Record<string, string>> {
+    <K extends keyof E & string>(key: K, ...vars: Fill<E[K]>): string;
+    /** The language asked for; a word it lacks reads English. */
+    readonly locale: LanguageTag;
+}
+export type WordBook<E extends Record<string, string>> = (locale: unknown) => Speak<E>;
+export declare const fillSlots: (template: string, vars?: Record<string, string | number>) => string;
+export declare function defineWords<const E extends Record<string, string>, const Z extends Record<string, string>>(id: string, book: {
+    en: E;
+    zh: Z & Translation<E, Z>;
+}): WordBook<E>;
+/** The English of every book defined so far, keyed by book id. */
+export declare const englishWords: () => Dictionaries;
+/**
+ * A language pack's words for the backend's books, spoken from now on. An
+ * entry English lacks, or one asking for other slots, reads English. The
+ * pack installed last speaks first. Returns the undo.
+ */
+export declare function installWords(locale: LanguageTag, books: Dictionaries): () => void;
+export {};
+//# sourceMappingURL=words.d.ts.map

package/dist/words.js

@@ -0,0 +1,45 @@
+import { languageTag, sameSlots } from "./language.js";
+export const wordsLocale = (locale) => (locale === "zh" ? "zh" : "en");
+export const fillSlots = (template, vars) => vars ? template.replace(/\{\{(\w+)\}\}/g, (_, name) => String(vars[name] ?? "")) : template;
+/** Every book's English, by id: what a language pack translates. */
+const english = new Map();
+/** Language → book → key: what installed language packs bring, each layer kept apart so one can be taken back. */
+const packs = new Map();
+export function defineWords(id, book) {
+    english.set(id, book.en);
+    const zh = book.zh;
+    return (locale) => {
+        const lang = languageTag(locale);
+        const speak = (key, vars) => {
+            const source = book.en[key];
+            let text;
+            // A pack's entry stands in only for a key English has, asking for the same values.
+            for (const layer of packs.get(lang) ?? []) {
+                const said = layer[id]?.[key];
+                if (text === undefined && source !== undefined && typeof said === "string" && sameSlots(source, said))
+                    text = said;
+            }
+            return fillSlots(text ?? (lang === "zh" ? zh[key] : undefined) ?? source ?? key, vars);
+        };
+        return Object.assign(speak, { locale: lang });
+    };
+}
+/** The English of every book defined so far, keyed by book id. */
+export const englishWords = () => Object.fromEntries(english);
+/**
+ * A language pack's words for the backend's books, spoken from now on. An
+ * entry English lacks, or one asking for other slots, reads English. The
+ * pack installed last speaks first. Returns the undo.
+ */
+export function installWords(locale, books) {
+    const tag = languageTag(locale);
+    packs.set(tag, [books, ...(packs.get(tag) ?? [])]);
+    return () => {
+        const rest = (packs.get(tag) ?? []).filter((l) => l !== books);
+        if (rest.length)
+            packs.set(tag, rest);
+        else
+            packs.delete(tag);
+    };
+}
+//# sourceMappingURL=words.js.map

package/package.json

@@ -1,6 +1,28 @@
 {
   "name": "@tomradex/domain",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.16",
+  "type": "module",
+  "author": "Haoyuan Tang",
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "Apache-2.0",
+  "description": "Tomrade's domain types and schemas: the issues, fields, boards, views and history a plugin reads",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "zod": "^4.4.3"
+  }
+}