cwtools-shared 0.1.0

package/dist/safety/paths.js

@@ -0,0 +1,122 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeWorkspaceRoot = normalizeWorkspaceRoot;
+exports.isPathInsideOrEqual = isPathInsideOrEqual;
+exports.resolveWorkspacePath = resolveWorkspacePath;
+exports.isLocalisationRelativePath = isLocalisationRelativePath;
+exports.isScratchRelativePath = isScratchRelativePath;
+exports.validateLocalisationPath = validateLocalisationPath;
+const path = __importStar(require("path"));
+function normalizeWorkspaceRoot(workspaceRoot) {
+    return path.resolve(workspaceRoot);
+}
+function isPathInsideOrEqual(parent, child) {
+    const relative = path.relative(path.resolve(parent), path.resolve(child));
+    return relative === '' || (!!relative && !relative.startsWith('..') && !path.isAbsolute(relative));
+}
+function resolveWorkspacePath(workspaceRoot, inputPath) {
+    const root = normalizeWorkspaceRoot(workspaceRoot);
+    const trimmed = inputPath.trim();
+    if (!trimmed) {
+        return { ok: false, input: inputPath, workspaceRoot: root, reason: 'empty_path' };
+    }
+    const resolved = path.resolve(root, trimmed);
+    if (!isPathInsideOrEqual(root, resolved)) {
+        return { ok: false, input: inputPath, workspaceRoot: root, reason: 'outside_workspace' };
+    }
+    return {
+        ok: true,
+        input: inputPath,
+        workspaceRoot: root,
+        resolvedPath: resolved,
+        relativePath: path.relative(root, resolved).replace(/\\/g, '/'),
+    };
+}
+function isLocalisationRelativePath(relativePath) {
+    const normalized = relativePath.replace(/\\/g, '/').toLowerCase();
+    return normalized.startsWith('localisation/')
+        || normalized.startsWith('localisation_synced/')
+        || normalized.startsWith('localization/');
+}
+function isScratchRelativePath(relativePath) {
+    const parts = relativePath
+        .replace(/\\/g, '/')
+        .toLowerCase()
+        .split('/');
+    return parts.includes('.cwtools') || parts.includes('.cwtools-ai');
+}
+function validateLocalisationPath(workspaceRoot, inputPath) {
+    const resolution = resolveWorkspacePath(workspaceRoot, inputPath);
+    if (!resolution.ok || !resolution.resolvedPath || !resolution.relativePath) {
+        return {
+            ok: false,
+            reason: 'outside_workspace',
+            message: `Path '${inputPath}' is outside the workspace root.`,
+        };
+    }
+    if (path.extname(resolution.resolvedPath).toLowerCase() !== '.yml') {
+        return {
+            ok: false,
+            reason: 'not_yml',
+            resolvedPath: resolution.resolvedPath,
+            relativePath: resolution.relativePath,
+            message: 'write_localisation only works with .yml files.',
+        };
+    }
+    if (isScratchRelativePath(resolution.relativePath)) {
+        return {
+            ok: false,
+            reason: 'scratch_path',
+            resolvedPath: resolution.resolvedPath,
+            relativePath: resolution.relativePath,
+            message: 'Localisation files must not be written under .cwtools scratch or topic folders.',
+        };
+    }
+    if (!isLocalisationRelativePath(resolution.relativePath)) {
+        return {
+            ok: false,
+            reason: 'not_localisation_directory',
+            resolvedPath: resolution.resolvedPath,
+            relativePath: resolution.relativePath,
+            message: 'Localisation files must be written under localisation/, localisation_synced/, or localization/.',
+        };
+    }
+    return {
+        ok: true,
+        resolvedPath: resolution.resolvedPath,
+        relativePath: resolution.relativePath,
+    };
+}

package/dist/safety/writes.d.ts

@@ -0,0 +1,3 @@
+import type { HostServices } from '../host/hostServices';
+import { type SharedToolResult } from '../tools/schema';
+export declare function ensureToolWriteAllowed(host: HostServices, toolName: string): SharedToolResult | null;

