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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fluid-app/fluid-cli-theme-dev",
-  "version": "0.1.9",
+  "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.5"
+    "@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,32 @@ 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;
 
@@ -120,14 +144,13 @@ export function createDevCommand(): Command {
             id: theme.id,
             name: theme.name,
             company,
-            editorUrl: theme.editor_url ?? undefined,
+            editorUrl,
           },
           themeRoot,
           { host: opts.host, port, reloadMode },
           (address) => {
             console.log(`\n  Dev server: ${address}`);
-            if (theme.editor_url)
-              console.log(`  Web editor: ${theme.editor_url}`);
+            console.log(`  Web editor: ${editorUrl}`);
             console.log("\n  Watching for file changes…\n");
 
             if (opts.navigate) {

package/src/commands/navigate.ts

@@ -4,6 +4,36 @@ import { requireToken, createApiClient } from "../api.js";
 import { getPluginState } from "../plugin-state.js";
 import { themes } from "@fluid-app/themes-api-client";
 
+function localSuggest(
+  input: string,
+  choices: prompts.Choice[],
+): prompts.Choice[] {
+  if (!input) return choices;
+  const lower = input.toLowerCase();
+  return choices.filter((c) => c.title.toLowerCase().includes(lower));
+}
+
+interface ThemeTemplate {
+  id: number;
+  name: string;
+  themeable_type: string;
+  default: boolean;
+}
+
+interface TemplatesResponse {
+  templates: ThemeTemplate[];
+}
+
+const THEMEABLE_TYPE_MAP: Record<string, string> = {
+  "/home": "home_page",
+  "/home/shop": "shop_page",
+  "/home/join": "join_page",
+  "/cart": "cart_page",
+  "/home/blog": "post_page",
+  "/home/categories": "category_page",
+  "/home/collections": "collection_page",
+};
+
 const STATIC_ROUTES = [
   { label: "Home", path: "/home" },
   { label: "Shop", path: "/home/shop" },
@@ -65,6 +95,50 @@ const RESOURCE_ROUTES = [
   },
 ] as const;
 
+async function fetchTemplatesForType(
+  api: ReturnType<typeof createApiClient>,
+  themeId: number,
+  themeableType: string,
+): Promise<ThemeTemplate[]> {
+  const params = new URLSearchParams({
+    application_theme_id: String(themeId),
+    themeable_type: themeableType,
+    published: "true",
+  });
+  const body = await api.get<TemplatesResponse>(
+    `/api/application_theme_templates?${params}`,
+  );
+  return body.templates ?? [];
+}
+
+async function selectTemplate(
+  api: ReturnType<typeof createApiClient>,
+  themeId: number,
+  themeableType: string,
+  onCancel: () => void,
+): Promise<number | null> {
+  const templates = await fetchTemplatesForType(api, themeId, themeableType);
+  if (templates.length <= 1) return null;
+
+  const templateChoices = templates.map((t) => ({
+    title: `${t.name}${t.default ? " (default)" : ""}`,
+    value: t.id,
+  }));
+  const { templateId } = await prompts(
+    {
+      type: "autocomplete",
+      name: "templateId",
+      message: "Select a template",
+      choices: templateChoices,
+      suggest: (input: string, choices: prompts.Choice[]) =>
+        Promise.resolve(localSuggest(input, choices)),
+    },
+    { onCancel },
+  );
+
+  return templateId ?? null;
+}
+
 export function createNavigateCommand(): Command {
   return new Command("navigate")
     .description("Interactively navigate to a route in the dev server browser")
@@ -115,21 +189,27 @@ export function createNavigateCommand(): Command {
 
       const { dest } = await prompts(
         {
-          type: "select",
+          type: "autocomplete",
           name: "dest",
           message: "Select a route",
           choices,
+          suggest: (input: string, choices: prompts.Choice[]) =>
+            Promise.resolve(localSuggest(input, choices)),
         },
         { onCancel },
       );
 
       if (!dest) return;
 
+      const api = createApiClient();
       let path: string;
+      let themeableType: string | undefined;
+
       if (typeof dest === "string") {
         path = dest;
+        themeableType = THEMEABLE_TYPE_MAP[dest];
       } else {
-        const api = createApiClient();
+        themeableType = dest.resourceType;
         const body = await themes.getApplicationThemeAvailableThemeables(
           api,
           themeId,
@@ -141,15 +221,18 @@ export function createNavigateCommand(): Command {
           console.log(`No ${dest.label} resources found, using listing page.`);
           path = dest.fallback;
         } else {
+          const resourceChoices = resources.map((r) => ({
+            title: r.title ?? r.slug ?? "Untitled",
+            value: r.slug,
+          }));
           const { slug } = await prompts(
             {
-              type: "select",
+              type: "autocomplete",
               name: "slug",
               message: `Select a ${dest.label.toLowerCase()}`,
-              choices: resources.map((r) => ({
-                title: r.title ?? r.slug ?? "Untitled",
-                value: r.slug,
-              })),
+              choices: resourceChoices,
+              suggest: (input: string, choices: prompts.Choice[]) =>
+                Promise.resolve(localSuggest(input, choices)),
             },
             { onCancel },
           );
@@ -157,7 +240,20 @@ export function createNavigateCommand(): Command {
         }
       }
 
-      const url = `${address}${path}`;
+      let templateParam = "";
+      if (themeableType) {
+        const templateId = await selectTemplate(
+          api,
+          themeId,
+          themeableType,
+          onCancel,
+        );
+        if (templateId) {
+          templateParam = `?theme_template_id=${templateId}`;
+        }
+      }
+
+      const url = `${address}${path}${templateParam}`;
       console.log(`\nNavigating to: ${url}\n`);
       const open = (await import("open")).default;
       await open(url);

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 {