@fluid-app/fluid-cli-theme-dev 0.1.0

package/src/commands/pull.ts

@@ -0,0 +1,90 @@
+import { Command } from "commander";
+import ora from "ora";
+import prompts from "prompts";
+import { requireToken, createApiClient } from "../api.js";
+import { ThemeRoot } from "../theme/root.js";
+import { Syncer } from "../theme/syncer.js";
+
+interface ApplicationTheme {
+  id: number;
+  name: string;
+}
+
+async function selectOrFindTheme(
+  api: ReturnType<typeof createApiClient>,
+  identifier?: string,
+): Promise<ApplicationTheme> {
+  const body = await api.get<{ application_themes: ApplicationTheme[] }>(
+    "/api/application_themes",
+  );
+  const themes = body.application_themes ?? [];
+  if (!themes.length) {
+    console.error("No themes found.");
+    process.exit(1);
+  }
+
+  if (identifier) {
+    const found =
+      themes.find((t) => String(t.id) === identifier) ??
+      themes.find((t) => t.name.toLowerCase() === identifier.toLowerCase());
+    if (!found) {
+      console.error(`No theme found with identifier: ${identifier}`);
+      process.exit(1);
+    }
+    return found;
+  }
+
+  const { id } = await prompts(
+    {
+      type: "select",
+      name: "id",
+      message: "Select a theme to pull",
+      choices: themes.map((t) => ({
+        title: `${t.name} (#${t.id})`,
+        value: t.id,
+      })),
+    },
+    { onCancel: () => process.exit(130) },
+  );
+  if (!id) {
+    console.error("No theme selected.");
+    process.exit(1);
+  }
+  return themes.find((t) => t.id === id)!;
+}
+
+export function createPullCommand(): Command {
+  return new Command("pull")
+    .description("Pull a remote theme to your local directory")
+    .option("-t, --theme <name-or-id>", "Theme name or ID to pull")
+    .option("-n, --nodelete", "Do not delete local files missing on remote")
+    .option("--root <path>", "Theme root directory", ".")
+    .action(
+      async (opts: { theme?: string; nodelete?: boolean; root: string }) => {
+        requireToken();
+
+        const api = createApiClient();
+        const theme = await selectOrFindTheme(api, opts.theme);
+        const themeRoot = new ThemeRoot(opts.root);
+
+        const syncer = new Syncer(api, theme.id, themeRoot);
+        const spinner = ora(`Pulling ${theme.name} (#${theme.id})…`).start();
+
+        const result = await syncer.downloadTheme({
+          delete: !opts.nodelete,
+          onProgress: (d, total) => {
+            spinner.text = `Downloading ${d}/${total} files…`;
+          },
+        });
+
+        if (result.errors.length) {
+          spinner.warn(`Pulled with ${result.errors.length} error(s).`);
+          for (const e of result.errors) console.error(`  ${e}`);
+        } else {
+          spinner.succeed(
+            `Downloaded ${result.downloaded} file(s), deleted ${result.deleted} local file(s).`,
+          );
+        }
+      },
+    );
+}

package/src/commands/push.ts

