{"id":20269963,"url":"https://github.com/xcraft-inc/xcraft-core-subst","last_synced_at":"2026-03-10T13:06:00.226Z","repository":{"id":57401126,"uuid":"64939864","full_name":"Xcraft-Inc/xcraft-core-subst","owner":"Xcraft-Inc","description":"Windows subst helpers","archived":false,"fork":false,"pushed_at":"2024-09-02T14:23:57.000Z","size":44,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-04-08T22:05:13.073Z","etag":null,"topics":["drive","subst","xcraft"],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Xcraft-Inc.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-08-04T14:07:29.000Z","updated_at":"2024-09-02T14:23:59.000Z","dependencies_parsed_at":"2024-11-14T12:41:04.726Z","dependency_job_id":null,"html_url":"https://github.com/Xcraft-Inc/xcraft-core-subst","commit_stats":{"total_commits":53,"total_committers":3,"mean_commits":"17.666666666666668","dds":0.2264150943396226,"last_synced_commit":"b68fdb26b70f2ebb0864fc574418443354ed9a3a"},"previous_names":[],"tags_count":11,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Xcraft-Inc%2Fxcraft-core-subst","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Xcraft-Inc%2Fxcraft-core-subst/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Xcraft-Inc%2Fxcraft-core-subst/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Xcraft-Inc%2Fxcraft-core-subst/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Xcraft-Inc","download_url":"https://codeload.github.com/Xcraft-Inc/xcraft-core-subst/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252905816,"owners_count":21822868,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["drive","subst","xcraft"],"created_at":"2024-11-14T12:28:13.479Z","updated_at":"2026-03-10T13:06:00.221Z","avatar_url":"https://github.com/Xcraft-Inc.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 📘 xcraft-core-subst\n\n## Aperçu\n\nLe module `xcraft-core-subst` est une bibliothèque utilitaire du framework Xcraft qui permet de gérer les substitutions de lecteurs sous Windows. Il offre une solution élégante pour contourner les limitations de longueur de chemin sous Windows (260 caractères) en montant temporairement des chemins longs sur des lettres de lecteur disponibles.\n\n## Sommaire\n\n- [Structure du module](#structure-du-module)\n- [Fonctionnement global](#fonctionnement-global)\n- [Exemples d'utilisation](#exemples-dutilisation)\n- [Interactions avec d'autres modules](#interactions-avec-dautres-modules)\n- [Détails des sources](#détails-des-sources)\n- [Licence](#licence)\n\n## Structure du module\n\nLe module expose trois composants principaux :\n\n- **Subst** : Classe principale pour gérer les substitutions de lecteurs Windows\n- **wrap** : Fonction utilitaire pour exécuter du code avec un chemin substitué temporairement\n- **wrapTmp** : Fonction utilitaire pour créer des copies temporaires dans un répertoire avec chemin court\n\n## Fonctionnement global\n\nLe module résout spécifiquement le problème des chemins trop longs sous Windows (\u003e 260 caractères ou \u003c 32 caractères pour déclencher la substitution). Il utilise la commande système `subst` de Windows pour associer un chemin long à une lettre de lecteur, permettant ainsi d'accéder aux fichiers via un chemin plus court.\n\n**Algorithme de sélection de lecteur :**\n\n1. Commence par la lettre 'z' et descend dans l'alphabet\n2. Vérifie la disponibilité avec `net use` (code de retour 2 = disponible)\n3. Effectue la substitution avec `subst` (code de retour 0 = succès)\n4. Si aucune lettre n'est disponible jusqu'à 'a', lève une exception\n\n**Comportement multi-plateforme :**\n\n- **Windows** : Substitution active pour les chemins ≥ 32 caractères\n- **Autres OS** : Mode passthrough, retourne les chemins d'origine sans modification\n\n## Exemples d'utilisation\n\n### Utilisation directe de la classe Subst\n\n```javascript\nconst {Subst} = require('xcraft-core-subst');\n\n// Avec générateurs (style Xcraft)\nfunction* processLongPath(resp) {\n  const subst = new Subst('/chemin/tres/long/vers/un/dossier', resp);\n  const drive = yield subst.mount();\n\n  try {\n    // Utiliser le lecteur monté (ex: 'z:')\n    resp.log.info(`Chemin substitué : ${drive}`);\n    // Traitement des fichiers...\n  } finally {\n    yield subst.umount();\n  }\n}\n```\n\n### Utilisation avec la fonction wrap\n\n```javascript\nconst {wrap} = require('xcraft-core-subst');\n\n// Traitement automatique avec gestion du cycle de vie\nfunction* processFile(resp) {\n  const result = yield wrap(\n    '/chemin/tres/long/vers/un/fichier.txt',\n    resp,\n    function* (err, shortPath, next) {\n      if (err) throw err;\n\n      // shortPath est maintenant 'z:/fichier.txt'\n      return yield processFileWithShortPath(shortPath, next);\n    }\n  );\n\n  return result;\n}\n```\n\n### Utilisation avec wrapTmp pour copies temporaires\n\n```javascript\nconst {wrapTmp} = require('xcraft-core-subst');\n\nfunction processWithTempCopy(resp) {\n  const {dest, unwrap} = wrapTmp(\n    '/chemin/source/tres/long',\n    'temp-processing',\n    resp,\n    true // overwrite si existe\n  );\n\n  try {\n    // Traiter les fichiers dans dest\n    console.log(`Fichiers temporaires dans : ${dest}`);\n    // ...\n  } finally {\n    unwrap(() =\u003e {\n      console.log('Nettoyage des fichiers temporaires terminé');\n    });\n  }\n}\n```\n\n## Interactions avec d'autres modules\n\n- **[xcraft-core-platform]** : Détection du système d'exploitation pour activer/désactiver la substitution\n- **[xcraft-core-process]** : Exécution des commandes système `net use` et `subst`\n- **[xcraft-core-etc]** : Chargement de la configuration Xcraft pour les répertoires temporaires\n- **gigawatts** : Gestion des générateurs et fonctions asynchrones\n- **fs-extra** : Opérations sur le système de fichiers (copie, suppression)\n\n## Détails des sources\n\n### `index.js`\n\nFichier principal contenant la classe `Subst` qui orchestre la substitution de lecteurs Windows.\n\n#### Classe Subst\n\nLa classe gère le cycle de vie complet d'une substitution de lecteur :\n\n**Propriétés :**\n\n- `drive` : Lettre de lecteur courante (commence à 'z')\n- `location` : Chemin à substituer\n- `skipped` : Booléen indiquant si la substitution est ignorée\n- `_resp` : Objet de réponse Xcraft pour les logs\n\n#### Méthodes publiques\n\n- **`mount()`** — Monte le chemin sur une lettre de lecteur disponible. Retourne la lettre de lecteur (ex: 'z:') ou le chemin original si la substitution est ignorée.\n\n- **`umount()`** — Démonte la lettre de lecteur précédemment montée. Nettoie proprement la substitution.\n\n#### Méthodes privées\n\n- **`_getDrive()`** — Retourne la lettre de lecteur actuelle formatée avec ':'\n- **`_getOptions(opts)`** — Prépare les options pour les commandes système, évalue les fonctions\n- **`_exec(cmd, opts, testCode, next)`** — Exécute une commande système et gère la logique de retry avec changement de lecteur\n- **`_netUse(next)`** — Vérifie la disponibilité d'une lettre de lecteur (code retour 2 = libre)\n- **`_subst(next)`** — Effectue la substitution effective (code retour 0 = succès)\n- **`_desubst(next)`** — Supprime la substitution avec l'option `/D`\n\n### `lib/wrap.js`\n\nFonction utilitaire qui encapsule l'utilisation de `Subst` pour un usage temporaire :\n\n1. **Préparation** : Assure l'existence du répertoire parent\n2. **Montage** : Monte le répertoire sur une lettre de lecteur\n3. **Exécution** : Appelle la fonction utilisateur avec le chemin court\n4. **Nettoyage** : Démonte automatiquement le lecteur (bloc `finally`)\n\nLa fonction utilise `watt` pour gérer les générateurs et garantit le démontage même en cas d'exception.\n\n### `lib/wrap-tmp.js`\n\nFonction de gestion des copies temporaires basée sur la configuration Xcraft :\n\n**Logique de fonctionnement :**\n\n1. Vérifie si `tempRoot` ≠ `tempDriveRoot` dans la configuration\n2. Si différents, copie les fichiers vers `tempDriveRoot/tmpDir`\n3. Préserve les timestamps lors de la copie\n4. Retourne un objet avec le chemin de destination et une fonction de nettoyage\n\n**Paramètres :**\n\n- `location` : Chemin source des fichiers\n- `tmpDir` : Nom du dossier temporaire à créer\n- `resp` : Objet de réponse Xcraft\n- `overwrite` : Booléen pour forcer l'écrasement (défaut: false)\n\n**Retour :**\n\n```javascript\n{\n  dest: string,        // Chemin de destination\n  unwrap: function     // Fonction de nettoyage\n}\n```\n\n## Licence\n\nCe module est distribué sous [licence MIT](./LICENSE).\n\n---\n\n_Ce contenu a été généré par IA_\n\n[xcraft-core-platform]: https://github.com/Xcraft-Inc/xcraft-core-platform\n[xcraft-core-process]: https://github.com/Xcraft-Inc/xcraft-core-process\n[xcraft-core-etc]: https://github.com/Xcraft-Inc/xcraft-core-etc\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxcraft-inc%2Fxcraft-core-subst","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fxcraft-inc%2Fxcraft-core-subst","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxcraft-inc%2Fxcraft-core-subst/lists"}