dropsh 0.0.1 → 0.1.0

package/README.md

@@ -1,78 +1,258 @@
 # dropsh
 
-Entity-agnostic helper CLI for Drupal 11 JSON:API. Written in TypeScript, used directly by the `dropsh` Claude skill for editorial publishing workflows.
+dropsh is a CLI for Drupal JSON:API with JSON Schema output and request
+validation. It is meant to give agents enough structure to build reliable Drupal
+payloads instead of guessing field names, required properties, component shapes,
+or authentication details.
 
-This is the foundation CLI. Discovery, schema generation, and the skill layer are delivered by follow-up plans.
+The CLI can read and search existing content, print schemas for create and update
+payloads, validate data locally, and then send the JSON:API request. Plugins can
+extend those schemas with site-specific fields, component metadata, builder
+constraints, and other context the agent needs to do the job. Authentication for
+common Drupal setups is handled through plugins as well.
+
+## Concept
+
+dropsh is built for workflows where an agent or script needs to work with Drupal
+content without hard-coding every content model.
+
+- `dropsh schema` returns JSON Schema for targets like `node/article`.
+- `create` and `update` validate payloads before sending them to Drupal.
+- Agents can inspect existing records with `search` and `read` before generating
+  new data.
+- Plugins can replace shallow inferred schemas with authoritative Drupal schemas
+  and enrich payload schemas with the extra context an agent needs.
+- Auth plugins support common Drupal authentication systems without changing the
+  commands that use them.
+- A skill can use dropsh as its Drupal execution layer and focus on the workflow.
 
 ## Install
 
+This repository is a pnpm workspace containing the root CLI, packages, and
+plugins.
+
+```bash
+corepack enable
+pnpm install
+pnpm run build
+```
+
+The required Node.js and pinned pnpm versions are declared in `package.json`.
+
+## Drupal Prerequisites
+
+The base CLI expects a Drupal site with JSON:API enabled and reachable from the
+machine running dropsh.
+
+Minimum Drupal setup:
+
+- Drupal 10 or 11
+- JSON:API enabled
+- A user or OAuth client with permissions for the entities you want to access
+
+Optional modules unlock stricter schemas or builder-specific support:
+
+| Feature | Drupal modules |
+| --- | --- |
+| OAuth2 login | `simple_oauth` |
+| Authoritative schemas | `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.
+
+### Installing the Drupal modules
+
+JSON:API ships with Drupal core; enable it together with the optional modules
+you need:
+
 ```bash
-npm install
-npm run build
+# Minimum: JSON:API (Drupal core)
+drush en jsonapi
+
+# Optional: OAuth2 login
+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"
+```
+
+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.
+
+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
+delete operations** at `/admin/config/services/jsonapi` (or via
+`drush config:set jsonapi.settings read_only 0`).
+
+## 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
+store.
+
+```js
+import { basicAuthPlugin } from "dropsh";
+import { oauth2Plugin } from "@dropsh/plugin-oauth2";
+import { schemataPlugin } from "@dropsh/plugin-schemata";
+
+export default {
+  site: {
+    base_url: "https://my-drupal.example.com",
+    jsonapi_prefix: "/jsonapi",
+  },
+  defaults: {
+    dry_run: false,
+    timeout_ms: 30000,
+  },
+  plugins: [
+    basicAuthPlugin(),
+    oauth2Plugin({
+      type: "oauth2_authcode",
+      client_id: "my-client",
+      token_url: "https://my-drupal.example.com/oauth/token",
+    }),
+    schemataPlugin(),
+  ],
+};
 ```
 
-## Configure
+Use `dropsh.config.example.js` as a fuller starting point. Override the config
+path with `--config <path>` or `DROPSH_CONFIG`.
+
+## Authentication
 
-Copy `.dropsh.yml.example` to `.dropsh.yml` in your project and set the auth fields. Secrets are referenced as `${ENV_VAR}` and expanded at load time.
+Authentication is configured through plugins. Each plugin that contributes an
+auth provider appears as a login option.
 
-```yaml
-site:
-  base_url: https://my-drupal.example.com
-  auth:
-    type: basic
-    username: ${DRUPAL_USER}
-    password: ${DRUPAL_PASSWORD}
+```bash
+dropsh auth login
+dropsh auth login --provider basic
+dropsh auth status
+dropsh auth logout
 ```
 
+Secrets and tokens are never written to `dropsh.config.js`. The active session is
+stored per host under `~/.config/dropsh/<host>.json` with file mode `0600`.
+
 ## Commands
 
-All commands write JSON to stdout, structured errors to stderr, and use exit codes 0-5.
+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=<b>] [--filter=key:value]… [--limit=N]
-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 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 delete <entity_type>/<bundle>/<uuid> [--dry-run]
-dropsh upload-file --target=<entity_type>/<bundle>/<uuid>/<field> --file=<path> [--dry-run]
+dropsh upload-file --target=<entity_type>/<bundle>/<uuid>/<field> --file=<path>
 dropsh schema [--refresh]
 dropsh schema <entity_type>/<bundle> [--for=create|update] [--refresh]
 ```
 
-### `schema`
+`create` and `update` validate payloads against the current schema by default.
+Pass `--no-validate` when you intentionally want to skip local validation.
+
+## Plugins
+
+Plugins are regular JavaScript or TypeScript modules that return a `dropshPlugin`.
+A plugin can contribute one or more of these capabilities:
+
+- an auth provider
+- schema extensions
+- operation-specific schema changes for `create` or `update`
+- additional CLI commands
+
+Schema plugins are the main way to make dropsh useful for agents on real sites.
+dropsh can generate a basic schema without them, but plugins can make that schema
+more precise by adding required fields, component definitions, builder-specific
+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.
 
-Without a target, prints the list of available `<entity_type>/<bundle>` targets on the site.
+Bundled plugins:
 
-With a target (e.g. `node/article`), prints a JSON Schema document that validates a JSON:API request body for that resource.
+| 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 |
 
-- `--for=create` (default) / `--for=update` — operation variant (update clears required fields)
-- `--refresh` — bypass the cache for this call
+Plugin APIs are exported from `dropsh/plugin`:
 
-If the site has `drupal/schemata` + `drupal/schemata_json_schema` installed, the schema is authoritative (required fields, constraints). Otherwise, a shallow schema is returned from sample records with a warning on stderr (field names only, no required fields, no constraints). The output carries `x-dropsh-source: "schemata" | "heuristic" | "heuristic-empty"` so consumers can tell how strict the schema is.
+```ts
+import type { dropshPlugin } from "dropsh/plugin";
 
