cwtools-shared 0.1.0

package/dist/knowledge/workflowHints.d.ts

@@ -0,0 +1,11 @@
+export interface WorkflowHint {
+    id: string;
+    title: string;
+    triggers: string[];
+    recommendedTools: string[];
+    guardrails: string[];
+}
+export declare function queryWorkflowHints(): {
+    status: 'ready';
+    hints: WorkflowHint[];
+};

package/dist/knowledge/workflowHints.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.queryWorkflowHints = queryWorkflowHints;
+function queryWorkflowHints() {
+    return {
+        status: 'ready',
+        hints: [
+            {
+                id: 'diagnostic-fix',
+                title: 'Fix CWTools diagnostics',
+                triggers: ['diagnostic', 'error', 'warning'],
+                recommendedTools: ['get_diagnostics', 'analyze_diagnostic_error', 'get_pdx_block', 'query_cwt_schema', 'query_rules'],
+                guardrails: ['Verify after writes.', 'Do not suppress diagnostics instead of fixing them.'],
+            },
+            {
+                id: 'loc-generation',
+                title: 'Generate or update localisation',
+                triggers: ['localisation', 'localization', 'translation'],
+                recommendedTools: ['query_localisation_index', 'write_localisation'],
+                guardrails: ['Do not write .yml files through generic file tools.', 'Preserve language header and BOM.'],
+            },
+            {
+                id: 'entity-lookup',
+                title: 'Verify game identifiers',
+                triggers: ['identifier', 'reference', 'definition', 'entity'],
+                recommendedTools: ['query_project_knowledge', 'explore_pdx_project', 'query_cwt_schema', 'search_rule_capabilities', 'query_rules', 'query_types', 'query_workspace_index', 'query_definition_by_name'],
+                guardrails: ['Treat empty text search results as inconclusive without indexed verification.', 'Treat semanticHints as retrieval hints, not legality proof.'],
+            },
+        ],
+    };
+}

package/dist/project/knowledge.d.ts

@@ -0,0 +1,15 @@
+import type { HostServices } from '../host/hostServices';
+import type { SharedToolResult } from '../tools/schema';
+export interface QueryProjectKnowledgeArgs {
+    intent?: string;
+    domains?: string[];
+    identifiers?: string[];
+    entityTypes?: string[];
+    includeProjectPatterns?: boolean;
+    includeVanillaArchetypes?: boolean;
+    includeTopology?: boolean;
+    includeUnresolved?: boolean;
+    includeEventGraph?: boolean;
+    limit?: number;
+}
+export declare function queryProjectKnowledgeWithHost(host: HostServices, args?: QueryProjectKnowledgeArgs): Promise<SharedToolResult>;

package/dist/project/knowledge.js

