@token-forge/core 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Badi Labassi
+
+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/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@token-forge/core",
+  "version": "0.3.0",
+  "description": "Token Forge pipeline bundle — profile, Terrazzo plugins, token schema, Figma import",
+  "license": "MIT",
+  "author": "Badi Labassi",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/blabassi/token-forge.git",
+    "directory": "packages/core"
+  },
+  "files": [
+    "src"
+  ],
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./bootstrap": "./src/bootstrap.ts",
+    "./terrazzo": "./src/terrazzo-pipeline.ts"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@terrazzo/cli": "^2.2.0",
+    "@terrazzo/plugin-css": "^2.2.0",
+    "@token-forge/plugins": "0.3.0",
+    "@token-forge/figma-importer": "0.3.0",
+    "@token-forge/lib": "0.3.0",
+    "@token-forge/token-schema": "0.3.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "typescript": "^7.0.2"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit -p ./"
+  }
+}

package/src/bootstrap.ts

@@ -0,0 +1,28 @@
+import {
+  systemIds,
+  type DesignSystemProfile,
+  parseDesignSystemProfile,
+  setDesignSystemProfile,
+} from "@token-forge/lib";
+
+export type BootstrappedDesignSystem = {
+  profile: DesignSystemProfile;
+  systems: string[];
+  isSystem: (value: string) => boolean;
+};
+
+/**
+ * Register the consumer's design-system profile for this process.
+ * Usually unnecessary when the repo uses `defineDesignSystemProfile` in `design-system.config.ts`
+ * (import that module at CLI/test entry instead).
+ */
+export function bootstrapDesignSystem(profile: DesignSystemProfile | unknown): BootstrappedDesignSystem {
+  const parsed = parseDesignSystemProfile(profile);
+  setDesignSystemProfile(parsed);
+  const systems = systemIds(parsed);
+  return {
+    profile: parsed,
+    systems,
+    isSystem: (value: string) => systems.includes(value),
+  };
+}

package/src/index.ts

@@ -0,0 +1,19 @@
+/**
+ * @token-forge/core — workspace bundle of the generic token pipeline.
+ *
+ * Consumer repos depend on this package (or the individual `@token-forge/*` packages)
+ * and provide `design-system.config.ts` + `tokens/` + a thin `terrazzo.config.ts`.
+ */
+
+export { bootstrapDesignSystem, type BootstrappedDesignSystem } from "./bootstrap";
+export {
+  createTerrazzoPipeline,
+  loadOutputPlugins,
+  resolveOutputPluginsSync,
+  type SystemBuildOptions,
+  type CreateTerrazzoPipelineOptions,
+} from "./terrazzo-pipeline";
+
+export * from "@token-forge/lib";
+export * from "@token-forge/plugins";
+export * from "@token-forge/token-schema";

package/src/terrazzo-pipeline.ts

