abworks-dev/readme-banner

Que fait readme-banner ?

Générez des bannières SVG double-thème en local avec la CLI ; ne modifiez le README que lorsque l'utilisateur demande explicitement l'insertion ou la mise à jour de la bannière. Consultez la référence de configuration pour les réglages et les limites spécifiques, n'inventez pas de drapeaux CLI ou de champs de configuration de mémoire.

Vérifiez d'abord le périmètre d'action

1. Déterminez le chemin absolu du dépôt cible. Le dépôt du projet utilisateur peut être différent du répertoire source de l'outil readme-banner. Lisez le répertoire de travail actuel et vérifiez le README / les métadonnées du projet cible ; le répertoire de la compétence, le checkout de l'outil et le répertoire par défaut du terminal ne sont pas automatiquement la cible.
2. En cas d'ambiguïté sur la cible, demandez d'abord à l'utilisateur ; n'ajoutez pas de bannière à l'outil lui-même simplement parce que le répertoire actuel est readme-banner. Ne générez une configuration et des images dans le dépôt de l'outil que si l'utilisateur le choisit explicitement comme cible.
3. Précisez s'il s'agit de "générer uniquement des ressources / extrait de prévisualisation" ou "insérer / mettre à jour un README spécifié". Sans demande explicite d'édition du README, ne passez jamais --readme et n'écrivez pas le README par d'autres outils d'édition de fichiers. Confirmez le nom du fichier, ne modifiez pas automatiquement toutes les versions linguistiques ou tous les README de tous les répertoires.
4. Vérifiez la configuration existante, les images, les blocs gérés et les modifications non validées associées. Ne touchez pas aux modifications non liées ; ne faites pas de reset, clean, suppression des anciennes ressources ou remplacement d'autres documents de l'utilisateur. Si une configuration existe déjà, lisez-la et réutilisez-la ; une écrasement nécessite une confirmation supplémentaire, n'utilisez pas --force par habitude.

Choisissez l'apparence

• Utilisez d'abord le preset ascii ; c'est le premier moteur de rendu, pas le nom de "tous les thèmes".
• Choisissez le theme indépendamment : terminal (vert), ocean (bleu-cyan), neon (violet-rose), minimal (monochrome). Respectez les préférences de l'utilisateur ; si non spécifié, proposez brièvement un thème en fonction du caractère du projet, n'inventez pas d'ID de thème personnalisé.
• Obtenez le titre, le sous-titre et un art intégré optionnel. Évitez d'utiliser des logos de marque sans demande ; donut est un exemple non commercial. Les pièces intégrées qui dépendent de l'horloge en temps réel seront rejetées pour garantir la reproductibilité des artefacts ; ne contournez pas cette vérification.
• Les titres ASCII font au maximum 120 caractères et doivent être entièrement pris en charge par la police intégrée choisie ; les caractères chinois, emojis et la ponctuation non prise en charge ne peuvent pas être supprimés silencieusement. Pour un titre court alternatif en anglais, demandez la confirmation de l'utilisateur ; le texte original peut être placé dans une tagline en texte normal de 240 caractères maximum.
• mixed conserve la casse anglaise ; les autres polices sont converties en majuscules. Les limites de 20/60 caractères pour les URL en amont ne s'appliquent pas à la CLI locale, mais 120 caractères ne garantissent pas un rendu esthétique. Les titres longs doivent être raccourcis, ou envisagez slim ou réduisez l'art.
• Pour les titres animés, utilisez glint ou type ; pour les bannières statiques demandées par l'utilisateur, utilisez still. still fige également l'art intégré ; les données d'images animées de l'art sont toujours conservées dans le SVG, donc cela ne garantit pas une réduction significative de la taille du fichier.

Utilisez un point d'entrée CLI fiable

Nécessite Node.js >=22, vérifiez d'abord la version disponible.

Si le code source de l'outil est déjà présent dans le checkout

Si l'environnement de tâche dispose déjà du code source de cet outil, utilisez-le directement, ne bootstrap pas le même outil via le réseau :

