@sortlist/cli 0.52.0 → 0.53.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 CHANGED
@@ -37,7 +37,7 @@ sl token # prints access token to stdout (useful for curl/scripts)
37
37
 
38
38
  ### When commands are missing
39
39
 
40
- The CLI builds its commands from the schema the federation router returns, and the router filters that schema by the scopes in your token. A service you hold no scope for therefore has **no commands at all** — `sl organizations` reports `unknown command`, not a permission error.
40
+ The CLI builds its commands from the schema the federation router returns, and the router filters that schema by the scopes in your token. A service you hold no scope for therefore has **no commands at all** — `sl atlas find-organizations` reports `unknown command`, not a permission error.
41
41
 
42
42
  `sl login` warns when a service came back with nothing:
43
43
 
@@ -65,36 +65,21 @@ A person can belong to several companies, and a subgraph that counts usage — A
65
65
 
66
66
  ```bash
67
67
  sl config set company spin42 # for every command from now on
68
- sl contacts --company spin42 … # for one call
68
+ sl atlas find-contacts --company spin42 … # for one call
69
69
  ```
70
70
 
71
71
  ## Revealing contact details
72
72
 
73
- Reading a contact shows only the reach details your company already owns — a name, an email, a phone, a LinkedIn profile each come back empty until revealed — and Atlas says so beside every row. Revealing is explicit, in the same command, with `--reveal`: a comma-separated list of dimensions named after the fields they unlock (`identity`, `emailAddress`, `phoneNumber`, `linkedinUrl`) or `all`. Whoever may read contacts may reveal them: nothing beyond `atlas/organization:read` is needed. Every Atlas command is checked with Hermes first: you must still be a member of the company you act for, or the application must belong to it, otherwise the whole command is refused with a 403 and nothing is recorded — the token's claim was stamped at login and can outlive a membership.
73
+ Finding a contact shows only the reach details your company already owns — a name, an email, a phone, a LinkedIn profile each come back empty until revealed — and Atlas says so beside every row. Revealing is explicit, in the same command, with `--reveal`: a comma-separated list of dimensions named after what they unlock (`contactIdentity`, `contactEmailAddress`, `contactPhoneNumber`, `contactLinkedinUrl`, and `organization…` for organizations). Whoever may read contacts may reveal them: nothing beyond `atlas/organization:read` is needed. Every Atlas command is checked with Hermes first: you must still be a member of the company you act for, or the application must belong to it, otherwise the whole command is refused with a 403 and nothing is recorded — the token's claim was stamped at login and can outlive a membership.
74
74
 
75
75
  ```bash
76
- sl contacts --first 5 --fields firstName,lastName,emailAddress # what you own
77
- sl contacts --first 5 --fields firstName,lastName,emailAddress --reveal identity,emailAddress # reveal, once per window
76
+ sl atlas find-contacts --page '{"first":5}' --wait \
77
+ --fields contacts.nodes.firstName,contacts.nodes.emailAddress # what you own
78
+ sl atlas find-contacts --page '{"first":5}' --wait --reveal contactIdentity,contactEmailAddress \
79
+ --fields contacts.nodes.firstName,contacts.nodes.emailAddress # reveal, once per window
78
80
  ```
79
81
 
