@agent-native/core 0.101.13 → 0.102.0

package/corpus/templates/tasks/server/tasks/store.ts

@@ -0,0 +1,306 @@
+import type { FieldValueInput } from "../custom-fields/types.js";
+import {
+  applyCustomFieldValuePatches,
+  deleteCustomFieldValuesByTaskIds,
+  prepareCustomFieldValuePatches,
+  updateCustomFieldValuesByTaskId,
+} from "../custom-fields/values/store.js";
+import { getDb } from "../db/index.js";
+import type { StoredItem } from "../db/schema.js";
+import type { DbHandle } from "../db/transaction.js";
+import { NotFoundError, UserInputError } from "../errors.js";
+import {
+  assertStoredItemsExist,
+  createStoredItem,
+  deleteStoredItems,
+  getStoredItem,
+  hasCompletedStoredItems,
+  listStoredItems,
+  reorderStoredItems,
+  requireUserEmail,
+  updateStoredItems,
+} from "../stored-items/store.js";
+
+export { requireUserEmail };
+
+/** Action/UI view of a task on the task list (`promotedToTask = true` in storage). */
+export type Task = Omit<StoredItem, "promotedToTask">;
+
+const NOT_FOUND = "Task not found.";
+
+export async function createTask(
+  input: {
+    ownerEmail: string;
+    title: string;
+    id?: string;
+    now?: string;
+  },
+  db: DbHandle = getDb(),
+): Promise<Task> {
+  const item = await createStoredItem(
+    {
+      ownerEmail: input.ownerEmail,
+      title: input.title,
+      id: input.id ?? crypto.randomUUID(),
+      now: input.now ?? new Date().toISOString(),
+      promotedToTask: true,
+    },
+    db,
+  );
+  return toTask(item);
+}
+
+export async function getTask(
+  input: {
+    ownerEmail: string;
+    id: string;
+  },
+  db: DbHandle = getDb(),
+): Promise<Task | null> {
+  const item = await getStoredItem(
+    {
+      ...input,
+      promotedToTask: true,
+    },
+    db,
+  );
+  return item ? toTask(item) : null;
+}
+
+export async function listTasks(
+  input: {
+    ownerEmail: string;
+    ids?: string[];
+    includeDone?: boolean;
+  },
+  db: DbHandle = getDb(),
+): Promise<Task[]> {
+  const items = await listStoredItems(
+    {
+      ...input,
+      promotedToTask: true,
+      notFoundMessage: NOT_FOUND,
+    },
+    db,
+  );
+  return items.map(toTask);
+}
+
+export async function hasCompletedTasks(
+  input: {
+    ownerEmail: string;
+  },
+  db: DbHandle = getDb(),
+): Promise<boolean> {
+  return hasCompletedStoredItems(
+    {
+      ownerEmail: input.ownerEmail,
+      promotedToTask: true,
+    },
+    db,
+  );
+}
+
+export async function updateTasks(
+  input: {
+    ownerEmail: string;
+    ids: string[];
+    title?: string;
+    done?: boolean;
+    now?: string;
+  },
+  db: DbHandle = getDb(),
+): Promise<Task[]> {
+  if (input.title === undefined && input.done === undefined) {
+    throw new UserInputError("Provide at least one of title or done.");
+  }
+
+  const items = await updateStoredItems(
+    {
+      ...input,
+      promotedToTask: true,
+      notFoundMessage: NOT_FOUND,
+    },
+    db,
+  );
+  return items.map(toTask);
+}
+
+/**
+ * Single-task update. Unlike `updateTasks` this also accepts `fieldValues`,
+ * which are per-task and so have no meaningful bulk form.
+ */
+export async function updateTask(
+  input: {
+    ownerEmail: string;
+    id: string;
+    title?: string;
+    done?: boolean;
+    fieldValues?: Array<{ fieldId: string; value: FieldValueInput }>;
+    now?: string;
+  },
+  db: DbHandle = getDb(),
+): Promise<Task> {
+  const hasTaskPatch = input.title !== undefined || input.done !== undefined;
+  const hasFieldPatch = input.fieldValues !== undefined;
+
+  if (!hasTaskPatch && !hasFieldPatch) {
+    throw new UserInputError(
+      "Provide at least one of title, done, or fieldValues.",
+    );
+  }
+
+  if (!hasFieldPatch) {
+    const [task] = await updateTasks({ ...input, ids: [input.id] }, db);
+    if (!task) throw new NotFoundError(NOT_FOUND);
+    return task;
+  }
+
+  if (!hasTaskPatch) {
+    const task = await getTask(
+      { ownerEmail: input.ownerEmail, id: input.id },
+      db,
+    );
+    if (!task) throw new NotFoundError(NOT_FOUND);
+
+    await updateCustomFieldValuesByTaskId(
+      {
+        ownerEmail: input.ownerEmail,
+        taskId: input.id,
+        values: input.fieldValues!,
+        now: input.now,
+      },
+      db,
+    );
+    return task;
+  }
+
+  await assertStoredItemsExist(
+    {
+      ownerEmail: input.ownerEmail,
+      ids: [input.id],
+      promotedToTask: true,
+      notFoundMessage: NOT_FOUND,
+    },
+    db,
+  );
+
+  const patches = await prepareCustomFieldValuePatches(
+    {
+      ownerEmail: input.ownerEmail,
+      taskId: input.id,
+      values: input.fieldValues!,
+    },
+    db,
+  );
+  const timestamp = input.now ?? new Date().toISOString();
+
+  const task = await db.transaction(async (tx) => {
+    const [item] = await updateStoredItems(
+      {
+        ownerEmail: input.ownerEmail,
+        ids: [input.id],
+        promotedToTask: true,
+        title: input.title,
+        done: input.done,
+        now: timestamp,
+        notFoundMessage: NOT_FOUND,
+      },
+      tx,
+    );
+    await applyCustomFieldValuePatches(
+      {
+        ownerEmail: input.ownerEmail,
+        taskId: input.id,
+        patches,
+        updatedAt: timestamp,
+      },
+      tx,
+    );
+    return item ? toTask(item) : null;
+  });
+
+  if (!task) throw new NotFoundError(NOT_FOUND);
+  return task;
+}
+
+export async function deleteTasks(
+  input: {
+    ownerEmail: string;
+    ids: string[];
+  },
+  db: DbHandle = getDb(),
+): Promise<{ ok: true; deleted: number }> {
+  const ids = [...new Set(input.ids)];
+  await assertStoredItemsExist(
+    {
+      ownerEmail: input.ownerEmail,
+      ids,
+      promotedToTask: true,
+      notFoundMessage: NOT_FOUND,
+    },
+    db,
+  );
+
+  await db.transaction(async (tx) => {
+    await deleteCustomFieldValuesByTaskIds(
+      { ownerEmail: input.ownerEmail, taskIds: ids },
+      tx,
+    );
+    await deleteStoredItems(
+      {
+        ownerEmail: input.ownerEmail,
+        ids,
+        promotedToTask: true,
+      },
+      tx,
+    );
+  });
+
+  return { ok: true, deleted: ids.length };
+}
+
+export async function deleteTask(
+  input: {
+    ownerEmail: string;
+    id: string;
+  },
+  db: DbHandle = getDb(),
+): Promise<void> {
+  await deleteTasks({ ownerEmail: input.ownerEmail, ids: [input.id] }, db);
+}
+
+export async function reorderTasks(
+  input: {
+    ownerEmail: string;
+    taskIds: string[];
+    includeDone?: boolean;
+  },
+  db: DbHandle = getDb(),
+): Promise<{ tasks: Task[] }> {
+  const includeDone = input.includeDone === true;
+  await reorderStoredItems(
+    {
+      ownerEmail: input.ownerEmail,
+      promotedToTask: true,
+      orderedIds: input.taskIds,
+      includeDone,
+      idLabel: "taskIds",
+    },
+    db,
+  );
+
+  const tasksAfter = await listTasks(
+    {
+      ownerEmail: input.ownerEmail,
+      includeDone,
+    },
+    db,
+  );
+  return { tasks: tasksAfter };
+}
+
+export function toTask(item: StoredItem): Task {
+  const { promotedToTask: _, ...task } = item;
+  return task;
+}

