dropsh 0.6.0 → 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/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;

package/dist/src/core/params/help.js

@@ -0,0 +1,148 @@
+import { indexSchemaFields, propertiesOf } from "./schema-fields.js";
+/**
+ * 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 const FIELD_PARAMETER_HELP = `
+Field parameters (instead of --data):
+  --<field> <value>          set a field, e.g. --title "Hello"
+  --<field>=<value>          same; also the form for many fields in one call
+  --<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
+
+Add --fields to list this bundle's actual field parameters and exit without
+sending anything. An unknown field name is rejected, never ignored.
+
+A value starting with -- needs the --<field>=<value> form. A field whose name
+collides with a reserved option (--bundle, --data, --dry-run, --no-validate,
+--fields, --format, --auth-profile, --config, --view-mode, --json) is reachable
+through --json <field>=<json> or --data, never as a bare --<field>.
+
+Example:
+  dropsh create node --bundle article --fields
+  dropsh create node --bundle article --title "Hello" --body.value "Text" --dry-run`;
+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;
+}
+function labelOf(node) {
+    if (!isRecord(node))
+        return undefined;
+    return typeof node.title === "string" ? node.title : undefined;
+}
+/** The command-line spelling, including how the value is written. */
+function spell(path, type) {
+    if (type === "array")
+        return `--json ${path}=<json>`;
+    if (type === "boolean")
+        return `--${path} [true|false]`;
+    return `--${path} <value>`;
+}
+function describeAttribute(path, node, required) {
+    const type = schemaTypeOf(node);
+    const label = labelOf(node);
+    return {
+        parameter: spell(path, type),
+        path,
+        ...(type !== undefined ? { type } : {}),
+        ...(label !== undefined ? { label } : {}),
+        ...(required ? { required: true } : {}),
+        ...(type === "boolean" ? { bare_flag: true } : {}),
+    };
+}
+/** An object attribute is settable only through its leaves, so recurse into them. */
+function describeAttributeTree(path, node, required) {
+    const props = schemaTypeOf(node) === "array" ? undefined : propertiesOf(node);
+    if (!props || Object.keys(props).length === 0) {
+        return [describeAttribute(path, node, required)];
+    }
+    const req = isRecord(node) && Array.isArray(node.required) ? node.required : [];
+    return Object.entries(props).flatMap(([sub, subNode]) => describeAttributeTree(`${path}.${sub}`, subNode, required && req.includes(sub)));
+}
+function describeRelationship(field) {
+    const targets = field.targetTypes ?? [];
+    const ambiguous = targets.length !== 1;
+    const label = labelOf(field.node);
+    return {
+        parameter: `--${field.name} ${ambiguous ? "<type>:<uuid>" : "<uuid>"}`,
+        path: field.name,
+        targets,
+        multiple: field.multiple === true,
+        ...(label !== undefined ? { label } : {}),
+        ...(ambiguous ? { requires_type_prefix: true } : {}),
+    };
+}
+/**
+ * Turn a resolved operation schema into the machine-readable field listing that
+ * `--fields` prints: every settable parameter, in schema declaration order.
+ */
+export function describeFields(schema) {
+    const index = indexSchemaFields(schema);
+    const attributeNode = propertiesOf(propertiesOf(schema)?.data)?.attributes;
+    const requiredNames = isRecord(attributeNode) && Array.isArray(attributeNode.required) ? attributeNode.required : [];
+    const attributes = [];
+    const relationships = [];
+    for (const name of index.order) {
+        const field = index.fields.get(name);
+        if (!field)
+            continue;
+        if (field.kind === "attribute") {
+            attributes.push(...describeAttributeTree(name, field.node, requiredNames.includes(name)));
+        }
+        else
+            relationships.push(describeRelationship(field));
+    }
+    return {
+        ...(index.resourceType !== undefined ? { type: index.resourceType } : {}),
+        attributes,
+        relationships,
+    };
+}
+/**
+ * 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 function renderFieldsTable(described) {
+    const { attributes, relationships } = described;
+    const head = `${described.type ?? "this bundle"} — field parameters`;
+    if (attributes.length === 0 && relationships.length === 0) {
+        return `${head}\n\nThe schema declares no field parameters for this bundle.`;
+    }
+    const rows = [];
+    for (const a of attributes) {
+        const notes = [a.type ?? "", a.required ? "required" : "", a.label ?? ""].filter((n) => n !== "");
+        rows.push([a.parameter, notes.join("  ")]);
+    }
+    const attributeRows = rows.length;
+    for (const r of relationships) {
+        const notes = [
+            r.targets.join(" | ") || "(no target type declared)",
+            r.multiple ? "repeatable" : "",
+            r.label ?? "",
+        ].filter((n) => n !== "");
+        rows.push([r.parameter, notes.join("  ")]);
+    }
+    const width = Math.max(...rows.map(([p]) => p.length)) + 2;
+    const line = ([p, notes]) => notes === "" ? `  ${p}` : `  ${p.padEnd(width)}${notes}`;
+    const out = [head];
+    if (attributeRows > 0) {
+        out.push("", "Attributes:", ...rows.slice(0, attributeRows).map(line));
+    }
+    if (relationships.length > 0) {
+        out.push("", "Relationships (take a UUID):", ...rows.slice(attributeRows).map(line));
+    }
+    return out.join("\n");
+}

package/dist/src/core/params/parse-args.d.ts

@@ -0,0 +1,18 @@
+export interface RawParameter {
+    /** Dotted path into the payload, e.g. "title" or "body.value". */
+    path: string;
+    value: string;
+    /** Which surface syntax produced it; "json" means `value` is raw JSON. */
+    form: "flag" | "json";
+    /**
+     * False for a bare `--field` with no following value. Whether that is legal
+     * depends on the field's schema type, so the decision belongs to the builder.
+     */
+    hasValue: boolean;
+}
+/**
+ * Parse the token stream Commander passes through for unknown options into an
+ * ordered parameter list. Purely syntactic: no schema is consulted, so an
+ * unknown field name is not an error here.
+ */
+export declare function parseFieldArgs(tokens: string[]): RawParameter[];

