@pathmx/core 0.5.0

package/ops/href.ts

@@ -0,0 +1,87 @@
+import { posixPath } from "../path.ts"
+import { publicPath } from "../server/router.ts"
+import type { Source } from "../source/index.ts"
+
+export function splitHref(href: string) {
+  const hash = href.indexOf("#")
+  const withoutHash = hash === -1 ? href : href.slice(0, hash)
+  const query = withoutHash.indexOf("?")
+  return {
+    pathname: query === -1 ? withoutHash : withoutHash.slice(0, query),
+    query: query === -1 ? "" : withoutHash.slice(query),
+    fragment: hash === -1 ? "" : href.slice(hash),
+  }
+}
+
+export function joinHref(pathname: string, query: string, fragment: string) {
+  return `${pathname}${query}${fragment}`
+}
+
+export function isRelativeHref(pathname: string) {
+  return (
+    Boolean(pathname) && !pathname.startsWith("/") && !pathname.startsWith("~")
+  )
+}
+
+export function authoredId(source: Source) {
+  const id = source.data.id
+  return typeof id === "string" && id.trim() ? id.trim() : undefined
+}
+
+export function isAuthoredIdHref(pathname: string, source: Source) {
+  const id = authoredId(source)
+  return Boolean(id && (pathname === id || pathname === `/${id}`))
+}
+
+export function relativeHref(
+  fromPath: string,
+  targetPath: string,
+  originalHref: string,
+) {
+  const fromDir = posixPath.dirname(fromPath)
+  let rel = posixPath.relative(fromDir, targetPath)
+  if (!rel) rel = posixPath.basename(targetPath)
+  if (
+    (originalHref.startsWith("./") &&
+      !rel.startsWith("../") &&
+      !rel.startsWith("/")) ||
+    (!rel.startsWith(".") && !rel.startsWith("/"))
+  ) {
+    rel = `./${rel}`
+  }
+  return rel
+}
+
+export function rebaseRelativeHref(
+  href: string,
+  oldDir: string,
+  newDir: string,
+) {
+  const { pathname, query, fragment } = splitHref(href)
+  if (!isRelativeHref(pathname)) return href
+  const oldTarget = posixPath.normalize(posixPath.join(oldDir, pathname))
+  return joinHref(
+    relativeHref(posixPath.join(newDir, "_"), oldTarget, href),
+    query,
+    fragment,
+  )
+}
+
+export function retargetHref(
+  href: string,
+  fromPath: string,
+  oldSource: Source,
+  newSource: Source,
+): string | undefined {
+  const { pathname, query, fragment } = splitHref(href)
+  if (!pathname) return
+  if (isAuthoredIdHref(pathname, oldSource)) return
+
+  const explicitMd = pathname.endsWith(".md")
+  const target = explicitMd ? newSource.path : publicPath(newSource)
+  const absTarget = target.startsWith("/") ? target : `/${target}`
+  const next = isRelativeHref(pathname)
+    ? relativeHref(fromPath, absTarget, href)
+    : target
+  return joinHref(next, query, fragment)
+}

package/ops/index.ts

@@ -0,0 +1,9 @@
+export {
+  applySourceOpPlan,
+  emptyPlan,
+  SourceOpError,
+  type SourceOpPlan,
+  type SourceOpWrite,
+} from "./plan.ts"
+export { moveSource } from "./move-source.ts"
+export { removeSource } from "./remove-source.ts"

package/ops/move-source.ts