package/dist/safety/writes.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ensureToolWriteAllowed = ensureToolWriteAllowed;
+const schema_1 = require("../tools/schema");
+const names_1 = require("../tools/names");
+function ensureToolWriteAllowed(host, toolName) {
+    if (!(0, names_1.isMcpWriteToolName)(toolName))
+        return null;
+    if (host.readonlyMode) {
+        return (0, schema_1.toolDenied)('read_only', `${toolName} is disabled because the MCP server is running in read-only mode.`);
+    }
+    if (!host.writesEnabled) {
+        return (0, schema_1.toolDenied)('writes_disabled', `${toolName} requires --enable-writes.`);
+    }
+    if (host.allowedWriteTools && !host.allowedWriteTools.has(toolName)) {
+        return (0, schema_1.toolDenied)('tool_not_allowed', `${toolName} is not in the configured write-tool allowlist.`);
+    }
+    return null;
+}

package/dist/tools/mcpSchema.d.ts

@@ -0,0 +1,5 @@
+import type { GeneratedMcpTool, McpToolSchema } from './schema';
+export declare function getGeneratedMcpTools(): readonly GeneratedMcpTool[];
+export declare function listMcpToolSchemas(): McpToolSchema[];
+export declare function getMcpToolSchema(name: string): McpToolSchema | undefined;
+export declare function getMcpToolRegistryMetadata(name: string): GeneratedMcpTool['registry'] | undefined;

package/dist/tools/mcpSchema.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getGeneratedMcpTools = getGeneratedMcpTools;
+exports.listMcpToolSchemas = listMcpToolSchemas;
+exports.getMcpToolSchema = getMcpToolSchema;
+exports.getMcpToolRegistryMetadata = getMcpToolRegistryMetadata;
+const mcpTools_1 = require("../generated/mcpTools");
+function getGeneratedMcpTools() {
+    return mcpTools_1.GENERATED_MCP_TOOLS;
+}
+function listMcpToolSchemas() {
+    return mcpTools_1.GENERATED_MCP_TOOLS.map(entry => ({ ...entry.tool }));
+}
+function getMcpToolSchema(name) {
+    return mcpTools_1.GENERATED_MCP_TOOLS.find(entry => entry.tool.name === name)?.tool;
+}
+function getMcpToolRegistryMetadata(name) {
+    return mcpTools_1.GENERATED_MCP_TOOLS.find(entry => entry.registry.name === name)?.registry;
+}

package/dist/tools/names.d.ts

@@ -0,0 +1,6 @@
+export declare const MCP_TOOL_NAMES: readonly ["query_types", "query_rules", "query_cwt_schema", "search_rule_capabilities", "explain_scope", "parse_pdx_fragment", "query_scope", "get_diagnostics", "analyze_diagnostic_error", "query_project_profile", "query_project_knowledge", "query_workspace_index", "explore_pdx_project", "query_localisation_index", "get_pdx_block", "get_completion_at", "document_symbols", "workspace_symbols", "query_definition", "query_definition_by_name", "query_references", "query_scripted_effects", "query_scripted_triggers", "query_enums", "query_static_modifiers", "query_variables", "get_entity_info", "query_shader_symbol", "query_shader_compile_unit", "query_shader_platform_variants", "query_shader_callers", "explain_shader_reachability", "validate_shader", "compare_shader_with_vanilla"];
+export type McpToolName = typeof MCP_TOOL_NAMES[number];
+export declare const MCP_WRITE_TOOL_NAMES: readonly [];
+export declare const MCP_READONLY_TOOL_NAMES: readonly ["query_types", "query_rules", "query_cwt_schema", "search_rule_capabilities", "explain_scope", "parse_pdx_fragment", "query_scope", "get_diagnostics", "analyze_diagnostic_error", "query_project_profile", "query_project_knowledge", "query_workspace_index", "explore_pdx_project", "query_localisation_index", "get_pdx_block", "get_completion_at", "document_symbols", "workspace_symbols", "query_definition", "query_definition_by_name", "query_references", "query_scripted_effects", "query_scripted_triggers", "query_enums", "query_static_modifiers", "query_variables", "get_entity_info", "query_shader_symbol", "query_shader_compile_unit", "query_shader_platform_variants", "query_shader_callers", "explain_shader_reachability", "validate_shader", "compare_shader_with_vanilla"];
+export declare function isMcpToolName(value: string): value is McpToolName;
+export declare function isMcpWriteToolName(value: string): value is typeof MCP_WRITE_TOOL_NAMES[number];

