@numericoach/gskills-admin-cli 0.1.15 → 0.1.17

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
@@ -51,8 +51,13 @@ Use the listed `cache.scopes` with `gskills-admin cache invalidate` after create
51
51
 
52
52
  AI translation is available for content that has native AI translation in the editor:
53
53
 
54
+ Warning: `translate pages` rewrites each translated page from the source page. It is not a diff update. Recreating translated pages this way can lose activity-specific fields, quiz ids, embedded ids, or future custom block data if the translator does not preserve them. Prefer the app diff update flow for pages with activities or custom blocks.
55
+
56
+ For pages with activities or custom blocks, prefer `--mode patch`. It uses the source page history to update changed text while preserving non-text target block data:
57
+
54
58
  ```bash
55
59
  gskills-admin translate pages <pageId> --to en,es --dry-run --output json
60
+ gskills-admin translate pages <pageId> --from fr --to en,es --mode patch --dry-run --output json
56
61
  gskills-admin translate pages --ids <pageId,pageId> --from fr --to en --dry-run --output json
57
62
  gskills-admin translate pages --all --instance global --from fr --to en --take 100 --dry-run --output json
58
63
  gskills-admin translate quizzes <quizId> --to en --yes --output json
@@ -69,6 +74,8 @@ gskills-admin access grant --user <userId> --type DEFAULT --dry-run --output jso
69
74
  gskills-admin instances create-plan --output json
70
75
  gskills-admin instances create --data '{"name":"Client","URL":"client","licenceType":"STARTER","tokensAllowed":50}' --dry-run --output json
71
76
  gskills-admin entities list --instance <instanceId> --output json
77
+ gskills-admin entities sync-google-groups --instance <instanceId> --dry-run --output json
78
+ gskills-admin entities sync-google-groups --instance <instanceId> --yes --output json
72
79
  gskills-admin entities set-page-visibility --instance <instanceId> --page <pageId> --entity-ids google-group:team@example.com --dry-run --output json
73
80
  gskills-admin org-units-sync google --instance <instanceId> --yes --output json
74
81
  gskills-admin ambassadors label --instance <instanceId> --language fr --output json
@@ -1108,6 +1108,9 @@ var runEntitiesCommand = async (action, entityId, ctx) => {
1108
1108
  return requestApi(`/api/cli/entities/access-summary?${entitySearchParams(ctx).toString()}`);
1109
1109
  }
1110
1110
  if (action === "sync-google-groups") {
1111
+ if (!hasFlag(ctx, "yes") && !hasFlag(ctx, "dry-run")) {
1112
+ throw new CliError("Google group sync writes the stored group catalog. Add --yes or use --dry-run.", 2);
1113
+ }
1111
1114
  return requestApi("/api/cli/entities/sync-google-groups", {
1112
1115
  method: "POST",
1113
1116
  body: JSON.stringify({
@@ -1291,7 +1294,8 @@ var runTranslateCommand = async (kind, id, ctx) => {
1291
1294
  if (!hasFlag(ctx, "yes") && !hasFlag(ctx, "dry-run")) {
1292
1295
  throw new CliError("AI translation writes content. Add --yes or use --dry-run.", 2);
1293
1296
  }
1294
- return requestApi(`/api/cli/translate/${kind}`, {
1297
+ const mode = getStringFlag(ctx, "mode") ?? "upsert";
1298
+ const result = await requestApi(`/api/cli/translate/${kind}`, {
1295
1299
  method: "POST",
1296
1300
  body: JSON.stringify({
1297
1301
  id,
@@ -1302,10 +1306,12 @@ var runTranslateCommand = async (kind, id, ctx) => {
1302
1306
  take: getNumberFlag(ctx, "take"),
1303
1307
  targetLanguages,
1304
1308
  sourceLanguage: getStringFlag(ctx, "from") ?? getStringFlag(ctx, "source-language"),
1305
- mode: getStringFlag(ctx, "mode") ?? "upsert",
1309
+ sourceHistoryEntryId: getStringFlag(ctx, "source-history") ?? getStringFlag(ctx, "source-history-entry"),
1310
+ mode,
1306
1311
  dryRun: hasFlag(ctx, "dry-run")
1307
1312
  })
1308
1313
  });
1314
+ return addTranslatePagesWarning(kind, mode, result);
1309
1315
  };
1310
1316
  var syncLogs = (ctx) => {
1311
1317
  const searchParams = new URLSearchParams;
@@ -1580,7 +1586,7 @@ var schemaHelp = () => ({
1580
1586
  { name: "sync presets", writes: false },
1581
1587
  { name: "cache scopes", writes: false },
1582
1588
  { name: "cache invalidate", required: ["--instance"], flags: ["--scope", "--languages", "--yes", "--dry-run"], writes: true },
1583
- { name: "translate", args: ["kind", "id?"], required: ["--to"], flags: ["--ids", "--all", "--instance", "--from", "--where", "--take", "--mode", "--yes", "--dry-run"], writes: true },
1589
+ { name: "translate", args: ["kind", "id?"], required: ["--to"], flags: ["--ids", "--all", "--instance", "--from", "--where", "--take", "--mode", "--source-history", "--yes", "--dry-run"], writes: true },
1584
1590
  { name: "feedback claim", args: ["feedbackId"], flags: ["--dry-run"], writes: true },
1585
1591
  { name: "feedback send-claim", args: ["feedbackId"], flags: ["--recipient-email", "--recipient-name", "--cc", "--subject", "--body", "--yes", "--dry-run"], writes: true },
1586
1592
  { name: "feedback send-reply", args: ["feedbackId"], flags: ["--subject", "--subject-file", "--body-file", "--translated-subject", "--translated-subject-file", "--translated-body-file", "--user-language", "--current-language", "--yes", "--dry-run"], writes: true },
@@ -1591,7 +1597,7 @@ var schemaHelp = () => ({
1591
1597
  { name: "entities list", required: ["--instance"], flags: ["--language"], writes: false },
1592
1598
  { name: "entities detail", args: ["entityId"], required: ["--instance"], flags: ["--language"], writes: false },
1593
1599
  { name: "entities access-summary", required: ["--instance"], writes: false },
1594
- { name: "entities sync-google-groups", required: ["--instance"], flags: ["--dry-run"], writes: false },
1600
+ { name: "entities sync-google-groups", required: ["--instance"], flags: ["--yes", "--dry-run"], writes: true },
1595
1601
  { name: "entities save-access-rules", required: ["--instance", "--entity-ids"], flags: ["--yes", "--dry-run"], writes: true },
1596
1602
  { name: "entities set-restrictions", args: ["entityId"], required: ["--instance"], flags: ["--category-ids", "--learning-path-ids", "--alpha-program-ids", "--alpha-all-programs", "--yes", "--dry-run"], writes: true },
1597
1603
  { name: "entities set-page-visibility", required: ["--instance", "--page"], flags: ["--entity-ids", "--yes", "--dry-run"], writes: true },
@@ -1687,10 +1693,25 @@ var translateHelp = () => ({
1687
1693
  "learning-paths",
1688
1694
  "chromebook-exercises"
1689
1695
  ],
1690
- modes: ["upsert", "create", "update"],
1696
+ modes: ["upsert", "create", "update", "patch"],
1691
1697
  selection: "Pass one id, --ids for several source rows, or --all with optional --instance, --from, --where and --take.",
1698
+ warning: PAGE_TRANSLATION_REWRITE_WARNING,
1699
+ patchMode: "For pages, --mode patch uses source page history to update changed translatable text while preserving target non-text block data such as activity ids, quiz ids, embedded ids, files, and future custom fields. It updates existing translations only and fails when no previous source history exists.",
1692
1700
  note: "Uses the same AI translation helpers as the editors. Dry-run plans the write without calling AI."
1693
1701
  });
1702
+ var PAGE_TRANSLATION_REWRITE_WARNING = "WARNING: translate pages is a full translated-page rewrite, not a diff update. Rebuilding target pages can lose activity-specific fields, quiz ids, embedded ids, or future custom block data if the translator does not preserve them. Prefer the app diff update flow for pages with activities or custom blocks.";
1703
+ var addTranslatePagesWarning = (kind, mode, result) => {
1704
+ if (kind !== "pages" && kind !== "page")
1705
+ return result;
1706
+ if (mode !== "update" && mode !== "upsert")
1707
+ return result;
1708
+ if (!result || typeof result !== "object" || Array.isArray(result))
1709
+ return result;
1710
+ return {
1711
+ ...result,
1712
+ warning: PAGE_TRANSLATION_REWRITE_WARNING
1713
+ };
1714
+ };
1694
1715
  var feedbackHelp = () => ({
1695
1716
  usage: [
1696
1717
  "gskills-admin feedback send-reply <feedbackId> --subject 'GSkills - ...' --body-file ./reply.fr.txt --dry-run",
@@ -1743,6 +1764,8 @@ var entitiesHelp = () => ({
1743
1764
  "gskills-admin entities list --instance <instanceId>",
1744
1765
  "gskills-admin entities detail <entityId> --instance <instanceId>",
1745
1766
  "gskills-admin entities access-summary --instance <instanceId>",
1767
+ "gskills-admin entities sync-google-groups --instance <instanceId> --dry-run",
1768
+ "gskills-admin entities sync-google-groups --instance <instanceId> --yes",
1746
1769
  "gskills-admin entities save-access-rules --instance <instanceId> --entity-ids manual-group:<id>,org-unit:<id> --dry-run",
1747
1770
  "gskills-admin entities set-restrictions <entityId> --instance <instanceId> --category-ids <id,id> --learning-path-ids <id,id> --yes",
1748
1771
  "gskills-admin entities set-page-visibility --instance <instanceId> --page <pageId> --entity-ids google-group:team@example.com --yes"
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@numericoach/gskills-admin-cli",
3
- "version": "0.1.15",
3
+ "version": "0.1.17",
4
4
  "private": false,
5
5
  "type": "module",
6
6
  "description": "Admin-only CLI for GSkills super-admin operations.",
@@ -166,6 +166,7 @@ Selection can be one source row, several source rows, or all matching rows:
166
166
 
167
167
  ```bash
