@maolon/pi-watcher 0.0.0-stage → 0.1.0

package/dist/source/task-status-v1/adapter.js

@@ -0,0 +1,263 @@
+/**
+ * task-status-v1 read-only SourceAdapter (design 4.1/4.2).
+ * - snapshot is published via atomic replace; journal is JSONL with stable sequence numbers
+ * - cursor stores file identity + byte offset + lastSeq + snapshotSeq
+ * - only complete JSON lines are accepted; a partial line waits for the next round
+ * - truncation/rotation changes the stream generation -> gap=true; the old cursor is not applied directly
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { createHash } from 'node:crypto';
+function fileIdentity(absPath) {
+    try {
+        const st = fs.statSync(absPath);
+        return `${st.dev}:${st.ino}`;
+    }
+    catch {
+        return null;
+    }
+}
+export class TaskStatusV1Adapter {
+    rootDir;
+    adapterId;
+    capabilities = {
+        stableAttempt: true,
+        terminalEvents: true,
+        incrementalCursor: true,
+        exclusiveNotificationOwner: true
+    };
+    timeoutMs;
+    maxBytes;
+    constructor(rootDir, options = {}) {
+        this.rootDir = rootDir;
+        this.adapterId = options.adapterId ?? 'task-status-v1';
+        this.timeoutMs = options.defaultTimeoutMs ?? 5000;
+        this.maxBytes = options.defaultMaxBytes ?? 65536;
+    }
+    targetDir(target) {
+        return path.join(this.rootDir, target.sourceId, target.taskId, target.runId, target.attemptId);
+    }
+    async read(target, cursor, signal) {
+        if (signal.aborted)
+            throw signal.reason ?? new Error('aborted');
+        const cur = normalizeCursor(cursor);
+        const dir = this.targetDir(target);
+        const journalPath = path.join(dir, 'journal.jsonl');
+        const snapshotPath = path.join(dir, 'snapshot.json');
+        let gap = false;
+        let offset = cur.offset;
+        let lastSeq = cur.lastSeq;
+        const nextCursor = { fileId: cur.fileId, offset, lastSeq, snapshotSeq: cur.snapshotSeq };
+        const observations = [];
+        // --- journal (JSONL with stable sequence numbers) ---
+        const journalId = fileIdentity(journalPath);
+        if (journalId !== null) {
+            if (cur.fileId !== null && cur.fileId !== journalId) {
+                // stream generation change (rotation/replacement): gap, re-read from the start, dedup by store
+                gap = true;
+                offset = 0;
+            }
+            const size = fs.statSync(journalPath).size;
+            if (offset > size) {
+                // in-place truncation
+                gap = true;
+                offset = 0;
+            }
+            if (size > offset) {
+                const fh = fs.openSync(journalPath, 'r');
+                try {
+                    const readLen = Math.min(size - offset, this.maxBytes);
+                    const buf = Buffer.alloc(readLen);
+                    const bytesRead = fs.readSync(fh, buf, 0, readLen, offset);
+                    const text = buf.subarray(0, bytesRead).toString('utf8');
+                    const lines = text.split('\n');
+                    // last element is '' (complete line) or a partial line: a partial line does not advance offset and waits for the next round
+                    lines.pop();
+                    let advanced = 0;
+                    const events = [];
+                    for (const line of lines) {
+                        const trimmed = line.trim();
+                        const lineLen = Buffer.byteLength(line, 'utf8') + 1;
+                        if (trimmed === '') {
+                            advanced += lineLen;
+                            continue;
+                        }
+                        try {
+                            events.push(JSON.parse(trimmed));
+                        }
+                        catch {
+                            // complete line but invalid JSON: audit gap, does not advance state conclusions
+                            gap = true;
+                        }
+                        advanced += lineLen;
+                    }
+                    offset += advanced;
+                    for (const ev of events) {
+                        if (typeof ev.sourceSeq !== 'number' || ev.sourceSeq <= lastSeq)
+                            continue;
+                        lastSeq = ev.sourceSeq;
+                        observations.push(journalObservation(target, ev));
+                    }
+                }
+                finally {
+                    fs.closeSync(fh);
+                }
+            }
+            nextCursor.offset = offset;
+            nextCursor.lastSeq = lastSeq;
+            nextCursor.fileId = journalId;
+        }
+        else if (cur.fileId !== null) {
+            // journal disappeared -> source gap
+            gap = true;
+            nextCursor.fileId = null;
+        }
+        // --- snapshot (atomic replace; a parse failure does not overwrite the last valid state) ---
+        if (fs.existsSync(snapshotPath)) {
+            let snapshot = null;
+            try {
+                snapshot = JSON.parse(fs.readFileSync(snapshotPath, 'utf8'));
+            }
+            catch {
+                snapshot = null;
+            }
+            if (snapshot && typeof snapshot.snapshotSeq === 'number' && snapshot.snapshotSeq > cur.snapshotSeq) {
+                nextCursor.snapshotSeq = snapshot.snapshotSeq;
+                observations.push(snapshotObservation(target, snapshot));
+            }
+        }
+        observations.sort((a, b) => a.sourceSeq - b.sourceSeq);
+        return { observations, nextCursor: nextCursor, gap };
+    }
+    async probes(target, _basis) {
+        const dir = this.targetDir(target);
+        const expiresAt = new Date(Date.now() + 60_000).toISOString();
+        const base = { target, scopeId: dir, expiresAt, timeoutMs: this.timeoutMs };
+        return [
+            { probeId: 'task-status-v1:read-status', revision: 1, kind: 'read-status', maxBytes: 64 * 1024, ...base },
+            { probeId: 'task-status-v1:read-log-delta', revision: 1, kind: 'read-log-delta', maxBytes: 128 * 1024, ...base },
+            { probeId: 'task-status-v1:read-artifact-manifest', revision: 1, kind: 'read-artifact-manifest', maxBytes: 64 * 1024, ...base },
+            { probeId: 'task-status-v1:read-validation-result', revision: 1, kind: 'read-validation-result', maxBytes: 64 * 1024, ...base }
+        ];
+    }
+    async execute(probe, signal) {
+        if (signal.aborted)
+            throw signal.reason ?? new Error('aborted');
+        const dir = probe.scopeId;
+        const nowIso = new Date().toISOString();
+        const mk = (kind, payload) => ({
+            schemaVersion: 1,
+            observationId: `obs-probe-${probe.probeId}-${Date.now()}-${Math.floor(Math.random() * 1e6)}`,
+            target: probe.target,
+            sourceSeq: 0,
+            observedAt: nowIso,
+            kind,
+            payload,
+            evidenceRefs: []
+        });
+        const readSnapshot = () => {
+            const p = path.join(dir, 'snapshot.json');
+            if (!fs.existsSync(p))
+                return null;
+            try {
+                return JSON.parse(fs.readFileSync(p, 'utf8'));
+            }
+            catch {
+                return null;
+            }
+        };
+        switch (probe.kind) {
+            case 'read-status': {
+                const snap = readSnapshot();
+                return [mk('status', snap ? snap : { state: 'unknown', note: 'no snapshot' })];
+            }
+            case 'read-log-delta': {
+                const p = path.join(dir, 'journal.jsonl');
+                if (!fs.existsSync(p))
+                    return [mk('log_delta', { lines: [], note: 'no journal' })];
+                const lines = fs.readFileSync(p, 'utf8').split('\n').filter(l => l.trim() !== '').slice(-32);
+                return [mk('log_delta', { lines })];
+            }
+            case 'read-artifact-manifest': {
+                const snap = readSnapshot();
+                const payload = { artifacts: snap?.artifacts ?? [] };
+                if (!snap)
+                    payload.note = 'no snapshot';
+                return [mk('artifact_manifest', payload)];
+            }
+            case 'read-validation-result': {
+                const snap = readSnapshot();
+                const payload = { checks: snap?.checks ?? [] };
+                if (!snap)
+                    payload.note = 'no snapshot';
+                return [mk('validation', payload)];
+            }
+            default:
+                return [];
+        }
+    }
+    async close() {
+        /* nothing to close */
+    }
+}
+function normalizeCursor(cursor) {
+    if (!cursor || typeof cursor !== 'object')
+        return { fileId: null, offset: 0, lastSeq: 0, snapshotSeq: 0 };
+    const c = cursor;
+    return {
+        fileId: typeof c.fileId === 'string' ? c.fileId : null,
+        offset: typeof c.offset === 'number' ? c.offset : 0,
+        lastSeq: typeof c.lastSeq === 'number' ? c.lastSeq : 0,
+        snapshotSeq: typeof c.snapshotSeq === 'number' ? c.snapshotSeq : 0
+    };
+}
+function evidenceRefsFor(target, ev) {
+    const text = JSON.stringify({ target, seq: ev.sourceSeq, at: ev.at, kind: ev.kind, payload: ev.payload });
+    const sha = createHash('sha256').update(text).digest('hex');
+    return [
+        {
+            evidenceId: `ev-${sha.slice(0, 16)}`,
+            sourceId: target.sourceId,
+            capturedAt: ev.at,
+            sha256: sha,
+            bytes: Buffer.byteLength(text, 'utf8'),
+            sampled: false
+        }
+    ];
+}
+function journalObservation(target, ev) {
+    return {
+        schemaVersion: 1,
+        observationId: `obs-${target.sourceId}-${target.runId}-${ev.sourceSeq}`,
+        target,
+        sourceSeq: ev.sourceSeq,
+        observedAt: ev.at,
+        kind: ev.kind,
+        payload: ev.payload,
+        evidenceRefs: evidenceRefsFor(target, ev)
+    };
+}
+function snapshotObservation(target, snap) {
+    return {
+        schemaVersion: 1,
+        observationId: `obs-${target.sourceId}-${target.runId}-snap-${snap.snapshotSeq}`,
+        target,
+        sourceSeq: snap.snapshotSeq,
+        observedAt: snap.updatedAt,
+        kind: 'status',
+        payload: {
+            state: snap.state,
+            stage: snap.stage,
+            exitCode: snap.exitCode,
+            summary: snap.summary,
+            checks: snap.checks,
+            artifacts: snap.artifacts
+        },
+        evidenceRefs: evidenceRefsFor(target, {
+            sourceSeq: snap.snapshotSeq,
+            at: snap.updatedAt,
+            kind: 'status',
+            payload: { state: snap.state }
+        })
+    };
+}

