@skillcdn/console 0.4.2 → 0.4.4

package/src/schemas.ts

@@ -16,9 +16,12 @@ import {
   MAX_BODY_LENGTH,
   MAX_CATEGORY_KEY_LENGTH,
   MAX_CATEGORY_NAME_LENGTH,
+  MAX_DECIDERS,
   MAX_DOCUMENT_LENGTH,
   MAX_DOCUMENT_PATH_LENGTH,
   MAX_FILE_NAME_LENGTH,
+  MAX_HOME_ROW,
+  MAX_HOME_TILES,
   MAX_LANGUAGE_TAG_LENGTH,
   MAX_LINK_LABEL_LENGTH,
   MAX_LINKS,
@@ -42,6 +45,7 @@ import {
   MAX_WORKERS,
   MIN_OPTIONS,
 } from "./limits.js";
+import { PLUGIN_WIDGET_SIZE_NAMES } from "./plugin/manifest.js";
 import { hasForbiddenCodePoint } from "./text.js";
 import {
   ARTIFACT_KINDS,
@@ -100,6 +104,14 @@ const day = z.iso.date();
 const count = z.int().check(z.nonnegative());
 
 /** A person of the workspace, as the pages show them. Nothing here is a secret. */
+/** A language tag as a browser sends one (`en`, `ko-KR`). */
+const languageTag = z
+  .string()
+  .check(
+    z.maxLength(MAX_LANGUAGE_TAG_LENGTH),
+    z.regex(/^[A-Za-z]{2,8}(?:-[A-Za-z0-9]{1,8})*$/, "must be a language tag"),
+  );
+
 export const restPersonSchema = z.object({
   id: uuid,
   /** What the account is called at its provider: a login at the git host, an address at Google. */
@@ -116,6 +128,19 @@ export const restPersonSchema = z.object({
   source: z.enum(MEMBERSHIP_SOURCES),
   /** When they were deactivated, or `null`. */
   deactivatedAt: z.nullable(instant),
+  /**
+   * The id of the person they report to, the reporting line of the directory an administrator
+   * keeps, or `null` for nobody; what a plugin reads as the default approver, the default
+   * assignee, in place of a line of its own. Answered from 0.4.4 and read as optional, so that
+   * a console built on this package still reads an older console's people.
+   */
+  managerId: z.optional(z.nullable(uuid)),
+  /**
+   * The language the person reads in (ADR-0065), a tag: the one they chose, else the one the pages
+   * first saw them in; `null` until they have opened the pages. What a plugin or an agent writes
+   * for them in. Answered from 0.4.4 and read as optional, as `managerId` is.
+   */
+  language: z.optional(z.nullable(languageTag)),
 });
 export type RestPerson = z.infer<typeof restPersonSchema>;
 
@@ -195,16 +220,59 @@ export const timeZoneName = z
     z.regex(/^[A-Za-z0-9_+-]+(?:\/[A-Za-z0-9_+-]+)*$/, "must be a time zone name"),
   );
 
-/** A language tag as a browser sends one (`en`, `ko-KR`): what the pages speak, by the person's choice. */
-const languageTag = z
+/** What `PATCH /api/v1/me` is sent: the language the person chose, or `null` to choose none. */
+/** The sizes of a tile on the front page (ADR-0061): a project's icon, and the widgets' family. */
+export const HOME_TILE_SIZES = ["icon", ...PLUGIN_WIDGET_SIZE_NAMES] as const;
+
+/** A tile by what it is: a project by its id, a widget by its plugin's key and its own. */
+const homeTileId = z
   .string()
   .check(
-    z.maxLength(MAX_LANGUAGE_TAG_LENGTH),
-    z.regex(/^[A-Za-z]{2,8}(?:-[A-Za-z0-9]{1,8})*$/, "must be a language tag"),
+    z.regex(
+      /^(?:project:[0-9a-f-]{36}|widget:[a-z][a-z0-9-]{0,31}:[a-z][a-z0-9-]{0,31})$/,
+      "must name a project or a widget",
+    ),
   );
 
-/** What `PATCH /api/v1/me` is sent: the language the person chose, or `null` to choose none. */
-export const restMePatchSchema = z.object({ language: z.nullable(languageTag) });
+/** One tile of a person's own front page, at a place of the grid and at a size. */
+export const restHomeTileSchema = z.object({
+  tile: homeTileId,
+  x: z.int().check(z.gte(0), z.lte(11)),
+  y: z.int().check(z.gte(0), z.lte(MAX_HOME_ROW)),
+  size: z.enum(HOME_TILE_SIZES),
+});
+export type RestHomeTile = z.infer<typeof restHomeTileSchema>;
+
+const homeLayoutSchema = z.array(restHomeTileSchema).check(z.maxLength(MAX_HOME_TILES));
+
+/**
+ * A person's own front page (ADR-0061): the tiles they took off it, which stay off, and what
+ * they arranged at each width of the grid, by its columns; what they have not seen yet takes
+ * the first room.
+ */
+export const restHomeSchema = z.object({
+  hidden: z.array(homeTileId).check(z.maxLength(MAX_HOME_TILES)),
+  layouts: z.object({
+    12: z.optional(homeLayoutSchema),
+    8: z.optional(homeLayoutSchema),
+    6: z.optional(homeLayoutSchema),
+    4: z.optional(homeLayoutSchema),
+  }),
+});
+export type RestHome = z.infer<typeof restHomeSchema>;
+
+/** What `PATCH /api/v1/me` is sent: the language, the front page, either or both; `null` lets the console choose. */
+export const restMePatchSchema = z
+  .object({
+    language: z.optional(z.nullable(languageTag)),
+    home: z.optional(z.nullable(restHomeSchema)),
+  })
+  .check(
+    z.refine(
+      (patch) => patch.language !== undefined || patch.home !== undefined,
+      "must name a language or the front page",
+    ),
+  );
 export type RestMePatch = z.infer<typeof restMePatchSchema>;
 
 /**
@@ -274,8 +342,13 @@ export const restMeSchema = z.object({
    * person's own knows it holds one. `null` on a session, and for nobody.
    */
   agent: z.nullable(z.string()),
-  /** The language the person chose for the pages (ADR-0012), or `null` for the browser's. */
+  /** The language the person reads in (ADR-0065): the one they chose, else the one the pages first saw them in; `null` until then. */
   language: z.nullable(languageTag),
+  /**
+   * The person's own front page (ADR-0061), or `null` while they have arranged nothing; answered
+   * from 0.4.4 and read as optional.
+   */
+  home: z.optional(z.nullable(restHomeSchema)),
   signIn: z.array(restProviderSchema),
   /**
    * The console's version and the range of command versions it takes, as npm spells one
@@ -284,6 +357,13 @@ export const restMeSchema = z.object({
    * built on this package still reads an older console's answer, and says it is older.
    */
   console: z.optional(z.object({ version: z.string(), clientRange: z.string() })),
+  /**
+   * How many decisions wait for the person's answer across the projects they may see
+   * (ADR-0042), for the pages to say beside My decisions; `null` for nobody. Answered from
+   * 0.4.3 and read as optional, so that a console built on this package still reads an older
+   * console's answer.
+   */
+  decisions: z.optional(z.nullable(z.object({ waiting: count }))),
 });
 export type RestMe = z.infer<typeof restMeSchema>;
 
@@ -306,11 +386,14 @@ export const restPersonPatchSchema = z
   .object({
     role: z.optional(z.enum(PERSON_ROLES)),
     status: z.optional(z.enum(PERSON_STATUSES)),
+    /** Whom the person reports to: another active person of the workspace, or `null` for nobody. */
+    managerId: z.optional(z.nullable(uuid)),
   })
   .check(
     z.refine(
-      (patch) => patch.role !== undefined || patch.status !== undefined,
-      "must name a role or a status",
+      (patch) =>
+        patch.role !== undefined || patch.status !== undefined || patch.managerId !== undefined,
+      "must name a role, a status or a manager",
     ),
   );
 export type RestPersonPatch = z.infer<typeof restPersonPatchSchema>;
@@ -498,6 +581,8 @@ export const restTaskSchema = z.object({
   owner: restPersonSchema,
   /** The plugin that made it, by key (ADR-0052), or `null`; left out by a console older than the plugins. */
   plugin: z.optional(z.nullable(z.string())),
+  /** The agent the task was written through, or `null` when a person wrote it themselves (ADR-0056); the owner may have changed since. Left out by an older console. */
+  agent: z.optional(z.nullable(z.string())),
   /** The people at work on it (ADR-0037), in the order they came to it; `[]` while nobody is. */
   workers: z.array(restPersonSchema),
   /** The task this one is part of, or `null`. */
@@ -608,6 +693,8 @@ export const restGoalSchema = z.object({
   /** The day the goal is meant to be reached by, or `null`. */
   dueOn: z.nullable(day),
   createdBy: restPersonSchema,
+  /** The agent the goal was set through, or `null` when a person set it themselves (ADR-0056); left out by an older console. */
+  agent: z.optional(z.nullable(z.string())),
   /** The tasks that work towards it, counted by state. */
   taskCounts: restTaskCountsSchema,
   createdAt: instant,
@@ -643,10 +730,50 @@ export const restGoalPatchSchema = z.object({
 });
 export type RestGoalPatch = z.infer<typeof restGoalPatchSchema>;
 
+/** A file a run handed in, as the console keeps it; its bytes are at `projectPath(key, "files", <artifact id>)`. */
+export const restFileSchema = z.object({
+  /** What the agent called it: one line, without a path. */
+  name: z.string(),
+  /** In bytes. */
+  size: count,
+  /** The media type the agent said, or `application/octet-stream`. */
+  contentType: z.string(),
+  /** The SHA-256 of the bytes, in hex: what the console keeps them under. */
+  sha256: z.string(),
+});
+export type RestFile = z.infer<typeof restFileSchema>;
+
+/** A file put on a decision when it was raised (ADR-0055), kept as a run's file is; its bytes are at `projectPath(key, "files", <id>)`. */
+export const restDecisionFileSchema = z.object({
+  id: uuid,
+  file: restFileSchema,
+});
+export type RestDecisionFile = z.infer<typeof restDecisionFileSchema>;
+
+/**
+ * The key a raiser may give an option, for a program to read the answer by instead of
+ * comparing labels: spelled as a plugin's key is.
+ */
+export const OPTION_KEY_PATTERN = /^[a-z][a-z0-9-]{1,31}$/;
+const optionKey = z
+  .string()
+  .check(
+    z.regex(
+      OPTION_KEY_PATTERN,
+      "must be a key: a lowercase letter, then lowercase letters, digits and hyphens, 2 to 32 long",
+    ),
+  );
+
 export const restDecisionOptionSchema = z.object({
   /** What an answer names: stable once given. */
   id: z.string(),
   label: z.string(),
+  /**
+   * The key the raiser gave the option, for a program to read the answer by (`optionKey` on the
+   * `decision.answered` event) without comparing labels; none on an option given without one,
+   * and none on the person's own answer.
+   */
+  key: z.optional(z.string()),
   /**
    * On the one option a person's own answer became, when they answered in their own words
    * instead of choosing (`POST .../answer` with `own`): added then, after the options given,
@@ -667,8 +794,15 @@ export const restDecisionSchema = z.object({
   /** The task's number, when there is a task, or `null`. */
   taskNumber: z.nullable(z.int()),
   raisedBy: restPersonSchema,
-  /** Who is to answer (ADR-0042): the raiser, unless another person of the project was named. */
+  /** The first of those to answer (ADR-0042): the raiser, unless others of the project were named. */
   decider: restPersonSchema,
+  /**
+   * Everyone the decision is addressed to (ADR-0057), `decider` first: each finds it among their
+   * decisions, any of them may answer, and the first answer ends it. Answered from 0.4.4 and read
+   * as optional, so that a console built on this package still reads an older console's
+   * decisions, where it is `[decider]`.
+   */
+  deciders: z.optional(z.array(restPersonSchema)),
   /** The run that raised it, as the agent asked, or `null` when a person did. */
   run: z.nullable(z.object({ id: uuid, agent: z.string() })),
   /** The plugin that raised it, by key (ADR-0052), or `null`; left out by a console older than the plugins. */
@@ -682,10 +816,31 @@ export const restDecisionSchema = z.object({
       note: z.nullable(z.string()),
       by: restPersonSchema,
       at: instant,
+      /**
+       * The agent the answer came through, when the person's agent wrote it in their name
+       * (`console answer`, ADR-0021), or `null` when they answered themselves (ADR-0056).
+       * Answered from 0.4.4 and read as optional, so that a console built on this package still
+       * reads an older console's decisions.
+       */
+      agent: z.optional(z.nullable(z.string())),
     }),
   ),
   /** What followed the decision, in Markdown, written afterwards; `null` until someone does. */
   outcome: z.nullable(z.string()),
+  /**
+   * Who wrote what followed, the agent they wrote it through (`null` when themselves) and when
+   * (ADR-0056); each `null` until someone does. Answered from 0.4.4 and read as optional.
+   */
+  outcomeBy: z.optional(z.nullable(restPersonSchema)),
+  outcomeAgent: z.optional(z.nullable(z.string())),
+  outcomeAt: z.optional(z.nullable(instant)),
+  /**
+   * The files put on it when it was raised (ADR-0055), in the order they came; a picture among
+   * them is shown where the context names it as `![words](its name)`, else after it. Answered
+   * from 0.4.3 and read as optional, so that a console built on this package still reads an
+   * older console's decisions.
+   */
+  files: z.optional(z.array(restDecisionFileSchema)),
   createdAt: instant,
   updatedAt: instant,
 });
@@ -742,18 +897,35 @@ export const restPersonWorkSchema = z.object({
 });
 export type RestPersonWork = z.infer<typeof restPersonWorkSchema>;
 
-/** What `POST /api/v1/projects/<key>/decisions` is sent: the question, its context, and the options. */
+/**
+ * What `POST /api/v1/projects/<key>/decisions` is sent: the question, its context, and the
+ * options. As JSON; or, with files put on the decision (ADR-0055), as the part `decision` of a
+ * form, with a part `file` for each file.
+ */
 export const restDecisionInputSchema = z.object({
   question: line(MAX_QUESTION_LENGTH),
   body: z.optional(body),
+  /** Each a label, and optionally a key a program reads the answer by, each key once. */
   options: z
-    .array(z.object({ label: line(MAX_OPTION_LABEL_LENGTH) }))
-    .check(z.minLength(MIN_OPTIONS), z.maxLength(MAX_OPTIONS)),
+    .array(z.object({ label: line(MAX_OPTION_LABEL_LENGTH), key: z.optional(optionKey) }))
+    .check(
+      z.minLength(MIN_OPTIONS),
+      z.maxLength(MAX_OPTIONS),
+      z.refine((options) => {
+        const keys = options.flatMap((option) => (option.key === undefined ? [] : [option.key]));
+        return new Set(keys).size === keys.length;
+      }, "each key once"),
+    ),
   taskId: z.optional(z.nullable(uuid)),
   /** The run that asks, when an agent does: the decision is about its task, and it waits for the answer. */
   runId: z.optional(z.nullable(uuid)),
   /** Who is to answer (ADR-0042): a person who may work in the project; the asker when left out. */
   deciderId: z.optional(uuid),
+  /**
+   * Several to answer (ADR-0057), in place of `deciderId`: each a person who may work in the
+   * project, up to `MAX_DECIDERS`; any of them may answer, and the first answer ends the decision.
+   */
+  deciderIds: z.optional(z.array(uuid).check(z.minLength(1), z.maxLength(MAX_DECIDERS))),
 });
 export type RestDecisionInput = z.infer<typeof restDecisionInputSchema>;
 
@@ -801,11 +973,14 @@ export const restEventDataSchema = z.object({
   from: z.optional(z.enum(TASK_STATES)),
   to: z.optional(z.enum(TASK_STATES)),
   question: z.optional(z.string()),
-  /** For `decision.answered`: the label of the chosen option. */
+  /** For `decision.answered`: the label of the chosen option, and its key where the raiser gave one. */
   option: z.optional(z.string()),
+  optionKey: z.optional(z.string()),
   /** For `person.role_changed` and the events about a project's members: whose role, and what it became. */
   login: z.optional(z.string()),
   role: z.optional(z.string()),
+  /** For `person.manager_changed`: the login of whom the person reports to now, or `null` for nobody. */
+  manager: z.optional(z.nullable(z.string())),
   /** For the events about a project: its key and its name. */
   key: z.optional(z.string()),
   name: z.optional(z.string()),
@@ -818,7 +993,7 @@ export const restEventDataSchema = z.object({
   label: z.optional(z.string()),
   /** For `run.reported` and `task.commented`: the first words of what was written. */
   excerpt: z.optional(z.string()),
-  /** For `task.commented`: how many files came with it. */
+  /** For `task.commented`, and for `decision.raised` when any came: how many files came with it. */
   files: z.optional(z.int()),
   /** For `plugin.command`: the command, how it ended, the refusal's code where it was refused, how long it ran, and the arguments, a secret one as `[hidden]`. */
   command: z.optional(z.string()),
@@ -867,19 +1042,6 @@ export const restReportSchema = z.object({
 });
 export type RestReport = z.infer<typeof restReportSchema>;
 
-/** A file a run handed in, as the console keeps it; its bytes are at `projectPath(key, "files", <artifact id>)`. */
-export const restFileSchema = z.object({
-  /** What the agent called it: one line, without a path. */
-  name: z.string(),
-  /** In bytes. */
-  size: count,
-  /** The media type the agent said, or `application/octet-stream`. */
-  contentType: z.string(),
-  /** The SHA-256 of the bytes, in hex: what the console keeps them under. */
-  sha256: z.string(),
-});
-export type RestFile = z.infer<typeof restFileSchema>;
-
 /** What a run handed in: a link to a branch, a pull request, a page; or a file the console keeps. */
 export const restArtifactSchema = z.object({
   id: uuid,