LIT

LIT e um package manager experimental em Node.js com foco em cache global, linking, integridade e compatibilidade progressiva com o ecossistema npm. A instalacao trabalha a partir do diretório atual do terminal, o que permite usar a CLI tanto neste repositório quanto em workspaces temporários ou outros projetos.

Importante: a arquitetura abaixo ja implementa install real com bridge do npm, store global, dependencias recursivas, lockfile com hash, suporte basico a .npmrc, node_modules/.bin para pacotes top-level e benchmark local. Ainda nao existe suporte completo a peer dependencies, optional dependencies e hoisting avancado no estilo npm/pnpm.

Filosofia

• Zero copia desnecessaria de pacotes
• Store global em ~/.lit/store
• Links em ./packages e ./node_modules
• Shims em ./node_modules/.bin para CLIs top-level
• Fallback automatico para o npm registry
• Suporte basico a registry e @scope:registry via .npmrc
• Resolucao recursiva de dependencias
• Integridade registrada no lockfile
• Benchmark reproducivel no repositorio

Estrutura

lit/
├── benchmarks/
│   └── compare-install.js
├── bin/
│   └── lit.js
├── src/
│   ├── commands/
│   │   ├── info.js
│   │   ├── install.js
│   │   ├── list.js
│   │   ├── remove.js
│   │   └── update.js
│   ├── installer/
│   │   ├── cache.js
│   │   ├── download.js
│   │   ├── extract.js
│   │   ├── graph.js
│   │   ├── link.js
│   │   └── storeIndex.js
│   ├── registry/
│   │   ├── litRegistry.js
│   │   └── npmRegistry.js
│   ├── utils/
│   │   ├── file.js
│   │   ├── integrity.js
│   │   ├── logger.js
│   │   ├── path.js
│   │   └── semver.js
│   └── config.js
├── examples/
│   └── hello-world.js
├── packages/
├── lit-lock.json
├── lit-registry.json
├── package.json
└── README.md

Como rodar

node bin/lit.js --help
node bin/lit.js install hello-world
node bin/lit.js install debug
node bin/lit.js info debug

Se quiser usar o comando globalmente durante o desenvolvimento:

npm link
lit install debug

Comandos

• lit install <pkg...>
• lit add <pkg...>
• lit i <pkg...>
• lit remove <pkg...>
• lit rm <pkg...>
• lit update <pkg...>
• lit list
• lit info <pkg>

O que o LIT faz hoje

1. Resolve dependencias recursivamente

Para pacotes do npm, o LIT le dependencies do package.json, resolve ranges semver e materializa a arvore no store global. Exemplo real validado no projeto:

• lit install debug
• [email protected] foi instalado
• [email protected] foi resolvido automaticamente
• debug passou a enxergar ms via ~/.lit/store/[email protected]/node_modules/ms

2. Registra integridade no lockfile e verifica downloads

• Tarballs do npm usam dist.integrity ou shasum
• Scripts do LIT registry recebem hash sha512
• O campo integrity passa a ser persistido em lit-lock.json
• Downloads invalidos falham antes da extracao

3. Mantem um indice local do store

O arquivo ~/.lit/store/index.json guarda o inventario do cache global:

• pacote e versao
• origem e URL resolvida
• integridade
• dependencias diretas resolvidas
• lastUsedAt

4. Aproxima a compatibilidade com npm

O LIT continua criando links em ./packages, mas agora tambem cria:

• ./node_modules/<pkg> para pacotes top-level
• ~/.lit/store/<pkg>@<version>/node_modules/<dep> para dependencias internas

Isso permite que o runtime do Node resolva imports/require no padrao esperado do ecossistema npm, sem copiar tudo para um node_modules gigante no projeto.

Quando o pacote top-level expoe bin, o LIT tambem cria shims em ./node_modules/.bin, permitindo executar CLIs no mesmo estilo esperado por ferramentas do ecossistema Node.

5. Mede desempenho localmente

O benchmark do repositório executa o LIT e compara com outros package managers encontrados na máquina:

npm run bench:install
node benchmarks/compare-install.js debug axios

No ambiente atual, o benchmark encontrou npm e bun, pulando pnpm e yarn por indisponibilidade local.

