ftp-deploy-mcp 0.0.0-stage → 0.3.1

package/docs/RELEASE.md

@@ -0,0 +1,435 @@
+# Release Guide
+
+**English** | [Français](./RELEASE.fr.md)
+
+This is the maintainer checklist for the GitHub source release v0.3.1 and,
+separately, a future first npm and Official MCP Registry publication. A GitHub
+release does not make the npm identifier, `npx` command or registry entry
+available. The published GitHub v0.3.0 tag and release remain immutable.
+
+Check available source assets on [GitHub Releases](https://github.com/alebgl77/ftp-deploy-mcp/releases/latest).
+The npm and MCP workflows are manual (`workflow_dispatch`); do not dispatch
+them as part of a source-only GitHub release.
+
+The MCP runtime supports Node.js >=22. Release tooling requires **Node.js 24.20.0 exactly**: archive creation and inspection, source inventories, installed-graph checks, registry verification and `npm run test:release` reject other versions before performing those operations. Use the qualified Node distribution, including its bundled npm, and record Node/libuv/npm/tar versions with `node scripts/release-toolchain.mjs`. Consumer runtime qualification may still execute the MCP server with Node 22 while invoking the external release tools separately with Node 24.20.0.
+
+CI retains all nine runtime jobs (Node 22/24/26 on Linux, macOS and Windows). The complete release suite runs separately on all three operating systems with Node 24.20.0. macOS has three predefined full passes; any failed pass fails the job. These are fixed qualification passes, with no failure retries, skipped cases or increased archive limits. Supply-chain and npm/MCP publication workflows use the same exact release Node version.
+
+Pull requests also run dependency review and reject newly introduced high or
+critical vulnerabilities. CodeQL analyzes JavaScript/TypeScript on pushes,
+pull requests and a weekly schedule. The supply-chain job uploads its validated
+CycloneDX 1.5 production SBOM as a 14-day CI artifact only after its complete
+package identity set matches `npm ls --omit=dev --all`; the SBOM is not added
+to npm packages or publication artifacts. The SBOM gate compares identities
+rather than CycloneDX edge layout because npm may hoist or deduplicate paths;
+the separate release-graph gate validates the installed production graph
+against the authoritative lockfile.
+
+## Manual prerequisites
+
+Complete these outside the repository before dispatching npm or MCP publication:
+
+- Confirm control of the intended npm package name and maintainer access to the
+  npm account or organization.
+- Enforce npm two-factor authentication and use a dedicated maintainer account
+  with least privilege.
+- For a package that already exists, configure npm Trusted Publishing for
+  `alebgl77/ftp-deploy-mcp` and workflow filename `release.yml`. No named GitHub
+  environment is configured by these workflows.
+- For the **first** publication, npm requires the package to exist before a
+  trust relationship can be configured. A maintainer must create a short-lived
+  granular token with the minimum available publish scope and the required
+  non-interactive/2FA permission, and store it only as `NPM_TOKEN` in GitHub
+  Actions secrets. After the first successful publish, configure Trusted
+  Publishing, remove that secret, and revoke the token immediately. Never
+  commit, paste into an issue/chat, or print the token. Do not create a
+  persistent token as a workaround. See [npm trust prerequisites](https://docs.npmjs.com/cli/v11/commands/npm-trust/)
+  and [npm trusted publishing](https://docs.npmjs.com/trusted-publishers/).
+- Confirm that the release workflow requests npm provenance and has only the
+  permissions it needs. Repository automation cannot create npm ownership or
+  approve a new package name.
+- Establish the publisher identity and namespace required by the official MCP
+  registry, and confirm access to its current publishing tool. A prepared
+  manifest or third-party index listing is not a registry publication.
+- Confirm that GitHub environments, required reviewers, branch protection, and
+  release permissions are in place.
+
+Record who completed each manual prerequisite and when. Do not start npm or MCP
+publication while any ownership or credential step is unresolved. These registry
+prerequisites do not establish whether a GitHub source release is ready.
+
+## Version and changelog gate
+
+For the v0.3.1 GitHub release:
+
+1. Set `version` in [package.json](../package.json), the root and root-package
+   metadata of `package-lock.json`, and `server.json` to `0.3.1`. The source lockfile
+   is the sole authoritative lockfile; do not keep a parallel `npm-shrinkwrap.json`.
+2. Set the MCP server's reported version to the same value. Search the source
+   and generated metadata for stale release strings; expected historical
+   references in the changelog are exempt.
+3. Use the paired heading `## [0.3.1] - 2026-10-17` in
+   [CHANGELOG.md](../CHANGELOG.md) and [CHANGELOG.fr.md](../CHANGELOG.fr.md).
+   Confirm the effective release date is a valid calendar date, update it only
+   if the actual release day changes, and preserve the complete 0.3.0 history.
+4. Confirm every user-visible minor-release change is documented in both
+   [README.md](../README.md) and [README.fr.md](../README.fr.md).
+5. Verify the release includes atomic replacement for newly written sensitive
+   configuration and tests its failure path. This is a release gate, not a
+   documentation-only claim.
+6. Confirm `node src/index.js --version`, package metadata, source lockfile and tag
+   agree. Verify npm and Official MCP Registry versions separately only after
+   their respective publications.
+
+Use a dedicated release commit. Never move or reuse the published v0.2.0 tag.
+
+## Review the source and installed dependency graphs
+
+The sole source authority is `package-lock.json`, with six exact direct pins and
+112 non-root records: 110 production and two development. Source/Docker/user
+installs use `npm ci --omit=dev --ignore-scripts`; contributors use
+`npm ci --ignore-scripts`. No shrinkwrap is retained. npm 12 no longer reads or
+writes shrinkwrap files, including in dependencies; see the
+[official npm lockfile documentation](https://docs.npmjs.com/cli/v12/configuring-npm/package-lock-json/).
+
+For an approved dependency update, change only the intended exact versions and
+regenerate the source lock with scripts disabled. Record Node/npm versions and
+review every graph change, registry URL, integrity value and optional/platform
+constraint. Keep the original reviewed source inventory as the authority when
+checking installations; never update it from the installed graph.
+
+The built-in-only graph verifier reads actual package manifests and installed
+lock records, including the hidden lock when present. It resolves transitive
+dependencies and peers from their real locations, including hoisted and nested
+packages. It rejects version/resolution/integrity drift, undeclared extras,
+missing required packages and changed dependency declarations. Declared optional
+omissions and source-proven development packages are reported separately; a
+present optional dependency with changed bytes or metadata is not an omission.
+No dependency code is imported by this verifier.
+
+## Qualify the source installation archive
+
+There are two fixed distributions. `ftp-deploy-mcp-0.3.1-source.tar.gz` contains
+90 regular files under `package/`, including the source lock. It is an
+installation archive, not the complete repository: tests, maintainer scripts and
+the HTML guide remain in the repository. GitHub's automatic source ZIP/tar
+contains the complete repository. The separate npm archive
+`ftp-deploy-mcp-0.3.1.tgz` contains 89 files and no lockfile.
+
+Capture all 90 reviewed source files before installation, tests or packing.
+Keep the portable inventory outside the checkout and retain its original SHA256
+independently of any generated proof. A source-only snapshot qualifies a pre-tag
+candidate; publication requires the actual clean tracked tag/event checkout.
+For a pre-tag candidate, run from the intended checkout (Bash):
+
+```bash
+source_root="$(pwd -P)"
+release_tmp="$(mktemp -d)"
+inventory="$release_tmp/source-inventory.json"
+node scripts/release-artifact.mjs snapshot "$inventory" --source-root "$source_root" --source-only
+```
+
+Record the original snapshot output in `inventory_sha256` before continuing.
+Never replace it with a value reread from a rewritten proof.
+
+```bash
+npm ci --ignore-scripts
+npm test
+npm run test:release
+node scripts/release-gate.mjs --source-only --runtime
+node scripts/release-artifact.mjs build-source "$release_tmp/source-pack.json" --source-root "$source_root" --inventory "$inventory" --inventory-sha256 "$inventory_sha256" --source-only
+node scripts/release-artifact.mjs preflight "$release_tmp/source-pack.json" --source-root "$source_root" --inventory "$inventory" --inventory-sha256 "$inventory_sha256" --distribution source
+```
+
+The builder writes only captured bytes into a private staging directory and uses
+real tar with bounded stdout. It validates every byte before exclusive archive
+and metadata writes. Retain the preflight's original canonical `tarball` path
+and SHA512 `integrity` outputs in those variables, then install in a fresh folder:
+
+```bash
+mkdir "$release_tmp/consumer"
+tar --ignore-zeros -xzf "$tarball" -C "$release_tmp/consumer"
+(cd "$release_tmp/consumer/package" && npm ci --omit=dev --ignore-scripts)
+node scripts/release-graph.mjs --source-root "$source_root" --inventory "$inventory" --inventory-sha256 "$inventory_sha256" --product-root "$release_tmp/consumer/package" --install-root "$release_tmp/consumer/package" --output "$release_tmp/source-graph.json" --source-only
+npm audit --prefix "$release_tmp/consumer/package" --omit=dev --audit-level=moderate
+node scripts/release-artifact.mjs check "$release_tmp/source-pack.json.verified.json" --source-root "$source_root" --inventory "$inventory" --inventory-sha256 "$inventory_sha256" --expected-integrity "$integrity" --expected-tarball "$tarball" --distribution source --source-only
+```
+
+Run the independent consumer runtime/transport cases, audits and production SBOM
+checks against this extracted installation before approving it. The installed
+product needs no `.git`; its Git provenance comes from the external checkout and
+original inventory. Never install the source tar.gz as an npm package. Users
+extract `package/`, run `npm ci --omit=dev --ignore-scripts` there, then run
+`node src/index.js setup` explicitly. Contributor commands run from the full
+repository, not from this installation archive.
+
+The proof binds an explicit `source` or `npm` distribution, exact filename,
+`package/` prefix, scope, commit, inventory SHA256, original integrity and
+canonical artifact path. The controller supplies the expected distribution;
+`inspect`/`check` default to npm and refuse a source proof. Changing a proof or
+renaming an archive cannot change its distribution.
+
+## Keep npm qualification separate
+
+npm remains unqualified: a real npm 10.9.8 consumer changed ten production
+dependencies. Its failed candidate and reports are retained, never promoted to
+source-release evidence or attached as a qualified asset. A future matching npm
+graph would establish only the tested environment/date, not reproducibility of
+future npm installs. To inspect a separate npm candidate with the original
+90-file source inventory:
+
+```bash
+npm pack --ignore-scripts --json --pack-destination "$release_tmp" > "$release_tmp/npm-pack.json"
+node scripts/release-artifact.mjs preflight "$release_tmp/npm-pack.json" --source-root "$source_root" --inventory "$inventory" --inventory-sha256 "$inventory_sha256" --distribution npm
+```
+
+Inspection checks all 89 npm files against the source; the source lock remains
+external authority. Install this exact npm candidate in an isolated prefix with
+scripts disabled, then invoke `release-graph.mjs` with `--product-root` pointing
+to `<prefix>/node_modules/ftp-deploy-mcp` and `--install-root` to the prefix.
+Any graph difference must fail before smoke tests, artifact transfer or npm/MCP
+publication. A source-only pass never authorizes a registry publication.
+
+## Artifact validation and provenance limits
+
+The fixed allowlists exclude local configuration, credentials, tests, temporary
+files and maintainer state. Complete package metadata and the source lock are
+structurally validated; each shipped byte must match the original inventory.
+Publication commands receive real `GITHUB_REF` and `GITHUB_SHA` from GitHub;
+HEAD and the exact tag target must match that event. Never invent this context.
+Use `snapshot` without `--source-only`, `inspect` instead of `preflight`, and
+`check` without `--source-only` only in that real publication context.
+
+Compressed bytes are read once with an 8 MiB cap and provide the original SHA512.
+Strict built-in gzip decoding has a 32 MiB total output cap, including TAR headers
+and padding. `engine.bytesWritten` must be an integer within the input length;
+any unconsumed byte must be NUL. Terminal NUL padding is allowed, nonzero hidden
+tails are rejected. Every inspection tar call receives the same decoded raw TAR,
+without `-z`, and uses `--ignore-zeros`. Untrusted archive paths are never
+extracted to disk during inspection.
+
+| Inspection limit | Maximum |
+|---|---|
+| Compressed archive | 8 MiB |
+| Complete decoded TAR, headers and padding included | 32 MiB |
+| Each expected or extracted file | 1 MiB |
+| Complete inspection | 90 seconds |
+| Each tar invocation | 15 seconds, or the shorter remaining budget |
+
+These are input/output/time limits, not an exact memory bound. The deadline is
+checked before and after synchronous gzip decoding and cannot preempt it. Failed
+validation emits no new proof or publication outputs. Recheck original inventory,
+source bytes, integrity and path immediately before publication. The controls
+assume trusted workflow code and runner, not a fully compromised runner.
+
+Git commit identity, checkout byte inventory and archive digest are distinct.
+CRLF/LF checkout conversion can produce different valid inventories on different
+systems. Qualification binds the exact Windows-built asset to its recorded
+checkout bytes; the nine OS/Node CI jobs qualify their own checkouts, not that
+Windows archive on every OS. After the final commit, establish an inventory for
+that commit and reinspect the same frozen bytes before release. Retain the
+pre-commit evidence as historical evidence, not as the final commit binding.
+On Windows, use native PowerShell paths, environment assignments and output
+handling instead of the Bash syntax above.
+
+## Separate qualification from publication
+
+The npm qualification job has `contents: read`, no OIDC permission and no
+secrets. It captures the source inventory before installation/tests/packing,
+then installs, tests, audits and qualifies the exact archive and consumer.
+The publication job starts on a fresh runner after qualification succeeds.
+Both checkouts are pinned to the event's `github.sha`; HEAD and the actual tag
+target must match that commit. Build outputs cannot select the privileged code.
+
+Only the `.tgz`, pack JSON and source inventory cross the job boundary through
+the exact upload artifact ID, downloaded outside the fresh checkout. No scripts,
+`node_modules`, caches, environment files or first-runner proof are transferred.
+The inventory is portable: commit, release identity, relative paths, sizes and
+byte hashes. Each command validates its own explicit canonical source root;
+moving roots never rewrites the original inventory bytes or SHA256.
+
+Qualification job outputs retain the original inventory SHA256 and archive
+SHA512. Fresh privileged `inspect` must enforce that original expected integrity
+against both pack JSON and compressed bytes before creating a local proof or
+outputs. It binds the portable inventory to the fresh source and newly downloaded
+canonical archive path. The final `check` uses the original inventory digest and
+the privileged inspection's integrity/path outputs; npm publishes only that
+checked path with `--provenance` and lifecycle scripts disabled. Registry
+verification retains those same original bindings.
+
+The privileged inspection receives `SOURCE_INVENTORY_SHA256` and
+`BUILD_INTEGRITY` from the original qualification job outputs:
+
+```bash
+node scripts/release-artifact.mjs inspect "$RUNNER_TEMP/release-input/release-pack.json" --source-root "$GITHUB_WORKSPACE" --inventory "$RUNNER_TEMP/release-input/source-inventory.json" --inventory-sha256 "$SOURCE_INVENTORY_SHA256" --expected-integrity "$BUILD_INTEGRITY"
+```
+
+The first qualification inspection emits the original archive digest; this
+fresh privileged inspection must require it, not choose a new expected value.
+
+Privileged jobs run only approved validators using Node built-ins, the npm CLI
+or the pinned MCP publisher. They run no `npm ci`/`npm install`, project tests,
+consumer smoke checks or `--runtime`. `NPM_TOKEN`, when needed for bootstrap,
+exists only in the final npm publish step. The MCP workflow uses the same job
+separation. Its nonprivileged job first captures the inventory, then `fetch-npm`
+verifies registry identity and SHA512, requires the fixed official HTTPS URL,
+downloads within the 8 MiB/time bounds and inspects all 89 files. It installs that
+actual download without scripts, checks the graph and runs consumer checks. The
+job output retains this qualified archive's original integrity. The privileged
+job receives it and requires it from the registry again before authentication:
+
+```bash
+node scripts/release-artifact.mjs verify-npm --source-root "$GITHUB_WORKSPACE" --expected-integrity "$QUALIFIED_INTEGRITY" --distribution npm
+```
+
+The standalone `verify-npm` form therefore enforces expected integrity too.
+No dependency files or code from the first runner are transferred; only the fresh
+event-pinned checkout supplies the published `server.json`.
+
+## GitHub release and assets
+
+After independent qualification and review, use the final verified commit,
+require its complete public CI, then create v0.3.1. Retain the exact validated
+`ftp-deploy-mcp-0.3.1-source.tar.gz` bytes. Prepare `SHA256SUMS` for this archive,
+the standalone bilingual HTML guide and final evidence/SBOM; upload only these
+verified files. Publish EN/FR notes that accurately describe the source scope,
+then download again and verify hashes. Record commit, tag, actual time, names
+and digests.
+
+Attach no drifting npm `.tgz`. GitHub's automatic ZIP/tar remains the separate
+complete repository. Asset uploads remain pending until verified; npm and MCP
+remain unqualified/pending. A source release does not make npm, `npx` or the
+Official MCP Registry available.
+
+## Publish npm
+
+1. Review the prepared release workflow and confirm its trigger matches the
+   intended tag policy.
+2. Create an annotated tag whose name exactly matches the version:
+   `git tag -a v0.3.1 -m "v0.3.1"`. If the GitHub source release already created
+   this tag, verify and reuse its unchanged target; do not recreate it.
+3. After maintainer approval and credential readiness, push the release commit
+   and tag. Ensure the workflow is present on the default branch, then dispatch
+   it explicitly on the tag:
+
+   ```bash
+   gh workflow run release.yml --ref v0.3.1
+   ```
+4. Require tests, version-consistency checks, installed graph equality, tarball inspection, and provenance
+   generation to pass before the publish step.
+5. Wait for that workflow run to finish successfully. Its last step compares
+   the public npm name, exact version, `mcpName`, and SHA512 integrity to the
+   validated archive. Only 404 propagation responses are retried (six attempts,
+   five-second delay, 15-second request timeout); authentication, HTTP errors,
+   invalid metadata, and mismatched integrity fail closed. A failed check after
+   publish does **not** prove npm publication failed: inspect the exact version
+   before doing anything else, and do not rerun npm publication blindly.
+6. For the first-publish bootstrap, configure Trusted Publishing and revoke and
+   remove the token immediately after success. For later releases, leave
+   `NPM_TOKEN` absent so npm authenticates with GitHub OIDC. Verify the trust
+   configuration before the next release; do not republish the same version to
+   test it.
+7. Verify the public artifact independently:
+
+```bash
+npm view ftp-deploy-mcp@0.3.1 name version mcpName dist.integrity
+npm view ftp-deploy-mcp@0.3.1 dist.tarball
+npx -y ftp-deploy-mcp@0.3.1 --version
+```
+
+Compare the registry integrity/version with the validated tarball and tag.
+Only after these checks pass should the README call `npx` a currently available
+installation method.
+
+Create the GitHub release from the same immutable tag and copy the relevant
+changelog entry. Do not move or reuse a published tag.
+
+## Publish to the MCP registry
+
+This step remains pending. Publish only after separate npm qualification, including the installed graph. The MCP workflow downloads and qualifies the actual published npm archive again; identity alone is insufficient:
+
+1. Review `server.json` against schema `2025-12-11`; it must agree with the tag,
+   source lockfile root/root-package versions, runtime version, npm identifier,
+   and `mcpName`.
+2. Dispatch the separate workflow on exactly the same tag:
+
+   ```bash
+   gh workflow run publish-mcp.yml --ref v0.3.1
+   ```
+
+3. The nonprivileged job also qualifies the actual npm download and installed graph. Its
+   fresh privileged successor verifies structural metadata, the exact npm
+   version, `mcpName` and the qualified integrity **before** MCP authentication, without dependency
+   installation, tests or `--runtime`.
+4. It verifies the pinned official publisher archive, then runs
+   `mcp-publisher login github-oidc` and `mcp-publisher publish`. GitHub OIDC
+   proves the `io.github.alebgl77/` namespace; no dedicated MCP secret is used.
+   The publisher validates the manifest during publication. The workflow logs
+   out afterwards. See the [official GitHub Actions guide](https://modelcontextprotocol.io/registry/github-actions)
+   and [registry quickstart](https://modelcontextprotocol.io/registry/quickstart).
+5. From a clean environment, find the official registry entry, install it by
+   its documented route, start the server, and confirm `--version` plus an MCP
+   `ftp_list_servers` call.
+6. Check that Glama and MCP Index discovery listings point to the canonical
+   repository and released version, but do not treat those third-party pages as
+   registry verification.
+
+The workflow pins `mcp-publisher` **v1.8.1**, Linux amd64, SHA256:
+
+```text
+a06c9096dcb9727c13555b6be26c7effa707b01f06a4c561ba7a3635443cf2cc
+```
+
+On 2026-09-03, the downloaded archive matched the digest returned by the
+[official GitHub release API](https://api.github.com/repos/modelcontextprotocol/registry/releases/tags/v1.8.1)
+for the [v1.8.1 release](https://github.com/modelcontextprotocol/registry/releases/tag/v1.8.1).
+The workflow verifies this SHA256 before extracting or executing the binary;
+it never resolves a mutable `latest` URL. This is a pinned digest verification,
+not a claim that a Sigstore signature was independently verified. Updating the
+tool requires reviewing and re-verifying both the version and digest.
+
+If npm succeeded but MCP publication failed, correct the MCP-specific issue
+and rerun only `publish-mcp.yml` on the unchanged tag. Do not attempt to recreate
+an existing npm version. The MCP Registry is a preview service; check its live
+entry after publishing before making availability claims.
+
+## Rollback and incident response
+
+Before publication, stop the workflow and fix the release commit. If an
+unpublished tag was pushed, remove it only after confirming no artifact was
+created, then create a corrected tag.
+
+After npm publication, assume the version is immutable:
+
+- stop MCP registry publication if it has not happened;
+- deprecate the broken npm version with a precise warning;
+- fix forward with a new patch version and a new tag;
+- use npm unpublish only for a qualifying emergency and within npm policy, not
+  as a normal rollback;
+- never overwrite, move, or reuse the published tag/version;
+- withdraw or deprecate the MCP registry version if the registry supports it,
+  then publish the fixed patch version;
+- revoke any bootstrap token, rotate exposed credentials, and preserve logs and
+  integrity values for incident review;
+- revert README availability claims if users can no longer install a safe
+  version.
+
+For a suspected security issue, pause the release and follow
+[SECURITY.md](../SECURITY.md).
+
+## Post-release checks
+
+For the source release, verify its archive, checksum, source graph, runtime and
+external commit inventory. Perform the following registry checks only after
+separate npm/MCP publication has actually succeeded.
+
+- Confirm npm provenance is visible and refers to the expected repository,
+  workflow, commit, and tag.
+- Confirm source, tarball, GitHub release, npm, server `--version`, and MCP
+  registry all report the same version.
+- Test source install, exact-version `npx`, and registry installation from
+  clean environments.
+- Update both README availability notices and add the verified `npx` path.
+- Announce only installation paths that were actually tested.
+- Monitor private security reports and release failures, and prepare a patch
+  rather than altering the published artifact.

package/docs/RESOURCE-BOUNDS.fr.md

@@ -0,0 +1,144 @@
+# Limites du parcours local et de l’admission des appels
+
+[English](./RESOURCE-BOUNDS.md)
+
+## Sélection d’un déploiement
+
+Chaque serveur configuré possède deux politiques facultatives, qui doivent être
+des entiers positifs représentables sans perte. Les arguments des outils ne
+peuvent modifier aucune de ces politiques.
+
+| Champ | Défaut | Maximum |
+| --- | ---: | ---: |
+| `maxScanEntries` | 100000 entrées visitées | 1000000 |
+| `maxScanDepth` | 64 niveaux de dossiers sous la racine | 256 |
+
+La racine compte pour une entrée visitée, à la profondeur zéro. Chaque entrée
+découverte compte une fois : dossiers, fichiers exclus et liens symboliques
+compris. La descente ne compte pas le dossier une seconde fois. Atteindre
+exactement une limite est accepté ; l’entrée suivante refuse toute la sélection
+avec `SCAN_LIMIT`. La profondeur est inclusive : les fichiers d’un dossier au
+niveau configuré restent éligibles, mais un sous-dossier non élagué est refusé
+avant son ouverture. Un sous-arbre élagué ne nécessite aucune descente et ses
+descendants non découverts ne sont pas comptés.
+
+`maxDeployFiles` borne séparément les fichiers sélectionnés dès leur accumulation.
+Les contrôles existants d’octets par fichier et par déploiement restent actifs.
+Un échec de sélection précède toute connexion ou mutation distante, en simulation
+comme en déploiement réel. `SCAN_LIMIT` renvoie `effects:none`, `retryable:false`
+et `next_action:fix_input`.
+
+Le parcours lit les dossiers séquentiellement avec `opendir` asynchrone, un tampon
+de 32 entrées par handle et au plus `maxScanDepth + 1` handles ouverts. Il vérifie
+l’annulation et le délai autour des lectures, puis rend la main à la boucle
+événementielle toutes les 256 entrées découvertes. Toutes les fermetures sont
+attendues, même après échec ou annulation. Un appel au système de fichiers ou une
+fermeture lente peut encore dépasser le délai réel ; une réponse anticipée de
+dépassement de délai ne signifie pas que le nettoyage est terminé.
+
+Seules les exclusions intégrées prouvées des sous-arbres `node_modules`, `.git`
+et `.ftp-mcp` permettent l’élagage. Les exclusions personnalisées et les motifs
+d’inclusion ne l’autorisent jamais ; leurs règles existantes restent appliquées
+à chaque fichier. Cela corrige un ancien test par sentinelle qui produisait des
+faux positifs : `exclude:["**/__ftp_deploy_probe__"]` ne masque plus
+`docs/wanted.txt`. Certains fichiers omis à tort peuvent désormais apparaître
+dans la sélection. Examinez une simulation après avoir changé les exclusions.
+
+Les liens symboliques rencontrés sont ignorés. Les contrôles lexicaux et
+canoniques de `localRoot` et la nouvelle validation des sources à l’envoi restent
+actifs. Ils ne suppriment pas les courses malveillantes sur les chemins causées
+par un autre programme exécuté sous le même compte système.
+
+## Admission des appels d’outil
+
+Un isolate Node admet au plus 64 appels d’outil pour tous les registres partageant
+le module d’admission. Il n’existe ni file d’admission supplémentaire ni reprise
+automatique. Un outil inconnu conserve l’erreur de protocole `-32602` ; des
+arguments invalides conservent `INVALID_ARGUMENT`. Une requête déjà annulée ne
+lance aucune préparation ni aucun handler. L’admission suit la validation du
+schéma et précède la préparation.
+
+Le 65e appel renvoie `CAPACITY_LIMIT`, `effects:none`, `retryable:false` et
+`next_action:retry`. Réessayez explicitement après la fin effective d’un appel
+actif. Chaque appel conserve sa place pendant la préparation, l’exécution et le
+nettoyage, y compris lorsqu’une entrée-sortie non coopérative se termine après
+une annulation ou un dépassement de délai. Les verrous FIFO existants par cible
+sont inchangés ; leurs appels en attente occupent aussi une place d’admission.
+Les identifiants de corrélation, dont `0` numérique, `""`, `1` numérique et `"0"`
+texte, restent distincts dans la garde du canal possédée par le point d’entrée.
+Cette garde réserve chaque identifiant de requête entrant, toutes méthodes
+confondues, avant sa remise au SDK et ferme la connexion sur tout doublon actif.
+
+Ces limites ne coordonnent pas les processus, isolates ou hôtes distincts. Elles
+ne bornent ni les tampons d’entrée du transport ni l’analyse des requêtes refusées.
+Les limites du parcours local ne bornent pas le tampon distant sous-jacent de
+`list()` ; la sortie MCP paginée conserve l’implémentation de liste existante.
+
+## Bornes de l'état durable et du statut
+
+`stateLimits` borne strictement les octets d'état, octets/fichiers de sauvegarde,
+plans, opérations, fichiers/octets de plan et octets/événements de journal. La
+publication d'un plan prouve toute sa réservation avant écriture. Apply et
+rollback consultent le budget avant chaque intention durable et événement
+terminal ; les flux s'exécutent hors du court verrou d'admission mais sous le
+verrou persistant de l'alias exact.
+
+`ftp_deploy_status` est sans écriture ni verrou : il rejoue un préfixe de journal
+dont l'intégrité est vérifiée, puis confirme que plan, association, journal et
+tête n'ont pas changé. Une concurrence renvoie `STATUS_CHANGED` ou
+`DURABLE_STATE_BUSY`, jamais une page mélangée. Une page accepte au plus 100
+lignes et s'arrête avant que le résultat structuré complet dépasse 18 Kio ;
+`next_offset` vaut toujours `offset + count` lorsqu'une ligne reste.
+
+Sauvegardes et journaux sont sensibles. Gardez `stateDir` privé et hors de toute
+arborescence `localRoot`. Ne copiez pas un état v1 : il est refusé avant décodage
+des plans et exige une réinitialisation hors ligne.
+
+## Cycle de vie interne des outils préparés
+
+Le registre expose une interface d’intégration interne ; les outils qui ne
+l’activent pas utilisent toujours leur résolveur `timeoutFor` ordinaire.
+L’interface elle-même n’active aucune reprise ni identifiant de requête
+persistant et ne modifie ni les descripteurs ni les résultats des outils qui ne
+l’utilisent pas.
+
+Une inscription peut fournir les callbacks privés appariés `prepare(args,
+operation)` et `disposePrepared(prepared, operation)`, tous deux obligatoirement
+des fonctions. Le handler reçoit la valeur préparée en troisième argument. Une
+préparation réussie transfère la propriété de sa ressource même si elle renvoie
+`undefined` ; le registre attend exactement une libération après le handler ou
+tout échec ultérieur. Une préparation qui rejette doit fermer chaque ressource
+acquise avant son rejet : le registre ne peut pas libérer un contexte jamais
+renvoyé. Le premier échec est conservé si la libération échoue aussi ; un échec
+de libération après un handler réussi devient une erreur d’outil bornée ordinaire.
+
+Préparation, traitement et libération s’exécutent dans le worker admis observé
+par le transport. Une annulation ou un dépassement de délai peut produire une
+réponse anticipée, mais le slot d’admission reste occupé jusqu’à la terminaison
+réelle, préparation tardive et libération comprises. L’identifiant de requête du
+canal reste réservé jusqu’au règlement ou à l’échec de l’envoi de la réponse
+terminale et jusqu’à la terminaison réelle de tous les tours de handler enregistrés,
+y compris tous les tours legacy d’entrée requise. Si l’annulation du client
+supprime la réponse, l’identifiant reste réservé jusqu’à la fermeture de la
+connexion. La libération s’exécute même après l’annulation et ne doit pas passer
+par `operation.step`, dont le contrôle d’annulation empêcherait le nettoyage. Un
+travail non coopératif peut donc retenir la capacité indéfiniment ; le délai
+n’interrompt pas du JavaScript ou des entrées-sorties arbitraires.
+
+L’option privée `preparedTimeoutMs` du registre vaut 120000 par défaut et accepte
+un entier sûr positif jusqu’à 3600000. Les outils préparés ne consultent jamais
+`timeoutFor`. Le futur assemblage fournit le plus grand délai serveur validé.
+Après sélection du serveur, la préparation appelle
+`operation.shortenTimeout(server.operationTimeoutMs)`, puis `operation.check()`
+avant tout effet. Le raccourcissement part du début initial de l’opération, ne
+prolonge jamais l’échéance courante et annule immédiatement une échéance déjà
+dépassée. Une opération terminée ne peut pas créer un autre timer.
+
+`operation.runPreparation(run)` est à usage unique, sans imbrication. Son plafond
+fixe de 10000 ms commence avant l’appel du callback et reste borné par l’échéance
+principale. Les contrôles avant et après le callback imposent aussi ce plafond
+si la boucle événementielle n’a pas exécuté le timer. Son expiration annule
+irréversiblement toute l’opération avec `TIMEOUT`. Une préparation réussie retire
+seulement le plafond de l’étape et conserve l’échéance principale. Le callback
+réel reste attendu après une réponse anticipée ; les timers sont supprimés à
+l’annulation et à la terminaison réelle.