@fluid-app/fluid-cli-theme-dev 0.1.14 → 0.1.16

package/jest.config.cjs

@@ -0,0 +1,21 @@
+module.exports = {
+  testEnvironment: "node",
+  testMatch: ["**/src/**/__tests__/**/*.test.ts"],
+  transform: {
+    "^.+\\.(t|j)sx?$": [
+      "@swc/jest",
+      {
+        module: {
+          type: "commonjs",
+        },
+      },
+    ],
+  },
+  moduleFileExtensions: ["ts", "tsx", "js", "jsx", "json", "node"],
+  moduleNameMapper: {
+    // The real package only ships ESM, which Jest can't resolve in CJS mode;
+    // map it to a stateful in-memory mock for plugin-state tests.
+    "^@fluid-app/fluid-cli$": "<rootDir>/jest.mocks/fluid-cli.ts",
+    "^(\\.{1,2}/.*)\\.js$": "$1",
+  },
+};

package/jest.mocks/fluid-cli.ts

@@ -0,0 +1,33 @@
+/**
+ * Jest mock for @fluid-app/fluid-cli.
+ *
+ * The real package only exports ESM (.mjs), which Jest can't resolve in CJS
+ * mode. plugin-state.ts only uses `readConfig`/`updateConfig`, so this mock
+ * backs them with an in-memory config. Tests seed/reset state through the
+ * normal `updateConfig` surface, so no test-only exports are needed.
+ */
+
+interface FakeConfig {
+  activeProfile: string | null;
+  profiles: Record<string, unknown>;
+  plugins: Record<string, unknown>;
+  enabledPlugins: string[] | null;
+}
+
+let config: FakeConfig = {
+  activeProfile: null,
+  profiles: {},
+  plugins: {},
+  enabledPlugins: null,
+};
+
+export function readConfig(): FakeConfig {
+  return config;
+}
+
+export function updateConfig(
+  updater: (config: FakeConfig) => FakeConfig,
+): FakeConfig {
+  config = updater(config);
+  return config;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fluid-app/fluid-cli-theme-dev",
-  "version": "0.1.14",
+  "version": "0.1.16",
   "description": "Fluid CLI plugin for theme developer workflows — dev server, push, pull, init",
   "type": "module",
   "main": "./dist/index.mjs",
@@ -26,14 +26,18 @@
     "@fluid-app/fluid-cli": "0.1.8"
   },
   "devDependencies": {
+    "@swc/core": "^1.15.18",
+    "@swc/jest": "^0.2.39",
+    "@types/jest": "^29.5.14",
     "@types/node": "^24",
     "@types/prompts": "^2.4.9",
+    "jest": "^29.7.0",
     "tsdown": "^0.21.0",
     "typescript": "^5",
-    "@fluid-app/theme-schema": "0.1.0",
-    "@fluid-app/themes-api-client": "0.1.0",
     "@fluid-app/api-client-core": "0.1.0",
-    "@fluid-app/typescript-config": "0.0.0"
+    "@fluid-app/theme-schema": "0.1.0",
+    "@fluid-app/typescript-config": "0.0.0",
+    "@fluid-app/themes-api-client": "0.1.0"
   },
   "engines": {
     "node": ">=18.0.0"
@@ -41,6 +45,7 @@
   "scripts": {
     "build": "tsdown",
     "dev": "tsdown --watch",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "test": "jest"
   }
 }

package/src/__tests__/plugin-state.test.ts