@@ -0,0 +1,121 @@
+import { Command } from "commander";
+import ora from "ora";
+import prompts from "prompts";
+import { requireToken, createApiClient } from "../api.js";
+import { ThemeRoot } from "../theme/root.js";
+import { Syncer } from "../theme/syncer.js";
+
+interface ApplicationTheme {
+  id: number;
+  name: string;
+  company: string;
+}
+
+async function selectTheme(
+  api: ReturnType<typeof createApiClient>,
+): Promise<ApplicationTheme> {
+  const body = await api.get<{ application_themes: ApplicationTheme[] }>(
+    "/api/application_themes",
+  );
+  const themes = body.application_themes ?? [];
+  if (!themes.length) {
+    console.error("No themes found.");
+    process.exit(1);
+  }
+  const { id } = await prompts(
+    {
+      type: "select",
+      name: "id",
+      message: "Select a theme to push to",
+      choices: themes.map((t) => ({
+        title: `${t.name} (#${t.id})`,
+        value: t.id,
+      })),
+    },
+    { onCancel: () => process.exit(130) },
+  );
+  if (!id) {
+    console.error("No theme selected.");
+    process.exit(1);
+  }
+  return themes.find((t) => t.id === id)!;
+}
+
+async function findTheme(
+  api: ReturnType<typeof createApiClient>,
+  identifier: string,
+): Promise<ApplicationTheme> {
+  const body = await api.get<{ application_themes: ApplicationTheme[] }>(
+    "/api/application_themes",
+  );
+  const themes = body.application_themes ?? [];
+  const found =
+    themes.find((t) => String(t.id) === identifier) ??
+    themes.find((t) => t.name.toLowerCase() === identifier.toLowerCase());
+  if (!found) {
+    console.error(`No theme found with identifier: ${identifier}`);
+    process.exit(1);
+  }
+  return found;
+}
+
+export function createPushCommand(): Command {
+  return new Command("push")
+    .description("Push local theme files to a remote theme")
+    .option("-t, --theme <name-or-id>", "Theme name or ID to push to")
+    .option("-n, --nodelete", "Do not delete remote files missing locally")
+    .option("-f, --force", "Skip schema validation")
+    .option("-p, --publish", "Publish the theme after pushing")
+    .option("--root <path>", "Theme root directory", ".")
+    .action(
+      async (opts: {
+        theme?: string;
+        nodelete?: boolean;
+        force?: boolean;
+        publish?: boolean;
+        root: string;
+      }) => {
+        requireToken();
+
+        const themeRoot = new ThemeRoot(opts.root);
+        if (!themeRoot.isValid()) {
+          console.error(`'${opts.root}' does not look like a theme directory.`);
+          process.exit(1);
+        }
+
+        const api = createApiClient();
+        const theme = opts.theme
+          ? await findTheme(api, opts.theme)
+          : await selectTheme(api);
+
+        const syncer = new Syncer(api, theme.id, themeRoot);
+        const spinner = ora(`Pushing to ${theme.name} (#${theme.id})…`).start();
+
+        const result = await syncer.uploadTheme({
+          delete: !opts.nodelete,
+          onProgress: (d, total) => {
+            spinner.text = `Pushing ${d}/${total} files…`;
+          },
+        });
+
+        if (result.errors.length) {
+          spinner.warn(`Pushed with ${result.errors.length} error(s).`);
+          for (const e of result.errors) console.error(`  ${e}`);
+        } else {
+          spinner.succeed(
+            `Pushed ${result.uploaded} file(s), deleted ${result.deleted} remote file(s).`,
+          );
+        }
+
+        if (opts.publish) {
+          const pubSpinner = ora("Publishing theme…").start();
+          try {
+            await api.post(`/api/application_themes/${theme.id}/publish`);
+            pubSpinner.succeed("Theme published.");
+          } catch (e) {
+            pubSpinner.fail(`Publish failed: ${e}`);
+          }
+        }
+      },
+    );
+}

package/src/commands/theme.ts

@@ -0,0 +1,21 @@
+import { Command } from "commander";
+import type { PluginContext } from "@fluid-app/fluid-cli";
+import { createDevCommand } from "./dev.js";
+import { createPushCommand } from "./push.js";
+import { createPullCommand } from "./pull.js";
+import { createInitCommand } from "./init.js";
+import { createNavigateCommand } from "./navigate.js";
+
+export function registerThemeCommand(ctx: PluginContext): void {
+  const cmd = new Command("theme").description(
+    "Theme developer workflow — dev server, push, pull, init",
+  );
+
+  cmd.addCommand(createDevCommand());
+  cmd.addCommand(createPushCommand());
+  cmd.addCommand(createPullCommand());
+  cmd.addCommand(createInitCommand());
+  cmd.addCommand(createNavigateCommand());
+
+  ctx.program.addCommand(cmd);
+}

package/src/index.ts

@@ -0,0 +1,12 @@
+import type { FluidPlugin, PluginContext } from "@fluid-app/fluid-cli";
+import { registerThemeCommand } from "./commands/theme.js";
+
+const plugin: FluidPlugin = {
+  name: "@fluid-app/fluid-cli-theme-dev",
+  version: "0.1.0",
+  register(ctx: PluginContext) {
+    registerThemeCommand(ctx);
+  },
+};
+
+export default plugin;

package/src/plugin-state.ts

@@ -0,0 +1,26 @@
+import { readConfig, updateConfig } from "@fluid-app/fluid-cli";
+
+interface ThemeDevState {
+  devThemeId?: number;
+  devThemeName?: string;
+}
+
+const PLUGIN_KEY = "theme-dev";
+
+export function getPluginState(): ThemeDevState {
+  const config = readConfig();
+  return (config.plugins[PLUGIN_KEY] as ThemeDevState) ?? {};
+}
+
+export function setPluginState(updates: Partial<ThemeDevState>): void {
+  updateConfig((config) => ({
+    ...config,
+    plugins: {
+      ...config.plugins,
+      [PLUGIN_KEY]: {
+        ...((config.plugins[PLUGIN_KEY] as ThemeDevState) ?? {}),
+        ...updates,
+      },
+    },
+  }));
+}

