dropsh 0.4.1 → 0.5.2

package/README.md

@@ -28,8 +28,27 @@ content without hard-coding every content model.
 
 ## Install
 
+Install dropsh globally to put the `dropsh` binary on `PATH`. No local project,
+`package.json`, or `node_modules` is required — dropsh runs from anywhere:
+
+```bash
+npm i -g dropsh          # or: pnpm add -g dropsh
+dropsh --help            # binary now on PATH, no project needed
+```
+
+dropsh needs Node.js 20 or newer.
+
+Plugins are **separate published packages** and are **not** bundled in the
+`dropsh` tarball. To use one, install it next to dropsh — either globally
+(`npm i -g dropsh @dropsh/plugin-oauth2`) or for a single command via
+`npx -p dropsh -p @dropsh/plugin-oauth2 dropsh …`. See [Plugins](#plugins) for
+how names resolve.
+
+<details>
+<summary>From source (contributors)</summary>
+
 This repository is a pnpm workspace containing the root CLI, packages, and
-plugins.
+plugins. Build it from source when developing dropsh itself:
 
 ```bash
 corepack enable
@@ -38,6 +57,11 @@ pnpm run build
 ```
 
 The required Node.js and pinned pnpm versions are declared in `package.json`.
+Inside the workspace, plugins resolve from the local `node_modules`, so config
+may import the plugin factories directly (see the workspace variant under
+[Configuration](#configuration)).
+
+</details>
 
 ## Drupal Prerequisites
 
@@ -55,14 +79,18 @@ Optional modules unlock stricter schemas or builder-specific support:
 | Feature | Drupal modules |
 | --- | --- |
 | OAuth2 login | `simple_oauth` |
-| Authoritative schemas | `schemata`, `schemata_json_schema` |
+| Authoritative schemas (Drupal 10.1+/11) | `jsonapi_schema` |
+| Authoritative schemas (legacy; 500s on D11/PHP 8.4) | `schemata`, `schemata_json_schema` |
 | Canvas schemas | `canvas`, `jsonapi_sdc` |
 | Display Builder schemas | `display_builder`, `display_builder_entity_view`, `jsonapi_sdc` |
 
-dropsh works without the Schemata modules. In that case, `dropsh schema` falls
-back to a shallow schema inferred from JSON:API sample records. Installing
-`schemata` and `schemata_json_schema` lets `@dropsh/plugin-schemata` return a
-more precise schema with Drupal's required fields and constraints.
+dropsh works without an authoritative-schema module. In that case, `dropsh
+schema` falls back to a shallow schema inferred from JSON:API sample records.
+Installing `jsonapi_schema` lets `@dropsh/plugin-jsonapi-schema` return a more
+precise schema with Drupal's required fields, formats, and constraints — so
+`create`/`update` reject malformed payloads client-side. On **Drupal 11 / PHP
+8.4** prefer `jsonapi_schema`: the older `schemata_json_schema` endpoint returns
+HTTP 500 there.
 
 ### Installing the Drupal modules
 
@@ -77,16 +105,21 @@ drush en jsonapi
 composer require drupal/simple_oauth
 drush en simple_oauth
 
-# Optional: authoritative schemas (schemata_json_schema is a submodule
-# of the schemata project)
-composer require drupal/schemata
-drush en schemata schemata_json_schema
-drush role:perm:add "content_editor" "access schemata data models"
+# Optional: authoritative schemas (Drupal 10.1+/11, PHP 8.4) — recommended
+composer require drupal/jsonapi_schema
+drush en jsonapi_schema
+
+# Legacy alternative — the schemata endpoint returns HTTP 500 on
+# Drupal 11 / PHP 8.4; prefer jsonapi_schema there.
+# composer require drupal/schemata
+# drush en schemata schemata_json_schema
+# drush role:perm:add "content_editor" "access schemata data models"
 ```
 
-Grant `access schemata data models` to the role used by dropsh. For OAuth2, that
-means the user role or client credential access context that reads the Schemata
-endpoint.
+`jsonapi_schema` serves its routes under the JSON:API prefix (`/jsonapi/*`), so
+the role/consumer used by dropsh needs no extra permission beyond JSON:API
+access. (The legacy `schemata` endpoint instead needs `access schemata data
+models` on that role.)
 
 By default JSON:API only accepts read operations. To create, update, or delete
 entities through dropsh, set **Accept all JSON:API create, read, update, and
@@ -95,16 +128,17 @@ delete operations** at `/admin/config/services/jsonapi` (or via
 
 ## Configuration
 
-Create a `dropsh.config.js` in the project where you run dropsh. The config holds
-only non-secret connection settings. Passwords, client secrets, and tokens are
-prompted during login and stored outside the project in the per-host session
+Create a `dropsh.config.js` in the directory where you run dropsh. The config
+holds only non-secret connection settings. Passwords, client secrets, and tokens
+are prompted during login and stored outside the project in the per-host session
 store.
 
-```js
-import { basicAuthPlugin } from "dropsh";
-import { oauth2Plugin } from "@dropsh/plugin-oauth2";
-import { schemataPlugin } from "@dropsh/plugin-schemata";
+Register plugins as **descriptor objects** — `{ plugin, with?, export? }` — that
+name a package by string. dropsh resolves and constructs each plugin itself, so
+the config needs **no `import` statements** and **no local `node_modules`**. This
+is the path a global install uses:
 
+```js
 export default {
   site: {
     base_url: "https://my-drupal.example.com",
@@ -114,6 +148,45 @@ export default {
     dry_run: false,
     timeout_ms: 30000,
   },
+  plugins: [
+    { plugin: "dropsh/plugin", export: "basicAuthPlugin" },
+    {
+      plugin: "@dropsh/plugin-oauth2",
+      export: "oauth2Plugin",
+      with: {
+        type: "oauth2_authcode",
+        client_id: "my-client",
+        token_url: "https://my-drupal.example.com/oauth/token",
+      },
+    },
+    { plugin: "@dropsh/plugin-jsonapi-schema", export: "jsonapiSchemaPlugin" },
+  ],
+};
+```
+
+Each descriptor's `with` is passed to the plugin factory (legacy alias:
+`options`). `export` names the factory to call and is **required** for every
+`@dropsh/plugin-*` package — they export named factories with no default export
+(see [Plugins](#plugins)). Basic auth lives on the `dropsh/plugin` entry, so its
+descriptor names `dropsh/plugin` with `export: "basicAuthPlugin"`.
+
+Use `dropsh.config.example.js` as a fuller starting point. Override the config
+path with `--config <path>` or `DROPSH_CONFIG`.
+
+<details>
+<summary>Workspace variant — importing factories directly</summary>
+
+Inside the pnpm workspace or any project that has the plugin packages in its
+local `node_modules`, you may skip descriptors and import the factories instead.
+The `plugins[]` array then holds constructed plugins:
+
+```js
+import { basicAuthPlugin } from "dropsh/plugin";
+import { oauth2Plugin } from "@dropsh/plugin-oauth2";
+import { jsonapiSchemaPlugin } from "@dropsh/plugin-jsonapi-schema";
+
+export default {
+  site: { base_url: "https://my-drupal.example.com", jsonapi_prefix: "/jsonapi" },
   plugins: [
     basicAuthPlugin(),
     oauth2Plugin({
@@ -121,13 +194,15 @@ export default {
       client_id: "my-client",
       token_url: "https://my-drupal.example.com/oauth/token",
     }),
-    schemataPlugin(),
+    jsonapiSchemaPlugin(),
   ],
 };
 ```
 
-Use `dropsh.config.example.js` as a fuller starting point. Override the config
-path with `--config <path>` or `DROPSH_CONFIG`.
+The two forms may be mixed in one `plugins[]` array. `import` resolves relative
+to the config file, so it only works when the packages are installed there.
+
+</details>
 
 ## Authentication
 
@@ -218,12 +293,12 @@ All commands write JSON to stdout, structured errors to stderr, and use stable
 exit codes.
 
 ```bash
-dropsh read <entity_type>/<bundle>/<uuid>
-dropsh search <entity_type> [--bundle=<bundle>] [--filter=key:value] [--limit=N]
-dropsh create <entity_type> --bundle=<bundle> --data=<json|@file> [--dry-run]
-dropsh update <entity_type>/<bundle>/<uuid> --data=<json|@file> [--dry-run]
+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 delete <entity_type>/<bundle>/<uuid> [--dry-run]
-dropsh upload-file --target=<entity_type>/<bundle>/<uuid>/<field> --file=<path>
+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]
 ```
@@ -231,6 +306,49 @@ dropsh schema <entity_type>/<bundle> [--for=create|update] [--refresh]
 `create` and `update` validate payloads against the current schema by default.
 Pass `--no-validate` when you intentionally want to skip local validation.
 
+### `--include` on `read` / `search`
+
+Pass `--include` to embed related resources in the response's JSON:API
+`included` array (the standard `?include=` query parameter). Accepts a
+comma-separated list or repeated/space-separated values, and nested paths with
+dots:
+
+```bash
+dropsh read node/article/<uuid> --include field_related,field_image
+dropsh search node --bundle=article --include field_related --filter status:1
+dropsh read node/article/<uuid> --include field_related.uid
+```
+
+`read` and `search` are the only commands that accept `--include`. Without it,
+the response contains only the primary resource(s).
+
+### Output formats
+
+By default every command emits JSON. Load a renderer plugin and pass a global
+`--format <id>` (before the subcommand) to render entities differently:
+
+```bash
+dropsh --format md read node/article/<uuid>      # Markdown detail view
+dropsh --format table search node --bundle=article  # aligned table
+```
+
+`--format` applies only to entity commands (`read`, `search`, `create`,
+`update`). Using it on `delete`, `upload-file`, or `schema` exits with code 2.
+
+The `@dropsh/plugin-tui` plugin adds an interactive full-screen format,
+selected the same way via `--format tui` (requires a TTY — an interactive
+terminal):
+
+```bash
+dropsh --format tui read node/article/<uuid>          # opens straight into the detail pane
+dropsh --format tui search node --bundle=article      # list → Enter → detail pane
+```
+
+`read --format tui` boots directly into the detail pane for the single
+entity. `search --format tui` shows a navigable list (↑/↓, Enter opens the
+detail pane, Esc/q goes back or quits). `--include` flows through to the
+detail pane in both cases.
+
 ## Plugins
 
 Plugins are regular JavaScript or TypeScript modules that return a `dropshPlugin`.
@@ -248,14 +366,47 @@ structures, allowed values, and other metadata that helps the agent produce a
 valid payload. Auth plugins keep the same command interface while supporting
 common Drupal authentication systems such as basic auth or OAuth2.
 
-Bundled plugins:
+Plugins developed in this repository (**"bundled"** = part of this repo, **not**
+shipped inside the `dropsh` npm tarball — each is a separately published package):
 
-| Package | Purpose |
-| --- | --- |
-| [`@dropsh/plugin-oauth2`](plugins/oauth2/README.md) | OAuth2 auth provider for Drupal `simple_oauth` |
-| [`@dropsh/plugin-schemata`](plugins/schemata/README.md) | authoritative JSON Schema source from Drupal `schemata` |
-| [`@dropsh/plugin-canvas`](plugins/canvas/README.md) | Canvas component schemas from `jsonapi_sdc` |
-| [`@dropsh/plugin-display-builder`](plugins/display-builder/README.md) | Display Builder operation schemas and metadata |
+| Package | Factory export | Purpose |
+| --- | --- | --- |
+| [`@dropsh/plugin-oauth2`](plugins/oauth2/README.md) | `oauth2Plugin` | OAuth2 auth provider for Drupal `simple_oauth` |
+| [`@dropsh/plugin-jsonapi-schema`](plugins/jsonapi-schema/README.md) | `jsonapiSchemaPlugin` | authoritative JSON Schema from Drupal `jsonapi_schema` |
+| [`@dropsh/plugin-schemata`](plugins/schemata/README.md) | `schemataPlugin` | authoritative JSON Schema from Drupal `schemata` (legacy) |
+| [`@dropsh/plugin-canvas`](plugins/canvas/README.md) | `canvasPlugin` | Canvas component schemas from `jsonapi_sdc` |
+| [`@dropsh/plugin-display-builder`](plugins/display-builder/README.md) | `displayBuilderPlugin` | Display Builder operation schemas and metadata |
+
+Basic auth is not a separate package — its `basicAuthPlugin` factory ships in the
+core CLI's `dropsh/plugin` entry.
+
+### Installing and resolving plugins
+
+`@dropsh/plugin-*` packages are **not** dependencies of `dropsh` and are **not**
+part of its tarball, so a global dropsh does not carry them. Install the ones you
+use next to dropsh:
+
+```bash
+npm i -g dropsh @dropsh/plugin-oauth2        # globally, alongside a global dropsh
+npx -p dropsh -p @dropsh/plugin-oauth2 dropsh …   # or one-off, no global install
+```
+
+A descriptor's `plugin` name is resolved like ESLint resolves its plugins, by
+string name against these locations **in order**:
+
+1. the directory of the `dropsh.config.js` file
+2. the current working directory
+3. dropsh's own install location
+
+Location 3 is what lets a plugin installed globally next to a global `dropsh` be
+found with no local project. If the name cannot be resolved from any of them,
+dropsh reports which package to install.
+
+`export` selects the factory to call and defaults to `"default"`. Every
+`@dropsh/plugin-*` factory is a **named** export with **no default**, so a
+descriptor for one of these packages **must** set `export` (e.g.
+`export: "oauth2Plugin"` — see the table above). Basic auth uses
+`{ plugin: "dropsh/plugin", export: "basicAuthPlugin" }`.
 
 Plugin APIs are exported from `dropsh/plugin`:
 
@@ -273,15 +424,18 @@ export function examplePlugin(): dropshPlugin {
 }
 ```
 
-Register local or package plugins in `dropsh.config.js`:
+Register a package plugin with a descriptor (no import needed), and a local
+plugin either by descriptor (path name) or by importing it:
 
 ```js
-import { basicAuthPlugin } from "dropsh";
 import { examplePlugin } from "./plugins/example.js";
 
 export default {
   site: { base_url: "https://my-drupal.example.com", jsonapi_prefix: "/jsonapi" },
-  plugins: [basicAuthPlugin(), examplePlugin()],
+  plugins: [
+    { plugin: "dropsh/plugin", export: "basicAuthPlugin" }, // packaged, resolved by name
+    examplePlugin(), // local module, imported directly
+  ],
 };
 ```
 

package/dist/src/commands/create.js

@@ -6,9 +6,9 @@ export async function runCreate(args, deps) {
         await deps.validate(payload, target);
     }
     if (args.dryRun) {
-        deps.emit({ dry_run: true, method: "POST", path: target, payload });
+        await deps.emit({ dry_run: true, method: "POST", path: target, payload });
         return;
     }
     const res = await deps.client.post(target, payload);
-    deps.emit(res);
+    await deps.emit(res);
 }

package/dist/src/commands/read.js

@@ -1,3 +1,4 @@
+import { DrupalJsonApiParams } from "drupal-jsonapi-params";
 import { ValidationError } from "../errors.js";
 // Allow short test UUIDs (e.g. "u1") and full Drupal UUIDs (36 chars)
 const TARGET_RE = /^[a-z0-9_]+\/[a-z0-9_]+\/[a-z0-9_-]+$/;
@@ -5,6 +6,14 @@ export async function runRead(args, deps) {
     if (!TARGET_RE.test(args.target)) {
         throw new ValidationError(`target must be <entity_type>/<bundle>/<uuid>, got "${args.target}"`);
     }
-    const res = await deps.client.get(args.target);
-    deps.emit(res);
+    let res;
+    if (args.include?.length) {
+        const params = new DrupalJsonApiParams();
+        params.addInclude(args.include);
+        res = await deps.client.get(args.target, params);
+    }
+    else {
+        res = await deps.client.get(args.target);
+    }
+    await deps.emit(res);
 }

package/dist/src/commands/search.js

@@ -24,7 +24,9 @@ export async function runSearch(args, deps) {
             params.addFilter(f.key, f.value);
     }
     params.addPageLimit(args.limit);
+    if (args.include?.length)
+        params.addInclude(args.include);
     const path = args.bundle ? `${args.entityType}/${args.bundle}` : args.entityType;
     const res = await deps.client.get(path, params);
-    deps.emit(res);
+    await deps.emit(res);
 }

package/dist/src/commands/update.js

@@ -12,9 +12,9 @@ export async function runUpdate(args, deps) {
         await deps.validate(payload, schemaTarget);
     }
     if (args.dryRun) {
-        deps.emit({ dry_run: true, method: "PATCH", path: args.target, payload });
+        await deps.emit({ dry_run: true, method: "PATCH", path: args.target, payload });
         return;
     }
     const res = await deps.client.patch(args.target, payload);
-    deps.emit(res);
+    await deps.emit(res);
 }

package/dist/src/core/cli/output.js

@@ -1,8 +1,34 @@
-import { CliError } from "../../errors.js";
+import { CliError, ConfigError } from "../../errors.js";
+import { isInteractive, } from "./render.js";
+function isJsonApiDocument(v) {
+    return !!v && typeof v === "object" && "data" in v;
+}
 export function createOutput(opts) {
+    const registry = new Map();
+    for (const r of opts.renderers ?? []) {
+        if (registry.has(r.id))
+            throw new ConfigError(`Duplicate renderer id: ${r.id}`);
+        registry.set(r.id, r);
+    }
+    const getFormat = opts.getFormat ?? (() => "json");
     return {
-        emit(value) {
-            opts.stdout(`${JSON.stringify(value)}\n`);
+        emit(value, ctx, services) {
+            const fmt = getFormat();
+            if (fmt === "json" || !isJsonApiDocument(value)) {
+                opts.stdout(`${JSON.stringify(value)}\n`);
+                return;
+            }
+            const renderer = registry.get(fmt);
+            if (!renderer) {
+                throw new ConfigError(`Unknown format: ${fmt}`, {
+                    available: ["json", ...registry.keys()],
+                });
+            }
+            if (isInteractive(renderer)) {
+                return renderer.run(value, ctx ?? { command: "read" }, services);
+            }
+            const text = renderer.render(value, ctx ?? { command: "read" });
+            opts.stdout(text.endsWith("\n") ? text : `${text}\n`);
         },
         fail(err) {
             const payload = err instanceof CliError
@@ -16,5 +42,8 @@ export function createOutput(opts) {
                 };
             opts.stderr(`${JSON.stringify(payload)}\n`);
         },
+        hasFormat(id) {
+            return id === "json" || registry.has(id);
+        },
     };
 }

package/dist/src/core/cli/render.js

@@ -0,0 +1,13 @@
+// Indexes a document's `included` resources by `${type}/${id}` so renderers can
+// resolve a relationship reference to its embedded resource (populated by
+// `--include`). Empty map when the document carries no `included`.
+export function indexIncluded(doc) {
+    const map = new Map();
+    for (const r of doc.included ?? []) {
+        map.set(`${r.type}/${r.id}`, r);
+    }
+    return map;
+}
+export function isInteractive(r) {
+    return "interactive" in r && r.interactive === true;
+}

package/dist/src/core/context.js

@@ -0,0 +1,44 @@
+import { AuthError, ConfigError } from "../errors.js";
+import { collectProviders, providerById } from "./auth/registry.js";
+import { readSession, writeSession } from "./auth/session-store.js";
+import { loadConfig } from "./config.js";
+import { createHttpClient } from "./http.js";
+import { createJsonApiClient } from "./jsonapi/client.js";
+export async function resolveAuth(deps) {
+    const rec = await readSession(deps.baseUrl, deps.stateDir);
+    if (!rec)
+        throw new AuthError("Not authenticated. Run 'dropsh auth login'.");
+    const provider = providerById(collectProviders(deps.plugins), rec.activeProvider);
+    if (!provider)
+        throw new ConfigError(`active provider '${rec.activeProvider}' is not configured`);
+    return provider.createAdapter(rec.session, {
+        http: deps.http,
+        now: deps.now,
+        save: (session) => writeSession(deps.baseUrl, provider.id, session, deps.stateDir),
+    });
+}
+export async function createCommandContext(configPath) {
+    const cfg = await loadConfig(configPath);
+    const http = createHttpClient({ timeoutMs: cfg.defaults.timeout_ms });
+    const auth = await resolveAuth({
+        baseUrl: cfg.site.base_url,
+        plugins: cfg.plugins,
+        http,
+        now: Date.now,
+    });
+    const client = createJsonApiClient({
+        baseUrl: cfg.site.base_url,
+        prefix: cfg.site.jsonapi_prefix,
+        http,
+        auth,
+    });
+    return {
+        client,
+        http,
+        auth,
+        baseUrl: cfg.site.base_url,
+        jsonapiPrefix: cfg.site.jsonapi_prefix,
+        cwd: process.cwd(),
+        plugins: cfg.plugins,
+    };
+}

package/dist/src/core/schema/jsonschema-source.js

@@ -4,7 +4,13 @@ export async function fetchJsonSchema(deps) {
     const { entity, bundle } = deps;
     const target = { entity_type: entity, bundle };
     const plugins = deps.plugins ?? [];
-    const ctx = { http: deps.http, auth: deps.auth, baseUrl: deps.baseUrl };
+    const ctx = {
+        http: deps.http,
+        auth: deps.auth,
+        baseUrl: deps.baseUrl,
+        jsonapiPrefix: deps.jsonapiPrefix,
+        warn: deps.warn,
+    };
     // Build heuristic base schema
     let heuristicResult;
     try {

package/dist/src/core/schema/validate.js

@@ -1,9 +1,16 @@
 import Ajv from "ajv";
 import draft6MetaSchema from "ajv/dist/refs/json-schema-draft-06.json" with { type: "json" };
 import draft7MetaSchema from "ajv/dist/refs/json-schema-draft-07.json" with { type: "json" };
+import addFormats from "ajv-formats";
 import { ValidationError } from "../../errors.js";
 export function validatePayload(schema, payload, target) {
     const ajv = new Ajv({ allErrors: true, strict: false, validateSchema: false, logger: false });
+    // Enforce standard `format` keywords (uri, date-time, uuid, email, …) so a
+    // constraint-bearing schema (e.g. from the jsonapi-schema plugin) rejects a
+    // malformed value — such as an SCP-style git remote where a URI is required —
+    // client-side, before the request is sent. Schemas without `format` are
+    // unaffected.
+    addFormats(ajv);
     // Schemata (Drupal module) may emit Draft-04 schemas that use `id` instead of `$id`.
     // AJV v8 hard-throws on `id`; removing the keyword makes AJV silently ignore it.
     ajv.removeKeyword("id");

package/dist/src/index.js

@@ -24,6 +24,17 @@ import { AuthError, ConfigError, exitCodeFor } from "./errors.js";
 function resolveConfigPath(override) {
     return override ?? process.env.DROPSH_CONFIG ?? "dropsh.config.js";
 }
+// Normalizes a variadic --include option into a flat, trimmed list of field
+// names: splits any comma-containing entries (so both `--include a,b` and
+// `--include a b` work) and drops empty strings.
+export function normalizeInclude(raw) {
+    if (!raw)
+        return [];
+    return raw
+        .flatMap((entry) => entry.split(","))
+        .map((s) => s.trim())
+        .filter((s) => s.length > 0);
+}
 /**
  * Choose the profile name to authenticate as. Precedence:
  *   explicit → stored `active` → config `default:true` → the sole provider.
@@ -131,7 +142,9 @@ export function buildProgram(opts = {}) {
         .description("Entity-agnostic CLI for Drupal 11 JSON:API")
         .version("0.0.0")
         .option("--config <path>", "path to config file (overrides DROPSH_CONFIG)")
-        .option("--auth-profile <id>", "auth profile to use (overrides the active profile and $DROPSH_AUTH_PROFILE)");
+        .option("--auth-profile <id>", "auth profile to use (overrides the active profile and $DROPSH_AUTH_PROFILE)")
+        .option("--format <id>", "output format: json (default) or a renderer id", "json")
+        .option("--view-mode <name>", "entity view mode for interactive formats", "default");
     const stdout = opts.stdout ?? ((s) => process.stdout.write(s));
     const stderr = opts.stderr ?? ((s) => process.stderr.write(s));
     const setExitCode = opts.setExitCode ??
@@ -144,9 +157,16 @@ export function buildProgram(opts = {}) {
             const profile = o.authProfile ?? process.env.DROPSH_AUTH_PROFILE;
             return defaultContext(resolveConfigPath(o.config), profile);
         });
-    const output = createOutput({ stdout, stderr });
-    async function run(fn) {
+    const renderers = (opts.plugins ?? []).flatMap((p) => p.renderers ?? []);
+    const output = createOutput({
+        stdout,
+        stderr,
+        renderers,
+        getFormat: () => program.opts().format ?? "json",
+    });
+    async function run(fn, precheck) {
         try {
+            precheck?.();
             const ctx = await contextFactory();
             await fn(ctx);
         }
@@ -164,6 +184,21 @@ export function buildProgram(opts = {}) {
             setExitCode(exitCodeFor(err));
         }
     }
+    function currentFormat() {
+        return program.opts().format ?? "json";
+    }
+    function assertRenderable() {
+        const f = currentFormat();
+        if (!output.hasFormat(f)) {
+            throw new ConfigError(`Unknown format '${f}'. Available: ${["json", ...renderers.map((r) => r.id)].join(", ")}`);
+        }
+    }
+    function assertJsonOnly(command) {
+        const f = currentFormat();
+        if (f !== "json") {
+            throw new ConfigError(`format '${f}' not applicable to command '${command}'`);
+        }
+    }
     async function authDeps() {
         const cfg = await loadConfig(resolveConfigPath(program.opts().config));
         return {
@@ -224,19 +259,48 @@ export function buildProgram(opts = {}) {
     program
         .command("read <target>")
         .description("Read entity_type/bundle/uuid")
-        .action((target) => run((ctx) => runRead({ target }, { client: ctx.client, emit: output.emit })));
+        .option("--include <fields...>", "related fields to include (JSON:API include)")
+        .action((target, o) => {
+        const [entityType, bundle] = target.split("/");
+        const rctx = { command: "read", target };
+        if (entityType !== undefined)
+            rctx.entityType = entityType;
+        if (bundle !== undefined)
+            rctx.bundle = bundle;
+        rctx.viewMode = program.opts().viewMode;
+        // biome-ignore lint/suspicious/noExplicitAny: optional include added conditionally
+        const args = { target };
+        const include = normalizeInclude(o.include);
+        if (include.length > 0)
+            args.include = include;
+        return run((ctx) => runRead(args, {
+            client: ctx.client,
+            emit: (v) => output.emit(v, rctx, { client: ctx.client, baseUrl: ctx.baseUrl }),
+        }), assertRenderable);
+    });
     program
         .command("search <entity_type>")
         .description("Search entities with filters")
         .option("--bundle <bundle>")
         .option("--filter <kv...>", "filter in key:value or key:op:value form", [])
         .option("--limit <n>", "max results", (v) => parseInt(v, 10), 50)
+        .option("--include <fields...>", "related fields to include (JSON:API include)")
         .action((entityType, o) => {
-        // biome-ignore lint/suspicious/noExplicitAny: optional bundle added conditionally
+        // biome-ignore lint/suspicious/noExplicitAny: optional bundle/include added conditionally
         const args = { entityType, filters: o.filter, limit: o.limit };
         if (o.bundle !== undefined)
             args.bundle = o.bundle;
-        run((ctx) => runSearch(args, { client: ctx.client, emit: output.emit }));
+        const include = normalizeInclude(o.include);
+        if (include.length > 0)
+            args.include = include;
+        const rctx = { command: "search", entityType };
+        if (o.bundle !== undefined)
+            rctx.bundle = o.bundle;
+        rctx.viewMode = program.opts().viewMode;
+        return run((ctx) => runSearch(args, {
+            client: ctx.client,
+            emit: (v) => output.emit(v, rctx, { client: ctx.client, baseUrl: ctx.baseUrl }),
+        }), assertRenderable);
     });
     program
         .command("create <entity_type>")
@@ -251,8 +315,9 @@ export function buildProgram(opts = {}) {
             args.dryRun = o.dryRun;
         if (o.validate === false)
             args.noValidate = true;
-        run(async (ctx) => {
-            const deps = { client: ctx.client, emit: output.emit };
+        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");
@@ -260,7 +325,7 @@ export function buildProgram(opts = {}) {
                 };
             }
             await runCreate(args, deps);
-        });
+        }, assertRenderable);
     });
     program
         .command("update <target>")
@@ -274,8 +339,14 @@ export function buildProgram(opts = {}) {
             args.dryRun = o.dryRun;
         if (o.validate === false)
             args.noValidate = true;
-        run(async (ctx) => {
-            const deps = { client: ctx.client, emit: output.emit };
+        return run(async (ctx) => {
+            const [entityType, bundle] = 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");
@@ -283,7 +354,7 @@ export function buildProgram(opts = {}) {
                 };
             }
             await runUpdate(args, deps);
-        });
+        }, assertRenderable);
     });
     program
         .command("delete <target>")
@@ -294,7 +365,7 @@ export function buildProgram(opts = {}) {
         const args = { target };
         if (o.dryRun !== undefined)
             args.dryRun = o.dryRun;
-        run((ctx) => runDelete(args, { client: ctx.client, emit: output.emit }));
+        return run((ctx) => runDelete(args, { client: ctx.client, emit: output.emit }), () => assertJsonOnly("delete"));
     });
     program
         .command("upload-file")
@@ -307,7 +378,7 @@ export function buildProgram(opts = {}) {
         const args = { target: o.target, file: o.file };
         if (o.dryRun !== undefined)
             args.dryRun = o.dryRun;
-        run((ctx) => runUploadFile(args, { client: ctx.client, emit: output.emit }));
+        return run((ctx) => runUploadFile(args, { client: ctx.client, emit: output.emit }), () => assertJsonOnly("upload-file"));
     });
     program
         .command("schema [target]")
@@ -319,7 +390,7 @@ export function buildProgram(opts = {}) {
         const schemaArgs = target !== undefined
             ? { target, operation, refresh: Boolean(o.refresh) }
             : { operation, refresh: Boolean(o.refresh) };
-        run((ctx) => runSchema(schemaArgs, {
+        return run((ctx) => runSchema(schemaArgs, {
             http: ctx.http,
             auth: ctx.auth,
             baseUrl: ctx.baseUrl,
@@ -328,7 +399,7 @@ export function buildProgram(opts = {}) {
             emit: 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.js

@@ -1,4 +1,5 @@
 export { basicAuthPlugin, basicAuthProvider } from "./core/auth/basic.js";
+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";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dropsh",
-  "version": "0.4.1",
+  "version": "0.5.2",
   "description": "Entity-agnostic helper CLI for Drupal 11 JSON:API, used by the dropsh Claude skill for editorial publishing workflows.",
   "type": "module",
   "bin": {
@@ -34,6 +34,7 @@
   },
   "dependencies": {
     "ajv": "^8.18.0",
+    "ajv-formats": "^3.0.1",
     "commander": "^12.1.0",
     "drupal-jsonapi-params": "^3.0.1",
     "open": "^11.0.0"
@@ -62,6 +63,7 @@
     "lint:fix": "biome check --write src/ packages/ plugins/ tests/integrations/helpers/ 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",
     "release": "node scripts/release.mjs"
   }
 }