@skillcdn/console 0.1.6 → 0.1.7

package/src/limits.ts

@@ -0,0 +1,61 @@
+// How much of anything the console takes in. Every text a person or an agent writes is bounded
+// at the edge (AGENTS.md, rule 2); these are the bounds, shared by the server that enforces them
+// and the pages that say so before a request is made.
+
+/** A task's title, a decision's question: one line. */
+export const MAX_TITLE_LENGTH = 200;
+export const MAX_QUESTION_LENGTH = 500;
+/** A body in Markdown: a task's, or the context of a decision. */
+export const MAX_BODY_LENGTH = 20_000;
+/** The links of a task: a repository, a pull request, a document. */
+export const MAX_LINKS = 20;
+export const MAX_LINK_LABEL_LENGTH = 120;
+export const MAX_URL_LENGTH = 2048;
+/** The options of a decision, and how a person words each. */
+export const MIN_OPTIONS = 2;
+export const MAX_OPTIONS = 10;
+export const MAX_OPTION_LABEL_LENGTH = 120;
+/** What a person adds to an answer. */
+export const MAX_NOTE_LENGTH = 2000;
+/** How many tasks or decisions one listing answers with. A board is read whole, for now. */
+export const LIST_LIMIT = 500;
+/** How many events one page of the feed carries. */
+export const EVENTS_PAGE_LIMIT = 100;
+/** What an agent calls itself when it takes a task: its kind, where it runs. One line. */
+export const MAX_AGENT_LENGTH = 80;
+/** What an agent says when it ends a run. Markdown. */
+export const MAX_SUMMARY_LENGTH = 2000;
+/** How many reports, and how many artifacts, one run may carry. */
+export const MAX_REPORTS_PER_RUN = 500;
+export const MAX_ARTIFACTS_PER_RUN = 50;
+/** A file a run hands in: how many bytes, and its name, one line without a path. */
+export const MAX_FILE_BYTES = 10 * 1024 * 1024;
+export const MAX_FILE_NAME_LENGTH = 200;
+/** What a person calls a token: the agent it is for, where it runs. One line. */
+export const MAX_TOKEN_NAME_LENGTH = 80;
+/** How long a token may be good for, in days, and how long one is when nothing is said. */
+export const MAX_TOKEN_DAYS = 365;
+export const DEFAULT_TOKEN_DAYS = 90;
+/** How many tokens one person may hold at a time. */
+export const MAX_TOKENS_PER_PERSON = 25;
+/** How long a secret a client presents in a body may be: a token or a connection's secret is far shorter. */
+export const MAX_SECRET_LENGTH = 200;
+/** How long a language tag may be: the longest a browser sends is far shorter. */
+export const MAX_LANGUAGE_TAG_LENGTH = 35;
+/** A project's key, what paths and the command say: lowercase letters, digits and hyphens. */
+export const MAX_PROJECT_KEY_LENGTH = 40;
+/** A project's name, one line, and its description, a paragraph. */
+export const MAX_PROJECT_NAME_LENGTH = 100;
+export const MAX_PROJECT_DESCRIPTION_LENGTH = 500;
+/** The address of a project's skills, as the standard spells one; the console checks it as one. */
+export const MAX_SKILLS_ADDRESS_LENGTH = 2048;
+/** A document's path: segments of lowercase letters, digits and hyphens, separated by slashes. */
+export const MAX_DOCUMENT_PATH_LENGTH = 200;
+export const MAX_DOCUMENT_SEGMENT_LENGTH = 64;
+/** A document's body: a page of Markdown. */
+export const MAX_DOCUMENT_LENGTH = 64_000;
+/** How many versions one document keeps, and how many files attach to one. */
+export const MAX_VERSIONS_PER_DOCUMENT = 500;
+export const MAX_FILES_PER_DOCUMENT = 50;
+/** The words a search of the documents takes. */
+export const MAX_SEARCH_LENGTH = 200;

package/src/router.ts

