dropsh 0.6.1 → 0.7.1

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
@@ -301,8 +362,13 @@ 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] [--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.
 
@@ -596,6 +662,31 @@ export default {
 `@dropsh/plugin-*` packages), so `import { DropSHPlugin } from "dropsh/plugin"`
 is typed with no ambient `declare module`.
 
+The connection-resolution API is available to embedders as well:
+
+```ts
+import {
+  resolveConfigSource,
+  resolveConnectionsDir,
+} from "dropsh/plugin";
+
+const connectionsDir = resolveConnectionsDir({
+  flag: "/home/me/.config/dropsh/connections",
+});
+const config = resolveConfigSource({
+  connection: "staging",
+  connectionsDir,
+});
+// config.path and config.source identify the selected config file and selector.
+```
+
+The same entry point also exports `CWD_CONFIG_FILE`, `listConnectionIds`, and
+`listConnections`, plus the `ConfigSource`, `ConfigSourceKind`,
+`ConnectionEntry`, `ResolveConfigSourceInput`, and `ResolveConnectionsDirInput`
+types. These exports use the same selector precedence and connections-directory
+semantics as the CLI; see [Named connections](#named-connections--one-config-file-per-site)
+for the full documentation.
+
 ### Composing plugins
 
 `composePlugins(...children)` bundles several plugins into one flat list, so an

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/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,33 @@ 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);
+    // Reject rather than silently trim, so the persisted config stays canonical.
+    // A trailing slash survives into every string-concatenated URL a consumer
+    // builds from base_url — notably `${base_url}/oauth/token` — where the doubled
+    // slash addresses a route that is not the token endpoint (DROPSH-13).
+    if (site.base_url.endsWith("/")) {
+        const corrected = site.base_url.replace(/\/+$/, "");
+        throw new ConfigError(`site.base_url must not end with a trailing slash — set it to ${corrected}`);
+    }
     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);
+}

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

@@ -0,0 +1,8 @@
+/**
+ * The user-global dropsh state directory. Single source of that path: the
+ * per-host auth store and the connections directory both hang off it, so the
+ * two cannot drift onto different roots.
+ */
+export declare function defaultStateDir(): string;
+/** Default location of the named-connection files, one `<id>.js` per connection. */
+export declare function defaultConnectionsDir(): string;

package/dist/src/core/paths.js

@@ -0,0 +1,14 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+/**
+ * The user-global dropsh state directory. Single source of that path: the
+ * per-host auth store and the connections directory both hang off it, so the
+ * two cannot drift onto different roots.
+ */
+export function defaultStateDir() {
+    return join(homedir(), ".config", "dropsh");
+}
+/** Default location of the named-connection files, one `<id>.js` per connection. */
+export function defaultConnectionsDir() {
+    return join(defaultStateDir(), "connections");
+}

package/dist/src/index.d.ts

@@ -39,4 +39,16 @@ export interface AuthStatusDeps {
 }
 export declare function authStatus(deps: AuthStatusDeps): Promise<AuthStatusInfo>;
 export declare function buildProgram(opts?: ProgramOptions): Command;
+/**
+ * The config selectors as they appear in raw argv, for the pre-parse plugin
+ * bootstrap — which runs before commander sees any option. It feeds the same
+ * resolver the commands use, so the early and the late resolution cannot answer
+ * differently and load plugins from a different connection than the command
+ * being bootstrapped.
+ */
+export declare function earlyConfigArgs(argv: string[]): {
+    config?: string;
+    connection?: string;
+    connectionsDir?: string;
+};
 export declare function main(): Promise<void>;

package/dist/src/index.js

@@ -3,6 +3,7 @@ import { parseArgs } from "node:util";
 import { Command } from "commander";
 import { readDataArg } from "./commands/_data.js";
 import { runAuthLogin, runAuthLogout, runAuthStatus, runAuthUse } from "./commands/auth.js";
+import { renderConnectionsTable, runConnectionsList, } from "./commands/connections.js";
 import { runCreate } from "./commands/create.js";
 import { runDelete } from "./commands/delete.js";
 import { runRead } from "./commands/read.js";
