@numericoach/gskills-admin-cli 0.1.30 → 0.1.32

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
@@ -6,6 +6,14 @@ Super admin CLI for GSkills operations through authenticated app API routes.
6
6
 
7
7
  The CLI opens GSkills in the browser, uses the normal GSkills login, then stores an opaque CLI token locally. Every API request re-checks `User.adminState = SUPER_ADMIN` in GSkills before touching data.
8
8
 
9
+ ## Content platform migration and ADRs
10
+
11
+ Before operating migrated content, run `gskills-admin content-platform help --output json`. The same directives are included in `schema --output json`. Read the [migration operations guide](skills/gskills-admin-cli/references/content-platform.md) before using the examples below on a migrated instance.
12
+
13
+ Browse all migration tables with `content-platform tables`, inspect one with `content-platform explain <resource>`, or read the [complete table reference](skills/gskills-admin-cli/references/content-platform-tables.md). Each resource's `help` and `schema` include the same explanation.
14
+
15
+ Canonical resources are read-only. Legacy page editing and sync examples below apply only to scopes whose current database authority still permits those legacy operations. They are not canonical draft or publication commands.
16
+
9
17
  ## Local usage
10
18
 
11
19
  ```bash
@@ -13,14 +21,14 @@ bun run gskills-admin auth login --base-url https://g-skills.fr
13
21
  bun run gskills-admin auth whoami
14
22
  bun run gskills-admin schema --output json
15
23
  bun run gskills-admin pages list
16
- bun run gskills-admin sync run --target <instanceId> --only pages,quizzes --yes
24
+ bun run gskills-admin content-platform help --output json
17
25
  ```
18
26
 
19
27
  Content-like resources default to `instanceId = "global"` when `--instance` is omitted. On `global`, create defaults to `disabled: true` for resources that support it unless the payload explicitly says otherwise.
20
28
  Delete commands are soft-only. They archive rows when the resource supports `archived`, fall back only when that field does not exist, and refuse resources that cannot be safely hidden.
21
29
  CLI writes are logged in the GSkills admin logs with the authenticated user and CLI metadata.
22
30
 
23
- Sync dry-runs use the shared GSkills diff preview system:
31
+ For scopes that still permit legacy sync, dry-runs use the shared GSkills diff preview system:
24
32
 
25
33
  ```bash
26
34
  gskills-admin sync presets --output json
@@ -57,6 +65,22 @@ gskills-admin pages update <pageId> --data-file ./page-fields.json --yes --outpu
57
65
 
58
66
  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. Delete flows should archive content first; after a real delete, re-read the row and verify `archived: true` when the resource supports it.
59
67
 
68
+ Workflow authoring has a guided CLI surface. Use it before raw `workflows` and `workflow-actions` CRUD:
69
+
70
+ ```bash
71
+ gskills-admin workflows schema --output json
72
+ gskills-admin workflows schema --trigger LEARNING_PATH_NOT_STARTED --output json
73
+ gskills-admin workflows example --trigger LEARNING_PATH_NOT_STARTED --output json
74
+ gskills-admin workflows preview-email --data-file ./workflow.json --fake --language fr --output json
75
+ gskills-admin workflows preview-email --data-file ./workflow.json --user user@example.com --language fr --output json
76
+ gskills-admin workflows create-configured --instance global --data-file ./workflow.json --inactive --dry-run --output json
77
+ gskills-admin workflows create-configured --instance global --data-file ./workflow.json --active --yes --output json
78
+ ```
79
+
80
+ `workflows schema` lists every supported trigger and action, the trigger config schema, trigger payload schema, email variables, button placeholders and examples. `create-configured` creates the workflow and all actions in one operation. It requires an activation decision. Ask whether to enable the workflow now, then pass `--active` or `--inactive`. Prefer `--inactive` until the preview email, target ids, recipients and translations are approved.
81
+
82
+ Email actions use `config.templates`, a map of language code to `{ subject, body }`. Keep variables such as `{{userName}}`, `{{userEmail}}`, `{{instanceName}}` and trigger-specific variables unchanged across translations. `preview-email` renders the exact subject and body without sending anything. Use `--fake` for sample trigger data, or `--user` / `--email` to preview with a real user.
83
+
60
84
  For page body edits, prefer the granular block helpers when a stable block id exists. Dry-run first, then write:
61
85
 
62
86
  ```bash
@@ -135,6 +159,30 @@ gskills-admin learning-paths generate-icon <learningPathId> --prompt-file ./icon
135
159
 
136
160
  Do not pass `--use-app-icon` unless the user explicitly asks for the app logo to appear. It is off by default because most parcours icons should be symbolic. Repeating app logos across every learning path gets visually heavy and often produces cluttered, low-quality icons.
137
161
 
