Colecciones externas

Por defecto, builder execute lee project-builder.json — y cada colección, factory y schema que registra — desde el directorio de trabajo. --manifest dirige esas lecturas a otro lugar de la misma máquina, mientras que los archivos generados siguen cayendo en el directorio de trabajo.

El caso que lo motiva son los git worktrees: tus schematics no están commiteados en el repositorio de la aplicación, así que un worktree creado junto al checkout principal no los tiene. Con --manifest, todos los checkouts ejecutan los mismos schematics desde un único lugar.

Dos raíces

Raíz	Qué es	Para qué se usa
Raíz del manifiesto	El directorio indicado por --manifest (o el directorio de trabajo si no se indica)	Todas las lecturas: project-builder.json, collection.json, factories, schema.json, plantillas. Las rutas registradas en el manifiesto se resuelven contra este directorio.
Workspace	El directorio de trabajo	Todas las escrituras: los archivos generados, y el @pbuilder/sdk que usa la ejecución

Sin --manifest, ambas raíces son el directorio de trabajo; por eso normalmente nunca notas la diferencia.

Solo directorios locales

--manifest y BUILDER_MANIFEST aceptan una ruta de esta máquina — nada más. Se rechaza cualquier valor que empiece con un esquema de URL (https://, git://, ssh://, file://) o con una letra de unidad. No se descarga, clona ni cachea nada.

Prepara un directorio compartido de colecciones

Mantén los schematics en un directorio propio, fuera de los checkouts de la aplicación, sin node_modules dentro ni por encima:

~/work/
├── app-schematics/          ← manifest root
│   ├── project-builder.json
│   └── schematics/
│       └── hello/
│           ├── factory.ts
│           ├── schema.json
│           └── schema.generated.ts
├── app/                     ← main checkout
└── app-feature-x/           ← git worktree of app

app-schematics/project-builder.json

{
  "collections": {
    "default": { "hello": { "path": "./schematics/hello" } }
  }
}

La raíz del manifiesto no debe tener su propio SDK

Una factory resuelve @pbuilder/sdk primero desde su propia ubicación. Si la raíz del manifiesto — o cualquier directorio por encima — tiene un node_modules/@pbuilder/sdk, la factory carga esa copia mientras la ejecución usa la copia del workspace. Dos copias nunca se mezclan: la ejecución falla con engine_native_developer_fault y una nota sobre un split module graph, aunque ambas copias sean de la misma versión.

Por eso los schematics guardados dentro del checkout principal, que tiene su propio node_modules, no se pueden ejecutar desde un worktree con --manifest. Muévelos a un directorio propio.

1. Instala el SDK una sola vez, fuera de los checkouts. Debe ser la versión 0.3.1 o posterior: las versiones anteriores no pueden ser cargadas por una factory fuera del workspace.

   bun add -g @pbuilder/sdk

   El directorio del paquete que se crea, ~/.bun/install/global/node_modules/@pbuilder/sdk, es la raíz del SDK. Para otras instalaciones globales, ver qué debe ser la raíz.

2. Ejecuta el schematic indicando ambas raíces. --manifest y --sdk-root van antes de <collection>:<schematic>:

   cd ~/work/app-feature-x
   builder execute --manifest=../app-schematics \
     --sdk-root=$HOME/.bun/install/global/node_modules/@pbuilder/sdk \
     default:hello --name=payments

   La factory y su schema se leen de ~/work/app-schematics; el archivo generado se escribe en ~/work/app-feature-x/src/services/payments.ts. El checkout no necesita un node_modules propio: la única otra entrada que escribe la ejecución es node_modules/@pbuilder/sdk, un enlace a la raíz del SDK.

3. Inspecciona la colección de la misma forma:

   builder info --manifest=../app-schematics default

El mismo comando funciona desde el checkout principal — todos los checkouts, sean worktrees o no, usan el directorio compartido y el SDK compartido.

Un checkout con su propio SDK

El orden en que execute elige un SDK está en Origen del SDK. Dos casos a vigilar:

• Un checkout que ya tiene un node_modules/@pbuilder/sdk real falla con execute_sdk_link_path_conflict cuando indicas otra raíz. Quita esa instalación, o ejecuta ese checkout sin --sdk-root y con BUILDER_SDK_ROOT sin definir, para que la ejecución la use.
• Un node_modules que es un symlink a otro checkout se rechaza por escapar del workspace, con o sin --sdk-root.

Cómo se lee el valor

• Un directorio o el archivo en sí. --manifest=../app-schematics y --manifest=../app-schematics/project-builder.json son equivalentes.
• Relativo o absoluto. Un valor relativo se resuelve contra el directorio de trabajo. La ruta se canonicaliza una sola vez, siguiendo los enlaces simbólicos.
• Indicar el directorio de trabajo equivale a no pasar el flag.
• Ubicación. En execute, --manifest debe ir antes de <collection>:<schematic> — después de él se rechaza con invalid_input en lugar de pasarse al schematic. info lo acepta antes o después de su argumento.

Defínelo una vez con variables de entorno

Las herramientas que lanzan builder dentro de un checkout — scripts, editores, agentes — pueden definir BUILDER_MANIFEST y BUILDER_SDK_ROOT en lugar de pasar los flags. Definidas una vez, permiten que cada checkout ejecute los schematics compartidos con comandos simples:

export BUILDER_MANIFEST=~/work/app-schematics
export BUILDER_SDK_ROOT=~/.bun/install/global/node_modules/@pbuilder/sdk
builder execute default:hello --name=orders

• Cada flag siempre tiene prioridad sobre su variable. Un flag que indica un directorio inutilizable falla por sí mismo; nunca recurre a la variable.
• Cuando BUILDER_MANIFEST apunta a un lugar distinto del directorio de trabajo, cada ejecución imprime la advertencia warn_manifest_root_ambient con la ruta resuelta, para que una configuración ambiental nunca pase desapercibida. Una raíz de BUILDER_SDK_ROOT imprime warn_sdk_root_ambient, que nombra la variable pero no la ruta — revisa la propia variable para saber qué SDK se ejecutó.
• La shell expande ~ en las líneas export de arriba. Un archivo de configuración de un editor o agente no lo hace, así que escribe ahí rutas completas.
• ¿Dejaste de usar BUILDER_SDK_ROOT? El enlace que dejó en cada checkout hace fallar la siguiente ejecución con execute_manifest_path_escape. Ver --sdk-root y BUILDER_SDK_ROOT.

Reglas de confianza

La raíz del manifiesto decide qué código se ejecuta, así que la CLI solo acepta una que nadie más pueda modificar. Rechaza:

• una raíz escribible por su grupo o por otros usuarios;
• una raíz con un directorio por encima escribible por el grupo, o escribible por todos sin el sticky bit;
• una raíz, o un directorio por encima, que pertenezca a un usuario distinto de ti o de root;
• la raíz del sistema de archivos y tu propio directorio home (un directorio dentro de tu home está bien).

Nota

En macOS y en muchos sistemas Linux, /tmp es escribible por su grupo, así que una raíz de manifiesto bajo /tmp se rechaza. Usa un directorio dentro de tu home.

Qué se queda en el workspace

• builder new schematic siempre escribe en el directorio de trabajo. Si --manifest o BUILDER_MANIFEST indican otro directorio, se niega con manifest_scoped_authoring_refused antes de escribir nada. Para crear schematics en el directorio compartido, haz cd a él y ejecuta builder new schematic allí. El directorio compartido no tiene SDK, y new schematic no lee BUILDER_SDK_ROOT, así que el andamiaje omite schema.generated.ts con una advertencia. Regenera los tipos con el script de la propia raíz del SDK — el codegen escribe dentro del proyecto que indiques:

  node $BUILDER_SDK_ROOT/dist/bin/pbuilder-codegen.js --project ~/work/app-schematics

• La configuración del SDK del manifiesto externo se ignora. Un sdk.root o sdk.version en el project-builder.json externo no se usa — el SDK lo aportan --sdk-root, BUILDER_SDK_ROOT o el SDK instalado del workspace, y el package.json propio del workspace fija el requisito de versión. Cuando el manifiesto externo declara un sdk.root, la ejecución advierte con warn_manifest_sdk_root_ignored.

• Los demás comandos no aceptan --manifest: pasarlo a init, por ejemplo, falla con manifest_root_unsupported_command.

Rutas dentro del manifiesto

Cada ruta que registra el manifiesto externo debe ser relativa a la raíz del manifiesto y quedar dentro de ella:

• Un path absoluto falla con collection_absolute_path.
• Una ruta que resuelve fuera de la raíz del manifiesto — por ejemplo ../app/schematics/hello — falla por escapar de la raíz del manifiesto indicada.

Relacionado

• builder execute y builder info — referencia de flags.
• Salida y errores de la CLI — cada error y advertencia de --manifest.
• Evaluar sin adoptar el SDK — usa un SDK en un checkout sin editar package.json.