80
- ```
81
- Q29udGFjdC8wMTllZGE0Mi1lYTAyLTc0YTAtYTgyMS0wZmIxNmUwNWQzZmY
82
- firstName Ada
83
- lastName Lovelace
84
- emailAddress ada@acme.com
85
- reveals CONTACT_IDENTITY REVEALED until 2026-12-11 23:59:59
86
- CONTACT_EMAIL_ADDRESS REVEALED until 2026-12-11 23:59:59
87
-
88
- credits
89
- held 2
90
- used 2
91
- byDimension CONTACT_IDENTITY 1
92
- CONTACT_EMAIL_ADDRESS 1
93
- ```
94
-
95
- Every row in a list is titled by its id, selected whether or not `--fields` names it, so a locked contact still has a handle to reveal it by. The `credits` block after the list is the bill of the command: `held` is the ceiling reserved before the page was read (rows × dimensions asked), `used` what it actually consumed, one unit per dimension revealed on one row; owned and unavailable cost nothing. Nothing is charged yet — these are the figures that would be.
96
-
97
- `OWNED` means the window is still running and nothing was counted again; `LOCKED` means Atlas has it and nobody asked; `UNAVAILABLE` means Atlas has nothing, and nothing is counted. Every list argument typed as an enum accepts the same shorthand.
82
+ The finds are searches: the mutation is acknowledged at once and the page arrives on a subscription, which `--wait` listens to. Atlas sends a page again as it fills it, and `--wait` prints its last, `COMPLETE`, version. Each edge's `reveals` says what happened to every dimension: `REVEALED` was recorded by this call, `OWNED` means the window is still running and nothing was counted again, `LOCKED` means Atlas has it and nobody asked, `UNAVAILABLE` means Atlas has nothing, and nothing is counted. The page's `credits` is the bill: `held` is the ceiling reserved before the page was read (rows × dimensions asked), `used` what it actually consumed, one unit per dimension revealed on one row. Nothing is charged yet — these are the figures that would be. Every list argument typed as an enum accepts the same comma-separated shorthand.
98
83
 
99
84
  ## Unattended authentication
100
85
 
@@ -118,19 +103,20 @@ The token endpoint is a different host from the federation endpoint, so it canno
118
103
 
119
104
  ## Federation operations
120
105
 
121
- Every query and mutation on the supergraph is available as a command, discovered at runtime through introspection. Operation names are unique across the supergraph, so they are **not** namespaced by subgraph:
106
+ The CLI offers an operation only when its subgraph tags the root field for it, with `@tag(name: "cli")` (`tags: [{ name: "cli" }]` on the Ruby field). Every other query, mutation and subscription stays reachable through the API, but has no command. Exposing one more is a backend change: tag the field, and the command appears within the hour, with no CLI release.
107
+
108
+ Commands are discovered at runtime through introspection and grouped under the subgraph that serves them. Hermes's account and company operations are the exception and stay at the top level, beside `login` and `config`:
122
109
 
123
110
  ```bash
124
- sl operations # list them all, grouped by queries and mutations
125
- sl operations --search company # filter by operation or subgraph name
126
- sl <operation> --help # flags for one operation
111
+ sl operations # list them all, grouped by queries, mutations and subscriptions
112
+ sl operations --search organization # filter by operation or subgraph name
113
+ sl <service> <operation> --help # flags for one operation
127
114
  ```
128
115
 
129
- They are hidden from the root help — listing seventy-odd entries there would bury the curated commands above — but they are ordinary top-level commands:
130
-
131
116
  ```bash
132
- sl organizations --first 5
133
- sl create-watcher --help
117
+ sl companies
118
+ sl atlas find-organizations --help
119
+ sl mercator resolve-locations --query brussels
134
120
  ```
135
121
 
136
122
  Output is JSON when piped or with `--json`, and aligned key/value blocks in a terminal. Ids are never truncated — they are what you paste into the next command — so records are printed as blocks rather than a table.