@@ -0,0 +1,114 @@
+import type { Engine } from "../host/engine.ts"
+import { posixPath } from "../path.ts"
+import { isIndexSource, publicPath } from "../server/router.ts"
+import { createSource, rewriteLinks, type Source } from "../source/index.ts"
+import {
+  authoredId,
+  isRelativeHref,
+  rebaseRelativeHref,
+  retargetHref,
+  splitHref,
+} from "./href.ts"
+import { emptyPlan, SourceOpError, type SourceOpPlan } from "./plan.ts"
+
+function resolveExisting(app: Engine, input: string): Source {
+  const graphPath = app.repo.graphPath(input)
+  const source =
+    app.repo.atPath(graphPath) ??
+    app.repo.get(input) ??
+    app.repo.get(app.repo.pathToId(graphPath))
+  if (!source) throw new SourceOpError(`Source not found: ${input}`)
+  if (!source.path.endsWith(".md")) {
+    throw new SourceOpError(`Only markdown sources can be moved: ${input}`)
+  }
+  return source
+}
+
+async function resolveDest(app: Engine, input: string) {
+  const path = app.repo.graphPath(input)
+  if (!path.endsWith(".md")) {
+    throw new SourceOpError(`Destination must be a markdown path: ${input}`)
+  }
+  const storagePath = app.repo.storagePath(path)
+  if (!storagePath)
+    throw new SourceOpError(`Destination escapes the source root: ${input}`)
+  if (
+    app.repo.atPath(path) ||
+    (await app.environment.storage.exists(storagePath))
+  ) {
+    throw new SourceOpError(`Destination already exists: ${path}`)
+  }
+  return path
+}
+
+function referrerPath(from: string) {
+  const hash = from.indexOf("#")
+  return hash === -1 ? from : from.slice(0, hash)
+}
+
+export async function moveSource(
+  app: Engine,
+  from: string,
+  to: string,
+): Promise<SourceOpPlan> {
+  const source = resolveExisting(app, from)
+  const dest = await resolveDest(app, to)
+  if (posixPath.normalize(source.path) === posixPath.normalize(dest)) {
+    throw new SourceOpError(`Source and destination are the same path: ${dest}`)
+  }
+
+  const preview = createSource(dest, source.content, app.environment.yaml)
+  const oldDir = posixPath.dirname(source.path)
+  const newDir = posixPath.dirname(dest)
+  const selfHrefs = new Set(
+    app.graph
+      .linksFrom(source.path)
+      .filter((edge) => edge.to === source.path)
+      .map((edge) => edge.href),
+  )
+
+  const movedContent = rewriteLinks(source.content, (href) => {
+    if (selfHrefs.has(href)) return retargetHref(href, dest, source, preview)
+    const { pathname } = splitHref(href)
+    if (isRelativeHref(pathname))
+      return rebaseRelativeHref(href, oldDir, newDir)
+  })
+
+  const plan = emptyPlan()
+  plan.writes.push({ path: dest, content: movedContent })
+  plan.deletes.push(source.path)
+
+  const inbound = app.graph.linksTo(source.path)
+  const byFile = new Map<string, Set<string>>()
+  for (const edge of inbound) {
+    const file = referrerPath(edge.from)
+    if (file === source.path) continue
+    const hrefs = byFile.get(file) ?? new Set()
+    hrefs.add(edge.href)
+    byFile.set(file, hrefs)
+  }
+
+  for (const [file, hrefs] of byFile) {
+    const referrer = app.repo.atPath(file)
+    if (!referrer) continue
+    const next = rewriteLinks(referrer.content, (href) => {
+      if (!hrefs.has(href)) return
+      return retargetHref(href, file, source, preview)
+    })
+    if (next !== referrer.content)
+      plan.writes.push({ path: file, content: next })
+  }
+
+  if (isIndexSource(source)) {
+    plan.warnings.push(
+      `Moving index source ${source.path} changes the directory route ${publicPath(source)}`,
+    )
+  }
+  if (!authoredId(source) && source.id !== preview.id) {
+    plan.warnings.push(
+      `Moving ${source.path} changes its public URL from ${source.id} to ${preview.id}`,
+    )
+  }
+
+  return plan
+}

package/ops/plan.ts

@@ -0,0 +1,47 @@
+import type { Engine } from "../host/engine.ts"
+import type { SourceChange } from "../repository.ts"
+
+export type SourceOpWrite = {
+  path: string
+  content: string
+}
+
+export type SourceOpPlan = {
+  writes: SourceOpWrite[]
+  deletes: string[]
+  warnings: string[]
+}
+
+export class SourceOpError extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = "SourceOpError"
+  }
+}
+
+export function emptyPlan(): SourceOpPlan {
+  return { writes: [], deletes: [], warnings: [] }
+}
+
+export async function applySourceOpPlan(app: Engine, plan: SourceOpPlan) {
+  const changes: SourceChange[] = []
+  for (const path of plan.deletes) {
+    const graphPath = app.repo.graphPath(path)
+    if (!app.repo.storagePath(graphPath)) {
+      throw new SourceOpError(`Path escapes repository: ${path}`)
+    }
+    changes.push({ type: "delete", path: graphPath })
+  }
+  for (const write of plan.writes) {
+    const path = app.repo.graphPath(write.path)
+    if (!app.repo.storagePath(path)) {
+      throw new SourceOpError(`Path escapes repository: ${write.path}`)
+    }
+    changes.push({
+      type: app.repo.atPath(path) ? "replace" : "create",
+      path,
+      content: write.content,
+    })
+  }
+  if (changes.length) await app.commit({ changes })
+}

package/ops/remove-source.ts

