@pathmx/core 0.5.0

package/browser-bundle.ts

@@ -0,0 +1,61 @@
+import type { BundledAsset, PathMXEnvironment } from "./environment.ts"
+import { documentAssetRank } from "./document.ts"
+
+type BrowserBundleHost = Pick<PathMXEnvironment, "bundle">
+
+type BrowserDocumentAsset =
+  | Readonly<{
+      type: "stylesheet"
+      name: string
+      text: string
+    }>
+  | Readonly<{
+      type: "script"
+      name: string
+      text: string
+      module: true
+    }>
+
+function documentAsset(
+  stem: string,
+  output: BundledAsset,
+): BrowserDocumentAsset {
+  if (output.type === "file") {
+    throw new Error(
+      `Browser bundle ${stem} emitted unsupported file asset ${output.path}.`,
+    )
+  }
+  return output.type === "style"
+    ? {
+        type: "stylesheet",
+        name: `${stem}.css`,
+        text: output.text,
+      }
+    : {
+        type: "script",
+        name: `${stem}.js`,
+        text: output.text,
+        module: true,
+      }
+}
+
+/** @internal Bundle one browser entrypoint into ordered document assets. */
+export async function browserBundleAssets(
+  host: BrowserBundleHost,
+  entrypoint: string | URL,
+  name: string,
+) {
+  const stem = name.replaceAll(":", "-")
+  const names = new Set<string>()
+  const assets = (await host.bundle(entrypoint)).map((output) => {
+    const asset = documentAsset(stem, output)
+    if (names.has(asset.name)) {
+      throw new Error(`Browser bundle ${stem} emitted duplicate ${asset.name}.`)
+    }
+    names.add(asset.name)
+    return asset
+  })
+  return assets.sort(
+    (left, right) => documentAssetRank(left) - documentAssetRank(right),
+  )
+}

package/canonical.ts

@@ -0,0 +1,41 @@
+export class CanonicalPathError extends Error {
+  constructor(value: string) {
+    super(`Invalid canonical path: ${value}`)
+    this.name = "CanonicalPathError"
+  }
+}
+
+export function canonicalPath(value: string) {
+  if (
+    !value.startsWith("/") ||
+    value.includes("\\") ||
+    value.includes("\0") ||
+    value.includes("?") ||
+    value.includes("#") ||
+    (value.length > 1 && value.endsWith("/"))
+  ) {
+    throw new CanonicalPathError(value)
+  }
+  if (value === "/") return value
+  const segments = value.slice(1).split("/")
+  if (
+    segments.some((segment) => !segment || segment === "." || segment === "..")
+  ) {
+    throw new CanonicalPathError(value)
+  }
+  return value
+}
+
+export function canonicalSourceId(value: string) {
+  const path = canonicalPath(value)
+  if (path === "/" || path.endsWith(".md")) throw new CanonicalPathError(value)
+  return path
+}
+
+export function tryCanonicalPath(value: string) {
+  try {
+    return canonicalPath(value)
+  } catch {
+    return undefined
+  }
+}

package/cli/dev.ts