@@ -0,0 +1,209 @@
+"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.queryProjectKnowledgeWithHost = queryProjectKnowledgeWithHost;
+const path = __importStar(require("path"));
+const KNOWLEDGE_DIR = path.join('.cwtools', 'project', 'knowledge');
+function asRecord(value) {
+    return value && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : {};
+}
+function stringArray(value) {
+    return Array.isArray(value) ? value.filter((item) => typeof item === 'string') : [];
+}
+function tokensFor(args) {
+    return [args.intent ?? '', ...(args.identifiers ?? []), ...(args.entityTypes ?? [])]
+        .join(' ')
+        .toLowerCase()
+        .match(/[@a-z0-9_.:-]{2,}/g)
+        ?.slice(0, 30) ?? [];
+}
+function score(value, tokens) {
+    if (tokens.length === 0)
+        return 1;
+    const text = JSON.stringify(value).toLowerCase();
+    return tokens.reduce((total, token) => total + (text.includes(token) ? 3 : 0), 0);
+}
+async function readJson(host, filePath) {
+    const read = await host.filesystem.readTextFile(filePath);
+    if (!read.exists)
+        return undefined;
+    try {
+        return asRecord(JSON.parse(read.content));
+    }
+    catch {
+        return undefined;
+    }
+}
+async function queryProjectKnowledgeWithHost(host, args = {}) {
+    let root = path.join(host.workspaceRoot, KNOWLEDGE_DIR);
+    let manifestPath = path.join(root, 'manifest.json');
+    let manifest = await readJson(host, manifestPath);
+    if (!manifest) {
+        const legacyRoot = path.join(host.workspaceRoot, '.cwtools-ai', 'project', 'knowledge');
+        const legacyManifestPath = path.join(legacyRoot, 'manifest.json');
+        const legacyManifest = await readJson(host, legacyManifestPath);
+        if (legacyManifest) {
+            root = legacyRoot;
+            manifestPath = legacyManifestPath;
+            manifest = legacyManifest;
+        }
+    }
+    if (!manifest) {
+        return {
+            ok: false,
+            status: 'unavailable',
+            source: 'cwtools-project-knowledge',
+            error: { code: 'knowledge_missing', message: 'Project knowledge pack is missing.' },
+            data: {
+                status: 'missing',
+                manifestPath,
+                domains: [],
+                evidence: [],
+                unresolved: [],
+                _hint: 'Run /init in the VS Code extension and wait for the deep semantic phase to complete.',
+            },
+        };
+    }
+    if (Number(manifest.schemaVersion) >= 2) {
+        const database = asRecord(manifest.database);
+        const relativeDatabasePath = typeof database.path === 'string' && database.path.trim()
+            ? database.path
+            : 'knowledge.sqlite';
+        const databasePath = path.resolve(root, relativeDatabasePath);
+        const relative = path.relative(root, databasePath);
+        if (relative.startsWith('..') || path.isAbsolute(relative)) {
+            return {
+                ok: false,
+                status: 'error',
+                source: 'cwtools-project-knowledge-sqlite',
+                error: { code: 'invalid_database_path', message: 'Project knowledge database path escapes the knowledge directory.' },
+            };
+        }
+        const result = asRecord(await host.lsp.executeCommand('cwtools.ai.queryProjectKnowledgeDb', [{ databasePath, ...args, includeEventGraph: args.includeEventGraph !== false }], { timeoutMs: 30000 }));
+        if (result.ok !== true) {
+            return {
+                ok: false,
+                status: 'error',
+                source: 'cwtools-project-knowledge-sqlite',
+                error: {
+                    code: 'knowledge_query_failed',
+                    message: typeof result.error === 'string' ? result.error : 'Project knowledge SQLite query failed.',
+                },
+                data: { manifestPath, databasePath },
+            };
+        }
+        const manifestStatus = String(manifest.status ?? 'stale');
+        const staleReasons = stringArray(manifest.staleReasons);
+        const ready = String(result.status ?? manifestStatus) === 'ready' && manifestStatus === 'ready' && staleReasons.length === 0;
+        const partial = staleReasons.length === 0
+            && (String(result.status ?? manifestStatus) === 'partial' || manifestStatus === 'partial');
+        return {
+            ok: true,
+            status: ready ? 'ready' : partial ? 'partial' : 'stale',
+            source: 'cwtools-project-knowledge-sqlite',
+            data: {
+                ...result,
+                status: ready ? 'ready' : partial ? 'partial' : 'stale',
+                manifestPath,
+                staleReasons,
+            },
+        };
+    }
+    const manifestDomains = stringArray(manifest.domains);
+    const domains = (args.domains?.length ? args.domains : manifestDomains)
+        .map(value => value.trim().toLowerCase())
+        .filter(Boolean)
+        .slice(0, 12);
+    const tokens = tokensFor(args);
+    const limit = Math.max(1, Math.min(Number(args.limit ?? 80) || 80, 300));
+    const evidence = [];
+    const capabilities = [];
+    for (const domain of domains) {
+        const capability = await readJson(host, path.join(root, 'capabilities', `${domain}.json`));
+        if (!capability)
+            continue;
+        capabilities.push({ domain, summary: capability.summary, evidencePolicy: capability.evidencePolicy });
+        const candidates = [];
+        if (Array.isArray(capability.definitions))
+            candidates.push(...capability.definitions.map(asRecord));
+        if (args.includeProjectPatterns !== false && Array.isArray(capability.projectExamples))
+            candidates.push(...capability.projectExamples.map(asRecord));
+        if (args.includeVanillaArchetypes !== false && Array.isArray(capability.vanillaArchetypes))
+            candidates.push(...capability.vanillaArchetypes.map(asRecord));
+        if (args.includeTopology !== false) {
+            const topology = asRecord(capability.topology);
+            if (Array.isArray(topology.edges))
+                candidates.push(...topology.edges.map(asRecord));
+        }
+        evidence.push(...candidates
+            .map(item => ({ ...item, domain, score: score(item, tokens) }))
+            .filter(item => tokens.length === 0 || Number(item.score) > 0)
+            .sort((a, b) => Number(b.score) - Number(a.score))
+            .slice(0, Math.max(5, Math.ceil(limit / Math.max(1, domains.length)))));
+    }
+    const unresolvedFile = args.includeUnresolved === false
+        ? undefined
+        : await readJson(host, path.join(root, 'unresolved.json'));
+    const unresolved = Array.isArray(unresolvedFile?.entries)
+        ? unresolvedFile.entries.map(asRecord).slice(0, 100)
+        : [];
+    const manifestStatus = String(manifest.status ?? 'stale');
+    const staleReasons = stringArray(manifest.staleReasons);
+    const ready = manifestStatus === 'ready' && staleReasons.length === 0;
+    return {
+        ok: true,
+        status: ready ? 'ready' : 'stale',
+        source: 'cwtools-project-knowledge',
+        data: {
+            status: ready ? 'ready' : 'stale',
+            manifestPath,
+            generatedAt: manifest.generatedAt,
+            game: manifest.game,
+            graphVersion: manifest.graphVersion,
+            staleReasons,
+            domains,
+            capabilities,
+            evidence: evidence.slice(0, limit),
+            unresolved,
+            requiredNextChecks: [
+                'Use query_cwt_schema/query_rules/query_scope for legality before writing.',
+                'Use query_override_modes for target directories with vanilla definitions.',
+                'Read exact source blocks before approving a complex blueprint.',
+            ],
+        },
+    };
+}