Fluxo do install

1. O LIT resolve o projeto alvo a partir do diretório atual.
2. Procura o pacote em lit-registry.json e no registry remoto configurado por LIT_REGISTRY_URL.
3. Se o pacote nao estiver no LIT registry, entra o NPM Bridge via https://registry.npmjs.org/<pkg>.
4. Resolve a versao compatível com a faixa semver.
5. Baixa apenas se a versao ainda nao estiver em ~/.lit/store.
6. Verifica integridade e extrai no cache global.
7. Resolve e linka dependencias recursivamente.
8. Cria links em ./packages e ./node_modules.
9. Atualiza lit-lock.json e ~/.lit/store/index.json.

LIT Registry

O arquivo lit-registry.json funciona como registry local:

{
  "hello-world": {
    "source": "lit",
    "version": "1.0.0",
    "format": "script",
    "url": "./examples/hello-world.js"
  }
}

Se a variavel LIT_REGISTRY_URL estiver definida, o LIT tenta baixar um registry remoto em JSON e usa esse conteudo como fallback do registry local.

Configuracao npm-compatible

O NPM Bridge agora tambem aceita configuracao basica de registry no formato do ecossistema npm:

• registry=https://...
• @scope:registry=https://...
• //host/:_authToken=...
• LIT_NPM_REGISTRY_URL=https://...

O LIT le ~/.npmrc e ./.npmrc, respeitando overrides do projeto quando presentes. Isso ajuda a consumir registries privados, espelhos e feeds por escopo no mesmo estilo de npm, yarn e pnpm.

Lockfile

O lit-lock.json agora guarda path, compat path, integridade e a arvore direta de dependencias:

{
  "debug": {
    "version": "4.4.3",
    "range": "latest",
    "path": "./packages/debug",
    "compatPath": "./node_modules/debug",
    "source": "npm",
    "storePath": "C:/Users/seu-usuario/.lit/store/[email protected]",
    "integrity": "sha512-...",
    "dependencies": {
      "ms": {
        "version": "2.1.3",
        "spec": "^2.1.3",
        "storePath": "C:/Users/seu-usuario/.lit/store/[email protected]",
        "integrity": "sha512-..."
      }
    }
  }
}

Cache global

• Windows: C:/Users/<user>/.lit/store
• Linux/macOS: ~/.lit/store

Cada versao fica isolada em um diretorio proprio:

~/.lit/store/
  [email protected]/
  [email protected]/
  index.json

No Windows, os links do projeto e do store sao criados como junctions. Em Linux e macOS, o LIT usa symlinks de diretório.

Exemplo de uso

node bin/lit.js install debug
node -e "import('debug').then((m) => console.log(typeof (m.default || m)))"
node bin/lit.js list
node bin/lit.js info debug
node bin/lit.js update debug
node bin/lit.js remove debug

Exemplo de saida

$ node bin/lit.js install debug
⚡ LIT install
   Instalando 1 pacote(s) com dependencias recursivas, store global e linking.

▶ step Instalando debug
ℹ info debug@latest nao esta no LIT registry. Acionando NPM Bridge...
ℹ info NPM Bridge encontrou [email protected].
ℹ info ms@^2.1.3 nao esta no LIT registry. Acionando NPM Bridge...
ℹ info NPM Bridge encontrou [email protected].
✔ success Cache populado em C:/Users/seu-usuario/.lit/store/[email protected]
✔ success Link criado em ./packages/debug
✔ success Compatibilidade criada em ./node_modules/debug
✔ success 1 pacote(s) pronto(s) para uso em ./packages e ./node_modules.

Limites atuais

• optionalDependencies e peerDependencies ainda nao entram no resolvedor
• ainda nao existe hoisting inteligente entre pacotes top-level
• ainda dependemos do utilitario tar do sistema para extrair tarballs
• o benchmark atual mede install em workspace limpo, nao limpa caches globais dos concorrentes

Proximos passos naturais

• Resolver optionalDependencies e peerDependencies
• Melhorar o algoritmo de hoisting/flattening
• Criar benchmark frio e quente com isolamento de cache
• Publicar o CLI para testes em projetos externos