@numericoach/gskills-admin-cli 0.1.12 → 0.1.14

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
@@ -17,7 +17,7 @@ bun run gskills-admin sync run --target <instanceId> --only pages,quizzes --yes
17
17
  ```
18
18
 
19
19
  Content-like resources default to `instanceId = "global"` when `--instance` is omitted.
20
- Deletes require both `--force` and an exact `--confirm-delete <resource>:<id>` token.
20
+ Delete commands are soft-only. They disable or deactivate rows when the resource supports it, and refuse resources that cannot be safely disabled.
21
21
  CLI writes are logged in the GSkills admin logs with the authenticated user and CLI metadata.
22
22
 
23
23
  Sync dry-runs use the shared GSkills diff preview system:
@@ -30,6 +30,8 @@ gskills-admin sync diff --target <instanceId> --preset client-content --output j
30
30
  gskills-admin sync run --targets <instanceId,instanceId> --only pages,quizzes --dry-run --output json
31
31
  ```
32
32
 
33
+ Language-limited menu sync writes are blocked from the CLI. Run the diff first, sync the language-limited content without `menus`, or sync menus without `--languages` after the backend non-destructive sync patch is deployed.
34
+
33
35
  Deploy cache can be invalidated at the same scopes as the super-admin content settings screen:
34
36
 
35
37
  ```bash
@@ -45,7 +47,7 @@ gskills-admin pages help --output json
45
47
  gskills-admin topics help --output json
46
48
  ```
47
49
 
48
- 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.
50
+ Use the listed `cache.scopes` with `gskills-admin cache invalidate` after create, update, or soft-delete when the end-user view must reflect the change immediately.
49
51
 
50
52
  AI translation is available for content that has native AI translation in the editor:
51
53
 
@@ -902,21 +902,45 @@ var updateResource = async (resource, id, ctx) => {
902
902
  body: JSON.stringify({ data })
903
903
  });
904
904
  };