package/dist/project/profile.d.ts

@@ -0,0 +1,45 @@
+import type { HostServices } from '../host/hostServices';
+import type { SharedToolResult } from '../tools/schema';
+export type AgentMode = 'build' | 'plan' | 'explore' | 'general' | 'utility' | 'review' | 'gui_expert' | 'script_reviewer' | 'loc_translator' | 'loc_writer' | 'orchestrator' | 'script';
+export interface QueryProjectProfileArgs {
+    section?: 'summary' | 'routing' | 'directories' | 'localisation' | 'identifiers' | 'validation' | 'promptCards' | 'all';
+    mode?: AgentMode | 'asset';
+}
+export interface ProjectProfile {
+    schemaVersion: 1;
+    generatedAt: string;
+    workspaceRoot: string;
+    workspaceKind: string;
+    projectName: string;
+    game: {
+        id: string;
+        displayName: string;
+        confidence: 'high' | 'medium' | 'low';
+        evidence: string[];
+    };
+    keyDirectories: Array<{
+        key: string;
+        path: string;
+        exists: boolean;
+        fileCount?: number;
+    }>;
+    localisation: {
+        roots: string[];
+        languages: string[];
+        encoding: string;
+        sampleFiles: string[];
+    };
+    identifiers: Record<string, unknown>;
+    routing: Record<string, unknown>;
+    validation: Record<string, unknown>;
+    promptCards: Partial<Record<AgentMode | 'asset', string>>;
+    efficiencyHints: string[];
+    [key: string]: unknown;
+}
+export declare const PROJECT_PROFILE_RELATIVE_PATH: string;
+export declare function getProjectProfilePath(workspaceRoot: string): string;
+export declare function isProjectProfile(value: unknown): value is ProjectProfile;
+export declare function buildProfileSummary(profile: ProjectProfile): string;
+export declare function getPromptCardForMode(profile: ProjectProfile, mode?: AgentMode | 'asset'): string | undefined;
+export declare function selectProfileSection(profile: ProjectProfile, section: NonNullable<QueryProjectProfileArgs['section']>): unknown;
+export declare function queryProjectProfileWithHost(host: HostServices, args?: QueryProjectProfileArgs): Promise<SharedToolResult>;

