@skillcdn/console 0.1.6 → 0.1.7

package/src/text.ts

@@ -0,0 +1,33 @@
+/**
+ * Code points that never belong in text the console accepts, stores or shows: control
+ * characters, and the invisible or direction-changing ones that make one string look like
+ * another. A body keeps its line breaks and tabs; a title has no use for them.
+ */
+function isForbidden(codePoint: number, multiline: boolean): boolean {
+  if (codePoint <= 0x1f) {
+    return !(multiline && (codePoint === 0x09 || codePoint === 0x0a || codePoint === 0x0d));
+  }
+  return (
+    (codePoint >= 0x7f && codePoint <= 0x9f) ||
+    (codePoint >= 0x200b && codePoint <= 0x200f) ||
+    (codePoint >= 0x2028 && codePoint <= 0x202e) ||
+    (codePoint >= 0x2060 && codePoint <= 0x2069) ||
+    codePoint === 0xfeff
+  );
+}
+
+/**
+ * True when the string is malformed UTF-16 or holds a forbidden code point. Linear in the input.
+ * With `multiline`, line breaks and tabs are allowed, as a body needs them.
+ */
+export function hasForbiddenCodePoint(value: string, multiline = false): boolean {
+  if (!value.isWellFormed()) {
+    return true;
+  }
+  for (const character of value) {
+    if (isForbidden(character.codePointAt(0) ?? 0, multiline)) {
+      return true;
+    }
+  }
+  return false;
+}

package/src/use-action.ts

@@ -0,0 +1,37 @@
+import { useState } from "react";
+import { ApiError } from "./api.js";
+import { en } from "./i18n/en.js";
+import { useWords } from "./i18n/index.js";
+
+// A change a page makes: run it, keep what went wrong for the page, and say while it is busy.
+// Shared by the compositions, so that every page says the same thing the same way.
+
+/** What a failure says to a person: the server's words, or the language's own for the rest. */
+export function errorWords(
+  error: unknown,
+  fallback: string = en.common.somethingWentWrong,
+): string {
+  if (error instanceof ApiError) {
+    return error.message;
+  }
+  return fallback;
+}
+
+/** Runs a change, keeps what went wrong for the page, and says when it is busy. */
+export function useAction() {
+  const words = useWords();
+  const [busy, setBusy] = useState(false);
+  const [error, setError] = useState<string | undefined>(undefined);
+  const act = async (work: () => Promise<unknown>) => {
+    setBusy(true);
+    setError(undefined);
+    try {
+      await work();
+    } catch (failure) {
+      setError(errorWords(failure, words.common.somethingWentWrong));
+    } finally {
+      setBusy(false);
+    }
+  };
+  return { busy, error, act };
+}

package/src/vocabulary.ts

