@gadicc/loom 1.33.1 → 1.35.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 (110) hide show
  1. package/README.md +108 -41
  2. package/esm/src/apiKeys/authorize.d.ts.map +1 -1
  3. package/esm/src/apiKeys/authorize.js +71 -0
  4. package/esm/src/apiKeys/betterAuth.d.ts +123 -0
  5. package/esm/src/apiKeys/betterAuth.d.ts.map +1 -0
  6. package/esm/src/apiKeys/betterAuth.js +164 -0
  7. package/esm/src/apiKeys/credentials.d.ts +37 -2
  8. package/esm/src/apiKeys/credentials.d.ts.map +1 -1
  9. package/esm/src/apiKeys/credentials.js +69 -8
  10. package/esm/src/apiKeys/lifecycle.d.ts +41 -0
  11. package/esm/src/apiKeys/lifecycle.d.ts.map +1 -0
  12. package/esm/src/apiKeys/lifecycle.js +6 -0
  13. package/esm/src/apiKeys/limits.d.ts +132 -0
  14. package/esm/src/apiKeys/limits.d.ts.map +1 -0
  15. package/esm/src/apiKeys/limits.js +246 -0
  16. package/esm/src/apiKeys/mod.d.ts +4 -0
  17. package/esm/src/apiKeys/mod.d.ts.map +1 -1
  18. package/esm/src/apiKeys/mod.js +4 -0
  19. package/esm/src/apiKeys/permissions.d.ts +56 -0
  20. package/esm/src/apiKeys/permissions.d.ts.map +1 -0
  21. package/esm/src/apiKeys/permissions.js +128 -0
  22. package/esm/src/apiKeys/policy.d.ts +3 -1
  23. package/esm/src/apiKeys/policy.d.ts.map +1 -1
  24. package/esm/src/apiKeys/policy.js +3 -1
  25. package/esm/src/apiKeys/types.d.ts +68 -1
  26. package/esm/src/apiKeys/types.d.ts.map +1 -1
  27. package/esm/src/cli/localDb.d.ts +28 -0
  28. package/esm/src/cli/localDb.d.ts.map +1 -0
  29. package/esm/src/cli/localDb.js +366 -0
  30. package/esm/src/cli/localDevLock.d.ts +97 -0
  31. package/esm/src/cli/localDevLock.d.ts.map +1 -0
  32. package/esm/src/cli/localDevLock.js +312 -0
  33. package/esm/src/cli/localDevPackage.d.ts +172 -0
  34. package/esm/src/cli/localDevPackage.d.ts.map +1 -0
  35. package/esm/src/cli/localDevPackage.js +617 -0
  36. package/esm/src/cli/migrationEnv.d.ts +19 -0
  37. package/esm/src/cli/migrationEnv.d.ts.map +1 -1
  38. package/esm/src/cli/migrationEnv.js +44 -1
  39. package/esm/src/cli/mod.d.ts +69 -4
  40. package/esm/src/cli/mod.d.ts.map +1 -1
  41. package/esm/src/cli/mod.js +2822 -419
  42. package/esm/src/cli/projectTooling.d.ts +19 -1
  43. package/esm/src/cli/projectTooling.d.ts.map +1 -1
  44. package/esm/src/cli/projectTooling.js +142 -12
  45. package/esm/src/mui/apiKeys.d.ts +123 -17
  46. package/esm/src/mui/apiKeys.d.ts.map +1 -1
  47. package/esm/src/mui/apiKeys.js +219 -78
  48. package/esm/src/mui/apiKeysView.d.ts +145 -0
  49. package/esm/src/mui/apiKeysView.d.ts.map +1 -1
  50. package/esm/src/mui/apiKeysView.js +278 -0
  51. package/esm/src/next/apiKeys/mod.d.ts +8 -1
  52. package/esm/src/next/apiKeys/mod.d.ts.map +1 -1
  53. package/esm/src/next/apiKeys/mod.js +5 -2
  54. package/package.json +2 -6
  55. package/script/src/apiKeys/authorize.d.ts.map +1 -1
  56. package/script/src/apiKeys/authorize.js +71 -0
  57. package/script/src/apiKeys/betterAuth.d.ts +123 -0
  58. package/script/src/apiKeys/betterAuth.d.ts.map +1 -0
  59. package/script/src/apiKeys/betterAuth.js +169 -0
  60. package/script/src/apiKeys/credentials.d.ts +37 -2
  61. package/script/src/apiKeys/credentials.d.ts.map +1 -1
  62. package/script/src/apiKeys/credentials.js +71 -8
  63. package/script/src/apiKeys/lifecycle.d.ts +41 -0
  64. package/script/src/apiKeys/lifecycle.d.ts.map +1 -0
  65. package/script/src/apiKeys/lifecycle.js +7 -0
  66. package/script/src/apiKeys/limits.d.ts +132 -0
  67. package/script/src/apiKeys/limits.d.ts.map +1 -0
  68. package/script/src/apiKeys/limits.js +254 -0
  69. package/script/src/apiKeys/mod.d.ts +4 -0
  70. package/script/src/apiKeys/mod.d.ts.map +1 -1
  71. package/script/src/apiKeys/mod.js +4 -0
  72. package/script/src/apiKeys/permissions.d.ts +56 -0
  73. package/script/src/apiKeys/permissions.d.ts.map +1 -0
  74. package/script/src/apiKeys/permissions.js +136 -0
  75. package/script/src/apiKeys/policy.d.ts +3 -1
  76. package/script/src/apiKeys/policy.d.ts.map +1 -1
  77. package/script/src/apiKeys/policy.js +3 -1
  78. package/script/src/apiKeys/types.d.ts +68 -1
  79. package/script/src/apiKeys/types.d.ts.map +1 -1
  80. package/script/src/cli/localDb.d.ts +28 -0
  81. package/script/src/cli/localDb.d.ts.map +1 -0
  82. package/script/src/cli/localDb.js +370 -0
  83. package/script/src/cli/localDevLock.d.ts +97 -0
  84. package/script/src/cli/localDevLock.d.ts.map +1 -0
  85. package/script/src/cli/localDevLock.js +320 -0
  86. package/script/src/cli/localDevPackage.d.ts +172 -0
  87. package/script/src/cli/localDevPackage.d.ts.map +1 -0
  88. package/script/src/cli/localDevPackage.js +635 -0
  89. package/script/src/cli/migrationEnv.d.ts +19 -0
  90. package/script/src/cli/migrationEnv.d.ts.map +1 -1
  91. package/script/src/cli/migrationEnv.js +48 -1
  92. package/script/src/cli/mod.d.ts +69 -4
  93. package/script/src/cli/mod.d.ts.map +1 -1
  94. package/script/src/cli/mod.js +2823 -419
  95. package/script/src/cli/projectTooling.d.ts +19 -1
  96. package/script/src/cli/projectTooling.d.ts.map +1 -1
  97. package/script/src/cli/projectTooling.js +176 -12
  98. package/script/src/mui/apiKeys.d.ts +123 -17
  99. package/script/src/mui/apiKeys.d.ts.map +1 -1
  100. package/script/src/mui/apiKeys.js +220 -77
  101. package/script/src/mui/apiKeysView.d.ts +145 -0
  102. package/script/src/mui/apiKeysView.d.ts.map +1 -1
  103. package/script/src/mui/apiKeysView.js +291 -0
  104. package/script/src/next/apiKeys/mod.d.ts +8 -1
  105. package/script/src/next/apiKeys/mod.d.ts.map +1 -1
  106. package/script/src/next/apiKeys/mod.js +5 -2
  107. package/skills/loom/SKILL.md +116 -18
  108. package/skills/loom-api-keys/SKILL.md +101 -7
  109. package/skills/loom-auth/SKILL.md +9 -0
  110. package/skills/loom-db/SKILL.md +33 -1