-Schemas are cached under `.dropsh/cache/` next to your `.dropsh.yml`. The `.dropsh/` directory is gitignored.
+export function examplePlugin(): dropshPlugin {
+  return {
+    id: "example",
+    requiredModules: [],
+    async extendSchema(_entityType, _bundle, schema) {
+      return schema;
+    },
+  };
+}
+```
+
+Register local or package plugins in `dropsh.config.js`:
+
+```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()],
+};
+```
+
+## Example Skills
 
-### Client-side validation in `create` / `update`
+A dropsh skill does not need to know every Drupal internal. Keep `SKILL.md` as a
+small orchestrator that decides when the skill applies, which dropsh plugins are
+expected, and which workflow file to load. Put the concrete command sequences,
+schema checks, payload rules, and error handling into separate workflow files.
 
-`dropsh create` and `dropsh update` run the payload through the bundle's schema before sending it. A validation failure exits with code 4 (`E_VALIDATION`) and emits the Ajv errors on stderr without issuing an HTTP request. Pass `--no-validate` to skip the check.
+See [docs/examples/skills](docs/examples/skills/README.md) for three example
+skill structures:
+
+- Article publishing over standard JSON:API nodes
+- Canvas pages driven by component schemas
+- Display Builder pages driven by display metadata and override fields
 
 ## Development
 
 ```bash
-npm test            # Vitest unit suite
-npm run test:watch
-npm run typecheck
-npm run build
+pnpm test
+pnpm run typecheck
+pnpm run build
+```
+
+Integration tests require DDEV:
+
+```bash
+pnpm run drupal:up
+pnpm run test:integration
+pnpm run drupal:down
 ```
 
-### Integration tests
+## Publishing
 
-Local-only, requires DDEV. See `tests/integrations/README.md`.
+The CLI and workspace packages are published together from the `1.x` branch:
 
 ```bash
