intor-cli 0.0.1

package/README.md

@@ -0,0 +1,46 @@
+### Design Guarantees
+
+- Message types are inferred from the **_default locale_** only.
+- All locales are assumed to share the same message shape.
+- Locale is treated as a runtime dimension, not a structural one.
+- Generated types are intentionally conservative and do not validate locale completeness.
+
+### NOTE
+
+```
+(Core Modules)
+├── collect-messages
+├── extract-usages
+├── find-configs
+├── generate-types
+├── infer-schema
+├── validation
+```
+
+- pipeline: Collect messages
+
+```
+input: none (Detect from environment)
+|-> find-configs -> collect-messages
+```
+
+- pipeline: Generate intor schema
+
+```
+intput: collected messages
+|-> infer-schema (write file)
+```
+
+- pipeline: Generate intor types
+
+```
+intput: intor schema
+|-> generate-types (write file)
+```
+
+- pipeline: Validation
+
+```
+intput: intor schema
+|-> extract-usages -> validation
+```

package/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "intor-cli",
+  "version": "0.0.1",
+  "description": "Intor CLI",
+  "author": "Yiming Liao",
+  "homepage": "https://github.com/yiming-liao/intor-cli#readme",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/yiming-liao/intor-cli"
+  },
+  "bugs": {
+    "url": "https://github.com/yiming-liao/intor-cli/issues"
+  },
+  "keywords": [
+    "i18n"
+  ],
+  "license": "MIT",
+  "type": "module",
+  "files": [
+    "README.md",
+    "LICENSE",
+    "src"
+  ],
+  "engines": {
+    "node": ">=16.0.0"
+  },
+  "scripts": {
+    "intor": "tsx src/cli/index.ts",
+    "type": "tsc --noEmit",
+    "lint": "eslint",
+    "lint:debug": "eslint --debug",
+    "test": "vitest",
+    "test:check": "tsx scripts/check-test-structure.ts",
+    "knip": "knip --config .config/knip.config.ts"
+  },
+  "bin": {
+    "intor": "src/cli/index.ts"
+  },
+  "dependencies": {
+    "@intor/reader-md": "0.1.1",
+    "@intor/reader-yaml": "0.1.0",
+    "cac": "6.7.14",
+    "fast-glob": "3.3.3",
+    "intor": "2.3.17",
+    "logry": "2.1.6",
+    "ora": "9.0.0",
+    "picocolors": "1.1.1",
+    "ts-morph": "27.0.2",
+    "tsx": "4.21.0"
+  },
+  "devDependencies": {
+    "@types/node": "25.0.3",
+    "@vitest/coverage-v8": "4.0.16",
+    "eslint": "9.39.2",
+    "eslint-config-prettier": "10.1.8",
+    "eslint-import-resolver-typescript": "4.4.4",
+    "eslint-plugin-import": "2.32.0",
+    "eslint-plugin-prettier": "5.5.4",
+    "eslint-plugin-unicorn": "62.0.0",
+    "eslint-plugin-unused-imports": "4.3.0",
+    "knip": "5.79.0",
+    "prettier": "3.7.4",
+    "remark": "15.0.1",
+    "remark-gfm": "4.0.1",
+    "typescript": "5.9.3",
+    "typescript-eslint": "8.51.0",
+    "vitest": "4.0.16"
+  },
+  "peerDependencies": {},
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/build/build-schemas/build-schemas.ts

@@ -0,0 +1,13 @@
+import type { BuildInput, GeneratedSchema } from "../types";
+
+export function buildSchemas(inputs: BuildInput[]): GeneratedSchema {
+  return {
+    version: 1,
+    generatedAt: new Date().toISOString(),
+    configs: inputs.map((input) => ({
+      id: input.id,
+      locales: input.locales,
+      schemas: input.schemas,
+    })),
+  };
+}

package/src/build/build-schemas/index.ts

@@ -0,0 +1 @@
+export { buildSchemas } from "./build-schemas";

package/src/build/build-types/build-types.ts

