@hzlmy2002/web-market 0.1.0

package/README.md

@@ -0,0 +1,100 @@
+# AIsa Web Market
+
+Node/TypeScript stdio MCP for focused website competitive analysis. Five tools call **AIsa REST APIs directly**, with user-supplied Bearer authentication. No dependency on the Python aisa-mcp server, OAuth, or model calls inside tools.
+
+## Install with npx
+
+Requires Node 22 or newer. Set AISA_API_KEY in the environment of the process launching your MCP client, then run one of:
+
+```sh
+npx -y @hzlmy2002/web-market@0.1.0 setup --client codex
+npx -y @hzlmy2002/web-market@0.1.0 setup --client claude-code
+npx -y @hzlmy2002/web-market@0.1.0 setup --client hermes
+```
+
+This installs the Skill and registers a version-pinned `npx -y @hzlmy2002/web-market@0.1.0 serve` MCP command. Clearing the npm cache does not invalidate the configured path: npx downloads the pinned release again when necessary. Restart or refresh the client to discover the Skill. Credentials must still reach the MCP process; the installer never stores your key. Use `uninstall --client ...` to remove an unchanged managed installation.
+
+## Local setup
+
+Requires Node 22 or newer.
+
+```sh
+npm ci
+npm test
+npm run build
+```
+
+Set `AISA_API_KEY` in the environment of the process launching your MCP client. It is an AIsa API key; never put it in a Skill or commit it. Desktop clients started outside your shell may need the variable configured explicitly in their MCP settings. The installer does not read or persist the key.
+
+Run one of these from this checkout:
+
+```sh
+node dist/cli.js setup --client codex
+node dist/cli.js setup --client claude-code
+node dist/cli.js setup --client hermes
+```
+
+Setup installs the Skill and merges a user-level MCP entry using the absolute Node executable and checkout path. Keep this checkout in place or rerun setup after moving it. Existing settings are preserved semantically; TOML/YAML comments and formatting can change. Unowned existing Skill files are preserved, even if their contents match the bundle. Setup refuses conflicting MCP entries and modified skills. It stages changes in memory, uses atomic writes and rolls back ordinary write failures. It uses a lock against concurrent AIsa installers; close the client's settings editor during setup. This is not a filesystem transaction across process crashes.
+
+| Client | Skill directory | MCP config |
+|---|---|---|
+| Codex | `~/.agents/skills/aisa-web-market` | `~/.codex/config.toml` |
+| Claude Code | `~/.claude/skills/aisa-web-market` | `~/.claude.json` |
+| Hermes | `~/.hermes/skills/aisa-web-market` | `~/.hermes/config.yaml` |
+
+Refresh/restart the client after installation if the skill is not visible. Setup follows the actual user's home directory; use `--home /absolute/path` for an isolated profile or testing. Symlinked installation paths are refused to avoid writing outside the selected location. For Hermes custom profiles, pass the matching profile home explicitly; otherwise setup targets `~/.hermes`.
+
+To use MCP-only configuration, set `command` to your Node executable and `args` to the absolute path to `dist/cli.js`, followed by `serve`. Pass `AISA_API_KEY` through the client environment. To install the skill during server startup, add `--install-skills --client codex` (or another supported client). This is an explicit opt-in, runs idempotently, and writes status only to stderr; the first session may require a refresh for skill discovery.
+
+```sh
+node dist/cli.js status
+node dist/cli.js uninstall --client codex
+```
+
+Uninstall removes only matching owned files and the matching MCP entry. It preserves other tools and settings. A modified owned file stops uninstall for review. It may leave empty directories. To update, rebuild this checkout and rerun setup.
+
+## Tools
+
+| Tool | Behavior |
+|---|---|
+| `AIsa_similar_sites` | One seed; explicit supported end month; exact 3-month window; up to 20 candidates |
+| `AIsa_traffic_engagement` | 1–5 domains, explicit 1–12 monthly buckets, visits and engagement; aligned missing cells and growth |
+| `AIsa_geography` | Latest worldwide snapshot, up to 10 countries per domain, 1–5 domains |
+| `AIsa_website_keywords` | Single-domain keyword sample, explicit month, up to 20 rows |
+| `AIsa_keyword_gap` | Target and 1–3 competitors, matching scope, deterministic sample classifications |
+
+Country is `us` or `ww` in this release. Keyword filtering by organic/paid or branded/nonbranded is not exposed by the pinned API contract. `competition` is not relabeled as difficulty. No search volume is invented. Domain URLs are normalized; duplicate, IP, local and invalid hosts are rejected.
+
+Every tool supports optional `max_price_usd`, a **total tool-call ceiling**, divided downward across planned requests and passed as `X-AISA-Max-Price-USD`. This relies on AIsa gateway enforcement. It is not a local price estimate or a conversation-wide budget. No automatic retries; timed-out requests may already have been billed. Up to three requests run concurrently, each with a 20-second timeout and 2 MB response cap; a tool invocation has a 60-second deadline. No persistent data cache is used.
+
+Dates are explicit for traffic, keywords and Similar Sites. The public API does not expose a universally verified availability endpoint for these datasets, so this release does not guess the latest published month or perform additional billed probing. Geography uses the server's latest available snapshot and reports its scope. A later release can add availability discovery once a stable public contract exists.
+
+Example user requests:
+
+- “Compare a.com and b.com traffic, worldwide, April–June 2026.”
+- “Compare target.com and rival.com keyword samples for June 2026 in the US.”
+- “Find sites similar to a.com for the supported window ending July 2026.”
+
+## Plugin bundles
+
+```sh
+npm run plugins
+```
+
+Generates `plugins/{codex,claude-code,hermes}/aisa-web-market/`, each with the same skills and a self-contained JS runtime (Node still required). No npm download is needed when starting a generated plugin. Packaging itself does not install anything into your clients or publish a marketplace entry.
+
+- Codex: `.codex-plugin/plugin.json` plus `.mcp.json`; distribute using the client's local/plugin marketplace workflow.
+- Claude Code: `.claude-plugin/plugin.json` plus `.mcp.json`; local test with `claude --plugin-dir /absolute/path/to/plugins/claude-code/aisa-web-market`.
+- Hermes: Agent Plugins v1 `plugin.json` plus `mcp.json`; requires a version supporting portable packages. Enable after installing through Hermes. Configure AISA_API_KEY in the Hermes process environment.
+
+Prefer either plugin installation or direct setup for a client, to avoid duplicate skills and tools. Plugin host discovery has not been tested in interactive Codex/Claude/Hermes sessions. The bundled runtime is tested over real stdio, and setup configuration is tested in isolated profiles.
+
+## Development and release
+
+`npm test` exercises API contracts, calculations, failures, installer preservation and real stdio protocol exchange without network calls or credits. `npm pack` creates an installable npm archive. The scoped package is configured for public npm publication. npm-installed setup registers a pinned npx command; setup from a source checkout registers its local Node entry. Plugin bundles remain a separate distribution option.
+
+`docs/contract.md` records the endpoint mapping and limits. `docs/upstream-snapshot.json` captures only the required operation definitions and examples from the supplied docs checkout. Run `node scripts/check-contract.mjs /path/to/docs/openapi/similarweb.json` to detect drift in those operations. Live API verification requires an explicitly selected funded account and month; no production calls are made by the test suite.
+
+## Live verification
+
+The five tools and all four underlying API paths were exercised with an authorized test account on 2026-09-05 (9 requests). See [the report](docs/live-verification-2026-09-05.md). `estk.me` returned provider Data not found for July 2026 traffic/geography; wikipedia.org succeeded. The exact no-data signature now returns empty success with an explanatory warning. The captured responses also run offline in regression tests. This does not guarantee every domain or month has data.

