dropsh 0.5.8 → 0.6.1

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/core/plugin.d.ts

@@ -1,7 +1,8 @@
 import type { Command } from "commander";
 import type { AuthAdapter, AuthProvider } from "./auth/types.js";
 import type { AnyRenderer } from "./cli/render.js";
-import type { HttpClient } from "./http.js";
+import type { HttpClient, HttpRequest } from "./http.js";
+import type { DropSHOperation } from "./jsonapi/client.js";
 import type { Operation } from "./schema/to-jsonschema.js";
 export interface PluginContext {
     http: HttpClient;
@@ -21,6 +22,11 @@ export interface PluginContext {
     warn?: (message: string) => void;
 }
 export type SchemaOperation = Operation;
+export interface RequestContext extends PluginContext {
+    operation: DropSHOperation;
+    entityType?: string;
+    bundle?: string;
+}
 /**
  * Import-free descriptor naming a plugin package as a string. Same shape used
  * by the top-level `plugins[]` config; a plugin returns these in `dependencies`
@@ -50,6 +56,7 @@ export interface DropSHPlugin {
      */
     extendSchema?(entityType: string, bundle: string, baseSchema: unknown, ctx: PluginContext): Promise<unknown>;
     extendOperationSchema?(entityType: string, bundle: string, operation: SchemaOperation, operationSchema: unknown, ctx: PluginContext): Promise<unknown>;
+    alterRequest?(req: HttpRequest, ctx: RequestContext): Promise<HttpRequest>;
     registerCommands?(program: Command): void;
     renderers?: AnyRenderer[];
 }

package/dist/src/core/request-hooks.d.ts

@@ -0,0 +1,4 @@
+import type { HttpRequest } from "./http.js";
+import type { DropSHOperation } from "./jsonapi/client.js";
+import type { DropSHPlugin, PluginContext } from "./plugin.js";
+export declare function composeRequestHooks(plugins: DropSHPlugin[], ctx: PluginContext): (req: HttpRequest, operation: DropSHOperation, entityType?: string, bundle?: string) => Promise<HttpRequest>;

package/dist/src/core/request-hooks.js

@@ -0,0 +1,26 @@
+import { PluginError } from "../errors.js";
+export function composeRequestHooks(plugins, ctx) {
+    return async (req, operation, entityType, bundle) => {
+        const requestContext = {
+            ...ctx,
+            operation,
+            ...(entityType !== undefined ? { entityType } : {}),
+            ...(bundle !== undefined ? { bundle } : {}),
+        };
+        let current = req;
+        for (const plugin of plugins) {
+            if (!plugin.alterRequest)
+                continue;
+            try {
+                const next = await plugin.alterRequest(current, requestContext);
+                if (next === undefined)
+                    throw new Error("alterRequest must return an HttpRequest");
+                current = next;
+            }
+            catch (cause) {
+                throw new PluginError(plugin.id, "alterRequest", cause);
+            }
+        }
+        return current;
+    };
+}

package/dist/src/errors.d.ts

@@ -17,4 +17,7 @@ export declare class HttpError extends CliError {
     readonly body: unknown;
     constructor(status: number, message: string, body?: unknown);
 }
+export declare class PluginError extends CliError {
+    constructor(pluginId: string, hook: string, cause: unknown);
+}
 export declare function exitCodeFor(err: unknown): number;

package/dist/src/errors.js

@@ -36,6 +36,16 @@ export class HttpError extends CliError {
         this.body = body;
     }
 }
+export class PluginError extends CliError {
+    constructor(pluginId, hook, cause) {
+        super("E_PLUGIN", `plugin '${pluginId}' failed in ${hook}`, {
+            pluginId,
+            hook,
+            cause: String(cause),
+        });
+        this.name = "PluginError";
+    }
+}
 export function exitCodeFor(err) {
     if (err instanceof ConfigError)
         return 2;
@@ -45,5 +55,7 @@ export function exitCodeFor(err) {
         return 4;
     if (err instanceof HttpError)
         return 5;
+    if (err instanceof PluginError)
+        return 6;
     return 1;
 }