@tokens-studio/tokenscript-schemas 0.0.11 → 0.0.12

package/src/cli/commands/list.ts

@@ -0,0 +1,109 @@
+/**
+ * List command - Display available schemas
+ */
+
+/// <reference types="../../../types/ulog" />
+
+import { readdir } from "node:fs/promises";
+import { join } from "node:path";
+import anylogger from "ulog";
+
+const log = anylogger("list");
+
+export interface ListOptions {
+  types?: boolean;
+  functions?: boolean;
+}
+
+interface ListResult {
+  types: string[];
+  functions: string[];
+}
+
+/**
+ * List all available schemas
+ */
+export async function listSchemas(
+  schemasDir: string = join(process.cwd(), "src/schemas"),
+  options: ListOptions = {},
+): Promise<ListResult> {
+  const showTypes = options.types || (!options.types && !options.functions);
+  const showFunctions = options.functions || (!options.types && !options.functions);
+
+  const types: string[] = [];
+  const functions: string[] = [];
+
+  // List type schemas
+  if (showTypes) {
+    try {
+      const typesDir = join(schemasDir, "types");
+      const typeEntries = await readdir(typesDir, { withFileTypes: true });
+      types.push(
+        ...typeEntries
+          .filter((entry) => entry.isDirectory())
+          .map((entry) => entry.name)
+          .sort(),
+      );
+    } catch (error) {
+      log.warn("Could not read types directory:", error);
+    }
+  }
+
+  // List function schemas
+  if (showFunctions) {
+    try {
+      const functionsDir = join(schemasDir, "functions");
+      const funcEntries = await readdir(functionsDir, { withFileTypes: true });
+      functions.push(
+        ...funcEntries
+          .filter((entry) => entry.isDirectory())
+          .map((entry) => entry.name)
+          .sort(),
+      );
+    } catch (error) {
+      log.warn("Could not read functions directory:", error);
+    }
+  }
+
+  return { types, functions };
+}
+
+/**
+ * Format list output for display
+ */
+export function formatListOutput(result: ListResult, options: ListOptions = {}): string {
+  const lines: string[] = [];
+
+  const showTypes = options.types || (!options.types && !options.functions);
+  const showFunctions = options.functions || (!options.types && !options.functions);
+
+  if (showTypes && result.types.length > 0) {
+    lines.push("Types:");
+    for (const type of result.types) {
+      lines.push(`  ${type}`);
+    }
+  }
+
+  if (showFunctions && result.functions.length > 0) {
+    if (lines.length > 0) lines.push("");
+    lines.push("Functions:");
+    for (const func of result.functions) {
+      lines.push(`  function:${func}`);
+    }
+  }
+
+  if (lines.length === 0) {
+    lines.push("No schemas found.");
+  }
+
+  return lines.join("\n");
+}
+
+/**
+ * CLI action handler for list command
+ */
+export async function handleListCommand(options: ListOptions = {}): Promise<void> {
+  const result = await listSchemas(undefined, options);
+  const output = formatListOutput(result, options);
+  console.log(output);
+}

package/src/cli/config-schema.ts

@@ -0,0 +1,36 @@
+/**
+ * Config file schema validation
+ */
+
+export interface BundleConfig {
+  schemas: string[];
+  output?: string;
+}
+
+/**
+ * Validate bundle config
+ */
+export function validateBundleConfig(data: unknown): BundleConfig {
+  if (typeof data !== "object" || data === null) {
+    throw new Error("Config must be an object");
+  }
+
+  const config = data as Record<string, unknown>;
+
+  if (!Array.isArray(config.schemas)) {
+    throw new Error("Config must have a 'schemas' array");
+  }
+
+  if (!config.schemas.every((s) => typeof s === "string")) {
+    throw new Error("All schemas must be strings");
+  }
+
+  if (config.output !== undefined && typeof config.output !== "string") {
+    throw new Error("Config 'output' must be a string if provided");
+  }
+
+  return {
+    schemas: config.schemas,
+    output: config.output as string | undefined,
+  };
+}

package/src/cli/index.ts

@@ -0,0 +1,50 @@
+#!/usr/bin/env node
+
+/**
+ * CLI entry point for @tokens-studio/tokenscript-schemas
+ */
+
+/// <reference types="../../types/ulog" />
+
+import cac from "cac";
+import anylogger from "ulog";
+import { type BundleOptions, handleBundleCommand } from "./commands/bundle.js";
+import { handleListCommand, type ListOptions } from "./commands/list.js";
+
+const log = anylogger("cli");
+
+const cli = cac("tokenscript-schemas");
+
+// Bundle command
+cli
+  .command("bundle [...schemas]", "Bundle schemas into a JS file")
+  .option("-c, --config <path>", "Path to config file")
+  .option("-o, --output <path>", "Output file path", { default: "./tokenscript-schemas.js" })
+  .option("-d, --dry-run", "Preview what would be bundled without writing")
+  .action(async (schemas: string[], options: BundleOptions) => {
+    try {
+      await handleBundleCommand(schemas, options);
+    } catch (error) {
+      log.error("Error:", error);
+      process.exit(1);
+    }
+  });
+
+// List command
+cli
+  .command("list", "List available schemas")
+  .option("--types", "List only type schemas")
+  .option("--functions", "List only function schemas")
+  .action(async (options: ListOptions) => {
+    try {
+      await handleListCommand(options);
+    } catch (error) {
+      log.error("Error:", error);
+      process.exit(1);
+    }
+  });
+
+cli.help();
+cli.version("0.0.12");
+
+cli.parse();