@@ -16,6 +17,7 @@ import { createFileStore } from "./core/cache/file-store.js";
 import { createOutput } from "./core/cli/output.js";
 import { createPrompt } from "./core/cli/prompt.js";
 import { loadConfig } from "./core/config.js";
+import { listConnections, resolveConfigSource, resolveConnectionsDir, } from "./core/connections.js";
 import { createHttpClient } from "./core/http.js";
 import { createJsonApiClient } from "./core/jsonapi/client.js";
 import { buildPayloadFromParameters } from "./core/params/from-parameters.js";
@@ -26,9 +28,6 @@ import { fetchJsonSchema } from "./core/schema/jsonschema-source.js";
 import { toOperationVariant } from "./core/schema/to-jsonschema.js";
 import { validatePayload } from "./core/schema/validate.js";
 import { AuthError, ConfigError, exitCodeFor, ValidationError } from "./errors.js";
-function resolveConfigPath(override) {
-    return override ?? process.env.DROPSH_CONFIG ?? "dropsh.config.js";
-}
 // Normalizes a variadic --include option into a flat, trimmed list of field
 // names: splits any comma-containing entries (so both `--include a,b` and
 // `--include a b` work) and drops empty strings.
@@ -153,7 +152,9 @@ export function buildProgram(opts = {}) {
         .name("dropsh")
         .description("Entity-agnostic CLI for Drupal 11 JSON:API")
         .version("0.0.0")
-        .option("--config <path>", "path to config file (overrides DROPSH_CONFIG)")
+        .option("--config <path>", "path to config file (overrides every id-based selector)")
+        .option("--connection <id>", "named connection to use: <connections-dir>/<id>.js (overrides $DROPSH_CONFIG)")
+        .option("--connections-dir <path>", "where named connections live (overrides $DROPSH_CONNECTIONS_DIR)")
         .option("--auth-profile <id>", "auth profile to use (overrides the active profile and $DROPSH_AUTH_PROFILE)")
         .option("--format <id>", "output format: json (default) or a renderer id", "json")
         .option("--view-mode <name>", "entity view mode for interactive formats", "default");
@@ -163,11 +164,28 @@ export function buildProgram(opts = {}) {
         ((c) => {
             process.exitCode = c;
         });
+    /** The connections directory for this invocation: `--connections-dir` > env > default. */
+    function currentConnectionsDir() {
+        return resolveConnectionsDir({ flag: program.opts().connectionsDir });
+    }
+    /**
+     * The config file this invocation resolves to, and why. Every caller — the
+     * command context, the auth wiring, and `connections list` — reads this one
+     * answer, so what the listing claims and what the next command does cannot
+     * disagree.
+     */
+    function currentConfigSource() {
+        const o = program.opts();
+        return resolveConfigSource({
+            config: o.config,
+            connection: o.connection,
+            connectionsDir: currentConnectionsDir(),
+        });
+    }
     const contextFactory = opts.contextFactory ??
         (() => {
-            const o = program.opts();
-            const profile = o.authProfile ?? process.env.DROPSH_AUTH_PROFILE;
-            return defaultContext(resolveConfigPath(o.config), profile);
+            const profile = program.opts().authProfile ?? process.env.DROPSH_AUTH_PROFILE;
+            return defaultContext(currentConfigSource().path, profile);
         });
     const renderers = (opts.plugins ?? []).flatMap((p) => p.renderers ?? []);
     const output = createOutput({
@@ -279,7 +297,7 @@ export function buildProgram(opts = {}) {
         }
     }
     async function authDeps() {
-        const cfg = await loadConfig(resolveConfigPath(program.opts().config));
+        const cfg = await loadConfig(currentConfigSource().path);
         return {
             baseUrl: cfg.site.base_url,
             providers: collectProviders(cfg.plugins),
@@ -528,6 +546,27 @@ Example:
             });
         }, () => assertJsonOnly("schema"));
     });
+    const connections = program.command("connections").description("Manage named connections");
+    connections
+        .command("list")
+        .description("List the connections in the resolved connections directory")
+        .action(() => 
+    // Builds no CommandContext, so it works with no cwd config present.
+    run2(async () => {
+        await runConnectionsList({ dir: currentConnectionsDir(), resolved: currentConfigSource() }, {
+            list: listConnections,
+            // A table because a human asked what the connections are; an
+            // explicit --format json hands back the same data verbatim.
+            emit: (v) => {
+                if (program.getOptionValueSource("format") === "default") {
+                    stdout(`${renderConnectionsTable(v)}\n`);
+                }
+                else {
+                    output.emit(v);
+                }
+            },
+        });
+    }));
     const auth = program.command("auth").description("Manage authentication");
     auth
         .command("login")
