@numericoach/gskills-admin-cli 0.1.26 → 0.1.27
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 +46 -1
- package/dist/gskills-admin.js +1270 -15
- package/package.json +1 -1
- package/skills/gskills-admin-cli/SKILL.md +45 -4
- package/skills/gskills-page-content-blocks/SKILL.md +107 -0
package/package.json
CHANGED
|
@@ -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
|
|
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
|
|
241
|
-
gskills-admin pages create --data
|
|
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
|
-
|
|
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
|