@@ -0,0 +1,109 @@
+// The concepts the schema, the API and the UI are named after (docs/architecture.md,
+// "Vocabulary"). A list here is a check constraint in the database, an enum in the schemas, and
+// a column or a badge on the board: one source for all three.
+
+/** The states a task moves through, in the order it usually does. */
+export const TASK_STATES = [
+  "idea",
+  "ready",
+  "in_progress",
+  "in_review",
+  "done",
+  "dropped",
+] as const;
+
+export type TaskState = (typeof TASK_STATES)[number];
+
+/** How much a task matters next to the others, in rising order. */
+export const TASK_PRIORITIES = ["low", "normal", "high", "urgent"] as const;
+
+export type TaskPriority = (typeof TASK_PRIORITIES)[number];
+
+/** The identity providers people may sign in through: the git host, and Google (Workspace). */
+export const PROVIDER_KEYS = ["gh", "google"] as const;
+
+export type ProviderKey = (typeof PROVIDER_KEYS)[number];
+
+export function isProviderKey(value: string | null | undefined): value is ProviderKey {
+  return (PROVIDER_KEYS as readonly string[]).includes(value ?? "");
+}
+
+/** What a person may do: an administrator configures the board, a member works on it. */
+export const PERSON_ROLES = ["admin", "member"] as const;
+
+export type PersonRole = (typeof PERSON_ROLES)[number];
+
+/** What a person is within a project: an owner configures it, a member works on it. */
+export const PROJECT_ROLES = ["owner", "member"] as const;
+
+export type ProjectRole = (typeof PROJECT_ROLES)[number];
+
+/** Who is a member of a project: every member of the workspace, or only those listed. */
+export const PROJECT_VISIBILITIES = ["workspace", "private"] as const;
+
+export type ProjectVisibility = (typeof PROJECT_VISIBILITIES)[number];
+
+/** What a run is doing: at work, waiting for a person's decision, or over in one of three ways. */
+export const RUN_STATUSES = ["running", "waiting", "finished", "failed", "abandoned"] as const;
+
+export type RunStatus = (typeof RUN_STATUSES)[number];
+
+/** How a run is over, as the agent says: the work is done, it could not be, or it was left. */
+export const RUN_ENDINGS = ["finished", "failed", "abandoned"] as const;
+
+export type RunEnding = (typeof RUN_ENDINGS)[number];
+
+/** What links to a document by its path: another document, a task, or a decision. */
+export const LINK_SOURCES = ["document", "task", "decision"] as const;
+
+export type LinkSource = (typeof LINK_SOURCES)[number];
+
+/** What a run hands in: a link to the web, or a file the console keeps. */
+export const ARTIFACT_KINDS = ["link", "file"] as const;
+
+export type ArtifactKind = (typeof ARTIFACT_KINDS)[number];
+
+/**
+ * What the console says of the organization's skills: that it has no address for them, or what
+ * the SkillCDN deployment answered for the address.
+ */
+export const SKILLS_STATUSES = [
+  "none",
+  "ready",
+  "indexing",
+  "failed",
+  "not_found",
+  "unavailable",
+] as const;
+
+export type SkillsStatus = (typeof SKILLS_STATUSES)[number];
+
+/**
+ * What can happen to the board. Every change of state is one of these, written down once with
+ * who did it: the live feed shows them as they happen, and the audit trail keeps them.
+ */
+export const EVENT_KINDS = [
+  "person.joined",
+  "person.role_changed",
+  "project.created",
+  "project.updated",
+  "project.member_added",
+  "project.member_changed",
+  "project.member_removed",
+  "task.created",
+  "task.updated",
+  "task.moved",
+  "decision.raised",
+  "decision.answered",
+  "decision.updated",
+  "run.started",
+  "run.reported",
+  "run.handed_in",
+  "run.ended",
+  "document.written",
+  "document.archived",
+  "document.restored",
+  "document.file_attached",
+] as const;
+
+export type EventKind = (typeof EVENT_KINDS)[number];

package/src/web.ts

