@agentrhq/webcmd 0.1.1 → 0.2.0

package/dist/src/update-check.js

@@ -0,0 +1,206 @@
+/**
+ * Non-blocking update checker.
+ *
+ * Pattern: register exit-hook + kick-off-background-fetch
+ * - On startup: kick off background fetch (non-blocking)
+ * - On process exit: read cache, print notice if newer version exists
+ * - Check interval: 24 hours
+ * - Notice appears AFTER command output, not before (same as npm/gh/yarn)
+ * - Never delays or blocks the CLI command
+ *
+ * Cache is shared between the CLI process (writes latestVersion / latestExtensionVersion
+ * via background fetch) and the daemon process (writes currentExtensionVersion /
+ * extensionLastSeenAt via `recordExtensionVersion` on each hello). Writes use a
+ * read-merge-write pattern so neither side clobbers the other.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+import { PKG_VERSION } from './version.js';
+import { EXTENSION_ARTIFACT_PREFIX, PACKAGE_NAME, PRODUCT_DISPLAY_NAME, PRODUCT_NAME } from './brand.js';
+const CACHE_DIR = path.join(os.homedir(), '.webcmd');
+const CACHE_FILE = path.join(CACHE_DIR, 'update-check.json');
+const CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000; // 24h
+const EXTENSION_STALE_MS = 7 * 24 * 60 * 60 * 1000; // 7d
+const NPM_REGISTRY_URL = 'https://invalid.example/webcmd/latest';
+const GITHUB_RELEASES_URL = 'https://invalid.example/webcmd/releases';
+const UPDATE_CHECKS_ENABLED = false;
+function readCacheSync() {
+    try {
+        return JSON.parse(fs.readFileSync(CACHE_FILE, 'utf-8'));
+    }
+    catch {
+        return null;
+    }
+}
+// Read cache once at module load — shared by both exported functions
+const _cache = readCacheSync();
+function writeCacheMerge(updates) {
+    try {
+        fs.mkdirSync(CACHE_DIR, { recursive: true });
+        const existing = readCacheSync() ?? {};
+        const merged = { ...existing, ...updates };
+        fs.writeFileSync(CACHE_FILE, JSON.stringify(merged), 'utf-8');
+    }
+    catch {
+        // Best-effort; never fail
+    }
+}
+/** Compare semver strings. Returns true if `a` is strictly newer than `b`. */
+function isNewer(a, b) {
+    const parse = (v) => v.replace(/^v/, '').split('-')[0].split('.').map(Number);
+    const pa = parse(a);
+    const pb = parse(b);
+    if (pa.some(isNaN) || pb.some(isNaN))
+        return false;
+    const [aMaj, aMin, aPat] = pa;
+    const [bMaj, bMin, bPat] = pb;
+    if (aMaj !== bMaj)
+        return aMaj > bMaj;
+    if (aMin !== bMin)
+        return aMin > bMin;
+    return aPat > bPat;
+}
+function isCI() {
+    return !!(process.env.CI || process.env.CONTINUOUS_INTEGRATION);
+}
+/** Pure function: derive notice text from cache state. Exported for tests. */
+function buildUpdateNotices({ cliVersion, cache, now }) {
+    if (!cache)
+        return {};
+    const lines = {};
+    if (cache.latestVersion && isNewer(cache.latestVersion, cliVersion)) {
+        lines.cli =
+            `\n  Update available: v${cliVersion} → v${cache.latestVersion}\n` +
+                `  Run: npm install -g ${PACKAGE_NAME}\n`;
+    }
+    const { currentExtensionVersion, latestExtensionVersion, extensionLastSeenAt } = cache;
+    if (currentExtensionVersion &&
+        latestExtensionVersion &&
+        extensionLastSeenAt &&
+        now - extensionLastSeenAt < EXTENSION_STALE_MS &&
+        isNewer(latestExtensionVersion, currentExtensionVersion)) {
+        lines.extension =
+            `\n  Runtime update available: v${currentExtensionVersion} → v${latestExtensionVersion}\n` +
+                `  Update the ${PRODUCT_DISPLAY_NAME} Cloak runtime from AgentR release artifacts.\n`;
+    }
+    return lines;
+}
+/**
+ * Register a process exit hook that prints an update notice if a newer
+ * version was found on the last background check.
+ * Notice appears after command output — same pattern as npm/gh/yarn.
+ * Skipped during --get-completions to avoid polluting shell completion output.
+ */
+export function registerUpdateNoticeOnExit() {
+    if (isCI())
+        return;
+    if (process.argv.includes('--get-completions'))
+        return;
+    process.on('exit', (code) => {
+        if (code !== 0)
+            return; // Don't show update notice on error exit
+        const { cli, extension } = buildUpdateNotices({
+            cliVersion: PKG_VERSION,
+            cache: _cache,
+            now: Date.now(),
+        });
+        if (!cli && !extension)
+            return;
+        try {
+            process.stderr.write(`${cli ?? ''}${extension ?? ''}\n`);
+        }
+        catch {
+            // Ignore broken pipe (stderr closed before process exits)
+        }
+    });
+}
+function extractLatestExtensionVersionFromReleases(releases) {
+    for (const release of releases) {
+        for (const asset of release.assets ?? []) {
+            const assetMatch = asset.name.match(new RegExp(`^${EXTENSION_ARTIFACT_PREFIX}-v(.+)\\.zip$`));
+            if (assetMatch)
+                return assetMatch[1];
+        }
+        const tagMatch = release.tag_name.match(/^ext-v(.+)$/);
+        if (tagMatch)
+            return tagMatch[1];
+    }
+    return undefined;
+}
+/** Fetch the latest extension version from GitHub Releases. */
+async function fetchLatestExtensionVersion() {
+    try {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), 3000);
+        const res = await fetch(GITHUB_RELEASES_URL, {
+            signal: controller.signal,
+            headers: { 'User-Agent': `${PRODUCT_NAME}/${PKG_VERSION}`, Accept: 'application/vnd.github+json' },
+        });
+        clearTimeout(timer);
+        if (!res.ok)
+            return undefined;
+        const releases = await res.json();
+        return extractLatestExtensionVersionFromReleases(releases);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Kick off a background fetch to npm registry. Writes to cache for next run.
+ * Fully non-blocking — never awaited.
+ */
+export function checkForUpdateBackground() {
+    if (!UPDATE_CHECKS_ENABLED)
+        return;
+    if (isCI())
+        return;
+    if (_cache?.lastCheck && Date.now() - _cache.lastCheck < CHECK_INTERVAL_MS)
+        return;
+    void (async () => {
+        try {
+            const controller = new AbortController();
+            const timer = setTimeout(() => controller.abort(), 3000);
+            const res = await fetch(NPM_REGISTRY_URL, {
+                signal: controller.signal,
+                headers: { 'User-Agent': `${PRODUCT_NAME}/${PKG_VERSION}` },
+            });
+            clearTimeout(timer);
+            if (!res.ok)
+                return;
+            const data = await res.json();
+            if (typeof data.version === 'string') {
+                const extVersion = await fetchLatestExtensionVersion();
+                const updates = { lastCheck: Date.now(), latestVersion: data.version };
+                if (extVersion)
+                    updates.latestExtensionVersion = extVersion;
+                writeCacheMerge(updates);
+            }
+        }
+        catch {
+            // Network error: silently skip, try again next run
+        }
+    })();
+}
+/**
+ * Stash the current extension version into the shared cache. Called by the
+ * daemon on each hello handshake. Lets the next CLI process compare against
+ * the latest known release and print an exit notice without any extra I/O.
+ */
+export function recordExtensionVersion(version) {
+    if (typeof version !== 'string' || !version.trim())
+        return;
+    writeCacheMerge({
+        currentExtensionVersion: version.trim(),
+        extensionLastSeenAt: Date.now(),
+    });
+}
+/**
+ * Get the cached latest extension version (if available).
+ * Used by `webcmd doctor` to report extension updates.
+ */
+export function getCachedLatestExtensionVersion() {
+    return _cache?.latestExtensionVersion;
+}
+export { extractLatestExtensionVersionFromReleases as _extractLatestExtensionVersionFromReleases, buildUpdateNotices as _buildUpdateNotices, EXTENSION_STALE_MS as _EXTENSION_STALE_MS, };

