@numericoach/gskills-admin-cli 0.1.3 → 0.1.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -41,9 +41,10 @@ gskills-admin cache invalidate --instance <instanceId> --scope menu-bundle --yes
41
41
  Operational helpers are available for the admin-only flows agents should not improvise:
42
42
 
43
43
  ```bash
44
- gskills-admin feedback claim <feedbackId> --dry-run --output json
45
- gskills-admin feedback send-claim <feedbackId> --recipient-email user@example.com --subject "..." --body "..." --yes --output json
44
+ gskills-admin feedback send-reply <feedbackId> --subject "GSkills - ..." --body-file ./reply.txt --dry-run --output json
46
45
  gskills-admin access grant --user <userId> --type DEFAULT --dry-run --output json
46
+ gskills-admin instances create-plan --output json
47
+ gskills-admin instances create --data '{"name":"Client","URL":"client","licenceType":"STARTER","tokensAllowed":50}' --dry-run --output json
47
48
  gskills-admin entities list --instance <instanceId> --output json
48
49
  gskills-admin entities set-page-visibility --instance <instanceId> --page <pageId> --entity-ids google-group:team@example.com --dry-run --output json
49
50
  gskills-admin org-units-sync google --instance <instanceId> --yes --output json
@@ -690,7 +690,7 @@ var resourceHelpRows = () => resources.map((resource) => ({
690
690
  aliases: resource.aliases.join(", ")
691
691
  }));
692
692
  // ../../src/cli/commands.ts
693
- import { cp, mkdir as mkdir2, stat } from "node:fs/promises";
693
+ import { cp, mkdir as mkdir2, readFile as readFile2, stat } from "node:fs/promises";
694
694
  import { dirname as dirname2, join as join2 } from "node:path";
695
695
  import { fileURLToPath } from "node:url";
696
696
  var runCommand = async (ctx) => {
@@ -719,6 +719,9 @@ var runCommand = async (ctx) => {
719
719
  return runOrgUnitsSyncCommand(actionOrResource, ctx);
720
720
  if (group === "ambassadors" && actionOrResource === "label")
721
721
  return runAmbassadorsCommand(actionOrResource, ctx);
722
+ if ((group === "instances" || group === "instance") && (actionOrResource === "create" || actionOrResource === "create-plan")) {
723
+ return runInstanceCreationCommand(actionOrResource, ctx);
724
+ }
722
725
  const resource = findResource(group);
723
726
  return runResourceCommand(resource, actionOrResource, maybeAction, rest, ctx);
724
727
  };
@@ -898,8 +901,53 @@ var runFeedbackCommand = async (action, feedbackId, ctx) => {
898
901
  })
899
902
  });
900
903
  }
904
+ if (action === "send-reply") {
905
+ if (!feedbackId)
906
+ throw new CliError("Missing feedback id", 2);
907
+ if (!hasFlag(ctx, "yes") && !hasFlag(ctx, "dry-run")) {
908
+ throw new CliError("Sending feedback reply email requires --yes or --dry-run", 2);
909
+ }
910
+ const subject = await getTextFlag(ctx, "subject", "subject-file");
911
+ const body = await getTextFlag(ctx, "body", "body-file");
912
+ const translatedSubject = await getTextFlag(ctx, "translated-subject", "translated-subject-file");
913
+ const translatedBody = await getTextFlag(ctx, "translated-body", "translated-body-file");
914
+ if (!subject || !body)
915
+ throw new CliError("Missing --subject or --body", 2);
916
+ return requestApi("/api/cli/feedback/send-reply", {
917
+ method: "POST",
918
+ body: JSON.stringify({
919
+ feedbackId,
920
+ subject,
921
+ body,
922
+ translatedSubject,
923
+ translatedBody,
924
+ userLanguage: getStringFlag(ctx, "user-language"),
925
+ currentLanguage: getStringFlag(ctx, "current-language") ?? "fr",
926
+ dryRun: hasFlag(ctx, "dry-run")
927
+ })
928
+ });
929
+ }
901
930
  throw new CliError(`Unknown feedback command "${action}"`, 2);
902
931
  };
932
+ var runInstanceCreationCommand = async (action, ctx) => {
933
+ if (!action || action === "help" || action === "create-plan")
934
+ return instanceCreateHelp();
935
+ if (action !== "create")
936
+ throw new CliError(`Unknown instances command "${action}"`, 2);
937
+ const data = parseJsonObject(getStringFlag(ctx, "data"), "--data");
938
+ if (Object.keys(data).length === 0)
939
+ throw new CliError("Missing --data JSON", 2);
940
+ if (!hasFlag(ctx, "yes") && !hasFlag(ctx, "dry-run")) {
941
+ throw new CliError("Guided instance creation writes production data. Add --yes or use --dry-run.", 2);
942
+ }
943
+ return requestApi("/api/cli/instances/create", {
944
+ method: "POST",
945
+ body: JSON.stringify({
946
+ data,
947
+ dryRun: hasFlag(ctx, "dry-run")
948
+ })
949
+ });
950
+ };
903
951
  var runAccessCommand = async (action, ctx) => {
904
952
  if (!action || action === "help")
905
953
  return accessHelp();
@@ -1308,6 +1356,13 @@ var getStringFlag = (ctx, name) => {
1308
1356
  return value;
1309
1357
  return;
1310
1358
  };
1359
+ var getTextFlag = async (ctx, inlineName, fileName) => {
1360
+ const filePath = getStringFlag(ctx, fileName);
1361
+ if (filePath) {
1362
+ return readFile2(filePath, "utf8");
1363
+ }
1364
+ return getStringFlag(ctx, inlineName);
1365
+ };
1311
1366
  var getNumberFlag = (ctx, name) => {
1312
1367
  const value = getStringFlag(ctx, name);
1313
1368
  if (!value)
@@ -1359,8 +1414,11 @@ var schemaHelp = () => ({
1359
1414
  { name: "cache invalidate", required: ["--instance"], flags: ["--scope", "--languages", "--yes", "--dry-run"], writes: true },
1360
1415
  { name: "feedback claim", args: ["feedbackId"], flags: ["--dry-run"], writes: true },
1361
1416
  { name: "feedback send-claim", args: ["feedbackId"], flags: ["--recipient-email", "--recipient-name", "--cc", "--subject", "--body", "--yes", "--dry-run"], writes: true },
1417
+ { name: "feedback send-reply", args: ["feedbackId"], flags: ["--subject", "--subject-file", "--body", "--body-file", "--translated-subject", "--translated-subject-file", "--translated-body", "--translated-body-file", "--user-language", "--current-language", "--yes", "--dry-run"], writes: true },
1362
1418
  { name: "access grant", required: ["--user"], flags: ["--type", "--start-at", "--custom-duration-days", "--preferred-language", "--yes", "--dry-run"], writes: true },
1363
1419
  { name: "access revoke-active", required: ["--user"], flags: ["--yes", "--dry-run"], writes: true },
1420
+ { name: "instances create-plan", writes: false },
1421
+ { name: "instances create", flags: ["--data", "--yes", "--dry-run"], writes: true },
1364
1422
  { name: "entities list", required: ["--instance"], flags: ["--language"], writes: false },
1365
1423
  { name: "entities detail", args: ["entityId"], required: ["--instance"], flags: ["--language"], writes: false },
1366
1424
  { name: "entities access-summary", required: ["--instance"], writes: false },
@@ -1430,11 +1488,42 @@ var cacheHelp = () => ({
1430
1488
  });
1431
1489
  var feedbackHelp = () => ({
1432
1490
  usage: [
1491
+ "gskills-admin feedback send-reply <feedbackId> --subject 'GSkills - ...' --body-file ./reply.fr.txt --dry-run",
1492
+ "gskills-admin feedback send-reply <feedbackId> --subject 'GSkills - ...' --body-file ./reply.fr.txt --yes",
1433
1493
  "gskills-admin feedback claim <feedbackId> --dry-run",
1434
1494
  "gskills-admin feedback claim <feedbackId>",
1435
1495
  "gskills-admin feedback send-claim <feedbackId> --recipient-email user@example.com --subject '...' --body '...' --yes"
1436
1496
  ],
1437
- note: "Claiming and sending emails use the same SLA recipient rules as the admin feedback UI and log through admin logs."
1497
+ note: "send-reply is the normal feedback detail email template flow. claim/send-claim is only the SLA ticket-taken-in-charge flow."
1498
+ });
1499
+ var instanceCreateHelp = () => ({
1500
+ usage: [
1501
+ "gskills-admin instances create-plan --output json",
1502
+ `gskills-admin instances create --data '{"name":"Client","URL":"client","licenceType":"STARTER","tokensAllowed":50}' --dry-run --output json`,
1503
+ "gskills-admin instances create --data '{...}' --yes --output json"
1504
+ ],
1505
+ path: [
1506
+ "1. Créer l'instance: name, URL, clientType, RunningState",
1507
+ "2. Licence et sièges: licenceType, tokensAllowed",
1508
+ "3. Langues: languageCodes, mainLanguage",
1509
+ "4. Fonctionnalités: aiEnabled",
1510
+ "5. Accès: InstanceAddStyle with domainGranular, accountGranular or later entity rules",
1511
+ "6. Contacts client: clientContacts, each becomes COMMANDITARY with unlimited pass",
1512
+ "7. Synchroniser: launchChecklist.syncFromGlobal",
1513
+ "8. Valider: one final production write",
1514
+ "9. Préparer la livraison: use the generated delivery email outside the CLI"
1515
+ ],
1516
+ requiredData: ["name", "URL", "licenceType", "tokensAllowed"],
1517
+ defaults: {
1518
+ RunningState: true,
1519
+ aiEnabled: true,
1520
+ languageCodes: ["fr", "en"],
1521
+ mainLanguage: "fr",
1522
+ InstanceAddStyle: "ALL unless granular values are provided",
1523
+ clientType: "NUMERICOACH_LICENSE",
1524
+ syncFromGlobal: true
1525
+ },
1526
+ warning: "This uses the guided creation workflow. Raw Prisma instance creation is intentionally not the default CLI path."
1438
1527
  });
1439
1528
  var accessHelp = () => ({
1440
1529
  usage: [
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@numericoach/gskills-admin-cli",
3
- "version": "0.1.3",
3
+ "version": "0.1.5",
4
4
  "private": false,
5
5
  "type": "module",
6
6
  "description": "Admin-only CLI for GSkills super-admin operations.",
@@ -258,9 +258,30 @@ gskills-admin cache invalidate --instance <instanceId> --scope menu-bundle --yes
258
258
  gskills-admin cache invalidate --instance <instanceId> --scope all --yes --output json
259
259
  ```
