@mostrom/app-shell 0.1.0

package/.claude/ralph-loop.local.md

@@ -0,0 +1,9 @@
+---
+active: true
+iteration: 1
+max_iterations: 0
+completion_promise: null
+started_at: "2026-02-13T12:51:42Z"
+---
+
+Without diverging from the drawer requirements in @docs/prompts/todo/drawer-fields.md ensure the drawer layout wise and style wise mimics this exact image docs/prompts/todo/Screenshot 2026-02-12 at 18.19.47.png and use playwright to take screenshots and do a comparison until the layouts match 100%

package/README.md

@@ -0,0 +1,172 @@
+# App Shell
+
+Shared Cloudscape-based layout shell used by all platform services. Mirrors the AWS Console layout pattern.
+
+## Publishing to npm
+
+Use the publish helper to publish both packages in order:
+
+1. `@mostrom/service-catalog`
+2. `@mostrom/app-shell`
+
+From `platform/shared/packages/app-shell`:
+
+Default scope is `@mostrom` (override with `--scope` if needed).
+
+```bash
+# Dry run
+npm run publish:npm:dry-run -- --version 0.1.0
+# or: sh scripts/publish-npm.sh --version 0.1.0 --dry-run
+
+# Publish to latest
+npm run publish:npm -- --version 0.1.0
+# or: sh scripts/publish-npm.sh --version 0.1.0
+
+# Publish to custom tag
+npm run publish:npm -- --version 0.1.0 --tag next
+# or: sh scripts/publish-npm.sh --version 0.1.0 --tag next
+```
+
+The script reads `NODE_AUTH_TOKEN` from environment variables, and also checks `app-shell/.env` for that key.
+
+## Quick Start
+
+### Initial Setup (New Apps)
+
+Run the init script to configure a new app to use app-shell:
+
+```bash
+# From your app's frontend directory, run the init script directly
+node ../../../shared/packages/app-shell/bin/init.js
+
+# Force overwrite existing files
+node ../../../shared/packages/app-shell/bin/init.js --force
+
+# Alternative: If app-shell is linked in node_modules, use the bin
+./node_modules/.bin/app-shell-init
+```
+
+> **Note:** In this monorepo, prefer running the local init script directly. If you publish to npm, consumers can also use the installed bin (`app-shell-init`).
+
+The init script creates/updates:
+
+- `app/tailwind.css` - Imports app-shell styles
+- `tailwind.config.ts` - Configured to scan app-shell components
+- `components.json` - shadcn/ui configuration
+- `app/lib/utils.ts` - Utility functions (cn, getBasePathHref)
+
+### When to Run Init
+
+| Scenario                                    | Run Init?                                            |
+| ------------------------------------------- | ---------------------------------------------------- |
+| Setting up a new app                        | Yes                                                  |
+| CSS changes in app-shell                    | No - changes are picked up automatically             |
+| Adding new shadcn components                | No - use `npx shadcn@latest add <component>`         |
+| Tailwind not scanning app-shell classes     | Yes, with `--force` to regenerate tailwind.config.ts |
+| Upgrading app-shell with new required files | Yes, with `--force`                                  |
+
+### Troubleshooting
+
+**Styles not applying from app-shell:**
+
+1. Ensure `tailwind.config.ts` includes the app-shell path in `content`:
+   ```ts
+   content: [
+     "./app/**/*.{ts,tsx,js,jsx}",
+     "../../../shared/packages/app-shell/src/**/*.{ts,tsx}",
+   ],
+   ```
+2. Run `node ../../../shared/packages/app-shell/bin/init.js --force` to regenerate config files
+
+**Conflicting CSS (wrong colors, broken layout):**
+
+- Check for `app/app.css` or similar files with `html`, `body`, or `:root` blocks that override app-shell variables
+- Remove hardcoded background-color/color declarations from global CSS
+
+## Layout Structure
+
+```
++------------------------------------------------------------------+
+|                        GLOBAL HEADER                             |
+| [Logo] [Search Bar........................] [Apps] [Gear] [User] |
++------------------------------------------------------------------+
+|                        SERVICE HEADER                            |
+| [Menu] [Service Name] [Breadcrumbs................] [Right Panel]|
++--------+-----------------------------------------+---------------+
+|        |                                         |               |
+|  LEFT  |              MAIN CONTENT               |    RIGHT      |
+| PANEL  |                                         |    PANEL      |
+|        |              (children)                 |               |
+|        |                                         |               |
++--------+-----------------------------------------+---------------+
+```
+
+## Component Map (Cloudscape)
+
+### Global Header (top-most, full width)
+
+Cloudscape `TopNavigation`.
+
+| Position | Element  | Cloudscape Component                                   | Behavior               |
+| -------- | -------- | ------------------------------------------------------ | ---------------------- |
+| Left     | Logo     | `TopNavigation` `identity`                             | Navigate to home       |
+| Center   | Search   | `TopNavigation` `search` with `Input` or `Autosuggest` | Global search          |
+| Right    | Apps     | `TopNavigation` utility with `Icon` `grid-view`        | Opens dropdown (empty) |
+| Right    | Settings | `TopNavigation` utility with `Icon` `settings`         | Opens dropdown (empty) |
+| Right    | User     | `TopNavigation` utility with `Icon` `user-profile`     | User menu              |
+
+### Service Header (below Global Header, full width)
+
+Cloudscape `AppLayoutToolbar`.
+
+| Position | Element      | Cloudscape Component                             | Behavior                 |
+| -------- | ------------ | ------------------------------------------------ | ------------------------ |
+| Left     | Menu         | `Button` (icon-only) with `Icon` `menu`          | Toggles Left Panel       |
+| Left     | Service Name | Text                                             | Current service name     |
+| Center   | Breadcrumbs  | `BreadcrumbGroup`                                | Single breadcrumb source |
+| Right    | Panel Toggle | `Button` (icon-only) with `Icon` `view-vertical` | Toggles Right Panel      |
+
+### Left Panel
+
+- Slot: `navigation` in `AppLayoutToolbar`
+- Component: `SideNavigation`
+- Header: `Header` with an icon-only `Button` (`Icon` `angle-left`) to collapse
+- Content: Empty placeholder list (service provides content)
+
+### Right Panel
+
+- Slot: `tools` in `AppLayoutToolbar`
+- Content: Empty container (no `HelpPanel`)
+
+### Notifications
+
+- Slot: `notifications` in `AppLayoutToolbar`
+- Component: `Flashbar`
+
+### Main Content Area
+
+- Renders `children` passed to `AppShell`
+
+## Required Cloudscape Packages
+
+- `@cloudscape-design/components`
+- `@cloudscape-design/global-styles` (import once per app for base styles/fonts)
+
+## Service Catalog Dependency
+
+The App Shell builds the **All services** menu and global search suggestions from
+`@mostrom/service-catalog`. Until we move to a monorepo workspace setup, each
+app should explicitly depend on this package to avoid module resolution issues.
+
+Add this to your app's `package.json` dependencies:
+
+```json
+{
+  "@mostrom/service-catalog": "file:../../../shared/packages/service-catalog"
+}
+```
+
+## Notes
+
+- Do not duplicate breadcrumbs outside the `BreadcrumbGroup`.
+- Use Cloudscape components as-is. No custom styling overrides required for the initial scaffold.