@@ -0,0 +1,134 @@
+import watcher from "@parcel/watcher"
+import { fileURLToPath } from "node:url"
+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path"
+import type { Command } from "commander"
+import { defaultPluginsRoot } from "../environments/bun-plugins.ts"
+import { fail, rootFromCommand } from "./utils.ts"
+import { listenPort, startServer } from "./serve.ts"
+
+// `pmx dev` runs in two layers. Bun restarts imported server modules; the outer
+// watcher covers newly discovered and browser-only plugin files. Source edits
+// stay on the in-process sync path shared by `serve` and `dev`.
+const DEV_CHILD_ENV = "PMX_DEV_CHILD"
+
+export function registerDev(program: Command) {
+  program
+    .command("dev")
+    .description("Start the development server (hot-restarts on code changes)")
+    .argument("[root]", "source root (defaults to ./paths)")
+    .option("-p, --port <port>", "port to listen on", listenPort)
+    .action(
+      async (
+        root: string | undefined,
+        opts: { port?: number },
+        cmd: Command,
+      ) => {
+        const resolved = rootFromCommand(cmd, root)
+        if (process.env[DEV_CHILD_ENV]) {
+          try {
+            await startServer({
+              root: resolved.root,
+              actionsRoot: resolved.actionsRoot,
+              port: opts.port,
+              verbose: true,
+              mode: "dev",
+            })
+          } catch (error) {
+            // Don't exit: `bun --watch` keeps the process alive so the server
+            // can come back on the next code change instead of dying for good.
+            console.error(error)
+          }
+          return
+        }
+        try {
+          await runWatched(resolved, opts.port)
+        } catch (error) {
+          fail(error)
+        }
+      },
+    )
+}
+
+async function runWatched(
+  resolved: { root: string; actionsRoot?: string },
+  port?: number,
+) {
+  const entry = fileURLToPath(new URL("./index.ts", import.meta.url))
+  const args = [process.execPath, "--watch", entry, "dev", resolved.root]
+  if (resolved.actionsRoot) args.push("--actions", resolved.actionsRoot)
+  if (port !== undefined) args.push("--port", String(port))
+
+  const pluginsRoot = resolve(defaultPluginsRoot(resolved.root))
+  const projectRoot = dirname(pluginsRoot)
+  let child: ReturnType<typeof Bun.spawn> | undefined
+  let stopped = false
+  let requestedGeneration = 0
+  let restartTimer: ReturnType<typeof setTimeout> | undefined
+
+  const spawn = () =>
+    Bun.spawn(args, {
+      env: { ...process.env, [DEV_CHILD_ENV]: "1" },
+      stdin: "inherit",
+      stdout: "inherit",
+      stderr: "inherit",
+    })
+
+  const restart = () => {
+    requestedGeneration++
+    if (restartTimer) clearTimeout(restartTimer)
+    restartTimer = setTimeout(() => {
+      restartTimer = undefined
+      child?.kill()
+    }, 75)
+  }
+
+  const subscription = await watcher.subscribe(
+    projectRoot,
+    (error, events) => {
+      if (error) {
+        console.error(error)
+        return
+      }
+      if (events.some((event) => isPluginEvent(pluginsRoot, event.path))) {
+        restart()
+      }
+    },
+    {
+      ignore: [
+        resolve(resolved.root),
+        join(projectRoot, ".git"),
+        join(projectRoot, "node_modules"),
+      ],
+    },
+  )
+
+  for (const signal of ["SIGINT", "SIGTERM"] as const) {
+    process.on(signal, () => {
+      stopped = true
+      if (restartTimer) clearTimeout(restartTimer)
+      child?.kill(signal)
+    })
+  }
+
+  let exitCode = 0
+  while (!stopped) {
+    const generation = requestedGeneration
+    child = spawn()
+    exitCode = await child.exited
+    child = undefined
+    if (requestedGeneration === generation) break
+  }
+  await subscription.unsubscribe()
+  process.exit(exitCode)
+}
+
+function isPluginEvent(root: string, path: string) {
+  const file = relative(root, path)
+  return (
+    !!file &&
+    !isAbsolute(file) &&
+    file !== ".." &&
+    !file.startsWith(`..${sep}`) &&
+    !file.split(/[\\/]/).includes("node_modules")
+  )
+}

package/cli/export.ts

@@ -0,0 +1,74 @@
+import type { Command } from "commander"
+import { isAbsolute, relative, resolve } from "node:path"
+import { publishToDirectory } from "../environments/bun-publish.ts"
+import { PathMX } from "../index.ts"
+import { projectDirectory } from "../project.ts"
+import { createPublication } from "../publish/build.ts"
+import { fail, rootFromCommand } from "./utils.ts"
+
+function contains(parent: string, child: string) {
+  const path = relative(parent, child)
+  return path === "" || (!path.startsWith("..") && !isAbsolute(path))
+}
+
+function overlaps(left: string, right: string) {
+  return contains(left, right) || contains(right, left)
+}
+
+function outputPath(root: string, explicit?: string) {
+  const output = resolve(explicit ?? projectDirectory(root, "dist"))
+  if (overlaps(output, resolve(root))) {
+    throw new Error(
+      "Export output must not contain or be inside the paths root.",
+    )
+  }
+  return output
+}
+
+export function registerExport(program: Command) {
+  program
+    .command("export")
+    .description("Export the public application as a static publication")
+    .argument("[root]", "source root (defaults to ./paths)")
+    .requiredOption("--origin <url>", "canonical public HTTP(S) origin")
+    .option("--base-path <path>", "public mount path (defaults to /)")
+    .option("-o, --out <path>", "output directory (defaults beside paths)")
+    .action(
+      async (
+        root: string | undefined,
+        options: { origin: string; basePath?: string; out?: string },
+        command: Command,
+      ) => {
+        let app
+        let failed = false
+        let failure: unknown
+        try {
+          const resolved = rootFromCommand(command, root)
+          const output = outputPath(resolved.root, options.out)
+          const exportingApp = await PathMX(resolved.root, {
+            actionsRoot: resolved.actionsRoot,
+            diagnostics: "throw",
+            runtime: { mode: "production", target: "static" },
+          })
+          app = exportingApp
+          const manifest = await publishToDirectory(output, async (store) => {
+            const publication = await createPublication(exportingApp, {
+              origin: options.origin,
+              basePath: options.basePath,
+              store,
+            })
+            await exportingApp.close()
+            app = undefined
+            return publication
+          })
+          console.log(`Exported ${manifest.routes.length} routes to ${output}`)
+        } catch (error) {
+          failed = true
+          failure = error
+        } finally {
+          await app?.close().catch(() => undefined)
+        }
+        if (failed) fail(failure)
+      },
+    )
+}