-npm run drupal:up
-npm run test:integration
-npm run drupal:down
+pnpm run release
 ```
 
-See `docs/superpowers/specs/2026-04-21-dropsh-design.md` for the full design.
+Run `npm login` first. `prepublishOnly` runs typecheck and build before publish.

package/dist/src/commands/auth.js

@@ -0,0 +1,88 @@
+import { loginCapableProviders, providerById } from "../core/auth/registry.js";
+import { clearSession, readSession, writeSession } from "../core/auth/session-store.js";
+import { AuthError, ConfigError } from "../errors.js";
+function authContext(deps) {
+    const ctx = {
+        baseUrl: deps.baseUrl,
+        http: deps.http,
+        prompt: deps.prompt,
+        openBrowser: deps.openBrowser,
+        stdout: deps.stdout,
+        now: deps.now,
+    };
+    if (deps.stateDir !== undefined)
+        ctx.stateDir = deps.stateDir;
+    return ctx;
+}
+async function pickProvider(deps, requestedId) {
+    const capable = loginCapableProviders(deps.providers);
+    if (capable.length === 0)
+        throw new ConfigError("no login-capable auth provider configured");
+    if (requestedId) {
+        const found = providerById(capable, requestedId);
+        if (!found)
+            throw new ConfigError(`unknown provider '${requestedId}'. Available: ${capable.map((p) => p.id).join(", ")}`);
+        return found;
+    }
+    if (!deps.isTTY)
+        throw new ConfigError("non-interactive: pass --provider <id>");
+    deps.stdout("Select an auth provider:\n");
+    capable.forEach((p, i) => {
+        deps.stdout(`  ${i + 1}) ${p.displayName} [${p.id}]\n`);
+    });
+    const answer = await deps.prompt({ label: "Number" });
+    const idx = Number.parseInt(answer, 10) - 1;
+    const chosen = capable[idx];
+    if (!chosen)
+        throw new ConfigError(`invalid selection '${answer}'`);
+    return chosen;
+}
+export async function runAuthLogin(args, deps) {
+    const provider = await pickProvider(deps, args.provider);
+    const session = await provider.login(authContext(deps));
+    await writeSession(deps.baseUrl, provider.id, session, deps.stateDir);
+    deps.stdout(`logged in via ${provider.displayName}\n`);
+}
+export async function runAuthLogout(_args, deps) {
+    const rec = await readSession(deps.baseUrl, deps.stateDir);
+    if (!rec) {
+        deps.stdout("not logged in\n");
+        return;
+    }
+    const provider = providerById(deps.providers, rec.activeProvider);
+    try {
+        if (provider)
+            await provider.logout(authContext(deps));
+    }
+    catch (err) {
+        // Best-effort revoke: never block local logout on a failing revoke call.
+        deps.stderr(`warning: provider logout failed: ${String(err)}\n`);
+    }
+    finally {
+        await clearSession(deps.baseUrl, deps.stateDir);
+    }
+    deps.stdout("logged out\n");
+}
+export async function runAuthStatus(args, deps) {
+    const rec = await readSession(deps.baseUrl, deps.stateDir);
+    if (!rec) {
+        if (args.json)
+            deps.stdout(`${JSON.stringify({ loggedIn: false })}\n`);
+        else
+            deps.stdout("not logged in\n");
+        return;
+    }
+    const provider = providerById(deps.providers, rec.activeProvider);
+    if (!provider)
+        throw new AuthError(`active provider '${rec.activeProvider}' is not configured`);
+    const info = await provider.status(rec.session);
+    const host = new URL(deps.baseUrl).hostname;
+    if (args.json) {
+        deps.stdout(`${JSON.stringify({ ...info, host })}\n`);
+        return;
+    }
+    deps.stdout(`provider: ${provider.displayName} [${provider.id}]\n`);
+    deps.stdout(`host: ${host}\n`);
+    if (info.expiresAt !== undefined)
+        deps.stdout(`token: ${info.state} (until ${new Date(info.expiresAt).toISOString()})\n`);
+}

package/dist/src/commands/schema.js

@@ -4,9 +4,55 @@ import { fetchCatalog } from "../core/schema/catalog.js";
 import { fetchJsonSchema } from "../core/schema/jsonschema-source.js";
 import { toOperationVariant } from "../core/schema/to-jsonschema.js";
 import { ValidationError } from "../errors.js";
+export const SCHEMA_PIPELINE_VERSION = 2;
+/**
+ * Per-site schema cache root. Schemas differ between sites, so the cache is
+ * namespaced by the site host — two configs pointing at different base_urls
+ * from the same working directory must not share cached schemas.
+ */
+export function siteCacheRoot(cwd, baseUrl) {
+    const host = new URL(baseUrl).host.toLowerCase().replace(/[^a-z0-9.-]/g, "_");
+    return join(cwd, ".dropsh/cache", host);
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+export function operationHookPluginIds(plugins) {
+    return plugins.filter((plugin) => plugin.extendOperationSchema).map((plugin) => plugin.id);
+}
+export function schemaCacheMetadataMatches(schema, operationHookPlugins) {
+    if (!isRecord(schema))
+        return false;
+    if (schema["x-dropsh-schema-pipeline-version"] !== SCHEMA_PIPELINE_VERSION)
+        return false;
+    const cachedPlugins = schema["x-dropsh-operation-hook-plugins"];
+    if (!Array.isArray(cachedPlugins))
+        return false;
+    if (cachedPlugins.length !== operationHookPlugins.length)
+        return false;
+    return cachedPlugins.every((plugin, index) => plugin === operationHookPlugins[index]);
+}
+export async function applyOperationSchemaPlugins(schema, args, deps) {
+    let current = schema;
+    const extensions = [];
+    const ctx = { http: deps.http, auth: deps.auth, baseUrl: deps.baseUrl };
+    for (const plugin of deps.plugins) {
+        if (!plugin.extendOperationSchema)
+            continue;
+        const extended = await plugin.extendOperationSchema(args.entity, args.bundle, args.operation, current, ctx);
+        if (extended !== current) {
+            current = extended;
+            extensions.push(plugin.id);
+        }
+    }
+    return { schema: current, extensions };
+}
 const TARGET_RE = /^[a-z0-9_]+\/[a-z0-9_]+$/;
 export async function runSchema(args, deps) {
-    const store = createFileStore({ rootDir: join(deps.cwd, ".dropsh/cache"), warn: deps.warn });
+    const store = createFileStore({
+        rootDir: siteCacheRoot(deps.cwd, deps.baseUrl),
+        warn: deps.warn,
+    });
     if (args.target === undefined) {
         if (!args.refresh) {
             const hit = await store.read("catalog.json");
@@ -32,9 +78,11 @@ export async function runSchema(args, deps) {
     // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
     const [entity, bundle] = args.target.split("/", 2);
     const cacheKey = `schema/${entity}--${bundle}.${args.operation}.json`;
+    const plugins = deps.plugins ?? [];
+    const hookPluginIds = operationHookPluginIds(plugins);
     if (!args.refresh) {
         const hit = await store.read(cacheKey);
-        if (hit !== undefined) {
+        if (hit !== undefined && schemaCacheMetadataMatches(hit, hookPluginIds)) {
             deps.emit(hit);
             return;
         }
@@ -47,14 +95,23 @@ export async function runSchema(args, deps) {
         entity,
         bundle,
         warn: deps.warn,
-        plugins: deps.plugins ?? [],
+        plugins,
     });
     const transformed = toOperationVariant(raw, args.operation);
+    const operationExtended = await applyOperationSchemaPlugins(transformed, { entity, bundle, operation: args.operation }, {
+        http: deps.http,
+        auth: deps.auth,
+        baseUrl: deps.baseUrl,
+        plugins,
+    });
     const tagged = {
-        ...transformed,
+        ...operationExtended.schema,
         "x-dropsh-source": source,
         "x-dropsh-target": { entity_type: entity, bundle },
         "x-dropsh-operation": args.operation,
+        "x-dropsh-schema-extensions": operationExtended.extensions,
+        "x-dropsh-schema-pipeline-version": SCHEMA_PIPELINE_VERSION,
+        "x-dropsh-operation-hook-plugins": hookPluginIds,
     };
     await store.write(cacheKey, tagged);
     deps.emit(tagged);

package/dist/src/core/auth/basic.js

@@ -1,24 +1,43 @@
 import { ConfigError } from "../../errors.js";
-export function createBasicAuth(cfg) {
-    if (typeof cfg.username !== "string" || cfg.username.length === 0)
-        throw new ConfigError("basicAuthPlugin: username required");
-    if (typeof cfg.password !== "string" || cfg.password.length === 0)
-        throw new ConfigError("basicAuthPlugin: password required");
-    const token = Buffer.from(`${cfg.username}:${cfg.password}`).toString("base64");
+function adapterFromB64(b64) {
     return {
         async apply(req) {
-            return { ...req, headers: { ...(req.headers ?? {}), Authorization: `Basic ${token}` } };
+            return { ...req, headers: { ...(req.headers ?? {}), Authorization: `Basic ${b64}` } };
         },
     };
 }
-export function basicAuthPlugin(config) {
-    const adapter = createBasicAuth(config);
+export function basicAuthProvider(config = {}) {
     return {
         id: "basic",
-        requiredModules: [],
-        createAuthAdapter: () => adapter,
-        async extendSchema(_entityType, _bundle, schema, _ctx) {
-            return schema;
+        displayName: "Basic auth (username / password)",
+        capabilities: { login: true, logout: true, status: true },
+        async login(ctx) {
+            const username = config.username ?? (await ctx.prompt({ label: "Username" }));
+            if (!username)
+                throw new ConfigError("basic auth: username required");
+            const password = await ctx.prompt({ label: "Password", secret: true });
+            if (!password)
+                throw new ConfigError("basic auth: password required");
+            return { basic_b64: Buffer.from(`${username}:${password}`).toString("base64") };
+        },
+        async logout() {
+            // No server-side revoke for basic auth; the core clears the session.
+        },
+        async status(session) {
+            return { loggedIn: session !== null, provider: "basic" };
         },
+        createAdapter(session) {
+            const b64 = session.basic_b64;
+            if (typeof b64 !== "string")
+                throw new ConfigError("basic auth: corrupt session");
+            return adapterFromB64(b64);
+        },
+    };
+}
+export function basicAuthPlugin(config = {}) {
+    return {
+        id: "basic",
+        requiredModules: [],
+        authProvider: basicAuthProvider(config),
     };
 }

package/dist/src/core/auth/registry.js

@@ -0,0 +1,9 @@
+export function collectProviders(plugins) {
+    return plugins.map((p) => p.authProvider).filter((p) => p !== undefined);
+}
+export function loginCapableProviders(providers) {
+    return providers.filter((p) => p.capabilities.login);
+}
+export function providerById(providers, id) {
+    return providers.find((p) => p.id === id);
+}

package/dist/src/core/auth/session-store.js

@@ -0,0 +1,38 @@
+import { chmod, mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+export function defaultStateDir() {
+    return join(homedir(), ".config", "dropsh");
+}
+function hostnameFromUrl(baseUrl) {
+    return new URL(baseUrl).hostname;
+}
+function sessionPath(baseUrl, dir) {
+    return join(dir, `${hostnameFromUrl(baseUrl)}.json`);
+}
+export async function readSession(baseUrl, dir) {
+    const path = sessionPath(baseUrl, dir ?? defaultStateDir());
+    try {
+        const raw = await readFile(path, "utf8");
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+export async function writeSession(baseUrl, activeProvider, session, dir) {
+    const stateDir = dir ?? defaultStateDir();
+    await mkdir(stateDir, { recursive: true });
+    const record = { activeProvider, session };
+    const path = sessionPath(baseUrl, stateDir);
+    await writeFile(path, JSON.stringify(record, null, 2), {
+        encoding: "utf8",
+        mode: 0o600,
+    });
+    // writeFile's `mode` only applies when creating a new file; overwriting an
+    // existing file keeps its old (possibly looser) permissions, so tighten explicitly.
+    await chmod(path, 0o600);
+}
+export async function clearSession(baseUrl, dir) {
+    await rm(sessionPath(baseUrl, dir ?? defaultStateDir()), { force: true });
+}

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

@@ -0,0 +1,53 @@
+import { createInterface } from "node:readline";
+/**
+ * Build a prompt function. Secret prompts use raw mode + manual key
+ * accumulation on a real TTY so the input is never echoed. On a non-TTY
+ * stream (tests/pipes) input is read as a line so the value is still captured.
+ */
+export function createPrompt(deps = {}) {
+    const input = deps.input ?? process.stdin;
+    const write = deps.write ?? ((s) => process.stderr.write(s));
+    const isTTY = deps.isTTY ?? Boolean(input.isTTY);
+    return ({ label, secret }) => new Promise((resolve, reject) => {
+        write(`${label}: `);
+        if (secret && isTTY) {
+            const stdin = input;
+            const prevRaw = stdin.isRaw === true;
+            let buf = "";
+            stdin.setRawMode?.(true);
+            stdin.resume();
+            const cleanup = () => {
+                stdin.setRawMode?.(prevRaw);
+                stdin.pause();
+                stdin.off("data", onData);
+            };
+            const onData = (d) => {
+                for (const ch of d.toString("utf8")) {
+                    if (ch === "\n" || ch === "\r") {
+                        cleanup();
+                        write("\n");
+                        resolve(buf);
+                        return;
+                    }
+                    if (ch === "\u0003") {
+                        cleanup();
+                        reject(new Error("input cancelled"));
+                        return;
+                    }
+                    if (ch === "\u007f" || ch === "\b")
+                        buf = buf.slice(0, -1);
+                    else
+                        buf += ch;
+                }
+            };
+            stdin.on("data", onData);
+            return;
+        }
+        // Non-secret, or non-TTY (tests/pipes): read a single line.
+        const rl = createInterface({ input });
+        rl.once("line", (line) => {
+            rl.close();
+            resolve(line.replace(/\r?\n$/, ""));
+        });
+    });
+}

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

@@ -27,6 +27,8 @@ export async function fetchJsonSchema(deps) {
     let source = heuristicResult.empty ? "heuristic-empty" : "heuristic";
     // Run each plugin's extendSchema — a plugin may replace the schema entirely (e.g. schemata)
     for (const plugin of plugins) {
+        if (!plugin.extendSchema)
+            continue;
         const extended = await plugin.extendSchema(entity, bundle, schema, ctx);
         if (extended !== schema) {
             schema = extended;

package/dist/src/index.js

@@ -1,33 +1,51 @@
 #!/usr/bin/env node
 import { parseArgs } from "node:util";
 import { Command } from "commander";
+import { runAuthLogin, runAuthLogout, runAuthStatus } from "./commands/auth.js";
 import { runCreate } from "./commands/create.js";
 import { runDelete } from "./commands/delete.js";
 import { runRead } from "./commands/read.js";
-import { runSchema } from "./commands/schema.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 { runUploadFile } from "./commands/upload-file.js";
+import { collectProviders, providerById } from "./core/auth/registry.js";
+import { readSession, writeSession } from "./core/auth/session-store.js";
 import { createFileStore } from "./core/cache/file-store.js";
 import { createOutput } from "./core/cli/output.js";
+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 { fetchJsonSchema } from "./core/schema/jsonschema-source.js";
 import { toOperationVariant } from "./core/schema/to-jsonschema.js";
 import { validatePayload } from "./core/schema/validate.js";
-import { ConfigError, exitCodeFor } from "./errors.js";
+import { AuthError, ConfigError, exitCodeFor } from "./errors.js";
 function resolveConfigPath(override) {
     return override ?? process.env.DROPSH_CONFIG ?? "dropsh.config.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),
+    });
+}
 async function defaultContext(configPath) {
     const cfg = await loadConfig(configPath);
     const http = createHttpClient({ timeoutMs: cfg.defaults.timeout_ms });
-    const authPlugin = cfg.plugins.find((p) => p.createAuthAdapter);
-    if (!authPlugin?.createAuthAdapter) {
-        throw new ConfigError("No auth plugin configured. Add basicAuthPlugin() or oauth2Plugin() to config.plugins.");
-    }
-    const auth = authPlugin.createAuthAdapter();
+    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,
@@ -70,15 +88,42 @@ export function buildProgram(opts = {}) {
             setExitCode(exitCodeFor(err));
         }
     }
+    async function run2(fn) {
+        try {
+            await fn();
+        }
+        catch (err) {
+            output.fail(err);
+            setExitCode(exitCodeFor(err));
+        }
+    }
+    async function authDeps() {
+        const cfg = await loadConfig(resolveConfigPath(program.opts().config));
+        return {
+            baseUrl: cfg.site.base_url,
+            providers: collectProviders(cfg.plugins),
+            stdout,
+            stderr,
+            prompt: createPrompt(),
+            openBrowser: async (url) => {
+                const { default: open } = await import("open");
+                await open(url);
+            },
+            http: createHttpClient({ timeoutMs: cfg.defaults.timeout_ms }),
+            now: Date.now,
+            isTTY: Boolean(process.stdin.isTTY),
+        };
+    }
     async function loadOrFetchSchema(ctx, target, op) {
         const store = createFileStore({
-            rootDir: `${ctx.cwd}/.dropsh/cache`,
+            rootDir: siteCacheRoot(ctx.cwd, ctx.baseUrl),
             warn: (m) => stderr(`${m}\n`),
         });
         const [entity, bundle] = target.split("/", 2);
         const key = `schema/${entity}--${bundle}.${op}.json`;
+        const hookPluginIds = operationHookPluginIds(ctx.plugins);
         const hit = await store.read(key);
-        if (hit !== undefined)
+        if (hit !== undefined && schemaCacheMetadataMatches(hit, hookPluginIds))
             return hit;
         const { schema: raw, source } = await fetchJsonSchema({
             http: ctx.http,
@@ -91,11 +136,20 @@ export function buildProgram(opts = {}) {
             plugins: ctx.plugins,
         });
         const transformed = toOperationVariant(raw, op);
+        const operationExtended = await applyOperationSchemaPlugins(transformed, { entity, bundle, operation: op }, {
+            http: ctx.http,
+            auth: ctx.auth,
+            baseUrl: ctx.baseUrl,
+            plugins: ctx.plugins,
+        });
         const tagged = {
-            ...transformed,
+            ...operationExtended.schema,
             "x-dropsh-source": source,
             "x-dropsh-target": { entity_type: entity, bundle },
             "x-dropsh-operation": op,
+            "x-dropsh-schema-extensions": operationExtended.extensions,
+            "x-dropsh-schema-pipeline-version": SCHEMA_PIPELINE_VERSION,
+            "x-dropsh-operation-hook-plugins": hookPluginIds,
         };
         await store.write(key, tagged);
         return tagged;
@@ -209,6 +263,21 @@ export function buildProgram(opts = {}) {
             plugins: ctx.plugins,
         }));
     });
+    const auth = program.command("auth").description("Manage authentication");
+    auth
+        .command("login")
+        .description("Log in via an auth provider")
+        .option("--provider <id>", "skip the picker and use this provider id")
+        .action((o) => run2(async () => runAuthLogin(o.provider ? { provider: o.provider } : {}, await authDeps())));
+    auth
+        .command("logout")
+        .description("Clear the active session")
+        .action(() => run2(async () => runAuthLogout({}, await authDeps())));
+    auth
+        .command("status")
+        .description("Show the active session")
+        .option("--json", "machine-readable output")
+        .action((o) => run2(async () => runAuthStatus(o, await authDeps())));
     if (opts.plugins) {
         for (const plugin of opts.plugins) {
             plugin.registerCommands?.(program);

package/dist/src/plugin-api.js

@@ -1,4 +1,4 @@
-export { basicAuthPlugin } from "./core/auth/basic.js";
+export { basicAuthPlugin, basicAuthProvider } from "./core/auth/basic.js";
 export { loadConfig } from "./core/config.js";
 export { createHttpClient } from "./core/http.js";
 export { AuthError, ConfigError, HttpError } from "./errors.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dropsh",
-  "version": "0.0.1",
+  "version": "0.1.0",
   "description": "Entity-agnostic helper CLI for Drupal 11 JSON:API, used by the dropsh Claude skill for editorial publishing workflows.",
   "type": "module",
   "bin": {
@@ -8,7 +8,8 @@
   },
   "exports": {
     ".": "./dist/src/index.js",
-    "./plugin": "./dist/src/plugin-api.js"
+    "./plugin": "./dist/src/plugin-api.js",
+    "./package.json": "./package.json"
   },
   "files": [
     "bin",
@@ -16,20 +17,6 @@
     "README.md",
     "LICENSE"
   ],
-  "scripts": {
-    "build": "tsc",
-    "build:plugins": "npm --prefix plugins/schemata run build && npm --prefix plugins/oauth2 run build",
-    "dev": "tsx src/index.ts",
-    "test": "vitest run --passWithNoTests",
-    "test:watch": "vitest",
-    "test:integration": "npm run build && vitest run -c vitest.config.integration.ts",
-    "typecheck": "tsc --noEmit",
-    "lint": "biome check src/ tests/integrations/helpers/ tests/integrations/schema/ tests/integrations/*.ts",
-    "lint:fix": "biome check --write src/ 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",
-    "prepublishOnly": "npm run typecheck && npm run build"
-  },
   "keywords": [
     "drupal",
     "drupal11",
@@ -56,9 +43,25 @@
     "@types/node": "^20.14.0",
     "tsx": "^4.19.0",
     "typescript": "^5.6.0",
-    "vitest": "^2.1.0"
+    "vite": "^6.4.3",
+    "vitest": "^4.1.8"
   },
   "engines": {
     "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc",
+    "build:packages": "pnpm --filter \"./packages/*\" run build",
+    "build:plugins": "pnpm --filter \"./plugins/*\" run build",
+    "dev": "tsx src/index.ts",
+    "test": "vitest run --passWithNoTests",
+    "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",
+    "drupal:up": "bash tests/integrations/bin/drupal-up.sh",
+    "drupal:down": "bash tests/integrations/bin/drupal-down.sh",
+    "release": "pnpm -r --include-workspace-root publish --no-git-checks"
   }
-}
+}

package/dist/src/commands/login.js

@@ -1,121 +0,0 @@
-import { createHash, randomBytes } from "node:crypto";
-import { createServer } from "node:http";
-import { writeToken } from "../core/auth/token-store.js";
-import { loadConfig } from "../core/config.js";
-import { createHttpClient } from "../core/http.js";
-import { AuthError } from "../errors.js";
-const DEFAULT_PORT = 7432;
-const DEFAULT_TIMEOUT_MS = 5 * 60 * 1000;
-export function generatePkce() {
-    const verifier = randomBytes(96).toString("base64url");
-    const challenge = createHash("sha256").update(verifier).digest("base64url");
-    return { verifier, challenge };
-}
-export function generateState() {
-    return randomBytes(16).toString("base64url");
-}
-export async function runLogin(deps = {}) {
-    const stdout = deps.stdout ?? ((s) => process.stdout.write(`${s}\n`));
-    const configPath = deps.configPath ?? (process.env.DRUPAL_CLI_CONFIG ?? ".drupal-cli.yml");
-    const timeoutMs = deps.timeoutMs ?? DEFAULT_TIMEOUT_MS;
-    const now = deps.now ?? Date.now;
-    const http = deps.http ?? createHttpClient();
-    const pkce = (deps._generatePkce ?? generatePkce)();
-    const state = (deps._generateState ?? generateState)();
-    const cfg = await loadConfig(configPath);
-    const { auth, base_url: baseUrl } = cfg.site;
-    if (auth.type !== "oauth2_authcode") {
-        throw new AuthError("login requires auth.type: oauth2_authcode in config");
-    }
-    const clientId = auth.client_id;
-    if (typeof clientId !== "string" || clientId.length === 0) {
-        throw new AuthError("oauth2_authcode auth requires client_id");
-    }
-    const scope = typeof auth.scope === "string" ? auth.scope : "";
-    const port = typeof auth.redirect_port === "number" ? auth.redirect_port : DEFAULT_PORT;
-    const redirectUri = `http://localhost:${port}/callback`;
-    const baseUrlNorm = baseUrl.replace(/\/$/, "");
-    const tokenEndpoint = `${baseUrlNorm}/oauth/token`;
-    const authUrl = new URL(`${baseUrlNorm}/oauth/authorize`);
-    authUrl.searchParams.set("response_type", "code");
-    authUrl.searchParams.set("client_id", clientId);
-    authUrl.searchParams.set("redirect_uri", redirectUri);
-    authUrl.searchParams.set("code_challenge", pkce.challenge);
-    authUrl.searchParams.set("code_challenge_method", "S256");
-    authUrl.searchParams.set("state", state);
-    if (scope)
-        authUrl.searchParams.set("scope", scope);
-    const code = await new Promise((resolve, reject) => {
-        let settled = false;
-        const finish = (fn) => {
-            if (settled)
-                return;
-            settled = true;
-            clearTimeout(timer);
-            server.close(() => fn());
-        };
-        const server = createServer((req, res) => {
-            const url = new URL(req.url ?? "/", `http://localhost:${port}`);
-            if (url.pathname !== "/callback") {
-                res.writeHead(404);
-                res.end();
-                return;
-            }
-            res.writeHead(200, { "Content-Type": "text/html" });
-            res.end("<html><body><p>Login successful. You can close this tab.</p></body></html>");
-            const receivedState = url.searchParams.get("state");
-            const receivedCode = url.searchParams.get("code");
-            if (receivedState !== state) {
-                finish(() => reject(new AuthError("OAuth state mismatch — possible CSRF attack")));
-                return;
-            }
-            if (!receivedCode) {
-                finish(() => reject(new AuthError("No authorization code received")));
-                return;
-            }
-            finish(() => resolve(receivedCode));
-        });
-        server.on("error", (err) => {
-            finish(() => reject(err));
-        });
-        const timer = setTimeout(() => {
-            finish(() => reject(new AuthError("Login timed out. Run 'drupal-cli login' to try again.")));
-        }, timeoutMs);
-        server.listen(port, () => {
-            stdout("Opening browser for login...");
-            stdout(`If the browser does not open, visit:\n${authUrl.toString()}`);
-            const openBrowser = deps.openBrowser ?? (async (url) => {
-                const { default: open } = await import("open");
-                await open(url);
-            });
-            openBrowser(authUrl.toString()).catch(() => {
-                // The URL is printed above, so the user still has a manual fallback.
-            });
-        });
-    });
-    const params = new URLSearchParams({
-        grant_type: "authorization_code",
-        code,
-        code_verifier: pkce.verifier,
-        client_id: clientId,
-        redirect_uri: redirectUri,
-    });
-    const res = await http.send({
-        method: "POST",
-        url: tokenEndpoint,
-        headers: { "Content-Type": "application/x-www-form-urlencoded" },
-        body: params.toString(),
-    });
-    const body = JSON.parse(res.body);
-    if (typeof body.access_token !== "string") {
-        throw new AuthError("Token endpoint returned no access_token");
-    }
-    const ttlSec = typeof body.expires_in === "number" ? body.expires_in : 3600;
-    const expiresAt = now() + ttlSec * 1000 - 5000;
-    await writeToken(baseUrl, {
-        access_token: body.access_token,
-        ...(typeof body.refresh_token === "string" ? { refresh_token: body.refresh_token } : {}),
-        expires_at: expiresAt,
-    }, deps.tokenDir);
-    stdout(`Logged in · token valid until ${new Date(expiresAt).toISOString()}`);
-}

