yes.exe ypack install ypack@0.3.0

Module ypack

Gestionnaire de paquets pour YScript : installer, rechercher, empaqueter et publier des bibliothèques externes (modules require-ables ou simples dossiers/scripts de travail). Spécification complète : documentation/specs/ypack-package-system.md (comportement de référence) et documentation/specs/ypack-gallery-api.md (contrat HTTP des sources distantes).

ypack s'utilise aussi bien comme bibliothèque (require("ypack")) que via la commande CLI yes.exe ypack <commande> ... (un routeur mince au-dessus de la même bibliothèque — voir La commande yes.exe ypack plus bas).

local ypack = require("ypack")

ypack.install("csv-tools")
local manifest = ypack.info("csv-tools")
print(manifest.name, manifest.version)

$ yes.exe ypack install csv-tools
$ yes.exe ypack list

Concepts

Le manifeste ypack.json

Chaque paquet publiable a, à sa racine, un ypack.json :

{
  "name": "csv-tools",
  "version": "1.2.0",
  "description": "Lecture/écriture de fichiers CSV",
  "engines": { "yscript": ">=0.3.0" },
  "dependencies": { "otherpackage": "^1.0.0" },
  "provides": { "module": true, "command": true }
}

name/version ne sont requis que pour un paquet publiable — un ypack.json qui n'a que dependencies est un manifeste consommateur (déclare les dépendances d'un dossier de travail ou d'un script, sans intention de publication ; voir ypack.ensure). ypack ne distingue pas structurellement les deux : c'est la présence de name+version qui fait la différence.

Un paquet publiable a en plus, à sa racine, un point d'entrée : init.yes (module require-able) et/ou command.yes (sous-commande CLI), et optionnellement documentation/index.md (voir ypack.doc).

Niveaux d'installation

Un paquet s'installe à l'un de trois niveaux, chacun avec sa propre racine de dossier :

Niveau	Racine	Portée
current	package.currentroot	À côté de l'exécutable yes.exe
user	package.userroot (défaut)	Profil de l'utilisateur courant
global	package.globalroot	Partagé par tous les utilisateurs de la machine

La résolution d'un paquet installé (ypack.info, ypack.uninstall, ypack.doc, et la vérification de dépendances déjà satisfaites) cherche dans cet ordre — current → user → global — quand aucun niveau n'est précisé, ce qui permet à une installation --current de surcharger localement un paquet déjà présent à un niveau plus large.

Registre local

Chaque racine d'installation a son propre registre, un fichier ypack-lock.json à sa racine (donc <niveau>root>/ypack-lock.json — ex. package.userroot .. "/ypack-lock.json" pour le niveau user) : ypack.list/ypack.info/ypack.uninstall/ypack.update s'appuient dessus plutôt que de re-parcourir tous les manifestes du dossier à chaque appel. Il recense, pour chaque paquet installé à ce niveau, sa version exacte et sa source d'origine (laquelle des sources configurées l'a fourni) — c'est cette information que ypack.update réutilise pour réinstaller depuis la même source plutôt que de re-parcourir la liste configurée.

Un dossier de module présent physiquement sans entrée correspondante dans ce fichier (installation manuelle, copie directe...) est détecté comme tel par ypack.update (voir plus bas), qui refuse de le mettre à jour automatiquement plutôt que de deviner une origine.

Sources

