@numericoach/gskills-admin-cli 0.1.11 → 0.1.13

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
@@ -17,7 +17,7 @@ bun run gskills-admin sync run --target <instanceId> --only pages,quizzes --yes
17
17
  ```
18
18
 
19
19
  Content-like resources default to `instanceId = "global"` when `--instance` is omitted.
20
- Deletes require both `--force` and an exact `--confirm-delete <resource>:<id>` token.
20
+ Delete commands are soft-only. They disable or deactivate rows when the resource supports it, and refuse resources that cannot be safely disabled.
21
21
  CLI writes are logged in the GSkills admin logs with the authenticated user and CLI metadata.
22
22
 
23
23
  Sync dry-runs use the shared GSkills diff preview system:
@@ -45,7 +45,19 @@ gskills-admin pages help --output json
45
45
  gskills-admin topics help --output json
46
46
  ```
47
47
 
48
- Use the listed `cache.scopes` with `gskills-admin cache invalidate` after create, update, or delete when the end-user view must reflect the change immediately.
48
+ Use the listed `cache.scopes` with `gskills-admin cache invalidate` after create, update, or soft-delete when the end-user view must reflect the change immediately.
49
+
50
+ AI translation is available for content that has native AI translation in the editor:
51
+
52
+ ```bash
53
+ gskills-admin translate pages <pageId> --to en,es --dry-run --output json
54
+ gskills-admin translate pages --ids <pageId,pageId> --from fr --to en --dry-run --output json
55
+ gskills-admin translate pages --all --instance global --from fr --to en --take 100 --dry-run --output json
56
+ gskills-admin translate quizzes <quizId> --to en --yes --output json
57
+ gskills-admin translate knowledge-video <knowledgeId> --from en --to es --yes --output json
58
+ ```
59
+
60
+ Supported kinds are `pages`, `quizzes`, `topics`, `badges`, `menus`, `menu-sections`, `internal-knowledge`, `knowledge-video`, `learning-paths`, and `chromebook-exercises`.
49
61
 
50
62
  Operational helpers are available for the admin-only flows agents should not improvise:
51
63
 
@@ -776,6 +776,8 @@ var runCommand = async (ctx) => {
776
776
  return runSyncCommand(actionOrResource, ctx);
777
777
  if (group === "cache")
778
778
  return runCacheCommand(actionOrResource, ctx);
779
+ if (group === "translate")
780
+ return runTranslateCommand(actionOrResource, maybeAction, ctx);
779
781
  if (group === "feedback")
780
782
  return runFeedbackCommand(actionOrResource, maybeAction, ctx);
781
783
  if (group === "access")
@@ -900,21 +902,45 @@ var updateResource = async (resource, id, ctx) => {
900
902
  body: JSON.stringify({ data })
901
903
  });
902
904
  };
