@pathmx/core 0.5.0

package/LICENSE.md

@@ -0,0 +1,172 @@
+# PathMX Proprietary Beta License
+
+Version 0.1 — July 21, 2026
+
+Copyright © 2026 DUO Interactive, LLC.
+All rights reserved.
+
+This license governs the first-party PathMX software distributed in the npm
+package `@pathmx/core`, including its command-line interface, bundled
+library surfaces, runtime and Player components, and accompanying
+documentation (the “Software”). DUO Interactive, LLC is the “Licensor.” This
+license does not cover the private PathMX source-code repository or separately
+identified third-party materials.
+
+“Project” means Paths, Sources, responses, data, and other content authored or
+processed with the Software.
+
+“Application” means software or a service created by you in which the Software
+supports product-specific functionality but is not itself offered as a
+general-purpose PathMX product.
+
+“Redistributable Components” means runtime, Player, or library portions of the
+Software incorporated into a Project, Application, or generated output through
+ordinary use of the Software or ordinary compilation and bundling tools.
+
+“Authorized Users” means your employees and individual contractors who use the
+Software on your behalf, and your hosting, continuous-integration, and other
+service providers that possess or run necessary copies solely to provide
+services to you.
+
+## 1. Agreement
+
+By installing, accessing, or using the Software, you agree to this license. If
+you use the Software on behalf of an organization, you represent that you have
+authority to accept this license for that organization. If you do not agree,
+do not install or use the Software.
+
+## 2. License grant
+
+Subject to this license, the Licensor grants you a non-exclusive, worldwide,
+royalty-free, non-transferable, and non-sublicensable license, perpetual for
+the version of the Software to which it applies unless terminated under
+Section 10, to:
+
+- install, execute, and use the Software for personal, educational,
+  internal-business, or commercial purposes;
+- use the Software to author, integrate, build, test, serve, play, host, and
+  operate Projects and Applications;
+- import, compile, bundle, configure, and integrate the Software through its
+  documented library and command-line interfaces;
+- create and distribute independent Projects, Applications, plugins, and
+  integrations that use those interfaces without modifying the Software
+  itself; and
+- make copies reasonably necessary for local development, testing, continuous
+  integration, backup, and hosted production environments.
+
+Your Authorized Users may exercise those rights solely on your behalf. You are
+responsible for their compliance with this license.
+
+You may reproduce and distribute Redistributable Components only as
+incorporated into your Project, Application, or generated output, and only when
+you preserve applicable license and proprietary notices. You may host and
+commercially provide access to that Project, Application, or output. You may
+not distribute Redistributable Components as a standalone package or as a
+general-purpose substitute for the Software.
+
+Each lawful recipient of a Redistributable Component may execute and use that
+component, display its output, and make technically necessary transitory copies
+solely as incorporated into the Project, Application, or output in which they
+received it. This limited recipient permission does not include a right to
+extract, modify, or redistribute the component separately.
+
+## 3. Restrictions
+
+Except where applicable law does not allow the restriction, you may not:
+
+- modify, adapt, translate, or create derivative works of the Software, except
+  for the compilation, bundling, configuration, and integration expressly
+  permitted in Section 2;
+- redistribute, sublicense, sell, lease, or otherwise provide the Software to
+  another person as a standalone package, product, or service except to an
+  Authorized User or as a Redistributable Component under Section 2;
+- resell, rebrand, or provide the Software as a hosted or managed service that
+  gives third parties general-purpose access to substantial PathMX authoring,
+  building, serving, Player-administration, or library functionality for their
+  own unrelated projects;
+- reverse engineer, decompile, disassemble, or otherwise attempt to derive the
+  source code of the Software; or
+- remove or alter copyright, license, trademark, or other proprietary notices.
+
+For clarity, the managed-service restriction does not prohibit a hosted
+Project or Application in which PathMX supports the licensee's own
+product-specific experience and is not itself the general-purpose product
+offered to customers.
+
+## 4. Your content
+
+As between you and the Licensor, you retain ownership of the Paths, Sources,
+responses, data, independent application code, and other content that you
+author or provide while using the Software. You are responsible for that
+content and for having the rights needed to use it.
+
+Generated output may contain Redistributable Components or third-party
+materials. Your ownership of your content does not change the ownership or
+license terms of those components and materials.
+
+## 5. Ownership and trademarks
+
+The Software is licensed, not sold. The Licensor and its suppliers retain all
+rights in the Software not expressly granted by this license. This license
+does not grant permission to use the PathMX name, logos, or other marks except
+as reasonably necessary to identify the Software accurately.
+
+## 6. Beta status and changes
+
+The Software is a proprietary beta release. Its APIs, behavior, file formats,
+and features may change or be removed without notice. The Licensor has no
+obligation to provide support, maintenance, updates, continued availability,
+or backward compatibility. A later version may be offered under different
+license terms, including an open-source license. Different terms for a later
+version do not change the license previously granted for an earlier version.
+
+## 7. Third-party materials
+
+The Software and Redistributable Components may include or depend on
+third-party materials governed by their own license terms. Those terms control
+for the applicable third-party materials. You must preserve third-party notices
+when the applicable third-party terms require it.
+
+## 8. Disclaimer of warranties
+
+TO THE MAXIMUM EXTENT PERMITTED BY LAW, THE SOFTWARE IS PROVIDED “AS IS” AND
+“AS AVAILABLE,” WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, EXPRESS,
+IMPLIED, OR STATUTORY, INCLUDING WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
+PARTICULAR PURPOSE, TITLE, NON-INFRINGEMENT, OR THAT THE SOFTWARE WILL BE
+SECURE, ERROR-FREE, OR UNINTERRUPTED.
+
+## 9. Limitation of liability
+
+TO THE MAXIMUM EXTENT PERMITTED BY LAW, THE LICENSOR AND ITS CONTRIBUTORS,
+SUPPLIERS, AND AFFILIATES WILL NOT BE LIABLE FOR ANY INDIRECT, INCIDENTAL,
+SPECIAL, CONSEQUENTIAL, EXEMPLARY, OR PUNITIVE DAMAGES, OR FOR LOSS OF DATA,
+PROFITS, REVENUE, GOODWILL, OR BUSINESS OPPORTUNITY, ARISING FROM OR RELATED TO
+THE SOFTWARE OR THIS LICENSE, EVEN IF ADVISED OF THE POSSIBILITY OF THOSE
+DAMAGES.
+
+TO THE MAXIMUM EXTENT PERMITTED BY LAW, THEIR TOTAL LIABILITY FOR ALL CLAIMS
+ARISING FROM OR RELATED TO THE SOFTWARE OR THIS LICENSE WILL NOT EXCEED THE
+GREATER OF THE AMOUNT YOU PAID FOR THE SOFTWARE DURING THE TWELVE MONTHS BEFORE
+THE EVENT GIVING RISE TO THE CLAIM OR US$100.
+
+## 10. Termination
+
+This license terminates if you materially breach it and do not cure the breach
+within thirty days after receiving written notice from the Licensor. On
+termination, you and your Authorized Users must stop using and delete your
+copies of the Software. Sections 4, 5, 8, 9, 10, and 11 survive termination.
+Termination does not withdraw the limited permission already granted by
+Section 2 to lawful recipients of Redistributable Components distributed
+before termination.
+
+## 11. General
+
+If a provision of this license is unenforceable, it will be modified only to
+the minimum extent necessary to make it enforceable, and the remaining
+provisions will continue in effect. Failure to enforce a provision is not a
+waiver. You may not assign or transfer this license without the Licensor's
+written consent. The Licensor may assign this license together with ownership
+of the Software to a successor owner. This license binds and benefits the
+permitted successors and assigns of you and the Licensor. This license is the
+entire agreement concerning the Software unless you and the Licensor have
+signed a separate agreement that expressly replaces it.

