@sortlist/cli 0.53.0 → 0.55.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
@@ -49,37 +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. Atlas still answers a search then, with every contact detail `LOCKED`, but refuses any call that would reveal one (`FORBIDDEN_COMPANY`), staff included; the CLI then retries that call once for your personal company, so that is where a reveal is counted. `--wait` names your personal company from the start, since a retry would miss the result. 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 atlas find-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
- 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.
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
80
  sl atlas find-contacts --page '{"first":5}' --wait \
77
- --fields contacts.nodes.firstName,contacts.nodes.emailAddress # what you own
81
+ --fields firstName,emailAddress # what you own
78
82
  sl atlas find-contacts --page '{"first":5}' --wait --reveal contactIdentity,contactEmailAddress \
79
- --fields contacts.nodes.firstName,contacts.nodes.emailAddress # reveal, once per window
83
+ --fields firstName,emailAddress # reveal, once per window
80
84
  ```
81
85
 
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.
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. In staging and production those units are taken from the company's credit balance; a local Atlas only logs them. Every list argument typed as an enum accepts the same comma-separated shorthand.
83
87
 
84
88
  ## Unattended authentication
85
89
 
@@ -87,7 +91,7 @@ The finds are searches: the mutation is acknowledged at once and the page arrive
87
91
 
88
92
  ```bash
89
93
  # Create a credential — the secret is in the response and shown only once
90
- sl create-application-credential --application-id <id> --name continuous-integration
94
+ sl hermes create-application-credential --application-id <id> --name continuous-integration
91
95
 
92
96
  export SORTLIST_CLIENT_ID=slc_...
93
97
  export SORTLIST_CLIENT_SECRET=sl_live_...
@@ -97,7 +101,7 @@ With both set, **every** command authenticates as the application instead of as
97
101
 
98
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.
99
103
 
100
- 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".
101
105
 
102
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.
103
107
 
@@ -105,7 +109,7 @@ The token endpoint is a different host from the federation endpoint, so it canno
105
109
 
106
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.
107
111
 
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`:
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.
109
113
 
110
114
  ```bash
111
115
  sl operations # list them all, grouped by queries, mutations and subscriptions
@@ -113,8 +117,10 @@ sl operations --search organization # filter by operation or subgraph name
113
117
  sl <service> <operation> --help # flags for one operation
114
118
  ```
115
119
 
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.
121
+
116
122
  ```bash
117
- sl companies
123
+ sl hermes companies
118
124
  sl atlas find-organizations --help
119
125
  sl mercator resolve-locations --query brussels
