@josui/token-studio 0.1.0

package/dist/cli.js

@@ -0,0 +1,676 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+import path7 from "path";
+import process from "process";
+import { Command } from "commander";
+import open from "open";
+
+// src/shared/constants.ts
+var SUPPORTED_TYPES = [
+  "color",
+  "dimension",
+  "duration",
+  "cubicBezier",
+  "fontFamily",
+  "number",
+  "string"
+];
+var DEFAULT_TOKENS_RELATIVE_DIR = "packages/tokens/src/tokens";
+var DEFAULT_TERRAZZO_RELATIVE_PATH = "packages/tokens/terrazzo.config.mjs";
+
+// src/shared/path-utils.ts
+import path from "path";
+function normalizeCategoryName(name) {
+  return name.trim().toLowerCase();
+}
+function categoryFileName(name) {
+  return `${name}.json`;
+}
+function validateCategoryName(name) {
+  if (!name) {
+    return "Category name is required";
+  }
+  if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(name)) {
+    return "Category name must be kebab-case";
+  }
+  return null;
+}
+function inferTerrazzoPathFromTokensDir(tokensDir, fallback) {
+  const normalized = path.normalize(tokensDir);
+  const suffix = path.normalize(path.join("src", "tokens"));
+  if (normalized.endsWith(suffix)) {
+    return path.join(normalized, "..", "..", "terrazzo.config.mjs");
+  }
+  return fallback;
+}
+
+// src/shared/config.ts
+import fs from "fs/promises";
+import path2 from "path";
+var CONFIG_FILE_NAMES = ["token-studio.config.json", ".token-studio.json"];
+async function exists(filePath) {
+  try {
+    await fs.access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function findConfigFile(startDir) {
+  let currentDir = path2.resolve(startDir);
+  while (true) {
+    for (const fileName of CONFIG_FILE_NAMES) {
+      const candidate = path2.join(currentDir, fileName);
+      if (await exists(candidate)) {
+        return candidate;
+      }
+    }
+    const parentDir = path2.dirname(currentDir);
+    if (parentDir === currentDir) {
+      break;
+    }
+    currentDir = parentDir;
+  }
+  return null;
+}
+async function readConfig(configPath) {
+  const content = await fs.readFile(configPath, "utf8");
+  const parsed = JSON.parse(content);
+  return parsed;
+}
+async function findNearestTokensRoot(startDir) {
+  let currentDir = path2.resolve(startDir);
+  while (true) {
+    const candidate = path2.join(currentDir, "packages/tokens/src/tokens");
+    if (await exists(candidate)) {
+      return candidate;
+    }
+    const parentDir = path2.dirname(currentDir);
+    if (parentDir === currentDir) {
+      break;
+    }
+    currentDir = parentDir;
+  }
+  return null;
+}
+
+// src/server/index.ts
+import { serve } from "@hono/node-server";
+import path6 from "path";
+
+// src/server/api.ts
+import path3 from "path";
+import fs2 from "fs/promises";
+import { Hono } from "hono";
+import { serveStatic } from "@hono/node-server/serve-static";
+
+// src/shared/schemas.ts
+import { z } from "zod";
+var supportedTypes = z.enum(SUPPORTED_TYPES);
+var createCategorySchema = z.object({
+  name: z.string().trim().min(1),
+  type: supportedTypes
+});
+var saveCategorySchema = z.object({
+  document: z.record(z.string(), z.unknown())
+});
+var validateSchema = z.object({
+  name: z.string().trim().min(1),
+  document: z.record(z.string(), z.unknown())
+});
+
+// src/shared/validators.ts
+function isObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isReferenceValue(value) {
+  return typeof value === "string" && /^\{[a-z0-9.-]+(?:\.[a-z0-9.-]+)*\}$/i.test(value);
+}
+function isSupportedType(type) {
+  return typeof type === "string" && SUPPORTED_TYPES.includes(type);
+}
+function validateTypedLiteral(type, value) {
+  if (isReferenceValue(value)) {
+    return null;
+  }
+  switch (type) {
+    case "color": {
+      if (!isObject(value)) {
+        return "Color value must be an object";
+      }
+      if (typeof value.colorSpace !== "string") {
+        return "Color value needs colorSpace";
+      }
+      if (!Array.isArray(value.components) || value.components.some((c) => typeof c !== "number")) {
+        return "Color value needs numeric components array";
+      }
+      return null;
+    }
+    case "dimension":
+    case "duration": {
+      if (!isObject(value)) {
+        return `${type} value must be an object`;
+      }
+      if (typeof value.value !== "number") {
+        return `${type} value needs numeric value`;
+      }
+      if (typeof value.unit !== "string") {
+        return `${type} value needs unit`;
+      }
+      return null;
+    }
+    case "cubicBezier": {
+      if (!Array.isArray(value) || value.length !== 4 || value.some((n) => typeof n !== "number")) {
+        return "cubicBezier value must be an array of four numbers";
+      }
+      return null;
+    }
+    case "fontFamily": {
+      if (typeof value === "string") {
+        return null;
+      }
+      if (Array.isArray(value) && value.every((part) => typeof part === "string")) {
+        return null;
+      }
+      return "fontFamily value must be string or string[]";
+    }
+    case "number": {
+      if (typeof value !== "number") {
+        return "number token must have numeric value";
+      }
+      return null;
+    }
+    case "string": {
+      if (typeof value !== "string") {
+        return "string token must have string value";
+      }
+      return null;
+    }
+    default:
+      return "Unsupported token type";
+  }
+}
+function validateCategoryDocument(name, document) {
+  const issues = [];
+  const rootKeys = Object.keys(document);
+  if (rootKeys.length !== 1) {
+    issues.push({ path: "$", message: "Document must contain exactly one root key" });
+    return { valid: false, issues };
+  }
+  const [rootKey] = rootKeys;
+  if (rootKey !== name) {
+    issues.push({ path: "$", message: `Root key must match category name "${name}"` });
+  }
+  const rootValue = document[rootKey];
+  if (!isObject(rootValue)) {
+    issues.push({ path: rootKey, message: "Root value must be an object" });
+    return { valid: false, issues };
+  }
+  function traverse(node, path8, context) {
+    const localType = isSupportedType(node.$type) ? node.$type : context.inheritedType;
+    const hasValue = Object.prototype.hasOwnProperty.call(node, "$value");
+    if (hasValue) {
+      if (!localType) {
+        issues.push({
+          path: path8,
+          message: "Token must define $type directly or inherit one from parent"
+        });
+      } else {
+        const typedIssue = validateTypedLiteral(localType, node.$value);
+        if (typedIssue) {
+          issues.push({ path: `${path8}.$value`, message: typedIssue });
+        }
+      }
+      if (Object.prototype.hasOwnProperty.call(node, "$extensions")) {
+        const extensions = node.$extensions;
+        if (!isObject(extensions)) {
+          issues.push({ path: `${path8}.$extensions`, message: "$extensions must be an object" });
+        } else if (Object.prototype.hasOwnProperty.call(extensions, "mode")) {
+          const mode = extensions.mode;
+          if (!isObject(mode)) {
+            issues.push({ path: `${path8}.$extensions.mode`, message: "mode must be an object" });
+          } else {
+            for (const modeKey of ["light", "dark"]) {
+              if (Object.prototype.hasOwnProperty.call(mode, modeKey) && localType) {
+                const typedIssue = validateTypedLiteral(localType, mode[modeKey]);
+                if (typedIssue) {
+                  issues.push({
+                    path: `${path8}.$extensions.mode.${modeKey}`,
+                    message: typedIssue
+                  });
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+    for (const [key, value] of Object.entries(node)) {
+      if (key.startsWith("$")) {
+        continue;
+      }
+      if (!isObject(value)) {
+        issues.push({ path: `${path8}.${key}`, message: "Group/token nodes must be objects" });
+        continue;
+      }
+      traverse(value, `${path8}.${key}`, {
+        inheritedType: localType
+      });
+    }
+  }
+  traverse(rootValue, rootKey, {
+    inheritedType: isSupportedType(rootValue.$type) ? rootValue.$type : void 0
+  });
+  return {
+    valid: issues.length === 0,
+    issues
+  };
+}
+
+// src/server/api.ts
+function createApi(repository, webDir) {
+  const app = new Hono();
+  app.get("/api/health", (context) => {
+    return context.json({
+      status: "ok",
+      tokensDir: repository.tokensDir,
+      terrazzoPath: repository.terrazzoPath
+    });
+  });
+  app.get("/api/categories", async (context) => {
+    const categories = await repository.listCategories();
+    return context.json({ categories });
+  });
+  app.get("/api/categories/:name", async (context) => {
+    const name = context.req.param("name");
+    try {
+      const category = await repository.getCategory(name);
+      return context.json(category);
+    } catch (error) {
+      return context.json({ error: error.message }, 404);
+    }
+  });
+  app.post("/api/categories", async (context) => {
+    const body = await context.req.json();
+    const parsed = createCategorySchema.safeParse(body);
+    if (!parsed.success) {
+      return context.json({ error: parsed.error.issues[0]?.message ?? "Invalid request" }, 400);
+    }
+    try {
+      const created = await repository.createCategory(parsed.data.name, parsed.data.type);
+      return context.json(created, 201);
+    } catch (error) {
+      return context.json({ error: error.message }, 400);
+    }
+  });
+  app.put("/api/categories/:name", async (context) => {
+    const name = context.req.param("name");
+    const body = await context.req.json();
+    const parsed = saveCategorySchema.safeParse(body);
+    if (!parsed.success) {
+      return context.json({ error: parsed.error.issues[0]?.message ?? "Invalid request" }, 400);
+    }
+    try {
+      const saved = await repository.saveCategory(name, parsed.data.document);
+      return context.json(saved);
+    } catch (error) {
+      return context.json({ error: error.message }, 400);
+    }
+  });
+  app.delete("/api/categories/:name", async (context) => {
+    const name = context.req.param("name");
+    await repository.deleteCategory(name);
+    return context.body(null, 204);
+  });
+  app.post("/api/validate", async (context) => {
+    const body = await context.req.json();
+    const parsed = validateSchema.safeParse(body);
+    if (!parsed.success) {
+      return context.json({ error: parsed.error.issues[0]?.message ?? "Invalid request" }, 400);
+    }
+    const result = validateCategoryDocument(parsed.data.name, parsed.data.document);
+    return context.json(result);
+  });
+  app.use("*", serveStatic({ root: webDir }));
+  app.get("*", async (context) => {
+    const requestPath = context.req.path;
+    if (requestPath.startsWith("/api/")) {
+      return context.notFound();
+    }
+    if (path3.extname(requestPath)) {
+      return context.notFound();
+    }
+    const indexPath = path3.join(webDir, "index.html");
+    try {
+      const html = await fs2.readFile(indexPath, "utf8");
+      return context.html(html);
+    } catch {
+      return context.text(
+        "Token Studio web assets are missing. Run `pnpm --filter @josui/token-studio build` first.",
+        503
+      );
+    }
+  });
+  return app;
+}
+
+// src/server/repository.ts
+import fs5 from "fs/promises";
+import path5 from "path";
+
+// src/shared/document.ts
+function isObject2(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function asSupportedType(value) {
+  if (value === "color" || value === "dimension" || value === "duration" || value === "cubicBezier" || value === "fontFamily" || value === "number" || value === "string") {
+    return value;
+  }
+  return void 0;
+}
+function flattenTokens(document) {
+  const rootKeys = Object.keys(document);
+  if (rootKeys.length !== 1) {
+    return [];
+  }
+  const [rootKey] = rootKeys;
+  const root = document[rootKey];
+  if (!isObject2(root)) {
+    return [];
+  }
+  const tokens = [];
+  function walk(node, currentPath, inheritedType) {
+    const localType = asSupportedType(node.$type) ?? inheritedType;
+    if (Object.prototype.hasOwnProperty.call(node, "$value") && localType) {
+      const entry = {
+        path: currentPath,
+        type: localType,
+        description: typeof node.$description === "string" ? node.$description : void 0,
+        value: node.$value,
+        hasMode: false
+      };
+      if (isObject2(node.$extensions) && isObject2(node.$extensions.mode)) {
+        entry.hasMode = true;
+        entry.mode = {
+          light: node.$extensions.mode.light,
+          dark: node.$extensions.mode.dark
+        };
+      }
+      tokens.push(entry);
+    }
+    for (const [key, value] of Object.entries(node)) {
+      if (key.startsWith("$")) {
+        continue;
+      }
+      if (!isObject2(value)) {
+        continue;
+      }
+      walk(value, `${currentPath}.${key}`, localType);
+    }
+  }
+  walk(root, rootKey, asSupportedType(root.$type));
+  return tokens.sort((a, b) => a.path.localeCompare(b.path));
+}
+
+// src/server/fs-utils.ts
+import fs3 from "fs/promises";
+import path4 from "path";
+import { randomUUID } from "crypto";
+async function readJsonFile(filePath) {
+  const content = await fs3.readFile(filePath, "utf8");
+  return JSON.parse(content);
+}
+async function writeJsonAtomic(filePath, document) {
+  const directory = path4.dirname(filePath);
+  const tempPath = path4.join(directory, `.${path4.basename(filePath)}.${randomUUID()}.tmp`);
+  const payload = `${JSON.stringify(document, null, 2)}
+`;
+  await fs3.writeFile(tempPath, payload, "utf8");
+  await fs3.rename(tempPath, filePath);
+}
+async function removeFileIfExists(filePath) {
+  try {
+    await fs3.unlink(filePath);
+  } catch (error) {
+    if (error.code !== "ENOENT") {
+      throw error;
+    }
+  }
+}
+async function ensureDirectory(directory) {
+  await fs3.mkdir(directory, { recursive: true });
+}
+
+// src/server/terrazzo.ts
+import fs4 from "fs/promises";
+function parseTokenArray(configContent) {
+  const match = /tokens\s*:\s*\[(?<entries>[\s\S]*?)\],/m.exec(configContent);
+  if (!match || !match.groups) {
+    return null;
+  }
+  const fullMatch = match[0];
+  const start = match.index;
+  const end = start + fullMatch.length;
+  const entriesBlock = match.groups.entries;
+  const entries = Array.from(entriesBlock.matchAll(/'([^']+)'/g), (entry) => entry[1]);
+  return {
+    entries,
+    start,
+    end
+  };
+}
+function formatTokenArray(entries) {
+  const formattedEntries = entries.map((entry) => `    '${entry}',`).join("\n");
+  return `tokens: [
+${formattedEntries}
+  ],`;
+}
+async function syncTerrazzoTokens(terrazzoPath, tokenRelativePath, operation) {
+  let configContent;
+  try {
+    configContent = await fs4.readFile(terrazzoPath, "utf8");
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      return;
+    }
+    throw error;
+  }
+  const parsed = parseTokenArray(configContent);
+  if (!parsed) {
+    return;
+  }
+  let nextEntries = parsed.entries;
+  if (operation === "add") {
+    if (!nextEntries.includes(tokenRelativePath)) {
+      nextEntries = [...nextEntries, tokenRelativePath];
+    }
+  } else {
+    nextEntries = nextEntries.filter((entry) => entry !== tokenRelativePath);
+  }
+  const replacement = formatTokenArray(nextEntries);
+  const nextConfig = `${configContent.slice(0, parsed.start)}${replacement}${configContent.slice(parsed.end)}`;
+  if (nextConfig !== configContent) {
+    await fs4.writeFile(terrazzoPath, nextConfig, "utf8");
+  }
+}
+
+// src/server/repository.ts
+var TokenRepository = class {
+  constructor(options) {
+    this.options = options;
+  }
+  get tokensDir() {
+    return this.options.tokensDir;
+  }
+  get terrazzoPath() {
+    return this.options.terrazzoPath;
+  }
+  async listCategories() {
+    await ensureDirectory(this.tokensDir);
+    const entries = await fs5.readdir(this.tokensDir, { withFileTypes: true });
+    const categories = [];
+    for (const entry of entries) {
+      if (!entry.isFile() || !entry.name.endsWith(".json")) {
+        continue;
+      }
+      const name = entry.name.replace(/\.json$/, "");
+      categories.push({
+        name,
+        fileName: entry.name,
+        path: path5.join(this.tokensDir, entry.name)
+      });
+    }
+    return categories.sort((a, b) => a.name.localeCompare(b.name));
+  }
+  categoryPath(name) {
+    return path5.join(this.tokensDir, categoryFileName(name));
+  }
+  async getCategory(name) {
+    const normalized = normalizeCategoryName(name);
+    const filePath = this.categoryPath(normalized);
+    const document = await readJsonFile(filePath);
+    return {
+      name: normalized,
+      document,
+      tokens: flattenTokens(document)
+    };
+  }
+  async createCategory(name, type) {
+    const normalized = normalizeCategoryName(name);
+    const nameError = validateCategoryName(normalized);
+    if (nameError) {
+      throw new Error(nameError);
+    }
+    const filePath = this.categoryPath(normalized);
+    try {
+      await fs5.access(filePath);
+      throw new Error(`Category ${normalized} already exists`);
+    } catch (error) {
+      if (error.code !== "ENOENT") {
+        throw error;
+      }
+    }
+    const document = {
+      [normalized]: {
+        $type: type
+      }
+    };
+    const validation = validateCategoryDocument(normalized, document);
+    if (!validation.valid) {
+      throw new Error(validation.issues[0]?.message ?? "Validation failed");
+    }
+    await writeJsonAtomic(filePath, document);
+    await syncTerrazzoTokens(
+      this.terrazzoPath,
+      `./src/tokens/${categoryFileName(normalized)}`,
+      "add"
+    );
+    return {
+      name: normalized,
+      document,
+      tokens: []
+    };
+  }
+  async saveCategory(name, document) {
+    const normalized = normalizeCategoryName(name);
+    const validation = validateCategoryDocument(normalized, document);
+    if (!validation.valid) {
+      throw new Error(
+        validation.issues.map((issue) => `${issue.path}: ${issue.message}`).join("\n")
+      );
+    }
+    const filePath = this.categoryPath(normalized);
+    await writeJsonAtomic(filePath, document);
+    return {
+      name: normalized,
+      document,
+      tokens: flattenTokens(document)
+    };
+  }
+  async deleteCategory(name) {
+    const normalized = normalizeCategoryName(name);
+    await removeFileIfExists(this.categoryPath(normalized));
+    await syncTerrazzoTokens(
+      this.terrazzoPath,
+      `./src/tokens/${categoryFileName(normalized)}`,
+      "remove"
+    );
+  }
+};
+
+// src/server/index.ts
+function startServer(options) {
+  const repository = new TokenRepository({
+    tokensDir: options.tokensDir,
+    terrazzoPath: options.terrazzoPath
+  });
+  const app = createApi(repository, path6.resolve(options.webDir));
+  const server = serve({
+    fetch: app.fetch,
+    port: options.port
+  });
+  return {
+    url: `http://127.0.0.1:${options.port}`,
+    stop: async () => {
+      await new Promise((resolve, reject) => {
+        server.close((error) => {
+          if (error) {
+            reject(error);
+            return;
+          }
+          resolve();
+        });
+      });
+    }
+  };
+}
+
+// src/cli.ts
+async function run() {
+  const program = new Command();
+  program.name("josui-token-studio").description("Launch local token CRUD editor").option("--cwd <path>", "Working directory", process.cwd()).option("--config <path>", "Path to token-studio config JSON").option("--tokens-dir <path>", "Tokens directory path").option("--port <number>", "Port to run local server", "4598").option("--no-open", "Do not open browser automatically");
+  program.parse(process.argv);
+  const options = program.opts();
+  const cwd = path7.resolve(options.cwd);
+  const explicitConfigPath = options.config ? path7.resolve(cwd, options.config) : null;
+  const discoveredConfigPath = explicitConfigPath ?? await findConfigFile(cwd);
+  const config = discoveredConfigPath ? await readConfig(discoveredConfigPath) : {};
+  const configBaseDir = discoveredConfigPath ? path7.dirname(discoveredConfigPath) : cwd;
+  const discoveredTokensDir = await findNearestTokensRoot(cwd);
+  const configTokensDir = config.tokensDir ? path7.resolve(configBaseDir, config.tokensDir) : void 0;
+  const tokensDir = path7.resolve(
+    options.tokensDir ?? configTokensDir ?? discoveredTokensDir ?? path7.join(cwd, DEFAULT_TOKENS_RELATIVE_DIR)
+  );
+  const defaultTerrazzoPath = path7.resolve(
+    config.terrazzoPath ? path7.resolve(configBaseDir, config.terrazzoPath) : path7.join(cwd, DEFAULT_TERRAZZO_RELATIVE_PATH)
+  );
+  const terrazzoPath = inferTerrazzoPathFromTokensDir(tokensDir, defaultTerrazzoPath);
+  const server = startServer({
+    tokensDir,
+    terrazzoPath,
+    port: Number(options.port),
+    webDir: path7.resolve(import.meta.dirname, "..", "dist", "web")
+  });
+  process.stdout.write(`Token Studio running at ${server.url}
+`);
+  if (discoveredConfigPath) {
+    process.stdout.write(`config: ${discoveredConfigPath}
+`);
+  }
+  process.stdout.write(`tokensDir: ${tokensDir}
+`);
+  process.stdout.write(`terrazzo: ${terrazzoPath}
+`);
+  if (options.open) {
+    await open(server.url);
+  }
+  const shutdown = async () => {
+    await server.stop();
+    process.exit(0);
+  };
+  process.on("SIGINT", shutdown);
+  process.on("SIGTERM", shutdown);
+}
+void run();
+//# sourceMappingURL=cli.js.map