@pathmx/core 0.5.0 → 0.5.2

package/README.md

@@ -55,14 +55,22 @@ const app = await createApp({
 })
 ```
 
+Routes and Source identities are file-based. A Source-level frontmatter `id`
+is ignored and reported as a non-failing `pmx lint` warning. Block-level ids
+remain authorable for stable local targets.
+
 Official packages follow the CLI's release channel:
 
 ```sh
-pathmx plugins add mermaid react
+pathmx plugins add paths
+pathmx plugins add auth mermaid
 pathmx plugins list
 pathmx plugins update
 ```
 
+`paths` installs the provider-neutral Path, Completion, and Player experience.
+Auth remains provider-configured and Mermaid remains opt-in.
+
 ## Image directives
 
 The default Image Plugin compiles portable image roles from normal Markdown:

package/assets.ts

@@ -1,15 +1,25 @@
+import { canonicalPath } from "./canonical.ts"
+
 const ASSET_NAME = /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/
-export const GENERATED_ASSET_LIMIT = 128
+export const ASSET_STORE_LIMIT = 128
 const encoder = new TextEncoder()
 
-export type ServedAsset = Readonly<{
-  body: string | Blob
-  contentType: string
-}>
-
-type StoredAsset = {
-  name: string
-  asset: ServedAsset
+export type StoredAsset =
+  | Readonly<{
+      type: "generated"
+      body: string | Blob
+      contentType: string
+    }>
+  | Readonly<{
+      type: "authored"
+      sourcePath: string
+      body: Blob
+      contentType: string
+    }>
+
+type RetainedAsset = {
+  key: string
+  asset: StoredAsset
 }
 
 function avalanche(value: number) {
@@ -52,7 +62,11 @@ function textFingerprint(text: string, contentType: string) {
   return fingerprint.digest()
 }
 
-export async function blobFingerprint(blob: Blob, contentType: string) {
+async function fingerprintBlobStream(
+  blob: Blob,
+  contentType: string,
+  chunks?: BlobPart[],
+) {
   const fingerprint = new AssetFingerprint()
   fingerprintHeader(fingerprint, contentType)
   const reader = blob.stream().getReader()
@@ -61,12 +75,25 @@ export async function blobFingerprint(blob: Blob, contentType: string) {
       const chunk = await reader.read()
       if (chunk.done) return fingerprint.digest()
       fingerprint.update(chunk.value)
+      chunks?.push(new Uint8Array(chunk.value).buffer)
     }
   } finally {
     reader.releaseLock()
   }
 }
 
+export function blobFingerprint(blob: Blob, contentType: string) {
+  return fingerprintBlobStream(blob, contentType)
+}
+
+async function fingerprintedSnapshot(blob: Blob, contentType: string) {
+  const chunks: BlobPart[] = []
+  return {
+    hash: await fingerprintBlobStream(blob, contentType, chunks),
+    body: new Blob(chunks, { type: contentType }),
+  }
+}
+
 function validateAssetName(name: string) {
   if (!ASSET_NAME.test(name)) {
     throw new Error(`Invalid generated asset name: ${name}`)
@@ -80,18 +107,34 @@ function assetHref(name: string, hash: string) {
   return `/.pmx/${stem}-${hash}${ext}`
 }
 
+function authoredHref(sourcePath: string, hash: string) {
+  const slash = sourcePath.lastIndexOf("/")
+  const directory = sourcePath.slice(0, slash + 1)
+  const name = sourcePath.slice(slash + 1)
+  const dot = name.lastIndexOf(".")
+  const stem = dot <= 0 ? name : name.slice(0, dot)
+  const extension = dot <= 0 ? "" : name.slice(dot)
+  return `${directory}${stem}-${hash}${extension}`
+}
+
+function authoredSourcePath(value: string) {
+  const path = canonicalPath(value)
+  if (path === "/" || path === "/.pmx" || path.startsWith("/.pmx/")) {
+    throw new Error(`Invalid authored asset path: ${value}`)
+  }
+  return path
+}
+
 /**
- * Publishes generated assets into the local bounded cache. A future CDN or
- * object-storage backend should extract byte retention behind a general
- * `AssetStore` (`put`, `get`, `href`) while keeping fingerprinting and key
- * policy here. Repository assets may share that store, but keep their own
- * routing and access rules; this LRU must not be their durable CDN origin.
+ * Retains generated and authored derivatives in one local bounded cache.
+ * Repository assets keep distinct routing and access rules; this LRU is not a
+ * durable CDN origin.
  */
-export class GeneratedAssets {
-  private assets = new Map<string, StoredAsset>()
-  private latest = new Map<string, ServedAsset & { href: string }>()
+export class AssetStore {
+  private assets = new Map<string, RetainedAsset>()
+  private latest = new Map<string, StoredAsset & { href: string }>()
 
-  constructor(private limit = GENERATED_ASSET_LIMIT) {}
+  constructor(private limit = ASSET_STORE_LIMIT) {}
 
   get(href: string) {
     const stored = this.assets.get(href)
@@ -107,42 +150,84 @@ export class GeneratedAssets {
     )
   }
 
+  delete(href: string) {
+    const stored = this.assets.get(href)
+    if (!stored) return
+    this.assets.delete(href)
+    if (this.latest.get(stored.key)?.href === href) {
+      this.latest.delete(stored.key)
+    }
+  }
+
   publishText(name: string, text: string, contentType: string) {
     validateAssetName(name)
-    const current = this.latest.get(name)
-    if (current?.body === text && current.contentType === contentType) {
+    const key = `generated:${name}`
+    const current = this.latest.get(key)
+    if (
+      current?.type === "generated" &&
+      current.body === text &&
+      current.contentType === contentType
+    ) {
       this.get(current.href)
       return current.href
     }
     const href = assetHref(name, textFingerprint(text, contentType))
-    this.retain(name, href, { body: text, contentType })
+    this.retain(key, href, {
+      type: "generated",
+      body: text,
+      contentType,
+    })
     return href
   }
 
   async publishBlob(name: string, blob: Blob, contentType = blob.type) {
     validateAssetName(name)
     contentType ||= "application/octet-stream"
-    const current = this.latest.get(name)
-    if (current?.body === blob && current.contentType === contentType) {
+    const key = `generated:${name}`
+    const current = this.latest.get(key)
+    if (
+      current?.type === "generated" &&
+      current.body === blob &&
+      current.contentType === contentType
+    ) {
       this.get(current.href)
       return current.href
     }
     const href = assetHref(name, await blobFingerprint(blob, contentType))
-    this.retain(name, href, { body: blob, contentType })
+    this.retain(key, href, {
+      type: "generated",
+      body: blob,
+      contentType,
+    })
+    return href
+  }
+
+  async publishAuthored(source: string, blob: Blob, contentType = blob.type) {
+    const sourcePath = authoredSourcePath(source)
+    contentType ||= "application/octet-stream"
+    const key = `authored:${sourcePath}`
+    const snapshot = await fingerprintedSnapshot(blob, contentType)
+    const href = authoredHref(sourcePath, snapshot.hash)
+    this.retain(key, href, {
+      type: "authored",
+      sourcePath,
+      body: snapshot.body,
+      contentType,
+    })
     return href
   }
 
-  private retain(name: string, href: string, asset: ServedAsset) {
+  private retain(key: string, href: string, asset: StoredAsset) {
     this.assets.delete(href)
-    this.assets.set(href, { name, asset })
-    this.latest.set(name, { ...asset, href })
+    this.assets.set(href, { key, asset })
+    this.latest.set(key, { ...asset, href })
 
     while (this.assets.size > this.limit) {
       const oldestHref = this.assets.keys().next().value!
-      const { name: oldestName } = this.assets.get(oldestHref)!
+      const { key: oldestKey } = this.assets.get(oldestHref)!
       this.assets.delete(oldestHref)
-      if (this.latest.get(oldestName)?.href === oldestHref) {
-        this.latest.delete(oldestName)
+      if (this.latest.get(oldestKey)?.href === oldestHref) {
+        this.latest.delete(oldestKey)
       }
     }
   }

package/cli/dev.ts

@@ -1,5 +1,4 @@
 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"
@@ -53,7 +52,9 @@ async function runWatched(
   resolved: { root: string; actionsRoot?: string },
   port?: number,
 ) {
-  const entry = fileURLToPath(new URL("./index.ts", import.meta.url))
+  const invokedEntry = process.argv[1]
+  if (!invokedEntry) throw new Error("PathMX CLI entrypoint is unavailable.")
+  const entry = resolve(invokedEntry)
   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))

package/cli/lint.ts

@@ -19,7 +19,13 @@ export type InvalidSourceIssue = Readonly<{
   message: string
 }>
 
-export type LintIssue = UnresolvedLinkIssue | InvalidSourceIssue
+export type SourceWarning = Readonly<{
+  type: "source.warning"
+  source: string
+  message: string
+}>
+
+export type LintIssue = UnresolvedLinkIssue | InvalidSourceIssue | SourceWarning
 
 export function collectUnresolved(app: Engine) {
   const issues: UnresolvedLinkIssue[] = []
@@ -37,9 +43,16 @@ export function collectUnresolved(app: Engine) {
 }
 
 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}`