120
126
  ```
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);
@@ -2061,21 +2062,19 @@ function deriveServiceMap(schema, fieldServices) {
2061
2062
  }
2062
2063
  return map;
2063
2064
  }
2064
- var TOP_LEVEL_SERVICE = "hermes";
2065
+ function describeScopes(scopes) {
2066
+ return scopes.map((alternative) => alternative.join(" + ")).join(" or ");
2067
+ }
2068
+ var LEGACY_TOP_LEVEL_SERVICE = "hermes";
2065
2069
  function invocation(service, commandName) {
2066
- return service === TOP_LEVEL_SERVICE ? commandName : `${service} ${commandName}`;
2070
+ return `${service} ${commandName}`;
2067
2071
  }
2068
2072
  function invocationOf(operation) {
2069
2073
  return invocation(operation.service, operation.command.name());
2070
2074
  }
2071
2075
  function groupOperationCommands(operations) {
2072
- const topLevel = [];
2073
2076
  const services = /* @__PURE__ */ new Map();
2074
2077
  for (const operation of operations) {
2075
- if (operation.service === TOP_LEVEL_SERVICE) {
2076
- topLevel.push(operation.command);
2077
- continue;
2078
- }
2079
2078
  let group = services.get(operation.service);
2080
2079
  if (!group) {
2081
2080
  group = new Command2(operation.service).description(`Operations served by ${operation.service}`);
@@ -2083,13 +2082,18 @@ function groupOperationCommands(operations) {
2083
2082
  }
2084
2083
  group.addCommand(operation.command);
2085
2084
  }
2086
- return {
2087
- topLevel,
2088
- services: [...services.values()].sort((a, b) => a.name().localeCompare(b.name()))
2089
- };
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);
2090
2089
  }
2091
- function buildOperationCommands(schema, fieldServices) {
2090
+ function buildOperationCommands(schema, fieldServices, fieldScopes = /* @__PURE__ */ new Map()) {
2092
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
+ };
2093
2097
  const pairs = resultSubscriptions(schema);
2094
2098
  const operations = [];
2095
2099
  for (const [service, entry] of serviceMap) {
@@ -2112,7 +2116,14 @@ function buildOperationCommands(schema, fieldServices) {
2112
2116
  if ((nameCounts.get(op.fieldName) ?? 0) > 1) {
2113
2117
  command.name(`${kebab(op.fieldName)}-${kind}`);
2114
2118
  }
2115
- 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 } : {} });
2116
2127
  } catch {
2117
2128
  }
2118
2129
  }
@@ -2135,12 +2146,17 @@ function formatOperationList(operations, search) {
2135
2146
  for (const kind of ["query", "mutation", "subscription"]) {
2136
2147
  const group = matching.filter((op) => op.kind === kind);
2137
2148
  if (group.length === 0) continue;
2138
- const rows = group.map((op) => ({ invocation: invocationOf(op), service: op.service }));
2149
+ const rows = group.map((op) => ({
2150
+ invocation: invocationOf(op),
2151
+ service: op.service,
2152
+ privilege: op.scopes ? `privileged: ${describeScopes(op.scopes)}` : ""
2153
+ }));
2139
2154
  rows.sort((a, b) => a.invocation.localeCompare(b.invocation));
2140
2155
  const width = Math.max(...rows.map((row) => row.invocation.length));
2156
+ const serviceWidth = Math.max(...rows.map((row) => row.service.length));
2141
2157
  lines.push(`${headings[kind]}:`);
2142
2158
  for (const row of rows) {
2143
- lines.push(` ${row.invocation.padEnd(width)} ${row.service}`);
2159
+ lines.push(` ${row.invocation.padEnd(width)} ${row.service.padEnd(serviceWidth)} ${row.privilege}`.trimEnd());
2144
2160
  }
2145
2161
  lines.push("");
2146
2162
  }
@@ -2175,6 +2191,11 @@ function openBrowser(url) {
2175
2191
  });
2176
2192
  }
2177
2193
 
2194
+ // src/lib/person.ts
2195
+ function personName(person) {
2196
+ return [person.firstName, person.lastName].filter(Boolean).join(" ") || null;
2197
+ }
2198
+
2178
2199
  // src/commands/login.ts
2179
2200
  var SERVICES = ["atlas", "core", "signals", "billing", "outreach", "hermes"];
2180
2201
  var ADMIN_API_SCOPES = SERVICES.map((service) => `${service}/*:read`);
@@ -2205,8 +2226,9 @@ async function setupUserContext(endpoint) {
2205
2226
  const userData = await graphql(Me, void 0, { endpoint });
2206
2227
  const user = userData.me;
2207
2228
  if (!user) return;
2229
+ const identity = [personName(user), `<${user.email}>`].filter(Boolean).join(" ");
2208
2230
  info("");
2209
- info(` User: ${user.firstName} ${user.lastName} <${user.email}>`);
2231
+ info(` User: ${identity}`);
2210
2232
  hint("Run `sl whoami` to verify.");
2211
2233
  }
2212
2234
  function reportScopeGrant(requestedScope, accessToken) {
@@ -2223,8 +2245,8 @@ var loginCommand = new Command3("login").summary("Log in to your Sortlist accoun
2223
2245
  `Log in to your Sortlist account
2224
2246
 
2225
2247
  Opens a browser to complete authentication, then saves your
2226
- credentials locally. If you belong to multiple companies, you'll
2227
- be prompted to pick one.
2248
+ credentials locally. To act for one of your companies, pass
2249
+ --company or run \`sl config set company <slug>\`.
2228
2250
 
2229
2251
  Examples:
2230
2252
  sl login Log in with the user scopes, no staff scope
@@ -2402,6 +2424,49 @@ Examples:
2402
2424
 
2403
2425
  // src/commands/use.ts
2404
2426
  import { Command as Command6 } from "commander";
2427
+
2428
+ // src/lib/application.ts
2429
+ function isApplicationId(value) {
2430
+ try {
2431
+ return Buffer.from(value, "base64url").toString("utf8").startsWith("Application/");
2432
+ } catch {
2433
+ return false;
2434
+ }
2435
+ }
2436
+ function parseApplicationReference(value) {
2437
+ const separator = value.indexOf("/");
2438
+ if (separator === -1) return { company: void 0, slug: value };
2439
+ return { company: value.slice(0, separator), slug: value.slice(separator + 1) };
2440
+ }
2441
+ var APPLICATION_BY_SLUG = `
2442
+ query ApplicationBySlug($slug: String!) {
2443
+ me {
2444
+ companies(first: 50) {
2445
+ nodes { id slug personal application(slug: $slug) { id } }
2446
+ }
2447
+ }
2448
+ }
2449
+ `;
2450
+ function pickApplication(data, company) {
2451
+ const me = data.me;
2452
+ const companies = me?.companies?.nodes ?? [];
2453
+ const match = companies.find((candidate) => {
2454
+ if (company === void 0) return candidate.personal === true;
2455
+ return isCompanyId(company) ? candidate.id === company : candidate.slug === company;
2456
+ });
2457
+ return { company: match ?? null, applicationId: match?.application?.id };
2458
+ }
2459
+ async function lookupApplicationId(reference, opts) {
2460
+ const company = reference.company ?? opts.company ?? opts.ctx?.company;
2461
+ const data = await graphqlRaw(
2462
+ APPLICATION_BY_SLUG,
2463
+ { slug: reference.slug },
2464
+ { endpoint: opts.endpoint, throwOnError: true, asPerson: true, withoutCompany: true }
2465
+ );
2466
+ return pickApplication(data, company);
2467
+ }
2468
+
2469
+ // src/commands/use.ts
2405
2470
  var CREATE = `
2406
2471
  mutation UseApplication($applicationId: ID!, $name: String!) {
2407
2472
  createApplicationCredential(input: { applicationId: $applicationId, name: $name, session: true }) {
@@ -2411,16 +2476,20 @@ var CREATE = `
2411
2476
  }
2412
2477
  }
2413
2478
  `;
2479
+ var APPLICATIONS_HINT = "`sl hermes applications` lists the applications you can act as, with their slugs.";
2414
2480
  var REVOKE = `
2415
2481
  mutation ReleaseSessionCredential($credentialId: ID!) {
2416
2482
  revokeApplicationCredential(input: { credentialId: $credentialId }) { revokedAt }
2417
2483
  }
2418
2484
  `;
2419
2485
  var useCommand = new Command6("use").summary("Act as an application, or go back to acting as yourself").description(
2420
- "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"
2486
+ "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"
2421
2487
  );
2422
- useCommand.command("application <id>").description("Act as an application for one token lifetime").action(async function(id) {
2488
+ useCommand.command("application <application>").description(
2489
+ "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"
2490
+ ).action(async function(reference) {
2423
2491
  const opts = this.optsWithGlobals();
2492
+ const id = await applicationIdFor(reference, opts);
2424
2493
  const asPerson = { endpoint: opts.endpoint, throwOnError: true, asPerson: true };
2425
2494
  let credential = null;
2426
2495
  try {
@@ -2428,12 +2497,12 @@ useCommand.command("application <id>").description("Act as an application for on
2428
2497
  credential = issued.createApplicationCredential;
2429
2498
  } catch (err) {
2430
2499
  error(`Could not create a session credential: ${err.message}`);
2431
- hint("`sl applications` lists the applications you can manage.");
2500
+ hint(APPLICATIONS_HINT);
2432
2501
  process.exit(1);
2433
2502
  }
2434
2503
  if (!credential) {
2435
2504
  error("The server did not return a session credential.");
2436
- hint("`sl applications` lists the applications you can manage.");
2505
+ hint(APPLICATIONS_HINT);
2437
2506
  process.exit(1);
2438
2507
  }
2439
2508
  let accessToken = null;
@@ -2475,6 +2544,29 @@ useCommand.command("me").description("Go back to acting as yourself").action(()
2475
2544
  function sessionName() {
2476
2545
  return `cli-session-${(/* @__PURE__ */ new Date()).toISOString().slice(0, 19).replace(/[:T]/g, "")}`;
2477
2546
  }
2547
+ async function applicationIdFor(reference, opts) {
2548
+ if (isApplicationId(reference)) return reference;
2549
+ const named = parseApplicationReference(reference);
2550
+ let found;
2551
+ try {
2552
+ found = await lookupApplicationId(named, { company: opts.company, ctx: getUserContext(), endpoint: opts.endpoint });
2553
+ } catch (err) {
2554
+ error(`Could not look up the application "${reference}": ${err.message}`);
2555
+ process.exit(1);
2556
+ }
2557
+ if (found.applicationId) return found.applicationId;
2558
+ if (found.company === null) {
2559
+ const company = named.company ?? opts.company ?? getUserContext().company;
2560
+ error(
2561
+ company ? `You do not belong to a company "${company}".` : "You have no personal company to look the application up in."
2562
+ );
2563
+ hint("`sl hermes companies` lists the companies you belong to, with their slugs.");
2564
+ } else {
2565
+ error(`No application "${named.slug}" in ${found.company.slug ?? "that company"}.`);
2566
+ hint(APPLICATIONS_HINT);
2567
+ }
2568
+ process.exit(2);
2569
+ }
2478
2570
 
2479
2571
  // src/commands/whoami.ts
2480
2572
  import { Command as Command7 } from "commander";
@@ -2576,7 +2668,7 @@ var whoamiCommand = new Command7("whoami").summary("Show what the CLI is current
2576
2668
  ` : "Acting as yourself.\n");
