@north-light/api 0.3.446 → 0.3.447

package/dist/api/__tests__/serial/client.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/api/__tests__/serial/client.test.js

@@ -0,0 +1,141 @@
+// client.test.ts — regression for issue #516: a cold-start `/healthz` timeout
+// used to throw a bare `daemon_unavailable` message that discarded the actual
+// startup failure (the tail of crtrd.err). `coldStartTimeoutMessage` is the
+// pure composition `handleColdSocket` uses on timeout; this proves an injected
+// diagnostic is appended (not dropped) and that a missing/empty diagnostic
+// still falls back to the original bare message unchanged. `safeColdStartDiagnostic`
+// is the guard `handleColdSocket` applies before that composition; this proves a
+// THROWING hook is treated as absent (per the documented `CrtrClientOptions`
+// contract) instead of propagating and replacing the typed `daemon_unavailable`
+// error.
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { createServer } from 'node:http';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { coldStartTimeoutMessage, CrtrClient, safeColdStartDiagnostic } from '../../client.js';
+import { ApiError } from '../../errors.js';
+test('coldStartTimeoutMessage appends a present diagnostic to the base message', () => {
+    const msg = coldStartTimeoutMessage('crtrd.err (tail):\nError: bind EADDRINUSE');
+    assert.match(msg, /crtrd did not start/);
+    assert.match(msg, /crtrd\.err \(tail\):\nError: bind EADDRINUSE/);
+});
+test('coldStartTimeoutMessage falls back to the bare message when no diagnostic is available', () => {
+    assert.equal(coldStartTimeoutMessage(undefined), 'crtrd did not start; run `crtr sys daemon start` and check crtrd.err.');
+    assert.equal(coldStartTimeoutMessage(''), 'crtrd did not start; run `crtr sys daemon start` and check crtrd.err.');
+});
+function startDelayedHealthzServer(socketPath, delayMs) {
+    const server = createServer((_req, res) => {
+        res.writeHead(200, { 'content-type': 'application/json' });
+        res.end(JSON.stringify({ ok: true }));
+    });
+    const timer = setTimeout(() => server.listen(socketPath), delayMs);
+    return { server, cancel: () => clearTimeout(timer) };
+}
+// REGRESSION: `crtr sys daemon restart` acks, then tears the old server down and
+// hands over to a successor — a request crossing that window dies with a hang-up
+// (ECONNRESET), not a refused connect. That used to surface as
+// `daemon_unavailable: socket hang up` telling the caller to run
+// `crtr sys daemon start` against a daemon that was already coming back up.
+function startHandoverServer(socketPath) {
+    let dropped = false;
+    const server = createServer((req, res) => {
+        if (!dropped) {
+            dropped = true; // model the old server dying mid-request
+            req.socket.destroy();
+            return;
+        }
+        res.writeHead(200, { 'content-type': 'application/json' });
+        res.end(JSON.stringify({ ok: true, method: req.method }));
+    });
+    return {
+        server,
+        ready: new Promise((resolvePromise) => server.listen(socketPath, resolvePromise)),
+    };
+}
+test('a hang-up mid-request rides out the daemon handover and replays the idempotent call', async () => {
+    const dir = mkdtempSync(join(tmpdir(), 'crtr-client-handover-'));
+    const socketPath = join(dir, 'crtrd.sock');
+    const { server, ready } = startHandoverServer(socketPath);
+    try {
+        await ready;
+        const client = new CrtrClient({ socketPath, autostart: false, coldStartPollWindowMs: 2_000 });
+        assert.deepEqual(await client.request('GET', '/v1/nodes'), { ok: true, method: 'GET' });
+    }
+    finally {
+        server.close();
+        rmSync(dir, { recursive: true, force: true });
+    }
+});
+test('a hang-up mid-mutation reports daemon_restarting, not daemon_unavailable', async () => {
+    const dir = mkdtempSync(join(tmpdir(), 'crtr-client-handover-'));
+    const socketPath = join(dir, 'crtrd.sock');
+    const { server, ready } = startHandoverServer(socketPath);
+    try {
+        await ready;
+        const client = new CrtrClient({ socketPath, autostart: false, coldStartPollWindowMs: 2_000 });
+        await assert.rejects(() => client.request('POST', '/v1/nodes', {}), 
+        // Replaying is unsafe (the daemon may have applied it), so this one is the
+        // caller's call — but it must not be reported as a daemon that is down.
+        (err) => err instanceof ApiError && err.code === 'daemon_restarting');
+    }
+    finally {
+        server.close();
+        rmSync(dir, { recursive: true, force: true });
+    }
+});
+test('cliClient-style cold start fails loud when the injected poll window is shorter than the (valid) startup delay', async () => {
+    const dir = mkdtempSync(join(tmpdir(), 'crtr-client-coldstart-'));
+    const socketPath = join(dir, 'crtrd.sock');
+    const { server, cancel } = startDelayedHealthzServer(socketPath, 300);
+    try {
+        const client = new CrtrClient({
+            socketPath,
+            autostart: true,
+            onColdSocket: async () => {
+                /* fire-and-forget: the delayed listen() above models ensureDaemon() */
+            },
+            coldStartPollWindowMs: 100, // shorter than the 300ms the daemon actually needs
+        });
+        await assert.rejects(() => client.healthz(), (err) => err instanceof ApiError && err.code === 'daemon_unavailable');
+    }
+    finally {
+        cancel(); // the client already timed out at 100ms; never let listen() fire at 300ms
+        server.close();
+        rmSync(dir, { recursive: true, force: true });
+    }
+});
+test('cliClient-style cold start succeeds when the injected poll window covers the (valid) startup delay', async () => {
+    const dir = mkdtempSync(join(tmpdir(), 'crtr-client-coldstart-'));
+    const socketPath = join(dir, 'crtrd.sock');
+    const { server, cancel } = startDelayedHealthzServer(socketPath, 300);
+    try {
+        const client = new CrtrClient({
+            socketPath,
+            autostart: true,
+            onColdSocket: async () => {
+                /* fire-and-forget: the delayed listen() above models ensureDaemon() */
+            },
+            coldStartPollWindowMs: 2_000, // long enough to see the 300ms-delayed daemon come up
+        });
+        const health = await client.healthz();
+        assert.deepEqual(health, { ok: true });
+    }
+    finally {
+        cancel(); // already fired by the time we get here; harmless no-op
+        server.close();
+        rmSync(dir, { recursive: true, force: true });
+    }
+});
+test('safeColdStartDiagnostic returns undefined for an absent hook', () => {
+    assert.equal(safeColdStartDiagnostic(undefined), undefined);
+});
+test('safeColdStartDiagnostic returns the hook result when it succeeds', () => {
+    assert.equal(safeColdStartDiagnostic(() => 'crtrd.err (tail):\nboom'), 'crtrd.err (tail):\nboom');
+});
+test('safeColdStartDiagnostic treats a THROWING hook as absent, not a propagated error', () => {
+    assert.equal(safeColdStartDiagnostic(() => {
+        throw new Error('custom hook blew up');
+    }), undefined);
+});

