@pathmx/core 0.5.0

package/cli/readme.md

@@ -0,0 +1,95 @@
+# PathMX CLI
+
+The PathMX CLI is a command-line tool for managing and serving PathMX projects.
+
+_Note: Source edits and Action commits keep connected browsers in sync in both
+`serve` and `dev`. Development mode additionally restarts for code changes._
+
+## Usage
+
+```
+pathmx <command>
+```
+
+`pmx` is a shorter alias. In this repository, `bun run cli -- <command>` runs
+the source CLI.
+
+## Commands
+
+- `pathmx serve [root] [--port <port>]` starts the production server and watches authored Markdown and CSS
+- `pathmx dev [root] [--port <port>]` starts the development server with the same Source watcher plus process restarts for engine, plugin, or Action code changes
+- `pathmx export [root] --origin <url> [--out <path>]` writes the anonymous static publication and canonical route manifest
+- `pathmx mv <old-path> <new-path> [--dry-run]` moves a source and rewrites linked references
+- `pathmx rm <path> [--dry-run]` removes a source and unlinks references
+- `pathmx tree [root] [--all]` shows the source/graph tree
+- `pathmx perms [source] [--as <actor>] [--format text|json]` inspects effective Source permissions
+- `pathmx lint [root]` runs Source, link, compile, foundation, and repository Plugin validation without starting a server
+- `pathmx query <sources|blocks|plugin:name>` runs an access-controlled query and writes JSON, JSON Lines, or a schema-derived table
+- `pathmx plugins list` lists installed official packages
+- `pathmx plugins add <name...>` installs exact releases from the CLI's channel
+- `pathmx plugins update [name...]` updates installed packages from the CLI's channel
+- `pathmx update [--check]` checks or updates the globally installed CLI
+- `pathmx help` shows help for a command
+
+Repository plugins can add trusted administrator commands beneath their plugin
+id, such as `pmx auth setup`, `pmx auth doctor`, `pmx auth users list`, and
+`pmx auth sessions revoke-all`. The plugin must already be installed under the
+project's sibling `plugins/` directory for its commands to be discovered.
+Plugin command contexts include the portable Pattern installer for safely
+planning and creating user-owned files beneath the source or project root.
+
+`create` is not implemented yet. Global `--root` / `--actions` override the default `./paths` and sibling `actions/` directories.
+
+## Export
+
+`pmx export` defaults to a sibling `dist/` directory. It stages the complete
+build before replacing the prior output and writes the adapter contract to
+`.pathmx/manifest.json`. Static pages retain enhanced navigation and poll the
+build marker for deployments; the marker points to an immutable page-leaf map
+and is staged last. Completed page bodies stream into private directory staging
+before the Merkle deployment root is known. Actions and other server-only
+authored behavior produce export diagnostics.
+
+The Book App collaboration fixture can be inspected directly:
+
+```sh
+pmx --root labs/book-app/paths perms /users/alice/papers/reading-reflection.paper
+pmx --root labs/book-app/paths perms /users/alice/papers/reading-reflection.paper --as /users/bob.user
+pmx --root labs/book-app/paths perms --as /users/bob.user --format json
+```
+
+Source mode shows every known Actor plus anonymous access. Actor mode lists only
+Sources that Actor can read. `--as` is trusted repository inspection; it does
+not create a credential session or impersonate the Actor.
+
+## Query
+
+`pmx query` uses the same installed Schema, query kernel, access checks, field
+catalog, and normalized request as `View.query`; it does not start a server or
+read around View access.
+
+```sh
+pmx query sources \
+  --from /work/issues \
+  --type issue \
+  --where status=open \
+  --sort priority:desc
+
+pmx query blocks --from /course --type task --where completed=false
+
+pmx query schedule:occurrences \
+  --input '{"start":"2026-08-01T00:00:00Z","end":"2026-09-01T00:00:00Z"}' \
+  --format jsonl
+```
+
+Common options are `--from`, repeatable `--where field=value`, repeatable
+`--sort field[:asc|desc]`, `--limit`, `--format json|jsonl|table`, and trusted
+`--as <actor>` inspection. Built-in Source and Block roots also support
+`--type`, repeatable `--has <registered-prop>`, and `--no-recursive`. Named
+queries accept their Standard Schema-validated input through `--input <json>`.
+`--request <json-or-yaml-file>` (or `-` for stdin) accepts the complete request
+shape and composes with explicit flags.
+
+JSON is deterministic and intended to pipe into `jq` when custom projection or
+transformation is needed. Table columns are discovered from the same required
+Standard JSON Schema representation used by authored query tables.

