@worldware/msg-cli 0.0.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Joel Sahleen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,181 @@
+# msg-cli
+
+## Overview
+
+msg-cli is a command-line tool for the [msg](https://github.com/worldware-studios/msg) library. It helps you scaffold internationalization (i18n) and localization (l10n) layout and wire up your project for use with msg.
+
+**Current status:** Implemented commands: `init` (scaffold i18n/l10n and config), `create project` (template a new MsgProject file in i18n/projects), and `create resource` (template a new MsgResource file in i18n/resources).
+
+## Installation
+
+Install globally:
+
+```bash
+npm install -g @worldware/msg-cli
+```
+
+Or use via `npx`:
+
+```bash
+npx @worldware/msg-cli <command>
+```
+
+For project-local setup, run `msg init` in your project root to add msg and msg-cli as dependencies and scaffold directories and config.
+
+## Core Concepts
+
+- **i18n (internationalization):** Source message projects and resources. MsgProject and MsgResource files live under the i18n directory (default `src/i18n`).
+- **l10n (localization):** Exported XLIFF files and imported translation JSON. Exports and translation data live under the l10n directory (default `res/l10n`).
+- **Import aliases:** The init command adds `#i18n/*` and `#l10n/*` (and `#root/*`) to `package.json` so you can import with short paths like `import project from '#i18n/projects/main'`.
+
+## Usage
+
+**Commands:** `init`, `create project`, `create resource`.
+
+### init
+
+Scaffold a msg project: create i18n and l10n directories, update `package.json` (directories, import aliases, scripts), optionally update `tsconfig.json` for path aliases, and install `@worldware/msg`.
+
+```bash
+msg init
+```
+
+| Flag | Description |
+|------|-------------|
+| `-h`, `--help` | Show help for the init command. |
+| `-i` | Interactive: prompt for i18n and l10n directory paths. |
+| `-f`, `--force` | Force a clean run; overwrite or re-apply existing msg setup. |
+| `--i18nDir <path>` | Relative path for the i18n directory (default: `src/i18n`). |
+| `--l10nDir <path>` | Relative path for the l10n directory (default: `res/l10n`). |
+
+**Examples:**
+
+```bash
+# Default layout (src/i18n, res/l10n)
+msg init
+
+# Custom paths
+msg init --i18nDir lib/i18n --l10nDir data/l10n
+
+# Re-run and overwrite existing setup
+msg init -f
+
+# Prompt for paths
+msg init -i
+```
+
+**What init does:**
+
+1. Creates `i18n` with subdirectories `projects` and `resources`, and `l10n` with `translations` and `xliff` (or your custom paths).
+2. Adds `.gitkeep` in each leaf directory.
+3. Adds `directories.i18n`, `directories.l10n`, and `directories.root` to `package.json`.
+4. Adds import aliases `#i18n/*`, `#l10n/*`, and `#root/*` to `package.json`.
+5. Adds scripts `i18n-export` and `l10n-import` (pointing to `msg export:resources` and `msg import:translations`) for when those commands are available.
+6. If `tsconfig.json` exists, adds `compilerOptions.baseUrl` and `compilerOptions.paths` for the aliases.
+7. Installs the latest `@worldware/msg` as a dependency.
+
+### create project
+
+Create a new MsgProject file in the i18n projects directory. Requires `package.json` with `directories.i18n` and `directories.l10n` (run `msg init` first).
+
+```bash
+msg create project <projectName> <source> <targets...> [--extend <name>]
+```
+
+| Argument     | Required | Description                              |
+|-------------|----------|------------------------------------------|
+| `projectName` | Yes      | Name of the project (used as file name). |
+| `source`      | Yes      | Source locale (e.g. `en`).               |
+| `targets`     | Yes (≥1) | Target locale(s), e.g. `fr`, `de`, `es`. |
+
+| Flag        | Short | Description                    |
+|------------|-------|--------------------------------|
+| `--extend` | `-e`  | Extend an existing project.   |
+| `--help`   | `-h`  | Show help for create project.  |
+
+**Examples:**
+
+```bash
+# Create project myApp with source en and targets fr, de
+msg create project myApp en fr de
+
+# Extend an existing project
+msg create project extendedApp en de --extend base
+
+# Help
+msg create project -h
+```
+
+**Behavior:**
+
+- Writes the file to `i18n/projects/<projectName>.js` or `.ts` (TypeScript if `tsconfig.json` exists).
+- Uses ES module or CommonJS export based on `package.json` `"type"`.
+- Generates a translation loader that imports from `l10n/translations` using the relative path from `i18n/projects` (from `directories` in package.json).
+- With `--extend <name>`, merges target locales and pseudoLocale from the existing project.
+- Errors if the project name already exists, package.json is missing or invalid, or required directories are not configured.
+
+### create resource
+
+Create a new MsgResource file in the i18n resources directory. Requires `msg init` and a project file in `i18n/projects` (run `msg create project` first).
+
+```bash
+msg create resource <projectName> <title> [-f] [-e]
+```
+
+| Argument     | Required | Description                                        |
+|-------------|----------|----------------------------------------------------|
+| `projectName` | Yes      | Name of the project to import in the MsgResource.  |
+| `title`       | Yes      | Title of the resource and file name (e.g. `messages` → `messages.msg.js`). |
+
+| Flag        | Short | Description                              |
+|------------|-------|------------------------------------------|
+| `--force`  | `-f`  | Overwrite an existing resource file.     |
+| `--edit`   | `-e`  | Open the file for editing after creation.|
+| `--help`   | `-h`  | Show help for create resource.           |
+
+**Examples:**
+
+```bash
+# Create resource messages for project myProject
+msg create resource myProject messages
+
+# Overwrite existing resource
+msg create resource myProject messages --force
+
+# Create and open in editor
+msg create resource myProject messages --edit
+```
+
+**Behavior:**
+
+- Writes the file to `i18n/resources/<title>.msg.js` or `.msg.ts` (TypeScript if `tsconfig.json` exists).
+- Uses ES module or CommonJS export based on `package.json` `"type"`.
+- Sets `lang` from the project's `sourceLocale` and `dir` to `rtl` for Arabic/Hebrew, `ltr` otherwise.
+- Includes a minimal example message. Validates that the generated file is importable.
+- Errors if i18n/projects or i18n/resources does not exist, the project is not found, or the resource file already exists (unless `--force`).
+
+## API Reference
+
+The CLI does not expose a programmatic API. For library usage, see [@worldware/msg](https://github.com/worldware-studios/msg).
+
+## Development
+
+- **Setup:** `npm install`
+- **Build:** `npm run build`
+- **Tests:** `npm run test`
+- **Coverage:** `npm run coverage`
+
+Source layout:
+
+- `src/commands/` — CLI commands (init, create/project, create/resource).
+- `src/lib/` — Shared utilities, init helpers, create-project helpers, and create-resource helpers.
+- `src/specs/` — Feature and command specs.
+- `src/tests/` — Vitest tests and fixtures.
+
+## License
+
+MIT. See [LICENSE](LICENSE).
+
+## Keywords
+
+i18n, l10n, internationalization, localization, xliff, msg, cli

package/bin/dev.cmd

@@ -0,0 +1,3 @@
+@echo off
+
+node "%~dp0\dev" %*

package/bin/dev.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node_modules/.bin/ts-node
+
+// eslint-disable-next-line unicorn/prefer-top-level-await
+;(async () => {
+  const oclif = await import('@oclif/core')
+  await oclif.execute({development: true, dir: __dirname})
+})()

package/bin/run.cmd

@@ -0,0 +1,3 @@
+@echo off
+
+node "%~dp0\run" %*

package/bin/run.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+
+// eslint-disable-next-line unicorn/prefer-top-level-await
+(async () => {
+  const oclif = await import('@oclif/core')
+  await oclif.execute({dir: __dirname})
+})()

package/dist/commands/create/project.js

@@ -0,0 +1,160 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const core_1 = require("@oclif/core");
+const fs_1 = require("fs");
+const path_1 = require("path");
+const create_project_helpers_js_1 = require("../../lib/create-project-helpers.js");
+const init_helpers_js_1 = require("../../lib/init-helpers.js");
+/**
+ * Creates a new MsgProject file in the i18n projects directory.
+ */
+class CreateProject extends core_1.Command {
+    run() {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a, _b;
+            const { argv, flags } = yield this.parse(CreateProject);
+            const [projectName, source, ...targets] = argv;
+            if (!(projectName === null || projectName === void 0 ? void 0 : projectName.trim())) {
+                this.error("projectName is required.", { exit: 1 });
+            }
+            if (!(source === null || source === void 0 ? void 0 : source.trim())) {
+                this.error("source locale is required.", { exit: 1 });
+            }
+            if (!(targets === null || targets === void 0 ? void 0 : targets.length) || targets.every((t) => !(t === null || t === void 0 ? void 0 : t.trim()))) {
+                this.error("At least one target locale is required.", { exit: 1 });
+            }
+            const cwd = process.cwd();
+            const pkgPath = (0, init_helpers_js_1.findPackageJsonPath)(cwd);
+            if (!pkgPath) {
+                this.error("package.json not found. Run this command from the project root.", { exit: 1 });
+            }
+            let pkg;
+            try {
+                pkg = (0, create_project_helpers_js_1.loadPackageJsonForCreateProject)(cwd);
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                this.error(msg, { exit: 1 });
+            }
+            const rootDir = (0, path_1.join)(pkgPath, "..");
+            const i18nDir = pkg.directories.i18n;
+            const l10nDir = pkg.directories.l10n;
+            const projectsDir = (0, path_1.join)(rootDir, i18nDir, "projects");
+            const translationsDir = (0, path_1.join)(rootDir, l10nDir, "translations");
+            const relPath = (0, create_project_helpers_js_1.calculateRelativePath)(projectsDir, translationsDir);
+            const useTypeScript = (0, fs_1.existsSync)((0, path_1.join)(rootDir, "tsconfig.json"));
+            const isEsm = pkg.type === "module";
+            const ext = useTypeScript ? ".ts" : ".js";
+            const outPath = (0, path_1.join)(projectsDir, `${projectName}${ext}`);
+            if ((0, fs_1.existsSync)(outPath)) {
+                this.error(`A project with the name '${projectName}' already exists.`, { exit: 1 });
+            }
+            let targetLocales = {};
+            let pseudoLocale = "en-XA";
+            if (flags.extend) {
+                const base = yield (0, create_project_helpers_js_1.importMsgProjectFile)(projectsDir, flags.extend);
+                if (!base) {
+                    this.error(`Project '${flags.extend}' could not be found to extend.`, { exit: 1 });
+                }
+                if (((_a = base.locales) === null || _a === void 0 ? void 0 : _a.targetLocales) && typeof base.locales.targetLocales === "object") {
+                    targetLocales = Object.assign({}, base.locales.targetLocales);
+                }
+                if ((_b = base.locales) === null || _b === void 0 ? void 0 : _b.pseudoLocale) {
+                    pseudoLocale = base.locales.pseudoLocale;
+                }
+            }
+            targetLocales[source] = [source];
+            for (const t of targets) {
+                if (t === null || t === void 0 ? void 0 : t.trim())
+                    targetLocales[t.trim()] = [t.trim()];
+            }
+            const loaderPathLine = "const path = `${TRANSLATION_IMPORT_PATH}/${project}/${language}/${title}.json`;";
+            const loaderWarnLine = "console.warn(`Translations for locale ${language} could not be loaded.`, error);";
+            const loaderBody = `${loaderPathLine}
+  try {
+    const module = await import(path, { with: { type: 'json' } });
+    return module.default;
+  } catch (error) {
+    ${loaderWarnLine}
+    return {
+      title,
+      attributes: { lang: language, dir: '' },
+      notes: [],
+      messages: []
+    };
+  }`;
+            const importPath = relPath.replace(/\\/g, "/");
+            const content = isEsm
+                ? `import { MsgProject } from '@worldware/msg';
+
+const TRANSLATION_IMPORT_PATH = ${JSON.stringify(importPath)};
+const loader = async (project, title, language) => {
+  ${loaderBody}
+};
+
+export default MsgProject.create({
+  project: { name: ${JSON.stringify(projectName)}, version: 1 },
+  locales: {
+    sourceLocale: ${JSON.stringify(source)},
+    pseudoLocale: ${JSON.stringify(pseudoLocale)},
+    targetLocales: ${JSON.stringify(targetLocales)}
+  },
+  loader
+});
+`
+                : `const { MsgProject } = require('@worldware/msg');
+
+const TRANSLATION_IMPORT_PATH = ${JSON.stringify(importPath)};
+const loader = async (project, title, language) => {
+  ${loaderBody}
+};
+
+module.exports = MsgProject.create({
+  project: { name: ${JSON.stringify(projectName)}, version: 1 },
+  locales: {
+    sourceLocale: ${JSON.stringify(source)},
+    pseudoLocale: ${JSON.stringify(pseudoLocale)},
+    targetLocales: ${JSON.stringify(targetLocales)}
+  },
+  loader
+});
+`;
+            this.log("Creating MsgProject file...");
+            (0, create_project_helpers_js_1.writeMsgProjectFile)(outPath, content);
+            this.log(`Created ${outPath}`);
+        });
+    }
+}
+CreateProject.description = "Create a new MsgProject file in the projects directory (i18n/projects)";
+CreateProject.strict = false;
+CreateProject.args = {
+    projectName: core_1.Args.string({
+        required: false,
+        description: "Name of the project (used as file name)",
+    }),
+    source: core_1.Args.string({
+        required: false,
+        description: "Source locale for the project",
+    }),
+    targets: core_1.Args.string({
+        required: false,
+        description: "Target locale(s) (variadic)",
+    }),
+};
+CreateProject.flags = {
+    help: core_1.Flags.help({ char: "h" }),
+    extend: core_1.Flags.string({
+        char: "e",
+        description: "Extend an existing project",
+    }),
+};
+exports.default = CreateProject;