package/src/theme/dev-server/hot-reload.ts

@@ -0,0 +1,65 @@
+export function buildHotReloadScript(mode: "full-page" | "off"): string {
+  return `
+<script>
+(() => {
+  window.__FLUID_CLI_ENV__ = ${JSON.stringify({ mode })};
+
+  class HotReload {
+    static reloadMode() { return window.__FLUID_CLI_ENV__.mode; }
+    static isActive() { return HotReload.reloadMode() !== "off"; }
+    static setHotReloadCookie(files) {
+      const expires = new Date(Date.now() + 3000).toUTCString();
+      document.cookie = \`hot_reload_files=\${files.join(",")};expires=\${expires};path=/\`;
+    }
+    static refresh(files) {
+      HotReload.setHotReloadCookie(files);
+      console.log("[HotReload] Refreshing page");
+      window.location.reload();
+    }
+  }
+
+  class SSEClient {
+    constructor(url, handler) {
+      if (typeof EventSource === "undefined") {
+        console.error("[HotReload] EventSource not supported in this browser.");
+        return;
+      }
+      console.log("[HotReload] Initializing…");
+      this.url = url;
+      this.handler = handler;
+    }
+    connect() {
+      const es = new EventSource(this.url);
+      es.onopen = () => console.log("[HotReload] SSE connected.");
+      es.onerror = () => {
+        console.log("[HotReload] SSE closed. Reconnecting in 5s…");
+        es.close();
+        setTimeout(() => this.connect(), 5000);
+      };
+      es.onmessage = (msg) => {
+        const data = JSON.parse(msg.data);
+        if (data.reload_page) { HotReload.refresh([]); return; }
+        this.handler(data);
+      };
+    }
+  }
+
+  if (HotReload.isActive()) {
+    new SSEClient("/hot-reload", (data) => {
+      if (data.modified) HotReload.refresh(data.modified);
+    }).connect();
+  }
+})();
+</script>`;
+}
+
+export function injectHotReload(
+  html: string,
+  mode: "full-page" | "off",
+): string {
+  const script = buildHotReloadScript(mode);
+  if (html.includes("</body>")) {
+    return html.replace("</body>", `${script}\n</body>`);
+  }
+  return html + script;
+}

package/src/theme/dev-server/index.ts

@@ -0,0 +1,125 @@
+import http from "node:http";
+import { SSEStream } from "./sse.js";
+import { proxyRequest } from "./proxy.js";
+import { watchTheme } from "./watcher.js";
+import { Syncer } from "../syncer.js";
+import type { ThemeRoot } from "../root.js";
+import type { ApiClient } from "../../api.js";
+
+export interface DevServerOptions {
+  host: string;
+  port: number;
+  reloadMode: "full-page" | "off";
+}
+
+export interface DevServerTheme {
+  id: number;
+  name: string;
+  company: string;
+  editorUrl?: string;
+}
+
+export async function startDevServer(
+  api: ApiClient,
+  theme: DevServerTheme,
+  themeRoot: ThemeRoot,
+  opts: DevServerOptions,
+  onReady?: (address: string) => void,
+): Promise<() => void> {
+  const sse = new SSEStream();
+  const syncer = new Syncer(api, theme.id, themeRoot);
+
+  const pendingUpdates = new Set<string>();
+
+  // ── Initial sync ─────────────────────────────────────────────────────────
+  console.log(`\nSyncing theme ${theme.name} (#${theme.id})…`);
+  await syncer.uploadTheme({
+    delete: true,
+    onProgress: (done, total) => {
+      process.stdout.write(`\r  Uploading ${done}/${total} files…`);
+    },
+  });
+  process.stdout.write("\n");
+
+  // ── File watcher ─────────────────────────────────────────────────────────
+  const stopWatcher = watchTheme(
+    themeRoot,
+    async (modified, added, removed) => {
+      const changed = [...modified, ...added];
+
+      for (const file of changed) {
+        pendingUpdates.add(file.relativePath);
+        try {
+          await syncer.uploadFile(file);
+        } catch (e) {
+          console.error(
+            `\n[Watcher] Upload failed: ${file.relativePath}: ${e}`,
+          );
+        } finally {
+          pendingUpdates.delete(file.relativePath);
+        }
+      }
+
+      for (const file of removed) {
+        try {
+          await syncer.deleteRemoteFile(file.relativePath);
+        } catch {
+          // ignore
+        }
+      }
+
+      if (removed.length > 0) {
+        sse.broadcast(JSON.stringify({ reload_page: true }));
+      } else if (changed.length > 0) {
+        sse.broadcast(
+          JSON.stringify({ modified: changed.map((f) => f.relativePath) }),
+        );
+      }
+    },
+  );
+
+  // ── HTTP server ───────────────────────────────────────────────────────────
+  const server = http.createServer(async (req, res) => {
+    if (req.url === "/hot-reload") {
+      sse.add(res);
+      return;
+    }
+
+    try {
+      await proxyRequest(req, res, {
+        company: theme.company,
+        themeId: theme.id,
+        reloadMode: opts.reloadMode,
+        pendingFiles: () =>
+          [...pendingUpdates]
+            .map((p) => themeRoot.file(p))
+            .filter((f) => f.isText)
+            .map((f) => ({
+              relativePath: f.relativePath,
+              read: () => f.read(),
+            })),
+      });
+    } catch (e) {
+      console.error(`[Proxy] ${req.method} ${req.url} → ${e}`);
+      if (!res.headersSent) {
+        res.writeHead(502);
+        res.end("Bad Gateway");
+      }
+    }
+  });
+
+  await new Promise<void>((resolve, reject) => {
+    server.listen(opts.port, opts.host, () => resolve());
+    server.on("error", reject);
+  });
+
+  const address = `http://${opts.host}:${opts.port}`;
+  onReady?.(address);
+
+  // ── Teardown ──────────────────────────────────────────────────────────────
+  return function stop() {
+    sse.close();
+    stopWatcher();
+    server.close();
+  };
+}