package/corpus/templates/tasks/server/user-config/store.ts

@@ -0,0 +1,138 @@
+import { eq } from "drizzle-orm";
+
+import {
+  DEFAULT_TASK_CARD_FIELD_NAMES,
+  TASK_CARD_FIELD_LIMIT,
+} from "../../shared/visible-task-fields.js";
+import { listCustomFields } from "../custom-fields/store.js";
+import { getDb } from "../db/index.js";
+import { timestamp } from "../db/record-utils.js";
+import { userConfig } from "../db/schema.js";
+import type { DbHandle } from "../db/transaction.js";
+import { UserInputError } from "../errors.js";
+
+export { DEFAULT_TASK_CARD_FIELD_NAMES, TASK_CARD_FIELD_LIMIT };
+
+function fieldIdsForNames(
+  fieldNames: readonly string[],
+  fields: readonly { id: string; title: string }[],
+) {
+  const fieldsByName = new Map(
+    fields.map((field) => [field.title.toLowerCase(), field.id]),
+  );
+  return fieldNames
+    .map((name) => fieldsByName.get(name.toLowerCase()))
+    .filter((id): id is string => Boolean(id))
+    .slice(0, TASK_CARD_FIELD_LIMIT);
+}
+
+function parseStoredFieldIds(raw: string): string[] {
+  try {
+    const parsed = JSON.parse(raw);
+    if (!Array.isArray(parsed)) return [];
+    return parsed
+      .filter((value): value is string => typeof value === "string")
+      .slice(0, TASK_CARD_FIELD_LIMIT);
+  } catch {
+    return [];
+  }
+}
+
+function dedupeFieldIds(fieldIds: readonly string[]) {
+  return [...new Set(fieldIds)].slice(0, TASK_CARD_FIELD_LIMIT);
+}
+
+function filterKnownFieldIds(
+  fieldIds: readonly string[],
+  knownIds: ReadonlySet<string>,
+) {
+  return fieldIds.filter((fieldId) => knownIds.has(fieldId));
+}
+
+export async function getTaskCardFieldIds(
+  input: {
+    ownerEmail: string;
+  },
+  db: DbHandle = getDb(),
+): Promise<string[]> {
+  const { fields } = await listCustomFields({ ownerEmail: input.ownerEmail });
+  const knownIds = new Set(fields.map((field) => field.id));
+
+  const [row] = await db
+    .select()
+    .from(userConfig)
+    .where(eq(userConfig.ownerEmail, input.ownerEmail))
+    .limit(1);
+
+  if (!row) {
+    return fieldIdsForNames(DEFAULT_TASK_CARD_FIELD_NAMES, fields);
+  }
+
+  return filterKnownFieldIds(
+    parseStoredFieldIds(row.taskCardFieldIdsJson),
+    knownIds,
+  );
+}
+
+export async function setTaskCardFieldIds(
+  input: {
+    ownerEmail: string;
+    fieldIds: readonly string[];
+    now?: string;
+  },
+  db: DbHandle = getDb(),
+): Promise<string[]> {
+  const { fields } = await listCustomFields({ ownerEmail: input.ownerEmail });
+  const knownIds = new Set(fields.map((field) => field.id));
+  const next = dedupeFieldIds(input.fieldIds);
+
+  if (!next.every((fieldId) => knownIds.has(fieldId))) {
+    throw new UserInputError("fieldIds must reference existing custom fields.");
+  }
+
+  const updatedAt = timestamp(input.now);
+  const taskCardFieldIdsJson = JSON.stringify(next);
+
+  await db
+    .insert(userConfig)
+    .values({
+      ownerEmail: input.ownerEmail,
+      taskCardFieldIdsJson,
+      updatedAt,
+    })
+    .onConflictDoUpdate({
+      target: userConfig.ownerEmail,
+      set: { taskCardFieldIdsJson, updatedAt },
+    });
+
+  return next;
+}
+
+export async function removeTaskCardFieldId(
+  input: {
+    ownerEmail: string;
+    fieldId: string;
+    now?: string;
+  },
+  db: DbHandle = getDb(),
+): Promise<void> {
+  const [row] = await db
+    .select()
+    .from(userConfig)
+    .where(eq(userConfig.ownerEmail, input.ownerEmail))
+    .limit(1);
+
+  if (!row) return;
+
+  const next = parseStoredFieldIds(row.taskCardFieldIdsJson).filter(
+    (fieldId) => fieldId !== input.fieldId,
+  );
+
+  await db
+    .update(userConfig)
+    .set({
+      taskCardFieldIdsJson: JSON.stringify(next),
+      updatedAt: timestamp(input.now),
+    })
+    .where(eq(userConfig.ownerEmail, input.ownerEmail));
+}