@@ -0,0 +1,213 @@
+import fs from "node:fs";
+import path from "node:path";
+import {
+  bootstrapCssPluginOptions,
+  buildOutDir,
+  buildSourceOrder,
+  cssPermutationsForSystem,
+  profileColorCssOutput,
+  resolverContextsBySystem,
+  resolverRelPath,
+  resolveColorCssOutput,
+  shouldExcludeLiquidPlugin,
+  tokenLayerRelPaths,
+  type ColorFormatPluginOptions,
+  type DesignSystemProfile,
+  type OutputPluginOverrides,
+  type ResolverContexts,
+} from "@token-forge/lib";
+import {
+  getBuildPlugin,
+  loadOutputPlugins,
+  registerBuiltinBuildPlugins,
+  type ResolvedOutputPlugin,
+  type TokenForgeBuildPlugin,
+} from "@token-forge/plugins";
+import { profileOutputPluginEntries } from "@token-forge/lib";
+import { defineConfig } from "@terrazzo/cli";
+import css from "@terrazzo/plugin-css";
+import { bootstrapDesignSystem } from "./bootstrap";
+
+export type { ColorFormatPluginOptions };
+export type SystemBuildOptions = ColorFormatPluginOptions & OutputPluginOverrides;
+
+export type CreateTerrazzoPipelineOptions<SystemId extends string = string> = {
+  profile: DesignSystemProfile;
+  /** Design-system entry ids to build (`profile.designSystems[].id`). */
+  systems: readonly SystemId[];
+  /** Consumer root (directory with `tokens/`, `resolvers/`, `design-system.config.ts`). */
+  repoRoot: string;
+  /** When true (default), calls `bootstrapDesignSystem(profile)` for this process. */
+  bootstrap?: boolean;
+  /**
+   * Pre-loaded build plugins (from {@link loadOutputPlugins}).
+   * When omitted, resolves from the registry (builtins + already-imported path modules).
+   */
+  outputPlugins?: ResolvedOutputPlugin[] | TokenForgeBuildPlugin[];
+};
+
+const sharedLint = {
+  build: { enabled: true },
+  rules: {
+    "core/valid-color": "error",
+    "core/valid-dimension": "error",
+    "core/valid-font-family": "error",
+    // "warn" not "error": Figma exports italic weights as names ("medium italic", …)
+    // which the rule rejects; plugins map them to numeric weights (FONT_WEIGHT_NAMES).
+    "core/valid-font-weight": "warn",
+    "core/valid-duration": "error",
+    "core/valid-cubic-bezier": "error",
+    "core/valid-number": "error",
+    "core/valid-link": "error",
+    "core/valid-boolean": "error",
+    "core/valid-string": "error",
+    "core/valid-stroke-style": "error",
+    "core/valid-border": "error",
+    "core/valid-transition": "error",
+    "core/valid-shadow": "error",
+    "core/valid-gradient": "error",
+    "core/valid-typography": "error",
+    "core/consistent-naming": "warn",
+  },
+} as const;
+
+function isPathRef(ref: string): boolean {
+  return ref.startsWith("./") || ref.startsWith("../") || path.isAbsolute(ref);
+}
+
+function derivedIdFromPath(modulePath: string): string {
+  return path.basename(modulePath, path.extname(modulePath));
+}
+
+/**
+ * Resolve plugin refs from the registry without dynamic import.
+ * Path refs must already be registered (side-effect import or prior `loadOutputPlugins`).
+ */
+export function resolveOutputPluginsSync(
+  profile: DesignSystemProfile,
+  overrides: OutputPluginOverrides = {},
+): ResolvedOutputPlugin[] {
+  registerBuiltinBuildPlugins();
+  const entries = profileOutputPluginEntries(profile);
+  if (!entries.length) {
+    throw new Error("profile.outputs.plugins must be a non-empty list");
+  }
+  const plugins = entries.map((entry) => {
+    const id = isPathRef(entry.id) ? derivedIdFromPath(entry.id) : entry.id;
+    try {
+      return { plugin: getBuildPlugin(id), options: entry.options };
+    } catch {
+      throw new Error(
+        `Build plugin "${entry.id}" is not registered. Import the module for its side effect, ` +
+          `or await loadOutputPlugins(profile, consumerDir) before createTerrazzoPipeline.`,
+      );
+    }
+  });
+  if (shouldExcludeLiquidPlugin(overrides)) {
+    return plugins.filter((entry) => entry.plugin.id !== "liquid");
+  }
+  return plugins;
+}
+
+function asResolved(plugins: ResolvedOutputPlugin[] | TokenForgeBuildPlugin[]): ResolvedOutputPlugin[] {
+  return plugins.map((entry) =>
+    "plugin" in entry && typeof (entry as ResolvedOutputPlugin).plugin?.create === "function"
+      ? (entry as ResolvedOutputPlugin)
+      : { plugin: entry as TokenForgeBuildPlugin },
+  );
+}
+
+/**
+ * Build Terrazzo `configForSystem` / `pluginsForSystem` from a design-system profile.
+ * Consumer repos keep a thin `terrazzo.config.ts` that calls this helper.
+ */
+export function createTerrazzoPipeline<SystemId extends string>(options: CreateTerrazzoPipelineOptions<SystemId>) {
+  const { profile, systems, repoRoot, bootstrap = true, outputPlugins: providedPlugins } = options;
+  if (!systems?.length) {
+    throw new Error("createTerrazzoPipeline requires non-empty `systems`");
+  }
+  if (bootstrap) {
+    bootstrapDesignSystem(profile);
+  }
+
+  registerBuiltinBuildPlugins();
+  const systemResolverContexts = resolverContextsBySystem(profile) as Record<SystemId, ResolverContexts>;
+
+  function activeOutputPlugins(buildOptions: SystemBuildOptions = {}): ResolvedOutputPlugin[] {
+    const base = asResolved(providedPlugins ?? resolveOutputPluginsSync(profile));
+    if (shouldExcludeLiquidPlugin(buildOptions)) {
+      return base.filter((entry) => entry.plugin.id !== "liquid");
+    }
+    return base;
+  }
+
+  function loadTokenDocsForSystem(system: SystemId): Record<string, unknown>[] {
+    return tokenLayerRelPaths(profile, system).map((relPath) => {
+      const fullPath = path.join(repoRoot, relPath);
+      return JSON.parse(fs.readFileSync(fullPath, "utf8")) as Record<string, unknown>;
+    });
+  }
+
+  function tokenOrderForSystem(system: SystemId): Map<string, number> {
+    return buildSourceOrder(loadTokenDocsForSystem(system));
+  }
+
+  function pluginsForSystem(
+    system: SystemId,
+    tokenOrder: Map<string, number>,
+    resolverContexts: ResolverContexts,
+    buildOptions: SystemBuildOptions = {},
+  ) {
+    const colorCssOutput = resolveColorCssOutput(buildOptions.colorCssOutput, profileColorCssOutput(profile));
+
+    const terrazzoPlugins = [
+      css({
+        filename: `_${system}-css-transforms.css`,
+        skipBuild: true,
+        permutations: cssPermutationsForSystem(profile, resolverContexts),
+        ...bootstrapCssPluginOptions(colorCssOutput),
+      }),
+    ];
+
+    for (const entry of activeOutputPlugins(buildOptions)) {
+      terrazzoPlugins.push(
+        entry.plugin.create({
+          system,
+          tokenOrder,
+          resolverContexts,
+          colorCssOutput,
+          options: entry.options,
+        }),
+      );
+    }
+
+    return terrazzoPlugins;
+  }
+
+  function configForSystem(system: SystemId, buildOptions: SystemBuildOptions = {}) {
+    const tokenOrder = tokenOrderForSystem(system);
+    const resolverContexts = systemResolverContexts[system];
+
+    return defineConfig({
+      tokens: [resolverRelPath(profile, system)],
+      outDir: buildOutDir(profile, system),
+      plugins: pluginsForSystem(system, tokenOrder, resolverContexts, buildOptions),
+      lint: sharedLint,
+    });
+  }
+
+  const systemConfigs = systems.map((system) => configForSystem(system));
+
+  return {
+    profile,
+    systems,
+    repoRoot,
+    pluginsForSystem,
+    configForSystem,
+    systemConfigs,
+    tokenOrderForSystem,
+    activeOutputPlugins,
+  };
+}
+
+export { loadOutputPlugins };