@sortlist/cli 0.52.0 → 0.54.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
 
@@ -49,52 +49,41 @@ The cause is a role assignment in the tenant you logged into, not a CLI setting:
49
49
 
50
50
  ## Acting as an application locally
51
51
 
52
- `sl use application <id>` creates a credential, exchanges it for a token, and **revokes the credential immediately**. Nothing reusable is stored: what lands in `~/.sortlist/` is a bearer token that expires, and a subgraph verifies it by signature against Hermes' published keys rather than by asking whether the credential still lives.
52
+ `sl use application <application>` creates a credential, exchanges it for a token, and **revokes the credential immediately**. Nothing reusable is stored: what lands in `~/.sortlist/` is a bearer token that expires, and a subgraph verifies it by signature against Hermes' published keys rather than by asking whether the credential still lives.
53
53
 
54
54
  ```bash
55
- sl use application <id> # act as it for one token lifetime
56
- sl whoami # confirms: person or application
57
- sl use me # go back to acting as yourself
55
+ sl use application ci # by slug, in the company you act for (your personal one by default)
56
+ sl use application acme/ci # by slug, naming the company
57
+ sl use application <id> # by the application's id
58
+ sl whoami # confirms: person or application
59
+ sl use me # go back to acting as yourself
58
60
  ```
59
61
 
62
+ An application's slug is derived from its name when it is created (`Organization importer` → `organization-importer`) and stays the same if it is renamed. It is unique within its company, so two companies can each own a `ci`. `sl hermes applications` lists the applications of every company you belong to, with their slugs, and the developer portal shows both the slug and the id on the application's page.
63
+
60
64
  When the token expires, renewing needs your own login again — so this is a local convenience, never a path to unattended use. For that, see below.
61
65
 
62
66
  ## Acting for a company
63
67
 
64
- A person can belong to several companies, and a subgraph that counts usage — Atlas records which contact details it hands out — needs to know which one a call is for. Every authenticated request carries that company as an `X-Company-Id` header, taken from `--company` or from `sl config set company`. Both take the company's slug or its GraphQL `id`, as `sl companies` lists them; a slug costs one lookup per command, and a raw uuid is refused. The subgraph checks it against the companies your token lists and refuses the request outright when it names one you do not belong to. Without either, no company is named: a staff account is served without anything being counted, anyone else is refused until they pick one. An application belongs to exactly one company, so acting as one needs no header.
68
+ A person can belong to several companies, and a subgraph that counts usage — Atlas records which contact details it hands out — needs to know which one a call is for. Every authenticated request carries that company as an `X-Company-Id` header, taken from `--company` or from `sl config set company`. Both take the company's slug or its GraphQL `id`, as `sl hermes companies` lists them; a slug costs one lookup per command, and a raw uuid is refused. The subgraph checks it against the companies your token lists and refuses the request outright when it names one you do not belong to. Without either, no company is named, and Atlas refuses any person who names none, staff included; the CLI then retries the call once for your personal company, so that is where it is counted. An application belongs to exactly one company, so acting as one needs no header.
65
69
 
66
70
  ```bash
67
- sl config set company spin42 # for every command from now on
68
- sl contacts --company spin42 … # for one call
71
+ sl config set company acme # for every command from now on
72
+ sl atlas find-contacts --company acme … # for one call
69
73
  ```
70
74
 
71
75
  ## Revealing contact details
72
76
 
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.
77
+ 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). Finding and revealing need no scope, only a company to act for: a reveal made while acting for none is refused with `FORBIDDEN_COMPANY`, and `sl` retries it once on your personal company. Each reveal is charged to the company's credits. When you name a company, Atlas checks with Hermes first: you must still be a member of it, 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
78
 
75
79
  ```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
78
- ```
79
-
80
+ sl atlas find-contacts --page '{"first":5}' --wait \
81
+ --fields firstName,emailAddress # what you own
82
+ sl atlas find-contacts --page '{"first":5}' --wait --reveal contactIdentity,contactEmailAddress \
83
+ --fields firstName,emailAddress # reveal, once per window
80
84
  ```
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
85
 
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.
86
+ 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
87
 
99
88
  ## Unattended authentication
100
89
 
@@ -102,7 +91,7 @@ Every row in a list is titled by its id, selected whether or not `--fields` name
102
91
 
103
92
  ```bash