package/corpus/templates/tasks/shared/app-state-tabs.ts

@@ -0,0 +1,15 @@
+const SAFE_TAB_ID_RE = /^[A-Za-z0-9_-]{1,96}$/;
+
+export function normalizeBrowserTabId(value: unknown): string | null {
+  if (typeof value !== "string") return null;
+  const trimmed = value.trim();
+  return SAFE_TAB_ID_RE.test(trimmed) ? trimmed : null;
+}
+
+export function appStateKeyForBrowserTab(
+  key: string,
+  browserTabId: unknown,
+): string {
+  const normalized = normalizeBrowserTabId(browserTabId);
+  return normalized ? `${key}:${normalized}` : key;
+}

package/corpus/templates/tasks/shared/boolean-param.ts

@@ -0,0 +1,22 @@
+/**
+ * Coerce booleans from HTTP query strings, CLI flags, or JSON bodies.
+ * Returns undefined when the value is absent.
+ */
+export function coerceBooleanParam(
+  value: string | boolean | null | undefined,
+): boolean | undefined {
+  if (value === undefined || value === null || value === "") return undefined;
+  if (value === true || value === "true" || value === "1") return true;
+  if (value === false || value === "false" || value === "0") return false;
+  return undefined;
+}
+
+/** URL/query flag written when Show all is enabled. */
+export const INCLUDE_DONE_QUERY_VALUE = "true";
+
+/** Parse includeDone from URL search params; defaults to false when absent. */
+export function parseIncludeDoneParam(
+  value: string | null | undefined,
+): boolean {
+  return coerceBooleanParam(value) ?? false;
+}