package/dist/src/update-check.test.d.ts

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

package/dist/src/update-check.test.js

@@ -0,0 +1,117 @@
+import { describe, expect, it } from 'vitest';
+import { _extractLatestExtensionVersionFromReleases as extractLatestExtensionVersionFromReleases, _buildUpdateNotices as buildUpdateNotices, _EXTENSION_STALE_MS as EXTENSION_STALE_MS, } from './update-check.js';
+describe('extractLatestExtensionVersionFromReleases', () => {
+    it('reads the extension version from a versioned asset on a normal CLI release', () => {
+        expect(extractLatestExtensionVersionFromReleases([
+            {
+                tag_name: 'v1.7.3',
+                assets: [
+                    { name: 'webcmd-extension.zip' },
+                    { name: 'webcmd-extension-v1.0.2.zip' },
+                ],
+            },
+        ])).toBe('1.0.2');
+    });
+    it('falls back to ext-v tags for extension-only releases', () => {
+        expect(extractLatestExtensionVersionFromReleases([
+            {
+                tag_name: 'ext-v1.1.0',
+                assets: [{ name: 'webcmd-extension.zip' }],
+            },
+        ])).toBe('1.1.0');
+    });
+    it('returns undefined when no extension version source exists', () => {
+        expect(extractLatestExtensionVersionFromReleases([
+            {
+                tag_name: 'v1.7.3',
+                assets: [{ name: 'webcmd-extension.zip' }],
+            },
+        ])).toBeUndefined();
+    });
+});
+describe('buildUpdateNotices', () => {
+    const now = 1_700_000_000_000;
+    it('returns nothing when cache is empty', () => {
+        expect(buildUpdateNotices({ cliVersion: '1.0.0', cache: null, now })).toEqual({});
+    });
+    it('emits a CLI notice when registry version is newer', () => {
+        const lines = buildUpdateNotices({
+            cliVersion: '1.0.0',
+            cache: { lastCheck: now, latestVersion: '1.0.1' },
+            now,
+        });
+        expect(lines.cli).toContain('v1.0.0 → v1.0.1');
+        expect(lines.extension).toBeUndefined();
+    });
+    it('emits a runtime notice when current runtime is older and cache is fresh', () => {
+        const lines = buildUpdateNotices({
+            cliVersion: '1.0.0',
+            cache: {
+                lastCheck: now,
+                latestVersion: '1.0.0',
+                latestExtensionVersion: '2.1.0',
+                currentExtensionVersion: '2.0.0',
+                extensionLastSeenAt: now - 60_000,
+            },
+            now,
+        });
+        expect(lines.cli).toBeUndefined();
+        expect(lines.extension).toContain('Runtime update available');
+        expect(lines.extension).toContain('v2.0.0 → v2.1.0');
+    });
+    it('skips the runtime notice when lastSeenAt is older than the stale window', () => {
+        const lines = buildUpdateNotices({
+            cliVersion: '1.0.0',
+            cache: {
+                lastCheck: now,
+                latestVersion: '1.0.0',
+                latestExtensionVersion: '2.1.0',
+                currentExtensionVersion: '2.0.0',
+                extensionLastSeenAt: now - EXTENSION_STALE_MS - 1,
+            },
+            now,
+        });
+        expect(lines.extension).toBeUndefined();
+    });
+    it('skips the extension notice when current and latest are equal', () => {
+        const lines = buildUpdateNotices({
+            cliVersion: '1.0.0',
+            cache: {
+                lastCheck: now,
+                latestVersion: '1.0.0',
+                latestExtensionVersion: '2.0.0',
+                currentExtensionVersion: '2.0.0',
+                extensionLastSeenAt: now,
+            },
+            now,
+        });
+        expect(lines.extension).toBeUndefined();
+    });
+    it('does not throw when cache has only daemon-written fields and no latestVersion', () => {
+        const lines = buildUpdateNotices({
+            cliVersion: '1.0.0',
+            cache: {
+                currentExtensionVersion: '2.0.0',
+                extensionLastSeenAt: now,
+            },
+            now,
+        });
+        expect(lines.cli).toBeUndefined();
+        expect(lines.extension).toBeUndefined();
+    });
+    it('emits both notices when both are out of date', () => {
+        const lines = buildUpdateNotices({
+            cliVersion: '1.0.0',
+            cache: {
+                lastCheck: now,
+                latestVersion: '1.1.0',
+                latestExtensionVersion: '2.1.0',
+                currentExtensionVersion: '2.0.0',
+                extensionLastSeenAt: now,
+            },
+            now,
+        });
+        expect(lines.cli).toContain('v1.0.0 → v1.1.0');
+        expect(lines.extension).toContain('v2.0.0 → v2.1.0');
+    });
+});

