@sortlist/cli 0.35.0 → 0.37.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.
@@ -1,569 +0,0 @@
1
- /**
2
- * Dynamic command registration.
3
- *
4
- * Derives service grouping from the `@join__field(graph: ...)` directives
5
- * that the router injects into introspection responses, then builds
6
- * Commander.js commands at runtime.
7
- */
8
- import { Command } from 'commander';
9
- import {
10
- isEnumType,
11
- isInputObjectType,
12
- isInterfaceType,
13
- isListType,
14
- isNonNullType,
15
- isObjectType,
16
- isScalarType,
17
- isUnionType,
18
- type GraphQLArgument,
19
- type GraphQLEnumType,
20
- type GraphQLField,
21
- type GraphQLInputObjectType,
22
- type GraphQLInputType,
23
- type GraphQLNamedType,
24
- type GraphQLObjectType,
25
- type GraphQLOutputType,
26
- type GraphQLSchema,
27
- } from 'graphql';
28
-
29
- import { graphqlRaw } from '../graphql/client.ts';
30
- import { type FieldServiceMap } from '../graphql/introspection.ts';
31
- import { buildQuery } from '../graphql/query-builder.ts';
32
- import { resolveCompanyId } from '../lib/company.ts';
33
- import { getUserContext } from '../lib/config.ts';
34
- import { error, hint, printJson, warn } from '../lib/output.ts';
35
-
36
- // Context fields that are auto-injected from ~/.sortlist/config.json.
37
- // Schema field names (key) → UserContext property (value). The CLI is
38
- // company-scoped; marketplace fields like `agencyId` are NOT auto-filled
39
- // (Agency and Company are independent entities) and must be passed
40
- // explicitly via `--agency-id`.
41
- const CONTEXT_FIELDS: Record<string, string> = {
42
- companyId: 'companyId',
43
- oauthId: 'oauthId',
44
- };
45
-
46
- // Fields to skip — internal relay/federation helpers
47
- const SKIP_FIELDS = new Set(['node', 'nodes', 'id', '_entities', '_service']);
48
-
49
- function unwrap(type: GraphQLOutputType | GraphQLInputType): GraphQLNamedType {
50
- if (isNonNullType(type)) return unwrap(type.ofType as GraphQLOutputType | GraphQLInputType);
51
- if (isListType(type)) return unwrap(type.ofType as GraphQLOutputType | GraphQLInputType);
52
- return type as GraphQLNamedType;
53
- }
54
-
55
- function kebab(s: string): string {
56
- return s.replace(/([a-z])([A-Z])/g, '$1-$2').toLowerCase();
57
- }
58
-
59
- function ucfirst(s: string): string {
60
- return s.charAt(0).toUpperCase() + s.slice(1);
61
- }
62
-
63
- /**
64
- * For mutations with a single `input` argument of an Input type,
65
- * return the fields of that input type for flattening into CLI options.
66
- */
67
- interface CliArg {
68
- name: string;
69
- type: GraphQLArgument['type'];
70
- required: boolean;
71
- description?: string | null;
72
- }
73
-
74
- function getInputFields(field: GraphQLField<unknown, unknown>): CliArg[] | null {
75
- if (field.args.length !== 1) return null;
76
- const arg = field.args[0];
77
- if (arg.name !== 'input') return null;
78
- const argType = unwrap(arg.type);
79
- if (!argType || !isInputObjectType(argType)) return null;
80
- const fields = argType.getFields();
81
- return Object.entries(fields).map(([name, f]) => ({
82
- name,
83
- type: f.type,
84
- required: isNonNullType(f.type),
85
- description: f.description,
86
- }));
87
- }
88
-
89
- /**
90
- * Render a GraphQL type as its SDL signature, e.g. `String!`,
91
- * `[OrganizationSortInput!]`, `OrganizationFilterInput`. Works for both input
92
- * and output types (the wrapper structure is identical).
93
- */
94
- function renderType(type: GraphQLInputType | GraphQLOutputType): string {
95
- if (isNonNullType(type)) return `${renderType(type.ofType as GraphQLInputType | GraphQLOutputType)}!`;
96
- if (isListType(type)) return `[${renderType(type.ofType as GraphQLInputType | GraphQLOutputType)}]`;
97
- return (type as GraphQLNamedType).name;
98
- }
99
-
100
- /**
101
- * A "structured" arg is one that must be supplied as JSON on the CLI and parsed
102
- * (rather than passed through as a raw string): lists and input objects. Plain
103
- * leaf scalars and enums are passed as raw strings — including when wrapped in
104
- * non-null (`String!` is still a bare string on the CLI). The non-null wrapper
105
- * is transparent for this decision; a list at any level means JSON.
106
- */
107
- function isStructuredInput(type: GraphQLInputType): boolean {
108
- if (isNonNullType(type)) return isStructuredInput(type.ofType as GraphQLInputType);
109
- if (isListType(type)) return true;
110
- return isInputObjectType(type);
111
- }
112
-
113
- /**
114
- * Coerce a raw CLI string into the value GraphQL expects for the arg's type.
115
- * Leaf scalars are parsed by name; structured types (input objects, lists,
116
- * enums) are parsed as JSON. Throws a readable error on malformed JSON so the
117
- * action can surface it instead of silently sending a bad string.
118
- */
119
- function coerceValue(raw: string, type: GraphQLInputType, flagName: string): unknown {
120
- if (isStructuredInput(type)) {
121
- try {
122
- return JSON.parse(raw);
123
- } catch (parseError) {
124
- throw new Error(
125
- `--${flagName} expects JSON for type ${renderType(type)}, but the value could not be parsed: ` +
126
- `${(parseError as Error).message}`,
127
- );
128
- }
129
- }
130
-
131
- const typeName = unwrap(type).name;
132
- if (typeName === 'Int') {
133
- const parsed = parseInt(raw, 10);
134
- if (Number.isNaN(parsed)) throw new Error(`--${flagName} expects an integer, got "${raw}".`);
135
- return parsed;
136
- }
137
- if (typeName === 'Float') {
138
- const parsed = parseFloat(raw);
139
- if (Number.isNaN(parsed)) throw new Error(`--${flagName} expects a number, got "${raw}".`);
140
- return parsed;
141
- }
142
- if (typeName === 'Boolean') {
143
- if (raw !== 'true' && raw !== 'false') {
144
- throw new Error(`--${flagName} expects "true" or "false", got "${raw}".`);
145
- }
146
- return raw === 'true';
147
- }
148
- return raw;
149
- }
150
-
151
- /**
152
- * One-line summary of an input-object or enum type's shape, used in option
153
- * help so callers know what JSON to pass without a separate introspection
154
- * round-trip. Expands a single level: `{ industry: StringFilterInput, country:
155
- * String, ... }` for input objects, `one of: A | B | C` for enums.
156
- */
157
- function describeStructuredType(named: GraphQLNamedType): string | null {
158
- if (isInputObjectType(named)) {
159
- const fields = Object.values((named as GraphQLInputObjectType).getFields());
160
- const parts = fields.map((f) => `${f.name}: ${renderType(f.type)}`);
161
- return `{ ${parts.join(', ')} }`;
162
- }
163
- if (isEnumType(named)) {
164
- const values = (named as GraphQLEnumType).getValues().map((v) => v.name);
165
- return `one of: ${values.join(' | ')}`;
166
- }
167
- return null;
168
- }
169
-
170
- /** A named type worth pointing the user at via `sl schema inspect` — i.e. one with structure. */
171
- function isInspectable(named: GraphQLNamedType): boolean {
172
- return isInputObjectType(named) || isEnumType(named) || isObjectType(named);
173
- }
174
-
175
- function oneLineDescription(text: string | null | undefined): string {
176
- return (text ?? '').replace(/\s+/g, ' ').trim();
177
- }
178
-
179
- /**
180
- * Render a full, human-readable description of a named type for
181
- * `sl schema inspect <Type>`: its kind, description, and one level of
182
- * structure (object/input fields with their types + descriptions, or enum
183
- * values). Nested structured types are named so the caller can `inspect` them
184
- * in turn. Returns null if the type does not exist in the schema.
185
- */
186
- export function formatTypeInspection(schema: GraphQLSchema, typeName: string): string | null {
187
- const named = schema.getType(typeName);
188
- if (!named) return null;
189
-
190
- const lines: string[] = [];
191
- const suffix = oneLineDescription(named.description);
192
- const header = (kind: string): string => {
193
- const label = kind ? `${kind} ${named.name}` : named.name;
194
- return suffix ? `${label} — ${suffix}` : label;
195
- };
196
-
197
- const pushFields = (entries: Array<{ name: string; typeSig: string; description?: string | null }>): void => {
198
- const width = Math.max(...entries.map((entry) => `${entry.name}: ${entry.typeSig}`.length), 0);
199
- for (const entry of entries) {
200
- const signature = `${entry.name}: ${entry.typeSig}`;
201
- const note = oneLineDescription(entry.description);
202
- lines.push(note ? ` ${signature.padEnd(width)} ${note}` : ` ${signature}`);
203
- }
204
- };
205
-
206
- if (isInputObjectType(named) || isObjectType(named)) {
207
- lines.push(header(isInputObjectType(named) ? 'input' : 'type'));
208
- pushFields(
209
- Object.values(named.getFields()).map((f) => ({
210
- name: f.name,
211
- typeSig: renderType(f.type),
212
- description: f.description,
213
- })),
214
- );
215
- } else if (isEnumType(named)) {
216
- lines.push(header('enum'));
217
- for (const value of named.getValues()) {
218
- const note = oneLineDescription(value.description);
219
- lines.push(note ? ` ${value.name.padEnd(20)} ${note}` : ` ${value.name}`);
220
- }
221
- } else if (isScalarType(named)) {
222
- lines.push(header('scalar'));
223
- lines.push(' (scalar — pass a plain value)');
224
- } else {
225
- lines.push(header(''));
226
- }
227
-
228
- // Point the caller at the nested types they can drill into next.
229
- const nested = new Set<string>();
230
- if (isInputObjectType(named) || isObjectType(named)) {
231
- for (const field of Object.values(named.getFields())) {
232
- const fieldType = unwrap(field.type);
233
- if (isInspectable(fieldType) && fieldType.name !== named.name) nested.add(fieldType.name);
234
- }
235
- }
236
- if (nested.size > 0) {
237
- lines.push('');
238
- lines.push(
239
- `Inspect nested types: ${[...nested]
240
- .sort()
241
- .map((n) => `sl schema inspect ${n}`)
242
- .join(', ')}`,
243
- );
244
- }
245
-
246
- return lines.join('\n');
247
- }
248
-
249
- /**
250
- * Build the help description for a single CLI option from its GraphQL arg:
251
- * the field description (if any), the rendered type with a `(JSON)` marker for
252
- * structured inputs, and a one-level shape hint (input-object fields or enum
253
- * values) so callers know what to pass without a separate introspection step.
254
- */
255
- function describeArg(arg: { name: string; type: GraphQLInputType; description?: string | null }): string {
256
- const parts: string[] = [];
257
- if (arg.description) parts.push(arg.description.replace(/\s+/g, ' ').trim());
258
-
259
- const typeSig = renderType(arg.type);
260
- parts.push(isStructuredInput(arg.type) ? `${typeSig} (JSON)` : typeSig);
261
-
262
- // Shape hint applies to enums (raw string) and input objects (JSON) alike.
263
- const named = unwrap(arg.type);
264
- const shape = describeStructuredType(named);
265
- if (shape) parts.push(shape);
266
-
267
- // Point at `schema inspect` so nested input/enum types can be drilled into
268
- // without resorting to raw introspection.
269
- if (isInputObjectType(named) || isEnumType(named)) {
270
- parts.push(`details: sl schema inspect ${named.name}`);
271
- }
272
-
273
- return parts.join(' — ');
274
- }
275
-
276
- function buildCommand(
277
- schema: GraphQLSchema,
278
- fieldName: string,
279
- kind: 'query' | 'mutation',
280
- description: string,
281
- ): Command {
282
- const rootType = kind === 'query' ? schema.getQueryType() : schema.getMutationType();
283
- if (!rootType) throw new Error(`No ${kind} type in schema`);
284
-
285
- const field = rootType.getFields()[fieldName];
286
- if (!field) throw new Error(`Unknown ${kind} field: ${fieldName}`);
287
-
288
- const inputFields = getInputFields(field);
289
- const useInputWrapper = inputFields != null;
290
- const cliArgs: CliArg[] = useInputWrapper
291
- ? inputFields
292
- : field.args.map((a) => ({
293
- name: a.name,
294
- type: a.type,
295
- required: isNonNullType(a.type),
296
- description: a.description,
297
- }));
298
-
299
- const cmd = new Command(kebab(fieldName)).description(description);
300
-
301
- const acceptsCompanyId = cliArgs.some((a) => a.name === 'companyId');
302
-
303
- for (const a of cliArgs) {
304
- const placeholder = isStructuredInput(a.type) ? 'json' : kebab(a.name);
305
- const flag = `--${kebab(a.name)} <${placeholder}>`;
306
- const isContext = a.name in CONTEXT_FIELDS;
307
- if (isContext) {
308
- cmd.option(flag, `${describeArg(a)} (from context if omitted)`);
309
- } else if (a.required) {
310
- cmd.requiredOption(flag, describeArg(a));
311
- } else {
312
- cmd.option(flag, describeArg(a));
313
- }
314
- }
315
-
316
- cmd
317
- .option('--depth <depth>', 'Selection depth (default: 0)', parseInt)
318
- .option('--fields <fields>', 'Comma-separated fields to include')
319
- .option('--exclude <fields>', 'Comma-separated fields to exclude');
320
-
321
- cmd.action(async function (this: Command) {
322
- const opts = this.optsWithGlobals();
323
- const needsContext = cliArgs.some((a) => a.name in CONTEXT_FIELDS);
324
- const ctx = needsContext ? getUserContext() : undefined;
325
-
326
- if (acceptsCompanyId) {
327
- const resolved = resolveCompanyId({
328
- companyId: typeof opts.companyId === 'string' ? opts.companyId : undefined,
329
- ctx,
330
- });
331
- if (!resolved) {
332
- error('No company selected.');
333
- hint('Pass --company-id <id> or set one with `sl config set companyId <id>`.');
334
- process.exit(2);
335
- }
336
- opts.companyId = resolved;
337
- }
338
-
339
- const collectArgs = (): Record<string, unknown> => {
340
- const out: Record<string, unknown> = {};
341
- for (const a of cliArgs) {
342
- const raw = opts[a.name];
343
- const ctxProp = CONTEXT_FIELDS[a.name];
344
- if (raw != null) {
345
- try {
346
- out[a.name] = coerceValue(raw, a.type, kebab(a.name));
347
- } catch (coerceError) {
348
- error((coerceError as Error).message);
349
- hint('Run the command with --help to see the expected shape of each argument.');
350
- process.exit(2);
351
- }
352
- } else if (ctxProp && ctx) {
353
- out[a.name] = (ctx as Record<string, unknown>)[ctxProp];
354
- }
355
- }
356
- return out;
357
- };
358
-
359
- const variables: Record<string, unknown> = useInputWrapper ? { input: collectArgs() } : collectArgs();
360
-
361
- const { query, fieldName: fName } = buildQuery(schema, kind, fieldName, variables, {
362
- depth: opts.depth,
363
- fields: opts.fields?.split(','),
364
- exclude: opts.exclude?.split(','),
365
- });
366
- const data = await graphqlRaw(query, variables, { endpoint: opts.endpoint });
367
- const result = data[fName];
368
- if (result == null) {
369
- warn('No results returned.');
370
- hint('The query succeeded but the server returned null.');
371
- hint('Try different arguments or check that the resource exists.');
372
- } else {
373
- printJson(result);
374
- }
375
- });
376
-
377
- return cmd;
378
- }
379
-
380
- // ── Help formatting ──
381
-
382
- const useColor = process.stdout.isTTY && !process.env.NO_COLOR;
383
- const ansi = {
384
- reset: '\x1b[0m',
385
- bold: '\x1b[1m',
386
- dim: '\x1b[2m',
387
- cyan: '\x1b[36m',
388
- yellow: '\x1b[33m',
389
- };
390
-
391
- function formatCommandList(commands: Command[]): string {
392
- if (commands.length === 0) return '';
393
-
394
- const maxLen = Math.max(...commands.map((c) => c.name().length + (c.options.length > 0 ? 10 : 0)));
395
- const padWidth = Math.max(maxLen, 20);
396
-
397
- return commands
398
- .map((c) => {
399
- const name = c.options.length > 0 ? `${c.name()} [options]` : c.name();
400
- const desc = c.description();
401
- const padding = ' '.repeat(Math.max(2, padWidth - name.length + 2));
402
- if (desc) {
403
- return ` ${name}${padding}${desc}`;
404
- }
405
- const noDesc = useColor ? `${ansi.yellow}No description provided${ansi.reset}` : 'No description provided';
406
- return ` ${name}${padding}${noDesc}`;
407
- })
408
- .join('\n');
409
- }
410
-
411
- // ── Service map derivation ──
412
-
413
- interface ServiceEntry {
414
- queries: Array<{ fieldName: string; description: string }>;
415
- mutations: Array<{ fieldName: string; description: string }>;
416
- }
417
-
418
- /**
419
- * Derive the service → operations map from the `@join__field(graph: ...)`
420
- * directives the router exposes on each root field. Fields without a mapped
421
- * subgraph are skipped.
422
- */
423
- function deriveServiceMap(schema: GraphQLSchema, fieldServices: FieldServiceMap): Map<string, ServiceEntry> {
424
- const map = new Map<string, ServiceEntry>();
425
-
426
- function ensure(service: string): ServiceEntry {
427
- if (!map.has(service)) map.set(service, { queries: [], mutations: [] });
428
- return map.get(service)!;
429
- }
430
-
431
- const rootTypes: Array<{ kind: 'queries' | 'mutations'; type: GraphQLObjectType | null | undefined }> = [
432
- { kind: 'queries', type: schema.getQueryType() },
433
- { kind: 'mutations', type: schema.getMutationType() },
434
- ];
435
-
436
- for (const { kind, type } of rootTypes) {
437
- if (!type) continue;
438
- const services = fieldServices.get(type.name);
439
- if (!services) continue;
440
-
441
- for (const [fieldName, field] of Object.entries(type.getFields())) {
442
- if (SKIP_FIELDS.has(fieldName) || fieldName.startsWith('__')) continue;
443
-
444
- // Skip operations returning interfaces or unions
445
- const returnType = unwrap(field.type);
446
- if (isInterfaceType(returnType) || isUnionType(returnType)) continue;
447
-
448
- const service = services.get(fieldName);
449
- if (!service) continue;
450
-
451
- ensure(service)[kind].push({ fieldName, description: field.description ?? '' });
452
- }
453
- }
454
-
455
- // Sort fields alphabetically within each service
456
- for (const entry of map.values()) {
457
- entry.queries.sort((a, b) => a.fieldName.localeCompare(b.fieldName));
458
- entry.mutations.sort((a, b) => a.fieldName.localeCompare(b.fieldName));
459
- }
460
-
461
- return map;
462
- }
463
-
464
- /**
465
- * Short blurb shown after `sl <service>` in the root help. Services not listed
466
- * here fall back to `<Service> service operations`.
467
- */
468
- const SERVICE_DESCRIPTIONS: Record<string, string> = {
469
- atlas: 'Atlas service (contacts, orgs)',
470
- marketplace: 'Marketplace service',
471
- hermes: 'Hermes service',
472
- };
473
-
474
- function serviceDescription(service: string): string {
475
- return SERVICE_DESCRIPTIONS[service] ?? `${ucfirst(service)} service operations`;
476
- }
477
-
478
- export interface ServiceCommand {
479
- command: Command;
480
- /** First query name suitable for an example in the root help, or null. */
481
- exampleQuery: string | null;
482
- }
483
-
484
- /**
485
- * Build all service commands from the introspected schema.
486
- * Returns a map of service name → Commander Command + metadata for the root help.
487
- */
488
- export function buildServiceCommands(
489
- schema: GraphQLSchema,
490
- fieldServices: FieldServiceMap,
491
- ): Map<string, ServiceCommand> {
492
- const serviceMap = deriveServiceMap(schema, fieldServices);
493
- const commands = new Map<string, ServiceCommand>();
494
-
495
- // Track operation names to deduplicate (same name across query + mutation)
496
- const allNames = new Map<string, number>();
497
- for (const entry of serviceMap.values()) {
498
- for (const op of [...entry.queries, ...entry.mutations]) {
499
- allNames.set(op.fieldName, (allNames.get(op.fieldName) ?? 0) + 1);
500
- }
501
- }
502
-
503
- for (const [service, entry] of serviceMap) {
504
- const subCmd = new Command(service).description(serviceDescription(service));
505
-
506
- const queryCommands: Command[] = [];
507
- const mutationCommands: Command[] = [];
508
-
509
- for (const op of entry.queries) {
510
- try {
511
- const cmd = buildCommand(schema, op.fieldName, 'query', op.description);
512
- if ((allNames.get(op.fieldName) ?? 0) > 1) {
513
- cmd.name(`${kebab(op.fieldName)}-query`);
514
- }
515
- subCmd.addCommand(cmd, { hidden: true });
516
- queryCommands.push(cmd);
517
- } catch {
518
- // Field may not be resolvable — skip
519
- }
520
- }
521
-
522
- for (const op of entry.mutations) {
523
- try {
524
- const cmd = buildCommand(schema, op.fieldName, 'mutation', op.description);
525
- if ((allNames.get(op.fieldName) ?? 0) > 1) {
526
- cmd.name(`${kebab(op.fieldName)}-mutation`);
527
- }
528
- subCmd.addCommand(cmd, { hidden: true });
529
- mutationCommands.push(cmd);
530
- } catch {
531
- // Field may not be resolvable — skip
532
- }
533
- }
534
-
535
- // Custom help that groups queries and mutations
536
- subCmd.configureHelp({
537
- formatHelp: () => {
538
- const lines: string[] = [];
539
- lines.push(`Usage: sl ${service} [command] [options]\n`);
540
- lines.push(`${serviceDescription(service)}\n`);
541
-
542
- if (queryCommands.length > 0) {
543
- lines.push(`Queries:`);
544
- lines.push(formatCommandList(queryCommands));
545
- lines.push('');
546
- }
547
-
548
- if (mutationCommands.length > 0) {
549
- lines.push(`Mutations:`);
550
- lines.push(formatCommandList(mutationCommands));
551
- lines.push('');
552
- }
553
-
554
- lines.push(`Options:`);
555
- lines.push(` -h, --help display help for command\n`);
556
- return lines.join('\n');
557
- },
558
- });
559
-
560
- if (queryCommands.length > 0 || mutationCommands.length > 0) {
561
- commands.set(service, {
562
- command: subCmd,
563
- exampleQuery: queryCommands[0]?.name() ?? null,
564
- });
565
- }
566
- }
567
-
568
- return commands;
569
- }