package/corpus/templates/tasks/shared/bulk-limits.ts

@@ -0,0 +1,7 @@
+/**
+ * Max ids accepted by a single bulk or reorder action.
+ *
+ * Reorder actions require every visible id, so this also caps the size of a
+ * list that can be reordered or select-all'd in one call.
+ */
+export const BULK_ID_LIMIT = 500;

package/corpus/templates/tasks/shared/list-screen-snapshot.ts

@@ -0,0 +1,90 @@
+export type AgentListSnapshot<TSummary> = {
+  totalCount: number;
+  truncated: boolean;
+};
+
+export function buildAgentListSnapshot<TItem, TSummary>(
+  items: TItem[],
+  cap: number,
+  toSummary: (item: TItem) => TSummary,
+): {
+  snapshot: TItem[];
+  list: AgentListSnapshot<TSummary> & { items: TSummary[] };
+} {
+  const snapshot = items.slice(0, cap);
+  return {
+    snapshot,
+    list: {
+      totalCount: items.length,
+      truncated: items.length > cap,
+      items: snapshot.map(toSummary),
+    },
+  };
+}
+
+export async function resolveSelectedFromList<
+  TItem extends { id: string },
+  TSummary,
+>(input: {
+  selectedId: string;
+  items: TItem[];
+  snapshot: TItem[];
+  toSummary: (item: TItem) => TSummary;
+  getById: (id: string) => Promise<TItem | null>;
+  inSnapshotKey: string;
+}): Promise<Record<string, unknown> | null> {
+  const fromSnapshot = input.snapshot.find(
+    (item) => item.id === input.selectedId,
+  );
+  if (fromSnapshot) {
+    return {
+      ...input.toSummary(fromSnapshot),
+      [input.inSnapshotKey]: true,
+    };
+  }
+
+  const fromList = input.items.find((item) => item.id === input.selectedId);
+  if (fromList) {
+    return {
+      ...input.toSummary(fromList),
+      [input.inSnapshotKey]: false,
+    };
+  }
+
+  const fetched = await input.getById(input.selectedId);
+  if (!fetched) return null;
+
+  return {
+    ...input.toSummary(fetched),
+    [input.inSnapshotKey]: false,
+  };
+}
+
+export function buildSelectionSnapshot<
+  TItem extends { id: string },
+  TSummary,
+>(input: {
+  selectedIds: string[];
+  items: TItem[];
+  toSummary: (item: TItem) => TSummary;
+}): {
+  selectionMode: true;
+  selectedCount: number;
+  selectedItems: TSummary[];
+  selectedIdsNotInVisibleList: string[];
+} {
+  const selectedIdSet = new Set(input.selectedIds);
+  const selectedInVisibleList = input.items.filter((item) =>
+    selectedIdSet.has(item.id),
+  );
+  const visibleIdSet = new Set(selectedInVisibleList.map((item) => item.id));
+
+  return {
+    selectionMode: true,
+    selectedCount: input.selectedIds.length,
+    selectedItems: selectedInVisibleList.map(input.toSummary),
+    selectedIdsNotInVisibleList: input.selectedIds.filter(
+      (id) => !visibleIdSet.has(id),
+    ),
+  };
+}