905
+ var getSoftDeleteData = (resource) => {
906
+ if (resource.defaultFields.includes("disabled"))
907
+ return { disabled: true };
908
+ if (resource.defaultFields.includes("archived"))
909
+ return { archived: true };
910
+ if (resource.defaultFields.includes("isActive"))
911
+ return { isActive: false };
912
+ if (resource.defaultFields.includes("active"))
913
+ return { active: false };
914
+ return null;
915
+ };
905
916
  var deleteResource = async (resource, id, ctx) => {
906
917
  const expectedConfirmation = `${resource.name}:${id}`;
918
+ const data = getSoftDeleteData(resource);
919
+ if (!data) {
920
+ throw new CliError("CLI delete is disabled for this resource because it cannot be safely disabled.", 2, {
921
+ id,
922
+ resource: resource.name,
923
+ warning: "The CLI never permanently deletes production data.",
924
+ suggestion: `Use gskills-admin ${resource.name} update <id> --data '{...}' only if you know the safe inactive field.`
925
+ });
926
+ }
907
927
  if (!hasFlag(ctx, "force")) {
908
- throw new CliError("Delete requires --force", 2, {
928
+ throw new CliError("Soft delete requires --force", 2, {
909
929
  id,
910
930
  resource: resource.name,
911
- warning: "This permanently deletes production data.",
931
+ action: "soft-delete",
932
+ data,
933
+ warning: "The CLI never permanently deletes production data.",
912
934
  requiredConfirmation: expectedConfirmation
913
935
  });
914
936
  }
915
937
  if (getStringFlag(ctx, "confirm-delete") !== expectedConfirmation) {
916
- throw new CliError(`Delete requires --confirm-delete ${expectedConfirmation}`, 2, {
938
+ throw new CliError(`Soft delete requires --confirm-delete ${expectedConfirmation}`, 2, {
917
939
  id,
918
940
  resource: resource.name,
919
- warning: "This permanently deletes production data.",
941
+ action: "soft-delete",
942
+ data,
943
+ warning: "The CLI never permanently deletes production data.",
920
944
  requiredConfirmation: expectedConfirmation,
921
945
  usage: `gskills-admin ${resource.name} delete ${id} --force --confirm-delete ${expectedConfirmation}`
922
946
  });
@@ -926,16 +950,15 @@ var deleteResource = async (resource, id, ctx) => {
926
950
  dryRun: true,
927
951
  resource: resource.name,
928
952
  id,
929
- action: "delete",
953
+ action: "soft-delete",
930
954
  confirmed: true,
931
- warning: "This permanently deletes production data."
955
+ data,
956
+ warning: "The CLI never permanently deletes production data."
932
957
  };
933
958
  }
934
959
  return requestApi(`/api/cli/${resource.name}/${id}`, {
935
- method: "DELETE",
936
- body: JSON.stringify({
937
- confirmation: expectedConfirmation
938
- })
960
+ method: "PATCH",
961
+ body: JSON.stringify({ data })
939
962
  });
940
963
  };
941
964
  var runFeedbackCommand = async (action, feedbackId, ctx) => {
@@ -1193,6 +1216,7 @@ var runSyncCommand = async (action, ctx) => {
1193
1216
  sourceInstanceId: getStringFlag(ctx, "source") ?? "global",
1194
1217
  options: buildSyncOptions(ctx)
1195
1218
  };
1219
+ assertSyncWriteIsNonDestructive(action, basePayload.options, ctx);
1196
1220
  const endpoint = action === "diff" || hasFlag(ctx, "dry-run") ? "/api/cli/sync/diff" : "/api/cli/sync/run";
1197
1221
  const runForTarget = (targetInstanceId) => requestApi(endpoint, {
1198
1222
  method: "POST",
@@ -1213,6 +1237,19 @@ var runSyncCommand = async (action, ctx) => {
1213
1237
  }
1214
1238
  return { targets: results };
1215
1239
  };
1240
+ var assertSyncWriteIsNonDestructive = (action, options, ctx) => {
1241
+ if (action !== "run" || hasFlag(ctx, "dry-run"))
1242
+ return;
1243
+ if (options.menus && options.allowedLanguageCodes.length > 0) {
1244
+ throw new CliError("Partial menu sync is blocked from the CLI because it can hide existing translations on older backends.", 2, {
1245
+ safeAlternatives: [
1246
+ "Run sync diff first.",
1247
+ "Remove menus from --only for language-limited syncs.",
1248
+ "Run menus without --languages only after backend non-destructive sync is deployed."
1249
+ ]
1250
+ });
1251
+ }
1252
+ };
1216
1253
  var runCacheCommand = async (action, ctx) => {
1217
1254
  if (!action || action === "help")
1218
1255
  return cacheHelp();
@@ -1509,6 +1546,7 @@ var rootHelp = () => ({
1509
1546
  "gskills-admin auth whoami",
1510
1547
  "gskills-admin pages list",
1511
1548
  `gskills-admin pages update <id> --data '{"disabled":true}'`,
1549
+ "gskills-admin pages delete <id> --force --confirm-delete pages:<id> # soft-disables only",
1512
1550
  "gskills-admin sync run --target <instanceId> --only pages,quizzes --yes",
1513
1551
  "gskills-admin translate pages <id> --to en,es --dry-run"
1514
1552
  ],
@@ -1564,7 +1602,7 @@ var schemaHelp = () => ({
1564
1602
  { name: `${resource.name} get`, args: ["id"], writes: false },
1565
1603
  { name: `${resource.name} create`, flags: ["--data", "--instance", "--dry-run"], writes: true },
1566
1604
  { name: `${resource.name} update`, args: ["id"], flags: ["--data", "--dry-run"], writes: true },
1567
- { name: `${resource.name} delete`, args: ["id"], flags: ["--force", "--confirm-delete", "--dry-run"], writes: true, destructive: true }
1605
+ { name: `${resource.name} delete`, args: ["id"], flags: ["--force", "--confirm-delete", "--dry-run"], writes: true, destructive: false, softOnly: true }
1568
1606
  ])
1569
1607
  ],
1570
1608
  resources: resources.map((resource) => ({
@@ -1573,7 +1611,7 @@ var schemaHelp = () => ({
1573
1611
  defaultFields: resource.defaultFields,
1574
1612
  syncable: Boolean(resource.syncable),
1575
1613
  cacheScopes: resource.cacheScopes ?? [],
1576
- cacheNote: resource.cacheScopes?.length ? "After create/update/delete, visible deploy content may stay stale until these cache scopes are invalidated." : "No deploy-cache scope is listed for this raw resource. Still verify visible product state after writes."
1614
+ cacheNote: resource.cacheScopes?.length ? "After create/update/soft-delete, visible deploy content may stay stale until these cache scopes are invalidated." : "No deploy-cache scope is listed for this raw resource. Still verify visible product state after writes."
1577
1615
  }))
1578
1616
  });
1579
1617
  var authHelp = () => ({
@@ -1733,9 +1771,9 @@ var resourceHelp = (resource) => ({
1733
1771
  cache: {
1734
1772
  scopes: resource.cacheScopes ?? [],
1735
1773
  invalidate: resource.cacheScopes?.length ? `gskills-admin cache invalidate --instance <instanceId> --scope ${resource.cacheScopes[0]} --dry-run` : null,
1736
- note: resource.cacheScopes?.length ? "After create/update/delete, deploy views may still show cached content. Dry-run and invalidate the relevant scope, then verify the visible page." : "No deploy-cache scope is listed for this raw resource. If the write affects visible content indirectly, use cache scopes to choose a broader invalidation."
1774
+ note: resource.cacheScopes?.length ? "After create/update/soft-delete, deploy views may still show cached content. Dry-run and invalidate the relevant scope, then verify the visible page." : "No deploy-cache scope is listed for this raw resource. If the write affects visible content indirectly, use cache scopes to choose a broader invalidation."
1737
1775
  },
1738
- deleteWarning: "Delete permanently removes production data and requires an exact --confirm-delete token."
1776
+ deleteWarning: "Delete is soft-only in the CLI. It writes disabled, archived, isActive=false, or active=false when the resource supports it."
1739
1777
  });
1740
1778
 
1741
1779
  // ../../src/cli/gskills-admin.ts
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@numericoach/gskills-admin-cli",
3
- "version": "0.1.12",
3
+ "version": "0.1.14",
4
4
  "private": false,
5
5
  "type": "module",
6
6
  "description": "Admin-only CLI for GSkills super-admin operations.",
@@ -67,16 +67,16 @@ gskills-admin cache invalidate --instance <instanceId> --scope pages --dry-run -
67
67
  gskills-admin cache invalidate --instance <instanceId> --scope pages --yes --output json
68
68
  ```
69
69
 
70
- CRUD help exposes `cache.scopes` for resources that are known to feed deploy caches. After create, update, or 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.
70
+ 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
71
 
72
- Deletes are stricter than other writes. They require both `--force` and an exact confirmation token.
72
+ Delete commands are soft-only. They require both `--force` and an exact confirmation token, then write the safest inactive field available, such as `disabled: true`, `archived: true`, `isActive: false`, or `active: false`. If a resource cannot be safely disabled, the CLI refuses the delete command.
73
73
 
74
74
  ```bash
75
75
  gskills-admin pages delete <id> --force --confirm-delete pages:<id> --dry-run --output json
76
76
  gskills-admin pages delete <id> --force --confirm-delete pages:<id> --output json
77
77
  ```
78
78
 
79
- Never add `--confirm-delete` unless the user explicitly asked for a permanent deletion and the target row was read first.
79
+ Never add `--confirm-delete` unless the user explicitly asked to remove something from visibility and the target row was read first. The CLI must not permanently delete production data.
80
80
 
81
81
  CLI create, update, and delete operations are written to the GSkills admin logs with the authenticated user, entity snapshots, and CLI metadata. When Codex runs the CLI, the log metadata includes `actorType = "cli"` and `agent = "codex"`.
82
82
 
@@ -195,6 +195,8 @@ Use selectors for narrow syncs:
195
195
  gskills-admin sync run --target <instanceId> --pages <pageId,pageId> --languages fr,en --dry-run --output json
196
196
  ```
197
197
 
198
+ Language-limited menu sync writes are blocked from the CLI. Run the diff first, sync the language-limited content without `menus`, or sync menus without `--languages` after the backend non-destructive sync patch is deployed.
199
+
198
200
  Use `sync diff` before a real run when the user wants to inspect what would change. It uses the same shared diff-preview system as the super-admin sync UI.
199
201
 
200
202
  ```bash
@@ -519,8 +521,8 @@ Prefer the narrowest scope:
519
521
  ## Safety
520
522
 
521
523
  - Prefer `list` and `get` before writes
522
- - Use `--dry-run` before create, update, delete, and sync
523
- - Use `--force --confirm-delete <resource>:<id>` only for deletes the user explicitly requested
524
+ - Use `--dry-run` before create, update, soft-delete, and sync
525
+ - Use `--force --confirm-delete <resource>:<id>` only for soft-deletes the user explicitly requested
524
526
  - Use `sync diff` before `sync run --yes`
525
527
  - Use cache `--dry-run` before cache `--yes`
526
528
  - Re-read changed rows after writes