dropsh 0.5.8 → 0.6.1

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,10 +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";
 }
@@ -119,11 +124,18 @@ async function defaultContext(configPath, profile) {
         now: Date.now,
         ...(profile !== undefined ? { profile } : {}),
     });
+    const pluginContext = {
+        http,
+        auth,
+        baseUrl: cfg.site.base_url,
+        jsonapiPrefix: cfg.site.jsonapi_prefix,
+    };
     const client = createJsonApiClient({
         baseUrl: cfg.site.base_url,
         prefix: cfg.site.jsonapi_prefix,
         http,
         auth,
+        alterRequest: composeRequestHooks(cfg.plugins, pluginContext),
     });
     return {
         client,
@@ -193,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") {
@@ -339,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
@@ -418,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

@@ -7,12 +7,17 @@ export type { Config, SiteConfig } from "./core/config.js";
 export { loadConfig } from "./core/config.js";
 export type { HttpClient, HttpRequest } from "./core/http.js";
 export { createHttpClient } from "./core/http.js";
-export type { JsonApiClient, JsonApiOptions, ResourceWriteBody, } from "./core/jsonapi/client.js";
+export type { DropSHOperation, JsonApiClient, JsonApiOptions, ResourceWriteBody, } from "./core/jsonapi/client.js";
 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 { DropSHPlugin, PluginContext, PluginDescriptor, SchemaOperation, } from "./core/plugin.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 } from "./errors.js";
+export { AuthError, ConfigError, HttpError, PluginError } from "./errors.js";
 export type { CommandContext } from "./index.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 } from "./errors.js";
+export { AuthError, ConfigError, HttpError, PluginError } from "./errors.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dropsh",
-  "version": "0.5.8",
+  "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",