package/corpus/templates/tasks/shared/navigation.ts

@@ -0,0 +1,104 @@
+/** Agent-facing view names for navigate + view-screen parity. */
+import { INCLUDE_DONE_QUERY_VALUE } from "./boolean-param.js";
+
+export const NAV_VIEWS = [
+  "tasks",
+  "inbox",
+  "fields",
+  "extensions",
+  "team",
+] as const;
+
+export type NavView = (typeof NAV_VIEWS)[number];
+
+export const VIEW_ROUTES: Record<NavView, string> = {
+  tasks: "/tasks",
+  inbox: "/inbox",
+  fields: "/fields",
+  extensions: "/extensions",
+  team: "/team",
+};
+
+const NAV_VIEW_ALIAS_NAMES = ["home", "ask"] as const;
+
+export type NavViewAlias = (typeof NAV_VIEW_ALIAS_NAMES)[number];
+
+export const NAV_VIEW_ALIASES: Record<string, NavView> = {
+  home: "tasks",
+  ask: "tasks",
+};
+
+export const NAV_VIEW_INPUTS = [...NAV_VIEWS, ...NAV_VIEW_ALIAS_NAMES] as const;
+
+export type NavViewInput = (typeof NAV_VIEW_INPUTS)[number];
+
+export function resolveNavView(view: NavViewInput): NavView {
+  return view in NAV_VIEW_ALIASES
+    ? NAV_VIEW_ALIASES[view as NavViewAlias]
+    : (view as NavView);
+}
+
+export interface NavigationState {
+  view: NavView;
+  path?: string;
+  includeDone?: boolean;
+  taskId?: string;
+  inboxItemId?: string;
+  fieldId?: string;
+}
+
+export interface NavigateCommand {
+  view?: NavView;
+  includeDone?: boolean;
+  taskId?: string;
+  inboxItemId?: string;
+  fieldId?: string;
+}
+
+/** UI bulk-selection state synced from list views for view-screen. */
+export interface ListSelectionAppState {
+  selectionMode: boolean;
+  selectedIds: string[];
+}
+
+/** UI-selected custom field columns shown on task cards. */
+export interface TaskCardFieldsState {
+  fieldIds: string[];
+}
+
+export function viewForPath(pathname: string): NavView {
+  for (const view of NAV_VIEWS) {
+    if (pathname.startsWith(VIEW_ROUTES[view])) return view;
+  }
+  return "tasks";
+}
+
+export function pathForView(view?: NavView): string {
+  if (view && view in VIEW_ROUTES) return VIEW_ROUTES[view];
+  return VIEW_ROUTES.tasks;
+}
+
+export function buildNavigatePath(
+  basePath: string,
+  command: NavigateCommand,
+  current?: Pick<NavigationState, "includeDone">,
+): string {
+  const params = new URLSearchParams();
+  if (command.taskId) params.set("task", command.taskId);
+  if (command.inboxItemId) params.set("inboxItem", command.inboxItemId);
+  if (command.fieldId) params.set("field", command.fieldId);
+  const includeDone =
+    command.includeDone !== undefined
+      ? command.includeDone
+      : navigatesToTasks(basePath) && current?.includeDone === true;
+  if (includeDone) params.set("includeDone", INCLUDE_DONE_QUERY_VALUE);
+  const query = params.toString();
+  return query ? `${basePath}?${query}` : basePath;
+}
+
+function navigatesToTasks(basePath: string): boolean {
+  return (
+    basePath === VIEW_ROUTES.tasks ||
+    basePath.startsWith(`${VIEW_ROUTES.tasks}/`)
+  );
+}

package/corpus/templates/tasks/shared/visible-task-fields.ts

@@ -0,0 +1,2 @@
+export const DEFAULT_TASK_CARD_FIELD_NAMES = ["Priority", "Due date"] as const;
+export const TASK_CARD_FIELD_LIMIT = 3;

package/corpus/templates/tasks/ssr-entry.ts

@@ -0,0 +1,15 @@
+/**
+ * SSR entry point for Nitro.
+ * Wraps React Router's request handler so Nitro can use it as a service.
+ */
+import { createRequestHandler } from "react-router";
+
+const handler = createRequestHandler(
+  () => import("virtual:react-router/server-build"),
+);
+
+export default {
+  async fetch(request: Request) {
+    return handler(request);
+  },
+};