rahman-resources 0.4.2 → 0.7.0

package/lib/slice-schema.json

@@ -0,0 +1,161 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://resource.rahmanef.com/slice-schema.json",
+  "title": "Rahman Resources slice.json",
+  "description": "Contract for a tier-3 portable feature slice. See docs/slice-architecture.md.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "slug",
+    "version",
+    "category",
+    "title",
+    "description",
+    "namespace",
+    "frontend",
+    "deps"
+  ],
+  "properties": {
+    "$schema": { "type": "string" },
+    "slug": {
+      "type": "string",
+      "pattern": "^[a-z0-9][a-z0-9-]*[a-z0-9]$",
+      "description": "Globally-unique kebab-case id."
+    },
+    "version": {
+      "type": "string",
+      "pattern": "^\\d+\\.\\d+\\.\\d+(?:-[0-9A-Za-z.-]+)?$",
+      "description": "Slice semver, independent of kitab version."
+    },
+    "category": {
+      "type": "string",
+      "enum": [
+        "ai",
+        "auth",
+        "data",
+        "payment",
+        "email",
+        "realtime",
+        "storage",
+        "search",
+        "content",
+        "ui",
+        "infra"
+      ]
+    },
+    "title": { "type": "string", "minLength": 3 },
+    "description": { "type": "string", "minLength": 10 },
+    "namespace": {
+      "type": "string",
+      "pattern": "^@/features/[a-z0-9][a-z0-9-]*$",
+      "description": "Import root for slice-internal references; CLI rewrites if user opts a different namespace."
+    },
+    "convex": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["rootPaths"],
+      "properties": {
+        "tablesExport": {
+          "type": "string",
+          "pattern": "^[a-zA-Z][a-zA-Z0-9_]*$",
+          "description": "Name of the table-fragment export in schema.ts (e.g., midtransTables)."
+        },
+        "schemaPath": {
+          "type": "string",
+          "description": "Convex schema file inside this slice's convex tree."
+        },
+        "rootPaths": {
+          "type": "array",
+          "minItems": 1,
+          "items": { "type": "string" },
+          "description": "Convex folders the lift pulls into the consumer's convex/."
+        }
+      }
+    },
+    "frontend": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["slicePath", "configExport"],
+      "properties": {
+        "slicePath": {
+          "type": "string",
+          "pattern": "^frontend/slices/[a-z0-9_/-]+$"
+        },
+        "configExport": {
+          "type": "string",
+          "pattern": "^[a-zA-Z][a-zA-Z0-9_]*$",
+          "description": "Name of the defineFeature(...) export the registry generators look for."
+        }
+      }
+    },
+    "deps": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "npm": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Plain npm install lines."
+        },
+        "shadcn": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "shadcn primitives this slice imports."
+        },
+        "env": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["name", "scope"],
+            "properties": {
+              "name": { "type": "string", "pattern": "^[A-Z][A-Z0-9_]*$" },
+              "scope": {
+                "type": "string",
+                "enum": ["convex", "next-public", "server"]
+              },
+              "required": { "type": "boolean", "default": true },
+              "description": { "type": "string" }
+            }
+          }
+        },
+        "peers": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["slug", "range"],
+            "properties": {
+              "slug": { "type": "string" },
+              "range": { "type": "string" },
+              "reason": { "type": "string" }
+            }
+          }
+        }
+      }
+    },
+    "registers": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "enum": ["registry", "preview-registry", "export-registry"]
+      },
+      "description": "Which registry generators auto-discover this slice."
+    },
+    "audit": {
+      "type": "array",
+      "items": { "type": "string", "pattern": "^bp:[a-z0-9-]+$" },
+      "description": "Audit-bp rule ids that apply to this slice."
+    },
+    "license": { "type": "string", "default": "MIT" },
+    "tags": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "providers": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Optional sub-provider list when a slice routes between alternatives (e.g., payment slice with midtrans + doku siblings)."
+    }
+  }
+}

