[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M786DMASM9PXP0NSEZYTHA7Q":3,"skill-same:01M786DMASM9PXP0NSEZYTHA7Q":47},{"skillNo":4,"name":5,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":7,"ownerLogin":8,"ownerAvatarUrl":9,"ownerAccountNo":10,"ownerDisplayName":11,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":15,"categories":16,"keywords":17,"publishedAt":18,"linkOnly":19,"markdownContent":20,"markdownBody":21,"frontMatter":22,"refName":23,"commitSha":24,"skillDirectory":25,"forksCount":26,"repositoryHtmlUrl":27,"repositoryHomepageUrl":28,"ownerHtmlUrl":29,"ownerBlogUrl":30,"ownerDescription":31,"updatedAt":32,"install":33,"resources":46},"01M786DMASM9PXP0NSEZYTHA7Q","ts-module-layout",null,"allanpablo\u002Fforja","allanpablo","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F22358346?v=4","01M786AH79M6N27CC4HZ2AHJTQ","Allan Pablo","01M786AH80CPCTFFMSTRMGEGYF",2,"MIT","https:\u002F\u002Fgithub.com\u002Fallanpablo\u002Fforja\u002Fblob\u002Fmain\u002Ftemplates\u002Fproject\u002Fskills\u002Fts-module-layout\u002FSKILL.md",[],[],"2026-11-15 14:19:17",false,"---\nname: ts-module-layout\ndescription: Use quando organizar ou reorganizar uma base de código TypeScript ou JavaScript (serviços Node, NestJS, bibliotecas, front-ends): avalia a árvore de pastas e o grafo de imports atuais e propõe uma estrutura alinhada aos contextos delimitados, sem ciclos de import, barrel files ou pastas genéricas, com regras de dependência verificáveis e um plano de movimentação incremental.\n---\n\n# Estrutura de Módulos em TypeScript\n\nEm TypeScript o arquivo é o módulo, e a pasta é só uma convenção. Nada impede um arquivo de domínio de importar o cliente do banco, a não ser regras que você escreve e verifica. Uma estrutura organizada por contexto de negócio mantém uma mudança num lugar só. Uma estrutura organizada por camada técnica (`models\u002F`, `services\u002F`, `controllers\u002F`) espalha cada funcionalidade pela árvore inteira, e os barrel files (`index.ts` que reexportam tudo) a transformam numa teia de ciclos.\n\nA saída padrão é uma **avaliação e uma estrutura alvo com um plano de movimentação**. Mova arquivos só quando o usuário pedir.\n\n## Convenções\n\n- Entradas: contextos de `bounded-context-mapping` ou `domain-modeling`; a árvore atual; `package.json`, `tsconfig.json` e o framework em uso.\n- As convenções existentes prevalecem quando funcionam. Proponha uma mudança só para um problema concreto (ciclos, acoplamento, propriedade confusa, builds lentos).\n- A estrutura do framework é respeitada onde ela sustenta algo (módulos NestJS, roteamento `app\u002F` do Next.js), e os contextos são organizados dentro dela.\n- Programas pequenos ficam planos: alguns arquivos em `src\u002F` estão bem até começar a doer.\n- Projetos JavaScript seguem as mesmas regras; os tipos vêm de JSDoc com `checkJs` quando o projeto o usa.\n\n## Avalie primeiro\n\nSomente leitura:\n\n1. `tsc --noEmit` (ou `tsc -b` com project references): o build é a linha de base.\n2. Ciclos: `npx madge --circular --extensions ts,tsx src` (ou `npx dpdm`). Em TS, ciclos compilam e falham em tempo de execução como imports `undefined` ou erros de zona morta temporal.\n3. Quem importa quem: `npx depcruise src --output-type text` ou `madge --image`. Procure arquivos de domínio importando infraestrutura (ORM, clientes HTTP, SDKs, `process.env`).\n4. Barrel files: arquivos `index.ts` que só reexportam. Eles escondem o grafo real de dependências e criam ciclos.\n5. Nomes de pastas: os genéricos (`utils`, `common`, `helpers`, `shared`, `lib`, `types`, `models`, `services`) são um mau sinal.\n6. Código morto e dependências sem uso: `npx knip`.\n7. Formato de módulo: `\"type\"` no `package.json`, `module`\u002F`moduleResolution` no `tsconfig.json`. ESM e CommonJS misturados são um achado por si só.\n\n## Estrutura alvo\n\n```\nsrc\u002F\n  main.ts                     # raiz de composição: config, montagem, start. Sem lógica de negócio.\n  \u003Ccontexto>\u002F                 # um por contexto delimitado, ex.: booking\u002F, billing\u002F\n    domain\u002F                   # entidades, objetos de valor, políticas, interfaces de repositório. TS puro.\n    application\u002F              # casos de uso; depende só do domínio\n    adapters\u002F\n      http\u002F                   # controllers\u002Frotas deste contexto\n      persistence\u002F            # implementa as interfaces de repositório do domínio\n  platform\u002F                   # infraestrutura transversal com comportamento real: db, logging, config\ntest\u002F                         # testes de integração e e2e (os unitários ficam junto do código)\n```\n\nCom NestJS, cada contexto é um módulo Nest (`booking.module.ts`) que monta os próprios providers; `domain\u002F` fica livre de decorators do Nest. Num front-end, a mesma ideia vale como pastas por funcionalidade (`features\u002F\u003Ccontexto>\u002F`), com os componentes básicos de UI num pacote de design system, e não num `components\u002F` guardando tudo.\n\nRegras:\n\n- **Organize por contexto, não por camada.** Divida um contexto em `domain\u002Fapplication\u002Fadapters` só quando ele crescer; um contexto pequeno pode ter três arquivos.\n- **As dependências apontam para dentro.** `domain\u002F` importa só a biblioteca padrão e o próprio contexto. `adapters\u002F` importam o domínio, nunca o contrário. `process.env` é lido em `platform\u002Fconfig` e passado adiante.\n- **As interfaces pertencem a quem as consome.** O domínio declara `interface BookingRepository`; o adaptador de persistência a implementa. A tipagem estrutural torna isso gratuito; não crie uma interface ao lado da sua única implementação \"para testar\".\n- **Os contextos conversam por costuras explícitas:** o serviço de aplicação do outro contexto ou eventos publicados, nunca seus arquivos internos. Respeite as relações do mapa de contextos (uma Camada Anticorrupção é um módulo que traduz).\n- **Sem barrel files** dentro da aplicação. Importe o arquivo que define a coisa. A API pública de um pacote é o campo `exports` do `package.json`, não um `index.ts` que reexporta o mundo.\n- **Sem pastas genéricas.** Um utilitário vai para o módulo que o usa, ou para um módulo com o nome do que ele faz (`money.ts`, `clock.ts`).\n- **Aliases de caminho são ergonomia, não fronteira.** `@booking\u002F*` em `paths` do `tsconfig` não impede um import proibido; uma regra de dependência impede.\n- **Verifique as regras no CI:** regras do `dependency-cruiser`, `eslint-plugin-boundaries` ou `no-restricted-imports` por pasta. Uma regra que não é verificada é uma sugestão.\n- **Um pacote só**, a menos que partes sejam versionadas ou publicadas separadamente. Aí use workspaces (npm\u002Fpnpm) e project references do TypeScript, com cada pacote expondo sua API pelo `exports`.\n- **Um formato de módulo só.** Código novo é ESM (`\"type\": \"module\"`, `module: \"nodenext\"`, imports relativos com extensão `.js`), a menos que o projeto seja CommonJS de propósito.\n\n## Plano de movimentação\n\nCada passo compila e passa nos testes sozinho, para poder ser um commit próprio:\n\n1. Quebre os ciclos primeiro (mova o tipo compartilhado para o módulo dono do conceito, ou inverta com uma interface do lado de quem consome).\n2. Remova os barrel files nos caminhos que você vai mover, apontando os imports para o arquivo que define.\n3. Crie a pasta do contexto e mova os arquivos de domínio.\n4. Mova os adaptadores para trás das interfaces do domínio.\n5. Atualize a raiz de composição (`main.ts` ou o módulo raiz do Nest).\n6. Adicione as regras de dependência ao CI para a estrutura não regredir.\n7. Apague as pastas genéricas que ficaram vazias.\n\nUse a refatoração \"mover arquivo\" do editor (ela reescreve os imports), ou `ts-morph` para movimentações grandes. Rode `tsc --noEmit` e os testes depois de cada passo. Evite localizar-e-substituir manual nos caminhos de import.\n\n## Formato\n\n```\n## Estado atual\n| Problema | Onde | Efeito |\n\n## Árvore alvo\n\u003Cárvore>\n\n## Regras de dependência\n\u003Cimports permitidos entre pastas, e a ferramenta\u002Fconfig que os verifica>\n\n## Plano de movimentação\n| # | Passo | Arquivos afetados | Commit |\n```\n\n## Próximo\n\n- `ts-code-review` verifica se o código novo respeita as regras de dependência.\n- `commit-message`: um commit `refactor` por passo.\n\n## Evite\n\n- `models\u002F`, `services\u002F`, `controllers\u002F`, `utils\u002F` no primeiro nível.\n- Barrel files `index.ts` reexportando uma pasta inteira.\n- Aliases de caminho do `tsconfig` usados como se fossem fronteiras.\n- Arquivos de domínio importando o ORM, o framework HTTP ou `process.env`.\n- Dividir em muitos pacotes de workspace antes de qualquer coisa ser publicada separadamente.\n- Reorganizações de uma vez num commit só.\n","# Estrutura de Módulos em TypeScript\n\nEm TypeScript o arquivo é o módulo, e a pasta é só uma convenção. Nada impede um arquivo de domínio de importar o cliente do banco, a não ser regras que você escreve e verifica. Uma estrutura organizada por contexto de negócio mantém uma mudança num lugar só. Uma estrutura organizada por camada técnica (`models\u002F`, `services\u002F`, `controllers\u002F`) espalha cada funcionalidade pela árvore inteira, e os barrel files (`index.ts` que reexportam tudo) a transformam numa teia de ciclos.\n\nA saída padrão é uma **avaliação e uma estrutura alvo com um plano de movimentação**. Mova arquivos só quando o usuário pedir.\n\n## Convenções\n\n- Entradas: contextos de `bounded-context-mapping` ou `domain-modeling`; a árvore atual; `package.json`, `tsconfig.json` e o framework em uso.\n- As convenções existentes prevalecem quando funcionam. Proponha uma mudança só para um problema concreto (ciclos, acoplamento, propriedade confusa, builds lentos).\n- A estrutura do framework é respeitada onde ela sustenta algo (módulos NestJS, roteamento `app\u002F` do Next.js), e os contextos são organizados dentro dela.\n- Programas pequenos ficam planos: alguns arquivos em `src\u002F` estão bem até começar a doer.\n- Projetos JavaScript seguem as mesmas regras; os tipos vêm de JSDoc com `checkJs` quando o projeto o usa.\n\n## Avalie primeiro\n\nSomente leitura:\n\n1. `tsc --noEmit` (ou `tsc -b` com project references): o build é a linha de base.\n2. Ciclos: `npx madge --circular --extensions ts,tsx src` (ou `npx dpdm`). Em TS, ciclos compilam e falham em tempo de execução como imports `undefined` ou erros de zona morta temporal.\n3. Quem importa quem: `npx depcruise src --output-type text` ou `madge --image`. Procure arquivos de domínio importando infraestrutura (ORM, clientes HTTP, SDKs, `process.env`).\n4. Barrel files: arquivos `index.ts` que só reexportam. Eles escondem o grafo real de dependências e criam ciclos.\n5. Nomes de pastas: os genéricos (`utils`, `common`, `helpers`, `shared`, `lib`, `types`, `models`, `services`) são um mau sinal.\n6. Código morto e dependências sem uso: `npx knip`.\n7. Formato de módulo: `\"type\"` no `package.json`, `module`\u002F`moduleResolution` no `tsconfig.json`. ESM e CommonJS misturados são um achado por si só.\n\n## Estrutura alvo\n\n```\nsrc\u002F\n  main.ts                     # raiz de composição: config, montagem, start. Sem lógica de negócio.\n  \u003Ccontexto>\u002F                 # um por contexto delimitado, ex.: booking\u002F, billing\u002F\n    domain\u002F                   # entidades, objetos de valor, políticas, interfaces de repositório. TS puro.\n    application\u002F              # casos de uso; depende só do domínio\n    adapters\u002F\n      http\u002F                   # controllers\u002Frotas deste contexto\n      persistence\u002F            # implementa as interfaces de repositório do domínio\n  platform\u002F                   # infraestrutura transversal com comportamento real: db, logging, config\ntest\u002F                         # testes de integração e e2e (os unitários ficam junto do código)\n```\n\nCom NestJS, cada contexto é um módulo Nest (`booking.module.ts`) que monta os próprios providers; `domain\u002F` fica livre de decorators do Nest. Num front-end, a mesma ideia vale como pastas por funcionalidade (`features\u002F\u003Ccontexto>\u002F`), com os componentes básicos de UI num pacote de design system, e não num `components\u002F` guardando tudo.\n\nRegras:\n\n- **Organize por contexto, não por camada.** Divida um contexto em `domain\u002Fapplication\u002Fadapters` só quando ele crescer; um contexto pequeno pode ter três arquivos.\n- **As dependências apontam para dentro.** `domain\u002F` importa só a biblioteca padrão e o próprio contexto. `adapters\u002F` importam o domínio, nunca o contrário. `process.env` é lido em `platform\u002Fconfig` e passado adiante.\n- **As interfaces pertencem a quem as consome.** O domínio declara `interface BookingRepository`; o adaptador de persistência a implementa. A tipagem estrutural torna isso gratuito; não crie uma interface ao lado da sua única implementação \"para testar\".\n- **Os contextos conversam por costuras explícitas:** o serviço de aplicação do outro contexto ou eventos publicados, nunca seus arquivos internos. Respeite as relações do mapa de contextos (uma Camada Anticorrupção é um módulo que traduz).\n- **Sem barrel files** dentro da aplicação. Importe o arquivo que define a coisa. A API pública de um pacote é o campo `exports` do `package.json`, não um `index.ts` que reexporta o mundo.\n- **Sem pastas genéricas.** Um utilitário vai para o módulo que o usa, ou para um módulo com o nome do que ele faz (`money.ts`, `clock.ts`).\n- **Aliases de caminho são ergonomia, não fronteira.** `@booking\u002F*` em `paths` do `tsconfig` não impede um import proibido; uma regra de dependência impede.\n- **Verifique as regras no CI:** regras do `dependency-cruiser`, `eslint-plugin-boundaries` ou `no-restricted-imports` por pasta. Uma regra que não é verificada é uma sugestão.\n- **Um pacote só**, a menos que partes sejam versionadas ou publicadas separadamente. Aí use workspaces (npm\u002Fpnpm) e project references do TypeScript, com cada pacote expondo sua API pelo `exports`.\n- **Um formato de módulo só.** Código novo é ESM (`\"type\": \"module\"`, `module: \"nodenext\"`, imports relativos com extensão `.js`), a menos que o projeto seja CommonJS de propósito.\n\n## Plano de movimentação\n\nCada passo compila e passa nos testes sozinho, para poder ser um commit próprio:\n\n1. Quebre os ciclos primeiro (mova o tipo compartilhado para o módulo dono do conceito, ou inverta com uma interface do lado de quem consome).\n2. Remova os barrel files nos caminhos que você vai mover, apontando os imports para o arquivo que define.\n3. Crie a pasta do contexto e mova os arquivos de domínio.\n4. Mova os adaptadores para trás das interfaces do domínio.\n5. Atualize a raiz de composição (`main.ts` ou o módulo raiz do Nest).\n6. Adicione as regras de dependência ao CI para a estrutura não regredir.\n7. Apague as pastas genéricas que ficaram vazias.\n\nUse a refatoração \"mover arquivo\" do editor (ela reescreve os imports), ou `ts-morph` para movimentações grandes. Rode `tsc --noEmit` e os testes depois de cada passo. Evite localizar-e-substituir manual nos caminhos de import.\n\n## Formato\n\n```\n## Estado atual\n| Problema | Onde | Efeito |\n\n## Árvore alvo\n\u003Cárvore>\n\n## Regras de dependência\n\u003Cimports permitidos entre pastas, e a ferramenta\u002Fconfig que os verifica>\n\n## Plano de movimentação\n| # | Passo | Arquivos afetados | Commit |\n```\n\n## Próximo\n\n- `ts-code-review` verifica se o código novo respeita as regras de dependência.\n- `commit-message`: um commit `refactor` por passo.\n\n## Evite\n\n- `models\u002F`, `services\u002F`, `controllers\u002F`, `utils\u002F` no primeiro nível.\n- Barrel files `index.ts` reexportando uma pasta inteira.\n- Aliases de caminho do `tsconfig` usados como se fossem fronteiras.\n- Arquivos de domínio importando o ORM, o framework HTTP ou `process.env`.\n- Dividir em muitos pacotes de workspace antes de qualquer coisa ser publicada separadamente.\n- Reorganizações de uma vez num commit só.\n",{},"main","cfe29d604e93a4c19fd25db4289328f6ec17bb41","templates\u002Fproject\u002Fskills\u002Fts-module-layout",0,"https:\u002F\u002Fgithub.com\u002Fallanpablo\u002Fforja","npmjs.com\u002Fforjajs","https:\u002F\u002Fgithub.com\u002Fallanpablo","www.allanpablo.com.br","Gestor de TI","2026-11-15 05:12:58",{"source":7,"skillName":5,"commands":34,"prompt":44,"zipAvailable":45},[35,38,41],{"tool":36,"command":37},"npx","npx skills add allanpablo\u002Fforja --skill ts-module-layout",{"tool":39,"command":40},"bunx","bunx skills add allanpablo\u002Fforja --skill ts-module-layout",{"tool":42,"command":43},"pnpm","pnpm dlx skills add allanpablo\u002Fforja --skill ts-module-layout","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fallanpablo\u002Fforja\u002Fblob\u002Fmain\u002Ftemplates\u002Fproject\u002Fskills\u002Fts-module-layout\u002FSKILL.md",true,[],[48,54,60,66,72,78],{"skillNo":49,"name":50,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":7,"ownerLogin":8,"ownerAvatarUrl":9,"ownerAccountNo":10,"ownerDisplayName":11,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":51,"categories":52,"keywords":53,"publishedAt":18},"01M786DTCHHV8K0MZMQQA2N81Q","web-performance","https:\u002F\u002Fgithub.com\u002Fallanpablo\u002Fforja\u002Fblob\u002Fmain\u002Ftemplates\u002Fproject\u002Fskills\u002Fweb-performance\u002FSKILL.md",[],[],{"skillNo":55,"name":56,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":7,"ownerLogin":8,"ownerAvatarUrl":9,"ownerAccountNo":10,"ownerDisplayName":11,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":57,"categories":58,"keywords":59,"publishedAt":18},"01M786DQ9FDGFMJTF6WANNJ7QG","ts-testing","https:\u002F\u002Fgithub.com\u002Fallanpablo\u002Fforja\u002Fblob\u002Fmain\u002Ftemplates\u002Fproject\u002Fskills\u002Fts-testing\u002FSKILL.md",[],[],{"skillNo":61,"name":62,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":7,"ownerLogin":8,"ownerAvatarUrl":9,"ownerAccountNo":10,"ownerDisplayName":11,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":63,"categories":64,"keywords":65,"publishedAt":18},"01M786DH4Y3AD551JN35D2R3HY","ts-code-review","https:\u002F\u002Fgithub.com\u002Fallanpablo\u002Fforja\u002Fblob\u002Fmain\u002Ftemplates\u002Fproject\u002Fskills\u002Fts-code-review\u002FSKILL.md",[],[],{"skillNo":67,"name":68,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":7,"ownerLogin":8,"ownerAvatarUrl":9,"ownerAccountNo":10,"ownerDisplayName":11,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":69,"categories":70,"keywords":71,"publishedAt":18},"01M786DF1R7PCK6KB44B34110S","ts-async-patterns","https:\u002F\u002Fgithub.com\u002Fallanpablo\u002Fforja\u002Fblob\u002Fmain\u002Ftemplates\u002Fproject\u002Fskills\u002Fts-async-patterns\u002FSKILL.md",[],[],{"skillNo":73,"name":74,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":7,"ownerLogin":8,"ownerAvatarUrl":9,"ownerAccountNo":10,"ownerDisplayName":11,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":75,"categories":76,"keywords":77,"publishedAt":18},"01M786DDCF8GHQ8KY2X4DGY3XN","threat-modeling","https:\u002F\u002Fgithub.com\u002Fallanpablo\u002Fforja\u002Fblob\u002Fmain\u002Ftemplates\u002Fproject\u002Fskills\u002Fthreat-modeling\u002FSKILL.md",[],[],{"skillNo":79,"name":80,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":7,"ownerLogin":8,"ownerAvatarUrl":9,"ownerAccountNo":10,"ownerDisplayName":11,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":81,"categories":82,"keywords":83,"publishedAt":18},"01M786DBDE38J5471FBVFB1DV8","testing","https:\u002F\u002Fgithub.com\u002Fallanpablo\u002Fforja\u002Fblob\u002Fmain\u002Ftemplates\u002Fproject\u002Fskills\u002Ftesting\u002FSKILL.md",[],[]]