@thecodecodex/tools 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Douglas Capeletti
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,45 @@
-# Temporary Holding Version
+# @thecodecodex/tools
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Lógica pura das ferramentas do [thecodecodex.com](https://thecodecodex.com/pt/tools/): finanças brasileiras (CLT, PJ,
+juros compostos, férias), CPF/CNPJ, fatura em PDF, PDF Studio, conversor de tabelas, diff, regex, JWT, hash, UUID e
+outras, além do script de terminal [`cli.js`](https://thecodecodex.com/cli.js) e do catálogo de skills de IA.
+
+Sem DOM nem framework: as mesmas funções rodam no navegador (site), no Node/Deno/Bun (`cli.js`) e nos testes.
+
+## Uso
+
+```sh
+pnpm add @thecodecodex/tools
+```
+
+O pacote publica o código-fonte TypeScript (ESM), para ser consumido por um bundler (Vite, esbuild, Astro) ou pelo Deno.
+
+```ts
+import { isValidCpf } from "@thecodecodex/tools/br/cpf"
+import { cltYear } from "@thecodecodex/tools/finance/clt"
+import { convertTable } from "@thecodecodex/tools/table-convert"
+```
+
+Indicadores de mercado (CDI, IPCA, poupança, câmbio) não vêm embutidos: carregue-os antes de usar
+`@thecodecodex/tools/market` ou os comandos de terminal que dependem deles.
+
+```ts
+import { setMarketData } from "@thecodecodex/tools/market"
+setMarketData(data) // { fetchedAt, source, series: { cdi, ipca12m, savingsMonthly, usd, eur, gbp, cad } }
+```
+
+## Desenvolvimento
+
+- `pnpm check`: tipos, lint e testes (Vitest, ao lado do código em `src/**/*.test.ts`)
+- Skills de IA ficam em `skills/<nome>/` (formato [Agent Skills](https://agentskills.io/specification)); depois de
+  editar, rode `pnpm skills:build` para regenerar `src/skills.json` (um teste falha se ficar desatualizado)
+- Nova ferramenta: a lógica e o comando de terminal (`src/cli/tools.ts`, com os mesmos parâmetros da URL no site)
+
+## Publicação
+
+Atualize `version` no `package.json`, faça o commit e envie a tag correspondente (`git tag v0.2.0 && git push --tags`):
+o workflow `publish.yml` roda os testes e publica no npm com provenance.
+
+## Licença
+
+MIT

package/package.json

@@ -1,6 +1,48 @@
 {
   "name": "@thecodecodex/tools",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Lógica das ferramentas do thecodecodex.com (finanças BR, CPF/CNPJ, PDF, regex, JWT e mais) e o script de terminal cli.js",
+  "license": "MIT",
+  "author": "Douglas Capeletti",
+  "homepage": "https://thecodecodex.com/pt/tools/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/douglas-capeletti/thecodecodex-tools.git"
+  },
+  "bugs": "https://github.com/douglas-capeletti/thecodecodex-tools/issues",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    "./random": "./src/random/index.ts",
+    "./table-convert": "./src/table-convert/index.ts",
+    "./skills.json": "./src/skills.json",
+    "./*": "./src/*.ts"
+  },
+  "files": [
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/*.fixture.*",
+    "!src/**/fixtures",
+    "!src/test-setup.ts"
+  ],
+  "scripts": {
+    "check": "tsc && eslint && vitest run",
+    "test": "vitest run",
+    "lint": "eslint",
+    "skills:build": "node scripts/build-skills.mjs",
+    "prepublishOnly": "pnpm check"
+  },
+  "dependencies": {
+    "pdf-lib": "^1.17.1"
+  },
+  "devDependencies": {
+    "@stylistic/eslint-plugin": "^2.13.0",
+    "@types/node": "^22.20.5",
+    "eslint": "^9.39.4",
+    "globals": "^15.15.0",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.59.0",
+    "vitest": "^5.0.5"
+  },
+  "packageManager": "pnpm@12.14.0"
+}

package/src/base64.ts

@@ -0,0 +1,36 @@
+// Codificação de texto UTF-8 (acentos e emojis) — btoa/atob puros só aceitam Latin-1
+export type Codec = "base64" | "base64url" | "url"
+export type Direction = "encode" | "decode"
+
+function bytesToBase64(bytes: Uint8Array): string {
+  let binary = ""
+  bytes.forEach((b) => (binary += String.fromCharCode(b)))
+  return btoa(binary)
+}
+
+function base64ToBytes(value: string): Uint8Array {
+  const binary = atob(value)
+  return Uint8Array.from(binary, (char) => char.charCodeAt(0))
+}
+
+export function encode(text: string, codec: Codec): string {
+  if (codec === "url") return encodeURIComponent(text)
+  const base64 = bytesToBase64(new TextEncoder().encode(text))
+  return codec === "base64url" ? base64.replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "") : base64
+}
+
+export function decode(text: string, codec: Codec): string {
+  if (codec === "url") return decodeURIComponent(text.replace(/\+/g, " "))
+  let value = text.trim().replace(/\s/g, "")
+  if (codec === "base64url") value = value.replace(/-/g, "+").replace(/_/g, "/")
+  value = value.padEnd(value.length + ((4 - (value.length % 4)) % 4), "=")
+  return new TextDecoder("utf-8", { fatal: true }).decode(base64ToBytes(value))
+}
+
+export function convert(text: string, codec: Codec, direction: Direction): { ok: true, value: string } | { ok: false } {
+  try {
+    return { ok: true, value: direction === "encode" ? encode(text, codec) : decode(text, codec) }
+  } catch {
+    return { ok: false }
+  }
+}

