@fluid-app/fluid-cli-theme-dev 0.1.10 → 0.1.11

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fluid-app/fluid-cli-theme-dev",
-  "version": "0.1.10",
+  "version": "0.1.11",
   "description": "Fluid CLI plugin for theme developer workflows — dev server, push, pull, init",
   "type": "module",
   "main": "./dist/index.mjs",
@@ -23,15 +23,15 @@
     "open": "^10.0.0",
     "ora": "^8.0.0",
     "prompts": "^2.4.2",
-    "@fluid-app/fluid-cli": "0.1.6"
+    "@fluid-app/fluid-cli": "0.1.7"
   },
   "devDependencies": {
     "@types/node": "^24",
     "@types/prompts": "^2.4.9",
     "tsdown": "^0.21.0",
     "typescript": "^5",
-    "@fluid-app/api-client-core": "0.1.0",
     "@fluid-app/typescript-config": "0.0.0",
+    "@fluid-app/api-client-core": "0.1.0",
     "@fluid-app/themes-api-client": "0.1.0"
   },
   "engines": {

package/src/commands/dev.ts

@@ -1,10 +1,12 @@
 import { Command } from "commander";
 import { requireToken, createApiClient } from "../api.js";
+import { readThemeConfig } from "../theme-config.js";
 import { getPluginState, setPluginState } from "../plugin-state.js";
 import { ThemeRoot } from "../theme/root.js";
 import { startDevServer } from "../theme/dev-server/index.js";
 import { themes } from "@fluid-app/themes-api-client";
 import { findTheme, type ApplicationTheme } from "../theme-picker.js";
+import { findWorkspace, resolveThemeRootFromCwd } from "../workspace.js";
 
 interface CompanyMe {
   data: { company: { subdomain?: string; name?: string } };
@@ -75,9 +77,18 @@ export function createDevCommand(): Command {
       }) => {
         requireToken();
 
-        const themeRoot = new ThemeRoot(opts.root);
+        // If no explicit --root and we're inside a workspace, resolve to the theme root
+        let rootPath = opts.root;
+        if (rootPath === ".") {
+          const workspace = findWorkspace();
+          if (workspace) {
+            rootPath = resolveThemeRootFromCwd(workspace) ?? rootPath;
+          }
+        }
+
+        const themeRoot = new ThemeRoot(rootPath);
         if (!themeRoot.isValid()) {
-          console.error(`'${opts.root}' does not look like a theme directory.`);
+          console.error(`'${rootPath}' does not look like a theme directory.`);
           process.exit(1);
         }
 
@@ -91,19 +102,31 @@ export function createDevCommand(): Command {
 
         const reloadMode = opts.liveReload === "off" ? "off" : "full-page";
         const api = createApiClient();
-
-        const companyRes = await api.get<CompanyMe>(
-          "/api/company/v1/companies/me",
-        );
-        const company = companyRes.data?.company?.subdomain;
-        if (!company) {
-          console.error(
-            "Could not determine company subdomain. Make sure your token is valid.",
+        const config = readThemeConfig(themeRoot.root);
+
+        // Use company from .fluid-theme.json if available, otherwise fetch
+        let company: string;
+        if (config?.company) {
+          company = config.company;
+        } else {
+          const companyRes = await api.get<CompanyMe>(
+            "/api/company/v1/companies/me",
           );
-          process.exit(1);
+          company = companyRes.data?.company?.subdomain ?? "";
+          if (!company) {
+            console.error(
+              "Could not determine company subdomain. Make sure your token is valid.",
+            );
+            process.exit(1);
+          }
         }
 
-        const theme = await ensureDevTheme(api, opts.theme);
+        // Use theme from .fluid-theme.json if available and no --theme flag
+        const theme = opts.theme
+          ? await ensureDevTheme(api, opts.theme)
+          : config
+            ? await ensureDevTheme(api, String(config.themeId))
+            : await ensureDevTheme(api);
         const editorUrl = `https://admin.fluid.app/themes/${theme.id}/editor`;
 
         let stop: (() => void) | undefined;

package/src/commands/pull.ts

@@ -1,43 +1,241 @@
+import { join, resolve } from "node:path";
+import chalk from "chalk";
 import { Command } from "commander";
 import ora from "ora";
+import prompts from "prompts";
 import { requireToken, createApiClient } from "../api.js";
+import { readThemeConfig, writeThemeConfig } from "../theme-config.js";
 import { ThemeRoot } from "../theme/root.js";
 import { Syncer } from "../theme/syncer.js";
 import { selectTheme, findTheme } from "../theme-picker.js";
+import { findWorkspace, resolveThemeRootFromCwd } from "../workspace.js";
+
+interface CompanyMe {
+  data: { company: { subdomain?: string; name?: string } };
+}
+
+async function fetchCompanySubdomain(
+  api: ReturnType<typeof createApiClient>,
+): Promise<string> {
+  const res = await api.get<CompanyMe>("/api/company/v1/companies/me");
+  const subdomain = res.data?.company?.subdomain;
+  if (!subdomain) {
+    console.error(
+      "Could not determine company subdomain. Make sure your token is valid.",
+    );
+    process.exit(1);
+  }
+  return subdomain;
+}
+
+function formatRelativeTime(iso: string): string {
+  const diff = Date.now() - new Date(iso).getTime();
+  const minutes = Math.floor(diff / 60_000);
+  if (minutes < 1) return "just now";
+  if (minutes < 60) return `${minutes}m ago`;
+  const hours = Math.floor(minutes / 60);
+  if (hours < 24) return `${hours}h ago`;
+  const days = Math.floor(hours / 24);
+  if (days === 1) return "yesterday";
+  const date = new Date(iso);
+  return `${days}d ago (${date.toLocaleDateString("en-US", { month: "short", day: "numeric", year: "numeric" })})`;
+}
+
+/**
+ * Detect files where both local and remote have changed since the last pull.
+ * Returns the set of conflicting resource keys.
+ */
+function detectConflicts(
+  storedChecksums: Record<string, string>,
+  remoteChecksums: Record<string, string>,
+  themeRoot: ThemeRoot,
+): string[] {
+  const conflicts: string[] = [];
+  for (const [key, storedChecksum] of Object.entries(storedChecksums)) {
+    const remoteChecksum = remoteChecksums[key];
+    if (remoteChecksum === undefined) continue; // deleted on remote, not a conflict
+    if (remoteChecksum === storedChecksum) continue; // remote unchanged
+
+    // Remote changed — check if local also changed
+    const file = themeRoot.file(key);
+    if (!file.exists) continue; // local deleted, not a conflict (remote wins)
+    const localChecksum = file.checksum();
+    if (localChecksum === storedChecksum) continue; // local unchanged, safe to overwrite
+    if (localChecksum === remoteChecksum) continue; // both sides made same change
+
+    conflicts.push(key);
+  }
+  return conflicts;
+}
 
 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", ".")
+    .option("--root <path>", "Theme root directory")
+    .option("-y, --yes", "Skip confirmation prompt")
     .action(
-      async (opts: { theme?: string; nodelete?: boolean; root: string }) => {
+      async (opts: {
+        theme?: string;
+        nodelete?: boolean;
+        root?: string;
+        yes?: boolean;
+      }) => {
         requireToken();
 
         const api = createApiClient();
+        const workspace = findWorkspace();
+
         const theme = opts.theme
           ? await findTheme(api, opts.theme)
           : await selectTheme(api, "Select a theme to pull");
-        const themeRoot = new ThemeRoot(opts.root);
+
+        // Resolve output directory
+        const subdomain = await fetchCompanySubdomain(api);
+        let root: string;
+        if (opts.root) {
+          root = opts.root;
+        } else if (workspace) {
+          // If already inside local/{company}/, use that directory
+          root =
+            resolveThemeRootFromCwd(workspace) ??
+            join(workspace.root, "local", subdomain);
+        } else {
+          root = `.`;
+        }
+
+        const absoluteRoot = resolve(root);
+        const existingConfig = readThemeConfig(absoluteRoot);
+
+        // Pre-flight summary
+        console.log();
+        console.log(`  Theme:   ${chalk.bold(theme.name)} (#${theme.id})`);
+        console.log(`  Company: ${chalk.bold(subdomain)}`);
+        console.log(`  Target:  ${chalk.bold(absoluteRoot)}`);
+        if (existingConfig?.lastPulledAt) {
+          console.log(
+            `  Last pulled: ${formatRelativeTime(existingConfig.lastPulledAt)}`,
+          );
+        }
+        console.log();
+
+        // Conflict detection — only possible if we have a previous pull's checksums
+        const themeRoot = new ThemeRoot(root);
+        let skipKeys: Set<string> | undefined;
+
+        if (existingConfig?.checksums) {
+          const fetchSpinner = ora("Checking for conflicts…").start();
+          const syncer = new Syncer(api, theme.id, themeRoot);
+          await syncer.fetchChecksums();
+          const remoteChecksums = syncer.remoteChecksums();
+          const conflicts = detectConflicts(
+            existingConfig.checksums,
+            remoteChecksums,
+            themeRoot,
+          );
+          fetchSpinner.stop();
+
+          if (conflicts.length > 0) {
+            console.log(
+              chalk.yellow(`⚠ ${conflicts.length} conflict(s) detected:\n`),
+            );
+            for (const key of conflicts) {
+              console.log(`  ${key}`);
+            }
+            console.log();
+
+            const { resolution } = await prompts(
+              {
+                type: "select",
+                name: "resolution",
+                message: "How do you want to handle conflicts?",
+                choices: [
+                  {
+                    title: "Keep local (skip conflicting files)",
+                    value: "keep-local",
+                  },
+                  {
+                    title: "Use remote (overwrite local changes)",
+                    value: "use-remote",
+                  },
+                  { title: "Abort", value: "abort" },
+                ],
+              },
+              { onCancel: () => process.exit(130) },
+            );
+
+            if (resolution === "abort") {
+              console.log("Aborted.");
+              process.exit(0);
+            }
+
+            if (resolution === "keep-local") {
+              skipKeys = new Set(conflicts);
+            }
+            // "use-remote" → skipKeys stays undefined, everything gets overwritten
+          }
+        }
+
+        if (!opts.yes && !skipKeys) {
+          const { confirmed } = await prompts(
+            {
+              type: "confirm",
+              name: "confirmed",
+              message: "Pull theme to this directory?",
+              initial: true,
+            },
+            { onCancel: () => process.exit(130) },
+          );
+          if (!confirmed) {
+            console.log("Aborted.");
+            process.exit(0);
+          }
+        }
 
         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,
+          skip: skipKeys,
           onProgress: (d, total) => {
             spinner.text = `Downloading ${d}/${total} files…`;
           },
         });
 
+        // Write .fluid-theme.json with the post-pull state.
+        // For skipped files, preserve the old stored checksum so the conflict
+        // is still detected on the next pull (instead of silently overwriting).
+        const newChecksums = syncer.remoteChecksums();
+        if (skipKeys && existingConfig?.checksums) {
+          for (const key of skipKeys) {
+            const oldChecksum = existingConfig.checksums[key];
+            if (oldChecksum) {
+              newChecksums[key] = oldChecksum;
+            }
+          }
+        }
+
+        writeThemeConfig(absoluteRoot, {
+          themeId: theme.id,
+          themeName: theme.name,
+          company: subdomain,
+          lastPulledAt: new Date().toISOString(),
+          checksums: newChecksums,
+        });
+
+        const parts: string[] = [`Downloaded ${result.downloaded} file(s)`];
+        if (result.deleted > 0)
+          parts.push(`deleted ${result.deleted} local file(s)`);
+        if (result.skipped > 0)
+          parts.push(`skipped ${result.skipped} conflict(s)`);
+
         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).`,
-          );
+          spinner.succeed(`${parts.join(", ")}.`);
         }
       },
     );

package/src/commands/push.ts

@@ -1,7 +1,9 @@
+import chalk from "chalk";
 import { Command } from "commander";
 import ora from "ora";
 import prompts from "prompts";
 import { requireToken, createApiClient } from "../api.js";
+import { readThemeConfig, writeThemeConfig } from "../theme-config.js";
 import { ThemeRoot } from "../theme/root.js";
 import { Syncer } from "../theme/syncer.js";
 import { themes } from "@fluid-app/themes-api-client";
@@ -10,6 +12,33 @@ import {
   findTheme,
   type ApplicationTheme,
 } from "../theme-picker.js";
+import { findWorkspace, resolveThemeRootFromCwd } from "../workspace.js";
+
+/**
+ * Detect files where the remote has changed since the last pull,
+ * and we also have local changes (i.e. we'd overwrite someone else's work).
+ */
+function detectRemoteDrift(
+  storedChecksums: Record<string, string>,
+  remoteChecksums: Record<string, string>,
+  themeRoot: ThemeRoot,
+): string[] {
+  const conflicts: string[] = [];
+  for (const [key, storedChecksum] of Object.entries(storedChecksums)) {
+    const remoteChecksum = remoteChecksums[key];
+    if (remoteChecksum === undefined) continue;
+    if (remoteChecksum === storedChecksum) continue; // remote unchanged since pull
+
+    // Remote changed — check if we also have this file locally (and it differs)
+    const file = themeRoot.file(key);
+    if (!file.exists) continue;
+    const localChecksum = file.checksum();
+    if (localChecksum === remoteChecksum) continue; // local matches remote already
+
+    conflicts.push(key);
+  }
+  return conflicts;
+}
 
 export function createPushCommand(): Command {
   return new Command("push")
@@ -34,13 +63,23 @@ export function createPushCommand(): Command {
       }) => {
         requireToken();
 
-        const themeRoot = new ThemeRoot(opts.root);
+        // If no explicit --root and we're inside a workspace, resolve to the theme root
+        let rootPath = opts.root;
+        if (rootPath === ".") {
+          const workspace = findWorkspace();
+          if (workspace) {
+            rootPath = resolveThemeRootFromCwd(workspace) ?? rootPath;
+          }
+        }
+
+        const themeRoot = new ThemeRoot(rootPath);
         if (!themeRoot.isValid()) {
-          console.error(`'${opts.root}' does not look like a theme directory.`);
+          console.error(`'${rootPath}' does not look like a theme directory.`);
           process.exit(1);
         }
 
         const api = createApiClient();
+        const config = readThemeConfig(themeRoot.root);
         let theme: ApplicationTheme;
 
         if (opts.unpublished) {
@@ -63,10 +102,74 @@ export function createPushCommand(): Command {
           console.log(
             `Created unpublished theme: ${theme.name} (#${theme.id})`,
           );
+        } else if (opts.theme) {
+          theme = await findTheme(api, opts.theme);
+        } else if (config) {
+          // Use .fluid-theme.json as the default
+          console.log(
+            `  Using theme from .fluid-theme.json: ${chalk.bold(config.themeName)} (#${config.themeId})`,
+          );
+          const body = await themes.getApplicationTheme(api, config.themeId);
+          theme = body.application_theme;
         } else {
-          theme = opts.theme
-            ? await findTheme(api, opts.theme)
-            : await selectTheme(api, "Select a theme to push to");
+          theme = await selectTheme(api, "Select a theme to push to");
+        }
+
+        // Check for remote drift if we have stored checksums
+        if (config?.checksums && !opts.force) {
+          const driftSpinner = ora("Checking for remote changes…").start();
+          const driftSyncer = new Syncer(api, theme.id, themeRoot);
+          await driftSyncer.fetchChecksums();
+          const remoteChecksums = driftSyncer.remoteChecksums();
+          const conflicts = detectRemoteDrift(
+            config.checksums,
+            remoteChecksums,
+            themeRoot,
+          );
+          driftSpinner.stop();
+
+          if (conflicts.length > 0) {
+            console.log(
+              chalk.yellow(
+                `\n⚠ ${conflicts.length} file(s) changed on remote since last pull:\n`,
+              ),
+            );
+            for (const key of conflicts) {
+              console.log(`  ${key}`);
+            }
+            console.log();
+
+            const { resolution } = await prompts(
+              {
+                type: "select",
+                name: "resolution",
+                message: "How do you want to handle this?",
+                choices: [
+                  {
+                    title: "Push anyway (overwrite remote changes)",
+                    value: "push",
+                  },
+                  {
+                    title: "Pull first, then push",
+                    value: "pull-first",
+                  },
+                  { title: "Abort", value: "abort" },
+                ],
+              },
+              { onCancel: () => process.exit(130) },
+            );
+
+            if (resolution === "abort") {
+              console.log("Aborted.");
+              process.exit(0);
+            }
+            if (resolution === "pull-first") {
+              console.log(
+                `Run ${chalk.cyan("fluid theme pull")} first, then push again.`,
+              );
+              process.exit(0);
+            }
+          }
         }
 
         const syncer = new Syncer(api, theme.id, themeRoot);
@@ -88,6 +191,14 @@ export function createPushCommand(): Command {
           );
         }
 
+        // Update stored checksums after successful push
+        if (config) {
+          writeThemeConfig(themeRoot.root, {
+            ...config,
+            checksums: syncer.remoteChecksums(),
+          });
+        }
+
         if (opts.publish) {
           const pubSpinner = ora("Publishing theme…").start();
           try {

package/src/theme/syncer.ts

@@ -46,6 +46,11 @@ export class Syncer {
     return [...this.checksums.keys()];
   }
 
+  /** Snapshot of remote checksums (key → sha256). Available after fetchChecksums() or downloadAll(). */
+  remoteChecksums(): Record<string, string> {
+    return Object.fromEntries(this.checksums);
+  }
+
   // ─── Upload ───────────────────────────────────────────────────────────────
 
   async uploadFile(file: ThemeFile): Promise<void> {
@@ -242,19 +247,27 @@ export class Syncer {
   async downloadTheme(
     opts: {
       delete?: boolean;
+      skip?: Set<string>;
       onProgress?: (done: number, total: number) => void;
     } = {},
-  ): Promise<SyncResult> {
+  ): Promise<SyncResult & { skipped: number }> {
     const resources = await this.downloadAll();
-    const result: SyncResult = {
+    const result: SyncResult & { skipped: number } = {
       uploaded: 0,
       deleted: 0,
       downloaded: 0,
+      skipped: 0,
       errors: [],
     };
 
     let done = 0;
     for (const resource of resources) {
+      if (opts.skip?.has(resource.key)) {
+        result.skipped++;
+        opts.onProgress?.(++done, resources.length);
+        continue;
+      }
+
       const file = this.themeRoot.file(resource.key);
 
       // Guard against path traversal from malicious API responses

package/src/theme-config.ts

@@ -0,0 +1,34 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+export interface ThemeConfig {
+  themeId: number;
+  themeName: string;
+  company: string;
+  lastPulledAt: string | null;
+  checksums: Record<string, string>;
+}
+
+const CONFIG_FILE = ".fluid-theme.json";
+
+function configPath(themeRoot: string): string {
+  return join(themeRoot, CONFIG_FILE);
+}
+
+/** Read `.fluid-theme.json` from a theme directory, or null if it doesn't exist. */
+export function readThemeConfig(themeRoot: string): ThemeConfig | null {
+  const path = configPath(themeRoot);
+  if (!existsSync(path)) return null;
+  try {
+    const raw = readFileSync(path, "utf-8");
+    return JSON.parse(raw) as ThemeConfig;
+  } catch {
+    return null;
+  }
+}
+
+/** Write `.fluid-theme.json` to a theme directory. */
+export function writeThemeConfig(themeRoot: string, config: ThemeConfig): void {
+  const path = configPath(themeRoot);
+  writeFileSync(path, JSON.stringify(config, null, 2) + "\n", "utf-8");
+}

package/src/workspace.ts

@@ -0,0 +1,71 @@
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join, relative, resolve, sep } from "node:path";
+
+export interface FluidWorkspace {
+  /** Absolute path to the workspace root (where .fluid-workspace.json lives) */
+  root: string;
+  /** Parsed workspace config */
+  config: WorkspaceConfig;
+}
+
+interface WorkspaceConfig {
+  type: string;
+  version: number;
+}
+
+const WORKSPACE_FILE = ".fluid-workspace.json";
+
+/**
+ * Walk up from `startDir` looking for `.fluid-workspace.json`.
+ * Returns the workspace info if found, or `null` if not in a workspace.
+ */
+export function findWorkspace(startDir?: string): FluidWorkspace | null {
+  let dir = resolve(startDir ?? process.cwd());
+
+  // eslint-disable-next-line no-constant-condition
+  while (true) {
+    const candidate = join(dir, WORKSPACE_FILE);
+    if (existsSync(candidate)) {
+      try {
+        const raw = readFileSync(candidate, "utf-8");
+        const config = JSON.parse(raw) as WorkspaceConfig;
+        return { root: dir, config };
+      } catch {
+        return null;
+      }
+    }
+    const parent = dirname(dir);
+    if (parent === dir) break; // reached filesystem root
+    dir = parent;
+  }
+
+  return null;
+}
+
+/**
+ * If cwd is already inside `{workspace}/local/{company}/...`, return that
+ * theme root directory. Otherwise return null.
+ *
+ * Examples (workspace root = /code/fluid-theme-dev):
+ *   cwd = /code/fluid-theme-dev/local/acme-co           → /code/fluid-theme-dev/local/acme-co
+ *   cwd = /code/fluid-theme-dev/local/acme-co/templates  → /code/fluid-theme-dev/local/acme-co
+ *   cwd = /code/fluid-theme-dev                          → null
+ *   cwd = /code/fluid-theme-dev/local                    → null
+ */
+export function resolveThemeRootFromCwd(
+  workspace: FluidWorkspace,
+): string | null {
+  const cwd = resolve(process.cwd());
+  const localDir = join(workspace.root, "local");
+  const rel = relative(localDir, cwd);
+
+  // Not under local/ at all, or exactly at local/
+  if (rel.startsWith("..") || rel === ".") return null;
+
+  // rel is like "acme-co" or "acme-co/templates/subfolder"
+  // The theme root is the first segment: local/{company}
+  const firstSegment = rel.split(sep)[0];
+  if (!firstSegment) return null;
+
+  return join(localDir, firstSegment);
+}

package/tsdown.config.ts

@@ -5,7 +5,7 @@ export default defineConfig({
   format: ["esm"],
   dts: { eager: true },
   clean: true,
-  target: "node18",
+  target: "node24",
   deps: {
     neverBundle: [
       "@fluid-app/fluid-cli",