dropsh 0.0.2 → 0.1.1

package/README.md

@@ -1,344 +1,245 @@
 # dropsh
 
-Entity-agnostic helper CLI for Drupal 11 JSON:API. Written in TypeScript, used directly by the `dropsh` Claude skill for editorial publishing workflows.
-
-This is the foundation CLI. Discovery, schema generation, and the skill layer are delivered by follow-up plans.
+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.
+
+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 is a [pnpm](https://pnpm.io) workspace (root CLI + `plugins/*` + `packages/*`).
-The pinned pnpm version is declared in `package.json` (`packageManager`); enable it with
-`corepack enable`.
+This repository is a pnpm workspace containing the root CLI, packages, and
+plugins.
 
 ```bash
+corepack enable
 pnpm install
 pnpm run build
 ```
 
-## Configure
-
-Copy `dropsh.config.example.js` to `dropsh.config.js` in your project. The config
-carries only **non-secret connection parameters** — secrets (passwords, client
-secrets, tokens) are never stored in the config. They are prompted at login and
-persisted separately (see [Authentication](#authentication)).
-
-```js
-import { basicAuthPlugin } from "dropsh";
-import { oauth2Plugin } from "@dropsh/plugin-oauth2";
-
-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" }),
-  ],
-};
-```
-
-## Authentication
-
-Authentication is provider-based. Each entry in `plugins` that contributes an auth
-provider (`basicAuthPlugin()`, `oauth2Plugin(...)`) becomes a login option. You log
-in once per host; dropsh stores a single active session and uses it for every
-subsequent command.
+The required Node.js and pinned pnpm versions are declared in `package.json`.
 
-```bash
-dropsh auth login                  # interactive picker over the configured providers
-dropsh auth login --provider basic # skip the picker and use a provider by id
-dropsh auth logout                 # clear the active session for the host
-dropsh auth status                 # show the active session
-dropsh auth status --json          # machine-readable status
-```
+## Drupal Prerequisites
 
-`dropsh auth login` prompts for any secrets the chosen provider needs (basic auth
-prompts username + password; OAuth2 password / client-credentials prompt the client
-secret and, for the password grant, the user password; `oauth2_authcode` opens the
-browser for a PKCE flow). On a non-interactive (non-TTY) shell you must pass
-`--provider <id>`.
+The base CLI expects a Drupal site with JSON:API enabled and reachable from the
+machine running dropsh.
 
-### Where secrets live
+Minimum Drupal setup:
 
-Secrets and tokens are **never** written to `dropsh.config.js`. The active session
-is stored per host at `~/.config/dropsh/<host>.json` with file mode `0600`:
+- Drupal 10 or 11
+- JSON:API enabled
+- A user or OAuth client with permissions for the entities you want to access
 
-```json
-{ "activeProvider": "oauth2_authcode", "session": { "access_token": "…", "expires_at": 1717459200000 } }
-```
+Optional modules unlock stricter schemas or builder-specific support:
 
-Only non-secret connection parameters stay in the config:
+| 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` |
 
-- **basic** — `basicAuthPlugin()` (no fields; an optional `username` may be
-  pre-seeded, but the password is always prompted)
-- **oauth2** — `client_id`, `token_url`, optional `scope`; `redirect_port` for
-  `oauth2_authcode`; `username` for `oauth2_password`. The `client_secret` and the
-  user `password` are prompted at login, never stored in config.
+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.
 
-## Commands
+### Installing the Drupal modules
 
-All commands write JSON to stdout, structured errors to stderr, and use exit codes 0-5.
+JSON:API ships with Drupal core; enable it together with the optional modules
+you need:
 
 ```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 delete <entity_type>/<bundle>/<uuid> [--dry-run]
-dropsh upload-file --target=<entity_type>/<bundle>/<uuid>/<field> --file=<path> [--dry-run]
-dropsh schema [--refresh]
-dropsh schema <entity_type>/<bundle> [--for=create|update] [--refresh]
+# 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"
 ```
 
-### `schema`
-
-Without a target, prints the list of available `<entity_type>/<bundle>` targets on the site.
-
-With a target (e.g. `node/article`), prints a JSON Schema document that validates a JSON:API request body for that resource.
+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.
 
-- `--for=create` (default) / `--for=update` — operation variant (update clears required fields)
-- `--refresh` — bypass the cache for this call
+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`).
 
-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.
+## Configuration
 
-Schemas are cached under `.dropsh/cache/`. Override the config path via `DROPSH_CONFIG` or `--config`.
-
-### Authoritative schemas — `@dropsh/plugin-schemata`
-
-Without a schema plugin, the schema is derived from sample records (field names
-only). [`@dropsh/plugin-schemata`](plugins/schemata/README.md) returns the
-authoritative schema (required fields + constraints) from Drupal's `schemata`
-module, which makes client-side validation in `create` / `update` meaningful.
-Requires the Drupal modules `schemata` + `jsonapi_schema`.
-
-```js
-import { schemataPlugin } from "@dropsh/plugin-schemata";
-
-export default {
-  site: { base_url: "https://my-drupal.example.com", jsonapi_prefix: "/jsonapi" },
-  plugins: [basicAuthPlugin(), schemataPlugin()],
-};
-```
-
-The output's `x-dropsh-source` is `"schemata"` when authoritative, or
-`"heuristic"` / `"heuristic-empty"` for the sample-derived fallback.
-
-### Canvas schema plugin
-
-Canvas support lives in `@dropsh/plugin-canvas` and requires these Drupal modules:
-
-- `canvas`
-- `jsonapi_sdc`
-
-Register the plugin in `dropsh.config.js`:
+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 { canvasPlugin } from "@dropsh/plugin-canvas";
+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" },
+  site: {
+    base_url: "https://my-drupal.example.com",
+    jsonapi_prefix: "/jsonapi",
+  },
+  defaults: {
+    dry_run: false,
+    timeout_ms: 30000,
+  },
   plugins: [
     basicAuthPlugin(),
-    canvasPlugin(),
+    oauth2Plugin({
+      type: "oauth2_authcode",
+      client_id: "my-client",
+      token_url: "https://my-drupal.example.com/oauth/token",
+    }),
+    schemataPlugin(),
   ],
 };
 ```
 
-Then ask for the Canvas schema:
+Use `dropsh.config.example.js` as a fuller starting point. Override the config
+path with `--config <path>` or `DROPSH_CONFIG`.
+
+## Authentication
+
+Authentication is configured through plugins. Each plugin that contributes an
+auth provider appears as a login option.
 
 ```bash
-dropsh schema canvas_page/canvas_page --for=create
+dropsh auth login
+dropsh auth login --provider basic
+dropsh auth status
+dropsh auth logout
 ```
 
-The returned JSON Schema includes `x-dropsh-builder: "canvas"`, `x-dropsh-components`, and a typed `attributes.components` array. If `jsonapi_sdc` is missing or inaccessible, the Canvas schema fails instead of returning incomplete component information.
+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`.
 
-### Client-side validation in `create` / `update`
+## Commands
 
-`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.
+All commands write JSON to stdout, structured errors to stderr, and use stable
+exit codes.
 
-## Writing plugins
+```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 delete <entity_type>/<bundle>/<uuid> [--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]
+```
 
-A plugin is a function that returns a `DropSHPlugin`. Plugins can do three
-independent things — extend schemas, provide an auth provider, and register CLI
-commands — and a single plugin may combine any of them. Everything you need is
-re-exported from `dropsh/plugin`:
+`create` and `update` validate payloads against the current schema by default.
+Pass `--no-validate` when you intentionally want to skip local validation.
 
-```ts
-import type {
-  DropSHPlugin, PluginContext, SchemaOperation, // schema extension
-  AuthProvider, AuthContext, AuthSession, AdapterRuntime, AuthAdapter, // auth
-} from "dropsh/plugin";
-import { AuthError, ConfigError, HttpError, createHttpClient } from "dropsh/plugin";
-```
+## Plugins
 
-The `DropSHPlugin` shape:
+Plugins are regular JavaScript or TypeScript modules that return a `dropshPlugin`.
+A plugin can contribute one or more of these capabilities:
 
-```ts
-interface DropSHPlugin {
-  readonly id: string;             // unique id, also the auth-provider key
-  readonly requiredModules: string[]; // Drupal modules the plugin needs
-  authProvider?: AuthProvider;     // optional: contributes a login option
-  extendSchema(entityType, bundle, baseSchema, ctx): Promise<unknown>;
-  extendOperationSchema?(entityType, bundle, operation, schema, ctx): Promise<unknown>;
-  registerCommands?(program): void; // optional: add Commander subcommands
-}
-```
+- 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.
 
-A plugin is wired up by adding it to `plugins` in `dropsh.config.js`. Package it
-as its own npm module with `dropsh` as a **peer dependency** (so it shares the
-host's core), or keep it local and import it directly.
+Bundled plugins:
 
-### A schema-extension plugin
+| 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 |
 
-`extendSchema` is called while building the JSON Schema for a target. It receives
-the schema produced so far and returns a (possibly) modified schema. Return
-`baseSchema` unchanged when the plugin does not apply. `extendOperationSchema`
-runs later, per operation (`create` / `update`), when you need to vary the schema
-by operation. `ctx: PluginContext` gives you `{ http, auth, baseUrl }` to call the
-site if you need live data.
+Plugin APIs are exported from `dropsh/plugin`:
 
 ```ts
-import type { DropSHPlugin, PluginContext, SchemaOperation } from "dropsh/plugin";
+import type { dropshPlugin } from "dropsh/plugin";
 
-// Marks node/article's `field_legacy_id` read-only and adds a provenance tag.
-export function articleRulesPlugin(): DropSHPlugin {
+export function examplePlugin(): dropshPlugin {
   return {
-    id: "article-rules",
+    id: "example",
     requiredModules: [],
-
-    async extendSchema(entityType: string, bundle: string, baseSchema: unknown, _ctx: PluginContext) {
-      if (entityType !== "node" || bundle !== "article") return baseSchema;
-      const schema = baseSchema as {
-        properties?: { attributes?: { properties?: Record<string, unknown> } };
-      };
-      const attrs = schema.properties?.attributes?.properties;
-      if (attrs?.field_legacy_id && typeof attrs.field_legacy_id === "object") {
-        (attrs.field_legacy_id as Record<string, unknown>).readOnly = true;
-      }
-      return { ...schema, "x-extended-by": "article-rules" };
-    },
-
-    // Optional: on create, require a field that is optional on update.
-    async extendOperationSchema(
-      entityType: string,
-      bundle: string,
-      operation: SchemaOperation,
-      schema: unknown,
-      _ctx: PluginContext,
-    ) {
-      if (entityType !== "node" || bundle !== "article" || operation !== "create") return schema;
-      const s = schema as { required?: string[] };
-      const required = new Set(s.required ?? []);
-      required.add("field_legacy_id");
-      return { ...s, required: [...required] };
+    async extendSchema(_entityType, _bundle, schema) {
+      return schema;
     },
   };
 }
 ```
 
-Register it:
+Register local or package plugins in `dropsh.config.js`:
 
 ```js
-import { articleRulesPlugin } from "./plugins/article-rules.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(), articleRulesPlugin()],
+  plugins: [basicAuthPlugin(), examplePlugin()],
 };
 ```
 
-The bundled `@dropsh/plugin-schemata` (authoritative schemas from the Drupal
-`schemata` module) and `@dropsh/plugin-canvas` (component schemas) are real
-examples of schema plugins — see `plugins/schemata/src/index.ts` and
-`plugins/canvas/src/index.ts`.
-
-### An auth-provider plugin
-
-An auth provider is a single `AuthProvider` object exposed via the plugin's
-`authProvider` field. It owns one protocol end-to-end: `login` acquires a session
-(prompting / browser as needed), `createAdapter` turns a stored session into the
-`apply(req)` runtime hook, and `logout` / `status` round it out. The core handles
-the picker, the single-session state file, and dispatch — the provider never
-touches stdin or disk directly; it uses the injected `AuthContext` / `AdapterRuntime`.
-
-```ts
-import type {
-  AdapterRuntime, AuthAdapter, AuthContext, AuthProvider, AuthSession, DropSHPlugin,
-} from "dropsh/plugin";
-import { ConfigError } from "dropsh/plugin";
-
-// Static API-key auth: prompts for a token at login, sends it as a header.
-export function apiKeyProvider(): AuthProvider {
-  return {
-    id: "apikey",
-    displayName: "API key (X-API-Key header)",
-    capabilities: { login: true, logout: true, status: true },
-
-    async login(ctx: AuthContext): Promise<AuthSession> {
-      const key = await ctx.prompt({ label: "API key", secret: true });
-      if (!key) throw new ConfigError("apikey: a non-empty key is required");
-      return { api_key: key };
-    },
+## Example Skills
 
-    async logout(_ctx: AuthContext) {
-      // No server-side revoke; the core clears the local session file.
-    },
+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.
 
-    async status(session: AuthSession | null) {
-      return { loggedIn: session !== null, provider: "apikey" };
-    },
+See [docs/examples/skills](docs/examples/skills/README.md) for three example
+skill structures:
 
-    createAdapter(session: AuthSession, _rt: AdapterRuntime): AuthAdapter {
-      const key = session.api_key;
-      if (typeof key !== "string") throw new ConfigError("apikey: corrupt session");
-      return {
-        async apply(req) {
-          return { ...req, headers: { ...(req.headers ?? {}), "X-API-Key": key } };
-        },
-      };
-    },
-  };
-}
-
-export function apiKeyPlugin(): DropSHPlugin {
-  return {
-    id: "apikey",
-    requiredModules: [],
-    authProvider: apiKeyProvider(),
-    async extendSchema(_entityType, _bundle, schema) {
-      return schema; // not a schema plugin
-    },
-  };
-}
-```
-
-Once registered in `plugins`, it shows up automatically in `dropsh auth login`:
-
-```bash
-dropsh auth login --provider apikey
-```
-
-`AuthContext` (passed to `login`/`logout`) provides `baseUrl`, an `http` client,
-`prompt({ label, secret })`, `openBrowser(url)`, `stdout(s)`, and `now()`.
-`AdapterRuntime` (passed to `createAdapter`) provides `http`, `now()`, and
-`save(session)` — call `save` to persist a refreshed session back to the active
-slot (the OAuth2 `oauth2_authcode` provider uses this to store a refreshed token).
-Throw `AuthError` for expired/invalid sessions so the CLI exits with code 3 and
-tells the user to run `dropsh auth login`. The bundled `@dropsh/plugin-oauth2`
-(`plugins/oauth2/src/provider.ts`) and the core basic provider
-(`src/core/auth/basic.ts`) are full reference implementations.
+- 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
-pnpm test            # Vitest unit suite
-pnpm run test:watch
+pnpm test
 pnpm run typecheck
 pnpm run build
 ```
 
-### Integration tests
-
-Local-only, requires DDEV. See `tests/integrations/README.md`.
+Integration tests require DDEV:
 
 ```bash
 pnpm run drupal:up
@@ -348,14 +249,10 @@ pnpm run drupal:down
 
 ## Publishing
 
-The CLI and all workspace packages are published together with a single command:
+The CLI and workspace packages are published together from the `1.x` branch:
 
 ```bash
 pnpm run release
 ```
 
-This publishes `dropsh` (workspace root) plus `@dropsh/sdc-client`,
-`@dropsh/plugin-schemata`, `@dropsh/plugin-oauth2` and `@dropsh/plugin-canvas`.
-`prepublishOnly` runs typecheck + build per package; scoped packages publish with
-public access via their `publishConfig`, and pnpm rewrites `workspace:*` deps to the
-released version. Log in first with `npm login`.
+Run `npm login` first. `prepublishOnly` runs typecheck and build before publish.

package/dist/src/commands/schema.js

@@ -5,6 +5,15 @@ 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);
 }
@@ -40,7 +49,10 @@ export async function applyOperationSchemaPlugins(schema, args, deps) {
 }
 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");

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

@@ -39,8 +39,5 @@ export function basicAuthPlugin(config = {}) {
         id: "basic",
         requiredModules: [],
         authProvider: basicAuthProvider(config),
-        async extendSchema(_entityType, _bundle, schema, _ctx) {
-            return schema;
-        },
     };
 }

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

@@ -5,7 +5,7 @@ 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 { applyOperationSchemaPlugins, operationHookPluginIds, runSchema, SCHEMA_PIPELINE_VERSION, schemaCacheMetadataMatches, } 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";
@@ -116,7 +116,7 @@ export function buildProgram(opts = {}) {
     }
     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);

package/dist/src/plugin-api.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dropsh",
-  "version": "0.0.2",
+  "version": "0.1.1",
   "description": "Entity-agnostic helper CLI for Drupal 11 JSON:API, used by the dropsh Claude skill for editorial publishing workflows.",
   "type": "module",
   "bin": {
@@ -56,12 +56,12 @@
     "dev": "tsx src/index.ts",
     "test": "vitest run --passWithNoTests",
     "test:watch": "vitest",
-    "test:integration": "pnpm 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",
+    "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 publish --no-git-checks && pnpm -r publish --no-git-checks"
+    "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}`;
-}