@tomradex/domain 0.2.0 → 0.2.18

package/dist/attachments.d.ts

@@ -0,0 +1,19 @@
+/**
+ * How a ticket body points at a file of the project's Files store: by id, so a
+ * rename or a move in Files never breaks the link and never rewrites the body.
+ */
+export declare const FILE_LINK = "tomrade-file://";
+/** Each file id the text links to, once, in order of first mention. */
+export declare function linkedFileIds(text: string | null | undefined): string[];
+/** A linked file as an agent can use it: where it is now and what it is. */
+export interface FileDescription {
+    fileId: string;
+    /** Relative to the Files store root. */
+    path: string;
+    name: string;
+    mime: string;
+    size: number;
+    /** On this machine, for engines that read files themselves; null when the store has no folder here. */
+    localPath: string | null;
+}
+//# sourceMappingURL=attachments.d.ts.map

package/dist/attachments.js

@@ -0,0 +1,13 @@
+/**
+ * How a ticket body points at a file of the project's Files store: by id, so a
+ * rename or a move in Files never breaks the link and never rewrites the body.
+ */
+export const FILE_LINK = "tomrade-file://";
+const LINKED = /tomrade-file:\/\/([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})/gi;
+/** Each file id the text links to, once, in order of first mention. */
+export function linkedFileIds(text) {
+    if (!text)
+        return [];
+    return [...new Set([...text.matchAll(LINKED)].map((m) => m[1].toLowerCase()))];
+}
+//# sourceMappingURL=attachments.js.map

package/dist/delivery.d.ts

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import type { FileDescription } from "./attachments.js";
 import type { Author } from "./types.js";
 /** Metadata only. File bytes and immutable versions belong to the Files plugin. */
 export interface FileReference {
@@ -66,5 +67,7 @@ export declare const reviewDeliverySchema: z.ZodObject<{
 /** The future Files plugin supplies this resolver; no fallback file store exists. */
 export interface FilesResolver {
     getVersion(projectId: string, reference: FileReference): Promise<FileReference | null>;
+    /** The files behind these ids as they are now; an id with no file here is left out. */
+    describe(projectId: string, fileIds: string[]): Promise<FileDescription[]>;
 }
 //# sourceMappingURL=delivery.d.ts.map

package/dist/errors.d.ts

@@ -50,4 +50,26 @@ export declare class FieldDefinitionError extends Error {
     readonly reason: string;
     constructor(fieldId: string, reason: string);
 }
+/**
+ * What a failed model call means for the person — each wants a different fix: the key, the address, a wait.
+ * `slow`: the model was reached but gave no answer in time; only a check that waits for one says it.
+ */
+export type ModelErrorKind = "auth" | "quota" | "rate" | "model" | "server" | "network" | "slow" | "other";
+/** Why a model turned a working key down: the wrong API for it, not open to this key's tier or account, or not known. */
+export type ModelRefusal = "method" | "tier" | "unknown";
+export declare function modelRefusal(message: string): ModelRefusal | null;
+/** Only a key the provider calls wrong or missing is `auth`; a model it will not serve this key is `model`, even on a 403. */
+export declare function modelErrorKind(message: string): ModelErrorKind;
+/** The provider's own words in a failed call's detail (its JSON `message`), or null; cut short where the detail was. */
+export declare function providerMessage(detail: string): string | null;
+/**
+ * An undo aimed at one write — a toast's — refused because the thing changed
+ * again since. The marker survives IPC's message wrapping, so the renderer can
+ * say it in the person's language.
+ */
+export declare const STALE_UNDO = "[stale-undo]";
+export declare class StaleUndoError extends Error {
+    readonly entityId: string;
+    constructor(entityId: string);
+}
 //# sourceMappingURL=errors.d.ts.map

package/dist/errors.js

@@ -96,4 +96,60 @@ export class FieldDefinitionError extends Error {
         this.name = "FieldDefinitionError";
     }
 }
+const BAD_KEY = /\b401\b|authenticat|unauthori[sz]ed|invalid[ _-]?(api[ _-]?)?key|incorrect api key|api[ _-]?key[ _-]?(not valid|invalid|expired|missing|required)|(missing|no) api[ _-]?key/i;
+export function modelRefusal(message) {
+    if (/not supported for (generateContent|this (api|method|endpoint))|not a chat model|only supported (in|on|by) (the )?(v1\/)?responses|not supported (in|on|by) (the )?(v1\/)?chat\/completions|does not support (chat|generateContent)/i.test(message))
+        return "method";
+    if (/model.{0,40}(not found|does not exist|not exist|unknown)|no such model|unknown model|model_not_found/i.test(message) && !/not have access to model/i.test(message))
+        return "unknown";
+    if (/free[ _-]?tier\w*.{0,80}\blimit: ?0\b|not available (on|for|in) (the |your |this )?(free |current )?(tier|plan)|not have access to (the |this )?model|not have permission to (use|access) (the |this )?model|not allow-?listed|model.{0,60}(not available|unavailable) (to|for) (you|this)/i.test(message))
+        return "tier";
+    return null;
+}
+/** Only a key the provider calls wrong or missing is `auth`; a model it will not serve this key is `model`, even on a 403. */
+export function modelErrorKind(message) {
+    if (BAD_KEY.test(message))
+        return "auth";
+    if (modelRefusal(message))
+        return "model";
+    if (/\b403\b|api key|permission denied|forbidden/i.test(message))
+        return "auth";
+    if (/\b402\b|insufficient|balance|quota|billing|credit/i.test(message))
+        return "quota";
+    if (/\b429\b|rate.?limit|too many requests/i.test(message))
+        return "rate";
+    if (/\b404\b|model.{0,40}(not found|does not exist|not exist|unknown|invalid)|no such model|unknown model/i.test(message))
+        return "model";
+    if (/\b5\d\d\b|overloaded|bad gateway|service unavailable/i.test(message))
+        return "server";
+    if (/fetch failed|ECONNREFUSED|ECONNRESET|ENOTFOUND|EAI_AGAIN|ETIMEDOUT|network|timed? ?out|socket hang up|certificate/i.test(message))
+        return "network";
+    return "other";
+}
+/** The provider's own words in a failed call's detail (its JSON `message`), or null; cut short where the detail was. */
+export function providerMessage(detail) {
+    const found = /"message"\s*:\s*"((?:[^"\\]|\\.)*)("|$)/.exec(detail);
+    if (!found?.[1].trim())
+        return null;
+    let said = found[1];
+    try {
+        said = JSON.parse(`"${said.replace(/\\$/, "")}"`);
+    }
+    catch { }
+    return found[2] ? said : `${said}…`;
+}
+/**
+ * An undo aimed at one write — a toast's — refused because the thing changed
+ * again since. The marker survives IPC's message wrapping, so the renderer can
+ * say it in the person's language.
+ */
+export const STALE_UNDO = "[stale-undo]";
+export class StaleUndoError extends Error {
+    entityId;
+    constructor(entityId) {
+        super(`${STALE_UNDO} ${entityId} changed again after that edit; undo it from History instead`);
+        this.entityId = entityId;
+        this.name = "StaleUndoError";
+    }
+}
 //# sourceMappingURL=errors.js.map