package/cli/release.ts

@@ -0,0 +1,75 @@
+import manifest from "../package.json" with { type: "json" }
+
+type ReleaseManifest = Readonly<{
+  name: string
+  version: string
+  engines: { bun: string }
+  pathmxRelease: {
+    channel: "beta" | "latest"
+    testedBun: string
+  }
+}>
+
+const releaseManifest = manifest as ReleaseManifest
+
+export const release = Object.freeze({
+  package: releaseManifest.name,
+  version: releaseManifest.version,
+  channel: releaseManifest.pathmxRelease.channel,
+  minimumBun: releaseManifest.engines.bun.replace(/^>=/, ""),
+  testedBun: releaseManifest.pathmxRelease.testedBun,
+})
+
+function numericVersion(version: string) {
+  const [major = 0, minor = 0, patch = 0] = version
+    .replace(/^v/, "")
+    .split("-", 1)[0]!
+    .split(".")
+    .map((part) => Number.parseInt(part, 10))
+  return [major, minor, patch] as const
+}
+
+export function compareVersions(left: string, right: string) {
+  const a = numericVersion(left)
+  const b = numericVersion(right)
+  for (let index = 0; index < a.length; index++) {
+    const difference = a[index]! - b[index]!
+    if (difference) return Math.sign(difference)
+  }
+  return 0
+}
+
+export type BunCompatibility = Readonly<{
+  type: "supported" | "outdated" | "unsupported"
+  message?: string
+}>
+
+export function bunCompatibility(
+  current: string,
+  minimum = release.minimumBun,
+  tested = release.testedBun,
+): BunCompatibility {
+  if (compareVersions(current, minimum) < 0) {
+    return {
+      type: "unsupported",
+      message: `PathMX ${release.version} requires Bun ${minimum} or newer; you are running ${current}. Run \`bun upgrade\` and try again.`,
+    }
+  }
+  if (compareVersions(current, tested) < 0) {
+    return {
+      type: "outdated",
+      message: `PathMX ${release.version} is tested with Bun ${tested}; you are running ${current}. Run \`bun upgrade\` when convenient.`,
+    }
+  }
+  return { type: "supported" }
+}
+
+export function checkBunVersion(current = Bun.version) {
+  const compatibility = bunCompatibility(current)
+  if (compatibility.type === "unsupported") {
+    throw new Error(compatibility.message)
+  }
+  if (compatibility.type === "outdated") {
+    console.warn(`warning: ${compatibility.message}`)
+  }
+}

package/cli/rm.ts

@@ -0,0 +1,22 @@
+import type { Command } from "commander"
+import { applySourceOpPlan, removeSource } from "../ops/index.ts"
+import { fail, loadApp, printPlan, rootFromCommand } from "./utils.ts"
+
+export function registerRm(program: Command) {
+  program
+    .command("rm")
+    .description("Remove a source and unlink references")
+    .argument("<path>", "source path to remove")
+    .option("--dry-run", "print the plan without writing")
+    .action(async (path: string, opts: { dryRun?: boolean }, cmd: Command) => {
+      try {
+        const { root, actionsRoot } = rootFromCommand(cmd)
+        const app = await loadApp(root, { actionsRoot, buildCache: false })
+        const plan = await removeSource(app, path)
+        printPlan(plan, Boolean(opts.dryRun))
+        if (!opts.dryRun) await applySourceOpPlan(app, plan)
+      } catch (error) {
+        fail(error)
+      }
+    })
+}

package/cli/serve.ts