package/dist/source/task-status-v1/producer.d.ts

@@ -0,0 +1,81 @@
+/**
+ * task-status-v1 fixture producer (design 4.1).
+ * Real async process: publishes the snapshot via a same-directory temp file + atomic replace; the journal is JSONL with stable sequence numbers.
+ * The watcher only reads these files and is not responsible for task execution.
+ */
+export type TaskState = 'unknown' | 'queued' | 'running' | 'blocked' | 'succeeded' | 'failed' | 'cancelled';
+export interface TaskStatusSnapshot {
+    schemaVersion: 1;
+    target: {
+        kind: 'run';
+        sourceId: string;
+        taskId: string;
+        runId: string;
+        attemptId: string;
+    };
+    state: TaskState;
+    stage: string | null;
+    exitCode: number | null;
+    summary: string | null;
+    checks: Array<{
+        checkId: string;
+        outcome: 'passed' | 'failed' | 'skipped' | 'unknown';
+        artifactDigest: string | null;
+    }>;
+    artifacts: Array<{
+        artifactId: string;
+        sha256: string;
+        sourceRevision: number;
+    }>;
+    snapshotSeq: number;
+    updatedAt: string;
+}
+export interface TaskStatusJournalEvent {
+    schemaVersion: 1;
+    sourceSeq: number;
+    at: string;
+    kind: 'status' | 'heartbeat' | 'log_delta' | 'validation' | 'artifact_manifest' | 'decision_request';
+    payload: Record<string, unknown>;
+}
+export declare function runDir(rootDir: string, target: {
+    sourceId: string;
+    taskId: string;
+    runId: string;
+    attemptId: string;
+}): string;
+export declare class TaskStatusProducer {
+    private readonly journalId;
+    private seq;
+    private readonly dir;
+    private readonly target;
+    private snapshot;
+    constructor(rootDir: string, target: {
+        sourceId: string;
+        taskId: string;
+        runId: string;
+        attemptId: string;
+    }, journalId?: string);
+    private nextSeq;
+    private nowIso;
+    appendEvent(kind: TaskStatusJournalEvent['kind'], payload: Record<string, unknown>): Promise<number>;
+    /** Atomic snapshot replace: tmp file + rename in the same directory. */
+    publishSnapshot(patch: Partial<Omit<TaskStatusSnapshot, 'schemaVersion' | 'target' | 'snapshotSeq' | 'updatedAt'>>): Promise<number>;
+    get lastSnapshot(): TaskStatusSnapshot | null;
+}
+export interface ProducerStep {
+    waitMs: number;
+    event?: {
+        kind: TaskStatusJournalEvent['kind'];
+        payload: Record<string, unknown>;
+    };
+    snapshot?: Partial<Omit<TaskStatusSnapshot, 'schemaVersion' | 'target' | 'snapshotSeq' | 'updatedAt'>>;
+}
+/** Real async fixture scenarios. */
+export declare function runScenario(rootDir: string, target: {
+    sourceId: string;
+    taskId: string;
+    runId: string;
+    attemptId: string;
+}, steps: ProducerStep[]): Promise<TaskStatusProducer>;
+/** Standard demo scenarios: build-success / build-failure. */
+export declare function scenarioSteps(kind: 'build-success' | 'build-failure', intervalMs?: number): ProducerStep[];

