@skillcdn/console 0.1.17 → 0.1.18

package/src/client.ts

@@ -107,7 +107,7 @@ import {
   restVersionsSchema,
   restWorkSchema,
 } from "./schemas.js";
-import type { TaskState } from "./vocabulary.js";
+import type { GoalState, TaskState } from "./vocabulary.js";
 
 // The client of the console's REST API: what the default console and a custom one talk to the
 // server with, and what the command line, a script or a console of a person's own talks to it
@@ -154,6 +154,12 @@ export interface ClientOptions {
    * the page's own origin is what the console answers to.
    */
   readonly token?: string;
+  /**
+   * What the client calls itself, sent as `user-agent` where the platform lets a client say
+   * (Node; a browser keeps its own): the command sends its product token, by which the console
+   * holds it to the versions it takes (ADR-0025).
+   */
+  readonly userAgent?: string;
 }
 
 export class ApiError extends Error {
@@ -189,6 +195,13 @@ export interface Page {
 }
 
 /** What the board is narrowed to: one state, the open ones, a category, a goal, an assignee, or what is due by a day. */
+/** What the roadmap is narrowed by: the goals in one state, or sorted into one category (ADR-0026). */
+export interface GoalFilter {
+  readonly state?: GoalState | undefined;
+  /** The key of a category of the workspace. */
+  readonly category?: string | undefined;
+}
+
 export interface TaskFilter extends Page {
   readonly state?: TaskState | undefined;
   /** True for the tasks not done or dropped; false for the rest. */
@@ -302,7 +315,8 @@ export interface ProjectClient {
   /** 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>;
+  /** The roadmap, or what the filter keeps of it: the active goals first. */
+  goals(filter?: GoalFilter, 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>;
@@ -381,7 +395,8 @@ const INVALID = "The server answered unexpectedly.";
 export function createClient(options: ClientOptions = {}): ConsoleClient {
   const base = (options.baseUrl ?? "").replace(/\/+$/, "");
   const send = options.fetch ?? ((input, init) => fetch(input, init));
-  const { token } = options;
+  const { token, userAgent } = options;
+  const named: Record<string, string> = userAgent === undefined ? {} : { "user-agent": userAgent };
 
   const withQuery = (path: string, params: Record<string, string | undefined>): string => {
     const query = new URLSearchParams();
@@ -423,6 +438,7 @@ export function createClient(options: ClientOptions = {}): ConsoleClient {
           // A form names its own type, boundary included; everything else is JSON.
           ...(body === undefined || form ? {} : { "content-type": "application/json" }),
           ...(token === undefined ? {} : { authorization: `Bearer ${token}` }),
+          ...named,
         },
         ...(body === undefined ? {} : { body: form ? body : JSON.stringify(body) }),
       });
@@ -457,7 +473,10 @@ export function createClient(options: ClientOptions = {}): ConsoleClient {
         method: "GET",
         ...(signal === undefined ? {} : { signal }),
         credentials: token === undefined ? "same-origin" : "omit",
-        headers: token === undefined ? {} : { authorization: `Bearer ${token}` },
+        headers: {
+          ...(token === undefined ? {} : { authorization: `Bearer ${token}` }),
+          ...named,
+        },
       });
     } catch (error) {
       if (signal?.aborted === true) {
@@ -681,8 +700,14 @@ 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),
+      goals: (filter = {}, signal) =>
+        request(
+          "GET",
+          withQuery(at("goals"), { state: filter.state, category: filter.category }),
+          undefined,
+          restGoalsSchema,
+          signal,
+        ),
       goal: (id, signal) =>
         request("GET", `${base}${at("goals", id)}`, undefined, restGoalSchema, signal),
       createGoal: (input) => request("POST", `${base}${at("goals")}`, input, restGoalSchema),

package/src/compat.ts

@@ -0,0 +1,173 @@
+// Whether the command and the console go together (ADR-0025). The command names its version on
+// every request, in the product token of its user-agent; the console answers every request of
+// the API with its own version and the range of command versions it takes, and refuses a
+// command outside the range with `426` and the words to update. One rule for both sides, kept
+// here so that the command and the console read the same one, and narrowed by the console's
+// policy below only, never widened: what the rule promises stays predictable.
+
+/** The product token the command names itself with: `skillcdn-console/<version>`. */
+export const CLIENT_PRODUCT = "skillcdn-console";
+/** On every answer of the API: the console's version. */
+export const VERSION_HEADER = "console-version";
+/** On every answer of the API: the range of command versions the console takes, as npm spells one. */
+export const CLIENT_RANGE_HEADER = "console-client-range";
+
+export interface Version {
+  readonly major: number;
+  readonly minor: number;
+  readonly patch: number;
+}
+
+/** `x.y.z`, each a number of at most nine digits without a leading zero; no tag, no build. */
+const VERSION = /^(0|[1-9]\d{0,8})\.(0|[1-9]\d{0,8})\.(0|[1-9]\d{0,8})$/;
+const MAX_VERSION_LENGTH = 32;
+
+/** A version as the package spells one, or nothing for any other text. */
+export function parseVersion(text: string | null | undefined): Version | undefined {
+  if (typeof text !== "string" || text.length > MAX_VERSION_LENGTH) {
+    return undefined;
+  }
+  const match = VERSION.exec(text);
+  return match === null
+    ? undefined
+    : { major: Number(match[1]), minor: Number(match[2]), patch: Number(match[3]) };
+}
+
+export function formatVersion(version: Version): string {
+  return `${version.major}.${version.minor}.${version.patch}`;
+}
+
+/** Negative when `a` is the older, zero when they are the same, positive when `a` is the newer. */
+export function compareVersions(a: Version, b: Version): number {
+  return a.major - b.major || a.minor - b.minor || a.patch - b.patch;
+}
+
+/** A half-open range of versions: from `atLeast` on, and before `below`. */
+export interface VersionRange {
+  readonly atLeast: Version;
+  readonly below: Version;
+}
+
+/** The range as npm spells one: `>=0.1.18 <0.2.0`. */
+export function formatRange(range: VersionRange): string {
+  return `>=${formatVersion(range.atLeast)} <${formatVersion(range.below)}`;
+}
+
+const RANGE = /^>=(\S+) <(\S+)$/;
+const MAX_RANGE_LENGTH = 2 * MAX_VERSION_LENGTH + 4;
+
+/** A range as `formatRange` spells one, or nothing for any other text. */
+export function parseRange(text: string | null | undefined): VersionRange | undefined {
+  if (typeof text !== "string" || text.length > MAX_RANGE_LENGTH) {
+    return undefined;
+  }
+  const match = RANGE.exec(text);
+  const atLeast = parseVersion(match?.[1]);
+  const below = parseVersion(match?.[2]);
+  return atLeast !== undefined && below !== undefined && compareVersions(atLeast, below) < 0
+    ? { atLeast, below }
+    : undefined;
+}
+
+export function inRange(version: Version, range: VersionRange): boolean {
+  return compareVersions(version, range.atLeast) >= 0 && compareVersions(version, range.below) < 0;
+}
+
+/**
+ * The common rule. Before 1.0, a command from the console's own version on and within the
+ * console's minor (`^0.1.18`): any release may change the contract until then (ADR-0007), so the
+ * console's own version is the floor, and the minor is the line. From 1.0, the console's major
+ * and a minor within one of the console's, either way, whatever the patch: a minor adds and a
+ * major breaks, as the version promises from then on.
+ */
+export function commonRange(server: Version): VersionRange {
+  if (server.major === 0) {
+    return { atLeast: server, below: { major: 0, minor: server.minor + 1, patch: 0 } };
+  }
+  return {
+    atLeast: { major: server.major, minor: Math.max(0, server.minor - 1), patch: 0 },
+    below: { major: server.major, minor: server.minor + 2, patch: 0 },
+  };
+}
+
+/**
+ * What the console narrows the common rule by, and nothing it widens it by: a floor above the
+ * rule's, for a contract that moved within what the rule still allows, and versions refused
+ * whatever the rule says, for a release whose command is wrong. Changed with a changeset that
+ * says why.
+ */
+export interface ClientPolicy {
+  /** The oldest command this console answers, when the common rule's floor is too low. */
+  readonly atLeast?: string | undefined;
+  /** Versions of the command refused outright. */
+  readonly refused?: readonly string[] | undefined;
+}
+
+/** The console's policy today: the common rule as it is. */
+export const CLIENT_POLICY: ClientPolicy = {};
+
+/** The range of command versions a console of `server` takes: the common rule, narrowed by the policy's floor where that floor is within it. */
+export function clientRange(server: Version, policy: ClientPolicy = CLIENT_POLICY): VersionRange {
+  const common = commonRange(server);
+  const floor = parseVersion(policy.atLeast);
+  return floor !== undefined &&
+    compareVersions(floor, common.atLeast) > 0 &&
+    compareVersions(floor, common.below) < 0
+    ? { atLeast: floor, below: common.below }
+    : common;
+}
+
+/**
+ * What a command of one version is to a console of another: within the range and the same
+ * (`current`), older (`behind`) or newer (`ahead`), which the console answers; or outside it,
+ * older (`outdated`) or newer (`too_new`), which the console refuses.
+ */
+export type ClientVerdict = "current" | "behind" | "ahead" | "outdated" | "too_new";
+
+export interface ClientJudgement {
+  readonly verdict: ClientVerdict;
+  readonly range: VersionRange;
+}
+
+export function judgeClient(
+  client: Version,
+  server: Version,
+  policy: ClientPolicy = CLIENT_POLICY,
+): ClientJudgement {
+  const range = clientRange(server, policy);
+  const order = compareVersions(client, server);
+  const refused = (policy.refused ?? []).some((text) => {
+    const version = parseVersion(text);
+    return version !== undefined && compareVersions(version, client) === 0;
+  });
+  if (refused) {
+    return { verdict: order > 0 ? "too_new" : "outdated", range };
+  }
+  if (compareVersions(client, range.atLeast) < 0) {
+    return { verdict: "outdated", range };
+  }
+  if (compareVersions(client, range.below) >= 0) {
+    return { verdict: "too_new", range };
+  }
+  return { verdict: order === 0 ? "current" : order < 0 ? "behind" : "ahead", range };
+}
+
+/** What the command sends as its user-agent: its product token, and, in a comment, where it runs. */
+export function userAgentOf(version: string, comment?: string): string {
+  // A comment holds printable ASCII without parentheses or backslashes; nothing else is said.
+  const safe = comment?.replaceAll(/[^\x20-\x27\x2a-\x5b\x5d-\x7e]/g, "").trim();
+  return `${CLIENT_PRODUCT}/${version}${safe === undefined || safe.length === 0 ? "" : ` (${safe})`}`;
+}
+
+const MAX_USER_AGENT_LENGTH = 512;
+const CLIENT_TOKEN = new RegExp(
+  `(?:^|\\s)${CLIENT_PRODUCT}/(\\d{1,9}\\.\\d{1,9}\\.\\d{1,9})(?![\\w.-])`,
+);
+
+/** The version of the command a request's user-agent names, or nothing for any other client. */
+export function clientVersionOf(userAgent: string | null | undefined): Version | undefined {
+  if (typeof userAgent !== "string") {
+    return undefined;
+  }
+  return parseVersion(CLIENT_TOKEN.exec(userAgent.slice(0, MAX_USER_AGENT_LENGTH))?.[1]);
+}

package/src/components/calendar.tsx

@@ -48,9 +48,11 @@ export interface CalendarProps {
   readonly today?: string | undefined;
   /** The workspace's categories, for the legend to say what the colours mean. */
   readonly categories?: readonly RestCategory[] | undefined;
-  /** The project's goals, so that the task under the pointer is shown with its goal's title. */
+  /** The project's goals, so that the task under the pointer is shown with its goal's title, and, given `goalHref`, so that each goal marks its target day. */
   readonly goals?: readonly RestGoal[] | undefined;
   readonly taskHref: (task: RestTask) => string;
+  /** Where a goal's page is: given, the goals mark their target days on the month (ADR-0026). */
+  readonly goalHref?: ((goal: RestGoal) => string) | undefined;
   /** Where the calendar is on another month. */
   readonly monthHref: (month: string) => string;
 }
@@ -324,12 +326,32 @@ interface WeekRowProps {
   readonly pointed: Pointed | null;
   /** The project's goals, so that the item under the pointer names its goal; none across projects. */
   readonly goals?: readonly RestGoal[] | undefined;
+  /** The goals whose target day is each day, where the goals mark the month. */
+  readonly goalsOn?: ReadonlyMap<string, readonly RestGoal[]> | undefined;
+  readonly goalHref?: ((goal: RestGoal) => string) | undefined;
   /** The pointer, or the focus, arrived on a task's item on a day. */
   readonly onPoint: (task: RestTask, day: string, item: HTMLElement) => void;
   /** It left. */
   readonly onLeave: () => void;
 }
 
+/** The goals that aim at each day, by day: those with a target day, still planned or worked towards. */
+function goalsOnDays(goals: readonly RestGoal[]): ReadonlyMap<string, readonly RestGoal[]> {
+  const on = new Map<string, RestGoal[]>();
+  for (const goal of goals) {
+    if (goal.dueOn === null || goal.state === "dropped") {
+      continue;
+    }
+    const list = on.get(goal.dueOn);
+    if (list === undefined) {
+      on.set(goal.dueOn, [goal]);
+    } else {
+      list.push(goal);
+    }
+  }
+  return on;
+}
+
 /** One week as a row of cells: the bars across the days in their lanes, then the tasks on each day. */
 function WeekRow(props: WeekRowProps) {
   const { week, segments, now } = props;
@@ -361,6 +383,21 @@ function WeekRow(props: WeekRowProps) {
           )}
         >
           <span className="sc-calendar-day">{Number(cell.day.slice(8))}</span>
+          {props.goalHref !== undefined &&
+            (props.goalsOn?.get(cell.day) ?? []).map((goal) => (
+              <a
+                key={goal.id}
+                className={cx(
+                  "sc-calendar-goal",
+                  `sc-category-${goal.category?.color ?? "gray"}`,
+                  goal.state === "done" && "sc-calendar-over",
+                )}
+                href={props.goalHref?.(goal)}
+              >
+                <span className="sc-calendar-flag" aria-hidden="true" />
+                <span className="sc-calendar-task-title">{goal.title}</span>
+              </a>
+            ))}
           {Array.from({ length: lanes }, (_, lane) => {
             const segment = segments.find(
               (candidate) =>
@@ -435,6 +472,7 @@ export function Calendar(props: CalendarProps) {
   const firstDay = firstDayOfWeek(tag);
   const weeks = monthGrid(props.month, firstDay);
   const on = onDays(props.tasks);
+  const goalsOn = props.goalHref === undefined ? undefined : goalsOnDays(props.goals ?? []);
   const inMonth = (day: string) => monthOf(day) === props.month;
   const monthWeeks = weeks.map((week) => ({ week, segments: weekSegments(week, props.tasks) }));
   const nothing =
@@ -492,6 +530,8 @@ export function Calendar(props: CalendarProps) {
               taskHref={props.taskHref}
               pointed={pointed}
               goals={props.goals}
+              goalsOn={goalsOn}
+              goalHref={props.goalHref}
               onPoint={point}
               onLeave={leave}
               people

package/src/components/goals.tsx

@@ -4,20 +4,32 @@ import {
   type GoalState,
   MAX_BODY_LENGTH,
   MAX_TITLE_LENGTH,
+  type RestCategory,
   type RestGoal,
   type RestGoalInput,
   type RestTask,
   TASK_STATES,
 } from "../api.js";
-import { useWords } from "../i18n/index.js";
+import { formatDays } from "../dates.js";
+import { useLanguage, useWords } from "../i18n/index.js";
 import { Markdown } from "./markdown.js";
 import { TaskList } from "./task-list.js";
-import { Button, Day, DueBadge, GoalStateBadge, PersonChip, ProgressBar, Time } from "./ui.js";
+import {
+  Button,
+  CategoryBadge,
+  Day,
+  DueBadge,
+  GoalStateBadge,
+  PersonChip,
+  ProgressBar,
+  Time,
+} from "./ui.js";
 
-// The roadmap of a project (ADR-0019): its goals, each with the day it is meant to be reached
-// by and how far its tasks are, read from the board as it stands. The list, one goal with its
-// tasks, and the form an owner sets one with. Each takes its data as props and nothing from
-// the network; what people wrote is shown as text, never as HTML.
+// The roadmap of a project (ADR-0019): its goals, each planned in days as a task is, a start
+// and a target, sorted into a category of the workspace (ADR-0026), with how far its tasks
+// are, read from the board as it stands. The list, one goal with its tasks, and the form an
+// owner sets one with. Each takes its data as props and nothing from the network; what people
+// wrote is shown as text, never as HTML.
 
 /** A goal's day on the calendar's terms: reached or let go, it is a plain fact; else it may be late. */
 const dueState = (goal: RestGoal) =>
@@ -33,6 +45,7 @@ export interface GoalListProps {
 
 export function GoalList(props: GoalListProps) {
   const words = useWords().roadmap;
+  const { tag } = useLanguage();
   if (props.goals.length === 0) {
     return <>{props.empty ?? null}</>;
   }
@@ -44,7 +57,11 @@ export function GoalList(props: GoalListProps) {
             <a className="sc-goal-title" href={props.goalHref(goal)}>
               {goal.title}
             </a>
+            {goal.category !== null && <CategoryBadge category={goal.category} />}
             <GoalStateBadge state={goal.state} />
+            {goal.startsOn !== null && goal.dueOn !== null && goal.startsOn < goal.dueOn && (
+              <span className="sc-goal-days">{formatDays(goal.startsOn, goal.dueOn, tag)}</span>
+            )}
             {goal.dueOn !== null && (
               <DueBadge dueOn={goal.dueOn} state={dueState(goal)} today={props.today} />
             )}
@@ -59,6 +76,8 @@ export function GoalList(props: GoalListProps) {
 export interface GoalFormProps {
   /** The goal to change; left out, the form sets a new one. */
   readonly goal?: RestGoal | undefined;
+  /** The workspace's categories to sort the goal into; left out, the form offers none. */
+  readonly categories?: readonly RestCategory[] | undefined;
   readonly busy?: boolean | undefined;
   readonly error?: string | undefined;
   readonly onSubmit: (input: RestGoalInput) => void;
@@ -72,11 +91,20 @@ export function GoalForm(props: GoalFormProps) {
   const [title, setTitle] = useState(goal?.title ?? "");
   const [body, setBody] = useState(goal?.body ?? "");
   const [state, setState] = useState<GoalState>(goal?.state ?? "planned");
+  const [category, setCategory] = useState(goal?.category?.key ?? "");
+  const [startsOn, setStartsOn] = useState(goal?.startsOn ?? "");
   const [dueOn, setDueOn] = useState(goal?.dueOn ?? "");
 
   const submit = (event: FormEvent) => {
     event.preventDefault();
-    props.onSubmit({ title: title.trim(), body, state, dueOn: dueOn === "" ? null : dueOn });
+    props.onSubmit({
+      title: title.trim(),
+      body,
+      state,
+      category: category === "" ? null : category,
+      startsOn: startsOn === "" ? null : startsOn,
+      dueOn: dueOn === "" ? null : dueOn,
+    });
   };
 
   return (
@@ -117,12 +145,42 @@ export function GoalForm(props: GoalFormProps) {
             ))}
           </select>
         </label>
+        {props.categories !== undefined && (
+          <label className="sc-field">
+            <span className="sc-field-label">{form.category}</span>
+            <select
+              className="sc-input"
+              value={category}
+              onChange={(event) => setCategory(event.target.value)}
+            >
+              <option value="">{form.noCategory}</option>
+              {props.categories.map((candidate) => (
+                <option key={candidate.key} value={candidate.key}>
+                  {candidate.name}
+                </option>
+              ))}
+            </select>
+          </label>
+        )}
+      </div>
+      <div className="sc-field-row">
+        <label className="sc-field">
+          <span className="sc-field-label">{form.startsOn}</span>
+          <input
+            className="sc-input"
+            type="date"
+            value={startsOn}
+            max={dueOn === "" ? undefined : dueOn}
+            onChange={(event) => setStartsOn(event.target.value)}
+          />
+        </label>
         <label className="sc-field">
           <span className="sc-field-label">{form.dueOn}</span>
           <input
             className="sc-input"
             type="date"
             value={dueOn}
+            min={startsOn === "" ? undefined : startsOn}
             onChange={(event) => setDueOn(event.target.value)}
           />
         </label>
@@ -175,6 +233,7 @@ export function GoalView(props: GoalViewProps) {
       <header className="sc-task-header">
         <h1 className="sc-task-title">{goal.title}</h1>
         <div className="sc-task-badges">
+          {goal.category !== null && <CategoryBadge category={goal.category} />}
           <GoalStateBadge state={goal.state} />
           {goal.dueOn !== null && (
             <DueBadge dueOn={goal.dueOn} state={dueState(goal)} today={props.today} />
@@ -233,6 +292,26 @@ export function GoalView(props: GoalViewProps) {
                 )}
               </dd>
             </div>
+            <div>
+              <dt>{roadmap.category}</dt>
+              <dd>
+                {goal.category === null ? (
+                  <span className="sc-muted">{roadmap.noCategory}</span>
+                ) : (
+                  <CategoryBadge category={goal.category} />
+                )}
+              </dd>
+            </div>
+            <div>
+              <dt>{roadmap.starts}</dt>
+              <dd>
+                {goal.startsOn === null ? (
+                  <span className="sc-muted">{roadmap.noStart}</span>
+                ) : (
+                  <Day day={goal.startsOn} />
+                )}
+              </dd>
+            </div>
             <div>
               <dt>{roadmap.target}</dt>
               <dd>