@@ -0,0 +1,186 @@
+import { existsSync } from "node:fs";
+import {
+  readConfig,
+  updateConfig,
+  type FluidConfig,
+} from "@fluid-app/fluid-cli";
+import {
+  devThemeKey,
+  getDevTheme,
+  setDevTheme,
+  clearDevTheme,
+  setLastDevThemeId,
+  getLastDevThemeId,
+} from "../plugin-state.js";
+
+// `@fluid-app/fluid-cli` is mapped to an in-memory mock (jest.mocks/fluid-cli.ts)
+// so these helpers never touch the real ~/.fluid/config.json. State is seeded
+// and reset through the normal `updateConfig` surface.
+jest.mock("node:fs", () => ({ existsSync: jest.fn() }));
+const existsSyncMock = existsSync as unknown as jest.Mock;
+
+const PLUGIN_KEY = "theme-dev";
+
+function freshConfig(): FluidConfig {
+  return {
+    activeProfile: null,
+    profiles: {},
+    plugins: {},
+    enabledPlugins: null,
+  };
+}
+
+function setPluginState(state: Record<string, unknown>): void {
+  updateConfig((config) => ({
+    ...config,
+    plugins: { ...config.plugins, [PLUGIN_KEY]: state },
+  }));
+}
+
+function pluginState(): Record<string, unknown> {
+  return readConfig().plugins[PLUGIN_KEY] as Record<string, unknown>;
+}
+
+beforeEach(() => {
+  updateConfig(() => freshConfig());
+  // Default: every stored project directory still exists (no pruning).
+  existsSyncMock.mockReset();
+  existsSyncMock.mockReturnValue(true);
+});
+
+describe("devThemeKey", () => {
+  it("combines company and theme root", () => {
+    expect(devThemeKey("acme", "/themes/store")).toBe("acme:/themes/store");
+  });
+
+  it("falls back to 'default' when company is undefined", () => {
+    expect(devThemeKey(undefined, "/themes/store")).toBe(
+      "default:/themes/store",
+    );
+  });
+});
+
+describe("setDevTheme / getDevTheme", () => {
+  it("stores and retrieves a dev theme per key", () => {
+    setDevTheme("acme:/a", { id: 1, name: "A" });
+    expect(getDevTheme("acme:/a")).toEqual({ id: 1, name: "A" });
+  });
+
+  it("isolates dev themes across keys", () => {
+    setDevTheme("acme:/a", { id: 1, name: "A" });
+    setDevTheme("acme:/b", { id: 2, name: "B" });
+    expect(getDevTheme("acme:/a")).toEqual({ id: 1, name: "A" });
+    expect(getDevTheme("acme:/b")).toEqual({ id: 2, name: "B" });
+  });
+
+  it("returns undefined for an unknown key", () => {
+    expect(getDevTheme("acme:/missing")).toBeUndefined();
+  });
+
+  it("marks the most recently stored theme as lastDevThemeId", () => {
+    setDevTheme("acme:/a", { id: 1, name: "A" });
+    setDevTheme("acme:/b", { id: 2, name: "B" });
+    expect(getLastDevThemeId()).toBe(2);
+  });
+});
+
+describe("clearDevTheme", () => {
+  it("removes only the targeted key", () => {
+    setDevTheme("acme:/a", { id: 1, name: "A" });
+    setDevTheme("acme:/b", { id: 2, name: "B" });
+    clearDevTheme("acme:/a");
+    expect(getDevTheme("acme:/a")).toBeUndefined();
+    expect(getDevTheme("acme:/b")).toEqual({ id: 2, name: "B" });
+  });
+
+  it("is a no-op for an unknown key", () => {
+    setDevTheme("acme:/a", { id: 1, name: "A" });
+    clearDevTheme("acme:/missing");
+    expect(getDevTheme("acme:/a")).toEqual({ id: 1, name: "A" });
+  });
+
+  it("clears lastDevThemeId when it pointed at the removed theme", () => {
+    setDevTheme("acme:/a", { id: 1, name: "A" });
+    expect(getLastDevThemeId()).toBe(1);
+    clearDevTheme("acme:/a");
+    expect(getLastDevThemeId()).toBeUndefined();
+  });
+
+  it("leaves lastDevThemeId when it points at a different theme", () => {
+    setDevTheme("acme:/a", { id: 1, name: "A" });
+    setDevTheme("acme:/b", { id: 2, name: "B" });
+    clearDevTheme("acme:/a"); // most-recent is /b (id 2)
+    expect(getLastDevThemeId()).toBe(2);
+  });
+});
+
+describe("devThemes map stays bounded", () => {
+  it("prunes entries whose theme directory no longer exists on the next write", () => {
+    setDevTheme("acme:/a", { id: 1, name: "A" });
+    setDevTheme("acme:/b", { id: 2, name: "B" });
+
+    // /a is deleted; /b and the new /c still exist.
+    existsSyncMock.mockImplementation((p: string) => p !== "/a");
+    setDevTheme("acme:/c", { id: 3, name: "C" });
+
+    expect(getDevTheme("acme:/a")).toBeUndefined(); // pruned
+    expect(getDevTheme("acme:/b")).toEqual({ id: 2, name: "B" });
+    expect(getDevTheme("acme:/c")).toEqual({ id: 3, name: "C" });
+    expect(
+      Object.keys(pluginState()["devThemes"] as Record<string, unknown>),
+    ).toEqual(["acme:/b", "acme:/c"]);
+  });
+
+  it("keeps the entry being written even if its own directory check fails", () => {
+    existsSyncMock.mockReturnValue(false);
+    setDevTheme("acme:/a", { id: 1, name: "A" });
+    expect(getDevTheme("acme:/a")).toEqual({ id: 1, name: "A" });
+  });
+});
+
+describe("setLastDevThemeId", () => {
+  it("updates the navigate pointer without recording a dev theme", () => {
+    setLastDevThemeId(123);
+    expect(getLastDevThemeId()).toBe(123);
+    expect(getDevTheme("acme:/a")).toBeUndefined();
+  });
+});
+
+describe("legacy migration", () => {
+  it("adopts a legacy global devThemeId for the first requesting key, then clears it", () => {
+    setPluginState({ devThemeId: 99, devThemeName: "Legacy" });
+
+    expect(getDevTheme("acme:/a")).toEqual({ id: 99, name: "Legacy" });
+
+    // Legacy fields are cleared so a second project can't adopt the same theme.
+    const state = pluginState();
+    expect(state["devThemeId"]).toBeUndefined();
+    expect(state["devThemeName"]).toBeUndefined();
+    expect(getDevTheme("acme:/b")).toBeUndefined();
+    expect(getLastDevThemeId()).toBe(99);
+  });
+
+  it("synthesizes a name when the legacy name is absent", () => {
+    setPluginState({ devThemeId: 42 });
+    expect(getDevTheme("acme:/a")).toEqual({ id: 42, name: "Development #42" });
+  });
+
+  it("prefers an explicit per-key entry over the legacy id", () => {
+    setPluginState({
+      devThemeId: 99,
+      devThemes: { "acme:/a": { id: 7, name: "Real" } },
+    });
+    expect(getDevTheme("acme:/a")).toEqual({ id: 7, name: "Real" });
+  });
+});
+
+describe("getLastDevThemeId", () => {
+  it("falls back to the legacy id before any per-project run", () => {
+    setPluginState({ devThemeId: 5 });
+    expect(getLastDevThemeId()).toBe(5);
+  });
+
+  it("returns undefined when nothing is stored", () => {
+    expect(getLastDevThemeId()).toBeUndefined();
+  });
+});