@@ -0,0 +1,46 @@
+import type { BuildInput } from "../types";
+import { appendHeader, appendConfigBlock, appendFooter } from "./output";
+import { renderInferNode } from "./utils/render-infer-node";
+
+const GENERATED_INTERFACE_NAME = "IntorGeneratedTypes";
+
+/**
+ * Builds the global TypeScript declaration from inferred typegen inputs.
+ */
+export function buildTypes(inputs: BuildInput[]): string {
+  const lines: string[] = [];
+
+  // Global declaration header
+  appendHeader(lines, GENERATED_INTERFACE_NAME);
+
+  // Per-config processing
+  for (const [index, input] of inputs.entries()) {
+    const localesType = input.locales.map((l) => `"${l}"`).join(" | ");
+    const messagesType = renderInferNode(input.schemas.messagesSchema);
+    const replacementsType = renderInferNode(input.schemas.replacementsSchema);
+    const richType = renderInferNode(input.schemas.richSchema);
+
+    if (index === 0) {
+      appendConfigBlock(lines, {
+        id: "__default__",
+        locales: localesType,
+        messages: messagesType,
+        replacements: replacementsType,
+        rich: richType,
+      });
+    }
+
+    appendConfigBlock(lines, {
+      id: `"${input.id}"`,
+      locales: localesType,
+      messages: messagesType,
+      replacements: replacementsType,
+      rich: richType,
+    });
+  }
+
+  // Global declaration footer
+  appendFooter(lines);
+
+  return lines.join("\n");
+}

package/src/build/build-types/index.ts

@@ -0,0 +1 @@
+export { buildTypes } from "./build-types";

package/src/build/build-types/output/append-config-block.ts

@@ -0,0 +1,34 @@
+import { PREFIX_PLACEHOLDER } from "intor";
+import { indent } from "../utils/indent";
+
+function wrapWithLocale(type: string) {
+  return `{
+${indent(4)}"${PREFIX_PLACEHOLDER}": ${type};
+${indent(3)}}`;
+}
+
+export function appendConfigBlock(
+  lines: string[],
+  {
+    id,
+    locales,
+    messages,
+    replacements,
+    rich,
+  }: {
+    id: string;
+    locales: string;
+    messages: string;
+    replacements: string;
+    rich: string;
+  },
+) {
+  lines.push(
+    `${indent(2)}${id}: {`,
+    `${indent(3)}Locales: ${locales};`,
+    `${indent(3)}Messages: ${wrapWithLocale(messages)};`,
+    `${indent(3)}Replacements: ${wrapWithLocale(replacements)};`,
+    `${indent(3)}Rich: ${wrapWithLocale(rich)};`,
+    `${indent(2)}};`,
+  );
+}

package/src/build/build-types/output/append-footer.ts

@@ -0,0 +1,5 @@
+import { indent } from "../utils/indent";
+
+export function appendFooter(lines: string[]) {
+  lines.push(`${indent(1)}}`, `}`, `export type __dummy = void;`);
+}

package/src/build/build-types/output/append-header.ts

@@ -0,0 +1,11 @@
+import { indent } from "../utils/indent";
+
+export const INTOR_GENERATED_KEY = "__intor_generated__";
+
+export function appendHeader(lines: string[], interfaceName: string) {
+  lines.push(
+    `declare global {`,
+    `${indent(1)}interface ${interfaceName} {`,
+    `${indent(2)}${INTOR_GENERATED_KEY}: true;`,
+  );
+}

package/src/build/build-types/output/index.ts

@@ -0,0 +1,3 @@
+export { appendHeader } from "./append-header";
+export { appendConfigBlock } from "./append-config-block";
+export { appendFooter } from "./append-footer";

package/src/build/build-types/utils/indent.ts

@@ -0,0 +1,3 @@
+export function indent(level: number, step = 2) {
+  return " ".repeat(level * step);
+}

package/src/build/build-types/utils/render-infer-node.ts

