@jshookmcp/jshook 0.2.2 → 0.2.5

package/dist/src/server/domains/maintenance/definitions.js

@@ -1,227 +1,68 @@
+import { tool } from '../../registry/tool-builder.js';
 export const tokenBudgetTools = [
-    {
-        name: 'get_token_budget_stats',
-        description: 'Get current token budget usage statistics.\n\n' +
-            'Returns current consumption, tool call counts, top consumers, warnings, and optimization suggestions. ' +
-            'Use manual_token_cleanup when usage exceeds 20-30%.',
-        inputSchema: {
-            type: 'object',
-            properties: {},
-        },
-        annotations: {
-            readOnlyHint: true,
-            destructiveHint: false,
-            idempotentHint: true,
-            openWorldHint: false,
-        },
-    },
-    {
-        name: 'manual_token_cleanup',
-        description: 'Trigger token budget cleanup to free context space. ' +
-            'Clears stale entries older than 5 minutes and resets counters. ' +
-            'Frees 10-30% of token budget while preserving recent data.',
-        inputSchema: {
-            type: 'object',
-            properties: {},
-        },
-        annotations: {
-            readOnlyHint: false,
-            destructiveHint: false,
-            idempotentHint: false,
-            openWorldHint: false,
-        },
-    },
-    {
-        name: 'reset_token_budget',
-        description: 'Hard-reset all token budget counters to zero. Destructive: clears all tracking history. ' +
-            'Only use when MCP session state is corrupted. Prefer manual_token_cleanup for routine cleanup.',
-        inputSchema: {
-            type: 'object',
-            properties: {},
-        },
-        annotations: {
-            readOnlyHint: false,
-            destructiveHint: true,
-            idempotentHint: false,
-            openWorldHint: false,
-        },
-    },
+    tool('get_token_budget_stats')
+        .desc('Get token budget usage stats, warnings, and optimization suggestions')
+        .readOnly()
+        .idempotent()
+        .build(),
+    tool('manual_token_cleanup')
+        .desc('Clear stale entries and reset counters to free 10-30% of token budget')
+        .build(),
+    tool('reset_token_budget')
+        .desc('Hard-reset all token budget counters. Destructive — prefer manual_token_cleanup')
+        .destructive()
+        .build(),
 ];
 export const extensionTools = [
-    {
-        name: 'list_extensions',
-        description: 'List all locally loaded plugins, workflows, and extension tools with their details.',
-        inputSchema: {
-            type: 'object',
-            properties: {},
-        },
-        annotations: {
-            readOnlyHint: true,
-            destructiveHint: false,
-            idempotentHint: true,
-            openWorldHint: false,
-        },
-    },
-    {
-        name: 'reload_extensions',
-        description: 'Reload all plugins and workflows from configured directories. ' +
-            'Dynamically registers extension tools and refreshes tool list.',
-        inputSchema: {
-            type: 'object',
-            properties: {},
-        },
-        annotations: {
-            readOnlyHint: false,
-            destructiveHint: false,
-            idempotentHint: false,
-            openWorldHint: true,
-        },
-    },
-    {
-        name: 'browse_extension_registry',
-        description: 'Browse the remote jshookmcp extension registry to discover available plugins and workflows.',
-        inputSchema: {
-            type: 'object',
-            properties: {
-                kind: {
-                    type: 'string',
-                    enum: ['plugin', 'workflow', 'all'],
-                    description: 'Filter by extension kind (default: "all")',
-                },
-            },
-        },
-        annotations: {
-            readOnlyHint: true,
-            destructiveHint: false,
-            idempotentHint: true,
-            openWorldHint: false,
-        },
-    },
-    {
-        name: 'install_extension',
-        description: 'Install an extension from the remote registry. Clones the repo, checks out the pinned commit, ' +
-            'and runs reload_extensions to activate. Requires git in PATH.',
-        inputSchema: {
-            type: 'object',
-            properties: {
-                slug: {
-                    type: 'string',
-                    description: 'Extension slug from the registry (e.g. "ida-bridge")',
-                },
-                targetDir: {
-                    type: 'string',
-                    description: 'Target directory override (optional, defaults to jshook install plugins/workflows root + slug)',
-                },
-            },
-            required: ['slug'],
-        },
-        annotations: {
-            readOnlyHint: false,
-            destructiveHint: false,
-            idempotentHint: false,
-            openWorldHint: true,
-        },
-    },
+    tool('list_extensions')
+        .desc('List all loaded plugins, workflows, and extension tools')
+        .readOnly()
+        .idempotent()
+        .build(),
+    tool('reload_extensions')
+        .desc('Reload plugins and workflows from configured directories')
+        .openWorld()
+        .build(),
+    tool('browse_extension_registry')
+        .desc('Browse the remote jshookmcp extension registry')
+        .enum('kind', ['plugin', 'workflow', 'all'], 'Filter by extension kind', { default: 'all' })
+        .readOnly()
+        .idempotent()
+        .build(),
+    tool('install_extension')
+        .desc('Install an extension from the remote registry via git')
+        .string('slug', 'Extension slug from the registry')
+        .string('targetDir', 'Target directory override')
+        .required('slug')
+        .openWorld()
+        .build(),
 ];
 export const cacheTools = [
-    {
-        name: 'get_cache_stats',
-        description: 'Get cache statistics for all internal caches. ' +
-            'Returns total entries, sizes, per-cache hit rates, TTL config, and cleanup recommendations.',
-        inputSchema: {
-            type: 'object',
-            properties: {},
-        },
-        annotations: {
-            readOnlyHint: true,
-            destructiveHint: false,
-            idempotentHint: true,
-            openWorldHint: false,
-        },
-    },
-    {
-        name: 'smart_cache_cleanup',
-        description: 'Intelligently clean caches to free memory while preserving hot data. ' +
-            'Evicts LRU entries, removes low-hit entries, and clears entries older than 2 hours.',
-        inputSchema: {
-            type: 'object',
-            properties: {
-                targetSize: {
-                    type: 'number',
-                    description: 'Target size in bytes (optional, defaults to 70% of maximum).',
-                },
-            },
-        },
-        annotations: {
-            readOnlyHint: false,
-            destructiveHint: false,
-            idempotentHint: false,
-            openWorldHint: false,
-        },
-    },
-    {
-        name: 'clear_all_caches',
-        description: 'Clear all internal caches completely. Destructive: all cached data will be lost. ' +
-            'Prefer smart_cache_cleanup for routine maintenance.',
-        inputSchema: {
-            type: 'object',
-            properties: {},
-        },
-        annotations: {
-            readOnlyHint: false,
-            destructiveHint: true,
-            idempotentHint: false,
-            openWorldHint: false,
-        },
-    },
+    tool('get_cache_stats')
+        .desc('Get cache statistics: entries, sizes, hit rates, and cleanup recommendations')
+        .readOnly()
+        .idempotent()
+        .build(),
+    tool('smart_cache_cleanup')
+        .desc('Evict LRU and stale entries while preserving hot data')
+        .number('targetSize', 'Target size in bytes')
+        .build(),
+    tool('clear_all_caches')
+        .desc('Clear all internal caches. Destructive — prefer smart_cache_cleanup')
+        .destructive()
+        .build(),
 ];
 export const artifactTools = [
-    {
-        name: 'cleanup_artifacts',
-        description: 'Clean generated artifacts, screenshots, and debugger sessions using retention rules. ' +
-            'Supports age-based removal, size-based trimming, and dry-run preview.',
-        inputSchema: {
-            type: 'object',
-            properties: {
-                retentionDays: {
-                    type: 'number',
-                    description: 'Override retention window in days for this cleanup run.',
-                },
-                maxTotalBytes: {
-                    type: 'number',
-                    description: 'Override maximum retained bytes across managed artifact directories.',
-                },
-                dryRun: {
-                    type: 'boolean',
-                    description: 'Preview removals without deleting files.',
-                },
-            },
-        },
-        annotations: {
-            readOnlyHint: false,
-            destructiveHint: true,
-            idempotentHint: false,
-            openWorldHint: false,
-        },
-    },
-    {
-        name: 'doctor_environment',
-        description: 'Run an environment doctor for optional dependencies, bridge endpoints, and platform limitations. ' +
-            'Use before debugging dependency issues or after installing external integrations.',
-        inputSchema: {
-            type: 'object',
-            properties: {
-                includeBridgeHealth: {
-                    type: 'boolean',
-                    description: 'When true, probe local native-bridge / Burp endpoints as part of the report.',
-                },
-            },
-        },
-        annotations: {
-            readOnlyHint: true,
-            destructiveHint: false,
-            idempotentHint: false,
-            openWorldHint: false,
-        },
-    },
+    tool('cleanup_artifacts')
+        .desc('Clean generated artifacts using age and size retention rules')
+        .number('retentionDays', 'Override retention window in days')
+        .number('maxTotalBytes', 'Override maximum retained bytes')
+        .boolean('dryRun', 'Preview removals without deleting')
+        .destructive()
+        .build(),
+    tool('doctor_environment')
+        .desc('Run environment doctor for dependencies, bridge endpoints, and platform limitations')
+        .boolean('includeBridgeHealth', 'Probe native-bridge / Burp endpoints')
+        .readOnly()
+        .build(),
 ];