package/src/cli/output-generator.ts

@@ -0,0 +1,63 @@
+/**
+ * Generate JavaScript output for bundled schemas
+ */
+
+import type { BundledSchemaEntry } from "@/bundler/selective-bundler.js";
+
+export interface OutputGeneratorOptions {
+  schemas: BundledSchemaEntry[];
+  includeHelper?: boolean; // Include makeConfig() helper
+}
+
+/**
+ * Generate JavaScript code for bundled schemas
+ */
+export function generateOutput(options: OutputGeneratorOptions): string {
+  const { schemas, includeHelper = true } = options;
+
+  const timestamp = new Date().toISOString();
+  const schemaList = schemas.map((s) => s.uri).join(", ");
+
+  const lines: string[] = [];
+
+  // Header comment
+  lines.push("// Auto-generated by @tokens-studio/tokenscript-schemas");
+  lines.push(`// Generated: ${timestamp}`);
+  lines.push(`// Schemas: ${schemaList}`);
+  lines.push("");
+
+  // Import statement
+  lines.push('import { Config } from "@tokens-studio/tokenscript-interpreter";');
+  lines.push("");
+
+  // SCHEMAS export
+  lines.push("export const SCHEMAS = [");
+  for (const entry of schemas) {
+    // Format each schema entry - we need to serialize both uri and schema
+    const schemaJson = JSON.stringify(entry.schema, null, 2);
+    const uriJson = JSON.stringify(entry.uri);
+
+    // Indent the schema JSON
+    const indentedSchema = schemaJson
+      .split("\n")
+      .map((line) => `    ${line}`)
+      .join("\n");
+
+    lines.push(`  {`);
+    lines.push(`    uri: ${uriJson},`);
+    lines.push(`    schema: ${indentedSchema.trim()}`);
+    lines.push(`  },`);
+  }
+  lines.push("];");
+  lines.push("");
+
+  // Helper function
+  if (includeHelper) {
+    lines.push("export function makeConfig() {");
+    lines.push("  return new Config().registerSchemas(SCHEMAS);");
+    lines.push("}");
+    lines.push("");
+  }
+
+  return lines.join("\n");
+}

package/src/downloader/index.ts