package/dist/tools/names.js

@@ -0,0 +1,51 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MCP_READONLY_TOOL_NAMES = exports.MCP_WRITE_TOOL_NAMES = exports.MCP_TOOL_NAMES = void 0;
+exports.isMcpToolName = isMcpToolName;
+exports.isMcpWriteToolName = isMcpWriteToolName;
+exports.MCP_TOOL_NAMES = [
+    'query_types',
+    'query_rules',
+    'query_cwt_schema',
+    'search_rule_capabilities',
+    'explain_scope',
+    'parse_pdx_fragment',
+    'query_scope',
+    'get_diagnostics',
+    'analyze_diagnostic_error',
+    'query_project_profile',
+    'query_project_knowledge',
+    'query_workspace_index',
+    'explore_pdx_project',
+    'query_localisation_index',
+    'get_pdx_block',
+    'get_completion_at',
+    'document_symbols',
+    'workspace_symbols',
+    'query_definition',
+    'query_definition_by_name',
+    'query_references',
+    'query_scripted_effects',
+    'query_scripted_triggers',
+    'query_enums',
+    'query_static_modifiers',
+    'query_variables',
+    'get_entity_info',
+    'query_shader_symbol',
+    'query_shader_compile_unit',
+    'query_shader_platform_variants',
+    'query_shader_callers',
+    'explain_shader_reachability',
+    'validate_shader',
+    'compare_shader_with_vanilla',
+];
+// The MCP surface is read-only by design: file writes go through the host agent's
+// own environment (Codex / Claude Code), not through this server.
+exports.MCP_WRITE_TOOL_NAMES = [];
+exports.MCP_READONLY_TOOL_NAMES = exports.MCP_TOOL_NAMES;
+function isMcpToolName(value) {
+    return exports.MCP_TOOL_NAMES.includes(value);
+}
+function isMcpWriteToolName(value) {
+    return exports.MCP_WRITE_TOOL_NAMES.includes(value);
+}

package/dist/tools/pdxBlock.d.ts

@@ -0,0 +1,17 @@
+import type { HostServices } from '../host/hostServices';
+import { type SharedToolResult } from './schema';
+export interface GetPdxBlockArgs {
+    file: string;
+    symbol: string;
+}
+export interface GetPdxBlockResult {
+    content: string;
+    truncated: boolean;
+    startLine?: number;
+    endLine?: number;
+    lineNumberBase: 1;
+    source: 'cwtools-lsp-symbols' | 'cwtools-node-block';
+    warnings?: string[];
+    error?: string;
+}
+export declare function getPdxBlockWithHost(host: HostServices, args: GetPdxBlockArgs): Promise<SharedToolResult<GetPdxBlockResult>>;

package/dist/tools/pdxBlock.js