package/src/theme/dev-server/proxy.ts

@@ -0,0 +1,125 @@
+import https from "node:https";
+import type { IncomingMessage, ServerResponse } from "node:http";
+import { injectHotReload } from "./hot-reload.js";
+import { getAuthToken } from "@fluid-app/fluid-cli";
+
+const HOP_BY_HOP = new Set([
+  "connection",
+  "keep-alive",
+  "proxy-authenticate",
+  "proxy-authorization",
+  "te",
+  "trailer",
+  "transfer-encoding",
+  "upgrade",
+  "content-security-policy",
+]);
+
+export interface ProxyOptions {
+  company: string;
+  themeId: number;
+  reloadMode: "full-page" | "off";
+  pendingFiles?: () => Array<{ relativePath: string; read: () => string }>;
+}
+
+export async function proxyRequest(
+  req: IncomingMessage,
+  res: ServerResponse,
+  opts: ProxyOptions,
+): Promise<void> {
+  const companyHost = `${opts.company}.fluid.app`;
+
+  const headers: Record<string, string> = {};
+  for (const [k, v] of Object.entries(req.headers)) {
+    if (!HOP_BY_HOP.has(k.toLowerCase()) && typeof v === "string") {
+      headers[k] = v;
+    }
+  }
+  headers["host"] = companyHost;
+  headers["x-fluid-theme"] = String(opts.themeId);
+  headers["user-agent"] = "Fluid CLI";
+  headers["accept-encoding"] = "identity";
+
+  const url = new URL(req.url ?? "/", `http://${req.headers.host}`);
+  url.searchParams.set("_fd", "0");
+  url.searchParams.set("pb", "0");
+
+  const pending = opts.pendingFiles?.() ?? [];
+  const isGet = req.method === "GET" || req.method === "HEAD";
+  let method = req.method ?? "GET";
+  let body: string | Buffer | undefined;
+
+  if (pending.length > 0 && isGet) {
+    method = "POST";
+    const params = new URLSearchParams();
+    params.set("_method", req.method ?? "GET");
+    for (const f of pending) {
+      params.set(`replace_templates[${f.relativePath}]`, f.read());
+    }
+    const token = getAuthToken();
+    if (token) headers["authorization"] = `Bearer ${token}`;
+    headers["content-type"] = "application/x-www-form-urlencoded";
+    body = params.toString();
+    headers["content-length"] = String(Buffer.byteLength(body));
+  } else if (!isGet) {
+    body = await readBody(req);
+    if (body.length > 0) {
+      headers["content-length"] = String(body.length);
+    }
+  }
+
+  return new Promise((resolve, reject) => {
+    const options: https.RequestOptions = {
+      hostname: companyHost,
+      port: 443,
+      path: url.pathname + (url.search || ""),
+      method,
+      headers,
+    };
+
+    const proxyReq = https.request(options, (proxyRes) => {
+      const contentType = proxyRes.headers["content-type"] ?? "";
+      const isHtml = contentType.includes("text/html");
+
+      const responseHeaders: Record<string, string | string[]> = {};
+      for (const [k, v] of Object.entries(proxyRes.headers)) {
+        if (!HOP_BY_HOP.has(k.toLowerCase()) && v !== undefined) {
+          responseHeaders[k] = v as string | string[];
+        }
+      }
+
+      if (isHtml) {
+        const chunks: Buffer[] = [];
+        proxyRes.on("data", (chunk: Buffer) => chunks.push(chunk));
+        proxyRes.on("end", () => {
+          let html = Buffer.concat(chunks).toString("utf-8");
+          html = injectHotReload(html, opts.reloadMode);
+          responseHeaders["content-length"] = String(Buffer.byteLength(html));
+          res.writeHead(proxyRes.statusCode ?? 200, responseHeaders);
+          res.end(html);
+          resolve();
+        });
+      } else {
+        res.writeHead(proxyRes.statusCode ?? 200, responseHeaders);
+        proxyRes.pipe(res);
+        proxyRes.on("end", resolve);
+      }
+    });
+
+    proxyReq.on("error", (err) => {
+      reject(err);
+    });
+
+    if (body) proxyReq.write(body);
+    proxyReq.end();
+  });
+}
+
+function readBody(req: IncomingMessage): Promise<Buffer> {
+  return new Promise((resolve, reject) => {
+    const chunks: Buffer[] = [];
+    req.on("data", (chunk: Buffer) => chunks.push(chunk));
+    req.on("end", () => resolve(Buffer.concat(chunks)));
+    req.on("error", reject);
+  });
+}