package/dist/src/core/params/parse-args.js

@@ -0,0 +1,75 @@
+import { ValidationError } from "../../errors.js";
+/**
+ * `--json` is the one collector: it takes `<field>=<json>` pairs rather than a
+ * value of its own, because a raw JSON value cannot be coerced from the leaf
+ * schema type. The collector name is matched before any other handling, so the
+ * pair's left-hand side is an arbitrary field path — including one that collides
+ * with a reserved option, or `json` itself. That makes `--json <field>=<json>` a
+ * second route to such a field besides `--data`; only the bare `--<field>` form
+ * is out of reach.
+ */
+const COLLECTORS = new Set(["json"]);
+function splitPair(pair, collector) {
+    const eq = pair.indexOf("=");
+    if (eq <= 0) {
+        throw new ValidationError(`--${collector} expects <field>=<value> pairs, got "${pair}"`);
+    }
+    return { path: pair.slice(0, eq), value: pair.slice(eq + 1) };
+}
+/**
+ * Parse the token stream Commander passes through for unknown options into an
+ * ordered parameter list. Purely syntactic: no schema is consulted, so an
+ * unknown field name is not an error here.
+ */
+export function parseFieldArgs(tokens) {
+    const out = [];
+    let i = 0;
+    while (i < tokens.length) {
+        const token = tokens[i];
+        if (!token.startsWith("--")) {
+            throw new ValidationError(`unexpected argument "${token}"; field parameters are long options (--<field> <value>)`);
+        }
+        const body = token.slice(2);
+        if (body.length === 0) {
+            throw new ValidationError('"--" is not a field parameter');
+        }
+        const eq = body.indexOf("=");
+        const name = eq === -1 ? body : body.slice(0, eq);
+        if (COLLECTORS.has(name)) {
+            const pairs = [];
+            if (eq !== -1) {
+                pairs.push(body.slice(eq + 1));
+                i += 1;
+            }
+            else {
+                i += 1;
+                while (i < tokens.length && !tokens[i].startsWith("--")) {
+                    pairs.push(tokens[i]);
+                    i += 1;
+                }
+            }
+            if (pairs.length === 0) {
+                throw new ValidationError(`--${name} expects at least one <field>=<value> pair`);
+            }
+            for (const pair of pairs) {
+                const { path, value } = splitPair(pair, name);
+                out.push({ path, value, form: "json", hasValue: true });
+            }
+            continue;
+        }
+        if (eq !== -1) {
+            out.push({ path: name, value: body.slice(eq + 1), form: "flag", hasValue: true });
+            i += 1;
+            continue;
+        }
+        const next = tokens[i + 1];
+        if (next !== undefined && !next.startsWith("--")) {
+            out.push({ path: name, value: next, form: "flag", hasValue: true });
+            i += 2;
+            continue;
+        }
+        out.push({ path: name, value: "", form: "flag", hasValue: false });
+        i += 1;
+    }
+    return out;
+}