package/dist/src/core/auth/api-key.js

@@ -1,13 +0,0 @@
-import { AuthError } from "../../errors.js";
-export function createApiKeyAuth(cfg) {
-    const key = cfg.key;
-    const header = typeof cfg.header === "string" ? cfg.header : "X-API-Key";
-    if (typeof key !== "string" || key.length === 0) {
-        throw new AuthError("api_key auth requires key");
-    }
-    return {
-        async apply(req) {
-            return { ...req, headers: { ...(req.headers ?? {}), [header]: key } };
-        },
-    };
-}

package/dist/src/core/auth/factory.js

@@ -1,17 +0,0 @@
-import { AuthError } from "../../errors.js";
-import { createBasicAuth } from "./basic.js";
-import { createOAuth2AuthCodeAuth } from "./oauth2-authcode.js";
-import { createOAuth2Auth } from "./oauth2.js";
-export function createAuthAdapter(cfg, deps) {
-    switch (cfg.type) {
-        case "basic":
-            return createBasicAuth(cfg);
-        case "oauth2_password":
-        case "oauth2_client_credentials":
-            return createOAuth2Auth(cfg, { http: deps.http, baseUrl: deps.baseUrl });
-        case "oauth2_authcode":
-            return createOAuth2AuthCodeAuth(cfg, { http: deps.http, baseUrl: deps.baseUrl });
-        default:
-            throw new AuthError(`Unknown auth.type: ${String(cfg.type)}`);
-    }
-}

