@pathmx/core 0.5.0

package/query/model.ts

@@ -0,0 +1,79 @@
+import type { SqlDatabase } from "../database.ts"
+import type { DependencyContext } from "../dependencies.ts"
+import type { PathMXDataSchema, StandardSchemaV1 } from "../schema/standard.ts"
+import type { BlockSummary, SourceSummary, View } from "../view/model.ts"
+
+export type QueryScalar = string | number | boolean | null
+
+export type QuerySort = Readonly<{
+  by: string
+  direction?: "asc" | "desc"
+}>
+
+export type QueryRequest<Input = undefined> = Readonly<{
+  from?: string
+  input?: Input
+  where?: Readonly<Record<string, QueryScalar>>
+  sort?: readonly QuerySort[]
+  limit?: number
+}>
+
+export type SourceQueryRequest = QueryRequest &
+  Readonly<{
+    type?: string
+    has?: string | readonly string[]
+    recursive?: boolean
+  }>
+
+export type BlockQueryRequest = SourceQueryRequest
+
+type Awaitable<T> = T | Promise<T>
+type DataSchema = PathMXDataSchema<unknown, unknown>
+type OutputSchema = PathMXDataSchema<unknown, readonly unknown[]>
+
+export type QueryDefinition<
+  InputSchema extends DataSchema | undefined = DataSchema | undefined,
+  ResultSchema extends OutputSchema = OutputSchema,
+> = Readonly<{
+  input?: InputSchema
+  output: ResultSchema
+  resolve(
+    input: InputSchema extends DataSchema
+      ? StandardSchemaV1.InferOutput<InputSchema>
+      : undefined,
+    context: QueryResolverContext,
+  ): Awaitable<StandardSchemaV1.InferOutput<ResultSchema>>
+}>
+
+export type QueryContribution = QueryDefinition<any, any>
+
+export type QueryDefinitionInput<Definition extends QueryDefinition> =
+  Definition["input"] extends DataSchema
+    ? StandardSchemaV1.InferInput<Definition["input"]>
+    : undefined
+
+export type QueryDefinitionOutput<Definition extends QueryDefinition> =
+  StandardSchemaV1.InferOutput<Definition["output"]>
+
+export type QueryRunner = {
+  <Definition extends QueryDefinition>(
+    definition: Definition,
+    request?: QueryRequest<QueryDefinitionInput<Definition>>,
+  ): Promise<QueryDefinitionOutput<Definition>>
+  (id: string, request?: QueryRequest<unknown>): Promise<readonly unknown[]>
+}
+
+export type ViewQuery = Readonly<{
+  sources(request?: SourceQueryRequest): Promise<readonly SourceSummary[]>
+  blocks(request?: BlockQueryRequest): Promise<readonly BlockSummary[]>
+  run: QueryRunner
+}>
+
+export type QueryResolverContext = DependencyContext &
+  Readonly<{
+    view: View
+    from: string
+    query: ViewQuery
+    /** Database isolated to the query's owning Plugin. */
+    database?: SqlDatabase
+  }>

package/repository.ts