package/bin/init.js

@@ -0,0 +1,269 @@
+#!/usr/bin/env node
+
+/**
+ * @platform/app-shell init
+ *
+ * Sets up a new app to use the app-shell package correctly.
+ * Similar to `shadcn init` but configured for our monorepo structure.
+ *
+ * Usage (from your app's frontend directory):
+ *   node ../../../shared/packages/app-shell/bin/init.js
+ *   node ../../../shared/packages/app-shell/bin/init.js --force
+ *
+ * Note: npx/bunx won't work - this is a private monorepo package, not published to npm.
+ *
+ * What it does:
+ *   1. Creates minimal app/tailwind.css (delegates to app-shell)
+ *   2. Creates components.json (shadcn/ui configuration)
+ *   3. Creates app/lib/utils.ts (cn utility + getBasePathHref)
+ *   4. Creates tailwind.config.ts
+ *   5. Validates vite.config.ts uses getSharedViteConfig()
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const cwd = process.cwd();
+
+// ANSI colors
+const green = (s) => `\x1b[32m${s}\x1b[0m`;
+const yellow = (s) => `\x1b[33m${s}\x1b[0m`;
+const red = (s) => `\x1b[31m${s}\x1b[0m`;
+const cyan = (s) => `\x1b[36m${s}\x1b[0m`;
+const dim = (s) => `\x1b[2m${s}\x1b[0m`;
+
+console.log();
+console.log(cyan("@platform/app-shell init"));
+console.log(dim("Setting up app-shell configuration..."));
+console.log();
+
+// Templates
+const TAILWIND_CSS = `@import "https://fonts.googleapis.com/css2?family=Hanken+Grotesk:wght@300;400;500;600;700&display=swap";
+@import "tw-animate-css";
+@import "tailwindcss";
+@import "@platform/app-shell/styles.css";
+@config "../tailwind.config.ts";
+`;
+
+// Compute relative path to app-shell from current directory
+function getAppShellRelativePath() {
+  // The init script is at app-shell/bin/init.js
+  // So app-shell src is at ../src relative to this script
+  const appShellSrc = path.resolve(__dirname, "../src");
+  const relativePath = path.relative(cwd, appShellSrc);
+  return relativePath.replace(/\\/g, "/"); // Normalize for all platforms
+}
+
+const appShellPath = getAppShellRelativePath();
+
+const TAILWIND_CONFIG = `export default {
+  darkMode: "class",
+  content: [
+    "./app/**/*.{ts,tsx,js,jsx}",
+    // Include app-shell components for Tailwind to scan
+    "${appShellPath}/**/*.{ts,tsx}",
+  ],
+};
+`;
+
+const COMPONENTS_JSON = `{
+  "$schema": "https://ui.shadcn.com/schema.json",
+  "style": "new-york",
+  "rsc": false,
+  "tsx": true,
+  "tailwind": {
+    "config": "tailwind.config.ts",
+    "css": "app/tailwind.css",
+    "baseColor": "neutral",
+    "cssVariables": true,
+    "prefix": ""
+  },
+  "iconLibrary": "lucide",
+  "rtl": false,
+  "aliases": {
+    "components": "~/components",
+    "utils": "~/lib/utils",
+    "ui": "~/components/ui",
+    "lib": "~/lib",
+    "hooks": "~/hooks"
+  },
+  "registries": {}
+}
+`;
+
+const UTILS_TS = `import { clsx, type ClassValue } from "clsx"
+import { twMerge } from "tailwind-merge"
+
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs))
+}
+
+/**
+ * Returns a path with the VITE_BASE_PATH prefix for use in href attributes.
+ * React Router's navigate() handles basename automatically, but href attributes
+ * on Cloudscape Link components (or native <a> tags) do not.
+ *
+ * @param path - The relative path (e.g., "/clients/123" or "/scheduling/abc")
+ * @returns The path prefixed with the base path (e.g., "/client-management/clients/123")
+ */
+export function getBasePathHref(path: string): string {
+  const configuredBasePath = import.meta.env.VITE_BASE_PATH;
+  if (typeof configuredBasePath !== "string") {
+    throw new Error("VITE_BASE_PATH must be defined");
+  }
+  const basePath = configuredBasePath.replace(/\\/$/, "");
+  const normalizedPath = path.startsWith("/") ? path : \`/\${path}\`;
+  if (basePath === "" || basePath === "/") {
+    return normalizedPath;
+  }
+  return \`\${basePath}\${normalizedPath}\`;
+}
+`;
+
+// Helper functions
+function ensureDir(dir) {
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+}
+
+function writeFile(filePath, content, overwrite = false) {
+  const relativePath = path.relative(cwd, filePath);
+
+  if (fs.existsSync(filePath) && !overwrite) {
+    // Check if content is different
+    const existing = fs.readFileSync(filePath, "utf-8");
+    if (existing === content) {
+      console.log(dim(`  ${relativePath} (unchanged)`));
+      return false;
+    }
+    console.log(yellow(`  ${relativePath} (exists, skipping - use --force to overwrite)`));
+    return false;
+  }
+
+  fs.writeFileSync(filePath, content);
+  console.log(green(`  ${relativePath}`));
+  return true;
+}
+
+function checkViteConfig() {
+  const viteConfigPath = path.join(cwd, "vite.config.ts");
+  if (!fs.existsSync(viteConfigPath)) {
+    console.log(yellow("  vite.config.ts not found - skipping validation"));
+    return;
+  }
+
+  const content = fs.readFileSync(viteConfigPath, "utf-8");
+
+  if (!content.includes("getSharedViteConfig")) {
+    console.log();
+    console.log(yellow("Warning: vite.config.ts does not use getSharedViteConfig()"));
+    console.log(dim("Consider updating it to use the shared config:"));
+    console.log();
+    console.log(dim(`  import { getSharedViteConfig } from "@platform/app-shell/vite";`));
+    console.log(dim(`  import { mergeConfig } from "vite";`));
+    console.log();
+    console.log(dim(`  export default defineConfig(({ mode }) => {`));
+    console.log(dim(`    const shared = getSharedViteConfig(__dirname);`));
+    console.log(dim(`    return mergeConfig(shared, { /* app-specific config */ });`));
+    console.log(dim(`  });`));
+  } else {
+    console.log(green("  vite.config.ts uses getSharedViteConfig()"));
+  }
+}
+
+function checkConflictingCss() {
+  // Check for app.css or other CSS files that might conflict with app-shell
+  const conflictingFiles = ["app/app.css", "app/global.css", "app/globals.css"];
+  const found = [];
+
+  for (const file of conflictingFiles) {
+    const filePath = path.join(cwd, file);
+    if (fs.existsSync(filePath)) {
+      const content = fs.readFileSync(filePath, "utf-8");
+      // Check if it has html/body/root blocks with hardcoded colors
+      // These patterns specifically target global style overrides
+      const hasGlobalColorOverride =
+        /(?:html|body|\:root)\s*\{[^}]*(?:background-color|background|color)\s*:/i.test(content);
+
+      if (hasGlobalColorOverride) {
+        found.push(file);
+      }
+    }
+  }
+
+  if (found.length > 0) {
+    console.log();
+    console.log(yellow("Warning: Found CSS files that may conflict with app-shell:"));
+    for (const file of found) {
+      console.log(red(`  ${file}`));
+    }
+    console.log(dim("These files have html/body/:root blocks with hardcoded colors."));
+    console.log(dim("Remove these blocks and rely on app-shell/styles.css for theming."));
+  } else {
+    console.log(green("  No conflicting CSS files found"));
+  }
+}
+
+// Check for --force flag
+const force = process.argv.includes("--force") || process.argv.includes("-f");
+
+// Preflight checks
+console.log("Preflight checks:");
+
+// Check if we're in a frontend directory
+const packageJsonPath = path.join(cwd, "package.json");
+if (!fs.existsSync(packageJsonPath)) {
+  console.log(red("  package.json not found"));
+  console.log(dim("  Run this command from your frontend directory"));
+  process.exit(1);
+}
+console.log(green("  Found package.json"));
+
+// Check for app directory (React Router convention)
+const appDir = path.join(cwd, "app");
+if (!fs.existsSync(appDir)) {
+  console.log(yellow("  app/ directory not found - will create it"));
+}
+console.log(green("  Found app/ directory"));
+
+// Check for @platform/app-shell dependency
+const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, "utf-8"));
+const hasAppShell = packageJson.dependencies?.["@platform/app-shell"] ||
+                    packageJson.devDependencies?.["@platform/app-shell"];
+if (!hasAppShell) {
+  console.log(yellow("  @platform/app-shell not in dependencies"));
+  console.log(dim("  Add it: \"@platform/app-shell\": \"file:../../../shared/packages/app-shell\""));
+} else {
+  console.log(green("  Found @platform/app-shell dependency"));
+}
+
+console.log();
+console.log("Creating files:");
+
+// Ensure directories exist
+ensureDir(path.join(cwd, "app"));
+ensureDir(path.join(cwd, "app/lib"));
+
+// Create files
+writeFile(path.join(cwd, "app/tailwind.css"), TAILWIND_CSS, force);
+writeFile(path.join(cwd, "tailwind.config.ts"), TAILWIND_CONFIG, force);
+writeFile(path.join(cwd, "components.json"), COMPONENTS_JSON, force);
+writeFile(path.join(cwd, "app/lib/utils.ts"), UTILS_TS, force);
+
+console.log();
+console.log("Validating configuration:");
+checkViteConfig();
+checkConflictingCss();
+
+console.log();
+console.log(green("Done!"));
+console.log();
+console.log("Next steps:");
+console.log(dim("  1. Run 'bun install' to install dependencies"));
+console.log(dim("  2. Import '@platform/app-shell' in your layout component"));
+console.log(dim("  3. Run 'bun run dev' to start the dev server"));
+console.log();