package/dist/source/task-status-v1/producer.js

@@ -0,0 +1,127 @@
+/**
+ * task-status-v1 fixture producer (design 4.1).
+ * Real async process: publishes the snapshot via a same-directory temp file + atomic replace; the journal is JSONL with stable sequence numbers.
+ * The watcher only reads these files and is not responsible for task execution.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { randomUUID } from 'node:crypto';
+export function runDir(rootDir, target) {
+    return path.join(rootDir, target.sourceId, target.taskId, target.runId, target.attemptId);
+}
+export class TaskStatusProducer {
+    journalId;
+    seq = 0;
+    dir;
+    target;
+    snapshot = null;
+    constructor(rootDir, target, journalId = `journal-${randomUUID().slice(0, 8)}`) {
+        this.journalId = journalId;
+        this.dir = runDir(rootDir, target);
+        this.target = { kind: 'run', ...target };
+        fs.mkdirSync(this.dir, { recursive: true });
+    }
+    nextSeq() {
+        this.seq += 1;
+        return this.seq;
+    }
+    nowIso() {
+        return new Date().toISOString();
+    }
+    async appendEvent(kind, payload) {
+        const sourceSeq = this.nextSeq();
+        const event = {
+            schemaVersion: 1,
+            sourceSeq,
+            at: this.nowIso(),
+            kind,
+            payload
+        };
+        await fs.promises.appendFile(path.join(this.dir, 'journal.jsonl'), JSON.stringify(event) + '\n', 'utf8');
+        return sourceSeq;
+    }
+    /** Atomic snapshot replace: tmp file + rename in the same directory. */
+    async publishSnapshot(patch) {
+        const snapshotSeq = this.nextSeq();
+        const prev = this.snapshot;
+        this.snapshot = {
+            schemaVersion: 1,
+            target: this.target,
+            state: patch.state ?? prev?.state ?? 'unknown',
+            stage: patch.stage !== undefined ? patch.stage : (prev?.stage ?? null),
+            exitCode: patch.exitCode !== undefined ? patch.exitCode : (prev?.exitCode ?? null),
+            summary: patch.summary !== undefined ? patch.summary : (prev?.summary ?? null),
+            checks: patch.checks !== undefined ? patch.checks : (prev?.checks ?? []),
+            artifacts: patch.artifacts !== undefined ? patch.artifacts : (prev?.artifacts ?? []),
+            snapshotSeq,
+            updatedAt: this.nowIso()
+        };
+        const tmp = path.join(this.dir, `.snapshot.${snapshotSeq}.tmp`);
+        await fs.promises.writeFile(tmp, JSON.stringify(this.snapshot, null, 2), 'utf8');
+        await fs.promises.rename(tmp, path.join(this.dir, 'snapshot.json'));
+        return snapshotSeq;
+    }
+    get lastSnapshot() {
+        return this.snapshot;
+    }
+}
+/** Real async fixture scenarios. */
+export async function runScenario(rootDir, target, steps) {
+    const producer = new TaskStatusProducer(rootDir, target);
+    for (const step of steps) {
+        if (step.waitMs > 0) {
+            await new Promise(resolve => setTimeout(resolve, step.waitMs));
+        }
+        if (step.event) {
+            await producer.appendEvent(step.event.kind, step.event.payload);
+        }
+        if (step.snapshot) {
+            await producer.publishSnapshot(step.snapshot);
+        }
+    }
+    return producer;
+}
+/** Standard demo scenarios: build-success / build-failure. */
+export function scenarioSteps(kind, intervalMs = 200) {
+    if (kind === 'build-success') {
+        return [
+            { waitMs: intervalMs, snapshot: { state: 'running', stage: 'compile', summary: 'compiling' } },
+            { waitMs: intervalMs, event: { kind: 'log_delta', payload: { lines: ['cc -c main.c', 'cc -c util.c'] } } },
+            { waitMs: intervalMs, snapshot: { state: 'running', stage: 'test', summary: 'compile finished, running tests' } },
+            { waitMs: intervalMs, event: { kind: 'validation', payload: { checkId: 'unit-tests', outcome: 'passed', artifactDigest: 'deadbeef01' } } },
+            {
+                waitMs: intervalMs,
+                snapshot: {
+                    state: 'succeeded',
+                    stage: 'done',
+                    exitCode: 0,
+                    summary: 'build and tests completed',
+                    checks: [{ checkId: 'unit-tests', outcome: 'passed', artifactDigest: 'deadbeef01' }],
+                    artifacts: [{ artifactId: 'artifact-app', sha256: 'a'.repeat(64), sourceRevision: 1 }]
+                }
+            }
+        ];
+    }
+    return [
+        { waitMs: intervalMs, snapshot: { state: 'running', stage: 'compile', summary: 'compiling' } },
+        { waitMs: intervalMs, event: { kind: 'log_delta', payload: { lines: ['cc -c main.c'] } } },
+        {
+            waitMs: intervalMs,
+            event: {
+                kind: 'decision_request',
+                payload: { text: 'Compiler reports that the requested API does not exist. Need the host to choose which API contract to target.' }
+            }
+        },
+        {
+            waitMs: intervalMs,
+            snapshot: {
+                state: 'failed',
+                stage: 'compile',
+                exitCode: 2,
+                summary: 'executor reports build failure; not yet attributed.',
+                checks: [{ checkId: 'unit-tests', outcome: 'unknown', artifactDigest: null }],
+                artifacts: []
+            }
+        }
+    ];
+}

