From bc49c0a550aa4d5665dee21818a5ddf4e6a371cd Mon Sep 17 00:00:00 2001 From: CI Agent Date: Thu, 8 Jan 2026 22:25:01 +0000 Subject: [PATCH 1/5] docs: add Copilot instructions and .env.sample for local dev --- .github/copilot-instructions.md | 122 +++++++++++++++++++++++++++ apps/ats/web/.env.sample | 11 +++ apps/mass-payout/backend/.env.sample | 19 +++++ packages/ats/contracts/.env.sample | 21 +++++ 4 files changed, 173 insertions(+) create mode 100644 .github/copilot-instructions.md create mode 100644 apps/mass-payout/backend/.env.sample diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md new file mode 100644 index 000000000..739dcaa11 --- /dev/null +++ b/.github/copilot-instructions.md @@ -0,0 +1,122 @@ +# Instrucciones para agentes Copilot / AI + +Resumen breve +- Monorepo modular para Asset Tokenization Studio (ATS) y Mass Payout. Estructura basada en `npm` workspaces: contratos Solidity, SDKs TypeScript, frontends (React/Vite) y backend (NestJS). + +Objetivo inmediato para el agente +- Proponer cambios que sean conscientes del monorepo: usar los scripts del `package.json` raíz o los scripts por workspace para construir/testear/limpiar. + +Comandos útiles (ejemplos concretos) +- Instalar dependencias y construir todo: `npm ci` → `npm run setup` (usa `package.json` raíz). +- ATS: `npm run ats:build`, `npm run ats:start`, `npm run ats:test`. +- Contratos ATS: en [packages/ats/contracts](packages/ats/contracts) usar `npm run compile`, `npm run test`, `npm run deploy:local` o `npm run deploy:hedera:previewnet`. +- SDK ATS: en [packages/ats/sdk](packages/ats/sdk) usar `npm run build` y `npm run test`. +- Frontend ATS: en [apps/ats/web](apps/ats/web) usar `npm run dev` (Vite) y `npm run build`. +- Mass Payout: use `npm run mass-payout:build` y los scripts por workspace (backend/frontend/contracts/sdk). + +Puntos arquitectónicos importantes +- Diamond pattern en contratos ATS (facets/modularidad). Ver carpeta [packages/ats/contracts/contracts](packages/ats/contracts/contracts) y los scripts en [packages/ats/contracts/scripts](packages/ats/contracts/scripts). +- El SDK (`packages/ats/sdk`) depende de los artefactos/typings de los contratos y expone APIs TypeScript (TypeChain + tsc-alias). +- Frontend ATS (`apps/ats/web`) consume el SDK (`@hashgraph/asset-tokenization-sdk`) como dependencia de workspace. +- Mass Payout separa contratos, SDK y aplicaciones (backend NestJS con PostgreSQL; frontend admin en React). + +> Convención práctica: cambiar solo el paquete afectado y usar los scripts raíz para orquestar builds/tests en workspace. + +Convenciones de desarrollo relevantes +- Versiones/engines: `packages/ats/sdk` exige Node >=18.20.8; comprobar `package.json` del workspace antes de ejecutar localmente. +- Formato y lint: usar `prettier`, `eslint` y `solhint`. Scripts raíz: `npm run lint`, `npm run format`. +- Hooks/CI: `husky` + `lint-staged` están en uso; los commits pueden fallar si no pasan lint staged. +- Tests Solidity: se ejecutan con `hardhat` (scripts definidos en [packages/ats/contracts/package.json](packages/ats/contracts/package.json)). Tests pueden requerir variables de entorno o nodos locales (ver `local:hardhat`). + +Integraciones y puntos de despliegue +- Hedera: Mirror & RPC nodes; WalletConnect y custodian libs (Dfns/Fireblocks) integradas en SDK. +- Deploys: existe un CLI de despliegue en `packages/ats/contracts/scripts/cli` (por ejemplo `standalone.ts`). Preferir los scripts `npm run deploy:*` definidos. + +Recomendaciones concretas para PRs y cambios del agente +- Cambios de contratos: compilar + ejecutar tests unitarios (`npm run ats:contracts:build` y `npm run ats:contracts:test`) antes de proponer cambios. +- Cambios en SDK: ejecutar `npm run ats:sdk:build` y tests (`npm run ats:sdk:test`). Ver `tsconfig` y `tsc-alias` si tocas alias de paths. +- Cambios en frontend: usar `npm run ats:web:dev` para pruebas locales y ejecutar `npm run ats:web:test` para pruebas unitarias. +- No publicar paquetes manualmente: la publicación usa `changesets`; los releases deben seguir las workflows en `.github/workflows`. + +Dónde mirar para ejemplos y patrones +- Arquitectura y flujos generales: [README.md](README.md) +- Scripts y orquestación monorepo: `package.json` (raíz) +- Contratos (Hardhat + scripts): [packages/ats/contracts/package.json](packages/ats/contracts/package.json) +- SDK build/tests: [packages/ats/sdk/package.json](packages/ats/sdk/package.json) +- Frontend DApp: [apps/ats/web/package.json](apps/ats/web/package.json) + +Limitaciones y cosas que NO asumir +- No asumir disponibilidad de nodos Hedera públicos en CI local; revisar `NETWORK` env vars y usar `local:hardhat` para tests que requieran EVM local. +- No publicar paquetes sin `changeset` y aprobación de release workflows. + +¿Necesitas que añada ejemplos de PRs automáticos, comandos de debug o snippets para tests específicos (Hardhat/Jest)? Dime qué prefieres y lo agrego. + +Snippets de depuración (rápido) +- Ejecutar un nodo Hardhat local (en `packages/ats/contracts`) y dejarlo en background: + + ```bash + # desde la raíz del monorepo + npm run ats:contracts:compile && npm --workspace=packages/ats/contracts run local:hardhat + # o ejecutar en background (Linux/mac): + (cd packages/ats/contracts && npx hardhat node) & + ``` + +- Desplegar los contratos a la red local y ver logs: + + ```bash + # despliega usando el CLI compilado (usa NETWORK env var) + NETWORK=local npm run ats:contracts:deploy + # despliegue automático que arranca hardhat node y luego despliega + npm --workspace=packages/ats/contracts run deploy:local:auto + ``` + +- Ejecutar tests Solidity apuntando a un nodo local (si requiere `NETWORK=local`): + + ```bash + # tests unitarios de contratos + npm run ats:contracts:test + # tests de scripts/integración + npm run ats:contracts:test:scripts:integration + ``` + +- Depurar SDK/JS y pruebas Jest (aumentar memoria si hay OOM): + + ```bash + # desde la raíz (usa workspace scripts) + npm run ats:sdk:build + NODE_OPTIONS=--max-old-space-size=16384 npm run ats:sdk:test + ``` + +- Levantar web app en modo dev (Vite) con variables locales: + + ```bash + # crear/editar apps/ats/web/.env.local antes + npm run ats:web:dev + ``` + +- Mass Payout backend (Postgres) — usar `docker-compose` incluido: + + ```bash + # desde apps/mass-payout/backend + docker compose up -d # levanta Postgres y dependencias (ver docker-compose.yml) + npm --workspace=apps/mass-payout/backend run start:dev + ``` + +- SLITHER / análisis estático (contratos): + + ```bash + # usa el script dockerizado definido en packages/ats/contracts/package.json + npm --workspace=packages/ats/contracts run slither + ``` + +- Cobertura y tamaño de contratos: + + ```bash + npm run ats:contracts:test:coverage + npm run ats:contracts:size + ``` + +Notas rápidas +- Asegúrate de copiar/llenar los `.env` apropiados antes de ejecutar (ver `apps/ats/web/.env.local`, `apps/mass-payout/backend/.env`). +- Para reproducir CI localmente usa los scripts `:*:ci` (ej. `npm run ats:test:ci`). +- Si tocas `tsconfig` o alias de paths, ejecutar `tsc-alias` (scripts de build ya lo hacen). diff --git a/apps/ats/web/.env.sample b/apps/ats/web/.env.sample index 303b1aaa4..2184645ca 100644 --- a/apps/ats/web/.env.sample +++ b/apps/ats/web/.env.sample @@ -1,3 +1,14 @@ +# Sample environment variables for local ATS web development +# Copy to .env.local and fill values before running `npm run ats:web:dev` + +VITE_HEDERA_NETWORK=local +VITE_RPC_URL=http://localhost:8545 +VITE_MIRROR_URL=http://localhost:5600 +VITE_RESOLVER_ADDRESS=0x0000000000000000000000000000000000000000 +VITE_FACTORY_ADDRESS=0x0000000000000000000000000000000000000000 +VITE_WALLETCONNECT_PROJECT_ID=your_walletconnect_project_id +VITE_API_URL=http://localhost:3000 +VITE_DEFAULT_CHAIN=hedera # * General REACT_APP_EQUITY_CONFIG_ID='0x0000000000000000000000000000000000000000000000000000000000000001' REACT_APP_EQUITY_CONFIG_VERSION='0' diff --git a/apps/mass-payout/backend/.env.sample b/apps/mass-payout/backend/.env.sample new file mode 100644 index 000000000..7a51b12c6 --- /dev/null +++ b/apps/mass-payout/backend/.env.sample @@ -0,0 +1,19 @@ +# Sample environment variables for Mass Payout backend (Postgres + Hedera) +# Copy to .env and adjust values before starting the backend + +NODE_ENV=development +PORT=3000 + +# Postgres (connection string or individual vars) +DATABASE_URL=postgresql://postgres:password@localhost:5432/mass_payout_db + +# JWT / security +JWT_SECRET=change_this_to_a_secure_value + +# Hedera settings +HEDERA_NETWORK=local +HEDERA_OPERATOR_ID=0.0.XXXX +HEDERA_OPERATOR_KEY=302e020100300506...replace_with_private_key + +# Optional: enable debug/logging +LOG_LEVEL=debug diff --git a/packages/ats/contracts/.env.sample b/packages/ats/contracts/.env.sample index 2200dcd7d..950840916 100644 --- a/packages/ats/contracts/.env.sample +++ b/packages/ats/contracts/.env.sample @@ -1,3 +1,24 @@ +# Sample environment for contracts (Hardhat / deployment) +# Copy to .env or export variables before running `npm run deploy*` or `npm run local:hardhat` + +# NETWORK accepted values used by scripts: local, hedera-local, hedera-previewnet, hedera-testnet, hedera-mainnet +NETWORK=local + +# Hardhat / RPC +HARDHAT_HOST=127.0.0.1 +HARDHAT_PORT=8545 +HARDHAT_URL=http://$HARDHAT_HOST:$HARDHAT_PORT + +# Operator / deployer account (replace with local test key when using hardhat node) +DEPLOYER_PRIVATE_KEY=0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa +DEPLOYER_ADDRESS=0x0000000000000000000000000000000000000000 + +# Hedera-specific (used by deployment scripts when NETWORK is hedra-*) +HEDERA_OPERATOR_ID=0.0.XXXX +HEDERA_OPERATOR_KEY=302e020100300506...replace_with_private_key + +# Optional: enable verbose logging for deployment scripts +LOG_LEVEL=debug # * Accounts and Keys # Private keys in RAW Format (Not DER) From bb65ea94c49418d8b0765fd2acd9a3e0fa743f3f Mon Sep 17 00:00:00 2001 From: CI Agent Date: Thu, 8 Jan 2026 22:29:03 +0000 Subject: [PATCH 2/5] docs: add PR template + CI checklist to copilot instructions --- .github/copilot-instructions.md | 31 +++++++++++++++++++++++++++++++ 1 file changed, 31 insertions(+) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 739dcaa11..b9177d9f2 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -120,3 +120,34 @@ Notas rápidas - Asegúrate de copiar/llenar los `.env` apropiados antes de ejecutar (ver `apps/ats/web/.env.local`, `apps/mass-payout/backend/.env`). - Para reproducir CI localmente usa los scripts `:*:ci` (ej. `npm run ats:test:ci`). - Si tocas `tsconfig` o alias de paths, ejecutar `tsc-alias` (scripts de build ya lo hacen). + +Plantillas de PR y flujo de revisión +- Formato mínimo de título: `type(scope): short description` (ej. `docs(copilot): add instructions and env samples`). +- Ejemplo de cuerpo de PR (copiar/pegar): + + ``` + Resumen: Añade `.github/copilot-instructions.md` y `.env.sample` para desarrollo local. + + Cambios principales: + - .github/copilot-instructions.md: guía para agentes AI + - apps/ats/web/.env.sample: variables de ejemplo + - apps/mass-payout/backend/.env.sample: variables de ejemplo + - packages/ats/contracts/.env.sample: variables de ejemplo + + Checklist (antes de pedir review): + - [ ] `npm ci` y `npm run ats:build` pasan localmente donde aplica + - [ ] `npm run ats:contracts:test` pasa (o marcar si requiere infra) + - [ ] `npm run lint` y `npm run format:check` pasan + - [ ] Añadido `changeset` si el cambio afecta paquetes publicados + ``` + +- Verificaciones CI esperadas (GitHub Actions): + - `ats/tests` — corre tests y lint de `packages/ats/*` y `apps/ats/*`. + - `mass-payout/tests` — corre tests y lint de `packages/mass-payout/*` y `apps/mass-payout/*`. + - `format/lint` — comprobación global de Prettier/ESLint. + +- Flujo de revisión recomendado para agentes: + - Ejecutar localmente los scripts relevantes (`npm run ats:contracts:test`, `npm run ats:sdk:test`, `npm run ats:web:test`). + - Añadir `changeset` si se modifica código publicado; no publicar manualmente. + - Pedir review a los propietarios de los paquetes (mentionar `@hashgraph/maintainers` o los responsables en el OWNERS file si existe). + From 586fef024c164c13ff09a87083f66c7dbfbd07a6 Mon Sep 17 00:00:00 2001 From: CI Agent Date: Thu, 8 Jan 2026 22:29:56 +0000 Subject: [PATCH 3/5] chore(docs): add PULL_REQUEST_TEMPLATE.md --- .github/PULL_REQUEST_TEMPLATE.md | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) create mode 100644 .github/PULL_REQUEST_TEMPLATE.md diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 000000000..bc02ebcd7 --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,24 @@ +## Título +Usar el formato: `type(scope): breve descripción` (ej. `docs(copilot): add instructions and env samples`). + +## Resumen +Describa en una o dos frases qué cambia y por qué. + +## Cambios principales +- Breve lista con los archivos/funcionalidades modificadas. + +## Checklist antes de pedir review +- [ ] `npm ci` y `npm run ats:build` pasan donde aplica. +- [ ] Tests relevantes pasan localmente (`npm run ats:contracts:test`, `npm run ats:sdk:test`, `npm run ats:web:test`). +- [ ] `npm run lint` y `npm run format:check` pasan. +- [ ] Añadido `changeset` si el cambio afecta paquetes publicados. + +## Notas de despliegue / entorno +Indicar si requiere pasos especiales (migraciones, variables de entorno, nodos locales). Ejemplo: + +``` +NETWORK=local npm run ats:contracts:deploy +``` + +## Revisor sugerido +Mencionar responsables del paquete o `@hashgraph/maintainers` según corresponda. From 28b403d3c13c47c6c26eae4e9af99a76b579f382 Mon Sep 17 00:00:00 2001 From: CI Agent Date: Thu, 8 Jan 2026 22:31:32 +0000 Subject: [PATCH 4/5] docs: link copilot instructions from README --- README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/README.md b/README.md index f805e4fe2..ecff9a594 100644 --- a/README.md +++ b/README.md @@ -225,6 +225,8 @@ Tests are automatically triggered only when relevant files are modified, improvi If you have a question on how to use the product, please see our [support guide](https://github.com/hashgraph/.github/blob/main/SUPPORT.md). +- **Instrucciones para agentes AI:** `/.github/copilot-instructions.md` contiene guías y comandos útiles para editar/ejecutar el monorepo. + ## Contributing Contributions are welcome. Please see the From f245e6ae311611720fc17c276efaa5bad0f4e8b1 Mon Sep 17 00:00:00 2001 From: CI Agent Date: Thu, 8 Jan 2026 22:34:42 +0000 Subject: [PATCH 5/5] chore(docs): add example changeset for copilot instructions --- .changeset/example-copilot-instructions.md | 24 ++++++++++++++++++++++ 1 file changed, 24 insertions(+) create mode 100644 .changeset/example-copilot-instructions.md diff --git a/.changeset/example-copilot-instructions.md b/.changeset/example-copilot-instructions.md new file mode 100644 index 000000000..04572002f --- /dev/null +++ b/.changeset/example-copilot-instructions.md @@ -0,0 +1,24 @@ +--- +# Example changeset for documentation-only changes +# +# This file is an example showing how to create a changeset when a change +# affects one or more packages. For documentation-only changes you normally +# DO NOT need a changeset; create one only if your change also modifies +# published package code or types. + +# Example frontmatter for actual package releases (uncomment and edit when needed): +# --- +# '@hashgraph/asset-tokenization-sdk': patch +# '@hashgraph/asset-tokenization-contracts': patch +# --- + +Docs: add Copilot instructions and .env.sample files for local development. + +Run locally to create a real changeset (interactive): + +```bash +npx changeset +``` + +Or create a file in `.changeset/*.md` with the frontmatter above and a short +description. See https://github.com/changesets/changesets for details.