260
260
 
261
- ## Feedback And SLA Emails
261
+ ## Feedback Emails
262
262
 
263
- Use these commands for feedback claim email flows. They reuse the same SLA contact flags and recipient validation as the admin feedback UI.
263
+ Use `send-reply` for the normal email available from the feedback detail dialog. It uses the `GSkillsEmail` template, sends to the feedback user, stores a `FeedbackReply`, updates `repliedAt`, and writes admin logs.
264
+
265
+ ```bash
266
+ gskills-admin feedback send-reply <feedbackId> --subject "GSkills - ..." --body-file ./reply.txt --dry-run --output json
267
+ gskills-admin feedback send-reply <feedbackId> --subject "GSkills - ..." --body-file ./reply.txt --yes --output json
268
+ ```
269
+
270
+ Always answer in the language of the user's feedback or the user's UI language. If the feedback is in English, answer in English. If it is in Portuguese, answer in Portuguese. Do not default to French unless the feedback/user language is French.
271
+
272
+ For same-language replies, pass both language flags with that language:
273
+
274
+ ```bash
275
+ gskills-admin feedback send-reply <feedbackId> --subject "GSkills - Reply" --body-file ./reply.en.txt --user-language en --current-language en --dry-run --output json
276
+ ```
277
+
278
+ If you intentionally draft in French and provide a translated version, pass the translated fields:
279
+
280
+ ```bash
281
+ gskills-admin feedback send-reply <feedbackId> --subject "GSkills - Réponse" --body-file ./reply.fr.txt --translated-subject "GSkills - Reply" --translated-body-file ./reply.en.txt --user-language en --current-language fr --dry-run --output json
282
+ ```
283
+
284
+ The claim commands below are not the normal feedback reply system. They are only for the SLA "ticket pris en charge" flow.
264
285
 
