chore: round-trip de types export/create + limpieza de casts post-SDK-0.1.3

[rarce]

Resumen

Dos mejoras detectadas durante la review de #33 que conviene resolver antes del release de 0.3.2:

1. Round-trip de types export → types create no funciona sin un paso manual de jq. El export produce un DocumentType completo, pero --schema de create espera el JSON Schema crudo.
2. Cast obsoleto en types create que existía como workaround del bug de SDK ya corregido en docutray@0.1.3.

Problema 1: Round-trip de export/create

docutray types export factura > factura.json ahora (post-#33) produce JSON con esta forma:

{
  "id": "...",
  "codeType": "factura",
  "name": "Factura Electrónica",
  "description": "...",
  "isPublic": true,
  "isDraft": false,
  "status": "PUBLISHED",
  "jsonSchema": { "type": "object", "properties": {}, "required": [] },
  "createdAt": "...",
  "updatedAt": "..."
}

Pero docutray types create --schema factura.json falla o produce un tipo inválido, porque parseSchema() (src/parse-schema.ts) trata el archivo entero como JSON Schema. El --help de export promete "migrating types between environments" — y técnicamente sí está toda la información, pero el round-trip exige jq .jsonSchema factura.json | docutray types create --schema -, que no está documentado.

Fix propuesto

Hacer parseSchema más inteligente: si el JSON parseado tiene una propiedad jsonSchema que es un objeto, usar esa; si no, tratar el contenido como schema directo (comportamiento actual).

export function parseSchema(input: string): Record<string, unknown> {
  const parsed = readAndParse(input)
  if (parsed && typeof parsed === 'object' && 'jsonSchema' in parsed && typeof parsed.jsonSchema === 'object') {
    return parsed.jsonSchema as Record<string, unknown>
  }
  return parsed as Record<string, unknown>
}

Con esto el flujo natural funciona:

docutray types export factura -o factura.json
docutray types create --name "Factura Copy" --code factura_copy \
  --description "..." --schema factura.json

Alternativa considerada y descartada: agregar --schema-only a types export. Es explícito pero rompe el caso de uso "backup completo" del export y obliga al usuario a elegir antes de saber qué necesita. La heurística en parseSchema permite que un mismo archivo sirva para backup y para reimport.

Problema 2: Cast obsoleto en types create

src/commands/types/create.ts:55 tiene:

{key: 'Mode', value: (() => {
  const mode = (result as unknown as Record<string, unknown>).conversionMode
  return typeof mode === 'string' && mode.trim() !== '' ? mode : 'json'
})()},

Este cast existía cuando el SDK devolvía {data: ...} y los campos no estaban en el tipo DocumentType. En docutray@0.1.3 el DocumentType está actualizado y result.conversionMode es accesible directamente — pero hoy el tipo declarado en docutray-node (src/types/document-type.ts) no incluye conversionMode. Verificar:

• Si SDK 0.1.3 incluye conversionMode en DocumentType: limpiar el cast usando acceso directo.
• Si no lo incluye: dejar nota en el SDK (issue separado en docutray-node) y mantener el cast con un comentario que explique por qué.

Criterios de aceptación

• parseSchema detecta payloads {jsonSchema: {...}, ...} y extrae jsonSchema. Si no existe esa key, mantiene comportamiento actual.
• Test que verifica el round-trip: serializar la salida de types get (forma completa de DocumentType) y pasarla a parseSchema, debe devolver el jsonSchema interno.
• Test que verifica que un schema crudo ({type: 'object', properties: {}}) sigue parseándose como antes.
• Examples del --help de types create actualizados para mostrar el flujo export → create con el archivo completo.
• Cast en types create.ts:55 removido si SDK 0.1.3 expone conversionMode en DocumentType; o issue documentado en docutray-node si no.

Prioridad

Bloquea el release 0.3.2. La idea es mergear este fix antes de hacer el tag v0.3.2.

Referencias

• Detectado en review de fix: types get/export now return jsonSchema (closes #32) #33.
• Depende de docutray@0.1.3 (ya en package.json post-fix: types get/export now return jsonSchema (closes #32) #33).