@dreamlake/dreamlake-cli 0.97.2 → 0.98.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.
- package/dist/api/client.d.ts +1 -1
- package/dist/api/client.js +4 -4
- package/dist/api/http.d.ts +48 -1
- package/dist/api/http.js +111 -4
- package/dist/api/index.d.ts +17 -513
- package/dist/api/index.js +6 -2
- package/dist/api/note-edits.d.ts +40 -2
- package/dist/api/note-edits.js +197 -2
- package/dist/api/note-events.d.ts +40 -4
- package/dist/api/note-events.js +55 -2
- package/dist/api/note-facade.d.ts +268 -0
- package/dist/api/note-facade.js +376 -0
- package/dist/api/note-reading.d.ts +27 -0
- package/dist/api/note-reading.js +27 -0
- package/dist/api/note-write.d.ts +110 -0
- package/dist/api/note-write.js +217 -0
- package/dist/api/notes.d.ts +33 -44
- package/dist/api/notes.js +44 -34
- package/dist/api/sessions.d.ts +5 -5
- package/dist/cli/client.d.ts +2 -41
- package/dist/cli/client.js +13 -90
- package/dist/cli/help-examples.generated.js +1 -1
- package/dist/cli/notes/api-transport.js +6 -6
- package/dist/cli/notes/document.d.ts +32 -26
- package/dist/cli/notes/document.js +150 -95
- package/dist/cli/notes/edit-commands.d.ts +26 -5
- package/dist/cli/notes/edit-commands.js +163 -36
- package/dist/cli/notes/events.d.ts +3 -33
- package/dist/cli/notes/events.js +4 -51
- package/dist/cli/notes/html-read.d.ts +6 -0
- package/dist/cli/notes/html-read.js +12 -0
- package/dist/cli/notes/index.d.ts +10 -1
- package/dist/cli/notes/index.js +98 -27
- package/dist/cli/notes/move-command.d.ts +4 -0
- package/dist/cli/notes/move-command.js +7 -0
- package/dist/cli/sessions/runner/serve.d.ts +1 -1
- package/dist/cli/vault/sshTransfer.d.ts +1 -1
- package/dist/cli/version.d.ts +1 -1
- package/dist/cli/version.js +1 -1
- package/package.json +9 -9
package/dist/api/note-edits.js
CHANGED
|
@@ -1,5 +1,200 @@
|
|
|
1
|
-
|
|
2
|
-
|
|
1
|
+
/** Generated reading-view annotations are never saved as source. What is
|
|
2
|
+
* forbidden is NEW text that carries the generated header line
|
|
3
|
+
* (`<!-- notes-reading-view revision=… hash=…`). Deleting such a line, keeping
|
|
4
|
+
* one the note already has, or mentioning the marker in prose or a code block
|
|
5
|
+
* is allowed. Checked on raw inserted text before compilation (escaping would
|
|
6
|
+
* hide it) and on the insertion payloads of a caller-supplied patch. */
|
|
7
|
+
export const READING_VIEW_MARKER = "<!-- notes-reading-view";
|
|
8
|
+
export const READING_VIEW_HEADER = /^\s*<!-- notes-reading-view revision=/m;
|
|
9
|
+
export class ReadingViewMarkerRefused extends Error {
|
|
10
|
+
constructor(what) {
|
|
11
|
+
super(`${what} adds a generated reading-view marker header ("${READING_VIEW_MARKER} revision=…"); generated annotations are never saved as source`);
|
|
12
|
+
this.name = "ReadingViewMarkerRefused";
|
|
13
|
+
}
|
|
14
|
+
}
|
|
15
|
+
/** Inserted or replacement text only, never deletions or unchanged context. */
|
|
16
|
+
export function refuseReadingView(text, what) {
|
|
17
|
+
if (READING_VIEW_HEADER.test(text))
|
|
18
|
+
throw new ReadingViewMarkerRefused(what);
|
|
19
|
+
}
|
|
20
|
+
/** Whole-body replacement: only lines that are new relative to the baseline count, so a header the note already holds survives a write. */
|
|
21
|
+
export function refuseNewReadingViewLines(baseline, content, what) {
|
|
22
|
+
const kept = new Set(baseline.split("\n"));
|
|
23
|
+
for (const line of content.split("\n"))
|
|
24
|
+
if (READING_VIEW_HEADER.test(line) && !kept.has(line))
|
|
25
|
+
throw new ReadingViewMarkerRefused(what);
|
|
26
|
+
}
|
|
27
|
+
/** inline-dff escapes only (`\\ \n \r \t \[ \] \{ \} \+ \-`); anything else keeps its backslash. Never applied to unified-diff lines. */
|
|
28
|
+
const INLINE_ESCAPES = { "\\": "\\", n: "\n", r: "\r", t: "\t", "[": "[", "]": "]", "{": "{", "}": "}", "+": "+", "-": "-" };
|
|
29
|
+
const decodeInline = (text) => text.replace(/\\(.)/g, (whole, char) => INLINE_ESCAPES[char] ?? whole);
|
|
30
|
+
/** Apply the inline-dff subset this client emits (`@@ chars s:e @@` + one `~` line of `[-old-]`/`{+new+}`
|
|
31
|
+
* segments) to a baseline. null when the patch is outside that subset or its old text does not match. */
|
|
32
|
+
export function applyInlineDff(baseline, patch) {
|
|
33
|
+
const points = Array.from(baseline), lines = patch.split("\n");
|
|
34
|
+
let out = "", cursor = 0;
|
|
35
|
+
for (let i = 0; i < lines.length;) {
|
|
36
|
+
if (lines[i] === "") {
|
|
37
|
+
i++;
|
|
38
|
+
continue;
|
|
39
|
+
}
|
|
40
|
+
const header = /^@@ chars (\d+):(\d+) @@$/.exec(lines[i]), body = lines[i + 1];
|
|
41
|
+
if (!header || body === undefined || !body.startsWith("~ "))
|
|
42
|
+
return null;
|
|
43
|
+
const start = Number(header[1]), end = Number(header[2]);
|
|
44
|
+
if (start < cursor || end < start || end > points.length)
|
|
45
|
+
return null;
|
|
46
|
+
let rest = body.slice(2), old = "", added = "";
|
|
47
|
+
while (rest) {
|
|
48
|
+
const segment = /^(?:\[-((?:\\.|[^\\])*?)-\]|\{\+((?:\\.|[^\\])*?)\+\})/.exec(rest);
|
|
49
|
+
if (!segment)
|
|
50
|
+
return null;
|
|
51
|
+
if (segment[1] !== undefined)
|
|
52
|
+
old += decodeInline(segment[1]);
|
|
53
|
+
else
|
|
54
|
+
added += decodeInline(segment[2]);
|
|
55
|
+
rest = rest.slice(segment[0].length);
|
|
56
|
+
}
|
|
57
|
+
if (points.slice(start, end).join("") !== old)
|
|
58
|
+
return null;
|
|
59
|
+
out += points.slice(cursor, start).join("") + added;
|
|
60
|
+
cursor = end;
|
|
61
|
+
i += 2;
|
|
62
|
+
}
|
|
63
|
+
return out + points.slice(cursor).join("");
|
|
64
|
+
}
|
|
65
|
+
/** Apply a unified diff to a baseline, verifying context and removed lines. null when it does not apply cleanly. */
|
|
66
|
+
export function applyUnifiedDiff(baseline, patch) {
|
|
67
|
+
const src = baseline.split("\n"), lines = patch.split("\n"), out = [];
|
|
68
|
+
let at = 0, i = 0;
|
|
69
|
+
while (i < lines.length && (lines[i].startsWith("--- ") || lines[i].startsWith("+++ ")))
|
|
70
|
+
i++;
|
|
71
|
+
while (i < lines.length) {
|
|
72
|
+
if (lines[i] === "" && i === lines.length - 1)
|
|
73
|
+
break;
|
|
74
|
+
const hunk = /^@@ -(\d+)(?:,(\d+))? \+\d+(?:,\d+)? @@/.exec(lines[i]);
|
|
75
|
+
if (!hunk)
|
|
76
|
+
return null;
|
|
77
|
+
const index = hunk[2] === "0" ? Number(hunk[1]) : Number(hunk[1]) - 1;
|
|
78
|
+
if (index < at || index > src.length)
|
|
79
|
+
return null;
|
|
80
|
+
out.push(...src.slice(at, index));
|
|
81
|
+
at = index;
|
|
82
|
+
i++;
|
|
83
|
+
while (i < lines.length && !lines[i].startsWith("@@")) {
|
|
84
|
+
const line = lines[i++];
|
|
85
|
+
if (line.startsWith("\\"))
|
|
86
|
+
continue;
|
|
87
|
+
if (line === "") {
|
|
88
|
+
if (i === lines.length)
|
|
89
|
+
break;
|
|
90
|
+
return null;
|
|
91
|
+
}
|
|
92
|
+
const tag = line[0], text = line.slice(1);
|
|
93
|
+
if (tag === " " || tag === "-") {
|
|
94
|
+
if (src[at] !== text)
|
|
95
|
+
return null;
|
|
96
|
+
if (tag === " ")
|
|
97
|
+
out.push(text);
|
|
98
|
+
at++;
|
|
99
|
+
}
|
|
100
|
+
else if (tag === "+")
|
|
101
|
+
out.push(text);
|
|
102
|
+
else
|
|
103
|
+
return null;
|
|
104
|
+
}
|
|
105
|
+
}
|
|
106
|
+
out.push(...src.slice(at));
|
|
107
|
+
return out.join("\n");
|
|
108
|
+
}
|
|
109
|
+
/** Insertion payloads of an inline-dff patch, hunk by hunk with their original spans; null outside the parseable subset. */
|
|
110
|
+
function inlineInsertions(patch) {
|
|
111
|
+
const lines = patch.split("\n"), hunks = [];
|
|
112
|
+
for (let i = 0; i < lines.length;) {
|
|
113
|
+
if (lines[i] === "") {
|
|
114
|
+
i++;
|
|
115
|
+
continue;
|
|
116
|
+
}
|
|
117
|
+
const header = /^@@ chars (\d+):(\d+) @@$/.exec(lines[i]), body = lines[i + 1];
|
|
118
|
+
if (!header || body === undefined || !body.startsWith("~ "))
|
|
119
|
+
return null;
|
|
120
|
+
let rest = body.slice(2), added = "";
|
|
121
|
+
while (rest) {
|
|
122
|
+
const segment = /^(?:\[-((?:\\.|[^\\])*?)-\]|\{\+((?:\\.|[^\\])*?)\+\})/.exec(rest);
|
|
123
|
+
if (!segment)
|
|
124
|
+
return null;
|
|
125
|
+
if (segment[2] !== undefined)
|
|
126
|
+
added += decodeInline(segment[2]);
|
|
127
|
+
rest = rest.slice(segment[0].length);
|
|
128
|
+
}
|
|
129
|
+
hunks.push({ start: Number(header[1]), end: Number(header[2]), added });
|
|
130
|
+
i += 2;
|
|
131
|
+
}
|
|
132
|
+
return hunks;
|
|
133
|
+
}
|
|
134
|
+
/** A caller-supplied patch. With the baseline it was written against, the target is reconstructed and
|
|
135
|
+
* checked like a whole-body write (so a header split across hunks is seen assembled, and one the note
|
|
136
|
+
* already has may be re-added). Without a baseline, or when the patch does not apply to it, the check is
|
|
137
|
+
* BEST-EFFORT on the insertion payloads: inline-dff `{+…+}` (escapes decoded), concatenated across hunks
|
|
138
|
+
* that are adjacent in the original (one's end offset is the next's start, so no baseline text lies
|
|
139
|
+
* between them), or unified-diff `+` lines. Authoritative enforcement belongs to the server. */
|
|
140
|
+
export function refuseReadingViewPatch(patch, format, baseline) {
|
|
141
|
+
if (baseline !== undefined) {
|
|
142
|
+
const target = format === "diff" ? applyUnifiedDiff(baseline, patch) : applyInlineDff(baseline, patch);
|
|
143
|
+
if (target !== null) {
|
|
144
|
+
refuseNewReadingViewLines(baseline, target, "the patch");
|
|
145
|
+
return;
|
|
146
|
+
}
|
|
147
|
+
}
|
|
148
|
+
if (format === "diff") {
|
|
149
|
+
for (const line of patch.split("\n"))
|
|
150
|
+
if (line.startsWith("+") && !line.startsWith("+++ "))
|
|
151
|
+
refuseReadingView(line.slice(1), "the patch");
|
|
152
|
+
return;
|
|
153
|
+
}
|
|
154
|
+
const hunks = inlineInsertions(patch);
|
|
155
|
+
if (hunks === null) {
|
|
156
|
+
for (const match of patch.matchAll(/\{\+((?:\\[\s\S]|[^\\])*?)\+\}/g))
|
|
157
|
+
refuseReadingView(decodeInline(match[1]), "the patch");
|
|
158
|
+
return;
|
|
159
|
+
}
|
|
160
|
+
let run = "", previousEnd = -1;
|
|
161
|
+
for (const hunk of hunks) {
|
|
162
|
+
run = hunk.start === previousEnd ? run + hunk.added : hunk.added;
|
|
163
|
+
previousEnd = hunk.end;
|
|
164
|
+
refuseReadingView(run, "the patch");
|
|
165
|
+
}
|
|
166
|
+
}
|
|
167
|
+
function inlineLiteral(text) {
|
|
168
|
+
return text.replace(/[\\\n\r\t\[\]{}+\-]/g, char => char === "\n" ? "\\n" : char === "\r" ? "\\r" : char === "\t" ? "\\t" : `\\${char}`);
|
|
169
|
+
}
|
|
170
|
+
/** Exact original-source spans, with untouched gaps omitted from the PATCH. The target the edits
|
|
171
|
+
* produce is reconstructed and checked against the baseline, so a generated header assembled from
|
|
172
|
+
* several spans is refused exactly as a whole-body write would be. */
|
|
173
|
+
export function documentEdits(source, edits, exact = false) {
|
|
174
|
+
const points = Array.from(source.content);
|
|
175
|
+
let lastEnd = 0, lastStart = -1, target = "";
|
|
176
|
+
const hunks = [];
|
|
177
|
+
for (const edit of edits) {
|
|
178
|
+
if (!Number.isSafeInteger(edit.start) || !Number.isSafeInteger(edit.end) || edit.start < lastEnd
|
|
179
|
+
|| edit.start <= lastStart || edit.end < edit.start || edit.end > points.length) {
|
|
180
|
+
throw new Error("Edit spans must be ordered and disjoint within the original source");
|
|
181
|
+
}
|
|
182
|
+
target += points.slice(lastEnd, edit.start).join("") + edit.text;
|
|
183
|
+
lastStart = edit.start;
|
|
184
|
+
lastEnd = edit.end;
|
|
185
|
+
const old = points.slice(edit.start, edit.end).join("");
|
|
186
|
+
if (old === edit.text)
|
|
187
|
+
continue;
|
|
188
|
+
hunks.push(`@@ chars ${edit.start}:${edit.end} @@\n~ ${old ? `[-${inlineLiteral(old)}-]` : ""}${edit.text ? `{+${inlineLiteral(edit.text)}+}` : ""}\n`);
|
|
189
|
+
}
|
|
190
|
+
refuseNewReadingViewLines(source.content, target + points.slice(lastEnd).join(""), "the edit");
|
|
191
|
+
return { format: "inline-dff", patch: hunks.join(""), baseRevision: source.revision, mode: exact ? "exact" : "merge" };
|
|
192
|
+
}
|
|
193
|
+
/** One literal insertion at an original-source Unicode code-point boundary. */
|
|
194
|
+
export function documentInsertion(source, at, text, exact = false) {
|
|
195
|
+
return documentEdits(source, [{ start: at, end: at, text }], exact);
|
|
196
|
+
}
|
|
197
|
+
/** Validate optional expected text, then use the same source-span compiler. */
|
|
3
198
|
export function noteEdits(source, edits, mode = "exact") {
|
|
4
199
|
const points = Array.from(source.content);
|
|
5
200
|
for (const edit of edits) {
|
|
@@ -1,5 +1,41 @@
|
|
|
1
|
-
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
1
|
+
export type NoteEventRequest = (url: string, options: {
|
|
2
|
+
token?: string | null;
|
|
3
|
+
headers?: Record<string, string>;
|
|
4
|
+
signal?: AbortSignal;
|
|
5
|
+
followRedirects?: boolean;
|
|
6
|
+
}) => Promise<Response>;
|
|
7
|
+
export type Selection = null | {
|
|
8
|
+
status: 'unresolved';
|
|
9
|
+
} | {
|
|
10
|
+
status: 'resolved';
|
|
11
|
+
anchor: number;
|
|
12
|
+
head: number;
|
|
13
|
+
start: number;
|
|
14
|
+
end: number;
|
|
15
|
+
unit: 'unicode-code-point';
|
|
16
|
+
text: string;
|
|
17
|
+
truncated: boolean;
|
|
18
|
+
};
|
|
19
|
+
export interface Participant {
|
|
20
|
+
client: string;
|
|
21
|
+
user: {
|
|
22
|
+
id: string;
|
|
23
|
+
name: string;
|
|
24
|
+
kind: 'human' | 'agent';
|
|
25
|
+
owner?: {
|
|
26
|
+
id: string;
|
|
27
|
+
name: string;
|
|
28
|
+
};
|
|
29
|
+
};
|
|
30
|
+
selection?: Selection;
|
|
31
|
+
}
|
|
32
|
+
export interface NoteEvent {
|
|
33
|
+
type: 'observation';
|
|
34
|
+
note: string;
|
|
35
|
+
hash: string;
|
|
36
|
+
observedAt: number;
|
|
37
|
+
participants: Participant[];
|
|
38
|
+
activityVersion: string;
|
|
39
|
+
}
|
|
40
|
+
/** Explicit-token adapter: no login files, telemetry or process state. */
|
|
5
41
|
export declare function readNoteEvents(url: string, token: string, note: string, signal: AbortSignal, receive: (event: NoteEvent) => void, request?: NoteEventRequest): Promise<void>;
|
package/dist/api/note-events.js
CHANGED
|
@@ -1,6 +1,59 @@
|
|
|
1
|
-
/**
|
|
2
|
-
import { readNoteEvents as readEvents } from "../cli/notes/events.js";
|
|
1
|
+
/** Notes SSE parser over an injected request; the CLI supplies its own `requestRaw`. */
|
|
3
2
|
import { httpResponse, HttpError } from "./http.js";
|
|
3
|
+
/** Fetch SSE with auth headers, abort/idle bounds, and no automatic replay across gaps. */
|
|
4
|
+
async function readEvents(url, token, note, signal, receive, request) {
|
|
5
|
+
const idle = new AbortController();
|
|
6
|
+
let timer;
|
|
7
|
+
const touch = () => { clearTimeout(timer); timer = setTimeout(() => idle.abort(new Error('Notes event stream timed out')), 45000); };
|
|
8
|
+
touch();
|
|
9
|
+
let reader;
|
|
10
|
+
try {
|
|
11
|
+
const res = await request(url, { token, headers: { Accept: 'text/event-stream' },
|
|
12
|
+
signal: AbortSignal.any([signal, idle.signal]), followRedirects: false });
|
|
13
|
+
if (!/^text\/event-stream(?:;|$)/i.test(res.headers.get('content-type') ?? '') || !res.body)
|
|
14
|
+
throw new Error('server does not support Notes events; upgrade the server');
|
|
15
|
+
reader = res.body.getReader();
|
|
16
|
+
const decoder = new TextDecoder('utf-8', { fatal: true });
|
|
17
|
+
let buffer = '', data = [], frameSize = 0;
|
|
18
|
+
while (!signal.aborted) {
|
|
19
|
+
const { done, value } = await reader.read();
|
|
20
|
+
if (done)
|
|
21
|
+
throw new Error('Notes event stream disconnected; run --linger again for a fresh snapshot');
|
|
22
|
+
touch();
|
|
23
|
+
buffer += decoder.decode(value, { stream: true });
|
|
24
|
+
if (buffer.length > 4_000_000)
|
|
25
|
+
throw new Error('Notes event frame exceeds limit');
|
|
26
|
+
let newline;
|
|
27
|
+
while ((newline = buffer.indexOf('\n')) >= 0) {
|
|
28
|
+
const line = buffer.slice(0, newline).replace(/\r$/, '');
|
|
29
|
+
buffer = buffer.slice(newline + 1);
|
|
30
|
+
if (line.startsWith('data:')) {
|
|
31
|
+
const part = line.slice(5).replace(/^ /, '');
|
|
32
|
+
frameSize += part.length;
|
|
33
|
+
if (frameSize > 4_000_000)
|
|
34
|
+
throw new Error('Notes event frame exceeds limit');
|
|
35
|
+
data.push(part);
|
|
36
|
+
}
|
|
37
|
+
else if (!line && data.length) {
|
|
38
|
+
const event = JSON.parse(data.join('\n'));
|
|
39
|
+
data = [];
|
|
40
|
+
frameSize = 0;
|
|
41
|
+
if (event.type === 'error')
|
|
42
|
+
throw new Error(`Notes event stream ended (${String(event.error)})`);
|
|
43
|
+
if (event.type !== 'observation' || event.note !== note || !/^sha256:[a-f0-9]{64}$/.test(event.hash) ||
|
|
44
|
+
!Array.isArray(event.participants) || typeof event.activityVersion !== 'string')
|
|
45
|
+
throw new Error('invalid Notes event response');
|
|
46
|
+
receive(event);
|
|
47
|
+
}
|
|
48
|
+
}
|
|
49
|
+
}
|
|
50
|
+
}
|
|
51
|
+
finally {
|
|
52
|
+
clearTimeout(timer);
|
|
53
|
+
await reader?.cancel().catch(() => { });
|
|
54
|
+
}
|
|
55
|
+
}
|
|
56
|
+
/** Explicit-token adapter: no login files, telemetry or process state. */
|
|
4
57
|
export function readNoteEvents(url, token, note, signal, receive, request) {
|
|
5
58
|
return readEvents(url, token, note, signal, receive, request ?? (async (url, options = {}) => {
|
|
6
59
|
const response = await httpResponse(url, { token: options.token, headers: options.headers, signal: options.signal, redirect: "manual" });
|
|
@@ -0,0 +1,268 @@
|
|
|
1
|
+
import { type Transport } from "./client.js";
|
|
2
|
+
import { type NoteSource } from "./note-edits.js";
|
|
3
|
+
import * as editing from "./note-editing.js";
|
|
4
|
+
import { type NoteFocusedRead } from "./note-reading.js";
|
|
5
|
+
import { type NoteCommandStatus, type NoteWriteMode, type NoteWriteReceipt } from "./note-write.js";
|
|
6
|
+
import { type NoteRow, type NotesApi, type NoteVersion } from "./notes.js";
|
|
7
|
+
/** `{note, content, hash, revision}`: four distinct values. A hash describes text; a revision is the write baseline. */
|
|
8
|
+
export type NoteSnapshot = NoteSource;
|
|
9
|
+
/** A qualified reference: the first `/` separates the lookup namespace from a 24-hex id or a slug. */
|
|
10
|
+
export type NoteRef = `${string}/${string}`;
|
|
11
|
+
/** Where an edit was planned from: the snapshot it was read from (preferred) or its bare revision string. */
|
|
12
|
+
export type NoteRevisionRef = NoteSnapshot | string;
|
|
13
|
+
type Hex = "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9" | "a" | "b" | "c" | "d" | "e" | "f" | "A" | "B" | "C" | "D" | "E" | "F";
|
|
14
|
+
/** True for a 24-hex literal type (one character per recursion step; no union expansion). */
|
|
15
|
+
type IsHexId<S extends string, N extends unknown[] = []> = N["length"] extends 24 ? (S extends "" ? true : false) : S extends `${Hex}${infer Rest}` ? IsHexId<Rest, [...N, 0]> : false;
|
|
16
|
+
/** What `dl.notes(x)` returns at the type level, matching the runtime dispatch: a 24-hex literal or a
|
|
17
|
+
* literal with a `/` is a NoteHandle, any other literal is the namespace-scoped API, and a plain `string`
|
|
18
|
+
* may be either, so narrow it (`"ref" in value`) or use `dl.notes.open(id)` / `dl.notes.namespace(ns)`. */
|
|
19
|
+
export type NotesFor<S extends string> = S extends NoteRef ? NoteHandle : string extends S ? NoteHandle | NotesApi : IsHexId<S> extends true ? NoteHandle : NotesApi;
|
|
20
|
+
export declare class NoteReferenceInvalid extends Error {
|
|
21
|
+
constructor(ref: string);
|
|
22
|
+
}
|
|
23
|
+
export declare class RevisionExpected extends Error {
|
|
24
|
+
constructor(message: string);
|
|
25
|
+
}
|
|
26
|
+
export declare class ModeRequired extends Error {
|
|
27
|
+
constructor(received: unknown);
|
|
28
|
+
}
|
|
29
|
+
/** The Note's metadata was created but its initial source was not written (`definite`) or not confirmed
|
|
30
|
+
* (`uncertain`). Retry by writing or appending to `note`; creating again would make a second Note. */
|
|
31
|
+
export declare class NoteCreatedWithoutSource extends Error {
|
|
32
|
+
readonly note: string;
|
|
33
|
+
readonly namespace: string;
|
|
34
|
+
readonly outcome: "definite" | "uncertain";
|
|
35
|
+
constructor(note: string, namespace: string, outcome: "definite" | "uncertain", options?: {
|
|
36
|
+
cause?: unknown;
|
|
37
|
+
});
|
|
38
|
+
}
|
|
39
|
+
/** A write through a handle with an explicit namespace found the note elsewhere: the asserted scope no longer
|
|
40
|
+
* holds it. Nothing was written; reopen the note by id (or with the discovered owner) and reconcile. */
|
|
41
|
+
export declare class NoteMoved extends Error {
|
|
42
|
+
readonly note: string;
|
|
43
|
+
readonly namespace: string;
|
|
44
|
+
readonly owner: string;
|
|
45
|
+
constructor(note: string, namespace: string, owner: string, options?: {
|
|
46
|
+
cause?: unknown;
|
|
47
|
+
});
|
|
48
|
+
}
|
|
49
|
+
/** A documented target this client (or the current server) does not implement; nothing is invented in its place. */
|
|
50
|
+
export declare class UnsupportedTarget extends Error {
|
|
51
|
+
constructor(what: string);
|
|
52
|
+
}
|
|
53
|
+
export interface NoteReadOptions {
|
|
54
|
+
/** `source` (default) returns the exact snapshot; `mapped` the addressed Markdown reading view. */
|
|
55
|
+
view?: "source" | "mapped";
|
|
56
|
+
/** Read a retained revision instead of the current one. */
|
|
57
|
+
at?: NoteRevisionRef;
|
|
58
|
+
/** Two integers, 1-based and inclusive: only that exact source slice, with its global address. */
|
|
59
|
+
lines?: [number, number];
|
|
60
|
+
/** Mapped scope: one section (`s1`) ... */
|
|
61
|
+
section?: string;
|
|
62
|
+
/** ... or one observed element (`s1.p2`). */
|
|
63
|
+
address?: string;
|
|
64
|
+
}
|
|
65
|
+
/** The reading view is read-only: its hints are generated and must never be written back. */
|
|
66
|
+
export interface NoteMappedRead {
|
|
67
|
+
note: string;
|
|
68
|
+
hash: string;
|
|
69
|
+
revision: string;
|
|
70
|
+
view: "mapped";
|
|
71
|
+
sourceType: "markdown" | "html";
|
|
72
|
+
scope: string;
|
|
73
|
+
text: string;
|
|
74
|
+
}
|
|
75
|
+
interface Identified {
|
|
76
|
+
at: NoteRevisionRef;
|
|
77
|
+
mode?: NoteWriteMode;
|
|
78
|
+
commandId?: string;
|
|
79
|
+
}
|
|
80
|
+
export interface NoteAppendInput extends Identified {
|
|
81
|
+
text: string;
|
|
82
|
+
}
|
|
83
|
+
export interface NoteReplaceInput extends Identified {
|
|
84
|
+
text: string;
|
|
85
|
+
lines?: [number, number];
|
|
86
|
+
address?: string;
|
|
87
|
+
}
|
|
88
|
+
export interface NoteInsertInput extends Identified {
|
|
89
|
+
text: string;
|
|
90
|
+
before?: string;
|
|
91
|
+
after?: string;
|
|
92
|
+
cursor?: number;
|
|
93
|
+
}
|
|
94
|
+
export interface NoteRemoveInput extends Identified {
|
|
95
|
+
lines?: [number, number];
|
|
96
|
+
address?: string;
|
|
97
|
+
}
|
|
98
|
+
export interface NoteWriteInput {
|
|
99
|
+
text: string;
|
|
100
|
+
at: NoteRevisionRef;
|
|
101
|
+
mode: NoteWriteMode;
|
|
102
|
+
commandId?: string;
|
|
103
|
+
}
|
|
104
|
+
export interface NotePatchInput {
|
|
105
|
+
patch: string;
|
|
106
|
+
format: "inline-dff" | "diff";
|
|
107
|
+
at: NoteRevisionRef;
|
|
108
|
+
mode: NoteWriteMode;
|
|
109
|
+
commandId?: string;
|
|
110
|
+
}
|
|
111
|
+
export interface NoteFindInput {
|
|
112
|
+
text?: string;
|
|
113
|
+
regex?: string;
|
|
114
|
+
flags?: string;
|
|
115
|
+
caseSensitive?: boolean;
|
|
116
|
+
limit?: number;
|
|
117
|
+
at?: NoteRevisionRef;
|
|
118
|
+
}
|
|
119
|
+
export interface NoteFindResult {
|
|
120
|
+
note: string;
|
|
121
|
+
hash: string;
|
|
122
|
+
revision: string;
|
|
123
|
+
matches: editing.Match[];
|
|
124
|
+
}
|
|
125
|
+
export interface NoteOutline {
|
|
126
|
+
note: string;
|
|
127
|
+
revision: string;
|
|
128
|
+
hash: string;
|
|
129
|
+
entries: ReturnType<typeof import("./note-toc.js").markdownToc>;
|
|
130
|
+
}
|
|
131
|
+
/** The v2 incremental read: `patch` applies to source whose hash is `base` (retained at `baseRevision` when
|
|
132
|
+
* `since` named a revision) and yields `hash` at `revision`; `since` echoes a resolved time/hash reference. */
|
|
133
|
+
export interface NoteDiff {
|
|
134
|
+
note: string;
|
|
135
|
+
base: string;
|
|
136
|
+
/** The retained revision the patch applies from; present when `since` was an RTC revision. */
|
|
137
|
+
baseRevision?: string;
|
|
138
|
+
hash: string;
|
|
139
|
+
revision: string;
|
|
140
|
+
format: "diff" | "inline-dff";
|
|
141
|
+
patch: string;
|
|
142
|
+
since?: string;
|
|
143
|
+
}
|
|
144
|
+
export interface NoteMoveInput {
|
|
145
|
+
toNamespace?: string;
|
|
146
|
+
toProject?: string;
|
|
147
|
+
toFolder?: string;
|
|
148
|
+
name?: string;
|
|
149
|
+
dryRun?: boolean;
|
|
150
|
+
}
|
|
151
|
+
export interface NoteVisitInput {
|
|
152
|
+
intent?: string;
|
|
153
|
+
address?: string;
|
|
154
|
+
cursor?: number;
|
|
155
|
+
at?: NoteRevisionRef;
|
|
156
|
+
}
|
|
157
|
+
export interface NoteHandle {
|
|
158
|
+
readonly ref: string;
|
|
159
|
+
/** The lookup namespace, once known (given, qualified, or read from the note's metadata). */
|
|
160
|
+
readonly namespace: string | undefined;
|
|
161
|
+
/** The id or slug the handle was opened with. */
|
|
162
|
+
readonly note: string;
|
|
163
|
+
read(options: NoteReadOptions & {
|
|
164
|
+
lines: [number, number];
|
|
165
|
+
}): Promise<NoteFocusedRead>;
|
|
166
|
+
read(options?: NoteReadOptions & {
|
|
167
|
+
view?: "source";
|
|
168
|
+
lines?: undefined;
|
|
169
|
+
}): Promise<NoteSnapshot>;
|
|
170
|
+
read(options: NoteReadOptions & {
|
|
171
|
+
view: "mapped";
|
|
172
|
+
lines?: undefined;
|
|
173
|
+
}): Promise<NoteMappedRead>;
|
|
174
|
+
/** Append `text` verbatim at the original document end (no separator is added). Merge unless `mode: "exact"`. */
|
|
175
|
+
append(input: NoteAppendInput): Promise<NoteWriteReceipt>;
|
|
176
|
+
/** Replace the exact span selected by `lines` or `address` with `text` (empty text deletes it). */
|
|
177
|
+
replace(input: NoteReplaceInput): Promise<NoteWriteReceipt>;
|
|
178
|
+
/** Insert `text` verbatim before/after an element's full original span, or at a code-point `cursor`. */
|
|
179
|
+
insert(input: NoteInsertInput): Promise<NoteWriteReceipt>;
|
|
180
|
+
/** Remove the exact span selected by `lines` or `address`; never the Note resource. */
|
|
181
|
+
remove(input: NoteRemoveInput): Promise<NoteWriteReceipt>;
|
|
182
|
+
/** Replace the whole source read at `at` with `text`, as a code-point diff; `mode` is explicit. */
|
|
183
|
+
write(input: NoteWriteInput): Promise<NoteWriteReceipt>;
|
|
184
|
+
/** Apply an explicit source patch (`inline-dff` or unified `diff`) against `at`; `mode` is explicit. */
|
|
185
|
+
patch(input: NotePatchInput): Promise<NoteWriteReceipt>;
|
|
186
|
+
outline(options?: {
|
|
187
|
+
at?: NoteRevisionRef;
|
|
188
|
+
}): Promise<NoteOutline>;
|
|
189
|
+
find(input: NoteFindInput): Promise<NoteFindResult>;
|
|
190
|
+
diff(input: {
|
|
191
|
+
since: string;
|
|
192
|
+
format?: "diff" | "inline-dff";
|
|
193
|
+
}): Promise<NoteDiff>;
|
|
194
|
+
presence(): Promise<unknown>;
|
|
195
|
+
/** Announce the caller once. `address`/`cursor` locations are a documented target (UnsupportedTarget today). */
|
|
196
|
+
visit(input?: NoteVisitInput): Promise<unknown>;
|
|
197
|
+
versions: {
|
|
198
|
+
list(options?: {
|
|
199
|
+
before?: string;
|
|
200
|
+
}): Promise<{
|
|
201
|
+
versions: NoteVersion[];
|
|
202
|
+
nextCursor?: string | null;
|
|
203
|
+
}>;
|
|
204
|
+
read(input: {
|
|
205
|
+
versionId: string;
|
|
206
|
+
}): Promise<NoteVersion>;
|
|
207
|
+
};
|
|
208
|
+
files: {
|
|
209
|
+
move(input: {
|
|
210
|
+
file: string;
|
|
211
|
+
toFolder?: string;
|
|
212
|
+
name?: string;
|
|
213
|
+
}): Promise<unknown>;
|
|
214
|
+
};
|
|
215
|
+
/** Workspace/project filing through the existing move contract; `toFolder` and `name` are documented targets (UnsupportedTarget today). */
|
|
216
|
+
move(input: NoteMoveInput): Promise<unknown>;
|
|
217
|
+
/** The durable record behind a `commandId` sent earlier. */
|
|
218
|
+
commandStatus(commandId: string): Promise<NoteCommandStatus>;
|
|
219
|
+
}
|
|
220
|
+
export type CreatedNote = NoteHandle & {
|
|
221
|
+
id: string;
|
|
222
|
+
created: NoteRow;
|
|
223
|
+
};
|
|
224
|
+
export interface NotesFacade {
|
|
225
|
+
/** With explicit namespace context any reference (id or bare slug) opens a handle; the slug resolves lazily in that namespace. */
|
|
226
|
+
(ref: string, context: {
|
|
227
|
+
namespace: string;
|
|
228
|
+
}): NoteHandle;
|
|
229
|
+
<S extends string>(ref: S, context?: {
|
|
230
|
+
namespace?: string;
|
|
231
|
+
}): NotesFor<S>;
|
|
232
|
+
/** A handle for a dynamic `string` id or qualified reference, typed as a handle. */
|
|
233
|
+
open(ref: string, context?: {
|
|
234
|
+
namespace?: string;
|
|
235
|
+
}): NoteHandle;
|
|
236
|
+
list(options: {
|
|
237
|
+
namespace: string;
|
|
238
|
+
q?: string;
|
|
239
|
+
limit?: number;
|
|
240
|
+
offset?: number;
|
|
241
|
+
includeArchived?: boolean;
|
|
242
|
+
}): Promise<{
|
|
243
|
+
notes: NoteRow[];
|
|
244
|
+
}>;
|
|
245
|
+
/** Create a Note (title defaults to Untitled) and, with `text`, initialize its source. Returns a usable handle.
|
|
246
|
+
* If the metadata is created but the source write fails, the error is a NoteCreatedWithoutSource carrying the id. */
|
|
247
|
+
create(options: {
|
|
248
|
+
namespace: string;
|
|
249
|
+
name?: string;
|
|
250
|
+
text?: string;
|
|
251
|
+
visibility?: "private" | "public";
|
|
252
|
+
projects?: string[];
|
|
253
|
+
}): Promise<CreatedNote>;
|
|
254
|
+
/** The namespace-scoped API for a dynamic namespace (a bare literal, `dl.notes("fortyfive")`, is the same object). */
|
|
255
|
+
namespace(namespace: string): NotesApi;
|
|
256
|
+
}
|
|
257
|
+
export declare function parseNoteRef(ref: string): {
|
|
258
|
+
namespace: string;
|
|
259
|
+
note: string;
|
|
260
|
+
};
|
|
261
|
+
/** The baseline an edit was planned from: a snapshot's own revision, or the bare string. */
|
|
262
|
+
export declare function revisionOf(at: NoteRevisionRef): string;
|
|
263
|
+
export declare function noteHandle(t: Transport, ref: string, context?: {
|
|
264
|
+
namespace?: string;
|
|
265
|
+
}): NoteHandle;
|
|
266
|
+
/** `dl.notes`: open one note by stable id or `"namespace/note"`, or reach the namespace API with a bare namespace literal. */
|
|
267
|
+
export declare function notesFacade(t: Transport): NotesFacade;
|
|
268
|
+
export {};
|