@pathmx/core 0.5.0

package/plugins/types.ts

@@ -0,0 +1,538 @@
+import type { ReadAccess, SourceCapability } from "../authority/access.ts"
+import type { GraphEdge } from "../graph.ts"
+import type { Html } from "../html.ts"
+import type { RouteInvalidation } from "../invalidation.ts"
+import type { CommitResult } from "../repository.ts"
+import type { RuntimeProfile } from "../runtime-profile.ts"
+import type { Source, SourceBlock, SourceNode } from "../source/index.ts"
+import type {
+  Actor,
+  ActorProfile,
+  CredentialSession,
+  Principal,
+} from "../authority/model.ts"
+import type { Dependency, DependencyContext } from "../dependencies.ts"
+import type { PathMXDataSchema, StandardSchemaV1 } from "../schema/standard.ts"
+import type { CredentialHost } from "../authority/credentials.ts"
+import type { SourceTransaction } from "../actions/transaction.ts"
+import type { View } from "../view/model.ts"
+import type { AgentAdmission, AgentJob } from "../authority/agents.ts"
+import type { Log } from "../log.ts"
+import type { PluginDatabase, SqlDatabase } from "../database.ts"
+import type { Command } from "commander"
+import type { ApplicationSchema, SchemaContribution } from "../schema/model.ts"
+import type { PatternInstaller } from "../pattern.ts"
+import type {
+  HtmlElement,
+  HtmlStringRewrite,
+  PathMXYaml,
+} from "../environment.ts"
+import type { PreparedQueryPlan } from "../query/kernel.ts"
+import type { QueryRequest } from "../query/model.ts"
+
+export type { Actor, Source }
+export type { Dependency, DependencyContext }
+
+export type Awaitable<T> = T | Promise<T>
+
+export type CompileContext = DependencyContext & {
+  source: Source
+  block?: SourceBlock
+  /** Compiler-owned placement of this content in the rendered document. */
+  scope: "page" | "embedded"
+  slots: string[]
+  /** Authored element names found once for the owning Source. */
+  elements: ReadonlySet<string>
+}
+
+export type DocumentStylesheet =
+  | Readonly<{ type: "stylesheet"; href: string; media?: string }>
+  | Readonly<{
+      type: "stylesheet"
+      name: string
+      text: string
+      media?: string
+    }>
+
+export type DocumentStyle = Readonly<{
+  type: "style"
+  text: string
+}>
+
+export type DocumentPreload = Readonly<{
+  type: "preload"
+  href: string
+  as: string
+  contentType?: string
+  crossorigin?: boolean
+}>
+
+export type DocumentScript =
+  | Readonly<{ type: "script"; href: string; module?: boolean }>
+  | Readonly<{ type: "script"; source: string; module?: boolean }>
+  | Readonly<{ type: "script"; text: string; module?: boolean }>
+  | Readonly<{ type: "script"; name: string; text: string; module?: boolean }>
+
+export type DocumentTitle = Readonly<{ type: "title"; text: string }>
+
+/** `attrs` render verbatim: `{ charset }`, `{ name, content }`, `{ name, media, content }`. */
+export type DocumentMeta = Readonly<{
+  type: "meta"
+  attrs: Readonly<Record<string, string>>
+}>
+
+/** Linked hrefs may be internal (`/app.js`) or external (`https://…`). */
+export type DocumentAsset =
+  | DocumentStylesheet
+  | DocumentStyle
+  | DocumentPreload
+  | DocumentScript
+  | DocumentTitle
+  | DocumentMeta
+
+export type AssetContext = {
+  addAsset(...assets: DocumentAsset[]): void
+  /** Bundle one browser entrypoint and atomically contribute its JS/CSS outputs. */
+  addBrowserBundle(entrypoint: string | URL, name: string): Promise<void>
+}
+
+export type PageContext = DependencyContext &
+  AssetContext & {
+    source: Source
+  }
+
+export type SourceTransition = Readonly<{
+  before?: Source
+  after?: Source
+}>
+
+export type PluginInvalidationTarget =
+  | Readonly<{
+      type: "route"
+      route: string
+      actors?: Iterable<string>
+    }>
+  | Readonly<{
+      type: "actor"
+      actors: Iterable<string>
+    }>
+
+export type PluginInvalidation = Readonly<{
+  /** Cached pages whose compiled output or dependency records are stale. */
+  dependencies?: Iterable<Dependency>
+  sourceIds?: Iterable<string>
+  /** Connected routes that must reconcile without implying a rebuild. */
+  targets?: Iterable<PluginInvalidationTarget>
+}>
+
+export type CompiledPage = Readonly<{
+  html: string
+  assets: readonly DocumentAsset[]
+  sourceId: string
+  route: string
+}>
+
+export type DocumentAssetContext = AssetContext & {
+  page?: CompiledPage
+}
+
+export type ViewContext = Readonly<{
+  view: View
+  session: CredentialSession
+  /** @deprecated Prefer `view.principal`; retained during the View migration. */
+  principal: Principal
+  /** @deprecated Internal render Source; migrate safe reads to `view`. */
+  source: Source
+  route: string
+  /** Database isolated to the View Component's owning plugin. */
+  database?: SqlDatabase
+}>
+
+type ViewComponentUseBase = Readonly<{
+  props: Readonly<Record<string, string>>
+  origin: Source
+}>
+
+export type ViewComponentUse<Data = undefined> = ViewComponentUseBase &
+  ([Data] extends [undefined]
+    ? Readonly<{ data?: undefined }>
+    : Readonly<{ data: Data }>)
+
+export type ViewComponent<
+  Compiled = undefined,
+  DataSchema extends PathMXDataSchema | undefined = undefined,
+> = Readonly<{
+  /** Internal `plugin:name` identity; authored Sources use the generated `x-plugin-name` tag. */
+  tag: string
+  /** Browser entrypoint bundled only on pages that author this component. */
+  client?: string | URL
+  /** Validate authored element attributes before exposing the raw props. */
+  props?: StandardSchemaV1
+  /** Validate one structured record supplied by a data-aware renderer. */
+  data?: DataSchema
+  compile?(
+    use: ViewComponentUse,
+    ctx: PageContext,
+    app: AppContext,
+  ): Awaitable<Compiled>
+  render(
+    use: ViewComponentUse<
+      DataSchema extends PathMXDataSchema
+        ? StandardSchemaV1.InferOutput<DataSchema>
+        : undefined
+    >,
+    compiled: Compiled,
+    ctx: ViewContext,
+    app: AppContext,
+  ): Awaitable<Html>
+}>
+
+/** Type-erased storage boundary; use defineViewComponent for authored inference. */
+export type AnyViewComponent = Readonly<{
+  tag: string
+  client?: string | URL
+  props?: StandardSchemaV1
+  data?: PathMXDataSchema
+  compile?: (...args: any[]) => Awaitable<unknown>
+  render: (...args: any[]) => Awaitable<Html>
+}>
+
+/** @internal Runtime-authored component definition used by Literate Components. */
+export type AuthoredDataComponent = Readonly<{
+  tag: string
+  available(origin: Source): boolean
+  compile?(
+    origin: Source,
+    ctx: PageContext,
+    app: AppContext,
+  ): Awaitable<unknown>
+  render(
+    use: ViewComponentUse<unknown>,
+    compiled: unknown,
+    ctx: ViewContext,
+    app: AppContext,
+  ): Awaitable<Html>
+}>
+
+export type ViewVariableUse = Readonly<{
+  path: readonly string[]
+  origin: Source
+}>
+
+export type ViewVariableValue = string | number | boolean | null | undefined
+
+export type ViewVariable = Readonly<{
+  namespace: string
+  render(
+    use: ViewVariableUse,
+    ctx: ViewContext,
+    app: AppContext,
+  ): Awaitable<ViewVariableValue>
+}>
+
+export type ServerGraph = Readonly<{
+  linksFrom(path: string): readonly GraphEdge[]
+  linksTo(path: string): readonly GraphEdge[]
+  neighbors(path: string): readonly SourceNode[]
+  backlinks(path: string): readonly SourceNode[]
+}>
+
+export type ServerRenderOptions = Readonly<{
+  status?: number
+  headers?: HeadersInit
+}>
+
+export type PluginLog = Readonly<Pick<Log, "debug" | "info" | "warn" | "error">>
+
+export type PluginContext = Readonly<{
+  plugin: string
+  log: PluginLog
+  runtime: RuntimeProfile
+  database?: SqlDatabase
+}>
+
+type AppSources = Readonly<{
+  /** Resolve a Source id, exact Source path, or public route. */
+  get(idOrPath: string): Source | undefined
+  all(): readonly Source[]
+  /** Resolve only a public page route. */
+  resolve(pathname: string): Source | undefined
+  /** Normalize a repository-relative value to an absolute graph path. */
+  path(value: string): string
+  isPage(source: Source): boolean
+  builtPages(): readonly CompiledPage[]
+}>
+
+type AppActors = Readonly<{
+  profile(actorId: string): ActorProfile | undefined
+  homeActorId(path: string): string | undefined
+}>
+
+type AppAccess = Readonly<{
+  read(principal: Principal, target: Source | string): ReadAccess
+  can(
+    principal: Principal,
+    target: Source | string,
+    capability: SourceCapability,
+  ): boolean
+  canEmbed(container: string, dependency: string): boolean
+}>
+
+type AppAssets = Readonly<{
+  load(url: URL): Awaitable<Blob>
+  publish(name: string, blob: Blob, contentType?: string): Promise<string>
+}>
+
+type AppHtml = Readonly<{
+  rewrite: HtmlStringRewrite
+}>
+
+type AppCompiler = Readonly<{
+  block(
+    source: Source,
+    block: SourceBlock,
+    dependencies?: DependencyContext,
+    options?: { id?: string },
+  ): Promise<string>
+  /** Compile another Source as a document while excluding the calling Plugin. */
+  document(
+    source: Source,
+    dependencies: DependencyContext,
+  ): Promise<Readonly<{ html: string; assets: readonly DocumentAsset[] }>>
+}>
+
+type AppComponents = Readonly<{
+  claim(sourcePath: string, tags: Iterable<string>): void
+  release(sourcePath: string): void
+  has(tag: string): boolean
+  /** @internal Replace runtime-authored structured-data component definitions. */
+  replaceData(
+    sourcePath: string,
+    components: Iterable<AuthoredDataComponent>,
+  ): void
+  /** @internal Prepare one structured-data component once during page compile. */
+  prepareData(
+    tag: string,
+    props: Readonly<Record<string, string>>,
+    origin: Source,
+    ctx: PageContext,
+  ): Promise<unknown>
+  /** @internal Render one validated record through a prepared component. */
+  renderData(prepared: unknown, data: unknown, ctx: ViewContext): Promise<Html>
+}>
+
+type AppDiagnostics = Readonly<{
+  /** Stop indexing one invalid Source with a lint-collectable Plugin issue. */
+  invalid(source: Source, message: string): never
+}>
+
+type AppQuery = Readonly<{
+  /** @internal Normalize, validate, and track a compile-time query plan. */
+  prepare(
+    query: string,
+    request?: QueryRequest<unknown>,
+  ): Promise<PreparedQueryPlan>
+}>
+
+/** Request-independent capabilities available to Plugin hooks and components. */
+export type AppContext = PluginContext &
+  Readonly<{
+    schema: ApplicationSchema
+    query: AppQuery
+    yaml: PathMXYaml
+    sources: AppSources
+    graph: ServerGraph
+    actors: AppActors
+    access: AppAccess
+    assets: AppAssets
+    html: AppHtml
+    compile: AppCompiler
+    components: AppComponents
+    diagnostics: AppDiagnostics
+  }>
+
+export type PluginCommandContext = Readonly<{
+  plugin: string
+  pathsRoot: string
+  /** Explicit CLI Action root, when it differs from the project convention. */
+  actionsRoot?: string
+  projectRoot: string
+  stateRoot: string
+  log: PluginLog
+  database?: SqlDatabase
+  /** Plan and install user-owned project files through the portable Pattern boundary. */
+  patterns: PatternInstaller
+}>
+
+export type PublishContext = Readonly<{
+  /** Add one finite public GET pathname to the static publication. */
+  route(pathname: string): void
+  /** Reject publication when an authored use has no static representation. */
+  unsupported(source: Source, message: string): void
+}>
+
+export type ServerContext = Readonly<{
+  request: Request
+  url: URL
+  /** Route path relative to the owning plugin's `/api/<plugin-id>/` mount. */
+  path: string
+  plugin: string
+  /** Structured logger whose messages are prefixed with the owning Plugin id. */
+  log: PluginLog
+  runtime: RuntimeProfile
+  /** Database isolated to the route's owning plugin. */
+  database?: SqlDatabase
+  graph: ServerGraph
+  source(idOrPath: string): Source | undefined
+  sources(): readonly Source[]
+  resolve(pathname: string): Source | undefined
+  isPublic(source: Source | string): boolean
+  session(): Promise<CredentialSession>
+  /** Return the memoized viewer-filtered Source and graph projection. */
+  view(): Promise<View>
+  readAccess(source: Source | string): Promise<ReadAccess>
+  onSync(listener: (event: RouteInvalidation) => void): () => void
+  render(
+    source: Source | string,
+    options?: ServerRenderOptions,
+  ): Promise<Response>
+  mutate(
+    run: (transaction: SourceTransaction) => Awaitable<void>,
+  ): Promise<CommitResult>
+  /** Commit one idempotent, target-only mutation under an admitted Agent Actor. */
+  mutateAsAgent(admission: AgentAdmission, run: AgentJob): Promise<CommitResult>
+  /** Delegate an auth URL to the CredentialHost owned by the auth plugin. */
+  handleCredentials(): Promise<Response>
+}>
+
+export type ServerRouteHandler = (ctx: ServerContext) => Awaitable<Response>
+
+export type ServerRoute = Readonly<{
+  method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "OPTIONS" | "*"
+  path: string
+  handle: ServerRouteHandler
+}>
+
+export type StreamHandler = {
+  element(el: HtmlElement): void
+}
+
+const PLUGIN_ID = /^[a-z0-9]+(?:-[a-z0-9]+)*$/
+
+export function canonicalPluginId(id: string) {
+  if (!PLUGIN_ID.test(id)) throw new Error(`Invalid plugin id: ${id}`)
+  return id
+}
+
+/** Optional lifecycle hooks. Implement any subset. */
+export type Plugin = {
+  /** Stable build-plugin identity used for diagnostics and composition. */
+  id: string
+  /** Earlier-installed Plugin ids this Plugin cannot operate without. */
+  requires?: readonly string[]
+  /** Discoverable Source, Block, prop, query, and Action declarations. */
+  schema?: SchemaContribution
+  /** Optional isolated SQL state owned and migrated by this plugin. */
+  database?: PluginDatabase
+  /** Trusted local administrator commands mounted below `pmx <plugin-id>`. */
+  commands?(group: Command, ctx: PluginCommandContext): void
+  /** Optional request-admission provider owned by this plugin. */
+  credentials?: CredentialHost
+  /** Portable HTTP handlers. Routes run before credential resolution. */
+  routes?: readonly ServerRoute[]
+  /** Viewer-aware leaf components authored through this plugin's namespace. */
+  components?: readonly AnyViewComponent[]
+  /** Escaped scalar namespaces resolved while rendering an admitted view. */
+  variables?: readonly ViewVariable[]
+  /** Perf/diagnostic label; defaults to the factory function's name. */
+  name?: string
+  /** Initialize plugin-owned resources after registration and before indexing. */
+  setup?(ctx: PluginContext): Awaitable<void>
+  /** Release plugin-owned resources during application shutdown. */
+  close?(ctx: PluginContext): Awaitable<void>
+  /** Report Source-local repository issues when `pmx lint` explicitly runs. */
+  lint?(
+    report: (source: Source, message: string) => void,
+    app: AppContext,
+  ): Awaitable<void>
+  /** Contribute finite GET routes and static-compatibility diagnostics. */
+  publish?(ctx: PublishContext, app: AppContext): Awaitable<void>
+  /** Inspect or enrich a source when it is added to the index. */
+  index?(source: Source, app: AppContext): void
+  /** Remove plugin state associated with a source before reindexing or deletion. */
+  unindex?(sourcePath: string, app: AppContext): void
+  /** Transform interpolated Markdown before it is rendered to HTML. */
+  precompile?(
+    markdown: string,
+    ctx: CompileContext,
+    app: AppContext,
+  ): Awaitable<string>
+  /** Transform HTML immediately after rendering a source or block. */
+  postcompile?(
+    html: string,
+    ctx: CompileContext,
+    app: AppContext,
+  ): Awaitable<string>
+  /** Transform an assembled page and collect its page-specific assets. */
+  page?(html: string, ctx: PageContext, app: AppContext): Awaitable<string>
+  /** Describe pages affected by plugin-owned state after a Source transition. */
+  invalidate?(
+    transition: SourceTransition,
+    app: AppContext,
+  ): PluginInvalidation | undefined
+  /** Collect document-level assets, optionally using the compiled page. */
+  documentAssets?(ctx: DocumentAssetContext, app: AppContext): Awaitable<void>
+  /** Register selector handlers for streaming transformations of final HTML. */
+  streamSelectors?(
+    ctx: ViewContext,
+    app: AppContext,
+  ): Record<string, StreamHandler>
+}
+
+/** Create a per-Engine plugin instance. Stateful plugins keep data in the closure. */
+export type PluginFactory = () => Plugin
+
+/** Preserve inference for repository-authored build plugins. */
+export function definePlugin<const Definition extends Plugin>(
+  definition: Definition,
+) {
+  return definition
+}
+
+/** Preserve compile-result inference for a viewer-aware component. */
+export function defineViewComponent<
+  Compiled,
+  DataSchema extends PathMXDataSchema | undefined = undefined,
+>(view: ViewComponent<Compiled, DataSchema>) {
+  return view
+}
+
+/** Define one actor-aware scalar namespace rendered through opaque view slots. */
+export function defineViewVariable(variable: ViewVariable) {
+  return variable
+}
+
+function serverRoute(
+  method: ServerRoute["method"],
+  path: string,
+  handle: ServerRouteHandler,
+): ServerRoute {
+  return { method, path, handle }
+}
+
+function methodRoute(method: Exclude<ServerRoute["method"], "*">) {
+  return (path: string, handle: ServerRouteHandler) =>
+    serverRoute(method, path, handle)
+}
+
+/** Define relative routes mounted below `/api/<plugin-id>/`. */
+export const route = Object.freeze({
+  get: methodRoute("GET"),
+  post: methodRoute("POST"),
+  put: methodRoute("PUT"),
+  patch: methodRoute("PATCH"),
+  delete: methodRoute("DELETE"),
+  options: methodRoute("OPTIONS"),
+  all: (path: string, handle: ServerRouteHandler) =>
+    serverRoute("*", path, handle),
+})

