@vrtmrz/livesync-commonlib 0.1.0-rc.5 → 0.1.0-rc.6

package/docs/proven-in-use.md

@@ -4,13 +4,13 @@ Commonlib is extracted from the implementation shared by [Self-hosted LiveSync](
 
 The useful evidence is host- and contract-specific. Focused Commonlib tests establish reusable result semantics; Self-hosted LiveSync tests establish how those contracts compose into the Obsidian plug-in and CLI. The Webapp has focused adapter tests, and both the Webapp and WebPeer are type-checked and built, but they do not have an equally current end-to-end gate.
 
-The source links below identify the exact reviewed Self-hosted LiveSync revision used to establish this package boundary. The integration descriptions must still be reviewed when the maintained downstream changes.
+The code paths below identify the maintained Self-hosted LiveSync composition points used to establish this package boundary. The exact reviewed downstream revision and compatibility imports are recorded in [`migration/downstream-imports.json`](migration/downstream-imports.json), which is regenerated by the package-boundary tooling rather than copied into prose links. The integration descriptions must still be reviewed when the maintained downstream changes.
 
 ## Obsidian plug-in
 
-The plug-in extends the neutral `ServiceContext` with Obsidian-owned capabilities in [`ObsidianServiceContext.ts`](https://github.com/vrtmrz/obsidian-livesync/blob/fa336574e6055bbd61557da859fa0c1c44ca7ec9/src/modules/services/ObsidianServiceContext.ts). One context instance carries the host translator and event hub through the Service Hub rather than placing those dependencies in Commonlib globals.
+The plug-in extends the neutral `ServiceContext` with Obsidian-owned capabilities in `src/modules/services/ObsidianServiceContext.ts`. One context instance carries the LiveSync-owned translator and event hub through the Service Hub rather than placing those dependencies in Commonlib globals. Commonlib supplies its typed English fallback when another host omits the translator.
 
-The consumer's [service-context contract](https://github.com/vrtmrz/obsidian-livesync/blob/fa336574e6055bbd61557da859fa0c1c44ca7ec9/test/contracts/serviceContext.ts) checks shared result semantics and exact context identity across the composed services. The [real-Obsidian suite](https://github.com/vrtmrz/obsidian-livesync/blob/fa336574e6055bbd61557da859fa0c1c44ca7ec9/test/e2e-obsidian/README.md) then covers plug-in loading, representative Svelte dialogue mounts, Vault reflection, CouchDB and Object Storage synchronisation, two-Vault behaviour, and other Obsidian-owned boundaries.
+The consumer contract in `test/contracts/serviceContext.ts` checks shared result semantics and exact context identity across the composed services. The real-Obsidian suite documented in `test/e2e-obsidian/README.md` then covers plug-in loading, representative Svelte dialogue mounts, Vault reflection, CouchDB and Object Storage synchronisation, a two-device P2P Setup URI round-trip, two-Vault behaviour, and other Obsidian-owned boundaries.
 
 Most replication and storage services used by the plug-in still enter through explicit `compat/*` paths. Those imports prove that the published compatibility boundary supports the current migration; they are not examples of a finished high-level client API.
 
@@ -20,37 +20,43 @@ Commonlib's confirmation contract can also convey a host-neutral vertical action
 
 ## CLI
 
-The CLI extends the same neutral context with its database path and injected `StandardIo` in [`NodeServiceContext.ts`](https://github.com/vrtmrz/obsidian-livesync/blob/fa336574e6055bbd61557da859fa0c1c44ca7ec9/src/apps/cli/services/NodeServiceContext.ts). Its entry point creates the Node standard-I/O adapter once and passes it to command composition, while unit tests provide stream-independent fakes for parsing, prompts, standard output, and standard error.
+The CLI extends the same neutral context with its database path and injected `StandardIo` in `src/apps/cli/services/NodeServiceContext.ts`. Its entry point creates the Node standard-I/O adapter once and passes it to command composition, while unit tests provide stream-independent fakes for parsing, prompts, standard output, and standard error.
 
-The CLI filesystem composition receives a configured base directory and constructs the rooted Node storage adapter in [`NodeFileSystemAdapter.ts`](https://github.com/vrtmrz/obsidian-livesync/blob/fa336574e6055bbd61557da859fa0c1c44ca7ec9/src/apps/cli/adapters/NodeFileSystemAdapter.ts). Commonlib's shared storage result table checks the focused root contract; the consumer adds its file cache, Vault-shaped operations, case handling, and command policy.
+The CLI filesystem composition receives a configured base directory and constructs the rooted Node storage adapter in `src/apps/cli/adapters/NodeFileSystemAdapter.ts`. Commonlib's shared storage result table checks the focused root contract; the consumer adds its file cache, Vault-shaped operations, case handling, and command policy.
 
-The maintained CLI checks include unit tests, Deno-driven CLI E2E, Compose-based compatibility runs, and the [CLI-to-real-Obsidian synchronisation scenario](https://github.com/vrtmrz/obsidian-livesync/blob/fa336574e6055bbd61557da859fa0c1c44ca7ec9/test/e2e-obsidian/scripts/cli-to-obsidian-sync.ts). The latter is the strongest current evidence that the CLI and plug-in compose compatible Commonlib behaviour across two hosts.
+The maintained CLI checks include unit tests, Deno-driven CLI E2E, Compose-based compatibility runs, and the CLI-to-real-Obsidian synchronisation scenario in `test/e2e-obsidian/scripts/cli-to-obsidian-sync.ts`. The latter is the strongest current evidence that the CLI and plug-in compose compatible Commonlib behaviour across two hosts.
 
 ## Webapp
 
-The Webapp receives an already authorised `FileSystemDirectoryHandle` from its host and constructs `FileSystemAccessStorageAdapter` inside [`FSAPIFileSystemAdapter.ts`](https://github.com/vrtmrz/obsidian-livesync/blob/fa336574e6055bbd61557da859fa0c1c44ca7ec9/src/apps/webapp/adapters/FSAPIFileSystemAdapter.ts). The adapter does not call `showDirectoryPicker()`, choose a directory, or persist the handle. This is the maintained application example for the browser entry's root-ownership rule.
+The Webapp receives an already authorised `FileSystemDirectoryHandle` from its host and constructs `FileSystemAccessStorageAdapter` inside `src/apps/webapp/adapters/FSAPIFileSystemAdapter.ts`. The adapter does not call `showDirectoryPicker()`, choose a directory, or persist the handle. This is the maintained application example for the browser entry's root-ownership rule.
 
 The browser and Node storage implementations run through the same Commonlib result contract, and the Webapp adapter has focused unit coverage. The Webapp is also type-checked and built by downstream verification. Its browser E2E has not been kept at the same level as the Obsidian and CLI suites, so the documentation does not treat Webapp integration as equivalent real-runtime evidence.
 
 ## WebPeer and browser service composition
 
-The browser service composition in [`createLiveSyncBrowserServiceHub.ts`](https://github.com/vrtmrz/obsidian-livesync/blob/fa336574e6055bbd61557da859fa0c1c44ca7ec9/src/apps/browser/createLiveSyncBrowserServiceHub.ts) supplies browser-owned API and UI services around a caller-supplied context. WebPeer and the browser applications exercise this compatibility surface through type checks and builds.
+The browser service composition in `src/apps/browser/createLiveSyncBrowserServiceHub.ts` supplies browser-owned API and UI services around a caller-supplied context. WebPeer and the browser applications exercise this compatibility surface through type checks and builds.
 
-The Obsidian plug-in, CLI, and Webapp compose P2P ownership through `useP2PReplicatorFeature`. Commands and Obsidian views retain its live result object and resolve the current replicator when an action occurs. WebPeer still enters through the deprecated combined compatibility function, which now delegates the same ownership and lifecycle to the focused feature instead of maintaining a second implementation. Downstream Deno and Compose P2P E2E cover peer discovery and synchronisation; the Webapp and WebPeer UI surfaces themselves remain build- and type-check evidence rather than equivalent real-runtime gates.
+The Obsidian plug-in, CLI, and Webapp compose P2P ownership through `useP2PReplicatorFeature`. Commands and Obsidian views retain its live result object and resolve the current replicator when an action occurs. WebPeer still enters through the deprecated combined compatibility function, which now delegates the same ownership and lifecycle to the focused feature instead of maintaining a second implementation. Downstream Deno and Compose P2P E2E cover headless peer discovery and synchronisation. The real-Obsidian Setup URI workflow additionally covers first-device local initialisation, one-pass additional-device Fetch, explicit peer approval, Vault reflection, and a two-way note round-trip. The Webapp and WebPeer UI surfaces themselves remain build- and type-check evidence rather than equivalent real-runtime gates.
 
-This is evidence that the current package boundary can be consumed without the Obsidian host, but it is not yet a recommended standalone Commonlib client factory. The high-level lifecycle, readiness, error, and disposal contract remains a documented 1.0 decision.
+This is evidence that the current package boundary can be consumed without the Obsidian host, but it is not yet a recommended standalone Commonlib client factory. The high-level lifecycle, readiness, error, and disposal contract remains future package work after Self-hosted LiveSync 1.0 rather than a gate for that release.
+
+## Verification ownership
+
+Commonlib tests the result and lifecycle contracts of the real implementations it publishes. A maintained host tests only its own composition, persistence, presentation, restart, and policy. When a current host test needs isolation, the host may inject the narrow structural capability it consumes and provide a small fake or spy for that test; Commonlib does not publish test-runner-specific mocks or expose its private service graph.
+
+This is a boundary rule, not a requirement to build mock and spy infrastructure before LiveSync 1.0. Add a substitution seam only when a current consumer-owned test needs one. Exact-package downstream checks and focused real-runtime E2E remain the integration proof that the real Commonlib implementation and host composition work together.
 
 ## What a new consumer should copy
 
 A new integration should start with the focused entries, not by reproducing Self-hosted LiveSync's compatibility imports:
 
-- create one `ServiceContext` per independently composed client, inject its translator and events, and extend it only with capabilities owned by that host;
+- create one `ServiceContext` per independently composed client, optionally inject its translator and events, and extend it only with capabilities owned by that host; an omitted translator renders Commonlib's canonical English messages;
 - let the host select and authorise a storage root, then pass the root once to the Node or browser storage factory;
 - inject `StandardIo` into CLI policy so that protocol output and prompts remain testable; and
 - use `/remote-configurations` when a host needs to create or select saved remote profiles, while keeping naming prompts, persistence, and restart policy in the host; and
 - run the relevant Commonlib result contract against another implementation before describing matching TypeScript shapes as compatible behaviour.
 
-Use the linked consumer code as an integration example, while retaining the ownership and limitations stated in the [root README](https://github.com/vrtmrz/livesync-commonlib/blob/main/readme.md), [storage guide](platform-storage.md), [standard-I/O guide](platform-standard-io.md), and [remote configuration profile guide](remote-configurations.md).
+Use the named consumer paths as integration examples, while retaining the ownership and limitations stated in the [root README](../readme.md), [storage guide](platform-storage.md), [standard-I/O guide](platform-standard-io.md), and [remote configuration profile guide](remote-configurations.md).
 
 ## Maintenance rule
 

package/docs/releasing.md

@@ -13,6 +13,20 @@ npm run verify:package
 
 The gate type-checks Commonlib, runs its complete unit suite, verifies the source boundary, builds the distributable package, installs its exact tarball into a clean consumer, and bundles representative browser and Node entry points. The source `package.json` remains private to prevent publishing the repository root. Only the generated `.package` directory is publishable, and its manifest defaults to public publication on the `next` dist-tag.
 
+### Lockfile reproducibility
+
+Regenerate `package-lock.json` with the reviewed npm CLI version pinned by the `Use the reviewed npm CLI` step in `.github/workflows/publish-npm.yml`. Do this after adding, removing, or updating a dependency, even when an older local npm reports that the lockfile is already up to date. npm minor versions can differ in how they record transitive optional peer dependencies; a lockfile accepted by an older client can otherwise fail the hosted `npm ci` before any tests run.
+
+With the currently reviewed npm version, use:
+
+```bash
+npx --yes npm@11.18.0 install --package-lock-only --ignore-scripts --no-audit --no-fund
+npx --yes npm@11.18.0 ci
+npm run verify:package
+```
+
+Inspect the lockfile diff before committing it. A dependency-only maintenance change must not alter the source package version, and lockfile normalisation must not be described as a package upgrade when resolved versions and integrity values are unchanged. When the workflow selects a newer reviewed npm CLI, update this example in the same change.
+
 Before publication, run the downstream workflow against an exact Self-hosted LiveSync ref which already consumes the package. The workflow installs the tarball produced from the selected Commonlib commit, then runs LiveSync type checks, unit tests, plug-in and application builds, and CLI E2E. Real Obsidian E2E remains local-only and is required when the changed boundary affects actual plug-in composition, storage, UI, or platform behaviour.
 
 ## Preparing a release

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vrtmrz/livesync-commonlib",
-  "version": "0.1.0-rc.5",
+  "version": "0.1.0-rc.6",
   "description": "Shared data, storage, and replication primitives for Self-hosted LiveSync clients.",
   "type": "module",
   "license": "MIT",
@@ -101,11 +101,6 @@
       "import": "./dist/common/coreEnvVars.js",
       "default": "./dist/common/coreEnvVars.js"
     },
-    "./compat/common/i18n": {
-      "types": "./dist/common/i18n.d.ts",
-      "import": "./dist/common/i18n.js",
-      "default": "./dist/common/i18n.js"
-    },
     "./compat/common/logger": {
       "types": "./dist/common/logger.d.ts",
       "import": "./dist/common/logger.js",
@@ -126,16 +121,6 @@
       "import": "./dist/common/models/setting.const.js",
       "default": "./dist/common/models/setting.const.js"
     },
-    "./compat/common/models/setting.const.defaults": {
-      "types": "./dist/common/models/setting.const.defaults.d.ts",
-      "import": "./dist/common/models/setting.const.defaults.js",
-      "default": "./dist/common/models/setting.const.defaults.js"
-    },
-    "./compat/common/models/setting.const.preferred": {
-      "types": "./dist/common/models/setting.const.preferred.d.ts",
-      "import": "./dist/common/models/setting.const.preferred.js",
-      "default": "./dist/common/models/setting.const.preferred.js"
-    },
     "./compat/common/models/setting.type": {
       "types": "./dist/common/models/setting.type.d.ts",
       "import": "./dist/common/models/setting.type.js",
@@ -156,11 +141,6 @@
       "import": "./dist/common/models/tweak.definition.js",
       "default": "./dist/common/models/tweak.definition.js"
     },
-    "./compat/common/rosetta": {
-      "types": "./dist/common/rosetta.d.ts",
-      "import": "./dist/common/rosetta.js",
-      "default": "./dist/common/rosetta.js"
-    },
     "./compat/common/settingConstants": {
       "types": "./dist/common/settingConstants.d.ts",
       "import": "./dist/common/settingConstants.js",
@@ -206,11 +186,6 @@
       "import": "./dist/events/coreEvents.js",
       "default": "./dist/events/coreEvents.js"
     },
-    "./compat/hub/hub": {
-      "types": "./dist/hub/hub.d.ts",
-      "import": "./dist/hub/hub.js",
-      "default": "./dist/hub/hub.js"
-    },
     "./compat/interfaces/Confirm": {
       "types": "./dist/interfaces/Confirm.d.ts",
       "import": "./dist/interfaces/Confirm.js",

package/dist/common/i18n.d.ts

@@ -1,18 +0,0 @@
-import type { AllMessageKeys, I18N_LANGS } from "./rosetta.js";
-import type { TaggedType } from "./types.js";
-export declare let currentLang: I18N_LANGS;
-export declare function getResolvedLang(lang?: I18N_LANGS): I18N_LANGS;
-export declare function isAutoDisplayLanguage(lang: I18N_LANGS): boolean;
-export declare function __getMissingTranslations(): string[];
-export declare function __onMissingTranslation(callback: (key: string) => void): void;
-export declare function setLang(lang: I18N_LANGS): void;
-export declare function $t(message: string, lang?: I18N_LANGS): string;
-export declare function translateIfAvailable(message: string, lang?: I18N_LANGS): string;
-/**
- * TagFunction to Automatically translate.
- * @param strings
- * @param values
- * @returns
- */
-export declare function $f(strings: TemplateStringsArray, ...values: string[]): string;
-export declare function $msg<T extends AllMessageKeys>(key: T, params?: Record<string, string>, lang?: I18N_LANGS): TaggedType<string, T>;

package/dist/common/i18n.js

@@ -1,101 +0,0 @@
-import { getLanguage } from "./coreEnvFunctions.js";
-import { allMessages } from "./messages/combinedMessages.prod.js";
-const obsidianLangMap = {
-  de: "de",
-  es: "es",
-  ja: "ja",
-  ko: "ko",
-  ru: "ru",
-  zh: "zh",
-  "zh-cn": "zh",
-  "zh-hans": "zh",
-  "zh-tw": "zh-tw",
-  "zh-hk": "zh-tw",
-  "zh-mo": "zh-tw",
-  "zh-hant": "zh-tw"
-};
-function resolveLanguage(lang) {
-  if (lang !== "") return lang;
-  const obsidianLanguage = getLanguage().toLowerCase();
-  return obsidianLangMap[obsidianLanguage] ?? "def";
-}
-let currentLang = resolveLanguage("");
-const missingTranslations = [];
-let __onMissingTranslations = (key) => console.warn(key);
-const msgCache = /* @__PURE__ */ new Map();
-function getResolvedLang(lang = currentLang) {
-  return resolveLanguage(lang);
-}
-function isAutoDisplayLanguage(lang) {
-  return lang === "";
-}
-function __getMissingTranslations() {
-  return missingTranslations;
-}
-function __onMissingTranslation(callback) {
-  __onMissingTranslations = callback;
-}
-function setLang(lang) {
-  const resolvedLang = resolveLanguage(lang);
-  if (resolvedLang === currentLang) return;
-  currentLang = resolvedLang;
-  msgCache.clear();
-}
-function _getMessage(key, lang) {
-  if (key.trim() == "") return key;
-  const msgs = allMessages[key] ?? void 0;
-  const resolvedLang = resolveLanguage(lang);
-  let msg = msgs?.[resolvedLang];
-  if (!msg) {
-    if (missingTranslations.indexOf(key) === -1) {
-      __onMissingTranslations(key);
-      missingTranslations.push(key);
-    }
-    msg = msgs?.def;
-  }
-  return msg ?? key;
-}
-function getMessage(key) {
-  if (msgCache.has(key)) return msgCache.get(key);
-  const msg = _getMessage(key, currentLang);
-  msgCache.set(key, msg);
-  return msg;
-}
-function $t(message, lang) {
-  if (lang !== void 0) {
-    return _getMessage(message, lang);
-  }
-  return getMessage(message);
-}
-function translateIfAvailable(message, lang) {
-  if (message.trim() == "" || allMessages[message] === void 0) return message;
-  return $t(message, lang);
-}
-function $f(strings, ...values) {
-  let result = "";
-  for (let i = 0; i < values.length; i++) {
-    result += getMessage(strings[i]) + values[i];
-  }
-  result += getMessage(strings[strings.length - 1]);
-  return result;
-}
-function $msg(key, params = {}, lang) {
-  let msg = $t(key, lang);
-  for (const [placeholder, value] of Object.entries(params)) {
-    const regex = new RegExp(`\\\${${placeholder}}`, "g");
-    msg = msg.replace(regex, value);
-  }
-  return msg;
-}
-export {
-  $f,
-  $msg,
-  $t,
-  __getMissingTranslations,
-  __onMissingTranslation,
-  currentLang,
-  getResolvedLang,
-  isAutoDisplayLanguage,
-  setLang,
-  translateIfAvailable
-};

package/dist/common/messages/combinedMessages.dev.d.ts

@@ -1,7 +0,0 @@
-import { PartialMessages as def } from "./def.js";
-import { type MESSAGE } from "../rosetta.js";
-type MessageKeys = keyof typeof def.def;
-export declare const allMessages: {
-    [key: string]: MESSAGE;
-};
-export { type MessageKeys };

package/dist/common/messages/combinedMessages.dev.js

@@ -1,44 +0,0 @@
-import { PartialMessages as def } from "./def.js";
-import { PartialMessages as es } from "./es.js";
-import { PartialMessages as fr } from "./fr.js";
-import { PartialMessages as he } from "./he.js";
-import { PartialMessages as ja } from "./ja.js";
-import { PartialMessages as ko } from "./ko.js";
-import { PartialMessages as ru } from "./ru.js";
-import { PartialMessages as zh } from "./zh.js";
-import { PartialMessages as zhTw } from "./zh-tw.js";
-import { expandKeywords } from "../rosetta.js";
-const messages = {
-  ...def,
-  ...es,
-  ...fr,
-  ...he,
-  ...ja,
-  ...ko,
-  ...ru,
-  ...zh,
-  ...zhTw
-};
-const w = Object.entries(messages).map(([lang, messageDefs]) => Object.entries(messageDefs).map(([key, value]) => [key, [lang, value]])).flat();
-const _allMessages = w.reduce(
-  (acc, [key, value]) => {
-    if (!acc[key]) acc[key] = {};
-    acc[key][value[0]] = value[1];
-    return acc;
-  },
-  {}
-);
-const expandedMessage = {
-  ...expandKeywords(_allMessages, "def"),
-  ...expandKeywords(_allMessages, "es"),
-  ...expandKeywords(_allMessages, "fr"),
-  ...expandKeywords(_allMessages, "ja"),
-  ...expandKeywords(_allMessages, "ko"),
-  ...expandKeywords(_allMessages, "ru"),
-  ...expandKeywords(_allMessages, "zh"),
-  ...expandKeywords(_allMessages, "zh-tw")
-};
-const allMessages = expandedMessage;
-export {
-  allMessages
-};