@sixb/core 0.1.20 → 0.1.21

package/src/artifacts/csv.ts

@@ -0,0 +1,108 @@
+/**
+ * The one CSV reader for sheets, used when a sheet is published and when it is shown, so both read
+ * the same cells. RFC 4180: fields split on commas (or tabs); a quoted field may hold separators,
+ * line breaks, and doubled quotes; lines end in CRLF, LF, or CR; a leading byte-order mark is not
+ * part of the text; blank lines are skipped. Rows come back as they were written, some shorter or
+ * longer than the header: the reader of the table decides what that means.
+ */
+export interface CsvTable {
+  readonly header: readonly string[]
+  readonly rows: readonly (readonly string[])[]
+}
+
+export class CsvParseError extends Error {
+  constructor(
+    message: string,
+    /** The line, from 1, where the record that could not be read starts. */
+    readonly line: number
+  ) {
+    super(message)
+    this.name = "CsvParseError"
+  }
+}
+
+export function parseCsv(
+  text: string,
+  options: { readonly delimiter?: "," | "\t" } = {}
+): CsvTable {
+  const delimiter = options.delimiter ?? ","
+  const source = text.charCodeAt(0) === 0xfeff ? text.slice(1) : text
+  const records: string[][] = []
+  let record: string[] = []
+  let field = ""
+  // Inside a quoted field; and whether the current record had one, so `""` alone is a record.
+  let quoted = false
+  let quotedSeen = false
+  let line = 1
+  let recordLine = 1
+  let index = 0
+
+  const endField = () => {
+    record.push(field)
+    field = ""
+  }
+  const endRecord = () => {
+    endField()
+    // A line with nothing on it is not a record.
+    if (!(record.length === 1 && record[0] === "" && !quotedSeen)) records.push(record)
+    record = []
+    quotedSeen = false
+  }
+
+  while (index < source.length) {
+    const char = source[index]
+    if (quoted) {
+      if (char === '"') {
+        if (source[index + 1] === '"') {
+          field += '"'
+          index += 2
+          continue
+        }
+        quoted = false
+        index += 1
+        const next = source[index]
+        if (next !== undefined && next !== delimiter && next !== "\n" && next !== "\r") {
+          throw new CsvParseError(
+            `A quoted field on line ${line} goes on after its closing quote; quote the whole field and double the quotes inside it.`,
+            recordLine
+          )
+        }
+        continue
+      }
+      if (char === "\n" || (char === "\r" && source[index + 1] !== "\n")) line += 1
+      field += char
+      index += 1
+      continue
+    }
+    if (char === '"' && field === "") {
+      quoted = true
+      quotedSeen = true
+      index += 1
+      continue
+    }
+    if (char === delimiter) {
+      endField()
+      index += 1
+      continue
+    }
+    if (char === "\r" || char === "\n") {
+      endRecord()
+      index += char === "\r" && source[index + 1] === "\n" ? 2 : 1
+      line += 1
+      recordLine = line
+      continue
+    }
+    field += char
+    index += 1
+  }
+  if (quoted) {
+    throw new CsvParseError(
+      `A quoted field that starts on line ${recordLine} is never closed.`,
+      recordLine
+    )
+  }
+  if (field !== "" || record.length > 0 || quotedSeen) endRecord()
+
+  const [header, ...rows] = records
+  return { header: header ?? [], rows }
+}

package/src/artifacts/errors.ts

@@ -0,0 +1,21 @@
+export type ArtifactRequestErrorCode =
+  | "artifact_not_found"
+  | "artifact_kind_mismatch"
+  | "invalid_artifact"
+  | "not_allowed"
+  | "storage_unavailable"
+
+/**
+ * Error for an artifact request the caller can correct or must be told about. Callers branch on
+ * `code`; the message says what to change.
+ */
+export class ArtifactRequestError extends Error {
+  readonly name = "ArtifactRequestError"
+
+  constructor(
+    readonly code: ArtifactRequestErrorCode,
+    message: string
+  ) {
+    super(message)
+  }
+}