package/dist/project/profile.js

@@ -0,0 +1,177 @@
+"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.PROJECT_PROFILE_RELATIVE_PATH = void 0;
+exports.getProjectProfilePath = getProjectProfilePath;
+exports.isProjectProfile = isProjectProfile;
+exports.buildProfileSummary = buildProfileSummary;
+exports.getPromptCardForMode = getPromptCardForMode;
+exports.selectProfileSection = selectProfileSection;
+exports.queryProjectProfileWithHost = queryProjectProfileWithHost;
+const path = __importStar(require("path"));
+exports.PROJECT_PROFILE_RELATIVE_PATH = path.join('.cwtools', 'project', 'profile.json');
+function getProjectProfilePath(workspaceRoot) {
+    try {
+        const fs = require('fs');
+        const primary = path.join(workspaceRoot, '.cwtools', 'project', 'profile.json');
+        if (fs.existsSync(primary))
+            return primary;
+        const legacy = path.join(workspaceRoot, '.cwtools-ai', 'project', 'profile.json');
+        if (fs.existsSync(legacy))
+            return legacy;
+        return primary;
+    }
+    catch {
+        return path.join(workspaceRoot, exports.PROJECT_PROFILE_RELATIVE_PATH);
+    }
+}
+function isProjectProfile(value) {
+    return !!value
+        && typeof value === 'object'
+        && value.schemaVersion === 1
+        && typeof value.projectName === 'string';
+}
+function buildProfileSummary(profile) {
+    const dirs = profile.keyDirectories.filter(dir => dir.exists).map(dir => dir.path).slice(0, 8).join(', ') || 'none';
+    const namespaces = Array.isArray(profile.identifiers.namespaces)
+        ? profile.identifiers.namespaces.slice(0, 8).join(', ') || 'none'
+        : 'none';
+    const languages = profile.localisation.languages.join(', ') || 'unknown';
+    return [
+        `Project: ${profile.projectName}`,
+        `Kind: ${profile.workspaceKind}`,
+        `Game: ${profile.game.displayName}`,
+        `Key dirs: ${dirs}`,
+        `Namespaces: ${namespaces}`,
+        `Localisation: ${languages} (${profile.localisation.encoding})`,
+    ].join('\n');
+}
+function getPromptCardForMode(profile, mode) {
+    if (!mode)
+        return undefined;
+    if (mode === 'loc_translator' || mode === 'loc_writer')
+        return profile.promptCards.loc_writer ?? profile.promptCards.build;
+    if (mode === 'gui_expert')
+        return profile.promptCards.asset ?? profile.promptCards.build;
+    if (mode === 'script_reviewer')
+        return profile.promptCards.review;
+    return profile.promptCards[mode] ?? profile.promptCards.build;
+}
+function selectProfileSection(profile, section) {
+    switch (section) {
+        case 'routing': return profile.routing;
+        case 'directories': return profile.keyDirectories;
+        case 'localisation': return profile.localisation;
+        case 'identifiers': return profile.identifiers;
+        case 'validation': return profile.validation;
+        case 'promptCards': return profile.promptCards;
+        case 'all': return profile;
+        case 'summary':
+        default:
+            return {
+                workspaceKind: profile.workspaceKind,
+                projectName: profile.projectName,
+                game: profile.game,
+                generatedAt: profile.generatedAt,
+                efficiencyHints: profile.efficiencyHints,
+            };
+    }
+}
+async function queryProjectProfileWithHost(host, args = {}) {
+    const profilePath = getProjectProfilePath(host.workspaceRoot);
+    try {
+        const read = await host.filesystem.readTextFile(profilePath);
+        if (!read.exists) {
+            return {
+                ok: false,
+                status: 'unavailable',
+                source: 'cwtools-shared',
+                error: {
+                    code: 'profile_missing',
+                    message: 'Project profile is missing.',
+                },
+                data: {
+                    status: 'missing',
+                    profilePath,
+                    _hint: 'Run /init in the VS Code extension or create .cwtools/project/profile.json, then retry.',
+                },
+            };
+        }
+        const parsed = JSON.parse(read.content);
+        if (!isProjectProfile(parsed)) {
+            return {
+                ok: false,
+                status: 'error',
+                source: 'cwtools-shared',
+                error: {
+                    code: 'invalid_profile',
+                    message: 'Project profile exists but is not schemaVersion 1.',
+                },
+            };
+        }
+        const section = args.section ?? 'summary';
+        return {
+            ok: true,
+            status: 'ready',
+            source: 'cwtools-shared',
+            data: {
+                status: 'ready',
+                profilePath,
+                generatedAt: parsed.generatedAt,
+                section,
+                profile: section === 'all' ? parsed : undefined,
+                summary: buildProfileSummary(parsed),
+                data: selectProfileSection(parsed, section),
+                promptCard: getPromptCardForMode(parsed, args.mode),
+                _hint: 'Use section="routing", "localisation", "identifiers", or a mode-specific promptCard for targeted context.',
+            },
+        };
+    }
+    catch (error) {
+        return {
+            ok: false,
+            status: 'error',
+            source: 'cwtools-shared',
+            error: {
+                code: 'profile_error',
+                message: error instanceof Error ? error.message : String(error),
+            },
+            data: {
+                status: 'error',
+                profilePath,
+            },
+        };
+    }
+}

