@numericoach/gskills-admin-cli 0.1.0

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 ADDED
@@ -0,0 +1,33 @@
1
+ # GSkills Admin CLI
2
+
3
+ Admin-only package for GSkills super-admin operations.
4
+
5
+ Super admin CLI for GSkills operations through authenticated app API routes.
6
+
7
+ The CLI opens GSkills in the browser, uses the normal GSkills login, then stores an opaque CLI token locally. Every API request re-checks `User.adminState = SUPER_ADMIN` in GSkills before touching data.
8
+
9
+ ## Local usage
10
+
11
+ ```bash
12
+ bun run gskills-admin auth login --base-url https://g-skills.fr
13
+ bun run gskills-admin auth whoami
14
+ bun run gskills-admin schema --output json
15
+ bun run gskills-admin pages list
16
+ bun run gskills-admin sync run --target <instanceId> --only pages,quizzes --yes
17
+ ```
18
+
19
+ Content-like resources default to `instanceId = "global"` when `--instance` is omitted.
20
+
21
+ ## Agent skill
22
+
23
+ Install the bundled skill so AI agents know the auth model, resource map, output modes, sync workflow, and content-authoring standards.
24
+
25
+ ```bash
26
+ gskills-admin skills install --target ~/.codex/skills
27
+ ```
28
+
29
+ ## Output
30
+
31
+ Use `--output json`, `--output jsonl`, `--output table`, or `--output markdown`.
32
+
33
+ Piped output defaults to JSON so agents and scripts can consume it safely.
@@ -0,0 +1,906 @@
1
+ #!/usr/bin/env node
2
+
3
+ // ../../src/cli/errors.ts
4
+ class CliError extends Error {
5
+ exitCode;
6
+ details;
7
+ constructor(message, exitCode = 1, details) {
8
+ super(message);
9
+ this.exitCode = exitCode;
10
+ this.details = details;
11
+ this.name = "CliError";
12
+ }
13
+ }
14
+ var isCliError = (error) => error instanceof CliError;
15
+
16
+ // ../../src/cli/output.ts
17
+ var normalizeValue = (value) => {
18
+ if (value instanceof Date)
19
+ return value.toISOString();
20
+ if (typeof value === "bigint")
21
+ return value.toString();
22
+ if (Array.isArray(value))
23
+ return value.map(normalizeValue);
24
+ if (!value || typeof value !== "object")
25
+ return value;
26
+ return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, normalizeValue(item)]));
27
+ };
28
+ var isTty = () => Boolean(process.stdout.isTTY);
29
+ var resolveOutputFormat = (format) => {
30
+ if (format !== "auto")
31
+ return format;
32
+ return isTty() ? "table" : "json";
33
+ };
34
+ var printResult = (value, options) => {
35
+ if (options.quiet)
36
+ return;
37
+ const normalized = normalizeValue(value);
38
+ const format = resolveOutputFormat(options.format);
39
+ if (format === "json") {
40
+ process.stdout.write(`${JSON.stringify(normalized, null, 2)}
41
+ `);
42
+ return;
43
+ }
44
+ if (format === "jsonl") {
45
+ if (Array.isArray(normalized)) {
46
+ for (const item of normalized) {
47
+ process.stdout.write(`${JSON.stringify(item)}
48
+ `);
49
+ }
50
+ } else {
51
+ process.stdout.write(`${JSON.stringify(normalized)}
52
+ `);
53
+ }
54
+ return;
55
+ }
56
+ if (format === "markdown") {
57
+ process.stdout.write(`${toMarkdown(normalized)}
58
+ `);
59
+ return;
60
+ }
61
+ process.stdout.write(`${toTable(normalized)}
62
+ `);
63
+ };
64
+ var toMarkdown = (value) => {
65
+ if (Array.isArray(value)) {
66
+ if (value.length === 0)
67
+ return "_No rows_";
68
+ return toMarkdownTable(value);
69
+ }
70
+ if (value && typeof value === "object") {
71
+ return Object.entries(value).map(([key, item]) => `- **${key}** ${formatScalar(item)}`).join(`
72
+ `);
73
+ }
74
+ return formatScalar(value);
75
+ };
76
+ var toTable = (value) => {
77
+ if (Array.isArray(value)) {
78
+ if (value.length === 0)
79
+ return "No rows";
80
+ return toPlainTable(value);
81
+ }
82
+ if (value && typeof value === "object") {
83
+ return Object.entries(value).map(([key, item]) => `${key.padEnd(22)} ${formatScalar(item)}`).join(`
84
+ `);
85
+ }
86
+ return formatScalar(value);
87
+ };
88
+ var toPlainTable = (rows) => {
89
+ const objects = rows.map((row) => row && typeof row === "object" ? row : { value: row });
90
+ const headers = Array.from(new Set(objects.flatMap((row) => Object.keys(row))));
91
+ const widths = headers.map((header) => Math.max(header.length, ...objects.map((row) => formatScalar(row[header]).length)));
92
+ const lines = [
93
+ headers.map((header, index) => header.padEnd(widths[index])).join(" "),
94
+ headers.map((header, index) => "-".repeat(Math.max(header.length, widths[index]))).join(" ")
95
+ ];
96
+ for (const row of objects) {
97
+ lines.push(headers.map((header, index) => formatScalar(row[header]).padEnd(widths[index])).join(" "));
98
+ }
99
+ return lines.join(`
100
+ `);
101
+ };
102
+ var toMarkdownTable = (rows) => {
103
+ const objects = rows.map((row) => row && typeof row === "object" ? row : { value: row });
104
+ const headers = Array.from(new Set(objects.flatMap((row) => Object.keys(row))));
105
+ const lines = [
106
+ `| ${headers.join(" | ")} |`,
107
+ `| ${headers.map(() => "---").join(" | ")} |`
108
+ ];
109
+ for (const row of objects) {
110
+ lines.push(`| ${headers.map((header) => formatScalar(row[header]).replaceAll("|", "\\|")).join(" | ")} |`);
111
+ }
112
+ return lines.join(`
113
+ `);
114
+ };
115
+ var formatScalar = (value) => {
116
+ if (value === null || value === undefined)
117
+ return "";
118
+ if (typeof value === "string")
119
+ return value;
120
+ if (typeof value === "number" || typeof value === "boolean" || typeof value === "bigint")
121
+ return String(value);
122
+ if (value instanceof Date)
123
+ return value.toISOString();
124
+ return JSON.stringify(normalizeValue(value));
125
+ };
126
+ var parseJsonObject = (value, label) => {
127
+ if (!value)
128
+ return {};
129
+ try {
130
+ const parsed = JSON.parse(value);
131
+ if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
132
+ throw new CliError(`${label} must be a JSON object`);
133
+ }
134
+ return parsed;
135
+ } catch (error) {
136
+ if (error instanceof CliError)
137
+ throw error;
138
+ throw new CliError(`Could not parse ${label} as JSON`, 2, { value });
139
+ }
140
+ };
141
+
142
+ // ../../src/cli/session.ts
143
+ import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
144
+ import { dirname, join } from "node:path";
145
+ import { homedir } from "node:os";
146
+ var sessionPath = () => process.env.GSKILLS_CLI_SESSION_PATH || join(homedir(), ".gskills-admin-cli", "session.json");
147
+ var readSession = async () => {
148
+ try {
149
+ const content = await readFile(sessionPath(), "utf8");
150
+ return JSON.parse(content);
151
+ } catch {
152
+ return null;
153
+ }
154
+ };
155
+ var writeSession = async (session) => {
156
+ const path = sessionPath();
157
+ await mkdir(dirname(path), { recursive: true });
158
+ await writeFile(path, JSON.stringify(session, null, 2), { mode: 384 });
159
+ return path;
160
+ };
161
+ var deleteSession = async () => {
162
+ await rm(sessionPath(), { force: true });
163
+ };
164
+ var getSessionPath = () => sessionPath();
165
+
166
+ // ../../src/cli/auth.ts
167
+ import { createServer } from "node:http";
168
+ import { execFile } from "node:child_process";
169
+ import { randomUUID } from "node:crypto";
170
+ import { promisify } from "node:util";
171
+ var execFileAsync = promisify(execFile);
172
+ var loginWithGSkills = async (input) => {
173
+ const baseUrl = normalizeBaseUrl(input.baseUrl);
174
+ const host = input.host ?? "127.0.0.1";
175
+ const state = randomUUID();
176
+ const callback = await waitForLocalCallback(host, input.port ?? 0, async (redirectUri) => {
177
+ const startUrl = new URL("/api/cli/auth/start", baseUrl);
178
+ startUrl.searchParams.set("redirect_uri", redirectUri);
179
+ startUrl.searchParams.set("state", state);
180
+ await openUrl(startUrl.toString());
181
+ process.stderr.write(`Opened ${startUrl.toString()}
182
+ `);
183
+ });
184
+ if (callback.state !== state) {
185
+ throw new CliError("GSkills auth state mismatch", 403);
186
+ }
187
+ const tokenResponse = await fetch(new URL("/api/cli/auth/token", baseUrl), {
188
+ method: "POST",
189
+ headers: {
190
+ accept: "application/json",
191
+ "content-type": "application/json"
192
+ },
193
+ body: JSON.stringify({
194
+ code: callback.code
195
+ })
196
+ });
197
+ const payload = await tokenResponse.json();
198
+ if (!tokenResponse.ok || !payload.token || !payload.user) {
199
+ throw new CliError(payload.error ?? "GSkills auth token exchange failed", tokenResponse.status || 1);
200
+ }
201
+ await writeSession({
202
+ mode: "gskills",
203
+ baseUrl,
204
+ token: payload.token,
205
+ createdAt: new Date().toISOString(),
206
+ user: payload.user
207
+ });
208
+ return {
209
+ authenticated: true,
210
+ baseUrl,
211
+ expiresAt: payload.expiresAt,
212
+ user: payload.user
213
+ };
214
+ };
215
+ var getApiSession = async () => {
216
+ const session = await readSession();
217
+ if (!session) {
218
+ throw new CliError("Not authenticated. Run gskills-admin auth login --base-url <gskills-url> first.", 401);
219
+ }
220
+ return session;
221
+ };
222
+ var whoami = async () => {
223
+ const session = await getApiSession();
224
+ const response = await fetch(new URL("/api/cli/auth/whoami", session.baseUrl), {
225
+ headers: {
226
+ accept: "application/json",
227
+ authorization: `Bearer ${session.token}`
228
+ }
229
+ });
230
+ const payload = await response.json();
231
+ if (!response.ok) {
232
+ throw new CliError(payload.error ?? "Could not verify CLI session", response.status);
233
+ }
234
+ return payload;
235
+ };
236
+ var waitForLocalCallback = async (host, port, onReady) => {
237
+ return new Promise((resolve, reject) => {
238
+ const server = createServer((request, response) => {
239
+ try {
240
+ const url = new URL(request.url ?? "/", `http://${host}`);
241
+ const code = url.searchParams.get("code");
242
+ const state = url.searchParams.get("state");
243
+ const error = url.searchParams.get("error");
244
+ if (error) {
245
+ response.writeHead(403, { "content-type": "text/plain" });
246
+ response.end(`GSkills CLI login failed: ${error}`);
247
+ server.close();
248
+ reject(new CliError(`GSkills CLI login failed: ${error}`, 403));
249
+ return;
250
+ }
251
+ if (!code || !state) {
252
+ response.writeHead(400, { "content-type": "text/plain" });
253
+ response.end("Missing GSkills CLI auth code.");
254
+ return;
255
+ }
256
+ response.writeHead(200, { "content-type": "text/plain" });
257
+ response.end("GSkills CLI login complete. You can close this tab.");
258
+ server.close();
259
+ resolve({ code, state });
260
+ } catch (error) {
261
+ reject(error);
262
+ }
263
+ });
264
+ server.on("error", reject);
265
+ server.listen(port, host, async () => {
266
+ try {
267
+ const address = server.address();
268
+ if (!address || typeof address === "string") {
269
+ reject(new CliError("Could not start local OAuth callback server"));
270
+ return;
271
+ }
272
+ const redirectUri = `http://${host}:${address.port}/callback`;
273
+ await onReady(redirectUri);
274
+ } catch (error) {
275
+ reject(error);
276
+ }
277
+ });
278
+ });
279
+ };
280
+ var normalizeBaseUrl = (value) => {
281
+ const url = new URL(value);
282
+ url.pathname = "";
283
+ url.search = "";
284
+ url.hash = "";
285
+ return url.toString().replace(/\/$/, "");
286
+ };
287
+ var openUrl = async (url) => {
288
+ const command = process.platform === "darwin" ? "open" : process.platform === "win32" ? "cmd" : "xdg-open";
289
+ const args = process.platform === "win32" ? ["/c", "start", "", url] : [url];
290
+ try {
291
+ await execFileAsync(command, args);
292
+ } catch {
293
+ process.stderr.write(`Could not open browser automatically. Use ${url}
294
+ `);
295
+ }
296
+ };
297
+
298
+ // ../../src/cli/api-client.ts
299
+ var requestApi = async (path, init = {}) => {
300
+ const session = await getApiSession();
301
+ const response = await fetch(new URL(path, session.baseUrl), {
302
+ ...init,
303
+ headers: {
304
+ accept: "application/json",
305
+ ...init.body ? { "content-type": "application/json" } : {},
306
+ ...init.headers ?? {},
307
+ authorization: `Bearer ${session.token}`
308
+ }
309
+ });
310
+ const payload = await response.json().catch(() => null);
311
+ if (!response.ok) {
312
+ throw new CliError(payload?.error ?? `GSkills API request failed with ${response.status}`, response.status);
313
+ }
314
+ return payload;
315
+ };
316
+
317
+ // ../../src/lib/cli/resources.ts
318
+ var resources = [
319
+ {
320
+ name: "pages",
321
+ delegate: "pages",
322
+ label: "Pages",
323
+ aliases: ["page", "content"],
324
+ defaultFields: ["id", "name", "slug", "language", "instanceId", "disabled", "archived", "alphaProgramIds", "updatedAt"],
325
+ syncable: true,
326
+ dangerousDelete: true
327
+ },
328
+ {
329
+ name: "topics",
330
+ delegate: "category_Application",
331
+ label: "Topics",
332
+ aliases: ["topic", "applications", "category-apps", "categories"],
333
+ defaultFields: ["id", "name", "slug", "language", "instanceId", "disabled", "archived", "alphaProgramIds", "updatedAt"],
334
+ syncable: true,
335
+ dangerousDelete: true
336
+ },
337
+ {
338
+ name: "resources",
339
+ delegate: "instanceResource",
340
+ label: "Resources",
341
+ aliases: ["resource", "ebooks", "e-books", "webinars", "magazines"],
342
+ defaultFields: ["id", "title", "type", "language", "instanceId", "isActive", "disabled", "archived", "alphaProgramIds", "updatedAt"],
343
+ syncable: true,
344
+ dangerousDelete: true
345
+ },
346
+ {
347
+ name: "internal-knowledge",
348
+ delegate: "instanceKnowledge",
349
+ label: "Internal knowledge",
350
+ aliases: ["knowledge", "knowledges"],
351
+ defaultFields: ["id", "title", "language", "instanceId", "isActive", "isAIAllowed", "disabled", "archived", "alphaProgramIds", "updatedAt"],
352
+ syncable: true,
353
+ dangerousDelete: true
354
+ },
355
+ {
356
+ name: "learning-paths",
357
+ delegate: "learningPath",
358
+ label: "Learning paths",
359
+ aliases: ["learning-path", "paths", "path"],
360
+ defaultFields: ["id", "name", "slug", "language", "instanceId", "isActive", "mandatory", "disabled", "archived", "alphaProgramIds", "updatedAt"],
361
+ syncable: true,
362
+ dangerousDelete: true
363
+ },
364
+ {
365
+ name: "changelogs",
366
+ delegate: "changelog",
367
+ label: "Changelogs",
368
+ aliases: ["changelog"],
369
+ defaultFields: ["id", "title", "slug", "target", "status", "language", "updatedAt"],
370
+ dangerousDelete: true
371
+ },
372
+ {
373
+ name: "project-data",
374
+ delegate: "instanceProjectData",
375
+ label: "Project data",
376
+ aliases: ["instance-project-data"],
377
+ defaultFields: ["id", "instanceId", "clientAdminEmail", "clientType", "goLiveAt", "updatedAt"]
378
+ },
379
+ {
380
+ name: "instances",
381
+ delegate: "instance",
382
+ label: "Instances",
383
+ aliases: ["instance"],
384
+ defaultFields: ["id", "name", "URL", "licenceType", "alphaProgramKeys", "createdAt", "updatedAt"],
385
+ dangerousDelete: true
386
+ },
387
+ {
388
+ name: "alpha-programs",
389
+ delegate: "alphaProgram",
390
+ label: "Alpha programs",
391
+ aliases: ["alpha", "alpha-program", "alphas"],
392
+ defaultFields: ["id", "key", "name", "provider", "status", "updatedAt"]
393
+ },
394
+ {
395
+ name: "quizzes",
396
+ delegate: "quiz",
397
+ label: "Quizzes",
398
+ aliases: ["quiz"],
399
+ defaultFields: ["id", "title", "language", "instanceId", "mandatory", "isActive", "disabled", "archived", "alphaProgramIds", "updatedAt"],
400
+ syncable: true,
401
+ dangerousDelete: true
402
+ },
403
+ {
404
+ name: "badges",
405
+ delegate: "badge",
406
+ label: "Badges",
407
+ aliases: ["badge"],
408
+ defaultFields: ["id", "name", "language", "instanceId", "disabled", "archived", "alphaProgramIds", "updatedAt"],
409
+ syncable: true,
410
+ dangerousDelete: true
411
+ },
412
+ {
413
+ name: "feedbacks",
414
+ delegate: "feedback",
415
+ label: "Feedbacks",
416
+ aliases: ["feedback"],
417
+ defaultFields: ["id", "instanceId", "userId", "type", "status", "priority", "createdAt", "updatedAt"]
418
+ },
419
+ {
420
+ name: "menus",
421
+ delegate: "menuItem",
422
+ label: "Menus",
423
+ aliases: ["menu", "menu-items"],
424
+ defaultFields: ["id", "name", "url", "pageId", "parentId", "instanceId", "disabled", "archived", "alphaProgramIds", "updatedAt"],
425
+ syncable: true,
426
+ dangerousDelete: true
427
+ },
428
+ {
429
+ name: "menu-sections",
430
+ delegate: "menuInstance",
431
+ label: "Menu sections",
432
+ aliases: ["menu-instances"],
433
+ defaultFields: ["id", "name", "order", "instanceId", "disabled", "archived", "alphaProgramIds"],
434
+ syncable: true,
435
+ dangerousDelete: true
436
+ },
437
+ {
438
+ name: "workflows",
439
+ delegate: "workflow",
440
+ label: "Workflows",
441
+ aliases: ["workflow"],
442
+ defaultFields: ["id", "name", "triggerType", "isActive", "instanceId", "disabled", "archived", "alphaProgramIds", "updatedAt"],
443
+ syncable: true,
444
+ dangerousDelete: true
445
+ },
446
+ {
447
+ name: "feature-flags",
448
+ delegate: "featureFlagAssignment",
449
+ label: "Feature flags",
450
+ aliases: ["feature-flag", "flags"],
451
+ defaultFields: ["id", "featureKey", "targetType", "targetId", "active", "variant", "updatedAt"]
452
+ },
453
+ {
454
+ name: "users",
455
+ delegate: "user",
456
+ label: "Users",
457
+ aliases: ["user"],
458
+ defaultFields: ["id", "email", "name", "adminState", "instanceID", "lastSeen", "updatedAt"]
459
+ },
460
+ {
461
+ name: "access-passes",
462
+ delegate: "accessPass",
463
+ label: "Access passes",
464
+ aliases: ["access-pass", "passes"],
465
+ defaultFields: ["id", "userId", "instanceId", "createdAt", "updatedAt"]
466
+ }
467
+ ];
468
+ var findResource = (name) => {
469
+ const normalized = name.trim().toLowerCase();
470
+ const match = resources.find((resource) => resource.name === normalized || resource.aliases.includes(normalized));
471
+ if (!match) {
472
+ throw new CliError(`Unknown resource "${name}"`, 2, {
473
+ available: resources.map((resource) => resource.name)
474
+ });
475
+ }
476
+ return match;
477
+ };
478
+ var resourceHelpRows = () => resources.map((resource) => ({
479
+ resource: resource.name,
480
+ db: resource.delegate,
481
+ sync: resource.syncable ? "yes" : "no",
482
+ aliases: resource.aliases.join(", ")
483
+ }));
484
+ // ../../src/cli/commands.ts
485
+ import { cp, mkdir as mkdir2, stat } from "node:fs/promises";
486
+ import { dirname as dirname2, join as join2 } from "node:path";
487
+ import { fileURLToPath } from "node:url";
488
+ var runCommand = async (ctx) => {
489
+ const [group, actionOrResource, maybeAction, ...rest] = ctx.args;
490
+ if (!group || group === "help")
491
+ return rootHelp();
492
+ if (group === "schema")
493
+ return schemaHelp();
494
+ if (group === "skills")
495
+ return runSkillsCommand(actionOrResource, ctx);
496
+ if (group === "auth")
497
+ return runAuthCommand(actionOrResource, ctx);
498
+ if (group === "resources")
499
+ return resourceHelpRows();
500
+ if (group === "sync")
501
+ return runSyncCommand(actionOrResource, ctx);
502
+ const resource = findResource(group);
503
+ return runResourceCommand(resource, actionOrResource, maybeAction, rest, ctx);
504
+ };
505
+ var runAuthCommand = async (action, ctx) => {
506
+ if (!action || action === "help")
507
+ return authHelp();
508
+ if (action === "login") {
509
+ const baseUrl = getStringFlag(ctx, "base-url") ?? process.env.GSKILLS_CLI_BASE_URL;
510
+ if (!baseUrl)
511
+ throw new CliError("Missing --base-url or GSKILLS_CLI_BASE_URL", 2);
512
+ return loginWithGSkills({
513
+ baseUrl,
514
+ host: getStringFlag(ctx, "host"),
515
+ port: getNumberFlag(ctx, "port")
516
+ });
517
+ }
518
+ if (action === "whoami")
519
+ return whoami();
520
+ if (action === "logout") {
521
+ const session = await readSession();
522
+ if (session) {
523
+ await fetch(new URL("/api/cli/auth/logout", session.baseUrl), {
524
+ method: "POST",
525
+ headers: {
526
+ accept: "application/json",
527
+ authorization: `Bearer ${session.token}`
528
+ }
529
+ }).catch(() => null);
530
+ }
531
+ await deleteSession();
532
+ return { authenticated: false, sessionPath: getSessionPath() };
533
+ }
534
+ throw new CliError(`Unknown auth command "${action}"`, 2);
535
+ };
536
+ var runResourceCommand = async (resource, action, maybeId, _rest, ctx) => {
537
+ if (!action || action === "help")
538
+ return resourceHelp(resource);
539
+ if (action === "list")
540
+ return listResource(resource, ctx);
541
+ if (action === "get") {
542
+ if (!maybeId)
543
+ throw new CliError(`Missing ${resource.name} id`, 2);
544
+ return requestApi(`/api/cli/${resource.name}/${maybeId}`);
545
+ }
546
+ if (action === "create")
547
+ return createResource(resource, ctx);
548
+ if (action === "update") {
549
+ if (!maybeId)
550
+ throw new CliError(`Missing ${resource.name} id`, 2);
551
+ return updateResource(resource, maybeId, ctx);
552
+ }
553
+ if (action === "delete") {
554
+ if (!maybeId)
555
+ throw new CliError(`Missing ${resource.name} id`, 2);
556
+ return deleteResource(resource, maybeId, ctx);
557
+ }
558
+ throw new CliError(`Unknown ${resource.name} command "${action}"`, 2);
559
+ };
560
+ var listResource = async (resource, ctx) => {
561
+ const searchParams = new URLSearchParams;
562
+ const where = parseJsonObject(getStringFlag(ctx, "where"), "--where");
563
+ const instanceId = getStringFlag(ctx, "instance") ?? defaultInstanceId(resource);
564
+ if (instanceId)
565
+ where.instanceId = instanceId;
566
+ searchParams.set("where", JSON.stringify(where));
567
+ searchParams.set("fields", getFields(resource, ctx).join(","));
568
+ searchParams.set("take", String(getNumberFlag(ctx, "take") ?? 25));
569
+ searchParams.set("skip", String(getNumberFlag(ctx, "skip") ?? 0));
570
+ const orderBy = getStringFlag(ctx, "order-by");
571
+ if (orderBy)
572
+ searchParams.set("orderBy", orderBy);
573
+ return requestApi(`/api/cli/${resource.name}?${searchParams.toString()}`);
574
+ };
575
+ var createResource = async (resource, ctx) => {
576
+ const data = parseJsonObject(getStringFlag(ctx, "data"), "--data");
577
+ const instanceId = getStringFlag(ctx, "instance") ?? defaultInstanceId(resource);
578
+ if (instanceId && data.instanceId === undefined)
579
+ data.instanceId = instanceId;
580
+ if (Object.keys(data).length === 0)
581
+ throw new CliError("Missing --data JSON", 2);
582
+ if (hasFlag(ctx, "dry-run"))
583
+ return { dryRun: true, resource: resource.name, data };
584
+ return requestApi(`/api/cli/${resource.name}`, {
585
+ method: "POST",
586
+ body: JSON.stringify({ data })
587
+ });
588
+ };
589
+ var updateResource = async (resource, id, ctx) => {
590
+ const data = parseJsonObject(getStringFlag(ctx, "data"), "--data");
591
+ if (Object.keys(data).length === 0)
592
+ throw new CliError("Missing --data JSON", 2);
593
+ if (hasFlag(ctx, "dry-run"))
594
+ return { dryRun: true, resource: resource.name, id, data };
595
+ return requestApi(`/api/cli/${resource.name}/${id}`, {
596
+ method: "PATCH",
597
+ body: JSON.stringify({ data })
598
+ });
599
+ };
600
+ var deleteResource = async (resource, id, ctx) => {
601
+ if (!hasFlag(ctx, "force")) {
602
+ throw new CliError("Delete requires --force", 2, { id, resource: resource.name });
603
+ }
604
+ if (hasFlag(ctx, "dry-run"))
605
+ return { dryRun: true, resource: resource.name, id, action: "delete" };
606
+ return requestApi(`/api/cli/${resource.name}/${id}`, { method: "DELETE" });
607
+ };
608
+ var runSyncCommand = async (action, ctx) => {
609
+ if (!action || action === "help")
610
+ return syncHelp();
611
+ if (action !== "run")
612
+ throw new CliError(`Unknown sync command "${action}"`, 2);
613
+ const targetInstanceId = getStringFlag(ctx, "target");
614
+ if (!targetInstanceId)
615
+ throw new CliError("Missing --target", 2);
616
+ if (!hasFlag(ctx, "yes") && !hasFlag(ctx, "dry-run")) {
617
+ throw new CliError("Sync writes DB data. Add --yes or use --dry-run.", 2);
618
+ }
619
+ const payload = {
620
+ sourceInstanceId: getStringFlag(ctx, "source") ?? "global",
621
+ targetInstanceId,
622
+ options: buildSyncOptions(ctx),
623
+ dryRun: hasFlag(ctx, "dry-run")
624
+ };
625
+ return requestApi("/api/cli/sync/run", {
626
+ method: "POST",
627
+ body: JSON.stringify(payload)
628
+ });
629
+ };
630
+ var runSkillsCommand = async (action, ctx) => {
631
+ if (!action || action === "help")
632
+ return skillsHelp();
633
+ if (action === "path")
634
+ return { path: await skillsSourceDir() };
635
+ if (action === "install") {
636
+ const target = getStringFlag(ctx, "target") ?? join2(process.cwd(), ".codex", "skills");
637
+ const destination = join2(target, "gskills-admin-cli");
638
+ await mkdir2(target, { recursive: true });
639
+ await cp(await skillsSourceDir(), destination, { recursive: true, force: true });
640
+ return { installed: true, destination };
641
+ }
642
+ throw new CliError(`Unknown skills command "${action}"`, 2);
643
+ };
644
+ var buildSyncOptions = (ctx) => {
645
+ const only = new Set(splitCsv(getStringFlag(ctx, "only")));
646
+ const hasOnly = only.size > 0;
647
+ const enabled = (key) => !hasOnly || only.has(key);
648
+ return {
649
+ languages: enabled("languages"),
650
+ categories: enabled("categories") || enabled("topics"),
651
+ pages: enabled("pages"),
652
+ pageVectors: enabled("pageVectors") || enabled("pages"),
653
+ menus: enabled("menus"),
654
+ quizzes: enabled("quizzes"),
655
+ learningPaths: enabled("learningPaths") || enabled("learning-paths"),
656
+ knowledge: enabled("knowledge") || enabled("internal-knowledge"),
657
+ knowledgeVectors: enabled("knowledgeVectors") || enabled("knowledge") || enabled("internal-knowledge"),
658
+ resources: enabled("resources"),
659
+ resourceVectors: enabled("resourceVectors") || enabled("resources"),
660
+ badges: enabled("badges"),
661
+ workflows: enabled("workflows"),
662
+ selectedPageIds: splitCsv(getStringFlag(ctx, "pages")),
663
+ selectedMenuItemIds: splitCsv(getStringFlag(ctx, "menus")),
664
+ selectedWorkflowIds: splitCsv(getStringFlag(ctx, "workflows")),
665
+ allowedLanguageCodes: splitCsv(getStringFlag(ctx, "languages")),
666
+ allowedApplicationIds: splitCsv(getStringFlag(ctx, "topic-ids")),
667
+ allowedApplicationNames: splitCsv(getStringFlag(ctx, "topics")),
668
+ allowedApplicationSlugs: splitCsv(getStringFlag(ctx, "topic-slugs")),
669
+ allowedPageSlugs: splitCsv(getStringFlag(ctx, "page-slugs")),
670
+ includeTagIds: splitCsv(getStringFlag(ctx, "include-tags")),
671
+ excludeTagIds: splitCsv(getStringFlag(ctx, "exclude-tags")),
672
+ updateReferences: !hasFlag(ctx, "no-update-references"),
673
+ fixDuplicates: !hasFlag(ctx, "no-fix-duplicates"),
674
+ quiet: hasFlag(ctx, "quiet"),
675
+ collectSummary: true
676
+ };
677
+ };
678
+ var getFields = (resource, ctx) => splitCsv(getStringFlag(ctx, "fields")).length > 0 ? splitCsv(getStringFlag(ctx, "fields")) : resource.defaultFields;
679
+ var splitCsv = (value) => value ? value.split(",").map((item) => item.trim()).filter(Boolean) : [];
680
+ var GLOBAL_DEFAULT_RESOURCES = new Set([
681
+ "pages",
682
+ "topics",
683
+ "resources",
684
+ "internal-knowledge",
685
+ "learning-paths",
686
+ "quizzes",
687
+ "badges",
688
+ "menus",
689
+ "menu-sections",
690
+ "workflows"
691
+ ]);
692
+ var defaultInstanceId = (resource) => GLOBAL_DEFAULT_RESOURCES.has(resource.name) ? "global" : undefined;
693
+ var skillsSourceDir = async () => {
694
+ const currentDir = dirname2(fileURLToPath(import.meta.url));
695
+ const candidates = [
696
+ join2(currentDir, "..", "skills", "gskills-admin-cli"),
697
+ join2(process.cwd(), "packages", "gskills-admin-cli", "skills", "gskills-admin-cli"),
698
+ join2(process.cwd(), ".codex", "skills", "gskills-admin-cli")
699
+ ];
700
+ for (const candidate of candidates) {
701
+ try {
702
+ if ((await stat(candidate)).isDirectory())
703
+ return candidate;
704
+ } catch {
705
+ continue;
706
+ }
707
+ }
708
+ throw new CliError("Bundled GSkills Admin CLI skill was not found", 1);
709
+ };
710
+ var hasFlag = (ctx, name) => ctx.flags[name] === true;
711
+ var getStringFlag = (ctx, name) => {
712
+ const value = ctx.flags[name];
713
+ if (Array.isArray(value))
714
+ return value[value.length - 1];
715
+ if (typeof value === "string")
716
+ return value;
717
+ return;
718
+ };
719
+ var getNumberFlag = (ctx, name) => {
720
+ const value = getStringFlag(ctx, name);
721
+ if (!value)
722
+ return;
723
+ const number = Number(value);
724
+ if (!Number.isFinite(number))
725
+ throw new CliError(`--${name} must be a number`, 2);
726
+ return number;
727
+ };
728
+ var rootHelp = () => ({
729
+ name: "gskills-admin",
730
+ description: "Super admin CLI for GSkills operations through authenticated API routes",
731
+ usage: [
732
+ "gskills-admin auth login --base-url https://g-skills.fr",
733
+ "gskills-admin auth whoami",
734
+ "gskills-admin pages list",
735
+ `gskills-admin pages update <id> --data '{"disabled":true}'`,
736
+ "gskills-admin sync run --target <instanceId> --only pages,quizzes --yes"
737
+ ],
738
+ resources: resources.map((resource) => resource.name),
739
+ output: "Use --output json, --output jsonl, --output table, or --output markdown. Piped output defaults to JSON.",
740
+ instanceDefault: "Content-like resources default to instanceId=global when --instance is omitted."
741
+ });
742
+ var schemaHelp = () => ({
743
+ name: "gskills-admin",
744
+ version: 1,
745
+ auth: {
746
+ type: "gskills-browser-token",
747
+ login: "gskills-admin auth login --base-url <url>",
748
+ header: "Authorization: Bearer <opaque-cli-token>",
749
+ authorization: "GSkills re-checks User.adminState = SUPER_ADMIN on every request"
750
+ },
751
+ globalFlags: [
752
+ { name: "output", values: ["json", "jsonl", "table", "markdown"], default: "auto" },
753
+ { name: "quiet", type: "boolean" }
754
+ ],
755
+ commands: [
756
+ { name: "auth login", required: ["--base-url"], writes: true },
757
+ { name: "auth whoami", writes: false },
758
+ { name: "auth logout", writes: true },
759
+ { name: "resources", writes: false },
760
+ { name: "schema", writes: false },
761
+ { name: "skills install", flags: ["--target"], writes: true },
762
+ { name: "sync run", required: ["--target"], safety: ["--yes or --dry-run"], writes: true },
763
+ ...resources.flatMap((resource) => [
764
+ { name: `${resource.name} list`, writes: false, flags: ["--where", "--fields", "--take", "--skip", "--order-by", "--instance"] },
765
+ { name: `${resource.name} get`, args: ["id"], writes: false },
766
+ { name: `${resource.name} create`, flags: ["--data", "--instance", "--dry-run"], writes: true },
767
+ { name: `${resource.name} update`, args: ["id"], flags: ["--data", "--dry-run"], writes: true },
768
+ { name: `${resource.name} delete`, args: ["id"], flags: ["--force", "--dry-run"], writes: true, destructive: true }
769
+ ])
770
+ ],
771
+ resources: resources.map((resource) => ({
772
+ name: resource.name,
773
+ aliases: resource.aliases,
774
+ defaultFields: resource.defaultFields,
775
+ syncable: Boolean(resource.syncable)
776
+ }))
777
+ });
778
+ var authHelp = () => ({
779
+ usage: [
780
+ "gskills-admin auth login --base-url https://g-skills.fr",
781
+ "gskills-admin auth whoami",
782
+ "gskills-admin auth logout"
783
+ ],
784
+ note: "The browser logs into GSkills. Every API request re-checks SUPER_ADMIN in GSkills before touching the DB."
785
+ });
786
+ var skillsHelp = () => ({
787
+ usage: [
788
+ "gskills-admin skills install",
789
+ "gskills-admin skills install --target ~/.codex/skills",
790
+ "gskills-admin skills path"
791
+ ],
792
+ defaultTarget: "./.codex/skills",
793
+ note: "Installs the bundled GSkills Admin CLI skill for AI agents."
794
+ });
795
+ var syncHelp = () => ({
796
+ usage: [
797
+ "gskills-admin sync run --target <instanceId> --yes",
798
+ "gskills-admin sync run --target <instanceId> --only pages,quizzes,learningPaths --pages <id,id> --languages fr,en --yes",
799
+ "gskills-admin sync run --target <instanceId> --dry-run"
800
+ ],
801
+ syncable: resources.filter((resource) => resource.syncable).map((resource) => resource.name),
802
+ sourceDefault: "global"
803
+ });
804
+ var resourceHelp = (resource) => ({
805
+ resource: resource.name,
806
+ label: resource.label,
807
+ aliases: resource.aliases,
808
+ usage: [
809
+ `gskills-admin ${resource.name} list --instance global`,
810
+ `gskills-admin ${resource.name} get <id>`,
811
+ `gskills-admin ${resource.name} create --data '{"instanceId":"global"}'`,
812
+ `gskills-admin ${resource.name} update <id> --data '{"disabled":true}'`,
813
+ `gskills-admin ${resource.name} delete <id> --force`
814
+ ],
815
+ defaultFields: resource.defaultFields
816
+ });
817
+
818
+ // ../../src/cli/gskills-admin.ts
819
+ var parseArgv = (argv) => {
820
+ const args = [];
821
+ const flags = {};
822
+ for (let index = 0;index < argv.length; index += 1) {
823
+ const token = argv[index];
824
+ if (!token.startsWith("--")) {
825
+ args.push(token);
826
+ continue;
827
+ }
828
+ const raw = token.slice(2);
829
+ const [name, inlineValue] = raw.split("=", 2);
830
+ const next = argv[index + 1];
831
+ const value = inlineValue ?? (next && !next.startsWith("--") ? next : true);
832
+ if (value === next)
833
+ index += 1;
834
+ const current = flags[name];
835
+ if (current === undefined) {
836
+ flags[name] = value;
837
+ } else if (Array.isArray(current)) {
838
+ current.push(String(value));
839
+ } else {
840
+ flags[name] = [String(current), String(value)];
841
+ }
842
+ }
843
+ if (flags.help || flags.h) {
844
+ if (args.length === 0)
845
+ args.push("help");
846
+ else
847
+ args.push("help");
848
+ }
849
+ return { args, flags };
850
+ };
851
+ var getOutputFormat = (ctx) => {
852
+ const value = ctx.flags.output ?? ctx.flags.o;
853
+ if (value === "json" || value === "jsonl" || value === "table" || value === "markdown")
854
+ return value;
855
+ if (value === undefined || value === true)
856
+ return "auto";
857
+ throw new Error("--output must be json, jsonl, table, or markdown");
858
+ };
859
+ var main = async () => {
860
+ const ctx = parseArgv(process.argv.slice(2));
861
+ const result = await runCommand(ctx);
862
+ printResult(result, {
863
+ format: getOutputFormat(ctx),
864
+ quiet: ctx.flags.quiet === true
865
+ });
866
+ };
867
+ main().catch((error) => {
868
+ const ctx = parseArgv(process.argv.slice(2));
869
+ const wantsStructuredError = ctx.flags.output === "json" || ctx.flags.output === "jsonl" || ctx.flags.json === true;
870
+ if (isCliError(error)) {
871
+ if (wantsStructuredError) {
872
+ process.stderr.write(`${JSON.stringify({
873
+ ok: false,
874
+ error: {
875
+ message: error.message,
876
+ code: error.exitCode,
877
+ details: error.details ?? null
878
+ }
879
+ }, null, 2)}
880
+ `);
881
+ } else {
882
+ process.stderr.write(`${error.message}
883
+ `);
884
+ if (error.details) {
885
+ process.stderr.write(`${JSON.stringify(error.details, null, 2)}
886
+ `);
887
+ }
888
+ }
889
+ process.exit(error.exitCode);
890
+ }
891
+ if (wantsStructuredError) {
892
+ process.stderr.write(`${JSON.stringify({
893
+ ok: false,
894
+ error: {
895
+ message: error instanceof Error ? error.message : String(error),
896
+ code: 1,
897
+ details: null
898
+ }
899
+ }, null, 2)}
900
+ `);
901
+ } else {
902
+ process.stderr.write(`${error instanceof Error ? error.stack ?? error.message : String(error)}
903
+ `);
904
+ }
905
+ process.exit(1);
906
+ });
package/package.json ADDED
@@ -0,0 +1,26 @@
1
+ {
2
+ "name": "@numericoach/gskills-admin-cli",
3
+ "version": "0.1.0",
4
+ "private": false,
5
+ "type": "module",
6
+ "description": "Admin-only CLI for GSkills super-admin operations.",
7
+ "publishConfig": {
8
+ "access": "public"
9
+ },
10
+ "bin": {
11
+ "gskills-admin": "dist/gskills-admin.js"
12
+ },
13
+ "files": [
14
+ "dist",
15
+ "skills",
16
+ "README.md"
17
+ ],
18
+ "scripts": {
19
+ "build": "bun scripts/build.ts",
20
+ "prepack": "bun run build"
21
+ },
22
+ "engines": {
23
+ "bun": ">=1.3.0",
24
+ "node": ">=20"
25
+ }
26
+ }
@@ -0,0 +1,153 @@
1
+ ---
2
+ name: gskills-admin-cli
3
+ description: Use when an AI agent needs to operate GSkills through the authenticated super-admin CLI, install the CLI skill, inspect schema, list or mutate content, sync global content to an instance, or create GSkills courses with the normal authoring standards.
4
+ ---
5
+
6
+ # GSkills Admin CLI
7
+
8
+ Use this skill when you need to operate GSkills as a super admin from an agent.
9
+
10
+ The CLI is intentionally boring. It logs in through GSkills Auth, calls GSkills API routes, and never asks an agent for a database URL.
11
+
12
+ ## Install
13
+
14
+ ```bash
15
+ bunx @numericoach/gskills-admin-cli auth login --base-url https://g-skills.fr
16
+ bunx @numericoach/gskills-admin-cli skills install --target ~/.codex/skills
17
+ ```
18
+
19
+ For local repo work:
20
+
21
+ ```bash
22
+ bun run gskills-admin auth login --base-url https://g-skills.fr
23
+ bun run gskills-admin skills install
24
+ ```
25
+
26
+ ## Agent Workflow
27
+
28
+ 1. Confirm auth.
29
+
30
+ ```bash
31
+ gskills-admin auth whoami --output json
32
+ ```
33
+
34
+ 2. Read the machine schema before acting.
35
+
36
+ ```bash
37
+ gskills-admin schema --output json
38
+ gskills-admin resources --output table
39
+ ```
40
+
41
+ 3. Use JSON for scripts and JSONL for pipelines.
42
+
43
+ ```bash
44
+ gskills-admin pages list --fields id,name,slug,language,instanceId --output json
45
+ gskills-admin pages list --take 100 --output jsonl
46
+ ```
47
+
48
+ 4. Dry-run writes first.
49
+
50
+ ```bash
51
+ gskills-admin pages create --data '{"name":"Draft","slug":"draft","language":"fr"}' --dry-run --output json
52
+ gskills-admin pages update <id> --data '{"disabled":false}' --dry-run --output json
53
+ ```
54
+
55
+ 5. Apply the exact same command without `--dry-run` only after the payload is correct.
56
+
57
+ ## Instance Rules
58
+
59
+ If `--instance` is omitted, content-like resources default to `instanceId = "global"`.
60
+
61
+ This applies to:
62
+
63
+ - `pages`
64
+ - `topics`
65
+ - `resources`
66
+ - `internal-knowledge`
67
+ - `learning-paths`
68
+ - `quizzes`
69
+ - `badges`
70
+ - `menus`
71
+ - `menu-sections`
72
+ - `workflows`
73
+
74
+ Still pass `--instance <instanceId>` when the user explicitly targets a client instance.
75
+
76
+ Never guess a client instance from a name if the CLI can list it:
77
+
78
+ ```bash
79
+ gskills-admin instances list --where '{"name":{"contains":"Air Liquide","mode":"insensitive"}}' --output json
80
+ ```
81
+
82
+ ## Auth Model
83
+
84
+ - Login happens in the browser on `https://g-skills.fr`
85
+ - The CLI stores only an opaque local token
86
+ - Every API call re-checks `User.adminState = SUPER_ADMIN`
87
+ - The CLI uses API routes, not direct database access
88
+ - Do not ask the user for `DATABASE_URL`
89
+
90
+ If `whoami` fails, stop and login again. Do not work around auth with copied browser sessions.
91
+
92
+ ## Content Authoring
93
+
94
+ Before creating or updating course content, inspect nearby examples.
95
+
96
+ Good GSkills content usually has:
97
+
98
+ - a concrete title and slug
99
+ - a short practical intro
100
+ - EditorJS blocks that match existing pages
101
+ - accordions for step-by-step instructions
102
+ - sections for bigger modules
103
+ - images only when they teach something
104
+ - quizzes when the page family uses quizzes
105
+ - a category connection
106
+ - a menu item under the right parent
107
+
108
+ For French content, write real French with accents. Avoid generic AI filler. Match the tone of the strongest current exemplar, not the most recent half-finished page.
109
+
110
+ Typical create flow:
111
+
112
+ ```bash
113
+ gskills-admin pages list --where '{"language":"fr","slug":{"contains":"gmail"}}' --fields id,name,slug,language,instanceId,contentType --output json
114
+ gskills-admin topics list --where '{"language":"fr"}' --fields id,name,slug,instanceId --output json
115
+ gskills-admin menus list --where '{"instanceId":"global"}' --fields id,name,parentId,pageId,url,instanceId --output json
116
+ gskills-admin pages create --data @page.json --dry-run --output json
117
+ gskills-admin pages create --data @page.json --output json
118
+ ```
119
+
120
+ 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.
121
+
122
+ ## Sync
123
+
124
+ Global is the source by default.
125
+
126
+ ```bash
127
+ gskills-admin sync run --target <instanceId> --only pages,quizzes,learningPaths --dry-run --output json
128
+ gskills-admin sync run --target <instanceId> --only pages,quizzes,learningPaths --yes --output json
129
+ ```
130
+
131
+ Use selectors for narrow syncs:
132
+
133
+ ```bash
134
+ gskills-admin sync run --target <instanceId> --pages <pageId,pageId> --languages fr,en --dry-run --output json
135
+ ```
136
+
137
+ ## Safety
138
+
139
+ - Prefer `list` and `get` before writes
140
+ - Use `--dry-run` before create, update, delete, and sync
141
+ - Use `--force` only for deletes the user explicitly requested
142
+ - Re-read changed rows after writes
143
+ - Keep output structured so another agent can parse it
144
+ - If production behavior matters, separate code state, deploy state, and data state
145
+
146
+ ## Good Agent Defaults
147
+
148
+ - `--output json` for decisions
149
+ - `--output table` for human scanning
150
+ - `--take 100` when inventory matters
151
+ - explicit `--fields` to avoid dumping huge content JSON
152
+ - explicit `--where` instead of fuzzy reasoning in prose
153
+ - no direct DB unless the user specifically asks for DB inspection or repair