Une source est un dépôt de paquets — soit un dossier local, soit une galerie HTTP (URL http(s)://, contrat détaillé dans documentation/specs/ypack-gallery-api.md). ypack.search, ypack.install et ypack.publish sans source explicite utilisent la liste configurée (ypack.sources()), essayée dans l'ordre jusqu'à la première source où le paquet est trouvé.

La configuration des sources vit dans un ypack-config.json :

{
  "sources": [
    "https://yscript.ygrenier.fr",
    { "url": "https://galerie-interne.example.com", "token": "mon-jeton-de-publication" },
    "D:/mes-paquets-locaux"
  ]
}

Une entrée est soit une chaîne (URL ou chemin de dossier), soit une table {url=..., token=...} — le token n'est utile que pour ypack.publish vers cette source (voir plus bas). Emplacement du fichier :

• Config projet : ypack-config.json à côté d'un ypack.json, dans le dossier courant — pris

en compte uniquement si les deux fichiers coexistent. Remplace entièrement la config utilisateur pour les opérations menées depuis ce dossier (pas de fusion).

• Config utilisateur (défaut) : <userpath>/yeg/yscript/ypack-config.json.
• Sans aucun fichier de config : une seule source par défaut,

https://yscript.ygrenier.fr.

Résolution de version / dépendances

ypack.install accepte un deuxième argument optionnel qui précise la version voulue :

Forme	Exemple	Signification
(omis)	—	Dernière version publiée
exacte	"1.2.3"	Exactement cette version
caret	"^1.2.3"	Même version majeure, >= 1.2.3 (dernière compatible retenue)
minimum	">=1.2.3"	N'importe quelle version >= 1.2.3 (dernière retenue)

Les dépendances déclarées par manifest.dependencies d'un paquet installé sont résolues automatiquement (récursivement) au moment de ypack.install : chaque dépendance manquante est installée, chaque dépendance déjà installée est vérifiée contre sa contrainte. Un conflit — une dépendance déjà installée dans une version qui ne satisfait pas la contrainte demandée — est une erreur explicite, pas une résolution silencieuse (pas de gestion multi-versions d'un même paquet). Une dépendance circulaire (A → B → A) ne boucle pas : A est enregistrée comme installée avant que ses propres dépendances ne soient traitées.

Immutabilité des versions publiées