104
93
  # Create a credential — the secret is in the response and shown only once
105
- sl create-application-credential --application-id <id> --name continuous-integration
94
+ sl hermes create-application-credential --application-id <id> --name continuous-integration
106
95
 
107
96
  export SORTLIST_CLIENT_ID=slc_...
108
97
  export SORTLIST_CLIENT_SECRET=sl_live_...
@@ -112,25 +101,28 @@ With both set, **every** command authenticates as the application instead of as
112
101
 
113
102
  The secret is shown exactly once, because only its digest is stored. Revoking stops new tokens immediately; a token already issued stays valid until it expires.
114
103
 
115
- A credential carries the **platform's application scopes**, the same for every application and set by nobody: `atlas/organization:read`, which reads contacts and organizations and reveals them, metered on the application's company. Scopes are additive on this platform, so the token also reaches the baseline — Mercator's geography, the billing plan catalog — while Signals operations and every staff read stay out of reach. Hermes' own management API is **not** part of what a credential reaches: Hermes refuses the tokens it mints, which is what stops a leaked secret from minting more. The derivation is in `backend/hermes/docs/api.md` in the platform monorepo, under "What a minted token reaches".
104
+ A credential's token carries **no scope**. It reaches what a plain login does: Atlas's `find-contacts` and `find-organizations`, whose reveals are charged to the application's company, Mercator's geography and the billing plan catalog. The unmetered `contacts` and `organizations` lists, Signals operations and every staff read stay out of reach. Hermes' own management API is **not** part of what a credential reaches: Hermes refuses the tokens it mints, which is what stops a leaked secret from minting more. The derivation is in `backend/hermes/docs/api.md` in the platform monorepo, under "What a minted token reaches".
116
105
 
117
106
  The token endpoint is a different host from the federation endpoint, so it cannot be derived. `sl config use-production` / `use-staging` / `use-local` set both together; `sl config set tokenEndpoint <url>` sets it on its own.
118
107
 
119
108
  ## Federation operations
120
109
 
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:
110
+ 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.
111
+
112
+ Commands are discovered at runtime through introspection and grouped under the subgraph that serves them, Hermes's account and company operations included: `sl hermes companies`, `sl hermes applications`, `sl hermes create-application`. Every Hermes operation a person can call is offered. The names they had at the top level before (`sl companies`, `sl create-application-credential`) still work, but are no longer listed.
122
113
 
123
114
  ```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
115
+ sl operations # list them all, grouped by queries, mutations and subscriptions
116
+ sl operations --search organization # filter by operation or subgraph name
117
+ sl <service> <operation> --help # flags for one operation
127
118
  ```
128
119
 
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:
120
+ An operation whose subgraph declares a scope for it (`@requiresScopes`) is listed as `privileged: <scopes>`, and its `--help` opens with the same line. Everything else works with a plain login. The router hides a privileged operation from a token that lacks the scope, so it may be missing from the list rather than marked.
130
121
 
131
122
  ```bash
132
- sl organizations --first 5
133
- sl create-watcher --help
123
+ sl hermes companies
124
+ sl atlas find-organizations --help
125
+ sl mercator resolve-locations --query brussels
134
126
  ```
135
127
 
136
128
  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
@@ -447,7 +447,7 @@ async function lookupCompanyId(slug) {
447
447
  const id = data.company?.id;
448
448
  if (typeof id === "string") return id;
449
449
  error(`No company with slug "${slug}" among yours.`);
450
- hint("`sl companies` lists the companies you belong to, with their slugs and ids.");
450
+ hint("`sl hermes companies` lists the companies you belong to, with their slugs and ids.");
451
451
  process.exit(2);
452
452
  }
