@pathmx/core 0.5.0

package/host/create.ts

@@ -0,0 +1,66 @@
+import { Engine } from "./engine.ts"
+import { ActorDirectory, ActorDirectoryPlugin } from "../authority/actors.ts"
+import { SourceAccessIndex, SourceAccessPlugin } from "../authority/access.ts"
+import type { PathMXEnvironment } from "../environment.ts"
+import type { Log } from "../log.ts"
+import { MetaPlugin } from "../plugins/meta.ts"
+import { SchemaPlugin } from "../plugins/schema.ts"
+import {
+  expandPluginContributions,
+  type PluginContribution,
+} from "../plugins/preset.ts"
+import { Repository } from "../repository.ts"
+import type { RuntimeProfileOptions } from "../runtime-profile.ts"
+import type { SourceDiagnosticMode } from "../source-diagnostic.ts"
+import { projectDirectory } from "../project.ts"
+
+export type CreateAppOptions = {
+  root: string
+  environment: PathMXEnvironment
+  actionsRoot?: string
+  stateRoot?: string
+  /** Compile every page at startup instead of caching pages on first request. */
+  buildCache?: boolean
+  plugins?: readonly PluginContribution[]
+  runtime?: RuntimeProfileOptions
+  diagnostics?: SourceDiagnosticMode
+  log?: Log
+}
+
+export async function createApp(options: CreateAppOptions) {
+  const repo = new Repository(options.root, options.environment)
+  const actors = new ActorDirectory()
+  const access = new SourceAccessIndex(repo, actors)
+  const app = new Engine(
+    repo,
+    options.environment,
+    actors,
+    actors.profiles,
+    access,
+    options.log,
+    options.runtime,
+    options.diagnostics,
+    options.stateRoot ?? projectDirectory(options.root, ".pathmx/state"),
+  )
+  if (options.actionsRoot) app.actionsRoot = options.actionsRoot
+  try {
+    app.registerPlugin(ActorDirectoryPlugin(actors))
+    app.registerPlugin(SourceAccessPlugin(access))
+    app.registerPlugin(MetaPlugin)
+    app.registerPlugin(SchemaPlugin)
+    for (const plugin of expandPluginContributions(options.plugins ?? [])) {
+      app.registerPlugin(plugin)
+    }
+    app.freezePlugins()
+    await app.setupPlugins()
+    await app.perf.measureAsync("repo.load", () => repo.load())
+    await app.indexAllNodes()
+    if (options.diagnostics !== "collect") access.validate()
+    await app.readyCredentials()
+    if (options.buildCache) await app.buildCache()
+    return app
+  } catch (error) {
+    await app.close().catch(() => undefined)
+    throw error
+  }
+}

package/host/engine.ts