@@ -0,0 +1,29 @@
+import type { InferNode } from "../../../core/infer-schema";
+import { indent } from "./indent";
+
+export function renderInferNode(node: InferNode, indentLevel = 4): string {
+  switch (node.kind) {
+    case "none": {
+      return "unknown";
+    }
+    case "primitive": {
+      return node.type;
+    }
+    case "array": {
+      return `${renderInferNode(node.element, indentLevel)}[]`;
+    }
+    case "record": {
+      return "Record<string, unknown>";
+    }
+    case "object": {
+      return `{
+${Object.entries(node.properties)
+  .map(
+    ([k, v]) =>
+      `${indent(indentLevel)}  "${k}": ${renderInferNode(v, indentLevel + 1)};`,
+  )
+  .join("\n")}
+${indent(indentLevel)}}`;
+    }
+  }
+}

package/src/build/index.ts

@@ -0,0 +1,3 @@
+export { buildTypes } from "./build-types";
+export { buildSchemas } from "./build-schemas";
+export type { BuildInput, GeneratedSchema } from "./types";

package/src/build/types.ts

@@ -0,0 +1,19 @@
+import type { InferredSchemas } from "../core";
+
+export interface BuildInput {
+  id: string;
+  locales: readonly string[];
+  schemas: InferredSchemas;
+}
+
+// Schema
+export interface GeneratedSchema {
+  version: number;
+  generatedAt: string;
+  configs: GeneratedSchemaConfig[];
+}
+export interface GeneratedSchemaConfig {
+  id: string;
+  locales: readonly string[];
+  schemas: InferredSchemas;
+}

package/src/cli/commands/check.ts

@@ -0,0 +1,50 @@
+import type { ReadGeneratedSchemaOptions } from "../../core";
+import type { ExtractUsagesOptions } from "../../core/extract-usages/extract-usages";
+import type { CAC } from "cac";
+import { check } from "../../features";
+
+export function registerCheckCommand(cli: CAC) {
+  cli
+    // -----------------------------------------------------------------------
+    // Command
+    // -----------------------------------------------------------------------
+    .command("check", "Validate intor translation usage")
+
+    // -----------------------------------------------------------------------
+    // Option
+    // -----------------------------------------------------------------------
+    // Read generated schema options
+    .option(
+      "--cwd <path>",
+      "Working directory for resolving intor config (default: process.cwd())",
+    )
+    .option(
+      "--file-name <name>",
+      "Generated schema file name (default: intor-generated.schema.json)",
+    )
+    .option(
+      "--out-dir <path>",
+      "Directory of generated schema output (default: .intor)",
+    )
+    // Extract usages options
+    .option(
+      "--tsconfig <path>",
+      "Path to tsconfig.json (default: tsconfig.json)",
+    )
+    .option("--debug", "Enable debug logging")
+
+    // -----------------------------------------------------------------------
+    // Action
+    // -----------------------------------------------------------------------
+    .action(
+      async (options: ReadGeneratedSchemaOptions & ExtractUsagesOptions) => {
+        const { cwd, fileName, outDir, tsconfigPath, debug } = options;
+        try {
+          await check({ cwd, fileName, outDir }, { tsconfigPath, debug });
+        } catch (error) {
+          console.error(error);
+          process.exitCode = 1;
+        }
+      },
+    );
+}

package/src/cli/commands/generate.ts

