@sixb/core 0.1.20 → 0.1.21

package/src/artifacts/publish/index.ts

@@ -0,0 +1,12 @@
+/** Publishing for this repo's packages: the Agent publishes through the same checks as the API. */
+
+export { isArtifactId } from "../ids"
+export { ARTIFACT_LIMITS } from "../limits"
+export {
+  artifactVersionWarnings,
+  type PreparedArtifactVersion,
+  type PublishArtifactInput,
+  prepareArtifactVersion,
+  publishArtifact,
+  storeArtifactVersion,
+} from "./publish"

package/src/artifacts/publish/publish.ts

@@ -0,0 +1,250 @@
+import type { Principal } from "../../auth"
+import { ArtifactStorageError } from "../../storage/artifacts/errors"
+import type {
+  ArtifactFile,
+  ArtifactOrigin,
+  ArtifactRecord,
+  ArtifactStorage,
+  ArtifactVersionInput,
+  ArtifactVersionRecord,
+  PublishedArtifactVersion,
+} from "../../storage/artifacts/types"
+import { ArtifactRequestError } from "../errors"
+import { createArtifactId } from "../ids"
+import type { ArtifactKind } from "../kinds"
+import { ARTIFACT_LIMITS } from "../limits"
+import type { ArtifactOutline } from "../outline"
+import { ARTIFACT_THEME_FILE, parseArtifactTheme } from "../theme"
+import type { ArtifactWarning } from "../warnings"
+import {
+  type ArtifactBlobStorage,
+  checkArtifactFiles,
+  invalidArtifact,
+  readArtifactText,
+} from "./files"
+import { brokenDependents, type FoundReference, resolveReferences } from "./references"
+import { validateDocument } from "./validate/document"
+import { validateFileArtifact } from "./validate/file"
+import { validateSheet } from "./validate/sheet"
+import { validateSlides } from "./validate/slides"
+
+export interface PublishArtifactContext {
+  readonly projectId: string
+  readonly storage: ArtifactStorage
+  readonly blobStorage: ArtifactBlobStorage
+}
+
+export interface PublishArtifactInput {
+  /** Publishes the next version of this artifact; without it, a new artifact is created. */
+  readonly artifactId?: string
+  readonly kind: ArtifactKind
+  readonly title: string
+  readonly files: readonly ArtifactFile[]
+  /** Publishes the version, and owns the artifact when this creates it. */
+  readonly author: Principal
+  readonly origin?: ArtifactOrigin
+}
+
+export interface PublishedArtifact {
+  readonly artifact: ArtifactRecord
+  readonly version: ArtifactVersionRecord
+  readonly warnings: readonly ArtifactWarning[]
+}
+
+const CREATE_ATTEMPTS = 3
+
+/** A version checked against its kind and with its addresses resolved, ready to store. */
+export interface PreparedArtifactVersion {
+  readonly artifactId?: string
+  readonly kind: ArtifactKind
+  readonly author: Principal
+  readonly version: ArtifactVersionInput
+}
+
+/**
+ * Validates a version against its kind and stores it. Who may publish is the caller's decision:
+ * this checks only what the version holds.
+ */
+export async function publishArtifact(
+  context: PublishArtifactContext,
+  input: PublishArtifactInput
+): Promise<PublishedArtifact> {
+  const prepared = await prepareArtifactVersion(context, input)
+  const stored = await storeArtifactVersion(context, prepared)
+  return { ...stored, warnings: await artifactVersionWarnings(context, prepared, stored) }
+}
+
+/**
+ * Everything publishing checks before it stores: the title, the files, the theme, the kind's own
+ * format, and every address, resolved against what the author can read. It reads the files back
+ * and parses them, so a caller that stores inside a transaction prepares outside it.
+ */
+export async function prepareArtifactVersion(
+  context: PublishArtifactContext,
+  input: PublishArtifactInput
+): Promise<PreparedArtifactVersion> {
+  const title = checkTitle(input.title)
+  await checkArtifactFiles(context.blobStorage, input.files)
+  if (input.kind !== "file") await checkTheme(context.blobStorage, input.files)
+  const validated = await validateKind(context.blobStorage, input.kind, input.files)
+  const references = await resolveReferences(
+    referenceContext(context, input),
+    validated.references ?? []
+  )
+  return {
+    ...(input.artifactId ? { artifactId: input.artifactId } : {}),
+    kind: input.kind,
+    author: input.author,
+    version: {
+      title,
+      entry: validated.entry,
+      files: input.files.map(({ path, file }) => ({ path, file: { ...file } })),
+      outline: validated.outline,
+      references,
+      author: input.author,
+      ...(input.origin ? { origin: input.origin } : {}),
+      createdAt: new Date(),
+    },
+  }
+}
+
+/** Stores a prepared version: the next one of its artifact, or the first of a new one. */
+export async function storeArtifactVersion(
+  context: PublishArtifactContext,
+  prepared: PreparedArtifactVersion
+): Promise<PublishedArtifactVersion> {
+  return prepared.artifactId
+    ? publishVersion(context, prepared.artifactId, prepared.kind, prepared.version)
+    : createArtifact(context, prepared.kind, prepared.author, prepared.version)
+}
+
+/**
+ * What a stored version breaks in other artifacts that show it. A first version breaks nothing:
+ * no other artifact could name it yet. The version is stored by now, so a failed check only loses
+ * the warnings.
+ */
+export async function artifactVersionWarnings(
+  context: PublishArtifactContext,
+  prepared: PreparedArtifactVersion,
+  stored: PublishedArtifactVersion
+): Promise<readonly ArtifactWarning[]> {
+  if (!prepared.artifactId) return []
+  try {
+    return await brokenDependents(
+      referenceContext(context, prepared),
+      stored.artifact,
+      stored.version
+    )
+  } catch (error) {
+    console.warn(
+      `[Sixb] Could not check which artifacts version ${stored.version.version} of '${stored.artifact.id}' breaks:`,
+      error
+    )
+    return []
+  }
+}
+
+function referenceContext(
+  context: PublishArtifactContext,
+  input: { readonly author: Principal; readonly artifactId?: string }
+) {
+  return {
+    projectId: context.projectId,
+    storage: context.storage,
+    author: input.author,
+    ...(input.artifactId ? { artifactId: input.artifactId } : {}),
+  }
+}
+
+async function validateKind(
+  blobStorage: ArtifactBlobStorage,
+  kind: ArtifactKind,
+  files: readonly ArtifactFile[]
+): Promise<{
+  readonly entry: string
+  readonly outline: ArtifactOutline
+  readonly references?: readonly FoundReference[]
+}> {
+  switch (kind) {
+    case "document":
+      return validateDocument(blobStorage, files)
+    case "file":
+      return validateFileArtifact(files)
+    case "sheet":
+      return validateSheet(blobStorage, files)
+    case "slides":
+      return validateSlides(blobStorage, files)
+    default:
+      // A caller past the API's schema, such as a script on the SDK, can name any kind.
+      throw invalidArtifact(`'${kind satisfies never}' is not a kind of artifact.`)
+  }
+}
+
+async function checkTheme(
+  blobStorage: ArtifactBlobStorage,
+  files: readonly ArtifactFile[]
+): Promise<void> {
+  const themeFile = files.find((file) => file.path === ARTIFACT_THEME_FILE)
+  if (!themeFile) return
+  const parsed = parseArtifactTheme(
+    await readArtifactText(blobStorage, themeFile, ARTIFACT_LIMITS.maxThemeBytes)
+  )
+  if ("error" in parsed) throw invalidArtifact(parsed.error)
+}
+
+function checkTitle(value: string): string {
+  const title = typeof value === "string" ? value.trim() : ""
+  if (title.length === 0 || /[\u0000-\u001f\u007f]/.test(title)) {
+    throw invalidArtifact("An artifact needs a title of plain text.")
+  }
+  if (title.length > ARTIFACT_LIMITS.maxTitleLength) {
+    throw invalidArtifact(`A title may be at most ${ARTIFACT_LIMITS.maxTitleLength} characters.`)
+  }
+  return title
+}
+
+async function publishVersion(
+  context: PublishArtifactContext,
+  artifactId: string,
+  kind: ArtifactKind,
+  version: ArtifactVersionInput
+): Promise<PublishedArtifactVersion> {
+  try {
+    return await context.storage.publish({
+      projectId: context.projectId,
+      artifactId,
+      kind,
+      version,
+    })
+  } catch (error) {
+    if (error instanceof ArtifactStorageError && error.code === "artifact_not_found") {
+      throw new ArtifactRequestError("artifact_not_found", error.message)
+    }
+    if (error instanceof ArtifactStorageError && error.code === "artifact_kind_mismatch") {
+      throw new ArtifactRequestError("artifact_kind_mismatch", error.message)
+    }
+    throw error
+  }
+}
+
+async function createArtifact(
+  context: PublishArtifactContext,
+  kind: ArtifactKind,
+  owner: Principal,
+  version: ArtifactVersionInput
+): Promise<PublishedArtifactVersion> {
+  for (let attempt = 1; ; attempt += 1) {
+    try {
+      return await context.storage.create({
+        projectId: context.projectId,
+        id: createArtifactId(),
+        kind,
+        owner,
+        version,
+      })
+    } catch (error) {
+      const collided = error instanceof ArtifactStorageError && error.code === "artifact_exists"
+      if (!collided || attempt === CREATE_ATTEMPTS) throw error
+    }
+  }
+}