package/dist/api.d.ts

@@ -0,0 +1,24 @@
+export type Row = Record<string, any>;
+export declare class ApiError extends Error {
+    code: string;
+    retryable: boolean;
+    status?: number | undefined;
+    constructor(code: string, message: string, retryable?: boolean, status?: number | undefined);
+}
+export declare const paths: {
+    readonly traffic: "/similarweb/website/traffic-engagement";
+    readonly similar: "/similarweb/website/similar-sites";
+    readonly keywords: "/similarweb/search/website-keywords";
+    readonly geography: "/similarweb/website-top-geographies";
+};
+export type Endpoint = typeof paths[keyof typeof paths];
+export interface Transport {
+    get(path: Endpoint, query: Row, cap?: number, signal?: AbortSignal): Promise<Row>;
+}
+export declare function safeError(error: unknown): ApiError;
+export declare class ApiClient implements Transport {
+    private key;
+    private fetcher;
+    constructor(key?: string | undefined, fetcher?: typeof fetch);
+    get(path: Endpoint, query: Row, cap?: number, signal?: AbortSignal): Promise<Row>;
+}

package/dist/api.js

@@ -0,0 +1,137 @@
+export class ApiError extends Error {
+    code;
+    retryable;
+    status;
+    constructor(code, message, retryable = false, status) {
+        super(message);
+        this.code = code;
+        this.retryable = retryable;
+        this.status = status;
+    }
+}
+export const paths = {
+    traffic: '/similarweb/website/traffic-engagement',
+    similar: '/similarweb/website/similar-sites',
+    keywords: '/similarweb/search/website-keywords',
+    geography: '/similarweb/website-top-geographies',
+};
+export function safeError(error) {
+    return error instanceof ApiError ? error : new ApiError('internal_error', 'The operation could not be completed.');
+}
+export class ApiClient {
+    key;
+    fetcher;
+    constructor(key = process.env.AISA_API_KEY, fetcher = fetch) {
+        this.key = key;
+        this.fetcher = fetcher;
+    }
+    async get(path, query, cap, signal) {
+        if (!this.key?.trim())
+            throw new ApiError('missing_credentials', 'Set AISA_API_KEY in the MCP server environment and restart the server.');
+        if (!Object.values(paths).includes(path))
+            throw new ApiError('invalid_input', 'Unsupported API operation.');
+        const url = new URL('https://api.aisa.one/apis/v1' + path);
+        for (const [k, v] of Object.entries(query))
+            if (v !== undefined)
+                url.searchParams.set(k, String(v));
+        const headers = { Authorization: `Bearer ${this.key.trim()}`, Accept: 'application/json' };
+        if (cap !== undefined)
+            headers['X-AISA-Max-Price-USD'] = String(cap);
+        try {
+            // No automatic retries: a timed-out billable request may already have succeeded.
+            const response = await this.fetcher(url, { headers, redirect: 'error', signal: signal ? AbortSignal.any([signal, AbortSignal.timeout(20_000)]) : AbortSignal.timeout(20_000) });
+            if (!response.ok) {
+                // Inspect only a bounded error body for known gateway identifiers.
+                // Never forward arbitrary provider messages (they may contain secrets).
+                let gatewayError;
+                let errorBody;
+                const errorReader = response.body?.getReader();
+                if (errorReader) {
+                    const chunks = [];
+                    let bytes = 0;
+                    try {
+                        while (true) {
+                            const { done, value } = await errorReader.read();
+                            if (done)
+                                break;
+                            bytes += value.byteLength;
+                            if (bytes > 16_384) {
+                                await errorReader.cancel();
+                                break;
+                            }
+                            chunks.push(value);
+                        }
+                        if (bytes <= 16_384) {
+                            const body = JSON.parse(Buffer.concat(chunks).toString('utf8'));
+                            errorBody = body;
+                            gatewayError = typeof body?.error === 'string' ? body.error : body?.error?.code;
+                        }
+                    }
+                    catch { /* Keep HTTP classification when error JSON cannot be read. */ }
+                    finally {
+                        errorReader.releaseLock();
+                    }
+                }
+                // Similarweb uses HTTP 404 + provider error_code 401 for an absent
+                // dataset. Provider code 401 is NOT HTTP authentication failure.
+                if (response.status === 404 && errorBody?.meta?.status === 'error'
+                    && errorBody.meta.error_code === 401 && errorBody.meta.error_message === 'Data not found'
+                    && errorBody.data === null) {
+                    return {
+                        meta: { ...errorBody.meta, status: 'success', empty_reason: 'provider_no_data' },
+                        data: path === paths.geography ? { countries: [] } : [],
+                    };
+                }
+                if (response.status === 402 && gatewayError === 'estimated_price_exceeds_max_price') {
+                    throw new ApiError('cost_limit_exceeded', 'The estimated request price exceeds max_price_usd. Increase the authorized budget or reduce scope; this error does not establish insufficient account credit.', false, 402);
+                }
+                if (response.status === 404 && gatewayError === 'api endpoint not found') {
+                    throw new ApiError('unavailable_operation', 'AIsa gateway could not resolve an enabled route for this API operation. Check endpoint and metering configuration; this does not establish an account-permission failure.', false, 404);
+                }
+                const codes = {
+                    400: ['invalid_input', 'AIsa rejected the query scope or parameters.', false],
+                    401: ['unauthorized', 'AIsa rejected the API key. Check AISA_API_KEY.', false],
+                    402: ['payment_required', 'AIsa requires sufficient credit and the appropriate subscription. Check your AIsa account.', false],
+                    403: ['forbidden', 'The account cannot access this data scope.', false],
+                    404: ['not_found', 'HTTP 404 returned by AIsa or its data provider. The response does not establish whether the route is unavailable or the requested resource/data was not found.', false],
+                    429: ['upstream_rate_limited', 'AIsa rate limited this request. Retry later.', true],
+                };
+                const [code, message, retryable] = codes[response.status] ?? ['upstream_unavailable', 'AIsa could not complete this request.', response.status >= 500];
+                throw new ApiError(code, message, retryable, response.status);
+            }
+            const reader = response.body?.getReader();
+            if (!reader)
+                throw new ApiError('invalid_response', 'AIsa returned no response body.');
+            let size = 0;
+            const chunks = [];
+            while (true) {
+                const { done, value } = await reader.read();
+                if (done)
+                    break;
+                size += value.byteLength;
+                if (size > 2_000_000) {
+                    await reader.cancel();
+                    throw new ApiError('response_too_large', 'AIsa response exceeded the 2 MB limit.');
+                }
+                chunks.push(value);
+            }
+            let body;
+            try {
+                body = JSON.parse(Buffer.concat(chunks).toString('utf8'));
+            }
+            catch {
+                throw new ApiError('invalid_response', 'AIsa returned invalid JSON.');
+            }
+            if (!body || typeof body !== 'object' || Array.isArray(body) || !('data' in body))
+                throw new ApiError('invalid_response', 'AIsa returned an unexpected data envelope.');
+            if (body.error || (body.meta?.status && body.meta.status !== 'success'))
+                throw new ApiError('upstream_error', 'The data source reported an error; no data was inferred.');
+            return body;
+        }
+        catch (e) {
+            if (e instanceof ApiError)
+                throw e;
+            throw new ApiError(signal?.aborted ? 'cancelled' : 'network_error', 'Request interrupted or unavailable. It may have been billed; it was not automatically retried.', true);
+        }
+    }
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,38 @@
+#!/usr/bin/env node
+import { parseArgs } from 'node:util';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { createServer } from './server.js';
+import { install } from './install.js';
+async function main() {
+    const { values, positionals } = parseArgs({ allowPositionals: true, options: { client: { type: 'string' }, home: { type: 'string' }, 'install-skills': { type: 'boolean' }, help: { type: 'boolean' } } });
+    const command = positionals[0] ?? 'serve';
+    if (values.help) {
+        console.log('aisa-web-market serve [--install-skills --client codex|claude-code|hermes]\naisa-web-market setup|uninstall --client codex|claude-code|hermes [--home directory]\naisa-web-market status\nSet AISA_API_KEY in the server environment. setup never stores the token.');
+        return;
+    }
+    if (positionals.length > 1)
+        throw Error('Unexpected positional argument.');
+    if (command === 'status') {
+        console.log(JSON.stringify({ credential_configured: Boolean(process.env.AISA_API_KEY?.trim()), authentication: 'bearer', version: '0.1.0' }));
+        return;
+    }
+    if (command === 'setup' || command === 'uninstall') {
+        if (!values.client)
+            throw Error('--client is required.');
+        console.log(JSON.stringify(await install(values.client, { home: values.home, remove: command === 'uninstall' })));
+        console.log('Client configuration preserves existing values; serialization may reformat comments. Ensure AISA_API_KEY reaches the client process. Restart or refresh the client to load skills.');
+        return;
+    }
+    if (command !== 'serve')
+        throw Error('Unknown command. Use --help.');
+    if (values['install-skills']) {
+        if (!values.client)
+            throw Error('--install-skills requires --client.');
+        console.error(JSON.stringify(await install(values.client, { home: values.home, skillsOnly: true })));
+    }
+    const server = createServer();
+    await server.connect(new StdioServerTransport());
+    for (const sig of ['SIGINT', 'SIGTERM'])
+        process.once(sig, () => { void server.close().finally(() => process.exit(0)); });
+}
+main().catch(e => { console.error(e instanceof Error ? e.message : 'Startup failed.'); process.exitCode = 1; });

package/dist/install.d.ts

@@ -0,0 +1,17 @@
+export type Client = 'codex' | 'claude-code' | 'hermes';
+export declare const packageRoot: string;
+export declare function launchEntry(client: Client, root?: string): {
+    env_vars?: string[] | undefined;
+    command: string;
+    args: string[];
+};
+export declare function install(client: Client, options?: {
+    home?: string;
+    remove?: boolean;
+    skillsOnly?: boolean;
+}): Promise<{
+    client: Client;
+    skill: string;
+    config: string | null;
+    action: string;
+}>;

package/dist/install.js

@@ -0,0 +1,176 @@
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { createHash, randomUUID } from 'node:crypto';
+import { homedir } from 'node:os';
+import { fileURLToPath } from 'node:url';
+import TOML from '@iarna/toml';
+import YAML from 'yaml';
+export const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const skillName = 'aisa-web-market';
+// npm/npx installations live in node_modules. Persist a version-pinned registry
+// command rather than a path into npx's disposable cache. Checkouts keep the
+// local Node entry so development changes remain immediately testable.
+export function launchEntry(client, root = packageRoot) {
+    const command = root.split(path.sep).includes('node_modules')
+        ? { command: process.platform === 'win32' ? 'npx.cmd' : 'npx', args: ['-y', '@hzlmy2002/web-market@0.1.0', 'serve'] }
+        : { command: process.execPath, args: [path.join(root, 'dist/cli.js'), 'serve'] };
+    return { ...command, ...(client === 'codex' ? { env_vars: ['AISA_API_KEY'] } : {}) };
+}
+const hash = (x) => createHash('sha256').update(x).digest('hex');
+async function read(file) { try {
+    return await fs.readFile(file, 'utf8');
+}
+catch (e) {
+    if (e.code === 'ENOENT')
+        return undefined;
+    throw e;
+} }
+async function noSymlinks(target) {
+    const full = path.resolve(target);
+    let cursor = path.parse(full).root;
+    for (const part of full.slice(cursor.length).split(path.sep)) {
+        cursor = path.join(cursor, part);
+        try {
+            if ((await fs.lstat(cursor)).isSymbolicLink())
+                throw Error(`Refusing symbolic link: ${cursor}`);
+        }
+        catch (e) {
+            if (e.code !== 'ENOENT')
+                throw e;
+        }
+    }
+}
+async function atomic(file, value) {
+    await noSymlinks(file);
+    await fs.mkdir(path.dirname(file), { recursive: true });
+    const tmp = `${file}.${randomUUID()}.tmp`;
+    try {
+        await fs.writeFile(tmp, value, { mode: 0o600, flag: 'wx' });
+        await fs.rename(tmp, file);
+    }
+    finally {
+        await fs.rm(tmp, { force: true });
+    }
+}
+function configFor(client, home) {
+    if (client === 'codex')
+        return { file: path.join(home, '.codex/config.toml'), key: 'mcp_servers', parse: (x) => TOML.parse(x), stringify: (x) => TOML.stringify(x) };
+    if (client === 'hermes')
+        return { file: path.join(home, '.hermes/config.yaml'), key: 'mcp_servers', parse: (x) => YAML.parse(x), stringify: (x) => YAML.stringify(x) };
+    return { file: path.join(home, '.claude.json'), key: 'mcpServers', parse: (x) => JSON.parse(x), stringify: (x) => JSON.stringify(x, null, 2) + '\n' };
+}
+function skillRoot(client, home) { return path.join(home, client === 'codex' ? '.agents/skills' : client === 'hermes' ? '.hermes/skills' : '.claude/skills', skillName); }
+async function skillFiles(root, prefix = '') {
+    const out = {};
+    for (const item of await fs.readdir(path.join(root, prefix), { withFileTypes: true })) {
+        const relative = path.join(prefix, item.name);
+        if (item.isSymbolicLink())
+            throw Error('Bundled skills must not contain symlinks.');
+        if (item.isDirectory())
+            Object.assign(out, await skillFiles(root, relative));
+        else
+            out[relative] = await fs.readFile(path.join(root, relative), 'utf8');
+    }
+    return out;
+}
+export async function install(client, options = {}) {
+    if (!['codex', 'claude-code', 'hermes'].includes(client))
+        throw Error('Choose --client codex, claude-code or hermes.');
+    const home = path.resolve(options.home ?? homedir());
+    const stateDir = path.join(home, '.aisa/web-market');
+    await noSymlinks(stateDir);
+    await fs.mkdir(stateDir, { recursive: true });
+    const lock = path.join(stateDir, 'install.lock');
+    let fd;
+    try {
+        fd = await fs.open(lock, 'wx', 0o600);
+    }
+    catch {
+        throw Error('Another setup is running. If it crashed, remove .aisa/web-market/install.lock after confirming no setup is active.');
+    }
+    try {
+        const stateFile = path.join(stateDir, `${client}.json`);
+        await noSymlinks(stateFile);
+        const previous = JSON.parse(await read(stateFile) ?? '{"files":{}}');
+        const cfg = configFor(client, home);
+        const root = skillRoot(client, home);
+        const entry = launchEntry(client);
+        const writes = new Map();
+        const next = { version: '0.1.0', files: {}, config: previous.config };
+        const bundled = await skillFiles(path.join(packageRoot, 'skills', skillName));
+        for (const relative of new Set([...Object.keys(bundled), ...Object.keys(previous.files)])) {
+            if (path.isAbsolute(relative) || relative.split(/[\\/]/).includes('..'))
+                throw Error('Invalid installer state path.');
+            const content = bundled[relative];
+            const file = path.join(root, relative);
+            await noSymlinks(file);
+            const current = await read(file);
+            if (options.remove || content === undefined) {
+                if (current !== undefined && previous.files[relative] === hash(current))
+                    writes.set(file, undefined);
+                else if (current !== undefined)
+                    throw Error(`Preserving modified or unowned skill: ${file}`);
+            }
+            else {
+                if (current !== undefined && previous.files[relative] !== hash(current))
+                    throw Error(`Preserving modified or unowned skill: ${file}`);
+                writes.set(file, content);
+                next.files[relative] = hash(content);
+            }
+        }
+        if (!options.skillsOnly && (!options.remove || previous.config)) {
+            await noSymlinks(cfg.file);
+            const current = await read(cfg.file);
+            let config;
+            try {
+                config = current?.trim() ? cfg.parse(current) : {};
+            }
+            catch {
+                throw Error('Client configuration could not be parsed; no files were changed.');
+            }
+            if (typeof config !== 'object' || Array.isArray(config))
+                throw Error('Invalid client configuration.');
+            config[cfg.key] ??= {};
+            if (typeof config[cfg.key] !== 'object' || Array.isArray(config[cfg.key]))
+                throw Error('Invalid MCP configuration section.');
+            const existing = config[cfg.key][skillName];
+            if (options.remove) {
+                if (existing && JSON.stringify(existing) !== JSON.stringify(previous.config))
+                    throw Error('MCP entry has been modified; preserving it.');
+                delete config[cfg.key][skillName];
+            }
+            else {
+                if (existing && JSON.stringify(existing) !== JSON.stringify(previous.config) && JSON.stringify(existing) !== JSON.stringify(entry))
+                    throw Error('An unowned aisa-web-market MCP entry already exists; preserving it.');
+                config[cfg.key][skillName] = entry;
+                next.config = entry;
+            }
+            writes.set(cfg.file, cfg.stringify(config));
+        }
+        writes.set(stateFile, options.remove ? undefined : JSON.stringify(next, null, 2));
+        const backups = new Map();
+        try {
+            for (const [file, content] of writes) {
+                backups.set(file, await read(file));
+                if (content === undefined)
+                    await fs.rm(file, { force: true });
+                else
+                    await atomic(file, content);
+            }
+        }
+        catch (e) {
+            for (const [file, old] of [...backups].reverse()) {
+                if (old === undefined)
+                    await fs.rm(file, { force: true });
+                else
+                    await atomic(file, old);
+            }
+            throw e;
+        }
+        return { client, skill: root, config: options.skillsOnly ? null : cfg.file, action: options.remove ? 'removed' : 'installed' };
+    }
+    finally {
+        await fd.close();
+        await fs.rm(lock, { force: true });
+    }
+}