@@ -0,0 +1,312 @@
1
+ import { randomUUID } from "node:crypto";
2
+ import { readFileSync, unlinkSync } from "node:fs";
3
+ import { mkdir, open, readFile, stat, unlink, utimes } from "node:fs/promises";
4
+ import { hostname as osHostname } from "node:os";
5
+ import { dirname } from "node:path";
6
+ import process from "node:process";
7
+ /** Holders refresh the lock this often while they run. */
8
+ export const LOCAL_DEV_LOCK_HEARTBEAT_MS = 5_000;
9
+ /**
10
+ * A lock nobody refreshed for this long is stale whatever its host or PID:
11
+ * its holder crashed, was killed, or is on a machine that went away.
12
+ */
13
+ export const LOCAL_DEV_LOCK_STALE_AFTER_MS = 60_000;
14
+ /**
15
+ * A holder on this host whose process still exists (paused with Ctrl-Z or
16
+ * stopped in a debugger, say) keeps its lock this long without refreshing.
17
+ */
18
+ export const LOCAL_DEV_LOCK_LIVE_HOLDER_STALE_AFTER_MS = 5 * 60_000;
19
+ /** Default wait for another sync; well beyond the stale thresholds. */
20
+ export const LOCAL_DEV_LOCK_TIMEOUT_MS = 10 * 60_000;
21
+ /**
22
+ * Before breaking a lock, a waiter must itself see it unrefreshed for this
23
+ * long, which spans two heartbeats. That protects live holders after a
24
+ * suspend/resume, under clock skew, and in another PID namespace.
25
+ */
26
+ const MIN_UNREFRESHED_OBSERVATION_MS = 12_000;
27
+ // A longer gap between polls means this process was suspended, so earlier
28
+ // observations say nothing about the holder.
29
+ const MAX_POLL_GAP_MS = 10_000;
30
+ // Breaking a lock takes milliseconds; an older break lock is from a crash.
31
+ const BREAK_LOCK_STALE_AFTER_MS = 10_000;
32
+ const DEFAULT_SIGNALS = ["SIGHUP", "SIGINT", "SIGTERM"];
33
+ function errorCode(error) {
34
+ return error?.code;
35
+ }
36
+ function defaultIsProcessAlive(pid) {
37
+ if (pid === process.pid)
38
+ return true;
39
+ try {
40
+ process.kill(pid, 0);
41
+ return true;
42
+ }
43
+ catch (error) {
44
+ // Only ESRCH proves the process is gone. EPERM means it belongs to
45
+ // someone else, and a sandbox may refuse the probe.
46
+ return errorCode(error) !== "ESRCH";
47
+ }
48
+ }
49
+ function parseHolder(text) {
50
+ try {
51
+ const value = JSON.parse(text);
52
+ return typeof value.pid === "number" &&
53
+ typeof value.hostname === "string" &&
54
+ typeof value.startedAt === "string" &&
55
+ typeof value.token === "string"
56
+ ? value
57
+ : null;
58
+ }
59
+ catch {
60
+ return null;
61
+ }
62
+ }
63
+ async function readLock(lockPath) {
64
+ try {
65
+ const [text, lockStat] = await Promise.all([
66
+ readFile(lockPath, "utf8"),
67
+ stat(lockPath),
68
+ ]);
69
+ return { holder: parseHolder(text), mtimeMs: lockStat.mtimeMs, text };
70
+ }
71
+ catch (error) {
72
+ if (errorCode(error) === "ENOENT")
73
+ return null;
74
+ throw error;
75
+ }
76
+ }
77
+ /** Removes the lock only if it still has the content this process read. */
78
+ async function unlinkIfUnchanged(lockPath, text) {
79
+ try {
80
+ if (await readFile(lockPath, "utf8") === text)
81
+ await unlink(lockPath);
82
+ }
83
+ catch (error) {
84
+ if (errorCode(error) !== "ENOENT")
85
+ throw error;
86
+ }
87
+ }
88
+ /** Creates a file exclusively with `text`, or returns false if it exists. */
89
+ async function createExclusive(path, text) {
90
+ const handle = await open(path, "wx").catch((error) => {
91
+ if (errorCode(error) === "EEXIST")
92
+ return null;
93
+ throw error;
94
+ });
95
+ if (!handle)
96
+ return false;
97
+ try {
98
+ await handle.writeFile(text, "utf8");
99
+ await handle.close();
100
+ }
101
+ catch (error) {
102
+ await handle.close().catch(() => { });
103
+ await unlink(path).catch(() => { });
104
+ throw error;
105
+ }
106
+ return true;
107
+ }
108
+ /**
109
+ * Removes a stale lock while holding `<lock>.break`, so that waiters break
110
+ * a crashed lock one at a time. Each breaker re-reads the lock under the
111
+ * break lock and removes it only if it still has the stale content, so a
112
+ * later breaker can never remove the fresh lock a previous waiter created.
113
+ * Returns false when another process is breaking it; the caller re-checks.
114
+ */
115
+ export async function breakStaleLock(lockPath, staleText, options) {
116
+ const breakPath = `${lockPath}.break`;
117
+ const breakText = `${randomUUID()}\n`;
118
+ if (!await createExclusive(breakPath, breakText)) {
119
+ const breakLock = await readLock(breakPath);
120
+ if (breakLock &&
121
+ options.now() - breakLock.mtimeMs > BREAK_LOCK_STALE_AFTER_MS) {
122
+ await unlinkIfUnchanged(breakPath, breakLock.text);
123
+ }
124
+ return false;
125
+ }
126
+ try {
127
+ const current = await readFile(lockPath, "utf8").catch((error) => {
128
+ if (errorCode(error) === "ENOENT")
129
+ return null;
130
+ throw error;
131
+ });
132
+ if (current === staleText) {
133
+ await options.beforeBreak?.();
134
+ await unlinkIfUnchanged(lockPath, staleText);
135
+ }
136
+ return true;
137
+ }
138
+ finally {
139
+ await unlinkIfUnchanged(breakPath, breakText);
140
+ }
141
+ }
142
+ function describeHolder(holder) {
143
+ return holder
144
+ ? `process ${holder.pid} on ${holder.hostname}, started ${holder.startedAt}`
145
+ : "a process whose lock record is unreadable";
146
+ }
147
+ /**
148
+ * Runs `run` while holding an exclusive lock file, so concurrent Loom
149
+ * commands in one project do not rebuild and reinstall the linked package at
150
+ * the same time. A waiting process runs `run` after the holder finishes, so
151
+ * it re-checks freshness instead of repeating the work.
152
+ *
153
+ * The holder refreshes the lock's modification time every `heartbeatMs` and
154
+ * removes it on SIGHUP/SIGINT/SIGTERM. A waiter breaks a lock it has seen
155
+ * unrefreshed for `staleAfterMs`, whatever its host or PID, or sooner (after
156
+ * two missed heartbeats) when the lock is already older than that or its
157
+ * process is gone on this host. Waiting longer than `timeoutMs` fails with a
158
+ * message naming the holder and the lock file.
159
+ */
160
+ export async function withLocalDevLock(lockPath, run, options = {}) {
161
+ const now = options.now ?? Date.now;
162
+ const sleep = options.sleep ??
163
+ ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
164
+ const hostname = options.hostname ?? osHostname();
165
+ const isProcessAlive = options.isProcessAlive ?? defaultIsProcessAlive;
166
+ const timeoutMs = options.timeoutMs ?? LOCAL_DEV_LOCK_TIMEOUT_MS;
167
+ const staleAfterMs = options.staleAfterMs ?? LOCAL_DEV_LOCK_STALE_AFTER_MS;
168
+ const pollMs = options.pollMs ?? 250;
169
+ const deadline = now() + timeoutMs;
170
+ const own = {
171
+ hostname,
172
+ pid: process.pid,
173
+ startedAt: "",
174
+ token: randomUUID(),
175
+ };
176
+ let ownText = "";
177
+ let waited = false;
178
+ // What this waiter has seen of the current lock, by its own clock.
179
+ let observed = null;
180
+ await mkdir(dirname(lockPath), { recursive: true });
181
+ while (true) {
182
+ own.startedAt = new Date(now()).toISOString();
183
+ ownText = `${JSON.stringify(own)}\n`;
184
+ if (await createExclusive(lockPath, ownText))
185
+ break;
186
+ const lock = await readLock(lockPath);
187
+ if (!lock)
188
+ continue;
189
+ const holder = lock.holder;
190
+ const time = now();
191
+ const signature = `${lock.mtimeMs}:${lock.text}`;
192
+ if (!observed || observed.signature !== signature ||
193
+ time - observed.lastPoll > MAX_POLL_GAP_MS) {
194
+ observed = { lastPoll: time, signature, since: time };
195
+ }
196
+ observed.lastPoll = time;
197
+ const unrefreshedFor = time - observed.since;
198
+ const onThisHost = holder !== null && holder.hostname === hostname;
199
+ const aliveHere = onThisHost && isProcessAlive(holder.pid);
200
+ const deadHere = onThisHost && !aliveHere;
201
+ // A process that still exists here is probably paused, not gone.
202
+ const unrefreshedLimit = aliveHere
203
+ ? Math.max(staleAfterMs, LOCAL_DEV_LOCK_LIVE_HOLDER_STALE_AFTER_MS)
204
+ : staleAfterMs;
205
+ const stale = unrefreshedFor >= unrefreshedLimit ||
206
+ (unrefreshedFor >= MIN_UNREFRESHED_OBSERVATION_MS &&
207
+ (deadHere ||
208
+ (!aliveHere && time - lock.mtimeMs >= staleAfterMs)));
209
+ if (stale) {
210
+ if (await breakStaleLock(lockPath, lock.text, {
211
+ beforeBreak: options.beforeBreak,
212
+ now,
213
+ })) {
214
+ observed = null;
215
+ continue;
216
+ }
217
+ }
218
+ else if (!waited) {
219
+ waited = true;
220
+ options.onWait?.(holder);
221
+ }
222
+ if (now() >= deadline) {
223
+ throw new Error(`Timed out after ${Math.round(timeoutMs / 1000)}s waiting for another Loom dev sync (${describeHolder(holder)}) that holds ${lockPath}. If no Loom command is running in this project, delete that file and rerun.`);
224
+ }
225
+ await sleep(pollMs);
226
+ }
227
+ let lost = false;
228
+ const heartbeat = setInterval(() => {
229
+ readFile(lockPath, "utf8")
230
+ .then((text) => {
231
+ if (text !== ownText) {
232
+ lost = true;
233
+ return;
234
+ }
235
+ if (options.touch)
236
+ return options.touch(lockPath);
237
+ const time = new Date();
238
+ return utimes(lockPath, time, time);
239
+ })
240
+ .catch(() => { });
241
+ }, options.heartbeatMs ?? LOCAL_DEV_LOCK_HEARTBEAT_MS);
242
+ const handle = {
243
+ waited,
244
+ assertHeld: async (changesMade = false) => {
245
+ let text = null;
246
+ for (let attempt = 1;; attempt += 1) {
247
+ try {
248
+ text = await readFile(lockPath, "utf8");
249
+ break;
250
+ }
251
+ catch (error) {
252
+ if (errorCode(error) === "ENOENT")
253
+ break;
254
+ if (attempt >= 3) {
255
+ throw new Error(`Could not read the dev sync lock ${lockPath}: ${error.message}`);
256
+ }
257
+ await sleep(50 * attempt);
258
+ }
259
+ }
260
+ if (text !== ownText)
261
+ lost = true;
262
+ if (lost) {
263
+ throw new Error(`This Loom command lost the dev sync lock (${lockPath}): it stopped refreshing it, for example while paused, and another Loom command took over. ${changesMade
264
+ ? "It had already changed the project (an override, build, or install) and stopped there; run `loom dev sync` to bring the local Loom package up to date."
265
+ : "It stopped before making changes; rerun it."}`);
266
+ }
267
+ },
268
+ };
269
+ // The heartbeat must never keep a finished command alive.
270
+ heartbeat.unref?.();
271
+ const signalTarget = options.signalTarget ??
272
+ process;
273
+ const signals = options.signals ?? DEFAULT_SIGNALS;
274
+ const handledSignals = [];
275
+ const removeSignalHandlers = () => {
276
+ for (const signal of handledSignals.splice(0)) {
277
+ signalTarget.off(signal, onSignal);
278
+ }
279
+ };
280
+ // Release synchronously, then re-raise so the default action still ends
281
+ // the process with the usual signal status.
282
+ function onSignal(signal) {
283
+ clearInterval(heartbeat);
284
+ try {
285
+ if (readFileSync(lockPath, "utf8") === ownText)
286
+ unlinkSync(lockPath);
287
+ }
288
+ catch {
289
+ // Gone already, or unreadable: nothing to release.
290
+ }
291
+ removeSignalHandlers();
292
+ signalTarget.kill(process.pid, signal);
293
+ }
294
+ for (const signal of signals) {
295
+ try {
296
+ signalTarget.on(signal, onSignal);
297
+ handledSignals.push(signal);
298
+ }
299
+ catch {
300
+ // Some runtimes cannot listen for every signal (Deno on Windows).
301
+ }
302
+ }
303
+ try {
304
+ return await run(handle);
305
+ }
306
+ finally {
307
+ clearInterval(heartbeat);
308
+ removeSignalHandlers();
309
+ // Never remove a lock another process took over after judging ours stale.
310
+ await unlinkIfUnchanged(lockPath, ownText);
311
+ }
312
+ }
@@ -0,0 +1,172 @@
1
+ /**
2
+ * Loom repository paths whose content can change the generated npm package.
3
+ * Release equivalence (`git diff`) and local build fingerprints share this list.
4
+ * It includes every script `scripts/build_npm.ts` imports.
5
+ */
6
+ export declare const LOOM_PACKAGE_RELEVANT_PATHS: readonly string[];
7
+ /**
8
+ * Build stamp written into Loom's `npm/` output by `scripts/build_npm.ts`.
9
+ * The build excludes it from the packed package, so it never reaches npm or a
10
+ * consumer's `node_modules`.
11
+ */
12
+ export declare const LOOM_BUILD_STAMP_FILE = ".loom-build.json";
13
+ /** Content identity and provenance of one local Loom npm build. */
14
+ export type LoomBuildStamp = {
15
+ /** Package version the build wrote into `npm/package.json`. */
16
+ packageVersion?: string;
17
+ /**
18
+ * Git HEAD of the Loom checkout when the build started, or null when git
19
+ * could not tell. Absent from stamps written before builds recorded it.
20
+ */
21
+ sourceCommit?: string | null;
22
+ /**
23
+ * Whether that checkout had tracked changes or untracked files git does
24
+ * not ignore when the build started; null when git could not tell. Absent
25
+ * from stamps written before builds recorded it.
26
+ */
27
+ sourceDirty?: boolean | null;
28
+ /**
29
+ * Written by `loom dev sync`, never by a build: the source fingerprint (as
30
+ * the syncing Loom computes it) of a fresh build that still produced no
31
+ * provenance, because the checkout's own build script predates it. Until
32
+ * the fingerprint changes, sync judges staleness by it alone instead of
33
+ * rebuilding on every run.
34
+ */
35
+ legacyBuildFingerprint?: string;
36
+ /**
37
+ * Digest of the packed output the build produced; see
38
+ * {@link computePackageContentDigest}. Absent from stamps written before
39
+ * builds recorded it.
40
+ */
41
+ packageDigest?: string;
42
+ /**
43
+ * Fingerprint of the package-relevant source content when the build
44
+ * started; see {@link computeLoomSourceFingerprint}.
45
+ */
46
+ sourceFingerprint: string;
47
+ version: 1;
48
+ };
49
+ /** What git reported about a Loom checkout when a build started. */
50
+ export type LoomSourceProvenance = {
51
+ sourceCommit: string | null;
52
+ sourceDirty: boolean | null;
53
+ };
54
+ /**
55
+ * Asks git for a checkout's HEAD commit and whether its working tree differs
56
+ * from it: tracked changes, untracked files that are not ignored (listed
57
+ * individually, whatever `status.showUntrackedFiles` says), or files marked
58
+ * skip-worktree or assume-unchanged, whose changes `git status` hides.
59
+ * `git` runs one git command in the checkout and returns its stdout, or null
60
+ * when it failed (git missing, not a repository). Whatever git cannot answer
61
+ * is null.
62
+ */
63
+ export declare function readLoomSourceProvenance(git: (args: string[]) => string | null): LoomSourceProvenance;
64
+ /**
65
+ * Settles a build's provenance from what git reported when the build started
66
+ * and when it finished. Any change in between (a commit, a checkout, an
67
+ * edit, which `sourcesChanged` reports from the source fingerprints, or git
68
+ * becoming unable to tell) means the output may mix two states, so the build
69
+ * is stamped dirty, which `loom dev published` refuses; the starting commit
70
+ * is kept. A start git could not read stays unknown.
71
+ */
72
+ export declare function settleLoomBuildProvenance(start: LoomSourceProvenance, end: LoomSourceProvenance, sourcesChanged: boolean): {
73
+ changedDuringBuild: boolean;
74
+ provenance: LoomSourceProvenance;
75
+ };
76
+ /**
77
+ * Whether a stamp records the build's provenance and output digest. Stamps
78
+ * from older build scripts lack them.
79
+ */
80
+ export declare function hasLoomBuildProvenance(stamp: LoomBuildStamp): boolean;
81
+ /**
82
+ * Hashes the content of every package-relevant file in a Loom checkout.
83
+ * Unlike modification times, the result changes exactly when a rebuild could
84
+ * produce a different package, including after checkouts that restore older
85
+ * timestamps and edits made while a build is running.
86
+ */
87
+ export declare function computeLoomSourceFingerprint(sourceRoot: string): Promise<string>;
88
+ /** Size and modification time of each package-relevant source file. */
89
+ export type LoomSourceSnapshot = Map<string, {
90
+ mtimeMs: number;
91
+ size: number;
92
+ }>;
93
+ /** Records {@link LoomSourceSnapshot} for a Loom checkout. */
94
+ export declare function snapshotLoomSources(sourceRoot: string): Promise<LoomSourceSnapshot>;
95
+ /**
96
+ * Whether any package-relevant source file was written while a build ran,
97
+ * from snapshots taken when it started (at `startedAtMs`) and when it
98
+ * finished. Content alone misses an edit that was reverted before the build
99
+ * finished, but the revert rewrites the file:
100
+ * - a file added, removed, resized or with a new modification time counts;
101
+ * - so does one modified at or after the start;
102
+ * - on filesystems with coarse timestamps (a whole-second modification time)
103
+ * an edit can keep the old value, so a file modified shortly before the
104
+ * start counts as well.
105
+ */
106
+ export declare function loomSourcesWrittenDuringBuild(start: LoomSourceSnapshot, end: LoomSourceSnapshot, startedAtMs: number): boolean;
107
+ /** Serializes the build stamp that `scripts/build_npm.ts` writes. */
108
+ export declare function formatLoomBuildStamp(stamp: Omit<LoomBuildStamp, "version">): string;
109
+ /** Reads a build stamp, returning null when it is absent or unrecognized. */
110
+ export declare function readLoomBuildStamp(packagePath: string): Promise<LoomBuildStamp | null>;
111
+ /**
112
+ * Digest of a built package's files by path and content, filtered as
113
+ * {@link findPackageTreeDifference} filters them: its root ignore rules,
114
+ * npm's always-ignored names, and every dot entry, which Loom's packing
115
+ * approximation treats as unpacked although npm would pack some. The build
116
+ * stamp records it, so any later edit to those files shows.
117
+ */
118
+ export declare function computePackageContentDigest(root: string): Promise<string>;
119
+ /**
120
+ * Compares a built package directory with the copy a package manager
121
+ * installed from it, by file list and byte content. Returns a short
122
+ * description of the first difference, or null when the installed copy
123
+ * matches.
124
+ *
125
+ * Both trees are filtered by the build's packing rules (its root
126
+ * `.npmignore` plus npm's always-ignored names), so a build that only adds a
127
+ * new top-level entry is still detected. When those rules cannot be read
128
+ * literally, top-level build entries absent from the installed copy are
129
+ * skipped instead.
130
+ */
131
+ export declare function findPackageTreeDifference(builtRoot: string, installedRoot: string): Promise<string | null>;
132
+ /**
133
+ * Cheap signature of an installed package tree: its real path plus each
134
+ * file's path, size, inode, and modification time (no file contents), or
135
+ * null when it is not installed. pnpm links unchanged files from its
136
+ * content-addressed store, so the signature changes when the package is
137
+ * replaced with different content. Lets a process tell whether the package
138
+ * it loaded was replaced later.
139
+ */
140
+ export declare function computePackageTreeSignature(root: string): Promise<string | null>;
141
+ /**
142
+ * Reads the override pnpm recorded for a package in the lockfile's top-level
143
+ * `overrides:` map. pnpm records the override map it actually applied, so
144
+ * this proves whether an override took effect.
145
+ */
146
+ export declare function getLockfileOverride(lockfileText: string, name: string): string | null;
147
+ /** The root importer's lockfile entry for one direct dependency. */
148
+ export type LockfileImporterDependency = {
149
+ specifier?: string;
150
+ version?: string;
151
+ };
152
+ /** Reads a direct dependency of the root importer (`.`) from a lockfile. */
153
+ export declare function getLockfileRootImporterDependency(lockfileText: string, name: string): LockfileImporterDependency | null;
154
+ /**
155
+ * Groups lockfile snapshot keys by `name@version`, collecting the peer (and
156
+ * patch) suffix of each variant, for example `(react@19.2.0)`.
157
+ */
158
+ export declare function getLockfileSnapshotVariants(lockfileText: string): Map<string, Set<string>>;
159
+ /** A package version whose number of lockfile peer variants grew. */
160
+ export type PeerVariantDuplicate = {
161
+ after: number;
162
+ before: number;
163
+ /** `name@version`. */
164
+ packageVersion: string;
165
+ };
166
+ /**
167
+ * Lists `name@version` entries that have more than one peer variant after a
168
+ * lockfile change and more variants than before it. Pre-existing duplicates
169
+ * are ignored so warnings point only at what the change introduced.
170
+ */
171
+ export declare function findNewPeerVariantDuplicates(beforeLockfileText: string | null, afterLockfileText: string): PeerVariantDuplicate[];
172
+ //# sourceMappingURL=localDevPackage.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"localDevPackage.d.ts","sourceRoot":"","sources":["../../../src/src/cli/localDevPackage.ts"],"names":[],"mappings":"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"}