@iseoane/agent-depot 0.6.0 → 0.6.2

package/CHANGELOG.md

@@ -7,6 +7,43 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.6.2] - 2026-10-13
+
+### Fixed
+
+- Pi Package update comparison no longer treats npm's generated dependency-free
+  root `package-lock.json` as a local checkout change. Any other lockfile, and
+  any tracked modification or additional untracked file, still blocks the
+  comparison.
+
+## [0.6.1] - 2026-10-13
+
+### Added
+
+- The Profile TUI guides export through a folder picker and editable filename,
+  then shows the full destination and a confirmation preview. Import filters for
+  JSON files, can show all files, and keeps the picker open with inline read or
+  parse errors.
+
+### Changed
+
+- `e` exports the complete Profile selection from any checklist row. `Enter`
+  expands groups or previews notes without starting export.
+- Profile export and import previews use semantic colors for resource names,
+  Hosts, version policies, and fields, including wrapped continuation rows.
+
+### Fixed
+
+- Profile import applies the exact previewed subset, including selections after
+  unselected entries.
+- Export ignores stale filename checks after edits and refuses existing files
+  or symlinks without overwriting them. Folder navigation follows symlinked
+  directories and keeps the guidance visible in narrow terminals.
+- Moved bundled-skill tests to `tests/skills/`. `pnpm test:skills` runs each
+  suite in its own Python process with bytecode writes disabled, so tests no
+  longer alter skill trees and cause source-versus-packed hash checks to report
+  false updates.
+
 ## [0.6.0] - 2026-10-12
 
 ### Added

package/README.es.md

@@ -525,7 +525,7 @@ se recortan la pestaña del encabezado y el título de la nota.
 | 2 Catalog | Skills y Packages disponibles, además de App recipes aplicables y aprobadas cuya ausencia se ha verificado. La instalación de una App tiene una previsualización y confirmación separadas. Las recetas inválidas o sin aprobar permanecen en Sources; un estado desconocido nunca se trata como ausencia. Los Packages que el Host confirma como instalados se ocultan; los seleccionados o con estado desconocido siguen visibles. Los Skills propiedad de Packages conservan su comportamiento actual. |
 | 3 Installations | Apps cuya instalación está confirmada, instalaciones de Skills gestionadas (globales de usuario y de proyecto), selecciones de Packages con pertenencia al Host y evidencia de versión mostradas por separado, y Skills globales de usuario no gestionados. Un registro de instalación de App permanece visible aunque caduque la aprobación de la receta, pero sus acciones siguen exigiendo aprobación vigente. |
 | 4 Updates | Skills gestionados en el ámbito global de usuario y de proyecto, además de Apps y Packages instalados globales de usuario con una versión más reciente disponible. Las Apps desconocidas o no verificadas no se tratan como instaladas. |
-| 5 Profile | Exportar o importar elecciones portables de Sources globales de usuario, selecciones individuales de Skills, App recipes y selecciones de Packages. Las réplicas solo identifican recursos cuya instalación se confirmó en el origen. |
+| 5 Profile | Exporta o importa elecciones globales de usuario. Consulta el [flujo de Profile](#flujo-de-profile) para ver la lista y los pasos del selector de archivos. |
 
 Teclas por vista (los avisos también aceptan `Esc` para cancelar y `y`/`n` para
 confirmar):
@@ -536,9 +536,73 @@ confirmar):
 | Catalog | `Enter`/flechas expanden y contraen; `space` marca el Skill disponible resaltado; `a` marca o desmarca los Skills disponibles visibles de su Source; `i` inicia la instalación de los Skills marcados o del Skill, Package o App aprobada cuya ausencia se verificó y que está resaltada. Confirma la instalación de una App por separado con `y`. `/` filtra y `s` amplía la vista de una Source a todas. Las marcas de otras Sources se conservan y no se instalan Skills ocultos por el filtro. |
 | Installations | `Enter`/flechas expanden y contraen. En filas globales de usuario, `u` inicia la desinstalación de una App o Skill gestionada, o elimina un Skill no gestionado; los Skills de proyecto no se pueden eliminar. `h` o `i` añade Hosts a una instalación global de usuario, y `A` o `Enter` adopta un Skill no gestionado. `space` marca una hoja y `a` marca todas las hojas visibles; las acciones por lotes omiten instalaciones de proyecto con un motivo. En una fila de App, `u` previsualiza la desinstalación y `h` selecciona setup/teardown; las recetas modificadas requieren una nueva aprobación. En una fila de Package, `i` previsualiza el plan de instalación congelado y lo ejecuta, aprobando antes el recibo si falta; `Enter` solo aprueba la declaración de instalación; `U` actualiza, `u` desinstala y `f` olvida el registro de selección. Las filas de Package no se pueden marcar para acciones por lotes. |
 | Updates | `space` marca una actualización, `a` marca todas las actualizaciones disponibles y `t`/`p`/`g` selecciona todo, el ámbito de proyecto o el global de usuario. `Enter` previsualiza las filas marcadas; `u` previsualiza el lote seleccionado; ninguna aplica actualizaciones. `r` vuelve a comprobar y las flechas izquierda/derecha pliegan o despliegan el grupo "cannot be checked". En una previsualización, las flechas o PageUp/PageDown avanzan una página visible y `j`/`k` una fila. Revisa todas las filas antes de `y`; `n` cancela. Las filas desconocidas son informativas. Packages y Apps solo se gestionan en el ámbito global de usuario; Packages requieren aprobación de acción antes de ejecutar una actualización. |
