---
name: next_numbered_dir
kind: function
lang: bash
domain: io
version: "1.0.0"
purity: impure
signature: "next_numbered_dir(parent_dir: string, [width: int]) -> string"
description: "Calcula el siguiente prefijo numerico NNNN- para un directorio numerado incremental. Escanea los subdirectorios directos de parent_dir cuyo nombre empiece por NNNN- (4+ digitos seguidos de guion), toma el maximo, le suma 1 y lo imprime con zero-padding al ancho width (default 4). Si parent_dir no existe o no tiene subdirs que matcheen, imprime 0001."
tags: [papers, io, scaffold]
uses_functions: []
uses_types: []
returns: []
returns_optional: false
error_type: "error_go_core"
imports: []
params:
  - name: parent_dir
    desc: "directorio padre cuyos subdirectorios numerados (NNNN-...) se escanean; obligatorio"
  - name: width
    desc: "ancho del zero-padding del numero impreso (default 4); opcional"
output: "el siguiente numero como string con zero-padding a width digitos a stdout (ej. 0003); usage a stderr y exit 1 si falta parent_dir"
tested: false
tests: []
test_file_path: ""
file_path: "bash/functions/io/next_numbered_dir.sh"
---

## Ejemplo

```bash
source bash/functions/io/next_numbered_dir.sh

# Sobre un papers/ que ya contiene 0001-foo y 0002-bar
mkdir -p /tmp/papers/{0001-foo,0002-bar}
next_numbered_dir /tmp/papers
# -> 0003

# Directorio vacio o inexistente -> primer numero
next_numbered_dir /tmp/papers_nuevo
# -> 0001

# Ancho de padding distinto
next_numbered_dir /tmp/papers 6
# -> 000003
```

## Cuando usarla

Cuando scaffoldees un artefacto numerado incremental (papers/, reports/, issues/) y necesites el siguiente NNNN sin colision: escanea lo que ya existe en disco y te da el numero libre listo para crear `<NNNN>-<slug>`.

## Gotchas

- **Impura**: lee el filesystem (estado del directorio en el momento de la llamada). No crea nada — solo calcula e imprime el numero.
- **Octal**: los numeros con cero a la izquierda (`08`, `09`) se interpretan como octal en aritmetica bash y romperian el calculo. La funcion fuerza base 10 con `10#$num` para evitarlo.
- **Solo subdirectorios**: cuenta unicamente subdirs directos. Archivos sueltos (`.gitkeep`, `notas.md`) y subdirs que no matcheen el patron se ignoran. No es recursivo.
- **Patron estricto**: el prefijo debe ser `NNNN-` (minimo 4 digitos seguidos de guion). Un subdir `12-foo` o `0001foo` (sin guion) NO se cuenta.
- No hay deteccion de huecos: devuelve `max+1`, no el primer numero libre intermedio. Si tienes `0001` y `0003`, devuelve `0004`, no `0002`.