168
168
  gskills-admin translate pages <pageId> --to en,es --dry-run --output json
169
+ gskills-admin translate pages <pageId> --from fr --to en,es --mode patch --dry-run --output json
169
170
  gskills-admin translate pages --ids <pageId,pageId> --from fr --to en --dry-run --output json
170
171
  gskills-admin translate pages --all --instance global --from fr --to en --take 100 --dry-run --output json
171
172
  gskills-admin translate quizzes <quizId> --to en --yes --output json
@@ -174,8 +175,24 @@ gskills-admin translate knowledge-video <knowledgeId> --from en --to es --yes --
174
175
 
175
176
  Always dry-run first. Dry-run lists planned rows and target languages without calling AI or writing data. Real runs require `--yes`.
176
177
 
178
+ Warning for pages: `translate pages` rewrites each translated page from the source page. It is not a diff update. Recreating translated pages this way can lose activity-specific fields, quiz ids, embedded ids, or future custom block data if the translator does not preserve them. Prefer the app diff update flow for pages with activities or custom blocks.
179
+
180
+ For pages with activities or custom blocks, prefer `--mode patch`. It uses the source page history to update changed translatable text while preserving target non-text block data such as activity ids, quiz ids, embedded ids, files, and future custom fields. It updates existing translations only and fails when no previous source history exists.
181
+
177
182
  For quizzes, the CLI mirrors the quiz thematic through `categoryId` across translations.