@@ -0,0 +1,374 @@
+import type { PathMXEnvironment } from "./environment.ts"
+import { type Source, createSource, resolveSourceId } from "./source/index.ts"
+import { canonicalSourceId } from "./canonical.ts"
+import {
+  readTextFileState,
+  sameTextFileState,
+  type TextFileState,
+} from "./text-file.ts"
+
+const LOAD_CONCURRENCY = 16
+
+export type SourceChange =
+  | { type: "create"; path: string; content: string }
+  | { type: "replace"; path: string; content: string }
+  | { type: "delete"; path: string }
+
+export type SourceChangeSet = {
+  changes: SourceChange[]
+}
+
+export type CommitResult = {
+  applied: SourceChange[]
+  error?: Error
+}
+
+export type UpsertResult =
+  | { type: "updated"; source: Source }
+  | { type: "deleted" }
+  | { type: "error"; error: SourceLoadError; source?: Source }
+
+export class DuplicateSourceIdError extends Error {
+  readonly id: string
+  readonly existingPath: string
+  readonly incomingPath: string
+
+  constructor(id: string, existingPath: string, incomingPath: string) {
+    super(`Duplicate source id "${id}": ${existingPath} and ${incomingPath}`)
+    this.name = "DuplicateSourceIdError"
+    this.id = id
+    this.existingPath = existingPath
+    this.incomingPath = incomingPath
+  }
+}
+
+export class SourceLoadError extends Error {
+  readonly path: string
+
+  constructor(path: string, cause: unknown) {
+    const detail = cause instanceof Error ? cause.message : String(cause)
+    super(`Failed to load source ${path}: ${detail}`)
+    this.name = "SourceLoadError"
+    this.path = path
+    this.cause = cause
+  }
+}
+
+export class SourceCommitError extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = "SourceCommitError"
+  }
+}
+
+export class SourceConflictError extends SourceCommitError {
+  readonly path: string
+
+  constructor(path: string) {
+    super(`Source changed before commit: ${path}`)
+    this.name = "SourceConflictError"
+    this.path = path
+  }
+}
+
+function isNotFound(error: unknown) {
+  return (
+    error instanceof Error &&
+    "code" in error &&
+    (error as { code?: string }).code === "ENOENT"
+  )
+}
+
+export class Repository {
+  rootPath: string
+  environment: PathMXEnvironment
+  private byId = new Map<string, Source>()
+  private byPath = new Map<string, Source>()
+  private revisionValue = 0
+
+  constructor(rootPath: string, environment: PathMXEnvironment) {
+    this.rootPath = rootPath
+    this.environment = environment
+  }
+
+  graphPath(relPath: string) {
+    return this.environment.path.join("/", relPath.replaceAll("\\", "/"))
+  }
+
+  pathToId(path: string) {
+    return resolveSourceId(this.graphPath(path), {})
+  }
+
+  get(id: string) {
+    return this.byId.get(id)
+  }
+
+  atPath(path: string) {
+    const routePath = this.graphPath(path).replace(/\/$/, "") || "/"
+    return this.byPath.get(routePath)
+  }
+
+  /** @deprecated Use atPath. */
+  sourceAtPath(path: string) {
+    return this.atPath(path)
+  }
+
+  all() {
+    return [...this.byPath.values()]
+  }
+
+  /** Changes whenever repository membership or source identity changes. */
+  get revision() {
+    return this.revisionValue
+  }
+
+  async load() {
+    this.byId.clear()
+    this.byPath.clear()
+    this.revisionValue++
+    const files = [
+      ...(await this.environment.storage.list(this.rootPath)),
+    ].filter((file) => file.endsWith(".md"))
+
+    for (let start = 0; start < files.length; start += LOAD_CONCURRENCY) {
+      const loaded = await Promise.all(
+        files
+          .slice(start, start + LOAD_CONCURRENCY)
+          .map((file) => this.readListedSource(file)),
+      )
+      for (const item of loaded) {
+        if (!item) continue
+        if ("error" in item) throw item.error
+        try {
+          this.put(createSource(item.path, item.content, this.environment.yaml))
+        } catch (error) {
+          if (error instanceof DuplicateSourceIdError) throw error
+          throw new SourceLoadError(item.path, error)
+        }
+      }
+    }
+  }
+
+  private async readListedSource(relPath: string) {
+    const path = this.graphPath(relPath)
+    const storagePath = this.storagePath(relPath)
+    if (!storagePath) return
+    try {
+      return {
+        path,
+        content: await this.environment.storage.readText(storagePath),
+      }
+    } catch (error) {
+      if (isNotFound(error)) return
+      try {
+        if (!(await this.environment.storage.exists(storagePath))) return
+      } catch {
+        // Preserve the original read error when existence cannot be checked.
+      }
+      return { error: new SourceLoadError(path, error) }
+    }
+  }
+
+  /**
+   * Index a constructed Source after enforcing the one-to-one id/path invariant.
+   */
+  put(source: Source) {
+    canonicalSourceId(source.id)
+    const existing = this.byId.get(source.id)
+    if (existing && existing.path !== source.path) {
+      throw new DuplicateSourceIdError(source.id, existing.path, source.path)
+    }
+    const previous = this.byPath.get(source.path)
+    if (previous && previous.id !== source.id) this.byId.delete(previous.id)
+    this.byId.set(source.id, source)
+    this.byPath.set(source.path, source)
+    this.revisionValue++
+    return source
+  }
+
+  async upsert(
+    relPath: string,
+    options: { onError?: "throw" | "preserve" } = {},
+  ): Promise<UpsertResult> {
+    const onError = options.onError ?? "preserve"
+    const path = this.graphPath(relPath)
+    const storagePath = this.storagePath(relPath)
+    const previous = this.atPath(path)
+    if (!storagePath) {
+      this.drop(previous)
+      return { type: "deleted" }
+    }
+    try {
+      if (!(await this.environment.storage.exists(storagePath))) {
+        this.drop(previous)
+        return { type: "deleted" }
+      }
+      const content = await this.environment.storage.readText(storagePath)
+      // Same text: keep the indexed Source. createSource() starts with
+      // empty blocks; replacing here made the watch echo after commit
+      // drop them (syncSource returns early when content is unchanged).
+      if (previous && previous.content === content) {
+        return { type: "updated", source: previous }
+      }
+      const source = createSource(path, content, this.environment.yaml)
+      this.put(source)
+      return { type: "updated", source }
+    } catch (error) {
+      if (isNotFound(error)) {
+        this.drop(previous)
+        return { type: "deleted" }
+      }
+      if (error instanceof DuplicateSourceIdError) {
+        if (onError === "throw") throw error
+        return {
+          type: "error",
+          error: new SourceLoadError(path, error),
+          source: previous,
+        }
+      }
+      const loadError = new SourceLoadError(path, error)
+      if (onError === "throw") throw loadError
+      return { type: "error", error: loadError, source: previous }
+    }
+  }
+
+  storagePath(targetPath: string) {
+    const rel = targetPath.replaceAll("\\", "/").replace(/^\/+/, "")
+    if (!rel || rel.split("/").includes("..")) return
+    const normalizedRoot = this.rootPath.replaceAll("\\", "/")
+    const root =
+      normalizedRoot === "/" ? "/" : normalizedRoot.replace(/\/+$/, "")
+    if (root === "/") return `/${rel}`
+    return root ? `${root}/${rel}` : rel
+  }
+
+  async isFile(targetPath: string) {
+    const storagePath = this.storagePath(targetPath)
+    if (!storagePath) return false
+    try {
+      return await this.environment.storage.exists(storagePath)
+    } catch {
+      return false
+    }
+  }
+
+  remove(relPath: string) {
+    this.drop(this.atPath(relPath))
+  }
+
+  async commit(changeSet: SourceChangeSet): Promise<CommitResult> {
+    const changes = changeSet.changes.map((change) => {
+      if (change.path.split(/[\\/]/).includes("..")) {
+        throw new SourceCommitError(`Path escapes repository: ${change.path}`)
+      }
+      return { ...change, path: this.graphPath(change.path) }
+    })
+    this.preflight(changes)
+    await this.verifyStorage(changes)
+
+    const applied: SourceChange[] = []
+    try {
+      for (const change of changes) {
+        const file = this.storagePath(change.path)
+        if (!file)
+          throw new SourceCommitError(`Path escapes repository: ${change.path}`)
+        if (change.type === "delete") {
+          if (await this.environment.storage.exists(file)) {
+            await this.environment.storage.delete(file)
+          }
+        } else {
+          await this.environment.storage.writeText(file, change.content)
+        }
+        applied.push(change)
+      }
+    } catch (error) {
+      await this.resync(applied)
+      return {
+        applied,
+        error: error instanceof Error ? error : new Error(String(error)),
+      }
+    }
+
+    await this.resync(applied)
+    return { applied }
+  }
+
+  private preflight(changes: SourceChange[]) {
+    const nextByPath = new Map(this.byPath)
+    const nextById = new Map(this.byId)
+
+    for (const change of changes) {
+      const file = this.storagePath(change.path)
+      if (!file) {
+        throw new SourceCommitError(`Path escapes repository: ${change.path}`)
+      }
+      const previous = nextByPath.get(change.path)
+      if (change.type === "delete") {
+        if (!previous) {
+          throw new SourceCommitError(`Path does not exist: ${change.path}`)
+        }
+        nextByPath.delete(change.path)
+        nextById.delete(previous.id)
+        continue
+      }
+
+      const source = createSource(
+        change.path,
+        change.content,
+        this.environment.yaml,
+      )
+      if (change.type === "create" && previous) {
+        throw new SourceCommitError(`Path already exists: ${change.path}`)
+      }
+      if (change.type === "replace" && !previous) {
+        throw new SourceCommitError(`Path does not exist: ${change.path}`)
+      }
+      if (previous && previous.id !== source.id) nextById.delete(previous.id)
+      const owner = nextById.get(source.id)
+      if (owner && owner.path !== change.path) {
+        throw new DuplicateSourceIdError(source.id, owner.path, change.path)
+      }
+      nextByPath.set(change.path, source)
+      nextById.set(source.id, source)
+    }
+  }
+
+  private async verifyStorage(changes: SourceChange[]) {
+    for (const change of changes) {
+      const file = this.storagePath(change.path)
+      if (!file)
+        throw new SourceCommitError(`Path escapes repository: ${change.path}`)
+      const before = this.atPath(change.path)
+      if (change.type !== "create" && !before) {
+        throw new SourceConflictError(change.path)
+      }
+      const expected: TextFileState = before
+        ? { type: "present", content: before.content }
+        : { type: "missing" }
+      let current: TextFileState
+      try {
+        current = await readTextFileState(this.environment.storage, file)
+      } catch {
+        throw new SourceConflictError(change.path)
+      }
+      if (!sameTextFileState(current, expected)) {
+        throw new SourceConflictError(change.path)
+      }
+    }
+  }
+
+  private async resync(changes: SourceChange[]) {
+    for (const change of changes) {
+      const rel = change.path.replace(/^\/+/, "")
+      if (change.type === "delete") this.remove(change.path)
+      else await this.upsert(rel, { onError: "throw" })
+    }
+  }
+
+  private drop(source?: Source) {
+    if (!source) return
+    this.byId.delete(source.id)
+    this.byPath.delete(source.path)
+    this.revisionValue++
+  }
+}