package/problem.ts

@@ -0,0 +1,41 @@
+export type ProblemDetails = {
+  type: "about:blank"
+  title: string
+  status: number
+  detail: string
+}
+
+export function actionProblem(
+  req: Request,
+  status: 400 | 403 | 404,
+  detail: string,
+) {
+  if (!req.headers.get("accept")?.includes("application/problem+json")) {
+    return new Response(detail, {
+      status,
+      headers: {
+        "Content-Type": "text/plain; charset=utf-8",
+        Vary: "Accept",
+      },
+    })
+  }
+
+  const problem: ProblemDetails = {
+    type: "about:blank",
+    title:
+      status === 404
+        ? "Not Found"
+        : status === 403
+          ? "Forbidden"
+          : "Bad Request",
+    status,
+    detail,
+  }
+  return new Response(JSON.stringify(problem), {
+    status,
+    headers: {
+      "Content-Type": "application/problem+json",
+      Vary: "Accept",
+    },
+  })
+}

package/project.ts

@@ -0,0 +1,6 @@
+/** Resolve a conventional project directory beside the authored `paths/` root. */
+export function projectDirectory(pathsRoot: string, name: string) {
+  const root = pathsRoot.replaceAll("\\", "/").replace(/\/+$/, "")
+  const slash = root.lastIndexOf("/")
+  return `${slash === -1 ? "" : root.slice(0, slash + 1)}${name}`
+}