tokvista 1.8.0 → 1.9.0

package/README.md

@@ -131,6 +131,22 @@ npx tokvista diff tokens-v1.json tokens-v2.json
 # - Migration tracking
 ```
 
+### Convert Formats
+
+```bash
+# Convert to W3C DTCG format
+npx tokvista convert tokens.json --to w3c --output tokens-w3c.json
+
+# Convert to Style Dictionary
+npx tokvista convert tokens.json --to style-dictionary --output tokens-sd.json
+
+# Convert to Supernova array format
+npx tokvista convert tokens.json --to supernova --output tokens-sn.json
+
+# Print to stdout
+npx tokvista convert tokens.json --to w3c
+```
+
 ### Interactive Setup
 
 ```bash
@@ -162,6 +178,7 @@ Then run `npx tokvista` to use your config.
 | `tokvista export <file> --format <type>` | Export tokens (css, scss, json, tailwind) |
 | `tokvista validate <file>` | Validate token structure and values |
 | `tokvista diff <old> <new>` | Compare two token files |
+| `tokvista convert <file> --to <format>` | Convert between token formats |
 | `--config`, `-c` | Config file path |
 | `--port`, `-p` | Server port (default: `3000`) |
 | `--format` | Export format (export only) |

package/dist/bin/tokvista.js

@@ -995,6 +995,99 @@ function diffTokens(oldTokens, newTokens) {
   return { added, removed, modified, unchanged };
 }
 