-| Profile | `e` exportar, `i` importar; introduce una ruta de archivo, `space` alterna opciones, `a` alterna todas, `Enter` previsualiza, `y` aplica; `j`/`k` desplazan las previsualizaciones y los resultados |
-
-Las previsualizaciones desplazables muestran todas las declaraciones y los términos de ejecución. Usa `j`/`k` para avanzar una fila, o las flechas y `PageUp`/`PageDown` para avanzar una página visible. Confirma solo después de mostrar cada fila física. Si cambias el tamaño del terminal, revisa las filas que aún no se han mostrado.
+| Profile | Pulsa `e` para exportar o `i` para importar. Consulta el [flujo de Profile](#flujo-de-profile) para ver la navegación, la selección, las previsualizaciones y las cancelaciones. |
+
+### Flujo de Profile
+
+La vista Profile transfiere elecciones portables globales de usuario. No
+transfiere instalaciones ni aprobaciones. Exportación e importación empiezan en
+la raíz del proyecto, salvo que la aplicación indique otro directorio inicial.
+
+#### Exportar
+
+1. Pulsa `e` en la vista Profile para crear y abrir la lista de exportación.
+   El grupo **Sources**, contraído al inicio, contiene grupos anidados para
+   Sources, Skills, Apps y Packages. **Installed replicas** y **Export notes**
+   son grupos separados. Pulsa `Enter` o las flechas para expandir o contraer un
+   grupo. `Enter` sobre una nota de exportación muestra sus detalles; nunca
+   inicia la exportación.
+2. Usa `j`/`k` o las flechas para moverte, `space` para alternar una fila
+   seleccionable y `a` para seleccionar todo o borrar la selección. Los
+   elementos excluidos y las filas informativas no se pueden seleccionar.
+   Pulsa `e` para exportar las filas seleccionadas. Si no hay ningún recurso
+   portable seleccionado, no se escribe nada. Pulsa `Esc` para salir de la
+   lista.
+3. Elige una carpeta de destino. Muévete con `j`/`k` o las flechas; pulsa
+   `Enter` para abrir una carpeta o selecciona **Use this folder** para elegir
+   la carpeta actual. Usa Izquierda o Retroceso para subir a la carpeta
+   superior. Pulsa `p` para mostrar la ruta completa y otra vez `p` para volver
+   al listado. `Esc` vuelve a la lista de exportación.
+4. Edita el nombre del archivo. El valor predeterminado es
+   `agent-depot-profile.json`. `Ctrl+U` borra el nombre y se añade `.json` si
+   falta una extensión. El editor muestra la ruta completa de destino. Pulsa
+   `Enter` para revisarla. Si la ruta ya existe, incluido un enlace simbólico,
+   aparece un error en línea y puedes elegir otro nombre; la exportación nunca
+   sobrescribe. `Esc` vuelve al selector de carpetas.
+5. Revisa la previsualización de exportación, incluidas las exclusiones y
+   advertencias. Usa `j`/`k` para avanzar una fila y las flechas o
+   `PageUp`/`PageDown` para avanzar una página visible. Pulsa `y` para escribir
+   el archivo nuevo. Pulsa `n` o `Esc` para cancelar y volver al editor del
+   nombre. Los resultados muestran la ruta final.
+
+#### Importar
+
+1. Pulsa `i` en la vista Profile para abrir el selector de archivos. Al
+   principio muestra archivos `.json` y carpetas. Pulsa `f` para mostrar todos
+   los archivos y otra vez `f` para filtrar de nuevo por `.json`. Navega con
+   `j`/`k` o las flechas; pulsa `Enter` para abrir una carpeta o seleccionar un
+   archivo, e Izquierda o Retroceso para subir a la carpeta superior. Pulsa `p`
+   para mostrar la ruta completa y otra vez `p` para volver. `Esc` vuelve a la
+   vista Profile.
+2. El archivo seleccionado se analiza y previsualiza. Si no se puede leer o
+   no es válido, aparece un error en línea y el selector permanece abierto para
+   elegir otro archivo. La lista de importación marca cada elemento como
+   **add**, **same** (omitido) o **conflict** (omitido, con las diferencias).
+   Solo se pueden seleccionar las adiciones. Usa `space` para alternar una
+   fila, `a` para seleccionar todas las adiciones o borrar la selección, y
+   `Enter` para previsualizar las adiciones seleccionadas. `Esc` vuelve a la
+   vista Profile.
+3. Revisa la previsualización exacta de importación. Usa `j`/`k` para avanzar
+   una fila y las flechas o `PageUp`/`PageDown` para una página visible. Pulsa
+   `y` para aplicar las adiciones seleccionadas, o `n`/`Esc` para cancelar y
+   volver a la lista de importación. Se informa del resultado de cada elemento;
+   un fallo no detiene las demás adiciones.
+
+Las recetas importadas siguen sin aprobarse. La importación no instala Apps ni
+Packages ni ejecuta comandos del Host. Las réplicas solo describen identidades
+en la máquina de origen; no transfieren aprobaciones ni estado de instalación.
+
+Las demás previsualizaciones desplazables de la TUI muestran todas las declaraciones y los términos de ejecución. Usa `j`/`k` para avanzar una fila o las flechas y `PageUp`/`PageDown` para avanzar una página visible. Confirma solo después de mostrar cada fila física. Si cambias el tamaño del terminal, revisa las filas que aún no se han mostrado.
 
 Al eliminar una receta App se comprueban su comando de versión aprobado y su
 seguimiento. Si la App está instalada o sigue registrada, la TUI ofrece el flujo
@@ -612,8 +676,14 @@ Desde un checkout de código fuente, compila y ejecuta la CLI directamente:
 pnpm install
 pnpm build
 node dist/src/cli.js --version
+pnpm test:skills
 ```
 
+`pnpm test:skills` ejecuta los tests de la biblioteca estándar de Python
+ubicados en `tests/skills/`. Inicia un proceso Python separado para cada skill
+incluida y define `PYTHONDONTWRITEBYTECODE=1`, por lo que los tests no crean
+archivos de bytecode en los directorios de las skills.
+
 ## Análisis estático
 
 [Fallow](https://docs.fallow.tools) 3.30.0 se ejecuta mediante `npx --yes fallow@3.30.0`
@@ -1024,13 +1094,24 @@ La pestaña **5 Import/Export** de la TUI empieza con el grupo padre **Sources**
 contraído. Dentro contiene grupos anidados para elecciones de Source, Skills, Apps y
 Packages; cada recurso muestra la identidad de su Source. **Installed replicas** y las
 notas de exportación son grupos separados. Usa las mismas previsualizaciones del núcleo
-compartido que la CLI. Las réplicas identifican recursos cuya instalación se confirmó
-en la máquina de origen; no incluyen el estado de instalación, las aprobaciones ni el
-contenido completo de la máquina. La importación solo añade; nunca transfiere
-aprobaciones ni instala automáticamente Apps o Packages. Las exclusiones y los conflictos
-no pueden seleccionarse. La exportación solo crea un archivo nuevo; las
-exportaciones vacías no escriben nada (la CLI informa de un error). La importación
-añade las elecciones que faltan sin reemplazar las existentes. Las recipes importadas
-permanecen sin aprobar y la importación nunca instala Apps. Las selecciones de Package
-importadas se registran sin instalar ningún bundle y sin ejecutar ningún comando del
-Host.
+compartido que la CLI.
+`e` exporta toda la selección marcada desde cualquier fila; `Enter` solo expande un grupo
+o previsualiza una nota, así que navegar nunca inicia una escritura. Las réplicas
+identifican recursos cuya instalación se confirmó en la máquina de origen; no incluyen el
+estado de instalación, las aprobaciones ni el contenido completo de la máquina. La
+importación solo añade; nunca transfiere aprobaciones ni instala automáticamente Apps o
+Packages. Las exclusiones y los conflictos no pueden seleccionarse.
+
+La exportación y la importación comparten un navegador de directorios que empieza en la
+raíz del proyecto, lista carpetas (y, al importar, archivos `.json`) y se mueve con
+`j`/`k` o las flechas. La exportación elige una carpeta y luego rellena
+`agent-depot-profile.json` en un campo editable que muestra el destino completo;
+`Ctrl+U` lo borra, un nombre sin extensión recibe `.json`, y un archivo o enlace
+simbólico existente se rechaza en ese paso para volver a escribirlo. La importación
+navega hasta un archivo existente; `f` alterna entre archivos `.json` y todos los
+archivos, y un archivo mal formado informa en línea mientras el navegador sigue abierto.
+La exportación solo crea un archivo nuevo; las exportaciones vacías no escriben nada (la
+CLI informa de un error). La importación añade las elecciones que faltan sin reemplazar
+las existentes. Las recipes importadas permanecen sin aprobar y la importación nunca
+instala Apps. Las selecciones de Package importadas se registran sin instalar ningún
+bundle y sin ejecutar ningún comando del Host.

package/README.md

@@ -476,7 +476,7 @@ review Profile export notes; at 24 columns, the app header tab and note title cl
 | 2 Catalog | Available Skills and Packages, plus applicable approved App recipes verified as not installed. App installation has a separate preview and confirmation. Invalid or unapproved recipes remain in Sources; unknown App state is never treated as absence. Host-confirmed installed Packages are hidden; selected-only or unknown-state Packages remain visible. Package-owned Skills keep their existing behavior. |
 | 3 Installations | Confirmed installed Apps, managed Skill installations (user-global and project), Package selections with Host membership and version evidence shown separately, and unmanaged user-global Skills. App installation records remain visible if recipe approval later expires, but recipe actions still require current approval. |
 | 4 Updates | Managed Skills in project and user-global scope, plus user-global installed Apps and Packages with a newer version available. Unknown or unverified Apps are not treated as installed. |
-| 5 Profile | Export or import portable user-global Source choices, individual Skill selections, App recipes and Package selections. Replica entries report confirmed origin-machine identities only. |
+| 5 Profile | Export or import portable user-global choices. See [Profile workflow](#profile-workflow) for the complete checklist and file-picker steps. |
 
 Keys per view (prompts also accept `Esc` to cancel and `y`/`n` to confirm):
 
@@ -486,9 +486,66 @@ Keys per view (prompts also accept `Esc` to cancel and `y`/`n` to confirm):
 | Catalog | `Enter`/arrows expand and collapse, `space` marks the highlighted loose Skill, `a` marks or clears the visible loose Skills in its Source, and `i` starts installation for marked Skills or the highlighted Skill, Package, or verified-absent approved App. Confirm an App install separately with `y`. `/` filters and `s` widens a Source view to all Sources. Marks in other Sources remain unchanged; Skills hidden by the filter are not installed. |
 | Installations | `Enter`/arrows expand and collapse. On user-global rows, `u` starts an App or managed Skill uninstall, or removes an unmanaged Skill; project Skills cannot be removed. `h` or `i` adds Hosts to a user-global Skill installation, and `A` or `Enter` adopts an unmanaged Skill. `space` marks a leaf and `a` marks all visible leaves; bulk actions skip project installations with a reason. On an App row, `u` previews uninstall and `h` selects setup/teardown; changed recipes must be approved again before commands run. On a Package row, `i` previews the frozen install plan and runs it, approving the receipt first when it is missing; `Enter` approves the install declaration only, `U` updates, `u` uninstalls, and `f` forgets the selection record. Package rows are not markable for bulk actions. |
 | Updates | `space` marks an update, `a` marks all available updates, and `t`/`p`/`g` selects all, project, or user-global scope. `Enter` previews the marked rows; `u` previews the selected batch; neither applies updates. `r` checks again, and left/right arrows fold or unfold the "cannot be checked" group. In a preview, arrows or PageUp/PageDown move by a visible page and `j`/`k` move one row. Review every row before `y`; `n` cancels. Unknown rows are informational. Packages and Apps are user-global only; Packages need action approval before update execution. |
-| Profile | `e` export, `i` import; enter a file path, `space` toggle choices, `a` toggle all, `Enter` preview, `y` apply; `j`/`k` scroll previews and results |
-
-Scrollable previews show every declaration and execution term. Use `j`/`k` to move one row, or the arrows and `PageUp`/`PageDown` to move by a visible page. Confirm only after every physical row has been displayed. Resizing a preview requires reviewing any rows that have not yet been displayed.
+| Profile | Press `e` to export or `i` to import. See [Profile workflow](#profile-workflow) for navigation, selection, previews, and cancellation. |
+
+### Profile workflow
+
+The Profile view transfers portable user-global choices. It does not transfer
+installed state or approvals. Export and import begin in the project root, unless
+the application supplies another start directory.
+
+#### Export
+
+1. Press `e` in the Profile view to build and open the export checklist. Its
+   collapsed **Sources** group contains nested Source, Skill, App, and Package
+   choices. **Installed replicas** and **Export notes** are separate groups.
+   Expand or collapse a group with `Enter` or the arrow keys. `Enter` on an
+   export note opens its details; it never starts an export.
+2. Use `j`/`k` or the arrows to navigate, `space` to toggle a selectable row,
+   and `a` to select all or clear all. Excluded items and informational rows
+   cannot be selected. Press `e` to export the selected rows. If no portable
+   resource is selected, nothing is written. Press `Esc` to leave the checklist.
+3. Choose a destination folder. Move with `j`/`k` or the arrows, press `Enter`
+   to open a folder, or select **Use this folder** to choose the current one.
+   Use Left or Backspace to go to the parent. Press `p` to show the full
+   directory path; press `p` again to return to the listing. `Esc` returns to
+   the checklist.
+4. Edit the file name. The default is `agent-depot-profile.json`. `Ctrl+U`
+   clears the name, and a name without an extension gets `.json`. The editor
+   shows the complete destination path. Press `Enter` to review it. If the path
+   already exists, including a symlink, the view reports an inline error and
+   lets you choose another name; export never overwrites. `Esc` returns to the
+   folder picker.
+5. Review the export preview, including exclusions and warnings. Use `j`/`k`
+   to move one row and the arrows or `PageUp`/`PageDown` to move by a visible
+   page. Press `y` to write the new file, `n` or `Esc` to cancel and return to
+   the name editor. Results show the final path.
+
+#### Import
+
+1. Press `i` in the Profile view to open the file picker. It initially lists
+   `.json` files and folders. Press `f` to show every file, `f` again to filter
+   back to `.json`. Navigate with `j`/`k` or the arrows, use `Enter` to open a
+   folder or select a file, and Left or Backspace to go to the parent. Press
+   `p` to show the full directory path and `p` again to return. `Esc` returns
+   to the Profile view.
+2. The selected file is parsed and previewed. If it is invalid or cannot be
+   read, an inline error appears and the picker stays open so you can choose
+   another file. The import list marks entries as **add**, **same** (skipped), or
+   **conflict** (skipped with differences). Only additions can be selected. Use
+   `space` to toggle a row, `a` to select all additions or clear them, and
+   `Enter` to preview the selected additions. Press `Esc` to return to the
+   Profile view.
+3. Review the exact import preview. Use `j`/`k` for one row and the arrows or
+   `PageUp`/`PageDown` for a visible page. Press `y` to apply the selected
+   additions, or `n`/`Esc` to cancel and return to the import list. Each result
+   is reported; an item failure does not stop the remaining additions.
+
+Imported recipes remain unapproved. Import does not install Apps or Packages or
+run Host commands. Replica entries describe identity on the exporting machine
+only. They do not confer approval or installed state.
+
+Scrollable previews elsewhere in the TUI show every declaration and execution term. Use `j`/`k` to move one row, or the arrows and `PageUp`/`PageDown` to move by a visible page. Confirm only after every physical row has been displayed. Resizing a preview requires reviewing any rows that have not yet been displayed.
 
 Removing an App recipe checks its approved version command and tracked state.
 If the App is installed or tracked, the TUI offers the existing uninstall flow;
@@ -558,8 +615,14 @@ From a source checkout, build and run the CLI directly:
 pnpm install
 pnpm build
 node dist/src/cli.js --version
+pnpm test:skills
 ```
 
+`pnpm test:skills` runs the Python standard-library tests from `tests/skills/`.
+It starts a separate Python process for each bundled skill and sets
+`PYTHONDONTWRITEBYTECODE=1`, so the tests do not create bytecode files in the
+skill directories.
+
 ## Static analysis
 
 [Fallow](https://docs.fallow.tools) 3.30.0 runs through `npx --yes fallow@3.30.0`
@@ -934,11 +997,20 @@ rows explain when discovery inclusion differs but is not imported.
 The **5 Import/Export** TUI tab starts with a collapsed **Sources** parent. It
 contains nested Source choices, Skills, Apps, and Packages groups; resource rows show
 their Source identities. **Installed replicas** and export notes are separate groups.
-Replica entries identify resources confirmed installed on the exporting machine.
-They do not contain installed state, approvals, or full machine contents. Import is
-add-only; it never transfers approval or automatically installs Apps or Packages.
-Exclusions and conflicts cannot be selected. Export creates
-a new file only; empty exports write nothing (CLI reports an error). Import adds missing choices without replacing existing ones.
-Imported recipes remain unapproved and Apps are never installed by import.
-Imported Package selections are recorded without installing a bundle and without
-running a Host command.
+`e` exports the whole marked selection from any row; `Enter` only expands a group or
+previews a note, so browsing never starts a write. Replica entries identify resources
+confirmed installed on the exporting machine. They do not contain installed state,
+approvals, or full machine contents. Import is add-only; it never transfers approval or
+automatically installs Apps or Packages. Exclusions and conflicts cannot be selected.
+
+Export and import share one directory browser that starts at the project root, lists
+folders (and, for import, `.json` files), and moves with `j`/`k` or the arrows. Export
+picks a folder, then pre-fills `agent-depot-profile.json` in an editable name field that
+shows the complete destination; `Ctrl+U` clears it, a name without an extension gains
+`.json`, and an existing file or symlink is refused at that step so you can retype.
+Import browses to an existing file; `f` switches between `.json` files and every file,
+and a malformed file reports inline while the browser stays open. Export creates a new
+file only; empty exports write nothing (CLI reports an error). Import adds missing
+choices without replacing existing ones. Imported recipes remain unapproved and Apps
+are never installed by import. Imported Package selections are recorded without
+installing a bundle and without running a Host command.

package/dist/src/package-host-state.js

@@ -258,7 +258,9 @@ async function readPiCheckoutEvidence(checkoutPath, sourceIdentity) {
         const version = isRecord(packageJson) && typeof packageJson.version === "string" && packageJson.version.trim() !== ""
             ? packageJson.version
             : undefined;
-        if (status !== "") {
+        const generatedRootLock = status === "?? package-lock.json"
+            && await isMatchingRootOnlyNpmLock(checkoutPath, packageJson);
+        if (status !== "" && !generatedRootLock) {
             return {
                 ...(version === undefined ? {} : { version }),
                 issue: `Pi reports this Package installed, but the Pi Git checkout has local modifications. Update assessment is unavailable; inspect the checkout before updating.`,
@@ -276,6 +278,48 @@ async function readPiCheckoutEvidence(checkoutPath, sourceIdentity) {
         return unavailable(reason);
     }
 }
+/** Recognize only npm's dependency-free generated root lock, never tracked edits. */
+async function isMatchingRootOnlyNpmLock(checkoutPath, manifest) {
+    try {
+        if (!isRecord(manifest))
+            return false;
+        const lockPath = path.join(checkoutPath, "package-lock.json");
+        await assertNoSymlinkPath(lockPath, "Pi generated lockfile");
+        const stat = await lstat(lockPath);
+        if (!stat.isFile() || stat.size > 64 * 1024)
+            return false;
+        const lock = JSON.parse(await readFile(lockPath, "utf8"));
+        if (!isRecord(lock) || lock.lockfileVersion !== 3 || lock.requires !== true
+            || typeof manifest.name !== "string" || typeof manifest.version !== "string"
+            || lock.name !== manifest.name || lock.version !== manifest.version
+            || Object.keys(lock).some((key) => !["name", "version", "lockfileVersion", "requires", "packages"].includes(key))
+            || !isRecord(lock.packages) || Object.keys(lock.packages).length !== 1)
+            return false;
+        const root = lock.packages[""];
+        if (!isRecord(root) || root.name !== manifest.name || root.version !== manifest.version)
+            return false;
+        // Ordinary dependencies mean this is more than the harmless root-only artifact.
+        for (const key of ["dependencies", "devDependencies", "optionalDependencies"]) {
+            if (manifest[key] !== undefined && (!isRecord(manifest[key]) || Object.keys(manifest[key]).length !== 0))
+                return false;
+        }
+        const allowed = ["name", "version", "license", "peerDependencies", "peerDependenciesMeta"];
+        const equalJson = (left, right) => {
+            if (left === right)
+                return true;
+            if (!isRecord(left) || !isRecord(right))
+                return false;
+            const keys = Object.keys(left);
+            return keys.length === Object.keys(right).length
+                && keys.every((key) => Object.hasOwn(right, key) && equalJson(left[key], right[key]));
+        };
+        return Object.keys(root).every((key) => allowed.includes(key) && equalJson(root[key], manifest[key]))
+            && ["peerDependencies", "peerDependenciesMeta"].every((key) => equalJson(root[key], manifest[key]));
+    }
+    catch {
+        return false;
+    }
+}
 async function runPiGit(checkoutPath, args) {
     const result = await runProcess("git", ["-C", checkoutPath, ...args], {
         captureStdout: true,

package/dist/src/tui/file-picker-model.js

@@ -0,0 +1,87 @@
+import { lstat, readdir, stat } from "node:fs/promises";
+import path from "node:path";
+/** The portable Profile artifact extension; import shows only these files until `f`. */
+export const PROFILE_EXTENSION = ".json";
+/** The pre-filled export file name; `Ctrl+U` clears it and a missing extension gains `.json`. */
+export const DEFAULT_PROFILE_FILE_NAME = "agent-depot-profile.json";
+/** The directory an export or import browser opens in. Tests inject `startDirectory`. */
+export function pickerStartDirectory(environment) {
+    return path.resolve(environment.startDirectory ?? environment.projectRoot ?? process.cwd());
+}
+export function isProfileFileName(name) {
+    return path.extname(name).toLowerCase() === PROFILE_EXTENSION;
+}
+/** Directories first, then files, each in code-point order, so the list is stable across platforms. */
+export function sortDirectoryEntries(entries) {
+    return [...entries].sort((left, right) => {
+        if (left.kind !== right.kind)
+            return left.kind === "directory" ? -1 : 1;
+        return left.name < right.name ? -1 : left.name > right.name ? 1 : 0;
+    });
+}
+/** Read one directory into the picker's listing shape; symlinked directories are followed. */
+export async function readDirectoryListing(directory) {
+    const dirents = await readdir(directory, { withFileTypes: true });
+    const entries = [];
+    for (const dirent of dirents) {
+        let isDirectory = dirent.isDirectory();
+        if (!isDirectory && dirent.isSymbolicLink()) {
+            try {
+                isDirectory = (await stat(path.join(directory, dirent.name))).isDirectory();
+            }
+            catch {
+                isDirectory = false;
+            }
+        }
+        entries.push({ name: dirent.name, kind: isDirectory ? "directory" : "file" });
+    }
+    const parent = path.dirname(directory);
+    return { directory, parent: parent === directory ? undefined : parent, entries: sortDirectoryEntries(entries) };
+}
+/** The rows a listing shows: folders for both purposes, files only for `file`, filtered by `f`. */
+export function pickerEntries(listing, purpose, showAllFiles) {
+    return listing.entries.filter(entry => {
+        if (entry.kind === "directory")
+            return true;
+        if (purpose === "directory")
+            return false;
+        return showAllFiles || isProfileFileName(entry.name);
+    });
+}
+/**
+ * Validate a typed file name and give it a JSON extension when it has none.
+ * Separators and the dot directories are refused so the name stays inside the chosen folder.
+ */
+export function resolveExportFileName(input) {
+    if (input === "")
+        return { kind: "invalid", message: "Enter a file name." };
+    if (input === "." || input === "..")
+        return { kind: "invalid", message: "A file name cannot be . or .." };
+    if (input.includes("/") || input.includes("\\"))
+        return { kind: "invalid", message: "A file name cannot contain / or \\." };
+    if (path.extname(input) === "")
+        return { kind: "ok", fileName: `${input}${PROFILE_EXTENSION}`, appendedExtension: true };
+    return { kind: "ok", fileName: input, appendedExtension: false };
+}
+/** The full destination path, shown live in the name editor and in the confirmation. */
+export function exportDestination(directory, fileName) {
+    return path.join(directory, fileName);
+}
+/** A note when the name keeps an extension other than `.json`; `undefined` when nothing needs explaining. */
+export function fileNameNotice(fileName) {
+    const extension = path.extname(fileName);
+    if (extension === "" || extension.toLowerCase() === PROFILE_EXTENSION)
+        return undefined;
+    return `Keeping the ${extension} extension; import lists ${PROFILE_EXTENSION} files by default; press f to show all files.`;
+}
+export async function pathExists(target) {
+    try {
+        await lstat(target);
+        return true;
+    }
+    catch (error) {
+        if (error instanceof Error && "code" in error && error.code === "ENOENT")
+            return false;
+        throw error;
+    }
+}

package/dist/src/tui/file-picker.js

@@ -0,0 +1,142 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import path from "node:path";
+import { Text, useWindowSize } from "ink";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { pickerEntries, readDirectoryListing, PROFILE_EXTENSION } from "./file-picker-model.js";
+import { useKeys } from "./keys.js";
+import { moveCursor } from "./mode-keys.js";
+import { BorderPanel } from "./panel-parts.js";
+import { clipText, wrapText } from "./text-wrap.js";
+import { theme } from "./theme.js";
+import { useMirrored, useMounted } from "./view-state.js";
+import { computeWindow, useListHeight } from "./window.js";
+/**
+ * A picker callback changes the enclosing view's stage. Defer it so the view's own key
+ * handler, which runs in the same event, still sees the picker stage and ignores the key.
+ */
+function settle(action) {
+    queueMicrotask(action);
+}
+/**
+ * A keyboard-only directory and file browser. It owns its keys while mounted, so the
+ * enclosing view must ignore its own bindings in the picker's stages. Each read carries a
+ * request generation, so a slow listing never overwrites a newer directory or an unmount.
+ */
+export function FilePicker({ purpose, startDirectory, notice, onCancel, onChoose, listHeight, readDirectory = readDirectoryListing }) {
+    const [state, setState] = useState({ status: "loading", directory: startDirectory });
+    const [cursor, cursorRef, cursorTo] = useMirrored(0);
+    const [showAllFiles, showAllFilesRef, setShowAllFiles] = useMirrored(false);
+    const [showFullPath, setShowFullPath] = useState(false);
+    const requestId = useRef(0);
+    const mounted = useMounted();
+    const { columns } = useWindowSize();
+    const panelWidth = Math.max((columns || 80) - 4, 1);
+    const navigate = useCallback((directory) => {
+        const id = ++requestId.current;
+        cursorTo(0);
+        setState({ status: "loading", directory });
+        void readDirectory(directory).then(listing => {
+            if (!mounted.current || requestId.current !== id)
+                return;
+            setState({ status: "ready", directory: listing.directory, parent: listing.parent, entries: listing.entries });
+        }, (error) => {
+            if (!mounted.current || requestId.current !== id)
+                return;
+            setState({ status: "error", directory, message: error instanceof Error ? error.message : String(error) });
+        });
+    }, [cursorTo, mounted, readDirectory]);
+    useEffect(() => { navigate(startDirectory); }, [navigate, startDirectory]);
+    const entries = state.status === "ready" ? pickerEntries(state, purpose, showAllFiles) : [];
+    const rows = useMemo(() => {
+        const parent = state.status === "ready" && state.parent !== undefined ? [{ kind: "parent" }] : [];
+        const listing = entries.map(entry => ({ kind: "entry", entry }));
+        const useFolder = state.status === "ready" && purpose === "directory" ? [{ kind: "use-folder" }] : [];
+        return [...useFolder, ...parent, ...listing];
+    }, [entries, purpose, state]);
+    const choose = (row) => {
+        if (!row || state.status !== "ready")
+            return;
+        if (row.kind === "use-folder") {
+            settle(() => onChoose({ kind: "directory", directory: state.directory }));
+            return;
+        }
+        if (row.kind === "parent") {
+            if (state.parent !== undefined)
+                navigate(state.parent);
+            return;
+        }
+        const target = path.join(state.directory, row.entry.name);
+        if (row.entry.kind === "directory")
+            navigate(target);
+        else
+            settle(() => onChoose({ kind: "file", file: target, directory: state.directory }));
+    };
+    useKeys((input, key) => {
+        if (key.escape) {
+            settle(onCancel);
+            return;
+        }
+        if (showFullPath) {
+            if (input === "p")
+                setShowFullPath(false);
+            return;
+        }
+        if (state.status !== "ready") {
+            const fallbackParent = path.dirname(state.directory);
+            if ((key.backspace || key.leftArrow) && fallbackParent !== state.directory)
+                navigate(fallbackParent);
+            return;
+        }
+        if (key.backspace || key.leftArrow) {
+            if (state.parent !== undefined)
+                navigate(state.parent);
+            return;
+        }
+        if (input === "f" && purpose === "file") {
+            setShowAllFiles(!showAllFilesRef.current);
+            cursorTo(0);
+            return;
+        }
+        if (input === "p") {
+            setShowFullPath(true);
+            return;
+        }
+        const next = moveCursor(cursorRef.current, rows.length, input, key);
+        if (next !== undefined) {
+            cursorTo(Math.max(next, 0));
+            return;
+        }
+        if (key.return)
+            choose(rows[Math.min(cursorRef.current, rows.length - 1)]);
+    });
+    const directory = state.directory;
+    const wrappedDirectory = wrapText(`Directory: ${directory}`, panelWidth);
+    const directoryLines = showFullPath || wrappedDirectory.length <= 3
+        ? wrappedDirectory
+        : [wrappedDirectory[0], ...wrapText(`… ${wrappedDirectory.length - 2} lines · press p for full path`, panelWidth), wrappedDirectory.at(-1)];
+    const ordinaryFooterLines = (purpose === "directory"
+        ? ["j/k move · Enter open/use · ←", "parent · p full path · Esc back"]
+        : ["j/k move · Enter open · ← parent", `f ${showAllFiles ? "json only" : "all files"} · p full path · Esc back`])
+        .flatMap(line => wrapText(line, panelWidth));
+    const noticeLines = notice === undefined ? [] : wrapText(notice, panelWidth);
+    const filterNoteLines = !showFullPath && purpose === "file" && state.status === "ready" && !showAllFiles
+        ? wrapText(`Showing ${PROFILE_EXTENSION} only · f shows all files`, panelWidth)
+        : [];
+    const statusLineCount = !showFullPath && (state.status === "loading" || state.status === "error" || (state.status === "ready" && rows.length === 0)) ? 1 : 0;
+    const visibleNoticeLines = showFullPath ? [] : noticeLines;
+    const footerLines = showFullPath ? wrapText("p hide path · Esc back", panelWidth) : ordinaryFooterLines;
+    const reservesWindowIndicator = !showFullPath && rows.length > 0 && listHeight === undefined ? 1 : 0;
+    const reserved = 3 + directoryLines.length + statusLineCount + filterNoteLines.length + visibleNoticeLines.length + footerLines.length + reservesWindowIndicator;
+    const available = useListHeight(listHeight, reserved, 1);
+    const height = rows.length > available && listHeight !== undefined ? Math.max(available - 1, 1) : available;
+    const window = computeWindow(rows.length, cursor, height);
+    const listedRows = showFullPath ? [] : rows.slice(window.start, window.end);
+    return (_jsxs(BorderPanel, { title: purpose === "directory" ? "Choose export folder" : "Choose import file", children: [directoryLines.map((line, index) => _jsx(Text, { color: theme.value, children: line }, index)), !showFullPath && state.status === "loading" ? _jsx(Text, { color: theme.muted, children: "Loading\u2026" }) : null, !showFullPath && state.status === "error" ? _jsxs(Text, { color: theme.error, children: ["Error: ", clipText(state.message, panelWidth)] }) : null, !showFullPath && state.status === "ready" && rows.length === 0 ? _jsx(Text, { color: theme.muted, children: "Empty folder" }) : null, filterNoteLines.map((line, index) => _jsx(Text, { color: theme.muted, children: line }, `filter-${index}`)), listedRows.map((row, position) => {
+                const index = window.start + position;
+                const marker = index === cursor ? "> " : "  ";
+                const label = row.kind === "use-folder" ? `Use this folder: ${directory}`
+                    : row.kind === "parent" ? ".. (parent folder)"
+                        : row.entry.kind === "directory" ? `${row.entry.name}/` : row.entry.name;
+                return _jsxs(Text, { children: [_jsx(Text, { color: theme.field, children: marker }), _jsx(Text, { color: theme.value, children: clipText(label, Math.max(panelWidth - 2, 1)) })] }, index);
+            }), visibleNoticeLines.map((line, index) => _jsx(Text, { color: theme.warning, children: line }, `notice-${index}`)), footerLines.map((line, index) => _jsx(Text, { color: theme.legend, children: line }, `footer-${index}`)), !showFullPath && window.indicator ? _jsx(Text, { color: theme.muted, children: window.indicator }) : null] }));
+}