package/dist/src/core/auth/jwt.js

@@ -1,12 +0,0 @@
-import { AuthError } from "../../errors.js";
-export function createJwtAuth(cfg) {
-    const token = cfg.token;
-    if (typeof token !== "string" || token.length === 0) {
-        throw new AuthError("jwt auth requires token");
-    }
-    return {
-        async apply(req) {
-            return { ...req, headers: { ...(req.headers ?? {}), Authorization: `Bearer ${token}` } };
-        },
-    };
-}

package/dist/src/core/auth/oauth2-authcode.js

@@ -1,67 +0,0 @@
-import { AuthError, HttpError } from "../../errors.js";
-import { readToken, writeToken } from "./token-store.js";
-function requireString(cfg, key) {
-    const value = cfg[key];
-    if (typeof value !== "string" || value.length === 0) {
-        throw new AuthError(`${cfg.type} auth requires ${key}`);
-    }
-    return value;
-}
-export function createOAuth2AuthCodeAuth(cfg, deps) {
-    const now = deps.now ?? Date.now;
-    const clientId = requireString(cfg, "client_id");
-    const tokenUrl = typeof cfg.token_url === "string" ? cfg.token_url : `${deps.baseUrl.replace(/\/$/, "")}/oauth/token`;
-    return {
-        async apply(req) {
-            const stored = await readToken(deps.baseUrl, deps.tokenDir);
-            if (!stored) {
-                throw new AuthError("Session expired. Run 'drupal-cli login' to authenticate.");
-            }
-            if (stored.expires_at - 30_000 > now()) {
-                return {
-                    ...req,
-                    headers: { ...(req.headers ?? {}), Authorization: `Bearer ${stored.access_token}` },
-                };
-            }
-            if (!stored.refresh_token) {
-                throw new AuthError("Session expired. Run 'drupal-cli login' to authenticate.");
-            }
-            try {
-                const params = new URLSearchParams({
-                    grant_type: "refresh_token",
-                    refresh_token: stored.refresh_token,
-                    client_id: clientId,
-                });
-                const res = await deps.http.send({
-                    method: "POST",
-                    url: tokenUrl,
-                    headers: { "Content-Type": "application/x-www-form-urlencoded" },
-                    body: params.toString(),
-                });
-                const body = JSON.parse(res.body);
-                if (typeof body.access_token !== "string") {
-                    throw new AuthError("Token endpoint returned no access_token");
-                }
-                const ttlSec = typeof body.expires_in === "number" ? body.expires_in : 3600;
-                const refreshed = {
-                    access_token: body.access_token,
-                    refresh_token: typeof body.refresh_token === "string" ? body.refresh_token : stored.refresh_token,
-                    expires_at: now() + ttlSec * 1000 - 5000,
-                };
-                await writeToken(deps.baseUrl, refreshed, deps.tokenDir);
-                return {
-                    ...req,
-                    headers: { ...(req.headers ?? {}), Authorization: `Bearer ${refreshed.access_token}` },
-                };
-            }
-            catch (err) {
-                if (err instanceof AuthError)
-                    throw err;
-                if (err instanceof HttpError) {
-                    throw new AuthError("Session expired. Run 'drupal-cli login' to authenticate.", { status: err.status, body: err.body });
-                }
-                throw new AuthError("Session expired. Run 'drupal-cli login' to authenticate.");
-            }
-        },
-    };
-}

