@simpleapps-com/augur-skills 0.0.22 → 0.0.23

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/package.json +1 -1
  2. package/skills/simpleapps/augur-packages/SKILL.md +39 -127
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@simpleapps-com/augur-skills",
3
- "version": "0.0.22",
3
+ "version": "0.0.23",
4
4
  "description": "Install curated Claude Code skills",
5
5
  "license": "MIT",
6
6
  "type": "module",
package/skills/simpleapps/augur-packages/SKILL.md CHANGED
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: augur-packages
3
- description: Shared npm packages under @simpleapps-com/augur-*. Covers what each package provides, correct import patterns, key usage patterns, and what custom code they replace. Use when writing code for a site that consumes augur packages, during migration, or when deciding whether to write custom code.
3
+ description: Shared npm packages under @simpleapps-com/augur-*. Directs agents to check installed packages before writing custom code. This skill is a starting point — always read the actual package code for current API surface.
4
4
  ---
5
5
 
6
6
  # Augur Packages
@@ -9,116 +9,40 @@ Shared npm packages for Next.js ecommerce sites and React Native apps. Published
9
9
 
10
10
  Before writing custom code, check whether a package export already solves the problem.
11
11
 
12
- ## augur-utils
12
+ ## Ground Truth: Read the Code
13
13
 
14
- Types, formatters, cache config. Zero framework dependencies. Works everywhere.
14
+ This skill is a **stub, not an archive**. New packages are created, existing packages gain features, APIs evolve. This skill MUST NOT be treated as the complete picture.
15
15
 
16
- ```typescript
17
- import { formatPrice, CACHE_CONFIG } from "@simpleapps-com/augur-utils";
18
- import type { TCartLine, TProductItem } from "@simpleapps-com/augur-utils";
19
- import { cn } from "@simpleapps-com/augur-utils/web"; // clsx + tailwind-merge
20
- ```
16
+ **Always read the installed packages in your project's `node_modules/`:**
21
17
 
22
- **Types** cover: cart, category, inventory, product, pricing, attributes, UOM, supplier, filter, customer, menu, order, shipping, search, tax, metadata. Each has a Valibot schema (e.g., `CartLineSchema`).
18
+ 1. Run `ls repo/node_modules/@simpleapps-com/` to discover ALL available packages — there may be packages not listed here
19
+ 2. Read `repo/node_modules/@simpleapps-com/<package>/package.json` for the `exports` field to find available sub-paths
20
+ 3. Read files in `repo/node_modules/@simpleapps-com/<package>/dist/` to understand the current API surface
21
+ 4. Do NOT look at the source repo or other folders — only read what is installed in your project's `node_modules/`
23
22
 
24
- **Cache tiers** for React Query — every hook maps to one of these:
23
+ When this skill and the installed code disagree, **the installed code wins**. This skill exists to point you in the right direction, not to replace reading the code.
25
24
 
26
- | Tier | Use Case |
27
- |------|----------|
28
- | `CACHE_CONFIG.STATIC` | Rarely changes (categories, item master) |
29
- | `CACHE_CONFIG.SEMI_STATIC` | Changes occasionally (pricing, search) |
30
- | `CACHE_CONFIG.DYNAMIC` | Changes frequently (stock levels) |
31
- | `CACHE_CONFIG.CART` | User-specific, short-lived |
32
- | `CACHE_CONFIG.REALTIME` | Always refetch |
25
+ ## Known Packages
33
26
 
34
- ## augur-web
27
+ These are starting hints — not a complete list. Always check `node_modules/@simpleapps-com/` for the full set.
35
28
 
36
- shadcn/Radix UI components. Per-component entry points — no barrel export, only what you import gets bundled.
29
+ | Package | Purpose |
30
+ |---------|---------|
31
+ | `augur-utils` | Types, formatters, cache config, Valibot schemas. Zero framework dependencies. |
32
+ | `augur-web` | shadcn/Radix UI components. Per-component entry points. |
33
+ | `augur-hooks` | React Query hooks and Zustand stores. Cross-platform. |
34
+ | `augur-server` | Server-side utilities for Next.js — Redis caching, auth factory, query client. |
35
+ | `augur-tailwind` | Tailwind v4 CSS theme. No config file needed. |
37
36
 