package/dist/src/server/domains/maintenance/handlers.d.ts

@@ -1,5 +1,5 @@
-import { TokenBudgetManager } from '../../../utils/TokenBudgetManager.js';
-import { UnifiedCacheManager } from '../../../utils/UnifiedCacheManager.js';
+import { type TokenBudgetManager } from '../../../utils/TokenBudgetManager.js';
+import { type UnifiedCacheManager } from '../../../utils/UnifiedCacheManager.js';
 import type { ToolResponse } from '../../types.js';
 import { cleanupArtifacts } from '../../../utils/artifactRetention.js';
 import { runEnvironmentDoctor } from '../../../utils/environmentDoctor.js';

package/dist/src/server/domains/maintenance/handlers.extensions.js

@@ -2,16 +2,16 @@ import { execFile } from 'node:child_process';
 import { existsSync } from 'node:fs';
 import { mkdir, readFile, writeFile } from 'node:fs/promises';
 import { homedir } from 'node:os';
-import { dirname, relative, resolve } from 'node:path';
+import { dirname, isAbsolute, relative, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { promisify } from 'node:util';
 import { logger } from '../../../utils/logger.js';
 import { EXTENSION_GIT_CLONE_TIMEOUT_MS, EXTENSION_GIT_CHECKOUT_TIMEOUT_MS } from '../../../constants.js';
+import { INSTALLED_EXTENSION_METADATA_FILENAME, } from '../../extensions/types.js';
 import { asJsonResponse, serializeError } from '../../domains/shared/response.js';
 const execFileAsync = promisify(execFile);
 function getJshookInstallRoot() {
-    const currentFile = fileURLToPath(import.meta.url);
-    return resolve(dirname(currentFile), '..', '..', '..', '..');
+    return fileURLToPath(new URL('../../../../', import.meta.url));
 }
 function parseFirstRoot(raw) {
     const value = raw?.trim();
@@ -38,6 +38,53 @@ function getRegistryBaseUrl() {
     }
     return baseUrl;
 }
+function normalizeInstallPathSegment(value, field) {
+    const normalized = value?.trim();
+    if (!normalized) {
+        if (field === 'subpath') {
+            return '.';
+        }
+        throw new Error(`Registry source.${field} must be a non-empty string`);
+    }
+    return normalized;
+}
+function ensurePathStaysWithin(baseDir, targetPath, field) {
+    const rel = relative(baseDir, targetPath).replace(/\\/g, '/');
+    if (rel === '..' || rel.startsWith('../') || isAbsolute(rel)) {
+        throw new Error(`Registry source.${field} must stay within ${baseDir}: ${targetPath}`);
+    }
+}
+function resolveExtensionProjectDir(installDir, subpath) {
+    const normalizedSubpath = normalizeInstallPathSegment(subpath, 'subpath');
+    const projectDir = resolve(installDir, normalizedSubpath);
+    ensurePathStaysWithin(installDir, projectDir, 'subpath');
+    return projectDir;
+}
+function resolveExtensionEntryFile(projectDir, entryPath) {
+    const normalizedEntry = normalizeInstallPathSegment(entryPath, 'entry');
+    const resolvedEntryFile = resolve(projectDir, normalizedEntry);
+    ensurePathStaysWithin(projectDir, resolvedEntryFile, 'entry');
+    return resolvedEntryFile;
+}
+async function writeInstalledExtensionMetadata(kind, entry, projectDir) {
+    const payload = {
+        version: 1,
+        kind,
+        slug: entry.slug,
+        id: entry.id,
+        source: {
+            type: entry.source.type,
+            repo: entry.source.repo,
+            ref: entry.source.ref,
+            commit: entry.source.commit,
+            subpath: normalizeInstallPathSegment(entry.source.subpath, 'subpath'),
+            entry: normalizeInstallPathSegment(entry.source.entry, 'entry'),
+        },
+    };
+    const metadataPath = resolve(projectDir, INSTALLED_EXTENSION_METADATA_FILENAME);
+    await writeFile(metadataPath, `${JSON.stringify(payload, null, 2)}\n`, 'utf8');
+    return metadataPath;
+}
 const LOCAL_EXTENSION_SDK_PACKAGE = '@jshookmcp/extension-sdk';
 const LOCAL_EXTENSION_SDK_ROOT = resolve(getJshookInstallRoot(), 'packages', 'extension-sdk');
 var RegistryLimit;
@@ -60,13 +107,13 @@ class RegistryFetchError extends Error {
     }
 }
 function resolvePackageManagerInvocation(packageManager, args) {
-    if (process.platform === 'win32') {
-        return {
-            command: 'powershell.exe',
-            args: ['-NoProfile', '-NonInteractive', '-Command', `${packageManager} ${args.join(' ')}`],
-        };
+    if (process.platform !== 'win32') {
+        return { command: packageManager, args };
     }
-    return { command: packageManager, args };
+    return {
+        command: 'powershell.exe',
+        args: ['-NoProfile', '-NonInteractive', '-Command', `${packageManager} ${args.join(' ')}`],
+    };
 }
 async function execPackageManager(packageManager, args, options) {
     const invocation = resolvePackageManagerInvocation(packageManager, args);
@@ -201,9 +248,6 @@ async function fetchJson(url, options) {
 }
 async function rewriteLocalExtensionSdkDependency(installDir) {
     const packageJsonPath = resolve(installDir, 'package.json');
-    if (!existsSync(packageJsonPath)) {
-        return false;
-    }
     try {
         const raw = await readFile(packageJsonPath, 'utf8');
         const pkg = JSON.parse(raw);
@@ -388,6 +432,8 @@ export class ExtensionManagementHandlers {
             const isWorkflow = kind === 'workflow';
             const defaultRoot = resolveDefaultExtensionRoot(isWorkflow ? 'workflow' : 'plugin');
             const installDir = targetDir ? resolve(targetDir) : resolve(defaultRoot, slug);
+            const projectDir = resolveExtensionProjectDir(installDir, entry.source.subpath);
+            const entryFile = resolveExtensionEntryFile(projectDir, entry.source.entry);
             if (existsSync(installDir)) {
                 return asJsonResponse({
                     success: false,
@@ -402,25 +448,36 @@ export class ExtensionManagementHandlers {
             await execFileAsync('git', ['-C', installDir, 'checkout', entry.source.commit], {
                 timeout: EXTENSION_GIT_CHECKOUT_TIMEOUT_MS,
             });
-            const packageJsonPath = resolve(installDir, 'package.json');
+            const packageJsonPath = resolve(projectDir, 'package.json');
             if (existsSync(packageJsonPath)) {
-                await rewriteLocalExtensionSdkDependency(installDir);
-                const packageManager = await resolvePackageManager(installDir);
+                await rewriteLocalExtensionSdkDependency(projectDir);
+                const packageManager = await resolvePackageManager(projectDir);
                 const installArgs = packageManager === 'pnpm'
                     ? ['--ignore-workspace', 'install', '--no-frozen-lockfile']
                     : ['install'];
                 await execPackageManager(packageManager, installArgs, {
-                    cwd: installDir,
+                    cwd: projectDir,
                     timeout: Math.max(EXTENSION_GIT_CLONE_TIMEOUT_MS, 120_000),
                 });
                 const buildArgs = packageManager === 'pnpm'
                     ? ['--ignore-workspace', 'run', '--if-present', 'build']
                     : ['run', 'build', '--if-present'];
                 await execPackageManager(packageManager, buildArgs, {
-                    cwd: installDir,
+                    cwd: projectDir,
                     timeout: Math.max(EXTENSION_GIT_CLONE_TIMEOUT_MS, 120_000),
                 });
             }
+            if (!existsSync(entryFile)) {
+                return asJsonResponse({
+                    success: false,
+                    error: `Installed extension entry not found: ${entry.source.entry}`,
+                    installDir,
+                    projectDir,
+                    expectedEntryFile: entryFile,
+                    hint: 'The registry source.entry must exist after clone/build before reloadExtensions can load it.',
+                });
+            }
+            const metadataPath = await writeInstalledExtensionMetadata(isWorkflow ? 'workflow' : 'plugin', entry, projectDir);
             const reloadResult = await this.ctx.reloadExtensions();
             return asJsonResponse({
                 success: true,
@@ -431,6 +488,10 @@ export class ExtensionManagementHandlers {
                     repo: entry.source.repo,
                     commit: entry.source.commit,
                     installDir,
+                    projectDir,
+                    entry: entry.source.entry,
+                    entryFile,
+                    metadataPath,
                 },
                 reload: {
                     addedTools: reloadResult.addedTools,
@@ -443,9 +504,6 @@ export class ExtensionManagementHandlers {
         }
         catch (error) {
             logger.error('Failed to install extension:', error);
-            if (error instanceof RegistryFetchError) {
-                return asJsonResponse(serializeRegistryFetchError(error));
-            }
             return asJsonResponse(serializeError(error));
         }
     }

package/dist/src/server/domains/maintenance/handlers.js

@@ -1,6 +1,6 @@
 import { logger } from '../../../utils/logger.js';
-import { TokenBudgetManager } from '../../../utils/TokenBudgetManager.js';
-import { UnifiedCacheManager } from '../../../utils/UnifiedCacheManager.js';
+import {} from '../../../utils/TokenBudgetManager.js';
+import {} from '../../../utils/UnifiedCacheManager.js';
 import { asJsonResponse, serializeError } from '../../domains/shared/response.js';
 import { cleanupArtifacts } from '../../../utils/artifactRetention.js';
 import { runEnvironmentDoctor } from '../../../utils/environmentDoctor.js';