package/dist/commands/create/resource.js

@@ -0,0 +1,169 @@
+"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;
+    };
+})();
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const core_1 = require("@oclif/core");
+const fs_1 = require("fs");
+const path_1 = require("path");
+const url_1 = require("url");
+const create_resource_helpers_js_1 = require("../../lib/create-resource-helpers.js");
+const init_helpers_js_1 = require("../../lib/init-helpers.js");
+/**
+ * Creates a new MsgResource file in the i18n resources directory.
+ */
+class CreateResource extends core_1.Command {
+    run() {
+        return __awaiter(this, void 0, void 0, function* () {
+            const { argv, flags } = yield this.parse(CreateResource);
+            const [projectName, title] = argv;
+            if (!(projectName === null || projectName === void 0 ? void 0 : projectName.trim())) {
+                this.error("projectName is required. Run 'msg init' first if you have not.", {
+                    exit: 1,
+                });
+            }
+            if (!(title === null || title === void 0 ? void 0 : title.trim())) {
+                this.error("title is required.", { exit: 1 });
+            }
+            const cwd = process.cwd();
+            const pkgPath = (0, init_helpers_js_1.findPackageJsonPath)(cwd);
+            if (!pkgPath) {
+                this.error("package.json not found. Run this command from the project root.", {
+                    exit: 1,
+                });
+            }
+            let pkgInfo;
+            try {
+                pkgInfo = (0, create_resource_helpers_js_1.readPackageJsonForCreateResource)(cwd);
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                this.error(msg, { exit: 1 });
+            }
+            const rootDir = (0, path_1.join)(pkgPath, "..");
+            const i18nDir = (0, path_1.join)(rootDir, pkgInfo.i18nDir);
+            const projectsDir = (0, path_1.join)(i18nDir, "projects");
+            const resourcesDir = (0, path_1.join)(i18nDir, "resources");
+            if (!(0, fs_1.existsSync)(i18nDir)) {
+                this.error(`i18n directory '${pkgInfo.i18nDir}' does not exist. Run 'msg init' first.`, { exit: 1 });
+            }
+            if (!(0, fs_1.existsSync)(projectsDir)) {
+                this.error(`i18n/projects directory does not exist. Run 'msg init' first.`, { exit: 1 });
+            }
+            if (!(0, fs_1.existsSync)(resourcesDir)) {
+                this.error(`i18n/resources directory does not exist. Run 'msg init' first.`, { exit: 1 });
+            }
+            const projectData = yield (0, create_resource_helpers_js_1.importMsgProjectForResource)(projectsDir, projectName.trim());
+            if (!projectData) {
+                this.error(`Project '${projectName}' not found or could not be loaded. Check i18n/projects for a matching file.`, { exit: 1 });
+            }
+            const ext = pkgInfo.useTypeScript ? ".ts" : ".js";
+            const outPath = (0, path_1.join)(resourcesDir, `${title.trim()}.msg${ext}`);
+            if ((0, fs_1.existsSync)(outPath) && !flags.force) {
+                this.error(`Resource file '${title.trim()}.msg${ext}' already exists. Use -f or --force to overwrite.`, { exit: 1 });
+            }
+            const content = (0, create_resource_helpers_js_1.generateMsgResourceContent)({
+                title: title.trim(),
+                projectName: projectName.trim(),
+                sourceLocale: projectData.sourceLocale,
+                dir: projectData.dir,
+                isEsm: pkgInfo.isEsm,
+            });
+            try {
+                (0, create_resource_helpers_js_1.writeMsgResourceFile)(outPath, content);
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                this.error(`Could not generate resource file: ${msg}`, { exit: 1 });
+            }
+            try {
+                const url = (0, url_1.pathToFileURL)(outPath).href;
+                yield Promise.resolve(`${url}`).then(s => __importStar(require(s)));
+            }
+            catch (err) {
+                try {
+                    (0, fs_1.unlinkSync)(outPath);
+                }
+                catch (_a) {
+                    // best-effort cleanup
+                }
+                const msg = err instanceof Error ? err.message : String(err);
+                this.error(`Generated file is invalid or not importable: ${msg}`, { exit: 1 });
+            }
+            this.log(`Created ${outPath}`);
+            if (flags.edit) {
+                const editor = process.env.VISUAL || process.env.EDITOR;
+                if (editor) {
+                    const { spawn } = yield Promise.resolve().then(() => __importStar(require("child_process")));
+                    spawn(editor, [outPath], { stdio: "inherit", detached: true });
+                }
+                else {
+                    this.warn("EDITOR or VISUAL not set. Open the file manually.");
+                }
+            }
+        });
+    }
+}
+CreateResource.description = "Create a new MsgResource file in the resources directory (i18n/resources)";
+CreateResource.strict = false;
+CreateResource.args = {
+    projectName: core_1.Args.string({
+        required: false,
+        description: "Name of the project to import in the MsgResource file",
+    }),
+    title: core_1.Args.string({
+        required: false,
+        description: "Title of the resource and file name for the file",
+    }),
+};
+CreateResource.flags = {
+    help: core_1.Flags.help({ char: "h" }),
+    force: core_1.Flags.boolean({
+        char: "f",
+        description: "Overwrite an existing resource file",
+    }),
+    edit: core_1.Flags.boolean({
+        char: "e",
+        description: "Open the file for editing after creation",
+    }),
+};
+exports.default = CreateResource;