package/dist/fields.d.ts

@@ -34,6 +34,10 @@ export interface FieldDef {
         group: boolean;
     };
     rank: number;
+    /** Computed by a plugin from what it keeps (a ticket's spend, say); its value rides on `item.fields` when items are read. */
+    derived?: boolean;
+    /** How a number reads: `usd` is money. */
+    unit?: "usd";
 }
 export type BuiltinFieldId = "title" | "status" | "workType" | "priority" | "epic" | "labels" | "board" | "updated" | "key" | "provenance";
 /** The fields every project has, in display order. Ids are reserved: a custom field can never claim one. */

package/dist/index.d.ts

@@ -1,8 +1,11 @@
 export * from "./types.js";
 export * from "./delivery.js";
+export * from "./attachments.js";
 export * from "./errors.js";
 export * from "./schema.js";
 export * from "./derive.js";
 export * from "./fields.js";
 export * from "./query.js";
+export * from "./words.js";
+export * from "./language.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -1,8 +1,11 @@
 export * from "./types.js";
 export * from "./delivery.js";
+export * from "./attachments.js";
 export * from "./errors.js";
 export * from "./schema.js";
 export * from "./derive.js";
 export * from "./fields.js";
 export * from "./query.js";
+export * from "./words.js";
+export * from "./language.js";
 //# sourceMappingURL=index.js.map