package/src/artifacts/execution.ts

@@ -0,0 +1,153 @@
+import { type Principal, principalsEqual, SYSTEM_PRINCIPAL } from "../auth"
+import type { BlobStorage } from "../blob-storage/types"
+import { resolveRuntimeAuthorizationForProject } from "../execution/authorization"
+import type { SixbRuntimeContext } from "../runtime/types"
+import type {
+  ArtifactFile,
+  ArtifactRecord,
+  ArtifactStorage,
+  ArtifactVersionRecord,
+  ListArtifactsResult,
+  ListArtifactVersionsResult,
+} from "../storage/artifacts/types"
+import { ArtifactRequestError } from "./errors"
+import type { ArtifactKind } from "./kinds"
+import { type PublishedArtifact, publishArtifact } from "./publish/publish"
+
+/** A version's content: what its kind renders from, and what it is called. */
+export interface ArtifactContentInput {
+  readonly kind: ArtifactKind
+  readonly title: string
+  /** Files stored with `sixb.blobs.put()` or `POST /api/files`, at their paths in the artifact. */
+  readonly files: readonly ArtifactFile[]
+}
+
+export interface ListArtifactsRuntimeInput {
+  /** Only artifacts with a version the Agent published in this thread. */
+  readonly threadId?: string
+  /** Only artifacts of this kind. */
+  readonly kind?: ArtifactKind
+  readonly limit?: number
+  readonly offset?: number
+}
+
+/**
+ * Artifacts the caller owns: create one, publish its next version, read it back. A user or service
+ * account reaches only its own artifacts; system code reaches every artifact in the project.
+ */
+export interface ArtifactsRuntime {
+  /** Creates an artifact owned by the caller, with its first version. */
+  create(input: ArtifactContentInput): Promise<PublishedArtifact>
+  /** Publishes the next version. The kind must be the artifact's. */
+  publish(artifactId: string, input: ArtifactContentInput): Promise<PublishedArtifact>
+  get(artifactId: string): Promise<ArtifactRecord | null>
+  /** Most recently updated first. */
+  list(input?: ListArtifactsRuntimeInput): Promise<ListArtifactsResult>
+  getVersion(artifactId: string, version: number | "latest"): Promise<ArtifactVersionRecord | null>
+  /** Newest first; `null` when the artifact is not the caller's. */
+  listVersions(
+    artifactId: string,
+    input?: { readonly limit?: number; readonly offset?: number }
+  ): Promise<ListArtifactVersionsResult | null>
+  /** Deletes the artifact with every version. `false` when it is not the caller's. */
+  delete(artifactId: string): Promise<boolean>
+}
+
+export function createArtifactsRuntime(
+  runtime: SixbRuntimeContext,
+  blobStorage: BlobStorage
+): ArtifactsRuntime {
+  const authority = resolveRuntimeAuthorizationForProject(runtime)
+  // Shared-link sessions and unresolved authority reach no artifact.
+  const caller: Principal | null =
+    authority.type === "principal"
+      ? authority.context.principal
+      : authority.type === "unrestricted"
+        ? SYSTEM_PRINCIPAL
+        : null
+  const ownerFilter = authority.type === "principal" ? caller : null
+
+  const requireStorage = (): ArtifactStorage => {
+    const storage = runtime.storage.artifacts
+    if (!storage) {
+      throw new ArtifactRequestError(
+        "storage_unavailable",
+        "[Sixb] Artifacts need storage that supports them."
+      )
+    }
+    return storage
+  }
+  const requireCaller = (): Principal => {
+    if (!caller) {
+      throw new ArtifactRequestError("not_allowed", "[Sixb] This caller cannot publish artifacts.")
+    }
+    return caller
+  }
+  const visible = (artifact: ArtifactRecord | null): ArtifactRecord | null =>
+    artifact && caller && (!ownerFilter || principalsEqual(ownerFilter, artifact.owner))
+      ? artifact
+      : null
+  const getVisible = async (artifactId: string): Promise<ArtifactRecord | null> =>
+    caller
+      ? visible(await requireStorage().get({ projectId: runtime.projectId, id: artifactId }))
+      : null
+
+  return {
+    async create(input) {
+      return publishArtifact(
+        { projectId: runtime.projectId, storage: requireStorage(), blobStorage },
+        { ...input, author: requireCaller() }
+      )
+    },
+
+    async publish(artifactId, input) {
+      const author = requireCaller()
+      if (!(await getVisible(artifactId))) throw notFound(artifactId)
+      return publishArtifact(
+        { projectId: runtime.projectId, storage: requireStorage(), blobStorage },
+        { ...input, artifactId, author }
+      )
+    },
+
+    get: getVisible,
+
+    async list(input = {}) {
+      if (!caller) return { artifacts: [], hasMore: false, total: 0 }
+      return requireStorage().list({
+        projectId: runtime.projectId,
+        ...(ownerFilter ? { owner: ownerFilter } : {}),
+        ...(input.threadId === undefined ? {} : { originThreadId: input.threadId }),
+        ...(input.kind === undefined ? {} : { kind: input.kind }),
+        ...(input.limit === undefined ? {} : { limit: input.limit }),
+        ...(input.offset === undefined ? {} : { offset: input.offset }),
+      })
+    },
+
+    async getVersion(artifactId, version) {
+      const artifact = await getVisible(artifactId)
+      if (!artifact) return null
+      return requireStorage().getVersion({
+        projectId: runtime.projectId,
+        artifactId,
+        version: version === "latest" ? artifact.latestVersion : version,
+      })
+    },
+
+    async listVersions(artifactId, input = {}) {
+      if (!(await getVisible(artifactId))) return null
+      return requireStorage().listVersions({ projectId: runtime.projectId, artifactId, ...input })
+    },
+
+    async delete(artifactId) {
+      if (!(await getVisible(artifactId))) return false
+      return requireStorage().delete({ projectId: runtime.projectId, id: artifactId })
+    },
+  }
+}
+
+function notFound(artifactId: string): ArtifactRequestError {
+  return new ArtifactRequestError(
+    "artifact_not_found",
+    `[Sixb] Artifact '${artifactId}' was not found.`
+  )
+}

