@summerscar/dsh-mnemon-sync 0.1.2 → 0.1.4

package/cordis.patch.yml

@@ -1,3 +1,11 @@
+# Host entry: HTTP API, scheduler and backup engine. Needs only webServer.
 - insert:
     - id: mnemon-sync
       name: '@summerscar/dsh-mnemon-sync'
+    # Memory Source entry, mounted exactly like the shipped dsh-mnemon-source-*
+    # packages: only id + name here, and the module itself exports
+    # `inject = ['mnemonMemory']` so the Loader waits for that service.
+    # Kept as a separate Entry so a profile without dsh-mnemon still gets a
+    # working backup engine (just no tab).
+    - id: mnemon-sync-source
+      name: '@summerscar/dsh-mnemon-sync/source'

package/index.js

@@ -14,14 +14,13 @@
  * resident process, which is both simpler and compatible with the store.
  *
  * The browser half only ever sees JSON: credentials are masked on the way out
- * and are never echoed back by a read.
+ * and are never echoed back by a read. The memory Source that owns the page is
+ * a separate Cordis entry (./source.js), mounted by the bundle patch.
  */
 
 import { createHash } from 'node:crypto'
 import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs'
-import { createRequire } from 'node:module'
 import { dirname, join, resolve } from 'node:path'