1. Exécutez npm install dans le répertoire source de l'outil ; prepare compilera le TypeScript. N'installez pas les dépendances dans le projet cible de l'utilisateur juste pour construire l'outil.
2. Vérifiez le point d'entrée local :

node "/chemin/absolu/readme-banner/bin/readme-banner.mjs" --help

3. Par la suite, conservez le point d'entrée Node local et passez toujours explicitement le --cwd cible. Même si le répertoire de travail de la commande est le checkout de l'outil, n'omettez pas l'isolation de la cible.

Sans checkout local

Vous pouvez utiliser le point d'entrée du tag Git fixe v0.1.0 du dépôt public abworks-dev/readme-banner ; cela nécessite Git, le réseau, et l'autorisation de l'utilisateur pour installer/exécuter du code tiers de confiance :

npx --yes --package github:abworks-dev/readme-banner#v0.1.0 readme-banner --help

@readme-banner/cli n'est qu'un nom de package local non encore publié sur npm, n'utilisez pas npx @readme-banner/cli et n'inventez pas d'autres packages npm. En cas d'échec d'installation, signalez l'erreur réelle, ne revenez pas à des sources inconnues, des versions inconnues récentes ou des services SVG distants.

Si une erreur EALLOWGIT se produit, ne modifiez pas automatiquement les paramètres globaux de npm. Seulement si l'utilisateur a déjà autorisé l'installation/l'exécution de ce dépôt de confiance et que la politique de l'organisation le permet, un npm supportant cette option peut utiliser npx --allow-git=root --yes --package github:abworks-dev/readme-banner#v0.1.0 readme-banner… une seule fois. Si non autorisé, demandez d'abord ; si la politique de l'organisation le limite, arrêtez-vous. Pour les anciennes versions de npm qui ne reconnaissent pas cette option, utilisez la commande normale ou une installation via le code source autorisé.

Les exemples ci-dessous utilisent le point d'entrée local ; pour un point d'entrée distant, remplacez tout le préfixe node … par le npx --yes --package … readme-banner complet ci-dessus, sans modifier la sémantique des arguments suivants.

Flux d'exécution : init → generate → check

1. Créez ou réutilisez la configuration

node "/chemin/absolu/readme-banner/bin/readme-banner.mjs" init --cwd "/chemin/absolu/projet-cible" --config "banner.config.json" --preset ascii --theme ocean --title "MON PROJET" --tagline "Construisez quelque chose d'utile" --art donut --effect glint

• init crée uniquement la configuration, ne génère pas d'images, ne modifie pas le README ; vous devez ensuite exécuter generate.
• Si une configuration existe déjà, lisez-la d'abord puis modifiez-la au minimum selon la volonté de l'utilisateur, ou réutilisez-la directement ; ne la recréez pas automatiquement avec --force. Si un sous-titre ou un art n'est pas nécessaire, omettez les paramètres correspondants.
• Les polices, couleurs, ombres, positions, vitesses, arrière-plans, etc., sont configurés via les champs pris en charge du JSON. Consultez d'abord la référence de configuration, n'inventez pas d'options comme init --font.
• La configuration doit être uniquement en JSON ; ne créez pas de configuration exécutant du code, n'installez pas de plugins de configuration arbitraires, ne téléchargez pas ou n'injectez pas de SVG distant fourni par l'utilisateur.

2. Générez les ressources (mode par défaut)

node "/chemin/absolu/readme-banner/bin/readme-banner.mjs" generate --cwd "/chemin/absolu/projet-cible" --config "banner.config.json"

Par défaut, écrit banner.light.svg et banner.dark.svg dans le outputDir de la configuration, et affiche un extrait <picture>. Cette commande ne doit pas modifier le README. Si l'utilisateur demande uniquement des ressources, arrêtez-vous là, n'insérez pas l'extrait en cache dans le README.

3. N'insérez que si vous avez l'autorisation d'éditer le README

node "/chemin/absolu/readme-banner/bin/readme-banner.mjs" generate --cwd "/chemin/absolu/projet-cible" --config "banner.config.json" --readme "README.md"