package/README.md

@@ -0,0 +1,111 @@
+# PathMX Beta
+
+PathMX is a minimal, plugin-first framework for building Paths and learning
+applications. This package includes the Bun-first CLI, portable core contracts,
+default Plugins, server adapter, and static publication API.
+
+The package root is runtime-neutral. Bun applications use the `/bun` entrypoint
+for the `PathMX()` convenience composition and Bun environment.
+
+This is an early beta. APIs and behavior may change between `0.x` releases;
+pin an exact version and review the release notes before upgrading.
+
+## Install
+
+```sh
+bun add --exact @pathmx/core@beta
+```
+
+PathMX currently requires Bun 1.4.0 or newer and recommends the Bun version used
+to test each release. Install the CLI globally when you want the `pathmx` and
+`pmx` commands everywhere:
+
+```sh
+bun add --global @pathmx/core@beta
+pathmx --help
+pathmx update
+```
+
+`pmx` is an alias for `pathmx`.
+
+## Create an application
+
+```ts
+import { PathMX, handleRequest } from "@pathmx/core/bun"
+
+const app = await PathMX({ root: "./paths" })
+
+Bun.serve({
+  fetch: (request) => handleRequest(app, request),
+})
+```
+
+`PathMX()` supplies the Bun environment and default Plugin set. Portable hosts
+can compose the smaller core API explicitly:
+
+```ts
+import { createApp } from "@pathmx/core"
+import { bunEnvironment } from "@pathmx/core/bun"
+import { defaultPlugins } from "@pathmx/core/plugins"
+
+const app = await createApp({
+  root: "./paths",
+  environment: bunEnvironment,
+  plugins: defaultPlugins,
+})
+```
+
+Official packages follow the CLI's release channel:
+
+```sh
+pathmx plugins add mermaid react
+pathmx plugins list
+pathmx plugins update
+```
+
+## Image directives
+
+The default Image Plugin compiles portable image roles from normal Markdown:
+
+```md
+![@image.fit Diagram](./diagram.png)
+![@image.fill Photo](./photo.jpg)
+![@image.background Hero](./hero.jpg)
+![@image.background.fit Diagram backdrop](./diagram.png)
+```
+
+The directive is removed from the rendered alt text. Background images render
+behind their containing Block in ordinary documents, while experiences such as
+Player can reuse the same role and fit metadata for their own layouts.
+
+## Block layouts
+
+The default Block Layout Plugin compiles reusable composition from Block
+topmatter. The same server-rendered metadata works in ordinary pages, static
+exports, Focus mode, and Slides mode:
+
+```md
+<!--
+layout: media-end
+-->
+
+# A diagram and explanation
+
+![System diagram](./diagram.png)
+```
+
+The built-in layouts are `center`, `media-start`, and `media-end`. Media
+layouts preserve Markdown reading order, use logical start/end placement, and
+collapse to one column on narrow screens. Lowercase custom slugs remain open
+for repository CSS, such as `layout: course-timeline`.
+
+## Package channels
+
+- `@fellowhumans/pathmx@latest` remains the previous PathMX implementation
+  during the transition and is not part of this release train.
+- `@pathmx/core@beta` is this minimal implementation.
+- `@pathmx/core@latest` will become the stable channel after the beta.
+- Published versions are immutable. The `beta` tag advances only after the
+  release preflight passes.
+
+PathMX is distributed under the [PathMX Proprietary Beta License](./LICENSE.md).