265
286
  ```bash
266
287
  gskills-admin feedback claim <feedbackId> --dry-run --output json
@@ -271,10 +292,36 @@ gskills-admin feedback send-claim <feedbackId> --recipient-email user@example.co
271
292
 
272
293
  Rules:
273
294
 
295
+ - For normal feedback responses, use `send-reply`.
296
+ - For multi-line email bodies, use `--body-file` and `--translated-body-file`; avoid inline shell strings for real sends.
274
297
  - Dry-run claim first to inspect recipient, CC recipients and draft.
275
298
  - Send only after the ticket is claimed by the same CLI user.
276
299
  - CC recipients must be allowed by instance SLA flags.
277
- - All claim and email sends are admin-logged with CLI metadata.
300
+ - All feedback email sends are admin-logged with CLI metadata.
301
+
302
+ ## Guided Instance Creation
303
+
304
+ Never use raw `instances create` as a blind Prisma row insert. The CLI `instances create` command is wired to the same guided creation path as `/fr/super-admin/instances/create`.
305
+
306
+ ```bash
307
+ gskills-admin instances create-plan --output json
308
+ gskills-admin instances create --data '{"name":"Client","URL":"client","licenceType":"STARTER","tokensAllowed":50}' --dry-run --output json
309
+ gskills-admin instances create --data '{"name":"Client","URL":"client","licenceType":"STARTER","tokensAllowed":50}' --yes --output json
310
+ ```
311
+
312
+ The guided path expects:
313
+
314
+ - identity: `name`, `URL`, `projectData.clientType`, `RunningState`
315
+ - licence: `licenceType`, `tokensAllowed`
316
+ - languages: `languageCodes`, `mainLanguage`
317
+ - features: `aiEnabled`
318
+ - access: `InstanceAddStyle`, plus `domainGranular`, `accountGranular`, or `groupGranular`
319
+ - contacts: `clientContacts`, each created or attached as `COMMANDITARY` with an unlimited pass
320
+ - launch: `launchChecklist.syncFromGlobal`
321
+
322
+ Default values match the UI where possible: active instance, IA enabled, `fr,en`, main language `fr`, client type `NUMERICOACH_LICENSE`, global sync enabled.
323
+
324
+ Use dry-run to inspect the full plan and warnings. The real run creates the instance, connects languages, creates the `quiz-retake` flag, project data, client commanditary accounts, unlimited access passes, optional global sync, deploy-cache invalidation, and admin log.
278
325
 
279
326
  ## Accesses
280
327
 
@@ -0,0 +1,164 @@
1
+ ---
2
+ name: gskills-instance-creation
3
+ description: Use when an agent must create a GSkills client instance or explain the guided super-admin instance creation flow.
4
+ ---
5
+
6
+ # Creation d'instance GSkills
7
+
8
+ Cette skill sert quand un agent doit creer une instance GSkills sans passer par l'UI.
9
+
10
+ Le principe est simple: la CLI doit suivre le chemin du formulaire `/fr/super-admin/instances/create`, pas creer une ligne `Instance` brute.
11
+
12
+ ## Comment l'UI fonctionne aujourd'hui
13
+
14
+ Le formulaire est un wizard en 9 etapes.
15
+
16
+ 1. Creer l'instance
17
+
18
+ - `name`: nom visible dans l'admin.
19
+ - `URL`: slug unique, utilise pour `https://<slug>.g-skills.fr/`.
20
+ - `projectData.clientType`: type commercial du client.
21
+ - `RunningState`: instance active ou fermee des la creation.
22
+
23
+ 2. Licence et sieges
24
+
25
+ - `licenceType`: `STARTER`, `PREMIUM`, ou `PRESTIGE`.
26
+ - `tokensAllowed`: nombre d'utilisateurs autorises.
27
+
28
+ 3. Langues
29
+
30
+ - `languageCodes`: langues actives.
31
+ - `mainLanguage`: langue principale.
32
+ - La langue principale doit etre dans les langues actives.
33
+ - Par defaut l'UI propose `fr` et `en`, avec `fr` en principal.
34
+
35
+ 4. Fonctionnalites
36
+
37
+ - `aiEnabled`: active ou desactive les fonctionnalites IA.
38
+ - Par defaut, l'IA est active.
39
+
40
+ 5. Acces a l'instance
41
+
42
+ Meme logique que Parametres > Acces.
43
+
44
+ - `ALL`: ouvert aux comptes autorises.
45
+ - `GRANULAR_DOMAIN`: necessite `domainGranular`.
46
+ - `GRANULAR_ACCOUNT`: necessite `accountGranular`.
47
+ - `GRANULAR_GOOGLE_GROUP`: les entites Google se terminent apres creation.
48
+ - `NONE`: aucun acces automatique, pass manuel uniquement.
49
+
50
+ 6. Contacts client
51
+
52
+ - `clientContacts`: emails, prenoms, noms, postes.
53
+ - Chaque contact devient `COMMANDITARY` sur l'instance.
54
+ - Chaque contact recoit un pass `UNLIMITED`.
55
+ - Le premier contact remplit les champs principaux de `InstanceProjectData`.
56
+ - Les suivants deviennent des `InstanceClientContact`.
57
+
58
+ 7. Synchroniser
59
+
60
+ - `launchChecklist.syncFromGlobal`.
61
+ - Si actif, le contenu global compatible avec les langues est copie.
62
+ - La synchro peut creer pages, categories, menus, quiz, parcours, connaissances, ressources, badges, exercices Chromebook et workflows.
63
+ - Le cache deploy est invalide apres la synchro.
64
+
65
+ 8. Valider
66
+
67
+ - Une seule action finale cree tout.
68
+ - L'UI loggue la creation avec un snapshot de l'instance et des contacts.
69
+
70
+ 9. Preparer la livraison
71
+
72
+ - L'UI prepare un email a copier dans Gmail.
73
+ - Cet email contient les liens d'acces, formulaire, notifications et prochaines etapes client.
74
+ - La CLI ne doit pas envoyer cet email automatiquement.
75
+
76
+ ## Comment le faire en CLI
77
+
78
+ Toujours commencer par le plan.
79
+
80
+ ```bash
81
+ gskills-admin instances create-plan --output json
82
+ ```
83
+
84
+ Ensuite preparer un payload JSON.
85
+
86
+ Payload minimal:
87
+
88
+ ```json
89
+ {
90
+ "name": "Client Exemple",
91
+ "URL": "client-exemple",
92
+ "licenceType": "STARTER",
93
+ "tokensAllowed": 50
94
+ }
95
+ ```
96
+
97
+ Payload complet courant:
98
+
99
+ ```json
100
+ {
101
+ "name": "Client Exemple",
102
+ "URL": "client-exemple",
103
+ "licenceType": "STARTER",
104
+ "tokensAllowed": 50,
105
+ "RunningState": true,
106
+ "aiEnabled": true,
107
+ "languageCodes": ["fr", "en"],
108
+ "mainLanguage": "fr",
109
+ "InstanceAddStyle": "GRANULAR_DOMAIN",
110
+ "domainGranular": ["client.com"],
111
+ "clientContacts": [
112
+ {
113
+ "email": "admin@client.com",
114
+ "firstName": "Marie",
115
+ "lastName": "Dupont",
116
+ "jobTitle": "Responsable formation"
117
+ }
118
+ ],
119
+ "projectData": {
120
+ "clientType": "NUMERICOACH_LICENSE"
121
+ },
122
+ "launchChecklist": {
123
+ "syncFromGlobal": true,
124
+ "prepareDeliveryEmail": true,
125
+ "requestWhitelist": true,
126
+ "requestOnboardingForm": true,
127
+ "requestUserImport": true,
128
+ "notes": ""
129
+ }
130
+ }
131
+ ```
132
+
133
+ Faire un dry-run.
134
+
135
+ ```bash
136
+ gskills-admin instances create --data '{"name":"Client Exemple","URL":"client-exemple","licenceType":"STARTER","tokensAllowed":50}' --dry-run --output json
137
+ ```
138
+
139
+ Verifier:
140
+
141
+ - slug disponible.
142
+ - langues attendues.
143
+ - mode d'acces coherent.
144
+ - contacts client corrects.
145
+ - synchro globale voulue ou non.
146
+ - warnings vides ou compris.
147
+
148
+ Puis creer.
149
+
150
+ ```bash
151
+ gskills-admin instances create --data '{"name":"Client Exemple","URL":"client-exemple","licenceType":"STARTER","tokensAllowed":50}' --yes --output json
152
+ ```
153
+
154
+ ## Regles agents
155
+
156
+ - Ne jamais utiliser un CRUD brut Prisma pour creer une instance.
157
+ - Ne jamais supposer le mode d'acces si le client a fourni domaines, emails ou groupes.
158
+ - Si `InstanceAddStyle = GRANULAR_DOMAIN`, il faut au moins un domaine.
159
+ - Si `InstanceAddStyle = GRANULAR_ACCOUNT`, il faut au moins un email.
160
+ - Pour `GRANULAR_GOOGLE_GROUP`, creer l'instance puis configurer les entites avec la CLI `entities`.
161
+ - Toujours faire `--dry-run` avant `--yes`.
162
+ - Apres creation, aller verifier les parametres et preparer l'email de livraison.
163
+ - Si la synchro initiale remonte un warning, ne pas l'ignorer. Lire les logs de sync avant de dire que tout est pret.
164
+