@numericoach/gskills-admin-cli 0.1.26 → 0.1.28

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/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@numericoach/gskills-admin-cli",
3
- "version": "0.1.26",
3
+ "version": "0.1.28",
4
4
  "private": false,
5
5
  "type": "module",
6
6
  "description": "Admin-only CLI for GSkills super-admin operations.",
@@ -13,6 +13,7 @@ Also install and use the companion skills:
13
13
 
14
14
  - `gskills-vocabulary` when explaining work to admins or writing user-facing summaries.
15
15
  - `gskills-customer-playbooks` when the task names a recurring GSkills customer.
16
+ - `gskills-page-content-blocks` before creating or patching `Pages.content`.
16
17
  - `gskills-admin-cli-publishing` when publishing the npm package or sharing the publish recipe with another teammate.
17
18
 
18
19
  ## Install
@@ -56,9 +57,10 @@ gskills-admin pages list --take 100 --output jsonl
56
57
  ```bash
57
58
  gskills-admin pages create --data '{"name":"Draft","slug":"draft","language":"fr"}' --dry-run --output json
58
59
  gskills-admin pages update <id> --data '{"disabled":false}' --dry-run --output json
60
+ gskills-admin pages create --data-file ./page.json --dry-run --output json
59
61
  ```
60
62
 
61
- 5. Apply the exact same command without `--dry-run` only after the payload is correct.
63
+ 5. Apply the exact same command with `--yes` only after the payload is correct.
62
64
 
63
65
  6. For visible content changes, check the resource cache hint and refresh cache when needed.
64
66
 
@@ -70,6 +72,39 @@ gskills-admin cache invalidate --instance <instanceId> --scope pages --yes --out
70
72
 
71
73
  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.
72
74
 
75
+ Generic `create` and `update` require `--dry-run` or `--yes`. Use `--data-file` for large JSON payloads. Do not ask agents to inline full EditorJS content in shell strings.
76
+
77
+ For page body edits, prefer the granular block helpers when a stable block id exists:
78
+
79
+ ```bash
80
+ gskills-admin pages content-schema --output json
81
+ gskills-admin pages get <pageId> --fields id,name,language,currentVersion,updatedAt,content --output json
82
+ gskills-admin pages block list <pageId> --output json
83
+ gskills-admin pages block replace-text <pageId> --block-id <blockId> --text-file ./block.txt --dry-run --output json
84
+ gskills-admin pages block insert-before <pageId> --block-id <anchorBlockId> --block-file ./block.json --dry-run --output json
85
+ gskills-admin pages block replace-text <pageId> --block-id <blockId> --text-file ./block.txt --reason "Fix wording" --yes --output json
86
+ ```
87
+
88
+ Use raw `pages patch-content` only when the edit really needs multiple JSON paths:
89
+
90
+ ```bash
91
+ gskills-admin pages patch-content <pageId> --patch-file ./page.patch.json --dry-run --output json
92
+ gskills-admin pages patch-content <pageId> --patch-file ./page.patch.json --expect-version 7 --expect-content-sha1 <sha1> --reason "Fix wording" --yes --output json
93
+ ```
94
+
95
+ Patch files are RFC 6902 JSON Patch arrays:
96
+
97
+ ```json
98
+ [
99
+ { "op": "test", "path": "/blocks/0/type", "value": "paragraph" },
100
+ { "op": "replace", "path": "/blocks/0/data/text", "value": "Updated paragraph text" }
101
+ ]
102
+ ```
103
+
104
+ The block helpers read the full page content, find nested blocks by id, generate guarded JSON Patch, validate the predicted full content against `pages content-schema`, call `pages patch-content`, then reread and validate the page after real writes. The patch route previews block/text deltas, stores page history, refreshes the page vector, invalidates `pages` and `pages-knowledge`, logs the write, and rejects stale `updatedAt`, version, or content SHA guards. Keep full-content `pages update --data '{"content": ...}'` for expert migrations only.
105
+
106
+ `pages content-schema` is the machine-readable source of truth for supported EditorJS/GSkills blocks, nested child-block paths, immutable reference fields and examples. Agents should call it before generating or patching page content.
107
+
73
108
  Internal knowledge and resources support direct local file uploads through signed GCS URLs. The CLI gets a signed URL from the authenticated app API, streams the local file directly to storage, then writes the normal row with the returned URL. This avoids routing large videos through a Next.js API body.
