@agentrhq/webcmd 0.2.1 → 0.2.2

package/dist/src/browser/runtime/local-cloak/session-manager.test.js

@@ -42,6 +42,64 @@ describe('CloakSessionManager', () => {
         expect(launchPersistentContext).toHaveBeenCalledTimes(1);
         expect(launchPersistentContext.mock.calls[0][0]).toMatchObject({ headless: false });
     });
+    it('freshPage closes the existing persistent lease page and creates a new one', async () => {
+        const makePage = () => ({
+            goto: vi.fn().mockResolvedValue(undefined),
+            evaluate: vi.fn().mockResolvedValue('ok'),
+            title: vi.fn().mockResolvedValue('Title'),
+            url: vi.fn().mockReturnValue('about:blank'),
+            isClosed: vi.fn().mockReturnValue(false),
+            close: vi.fn().mockResolvedValue(undefined),
+        });
+        const openPages = [];
+        const context = {
+            pages: vi.fn(() => openPages),
+            newPage: vi.fn(async () => {
+                const page = makePage();
+                openPages.push(page);
+                return page;
+            }),
+            cookies: vi.fn().mockResolvedValue([]),
+            close: vi.fn().mockResolvedValue(undefined),
+        };
+        const manager = new CloakSessionManager({
+            baseDir: '/tmp/webcmd-test',
+            launchPersistentContext: vi.fn().mockResolvedValue(context),
+        });
+        const key = { profileId: 'default', session: 'site:district', surface: 'adapter', siteSession: 'persistent' };
+        const first = await manager.getPage(key);
+        expect((await manager.getPage(key)).page).toBe(first.page);
+        const fresh = await manager.getPage({ ...key, freshPage: true });
+        expect(first.page.close).toHaveBeenCalled();
+        expect(fresh.page).not.toBe(first.page);
+        const reused = await manager.getPage(key);
+        expect(reused.page).toBe(fresh.page);
+    });
+    it('freshPage never adopts a leftover context tab', async () => {
+        const leftover = {
+            goto: vi.fn(),
+            isClosed: vi.fn().mockReturnValue(false),
+            close: vi.fn().mockResolvedValue(undefined),
+        };
+        const created = {
+            goto: vi.fn(),
+            isClosed: vi.fn().mockReturnValue(false),
+            close: vi.fn().mockResolvedValue(undefined),
+        };
+        const context = {
+            pages: vi.fn().mockReturnValue([leftover]),
+            newPage: vi.fn().mockResolvedValue(created),
+            cookies: vi.fn().mockResolvedValue([]),
+            close: vi.fn().mockResolvedValue(undefined),
+        };
+        const manager = new CloakSessionManager({
+            baseDir: '/tmp/webcmd-test',
+            launchPersistentContext: vi.fn().mockResolvedValue(context),
+        });
+        const lease = await manager.getPage({ profileId: 'default', session: 'site:district', surface: 'adapter', siteSession: 'persistent', freshPage: true });
+        expect(lease.page).toBe(created);
+        expect(context.newPage).toHaveBeenCalled();
+    });
     it('closes ephemeral adapter sessions when released', async () => {
         const launched = fakeContext();
         const manager = new CloakSessionManager({

package/dist/src/build-manifest.js

@@ -103,6 +103,7 @@ function toManifestEntry(cmd, modulePath, sourceFile) {
         sourceFile,
         navigateBefore: cmd.navigateBefore,
         siteSession: cmd.siteSession,
+        freshPage: cmd.freshPage,
         defaultWindowMode: cmd.defaultWindowMode,
     };
 }

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

@@ -81,6 +81,40 @@ describe('manifest helper rules', () => {
         expect(entries[0].sourceFile).not.toContain('\\');
         getRegistry().delete(key);
     });
+    it('serializes freshPage for persistent browser commands', async () => {
+        const site = `manifest-fresh-page-${Date.now()}`;
+        const key = `${site}/checkout`;
+        const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'webcmd-manifest-'));
+        tempDirs.push(dir);
+        const file = path.join(dir, `${site}.ts`);
+        fs.writeFileSync(file, `export const command = cli({ site: '${site}', name: 'checkout', access: 'write' });`);
+        const entries = await loadManifestEntries(file, site, async () => ({
+            command: cli({
+                site,
+                name: 'checkout',
+                access: 'write',
+                description: 'checkout command',
+                strategy: Strategy.COOKIE,
+                browser: true,
+                siteSession: 'persistent',
+                freshPage: true,
+            }),
+        }));
+        expect(entries).toMatchObject([
+            {
+                site,
+                name: 'checkout',
+                access: 'write',
+                strategy: 'cookie',
+                browser: true,
+                siteSession: 'persistent',
+                freshPage: true,
+                type: 'js',
+                modulePath: `${site}/${site}.js`,
+            },
+        ]);
+        getRegistry().delete(key);
+    });
     it('falls back to registry delta for side-effect-only cli modules', async () => {
         const site = `manifest-side-effect-${Date.now()}`;
         const key = `${site}/legacy`;

package/dist/src/cli.js

@@ -7,6 +7,7 @@
 import * as fs from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
+import * as readline from 'node:readline/promises';
 import { fileURLToPath } from 'node:url';
 import { Command, InvalidArgumentError, Option } from 'commander';
 import { findPackageRoot, getBuiltEntryCandidates } from './package-paths.js';
@@ -16,10 +17,10 @@ import { render as renderOutput } from './output.js';
 import { PKG_VERSION } from './version.js';
 import { printCompletionScript } from './completion.js';
 import { loadExternalClis, executeExternalCli, installExternalCli, registerExternalCli, isBinaryInstalled, formatExternalCliLabel } from './external.js';
-import { listWebcmdSkills, readWebcmdSkill } from './skills.js';
+import { installWebcmdSkill, listWebcmdSkills, updateWebcmdSkill } from './skills.js';
 import { registerAllCommands } from './commanderAdapter.js';
 import { classifyAdapter, formatRootAdapterHelpText, installCommanderNamespaceStructuredHelp, installStructuredHelp, leadingPositionalFromUsage, rootHelpData } from './help.js';
-import { EXIT_CODES, getErrorMessage, BrowserConnectError, CliError } from './errors.js';
+import { EXIT_CODES, getErrorMessage, BrowserConnectError, CliError, ArgumentError } from './errors.js';
 import { TargetError } from './browser/target-errors.js';
 import { resolveTargetJs, getTextResolvedJs, getValueResolvedJs, getAttributesResolvedJs, selectResolvedJs, isAutocompleteResolvedJs } from './browser/target-resolver.js';
 import { buildFindJs, buildSemanticFindJs, isFindError } from './browser/find.js';
@@ -58,6 +59,70 @@ function parseDurationMs(raw, flagName) {
 function timestampFromRaw(value) {
     return typeof value === 'number' && Number.isFinite(value) && value > 0 ? value : Date.now();
 }
+function isInteractiveInstall(opts) {
+    return !opts.json && process.stdin.isTTY === true && process.stdout.isTTY === true;
+}
+async function resolveSkillInstallOptions(opts) {
+    if (!isInteractiveInstall(opts))
+        return opts;
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        const scope = opts.scope ?? await choosePrompt(rl, 'Where should Webcmd install skills?', [
+            { key: '1', label: 'Global', value: 'user', aliases: ['global', 'user', 'g'] },
+            { key: '2', label: 'Local project', value: 'project', aliases: ['local', 'project', 'l'] },
+        ], '1');
+        const provider = opts.provider ?? (opts.path ? undefined : await choosePrompt(rl, 'Which coding agent should use them?', [
+            { key: '1', label: 'Agents', value: 'agents', aliases: ['agents', 'agent', 'a'] },
+            { key: '2', label: 'Codex', value: 'codex', aliases: ['codex', 'c'] },
+            { key: '3', label: 'Claude', value: 'claude', aliases: ['claude', 'claude-code'] },
+            { key: '4', label: 'Custom path', value: 'custom', aliases: ['custom', 'path'] },
+        ], '1'));
+        const customPath = opts.path ?? (provider === 'custom' ? await nonEmptyPrompt(rl, 'Skills directory path: ') : undefined);
+        return { ...opts, scope, provider: provider === 'custom' ? undefined : provider, path: customPath };
+    }
+    finally {
+        rl.close();
+    }
+}
+async function choosePrompt(rl, question, choices, defaultKey) {
+    console.log(question);
+    for (const choice of choices)
+        console.log(`  ${choice.key}) ${choice.label}`);
+    while (true) {
+        const answer = (await rl.question(`Choose [${defaultKey}]: `)).trim().toLowerCase() || defaultKey;
+        const choice = choices.find((item) => item.key === answer || item.aliases.includes(answer));
+        if (choice)
+            return choice.value;
+        console.log(`Choose one of: ${choices.map((item) => item.key).join(', ')}`);
+    }
+}
+async function nonEmptyPrompt(rl, question) {
+    while (true) {
+        const answer = (await rl.question(question)).trim();
+        if (answer)
+            return answer;
+        console.log('Path is required.');
+    }
+}
+async function handleSkillLinkCommand(action, json, verb) {
+    try {
+        const result = await action();
+        if (json) {
+            console.log(JSON.stringify(result, null, 2));
+            return;
+        }
+        console.log(`Webcmd skills ${verb}: ${result.skills.length}`);
+        for (const skill of result.skills) {
+            console.log(`${skill.name}: ${skill.destination ? `${skill.destination} -> ` : ''}${skill.stableLink}`);
+        }
+    }
+    catch (err) {
+        console.error(`Error: ${getErrorMessage(err)}`);
+        if (err instanceof CliError && err.hint)
+            console.error(`Hint: ${err.hint}`);
+        process.exitCode = err instanceof CliError ? err.exitCode : EXIT_CODES.GENERIC_ERROR;
+    }
+}
 function toIsoTimestamp(timestamp) {
     if (typeof timestamp !== 'number' || !Number.isFinite(timestamp) || timestamp <= 0)
         return undefined;
@@ -711,10 +776,20 @@ export function createProgram(BUILTIN_CLIS, USER_CLIS) {
     });
     const skillsCmd = program
         .command('skills')
-        .description('Read bundled Webcmd skills');
+        .description('List, install, and update bundled Webcmd skills')
+        .action(() => {
+        const rows = listWebcmdSkills();
+        renderOutput(rows, {
+            fmt: 'table',
+            fmtExplicit: false,
+            columns: ['name', 'description', 'version', 'path'],
+            title: 'webcmd/skills/list',
+            source: 'webcmd skills',
+        });
+    });
     skillsCmd
         .command('list')
-        .description('List bundled webcmd-* skills')
+        .description('List bundled Webcmd skills')
         .option('-f, --format <fmt>', 'Output format: table, json, yaml, md, csv', 'table')
         .action((opts) => {
         const rows = listWebcmdSkills();
@@ -727,30 +802,38 @@ export function createProgram(BUILTIN_CLIS, USER_CLIS) {
         });
     });
     skillsCmd
-        .command('read')
-        .description("Print a bundled webcmd-* skill's SKILL.md or reference file")
-        .argument('<skill>', 'Skill name, or skill/path like webcmd-browser/references/foo.md')
-        .argument('[path]', 'Path under the skill directory')
-        .option('--json', 'Output a JSON envelope instead of raw markdown', false)
-        .action((skill, skillPath, opts) => {
-        let result;
-        try {
-            result = readWebcmdSkill(skill, skillPath ?? '');
-        }
-        catch (err) {
-            console.error(`Error: ${getErrorMessage(err)}`);
-            if (err instanceof CliError && err.hint)
-                console.error(`Hint: ${err.hint}`);
-            process.exitCode = err instanceof CliError ? err.exitCode : EXIT_CODES.GENERIC_ERROR;
-            return;
-        }
-        if (opts.json) {
-            console.log(JSON.stringify(result, null, 2));
-            return;
-        }
-        process.stdout.write(result.content);
-        if (!result.content.endsWith('\n'))
-            process.stdout.write('\n');
+        .command('install')
+        .description('Install bundled Webcmd skills into an agent skills folder')
+        .option('-p, --provider <provider>', 'Agent provider: agents, codex, claude')
+        .option('-s, --scope <scope>', 'Install scope: user/global or project/local')
+        .option('--path <path>', 'Custom agent skills directory')
+        .option('--json', 'Output a JSON envelope', false)
+        .action(async (opts) => {
+        await handleSkillLinkCommand(async () => {
+            const resolved = await resolveSkillInstallOptions(opts);
+            if (resolved.provider === 'custom' && !resolved.path) {
+                throw new ArgumentError('Custom skill provider requires --path.', 'Pass --path <skills-dir> or run interactively.');
+            }
+            return installWebcmdSkill({
+                provider: resolved.provider,
+                scope: resolved.scope,
+                customPath: resolved.path,
+            });
+        }, opts.json, 'installed');
+    });
+    skillsCmd
+        .command('update')
+        .description('Refresh bundled Webcmd skill symlinks after updating the package')
+        .option('-p, --provider <provider>', 'Also repair provider link: agents, codex, claude')
+        .option('-s, --scope <scope>', 'Also repair scoped link: user/global or project/local')
+        .option('--path <path>', 'Also repair a custom agent skills directory')
+        .option('--json', 'Output a JSON envelope', false)
+        .action(async (opts) => {
+        await handleSkillLinkCommand(() => updateWebcmdSkill({
+            provider: opts.provider,
+            scope: opts.scope,
+            customPath: opts.path,
+        }), opts.json, 'updated');
     });
     const authCmd = registerAuthCommands(program);
     program

package/dist/src/discovery.js

@@ -211,6 +211,7 @@ async function loadFromManifest(manifestPath, clisDir) {
                 source: entry.sourceFile ? path.resolve(clisDir, entry.sourceFile) : modulePath,
                 navigateBefore: entry.navigateBefore,
                 siteSession: entry.siteSession,
+                freshPage: entry.freshPage,
                 defaultWindowMode: entry.defaultWindowMode,
                 _lazy: true,
                 _modulePath: modulePath,

package/dist/src/engine.test.js

@@ -3,6 +3,7 @@ import { discoverClis, discoverPlugins, ensureUserCliCompatShims, ensureUserAdap
 import { executeCommand } from './execution.js';
 import { getRegistry, cli, Strategy } from './registry.js';
 import { clearAllHooks, onAfterExecute } from './hooks.js';
+import * as runtime from './runtime.js';
 import * as fs from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
@@ -71,6 +72,67 @@ cli({
             await fs.promises.rm(tempBuildRoot, { recursive: true, force: true });
         }
     });
+    it('preserves freshPage from manifest before lazy command import', async () => {
+        const site = `manifest-fresh-${Date.now()}`;
+        const tempBuildRoot = await fs.promises.mkdtemp(path.join(os.tmpdir(), 'webcmd-manifest-fresh-'));
+        const distDir = path.join(tempBuildRoot, 'dist');
+        const siteDir = path.join(distDir, site);
+        const commandPath = path.join(siteDir, 'checkout.js');
+        const manifestPath = path.join(tempBuildRoot, 'cli-manifest.json');
+        const sessionOpts = [];
+        const mockPage = { closeWindow: vi.fn().mockResolvedValue(undefined) };
+        try {
+            await fs.promises.mkdir(siteDir, { recursive: true });
+            await fs.promises.writeFile(manifestPath, `${JSON.stringify([
+                {
+                    site,
+                    name: 'checkout',
+                    description: 'fresh checkout',
+                    access: 'write',
+                    strategy: 'public',
+                    browser: true,
+                    args: [],
+                    type: 'js',
+                    modulePath: `${site}/checkout.js`,
+                    sourceFile: `${site}/checkout.js`,
+                    siteSession: 'persistent',
+                    freshPage: true,
+                },
+            ], null, 2)}\n`);
+            await fs.promises.writeFile(commandPath, `
+import { cli, Strategy } from '${pathToFileURL(path.join(process.cwd(), 'src', 'registry.ts')).href}';
+cli({
+  site: '${site}',
+  name: 'checkout', access: 'write',
+  description: 'fresh checkout',
+  browser: true,
+  strategy: Strategy.PUBLIC,
+  siteSession: 'persistent',
+  freshPage: true,
+  func: async () => [{ ok: true }],
+});
+`);
+            await discoverClis(distDir);
+            const cmd = getRegistry().get(`${site}/checkout`);
+            expect(cmd?.freshPage).toBe(true);
+            vi.spyOn(runtime, 'browserSession').mockImplementation(async (_Factory, fn, opts) => {
+                sessionOpts.push(opts ?? {});
+                return fn(mockPage);
+            });
+            await expect(executeCommand(cmd, {})).resolves.toEqual([{ ok: true }]);
+            expect(sessionOpts).toHaveLength(1);
+            expect(sessionOpts[0]).toMatchObject({
+                session: `site:${site}`,
+                siteSession: 'persistent',
+                freshPage: true,
+            });
+        }
+        finally {
+            vi.restoreAllMocks();
+            getRegistry().delete(`${site}/checkout`);
+            await fs.promises.rm(tempBuildRoot, { recursive: true, force: true });
+        }
+    });
     it('loads user CLI modules via package exports symlink', async () => {
         const tempWebcmdRoot = await fs.promises.mkdtemp(path.join(os.tmpdir(), 'webcmd-user-clis-'));
         const userClisDir = path.join(tempWebcmdRoot, 'clis');

package/dist/src/execution.js

@@ -334,7 +334,7 @@ export async function executeCommand(cmd, rawKwargs, debug = false, opts = {}) {
                         await page.closeWindow?.().catch(() => { });
                     throw err;
                 }
-            }, { session, cdpEndpoint, ...profileRouting, windowMode, surface: 'adapter', siteSession });
+            }, { session, cdpEndpoint, ...profileRouting, windowMode, surface: 'adapter', siteSession, freshPage: cmd.freshPage === true && siteSession === 'persistent' });
         }
         else {
             // Non-browser commands: enforce a timeout only when the command exposes

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

@@ -38,6 +38,8 @@ export interface ManifestEntry {
     navigateBefore?: boolean | string;
     /** Site session lifecycle defaults — see CliCommand.siteSession */
     siteSession?: 'ephemeral' | 'persistent';
+    /** Fresh page behavior for persistent site sessions — see CliCommand.freshPage */
+    freshPage?: boolean;
     /** Default browser window visibility — see CliCommand.defaultWindowMode */
     defaultWindowMode?: 'foreground' | 'background';
 }

package/dist/src/registry.d.ts

@@ -63,6 +63,16 @@ interface BaseCliCommand {
     navigateBefore?: boolean | string;
     /** Site session lifecycle for adapter commands. */
     siteSession?: SiteSessionMode;
+    /**
+     * Start this command on a freshly created page even when the persistent
+     * site session already has a leased tab. The old tab is closed and a new
+     * one opened under the same lease, so profile state (cookies, localStorage,
+     * login, location) survives while stale DOM (leftover modals, drawers,
+     * half-finished flows from earlier commands) is discarded. Requires
+     * `siteSession: 'persistent'` — ephemeral sessions always start fresh, so
+     * combining them is a contradiction and fails at registration.
+     */
+    freshPage?: boolean;
     /** Default browser window mode for commands whose UX requires visibility. */
     defaultWindowMode?: 'foreground' | 'background';
     /** Override the default CLI output format when the user does not pass -f/--format. */

package/dist/src/registry.js

@@ -29,6 +29,7 @@ export function cli(opts) {
         validateArgs: opts.validateArgs,
         navigateBefore: opts.navigateBefore,
         siteSession: opts.siteSession,
+        freshPage: opts.freshPage,
         defaultWindowMode: opts.defaultWindowMode,
         defaultFormat: opts.defaultFormat,
         authStatus: opts.authStatus,
@@ -86,12 +87,13 @@ function assertCommandAccess(cmd) {
     throw new Error(`Command ${key} must declare access: 'read' | 'write'`);
 }
 function assertSiteSession(cmd) {
-    if (cmd.siteSession === undefined)
-        return;
     const key = `${cmd.site}/${cmd.name}`;
-    if (cmd.siteSession !== 'ephemeral' && cmd.siteSession !== 'persistent') {
+    if (cmd.siteSession !== undefined && cmd.siteSession !== 'ephemeral' && cmd.siteSession !== 'persistent') {
         throw new Error(`Command ${key} siteSession must be one of: ephemeral, persistent`);
     }
+    if (cmd.freshPage === true && cmd.siteSession !== 'persistent') {
+        throw new Error(`Command ${key} freshPage requires siteSession: 'persistent' — ephemeral sessions already start on a fresh page`);
+    }
 }
 export function registerCommand(cmd) {
     const normalized = normalizeCommand(cmd);

package/dist/src/registry.test.js

@@ -19,6 +19,31 @@ describe('cli() registration', () => {
         expect(cmd.browser).toBe(false);
         expect(cmd.args).toEqual([]);
     });
+    it('accepts freshPage with a persistent site session', () => {
+        const cmd = cli({
+            site: 'test-registry',
+            name: 'fresh-ok', access: 'write',
+            description: 'test',
+            siteSession: 'persistent',
+            freshPage: true,
+        });
+        expect(cmd.freshPage).toBe(true);
+    });
+    it('rejects freshPage without a persistent site session', () => {
+        expect(() => cli({
+            site: 'test-registry',
+            name: 'fresh-bad', access: 'write',
+            description: 'test',
+            freshPage: true,
+        })).toThrow(/freshPage requires siteSession: 'persistent'/);
+        expect(() => cli({
+            site: 'test-registry',
+            name: 'fresh-bad-ephemeral', access: 'write',
+            description: 'test',
+            siteSession: 'ephemeral',
+            freshPage: true,
+        })).toThrow(/freshPage requires siteSession: 'persistent'/);
+    });
     it('puts registered command in the registry', () => {
         cli({
             site: 'test-registry',

package/dist/src/runtime.d.ts

@@ -34,6 +34,7 @@ export interface IBrowserFactory {
         windowMode?: BrowserWindowMode;
         surface?: BrowserSurface;
         siteSession?: 'ephemeral' | 'persistent';
+        freshPage?: boolean;
     }): Promise<IPage>;
     close(): Promise<void>;
 }
@@ -46,4 +47,5 @@ export declare function browserSession<T>(BrowserFactory: new () => IBrowserFact
     windowMode?: BrowserWindowMode;
     surface?: BrowserSurface;
     siteSession?: 'ephemeral' | 'persistent';
+    freshPage?: boolean;
 }): Promise<T>;

package/dist/src/runtime.js

@@ -46,6 +46,7 @@ export async function browserSession(BrowserFactory, fn, opts = {}) {
             windowMode: opts.windowMode,
             surface: opts.surface,
             siteSession: opts.siteSession,
+            freshPage: opts.freshPage,
         });
         return await fn(page);
     }

package/dist/src/skills.d.ts

@@ -4,11 +4,29 @@ export interface WebcmdSkillInfo {
     version: string;
     path: string;
 }
-export interface WebcmdSkillReadResult {
-    skill: string;
-    path: string;
-    content: string;
+export interface WebcmdSkillInstallOptions {
+    provider?: string;
+    scope?: string;
+    customPath?: string;
+    packageRoot?: string;
+    homeDir?: string;
+    cwd?: string;
+}
+export interface WebcmdSkillLink {
+    name: string;
+    source: string;
+    stableLink: string;
+    destination?: string;
+}
+export interface WebcmdSkillInstallResult {
+    provider?: SkillProvider;
+    scope?: SkillScope;
+    skills: WebcmdSkillLink[];
 }
+type SkillProvider = 'agents' | 'codex' | 'claude';
+type SkillScope = 'user' | 'project';
 export declare function getSkillsRoot(packageRoot?: string): string;
 export declare function listWebcmdSkills(packageRoot?: string): WebcmdSkillInfo[];
-export declare function readWebcmdSkill(target: string, relpath?: string, packageRoot?: string): WebcmdSkillReadResult;
+export declare function installWebcmdSkill(options?: WebcmdSkillInstallOptions): WebcmdSkillInstallResult;
+export declare function updateWebcmdSkill(options?: WebcmdSkillInstallOptions): WebcmdSkillInstallResult;
+export {};