@@ -0,0 +1,100 @@
+import type { Command } from "commander"
+import { PathMX, handleRequest } from "../index.ts"
+import { watchPaths } from "../server/watch.ts"
+import { fail, rootFromCommand } from "./utils.ts"
+
+export type ServerMode = "serve" | "dev"
+
+export async function startServer(options: {
+  root: string
+  actionsRoot?: string
+  port?: number
+  hostname?: string
+  verbose?: boolean
+  mode?: ServerMode
+}) {
+  const mode = options.mode ?? "serve"
+  const app = await PathMX(options.root, {
+    actionsRoot: options.actionsRoot,
+    runtime: {
+      mode: mode === "dev" ? "development" : "production",
+    },
+    diagnostics: mode === "dev" ? "collect" : "throw",
+  })
+  if (options.verbose) app.log.level = "debug"
+  const watch = watchPaths(app, options.root)
+  try {
+    await watch.subscription
+    const port = options.port ?? (Number(process.env.PORT) || 3000)
+    const hostname =
+      options.hostname ?? (mode === "dev" ? "127.0.0.1" : undefined)
+    const server = Bun.serve({
+      port,
+      ...(hostname ? { hostname } : {}),
+      fetch(req, srv) {
+        // Quiet SSE streams count as idle. Bun's default 10s idleTimeout
+        // then kills /api/runtime/live mid-chunk; Chrome logs
+        // ERR_INCOMPLETE_CHUNKED_ENCODING and EventSource reconnects.
+        if (new URL(req.url).pathname === "/api/runtime/live")
+          srv.timeout(req, 0)
+        return handleRequest(app, req)
+      },
+    })
+
+    app.log.info("listen", {
+      url: String(server.url),
+      sources: app.repo.all().length,
+      mode,
+    })
+    return {
+      app,
+      server,
+      async close() {
+        await watch.close()
+        await app.close()
+        server.stop(true)
+      },
+    }
+  } catch (error) {
+    await watch.close()
+    await app.close()
+    throw error
+  }
+}
+
+export function listenPort(value: string) {
+  const port = Number(value)
+  if (!Number.isInteger(port) || port <= 0) {
+    throw new Error(`Invalid port: ${value}`)
+  }
+  return port
+}
+
+export function registerServe(program: Command) {
+  program
+    .command("serve")
+    .description("Start the live production server")
+    .argument("[root]", "source root (defaults to ./paths)")
+    .option("-p, --port <port>", "port to listen on", listenPort)
+    .option("--host <hostname>", "hostname or address to listen on")
+    .action(
+      async (
+        root: string | undefined,
+        opts: { port?: number; host?: string },
+        cmd: Command,
+      ) => {
+        try {
+          const resolved = rootFromCommand(cmd, root)
+          await startServer({
+            root: resolved.root,
+            actionsRoot: resolved.actionsRoot,
+            port: opts.port,
+            hostname: opts.host,
+            mode: "serve",
+          })
+        } catch (error) {
+          fail(error)
+        }
+      },
+    )
+}

package/cli/tree.ts

@@ -0,0 +1,131 @@
+import { basename } from "node:path"
+import type { Command } from "commander"
+import pc from "picocolors"
+import type { Engine } from "../host/engine.ts"
+import type { Source } from "../source/index.ts"
+import { fail, loadApp, rootFromCommand } from "./utils.ts"
+
+type TrieNode = {
+  name: string
+  source?: Source
+  asset?: boolean
+  children: Map<string, TrieNode>
+}
+
+function insert(
+  root: TrieNode,
+  parts: string[],
+  source?: Source,
+  asset?: boolean,
+) {
+  let node = root
+  for (const part of parts) {
+    let child = node.children.get(part)
+    if (!child) {
+      child = { name: part, children: new Map() }
+      node.children.set(part, child)
+    }
+    node = child
+  }
+  if (source) node.source = source
+  if (asset) node.asset = true
+}
+
+function annotate(source: Source, app: Engine) {
+  const outgoing = app.graph.linksFrom(source.path)
+  const inbound = app.graph.linksTo(source.path)
+  const unresolved = outgoing.filter(
+    (edge) => edge.type === "unresolved",
+  ).length
+  const parts = [source.type]
+  if (source.blocks.length) {
+    parts.push(
+      `${source.blocks.length} block${source.blocks.length === 1 ? "" : "s"}`,
+    )
+  }
+  if (outgoing.length || inbound.length) {
+    parts.push(`${outgoing.length}→ ${inbound.length}←`)
+  }
+  const suffix = unresolved ? ` · ${pc.red(`${unresolved} unresolved`)}` : ""
+  return ` ${pc.dim(`(${parts.join(" · ")})`)}${suffix}`
+}
+
+function render(
+  node: TrieNode,
+  prefix: string,
+  isLast: boolean,
+  lines: string[],
+  app: Engine,
+) {
+  const branch = isLast ? "└── " : "├── "
+  const extra = node.source
+    ? annotate(node.source, app)
+    : node.asset
+      ? ` ${pc.dim("(asset)")}`
+      : ""
+  lines.push(`${prefix}${branch}${node.name}${extra}`)
+  const next = `${prefix}${isLast ? "    " : "│   "}`
+  const children = [...node.children.values()].sort((a, b) =>
+    a.name.localeCompare(b.name),
+  )
+  children.forEach((child, index) => {
+    render(child, next, index === children.length - 1, lines, app)
+  })
+}
+
+export function formatTree(app: Engine, options: { all?: boolean } = {}) {
+  const trie: TrieNode = {
+    name: basename(app.repo.rootPath) || "paths",
+    children: new Map(),
+  }
+
+  for (const source of app.repo.all()) {
+    const parts = source.path.replace(/^\/+/, "").split("/").filter(Boolean)
+    insert(trie, parts, source)
+  }
+
+  if (options.all) {
+    for (const file of new Bun.Glob("**/*").scanSync({
+      cwd: app.repo.rootPath,
+      onlyFiles: true,
+    })) {
+      if (file.endsWith(".md")) continue
+      insert(trie, file.split("/").filter(Boolean), undefined, true)
+    }
+  }
+
+  const lines = [`${trie.name}/`]
+  const children = [...trie.children.values()].sort((a, b) =>
+    a.name.localeCompare(b.name),
+  )
+  children.forEach((child, index) => {
+    render(child, "", index === children.length - 1, lines, app)
+  })
+  return lines.join("\n")
+}
+
+export function registerTree(program: Command) {
+  program
+    .command("tree")
+    .description("Show the source/graph tree")
+    .argument("[root]", "source root (defaults to ./paths)")
+    .option("--all", "include non-markdown files")
+    .action(
+      async (
+        root: string | undefined,
+        opts: { all?: boolean },
+        cmd: Command,
+      ) => {
+        try {
+          const resolved = rootFromCommand(cmd, root)
+          const app = await loadApp(resolved.root, {
+            actionsRoot: resolved.actionsRoot,
+            buildCache: false,
+          })
+          console.log(formatTree(app, { all: opts.all }))
+        } catch (error) {
+          fail(error)
+        }
+      },
+    )
+}