package/src/br/cnpj.ts

@@ -0,0 +1,55 @@
+import { secureRandom, type Random } from "../random/index"
+
+// CNPJ alfanumérico (IN RFB nº 2.229/2024): raiz e ordem aceitam [0-9A-Z]; os dígitos verificadores
+// seguem numéricos. Cada caractere vale (código ASCII − 48), então o cálculo é o mesmo do CNPJ numérico.
+const ALPHANUMERIC = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ"
+const WEIGHTS = [6, 5, 4, 3, 2, 9, 8, 7, 6, 5, 4, 3, 2]
+
+function charValue(char: string): number {
+  return char.charCodeAt(0) - 48
+}
+
+function checkDigit(chars: string): number {
+  const weights = WEIGHTS.slice(WEIGHTS.length - chars.length)
+  const sum = [...chars].reduce((acc, char, i) => acc + charValue(char) * (weights[i] ?? 0), 0)
+  const rest = sum % 11
+  return rest < 2 ? 0 : 11 - rest
+}
+
+export function cnpjCheckDigits(base: string): string {
+  const first = checkDigit(base)
+  const second = checkDigit(base + first)
+  return `${first}${second}`
+}
+
+export type CnpjKind = "numeric" | "alphanumeric"
+
+export function generateCnpj({ kind = "numeric", branch = "0001", random = secureRandom }: { kind?: CnpjKind, branch?: string, random?: Random } = {}): string {
+  const alphabet = kind === "alphanumeric" ? ALPHANUMERIC : ALPHANUMERIC.slice(0, 10)
+  let root: string
+  do {
+    root = Array.from({ length: 8 }, () => alphabet[random(alphabet.length)]).join("")
+    // garante ao menos uma letra no alfanumérico, senão é só um CNPJ numérico
+  } while (/^(.)\1+$/.test(root) || (kind === "alphanumeric" && !/[A-Z]/.test(root)))
+  const base = root + branch
+  return base + cnpjCheckDigits(base)
+}
+
+export function stripCnpj(value: string): string {
+  return value.toUpperCase().replace(/[^0-9A-Z]/g, "")
+}
+
+export function formatCnpj(value: string): string {
+  const chars = stripCnpj(value)
+  return chars.length === 14 ? chars.replace(/(.{2})(.{3})(.{3})(.{4})(.{2})/, "$1.$2.$3/$4-$5") : value
+}
+
+export function isValidCnpj(value: string): boolean {
+  const chars = stripCnpj(value)
+  if (!/^[0-9A-Z]{12}\d{2}$/.test(chars) || /^(.)\1+$/.test(chars)) return false
+  return cnpjCheckDigits(chars.slice(0, 12)) === chars.slice(12)
+}
+
+export function cnpjKind(value: string): CnpjKind {
+  return /[A-Z]/.test(stripCnpj(value).slice(0, 12)) ? "alphanumeric" : "numeric"
+}