package/src/theme/dev-server/sse.ts

@@ -0,0 +1,43 @@
+import type { ServerResponse } from "node:http";
+
+export class SSEStream {
+  private responses = new Set<ServerResponse>();
+
+  add(res: ServerResponse): void {
+    res.writeHead(200, {
+      "Content-Type": "text/event-stream",
+      "Cache-Control": "no-cache",
+      Connection: "keep-alive",
+      "Access-Control-Allow-Origin": "*",
+    });
+    res.write(":\n\n");
+    this.responses.add(res);
+    res.on("close", () => this.responses.delete(res));
+  }
+
+  broadcast(data: string): void {
+    const payload = `data: ${data}\n\n`;
+    for (const res of this.responses) {
+      try {
+        res.write(payload);
+      } catch {
+        this.responses.delete(res);
+      }
+    }
+  }
+
+  close(): void {
+    for (const res of this.responses) {
+      try {
+        res.end();
+      } catch {
+        // ignore
+      }
+    }
+    this.responses.clear();
+  }
+
+  get size(): number {
+    return this.responses.size;
+  }
+}

package/src/theme/dev-server/watcher.ts

@@ -0,0 +1,54 @@
+import { relative } from "node:path";
+import chokidar from "chokidar";
+import type { ThemeRoot } from "../root.js";
+import type { ThemeFile } from "../file.js";
+
+export type FileChangeHandler = (
+  modified: ThemeFile[],
+  added: ThemeFile[],
+  removed: ThemeFile[],
+) => Promise<void>;
+
+export function watchTheme(
+  root: ThemeRoot,
+  handler: FileChangeHandler,
+): () => Promise<void> {
+  const watcher = chokidar.watch(root.root, {
+    ignoreInitial: true,
+    ignored: (filePath: string) => {
+      if (filePath.includes("node_modules")) return true;
+      try {
+        const rel = relative(root.root, filePath);
+        const basename = rel.split(/[\\/]/).pop() ?? "";
+        return basename.startsWith(".") || root.ignore.ignore(rel);
+      } catch {
+        return false;
+      }
+    },
+    persistent: true,
+    awaitWriteFinish: { stabilityThreshold: 50, pollInterval: 10 },
+  });
+
+  let pending = Promise.resolve();
+  const enqueue = (fn: () => Promise<void>) => {
+    pending = pending.then(fn).catch(() => {});
+  };
+
+  watcher.on("change", (filePath) => {
+    const rel = relative(root.root, filePath);
+    if (root.ignore.ignore(rel)) return;
+    enqueue(() => handler([root.file(filePath)], [], []));
+  });
+
+  watcher.on("add", (filePath) => {
+    const rel = relative(root.root, filePath);
+    if (root.ignore.ignore(rel)) return;
+    enqueue(() => handler([], [root.file(filePath)], []));
+  });
+
+  watcher.on("unlink", (filePath) => {
+    enqueue(() => handler([], [], [root.file(filePath)]));
+  });
+
+  return () => watcher.close();
+}