{"_id":"@cncflora/occur2dwc","_rev":"3-b50e8418ad65db0d4d246b73bd8633f4","name":"@cncflora/occur2dwc","dist-tags":{"latest":"0.1.2"},"versions":{"0.1.0":{"name":"@cncflora/occur2dwc","version":"0.1.0","keywords":["darwin-core","darwin-core-archive","dwc","dwca","biodiversity","biodiversity-data","gbif","cli","typescript","validation","conversion","data-publishing"],"author":{"name":"Vicente Calfo","email":"vicentecalfo@jbrj.gov.br"},"license":"MIT","_id":"@cncflora/occur2dwc@0.1.0","maintainers":[{"name":"vicentecalfo.dev","email":"vicentecalfo.dev@gmail.com"}],"homepage":"https://github.com/Occur2DWC/occur2dwc#readme","bugs":{"url":"https://github.com/Occur2DWC/occur2dwc/issues"},"bin":{"occur2dwc":"dist/cli.js"},"dist":{"shasum":"4a640703b22552d87eca95a684925aa22daf0e39","tarball":"https://registry.npmjs.org/@cncflora/occur2dwc/-/occur2dwc-0.1.0.tgz","fileCount":16,"integrity":"sha512-Bk8zPG86MjcT7klLj2hY/wbRG3kwGASR5zuc5CskUUhQgpqVymkzNU8rCXJspL9uuIYlabZaax+43HiE6CCl4w==","signatures":[{"sig":"MEUCIQDbnJzSQYe9V02JdfKH6QnuX6ixVRY4DJwJsJHO0O0/xgIgE+Phn5OqviiGfQW6XoLsPtMkNmLGYVbO9oCrIh2BKRs=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":580290},"main":"dist/index.js","types":"dist/index.d.ts","engines":{"node":">=20.0.0"},"gitHead":"e949fc348e2383f56e2200dbd3f70910334128df","scripts":{"dev":"tsx src/cli.ts --help","lint":"eslint .","test":"vitest","build":"tsup","check":"npm run lint && npm run typecheck && npm run test:run && npm run build","clean":"rm -rf dist coverage","format":"prettier . --write","prepare":"husky","coverage":"vitest run --coverage","lint:fix":"eslint . --fix","test:run":"vitest run","typecheck":"tsc --noEmit","coverage:c8":"npm run build && c8 node scripts/coverage-runner.cjs","lint-staged":"lint-staged","format:check":"prettier . --check","prepublishOnly":"npm run build && npm run test:run"},"_npmUser":{"name":"vicentecalfo.dev","email":"vicentecalfo.dev@gmail.com"},"repository":{"url":"git+https://github.com/Occur2DWC/occur2dwc.git","type":"git"},"_npmVersion":"11.6.2","description":"CLI para inicializar, converter, validar e empacotar dados de ocorrencia em Darwin Core (DwC).","directories":{},"lint-staged":{"*.{ts,js,mjs,cjs}":["eslint --fix","prettier --write"],"*.{json,md,yml,yaml}":["prettier --write"]},"_nodeVersion":"24.13.0","dependencies":{"yaml":"^2.8.1","archiver":"^7.0.1","commander":"^14.0.1"},"_hasShrinkwrap":false,"devDependencies":{"c8":"^10.1.3","tsx":"^4.20.6","tsup":"^8.5.0","husky":"^9.1.7","eslint":"^9.39.1","vitest":"^4.0.8","adm-zip":"^0.5.16","globals":"^16.5.0","prettier":"^3.6.2","@eslint/js":"^9.39.1","typescript":"^5.9.3","@types/node":"^24.10.1","lint-staged":"^16.2.6","@types/adm-zip":"^0.5.7","@types/archiver":"^6.0.3","typescript-eslint":"^8.46.4","@vitest/coverage-v8":"^4.0.8","eslint-config-prettier":"^10.1.8"},"_npmOperationalInternal":{"tmp":"tmp/occur2dwc_0.1.0_1772039229096_0.5824102260407131","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"@cncflora/occur2dwc","version":"0.1.1","keywords":["darwin-core","darwin-core-archive","dwc","dwca","biodiversity","biodiversity-data","gbif","cli","typescript","validation","conversion","data-publishing"],"author":{"name":"Vicente Calfo","email":"vicentecalfo@jbrj.gov.br"},"license":"MIT","_id":"@cncflora/occur2dwc@0.1.1","maintainers":[{"name":"vicentecalfo.dev","email":"vicentecalfo.dev@gmail.com"}],"homepage":"https://github.com/Occur2DWC/occur2dwc#readme","bugs":{"url":"https://github.com/Occur2DWC/occur2dwc/issues"},"bin":{"occur2dwc":"dist/cli.js"},"dist":{"shasum":"6ccede92c157baa5c631ad93b29cb6a26e416dc6","tarball":"https://registry.npmjs.org/@cncflora/occur2dwc/-/occur2dwc-0.1.1.tgz","fileCount":16,"integrity":"sha512-E3oBSY5eEO77sI2GMoEohFXPW50uZj2BJ4b18pUVrIMdzWciBKchNNksReg6QNi9jt7evNvO2g+32MtBEzC3Yg==","signatures":[{"sig":"MEQCIFlbPrje7BP1nlt4JHeVkjdFByKvpq5Of1GJuZxBkXVTAiAKHPsb8Kcz9p/yoAN4tdm8zZ7Py+Jv+D9mRJ0voaBlhg==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":619991},"main":"dist/index.js","types":"dist/index.d.ts","engines":{"node":">=20.0.0"},"gitHead":"3bbd577d4d8635b551014f973757ef1582657336","scripts":{"dev":"tsx src/cli.ts --help","lint":"eslint .","test":"vitest","build":"tsup","check":"npm run lint && npm run typecheck && npm run test:run && npm run build","clean":"rm -rf dist coverage","format":"prettier . --write","prepare":"husky","coverage":"vitest run --coverage","lint:fix":"eslint . --fix","test:run":"vitest run","typecheck":"tsc --noEmit","coverage:c8":"npm run build && c8 node scripts/coverage-runner.cjs","lint-staged":"lint-staged","format:check":"prettier . --check","prepublishOnly":"npm run build && npm run test:run"},"_npmUser":{"name":"vicentecalfo.dev","email":"vicentecalfo.dev@gmail.com"},"repository":{"url":"git+https://github.com/Occur2DWC/occur2dwc.git","type":"git"},"_npmVersion":"11.6.2","description":"CLI para inicializar, converter, validar e empacotar dados de ocorrencia em Darwin Core (DwC).","directories":{},"lint-staged":{"*.{ts,js,mjs,cjs}":["eslint --fix","prettier --write"],"*.{json,md,yml,yaml}":["prettier --write"]},"_nodeVersion":"24.13.0","dependencies":{"yaml":"^2.8.1","archiver":"^7.0.1","commander":"^14.0.1"},"_hasShrinkwrap":false,"devDependencies":{"c8":"^10.1.3","tsx":"^4.20.6","tsup":"^8.5.0","husky":"^9.1.7","eslint":"^9.39.1","vitest":"^4.0.8","adm-zip":"^0.5.16","globals":"^16.5.0","prettier":"^3.6.2","@eslint/js":"^9.39.1","typescript":"^5.9.3","@types/node":"^24.10.1","lint-staged":"^16.2.6","@types/adm-zip":"^0.5.7","@types/archiver":"^6.0.3","typescript-eslint":"^8.46.4","@vitest/coverage-v8":"^4.0.8","eslint-config-prettier":"^10.1.8"},"_npmOperationalInternal":{"tmp":"tmp/occur2dwc_0.1.1_1772201388510_0.8950521893531489","host":"s3://npm-registry-packages-npm-production"}},"0.1.2":{"name":"@cncflora/occur2dwc","version":"0.1.2","description":"CLI para inicializar, converter, validar e empacotar dados de ocorrencia em Darwin Core (DwC).","license":"MIT","author":{"name":"Vicente Calfo","email":"vicentecalfo@jbrj.gov.br"},"homepage":"https://github.com/Occur2DWC/occur2dwc#readme","repository":{"type":"git","url":"git+https://github.com/Occur2DWC/occur2dwc.git"},"bugs":{"url":"https://github.com/Occur2DWC/occur2dwc/issues"},"keywords":["darwin-core","darwin-core-archive","dwc","dwca","biodiversity","biodiversity-data","gbif","cli","typescript","validation","conversion","data-publishing"],"engines":{"node":">=20.0.0"},"main":"dist/index.js","types":"dist/index.d.ts","bin":{"occur2dwc":"dist/cli.js"},"scripts":{"clean":"rm -rf dist coverage","build":"tsup","dev":"tsx src/cli.ts --help","typecheck":"tsc --noEmit","lint":"eslint .","lint:fix":"eslint . --fix","format":"prettier . --write","format:check":"prettier . --check","test":"vitest","test:run":"vitest run","coverage":"vitest run --coverage","coverage:c8":"npm run build && c8 node scripts/coverage-runner.cjs","lint-staged":"lint-staged","prepare":"husky","check":"npm run lint && npm run typecheck && npm run test:run && npm run build","prepublishOnly":"npm run build && npm run test:run"},"lint-staged":{"*.{ts,js,mjs,cjs}":["eslint --fix","prettier --write"],"*.{json,md,yml,yaml}":["prettier --write"]},"dependencies":{"archiver":"^7.0.1","commander":"^14.0.1","yaml":"^2.8.1"},"devDependencies":{"@eslint/js":"^9.39.1","@types/adm-zip":"^0.5.7","@types/archiver":"^6.0.3","@types/node":"^24.10.1","@vitest/coverage-v8":"^4.0.8","adm-zip":"^0.5.16","c8":"^10.1.3","eslint":"^9.39.1","eslint-config-prettier":"^10.1.8","globals":"^16.5.0","husky":"^9.1.7","lint-staged":"^16.2.6","prettier":"^3.6.2","tsup":"^8.5.0","tsx":"^4.20.6","typescript":"^5.9.3","typescript-eslint":"^8.46.4","vitest":"^4.0.8"},"gitHead":"57cb88f29a12e5f3b7749d5cfa08e8bcb89f3fb5","_id":"@cncflora/occur2dwc@0.1.2","_nodeVersion":"24.13.0","_npmVersion":"11.6.2","dist":{"integrity":"sha512-OWl+Jxx8SOxyE1GtnlMa13VhF8/e+NZeTbNi88/fxhsfRW6L5uSXmNzeploZHqm8rSFh3h6S1NZPMiAOgFtnaA==","shasum":"d3df06de81ecd4f8b4a21cc9a4387998cae3dfcb","tarball":"https://registry.npmjs.org/@cncflora/occur2dwc/-/occur2dwc-0.1.2.tgz","fileCount":16,"unpackedSize":621207,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIDBCGEux+PPyXe8683BI+OxPWxqQRnUE3doaZ+P+0KhxAiB0nZvFElKyUWL7u4ic5HnKpM4jScjp+kG0TaY0SXvG9Q=="}]},"_npmUser":{"name":"vicentecalfo.dev","email":"vicentecalfo.dev@gmail.com"},"directories":{},"maintainers":[{"name":"vicentecalfo.dev","email":"vicentecalfo.dev@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/occur2dwc_0.1.2_1772203134664_0.7558669860479006"},"_hasShrinkwrap":false}},"time":{"created":"2026-02-25T17:07:08.696Z","modified":"2026-02-27T14:38:55.106Z","0.1.0":"2026-02-25T17:07:09.274Z","0.1.1":"2026-02-27T14:09:48.688Z","0.1.2":"2026-02-27T14:38:54.894Z"},"bugs":{"url":"https://github.com/Occur2DWC/occur2dwc/issues"},"author":{"name":"Vicente Calfo","email":"vicentecalfo@jbrj.gov.br"},"license":"MIT","homepage":"https://github.com/Occur2DWC/occur2dwc#readme","keywords":["darwin-core","darwin-core-archive","dwc","dwca","biodiversity","biodiversity-data","gbif","cli","typescript","validation","conversion","data-publishing"],"repository":{"type":"git","url":"git+https://github.com/Occur2DWC/occur2dwc.git"},"description":"CLI para inicializar, converter, validar e empacotar dados de ocorrencia em Darwin Core (DwC).","maintainers":[{"name":"vicentecalfo.dev","email":"vicentecalfo.dev@gmail.com"}],"readme":"# Occur2DWC\n\nFerramenta de linha de comando para conversao, validacao e geracao de pacotes Darwin Core (Simple Darwin Core e Darwin Core Archive - DwC-A).\n\n## 1. Titulo\n\n### Occur2DWC\n\nCLI para padronizacao de dados de ocorrencia biologica no ecossistema Darwin Core, incluindo mapeamento, validacao e empacotamento para publicacao.\n\n## 2. Visao Geral\n\nProjetos de biodiversidade frequentemente lidam com planilhas heterogeneas, nomes de colunas inconsistentes e ausencia de controles minimos de qualidade antes da publicacao. O Occur2DWC resolve esse problema ao oferecer um fluxo operacional unico para transformar dados tabulares em estruturas compativeis com Darwin Core.\n\nCom a ferramenta, e possivel:\n\n- converter CSV/TSV para Simple Darwin Core;\n- validar campos obrigatorios e consistencia basica de coordenadas e data;\n- gerar relatorios tecnicos em JSON para auditoria;\n- empacotar datasets em Darwin Core Archive (DwC-A) com `occurrence.txt`, `meta.xml` e `eml.xml`.\n\nPrincipais comandos:\n\n- `convert`: converte e aplica regras de transformacao;\n- `validate`: valida arquivos sem transformar o dataset;\n- `pack`: gera o pacote DwC-A (`.zip`);\n- `init`: inicializa estrutura recomendada de projeto.\n\n## 3. Conceitos Fundamentais\n\n### Darwin Core\n\nDarwin Core (DwC) e um padrao de termos para troca de dados de biodiversidade, com foco em ocorrencias, taxonomia, localizacao, coleta e identificacao.\n\n### Simple Darwin Core\n\nSimple DwC representa os dados em um unico arquivo tabular (normalmente CSV ou TSV), no qual cada linha descreve uma ocorrencia e cada coluna corresponde a um termo DwC.\n\n### Darwin Core Archive (DwC-A)\n\nDwC-A e um pacote zipado para distribuicao de dados. No caso de ocorrencia simples, inclui tipicamente:\n\n- `occurrence.txt`;\n- `meta.xml` (metadados estruturais do arquivo);\n- `eml.xml` (metadados descritivos do dataset).\n\n### dynamicProperties\n\n`dynamicProperties` e um termo DwC usado para armazenar informacao adicional em formato JSON quando a coluna original nao corresponde a termos DwC mapeados explicitamente.\n\n### Presets\n\nPresets sao mapeamentos internos predefinidos para formatos de entrada conhecidos. O projeto inclui o preset `cncflora-proflora`.\n\n### Profiles\n\nProfiles definem a estrutura alvo de colunas e os campos obrigatorios durante conversao/validacao. No Occur2DWC, os perfis disponiveis sao:\n\n- `minimal-occurrence`;\n- `occurrence`;\n- `cncflora-occurrence`.\n\n## 4. Instalacao\n\n### Instalacao global\n\n```bash\nnpm install -g occur2dwc\n```\n\n### Uso via npx\n\n```bash\nnpx occur2dwc --help\n```\n\n### Uso local em desenvolvimento\n\nPasso a passo:\n\n1. Clonar o repositorio.\n2. Instalar dependencias.\n3. Compilar o projeto.\n4. Executar a CLI gerada.\n\n```bash\ngit clone https://github.com/Occur2DWC/occur2dwc.git\ncd occur2dwc\nnpm install\nnpm run build\nnode dist/cli.js --help\n```\n\nExecucao em desenvolvimento (sem build final):\n\n```bash\nnpm run dev\n```\n\nRequisito de ambiente:\n\n- Node.js `>= 20`.\n\n## 5. Estrutura Geral de Uso\n\nFluxo recomendado:\n\n1. `convert`\n2. `validate`\n3. `pack`\n\n### Etapa 1: Conversao (`convert`)\n\nConverte o arquivo de origem para Simple DwC, aplica mapeamento de colunas, trata campos extras e opcionalmente deriva `eventDate`.\n\n### Etapa 2: Validacao (`validate`)\n\nValida o resultado para identificar erros estruturais e semanticos antes da publicacao. Pode gerar relatorio JSON para rastreabilidade.\n\n### Etapa 3: Empacotamento (`pack`)\n\nGera um arquivo `.zip` no formato DwC-A contendo dados e metadados estruturais (`meta.xml`) e descritivos (`eml.xml`).\n\n## 6. Comando `convert`\n\n### O que faz\n\nTransforma um CSV/TSV de entrada em um arquivo Simple DwC, com suporte a:\n\n- mapeamento por arquivo (`--map`);\n- preset interno (`--preset`);\n- inferencia por cabecalho;\n- validacao por perfil;\n- controle de colunas nao mapeadas (`--extras`);\n- relatorio tecnico em JSON (`--report`).\n\n### Quando usar\n\nUse `convert` quando o dataset de origem ainda nao esta no padrao DwC, ou quando precisa padronizar delimitador, nomes de campo e estrutura de saida.\n\n### Opcoes principais\n\n| Opcao                          | Descricao tecnica                                                                            |\n| ------------------------------ | -------------------------------------------------------------------------------------------- | ----------------------------------------------------- | ------------------------------------------------------------------------- | --------------------------------------- |\n| `--in <path>`                  | Arquivo de entrada (opcional; se ausente, le de `stdin`).                                    |\n| `--out <path>`                 | Arquivo de saida (obrigatorio).                                                              |\n| `--map <path>`                 | Arquivo YAML/JSON com `version: 1` e bloco `mappings` (alias: `--mapping`).                  |\n| `--preset <auto                | cncflora-proflora                                                                            | none>`                                                | Preset interno de mapeamento. Padrao: `auto`.                             |\n| `--profile <minimal-occurrence | occurrence                                                                                   | cncflora-occurrence>`                                 | Define colunas alvo e campos obrigatorios. Padrao: `occurrence`.          |\n| `--derive-eventdate`           | Deriva `eventDate` (ISO-8601) a partir de `day/month/year` quando `eventDate` estiver vazio. |\n| `--extras <keep                | drop                                                                                         | dynamicProperties>`                                   | Define estrategia para colunas nao mapeadas. Padrao: `dynamicProperties`. |\n| `--validation <strict          | lenient>`                                                                                    | Define como tratar erros por linha. Padrao: `strict`. |\n| `--strict`                     | Retorna erro (codigo 1) ao final se ainda houver erros de validacao.                         |\n| `--report <path>`              | Salva relatorio JSON da conversao.                                                           |\n| `--input-delimiter <auto       | comma                                                                                        | tab                                                   | semicolon>`                                                               | Delimitador da entrada. Padrao: `auto`. |\n| `--output-delimiter <tab       | comma>`                                                                                      | Delimitador da saida. Padrao: `tab`.                  |\n\nOpcoes adicionais relevantes:\n\n- `--max-errors <n>`: limita o total de erros armazenados no relatorio (padrao `1000`);\n- `--id-strategy <preserve|uuid|hash>`: estrategia para `occurrenceID`;\n- `--encoding <utf8|latin1>`: codificacao de entrada/saida;\n- `--normalize-html-entities`: decodifica entidades HTML em campos de texto;\n- `--log-format <text|json>`: formato de log.\n\n### Como funciona `--validation`\n\n- `strict` (padrao): mantem o comportamento atual da conversao. Linhas com erro de validacao sao removidas da saida.\n- `lenient`: nao remove linhas por campo vazio/valor invalido. A saida sempre tem uma linha para cada linha de entrada.\n- No modo `lenient`, valores `undefined`/`null` viram `\"\"` e campos com erro de transformacao/validacao sao gravados como `\"\"` com warning no log.\n\n### Como funciona o mapping\n\nO processo de mapeamento segue esta ordem:\n\n1. Se `--map` for informado, o arquivo de mapeamento do usuario e aplicado.\n2. Se nao houver `--map`, a CLI tenta aplicar preset interno (dependendo de `--preset` e do cabecalho).\n3. Colunas ainda nao mapeadas podem ser inferidas por normalizacao do nome da coluna para termos DwC conhecidos.\n4. Colunas remanescentes sao tratadas por `--extras`.\n\nExemplo de mapeamento (`mapping.yml`):\n\n```yaml\nversion: 1\nidStrategy: preserve\nmappings:\n  id_registro: occurrenceID\n  nome_cientifico: scientificName\n  latitude: decimalLatitude\n  longitude: decimalLongitude\nextras:\n  - observacoes_internas\n  - codigo_planilha\n```\n\n### Como funciona o preset `cncflora-proflora`\n\nO preset interno `cncflora-proflora` pode ser:\n\n- aplicado automaticamente quando `--preset auto` e o cabecalho indica layout compativel;\n- forcado com `--preset cncflora-proflora`;\n- desativado com `--preset none`.\n\n### Como funciona `--extras`\n\nO comportamento de colunas nao mapeadas depende do modo selecionado:\n\n- `keep`: mantem como colunas adicionais na saida;\n- `drop`: remove completamente;\n- `dynamicProperties`: agrega como JSON no campo `dynamicProperties`.\n\n### Exemplos simples\n\nConversao basica:\n\n```bash\noccur2dwc convert \\\n  --in ./dados/origem.csv \\\n  --out ./saida/occurrence.tsv\n```\n\nConversao com mapeamento e relatorio:\n\n```bash\noccur2dwc convert \\\n  --in ./dados/origem.csv \\\n  --out ./saida/occurrence.tsv \\\n  --map ./mapping.yml \\\n  --report ./saida/convert.report.json\n```\n\nConversao com validacao explicita:\n\n```bash\noccur2dwc convert input.csv --mapping mapping.json --validation strict\noccur2dwc convert input.csv --mapping mapping.json --validation lenient\n```\n\n### Exemplo avancado\n\n```bash\noccur2dwc convert \\\n  --in ./dados/proflora.csv \\\n  --out ./saida/occurrence.csv \\\n  --preset cncflora-proflora \\\n  --profile cncflora-occurrence \\\n  --input-delimiter semicolon \\\n  --output-delimiter comma \\\n  --derive-eventdate \\\n  --extras dynamicProperties \\\n  --id-strategy hash \\\n  --max-errors 5000 \\\n  --strict \\\n  --report ./saida/convert.report.json\n```\n\n## 7. Tratamento de Colunas Nao Mapeadas (`--extras`)\n\n### Modo `keep`\n\nMantem as colunas nao mapeadas no arquivo final. Recomendado para diagnostico de migracao e auditoria comparativa.\n\n### Modo `drop`\n\nDescarta colunas nao mapeadas. Recomendado quando a politica institucional exige saida estritamente aderente ao perfil alvo.\n\n### Modo `dynamicProperties` (padrao)\n\nMove colunas nao mapeadas para um JSON em `dynamicProperties`. Recomendado para preservar contexto sem expandir a estrutura de colunas.\n\nExemplo de valor gerado em `dynamicProperties`:\n\n```json\n{ \"codigo_planilha\": \"LTP-2024-09\", \"habitat\": \"Floresta ombrofila\", \"status_local\": \"rara\" }\n```\n\nObservacoes tecnicas:\n\n- chaves sao ordenadas alfabeticamente para estabilidade de output;\n- campos vazios nao sao incluidos no JSON;\n- colunas mapeadas para termos DwC nao sao duplicadas em `dynamicProperties`.\n\n## 8. Comando `validate`\n\n### O que e validado\n\n`validate` verifica o arquivo sem alterar os dados, incluindo:\n\n- campos obrigatorios do perfil selecionado;\n- formato/faixa de `decimalLatitude` e `decimalLongitude`;\n- coerencia de par lat/lon (ambos devem existir juntos);\n- consistencia de `day`, `month`, `year` (incompleto gera aviso; valores invalidos geram erro);\n- divergencia de quantidade de colunas por linha (`column_mismatch`).\n\n### Modo strict\n\nCom `--strict`, a execucao retorna codigo `1` se houver qualquer linha com erro.\n\n### Controle por `--max-errors`\n\n`--max-errors` limita a quantidade de issues armazenadas no relatorio. Ao atingir o limite, a validacao e interrompida com aviso de truncamento no resumo.\n\n### Relatorio JSON\n\nCom `--report`, a CLI salva um relatorio contendo:\n\n- `summary`: totais, perfil, delimitador detectado, duracao e status de truncamento;\n- `issues`: lista de erros/avisos com `rowNumber`, `severity`, `code`, `messagePtBr`, `field` e `value`.\n\nExemplo resumido de relatorio:\n\n```json\n{\n  \"summary\": {\n    \"totalRows\": 3,\n    \"errorRows\": 1,\n    \"warningRows\": 1,\n    \"totalIssues\": 2,\n    \"truncated\": false,\n    \"profile\": \"occurrence\",\n    \"strict\": false,\n    \"delimiter\": \"\\t\"\n  },\n  \"issues\": [\n    {\n      \"rowNumber\": 2,\n      \"severity\": \"error\",\n      \"code\": \"required_field_missing\",\n      \"messagePtBr\": \"Campo obrigatorio ausente: occurrenceID\",\n      \"field\": \"occurrenceID\"\n    },\n    {\n      \"rowNumber\": 3,\n      \"severity\": \"warning\",\n      \"code\": \"incomplete_day_month_year\",\n      \"messagePtBr\": \"Preenchimento parcial de day/month/year. Informe os tres campos para uma data completa.\"\n    }\n  ]\n}\n```\n\n### Interpretacao dos erros\n\n- `required_field_missing`: campo obrigatorio ausente;\n- `invalid_decimal_latitude` / `invalid_decimal_longitude`: coordenada invalida ou fora da faixa;\n- `require_lat_lon_pair`: apenas um dos campos lat/lon informado;\n- `invalid_day_month_year`: valores de dia/mes/ano fora das regras;\n- `column_mismatch`: quantidade de colunas da linha difere do cabecalho.\n\n## 9. Comando `pack` (DwC-A)\n\n### O que e gerado\n\n`pack` transforma um arquivo Simple DwC em um `.zip` no formato Darwin Core Archive.\n\nEstrutura tipica do zip:\n\n```text\nmeu-dataset.dwca.zip\n├── occurrence.txt\n├── meta.xml\n└── eml.xml\n```\n\n### `meta.xml`\n\n`meta.xml` descreve:\n\n- localizacao do core (`occurrence.txt`);\n- indice do identificador (`<id index=\"...\"/>`);\n- mapeamento de cada coluna para URI DwC.\n\nQuando uma coluna nao e reconhecida na whitelist DwC, ela e mapeada para o termo `dynamicProperties` e um warning e emitido no log.\n\n### `eml.xml`\n\n`eml.xml` pode ser:\n\n- fornecido via `--eml <path>`;\n- gerado automaticamente (padrao) quando `--eml` nao e informado e `--generate-eml true`.\n\nMetadados opcionais para EML gerado:\n\n- `--dataset-title`;\n- `--dataset-description`;\n- `--publisher`.\n\n### `id-field`\n\n`--id-field <term>` define qual coluna do cabecalho sera usada como identificador no `meta.xml`.\n\n- padrao: `occurrenceID`;\n- deve existir no cabecalho de entrada;\n- se nao existir, o comando falha com erro estrutural.\n\nModo de depuracao:\n\n- `--meta-only`: nao gera o `.zip`; grava apenas `<nome-saida>.meta.xml` ao lado do caminho informado em `--out`.\n\n### Exemplo completo\n\n```bash\noccur2dwc pack \\\n  --in ./saida/occurrence.tsv \\\n  --out ./publicacao/dataset.dwca.zip \\\n  --delimiter tab \\\n  --id-field occurrenceID \\\n  --dataset-title \"Inventario Floristico Regional\" \\\n  --dataset-description \"Ocorrencias validadas para publicacao em Darwin Core Archive.\" \\\n  --publisher \"Instituicao Cientifica Exemplo\"\n```\n\n## 10. Comando `init`\n\n### O que e gerado\n\n`init` cria uma estrutura base para iniciar o fluxo de publicacao com exemplos, templates e arquivos de apoio.\n\n### Quando utilizar\n\nUse `init` no inicio de um projeto, em novos diretorios de trabalho ou para padronizar a estrutura operacional entre equipes.\n\n### Estrutura criada\n\nArquivos gerados pelo comando:\n\n- `mapping.example.yml`\n- `profiles/custom-profile.json`\n- `examples/input.sample.csv`\n- `examples/expected.simple.tsv`\n- `examples/README.md`\n- `eml.template.xml`\n- `README.occur2dwc.md`\n\nExemplo:\n\n```bash\noccur2dwc init --dir ./projeto-dwc\n```\n\nPara sobrescrever arquivos existentes:\n\n```bash\noccur2dwc init --dir ./projeto-dwc --force\n```\n\n## 11. Preset CNCFlora / ProFlora\n\n### Quando e aplicado automaticamente\n\nCom `--preset auto` (padrao), a deteccao automatica do preset `cncflora-proflora` ocorre quando o cabecalho de entrada contem indicios como:\n\n- `taxon_flora_id`\n- `scientific_name`\n- `decimal_latitude`\n\n### Como forcar com `--preset cncflora-proflora`\n\n```bash\noccur2dwc convert \\\n  --in ./dados/proflora.csv \\\n  --out ./saida/occurrence.tsv \\\n  --preset cncflora-proflora\n```\n\n### Como desativar com `--preset none`\n\n```bash\noccur2dwc convert \\\n  --in ./dados/proflora.csv \\\n  --out ./saida/occurrence.tsv \\\n  --preset none\n```\n\n### Exemplo com CSV separado por ponto e virgula\n\n```bash\noccur2dwc convert \\\n  --in ./dados/proflora.csv \\\n  --out ./saida/occurrence.tsv \\\n  --input-delimiter semicolon \\\n  --preset cncflora-proflora\n```\n\n## 12. Profiles Disponiveis\n\nProfiles suportados:\n\n- `minimal-occurrence`\n- `occurrence`\n- `cncflora-occurrence`\n\nDiferencas principais:\n\n| Profile               | Colunas de saida                                                                                                         | Campos obrigatorios                                                     |\n| --------------------- | ------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------- |\n| `minimal-occurrence`  | conjunto minimo (`occurrenceID`, `scientificName`, `decimalLatitude`, `decimalLongitude`)                                | os 4 campos minimos                                                     |\n| `occurrence`          | perfil padrao de ocorrencia (inclui taxonomia, localidade, coleta, identificacao e observacoes)                          | `occurrenceID`, `scientificName`, `decimalLatitude`, `decimalLongitude` |\n| `cncflora-occurrence` | igual ao `occurrence`, com termos adicionais institucionais (`basisOfRecord`, `institutionCode`, `ownerInstitutionCode`) | mesmo conjunto obrigatorio do profile `occurrence`                      |\n\n## 13. Exemplos Completos\n\n### Fluxo 1: CSV simples\n\n```bash\noccur2dwc convert \\\n  --in ./dados/entrada.csv \\\n  --out ./saida/occurrence.tsv \\\n  --map ./mapping.yml \\\n  --derive-eventdate \\\n  --report ./saida/convert.report.json\n\noccur2dwc validate \\\n  --in ./saida/occurrence.tsv \\\n  --profile occurrence \\\n  --report ./saida/validate.report.json\n```\n\n### Fluxo 2: CSV ProFlora separado por ponto e virgula\n\n```bash\noccur2dwc convert \\\n  --in ./dados/proflora.csv \\\n  --out ./saida/proflora.occurrence.tsv \\\n  --input-delimiter semicolon \\\n  --preset cncflora-proflora \\\n  --profile cncflora-occurrence \\\n  --extras dynamicProperties \\\n  --report ./saida/proflora.convert.report.json\n\noccur2dwc validate \\\n  --in ./saida/proflora.occurrence.tsv \\\n  --delimiter tab \\\n  --profile cncflora-occurrence \\\n  --strict \\\n  --report ./saida/proflora.validate.report.json\n```\n\n### Fluxo 3: Geracao de DwC-A completo\n\n```bash\noccur2dwc convert \\\n  --in ./dados/entrada.csv \\\n  --out ./saida/occurrence.tsv \\\n  --map ./mapping.yml \\\n  --report ./saida/convert.report.json\n\noccur2dwc validate \\\n  --in ./saida/occurrence.tsv \\\n  --strict \\\n  --report ./saida/validate.report.json\n\noccur2dwc pack \\\n  --in ./saida/occurrence.tsv \\\n  --out ./publicacao/dataset.dwca.zip \\\n  --id-field occurrenceID \\\n  --eml ./metadados/eml.xml\n```\n\n## 14. Tratamento de Erros e Codigos de Saida\n\nCodigos principais:\n\n- `0`: execucao concluida com sucesso;\n- `1`: erro de validacao (tipicamente em `--strict`) ou erro inesperado;\n- `2`: erro de uso (argumentos), estrutura de entrada ou IO.\n\nObservacao operacional:\n\n- interrupcao por sinal (`SIGINT`/`SIGTERM`) pode resultar em codigo `130`.\n\nUso de verbosidade:\n\n- `--verbose`: habilita logs de debug e stack trace em falhas;\n- `--quiet`: suprime logs informativos e warnings (erros continuam sendo exibidos).\n\n## 15. Perguntas Frequentes\n\n### Foram encontrados multiplos erros no relatorio. Como proceder?\n\nUtilize `--max-errors` para controlar o volume de issues em datasets grandes e trate primeiro erros estruturais (`column_mismatch`, campos obrigatorios ausentes), pois eles afetam as validacoes subsequentes.\n\n### `occurrenceID` esta ausente. O que fazer?\n\nDefina mapeamento explicito para `occurrenceID` (`--map`) ou aplique `--id-strategy uuid`/`--id-strategy hash` no `convert` quando o identificador nao existir na origem.\n\n### O delimitador parece incorreto. Como corrigir?\n\nInforme explicitamente o delimitador:\n\n- `convert`: `--input-delimiter <auto|comma|tab|semicolon>`\n- `validate` e `pack`: `--delimiter <auto|tab|comma|semicolon>`\n\n### Como limpar colunas extras?\n\nUse `--extras drop` no `convert` para remover todas as colunas nao mapeadas da saida final.\n\n### Como preservar colunas internas sem quebrar o perfil DwC?\n\nUse `--extras dynamicProperties` para manter esses dados em JSON no campo `dynamicProperties`, ou `--extras keep` durante etapas de auditoria interna.\n\n## 16. Boas Praticas\n\n- sempre executar `validate` antes de `pack`;\n- versionar os arquivos convertidos e os relatorios JSON;\n- manter arquivo de mapeamento (`mapping.yml`/`mapping.json`) sob controle de versao;\n- evitar sobrescrever dados originais de entrada;\n- padronizar delimitador e codificacao por projeto;\n- revisar `eml.xml` antes de publicacao externa.\n\n## 17. Licenca\n\nMIT.\n","readmeFilename":"README.md"}