dropsh 0.5.8 → 0.6.1

package/README.md

@@ -295,17 +295,170 @@ 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]
 ```
 
 `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/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/types.d.ts

@@ -1,13 +1,26 @@
 import type { HttpClient, HttpRequest } from "../http.js";
+/**
+ * Outcome of a reactive credential renewal. On failure the renewal cause is
+ * carried back so the caller can surface *why* renewal failed instead of the
+ * bare, unexplained 401 that first triggered it.
+ */
+export type RenewOutcome = {
+    ok: true;
+} | {
+    ok: false;
+    cause?: unknown;
+};
 export interface AuthAdapter {
     apply(req: HttpRequest): Promise<HttpRequest>;
     /**
      * Force a credential refresh after the server rejected the current token (401),
-     * then persist it. Returns true if renewal succeeded (caller retries the request
-     * once), false if it could not renew (caller surfaces the original 401).
-     * Providers that cannot renew (e.g. basic auth) omit this.
+     * then persist it. Resolves `{ ok: true }` when renewal succeeded (caller
+     * retries the request once) or `{ ok: false, cause }` when it could not renew,
+     * where `cause` is the error explaining the failure (the caller surfaces it in
+     * place of the original 401). Providers that cannot renew (e.g. basic auth)
+     * omit this method.
      */
-    renew?(): Promise<boolean>;
+    renew?(): Promise<RenewOutcome>;
 }
 /** Provider-specific opaque session payload persisted to the state dir. */
 export type AuthSession = Record<string, unknown>;

package/dist/src/core/jsonapi/client.d.ts

@@ -1,8 +1,9 @@
 import type { DrupalJsonApiParams } from "drupal-jsonapi-params";
 import type { AuthAdapter } from "../auth/types.js";
-import type { HttpClient } from "../http.js";
+import type { HttpClient, HttpRequest } from "../http.js";
 import { type Collection } from "./collection.js";
 import { type Resource } from "./resource.js";