178
183
 
184
+ Everything translated by the CLI and stored in the DB works as a family. A page is still one page, even when the DB stores one row per language. Do not tell a non-technical user that one page became 40 pages, unless they explicitly ask for DB-level detail.
185
+
186
+ When a translated thing has relations, translate or relink those relations too. A translated page, quiz, badge, resource, knowledge item, menu entry, or learning path should not quietly point back to the French-only relation when a same-language relation exists.
187
+
188
+ For learning paths, a complete translation includes the parcours itself, its groups, its items, same-language page, quiz, resource, and knowledge references when available, the awarded badge family, and each translated parcours linked to the badge in the same language. This exact trap has happened: the parcours translated correctly but every translated parcours still pointed to the French badge.
189
+
190
+ When explaining CLI work to the user, use `gskills-vocabulary`. Speak like a GSkills admin or end user, not like a database. Use words like page, quiz, parcours, badge, menu, resource, and knowledge base. Do not lead with ids, row counts, parent ids, or schema terms unless the user asks for them.
191
+
192
+ Users could do most of these content tasks in the GSkills UI. The reason they ask Codex is speed. Keep the answer simple: what changed, what stays hidden or visible, and what was verified.
193
+
194
+ After translating content, query the DB or CLI output to prove there are no missing languages, no unexpected active content, no missing related content, and no language mismatch between connected things.
195
+
179
196
  For internal knowledge videos, use `knowledge-video`. It queues the same native video localization workflow as the editor, so it creates a localization job instead of copying the original media.
180
197
 
181
198
  After visible content translation, read the cache hint in the response and invalidate the narrow scope before checking the deploy UI.
@@ -409,7 +426,8 @@ Entities are the shared segmentation layer for manual groups, Google groups, and
409
426
  gskills-admin entities list --instance <instanceId> --language fr --output json
410
427
  gskills-admin entities detail manual-group:<groupId> --instance <instanceId> --language fr --output json
411
428
  gskills-admin entities access-summary --instance <instanceId> --output json
412
- gskills-admin entities sync-google-groups --instance <instanceId> --output json
429
+ gskills-admin entities sync-google-groups --instance <instanceId> --dry-run --output json
430
+ gskills-admin entities sync-google-groups --instance <instanceId> --yes --output json
413
431
  gskills-admin org-units-sync google --instance <instanceId> --dry-run --output json
414
432
  gskills-admin org-units-sync google --instance <instanceId> --yes --output json
415
433
  ```
@@ -36,6 +36,7 @@ Known context:
36
36
 
37
37
  - Customer id used during Google Admin checks: `C028v0b9g`.
38
38
  - Known Google Chat space: `Air Liquide x Numericoach - GSkills`, `spaces/AAQAc2CT1qI`.
39
+ - Recurring task-tracking Sheet from Audrey: `NC AIR LIQUIDE GSKILLS GDP`, `https://docs.google.com/spreadsheets/d/1qhbvCEae5-3MIDENxEcp708vt_gK8lpRdkSHYEXHSog/edit?gid=0#gid=0`. Use it when the user asks about Air Liquide task ownership or GDP follow-up. Prefer moving actionable work into the app or ClickUp when possible; Google Workspace tracking is tolerated here because the client uses it, not because it is the desired operating model.
39
40
  - Harold OUSSET was a known user whose display name required surname-first parsing.
40
41
  - Air Liquide syncs should usually start with `sync logs`, then `sync diff`, then a narrow or preset run.
41
42