74
109
 
75
110
  ```bash
@@ -131,6 +166,10 @@ These recurring historical DB-only jobs now have CLI paths:
131
166
  | Existing global knowledge video URL changed | `gskills-admin internal-knowledge sync-media --source global --since today --languages fr --all-targets --dry-run --output json` |
132
167
  | Source-link drift after sync | `gskills-admin sync repair-source-links --target <instanceId> --dry-run --output json` |
133
168
  | Page metadata backfill from global copies | `gskills-admin pages backfill-field --field headerColor --all-targets --dry-run --output json` |
169
+ | Page block schema for agents | `gskills-admin pages content-schema --output json` |
170
+ | Single page block edit by id | `gskills-admin pages block replace-text <pageId> --block-id <blockId> --text-file ./block.txt --dry-run --output json` |
171
+ | Insert a page block near another block | `gskills-admin pages block insert-before <pageId> --block-id <anchorBlockId> --block-file ./block.json --dry-run --output json` |
172
+ | Page body patch with history/vector/cache | `gskills-admin pages patch-content <pageId> --patch-file ./page.patch.json --dry-run --output json` |
134
173
  | Passed quiz did not complete a page/course | `gskills-admin progress embedded-course --user <userId> --quiz <quizId> --page <pageId> --dry-run --output json` |
135
174
  | Passed learning-path quiz missing completion row | `gskills-admin progress learning-path-quiz-mismatches --instance <instanceId> --output json` then `gskills-admin progress repair-learning-path-quiz-mismatches --instance <instanceId> --dry-run --output json` |
136
175
  | Force relogin after access/auth data change | `gskills-admin sessions invalidate --email user@example.com --dry-run --output json` |
@@ -140,6 +179,8 @@ These recurring historical DB-only jobs now have CLI paths:
140
179
 
141
180
  If a job is not in this table, first try `gskills-admin schema --output json` and resource CRUD. If the route is still missing and the job is recurring, add the CLI route before reaching for direct DB access.
142
181
 
182
+ `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.
183
+
143
184
  ## Imported Sheet Cell Updates
144
185
 
145
186
  Use `patch-cells` for focused imported-sheet row-cell updates, especially when a script already has the right target rows from `imported-sheets get`.
@@ -237,11 +278,11 @@ Typical create flow:
237
278
  gskills-admin pages list --where '{"language":"fr","slug":{"contains":"gmail"}}' --fields id,name,slug,language,instanceId,contentType --output json
238
279
  gskills-admin topics list --where '{"language":"fr"}' --fields id,name,slug,instanceId --output json
239
280
  gskills-admin menus list --where '{"instanceId":"global"}' --fields id,name,parentId,pageId,url,instanceId --output json