package/dist/api/dto/memory.d.ts

@@ -0,0 +1,171 @@
+export declare const MEMORY_SCOPES: readonly ["node", "project", "profile", "user", "builtin"];
+export type MemoryScopeName = typeof MEMORY_SCOPES[number];
+/** A canonical document address: slash-joined safe segments, carried as one percent-encoded path segment. */
+export declare function isMemoryDocName(name: string): boolean;
+export interface MemoryOriginConversationDTO {
+    session_file: string;
+}
+export interface MemoryScope {
+    node?: string;
+    cwd?: string;
+    profile?: string;
+    store?: MemoryScopeName;
+}
+export interface MemoryDocSummaryDTO {
+    name: string;
+    short_form: string;
+    kind: string;
+    privacy: 'public' | 'friends' | 'private';
+    scope: MemoryScopeName;
+    extensions: Record<string, Record<string, string | boolean | number>>;
+    path: string;
+    store_root: string;
+    physical_relative_path: string;
+    candidates?: MemoryCandidateDTO[];
+}
+export interface MemoryCandidateDTO {
+    winner: boolean;
+    scope: MemoryScopeName;
+    store_root: string;
+    physical_relative_path: string;
+    path: string;
+}
+export interface MemoryDocDTO extends MemoryDocSummaryDTO {
+    body: string;
+    frontmatter: Record<string, unknown> | null;
+    representation: 'leaf-file' | 'directory-index';
+    links: string[];
+    findings?: MemoryLintFindingDTO[];
+}
+export interface MemoryLintFindingDTO {
+    severity: string;
+    rule: string;
+    message: string;
+}
+export interface MemoryListQuery extends MemoryScope {
+    kind?: string;
+    limit?: number;
+    after?: string;
+}
+export interface MemoryDocCreateRequest extends MemoryScope {
+    name: string;
+    kind: string;
+    when_and_why_to_read: string;
+    body: string;
+    frontmatter?: Record<string, unknown>;
+    extensions?: Record<string, Record<string, string | boolean | number>>;
+}
+export interface MemoryDocUpdateRequest extends MemoryScope {
+    rationale: string;
+    body?: string;
+    frontmatter?: Record<string, unknown>;
+    extensions?: Record<string, Record<string, string | boolean | number>>;
+    unset?: string[];
+}
+export interface MemoryDocDeletedDTO {
+    name: string;
+    scope: MemoryScopeName;
+    path: string;
+    log_path: string;
+    deleted: true;
+}
+export interface MemoryDocMoveRequest extends MemoryScope {
+    to: string;
+}
+export interface MemoryDocMovedDTO {
+    name: string;
+    previous_name: string;
+    scope: MemoryScopeName;
+    path: string;
+    log_path: string;
+    refs_rewritten: Array<{
+        name: string;
+        scope: MemoryScopeName;
+        path: string;
+        refs: number;
+    }>;
+    follow_up: string;
+}
+export interface MemorySearchRequest extends MemoryScope {
+    query: string;
+    kind?: string;
+    grep?: boolean;
+    body?: boolean;
+    limit?: number;
+    after?: string;
+    min_score?: number;
+}
+export type MemorySearchHitDTO = MemoryRankedSearchHitDTO | MemoryGrepSearchHitDTO;
+export interface MemoryRankedSearchHitDTO {
+    name: string;
+    kind: string;
+    privacy: 'public' | 'friends' | 'private';
+    scope: MemoryScopeName;
+    score: number;
+    short_form: string;
+    path: string;
+    store_root: string;
+    physical_relative_path: string;
+    candidates?: MemoryCandidateDTO[];
+}
+export interface MemoryGrepSearchHitDTO {
+    name: string;
+    privacy: 'public' | 'friends' | 'private';
+    scope: MemoryScopeName;
+    line: number;
+    text: string;
+    path: string;
+    store_root: string;
+    physical_relative_path: string;
+    candidates?: MemoryCandidateDTO[];
+}
+export interface MemoryHistoryQuery extends MemoryScope {
+    limit?: number;
+    revision?: number;
+    diff?: boolean;
+}
+export interface MemoryHistoryRevisionDTO {
+    revision: number;
+    op: 'create' | 'edit' | 'delete' | 'move';
+    at: string;
+    node?: string;
+    rationale?: string;
+    verbatim?: true;
+    body_changed: boolean;
+    frontmatter_changed: string[];
+    diff?: string;
+}
+export interface MemoryHistoryRecordDTO {
+    revision: number;
+    op: 'create' | 'edit' | 'delete' | 'move';
+    at: string;
+    node?: string;
+    cwd: string;
+    from?: string;
+    rationale?: string;
+    verbatim?: boolean;
+    before: string;
+    after: string;
+}
+export interface MemoryHistoryDTO {
+    name: string;
+    scope: MemoryScopeName;
+    log_path: string;
+    total: number;
+    deleted?: unknown;
+    revisions?: MemoryHistoryRevisionDTO[];
+    record?: MemoryHistoryRecordDTO;
+}
+export interface MemoryDocRefDTO {
+    name: string;
+    scope: string;
+    path: string;
+    store_root: string;
+    physical_relative_path: string;
+    plugin?: string;
+}
+export interface MemoryListDTO<T> {
+    object: 'list';
+    data: T[];
+    has_more: boolean;
+}

package/dist/api/dto/memory.js

@@ -0,0 +1,7 @@
+// Memory-document DTOs. Every memory request carries an explicit target; crtrd
+// never resolves documents from its own cwd or environment.
+export const MEMORY_SCOPES = ['node', 'project', 'profile', 'user', 'builtin'];
+/** A canonical document address: slash-joined safe segments, carried as one percent-encoded path segment. */
+export function isMemoryDocName(name) {
+    return /^[A-Za-z0-9._-]+(?:\/[A-Za-z0-9._-]+)*$/.test(name);
+}