@numericoach/gskills-admin-cli 0.1.3 → 0.1.4

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 "Bonjour..." --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
@@ -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,51 @@ 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 = getStringFlag(ctx, "subject");
911
+ const body = getStringFlag(ctx, "body");
912
+ if (!subject || !body)
913
+ throw new CliError("Missing --subject or --body", 2);
914
+ return requestApi("/api/cli/feedback/send-reply", {
915
+ method: "POST",
916
+ body: JSON.stringify({
917
+ feedbackId,
918
+ subject,
919
+ body,
920
+ translatedSubject: getStringFlag(ctx, "translated-subject"),
921
+ translatedBody: getStringFlag(ctx, "translated-body"),
922
+ userLanguage: getStringFlag(ctx, "user-language"),
923
+ currentLanguage: getStringFlag(ctx, "current-language") ?? "fr",
924
+ dryRun: hasFlag(ctx, "dry-run")
925
+ })
926
+ });
927
+ }
901
928
  throw new CliError(`Unknown feedback command "${action}"`, 2);
902
929
  };
930
+ var runInstanceCreationCommand = async (action, ctx) => {
931
+ if (!action || action === "help" || action === "create-plan")
932
+ return instanceCreateHelp();
933
+ if (action !== "create")
934
+ throw new CliError(`Unknown instances command "${action}"`, 2);
935
+ const data = parseJsonObject(getStringFlag(ctx, "data"), "--data");
936
+ if (Object.keys(data).length === 0)
937
+ throw new CliError("Missing --data JSON", 2);
938
+ if (!hasFlag(ctx, "yes") && !hasFlag(ctx, "dry-run")) {
939
+ throw new CliError("Guided instance creation writes production data. Add --yes or use --dry-run.", 2);
940
+ }
941
+ return requestApi("/api/cli/instances/create", {
942
+ method: "POST",
943
+ body: JSON.stringify({
944
+ data,
945
+ dryRun: hasFlag(ctx, "dry-run")
946
+ })
947
+ });
948
+ };
903
949
  var runAccessCommand = async (action, ctx) => {
904
950
  if (!action || action === "help")
905
951
  return accessHelp();
@@ -1359,8 +1405,11 @@ var schemaHelp = () => ({
1359
1405
  { name: "cache invalidate", required: ["--instance"], flags: ["--scope", "--languages", "--yes", "--dry-run"], writes: true },
1360
1406
  { name: "feedback claim", args: ["feedbackId"], flags: ["--dry-run"], writes: true },
1361
1407
  { name: "feedback send-claim", args: ["feedbackId"], flags: ["--recipient-email", "--recipient-name", "--cc", "--subject", "--body", "--yes", "--dry-run"], writes: true },
1408
+ { name: "feedback send-reply", args: ["feedbackId"], flags: ["--subject", "--body", "--translated-subject", "--translated-body", "--user-language", "--current-language", "--yes", "--dry-run"], writes: true },
1362
1409
  { name: "access grant", required: ["--user"], flags: ["--type", "--start-at", "--custom-duration-days", "--preferred-language", "--yes", "--dry-run"], writes: true },
1363
1410
  { name: "access revoke-active", required: ["--user"], flags: ["--yes", "--dry-run"], writes: true },
1411
+ { name: "instances create-plan", writes: false },
1412
+ { name: "instances create", flags: ["--data", "--yes", "--dry-run"], writes: true },
1364
1413
  { name: "entities list", required: ["--instance"], flags: ["--language"], writes: false },
1365
1414
  { name: "entities detail", args: ["entityId"], required: ["--instance"], flags: ["--language"], writes: false },
1366
1415
  { name: "entities access-summary", required: ["--instance"], writes: false },
@@ -1430,11 +1479,42 @@ var cacheHelp = () => ({
1430
1479
  });
1431
1480
  var feedbackHelp = () => ({
1432
1481
  usage: [
1482
+ "gskills-admin feedback send-reply <feedbackId> --subject 'GSkills - ...' --body 'Bonjour...' --dry-run",
1483
+ "gskills-admin feedback send-reply <feedbackId> --subject 'GSkills - ...' --body 'Bonjour...' --yes",
1433
1484
  "gskills-admin feedback claim <feedbackId> --dry-run",
1434
1485
  "gskills-admin feedback claim <feedbackId>",
1435
1486
  "gskills-admin feedback send-claim <feedbackId> --recipient-email user@example.com --subject '...' --body '...' --yes"
1436
1487
  ],
1437
- note: "Claiming and sending emails use the same SLA recipient rules as the admin feedback UI and log through admin logs."
1488
+ note: "send-reply is the normal feedback detail email template flow. claim/send-claim is only the SLA ticket-taken-in-charge flow."
1489
+ });
1490
+ var instanceCreateHelp = () => ({
1491
+ usage: [
1492
+ "gskills-admin instances create-plan --output json",
1493
+ `gskills-admin instances create --data '{"name":"Client","URL":"client","licenceType":"STARTER","tokensAllowed":50}' --dry-run --output json`,
1494
+ "gskills-admin instances create --data '{...}' --yes --output json"
1495
+ ],
1496
+ path: [
1497
+ "1. Créer l'instance: name, URL, clientType, RunningState",
1498
+ "2. Licence et sièges: licenceType, tokensAllowed",
1499
+ "3. Langues: languageCodes, mainLanguage",
1500
+ "4. Fonctionnalités: aiEnabled",
1501
+ "5. Accès: InstanceAddStyle with domainGranular, accountGranular or later entity rules",
1502
+ "6. Contacts client: clientContacts, each becomes COMMANDITARY with unlimited pass",
1503
+ "7. Synchroniser: launchChecklist.syncFromGlobal",
1504
+ "8. Valider: one final production write",
1505
+ "9. Préparer la livraison: use the generated delivery email outside the CLI"
1506
+ ],
1507
+ requiredData: ["name", "URL", "licenceType", "tokensAllowed"],
1508
+ defaults: {
1509
+ RunningState: true,
1510
+ aiEnabled: true,
1511
+ languageCodes: ["fr", "en"],
1512
+ mainLanguage: "fr",
1513
+ InstanceAddStyle: "ALL unless granular values are provided",
1514
+ clientType: "NUMERICOACH_LICENSE",
1515
+ syncFromGlobal: true
1516
+ },
1517
+ warning: "This uses the guided creation workflow. Raw Prisma instance creation is intentionally not the default CLI path."
1438
1518
  });
1439
1519
  var accessHelp = () => ({
1440
1520
  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.4",
4
4
  "private": false,
5
5
  "type": "module",
6
6
  "description": "Admin-only CLI for GSkills super-admin operations.",
@@ -258,9 +258,22 @@ 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 "Bonjour..." --dry-run --output json
267
+ gskills-admin feedback send-reply <feedbackId> --subject "GSkills - ..." --body "Bonjour..." --yes --output json
268
+ ```
269
+
270
+ If the user language differs from French, pass the edited translated fields generated or reviewed by the agent:
271
+
272
+ ```bash
273
+ gskills-admin feedback send-reply <feedbackId> --subject "GSkills - ..." --body "Bonjour..." --translated-subject "GSkills - ..." --translated-body "Hello..." --user-language en --current-language fr --dry-run --output json
274
+ ```
275
+
276
+ The claim commands below are not the normal feedback reply system. They are only for the SLA "ticket pris en charge" flow.
264
277
 
265
278
  ```bash
266
279
  gskills-admin feedback claim <feedbackId> --dry-run --output json
@@ -271,10 +284,35 @@ gskills-admin feedback send-claim <feedbackId> --recipient-email user@example.co
271
284
 
272
285
  Rules:
273
286
 
287
+ - For normal feedback responses, use `send-reply`.
274
288
  - Dry-run claim first to inspect recipient, CC recipients and draft.
275
289
  - Send only after the ticket is claimed by the same CLI user.
276
290
  - CC recipients must be allowed by instance SLA flags.
277
- - All claim and email sends are admin-logged with CLI metadata.
291
+ - All feedback email sends are admin-logged with CLI metadata.
292
+
293
+ ## Guided Instance Creation
294
+
295
+ 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`.
296
+
297
+ ```bash
298
+ gskills-admin instances create-plan --output json
299
+ gskills-admin instances create --data '{"name":"Client","URL":"client","licenceType":"STARTER","tokensAllowed":50}' --dry-run --output json
300
+ gskills-admin instances create --data '{"name":"Client","URL":"client","licenceType":"STARTER","tokensAllowed":50}' --yes --output json
301
+ ```
302
+
303
+ The guided path expects:
304
+
305
+ - identity: `name`, `URL`, `projectData.clientType`, `RunningState`
306
+ - licence: `licenceType`, `tokensAllowed`
307
+ - languages: `languageCodes`, `mainLanguage`
308
+ - features: `aiEnabled`
309
+ - access: `InstanceAddStyle`, plus `domainGranular`, `accountGranular`, or `groupGranular`
310
+ - contacts: `clientContacts`, each created or attached as `COMMANDITARY` with an unlimited pass
311
+ - launch: `launchChecklist.syncFromGlobal`
312
+
313
+ Default values match the UI where possible: active instance, IA enabled, `fr,en`, main language `fr`, client type `NUMERICOACH_LICENSE`, global sync enabled.
314
+
315
+ 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
316
 
279
317
  ## Accesses
280
318
 
@@ -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
+