@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
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@numericoach/gskills-admin-cli",
3
- "version": "0.1.25",
3
+ "version": "0.1.27",
4
4
  "private": false,
5
5
  "type": "module",
6
6
  "description": "Admin-only CLI for GSkills super-admin operations.",
@@ -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 without `--dry-run` only after the payload is correct.
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 @page.json --dry-run --output json
240
- 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
241
283
  ```
242
284
 
243
- 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.
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