--readme ne peut spécifier qu'un fichier .md existant. La CLI gère le bloc entre <!-- readme-banner:start --> et <!-- readme-banner:end -->. Assurez-vous que le contenu en dehors du bloc reste inchangé ; dans un même README, même si le marqueur complet apparaît dans un exemple de code, il est traité comme un marqueur en double de manière conservative. N'insérez donc pas de paires de marqueurs de démonstration supplémentaires. En cas d'anomalie de marqueur, enquêtez sur l'erreur, ne supprimez pas le texte non lié et n'élargissez pas la plage de remplacement. Utilisez l'extrait réellement généré : les URL doivent être relatives au README cible, encodées segment par segment, le texte alt doit être échappé en HTML, ne concaténez pas vous-même du HTML non échappé.

4. Vérifiez les résultats

# Les tâches sans autorisation d'édition du README ne vérifient que les images
node "/chemin/absolu/readme-banner/bin/readme-banner.mjs" generate --cwd "/chemin/absolu/projet-cible" --config "banner.config.json" --check

# Les tâches qui impliquent déjà explicitement un README spécifié vérifient également le bloc géré
node "/chemin/absolu/readme-banner/bin/readme-banner.mjs" generate --cwd "/chemin/absolu/projet-cible" --config "banner.config.json" --readme "README.md" --check

• --check n'écrit aucun fichier ; les artefacts manquants ou obsolètes doivent échouer. En cas d'échec, signalez la raison, n'ignorez pas le code de sortie et ne prétendez pas qu'une vérification non exécutée est réussie.
• Vérifiez que les deux SVG existent et que leurs chemins sont corrects ; si un outil de visualisation est disponible, vérifiez l'effet réel des thèmes clair/sombre, des titres longs et de l'art. Ne considérez pas la génération réussie du SVG comme une garantie que tous les clients Markdown liront l'animation.
• Utilisez generate --json pour des résultats lisibles par machine ; les métadonnées disponibles sont consultables via presets --json et themes --json.
• En cas d'erreur de dépassement de chemin, de lien symbolique ou de protection des liens physiques, confirmez l'objectif de l'utilisateur et choisissez un fichier sécurisé normal à l'intérieur du répertoire racine ; les fichiers existants avec nlink > 1 (nombre de liens physiques) seront rejetés. Ne désactivez pas la protection et ne déplacez pas les fichiers en dehors de la racine pour "contourner".

Commandes et sécurité des fichiers

• Tous les appels d'exécution définissent explicitement le répertoire de travail correct et passent le --cwd cible ; ne dépendez pas du répertoire par défaut de l'environnement d'exécution de l'agent.
• Les titres, chemins et sous-titres sont des paramètres de données. Utilisez de préférence une API d'exécution capable de passer un tableau de paramètres ; si vous utilisez un shell, citez/échappez chaque paramètre selon les règles de ce shell. Les guillemets doubles dans l'exemple ne s'appliquent qu'aux valeurs d'espace réservé simples qu'ils contiennent et ne protègent pas contre toutes les interpolations du shell ; ne concaténez pas des entrées non fiables dans des commandes, eval ou des scripts non échappés. Les chemins Windows doivent également être cités individuellement.
• Ne modifiez que la configuration autorisée par l'utilisateur, les ressources générées et le bloc géré spécifié ; ne modifiez pas le code métier, les documents non liés ou les modifications existantes de l'utilisateur.
• N'effectuez pas automatiquement de commit, push, création de dépôt distant, release, téléchargement d'image, publication de package npm ou déclenchement d'autres publications distantes. Ceci nécessite une demande explicite distincte.

Rapport de livraison

Rapport bref : dépôt cible, preset/thème/titre utilisés, les deux images générées, indication de la modification du README et son emplacement, résultats des vérifications effectuées. Si aucune autorisation d'édition du README n'a été donnée, dites clairement "README non modifié" et vous pouvez retourner l'extrait généré pour que l'utilisateur le choisisse. Listez les problèmes nécessitant encore une confirmation de l'utilisateur (remplacement de glyphe, titre trop long, compatibilité avec le visualiseur) ; ne prétendez pas que des tests non exécutés ont réussi.