@@ -0,0 +1,170 @@
+import { createHash } from "node:crypto";
+import { readdir, readFile, stat } from "node:fs/promises";
+import { extname, join, relative, sep } from "node:path";
+
+// Serves a build of a console: static files, and the one page for every path that is not a
+// file, since the pages route in the browser. What the image serves the default UI with, from
+// WEB_ROOT, and what `console serve` serves a person's own build with (ADR-0014): one
+// policy for both. Nothing here knows the UI but the directory; a deployment without one is
+// API only. Node only: `@skillcdn/console/web`.
+
+const MAX_FILES = 5000;
+const HTML = "text/html; charset=utf-8";
+
+const CONTENT_TYPES: Readonly<Record<string, string>> = {
+  ".css": "text/css; charset=utf-8",
+  ".js": "text/javascript; charset=utf-8",
+  ".mjs": "text/javascript; charset=utf-8",
+  ".json": "application/json; charset=utf-8",
+  ".map": "application/json; charset=utf-8",
+  ".svg": "image/svg+xml",
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".webp": "image/webp",
+  ".gif": "image/gif",
+  ".ico": "image/x-icon",
+  ".txt": "text/plain; charset=utf-8",
+  ".webmanifest": "application/manifest+json",
+  ".woff2": "font/woff2",
+  ".woff": "font/woff",
+};
+
+/**
+ * Pages show what people and agents wrote, which is untrusted. Nothing inline runs, nothing
+ * loads from elsewhere but pictures over https, and nobody frames the page.
+ */
+const PAGE_HEADERS: Readonly<Record<string, string>> = {
+  "content-security-policy": [
+    "default-src 'self'",
+    "script-src 'self'",
+    "style-src 'self'",
+    "img-src 'self' data: https:",
+    "font-src 'self'",
+    "connect-src 'self'",
+    "object-src 'none'",
+    "base-uri 'none'",
+    "form-action 'self'",
+    "frame-ancestors 'none'",
+  ].join("; "),
+  "referrer-policy": "strict-origin-when-cross-origin",
+  "x-content-type-options": "nosniff",
+  "x-frame-options": "DENY",
+  "cross-origin-opener-policy": "same-origin",
+};
+
+/** Paths that belong to the API and never to the pages: they answer their own not-found. */
+const NOT_PAGES = ["/api/", "/auth/", "/healthz", "/readyz"];
+
+export class WebRootError extends Error {
+  constructor(message: string, options?: { readonly cause?: unknown }) {
+    super(message, options);
+    this.name = "WebRootError";
+  }
+}
+
+interface StaticFile {
+  readonly file: string;
+  readonly contentType: string;
+  readonly etag: string;
+  readonly size: number;
+  readonly cacheControl: string;
+}
+
+export interface WebRoot {
+  /** The file at the path, the page for a path of the app, or nothing for the API's paths. */
+  respond(request: Request): Promise<Response | undefined>;
+  readonly files: number;
+}
+
+async function listFiles(directory: string): Promise<string[]> {
+  const found: string[] = [];
+  const walk = async (current: string): Promise<void> => {
+    for (const entry of await readdir(current, { withFileTypes: true })) {
+      if (found.length >= MAX_FILES) {
+        throw new WebRootError(`more than ${MAX_FILES} files`);
+      }
+      const path = join(current, entry.name);
+      if (entry.isDirectory()) {
+        await walk(path);
+      } else if (entry.isFile()) {
+        found.push(path);
+      }
+    }
+  };
+  await walk(directory);
+  return found;
+}
+
+/**
+ * Reads the build once: the files it has, and the page. Only what was listed is ever served,
+ * so a path can name nothing outside the directory, whatever it spells.
+ */
+export async function loadWebRoot(directory: string): Promise<WebRoot> {
+  let page: Buffer;
+  try {
+    page = await readFile(join(directory, "index.html"));
+  } catch (error) {
+    throw new WebRootError(`${directory} holds no index.html`, { cause: error });
+  }
+  const pageEtag = `"${createHash("sha256").update(page).digest("base64url").slice(0, 27)}"`;
+  const files = new Map<string, StaticFile>();
+  for (const file of await listFiles(directory)) {
+    const path = `/${relative(directory, file).split(sep).join("/")}`;
+    if (path === "/index.html") {
+      continue;
+    }
+    const info = await stat(file);
+    // A build names its bundles by their content: those never change, and may be kept forever.
+    const immutable = path.startsWith("/assets/");
+    files.set(path, {
+      file,
+      contentType: CONTENT_TYPES[extname(path).toLowerCase()] ?? "application/octet-stream",
+      etag: `W/"${info.size.toString(16)}-${Math.floor(info.mtimeMs).toString(16)}"`,
+      size: info.size,
+      cacheControl: immutable ? "public, max-age=31536000, immutable" : "no-cache",
+    });
+  }
+
+  const respond = async (request: Request): Promise<Response | undefined> => {
+    if (request.method !== "GET" && request.method !== "HEAD") {
+      return undefined;
+    }
+    const { pathname } = new URL(request.url);
+    if (NOT_PAGES.some((prefix) => pathname === prefix || pathname.startsWith(prefix))) {
+      return undefined;
+    }
+    const found = files.get(pathname);
+    const head = request.method === "HEAD";
+    if (found !== undefined) {
+      const headers = {
+        "content-type": found.contentType,
+        "cache-control": found.cacheControl,
+        etag: found.etag,
+        "x-content-type-options": "nosniff",
+      };
+      if (request.headers.get("if-none-match") === found.etag) {
+        return new Response(null, { status: 304, headers });
+      }
+      return new Response(head ? null : new Uint8Array(await readFile(found.file)), {
+        status: 200,
+        headers: { ...headers, "content-length": String(found.size) },
+      });
+    }
+    // Every other path is a page of the app, which routes in the browser; what is not one is
+    // the app's own not-found page, and a crawler reads the shell either way.
+    const headers = {
+      ...PAGE_HEADERS,
+      "content-type": HTML,
+      "cache-control": "no-cache",
+      etag: pageEtag,
+      "content-length": String(page.byteLength),
+    };
+    if (request.headers.get("if-none-match") === pageEtag) {
+      return new Response(null, { status: 304, headers });
+    }
+    return new Response(head ? null : new Uint8Array(page), { status: 200, headers });
+  };
+
+  return { respond, files: files.size };
+}