905
+ var getSoftDeleteData = (resource) => {
906
+ if (resource.defaultFields.includes("disabled"))
907
+ return { disabled: true };
908
+ if (resource.defaultFields.includes("archived"))
909
+ return { archived: true };
910
+ if (resource.defaultFields.includes("isActive"))
911
+ return { isActive: false };
912
+ if (resource.defaultFields.includes("active"))
913
+ return { active: false };
914
+ return null;
915
+ };
903
916
  var deleteResource = async (resource, id, ctx) => {
904
917
  const expectedConfirmation = `${resource.name}:${id}`;
918
+ const data = getSoftDeleteData(resource);
919
+ if (!data) {
920
+ throw new CliError("CLI delete is disabled for this resource because it cannot be safely disabled.", 2, {
921
+ id,
922
+ resource: resource.name,
923
+ warning: "The CLI never permanently deletes production data.",
924
+ suggestion: `Use gskills-admin ${resource.name} update <id> --data '{...}' only if you know the safe inactive field.`
925
+ });
926
+ }
905
927
  if (!hasFlag(ctx, "force")) {
906
- throw new CliError("Delete requires --force", 2, {
928
+ throw new CliError("Soft delete requires --force", 2, {
907
929
  id,
908
930
  resource: resource.name,
909
- warning: "This permanently deletes production data.",
931
+ action: "soft-delete",
932
+ data,
933
+ warning: "The CLI never permanently deletes production data.",
910
934
  requiredConfirmation: expectedConfirmation
911
935
  });
912
936
  }
913
937
  if (getStringFlag(ctx, "confirm-delete") !== expectedConfirmation) {
914
- throw new CliError(`Delete requires --confirm-delete ${expectedConfirmation}`, 2, {
938
+ throw new CliError(`Soft delete requires --confirm-delete ${expectedConfirmation}`, 2, {
915
939
  id,
916
940
  resource: resource.name,
917
- warning: "This permanently deletes production data.",
941
+ action: "soft-delete",
942
+ data,
943
+ warning: "The CLI never permanently deletes production data.",
918
944
  requiredConfirmation: expectedConfirmation,
919
945
  usage: `gskills-admin ${resource.name} delete ${id} --force --confirm-delete ${expectedConfirmation}`
920
946
  });
@@ -924,16 +950,15 @@ var deleteResource = async (resource, id, ctx) => {
924
950
  dryRun: true,
925
951
  resource: resource.name,
926
952
  id,
927
- action: "delete",
953
+ action: "soft-delete",
928
954
  confirmed: true,
929
- warning: "This permanently deletes production data."
955
+ data,
956
+ warning: "The CLI never permanently deletes production data."
930
957
  };
931
958
  }
932
959
  return requestApi(`/api/cli/${resource.name}/${id}`, {
933
- method: "DELETE",
934
- body: JSON.stringify({
935
- confirmation: expectedConfirmation
936
- })
960
+ method: "PATCH",
961
+ body: JSON.stringify({ data })
937
962
  });
938
963
  };
939
964
  var runFeedbackCommand = async (action, feedbackId, ctx) => {
@@ -1237,6 +1262,37 @@ var runCacheCommand = async (action, ctx) => {
1237
1262
  body: JSON.stringify(payload)
1238
1263
  });
1239
1264
  };
1265
+ var runTranslateCommand = async (kind, id, ctx) => {
1266
+ if (!kind || kind === "help")
1267
+ return translateHelp();
1268
+ const ids = splitCsv(getStringFlag(ctx, "ids"));
1269
+ const all = hasFlag(ctx, "all");
1270
+ if (!id && ids.length === 0 && !all)
1271
+ throw new CliError("Missing source content id, --ids, or --all", 2);
1272
+ if (all && (id || ids.length > 0))
1273
+ throw new CliError("Use either an id/--ids or --all, not both", 2);
1274
+ const targetLanguages = splitCsv(getStringFlag(ctx, "to") ?? getStringFlag(ctx, "languages"));
1275
+ if (targetLanguages.length === 0)
1276
+ throw new CliError("Missing --to", 2);
1277
+ if (!hasFlag(ctx, "yes") && !hasFlag(ctx, "dry-run")) {
1278
+ throw new CliError("AI translation writes content. Add --yes or use --dry-run.", 2);
1279
+ }
1280
+ return requestApi(`/api/cli/translate/${kind}`, {
1281
+ method: "POST",
1282
+ body: JSON.stringify({
1283
+ id,
1284
+ ids,
1285
+ all,
1286
+ where: parseJsonObject(getStringFlag(ctx, "where"), "--where"),
1287
+ instanceId: getStringFlag(ctx, "instance"),
1288
+ take: getNumberFlag(ctx, "take"),
1289
+ targetLanguages,
1290
+ sourceLanguage: getStringFlag(ctx, "from") ?? getStringFlag(ctx, "source-language"),
1291
+ mode: getStringFlag(ctx, "mode") ?? "upsert",
1292
+ dryRun: hasFlag(ctx, "dry-run")
1293
+ })
1294
+ });
1295
+ };
1240
1296
  var syncLogs = (ctx) => {
1241
1297
  const searchParams = new URLSearchParams;
1242
1298
  const targetInstanceId = getStringFlag(ctx, "target") ?? getStringFlag(ctx, "instance");
@@ -1476,7 +1532,9 @@ var rootHelp = () => ({
1476
1532
  "gskills-admin auth whoami",
1477
1533
  "gskills-admin pages list",
1478
1534
  `gskills-admin pages update <id> --data '{"disabled":true}'`,
1479
- "gskills-admin sync run --target <instanceId> --only pages,quizzes --yes"
1535
+ "gskills-admin pages delete <id> --force --confirm-delete pages:<id> # soft-disables only",
1536
+ "gskills-admin sync run --target <instanceId> --only pages,quizzes --yes",
1537
+ "gskills-admin translate pages <id> --to en,es --dry-run"
1480
1538
  ],
1481
1539
  resources: resources.map((resource) => resource.name),
1482
1540
  output: "Use --output json, --output jsonl, --output table, or --output markdown. Piped output defaults to JSON.",
@@ -1508,6 +1566,7 @@ var schemaHelp = () => ({
1508
1566
  { name: "sync presets", writes: false },
1509
1567
  { name: "cache scopes", writes: false },
1510
1568
  { name: "cache invalidate", required: ["--instance"], flags: ["--scope", "--languages", "--yes", "--dry-run"], writes: true },
1569
+ { name: "translate", args: ["kind", "id?"], required: ["--to"], flags: ["--ids", "--all", "--instance", "--from", "--where", "--take", "--mode", "--yes", "--dry-run"], writes: true },
1511
1570
  { name: "feedback claim", args: ["feedbackId"], flags: ["--dry-run"], writes: true },
1512
1571
  { name: "feedback send-claim", args: ["feedbackId"], flags: ["--recipient-email", "--recipient-name", "--cc", "--subject", "--body", "--yes", "--dry-run"], writes: true },
1513
1572
  { 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 },
@@ -1529,7 +1588,7 @@ var schemaHelp = () => ({
1529
1588
  { name: `${resource.name} get`, args: ["id"], writes: false },
1530
1589
  { name: `${resource.name} create`, flags: ["--data", "--instance", "--dry-run"], writes: true },
1531
1590
  { name: `${resource.name} update`, args: ["id"], flags: ["--data", "--dry-run"], writes: true },
1532
- { name: `${resource.name} delete`, args: ["id"], flags: ["--force", "--confirm-delete", "--dry-run"], writes: true, destructive: true }
1591
+ { name: `${resource.name} delete`, args: ["id"], flags: ["--force", "--confirm-delete", "--dry-run"], writes: true, destructive: false, softOnly: true }
1533
1592
  ])
1534
1593
  ],
1535
1594
  resources: resources.map((resource) => ({
@@ -1538,7 +1597,7 @@ var schemaHelp = () => ({
1538
1597
  defaultFields: resource.defaultFields,
1539
1598
  syncable: Boolean(resource.syncable),
1540
1599
  cacheScopes: resource.cacheScopes ?? [],
1541
- cacheNote: resource.cacheScopes?.length ? "After create/update/delete, visible deploy content may stay stale until these cache scopes are invalidated." : "No deploy-cache scope is listed for this raw resource. Still verify visible product state after writes."
1600
+ cacheNote: resource.cacheScopes?.length ? "After create/update/soft-delete, visible deploy content may stay stale until these cache scopes are invalidated." : "No deploy-cache scope is listed for this raw resource. Still verify visible product state after writes."
1542
1601
  }))
1543
1602
  });
1544
1603
  var authHelp = () => ({
@@ -1587,6 +1646,37 @@ var cacheHelp = () => ({
1587
1646
  scopes: ["all", "pages", "pages-knowledge", "menu-bundle", "applications"],
1588
1647
  note: "Uses the same deploy-cache version bump system as the super-admin content settings screen."
1589
1648
  });
1649
+ var translateHelp = () => ({
1650
+ usage: [
1651
+ "gskills-admin translate pages <pageId> --to en,es --dry-run",
1652
+ "gskills-admin translate pages --ids <pageId,pageId> --to en --dry-run",
1653
+ "gskills-admin translate pages --all --instance global --from fr --to en --take 100 --dry-run",
1654
+ "gskills-admin translate quizzes <quizId> --to en --yes",
1655
+ "gskills-admin translate topics <topicId> --to en --yes",
1656
+ "gskills-admin translate badges <badgeId> --to en --yes",
1657
+ "gskills-admin translate menus <menuItemId> --to en --yes",
1658
+ "gskills-admin translate menu-sections <menuSectionId> --to en --yes",
1659
+ "gskills-admin translate internal-knowledge <knowledgeId> --to en --yes",
1660
+ "gskills-admin translate knowledge-video <knowledgeId> --from en --to es --yes",
1661
+ "gskills-admin translate learning-paths <pathId> --to en --yes",
1662
+ "gskills-admin translate chromebook-exercises <exerciseId> --to en --yes"
1663
+ ],
1664
+ contentKinds: [
1665
+ "pages",
1666
+ "quizzes",
1667
+ "topics",
1668
+ "badges",
1669
+ "menus",
1670
+ "menu-sections",
1671
+ "internal-knowledge",
1672
+ "knowledge-video",
1673
+ "learning-paths",
1674
+ "chromebook-exercises"
1675
+ ],
1676
+ modes: ["upsert", "create", "update"],
1677
+ selection: "Pass one id, --ids for several source rows, or --all with optional --instance, --from, --where and --take.",
1678
+ note: "Uses the same AI translation helpers as the editors. Dry-run plans the write without calling AI."
1679
+ });
1590
1680
  var feedbackHelp = () => ({
1591
1681
  usage: [
1592
1682
  "gskills-admin feedback send-reply <feedbackId> --subject 'GSkills - ...' --body-file ./reply.fr.txt --dry-run",
@@ -1667,9 +1757,9 @@ var resourceHelp = (resource) => ({
1667
1757
  cache: {
1668
1758
  scopes: resource.cacheScopes ?? [],
1669
1759
  invalidate: resource.cacheScopes?.length ? `gskills-admin cache invalidate --instance <instanceId> --scope ${resource.cacheScopes[0]} --dry-run` : null,
1670
- note: resource.cacheScopes?.length ? "After create/update/delete, deploy views may still show cached content. Dry-run and invalidate the relevant scope, then verify the visible page." : "No deploy-cache scope is listed for this raw resource. If the write affects visible content indirectly, use cache scopes to choose a broader invalidation."
1760
+ note: resource.cacheScopes?.length ? "After create/update/soft-delete, deploy views may still show cached content. Dry-run and invalidate the relevant scope, then verify the visible page." : "No deploy-cache scope is listed for this raw resource. If the write affects visible content indirectly, use cache scopes to choose a broader invalidation."
1671
1761
  },
1672
- deleteWarning: "Delete permanently removes production data and requires an exact --confirm-delete token."
1762
+ deleteWarning: "Delete is soft-only in the CLI. It writes disabled, archived, isActive=false, or active=false when the resource supports it."
1673
1763
  });
1674
1764
 
1675
1765
  // ../../src/cli/gskills-admin.ts
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@numericoach/gskills-admin-cli",
3
- "version": "0.1.11",
3
+ "version": "0.1.13",
4
4
  "private": false,
5
5
  "type": "module",
6
6
  "description": "Admin-only CLI for GSkills super-admin operations.",
@@ -67,16 +67,16 @@ gskills-admin cache invalidate --instance <instanceId> --scope pages --dry-run -
67
67
  gskills-admin cache invalidate --instance <instanceId> --scope pages --yes --output json
68
68
  ```
69
69
 
70
- CRUD help exposes `cache.scopes` for resources that are known to feed deploy caches. After create, update, or delete, the database can be correct while the end-user view is still stale. Use the narrowest listed scope first. Use `all` only when the changed setting affects many deploy surfaces or when the narrow scope did not clear the visible stale state.
70
+ CRUD help exposes `cache.scopes` for resources that are known to feed deploy caches. After create, update, or soft-delete, the database can be correct while the end-user view is still stale. Use the narrowest listed scope first. Use `all` only when the changed setting affects many deploy surfaces or when the narrow scope did not clear the visible stale state.
71
71
 
72
- Deletes are stricter than other writes. They require both `--force` and an exact confirmation token.
72
+ Delete commands are soft-only. They require both `--force` and an exact confirmation token, then write the safest inactive field available, such as `disabled: true`, `archived: true`, `isActive: false`, or `active: false`. If a resource cannot be safely disabled, the CLI refuses the delete command.
73
73
 
74
74
  ```bash
75
75
  gskills-admin pages delete <id> --force --confirm-delete pages:<id> --dry-run --output json
76
76
  gskills-admin pages delete <id> --force --confirm-delete pages:<id> --output json
77
77
  ```
78
78
 
79
- Never add `--confirm-delete` unless the user explicitly asked for a permanent deletion and the target row was read first.
79
+ Never add `--confirm-delete` unless the user explicitly asked to remove something from visibility and the target row was read first. The CLI must not permanently delete production data.
80
80
 
81
81
  CLI create, update, and delete operations are written to the GSkills admin logs with the authenticated user, entity snapshots, and CLI metadata. When Codex runs the CLI, the log metadata includes `actorType = "cli"` and `agent = "codex"`.
82
82
 
@@ -145,6 +145,41 @@ gskills-admin pages create --data @page.json --output json
145
145
 
146
146
  If the CLI version does not support `@file` JSON yet, inline compact JSON or use a small repo script that calls the authenticated API. Do not switch to raw DB access for convenience.
147
147
 
148
+ ## AI Translation
149
+
150
+ Use `translate` when content already has AI translation in its editor and the same operation is needed from the CLI.
151
+
152
+ Supported content kinds:
153
+
154
+ - `pages`
155
+ - `quizzes`
156
+ - `topics`
157
+ - `badges`
158
+ - `menus`
159
+ - `menu-sections`
160
+ - `internal-knowledge`
161
+ - `knowledge-video`
162
+ - `learning-paths`
163
+ - `chromebook-exercises`
164
+
165
+ Selection can be one source row, several source rows, or all matching rows:
166
+
167
+ ```bash
168
+ gskills-admin translate pages <pageId> --to en,es --dry-run --output json
169
+ gskills-admin translate pages --ids <pageId,pageId> --from fr --to en --dry-run --output json
170
+ gskills-admin translate pages --all --instance global --from fr --to en --take 100 --dry-run --output json
171
+ gskills-admin translate quizzes <quizId> --to en --yes --output json
172
+ gskills-admin translate knowledge-video <knowledgeId> --from en --to es --yes --output json
173
+ ```
174
+
175
+ Always dry-run first. Dry-run lists planned rows and target languages without calling AI or writing data. Real runs require `--yes`.
176
+
177
+ For quizzes, the CLI mirrors the quiz thematic through `categoryId` across translations.
178
+
179
+ 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
+
181
+ After visible content translation, read the cache hint in the response and invalidate the narrow scope before checking the deploy UI.
182
+
148
183
  ## Sync
149
184
 
150
185
  Global is the source by default.
@@ -484,8 +519,8 @@ Prefer the narrowest scope:
484
519
  ## Safety
485
520
 
486
521
  - Prefer `list` and `get` before writes
487
- - Use `--dry-run` before create, update, delete, and sync
488
- - Use `--force --confirm-delete <resource>:<id>` only for deletes the user explicitly requested
522
+ - Use `--dry-run` before create, update, soft-delete, and sync
523
+ - Use `--force --confirm-delete <resource>:<id>` only for soft-deletes the user explicitly requested
489
524
  - Use `sync diff` before `sync run --yes`
490
525
  - Use cache `--dry-run` before cache `--yes`
491
526
  - Re-read changed rows after writes