package/src/br/cpf.ts

@@ -0,0 +1,61 @@
+import { secureRandom, type Random } from "../random/index"
+
+// O 9º dígito do CPF indica a região fiscal de emissão
+export const CPF_REGIONS: Record<string, number> = {
+  RS: 0,
+  DF: 1, GO: 1, MS: 1, MT: 1, TO: 1,
+  AC: 2, AM: 2, AP: 2, PA: 2, RO: 2, RR: 2,
+  CE: 3, MA: 3, PI: 3,
+  AL: 4, PB: 4, PE: 4, RN: 4,
+  BA: 5, SE: 5,
+  MG: 6,
+  ES: 7, RJ: 7,
+  SP: 8,
+  PR: 9, SC: 9,
+}
+
+function checkDigit(digits: number[]): number {
+  const weightStart = digits.length + 1
+  const sum = digits.reduce((acc, digit, i) => acc + digit * (weightStart - i), 0)
+  const rest = sum % 11
+  return rest < 2 ? 0 : 11 - rest
+}
+
+export function cpfCheckDigits(base: string): string {
+  const digits = [...base].map(Number)
+  const first = checkDigit(digits)
+  const second = checkDigit([...digits, first])
+  return `${first}${second}`
+}
+
+export function generateCpf({ uf, random = secureRandom }: { uf?: string | undefined, random?: Random } = {}): string {
+  const region = uf ? CPF_REGIONS[uf] : undefined
+  let base: string
+  do {
+    base = Array.from({ length: 8 }, () => random(10)).join("") + String(region ?? random(10))
+  } while (/^(\d)\1+$/.test(base))
+  return base + cpfCheckDigits(base)
+}
+
+export function stripCpf(value: string): string {
+  return value.replace(/\D/g, "")
+}
+
+export function formatCpf(value: string): string {
+  const digits = stripCpf(value)
+  return digits.length === 11 ? digits.replace(/(\d{3})(\d{3})(\d{3})(\d{2})/, "$1.$2.$3-$4") : value
+}
+
+export function isValidCpf(value: string): boolean {
+  const digits = stripCpf(value)
+  // sequências repetidas (111.111.111-11) passam no cálculo mas são inválidas
+  if (digits.length !== 11 || /^(\d)\1+$/.test(digits)) return false
+  return cpfCheckDigits(digits.slice(0, 9)) === digits.slice(9)
+}
+
+export function cpfRegion(value: string): string[] {
+  const digits = stripCpf(value)
+  if (digits.length < 9) return []
+  const region = Number(digits[8])
+  return Object.entries(CPF_REGIONS).filter(([, r]) => r === region).map(([uf]) => uf)
+}

package/src/cli/main.ts

