@dennisrongo/skills 0.1.2 → 0.1.3

package/skills/tauri-2-app/references/templates/use-tauri-command.md

@@ -0,0 +1,194 @@
+# `src/hooks/useTauriCommand.ts`
+
+Generic hook that wraps `invoke()` with `data` / `isLoading` / `error` / `execute`. Every per-domain hook (`useSettings`, `useRecording`, …) composes this. **Components never call `invoke()` directly.**
+
+```ts
+import { invoke } from "@tauri-apps/api/core";
+import { useCallback, useEffect, useState } from "react";
+import { isTauriReady } from "../tauriReady";
+
+export interface UseCommandOptions<T> {
+  command: string;
+  args?: Record<string, unknown>;
+  onSuccess?: (data: T) => void;
+  onError?: (error: string) => void;
+}
+
+export interface CommandState<T> {
+  data: T | null;
+  isLoading: boolean;
+  error: string | null;
+  execute: (args?: Record<string, unknown>) => Promise<T>;
+}
+
+export function useTauriCommand<T = unknown>(
+  options: UseCommandOptions<T>,
+): CommandState<T> {
+  const { command, args: defaultArgs, onSuccess, onError } = options;
+  const [data, setData] = useState<T | null>(null);
+  const [isLoading, setIsLoading] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  const execute = useCallback(
+    async (args?: Record<string, unknown>) => {
+      setIsLoading(true);
+      setError(null);
+      try {
+        const result = await invoke<T>(command, args || defaultArgs);
+        setData(result);
+        onSuccess?.(result);
+        return result;
+      } catch (err) {
+        const errorMsg = String(err);
+        setError(errorMsg);
+        onError?.(errorMsg);
+        throw err;
+      } finally {
+        setIsLoading(false);
+      }
+    },
+    [command, defaultArgs, onSuccess, onError],
+  );
+
+  return { data, isLoading, error, execute };
+}
+
+export interface UseLoadOptions<T> extends UseCommandOptions<T> {
+  loadOnMount?: boolean;
+  defaultValue?: T;
+}
+
+export interface LoadState<T> {
+  data: T;
+  isLoading: boolean;
+  error: string | null;
+  execute: (args?: Record<string, unknown>) => Promise<T>;
+  reload: () => Promise<T>;
+}
+
+export function useTauriLoad<T = unknown>(
+  options: UseLoadOptions<T>,
+): LoadState<T> {
+  const { loadOnMount = true, defaultValue, ...commandOptions } = options;
+  const { data, isLoading, error, execute } = useTauriCommand<T>(commandOptions);
+
+  const reload = useCallback(() => execute(), [execute]);
+
+  useEffect(() => {
+    if (!loadOnMount) return;
+    if (!isTauriReady()) return;
+    execute().catch(() => {
+      /* error already captured */
+    });
+  }, [loadOnMount, execute]);
+
+  return {
+    data: (data ?? defaultValue) as T,
+    isLoading,
+    error,
+    execute,
+    reload,
+  };
+}
+
+export interface UseMutationOptions<T> extends UseCommandOptions<T> {
+  onMutate?: () => void | Promise<void>;
+}
+
+export interface MutationState<T> {
+  isMutating: boolean;
+  error: string | null;
+  execute: (args?: Record<string, unknown>) => Promise<T>;
+  resetError: () => void;
+}
+
+export function useTauriMutation<T = unknown>(
+  options: UseMutationOptions<T>,
+): MutationState<T> {
+  const { command, args: defaultArgs, onSuccess, onError, onMutate } = options;
+  const [isMutating, setIsMutating] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  const execute = useCallback(
+    async (args?: Record<string, unknown>) => {
+      if (!isTauriReady()) {
+        return Promise.reject(new Error("Tauri not ready"));
+      }
+      setIsMutating(true);
+      setError(null);
+      try {
+        await onMutate?.();
+        const result = await invoke<T>(command, args || defaultArgs);
+        onSuccess?.(result);
+        return result;
+      } catch (err) {
+        const errorMsg = String(err);
+        setError(errorMsg);
+        onError?.(errorMsg);
+        throw err;
+      } finally {
+        setIsMutating(false);
+      }
+    },
+    [command, defaultArgs, onMutate, onSuccess, onError],
+  );
+
+  const resetError = useCallback(() => setError(null), []);
+
+  return { isMutating, error, execute, resetError };
+}
+```
+
+## Per-domain hook example
+
+```ts
+// src/hooks/useSettings.ts
+import type { Settings } from "../types";
+import { useTauriLoad, useTauriMutation } from "./useTauriCommand";
+
+const DEFAULT_SETTINGS: Settings = { /* sensible defaults */ };
+
+export function useSettings() {
+  return useTauriLoad<Settings>({
+    command: "get_settings",
+    defaultValue: DEFAULT_SETTINGS,
+  });
+}
+
+export function useSaveSettings() {
+  return useTauriMutation<void>({ command: "save_settings_command" });
+}
+```
+
+## Component usage
+
+```tsx
+function SettingsPage() {
+  const { data: settings, isLoading, error, reload } = useSettings();
+  const { execute: saveSettings, isMutating } = useSaveSettings();
+
+  if (isLoading) return <Spinner />;
+  if (error) return <ErrorBanner error={error} onRetry={reload} />;
+
+  return (
+    <Form
+      initialValues={settings}
+      onSubmit={async (values) => {
+        await saveSettings({ settings: values });
+        await reload();
+      }}
+    />
+  );
+}
+```
+
+## Why this shape
+
+- **One place to add cross-cutting concerns** — retry, exponential backoff, telemetry, error toasts, request-id headers — all change one file.
+- **Type safety** — `T` flows through `invoke<T>`. The hook user gets `data: T | null`, not `data: any`.
+- **Three flavors** —
+  - `useTauriCommand`: imperative; component triggers it.
+  - `useTauriLoad`: auto-fires on mount; for "get me this data".
+  - `useTauriMutation`: imperative; explicitly skips auto-fire; for write paths.
+- **`isTauriReady()` guard** — In Tauri 2 the IPC bridge is ready before React mounts, but the guard makes the code safe to preview via plain `vite dev` for static UI iteration.
+- **No `invoke()` in components** — Refactoring command names, adding logging, fixing race conditions all happen in one file. Without this discipline, every component reinvents loading/error state slightly differently.