+// src/bin/converter.ts
+function isRecord6(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isTokenLike4(obj) {
+  return isRecord6(obj) && "value" in obj;
+}
+function toW3C(tokens) {
+  function walk(node) {
+    if (!isRecord6(node)) return node;
+    if (Object.keys(node).some((k) => k.includes("/"))) {
+      const result2 = {};
+      Object.entries(node).forEach(([key, val]) => {
+        Object.assign(result2, walk(val));
+      });
+      return result2;
+    }
+    if (isTokenLike4(node)) {
+      return {
+        $value: node.value,
+        ...node.type ? { $type: node.type } : {}
+      };
+    }
+    const result = {};
+    Object.entries(node).forEach(([key, val]) => {
+      result[key] = walk(val);
+    });
+    return result;
+  }
+  return walk(tokens);
+}
+function toStyleDictionary(tokens) {
+  function walk(node) {
+    if (!isRecord6(node)) return node;
+    if (Object.keys(node).some((k) => k.includes("/"))) {
+      const result2 = {};
+      Object.entries(node).forEach(([key, val]) => {
+        Object.assign(result2, walk(val));
+      });
+      return result2;
+    }
+    if (isTokenLike4(node)) {
+      return node;
+    }
+    const result = {};
+    Object.entries(node).forEach(([key, val]) => {
+      result[key] = walk(val);
+    });
+    return result;
+  }
+  return walk(tokens);
+}
+function toSupernova(tokens) {
+  const result = [];
+  let idCounter = 1;
+  function walk(node, path2 = []) {
+    if (!isRecord6(node)) return;
+    if (path2.length === 0 && Object.keys(node).some((k) => k.includes("/"))) {
+      Object.values(node).forEach((val) => walk(val, []));
+      return;
+    }
+    if (isTokenLike4(node)) {
+      result.push({
+        id: String(idCounter++),
+        name: path2[path2.length - 1] || "token",
+        tokenType: node.type || "unknown",
+        value: node.value
+      });
+      return;
+    }
+    Object.entries(node).forEach(([key, val]) => {
+      walk(val, [...path2, key]);
+    });
+  }
+  walk(tokens);
+  return result;
+}
+function convertTokenFormat(tokens, targetFormat) {
+  if (targetFormat === "token-studio") {
+    return tokens;
+  }
+  switch (targetFormat) {
+    case "w3c":
+      return toW3C(tokens);
+    case "style-dictionary":
+      return toStyleDictionary(tokens);
+    case "supernova":
+      return toSupernova(tokens);
+    default:
+      throw new Error(`Unsupported target format: ${targetFormat}`);
+  }
+}
+
 // src/bin/watcher.ts
 import { watch } from "fs";
 function watchFile(filePath, onChange) {
@@ -1028,6 +1121,7 @@ Usage:
   tokvista export <tokens.json> --format <css|scss|json|tailwind> [--output <file>]
   tokvista validate <tokens.json>
   tokvista diff <old.json> <new.json>
+  tokvista convert <tokens.json> --to <w3c|style-dictionary|supernova> [--output <file>]
 
 Arguments:
   tokens.json       Path to your tokens file (overrides config.tokens)
@@ -1160,6 +1254,9 @@ function parseArgs(args) {
   if (args[0] === "diff") {
     return parseDiffArgs(args.slice(1));
   }
+  if (args[0] === "convert") {
+    return parseConvertArgs(args.slice(1));
+  }
   return parseServeArgs(args);
 }
 function parseValidateArgs(args) {
@@ -1205,6 +1302,57 @@ function parseDiffArgs(args) {
   if (!newFileArg) throw new Error("New token file is required");
   return { command: "diff", oldFileArg, newFileArg };
 }
+function parseConvertArgs(args) {
+  let tokenFileArg;
+  let to;
+  let output;
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === "-h" || arg === "--help") {
+      printHelp();
+      process.exit(0);
+    }
+    if (arg === "--to") {
+      const next = args[index + 1];
+      if (!next) throw new Error("Missing value for --to");
+      if (!["w3c", "style-dictionary", "supernova", "token-studio"].includes(next)) {
+        throw new Error("Format must be: w3c, style-dictionary, supernova, or token-studio");
+      }
+      to = next;
+      index += 1;
+      continue;
+    }
+    if (arg === "--output" || arg === "-o") {
+      const next = args[index + 1];
+      if (!next) throw new Error("Missing value for --output");
+      output = next;
+      index += 1;
+      continue;
+    }
+    if (arg.startsWith("--to=")) {
+      const val = arg.slice("--to=".length);
+      if (!["w3c", "style-dictionary", "supernova", "token-studio"].includes(val)) {
+        throw new Error("Format must be: w3c, style-dictionary, supernova, or token-studio");
+      }
+      to = val;
+      continue;
+    }
+    if (arg.startsWith("--output=")) {
+      output = arg.slice("--output=".length);
+      continue;
+    }
+    if (arg.startsWith("-")) {
+      throw new Error(`Unknown option: ${arg}`);
+    }
+    if (tokenFileArg) {
+      throw new Error(`Only one token file is supported. Unexpected value: "${arg}"`);
+    }
+    tokenFileArg = arg;
+  }
+  if (!tokenFileArg) throw new Error("Token file is required for convert");
+  if (!to) throw new Error("--to is required (w3c, style-dictionary, supernova, or token-studio)");
+  return { command: "convert", tokenFileArg, to, output };
+}
 function parseExportArgs(args) {
   let tokenFileArg;
   let format;
@@ -1955,6 +2103,28 @@ Comparing tokens:
   console.log(`Total changes: ${diff.added.length + diff.removed.length + diff.modified.length}
 `);
 }
+async function runConvertCommand(cwd, options) {
+  const resolvedTokenPath = path.resolve(cwd, options.tokenFileArg);
+  if (!existsSync(resolvedTokenPath)) {
+    throw new Error(`Token file not found: ${resolvedTokenPath}`);
+  }
+  const tokens = await readTokens(resolvedTokenPath);
+  const detection = detectTokenFormat(tokens);
+  let normalizedTokens = tokens;
+  if (detection.format !== "token-studio" && detection.format !== "unknown") {
+    normalizedTokens = normalizeTokenFormat(tokens, detection.format);
+  }
+  const converted = convertTokenFormat(normalizedTokens, options.to);
+  const output = JSON.stringify(converted, null, 2);
+  if (options.output) {
+    const outputPath = path.resolve(cwd, options.output);
+    await writeFile(outputPath, output, "utf8");
+    console.log(`Converted ${detection.format} \u2192 ${options.to}`);
+    console.log(`Output: ${outputPath}`);
+  } else {
+    console.log(output);
+  }
+}
 async function main() {
   try {
     const options = parseArgs(process.argv.slice(2));
@@ -1978,6 +2148,10 @@ async function main() {
       await runDiffCommand(cwd, options);
       return;
     }
+    if (options.command === "convert") {
+      await runConvertCommand(cwd, options);
+      return;
+    }
     await runServeCommand(cwd, options);
   } catch (error) {
     console.error(error.message);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tokvista",
-  "version": "1.8.0",
+  "version": "1.9.0",
   "description": "Interactive visual documentation for design tokens.",
   "type": "module",
   "main": "./dist/index.cjs",