package/dist/index.js CHANGED
@@ -1759,6 +1759,14 @@ function isRecord2(value) {
1759
1759
  function isStillFilling(result) {
1760
1760
  return isRecord2(result) && result.status === "FILLING";
1761
1761
  }
1762
+ var PAGE_STATUS_FIELD = "status";
1763
+ function deliversFillingPages(schema, subscriptionName) {
1764
+ const field = schema.getSubscriptionType()?.getFields()[subscriptionName];
1765
+ const returnType = field ? unwrap2(field.type) : null;
1766
+ const status = returnType && isObjectType2(returnType) ? returnType.getFields()[PAGE_STATUS_FIELD] : void 0;
1767
+ const statusType = status ? unwrap2(status.type) : null;
1768
+ return Boolean(statusType && isEnumType2(statusType) && statusType.getValue("FILLING"));
1769
+ }
1762
1770
  function shellWord(value) {
1763
1771
  if (/^[\w.:/@=+-]+$/.test(value)) return value;
1764
1772
  return "'" + value.replace(/'/g, "'\\''") + "'";
@@ -1841,7 +1849,7 @@ function isDroppedStream(err) {
1841
1849
  const code = err.cause?.code;
1842
1850
  return err.message === "terminated" || code === "UND_ERR_SOCKET" || code === "ECONNRESET";
1843
1851
  }
1844
- function buildCommand(schema, fieldName, kind, description, service, resultSubscription) {
1852
+ function buildCommand(schema, fieldName, kind, description, service, resultSubscription, resultCommand) {
1845
1853
  const rootType = rootTypeOf(schema, kind);
1846
1854
  if (!rootType) throw new Error(`No ${kind} type in schema`);
1847
1855
  const field = rootType.getFields()[fieldName];
@@ -1962,6 +1970,9 @@ function buildCommand(schema, fieldName, kind, description, service, resultSubsc
1962
1970
  }
1963
1971
  const externalId = opts.externalId;
1964
1972
  const subscriptionVariables = { externalId };
1973
+ if (selection.fields && !selection.fields.includes(PAGE_STATUS_FIELD) && deliversFillingPages(schema, resultSubscription)) {
1974
+ selection.fields = [...selection.fields, PAGE_STATUS_FIELD];
1975
+ }
1965
1976
  const { query: subscriptionQuery, fieldName: subscriptionField } = build2(
1966
1977
  "subscription",
1967
1978
  resultSubscription,
@@ -1983,7 +1994,12 @@ function buildCommand(schema, fieldName, kind, description, service, resultSubsc
1983
1994
  printResult(resultSubscription, delivered, opts);
1984
1995
  const pageArgument = useInputWrapper ? variables.input.page : variables.page;
1985
1996
  const takesPage = cliArgs.some((a) => a.name === "page");
1986
- const pageHint = takesPage ? nextPageHint(this.name(), externalId, pageArgument, delivered) : null;
1997
+ const pageHint = takesPage ? nextPageHint(
1998
+ invocation(service, this.name()),
1999
+ externalId,
2000
+ pageArgument,
2001
+ delivered
2002
+ ) : null;
1987
2003
  if (pageHint) hint(pageHint);
1988
2004
  return;
1989
2005
  } catch (err) {
@@ -2004,10 +2020,10 @@ function buildCommand(schema, fieldName, kind, description, service, resultSubsc
2004
2020
  const { query, fieldName: fName } = build2(kind, fieldName, variables);
2005
2021
  const data = await graphqlRaw(query, variables, requestOptions);
2006
2022
  printResult(fieldName, data[fName], opts);
2007
- if (generatedExternalId && resultSubscription) {
2008
- hint(
2009
- `Its result arrives on ${kebab(resultSubscription)} --external-id ${String(opts.externalId)}, or pass --wait.`
2010
- );
2023
+ if (generatedExternalId && resultCommand) {
2024
+ hint(`Its result arrives on sl ${resultCommand} --external-id ${String(opts.externalId)}, or pass --wait.`);
2025
+ } else if (generatedExternalId && resultSubscription) {
2026
+ hint(`Its external id is ${String(opts.externalId)}. Pass --wait to receive its result.`);
2011
2027
  }
2012
2028
  });
2013
2029
  return cmd;
@@ -2045,17 +2061,43 @@ function deriveServiceMap(schema, fieldServices) {
2045
2061
  }
2046
2062
  return map;
2047
2063
  }
2064
+ var TOP_LEVEL_SERVICE = "hermes";
2065
+ function invocation(service, commandName) {
2066
+ return service === TOP_LEVEL_SERVICE ? commandName : `${service} ${commandName}`;
2067
+ }
2068
+ function invocationOf(operation) {
2069
+ return invocation(operation.service, operation.command.name());
2070
+ }
2071
+ function groupOperationCommands(operations) {
2072
+ const topLevel = [];
2073
+ const services = /* @__PURE__ */ new Map();
2074
+ for (const operation of operations) {
2075
+ if (operation.service === TOP_LEVEL_SERVICE) {
2076
+ topLevel.push(operation.command);
2077
+ continue;
2078
+ }
2079
+ let group = services.get(operation.service);
2080
+ if (!group) {
2081
+ group = new Command2(operation.service).description(`Operations served by ${operation.service}`);
2082
+ services.set(operation.service, group);
2083
+ }
2084
+ group.addCommand(operation.command);
2085
+ }
2086
+ return {
2087
+ topLevel,
2088
+ services: [...services.values()].sort((a, b) => a.name().localeCompare(b.name()))
2089
+ };
2090
+ }
2048
2091
  function buildOperationCommands(schema, fieldServices) {
2049
2092
  const serviceMap = deriveServiceMap(schema, fieldServices);
2050
2093
  const pairs = resultSubscriptions(schema);
2051
2094
  const operations = [];
2052
- const nameCounts = /* @__PURE__ */ new Map();
2053
- for (const entry of serviceMap.values()) {
2095
+ for (const [service, entry] of serviceMap) {
2096
+ const nameCounts = /* @__PURE__ */ new Map();
2054
2097
  for (const op of [...entry.queries, ...entry.mutations, ...entry.subscriptions]) {
2055
2098
  nameCounts.set(op.fieldName, (nameCounts.get(op.fieldName) ?? 0) + 1);
2056
2099
  }
2057
- }
2058
- for (const [service, entry] of serviceMap) {
2100
+ const exposedSubscriptions = new Set(entry.subscriptions.map((op) => op.fieldName));
2059
2101
  const kinds = [
2060
2102
  { kind: "query", ops: entry.queries },
2061
2103
  { kind: "mutation", ops: entry.mutations },
@@ -2065,7 +2107,8 @@ function buildOperationCommands(schema, fieldServices) {
2065
2107
  for (const op of ops) {
2066
2108
  try {
2067
2109
  const paired = kind === "mutation" ? pairs.get(op.fieldName) : void 0;
2068
- const command = buildCommand(schema, op.fieldName, kind, op.description, service, paired);
2110
+ const resultCommand = paired && exposedSubscriptions.has(paired) ? invocation(service, kebab(paired)) : void 0;
2111
+ const command = buildCommand(schema, op.fieldName, kind, op.description, service, paired, resultCommand);
2069
2112
  if ((nameCounts.get(op.fieldName) ?? 0) > 1) {
2070
2113
  command.name(`${kebab(op.fieldName)}-${kind}`);
2071
2114
  }
@@ -2079,9 +2122,9 @@ function buildOperationCommands(schema, fieldServices) {
2079
2122
  }
2080
2123
  function formatOperationList(operations, search) {
2081
2124
  const needle = search?.toLowerCase();
2082
- const matching = needle ? operations.filter((op) => op.command.name().includes(needle) || op.service.toLowerCase().includes(needle)) : operations;
2125
+ const matching = needle ? operations.filter((op) => invocationOf(op).includes(needle) || op.service.toLowerCase().includes(needle)) : operations;
2083
2126
  if (matching.length === 0) {
2084
- return search ? `No operation matching "${search}".` : "No operations available. The endpoint is not a composed supergraph, so no subgraph mapping is exposed.";
2127
+ return search ? `No operation matching "${search}".` : "No operation on this endpoint is exposed to the CLI.";
2085
2128
  }
2086
2129
  const lines = [];
2087
2130
  const headings = {
@@ -2092,10 +2135,12 @@ function formatOperationList(operations, search) {
2092
2135
  for (const kind of ["query", "mutation", "subscription"]) {
2093
2136
  const group = matching.filter((op) => op.kind === kind);
2094
2137
  if (group.length === 0) continue;
2095
- const width = Math.max(...group.map((op) => op.command.name().length));
2138
+ const rows = group.map((op) => ({ invocation: invocationOf(op), service: op.service }));
2139
+ rows.sort((a, b) => a.invocation.localeCompare(b.invocation));
2140
+ const width = Math.max(...rows.map((row) => row.invocation.length));
2096
2141
  lines.push(`${headings[kind]}:`);
2097
- for (const op of group) {
2098
- lines.push(` ${op.command.name().padEnd(width)} ${op.service}`);
2142
+ for (const row of rows) {
2143
+ lines.push(` ${row.invocation.padEnd(width)} ${row.service}`);
2099
2144
  }
2100
2145
  lines.push("");
2101
2146
  }
@@ -2604,6 +2649,12 @@ async function fetchIntrospection(endpoint, token) {
2604
2649
  }
2605
2650
  return { introspection: json.data, raw: json.data };
2606
2651
  }
2652
+ var CLI_TAG = "cli";
2653
+ function isTaggedForCli(field) {
2654
+ return field.appliedDirectives?.some(
2655
+ (d) => d.name === "tag" && d.args.some((a) => a.name === "name" && a.value === CLI_TAG)
2656
+ ) ?? false;
2657
+ }
2607
2658
  function parseIntrospection(raw) {
2608
2659
  const fieldServices = /* @__PURE__ */ new Map();
2609
2660
  const services = /* @__PURE__ */ new Set();
@@ -2616,7 +2667,8 @@ function parseIntrospection(raw) {
2616
2667
  const graphArg = directive.args.find((a) => a.name === "graph");
2617
2668
  if (!graphArg || typeof graphArg.value !== "string") continue;
2618
2669
  services.add(graphArg.value);
2619
- if (!fieldMap) fieldMap = /* @__PURE__ */ new Map();
2670
+ if (!isTaggedForCli(field)) continue;
2671
+ fieldMap ??= /* @__PURE__ */ new Map();
2620
2672
  fieldMap.set(field.name, graphArg.value);
2621
2673
  }
2622
2674
  if (fieldMap) fieldServices.set(type.name, fieldMap);
@@ -2781,15 +2833,13 @@ function buildRootDescription(operationCount) {
2781
2833
  const parts = [BASE_DESCRIPTION];
2782
2834
  if (operationCount > 0) {
2783
2835
  parts.push(
2784
- `Every federation operation is a command (${operationCount} available).
2785
- Operation names are unique across the supergraph, so they are not namespaced:
2786
- sl operations List them all
2787
- sl operations --search company
2788
- sl <operation> --help Flags for one operation`
2789
- );
2790
- parts.push(
2791
- "Examples:\n sl organizations --limit 5\n sl create-application --name continuous-integration\n sl config show"
2836
+ `Every federation operation exposed to the CLI is a command (${operationCount} available),
2837
+ grouped under the service that serves it. Account and company operations stay at the top level:
2838
+ sl operations List them all
2839
+ sl operations --search organization
2840
+ sl <service> <operation> --help Flags for one operation`
2792
2841
  );
2842
+ parts.push("Examples:\n sl companies\n sl atlas find-organizations --help\n sl config show");
2793
2843
  }
2794
2844
  return parts.join("\n\n");
2795
2845
  }
@@ -2839,8 +2889,12 @@ var endpointOverride = endpointIdx !== -1 ? process.argv[endpointIdx + 1] : void
2839
2889
  try {
2840
2890
  const { schema, fieldServices } = await getIntrospectedSchema(endpointOverride);
2841
2891
  const operations = buildOperationCommands(schema, fieldServices);
2842
- for (const operation of operations) {
2843
- program.addCommand(operation.command, { hidden: true });
2892
+ const { topLevel, services } = groupOperationCommands(operations);
2893
+ for (const command of topLevel) {
2894
+ program.addCommand(command, { hidden: true });
2895
+ }
2896
+ for (const command of services) {
2897
+ program.addCommand(command);
2844
2898
  }
2845
2899
  const operationsCommand = new Command8("operations").summary("List every federation operation available as a command").option("--search <text>", "Filter by operation or subgraph name").action(function() {
2846
2900
  info(formatOperationList(operations, this.opts().search));