package/dist/src/utils.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Shared utility functions used across the codebase.
+ */
+import TurndownService from 'turndown';
+/** Type guard: checks if a value is a non-null, non-array object. */
+export declare function isRecord(value: unknown): value is Record<string, unknown>;
+/** Simple async concurrency limiter. */
+export declare function mapConcurrent<T, R>(items: T[], limit: number, fn: (item: T, index: number) => Promise<R>): Promise<R[]>;
+/** Pause for the given number of milliseconds. */
+export declare function sleep(ms: number): Promise<void>;
+/** Save a base64-encoded string to a file, creating parent directories as needed. */
+export declare function saveBase64ToFile(base64: string, filePath: string): Promise<void>;
+export declare function createMarkdownConverter(configure?: (td: TurndownService) => void): TurndownService;
+export declare function htmlToMarkdown(value: string, configure?: (td: TurndownService) => void): string;
+/** Sentinel shape that browser-side `fetch` wrappers return when they detect an
+ * HTML response in place of JSON. Kept as a plain object so it survives the
+ * `page.evaluate` JSON round-trip. */
+export interface LoginWallSignal {
+    __loginWall: true;
+    status: number;
+    url: string;
+    contentType: string;
+    bodyPreview: string;
+}
+/** Throw a `LoginWallError` if `value` is the sentinel returned by the
+ * browser-side sniffer; otherwise return `value` unchanged. Adapters that
+ * fetch from inside `page.evaluate` call this on the result before consuming
+ * it, so the Node-side gets a typed error instead of a JSON-parse stack
+ * trace. */
+export declare function throwIfLoginWall<T>(value: T, opts?: {
+    url?: string;
+}): T;
+/** Parse a `Response` body as JSON, throwing `LoginWallError` if the server
+ * returned an HTML page (login wall / rate limit / WAF interception) instead
+ * of the expected JSON. Catches the common case of `<!DOCTYPE` or `<html`
+ * leading the body \u2014 naive `JSON.parse` on these gives a cryptic
+ * `SyntaxError` that callers can't distinguish from "real" malformed JSON.
+ *
+ * On real (non-HTML) JSON-parse failures, throws a regular `Error` with a
+ * body preview attached so debugging doesn't require a packet capture. */
+export declare function parseJsonOrThrowLoginWall(response: Response, opts?: {
+    url?: string;
+}): Promise<unknown>;
+/** Browser-side JS source fragment (as a string) that performs a `fetch` and
+ * either returns the parsed JSON body or a `LoginWallSignal` sentinel when
+ * the response is HTML. Intended to be embedded inside an adapter's
+ * `page.evaluate` block.
+ *
+ * Usage from inside a `page.evaluate` IIFE:
+ *
+ *     ${BROWSER_JSON_SNIFF_FN}
+ *     const res = await fetchJsonOrLoginWall('/some/path.json', { credentials: 'include' });
+ *     // res is the parsed JSON object, OR { __loginWall: true, status, url, contentType, bodyPreview }
+ *     return res;
+ *
+ * The Node side then calls `throwIfLoginWall(res, { url })` on the result. */
+export declare const BROWSER_JSON_SNIFF_FN = "\nasync function fetchJsonOrLoginWall(input, init) {\n  const r = await fetch(input, init);\n  const contentType = r.headers.get('content-type') || '';\n  const text = await r.text();\n  const trimmed = text.replace(/^\\s+/, '');\n  const looksLikeHtml =\n    contentType.toLowerCase().includes('text/html')\n    || trimmed.startsWith('<!DOCTYPE')\n    || trimmed.startsWith('<!doctype')\n    || trimmed.startsWith('<html')\n    || trimmed.startsWith('<HTML');\n  if (looksLikeHtml) {\n    return {\n      __loginWall: true,\n      status: r.status,\n      url: r.url || (typeof input === 'string' ? input : ''),\n      contentType,\n      bodyPreview: trimmed.slice(0, 100),\n    };\n  }\n  if (!r.ok) {\n    return { error: r.status };\n  }\n  try {\n    return JSON.parse(text);\n  } catch (err) {\n    throw new Error(\n      'JSON parse failed (status=' + r.status + ', body[0..50]=' + JSON.stringify(trimmed.slice(0, 50)) + '): '\n      + (err && err.message ? err.message : String(err))\n    );\n  }\n}\n";