package/cli/update.ts

@@ -0,0 +1,78 @@
+import type { Command } from "commander"
+import { compareVersions, release } from "./release.ts"
+
+type RegistryMetadata = Readonly<{
+  "dist-tags"?: Readonly<Record<string, string>>
+}>
+
+type Fetcher = (
+  input: string | URL | Request,
+  init?: RequestInit,
+) => Promise<Response>
+
+export function releaseSpec() {
+  return `${release.package}@${release.channel}`
+}
+
+export async function availableRelease(
+  fetcher: Fetcher = fetch,
+): Promise<string> {
+  const response = await fetcher(
+    `https://registry.npmjs.org/${encodeURIComponent(release.package)}`,
+    { headers: { Accept: "application/json" } },
+  )
+  if (!response.ok) {
+    throw new Error(
+      `Unable to check ${releaseSpec()} (${response.status} ${response.statusText}).`,
+    )
+  }
+  const metadata = (await response.json()) as RegistryMetadata
+  const version = metadata["dist-tags"]?.[release.channel]
+  if (!version) {
+    throw new Error(`${releaseSpec()} does not have a published release.`)
+  }
+  return version
+}
+
+async function installRelease(spec: string) {
+  const child = Bun.spawn([process.execPath, "add", "--global", spec], {
+    stdin: "inherit",
+    stdout: "inherit",
+    stderr: "inherit",
+  })
+  const exitCode = await child.exited
+  if (exitCode !== 0) {
+    throw new Error(`Bun could not install ${spec} (exit ${exitCode}).`)
+  }
+}
+
+export function registerUpdate(program: Command) {
+  program
+    .command("update")
+    .description(`update the PathMX CLI from the ${release.channel} channel`)
+    .option("--check", "check for an update without installing it")
+    .action(async ({ check }: { check?: boolean }) => {
+      const available = await availableRelease()
+      const comparison = compareVersions(release.version, available)
+      if (comparison >= 0) {
+        const qualifier = comparison > 0 ? "newer than" : "matches"
+        console.log(
+          `PathMX ${release.version} ${qualifier} ${releaseSpec()} (${available}).`,
+        )
+        return
+      }
+      if (check) {
+        console.log(
+          `PathMX ${available} is available on the ${release.channel} channel (installed: ${release.version}).`,
+        )
+        return
+      }
+      console.log(
+        `Updating ${release.package} ${release.version} → ${available}`,
+      )
+      await installRelease(releaseSpec())
+      console.log(
+        `PathMX ${available} installed. Run \`pathmx --version\` to verify.`,
+      )
+    })
+}

package/cli/utils.ts

