@agentrhq/webcmd 0.3.2 → 0.3.4

package/dist/src/hosted/types.d.ts

@@ -28,6 +28,7 @@ export interface HostedCommand extends CommandSurfaceMetadata {
     columns: string[];
     domain?: string | null;
     defaultFormat?: string | null;
+    freshPage?: boolean;
 }
 export interface HostedManifest {
     userId: string;

package/dist/src/main.js

@@ -65,6 +65,10 @@ if (!fastPathHandled) {
         const { runHostedSetup } = await import('./hosted/setup.js');
         process.exitCode = await runHostedSetup();
     }
+    else if (argv[0] === 'skills') {
+        const { createProgram } = await import('./cli.js');
+        await createProgram(BUILTIN_CLIS, USER_CLIS).parseAsync(argv, { from: 'user' });
+    }
     else {
         const { shouldUseHostedMode } = await import('./hosted/config.js');
         if (shouldUseHostedMode()) {

package/dist/src/package-bin-process.d.ts

@@ -0,0 +1,13 @@
+type SpawnOutput = string | Buffer | null | undefined;
+export interface PackageBinSpawnFailure {
+    error?: Error;
+    signal?: NodeJS.Signals | null;
+    status: number | null;
+    stdout?: SpawnOutput;
+    stderr?: SpawnOutput;
+}
+export declare function packageBinSpawnOptions(platform: NodeJS.Platform, command: string): {
+    shell?: true;
+};
+export declare function formatPackageBinSpawnFailure(command: string, args: string[], result: PackageBinSpawnFailure): string;
+export {};

package/dist/src/package-bin-process.js

@@ -0,0 +1,24 @@
+import path from 'node:path';
+export function packageBinSpawnOptions(platform, command) {
+    if (platform !== 'win32')
+        return {};
+    const basename = path.win32.basename(command).toLowerCase();
+    return basename === 'npm' || basename.endsWith('.cmd') ? { shell: true } : {};
+}
+function outputText(output) {
+    return output == null ? '' : output.toString().trim();
+}
+export function formatPackageBinSpawnFailure(command, args, result) {
+    const invocation = [command, ...args].join(' ');
+    if (result.error) {
+        return `${invocation} failed to start: ${result.error.message}`;
+    }
+    const outcome = result.status === null
+        ? `terminated by ${result.signal ?? 'an unknown signal'}`
+        : `exited ${result.status}`;
+    return [
+        `${invocation} ${outcome}`,
+        outputText(result.stdout),
+        outputText(result.stderr),
+    ].filter(Boolean).join('\n');
+}

package/dist/src/package-bin-process.test.d.ts

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

package/dist/src/package-bin-process.test.js

@@ -0,0 +1,22 @@
+import { describe, expect, it } from 'vitest';
+import { formatPackageBinSpawnFailure, packageBinSpawnOptions, } from './package-bin-process.js';
+describe('package bin process options', () => {
+    it('uses a shell for npm and cmd shims on Windows', () => {
+        expect(packageBinSpawnOptions('win32', 'npm')).toEqual({ shell: true });
+        expect(packageBinSpawnOptions('win32', 'C:\\prefix\\webcmd.cmd')).toEqual({ shell: true });
+    });
+    it('keeps native executables shell-free', () => {
+        expect(packageBinSpawnOptions('linux', 'npm')).toEqual({});
+        expect(packageBinSpawnOptions('darwin', '/tmp/webcmd')).toEqual({});
+        expect(packageBinSpawnOptions('win32', 'node.exe')).toEqual({});
+    });
+    it('reports launch errors without assuming output streams exist', () => {
+        const error = Object.assign(new Error('spawnSync npm EINVAL'), { code: 'EINVAL' });
+        expect(formatPackageBinSpawnFailure('npm', ['pack'], {
+            error,
+            status: null,
+            stdout: undefined,
+            stderr: undefined,
+        })).toBe('npm pack failed to start: spawnSync npm EINVAL');
+    });
+});

package/dist/src/session-lease.d.ts

@@ -0,0 +1,82 @@
+/** Inactivity window after which an unowned session lease expires. */
+export declare const SESSION_LEASE_TTL_MS = 45000;
+/** Generate an id for one complete logical CLI command run. */
+export declare function generateRunId(): string;
+export interface DaemonRunContext {
+    runId: string;
+    command: string;
+    access: 'read' | 'write';
+}
+/** Run one logical execution with context isolated across its async chain. */
+export declare function runWithDaemonRunContext<T>(context: DaemonRunContext, callback: () => T): T;
+export declare function setDaemonRunContext(context: DaemonRunContext): void;
+export declare function getDaemonRunContext(): DaemonRunContext | undefined;
+/**
+ * Clear only the context still owned by `runId`. Deferred cleanup from an old
+ * command must not clear a newer command's run identity.
+ */
+export declare function clearDaemonRunContext(runId: string): void;
+/**
+ * Detect errors whose browser-side result is unknown. The traversal includes
+ * wrapper causes and AggregateError members and tolerates cyclic error graphs.
+ */
+export declare function isUnknownOutcomeError(error: unknown): boolean;
+export interface SessionLeaseHolder {
+    command: string;
+    pid?: number;
+    acquiredAt: number;
+    heartbeatAt: number;
+}
+export interface SessionLease extends SessionLeaseHolder {
+    key: string;
+    runId: string;
+}
+/** Public status shape: the internal ownership token is intentionally omitted. */
+export type SessionLeaseStatus = Omit<SessionLease, 'runId'>;
+export interface AcquireSessionLeaseInput {
+    key: string;
+    runId: string;
+    command: string;
+    pid?: number;
+}
+export type AcquireResult = {
+    acquired: true;
+    lease: SessionLease;
+} | {
+    acquired: false;
+    holder: SessionLease;
+};
+/**
+ * Lease key for a site session after the daemon has resolved its actual Cloak
+ * profile. Encoding the session keeps key partitions unambiguous.
+ */
+export declare function getSessionLeaseKey(profileId: string, surface: string, session: string): string;
+/** Whether a process id is safe to interpolate into local process guidance. */
+export declare function isActionablePid(pid: unknown): pid is number;
+export interface SessionLeaseCommand {
+    surface?: unknown;
+    siteSession?: unknown;
+    access?: unknown;
+    session?: unknown;
+    runId?: unknown;
+}
+/** Only persistent adapter writes with a complete owner identity need a lease. */
+export declare function isSessionLeaseCommand<T extends SessionLeaseCommand>(command: T): command is T & {
+    surface: 'adapter';
+    siteSession: 'persistent';
+    access: 'write';
+    session: string;
+    runId: string;
+};
+export declare class SessionLeaseRegistry {
+    private readonly now;
+    private readonly leases;
+    constructor(now?: () => number);
+    acquire(input: AcquireSessionLeaseInput, hasPendingWork: (runId: string) => boolean): AcquireResult;
+    /** Refresh a lease only when both its key and logical owner match. */
+    heartbeat(key: string, runId: string): boolean;
+    /** Release all leases owned by one logical run. */
+    releaseByRunId(runId: string): number;
+    /** Return a snapshot of currently live leases without exposing mutable state. */
+    list(hasPendingWork: (runId: string) => boolean): SessionLease[];
+}

package/dist/src/session-lease.js

@@ -0,0 +1,163 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+/** Inactivity window after which an unowned session lease expires. */
+export const SESSION_LEASE_TTL_MS = 45_000;
+let runIdCounter = 0;
+/** Generate an id for one complete logical CLI command run. */
+export function generateRunId() {
+    return `run_${process.pid}_${Date.now()}_${++runIdCounter}`;
+}
+let activeRun;
+const daemonRunContextStorage = new AsyncLocalStorage();
+/** Run one logical execution with context isolated across its async chain. */
+export function runWithDaemonRunContext(context, callback) {
+    return daemonRunContextStorage.run(context, callback);
+}
+export function setDaemonRunContext(context) {
+    activeRun = context;
+}
+export function getDaemonRunContext() {
+    return daemonRunContextStorage.getStore() ?? activeRun;
+}
+/**
+ * Clear only the context still owned by `runId`. Deferred cleanup from an old
+ * command must not clear a newer command's run identity.
+ */
+export function clearDaemonRunContext(runId) {
+    if (activeRun?.runId === runId)
+        activeRun = undefined;
+}
+const UNKNOWN_OUTCOME_CODES = [
+    'command_result_unknown',
+    'command_lost',
+    'result_evicted',
+];
+function containsUnknownOutcomeCode(value) {
+    if (typeof value !== 'string')
+        return false;
+    const normalized = value.toLowerCase();
+    return UNKNOWN_OUTCOME_CODES.some((code) => {
+        const start = normalized.indexOf(code);
+        if (start < 0)
+            return false;
+        const before = normalized[start - 1];
+        const after = normalized[start + code.length];
+        return (!before || !/[a-z0-9_]/.test(before)) && (!after || !/[a-z0-9_]/.test(after));
+    });
+}
+/**
+ * Detect errors whose browser-side result is unknown. The traversal includes
+ * wrapper causes and AggregateError members and tolerates cyclic error graphs.
+ */
+export function isUnknownOutcomeError(error) {
+    const queue = [error];
+    const seen = new Set();
+    while (queue.length > 0) {
+        const current = queue.pop();
+        if (!current || (typeof current !== 'object' && typeof current !== 'function') || seen.has(current)) {
+            continue;
+        }
+        seen.add(current);
+        const record = current;
+        if (containsUnknownOutcomeCode(record.code)
+            || containsUnknownOutcomeCode(record.errorCode)
+            || containsUnknownOutcomeCode(record.daemonCode)
+            || containsUnknownOutcomeCode(record.message)
+            || containsUnknownOutcomeCode(record.error)) {
+            return true;
+        }
+        if (record.cause !== undefined)
+            queue.push(record.cause);
+        if (Array.isArray(record.errors))
+            queue.push(...record.errors);
+    }
+    return false;
+}
+/**
+ * Lease key for a site session after the daemon has resolved its actual Cloak
+ * profile. Encoding the session keeps key partitions unambiguous.
+ */
+export function getSessionLeaseKey(profileId, surface, session) {
+    return `${profileId}␟${surface}␟${encodeURIComponent(session)}`;
+}
+/** Whether a process id is safe to interpolate into local process guidance. */
+export function isActionablePid(pid) {
+    return typeof pid === 'number' && Number.isSafeInteger(pid) && pid > 0;
+}
+function pidFromRunId(runId) {
+    const match = /^run_(\d+)_/.exec(runId);
+    if (!match)
+        return undefined;
+    const pid = Number(match[1]);
+    return isActionablePid(pid) ? pid : undefined;
+}
+/** Only persistent adapter writes with a complete owner identity need a lease. */
+export function isSessionLeaseCommand(command) {
+    return command.surface === 'adapter'
+        && command.siteSession === 'persistent'
+        && command.access === 'write'
+        && typeof command.session === 'string'
+        && command.session.length > 0
+        && typeof command.runId === 'string'
+        && command.runId.length > 0;
+}
+export class SessionLeaseRegistry {
+    now;
+    leases = new Map();
+    constructor(now = Date.now) {
+        this.now = now;
+    }
+    acquire(input, hasPendingWork) {
+        const now = this.now();
+        const current = this.leases.get(input.key);
+        const currentIsLive = current !== undefined
+            && (now - current.heartbeatAt <= SESSION_LEASE_TTL_MS || hasPendingWork(current.runId));
+        if (current && currentIsLive && current.runId !== input.runId) {
+            return { acquired: false, holder: { ...current } };
+        }
+        const pid = input.pid === undefined
+            ? pidFromRunId(input.runId)
+            : (isActionablePid(input.pid) ? input.pid : undefined);
+        const lease = current?.runId === input.runId
+            ? { ...current, heartbeatAt: now }
+            : {
+                key: input.key,
+                runId: input.runId,
+                command: input.command,
+                ...(pid === undefined ? {} : { pid }),
+                acquiredAt: now,
+                heartbeatAt: now,
+            };
+        this.leases.set(input.key, lease);
+        return { acquired: true, lease: { ...lease } };
+    }
+    /** Refresh a lease only when both its key and logical owner match. */
+    heartbeat(key, runId) {
+        const current = this.leases.get(key);
+        if (!current || current.runId !== runId)
+            return false;
+        current.heartbeatAt = this.now();
+        return true;
+    }
+    /** Release all leases owned by one logical run. */
+    releaseByRunId(runId) {
+        let released = 0;
+        for (const [key, lease] of this.leases) {
+            if (lease.runId !== runId)
+                continue;
+            this.leases.delete(key);
+            released += 1;
+        }
+        return released;
+    }
+    /** Return a snapshot of currently live leases without exposing mutable state. */
+    list(hasPendingWork) {
+        const now = this.now();
+        const active = [];
+        for (const lease of this.leases.values()) {
+            if (now - lease.heartbeatAt <= SESSION_LEASE_TTL_MS || hasPendingWork(lease.runId)) {
+                active.push({ ...lease });
+            }
+        }
+        return active;
+    }
+}

package/dist/src/session-lease.test.d.ts

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

package/dist/src/session-lease.test.js

@@ -0,0 +1,217 @@
+import { afterEach, beforeEach, describe, expect, expectTypeOf, it, vi } from 'vitest';
+import { SESSION_LEASE_TTL_MS, SessionLeaseRegistry, clearDaemonRunContext, generateRunId, getDaemonRunContext, getSessionLeaseKey, isSessionLeaseCommand, isUnknownOutcomeError, runWithDaemonRunContext, setDaemonRunContext, } from './session-lease.js';
+const T0 = 1_000_000;
+describe('logical daemon run context', () => {
+    afterEach(() => {
+        const current = getDaemonRunContext();
+        if (current)
+            clearDaemonRunContext(current.runId);
+        vi.restoreAllMocks();
+    });
+    it('keeps one run id stable while a logical run is bound and generates a different id for the next run', () => {
+        vi.spyOn(Date, 'now').mockReturnValue(1_763_000_000_000);
+        const firstRunId = generateRunId();
+        setDaemonRunContext({ runId: firstRunId, command: 'chatgpt ask', access: 'write' });
+        expect(getDaemonRunContext()?.runId).toBe(firstRunId);
+        expect(getDaemonRunContext()?.runId).toBe(firstRunId);
+        clearDaemonRunContext(firstRunId);
+        const secondRunId = generateRunId();
+        expect(secondRunId).not.toBe(firstRunId);
+        expect(firstRunId).toMatch(new RegExp(`^run_${process.pid}_1763000000000_\\d+$`));
+    });
+    it('does not let deferred cleanup from an older run clear a newer run context', () => {
+        setDaemonRunContext({ runId: 'run_111_1_1', command: 'chatgpt ask', access: 'write' });
+        setDaemonRunContext({ runId: 'run_222_2_2', command: 'claude ask', access: 'write' });
+        clearDaemonRunContext('run_111_1_1');
+        expect(getDaemonRunContext()).toEqual({
+            runId: 'run_222_2_2',
+            command: 'claude ask',
+            access: 'write',
+        });
+        clearDaemonRunContext('run_222_2_2');
+        expect(getDaemonRunContext()).toBeUndefined();
+    });
+    it('only accepts a concrete run context through the setter', () => {
+        expectTypeOf(setDaemonRunContext).parameter(0).toEqualTypeOf();
+    });
+    it('keeps overlapping async run contexts isolated across awaits', async () => {
+        let resumeFirst;
+        const firstGate = new Promise(resolve => { resumeFirst = resolve; });
+        const firstContext = {
+            runId: 'run_111_1_1',
+            command: 'first write',
+            access: 'write',
+        };
+        const secondContext = {
+            runId: 'run_222_2_2',
+            command: 'second write',
+            access: 'write',
+        };
+        const first = runWithDaemonRunContext(firstContext, async () => {
+            await firstGate;
+            return getDaemonRunContext();
+        });
+        const second = runWithDaemonRunContext(secondContext, async () => getDaemonRunContext());
+        expect(await second).toEqual(secondContext);
+        resumeFirst();
+        expect(await first).toEqual(firstContext);
+        expect(getDaemonRunContext()).toBeUndefined();
+    });
+});
+describe('isUnknownOutcomeError', () => {
+    it('recognizes public, daemon, and message codes case-insensitively', () => {
+        expect(isUnknownOutcomeError({ code: 'COMMAND_RESULT_UNKNOWN' })).toBe(true);
+        expect(isUnknownOutcomeError({ errorCode: 'Command_Lost' })).toBe(true);
+        expect(isUnknownOutcomeError(new Error('daemon returned RESULT_EVICTED'))).toBe(true);
+        expect(isUnknownOutcomeError({ daemonCode: 'attach_failed', message: 'ordinary failure' })).toBe(false);
+    });
+    it('walks causes and AggregateError members without looping on cycles', () => {
+        const cyclic = new Error('outer');
+        cyclic.cause = cyclic;
+        const aggregate = new AggregateError([
+            cyclic,
+            new Error('wrapped', { cause: { errorCode: 'COMMAND_LOST' } }),
+        ]);
+        expect(isUnknownOutcomeError(aggregate)).toBe(true);
+        expect(isUnknownOutcomeError(cyclic)).toBe(false);
+    });
+});
+describe('session lease partitions', () => {
+    it('partitions persistent writes by resolved profile, surface, and encoded site', () => {
+        const workChatgpt = getSessionLeaseKey('work', 'adapter', 'site:chatgpt');
+        expect(workChatgpt).toBe('work␟adapter␟site%3Achatgpt');
+        expect(workChatgpt).not.toBe(getSessionLeaseKey('personal', 'adapter', 'site:chatgpt'));
+        expect(workChatgpt).not.toBe(getSessionLeaseKey('work', 'adapter', 'site:claude'));
+        expect(workChatgpt).not.toBe(getSessionLeaseKey('work', 'browser', 'site:chatgpt'));
+    });
+    it('does not arbitrate reads, ephemeral sessions, raw browser operations, or incomplete identities', () => {
+        const eligible = {
+            surface: 'adapter',
+            siteSession: 'persistent',
+            access: 'write',
+            session: 'site:chatgpt',
+            runId: 'run_111_1_1',
+        };
+        expect(isSessionLeaseCommand(eligible)).toBe(true);
+        expect(isSessionLeaseCommand({ ...eligible, access: 'read' })).toBe(false);
+        expect(isSessionLeaseCommand({ ...eligible, siteSession: 'ephemeral' })).toBe(false);
+        expect(isSessionLeaseCommand({ ...eligible, surface: 'browser' })).toBe(false);
+        expect(isSessionLeaseCommand({ ...eligible, session: '' })).toBe(false);
+        expect(isSessionLeaseCommand({ ...eligible, runId: undefined })).toBe(false);
+    });
+});
+describe('SessionLeaseRegistry', () => {
+    const KEY = getSessionLeaseKey('work', 'adapter', 'site:chatgpt');
+    let now = T0;
+    beforeEach(() => {
+        now = T0;
+    });
+    function registry() {
+        return new SessionLeaseRegistry(() => now);
+    }
+    function acquire(registry, runId, key = KEY) {
+        return registry.acquire({ key, runId, command: 'chatgpt ask', pid: Number(runId.split('_')[1]) }, () => false);
+    }
+    it('acquires a free key and returns the live holder on a conflicting run without mutation', () => {
+        const leases = registry();
+        expect(acquire(leases, 'run_111_1_1')).toEqual({
+            acquired: true,
+            lease: expect.objectContaining({
+                key: KEY,
+                runId: 'run_111_1_1',
+                command: 'chatgpt ask',
+                pid: 111,
+                acquiredAt: T0,
+                heartbeatAt: T0,
+            }),
+        });
+        now += 1_000;
+        const conflict = acquire(leases, 'run_222_2_2');
+        expect(conflict).toEqual({
+            acquired: false,
+            holder: expect.objectContaining({ runId: 'run_111_1_1', heartbeatAt: T0 }),
+        });
+        expect(leases.list(() => false)).toEqual([
+            expect.objectContaining({ runId: 'run_111_1_1', heartbeatAt: T0 }),
+        ]);
+    });
+    it('recovers the holder pid from a generated run id when explicit metadata is absent', () => {
+        const leases = registry();
+        expect(leases.acquire({ key: KEY, runId: 'run_4242_1700000000000_7', command: 'chatgpt ask' }, () => false)).toEqual({
+            acquired: true,
+            lease: expect.objectContaining({ pid: 4242 }),
+        });
+    });
+    it.each([
+        0,
+        -1,
+        1.5,
+        Number.NaN,
+        Number.POSITIVE_INFINITY,
+        Number.MAX_SAFE_INTEGER + 1,
+    ])('omits a non-actionable explicit holder pid (%s)', (pid) => {
+        const leases = registry();
+        const result = leases.acquire({ key: KEY, runId: 'opaque-run-id', command: 'chatgpt ask', pid }, () => false);
+        expect(result.acquired).toBe(true);
+        if (result.acquired)
+            expect(result.lease).not.toHaveProperty('pid');
+    });
+    it.each([
+        'run_0_1700000000000_1',
+        'run_-1_1700000000000_1',
+        'run_1.5_1700000000000_1',
+        'run_NaN_1700000000000_1',
+        'run_Infinity_1700000000000_1',
+        `run_${Number.MAX_SAFE_INTEGER + 1}_1700000000000_1`,
+    ])('does not recover a non-actionable holder pid from %s', (runId) => {
+        const leases = registry();
+        const result = leases.acquire({ key: KEY, runId, command: 'chatgpt ask' }, () => false);
+        expect(result.acquired).toBe(true);
+        if (result.acquired)
+            expect(result.lease).not.toHaveProperty('pid');
+    });
+    it('treats same-run acquisition and explicit heartbeat as owner-only liveness refreshes', () => {
+        const leases = registry();
+        acquire(leases, 'run_111_1_1');
+        now += SESSION_LEASE_TTL_MS;
+        const refreshed = acquire(leases, 'run_111_1_1');
+        expect(refreshed).toEqual({
+            acquired: true,
+            lease: expect.objectContaining({ acquiredAt: T0, heartbeatAt: now }),
+        });
+        now += 10;
+        expect(leases.heartbeat(KEY, 'run_999_9_9')).toBe(false);
+        expect(leases.heartbeat(KEY, 'run_111_1_1')).toBe(true);
+        expect(leases.list(() => false)[0]).toMatchObject({ acquiredAt: T0, heartbeatAt: now });
+    });
+    it('lets a challenger acquire after expiry', () => {
+        const leases = registry();
+        acquire(leases, 'run_111_1_1');
+        now += SESSION_LEASE_TTL_MS + 1;
+        expect(acquire(leases, 'run_222_2_2')).toEqual({
+            acquired: true,
+            lease: expect.objectContaining({ runId: 'run_222_2_2', acquiredAt: now }),
+        });
+    });
+    it('keeps an expired holder live while the holder still has pending work', () => {
+        const leases = registry();
+        acquire(leases, 'run_111_1_1');
+        now += SESSION_LEASE_TTL_MS + 10_000;
+        const conflict = leases.acquire({ key: KEY, runId: 'run_222_2_2', command: 'chatgpt ask', pid: 222 }, (runId) => runId === 'run_111_1_1');
+        expect(conflict).toEqual({
+            acquired: false,
+            holder: expect.objectContaining({ runId: 'run_111_1_1' }),
+        });
+        expect(leases.list((runId) => runId === 'run_111_1_1')).toHaveLength(1);
+        expect(leases.list(() => false)).toEqual([]);
+    });
+    it('releases only leases owned by the requested run and reports the count', () => {
+        const leases = registry();
+        acquire(leases, 'run_111_1_1');
+        acquire(leases, 'run_111_1_1', getSessionLeaseKey('work', 'adapter', 'site:claude'));
+        expect(leases.releaseByRunId('run_999_9_9')).toBe(0);
+        expect(leases.list(() => false)).toHaveLength(2);
+        expect(leases.releaseByRunId('run_111_1_1')).toBe(2);
+        expect(leases.list(() => false)).toEqual([]);
+    });
+});

package/dist/src/skills.d.ts

@@ -4,7 +4,7 @@ export interface WebcmdSkillInfo {
     version: string;
     path: string;
 }
-export interface WebcmdSkillInstallOptions {
+export interface WebcmdSkillOptions {
     provider?: string;
     scope?: string;
     customPath?: string;
@@ -18,15 +18,19 @@ export interface WebcmdSkillLink {
     stableLink: string;
     destination?: string;
 }
-export interface WebcmdSkillInstallResult {
+export interface WebcmdSkillAddResult {
     provider?: SkillProvider;
     scope?: SkillScope;
     skills: WebcmdSkillLink[];
 }
+export interface WebcmdSkillRemoveResult {
+    removed: string[];
+}
 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 installWebcmdSkill(options?: WebcmdSkillInstallOptions): WebcmdSkillInstallResult;
-export declare function updateWebcmdSkill(options?: WebcmdSkillInstallOptions): WebcmdSkillInstallResult;
+export declare function addWebcmdSkills(options?: WebcmdSkillOptions): WebcmdSkillAddResult;
+export declare function updateWebcmdSkill(options?: WebcmdSkillOptions): WebcmdSkillAddResult;
+export declare function removeWebcmdSkills(options?: WebcmdSkillOptions): WebcmdSkillRemoveResult;
 export {};

package/dist/src/skills.js

@@ -19,7 +19,7 @@ export function listWebcmdSkills(packageRoot) {
         .filter((entry) => entry !== null)
         .sort((a, b) => a.name.localeCompare(b.name));
 }
-export function installWebcmdSkill(options = {}) {
+export function addWebcmdSkills(options = {}) {
     const provider = options.customPath === undefined ? normalizeProvider(options.provider) : undefined;
     const scope = normalizeScope(options.scope);
     const skills = updateStableSkillLinks(options)
@@ -46,6 +46,35 @@ export function updateWebcmdSkill(options = {}) {
         }),
     };
 }
+export function removeWebcmdSkills(options = {}) {
+    const homeDir = options.homeDir ?? os.homedir();
+    const cwd = options.cwd ?? process.cwd();
+    const roots = new Set([
+        ...['.agents', '.codex', '.claude'].flatMap((dir) => [
+            path.join(homeDir, dir, 'skills'),
+            path.join(cwd, dir, 'skills'),
+        ]),
+        ...(options.customPath === undefined ? [] : [expandHomePath(options.customPath)]),
+        path.join(homeDir, '.webcmd', 'skills'),
+    ]);
+    const skills = listWebcmdSkills(options.packageRoot);
+    const removed = [];
+    for (const root of roots) {
+        for (const skill of skills) {
+            const linkPath = path.join(root, skill.name);
+            const current = safeLstat(linkPath);
+            if (!current)
+                continue;
+            if (!current.isSymbolicLink()) {
+                throw new ArgumentError(`Refusing to remove non-symlink path: ${linkPath}`, 'Remove it manually if it is no longer needed.');
+            }
+            removed.push(linkPath);
+        }
+    }
+    for (const linkPath of removed)
+        fs.unlinkSync(linkPath);
+    return { removed };
+}
 function updateStableSkillLinks(options) {
     const skillsRoot = getSkillsRoot(options.packageRoot);
     const skills = listWebcmdSkills(options.packageRoot);