@@ -0,0 +1,93 @@
+// Ponto de entrada de thecodecodex.com/cli.js. Uso:
+//   deno run "https://thecodecodex.com/cli.js?tool=net-salary&bruto=8000"
+//   curl -s https://thecodecodex.com/cli.js | node --input-type=module - net-salary bruto=8000
+// Parâmetros: da query string da URL do script (Deno) e/ou argumentos (`tool chave=valor` ou `--chave valor`).
+import { TOOLS, type Params } from "./tools"
+
+declare const Deno: { args: string[], stdout: { write(data: Uint8Array): Promise<number> }, exit(code: number): never } | undefined
+declare const process: { argv: string[], stdout: { write(data: Uint8Array | string): boolean }, exitCode?: number } | undefined
+
+export const SITE = "https://thecodecodex.com"
+
+export function parseArgs(url: string, args: string[]): { tool: string | undefined, params: Params } {
+  const params = new URLSearchParams(url.includes("?") ? url.slice(url.indexOf("?") + 1) : "")
+  let tool = params.get("tool") ?? undefined
+  params.delete("tool")
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i] ?? ""
+    if (arg.startsWith("--")) {
+      const [key, inline] = arg.slice(2).split(/=(.*)/s)
+      const value = inline ?? (args[i + 1] && !args[i + 1]?.startsWith("--") ? args[++i] : "1")
+      if (key === "tool") tool = value
+      else if (key) params.set(key, value ?? "")
+    } else if (arg.includes("=")) {
+      const [key = "", value = ""] = arg.split(/=(.*)/s)
+      if (key === "tool") tool = value
+      else params.set(key, value)
+    } else if (!tool) tool = arg
+  }
+  return { tool, params }
+}
+
+export function help(): unknown {
+  return {
+    usage: [`deno run "${SITE}/cli.js?tool=<ferramenta>&<parametro>=<valor>"`, `curl -s ${SITE}/cli.js | node --input-type=module - <ferramenta> <parametro>=<valor>`],
+    note: "Os parâmetros são os mesmos da URL da ferramenta no site: copie o link de compartilhamento e troque o endereço.",
+    tools: Object.fromEntries(Object.entries(TOOLS).map(([name, tool]) => [name, { description: tool.description, params: Object.fromEntries(tool.params.map((p) => [p.name, `${p.description} (padrão: ${p.default || "—"})`])) }])),
+  }
+}
+
+export type ExecuteResult = { text: string, write?: FileToWrite[] } | { bytes: Uint8Array }
+export interface FileToWrite {
+  path: string
+  content: string
+}
+
+export async function execute(tool: string | undefined, params: Params): Promise<ExecuteResult> {
+  if (!tool || tool === "help") return { text: JSON.stringify(help(), null, 2) }
+  const definition = TOOLS[tool]
+  if (!definition) throw new Error(`Ferramenta desconhecida: ${tool}. Rode sem parâmetros para ver a lista.`)
+  const output = await definition.run(params)
+  if ("pdf" in output) return { bytes: output.pdf }
+  if ("file" in output) return { bytes: output.file }
+  if ("text" in output) return { text: output.text }
+  const text = JSON.stringify({ tool, input: Object.fromEntries(params), result: output.json }, null, 2)
+  return "write" in output ? { text, write: output.write } : { text }
+}
+
+// Grava arquivos com node:fs (Node, Bun e Deno entendem o prefixo node:; no Deno exige --allow-write).
+// Import dinâmico com especificador em variável: o bundle "neutral" não tenta resolver módulos do Node.
+interface NodeFs {
+  mkdir(path: string, options: { recursive: boolean }): Promise<unknown>
+  writeFile(path: string, data: string): Promise<void>
+}
+async function writeFiles(files: FileToWrite[]) {
+  const fsModule = "node:fs/promises"
+  const fs = (await import(/* @vite-ignore */ fsModule)) as NodeFs
+  for (const file of files) {
+    const folder = file.path.slice(0, Math.max(file.path.lastIndexOf("/"), 0))
+    if (folder) await fs.mkdir(folder, { recursive: true })
+    await fs.writeFile(file.path, file.content)
+  }
+}
+
+export async function main() {
+  const isDeno = typeof Deno !== "undefined"
+  const args = isDeno ? Deno.args : (process?.argv.slice(2) ?? []).filter((a) => a !== "-")
+  const write = async (data: Uint8Array | string) => {
+    const bytes = typeof data === "string" ? new TextEncoder().encode(`${data}\n`) : data
+    if (isDeno) await Deno.stdout.write(bytes)
+    else process?.stdout.write(bytes)
+  }
+  try {
+    const { tool, params } = parseArgs(import.meta.url, args)
+    const result = await execute(tool, params)
+    if ("write" in result && result.write) await writeFiles(result.write)
+    await write("text" in result ? result.text : result.bytes)
+  } catch (error) {
+    await write(JSON.stringify({ error: error instanceof Error ? error.message : String(error) }, null, 2))
+    if (isDeno) Deno.exit(1)
+    else if (process) process.exitCode = 1
+  }
+}
+