@staix/vault-mem 0.9.1 → 0.10.1
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/CHANGELOG.md +31 -0
- package/README.md +19 -6
- package/bin/vmem.js +2 -2
- package/package.json +2 -2
- package/src/analysis-commands.ts +24 -14
- package/src/analysis-input.ts +12 -0
- package/src/analysis-types.ts +5 -1
- package/src/assert-command.ts +48 -0
- package/src/assertion-exposure.ts +367 -0
- package/src/assertion-index.ts +86 -0
- package/src/assertion-policy.ts +63 -0
- package/src/assertion-read.ts +170 -0
- package/src/assertions-command.ts +123 -0
- package/src/assertions.ts +1013 -0
- package/src/cli-output.ts +9 -3
- package/src/cli.ts +44 -23
- package/src/commands-table.ts +16 -2
- package/src/evidence.ts +222 -0
- package/src/graph-evidence.ts +169 -0
- package/src/index.ts +14 -0
- package/src/links.ts +18 -0
- package/src/log-commands.ts +7 -7
- package/src/mcp-spec.ts +11 -11
- package/src/mcp-vault.ts +105 -6
- package/src/mcp.ts +4 -0
- package/src/org-commands.ts +5 -5
- package/src/org-promote.ts +9 -0
- package/src/promote-command.ts +6 -6
- package/src/proposal-commands.ts +100 -0
- package/src/proposal-provider.ts +335 -0
- package/src/proposal-storage.ts +334 -0
- package/src/proposals.ts +170 -0
- package/src/read-commands.ts +44 -12
- package/src/read-output.ts +42 -14
- package/src/skills-mine.ts +12 -7
- package/src/source-age.ts +131 -0
- package/src/spec-output.ts +14 -13
- package/src/sync.ts +14 -7
- package/src/text-output.ts +86 -21
- package/src/vault-brief.ts +8 -4
- package/src/vault-graph.ts +12 -3
- package/src/vault-history.ts +662 -0
- package/src/vault-index.ts +2 -0
- package/src/vault-lint.ts +15 -4
- package/src/write-commands.ts +18 -17
- package/src/write-output.ts +6 -6
- package/src/write-types.ts +1 -0
- package/src/write-validation.ts +3 -1
- package/src/writer.ts +257 -11
|
@@ -0,0 +1,662 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Read-only Git snapshot history for a registered vault (#235). Git commits are snapshot boundaries; this provider
|
|
3
|
+
* never writes, checks out, fetches or reads commit messages/authors. Every object id is a full SHA-1/SHA-256 commit
|
|
4
|
+
* reachable from the vault HEAD, resolved once and pinned for the request. Current note policy (denied paths, UTF-8,
|
|
5
|
+
* symlink and size rules) also applies to historical blobs.
|
|
6
|
+
*/
|
|
7
|
+
import { spawnSync } from "node:child_process";
|
|
8
|
+
import { createHash } from "node:crypto";
|
|
9
|
+
import { realpathSync } from "node:fs";
|
|
10
|
+
import { join } from "node:path";
|
|
11
|
+
import { isDenied, memoryGitArgv, memoryGitEnv } from "./platform.ts";
|
|
12
|
+
import { VaultIndex, MAX_NOTE_BYTES, MAX_READ_BYTES, h2Sections, headingMetadata, readPage } from "./vault-index.ts";
|
|
13
|
+
import { parseFrontmatter } from "./frontmatter.ts";
|
|
14
|
+
import { blocks, clean, fields, heading, nextCommand, paint, plural, shellWord, status, stripTerminal, summary, table, tone, type TextOptions } from "./text-output.ts";
|
|
15
|
+
import type { VaultSpec } from "./config.ts";
|
|
16
|
+
|
|
17
|
+
export const SNAPSHOT_SCHEMA_VERSION = 1;
|
|
18
|
+
/** Note revisions per history page, and commits a single request may scan. */
|
|
19
|
+
export const HISTORY_PAGE_LIMIT = 100;
|
|
20
|
+
export const HISTORY_SCAN_LIMIT = 1000;
|
|
21
|
+
export const CHANGES_PAGE_LIMIT = 500;
|
|
22
|
+
/** One Git subprocess deadline per request, shared by every call it makes. */
|
|
23
|
+
export const SNAPSHOT_DEADLINE_MS = 5000;
|
|
24
|
+
/**
|
|
25
|
+
* A complete CLI/MCP response, envelope and escaping included, stays within 48 KiB. This is the only result cap: it is
|
|
26
|
+
* tighter than the 256 KiB aggregate the transport accepts, so a page is trimmed to fit instead of being refused there.
|
|
27
|
+
*/
|
|
28
|
+
export const SNAPSHOT_TRANSPORT_BYTES = 48 * 1024;
|
|
29
|
+
/**
|
|
30
|
+
* The MCP transport measures a handler's result after stringifying it into the JSON-RPC frame, so every payload byte
|
|
31
|
+
* is counted twice through its escaping. This reserves the frame around it: `{"jsonrpc":"2.0","id":…,"result":
|
|
32
|
+
* {"content":[{"type":"text","text":…}]}}` with a request id of at most 200 characters, plus the newline.
|
|
33
|
+
*/
|
|
34
|
+
const FRAME_RESERVE = 512;
|
|
35
|
+
/** A cursor carries one note path (at most 1024 bytes), up to two commit ids and its JSON keys, base64url-expanded. */
|
|
36
|
+
export const SNAPSHOT_CURSOR_CHARS = 4 * (1024 + 64 + 64 + 160);
|
|
37
|
+
const LOG_BUFFER_BYTES = 1024 * 1024;
|
|
38
|
+
const DIFF_BUFFER_BYTES = 4 * 1024 * 1024;
|
|
39
|
+
const BATCH_BUFFER_BYTES = 64 * 1024;
|
|
40
|
+
const STATUS_BUFFER_BYTES = 1024 * 1024;
|
|
41
|
+
const FULL_OID = /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/;
|
|
42
|
+
const NOTE_PATH = /^notes\/(?:[^/]+\/)*[^/]+\.md$/;
|
|
43
|
+
const ZERO_OID = /^0+$/;
|
|
44
|
+
type GitOutcome = { status: number | null; stdout: Buffer; stderr: string };
|
|
45
|
+
type GitOptions = { input?: string | Buffer; maxBuffer?: number; allowFail?: boolean; env?: NodeJS.ProcessEnv };
|
|
46
|
+
|
|
47
|
+
/** Why a snapshot read cannot answer, reported as a result rather than as current content. */
|
|
48
|
+
export type SnapshotCapability = "not_a_repository" | "vault_not_repository_root" | "git_unavailable" | "no_commits" | "shallow_history" | "object_unavailable";
|
|
49
|
+
export interface SnapshotCoverage { complete: boolean; reason?: string }
|
|
50
|
+
export interface SnapshotBase {
|
|
51
|
+
schemaVersion: number;
|
|
52
|
+
basis: "git_snapshot";
|
|
53
|
+
vault: string;
|
|
54
|
+
head: string | null;
|
|
55
|
+
firstParent: true;
|
|
56
|
+
renamePolicy: "exact_path";
|
|
57
|
+
timeBasis: "git_commit_metadata_not_assertion_time";
|
|
58
|
+
coverage: SnapshotCoverage;
|
|
59
|
+
capability?: SnapshotCapability;
|
|
60
|
+
dirtyNotes: number | null;
|
|
61
|
+
dirtyNotesReason?: string;
|
|
62
|
+
}
|
|
63
|
+
export interface HistoryRevision { revision: string; blob: string; bytes: number; committedAt: string }
|
|
64
|
+
export type HistoryStopReason = "page_full" | "scan_limit" | "history_end" | "unsupported" | "transport_limit";
|
|
65
|
+
export interface HistoryResult extends SnapshotBase {
|
|
66
|
+
path: string;
|
|
67
|
+
revisions: HistoryRevision[];
|
|
68
|
+
scanned: number;
|
|
69
|
+
scanLimit: number;
|
|
70
|
+
pageLimit: number;
|
|
71
|
+
stopReason: HistoryStopReason;
|
|
72
|
+
truncated: boolean;
|
|
73
|
+
continuation?: string;
|
|
74
|
+
skippedSymlink: number;
|
|
75
|
+
}
|
|
76
|
+
export interface RevisionResult extends SnapshotBase {
|
|
77
|
+
path: string;
|
|
78
|
+
found: boolean;
|
|
79
|
+
revision?: string;
|
|
80
|
+
blob?: string;
|
|
81
|
+
sha256?: string;
|
|
82
|
+
bytes?: number;
|
|
83
|
+
content?: string;
|
|
84
|
+
truncated?: boolean;
|
|
85
|
+
section?: string;
|
|
86
|
+
offset?: number;
|
|
87
|
+
nextOffset?: number;
|
|
88
|
+
headings?: string[];
|
|
89
|
+
headingsTruncated?: boolean;
|
|
90
|
+
transportLimited?: boolean;
|
|
91
|
+
}
|
|
92
|
+
export type ChangeStatus = "A" | "M" | "D" | "T";
|
|
93
|
+
export interface ChangedNote { path: string; status: ChangeStatus; before: string | null; after: string | null }
|
|
94
|
+
export interface ChangesResult extends SnapshotBase {
|
|
95
|
+
from: string;
|
|
96
|
+
to: string;
|
|
97
|
+
changed: ChangedNote[];
|
|
98
|
+
total: number;
|
|
99
|
+
truncated: boolean;
|
|
100
|
+
continuation?: string;
|
|
101
|
+
skippedDenied: number;
|
|
102
|
+
skippedSymlink: number;
|
|
103
|
+
}
|
|
104
|
+
export interface SnapshotRequestBase { vault: VaultSpec; home: string; denyPaths?: readonly string[]; env?: NodeJS.ProcessEnv }
|
|
105
|
+
export interface HistoryRequest extends SnapshotRequestBase { note: string; limit?: number; cursor?: string }
|
|
106
|
+
export interface RevisionRequest extends SnapshotRequestBase { note: string; revision: string; maxBytes?: number; offset?: number; section?: string }
|
|
107
|
+
export interface ChangesRequest extends SnapshotRequestBase { from: string; to: string; limit?: number; cursor?: string }
|
|
108
|
+
/** Internal bounds for tests; public surfaces never pass these. */
|
|
109
|
+
export interface SnapshotLimits { pageLimit?: number; scanLimit?: number; deadlineMs?: number; transportBytes?: number }
|
|
110
|
+
|
|
111
|
+
function refuse(message: string, code = "V04"): never { throw Object.assign(new Error(message), { code }); }
|
|
112
|
+
function text(value: Buffer): string { return value.toString("utf8"); }
|
|
113
|
+
/** The bytes this result costs on the wire: stringified for `--json`, then escaped again inside the MCP frame. */
|
|
114
|
+
function byteLength(value: unknown): number { return Buffer.byteLength(JSON.stringify(JSON.stringify(value))); }
|
|
115
|
+
const fits = (value: unknown, transportBytes: number) => byteLength(value) <= transportBytes - FRAME_RESERVE;
|
|
116
|
+
function boundary(bytes: Buffer, proposed: number): number {
|
|
117
|
+
let end = Math.min(proposed, bytes.length);
|
|
118
|
+
while (end > 0 && end < bytes.length && (bytes[end]! & 0xc0) === 0x80) end--;
|
|
119
|
+
return end;
|
|
120
|
+
}
|
|
121
|
+
|
|
122
|
+
/**
|
|
123
|
+
* Hardened Git call: no pager, hooks, fsmonitor, external diff, prompts, lazy fetch or inherited Git directories. The
|
|
124
|
+
* extra `-c` entries pin the three settings a repository can still turn on by itself: `log.follow` renames a path
|
|
125
|
+
* projection, `log.showSignature` runs `gpg.program`, and that program is emptied here as well.
|
|
126
|
+
*/
|
|
127
|
+
const HARDENED_CONFIG = ["-c", "log.follow=false", "-c", "log.showSignature=false", "-c", "gpg.program="];
|
|
128
|
+
function historyGit(root: string, args: string[], deadline: number, options: GitOptions = {}): GitOutcome {
|
|
129
|
+
const remaining = deadline - Date.now();
|
|
130
|
+
if (remaining <= 0) refuse(`snapshot: the ${SNAPSHOT_DEADLINE_MS / 1000} s Git budget is spent; retry once the repository is responsive`, "V09");
|
|
131
|
+
const argv = memoryGitArgv([...HARDENED_CONFIG, "-C", root, ...args]);
|
|
132
|
+
const env = memoryGitEnv({ ...(options.env ?? process.env), GIT_OPTIONAL_LOCKS: "0", LC_ALL: "C" }, { repositoryIsolation: true, readOnlyDiagnostic: true });
|
|
133
|
+
// Literal pathspecs after the projection, which drops every inherited GIT_* key: a note path is never a glob.
|
|
134
|
+
env.GIT_LITERAL_PATHSPECS = "1";
|
|
135
|
+
const result = spawnSync(argv[0]!, argv.slice(1), {
|
|
136
|
+
env, timeout: remaining, maxBuffer: options.maxBuffer ?? 65536, stdio: ["pipe", "pipe", "pipe"],
|
|
137
|
+
...(options.input !== undefined ? { input: options.input } : {}),
|
|
138
|
+
});
|
|
139
|
+
if (result.error) {
|
|
140
|
+
const code = (result.error as NodeJS.ErrnoException).code;
|
|
141
|
+
if (code === "ENOENT") return { status: null, stdout: Buffer.alloc(0), stderr: "ENOENT" };
|
|
142
|
+
if (code === "ETIMEDOUT") refuse(`snapshot: Git exceeded the ${SNAPSHOT_DEADLINE_MS / 1000} s subprocess deadline; retry on a responsive repository`, "V09");
|
|
143
|
+
if (code === "ENOBUFS") refuse("snapshot: Git output exceeded its bounded buffer; narrow the request or the revision range", "V09");
|
|
144
|
+
refuse(`snapshot: Git could not run (${code ?? "spawn failure"}); install git or fix PATH`, "GIT");
|
|
145
|
+
}
|
|
146
|
+
const stdout = result.stdout ?? Buffer.alloc(0), stderr = result.stderr ? text(result.stderr) : "";
|
|
147
|
+
if (result.status === null) refuse(`snapshot: Git was terminated (signal ${result.signal ?? "unavailable"}); retry once the repository is responsive`, "V09");
|
|
148
|
+
if (result.status !== 0 && !options.allowFail) {
|
|
149
|
+
const first = stderr.split(/\r?\n/)[0] ?? "no diagnostic";
|
|
150
|
+
refuse(`snapshot: Git refused inspection (exit ${result.status}): ${first.slice(0, 240)}; check the repository with \`git fsck\` and repair it, then retry`, "V09");
|
|
151
|
+
}
|
|
152
|
+
return { status: result.status, stdout, stderr };
|
|
153
|
+
}
|
|
154
|
+
|
|
155
|
+
interface Snapshot {
|
|
156
|
+
root: string;
|
|
157
|
+
head: string;
|
|
158
|
+
shallow: boolean;
|
|
159
|
+
env: NodeJS.ProcessEnv;
|
|
160
|
+
deadline: number;
|
|
161
|
+
git(args: string[], options?: GitOptions): GitOutcome;
|
|
162
|
+
}
|
|
163
|
+
type Opened = { ok: true; snapshot: Snapshot } | { ok: false; capability: SnapshotCapability; reason?: string };
|
|
164
|
+
|
|
165
|
+
function openSnapshot(vault: VaultSpec, env: NodeJS.ProcessEnv, limits: SnapshotLimits): Opened {
|
|
166
|
+
const deadline = Date.now() + (limits.deadlineMs ?? SNAPSHOT_DEADLINE_MS);
|
|
167
|
+
let root: string;
|
|
168
|
+
try { root = realpathSync(vault.path); }
|
|
169
|
+
catch { return { ok: false, capability: "not_a_repository", reason: "the vault path is missing or unreadable" }; }
|
|
170
|
+
if (root !== vault.path) refuse(`vault ${vault.id}: registered path changed; re-register it with vmem vaults add and retry`);
|
|
171
|
+
const git = (args: string[], options: GitOptions = {}) => historyGit(root, args, deadline, { ...options, env });
|
|
172
|
+
const top = git(["rev-parse", "--show-toplevel"], { allowFail: true });
|
|
173
|
+
if (top.status !== 0) {
|
|
174
|
+
if (top.stderr.trim() === "ENOENT") return { ok: false, capability: "git_unavailable", reason: "git is not available on PATH" };
|
|
175
|
+
return { ok: false, capability: "not_a_repository", reason: top.stderr.split(/\r?\n/)[0]?.slice(0, 200) || "not a Git work tree" };
|
|
176
|
+
}
|
|
177
|
+
let toplevel: string;
|
|
178
|
+
try { toplevel = realpathSync(text(top.stdout).trim()); } catch { toplevel = text(top.stdout).trim(); }
|
|
179
|
+
if (toplevel !== root) return { ok: false, capability: "vault_not_repository_root", reason: "the registered vault root is not the repository top level" };
|
|
180
|
+
const shallow = text(git(["rev-parse", "--is-shallow-repository"], { allowFail: true }).stdout).trim() === "true";
|
|
181
|
+
const headOut = git(["rev-parse", "--verify", "--quiet", "HEAD^{commit}"], { allowFail: true });
|
|
182
|
+
const head = text(headOut.stdout).trim();
|
|
183
|
+
if (headOut.status !== 0 || !FULL_OID.test(head)) return { ok: false, capability: "no_commits", reason: "the vault HEAD names no commit" };
|
|
184
|
+
return { ok: true, snapshot: { root, head, shallow, env, deadline, git } };
|
|
185
|
+
}
|
|
186
|
+
|
|
187
|
+
function coverageOf(snapshot: Snapshot): SnapshotCoverage {
|
|
188
|
+
return snapshot.shallow ? { complete: false, reason: "shallow_history" } : { complete: true };
|
|
189
|
+
}
|
|
190
|
+
|
|
191
|
+
/**
|
|
192
|
+
* A repository clean filter is a command `.gitattributes` (never the note) selects, and `git status` runs it over every
|
|
193
|
+
* tracked note. `check-attr` only reads attributes, so it decides first whether the count can be taken at all.
|
|
194
|
+
*/
|
|
195
|
+
function cleanFilterPaths(git: Snapshot["git"]): { filtered: boolean; reason?: string } {
|
|
196
|
+
const listed = git(["ls-files", "-z", "--", "notes"], { allowFail: true, maxBuffer: STATUS_BUFFER_BYTES });
|
|
197
|
+
if (listed.status !== 0) return { filtered: false, reason: "Git could not list the tracked notes" };
|
|
198
|
+
if (!listed.stdout.length) return { filtered: false };
|
|
199
|
+
// The NUL-separated paths go back in as the bytes Git wrote, so a non-UTF-8 filename is not re-encoded.
|
|
200
|
+
const attrs = git(["check-attr", "-z", "--stdin", "filter"], { allowFail: true, input: listed.stdout, maxBuffer: STATUS_BUFFER_BYTES });
|
|
201
|
+
if (attrs.status !== 0) return { filtered: false, reason: "Git could not read the notes attributes" };
|
|
202
|
+
const tokens = text(attrs.stdout).split("\0");
|
|
203
|
+
for (let i = 2; i < tokens.length; i += 3) if (tokens[i] && tokens[i] !== "unspecified") return { filtered: true };
|
|
204
|
+
return { filtered: false };
|
|
205
|
+
}
|
|
206
|
+
|
|
207
|
+
function dirtyNoteCount(git: Snapshot["git"]): { count: number | null; reason?: string } {
|
|
208
|
+
const filter = cleanFilterPaths(git);
|
|
209
|
+
if (filter.filtered) return { count: null, reason: "a clean filter is configured for notes/; the dirty-note count is not taken" };
|
|
210
|
+
if (filter.reason) return { count: null, reason: filter.reason };
|
|
211
|
+
const out = git(["status", "--porcelain=v1", "-z", "--untracked-files=normal", "--", "notes"], { allowFail: true, maxBuffer: STATUS_BUFFER_BYTES });
|
|
212
|
+
if (out.status !== 0) return { count: null, reason: "git status is unavailable" };
|
|
213
|
+
const parts = text(out.stdout).split("\0").filter(Boolean);
|
|
214
|
+
let count = 0;
|
|
215
|
+
for (let i = 0; i < parts.length; i++) {
|
|
216
|
+
count++;
|
|
217
|
+
if (/[RC]/.test(parts[i]!.slice(0, 2))) i++;
|
|
218
|
+
}
|
|
219
|
+
return { count };
|
|
220
|
+
}
|
|
221
|
+
|
|
222
|
+
/** A full lowercase object id, never a revision expression, prefix or option-like string. */
|
|
223
|
+
function fullOid(value: string, label: string): string {
|
|
224
|
+
if (typeof value !== "string" || !FULL_OID.test(value)) {
|
|
225
|
+
refuse(`${label}: expected a full lowercase SHA-1 or SHA-256 commit id; prefixes, revision expressions and option-like input are refused`);
|
|
226
|
+
}
|
|
227
|
+
return value;
|
|
228
|
+
}
|
|
229
|
+
|
|
230
|
+
/**
|
|
231
|
+
* `notes/<path>.md` with no traversal, dot segment, backslash or control character; the only path shape historical
|
|
232
|
+
* reads accept. A control character is refused because Git's own line-oriented plumbing would read it as a second
|
|
233
|
+
* path expression.
|
|
234
|
+
*/
|
|
235
|
+
function notesPath(value: string): string | undefined {
|
|
236
|
+
if (!NOTE_PATH.test(value) || Buffer.byteLength(value) > 1024 || /[\\\u0000-\u001f]/.test(value)) return undefined;
|
|
237
|
+
const parts = value.split("/").slice(1);
|
|
238
|
+
return parts.some(part => part === "." || part === ".." || part.startsWith(".")) ? undefined : value;
|
|
239
|
+
}
|
|
240
|
+
|
|
241
|
+
/** Literal notes/ path, or the indexed note resolved by stem/alias exactly as `vmem show` does. */
|
|
242
|
+
function resolveNote(vault: VaultSpec, home: string, note: string): string {
|
|
243
|
+
const literal = notesPath(note);
|
|
244
|
+
if (literal) return literal;
|
|
245
|
+
const relative = typeof note === "string" ? note.replace(/^notes\//i, "") : "";
|
|
246
|
+
// A target is one note's stem or alias: no path separator, dot segment, backslash or control character.
|
|
247
|
+
if (!relative || Buffer.byteLength(note) > 1024 || /[/\\\u0000-\u001f]/.test(relative) || relative.startsWith(".")) {
|
|
248
|
+
refuse("note: expected a note target or a vault-relative notes/<path>.md path; other paths are not readable");
|
|
249
|
+
}
|
|
250
|
+
const index = new VaultIndex(home, vault, [vault.path], { memory: true });
|
|
251
|
+
try {
|
|
252
|
+
index.scan();
|
|
253
|
+
return `notes/${index.resolve(note)}`;
|
|
254
|
+
} catch (error) {
|
|
255
|
+
const message = error instanceof Error ? error.message : "note lookup failed";
|
|
256
|
+
if (message.startsWith("note:")) refuse(`${message}; pass the note's notes/<path>.md to read a deleted note's history`);
|
|
257
|
+
throw error;
|
|
258
|
+
} finally { index.close(); }
|
|
259
|
+
}
|
|
260
|
+
|
|
261
|
+
function assertReadable(path: string, root: string, denyPaths: readonly string[]): void {
|
|
262
|
+
if (isDenied(join(root, path), [...denyPaths])) refuse(`path: ${path} is denied by the built-in secret rules or registry denyPaths; nothing read`, "V06");
|
|
263
|
+
}
|
|
264
|
+
|
|
265
|
+
function commitParent(git: Snapshot["git"], commit: string): string | null {
|
|
266
|
+
const out = git(["rev-parse", "--verify", "--quiet", `${commit}^`], { allowFail: true });
|
|
267
|
+
const parent = text(out.stdout).trim();
|
|
268
|
+
return out.status === 0 && FULL_OID.test(parent) ? parent : null;
|
|
269
|
+
}
|
|
270
|
+
|
|
271
|
+
function reachable(git: Snapshot["git"], commit: string, head: string): void {
|
|
272
|
+
const out = git(["merge-base", "--is-ancestor", commit, head], { allowFail: true });
|
|
273
|
+
if (out.status === 1) refuse(`revision: ${commit} is not reachable from the vault HEAD; only commits reachable from HEAD are readable`, "V06");
|
|
274
|
+
if (out.status !== 0) refuse(`revision: reachability of ${commit} could not be checked (exit ${out.status}); inspect the repository`, "V09");
|
|
275
|
+
}
|
|
276
|
+
|
|
277
|
+
/**
|
|
278
|
+
* Whether `commit` sits on `pin`'s own first-parent chain, which is the walk a page continues from. Bounded by the
|
|
279
|
+
* scan limit: a chain longer than the bound cannot be proved, and is refused rather than walked further.
|
|
280
|
+
*/
|
|
281
|
+
function onFirstParentChain(git: Snapshot["git"], commit: string, pin: string, limit: number): boolean {
|
|
282
|
+
const out = git(["rev-list", "--first-parent", `--max-count=${limit + 1}`, pin], { allowFail: true, maxBuffer: LOG_BUFFER_BYTES });
|
|
283
|
+
if (out.status !== 0) refuse(`cursor: the first-parent chain of ${pin} could not be read (exit ${out.status}); restart without --cursor`, "V09");
|
|
284
|
+
return text(out.stdout).split("\n").some(line => line.trim() === commit);
|
|
285
|
+
}
|
|
286
|
+
|
|
287
|
+
/** Whether one object expression (`<commit>^{commit}` or a blob id) is present in this repository's object store. */
|
|
288
|
+
function objectAvailable(git: Snapshot["git"], expression: string): boolean {
|
|
289
|
+
return git(["cat-file", "-e", expression], { allowFail: true }).status === 0;
|
|
290
|
+
}
|
|
291
|
+
|
|
292
|
+
function commitObject(git: Snapshot["git"], value: string, label: string): string {
|
|
293
|
+
const commit = fullOid(value, label);
|
|
294
|
+
if (!objectAvailable(git, `${commit}^{commit}`)) refuse(`revision: ${commit} is not an available commit object; it may be pruned, shallow or belong to another repository. Pick a full commit id from \`vmem history <vault> <note>\``, "V09");
|
|
295
|
+
const resolved = text(git(["rev-parse", "--verify", "--quiet", `${commit}^{commit}`], { allowFail: true }).stdout).trim();
|
|
296
|
+
if (resolved !== commit) refuse(`revision: ${commit} does not name a commit object; pass the full commit id Git reported`, "V04");
|
|
297
|
+
return commit;
|
|
298
|
+
}
|
|
299
|
+
|
|
300
|
+
/** One record per commit that changed the note path, from `git log --first-parent --raw -z`. */
|
|
301
|
+
interface RawRecord { revision: string; committedAt: string; mode: string; status: string; blob: string }
|
|
302
|
+
function parseLogRaw(output: string, path: string): RawRecord[] {
|
|
303
|
+
const tokens = output.split("\0"), records: RawRecord[] = [];
|
|
304
|
+
let current: { revision: string; committedAt: string } | undefined;
|
|
305
|
+
for (let i = 0; i < tokens.length; i++) {
|
|
306
|
+
const token = tokens[i]!.replace(/^\n/, "");
|
|
307
|
+
if (!token) continue;
|
|
308
|
+
if (token.startsWith("\x01")) {
|
|
309
|
+
const [revision, committedAt] = token.slice(1).split("\t");
|
|
310
|
+
current = revision !== undefined && FULL_OID.test(revision) ? { revision, committedAt: committedAt ?? "" } : undefined;
|
|
311
|
+
continue;
|
|
312
|
+
}
|
|
313
|
+
if (!token.startsWith(":") || current === undefined) continue;
|
|
314
|
+
const parts = token.slice(1).split(" ");
|
|
315
|
+
const recordPath = tokens[++i] ?? "";
|
|
316
|
+
if (recordPath !== path) { current = undefined; continue; }
|
|
317
|
+
records.push({ ...current, mode: parts[1] ?? "", status: parts[4] ?? "", blob: parts[3] ?? "" });
|
|
318
|
+
current = undefined;
|
|
319
|
+
}
|
|
320
|
+
return records;
|
|
321
|
+
}
|
|
322
|
+
|
|
323
|
+
interface HistoryCursor { v: 1; kind: "history"; path: string; head: string; after: string }
|
|
324
|
+
interface ChangesCursor { v: 1; kind: "changes"; from: string; to: string; after: string }
|
|
325
|
+
function encodeCursor(cursor: HistoryCursor | ChangesCursor): string { return Buffer.from(JSON.stringify(cursor), "utf8").toString("base64url"); }
|
|
326
|
+
function decodeCursor(raw: string): HistoryCursor | ChangesCursor {
|
|
327
|
+
if (typeof raw !== "string" || !raw || raw.length > SNAPSHOT_CURSOR_CHARS) refuse("cursor: expected the opaque continuation from a previous page; restart without --cursor");
|
|
328
|
+
let value: unknown;
|
|
329
|
+
try { value = JSON.parse(Buffer.from(raw, "base64url").toString("utf8")); }
|
|
330
|
+
catch { refuse("cursor: not a continuation this provider issued; restart without --cursor"); }
|
|
331
|
+
if (!value || typeof value !== "object" || Array.isArray(value)) refuse("cursor: not a continuation this provider issued; restart without --cursor");
|
|
332
|
+
const cursor = value as Record<string, unknown>;
|
|
333
|
+
if (cursor.v !== 1 || (cursor.kind !== "history" && cursor.kind !== "changes") || typeof cursor.after !== "string") {
|
|
334
|
+
refuse("cursor: not a continuation this provider issued; restart without --cursor");
|
|
335
|
+
}
|
|
336
|
+
return cursor as unknown as HistoryCursor | ChangesCursor;
|
|
337
|
+
}
|
|
338
|
+
|
|
339
|
+
function baseResult(vault: VaultSpec, head: string | null, coverage: SnapshotCoverage, extra: Partial<SnapshotBase> = {}): SnapshotBase {
|
|
340
|
+
return { schemaVersion: SNAPSHOT_SCHEMA_VERSION, basis: "git_snapshot", vault: vault.id, head, firstParent: true,
|
|
341
|
+
renamePolicy: "exact_path", timeBasis: "git_commit_metadata_not_assertion_time", coverage, dirtyNotes: null, ...extra };
|
|
342
|
+
}
|
|
343
|
+
|
|
344
|
+
function unsupportedHistory(vault: VaultSpec, path: string, capability: SnapshotCapability, reason?: string): HistoryResult {
|
|
345
|
+
return { ...baseResult(vault, null, { complete: false, reason: reason ?? capability }, { capability, dirtyNotes: null, ...(reason ? { dirtyNotesReason: reason } : {}) }),
|
|
346
|
+
path, revisions: [], scanned: 0, scanLimit: HISTORY_SCAN_LIMIT, pageLimit: HISTORY_PAGE_LIMIT, stopReason: "unsupported", truncated: false, skippedSymlink: 0 };
|
|
347
|
+
}
|
|
348
|
+
|
|
349
|
+
/** The page and the cursor are trimmed until the whole result, envelope included, fits the transport bound. */
|
|
350
|
+
function fitHistory(result: HistoryResult, transportBytes: number): HistoryResult {
|
|
351
|
+
if (fits(result, transportBytes)) return result;
|
|
352
|
+
const revisions = [...result.revisions];
|
|
353
|
+
while (revisions.length) {
|
|
354
|
+
revisions.pop();
|
|
355
|
+
const after = revisions.at(-1)?.revision;
|
|
356
|
+
const candidate: HistoryResult = { ...result, revisions, truncated: true, stopReason: revisions.length ? "page_full" : "transport_limit",
|
|
357
|
+
...(after ? { continuation: encodeCursor({ v: 1, kind: "history", path: result.path, head: result.head ?? "", after }) } : { continuation: undefined }) };
|
|
358
|
+
if (fits(candidate, transportBytes)) return candidate;
|
|
359
|
+
}
|
|
360
|
+
return { ...result, revisions: [], truncated: true, stopReason: "transport_limit", continuation: undefined };
|
|
361
|
+
}
|
|
362
|
+
|
|
363
|
+
/** The longest UTF-8 prefix of `bytes` that fits, or undefined when not even an empty page does. */
|
|
364
|
+
function trimContent(base: RevisionResult, bytes: Buffer, transportBytes: number): RevisionResult | undefined {
|
|
365
|
+
const render = (cut: number): RevisionResult => ({ ...base, content: bytes.subarray(0, cut).toString("utf8"), truncated: true,
|
|
366
|
+
...(cut > 0 ? { nextOffset: (base.offset ?? 0) + cut } : {}), transportLimited: true });
|
|
367
|
+
let low = 0, high = bytes.length, best = -1;
|
|
368
|
+
while (low <= high) {
|
|
369
|
+
const middle = (low + high) >> 1, cut = boundary(bytes, middle);
|
|
370
|
+
if (fits(render(cut), transportBytes)) { best = cut; low = middle + 1; }
|
|
371
|
+
else high = middle - 1;
|
|
372
|
+
}
|
|
373
|
+
return best < 0 ? undefined : render(boundary(bytes, best));
|
|
374
|
+
}
|
|
375
|
+
|
|
376
|
+
/**
|
|
377
|
+
* Content is trimmed first, then the heading list (a page can be heading-heavy while its body is short): both count
|
|
378
|
+
* towards the same bound, and the flag says the list was cut.
|
|
379
|
+
*/
|
|
380
|
+
function fitRevision(result: RevisionResult, transportBytes: number): RevisionResult {
|
|
381
|
+
if (fits(result, transportBytes)) return result;
|
|
382
|
+
const bytes = Buffer.from(result.content ?? "", "utf8");
|
|
383
|
+
const trimmed = trimContent(result, bytes, transportBytes);
|
|
384
|
+
if (trimmed) return trimmed;
|
|
385
|
+
const dropped = { ...result };
|
|
386
|
+
delete dropped.headings;
|
|
387
|
+
delete dropped.headingsTruncated;
|
|
388
|
+
const base: RevisionResult = { ...dropped, ...(result.headings?.length ? { headingsTruncated: true } : {}) };
|
|
389
|
+
return trimContent(base, bytes, transportBytes) ?? { ...base, content: "", truncated: true, transportLimited: true };
|
|
390
|
+
}
|
|
391
|
+
|
|
392
|
+
function fitChanges(result: ChangesResult, transportBytes: number): ChangesResult {
|
|
393
|
+
if (fits(result, transportBytes)) return result;
|
|
394
|
+
const changed = [...result.changed];
|
|
395
|
+
while (changed.length) {
|
|
396
|
+
changed.pop();
|
|
397
|
+
const after = changed.at(-1)?.path;
|
|
398
|
+
const candidate: ChangesResult = { ...result, changed, truncated: true,
|
|
399
|
+
...(after ? { continuation: encodeCursor({ v: 1, kind: "changes", from: result.from, to: result.to, after }) } : { continuation: undefined }) };
|
|
400
|
+
if (fits(candidate, transportBytes)) return candidate;
|
|
401
|
+
}
|
|
402
|
+
return { ...result, changed: [], truncated: true, continuation: undefined };
|
|
403
|
+
}
|
|
404
|
+
|
|
405
|
+
/** Bounded read-only history of one note path, newest first, pinned to the HEAD the first page saw. */
|
|
406
|
+
export function readHistory(request: HistoryRequest, limits: SnapshotLimits = {}): HistoryResult {
|
|
407
|
+
const env = request.env ?? process.env, denyPaths = request.denyPaths ?? [];
|
|
408
|
+
const pageLimit = limits.pageLimit ?? HISTORY_PAGE_LIMIT, scanLimit = limits.scanLimit ?? HISTORY_SCAN_LIMIT;
|
|
409
|
+
const transportBytes = limits.transportBytes ?? SNAPSHOT_TRANSPORT_BYTES;
|
|
410
|
+
const path = resolveNote(request.vault, request.home, request.note);
|
|
411
|
+
assertReadable(path, request.vault.path, denyPaths);
|
|
412
|
+
if (request.limit !== undefined && (!Number.isInteger(request.limit) || request.limit < 1 || request.limit > pageLimit)) refuse(`limit: expected integer 1..${pageLimit}`);
|
|
413
|
+
const opened = openSnapshot(request.vault, env, limits);
|
|
414
|
+
if (!opened.ok) return unsupportedHistory(request.vault, path, opened.capability, opened.reason);
|
|
415
|
+
const snapshot = opened.snapshot, dirty = dirtyNoteCount(snapshot.git);
|
|
416
|
+
let pin = snapshot.head, start: string | null = snapshot.head;
|
|
417
|
+
if (request.cursor !== undefined) {
|
|
418
|
+
const cursor = decodeCursor(request.cursor);
|
|
419
|
+
if (cursor.kind !== "history") refuse("cursor: belongs to a changes page; restart without --cursor");
|
|
420
|
+
if (cursor.path !== path) refuse("cursor: belongs to another note path; restart without --cursor");
|
|
421
|
+
pin = commitObject(snapshot.git, cursor.head, "cursor.head");
|
|
422
|
+
reachable(snapshot.git, pin, snapshot.head);
|
|
423
|
+
// A cursor resumes a walk, so the commit it resumes after must be one this walk could have reached.
|
|
424
|
+
const after = commitObject(snapshot.git, cursor.after, "cursor.after");
|
|
425
|
+
if (!onFirstParentChain(snapshot.git, after, pin, scanLimit)) {
|
|
426
|
+
refuse(`cursor: ${after} is not on the first-parent chain of the pinned ${pin}; restart without --cursor`, "V06");
|
|
427
|
+
}
|
|
428
|
+
start = commitParent(snapshot.git, after);
|
|
429
|
+
if (start === null) {
|
|
430
|
+
return { ...baseResult(request.vault, pin, coverageOf(snapshot), { ...(snapshot.shallow ? { capability: "shallow_history" as const } : {}), dirtyNotes: dirty.count, ...(dirty.reason ? { dirtyNotesReason: dirty.reason } : {}) }),
|
|
431
|
+
path, revisions: [], scanned: 0, scanLimit, pageLimit, stopReason: "history_end", truncated: false, skippedSymlink: 0 };
|
|
432
|
+
}
|
|
433
|
+
}
|
|
434
|
+
const perPage = Math.min(request.limit ?? pageLimit, pageLimit);
|
|
435
|
+
// The window bounds commits traversed, not commits that touched the path: `rev-list` walks first-parent, and `log`
|
|
436
|
+
// then projects each of those commits onto this one path without walking any further.
|
|
437
|
+
const walked = text(snapshot.git(["rev-list", "--first-parent", `--max-count=${scanLimit + 1}`, start], { maxBuffer: LOG_BUFFER_BYTES }).stdout)
|
|
438
|
+
.split("\n").map(line => line.trim()).filter(Boolean);
|
|
439
|
+
if (walked.some(commit => !FULL_OID.test(commit))) refuse("snapshot: Git returned an unexpected commit id; retry", "V09");
|
|
440
|
+
const moreCommits = walked.length > scanLimit, traversed = walked.slice(0, scanLimit);
|
|
441
|
+
const out = traversed.length
|
|
442
|
+
? snapshot.git(["log", "--no-walk=unsorted", "--stdin", "-z", "--first-parent", "--raw", "--no-renames", "--no-textconv", "--no-abbrev",
|
|
443
|
+
"--format=%x01%H%x09%cI", "--", path], { input: `${traversed.join("\n")}\n`, maxBuffer: LOG_BUFFER_BYTES })
|
|
444
|
+
: { status: 0, stdout: Buffer.alloc(0), stderr: "" };
|
|
445
|
+
const parsed = parseLogRaw(text(out.stdout), path);
|
|
446
|
+
const noteRecords = parsed.filter(record => (record.mode === "100644" || record.mode === "100755") && !ZERO_OID.test(record.blob) && record.status !== "D");
|
|
447
|
+
const skippedSymlink = parsed.filter(record => record.mode === "120000").length;
|
|
448
|
+
let incomplete: string | undefined;
|
|
449
|
+
const revisions: HistoryRevision[] = [];
|
|
450
|
+
if (noteRecords.length) {
|
|
451
|
+
// Keyed by the blob id `--raw` reported, never by `<commit>:<path>`: a path is data, not a second expression.
|
|
452
|
+
const batch = snapshot.git(["cat-file", "--batch-check"], { input: `${noteRecords.map(record => record.blob).join("\n")}\n`, maxBuffer: BATCH_BUFFER_BYTES });
|
|
453
|
+
const lines = text(batch.stdout).split("\n");
|
|
454
|
+
for (const [index, record] of noteRecords.entries()) {
|
|
455
|
+
const parts = (lines[index] ?? "").split(" ");
|
|
456
|
+
const blob = parts[0] ?? "", type = parts[1] ?? "", size = Number(parts[2]);
|
|
457
|
+
if (type !== "blob" || blob !== record.blob || !Number.isSafeInteger(size) || size < 0) { incomplete = "object_unavailable"; continue; }
|
|
458
|
+
revisions.push({ revision: record.revision, blob, bytes: size, committedAt: record.committedAt });
|
|
459
|
+
}
|
|
460
|
+
}
|
|
461
|
+
const page = revisions.slice(0, perPage);
|
|
462
|
+
const stopReason: HistoryStopReason = revisions.length > perPage ? "page_full" : moreCommits ? "scan_limit" : "history_end";
|
|
463
|
+
// A scan-limited page with no matching revision still continues: from the oldest commit the window traversed.
|
|
464
|
+
const resume = page.at(-1)?.revision ?? (moreCommits ? traversed.at(-1) : undefined);
|
|
465
|
+
const continuation = stopReason === "history_end" || !resume ? undefined : encodeCursor({ v: 1, kind: "history", path, head: pin, after: resume });
|
|
466
|
+
const result: HistoryResult = {
|
|
467
|
+
...baseResult(request.vault, pin, incomplete ? { complete: false, reason: incomplete } : coverageOf(snapshot),
|
|
468
|
+
{ ...(snapshot.shallow ? { capability: "shallow_history" as const } : {}), ...(incomplete ? { capability: "object_unavailable" as const } : {}), dirtyNotes: dirty.count, ...(dirty.reason ? { dirtyNotesReason: dirty.reason } : {}) }),
|
|
469
|
+
path, revisions: page, scanned: traversed.length, scanLimit, pageLimit, stopReason, truncated: stopReason !== "history_end", ...(continuation ? { continuation } : {}), skippedSymlink,
|
|
470
|
+
};
|
|
471
|
+
return fitHistory(result, transportBytes);
|
|
472
|
+
}
|
|
473
|
+
|
|
474
|
+
/** One historical note blob at a pinned commit, with the current reader's paging, UTF-8, symlink, size and deny rules. */
|
|
475
|
+
export function readRevision(request: RevisionRequest, limits: SnapshotLimits = {}): RevisionResult {
|
|
476
|
+
const env = request.env ?? process.env, denyPaths = request.denyPaths ?? [];
|
|
477
|
+
const transportBytes = limits.transportBytes ?? SNAPSHOT_TRANSPORT_BYTES;
|
|
478
|
+
const requested = fullOid(request.revision, "revision");
|
|
479
|
+
const path = resolveNote(request.vault, request.home, request.note);
|
|
480
|
+
assertReadable(path, request.vault.path, denyPaths);
|
|
481
|
+
const maxBytes = request.maxBytes ?? 16384, offset = request.offset;
|
|
482
|
+
if (!Number.isInteger(maxBytes) || maxBytes < 1 || maxBytes > MAX_READ_BYTES) refuse(`max-bytes: expected integer 1..${MAX_READ_BYTES}`);
|
|
483
|
+
if (offset !== undefined && (!Number.isSafeInteger(offset) || offset < 0 || offset > MAX_NOTE_BYTES)) refuse(`offset: expected integer 0..${MAX_NOTE_BYTES}`);
|
|
484
|
+
if (request.section !== undefined && (!request.section.trim() || /[\r\n]/.test(request.section) || Buffer.byteLength(request.section) > 1024)) refuse("section: expected one exact H2 heading <=1024 bytes");
|
|
485
|
+
const opened = openSnapshot(request.vault, env, limits);
|
|
486
|
+
if (!opened.ok) {
|
|
487
|
+
return { ...baseResult(request.vault, null, { complete: false, reason: opened.reason ?? opened.capability }, { capability: opened.capability, dirtyNotes: null }), path, found: false };
|
|
488
|
+
}
|
|
489
|
+
const snapshot = opened.snapshot, dirty = dirtyNoteCount(snapshot.git);
|
|
490
|
+
const coverage = coverageOf(snapshot);
|
|
491
|
+
const base = { ...baseResult(request.vault, snapshot.head, coverage, { ...(snapshot.shallow ? { capability: "shallow_history" as const } : {}), dirtyNotes: dirty.count, ...(dirty.reason ? { dirtyNotesReason: dirty.reason } : {}) }),
|
|
492
|
+
path, found: false, revision: requested } as RevisionResult;
|
|
493
|
+
/** A pruned, shallow or missing object is a capability result, never a generic refusal and never current content. */
|
|
494
|
+
const unavailable = (): RevisionResult => ({ ...base, found: false,
|
|
495
|
+
coverage: { complete: false, reason: "object_unavailable" }, capability: "object_unavailable" });
|
|
496
|
+
if (!objectAvailable(snapshot.git, `${requested}^{commit}`)) return unavailable();
|
|
497
|
+
const commit = commitObject(snapshot.git, requested, "revision");
|
|
498
|
+
reachable(snapshot.git, commit, snapshot.head);
|
|
499
|
+
const common: RevisionResult = { ...base, revision: commit };
|
|
500
|
+
const tree = text(snapshot.git(["ls-tree", "-z", commit, "--", path], { maxBuffer: 8192 }).stdout).split("\0").filter(Boolean);
|
|
501
|
+
if (!tree.length) return common;
|
|
502
|
+
const [meta, entryPath] = tree[0]!.split("\t");
|
|
503
|
+
if (entryPath !== path) refuse("revision: Git reported another path than the one requested; nothing read", "V09");
|
|
504
|
+
const [mode, type, blob] = (meta ?? "").split(" ");
|
|
505
|
+
if (type !== "blob") refuse("revision: the path is not a file at this revision; pick another revision from `vmem history <vault> <note>`", "V04");
|
|
506
|
+
if (mode === "120000") refuse("revision: the path is a symlink at this revision; symlinked blobs are refused because a link can leave the vault. Pick another revision from `vmem history <vault> <note>`", "V06");
|
|
507
|
+
if (!/^100[0-7]{3}$/.test(mode ?? "") || !blob || !FULL_OID.test(blob)) refuse("revision: the path is not a regular file at this revision; pick another revision from `vmem history <vault> <note>`", "V04");
|
|
508
|
+
if (!objectAvailable(snapshot.git, blob)) return unavailable();
|
|
509
|
+
const size = Number(text(snapshot.git(["cat-file", "-s", blob]).stdout).trim());
|
|
510
|
+
if (!Number.isSafeInteger(size) || size < 0) return unavailable();
|
|
511
|
+
if (size > MAX_NOTE_BYTES) refuse(`revision: the historical note is ${size} bytes, over the ${MAX_NOTE_BYTES}-byte read bound; read it outside vmem or split it`, "V09");
|
|
512
|
+
const raw = snapshot.git(["cat-file", "blob", blob], { maxBuffer: size + 1 }).stdout;
|
|
513
|
+
if (raw.length !== size) refuse("revision: the blob changed while it was read; retry", "V09");
|
|
514
|
+
const source = raw.toString("utf8");
|
|
515
|
+
if (!Buffer.from(source).equals(raw)) refuse("revision: the historical blob is not valid UTF-8 text; vmem reads text notes only. Read that blob with `git cat-file blob` outside vmem", "V01");
|
|
516
|
+
const sha256 = createHash("sha256").update(raw).digest("hex");
|
|
517
|
+
const start = offset ?? 0;
|
|
518
|
+
let page: ReturnType<typeof readPage>, headings: RevisionResult["headings"], headingsTruncated: boolean | undefined;
|
|
519
|
+
if (request.section !== undefined) {
|
|
520
|
+
const body = parseFrontmatter(source).body, sections = h2Sections(body);
|
|
521
|
+
const found = sections.filter(item => item.name === request.section);
|
|
522
|
+
if (found.length !== 1) refuse(found.length ? "section: ambiguous H2 heading" : "section: unknown H2 heading");
|
|
523
|
+
const selected = Buffer.from(body.slice(found[0]!.start, found[0]!.end));
|
|
524
|
+
page = readPage(selected.subarray(start, start + maxBytes + 4), maxBytes, start, selected.length);
|
|
525
|
+
} else {
|
|
526
|
+
page = readPage(raw.subarray(start, start + maxBytes + 4), maxBytes, start, raw.length);
|
|
527
|
+
}
|
|
528
|
+
if (page.truncated) {
|
|
529
|
+
// The same bounded heading list the current reader reports, so a historical page pages the same way.
|
|
530
|
+
const metadata = headingMetadata(h2Sections(parseFrontmatter(source).body));
|
|
531
|
+
headings = metadata.headings;
|
|
532
|
+
headingsTruncated = metadata.headingsTruncated;
|
|
533
|
+
}
|
|
534
|
+
const result: RevisionResult = { ...common, found: true, revision: commit, blob, sha256, bytes: size, content: page.content,
|
|
535
|
+
truncated: page.truncated, ...(request.section !== undefined ? { section: request.section } : {}), ...(offset !== undefined ? { offset } : {}),
|
|
536
|
+
...(page.nextOffset !== undefined ? { nextOffset: page.nextOffset } : {}), ...(headings ? { headings } : {}), ...(headingsTruncated ? { headingsTruncated } : {}) };
|
|
537
|
+
return fitRevision(result, transportBytes);
|
|
538
|
+
}
|
|
539
|
+
|
|
540
|
+
interface RawChange { oldMode: string; mode: string; oldBlob: string; blob: string; status: string; path: string }
|
|
541
|
+
function parseDiffRaw(output: string): RawChange[] {
|
|
542
|
+
const tokens = output.split("\0"), changes: RawChange[] = [];
|
|
543
|
+
for (let i = 0; i < tokens.length; i++) {
|
|
544
|
+
const token = tokens[i]!;
|
|
545
|
+
if (!token.startsWith(":")) continue;
|
|
546
|
+
const parts = token.slice(1).split(" "), path = tokens[++i] ?? "";
|
|
547
|
+
changes.push({ oldMode: parts[0] ?? "", mode: parts[1] ?? "", oldBlob: parts[2] ?? "", blob: parts[3] ?? "", status: parts[4] ?? "", path });
|
|
548
|
+
}
|
|
549
|
+
return changes;
|
|
550
|
+
}
|
|
551
|
+
|
|
552
|
+
/** Notes-only tree comparison between two pinned commits: blob hashes and status, never a content diff. */
|
|
553
|
+
export function readChanges(request: ChangesRequest, limits: SnapshotLimits = {}): ChangesResult {
|
|
554
|
+
const env = request.env ?? process.env, denyPaths = request.denyPaths ?? [];
|
|
555
|
+
const pageLimit = limits.pageLimit ?? CHANGES_PAGE_LIMIT;
|
|
556
|
+
const transportBytes = limits.transportBytes ?? SNAPSHOT_TRANSPORT_BYTES;
|
|
557
|
+
const from = fullOid(request.from, "from"), to = fullOid(request.to, "to");
|
|
558
|
+
if (request.limit !== undefined && (!Number.isInteger(request.limit) || request.limit < 1 || request.limit > pageLimit)) refuse(`limit: expected integer 1..${pageLimit}`);
|
|
559
|
+
const opened = openSnapshot(request.vault, env, limits);
|
|
560
|
+
if (!opened.ok) {
|
|
561
|
+
return { ...baseResult(request.vault, null, { complete: false, reason: opened.reason ?? opened.capability }, { capability: opened.capability, dirtyNotes: null }), from, to, changed: [], total: 0, truncated: false, skippedDenied: 0, skippedSymlink: 0 };
|
|
562
|
+
}
|
|
563
|
+
const snapshot = opened.snapshot, dirty = dirtyNoteCount(snapshot.git);
|
|
564
|
+
const fromCommit = commitObject(snapshot.git, from, "from"), toCommit = commitObject(snapshot.git, to, "to");
|
|
565
|
+
reachable(snapshot.git, fromCommit, snapshot.head);
|
|
566
|
+
reachable(snapshot.git, toCommit, snapshot.head);
|
|
567
|
+
const out = snapshot.git(["diff-tree", "-r", "--no-renames", "--raw", "-z", "--no-abbrev", "--no-textconv", "--no-ext-diff", fromCommit, toCommit, "--", "notes"], { maxBuffer: DIFF_BUFFER_BYTES });
|
|
568
|
+
let skippedDenied = 0, skippedSymlink = 0;
|
|
569
|
+
const changed: ChangedNote[] = [];
|
|
570
|
+
for (const record of parseDiffRaw(text(out.stdout))) {
|
|
571
|
+
const path = notesPath(record.path);
|
|
572
|
+
if (!path) continue;
|
|
573
|
+
// A symlink or submodule on either side is not a note; its path or object id is never reported.
|
|
574
|
+
const regular = (mode: string) => mode === "000000" || /^100[0-7]{3}$/.test(mode);
|
|
575
|
+
if (!regular(record.oldMode) || !regular(record.mode)) { skippedSymlink++; continue; }
|
|
576
|
+
if (isDenied(join(snapshot.root, path), [...denyPaths])) { skippedDenied++; continue; }
|
|
577
|
+
const status = record.status.slice(0, 1);
|
|
578
|
+
if (!["A", "M", "D", "T"].includes(status)) continue;
|
|
579
|
+
changed.push({ path, status: status as ChangeStatus,
|
|
580
|
+
before: status === "A" || ZERO_OID.test(record.oldBlob) ? null : record.oldBlob,
|
|
581
|
+
after: status === "D" || ZERO_OID.test(record.blob) ? null : record.blob });
|
|
582
|
+
}
|
|
583
|
+
let remaining = changed;
|
|
584
|
+
if (request.cursor !== undefined) {
|
|
585
|
+
const cursor = decodeCursor(request.cursor);
|
|
586
|
+
if (cursor.kind !== "changes") refuse("cursor: belongs to a history page; restart without --cursor");
|
|
587
|
+
if (cursor.from !== fromCommit || cursor.to !== toCommit) refuse("cursor: belongs to another revision pair; restart without --cursor");
|
|
588
|
+
const at = changed.findIndex(item => item.path === cursor.after);
|
|
589
|
+
if (at < 0) refuse("cursor: no longer matches these snapshots; restart without --cursor");
|
|
590
|
+
remaining = changed.slice(at + 1);
|
|
591
|
+
}
|
|
592
|
+
const page = remaining.slice(0, Math.min(request.limit ?? pageLimit, pageLimit));
|
|
593
|
+
const continuation = remaining.length > page.length && page.length
|
|
594
|
+
? encodeCursor({ v: 1, kind: "changes", from: fromCommit, to: toCommit, after: page.at(-1)!.path }) : undefined;
|
|
595
|
+
const result: ChangesResult = {
|
|
596
|
+
...baseResult(request.vault, snapshot.head, coverageOf(snapshot), { ...(snapshot.shallow ? { capability: "shallow_history" as const } : {}), dirtyNotes: dirty.count, ...(dirty.reason ? { dirtyNotesReason: dirty.reason } : {}) }),
|
|
597
|
+
from: fromCommit, to: toCommit, changed: page, total: changed.length, truncated: remaining.length > page.length, ...(continuation ? { continuation } : {}), skippedDenied, skippedSymlink,
|
|
598
|
+
};
|
|
599
|
+
return fitChanges(result, transportBytes);
|
|
600
|
+
}
|
|
601
|
+
|
|
602
|
+
const command = (...words: string[]) => ["vmem", ...words].map(shellWord).join(" ");
|
|
603
|
+
function basisFields(result: SnapshotBase, o: TextOptions, extra: [string, number | string | undefined][] = []) {
|
|
604
|
+
return fields([["basis", result.basis], ["head", result.head ? result.head.slice(0, 12) : undefined],
|
|
605
|
+
["dirty notes", result.dirtyNotes === null ? (result.dirtyNotesReason ?? "unavailable") : String(result.dirtyNotes)],
|
|
606
|
+
["coverage", result.coverage.complete ? "complete" : `incomplete: ${result.coverage.reason ?? "unknown"}`], ...extra], o);
|
|
607
|
+
}
|
|
608
|
+
|
|
609
|
+
/** Plain-text history: the pinned HEAD, the page of revisions and the exact continuation command. */
|
|
610
|
+
export function historyText(result: HistoryResult, o: TextOptions, c: { vault: string; note: string; limit?: number; cursor?: string }): string {
|
|
611
|
+
const head = heading(`history ${c.vault} ${result.path}`, o) + "\n" + basisFields(result, o, [
|
|
612
|
+
["scanned commits", result.scanned], ["page limit", result.pageLimit], ["skipped symlinks", result.skippedSymlink || undefined],
|
|
613
|
+
]);
|
|
614
|
+
if (!result.revisions.length) {
|
|
615
|
+
const why = result.capability ? status("warn", `no snapshot history: ${result.capability}`, o)
|
|
616
|
+
: status("absent", `no recorded revisions of ${result.path} on the first-parent history`, o);
|
|
617
|
+
return blocks(head, why);
|
|
618
|
+
}
|
|
619
|
+
const rows = result.revisions.map(revision => [revision.revision.slice(0, 12), revision.blob.slice(0, 12), revision.bytes, revision.committedAt]);
|
|
620
|
+
const more = result.continuation ? nextCommand("next", command("history", c.vault, result.path, ...(c.limit !== undefined ? ["--limit", String(c.limit)] : []), "--cursor", result.continuation), o) : undefined;
|
|
621
|
+
const stop = result.stopReason === "scan_limit" ? status("warn", `stopped after the ${result.scanLimit}-commit scan limit; continue from the cursor`, o)
|
|
622
|
+
: result.stopReason === "transport_limit" ? status("warn", "result reached the 48 KiB transport bound; page with a smaller --limit", o) : undefined;
|
|
623
|
+
const counts = summary({ ok: result.revisions.length, warnings: result.skippedSymlink }, o);
|
|
624
|
+
return blocks(head, table(["REVISION", "BLOB", "BYTES", "COMMITTED (GIT METADATA)"], rows, o), [counts, stop, more].filter(Boolean).join("\n"));
|
|
625
|
+
}
|
|
626
|
+
|
|
627
|
+
/** Plain-text historical read: commit, blob and content hashes, then the paged content. */
|
|
628
|
+
export function revisionText(result: RevisionResult, o: TextOptions, c: { vault: string; note: string; revision: string; maxBytes?: number }): string {
|
|
629
|
+
const where = result.revision ? result.revision.slice(0, 12) : c.revision.slice(0, 12);
|
|
630
|
+
const head = heading(`show ${c.vault} ${result.path} at ${where}`, o) + "\n" + fields([
|
|
631
|
+
["revision", result.revision], ["blob", result.blob], ["sha256", result.sha256?.slice(0, 12)], ["bytes", result.bytes],
|
|
632
|
+
["offset", result.offset], ["dirty notes", result.dirtyNotes === null ? (result.dirtyNotesReason ?? "unavailable") : String(result.dirtyNotes)],
|
|
633
|
+
["coverage", result.coverage.complete ? "complete" : `incomplete: ${result.coverage.reason ?? "unknown"}`],
|
|
634
|
+
], o);
|
|
635
|
+
if (!result.found) {
|
|
636
|
+
const why = result.capability ? status("warn", `no historical content: ${result.capability}`, o)
|
|
637
|
+
: status("absent", `the note did not exist at ${where}`, o);
|
|
638
|
+
return blocks(head, why);
|
|
639
|
+
}
|
|
640
|
+
const body = stripTerminal(result.content ?? "").replace(/\n+$/, "");
|
|
641
|
+
if (!result.truncated) return blocks(head, body);
|
|
642
|
+
const words = ["show", c.vault, c.note, "--revision", result.revision ?? c.revision, ...(result.section ? ["--section", result.section] : []),
|
|
643
|
+
...(c.maxBytes !== undefined ? ["--max-bytes", String(c.maxBytes)] : []), "--offset", String(result.nextOffset)];
|
|
644
|
+
const tail = [status("warn", result.transportLimited ? "truncated at the 48 KiB transport bound" : "truncated", o),
|
|
645
|
+
...(result.nextOffset !== undefined ? [nextCommand("next", command(...words), o)] : [])];
|
|
646
|
+
const headings = result.headings?.length ? ["H2 headings (read one with --section):", ...result.headings.map(name => ` ${clean(name)}`), ...(result.headingsTruncated ? [paint(" ... more headings", "muted", o)] : [])].join("\n") : undefined;
|
|
647
|
+
return blocks(head, body, tail.join("\n"), headings);
|
|
648
|
+
}
|
|
649
|
+
|
|
650
|
+
/** Plain-text tree comparison. */
|
|
651
|
+
export function changesText(result: ChangesResult, o: TextOptions, c: { vault: string; from: string; to: string; limit?: number }): string {
|
|
652
|
+
const head = heading(`changes ${c.vault} ${result.from.slice(0, 12)}..${result.to.slice(0, 12)}`, o) + "\n" + basisFields(result, o, [
|
|
653
|
+
["total changes", result.total], ["skipped denied", result.skippedDenied || undefined], ["skipped symlinks", result.skippedSymlink || undefined],
|
|
654
|
+
]);
|
|
655
|
+
if (!result.changed.length) return blocks(head, status("absent", `no note changes between ${result.from.slice(0, 12)} and ${result.to.slice(0, 12)}`, o));
|
|
656
|
+
const rows = result.changed.map(item => [tone(item.status, item.status === "D" ? "warn" : "ok"), item.path, item.before?.slice(0, 12) ?? "-", item.after?.slice(0, 12) ?? "-"]);
|
|
657
|
+
const more = result.continuation ? nextCommand("next", command("changes", c.vault, "--from", result.from, "--to", result.to, ...(c.limit !== undefined ? ["--limit", String(c.limit)] : []), "--cursor", result.continuation), o) : undefined;
|
|
658
|
+
const denied = result.skippedDenied ? status("warn", `${plural(result.skippedDenied, "denied path")} left out by current policy`, o) : undefined;
|
|
659
|
+
const symlinked = result.skippedSymlink ? status("warn", `${plural(result.skippedSymlink, "symlinked or non-file entry")} left out`, o) : undefined;
|
|
660
|
+
const counts = summary({ ok: result.changed.length, warnings: result.skippedDenied + result.skippedSymlink }, o);
|
|
661
|
+
return blocks(head, table(["ST", "PATH", "BEFORE", "AFTER"], rows, o), [counts, denied, symlinked, more].filter(Boolean).join("\n"));
|
|
662
|
+
}
|