-import { pathToFileURL } from 'node:url'
 
 import { SyncHistory, SyncScheduler } from './scheduler.js'
 import {
@@ -165,7 +164,6 @@ export function apply(ctx, config = {}) {
   // — not UI contributions. Standing up this minimal Source is what lets the
   // page use its own type instead of borrowing `memory-spaces`, which is the
   // only way its tab can highlight independently.
-  ctx.effect(() => registerSyncSource(ctx, dataRoot), 'mnemon-sync: memory source')
 
   ctx.effect(() => ctx.webServer.register({
     kind: 'prefix',
@@ -582,104 +580,6 @@ function restoreMaskedSecrets(incoming, previous) {
   return incoming
 }
 
-/**
- * Resolve the dsh-mnemon extension SDK.
- *
- * A bare `import('dsh-mnemon/extension-sdk')` is not enough here. Installed
- * from npm the package sits at `<profile>/node_modules/@summerscar/...`, so
- * Node's own ancestor walk would find dsh-mnemon beside it — but a *linked*
- * checkout lives outside the profile with no `node_modules` of its own, and
- * then the walk finds nothing.
- *
- * Both install shapes are therefore covered, cheapest first:
- *   1. From this module's own location, which is right for an npm install.
- *   2. From `DSH_PROFILE_DIR`, which is right for a linked checkout and is set
- *      in every shell and Host process a profile launches.
- *   3. From `DSH_HOME/profiles/web`, for a Host booted without that variable.
- *
- * Returns `undefined` when dsh-mnemon is not installed at all, which is a
- * supported configuration: the backup keeps working without its page.
- */
-async function loadExtensionSdk() {
-  // 1. Ask Node, anchored at this file. Resolves for an npm install.
-  try {
-    const resolver = createRequire(import.meta.url)
-    const resolved = resolver.resolve('dsh-mnemon/lib/extension-sdk.js')
-    return await import(pathToFileURL(resolved).href)
-  } catch {
-    // Not resolvable from here: fall through to the profile-anchored paths.
-  }
-
-  const candidates = []
-  const profileDir = process.env.DSH_PROFILE_DIR?.trim()
-  if (profileDir !== undefined && profileDir !== '') {
-    candidates.push(join(profileDir, 'node_modules', 'dsh-mnemon', 'lib', 'extension-sdk.js'))
-  }
-  // The Host that loads this plugin lives in the installation's own tree.
-  candidates.push(join(process.env.DSH_HOME ?? '', 'profiles', 'web', 'node_modules', 'dsh-mnemon', 'lib', 'extension-sdk.js'))
-  for (const candidate of candidates) {
-    if (candidate === '' || !existsSync(candidate)) continue
-    return import(pathToFileURL(candidate).href)
-  }
-  return undefined
-}
-
-/**
- * Install the sync Source into dsh-mnemon's composable-memory service.
- *
- * Returns a disposer, and does nothing at all when the Host runs without that
- * service (a profile with dsh-mnemon absent).
- */
-function registerSyncSource(ctx, dataRoot) {
-  if (typeof ctx.get !== 'function') return () => {}
-  const service = ctx.get('mnemonMemory')
-  if (service === undefined || service === null || typeof service.installContributions !== 'function') {
-    return () => {}
-  }
-  let disposed = false
-  let uninstall
-  void (async () => {
-    try {
-      const sdk = await loadExtensionSdk()
-      if (sdk === undefined || typeof sdk.defineMemorySource !== 'function') {
-        console.warn('mnemon-sync: dsh-mnemon extension SDK not found; the sync tab stays hidden')
-        return
-      }
-      const { createSyncSource, syncSourceManifest } = await import('./source.js')
-      if (disposed) return
-      // The manifest goes through the SDK validator so a contract drift in
-      // dsh-mnemon fails loudly here instead of at composition time.
-      const definition = sdk.defineMemorySource(createSyncSource({ ...syncSourceManifest }))
-      uninstall = service.installContributions({
-        plugin: {
-          apiVersion: 'dsh-mnemon/plugin/v1',
-          packageName: '@summerscar/dsh-mnemon-sync',
-          label: { en: 'Sync backup', 'zh-CN': '同步备份' },
-          description: {
-            en: 'Archive memory spaces to S3 or WebDAV.',
-            'zh-CN': '把记忆空间备份到 S3 或 WebDAV。',
-          },
-          roles: ['source'],
-          provides: [{ id: 'source' }],
-        },
-        sources: [definition],
-      }, { instanceId: 'mnemon-sync' })
-      if (disposed) {
-        uninstall?.()
-        uninstall = undefined
-      }
-    } catch (error) {
-      // A Host that cannot accept the Source must not take the backup down.
-      console.warn('mnemon-sync: could not register the sync source', error)
-    }
-  })()
-  return () => {
-    disposed = true
-    uninstall?.()
-    uninstall = undefined
-  }
-}
-
 /** Read a staging tree into the flat `{ path, bytes }` entries the ZIP writer takes. */
 function collect(root, prefix = '') {
   const entries = []

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@summerscar/dsh-mnemon-sync",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Back up and restore dsh-mnemon memory components (memory spaces, project documents, runtime memory) to S3-compatible storage or WebDAV.",
   "type": "module",
   "main": "index.js",
@@ -8,7 +8,8 @@
     ".": "./index.js",
     "./client": "./client.js",
     "./locale/*.json": "./locale/*.json",
-    "./icon": "./icon.svg"
+    "./icon": "./icon.svg",
+    "./source": "./source.js"
   },
   "files": [
     "index.js",

package/source.js

@@ -1,34 +1,98 @@
 /**
  * Mnemon Sync — the Source that owns this page.
  *
+ * This module is a standard Cordis plugin entry, written the same way the
+ * shipped dsh-mnemon Source packages are (see dsh-mnemon-source-runtime):
+ * `inject = ['mnemonMemory']` and `installMemory(ctx, ...)` inside `apply`.
+ * The Loader waits for the service, calls apply when it appears, and disposes
+ * the registration when it goes away.
+ *
+ * One concession to being distributable: the SDK is loaded with `createRequire`
+ * instead of a static `import`. A static import resolves fine for an npm
+ * install (the package sits under `<profile>/node_modules/`, with dsh-mnemon
+ * as a sibling ancestor) but fails for a `link:` checkout that lives outside
+ * the profile and has no `node_modules` of its own. `createRequire` with an
+ * explicit `DSH_PROFILE_DIR` fallback covers both shapes.
+ *
  * Why a Source is required at all: dsh-mnemon renders a page tab only when its
- * `sourceTypeId` appears in the live source catalog, and the catalog lists
+ * `sourceTypeId` appears in the live source catalog, and that catalog lists
  * real, running Source implementations. A UI-only contribution can borrow
  * `memory-spaces` and be shown, but the tab bar highlights *every* tab sharing
  * the selected page's type prefix, so borrowing means clicking one lights up
  * the other. Declaring our own type is the only way to get an independent tab.
  *
  * This Source is deliberately honest about what it holds. It is not a memory
- * backend: it stores no insights, so it contributes an empty projection and
- * declares no read routes or write actions. Its role is to be the identity the
- * sync page hangs from, which is why every capability is false and the facts
- * report only what the backup configuration currently is.
- *
- * The alternative — faking routes that answer with nothing — would pollute the
- * model's memory view with an empty source and could make a composition look
- * incomplete. An empty, clearly-labelled source is the smaller lie.
+ * backend: it stores no insights, contributes an empty projection and declares
+ * no read routes or write actions. Its role is to be the identity the sync
+ * page hangs from.
  */
 
 import { createHash } from 'node:crypto'
+import { existsSync } from 'node:fs'
+import { createRequire } from 'node:module'
 import { join } from 'node:path'
 
 import { resolveDataRoot } from './index.js'
 import { inspectHome } from './snapshot.js'
 import { readSettings } from './store.js'
 
+const require = createRequire(import.meta.url)
+
 export const SYNC_SOURCE_TYPE_ID = 'mnemon-sync'
 export const SYNC_PACKAGE_NAME = '@summerscar/dsh-mnemon-sync'
 
+export const name = SYNC_PACKAGE_NAME
+// The one dependency the Source needs. The Loader holds this Entry until
+// dsh-mnemon publishes mnemonMemory, then mounts it.
+export const inject = ['mnemonMemory']
+
+/**
+ * Resolve the extension SDK synchronously so `apply` can stay synchronous.
+ * Tries normal package resolution first, then the profile-anchored absolute
+ * path for linked checkouts.
+ */
+function loadSdk() {
+  try {
+    return require('dsh-mnemon/extension-sdk')
+  } catch {
+    // Fall through: linked checkout has no ancestor node_modules.
+  }
+  const profileDir = process.env.DSH_PROFILE_DIR?.trim()
+  const candidates = []
+  if (profileDir !== undefined && profileDir !== '') {
+    candidates.push(join(profileDir, 'node_modules', 'dsh-mnemon', 'lib', 'extension-sdk.js'))
+  }
+  candidates.push(join(process.env.DSH_HOME ?? '', 'profiles', 'web', 'node_modules', 'dsh-mnemon', 'lib', 'extension-sdk.js'))
+  for (const candidate of candidates) {
+    if (candidate === '' || !existsSync(candidate)) continue
+    return require(candidate)
+  }
+  return undefined
+}
+
+const sdk = loadSdk()
+
+/** The plugin descriptor, validated by the SDK when available. */
+export const memoryPlugin = sdk === undefined ? {
+  packageName: SYNC_PACKAGE_NAME,
+  label: { en: 'Sync backup', 'zh-CN': '同步备份' },
+  description: {
+    en: 'Back up and restore dsh-mnemon memory components.',
+    'zh-CN': '备份与恢复 dsh-mnemon 的记忆组件。',
+  },
+  roles: ['source'],
+  provides: [{ id: 'source' }],
+} : sdk.defineMemoryPlugin({
+  packageName: SYNC_PACKAGE_NAME,
+  label: { en: 'Sync backup', 'zh-CN': '同步备份' },
+  description: {
+    en: 'Back up and restore dsh-mnemon memory components.',
+    'zh-CN': '备份与恢复 dsh-mnemon 的记忆组件。',
+  },
+  roles: ['source'],
+  provides: [{ id: 'source' }],
+})
+
 /** The manifest Core validates before this Source may take part in a View. */
 export const syncSourceManifest = {
   apiVersion: 'dsh-mnemon/v1',
@@ -43,30 +107,21 @@ export const syncSourceManifest = {
   consistency: 'exact-snapshot',
   routes: [],
   actions: [],
-  // A management descriptor is not decoration. dsh-mnemon builds its Source
-  // catalog from installed Sources that declare one, and the workbench decides
-  // a layer is "running" by whether its type is in that catalog — so a Source
-  // without `management` is installed but reported as "on yet not running".
-  // Fields stay empty: this page does its own editing.
+  // A management descriptor is required for managementCatalog to list this
+  // Source; without it the Source is installed but reported "on yet not running".
   management: {
     label: 'Sync backup',
-    description: 'Archive memory spaces to S3 or WebDAV.',
+    description: 'Back up and restore dsh-mnemon memory components.',
   },
 }
 
 /**
  * Build the Source definition.
  *
- * `facts()` must return the Host's *facts envelope* — `sourceInstanceKey`,
+ * `facts()` returns the Host's facts envelope — `sourceInstanceKey`,
  * `sourceTypeId`, `role`, `availability`, `revision`, `capabilities`,
- * `routeIds`, `actionIds` (plus optional `hints`). dsh-mnemon rejects anything
- * else: `normalizeFacts()` compares `facts.sourceInstanceKey` against the
- * registry key and throws `memory Source facts instance mismatch` when it is
- * missing, which is exactly what a `{ summary, details }` shape produced.
- *
- * `hints` is the only free-form channel that survives normalization, so the
- * backup configuration a human may want to see travels there. `project()`
- * returns `{ fragments: [] }`: there is no memory content here to contribute.
+ * `routeIds`, `actionIds` (plus optional `hints`). `project()` brings nothing
+ * into a prompt, because there is no memory content here to bring.
  */
 export function createSyncSource(manifest = syncSourceManifest) {
   return {
@@ -81,21 +136,18 @@ export function createSyncSource(manifest = syncSourceManifest) {
       return {
         facts() {
           const settings = safeSettings(home)
-          const inspected = safeInspect(dataRoot)
+          const inspected = safeInspect(home)
           return {
             sourceInstanceKey: context.sourceInstanceKey,
             sourceTypeId: manifest.typeId,
             role: manifest.role,
-            // This Source is a maintenance identity, not a memory backend: it
-            // is always ready and holds nothing a View could select.
             availability: 'ready',
             revision: configurationRevision(settings, inspected),
             capabilities: [],
             routeIds: [],
             actionIds: [],
-            // Facts are JSON only and must stay small: metadata the Host may
-            // surface, never memory content. Only `hints` survives
-            // normalization, so anything worth showing goes here.
+            // Only `hints` survives normalization, so the backup configuration
+            // a human may want to see travels there.
             hints: {
               summary: settings.enabled
                 ? `Sync backup every ${String(settings.autoSyncMinutes)} min to ${describeTarget(settings.target)}`
@@ -114,7 +166,6 @@ export function createSyncSource(manifest = syncSourceManifest) {
           }
         },
         project() {
-          // Nothing to inject: this Source holds no memories to contribute.
           return { fragments: [] }
         },
         dispose() {},
@@ -123,13 +174,23 @@ export function createSyncSource(manifest = syncSourceManifest) {
   }
 }
 
+/** The standard Cordis entry point, identical in shape to the shipped Sources. */
+export function apply(ctx, config = {}) {
+  if (sdk === undefined) {
+    // dsh-mnemon is not installed at all; the backup engine in index.js still
+    // works, only the page is unavailable. Do not fake a registration.
+    console.warn('mnemon-sync: dsh-mnemon extension SDK not found; the sync tab stays hidden')
+    return
+  }
+  sdk.installMemory(ctx, {
+    plugin: memoryPlugin,
+    sources: [sdk.defineMemorySource(createSyncSource({ ...syncSourceManifest }))],
+  }, config?.instanceId === undefined ? undefined : { instanceId: config.instanceId })
+}
+
 /**
- * A stable revision for the current backup configuration.
- *
- * The Host requires a non-empty string and compares it across a turn, so this
- * must change when the configuration changes and stay equal otherwise. It is
- * derived from the facts themselves rather than a clock, which keeps
- * composition deterministic.
+ * A stable revision for the current backup configuration, derived from the
+ * facts themselves rather than a clock so composition stays deterministic.
  */
 function configurationRevision(settings, inspected) {
   const material = JSON.stringify({

package/targets.js

@@ -266,7 +266,29 @@ function parseWebDavListing(xml, remotePath) {
       modifiedAt: textOf(/<[^:>]*:?getlastmodified[^>]*>([^<]+)</iu.exec(block)),
     })
   }
-  return entries.sort((left, right) => String(right.modifiedAt ?? '').localeCompare(String(left.modifiedAt ?? '')))
+  return newestFirst(entries)
+}
+
+/**
+ * Sort archives newest first.
+ *
+ * `modifiedAt` is an RFC 1123 string (`Sun, 09 Nov 2026 08:00:00 GMT`) from
+ * WebDAV and an ISO 8601 string from S3. Comparing those as text is wrong: the
+ * weekday and day lead the WebDAV form, so "09 Nov 23:00" sorts before
+ * "10 Nov 01:00" even though it is older. Parse to an instant instead.
+ *
+ * An unparseable or missing stamp sorts last rather than corrupting the order:
+ * a listing that cannot say when something was written should not push a
+ * usable row off the top.
+ */
+function newestFirst(entries) {
+  const stamp = (entry) => {
+    const value = entry?.modifiedAt
+    if (typeof value !== 'string') return Number.NEGATIVE_INFINITY
+    const parsed = Date.parse(value)
+    return Number.isNaN(parsed) ? Number.NEGATIVE_INFINITY : parsed
+  }
+  return entries.sort((left, right) => stamp(right) - stamp(left))
 }
 
 function integerOf(match) {
@@ -465,7 +487,7 @@ async function listS3(target, signal) {
       modifiedAt: textOf(/<LastModified>([^<]+)<\/LastModified>/u.exec(block)),
     })
   }
-  return entries.sort((left, right) => String(right.modifiedAt ?? '').localeCompare(String(left.modifiedAt ?? '')))
+  return newestFirst(entries)
 }
 
 /**