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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fluid-app/fluid-cli-theme-dev",
-  "version": "0.1.10",
+  "version": "0.1.12",
   "description": "Fluid CLI plugin for theme developer workflows — dev server, push, pull, init",
   "type": "module",
   "main": "./dist/index.mjs",
@@ -23,7 +23,8 @@
     "open": "^10.0.0",
     "ora": "^8.0.0",
     "prompts": "^2.4.2",
-    "@fluid-app/fluid-cli": "0.1.6"
+    "@fluid-app/theme-schema": "0.1.0",
+    "@fluid-app/fluid-cli": "0.1.7"
   },
   "devDependencies": {
     "@types/node": "^24",

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;
@@ -124,7 +147,7 @@ export function createDevCommand(): Command {
             editorUrl,
           },
           themeRoot,
-          { host: opts.host, port, reloadMode },
+          { host: opts.host, port, reloadMode, validate: !opts.force },
           (address) => {
             console.log(`\n  Dev server: ${address}`);
             console.log(`  Web editor: ${editorUrl}`);

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);
@@ -74,12 +177,19 @@ export function createPushCommand(): Command {
 
         const result = await syncer.uploadTheme({
           delete: !opts.nodelete,
+          validate: !opts.force,
           onProgress: (d, total) => {
             spinner.text = `Pushing ${d}/${total} files…`;
           },
         });
 
-        if (result.errors.length) {
+        if (result.validationFailed) {
+          spinner.fail(
+            `Schema validation failed (${result.errors.length} error(s)). Use --force to skip.`,
+          );
+          for (const e of result.errors) console.error(`  ${e}`);
+          process.exit(1);
+        } else if (result.errors.length) {
           spinner.warn(`Pushed with ${result.errors.length} error(s).`);
           for (const e of result.errors) console.error(`  ${e}`);
         } else {
@@ -88,6 +198,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/dev-server/index.ts

@@ -23,7 +23,7 @@ export async function startDevServer(
   api: ApiClient,
   theme: DevServerTheme,
   themeRoot: ThemeRoot,
-  opts: DevServerOptions,
+  opts: DevServerOptions & { validate?: boolean },
   onReady?: (address: string) => void,
 ): Promise<() => void> {
   const sse = new SSEStream();
@@ -33,13 +33,23 @@ export async function startDevServer(
 
   // ── Initial sync ─────────────────────────────────────────────────────────
   console.log(`\nSyncing theme ${theme.name} (#${theme.id})…`);
-  await syncer.uploadTheme({
+  const syncResult = await syncer.uploadTheme({
     delete: true,
+    validate: opts.validate,
     onProgress: (done, total) => {
       process.stdout.write(`\r  Uploading ${done}/${total} files…`);
     },
   });
   process.stdout.write("\n");
+  if (syncResult.validationFailed) {
+    console.error(
+      `\nSchema validation failed (${syncResult.errors.length} error(s)). Use --force to skip.\n`,
+    );
+    for (const e of syncResult.errors) console.error(`  ${e}`);
+    process.exit(1);
+  } else if (syncResult.errors.length > 0) {
+    for (const e of syncResult.errors) console.error(`  ${e}`);
+  }
 
   // ── File watcher ─────────────────────────────────────────────────────────
   const stopWatcher = watchTheme(
@@ -48,6 +58,16 @@ export async function startDevServer(
       const changed = [...modified, ...added];
 
       for (const file of changed) {
+        // Validate schema on liquid files during dev (warn, don't block)
+        if (opts.validate && file.isLiquid) {
+          const diagnostics = file.validateSchema();
+          for (const d of diagnostics) {
+            const prefix =
+              d.severity === "error" ? "Schema error" : "Schema warning";
+            console.warn(`\n[${prefix}] ${file.relativePath}: ${d.message}`);
+          }
+        }
+
         pendingUpdates.add(file.relativePath);
         try {
           await syncer.uploadFile(file);

package/src/theme/file.ts

@@ -8,6 +8,11 @@ import {
 import { extname, basename, relative, dirname } from "node:path";
 import { createHash } from "node:crypto";
 import { mimeTypeFor, type MimeType } from "./mime-type.js";
+import {
+  validateSchemaText,
+  type Diagnostic,
+  type BlocksSchemaType,
+} from "@fluid-app/theme-schema";
 
 export class ThemeFile {
   readonly absolutePath: string;
@@ -65,4 +70,27 @@ export class ThemeFile {
   size(): number {
     return statSync(this.absolutePath).size;
   }
+
+  get isTemplate(): boolean {
+    // Template files (home_page, product, etc.) expect blocks as objects.
+    // Section files expect blocks as arrays.
+    const parts = this.relativePath.split(/[/\\]/);
+    return (
+      parts[0] === "templates" &&
+      parts.length >= 3 &&
+      parts[1] !== "sections" &&
+      parts[1] !== "blocks" &&
+      parts[1] !== "components"
+    );
+  }
+
+  validateSchema(): Diagnostic[] {
+    if (!this.isLiquid) return [];
+
+    const blocksSchemaType: BlocksSchemaType = this.isTemplate
+      ? "object"
+      : "array";
+
+    return validateSchemaText(this.read(), { blocksSchemaType });
+  }
 }