@numericoach/gskills-admin-cli 0.1.16 → 0.1.18
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
|
|
@@ -60,12 +65,19 @@ gskills-admin translate knowledge-video <knowledgeId> --from en --to es --yes --
|
|
|
60
65
|
```
|
|
61
66
|
|
|
62
67
|
Supported kinds are `pages`, `quizzes`, `topics`, `badges`, `menus`, `menu-sections`, `internal-knowledge`, `knowledge-video`, `learning-paths`, and `chromebook-exercises`.
|
|
68
|
+
Target languages must be explicit. `--to all` is rejected.
|
|
63
69
|
|
|
64
70
|
Operational helpers are available for the admin-only flows agents should not improvise:
|
|
65
71
|
|
|
66
72
|
```bash
|
|
73
|
+
gskills-admin feedback inspect <feedbackId> --output json
|
|
74
|
+
gskills-admin feedback translation-status <feedbackId> --output json
|
|
67
75
|
gskills-admin feedback send-reply <feedbackId> --subject "GSkills - ..." --body-file ./reply.txt --dry-run --output json
|
|
76
|
+
gskills-admin access diagnose --email user@example.com --instance <instanceId> --output json
|
|
68
77
|
gskills-admin access grant --user <userId> --type DEFAULT --dry-run --output json
|
|
78
|
+
gskills-admin internal-knowledge sync-media --source global --since today --languages fr --all-targets --dry-run --output json
|
|
79
|
+
gskills-admin admin-ingest repair-state --instance <instanceId> --output json
|
|
80
|
+
gskills-admin admin-ingest repair --instance <instanceId> --dry-run --output json
|
|
69
81
|
gskills-admin instances create-plan --output json
|
|
70
82
|
gskills-admin instances create --data '{"name":"Client","URL":"client","licenceType":"STARTER","tokensAllowed":50}' --dry-run --output json
|
|
71
83
|
gskills-admin entities list --instance <instanceId> --output json
|
|
@@ -78,6 +90,8 @@ gskills-admin ambassadors label --instance <instanceId> --language fr --output j
|
|
|
78
90
|
|
|
79
91
|
Feedback reply bodies are file-based on purpose. Production replies are multi-line, and `send-reply` rejects inline body text to avoid shell parsing surprises.
|
|
80
92
|
|
|
93
|
+
`internal-knowledge sync-media` changes only selected media fields on existing target copies matched by `sourceKnowledgeId`. The default field is `url`, and it invalidates `pages-knowledge` cache for touched instances.
|
|
94
|
+
|
|
81
95
|
Raw project and analytics data can be read or adjusted through resources such as `project-data`, `ticket-sla-rules`, `learning-path-items`, `learning-path-groups`, `quiz-questions`, `quiz-options`, `analytics`, `quiz-attempts`, `user-paths`, `chromebook-progress`, `user-badges`, `user-learning-paths`, and `user-learning-path-item-completions`.
|
|
82
96
|
|
|
83
97
|
## Agent skill
|
package/dist/gskills-admin.js
CHANGED
|
@@ -782,6 +782,8 @@ var runCommand = async (ctx) => {
|
|
|
782
782
|
return runFeedbackCommand(actionOrResource, maybeAction, ctx);
|
|
783
783
|
if (group === "access")
|
|
784
784
|
return runAccessCommand(actionOrResource, ctx);
|
|
785
|
+
if (group === "admin-ingest")
|
|
786
|
+
return runAdminIngestCommand(actionOrResource, ctx);
|
|
785
787
|
if (group === "entities")
|
|
786
788
|
return runEntitiesCommand(actionOrResource, maybeAction, ctx);
|
|
787
789
|
if (group === "org-units-sync")
|
|
@@ -828,6 +830,9 @@ var runAuthCommand = async (action, ctx) => {
|
|
|
828
830
|
var runResourceCommand = async (resource, action, maybeId, _rest, ctx) => {
|
|
829
831
|
if (!action || action === "help")
|
|
830
832
|
return resourceHelp(resource);
|
|
833
|
+
if (resource.name === "internal-knowledge" && action === "sync-media") {
|
|
834
|
+
return runKnowledgeSyncMediaCommand(ctx);
|
|
835
|
+
}
|
|
831
836
|
if (action === "list")
|
|
832
837
|
return listResource(resource, ctx);
|
|
833
838
|
if (action === "get") {
|
|
@@ -964,9 +969,17 @@ var deleteResource = async (resource, id, ctx) => {
|
|
|
964
969
|
var runFeedbackCommand = async (action, feedbackId, ctx) => {
|
|
965
970
|
if (!action || action === "help")
|
|
966
971
|
return feedbackHelp();
|
|
972
|
+
if ((action === "inspect" || action === "translation-status") && !feedbackId) {
|
|
973
|
+
throw new CliError("Missing feedback id or URL", 2);
|
|
974
|
+
}
|
|
967
975
|
if ((action === "claim" || action === "send-claim") && !feedbackId) {
|
|
968
976
|
throw new CliError("Missing feedback id", 2);
|
|
969
977
|
}
|
|
978
|
+
if (action === "inspect" || action === "translation-status") {
|
|
979
|
+
const searchParams = new URLSearchParams;
|
|
980
|
+
searchParams.set("ref", feedbackId);
|
|
981
|
+
return requestApi(`/api/cli/feedback/${action}?${searchParams.toString()}`);
|
|
982
|
+
}
|
|
970
983
|
if (action === "claim") {
|
|
971
984
|
return requestApi("/api/cli/feedback/claim", {
|
|
972
985
|
method: "POST",
|
|
@@ -1051,6 +1064,21 @@ var runInstanceCreationCommand = async (action, ctx) => {
|
|
|
1051
1064
|
var runAccessCommand = async (action, ctx) => {
|
|
1052
1065
|
if (!action || action === "help")
|
|
1053
1066
|
return accessHelp();
|
|
1067
|
+
if (action === "diagnose") {
|
|
1068
|
+
const userId = getStringFlag(ctx, "user");
|
|
1069
|
+
const email = getStringFlag(ctx, "email");
|
|
1070
|
+
if (!userId && !email)
|
|
1071
|
+
throw new CliError("Missing --user or --email", 2);
|
|
1072
|
+
const searchParams = new URLSearchParams;
|
|
1073
|
+
if (userId)
|
|
1074
|
+
searchParams.set("userId", userId);
|
|
1075
|
+
if (email)
|
|
1076
|
+
searchParams.set("email", email);
|
|
1077
|
+
const instance = getStringFlag(ctx, "instance");
|
|
1078
|
+
if (instance)
|
|
1079
|
+
searchParams.set("instance", instance);
|
|
1080
|
+
return requestApi(`/api/cli/access/diagnose?${searchParams.toString()}`);
|
|
1081
|
+
}
|
|
1054
1082
|
if (action === "grant") {
|
|
1055
1083
|
const userId = getStringFlag(ctx, "user");
|
|
1056
1084
|
if (!userId)
|
|
@@ -1087,6 +1115,62 @@ var runAccessCommand = async (action, ctx) => {
|
|
|
1087
1115
|
}
|
|
1088
1116
|
throw new CliError(`Unknown access command "${action}"`, 2);
|
|
1089
1117
|
};
|
|
1118
|
+
var runAdminIngestCommand = async (action, ctx) => {
|
|
1119
|
+
if (!action || action === "help")
|
|
1120
|
+
return adminIngestHelp();
|
|
1121
|
+
if (action === "repair-state") {
|
|
1122
|
+
const instanceId = getStringFlag(ctx, "instance");
|
|
1123
|
+
if (!instanceId)
|
|
1124
|
+
throw new CliError("Missing --instance", 2);
|
|
1125
|
+
return requestApi(`/api/cli/admin-ingest/repair-state?instanceId=${encodeURIComponent(instanceId)}`);
|
|
1126
|
+
}
|
|
1127
|
+
if (action === "repair") {
|
|
1128
|
+
const instanceId = getStringFlag(ctx, "instance");
|
|
1129
|
+
if (!instanceId)
|
|
1130
|
+
throw new CliError("Missing --instance", 2);
|
|
1131
|
+
if (hasFlag(ctx, "dry-run")) {
|
|
1132
|
+
return requestApi(`/api/cli/admin-ingest/repair-state?instanceId=${encodeURIComponent(instanceId)}`);
|
|
1133
|
+
}
|
|
1134
|
+
if (!hasFlag(ctx, "yes")) {
|
|
1135
|
+
throw new CliError("Admin ingest repair queues production workflows. Add --yes or use --dry-run.", 2);
|
|
1136
|
+
}
|
|
1137
|
+
return requestApi("/api/cli/admin-ingest/repair", {
|
|
1138
|
+
method: "POST",
|
|
1139
|
+
body: JSON.stringify({ instanceId })
|
|
1140
|
+
});
|
|
1141
|
+
}
|
|
1142
|
+
throw new CliError(`Unknown admin-ingest command "${action}"`, 2);
|
|
1143
|
+
};
|
|
1144
|
+
var runKnowledgeSyncMediaCommand = async (ctx) => {
|
|
1145
|
+
const targetInstanceIds = getTargetInstanceIds(ctx);
|
|
1146
|
+
const allTargets = hasFlag(ctx, "all-targets");
|
|
1147
|
+
if (targetInstanceIds.length === 0 && !allTargets) {
|
|
1148
|
+
throw new CliError("Missing --target, --targets, or --all-targets", 2);
|
|
1149
|
+
}
|
|
1150
|
+
if (targetInstanceIds.length > 0 && allTargets) {
|
|
1151
|
+
throw new CliError("Use either --target/--targets or --all-targets, not both", 2);
|
|
1152
|
+
}
|
|
1153
|
+
if (!hasFlag(ctx, "yes") && !hasFlag(ctx, "dry-run")) {
|
|
1154
|
+
throw new CliError("Knowledge media sync writes production data. Add --yes or use --dry-run.", 2);
|
|
1155
|
+
}
|
|
1156
|
+
return requestApi("/api/cli/internal-knowledge/sync-media", {
|
|
1157
|
+
method: "POST",
|
|
1158
|
+
body: JSON.stringify({
|
|
1159
|
+
sourceInstanceId: getStringFlag(ctx, "source") ?? "global",
|
|
1160
|
+
targetInstanceIds,
|
|
1161
|
+
allTargets,
|
|
1162
|
+
languages: splitCsv(getStringFlag(ctx, "languages")),
|
|
1163
|
+
since: getStringFlag(ctx, "since") ?? getStringFlag(ctx, "updated-after") ?? "today",
|
|
1164
|
+
fields: splitCsv(getStringFlag(ctx, "fields")).length > 0 ? splitCsv(getStringFlag(ctx, "fields")) : ["url"],
|
|
1165
|
+
mime: getStringFlag(ctx, "mime") ?? "video",
|
|
1166
|
+
sourceType: getStringFlag(ctx, "source-type") ?? "UPLOAD",
|
|
1167
|
+
includeDisabled: hasFlag(ctx, "include-disabled"),
|
|
1168
|
+
includeArchived: hasFlag(ctx, "include-archived"),
|
|
1169
|
+
skipCache: hasFlag(ctx, "no-cache"),
|
|
1170
|
+
dryRun: hasFlag(ctx, "dry-run")
|
|
1171
|
+
})
|
|
1172
|
+
});
|
|
1173
|
+
};
|
|
1090
1174
|
var runEntitiesCommand = async (action, entityId, ctx) => {
|
|
1091
1175
|
if (!action || action === "help")
|
|
1092
1176
|
return entitiesHelp();
|
|
@@ -1291,10 +1375,14 @@ var runTranslateCommand = async (kind, id, ctx) => {
|
|
|
1291
1375
|
const targetLanguages = splitCsv(getStringFlag(ctx, "to") ?? getStringFlag(ctx, "languages"));
|
|
1292
1376
|
if (targetLanguages.length === 0)
|
|
1293
1377
|
throw new CliError("Missing --to", 2);
|
|
1378
|
+
if (targetLanguages.some((language) => language.toLowerCase() === "all")) {
|
|
1379
|
+
throw new CliError("Do not use --to all. Pass explicit target languages like --to en,es,pt-BR.", 2);
|
|
1380
|
+
}
|
|
1294
1381
|
if (!hasFlag(ctx, "yes") && !hasFlag(ctx, "dry-run")) {
|
|
1295
1382
|
throw new CliError("AI translation writes content. Add --yes or use --dry-run.", 2);
|
|
1296
1383
|
}
|
|
1297
|
-
|
|
1384
|
+
const mode = getStringFlag(ctx, "mode") ?? "upsert";
|
|
1385
|
+
const result = await requestApi(`/api/cli/translate/${kind}`, {
|
|
1298
1386
|
method: "POST",
|
|
1299
1387
|
body: JSON.stringify({
|
|
1300
1388
|
id,
|
|
@@ -1305,10 +1393,12 @@ var runTranslateCommand = async (kind, id, ctx) => {
|
|
|
1305
1393
|
take: getNumberFlag(ctx, "take"),
|
|
1306
1394
|
targetLanguages,
|
|
1307
1395
|
sourceLanguage: getStringFlag(ctx, "from") ?? getStringFlag(ctx, "source-language"),
|
|
1308
|
-
|
|
1396
|
+
sourceHistoryEntryId: getStringFlag(ctx, "source-history") ?? getStringFlag(ctx, "source-history-entry"),
|
|
1397
|
+
mode,
|
|
1309
1398
|
dryRun: hasFlag(ctx, "dry-run")
|
|
1310
1399
|
})
|
|
1311
1400
|
});
|
|
1401
|
+
return addTranslatePagesWarning(kind, mode, result);
|
|
1312
1402
|
};
|
|
1313
1403
|
var syncLogs = (ctx) => {
|
|
1314
1404
|
const searchParams = new URLSearchParams;
|
|
@@ -1551,7 +1641,8 @@ var rootHelp = () => ({
|
|
|
1551
1641
|
`gskills-admin pages update <id> --data '{"disabled":true}'`,
|
|
1552
1642
|
"gskills-admin pages delete <id> --force --confirm-delete pages:<id> # soft-disables only",
|
|
1553
1643
|
"gskills-admin sync run --target <instanceId> --only pages,quizzes --yes",
|
|
1554
|
-
"gskills-admin translate pages <id> --to en,es --dry-run"
|
|
1644
|
+
"gskills-admin translate pages <id> --to en,es --dry-run",
|
|
1645
|
+
"gskills-admin internal-knowledge sync-media --since today --languages fr --all-targets --dry-run"
|
|
1555
1646
|
],
|
|
1556
1647
|
resources: resources.map((resource) => resource.name),
|
|
1557
1648
|
output: "Use --output json, --output jsonl, --output table, or --output markdown. Piped output defaults to JSON.",
|
|
@@ -1583,12 +1674,18 @@ var schemaHelp = () => ({
|
|
|
1583
1674
|
{ name: "sync presets", writes: false },
|
|
1584
1675
|
{ name: "cache scopes", writes: false },
|
|
1585
1676
|
{ name: "cache invalidate", required: ["--instance"], flags: ["--scope", "--languages", "--yes", "--dry-run"], writes: true },
|
|
1586
|
-
{ name: "translate", args: ["kind", "id?"], required: ["--to"], flags: ["--ids", "--all", "--instance", "--from", "--where", "--take", "--mode", "--yes", "--dry-run"], writes: true },
|
|
1677
|
+
{ name: "translate", args: ["kind", "id?"], required: ["--to"], flags: ["--ids", "--all", "--instance", "--from", "--where", "--take", "--mode", "--source-history", "--yes", "--dry-run"], writes: true },
|
|
1678
|
+
{ name: "internal-knowledge sync-media", flags: ["--source", "--target", "--targets", "--all-targets", "--languages", "--since", "--updated-after", "--fields", "--mime", "--source-type", "--include-disabled", "--include-archived", "--no-cache", "--yes", "--dry-run"], writes: true },
|
|
1679
|
+
{ name: "feedback inspect", args: ["feedbackId or URL"], writes: false },
|
|
1680
|
+
{ name: "feedback translation-status", args: ["feedbackId or URL"], writes: false },
|
|
1587
1681
|
{ name: "feedback claim", args: ["feedbackId"], flags: ["--dry-run"], writes: true },
|
|
1588
1682
|
{ name: "feedback send-claim", args: ["feedbackId"], flags: ["--recipient-email", "--recipient-name", "--cc", "--subject", "--body", "--yes", "--dry-run"], writes: true },
|
|
1589
1683
|
{ 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 },
|
|
1684
|
+
{ name: "access diagnose", required: ["--user or --email"], flags: ["--instance"], writes: false },
|
|
1590
1685
|
{ name: "access grant", required: ["--user"], flags: ["--type", "--start-at", "--custom-duration-days", "--preferred-language", "--yes", "--dry-run"], writes: true },
|
|
1591
1686
|
{ name: "access revoke-active", required: ["--user"], flags: ["--yes", "--dry-run"], writes: true },
|
|
1687
|
+
{ name: "admin-ingest repair-state", required: ["--instance"], writes: false },
|
|
1688
|
+
{ name: "admin-ingest repair", required: ["--instance"], flags: ["--yes", "--dry-run"], writes: true },
|
|
1592
1689
|
{ name: "instances create-plan", writes: false },
|
|
1593
1690
|
{ name: "instances create", flags: ["--data", "--yes", "--dry-run"], writes: true },
|
|
1594
1691
|
{ name: "entities list", required: ["--instance"], flags: ["--language"], writes: false },
|
|
@@ -1690,12 +1787,30 @@ var translateHelp = () => ({
|
|
|
1690
1787
|
"learning-paths",
|
|
1691
1788
|
"chromebook-exercises"
|
|
1692
1789
|
],
|
|
1693
|
-
modes: ["upsert", "create", "update"],
|
|
1790
|
+
modes: ["upsert", "create", "update", "patch"],
|
|
1694
1791
|
selection: "Pass one id, --ids for several source rows, or --all with optional --instance, --from, --where and --take.",
|
|
1695
|
-
|
|
1792
|
+
warning: PAGE_TRANSLATION_REWRITE_WARNING,
|
|
1793
|
+
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.",
|
|
1794
|
+
note: "Uses the same AI translation helpers as the editors. Dry-run plans the write without calling AI. Pass explicit target languages. --to all is intentionally rejected."
|
|
1696
1795
|
});
|
|
1796
|
+
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.";
|
|
1797
|
+
var addTranslatePagesWarning = (kind, mode, result) => {
|
|
1798
|
+
if (kind !== "pages" && kind !== "page")
|
|
1799
|
+
return result;
|
|
1800
|
+
if (mode !== "update" && mode !== "upsert")
|
|
1801
|
+
return result;
|
|
1802
|
+
if (!result || typeof result !== "object" || Array.isArray(result))
|
|
1803
|
+
return result;
|
|
1804
|
+
return {
|
|
1805
|
+
...result,
|
|
1806
|
+
warning: PAGE_TRANSLATION_REWRITE_WARNING
|
|
1807
|
+
};
|
|
1808
|
+
};
|
|
1697
1809
|
var feedbackHelp = () => ({
|
|
1698
1810
|
usage: [
|
|
1811
|
+
"gskills-admin feedback inspect <feedbackId>",
|
|
1812
|
+
"gskills-admin feedback inspect 'https://client.g-skills.fr/fr/...'",
|
|
1813
|
+
"gskills-admin feedback translation-status <feedbackId>",
|
|
1699
1814
|
"gskills-admin feedback send-reply <feedbackId> --subject 'GSkills - ...' --body-file ./reply.fr.txt --dry-run",
|
|
1700
1815
|
"gskills-admin feedback send-reply <feedbackId> --subject 'GSkills - ...' --body-file ./reply.fr.txt --yes",
|
|
1701
1816
|
"gskills-admin feedback claim <feedbackId> --dry-run",
|
|
@@ -1704,6 +1819,14 @@ var feedbackHelp = () => ({
|
|
|
1704
1819
|
],
|
|
1705
1820
|
note: "send-reply is the normal feedback detail email template flow. claim/send-claim is only the SLA ticket-taken-in-charge flow."
|
|
1706
1821
|
});
|
|
1822
|
+
var adminIngestHelp = () => ({
|
|
1823
|
+
usage: [
|
|
1824
|
+
"gskills-admin admin-ingest repair-state --instance <instanceId>",
|
|
1825
|
+
"gskills-admin admin-ingest repair --instance <instanceId> --dry-run",
|
|
1826
|
+
"gskills-admin admin-ingest repair --instance <instanceId> --yes"
|
|
1827
|
+
],
|
|
1828
|
+
note: "repair-state reads the same historical repair planner as the admin-console data UI. repair queues the existing repair catchup workflow."
|
|
1829
|
+
});
|
|
1707
1830
|
var instanceCreateHelp = () => ({
|
|
1708
1831
|
usage: [
|
|
1709
1832
|
"gskills-admin instances create-plan --output json",
|
|
@@ -1735,6 +1858,8 @@ var instanceCreateHelp = () => ({
|
|
|
1735
1858
|
});
|
|
1736
1859
|
var accessHelp = () => ({
|
|
1737
1860
|
usage: [
|
|
1861
|
+
"gskills-admin access diagnose --email user@example.com --instance <instanceId>",
|
|
1862
|
+
"gskills-admin access diagnose --user <userId>",
|
|
1738
1863
|
"gskills-admin access grant --user <userId> --type DEFAULT --dry-run",
|
|
1739
1864
|
"gskills-admin access grant --user <userId> --type PASS_90_DAYS --preferred-language fr --yes",
|
|
1740
1865
|
"gskills-admin access revoke-active --user <userId> --yes"
|
|
@@ -1770,7 +1895,8 @@ var resourceHelp = (resource) => ({
|
|
|
1770
1895
|
`gskills-admin ${resource.name} get <id>`,
|
|
1771
1896
|
`gskills-admin ${resource.name} create --data '{"instanceId":"global"}'`,
|
|
1772
1897
|
`gskills-admin ${resource.name} update <id> --data '{"disabled":true}'`,
|
|
1773
|
-
`gskills-admin ${resource.name} delete <id> --force --confirm-delete ${resource.name}:<id
|
|
1898
|
+
`gskills-admin ${resource.name} delete <id> --force --confirm-delete ${resource.name}:<id>`,
|
|
1899
|
+
...resource.name === "internal-knowledge" ? [`gskills-admin ${resource.name} sync-media --since today --languages fr --all-targets --dry-run`] : []
|
|
1774
1900
|
],
|
|
1775
1901
|
defaultFields: resource.defaultFields,
|
|
1776
1902
|
cache: {
|
package/package.json
CHANGED
|
@@ -80,6 +80,20 @@ Never add `--confirm-delete` unless the user explicitly asked to remove somethin
|
|
|
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
|
|
|
83
|
+
## CLI Plus Code Rule
|
|
84
|
+
|
|
85
|
+
Most agents do not have Theo's direct production DB access. Treat the CLI as the production access layer.
|
|
86
|
+
|
|
87
|
+
Good pattern:
|
|
88
|
+
|
|
89
|
+
1. Use `gskills-admin schema`, resource reads, and specialized commands first.
|
|
90
|
+
2. If the operation needs custom logic, inspect the app code and add or use an authenticated CLI API route.
|
|
91
|
+
3. Keep the write path behind `--dry-run` and `--yes`.
|
|
92
|
+
4. Log admin-visible writes and invalidate deploy cache when the data affects visible content.
|
|
93
|
+
5. Publish the CLI and bundled skills when a recurring DB-only workaround becomes a normal operation.
|
|
94
|
+
|
|
95
|
+
Do not ask an agent for `DATABASE_URL` and do not write a one-off direct DB script when the same job will happen again. Code is still useful, but it should live behind the CLI or a reusable app helper.
|
|
96
|
+
|
|
83
97
|
## Instance Rules
|
|
84
98
|
|
|
85
99
|
If `--instance` is omitted, content-like resources default to `instanceId = "global"`.
|
|
@@ -166,6 +180,7 @@ Selection can be one source row, several source rows, or all matching rows:
|
|
|
166
180
|
|
|
167
181
|
```bash
|
|
168
182
|
gskills-admin translate pages <pageId> --to en,es --dry-run --output json
|
|
183
|
+
gskills-admin translate pages <pageId> --from fr --to en,es --mode patch --dry-run --output json
|
|
169
184
|
gskills-admin translate pages --ids <pageId,pageId> --from fr --to en --dry-run --output json
|
|
170
185
|
gskills-admin translate pages --all --instance global --from fr --to en --take 100 --dry-run --output json
|
|
171
186
|
gskills-admin translate quizzes <quizId> --to en --yes --output json
|
|
@@ -174,8 +189,26 @@ gskills-admin translate knowledge-video <knowledgeId> --from en --to es --yes --
|
|
|
174
189
|
|
|
175
190
|
Always dry-run first. Dry-run lists planned rows and target languages without calling AI or writing data. Real runs require `--yes`.
|
|
176
191
|
|
|
192
|
+
Never use `--to all`. The CLI rejects it because target languages must be explicit.
|
|
193
|
+
|
|
194
|
+
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.
|
|
195
|
+
|
|
196
|
+
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.
|
|
197
|
+
|
|
177
198
|
For quizzes, the CLI mirrors the quiz thematic through `categoryId` across translations.
|
|
178
199
|
|
|
200
|
+
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.
|
|
201
|
+
|
|
202
|
+
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.
|
|
203
|
+
|
|
204
|
+
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.
|
|
205
|
+
|
|
206
|
+
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.
|
|
207
|
+
|
|
208
|
+
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.
|
|
209
|
+
|
|
210
|
+
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.
|
|
211
|
+
|
|
179
212
|
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
213
|
|
|
181
214
|
After visible content translation, read the cache hint in the response and invalidate the narrow scope before checking the deploy UI.
|
|
@@ -215,6 +248,23 @@ Common presets:
|
|
|
215
248
|
- `pages-learning-paths`: refinement pass after broad syncs.
|
|
216
249
|
- `knowledge-resources-paths`: narrow asset and learning path rerun.
|
|
217
250
|
|
|
251
|
+
## Knowledge Media Sync
|
|
252
|
+
|
|
253
|
+
Use this when existing internal knowledge copies already exist on client instances and only the referenced media changed on global.
|
|
254
|
+
|
|
255
|
+
Default behavior changes only `url` on existing target copies matched by `sourceKnowledgeId`. It does not create knowledge rows and does not change activities, metadata, tags, categories, active state, parent links, or AI flags.
|
|
256
|
+
|
|
257
|
+
```bash
|
|
258
|
+
gskills-admin internal-knowledge sync-media --source global --since today --languages fr --all-targets --dry-run --output json
|
|
259
|
+
gskills-admin internal-knowledge sync-media --source global --since today --languages fr --all-targets --yes --output json
|
|
260
|
+
```
|
|
261
|
+
|
|
262
|
+
Use `--target <instanceId>` or `--targets <id,id>` instead of `--all-targets` for a smaller run.
|
|
263
|
+
|
|
264
|
+
Use `--fields url,updatedAt` only when the visible update date must mirror the source. The safer default is `url` only.
|
|
265
|
+
|
|
266
|
+
The command invalidates `pages-knowledge` for touched instances unless `--no-cache` is passed.
|
|
267
|
+
|
|
218
268
|
## Marina Sync Playbook
|
|
219
269
|
|
|
220
270
|
This section is based on prod admin logs and sync runs checked on 2026-05-13 for the period 2026-03-13 to 2026-05-13.
|
|
@@ -323,6 +373,16 @@ Typical mapping:
|
|
|
323
373
|
|
|
324
374
|
## Feedback Emails
|
|
325
375
|
|
|
376
|
+
Use `inspect` before investigating feedback through direct DB access. It returns the feedback row, user, instance, route metadata, analysis, assignees, recent replies and comments.
|
|
377
|
+
|
|
378
|
+
```bash
|
|
379
|
+
gskills-admin feedback inspect <feedbackId> --output json
|
|
380
|
+
gskills-admin feedback inspect 'https://client.g-skills.fr/fr/...' --output json
|
|
381
|
+
gskills-admin feedback translation-status <feedbackId> --output json
|
|
382
|
+
```
|
|
383
|
+
|
|
384
|
+
`translation-status` is useful when `translatedFr` exists but may simply be the original text after a translator fallback.
|
|
385
|
+
|
|
326
386
|
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.
|
|
327
387
|
|
|
328
388
|
Production reality from the latest 50 `FeedbackReply` rows checked on 2026-05-13: all reply bodies were multi-line, usually 9-13 lines with paragraph breaks. Translated PT/ES replies were multi-line too. Therefore, real feedback replies must use `--body-file`; never put the body inline in the shell.
|
|
@@ -390,6 +450,15 @@ Use dry-run to inspect the full plan and warnings. The real run creates the inst
|
|
|
390
450
|
|
|
391
451
|
## Accesses
|
|
392
452
|
|
|
453
|
+
Use `access diagnose` before granting, revoking, or asking for direct DB inspection.
|
|
454
|
+
|
|
455
|
+
```bash
|
|
456
|
+
gskills-admin access diagnose --email user@example.com --instance <instanceId> --output json
|
|
457
|
+
gskills-admin access diagnose --user <userId> --output json
|
|
458
|
+
```
|
|
459
|
+
|
|
460
|
+
It reports the user instance, active passes, upcoming passes, role bypass, automatic instance gate and Google group membership facts.
|
|
461
|
+
|
|
393
462
|
Use `access grant` and `access revoke-active` instead of raw `access-passes` writes when the operation should trigger workflows and admin logs.
|
|
394
463
|
|
|
395
464
|
```bash
|
|
@@ -401,6 +470,18 @@ gskills-admin access revoke-active --user <userId> --yes --output json
|
|
|
401
470
|
|
|
402
471
|
Types are `DEFAULT`, `PASS_90_DAYS`, `PASS_12_MONTHS`, `CUSTOM`, and `UNLIMITED`.
|
|
403
472
|
|
|
473
|
+
## Admin Ingest Repair
|
|
474
|
+
|
|
475
|
+
Use this when the UI says synchronisations incomplètes or admin console data has repair tasks.
|
|
476
|
+
|
|
477
|
+
```bash
|
|
478
|
+
gskills-admin admin-ingest repair-state --instance <instanceId> --output json
|
|
479
|
+
gskills-admin admin-ingest repair --instance <instanceId> --dry-run --output json
|
|
480
|
+
gskills-admin admin-ingest repair --instance <instanceId> --yes --output json
|
|
481
|
+
```
|
|
482
|
+
|
|
483
|
+
`repair-state` reads the same planner as the admin-console data UI. `repair --yes` queues the existing repair catchup workflow and writes an admin log. Do not run the old direct `bun --conditions react-server` repair snippet unless the CLI path is unavailable in the deployed version.
|
|
484
|
+
|
|
404
485
|
## Entities And Restrictions
|
|
405
486
|
|
|
406
487
|
Entities are the shared segmentation layer for manual groups, Google groups, and Google Admin OUs.
|
|
@@ -537,4 +618,4 @@ Prefer the narrowest scope:
|
|
|
537
618
|
- `--take 100` when inventory matters
|
|
538
619
|
- explicit `--fields` to avoid dumping huge content JSON
|
|
539
620
|
- explicit `--where` instead of fuzzy reasoning in prose
|
|
540
|
-
- no direct DB
|
|
621
|
+
- no direct DB for normal agents. If the CLI lacks the recurring operation, add the CLI route or reusable helper first
|
|
@@ -9,6 +9,8 @@ Use this for Codex-backed maintenance of GSkills content data.
|
|
|
9
9
|
|
|
10
10
|
This is not about UI visits. It is about proving and fixing content state with DB, sync logs, cache helpers, and production verification.
|
|
11
11
|
|
|
12
|
+
For normal agents, use `gskills-admin` as the production access layer. If the old fix required direct DB or a repo script, first check whether the CLI now exposes that operation.
|
|
13
|
+
|
|
12
14
|
## What Codex Has Actually Been Used For
|
|
13
15
|
|
|
14
16
|
- Investigating a Google Contacts page sync issue where source global content was published but client copies stayed disabled.
|
|
@@ -91,6 +93,24 @@ Known validated shape:
|
|
|
91
93
|
- Before: 49,338 mapped pages, 25,611 mismatches.
|
|
92
94
|
- After: 0 mismatches.
|
|
93
95
|
|
|
96
|
+
## Knowledge Media Reference Sync
|
|
97
|
+
|
|
98
|
+
Use this when global internal knowledge videos changed and client copies already exist.
|
|
99
|
+
|
|
100
|
+
```bash
|
|
101
|
+
gskills-admin internal-knowledge sync-media --source global --since today --languages fr --all-targets --dry-run --output json
|
|
102
|
+
gskills-admin internal-knowledge sync-media --source global --since today --languages fr --all-targets --yes --output json
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
Rules:
|
|
106
|
+
|
|
107
|
+
- default `--fields url` changes only the referenced media URL
|
|
108
|
+
- use `--fields url,updatedAt` only when the visible date must mirror global
|
|
109
|
+
- target rows are matched by `sourceKnowledgeId`
|
|
110
|
+
- no rows are created
|
|
111
|
+
- activities, metadata, tags, categories, parent links and active state are not changed
|
|
112
|
+
- `pages-knowledge` cache is invalidated for touched instances unless `--no-cache` is passed
|
|
113
|
+
|
|
94
114
|
## Admin Ingest Repair
|
|
95
115
|
|
|
96
116
|
Use this when the UI says synchronisations incomplètes or admin console data has repair tasks.
|
|
@@ -98,14 +118,12 @@ Use this when the UI says synchronisations incomplètes or admin console data ha
|
|
|
98
118
|
Preferred path:
|
|
99
119
|
|
|
100
120
|
```bash
|
|
101
|
-
|
|
102
|
-
|
|
121
|
+
gskills-admin admin-ingest repair-state --instance <instanceId> --output json
|
|
122
|
+
gskills-admin admin-ingest repair --instance <instanceId> --dry-run --output json
|
|
123
|
+
gskills-admin admin-ingest repair --instance <instanceId> --yes --output json
|
|
103
124
|
```
|
|
104
125
|
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
- `getAdminIngestRepairState(instanceId)`
|
|
108
|
-
- `adminIngestRepairWorkflow(instanceId, { maxConcurrentDays: 1 })`
|
|
126
|
+
This uses the same repair planner and catchup workflow as the admin-console data UI. Do not use direct env pulls and one-off workflow snippets unless the deployed CLI route is missing.
|
|
109
127
|
|
|
110
128
|
Verify the queue is empty:
|
|
111
129
|
|
|
@@ -7,7 +7,17 @@ description: Use when Codex is asked to handle GSkills feedback as an operationa
|
|
|
7
7
|
|
|
8
8
|
Use this for recurring Codex feedback work, not generic UI ticket browsing.
|
|
9
9
|
|
|
10
|
-
The pattern is: source evidence ->
|
|
10
|
+
The pattern is: source evidence -> CLI feedback inspection -> root cause or data repair -> optional code fix -> feedback state/email update.
|
|
11
|
+
|
|
12
|
+
For normal agents, start with the CLI instead of direct DB access:
|
|
13
|
+
|
|
14
|
+
```bash
|
|
15
|
+
gskills-admin feedback inspect <feedbackId> --output json
|
|
16
|
+
gskills-admin feedback inspect 'https://client.g-skills.fr/fr/...' --output json
|
|
17
|
+
gskills-admin feedback translation-status <feedbackId> --output json
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
Use direct DB only when the CLI output proves the next required table is not exposed yet. If that gap is recurring, add a CLI route or reusable helper.
|
|
11
21
|
|
|
12
22
|
## What Codex Has Actually Been Used For
|
|
13
23
|
|
|
@@ -26,6 +36,7 @@ The pattern is: source evidence -> prod DB row -> root cause or data repair -> o
|
|
|
26
36
|
- Gmail thread when the ticket comes from forwarded client mail.
|
|
27
37
|
- Screenshot and client metadata.
|
|
28
38
|
2. Read prod DB.
|
|
39
|
+
- Prefer `gskills-admin feedback inspect` first.
|
|
29
40
|
- `Feedback`
|
|
30
41
|
- `FeedbackAnalysis`
|
|
31
42
|
- `CommentFeedback`
|
|
@@ -120,6 +131,8 @@ Only write after the dry-run proves eligibility.
|
|
|
120
131
|
## Common Pitfalls
|
|
121
132
|
|
|
122
133
|
- Do not trust the automatic AI comment over Marina’s Slack reply.
|
|
134
|
+
- Do not skip `feedback inspect` when the ticket id or URL is known.
|
|
135
|
+
- Do not trust `FeedbackAnalysis.translatedFr` blindly. Use `translation-status` when it might be a fallback copy.
|
|
123
136
|
- Do not import forwarded email as one ticket if it contains multiple asks.
|
|
124
137
|
- Do not close a feedback before prod deploy is live when the fix depends on deploy.
|
|
125
138
|
- Do not use inline body strings for real feedback reply emails.
|