@pathmx/core 0.5.0 → 0.5.1

package/README.md

@@ -58,11 +58,15 @@ const app = await createApp({
 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))