@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 +17 -31
- package/dist/index.js +81 -27
- package/dist/index.js.map +1 -1
- package/package.json +1 -1
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
|
-
|
|
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
|
|
77
|
-
|
|
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
|
-
|
|
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
|
|
125
|
-
sl operations --search
|
|
126
|
-
sl <operation> --help
|
|
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
|
|
133
|
-
sl
|
|
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(
|
|
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 &&
|
|
2008
|
-
hint(
|
|
2009
|
-
|
|
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
|
|
2053
|
-
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
2098
|
-
lines.push(` ${
|
|
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 (!
|
|
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
|
-
|
|
2786
|
-
sl operations
|
|
2787
|
-
sl operations --search
|
|
2788
|
-
sl <operation> --help
|
|
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
|
-
|
|
2843
|
-
|
|
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));
|