package/src/commands/dev.ts

@@ -1,7 +1,13 @@
 import { Command } from "commander";
 import { requireToken, createApiClient } from "../api.js";
 import { readThemeConfig } from "../theme-config.js";
-import { getPluginState, setPluginState } from "../plugin-state.js";
+import {
+  devThemeKey,
+  getDevTheme,
+  setDevTheme,
+  setLastDevThemeId,
+  clearDevTheme,
+} 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";
@@ -14,24 +20,34 @@ interface CompanyMe {
 
 async function ensureDevTheme(
   api: ReturnType<typeof createApiClient>,
+  projectKey: string,
   identifier?: string,
 ): Promise<ApplicationTheme> {
   if (identifier) {
-    return findTheme(api, identifier);
+    const theme = await findTheme(api, identifier);
+    // Keep `navigate` pointed at whatever the dev server is actually serving.
+    setLastDevThemeId(theme.id);
+    return theme;
   }
 
-  // Reuse stored dev theme if it still exists
-  const { devThemeId } = getPluginState();
-  if (devThemeId) {
+  // Reuse this project's stored dev theme if it still exists and is still a
+  // development theme (a published/promoted theme must not be edited in place).
+  const stored = getDevTheme(projectKey);
+  if (stored) {
     try {
-      const body = await themes.getApplicationTheme(api, devThemeId);
-      if (body.application_theme) {
-        console.log(`Using existing dev theme #${devThemeId}`);
-        return body.application_theme;
+      const body = await themes.getApplicationTheme(api, stored.id);
+      const existing = body.application_theme;
+      if (existing && existing.status === "development") {
+        console.log(`Using existing dev theme #${existing.id}`);
+        // Refresh the stored name and mark it most-recent for `navigate`.
+        setDevTheme(projectKey, { id: existing.id, name: existing.name });
+        return existing;
       }
     } catch {
-      // Theme no longer exists — create a new one
+      // Theme no longer exists — fall through to create a new one.
     }
+    // Stored theme is gone or no longer a dev theme; forget it.
+    clearDevTheme(projectKey);
   }
 
   // Create a new development theme
@@ -47,7 +63,7 @@ async function ensureDevTheme(
     application_theme: { name, status: "development" },
   });
   const theme = body.application_theme;
-  setPluginState({ devThemeId: theme.id, devThemeName: theme.name });
+  setDevTheme(projectKey, { id: theme.id, name: theme.name });
   console.log(`Created dev theme: ${theme.name} (#${theme.id})`);
   return theme;
 }
@@ -121,12 +137,16 @@ export function createDevCommand(): Command {
           }
         }
 
-        // Use theme from .fluid-theme.json if available and no --theme flag
+        // Always iterate on an isolated dev theme: reuse the stored one or
+        // create a fresh `development` theme. `--theme` is the explicit
+        // escape hatch for targeting an existing theme. We deliberately do NOT
+        // fall back to `.fluid-theme.json`'s themeId — that points at whatever
+        // was pulled (often the active/production theme), and the dev server's
+        // `delete: true` sync would overwrite it in place.
+        const projectKey = devThemeKey(company, themeRoot.root);
         const theme = opts.theme
-          ? await ensureDevTheme(api, opts.theme)
-          : config
-            ? await ensureDevTheme(api, String(config.themeId))
-            : await ensureDevTheme(api);
+          ? await ensureDevTheme(api, projectKey, opts.theme)
+          : await ensureDevTheme(api, projectKey);
         const editorUrl = `https://admin.fluid.app/themes/${theme.id}/editor`;
 
         let stop: (() => void) | undefined;

package/src/commands/lint.ts

@@ -0,0 +1,175 @@
+import chalk from "chalk";
+import { Command } from "commander";
+import {
+  findMissingSectionReferences,
+  validateSchemaText,
+  type BlocksSchemaType,
+  type Diagnostic,
+  type TemplateInput,
+} from "@fluid-app/theme-schema";
+import { ThemeRoot } from "../theme/root.js";
+import { findWorkspace, resolveThemeRootFromCwd } from "../workspace.js";
+
+interface FileDiagnostics {
+  path: string;
+  diagnostics: Diagnostic[];
+}
+
+// A theme section is defined by a liquid file under `templates/sections/`.
+// Returns the section name a `{% section %}` tag would reference, or null if
+// the file is not a section definition. Handles both the flat layout
+// (`templates/sections/hero.liquid`) and the nested one
+// (`templates/sections/hero/index.liquid`).
+function sectionNameOf(relativePath: string): string | null {
+  const parts = relativePath.split(/[/\\]/);
+  if (
+    parts[0] === "templates" &&
+    parts[1] === "sections" &&
+    parts.length >= 3
+  ) {
+    return parts[2]!.replace(/\.liquid$/, "");
+  }
+  return null;
+}
+
+export function createLintCommand(): Command {
+  return new Command("lint")
+    .description("Validate theme files locally (read-only — no upload)")
+    .option("--root <path>", "Theme root directory", ".")
+    .option("--json", "Output results as compact JSON")
+    .action(async (opts: { root: string; json?: boolean }) => {
+      // Resolve the theme root the same way push/dev do: when left at the
+      // default, prefer the workspace's theme root if we're inside one.
+      let rootPath = opts.root;
+      if (rootPath === ".") {
+        const workspace = findWorkspace();
+        if (workspace) {
+          rootPath = resolveThemeRootFromCwd(workspace) ?? rootPath;
+        }
+      }
+
+      const themeRoot = new ThemeRoot(rootPath);
+      if (!themeRoot.isValid()) {
+        const message = `'${rootPath}' does not look like a theme directory.`;
+        if (opts.json) {
+          console.log(JSON.stringify({ ok: false, error: message }));
+        } else {
+          console.error(message);
+        }
+        process.exit(1);
+      }
+
+      const files = themeRoot.files();
+      // Read each liquid file once and reuse the content for both passes
+      // (validateSchemaText and the section scan) to avoid a double disk read.
+      const liquidFiles = files
+        .filter((f) => f.isLiquid)
+        .map((f) => ({ file: f, content: f.read() }));
+
+      const byFile = new Map<string, Diagnostic[]>();
+      const record = (path: string, diagnostic: Diagnostic): void => {
+        const existing = byFile.get(path);
+        if (existing) existing.push(diagnostic);
+        else byFile.set(path, [diagnostic]);
+      };
+
+      // ── Schema pass — the same {% schema %} validation `fluid theme push`
+      // runs. blocksSchemaType mirrors ThemeFile.validateSchema: page/layout
+      // templates use object blocks, sections use array blocks.
+      for (const { file, content } of liquidFiles) {
+        const blocksSchemaType: BlocksSchemaType = file.isTemplate
+          ? "object"
+          : "array";
+        for (const diagnostic of validateSchemaText(content, {
+          blocksSchemaType,
+        })) {
+          record(file.relativePath, diagnostic);
+        }
+      }
+
+      // ── Section pass — flag `{% section 'x' %}` references to a section
+      // that has no definition on disk. Section definitions and assets are
+      // not themselves referrers, so they are excluded from the scan.
+      const existingSectionNames = new Set<string>();
+      for (const { file } of liquidFiles) {
+        const name = sectionNameOf(file.relativePath);
+        if (name) existingSectionNames.add(name);
+      }
+      const referrers: TemplateInput[] = liquidFiles
+        .filter(({ file }) => sectionNameOf(file.relativePath) === null)
+        .map(({ file, content }) => ({ path: file.relativePath, content }));
+      for (const missing of findMissingSectionReferences(
+        referrers,
+        existingSectionNames,
+      )) {
+        record(missing.templatePath, missing.diagnostic);
+      }
+
+      const results: FileDiagnostics[] = [...byFile.entries()]
+        .map(([path, diagnostics]) => ({ path, diagnostics }))
+        .sort((a, b) => a.path.localeCompare(b.path));
+
+      let errors = 0;
+      let warnings = 0;
+      for (const { diagnostics } of results) {
+        for (const d of diagnostics) {
+          if (d.severity === "error") errors++;
+          else warnings++;
+        }
+      }
+
+      if (opts.json) {
+        console.log(
+          JSON.stringify({
+            ok: errors === 0,
+            errors,
+            warnings,
+            filesChecked: liquidFiles.length,
+            files: results,
+          }),
+        );
+      } else {
+        printText(results, errors, warnings, liquidFiles.length);
+      }
+
+      process.exit(errors > 0 ? 1 : 0);
+    });
+}
+
+function plural(count: number, noun: string): string {
+  return `${count} ${noun}${count === 1 ? "" : "s"}`;
+}
+
+function printText(
+  results: FileDiagnostics[],
+  errors: number,
+  warnings: number,
+  filesChecked: number,
+): void {
+  for (const { path, diagnostics } of results) {
+    console.log(chalk.bold(path));
+    for (const d of diagnostics) {
+      const label =
+        d.severity === "error"
+          ? chalk.red("error".padEnd(7))
+          : chalk.yellow("warning".padEnd(7));
+      // Only the first line — diagnostics like the invalid-setting-type list
+      // carry a long multi-line body that the `--json` output preserves.
+      const message = d.message.split("\n")[0];
+      console.log(`  ${label} ${message}`);
+    }
+  }
+
+  const suffix = `(${plural(filesChecked, "file")} checked)`;
+  if (errors > 0) {
+    console.log(
+      `\n${chalk.red(`✖ ${plural(errors, "error")}, ${plural(warnings, "warning")}`)} ${suffix}`,
+    );
+  } else if (warnings > 0) {
+    console.log(
+      `\n${chalk.yellow(`⚠ ${plural(warnings, "warning")}`)} ${suffix}`,
+    );
+  } else {
+    console.log(`${chalk.green("✓ No problems found")} ${suffix}`);
+  }
+}

package/src/commands/navigate.ts

@@ -1,7 +1,7 @@
 import { Command } from "commander";
 import prompts from "prompts";
 import { requireToken, createApiClient } from "../api.js";
-import { getPluginState } from "../plugin-state.js";
+import { getLastDevThemeId } from "../plugin-state.js";
 import { themes } from "@fluid-app/themes-api-client";
 
 function localSuggest(
@@ -148,9 +148,7 @@ export function createNavigateCommand(): Command {
     .action(async (opts: { host: string; port: string; theme?: string }) => {
       requireToken();
 
-      const themeId = opts.theme
-        ? Number(opts.theme)
-        : getPluginState().devThemeId;
+      const themeId = opts.theme ? Number(opts.theme) : getLastDevThemeId();
 
       if (!themeId) {
         console.error(

package/src/commands/theme.ts

@@ -3,17 +3,19 @@ import type { PluginContext } from "@fluid-app/fluid-cli";
 import { createDevCommand } from "./dev.js";
 import { createPushCommand } from "./push.js";
 import { createPullCommand } from "./pull.js";
+import { createLintCommand } from "./lint.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",
+    "Theme developer workflow — dev server, push, pull, lint, init",
   );
 
   cmd.addCommand(createDevCommand());
   cmd.addCommand(createPushCommand());
   cmd.addCommand(createPullCommand());
+  cmd.addCommand(createLintCommand());
   cmd.addCommand(createInitCommand());
   cmd.addCommand(createNavigateCommand());