@sortlist/cli 0.28.0 → 0.30.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/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@sortlist/cli",
3
- "version": "0.28.0",
3
+ "version": "0.30.0",
4
4
  "description": "Sortlist platform CLI — GraphQL federation client and Clara AI chat",
5
5
  "type": "module",
6
6
  "publishConfig": {
@@ -7,13 +7,18 @@
7
7
  */
8
8
  import { Command } from 'commander';
9
9
  import {
10
+ isEnumType,
10
11
  isInputObjectType,
11
12
  isInterfaceType,
12
13
  isListType,
13
14
  isNonNullType,
15
+ isObjectType,
16
+ isScalarType,
14
17
  isUnionType,
15
18
  type GraphQLArgument,
19
+ type GraphQLEnumType,
16
20
  type GraphQLField,
21
+ type GraphQLInputObjectType,
17
22
  type GraphQLInputType,
18
23
  type GraphQLNamedType,
19
24
  type GraphQLObjectType,
@@ -60,9 +65,14 @@ function ucfirst(s: string): string {
60
65
  * For mutations with a single `input` argument of an Input type,
61
66
  * return the fields of that input type for flattening into CLI options.
62
67
  */
63
- function getInputFields(
64
- field: GraphQLField<unknown, unknown>,
65
- ): { name: string; type: GraphQLArgument['type']; required: boolean }[] | null {
68
+ interface CliArg {
69
+ name: string;
70
+ type: GraphQLArgument['type'];
71
+ required: boolean;
72
+ description?: string | null;
73
+ }
74
+
75
+ function getInputFields(field: GraphQLField<unknown, unknown>): CliArg[] | null {
66
76
  if (field.args.length !== 1) return null;
67
77
  const arg = field.args[0];
68
78
  if (arg.name !== 'input') return null;
@@ -73,16 +83,184 @@ function getInputFields(
73
83
  name,
74
84
  type: f.type,
75
85
  required: isNonNullType(f.type),
86
+ description: f.description,
76
87
  }));
77
88
  }
78
89
 
79
- function coerceValue(raw: string, typeName: string): unknown {
90
+ /**
91
+ * Render a GraphQL type as its SDL signature, e.g. `String!`,
92
+ * `[OrganizationSortInput!]`, `OrganizationFilterInput`. Works for both input
93
+ * and output types (the wrapper structure is identical).
94
+ */
95
+ function renderType(type: GraphQLInputType | GraphQLOutputType): string {
96
+ if (isNonNullType(type)) return `${renderType(type.ofType as GraphQLInputType | GraphQLOutputType)}!`;
97
+ if (isListType(type)) return `[${renderType(type.ofType as GraphQLInputType | GraphQLOutputType)}]`;
98
+ return (type as GraphQLNamedType).name;
99
+ }
100
+
101
+ /**
102
+ * A "structured" arg is one that must be supplied as JSON on the CLI and parsed
103
+ * (rather than passed through as a raw string): lists and input objects. Plain
104
+ * leaf scalars and enums are passed as raw strings — including when wrapped in
105
+ * non-null (`String!` is still a bare string on the CLI). The non-null wrapper
106
+ * is transparent for this decision; a list at any level means JSON.
107
+ */
108
+ function isStructuredInput(type: GraphQLInputType): boolean {
109
+ if (isNonNullType(type)) return isStructuredInput(type.ofType as GraphQLInputType);
110
+ if (isListType(type)) return true;
111
+ return isInputObjectType(type);
112
+ }
113
+
114
+ /**
115
+ * Coerce a raw CLI string into the value GraphQL expects for the arg's type.
116
+ * Leaf scalars are parsed by name; structured types (input objects, lists,
117
+ * enums) are parsed as JSON. Throws a readable error on malformed JSON so the
118
+ * action can surface it instead of silently sending a bad string.
119
+ */
120
+ function coerceValue(raw: string, type: GraphQLInputType, flagName: string): unknown {
121
+ if (isStructuredInput(type)) {
122
+ try {
123
+ return JSON.parse(raw);
124
+ } catch (parseError) {
125
+ throw new Error(
126
+ `--${flagName} expects JSON for type ${renderType(type)}, but the value could not be parsed: ` +
127
+ `${(parseError as Error).message}`,
128
+ );
129
+ }
130
+ }
131
+
132
+ const typeName = unwrap(type).name;
80
133
  if (typeName === 'Int') return parseInt(raw, 10);
81
134
  if (typeName === 'Float') return parseFloat(raw);
82
135
  if (typeName === 'Boolean') return raw === 'true';
83
136
  return raw;
84
137
  }
85
138
 
139
+ /**
140
+ * One-line summary of an input-object or enum type's shape, used in option
141
+ * help so callers know what JSON to pass without a separate introspection
142
+ * round-trip. Expands a single level: `{ industry: StringFilterInput, country:
143
+ * String, ... }` for input objects, `one of: A | B | C` for enums.
144
+ */
145
+ function describeStructuredType(named: GraphQLNamedType): string | null {
146
+ if (isInputObjectType(named)) {
147
+ const fields = Object.values((named as GraphQLInputObjectType).getFields());
148
+ const parts = fields.map((f) => `${f.name}: ${renderType(f.type)}`);
149
+ return `{ ${parts.join(', ')} }`;
150
+ }
151
+ if (isEnumType(named)) {
152
+ const values = (named as GraphQLEnumType).getValues().map((v) => v.name);
153
+ return `one of: ${values.join(' | ')}`;
154
+ }
155
+ return null;
156
+ }
157
+
158
+ /** A named type worth pointing the user at via `sl schema inspect` — i.e. one with structure. */
159
+ function isInspectable(named: GraphQLNamedType): boolean {
160
+ return isInputObjectType(named) || isEnumType(named) || isObjectType(named);
161
+ }
162
+
163
+ function oneLineDescription(text: string | null | undefined): string {
164
+ return (text ?? '').replace(/\s+/g, ' ').trim();
165
+ }
166
+
167
+ /**
168
+ * Render a full, human-readable description of a named type for
169
+ * `sl schema inspect <Type>`: its kind, description, and one level of
170
+ * structure (object/input fields with their types + descriptions, or enum
171
+ * values). Nested structured types are named so the caller can `inspect` them
172
+ * in turn. Returns null if the type does not exist in the schema.
173
+ */
174
+ export function formatTypeInspection(schema: GraphQLSchema, typeName: string): string | null {
175
+ const named = schema.getType(typeName);
176
+ if (!named) return null;
177
+
178
+ const lines: string[] = [];
179
+ const suffix = oneLineDescription(named.description);
180
+ const header = (kind: string): string => {
181
+ const label = kind ? `${kind} ${named.name}` : named.name;
182
+ return suffix ? `${label} — ${suffix}` : label;
183
+ };
184
+
185
+ const pushFields = (entries: Array<{ name: string; typeSig: string; description?: string | null }>): void => {
186
+ const width = Math.max(...entries.map((entry) => `${entry.name}: ${entry.typeSig}`.length), 0);
187
+ for (const entry of entries) {
188
+ const signature = `${entry.name}: ${entry.typeSig}`;
189
+ const note = oneLineDescription(entry.description);
190
+ lines.push(note ? ` ${signature.padEnd(width)} ${note}` : ` ${signature}`);
191
+ }
192
+ };
193
+
194
+ if (isInputObjectType(named) || isObjectType(named)) {
195
+ lines.push(header(isInputObjectType(named) ? 'input' : 'type'));
196
+ pushFields(
197
+ Object.values(named.getFields()).map((f) => ({
198
+ name: f.name,
199
+ typeSig: renderType(f.type),
200
+ description: f.description,
201
+ })),
202
+ );
203
+ } else if (isEnumType(named)) {
204
+ lines.push(header('enum'));
205
+ for (const value of named.getValues()) {
206
+ const note = oneLineDescription(value.description);
207
+ lines.push(note ? ` ${value.name.padEnd(20)} ${note}` : ` ${value.name}`);
208
+ }
209
+ } else if (isScalarType(named)) {
210
+ lines.push(header('scalar'));
211
+ lines.push(' (scalar — pass a plain value)');
212
+ } else {
213
+ lines.push(header(''));
214
+ }
215
+
216
+ // Point the caller at the nested types they can drill into next.
217
+ const nested = new Set<string>();
218
+ if (isInputObjectType(named) || isObjectType(named)) {
219
+ for (const field of Object.values(named.getFields())) {
220
+ const fieldType = unwrap(field.type);
221
+ if (isInspectable(fieldType) && fieldType.name !== named.name) nested.add(fieldType.name);
222
+ }
223
+ }
224
+ if (nested.size > 0) {
225
+ lines.push('');
226
+ lines.push(
227
+ `Inspect nested types: ${[...nested]
228
+ .sort()
229
+ .map((n) => `sl schema inspect ${n}`)
230
+ .join(', ')}`,
231
+ );
232
+ }
233
+
234
+ return lines.join('\n');
235
+ }
236
+
237
+ /**
238
+ * Build the help description for a single CLI option from its GraphQL arg:
239
+ * the field description (if any), the rendered type with a `(JSON)` marker for
240
+ * structured inputs, and a one-level shape hint (input-object fields or enum
241
+ * values) so callers know what to pass without a separate introspection step.
242
+ */
243
+ function describeArg(arg: { name: string; type: GraphQLInputType; description?: string | null }): string {
244
+ const parts: string[] = [];
245
+ if (arg.description) parts.push(arg.description.replace(/\s+/g, ' ').trim());
246
+
247
+ const typeSig = renderType(arg.type);
248
+ parts.push(isStructuredInput(arg.type) ? `${typeSig} (JSON)` : typeSig);
249
+
250
+ // Shape hint applies to enums (raw string) and input objects (JSON) alike.
251
+ const named = unwrap(arg.type);
252
+ const shape = describeStructuredType(named);
253
+ if (shape) parts.push(shape);
254
+
255
+ // Point at `schema inspect` so nested input/enum types can be drilled into
256
+ // without resorting to raw introspection.
257
+ if (isInputObjectType(named) || isEnumType(named)) {
258
+ parts.push(`details: sl schema inspect ${named.name}`);
259
+ }
260
+
261
+ return parts.join(' — ');
262
+ }
263
+
86
264
  function buildCommand(
87
265
  schema: GraphQLSchema,
88
266
  fieldName: string,
@@ -97,12 +275,13 @@ function buildCommand(
97
275
 
98
276
  const inputFields = getInputFields(field);
99
277
  const useInputWrapper = inputFields != null;
100
- const cliArgs = useInputWrapper
278
+ const cliArgs: CliArg[] = useInputWrapper
101
279
  ? inputFields
102
280
  : field.args.map((a) => ({
103
281
  name: a.name,
104
282
  type: a.type,
105
283
  required: isNonNullType(a.type),
284
+ description: a.description,
106
285
  }));
107
286
 
108
287
  const cmd = new Command(kebab(fieldName)).description(description);
@@ -111,14 +290,15 @@ function buildCommand(
111
290
  const acceptsCompanySlug = cliArgs.some((a) => a.name === 'companySlug');
112
291
 
113
292
  for (const a of cliArgs) {
114
- const flag = `--${kebab(a.name)} <${a.name}>`;
293
+ const placeholder = isStructuredInput(a.type) ? 'json' : kebab(a.name);
294
+ const flag = `--${kebab(a.name)} <${placeholder}>`;
115
295
  const isContext = a.name in CONTEXT_FIELDS;
116
296
  if (isContext) {
117
- cmd.option(flag, `${a.name} (from context)`);
297
+ cmd.option(flag, `${describeArg(a)} (from context if omitted)`);
118
298
  } else if (a.required) {
119
- cmd.requiredOption(flag, a.name);
299
+ cmd.requiredOption(flag, describeArg(a));
120
300
  } else {
121
- cmd.option(flag, a.name);
301
+ cmd.option(flag, describeArg(a));
122
302
  }
123
303
  }
124
304
 
@@ -154,35 +334,27 @@ function buildCommand(
154
334
  opts.companyId = resolved;
155
335
  }
156
336
 
157
- let variables: Record<string, unknown>;
158
- if (useInputWrapper) {
159
- const input: Record<string, unknown> = {};
337
+ const collectArgs = (): Record<string, unknown> => {
338
+ const out: Record<string, unknown> = {};
160
339
  for (const a of cliArgs) {
161
340
  const raw = opts[a.name];
162
341
  const ctxProp = CONTEXT_FIELDS[a.name];
163
- const namedType = unwrap(a.type);
164
342
  if (raw != null) {
165
- input[a.name] = coerceValue(raw, namedType.name);
343
+ try {
344
+ out[a.name] = coerceValue(raw, a.type, kebab(a.name));
345
+ } catch (coerceError) {
346
+ error((coerceError as Error).message);
347
+ hint('Run the command with --help to see the expected shape of each argument.');
348
+ process.exit(2);
349
+ }
166
350
  } else if (ctxProp && ctx) {
167
- input[a.name] = (ctx as Record<string, unknown>)[ctxProp];
351
+ out[a.name] = (ctx as Record<string, unknown>)[ctxProp];
168
352
  }
169
353
  }
170
- variables = { input };
171
- } else if (cliArgs.length === 0) {
172
- variables = {};
173
- } else {
174
- variables = {};
175
- for (const a of cliArgs) {
176
- const raw = opts[a.name];
177
- const ctxProp = CONTEXT_FIELDS[a.name];
178
- const namedType = unwrap(a.type);
179
- if (raw != null) {
180
- variables[a.name] = coerceValue(raw, namedType.name);
181
- } else if (ctxProp && ctx) {
182
- variables[a.name] = (ctx as Record<string, unknown>)[ctxProp];
183
- }
184
- }
185
- }
354
+ return out;
355
+ };
356
+
357
+ const variables: Record<string, unknown> = useInputWrapper ? { input: collectArgs() } : collectArgs();
186
358
 
187
359
  const { query, fieldName: fName } = buildQuery(schema, kind, fieldName, variables, {
188
360
  depth: opts.depth,
@@ -253,6 +253,7 @@ export type ActivityKindEnum =
253
253
  | 'CRM_WRITE'
254
254
  | 'LEAD_SOURCED'
255
255
  | 'REPLY_RECEIVED'
256
+ | 'ROUTINE_CREATED'
256
257
  | 'ROUTINE_NOTE'
257
258
  | 'SIGNAL_CREATED'
258
259
  | 'SIGNAL_FIRED'
package/src/index.ts CHANGED
@@ -3,7 +3,7 @@ import { Command } from 'commander';
3
3
 
4
4
  // import { chatCommand } from './commands/chat/chat.ts';
5
5
  import { configCommand } from './commands/config.ts';
6
- import { buildServiceCommands } from './commands/dynamic.ts';
6
+ import { buildServiceCommands, formatTypeInspection } from './commands/dynamic.ts';
7
7
  import { loginCommand } from './commands/login.ts';
8
8
  import { logoutCommand } from './commands/logout.ts';
9
9
  import { offerCommand } from './commands/offer.ts';
@@ -120,6 +120,28 @@ schemaCommand
120
120
  }
121
121
  });
122
122
 
123
+ schemaCommand
124
+ .command('inspect <type>')
125
+ .description('Show the fields/values of a schema type (e.g. an input filter or enum)')
126
+ .action(async function (this: Command, typeName: string) {
127
+ const opts = this.optsWithGlobals();
128
+ try {
129
+ const { schema } = await getIntrospectedSchema(opts.endpoint);
130
+ const formatted = formatTypeInspection(schema, typeName);
131
+ if (!formatted) {
132
+ error(`No type named "${typeName}" in the schema.`);
133
+ hint('Type names are case-sensitive, e.g. `sl schema inspect OrganizationFilterInput`.');
134
+ hint('Find argument types in any command’s --help output.');
135
+ process.exit(1);
136
+ }
137
+ info(formatted);
138
+ } catch (err) {
139
+ error(`Could not read the schema: ${(err as Error).message}`);
140
+ hint('Check your network connection and endpoint: sl config show');
141
+ process.exit(1);
142
+ }
143
+ });
144
+
123
145
  program.addCommand(schemaCommand);
124
146
 
125
147
  // Parse --endpoint early so introspection uses the right URL