hybridtm 0.5.0 → 0.7.0

package/README.md

@@ -9,12 +9,13 @@ HybridTM is a semantic translation memory engine that stores bilingual content i
 - Provides `semanticTranslationSearch`, `semanticSearch`, and `concordanceSearch` APIs with metadata-aware filtering
 - Streams data into LanceDB through a JSONL-based batch importer to keep memory usage predictable
 - Prevents duplicate segments by rewriting entries with deterministic IDs (`fileId:unitId:segmentIndex:lang`)
+- Ships a `hybridtm` command-line tool for creating instances, importing files, and enriching XLIFF files with TM match candidates from the shell
 
 Models download automatically the first time you initialize an instance and are cached in the standard Hugging Face directory.
 
 ## Requirements
 
-- Node.js 22 LTS or later
+- Node.js 24 LTS or later
 - npm 11+
 - Disk space for both the LanceDB directory you choose and the embedding model cache
 
@@ -72,12 +73,32 @@ await tm.importSDLTM('./translations/legacy.sdltm');
 
 `semanticTranslationSearch` automatically pairs every source hit with its matching target segment (same `fileId`, `unitId`, and `segmentIndex`), making the output ready for CAT integrations.
 
+## Command-line interface
+
+Installing HybridTM globally also adds a `hybridtm` command:
+
+```bash
+npm install -g hybridtm
+
+hybridtm create -name project -path ./project.lancedb
+hybridtm import -name project -file ./translations/project.xlf
+hybridtm match  -name project -file ./new-content.xlf -output ./new-content.matches.xlf
+hybridtm list
+hybridtm remove -name project -yes
+```
+
+`match` never touches `<target>` — it adds spec Translation Candidates
+(`<mtc:matches>`/`<mtc:match>`) entries to a **new** output file, leaving the
+input untouched. Run `hybridtm <command> -help` for the full flag list, or
+see [05 · Command-Line Interface](docs/05-command-line-interface.md).
+
 ## Documentation
 
 - [01 · Getting Started](docs/01-getting-started.md)
 - [02 · Importing Data](docs/02-importing-data.md)
 - [03 · Search and Filtering](docs/03-search-and-filtering.md)
 - [04 · Sample Scenarios](docs/04-sample-scenarios.md)
+- [05 · Command-Line Interface](docs/05-command-line-interface.md)
 
 Each guide is short and task-oriented, so you can jump directly to the workflow you need.
 
