dsh-todo-time-log 0.5.0 → 0.5.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/lib/store.js CHANGED
@@ -35,8 +35,10 @@
35
35
  * unit tests can drive it directly and a future storage adapter can reuse it.
36
36
  */
37
37
 
38
+ import { createHash } from 'node:crypto';
38
39
  import { promises as fsp } from 'node:fs';
39
40
  import path from 'node:path';
41
+ import { setTimeout as delay } from 'node:timers/promises';
40
42
  import {
41
43
  formatLocalDateTime,
42
44
  nowIso,
@@ -458,6 +460,24 @@ export function computeStats(todos) {
458
460
  return { total: todos.length, pending, completed: todos.length - pending };
459
461
  }
460
462
 
463
+ /** Default bound for acquiring the cross-process write lock. */
464
+ const DEFAULT_LOCK_TIMEOUT_MS = 2000;
465
+ /** A lock file older than this is treated as left behind by a crashed writer. */
466
+ const DEFAULT_STALE_LOCK_MS = 10_000;
467
+ const LOCK_RETRY_MIN_MS = 20;
468
+ const LOCK_RETRY_MAX_MS = 50;
469
+
470
+ /** SHA-256 of a persisted payload; distinguishes a real rewrite from a `touch`. */
471
+ function hashText(text) {
472
+ return createHash('sha256').update(text, 'utf8').digest('hex');
473
+ }
474
+
475
+ /** Monotonic-ish backoff used while another writer owns the lock. */
476
+ function lockRetryDelay() {
477
+ return LOCK_RETRY_MIN_MS
478
+ + Math.floor(Math.random() * (LOCK_RETRY_MAX_MS - LOCK_RETRY_MIN_MS + 1));
479
+ }
480
+
461
481
  async function writeFileAtomic(file, text) {
462
482
  await fsp.mkdir(path.dirname(file), { recursive: true });
463
483
  const tmp = `${file}.${process.pid}.${Date.now()}.tmp`;
@@ -483,9 +503,17 @@ async function writeFileAtomic(file, text) {
483
503
  *
484
504
  * Concurrency: mutations are synchronous on the in-memory map and then
485
505
  * serialized through one write chain, so the persisted file always reflects a
486
- * complete, ordered sequence of operations. A failed write keeps the in-memory
487
- * change and is retried by the next write; the failure is surfaced as a notice
488
- * and in `describe()`.
506
+ * complete, ordered sequence of operations. Cross-process writers are guarded
507
+ * by a `<dataFile>.lock` file: every write acquires the lock, re-reads the file
508
+ * when its mtime/size/hash changed underneath us, merges the foreign records
509
+ * (newest `updatedAt` wins for the same id, locally deleted ids stay deleted
510
+ * via tombstones) and only then replaces the file. A failed write keeps the
511
+ * in-memory change and is retried by the next write; the failure is surfaced
512
+ * as a notice and in `describe()`.
513
+ *
514
+ * `lockTimeoutMs` / `staleLockMs` are optional tuning knobs for tests; the
515
+ * defaults are the production values (about 2s to acquire a lock, a lock file
516
+ * older than 10s is considered stale).
489
517
  */
490
518
  export class TodoStore {
491
519
  #todos = new Map();
@@ -494,6 +522,14 @@ export class TodoStore {
494
522
  #loadNotices = [];
495
523
  #pendingNotices = [];
496
524
  #lastPersistError = null;
525
+ #lockHandle = null;
526
+ /** Ids deleted by this instance; never resurrected by a disk merge. */
527
+ #tombstones = new Set();
528
+ /** Known on-disk state: mtime/size/hash, or nulls when the file is absent. */
529
+ #knownMtimeMs = null;
530
+ #knownSize = null;
531
+ #knownHash = null;
532
+ #diskStateKnown = false;
497
533
 
498
534
  constructor(options = {}) {
499
535
  const { dataFile } = options;
@@ -504,6 +540,12 @@ export class TodoStore {
504
540
  this.now = typeof options.now === 'function' ? options.now : () => Date.now();
505
541
  this.logger = options.logger ?? null;
506
542
  this.disposed = false;
543
+ this.lockTimeoutMs = Number.isFinite(options.lockTimeoutMs) && options.lockTimeoutMs > 0
544
+ ? options.lockTimeoutMs
545
+ : DEFAULT_LOCK_TIMEOUT_MS;
546
+ this.staleLockMs = Number.isFinite(options.staleLockMs) && options.staleLockMs > 0
547
+ ? options.staleLockMs
548
+ : DEFAULT_STALE_LOCK_MS;
507
549
  }
508
550
 
509
551
  get loaded() {
@@ -538,6 +580,18 @@ export class TodoStore {
538
580
  return notices;
539
581
  }
540
582
 
583
+ /**
584
+ * Queue one event notice (a merge from another instance, for example):
585
+ * unlike `#note`, the same message is delivered again on every occurrence,
586
+ * while the diagnostic history still keeps it once.
587
+ */
588
+ #noteEvent(message) {
589
+ if (!this.#loadNotices.includes(message)) {
590
+ this.#loadNotices.push(message);
591
+ }
592
+ this.#pendingNotices.push(message);
593
+ }
594
+
541
595
  async load() {
542
596
  if (this.#loadPromise === null) {
543
597
  this.#loadPromise = this.#load();
@@ -546,22 +600,35 @@ export class TodoStore {
546
600
  }
547
601
 
548
602
  async #load() {
603
+ // Stat before reading: if another writer replaces the file between the two
604
+ // calls we only ever see an older mtime, so the next write detects the
605
+ // change and re-reads instead of missing a foreign update.
606
+ let stat = null;
607
+ try {
608
+ stat = await fsp.stat(this.dataFile);
609
+ } catch {
610
+ /* missing or unreadable: the read below reports it */
611
+ }
549
612
  let text;
550
613
  try {
551
614
  text = await fsp.readFile(this.dataFile, 'utf8');
552
615
  } catch (error) {
553
- if (error && error.code !== 'ENOENT') {
616
+ if (error && error.code === 'ENOENT') {
617
+ this.#forgetDiskState();
618
+ } else {
554
619
  this.#note(`读取数据文件失败:${error.message}`);
555
620
  this.#warn(`todo-time-log: read failed: ${error.message}`);
556
621
  }
557
622
  return { ok: true, notices: this.#loadNotices.slice() };
558
623
  }
624
+ this.#adoptDiskState(stat, text);
559
625
 
560
626
  let parsed;
561
627
  try {
562
628
  parsed = JSON.parse(text);
563
629
  } catch (error) {
564
630
  await this.#archiveCorrupt('json');
631
+ this.#forgetDiskState();
565
632
  this.#note('数据文件不是合法 JSON,已备份原文件并重建为空列表');
566
633
  this.#warn(`todo-time-log: corrupt data file: ${error.message}`);
567
634
  return { ok: true, notices: this.#loadNotices.slice() };
@@ -572,6 +639,7 @@ export class TodoStore {
572
639
  : undefined;
573
640
  if (typeof envelopeVersion === 'number' && !SUPPORTED_STORE_VERSIONS.includes(envelopeVersion)) {
574
641
  await this.#archiveCorrupt(`version-${envelopeVersion}`);
642
+ this.#forgetDiskState();
575
643
  this.#note(`数据文件版本 ${envelopeVersion} 不受支持,已备份原文件并重建为空列表`);
576
644
  return { ok: true, notices: this.#loadNotices.slice() };
577
645
  }
@@ -590,6 +658,7 @@ export class TodoStore {
590
658
  // Valid JSON, wrong shape: archive before the next write replaces it,
591
659
  // otherwise a recognisable-but-misplaced list would be lost silently.
592
660
  await this.#archiveCorrupt('shape');
661
+ this.#forgetDiskState();
593
662
  this.#note('数据文件结构异常,已备份原文件并重建为空列表');
594
663
  return { ok: true, notices: this.#loadNotices.slice() };
595
664
  }
@@ -636,6 +705,189 @@ export class TodoStore {
636
705
  }
637
706
  }
638
707
 
708
+ /** Adopt the on-disk state we just read or wrote as the merge baseline. */
709
+ #adoptDiskState(stat, text) {
710
+ this.#knownMtimeMs = stat ? stat.mtimeMs : null;
711
+ this.#knownSize = stat ? stat.size : null;
712
+ this.#knownHash = hashText(text);
713
+ this.#diskStateKnown = true;
714
+ }
715
+
716
+ /** The data file is known to be absent (never written or archived as corrupt). */
717
+ #forgetDiskState() {
718
+ this.#knownMtimeMs = null;
719
+ this.#knownSize = null;
720
+ this.#knownHash = null;
721
+ this.#diskStateKnown = true;
722
+ }
723
+
724
+ /**
725
+ * Acquire the per-file writer lock. `wx` (create-exclusive) guarantees a
726
+ * single creator; a lock file older than `staleLockMs` is assumed to belong
727
+ * to a crashed writer and is cleaned up once, then the acquisition retries.
728
+ */
729
+ async #acquireLock() {
730
+ const lockPath = `${this.dataFile}.lock`;
731
+ await fsp.mkdir(path.dirname(this.dataFile), { recursive: true });
732
+ const deadline = Date.now() + this.lockTimeoutMs;
733
+ let staleLockCleaned = false;
734
+ for (;;) {
735
+ try {
736
+ const handle = await fsp.open(lockPath, 'wx');
737
+ try {
738
+ await handle.writeFile(`${process.pid} ${new Date().toISOString()}\n`, 'utf8');
739
+ } catch {
740
+ /* the lock's existence is what matters, not its content */
741
+ }
742
+ this.#lockHandle = handle;
743
+ return;
744
+ } catch (error) {
745
+ if (!error || error.code !== 'EEXIST') {
746
+ throw new Error(`无法创建数据文件锁:${error?.message ?? String(error)}`);
747
+ }
748
+ }
749
+ if (!staleLockCleaned) {
750
+ try {
751
+ const lockStat = await fsp.stat(lockPath);
752
+ if (Date.now() - lockStat.mtimeMs > this.staleLockMs) {
753
+ staleLockCleaned = true;
754
+ this.#warn(`todo-time-log: removing stale lock file ${lockPath}`);
755
+ await fsp.rm(lockPath, { force: true });
756
+ continue;
757
+ }
758
+ } catch (statError) {
759
+ if (statError && statError.code === 'ENOENT') {
760
+ continue; // released between the failed open and the stat
761
+ }
762
+ }
763
+ }
764
+ if (Date.now() >= deadline) {
765
+ throw new Error(`获取数据文件锁超时(${this.lockTimeoutMs}ms):${lockPath}`);
766
+ }
767
+ await delay(lockRetryDelay());
768
+ }
769
+ }
770
+
771
+ async #releaseLock() {
772
+ const handle = this.#lockHandle;
773
+ this.#lockHandle = null;
774
+ if (handle === null) return;
775
+ try {
776
+ await handle.close();
777
+ } catch {
778
+ /* an already-closed handle must not mask the write result */
779
+ }
780
+ try {
781
+ await fsp.rm(`${this.dataFile}.lock`, { force: true });
782
+ } catch (error) {
783
+ this.#warn(`todo-time-log: could not remove lock file: ${error.message}`);
784
+ }
785
+ }
786
+
787
+ /**
788
+ * Merge records another instance wrote since our last known state. Runs while
789
+ * holding the write lock, so the snapshot serialized afterwards is the union
790
+ * of both instances' state.
791
+ *
792
+ * Corrupt data is never archived here (`load` already archived it once) and
793
+ * never merged: the caller still writes its own snapshot, which matches the
794
+ * previous overwrite-on-next-write behavior.
795
+ */
796
+ async #mergeIfDiskChanged() {
797
+ if (!this.#diskStateKnown) return;
798
+ let stat;
799
+ try {
800
+ stat = await fsp.stat(this.dataFile);
801
+ } catch (error) {
802
+ if (error && error.code === 'ENOENT') {
803
+ this.#forgetDiskState();
804
+ return;
805
+ }
806
+ this.#note(`无法检查数据文件是否被其他实例修改,本次未合并:${error.message}`);
807
+ return;
808
+ }
809
+ if (stat.mtimeMs === this.#knownMtimeMs && stat.size === this.#knownSize) {
810
+ return;
811
+ }
812
+
813
+ let text;
814
+ try {
815
+ text = await fsp.readFile(this.dataFile, 'utf8');
816
+ } catch (error) {
817
+ if (error && error.code === 'ENOENT') {
818
+ this.#forgetDiskState();
819
+ return;
820
+ }
821
+ this.#note(`检测到其他实例的写入,但重新读取数据文件失败,本次未合并:${error.message}`);
822
+ return;
823
+ }
824
+ if (hashText(text) === this.#knownHash) {
825
+ // Content unchanged (e.g. an mtime-only touch): adopt the new stat.
826
+ this.#adoptDiskState(stat, text);
827
+ return;
828
+ }
829
+
830
+ let parsed;
831
+ try {
832
+ parsed = JSON.parse(text);
833
+ } catch {
834
+ this.#note('检测到其他实例的写入,但磁盘数据不是合法 JSON,本次未合并(保留现有数据并照常写入)');
835
+ return;
836
+ }
837
+ const envelopeVersion = parsed && typeof parsed === 'object' && !Array.isArray(parsed)
838
+ ? parsed.version
839
+ : undefined;
840
+ if (typeof envelopeVersion === 'number' && !SUPPORTED_STORE_VERSIONS.includes(envelopeVersion)) {
841
+ this.#note(`检测到其他实例的写入,但磁盘数据版本 ${envelopeVersion} 不受支持,本次未合并(保留现有数据并照常写入)`);
842
+ return;
843
+ }
844
+ const rows = Array.isArray(parsed) ? parsed : (parsed && parsed.todos);
845
+ if (!Array.isArray(rows)) {
846
+ this.#note('检测到其他实例的写入,但磁盘数据结构异常,本次未合并(保留现有数据并照常写入)');
847
+ return;
848
+ }
849
+
850
+ let added = 0;
851
+ let replaced = 0;
852
+ let dropped = 0;
853
+ let overflow = 0;
854
+ const seen = new Set();
855
+ for (const row of rows) {
856
+ const { todo } = normalizeTodo(row, { now: this.now() });
857
+ if (todo === null || seen.has(todo.id)) {
858
+ dropped += 1;
859
+ continue;
860
+ }
861
+ seen.add(todo.id);
862
+ if (this.#tombstones.has(todo.id)) continue;
863
+ const mine = this.#todos.get(todo.id);
864
+ if (!mine) {
865
+ if (this.#todos.size >= MAX_TODOS) {
866
+ overflow += 1;
867
+ continue;
868
+ }
869
+ this.#todos.set(todo.id, todo);
870
+ added += 1;
871
+ continue;
872
+ }
873
+ const mineMs = parseTimestamp(mine.updatedAt);
874
+ const diskMs = parseTimestamp(todo.updatedAt);
875
+ if (diskMs !== null && (mineMs === null || diskMs > mineMs)) {
876
+ this.#todos.set(todo.id, todo);
877
+ replaced += 1;
878
+ }
879
+ }
880
+ const merged = added + replaced;
881
+ if (merged > 0) {
882
+ this.#noteEvent(overflow > 0
883
+ ? `检测到其他实例的写入,已合并 ${merged} 条(另有 ${overflow} 条超出数量上限未合并)`
884
+ : `检测到其他实例的写入,已合并 ${merged} 条`);
885
+ }
886
+ if (dropped > 0) {
887
+ this.#note(`合并其他实例的数据时丢弃 ${dropped} 条非法待办记录`);
888
+ }
889
+ }
890
+
639
891
  serialize() {
640
892
  return JSON.stringify(
641
893
  {
@@ -649,10 +901,23 @@ export class TodoStore {
649
901
  }
650
902
 
651
903
  #persist() {
652
- const text = this.serialize();
653
904
  const write = async () => {
654
- await writeFileAtomic(this.dataFile, text);
655
- this.#lastPersistError = null;
905
+ await this.#acquireLock();
906
+ try {
907
+ await this.#mergeIfDiskChanged();
908
+ const text = this.serialize();
909
+ await writeFileAtomic(this.dataFile, text);
910
+ let stat = null;
911
+ try {
912
+ stat = await fsp.stat(this.dataFile);
913
+ } catch {
914
+ /* unknown mtime: the next write re-reads and the hash skips the merge */
915
+ }
916
+ this.#adoptDiskState(stat, text);
917
+ this.#lastPersistError = null;
918
+ } finally {
919
+ await this.#releaseLock();
920
+ }
656
921
  };
657
922
  this.#persistChain = this.#persistChain.then(write, write);
658
923
  return this.#persistChain;
@@ -667,7 +932,10 @@ export class TodoStore {
667
932
  next.push(`数据已更新但写入磁盘失败,将在下次写入时重试:${this.#lastPersistError}`);
668
933
  this.#warn(`todo-time-log: persist failed: ${this.#lastPersistError}`);
669
934
  }
670
- return { ok: true, todo, notices: next, persisted: this.#lastPersistError === null };
935
+ // A merge may have replaced this record with a newer foreign version while
936
+ // the write was in flight, so report what actually lives in memory now.
937
+ const current = this.#todos.get(todo.id) ?? todo;
938
+ return { ok: true, todo: current, notices: next, persisted: this.#lastPersistError === null };
671
939
  }
672
940
 
673
941
  async list(options = {}) {
@@ -743,6 +1011,7 @@ export class TodoStore {
743
1011
  completedAt: null,
744
1012
  updatedAt: createdAt,
745
1013
  };
1014
+ this.#tombstones.delete(todo.id);
746
1015
  this.#todos.set(todo.id, todo);
747
1016
  return this.#commit(todo, []);
748
1017
  }
@@ -845,6 +1114,9 @@ export class TodoStore {
845
1114
  return failure(ERROR_CODES.NOT_FOUND, `待办不存在:${String(id)}`);
846
1115
  }
847
1116
  this.#todos.delete(key);
1117
+ // Remember the deletion so a disk snapshot written by a stale peer cannot
1118
+ // merge this id back into memory (the next write also drops it on disk).
1119
+ this.#tombstones.add(key);
848
1120
  const notices = [];
849
1121
  try {
850
1122
  await this.#persist();
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "dsh-todo-time-log",
3
- "version": "0.5.0",
3
+ "version": "0.5.2",
4
4
  "description": "查看待办事项,并记录与展示每个待办的创建时间与完成时间(Todo time log for DeepSeek Harness)",
5
5
  "keywords": [
6
6
  "dsh",
@@ -40,13 +40,27 @@
40
40
  "README.md"
41
41
  ],
42
42
  "engines": {
43
- "node": ">=20"
43
+ "node": ">=20",
44
+ "dsh": ">=0.2.0-rc.2 <0.2.3-0"
45
+ },
46
+ "peerDependencies": {
47
+ "@deepseek-ai/dsh": ">=0.2.0-rc.2 <0.2.3-0"
48
+ },
49
+ "peerDependenciesMeta": {
50
+ "@deepseek-ai/dsh": {
51
+ "optional": true
52
+ }
44
53
  },
45
54
  "scripts": {
46
- "test": "node test/parse.mjs && node test/smoke.mjs && node test/http.mjs",
55
+ "build": "node scripts/build-client.mjs",
47
56
  "check": "node --check lib/time.js && node --check lib/parse.js && node --check lib/files.js && node --check lib/store.js && node --check lib/index.js && node --check lib/client.js",
57
+ "lint": "eslint .",
58
+ "typecheck": "tsc -p tsconfig.json",
59
+ "test": "node --test test/parse.test.mjs test/smoke.test.mjs test/http.test.mjs test/ui/panel.test.mjs test/store-concurrency.test.mjs",
60
+ "test:coverage": "node --test --experimental-test-coverage test/parse.test.mjs test/smoke.test.mjs test/http.test.mjs test/ui/panel.test.mjs test/store-concurrency.test.mjs",
48
61
  "audit": "node test/client-audit.mjs",
49
- "prepublishOnly": "npm run check && npm test && npm run audit"
62
+ "verify": "npm run check && npm run lint && npm run typecheck && npm run build && npm test && npm run audit",
63
+ "prepublishOnly": "npm run verify"
50
64
  },
51
65
  "publishConfig": {
52
66
  "access": "public"
@@ -59,5 +73,16 @@
59
73
  "platform": "web",
60
74
  "immediately": true
61
75
  }
76
+ },
77
+ "devDependencies": {
78
+ "@eslint/js": "^9.39.5",
79
+ "@types/node": "^26.6.6",
80
+ "esbuild": "^0.28.2",
81
+ "eslint": "^9.39.5",
82
+ "globals": "^17.14.0",
83
+ "jsdom": "^26.1.0",
84
+ "react": "^18.3.1",
85
+ "react-dom": "^18.3.1",
86
+ "typescript": "^5.9.3"
62
87
  }
63
88
  }