@north-light/cli 0.0.0 → 0.3.414

package/dist/core/canvas/memory-reads.d.ts

@@ -0,0 +1,24 @@
+import type { DatabaseSync } from 'node:sqlite';
+import type { MemoryReadEventDTO } from '../../api/dto/analytics.js';
+/** Entries older than this are deleted by the hourly storage-maintenance pass. */
+export declare const MEMORY_READS_RETENTION_MS: number;
+export interface MemoryReadRow {
+    node_id: string;
+    name: string;
+    scope: string;
+    at: string;
+    type: 'read' | 'loaded';
+}
+/** Insert every event for one node in one transaction. `at` must already be a
+ *  canonical ISO UTC string (`Date#toISOString`) so range reads compare as text. */
+export declare function insertMemoryReads(nodeId: string, events: MemoryReadEventDTO[]): void;
+/** Record events inside the caller's write transaction: the canvas-model
+ *  delivery (`loaded`) and explicit document read (`read`) sites call this so
+ *  the log lands with the exposures and watches it describes. */
+export declare function recordMemoryReadsIn(db: DatabaseSync, nodeId: string, events: readonly MemoryReadEventDTO[]): void;
+/** Entries with `fromIso <= at < toIso`, oldest first. */
+export declare function listMemoryReads(fromIso: string, toIso: string): MemoryReadRow[];
+/** Delete entries older than the retention window; returns the count deleted. */
+export declare function pruneMemoryReads(nowMs: number): number;
+/** When recording began: the time the memory_reads migration ran. */
+export declare function memoryReadsStartedAt(): string | null;

package/dist/core/canvas/memory-reads.js

@@ -0,0 +1 @@
+var E=Object.defineProperty;var o=(e,t)=>E(e,"name",{value:t,configurable:!0});import{prepared as n}from"../sqlite-statements.js";import{openDb as m,withCanvasWrite as p}from"./db.js";const c=720*60*60*1e3;function u(e,t){p(a=>{const s=n(a,"INSERT INTO memory_reads (node_id, name, scope, at, type) VALUES (?, ?, ?, ?, ?)");for(const r of t)s.run(e,r.name,r.scope,r.at,r.type)})}o(u,"insertMemoryReads");function y(e,t,a){if(a.length===0)return;const s=n(e,"INSERT INTO memory_reads (node_id, name, scope, at, type) VALUES (?, ?, ?, ?, ?)");for(const r of a)s.run(t,r.name,r.scope,r.at,r.type)}o(y,"recordMemoryReadsIn");function _(e,t){return n(m(),"SELECT node_id, name, scope, at, type FROM memory_reads WHERE at >= ? AND at < ? ORDER BY at").all(e,t)}o(_,"listMemoryReads");function f(e){return p(t=>Number(n(t,"DELETE FROM memory_reads WHERE at < ?").run(new Date(e-c).toISOString()).changes))}o(f,"pruneMemoryReads");function S(){return n(m(),"SELECT value FROM canvas_meta WHERE key = 'memory_reads.started_at'").get()?.value??null}o(S,"memoryReadsStartedAt");export{c as MEMORY_READS_RETENTION_MS,u as insertMemoryReads,_ as listMemoryReads,S as memoryReadsStartedAt,f as pruneMemoryReads,y as recordMemoryReadsIn};

package/dist/core/canvas/meta-file.d.ts