38
- ```typescript
39
- import { Button } from "@simpleapps-com/augur-web/button";
40
- import { Dialog, DialogContent, DialogTitle } from "@simpleapps-com/augur-web/dialog";
41
- import { Card, CardHeader, CardContent } from "@simpleapps-com/augur-web/card";
42
- ```
37
+ ## How to Check for Package Solutions
43
38
 
44
- **Component conventions:** CVA variants, `React.forwardRef`, `asChild` via Radix Slot, `cn()` for class merging, `"use client"` preserved in build, `displayName` set, icons use `react-icons/lu`.
39
+ When considering custom code:
45
40
 
46
- **Tailwind content detection:** Tailwind v4 auto-detects sources. If augur-web classes are missing, add `@source "../node_modules/@simpleapps-com/augur-web/dist";` to your CSS.
47
-
48
- ## augur-hooks
49
-
50
- React Query hooks and Zustand stores. Cross-platform (works in Next.js and React Native).
51
-
52
- ```typescript
53
- // Cross-platform
54
- import { useItemPrice, useCartStore, useDebounce, AugurHooksProvider } from "@simpleapps-com/augur-hooks";
55
- // Web only (DOM-dependent)
56
- import { useIsMobile, useIsHydrated } from "@simpleapps-com/augur-hooks/web";
57
- ```
58
-
59
- **Hook triple pattern** — every query hook exports three things:
60
- - `use<Name>(params, options?)` — client-side hook (reads SDK from provider context)
61
- - `get<Name>Options(api, params)` — server-side prefetch (accepts SDK directly)
62
- - `get<Name>Key(params)` — query key factory for cache invalidation
63
-
64
- ```typescript
65
- // Client
66
- const { data } = useItemPrice(itemId, customerId, 1);
67
-
68
- // Server prefetch (no React context)
69
- await queryClient.prefetchQuery(getItemPriceOptions(api, itemId, customerId));
70
-
71
- // Cache invalidation
72
- queryClient.invalidateQueries({ queryKey: getItemPriceKey(itemId, customerId) });
73
- ```
74
-
75
- **queryFn override** — web consumers can route through cached server actions:
76
-
77
- ```typescript
78
- const { data } = useItemPrice(itemId, customerId, 1, {
79
- queryFn: () => getCachedItemPrice(itemId, customerId, 1),
80
- });
81
- ```
82
-
83
- **Cart hooks** use dependency injection — the package provides React Query orchestration (optimistic updates, invalidation, loading states), consumers inject site-specific mutation callbacks.
84
-
85
- **Provider required:** All query hooks need `AugurHooksProvider` wrapping the app with an SDK instance.
86
-
87
- ## augur-server
88
-
89
- Server-side utilities for Next.js. Redis caching, auth factory, query client, environment detection.
90
-
91
- ```typescript
92
- import { cachedSdkCall, getServerQueryClient, isDev, sdkCall } from "@simpleapps-com/augur-server";
93
- import { createAuthConfig } from "@simpleapps-com/augur-server/auth";
94
- ```
95
-
96
- **cachedSdkCall** wraps SDK calls with Redis caching (SHA-256 key hashing, per-method stats, fire-and-forget writes, circuit breaker). Falls through without caching if ioredis is not installed.
97
-
98
- **createAuthConfig** — NextAuth 5 factory with dependency-injected callbacks:
99
-
100
- ```typescript
101
- export const { handlers, signIn, signOut, auth } = NextAuth(
102
- createAuthConfig({
103
- callbacks: { getUserProfile, cartHdrLookup }, // site-specific
104
- defaultCustomerId: process.env.NEXT_PUBLIC_DEFAULT_CUSTOMER_ID,
105
- }),
106
- );
107
- ```
108
-
109
- **Site action registry** — `createServerSite()` creates a process-global singleton. Self-heals via three-tier fallback (globalThis → module cache → auto-init from env vars).
110
-
111
- ## augur-tailwind
112
-
113
- Tailwind v4 CSS theme. No `tailwind.config.ts` needed.
114
-
115
- ```css
116
- @import "tailwindcss";
117
- @import "@simpleapps-com/augur-tailwind/base.css";
118
- @plugin "tailwindcss-animate";
119
- ```
120
-
121
- Override brand with CSS variables: `--primary`, `--secondary`, `--radius`, etc. All HSL components (no wrapper).
41
+ 1. Run `ls repo/node_modules/@simpleapps-com/` to see what's installed
42
+ 2. Read the package's `package.json` `exports` and its `dist/` files for available functions, hooks, and components
43
+ 3. Look for the hook triple pattern in augur-hooks: `use<Name>`, `get<Name>Options`, `get<Name>Key`
44
+ 4. Check augur-web for UI components before building custom ones
45
+ 5. Only use what is in your `node_modules/` — do not reference the source repo
122
46
 