package/lib/starter/_gitignore

@@ -7,6 +7,8 @@ dist
 .env
 *.tsbuildinfo
 next-env.d.ts
-convex/_generated
+# convex/_generated is COMMITTED in self-hosted setups (Dokploy etc) so the
+# Docker build can typecheck without running codegen inside the container.
+# If you deploy via Convex Cloud, you can re-add the ignore line.
 .vercel
 .DS_Store

package/lib/starter/_package.json

@@ -13,6 +13,7 @@
     "convex:codegen": "convex dev --once"
   },
   "dependencies": {
+    "@auth/core": "^0.37.0",
     "@convex-dev/auth": "^0.0.84",
     "@radix-ui/react-label": "^2.1.0",
     "@radix-ui/react-slot": "^1.1.0",

package/lib/starter/app/layout.tsx

@@ -1,4 +1,5 @@
 import type { Metadata } from "next";
+import { Suspense } from "react";
 import { Inter } from "next/font/google";
 import { ConvexClientProvider } from "@/components/convex-provider";
 import { Toaster } from "sonner";
@@ -15,7 +16,9 @@ export default function RootLayout({ children }: { children: React.ReactNode })
   return (
     <html lang="en" suppressHydrationWarning>
       <body className={`${inter.variable} font-sans antialiased`}>
-        <ConvexClientProvider>{children}</ConvexClientProvider>
+        <Suspense fallback={null}>
+          <ConvexClientProvider>{children}</ConvexClientProvider>
+        </Suspense>
         <Toaster position="bottom-right" />
       </body>
     </html>

package/lib/starter/components/convex-provider.tsx

@@ -1,13 +1,37 @@
 "use client";
 
-import { ConvexAuthNextjsProvider } from "@convex-dev/auth/nextjs";
-import { ConvexReactClient } from "convex/react";
-import type { ReactNode } from "react";
+// SSG-safe Convex auth provider for Next 16 + cacheComponents:true.
+//
+// Why not ConvexAuthNextjsProvider? Postmortem 5.2: it crashes during static
+// prerender (calls useConvexAuth() with undefined context). This client-only
+// mount + Suspense wrap pattern matches what the si-coder skill ships.
+//
+// Auth actions are routed through HTTP (not WebSocket) so signIn / signOut
+// work even when the client hasn't established its WS yet.
 
-const url = process.env.NEXT_PUBLIC_CONVEX_URL;
-const convex = url ? new ConvexReactClient(url) : null;
+import { ConvexAuthProvider } from "@convex-dev/auth/react";
+import { ConvexReactClient } from "convex/react";
+import { ConvexHttpClient } from "convex/browser";
+import { useEffect, useState, type ReactNode } from "react";
 
 export function ConvexClientProvider({ children }: { children: ReactNode }) {
-  if (!convex) return <>{children}</>;
-  return <ConvexAuthNextjsProvider client={convex}>{children}</ConvexAuthNextjsProvider>;
+  const [mounted, setMounted] = useState(false);
+  const [convex] = useState(() => {
+    const url = process.env.NEXT_PUBLIC_CONVEX_URL;
+    if (!url) return null;
+    const client = new ConvexReactClient(url);
+    const http = new ConvexHttpClient(url);
+    const orig = client.action.bind(client);
+    (client as unknown as { action: typeof client.action }).action = ((ref, args) => {
+      const name = (ref as unknown as { _name?: string })?._name ?? String(ref);
+      return typeof name === "string" && name.startsWith("auth:")
+        ? http.action(ref, args)
+        : orig(ref, args);
+    }) as typeof client.action;
+    return client;
+  });
+
+  useEffect(() => setMounted(true), []);
+  if (!mounted || !convex) return <>{children}</>;
+  return <ConvexAuthProvider client={convex}>{children}</ConvexAuthProvider>;
 }

package/lib/starter/tsconfig.json

@@ -15,9 +15,12 @@
     "incremental": true,
     "plugins": [{ "name": "next" }],
     "paths": {
-      "@/*": ["./*"]
+      "@/*": ["./*"],
+      "@/shared/*": ["./components/shared/*", "./lib/shared/*"],
+      "@/features/*": ["./frontend/slices/*"],
+      "@convex/*": ["./convex/*"]
     }
   },
   "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts"],
