@geenius/tools 0.1.0

package/.changeset/config.json

@@ -0,0 +1,11 @@
+{
+  "$schema": "https://unpkg.com/@changesets/config@3.1.1/schema.json",
+  "changelog": "@changesets/cli/changelog",
+  "commit": false,
+  "fixed": [],
+  "linked": [],
+  "access": "public",
+  "baseBranch": "main",
+  "updateInternalDependencies": "patch",
+  "ignore": []
+}

package/.env.example

@@ -0,0 +1,2 @@
+# No environment variables required for library development
+# This file exists for compliance — the library has no runtime env dependencies

package/.github/CODEOWNERS

@@ -0,0 +1 @@
+* @mxn2020

package/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,16 @@
+---
+name: Bug Report
+about: Report a bug
+labels: bug
+---
+
+## Describe the bug
+
+## Steps to reproduce
+
+## Expected behavior
+
+## Environment
+- Package version:
+- Node version:
+- OS:

package/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,11 @@
+---
+name: Feature Request
+about: Suggest a new feature
+labels: enhancement
+---
+
+## Problem
+
+## Proposed solution
+
+## Alternatives considered

package/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,10 @@
+## What
+
+## Why
+
+## How
+
+## Checklist
+- [ ] Tests added/updated
+- [ ] `pnpm changeset` run (if applicable)
+- [ ] Documentation updated

package/.github/dependabot.yml

@@ -0,0 +1,11 @@
+version: 2
+updates:
+  - package-ecosystem: "npm"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 10
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"

package/.github/workflows/ci.yml

@@ -0,0 +1,23 @@
+name: CI
+on:
+  pull_request:
+    branches: [main]
+  push:
+    branches: [main]
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
+        with:
+          version: 10
+      - uses: actions/setup-node@v4
+        with:
+          node-version-file: '.nvmrc'
+          cache: 'pnpm'
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm build
+      - run: pnpm lint
+      - run: pnpm test

package/.github/workflows/release.yml

@@ -0,0 +1,29 @@
+name: Release
+on:
+  push:
+    branches: [main]
+
+concurrency: ${{ github.workflow }}-${{ github.ref }}
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
+        with:
+          version: 10
+      - uses: actions/setup-node@v4
+        with:
+          node-version-file: '.nvmrc'
+          cache: 'pnpm'
+          registry-url: 'https://registry.npmjs.org'
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm build
+      - uses: changesets/action@v1
+        with:
+          publish: pnpm changeset publish
+          version: pnpm changeset version
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

package/.node-version

@@ -0,0 +1 @@
+20

package/.nvmrc

@@ -0,0 +1 @@
+22

package/.prettierrc

@@ -0,0 +1,7 @@
+{
+  "semi": false,
+  "singleQuote": true,
+  "trailingComma": "all",
+  "printWidth": 120,
+  "tabWidth": 2
+}

package/.project/ACCOUNT.yaml

@@ -0,0 +1,4 @@
+owner: Mehdi Nabhani
+email: mehdi@geenius.app
+github: mxn2020
+organization: geenius

package/.project/IDEAS.yaml

@@ -0,0 +1,7 @@
+ideas:
+  - title: "CLI scaffolding"
+    description: "Add a create command to geenius-cli for this package"
+    priority: medium
+  - title: "Vue adapter"
+    description: "Add Vue 3 support alongside React and SolidJS"
+    priority: low

package/.project/PROJECT.yaml

@@ -0,0 +1,11 @@
+name: geenius-tools
+description: "Geenius Tools — Reusable dev tools for React, Solid, and Convex"
+category: library
+priority: high
+tags:
+  - geenius
+  - npm-package
+  - react
+  - solidjs
+deploy_url: null
+npm_scope: "@geenius-tools"

package/.project/ROADMAP.yaml

