@react-native-rethemed/cli 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 manato
+
+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

@@ -1,3 +1,56 @@
-# Temporary Holding Version
+# @react-native-rethemed/cli
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![npm](https://img.shields.io/npm/v/@react-native-rethemed/cli.svg)](https://www.npmjs.com/package/@react-native-rethemed/cli)
+
+Code generator for [react-native-rethemed](https://github.com/manakuro/react-native-rethemed). Reads your theme and writes:
+
+- **`themed.gen.ts`** — token types, a JSDoc table of tokens and values on every token-aware prop (shown in editor hovers and autocomplete), and the ready-to-use `ThemedProvider` / `useThemed` / `useColorMode`.
+- **A token reference for AI agents** (`--docs`) — every token with its light/dark values, every text preset, and the rules for using them. Reference it from your `DESIGN.md` so coding agents use tokens instead of hard-coded values.
+
+## Installation
+
+```sh
+npm install @react-native-rethemed/core
+npm install --save-dev @react-native-rethemed/cli
+```
+
+## Usage
+
+```sh
+npx @react-native-rethemed/cli codegen src/theme/theme.ts --docs docs/themed.md
+```
+
+We recommend a script run from `prepare`, so the bindings are regenerated on every install:
+
+```json
+{
+  "scripts": {
+    "theme:codegen": "react-native-rethemed codegen src/theme/theme.ts --docs docs/themed.md",
+    "prepare": "npm run theme:codegen"
+  }
+}
+```
+
+The theme file is evaluated directly (TypeScript is supported, no build step), and validated before anything is written — for example, a text preset that references a missing `fontSizes` key fails with a clear message.
+
+## Options
+
+```
+Usage: react-native-rethemed codegen <theme-file> [options]
+
+Options:
+  -o, --out <file>      Output file (default: <theme-dir>/themed.gen.ts)
+  -d, --docs <file>     Also write a Markdown token reference for AI
+                        agents and humans (e.g. docs/themed.md)
+  -e, --export <name>   Export holding the config (default: the default
+                        export, or the only ThemeConfig-looking export)
+      --core <module>   Core module specifier used by the generated file
+                        (default: @react-native-rethemed/core)
+  -h, --help            Show this help
+```
+
+See the [main README](https://github.com/manakuro/react-native-rethemed#readme) for the generated API.
+
+## License
+
+MIT

package/bin/react-native-rethemed.mjs

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+// Runs the TypeScript sources through jiti, so no build step is needed while
+// the package lives in the monorepo (and `prepare` never races a build).
+import { createJiti } from 'jiti';
+
+const jiti = createJiti(import.meta.url);
+const { main } = await jiti.import('../src/cli.ts');
+await main(process.argv.slice(2));

package/package.json

@@ -1,6 +1,59 @@
 {
   "name": "@react-native-rethemed/cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.1",
+  "description": "CLI for react-native-rethemed: generates typed token docs (themed.gen.ts) and an AI-agent token reference from your theme.",
+  "keywords": [
+    "react-native",
+    "react-native-rethemed",
+    "design-tokens",
+    "codegen",
+    "cli",
+    "ai-agents"
+  ],
+  "license": "MIT",
+  "author": "manakuro",
+  "homepage": "https://github.com/manakuro/react-native-rethemed/tree/main/packages/react-native-rethemed/cli#readme",
+  "bugs": {
+    "url": "https://github.com/manakuro/react-native-rethemed/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/manakuro/react-native-rethemed.git",
+    "directory": "packages/react-native-rethemed/cli"
+  },
+  "type": "module",
+  "bin": {
+    "react-native-rethemed": "./bin/react-native-rethemed.mjs"
+  },
+  "files": [
+    "bin",
+    "src",
+    "!src/**/*.test.ts",
+    "!src/__fixtures__"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@clack/prompts": "1.8.1",
+    "@react-native-rethemed/core": "^0.1.1",
+    "jiti": "2.7.0"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.5.4",
+    "@types/node": "24.10.4",
+    "@types/react": "19.2.17",
+    "biome-config": "0.0.0",
+    "react": "19.2.3",
+    "react-native": "0.86.2",
+    "typescript": "6.0.3",
+    "vitest": "4.1.10"
+  },
+  "scripts": {
+    "lint": "biome check src bin",
+    "lint:fix": "biome check --write --unsafe src bin",
+    "tsc": "tsc --noEmit",
+    "test": "vitest",
+    "test:ci": "vitest run"
+  }
 }

package/src/cli.ts

@@ -0,0 +1,156 @@
+import path from 'node:path';
+import { parseArgs, styleText } from 'node:util';
+import * as p from '@clack/prompts';
+import { CodegenError, codegen, type TokenCounts } from './codegen';
+
+const USAGE = `Usage: react-native-rethemed codegen <theme-file> [options]
+
+Generates typed \`themed\` bindings (themed.gen.ts) from a theme config.
+
+Options:
+  -o, --out <file>      Output file (default: <theme-dir>/themed.gen.ts)
+  -d, --docs <file>     Also write a Markdown token reference for AI
+                        agents and humans (e.g. docs/themed.md)
+  -e, --export <name>   Export holding the config (default: the default
+                        export, or the only ThemeConfig-looking export)
+      --core <module>   Core module specifier used by the generated file
+                        (default: @react-native-rethemed/core)
+  -h, --help            Show this help`;
+
+const dim = (text: string) => styleText('dim', text);
+
+/** Paths as the user typed them: relative to where the command ran. */
+const display = (file: string) =>
+  path.relative(process.cwd(), file).split(path.sep).join('/');
+
+const COUNT_LABELS: [keyof TokenCounts, string][] = [
+  ['colors', 'semantic colors'],
+  ['primitiveColors', 'primitive colors'],
+  ['radii', 'radii'],
+  ['spacing', 'spacing'],
+  ['shadows', 'shadows'],
+  ['textPresets', 'text presets'],
+];
+
+/** `54 semantic colors · 11 radii · 35 spacing`, skipping empty categories. */
+export function formatCounts(counts: TokenCounts): string {
+  const parts = COUNT_LABELS.filter(([key]) => counts[key] > 0).map(
+    ([key, label]) => `${counts[key]} ${label}`,
+  );
+  return parts.length > 0 ? parts.join(' · ') : 'no tokens';
+}
+
+const STAGE_TITLES = {
+  load: 'Failed to load theme',
+  validate: 'Invalid theme config',
+  write: 'Failed to write output',
+} as const;
+
+const parseCodegenArgs = (args: string[]) =>
+  parseArgs({
+    args,
+    allowPositionals: true,
+    options: {
+      out: { type: 'string', short: 'o' },
+      docs: { type: 'string', short: 'd' },
+      export: { type: 'string', short: 'e' },
+      core: { type: 'string' },
+      help: { type: 'boolean', short: 'h' },
+    },
+  });
+
+async function runCodegen(args: string[]): Promise<void> {
+  let parsed: ReturnType<typeof parseCodegenArgs>;
+  try {
+    parsed = parseCodegenArgs(args);
+  } catch (error) {
+    // e.g. an unknown option or a missing option value
+    console.error(`${error instanceof Error ? error.message : error}\n`);
+    console.log(USAGE);
+    process.exitCode = 1;
+    return;
+  }
+  const { values, positionals } = parsed;
+
+  if (values.help || positionals.length !== 1) {
+    console.log(USAGE);
+    if (!values.help) process.exitCode = 1;
+    return;
+  }
+
+  const startedAt = performance.now();
+  p.intro('react-native-rethemed ⚡️');
+
+  try {
+    await codegen(
+      {
+        themeFile: positionals[0],
+        outFile: values.out,
+        exportName: values.export,
+        coreSpecifier: values.core,
+        docsFile: values.docs,
+      },
+      {
+        loaded: ({ themeFile, exportName }) =>
+          p.log.step(
+            `✅ Loaded theme  ${dim(`${display(themeFile)} (${exportName})`)}`,
+          ),
+        validated: (counts) =>
+          p.log.step(`✅ Validated tokens  ${dim(formatCounts(counts))}`),
+        warned: (warnings) =>
+          p.log.warn(
+            [
+              `⚠️  ${warnings.length === 1 ? '1 warning' : `${warnings.length} warnings`}`,
+              ...warnings.map((w) => dim(`  - ${w}`)),
+            ].join('\n'),
+          ),
+        written: ({ outFile, changed }) =>
+          p.log.step(
+            changed
+              ? `✅ Generated ${display(outFile)}`
+              : `⏭️  ${display(outFile)} ${dim('is up to date')}`,
+          ),
+        docsWritten: ({ docsFile, changed }) =>
+          p.log.step(
+            changed
+              ? `✅ Generated ${display(docsFile)}`
+              : `⏭️  ${display(docsFile)} ${dim('is up to date')}`,
+          ),
+      },
+    );
+  } catch (error) {
+    if (error instanceof CodegenError) {
+      const details = error.details.map((d) => dim(`  - ${d}`));
+      const title =
+        error.stage === 'validate'
+          ? STAGE_TITLES.validate
+          : `${STAGE_TITLES[error.stage]}: ${error.message}`;
+      p.log.error([`❌ ${title}`, ...details].join('\n'));
+    } else {
+      p.log.error(`❌ ${error instanceof Error ? error.message : error}`);
+    }
+    p.cancel('Failed');
+    process.exitCode = 1;
+    return;
+  }
+
+  p.outro(`🎉 Done in ${Math.round(performance.now() - startedAt)}ms`);
+}
+
+export async function main(argv: string[]): Promise<void> {
+  const [command, ...rest] = argv;
+  switch (command) {
+    case 'codegen':
+      await runCodegen(rest);
+      break;
+    case undefined:
+    case '-h':
+    case '--help':
+      console.log(USAGE);
+      break;
+    default:
+      console.error(`Unknown command: ${command}\n`);
+      console.log(USAGE);
+      process.exitCode = 1;
+  }
+}

package/src/codegen.ts

@@ -0,0 +1,216 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import {
+  type ThemeConfig,
+  walkSemanticColors,
+  walkTextPresets,
+} from '@react-native-rethemed/core/config';
+import { generateDocs } from './docs';
+import { generate } from './generate';
+import { loadTheme } from './load-theme';
+import { themeWarnings, validateTheme } from './validate';
+
+export type CodegenOptions = {
+  /** Theme file, absolute or relative to `cwd`. */
+  themeFile: string;
+  /** Output file. Defaults to `themed.gen.ts` next to the theme file. */
+  outFile?: string;
+  /** Export holding the config. Auto-detected when omitted. */
+  exportName?: string;
+  /** Core module specifier used by the generated file. */
+  coreSpecifier?: string;
+  /** Also write the Markdown token reference here (opt-in). */
+  docsFile?: string;
+  cwd?: string;
+};
+
+export type TokenCounts = {
+  /** Semantic colors (`semanticTokens.colors`). */
+  colors: number;
+  /** Primitive colors (`tokens.colors`). */
+  primitiveColors: number;
+  radii: number;
+  spacing: number;
+  fontSizes: number;
+  fontWeights: number;
+  lineHeights: number;
+  letterSpacings: number;
+  shadows: number;
+  textPresets: number;
+};
+
+export type CodegenResult = {
+  themeFile: string;
+  exportName: string;
+  outFile: string;
+  counts: TokenCounts;
+  /** Non-fatal theme problems (see `themeWarnings`). */
+  warnings: string[];
+  /** `false` when the output was already up to date (nothing written). */
+  changed: boolean;
+  /** Present when `docsFile` was requested. */
+  docs?: { file: string; changed: boolean };
+};
+
+/** Which step failed, so the CLI can say where things went wrong. */
+export type CodegenStage = 'load' | 'validate' | 'write';
+
+export class CodegenError extends Error {
+  constructor(
+    readonly stage: CodegenStage,
+    message: string,
+    readonly details: string[] = [],
+  ) {
+    super(message);
+    this.name = 'CodegenError';
+  }
+}
+
+/**
+ * Progress callbacks, fired as each step completes. The CLI renders them;
+ * tests and programmatic callers can ignore them and use the result.
+ */
+export type CodegenReporter = {
+  loaded?: (info: { themeFile: string; exportName: string }) => void;
+  validated?: (counts: TokenCounts) => void;
+  /** Only fired when there is something to warn about. */
+  warned?: (warnings: string[]) => void;
+  written?: (info: { outFile: string; changed: boolean }) => void;
+  docsWritten?: (info: { docsFile: string; changed: boolean }) => void;
+};
+
+const size = (table: object | undefined) => Object.keys(table ?? {}).length;
+
+function countPresets(config: ThemeConfig): number {
+  let count = 0;
+  walkTextPresets(config.semanticTokens?.text, () => {
+    count += 1;
+  });
+  return count;
+}
+
+export function countTokens(config: ThemeConfig): TokenCounts {
+  const tokens = config.tokens ?? {};
+  let colors = 0;
+  walkSemanticColors(config.semanticTokens?.colors, () => {
+    colors += 1;
+  });
+
+  return {
+    colors,
+    primitiveColors: size(tokens.colors),
+    radii: size(tokens.radii),
+    spacing: size(tokens.spacing),
+    fontSizes: size(tokens.fontSizes),
+    fontWeights: size(tokens.fontWeights),
+    lineHeights: size(tokens.lineHeights),
+    letterSpacings: size(tokens.letterSpacings),
+    shadows: size(tokens.shadows),
+    textPresets: countPresets(config),
+  };
+}
+
+/** `./theme` style specifier from the output file to the theme file. */
+function importSpecifier(fromFile: string, toFile: string): string {
+  const rel = path
+    .relative(path.dirname(fromFile), toFile)
+    .split(path.sep)
+    .join('/')
+    .replace(/\.[cm]?[jt]sx?$/, '');
+  return rel.startsWith('.') ? rel : `./${rel}`;
+}
+
+/** Writes only when the content differs; returns whether it wrote. */
+function writeIfChanged(file: string, content: string): boolean {
+  const current = existsSync(file) ? readFileSync(file, 'utf8') : null;
+  if (current === content) return false;
+  try {
+    mkdirSync(path.dirname(file), { recursive: true });
+    writeFileSync(file, content);
+  } catch (error) {
+    throw new CodegenError(
+      'write',
+      error instanceof Error ? error.message : String(error),
+    );
+  }
+  return true;
+}
+
+/**
+ * Load → validate → generate → write. Throws `CodegenError` tagged with the
+ * failing stage. Skips the write when the output is already identical, so
+ * Metro/tsc watchers don't churn.
+ */
+export async function codegen(
+  options: CodegenOptions,
+  reporter: CodegenReporter = {},
+): Promise<CodegenResult> {
+  const cwd = options.cwd ?? process.cwd();
+  const themeFile = path.resolve(cwd, options.themeFile);
+  const outFile = path.resolve(
+    cwd,
+    options.outFile ?? path.join(path.dirname(themeFile), 'themed.gen.ts'),
+  );
+
+  // --- load -----------------------------------------------------------------
+  if (!existsSync(themeFile)) {
+    throw new CodegenError('load', `${options.themeFile} not found`);
+  }
+  let loaded: Awaited<ReturnType<typeof loadTheme>>;
+  try {
+    loaded = await loadTheme(themeFile, options.exportName);
+  } catch (error) {
+    throw new CodegenError(
+      'load',
+      error instanceof Error ? error.message : String(error),
+    );
+  }
+  const { config, exportName } = loaded;
+  reporter.loaded?.({ themeFile, exportName });
+
+  // --- validate -------------------------------------------------------------
+  const problems = validateTheme(config);
+  if (problems.length > 0) {
+    throw new CodegenError('validate', 'Invalid theme config', problems);
+  }
+  const counts = countTokens(config);
+  reporter.validated?.(counts);
+  const warnings = themeWarnings(config);
+  if (warnings.length > 0) reporter.warned?.(warnings);
+
+  // --- generate & write -----------------------------------------------------
+  const toPosix = (file: string) =>
+    path.relative(cwd, file).split(path.sep).join('/');
+  const command = [
+    'react-native-rethemed codegen',
+    toPosix(themeFile),
+    ...(options.outFile ? ['--out', toPosix(outFile)] : []),
+    ...(options.docsFile
+      ? ['--docs', toPosix(path.resolve(cwd, options.docsFile))]
+      : []),
+  ].join(' ');
+
+  const source = generate({
+    config,
+    themeImport: { specifier: importSpecifier(outFile, themeFile), exportName },
+    coreSpecifier: options.coreSpecifier,
+    command,
+  });
+  const changed = writeIfChanged(outFile, source);
+  reporter.written?.({ outFile, changed });
+
+  let docs: CodegenResult['docs'];
+  if (options.docsFile) {
+    const docsFile = path.resolve(cwd, options.docsFile);
+    const markdown = generateDocs({
+      config,
+      themeFile: toPosix(themeFile),
+      genFile: toPosix(outFile),
+      command,
+    });
+    docs = { file: docsFile, changed: writeIfChanged(docsFile, markdown) };
+    reporter.docsWritten?.({ docsFile, changed: docs.changed });
+  }
+
+  return { themeFile, exportName, outFile, counts, warnings, changed, docs };
+}