-  "exclude": ["node_modules", "convex/_generated"]
+  "exclude": ["node_modules", "convex-templates"]
 }

package/lib/workflows/features.md

@@ -0,0 +1,50 @@
+# Workflow — Features (CRUD)
+
+Features are backend / integration drop-ins (auth, midtrans, resend, vector-search, ai-router, …).
+Source of truth: `lib/content/features.ts`.
+
+## Create
+
+1. Build the feature surface — backend code in `convex/features/<slug>/`, frontend code in
+   `frontend/slices/<slug>/` (vertical-slice convention per CLAUDE.md).
+2. Per-feature schema: `convex/features/<slug>/schema.ts` exporting `<slug>Tables`. Compose into root.
+3. Frontend: `frontend/slices/<slug>/{config.ts, init.ts, page.tsx, ...}`. The `config.ts` calls
+   `defineFeature({...})` and gets picked up automatically by
+   `npx tsx scripts/features/generate-registry.ts`.
+4. Register entry in `lib/content/features.ts`: slug, title, description, category, tags,
+   pullPaths, files, dependencies, agentRecipe.
+5. Regenerate registries:
+   ```bash
+   npx tsx scripts/features/generate-registry.ts
+   npx tsx scripts/features/generate-preview-registry.ts
+   npx tsx scripts/features/generate-export-registry.ts
+   cd packages/cli && node scripts/gen-manifest.mjs
+   ```
+6. Verify `npx tsc --noEmit` clean.
+7. Commit + push.
+8. Publish CLI minor — feature is now installable via `npx rahman-resources add <slug>`.
+
+## Read
+
+- Browse: `https://resource.rahmanef.com/features` then `/features/<slug>`.
+- CLI: `npx rahman-resources list features` / `info <slug>`.
+- MCP tool: `rr_list_features` / `rr_get`.
+- MCP resource: `rr://features/<slug>`.
+
+## Update
+
+1. Edit `lib/content/features.ts` entry.
+2. Update slice/convex code if shape changed.
+3. Regenerate registries (same as Create step 5).
+4. Commit + push.
+5. Publish CLI patch (content-only) or minor (file-list change).
+
+## Delete
+
+1. Remove entry from `lib/content/features.ts`.
+2. `git rm -r convex/features/<slug>/` + `frontend/slices/<slug>/`.
+3. Regenerate registries.
+4. Search repo for `<slug>` references — most likely no other feature depends on it,
+   but check `site/lib/build/compat.ts` for template×feature compat hints.
+5. Commit + push.
+6. Publish CLI **major** if widely depended on, else minor.

package/lib/workflows/recipes.md

