@vrtmrz/livesync-commonlib 0.1.39 → 0.1.40

package/dist/platform/node/index.d.ts

@@ -20,5 +20,5 @@ export declare const readline: typeof nodeReadlinePromises;
 export declare const builtinModules: readonly string[];
 /** Returns whether a module specifier refers to a Node built-in. */
 export declare const isBuiltin: typeof nodeIsBuiltin;
-export { NodeStorageAdapter, createNodeStorage, validateStoragePath, type CreateNodeStorageOptions, type NodeStorageStat, } from "./storage.js";
+export { NodeStorageAdapter, createNodeStorage, getNodeFileCreationTime, validateStoragePath, type CreateNodeStorageOptions, type NodeStorageStat, } from "./storage.js";
 export { createNodeStandardIo, type CreateNodeStandardIoOptions, type NodeStandardInput, type NodeStandardOutput, } from "./standardIo.js";

package/dist/platform/node/index.js

@@ -15,6 +15,7 @@ const isBuiltin = nodeIsBuiltin;
 import {
   NodeStorageAdapter,
   createNodeStorage,
+  getNodeFileCreationTime,
   validateStoragePath
 } from "./storage.js";
 import {
@@ -28,6 +29,7 @@ export {
   fileURLToPath,
   fs,
   fsPromises,
+  getNodeFileCreationTime,
   isBuiltin,
   os,
   path,

package/dist/platform/node/storage.d.ts

@@ -1,6 +1,9 @@
+import type { Stats } from "node:fs";
 import type { UXDataWriteOptions, UXStat } from "../../common/types.js";
 import type { IStorageAdapter } from "../../serviceModules/adapters/IStorageAdapter.js";
 export type NodeStorageStat = UXStat;
+/** Read creation time in integer milliseconds, using change time when birth time is unavailable. */
+export declare function getNodeFileCreationTime(stat: Pick<Stats, "birthtimeMs" | "ctimeMs">): number;
 export interface CreateNodeStorageOptions {
     /**
      * Host-selected root directory. Adapter paths are resolved relative to this root.

package/dist/platform/node/storage.js

@@ -2,6 +2,9 @@ import { constants as nodeFsConstants } from "node:fs";
 import * as nodeFsPromises from "node:fs/promises";
 import * as nodePath from "node:path";
 import { validateStoragePath } from "../storagePath.js";
+function getNodeFileCreationTime(stat) {
+  return Math.floor(stat.birthtimeMs > 0 ? stat.birthtimeMs : stat.ctimeMs);
+}
 const NO_FOLLOW = nodeFsConstants.O_NOFOLLOW ?? 0;
 class SymbolicLinkStoragePathError extends Error {
   constructor(path) {
@@ -48,7 +51,7 @@ class NodeStorageAdapter {
       return {
         size: stat.size,
         mtime: Math.floor(stat.mtimeMs),
-        ctime: Math.floor(stat.ctimeMs),
+        ctime: getNodeFileCreationTime(stat),
         type: stat.isDirectory() ? "folder" : "file"
       };
     } catch (error) {
@@ -161,5 +164,6 @@ import { validateStoragePath as validateStoragePath2 } from "../storagePath.js";
 export {
   NodeStorageAdapter,
   createNodeStorage,
+  getNodeFileCreationTime,
   validateStoragePath2 as validateStoragePath
 };

package/docs/platform-storage.md

@@ -39,6 +39,8 @@ await storage.write('notes/example.md', '# Example');
 
 `rootPath` may be absolute or process-relative. The host should normally resolve and validate configuration before constructing the adapter.
 
+Node storage reports creation time from a positive `birthtimeMs`, falling back to `ctimeMs` when birth time is unavailable. Timestamps are rounded down to integer milliseconds. Hosts converting native Node stats can use `getNodeFileCreationTime` from the `/node` entry for the same conversion. Some platforms already return change time as birth time, so this fallback cannot guarantee a stable creation time there. Replacing a file can also change its birth time. Write options preserve modification time; the Node adapter does not restore creation time from `ctime`.
+
 The Node adapter rejects symbolic-link components which it observes in an adapter path before an operation. File opens also use `O_NOFOLLOW` for the final component where the platform exposes that flag. These checks protect against invalid paths and symbolic links which already exist when an operation begins. Its concrete `rename(sourcePath, targetPath)` operation validates both paths before providing the atomic rename expected by Node hosts.
 
 The host-selected `rootPath` is a trust boundary, not an operating-system filesystem sandbox. The adapter assumes that an untrusted local process cannot replace that root or its descendants concurrently with an operation. A host which grants another local actor write access to the tree must not rely on the adapter as a privilege boundary.

package/docs/proven-in-use.md

@@ -86,6 +86,8 @@ The CLI extends the same neutral context with its database path and injected `St
 
 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.
 
+Unreleased Node timestamp tests verify that `stat` and `trystat` retain an available birth time when change time advances, fall back when birth time is zero, and return integer milliseconds. Packed-package checks exercise the shared `getNodeFileCreationTime` export. With the exact locally packed candidate installed, downstream CLI tests verify that an in-place edit retains creation time in local Metadata. The CLI-to-real-Obsidian scenario additionally verifies the edited content and creation time in received Metadata. These checks do not establish the reporter's ZFS behaviour or physical-file creation times in Obsidian.
+
 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.
 
 The CLI mirror command returns Commonlib's full-scan aggregate, and daemon start-up stops when that aggregate reports an actual pair failure. Deliberately skipped pairs remain a successful scan result. Commonlib owns the pair classification and aggregate; the CLI owns its command and process policy.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vrtmrz/livesync-commonlib",
-  "version": "0.1.39",
+  "version": "0.1.40",
   "description": "Shared data, storage, and replication primitives for Self-hosted LiveSync clients.",
   "type": "module",
   "types": "./dist/index.d.ts",