123
47
  ## What Stays Site-Specific
124
48
 
@@ -126,38 +50,26 @@ MUST NOT be replaced by packages:
126
50
  - **Server actions** (`"use server"`) — site-specific business logic
127
51
  - **Layout components** (Header, Footer, MainMenu) — brand-specific
128
52
  - **Domain components** (ProductItem, CartTable, CategoryCard) — compose UI primitives
129
- - **Auth callbacks** (`getUserProfile`, `cartHdrLookup`) — injected into `createAuthConfig`
53
+ - **Auth callbacks** — injected into package auth factory
130
54
  - **Cart mutation callbacks** — depend on site-specific server actions
131
55
  - **CSS variable overrides** — brand colors, fonts, radius
132
56
  - **next.config** — image domains, redirects, security headers
133
57
  - **Site integrations** — GA4, Maps, reCAPTCHA
134
58
 
135
- ## Anti-Pattern Catalog
136
-
137
- Custom code that duplicates package exports. When you see these in a site, replace with the package version.
138
-
139
- | Custom Code | Replace With |
140
- |-------------|-------------|
141
- | `cn()` in `@/lib/utils` | `cn` from `augur-utils/web` |
142
- | `formatPrice()` helpers | `formatPrice` from `augur-utils` |
143
- | Local types (`@/types/T*`) | Types from `augur-utils` |
144
- | Custom `CACHE_CONFIG` / inline TTLs | `CACHE_CONFIG` from `augur-utils` |
145
- | `@/components/ui/*` imports | `augur-web/<component>` |
146
- | Custom breadcrumb, quantity, pagination, form inputs | `augur-web/<component>` |
147
- | Custom `useDebounce` | `useDebounce` from `augur-hooks` |
148
- | Custom `useIsMobile` / `useIsHydrated` | From `augur-hooks/web` |
149
- | Custom price/cart hooks or stores | From `augur-hooks` |
150
- | Custom `cachedSdkCall` / SDK cache | `cachedSdkCall` from `augur-server` |
151
- | Custom `getServerQueryClient` | From `augur-server` |
152
- | Custom `isDev` / env detection | From `augur-server` |
153
- | Manual NextAuth Credentials config | `createAuthConfig` from `augur-server/auth` |
154
- | `lucide-react` / `@heroicons/react` | `react-icons/lu` |
155
- | `tailwind.config.ts` (v3) | `augur-tailwind/base.css` CSS-first |
156
-
157
- ## Platform Standard
59
+ ## Suggest Package Improvements
60
+
61
+ The augur packages exist to share common code across ALL Node projects. When you find yourself writing code that would benefit other sites, suggest it as a package addition:
62
+
63
+ - Create a GitHub issue on `simpleapps-com/augur-packages` describing the proposed addition
64
+ - Explain what it does, which sites would benefit, and why it belongs in the shared package
65
+ - Examples: a new utility function, a reusable hook, a common UI component, a shared type
66
+
67
+ The goal is to grow the packages over time so sites write less custom code.
68
+
69
+ ## Platform Standards
158
70
 
159
71
  - **Icons:** `react-icons/lu`
160
- - **Tailwind:** v4, CSS-first via `augur-tailwind/base.css`
72
+ - **Tailwind:** v4, CSS-first
161
73
  - **Validation:** Valibot (not Zod, not Yup)
162
- - **Auth:** NextAuth 5 via `createAuthConfig()`
74
+ - **Auth:** NextAuth 5 via package auth factory
163
75
  - **Reference site:** ampro-online