@skillcdn/console 0.1.24 → 0.3.0

package/src/data.ts

@@ -245,6 +245,28 @@ async function readTasks(
   return { items };
 }
 
+/** How many pages of the decisions are read before the record is shown as it stands. */
+const DECISIONS_MAX_PAGES = 20;
+
+/**
+ * The decisions of a project, whole: page after page while the server says there is more, so
+ * that the record is read to its end and the pages turn it without asking again.
+ */
+async function readDecisions(
+  scope: ProjectClient,
+  signal: AbortSignal | undefined,
+): Promise<{ readonly items: RestDecision[] }> {
+  const items: RestDecision[] = [];
+  for (let page = 0; page < DECISIONS_MAX_PAGES; page += 1) {
+    const result = await scope.decisions({ limit: LIST_LIMIT, offset: page * LIST_LIMIT }, signal);
+    items.push(...result.items);
+    if (!result.more) {
+      break;
+    }
+  }
+  return { items };
+}
+
 const wordsOf = (failure: unknown, fallback: string): string =>
   failure instanceof ApiError ? failure.message : fallback;
 
@@ -310,7 +332,7 @@ export function useConsoleData(client: ConsoleClient, projectKey: string | undef
         await Promise.all([
           scope.get(signal),
           readTasks(scope, signal),
-          scope.decisions(undefined, signal),
+          readDecisions(scope, signal),
           scope.goals({}, signal),
           scope.runs(undefined, signal),
           scope.members(signal),
@@ -427,7 +449,15 @@ export function useConsoleData(client: ConsoleClient, projectKey: string | undef
           // No answer at all is said on the page as the deployment being out of reach,
           // rather than waited for.
           if (!signal.aborted) {
-            setSkills({ address: null, source: "", page: null, status: "unavailable", items: [] });
+            setSkills({
+              address: null,
+              source: "",
+              page: null,
+              status: "unavailable",
+              refusal: null,
+              items: [],
+              mount: null,
+            });
           }
         });
       if (typeof EventSource === "undefined") {

package/src/i18n/en.ts

@@ -9,6 +9,7 @@ import type {
   ProjectVisibility,
   ProviderKey,
   RunStatus,
+  SkillsStatus,
   TaskPriority,
   TaskState,
 } from "../vocabulary.js";
@@ -102,6 +103,12 @@ export const en = {
     copy: "Copy",
     copied: "Copied",
     showMore: (n: number, of: number) => `Show ${n} more of ${of}`,
+    pager: {
+      label: "Pages",
+      previous: "Previous page",
+      next: "Next page",
+      range: (from: number, to: number, of: number) => `${from}-${to} of ${of}`,
+    },
   },
 
   nav: {
@@ -325,6 +332,9 @@ export const en = {
     waitingForPerson: "Waiting for a person.",
     options: "Options",
     notePlaceholder: "A word about it, if any",
+    own: "Something else",
+    ownPlaceholder: "Your answer, in a line",
+    ownAnswer: "in their own words",
     answer: "Answer",
     asked: "asked",
     askedThrough: (agent: string) => `asked through ${agent}`,
@@ -662,6 +672,14 @@ export const en = {
     connect:
       "An agent reads these with the console command (console skill <path>), or through its own MCP connection to this address, which a person makes once:",
     connectLink: "how, on the address's page at SkillCDN",
+    fromMachine: "Read from a directory on the console's machine, at",
+    connectLocal:
+      "An agent reads these with the console command (console skill <path>); the pack is on the console's machine and nowhere else.",
+    localStatus: {
+      not_found:
+        "No pack is served from the console's machine at this address: whoever runs the console puts it in the packs directory, as <owner>/<name>.",
+      unavailable: "The pack could not be read from the console's machine. Look again later.",
+    } as Partial<Record<SkillsStatus, string>>,
     status: {
       indexing: "SkillCDN is still indexing the repository. Look again in a moment.",
       failed: "SkillCDN could not index the repository. What it found is on the address's page.",

package/src/i18n/ko.ts

@@ -72,6 +72,12 @@ export const ko: Messages = {
     copy: "복사",
     copied: "복사됨",
     showMore: (n, of) => `${of}개 중 ${n}개 더 보기`,
+    pager: {
+      label: "페이지",
+      previous: "이전",
+      next: "다음",
+      range: (from, to, of) => `${of}건 중 ${from}-${to}`,
+    },
   },
 
   nav: {
@@ -294,6 +300,9 @@ export const ko: Messages = {
     waitingForPerson: "사람을 기다리는 중입니다.",
     options: "선택지",
     notePlaceholder: "덧붙일 말이 있다면",
+    own: "직접 입력",
+    ownPlaceholder: "원하는 답을 한 줄로",
+    ownAnswer: "직접 입력",
     answer: "답변",
     asked: "질문",
     askedThrough: (agent) => `${agent}을(를) 통해 질문`,
@@ -626,6 +635,14 @@ export const ko: Messages = {
     connect:
       "에이전트는 콘솔 명령(console skill <경로>)으로, 또는 이 주소에 자기 MCP 연결로 스킬을 받습니다. MCP 연결은 사람이 한 번 해 줍니다:",
     connectLink: "SkillCDN 페이지의 연결 안내",
+    fromMachine: "콘솔 기계의 디렉터리에서 읽음, 주소:",
+    connectLocal:
+      "에이전트는 콘솔 명령(console skill <경로>)으로 읽습니다. 이 팩은 콘솔 기계에만 있습니다.",
+    localStatus: {
+      not_found:
+        "이 주소로 콘솔 기계에서 제공되는 팩이 없습니다. 콘솔 운영자가 팩 디렉터리에 <owner>/<name>으로 넣습니다.",
+      unavailable: "콘솔 기계에서 팩을 읽지 못했습니다. 나중에 다시 보세요.",
+    },
     status: {
       indexing: "SkillCDN이 아직 저장소를 색인하고 있습니다. 잠시 후 다시 보세요.",
       failed: "SkillCDN이 저장소를 색인하지 못했습니다. 찾은 내용은 주소의 페이지에 있습니다.",

package/src/index.ts

@@ -82,7 +82,14 @@ export {
   goalMonth,
 } from "./components/goals.js";
 export { Markdown, type MarkdownProps } from "./components/markdown.js";
-export { PAGE_SIZE, ShowMore, usePaged } from "./components/paged.js";
+export {
+  PAGE_SIZE,
+  Pager,
+  pageOf,
+  RECORD_PAGE_SIZE,
+  ShowMore,
+  usePaged,
+} from "./components/paged.js";
 export {
   ListingForm,
   type ListingFormProps,
@@ -246,6 +253,7 @@ export {
   customPageHref,
   type DocsView,
   decisionHref,
+  decisionsHref,
   docHref,
   GOAL_TASK_VIEWS,
   type GoalPageOptions,

package/src/router.ts

@@ -5,7 +5,7 @@ import { isDay, isMonth } from "./dates.js";
 // route, and the hrefs below are its inverse. A project's pages live under `/projects/<key>`,
 // the word the REST API uses; an address names what it shows (a task by its number, a decision
 // by its id, a document by its path, a goal by its id), every form has one, and the query says
-// how a page is shown (`?edit`, `?ask`, `?new`, `?version=`, `?q=`, `?month=`, `?week=`, and the
+// how a page is shown (`?edit`, `?ask`, `?new`, `?version=`, `?q=`, `?month=`, `?week=`, `?page=`, and the
 // board's filters). The old addresses are taken to the new.
 
 /** How a task's page is shown: as it is, or with one of its forms open. */
@@ -49,7 +49,8 @@ export type Route =
       readonly path: string;
       readonly view: DocsView;
     }
-  | { readonly name: "decisions"; readonly project: string }
+  /** The decisions of a project: the waiting ones, and the record on one of its pages, the first when the address names none. */
+  | { readonly name: "decisions"; readonly project: string; readonly page: number | undefined }
   | { readonly name: "new-decision"; readonly project: string }
   | { readonly name: "decision"; readonly project: string; readonly id: string }
   /** The calendar of a project: the month shown, or this one when the address names none, narrowed as the board is. */
@@ -155,13 +156,10 @@ const NUMBER = /^[1-9][0-9]{0,8}$/;
 /** A code as it may be typed into an address: checked for what it is by the page. */
 const CODE_TEXT = /^[A-Za-z0-9-]{1,16}$/;
 /** The pages of a project that take nothing after their name. */
-const PLAIN_PAGES: readonly Exclude<ProjectPage, "docs" | "calendar" | "roadmap" | "settings">[] = [
-  "decisions",
-  "archive",
-  "feed",
-  "skills",
-  "members",
-];
+const PLAIN_PAGES: readonly Exclude<
+  ProjectPage,
+  "docs" | "decisions" | "calendar" | "roadmap" | "settings"
+>[] = ["archive", "feed", "skills", "members"];
 const NOT_FOUND: Route = { name: "not-found" };
 
 /** Where an address of the 0.1 line before this one leads now, or nothing for a current one. */
@@ -386,6 +384,13 @@ export function matchRoute(pathname: string, search = ""): Route {
             : undefined,
     };
   }
+  if (page === "decisions") {
+    const turned = params.get("page");
+    if (turned !== null && !NUMBER.test(turned)) {
+      return NOT_FOUND;
+    }
+    return { name: "decisions", project, page: turned === null ? undefined : Number(turned) };
+  }
   const found = PLAIN_PAGES.find((candidate) => candidate === page);
   return found === undefined ? NOT_FOUND : { name: found, project };
 }
@@ -469,6 +474,12 @@ export function decisionHref(key: string, id: string): string {
   return `${PATHS.project}/${key}/decisions/${id}`;
 }
 
+/** Where a project's decisions are: the waiting ones and the record, on one of its pages, or on the first when none is named. */
+export function decisionsHref(key: string, page?: number): string {
+  const base = projectHref(key, "decisions");
+  return page === undefined || page <= 1 ? base : `${base}?page=${page}`;
+}
+
 /** Where the person's own work is, with the week of a day at the top, or this week's when none is named. */
 export function workHref(week?: string): string {
   return week === undefined ? PATHS.work : `${PATHS.work}?week=${week}`;

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 {
@@ -548,9 +555,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 +659,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 +920,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 +963,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 +974,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 +991,31 @@ 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(),
-});
-/** 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 RestSkillPage = z.infer<typeof restSkillPageSchema>;
-
-/** `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>;