@@ -0,0 +1,20 @@
+/** Read a metadata object, tolerating a missing/empty/corrupt file as `null`
+ *  (never throws). Callers that reindex/revive the whole canvas must not crash on
+ *  one damaged node. Read only while holding {@link withMetaLock} for any
+ *  read-modify-write that races other writers. */
+export declare function readMetaObject(path: string): Record<string, unknown> | null;
+/** Serialize every read-modify-write to one node's meta.json behind a single
+ *  cross-process lock, so a migration and a normal identity update can never
+ *  interleave into a lost write or a restored-legacy-prefix. The lock is NOT
+ *  re-entrant — the operation must use {@link writeMetaObjectLocked}, never the
+ *  lock-taking {@link writeJsonFileDurably}. */
+export declare function withMetaLock<T>(path: string, operation: () => T): T;
+/** Collision-free durable write (fsync file + parent dir), assuming the caller
+ *  already holds {@link withMetaLock} for `path`. */
+export declare function writeMetaObjectLocked(path: string, value: unknown): void;
+/** Serialize a normal identity write with migrations and use a collision-free durable temp file. */
+export declare function writeJsonFileDurably(path: string, value: unknown): void;
+/** Transform one metadata object in place while holding the same lock normal
+ *  writes honor. The transform MUTATES the passed object and returns whether it
+ *  changed anything; only a `true` return persists the mutated object. */
+export declare function updateJsonFileDurably(path: string, transform: (value: Record<string, unknown>) => boolean): boolean;

package/dist/core/canvas/meta-file.js

@@ -0,0 +1 @@
+var s=Object.defineProperty;var o=(r,e)=>s(r,"name",{value:e,configurable:!0});import{randomUUID as y}from"node:crypto";import{closeSync as c,existsSync as d,fsyncSync as a,openSync as u,readFileSync as w,renameSync as b,rmSync as S,writeSync as p}from"node:fs";import{dirname as $}from"node:path";import{withExclusiveDirectoryLock as x}from"../exclusive-lock.js";function l(r,e){if(!d(r))return null;const t=w(r,"utf8");if(t.trim()===""){if(e)throw new Error(`cannot migrate unreadable node metadata: ${r}`);return null}try{const n=JSON.parse(t);if(typeof n!="object"||n===null||Array.isArray(n))throw new Error("metadata must be an object");return n}catch(n){if(e)throw new Error(`cannot migrate unreadable node metadata: ${r} \u2014 ${n.message}`);return null}}o(l,"parseObject");function D(r){return l(r,!1)}o(D,"readMetaObject");function f(r,e){return x(`${r}.lock`,e,{timeoutMs:5e3,timeoutError:o(()=>new Error(`timed out waiting to write node metadata: ${r}`),"timeoutError")})}o(f,"withMetaLock");function m(r,e){const t=`${r}.${process.pid}.${y()}.tmp`;try{const i=u(t,"w");try{p(i,JSON.stringify(e,null,2)),a(i)}finally{c(i)}b(t,r)}catch(i){throw S(t,{force:!0}),i}const n=u($(r),"r");try{a(n)}finally{c(n)}}o(m,"writeMetaObjectLocked");function F(r,e){f(r,()=>m(r,e))}o(F,"writeJsonFileDurably");function J(r,e){return f(r,()=>{const t=l(r,!1);return t===null||!e(t)?!1:(m(r,t),!0)})}o(J,"updateJsonFileDurably");export{D as readMetaObject,J as updateJsonFileDurably,f as withMetaLock,F as writeJsonFileDurably,m as writeMetaObjectLocked};

package/dist/core/canvas/migrations.d.ts

@@ -0,0 +1,16 @@
+import { DatabaseSync } from 'node:sqlite';
+export declare const MIGRATIONS: ReadonlyArray<(db: DatabaseSync) => void>;
+/** Bring `db` up to the latest schema version. Reads `user_version`, runs each
+ *  pending migration in order, and bumps `user_version` after each so the work
+ *  is gated and idempotent: re-running is a no-op once `user_version` reaches
+ *  `MIGRATIONS.length`. Forward-only.
+ *
+ *  ATOMIC AND RESTARTABLE: each step AND its `user_version` bump run inside one
+ *  `BEGIN IMMEDIATE`/`COMMIT` (SQLite journals `user_version` with the
+ *  transaction, so a rollback restores it too). An interrupted or failing step
+ *  therefore leaves the db exactly at the previous version with none of its
+ *  writes committed — a half-applied step can never wedge every later open. The
+ *  write lock also serializes concurrent openers; the version is re-read after
+ *  acquiring it so a step another process just applied is skipped rather than
+ *  re-run. */
+export declare function migrate(db: DatabaseSync): void;