+export type DropSHOperation = "read" | "search" | "create" | "update" | "delete" | "upload";
 /** Attributes/relationships payload accepted by create/update/upsert. */
 export interface ResourceWriteBody {
     attributes?: Record<string, unknown>;
@@ -35,5 +36,6 @@ export interface JsonApiOptions {
     prefix: string;
     http: HttpClient;
     auth: AuthAdapter;
+    alterRequest?: (req: HttpRequest, operation: DropSHOperation, entityType?: string, bundle?: string) => Promise<HttpRequest>;
 }
 export declare function createJsonApiClient(opts: JsonApiOptions): JsonApiClient;

package/dist/src/core/jsonapi/client.js

@@ -12,27 +12,45 @@ const JSONAPI_HEADERS = {
     Accept: "application/vnd.api+json",
     "Content-Type": "application/vnd.api+json",
 };
+function targetFromPath(path) {
+    const [entityType, bundle] = path.split("/").filter(Boolean);
+    return {
+        ...(entityType !== undefined ? { entityType } : {}),
+        ...(bundle !== undefined ? { bundle } : {}),
+    };
+}
+function getOperation(path) {
+    const segments = path.split("/").filter(Boolean);
+    return segments.length === 0 || segments.length >= 3 ? "read" : "search";
+}
 export function createJsonApiClient(opts) {
-    async function send(method, url, body, extraHeaders = {}) {
+    async function send(method, path, operation, body, extraHeaders = {}, queryString = "") {
         const reqBase = {
             method,
-            url,
+            url: joinUrl(opts.baseUrl, opts.prefix, path) + queryString,
             headers: { ...JSONAPI_HEADERS, ...extraHeaders },
         };
         const req = body !== undefined ? { ...reqBase, body } : reqBase;
+        const authenticatedRequest = await opts.auth.apply(req);
+        const { entityType, bundle } = targetFromPath(path);
+        const alteredRequest = opts.alterRequest
+            ? await opts.alterRequest(authenticatedRequest, operation, entityType, bundle)
+            : authenticatedRequest;
         let res;
         try {
-            res = await opts.http.send(await opts.auth.apply(req));
+            res = await opts.http.send(alteredRequest);
         }
         catch (err) {
             // The server rejected the token (401). Ask the auth adapter to renew and,
-            // if it could, retry the request exactly once with a fresh token.
+            // if it could, retry the request exactly once with a fresh token. If it
+            // could not, surface the renewal cause (e.g. an unconfigured secret) so
+            // the caller sees *why* renewal failed, not just the original 401.
             if (!(err instanceof HttpError) || err.status !== 401 || !opts.auth.renew)
                 throw err;
-            const renewed = await opts.auth.renew();
-            if (!renewed)
-                throw err;
-            res = await opts.http.send(await opts.auth.apply(req));
+            const outcome = await opts.auth.renew();
+            if (!outcome.ok)
+                throw outcome.cause ?? err;
+            res = await opts.http.send(await opts.auth.apply(alteredRequest));
         }
         if (res.status === 204 || res.body.length === 0)
             return { ok: true };
@@ -41,19 +59,19 @@ export function createJsonApiClient(opts) {
     const client = {
         async get(path, params) {
             const qs = params ? `?${params.getQueryString()}` : "";
-            return send("GET", joinUrl(opts.baseUrl, opts.prefix, path) + qs);
+            return send("GET", path, getOperation(path), undefined, {}, qs);
         },
         async post(path, body) {
-            return send("POST", joinUrl(opts.baseUrl, opts.prefix, path), JSON.stringify(body));
+            return send("POST", path, "create", JSON.stringify(body));
         },
         async patch(path, body) {
-            return send("PATCH", joinUrl(opts.baseUrl, opts.prefix, path), JSON.stringify(body));
+            return send("PATCH", path, "update", JSON.stringify(body));
         },
         async delete(path) {
-            return send("DELETE", joinUrl(opts.baseUrl, opts.prefix, path));
+            return send("DELETE", path, "delete");
         },
         async upload(path, filename, data) {
-            return send("POST", joinUrl(opts.baseUrl, opts.prefix, path), data, {
+            return send("POST", path, "upload", data, {
                 "Content-Type": "application/octet-stream",
                 "Content-Disposition": `file; filename="${filename}"`,
             });

package/dist/src/core/params/from-parameters.d.ts

@@ -0,0 +1,12 @@
+import type { RawParameter } from "./parse-args.js";
+export interface BuildPayloadInput {
+    /** The resolved operation schema, plugin extensions already applied. */
+    schema: unknown;
+    parameters: RawParameter[];
+    operation: "create" | "update";
+    /** Required for `update`: becomes `data.id`. */
+    id?: string;
+    /** Fallback resource type when the schema carries no `type` const/enum. */
+    resourceType?: string;
+}
+export declare function buildPayloadFromParameters(input: BuildPayloadInput): unknown;

package/dist/src/core/params/from-parameters.js

@@ -0,0 +1,209 @@
+import { ValidationError } from "../../errors.js";
+import { indexSchemaFields, propertiesOf, } from "./schema-fields.js";
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function schemaTypeOf(node) {
+    if (!isRecord(node))
+        return undefined;
+    const t = node.type;
+    if (typeof t === "string")
+        return t;
+    if (Array.isArray(t))
+        return t.find((x) => typeof x === "string" && x !== "null");
+    return undefined;
+}
+/**
+ * Convert one command-line string into the value the leaf schema node asks for.
+ * A non-convertible value is rejected here rather than left for Ajv, because
+ * `--no-validate` must not turn a wrong type into a silently wrong payload.
+ */
+function coerce(node, param, label) {
+    const type = schemaTypeOf(node);
+    if (!param.hasValue) {
+        if (type === "boolean")
+            return true;
+        throw new ValidationError(`missing value for --${label}${type !== undefined ? ` (expected ${type})` : ""}`);
+    }
+    if (type === "boolean") {
+        if (param.value === "true")
+            return true;
+        if (param.value === "false")
+            return false;
+        throw new ValidationError(`--${label} expects true or false, got "${param.value}"`);
+    }
+    if (type === "integer" || type === "number") {
+        const n = Number(param.value);
+        if (param.value.trim() === "" || !Number.isFinite(n)) {
+            throw new ValidationError(`--${label} expects ${type}, got "${param.value}"`);
+        }
+        if (type === "integer" && !Number.isInteger(n)) {
+            throw new ValidationError(`--${label} expects integer, got "${param.value}"`);
+        }
+        return n;
+    }
+    return param.value;
+}
+function parseJsonValue(param) {
+    try {
+        return JSON.parse(param.value);
+    }
+    catch (err) {
+        throw new ValidationError(`--json ${param.path} is not valid JSON: ${err.message}`);
+    }
+}
+/**
+ * Re-emit an object with its keys in the order its subschema declares them, so
+ * the same fields always serialise to the same bytes.
+ */
+function ordered(node, value) {
+    if (Array.isArray(value)) {
+        const items = isRecord(node) ? node.items : undefined;
+        return value.map((entry) => ordered(items, entry));
+    }
+    if (!isRecord(value))
+        return value;
+    const props = propertiesOf(node);
+    const keys = Object.keys(value);
+    const declared = props ? Object.keys(props).filter((k) => keys.includes(k)) : [];
+    const extra = keys.filter((k) => !declared.includes(k)).sort();
+    const out = {};
+    for (const key of [...declared, ...extra]) {
+        out[key] = ordered(props?.[key], value[key]);
+    }
+    return out;
+}
+/**
+ * Walk a dotted path into a field's subschema, rejecting a segment the schema
+ * does not declare. Returns the leaf node the value must satisfy.
+ */
+function resolveLeaf(field, segments) {
+    let node = field.node;
+    for (const segment of segments) {
+        const props = propertiesOf(node);
+        const next = props?.[segment];
+        if (next === undefined) {
+            throw new ValidationError(`unknown sub-property '${segment}' of '${field.name}'${props ? `; known: ${Object.keys(props).join(", ")}` : ""}`);
+        }
+        node = next;
+    }
+    return node;
+}
+function assign(target, segments, value, label) {
+    let cursor = target;
+    for (const segment of segments.slice(0, -1)) {
+        const existing = cursor[segment];
+        if (existing === undefined) {
+            const created = {};
+            cursor[segment] = created;
+            cursor = created;
+        }
+        else if (isRecord(existing)) {
+            cursor = existing;
+        }
+        else {
+            throw new ValidationError(`parameter '${label}' conflicts with an earlier value`);
+        }
+    }
+    const leaf = segments[segments.length - 1];
+    if (leaf in cursor) {
+        throw new ValidationError(`parameter '${label}' was given more than once`);
+    }
+    cursor[leaf] = value;
+}
+function unknownParameter(name, index) {
+    const attributes = [];
+    const relationships = [];
+    for (const field of index.fields.values()) {
+        (field.kind === "attribute" ? attributes : relationships).push(field.name);
+    }
+    throw new ValidationError(`unknown parameter '${name}'. Known attributes: ${attributes.join(", ") || "(none)"}. ` +
+        `Known relationships: ${relationships.join(", ") || "(none)"}.`);
+}
+/**
+ * A relationship parameter is a bare UUID whenever the schema allows exactly one
+ * target type, and `<type>:<uuid>` when it allows several. The UUID itself never
+ * contains a colon, so the split is unambiguous.
+ */
+function resourceIdentifier(field, param) {
+    if (!param.hasValue) {
+        throw new ValidationError(`missing value for --${field.name} (expected a UUID)`);
+    }
+    const allowed = field.targetTypes ?? [];
+    const colon = param.value.lastIndexOf(":");
+    if (colon > 0) {
+        const type = param.value.slice(0, colon);
+        const id = param.value.slice(colon + 1);
+        if (allowed.length > 0 && !allowed.includes(type)) {
+            throw new ValidationError(`'${type}' is not an allowed target type for '${field.name}'; allowed: ${allowed.join(", ")}`);
+        }
+        return { type, id };
+    }
+    if (allowed.length === 0) {
+        throw new ValidationError(`relationship '${field.name}' declares no target type in the schema; pass <type>:<uuid>`);
+    }
+    if (allowed.length > 1) {
+        throw new ValidationError(`relationship '${field.name}' allows several target types (${allowed.join(", ")}); ` +
+            "pass <type>:<uuid>");
+    }
+    return { type: allowed[0], id: param.value };
+}
+export function buildPayloadFromParameters(input) {
+    const index = indexSchemaFields(input.schema);
+    const attributes = {};
+    const relationships = new Map();
+    for (const param of input.parameters) {
+        const segments = param.path.split(".");
+        const name = segments[0];
+        const field = index.fields.get(name);
+        if (!field)
+            unknownParameter(name, index);
+        if (field.kind === "relationship") {
+            if (segments.length > 1) {
+                throw new ValidationError(`relationship '${name}' takes a UUID, not a sub-path ('${param.path}')`);
+            }
+            const collected = relationships.get(name) ?? [];
+            if (collected.length > 0 && field.multiple !== true) {
+                throw new ValidationError(`relationship '${name}' accepts a single value; it was given more than once`);
+            }
+            collected.push(resourceIdentifier(field, param));
+            relationships.set(name, collected);
+            continue;
+        }
+        const tail = segments.slice(1);
+        const leaf = resolveLeaf(field, tail);
+        const value = param.form === "json"
+            ? ordered(leaf, parseJsonValue(param))
+            : coerce(leaf, param, param.path);
+        assign(attributes, segments, value, param.path);
+    }
+    const resourceType = index.resourceType ?? input.resourceType;
+    if (resourceType === undefined) {
+        throw new ValidationError("cannot determine the JSON:API resource type: the schema declares no type and no fallback was given");
+    }
+    const data = { type: resourceType };
+    if (input.operation === "update") {
+        if (input.id === undefined || input.id === "") {
+            throw new ValidationError("update requires the entity id for data.id");
+        }
+        data.id = input.id;
+    }
+    const attributeNode = propertiesOf(propertiesOf(input.schema)?.data)?.attributes;
+    if (Object.keys(attributes).length > 0) {
+        data.attributes = ordered(attributeNode, attributes);
+    }
+    if (relationships.size > 0) {
+        const out = {};
+        for (const name of index.order) {
+            const collected = relationships.get(name);
+            if (!collected)
+                continue;
+            const field = index.fields.get(name);
+            out[name] = {
+                data: field.multiple === true ? collected : collected[0],
+            };
+        }
+        data.relationships = out;
+    }
+    return { data };
+}

package/dist/src/core/params/help.d.ts

@@ -0,0 +1,46 @@
+/**
+ * The `--help` block for the write commands. It documents the *forms* only and
+ * points at `--fields` for the bundle's actual field names: Commander renders
+ * help synchronously, so it cannot resolve a schema, while `--fields` runs in
+ * the action and goes through the normal fetch-and-cache pipeline.
+ */
+export declare const FIELD_PARAMETER_HELP = "\nField parameters (instead of --data):\n  --<field> <value>          set a field, e.g. --title \"Hello\"\n  --<field>=<value>          same; also the form for many fields in one call\n  --<field>.<sub> <value>    set a sub-property, e.g. --body.value \"Text\"\n  --<relationship> <uuid>    reference by UUID; repeat for a multi-valued field\n  --json <field>=<json>      raw JSON value, for arrays of objects\n\nAdd --fields to list this bundle's actual field parameters and exit without\nsending anything. An unknown field name is rejected, never ignored.\n\nA value starting with -- needs the --<field>=<value> form. A field whose name\ncollides with a reserved option (--bundle, --data, --dry-run, --no-validate,\n--fields, --format, --auth-profile, --config, --view-mode, --json) is reachable\nthrough --json <field>=<json> or --data, never as a bare --<field>.\n\nExample:\n  dropsh create node --bundle article --fields\n  dropsh create node --bundle article --title \"Hello\" --body.value \"Text\" --dry-run";
+export interface AttributeDescription {
+    /** The complete command-line spelling, value placeholder included. */
+    parameter: string;
+    /** Dotted path into `data.attributes`. */
+    path: string;
+    type?: string;
+    /** The field's human label, from the schema's `title`. */
+    label?: string;
+    /** Present only when the schema requires the field. */
+    required?: true;
+    /** Present only when the field can be given as a bare `--flag`. */
+    bare_flag?: true;
+}
+export interface RelationshipDescription {
+    parameter: string;
+    path: string;
+    targets: string[];
+    multiple: boolean;
+    /** The relationship's human label, from the schema's `title`. */
+    label?: string;
+    /** Present only when several target types make `<type>:<uuid>` mandatory. */
+    requires_type_prefix?: true;
+}
+export interface FieldsDescription {
+    type?: string;
+    attributes: AttributeDescription[];
+    relationships: RelationshipDescription[];
+}
+/**
+ * Turn a resolved operation schema into the machine-readable field listing that
+ * `--fields` prints: every settable parameter, in schema declaration order.
+ */
+export declare function describeFields(schema: unknown): FieldsDescription;
+/**
+ * Render the field listing as an aligned, human-readable table — what `--fields`
+ * prints by default. `--format json` yields `describeFields` verbatim instead,
+ * for a caller that wants to consume it.
+ */
+export declare function renderFieldsTable(described: FieldsDescription): string;