package/src/artifacts/frames/assets.ts

@@ -0,0 +1,88 @@
+import type { ArtifactFrameTarget } from "../../storage/artifacts/types"
+import { isArtifactAddress, parseArtifactAddress } from "../address"
+import { decodeHtmlEntities } from "../html"
+import { FRAME_ASSET_PREFIX } from "../publish/validate/slides"
+import { FRAME_KIT_CSS } from "./kit"
+import { frameRuntime } from "./runtime"
+
+/**
+ * The files a frame gets besides the version's own, under `__sixb/`, which a version may not use.
+ * The server serves them to the app's frames, and the Agent's layout check serves them to its
+ * browser, so both lay a deck out the same way.
+ */
+export const FRAME_ASSETS: Readonly<
+  Record<string, { readonly body: string; readonly type: string }>
+> = {
+  [`${FRAME_ASSET_PREFIX}kit.css`]: { body: FRAME_KIT_CSS, type: "text/css; charset=utf-8" },
+  [`${FRAME_ASSET_PREFIX}runtime.js`]: {
+    body: `(${frameRuntime.toString()})()\n`,
+    type: "text/javascript; charset=utf-8",
+  },
+}
+
+const INJECTED = `<link rel="stylesheet" href="${FRAME_ASSET_PREFIX}kit.css"><script src="${FRAME_ASSET_PREFIX}runtime.js"></script>`
+
+/**
+ * A deck's entry with the kit and the runtime first in its `<head>`, before anything of its own,
+ * so the deck's styles and scripts build on them. Exactly once, whatever the markup: in `<head>`
+ * when the page has one, else first in `<html>`, else right after the doctype, so a page without
+ * either still renders in standards mode. Each element is looked for by parsing, not by matching
+ * text, so a `<head>` inside a comment or a script's string is not one.
+ */
+export function injectFrameAssets(html: string): string {
+  for (const selector of ["head", "html"]) {
+    let injected = false
+    const rewritten = new HTMLRewriter()
+      .on(selector, {
+        element(element) {
+          if (injected) return
+          injected = true
+          element.prepend(INJECTED, { html: true })
+        },
+      })
+      .transform(html)
+    if (injected) return rewritten
+  }
+  const doctype = /^\s*<!doctype[^>]*>/i.exec(html)?.[0] ?? ""
+  return `${doctype}${INJECTED}${html.slice(doctype.length)}`
+}
+
+/** Where a frame serves a file another artifact lends it: `__sixb/ref/<id>@<version>/<path>`. */
+export const FRAME_REFERENCE_PREFIX = `${FRAME_ASSET_PREFIX}ref/`
+
+/** The path, under a frame's base, of a file one of its targets lends it. */
+function frameReferencePath(target: ArtifactFrameTarget): string | null {
+  const file = parseArtifactAddress(target.address)?.path
+  if (!file) return null
+  const path = file.split("/").map(encodeURIComponent).join("/")
+  return `${FRAME_REFERENCE_PREFIX}${target.artifactId}@${target.version}/${path}`
+}
+
+/**
+ * Points each image a deck shows from another artifact (`<img src="artifact:…">`) at the copy its
+ * frame serves, marked `data-sixb-ref`. An image its reader cannot see, or that the frame has
+ * no target for, loses its source and is marked unavailable: the kit draws it as an empty box.
+ * Addresses are compared as publishing recorded them, with their entities decoded.
+ */
+export function rewriteFrameReferences(
+  html: string,
+  targets: readonly ArtifactFrameTarget[]
+): string {
+  return new HTMLRewriter()
+    .on("img[src]", {
+      element(element) {
+        const source = decodeHtmlEntities(element.getAttribute("src") ?? "").trim()
+        if (!isArtifactAddress(source)) return
+        const target = targets.find((candidate) => candidate.address === source)
+        const path = target ? frameReferencePath(target) : null
+        if (path) {
+          element.setAttribute("src", path)
+          element.setAttribute("data-sixb-ref", "")
+        } else {
+          element.removeAttribute("src")
+          element.setAttribute("data-sixb-ref", "unavailable")
+        }
+      },
+    })
+    .transform(html)
+}