package/src/artifacts/publish/references.ts

@@ -0,0 +1,130 @@
+import { type Principal, principalsEqual } from "../../auth"
+import type {
+  ArtifactRecord,
+  ArtifactStorage,
+  ArtifactVersionRecord,
+} from "../../storage/artifacts/types"
+import { parseArtifactAddress } from "../address"
+import { ARTIFACT_LIMITS } from "../limits"
+import type { ArtifactReference } from "../references"
+import { resolveArtifactAddress } from "../resolve"
+import type { ArtifactWarning } from "../warnings"
+import { invalidArtifact } from "./files"
+
+/** An address a validator found in a version, before it is resolved. */
+export type FoundReference = Omit<ArtifactReference, "resolvedVersion">
+
+interface ReferenceContext {
+  readonly projectId: string
+  readonly storage: ArtifactStorage
+  /** Who publishes: an address resolves only to artifacts they can read. */
+  readonly author: Principal
+  /** The artifact being published, which an address may not name. */
+  readonly artifactId?: string
+}
+
+/**
+ * Resolves every address a version uses against what its author can read, recording the version
+ * each one resolved to. An address that resolves to nothing refuses the version, saying where it
+ * is and what the target has instead.
+ */
+export async function resolveReferences(
+  context: ReferenceContext,
+  found: readonly FoundReference[]
+): Promise<ArtifactReference[]> {
+  if (found.length > ARTIFACT_LIMITS.maxReferences) {
+    throw invalidArtifact(
+      `A version may refer to at most ${ARTIFACT_LIMITS.maxReferences} artifacts; this one has ${found.length} addresses.`
+    )
+  }
+  const artifacts = new Map<string, Promise<ArtifactRecord | null>>()
+  const versions = new Map<string, Promise<ArtifactVersionRecord | null>>()
+  const resolved: ArtifactReference[] = []
+  for (const reference of found) {
+    const where = reference.at
+      ? `In '${reference.at}', '${reference.address}'`
+      : `'${reference.address}'`
+    const address = parseArtifactAddress(reference.address)
+    if (!address) {
+      throw invalidArtifact(
+        `${where} is not an artifact address: write artifact:<id>[@<version>][/<file>][#<part>], such as artifact:art_k3m9q2x7tp#chart=revenue.`
+      )
+    }
+    if (address.artifactId === context.artifactId) {
+      throw invalidArtifact(
+        `${where} names the artifact being published. Link to one of its sections with #<slug> instead.`
+      )
+    }
+    let artifact = artifacts.get(address.artifactId)
+    if (!artifact) {
+      artifact = context.storage
+        .get({ projectId: context.projectId, id: address.artifactId })
+        .then((record) => (record && readable(context.author, record) ? record : null))
+      artifacts.set(address.artifactId, artifact)
+    }
+    const record = await artifact
+    if (!record) {
+      throw invalidArtifact(`${where} names no artifact you can read.`)
+    }
+    const number = address.version ?? record.latestVersion
+    const key = `${record.id}@${number}`
+    let version = versions.get(key)
+    if (!version) {
+      version = context.storage.getVersion({
+        projectId: context.projectId,
+        artifactId: record.id,
+        version: number,
+      })
+      versions.set(key, version)
+    }
+    const target = await version
+    if (!target) throw invalidArtifact(`${where}: “${record.title}” has no version ${number}.`)
+    const result = resolveArtifactAddress(address, { kind: record.kind, ...target })
+    if ("problem" in result) {
+      throw invalidArtifact(`${where}: “${target.title}” ${result.problem}.`)
+    }
+    resolved.push({ ...reference, resolvedVersion: target.version })
+  }
+  return resolved
+}
+
+/**
+ * The artifacts a new version breaks: each one whose latest version follows this artifact's latest
+ * and names something this version no longer has. Only artifacts the author can read are named.
+ */
+export async function brokenDependents(
+  context: ReferenceContext,
+  artifact: ArtifactRecord,
+  version: ArtifactVersionRecord
+): Promise<ArtifactWarning[]> {
+  const dependents = await context.storage.listReferencingVersions({
+    projectId: context.projectId,
+    artifactId: artifact.id,
+  })
+  const warnings: ArtifactWarning[] = []
+  for (const dependent of dependents) {
+    if (dependent.artifactId === artifact.id) continue
+    const owner = await context.storage.get({
+      projectId: context.projectId,
+      id: dependent.artifactId,
+    })
+    if (!owner || !readable(context.author, owner)) continue
+    for (const reference of dependent.references) {
+      const address = parseArtifactAddress(reference.address)
+      // A pinned address keeps showing the version it names.
+      if (address?.artifactId !== artifact.id || address.version !== undefined) continue
+      const result = resolveArtifactAddress(address, { kind: artifact.kind, ...version })
+      if (!("problem" in result)) continue
+      warnings.push({
+        code: "reference_broken",
+        message: `“${dependent.title}” (${dependent.artifactId}) ${reference.as === "embed" ? "shows" : "links to"} ${reference.address}, but version ${version.version} ${result.problem}. Publish its next version with an address that resolves, or restore what it names.`,
+      })
+    }
+  }
+  return warnings
+}
+
+/** Owner-only, as reading is: system code reads every artifact in the project. */
+function readable(reader: Principal, artifact: ArtifactRecord): boolean {
+  return reader.type === "system" || principalsEqual(reader, artifact.owner)
+}