240
- gskills-admin pages create --data @page.json --dry-run --output json
241
- gskills-admin pages create --data @page.json --output json
281
+ gskills-admin pages create --data-file ./page.json --dry-run --output json
282
+ gskills-admin pages create --data-file ./page.json --yes --output json
242
283
  ```
243
284
 
244
- 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.
285
+ For edits to an existing page body, use `pages block ...` when targeting one stable block id. Use `pages patch-content` for reviewed multi-path patches. Avoid rewriting the whole `content` JSON unless you are doing a reviewed migration.
245
286
 
246
287
  ## AI Translation
247
288
 
@@ -0,0 +1,107 @@
1
+ ---
2
+ name: gskills-page-content-blocks
3
+ description: Use before creating or patching GSkills page content, especially EditorJS Pages.content JSON, custom blocks, nested layouts, imported sheets, quizzes, page/resource tags, and AI-agent page edits.
4
+ ---
5
+
6
+ # GSkills Page Content Blocks
7
+
8
+ Use this skill whenever Codex creates or edits `Pages.content`.
9
+
10
+ The source of truth is the CLI block schema. Read it first:
11
+
12
+ ```bash
13
+ gskills-admin pages content-schema --output json
14
+ ```
15
+
16
+ If `gskills-admin` is not installed, use:
17
+
18
+ ```bash
19
+ bunx @numericoach/gskills-admin-cli@latest pages content-schema --output json
20
+ ```
21
+
22
+ ## Rules
23
+
24
+ - Treat `Pages.content` as EditorJS JSON, not markdown.
25
+ - Preserve existing block `id`, `type`, nested blocks, IDs, URLs and media metadata.
26
+ - Use real IDs from CLI reads for `quiz`, `pageTag`, `learningPathTag`, `resourceTag`, `importedSheet`, `pointRedemption`, `image`, `video`, `vimeo` and `boardly`.
27
+ - Never invent a block type. If it is not in `pages content-schema`, inspect the app before using it.
28
+ - For single-block edits, prefer `pages block ...` commands. They find nested blocks by id, generate guarded JSON Patch, validate against this schema, and reuse `pages patch-content`.
29
+ - For multi-path edits, use `pages patch-content` with JSON Patch, `test` operations and version or content SHA guards.
30
+ - Use full `pages update --data '{"content": ...}'` only for reviewed migrations.
31
+
32
+ ## Common Flow
33
+
34
+ ```bash
35
+ gskills-admin pages content-schema --output json
36
+ gskills-admin pages get <pageId> --fields id,name,language,currentVersion,updatedAt,content --output json
37
+ gskills-admin pages block list <pageId> --output json
38
+ gskills-admin pages block replace-text <pageId> --block-id <blockId> --text-file ./block.txt --dry-run --output json
39
+ gskills-admin pages block insert-before <pageId> --block-id <anchorBlockId> --block-file ./block.json --dry-run --output json
40
+ gskills-admin pages block replace-text <pageId> --block-id <blockId> --text-file ./block.txt --expect-type paragraph --yes --output json
41
+ ```
42
+
43
+ Raw JSON Patch is still available for multi-path edits:
44
+
45
+ ```bash
46
+ gskills-admin pages patch-content <pageId> --patch-file ./page.patch.json --dry-run --output json
47
+ gskills-admin pages patch-content <pageId> --patch-file ./page.patch.json --expect-version <version> --yes --output json
48
+ ```
49
+
50
+ ## Nested Blocks
51
+
52
+ The main nested block containers are:
53
+
54
+ - `columns`: `data.cols[].blocks`
55
+ - `accordion_tool`: `data.sections[].content.blocks`
56
+ - `vertical_accordion`: `data.sections[].content.blocks`
57
+ - `section_tool`: `data.content.blocks`
58
+ - `tabs`: `data.tabs[].content.blocks`
59
+ - `slider`: `data.slides[].content.blocks`
60
+
61
+ When patching nested content, use those paths and include a `test` on the target block type or expected text.
62
+
63
+ ## Good Patch Shape
64
+
65
+ ```json
66
+ [
67
+ { "op": "test", "path": "/blocks/0/type", "value": "paragraph" },
68
+ { "op": "test", "path": "/blocks/0/data/text", "value": "Ancien texte" },
69
+ { "op": "replace", "path": "/blocks/0/data/text", "value": "Nouveau texte" }
70
+ ]
71
+ ```
72
+
73
+ For inserted blocks, generate a compact valid EditorJS block:
74
+
75
+ ```json
76
+ [
77
+ {
78
+ "op": "add",
79
+ "path": "/blocks/2",
80
+ "value": {
81
+ "id": "codex-note-1",
82
+ "type": "paragraph",
83
+ "data": { "text": "Texte ajoute." }
84
+ }
85
+ }
86
+ ]
87
+ ```
88
+
89
+ ## Block Choice
90
+
91
+ - Use `paragraph`, `header`, `list`, `quote`, `table` and `code` for normal text.
92
+ - Use `accordion_tool` for course modules.
93
+ - Use `section_tool` for visual grouping and Gemini sections.
94
+ - Use `tabs`, `slider` and `columns` only when nearby pages already use them or the user asked for that structure.
95
+ - Use `quiz` only with an existing quiz ID.
96
+ - Use `importedSheet` only after inspecting or creating the imported sheet with the CLI.
97
+ - Use `pageTag`, `learningPathTag` and `resourceTag` only with real same-language rows when available.
98
+
99
+ ## After Writing
100
+
101
+ Verify:
102
+
103
+ - dry-run preview matched the intended block and text deltas
104
+ - `currentVersion` changed after the write
105
+ - page history exists through the patch route
106
+ - cache scopes are refreshed for visible deploy content
107
+ - translated sibling pages keep localized IDs and wording