package/runtime-profile.ts

@@ -0,0 +1,34 @@
+export type RuntimeProfileOptions = Readonly<{
+  mode?: "development" | "production"
+  target?: "server" | "static"
+  capabilities?: readonly Readonly<{ plugin: string; key: string }>[]
+}>
+
+export type RuntimeProfile = Readonly<{
+  mode: NonNullable<RuntimeProfileOptions["mode"]>
+  target: NonNullable<RuntimeProfileOptions["target"]>
+  has(plugin: string, key: string): boolean
+}>
+
+/** Normalize portable startup configuration into an immutable runtime view. */
+export function createRuntimeProfile(
+  options: RuntimeProfileOptions = {},
+): RuntimeProfile {
+  const capabilities = new Map<string, Set<string>>()
+  for (const capability of options.capabilities ?? []) {
+    let keys = capabilities.get(capability.plugin)
+    if (!keys) {
+      keys = new Set()
+      capabilities.set(capability.plugin, keys)
+    }
+    keys.add(capability.key)
+  }
+
+  return Object.freeze({
+    mode: options.mode ?? "production",
+    target: options.target ?? "server",
+    has(plugin: string, key: string) {
+      return capabilities.get(plugin)?.has(key) ?? false
+    },
+  })
+}

package/schema/model.ts

