diff --git a/CHANGELOG.md b/CHANGELOG.md index 24ea04a..5f7ccff 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -16,6 +16,12 @@ Le format suit [Keep a Changelog](https://keepachangelog.com/fr/1.1.0/) et le pr ## [Unreleased] +### Added +- **`@4sh/ui-kit-schematics` embarque son `LICENSE` et ses README** (EN + FR). Le package déclarait `Apache-2.0` sans en fournir le texte, alors que la licence (§4a) demande qu'une redistribution en joigne une copie — d'autant plus ici que ce package existe pour que son contenu soit recopié ailleurs. Sa page npmjs, jusque-là vide, redirige maintenant vers `@4sh/ui-kit` : le compagnon ne s'installe jamais directement. + +### Changed +- **L'en-tête de traçabilité des fichiers copiés par `ng generate @4sh/ui-kit:add` porte la mention de licence** (`Apache-2.0 — Copyright 2026 4SH.`) en plus de son origine et de sa version. Une fois copié, le fichier vit dans le dépôt du consommateur, où plus rien n'indiquait sous quels termes il est fourni. Conséquence attendue : le premier `ng generate @4sh/ui-kit:update` suivant cette version affiche un diff d'une ligne en tête de chaque fichier installé. + ## [0.2.0] - 2026-08-14 Première version depuis la mise en package à porter de véritables changements de diff --git a/docs/PUBLISHING.md b/docs/PUBLISHING.md index 05c611a..2728a18 100644 --- a/docs/PUBLISHING.md +++ b/docs/PUBLISHING.md @@ -77,14 +77,22 @@ Le réglage n'est possible qu'une fois le package **déjà présent** sur le registre : la `0.1.0` a donc été publiée par token, et c'est ce token que la bascule supprime. -> 🔴 **`@4sh/ui-kit-schematics` n'existe pas encore sur le registre.** Il retombe -> donc exactement dans ce cas : sa *première* publication ne peut pas passer par -> Trusted Publishing, faute de page de package sur laquelle le déclarer. Il faut -> la faire **une fois** avec un token (voir « Publier depuis un poste »), puis -> déclarer aussitôt le Trusted Publisher et **révoquer le token**. Tant que ce -> n'est pas fait, lancer le workflow en `dry_run: false` publiera le kit et -> échouera sur le compagnon — d'où l'ordre inverse retenu, qui fait échouer le -> compagnon *avant* que le kit ne parte. +> ℹ️ **`@4sh/ui-kit-schematics` est tombé dans le même cas** (FSHSP-109) : sa +> *première* publication ne pouvait pas passer par Trusted Publishing, faute de +> page de package sur laquelle le déclarer. Un lancement du workflow l'a vérifié +> — échec en `ENEEDAUTH` sur la première étape, l'ordre compagnon→kit ayant +> empêché le kit de partir seul. +> +> Elle a donc été faite **depuis un poste** (voir « Publier depuis un poste »), en +> session `npm login` interactive plutôt qu'avec un token de CI, pour la `0.2.0` +> du 17/08/2026 — les deux packages à la main ce jour-là, puisqu'un compagnon +> déjà publié aurait fait échouer la CI en `403` sur sa propre étape. Deux +> conséquences, propres à cette version : la `0.2.0` ne porte **aucune +> attestation de provenance**, et son tag `v0.2.0` a été poussé à la main, le job +> `release` n'ayant pas tourné. +> +> Amorçage terminé : les deux packages existent, et les versions suivantes +> repassent entièrement par la CI. ### Pourquoi c'est strictement mieux qu'un token @@ -216,8 +224,9 @@ irréversible, et affiche les notes de release telles qu'elles seront rendues. Le workflow publie avec `--provenance` : npmjs affiche un lien vérifiable entre le tarball et le commit + workflow qui l'a produit. Trusted Publishing la rend implicite, mais le drapeau reste explicite — il ne coûte rien et documente -l'intention. Les attestations SLSA de la `0.1.0` et de la `0.1.1` sont -consultables via `npm view @4sh/ui-kit dist --json`. +l'intention. Les attestations SLSA sont consultables via +`npm view @4sh/ui-kit dist --json` — présentes pour toutes les versions publiées +par la CI, absentes de la `0.2.0`, publiée depuis un poste (voir plus haut). --- @@ -227,14 +236,36 @@ La voie normale reste la CI : elle publie depuis un environnement reproductible, sous approbation, avec provenance. Mais si l'OIDC était indisponible, c'est **ici** qu'il faut se replier — pas dans un token de CI. +Les **deux** packages doivent partir, dans le même ordre que la CI — compagnon +d'abord (voir l'avertissement en haut de page). + ```bash npm login # compte 4sh-package-admin, code 2FA à la saisie +npm whoami # doit répondre un nom de compte, pas une erreur + npm run ui-kit:build -cd dist/ui-kit -npm publish --dry-run # toujours, d'abord -npm publish --provenance=false # pas de provenance hors CI : rien à attester +npm run schematics:build + +# parité de version : c'est le contrôle que le job `verify` fait à ta place +node -p "require('./dist/ui-kit/package.json').version + ' / ' + require('./dist/ui-kit-schematics/package.json').version" + +npm publish ./dist/ui-kit-schematics --dry-run # toujours, d'abord +npm publish ./dist/ui-kit --dry-run + +npm publish ./dist/ui-kit-schematics --provenance=false +npm publish ./dist/ui-kit --provenance=false # pas de provenance hors CI + +npm logout ``` +Ne pas se fier au seul `npm login` : une session expirée laisse un jeton dans +`~/.npmrc` et npm répond alors un `404` sur le `PUT` — il masque le refus +d'autorisation plutôt que de révéler l'existence d'un package scopé. D'où le +`npm whoami` avant de publier. En cas de doute, `npm logout` purge le jeton mort. + +Le job `release` n'ayant pas tourné, il reste à poser le tag à la main : +`git tag vX.Y.Z && git push origin vX.Y.Z`. + `npm login` ouvre une **session interactive**, pas un secret partagé : elle est liée au poste, expire, et se ferme avec `npm logout`. C'est ce qui distingue ce repli d'un token de CI. Ne jamais écrire de token dans un fichier suivi par git, @@ -290,8 +321,8 @@ packages, le kit ne sachant que déléguer : npm run schematics:pack # → 4sh-ui-kit-schematics-.tgz npm run ui-kit:pack # → 4sh-ui-kit-.tgz -# dans le projet consommateur — le compagnon d'abord, sinon `ng add` le -# réinstallerait depuis le registre où il n'est pas encore publié +# dans le projet consommateur — le compagnon d'abord, sinon `ng add` tirerait +# la version publiée sur le registre au lieu de celle qu'on veut éprouver npm install -D /chemin/vers/4sh-ui-kit-schematics-.tgz npm install -D /chemin/vers/4sh-ui-kit-.tgz ng generate @4sh/ui-kit:add diff --git a/projects/ui-kit-schematics/LICENSE b/projects/ui-kit-schematics/LICENSE new file mode 100644 index 0000000..9825ffd --- /dev/null +++ b/projects/ui-kit-schematics/LICENSE @@ -0,0 +1,201 @@ + Apache License + Version 2.0, January 2004 + http://www.apache.org/licenses/ + + TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION + + 1. Definitions. + + "License" shall mean the terms and conditions for use, reproduction, + and distribution as defined by Sections 1 through 9 of this document. + + "Licensor" shall mean the copyright owner or entity authorized by + the copyright owner that is granting the License. + + "Legal Entity" shall mean the union of the acting entity and all + other entities that control, are controlled by, or are under common + control with that entity. For the purposes of this definition, + "control" means (i) the power, direct or indirect, to cause the + direction or management of such entity, whether by contract or + otherwise, or (ii) ownership of fifty percent (50%) or more of the + outstanding shares, or (iii) beneficial ownership of such entity. + + "You" (or "Your") shall mean an individual or Legal Entity + exercising permissions granted by this License. + + "Source" form shall mean the preferred form for making modifications, + including but not limited to software source code, documentation + source, and configuration files. + + "Object" form shall mean any form resulting from mechanical + transformation or translation of a Source form, including but + not limited to compiled object code, generated documentation, + and conversions to other media types. + + "Work" shall mean the work of authorship, whether in Source or + Object form, made available under the License, as indicated by a + copyright notice that is included in or attached to the work + (an example is provided in the Appendix below). + + "Derivative Works" shall mean any work, whether in Source or Object + form, that is based on (or derived from) the Work and for which the + editorial revisions, annotations, elaborations, or other modifications + represent, as a whole, an original work of authorship. For the purposes + of this License, Derivative Works shall not include works that remain + separable from, or merely link (or bind by name) to the interfaces of, + the Work and Derivative Works thereof. + + "Contribution" shall mean any work of authorship, including + the original version of the Work and any modifications or additions + to that Work or Derivative Works thereof, that is intentionally + submitted to Licensor for inclusion in the Work by the copyright owner + or by an individual or Legal Entity authorized to submit on behalf of + the copyright owner. For the purposes of this definition, "submitted" + means any form of electronic, verbal, or written communication sent + to the Licensor or its representatives, including but not limited to + communication on electronic mailing lists, source code control systems, + and issue tracking systems that are managed by, or on behalf of, the + Licensor for the purpose of discussing and improving the Work, but + excluding communication that is conspicuously marked or otherwise + designated in writing by the copyright owner as "Not a Contribution." + + "Contributor" shall mean Licensor and any individual or Legal Entity + on behalf of whom a Contribution has been received by Licensor and + subsequently incorporated within the Work. + + 2. Grant of Copyright License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + copyright license to reproduce, prepare Derivative Works of, + publicly display, publicly perform, sublicense, and distribute the + Work and such Derivative Works in Source or Object form. + + 3. Grant of Patent License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + (except as stated in this section) patent license to make, have made, + use, offer to sell, sell, import, and otherwise transfer the Work, + where such license applies only to those patent claims licensable + by such Contributor that are necessarily infringed by their + Contribution(s) alone or by combination of their Contribution(s) + with the Work to which such Contribution(s) was submitted. If You + institute patent litigation against any entity (including a + cross-claim or counterclaim in a lawsuit) alleging that the Work + or a Contribution incorporated within the Work constitutes direct + or contributory patent infringement, then any patent licenses + granted to You under this License for that Work shall terminate + as of the date such litigation is filed. + + 4. Redistribution. You may reproduce and distribute copies of the + Work or Derivative Works thereof in any medium, with or without + modifications, and in Source or Object form, provided that You + meet the following conditions: + + (a) You must give any other recipients of the Work or + Derivative Works a copy of this License; and + + (b) You must cause any modified files to carry prominent notices + stating that You changed the files; and + + (c) You must retain, in the Source form of any Derivative Works + that You distribute, all copyright, patent, trademark, and + attribution notices from the Source form of the Work, + excluding those notices that do not pertain to any part of + the Derivative Works; and + + (d) If the Work includes a "NOTICE" text file as part of its + distribution, then any Derivative Works that You distribute must + include a readable copy of the attribution notices contained + within such NOTICE file, excluding those notices that do not + pertain to any part of the Derivative Works, in at least one + of the following places: within a NOTICE text file distributed + as part of the Derivative Works; within the Source form or + documentation, if provided along with the Derivative Works; or, + within a display generated by the Derivative Works, if and + wherever such third-party notices normally appear. The contents + of the NOTICE file are for informational purposes only and + do not modify the License. You may add Your own attribution + notices within Derivative Works that You distribute, alongside + or as an addendum to the NOTICE text from the Work, provided + that such additional attribution notices cannot be construed + as modifying the License. + + You may add Your own copyright statement to Your modifications and + may provide additional or different license terms and conditions + for use, reproduction, or distribution of Your modifications, or + for any such Derivative Works as a whole, provided Your use, + reproduction, and distribution of the Work otherwise complies with + the conditions stated in this License. + + 5. Submission of Contributions. Unless You explicitly state otherwise, + any Contribution intentionally submitted for inclusion in the Work + by You to the Licensor shall be under the terms and conditions of + this License, without any additional terms or conditions. + Notwithstanding the above, nothing herein shall supersede or modify + the terms of any separate license agreement you may have executed + with Licensor regarding such Contributions. + + 6. Trademarks. This License does not grant permission to use the trade + names, trademarks, service marks, or product names of the Licensor, + except as required for reasonable and customary use in describing the + origin of the Work and reproducing the content of the NOTICE file. + + 7. Disclaimer of Warranty. Unless required by applicable law or + agreed to in writing, Licensor provides the Work (and each + Contributor provides its Contributions) on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or + implied, including, without limitation, any warranties or conditions + of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A + PARTICULAR PURPOSE. You are solely responsible for determining the + appropriateness of using or redistributing the Work and assume any + risks associated with Your exercise of permissions under this License. + + 8. Limitation of Liability. In no event and under no legal theory, + whether in tort (including negligence), contract, or otherwise, + unless required by applicable law (such as deliberate and grossly + negligent acts) or agreed to in writing, shall any Contributor be + liable to You for damages, including any direct, indirect, special, + incidental, or consequential damages of any character arising as a + result of this License or out of the use or inability to use the + Work (including but not limited to damages for loss of goodwill, + work stoppage, computer failure or malfunction, or any and all + other commercial damages or losses), even if such Contributor + has been advised of the possibility of such damages. + + 9. Accepting Warranty or Additional Liability. While redistributing + the Work or Derivative Works thereof, You may choose to offer, + and charge a fee for, acceptance of support, warranty, indemnity, + or other liability obligations and/or rights consistent with this + License. However, in accepting such obligations, You may act only + on Your own behalf and on Your sole responsibility, not on behalf + of any other Contributor, and only if You agree to indemnify, + defend, and hold each Contributor harmless for any liability + incurred by, or claims asserted against, such Contributor by reason + of your accepting any such warranty or additional liability. + + END OF TERMS AND CONDITIONS + + APPENDIX: How to apply the Apache License to your work. + + To apply the Apache License to your work, attach the following + boilerplate notice, with the fields enclosed by brackets "[]" + replaced with your own identifying information. (Don't include + the brackets!) The text should be enclosed in the appropriate + comment syntax for the file format. We also recommend that a + file or class name and description of purpose be included on the + same "printed page" as the copyright notice for easier + identification within third-party archives. + + Copyright 2026 4SH + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. diff --git a/projects/ui-kit-schematics/README.fr.md b/projects/ui-kit-schematics/README.fr.md new file mode 100644 index 0000000..03eb5f5 --- /dev/null +++ b/projects/ui-kit-schematics/README.fr.md @@ -0,0 +1,63 @@ +# @4sh/ui-kit-schematics + +*[English](./README.md) · **Français*** + +Package compagnon de **[`@4sh/ui-kit`](https://www.npmjs.com/package/@4sh/ui-kit)** : +il porte les *sources brutes* des composants du Design System, et les schematics +Angular qui les recopient dans un projet consommateur. + +**Documentation complète (Storybook)** : + + +--- + +## ⚠️ Ne pas installer ce package directement + +Vous ne l'installez jamais vous-même, et vous n'épinglez jamais sa version. Il +est tiré automatiquement par le kit : + +```bash +ng add @4sh/ui-kit +``` + +Tout est documenté sur +[`@4sh/ui-kit`](https://www.npmjs.com/package/@4sh/ui-kit) — c'est ce package +qu'il faut lire, et le seul dont dépendre. + +--- + +## Pourquoi un package séparé + +`ng-packagr` *inline* template et SCSS dans le `.mjs` publié. Les sources que +`ng generate @4sh/ui-kit:add` doit copier n'existent donc nulle part dans le +tarball du kit. Les garder ici a une conséquence voulue : un consommateur +classique de `@4sh/ui-kit`, qui importe seulement les composants compilés, ne les +télécharge jamais. + +Le kit expose une façade de schematics sans aucune logique, qui délègue à ce +package. C'est toute la relation entre les deux. + +## Contenu + +| | | +|---|---| +| `ng-add` | fondation : styles, tokens, `angular.json` | +| `add` | copie les composants dans le projet (sélection interactive, ou `--all`) | +| `update` | diff par composant face aux sources publiées | +| `assets/` | les sources brutes des composants, et la chaîne de génération des tokens | + +## Versionnage + +**Les deux packages portent toujours le même numéro de version**, estampillé +depuis celui du kit à l'assemblage — la façade du kit réclame le compagnon en +`^`. Il n'y a rien à tenir à jour à la main, ni aucune raison +d'épingler ce package vous-même. + +Voir [`docs/VERSIONING.md`](https://github.com/4sh/starter-angular/blob/main/docs/VERSIONING.md) +et [`docs/PUBLISHING.md`](https://github.com/4sh/starter-angular/blob/main/docs/PUBLISHING.md). + +--- + +## Licence + +Apache-2.0 — Copyright 2026 4SH. diff --git a/projects/ui-kit-schematics/README.md b/projects/ui-kit-schematics/README.md new file mode 100644 index 0000000..08c2de9 --- /dev/null +++ b/projects/ui-kit-schematics/README.md @@ -0,0 +1,63 @@ +# @4sh/ui-kit-schematics + +***English** · [Français](./README.fr.md)* + +Companion package of **[`@4sh/ui-kit`](https://www.npmjs.com/package/@4sh/ui-kit)**: +it carries the *raw sources* of the Design System components, and the Angular +schematics that copy them into a consuming project. + +**Full documentation (Storybook)**: + + +--- + +## ⚠️ Do not install this package directly + +You never install it yourself, and you never pin its version. It is pulled in +automatically by the kit: + +```bash +ng add @4sh/ui-kit +``` + +Everything is documented on +[`@4sh/ui-kit`](https://www.npmjs.com/package/@4sh/ui-kit) — that is the package +to read, and the only one to depend on. + +--- + +## Why a separate package + +`ng-packagr` *inlines* templates and SCSS into the published `.mjs`. The sources +that `ng generate @4sh/ui-kit:add` has to copy therefore exist nowhere in the +kit's own tarball. Keeping them here has a deliberate consequence: a regular +consumer of `@4sh/ui-kit`, who only imports compiled components, never downloads +them. + +The kit exposes a schematics facade holding no logic, which delegates to this +package. That is the whole relationship between the two. + +## Contents + +| | | +|---|---| +| `ng-add` | foundation: styles, tokens, `angular.json` | +| `add` | copies components into the project (interactive selection, or `--all`) | +| `update` | per-component diff against the published sources | +| `assets/` | the raw component sources, plus the token generation chain | + +## Versioning + +**The two packages always carry the same version number**, stamped from the +kit's at assembly time — the kit's facade requires the companion in +`^`. There is nothing to keep in sync by hand, and no reason to +pin this package yourself. + +See [`docs/VERSIONING.md`](https://github.com/4sh/starter-angular/blob/main/docs/VERSIONING.md) +and [`docs/PUBLISHING.md`](https://github.com/4sh/starter-angular/blob/main/docs/PUBLISHING.md). + +--- + +## License + +Apache-2.0 — Copyright 2026 4SH. diff --git a/projects/ui-kit-schematics/src/utils/copy.ts b/projects/ui-kit-schematics/src/utils/copy.ts index 5e69c92..de35beb 100644 --- a/projects/ui-kit-schematics/src/utils/copy.ts +++ b/projects/ui-kit-schematics/src/utils/copy.ts @@ -1,25 +1,30 @@ /** * copy — recopie une unité (`AssetUnit`) dans l'arbre du projet consommateur, - * avec en-tête de traçabilité (origine + version) sur chaque fichier. + * avec en-tête de traçabilité (origine + version + licence) sur chaque fichier. */ import type { Tree } from '@angular-devkit/schematics'; import { readFileSync, readdirSync } from 'node:fs'; import { join, relative } from 'node:path'; import type { AssetUnit } from './component-registry'; -const HEADER_STYLE: Record string> = { - '.ts': (body) => `// ${body}\n`, - '.scss': (body) => `// ${body}\n`, - '.html': (body) => `\n`, +const HEADER_STYLE: Record string> = { + '.ts': (lines) => lines.map((l) => `// ${l}`).join('\n') + '\n', + '.scss': (lines) => lines.map((l) => `// ${l}`).join('\n') + '\n', + '.html': (lines) => `\n`, }; function traceabilityHeader(unit: AssetUnit, relPath: string, kitVersion: string, ext: string): string { const make = HEADER_STYLE[ext]; if (!make) return ''; - const body = - `Copié depuis @4sh/ui-kit@${kitVersion} (${unit.kind === 'component' ? unit.category + '/' + unit.name : 'base partagée ' + unit.name}, ${relPath}). ` + - `Géré par ui-kit.json — voir \`ng generate @4sh/ui-kit-schematics:update\`.`; - return make(body); + const origin = unit.kind === 'component' ? `${unit.category}/${unit.name}` : `base partagée ${unit.name}`; + return make([ + `Copié depuis @4sh/ui-kit@${kitVersion} (${origin}, ${relPath}). ` + + `Géré par ui-kit.json — voir \`ng generate @4sh/ui-kit-schematics:update\`.`, + // Le fichier quitte le package pour vivre dans le dépôt du consommateur : + // sans cette ligne, plus rien n'y rattache les termes sous lesquels il est + // fourni (Apache-2.0 §4b — conserver les mentions dans les copies). + `Apache-2.0 — Copyright 2026 4SH.`, + ]); } function walk(dir: string): string[] { diff --git a/scripts/schematics-package.build.mjs b/scripts/schematics-package.build.mjs index 4dc147d..a80a06f 100644 --- a/scripts/schematics-package.build.mjs +++ b/scripts/schematics-package.build.mjs @@ -48,7 +48,10 @@ const companionPkg = JSON.parse(readFileSync(join(PKG, 'package.json'), 'utf8')) const kitVersion = JSON.parse(readFileSync(join(ROOT, 'projects/ui-kit/package.json'), 'utf8')).version; companionPkg.version = kitVersion; writeFileSync(join(DEST, 'package.json'), JSON.stringify(companionPkg, null, 2) + '\n'); -for (const name of ['README.md', 'README.fr.md']) { +// LICENSE inclus : l'Apache-2.0 (§4a) demande que toute redistribution en +// fournisse une copie, et ce package est précisément fait pour que son contenu +// soit recopié ailleurs. +for (const name of ['README.md', 'README.fr.md', 'LICENSE']) { const src = join(PKG, name); if (existsSync(src)) copyFileSync(src, join(DEST, name)); }