dropsh 0.5.3 → 0.5.6

package/README.md

@@ -439,6 +439,29 @@ export default {
 };
 ```
 
+`dropsh/plugin` ships its own TypeScript declarations (as do the
+`@dropsh/plugin-*` packages), so `import { DropSHPlugin } from "dropsh/plugin"`
+is typed with no ambient `declare module`.
+
+### Composing plugins
+
+`composePlugins(...children)` bundles several plugins into one flat list, so an
+aggregator plugin can present N children from a **single** `plugins[]` entry
+without hand-merging their hooks. dropsh flattens a nested array — or an array
+returned by a plugin factory — into separate entries; each child's own
+`dependencies` still expand first, and duplicate ids are de-duplicated.
+
+```ts
+import { composePlugins } from "dropsh/plugin";
+import { markdownPlugin } from "@dropsh/plugin-markdown";
+import { jsonapiSchemaPlugin } from "@dropsh/plugin-jsonapi-schema";
+
+export function essentials() {
+  return composePlugins(markdownPlugin(), jsonapiSchemaPlugin());
+}
+// config: plugins: [essentials()]  ← one entry, flattened into N children
+```
+
 ## Example Skills
 
 A dropsh skill does not need to know every Drupal internal. Keep `SKILL.md` as a

package/dist/src/commands/_data.d.ts

@@ -0,0 +1 @@
+export declare function readDataArg(raw: string): Promise<unknown>;

package/dist/src/commands/auth.d.ts

@@ -0,0 +1,30 @@
+import type { AuthContext, AuthProvider } from "../core/auth/types.js";
+export interface AuthDeps {
+    baseUrl: string;
+    providers: AuthProvider[];
+    stdout: (s: string) => void;
+    stderr: (s: string) => void;
+    prompt: (opts: {
+        label: string;
+        secret?: boolean;
+    }) => Promise<string>;
+    openBrowser: (url: string) => Promise<void>;
+    http: AuthContext["http"];
+    now: () => number;
+    isTTY: boolean;
+    stateDir?: string;
+}
+export declare function runAuthLogin(args: {
+    provider?: string;
+}, deps: AuthDeps): Promise<void>;
+export declare function runAuthUse(args: {
+    profile: string;
+}, deps: AuthDeps): Promise<void>;
+export declare function runAuthLogout(args: {
+    profile?: string;
+    all?: boolean;
+}, deps: AuthDeps): Promise<void>;
+export declare function runAuthStatus(args: {
+    json?: boolean;
+    profile?: string;
+}, deps: AuthDeps): Promise<void>;

package/dist/src/commands/create.d.ts

@@ -0,0 +1,14 @@
+import type { JsonApiClient } from "../core/jsonapi/client.js";
+export interface CreateArgs {
+    entityType: string;
+    bundle: string;
+    dataArg: string;
+    dryRun?: boolean;
+    noValidate?: boolean;
+}
+export interface CreateDeps {
+    client: JsonApiClient;
+    emit: (v: unknown) => void | Promise<void>;
+    validate?: (payload: unknown, target: string) => void | Promise<void>;
+}
+export declare function runCreate(args: CreateArgs, deps: CreateDeps): Promise<void>;

package/dist/src/commands/delete.d.ts

@@ -0,0 +1,10 @@
+import type { JsonApiClient } from "../core/jsonapi/client.js";
+export interface DeleteArgs {
+    target: string;
+    dryRun?: boolean;
+}
+export interface DeleteDeps {
+    client: JsonApiClient;
+    emit: (v: unknown) => void;
+}
+export declare function runDelete(args: DeleteArgs, deps: DeleteDeps): Promise<void>;

package/dist/src/commands/read.d.ts

@@ -0,0 +1,10 @@
+import type { JsonApiClient } from "../core/jsonapi/client.js";
+export interface ReadArgs {
+    target: string;
+    include?: string[];
+}
+export interface ReadDeps {
+    client: JsonApiClient;
+    emit: (v: unknown) => void | Promise<void>;
+}
+export declare function runRead(args: ReadArgs, deps: ReadDeps): Promise<void>;

package/dist/src/commands/schema.d.ts

@@ -0,0 +1,42 @@
+import type { AuthAdapter } from "../core/auth/types.js";
+import type { HttpClient } from "../core/http.js";
+import type { DropSHPlugin } from "../core/plugin.js";
+import { type Operation } from "../core/schema/to-jsonschema.js";
+export interface SchemaArgs {
+    target?: string;
+    operation: Operation;
+    refresh: boolean;
+}
+export interface SchemaDeps {
+    http: HttpClient;
+    auth: AuthAdapter;
+    baseUrl: string;
+    jsonapiPrefix: string;
+    cwd: string;
+    emit: (v: unknown) => void;
+    warn: (m: string) => void;
+    plugins?: DropSHPlugin[];
+}
+export declare 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 declare function siteCacheRoot(cwd: string, baseUrl: string): string;
+export declare function operationHookPluginIds(plugins: DropSHPlugin[]): string[];
+export declare function schemaCacheMetadataMatches(schema: unknown, operationHookPlugins: string[]): boolean;
+export declare function applyOperationSchemaPlugins(schema: unknown, args: {
+    entity: string;
+    bundle: string;
+    operation: Operation;
+}, deps: {
+    http: HttpClient;
+    auth: AuthAdapter;
+    baseUrl: string;
+    plugins: DropSHPlugin[];
+}): Promise<{
+    schema: unknown;
+    extensions: string[];
+}>;
+export declare function runSchema(args: SchemaArgs, deps: SchemaDeps): Promise<void>;

package/dist/src/commands/search.d.ts

@@ -0,0 +1,23 @@
+import type { JsonApiClient } from "../core/jsonapi/client.js";
+export interface SearchArgs {
+    entityType: string;
+    bundle?: string;
+    filters: string[];
+    limit: number;
+    offset?: number;
+    /** JSON:API sort field; a leading `-` requests descending order. */
+    sort?: string;
+    include?: string[];
+}
+export interface SearchDeps {
+    client: JsonApiClient;
+    emit: (v: unknown) => void | Promise<void>;
+}
+export interface ParsedFilter {
+    key: string;
+    /** Filter value, or `null` for value-less operators (IS NULL / IS NOT NULL). */
+    value: string | null;
+    operator?: string;
+}
+export declare function parseFilterFlag(raw: string): ParsedFilter;
+export declare function runSearch(args: SearchArgs, deps: SearchDeps): Promise<void>;

package/dist/src/commands/search.js

@@ -1,29 +1,86 @@
 import { DrupalJsonApiParams } from "drupal-jsonapi-params";
 import { ValidationError } from "../errors.js";
+/**
+ * JSON:API filter operators recognised in the `key:op:value` form. Only when
+ * segment 2 of a `--filter` matches one of these is it treated as an operator;
+ * otherwise the remainder is kept verbatim as the value (so a value containing
+ * a colon — e.g. a URL — parses as key:value, not key:op:value).
+ *
+ * `!=` is accepted as an alias of `<>`; it is normalised to `<>` before the
+ * request is built (Drupal's allowed-operators list has `<>`, not `!=`).
+ */
+const KNOWN_OPERATORS = new Set([
+    "=",
+    "<>",
+    "!=",
+    ">",
+    ">=",
+    "<",
+    "<=",
+    "CONTAINS",
+    "STARTS_WITH",
+    "ENDS_WITH",
+    "IN",
+    "NOT IN",
+    "BETWEEN",
+    "NOT BETWEEN",
+    "IS NULL",
+    "IS NOT NULL",
+]);
+/** Operators that take no value; expressed as `key:IS NULL` / `key:IS NOT NULL`. */
+const VALUELESS_OPERATORS = new Set(["IS NULL", "IS NOT NULL"]);
+/**
+ * Operators whose value is a list; the `--filter` value is split on commas into
+ * an array (e.g. `key:IN:a,b,c`). Drupal rejects a scalar for these.
+ */
+const MULTI_VALUE_OPERATORS = new Set(["IN", "NOT IN", "BETWEEN", "NOT BETWEEN"]);
 export function parseFilterFlag(raw) {
     const parts = raw.split(":");
-    if (parts.length === 2) {
-        const [key, value] = parts;
-        return { key, value };
+    if (parts.length < 2) {
+        throw new ValidationError(`--filter must be key:value or key:op:value, got "${raw}"`);
     }
-    if (parts.length >= 3) {
-        const key = parts[0];
-        const operator = parts[1];
-        const value = parts.slice(2).join(":");
-        return { key, operator, value };
+    const key = parts[0];
+    const rest = parts.slice(1).join(":");
+    // key:IS NULL / key:IS NOT NULL — value-less operator.
+    if (VALUELESS_OPERATORS.has(rest)) {
+        return { key, operator: rest, value: null };
     }
-    throw new ValidationError(`--filter must be key:value or key:op:value, got "${raw}"`);
+    // key:op:value — only when segment 2 is a known operator.
+    if (parts.length >= 3 && KNOWN_OPERATORS.has(parts[1])) {
+        return { key, operator: parts[1], value: parts.slice(2).join(":") };
+    }
+    // key:value — value kept verbatim (may contain colons, e.g. a URL).
+    return { key, value: rest };
 }
 export async function runSearch(args, deps) {
     const params = new DrupalJsonApiParams();
     for (const raw of args.filters) {
         const f = parseFilterFlag(raw);
-        if (f.operator)
-            params.addFilter(f.key, f.value, f.operator);
-        else
+        if (f.operator === undefined) {
             params.addFilter(f.key, f.value);
+            continue;
+        }
+        // `!=` is an alias of `<>`; Drupal's allowed operators do not include `!=`.
+        const operator = f.operator === "!=" ? "<>" : f.operator;
+        // List operators (IN/NOT IN/BETWEEN/NOT BETWEEN) take an array value.
+        const value = f.value !== null && MULTI_VALUE_OPERATORS.has(operator) ? f.value.split(",") : f.value;
+        params.addFilter(f.key, value, operator);
     }
     params.addPageLimit(args.limit);
+    if (args.offset !== undefined) {
+        if (!Number.isInteger(args.offset) || args.offset < 0) {
+            throw new ValidationError(`--offset must be a non-negative integer, got "${args.offset}"`);
+        }
+        params.addPageOffset(args.offset);
+    }
+    if (args.sort) {
+        const descending = args.sort.startsWith("-");
+        const field = descending ? args.sort.slice(1) : args.sort;
+        if (field === "") {
+            throw new ValidationError(`--sort requires a field name, got "${args.sort}"`);
+        }
+        params.addSort(field, descending ? "DESC" : "ASC");
+    }
     if (args.include?.length)
         params.addInclude(args.include);
     const path = args.bundle ? `${args.entityType}/${args.bundle}` : args.entityType;

package/dist/src/commands/update.d.ts

@@ -0,0 +1,13 @@
+import type { JsonApiClient } from "../core/jsonapi/client.js";
+export interface UpdateArgs {
+    target: string;
+    dataArg: string;
+    dryRun?: boolean;
+    noValidate?: boolean;
+}
+export interface UpdateDeps {
+    client: JsonApiClient;
+    emit: (v: unknown) => void | Promise<void>;
+    validate?: (payload: unknown, target: string) => void | Promise<void>;
+}
+export declare function runUpdate(args: UpdateArgs, deps: UpdateDeps): Promise<void>;

package/dist/src/commands/upload-file.d.ts

@@ -0,0 +1,11 @@
+import type { JsonApiClient } from "../core/jsonapi/client.js";
+export interface UploadArgs {
+    target: string;
+    file: string;
+    dryRun?: boolean;
+}
+export interface UploadDeps {
+    client: JsonApiClient;
+    emit: (v: unknown) => void;
+}
+export declare function runUploadFile(args: UploadArgs, deps: UploadDeps): Promise<void>;

package/dist/src/core/auth/basic.d.ts

@@ -0,0 +1,8 @@
+import type { DropSHPlugin } from "../plugin.js";
+import type { AuthProvider } from "./types.js";
+export interface BasicAuthConfig {
+    /** Optional pre-seeded username; password is always prompted at login. */
+    username?: string;
+}
+export declare function basicAuthProvider(config?: BasicAuthConfig): AuthProvider;
+export declare function basicAuthPlugin(config?: BasicAuthConfig): DropSHPlugin;

package/dist/src/core/auth/registry.d.ts

@@ -0,0 +1,16 @@
+import type { DropSHPlugin } from "../plugin.js";
+import type { AuthProvider } from "./types.js";
+export declare function collectProviders(plugins: DropSHPlugin[]): AuthProvider[];
+/**
+ * The provider declaring `default: true`, used as the fallback profile when none
+ * is active or explicitly selected. Throws if more than one claims the default.
+ */
+export declare function defaultProvider(providers: AuthProvider[]): AuthProvider | undefined;
+export declare function loginCapableProviders(providers: AuthProvider[]): AuthProvider[];
+export declare function providerById(providers: AuthProvider[], id: string): AuthProvider | undefined;
+/**
+ * A session-less provider (e.g. static Basic) is the sole configured provider
+ * that declares no login capability: it carries credentials inline and needs no
+ * stored session. Used by both resolveAuth and authStatus.
+ */
+export declare function sessionlessProvider(providers: AuthProvider[]): AuthProvider | undefined;

package/dist/src/core/auth/session-store.d.ts

@@ -0,0 +1,42 @@
+import type { AuthSession } from "./types.js";
+/** One stored auth identity: the provider that owns it plus its opaque session. */
+export interface ProfileRecord {
+    provider: string;
+    session: AuthSession;
+}
+/** On-disk shape (v2): a host holds many named profiles + an active pointer. */
+export interface ProfilesFile {
+    version: 2;
+    /** Persistent default profile for this host; undefined until `auth use`/`login`. */
+    active?: string;
+    /** Keyed by profile name (== provider id in the current model). */
+    profiles: Record<string, ProfileRecord>;
+}
+/** Legacy (v1) shape kept for reading old files and for the compat wrappers below. */
+export interface SessionRecord {
+    activeProvider: string;
+    session: AuthSession;
+}
+export declare function defaultStateDir(): string;
+/**
+ * Read the whole profiles file, migrating a legacy `{ activeProvider, session }`
+ * record in memory to the v2 shape. No write-time migration is needed: the next
+ * `writeProfile` persists v2 naturally.
+ */
+export declare function readProfiles(baseUrl: string, dir?: string): Promise<ProfilesFile | null>;
+export declare function readProfile(baseUrl: string, name: string, dir?: string): Promise<ProfileRecord | null>;
+/**
+ * Upsert a single profile slot, merging into the existing file so other slots and
+ * the `active` pointer are preserved. Used both by `auth login` and by adapter
+ * token renewals (which must never disturb sibling profiles).
+ */
+export declare function writeProfile(baseUrl: string, name: string, provider: string, session: AuthSession, dir?: string): Promise<void>;
+/** Set the persistent active pointer. Errors if the slot has no stored session. */
+export declare function setActive(baseUrl: string, name: string, dir?: string): Promise<void>;
+/** Remove a single profile; unset `active` if it pointed there; delete the file if empty. */
+export declare function clearProfile(baseUrl: string, name: string, dir?: string): Promise<void>;
+/** Remove every profile for this host (deletes the file). */
+export declare function clearAll(baseUrl: string, dir?: string): Promise<void>;
+export declare function readSession(baseUrl: string, dir?: string): Promise<SessionRecord | null>;
+export declare function writeSession(baseUrl: string, activeProvider: string, session: AuthSession, dir?: string): Promise<void>;
+export declare function clearSession(baseUrl: string, dir?: string): Promise<void>;

package/dist/src/core/auth/types.d.ts

@@ -0,0 +1,57 @@
+import type { HttpClient, HttpRequest } from "../http.js";
+export interface AuthAdapter {
+    apply(req: HttpRequest): Promise<HttpRequest>;
+    /**
+     * Force a credential refresh after the server rejected the current token (401),
+     * then persist it. Returns true if renewal succeeded (caller retries the request
+     * once), false if it could not renew (caller surfaces the original 401).
+     * Providers that cannot renew (e.g. basic auth) omit this.
+     */
+    renew?(): Promise<boolean>;
+}
+/** Provider-specific opaque session payload persisted to the state dir. */
+export type AuthSession = Record<string, unknown>;
+export interface AuthStatusInfo {
+    loggedIn: boolean;
+    provider?: string;
+    host?: string;
+    expiresAt?: number;
+    state?: "valid" | "expired";
+    sessionless?: boolean;
+}
+/** I/O the core supplies to a provider during login/logout so providers stay testable. */
+export interface AuthContext {
+    baseUrl: string;
+    http: HttpClient;
+    /** State dir override (tests). Undefined → provider uses the default (~/.config/dropsh). */
+    stateDir?: string;
+    prompt(opts: {
+        label: string;
+        secret?: boolean;
+    }): Promise<string>;
+    openBrowser(url: string): Promise<void>;
+    stdout(s: string): void;
+    now(): number;
+}
+/** Runtime helpers handed to createAdapter so a provider can refresh + persist its session. */
+export interface AdapterRuntime {
+    http: HttpClient;
+    now(): number;
+    /** Persist a refreshed session back to the active session slot. */
+    save(session: AuthSession): Promise<void>;
+}
+export interface AuthProvider {
+    readonly id: string;
+    readonly displayName: string;
+    /** When true, this provider is the fallback profile if none is active/selected. */
+    readonly default?: boolean;
+    readonly capabilities: {
+        login: boolean;
+        logout: boolean;
+        status: boolean;
+    };
+    login(ctx: AuthContext): Promise<AuthSession>;
+    logout(ctx: AuthContext): Promise<void>;
+    status(session: AuthSession | null): Promise<AuthStatusInfo>;
+    createAdapter(session: AuthSession | undefined, rt: AdapterRuntime): AuthAdapter;
+}

package/dist/src/core/cache/file-store.d.ts

@@ -0,0 +1,9 @@
+export interface FileStore {
+    read<T>(relPath: string): Promise<T | undefined>;
+    write(relPath: string, value: unknown): Promise<void>;
+}
+export interface FileStoreOptions {
+    rootDir: string;
+    warn: (message: string) => void;
+}
+export declare function createFileStore(opts: FileStoreOptions): FileStore;

package/dist/src/core/cli/output.d.ts

@@ -0,0 +1,13 @@
+import { type AnyRenderer, type RenderContext, type RenderServices } from "./render.js";
+export interface Output {
+    emit(value: unknown, ctx?: RenderContext, services?: RenderServices): void | Promise<void>;
+    fail(err: unknown): void;
+    hasFormat(id: string): boolean;
+}
+export interface OutputOptions {
+    stdout: (s: string) => void;
+    stderr: (s: string) => void;
+    renderers?: AnyRenderer[];
+    getFormat?: () => string;
+}
+export declare function createOutput(opts: OutputOptions): Output;

package/dist/src/core/cli/prompt.d.ts

@@ -0,0 +1,17 @@
+import type { Readable } from "node:stream";
+export interface PromptDeps {
+    input?: Readable;
+    write?: (s: string) => void;
+    /** TTY check override (tests). Defaults to input.isTTY. */
+    isTTY?: boolean;
+}
+export type PromptFn = (opts: {
+    label: string;
+    secret?: boolean;
+}) => Promise<string>;
+/**
+ * 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 declare function createPrompt(deps?: PromptDeps): PromptFn;

package/dist/src/core/cli/render.d.ts

@@ -0,0 +1,25 @@
+import type { JsonApiClient } from "../jsonapi/client.js";
+import type { JsonApiDocument, JsonApiResource } from "../jsonapi/types.js";
+export declare function indexIncluded(doc: JsonApiDocument): Map<string, JsonApiResource>;
+export interface RenderContext {
+    command: "read" | "search" | "create" | "update";
+    target?: string;
+    entityType?: string;
+    bundle?: string;
+    viewMode?: string;
+}
+export interface RenderServices {
+    client: JsonApiClient;
+    baseUrl: string;
+}
+export interface Renderer {
+    readonly id: string;
+    render(doc: JsonApiDocument, ctx: RenderContext): string;
+}
+export interface InteractiveRenderer {
+    readonly id: string;
+    readonly interactive: true;
+    run(doc: JsonApiDocument, ctx: RenderContext, services?: RenderServices): Promise<void>;
+}
+export type AnyRenderer = Renderer | InteractiveRenderer;
+export declare function isInteractive(r: AnyRenderer): r is InteractiveRenderer;

package/dist/src/core/config.d.ts

@@ -0,0 +1,14 @@
+import type { DropSHPlugin } from "./plugin.js";
+export interface SiteConfig {
+    base_url: string;
+    jsonapi_prefix: string;
+}
+export interface Config {
+    site: SiteConfig;
+    defaults: {
+        dry_run: boolean;
+        timeout_ms: number;
+    };
+    plugins: DropSHPlugin[];
+}
+export declare function loadConfig(filePath: string): Promise<Config>;

package/dist/src/core/config.js

@@ -16,19 +16,18 @@ function isPluginDescriptor(e) {
     return isRecord(e) && typeof e.plugin === "string";
 }
 /**
- * Resolve a named plugin package the way ESLint resolves plugins: by string
- * name, relative to the config file first, then the cwd, then dropsh's own
- * install (so a plugin installed alongside dropsh — a dropsh dep, or globally
- * next to a global dropsh, or via `npx -p`— is found). The config never imports
- * the package itself.
+ * Resolve a single named-plugin descriptor to its module path + export the way
+ * ESLint resolves plugins: by string name against a list of base modules, first
+ * match wins (so a plugin installed alongside dropsh — a dropsh dep, or globally
+ * next to a global dropsh, or via `npx -p` — is found). The config never imports
+ * the package itself. This does **not** call the plugin factory: the resolved
+ * path + export + options form the identity the graph expander de-duplicates on,
+ * so construction is deferred to a cache miss (a shared/diamond dependency's
+ * factory must run exactly once — AC-3). Returns a `construct` thunk the caller
+ * invokes only when the resolved identity is new.
  */
-async function loadNamedPlugin(entry, configPath) {
+async function resolveDescriptor(entry, bases, declaredBy) {
     const name = entry.plugin;
-    const bases = [
-        pathToFileURL(configPath).href,
-        pathToFileURL(`${process.cwd()}/`).href,
-        import.meta.url,
-    ];
     let resolved;
     for (const base of bases) {
         try {
@@ -39,8 +38,10 @@ async function loadNamedPlugin(entry, configPath) {
             // try the next base
         }
     }
-    if (resolved === undefined)
-        throw new ConfigError(`cannot resolve plugin '${name}'. Install it next to dropsh (project dep, dropsh dep, global next to a global dropsh, or 'npx -p dropsh -p ${name}').`);
+    if (resolved === undefined) {
+        const from = declaredBy ? ` (declared by '${declaredBy}')` : "";
+        throw new ConfigError(`cannot resolve plugin '${name}'${from}. Install it next to dropsh (project dep, dropsh dep, global next to a global dropsh, or 'npx -p dropsh -p ${name}').`);
+    }
     let mod;
     try {
         mod = (await import(pathToFileURL(resolved).href));
@@ -52,19 +53,89 @@ async function loadNamedPlugin(entry, configPath) {
     const factory = mod[exportName];
     if (typeof factory !== "function")
         throw new ConfigError(`plugin '${name}' has no callable export '${exportName}'`);
-    return factory(entry.with ?? entry.options);
+    const construct = () => factory(entry.with ?? entry.options);
+    return { resolvedPath: resolved, exportName, construct };
 }
 /**
- * Expands `plugins[]` entries: named-package descriptors are resolved + built
- * into real plugins; already-constructed plugins pass through unchanged
- * (backward compat).
+ * Expands `plugins[]` into a flat plugin list: named-package descriptors are
+ * resolved + built, and each built plugin's `dependencies` are expanded
+ * *before* it (post-order DFS). A descriptor's identity is its resolved module
+ * path + export + options (`with`/`options`) — that single key drives both
+ * de-duplication and on-path cycle detection, and construction happens only on a
+ * cache miss, so a shared dependency's factory runs exactly once (AC-3). Because
+ * the key is the *resolved* module, one relative string naming different files
+ * on a path is not a cycle, and two same-package entries with different options
+ * are two distinct plugins. `id` collisions are still de-duplicated in the final
+ * list. A dependency cycle is rejected with the offending chain of descriptor
+ * names. Pre-constructed plugin objects pass through unchanged (backward compat).
  */
 async function resolvePlugins(raw, configPath) {
     if (!Array.isArray(raw))
         return [];
-    return Promise.all(raw.map((entry) => isPluginDescriptor(entry)
-        ? loadNamedPlugin(entry, configPath)
-        : Promise.resolve(entry)));
+    const baseBases = [
+        pathToFileURL(configPath).href,
+        pathToFileURL(`${process.cwd()}/`).href,
+        import.meta.url,
+    ];
+    const out = [];
+    const doneKeys = new Set(); // resolvedPath::export::options — fully expanded
+    const doneIds = new Set(); // plugin.id already emitted
+    // Descriptors on the current DFS path, keyed by resolved identity; `name` is
+    // the descriptor string, kept only to render the cycle-error chain.
+    const stack = [];
+    const emit = (plugin) => {
+        if (doneIds.has(plugin.id))
+            return;
+        doneIds.add(plugin.id);
+        out.push(plugin);
+    };
+    const expandDeps = async (plugin, bases) => {
+        for (const dep of plugin.dependencies ?? [])
+            await expand(dep, bases, plugin.id);
+    };
+    // Expand a pre-constructed plugin (or a nested array of them): a composite —
+    // e.g. `composePlugins(a(), b())` — reaches here as an array, and is flattened
+    // into separate entries so N children register without hand-merging hooks.
+    const expandValue = async (value, bases) => {
+        if (Array.isArray(value)) {
+            for (const sub of value)
+                await expand(sub, bases, undefined);
+            return;
+        }
+        const plugin = value;
+        await expandDeps(plugin, bases);
+        emit(plugin);
+    };
+    async function expand(entry, bases, declaredBy) {
+        if (!isPluginDescriptor(entry)) {
+            // Pre-constructed plugin object, or a nested-array composite entry.
+            await expandValue(entry, bases);
+            return;
+        }
+        const { resolvedPath, exportName, construct } = await resolveDescriptor(entry, bases, declaredBy);
+        const key = `${resolvedPath}::${exportName}::${JSON.stringify(entry.with ?? entry.options ?? null)}`;
+        if (doneKeys.has(key))
+            return; // same resolved identity already expanded + emitted — do not re-construct
+        if (stack.some((f) => f.key === key))
+            throw new ConfigError(`plugin dependency cycle: ${[...stack.map((f) => f.name), entry.plugin].join(" → ")}`);
+        // A factory may return one plugin or an array of them (composePlugins); a
+        // returned array is flattened into separate entries under this descriptor's
+        // identity (one construction, so a shared descriptor still runs once).
+        const produced = construct();
+        stack.push({ key, name: entry.plugin });
+        try {
+            // Child descriptors resolve relative to this plugin's module first.
+            const childBases = [pathToFileURL(resolvedPath).href, ...baseBases];
+            await expandValue(produced, childBases);
+        }
+        finally {
+            stack.pop();
+        }
+        doneKeys.add(key);
+    }
+    for (const entry of raw)
+        await expand(entry, baseBases, undefined);
+    return out;
 }
 export async function loadConfig(filePath) {
     const configPath = resolve(filePath);

package/dist/src/core/http.d.ts

@@ -0,0 +1,21 @@
+export interface HttpRequest {
+    method: "GET" | "POST" | "PATCH" | "DELETE";
+    url: string;
+    headers?: Record<string, string>;
+    body?: string | Uint8Array;
+}
+export interface HttpResponse {
+    status: number;
+    headers: Record<string, string>;
+    body: string;
+}
+export interface HttpClient {
+    send(req: HttpRequest): Promise<HttpResponse>;
+}
+export interface HttpOptions {
+    fetch?: typeof fetch;
+    timeoutMs?: number;
+    maxRetries?: number;
+    retryDelayMs?: number;
+}
+export declare function createHttpClient(opts?: HttpOptions): HttpClient;

package/dist/src/core/jsonapi/client.d.ts

@@ -0,0 +1,39 @@
+import type { DrupalJsonApiParams } from "drupal-jsonapi-params";
+import type { AuthAdapter } from "../auth/types.js";
+import type { HttpClient } from "../http.js";
+import { type Collection } from "./collection.js";
+import { type Resource } from "./resource.js";
+/** Attributes/relationships payload accepted by create/update/upsert. */
+export interface ResourceWriteBody {
+    attributes?: Record<string, unknown>;
+    relationships?: Record<string, unknown>;
+}
+export interface JsonApiClient {
+    get(path: string, params?: DrupalJsonApiParams): Promise<unknown>;
+    post(path: string, body: unknown): Promise<unknown>;
+    patch(path: string, body: unknown): Promise<unknown>;
+    delete(path: string): Promise<unknown>;
+    upload(path: string, filename: string, data: Uint8Array | Buffer): Promise<unknown>;
+    /** Start a fluent query for the given resource type. */
+    collection(type: string): Collection;
+    /** Fetch a single resource by id. */
+    resource(type: string, id: string): Promise<Resource>;
+    /** Create a resource (POST `{ data: { type, ...body } }`). */
+    create(type: string, body: ResourceWriteBody): Promise<Resource>;
+    /** Update a resource (PATCH `{ data: { type, id, ...body } }`). */
+    update(type: string, id: string, body: ResourceWriteBody): Promise<Resource>;
+    /** Update the resource matching `match`, or create one if none exists. */
+    upsert(type: string, match: {
+        path: string;
+        value: string;
+    }, body: ResourceWriteBody): Promise<Resource>;
+    /** Resolve the current authenticated user's uuid from the root document. */
+    me(): Promise<string>;
+}
+export interface JsonApiOptions {
+    baseUrl: string;
+    prefix: string;
+    http: HttpClient;
+    auth: AuthAdapter;
+}
+export declare function createJsonApiClient(opts: JsonApiOptions): JsonApiClient;

package/dist/src/core/jsonapi/collection.d.ts

@@ -0,0 +1,31 @@
+import { DrupalJsonApiParams } from "drupal-jsonapi-params";
+import { type Resource } from "./resource.js";
+export type FilterOp = "=" | "<>" | ">" | ">=" | "<" | "<=" | "STARTS_WITH" | "CONTAINS";
+export interface Collection {
+    where(path: string, op: FilterOp, value: string | number): Collection;
+    /** Match any of the given values (JSON:API `IN` operator). */
+    whereIn(path: string, values: Array<string | number>): Collection;
+    /** Require the field to be empty (JSON:API `IS NULL` operator). */
+    notExists(path: string): Collection;
+    /** Restrict the sparse fieldset for this collection's resource type. */
+    fields(names: string[]): Collection;
+    sort(path: string, dir?: "ASC" | "DESC"): Collection;
+    page(limit: number): Collection;
+    list(): Promise<Resource[]>;
+    /** First match, or `null`. Applies `page(1)` to keep the request minimal. */
+    first(): Promise<Resource | null>;
+    /**
+     * Number of matching resources.
+     *
+     * CAVEAT: this counts the rows returned by a single `list()` request and is
+     * therefore bounded by the active page limit (default JSON:API page size is
+     * 50). It does not read JSON:API `meta.count` and will under-report when the
+     * result set exceeds the page limit. Use it only for small/known-bounded sets.
+     */
+    count(): Promise<number>;
+}
+/** Minimal client surface a {@link Collection} needs — keeps it decoupled. */
+export interface CollectionClient {
+    get(path: string, params?: DrupalJsonApiParams): Promise<unknown>;
+}
+export declare function createCollection(client: CollectionClient, spec: string, params?: DrupalJsonApiParams): Collection;

package/dist/src/core/jsonapi/resource.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Ergonomic accessors over a raw JSON:API resource object.
+ *
+ * A {@link Resource} wraps the `data` member of a JSON:API document and exposes
+ * typed helpers for attributes and relationships so callers stop digging through
+ * nested `attributes`/`relationships` structures by hand.
+ */
+export interface JsonApiResourceIdentifier {
+    id: string;
+    type: string;
+}
+export interface JsonApiResourceObject {
+    id: string;
+    type: string;
+    attributes?: Record<string, unknown>;
+    relationships?: Record<string, {
+        data: JsonApiResourceIdentifier | JsonApiResourceIdentifier[] | null;
+    }>;
+}
+export interface Resource {
+    readonly id: string;
+    readonly type: string;
+    /** Read a single attribute, typed by the caller. Returns `undefined` if absent. */
+    attr<T = unknown>(key: string): T | undefined;
+    /** Related id for a to-one relationship, or `null` if missing/empty. */
+    rel(key: string): string | null;
+    /** Related ids for a to-many relationship. Returns `[]` if missing/empty. */
+    rels(key: string): string[];
+    /** The underlying raw JSON:API resource object. */
+    readonly raw: JsonApiResourceObject;
+}
+export declare function toResource(obj: JsonApiResourceObject): Resource;

package/dist/src/core/jsonapi/types.d.ts

@@ -0,0 +1,40 @@
+/**
+ * JSON:API resource type/path normalization.
+ *
+ * Drupal JSON:API addresses resources by a `entity/bundle` path (e.g.
+ * `node/article`) but identifies them in document envelopes by a `entity--bundle`
+ * type (e.g. `node--article`). This helper accepts either form plus a convenient
+ * single-segment shorthand and produces both representations.
+ */
+export interface ResolvedType {
+    /** URL path segment, e.g. `node/article`. */
+    path: string;
+    /** JSON:API resource type, e.g. `node--article`. */
+    type: string;
+}
+/**
+ * Resolve a loose type specifier into its `{ path, type }` pair.
+ *
+ * Accepted forms:
+ * - `'gaia_run'`        -> `{ path: 'gaia_run/gaia_run', type: 'gaia_run--gaia_run' }`
+ * - `'entity/bundle'`   -> `{ path: 'entity/bundle',     type: 'entity--bundle'      }`
+ * - `'entity--bundle'`  -> `{ path: 'entity/bundle',     type: 'entity--bundle'      }`
+ */
+export declare function resolveType(spec: string): ResolvedType;
+/**
+ * JSON:API document envelope shapes used by the render layer. The ergonomic
+ * client returns `unknown`; renderers narrow to these via a runtime guard.
+ */
+export interface JsonApiResource {
+    type: string;
+    id: string;
+    attributes?: Record<string, unknown>;
+    relationships?: Record<string, unknown>;
+    links?: Record<string, unknown>;
+}
+export interface JsonApiDocument {
+    data: JsonApiResource | JsonApiResource[];
+    included?: JsonApiResource[];
+    meta?: Record<string, unknown>;
+    links?: Record<string, unknown>;
+}

package/dist/src/core/plugin.d.ts

@@ -0,0 +1,65 @@
+import type { Command } from "commander";
+import type { AuthAdapter, AuthProvider } from "./auth/types.js";
+import type { AnyRenderer } from "./cli/render.js";
+import type { HttpClient } from "./http.js";
+import type { Operation } from "./schema/to-jsonschema.js";
+export interface PluginContext {
+    http: HttpClient;
+    auth: AuthAdapter;
+    baseUrl: string;
+    /**
+     * JSON:API path prefix (e.g. "/jsonapi"). Present when the schema pipeline
+     * builds the context; plugins that target routes under the JSON:API prefix
+     * should fall back to "/jsonapi" when it is absent.
+     */
+    jsonapiPrefix?: string;
+    /**
+     * Emit a user-visible warning (goes to stderr). Plugins use this to surface
+     * a broken/unreachable authoritative-schema endpoint instead of silently
+     * falling back to the heuristic schema.
+     */
+    warn?: (message: string) => void;
+}
+export type SchemaOperation = Operation;
+/**
+ * Import-free descriptor naming a plugin package as a string. Same shape used
+ * by the top-level `plugins[]` config; a plugin returns these in `dependencies`
+ * to have dropsh auto-load further plugins.
+ */
+export interface PluginDescriptor {
+    plugin: string;
+    with?: unknown;
+    options?: unknown;
+    export?: string;
+}
+export interface DropSHPlugin {
+    readonly id: string;
+    readonly requiredModules: string[];
+    /**
+     * Plugins this plugin depends on. dropsh resolves each descriptor and inserts
+     * the resulting plugin into the flat plugin list *before* this plugin, so a
+     * dependency's renderers / schema hooks are available when this plugin runs.
+     * De-duplicated across the whole graph; cycles are rejected at config load.
+     */
+    dependencies?: PluginDescriptor[];
+    /** Provider-based auth (login/logout/status/createAdapter). */
+    authProvider?: AuthProvider;
+    /**
+     * Optional schema extension. Plugins that contribute other capabilities
+     * (auth, commands, or consumer-defined slots) can omit it.
+     */
+    extendSchema?(entityType: string, bundle: string, baseSchema: unknown, ctx: PluginContext): Promise<unknown>;
+    extendOperationSchema?(entityType: string, bundle: string, operation: SchemaOperation, operationSchema: unknown, ctx: PluginContext): Promise<unknown>;
+    registerCommands?(program: Command): void;
+    renderers?: AnyRenderer[];
+}
+/**
+ * Combine several child plugins into one flat plugin list. An aggregator's
+ * factory returns `composePlugins(childA(), childB(), …)` and places the result
+ * as a single `plugins[]` entry (a nested array) or a single named-descriptor
+ * export; dropsh flattens it into separate plugin entries. This lets one config
+ * entry pull in N plugins without hand-merging their hooks or presence-guarding
+ * hook presence — each child stays a distinct entry, indistinguishable from N
+ * separate entries. Nested arrays (composed composites) are flattened one level.
+ */
+export declare function composePlugins(...children: (DropSHPlugin | DropSHPlugin[])[]): DropSHPlugin[];

package/dist/src/core/plugin.js

@@ -1 +1,12 @@
-export {};
+/**
+ * Combine several child plugins into one flat plugin list. An aggregator's
+ * factory returns `composePlugins(childA(), childB(), …)` and places the result
+ * as a single `plugins[]` entry (a nested array) or a single named-descriptor
+ * export; dropsh flattens it into separate plugin entries. This lets one config
+ * entry pull in N plugins without hand-merging their hooks or presence-guarding
+ * hook presence — each child stays a distinct entry, indistinguishable from N
+ * separate entries. Nested arrays (composed composites) are flattened one level.
+ */
+export function composePlugins(...children) {
+    return children.flat();
+}

package/dist/src/core/schema/catalog.d.ts

@@ -0,0 +1,14 @@
+import type { AuthAdapter } from "../auth/types.js";
+import type { HttpClient } from "../http.js";
+export interface CatalogEntry {
+    entity_type: string;
+    bundle: string;
+    label: string;
+}
+export interface CatalogDeps {
+    http: HttpClient;
+    auth: AuthAdapter;
+    baseUrl: string;
+    jsonapiPrefix: string;
+}
+export declare function fetchCatalog(deps: CatalogDeps): Promise<CatalogEntry[]>;

package/dist/src/core/schema/jsonschema-source.d.ts

@@ -0,0 +1,23 @@
+import type { AuthAdapter } from "../auth/types.js";
+import type { HttpClient } from "../http.js";
+import type { DropSHPlugin } from "../plugin.js";
+export type SchemaSource = "heuristic" | "heuristic-empty" | (string & {});
+export interface JsonSchemaResult {
+    schema: unknown;
+    source: SchemaSource;
+    target: {
+        entity_type: string;
+        bundle: string;
+    };
+}
+export interface JsonSchemaDeps {
+    http: HttpClient;
+    auth: AuthAdapter;
+    baseUrl: string;
+    jsonapiPrefix: string;
+    entity: string;
+    bundle: string;
+    warn: (message: string) => void;
+    plugins?: DropSHPlugin[];
+}
+export declare function fetchJsonSchema(deps: JsonSchemaDeps): Promise<JsonSchemaResult>;

package/dist/src/core/schema/sources/heuristic.d.ts

@@ -0,0 +1,15 @@
+import type { AuthAdapter } from "../../auth/types.js";
+import type { HttpClient } from "../../http.js";
+export interface HeuristicDeps {
+    http: HttpClient;
+    auth: AuthAdapter;
+    baseUrl: string;
+    jsonapiPrefix: string;
+    entity: string;
+    bundle: string;
+}
+export interface HeuristicResult {
+    schema: unknown;
+    empty: boolean;
+}
+export declare function fetchHeuristic(deps: HeuristicDeps): Promise<HeuristicResult>;

package/dist/src/core/schema/sources/heuristic.js

@@ -19,8 +19,11 @@ function mergeTypes(types) {
     const arr = [...types].filter((t) => t !== undefined);
     if (arr.length === 0)
         return {};
+    // A field that is `null` in every sample carries no type information — leave
+    // it permissive rather than locking it to `type: null` (which would reject any
+    // real value written later).
     if (arr.length === 1)
-        return { type: arr[0] };
+        return arr[0] === "null" ? {} : { type: arr[0] };
     return { type: arr };
 }
 export async function fetchHeuristic(deps) {

package/dist/src/core/schema/to-jsonschema.d.ts

@@ -0,0 +1,2 @@
+export type Operation = "create" | "update";
+export declare function toOperationVariant(schema: unknown, op: Operation): unknown;

package/dist/src/core/schema/validate.d.ts

@@ -0,0 +1 @@
+export declare function validatePayload(schema: unknown, payload: unknown, target: string): void;

package/dist/src/errors.d.ts

@@ -0,0 +1,20 @@
+export declare class CliError extends Error {
+    readonly code: string;
+    readonly details: Record<string, unknown>;
+    constructor(code: string, message: string, details?: Record<string, unknown>);
+}
+export declare class ConfigError extends CliError {
+    constructor(message: string, details?: Record<string, unknown>);
+}
+export declare class AuthError extends CliError {
+    constructor(message: string, details?: Record<string, unknown>);
+}
+export declare class ValidationError extends CliError {
+    constructor(message: string, details?: Record<string, unknown>);
+}
+export declare class HttpError extends CliError {
+    readonly status: number;
+    readonly body: unknown;
+    constructor(status: number, message: string, body?: unknown);
+}
+export declare function exitCodeFor(err: unknown): number;

package/dist/src/index.d.ts

@@ -0,0 +1,42 @@
+#!/usr/bin/env node
+import { Command } from "commander";
+import type { AuthAdapter, AuthStatusInfo } from "./core/auth/types.js";
+import type { HttpClient } from "./core/http.js";
+import { type JsonApiClient } from "./core/jsonapi/client.js";
+import type { DropSHPlugin } from "./core/plugin.js";
+export interface CommandContext {
+    client: JsonApiClient;
+    http: HttpClient;
+    auth: AuthAdapter;
+    baseUrl: string;
+    jsonapiPrefix: string;
+    cwd: string;
+    plugins: DropSHPlugin[];
+}
+export interface ProgramOptions {
+    contextFactory?: () => Promise<CommandContext>;
+    stdout?: (s: string) => void;
+    stderr?: (s: string) => void;
+    setExitCode?: (code: number) => void;
+    plugins?: DropSHPlugin[];
+}
+export declare function normalizeInclude(raw: string[] | undefined): string[];
+export interface ResolveAuthDeps {
+    baseUrl: string;
+    plugins: DropSHPlugin[];
+    http: HttpClient;
+    now: () => number;
+    stateDir?: string;
+    /** Explicit profile from --auth-profile / $DROPSH_AUTH_PROFILE (highest precedence). */
+    profile?: string;
+}
+export declare function resolveAuth(deps: ResolveAuthDeps): Promise<AuthAdapter>;
+export interface AuthStatusDeps {
+    baseUrl: string;
+    plugins: DropSHPlugin[];
+    stateDir?: string;
+    profile?: string;
+}
+export declare function authStatus(deps: AuthStatusDeps): Promise<AuthStatusInfo>;
+export declare function buildProgram(opts?: ProgramOptions): Command;
+export declare function main(): Promise<void>;

package/dist/src/index.js

@@ -283,13 +283,46 @@ export function buildProgram(opts = {}) {
         .description("Search entities with filters")
         .option("--bundle <bundle>")
         .option("--filter <kv...>", "filter in key:value or key:op:value form", [])
-        .option("--limit <n>", "max results", (v) => parseInt(v, 10), 50)
+        .option("--limit <n>", "max results per page", (v) => parseInt(v, 10), 50)
+        .option("--offset <n>", "skip the first n results (page[offset])", (v) => parseInt(v, 10))
+        .option("--sort <field>", "sort by field; prefix with - for descending")
         .option("--include <fields...>", "related fields to include (JSON:API include)")
+        .addHelpText("after", `
+Filter operators (--filter key:op:value):
+  =            equals (default when op is omitted: key:value)
+  <>, !=       not equals (!= is an alias of <>)
+  <, <=, >, >= comparisons
+  CONTAINS     substring match
+  STARTS_WITH  prefix match
+  ENDS_WITH    suffix match
+  IN, NOT IN   value is a comma-separated list  (--filter key:IN:a,b,c)
+  BETWEEN      value is a comma-separated low,high pair
+  NOT BETWEEN  (--filter age:BETWEEN:18,65)
+  IS NULL      field is empty      (value-less: --filter key:IS NULL)
+  IS NOT NULL  field is not empty  (value-less: --filter key:IS NOT NULL)
+
+An operator is recognised only when it is a known operator above; a value
+containing a colon (e.g. a URL) is kept intact, so key:value still works:
+  --filter link:https://example.com/x   ->  link = "https://example.com/x"
+
+Paging & sort:
+  --limit <n>    max results per page (default 50)
+  --offset <n>   skip the first n results
+  --sort <field> sort ascending; prefix - for descending (e.g. --sort -created)
+
+Example:
+  dropsh search gaia_ticket --bundle gaia_ticket \\
+    --filter title:CONTAINS:search --filter conductor_id:IS NOT NULL \\
+    --sort -created --limit 20 --offset 20`)
         .action((entityType, o) => {
         // biome-ignore lint/suspicious/noExplicitAny: optional bundle/include added conditionally
         const args = { entityType, filters: o.filter, limit: o.limit };
         if (o.bundle !== undefined)
             args.bundle = o.bundle;
+        if (o.offset !== undefined)
+            args.offset = o.offset;
+        if (o.sort !== undefined)
+            args.sort = o.sort;
         const include = normalizeInclude(o.include);
         if (include.length > 0)
             args.include = include;

package/dist/src/plugin-api.d.ts

@@ -0,0 +1,18 @@
+export type { BasicAuthConfig } from "./core/auth/basic.js";
+export { basicAuthPlugin, basicAuthProvider } from "./core/auth/basic.js";
+export type { AdapterRuntime, AuthAdapter, AuthContext, AuthProvider, AuthSession, AuthStatusInfo, } from "./core/auth/types.js";
+export type { AnyRenderer, InteractiveRenderer, RenderContext, Renderer, RenderServices, } from "./core/cli/render.js";
+export { indexIncluded, isInteractive } from "./core/cli/render.js";
+export type { Config, SiteConfig } from "./core/config.js";
+export { loadConfig } from "./core/config.js";
+export type { HttpClient, HttpRequest } from "./core/http.js";
+export { createHttpClient } from "./core/http.js";
+export type { JsonApiClient, JsonApiOptions, ResourceWriteBody, } from "./core/jsonapi/client.js";
+export { createJsonApiClient } from "./core/jsonapi/client.js";
+export type { Collection, FilterOp } from "./core/jsonapi/collection.js";
+export type { JsonApiResourceObject, Resource, } from "./core/jsonapi/resource.js";
+export type { JsonApiDocument, JsonApiResource } from "./core/jsonapi/types.js";
+export type { DropSHPlugin, PluginContext, PluginDescriptor, SchemaOperation, } from "./core/plugin.js";
+export { composePlugins } from "./core/plugin.js";
+export { AuthError, ConfigError, HttpError } from "./errors.js";
+export type { CommandContext } from "./index.js";

package/dist/src/plugin-api.js

@@ -3,4 +3,5 @@ export { indexIncluded, isInteractive } from "./core/cli/render.js";
 export { loadConfig } from "./core/config.js";
 export { createHttpClient } from "./core/http.js";
 export { createJsonApiClient } from "./core/jsonapi/client.js";
+export { composePlugins } from "./core/plugin.js";
 export { AuthError, ConfigError, HttpError } from "./errors.js";

package/package.json

@@ -1,14 +1,21 @@
 {
   "name": "dropsh",
-  "version": "0.5.3",
+  "version": "0.5.6",
   "description": "Entity-agnostic helper CLI for Drupal 11 JSON:API, used by the dropsh Claude skill for editorial publishing workflows.",
   "type": "module",
   "bin": {
     "dropsh": "./bin/dropsh"
   },
+  "types": "./dist/src/index.d.ts",
   "exports": {
-    ".": "./dist/src/index.js",
-    "./plugin": "./dist/src/plugin-api.js",
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "default": "./dist/src/index.js"
+    },
+    "./plugin": {
+      "types": "./dist/src/plugin-api.d.ts",
+      "default": "./dist/src/plugin-api.js"
+    },
     "./package.json": "./package.json"
   },
   "files": [