@@ -0,0 +1,92 @@
+import type { ActionContribution } from "../actions/actions.ts"
+import type { QueryContribution } from "../query/model.ts"
+import type { PathMXDataSchema } from "./standard.ts"
+import type { SourceNode } from "../source/index.ts"
+
+export type NodeTypeDefinition = Readonly<{
+  /** Singular human label. Falls back to the title-cased node type. */
+  label?: string
+  description?: string
+  /** Renderer-owned icon name, such as a Lucide icon id. */
+  icon?: string
+  /** Renderer-owned color token or CSS color. */
+  color?: string
+  /** Validate the complete authored data map for this node type. */
+  schema?: PathMXDataSchema
+}>
+
+export type SourceTypeDefinition = NodeTypeDefinition
+export type BlockTypeDefinition = NodeTypeDefinition
+
+export type SchemaContribution = Readonly<{
+  /** Ordered Source-type contributions. Later Plugins may refine presentation. */
+  sources?: Readonly<Record<string, SourceTypeDefinition>>
+  /** Ordered Block-type contributions. Later Plugins may refine presentation. */
+  blocks?: Readonly<Record<string, BlockTypeDefinition>>
+  /** Exclusively owned Source/Block data props and their value schemas. */
+  props?: Readonly<Record<string, PathMXDataSchema>>
+  /** Plugin-local query names installed externally as `<plugin>:<name>`. */
+  query?: Readonly<Record<string, QueryContribution>>
+  /** Plugin-local Action names installed externally as `<plugin>:<name>`. */
+  actions?: Readonly<Record<string, ActionContribution>>
+}>
+
+/** Preserve the complete inferred shape of one Plugin-owned Schema fragment. */
+export function defineSchema<const Definition extends SchemaContribution>(
+  definition: Definition,
+) {
+  return definition
+}
+
+/** Serializable node-type meaning safe to project into Views and UIs. */
+export type NodeType = Readonly<{
+  type: string
+  label: string
+  description?: string
+  icon: string
+  color: string
+  origin: "defined" | "observed"
+  plugins: readonly string[]
+}>
+
+export type SourceType = NodeType
+export type BlockType = NodeType
+
+export type DataProp = Readonly<{
+  name: string
+  plugin: string
+  schema: PathMXDataSchema
+  inputJsonSchema: Readonly<Record<string, unknown>>
+  outputJsonSchema: Readonly<Record<string, unknown>>
+}>
+
+export type NodeSchema = Readonly<{
+  plugin: string
+  schema: PathMXDataSchema
+  inputJsonSchema: Readonly<Record<string, unknown>>
+  outputJsonSchema: Readonly<Record<string, unknown>>
+}>
+
+export type QuerySchema = Readonly<{
+  id: string
+  plugin: string
+  input?: PathMXDataSchema
+  output: PathMXDataSchema<unknown, readonly unknown[]>
+  inputJsonSchema?: Readonly<Record<string, unknown>>
+  outputJsonSchema: Readonly<Record<string, unknown>>
+}>
+
+export type ApplicationSchema = Readonly<{
+  sourceType(sourceOrType: SourceNode | string): SourceType
+  sourceTypes(): readonly SourceType[]
+  blockType(blockOrType: SourceNode | string): BlockType
+  blockTypes(): readonly BlockType[]
+  sourceSchemas(sourceOrType: SourceNode | string): readonly NodeSchema[]
+  blockSchemas(blockOrType: SourceNode | string): readonly NodeSchema[]
+  query(id: string): QuerySchema | undefined
+  queries(): readonly QuerySchema[]
+  prop(name: string): DataProp | undefined
+  props(node?: SourceNode): readonly DataProp[]
+  has(node: SourceNode, prop: string): boolean
+  value(node: SourceNode, prop: string): unknown
+}>