@@ -558,17 +597,49 @@ Example:
     program.exitOverride();
     return program;
 }
-function earlyConfigArg(argv) {
+/**
+ * The config selectors as they appear in raw argv, for the pre-parse plugin
+ * bootstrap — which runs before commander sees any option. It feeds the same
+ * resolver the commands use, so the early and the late resolution cannot answer
+ * differently and load plugins from a different connection than the command
+ * being bootstrapped.
+ */
+export function earlyConfigArgs(argv) {
     const { values } = parseArgs({
         args: argv.slice(2),
-        options: { config: { type: "string" } },
+        options: {
+            config: { type: "string" },
+            connection: { type: "string" },
+            "connections-dir": { type: "string" },
+        },
         strict: false,
     });
-    return typeof values.config === "string" ? values.config : undefined;
+    const str = (v) => (typeof v === "string" ? v : undefined);
+    const config = str(values.config);
+    const connection = str(values.connection);
+    const connectionsDir = str(values["connections-dir"]);
+    return {
+        ...(config !== undefined ? { config } : {}),
+        ...(connection !== undefined ? { connection } : {}),
+        ...(connectionsDir !== undefined ? { connectionsDir } : {}),
+    };
 }
 export async function main() {
-    const configPath = resolveConfigPath(earlyConfigArg(process.argv));
-    const cfg = await loadConfig(configPath).catch(() => null);
+    const early = earlyConfigArgs(process.argv);
+    // An unresolvable selector is not reported here: the bootstrap only collects
+    // plugins, and commander's own resolution raises the error with its exit code.
+    const configPath = (() => {
+        try {
+            return resolveConfigSource({
+                ...early,
+                connectionsDir: resolveConnectionsDir({ flag: early.connectionsDir }),
+            }).path;
+        }
+        catch {
+            return null;
+        }
+    })();
+    const cfg = configPath === null ? null : await loadConfig(configPath).catch(() => null);
     const plugins = cfg?.plugins ?? [];
     const program = buildProgram({ plugins });
     try {

package/dist/src/plugin-api.d.ts

@@ -5,6 +5,8 @@ export type { AnyRenderer, InteractiveRenderer, RenderContext, Renderer, RenderS
 export { indexIncluded, isInteractive } from "./core/cli/render.js";
 export type { Config, SiteConfig } from "./core/config.js";
 export { loadConfig } from "./core/config.js";
+export type { ConfigSource, ConfigSourceKind, ConnectionEntry, ResolveConfigSourceInput, ResolveConnectionsDirInput, } from "./core/connections.js";
+export { CWD_CONFIG_FILE, listConnectionIds, listConnections, resolveConfigSource, resolveConnectionsDir, } from "./core/connections.js";
 export type { HttpClient, HttpRequest } from "./core/http.js";
 export { createHttpClient } from "./core/http.js";
 export type { DropSHOperation, JsonApiClient, JsonApiOptions, ResourceWriteBody, } from "./core/jsonapi/client.js";

package/dist/src/plugin-api.js

@@ -1,6 +1,7 @@
 export { basicAuthPlugin, basicAuthProvider } from "./core/auth/basic.js";
 export { indexIncluded, isInteractive } from "./core/cli/render.js";
 export { loadConfig } from "./core/config.js";
+export { CWD_CONFIG_FILE, listConnectionIds, listConnections, resolveConfigSource, resolveConnectionsDir, } from "./core/connections.js";
 export { createHttpClient } from "./core/http.js";
 export { createJsonApiClient } from "./core/jsonapi/client.js";
 export { buildPayloadFromParameters } from "./core/params/from-parameters.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dropsh",
-  "version": "0.6.1",
+  "version": "0.7.1",
   "description": "Entity-agnostic helper CLI for Drupal 11 JSON:API, used by the dropsh Claude skill for editorial publishing workflows.",
   "type": "module",
   "bin": {