@@ -100,6 +121,7 @@ If you copy `samples/` elsewhere, update `samples/package.json` so the `hybridtm
 ## Project layout
 
 - `ts/` – source files for the library
+- `ts/cli/` – source for the `hybridtm` command-line tool
 - `dist/` – compiled JavaScript and declarations (`npm run build`)
 - `docs/` – task-focused tutorials referenced above
 - `samples/` – standalone TypeScript project with runnable workflows

package/dist/cli/cliUtils.d.ts

@@ -0,0 +1,19 @@
+/*******************************************************************************
+ * Copyright (c) 2025-2026 Maxprograms.
+ *
+ * This program and the accompanying materials
+ * are made available under the terms of the Eclipse   License 1.0
+ * which accompanies this distribution, and is available at
+ * https://www.eclipse.org/org/documents/epl-v10.html
+ *
+ * Contributors:
+ *     Maxprograms - initial API and implementation
+ *******************************************************************************/
+export declare class CliUtils {
+    static getFlag(args: string[], flag: string): string | undefined;
+    static hasFlag(args: string[], flag: string): boolean;
+    static resolvePath(rawPath: string): string;
+    static requireExistingFile(rawPath: string, label: string): string;
+    static resolveModelName(alias: string | undefined): string;
+    static fail(message: string): never;
+}

package/dist/cli/cliUtils.js

@@ -0,0 +1,67 @@
+/*******************************************************************************
+ * Copyright (c) 2025-2026 Maxprograms.
+ *
+ * This program and the accompanying materials
+ * are made available under the terms of the Eclipse   License 1.0
+ * which accompanies this distribution, and is available at
+ * https://www.eclipse.org/org/documents/epl-v10.html
+ *
+ * Contributors:
+ *     Maxprograms - initial API and implementation
+ *******************************************************************************/
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+import { HybridTM } from '../hybridtm.js';
+export class CliUtils {
+    static getFlag(args, flag) {
+        const index = args.indexOf(flag);
+        if (index !== -1 && index + 1 < args.length) {
+            return args[index + 1];
+        }
+        return undefined;
+    }
+    static hasFlag(args, flag) {
+        return args.includes(flag);
+    }
+    static resolvePath(rawPath) {
+        let expanded = rawPath;
+        if (expanded.startsWith('~')) {
+            const home = homedir();
+            if (expanded === '~') {
+                expanded = home;
+            }
+            else if (expanded.startsWith('~/')) {
+                expanded = join(home, expanded.slice(2));
+            }
+        }
+        return resolve(expanded);
+    }
+    static requireExistingFile(rawPath, label) {
+        const resolved = CliUtils.resolvePath(rawPath);
+        if (!existsSync(resolved)) {
+            console.error(label + ' "' + resolved + '" does not exist.');
+            process.exit(1);
+        }
+        return resolved;
+    }
+    static resolveModelName(alias) {
+        switch (alias) {
+            case 'speed':
+                return HybridTM.SPEED_MODEL;
+            case 'resource':
+                return HybridTM.RESOURCE_MODEL;
+            case 'quality':
+            case undefined:
+                return HybridTM.QUALITY_MODEL;
+            default:
+                console.error('Unknown -model value "' + alias + '". Expected speed, quality, or resource.');
+                process.exit(1);
+        }
+    }
+    static fail(message) {
+        console.error(message);
+        process.exit(1);
+    }
+}
+//# sourceMappingURL=cliUtils.js.map

package/dist/cli/cliUtils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cliUtils.js","sourceRoot":"","sources":["../../ts/cli/cliUtils.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;iFAUiF;AAEjF,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAClC,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAE1C,MAAM,OAAO,QAAQ;IAEjB,MAAM,CAAC,OAAO,CAAC,IAAc,EAAE,IAAY;QACvC,MAAM,KAAK,GAAW,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;QACzC,IAAI,KAAK,KAAK,CAAC,CAAC,IAAI,KAAK,GAAG,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC;YAC1C,OAAO,IAAI,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC;QAC3B,CAAC;QACD,OAAO,SAAS,CAAC;IACrB,CAAC;IAED,MAAM,CAAC,OAAO,CAAC,IAAc,EAAE,IAAY;QACvC,OAAO,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;IAC/B,CAAC;IAED,MAAM,CAAC,WAAW,CAAC,OAAe;QAC9B,IAAI,QAAQ,GAAW,OAAO,CAAC;QAC/B,IAAI,QAAQ,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;YAC3B,MAAM,IAAI,GAAW,OAAO,EAAE,CAAC;YAC/B,IAAI,QAAQ,KAAK,GAAG,EAAE,CAAC;gBACnB,QAAQ,GAAG,IAAI,CAAC;YACpB,CAAC;iBAAM,IAAI,QAAQ,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;gBACnC,QAAQ,GAAG,IAAI,CAAC,IAAI,EAAE,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;YAC7C,CAAC;QACL,CAAC;QACD,OAAO,OAAO,CAAC,QAAQ,CAAC,CAAC;IAC7B,CAAC;IAED,MAAM,CAAC,mBAAmB,CAAC,OAAe,EAAE,KAAa;QACrD,MAAM,QAAQ,GAAW,QAAQ,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC;QACvD,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;YACxB,OAAO,CAAC,KAAK,CAAC,KAAK,GAAG,IAAI,GAAG,QAAQ,GAAG,mBAAmB,CAAC,CAAC;YAC7D,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QACpB,CAAC;QACD,OAAO,QAAQ,CAAC;IACpB,CAAC;IAED,MAAM,CAAC,gBAAgB,CAAC,KAAyB;QAC7C,QAAQ,KAAK,EAAE,CAAC;YACZ,KAAK,OAAO;gBACR,OAAO,QAAQ,CAAC,WAAW,CAAC;YAChC,KAAK,UAAU;gBACX,OAAO,QAAQ,CAAC,cAAc,CAAC;YACnC,KAAK,SAAS,CAAC;YACf,KAAK,SAAS;gBACV,OAAO,QAAQ,CAAC,aAAa,CAAC;YAClC;gBACI,OAAO,CAAC,KAAK,CAAC,wBAAwB,GAAG,KAAK,GAAG,0CAA0C,CAAC,CAAC;gBAC7F,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QACxB,CAAC;IACL,CAAC;IAED,MAAM,CAAC,IAAI,CAAC,OAAe;QACvB,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QACvB,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IACpB,CAAC;CACJ"}

package/dist/cli/createCommand.d.ts

@@ -0,0 +1,13 @@
+/*******************************************************************************
+ * Copyright (c) 2025-2026 Maxprograms.
+ *
+ * This program and the accompanying materials
+ * are made available under the terms of the Eclipse   License 1.0
+ * which accompanies this distribution, and is available at
+ * https://www.eclipse.org/org/documents/epl-v10.html
+ *
+ * Contributors:
+ *     Maxprograms - initial API and implementation
+ *******************************************************************************/
+export declare function usage(): void;
+export declare function runCreateCommand(args: string[]): Promise<void>;

package/dist/cli/createCommand.js

@@ -0,0 +1,44 @@
+/*******************************************************************************
+ * Copyright (c) 2025-2026 Maxprograms.
+ *
+ * This program and the accompanying materials
+ * are made available under the terms of the Eclipse   License 1.0
+ * which accompanies this distribution, and is available at
+ * https://www.eclipse.org/org/documents/epl-v10.html
+ *
+ * Contributors:
+ *     Maxprograms - initial API and implementation
+ *******************************************************************************/
+import { HybridTMFactory } from '../index.js';
+import { CliUtils } from './cliUtils.js';
+export function usage() {
+    console.log('Usage: hybridtm create -name <name> -path <dir> [-model speed|quality|resource]');
+    console.log();
+    console.log('  -name    Name to register the new instance under (required)');
+    console.log('  -path    Directory where the instance\'s LanceDB data will live (required)');
+    console.log('  -model   Embedding model preset: speed, quality (default), or resource');
+}
+export async function runCreateCommand(args) {
+    if (CliUtils.hasFlag(args, '-help')) {
+        usage();
+        return;
+    }
+    const name = CliUtils.getFlag(args, '-name');
+    const rawPath = CliUtils.getFlag(args, '-path');
+    if (!name || !rawPath) {
+        usage();
+        CliUtils.fail('Missing required -name or -path.');
+    }
+    const modelAlias = CliUtils.getFlag(args, '-model');
+    const modelName = CliUtils.resolveModelName(modelAlias);
+    const resolvedPath = CliUtils.resolvePath(rawPath);
+    try {
+        const tm = HybridTMFactory.createInstance(name, resolvedPath, modelName);
+        await tm.close();
+        console.log('Created instance "' + name + '" at ' + resolvedPath + ' (model: ' + modelName + ')');
+    }
+    catch (error) {
+        CliUtils.fail(error instanceof Error ? error.message : String(error));
+    }
+}
+//# sourceMappingURL=createCommand.js.map

package/dist/cli/createCommand.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"createCommand.js","sourceRoot":"","sources":["../../ts/cli/createCommand.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;iFAUiF;AAEjF,OAAO,EAAY,eAAe,EAAE,MAAM,aAAa,CAAC;AACxD,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAEzC,MAAM,UAAU,KAAK;IACjB,OAAO,CAAC,GAAG,CAAC,iFAAiF,CAAC,CAAC;IAC/F,OAAO,CAAC,GAAG,EAAE,CAAC;IACd,OAAO,CAAC,GAAG,CAAC,+DAA+D,CAAC,CAAC;IAC7E,OAAO,CAAC,GAAG,CAAC,8EAA8E,CAAC,CAAC;IAC5F,OAAO,CAAC,GAAG,CAAC,0EAA0E,CAAC,CAAC;AAC5F,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAC,IAAc;IACjD,IAAI,QAAQ,CAAC,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,EAAE,CAAC;QAClC,KAAK,EAAE,CAAC;QACR,OAAO;IACX,CAAC;IAED,MAAM,IAAI,GAAuB,QAAQ,CAAC,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;IACjE,MAAM,OAAO,GAAuB,QAAQ,CAAC,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;IACpE,IAAI,CAAC,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;QACpB,KAAK,EAAE,CAAC;QACR,QAAQ,CAAC,IAAI,CAAC,kCAAkC,CAAC,CAAC;IACtD,CAAC;IAED,MAAM,UAAU,GAAuB,QAAQ,CAAC,OAAO,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;IACxE,MAAM,SAAS,GAAW,QAAQ,CAAC,gBAAgB,CAAC,UAAU,CAAC,CAAC;IAChE,MAAM,YAAY,GAAW,QAAQ,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC;IAE3D,IAAI,CAAC;QACD,MAAM,EAAE,GAAa,eAAe,CAAC,cAAc,CAAC,IAAI,EAAE,YAAY,EAAE,SAAS,CAAC,CAAC;QACnF,MAAM,EAAE,CAAC,KAAK,EAAE,CAAC;QACjB,OAAO,CAAC,GAAG,CAAC,oBAAoB,GAAG,IAAI,GAAG,OAAO,GAAG,YAAY,GAAG,WAAW,GAAG,SAAS,GAAG,GAAG,CAAC,CAAC;IACtG,CAAC;IAAC,OAAO,KAAc,EAAE,CAAC;QACtB,QAAQ,CAAC,IAAI,CAAC,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;IAC1E,CAAC;AACL,CAAC"}

package/dist/cli/hybridtmCli.d.ts

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+/*******************************************************************************
+ * Copyright (c) 2025-2026 Maxprograms.
+ *
+ * This program and the accompanying materials
+ * are made available under the terms of the Eclipse   License 1.0
+ * which accompanies this distribution, and is available at
+ * https://www.eclipse.org/org/documents/epl-v10.html
+ *
+ * Contributors:
+ *     Maxprograms - initial API and implementation
+ *******************************************************************************/
+export {};

package/dist/cli/hybridtmCli.js

@@ -0,0 +1,73 @@
+#!/usr/bin/env node
+/*******************************************************************************
+ * Copyright (c) 2025-2026 Maxprograms.
+ *
+ * This program and the accompanying materials
+ * are made available under the terms of the Eclipse   License 1.0
+ * which accompanies this distribution, and is available at
+ * https://www.eclipse.org/org/documents/epl-v10.html
+ *
+ * Contributors:
+ *     Maxprograms - initial API and implementation
+ *******************************************************************************/
+import { runCreateCommand } from './createCommand.js';
+import { runImportCommand } from './importCommand.js';
+import { runMatchCommand } from './matchCommand.js';
+import { runListCommand, runRemoveCommand } from './registryCommands.js';
+class HybridTMCli {
+    constructor() {
+        this.run(process.argv.slice(2));
+    }
+    async run(argv) {
+        const command = argv[0];
+        const rest = argv.slice(1);
+        try {
+            if (command === 'create') {
+                await runCreateCommand(rest);
+            }
+            else if (command === 'import') {
+                await runImportCommand(rest);
+            }
+            else if (command === 'match') {
+                await runMatchCommand(rest);
+            }
+            else if (command === 'list') {
+                await runListCommand(rest);
+            }
+            else if (command === 'remove') {
+                await runRemoveCommand(rest);
+            }
+            else if (command === '-help' || command === '--help') {
+                this.usage();
+                process.exit(0);
+            }
+            else if (command === undefined) {
+                this.usage();
+                process.exit(1);
+            }
+            else {
+                console.error('Unknown command "' + command + '".');
+                this.usage();
+                process.exit(1);
+            }
+        }
+        catch (error) {
+            console.error(error instanceof Error ? error.message : String(error));
+            process.exit(1);
+        }
+    }
+    usage() {
+        console.log('Usage: hybridtm <command> [options]');
+        console.log();
+        console.log('Commands:');
+        console.log('  create   Create a new named TM instance');
+        console.log('  import   Import an XLIFF/TMX/SDLTM file into an instance');
+        console.log('  match    Enrich an XLIFF file with TM match candidates');
+        console.log('  list     List registered instances');
+        console.log('  remove   Delete a registered instance and its data');
+        console.log();
+        console.log('Run "hybridtm <command> -help" for command-specific options.');
+    }
+}
+new HybridTMCli();
+//# sourceMappingURL=hybridtmCli.js.map

package/dist/cli/hybridtmCli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hybridtmCli.js","sourceRoot":"","sources":["../../ts/cli/hybridtmCli.ts"],"names":[],"mappings":";AACA;;;;;;;;;;iFAUiF;AAEjF,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAEzE,MAAM,WAAW;IAEb;QACI,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IACpC,CAAC;IAEO,KAAK,CAAC,GAAG,CAAC,IAAc;QAC5B,MAAM,OAAO,GAAuB,IAAI,CAAC,CAAC,CAAC,CAAC;QAC5C,MAAM,IAAI,GAAa,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;QACrC,IAAI,CAAC;YACD,IAAI,OAAO,KAAK,QAAQ,EAAE,CAAC;gBACvB,MAAM,gBAAgB,CAAC,IAAI,CAAC,CAAC;YACjC,CAAC;iBAAM,IAAI,OAAO,KAAK,QAAQ,EAAE,CAAC;gBAC9B,MAAM,gBAAgB,CAAC,IAAI,CAAC,CAAC;YACjC,CAAC;iBAAM,IAAI,OAAO,KAAK,OAAO,EAAE,CAAC;gBAC7B,MAAM,eAAe,CAAC,IAAI,CAAC,CAAC;YAChC,CAAC;iBAAM,IAAI,OAAO,KAAK,MAAM,EAAE,CAAC;gBAC5B,MAAM,cAAc,CAAC,IAAI,CAAC,CAAC;YAC/B,CAAC;iBAAM,IAAI,OAAO,KAAK,QAAQ,EAAE,CAAC;gBAC9B,MAAM,gBAAgB,CAAC,IAAI,CAAC,CAAC;YACjC,CAAC;iBAAM,IAAI,OAAO,KAAK,OAAO,IAAI,OAAO,KAAK,QAAQ,EAAE,CAAC;gBACrD,IAAI,CAAC,KAAK,EAAE,CAAC;gBACb,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;YACpB,CAAC;iBAAM,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;gBAC/B,IAAI,CAAC,KAAK,EAAE,CAAC;gBACb,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;YACpB,CAAC;iBAAM,CAAC;gBACJ,OAAO,CAAC,KAAK,CAAC,mBAAmB,GAAG,OAAO,GAAG,IAAI,CAAC,CAAC;gBACpD,IAAI,CAAC,KAAK,EAAE,CAAC;gBACb,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;YACpB,CAAC;QACL,CAAC;QAAC,OAAO,KAAc,EAAE,CAAC;YACtB,OAAO,CAAC,KAAK,CAAC,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;YACtE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QACpB,CAAC;IACL,CAAC;IAEO,KAAK;QACT,OAAO,CAAC,GAAG,CAAC,qCAAqC,CAAC,CAAC;QACnD,OAAO,CAAC,GAAG,EAAE,CAAC;QACd,OAAO,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;QACzB,OAAO,CAAC,GAAG,CAAC,2CAA2C,CAAC,CAAC;QACzD,OAAO,CAAC,GAAG,CAAC,4DAA4D,CAAC,CAAC;QAC1E,OAAO,CAAC,GAAG,CAAC,0DAA0D,CAAC,CAAC;QACxE,OAAO,CAAC,GAAG,CAAC,sCAAsC,CAAC,CAAC;QACpD,OAAO,CAAC,GAAG,CAAC,sDAAsD,CAAC,CAAC;QACpE,OAAO,CAAC,GAAG,EAAE,CAAC;QACd,OAAO,CAAC,GAAG,CAAC,8DAA8D,CAAC,CAAC;IAChF,CAAC;CACJ;AAED,IAAI,WAAW,EAAE,CAAC"}

package/dist/cli/importCommand.d.ts

@@ -0,0 +1,13 @@
+/*******************************************************************************
+ * Copyright (c) 2025-2026 Maxprograms.
+ *
+ * This program and the accompanying materials
+ * are made available under the terms of the Eclipse   License 1.0
+ * which accompanies this distribution, and is available at
+ * https://www.eclipse.org/org/documents/epl-v10.html
+ *
+ * Contributors:
+ *     Maxprograms - initial API and implementation
+ *******************************************************************************/
+export declare function usage(): void;
+export declare function runImportCommand(args: string[]): Promise<void>;

package/dist/cli/importCommand.js

@@ -0,0 +1,105 @@
+/*******************************************************************************
+ * Copyright (c) 2025-2026 Maxprograms.
+ *
+ * This program and the accompanying materials
+ * are made available under the terms of the Eclipse   License 1.0
+ * which accompanies this distribution, and is available at
+ * https://www.eclipse.org/org/documents/epl-v10.html
+ *
+ * Contributors:
+ *     Maxprograms - initial API and implementation
+ *******************************************************************************/
+import { extname } from "node:path";
+import { HybridTMFactory } from '../index.js';
+import { CliUtils } from './cliUtils.js';
+export function usage() {
+    console.log('Usage: hybridtm import -name <name> -file <path> [-type xliff|tmx|sdltm]');
+    console.log('                        [-minState initial|translated|reviewed|final]');
+    console.log('                        [-keepEmpty] [-keepUnconfirmed] [-noMetadata]');
+    console.log();
+    console.log('  -name             Instance to import into (required)');
+    console.log('  -file             File to import (required)');
+    console.log('  -type             Import format; inferred from the file extension when omitted');
+    console.log('  -minState         Minimum segment state to import (default: translated)');
+    console.log('  -keepEmpty        Import segments with an empty target (default: skipped)');
+    console.log('  -keepUnconfirmed  Import segments with no recognized state (default: skipped)');
+    console.log('  -noMetadata       Skip extracting notes/metadata/extension attributes');
+}
+export async function runImportCommand(args) {
+    if (CliUtils.hasFlag(args, '-help')) {
+        usage();
+        return;
+    }
+    const name = CliUtils.getFlag(args, '-name');
+    const rawFile = CliUtils.getFlag(args, '-file');
+    if (!name || !rawFile) {
+        usage();
+        CliUtils.fail('Missing required -name or -file.');
+    }
+    const filePath = CliUtils.requireExistingFile(rawFile, 'Import file');
+    const type = resolveImportType(CliUtils.getFlag(args, '-type'), filePath);
+    const options = buildImportOptions(args);
+    const tm = HybridTMFactory.getInstance(name);
+    if (!tm) {
+        CliUtils.fail('No instance named "' + name + '". Run "hybridtm create" or "hybridtm list" first.');
+    }
+    try {
+        let count;
+        switch (type) {
+            case 'xliff':
+                count = await tm.importXLIFF(filePath, options);
+                break;
+            case 'tmx':
+                count = await tm.importTMX(filePath, options);
+                break;
+            case 'sdltm':
+                count = await tm.importSDLTM(filePath, options);
+                break;
+        }
+        console.log('Imported ' + count + ' entries from ' + filePath + ' into "' + name + '".');
+    }
+    catch (error) {
+        CliUtils.fail(error instanceof Error ? error.message : String(error));
+    }
+    finally {
+        await tm.close();
+    }
+}
+function resolveImportType(explicit, filePath) {
+    if (explicit === 'xliff' || explicit === 'tmx' || explicit === 'sdltm') {
+        return explicit;
+    }
+    if (explicit !== undefined) {
+        CliUtils.fail('Unknown -type value "' + explicit + '". Expected xliff, tmx, or sdltm.');
+    }
+    const ext = extname(filePath).toLowerCase();
+    if (ext === '.xlf' || ext === '.xliff') {
+        return 'xliff';
+    }
+    if (ext === '.tmx') {
+        return 'tmx';
+    }
+    if (ext === '.sdltm') {
+        return 'sdltm';
+    }
+    CliUtils.fail('Could not infer import type from "' + filePath + '". Pass -type explicitly.');
+}
+function buildImportOptions(args) {
+    const options = {
+        skipEmpty: !CliUtils.hasFlag(args, '-keepEmpty'),
+        skipUnconfirmed: !CliUtils.hasFlag(args, '-keepUnconfirmed'),
+        extractMetadata: !CliUtils.hasFlag(args, '-noMetadata')
+    };
+    const minState = CliUtils.getFlag(args, '-minState');
+    if (minState !== undefined) {
+        if (!isTranslationState(minState)) {
+            CliUtils.fail('Unknown -minState value "' + minState + '". Expected initial, translated, reviewed, or final.');
+        }
+        options.minState = minState;
+    }
+    return options;
+}
+function isTranslationState(value) {
+    return value === 'initial' || value === 'translated' || value === 'reviewed' || value === 'final';
+}
+//# sourceMappingURL=importCommand.js.map

package/dist/cli/importCommand.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"importCommand.js","sourceRoot":"","sources":["../../ts/cli/importCommand.ts"],"names":[],"mappings":"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"}

package/dist/cli/matchCommand.d.ts

@@ -0,0 +1,13 @@
+/*******************************************************************************
+ * Copyright (c) 2025-2026 Maxprograms.
+ *
+ * This program and the accompanying materials
+ * are made available under the terms of the Eclipse   License 1.0
+ * which accompanies this distribution, and is available at
+ * https://www.eclipse.org/org/documents/epl-v10.html
+ *
+ * Contributors:
+ *     Maxprograms - initial API and implementation
+ *******************************************************************************/
+export declare function usage(): void;
+export declare function runMatchCommand(args: string[]): Promise<void>;

package/dist/cli/matchCommand.js

@@ -0,0 +1,195 @@
+/*******************************************************************************
+ * Copyright (c) 2025-2026 Maxprograms.
+ *
+ * This program and the accompanying materials
+ * are made available under the terms of the Eclipse   License 1.0
+ * which accompanies this distribution, and is available at
+ * https://www.eclipse.org/org/documents/epl-v10.html
+ *
+ * Contributors:
+ *     Maxprograms - initial API and implementation
+ *******************************************************************************/
+import { basename, dirname, extname, join } from "node:path";
+import { XliffGroup, XliffMatch, XliffMatches, XliffMrk, XliffParser, XliffPc, XliffSegment, XliffSource, XliffTarget } from 'typesxliff';
+import { HybridTMFactory, Utils } from '../index.js';
+import { CliUtils } from './cliUtils.js';
+const MATCHES_NAMESPACE = 'urn:oasis:names:tc:xliff:matches:2.0';
+const DEFAULT_PREFIX = 'mtc';
+const DEFAULT_LIMIT = 5;
+const DEFAULT_SIMILARITY = 60;
+export function usage() {
+    console.log('Usage: hybridtm match -name <name> -file <path> [-output <path>]');
+    console.log('                       [-limit N] [-similarity N] [-all]');
+    console.log();
+    console.log('  -name        TM instance to search against (required)');
+    console.log('  -file        XLIFF file to enrich with match candidates (required)');
+    console.log('  -output      Output path (default: <file-without-ext>.matches.xlf)');
+    console.log('  -limit       Max candidates per segment (default: ' + DEFAULT_LIMIT + ')');
+    console.log('  -similarity  Minimum hybrid match score 0-100 (default: ' + DEFAULT_SIMILARITY + ')');
+    console.log('  -all         Consider every segment, not just untranslated ones');
+    console.log();
+    console.log('Never modifies <target>. Adds spec Translation Candidates module');
+    console.log('(<mtc:matches>/<mtc:match>) entries and writes the result to a new file.');
+}
+export async function runMatchCommand(args) {
+    if (CliUtils.hasFlag(args, '-help')) {
+        usage();
+        return;
+    }
+    const name = CliUtils.getFlag(args, '-name');
+    const rawFile = CliUtils.getFlag(args, '-file');
+    if (!name || !rawFile) {
+        usage();
+        CliUtils.fail('Missing required -name or -file.');
+    }
+    const filePath = CliUtils.requireExistingFile(rawFile, 'XLIFF file');
+    const limit = parsePositiveInt(CliUtils.getFlag(args, '-limit'), DEFAULT_LIMIT, '-limit');
+    const similarity = parsePositiveInt(CliUtils.getFlag(args, '-similarity'), DEFAULT_SIMILARITY, '-similarity');
+    const processAll = CliUtils.hasFlag(args, '-all');
+    const outputPath = resolveOutputPath(CliUtils.getFlag(args, '-output'), filePath);
+    const tm = HybridTMFactory.getInstance(name);
+    if (!tm) {
+        CliUtils.fail('No instance named "' + name + '". Run "hybridtm create" or "hybridtm list" first.');
+    }
+    try {
+        const parser = new XliffParser();
+        parser.parseFile(filePath);
+        const document = parser.getXliffDocument();
+        if (!document) {
+            CliUtils.fail('Unable to parse "' + filePath + '".');
+        }
+        const srcLang = document.getSrcLang();
+        const tgtLang = document.getTrgLang();
+        if (!tgtLang) {
+            CliUtils.fail('"' + filePath + '" is missing @trgLang; nothing to match against.');
+        }
+        let segmentsProcessed = 0;
+        let segmentsWithMatches = 0;
+        let totalMatches = 0;
+        let usedModule = false;
+        for (const file of document.getFiles()) {
+            const fileId = file.getId();
+            for (const unit of collectUnits(file.getEntries())) {
+                const unitMatches = [];
+                const unitId = unit.getId();
+                for (const item of unit.getItems()) {
+                    if (!(item instanceof XliffSegment)) {
+                        continue;
+                    }
+                    if (!processAll && !needsMatches(item)) {
+                        continue;
+                    }
+                    const source = item.getSource();
+                    const pureSource = source ? getPureText(source.getContent()) : '';
+                    if (pureSource.trim().length === 0) {
+                        continue;
+                    }
+                    segmentsProcessed++;
+                    const results = await tm.semanticTranslationSearch(pureSource, srcLang, tgtLang, similarity, limit);
+                    if (results.length === 0) {
+                        continue;
+                    }
+                    segmentsWithMatches++;
+                    totalMatches += results.length;
+                    const ref = '#/f=' + fileId + '/u=' + unitId + (item.getId() ? '/' + item.getId() : '');
+                    results.forEach((match) => unitMatches.push(buildXliffMatch(ref, match)));
+                }
+                if (unitMatches.length > 0) {
+                    const matches = new XliffMatches();
+                    matches.setNamespacePrefix(DEFAULT_PREFIX);
+                    unitMatches.forEach((match) => matches.addMatch(match));
+                    unit.setMatches(matches);
+                    usedModule = true;
+                }
+            }
+        }
+        if (usedModule) {
+            declareMatchesNamespace(document);
+        }
+        document.writeDocument(outputPath, true);
+        console.log('Segments processed: ' + segmentsProcessed);
+        console.log('Segments with matches: ' + segmentsWithMatches);
+        console.log('Total match candidates: ' + totalMatches);
+        console.log('Output: ' + outputPath);
+    }
+    catch (error) {
+        CliUtils.fail(error instanceof Error ? error.message : String(error));
+    }
+    finally {
+        await tm.close();
+    }
+}
+function collectUnits(entries) {
+    const units = [];
+    entries.forEach((entry) => {
+        if (entry instanceof XliffGroup) {
+            units.push(...collectUnits(entry.getEntries()));
+        }
+        else {
+            units.push(entry);
+        }
+    });
+    return units;
+}
+function needsMatches(segment) {
+    const state = segment.getState();
+    if (state === undefined || state === 'initial') {
+        return true;
+    }
+    const target = segment.getTarget();
+    if (!target) {
+        return true;
+    }
+    return getPureText(target.getContent()).trim().length === 0;
+}
+function buildXliffMatch(ref, match) {
+    const xliffMatch = new XliffMatch(ref);
+    xliffMatch.setNamespacePrefix(DEFAULT_PREFIX);
+    xliffMatch.setType('tm');
+    xliffMatch.setOrigin(match.origin);
+    xliffMatch.setSimilarity(String(match.similarity));
+    const source = new XliffSource();
+    source.addText(Utils.getPureText(match.source));
+    xliffMatch.setSource(source);
+    const target = new XliffTarget();
+    target.addText(Utils.getPureText(match.target));
+    xliffMatch.setTarget(target);
+    return xliffMatch;
+}
+function declareMatchesNamespace(document) {
+    const alreadyDeclared = document.getOtherAttributes().some((attribute) => attribute.getName().startsWith('xmlns:') && attribute.getValue() === MATCHES_NAMESPACE);
+    if (!alreadyDeclared) {
+        document.setOtherAttribute('xmlns:' + DEFAULT_PREFIX, MATCHES_NAMESPACE);
+    }
+}
+function resolveOutputPath(explicit, inputPath) {
+    if (explicit) {
+        return CliUtils.resolvePath(explicit);
+    }
+    const ext = extname(inputPath);
+    const stem = basename(inputPath, ext);
+    return join(dirname(inputPath), stem + '.matches.xlf');
+}
+function parsePositiveInt(raw, fallback, flag) {
+    if (raw === undefined) {
+        return fallback;
+    }
+    const parsed = Number(raw);
+    if (!Number.isInteger(parsed) || parsed <= 0) {
+        CliUtils.fail('Invalid ' + flag + ' value "' + raw + '"; expected a positive integer.');
+    }
+    return parsed;
+}
+function getPureText(content) {
+    let text = '';
+    content.forEach((item) => {
+        if (typeof item === 'string') {
+            text += item;
+        }
+        else if (item instanceof XliffPc || item instanceof XliffMrk) {
+            text += getPureText(item.getContent());
+        }
+    });
+    return text;
+}
+//# sourceMappingURL=matchCommand.js.map