package/dist/src/core/params/schema-fields.d.ts

@@ -0,0 +1,20 @@
+export interface FieldDescriptor {
+    name: string;
+    kind: "attribute" | "relationship";
+    /** The field's own subschema, as declared under attributes/relationships. */
+    node: unknown;
+    /** Relationship only: the resource types its `data.type` accepts. */
+    targetTypes?: string[];
+    /** Relationship only: true when `data` is an array. */
+    multiple?: boolean;
+}
+export interface SchemaFieldIndex {
+    /** From `data.properties.type.const`, else the first `enum` entry. */
+    resourceType?: string;
+    fields: Map<string, FieldDescriptor>;
+    /** Schema declaration order: attributes first, then relationships. */
+    order: string[];
+}
+/** The `properties` map of a schema node, or undefined when it has none. */
+export declare function propertiesOf(node: unknown): Record<string, unknown> | undefined;
+export declare function indexSchemaFields(schema: unknown): SchemaFieldIndex;

package/dist/src/core/params/schema-fields.js

@@ -0,0 +1,65 @@
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** The `properties` map of a schema node, or undefined when it has none. */
+export function propertiesOf(node) {
+    if (!isRecord(node))
+        return undefined;
+    const props = node.properties;
+    return isRecord(props) ? props : undefined;
+}
+function resourceTypeOf(dataNode) {
+    const typeNode = propertiesOf(dataNode)?.type;
+    if (!isRecord(typeNode))
+        return undefined;
+    if (typeof typeNode.const === "string")
+        return typeNode.const;
+    if (Array.isArray(typeNode.enum) && typeof typeNode.enum[0] === "string") {
+        return typeNode.enum[0];
+    }
+    return undefined;
+}
+/**
+ * A relationship declares its payload under `data`, either as a single resource
+ * identifier object or as an array of them. Both carry the allowed resource
+ * types in their `type` node's `enum`/`const`, which is what lets a bare UUID on
+ * the command line become a complete identifier object.
+ */
+function describeRelationship(name, node) {
+    const dataNode = propertiesOf(node)?.data;
+    const multiple = isRecord(dataNode) && dataNode.type === "array";
+    const itemNode = multiple ? dataNode.items : dataNode;
+    const typeNode = propertiesOf(itemNode)?.type;
+    let targetTypes;
+    if (isRecord(typeNode)) {
+        if (Array.isArray(typeNode.enum)) {
+            targetTypes = typeNode.enum.filter((t) => typeof t === "string");
+        }
+        else if (typeof typeNode.const === "string") {
+            targetTypes = [typeNode.const];
+        }
+    }
+    return {
+        name,
+        kind: "relationship",
+        node,
+        multiple,
+        ...(targetTypes !== undefined ? { targetTypes } : {}),
+    };
+}
+export function indexSchemaFields(schema) {
+    const dataNode = propertiesOf(schema)?.data;
+    const dataProps = propertiesOf(dataNode);
+    const fields = new Map();
+    const order = [];
+    for (const [name, node] of Object.entries(propertiesOf(dataProps?.attributes) ?? {})) {
+        fields.set(name, { name, kind: "attribute", node });
+        order.push(name);
+    }
+    for (const [name, node] of Object.entries(propertiesOf(dataProps?.relationships) ?? {})) {
+        fields.set(name, describeRelationship(name, node));
+        order.push(name);
+    }
+    const resourceType = resourceTypeOf(dataNode);
+    return { fields, order, ...(resourceType !== undefined ? { resourceType } : {}) };
+}

package/dist/src/index.js

@@ -1,13 +1,14 @@
 #!/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 { 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";
@@ -17,11 +18,14 @@ import { createPrompt } from "./core/cli/prompt.js";
 import { loadConfig } from "./core/config.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";
+import { AuthError, ConfigError, exitCodeFor, ValidationError } from "./errors.js";
 function resolveConfigPath(override) {
     return override ?? process.env.DROPSH_CONFIG ?? "dropsh.config.js";
 }
@@ -201,6 +205,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") {
@@ -347,54 +418,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,21 +504,29 @@ 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 auth = program.command("auth").description("Manage authentication");
     auth

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.6.1",
   "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",