162
+ Pedagogical activities have first-class authoring commands. Use `schema` first so agents can see every live activity type, starter template, translatable JSON path, page block shape, and learning path item shape:
163
+
164
+ ```bash
165
+ gskills-admin pedagogical-activities schema --output json
166
+ gskills-admin pedagogical-activities example --type choice_question --instance global --language fr --output json
167
+ gskills-admin pedagogical-activities create --data-file ./activity.json --dry-run --output json
168
+ gskills-admin pedagogical-activities update <activityId> --data-file ./activity.patch.json --dry-run --output json
169
+ gskills-admin pedagogical-activities translate <activityId> --from fr --to en,es --mode full --dry-run --output json
170
+ gskills-admin pedagogical-activities attach-page <activityId> --page <pageId> --position end --points 25 --badges <badgeId> --dry-run --output json
171
+ gskills-admin pedagogical-activities attach-learning-path <activityId> --learning-path <learningPathId> --rewards-file ./rewards.json --dry-run --output json
172
+ gskills-admin pages activity add <pageId> --activity <activityId> --position end --points 25 --badges <badgeId> --dry-run --output json
173
+ gskills-admin pages activity update <pageId> --block-id <blockId> --rewards-file ./rewards.json --dry-run --output json
174
+ gskills-admin pages activity remove <pageId> --block-id <blockId> --dry-run --output json
175
+ gskills-admin learning-paths activity add <learningPathId> --activity <activityId> --points 25 --badges <badgeId> --dry-run --output json
176
+ gskills-admin learning-paths activity update <learningPathId> --item <itemId> --rewards-file ./rewards.json --dry-run --output json
177
+ gskills-admin learning-paths activity remove <learningPathId> --item <itemId> --dry-run --output json
178
+ ```
179
+
180
+ `create` and `update` use the same editor payload contract and publish validation as the super-admin editor. `translate` preserves technical IDs, URLs, answer keys, coordinates, and per-type logic while translating only declared human-readable strings. Prefer `pages activity ...` and `learning-paths activity ...` when editing containers. They add, update, or remove the activity reference and keep placement rows in sync. The older `pedagogical-activities attach-*` aliases are still available for simple insertion. All writes require `--dry-run` or `--yes`.
181
+
182
+ Rewards belong to the page block or learning-path item where the activity is placed. Placement commands accept `--points` and comma-separated `--badges` for known rewards, or `--rewards` / `--rewards-file` for the generic reward array. Reward items need stable unique IDs and use `ONCE_PER_PLACEMENT`. New placements default to an explicit empty array. Updates preserve the existing placement rewards when no reward flag is supplied. Use `--clear-rewards` to replace them with an empty array.
183
+
184
+ Placement does not publish an activity. Learner-ready activities must be published, enabled, not archived, and translated for the target page or learning path language. Placement dry-runs report these checks in `readiness`. `pedagogical-activities get` returns the complete editable activity, including translations, placements, whole-activity skill links, and per-step skill links.
185
+
138
186
  AI translation is available for content that has native AI translation in the editor:
139
187
 
140
188
  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.
@@ -148,11 +196,12 @@ gskills-admin translate pages --ids <pageId,pageId> --from fr --to en --dry-run
148
196
  gskills-admin translate pages --all --instance global --from fr --to en --take 100 --dry-run --output json
149
197
  gskills-admin translate quizzes <quizId> --to en --yes --output json
150
198
  gskills-admin translate knowledge-video <knowledgeId> --from en --to es --yes --output json
199
+ gskills-admin pedagogical-activities translate <activityId> --from fr --to en,es --mode full --dry-run --output json
151
200
  gskills-admin translate changelogs <changelogId> --to all --concurrency 8 --dry-run --output json
152
201
  ```
153
202
 
154
203
  Supported kinds are `pages`, `quizzes`, `topics`, `badges`, `menus`, `menu-sections`, `internal-knowledge`, `knowledge-video`, `learning-paths`, `chromebook-exercises`, and `changelogs`.
155
- Use `--to all` to expand to every supported locale. Changelog translation supports `--concurrency 1-20` for faster backfills.
204
+ Use `--to all` to expand to every supported locale. Use `pedagogical-activities translate` for activity content because it preserves per-type JSON and activity ids. Changelog translation supports `--concurrency 1-20` for faster backfills.
156
205
 
157
206
  Changelog CRUD is available through `changelogs` and `changelog-groups`:
158
207
 
@@ -239,7 +288,7 @@ The direct-DB replacement commands cover the recurring historical gaps: email-to
239
288
 
240
289
  Agents can combine the CLI with local code. Use CLI JSON output inside shell loops, `jq`, Bun, Node, or TypeScript helpers for batching, joins, comparisons, retries, and reports. If a small local tool is missing, install or invoke it when useful. Keep production access through the authenticated CLI, not direct DB URLs.
241
290
 
242
- Raw project, skill, workflow, 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`, `workflow-actions`, `skill-applications`, `skill-capabilities`, `skill-clusters`, `skills`, `skill-content-links`, `skill-sets`, `analytics`, `quiz-attempts`, `user-paths`, `chromebook-progress`, `user-badges`, `user-learning-paths`, and `user-learning-path-item-completions`.
291
+ Raw project, skill, activity, workflow, and analytics data can be read or adjusted through resources such as `project-data`, `ticket-sla-rules`, `learning-path-items`, `learning-path-groups`, `pedagogical-activities`, `pedagogical-activity-translations`, `pedagogical-activity-placements`, `pedagogical-activity-attempts`, `pedagogical-activity-responses`, `pedagogical-activity-events`, `quiz-questions`, `quiz-options`, `workflow-actions`, `skill-applications`, `skill-capabilities`, `skill-clusters`, `skills`, `skill-content-links`, `skill-sets`, `analytics`, `quiz-attempts`, `user-paths`, `chromebook-progress`, `user-badges`, `user-learning-paths`, and `user-learning-path-item-completions`.
243
292
 
244
293
  `gskills-admin skills install`, `skills path`, and `skills help` are for bundled Codex skills. `skills list`, `skills get`, `skills create`, `skills update`, and `skills delete` operate on the app skill catalog. Use `skill-content-links` when associating pages, quizzes, parcours items, knowledge, or resources to skills.
245
294