package/dist/storage/lock.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Root singleton lock: persistent advisory lock on a fixed-inode lock file (design 7.2).
+ * The lock file is never deleted or replaced; a second instance may only report a conflict and must not start a second set of timers.
+ */
+export declare class RootLock {
+    readonly lockPath: string;
+    private fd;
+    constructor(rootDir: string);
+    /** Exclusive, non-blocking. Returns true when acquired; false when already held. */
+    tryAcquire(): Promise<boolean>;
+    requireAcquire(): Promise<void>;
+    get held(): boolean;
+    release(): Promise<void>;
+}

package/dist/storage/lock.js

@@ -0,0 +1,66 @@
+/**
+ * Root singleton lock: persistent advisory lock on a fixed-inode lock file (design 7.2).
+ * The lock file is never deleted or replaced; a second instance may only report a conflict and must not start a second set of timers.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { flock } from 'fs-ext';
+import { WatcherError } from '../util/result.js';
+function flockAsync(fd, mode) {
+    return new Promise((resolve, reject) => {
+        flock(fd, mode, (err) => {
+            if (err)
+                reject(err);
+            else
+                resolve();
+        });
+    });
+}
+export class RootLock {
+    lockPath;
+    fd = null;
+    constructor(rootDir) {
+        this.lockPath = path.join(rootDir, 'watcher.lock');
+    }
+    /** Exclusive, non-blocking. Returns true when acquired; false when already held. */
+    async tryAcquire() {
+        if (this.fd !== null)
+            return true;
+        // 'a' keeps the existing inode; never truncate/replace the lock file.
+        const fd = fs.openSync(this.lockPath, 'a');
+        try {
+            await flockAsync(fd, 'exnb');
+            this.fd = fd;
+            return true;
+        }
+        catch (e) {
+            const code = e.code;
+            fs.closeSync(fd);
+            if (code === 'EAGAIN' || code === 'EWOULDBLOCK' || code === 'EACCES' || code === 'EDEADLK') {
+                return false;
+            }
+            throw e;
+        }
+    }
+    async requireAcquire() {
+        const got = await this.tryAcquire();
+        if (!got) {
+            throw new WatcherError('ROOT_LOCK_HELD', `watcher root already locked by another process: ${this.lockPath}`);
+        }
+    }
+    get held() {
+        return this.fd !== null;
+    }
+    async release() {
+        if (this.fd === null)
+            return;
+        const fd = this.fd;
+        this.fd = null;
+        try {
+            await flockAsync(fd, 'un');
+        }
+        finally {
+            fs.closeSync(fd);
+        }
+    }
+}