package/dist/src/utils.js

@@ -0,0 +1,152 @@
+/**
+ * Shared utility functions used across the codebase.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import TurndownService from 'turndown';
+import { LoginWallError } from './errors.js';
+/** Type guard: checks if a value is a non-null, non-array object. */
+export function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/** Simple async concurrency limiter. */
+export async function mapConcurrent(items, limit, fn) {
+    const results = new Array(items.length);
+    let index = 0;
+    async function worker() {
+        while (index < items.length) {
+            const i = index++;
+            results[i] = await fn(items[i], i);
+        }
+    }
+    const workers = Array.from({ length: Math.min(limit, items.length) }, () => worker());
+    await Promise.all(workers);
+    return results;
+}
+/** Pause for the given number of milliseconds. */
+export function sleep(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+}
+/** Save a base64-encoded string to a file, creating parent directories as needed. */
+export async function saveBase64ToFile(base64, filePath) {
+    const dir = path.dirname(filePath);
+    await fs.promises.mkdir(dir, { recursive: true });
+    await fs.promises.writeFile(filePath, Buffer.from(base64, 'base64'));
+}
+export function createMarkdownConverter(configure) {
+    const td = new TurndownService({
+        headingStyle: 'atx',
+        codeBlockStyle: 'fenced',
+        bulletListMarker: '-',
+    });
+    td.addRule('linebreak', {
+        filter: 'br',
+        replacement: () => '\n',
+    });
+    if (configure)
+        configure(td);
+    return td;
+}
+export function htmlToMarkdown(value, configure) {
+    return createMarkdownConverter(configure).turndown(value || '')
+        .replace(/\u00a0/g, ' ')
+        .replace(/\n{4,}/g, '\n\n\n')
+        .replace(/[ \t]+$/gm, '')
+        .trim();
+}
+function isLoginWallSignal(v) {
+    return (typeof v === 'object'
+        && v !== null
+        && v.__loginWall === true
+        && typeof v.status === 'number');
+}
+/** Throw a `LoginWallError` if `value` is the sentinel returned by the
+ * browser-side sniffer; otherwise return `value` unchanged. Adapters that
+ * fetch from inside `page.evaluate` call this on the result before consuming
+ * it, so the Node-side gets a typed error instead of a JSON-parse stack
+ * trace. */
+export function throwIfLoginWall(value, opts = {}) {
+    if (isLoginWallSignal(value)) {
+        throw new LoginWallError(`Server returned HTML instead of JSON (status=${value.status}). `
+            + `Likely a login wall, rate limit, or WAF challenge.`, value.status, opts.url || value.url || '', value.bodyPreview);
+    }
+    return value;
+}
+/** Parse a `Response` body as JSON, throwing `LoginWallError` if the server
+ * returned an HTML page (login wall / rate limit / WAF interception) instead
+ * of the expected JSON. Catches the common case of `<!DOCTYPE` or `<html`
+ * leading the body \u2014 naive `JSON.parse` on these gives a cryptic
+ * `SyntaxError` that callers can't distinguish from "real" malformed JSON.
+ *
+ * On real (non-HTML) JSON-parse failures, throws a regular `Error` with a
+ * body preview attached so debugging doesn't require a packet capture. */
+export async function parseJsonOrThrowLoginWall(response, opts = {}) {
+    const contentType = response.headers.get('content-type') || '';
+    const text = await response.text();
+    const trimmed = text.trimStart();
+    const looksLikeHtml = contentType.toLowerCase().includes('text/html')
+        || trimmed.startsWith('<!DOCTYPE')
+        || trimmed.startsWith('<!doctype')
+        || trimmed.startsWith('<html')
+        || trimmed.startsWith('<HTML');
+    if (looksLikeHtml) {
+        throw new LoginWallError(`Server returned HTML instead of JSON (status=${response.status}). `
+            + `Likely a login wall, rate limit, or WAF challenge.`, response.status, opts.url || response.url || '', trimmed.slice(0, 100));
+    }
+    try {
+        return JSON.parse(text);
+    }
+    catch (err) {
+        // Real malformed JSON \u2014 surface body preview alongside the parser message
+        // so we don't have to repro to know what came back.
+        throw new Error(`JSON parse failed (status=${response.status}, body[0..50]=${JSON.stringify(trimmed.slice(0, 50))}): `
+            + (err instanceof Error ? err.message : String(err)));
+    }
+}
+/** Browser-side JS source fragment (as a string) that performs a `fetch` and
+ * either returns the parsed JSON body or a `LoginWallSignal` sentinel when
+ * the response is HTML. Intended to be embedded inside an adapter's
+ * `page.evaluate` block.
+ *
+ * Usage from inside a `page.evaluate` IIFE:
+ *
+ *     ${BROWSER_JSON_SNIFF_FN}
+ *     const res = await fetchJsonOrLoginWall('/some/path.json', { credentials: 'include' });
+ *     // res is the parsed JSON object, OR { __loginWall: true, status, url, contentType, bodyPreview }
+ *     return res;
+ *
+ * The Node side then calls `throwIfLoginWall(res, { url })` on the result. */
+export const BROWSER_JSON_SNIFF_FN = `
+async function fetchJsonOrLoginWall(input, init) {
+  const r = await fetch(input, init);
+  const contentType = r.headers.get('content-type') || '';
+  const text = await r.text();
+  const trimmed = text.replace(/^\\s+/, '');
+  const looksLikeHtml =
+    contentType.toLowerCase().includes('text/html')
+    || trimmed.startsWith('<!DOCTYPE')
+    || trimmed.startsWith('<!doctype')
+    || trimmed.startsWith('<html')
+    || trimmed.startsWith('<HTML');
+  if (looksLikeHtml) {
+    return {
+      __loginWall: true,
+      status: r.status,
+      url: r.url || (typeof input === 'string' ? input : ''),
+      contentType,
+      bodyPreview: trimmed.slice(0, 100),
+    };
+  }
+  if (!r.ok) {
+    return { error: r.status };
+  }
+  try {
+    return JSON.parse(text);
+  } catch (err) {
+    throw new Error(
+      'JSON parse failed (status=' + r.status + ', body[0..50]=' + JSON.stringify(trimmed.slice(0, 50)) + '): '
+      + (err && err.message ? err.message : String(err))
+    );
+  }
+}
+`;

package/dist/src/utils.test.d.ts

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