@toghen/figma 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Egildo Tagliareni
+
+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,19 @@
-# Temporary Holding Version
+# @toghen/figma
 
-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.
+The Figma adapter of [Toghen](https://codeberg.org/Toghen). A resolver document, resolved through [`@toghen/lib`](https://codeberg.org/Toghen/lib), becomes a Figma file's Variables and Styles: one collection per modifier, a mode per context. A component file (`.component.kdl`) becomes a component set in the same file. Running again changes only the difference.
+
+```sh
+pnpm add -D @toghen/figma
+```
+
+The package holds three pieces:
+
+- **The plugin**, built into `dist/` with its `manifest.json`. Import it in the Figma desktop app.
+- **Component files**, the format a component set is built from. See [component-files.md](https://codeberg.org/Toghen/figma/src/branch/main/component-files.md).
+- **The command line**, `toghen-figma`. It pairs with the open plugin over a local socket and runs the whole job from a repository: read and check everything, sync variables, sync styles, then build each component file.
+
+The [guide](https://codeberg.org/Toghen/figma/src/branch/main/guide.md) goes from a fresh checkout to a synced file, and the [reference](https://codeberg.org/Toghen/figma/src/branch/main/reference.md) lists the protocol and the schemas.
+
+## License
+
+MIT. See [LICENSE](https://codeberg.org/Toghen/figma/src/branch/main/LICENSE).

package/cli/bin.mjs

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+// The `toghen-figma` command. It always runs `main`: comparing this file with
+// `process.argv[1]` breaks when the package is reached through a symlink.
+import { readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { register } from 'tsx/esm/api';
+
+register();
+const { main } = await import('./main.ts');
+
+process.exitCode = await main(process.argv.slice(2), {
+  // pnpm runs a package script in the package's own directory; INIT_CWD is where the person typed it.
+  cwd: process.env.INIT_CWD ?? process.cwd(),
+  readFile: (path) => readFileSync(path, 'utf8'),
+  stdout: (text) => process.stdout.write(text),
+  stderr: (text) => process.stderr.write(text),
+  pairingFile: join(homedir(), '.toghen', 'figma-pairing'),
+});

package/cli/bridge.ts

@@ -0,0 +1,243 @@
+/**
+ * The command line's half of the bridge: a localhost socket the plugin's UI connects to.
+ *
+ * It listens on a port the plugin's manifest names, and only on the loopback addresses. The socket's
+ * origin is `null`, so it cannot tell the plugin from another page that opens the port; the two pair
+ * instead. The plugin's first message is `{ "pair": "<code>" }`, and a connection without the right code
+ * is closed with `REFUSED` and never sees a token. Once paired, messages in both directions are the plugin's
+ * own protocol (`shared/protocol.ts`), one JSON object each, and the command line asks one question at a time.
+ *
+ * The code outlives the process: each run is a new one, and the plugin reconnects to it when it starts. It is kept in
+ * a file only the person's account can read, and `pairing` is how a run reads and renews it.
+ *
+ * A run with a library holds two plugins at once, one in the library file and one in the target file: one code each,
+ * one role each, on the same port (`serve`).
+ */
+
+import { randomInt, timingSafeEqual } from 'node:crypto';
+import { chmodSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { createServer, type Server } from 'node:http';
+import type { AddressInfo } from 'node:net';
+import { dirname } from 'node:path';
+import { WebSocketServer, type WebSocket } from 'ws';
+import type { Command, Response } from '../shared/protocol.js';
+
+/** The port the manifest names. A port it does not declare is refused by Figma. */
+export const PORT = 3055;
+/** The close code for a pairing code the command line does not know. The plugin stops trying on it. */
+export const REFUSED = 4001;
+/** The close code for a plugin whose place another connection with the right code took. */
+export const REPLACED = 4002;
+/** After this many wrong codes in one run the run stops: nothing legitimate types a code that often. */
+const MAX_REFUSALS = 5;
+
+const ALPHABET = 'ABCDEFGHJKLMNPQRSTUVWXYZ23456789';
+
+/** Eight characters from an alphabet without look-alikes, written `XXXX-XXXX`. */
+export function newCode(): string {
+  let code = '';
+  for (let i = 0; i < 8; i += 1) code += ALPHABET[randomInt(ALPHABET.length)];
+  return `${code.slice(0, 4)}-${code.slice(4)}`;
+}
+
+/** What is typed is compared without case, dashes or spaces. */
+const normalize = (code: string): string => code.toUpperCase().replace(/[^A-Z0-9]/g, '');
+
+const same = (a: string, b: string): boolean => {
+  const x = Buffer.from(normalize(a));
+  const y = Buffer.from(normalize(b));
+  return x.length === y.length && timingSafeEqual(x, y);
+};
+
+/** The pairing code kept between runs, in a file only this account can read. */
+export const pairing = {
+  read(file: string): string | undefined {
+    try {
+      return readFileSync(file, 'utf8').trim() || undefined;
+    } catch {
+      return undefined;
+    }
+  },
+  write(file: string, code: string): void {
+    mkdirSync(dirname(file), { recursive: true, mode: 0o700 });
+    writeFileSync(file, `${code}\n`, { mode: 0o600 });
+    // The mode above applies only to a file this call created.
+    chmodSync(file, 0o600);
+  },
+};
+
+/** The port is held by something else. */
+export class PortTaken extends Error {
+  constructor(readonly port: number) {
+    super(
+      `port ${port} is taken: another toghen-figma, or another program, is listening on it. Stop that one and run again; the plugin's manifest names this port, so it cannot be changed`,
+    );
+    this.name = 'PortTaken';
+  }
+}
+
+/** The plugin went away, or the run was stopped, while a question was waiting. */
+export class PluginGone extends Error {}
+
+export interface Bridge {
+  readonly port: number;
+  /** Resolves once a plugin has paired; rejects when too many wrong codes were tried. */
+  paired: Promise<void>;
+  /**
+   * Sends a command and resolves with the first response whose type is one of `answers`, or the `ERROR` that
+   * names this command. Progress and anything else the plugin posts meanwhile goes to `onOther`.
+   */
+  request(command: Command, answers: Response['type'][], onOther?: (response: Response) => void): Promise<Response>;
+  close(): Promise<void>;
+}
+
+const listen = (server: Server, port: number, host: string): Promise<void> =>
+  new Promise((resolve, reject) => {
+    server.once('error', reject);
+    server.listen(port, host, () => {
+      server.off('error', reject);
+      resolve();
+    });
+  });
+
+/** One plugin's end of the bridge, whose code a run can replace while it listens (a kept code nobody came back with). */
+export interface Role extends Bridge {
+  /** From now on this code pairs for the role, and the one before is refused. */
+  renew(code: string): void;
+}
+
+/**
+ * Starts listening, on 127.0.0.1 and, where there is one, ::1: `localhost` is either, depending on who asks.
+ *
+ * One code per role: a run with a library holds two plugins, one in each file, on the one port. A connection pairs as
+ * the role whose code it gives, and replaces the plugin that held that role. Five wrong codes in all stop every role.
+ * Closing any role closes the server, and every plugin's socket with it.
+ */
+export async function serve<R extends string>(port: number, codes: Record<R, string>): Promise<Record<R, Role>> {
+  interface Held {
+    code: string;
+    plugin?: WebSocket;
+    onMessage?: (response: Response) => void;
+    onGone?: (error: Error) => void;
+    markPaired: () => void;
+    refuse: (error: Error) => void;
+    paired: Promise<void>;
+  }
+  const held = {} as Record<R, Held>;
+  for (const role of Object.keys(codes) as R[]) {
+    const entry = { code: codes[role] } as Held;
+    entry.paired = new Promise<void>((resolve, reject) => {
+      entry.markPaired = resolve;
+      entry.refuse = reject;
+    });
+    entry.paired.catch(() => {});
+    held[role] = entry;
+  }
+  const all = Object.values<Held>(held);
+  let refusals = 0;
+
+  const wss = new WebSocketServer({ noServer: true, maxPayload: 256 * 1024 * 1024 });
+  wss.on('connection', (socket) => {
+    let mine: Held | undefined;
+    socket.on('message', (data) => {
+      let message: { pair?: unknown } & Partial<Response>;
+      try {
+        message = JSON.parse(data.toString());
+      } catch {
+        return socket.close(REFUSED, 'not JSON');
+      }
+      if (!mine) {
+        const { pair } = message;
+        const found = typeof pair === 'string' ? all.find((entry) => same(pair, entry.code)) : undefined;
+        if (!found) {
+          socket.close(REFUSED, 'pairing code refused');
+          refusals += 1;
+          if (refusals >= MAX_REFUSALS)
+            for (const entry of all)
+              entry.refuse(
+                new Error(
+                  `${refusals} connections gave a wrong pairing code, so the run stopped. Something other than the plugin is using port ${port}`,
+                ),
+              );
+          return;
+        }
+        mine = found;
+        found.plugin?.close(REPLACED, 'another connection paired');
+        found.plugin = socket;
+        socket.send(JSON.stringify({ paired: true }));
+        found.markPaired();
+        return;
+      }
+      mine.onMessage?.(message as Response);
+    });
+    socket.on('close', () => {
+      if (!mine || mine.plugin !== socket) return;
+      mine.plugin = undefined;
+      mine.onGone?.(new PluginGone('the plugin disconnected: it was closed, or Figma lost it'));
+    });
+  });
+
+  const servers = [createServer(), createServer()];
+  for (const server of servers)
+    server.on('upgrade', (request, socket, head) => wss.handleUpgrade(request, socket, head, (ws) => wss.emit('connection', ws, request)));
+  try {
+    await listen(servers[0], port, '127.0.0.1');
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'EADDRINUSE') throw new PortTaken(port);
+    throw error;
+  }
+  const bound = (servers[0].address() as AddressInfo).port;
+  try {
+    await listen(servers[1], bound, '::1');
+  } catch (error) {
+    // No IPv6 loopback is not a problem; a port something else holds there is.
+    if ((error as NodeJS.ErrnoException).code === 'EADDRINUSE') {
+      servers[0].close();
+      throw new PortTaken(bound);
+    }
+  }
+
+  let closing: Promise<void> | undefined;
+  const close = (): Promise<void> =>
+    (closing ??= (async () => {
+      for (const entry of all) {
+        entry.onMessage = entry.onGone = undefined;
+        // A paired plugin is closed with the normal code, and reconnects when the next run listens.
+        entry.plugin?.close(1000);
+      }
+      for (const client of wss.clients) client.terminate();
+      wss.close();
+      await Promise.all(servers.map((server) => new Promise<void>((done) => (server.listening ? server.close(() => done()) : done()))));
+    })());
+
+  const roles = {} as Record<R, Role>;
+  for (const role of Object.keys(held) as R[]) {
+    const entry = held[role];
+    roles[role] = {
+      port: bound,
+      paired: entry.paired,
+      renew(code) {
+        entry.code = code;
+      },
+      request(command, answers, onOther) {
+        return new Promise((resolve, reject) => {
+          const plugin = entry.plugin;
+          if (!plugin || plugin.readyState !== plugin.OPEN) return reject(new PluginGone('the plugin is not connected'));
+          entry.onGone = (error) => {
+            entry.onMessage = entry.onGone = undefined;
+            reject(error);
+          };
+          entry.onMessage = (response) => {
+            const mine = response.type === 'ERROR' && response.payload.commandType === command.type;
+            if (!mine && !answers.includes(response.type)) return onOther?.(response);
+            entry.onMessage = entry.onGone = undefined;
+            resolve(response);
+          };
+          plugin.send(JSON.stringify(command));
+        });
+      },
+      close,
+    };
+  }
+  return roles;
+}

package/cli/check.ts

@@ -0,0 +1,62 @@
+/**
+ * `toghen-figma check <entry.json>… <file>… [--name <name>] [--overrides <map.json>] [--input <document>]`: the files
+ * read against the design system, with no plugin and no Figma file.
+ *
+ * It is the plugin's own check (`checkComponents`, `main/components/file.ts`), given the resolver built here in Node, from
+ * the document the core's `load` returned, as the plugin builds it when a document is loaded. What only Figma holds,
+ * whether a variable already exists or is ambiguous between collections, is the dry run's to say.
+ */
+
+import { Resolver } from '@toghen/lib';
+import { resolve } from 'node:path';
+import { checkComponents } from '../main/components/file.js';
+import { resolveSumModes } from '../main/utils/resolverModes.js';
+import { entryLabel, readInputs, readSource, type Io, type LoadArguments } from './run.js';
+
+export interface CheckArguments extends LoadArguments {
+  /** A resolver document, one token file, or several in order. */
+  entry: string | string[];
+  files: string[];
+  input?: string;
+}
+
+/** Prints every problem, one per line, and returns the exit code: 0 when no file has an error, 1 otherwise. */
+export async function check(args: CheckArguments, io: Io): Promise<number> {
+  let design: Resolver;
+  try {
+    design = new Resolver((await readSource(args.entry, io, args)).document);
+    // As the plugin does when it loads a document: the sum, which refuses a modifier with no default.
+    resolveSumModes(design);
+  } catch (error) {
+    io.stderr(`${entryLabel(args.entry)}: ${(error as Error).message}\n`);
+    return 1;
+  }
+  let inputs: Record<string, unknown> | undefined;
+  if (args.input !== undefined) {
+    try {
+      inputs = await readInputs(args.input, io);
+    } catch (error) {
+      io.stderr(`${args.input}: ${(error as Error).message}\n`);
+      return 1;
+    }
+  }
+  const files: { fileName: string; text: string }[] = [];
+  let unreadable = false;
+  for (const file of args.files) {
+    try {
+      files.push({ fileName: file, text: io.readFile(resolve(io.cwd, file)) });
+    } catch (error) {
+      io.stderr(`${file} cannot be read: ${(error as Error).message}\n`);
+      unreadable = true;
+    }
+  }
+  if (unreadable) return 1;
+
+  const { errors, warnings } = checkComponents(files, { names: true, ...(inputs ? { inputs } : {}) }, design);
+  for (const line of [...errors, ...warnings]) io.stderr(`${line}\n`);
+  const noun = (n: number, word: string) => `${n} ${word}${n === 1 ? '' : 's'}`;
+  io.stdout(
+    `${noun(files.length, 'file')} read: ${errors.length === 0 ? 'no errors' : noun(errors.length, 'error')}${warnings.length > 0 ? `, ${noun(warnings.length, 'warning')}` : ''}\n`,
+  );
+  return errors.length === 0 ? 0 : 1;
+}