dropsh 0.6.0 → 0.7.0

package/README.md

@@ -171,7 +171,8 @@ Each descriptor's `with` is passed to the plugin factory (legacy alias:
 descriptor names `dropsh/plugin` with `export: "basicAuthPlugin"`.
 
 Use `dropsh.config.example.js` as a fuller starting point. Override the config
-path with `--config <path>` or `DROPSH_CONFIG`.
+path with `--config <path>` or `DROPSH_CONFIG`, or address a config file by name
+with `--connection <id>` — see [Named connections](#named-connections--one-config-file-per-site).
 
 <details>
 <summary>Workspace variant — importing factories directly</summary>
@@ -204,6 +205,66 @@ to the config file, so it only works when the packages are installed there.
 
 </details>
 
+### Named connections — one config file per site
+
+A *named connection* is a config file addressed by id instead of by path. A
+connection is a file: `<connections-dir>/<id>.js`, carrying exactly the shape
+`dropsh.config.js` has (`site`, `defaults`, `plugins`), and its basename is its
+id. There is no registry, index or map — adding a connection is adding a file.
+Only `.js` files are connections.
+
+```bash
+dropsh --connection staging read node/article/<uuid>
+```
+
+**The connections directory** defaults to `~/.config/dropsh/connections/`,
+beside the per-host auth store. It is overridable, and the flag wins over the
+environment variable:
+
+| # | Selector | Kind |
+|---|----------|------|
+| 1 | `--connections-dir <path>` | flag |
+| 2 | `$DROPSH_CONNECTIONS_DIR`  | environment |
+| 3 | `~/.config/dropsh/connections` | default |
+
+**Which config file a run uses**, highest first:
+
+| # | Selector | Kind |
+|---|----------|------|
+| 1 | `--config <path>` | names a **file** |
+| 2 | `--connection <id>` | names an **entry** |
+| 3 | `$DROPSH_CONFIG` | names a **file** |
+| 4 | `$DROPSH_CONNECTION` | names an **entry** |
+| 5 | `./dropsh.config.js` | the cwd default |
+
+`--config` and `--connection` given together is not an error: `--config` names a
+file and wins.
+
+An unknown id is a hard error — non-zero exit, naming the id, the directory
+searched and the available ids. Nothing is prompted and nothing is created, so
+an unattended run fails rather than hangs:
+
+```
+Unknown connection 'stagng'. Available in /home/me/.config/dropsh/connections: production, staging.
+```
+
+**List them** with `dropsh connections list`: one row per connection with its
+`site.base_url`, a `*` on the one the current invocation would resolve to, and
+the resolved path stated instead when that is a path rather than an id. A
+connection whose file cannot be read is listed with its error in place of the
+URL and the listing still exits 0. Listing reads `site` only, so a connection
+naming an uninstalled plugin package cannot abort the listing of the others.
+
+```bash
+dropsh connections list
+dropsh connections list --format json
+```
+
+Auth is unchanged by connections: the session store keys on the host of
+`site.base_url`, so two connections against different hosts keep their tokens
+apart and two against the same host share them. `--auth-profile` keeps selecting
+the identity *within* whichever connection is in force.
+
 ## Authentication
 
 Authentication is configured through plugins. Each plugin that contributes an
@@ -295,17 +356,175 @@ exit codes.
 ```bash
 dropsh read <entity_type>/<bundle>/<uuid> [--include=<field>,…]
 dropsh search <entity_type> [--bundle=<b>] [--filter=key:value]… [--limit=N] [--include=<field>,…]
-dropsh create <entity_type> --bundle=<b> --data=<json|@file> [--dry-run] [--no-validate]
-dropsh update <entity_type>/<bundle>/<uuid> --data=<json|@file> [--dry-run] [--no-validate]
+dropsh create <entity_type> --bundle=<b> (--data=<json|@file> | <field parameters>) [--dry-run] [--no-validate]
+dropsh update <entity_type>/<bundle>/<uuid> (--data=<json|@file> | <field parameters>) [--dry-run] [--no-validate]
 dropsh delete <entity_type>/<bundle>/<uuid> [--dry-run]
 dropsh upload-file --target=<entity_type>/<bundle>/<uuid>/<field> --file=<path> [--dry-run]
 dropsh schema [--refresh]
-dropsh schema <entity_type>/<bundle> [--for=create|update] [--refresh]
+dropsh schema <entity_type>/<bundle> [--for=create|update] [--refresh] [--fields]
+dropsh connections list
 ```
 
+Every command accepts the global `--config <path>`, `--connection <id>` and
+`--connections-dir <path>` selectors described under
+[Named connections](#named-connections--one-config-file-per-site).
+
 `create` and `update` validate payloads against the current schema by default.
 Pass `--no-validate` when you intentionally want to skip local validation.
 
+### Field parameters on `create` / `update`
+
+Instead of handing `create`/`update` a finished JSON:API document via `--data`,
+you can name the fields directly. The CLI reads the bundle's operation schema and
+builds the document itself, so it knows which name is an attribute and which is a
+relationship:
+
+| Form | Meaning |
+|---|---|
+| `--<field> <value>` | set a field |
+| `--<field>=<value>` | same; required when the value itself starts with `--` |
+| `--<field>.<sub> <value>` | set a sub-property, e.g. `--body.value "Text"` |
+| `--<relationship> <uuid>` | reference by UUID; repeat for a multi-valued field |
+| `--json <field>=<json>` | raw JSON value, for arrays of objects |
+
+Any number of fields goes into a single invocation; the `--<field>=<value>` pair
+form and the spaced form are interchangeable and produce identical output.
+
+**`--fields` lists the bundle's actual fields.** `--help` documents the forms;
+`--fields` resolves the bundle's schema and prints every settable parameter,
+then exits without sending anything:
+
+```bash
+dropsh schema node/article_test --fields          # the introspection route
+dropsh create node --bundle=article_test --fields  # same listing, on the command
+```
+
+```
+node--article_test — field parameters
+
+Attributes:
+  --drupal_internal__nid <value>                integer  ID
+  --drupal_internal__vid <value>                integer  Revision ID
+  --langcode.value <value>                      string  Language code
+  --langcode.language <value>                   Language object
+  --revision_timestamp <value>                  number  Revision create time
+  --revision_log <value>                        string  Revision log message
+  --status [true|false]                         boolean  Published
+  --title <value>                               string  required  Title
+  --created <value>                             number  Authored on
+  --changed <value>                             number  Changed
+  --promote [true|false]                        boolean  Promoted to front page
+  --sticky [true|false]                         boolean  Sticky at top of lists
+  --default_langcode [true|false]               boolean  Default translation
+  --revision_default [true|false]               boolean  Default revision
+  --revision_translation_affected [true|false]  boolean  Revision translation affected
+  --path.alias <value>                          string  Path alias
+  --path.pid <value>                            integer  Path id
+  --path.langcode <value>                       string  Language Code
+  --body.value <value>                          string  Text
+  --body.format <value>                         string  Text format
+  --body.summary <value>                        string  Summary
+  --field_test_text <value>                     string  Test Text
+
+Relationships (take a UUID):
+  --node_type <uuid>                            node_type--node_type  Content type
+  --revision_uid <uuid>                         user--user  Revision user
+  --uid <uuid>                                  user--user  Authored by
+  --field_image <uuid>                          file--file  Image
+```
+
+The listing is the schema's, not a curated subset: Drupal's base fields
+(`--drupal_internal__nid`, `--langcode.*`, `--path.*`, `--node_type`,
+`--revision_uid`, …) are settable parameters and appear alongside the
+bundle's own fields.
+
+Each row carries the schema type, whether the field is required, and the field's
+human label. Object attributes appear as their dotted leaves (`--body.value`,
+never `--body`), array attributes as their `--json` form, and a relationship that
+allows several target types is spelled `<type>:<uuid>`. The same listing is reachable three ways, all derived from the schema alone with
+no extra request: `dropsh schema <entity>/<bundle> --fields` (honouring `--for`
+and `--refresh`), and `--fields` on `create` and `update`.
+
+Add an explicit `--format json` to get the same listing as JSON — `parameter`,
+`path`, `type`, `label`, `required`, `bare_flag` per attribute, and `targets`,
+`multiple`, `requires_type_prefix` per relationship — for a caller that wants to
+consume it rather than read it.
+
+Rules worth knowing:
+
+- **Field names come from the schema** (`dropsh schema <entity>/<bundle>`), so an
+  unknown name is **rejected** with exit code `4` instead of being ignored. The
+  error names the rejected parameter and lists the known attributes and
+  relationships.
+- **Relationships take a bare UUID**; the resource type comes from the schema.
+  When a relationship allows several target types, pass `<type>:<uuid>`.
+  Repeating the flag accumulates values on a multi-valued relationship; a second
+  value on a single-valued one is an error.
+- **Values are typed by the schema** — `boolean`, `integer`/`number`, else
+  string. A bare `--flag` means `true` only on a boolean field. Values are never
+  comma-split, so `--title "a, b"` survives intact.
+- **`--data` and field parameters are mutually exclusive**; giving neither is an
+  error.
+- **`--dry-run` prints the generated document** and sends nothing. Output keys are
+  emitted in schema declaration order, so two dry-runs of the same fields are
+  byte-identical and diffable.
+- **`--no-validate` skips Ajv, not the schema.** In parameter mode the schema is
+  always loaded — attribute/relationship placement is impossible without it.
+- A field whose name collides with a reserved option (`--bundle`, `--data`,
+  `--dry-run`, `--no-validate`, `--fields`, `--format`, `--auth-profile`,
+  `--config`, `--view-mode`, `--json`) is out of reach as a bare `--<field>`, but
+  `--json <field>=<json>` still sets it (write the value as JSON), and so does
+  `--data`. No Drupal base field name collides with that list in practice.
+- Fields contributed by a plugin's `extendOperationSchema` hook are usable as
+  parameters like any native field.
+
+Worked example:
+
+```bash
+dropsh create node --bundle=article_test \
+  --title "Hello" --body.value "Text" \
+  --uid c8e0b5d2-9e66-4caf-ac43-337f3b3af62d --dry-run | jq
+```
+
+```json
+{
+  "dry_run": true,
+  "method": "POST",
+  "path": "node/article_test",
+  "payload": {
+    "data": {
+      "type": "node--article_test",
+      "attributes": {
+        "title": "Hello",
+        "body": {
+          "value": "Text"
+        }
+      },
+      "relationships": {
+        "uid": {
+          "data": {
+            "type": "user--user",
+            "id": "c8e0b5d2-9e66-4caf-ac43-337f3b3af62d"
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+`update` works the same way and puts the target UUID into `data.id`, sending a
+PATCH with only the fields you named:
+
+```bash
+dropsh update node/article_test/<uuid> --title "changed title"
+```
+
+The builder is also available programmatically — `buildPayloadFromParameters`,
+`indexSchemaFields` and `propertiesOf` are exported from `dropsh/plugin`, so a
+plugin can turn (schema, parameters) into the same document without invoking the
+CLI.
+
 ### `--include` on `read` / `search`
 
 Pass `--include` to embed related resources in the response's JSON:API

package/dist/src/commands/connections.d.ts

@@ -0,0 +1,37 @@
+import type { ConfigSource, ConnectionEntry } from "../core/connections.js";
+export interface ConnectionsListArgs {
+    /** The resolved connections directory. */
+    dir: string;
+    /** What this invocation would resolve to — the row it marks, when it names an id. */
+    resolved: ConfigSource;
+}
+export interface ConnectionsListDeps {
+    list: (dir: string) => Promise<ConnectionEntry[]>;
+    emit: (v: unknown) => void | Promise<void>;
+}
+/** One listed connection, as it is emitted. */
+export interface ConnectionsListRow {
+    id: string;
+    base_url?: string;
+    error?: string;
+    /** True on the single connection this invocation would resolve to. */
+    current: boolean;
+}
+export interface ConnectionsListResult {
+    directory: string;
+    resolved: ConfigSource;
+    connections: ConnectionsListRow[];
+}
+/**
+ * List the connections in the resolved directory. A broken connection is a row
+ * carrying its error, not an abort: the listing succeeded and reports exactly
+ * what is on disk. When the invocation resolves to a path rather than an id —
+ * `--config`, `$DROPSH_CONFIG`, or the cwd default — no row is marked and the
+ * resolved path stands on its own in `resolved`.
+ */
+export declare function runConnectionsList(args: ConnectionsListArgs, deps: ConnectionsListDeps): Promise<ConnectionsListResult>;
+/**
+ * The listing as a human reads it: one row per connection, a `*` on the one in
+ * force, and the resolved path stated below when no id is in force.
+ */
+export declare function renderConnectionsTable(result: ConnectionsListResult): string;

package/dist/src/commands/connections.js

@@ -0,0 +1,42 @@
+/**
+ * List the connections in the resolved directory. A broken connection is a row
+ * carrying its error, not an abort: the listing succeeded and reports exactly
+ * what is on disk. When the invocation resolves to a path rather than an id —
+ * `--config`, `$DROPSH_CONFIG`, or the cwd default — no row is marked and the
+ * resolved path stands on its own in `resolved`.
+ */
+export async function runConnectionsList(args, deps) {
+    const entries = await deps.list(args.dir);
+    const result = {
+        directory: args.dir,
+        resolved: args.resolved,
+        connections: entries.map((e) => ({
+            id: e.id,
+            ...(e.baseUrl !== undefined ? { base_url: e.baseUrl } : {}),
+            ...(e.error !== undefined ? { error: e.error } : {}),
+            current: e.id === args.resolved.id,
+        })),
+    };
+    await deps.emit(result);
+    return result;
+}
+/**
+ * The listing as a human reads it: one row per connection, a `*` on the one in
+ * force, and the resolved path stated below when no id is in force.
+ */
+export function renderConnectionsTable(result) {
+    const lines = [`Connections in ${result.directory}`];
+    if (result.connections.length === 0) {
+        lines.push("  (none)");
+    }
+    const width = Math.max(0, ...result.connections.map((c) => c.id.length));
+    for (const c of result.connections) {
+        const marker = c.current ? "*" : " ";
+        const value = c.base_url ?? `! ${c.error ?? "unreadable"}`;
+        lines.push(`${marker} ${c.id.padEnd(width)}  ${value}`);
+    }
+    if (result.resolved.id === undefined) {
+        lines.push(`Resolved config: ${result.resolved.path} (${result.resolved.source})`);
+    }
+    return lines.join("\n");
+}

package/dist/src/commands/create.d.ts

@@ -2,7 +2,12 @@ import type { JsonApiClient } from "../core/jsonapi/client.js";
 export interface CreateArgs {
     entityType: string;
     bundle: string;
-    dataArg: string;
+    /**
+     * The JSON:API document to send. Resolving it — from `--data` or from field
+     * parameters — happens before this command runs, so nothing here knows or
+     * cares which route produced it.
+     */
+    payload: unknown;
     dryRun?: boolean;
     noValidate?: boolean;
 }

package/dist/src/commands/create.js

@@ -1,6 +1,5 @@
-import { readDataArg } from "./_data.js";
 export async function runCreate(args, deps) {
-    const payload = await readDataArg(args.dataArg);
+    const { payload } = args;
     const target = `${args.entityType}/${args.bundle}`;
     if (!args.noValidate && deps.validate) {
         await deps.validate(payload, target);

package/dist/src/commands/update.d.ts

@@ -1,7 +1,12 @@
 import type { JsonApiClient } from "../core/jsonapi/client.js";
 export interface UpdateArgs {
     target: string;
-    dataArg: string;
+    /**
+     * The JSON:API document to send. Resolving it — from `--data` or from field
+     * parameters — happens before this command runs, so nothing here knows or
+     * cares which route produced it.
+     */
+    payload: unknown;
     dryRun?: boolean;
     noValidate?: boolean;
 }
@@ -10,4 +15,11 @@ export interface UpdateDeps {
     emit: (v: unknown) => void | Promise<void>;
     validate?: (payload: unknown, target: string) => void | Promise<void>;
 }
+/**
+ * Reject a malformed target. Exported so the CLI can run this guard *before* it
+ * builds a payload from field parameters: without it, a bad target would surface
+ * as the builder's "update requires the entity id" instead of this clearer
+ * message.
+ */
+export declare function assertUpdateTarget(target: string): void;
 export declare function runUpdate(args: UpdateArgs, deps: UpdateDeps): Promise<void>;

package/dist/src/commands/update.js

@@ -1,11 +1,19 @@
 import { ValidationError } from "../errors.js";
-import { readDataArg } from "./_data.js";
 const TARGET_RE = /^[a-z0-9_]+\/[a-z0-9_]+\/[a-f0-9-]{8,}$/;
-export async function runUpdate(args, deps) {
-    if (!TARGET_RE.test(args.target)) {
-        throw new ValidationError(`target must be <entity_type>/<bundle>/<uuid>, got "${args.target}"`);
+/**
+ * Reject a malformed target. Exported so the CLI can run this guard *before* it
+ * builds a payload from field parameters: without it, a bad target would surface
+ * as the builder's "update requires the entity id" instead of this clearer
+ * message.
+ */
+export function assertUpdateTarget(target) {
+    if (!TARGET_RE.test(target)) {
+        throw new ValidationError(`target must be <entity_type>/<bundle>/<uuid>, got "${target}"`);
     }
-    const payload = await readDataArg(args.dataArg);
+}
+export async function runUpdate(args, deps) {
+    assertUpdateTarget(args.target);
+    const { payload } = args;
     const [entity, bundle] = args.target.split("/", 3);
     const schemaTarget = `${entity}/${bundle}`;
     if (!args.noValidate && deps.validate) {

package/dist/src/core/auth/session-store.d.ts

@@ -1,4 +1,6 @@
+import { defaultStateDir } from "../paths.js";
 import type { AuthSession } from "./types.js";
+export { defaultStateDir };
 /** One stored auth identity: the provider that owns it plus its opaque session. */
 export interface ProfileRecord {
     provider: string;
@@ -17,7 +19,6 @@ export interface SessionRecord {
     activeProvider: string;
     session: AuthSession;
 }
-export declare function defaultStateDir(): string;
 /**
  * Read the whole profiles file, migrating a legacy `{ activeProvider, session }`
  * record in memory to the v2 shape. No write-time migration is needed: the next

package/dist/src/core/auth/session-store.js

@@ -1,10 +1,10 @@
 import { chmod, mkdir, readFile, rm, writeFile } from "node:fs/promises";
-import { homedir } from "node:os";
 import { join } from "node:path";
 import { ConfigError } from "../../errors.js";
-export function defaultStateDir() {
-    return join(homedir(), ".config", "dropsh");
-}
+import { defaultStateDir } from "../paths.js";
+// Re-exported so every existing importer of the auth store keeps working while
+// the path itself lives in one place (`src/core/paths.ts`).
+export { defaultStateDir };
 function hostnameFromUrl(baseUrl) {
     return new URL(baseUrl).hostname;
 }

package/dist/src/core/config.d.ts

@@ -11,4 +11,6 @@ export interface Config {
     };
     plugins: DropSHPlugin[];
 }
+/** The `site` section of a config file, read without resolving its plugins. */
+export declare function loadConfigSite(filePath: string): Promise<SiteConfig>;
 export declare function loadConfig(filePath: string): Promise<Config>;

package/dist/src/core/config.js

@@ -152,7 +152,14 @@ async function resolvePlugins(raw, configPath) {
         await expand(entry, baseBases, undefined);
     return out;
 }
-export async function loadConfig(filePath) {
+/**
+ * Import a config module and validate its `site` section — everything a config
+ * source has to be valid for, short of resolving `plugins[]`. Both `loadConfig`
+ * and the connection listing go through here, so the two cannot diverge on what
+ * a valid `site` is, and the listing can read many files without constructing
+ * any plugin.
+ */
+async function importConfig(filePath) {
     const configPath = resolve(filePath);
     let mod;
     try {
@@ -169,13 +176,25 @@ export async function loadConfig(filePath) {
         throw new ConfigError("site section missing");
     if (typeof site.base_url !== "string" || site.base_url.length === 0)
         throw new ConfigError("site.base_url required");
-    const defaults = isRecord(raw.defaults) ? raw.defaults : {};
-    const plugins = await resolvePlugins(raw.plugins, configPath);
     return {
+        configPath,
+        raw,
         site: {
             base_url: site.base_url,
             jsonapi_prefix: typeof site.jsonapi_prefix === "string" ? site.jsonapi_prefix : "/jsonapi",
         },
+    };
+}
+/** The `site` section of a config file, read without resolving its plugins. */
+export async function loadConfigSite(filePath) {
+    return (await importConfig(filePath)).site;
+}
+export async function loadConfig(filePath) {
+    const { configPath, raw, site } = await importConfig(filePath);
+    const defaults = isRecord(raw.defaults) ? raw.defaults : {};
+    const plugins = await resolvePlugins(raw.plugins, configPath);
+    return {
+        site,
         defaults: {
             dry_run: defaults.dry_run === true,
             timeout_ms: typeof defaults.timeout_ms === "number" ? defaults.timeout_ms : 30000,

package/dist/src/core/connections.d.ts

@@ -0,0 +1,58 @@
+/** The name of the config file dropsh falls back to in the current directory. */
+export declare const CWD_CONFIG_FILE = "dropsh.config.js";
+/** Which selector produced the resolved config path. */
+export type ConfigSourceKind = "flag-config" | "flag-connection" | "env-config" | "env-connection" | "cwd";
+/** The chosen config file plus the provenance of that choice. */
+export interface ConfigSource {
+    path: string;
+    source: ConfigSourceKind;
+    /** The connection id, when the winning selector named an entry rather than a file. */
+    id?: string;
+}
+export interface ResolveConnectionsDirInput {
+    /** `--connections-dir <path>`. */
+    flag?: string | undefined;
+    env?: NodeJS.ProcessEnv;
+}
+/**
+ * The connections directory: `--connections-dir` > `$DROPSH_CONNECTIONS_DIR` >
+ * `~/.config/dropsh/connections`. Resolved independently of which config
+ * selector wins, because `connections list` reports the directory either way.
+ */
+export declare function resolveConnectionsDir(input?: ResolveConnectionsDirInput): string;
+export interface ResolveConfigSourceInput {
+    /** `--config <path>`. */
+    config?: string | undefined;
+    /** `--connection <id>`. */
+    connection?: string | undefined;
+    connectionsDir?: string;
+    env?: NodeJS.ProcessEnv;
+    cwd?: string;
+}
+/**
+ * Resolve the config file for this invocation, highest selector first:
+ * `--config` > `--connection` > `$DROPSH_CONFIG` > `$DROPSH_CONNECTION` >
+ * `./dropsh.config.js`. `--config` and `--connection` together is not an error:
+ * `--config` names a *file* and that is its stated meaning, so it wins silently.
+ *
+ * Returns the path *and* its provenance, so every caller — the command context,
+ * the auth wiring, the pre-parse plugin bootstrap and `connections list` — reads
+ * the same answer instead of re-deriving the chain.
+ */
+export declare function resolveConfigSource(input?: ResolveConfigSourceInput): ConfigSource;
+/** One row of `connections list`: a connection's id and either its base URL or its error. */
+export interface ConnectionEntry {
+    id: string;
+    baseUrl?: string;
+    error?: string;
+}
+/**
+ * Every `.js` file in `dir`, by basename, sorted, with its `site.base_url`. A
+ * file that cannot be imported, or that declares no usable `site`, is a row
+ * carrying its error rather than an abort: the listing reports exactly what is
+ * on disk. Plugins are never constructed, so one connection naming an
+ * uninstalled package cannot take the others down with it.
+ */
+export declare function listConnections(dir: string): Promise<ConnectionEntry[]>;
+/** Sorted ids of the `.js` files in `dir`; `[]` when the directory is absent. */
+export declare function listConnectionIds(dir: string): Promise<string[]>;

package/dist/src/core/connections.js

@@ -0,0 +1,115 @@
+import { existsSync, readdirSync } from "node:fs";
+import { readdir } from "node:fs/promises";
+import { basename, join } from "node:path";
+import { ConfigError } from "../errors.js";
+import { loadConfigSite } from "./config.js";
+import { defaultConnectionsDir } from "./paths.js";
+/** The name of the config file dropsh falls back to in the current directory. */
+export const CWD_CONFIG_FILE = "dropsh.config.js";
+/**
+ * The connections directory: `--connections-dir` > `$DROPSH_CONNECTIONS_DIR` >
+ * `~/.config/dropsh/connections`. Resolved independently of which config
+ * selector wins, because `connections list` reports the directory either way.
+ */
+export function resolveConnectionsDir(input = {}) {
+    const env = input.env ?? process.env;
+    return input.flag ?? env.DROPSH_CONNECTIONS_DIR ?? defaultConnectionsDir();
+}
+function connectionPath(dir, id) {
+    return join(dir, `${id}.js`);
+}
+function toIds(entries) {
+    return entries
+        .filter((name) => name.endsWith(".js"))
+        .map((name) => basename(name, ".js"))
+        .sort();
+}
+/**
+ * Sorted ids of the `.js` files in `dir`; `[]` when the directory is absent.
+ * Synchronous because it is only reached on the unknown-id error path, and the
+ * resolver itself has to stay synchronous for the commander option wiring.
+ */
+function listConnectionIdsSync(dir) {
+    try {
+        return toIds(readdirSync(dir));
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Resolve the config file for this invocation, highest selector first:
+ * `--config` > `--connection` > `$DROPSH_CONFIG` > `$DROPSH_CONNECTION` >
+ * `./dropsh.config.js`. `--config` and `--connection` together is not an error:
+ * `--config` names a *file* and that is its stated meaning, so it wins silently.
+ *
+ * Returns the path *and* its provenance, so every caller — the command context,
+ * the auth wiring, the pre-parse plugin bootstrap and `connections list` — reads
+ * the same answer instead of re-deriving the chain.
+ */
+export function resolveConfigSource(input = {}) {
+    const env = input.env ?? process.env;
+    const dir = input.connectionsDir ?? resolveConnectionsDir({ env });
+    const cwd = input.cwd ?? process.cwd();
+    if (input.config)
+        return { path: input.config, source: "flag-config" };
+    if (input.connection) {
+        return {
+            path: requireConnection(dir, input.connection),
+            source: "flag-connection",
+            id: input.connection,
+        };
+    }
+    if (env.DROPSH_CONFIG)
+        return { path: env.DROPSH_CONFIG, source: "env-config" };
+    if (env.DROPSH_CONNECTION) {
+        const id = env.DROPSH_CONNECTION;
+        return { path: requireConnection(dir, id), source: "env-connection", id };
+    }
+    return { path: join(cwd, CWD_CONFIG_FILE), source: "cwd" };
+}
+/**
+ * The path of connection `id`, or a `ConfigError` naming the id, the directory
+ * searched and the available ids. Nothing prompts and nothing is created: an
+ * unattended dispatch must fail rather than hang.
+ */
+function requireConnection(dir, id) {
+    const path = connectionPath(dir, id);
+    if (existsSync(path))
+        return path;
+    const available = listConnectionIdsSync(dir);
+    const tail = available.length > 0
+        ? `Available in ${dir}: ${available.join(", ")}.`
+        : `no connections found in ${dir}.`;
+    throw new ConfigError(`Unknown connection '${id}'. ${tail}`);
+}
+/**
+ * Every `.js` file in `dir`, by basename, sorted, with its `site.base_url`. A
+ * file that cannot be imported, or that declares no usable `site`, is a row
+ * carrying its error rather than an abort: the listing reports exactly what is
+ * on disk. Plugins are never constructed, so one connection naming an
+ * uninstalled package cannot take the others down with it.
+ */
+export async function listConnections(dir) {
+    const ids = await listConnectionIds(dir);
+    return Promise.all(ids.map(async (id) => {
+        try {
+            const site = await loadConfigSite(connectionPath(dir, id));
+            return { id, baseUrl: site.base_url };
+        }
+        catch (err) {
+            return { id, error: err instanceof Error ? err.message : String(err) };
+        }
+    }));
+}
+/** Sorted ids of the `.js` files in `dir`; `[]` when the directory is absent. */
+export async function listConnectionIds(dir) {
+    let entries;
+    try {
+        entries = await readdir(dir);
+    }
+    catch {
+        return [];
+    }
+    return toIds(entries);
+}