@miadi/tide 0.5.4 → 0.6.0

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.
Files changed (2) hide show
  1. package/package.json +2 -2
  2. package/src/annotate.ts +59 -8
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@miadi/tide",
3
- "version": "0.5.4",
3
+ "version": "0.6.0",
4
4
  "description": "Typed client boundary for the ironsilk `tide` runtime. Daemon Unix-socket transport with CLI fallback.",
5
5
  "publishConfig": {
6
6
  "access": "public"
@@ -15,7 +15,7 @@
15
15
  "src"
16
16
  ],
17
17
  "dependencies": {
18
- "@miadi/annotate-core": "^0.1.1",
18
+ "@miadi/annotate-core": "^0.2.0",
19
19
  "@miadi/tide-contract": "0.3.1"
20
20
  },
21
21
  "keywords": [
package/src/annotate.ts CHANGED
@@ -36,12 +36,14 @@ import { promisify } from "node:util"
36
36
  import { mkdir, readdir, readFile, realpath, rm, writeFile } from "node:fs/promises"
37
37
  import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path"
38
38
  import { homedir } from "node:os"
39
+ import { existsSync } from "node:fs"
39
40
  import { randomBytes } from "node:crypto"
40
41
  import { TideError } from "./errors"
41
- import { isMarkAuthor, MARK_KINDS, resolveQuote } from "@miadi/annotate-core"
42
+ import { AUTHOR_BASES, isMarkAuthor, MARK_KINDS, resolveQuote } from "@miadi/annotate-core"
42
43
  import type {
43
44
  AnnotateBlock,
44
45
  AnnotateDocument,
46
+ AuthorBasis,
45
47
  DeliverOutcome,
46
48
  MarkAuthor,
47
49
  MarkKind,
@@ -117,6 +119,10 @@ export interface MarkInput {
117
119
  text: string
118
120
  kind?: MarkKind
119
121
  author: MarkAuthor
122
+ /** How the author was known, from `resolveAuthor`. Recorded on the mark as `author_basis`. */
123
+ basis?: AuthorBasis
124
+ /** Whose request carried the mark, from `resolveAuthor`. Recorded as `author_by` / `author_by_name`. */
125
+ by?: MarkAuthor | null
120
126
  }
121
127
 
122
128
  export interface ReviewExport {
@@ -130,6 +136,8 @@ export interface MarkResult extends ReviewExport {
130
136
  /** How many new records received the author. 1 on the normal path. */
131
137
  stamped: number
132
138
  author: MarkAuthor
139
+ basis?: AuthorBasis
140
+ by?: MarkAuthor | null
133
141
  }
134
142
 
135
143
  export interface DeliverResult extends DeliverOutcome {
@@ -154,11 +162,34 @@ export function resolveVesselRoot(env: NodeJS.ProcessEnv = process.env, home: st
154
162
  return join(xdg || join(home, ".local", "state"), "plannotator-tmux-review")
155
163
  }
156
164
 
157
- /** plannotator-tui's record root: `$PLANNOTATOR_STORE_DIR` → `~/.plannotator/clients/plannotator-tui/annotations`. */
158
- export function resolveStoreRoot(env: NodeJS.ProcessEnv = process.env, home: string = homedir()): string {
165
+ /** plannotator-tui's data dir, in the binary's own order (plannotator-tui-schema `data_dir`). */
166
+ export const DATA_DIR_ENV = "PLANNOTATOR_DATA_DIR"
167
+
168
+ /**
169
+ * plannotator-tui's record root: `$PLANNOTATOR_STORE_DIR` (tide's override), else
170
+ * `<data dir>/clients/plannotator-tui/annotations`, where the data dir is found as
171
+ * the binary finds it: `$PLANNOTATOR_DATA_DIR` (a leading `~` is home) → an existing
172
+ * `~/.plannotator` → an absolute `$XDG_DATA_HOME/plannotator` → `~/.plannotator`.
173
+ * A host that shares annotations sets PLANNOTATOR_DATA_DIR, and the marks the
174
+ * binary writes there are the ones read here (jgwill/gaia#87).
175
+ */
176
+ export function resolveStoreRoot(
177
+ env: NodeJS.ProcessEnv = process.env,
178
+ home: string = homedir(),
179
+ exists: (p: string) => boolean = existsSync,
180
+ ): string {
159
181
  const fromEnv = env[STORE_ROOT_ENV]?.trim()
160
182
  if (fromEnv) return fromEnv
161
- return join(home, ".plannotator", "clients", "plannotator-tui", "annotations")
183
+ const dataDir = (): string => {
184
+ const set = env[DATA_DIR_ENV]?.trim()
185
+ if (set) return set === "~" ? home : set.startsWith("~/") ? join(home, set.slice(2)) : set
186
+ const dot = join(home, ".plannotator")
187
+ if (exists(dot)) return dot
188
+ const xdg = env.XDG_DATA_HOME?.trim()
189
+ if (xdg && isAbsolute(xdg)) return join(xdg, "plannotator")
190
+ return dot
191
+ }
192
+ return join(dataDir(), "clients", "plannotator-tui", "annotations")
162
193
  }
163
194
 
164
195
  function resolveTmuxBin(env: NodeJS.ProcessEnv = process.env): string {
@@ -497,8 +528,17 @@ interface StoreAnnotation {
497
528
  id?: unknown
498
529
  author?: unknown
499
530
  author_name?: unknown
531
+ author_basis?: unknown
532
+ author_by?: unknown
533
+ author_by_name?: unknown
500
534
  [k: string]: unknown
501
535
  }
536
+
537
+ /** How an author was known and whose request carried the mark; plannotator-tui keeps unknown fields on rewrite. */
538
+ export interface MarkAttribution {
539
+ basis?: AuthorBasis
540
+ by?: MarkAuthor | null
541
+ }
502
542
  interface StoreRecord {
503
543
  path?: unknown
504
544
  annotations?: StoreAnnotation[]
@@ -512,15 +552,22 @@ export function recordIds(rec: StoreRecord): Set<string> {
512
552
  /**
513
553
  * Write the author onto exactly the records in `ids` that have none. Returns how
514
554
  * many were stamped. A record that already carries an author is left alone —
515
- * the rule is no assignment after the fact, in either direction.
555
+ * the rule is no assignment after the fact, in either direction. With an
556
+ * attribution, the record also says how the author was known (`author_basis`)
557
+ * and whose request carried it (`author_by`, `author_by_name`).
516
558
  */
517
- export function stampAuthor(rec: StoreRecord, ids: Set<string>, author: MarkAuthor): number {
559
+ export function stampAuthor(rec: StoreRecord, ids: Set<string>, author: MarkAuthor, attribution: MarkAttribution = {}): number {
518
560
  let n = 0
519
561
  for (const a of rec.annotations ?? []) {
520
562
  if (typeof a.id !== "string" || !ids.has(a.id)) continue
521
563
  if (a.author !== null && a.author !== undefined) continue
522
564
  a.author = author.id
523
565
  a.author_name = author.name
566
+ if (attribution.basis) {
567
+ a.author_basis = attribution.basis
568
+ a.author_by = attribution.by ? attribution.by.id : null
569
+ a.author_by_name = attribution.by ? attribution.by.name : null
570
+ }
524
571
  n++
525
572
  }
526
573
  return n
@@ -684,6 +731,9 @@ export async function listMarks(doc: string, storeRoot?: string): Promise<MarkRe
684
731
  id: text(a.id),
685
732
  author: typeof a.author === "string" && a.author ? a.author : null,
686
733
  author_name: typeof a.author_name === "string" && a.author_name ? a.author_name : null,
734
+ author_basis: (AUTHOR_BASES as readonly unknown[]).includes(a.author_basis) ? (a.author_basis as AuthorBasis) : null,
735
+ author_by: typeof a.author_by === "string" && a.author_by ? a.author_by : null,
736
+ author_by_name: typeof a.author_by_name === "string" && a.author_by_name ? a.author_by_name : null,
687
737
  text: text(a.body),
688
738
  quote: text((a.anchor as { originalText?: unknown } | undefined)?.originalText),
689
739
  created_at: typeof a.created_at === "string" ? a.created_at : null,
@@ -724,10 +774,11 @@ export async function mark(doc: string, input: MarkInput): Promise<MarkResult> {
724
774
  if (!store) throw new TideError("the mark was written but its record was not found in the plannotator store; author not stamped")
725
775
  const rec = JSON.parse(await readFile(store, "utf8")) as StoreRecord
726
776
  const fresh = new Set([...recordIds(rec)].filter(id => !idsBefore.has(id)))
727
- const stamped = stampAuthor(rec, fresh, input.author)
777
+ const attribution: MarkAttribution = input.basis ? { basis: input.basis, by: input.by ?? null } : {}
778
+ const stamped = stampAuthor(rec, fresh, input.author, attribution)
728
779
  if (stamped > 0) await writeFile(store, JSON.stringify(rec, null, 2) + "\n", "utf8")
729
780
  const exported = await exportReview(doc)
730
- return { ...exported, stamped, author: input.author }
781
+ return { ...exported, stamped, author: input.author, ...attribution }
731
782
  }
732
783
 
733
784
  /**