2577
2669
  info(
2578
2670
  formatResult({
2579
- name: [user.firstName, user.lastName].filter(Boolean).join(" ") || null,
2671
+ name: personName(user),
2580
2672
  email: user.email,
2581
2673
  id: user.id,
2582
2674
  ...elevation && { "elevated until": elevation.until },
@@ -2655,12 +2747,20 @@ function isTaggedForCli(field) {
2655
2747
  (d) => d.name === "tag" && d.args.some((a) => a.name === "name" && a.value === CLI_TAG)
2656
2748
  ) ?? false;
2657
2749
  }
2750
+ function requiredScopes(field) {
2751
+ const value = field.appliedDirectives?.find((directive) => directive.name === "requiresScopes")?.args.find((arg) => arg.name === "scopes")?.value;
2752
+ const parsed = typeof value === "string" ? JSON.parse(value) : value;
2753
+ if (!Array.isArray(parsed)) return void 0;
2754
+ return parsed.filter(Array.isArray).map((alternative) => alternative.map(String));
2755
+ }
2658
2756
  function parseIntrospection(raw) {
2659
2757
  const fieldServices = /* @__PURE__ */ new Map();
2758
+ const fieldScopes = /* @__PURE__ */ new Map();
2660
2759
  const services = /* @__PURE__ */ new Set();
2661
2760
  for (const type of raw.__schema.types ?? []) {
2662
2761
  if (!type.fields?.length) continue;
2663
2762
  let fieldMap = null;
2763
+ let scopeMap = null;
2664
2764
  for (const field of type.fields) {
2665
2765
  const directive = field.appliedDirectives?.find((d) => d.name === "join__field");
2666
2766
  if (!directive) continue;
@@ -2670,10 +2770,16 @@ function parseIntrospection(raw) {
2670
2770
  if (!isTaggedForCli(field)) continue;
2671
2771
  fieldMap ??= /* @__PURE__ */ new Map();
2672
2772
  fieldMap.set(field.name, graphArg.value);
2773
+ const scopes = requiredScopes(field);
2774
+ if (scopes?.length) {
2775
+ scopeMap ??= /* @__PURE__ */ new Map();
2776
+ scopeMap.set(field.name, scopes);
2777
+ }
2673
2778
  }
2674
2779
  if (fieldMap) fieldServices.set(type.name, fieldMap);
2780
+ if (scopeMap) fieldScopes.set(type.name, scopeMap);
2675
2781
  }
2676
- return { fieldServices, services };
2782
+ return { fieldServices, fieldScopes, services };
2677
2783
  }
2678
2784
  async function currentAccessToken() {
2679
2785
  const machine = clientCredentials();
@@ -2706,8 +2812,8 @@ async function getIntrospectedSchema(endpointOverride2) {
2706
2812
  }
2707
2813
  function build(introspection, raw) {
2708
2814
  try {
2709
- const { fieldServices, services } = parseIntrospection(raw);
2710
- return { schema: buildClientSchema(introspection), fieldServices, services };
2815
+ const { fieldServices, fieldScopes, services } = parseIntrospection(raw);
2816
+ return { schema: buildClientSchema(introspection), fieldServices, fieldScopes, services };
2711
2817
  } catch {
2712
2818
  return null;
2713
2819
  }
@@ -2834,12 +2940,14 @@ function buildRootDescription(operationCount) {
2834
2940
  if (operationCount > 0) {
2835
2941
  parts.push(
2836
2942
  `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:
2943
+ grouped under the service that serves it, Hermes's account and company operations included:
2838
2944
  sl operations List them all
2839
2945
  sl operations --search organization
2840
2946
  sl <service> <operation> --help Flags for one operation`
2841
2947
  );
2842
- parts.push("Examples:\n sl companies\n sl atlas find-organizations --help\n sl config show");
2948
+ parts.push(
2949
+ "Examples:\n sl hermes companies\n sl atlas find-organizations --help\n sl config show"
2950
+ );
2843
2951
  }
2844
2952
  return parts.join("\n\n");
2845
2953
  }
@@ -2887,15 +2995,14 @@ program.addCommand(schemaCommand);
2887
2995
  var endpointIdx = process.argv.indexOf("--endpoint");
2888
2996
  var endpointOverride = endpointIdx !== -1 ? process.argv[endpointIdx + 1] : void 0;
2889
2997
  try {
2890
- const { schema, fieldServices } = await getIntrospectedSchema(endpointOverride);
2891
- const operations = buildOperationCommands(schema, fieldServices);
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) {
2998
+ const { schema, fieldServices, fieldScopes } = await getIntrospectedSchema(endpointOverride);
2999
+ const operations = buildOperationCommands(schema, fieldServices, fieldScopes);
3000
+ for (const command of groupOperationCommands(operations)) {
2897
3001
  program.addCommand(command);
2898
3002
  }
3003
+ for (const command of legacyTopLevelCommands(schema, fieldServices, fieldScopes)) {
3004
+ program.addCommand(command, { hidden: true });
3005
+ }
2899
3006
  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() {
2900
3007
  info(formatOperationList(operations, this.opts().search));
2901
3008
  });