@@ -0,0 +1,630 @@
+import type {
+  Actor,
+  ActorProfiles,
+  CredentialSession,
+  KnownActorIndex,
+  Principal,
+} from "../authority/model"
+import type {
+  AssetContext,
+  CompiledPage,
+  CompileContext,
+  DocumentAsset,
+  PageContext,
+  Plugin,
+  PluginFactory,
+  ViewContext,
+} from "../plugins/types"
+import {
+  type AccessDecision,
+  type ProposedSourceChange,
+  type ReadAccess,
+  type SourceAccessInspection,
+  type SourceCapability,
+  type SourcePermissionRecord,
+  type SourceAccessPolicy,
+} from "../authority/access"
+import {
+  indexSourceDocument,
+  type Source,
+  type SourceBlock,
+} from "../source/index"
+import { type Dependency, type DependencyContext } from "../dependencies"
+import type { RouteInvalidation } from "../invalidation"
+import { Graph } from "../graph"
+import {
+  type CommitResult,
+  type SourceChangeSet,
+  Repository,
+} from "../repository"
+import type { BundledAsset, PathMXEnvironment } from "../environment"
+import { Log } from "../log"
+import { Perf } from "../perf"
+import { defaultActionsRoot } from "../actions/actions"
+import { indexRouteConflicts, publicPath, resolveRoute } from "../server/router"
+import { ActorSourceError } from "../authority/actors.ts"
+import { SourceAccessError } from "../authority/access.ts"
+import {
+  runAgentJobWithIndex,
+  type AgentAdmission,
+  type AgentJob,
+} from "../authority/agents.ts"
+import {
+  createAssetBag,
+  documentAssetRank,
+  renderDocumentAssets,
+} from "../document.ts"
+import { GeneratedAssets } from "../assets.ts"
+import { PluginHost } from "./plugin-host.ts"
+import { PageCompiler } from "./compiler.ts"
+import { SourceSynchronizer } from "./source-sync.ts"
+import { PluginDatabases } from "../database.ts"
+import { projectDirectory } from "../project.ts"
+import { browserBundleAssets } from "../browser-bundle.ts"
+import {
+  createRuntimeProfile,
+  type RuntimeProfile,
+  type RuntimeProfileOptions,
+} from "../runtime-profile.ts"
+import { createView } from "../view/session.ts"
+import {
+  SourceDiagnostics,
+  type SourceDiagnostic,
+  type SourceDiagnosticMode,
+} from "../source-diagnostic.ts"
+import type { ApplicationSchema } from "../schema/model.ts"
+import { Query } from "../query/kernel.ts"
+import type { QueryContribution } from "../query/model.ts"
+
+export { PluginRegistrationError } from "./plugin-host.ts"
+
+export class Engine {
+  environment: PathMXEnvironment
+  readonly runtime: RuntimeProfile
+  repo: Repository
+  graph: Graph
+  readonly profiles: ActorProfiles
+  actionsRoot: string
+  perf = new Perf()
+  log: Log
+  private bundles = new Map<string, Promise<BundledAsset[]>>()
+  private assetRevisions = new Map<string, number>()
+  private generatedAssets: GeneratedAssets
+  private actorIndex: KnownActorIndex
+  private accessPolicy: SourceAccessPolicy
+  private authorityErrors = new Map<string, string>()
+  private sourceDiagnosticStore: SourceDiagnostics
+  private pluginHost: PluginHost
+  readonly queries: Query
+  private compiler: PageCompiler
+  private sourceSync: SourceSynchronizer
+
+  constructor(
+    repo: Repository,
+    environment: PathMXEnvironment,
+    actors: KnownActorIndex,
+    profiles: ActorProfiles,
+    access: SourceAccessPolicy,
+    log = new Log(),
+    runtime?: RuntimeProfileOptions,
+    diagnostics: SourceDiagnosticMode = "throw",
+    stateRoot = projectDirectory(repo.rootPath, ".pathmx/state"),
+  ) {
+    this.repo = repo
+    this.environment = environment
+    this.runtime = createRuntimeProfile(runtime)
+    this.generatedAssets =
+      this.runtime.target === "static"
+        ? new GeneratedAssets(Number.POSITIVE_INFINITY)
+        : new GeneratedAssets()
+    this.graph = new Graph(repo)
+    this.actorIndex = actors
+    this.profiles = profiles
+    this.accessPolicy = access
+    this.log = log
+    this.pluginHost = new PluginHost(
+      new PluginDatabases(environment.database, stateRoot),
+    )
+    this.queries = new Query(this)
+    this.compiler = new PageCompiler(this, this.pluginHost)
+    this.sourceSync = new SourceSynchronizer(
+      this,
+      this.pluginHost,
+      this.compiler,
+    )
+    this.sourceDiagnosticStore = new SourceDiagnostics(diagnostics, log)
+    this.actionsRoot = defaultActionsRoot(repo.rootPath)
+  }
+
+  registerPlugin(plugin: PluginFactory | Plugin) {
+    this.pluginHost.register(plugin)
+  }
+
+  freezePlugins() {
+    this.pluginHost.freeze()
+  }
+
+  setupPlugins() {
+    return this.pluginHost.setup(this)
+  }
+
+  appContext(plugin: string) {
+    return this.pluginHost.appContext(plugin, this)
+  }
+
+  get plugins() {
+    return this.pluginHost.plugins
+  }
+
+  get schema(): ApplicationSchema {
+    return this.pluginHost.schema
+  }
+
+  registeredQuery(reference: string | QueryContribution) {
+    return this.pluginHost.query(reference)
+  }
+
+  actor(id: string) {
+    return this.actorIndex.findActorById(id)
+  }
+
+  get pageCache() {
+    return this.compiler.pageCache
+  }
+
+  dependentsOf(dependency: string | Dependency) {
+    return this.compiler.dependentsOf(dependency)
+  }
+
+  dependenciesOf(path: string) {
+    return this.compiler.dependenciesOf(path)
+  }
+
+  /** Bundle a browser entrypoint once per Engine; concurrent calls share one build. */
+  bundle(entrypoint: string | URL) {
+    const key = String(entrypoint)
+    let pending = this.bundles.get(key)
+    if (!pending) {
+      pending = this.perf.measureAsync(
+        "bundle",
+        () => this.environment.bundle(entrypoint),
+        key,
+      )
+      this.bundles.set(key, pending)
+    }
+    return pending
+  }
+
+  /** @internal Create the asset collector shared by host compilation paths. */
+  documentAssetBag(assets: DocumentAsset[] = []) {
+    const bag = createAssetBag(assets)
+    const addBrowserBundle: AssetContext["addBrowserBundle"] = async (
+      entrypoint,
+      name,
+    ) => {
+      bag.addAsset(...(await browserBundleAssets(this, entrypoint, name)))
+    }
+    return { ...bag, addBrowserBundle }
+  }
+
+  async documentAssets(page?: CompiledPage) {
+    const { assets, addAsset, addBrowserBundle } = this.documentAssetBag()
+    const ctx = { page, addAsset, addBrowserBundle }
+    await this.pluginHost.documentAssets(ctx, this)
+    addAsset(...(page?.assets ?? []))
+    return assets
+      .map((asset) => this.resolveDocumentAsset(asset))
+      .sort((a, b) => documentAssetRank(a) - documentAssetRank(b))
+  }
+
+  servedAsset(pathname: string) {
+    return this.generatedAssets.get(pathname)
+  }
+
+  /** @internal Enumerate retained generated artifacts during static publication. */
+  generatedAssetEntries() {
+    return this.generatedAssets.entries()
+  }
+
+  /** Publish an immutable, content-hashed binary asset under `/.pmx/`. */
+  async publishAsset(name: string, blob: Blob, contentType = blob.type) {
+    return this.generatedAssets.publishBlob(name, blob, contentType)
+  }
+
+  onSync(listener: (event: RouteInvalidation) => void) {
+    return this.sourceSync.onSync(listener)
+  }
+
+  private resolveDocumentAsset(asset: DocumentAsset): DocumentAsset {
+    if (asset.type === "stylesheet" && "name" in asset) {
+      const href = this.storeNamed(
+        asset.name,
+        asset.text,
+        "text/css; charset=utf-8",
+      )
+      return {
+        type: "stylesheet",
+        href,
+        ...(asset.media ? { media: asset.media } : {}),
+      }
+    }
+    if (asset.type === "script" && "name" in asset) {
+      const href = this.storeNamed(
+        asset.name,
+        asset.text,
+        "text/javascript; charset=utf-8",
+      )
+      return { type: "script", href, module: asset.module }
+    }
+    if (asset.type === "script" && "source" in asset) {
+      const revision = this.assetRevisions.get(asset.source)
+      const href = revision ? `${asset.source}?pmx=${revision}` : asset.source
+      return { type: "script", href, module: asset.module }
+    }
+    return asset
+  }
+
+  bumpAssetRevisions(paths: Iterable<string>) {
+    for (const path of paths) {
+      const graphPath = this.repo.graphPath(path)
+      this.assetRevisions.set(
+        graphPath,
+        (this.assetRevisions.get(graphPath) ?? 0) + 1,
+      )
+    }
+  }
+
+  private storeNamed(name: string, text: string, contentType: string) {
+    return this.generatedAssets.publishText(name, text, contentType)
+  }
+
+  async documentHead(page?: CompiledPage) {
+    return renderDocumentAssets(await this.documentAssets(page))
+  }
+
+  resolve(pathname: string) {
+    const route = resolveRoute(this.repo, pathname)
+    return route?.type === "page" ? route.source : undefined
+  }
+
+  resolveCredentials(request: Request) {
+    return this.pluginHost.resolveCredentials(request, this.actorIndex, this)
+  }
+
+  /** Create a lightweight live View from a host-admitted credential session. */
+  view(session: CredentialSession) {
+    return createView(this, session)
+  }
+
+  credentialRequest(request: Request) {
+    return this.pluginHost.credentialRequest(request, this.actorIndex)
+  }
+
+  readyCredentials() {
+    return this.pluginHost.readyCredentials(this.actorIndex)
+  }
+
+  serverRoute(request: Request, url = new URL(request.url), publicUrl = url) {
+    return this.pluginHost.serverRoute(request, url, this, publicUrl)
+  }
+
+  /** @internal Test whether an optional behavior-owning Plugin is installed. */
+  hasPlugin(id: string) {
+    return this.pluginHost.has(id)
+  }
+
+  /** @internal Resolve a namespaced Action contributed by a Plugin. */
+  pluginAction(name: string) {
+    return this.pluginHost.action(name)
+  }
+
+  /** @internal Project contextual Actions registered by Plugins. */
+  actionAffordances(principal: Principal, target: Source) {
+    return this.pluginHost.actionAffordances(principal, target, this)
+  }
+
+  closeCredentials() {
+    return this.pluginHost.closeCredentials()
+  }
+
+  close() {
+    return this.pluginHost.close(this)
+  }
+
+  homeActorId(path: string) {
+    return this.actorIndex.findHomeOwner(path)?.id
+  }
+
+  /** Admit a configured Agent without exposing the private Actor directory. */
+  runAgentJob(admission: AgentAdmission, job: AgentJob) {
+    return runAgentJobWithIndex(this, this.actorIndex, admission, job)
+  }
+
+  readAccess(principal: Principal, target: string | Source): ReadAccess {
+    return this.accessPolicy.readAccess(principal, target)
+  }
+
+  inspectSourceAccess(
+    principal: Principal,
+    target: string | Source,
+  ): SourceAccessInspection {
+    return this.accessPolicy.inspect(principal, target)
+  }
+
+  /** Privileged repository inspection for administrative tools such as the CLI. */
+  inspectSourcePermissions(target: Source): readonly SourcePermissionRecord[] {
+    return [
+      ...this.actorIndex.all().map((actor) => ({
+        sourceId: target.id,
+        actorId: actor.id,
+        ...this.accessPolicy.inspect({ type: "actor", actor }, target),
+      })),
+      {
+        sourceId: target.id,
+        actorId: null,
+        ...this.accessPolicy.inspect({ type: "anonymous" }, target),
+      },
+    ]
+  }
+
+  /** Privileged repository inspection; unlike a credential session, this does not impersonate. */
+  inspectActorPermissions(
+    actorId: string,
+  ): readonly SourcePermissionRecord[] | undefined {
+    const actor = this.actorIndex.findActorById(actorId)
+    if (!actor) return
+    const principal = { type: "actor" as const, actor }
+    return this.repo
+      .all()
+      .sort((a, b) => a.id.localeCompare(b.id))
+      .map((source) => ({
+        sourceId: source.id,
+        actorId,
+        ...this.accessPolicy.inspect(principal, source),
+      }))
+  }
+
+  hasSourceCapability(
+    principal: Principal,
+    target: string | Source,
+    capability: SourceCapability,
+  ) {
+    return this.accessPolicy.hasCapability(principal, target, capability)
+  }
+
+  authorizeChange(actor: Actor, change: ProposedSourceChange): AccessDecision {
+    return this.accessPolicy.authorizeChange(actor, change)
+  }
+
+  canEmbed(container: string, dependency: string) {
+    return this.accessPolicy.canEmbed(container, dependency)
+  }
+
+  forgetNode(nodePath: string) {
+    this.compiler.unindexSource(nodePath)
+    this.sourceDiagnosticStore.delete(nodePath)
+    this.pluginHost.unindex(nodePath, this)
+    this.queries.unindexSource(nodePath)
+  }
+
+  /** @internal Clear a degraded authority record after its Source is removed. */
+  clearAuthorityError(sourceId: string) {
+    this.authorityErrors.delete(sourceId)
+  }
+
+  /** @internal Expected authoring failures collected while indexing. */
+  sourceDiagnostics(): readonly SourceDiagnostic[] {
+    return this.sourceDiagnosticStore.all()
+  }
+
+  indexSource(source: Source, tolerateAuthorityErrors = false) {
+    return this.perf.measure(
+      "index.source",
+      () => {
+        this.forgetNode(source.path)
+        this.compiler.indexSource(source)
+        this.authorityErrors.delete(source.id)
+        const capture = (error: unknown) => {
+          if (this.sourceDiagnosticStore.capture(error)) return true
+          if (
+            !tolerateAuthorityErrors ||
+            !(
+              error instanceof ActorSourceError ||
+              error instanceof SourceAccessError
+            )
+          ) {
+            return false
+          }
+          this.authorityErrors.set(source.id, error.message)
+          this.log.error("authority.degraded", {
+            source: source.id,
+            message: error.message,
+          })
+          return true
+        }
+        try {
+          indexSourceDocument(source, this.environment.yaml)
+        } catch (error) {
+          if (!capture(error)) throw error
+          return
+        }
+        this.pluginHost.index(source, this, capture)
+        this.queries.indexSource(source)
+      },
+      source.path,
+    )
+  }
+
+  async indexAllNodes() {
+    this.log.info("index", { sources: this.repo.all().length })
+    for (const source of this.repo.all()) this.indexSource(source)
+    for (const conflict of indexRouteConflicts(this.repo)) {
+      this.log.warn("route.index.conflict", {
+        dir: conflict.dir,
+        winner: conflict.winner.path,
+        shadowed: conflict.shadowed.map((source) => source.path),
+        rule: "first index source by id, codepoint order",
+      })
+    }
+    await this.perf.measureAsync("graph.rebuild", () => this.graph.rebuild())
+  }
+
+  authorityReadiness() {
+    const errors = [
+      ...[...this.authorityErrors].map(([sourceId, message]) => ({
+        sourceId,
+        message,
+      })),
+      ...(this.accessPolicy.diagnostics?.() ?? []),
+    ]
+      .filter(
+        (error, index, all) =>
+          all.findIndex(
+            (candidate) =>
+              candidate.sourceId === error.sourceId &&
+              candidate.message === error.message,
+          ) === index,
+      )
+      .sort(
+        (a, b) =>
+          a.sourceId.localeCompare(b.sourceId) ||
+          a.message.localeCompare(b.message),
+      )
+    return errors.length
+      ? {
+          type: "degraded" as const,
+          errors,
+        }
+      : { type: "ready" as const, errors: [] }
+  }
+
+  isAuthorized(source: Source, actor: Actor) {
+    return this.readAccess({ type: "actor", actor }, source) !== "denied"
+  }
+
+  isAuthorizedPath(path: string, actor: Actor) {
+    const source = this.repo.atPath(path) ?? this.repo.get(path)
+    if (source) return this.isAuthorized(source, actor)
+    return this.readAccess({ type: "actor", actor }, path) !== "denied"
+  }
+
+  compilePage(source: Source) {
+    return this.compiler.compilePage(source)
+  }
+
+  /** @internal Release state retained only for live recompilation. */
+  forgetCompiledPage(path: string) {
+    this.compiler.forgetCompiled(path)
+  }
+
+  ensurePage(source: Source) {
+    return this.compiler.ensurePage(source)
+  }
+
+  compileDocument(
+    source: Source,
+    dependencies: DependencyContext,
+    excludedPluginId: string,
+  ) {
+    return this.compiler.compileDocument(source, dependencies, excludedPluginId)
+  }
+
+  compileBlock(
+    source: Source,
+    block: SourceBlock,
+    dependencies?: DependencyContext,
+    options?: { id?: string },
+    scope?: CompileContext["scope"],
+  ) {
+    return this.compiler.compileBlock(
+      source,
+      block,
+      dependencies,
+      options,
+      scope,
+    )
+  }
+
+  isPage(source: Source) {
+    return this.compiler.isPage(source)
+  }
+
+  buildCache() {
+    return this.compiler.buildCache()
+  }
+
+  dropNode(nodePath: string) {
+    return this.sourceSync.dropNode(nodePath)
+  }
+
+  commit(changeSet: SourceChangeSet) {
+    return this.sourceSync.commit(changeSet)
+  }
+
+  commitPrepared(prepare: () => Promise<SourceChangeSet>) {
+    return this.sourceSync.commitPrepared(prepare)
+  }
+
+  refresh(
+    result: CommitResult,
+    before = new Map<string, Source | undefined>(),
+  ) {
+    return this.sourceSync.refresh(result, before)
+  }
+
+  syncSource(path: string) {
+    return this.sourceSync.syncSource(path)
+  }
+
+  invalidateAsset(path: string) {
+    return this.sourceSync.invalidateAsset(path)
+  }
+
+  invalidateAssets(paths: Iterable<string>) {
+    return this.sourceSync.invalidateAssets(paths)
+  }
+
+  syncFromStorage(relPath: string) {
+    return this.sourceSync.syncFromStorage(relPath)
+  }
+
+  rewrite(
+    session: CredentialSession,
+    html: string,
+    source: Source,
+    init?: ResponseInit,
+  ) {
+    return this.perf.measureAsync(
+      "rewrite",
+      () => {
+        const view = this.view(session)
+        return this.rewriteWithPlugins(
+          html,
+          {
+            view,
+            session,
+            principal: view.principal,
+            source,
+            route: publicPath(source),
+          },
+          init,
+        )
+      },
+      source.path,
+    )
+  }
+
+  private async rewriteWithPlugins(
+    html: string,
+    ctx: ViewContext,
+    init?: ResponseInit,
+  ) {
+    return this.pluginHost.renderView(
+      html,
+      this.compiler.planFor(ctx.source.path),
+      ctx,
+      this,
+      init,
+    )
+  }
+}