@jackwener/opencli 1.7.8 → 1.7.10

package/dist/src/browser/daemon-client.d.ts

@@ -6,7 +6,7 @@
 import type { BrowserSessionInfo } from '../types.js';
 export interface DaemonCommand {
     id: string;
-    action: 'exec' | 'navigate' | 'tabs' | 'cookies' | 'screenshot' | 'close-window' | 'sessions' | 'set-file-input' | 'insert-text' | 'bind-current' | 'network-capture-start' | 'network-capture-read' | 'cdp' | 'frames';
+    action: 'exec' | 'navigate' | 'tabs' | 'cookies' | 'screenshot' | 'close-window' | 'sessions' | 'set-file-input' | 'insert-text' | 'bind' | 'network-capture-start' | 'network-capture-read' | 'cdp' | 'frames';
     /** Target page identity (targetId). Cross-layer contract with the extension. */
     page?: string;
     code?: string;
@@ -30,21 +30,32 @@ export interface DaemonCommand {
     pattern?: string;
     cdpMethod?: string;
     cdpParams?: Record<string, unknown>;
-    /** When true, automation windows are created in the foreground */
+    /** When true, the owned automation container is created in the foreground */
     windowFocused?: boolean;
     /** Custom idle timeout in seconds for this workspace session. Overrides the default. */
     idleTimeout?: number;
+    /** Explicitly allow navigation inside a borrowed bound tab. */
+    allowBoundNavigation?: boolean;
     /** Frame index for cross-frame operations (0-based, from 'frames' action) */
     frameIndex?: number;
+    /** Browser profile/context to route the command to. */
+    contextId?: string;
 }
 export interface DaemonResult {
     id: string;
     ok: boolean;
     data?: unknown;
     error?: string;
+    errorCode?: string;
+    errorHint?: string;
     /** Page identity (targetId) — present on page-scoped command responses */
     page?: string;
 }
+export declare class BrowserCommandError extends Error {
+    readonly code?: string | undefined;
+    readonly hint?: string | undefined;
+    constructor(message: string, code?: string | undefined, hint?: string | undefined);
+}
 export interface DaemonStatus {
     ok: boolean;
     pid: number;
@@ -53,12 +64,25 @@ export interface DaemonStatus {
     extensionConnected: boolean;
     extensionVersion?: string;
     extensionCompatRange?: string;
+    contextId?: string;
+    profileRequired?: boolean;
+    profileDisconnected?: boolean;
+    profiles?: BrowserProfileStatus[];
     pending: number;
     memoryMB: number;
     port: number;
 }
+export interface BrowserProfileStatus {
+    contextId: string;
+    extensionConnected: boolean;
+    extensionVersion?: string;
+    extensionCompatRange?: string;
+    pending: number;
+    lastSeenAt?: number;
+}
 export declare function fetchDaemonStatus(opts?: {
     timeout?: number;
+    contextId?: string;
 }): Promise<DaemonStatus | null>;
 export type DaemonHealth = {
     state: 'stopped';
@@ -66,6 +90,12 @@ export type DaemonHealth = {
 } | {
     state: 'no-extension';
     status: DaemonStatus;
+} | {
+    state: 'profile-required';
+    status: DaemonStatus;
+} | {
+    state: 'profile-disconnected';
+    status: DaemonStatus;
 } | {
     state: 'ready';
     status: DaemonStatus;
@@ -76,6 +106,7 @@ export type DaemonHealth = {
  */
 export declare function getDaemonHealth(opts?: {
     timeout?: number;
+    contextId?: string;
 }): Promise<DaemonHealth>;
 export declare function requestDaemonShutdown(opts?: {
     timeout?: number;
@@ -92,8 +123,11 @@ export declare function sendCommandFull(action: DaemonCommand['action'], params?
     data: unknown;
     page?: string;
 }>;
-export declare function listSessions(): Promise<BrowserSessionInfo[]>;
-export declare function bindCurrentTab(workspace: string, opts?: {
+export declare function listSessions(opts?: {
+    contextId?: string;
+}): Promise<BrowserSessionInfo[]>;
+export declare function bindTab(workspace: string, opts?: {
     matchDomain?: string;
     matchPathPrefix?: string;
+    contextId?: string;
 }): Promise<unknown>;

package/dist/src/browser/daemon-client.js

@@ -6,6 +6,7 @@
 import { DEFAULT_DAEMON_PORT } from '../constants.js';
 import { sleep } from '../utils.js';
 import { classifyBrowserError } from './errors.js';
+import { resolveProfileContextId } from './profile.js';
 const DAEMON_PORT = parseInt(process.env.OPENCLI_DAEMON_PORT ?? String(DEFAULT_DAEMON_PORT), 10);
 const DAEMON_URL = `http://127.0.0.1:${DAEMON_PORT}`;
 const OPENCLI_HEADERS = { 'X-OpenCLI': '1' };
@@ -13,6 +14,16 @@ let _idCounter = 0;
 function generateId() {
     return `cmd_${process.pid}_${Date.now()}_${++_idCounter}`;
 }
+export class BrowserCommandError extends Error {
+    code;
+    hint;
+    constructor(message, code, hint) {
+        super(message);
+        this.code = code;
+        this.hint = hint;
+        this.name = 'BrowserCommandError';
+    }
+}
 async function requestDaemon(pathname, init) {
     const { timeout = 2000, headers, ...rest } = init ?? {};
     const controller = new AbortController();
@@ -30,7 +41,8 @@ async function requestDaemon(pathname, init) {
 }
 export async function fetchDaemonStatus(opts) {
     try {
-        const res = await requestDaemon('/status', { timeout: opts?.timeout ?? 2000 });
+        const params = opts?.contextId ? `?contextId=${encodeURIComponent(opts.contextId)}` : '';
+        const res = await requestDaemon(`/status${params}`, { timeout: opts?.timeout ?? 2000 });
         if (!res.ok)
             return null;
         return await res.json();
@@ -47,6 +59,10 @@ export async function getDaemonHealth(opts) {
     const status = await fetchDaemonStatus(opts);
     if (!status)
         return { state: 'stopped', status: null };
+    if (status.profileRequired)
+        return { state: 'profile-required', status };
+    if (status.profileDisconnected)
+        return { state: 'profile-disconnected', status };
     if (!status.extensionConnected)
         return { state: 'no-extension', status };
     return { state: 'ready', status };
@@ -75,7 +91,8 @@ async function sendCommandRaw(action, params) {
         const id = generateId();
         const wf = process.env.OPENCLI_WINDOW_FOCUSED;
         const windowFocused = (wf === '1' || wf === 'true') ? true : undefined;
-        const command = { id, action, ...params, ...(windowFocused && { windowFocused }) };
+        const contextId = params.contextId ?? resolveProfileContextId();
+        const command = { id, action, ...params, ...(contextId && { contextId }), ...(windowFocused && { windowFocused }) };
         try {
             const res = await requestDaemon('/command', {
                 method: 'POST',
@@ -95,7 +112,7 @@ async function sendCommandRaw(action, params) {
                     await sleep(advice.delayMs);
                     continue;
                 }
-                throw new Error(result.error ?? 'Daemon command failed');
+                throw new BrowserCommandError(result.error ?? 'Daemon command failed', result.errorCode, result.errorHint);
             }
             return result;
         }
@@ -126,10 +143,10 @@ export async function sendCommandFull(action, params = {}) {
     const result = await sendCommandRaw(action, params);
     return { data: result.data, page: result.page };
 }
-export async function listSessions() {
-    const result = await sendCommand('sessions');
+export async function listSessions(opts) {
+    const result = await sendCommand('sessions', { ...(opts?.contextId && { contextId: opts.contextId }) });
     return Array.isArray(result) ? result : [];
 }
-export async function bindCurrentTab(workspace, opts = {}) {
-    return sendCommand('bind-current', { workspace, ...opts });
+export async function bindTab(workspace, opts = {}) {
+    return sendCommand('bind', { workspace, ...opts });
 }

package/dist/src/browser/daemon-client.test.js

@@ -6,6 +6,7 @@ describe('daemon-client', () => {
     });
     afterEach(() => {
         vi.restoreAllMocks();
+        vi.unstubAllEnvs();
     });
     it('fetchDaemonStatus sends the shared status request and returns parsed data', async () => {
         const status = {
@@ -78,6 +79,43 @@ describe('daemon-client', () => {
         });
         await expect(getDaemonHealth()).resolves.toEqual({ state: 'ready', status });
     });
+    it('getDaemonHealth returns profile-required when multiple profiles are connected without a selection', async () => {
+        const status = {
+            ok: true,
+            pid: 123,
+            uptime: 10,
+            extensionConnected: false,
+            profileRequired: true,
+            profiles: [
+                { contextId: 'work', extensionConnected: true, pending: 0 },
+                { contextId: 'personal', extensionConnected: true, pending: 0 },
+            ],
+            pending: 0,
+            memoryMB: 32,
+            port: 19825,
+        };
+        vi.mocked(fetch).mockResolvedValue({
+            ok: true,
+            json: () => Promise.resolve(status),
+        });
+        await expect(getDaemonHealth()).resolves.toEqual({ state: 'profile-required', status });
+    });
+    it('fetchDaemonStatus includes contextId in the status query', async () => {
+        vi.mocked(fetch).mockResolvedValue({
+            ok: true,
+            json: () => Promise.resolve({
+                ok: true,
+                pid: 1,
+                uptime: 0,
+                extensionConnected: true,
+                pending: 0,
+                memoryMB: 1,
+                port: 19825,
+            }),
+        });
+        await fetchDaemonStatus({ contextId: 'work' });
+        expect(vi.mocked(fetch).mock.calls[0][0]).toMatch(/\/status\?contextId=work$/);
+    });
     it('sendCommand includes the current pid in generated command ids', async () => {
         vi.spyOn(Date, 'now').mockReturnValue(1_763_000_000_000);
         vi.mocked(fetch).mockResolvedValue({
@@ -95,6 +133,17 @@ describe('daemon-client', () => {
         expect(ids[1]).toMatch(new RegExp(`^cmd_${process.pid}_1763000000000_\\d+$`));
         expect(ids[0]).not.toBe(ids[1]);
     });
+    it('sendCommand forwards OPENCLI_PROFILE as command contextId', async () => {
+        vi.stubEnv('OPENCLI_PROFILE', 'work');
+        vi.spyOn(Date, 'now').mockReturnValue(1_763_000_000_000);
+        vi.mocked(fetch).mockResolvedValue({
+            status: 200,
+            json: () => Promise.resolve({ id: 'server', ok: true, data: 'ok' }),
+        });
+        await sendCommand('exec', { code: '1 + 1' });
+        const body = JSON.parse(String(vi.mocked(fetch).mock.calls[0][1]?.body));
+        expect(body.contextId).toBe('work');
+    });
     it('sendCommand retries with a new id when daemon reports a duplicate pending id', async () => {
         vi.spyOn(Date, 'now').mockReturnValue(1_763_000_000_123);
         const fetchMock = vi.mocked(fetch);

package/dist/src/browser/daemon-lifecycle.d.ts

@@ -0,0 +1,23 @@
+import { type ChildProcess } from 'node:child_process';
+import { DEFAULT_DAEMON_PORT } from '../constants.js';
+import { type DaemonStatus } from './daemon-client.js';
+export interface DaemonLaunchSpec {
+    binary: string;
+    args: string[];
+    scriptPath: string;
+}
+export interface DaemonRestartResult {
+    previousStatus: DaemonStatus | null;
+    status: DaemonStatus | null;
+    stopped: boolean;
+    spawned: boolean;
+}
+export declare function resolveDaemonLaunchSpec(): DaemonLaunchSpec;
+export declare function spawnDaemonProcess(): ChildProcess;
+export declare function waitForDaemonStop(timeoutMs: number): Promise<boolean>;
+export declare function waitForDaemonStatus(timeoutMs: number): Promise<DaemonStatus | null>;
+export declare function restartDaemon(opts?: {
+    stopTimeoutMs?: number;
+    startTimeoutMs?: number;
+}): Promise<DaemonRestartResult>;
+export { DEFAULT_DAEMON_PORT };

package/dist/src/browser/daemon-lifecycle.js

@@ -0,0 +1,67 @@
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { DEFAULT_DAEMON_PORT } from '../constants.js';
+import { fetchDaemonStatus, getDaemonHealth, requestDaemonShutdown } from './daemon-client.js';
+export function resolveDaemonLaunchSpec() {
+    const __dirname = path.dirname(fileURLToPath(import.meta.url));
+    const parentDir = path.resolve(__dirname, '..');
+    const daemonTs = path.join(parentDir, 'daemon.ts');
+    const daemonJs = path.join(parentDir, 'daemon.js');
+    const isTs = fs.existsSync(daemonTs);
+    const scriptPath = isTs ? daemonTs : daemonJs;
+    return {
+        binary: process.execPath,
+        args: isTs ? ['--import', 'tsx/esm', scriptPath] : [scriptPath],
+        scriptPath,
+    };
+}
+export function spawnDaemonProcess() {
+    const launch = resolveDaemonLaunchSpec();
+    const proc = spawn(launch.binary, launch.args, {
+        detached: true,
+        stdio: 'ignore',
+        env: { ...process.env },
+    });
+    proc.unref();
+    return proc;
+}
+export async function waitForDaemonStop(timeoutMs) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        await sleep(200);
+        const h = await getDaemonHealth();
+        if (h.state === 'stopped')
+            return true;
+    }
+    return false;
+}
+export async function waitForDaemonStatus(timeoutMs) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        const status = await fetchDaemonStatus({ timeout: Math.min(1000, Math.max(100, deadline - Date.now())) });
+        if (status)
+            return status;
+        await sleep(200);
+    }
+    return null;
+}
+export async function restartDaemon(opts = {}) {
+    const previousStatus = await fetchDaemonStatus();
+    let stopped = previousStatus === null;
+    if (previousStatus) {
+        const shutdownAccepted = await requestDaemonShutdown();
+        stopped = shutdownAccepted && await waitForDaemonStop(opts.stopTimeoutMs ?? 3000);
+        if (!stopped) {
+            return { previousStatus, status: previousStatus, stopped: false, spawned: false };
+        }
+    }
+    spawnDaemonProcess();
+    const status = await waitForDaemonStatus(opts.startTimeoutMs ?? 5000);
+    return { previousStatus, status, stopped, spawned: true };
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+export { DEFAULT_DAEMON_PORT };

package/dist/src/browser/daemon-version.d.ts

@@ -0,0 +1,4 @@
+import type { DaemonStatus } from './daemon-client.js';
+export declare function isDaemonStale(status: Pick<DaemonStatus, 'daemonVersion'> | null | undefined, cliVersion?: string): boolean;
+export declare function formatDaemonVersion(status: Pick<DaemonStatus, 'daemonVersion'> | null | undefined): string;
+export declare function staleDaemonIssue(status: Pick<DaemonStatus, 'daemonVersion'> | null | undefined, cliVersion: string): string;

package/dist/src/browser/daemon-version.js

@@ -0,0 +1,12 @@
+export function isDaemonStale(status, cliVersion) {
+    if (!status || !cliVersion)
+        return false;
+    return !status.daemonVersion || status.daemonVersion !== cliVersion;
+}
+export function formatDaemonVersion(status) {
+    return status?.daemonVersion ? `v${status.daemonVersion}` : 'version unknown';
+}
+export function staleDaemonIssue(status, cliVersion) {
+    return `Stale daemon detected: daemon ${formatDaemonVersion(status)} != CLI v${cliVersion}.\n` +
+        '  Run: opencli daemon restart';
+}

package/dist/src/browser/errors.js

@@ -15,7 +15,10 @@ const EXTENSION_TRANSIENT_PATTERNS = [
     'Extension disconnected',
     'Extension not connected',
     'attach failed',
+    'Detached while handling command',
+    'Debugger is not attached to the tab',
     'no longer exists',
+    'No tab with id',
     'CDP connection',
     'Daemon command failed',
     'No window with id',

package/dist/src/browser/errors.test.js

@@ -6,7 +6,10 @@ describe('classifyBrowserError', () => {
             'Extension disconnected',
             'Extension not connected',
             'attach failed',
+            'Detached while handling command',
+            'Debugger is not attached to the tab: 123',
             'no longer exists',
+            'No tab with id: 456',
             'CDP connection reset',
             'Daemon command failed',
             'No window with id: 123',

package/dist/src/browser/network-cache.d.ts

@@ -25,6 +25,7 @@ export interface CachedNetworkEntry {
      */
     body_truncated?: boolean;
     body_full_size?: number;
+    timestamp?: number;
 }
 export interface NetworkCacheFile {
     version: 1;

package/dist/src/browser/page.d.ts

@@ -15,8 +15,9 @@ import { BasePage } from './base-page.js';
  */
 export declare class Page extends BasePage {
     private readonly workspace;
+    readonly contextId?: string | undefined;
     private readonly _idleTimeout;
-    constructor(workspace?: string, idleTimeout?: number);
+    constructor(workspace?: string, idleTimeout?: number, contextId?: string | undefined);
     /** Active page identity (targetId), set after navigate and used in all subsequent commands */
     private _page;
     private _networkCaptureUnsupported;
@@ -28,6 +29,7 @@ export declare class Page extends BasePage {
     goto(url: string, options?: {
         waitUntil?: 'load' | 'none';
         settleMs?: number;
+        allowBoundNavigation?: boolean;
     }): Promise<void>;
     /** Get the active page identity (targetId) */
     getActivePage(): string | undefined;

package/dist/src/browser/page.js

@@ -27,10 +27,12 @@ function isUnsupportedNetworkCaptureError(err) {
  */
 export class Page extends BasePage {
     workspace;
+    contextId;
     _idleTimeout;
-    constructor(workspace = 'default', idleTimeout) {
+    constructor(workspace = 'default', idleTimeout, contextId) {
         super();
         this.workspace = workspace;
+        this.contextId = contextId;
         this._idleTimeout = idleTimeout;
     }
     /** Active page identity (targetId), set after navigate and used in all subsequent commands */
@@ -39,12 +41,17 @@ export class Page extends BasePage {
     _networkCaptureWarned = false;
     /** Helper: spread workspace into command params */
     _wsOpt() {
-        return { workspace: this.workspace, ...(this._idleTimeout != null && { idleTimeout: this._idleTimeout }) };
+        return {
+            workspace: this.workspace,
+            ...(this.contextId && { contextId: this.contextId }),
+            ...(this._idleTimeout != null && { idleTimeout: this._idleTimeout }),
+        };
     }
     /** Helper: spread workspace + page identity into command params */
     _cmdOpts() {
         return {
             workspace: this.workspace,
+            ...(this.contextId && { contextId: this.contextId }),
             ...(this._page !== undefined && { page: this._page }),
             ...(this._idleTimeout != null && { idleTimeout: this._idleTimeout }),
         };
@@ -53,6 +60,7 @@ export class Page extends BasePage {
         const result = await sendCommandFull('navigate', {
             url,
             ...this._cmdOpts(),
+            ...(options?.allowBoundNavigation === true && { allowBoundNavigation: true }),
         });
         // Remember the page identity (targetId) for subsequent calls
         if (result.page) {

package/dist/src/browser/profile.d.ts

@@ -0,0 +1,14 @@
+export declare const DEFAULT_CONTEXT_ID = "default";
+export type ProfileConfig = {
+    version: 1;
+    defaultContextId?: string;
+    aliases: Record<string, string>;
+};
+export declare function normalizeContextId(value: string | undefined | null): string | undefined;
+export declare function emptyProfileConfig(): ProfileConfig;
+export declare function loadProfileConfig(): ProfileConfig;
+export declare function saveProfileConfig(config: ProfileConfig): void;
+export declare function resolveProfileContextId(profile?: string): string | undefined;
+export declare function aliasForContextId(config: ProfileConfig, contextId: string): string | undefined;
+export declare function renameProfile(contextId: string, alias: string): ProfileConfig;
+export declare function setDefaultProfile(profile: string): ProfileConfig;

package/dist/src/browser/profile.js

@@ -0,0 +1,85 @@
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+export const DEFAULT_CONTEXT_ID = 'default';
+function profileConfigPath() {
+    const baseDir = process.env.OPENCLI_CONFIG_DIR || path.join(os.homedir(), '.opencli');
+    return path.join(baseDir, 'browser-profiles.json');
+}
+export function normalizeContextId(value) {
+    const trimmed = value?.trim();
+    return trimmed || undefined;
+}
+export function emptyProfileConfig() {
+    return { version: 1, aliases: {} };
+}
+export function loadProfileConfig() {
+    try {
+        const raw = fs.readFileSync(profileConfigPath(), 'utf-8');
+        const parsed = JSON.parse(raw);
+        const aliases = parsed.aliases && typeof parsed.aliases === 'object'
+            ? Object.fromEntries(Object.entries(parsed.aliases).filter((entry) => {
+                const [key, value] = entry;
+                return typeof key === 'string' && key.trim().length > 0
+                    && typeof value === 'string' && value.trim().length > 0;
+            }))
+            : {};
+        return {
+            version: 1,
+            aliases,
+            ...(typeof parsed.defaultContextId === 'string' && parsed.defaultContextId.trim()
+                ? { defaultContextId: parsed.defaultContextId.trim() }
+                : {}),
+        };
+    }
+    catch {
+        return emptyProfileConfig();
+    }
+}
+export function saveProfileConfig(config) {
+    const target = profileConfigPath();
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    fs.writeFileSync(target, JSON.stringify(config, null, 2) + '\n', 'utf-8');
+}
+export function resolveProfileContextId(profile) {
+    const config = loadProfileConfig();
+    const requested = normalizeContextId(profile)
+        ?? normalizeContextId(process.env.OPENCLI_PROFILE)
+        ?? normalizeContextId(config.defaultContextId);
+    if (!requested)
+        return undefined;
+    return config.aliases[requested] ?? requested;
+}
+export function aliasForContextId(config, contextId) {
+    for (const [alias, id] of Object.entries(config.aliases)) {
+        if (id === contextId)
+            return alias;
+    }
+    return undefined;
+}
+export function renameProfile(contextId, alias) {
+    const normalizedContextId = normalizeContextId(contextId);
+    const normalizedAlias = normalizeContextId(alias);
+    if (!normalizedContextId)
+        throw new Error('profile contextId is required');
+    if (!normalizedAlias)
+        throw new Error('profile alias is required');
+    const config = loadProfileConfig();
+    for (const [existingAlias, existingContextId] of Object.entries(config.aliases)) {
+        if (existingAlias !== normalizedAlias && existingContextId === normalizedContextId) {
+            delete config.aliases[existingAlias];
+        }
+    }
+    config.aliases[normalizedAlias] = normalizedContextId;
+    saveProfileConfig(config);
+    return config;
+}
+export function setDefaultProfile(profile) {
+    const contextId = resolveProfileContextId(profile) ?? normalizeContextId(profile);
+    if (!contextId)
+        throw new Error('profile is required');
+    const config = loadProfileConfig();
+    config.defaultContextId = contextId;
+    saveProfileConfig(config);
+    return config;
+}

package/dist/src/build-manifest.d.ts

@@ -39,5 +39,7 @@ export interface ManifestEntry {
     /** Pre-navigation control — see CliCommand.navigateBefore */
     navigateBefore?: boolean | string;
 }
+export declare function normalizeManifestPath(relativePath: string): string;
 export declare function loadManifestEntries(filePath: string, site: string, importer?: (moduleHref: string) => Promise<unknown>): Promise<ManifestEntry[]>;
 export declare function buildManifest(): Promise<ManifestEntry[]>;
+export declare function serializeManifest(manifest: ManifestEntry[]): string;

package/dist/src/build-manifest.js

@@ -36,6 +36,12 @@ function toModulePath(filePath, site) {
     const baseName = path.basename(filePath, path.extname(filePath));
     return `${site}/${baseName}.js`;
 }
+export function normalizeManifestPath(relativePath) {
+    return relativePath.replace(/\\/g, '/');
+}
+function toManifestRelativePath(filePath) {
+    return normalizeManifestPath(path.relative(CLIS_DIR, filePath));
+}
 function isCliCommandValue(value, site) {
     return isRecord(value)
         && typeof value.site === 'string'
@@ -85,8 +91,9 @@ export async function loadManifestEntries(filePath, site, importer = moduleHref
                 return !previous || previous !== cmd;
             })
                 .map(([, cmd]) => cmd);
-        // Resolve sourceFile relative to clis/.
-        const sourceRelative = path.relative(CLIS_DIR, filePath);
+        // Manifest paths are cross-platform artifacts; keep them POSIX-style even
+        // when build-manifest runs on Windows.
+        const sourceRelative = toManifestRelativePath(filePath);
         const seen = new Set();
         return runtimeCommands
             .filter((cmd) => {
@@ -128,10 +135,13 @@ export async function buildManifest() {
     }
     return [...manifest.values()].sort((a, b) => a.site.localeCompare(b.site) || a.name.localeCompare(b.name));
 }
+export function serializeManifest(manifest) {
+    return `${JSON.stringify(manifest, null, 2)}\n`;
+}
 async function main() {
     const manifest = await buildManifest();
     fs.mkdirSync(path.dirname(OUTPUT), { recursive: true });
-    fs.writeFileSync(OUTPUT, JSON.stringify(manifest, null, 2));
+    fs.writeFileSync(OUTPUT, serializeManifest(manifest));
     console.log(`✅ Manifest compiled: ${manifest.length} entries → ${OUTPUT}`);
     // Restore executable permissions on bin entries.
     // tsc does not preserve the +x bit, so after a clean rebuild the CLI

package/dist/src/build-manifest.test.js

@@ -3,7 +3,7 @@ import * as fs from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
 import { cli, getRegistry, Strategy } from './registry.js';
-import { loadManifestEntries } from './build-manifest.js';
+import { loadManifestEntries, normalizeManifestPath, serializeManifest } from './build-manifest.js';
 describe('manifest helper rules', () => {
     const tempDirs = [];
     afterEach(() => {
@@ -76,8 +76,9 @@ describe('manifest helper rules', () => {
                 replacedBy: 'opencli demo new',
             },
         ]);
-        // Verify sourceFile is included
+        // Verify sourceFile is included and stable for manifest consumers.
         expect(entries[0].sourceFile).toBeDefined();
+        expect(entries[0].sourceFile).not.toContain('\\');
         getRegistry().delete(key);
     });
     it('falls back to registry delta for side-effect-only cli modules', async () => {
@@ -139,4 +140,21 @@ describe('manifest helper rules', () => {
         getRegistry().delete(screenKey);
         getRegistry().delete(statusKey);
     });
+    it('normalizes manifest paths to POSIX separators', () => {
+        expect(normalizeManifestPath('demo\\status.js')).toBe('demo/status.js');
+        expect(normalizeManifestPath('demo/status.js')).toBe('demo/status.js');
+    });
+    it('serializes manifest json with a trailing newline', () => {
+        const serialized = serializeManifest([{
+                site: 'demo',
+                name: 'status',
+                description: '',
+                strategy: 'public',
+                browser: false,
+                args: [],
+                type: 'js',
+            }]);
+        expect(serialized.endsWith('\n')).toBe(true);
+        expect(serialized).toContain('\n]');
+    });
 });

package/dist/src/cli.d.ts

@@ -6,6 +6,12 @@
  */
 import { Command } from 'commander';
 import { findPackageRoot } from './package-paths.js';
+export declare function selectFreshByTimestamp<T extends {
+    timestamp?: unknown;
+}>(items: T[], lastSeenTs: number): {
+    fresh: T[];
+    lastSeenTs: number;
+};
 /**
  * Check whether the site-memory scaffolding exists under
  * ~/.opencli/sites/<site>/. Agents have a strong tendency to forget to write