package/src/artifacts/publish/validate/document.ts

@@ -0,0 +1,114 @@
+import { posix } from "node:path"
+import type { ArtifactFile } from "../../../storage/artifacts/types"
+import { isArtifactAddress } from "../../address"
+import { decodeHtmlEntities } from "../../html"
+import { ARTIFACT_LIMITS } from "../../limits"
+import { createHeadingSlugger, type DocumentHeading, type DocumentOutline } from "../../outline"
+import { type ArtifactBlobStorage, invalidArtifact, readArtifactText } from "../files"
+import type { FoundReference } from "../references"
+
+/** The file a document renders from. */
+export const DOCUMENT_ENTRY = "document.md"
+
+/**
+ * Reads a document's Markdown: its headings become the outline, and every image must be a file in
+ * the version or an `artifact:` address, so the document renders the same wherever it is opened.
+ * The addresses it shows and links to are returned with the section each sits in, to resolve.
+ */
+export async function validateDocument(
+  blobStorage: ArtifactBlobStorage,
+  files: readonly ArtifactFile[]
+): Promise<{
+  readonly entry: string
+  readonly outline: DocumentOutline
+  readonly references: readonly FoundReference[]
+}> {
+  const entry = files.find((file) => file.path === DOCUMENT_ENTRY)
+  if (!entry) throw invalidArtifact(`A document needs its Markdown in '${DOCUMENT_ENTRY}'.`)
+  const markdown = await readArtifactText(blobStorage, entry, ARTIFACT_LIMITS.maxDocumentBytes)
+
+  // The same options the docs site renders with, so headings and images read the same way.
+  const html = Bun.markdown.html(markdown, {
+    tables: true,
+    strikethrough: true,
+    tasklists: true,
+    autolinks: true,
+  })
+  const headings: { depth: number; text: string }[] = []
+  const images: string[] = []
+  // Each address with the index of the heading it follows, -1 before the first.
+  const addresses: { address: string; as: "embed" | "link"; heading: number }[] = []
+  let heading: { depth: number; text: string } | null = null
+  new HTMLRewriter()
+    .on("h1, h2, h3, h4, h5, h6", {
+      element(element) {
+        heading = { depth: Number(element.tagName.slice(1)), text: "" }
+        headings.push(heading)
+        element.onEndTag(() => {
+          heading = null
+        })
+      },
+      text(chunk) {
+        if (heading) heading.text += chunk.text
+      },
+    })
+    .on("img", {
+      element(element) {
+        const source = decodeHtmlEntities(element.getAttribute("src") ?? "")
+        if (isArtifactAddress(source)) {
+          addresses.push({ address: source.trim(), as: "embed", heading: headings.length - 1 })
+        } else {
+          images.push(source)
+        }
+      },
+    })
+    .on("a", {
+      element(element) {
+        const href = decodeHtmlEntities(element.getAttribute("href") ?? "")
+        if (isArtifactAddress(href)) {
+          addresses.push({ address: href.trim(), as: "link", heading: headings.length - 1 })
+        }
+      },
+    })
+    .transform(html)
+
+  const paths = new Set(files.map((file) => file.path))
+  for (const source of images) checkImage(source, paths)
+
+  const slug = createHeadingSlugger()
+  const outlined = headings.map(({ depth, text }): DocumentHeading => {
+    const plain = decodeHtmlEntities(text).replace(/\s+/g, " ").trim()
+    return { depth, text: plain, slug: slug(plain) }
+  })
+  return {
+    entry: DOCUMENT_ENTRY,
+    outline: { kind: "document", headings: outlined },
+    references: addresses.map(({ address, as, heading: index }) => ({
+      address,
+      as,
+      at: outlined[index]?.slug ?? "",
+    })),
+  }
+}
+
+function checkImage(source: string, paths: ReadonlySet<string>): void {
+  if (source === "" || source.startsWith("//") || /^[a-z][a-z\d+.-]*:/i.test(source)) {
+    throw invalidArtifact(
+      `${DOCUMENT_ENTRY} shows the image '${source}'. Images must be files in the artifact, by their relative path, or another artifact's address, such as artifact:art_k3m9q2x7tp#chart=revenue.`
+    )
+  }
+  const path = posix.normalize(safeDecodeUri(source.split(/[?#]/)[0] ?? ""))
+  if (!paths.has(path)) {
+    throw invalidArtifact(
+      `${DOCUMENT_ENTRY} shows the image '${source}', which is not one of the artifact's files.`
+    )
+  }
+}
+
+function safeDecodeUri(value: string): string {
+  try {
+    return decodeURI(value)
+  } catch {
+    return value
+  }
+}

package/src/artifacts/publish/validate/file.ts

@@ -0,0 +1,19 @@
+import { inferFileMediaType } from "../../../blob-storage/media-type"
+import type { ArtifactFile } from "../../../storage/artifacts/types"
+import type { FileOutline } from "../../outline"
+import { invalidArtifact } from "../files"
+
+/** A file artifact is one file of any type, delivered as it is. */
+export function validateFileArtifact(files: readonly ArtifactFile[]): {
+  readonly entry: string
+  readonly outline: FileOutline
+} {
+  const [file] = files
+  if (!file || files.length > 1) {
+    throw invalidArtifact(`A file artifact holds exactly one file; this one has ${files.length}.`)
+  }
+  return {
+    entry: file.path,
+    outline: { kind: "file", mediaType: file.file.mediaType ?? inferFileMediaType(file.path) },
+  }
+}