@@ -0,0 +1,61 @@
+import type { ExtraExt } from "../../core";
+import type { CAC } from "cac";
+import { generate } from "../../features";
+
+export function registerGenerateCommand(cli: CAC) {
+  cli
+    // -----------------------------------------------------------------------
+    // Command
+    // -----------------------------------------------------------------------
+    .command("generate", "Generate intor types and schemas")
+
+    // -----------------------------------------------------------------------
+    // Option
+    // -----------------------------------------------------------------------
+    .option(
+      "--ext <ext>",
+      "Enable extra messages file extension (repeatable)",
+      { default: [] },
+    )
+    .option(
+      "--reader <mapping>",
+      "Custom reader mapping in the form <ext=path> (repeatable)",
+      { default: [] },
+    )
+    .option(
+      "--debug",
+      "Print debug information during config discovery and generation",
+    )
+
+    // -----------------------------------------------------------------------
+    // Action
+    // -----------------------------------------------------------------------
+    .action(async (options) => {
+      const { ext, reader, debug } = options as {
+        ext?: Array<ExtraExt>;
+        reader?: string[];
+        debug?: boolean;
+      };
+
+      // Normalize exts
+      const exts = ext ? (Array.isArray(ext) ? ext : [ext]) : [];
+
+      // Parse customReaders: ["md=./my-md-reader.ts"] → { md: "./my-md-reader.ts" }
+      let customReaders: Record<string, string> | undefined;
+      if (reader && reader.length > 0) {
+        customReaders = {};
+        for (const item of reader) {
+          const [key, value] = item.split("=", 2);
+          if (!key || !value) continue;
+          customReaders[key] = value;
+        }
+      }
+
+      try {
+        await generate({ exts, customReaders, debug });
+      } catch (error) {
+        console.error(error);
+        process.exitCode = 1;
+      }
+    });
+}

package/src/cli/index.ts

@@ -0,0 +1,24 @@
+#!/usr/bin/env tsx
+
+import { cac } from "cac";
+import { registerCheckCommand } from "./commands/check";
+import { registerGenerateCommand } from "./commands/generate";
+
+const cli = cac("intor");
+
+// ---------------------------------------------------------------------
+// Register commands
+// ---------------------------------------------------------------------
+registerGenerateCommand(cli);
+registerCheckCommand(cli);
+
+// ---------------------------------------------------------------------
+// Global options / help
+// ---------------------------------------------------------------------
+cli.help();
+cli.version("0.1.10");
+
+// ---------------------------------------------------------------------
+// Parse argv
+// ---------------------------------------------------------------------
+cli.parse();

package/src/core/collect-messages/collect-runtime-messages.ts

@@ -0,0 +1,76 @@
+import type { ExtraExt } from "../../core";
+import {
+  mergeMessages,
+  resolveLoaderOptions,
+  type IntorResolvedConfig,
+  type LocaleMessages,
+  type MessagesReaders,
+} from "intor";
+import { loadMessages } from "intor/server";
+import { getBuiltInReaders } from "../collect-messages/readers";
+import { resolveMessagesReader } from "./resolve-messages-reader";
+
+/**
+ * Collect runtime messages for a given locale.
+ *
+ * Precedence: client-side runtime > server-side runtime > static messages.
+ */
+export async function collectRuntimeMessages(
+  config: IntorResolvedConfig,
+  locale: string,
+  exts: Array<ExtraExt> = [],
+  customReaders?: Record<string, string>, // {ext, customReaderFilePath}
+): Promise<LocaleMessages> {
+  // ----------------------------------------------------------------------
+  // Resolve readers
+  // ----------------------------------------------------------------------
+  // Resolve optional custom readers
+  const resolvedCustomReaders: MessagesReaders = {};
+  for (const [ext, filePath] of Object.entries(customReaders || {})) {
+    const resolved = await resolveMessagesReader(filePath);
+    if (resolved) resolvedCustomReaders[ext] = resolved;
+  }
+  const readers = { ...getBuiltInReaders(exts), ...resolvedCustomReaders };
+
+  // ----------------------------------------------------------------------
+  // Load runtime messages
+  // ----------------------------------------------------------------------
+  let serverMessages: LocaleMessages | undefined;
+  let clientMessages: LocaleMessages | undefined;
+
+  // Load server-side runtime messages
+  if (config.loader || config.server?.loader) {
+    const serverLoader = resolveLoaderOptions(config, "server");
+    if (serverLoader) {
+      serverMessages = await loadMessages({
+        config: { ...config, loader: serverLoader },
+        locale,
+        readers,
+      });
+    }
+  }
+
+  // Load client-side runtime messages
+  if (config.client?.loader) {
+    const clientLoader = resolveLoaderOptions(config, "client");
+    if (clientLoader) {
+      clientMessages = await loadMessages({
+        config: { ...config, loader: clientLoader },
+        locale,
+        readers,
+      });
+    }
+  }
+
+  // ----------------------------------------------------------------------
+  // Merge messages
+  // ----------------------------------------------------------------------
+  // client-side runtime > server-side runtime
+  const runtimeMessages = mergeMessages(serverMessages, clientMessages, {
+    config,
+    locale,
+  });
+
+  // runtime messages > static messages
+  return mergeMessages(config.messages, runtimeMessages, { config, locale });
+}