@@ -0,0 +1,53 @@
+import { resolve } from "node:path"
+import type { Command } from "commander"
+import pc from "picocolors"
+import { PathMX } from "../index.ts"
+import type { SourceOpPlan } from "../ops/index.ts"
+
+export function defaultSourceRoot() {
+  return resolve(process.cwd(), "paths")
+}
+
+export function resolveRoot(explicit?: string) {
+  return explicit ? resolve(explicit) : defaultSourceRoot()
+}
+
+export function rootFromCommand(command: Command, positional?: string) {
+  const globals = command.optsWithGlobals() as {
+    root?: string
+    actions?: string
+  }
+  return {
+    root: resolveRoot(positional ?? globals.root),
+    actionsRoot: globals.actions ? resolve(globals.actions) : undefined,
+  }
+}
+
+export function loadApp(
+  root: string,
+  options: Parameters<typeof PathMX>[1] = {},
+) {
+  return PathMX(root, options)
+}
+
+export function printPlan(plan: SourceOpPlan, dryRun: boolean) {
+  if (dryRun) console.log(pc.bold("Dry run"))
+  for (const write of plan.writes) {
+    console.log(`${pc.green("write")} ${write.path}`)
+  }
+  for (const path of plan.deletes) {
+    console.log(`${pc.red("delete")} ${path}`)
+  }
+  if (!plan.writes.length && !plan.deletes.length) {
+    console.log(pc.dim("No file changes"))
+  }
+  for (const warning of plan.warnings) {
+    console.log(`${pc.yellow("warning")} ${warning}`)
+  }
+}
+
+export function fail(error: unknown): never {
+  const message = error instanceof Error ? error.message : String(error)
+  console.error(pc.red(message))
+  process.exit(1)
+}

package/core.ts

@@ -0,0 +1,96 @@
+export type { Actor, CredentialSession, UserActor } from "./authority/model.ts"
+export type {
+  BlockSummary,
+  SourceDescription,
+  SourceRelation,
+  SourceSummary,
+  SourceView,
+  View,
+  ViewIdentity,
+} from "./view/model.ts"
+export { html } from "./html.ts"
+export type {
+  ActorAdmission,
+  CredentialDirectory,
+  CredentialHost,
+  CredentialProvider,
+} from "./authority/credentials.ts"
+export {
+  anonymousCredentialHost,
+  createCredentialHost,
+} from "./authority/credentials.ts"
+export type {
+  AppContext,
+  Plugin,
+  PluginCommandContext,
+  PluginContext,
+  PluginFactory,
+  PluginLog,
+  PublishContext,
+  ServerContext,
+} from "./plugins/types.ts"
+export type { PluginPreset } from "./plugins/preset.ts"
+export { defineSchema } from "./schema/model.ts"
+export {
+  definePlugin,
+  defineViewComponent,
+  defineViewVariable,
+  route,
+} from "./plugins/types.ts"
+export { definePreset } from "./plugins/preset.ts"
+export { defineAppComponent } from "./plugins/app-component.ts"
+export type { PluginDatabase, SqlDatabase, SqlValue } from "./database.ts"
+export type {
+  MarkdownList,
+  MarkdownListItem,
+  MarkdownTask,
+  Source,
+  SourceBlock,
+} from "./source/index.ts"
+export {
+  formatFrontmatter,
+  isFenceClose,
+  markdownListItemLink,
+  matchFenceOpen,
+  splitFrontmatter,
+} from "./source/index.ts"
+export type {
+  Action,
+  ActionContext,
+  ActionAffordance,
+} from "./actions/actions.ts"
+export type {
+  ApplicationSchema,
+  BlockType,
+  BlockTypeDefinition,
+  DataProp,
+  NodeSchema,
+  NodeType,
+  QuerySchema,
+  SchemaContribution,
+  SourceType,
+  SourceTypeDefinition,
+} from "./schema/model.ts"
+export type {
+  PathMXDataSchema,
+  StandardJSONSchemaV1,
+  StandardSchemaV1,
+} from "./schema/standard.ts"
+export type {
+  BlockQueryRequest,
+  QueryDefinition,
+  QueryRequest,
+  QueryResolverContext,
+  QueryScalar,
+  QuerySort,
+  SourceQueryRequest,
+  ViewQuery,
+} from "./query/model.ts"
+export { definePattern } from "./pattern.ts"
+export { defineAction } from "./actions/actions.ts"
+export type { SourceTransaction } from "./actions/transaction.ts"
+export type { PathMXEnvironment } from "./environment.ts"
+export { createApp } from "./host/create.ts"
+export { handleRequest } from "./server/http.ts"
+export { privateResponse } from "./host/response.ts"
+export { Log } from "./log.ts"