@skillcdn/console 0.1.9 → 0.1.11

package/src/cli/help.ts

@@ -1,4 +1,5 @@
 import {
+  DEFAULT_PAGE_LIMIT,
   MAX_AGENT_LENGTH,
   MAX_ARTIFACTS_PER_RUN,
   MAX_BODY_LENGTH,
@@ -51,6 +52,22 @@ const MARKDOWN = `Markdown, up to ${MAX_BODY_LENGTH} characters`;
 const DOCUMENT_PATH = `a path of lowercase letters, digits and hyphens, with slashes between its folders (guides/onboarding), up to ${MAX_DOCUMENT_PATH_LENGTH} characters; it does not change once written`;
 const DOCUMENT_REFUSALS = ["document.not_found: no page has that path in this project"];
 
+const DAY = "a day as 2026-10-24, today, tomorrow, or +7 for seven days from today";
+const TASK_FIELD_FLAGS =
+  "[--state <state>] [--priority <priority>] [--category <key>] [--goal <id>] [--starts <day>] [--due <day>] [--assignee <login|me>] [--parent <number|id>]";
+const TASK_FIELD_LIMITS = [
+  `starts, due: ${DAY}; the due day is not before the start`,
+  "category: the key of one of the workspace's categories (console categories); goal: the id of one of the project's goals (console goals)",
+  "assignee: a login of the workspace, or me; parent: a task of the project",
+];
+const TASK_FIELD_REFUSALS = [
+  "task.invalid_category: no category has that key",
+  "task.invalid_goal: the goal is not one of this project",
+  "task.invalid_dates: the due day is before the start",
+  "task.invalid_assignee: the person may not work in the project",
+  "task.invalid_parent: the parent is not a task of the project, or would make a loop",
+];
+
 export const COMMAND_HELP: Readonly<Record<string, CommandHelp>> = {
   login: {
     usage: "login --url <origin> [--agent <name>] [--token-stdin]",
@@ -82,18 +99,51 @@ export const COMMAND_HELP: Readonly<Record<string, CommandHelp>> = {
       "Says which project this directory works in: writes .skillcdn-console.json here, which the commands read from this directory or one above it, and which is meant to be committed. --project <key> on any command, or CONSOLE_PROJECT in the environment, wins over it.",
     refusals: ["project.not_found: no project has the key, or it is not yours to see"],
   },
-  tasks: {
-    usage: "tasks [--state <state>]",
+  work: {
+    usage: "work",
     about:
-      "The tasks on the board, newest first: number, state, priority, title, who owns and works on each, and what waits on it. States: idea, ready, in_progress, in_review, done, dropped.",
+      "What is on your plate across the projects you may see: the open tasks assigned to you, the sooner due first, each with its project; and the decisions waiting for a person. Needs no project.",
+  },
+  tasks: {
+    usage:
+      "tasks [--state <state>] [--open] [--mine] [--category <key>] [--goal <id>] [--due <day|today|week|overdue>] [--limit <n>] [--offset <n>]",
+    about: `The tasks on the board, newest first: number, state, priority, title, who owns and works on each, its category and its due day, and what waits on it. --open keeps the ones not done or dropped, --mine those assigned to you, --category and --goal those sorted into one, --due those due by a day: today, within the week, or overdue (the open ones past their day). A page at a time: ${DEFAULT_PAGE_LIMIT} unless --limit says otherwise, from --offset on; a last line says when there is more. States: idea, ready, in_progress, in_review, done, dropped.`,
   },
   task: {
+    usage: `task <number|id>  |  task new <title> [--body <markdown>|--file <path>] ${TASK_FIELD_FLAGS}  |  task edit <number|id> [--title <title>] [--body <markdown>|--file <path>] ${TASK_FIELD_FLAGS}`,
+    about:
+      "One task in full, with its plan (category, goal, start and due days), what happened to it (when it was started and done, which the board keeps itself), the decisions about it and the runs on it; or a new task written down; or a task changed, only in what the flags say, where none clears a field (priorities: low, normal, high, urgent).",
+    limits: [
+      `title: one line, up to ${MAX_TITLE_LENGTH} characters`,
+      `body: ${MARKDOWN}`,
+      ...TASK_FIELD_LIMITS,
+    ],
+    refusals: ["task.not_found: no task has that number or id", ...TASK_FIELD_REFUSALS],
+  },
+  goals: {
+    usage: "goals",
+    about:
+      "The roadmap of the project: its goals, the active first, each with its id, its state (planned, active, done, dropped), its target day, and how far it is, counted from the tasks that work towards it.",
+  },
+  goal: {
     usage:
-      "task <number|id>  |  task new <title> [--body <markdown>|--file <path>] [--state <state>] [--priority <priority>]",
+      'goal <id>  |  goal new "<title>" [--body <markdown>|--file <path>] [--state <state>] [--due <day>]  |  goal edit <id> [--title <title>] [--body <markdown>|--file <path>] [--state <state>] [--due <day|none>]',
+    about:
+      "One goal in full, with the tasks that work towards it; or a goal set on the roadmap, for an owner of the project; or one changed, only in what the flags say. A task works towards a goal through its --goal.",
+    limits: [
+      `title: one line, up to ${MAX_TITLE_LENGTH} characters`,
+      `body: ${MARKDOWN}`,
+      `due: ${DAY}`,
+    ],
+    refusals: [
+      "goal.not_found: no goal of this project has that id",
+      "auth.forbidden: only an owner of the project sets its roadmap",
+    ],
+  },
+  categories: {
+    usage: "categories",
     about:
-      "One task in full, with the decisions about it and the runs on it; or a new task written down (priorities: low, normal, high, urgent).",
-    limits: [`title: one line, up to ${MAX_TITLE_LENGTH} characters`, `body: ${MARKDOWN}`],
-    refusals: ["task.not_found: no task has that number or id"],
+      "The categories tasks are sorted into, the same in every project: each with its key, which --category takes, its name and its colour. An administrator keeps them on the console's Categories page.",
   },
   skills: {
     usage: "skills",
@@ -103,11 +153,10 @@ export const COMMAND_HELP: Readonly<Record<string, CommandHelp>> = {
   take: {
     usage: "take <number|id> [--agent <name>]",
     about:
-      "Takes a task: a run begins, and the task is in progress and the person's. One agent at a time per task. --agent is what people see at work; left out, it is what the person called the token.",
+      "Takes a task: a run begins, and the task is in progress and the person's. A run still open on the task is taken over, since the board cannot know whether its agent still runs: it ends as abandoned, the feed says who took over, and that agent is refused on its next command. Look before taking (console task <number> lists the runs, with when each was last heard from), and take a task another agent was heard from on lately only when told to. --agent is what people see at work; left out, it is what the person called the token.",
     limits: [`agent: one line, up to ${MAX_AGENT_LENGTH} characters`],
     refusals: [
       "task.not_found: no task has that number or id",
-      "run.task_taken: a run is open on the task already; console runs --open --mine shows whether it is yours",
       "run.task_closed: the task is done or dropped",
     ],
   },
@@ -157,8 +206,8 @@ export const COMMAND_HELP: Readonly<Record<string, CommandHelp>> = {
     refusals: ["decision.not_found: no decision has that id"],
   },
   decisions: {
-    usage: "decisions [--open]",
-    about: "The decisions on the board, the waiting first; --open keeps only those.",
+    usage: "decisions [--open] [--limit <n>] [--offset <n>]",
+    about: `The decisions on the board, the waiting first; --open keeps only those. A page at a time: ${DEFAULT_PAGE_LIMIT} unless --limit says otherwise, from --offset on.`,
   },
   finish: {
     usage: 'finish [--summary "<markdown>"|--file <path>]',
@@ -181,9 +230,8 @@ export const COMMAND_HELP: Readonly<Record<string, CommandHelp>> = {
     refusals: RUN_REFUSALS,
   },
   runs: {
-    usage: "runs [--task <number|id>] [--open] [--mine]",
-    about:
-      "The runs, newest first: agents at work and what they did. --mine keeps those begun with this token.",
+    usage: "runs [--task <number|id>] [--open] [--mine] [--limit <n>] [--offset <n>]",
+    about: `The runs, newest first, each with when its agent was last heard from: --open keeps the ones not over, --mine those begun with this token. A page at a time: ${DEFAULT_PAGE_LIMIT} unless --limit says otherwise, from --offset on.`,
   },
   run: {
     usage: "run <id>",
@@ -262,6 +310,8 @@ Usage: console <command> [arguments] [--json] [--url <origin>] [--project <key>]
 
 const CLOSING = `Options everywhere: --json answers with the console's own JSON; --url names another console;
 --project names the project to work in, over CONSOLE_PROJECT and over what console use kept here.
+A listing (tasks, decisions, runs) is a page at a time: --limit <n> and --offset <n>, and a last line
+says when there is more, so that nothing is read that is not needed.
 Commands on a run (report, hand-in, ask, finish, fail) act on your one open run in the project;
 with several open, say which with --run <id>. A Markdown body given as - is read from standard input.
 console help <command> says what each command takes, the limits the console holds it to, and
@@ -283,7 +333,19 @@ const SECTIONS: readonly { readonly title: string; readonly commands: readonly s
   },
   {
     title: "The board",
-    commands: ["tasks", "task", "decisions", "decision", "runs", "run", "skills"],
+    commands: [
+      "work",
+      "tasks",
+      "task",
+      "goals",
+      "goal",
+      "categories",
+      "decisions",
+      "decision",
+      "runs",
+      "run",
+      "skills",
+    ],
   },
   { title: "Working", commands: ["take", "report", "hand-in", "ask", "finish", "fail", "abandon"] },
   {

package/src/client.ts

@@ -1,6 +1,7 @@
 import {
   AUTH_ROUTES,
   CLAIM_PATH,
+  categoryPath,
   connectPath,
   personTokensPath,
   projectPath,
@@ -10,6 +11,10 @@ import {
 import {
   type RestAnswerInput,
   type RestArtifactInput,
+  type RestCategories,
+  type RestCategory,
+  type RestCategoryInput,
+  type RestCategoryPatch,
   type RestClaim,
   type RestConnectInput,
   type RestConnection,
@@ -22,6 +27,10 @@ import {
   type RestDocumentInput,
   type RestDocuments,
   type RestEvents,
+  type RestGoal,
+  type RestGoalInput,
+  type RestGoalPatch,
+  type RestGoals,
   type RestMe,
   type RestMember,
   type RestMemberInput,
@@ -50,6 +59,9 @@ import {
   type RestTokens,
   type RestVersion,
   type RestVersions,
+  type RestWork,
+  restCategoriesSchema,
+  restCategorySchema,
   restClaimSchema,
   restConnectionSchema,
   restConnectRequestSchema,
@@ -59,6 +71,8 @@ import {
   restDocumentsSchema,
   restErrorSchema,
   restEventsSchema,
+  restGoalSchema,
+  restGoalsSchema,
   restMemberSchema,
   restMembersSchema,
   restMeSchema,
@@ -75,6 +89,7 @@ import {
   restTokensSchema,
   restVersionSchema,
   restVersionsSchema,
+  restWorkSchema,
 } from "./schemas.js";
 import type { TaskState } from "./vocabulary.js";
 
@@ -135,6 +150,27 @@ export interface EventFilter {
   readonly document?: string | undefined;
 }
 
+/** One page of a listing: how many items, from which one on; the server's bounds apply. */
+export interface Page {
+  readonly limit?: number | undefined;
+  readonly offset?: number | undefined;
+}
+
+/** What the board is narrowed to: one state, the open ones, a category, a goal, an assignee, or what is due by a day. */
+export interface TaskFilter extends Page {
+  readonly state?: TaskState | undefined;
+  /** True for the tasks not done or dropped; false for the rest. */
+  readonly open?: boolean | undefined;
+  /** The key of a category. */
+  readonly category?: string | undefined;
+  /** The id of a goal. */
+  readonly goal?: string | undefined;
+  /** The id of the person the tasks are assigned to. */
+  readonly assignee?: string | undefined;
+  /** A day (`2026-10-20`): the tasks due on it or before it. */
+  readonly dueBy?: string | undefined;
+}
+
 /** What a folder's listing, or a search, of the documents is narrowed to. */
 export interface DocumentFilter {
   /** The folder to list, `""` or left out for the root. */
@@ -153,20 +189,24 @@ export interface ProjectClient {
   get(signal?: AbortSignal): Promise<RestProject>;
   /** Changes the project's settings; for an owner. */
   update(patch: RestProjectPatch): Promise<RestProject>;
+  /** Sets the project's own image for its mark, sent as a form; for an owner on the console's own pages. */
+  setIcon(input: FileUpload): Promise<RestProject>;
+  /** Takes the image away: the mark is the symbol on the colour again. */
+  removeIcon(): Promise<RestProject>;
   /** Those listed in the project, by login. */
   members(signal?: AbortSignal): Promise<RestMembers>;
   /** Lists a person of the workspace in the project; for an owner. */
   addMember(input: RestMemberInput): Promise<RestMember>;
   updateMember(personId: string, patch: RestMemberPatch): Promise<RestMember>;
   removeMember(personId: string): Promise<void>;
-  tasks(filter?: { readonly state?: TaskState }, signal?: AbortSignal): Promise<RestTasks>;
+  tasks(filter?: TaskFilter, signal?: AbortSignal): Promise<RestTasks>;
   /** One task, by its id or by its number. */
   task(ref: string, signal?: AbortSignal): Promise<RestTask>;
   createTask(input: RestTaskInput): Promise<RestTask>;
   updateTask(id: string, patch: RestTaskPatch): Promise<RestTask>;
-  /** The decisions, or only those that wait, or only those about one task. */
+  /** The decisions, or only those that wait, or only those about one task; a page of them. */
   decisions(
-    filter?: { readonly open?: boolean; readonly task?: string },
+    filter?: { readonly open?: boolean; readonly task?: string } & Page,
     signal?: AbortSignal,
   ): Promise<RestDecisions>;
   decision(id: string, signal?: AbortSignal): Promise<RestDecision>;
@@ -179,9 +219,9 @@ export interface ProjectClient {
   answerDecision(id: string, input: RestAnswerInput): Promise<RestDecision>;
   /** Grows a decision's record: its context, or what followed. */
   updateDecision(id: string, patch: RestDecisionPatch): Promise<RestDecision>;
-  /** The runs, newest first; or only those on one task, only the open ones, only the asker's own. */
+  /** The runs, newest first; or only those on one task, only the open ones, only the asker's own; a page of them. */
   runs(
-    filter?: { readonly task?: string; readonly open?: boolean; readonly mine?: boolean },
+    filter?: { readonly task?: string; readonly open?: boolean; readonly mine?: boolean } & Page,
     signal?: AbortSignal,
   ): Promise<RestRuns>;
   run(id: string, signal?: AbortSignal): Promise<RestRun>;
@@ -221,6 +261,12 @@ export interface ProjectClient {
   attachFile(path: string, input: FileUpload): Promise<RestDocument>;
   /** Where the bytes of a file attached to a document are read, by the file's id. */
   documentFileUrl(path: string, fileId: string): string;
+  /** The roadmap (ADR-0019): the goals, the active first, each with its tasks counted by state. */
+  goals(signal?: AbortSignal): Promise<RestGoals>;
+  goal(id: string, signal?: AbortSignal): Promise<RestGoal>;
+  /** Sets a goal; for an owner, with a session or a token. */
+  createGoal(input: RestGoalInput): Promise<RestGoal>;
+  updateGoal(id: string, patch: RestGoalPatch): Promise<RestGoal>;
 }
 
 export interface ConsoleClient {
@@ -238,6 +284,15 @@ export interface ConsoleClient {
   project(key: string): ProjectClient;
   /** The workspace's own events, the ones about no project, after event number `after`. */
   events(after: number, signal?: AbortSignal): Promise<RestEvents>;
+  /** The categories tasks are sorted into (ADR-0019), by name. */
+  categories(signal?: AbortSignal): Promise<RestCategories>;
+  /** Makes a category; for an administrator signed in. */
+  createCategory(input: RestCategoryInput): Promise<RestCategory>;
+  updateCategory(key: string, patch: RestCategoryPatch): Promise<RestCategory>;
+  /** Removes a category no task uses; for an administrator signed in. */
+  removeCategory(key: string): Promise<void>;
+  /** What is on the asker's plate across the projects they may see: their open tasks, and the decisions waiting. */
+  work(signal?: AbortSignal): Promise<RestWork>;
   /** The tokens of whoever asks. */
   tokens(signal?: AbortSignal): Promise<RestTokens>;
   /** The tokens of another person: for an administrator. */
@@ -336,6 +391,8 @@ export function createClient(options: ClientOptions = {}): ConsoleClient {
 
   const flag = (value: boolean | undefined): string | undefined =>
     value === undefined ? undefined : String(value);
+  const number = (value: number | undefined): string | undefined =>
+    value === undefined ? undefined : String(value);
 
   /** A file as the parts of a form: the bytes with their name and type, and the label. */
   const formOf = (input: FileUpload): FormData => {
@@ -360,6 +417,8 @@ export function createClient(options: ClientOptions = {}): ConsoleClient {
       key,
       get: (signal) => request("GET", `${base}${at()}`, undefined, restProjectSchema, signal),
       update: (patch) => request("PATCH", `${base}${at()}`, patch, restProjectSchema),
+      setIcon: (input) => request("POST", `${base}${at()}/icon`, formOf(input), restProjectSchema),
+      removeIcon: () => request("DELETE", `${base}${at()}/icon`, undefined, restProjectSchema),
       members: (signal) =>
         request("GET", `${base}${at("members")}`, undefined, restMembersSchema, signal),
       addMember: (input) => request("POST", `${base}${at("members")}`, input, restMemberSchema),
@@ -370,7 +429,16 @@ export function createClient(options: ClientOptions = {}): ConsoleClient {
       tasks: (filter = {}, signal) =>
         request(
           "GET",
-          withQuery(at("tasks"), { state: filter.state }),
+          withQuery(at("tasks"), {
+            state: filter.state,
+            open: flag(filter.open),
+            category: filter.category,
+            goal: filter.goal,
+            assignee: filter.assignee,
+            dueBy: filter.dueBy,
+            limit: number(filter.limit),
+            offset: number(filter.offset),
+          }),
           undefined,
           restTasksSchema,
           signal,
@@ -383,7 +451,12 @@ export function createClient(options: ClientOptions = {}): ConsoleClient {
       decisions: (filter = {}, signal) =>
         request(
           "GET",
-          withQuery(at("decisions"), { open: flag(filter.open), task: filter.task }),
+          withQuery(at("decisions"), {
+            open: flag(filter.open),
+            task: filter.task,
+            limit: number(filter.limit),
+            offset: number(filter.offset),
+          }),
           undefined,
           restDecisionsSchema,
           signal,
@@ -411,6 +484,8 @@ export function createClient(options: ClientOptions = {}): ConsoleClient {
             task: filter.task,
             open: flag(filter.open),
             mine: flag(filter.mine),
+            limit: number(filter.limit),
+            offset: number(filter.offset),
           }),
           undefined,
           restRunsSchema,
@@ -485,6 +560,13 @@ export function createClient(options: ClientOptions = {}): ConsoleClient {
         request("POST", `${base}${at("docs", path)}/files`, formOf(input), restDocumentSchema),
       documentFileUrl: (path, fileId) =>
         `${base}${at("docs", path)}/files/${encodeURIComponent(fileId)}`,
+      goals: (signal) =>
+        request("GET", `${base}${at("goals")}`, undefined, restGoalsSchema, signal),
+      goal: (id, signal) =>
+        request("GET", `${base}${at("goals", id)}`, undefined, restGoalSchema, signal),
+      createGoal: (input) => request("POST", `${base}${at("goals")}`, input, restGoalSchema),
+      updateGoal: (id, patch) =>
+        request("PATCH", `${base}${at("goals", id)}`, patch, restGoalSchema),
     };
   };
 
@@ -507,6 +589,15 @@ export function createClient(options: ClientOptions = {}): ConsoleClient {
         restEventsSchema,
         signal,
       ),
+    categories: (signal) =>
+      request("GET", `${base}${REST_ROUTES.categories}`, undefined, restCategoriesSchema, signal),
+    createCategory: (input) =>
+      request("POST", `${base}${REST_ROUTES.categories}`, input, restCategorySchema),
+    updateCategory: (key, patch) =>
+      request("PATCH", `${base}${categoryPath(key)}`, patch, restCategorySchema),
+    removeCategory: (key) => request("DELETE", `${base}${categoryPath(key)}`, undefined, undefined),
+    work: (signal) =>
+      request("GET", `${base}${REST_ROUTES.work}`, undefined, restWorkSchema, signal),
     tokens: (signal) =>
       request("GET", `${base}${REST_ROUTES.tokens}`, undefined, restTokensSchema, signal),
     createToken: (input) =>

package/src/components/board.tsx

@@ -1,10 +1,21 @@
 import type { ReactNode } from "react";
-import { type RestTask, TASK_STATES, type TaskState } from "../api.js";
+import {
+  type RestCategory,
+  type RestGoal,
+  type RestPerson,
+  type RestTask,
+  TASK_STATES,
+  type TaskState,
+} from "../api.js";
 import { useWords } from "../i18n/index.js";
-import { Avatar, Badge, cx, PriorityBadge } from "./ui.js";
+import type { BoardFilter } from "../router.js";
+import { Avatar, Badge, Button, CategoryBadge, cx, DueBadge, PriorityBadge } from "./ui.js";
 
-// The board: one column per state, the tasks in it, newest first. It takes its data as props
-// and nothing from the network; what it is told on a click goes back up.
+// The board: one column per state, the tasks in it, the sooner due first and the newest after.
+// A card says what a person needs at a glance and nothing more: the number and the title, the
+// category, what is due, who is on it, and what blocks it. Whether an agent is at it is not
+// said, since the board cannot know (ADR-0020); the task's page shows its runs. It takes its
+// data as props and nothing from the network; what it is told on a click goes back up.
 
 export interface BoardProps {
   readonly tasks: readonly RestTask[];
@@ -13,6 +24,8 @@ export interface BoardProps {
   readonly onOpen: (task: RestTask) => void;
   /** Called when a person moves a task to another column. Left out, the board is read-only. */
   readonly onMove?: ((task: RestTask, state: TaskState) => void) | undefined;
+  /** The day to count due days from; the browser's today when left out. */
+  readonly today?: string | undefined;
   /** What a column shows when it has nothing; the way to write the first task, for example. */
   readonly empty?: ReactNode;
 }
@@ -22,6 +35,7 @@ export function TaskCard(props: {
   readonly href: string;
   readonly onOpen: (task: RestTask) => void;
   readonly onMove?: ((task: RestTask, state: TaskState) => void) | undefined;
+  readonly today?: string | undefined;
 }) {
   const words = useWords();
   const { task } = props;
@@ -40,20 +54,16 @@ export function TaskCard(props: {
         <span className="sc-card-number">#{task.number}</span> {task.title}
       </a>
       <div className="sc-card-meta">
+        {task.category !== null && <CategoryBadge category={task.category} />}
         <PriorityBadge priority={task.priority} />
+        {task.dueOn !== null && (
+          <DueBadge dueOn={task.dueOn} state={task.state} today={props.today} />
+        )}
         {task.openDecisions > 0 && (
           <Badge tone="warning" title={words.board.decisionsTitle}>
             {words.board.decisions(task.openDecisions)}
           </Badge>
         )}
-        {task.openRuns > 0 && (
-          <Badge tone="accent" title={words.board.agentAtWorkTitle}>
-            {words.board.agentAtWork}
-          </Badge>
-        )}
-        {task.links.length > 0 && (
-          <Badge tone="neutral">{words.board.links(task.links.length)}</Badge>
-        )}
         <span className="sc-card-spacer" />
         {task.assignee !== null && <Avatar person={task.assignee} size="sm" />}
       </div>
@@ -76,12 +86,26 @@ export function TaskCard(props: {
   );
 }
 
+/** The order a column reads in: what is due soonest first, what has no day after, the newest first among those. */
+export function byDue(a: RestTask, b: RestTask): number {
+  if (a.dueOn !== b.dueOn) {
+    if (a.dueOn === null) {
+      return 1;
+    }
+    if (b.dueOn === null) {
+      return -1;
+    }
+    return a.dueOn.localeCompare(b.dueOn);
+  }
+  return b.number - a.number;
+}
+
 export function Board(props: BoardProps) {
   const words = useWords();
   return (
     <div className="sc-board">
       {TASK_STATES.map((state) => {
-        const tasks = props.tasks.filter((task) => task.state === state);
+        const tasks = props.tasks.filter((task) => task.state === state).sort(byDue);
         return (
           <section
             key={state}
@@ -100,6 +124,7 @@ export function Board(props: BoardProps) {
                   href={props.taskHref(task)}
                   onOpen={props.onOpen}
                   onMove={props.onMove}
+                  today={props.today}
                 />
               ))}
               {tasks.length === 0 && state === "idea" && props.empty}
@@ -110,3 +135,138 @@ export function Board(props: BoardProps) {
     </div>
   );
 }
+
+/** What the filter keeps of the board: a category or none, a goal or none, a person, one's own. */
+export function filterTasks(
+  tasks: readonly RestTask[],
+  filter: BoardFilter,
+  me?: RestPerson | undefined,
+): RestTask[] {
+  return tasks.filter((task) => {
+    if (filter.category !== undefined && (task.category?.key ?? "") !== filter.category) {
+      return false;
+    }
+    if (filter.goal !== undefined && (task.goalId ?? "") !== filter.goal) {
+      return false;
+    }
+    if (filter.person !== undefined && task.assignee?.id !== filter.person) {
+      return false;
+    }
+    if (filter.mine === true && (me === undefined || task.assignee?.id !== me.id)) {
+      return false;
+    }
+    return true;
+  });
+}
+
+export interface BoardFiltersProps {
+  readonly filter: BoardFilter;
+  readonly categories: readonly RestCategory[];
+  readonly goals: readonly RestGoal[];
+  readonly people: readonly RestPerson[];
+  /** Whoever is looking, for "mine". */
+  readonly me?: RestPerson | undefined;
+  /** How many tasks the filter keeps, of how many. */
+  readonly shown: number;
+  readonly total: number;
+  /** Called with the filter as it is to be: the composition shows the board at its address. */
+  readonly onChange: (filter: BoardFilter) => void;
+}
+
+/** The ways to narrow the board, each a change of its address (ADR-0010). */
+export function BoardFilters(props: BoardFiltersProps) {
+  const words = useWords().board.filters;
+  const { filter } = props;
+  const narrowed = Object.keys(filter).length > 0;
+  const goals = props.goals.filter((goal) => goal.state !== "dropped");
+  const change = (patch: BoardFilter, drop?: keyof BoardFilter) => {
+    const next: Record<string, unknown> = { ...filter, ...patch };
+    if (drop !== undefined) {
+      delete next[drop];
+    }
+    props.onChange(next as BoardFilter);
+  };
+  return (
+    <form
+      className="sc-filters"
+      aria-label={words.aria}
+      onSubmit={(event) => event.preventDefault()}
+    >
+      <label className="sc-field sc-field-inline">
+        <span className="sc-visually-hidden">{words.anyCategory}</span>
+        <select
+          className="sc-input"
+          value={filter.category ?? "*"}
+          onChange={(event) =>
+            event.target.value === "*"
+              ? change({}, "category")
+              : change({ category: event.target.value })
+          }
+        >
+          <option value="*">{words.anyCategory}</option>
+          <option value="">{words.noCategory}</option>
+          {props.categories.map((category) => (
+            <option key={category.key} value={category.key}>
+              {category.name}
+            </option>
+          ))}
+        </select>
+      </label>
+      {goals.length > 0 && (
+        <label className="sc-field sc-field-inline">
+          <span className="sc-visually-hidden">{words.anyGoal}</span>
+          <select
+            className="sc-input"
+            value={filter.goal ?? "*"}
+            onChange={(event) =>
+              event.target.value === "*" ? change({}, "goal") : change({ goal: event.target.value })
+            }
+          >
+            <option value="*">{words.anyGoal}</option>
+            <option value="">{words.noGoal}</option>
+            {goals.map((goal) => (
+              <option key={goal.id} value={goal.id}>
+                {goal.title}
+              </option>
+            ))}
+          </select>
+        </label>
+      )}
+      <label className="sc-field sc-field-inline">
+        <span className="sc-visually-hidden">{words.everyone}</span>
+        <select
+          className="sc-input"
+          value={filter.mine === true ? "mine" : (filter.person ?? "*")}
+          onChange={(event) => {
+            const value = event.target.value;
+            if (value === "*") {
+              change({ mine: undefined, person: undefined });
+              return;
+            }
+            if (value === "mine") {
+              change({ mine: true, person: undefined });
+              return;
+            }
+            change({ person: value, mine: undefined });
+          }}
+        >
+          <option value="*">{words.everyone}</option>
+          {props.me !== undefined && <option value="mine">{words.mine}</option>}
+          {props.people
+            .filter((person) => person.id !== props.me?.id)
+            .map((person) => (
+              <option key={person.id} value={person.id}>
+                {person.login}
+              </option>
+            ))}
+        </select>
+      </label>
+      <span className="sc-filters-count sc-muted">{words.showing(props.shown, props.total)}</span>
+      {narrowed && (
+        <Button variant="ghost" size="sm" onClick={() => props.onChange({})}>
+          {words.clear}
+        </Button>
+      )}
+    </form>
+  );
+}