@@ -0,0 +1,15 @@
+version: "0.1"
+milestones:
+  - name: "v0.1.0 — Initial Release"
+    status: in-progress
+    items:
+      - "Core shared types and logic"
+      - "React hooks and components"
+      - "SolidJS primitives"
+      - "npm publishing via Changesets"
+  - name: "v0.2.0 — Stability"
+    status: planned
+    items:
+      - "Test coverage ≥ 50%"
+      - "API documentation"
+      - "Convex adapter"

package/CHANGELOG.md

@@ -0,0 +1,16 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.0.1] - 2026-03-08
+
+### Added
+- Initial release
+- Error handling: `convex-errors`, `errors-react`, `errors-solidjs`
+- Logging: `logger`, `logger-react`, `logger-solid`
+- Performance: `perf-react`, `perf-solidjs`
+- Utilities: `convex-wrappers`, `env`
+- Developer tools: `devtools-react`

package/CODE_OF_CONDUCT.md

@@ -0,0 +1,26 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, caste, color, religion, or sexual identity and orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment:
+- Using welcoming and inclusive language
+- Being respectful of differing viewpoints and experiences
+- Gracefully accepting constructive criticism
+- Focusing on what is best for the community
+
+Examples of unacceptable behavior:
+- Trolling, insulting/derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information without explicit permission
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the project maintainers at support@geenius.app. All complaints will be reviewed and investigated.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org/), version 2.1.

package/CONTRIBUTING.md