package/actions/actions.ts

@@ -0,0 +1,307 @@
+import type { Engine } from "../host/engine.ts"
+import type { SourceCapability } from "../authority/access.ts"
+import type { PathMXYaml } from "../environment.ts"
+import type { Source } from "../source/index.ts"
+import {
+  formatSchemaIssues,
+  isStandardSchema,
+  standardJsonSchema,
+  type StandardSchemaV1,
+} from "../schema/standard.ts"
+import type { Principal, UserActor } from "../authority/model.ts"
+import { projectDirectory } from "../project.ts"
+import { type SourceTransaction, createTransaction } from "./transaction.ts"
+
+export function defaultActionsRoot(pathsRoot: string) {
+  return projectDirectory(pathsRoot, "actions")
+}
+
+export type ActionInput = Record<string, string | string[]>
+
+type ActionResult = unknown
+
+export type ActionViewContext = Readonly<{
+  principal: Principal
+  target: Source
+  yaml: PathMXYaml
+  can(capability: SourceCapability): boolean
+}>
+
+export type ActionAvailability =
+  | boolean
+  | string
+  | Readonly<{
+      rel?: string
+      title?: string
+      description?: string
+      status?: "available" | "unavailable"
+      reason?: string
+      boundInput?: Readonly<Record<string, unknown>>
+    }>
+
+export type ActionOptions<
+  S extends StandardSchemaV1 = StandardSchemaV1<unknown, ActionInput>,
+  O extends StandardSchemaV1 | undefined = undefined,
+> = Readonly<{
+  title: string
+  description?: string
+  input?: S
+  output?: O
+  affordance?: (
+    context: ActionViewContext,
+  ) => ActionAvailability | Promise<ActionAvailability>
+  authorize?: (
+    context: ActionContext,
+  ) => boolean | string | Promise<boolean | string>
+  execute(
+    input: StandardSchemaV1.InferOutput<S>,
+    context: ActionContext,
+  ): ActionResult | Promise<ActionResult>
+}>
+
+export type Action<
+  S extends StandardSchemaV1 = StandardSchemaV1<unknown, ActionInput>,
+  O extends StandardSchemaV1 | undefined = undefined,
+> = ((
+  input: StandardSchemaV1.InferOutput<S>,
+  context: ActionContext,
+) => ActionResult | Promise<ActionResult>) &
+  Readonly<{
+    title?: string
+    description?: string
+    input?: S
+    output?: O
+    affordance?: ActionOptions<S, O>["affordance"]
+    authorize?: ActionOptions<S, O>["authorize"]
+  }>
+
+/** An Action whose schema-specific input type is intentionally erased for registration. */
+export type ActionContribution = ((
+  input: never,
+  context: ActionContext,
+) => ActionResult | Promise<ActionResult>) &
+  Readonly<{
+    title?: string
+    description?: string
+    input?: StandardSchemaV1
+    output?: StandardSchemaV1
+    affordance?: ActionOptions["affordance"]
+    authorize?: ActionOptions["authorize"]
+  }>
+
+export type ActionContext = {
+  actor: UserActor
+  tx: SourceTransaction
+  target?: Source
+  yaml: PathMXYaml
+}
+
+export type ActionAffordance = Readonly<{
+  type: "action"
+  id: string
+  rel: string
+  title: string
+  description?: string
+  method: "post"
+  href: string
+  target: Readonly<{ type: "source"; id: string }>
+  input?: Readonly<Record<string, unknown>>
+  output?: Readonly<Record<string, unknown>>
+  boundInput?: Readonly<Record<string, unknown>>
+  status: "available" | "unavailable"
+  reason?: string
+}>
+
+export class ActionNotFoundError extends Error {
+  constructor(name: string) {
+    super(`Action not found: ${name}`)
+    this.name = "ActionNotFoundError"
+  }
+}
+
+export class ActionValidationError extends Error {
+  readonly issues: ReadonlyArray<StandardSchemaV1.Issue>
+
+  constructor(issues: ReadonlyArray<StandardSchemaV1.Issue>) {
+    super(formatSchemaIssues(issues))
+    this.name = "ActionValidationError"
+    this.issues = issues
+  }
+}
+
+export class ActionUnavailableError extends Error {
+  constructor(name: string, reason?: string) {
+    super(reason ?? `Action unavailable: ${name}`)
+    this.name = "ActionUnavailableError"
+  }
+}
+
+export function defineAction<S extends StandardSchemaV1>(
+  input: S,
+  execute: Action<S>,
+): Action<S> & { input: S }
+export function defineAction<
+  S extends StandardSchemaV1 = StandardSchemaV1<unknown, ActionInput>,
+  O extends StandardSchemaV1 | undefined = undefined,
+>(options: ActionOptions<S, O>): Action<S, O>
+export function defineAction<
+  S extends StandardSchemaV1 = StandardSchemaV1<unknown, ActionInput>,
+  O extends StandardSchemaV1 | undefined = undefined,
+>(
+  inputOrOptions: S | ActionOptions<S, O>,
+  legacyExecute?: Action<S>,
+): Action<S, O> {
+  if (legacyExecute)
+    return Object.assign(legacyExecute, { input: inputOrOptions as S })
+  const options = inputOrOptions as ActionOptions<S, O>
+  return Object.assign(options.execute, {
+    title: options.title,
+    ...(options.description ? { description: options.description } : {}),
+    ...(options.input ? { input: options.input } : {}),
+    ...(options.output ? { output: options.output } : {}),
+    ...(options.affordance ? { affordance: options.affordance } : {}),
+    ...(options.authorize ? { authorize: options.authorize } : {}),
+  })
+}
+
+function availability(
+  value: ActionAvailability,
+): Exclude<ActionAvailability, boolean | string> | undefined {
+  if (value === false) return
+  if (value === true) return {}
+  if (typeof value === "string") {
+    return { status: "unavailable", reason: value }
+  }
+  return value
+}
+
+async function resolveAvailability(
+  action: ActionContribution,
+  context: ActionViewContext,
+) {
+  if (!action.affordance) {
+    return Object.freeze({ declared: false, description: undefined })
+  }
+  return Object.freeze({
+    declared: true,
+    description: availability(await action.affordance(context)),
+  })
+}
+
+export async function describeAction(
+  name: string,
+  action: ActionContribution,
+  context: ActionViewContext,
+): Promise<ActionAffordance | undefined> {
+  if (!action.title || !action.affordance) return
+  const { description: described } = await resolveAvailability(action, context)
+  if (!described) return
+  const input = standardJsonSchema(action.input, "input")
+  const output = standardJsonSchema(action.output, "output")
+  return Object.freeze({
+    type: "action",
+    id: name,
+    rel: described.rel ?? name,
+    title: described.title ?? action.title,
+    ...((described.description ?? action.description)
+      ? { description: described.description ?? action.description }
+      : {}),
+    method: "post",
+    href: `/actions/${name}`,
+    target: Object.freeze({ type: "source", id: context.target.id }),
+    ...(input ? { input } : {}),
+    ...(output ? { output } : {}),
+    ...(described.boundInput
+      ? { boundInput: Object.freeze({ ...described.boundInput }) }
+      : {}),
+    status: described.status ?? "available",
+    ...(described.reason ? { reason: described.reason } : {}),
+  })
+}
+
+export async function parseActionInput<S extends StandardSchemaV1>(
+  schema: S,
+  data: unknown,
+): Promise<StandardSchemaV1.InferOutput<S>> {
+  let result = schema["~standard"].validate(data)
+  if (result instanceof Promise) result = await result
+  if (result.issues) throw new ActionValidationError(result.issues)
+  return result.value
+}
+
+export async function dispatchAction(
+  engine: Engine,
+  name: string,
+  input: ActionInput,
+  actor: UserActor,
+  target?: Source,
+) {
+  const action =
+    engine.pluginAction(name) ?? (await loadAuthoredAction(engine, name))
+
+  engine.log.info("action", {
+    name,
+    actor: actor.id,
+    target: target?.id,
+  })
+  let value: ActionResult = undefined
+  const commit = await engine.commitPrepared(async () => {
+    const currentTarget = target ? engine.repo.atPath(target.path) : undefined
+    if (target && !currentTarget) throw new ActionUnavailableError(name)
+    let boundInput: Readonly<Record<string, unknown>> | undefined
+    if (currentTarget) {
+      const principal = { type: "actor" as const, actor }
+      if (!engine.hasSourceCapability(principal, currentTarget, "execute")) {
+        throw new ActionUnavailableError(name)
+      }
+      const resolved = await resolveAvailability(action, {
+        principal,
+        target: currentTarget,
+        yaml: engine.environment.yaml,
+        can: (capability) =>
+          engine.hasSourceCapability(principal, currentTarget, capability),
+      })
+      if (resolved.declared && !resolved.description) {
+        throw new ActionUnavailableError(name)
+      }
+      if (resolved.description?.status === "unavailable") {
+        throw new ActionUnavailableError(name, resolved.description.reason)
+      }
+      boundInput = resolved.description?.boundInput
+    }
+    const submitted = { ...input, ...(boundInput ?? {}) }
+    const parsed = isStandardSchema(action.input)
+      ? await parseActionInput(action.input, submitted)
+      : submitted
+    const tx = createTransaction(engine, actor)
+    const context = {
+      actor,
+      tx,
+      target: currentTarget,
+      yaml: engine.environment.yaml,
+    }
+    const authorized = await action.authorize?.(context)
+    if (authorized === false || typeof authorized === "string") {
+      throw new ActionUnavailableError(
+        name,
+        typeof authorized === "string" ? authorized : undefined,
+      )
+    }
+    value = await action(parsed as never, context)
+    if (isStandardSchema(action.output)) {
+      value = await parseActionInput(action.output, value)
+    }
+    return tx.changeSet()
+  })
+  return Object.freeze({ value, commit })
+}
+
+async function loadAuthoredAction(engine: Engine, name: string) {
+  if (!/^[a-z0-9-]+$/.test(name)) throw new ActionNotFoundError(name)
+  const root = engine.actionsRoot.replace(/\/+$/, "")
+  const file = `${root}/${name}.action.ts`
+  const mod = (await engine.environment.loadModule(file)) as
+    { default?: ActionContribution } | undefined
+  if (typeof mod?.default !== "function") throw new ActionNotFoundError(name)
+  return mod.default
+}

