@atlashub/smartstack-cli 1.29.0 → 1.31.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atlashub/smartstack-cli",
-  "version": "1.29.0",
+  "version": "1.31.0",
   "description": "SmartStack Claude Code automation toolkit - GitFlow, APEX, EF Core migrations, prompts and more",
   "author": {
     "name": "SmartStack",

package/templates/project/api.ts.template

@@ -0,0 +1,31 @@
+import axios from 'axios';
+
+const api = axios.create({
+  baseURL: '/api',
+  headers: {
+    'Content-Type': 'application/json',
+  },
+});
+
+// Request interceptor for auth token
+api.interceptors.request.use((config) => {
+  const token = localStorage.getItem('token');
+  if (token) {
+    config.headers.Authorization = `Bearer ${token}`;
+  }
+  return config;
+});
+
+// Response interceptor for error handling
+api.interceptors.response.use(
+  (response) => response,
+  (error) => {
+    if (error.response?.status === 401) {
+      localStorage.removeItem('token');
+      window.location.href = '/login';
+    }
+    return Promise.reject(error);
+  }
+);
+
+export default api;

package/templates/skills/review-code/references/clean-code-principles.md

@@ -28,6 +28,42 @@ Parameter limits:
 - Maximum 3 parameters
 - Avoid flag arguments (split into separate methods)
 - Use objects for related parameters
+
+**Parameter Object Pattern (for 4+ parameters):**
+
+```csharp
+// ❌ BAD - Too many parameters (S107)
+public void CreateUser(
+    string name,
+    string email,
+    string phone,
+    string address,
+    bool isActive,
+    Guid tenantId)
+{
+    // ...
+}
+
+// ✅ GOOD - Use parameter object
+public record CreateUserRequest(
+    string Name,
+    string Email,
+    string Phone,
+    string Address,
+    bool IsActive,
+    Guid TenantId);
+
+public void CreateUser(CreateUserRequest request)
+{
+    // Access via request.Name, request.Email, etc.
+}
+```
+
+**Benefits:**
+- Easier to extend (add new parameters without changing signature)
+- Self-documenting (grouped related data)
+- Enables validation logic on the object itself
+- Reduces method signature complexity
 </parameters>
 
 <naming>
@@ -37,6 +73,45 @@ Function naming patterns:
 - Reveals intent without reading body
 - No abbreviations: `getTransaction()` not `getTx()`
 </naming>
+
+<string_comparison>
+**C# String Comparison Best Practices:**
+
+ALWAYS use `StringComparison` overloads to avoid culture-specific issues (CA1873).
+
+```csharp
+// ❌ BAD - Culture-dependent, performance issue
+if (str1.ToLower() == str2.ToLower()) { ... }
+if (str1.ToUpper() == str2.ToUpper()) { ... }
+
+// ✅ GOOD - Explicit comparison
+if (string.Equals(str1, str2, StringComparison.OrdinalIgnoreCase)) { ... }
+if (str1.Equals(str2, StringComparison.OrdinalIgnoreCase)) { ... }
+
+// ❌ BAD - Culture-dependent Contains
+if (str.ToLower().Contains("keyword")) { ... }
+
+// ✅ GOOD - Explicit comparison (C# 5.0+)
+if (str.Contains("keyword", StringComparison.OrdinalIgnoreCase)) { ... }
+
+// ❌ BAD - Culture-dependent StartsWith/EndsWith
+if (str.ToLower().StartsWith("prefix")) { ... }
+
+// ✅ GOOD - Explicit comparison
+if (str.StartsWith("prefix", StringComparison.OrdinalIgnoreCase)) { ... }
+```
+
+**StringComparison options:**
+- `Ordinal` - Binary comparison (fastest, case-sensitive)
+- `OrdinalIgnoreCase` - Binary comparison (case-insensitive)
+- `CurrentCulture` - Culture-aware (rarely needed)
+- `InvariantCulture` - Culture-invariant (for data storage)
+
+**Rule of thumb:**
+- Use `Ordinal` for identifiers, file paths, keys
+- Use `OrdinalIgnoreCase` for user input comparison
+- Avoid `ToLower()`/`ToUpper()` for comparison
+</string_comparison>
 </function_guidelines>
 
 <naming_conventions>
@@ -73,7 +148,84 @@ Suggest these fixes:
 | **Magic Numbers** | Unexplained literals | Named constants |
 | **Dead Code** | Commented-out or unreachable code | Delete it |
 | **Shotgun Surgery** | Small change touches many files | Consolidate related code |
+| **Nested Ternary** | `? ( ? : ) :` patterns | Extract to function/if-else |
+| **TODO/FIXME** | Untracked technical debt | Create ticket or fix immediately |
 </medium_smells>
+
+<nested_ternary_detection>
+**Nested Ternary Operators (S3358):**
+
+Nested ternaries are hard to read and maintain.
+
+```typescript
+// ❌ BAD - Nested ternary
+const status = isActive
+  ? (isPremium ? 'premium-active' : 'standard-active')
+  : 'inactive';
+
+const color = type === 'error'
+  ? 'red'
+  : type === 'warning' ? 'yellow' : 'blue';
+
+// ✅ GOOD - Early returns in function
+function getStatus(isActive: boolean, isPremium: boolean): string {
+  if (!isActive) return 'inactive';
+  if (isPremium) return 'premium-active';
+  return 'standard-active';
+}
+
+// ✅ GOOD - If-else chain
+let color: string;
+if (type === 'error') {
+  color = 'red';
+} else if (type === 'warning') {
+  color = 'yellow';
+} else {
+  color = 'blue';
+}
+
+// ✅ GOOD - Map/lookup for simple cases
+const colorMap: Record<string, string> = {
+  error: 'red',
+  warning: 'yellow',
+  info: 'blue'
+};
+const color = colorMap[type] ?? 'blue';
+```
+
+**Detection pattern:** Look for `? ... ? ... : ... :` in code.
+</nested_ternary_detection>
+
+<todo_fixme_tracking>
+**TODO/FIXME Comments (S1135):**
+
+Untracked TODOs become technical debt. Either fix immediately or create a tracked ticket.
+
+```typescript
+// ❌ BAD - Untracked TODO
+// TODO: handle edge case
+
+// ❌ BAD - Vague FIXME
+// FIXME: this is broken
+
+// ✅ ACCEPTABLE - Linked to ticket
+// TODO(#1234): Implement retry logic for transient failures
+
+// ✅ ACCEPTABLE - With deadline
+// FIXME(2026-02-15): Remove legacy API call after migration
+
+// ✅ BEST - No comment, just fix it
+// (Actually implement the fix instead of leaving a comment)
+```
+
+**Code review action:**
+1. Search for `TODO`, `FIXME`, `HACK`, `XXX`, `REFACTOR` comments
+2. For each:
+   - Is it linked to a ticket? If not, create one or fix now
+   - Is it still relevant? If not, delete
+   - Does it have context? If not, add details
+3. Report untracked TODOs as `[SUGGESTION]` in review
+</todo_fixme_tracking>
 </code_smells>
 
 <complexity_reduction>

package/templates/skills/review-code/references/smartstack-conventions.md

@@ -154,12 +154,36 @@ builder.ToTable("auth_users", SchemaConstants.Core);
 ```csharp
 [ApiController]
 [NavRoute("platform.administration.users")]
-public class UsersController : ControllerBase
+public class UsersController : ControllerBase  // MUST be ControllerBase, NOT Controller
 {
     // Routes generated from NavRoute: /api/platform/administration/users
 }
 ```
 
+**CRITICAL: Controller Inheritance (S6934)**
+
+```csharp
+// ❌ BAD - Inheriting from Controller
+public class UsersController : Controller
+{
+    // Brings in MVC View support (Razor, ViewData, ViewBag)
+    // Unnecessary for API controllers
+}
+
+// ✅ GOOD - Inheriting from ControllerBase
+public class UsersController : ControllerBase
+{
+    // Lightweight, API-only base class
+    // No MVC View support (cleaner, more appropriate)
+}
+```
+
+**Why ControllerBase?**
+- API controllers don't need MVC View support
+- `Controller` adds unnecessary dependencies (Razor, ViewData, etc.)
+- `ControllerBase` is lighter and more focused on APIs
+- Better performance and smaller footprint
+
 **NavRoute format:**
 - Lowercase only
 - Dot-separated hierarchy

package/templates/skills/ui-components/SKILL.md

@@ -318,6 +318,175 @@ const STATUS_CONFIG = {
 )}
 ```
 
+## TYPESCRIPT INTERFACES (MANDATORY)
+
+**ALWAYS define explicit TypeScript interfaces for component props.**
+
+```typescript
+// ✅ CORRECT - Explicit interface with all props typed
+interface UserCardProps {
+  user: User;
+  onSelect?: (user: User) => void;
+  isSelected?: boolean;
+  variant?: 'default' | 'compact';
+}
+
+export const UserCard: React.FC<UserCardProps> = ({
+  user,
+  onSelect,
+  isSelected = false,
+  variant = 'default'
+}) => {
+  // ...
+};
+
+// ❌ WRONG - Missing interface, inline types, or any
+export const UserCard = ({ user, onSelect }: any) => { ... }
+export const UserCard = (props: { user: any }) => { ... }
+```
+
+### State Typing
+```typescript
+// ✅ CORRECT - Explicit state types
+const [users, setUsers] = useState<User[]>([]);
+const [selectedId, setSelectedId] = useState<string | null>(null);
+const [status, setStatus] = useState<'idle' | 'loading' | 'error'>('idle');
+
+// ❌ WRONG - Implicit or missing types
+const [users, setUsers] = useState([]);
+const [data, setData] = useState();
+```
+
+## SEMANTIC HTML (ACCESSIBILITY)
+
+**ALWAYS use semantic HTML elements instead of divs with roles.**
+
+```tsx
+// ✅ CORRECT - Native button element
+<button type="button" onClick={handleClick} disabled={isDisabled}>
+  Click me
+</button>
+
+// ❌ WRONG - div with role (S6819)
+<div role="button" onClick={handleClick} tabIndex={0}>
+  Click me
+</div>
+```
+
+### Interactive Elements Mapping
+
+| Use Case | Correct Element | Wrong Pattern |
+|----------|----------------|---------------|
+| Clickable action | `<button type="button">` | `<div role="button">` |
+| Navigation link | `<a href="...">` or `<Link>` | `<div onClick={navigate}>` |
+| Form submission | `<button type="submit">` | `<div onClick={submit}>` |
+| Expandable section | `<details><summary>` | `<div onClick={toggle}>` |
+| List of items | `<ul><li>` with `<button>` inside | `<div role="listitem">` |
+
+### Clickable Cards Pattern
+```tsx
+// ✅ CORRECT - Card with button inside
+<div className="rounded-[var(--radius-card)] border ...">
+  <div className="p-4">
+    <h3>{title}</h3>
+    <p>{description}</p>
+  </div>
+  <button
+    type="button"
+    onClick={() => onSelect(item)}
+    className="w-full px-4 py-2 border-t ..."
+  >
+    Select
+  </button>
+</div>
+
+// ✅ CORRECT - Entire card as link
+<Link to={`/items/${item.id}`} className="block rounded-[var(--radius-card)] ...">
+  <div className="p-4">...</div>
+</Link>
+
+// ❌ WRONG - div with click handler
+<div onClick={() => onSelect(item)} className="cursor-pointer ...">
+  ...
+</div>
+```
+
+## PERFORMANCE OPTIMIZATION
+
+### React.memo for Pure Components
+```tsx
+import { memo, useCallback, useMemo } from 'react';
+
+// ✅ CORRECT - Memoized component for lists
+export const UserCard = memo(({ user, onSelect }: UserCardProps) => {
+  return (
+    <div className="...">
+      <h3>{user.name}</h3>
+      <button onClick={() => onSelect(user)}>Select</button>
+    </div>
+  );
+});
+UserCard.displayName = 'UserCard';
+```
+
+### useCallback for Event Handlers
+```tsx
+// ✅ CORRECT - Stable callback reference
+const handleSelect = useCallback((item: Item) => {
+  onSelect?.(item);
+  setSelectedId(item.id);
+}, [onSelect]);
+
+// ❌ WRONG - New function on every render
+const handleSelect = (item: Item) => {
+  onSelect?.(item);
+};
+```
+
+### useMemo for Expensive Computations
+```tsx
+// ✅ CORRECT - Memoized filtered list
+const filteredItems = useMemo(() =>
+  items.filter(item => item.status === filter),
+  [items, filter]
+);
+
+// ❌ WRONG - Recomputed on every render
+const filteredItems = items.filter(item => item.status === filter);
+```
+
+## LIST RENDERING (UNIQUE KEYS)
+
+**NEVER use array index as React key. ALWAYS use unique identifiers.**
+
+```tsx
+// ✅ CORRECT - Unique ID from data
+{items.map(item => (
+  <EntityCard key={item.id} {...mapToCardProps(item)} />
+))}
+
+// ✅ CORRECT - Composite key when needed
+{items.map(item => (
+  <Row key={`${item.tenantId}-${item.id}`} data={item} />
+))}
+
+// ❌ WRONG - Array index as key (S6479)
+{items.map((item, index) => (
+  <EntityCard key={index} {...mapToCardProps(item)} />
+))}
+
+// ❌ WRONG - Random key
+{items.map(item => (
+  <EntityCard key={Math.random()} {...mapToCardProps(item)} />
+))}
+```
+
+### Why Index Keys Are Problematic
+- Causes unnecessary re-renders when list order changes
+- Breaks component state (inputs, animations)
+- Causes visual glitches with drag-and-drop
+- Makes reconciliation inefficient
+
 ## ABSOLUTE RULES
 
 | DO | DON'T |
@@ -330,3 +499,8 @@ const STATUS_CONFIG = {
 | Responsive grid 1→2→3→4 | Fixed non-responsive grid |
 | h-full + flex-1 + mt-auto | Unaligned buttons in grid |
 | Empty and loading states | Native HTML tooltip |
+| Explicit TypeScript interfaces | `any` or implicit types |
+| `<button>` for click actions | `<div role="button">` |
+| `memo()` for list item components | Unmemoized components in loops |
+| `useCallback` for event handlers | Inline arrow functions in JSX |
+| Unique `id` for list keys | Array index as key |