@@ -0,0 +1,295 @@
+import { isFolderPath, isSignInFailure, SIGN_IN_PARAM, type SignInFailure } from "./api.js";
+
+// The addresses of the default console (ADR-0010): the router is a function from a URL to a
+// 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), every form has one, and the query says how a page is
+// shown (`?edit`, `?ask`, `?new`, `?version=`, `?q=`). 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. */
+export type TaskFormKind = "edit" | "ask";
+
+/** How the documents are shown at a path: a folder or a page, a form, a version, or a search. */
+export type DocsView =
+  | { readonly kind: "read"; readonly version?: number | undefined }
+  | { readonly kind: "new" }
+  | { readonly kind: "edit" }
+  | { readonly kind: "search"; readonly q: string };
+
+export type Route =
+  | { readonly name: "projects" }
+  | { readonly name: "new-project" }
+  | { readonly name: "board"; readonly project: string }
+  | { readonly name: "new-task"; readonly project: string }
+  | {
+      readonly name: "task";
+      readonly project: string;
+      /** The task's number, or nothing when the address names it by id. */
+      readonly number: number | undefined;
+      readonly id: string | undefined;
+      readonly form: TaskFormKind | undefined;
+    }
+  | {
+      readonly name: "docs";
+      readonly project: string;
+      readonly path: string;
+      readonly view: DocsView;
+    }
+  | { readonly name: "decisions"; readonly project: string }
+  | { readonly name: "new-decision"; readonly project: string }
+  | { readonly name: "decision"; readonly project: string; readonly id: string }
+  | { readonly name: "feed"; readonly project: string }
+  | { readonly name: "skills"; readonly project: string }
+  | { readonly name: "members"; readonly project: string }
+  | { readonly name: "settings"; readonly project: string }
+  | { readonly name: "people" }
+  /** The agents of one person, for an administrator. */
+  | { readonly name: "person-agents"; readonly id: string }
+  | { readonly name: "agents" }
+  | { readonly name: "new-token" }
+  /** Where a person approves an agent's connection, by the code it showed, or types one. */
+  | { readonly name: "connect"; readonly code: string | undefined }
+  /** An address that moved: the page takes the person to `to` in its place. */
+  | { readonly name: "moved"; readonly to: string }
+  | { readonly name: "not-found" };
+
+/** The pages of a project, after its key. */
+export type ProjectPage = "docs" | "decisions" | "feed" | "skills" | "members" | "settings";
+
+export const PATHS = {
+  /** The projects the person may see: the front page. */
+  projects: "/",
+  /** Where a project's pages are: `/projects/<key>`, then the page. */
+  project: "/projects",
+  newProject: "/projects/new",
+  people: "/people",
+  /** The agents of whoever is signed in, which hold their tokens: their own page. */
+  agents: "/agents",
+  /** The form for a token made by hand, for a script or a console of one's own. */
+  newToken: "/agents/new",
+  /** Where an agent's connection is approved (ADR-0011): `/connect/<code>`, or the code typed. */
+  connect: "/connect",
+} as const;
+
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const PROJECT_KEY = /^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/;
+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">[] = [
+  "decisions",
+  "feed",
+  "skills",
+  "members",
+  "settings",
+];
+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. */
+export function movedFrom(pathname: string): string | undefined {
+  if (pathname === "/tokens") {
+    return PATHS.agents;
+  }
+  if (pathname === "/p" || pathname.startsWith("/p/")) {
+    return `${PATHS.project}${pathname.slice(2)}`;
+  }
+  if (pathname === PATHS.project) {
+    return PATHS.projects;
+  }
+  return undefined;
+}
+
+const taskFormOf = (params: URLSearchParams): TaskFormKind | undefined =>
+  params.has("edit") ? "edit" : params.has("ask") ? "ask" : undefined;
+
+/** The view the query asks for at a path, or nothing for one the path cannot be shown as. */
+const docsViewOf = (params: URLSearchParams, path: string): DocsView | undefined => {
+  const q = params.get("q");
+  if (q !== null && q.trim().length > 0) {
+    return { kind: "search", q: q.trim() };
+  }
+  if (params.has("new")) {
+    return { kind: "new" };
+  }
+  if (params.has("edit")) {
+    return path === "" ? undefined : { kind: "edit" };
+  }
+  const version = params.get("version");
+  if (version !== null) {
+    return path !== "" && NUMBER.test(version)
+      ? { kind: "read", version: Number(version) }
+      : undefined;
+  }
+  return { kind: "read" };
+};
+
+export function matchRoute(pathname: string, search = ""): Route {
+  const path = pathname.length > 1 ? pathname.replace(/\/+$/, "") : pathname;
+  const moved = movedFrom(path);
+  if (moved !== undefined) {
+    return { name: "moved", to: `${moved}${search}` };
+  }
+  const params = new URLSearchParams(search);
+  if (path === PATHS.projects) {
+    return { name: "projects" };
+  }
+  if (path === PATHS.newProject) {
+    return { name: "new-project" };
+  }
+  if (path === PATHS.people) {
+    return { name: "people" };
+  }
+  if (path === PATHS.agents) {
+    return { name: "agents" };
+  }
+  if (path === PATHS.newToken) {
+    return { name: "new-token" };
+  }
+  if (path === PATHS.connect) {
+    return { name: "connect", code: undefined };
+  }
+  if (path.startsWith(`${PATHS.connect}/`)) {
+    const code = path.slice(PATHS.connect.length + 1);
+    return CODE_TEXT.test(code) ? { name: "connect", code } : NOT_FOUND;
+  }
+  if (path.startsWith(`${PATHS.people}/`)) {
+    const [id, page, ...more] = path.slice(PATHS.people.length + 1).split("/");
+    return id !== undefined && UUID.test(id) && page === "agents" && more.length === 0
+      ? { name: "person-agents", id }
+      : NOT_FOUND;
+  }
+  if (!path.startsWith(`${PATHS.project}/`)) {
+    return NOT_FOUND;
+  }
+  const [project, page, third, ...rest] = path.slice(PATHS.project.length + 1).split("/");
+  if (project === undefined || !PROJECT_KEY.test(project)) {
+    return NOT_FOUND;
+  }
+  if (page === undefined) {
+    return { name: "board", project };
+  }
+  if (page === "docs") {
+    // The rest of the path is the document's, or a folder's, or nothing for the root.
+    const docPath = [third, ...rest].filter((segment) => segment !== undefined).join("/");
+    if (!isFolderPath(docPath)) {
+      return NOT_FOUND;
+    }
+    const view = docsViewOf(params, docPath);
+    return view === undefined ? NOT_FOUND : { name: "docs", project, path: docPath, view };
+  }
+  if (rest.length > 0) {
+    return NOT_FOUND;
+  }
+  if (page === "tasks") {
+    if (third === "new") {
+      return { name: "new-task", project };
+    }
+    if (third !== undefined && NUMBER.test(third)) {
+      return {
+        name: "task",
+        project,
+        number: Number(third),
+        id: undefined,
+        form: taskFormOf(params),
+      };
+    }
+    if (third !== undefined && UUID.test(third)) {
+      return { name: "task", project, number: undefined, id: third, form: taskFormOf(params) };
+    }
+    return NOT_FOUND;
+  }
+  if (page === "decisions" && third !== undefined) {
+    if (third === "new") {
+      return { name: "new-decision", project };
+    }
+    return UUID.test(third) ? { name: "decision", project, id: third } : NOT_FOUND;
+  }
+  if (third !== undefined) {
+    return NOT_FOUND;
+  }
+  const found = PLAIN_PAGES.find((candidate) => candidate === page);
+  return found === undefined ? NOT_FOUND : { name: found, project };
+}
+
+/** Where a person approves an agent's connection by its code, or types one. */
+export function connectHref(code?: string): string {
+  return code === undefined ? PATHS.connect : `${PATHS.connect}/${encodeURIComponent(code)}`;
+}
+
+/** Where an administrator sees one person's agents. */
+export function personAgentsHref(personId: string): string {
+  return `${PATHS.people}/${personId}/agents`;
+}
+
+/** Where a project's board is, or one of its pages. */
+export function projectHref(key: string, page?: ProjectPage): string {
+  const base = `${PATHS.project}/${key}`;
+  return page === undefined ? base : `${base}/${page}`;
+}
+
+/** Where a task is written: the form. */
+export function newTaskHref(key: string): string {
+  return `${PATHS.project}/${key}/tasks/new`;
+}
+
+/** Where a task is read by its number, or one of its forms is open. */
+export function taskHref(key: string, number: number, form?: TaskFormKind): string {
+  const base = `${PATHS.project}/${key}/tasks/${number}`;
+  return form === undefined ? base : `${base}?${form}`;
+}
+
+/** Where a decision is raised from the Decisions page: the form. */
+export function newDecisionHref(key: string): string {
+  return `${PATHS.project}/${key}/decisions/new`;
+}
+
+/** Where one decision is read, and answered. */
+export function decisionHref(key: string, id: string): string {
+  return `${PATHS.project}/${key}/decisions/${id}`;
+}
+
+/**
+ * Where a document of a project is read, or a folder of them listed (`""` for the root), and
+ * how: a form, a version, or a search over all of them.
+ */
+export function docHref(key: string, path: string, view?: DocsView): string {
+  const base = path === "" ? projectHref(key, "docs") : `${PATHS.project}/${key}/docs/${path}`;
+  if (view === undefined) {
+    return base;
+  }
+  switch (view.kind) {
+    case "search":
+      return `${base}?q=${encodeURIComponent(view.q)}`;
+    case "new":
+      return `${base}?new`;
+    case "edit":
+      return `${base}?edit`;
+    case "read":
+      return view.version === undefined ? base : `${base}?version=${view.version}`;
+  }
+}
+
+/** The ways a page moves the person: to an address, in place of the one shown, or back. */
+export interface Navigation {
+  /** Shows the address, as one more step in the history. */
+  go(href: string): void;
+  /** Shows the address in place of the one shown: for a redirect, or for what a form made. */
+  replace(href: string): void;
+  /** Goes back to where the page was reached from, or to `fallback` when there is no such place. */
+  back(fallback: string): void;
+}
+
+/** Why the last sign-in did not complete, as the page's URL says it, or nothing. */
+export function signInFailureOf(search: string): SignInFailure | undefined {
+  const value = new URLSearchParams(search).get(SIGN_IN_PARAM);
+  return isSignInFailure(value) ? value : undefined;
+}
+
+/** The URL without the sign-in parameter, once the page has read it. */
+export function withoutSignInParam(pathname: string, search: string): string {
+  const params = new URLSearchParams(search);
+  params.delete(SIGN_IN_PARAM);
+  const query = params.toString();
+  return query.length === 0 ? pathname : `${pathname}?${query}`;
+}