@@ -0,0 +1,42 @@
+# Workflow — Recipes (CRUD)
+
+Recipes are UI patterns to **copy manually** (block-editor, command-palette, asymmetric-masonry, …).
+Lower-friction than features — recipes don't always have backend pieces.
+Source of truth: `lib/content/recipes.ts`.
+
+## Create
+
+1. Build the UI under any of these (pick what fits the recipe shape):
+   - `frontend/slices/<slug>/` for full slice patterns
+   - `components/<area>/<Component>.tsx` for single-component recipes
+   - Existing `cookbook/` or `recipes/` dirs at repo root for ready-to-paste snippets
+2. Register entry in `lib/content/recipes.ts`: slug, title, description, source, repoPath, tags,
+   exampleCode (the snippet user pastes), agentRecipe (instructions for AI to install).
+3. Regenerate manifest: `cd packages/cli && node scripts/gen-manifest.mjs`.
+4. Verify build (recipes show on `/recipes` index + `/recipes/<slug>` detail).
+5. Commit + push.
+6. Publish CLI patch — recipes don't ship as installable artifacts via `add`; they're
+   reference patterns reachable via the docs site + MCP.
+
+## Read
+
+- Browse: `https://resource.rahmanef.com/recipes` then `/recipes/<slug>`.
+- CLI: `npx rahman-resources list` (no recipe-only filter; full mixed list) / `info <slug>`.
+- MCP tool: `rr_list_recipes` / `rr_get`.
+- MCP resource: `rr://recipes/<slug>`.
+
+## Update
+
+1. Edit `lib/content/recipes.ts` entry.
+2. Update the underlying snippet/file if it lives in the repo.
+3. Regenerate manifest.
+4. Commit + push.
+5. Publish CLI patch.
+
+## Delete
+
+1. Remove entry from `lib/content/recipes.ts`.
+2. Remove the underlying file(s) if exclusive to this recipe.
+3. Regenerate manifest.
+4. Commit + push.
+5. Publish CLI patch (recipes don't have installer call-sites — safe to remove).

package/lib/workflows/skills.md

@@ -0,0 +1,48 @@
+# Workflow — Claude Skills (CRUD)
+
+Claude Skills are reusable agent skills (anthropics + rahman-authored) shipped via the kitab.
+Source of truth: `site/lib/content/claude-skills.ts` — sync feeds `packages/cli/lib/skills.json`.
+
+## Create
+
+1. Author the skill at `~/.agents/skills/<slug>/SKILL.md` (or the project-local skill path).
+   Follow the SKILL.md frontmatter contract (name, description, type, tools).
+2. If it should ship via the kitab, add an entry to `site/lib/content/claude-skills.ts`:
+   slug, title, description, scope ("anthropics" | "rahman"), tags, sourceUrl.
+3. Sync to CLI bundle:
+   ```bash
+   node packages/cli/scripts/sync-skills.mjs
+   ```
+   This writes `packages/cli/lib/skills.json` from the TypeScript source. The
+   `--check` variant runs in CI to prevent drift.
+4. Regenerate manifest: `cd packages/cli && node scripts/gen-manifest.mjs`.
+5. Verify the skill shows in `npx rahman-resources list skills`.
+6. Commit + push (both `site/lib/content/claude-skills.ts` and `packages/cli/lib/skills.json`).
+7. Publish CLI minor — consumers can now `npx rahman-resources add-skill <slug>`.
+
+## Read
+
+- Browse: `https://resource.rahmanef.com/agents` (and on the site Skills are listed alongside
+  templates/features in the Bundle Builder at `/build`).
+- CLI: `npx rahman-resources list skills` / `info <slug>`.
+- MCP tool: `rr_list_skills` / `rr_get`.
+- MCP resource: `rr://skills/<slug>`.
+
+## Update
+
+1. Edit `site/lib/content/claude-skills.ts` entry.
+2. Edit `~/.agents/skills/<slug>/SKILL.md` if the actual skill changed.
+3. Run `node packages/cli/scripts/sync-skills.mjs`.
+4. Regenerate manifest.
+5. Commit + push.
+6. Publish CLI patch (description-only) or minor (slug rename / new tools).
+
+## Delete
+
+1. Remove entry from `site/lib/content/claude-skills.ts`.
+2. Delete the SKILL.md folder if no longer used.
+3. Re-sync (`sync-skills.mjs`).
+4. Regenerate manifest.
+5. Commit + push.
+6. Publish CLI **major** if widely used (consumers' `add-skill <slug>` will 404),
+   else minor.

package/lib/workflows/templates.md

@@ -0,0 +1,51 @@
+# Workflow — Templates (CRUD)
+
+Templates are full-app website templates registered with `category: "website-template"`.
+Source of truth: `lib/content/layouts.ts` in the kitab repo.
+
+## Create
+
+1. Build the UI scaffold under `app/preview/<slug>/{public,admin}/` following the
+   `personal-brand-os` gold reference (read `template-base/CONSUMER-SETUP.md` first).
+2. Build per-template shared at
+   `components/templates/<base>/shared/{site-config.ts, types.ts, seed.ts, nav-config.ts, store.tsx}`.
+3. Build slice components at `components/templates/<base>/slices/<route>/<RouteName>Page.tsx` for public
+   and `components/templates/<base>/slices/admin/<route>/<RouteName>View.tsx` for admin.
+4. Reuse chrome from `components/templates/_shared/ui/*` — never create new chrome.
+5. Reuse shadcn primitives from `@/components/ui/*` + lucide-react. No new UI lib deps.
+6. Register an entry in `lib/content/layouts.ts` with: slug, title, category="website-template",
+   description, source, repoPath, primaryFile, tags, previewPath, adminPreviewPath, defaultSurface,
+   pullPaths, files (full list), dependencies, exampleCode, agentRecipe.
+7. Regenerate manifest: `cd packages/cli && node scripts/gen-manifest.mjs`.
+8. Verify: `npx tsc --noEmit` (root + template-base both 0) and `npm run build` (route appears
+   in the prerendered list).
+9. Commit + push.
+10. Publish CLI minor (`packages/cli/package.json` version bump → `npm publish`) so the new
+    template lands in the npm tarball consumers fetch via `npx rahman-resources init`.
+
+## Read
+
+- Browse: `https://resource.rahmanef.com/templates` (gallery) or `/layouts/<slug>` (detail).
+- CLI: `npx rahman-resources list templates` then `npx rahman-resources info <slug>`.
+- MCP tool: `rr_list_templates` / `rr_get`.
+- MCP resource: `rr://templates/<slug>`.
+- Knowledge base for AI agents: `https://resource.rahmanef.com/llms.txt`.
+
+## Update
+
+1. Edit the entry in `lib/content/layouts.ts` (description, files, agentRecipe — anything).
+2. Update the underlying component files if shape changed.
+3. Regenerate manifest (same step as Create).
+4. Verify build green.
+5. Commit + push.
+6. Publish CLI patch (content-only) or minor (new field/file in the entry).
+
+## Delete
+
+1. Remove the entry from `lib/content/layouts.ts`.
+2. `git rm -r app/preview/<slug>/` and `components/templates/<base>/`.
+3. Regenerate manifest.
+4. Audit: `grep -r "<slug>"` repo-wide — purge stale references.
+5. Commit + push.
+6. Publish CLI **major** if the template was widely used (consumers' `init` calls referencing
+   the slug will fail), else minor.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "rahman-resources",
-  "version": "0.4.2",
-  "description": "Scaffolder + installer for Rahman Resources kitab — npx rahman-resources init <app>; add <template>; list; info",
+  "version": "0.7.0",
+  "description": "Scaffolder + installer for Rahman Resources kitab — npx rahman-resources init/add/lift/scaffold-slice/publish-slice. Tier-3 portable feature slices + manifest + skills + CRUD workflows.",
   "type": "module",
   "license": "MIT",
   "author": "Rahman <casadezian@gmail.com>",
@@ -25,14 +25,18 @@
   "scripts": {
     "gen": "node scripts/gen-manifest.mjs",
     "validate": "node scripts/validate.mjs",
+    "validate:slices": "node scripts/validate-slice.mjs",
     "sync:skills": "node scripts/sync-skills.mjs",
     "sync:skills:check": "node scripts/sync-skills.mjs --check",
-    "prepublishOnly": "node scripts/sync-skills.mjs --check && node scripts/validate.mjs"
+    "prepublishOnly": "node scripts/sync-skills.mjs --check && node scripts/validate.mjs && node scripts/validate-slice.mjs --check"
   },
   "dependencies": {
     "kleur": "^4.1.5",
     "tiged": "^2.12.7"
   },
+  "overrides": {
+    "tar": "^7.5.0"
+  },
   "keywords": [
     "rahman",
     "kitab",