package/cli/index.ts

@@ -0,0 +1,52 @@
+#!/usr/bin/env bun
+import { Command } from "commander"
+import { registerDev } from "./dev.ts"
+import { registerExport } from "./export.ts"
+import { registerLint } from "./lint.ts"
+import { registerMv } from "./mv.ts"
+import { registerPerms } from "./perms.ts"
+import { registerRm } from "./rm.ts"
+import { registerServe } from "./serve.ts"
+import { registerTree } from "./tree.ts"
+import { registerPluginCommands } from "./plugins.ts"
+import { registerPluginPackages } from "./plugin-packages.ts"
+import { registerQuery } from "./query.ts"
+import { checkBunVersion, release } from "./release.ts"
+import { registerUpdate } from "./update.ts"
+
+export function createProgram() {
+  const program = new Command()
+    .name("pathmx")
+    .description("Manage and serve PathMX projects")
+    .version(release.version)
+    .option("-r, --root <path>", "source root (defaults to ./paths)")
+    .option("-a, --actions <path>", "actions root")
+
+  registerServe(program)
+  registerDev(program)
+  registerExport(program)
+  registerMv(program)
+  registerRm(program)
+  registerTree(program)
+  registerPerms(program)
+  registerLint(program)
+  registerQuery(program)
+  registerPluginPackages(program)
+  registerUpdate(program)
+  return program
+}
+
+export async function runCli(argv = process.argv) {
+  checkBunVersion()
+  const program = createProgram()
+  const close = await registerPluginCommands(program, argv)
+  try {
+    await program.parseAsync(argv)
+  } finally {
+    await close()
+  }
+}
+
+if (import.meta.main) {
+  await runCli()
+}

package/cli/lint.ts