+  switch (issue.type) {
+    case "link.unresolved":
+      return `${issue.type}\0${issue.source}\0${issue.href}\0${issue.label ?? ""}`
+    case "source.invalid":
+      return `${issue.type}\0${issue.source}\0${issue.plugin}\0${issue.message}`
+    case "source.warning":
+      return `${issue.type}\0${issue.source}\0${issue.message}`
+    default:
+      return issue satisfies never
+  }
 }
 
 function compareIssues(a: LintIssue, b: LintIssue) {
@@ -60,6 +73,7 @@ export function formatLintIssues(issues: readonly LintIssue[]) {
 
   const links: UnresolvedLinkIssue[] = []
   const authoring: InvalidSourceIssue[] = []
+  const warnings: SourceWarning[] = []
   for (const issue of issues) {
     switch (issue.type) {
       case "link.unresolved":
@@ -68,6 +82,9 @@ export function formatLintIssues(issues: readonly LintIssue[]) {
       case "source.invalid":
         authoring.push(issue)
         break
+      case "source.warning":
+        warnings.push(issue)
+        break
       default:
         issue satisfies never
     }
@@ -89,9 +106,24 @@ export function formatLintIssues(issues: readonly LintIssue[]) {
       ].join("\n"),
     )
   }
+  if (warnings.length) {
+    sections.push(
+      [
+        pc.bold(`Warnings (${warnings.length})`),
+        ...warnings.map((issue) => `${issue.source}: ${issue.message}`),
+      ].join("\n"),
+    )
+  }
 
-  const noun = issues.length === 1 ? "issue" : "issues"
-  sections.push(pc.red(`${issues.length} ${noun} found`))
+  const failureCount = links.length + authoring.length
+  if (failureCount) {
+    const noun = failureCount === 1 ? "issue" : "issues"
+    sections.push(pc.red(`${failureCount} ${noun} found`))
+  }
+  if (warnings.length) {
+    const noun = warnings.length === 1 ? "warning" : "warnings"
+    sections.push(pc.yellow(`${warnings.length} ${noun} found`))
+  }
   return sections.join("\n\n")
 }
 
@@ -114,6 +146,15 @@ export async function collectLintIssues(app: Engine) {
     addDiagnostic(diagnostic)
   }
   for (const source of app.repo.all()) {
+    if (Object.hasOwn(source.data, "id")) {
+      const warning: SourceWarning = {
+        type: "source.warning",
+        source: source.path,
+        message:
+          'Source frontmatter "id" is ignored; Source ids are derived from file paths. Remove this field.',
+      }
+      issues.set(issueKey(warning), warning)
+    }
     if (!app.isPage(source)) continue
     try {
       await app.compilePage(source)
@@ -155,8 +196,9 @@ export function registerLint(program: Command) {
         })
         const issues = await collectLintIssues(app)
         console.log(formatLintIssues(issues))
-        if (!issues.length) return
-        process.exitCode = 1
+        if (issues.some((issue) => issue.type !== "source.warning")) {
+          process.exitCode = 1
+        }
       } catch (error) {
         fail(error)
       }

package/cli/update.ts

@@ -35,15 +35,52 @@ export async function availableRelease(
 }
 
 async function installRelease(spec: string) {
-  const child = Bun.spawn([process.execPath, "add", "--global", spec], {
+  const child = Bun.spawn(
+    [process.execPath, "add", "--global", "--exact", spec],
+    {
+      stdin: "inherit",
+      stdout: "inherit",
+      stderr: "inherit",
+    },
+  )
+  return child.exited
+}
+
+export function globalPackageVersion(output: string, packageName: string) {
+  const escaped = packageName.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")
+  return output.match(new RegExp(`${escaped}@([^\\s]+)`))?.[1]
+}
+
+async function installedGlobalVersion() {
+  const child = Bun.spawn([process.execPath, "pm", "ls", "--global"], {
     stdin: "inherit",
-    stdout: "inherit",
-    stderr: "inherit",
+    stdout: "pipe",
+    stderr: "pipe",
   })
-  const exitCode = await child.exited
+  const [stdout, exitCode] = await Promise.all([
+    new Response(child.stdout).text(),
+    child.exited,
+  ])
+  if (exitCode !== 0) return
+  return globalPackageVersion(stdout, release.package)
+}
+
+type InstallRelease = (spec: string) => Promise<number>
+type InstalledVersion = () => Promise<string | undefined>
+
+export async function installCheckedRelease(
+  spec: string,
+  expected: string,
+  install: InstallRelease = installRelease,
+  installed: InstalledVersion = installedGlobalVersion,
+) {
+  const exitCode = await install(spec)
   if (exitCode !== 0) {
+    if ((await installed()) === expected)
+      return { type: "installed-with-warning" as const, exitCode }
     throw new Error(`Bun could not install ${spec} (exit ${exitCode}).`)
   }
+  return { type: "installed" as const }
 }
 
 export function registerUpdate(program: Command) {
@@ -70,7 +107,12 @@ export function registerUpdate(program: Command) {
       console.log(
         `Updating ${release.package} ${release.version} → ${available}`,
       )
-      await installRelease(releaseSpec())
+      const result = await installCheckedRelease(releaseSpec(), available)
+      if (result.type === "installed-with-warning") {
+        console.warn(
+          `warning: Bun exited with ${result.exitCode}, but ${release.package}@${available} was installed. Check your Bun global package manifest for an unrelated invalid dependency.`,
+        )
+      }
       console.log(
         `PathMX ${available} installed. Run \`pathmx --version\` to verify.`,
       )