Une fois name+version publiés sur une source (locale ou HTTP), republier exactement le même couple est refusé (message d'erreur en local, 409 Conflict sur une galerie HTTP) — les versions sont immuables, un consommateur qui a téléchargé une version doit toujours en retrouver le même contenu. Publier un correctif nécessite un nouveau numéro de version.

Vue d'ensemble — API (require("ypack"))

Fonction	Description
ypack.VERSION	Version du module ypack lui-même (chaîne)
ypack.LEVELS	{ "current", "user", "global" }
ypack.root(level)	Racine de dossier d'un niveau d'installation
ypack.list([level])	Paquets installés (registre local)
ypack.info(name [, level])	Manifeste d'un paquet installé
ypack.uninstall(name [, level])	Désinstalle un paquet
ypack.update(name [, level])	Met à jour un paquet installé depuis sa source d'origine
ypack.installfile(zippath [, level])	Installe une archive .zip déjà présente sur le disque
ypack.sources()	Liste ordonnée des sources configurées
ypack.search(query [, source])	Recherche un paquet dans les sources configurées (ou une source unique)
ypack.install(name [, versionorconstraint [, level [, source]]])	Résout et installe un paquet (+ ses dépendances) depuis les sources
ypack.ensure([manifestpath])	Installe les dépendances manquantes d'un manifeste consommateur
ypack.pack(src, destzip)	Empaquette un dossier/script en archive .zip
ypack.doc(name [, level])	Documentation (documentation/index.md) d'un paquet
ypack.publish(zippath [, source [, token]])	Publie une archive vers une source

Vue d'ensemble — CLI (yes.exe ypack ...)

Commande	Description
version	Affiche la version
help	Affiche l'aide
list	Liste les paquets installés
info <nom>	Affiche le manifeste d'un paquet installé
search [requête]	Recherche dans les sources configurées
install [nom|archive.zip] [version]	Installe un paquet, une archive, ou les dépendances du projet si omis
uninstall <nom>	Désinstalle un paquet
update <nom>	Met à jour un paquet installé depuis sa source d'origine
pack <source> <dest.zip>	Empaquette un dossier ou un script isolé
doc <nom>	Affiche la documentation d'un paquet
publish <archive.zip>	Publie une archive vers une source

Options communes, applicables selon la commande (voir chaque section pour le détail) : --current/--user/--global (niveau d'installation), --source <src> (source unique explicite, bypass la liste configurée), --token <jeton> (authentification de publication vers une source HTTP).

---

ypack.VERSION

Chaîne, version du module ypack lui-même (pas celle des paquets qu'il gère).

ypack.LEVELS

Tableau { "current", "user", "global" }, dans l'ordre de résolution utilisé partout où un niveau n'est pas explicite.

ypack.root(level)

Retourne le chemin de la racine de dossier correspondant à level ("current", "user" ou "global") — lève une erreur si level n'est pas l'une de ces trois valeurs.

print(ypack.root("user"))   --> ex. C:/Users/alice/AppData/Roaming/yeg/yscript/0.3

ypack.list([level])

Retourne un tableau des paquets installés (indices 1..n), chaque entrée : { name, version, source, level } — source est la source d'origine enregistrée lors de l'installation. Sans level, agrège les trois niveaux.

for _, pkg in ipairs(ypack.list()) do
    print(pkg.name, pkg.version, pkg.level)
end

ypack.info(name [, level])

Retourne le manifeste complet (ypack.json décodé) du paquet name installé, augmenté de deux champs : level (niveau où il a été trouvé) et installdir (dossier d'installation). Cherche current → user → global si level est omis.

nil, message si le paquet n'est pas installé à ce niveau (ou à aucun niveau, si level est omis).

local manifest, err = ypack.info("csv-tools")
if manifest then
    print(manifest.name, manifest.version, manifest.installdir)
else
    print("non installé : " .. err)
end

ypack.uninstall(name [, level])

Supprime le dossier d'installation du paquet name et le retire du registre local. nil, message si le paquet n'est pas installé (au niveau donné, ou à aucun niveau si level est omis).

local ok, err = ypack.uninstall("csv-tools")

ypack.update(name [, level])

Met à jour un paquet installé vers la dernière version disponible sur sa source d'origine — celle enregistrée dans le registre local (ypack-lock.json) lors de son installation. Ne re-parcourt jamais la liste des sources configurées : une mise à jour ne peut pas basculer silencieusement l'origine d'un paquet si cette liste a changé depuis l'installation initiale. Cherche current → user → global si level est omis (comme ypack.info).

Retourne manifest, previousversion — comparez manifest.version à previousversion pour savoir si une mise à jour a effectivement eu lieu (identiques : déjà à jour). nil, message si :

• le paquet n'est pas installé ;
• il l'est mais absent du registre local (installation manuelle du dossier, ypack ne peut pas

garantir son origine) ;

• sa source d'origine n'est plus configurée/joignable (paquet introuvable dessus, réseau en

panne...) — pas de repli silencieux sur une autre source.

local manifest, previousversion = ypack.update("csv-tools")
if manifest then
    if manifest.version == previousversion then
        print("déjà à jour : " .. manifest.version)
    else
        print(previousversion .. " -> " .. manifest.version)
    end
end

ypack.installfile(zippath [, level])

Installe directement une archive .zip déjà présente sur le disque (pas de résolution depuis une source — utile pour une archive reçue hors galerie). level par défaut "user". Retourne le manifeste installé, ou nil, message (archive absente, ypack.json absent/invalide de l'archive, point d'entrée manquant...).

local manifest, err = ypack.installfile("csv-tools-1.2.0.zip")

ypack.sources()

Retourne la liste ordonnée des sources configurées (voir Sources ci-dessus) : celle du projet courant si ypack.json+ypack-config.json coexistent dans le dossier courant, sinon celle de l'utilisateur, sinon { "https://yscript.ygrenier.fr" } par défaut.

for i, src in ipairs(ypack.sources()) do
    print(i, type(src) == "table" and src.url or src)
end

ypack.search(query [, source])

Recherche query (sous-chaîne, insensible à la casse côté galerie HTTP ; correspondance sur le nom côté source locale) dans les sources configurées, ou uniquement dans source si fourni (bypass la liste configurée). query vide ou omis liste tous les paquets disponibles.

Retourne un tableau d'entrées { name, version, description, source } (une par paquet, la dernière version publiée). Une source HTTP injoignable ou en erreur ne fait pas échouer la recherche globale — elle contribue simplement zéro résultat.

for _, r in ipairs(ypack.search("csv")) do
    print(r.name, r.version, r.description)
end

ypack.install(name [, versionorconstraint [, level [, source]]])

Résout name/versionorconstraint (voir Résolution de version ci-dessus) dans source si fourni, sinon dans les sources configurées essayées dans l'ordre ; télécharge/copie l'archive, l'installe dans level (défaut "user"), enregistre le paquet dans le registre local, puis installe récursivement ses dépendances déclarées. Une installation existante du même nom à ce niveau est remplacée.

Retourne le manifeste installé, ou nil, message (paquet introuvable dans les sources, conflit de dépendance, archive invalide, checksum invalide sur téléchargement HTTP...).

ypack.install("csv-tools")                     -- dernière version
ypack.install("csv-tools", "^1.0.0")            -- contrainte caret
ypack.install("csv-tools", "1.2.0", "global")   -- version exacte, niveau global
ypack.install("csv-tools", nil, "user", "D:/mes-paquets-locaux")  -- source explicite

ypack.ensure([manifestpath])

Installe (niveau "user" par défaut pour les nouvelles, cherche tous les niveaux pour détecter une dépendance déjà présente) chaque dépendance déclarée dans un manifeste consommateur — ypack.json (contenant seulement dependencies) ou script isolé <nom>.ypack.json — non déjà installée dans une version satisfaisant sa contrainte. Idempotent.

• manifestpath explicite : chemin direct vers le fichier manifeste à utiliser.
• Omis : cherche ypack.json dans le dossier courant, sinon un unique *.ypack.json. Erreur si

ambigu (les deux coexistent, ou plusieurs *.ypack.json sans ypack.json).

Retourne la liste des noms de paquets effectivement (ré)installés au cours de cet appel, ou nil, message.

local installed, err = ypack.ensure()          -- lit ./ypack.json ou l'unique *.ypack.json
local installed, err = ypack.ensure("my-script.ypack.json")

ypack.pack(src, destzip)

Empaquette src (dossier ou fichier .yes) vers l'archive destzip. Deux modes, selon src :

• Dossier avec ypack.json publiable (name+version) : valide la présence d'un point

d'entrée (init.yes ou <name>.dll) avant d'empaqueter — erreur explicite si absent. Retourne true, "<name>@<version>".

• Dossier avec ypack.json non publiable, ou sans ypack.json : empaquette tel quel (bundle de

transmission consommateur, §4.5). Retourne true, "scripts + ypack.json" s'il y avait un manifeste, true, nil sinon.

• Script isolé (src est un fichier .yes) : nécessite un manifeste consommateur associé

<base>.ypack.json à côté du script — erreur sinon. Archive construite entrée par entrée (juste les deux fichiers). Retourne true, "<script>.yes + <script>.ypack.json".

nil, message en cas d'échec (source introuvable, point d'entrée manquant, manifeste consommateur associé introuvable pour un script isolé).

ypack.pack("dist/csv-tools", "csv-tools-1.2.0.zip")   -- paquet publiable
ypack.pack("myproject/", "myproject-bundle.zip")       -- bundle dossier consommateur
ypack.pack("my-script.yes", "my-script-bundle.zip")    -- bundle script isolé

ypack.doc(name [, level])

Retourne le contenu de documentation/index.md du paquet name — cherché d'abord parmi les paquets installés (level, ou tous niveaux si omis), sinon dans les sources configurées (dernière version publiée de chaque source, essayées dans l'ordre). nil, message si introuvable partout, ou si le paquet existe mais n'a pas de documentation.

local content, err = ypack.doc("csv-tools")
if content then print(content) end

ypack.publish(zippath [, source [, token]])

Publie l'archive zippath (doit contenir un ypack.json publiable, name+version) vers source :

• source omis : utilise la première source configurée (ypack.sources()[1]).
• source une entrée de configuration (chaîne, ou table {url=..., token=...}) ou une URL/chemin

de dossier explicite.

• token explicite prime toujours sur celui porté par une entrée de configuration table.

Un jeton est requis pour publier vers une source HTTP (--token, ou configuré pour cette source dans ypack-config.json) — jamais requis pour une source en dossier local, où il n'a aucun sens. Voir documentation/specs/ypack-gallery-api.md §6.2 pour le format d'authentification côté galerie.

Refuse (voir Immutabilité des versions) si name/version sont déjà publiés sur cette source.

true en cas de succès, nil, message sinon.

ypack.publish("csv-tools-1.2.0.zip")                                       -- 1ère source configurée
ypack.publish("csv-tools-1.2.0.zip", "D:/mes-paquets-locaux")              -- source locale explicite
ypack.publish("csv-tools-1.2.0.zip", "https://galerie.example.com", "mon-jeton")

---

La commande yes.exe ypack

Routeur mince au-dessus de l'API ci-dessus : parse les arguments/flags, appelle la fonction ypack.* correspondante, met en forme le résultat sur la sortie standard (erreur sur la sortie d'erreur, code de sortie 1).

