@nocville/npc 0.3.0 → 0.4.0

package/dist/cli.js

@@ -56,10 +56,12 @@ Monitoring NPC types:
   plant-caretaker         Waters plants and reviews their performance
   it-technician           Inspects tech gear and recommends reboots
   out-of-touch-executive  Interrupts coworkers between long lounge breaks
+  slightly-inappropriate-hr  Desk-based HR with questionable people skills
   github-watcher          Call out new commits on a repo
   web-page-watcher        Render a watched web page as a pixel-art TV
 
 Common Options:
+  --workspace=<file>     Verified producer workspace settings from team privacy settings.
   --api-key=<key>         Team API key (or NOCVILLE_API_KEY env)
   --api-url=<url>         Nocville API URL (or NOCVILLE_API_URL env).
                           Default: https://nocville.com. For local dev use
@@ -382,7 +384,8 @@ async function main() {
         case 'office-dog':
         case 'plant-caretaker':
         case 'it-technician':
-        case 'out-of-touch-executive': {
+        case 'out-of-touch-executive':
+        case 'slightly-inappropriate-hr': {
             if (!config.serviceId)
                 config.serviceId = parsed.command;
             const { OFFICE_CHARACTER_NPCS } = await import('./npcs/office-characters/index.js');
@@ -475,7 +478,20 @@ async function runInit(flags, config) {
     let apiKey = stringFlag(flags, 'api-key');
     const apiUrl = stringFlag(flags, 'api-url');
     const map = stringFlag(flags, 'map');
-    if (!apiKey && !apiUrl && !map) {
+    const workspace = config.workspace;
+    if (workspace)
+        apiKey = apiKey || config.apiKey;
+    if (workspace && !apiKey) {
+        const { resolveApiKey } = await import('./core/api-key.js');
+        const resolved = await resolveApiKey({ flags });
+        if (!resolved.ok) {
+            console.error(resolved.error);
+            process.exitCode = 1;
+            return;
+        }
+        apiKey = resolved.key;
+    }
+    if (!apiKey && !apiUrl && !map && !workspace) {
         const saved = loadUserConfig();
         if (saved.apiKey && !process.env['NOCVILLE_API_KEY']?.trim()) {
             console.log('Usage: nocville-npc init --api-key=<key> [--api-url=<url>] [--map=<name>]');
@@ -491,7 +507,12 @@ async function runInit(flags, config) {
         }
         apiKey = resolved.key;
     }
-    const path = saveUserConfig({ apiKey, apiUrl, map });
+    const path = saveUserConfig({
+        apiKey,
+        apiUrl: workspace ? config.apiUrl : apiUrl,
+        map: workspace ? config.map : map,
+        workspace,
+    });
     const saved = loadUserConfig();
     console.log(`✓ Saved ${path} (mode 0600)`);
     console.log(`  API: ${saved.apiUrl ?? 'https://nocville.com'}  key: ${maskKey(saved.apiKey)}`);

package/dist/core/base-npc.js

@@ -14,6 +14,7 @@ export class BaseNPC {
         // We can't access `this.name` here since it's abstract, so use a placeholder
         this.logger = new Logger('npc', config.debug);
         this.client = new NocvilleClient({
+            workspace: config.workspace,
             apiUrl: config.apiUrl,
             apiKey: config.apiKey,
             serviceId: config.serviceId,

package/dist/core/config.js

@@ -1,3 +1,5 @@
+import { loadProducerWorkspace } from '@nocville/node';
+import { resolve } from 'node:path';
 import { loadUserConfig } from './user-config.js';
 /**
  * Simple hand-rolled CLI arg parser.
@@ -48,9 +50,16 @@ export function parseArgs(argv) {
  */
 export function resolveConfig(flags, overrides) {
     const saved = loadUserConfig();
+    const workspacePath = overrides?.workspace ||
+        stringFlag(flags, 'workspace') ||
+        process.env['NOCVILLE_WORKSPACE'] ||
+        saved.workspace;
+    const workspace = workspacePath ? resolve(workspacePath) : undefined;
+    const enrollment = workspace ? loadProducerWorkspace(workspace) : undefined;
     const apiUrl = overrides?.apiUrl ||
         stringFlag(flags, 'api-url') ||
         process.env['NOCVILLE_API_URL'] ||
+        enrollment?.apiUrl ||
         saved.apiUrl ||
         'https://nocville.com';
     const apiKey = overrides?.apiKey ||
@@ -68,10 +77,23 @@ export function resolveConfig(flags, overrides) {
     const map = overrides?.map ||
         stringFlag(flags, 'map') ||
         process.env['NOCVILLE_MAP'] ||
+        enrollment?.encryption.mapId ||
         saved.map ||
         undefined;
     const name = overrides?.name || stringFlag(flags, 'name') || process.env['NOCVILLE_NAME'] || undefined;
-    return { apiUrl, apiKey, serviceId, debug, map, name };
+    if (enrollment && apiUrl.replace(/\/+$/, '') !== enrollment.apiUrl)
+        throw new Error('API origin does not match the verified workspace');
+    if (enrollment && map && map !== enrollment.encryption.mapId)
+        throw new Error('Encrypted producers use the map ID in their workspace settings');
+    return {
+        apiUrl,
+        apiKey,
+        serviceId,
+        debug,
+        map: enrollment?.encryption.mapId ?? map,
+        name,
+        ...(workspace ? { workspace } : {}),
+    };
 }
 export function stringFlag(flags, key) {
     const val = flags[key];

package/dist/core/polling-npc.d.ts

@@ -2,6 +2,8 @@ import { BaseNPC } from './base-npc.js';
 import type { NpcConfig, CollectedMetrics } from './types.js';
 export interface PollingNpcConfig extends NpcConfig {
     pollInterval?: number;
+    /** Local diagnostics; never included in published payloads. */
+    onCollection?: (metrics: CollectedMetrics) => void;
 }
 /**
  * Lower bound for any poll interval, so a typo can't exhaust the API's
@@ -19,6 +21,7 @@ export declare abstract class PollingNPC extends BaseNPC {
     private lastPushed;
     private lastPushAt;
     protected pollInterval: number;
+    private onCollection?;
     constructor(config: PollingNpcConfig);
     /** Scale staleness to the poll cadence: the server marks unknown at ~2x the interval. */
     get heartbeatSeconds(): number;

package/dist/core/polling-npc.js

@@ -20,8 +20,10 @@ export class PollingNPC extends BaseNPC {
     lastPushed = null;
     lastPushAt = 0;
     pollInterval;
+    onCollection;
     constructor(config) {
         super(config);
+        this.onCollection = config.onCollection;
         const requested = config.pollInterval ?? 15000;
         this.pollInterval = Number.isFinite(requested)
             ? Math.max(MIN_POLL_INTERVAL_MS, requested)
@@ -114,6 +116,12 @@ export class PollingNPC extends BaseNPC {
             // Stopped mid-collection: never push after (or race) the offline push.
             if (this.state !== 'running')
                 return;
+            try {
+                this.onCollection?.(metrics);
+            }
+            catch {
+                /* Diagnostics cannot stop publishing. */
+            }
             await this.pushMetrics(metrics);
             this.lastPushed = metrics;
             this.lastPushAt = Date.now();

package/dist/core/types.d.ts

@@ -6,6 +6,8 @@ export type Archetype = 'service' | 'database' | 'trading' | 'ai-agent' | 'pipel
 /** A companion declaration is the SDK's CompanionSpec. */
 export type CompanionDecl = CompanionSpec;
 export interface NpcConfig {
+    /** Local verified workspace enrollment bundle. */
+    workspace?: string;
     apiUrl: string;
     apiKey: string;
     serviceId: string;

package/dist/core/user-config.d.ts

@@ -4,6 +4,7 @@
  * has to appear in ~/.claude/settings.json, ~/.codex/hooks.json or `ps` output.
  */
 export interface UserConfig {
+    workspace?: string;
     apiUrl?: string;
     apiKey?: string;
     map?: string;

package/dist/core/user-config.js

@@ -18,6 +18,8 @@ export function loadUserConfig(path = userConfigPath()) {
     try {
         const raw = JSON.parse(readFileSync(path, 'utf-8'));
         const out = {};
+        if (typeof raw['workspace'] === 'string' && raw['workspace'])
+            out.workspace = raw['workspace'];
         if (typeof raw['apiUrl'] === 'string' && raw['apiUrl'])
             out.apiUrl = raw['apiUrl'];
         if (typeof raw['apiKey'] === 'string' && raw['apiKey'])

package/dist/doctor.js

@@ -1,3 +1,4 @@
+import { NocvilleClient } from '@nocville/node';
 import { randomUUID } from 'node:crypto';
 import { readdirSync } from 'node:fs';
 import { isAgentAlive } from './npcs/agent-common/liveness.js';
@@ -39,6 +40,24 @@ export async function runDoctor(config) {
     if (!hasKey) {
         console.log('  [SKIP] POST /api/v1/status — no --api-key / NOCVILLE_API_KEY set');
     }
+    else if (config.workspace || config.apiKey.includes('.team_')) {
+        // Exercise the locally encrypted path; never send a plaintext probe to a v2 workspace.
+        try {
+            const client = new NocvilleClient({
+                workspace: config.workspace,
+                apiUrl: config.apiUrl,
+                apiKey: config.apiKey,
+                serviceId: 'nocville-doctor',
+                retries: 0,
+            });
+            const result = await client.pushStatus({ status: 'unknown', offline: true });
+            pushOk = result.success;
+            console.log(`  [${pushOk ? 'OK' : 'FAIL'}] Encrypted producer: ${result.error ?? 'accepted'}`);
+        }
+        catch (error) {
+            console.log(`  [FAIL] Encrypted producer: ${error.message}`);
+        }
+    }
     else {
         const start = Date.now();
         const t = withTimeout(5000);

package/dist/index.d.ts

@@ -42,5 +42,5 @@ export { CURSOR_DEFAULTS, CURSOR_ADAPTER, cursorServiceId, handleCursorHookEvent
 export type { CursorSetupOptions } from './npcs/cursor/index.js';
 export { isCursorInvocation, normalizeCursorEvent } from './npcs/cursor/normalize.js';
 export { SecurityNPC } from './npcs/security/index.js';
-export { JanitorNPC, BaristaNPC, OfficeCatNPC, OfficeDogNPC, PlantCaretakerNPC, ITTechnicianNPC, OutOfTouchExecutiveNPC, OFFICE_CHARACTER_NPCS, } from './npcs/office-characters/index.js';
+export { JanitorNPC, BaristaNPC, OfficeCatNPC, OfficeDogNPC, PlantCaretakerNPC, ITTechnicianNPC, OutOfTouchExecutiveNPC, SlightlyInappropriateHRNPC, OFFICE_CHARACTER_NPCS, } from './npcs/office-characters/index.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -26,5 +26,5 @@ export { GEMINI_DEFAULTS, GEMINI_ADAPTER, geminiTransition, geminiServiceId, han
 export { CURSOR_DEFAULTS, CURSOR_ADAPTER, cursorServiceId, handleCursorHookEvent, setupCursorHooks, uninstallCursorHooks, installCursorHooksInto, CURSOR_HOOK_EVENTS, } from './npcs/cursor/index.js';
 export { isCursorInvocation, normalizeCursorEvent } from './npcs/cursor/normalize.js';
 export { SecurityNPC } from './npcs/security/index.js';
-export { JanitorNPC, BaristaNPC, OfficeCatNPC, OfficeDogNPC, PlantCaretakerNPC, ITTechnicianNPC, OutOfTouchExecutiveNPC, OFFICE_CHARACTER_NPCS, } from './npcs/office-characters/index.js';
+export { JanitorNPC, BaristaNPC, OfficeCatNPC, OfficeDogNPC, PlantCaretakerNPC, ITTechnicianNPC, OutOfTouchExecutiveNPC, SlightlyInappropriateHRNPC, OFFICE_CHARACTER_NPCS, } from './npcs/office-characters/index.js';
 //# sourceMappingURL=index.js.map

package/dist/npcs/agent-common/session.js

@@ -241,6 +241,7 @@ export function buildAgentPayload(adapter, state, config) {
 }
 async function defaultPush(config, serviceId, payload, timeoutMs) {
     const client = new NocvilleClient({
+        workspace: config.workspace,
         apiUrl: config.apiUrl,
         apiKey: config.apiKey,
         serviceId,
@@ -359,6 +360,8 @@ export function spawnDetachedAgent(adapter, config, args, cliPath = process.argv
     if (!cliPath)
         return undefined;
     const env = { ...process.env };
+    if (config.workspace)
+        env['NOCVILLE_WORKSPACE'] = config.workspace;
     env['NOCVILLE_API_URL'] = config.apiUrl;
     env['NOCVILLE_API_KEY'] = config.apiKey;
     if (config.map)

package/dist/npcs/codex/watcher.js

@@ -335,6 +335,7 @@ export class CodexWatcher {
             let client = this.clients.get(serviceId);
             if (!client) {
                 client = new NocvilleClient({
+                    workspace: this.config.workspace,
                     apiUrl: this.config.apiUrl,
                     apiKey: this.config.apiKey,
                     serviceId,

package/dist/npcs/github-watcher/github.d.ts

@@ -0,0 +1,39 @@
+export interface CommitInfo {
+    sha: string;
+    author: string;
+    message: string;
+    date: string;
+}
+export interface FetchCommitsResult {
+    /** 304 Not Modified — the ETag matched, nothing changed, no rate-limit cost. */
+    notModified: boolean;
+    commits: CommitInfo[];
+    etag: string | null;
+    rateRemaining: number | null;
+    status: number;
+}
+export interface FetchOptions {
+    token?: string;
+    etag?: string | null;
+    timeoutMs?: number;
+    perPage?: number;
+}
+/**
+ * Fetch recent commits from the GitHub REST API using conditional requests.
+ * Passing the previous ETag yields a 304 (which does not count against the
+ * unauthenticated 60/hour limit) when nothing has changed. Never throws —
+ * network errors surface as `status: 0`.
+ */
+export declare function fetchCommits(repo: string, opts?: FetchOptions): Promise<FetchCommitsResult>;
+/** Count how many commits landed within the last `hours`. */
+export declare function commitsWithin(commits: CommitInfo[], hours: number, now?: number): number;
+/** Short relative-time string like "3m ago", "2h ago", "1d ago". */
+export declare function relativeTime(iso: string, now?: number): string;
+/**
+ * Return the commits newer than `lastSeenSha`, newest-first. When the sha isn't
+ * present in the window (more than a page of new commits, or rewritten history)
+ * every fetched commit is treated as new. An undefined sha means "not seeded
+ * yet" — returns empty so the caller can seed without a spurious announcement.
+ */
+export declare function newCommitsSince(commits: CommitInfo[], lastSeenSha: string | null): CommitInfo[];
+//# sourceMappingURL=github.d.ts.map

package/dist/npcs/github-watcher/github.js

@@ -0,0 +1,103 @@
+function toNum(v) {
+    if (v === null)
+        return null;
+    const n = Number(v);
+    return Number.isNaN(n) ? null : n;
+}
+/**
+ * Fetch recent commits from the GitHub REST API using conditional requests.
+ * Passing the previous ETag yields a 304 (which does not count against the
+ * unauthenticated 60/hour limit) when nothing has changed. Never throws —
+ * network errors surface as `status: 0`.
+ */
+export async function fetchCommits(repo, opts = {}) {
+    const perPage = opts.perPage ?? 10;
+    const url = `https://api.github.com/repos/${repo}/commits?per_page=${perPage}`;
+    const headers = {
+        Accept: 'application/vnd.github+json',
+        'User-Agent': 'nocville-npc',
+        'X-GitHub-Api-Version': '2022-11-28',
+    };
+    if (opts.token)
+        headers['Authorization'] = `Bearer ${opts.token}`;
+    if (opts.etag)
+        headers['If-None-Match'] = opts.etag;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), opts.timeoutMs ?? 5000);
+    try {
+        const res = await fetch(url, { headers, signal: controller.signal });
+        const rateRemaining = toNum(res.headers.get('x-ratelimit-remaining'));
+        const etag = res.headers.get('etag');
+        if (res.status === 304) {
+            return { notModified: true, commits: [], etag: opts.etag ?? null, rateRemaining, status: 304 };
+        }
+        if (!res.ok) {
+            // Drain the body so the socket can be reused.
+            await res.text().catch(() => undefined);
+            return { notModified: false, commits: [], etag, rateRemaining, status: res.status };
+        }
+        const body = (await res.json());
+        const commits = body.map((c) => parseCommit(c));
+        return { notModified: false, commits, etag, rateRemaining, status: res.status };
+    }
+    catch {
+        return { notModified: false, commits: [], etag: null, rateRemaining: null, status: 0 };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+function parseCommit(c) {
+    const commit = c['commit'] ?? {};
+    const commitAuthor = commit['author'] ?? {};
+    const ghAuthor = c['author'] ?? {};
+    const message = String(commit['message'] ?? '').split('\n')[0] ?? '';
+    return {
+        sha: String(c['sha'] ?? ''),
+        author: String(commitAuthor['name'] ?? ghAuthor['login'] ?? 'unknown'),
+        message,
+        date: String(commitAuthor['date'] ?? ''),
+    };
+}
+/** Count how many commits landed within the last `hours`. */
+export function commitsWithin(commits, hours, now = Date.now()) {
+    const cutoff = now - hours * 3600_000;
+    return commits.filter((c) => {
+        const t = Date.parse(c.date);
+        return Number.isFinite(t) && t >= cutoff;
+    }).length;
+}
+/** Short relative-time string like "3m ago", "2h ago", "1d ago". */
+export function relativeTime(iso, now = Date.now()) {
+    const t = Date.parse(iso);
+    if (!Number.isFinite(t))
+        return 'unknown';
+    const secs = Math.max(0, Math.round((now - t) / 1000));
+    if (secs < 60)
+        return `${secs}s ago`;
+    const mins = Math.round(secs / 60);
+    if (mins < 60)
+        return `${mins}m ago`;
+    const hrs = Math.round(mins / 60);
+    if (hrs < 24)
+        return `${hrs}h ago`;
+    const days = Math.round(hrs / 24);
+    return `${days}d ago`;
+}
+/**
+ * Return the commits newer than `lastSeenSha`, newest-first. When the sha isn't
+ * present in the window (more than a page of new commits, or rewritten history)
+ * every fetched commit is treated as new. An undefined sha means "not seeded
+ * yet" — returns empty so the caller can seed without a spurious announcement.
+ */
+export function newCommitsSince(commits, lastSeenSha) {
+    if (!lastSeenSha)
+        return [];
+    const idx = commits.findIndex((c) => c.sha === lastSeenSha);
+    if (idx === 0)
+        return []; // newest is already seen
+    if (idx === -1)
+        return commits; // fell out of the window — treat all as new
+    return commits.slice(0, idx);
+}
+//# sourceMappingURL=github.js.map

package/dist/npcs/office-characters/index.d.ts

@@ -37,6 +37,10 @@ export declare class OutOfTouchExecutiveNPC extends OfficeCharacterNPC {
     get name(): 'out-of-touch-executive';
     protected get defaultDisplayName(): string;
 }
+export declare class SlightlyInappropriateHRNPC extends OfficeCharacterNPC {
+    get name(): 'slightly-inappropriate-hr';
+    protected get defaultDisplayName(): string;
+}
 export declare const OFFICE_CHARACTER_NPCS: {
     readonly janitor: typeof JanitorNPC;
     readonly barista: typeof BaristaNPC;
@@ -45,6 +49,7 @@ export declare const OFFICE_CHARACTER_NPCS: {
     readonly 'plant-caretaker': typeof PlantCaretakerNPC;
     readonly 'it-technician': typeof ITTechnicianNPC;
     readonly 'out-of-touch-executive': typeof OutOfTouchExecutiveNPC;
+    readonly 'slightly-inappropriate-hr': typeof SlightlyInappropriateHRNPC;
 };
 export {};
 //# sourceMappingURL=index.d.ts.map

package/dist/npcs/office-characters/index.js

@@ -70,6 +70,14 @@ export class OutOfTouchExecutiveNPC extends OfficeCharacterNPC {
         return 'Out-of-Touch Executive';
     }
 }
+export class SlightlyInappropriateHRNPC extends OfficeCharacterNPC {
+    get name() {
+        return 'slightly-inappropriate-hr';
+    }
+    get defaultDisplayName() {
+        return 'Slightly Inappropriate HR';
+    }
+}
 export const OFFICE_CHARACTER_NPCS = {
     janitor: JanitorNPC,
     barista: BaristaNPC,
@@ -78,5 +86,6 @@ export const OFFICE_CHARACTER_NPCS = {
     'plant-caretaker': PlantCaretakerNPC,
     'it-technician': ITTechnicianNPC,
     'out-of-touch-executive': OutOfTouchExecutiveNPC,
+    'slightly-inappropriate-hr': SlightlyInappropriateHRNPC,
 };
 //# sourceMappingURL=index.js.map

package/dist/npcs/web-page-watcher/basic.d.ts

@@ -0,0 +1,16 @@
+import type { Status } from '../../core/types.js';
+export interface BasicCheck {
+    status: number;
+    title: string;
+    ok: boolean;
+    timedOut: boolean;
+}
+/** Extract the <title> text from an HTML string (empty if none). */
+export declare function extractTitle(html: string): string;
+/** Map an HTTP status to NPC status: 2xx/3xx ok, 4xx/timeout warn, 5xx/refused crit. */
+export declare function statusFromHttp(code: number, timedOut?: boolean): Status;
+/** Fetch a page and extract HTTP status + <title> (basic, no browser). */
+export declare function basicCheck(url: string, timeoutMs?: number): Promise<BasicCheck>;
+/** Best-effort hostname for a URL, falling back to the raw string. */
+export declare function hostnameOf(url: string): string;
+//# sourceMappingURL=basic.d.ts.map

package/dist/npcs/web-page-watcher/basic.js

@@ -0,0 +1,52 @@
+/** Extract the <title> text from an HTML string (empty if none). */
+export function extractTitle(html) {
+    const m = html.match(/<title[^>]*>([\s\S]*?)<\/title>/i);
+    return m ? m[1].replace(/\s+/g, ' ').trim().slice(0, 80) : '';
+}
+/** Map an HTTP status to NPC status: 2xx/3xx ok, 4xx/timeout warn, 5xx/refused crit. */
+export function statusFromHttp(code, timedOut = false) {
+    if (code >= 200 && code < 400)
+        return 'healthy';
+    if (code >= 400 && code < 500)
+        return 'warning';
+    if (code >= 500)
+        return 'critical';
+    return timedOut ? 'warning' : 'critical'; // 0 = network error
+}
+/** Fetch a page and extract HTTP status + <title> (basic, no browser). */
+export async function basicCheck(url, timeoutMs = 8000) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        const res = await fetch(url, {
+            signal: controller.signal,
+            headers: { 'User-Agent': 'nocville-npc' },
+            redirect: 'follow',
+        });
+        let title = '';
+        try {
+            title = extractTitle(await res.text());
+        }
+        catch {
+            // body unavailable; leave title blank
+        }
+        return { status: res.status, title, ok: res.ok, timedOut: false };
+    }
+    catch (err) {
+        const timedOut = err instanceof Error && err.name === 'AbortError';
+        return { status: 0, title: '', ok: false, timedOut };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/** Best-effort hostname for a URL, falling back to the raw string. */
+export function hostnameOf(url) {
+    try {
+        return new URL(url).hostname;
+    }
+    catch {
+        return url.slice(0, 40);
+    }
+}
+//# sourceMappingURL=basic.js.map

package/dist/npcs/web-page-watcher/capture.js

@@ -1,3 +1,4 @@
+import { join } from 'node:path';
 import { existsSync } from 'node:fs';
 import { execFileSync } from 'node:child_process';
 const MAC_PATHS = [
@@ -43,6 +44,25 @@ export function findChrome(explicit) {
                 return p;
         return null;
     }
+    if (process.platform === 'win32') {
+        const roots = [
+            process.env['LOCALAPPDATA'],
+            process.env['PROGRAMFILES'],
+            process.env['PROGRAMFILES(X86)'],
+        ].filter((p) => !!p);
+        for (const root of roots)
+            for (const relative of [
+                ['Google', 'Chrome', 'Application', 'chrome.exe'],
+                ['Microsoft', 'Edge', 'Application', 'msedge.exe'],
+                ['Chromium', 'Application', 'chrome.exe'],
+                ['BraveSoftware', 'Brave-Browser', 'Application', 'brave.exe'],
+            ]) {
+                const path = join(root, ...relative);
+                if (existsSync(path))
+                    return path;
+            }
+        return null;
+    }
     if (process.platform === 'linux') {
         for (const bin of LINUX_BINARIES) {
             const resolved = which(bin);
@@ -76,6 +96,12 @@ export function runningAsRoot() {
  */
 export async function loadPuppeteer() {
     try {
+        // Prefer CommonJS in bundled runtimes so Electron resolves through its
+        // ASAR loader. Native ESM installations use the optional dynamic import below.
+        if (typeof require === 'function') {
+            const mod = require('puppeteer-core');
+            return mod.default ?? mod;
+        }
         const dynImport = new Function('m', 'return import(m)');
         const mod = await dynImport('puppeteer-core');
         return (mod.default ?? mod);

package/dist/npcs/web-page-watcher/chrome.d.ts

@@ -0,0 +1,46 @@
+export interface PuppeteerViewport {
+    width: number;
+    height: number;
+    deviceScaleFactor?: number;
+}
+export interface PuppeteerResponse {
+    status(): number;
+}
+export interface PuppeteerPage {
+    setViewport(v: PuppeteerViewport): Promise<void>;
+    goto(url: string, opts?: {
+        waitUntil?: string;
+        timeout?: number;
+    }): Promise<PuppeteerResponse | null>;
+    screenshot(opts: {
+        type?: string;
+        fullPage?: boolean;
+    }): Promise<Buffer | Uint8Array>;
+    close(): Promise<void>;
+}
+export interface PuppeteerBrowser {
+    newPage(): Promise<PuppeteerPage>;
+    close(): Promise<void>;
+    /** puppeteer >= 20 exposes `connected`; older versions expose isConnected(). */
+    connected?: boolean;
+    isConnected?(): boolean;
+    on(event: string, cb: () => void): void;
+}
+export interface PuppeteerModule {
+    launch(opts: {
+        executablePath?: string;
+        headless?: boolean | 'new';
+        args?: string[];
+    }): Promise<PuppeteerBrowser>;
+}
+/** Find a usable Chrome/Chromium executable: explicit path → env → known paths. */
+export declare function findChrome(explicit?: string): string | null;
+/**
+ * Load the optional `puppeteer-core` peer dependency without a static import,
+ * so the package builds and runs when it isn't installed. Returns null if the
+ * module is absent.
+ */
+export declare function loadPuppeteer(): Promise<PuppeteerModule | null>;
+/** True if the browser reports a live connection. */
+export declare function browserConnected(browser: PuppeteerBrowser): boolean;
+//# sourceMappingURL=chrome.d.ts.map

package/dist/npcs/web-page-watcher/chrome.js

@@ -0,0 +1,57 @@
+import { existsSync } from 'node:fs';
+const CHROME_PATHS = {
+    darwin: [
+        '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
+        '/Applications/Google Chrome Canary.app/Contents/MacOS/Google Chrome Canary',
+        '/Applications/Chromium.app/Contents/MacOS/Chromium',
+        '/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge',
+    ],
+    linux: [
+        '/usr/bin/google-chrome',
+        '/usr/bin/google-chrome-stable',
+        '/usr/bin/chromium',
+        '/usr/bin/chromium-browser',
+        '/usr/bin/microsoft-edge',
+        '/snap/bin/chromium',
+    ],
+};
+/** Find a usable Chrome/Chromium executable: explicit path → env → known paths. */
+export function findChrome(explicit) {
+    const envPath = process.env['CHROME_PATH'];
+    const candidates = [
+        ...(explicit ? [explicit] : []),
+        ...(envPath ? [envPath] : []),
+        ...(CHROME_PATHS[process.platform] ?? []),
+    ];
+    for (const p of candidates) {
+        if (p && existsSync(p))
+            return p;
+    }
+    return null;
+}
+/**
+ * Load the optional `puppeteer-core` peer dependency without a static import,
+ * so the package builds and runs when it isn't installed. Returns null if the
+ * module is absent.
+ */
+export async function loadPuppeteer() {
+    try {
+        // Indirect dynamic import so TypeScript/bundlers don't require the module
+        // at build time.
+        const dynImport = new Function('m', 'return import(m)');
+        const mod = await dynImport('puppeteer-core');
+        return (mod.default ?? mod);
+    }
+    catch {
+        return null;
+    }
+}
+/** True if the browser reports a live connection. */
+export function browserConnected(browser) {
+    if (typeof browser.connected === 'boolean')
+        return browser.connected;
+    if (typeof browser.isConnected === 'function')
+        return browser.isConnected();
+    return true;
+}
+//# sourceMappingURL=chrome.js.map