dropsh 0.6.0 → 0.7.0

package/dist/src/index.js

@@ -1,13 +1,15 @@
 #!/usr/bin/env node
 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";
 import { applyOperationSchemaPlugins, operationHookPluginIds, runSchema, SCHEMA_PIPELINE_VERSION, schemaCacheMetadataMatches, siteCacheRoot, } from "./commands/schema.js";
 import { runSearch } from "./commands/search.js";
-import { runUpdate } from "./commands/update.js";
+import { assertUpdateTarget, runUpdate, } from "./commands/update.js";
 import { runUploadFile } from "./commands/upload-file.js";
 import { collectProviders, defaultProvider, providerById, sessionlessProvider, } from "./core/auth/registry.js";
 import { readProfiles, writeProfile } from "./core/auth/session-store.js";
@@ -15,16 +17,17 @@ 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";
+import { describeFields, FIELD_PARAMETER_HELP, renderFieldsTable } from "./core/params/help.js";
+import { parseFieldArgs } from "./core/params/parse-args.js";
 import { composeRequestHooks } from "./core/request-hooks.js";
 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 } from "./errors.js";
-function resolveConfigPath(override) {
-    return override ?? process.env.DROPSH_CONFIG ?? "dropsh.config.js";
-}
+import { AuthError, ConfigError, exitCodeFor, ValidationError } from "./errors.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.
@@ -149,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");
@@ -159,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({
@@ -201,6 +223,73 @@ export function buildProgram(opts = {}) {
             throw new ConfigError(`Unknown format '${f}'. Available: ${["json", ...renderers.map((r) => r.id)].join(", ")}`);
         }
     }
+    /**
+     * Print a resolved schema as its field listing: a table for a human, or the
+     * same data verbatim on an explicit `--format json`. Shared by `create`,
+     * `update` and `schema`, so the three cannot drift.
+     */
+    function emitFieldListing(schema, rctx) {
+        const described = describeFields(schema);
+        if (program.getOptionValueSource("format") === "default") {
+            stdout(`${renderFieldsTable(described)}\n`);
+        }
+        else {
+            output.emit(described, rctx);
+        }
+    }
+    /**
+     * The write-command wiring `create` and `update` share: decide `--data` vs
+     * field parameters, fetch the operation schema at most once, build the payload
+     * from the parameters, and hand back the args/deps both `runCreate` and
+     * `runUpdate` accept. The two commands differ only in how they identify their
+     * target, which is why that part stays in each action.
+     */
+    async function writeWiring(input) {
+        const { ctx, options } = input;
+        // --fields is a discovery request, not a write: resolve the schema through
+        // the normal fetch-and-cache pipeline, print the parameters, send nothing.
+        // It reads as a table because a human asked what the fields are; an explicit
+        // --format json hands back the same data verbatim for a caller to consume.
+        if (options.fields === true) {
+            emitFieldListing(await loadOrFetchSchema(ctx, input.schemaTarget, input.operation), input.rctx);
+            return "listed";
+        }
+        // Exactly one route produces the document, and it is settled here so the
+        // command itself only ever receives a finished payload.
+        const fields = parseFieldArgs(input.tokens);
+        if (options.data !== undefined && fields.length > 0) {
+            throw new ValidationError("--data and field parameters are mutually exclusive; use one or the other");
+        }
+        if (options.data === undefined && fields.length === 0) {
+            throw new ValidationError("provide either --data or field parameters (--<field> <value>)");
+        }
+        let cached;
+        const schema = async () => (cached ??= await loadOrFetchSchema(ctx, input.schemaTarget, input.operation));
+        let payload;
+        if (options.data !== undefined) {
+            payload = await readDataArg(options.data);
+        }
+        else {
+            input.guard?.();
+            payload = buildPayloadFromParameters({
+                schema: await schema(),
+                parameters: fields,
+                operation: input.operation,
+                ...(input.id !== undefined ? { id: input.id } : {}),
+                resourceType: input.resourceType,
+            });
+        }
+        const args = { payload };
+        if (options.dryRun !== undefined)
+            args.dryRun = options.dryRun;
+        if (options.validate === false)
+            args.noValidate = true;
+        const deps = { client: ctx.client, emit: (v) => output.emit(v, input.rctx) };
+        if (!args.noValidate) {
+            deps.validate = async (payload, t) => validatePayload(await schema(), payload, t);
+        }
+        return { args, deps };
+    }
     function assertJsonOnly(command) {
         const f = currentFormat();
         if (f !== "json") {
@@ -208,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),
@@ -347,54 +436,61 @@ Example:
         .command("create <entity_type>")
         .description("Create an entity of given type/bundle")
         .requiredOption("--bundle <bundle>")
-        .requiredOption("--data <json>", "inline JSON or @path")
+        .option("--data <json>", "inline JSON or @path")
         .option("--dry-run")
         .option("--no-validate", "skip client-side schema validation")
-        .action((entityType, o) => {
-        const args = { entityType, bundle: o.bundle, dataArg: o.data };
-        if (o.dryRun !== undefined)
-            args.dryRun = o.dryRun;
-        if (o.validate === false)
-            args.noValidate = true;
+        .option("--fields", "list this bundle's field parameters and exit")
+        .allowUnknownOption()
+        .addHelpText("after", FIELD_PARAMETER_HELP)
+        .action((entityType, o, cmd) => {
         return run(async (ctx) => {
-            const rctx = { command: "create", entityType, bundle: o.bundle };
-            const deps = { client: ctx.client, emit: (v) => output.emit(v, rctx) };
-            if (!args.noValidate) {
-                deps.validate = async (payload, target) => {
-                    const schema = await loadOrFetchSchema(ctx, target, "create");
-                    validatePayload(schema, payload, target);
-                };
-            }
-            await runCreate(args, deps);
+            const wiring = await writeWiring({
+                ctx,
+                operation: "create",
+                schemaTarget: `${entityType}/${o.bundle}`,
+                resourceType: `${entityType}--${o.bundle}`,
+                tokens: cmd.args.slice(1),
+                rctx: { command: "create", entityType, bundle: o.bundle },
+                options: o,
+            });
+            if (wiring === "listed")
+                return;
+            await runCreate({ entityType, bundle: o.bundle, ...wiring.args }, wiring.deps);
         }, assertRenderable);
     });
     program
         .command("update <target>")
         .description("Update an existing entity")
-        .requiredOption("--data <json>", "inline JSON or @path")
+        .option("--data <json>", "inline JSON or @path")
         .option("--dry-run")
         .option("--no-validate", "skip client-side schema validation")
-        .action((target, o) => {
-        const args = { target, dataArg: o.data };
-        if (o.dryRun !== undefined)
-            args.dryRun = o.dryRun;
-        if (o.validate === false)
-            args.noValidate = true;
+        .option("--fields", "list this bundle's field parameters and exit")
+        .allowUnknownOption()
+        .addHelpText("after", FIELD_PARAMETER_HELP)
+        .action((target, o, cmd) => {
         return run(async (ctx) => {
-            const [entityType, bundle] = target.split("/");
+            const [entityType, bundle, id] = target.split("/");
             const rctx = { command: "update", target };
             if (entityType !== undefined)
                 rctx.entityType = entityType;
             if (bundle !== undefined)
                 rctx.bundle = bundle;
-            const deps = { client: ctx.client, emit: (v) => output.emit(v, rctx) };
-            if (!args.noValidate) {
-                deps.validate = async (payload, t) => {
-                    const schema = await loadOrFetchSchema(ctx, t, "update");
-                    validatePayload(schema, payload, t);
-                };
-            }
-            await runUpdate(args, deps);
+            const wiring = await writeWiring({
+                ctx,
+                operation: "update",
+                schemaTarget: `${entityType}/${bundle}`,
+                resourceType: `${entityType}--${bundle}`,
+                tokens: cmd.args.slice(1),
+                rctx,
+                options: o,
+                ...(id !== undefined ? { id } : {}),
+                // Guard the target before building, so a malformed one is reported by
+                // its own message rather than as a missing data.id.
+                guard: () => assertUpdateTarget(target),
+            });
+            if (wiring === "listed")
+                return;
+            await runUpdate({ target, ...wiring.args }, wiring.deps);
         }, assertRenderable);
     });
     program
@@ -426,22 +522,51 @@ Example:
         .description("Catalog (no target) or JSON Schema for <entity>/<bundle>")
         .option("--for <op>", "create|update", "create")
         .option("--refresh", "bypass cache for this call")
+        .option("--fields", "list the target's field parameters instead of its schema")
         .action((target, o) => {
         const operation = o.for === "update" ? "update" : "create";
         const schemaArgs = target !== undefined
             ? { target, operation, refresh: Boolean(o.refresh) }
             : { operation, refresh: Boolean(o.refresh) };
-        return run((ctx) => runSchema(schemaArgs, {
-            http: ctx.http,
-            auth: ctx.auth,
-            baseUrl: ctx.baseUrl,
-            jsonapiPrefix: ctx.jsonapiPrefix,
-            cwd: ctx.cwd,
-            emit: output.emit,
-            warn: (m) => stderr(`${m}\n`),
-            plugins: ctx.plugins,
-        }), () => assertJsonOnly("schema"));
+        return run((ctx) => {
+            if (o.fields === true && target === undefined) {
+                throw new ValidationError("--fields needs a target: dropsh schema <entity_type>/<bundle> --fields");
+            }
+            // --fields is the same schema, viewed as its parameters: swapping the
+            // emitter inherits runSchema's caching and --refresh untouched.
+            return runSchema(schemaArgs, {
+                http: ctx.http,
+                auth: ctx.auth,
+                baseUrl: ctx.baseUrl,
+                jsonapiPrefix: ctx.jsonapiPrefix,
+                cwd: ctx.cwd,
+                emit: o.fields === true ? (schema) => emitFieldListing(schema) : output.emit,
+                warn: (m) => stderr(`${m}\n`),
+                plugins: ctx.plugins,
+            });
+        }, () => 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")
@@ -472,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

@@ -12,6 +12,11 @@ export { createJsonApiClient } from "./core/jsonapi/client.js";
 export type { Collection, FilterOp } from "./core/jsonapi/collection.js";
 export type { JsonApiResourceObject, Resource, } from "./core/jsonapi/resource.js";
 export type { JsonApiDocument, JsonApiResource } from "./core/jsonapi/types.js";
+export type { BuildPayloadInput } from "./core/params/from-parameters.js";
+export { buildPayloadFromParameters } from "./core/params/from-parameters.js";
+export type { RawParameter } from "./core/params/parse-args.js";
+export type { FieldDescriptor, SchemaFieldIndex } from "./core/params/schema-fields.js";
+export { indexSchemaFields, propertiesOf } from "./core/params/schema-fields.js";
 export type { DropSHPlugin, PluginContext, PluginDescriptor, RequestContext, SchemaOperation, } from "./core/plugin.js";
 export { composePlugins } from "./core/plugin.js";
 export { AuthError, ConfigError, HttpError, PluginError } from "./errors.js";

package/dist/src/plugin-api.js

@@ -3,5 +3,7 @@ export { indexIncluded, isInteractive } from "./core/cli/render.js";
 export { loadConfig } from "./core/config.js";
 export { createHttpClient } from "./core/http.js";
 export { createJsonApiClient } from "./core/jsonapi/client.js";
+export { buildPayloadFromParameters } from "./core/params/from-parameters.js";
+export { indexSchemaFields, propertiesOf } from "./core/params/schema-fields.js";
 export { composePlugins } from "./core/plugin.js";
 export { AuthError, ConfigError, HttpError, PluginError } from "./errors.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dropsh",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Entity-agnostic helper CLI for Drupal 11 JSON:API, used by the dropsh Claude skill for editorial publishing workflows.",
   "type": "module",
   "bin": {
@@ -66,8 +66,8 @@
     "test:watch": "vitest",
     "test:integration": "pnpm run build && pnpm run build:packages && vitest run -c vitest.config.integration.ts",
     "typecheck": "pnpm run build:packages && tsc --noEmit && pnpm -r run typecheck",
-    "lint": "biome check src/ packages/ plugins/ tests/integrations/helpers/ tests/integrations/schema/ tests/integrations/*.ts",
-    "lint:fix": "biome check --write src/ packages/ plugins/ tests/integrations/helpers/ tests/integrations/schema/ tests/integrations/*.ts",
+    "lint": "biome check src/ packages/ plugins/ tests/integrations/helpers/ tests/integrations/params/ tests/integrations/schema/ tests/integrations/*.ts",
+    "lint:fix": "biome check --write src/ packages/ plugins/ tests/integrations/helpers/ tests/integrations/params/ tests/integrations/schema/ tests/integrations/*.ts",
     "drupal:up": "bash tests/integrations/bin/drupal-up.sh",
     "drupal:down": "bash tests/integrations/bin/drupal-down.sh",
     "init-worktree": "node scripts/init-worktree.mjs",