@pasosdejesus/m 0.15.0

package/package.json

@@ -0,0 +1,223 @@
+{
+  "name": "@pasosdejesus/m",
+  "version": "0.15.0",
+  "description": "Motor para crear y gestionar proyectos al estilo Pasos de Jesus.",
+  "author": "",
+  "license": "ISC",
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "dist/index.js",
+  "types": "./dist/index.d.ts",
+  "type": "module",
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./dist/*": {
+      "import": "./dist/*",
+      "types": "./dist/*.d.ts"
+    },
+    "./plugin": {
+      "import": "./dist/plugin.js",
+      "types": "./dist/plugin.d.ts"
+    },
+    "./test-utils": {
+      "import": "./dist/test-utils/index.js",
+      "types": "./dist/test-utils/index.d.ts"
+    },
+    "./test-utils/*": {
+      "import": "./dist/test-utils/*.js",
+      "types": "./dist/test-utils/*.d.ts"
+    },
+    "./i18n": {
+      "import": "./dist/i18n/index.js",
+      "types": "./dist/i18n/index.d.ts"
+    },
+    "./debug": {
+      "import": "./dist/debug/index.js",
+      "types": "./dist/debug/index.d.ts"
+    },
+    "./wba": {
+      "import": "./dist/wba/index.js",
+      "types": "./dist/wba/index.d.ts"
+    },
+    "./wba/routes": {
+      "import": "./dist/wba/routes/index.js",
+      "types": "./dist/wba/routes/index.d.ts"
+    },
+    "./wba/routes/*": {
+      "import": "./dist/wba/routes/*.js",
+      "types": "./dist/wba/routes/*.d.ts"
+    },
+    "./shadcn-components/ui/*": {
+      "import": "./dist/shadcn_components/ui/*.js",
+      "types": "./dist/shadcn_components/ui/*.d.ts"
+    },
+    "./shadcn-components/cn": {
+      "import": "./dist/shadcn_components/cn.js",
+      "types": "./dist/shadcn_components/cn.d.ts"
+    },
+    "./blockchain": {
+      "import": "./dist/blockchain/index.js",
+      "types": "./dist/blockchain/index.d.ts"
+    },
+    "./blockchain/deployments": {
+      "import": "./dist/blockchain/deployments.js",
+      "types": "./dist/blockchain/deployments.d.ts"
+    },
+    "./blockchain/credentials": {
+      "import": "./dist/blockchain/credentials.js",
+      "types": "./dist/blockchain/credentials.d.ts"
+    },
+    "./blockchain/admin-credentials": {
+      "import": "./dist/blockchain/admin-credentials.js",
+      "types": "./dist/blockchain/admin-credentials.d.ts"
+    },
+    "./blockchain/credential-images": {
+      "import": "./dist/blockchain/credential-images.js",
+      "types": "./dist/blockchain/credential-images.d.ts"
+    },
+    "./blockchain/credential-cache": {
+      "import": "./dist/blockchain/credential-cache.js",
+      "types": "./dist/blockchain/credential-cache.d.ts"
+    },
+    "./blockchain/ecosystem-addresses": {
+      "import": "./dist/blockchain/ecosystem-addresses.js",
+      "types": "./dist/blockchain/ecosystem-addresses.d.ts"
+    },
+    "./blockchain/slearn-info": {
+      "import": "./dist/blockchain/SlearnInfo.js",
+      "types": "./dist/blockchain/SlearnInfo.d.ts"
+    },
+    "./m": {
+      "import": "./dist/m.js",
+      "types": "./dist/m.d.ts"
+    },
+    "./e2e": {
+      "import": "./dist/e2e/index.js",
+      "types": "./dist/e2e/index.d.ts"
+    }
+  },
+  "bin": {
+    "m": "dist/m.js"
+  },
+  "files": [
+    "CHANGELOG.md",
+    "dist",
+    "doc",
+    "src/tasks/README.md",
+    "src/util/README.md",
+    "src/wba/README.md",
+    "src/i18n/README.md",
+    "src/debug/README.md",
+    "src/shadcn_components/README.md",
+    "src/test-utils/README.md",
+    "src/blockchain/README.md",
+    "src/e2e/README.md"
+  ],
+  "dependencies": {
+    "dotenv": "^17.4.2",
+    "execa": "^9.6.1",
+    "glob": "^13.0.6",
+    "picocolors": "^1.1.1"
+  },
+  "optionalDependencies": {
+    "@pasosdejesus/edr": "0.1.0",
+    "@pasosdejesus/contract-test": "0.1.0"
+  },
+  "devDependencies": {
+    "@radix-ui/react-accordion": "^1.2.12",
+    "@radix-ui/react-alert-dialog": "^1.1.15",
+    "@radix-ui/react-avatar": "^1.1.11",
+    "@radix-ui/react-checkbox": "^1.3.3",
+    "@radix-ui/react-dialog": "^1.1.15",
+    "@radix-ui/react-dropdown-menu": "^2.1.16",
+    "@radix-ui/react-label": "^2.1.8",
+    "@radix-ui/react-menubar": "^1.1.16",
+    "@radix-ui/react-popover": "^1.1.15",
+    "@radix-ui/react-progress": "^1.1.8",
+    "@radix-ui/react-radio-group": "^1.3.8",
+    "@radix-ui/react-scroll-area": "^1.2.10",
+    "@radix-ui/react-select": "^2.2.6",
+    "@radix-ui/react-separator": "^1.1.8",
+    "@radix-ui/react-slider": "^1.3.6",
+    "@radix-ui/react-slot": "^1.2.4",
+    "@radix-ui/react-switch": "^1.2.6",
+    "@radix-ui/react-tabs": "^1.1.13",
+    "@radix-ui/react-toast": "^1.2.15",
+    "@radix-ui/react-tooltip": "^1.2.8",
+    "@remix-project/remix-lib": "link:../remix-project/libs/remix-lib",
+    "@remix-project/remix-simulator": "link:../remix-project/libs/remix-simulator",
+    "@testing-library/jest-dom": "^6.9.1",
+    "@testing-library/react": "^16.3.2",
+    "@types/node": "^20.19.41",
+    "@types/react": "^19.2.15",
+    "@types/react-dom": "^19.2.3",
+    "autoprefixer": "^10.5.0",
+    "class-variance-authority": "^0.7.1",
+    "clsx": "^2.1.1",
+    "jsdom": "^29.1.1",
+    "kysely": "^0.27.6",
+    "kysely-codegen": "^0.20.0",
+    "kysely-ctl": "^0.21.0",
+    "lucide-react": "^1.16.0",
+    "next": "^15.5.21",
+    "next-auth": "^4.24.14",
+    "pg": "^8.21.0",
+    "postcss": "^8.5.15",
+    "react": "^19.2.8",
+    "react-dom": "^19.2.8",
+    "react-hook-form": "^7.76.1",
+    "siwe": "^2.3.2",
+    "tailwind-merge": "^3.6.0",
+    "tailwindcss": "^4.3.0",
+    "typescript": "^5.9.3",
+    "viem": "^2.55.0",
+    "vitest": "2.1.9",
+    "wagmi": "^2.19.5"
+  },
+  "optionalPeerDependencies": {
+    "@radix-ui/react-accordion": "^1.2.12",
+    "@radix-ui/react-alert-dialog": "^1.1.15",
+    "@radix-ui/react-avatar": "^1.1.11",
+    "@radix-ui/react-checkbox": "^1.3.3",
+    "@radix-ui/react-dialog": "^1.1.15",
+    "@radix-ui/react-dropdown-menu": "^2.1.16",
+    "@radix-ui/react-label": "^2.1.8",
+    "@radix-ui/react-menubar": "^1.1.16",
+    "@radix-ui/react-popover": "^1.1.15",
+    "@radix-ui/react-progress": "^1.1.8",
+    "@radix-ui/react-radio-group": "^1.3.8",
+    "@radix-ui/react-scroll-area": "^1.2.10",
+    "@radix-ui/react-select": "^2.2.6",
+    "@radix-ui/react-separator": "^1.1.8",
+    "@radix-ui/react-slider": "^1.3.6",
+    "@radix-ui/react-slot": "^1.2.4",
+    "@radix-ui/react-switch": "^1.2.6",
+    "@radix-ui/react-tabs": "^1.1.13",
+    "@radix-ui/react-toast": "^1.2.15",
+    "@radix-ui/react-tooltip": "^1.2.8",
+    "@testing-library/react": "^16.0.0",
+    "class-variance-authority": "^0.7.1",
+    "clsx": "^2.1.1",
+    "lucide-react": "^0.525.0",
+    "tailwind-merge": "^3.5.0",
+    "viem": "^2.51.0",
+    "next-auth": "^4.0.0",
+    "wagmi": "^2.0.0",
+    "siwe": "^2.1.0",
+    "kysely": "^0.27.0",
+    "pg": "^8.11.0",
+    "react-hook-form": "^7.0.0"
+  },
+  "scripts": {
+    "build": "rm -rf dist && npx tsc && perl -pi -e 'print \"#!/usr/bin/env node\\n\" if $. == 1' dist/m.js && mkdir -p dist/templates dist/blockchain && cp -R templates/* dist/templates/",
+    "start": "node dist/m.js m:create",
+    "test": "npx vitest run",
+    "typecheck": "tsc --noEmit",
+    "postinstall": "echo Instalación completada"
+  }
+}

package/src/blockchain/README.md

@@ -0,0 +1,80 @@
+# Blockchain — Deployments (`@pasosdejesus/m/blockchain`)
+
+> "For the Lord loves justice" (Psalm 37:28)
+
+Shared deployment address resolution for Hardhat contract deployments.
+
+> ⚠️ **Monorepo v0.15.0**: Los módulos de credenciales, admin, imágenes, cache,
+> ecosystem-addresses y slearn-info se movieron a `@pasosdejesus/mpdj/blockchain/*`.
+> Este archivo solo documenta `deployments` que permanece en `@pasosdejesus/m`.
+> Ver [`packages/mpdj/src/blockchain/`](../../../mpdj/src/blockchain/) para los demás.
+
+## Exports
+
+### Deployments (`@pasosdejesus/m/blockchain/deployments`)
+
+| Export | Type | Purpose |
+|--------|------|---------|
+| `readDeployment(network, deploymentsDir, opts?)` | function | Reads deployment JSON. `opts: { contract?, version? }` enables hierarchical path `{contract}/{version}/{network}.json` (falls back to flat `{network}.json`). |
+| `getContractAddress(network, envVar, deploymentsDir, opts?)` | function | Address from deployment or env fallback |
+| `getCeloCredentialsAddress(deploymentsDir, opts?)` | function | Celo address helper |
+| `getBaseCredentialsAddress(deploymentsDir, opts?)` | function | Base address helper |
+
+## Usage
+
+```typescript
+import {
+  getCeloCredentialsAddress,
+  getContractAddress,
+  readDeployment,
+} from '@pasosdejesus/m/blockchain/deployments'
+import path from 'path'
+
+const deploymentsDir = path.join(process.cwd(), '..', 'hardhat', 'deployments', 'PasosDeJesusCredentials')
+const addr = getCeloCredentialsAddress(deploymentsDir)
+
+// Read a specific deployment
+const deployment = readDeployment('celoSepolia', deploymentsDir, { contract: 'PasosDeJesusCredentials', version: 'v1' })
+
+// Get address with env fallback
+const usdt = getContractAddress('celo', 'NEXT_PUBLIC_USDT_ADDRESS', deploymentsDir, { contract: 'USDT' })
+```
+
+## Architecture
+
+```
+┌──────────────────────────────────────────────────────┐
+│  Project (sivel.xyz / learn.tg)                      │
+│                                                      │
+│  apps/hardhat/deployments/                           │
+│    └── *.json (deployment addresses)                │
+│                                                      │
+│  lib/deployments.ts                                  │
+│    └── re-exports from @pasosdejesus/m/blockchain   │
+│        /deployments with local paths                 │
+└──────────────────────────────────────────────────────┘
+```
+
+## Módulos movidos a `@pasosdejesus/mpdj`
+
+Los siguientes módulos eran parte de `@pasosdejesus/m/blockchain` antes de v0.15.0.
+Ahora están en `@pasosdejesus/mpdj/blockchain/*`:
+
+| Módulo | Nueva ruta |
+|--------|-----------|
+| Credentials (mint, query) | `@pasosdejesus/mpdj/blockchain` |
+| Admin (grant/revoke roles) | `@pasosdejesus/mpdj/blockchain/admin-credentials` |
+| Credential images (SVG+PNG) | `@pasosdejesus/mpdj/blockchain/credential-images` |
+| Credential cache (DB metadata) | `@pasosdejesus/mpdj/blockchain/credential-cache` |
+| Ecosystem addresses | `@pasosdejesus/mpdj/blockchain/ecosystem-addresses` |
+| SlearnInfo (React component) | `@pasosdejesus/mpdj/blockchain/slearn-info` |
+
+Para migrar imports existentes:
+
+```diff
+- import { mintCredentialWithRetry } from '@pasosdejesus/m/blockchain'
++ import { mintCredentialWithRetry } from '@pasosdejesus/mpdj/blockchain'
+
+- import { SLEARN_ADDRESSES } from '@pasosdejesus/m/blockchain/ecosystem-addresses'
++ import { SLEARN_ADDRESSES } from '@pasosdejesus/mpdj/blockchain/ecosystem-addresses'
+```

package/src/debug/README.md

@@ -0,0 +1,94 @@
+# Debug Console — `@pasosdejesus/m/debug`
+
+> *"Y todo lo que hagáis, hacedlo de corazón, como para el Señor y no para los hombres"* (Colosenses 3:23)
+
+Floating debug console for MiniPay and embedded browsers. Displays real-time logs
+inside the application without needing browser DevTools.
+
+## Exports
+
+| Export | Type | Purpose |
+|--------|------|---------|
+| `Logger` | class | Logging engine — singleton, buffers 500 entries, writes to `console.*` |
+| `logger` | instance | Pre-instantiated singleton |
+| `useLogger` | hook (`'use client'`) | React hook — returns `{ logs, logger, isEnabled }` |
+| `DebugConsole` | component (`'use client'`) | Floating UI — <kbd>&gt;_</kbd> button → log viewer |
+| `safeStringify` | function | Serializes objects safely (circular references, Errors, truncation) |
+| `debugLog` | function | `console.log` with `[DEBUG]` prefix and safe serialization |
+
+## Usage
+
+### 1. Render the console in your root layout
+
+```tsx
+import { DebugConsole } from '@pasosdejesus/m/debug'
+
+export default function ClientLayout({ children }) {
+  return (
+    <>
+      {children}
+      <DebugConsole />
+    </>
+  )
+}
+```
+
+The component renders `null` when disabled — no performance impact.
+
+### 2. Write logs from anywhere
+
+```typescript
+import { logger } from '@pasosdejesus/m/debug'
+
+logger.info('Loading data...', 'MyModule')
+logger.success('Data loaded', 'MyModule')
+logger.error('Failed to fetch', 'MyModule')
+logger.warning('Retrying...', 'MyModule')
+```
+
+The second argument (`source`) groups logs by module in the console UI.
+
+### 3. Enable the console
+
+| Method | How |
+|--------|-----|
+| **URL parameter** | Add `?debug=1` to the URL |
+| **Environment variable** | Set `NEXT_PUBLIC_M_DEBUGGER_CONSOLE=1` at build time |
+
+## Activate via URL (recommended)
+
+```
+https://example.com/page?debug=1
+```
+
+In all cases, logs are always written to `console.log`/`console.error` via
+browser DevTools regardless of the floating console state.
+
+## Architecture
+
+```
+ClientLayout
+  └── <DebugConsole />          ← renders always (returns null when disabled)
+        └── useLogger()         ← subscribes to Logger singleton
+
+Any component/module            ← writes via
+  └── logger.info('msg')        → Logger singleton → console.log (always)
+                                                     → subscribers (debug UI)
+```
+
+## FAQ
+
+### Why doesn't the console appear?
+
+- Make sure the URL has `?debug=1`
+- Restart the app
+
+### Are logs persisted?
+
+No. Logs are volatile (buffer up to 500 entries). Use the **copy** button (📋)
+before closing to preserve them.
+
+### Can I use it on desktop?
+
+Yes. On desktop you can also use F12 DevTools — the Logger writes to
+`console.log` regardless of the floating console.

package/src/e2e/README.md

@@ -0,0 +1,105 @@
+# @pasosdejesus/m/e2e
+
+E2E test helpers for Puppeteer + SIWE on OpenBSD/adJ.
+
+## Quick Start
+
+```bash
+# In your project
+pnpm add -D puppeteer-core
+mkdir -p e2e/specs e2e/smoke
+```
+
+```js
+// e2e/specs/my-test.spec.mjs
+import {
+  initTestEnv, launchBrowser, newPage,
+  resetFailures, ok, fail, summary,
+  simulateSIWE, checkSessionFull,
+  waitForText, short,
+} from '@pasosdejesus/m/e2e'
+
+const env = await initTestEnv()
+const browser = await launchBrowser(env.headless)
+const page = await newPage(browser, env.account.address, env.timeout)
+
+await page.goto(`${env.base}/en`, { waitUntil: 'domcontentloaded' })
+await simulateSIWE(page, env)
+ok('SIWE completed')
+
+await browser.close()
+const failures = summary(performance.now())
+process.exit(failures > 0 ? 1 : 0)
+```
+
+Run:
+```bash
+CHROME_PATH=/usr/local/bin/chromium IPDES=learn.tg node e2e/specs/my-test.spec.mjs
+```
+
+Or via CLI:
+```bash
+./bin/m test:e2e my-test
+./bin/m test:e2e --smoke          # HTTP-only, no Chrome
+./bin/m test:e2e --grep session   # Filter by name
+```
+
+## API
+
+### Assertions
+```ts
+ok(msg: string)            // ✅ success
+fail(msg: string)           // ❌ failure (increments counter)
+resetFailures()             // Reset counter
+summary(t0: number): number // Print summary, return failure count
+```
+
+### Environment
+```ts
+await initTestEnv(): E2EEnv  // { base, timeout, account, chainId, headless, ... }
+short(addr: string): string  // Truncate address to 10 chars + ...
+```
+
+### Browser
+```ts
+findChrome(): string
+launchBrowser(headless?: boolean): Promise<E2EBrowser>
+newPage(browser, address, timeout?): Promise<E2EPage>
+newIncognitoContext(browser): Promise<E2EBrowserContext>
+newIncognitoPage(ctx, address, timeout?): Promise<E2EPage>  // with mock auto-injected
+clearBrowserCache(page): Promise<void>
+```
+
+### SIWE
+```ts
+simulateSIWE(page, params): Promise<boolean>
+// params: { account, host, domainPort, base, chainId, statement? }
+checkSessionFull(page): Promise<boolean>
+checkPartialLogin(page): Promise<boolean>   // detect "Partial login" guard message in DOM
+```
+
+### Navigation
+```ts
+safeNavigate(page, link, hrefFallback?): Promise<void>
+waitForText(page, text, maxSeconds?): Promise<boolean>
+```
+
+### Wallet Mock
+```ts
+ethereumMockCode({ address, chainId? }): string
+eip6963MockCode({ address, chainId?, walletName? }): string  // wagmi-compatible
+injectEIP6963(page, { address, chainId?, walletName? }): Promise<void>
+```
+
+Use `eip6963MockCode` or `injectEIP6963` when tests need `useAccount()`, `useWalletClient()`,
+or `usePublicClient()` from wagmi. Pass `useEIP6963: true` to `newPage()` or `newIncognitoPage()`.
+
+```js
+// Spec with wagmi support
+const page = await newPage(browser, address, timeout, true)
+// GoodDollarClaimButton, wallet interactions now work
+```
+
+## Environment Variables
+
+See [doc/e2e.md](../../../../doc/e2e.md) for full reference.

package/src/i18n/README.md

@@ -0,0 +1,143 @@
+# `@pasosdejesus/m/i18n` — Zero-Dependency Internationalization
+
+Framework-free translations for Next.js apps. Pure TypeScript objects, no i18n library.
+
+## Exports
+
+| Export | Location | Dependencies | Use in |
+|--------|----------|-------------|--------|
+| `createTranslator` | `createTranslator.ts` | None | Server components, pure functions, client components |
+| `TranslationSet` | `types.ts` | None | Type definitions |
+| `LocaleStrings` | `types.ts` | None | Type definitions |
+
+> **Note:** `useTranslation` (React hook) is **not** included in this package
+> to avoid a hard dependency on `next/navigation`. Each project creates its
+> own thin wrapper — see "Client component" example below.
+
+## Usage
+
+### 1. Define translations
+
+```ts
+// In your component or page
+const localT = {
+  en: { hello: 'Hello', greeting: 'Hello {{0}}' },
+  es: { hello: 'Hola', greeting: 'Hola {{0}}' },
+}
+```
+
+### 2a. Client component (with `useTranslation` hook)
+
+Each project creates its own thin wrapper hook:
+
+```tsx
+// hooks/useTranslation.ts
+'use client'
+import { useParams } from 'next/navigation'
+import { useMemo } from 'react'
+import { createTranslator } from '@pasosdejesus/m/i18n'
+import type { TranslationSet } from '@pasosdejesus/m/i18n'
+import commonTranslations from '@/lib/i18n/common'
+
+export function useTranslation(
+  translations: TranslationSet,
+  paramName: string = 'locale'
+) {
+  const params = useParams()
+  const locale = ((params?.[paramName] as string) || 'en')
+  const t = useMemo(
+    () => createTranslator(locale, translations, commonTranslations),
+    [locale, translations]
+  )
+  return { t, locale }
+}
+```
+
+Then in any component:
+
+```tsx
+'use client'
+import { useTranslation } from '@/hooks/useTranslation'
+
+const localT = {
+  en: { hello: 'Hello' },
+  es: { hello: 'Hola' },
+}
+
+export function MyComponent() {
+  const { t } = useTranslation(localT)
+  return <h1>{t('hello')}</h1>
+}
+```
+
+### 2b. Server component
+
+```tsx
+import { createTranslator } from '@pasosdejesus/m/i18n'
+
+const localT = {
+  en: { title: 'Hello' },
+  es: { title: 'Hola' },
+}
+
+export default async function Page({ params }: { params: { locale: string } }) {
+  const { locale } = await params
+  const t = createTranslator(locale, localT)
+  return <h1>{t('title')}</h1>
+}
+```
+
+### 3. Common translations (shared across the app)
+
+```ts
+// lib/i18n/common.ts
+import type { TranslationSet } from '@pasosdejesus/m/i18n'
+
+const common: TranslationSet = {
+  en: { save: 'Save', cancel: 'Cancel' },
+  es: { save: 'Guardar', cancel: 'Cancelar' },
+}
+export default common
+```
+
+Pass `common` to `createTranslator` (server):
+
+```tsx
+import { createTranslator } from '@pasosdejesus/m/i18n'
+import common from '@/lib/i18n/common'
+
+const t = createTranslator(locale, localT, common)
+t('save') // → 'Guardar' (from common[es])
+```
+
+For client components, the project's `useTranslation` hook injects `commonTranslations`
+automatically (see 2a), so no extra import is needed:
+
+### Fallback Resolution Order
+
+1. `translations[locale]`
+2. `translations['en']`
+3. `common[locale]` (if provided)
+4. `common['en']` (if provided)
+5. The raw key
+
+### Interpolation
+
+Use `{{0}}`, `{{1}}`, etc. as placeholders:
+
+```ts
+const localT = {
+  en: { greeting: 'Hello {{0}}', welcome: 'Welcome {{0}}, you have {{1}} messages' },
+  es: { greeting: 'Hola {{0}}', welcome: 'Bienvenido {{0}}, tienes {{1}} mensajes' },
+}
+
+const t = createTranslator('es', localT)
+t('greeting', 'Mundo')   // → 'Hola Mundo'
+
+const tEn = createTranslator('en', localT)
+tEn('welcome', 'John', '5') // → 'Welcome John, you have 5 messages'
+```
+
+## Why no i18n library?
+
+Traditional i18n libraries (`next-i18next`, `next-intl`) have shown compatibility or performance issues on **OpenBSD/adJ**. Pure TypeScript objects give maximum performance, zero external dependencies, and full type safety.