package/src/artifacts/frames/grants.ts

@@ -0,0 +1,124 @@
+import { createHash, randomBytes } from "node:crypto"
+import type {
+  ArtifactFrameTarget,
+  ArtifactStorage,
+  ArtifactVersionRecord,
+} from "../../storage/artifacts/types"
+import { parseArtifactAddress } from "../address"
+import { ArtifactRequestError } from "../errors"
+
+/** Path prefix of the route that serves a version's files to its frame. */
+export const ARTIFACT_FRAME_ROUTE_PREFIX = "/api/artifact-frames/"
+
+/** A frame link lasts an hour; the app asks for a new one before it runs out. */
+const FRAME_LIFETIME_MS = 60 * 60 * 1000
+/** 32 random bytes in base64url. */
+const TOKEN_PATTERN = /^[A-Za-z0-9_-]{43}$/
+
+export interface ArtifactFrame {
+  /** The frame's base, ending in `/`: the version's files are served under it by their paths. */
+  readonly path: string
+  readonly expiresAt: Date
+}
+
+type ReadArtifactVersion = (
+  artifactId: string,
+  version: number | "latest"
+) => Promise<ArtifactVersionRecord | null>
+
+/**
+ * Issues a link that serves a deck's version to a sandboxed frame, with the files it embeds from
+ * other artifacts that `read` finds. The token in the link is the credential: only its hash is
+ * stored. Whoever asks must already have been allowed to read the version, and `read` reads as
+ * them. Only a deck opens in a frame, since the frame serves its entry as a page.
+ */
+export async function createArtifactFrame(input: {
+  readonly projectId: string
+  readonly storage: ArtifactStorage
+  readonly version: ArtifactVersionRecord
+  readonly read?: ReadArtifactVersion
+  readonly now?: Date
+}): Promise<ArtifactFrame> {
+  const { version } = input
+  if (version.outline.kind !== "slides") {
+    throw new ArtifactRequestError(
+      "artifact_kind_mismatch",
+      `[Sixb] Only a deck opens in a frame; '${version.artifactId}' is a ${version.outline.kind}. Read its files instead.`
+    )
+  }
+  const createdAt = input.now ?? new Date()
+  const expiresAt = new Date(createdAt.getTime() + FRAME_LIFETIME_MS)
+  const token = randomBytes(32).toString("base64url")
+  await input.storage.createFrameGrant({
+    projectId: input.projectId,
+    tokenHash: hashToken(token),
+    artifactId: version.artifactId,
+    version: version.version,
+    targets: input.read ? await frameTargets(version, input.read) : [],
+    createdAt,
+    expiresAt,
+  })
+  return { path: `${ARTIFACT_FRAME_ROUTE_PREFIX}${token}/`, expiresAt }
+}
+
+/**
+ * The files from other artifacts a version's frame may show its reader: each file it embeds
+ * (`<img src="artifact:…/figure.svg">`) that `read`, as the reader, finds, at the version the
+ * address pins or the latest. A chart, range, or section is drawn by the app over the frame, under
+ * the reader's own session, and needs nothing here.
+ */
+async function frameTargets(
+  version: ArtifactVersionRecord,
+  read: ReadArtifactVersion
+): Promise<ArtifactFrameTarget[]> {
+  const targets: ArtifactFrameTarget[] = []
+  for (const reference of version.references) {
+    if (
+      reference.as !== "embed" ||
+      targets.some((target) => target.address === reference.address)
+    ) {
+      continue
+    }
+    const address = parseArtifactAddress(reference.address)
+    if (!address?.path) continue
+    const target = await read(address.artifactId, address.version ?? "latest").catch(() => null)
+    if (!target?.files.some((file) => file.path === address.path)) continue
+    targets.push({
+      address: reference.address,
+      artifactId: target.artifactId,
+      version: target.version,
+    })
+  }
+  return targets
+}
+
+/**
+ * What a frame link serves: its deck's version, and what it may show from other artifacts; `null`
+ * once the link is unknown, expired, or its version gone, and for a version that is not a deck.
+ */
+export async function resolveArtifactFrame(input: {
+  readonly projectId: string
+  readonly storage: ArtifactStorage
+  readonly token: string
+  readonly now?: Date
+}): Promise<{
+  readonly version: ArtifactVersionRecord
+  readonly targets: readonly ArtifactFrameTarget[]
+} | null> {
+  if (!TOKEN_PATTERN.test(input.token)) return null
+  const grant = await input.storage.findFrameGrant({
+    projectId: input.projectId,
+    tokenHash: hashToken(input.token),
+  })
+  if (!grant || grant.expiresAt <= (input.now ?? new Date())) return null
+  const version = await input.storage.getVersion({
+    projectId: input.projectId,
+    artifactId: grant.artifactId,
+    version: grant.version,
+  })
+  return version?.outline.kind === "slides" ? { version, targets: grant.targets } : null
+}
+
+function hashToken(token: string): string {
+  return createHash("sha256").update(token).digest("hex")
+}

package/src/artifacts/frames/index.ts

@@ -0,0 +1,15 @@
+/**
+ * Frames for this repo's packages: the server issues and serves them, with the kit and runtime,
+ * and the Agent's layout check lays a deck out in them.
+ */
+
+export { SLIDES_ENTRY } from "../publish/validate/slides"
+export {
+  FRAME_ASSETS,
+  FRAME_REFERENCE_PREFIX,
+  injectFrameAssets,
+  rewriteFrameReferences,
+} from "./assets"
+export { ARTIFACT_FRAME_ROUTE_PREFIX, createArtifactFrame, resolveArtifactFrame } from "./grants"
+export { FRAME_DEFAULT_THEMES } from "./kit"
+export { type LayoutProblem, layoutProbe } from "./probe"