package/src/routes.ts

@@ -0,0 +1,106 @@
+// Where the console answers (docs/architecture.md). The REST API is for the pages and for a
+// custom console; signing in and out are navigations and one form post, not part of it. The
+// board is nested under the project it belongs to (ADR-0008).
+import type { ProviderKey } from "./vocabulary.js";
+
+/** One prefix per resource of the workspace; an id follows where one is needed. */
+export const REST_ROUTES = {
+  /** Who is signed in, what the workspace is called, and whether anyone can sign in. */
+  me: "/api/v1/me",
+  /** The people of the workspace: everyone who has signed in. */
+  people: "/api/v1/people",
+  /** The projects the asker may see; the board of each is under its key. */
+  projects: "/api/v1/projects",
+  /** The workspace's own events, the ones about no project: who joined, who was made what. */
+  events: "/api/v1/events",
+  /** The tokens of whoever asks: what their agents, scripts and consoles act as them with. */
+  tokens: "/api/v1/tokens",
+  /** Connecting an agent (ADR-0011): begun as nobody, approved by a person, claimed by the command. */
+  connect: "/api/v1/connect",
+} as const;
+
+/** Where the command claims the token of a connection, with its secret. */
+export const CLAIM_PATH = `${REST_ROUTES.connect}/claim`;
+
+/** The REST path of one connection, by its code, or of approving or denying it. */
+export function connectPath(code: string, action?: "approve" | "deny"): string {
+  const base = `${REST_ROUTES.connect}/${encodeURIComponent(code)}`;
+  return action === undefined ? base : `${base}/${action}`;
+}
+
+/** The REST path of a person's tokens, or of one of them: for an administrator. */
+export function personTokensPath(personId: string, tokenId?: string): string {
+  const base = `${restPath("people", personId)}/tokens`;
+  return tokenId === undefined ? base : `${base}/${encodeURIComponent(tokenId)}`;
+}
+
+/** What a project holds, each under `/api/v1/projects/<key>/<collection>`. */
+export const PROJECT_COLLECTIONS = [
+  "tasks",
+  "decisions",
+  "runs",
+  "files",
+  "events",
+  "skills",
+  "members",
+  "docs",
+] as const;
+
+export type ProjectCollection = (typeof PROJECT_COLLECTIONS)[number];
+
+/** Where a browser signs in and out. Signing in is per provider: `/auth/<provider>/...`. */
+export const AUTH_ROUTES = {
+  /** Sends the browser to the provider to sign in, and afterwards to `return_to`. */
+  login: (provider: ProviderKey): string => `/auth/${provider}/login`,
+  /** Where the provider sends the browser back to. */
+  callback: (provider: ProviderKey): string => `/auth/${provider}/callback`,
+  /** A POST from the pages that ends the session. */
+  logout: "/auth/logout",
+} as const;
+
+/** The parameter of the login route naming the page to come back to: a path of this origin. */
+export const RETURN_TO_PARAM = "return_to";
+
+/**
+ * The parameter by which the server tells a page that a sign-in did not complete: the person
+ * said no at the provider, the attempt was not finished in time or in the browser that began
+ * it, the provider did not confirm it, or the account is not a member of the workspace.
+ */
+export const SIGN_IN_PARAM = "sign_in";
+export const SIGN_IN_FAILURES = ["denied", "expired", "failed", "refused"] as const;
+export type SignInFailure = (typeof SIGN_IN_FAILURES)[number];
+
+export function isSignInFailure(value: string | null | undefined): value is SignInFailure {
+  return (SIGN_IN_FAILURES as readonly string[]).includes(value ?? "");
+}
+
+/** Where a browser leaves for the provider to sign in and come back to `returnTo`. */
+export function loginPath(provider: ProviderKey, returnTo: string): string {
+  return `${AUTH_ROUTES.login(provider)}?${RETURN_TO_PARAM}=${encodeURIComponent(returnTo)}`;
+}
+
+/** A page of this origin, told why the sign-in it was waiting for did not complete. */
+export function signInPath(page: string, failure: SignInFailure): string {
+  return `${page}${page.includes("?") ? "&" : "?"}${SIGN_IN_PARAM}=${failure}`;
+}
+
+/** The REST path of one person, token or project: the collection, then the id or the key. */
+export function restPath(collection: "people" | "tokens" | "projects", id: string): string {
+  return `${REST_ROUTES[collection]}/${encodeURIComponent(id)}`;
+}
+
+/**
+ * The REST path of a project, of one of its collections, or of one item in it: the tasks of
+ * `web` are at `projectPath("web", "tasks")`, task 7 at `projectPath("web", "tasks", "7")`.
+ * A document's path is one segment of the URL, its slashes encoded: `projectPath("web",
+ * "docs", "guides/onboarding")` is `/api/v1/projects/web/docs/guides%2Fonboarding`.
+ */
+export function projectPath(key: string, collection?: ProjectCollection, id?: string): string {
+  const base = restPath("projects", key);
+  if (collection === undefined) {
+    return base;
+  }
+  return id === undefined
+    ? `${base}/${collection}`
+    : `${base}/${collection}/${encodeURIComponent(id)}`;
+}