package/dist/language.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Languages as data. English is the source every dictionary translates: a
+ * translation is a set of `namespace → key → template` entries, and an entry
+ * counts only where English has the key and the template asks for the same
+ * values. Everything here is pure, so the main process and the renderer
+ * merge, check and pick languages the same way.
+ */
+/** A BCP 47 language tag: "en", "zh-Hant", "pt-BR". */
+export type LanguageTag = string;
+/** Templates by namespace, then key. */
+export type Dictionaries = Record<string, Record<string, string>>;
+/** The tag in its canonical spelling ("pt-br" → "pt-BR"), or null when it is not a language tag. */
+export declare function canonicalTag(tag: unknown): LanguageTag | null;
+export declare const isLanguageTag: (tag: unknown) => tag is LanguageTag;
+/** Any language a person may be reading in; English for anything that is not a tag ("system", nothing at all). */
+export declare const languageTag: (locale: unknown) => LanguageTag;
+/** The language's English name, for a prompt's "reply in …" line: "Brazilian Portuguese". */
+export declare function languageName(locale: unknown): string;
+/** What a template fills in or keys off: its `{{slot}}`s and the `[[cmd:…]]` chords the interface writes. */
+export declare const slotsOf: (template: string) => string[];
+export declare const sameSlots: (a: string, b: string) => boolean;
+/** The entries of a translation that can stand in for English: keys English has, asking for the values its template does. */
+export declare function usableWords(english: Dictionaries, translated: Dictionaries): Dictionaries;
+export interface LanguageCoverage {
+    /** Entries English has. */
+    total: number;
+    /** Entries translated with the slots English asks for. */
+    translated: number;
+    /** `namespace.key` English has and the translation does not; these read in English. */
+    missing: string[];
+    /** `namespace.key` the translation has and English no longer does; nothing reads them. */
+    stale: string[];
+    /** Entries whose template asks for other values than English's; these read in English. */
+    slotMismatches: {
+        key: string;
+        english: string[];
+        translated: string[];
+    }[];
+}
+/** How much of English a translation covers, and what in it nothing can use. */
+export declare function languageCoverage(english: Dictionaries, translated: Dictionaries): LanguageCoverage;
+/**
+ * The language to show for a system that prefers `system`, among those the
+ * app has: the same tag, else the same language written in the same script —
+ * the system's region first, then the language's plain tag. zh-TW finds
+ * zh-Hant and never zh; pt-PT finds pt-BR when that is all there is.
+ */
+export declare function pickLanguage(system: string | readonly string[] | undefined | null, available: readonly LanguageTag[]): LanguageTag | null;
+//# sourceMappingURL=language.d.ts.map

package/dist/language.js