@@ -0,0 +1,164 @@
+import type { Command } from "commander"
+import pc from "picocolors"
+import type { Engine } from "../host/engine.ts"
+import { Log } from "../log.ts"
+import { SourceDiagnosticError } from "../source-diagnostic.ts"
+import { fail, loadApp, rootFromCommand } from "./utils.ts"
+
+export type UnresolvedLinkIssue = Readonly<{
+  type: "link.unresolved"
+  source: string
+  href: string
+  label?: string
+}>
+
+export type InvalidSourceIssue = Readonly<{
+  type: "source.invalid"
+  source: string
+  plugin: string
+  message: string
+}>
+
+export type LintIssue = UnresolvedLinkIssue | InvalidSourceIssue
+
+export function collectUnresolved(app: Engine) {
+  const issues: UnresolvedLinkIssue[] = []
+  for (const edge of app.graph.unresolvedLinks()) {
+    const source = app.repo.atPath(edge.from)
+    const link = source?.links.find((item) => item.href === edge.href)
+    issues.push({
+      type: "link.unresolved",
+      source: edge.from,
+      href: edge.href,
+      ...(link?.label ? { label: link.label } : {}),
+    })
+  }
+  return issues
+}
+
+function issueKey(issue: LintIssue) {
+  return issue.type === "link.unresolved"
+    ? `${issue.type}\0${issue.source}\0${issue.href}\0${issue.label ?? ""}`
+    : `${issue.type}\0${issue.source}\0${issue.plugin}\0${issue.message}`
+}
+
+function compareIssues(a: LintIssue, b: LintIssue) {
+  return (
+    a.type.localeCompare(b.type) ||
+    a.source.localeCompare(b.source) ||
+    issueKey(a).localeCompare(issueKey(b))
+  )
+}
+
+function linkText(issue: UnresolvedLinkIssue) {
+  const link = issue.label ? `[${issue.label}](${issue.href})` : issue.href
+  return `${issue.source}: ${link}`
+}
+
+export function formatLintIssues(issues: readonly LintIssue[]) {
+  if (!issues.length) return pc.green("No issues found")
+
+  const links: UnresolvedLinkIssue[] = []
+  const authoring: InvalidSourceIssue[] = []
+  for (const issue of issues) {
+    switch (issue.type) {
+      case "link.unresolved":
+        links.push(issue)
+        break
+      case "source.invalid":
+        authoring.push(issue)
+        break
+      default:
+        issue satisfies never
+    }
+  }
+  const sections: string[] = []
+  if (links.length) {
+    sections.push(
+      [
+        pc.bold(`Unresolved links (${links.length})`),
+        ...links.map(linkText),
+      ].join("\n"),
+    )
+  }
+  if (authoring.length) {
+    sections.push(
+      [
+        pc.bold(`Authoring issues (${authoring.length})`),
+        ...authoring.map((issue) => issue.message),
+      ].join("\n"),
+    )
+  }
+
+  const noun = issues.length === 1 ? "issue" : "issues"
+  sections.push(pc.red(`${issues.length} ${noun} found`))
+  return sections.join("\n\n")
+}
+
+export async function collectLintIssues(app: Engine) {
+  const issues = new Map<string, LintIssue>(
+    collectUnresolved(app).map((issue) => [issueKey(issue), issue]),
+  )
+  const addDiagnostic = (diagnostic: {
+    source: string
+    plugin: string
+    message: string
+  }) => {
+    const issue: InvalidSourceIssue = {
+      type: "source.invalid",
+      ...diagnostic,
+    }
+    issues.set(issueKey(issue), issue)
+  }
+  for (const diagnostic of app.sourceDiagnostics()) {
+    addDiagnostic(diagnostic)
+  }
+  for (const source of app.repo.all()) {
+    if (!app.isPage(source)) continue
+    try {
+      await app.compilePage(source)
+    } catch (error) {
+      if (!(error instanceof SourceDiagnosticError)) throw error
+      addDiagnostic(error.diagnostic)
+    }
+  }
+  for (const plugin of app.plugins) {
+    if (!plugin.lint) continue
+    await plugin.lint((source, message) => {
+      const normalized = message.trim()
+      if (!normalized) {
+        throw new Error(`Plugin ${plugin.id} reported an empty lint message.`)
+      }
+      addDiagnostic({
+        source: source.path,
+        plugin: plugin.id,
+        message: normalized,
+      })
+    }, app.appContext(plugin.id))
+  }
+  return [...issues.values()].sort(compareIssues)
+}
+
+export function registerLint(program: Command) {
+  program
+    .command("lint")
+    .description("Validate authored Sources without starting a server")
+    .argument("[root]", "source root (defaults to ./paths)")
+    .action(async (root: string | undefined, _opts: unknown, cmd: Command) => {
+      try {
+        const resolved = rootFromCommand(cmd, root)
+        const app = await loadApp(resolved.root, {
+          actionsRoot: resolved.actionsRoot,
+          buildCache: false,
+          diagnostics: "collect",
+          log: new Log({ sink() {} }),
+        })
+        const issues = await collectLintIssues(app)
+        console.log(formatLintIssues(issues))
+        if (!issues.length) return
+        process.exitCode = 1
+      } catch (error) {
+        fail(error)
+      }
+    })
+}

package/cli/mv.ts

@@ -0,0 +1,30 @@
+import type { Command } from "commander"
+import { applySourceOpPlan, moveSource } from "../ops/index.ts"
+import { fail, loadApp, printPlan, rootFromCommand } from "./utils.ts"
+
+export function registerMv(program: Command) {
+  program
+    .command("mv")
+    .description("Move a source and rewrite linked references")
+    .argument("<old-path>", "existing source path")
+    .argument("<new-path>", "destination markdown path")
+    .option("--dry-run", "print the plan without writing")
+    .action(
+      async (
+        oldPath: string,
+        newPath: string,
+        opts: { dryRun?: boolean },
+        cmd: Command,
+      ) => {
+        try {
+          const { root, actionsRoot } = rootFromCommand(cmd)
+          const app = await loadApp(root, { actionsRoot, buildCache: false })
+          const plan = await moveSource(app, oldPath, newPath)
+          printPlan(plan, Boolean(opts.dryRun))
+          if (!opts.dryRun) await applySourceOpPlan(app, plan)
+        } catch (error) {
+          fail(error)
+        }
+      },
+    )
+}