package/src/core/collect-messages/index.ts

@@ -0,0 +1 @@
+export { collectRuntimeMessages } from "./collect-runtime-messages";

package/src/core/collect-messages/readers.ts

@@ -0,0 +1,23 @@
+import type { ExtraExt } from "../../core/constants";
+import type { MessagesReader, MessagesReaders } from "intor";
+import { mdReader } from "@intor/reader-md";
+import { yamlReader } from "@intor/reader-yaml";
+
+export const BUILTIN_READERS: Record<ExtraExt, MessagesReader> = {
+  md: mdReader,
+  yaml: yamlReader,
+};
+
+export const getBuiltInReaders = (
+  exts: readonly ExtraExt[],
+): MessagesReaders => {
+  // Map to [ext, reader]
+  const entries = exts
+    .map((ext) => {
+      const reader = BUILTIN_READERS[ext];
+      return reader ? [ext, reader] : null;
+    })
+    .filter((e): e is [ExtraExt, MessagesReader] => e !== null);
+  // Entries to object
+  return Object.fromEntries(entries);
+};

package/src/core/collect-messages/resolve-messages-reader.ts

@@ -0,0 +1,57 @@
+import type { MessagesReader } from "intor";
+import fs from "node:fs/promises";
+import path from "node:path";
+
+/**
+ * Resolve a MessagesReader from a module path.
+ *
+ * Resolution order:
+ * 1. Default export
+ * 2. First exported function (fallback)
+ */
+export async function resolveMessagesReader(
+  filePath?: string,
+): Promise<MessagesReader | undefined> {
+  if (!filePath) return;
+
+  const absolutePath = path.resolve(process.cwd(), filePath);
+
+  // ----------------------------------------------------------------------
+  // Ensure the file exists before attempting dynamic import
+  // ----------------------------------------------------------------------
+  try {
+    await fs.access(absolutePath);
+  } catch {
+    throw new Error(`[intor] Reader file not found: ${filePath}`);
+  }
+
+  // ----------------------------------------------------------------------
+  // Resolve reader module exports
+  // ----------------------------------------------------------------------
+  // Dynamically import the reader module
+  const moduleExports = await import(absolutePath);
+
+  // Prefer default export
+  let reader = moduleExports.default;
+
+  // Fallback to the first exported function
+  if (typeof reader !== "function") {
+    for (const value of Object.values(moduleExports)) {
+      if (typeof value === "function") {
+        reader = value;
+        break;
+      }
+    }
+  }
+
+  // ----------------------------------------------------------------------
+  // Validate resolved reader
+  // ----------------------------------------------------------------------
+  if (typeof reader !== "function") {
+    throw new Error(
+      `[intor] No function export found in reader module: ${filePath}`,
+    );
+  }
+
+  return reader;
+}

package/src/core/constants/extra-exts.ts

@@ -0,0 +1,2 @@
+export const EXTRA_EXTS = ["md", "yaml"] as const;
+export type ExtraExt = (typeof EXTRA_EXTS)[number];

package/src/core/constants/generated-files.ts

@@ -0,0 +1,3 @@
+export const DEFAULT_OUT_DIR = ".intor";
+export const DEFAULT_TYPES_FILE = "intor-generated-types.d.ts";
+export const DEFAULT_SCHEMA_FILE = "intor-generated.schema.json";

package/src/core/constants/index.ts

@@ -0,0 +1,7 @@
+export {
+  DEFAULT_OUT_DIR,
+  DEFAULT_TYPES_FILE,
+  DEFAULT_SCHEMA_FILE,
+} from "./generated-files";
+
+export { EXTRA_EXTS, type ExtraExt } from "./extra-exts";