package/dist/src/core/auth/oauth2.js

@@ -1,64 +0,0 @@
-import { AuthError, HttpError } from "../../errors.js";
-function requireString(cfg, key) {
-    const v = cfg[key];
-    if (typeof v !== "string" || v.length === 0) {
-        throw new AuthError(`${cfg.type} auth requires ${key}`);
-    }
-    return v;
-}
-export function createOAuth2Auth(cfg, deps) {
-    const now = deps.now ?? Date.now;
-    const clientId = requireString(cfg, "client_id");
-    const clientSecret = requireString(cfg, "client_secret");
-    const tokenUrl = typeof cfg.token_url === "string" ? cfg.token_url : `${deps.baseUrl.replace(/\/$/, "")}/oauth/token`;
-    const params = new URLSearchParams({
-        client_id: clientId,
-        client_secret: clientSecret,
-    });
-    if (cfg.type === "oauth2_password") {
-        params.set("grant_type", "password");
-        params.set("username", requireString(cfg, "username"));
-        params.set("password", requireString(cfg, "password"));
-        if (typeof cfg.scope === "string")
-            params.set("scope", cfg.scope);
-    }
-    else if (cfg.type === "oauth2_client_credentials") {
-        params.set("grant_type", "client_credentials");
-        if (typeof cfg.scope === "string")
-            params.set("scope", cfg.scope);
-    }
-    else {
-        throw new AuthError(`Unsupported oauth2 grant: ${cfg.type}`);
-    }
-    let cached = null;
-    async function fetchToken() {
-        try {
-            const res = await deps.http.send({
-                method: "POST",
-                url: tokenUrl,
-                headers: { "Content-Type": "application/x-www-form-urlencoded" },
-                body: params.toString(),
-            });
-            const body = JSON.parse(res.body);
-            if (typeof body.access_token !== "string") {
-                throw new AuthError("Token endpoint returned no access_token");
-            }
-            const ttlSec = typeof body.expires_in === "number" ? body.expires_in : 3600;
-            return { token: body.access_token, expiresAt: now() + ttlSec * 1000 - 5000 };
-        }
-        catch (err) {
-            if (err instanceof HttpError)
-                throw new AuthError(`Token request failed: HTTP ${err.status}`, { body: err.body });
-            if (err instanceof AuthError)
-                throw err;
-            throw new AuthError(`Token request failed: ${err.message}`);
-        }
-    }
-    return {
-        async apply(req) {
-            if (!cached || cached.expiresAt <= now())
-                cached = await fetchToken();
-            return { ...req, headers: { ...(req.headers ?? {}), Authorization: `Bearer ${cached.token}` } };
-        },
-    };
-}

