dropsh 0.0.1 → 0.0.2

package/README.md

@@ -6,24 +6,74 @@ This is the foundation CLI. Discovery, schema generation, and the skill layer ar
 
 ## 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`.
+
 ```bash
-npm install
-npm run build
+pnpm install
+pnpm run build
 ```
 
 ## Configure
 
-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.
+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.
+
+```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
+```
+
+`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>`.
+
+### Where secrets live
+
+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`:
 
-```yaml
-site:
-  base_url: https://my-drupal.example.com
-  auth:
-    type: basic
-    username: ${DRUPAL_USER}
-    password: ${DRUPAL_PASSWORD}
+```json
+{ "activeProvider": "oauth2_authcode", "session": { "access_token": "…", "expires_at": 1717459200000 } }
 ```
 
+Only non-secret connection parameters stay in the config:
+
+- **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.
+
 ## Commands
 
 All commands write JSON to stdout, structured errors to stderr, and use exit codes 0-5.
@@ -50,19 +100,240 @@ With a target (e.g. `node/article`), prints a JSON Schema document that validate
 
 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.
 
-Schemas are cached under `.dropsh/cache/` next to your `.dropsh.yml`. The `.dropsh/` directory is gitignored.
+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`:
+
+```js
+import { basicAuthPlugin } from "dropsh";
+import { canvasPlugin } from "@dropsh/plugin-canvas";
+
+export default {
+  site: { base_url: "https://my-drupal.example.com", jsonapi_prefix: "/jsonapi" },
+  plugins: [
+    basicAuthPlugin(),
+    canvasPlugin(),
+  ],
+};
+```
+
+Then ask for the Canvas schema:
+
+```bash
+dropsh schema canvas_page/canvas_page --for=create
+```
+
+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.
 
 ### Client-side validation in `create` / `update`
 
 `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.
 
+## Writing plugins
+
+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`:
+
+```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";
+```
+
+The `DropSHPlugin` shape:
+
+```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
+}
+```
+
+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.
+
+### A schema-extension plugin
+
+`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.
+
+```ts
+import type { DropSHPlugin, PluginContext, SchemaOperation } from "dropsh/plugin";
+
+// Marks node/article's `field_legacy_id` read-only and adds a provenance tag.
+export function articleRulesPlugin(): DropSHPlugin {
+  return {
+    id: "article-rules",
+    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] };
+    },
+  };
+}
+```
+
+Register it:
+
+```js
+import { articleRulesPlugin } from "./plugins/article-rules.js";
+export default {
+  site: { base_url: "https://my-drupal.example.com", jsonapi_prefix: "/jsonapi" },
+  plugins: [basicAuthPlugin(), articleRulesPlugin()],
+};
+```
+
+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 };
+    },
+
+    async logout(_ctx: AuthContext) {
+      // No server-side revoke; the core clears the local session file.
+    },
+
+    async status(session: AuthSession | null) {
+      return { loggedIn: session !== null, provider: "apikey" };
+    },
+
+    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.
+
 ## Development
 
 ```bash
-npm test            # Vitest unit suite
-npm run test:watch
-npm run typecheck
-npm run build
+pnpm test            # Vitest unit suite
+pnpm run test:watch
+pnpm run typecheck
+pnpm run build
 ```
 
 ### Integration tests
@@ -70,9 +341,21 @@ npm run build
 Local-only, requires DDEV. See `tests/integrations/README.md`.
 
 ```bash
-npm run drupal:up
-npm run test:integration
-npm run drupal:down
+pnpm run drupal:up
+pnpm run test:integration
+pnpm run drupal:down
+```
+
+## Publishing
+
+The CLI and all workspace packages are published together with a single command:
+
+```bash
+pnpm run release
 ```
 
-See `docs/superpowers/specs/2026-04-21-dropsh-design.md` for the full design.
+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`.

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,6 +4,40 @@ 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;
+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 });
@@ -32,9 +66,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 +83,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,22 +1,44 @@
 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",
+        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: [],
-        createAuthAdapter: () => adapter,
+        authProvider: basicAuthProvider(config),
         async extendSchema(_entityType, _bundle, schema, _ctx) {
             return schema;
         },

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/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, } 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,6 +88,32 @@ 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`,
@@ -77,8 +121,9 @@ export function buildProgram(opts = {}) {
         });
         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.0.2",
   "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 && 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",
+    "release": "pnpm publish --no-git-checks && pnpm -r publish --no-git-checks"
   }
-}
+}