package/dist/safety/localisation.d.ts

@@ -0,0 +1,33 @@
+import type { HostServices } from '../host/hostServices';
+import type { SharedToolResult } from '../tools/schema';
+export interface LocalisationEntry {
+    key: string;
+    value: string;
+    number?: number;
+    comment?: string;
+}
+export interface UpsertLocalisationResult {
+    content: string;
+    added: number;
+    updated: number;
+    hasBom: boolean;
+    language: string;
+    keys: string[];
+}
+export interface WriteLocalisationArgs {
+    filePath: string;
+    language?: string;
+    entries: LocalisationEntry[];
+}
+export interface WriteLocalisationResult {
+    success: boolean;
+    message: string;
+    filePath?: string;
+    relativePath?: string;
+    added?: number;
+    updated?: number;
+    keys?: string[];
+}
+export declare function sanitizeLocalisationValue(value: string): string;
+export declare function upsertLocalisationText(existingContent: string | null | undefined, language: string | undefined, entries: LocalisationEntry[]): UpsertLocalisationResult;
+export declare function writeLocalisationWithHost(host: HostServices, args: WriteLocalisationArgs): Promise<SharedToolResult<WriteLocalisationResult>>;

package/dist/safety/localisation.js

@@ -0,0 +1,105 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sanitizeLocalisationValue = sanitizeLocalisationValue;
+exports.upsertLocalisationText = upsertLocalisationText;
+exports.writeLocalisationWithHost = writeLocalisationWithHost;
+const paths_1 = require("./paths");
+const writes_1 = require("./writes");
+const schema_1 = require("../tools/schema");
+const BOM = '\uFEFF';
+function sanitizeLocalisationValue(value) {
+    return value
+        .replace(/\r\n/g, String.raw `\n`)
+        .replace(/\n/g, String.raw `\n`)
+        .replace(/\r/g, '')
+        .replace(/\t/g, String.raw `\t`)
+        .replace(/\u201C|\u201D/g, '"')
+        .replace(/\u2018|\u2019/g, "'");
+}
+function upsertLocalisationText(existingContent, language = 'l_english', entries) {
+    const raw = existingContent ?? '';
+    const existingHasBom = raw.charCodeAt(0) === 0xfeff;
+    const isNewFile = raw.length === 0;
+    const clean = existingHasBom ? raw.slice(1) : raw;
+    const lines = clean.length > 0 ? clean.split(/\r?\n/) : [];
+    const header = `${language}:`;
+    const firstNonEmpty = lines.findIndex(line => line.trim().length > 0);
+    if (firstNonEmpty === -1) {
+        lines.splice(0, lines.length, header);
+    }
+    else if (!/^l_[a-z_]+:\s*$/i.test(lines[firstNonEmpty].trim())) {
+        lines.splice(firstNonEmpty, 0, header);
+    }
+    const keyLineMap = new Map();
+    const keyRegex = /^\s*([\w.-]+):\d*\s*"/;
+    for (let index = 0; index < lines.length; index++) {
+        const match = lines[index].match(keyRegex);
+        if (match?.[1])
+            keyLineMap.set(match[1], index);
+    }
+    const appendLines = [];
+    let added = 0;
+    let updated = 0;
+    for (const entry of entries) {
+        const number = entry.number ?? 0;
+        const formattedLine = ` ${entry.key}:${number} "${sanitizeLocalisationValue(entry.value)}"`;
+        const existingIndex = keyLineMap.get(entry.key);
+        if (existingIndex !== undefined) {
+            lines[existingIndex] = formattedLine;
+            updated++;
+        }
+        else {
+            if (entry.comment)
+                appendLines.push(` ${entry.comment}`);
+            appendLines.push(formattedLine);
+            added++;
+        }
+    }
+    if (appendLines.length > 0) {
+        while (lines.length > 0 && lines[lines.length - 1].trim() === '')
+            lines.pop();
+        lines.push(...appendLines);
+    }
+    while (lines.length > 0 && lines[lines.length - 1].trim() === '')
+        lines.pop();
+    const hasBom = existingHasBom || isNewFile;
+    const body = `${lines.join('\n')}\n`;
+    return {
+        content: `${hasBom ? BOM : ''}${body}`,
+        added,
+        updated,
+        hasBom,
+        language,
+        keys: entries.map(entry => entry.key),
+    };
+}
+async function writeLocalisationWithHost(host, args) {
+    const writeDenied = (0, writes_1.ensureToolWriteAllowed)(host, 'write_localisation');
+    if (writeDenied)
+        return writeDenied;
+    if (!Array.isArray(args.entries) || args.entries.length === 0) {
+        return (0, schema_1.toolDenied)('invalid_arguments', 'write_localisation requires at least one entry.');
+    }
+    const pathValidation = (0, paths_1.validateLocalisationPath)(host.workspaceRoot, args.filePath);
+    if (!pathValidation.ok || !pathValidation.resolvedPath) {
+        return (0, schema_1.toolDenied)(pathValidation.reason ?? 'invalid_path', pathValidation.message ?? 'Invalid localisation path.');
+    }
+    const existing = await host.filesystem.readTextFile(pathValidation.resolvedPath);
+    const upsert = upsertLocalisationText(existing.exists ? existing.content : null, args.language ?? 'l_english', args.entries);
+    await host.filesystem.writeTextFile(pathValidation.resolvedPath, upsert.content);
+    await host.indexing?.invalidate?.(pathValidation.resolvedPath);
+    return {
+        ok: true,
+        status: 'success',
+        source: 'cwtools-shared',
+        data: {
+            success: true,
+            message: `Localisation updated: ${upsert.added} added, ${upsert.updated} updated.`,
+            filePath: pathValidation.resolvedPath,
+            relativePath: pathValidation.relativePath,
+            added: upsert.added,
+            updated: upsert.updated,
+            keys: upsert.keys,
+        },
+    };
+}

package/dist/safety/paths.d.ts

@@ -0,0 +1,21 @@
+export interface WorkspacePathResolution {
+    ok: boolean;
+    input: string;
+    workspaceRoot: string;
+    resolvedPath?: string;
+    relativePath?: string;
+    reason?: 'empty_path' | 'outside_workspace';
+}
+export interface LocalisationPathValidation {
+    ok: boolean;
+    resolvedPath?: string;
+    relativePath?: string;
+    reason?: 'outside_workspace' | 'not_yml' | 'not_localisation_directory' | 'scratch_path';
+    message?: string;
+}
+export declare function normalizeWorkspaceRoot(workspaceRoot: string): string;
+export declare function isPathInsideOrEqual(parent: string, child: string): boolean;
+export declare function resolveWorkspacePath(workspaceRoot: string, inputPath: string): WorkspacePathResolution;
+export declare function isLocalisationRelativePath(relativePath: string): boolean;
+export declare function isScratchRelativePath(relativePath: string): boolean;
+export declare function validateLocalisationPath(workspaceRoot: string, inputPath: string): LocalisationPathValidation;