package/actions/draft.ts

@@ -0,0 +1,105 @@
+import {
+  appendBlockSection,
+  formatNewSource,
+  patchFrontmatter,
+  prependBlockSection,
+  removeBlockSection,
+  updateBlockSection,
+  type BlockDraft,
+  type BlockUpdate,
+} from "../source/format.ts"
+import type { Topmatter } from "../source/topmatter.ts"
+import type { PathMXYaml } from "../environment.ts"
+
+type DraftIO = {
+  create(path: string, content: string): Promise<void>
+  update(path: string, content: string): Promise<void>
+  read(path: string): Promise<string>
+}
+
+type DraftOperation =
+  | { type: "data"; patch: Topmatter }
+  | { type: "append"; block: BlockDraft }
+  | { type: "prepend"; block: BlockDraft }
+  | { type: "update"; id: string; update: BlockUpdate }
+  | { type: "remove"; id: string }
+
+export type SourceDraft = {
+  readonly path: string
+  create(): SourceDraft
+  data(patch: Topmatter): SourceDraft
+  appendBlock(block: BlockDraft): SourceDraft
+  prependBlock(block: BlockDraft): SourceDraft
+  updateBlock(id: string, update: BlockUpdate): SourceDraft
+  removeBlock(id: string): SourceDraft
+}
+
+export function createSourceDraft(
+  path: string,
+  io: DraftIO,
+  yaml: PathMXYaml,
+): SourceDraft & {
+  flush(): Promise<void>
+} {
+  let creating = false
+  const operations: DraftOperation[] = []
+
+  const apply = (initial: string) => {
+    let content = initial
+    for (const operation of operations) {
+      if (operation.type === "data") {
+        content = patchFrontmatter(content, operation.patch, yaml)
+      } else if (operation.type === "append") {
+        content = appendBlockSection(content, operation.block, yaml)
+      } else if (operation.type === "prepend") {
+        content = prependBlockSection(content, operation.block, yaml)
+      } else if (operation.type === "update") {
+        content = updateBlockSection(
+          content,
+          operation.id,
+          operation.update,
+          yaml,
+        )
+      } else {
+        content = removeBlockSection(content, operation.id, yaml)
+      }
+    }
+    return content
+  }
+
+  const draft: SourceDraft & { flush(): Promise<void> } = {
+    path,
+    create() {
+      creating = true
+      return draft
+    },
+    data(patch) {
+      operations.push({ type: "data", patch })
+      return draft
+    },
+    appendBlock(block) {
+      operations.push({ type: "append", block })
+      return draft
+    },
+    prependBlock(block) {
+      operations.push({ type: "prepend", block })
+      return draft
+    },
+    updateBlock(id, update) {
+      operations.push({ type: "update", id, update })
+      return draft
+    },
+    removeBlock(id) {
+      operations.push({ type: "remove", id })
+      return draft
+    },
+    async flush() {
+      if (creating) {
+        await io.create(path, apply(formatNewSource({}, yaml)))
+        return
+      }
+      await io.update(path, apply(await io.read(path)))
+    },
+  }
+  return draft
+}