@@ -0,0 +1,117 @@
+/**
+ * Languages as data. English is the source every dictionary translates: a
+ * translation is a set of `namespace → key → template` entries, and an entry
+ * counts only where English has the key and the template asks for the same
+ * values. Everything here is pure, so the main process and the renderer
+ * merge, check and pick languages the same way.
+ */
+const canonical = new Map();
+/** The tag in its canonical spelling ("pt-br" → "pt-BR"), or null when it is not a language tag. */
+export function canonicalTag(tag) {
+    if (typeof tag !== "string" || !/^[A-Za-z]{2,3}(-[A-Za-z0-9]{1,8})*$/.test(tag))
+        return null;
+    let known = canonical.get(tag);
+    if (known === undefined) {
+        try {
+            known = Intl.getCanonicalLocales(tag)[0] ?? null;
+        }
+        catch {
+            known = null;
+        }
+        canonical.set(tag, known);
+    }
+    return known;
+}
+export const isLanguageTag = (tag) => canonicalTag(tag) !== null;
+/** Any language a person may be reading in; English for anything that is not a tag ("system", nothing at all). */
+export const languageTag = (locale) => canonicalTag(locale) ?? "en";
+// Intl names zh "Chinese"; the app's zh is the simplified script.
+const NAMES = { zh: "Simplified Chinese", "zh-Hant": "Traditional Chinese" };
+/** The language's English name, for a prompt's "reply in …" line: "Brazilian Portuguese". */
+export function languageName(locale) {
+    const tag = languageTag(locale);
+    if (NAMES[tag])
+        return NAMES[tag];
+    try {
+        return new Intl.DisplayNames(["en"], { type: "language" }).of(tag) ?? tag;
+    }
+    catch {
+        return tag;
+    }
+}
+/** What a template fills in or keys off: its `{{slot}}`s and the `[[cmd:…]]` chords the interface writes. */
+export const slotsOf = (template) => [...new Set((template.match(/\{\{\s*\w+\s*\}\}|\[\[cmd:\w+\]\]/g) ?? []).map((s) => s.replace(/\s/g, "")))].sort();
+export const sameSlots = (a, b) => slotsOf(a).join("\0") === slotsOf(b).join("\0");
+/** The entries of a translation that can stand in for English: keys English has, asking for the values its template does. */
+export function usableWords(english, translated) {
+    const out = {};
+    for (const [ns, entries] of Object.entries(translated)) {
+        const source = english[ns];
+        if (!source || typeof entries !== "object" || entries === null)
+            continue;
+        for (const [key, text] of Object.entries(entries)) {
+            if (typeof text !== "string" || typeof source[key] !== "string" || !sameSlots(source[key], text))
+                continue;
+            (out[ns] ??= {})[key] = text;
+        }
+    }
+    return out;
+}
+/** How much of English a translation covers, and what in it nothing can use. */
+export function languageCoverage(english, translated) {
+    const out = { total: 0, translated: 0, missing: [], stale: [], slotMismatches: [] };
+    for (const [ns, entries] of Object.entries(english)) {
+        for (const [key, source] of Object.entries(entries)) {
+            out.total += 1;
+            const text = translated[ns]?.[key];
+            if (typeof text !== "string")
+                out.missing.push(`${ns}.${key}`);
+            else if (!sameSlots(source, text))
+                out.slotMismatches.push({ key: `${ns}.${key}`, english: slotsOf(source), translated: slotsOf(text) });
+            else
+                out.translated += 1;
+        }
+    }
+    for (const [ns, entries] of Object.entries(translated)) {
+        for (const key of Object.keys(entries ?? {}))
+            if (typeof english[ns]?.[key] !== "string")
+                out.stale.push(`${ns}.${key}`);
+    }
+    return out;
+}
+const parts = (tag) => {
+    try {
+        const l = new Intl.Locale(tag).maximize();
+        return { language: l.language, script: l.script, region: l.region };
+    }
+    catch {
+        return null;
+    }
+};
+/**
+ * The language to show for a system that prefers `system`, among those the
+ * app has: the same tag, else the same language written in the same script —
+ * the system's region first, then the language's plain tag. zh-TW finds
+ * zh-Hant and never zh; pt-PT finds pt-BR when that is all there is.
+ */
+export function pickLanguage(system, available) {
+    const wanted = (typeof system === "string" ? [system] : (system ?? [])).map((s) => canonicalTag(s.replace(/_/g, "-").split(".")[0])).filter((s) => !!s);
+    const options = available.flatMap((tag) => {
+        const p = parts(tag);
+        return p ? [{ tag, ...p }] : [];
+    });
+    for (const tag of wanted) {
+        const exact = available.find((a) => a.toLowerCase() === tag.toLowerCase());
+        if (exact)
+            return exact;
+        const want = parts(tag);
+        if (!want)
+            continue;
+        const same = options.filter((o) => o.language === want.language && o.script === want.script);
+        const pick = same.find((o) => o.region === want.region && o.tag.includes("-")) ?? same.find((o) => o.tag === want.language) ?? same[0];
+        if (pick)
+            return pick.tag;
+    }
+    return null;
+}
+//# sourceMappingURL=language.js.map

package/dist/query.d.ts

@@ -54,6 +54,14 @@ export interface QueryContext {
 export declare function dayBound(value: FieldValue | null | undefined, op: "gte" | "lte"): number | null;
 export declare function matchesClause(item: Item, clause: FilterClause): boolean;
 export declare const matchesFilter: (item: Item, filter: FilterClause[]) => boolean;
+/**
+ * The terms of a search: whitespace-separated words, except that a run in
+ * double quotes ("login timeout", “登录 超时”) is one term matched as a whole,
+ * spaces included. A quote with no partner runs to the end of the string.
+ */
+export declare function searchTerms(search: string): string[];
+/** Every term appears, case aside, in the ticket's key, title or body — what the items index matches, plus the key. */
+export declare function matchesSearch(item: Item, terms: string[]): boolean;
 /** A comparable for one sort key: numbers for numeric fields, strings otherwise, null when empty. */
 export declare function sortKeyOf(item: Item, fieldId: string, ctx: QueryContext): number | string | null;
 /** Empty values sort last whichever direction; ties fall through to manual rank, then recency. */

package/dist/query.js

@@ -53,6 +53,45 @@ export function matchesClause(item, clause) {
     }
 }
 export const matchesFilter = (item, filter) => filter.every((c) => matchesClause(item, c));
