@numericoach/gskills-admin-cli 0.1.25 → 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/package.json
CHANGED
|
@@ -13,6 +13,8 @@ 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`.
|
|
17
|
+
- `gskills-admin-cli-publishing` when publishing the npm package or sharing the publish recipe with another teammate.
|
|
16
18
|
|
|
17
19
|
## Install
|
|
18
20
|
|
|
@@ -55,9 +57,10 @@ gskills-admin pages list --take 100 --output jsonl
|
|
|
55
57
|
```bash
|
|
56
58
|
gskills-admin pages create --data '{"name":"Draft","slug":"draft","language":"fr"}' --dry-run --output json
|
|
57
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
|
|
58
61
|
```
|
|
59
62
|
|
|
60
|
-
5. Apply the exact same command
|
|
63
|
+
5. Apply the exact same command with `--yes` only after the payload is correct.
|
|
61
64
|
|
|
62
65
|
6. For visible content changes, check the resource cache hint and refresh cache when needed.
|
|
63
66
|
|
|
@@ -69,6 +72,39 @@ gskills-admin cache invalidate --instance <instanceId> --scope pages --yes --out
|
|
|
69
72
|
|
|
70
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.
|
|
71
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
|
+
|
|
72
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.
|
|
73
109
|
|
|
74
110
|
```bash
|
|
@@ -130,6 +166,10 @@ These recurring historical DB-only jobs now have CLI paths:
|
|
|
130
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` |
|
|
131
167
|
| Source-link drift after sync | `gskills-admin sync repair-source-links --target <instanceId> --dry-run --output json` |
|
|
132
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` |
|
|
133
173
|
| Passed quiz did not complete a page/course | `gskills-admin progress embedded-course --user <userId> --quiz <quizId> --page <pageId> --dry-run --output json` |
|
|
134
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` |
|
|
135
175
|
| Force relogin after access/auth data change | `gskills-admin sessions invalidate --email user@example.com --dry-run --output json` |
|
|
@@ -139,6 +179,8 @@ These recurring historical DB-only jobs now have CLI paths:
|
|
|
139
179
|
|
|
140
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.
|
|
141
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
|
+
|
|
142
184
|
## Imported Sheet Cell Updates
|
|
143
185
|
|
|
144
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`.
|
|
@@ -236,11 +278,11 @@ Typical create flow:
|
|
|
236
278
|
gskills-admin pages list --where '{"language":"fr","slug":{"contains":"gmail"}}' --fields id,name,slug,language,instanceId,contentType --output json
|
|
237
279
|
gskills-admin topics list --where '{"language":"fr"}' --fields id,name,slug,instanceId --output json
|
|
238
280
|
gskills-admin menus list --where '{"instanceId":"global"}' --fields id,name,parentId,pageId,url,instanceId --output json
|
|
239
|
-
gskills-admin pages create --data
|
|
240
|
-
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
|
|
241
283
|
```
|
|
242
284
|
|
|
243
|
-
|
|
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.
|
|
244
286
|
|
|
245
287
|
## AI Translation
|
|
246
288
|
|
|
@@ -0,0 +1,84 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: gskills-admin-cli-publishing
|
|
3
|
+
description: Use when publishing the @numericoach/gskills-admin-cli npm package or refreshing the team publish recipe.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# GSkills Admin CLI Publishing
|
|
7
|
+
|
|
8
|
+
Use this skill when publishing `@numericoach/gskills-admin-cli`.
|
|
9
|
+
|
|
10
|
+
The package lives in `packages/gskills-admin-cli`. It is public, but publishing still needs a Numericoach npm token with publish rights.
|
|
11
|
+
|
|
12
|
+
## Token Storage
|
|
13
|
+
|
|
14
|
+
Never commit an npm token and never write it into a repo `.npmrc`.
|
|
15
|
+
|
|
16
|
+
On macOS, store each teammate's own token in Keychain:
|
|
17
|
+
|
|
18
|
+
```bash
|
|
19
|
+
read -rsp "npm token: " NPM_TOKEN
|
|
20
|
+
printf "\n"
|
|
21
|
+
security add-generic-password \
|
|
22
|
+
-s numericoach-npm-publish-token \
|
|
23
|
+
-a registry.npmjs.org \
|
|
24
|
+
-w "$NPM_TOKEN" \
|
|
25
|
+
-U
|
|
26
|
+
unset NPM_TOKEN
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
Check that the Keychain item exists without printing the token:
|
|
30
|
+
|
|
31
|
+
```bash
|
|
32
|
+
security find-generic-password \
|
|
33
|
+
-s numericoach-npm-publish-token \
|
|
34
|
+
-a registry.npmjs.org >/dev/null
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
## Publish Flow
|
|
38
|
+
|
|
39
|
+
From the repo root:
|
|
40
|
+
|
|
41
|
+
```bash
|
|
42
|
+
npm view @numericoach/gskills-admin-cli version --registry=https://registry.npmjs.org/
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
Bump `packages/gskills-admin-cli/package.json` to the next patch version.
|
|
46
|
+
|
|
47
|
+
Build and inspect the package:
|
|
48
|
+
|
|
49
|
+
```bash
|
|
50
|
+
cd packages/gskills-admin-cli
|
|
51
|
+
bun run build
|
|
52
|
+
node dist/gskills-admin.js schema --output json >/tmp/gskills-admin-schema.json
|
|
53
|
+
bun pm pack --dry-run
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
Publish with a temporary npm config generated from Keychain:
|
|
57
|
+
|
|
58
|
+
```bash
|
|
59
|
+
cd packages/gskills-admin-cli
|
|
60
|
+
NPM_TOKEN="$(security find-generic-password -s numericoach-npm-publish-token -a registry.npmjs.org -w)"
|
|
61
|
+
NPM_CONFIG_FILE="$(mktemp)"
|
|
62
|
+
trap 'rm -f "$NPM_CONFIG_FILE"' EXIT
|
|
63
|
+
{
|
|
64
|
+
printf 'registry=https://registry.npmjs.org/\n'
|
|
65
|
+
printf '//registry.npmjs.org/:_authToken=%s\n' "$NPM_TOKEN"
|
|
66
|
+
} > "$NPM_CONFIG_FILE"
|
|
67
|
+
unset NPM_TOKEN
|
|
68
|
+
NPM_CONFIG_USERCONFIG="$NPM_CONFIG_FILE" npm whoami
|
|
69
|
+
NPM_CONFIG_USERCONFIG="$NPM_CONFIG_FILE" npm publish --access public
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
Verify the exact version after publish:
|
|
73
|
+
|
|
74
|
+
```bash
|
|
75
|
+
npm view @numericoach/gskills-admin-cli@<version> version --registry=https://registry.npmjs.org/
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
## Rules
|
|
79
|
+
|
|
80
|
+
- Publish from `packages/gskills-admin-cli`, not the app root.
|
|
81
|
+
- Use `NPM_CONFIG_USERCONFIG` with a temp file for publish. Plain `NPM_TOKEN` can be ignored by npm in this setup.
|
|
82
|
+
- Keep the token in the OS credential store, not in shell rc files, repo files, command logs, or documentation.
|
|
83
|
+
- Commit the version bump, bundled skills, README updates, and rebuilt `dist/gskills-admin.js` after validation.
|
|
84
|
+
- Do not call the package published until `npm view @numericoach/gskills-admin-cli@<version> version` returns the new version.
|
|
@@ -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
|