@@ -0,0 +1,70 @@
+import type { Engine } from "../host/engine.ts"
+import { isIndexSource, publicPath } from "../server/router.ts"
+import { unlinkLinks, type Source } from "../source/index.ts"
+import { emptyPlan, SourceOpError, type SourceOpPlan } from "./plan.ts"
+
+function resolveExisting(app: Engine, input: string): Source {
+  const graphPath = app.repo.graphPath(input)
+  const source =
+    app.repo.atPath(graphPath) ??
+    app.repo.get(input) ??
+    app.repo.get(app.repo.pathToId(graphPath))
+  if (!source) throw new SourceOpError(`Source not found: ${input}`)
+  if (!source.path.endsWith(".md")) {
+    throw new SourceOpError(`Only markdown sources can be removed: ${input}`)
+  }
+  return source
+}
+
+function referrerPath(from: string) {
+  const hash = from.indexOf("#")
+  return hash === -1 ? from : from.slice(0, hash)
+}
+
+export async function removeSource(
+  app: Engine,
+  path: string,
+): Promise<SourceOpPlan> {
+  const source = resolveExisting(app, path)
+  const inbound = app.graph.linksTo(source.path)
+  const byFile = new Map<string, Set<string>>()
+  let blockTargets = 0
+
+  for (const edge of inbound) {
+    const file = referrerPath(edge.from)
+    if (file === source.path) continue
+    const hrefs = byFile.get(file) ?? new Set()
+    hrefs.add(edge.href)
+    byFile.set(file, hrefs)
+    if (
+      edge.fragment &&
+      source.blocks.some((block) => block.id === edge.fragment)
+    ) {
+      blockTargets++
+    }
+  }
+
+  const plan = emptyPlan()
+  plan.deletes.push(source.path)
+
+  for (const [file, hrefs] of byFile) {
+    const referrer = app.repo.atPath(file)
+    if (!referrer) continue
+    const next = unlinkLinks(referrer.content, (href) => hrefs.has(href))
+    if (next !== referrer.content)
+      plan.writes.push({ path: file, content: next })
+  }
+
+  if (isIndexSource(source)) {
+    plan.warnings.push(
+      `Removing index source ${source.path} will 404 the directory route ${publicPath(source)}`,
+    )
+  }
+  if (blockTargets) {
+    plan.warnings.push(
+      `Removing ${source.path} unlinks ${blockTargets} block target${blockTargets === 1 ? "" : "s"}`,
+    )
+  }
+
+  return plan
+}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@pathmx/core",
+  "description": "A minimal, plugin-first framework for Paths and learning applications.",
+  "version": "0.5.0",
+  "license": "SEE LICENSE IN LICENSE.md",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pathmx/pathmx-beta.git",
+    "directory": "pathmx/core"
+  },
+  "homepage": "https://github.com/pathmx/pathmx-beta#readme",
+  "bugs": "https://github.com/pathmx/pathmx-beta/issues",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/",
+    "tag": "beta"
+  },
+  "type": "module",
+  "types": "./core.ts",
+  "module": "./core.ts",
+  "bin": {
+    "pathmx": "dist/pathmx.js",
+    "pmx": "dist/pathmx.js"
+  },
+  "exports": {
+    ".": "./core.ts",
+    "./bun": "./index.ts",
+    "./publish": "./publish/index.ts",
+    "./plugins": "./plugins/index.ts"
+  },
+  "engines": {
+    "bun": ">=1.4.0"
+  },
+  "pathmxRelease": {
+    "channel": "beta",
+    "testedBun": "1.4.0"
+  },
+  "dependencies": {
+    "@parcel/watcher": "^2.6.0",
+    "commander": "^15.0.0",
+    "highlight.js": "^11.12.0",
+    "morphdom": "^2.7.8",
+    "picocolors": "^1.1.1",
+    "temml": "^0.13.4"
+  }
+}

package/path.ts

@@ -0,0 +1,75 @@
+function parts(value: string) {
+  return value.split("/").filter(Boolean)
+}
+
+function normalize(value: string) {
+  if (!value) return "."
+  const absolute = value.startsWith("/")
+  const stack: string[] = []
+  for (const part of value.split("/")) {
+    if (!part || part === ".") continue
+    if (part === "..") {
+      if (stack.length && stack.at(-1) !== "..") stack.pop()
+      else if (!absolute) stack.push(part)
+    } else {
+      stack.push(part)
+    }
+  }
+  const normalized = `${absolute ? "/" : ""}${stack.join("/")}`
+  return normalized || (absolute ? "/" : ".")
+}
+
+function join(...values: string[]) {
+  return normalize(values.filter(Boolean).join("/"))
+}
+
+function dirname(value: string) {
+  const normalized = normalize(value)
+  if (normalized === "/" || normalized === ".") return normalized
+  const index = normalized.lastIndexOf("/")
+  if (index === -1) return "."
+  return index === 0 ? "/" : normalized.slice(0, index)
+}
+
+function basename(value: string) {
+  const normalized = normalize(value)
+  if (normalized === "/" || normalized === ".") return normalized
+  return normalized.slice(normalized.lastIndexOf("/") + 1)
+}
+
+function relative(from: string, to: string) {
+  const source = parts(normalize(from))
+  const target = parts(normalize(to))
+  let shared = 0
+  while (
+    shared < source.length &&
+    shared < target.length &&
+    source[shared] === target[shared]
+  ) {
+    shared++
+  }
+  return [
+    ...Array.from({ length: source.length - shared }, () => ".."),
+    ...target.slice(shared),
+  ].join("/")
+}
+
+function extname(value: string) {
+  const name = basename(value)
+  const index = name.lastIndexOf(".")
+  return index > 0 ? name.slice(index) : ""
+}
+
+function resolve(base: string, target: string) {
+  return normalize(target.startsWith("/") ? target : join(base, target))
+}
+
+export const posixPath = {
+  basename,
+  dirname,
+  extname,
+  join,
+  normalize,
+  relative,
+  resolve,
+}