package/skills/tauri-2-app/references/templates/vite-and-tsconfig.md

@@ -0,0 +1,189 @@
+# Frontend configs: `vite.config.ts`, `tsconfig.json`, `package.json`, `index.html`
+
+## `vite.config.ts`
+
+```ts
+import { defineConfig } from "vite";
+import react from "@vitejs/plugin-react";
+import { readFileSync } from "fs";
+
+// Read tauri.conf.json so the frontend has a single source of truth for version.
+const tauriConfig = JSON.parse(
+  readFileSync("./src-tauri/tauri.conf.json", "utf-8"),
+);
+
+// @ts-expect-error process is a Node global
+const host = process.env.TAURI_DEV_HOST;
+
+export default defineConfig({
+  // Relative base so bundled HTML loads from tauri://localhost
+  base: "./",
+
+  plugins: [react()],
+
+  // Don't hide Rust compiler errors
+  clearScreen: false,
+
+  server: {
+    port: 5173,
+    strictPort: true,                  // Tauri's devUrl pins 5173 — fail loudly if taken
+    host: host || false,
+    hmr: host
+      ? { protocol: "ws", host, port: 1421 }
+      : undefined,
+    watch: {
+      // Cargo handles src-tauri/ rebuilds; Vite ignoring it prevents HMR loops
+      ignored: ["**/src-tauri/**"],
+    },
+  },
+
+  esbuild: { jsx: "automatic" },
+
+  define: {
+    __APP_VERSION__: JSON.stringify(tauriConfig.version),
+  },
+});
+```
+
+Vanilla TypeScript (no React)? Drop the `react()` plugin and the `esbuild.jsx` line.
+
+## `tsconfig.json`
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "useDefineForClassFields": true,
+    "module": "ESNext",
+    "lib": ["ES2020", "DOM", "DOM.Iterable"],
+    "skipLibCheck": true,
+    "jsx": "react-jsx",
+
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "noEmit": true,
+
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noFallthroughCasesInSwitch": true
+  },
+  "include": ["src"],
+  "references": [{ "path": "./tsconfig.node.json" }]
+}
+```
+
+`tsconfig.node.json` is a tiny companion for the `vite.config.ts` file itself:
+
+```json
+{
+  "compilerOptions": {
+    "composite": true,
+    "skipLibCheck": true,
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "allowSyntheticDefaultImports": true
+  },
+  "include": ["vite.config.ts"]
+}
+```
+
+## `package.json`
+
+```json
+{
+  "name": "{{app-name}}",
+  "private": true,
+  "version": "0.1.0",
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc && vite build",
+    "preview": "vite preview",
+    "tauri": "tauri",
+    "tauri:dev": "tauri dev",
+    "tauri:build": "tauri build",
+    "clean": "rimraf node_modules/.vite dist",
+    "test": "cd src-tauri && cargo test"
+  },
+  "dependencies": {
+    "@tauri-apps/api": "<latest 2.x>",
+    "@tauri-apps/plugin-dialog": "<latest 2.x>",
+    "@tauri-apps/plugin-fs": "<latest 2.x>",
+    "@tauri-apps/plugin-notification": "<latest 2.x>",
+    "@tauri-apps/plugin-opener": "<latest 2.x>",
+    "react": "<latest>",
+    "react-dom": "<latest>"
+  },
+  "devDependencies": {
+    "@tauri-apps/cli": "<latest 2.x>",
+    "@types/react": "<latest>",
+    "@types/react-dom": "<latest>",
+    "@vitejs/plugin-react": "<latest>",
+    "rimraf": "<latest>",
+    "typescript": "<latest>",
+    "vite": "<latest>"
+  }
+}
+```
+
+Resolve `<latest>` markers at scaffold time — never paste a literal version into a generated file.
+
+## `index.html`
+
+```html
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <title>{{ProductName}}</title>
+
+  <!-- Optional: anti-flash theme script. Runs BEFORE React mounts so the
+       initial paint matches the user's preference. -->
+  <script>
+    (function() {
+      const stored = localStorage.getItem("{{app-name}}-theme");
+      const prefersDark = window.matchMedia("(prefers-color-scheme: dark)").matches;
+      const isDark = stored === "dark" || ((!stored || stored === "system") && prefersDark);
+      if (isDark) document.documentElement.classList.add("dark");
+    })();
+  </script>
+
+  <style>
+    #app { opacity: 0; transition: opacity 0.15s ease-in; }
+    #app.loaded { opacity: 1; }
+  </style>
+</head>
+<body>
+  <div id="app"></div>
+  <script type="module" src="/src/main.tsx"></script>
+</body>
+</html>
+```
+
+```tsx
+// src/main.tsx
+import { createRoot } from "react-dom/client";
+import App from "./App";
+import "./styles.css";
+
+const rootElement = document.getElementById("app");
+if (rootElement) {
+  createRoot(rootElement).render(<App />);
+  requestAnimationFrame(() => rootElement.classList.add("loaded"));
+}
+```
+
+## Why these choices
+
+- **`base: './'`** — Tauri serves the bundled frontend from `tauri://localhost/`. Absolute paths (`base: '/'`) break asset URLs like `/assets/index.css` because they resolve against the protocol root.
+- **`strictPort: true`** — Tauri's `devUrl` is `http://localhost:5173`. If Vite silently falls back to 5174, Tauri opens a blank window with no error.
+- **`server.watch.ignored: ['**/src-tauri/**']`** — Cargo writes to `src-tauri/target/` constantly during dev. Without this, Vite's HMR triggers on every Cargo file write and reloads the frontend in a tight loop.
+- **`clearScreen: false`** — Vite's default behavior clears the terminal on startup, hiding Rust compile errors. Tauri devs need both visible.
+- **`isolatedModules: true`** — Required for Vite (which transpiles file-by-file, not whole-program).
+- **`strict: true` + `noUnusedLocals` + `noUnusedParameters`** — Catches the kind of "I forgot to wire this up" mistakes that slip past code review.
+- **Anti-flash script** — Without it, a dark-mode user sees a white flash before React's theme provider mounts. The script reads `localStorage` synchronously and applies the `dark` class before first paint.
+- **Single `createRoot` call** — React 18+ doesn't tolerate multiple roots on the same node. Use one entry point.