453
453
  async function resolveCompanyId(opts) {
@@ -701,6 +701,7 @@ function codeOf(errors) {
701
701
  }
702
702
  var UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
703
703
  var CALLBACK_STATUS_NOT_OK = "SUBGRAPH_HTTP_CALLBACK_STATUS_CODE_NOT_OK";
704
+ var FORBIDDEN_COMPANY = "FORBIDDEN_COMPANY";
704
705
  function subrequestStatus(errors) {
705
706
  for (const { message, extensions } of errors) {
706
707
  const http = extensions?.http;
@@ -780,7 +781,7 @@ function refusedForNamingNoCompany(errors, namedNoCompany) {
780
781
  if (!namedNoCompany) return false;
781
782
  const status = subrequestStatus(errors);
782
783
  const maskedCallbackRefusal = status === null && codeOf(errors) === CALLBACK_STATUS_NOT_OK;
783
- return status === 403 || maskedCallbackRefusal;
784
+ return status === 403 || maskedCallbackRefusal || codeOf(errors) === FORBIDDEN_COMPANY;
784
785
  }
785
786
  function hasResolvedField(data) {
786
787
  if (data === null || data === void 0) return false;
@@ -832,10 +833,10 @@ function reportGraphqlErrors(errors, options, attempt) {
832
833
  error(`${where} refused to act for your personal company.`);
833
834
  hint("It was tried because the request named no company, and your token does not list it as yours.");
834
835
  hint("On a local stack the token comes from a shared tenant and lists that environment's companies.");
835
- hint("Pass --company <slug|id>, or `sl config set company <slug|id>`; `sl companies` lists them.");
836
+ hint("Pass --company <slug|id>, or `sl config set company <slug|id>`; `sl hermes companies` lists them.");
836
837
  } else if (company && UUID.test(company)) {
837
838
  error(`${where} refused ${company}: that is a raw uuid, not a company id.`);
838
- hint("Pass its slug, or the id `sl companies` lists.");
839
+ hint("Pass its slug, or the id `sl hermes companies` lists.");
839
840
  } else if (company) {
840
841
  error(`${where} refused to act for company ${company}.`);
841
842
  hint("Your token does not list that company, or Hermes no longer knows you as one of its members.");
@@ -844,7 +845,7 @@ function reportGraphqlErrors(errors, options, attempt) {
844
845
  } else {
845
846
  error(`${where} refused this request: it names no company to act for.`);
846
847
  hint("Pick one of your companies with --company or `sl config set company <slug|id>`;");
847
- hint("`sl companies` lists them. Join one first if the list is empty.");
848
+ hint("`sl hermes companies` lists them. Join one first if the list is empty.");
848
849
  }
849
850
  if (verbose) for (const gqlError of errors) info(`[debug] ${JSON.stringify(gqlError)}`);
850
851
  process.exit(4);
@@ -1759,6 +1760,14 @@ function isRecord2(value) {
1759
1760
  function isStillFilling(result) {
1760
1761
  return isRecord2(result) && result.status === "FILLING";
1761
1762
  }
1763
+ var PAGE_STATUS_FIELD = "status";
1764
+ function deliversFillingPages(schema, subscriptionName) {
1765
+ const field = schema.getSubscriptionType()?.getFields()[subscriptionName];
1766
+ const returnType = field ? unwrap2(field.type) : null;
1767
+ const status = returnType && isObjectType2(returnType) ? returnType.getFields()[PAGE_STATUS_FIELD] : void 0;
1768
+ const statusType = status ? unwrap2(status.type) : null;
1769
+ return Boolean(statusType && isEnumType2(statusType) && statusType.getValue("FILLING"));
1770
+ }
1762
1771
  function shellWord(value) {
1763
1772
  if (/^[\w.:/@=+-]+$/.test(value)) return value;
1764
1773
  return "'" + value.replace(/'/g, "'\\''") + "'";
@@ -1841,7 +1850,7 @@ function isDroppedStream(err) {
1841
1850
  const code = err.cause?.code;
1842
1851
  return err.message === "terminated" || code === "UND_ERR_SOCKET" || code === "ECONNRESET";
1843
1852
  }
1844
- function buildCommand(schema, fieldName, kind, description, service, resultSubscription) {
1853
+ function buildCommand(schema, fieldName, kind, description, service, resultSubscription, resultCommand) {
1845
1854
  const rootType = rootTypeOf(schema, kind);
1846
1855
  if (!rootType) throw new Error(`No ${kind} type in schema`);
1847
1856
  const field = rootType.getFields()[fieldName];
@@ -1962,6 +1971,9 @@ function buildCommand(schema, fieldName, kind, description, service, resultSubsc
1962
1971
  }
1963
1972
  const externalId = opts.externalId;
1964
1973
  const subscriptionVariables = { externalId };
1974
+ if (selection.fields && !selection.fields.includes(PAGE_STATUS_FIELD) && deliversFillingPages(schema, resultSubscription)) {
1975
+ selection.fields = [...selection.fields, PAGE_STATUS_FIELD];
1976
+ }
1965
1977
  const { query: subscriptionQuery, fieldName: subscriptionField } = build2(
1966
1978
  "subscription",
1967
1979
  resultSubscription,
@@ -1983,7 +1995,12 @@ function buildCommand(schema, fieldName, kind, description, service, resultSubsc
1983
1995
  printResult(resultSubscription, delivered, opts);
1984
1996
  const pageArgument = useInputWrapper ? variables.input.page : variables.page;
1985
1997
  const takesPage = cliArgs.some((a) => a.name === "page");
1986
- const pageHint = takesPage ? nextPageHint(this.name(), externalId, pageArgument, delivered) : null;
1998
+ const pageHint = takesPage ? nextPageHint(
1999
+ invocation(service, this.name()),
2000
+ externalId,
2001
+ pageArgument,
2002
+ delivered
2003
+ ) : null;
1987
2004
  if (pageHint) hint(pageHint);
1988
2005
  return;
1989
2006
  } catch (err) {
@@ -2004,10 +2021,10 @@ function buildCommand(schema, fieldName, kind, description, service, resultSubsc
2004
2021
  const { query, fieldName: fName } = build2(kind, fieldName, variables);
2005
2022
  const data = await graphqlRaw(query, variables, requestOptions);
2006
2023
  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
- );
2024
+ if (generatedExternalId && resultCommand) {
2025
+ hint(`Its result arrives on sl ${resultCommand} --external-id ${String(opts.externalId)}, or pass --wait.`);
2026
+ } else if (generatedExternalId && resultSubscription) {
2027
+ hint(`Its external id is ${String(opts.externalId)}. Pass --wait to receive its result.`);
2011
2028
  }
2012
2029
  });
2013
2030
  return cmd;
@@ -2045,17 +2062,46 @@ function deriveServiceMap(schema, fieldServices) {
2045
2062
  }
2046
2063
  return map;
2047
2064
  }
2048
- function buildOperationCommands(schema, fieldServices) {
2065
+ function describeScopes(scopes) {
2066
+ return scopes.map((alternative) => alternative.join(" + ")).join(" or ");
2067
+ }
2068
+ var LEGACY_TOP_LEVEL_SERVICE = "hermes";
2069
+ function invocation(service, commandName) {
2070
+ return `${service} ${commandName}`;
2071
+ }
2072
+ function invocationOf(operation) {
2073
+ return invocation(operation.service, operation.command.name());
2074
+ }
2075
+ function groupOperationCommands(operations) {
2076
+ const services = /* @__PURE__ */ new Map();
2077
+ for (const operation of operations) {
2078
+ let group = services.get(operation.service);
2079
+ if (!group) {
2080
+ group = new Command2(operation.service).description(`Operations served by ${operation.service}`);
2081
+ services.set(operation.service, group);
2082
+ }
2083
+ group.addCommand(operation.command);
2084
+ }
2085
+ return [...services.values()].sort((a, b) => a.name().localeCompare(b.name()));
2086
+ }
2087
+ function legacyTopLevelCommands(schema, fieldServices, fieldScopes = /* @__PURE__ */ new Map()) {
2088
+ return buildOperationCommands(schema, fieldServices, fieldScopes).filter((operation) => operation.service === LEGACY_TOP_LEVEL_SERVICE).map((operation) => operation.command);
2089
+ }
2090
+ function buildOperationCommands(schema, fieldServices, fieldScopes = /* @__PURE__ */ new Map()) {
2049
2091
  const serviceMap = deriveServiceMap(schema, fieldServices);
2092
+ const rootTypeNames = {
2093
+ query: schema.getQueryType()?.name,
2094
+ mutation: schema.getMutationType()?.name,
2095
+ subscription: schema.getSubscriptionType()?.name
2096
+ };
2050
2097
  const pairs = resultSubscriptions(schema);
2051
2098
  const operations = [];
2052
- const nameCounts = /* @__PURE__ */ new Map();
2053
- for (const entry of serviceMap.values()) {
2099
+ for (const [service, entry] of serviceMap) {
2100
+ const nameCounts = /* @__PURE__ */ new Map();
2054
2101
  for (const op of [...entry.queries, ...entry.mutations, ...entry.subscriptions]) {
2055
2102
  nameCounts.set(op.fieldName, (nameCounts.get(op.fieldName) ?? 0) + 1);
2056
2103
  }
2057
- }
2058
- for (const [service, entry] of serviceMap) {
2104
+ const exposedSubscriptions = new Set(entry.subscriptions.map((op) => op.fieldName));
2059
2105
  const kinds = [
2060
2106
  { kind: "query", ops: entry.queries },
2061
2107
  { kind: "mutation", ops: entry.mutations },
@@ -2065,11 +2111,19 @@ function buildOperationCommands(schema, fieldServices) {
2065
2111
  for (const op of ops) {
2066
2112
  try {
2067
2113
  const paired = kind === "mutation" ? pairs.get(op.fieldName) : void 0;
2068
- const command = buildCommand(schema, op.fieldName, kind, op.description, service, paired);
2114
+ const resultCommand = paired && exposedSubscriptions.has(paired) ? invocation(service, kebab(paired)) : void 0;
2115
+ const command = buildCommand(schema, op.fieldName, kind, op.description, service, paired, resultCommand);
2069
2116
  if ((nameCounts.get(op.fieldName) ?? 0) > 1) {
2070
2117
  command.name(`${kebab(op.fieldName)}-${kind}`);
2071
2118
  }
2072
- operations.push({ command, fieldName: op.fieldName, kind, service });
2119
+ const rootTypeName = rootTypeNames[kind];
2120
+ const scopes = rootTypeName ? fieldScopes.get(rootTypeName)?.get(op.fieldName) : void 0;
2121
+ if (scopes) {
2122
+ command.description(`Privileged: requires ${describeScopes(scopes)}.
2123
+
2124
+ ${command.description()}`);
2125
+ }
2126
+ operations.push({ command, fieldName: op.fieldName, kind, service, ...scopes ? { scopes } : {} });
2073
2127
  } catch {
2074
2128
  }
2075
2129
  }
@@ -2079,9 +2133,9 @@ function buildOperationCommands(schema, fieldServices) {
2079
2133
  }
2080
2134
  function formatOperationList(operations, search) {
2081
2135
  const needle = search?.toLowerCase();
2082
- const matching = needle ? operations.filter((op) => op.command.name().includes(needle) || op.service.toLowerCase().includes(needle)) : operations;
2136
+ const matching = needle ? operations.filter((op) => invocationOf(op).includes(needle) || op.service.toLowerCase().includes(needle)) : operations;
2083
2137
  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.";
2138
+ return search ? `No operation matching "${search}".` : "No operation on this endpoint is exposed to the CLI.";
2085
2139
  }
2086
2140
  const lines = [];
2087
2141
  const headings = {
@@ -2092,10 +2146,17 @@ function formatOperationList(operations, search) {
2092
2146
  for (const kind of ["query", "mutation", "subscription"]) {
2093
2147
  const group = matching.filter((op) => op.kind === kind);
2094
2148
  if (group.length === 0) continue;
2095
- const width = Math.max(...group.map((op) => op.command.name().length));
2149
+ const rows = group.map((op) => ({
2150
+ invocation: invocationOf(op),
2151
+ service: op.service,
2152
+ privilege: op.scopes ? `privileged: ${describeScopes(op.scopes)}` : ""
2153
+ }));
2154
+ rows.sort((a, b) => a.invocation.localeCompare(b.invocation));
2155
+ const width = Math.max(...rows.map((row) => row.invocation.length));
2156
+ const serviceWidth = Math.max(...rows.map((row) => row.service.length));
2096
2157
  lines.push(`${headings[kind]}:`);
2097
- for (const op of group) {
2098
- lines.push(` ${op.command.name().padEnd(width)} ${op.service}`);
2158
+ for (const row of rows) {
2159
+ lines.push(` ${row.invocation.padEnd(width)} ${row.service.padEnd(serviceWidth)} ${row.privilege}`.trimEnd());
2099
2160
  }
2100
2161
  lines.push("");
2101
2162
  }
@@ -2357,6 +2418,49 @@ Examples:
2357
2418
 
2358
2419
  // src/commands/use.ts
2359
2420
  import { Command as Command6 } from "commander";
2421
+
2422
+ // src/lib/application.ts
2423
+ function isApplicationId(value) {
2424
+ try {
2425
+ return Buffer.from(value, "base64url").toString("utf8").startsWith("Application/");
2426
+ } catch {
2427
+ return false;
2428
+ }
2429
+ }
2430
+ function parseApplicationReference(value) {
2431
+ const separator = value.indexOf("/");
2432
+ if (separator === -1) return { company: void 0, slug: value };
2433
+ return { company: value.slice(0, separator), slug: value.slice(separator + 1) };
2434
+ }
2435
+ var APPLICATION_BY_SLUG = `
2436
+ query ApplicationBySlug($slug: String!) {
2437
+ me {
2438
+ companies(first: 50) {
2439
+ nodes { id slug personal application(slug: $slug) { id } }
2440
+ }
2441
+ }
2442
+ }
2443
+ `;
2444
+ function pickApplication(data, company) {
2445
+ const me = data.me;
2446
+ const companies = me?.companies?.nodes ?? [];
2447
+ const match = companies.find((candidate) => {
2448
+ if (company === void 0) return candidate.personal === true;
2449
+ return isCompanyId(company) ? candidate.id === company : candidate.slug === company;
2450
+ });
2451
+ return { company: match ?? null, applicationId: match?.application?.id };
2452
+ }
2453
+ async function lookupApplicationId(reference, opts) {
2454
+ const company = reference.company ?? opts.company ?? opts.ctx?.company;
2455
+ const data = await graphqlRaw(
2456
+ APPLICATION_BY_SLUG,
2457
+ { slug: reference.slug },
2458
+ { endpoint: opts.endpoint, throwOnError: true, asPerson: true, withoutCompany: true }
2459
+ );
2460
+ return pickApplication(data, company);
2461
+ }
2462
+
2463
+ // src/commands/use.ts
2360
2464
  var CREATE = `
2361
2465
  mutation UseApplication($applicationId: ID!, $name: String!) {
2362
2466
  createApplicationCredential(input: { applicationId: $applicationId, name: $name, session: true }) {
@@ -2366,16 +2470,20 @@ var CREATE = `
2366
2470
  }
2367
2471
  }
2368
2472
  `;
2473
+ var APPLICATIONS_HINT = "`sl hermes applications` lists the applications you can act as, with their slugs.";
2369
2474
  var REVOKE = `
2370
2475
  mutation ReleaseSessionCredential($credentialId: ID!) {
2371
2476
  revokeApplicationCredential(input: { credentialId: $credentialId }) { revokedAt }
2372
2477
  }
2373
2478
  `;
2374
2479
  var useCommand = new Command6("use").summary("Act as an application, or go back to acting as yourself").description(
2375
- "Act as an application, or go back to acting as yourself\n\nExamples:\n sl use application <id> Act as that application for one token lifetime\n sl use me Go back to acting as yourself"
2480
+ "Act as an application, or go back to acting as yourself\n\nExamples:\n sl use application testapp Act as your application testapp for one token lifetime\n sl use application acme/testapp The same, naming the company it belongs to\n sl use application <id> The same, by the application's id\n sl use me Go back to acting as yourself"
2376
2481
  );
2377
- useCommand.command("application <id>").description("Act as an application for one token lifetime").action(async function(id) {
2482
+ useCommand.command("application <application>").description(
2483
+ "Act as an application for one token lifetime. Name it by slug, which is looked up in the company you act for, by <company>/<slug>, or by its id"
2484
+ ).action(async function(reference) {
2378
2485
  const opts = this.optsWithGlobals();
2486
+ const id = await applicationIdFor(reference, opts);
2379
2487
  const asPerson = { endpoint: opts.endpoint, throwOnError: true, asPerson: true };
2380
2488
  let credential = null;
2381
2489
  try {
@@ -2383,12 +2491,12 @@ useCommand.command("application <id>").description("Act as an application for on
2383
2491
  credential = issued.createApplicationCredential;
2384
2492
  } catch (err) {
2385
2493
  error(`Could not create a session credential: ${err.message}`);
2386
- hint("`sl applications` lists the applications you can manage.");
2494
+ hint(APPLICATIONS_HINT);
2387
2495
  process.exit(1);
2388
2496
  }
2389
2497
  if (!credential) {
2390
2498
  error("The server did not return a session credential.");
2391
- hint("`sl applications` lists the applications you can manage.");
2499
+ hint(APPLICATIONS_HINT);
2392
2500
  process.exit(1);
2393
2501
  }
2394
2502
  let accessToken = null;
@@ -2430,6 +2538,29 @@ useCommand.command("me").description("Go back to acting as yourself").action(()
2430
2538
  function sessionName() {
2431
2539
  return `cli-session-${(/* @__PURE__ */ new Date()).toISOString().slice(0, 19).replace(/[:T]/g, "")}`;
2432
2540
  }
2541
+ async function applicationIdFor(reference, opts) {
2542
+ if (isApplicationId(reference)) return reference;
2543
+ const named = parseApplicationReference(reference);
2544
+ let found;
2545
+ try {
2546
+ found = await lookupApplicationId(named, { company: opts.company, ctx: getUserContext(), endpoint: opts.endpoint });
2547
+ } catch (err) {
2548
+ error(`Could not look up the application "${reference}": ${err.message}`);
2549
+ process.exit(1);
2550
+ }
2551
+ if (found.applicationId) return found.applicationId;
2552
+ if (found.company === null) {
2553
+ const company = named.company ?? opts.company ?? getUserContext().company;
2554
+ error(
2555
+ company ? `You do not belong to a company "${company}".` : "You have no personal company to look the application up in."
2556
+ );
2557
+ hint("`sl hermes companies` lists the companies you belong to, with their slugs.");
2558
+ } else {
2559
+ error(`No application "${named.slug}" in ${found.company.slug ?? "that company"}.`);
2560
+ hint(APPLICATIONS_HINT);
2561
+ }
2562
+ process.exit(2);
2563
+ }
2433
2564
 
2434
2565
  // src/commands/whoami.ts
2435
2566
  import { Command as Command7 } from "commander";
@@ -2604,24 +2735,45 @@ async function fetchIntrospection(endpoint, token) {
2604
2735
  }
2605
2736
  return { introspection: json.data, raw: json.data };
2606
2737
  }
2738
+ var CLI_TAG = "cli";
2739
+ function isTaggedForCli(field) {
2740
+ return field.appliedDirectives?.some(
2741
+ (d) => d.name === "tag" && d.args.some((a) => a.name === "name" && a.value === CLI_TAG)
2742
+ ) ?? false;
2743
+ }
2744
+ function requiredScopes(field) {
2745
+ const value = field.appliedDirectives?.find((directive) => directive.name === "requiresScopes")?.args.find((arg) => arg.name === "scopes")?.value;
2746
+ const parsed = typeof value === "string" ? JSON.parse(value) : value;
2747
+ if (!Array.isArray(parsed)) return void 0;
2748
+ return parsed.filter(Array.isArray).map((alternative) => alternative.map(String));
2749
+ }
2607
2750
  function parseIntrospection(raw) {
2608
2751
  const fieldServices = /* @__PURE__ */ new Map();
2752
+ const fieldScopes = /* @__PURE__ */ new Map();
2609
2753
  const services = /* @__PURE__ */ new Set();
2610
2754
  for (const type of raw.__schema.types ?? []) {
2611
2755
  if (!type.fields?.length) continue;
2612
2756
  let fieldMap = null;
2757
+ let scopeMap = null;
2613
2758
  for (const field of type.fields) {
2614
2759
  const directive = field.appliedDirectives?.find((d) => d.name === "join__field");
2615
2760
  if (!directive) continue;
2616
2761
  const graphArg = directive.args.find((a) => a.name === "graph");
2617
2762
  if (!graphArg || typeof graphArg.value !== "string") continue;
2618
2763
  services.add(graphArg.value);
2619
- if (!fieldMap) fieldMap = /* @__PURE__ */ new Map();
2764
+ if (!isTaggedForCli(field)) continue;
2765
+ fieldMap ??= /* @__PURE__ */ new Map();
2620
2766
  fieldMap.set(field.name, graphArg.value);
2767
+ const scopes = requiredScopes(field);
2768
+ if (scopes?.length) {
2769
+ scopeMap ??= /* @__PURE__ */ new Map();
2770
+ scopeMap.set(field.name, scopes);
2771
+ }
2621
2772
  }
2622
2773
  if (fieldMap) fieldServices.set(type.name, fieldMap);
2774
+ if (scopeMap) fieldScopes.set(type.name, scopeMap);
2623
2775
  }
2624
- return { fieldServices, services };
2776
+ return { fieldServices, fieldScopes, services };
2625
2777
  }
2626
2778
  async function currentAccessToken() {
2627
2779
  const machine = clientCredentials();
@@ -2654,8 +2806,8 @@ async function getIntrospectedSchema(endpointOverride2) {
2654
2806
  }
2655
2807
  function build(introspection, raw) {
2656
2808
  try {
2657
- const { fieldServices, services } = parseIntrospection(raw);
2658
- return { schema: buildClientSchema(introspection), fieldServices, services };
2809
+ const { fieldServices, fieldScopes, services } = parseIntrospection(raw);
2810
+ return { schema: buildClientSchema(introspection), fieldServices, fieldScopes, services };
2659
2811
  } catch {
2660
2812
  return null;
2661
2813
  }
@@ -2781,14 +2933,14 @@ function buildRootDescription(operationCount) {
2781
2933
  const parts = [BASE_DESCRIPTION];
2782
2934
  if (operationCount > 0) {
2783
2935
  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`
2936
+ `Every federation operation exposed to the CLI is a command (${operationCount} available),
2937
+ grouped under the service that serves it, Hermes's account and company operations included:
2938
+ sl operations List them all
2939
+ sl operations --search organization
2940
+ sl <service> <operation> --help Flags for one operation`
2789
2941
  );
2790
2942
  parts.push(
2791
- "Examples:\n sl organizations --limit 5\n sl create-application --name continuous-integration\n sl config show"
2943
+ "Examples:\n sl hermes companies\n sl atlas find-organizations --help\n sl config show"
2792
2944
  );
2793
2945
  }
2794
2946
  return parts.join("\n\n");
@@ -2837,10 +2989,13 @@ program.addCommand(schemaCommand);
2837
2989
  var endpointIdx = process.argv.indexOf("--endpoint");
2838
2990
  var endpointOverride = endpointIdx !== -1 ? process.argv[endpointIdx + 1] : void 0;
2839
2991
  try {
2840
- const { schema, fieldServices } = await getIntrospectedSchema(endpointOverride);
2841
- const operations = buildOperationCommands(schema, fieldServices);
2842
- for (const operation of operations) {
2843
- program.addCommand(operation.command, { hidden: true });
2992
+ const { schema, fieldServices, fieldScopes } = await getIntrospectedSchema(endpointOverride);
2993
+ const operations = buildOperationCommands(schema, fieldServices, fieldScopes);
2994
+ for (const command of groupOperationCommands(operations)) {
2995
+ program.addCommand(command);
2996
+ }
2997
+ for (const command of legacyTopLevelCommands(schema, fieldServices, fieldScopes)) {
2998
+ program.addCommand(command, { hidden: true });
2844
2999
  }
2845
3000
  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
3001
  info(formatOperationList(operations, this.opts().search));