package/dist/src/core/auth/token-store.js

@@ -1,26 +0,0 @@
-import { mkdir, readFile, writeFile } from "node:fs/promises";
-import { homedir } from "node:os";
-import { join } from "node:path";
-function hostnameFromUrl(baseUrl) {
-    return new URL(baseUrl).hostname;
-}
-export function defaultTokenDir() {
-    return join(homedir(), ".config", "drupal-cli");
-}
-export async function readToken(baseUrl, dir) {
-    const tokenDir = dir ?? defaultTokenDir();
-    const tokenPath = join(tokenDir, `${hostnameFromUrl(baseUrl)}.json`);
-    try {
-        const raw = await readFile(tokenPath, "utf8");
-        return JSON.parse(raw);
-    }
-    catch {
-        return null;
-    }
-}
-export async function writeToken(baseUrl, token, dir) {
-    const tokenDir = dir ?? defaultTokenDir();
-    await mkdir(tokenDir, { recursive: true });
-    const tokenPath = join(tokenDir, `${hostnameFromUrl(baseUrl)}.json`);
-    await writeFile(tokenPath, JSON.stringify(token, null, 2), { encoding: "utf8", mode: 0o600 });
-}

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

@@ -1,18 +0,0 @@
-export function buildQueryString(q) {
-    const params = new URLSearchParams();
-    for (const f of q.filter ?? []) {
-        params.append(`filter[${f.key}][value]`, f.value);
-        if (f.operator)
-            params.append(`filter[${f.key}][operator]`, f.operator);
-    }
-    if (q.sort)
-        params.append("sort", q.sort);
-    if (q.page?.limit !== undefined)
-        params.append("page[limit]", String(q.page.limit));
-    if (q.page?.offset !== undefined)
-        params.append("page[offset]", String(q.page.offset));
-    if (q.include && q.include.length > 0)
-        params.append("include", q.include.join(","));
-    const s = params.toString();
-    return s.length === 0 ? "" : `?${s}`;
-}