Options communes

Option	Commandes concernées	Effet
--current / --user / --global	list, info, install, uninstall, update, doc	Force le niveau d'installation (défaut --user, cf. ypack.LEVELS)
--source <src>	search, install, publish	Source unique explicite, bypass la liste configurée
--token <jeton>	publish	Jeton d'authentification pour une source HTTP

yes.exe ypack version

Affiche ypack <VERSION>. Commande par défaut (yes.exe ypack sans argument fait de même).

yes.exe ypack help

Affiche la liste des commandes et options disponibles.

yes.exe ypack list

Liste les paquets installés (ypack.list), une ligne <nom> <version> (<niveau>) par paquet. Aucun paquet installé. si le registre est vide.

yes.exe ypack info <nom>

Affiche le manifeste d'un paquet installé (ypack.info) : nom, version, description si présente, dossier d'installation.

yes.exe ypack search [requête]

Recherche (ypack.search) dans les sources configurées (ou --source <src> pour une source unique). Aucun résultat. si rien ne correspond, sinon une ligne <nom> <version> - <description> par résultat.

yes.exe ypack install [nom|archive.zip] [version]

Trois formes, selon l'argument :

• Sans argument : installe les dépendances déclarées par le manifeste consommateur du dossier

courant (ypack.ensure(), voir la détection automatique ypack.json/*.ypack.json décrite plus haut).

• Un chemin vers un fichier .zip existant : installe directement cette archive

(ypack.installfile).

• Un nom de paquet, avec une version/contrainte optionnelle en second argument positionnel :

résout et installe depuis les sources configurées ou --source <src> (ypack.install).

$ yes.exe ypack install                     -- dépendances du projet courant
$ yes.exe ypack install csv-tools           -- dernière version
$ yes.exe ypack install csv-tools ^1.0.0    -- contrainte caret
$ yes.exe ypack install csv-tools-1.2.0.zip -- archive locale

yes.exe ypack uninstall <nom>

Désinstalle un paquet (ypack.uninstall).

yes.exe ypack update <nom>

Met à jour un paquet installé (ypack.update) et affiche <nom> <version> : déjà à jour ou <nom> <ancienne> -> <nouvelle> : mis à jour selon le cas.

$ yes.exe ypack update csv-tools
csv-tools 1.2.0 -> 1.3.0 : mis à jour

yes.exe ypack pack <source> <dest.zip>

Empaquette <source> (dossier ou script .yes) vers <dest.zip> (ypack.pack) et affiche Archive créée : <dest.zip>, suivi entre parenthèses d'une description du contenu quand un manifeste a été trouvé — (nom@version) pour un paquet publiable, (scripts + ypack.json) pour un bundle de dossier consommateur, (script.yes + script.ypack.json) pour un bundle de script isolé. La destination doit toujours être fournie explicitement : contrairement à un paquet publiable (nommage déductible <nom>-<version>.zip), un bundle consommateur n'a ni nom ni version à en tirer.

$ yes.exe ypack pack dist/csv-tools csv-tools-1.2.0.zip
Archive créée : csv-tools-1.2.0.zip (csv-tools@1.2.0)

$ yes.exe ypack pack myproject/ myproject-bundle.zip
Archive créée : myproject-bundle.zip (scripts + ypack.json)

yes.exe ypack doc <nom>

Affiche la documentation (ypack.doc) d'un paquet, installé ou disponible dans les sources configurées.

yes.exe ypack publish <archive.zip>

Publie une archive (ypack.publish) vers --source <src> si fourni, sinon la première source configurée. --token <jeton> pour l'authentification vers une source HTTP (sinon celui configuré pour cette source dans ypack-config.json).

$ yes.exe ypack publish csv-tools-1.2.0.zip
$ yes.exe ypack publish csv-tools-1.2.0.zip --source https://galerie.example.com --token mon-jeton

Erreurs

Sauf mention contraire ci-dessus, toutes les fonctions de l'API retournent nil, message en cas d'échec plutôt que de lever une erreur script — cohérent avec le style io.open/zip.open. Les échecs de décodage JSON internes (ypack.json corrompu, réponse de galerie invalide) sont également remontés sous cette forme, jamais laissés se propager comme une erreur script brute.

Côté CLI, un échec écrit le message sur la sortie d'erreur (préfixé ypack: ) et termine le processus avec le code de sortie 1.

Limites connues (v1)

• Pas de résolveur de conflits multi-versions façon npm : un conflit de contrainte sur une

dépendance déjà installée est une erreur, pas une résolution automatique (dé-duplication par sous-arbre, versions multiples d'un même paquet côte à côte, etc.).

• Pas de verrouillage/contrôle de propriété sur la publication (v1) — n'importe quel jeton valide

pour une source peut publier n'importe quel nom de paquet sur cette source.

• ypack.update vise toujours la dernière version publiée sur la source d'origine — pas de

contrainte SemVer pour borner la mise à jour (ex. rester sur la même version majeure).