+/**
+ * The terms of a search: whitespace-separated words, except that a run in
+ * double quotes ("login timeout", “登录 超时”) is one term matched as a whole,
+ * spaces included. A quote with no partner runs to the end of the string.
+ */
+export function searchTerms(search) {
+    const out = [];
+    const closer = { '"': '"', "\u201c": "\u201d" };
+    let i = 0;
+    while (i < search.length) {
+        const c = search[i];
+        if (/\s/.test(c)) {
+            i++;
+            continue;
+        }
+        const close = closer[c];
+        if (close) {
+            const end = search.indexOf(close, i + 1);
+            const phrase = (end === -1 ? search.slice(i + 1) : search.slice(i + 1, end)).trim();
+            if (phrase)
+                out.push(phrase);
+            i = end === -1 ? search.length : end + 1;
+            continue;
+        }
+        let j = i;
+        while (j < search.length && !/\s/.test(search[j]))
+            j++;
+        out.push(search.slice(i, j));
+        i = j;
+    }
+    return out;
+}
+/** Every term appears, case aside, in the ticket's key, title or body — what the items index matches, plus the key. */
+export function matchesSearch(item, terms) {
+    if (!terms.length)
+        return true;
+    const text = `${item.key} ${item.title} ${item.body ?? ""}`.toLowerCase();
+    return terms.every((term) => text.includes(term.toLowerCase()));
+}
 /** A comparable for one sort key: numbers for numeric fields, strings otherwise, null when empty. */
 export function sortKeyOf(item, fieldId, ctx) {
     const raw = fieldValueOf(item, fieldId);

package/dist/schema.d.ts

@@ -1,7 +1,7 @@
 import { z } from "zod";
 export declare const itemKindSchema: z.ZodEnum<{
-    ticket: "ticket";
     epic: "epic";
+    ticket: "ticket";
 }>;
 export declare const workTypeSchema: z.ZodEnum<{
     coding: "coding";
@@ -15,7 +15,7 @@ export declare const itemStatusSchema: z.ZodEnum<{
     done: "done";
     cancelled: "cancelled";
 }>;
-export declare const prioritySchema: z.ZodUnion<readonly [z.ZodLiteral<0>, z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodLiteral<3>, z.ZodLiteral<4>]>;
+export declare const prioritySchema: z.ZodLiteral<0 | 1 | 2 | 3 | 4>;
 export declare const listItemsFilterSchema: z.ZodObject<{
     projectId: z.ZodOptional<z.ZodString>;
     boardId: z.ZodOptional<z.ZodString>;
@@ -28,14 +28,14 @@ export declare const listItemsFilterSchema: z.ZodObject<{
         cancelled: "cancelled";
     }>>;
     kind: z.ZodOptional<z.ZodEnum<{
-        ticket: "ticket";
         epic: "epic";
+        ticket: "ticket";
     }>>;
     workType: z.ZodOptional<z.ZodEnum<{
         coding: "coding";
         general: "general";
     }>>;
-    priority: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<0>, z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodLiteral<3>, z.ZodLiteral<4>]>>;
+    priority: z.ZodOptional<z.ZodLiteral<0 | 1 | 2 | 3 | 4>>;
     label: z.ZodOptional<z.ZodString>;
     parentId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     search: z.ZodOptional<z.ZodString>;
@@ -66,8 +66,8 @@ export declare const createItemSchema: z.ZodObject<{
     title: z.ZodString;
     body: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     kind: z.ZodOptional<z.ZodEnum<{
-        ticket: "ticket";
         epic: "epic";
+        ticket: "ticket";
     }>>;
     workType: z.ZodOptional<z.ZodEnum<{
         coding: "coding";
@@ -81,7 +81,7 @@ export declare const createItemSchema: z.ZodObject<{
         done: "done";
         cancelled: "cancelled";
     }>>;
-    priority: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<0>, z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodLiteral<3>, z.ZodLiteral<4>]>>;
+    priority: z.ZodOptional<z.ZodLiteral<0 | 1 | 2 | 3 | 4>>;
     labels: z.ZodOptional<z.ZodArray<z.ZodString>>;
     parentId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     projectId: z.ZodOptional<z.ZodString>;
@@ -93,8 +93,8 @@ export declare const patchSchema: z.ZodObject<{
     title: z.ZodOptional<z.ZodString>;
     body: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     kind: z.ZodOptional<z.ZodEnum<{
-        ticket: "ticket";
         epic: "epic";
+        ticket: "ticket";
     }>>;
     workType: z.ZodOptional<z.ZodEnum<{
         coding: "coding";
@@ -108,11 +108,12 @@ export declare const patchSchema: z.ZodObject<{
         done: "done";
         cancelled: "cancelled";
     }>>;
-    priority: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<0>, z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodLiteral<3>, z.ZodLiteral<4>]>>;
+    priority: z.ZodOptional<z.ZodLiteral<0 | 1 | 2 | 3 | 4>>;
     labels: z.ZodOptional<z.ZodArray<z.ZodString>>;
     blocks: z.ZodOptional<z.ZodArray<z.ZodString>>;
     parentId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     rank: z.ZodOptional<z.ZodNumber>;
+    boardId: z.ZodOptional<z.ZodString>;
     fields: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNullable<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>>>;
 }, z.core.$strip>;
 //# sourceMappingURL=schema.d.ts.map

package/dist/schema.js

@@ -2,7 +2,8 @@ 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"]);
-export const prioritySchema = z.union([z.literal(0), z.literal(1), z.literal(2), z.literal(3), z.literal(4)]);
+// 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(),
@@ -11,7 +12,7 @@ export const listItemsFilterSchema = z.object({
     workType: workTypeSchema.optional(),
     priority: prioritySchema.optional(),
     label: z.string().optional(),
-    parentId: z.string().nullable().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()]);
@@ -32,7 +33,7 @@ export const createItemSchema = z.object({
     status: itemStatusSchema.optional(),
     priority: prioritySchema.optional(),
     labels: z.array(z.string()).optional(),
-    parentId: z.string().nullable().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()
@@ -46,9 +47,10 @@ export const patchSchema = z.object({
     status: itemStatusSchema.optional(),
     priority: prioritySchema.optional(),
     labels: z.array(z.string()).optional(),
-    blocks: z.array(z.string()).optional(),
-    parentId: z.string().nullable().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

@@ -91,8 +91,9 @@ export interface UndoResult {
 /** 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: OplogEntity;
+        entity: string;
         entityId: string;
         label: string;
         reason: string;
@@ -175,6 +176,8 @@ export interface Project {
     /** 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;
 }
@@ -182,6 +185,8 @@ 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">>;
 /**
@@ -285,8 +290,12 @@ export interface ThemeAutomation {
     schedule: ThemeScheduleRule[];
     shuffleMinutes: number;
 }
-/** 'system' follows the OS locale, falling back to English when that locale isn't supported. */
-export type LanguagePreference = "system" | "en" | "zh";
+/**
+ * '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;

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,6 @@
 {
   "name": "@tomradex/domain",
-  "version": "0.2.0",
+  "version": "0.2.18",
   "type": "module",
   "author": "Haoyuan Tang",
   "engines": {

package/dist/view-kinds.d.ts

@@ -1,13 +0,0 @@
-import type { GroupBy, ViewKind } from "./types.js";
-/**
- * The `views` table still carries legacy `name`/`icon`/`group_by` columns
- * (kept for schema stability — see packages/db). These are the values written
- * into them for each built-in kind; the app itself never reads them back.
- */
-export declare const VIEW_KIND_META: Record<ViewKind, {
-    name: string;
-    icon: string;
-    groupBy: GroupBy;
-    rank: number;
-}>;
-//# sourceMappingURL=view-kinds.d.ts.map

package/dist/view-kinds.js

@@ -1,12 +0,0 @@
-/**
- * The `views` table still carries legacy `name`/`icon`/`group_by` columns
- * (kept for schema stability — see packages/db). These are the values written
- * into them for each built-in kind; the app itself never reads them back.
- */
-export const VIEW_KIND_META = {
-    status: { name: "Status", icon: "s-doing", groupBy: "status", rank: 0 },
-    priority: { name: "Priority", icon: "i-bars", groupBy: "priority", rank: 1 },
-    epic: { name: "Epic", icon: "i-stack", groupBy: "epic", rank: 2 },
-    dependencies: { name: "Dependencies", icon: "i-graph", groupBy: "status", rank: 3 }
-};
-//# sourceMappingURL=view-kinds.js.map