@@ -0,0 +1,248 @@
+/**
+ * Schema downloader - fetches schemas from the TokenScript API
+ */
+
+import { mkdir, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import type {
+  SchemaConfig,
+  SchemaDetails,
+  SchemaListItem,
+  SchemaVersion,
+} from "@/downloader/types.js";
+
+const DEFAULT_CONFIG: SchemaConfig = {
+  apiBaseUrl: "https://schema.tokenscript.dev.gcp.tokens.studio/api/v1",
+  outputDir: "src/schemas",
+  targetVersion: "0.0.10",
+};
+
+/**
+ * Fetch all schemas from the API
+ */
+export async function fetchSchemaList(
+  config: SchemaConfig = DEFAULT_CONFIG,
+): Promise<SchemaListItem[]> {
+  const url = `${config.apiBaseUrl}/schema/?format=json`;
+
+  console.log(`Fetching schema list from ${url}...`);
+  const response = await fetch(url);
+
+  if (!response.ok) {
+    throw new Error(`Failed to fetch schemas: ${response.statusText}`);
+  }
+
+  const data = (await response.json()) as SchemaListItem[];
+  console.log(`Found ${data.length} schemas`);
+
+  return data;
+}
+
+/**
+ * Fetch versions for a schema
+ */
+export async function fetchSchemaVersions(
+  schemaSlug: string,
+  config: SchemaConfig = DEFAULT_CONFIG,
+): Promise<SchemaVersion[]> {
+  const url = `${config.apiBaseUrl}/schema/${schemaSlug}/versions/?format=json`;
+
+  const response = await fetch(url);
+
+  if (!response.ok) {
+    throw new Error(`Failed to fetch versions for ${schemaSlug}: ${response.statusText}`);
+  }
+
+  return (await response.json()) as SchemaVersion[];
+}
+
+/**
+ * Create the folder structure for a schema
+ */
+async function createSchemaFolder(
+  schemaSlug: string,
+  schemaType: "type" | "function",
+  baseDir: string,
+): Promise<string> {
+  const schemaPath = join(baseDir, schemaType === "type" ? "types" : "functions", schemaSlug);
+  await mkdir(schemaPath, { recursive: true });
+  return schemaPath;
+}
+
+/**
+ * Write schema.json file
+ */
+async function writeSchemaJson(
+  schemaPath: string,
+  schema: SchemaDetails,
+  targetVersion: string,
+): Promise<void> {
+  const content = schema.content as any;
+
+  const schemaJson = {
+    id: schema.id,
+    slug: schema.slug,
+    name: schema.name,
+    description: schema.description,
+    type: schema.type,
+    version: targetVersion,
+    originalVersion: schema.version,
+    contentType: content.type || null,
+    metadata: schema.metadata || {},
+  };
+
+  await writeFile(join(schemaPath, "schema.json"), JSON.stringify(schemaJson, null, 2));
+}
+
+/**
+ * Generate a unit test stub
+ */
+async function createUnitTestStub(
+  schemaPath: string,
+  schemaName: string,
+  schemaType: "type" | "function",
+): Promise<void> {
+  const testContent = `import { describe, test, expect } from "vitest";
+
+describe("${schemaName}", () => {
+  test.todo("should implement ${schemaType} functionality");
+});
+`;
+
+  await writeFile(join(schemaPath, "unit.test.ts"), testContent);
+}
+
+/**
+ * Extract conversion script name from source/target
+ */
+function getConversionFileName(source: string, target: string): string {
+  // Extract the type name from URLs like "https://schema.../core/hex-color/0/"
+  const extractType = (url: string): string => {
+    const match = url.match(/\/([^/]+)\/\d+\/?$/);
+    return match ? match[1] : url;
+  };
+
+  const sourceType = extractType(source);
+  const targetType = extractType(target);
+
+  if (target === "$self") {
+    return `to-${sourceType}.tokenscript`;
+  }
+  if (source === "$self") {
+    return `from-${targetType}.tokenscript`;
+  }
+
+  return `${sourceType}-to-${targetType}.tokenscript`;
+}
+
+/**
+ * Write TokenScript files from schema content
+ */
+async function writeTokenScriptFiles(schemaPath: string, schema: SchemaDetails): Promise<void> {
+  const content = schema.content as any;
+
+  // Write the main schema definition as JSON
+  if (content.schema) {
+    await writeFile(
+      join(schemaPath, "schema-definition.json"),
+      JSON.stringify(content.schema, null, 2),
+    );
+  }
+
+  // Extract and write conversion scripts
+  if (content.conversions && Array.isArray(content.conversions)) {
+    for (const conversion of content.conversions) {
+      if (conversion.script?.script) {
+        const fileName = getConversionFileName(conversion.source || "", conversion.target || "");
+
+        // Add description as comment if available
+        let scriptContent = "";
+        if (conversion.description) {
+          scriptContent += `# ${conversion.description}\n`;
+          scriptContent += `# Source: ${conversion.source}\n`;
+          scriptContent += `# Target: ${conversion.target}\n`;
+          scriptContent += `# Lossless: ${conversion.lossless || false}\n\n`;
+        }
+
+        scriptContent += conversion.script.script;
+
+        await writeFile(join(schemaPath, fileName), scriptContent);
+      }
+    }
+  }
+
+  // Create initializer if no conversions found
+  if (!content.conversions || content.conversions.length === 0) {
+    const initializerContent = `# ${schema.name} Initializer
+# TODO: Implement initialization logic
+
+`;
+    await writeFile(join(schemaPath, "initializer.tokenscript"), initializerContent);
+  }
+}
+
+/**
+ * Download and organize a single schema
+ */
+export async function downloadSchema(
+  schema: SchemaListItem,
+  config: SchemaConfig = DEFAULT_CONFIG,
+): Promise<void> {
+  console.log(`Downloading ${schema.slug}...`);
+
+  // Fetch all versions
+  const versions = await fetchSchemaVersions(schema.slug, config);
+
+  if (versions.length === 0) {
+    console.warn(`No versions found for ${schema.slug}, skipping`);
+    return;
+  }
+
+  // Get the latest version (first one)
+  const latestVersion = versions[0];
+
+  // Create folder structure
+  const schemaPath = await createSchemaFolder(schema.slug, schema.type, config.outputDir);
+
+  // Combine schema info with version info
+  const details: SchemaDetails = {
+    id: schema.id,
+    slug: schema.slug,
+    name: schema.name,
+    description: schema.description,
+    type: schema.type,
+    version: latestVersion.version,
+    content: latestVersion.content,
+  };
+
+  // Write files
+  await writeSchemaJson(schemaPath, details, config.targetVersion);
+  await writeTokenScriptFiles(schemaPath, details);
+  await createUnitTestStub(schemaPath, schema.name, schema.type);
+
+  console.log(`✓ Downloaded ${schema.slug} to ${schemaPath}`);
+}
+
+/**
+ * Download all schemas from the API
+ */
+export async function downloadAllSchemas(config: Partial<SchemaConfig> = {}): Promise<void> {
+  const fullConfig = { ...DEFAULT_CONFIG, ...config };
+
+  // Fetch schema list
+  const schemas = await fetchSchemaList(fullConfig);
+
+  // Download each schema
+  for (const schema of schemas) {
+    try {
+      await downloadSchema(schema, fullConfig);
+    } catch (error) {
+      console.error(`Failed to download ${schema.slug}:`, error);
+    }
+  }
+
+  console.log("\n✓ All schemas downloaded successfully!");
+}
+
+export { DEFAULT_CONFIG };
+export type * from "@/downloader/types.js";

package/src/downloader/types.ts

@@ -0,0 +1,48 @@
+/**
+ * Types for schema downloader
+ */
+
+export interface LatestVersion {
+  id: string;
+  version: string;
+  created_at: string;
+}
+
+export interface SchemaListItem {
+  id: string;
+  slug: string;
+  name: string;
+  description: string;
+  license_name: string | null;
+  type: "type" | "function";
+  latest: LatestVersion;
+}
+
+export interface SchemaVersion {
+  id: string;
+  type: "type" | "function";
+  schema: string;
+  slug: string;
+  version: string;
+  content: unknown;
+  status?: string;
+  created_at?: string;
+  updated_at?: string;
+}
+
+export interface SchemaDetails {
+  id: string;
+  slug: string;
+  name: string;
+  description: string;
+  type: "type" | "function";
+  version: string;
+  content: unknown;
+  metadata?: Record<string, unknown>;
+}
+
+export interface SchemaConfig {
+  apiBaseUrl: string;
+  outputDir: string;
+  targetVersion: string;
+}

package/src/index.ts

@@ -0,0 +1,8 @@
+/**
+ * @tokens-studio/tokenscript-schemas
+ *
+ * Schema registry for TokenScript with bundled schemas and validation
+ */
+
+export * from "@/bundler/index.js";
+export * from "@/downloader/index.js";

package/src/schemas/functions/adjust_chroma/adjust-chroma.tokenscript

@@ -0,0 +1,27 @@
+// adjust_chroma: Adjust chroma by a relative amount
+//
+// Modifies the chroma (colorfulness) of a color by adding the
+// specified amount. Positive values increase saturation,
+// negative values decrease it. Result is clamped to [0, ∞).
+//
+// Uses OKLCH for perceptually uniform results.
+// Preserves lightness and hue.
+
+variable input: List = {input};
+variable color: Color.OKLCH = input.get(0).to.oklch();
+variable amount: Number = input.get(1);
+
+// Calculate new chroma
+variable new_c: Number = color.c + amount;
+
+// Clamp to valid range (chroma cannot be negative)
+if (new_c < 0) [ new_c = 0; ];
+
+// Create result
+variable result: Color.OKLCH;
+result.l = color.l;
+result.c = new_c;
+result.h = color.h;
+
+return result;
+

package/src/schemas/functions/adjust_chroma/schema.json

@@ -0,0 +1,48 @@
+{
+  "name": "adjust_chroma",
+  "type": "function",
+  "description": "Adjusts a color's chroma by a relative amount. Positive values increase saturation, negative values decrease it. Unlike set_chroma which sets an absolute value, adjust_chroma adds to the current chroma. Result is clamped to valid range [0, ~0.4].",
+  "keyword": "adjust_chroma",
+  "requirements": ["/api/v1/core/srgb-color/0/", "/api/v1/core/oklch-color/0/"],
+  "schema": {
+    "type": "object",
+    "properties": {
+      "input": {
+        "type": "array",
+        "items": [
+          {
+            "description": "Color to adjust",
+            "type": "color"
+          },
+          {
+            "description": "Amount to adjust chroma (+/-)",
+            "type": "number"
+          }
+        ],
+        "minItems": 2,
+        "maxItems": 2
+      }
+    },
+    "required": ["input"]
+  },
+  "returns": {
+    "type": "color",
+    "description": "Color with adjusted chroma"
+  },
+  "script": {
+    "type": "https://schema.tokenscript.dev.gcp.tokens.studio/api/v1/core/tokenscript/0/",
+    "script": "./adjust-chroma.tokenscript"
+  },
+  "examples": [
+    {
+      "description": "Increase saturation",
+      "input": ["#808080", 0.1],
+      "output": "More saturated color"
+    },
+    {
+      "description": "Decrease saturation",
+      "input": ["#ff6600", -0.1],
+      "output": "Less saturated orange"
+    }
+  ]
+}