@@ -0,0 +1,69 @@
+# Contributing to @geenius-tools
+
+Thank you for your interest in contributing! This guide will help you get started.
+
+## Development Setup
+
+```bash
+# Clone the repository
+git clone https://github.com/mxn2020/geenius-tools.git
+cd geenius-tools
+
+# Install dependencies
+pnpm install
+
+# Build all packages
+pnpm build
+
+# Run tests
+pnpm test
+
+# Lint
+pnpm lint
+```
+
+## Project Structure
+
+```
+packages/
+  convex-errors/     — Convex error handling utilities
+  convex-wrappers/   — Convex function wrappers
+  devtools-react/    — React developer tools panel
+  env/               — Environment variable utilities
+  errors-react/      — React error boundaries and displays
+  errors-solidjs/    — SolidJS error handling
+  logger/            — Structured logging
+  logger-react/      — React logging hooks
+  logger-solid/      — SolidJS logging hooks
+  perf-react/        — React performance monitoring
+  perf-solidjs/      — SolidJS performance monitoring
+```
+
+## Contribution Workflow
+
+1. **Fork** the repository
+2. **Create a branch** for your change: `git checkout -b feat/my-feature`
+3. **Make your changes** and add tests
+4. **Ensure checks pass**: `pnpm lint && pnpm test && pnpm build`
+5. **Commit** with a conventional message: `feat: add metrics collector`
+6. **Push** and open a Pull Request
+
+## Commit Convention
+
+We follow [Conventional Commits](https://www.conventionalcommits.org/):
+- `feat:` — New feature or utility
+- `fix:` — Bug fix
+- `docs:` — Documentation only
+- `refactor:` — Code change that neither fixes a bug nor adds a feature
+- `test:` — Adding or updating tests
+- `chore:` — Tooling, CI, dependencies
+
+## Code Style
+
+- TypeScript strict mode
+- Prettier for formatting
+- ESLint for linting
+
+## Questions?
+
+Open an issue or reach out at support@geenius.app.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Geenius
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1 @@
+# ✦ geenius-tools\n\n> Geenius Tools — Reusable dev tools for React, Solid, and Convex\n\n---\n\n## Overview\nBuilt with Steve Jobs-level minimalism and Jony Ive-level craftsmanship, this package is designed to deliver unparalleled developer experience (DX) and rock-solid performance.\n\n## Installation\n\n```bash\npnpm add geenius-tools\n```\n\n## Usage\n\n```typescript\nimport { init } from 'geenius-tools';\n\n// Initialize the module with absolute precision\ninit({\n  mode: 'premium',\n});\n```\n\n## Architecture\n- **Zero-config**: It just works.\n- **Strictly Typed**: Fully written in TypeScript for flawless IntelliSense.\n- **Framework Agnostic**: seamlessly integrates into the Geenius ecosystem.\n\n---\n\n*Designed by Antigravity HQ*\n

package/SECURITY.md

@@ -0,0 +1,18 @@
+# Security Policy
+
+## Supported Versions
+
+| Version | Supported          |
+|---------|-------------------|
+| 0.0.x   | ✅ Yes             |
+
+## Reporting a Vulnerability
+
+If you discover a security vulnerability, please report it responsibly:
+
+1. **Do NOT** open a public GitHub issue
+2. **Email** security@geenius.app with details
+3. Include steps to reproduce, impact assessment, and any suggested fix
+4. You will receive a response within **48 hours**
+
+We will coordinate disclosure and credit you (if desired) once the issue is resolved.

package/SUPPORT.md

@@ -0,0 +1,14 @@
+# Support
+
+## Getting Help
+
+- **Documentation**: See the [README](./README.md) for usage and API reference
+- **Issues**: [Open a GitHub issue](https://github.com/mxn2020/geenius-tools/issues) for bugs or feature requests
+- **Discussions**: Use [GitHub Discussions](https://github.com/mxn2020/geenius-tools/discussions) for questions and community support
+- **Email**: support@geenius.app for private inquiries
+
+## Response Times
+
+- **Bug reports**: Within 48 hours
+- **Feature requests**: Reviewed weekly
+- **Security issues**: Within 24 hours (see [SECURITY.md](./SECURITY.md))

package/package.json

@@ -0,0 +1,75 @@
+{
+  "name": "@geenius/tools",
+  "type": "module",
+  "version": "0.1.0",
+  "description": "Geenius Tools — Reusable dev tools for React, Solid, and Convex",
+  "author": "Antigravity HQ",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/mxn2020/geenius-tools.git"
+  },
+  "keywords": [
+    "devtools",
+    "error-handling",
+    "logging",
+    "performance",
+    "convex",
+    "react",
+    "solidjs",
+    "geenius"
+  ],
+  "scripts": {
+    "dev": "pnpm -r --parallel type-check",
+    "build": "pnpm -r build",
+    "clean": "pnpm -r clean",
+    "lint": "pnpm -r --parallel type-check",
+    "test": "echo \"No tests configured yet\" && exit 0",
+    "type-check": "pnpm -r type-check",
+    "format": "prettier --write \"packages/*/src/**/*.{ts,tsx}\"",
+    "version:patch": "pnpm -r exec -- npm version patch --no-git-tag-version && npm version patch -m 'v%s'",
+    "version:minor": "pnpm -r exec -- npm version minor --no-git-tag-version && npm version minor -m 'v%s'",
+    "version:major": "pnpm -r exec -- npm version major --no-git-tag-version && npm version major -m 'v%s'",
+    "release": "git push && git push --tags",
+    "publish:all": "pnpm -r publish --access public",
+    "stop": "pkill -f 'vite.*geenius-tools' || true"
+  },
+  "devDependencies": {
+    "prettier": "^3.8.1"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "exports": {
+    ".": {
+      "types": "./packages/env/dist/index.d.ts",
+      "import": "./packages/env/dist/index.js"
+    },
+    "./env": {
+      "types": "./packages/env/dist/index.d.ts",
+      "import": "./packages/env/dist/index.js"
+    },
+    "./errors": {
+      "types": "./packages/errors/dist/index.d.ts",
+      "import": "./packages/errors/dist/index.js"
+    },
+    "./logger": {
+      "types": "./packages/logger/dist/index.d.ts",
+      "import": "./packages/logger/dist/index.js"
+    },
+    "./perf": {
+      "types": "./packages/perf/dist/index.d.ts",
+      "import": "./packages/perf/dist/index.js"
+    },
+    "./devtools": {
+      "types": "./packages/devtools/dist/index.d.ts",
+      "import": "./packages/devtools/dist/index.js"
+    },
+    "./convex": {
+      "types": "./packages/convex/shared/dist/index.d.ts",
+      "import": "./packages/convex/shared/dist/index.js"
+    }
+  },
+  "main": "./packages/env/dist/index.js",
+  "types": "./packages/env/dist/index.d.ts"
+}

package/packages/convex/shared/README.md

@@ -0,0 +1 @@
+# ✦ @geenius-tools/convex\n\n> Typed error system for Convex applications\n\n---\n\n## Overview\nBuilt with Steve Jobs-level minimalism and Jony Ive-level craftsmanship, this package is designed to deliver unparalleled developer experience (DX) and rock-solid performance.\n\n## Installation\n\n```bash\npnpm add @geenius-tools/convex\n```\n\n## Usage\n\n```typescript\nimport { init } from '@geenius-tools/convex';\n\n// Initialize the module with absolute precision\ninit({\n  mode: 'premium',\n});\n```\n\n## Architecture\n- **Zero-config**: It just works.\n- **Strictly Typed**: Fully written in TypeScript for flawless IntelliSense.\n- **Framework Agnostic**: seamlessly integrates into the Geenius ecosystem.\n\n---\n\n*Designed by Antigravity HQ*\n

package/packages/convex/shared/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@geenius-tools/convex",
+  "version": "0.1.0",
+  "private": false,
+  "type": "module",
+  "description": "Typed error system for Convex applications",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "clean": "rm -rf dist",
+    "type-check": "tsc --noEmit",
+    "prepublishOnly": "pnpm clean && pnpm build"
+  },
+  "peerDependencies": {
+    "convex": ">=1.0.0"
+  },
+  "devDependencies": {
+    "convex": "^1.34.0",
+    "tsup": "^8.5.1",
+    "typescript": "~5.9.3"
+  },
+  "author": "Antigravity HQ",
+  "engines": {
+    "node": ">=20.0.0"
+  }
+}

package/packages/convex/shared/src/audit/index.ts

@@ -0,0 +1,5 @@
+// @geenius-tools/convex-wrappers — src/audit/index.ts
+
+export { auditLogFields, auditLogIndexes } from './schema'
+export { writeAudit, generateSearchableText, computeDiff } from './write'
+export { auditPreset } from './presets'

package/packages/convex/shared/src/audit/presets.ts

@@ -0,0 +1,165 @@
+// @geenius-tools/convex-wrappers — src/audit/presets.ts
+
+import type { AuditLogEntry } from '../types'
+import { computeDiff } from './write'
+
+/**
+ * Audit log presets — reusable patterns for common mutation audit scenarios.
+ *
+ * These return factory functions compatible with the mutation wrapper's
+ * `.audit()` builder, producing `AuditLogEntry` payloads automatically.
+ *
+ * @example
+ * ```ts
+ * // In your Convex mutation:
+ * import { auditPreset } from '@geenius-tools/convex-wrappers'
+ *
+ * export const updateOrderStatus = authedMutation()
+ *   .name('orders.updateStatus')
+ *   .args({ orderId: v.id('orders'), status: v.string() })
+ *   .audit(auditPreset.entityStatus({
+ *     entityTable: 'orders',
+ *     entityId: (args) => args.orderId,
+ *     action: 'update_status',
+ *     before: async (ctx, args) => {
+ *       const order = await ctx.db.get(args.orderId)
+ *       return order?.status
+ *     },
+ *     after: (args) => args.status,
+ *   }))
+ *   .handler(async (ctx, args) => { ... })
+ * ```
+ */
+export const auditPreset = {
+    /**
+     * Preset for status changes (before → after).
+     * Generates a diff showing `{ status: { from, to } }`.
+     */
+    entityStatus<TArgs, TResult = unknown>(params: {
+        entityTable: string
+        entityId: (args: TArgs) => string
+        action: string
+        before?: (ctx: any, args: TArgs) => Promise<unknown> | unknown
+        after: ((args: TArgs, result: TResult) => unknown) | unknown
+        reason?: (args: TArgs) => string | undefined
+    }) {
+        return (args: TArgs) => ({
+            onSuccess: async (callParams: {
+                ctx: any
+                args: TArgs
+                result: TResult
+                requestId: string
+                userId?: string
+                user?: any
+                flags: Record<string, boolean>
+            }): Promise<Omit<AuditLogEntry, 'createdAt'> | null> => {
+                const { ctx, result, requestId, user } = callParams
+
+                const beforeVal = params.before
+                    ? await params.before(ctx, args)
+                    : undefined
+
+                const afterVal =
+                    typeof params.after === 'function'
+                        ? (params.after as (args: TArgs, result: TResult) => unknown)(args, result)
+                        : params.after
+
+                return {
+                    actorId: user?._id,
+                    role: user?.role ?? 'system',
+                    actorRoles: user?.roles ?? (user?.role ? [user.role] : undefined),
+                    action: params.action,
+                    entityTable: params.entityTable,
+                    entityId: params.entityId(args),
+                    beforeJson: beforeVal === undefined ? undefined : JSON.stringify(beforeVal),
+                    afterJson: afterVal === undefined ? undefined : JSON.stringify(afterVal),
+                    diffJson: JSON.stringify({ status: { from: beforeVal, to: afterVal } }),
+                    reason: params.reason ? params.reason(args) : undefined,
+                    requestId,
+                }
+            },
+        })
+    },
+
+    /**
+     * Preset for entity patches (partial updates with full before/after + diff).
+     */
+    entityPatch<TArgs, TResult = unknown>(params: {
+        entityTable: string
+        entityId: (args: TArgs) => string
+        action: string
+        before: (ctx: any, args: TArgs) => Promise<Record<string, unknown>>
+        patch: (args: TArgs, result: TResult) => Record<string, unknown>
+        reason?: (args: TArgs) => string | undefined
+    }) {
+        return (args: TArgs) => ({
+            onSuccess: async (callParams: {
+                ctx: any
+                args: TArgs
+                result: TResult
+                requestId: string
+                userId?: string
+                user?: any
+                flags: Record<string, boolean>
+            }): Promise<Omit<AuditLogEntry, 'createdAt'> | null> => {
+                const { ctx, result, requestId, user } = callParams
+
+                const beforeObj = await params.before(ctx, args)
+                const patchObj = params.patch(args, result)
+                const afterObj = { ...beforeObj, ...patchObj }
+                const diff = computeDiff(beforeObj, afterObj)
+
+                return {
+                    actorId: user?._id,
+                    role: user?.role ?? 'system',
+                    actorRoles: user?.roles ?? (user?.role ? [user.role] : undefined),
+                    action: params.action,
+                    entityTable: params.entityTable,
+                    entityId: params.entityId(args),
+                    beforeJson: JSON.stringify(beforeObj),
+                    afterJson: JSON.stringify(afterObj),
+                    diffJson: JSON.stringify(diff),
+                    reason: params.reason?.(args),
+                    requestId,
+                }
+            },
+        })
+    },
+
+    /**
+     * Preset for simple create/delete actions (no before/after diff needed).
+     */
+    entityAction<TArgs>(params: {
+        entityTable: string
+        entityId: (args: TArgs) => string
+        action: string
+        description?: (args: TArgs) => string | undefined
+        reason?: (args: TArgs) => string | undefined
+    }) {
+        return (_args: TArgs) => ({
+            onSuccess: async (callParams: {
+                ctx: any
+                args: TArgs
+                result: unknown
+                requestId: string
+                userId?: string
+                user?: any
+                flags: Record<string, boolean>
+            }): Promise<Omit<AuditLogEntry, 'createdAt'> | null> => {
+                const { args, requestId, user } = callParams
+
+                return {
+                    actorId: user?._id,
+                    role: user?.role ?? 'system',
+                    actorRoles: user?.roles ?? (user?.role ? [user.role] : undefined),
+                    action: params.action,
+                    entityTable: params.entityTable,
+                    entityId: params.entityId(args),
+                    description: params.description?.(args),
+                    reason: params.reason?.(args),
+                    requestId,
+                }
+            },
+        })
+    },
+}