@skillcdn/console 0.1.24 → 0.3.1

package/src/schemas.ts

@@ -2,6 +2,13 @@
 // most of what a page downloads. The server validates what it is sent with the input schemas
 // and builds the output shapes; the pages and a custom console parse answers with the rest.
 // Absent values are `null` on the wire, never missing keys. Changes within a version are additive.
+import {
+  restBrowseSchema as packBrowseSchema,
+  restFileSchema as packFileSchema,
+  restFindSchema as packFindSchema,
+  restMountSchema as packMountSchema,
+  restSkillSchema as packSkillSchema,
+} from "@skillcdn/core";
 import * as z from "zod/mini";
 import { isDocumentPath } from "./documents.js";
 import {
@@ -43,6 +50,8 @@ import {
   GOAL_STATES,
   LINK_SOURCES,
   MEMBERSHIP_SOURCES,
+  PACK_CONNECT_ENDINGS,
+  PEOPLE_VISIBILITIES,
   PERSON_ROLES,
   PERSON_STATUSES,
   PROJECT_ICON_TYPES,
@@ -56,6 +65,7 @@ import {
   SKILLS_STATUSES,
   TASK_PRIORITIES,
   TASK_STATES,
+  WEEK_STARTS,
 } from "./vocabulary.js";
 
 /** A line of text a person wrote: trimmed, bounded, and free of characters that hide. */
@@ -159,6 +169,18 @@ export const restProviderSchema = z.object({
 });
 export type RestProvider = z.infer<typeof restProviderSchema>;
 
+/**
+ * A time zone's name as the IANA database spells one (`Asia/Seoul`, `UTC`): its shape here; the
+ * server knows which names are zones.
+ */
+export const timeZoneName = z
+  .string()
+  .check(
+    z.minLength(1),
+    z.maxLength(64),
+    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
   .string()
@@ -171,22 +193,67 @@ const languageTag = z
 export const restMePatchSchema = z.object({ language: z.nullable(languageTag) });
 export type RestMePatch = z.infer<typeof restMePatchSchema>;
 
+/**
+ * The workspace as `GET /api/v1/me` describes it, and as `PATCH /api/v1/workspace` answers: what
+ * the board is called, what the deployment's configuration says of it, and the settings an
+ * administrator keeps on the Settings page (ADR-0035).
+ */
+export const restWorkspaceSchema = z.object({
+  name: z.string(),
+  /** The most days a token may be good for here, or `null` when a person chooses. */
+  tokenDaysAtMost: z.nullable(z.int().check(z.positive())),
+  /**
+   * The organization's skills: the origin of the SkillCDN deployment they are read through,
+   * and the address a project without one of its own reads, canonical, or `null` for none.
+   */
+  skills: z.object({
+    source: z.string(),
+    address: z.nullable(z.string()),
+    /**
+     * The SkillCDN token the organization's pack is read with, by a project that names no
+     * address and holds no token of its own (ADR-0036): when it was set, never the token; `null`
+     * for none. Optional, so that a console older than it still answers.
+     */
+    packToken: z.optional(z.nullable(z.object({ setAt: instant }))),
+  }),
+  /**
+   * Who sees whom on the People page (ADR-0035): everyone, or the people one shares a project
+   * with. Read as optional, so that a console older than this setting still answers; `everyone`
+   * then, which is what it does.
+   */
+  peopleVisibility: z.optional(z.enum(PEOPLE_VISIBILITIES)),
+  /** The day the calendars begin a week on: the language's, Monday or Sunday. Optional as above; `auto` then. */
+  weekStart: z.optional(z.enum(WEEK_STARTS)),
+  /**
+   * The workspace's time zone, an IANA name, in which the command prints moments; `null` for
+   * none, when they stay as the API gives them, in UTC. Optional as above; none then.
+   */
+  timeZone: z.optional(z.nullable(timeZoneName)),
+});
+export type RestWorkspace = z.infer<typeof restWorkspaceSchema>;
+
+/** What `PATCH /api/v1/workspace` is sent, by an administrator: the settings to change, at least one. */
+export const restWorkspacePatchSchema = z
+  .object({
+    peopleVisibility: z.optional(z.enum(PEOPLE_VISIBILITIES)),
+    weekStart: z.optional(z.enum(WEEK_STARTS)),
+    /** A zone's name, or `null` for none. */
+    timeZone: z.optional(z.nullable(timeZoneName)),
+  })
+  .check(
+    z.refine((patch) => Object.values(patch).some((value) => value !== undefined), {
+      message: "names nothing to change",
+    }),
+  );
+export type RestWorkspacePatch = z.infer<typeof restWorkspacePatchSchema>;
+
 /**
  * `GET /api/v1/me`: the workspace, who the session cookie says is signed in (or `null`), the
  * language they chose (or `null`), and the identity providers people sign in through, none
  * where nobody can.
  */
 export const restMeSchema = z.object({
-  workspace: z.object({
-    name: z.string(),
-    /** The most days a token may be good for here, or `null` when a person chooses. */
-    tokenDaysAtMost: z.nullable(z.int().check(z.positive())),
-    /**
-     * The organization's skills: the origin of the SkillCDN deployment they are read through,
-     * and the address a project without one of its own reads, canonical, or `null` for none.
-     */
-    skills: z.object({ source: z.string(), address: z.nullable(z.string()) }),
-  }),
+  workspace: restWorkspaceSchema,
   person: z.nullable(restPersonSchema),
   /**
    * What the token asking is called by its person, when a token asks: how a console of a
@@ -322,15 +389,25 @@ export const restProjectPatchSchema = z.object({
 });
 export type RestProjectPatch = z.infer<typeof restProjectPatchSchema>;
 
-/** A person listed in a project, with what they are in it. */
+/**
+ * A member of a project, with what they are in it: a person listed in it, or, in a project open
+ * to the workspace, anyone of the workspace, who is a member of it without a listing (ADR-0035).
+ */
 export const restMemberSchema = z.object({
   person: restPersonSchema,
+  /** What they are in it: an owner as listed or as an administrator, else a member. */
   role: z.enum(PROJECT_ROLES),
+  /** Since when: the listing's day, or, for a member without one, the later of the project's making and their joining. */
   addedAt: instant,
+  /**
+   * Whether a listing holds them in the project. Read as optional, so that a console older than
+   * this field still answers; everyone it lists is listed.
+   */
+  listed: z.optional(z.boolean()),
 });
 export type RestMember = z.infer<typeof restMemberSchema>;
 
-/** `GET /api/v1/projects/<key>/members`: those listed, by login. */
+/** `GET /api/v1/projects/<key>/members`: the members, by login; everyone of the workspace in a project open to it. */
 export const restMembersSchema = z.object({ items: z.array(restMemberSchema) });
 export type RestMembers = z.infer<typeof restMembersSchema>;
 
@@ -548,9 +625,15 @@ export const restGoalPatchSchema = z.object({
 export type RestGoalPatch = z.infer<typeof restGoalPatchSchema>;
 
 export const restDecisionOptionSchema = z.object({
-  /** What an answer names: stable for the life of the decision. */
+  /** What an answer names: stable once given. */
   id: z.string(),
   label: 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,
+   * which carry no `own`.
+   */
+  own: z.optional(z.literal(true)),
 });
 export type RestDecisionOption = z.infer<typeof restDecisionOptionSchema>;
 
@@ -646,11 +729,24 @@ export const restDecisionPatchSchema = z.object({
 });
 export type RestDecisionPatch = z.infer<typeof restDecisionPatchSchema>;
 
-/** What `POST .../decisions/<id>/answer` is sent: an option, and a word about it. */
-export const restAnswerInputSchema = z.object({
-  option: z.string().check(z.minLength(1), z.maxLength(64)),
-  note: z.optional(paragraphs(MAX_NOTE_LENGTH)),
-});
+/**
+ * What `POST .../decisions/<id>/answer` is sent: one of the options by its id, or the person's
+ * own answer in a line, one of the two; and a word about either.
+ */
+export const restAnswerInputSchema = z
+  .object({
+    /** The id of the chosen option. */
+    option: z.optional(z.string().check(z.minLength(1), z.maxLength(64))),
+    /** The person's own answer, when none of the options is it: one line, worded as an option is. */
+    own: z.optional(line(MAX_OPTION_LABEL_LENGTH)),
+    note: z.optional(paragraphs(MAX_NOTE_LENGTH)),
+  })
+  .check(
+    z.refine(
+      (input) => (input.option === undefined) !== (input.own === undefined),
+      "must name an option or give an answer of its own, one of the two",
+    ),
+  );
 export type RestAnswerInput = z.infer<typeof restAnswerInputSchema>;
 
 /**
@@ -894,15 +990,39 @@ export const restClaimSchema = z.union([
 ]);
 export type RestClaim = z.infer<typeof restClaimSchema>;
 
-/** One of the project's skills, as the SkillCDN deployment lists it at the project's address. */
+/** Why a pack did not answer a read: the code and the words the deployment, or the console reading a directory, gave, as the main repository's API spells them. */
+export const restPackRefusalSchema = z.object({
+  code: z.string(),
+  message: z.string(),
+  /** With a file the pack will not carry: where it is at its source, or `null`. */
+  sourceUrl: z.nullable(z.string()),
+  /** With `skill.ambiguous`: the directories to choose from. */
+  directories: z.array(z.string()),
+});
+export type RestPackRefusal = z.infer<typeof restPackRefusalSchema>;
+
+/** What every answer about a pack says first: its address, where it is read, and how the read went. */
+const packEnvelope = {
+  /** The address, canonical, or `null` when neither the project nor the console names one. */
+  address: z.nullable(z.string()),
+  /** The origin of the SkillCDN deployment the pack is read at; `null` for a pack read from a directory on the console's machine (ADR-0031). */
+  source: z.nullable(z.string()),
+  /** Where a person browses the address at the deployment, or `null` without one. */
+  page: z.nullable(z.string()),
+  status: z.enum(SKILLS_STATUSES),
+  /** Why the read did not happen, in the pack's own words, when `status` says it did not; `null` otherwise. */
+  refusal: z.nullable(restPackRefusalSchema),
+};
+
+/** One of the project's skills, as the pack lists it: what the repository says of it, where a person reads it, what an agent loads it by. */
 export const restSkillSchema = z.object({
   name: z.string(),
   description: z.string(),
   /** The skill's folder in the repository (`""` for the root), and the path of its `SKILL.md`. */
   directory: z.string(),
   path: z.string(),
-  /** Where a person reads the skill: its page at the deployment. */
-  page: z.string(),
+  /** Where a person reads the skill: its page at the deployment, or `null` for a pack read from a directory. */
+  page: z.nullable(z.string()),
   /** What an agent loads the skill by, through its own SkillCDN connection; `null` when the path is not one. */
   uri: z.nullable(z.string()),
   /** The title and the description in other languages, by language tag, as the repository gives them. */
@@ -913,15 +1033,9 @@ export const restSkillSchema = z.object({
 });
 export type RestSkill = z.infer<typeof restSkillSchema>;
 
-/** `GET /api/v1/projects/<key>/skills`: the project's skills, read by address through SkillCDN. */
+/** `GET /api/v1/projects/<key>/skills`: the project's pack, read by address (ADR-0028, ADR-0031). */
 export const restSkillsSchema = z.object({
-  /** The address, canonical, or `null` when neither the project nor the deployment names one. */
-  address: z.nullable(z.string()),
-  /** The origin of the SkillCDN deployment the skills are read through. */
-  source: z.string(),
-  /** Where a person browses the address, or `null` without one. */
-  page: z.nullable(z.string()),
-  status: z.enum(SKILLS_STATUSES),
+  ...packEnvelope,
   /** The pack as its manifest or its README names it, when `ready`: what it is called, what it is for, the language it is written in. */
   pack: z.optional(
     z.object({
@@ -930,10 +1044,12 @@ export const restSkillsSchema = z.object({
       language: z.nullable(z.string()),
     }),
   ),
-  /** How many skills and documents the deployment indexed at the address, when `ready`. */
+  /** How many skills and documents the index found at the address, when `ready`. */
   counts: z.optional(z.object({ skills: count, documents: count })),
   /** The skills, when `ready`; empty otherwise. */
   items: z.array(restSkillSchema),
+  /** What the address serves, as the main repository's REST API answers it (`RestMount` of `@skillcdn/core`), for a program that renders what a model is given; `null` when nothing was answered. */
+  mount: z.nullable(packMountSchema),
 });
 export type RestSkills = z.infer<typeof restSkillsSchema>;
 
@@ -945,181 +1061,78 @@ export const restPackTokenInputSchema = z.object({
 });
 export type RestPackTokenInput = z.infer<typeof restPackTokenInputSchema>;
 
-/** A rule, the body or an included file of a skill: its path from the repository's root and its text, cut where a page ends. */
-export const restSkillTextSchema = z.object({
-  path: z.string(),
-  body: z.string(),
-  truncated: z.boolean(),
+/**
+ * `POST .../pack-token/connect` (ADR-0036): what the person is shown, as the deployment said it,
+ * the code and the page to approve it on, until when, and how often the console asks again. The
+ * secret the console claims the token with stays with the console.
+ */
+export const restPackConnectStartedSchema = z.object({
+  code: z.string(),
+  url: z.string(),
+  expiresAt: instant,
+  intervalSeconds: z.int().check(z.positive()),
 });
-/** A skill as the deployment serves it, on one page of its context: what `load_skill` gives a model, in the console's shape. */
-export const restSkillPageSchema = z.object({
-  path: z.string(),
-  directory: z.string(),
-  name: z.string(),
-  description: z.string(),
-  /** The rules that hold for the skill, from the repository's root to the nearest manifest. */
-  rules: z.array(restSkillTextSchema),
-  body: z.string(),
-  /** The files the skill includes with its body. */
-  included: z.array(restSkillTextSchema),
-  /** The paths of the skill's own files, read with the file route. */
-  files: z.array(z.string()),
-  references: z.array(
-    z.object({
-      path: z.string(),
-      status: z.enum(["available", "blocked", "missing", "outside_mount"]),
-    }),
-  ),
-  /** Whether this page completes the skill; else the cursor of the next. */
-  complete: z.boolean(),
-  nextCursor: z.nullable(z.string()),
-  /** How the skill is served: whole, or described only, with its license and where it is read at its host. */
-  serving: z.object({
-    full: z.boolean(),
-    license: z.nullable(z.string()),
-    sourceUrl: z.nullable(z.string()),
-  }),
-  warnings: z.array(z.string()),
+export type RestPackConnectStarted = z.infer<typeof restPackConnectStartedSchema>;
+
+/**
+ * `GET .../pack-token/connect`: how the connection stands. Nothing asked; waiting for the
+ * person, with what they were shown; connected, the token kept and the project as it stands; or
+ * ended short of a token, and why.
+ */
+const packConnectNone = z.object({ status: z.literal("none") });
+const packConnectPending = z.object({
+  status: z.literal("pending"),
+  code: z.string(),
+  url: z.string(),
+  expiresAt: instant,
+  intervalSeconds: z.int().check(z.positive()),
+});
+const packConnectEnded = z.object({
+  status: z.literal("ended"),
+  reason: z.enum(PACK_CONNECT_ENDINGS),
 });
-export type RestSkillPage = z.infer<typeof restSkillPageSchema>;
+export const restPackConnectSchema = z.union([
+  packConnectNone,
+  packConnectPending,
+  z.object({ status: z.literal("connected"), project: restProjectSchema }),
+  packConnectEnded,
+]);
+export type RestPackConnect = z.infer<typeof restPackConnectSchema>;
+
+/** `GET /api/v1/workspace/pack-token/connect`: the same, for the workspace's token, with the workspace as it stands once connected. */
+export const restWorkspacePackConnectSchema = z.union([
+  packConnectNone,
+  packConnectPending,
+  z.object({ status: z.literal("connected"), workspace: restWorkspaceSchema }),
+  packConnectEnded,
+]);
+export type RestWorkspacePackConnect = z.infer<typeof restWorkspacePackConnectSchema>;
 
-/** `GET .../skills/one?path=&cursor=`: one skill of the pack, a page of it; `skill` is `null` unless `ready`. */
+/** `GET .../skills/one?path=&cursor=`: a page of a skill's context, as the pack answers `load_skill` (`RestSkill` of `@skillcdn/core`); `read` is `null` unless `ready`. */
 export const restSkillLoadSchema = z.object({
-  address: z.nullable(z.string()),
-  source: z.string(),
-  page: z.nullable(z.string()),
-  status: z.enum(SKILLS_STATUSES),
-  skill: z.nullable(restSkillPageSchema),
+  ...packEnvelope,
+  read: z.nullable(packSkillSchema),
 });
 export type RestSkillLoad = z.infer<typeof restSkillLoadSchema>;
 
-/** `GET .../skills/file?path=&offset=&limit=`: a page of a file of the pack, or what a folder holds; both `null` unless `ready`. */
+/** `GET .../skills/file?path=&offset=&limit=`: a page of a file, or what a folder holds, as the pack answers `read_repo_file` (`RestFile` of `@skillcdn/core`); `read` is `null` unless `ready`. */
 export const restSkillFileSchema = z.object({
-  address: z.nullable(z.string()),
-  source: z.string(),
-  status: z.enum(SKILLS_STATUSES),
-  file: z.nullable(
-    z.object({
-      path: z.string(),
-      content: z.string(),
-      offset: count,
-      nextOffset: z.nullable(count),
-      totalLength: count,
-    }),
-  ),
-  folder: z.nullable(
-    z.object({
-      path: z.string(),
-      entries: z.array(
-        z.object({
-          path: z.string(),
-          kind: z.enum(["directory", "file"]),
-          size: z.nullable(count),
-        }),
-      ),
-      truncated: z.boolean(),
-    }),
-  ),
+  ...packEnvelope,
+  read: z.nullable(packFileSchema),
 });
 export type RestSkillFile = z.infer<typeof restSkillFileSchema>;
 
-/** An entry of a folder of the pack, as the deployment browses it: a skill, a folder with what it holds, or a file. */
-export const restSkillBrowseEntrySchema = z.object({
-  kind: z.enum(["skill", "directory", "file"]),
-  /** The path from the repository's root: of the `SKILL.md` for a skill, of the folder, of the file. */
-  path: z.string(),
-  name: z.nullable(z.string()),
-  description: z.nullable(z.string()),
-  /** For a folder: the skills and the documents under it. */
-  skillCount: count,
-  documentCount: count,
-  /** For a file: its size in bytes. */
-  size: z.nullable(count),
-  /** For a folder: the README that introduces it, read with the file route. */
-  overviewPath: z.nullable(z.string()),
-  /** For a skill: its license, and whether the address only describes it. */
-  license: z.nullable(z.string()),
-  describedOnly: z.boolean(),
-});
-export type RestSkillBrowseEntry = z.infer<typeof restSkillBrowseEntrySchema>;
-
-/** `GET .../skills/browse?path=&cursor=&limit=`: what a folder of the pack holds, a page of it (`browse_repo`); `folder` is `null` unless `ready`. */
+/** `GET .../skills/browse?path=&cursor=&limit=`: what a folder holds, a page of it, as the pack answers `browse_repo` (`RestBrowse` of `@skillcdn/core`); `read` is `null` unless `ready`. */
 export const restSkillBrowseSchema = z.object({
-  address: z.nullable(z.string()),
-  source: z.string(),
-  page: z.nullable(z.string()),
-  status: z.enum(SKILLS_STATUSES),
-  folder: z.nullable(
-    z.object({
-      path: z.string(),
-      /** The README that introduces the folder, or `null`. */
-      overview: z.nullable(
-        z.object({
-          path: z.string(),
-          title: z.nullable(z.string()),
-          description: z.nullable(z.string()),
-        }),
-      ),
-      entries: z.array(restSkillBrowseEntrySchema),
-      /** Where the listing goes on, or `null` at its end. */
-      nextCursor: z.nullable(z.string()),
-    }),
-  ),
+  ...packEnvelope,
+  read: z.nullable(packBrowseSchema),
 });
 export type RestSkillBrowse = z.infer<typeof restSkillBrowseSchema>;
 
-/** What a search of the pack found: a skill, as the listing has it, with the files of it that matched; or a document on its own. */
-export const restSkillFindItemSchema = z.discriminatedUnion("kind", [
-  z.object({
-    kind: z.literal("skill"),
-    name: z.string(),
-    description: z.string(),
-    directory: z.string(),
-    path: z.string(),
-    page: z.string(),
-    uri: z.nullable(z.string()),
-    translations: z.record(
-      z.string(),
-      z.object({ title: z.nullable(z.string()), description: z.nullable(z.string()) }),
-    ),
-    /** The files of the skill that matched, a few, and how many more did. */
-    files: z.array(
-      z.object({
-        path: z.string(),
-        title: z.nullable(z.string()),
-        summary: z.nullable(z.string()),
-      }),
-    ),
-    moreFiles: count,
-    license: z.nullable(z.string()),
-    describedOnly: z.boolean(),
-  }),
-  z.object({
-    kind: z.literal("document"),
-    path: z.string(),
-    title: z.nullable(z.string()),
-    summary: z.nullable(z.string()),
-    /** The folder of the skill the document belongs to, or `null` for one on its own. */
-    skillDirectory: z.nullable(z.string()),
-  }),
-]);
-export type RestSkillFindItem = z.infer<typeof restSkillFindItemSchema>;
-
-/** `GET .../skills/find?query=&path=&cursor=&limit=`: what words find in the pack, a page of it in relevance order (`search_repo`); `found` is `null` unless `ready`. */
+/** `GET .../skills/find?query=&path=&cursor=&limit=`: what words find, a page of it in relevance order, as the pack answers `search_repo` (`RestFind` of `@skillcdn/core`); `read` is `null` unless `ready`. */
 export const restSkillFindSchema = z.object({
-  address: z.nullable(z.string()),
-  source: z.string(),
-  page: z.nullable(z.string()),
-  status: z.enum(SKILLS_STATUSES),
-  found: z.nullable(
-    z.object({
-      query: z.string(),
-      /** The folder the search was kept to, or `null` for the whole pack. */
-      path: z.nullable(z.string()),
-      items: z.array(restSkillFindItemSchema),
-      nextCursor: z.nullable(z.string()),
-    }),
-  ),
+  ...packEnvelope,
+  read: z.nullable(packFindSchema),
 });
 export type RestSkillFind = z.infer<typeof restSkillFindSchema>;