@@ -0,0 +1,140 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getPdxBlockWithHost = getPdxBlockWithHost;
+const paths_1 = require("../safety/paths");
+const schema_1 = require("./schema");
+const symbols_1 = require("./symbols");
+async function getPdxBlockWithHost(host, args) {
+    const resolution = (0, paths_1.resolveWorkspacePath)(host.workspaceRoot, args.file);
+    if (!resolution.ok || !resolution.resolvedPath) {
+        return (0, schema_1.toolDenied)('outside_workspace', `Path '${args.file}' is outside the workspace root.`);
+    }
+    const read = await host.filesystem.readTextFile(resolution.resolvedPath);
+    if (!read.exists) {
+        return {
+            ok: false,
+            status: 'error',
+            source: 'cwtools-node-block',
+            error: { code: 'file_not_found', message: `File not found: ${args.file}` },
+        };
+    }
+    const content = read.hasBom ? read.content.slice(1) : read.content;
+    const lines = content.split(/\r?\n/);
+    const symbolRange = await resolveSymbolRange(host, resolution.resolvedPath, args.symbol);
+    const startLine = symbolRange?.startLine ?? findBlockStart(lines, args.symbol);
+    if (startLine === undefined) {
+        return {
+            ok: false,
+            status: 'error',
+            source: 'cwtools-node-block',
+            error: { code: 'symbol_not_found', message: `Symbol '${args.symbol}' not found in file.` },
+            data: {
+                content: `Error: Symbol '${args.symbol}' not found in file.`,
+                truncated: false,
+                lineNumberBase: 1,
+                source: 'cwtools-node-block',
+                error: `Symbol '${args.symbol}' not found in file.`,
+            },
+        };
+    }
+    const endLine = symbolRange?.endLine ?? findBlockEnd(lines, startLine);
+    const blockLines = lines.slice(startLine, endLine + 1);
+    const fullText = blockLines.join('\n');
+    const maxChars = 16000;
+    const truncated = fullText.length > maxChars;
+    const source = symbolRange?.source === 'cwtools-lsp-symbols' ? 'cwtools-lsp-symbols' : 'cwtools-node-block';
+    return {
+        ok: true,
+        status: 'ready',
+        source,
+        data: {
+            content: truncated ? `${fullText.slice(0, maxChars)}\n... [Block truncated due to size]` : fullText,
+            truncated,
+            startLine: startLine + 1,
+            endLine: endLine + 1,
+            lineNumberBase: 1,
+            source,
+            warnings: source === 'cwtools-node-block'
+                ? ['LSP document symbols were unavailable or did not contain this symbol; block boundaries were inferred in Node.']
+                : undefined,
+        },
+    };
+}
+async function resolveSymbolRange(host, file, symbolName) {
+    const symbolsResult = await (0, symbols_1.documentSymbolsWithHost)(host, { file }).catch(() => undefined);
+    const symbol = symbolsResult?.data ? findSymbol(symbolsResult.data.symbols, symbolName) : undefined;
+    if (!symbol)
+        return undefined;
+    return {
+        startLine: symbol.range.startLine,
+        endLine: symbol.range.endLine,
+        source: symbolsResult.source,
+    };
+}
+function findSymbol(symbols, targetName) {
+    for (const symbol of symbols) {
+        if (symbol.name === targetName)
+            return symbol;
+        const child = symbol.children ? findSymbol(symbol.children, targetName) : undefined;
+        if (child)
+            return child;
+    }
+    return undefined;
+}
+function findBlockStart(lines, symbol) {
+    const escaped = escapeRegExp(symbol);
+    const topLevelPattern = new RegExp(`^\\s*${escaped}\\s*=`);
+    const idPattern = new RegExp(`\\bid\\s*=\\s*"?${escaped}"?\\b`);
+    for (let index = 0; index < lines.length; index++) {
+        const line = lines[index] ?? '';
+        if (topLevelPattern.test(line))
+            return index;
+        if (idPattern.test(line)) {
+            for (let back = index; back >= 0; back--) {
+                if (/\w+\s*=\s*\{/.test(lines[back] ?? ''))
+                    return back;
+            }
+            return index;
+        }
+    }
+    return undefined;
+}
+function findBlockEnd(lines, startLine) {
+    let depth = 0;
+    let sawOpen = false;
+    for (let index = startLine; index < lines.length; index++) {
+        const counts = countBraces(lines[index] ?? '');
+        depth += counts.open - counts.close;
+        sawOpen || (sawOpen = counts.open > 0);
+        if (sawOpen && depth <= 0)
+            return index;
+    }
+    return startLine;
+}
+function countBraces(line) {
+    let open = 0;
+    let close = 0;
+    let inString = false;
+    let escaped = false;
+    for (let index = 0; index < line.length; index++) {
+        const char = line[index];
+        if (!inString && char === '#')
+            break;
+        if (char === '"' && !escaped) {
+            inString = !inString;
+        }
+        else if (!inString && char === '{') {
+            open++;
+        }
+        else if (!inString && char === '}') {
+            close++;
+        }
+        escaped = char === '\\' && !escaped;
+        if (char !== '\\')
+            escaped = false;
+    }
+    return { open, close };
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}

package/dist/tools/registry.d.ts

@@ -0,0 +1,10 @@
+export type ToolEffect = 'none' | 'memory' | 'workspace_read' | 'workspace_write' | 'network' | 'shell' | 'git' | 'media' | 'mcp';
+export type ToolConcurrencyClass = 'parallel' | 'lsp-limited' | 'network-limited' | 'per-file-write' | 'global-exclusive' | 'interactive';
+export interface ToolRegistryMetadata {
+    name: string;
+    isWrite: boolean;
+    isReadOnly: boolean;
+    effect: ToolEffect;
+    riskLevel: 0 | 1 | 2 | 3;
+    concurrencyClass: ToolConcurrencyClass;
+}

package/dist/tools/registry.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/tools/schema.d.ts

@@ -0,0 +1,36 @@
+import type { ToolRegistryMetadata } from './registry';
+export type JsonObject = Record<string, unknown>;
+export interface ToolDefinition {
+    type: 'function';
+    function: {
+        name: string;
+        description: string;
+        parameters: JsonObject;
+    };
+}
+export interface McpToolSchema {
+    name: string;
+    description: string;
+    inputSchema: JsonObject;
+}
+export interface GeneratedMcpTool {
+    tool: McpToolSchema;
+    registry: ToolRegistryMetadata;
+}
+export interface SharedToolError {
+    code: string;
+    message: string;
+}
+export interface SharedToolResult<T = unknown> {
+    ok: boolean;
+    status: 'ready' | 'partial' | 'success' | 'denied' | 'loading' | 'stale' | 'unavailable' | 'error';
+    source: string;
+    data?: T;
+    error?: SharedToolError;
+    warnings?: string[];
+    nextSteps?: string[];
+    vanillaCache?: import('../host/vanillaCache').VanillaCacheStatus;
+    readiness?: import('../host/readiness').LspReadiness;
+}
+export declare function toolUnavailable(tool: string, message: string, nextSteps?: string[]): SharedToolResult;
+export declare function toolDenied(code: string, message: string): SharedToolResult;

package/dist/tools/schema.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toolUnavailable = toolUnavailable;
+exports.toolDenied = toolDenied;
+function toolUnavailable(tool, message, nextSteps = []) {
+    return {
+        ok: false,
+        status: 'unavailable',
+        source: 'cwtools-shared',
+        error: { code: 'unavailable', message },
+        nextSteps,
+    };
+}
+function toolDenied(code, message) {
+    return {
+        ok: false,
+        status: 'denied',
+        source: 'cwtools-shared',
+        error: { code, message },
+    };
+}

package/dist/tools/symbols.d.ts

@@ -0,0 +1,60 @@
+import type { HostServices } from '../host/hostServices';
+import { type SharedToolResult } from './schema';
+export interface DocumentSymbolInfo {
+    name: string;
+    kind: string;
+    range: {
+        startLine: number;
+        endLine: number;
+        startColumn?: number;
+        endColumn?: number;
+    };
+    children?: DocumentSymbolInfo[];
+    _hasDeeper?: boolean;
+}
+export interface WorkspaceSymbolInfo {
+    name: string;
+    kind: string;
+    file: string;
+    line: number;
+    column?: number;
+    containerName?: string;
+    source?: string;
+}
+export type SymbolOrigin = 'workspace' | 'vanilla' | 'generated' | 'external';
+export declare function getCompletionAtWithHost(host: HostServices, args: {
+    file: string;
+    line: number;
+    column: number;
+    limit?: number;
+}): Promise<SharedToolResult>;
+export declare function documentSymbolsWithHost(host: HostServices, args: {
+    file: string;
+}): Promise<SharedToolResult<{
+    symbols: DocumentSymbolInfo[];
+    lineNumberBase: 0;
+    source: string;
+    warnings?: string[];
+}>>;
+export declare function workspaceSymbolsWithHost(host: HostServices, args: {
+    query: string;
+    limit?: number;
+}): Promise<SharedToolResult<{
+    symbols: WorkspaceSymbolInfo[];
+    source: string;
+    warnings?: string[];
+}>>;
+export declare function queryDefinitionWithHost(host: HostServices, args: {
+    file: string;
+    line: number;
+    column: number;
+}): Promise<SharedToolResult>;
+export declare function queryDefinitionByNameWithHost(host: HostServices, args: {
+    symbolName: string;
+}): Promise<SharedToolResult>;
+export declare function queryReferencesWithHost(host: HostServices, args: {
+    identifier: string;
+    file?: string;
+    limit?: number;
+}): Promise<SharedToolResult>;
+export declare function inferDocumentSymbolsFromText(content: string): DocumentSymbolInfo[];