vydanne 0.14.0 → 1.0.0-rc.1

package/README.md

@@ -440,6 +440,46 @@ don't have to learn them the hard way.
 
 <br>
 
+## Middleware — your own checks around any command
+
+A release has rules that belong to your app, not to vydanne: "never upload a bundle that has not opened on the lowest
+Android we support", "tell the channel when a build reaches testers", "refuse a Friday". `middleware` in the config is
+where that logic goes, so you do not wrap the CLI in a script that someone can bypass by calling vydanne directly.
+
+```js
+// vydanne.config.mjs
+export default {
+  // …
+  middleware: [
+    // an object limits an entry to the commands and stores it names
+    {
+      name: "release-gate",
+      commands: ["prerelease"],
+      stores: ["google"],
+      async run(ctx, next) {
+        if (ctx.apply && !hasReceipt(ctx.config.google.aab)) ctx.fail("this bundle has not passed the legacy-device check");
+        const result = await next();          // the command itself
+        if (ctx.apply && result?.ok) await tell("build is with testers");
+        return result;                         // returning nothing keeps the command's own result
+      },
+    },
+    // a bare function runs for every store command
+    async (ctx, next) => { ctx.log(`${ctx.command} on ${ctx.store}`); return next(); },
+  ],
+};
+```
+
+The first entry is outermost. Before `await next()` you may refuse: `ctx.fail(reason)` stops the command, prints
+`refused by middleware release-gate: …` and exits 1, before any client exists, so a refusal costs no Play or App Store
+Connect request. After it you see the result (`{ ok, planned }`). An entry that never calls `next()` skips the command and
+says so. `ctx` carries `command`, `store`, `apply`, `dryRun`, `writes`, `argv`, `cwd`, `env`, `version`, and the live
+`config`: a change made before `next()` (a different `google.track`, say) is what the command sees.
+
+It wraps every store command, from the CLI and from `runCommand`. It does not wrap `auth`, `locales`, `version` or help, which
+touch no store. A malformed entry is an error when the config loads. Middleware runs with the full power of the file it
+lives in, so it is not a sandbox. The same `middleware` key, with the same semantics, is in
+[zdymak](https://github.com/Lonli-Lokli/zdymak), so a check written for one reads the same in the other.
+
 ## What vydanne will never do
 
 - **It never submits for review, and never ships to the public.** It *will* put a build in front of

package/SKILL.md

@@ -397,6 +397,14 @@ It waits for the version to actually leave review before returning. Apple passes
 `CANCELING` first, and a command that returned there would send you straight into a `fill` that
 fails on a still-locked version.
 
+## `middleware` — the app's own logic around commands
+
+The config key `middleware` takes `(ctx, next)` functions or `{ name, commands, stores, run }` objects, first entry outermost.
+Before `await next()` an entry may refuse with `ctx.fail(reason)`; after it, it sees `{ ok, planned }`. It runs for every store
+command (CLI and `runCommand`), before any client exists, and not for `auth`/`locales`/`version`/help. Use it for a release
+gate or a notifier rather than a wrapper script, which a direct `vydanne prerelease --apply` bypasses. Full example: README,
+"Middleware". The same key exists in zdymak.
+
 ## `--apply` — writes are opt-in
 
 **Every store-mutating command is a DRY RUN without `--apply`**: `prepare` · `push` · `fill` ·

package/bin/vydanne.mjs

@@ -6,6 +6,7 @@ import { loadConfig } from "../src/config.mjs";
 import { Client } from "../src/client.mjs";
 import { COMMANDS, PLAY_COMMANDS } from "../src/registry.mjs";
 import { yellow } from "../src/util.mjs";
+import { runMiddleware } from "../src/middleware.mjs";
 
 const VERSION = JSON.parse(readFileSync(new URL("../package.json", import.meta.url))).version;
 
@@ -33,6 +34,12 @@ if (store !== "apple" && store !== "google") {
 // keep working unchanged; `--apply` is what the docs teach.
 const apply = argv.includes("--apply") || process.env.VYDANNE_COMMIT === "1";
 
+// USER MIDDLEWARE (config `middleware`) wraps every STORE command. Not `auth`, `locales`, `version` or help: those
+// touch no store, so there is nothing for a release gate or a notifier to guard.
+const through = (cfg, execute, extra = {}) => runMiddleware(cfg.middleware, {
+  tool: "vydanne", version: VERSION, command: cmd, store, apply, argv, config: cfg, cwd: process.cwd(), env: process.env, ...extra,
+}, execute);
+
 try {
   if (["version", "-v", "--version"].includes(cmd)) {
     console.log(`vydanne ${VERSION}`);
@@ -81,31 +88,37 @@ try {
     const { PlayClient } = await import("../src/play/client.mjs");
     const spec = PLAY_COMMANDS[cmd];
     const dryRun = Boolean(spec.writes) && !apply;
-    // Play needs no request-level gate: every mutation happens inside an Edit, and an Edit that is never
-    // committed changes nothing. So a dry run here VALIDATES for real against Google, then discards.
-    const client = await PlayClient.create({ keyPath: cfg.google.serviceAccountKey, packageName: cfg.google.packageName, dryRun });
-    if (dryRun) console.log(yellow(`DRY RUN — '${cmd} --store google' validates against Play and discards the edit. Add --apply to commit.`));
-    const { run } = await import(`../src/play/commands/${spec.mod}.mjs`);
-    const ok = await run(cfg, client);
-    if (ok === false) process.exit(1);
+    // Middleware runs BEFORE the client exists, so a refusal costs no authentication and no Play request.
+    const result = await through(cfg, async () => {
+      // Play needs no request-level gate: every mutation happens inside an Edit, and an Edit that is never
+      // committed changes nothing. So a dry run here VALIDATES for real against Google, then discards.
+      const client = await PlayClient.create({ keyPath: cfg.google.serviceAccountKey, packageName: cfg.google.packageName, dryRun });
+      if (dryRun) console.log(yellow(`DRY RUN — '${cmd} --store google' validates against Play and discards the edit. Add --apply to commit.`));
+      const { run } = await import(`../src/play/commands/${spec.mod}.mjs`);
+      return { ok: (await run(cfg, client)) !== false, planned: [] };
+    }, { dryRun, writes: Boolean(spec.writes) });
+    if (result?.ok === false) process.exit(1);
   } else if (COMMANDS[cmd]) {
     const cfg = await loadConfig(cfgPath);
     const spec = COMMANDS[cmd];
     const { run } = await import(`../src/commands/${spec.mod}.mjs`);
     const dryRun = Boolean(spec.writes) && !apply;
-    const client = spec.client ? new Client({ keyId: cfg.keyId, issuerId: cfg.issuerId, keyPath: cfg.keyPath, keyContent: cfg.keyContent, dryRun }) : null;
-    if (dryRun) console.log(yellow(`DRY RUN — '${cmd}' will not change App Store Connect. Add --apply to write.`));
-    // altool authenticates on its own rather than through our JWT, so it needs the raw ids.
-    const ok = await run(cfg, client, spec.credentials ? { keyId: cfg.keyId, issuerId: cfg.issuerId } : undefined);
-    // The count is the point: "nothing happened" is not the same as "nothing would happen", and only the
-    // second one means the local state already matches the store.
-    if (dryRun && client) {
-      const n = client.planned.length;
-      console.log(yellow(n
-        ? `DRY RUN — ${n} store write(s) withheld. Re-run with --apply to perform them.`
-        : "DRY RUN — nothing to write; the store already matches local."));
-    }
-    if (ok === false) process.exit(1);
+    const result = await through(cfg, async () => {
+      const client = spec.client ? new Client({ keyId: cfg.keyId, issuerId: cfg.issuerId, keyPath: cfg.keyPath, keyContent: cfg.keyContent, dryRun }) : null;
+      if (dryRun) console.log(yellow(`DRY RUN — '${cmd}' will not change App Store Connect. Add --apply to write.`));
+      // altool authenticates on its own rather than through our JWT, so it needs the raw ids.
+      const ok = await run(cfg, client, spec.credentials ? { keyId: cfg.keyId, issuerId: cfg.issuerId } : undefined);
+      // The count is the point: "nothing happened" is not the same as "nothing would happen", and only the
+      // second one means the local state already matches the store.
+      if (dryRun && client) {
+        const n = client.planned.length;
+        console.log(yellow(n
+          ? `DRY RUN — ${n} store write(s) withheld. Re-run with --apply to perform them.`
+          : "DRY RUN — nothing to write; the store already matches local."));
+      }
+      return { ok: ok !== false, planned: client?.planned ?? [] };
+    }, { dryRun, writes: Boolean(spec.writes) });
+    if (result?.ok === false) process.exit(1);
   } else {
     console.error(usage());
     process.exit(1);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vydanne",
-  "version": "0.14.0",
+  "version": "1.0.0-rc.1",
   "description": "App Store Connect + Google Play submission prep — the companion to zdymak (media). Native Node (no fastlane/Ruby/Python): localized listings, screenshot/preview/icon upload, ratings, review contact, accessibility & privacy labels, IAP, export docs, build upload to TestFlight / a Play closed track, a diff of local-vs-store, and a preflight verifier that encodes the store gotchas. Never submits for review. iOS/macOS via the ASC REST API; Android via the Play Developer Edits API (--store google).",
   "keywords": [
     "app-store-connect",
@@ -52,11 +52,13 @@
     "check:docs": "node scripts/check-docs.mjs",
     "check:types": "tsc --noEmit -p tsconfig.json && node scripts/check-types.mjs",
     "check:config": "node scripts/check-config.mjs",
-    "verify": "npm run check:docs && npm run check:types && npm run check:config",
+    "verify": "npm run check:docs && npm run check:types && npm run check:config && npm run check:middleware && npm run check:release",
     "prepublishOnly": "npm run verify",
     "release:patch": "node scripts/release.mjs patch",
     "release:minor": "node scripts/release.mjs minor",
-    "release:major": "node scripts/release.mjs major"
+    "release:major": "node scripts/release.mjs major",
+    "check:middleware": "node --test scripts/middleware.test.mjs",
+    "check:release": "node --test scripts/release-from-tag.test.mjs"
   },
   "dependencies": {
     "dotenv": "^17.4.2",

package/src/commands/prepare.mjs

@@ -54,10 +54,19 @@ async function versionsFor(client, platform) {
   return json.data || [];
 }
 
-/** The newest build, together with the marketing version its archive declares. */
-async function newestBuildWithVersion(client) {
+/**
+ * The newest build FOR THIS PLATFORM, together with the marketing version its archive declares.
+ *
+ * Filtered by platform, which it was not: an app shipping on iOS and the Mac App Store uploads a build
+ * to each, and the unfiltered query returned whichever went up last. Preparing MAC_OS then tried to
+ * attach an iOS build and Apple answered 409 — so the Mac version was left holding nothing, or an older
+ * build, purely because the iOS one was newer. The 409 made it visible; a same-platform mix-up would
+ * not have been.
+ */
+async function newestBuildWithVersion(client, platform) {
   const { json } = await client.get(
     `/v1/builds?filter[app]=${client.appId}&sort=-uploadedDate&limit=1` +
+      (platform ? `&filter[preReleaseVersion.platform]=${platform}` : "") +
       `&fields[builds]=version,processingState&include=preReleaseVersion` +
       `&fields[preReleaseVersions]=version`,
   );
@@ -218,7 +227,7 @@ export async function run(config, client) {
 async function prepareOne(config, client, platform) {
   console.log(green(`prepare → App Store version (${platform})`));
 
-  const { build, marketing } = await newestBuildWithVersion(client);
+  const { build, marketing } = await newestBuildWithVersion(client, platform);
   const target = process.env.VYDANNE_VERSION || marketing;
 
   if (!target) {

package/src/commands/withdraw.mjs

@@ -56,7 +56,12 @@ export async function run(config, client) {
     console.log("  no versions on this app");
     return true;
   }
-  const version = mine[0];
+  // Pick the version that is ACTUALLY in review, not merely the first one Apple returned. An app on two
+  // platforms has two 1.2 records, and `mine[0]` was whichever came back first: with iOS
+  // WAITING_FOR_REVIEW and macOS PREPARE_FOR_SUBMISSION, this reported "not submitted — nothing to
+  // withdraw" and exited 0, never looking at the submission it was asked to cancel. Silence is the worst
+  // possible answer here, because the operator walks away believing the withdrawal happened.
+  const version = mine.find((v) => WITHDRAWABLE[v.attributes.appStoreState]) || mine[0];
   const state = version.attributes.appStoreState;
   const label = `${version.attributes.versionString} (${state})`;
 

package/src/config.mjs

@@ -5,10 +5,11 @@ import { resolveLocales } from "./locales.mjs";
 import { resolveCredentials } from "./credentials.mjs";
 import { DEFAULT_SCREENSHOT_BASE } from "./screenshots.mjs";
 import { DEFAULT_PLAY_IMAGES } from "./play/images.mjs";
+import { normalizeMiddleware } from "./middleware.mjs";
 
 // The public config surface — the drift guards assert each key is documented (README/SKILL) and typed
 // (types/index.d.ts). Add a config knob → document + type it, or the guards fail before publish.
-export const CONFIG_KEYS = ["bundleId", "primaryLocale", "asc", "platforms", "uiLocales", "localeMap", "metadataDir", "screenshots", "rating", "ageRating", "categories", "contentRights", "privacy", "iaps", "previews", "export", "ios", "google", "accessibility", "bridge", "push", "reviewContact", "allowCrossStoreTerms", "buildNumberOffset"];
+export const CONFIG_KEYS = ["bundleId", "primaryLocale", "asc", "platforms", "uiLocales", "localeMap", "metadataDir", "screenshots", "rating", "ageRating", "categories", "contentRights", "privacy", "iaps", "previews", "export", "ios", "google", "accessibility", "bridge", "push", "reviewContact", "allowCrossStoreTerms", "buildNumberOffset", "middleware"];
 
 // One `vydanne.config.mjs` per app (ESM, like zdymak.config.mjs) — nothing hard-coded. Secrets stay out:
 // credentials resolve from the environment, a gitignored .env, or ~/.appstoreconnect/config.json (see
@@ -94,6 +95,9 @@ export async function loadConfig(p) {
     // tool cannot verify, so it is refused unless it is an integer and reported wherever it is
     // applied. 0 means the plain convention, which is every app that never had the accident.
     buildNumberOffset: integerOr("buildNumberOffset", raw.buildNumberOffset, 0),
+    // The consumer's own logic around every store command: `[(ctx, next) => …]` or `{ name, commands, stores, run }`.
+    // Validated HERE so a malformed entry fails at config load, not halfway through a release. See middleware.mjs.
+    middleware: normalizeMiddleware(raw.middleware, "vydanne"),
     // Terms the cross-store check must not flag for this app (see src/crossStore.mjs).
     allowCrossStoreTerms: raw.allowCrossStoreTerms || [],
     previews: raw.previews || null,

package/src/index.mjs

@@ -4,13 +4,16 @@
 // filenames that nothing outside the package could resolve, because `exports` maps only ".". So a
 // consumer could see that `fill` existed and had no way to run it. `runCommand` is that missing half:
 // the same dispatch bin/ performs, minus the argv parsing and the process.exit.
+import { readFileSync } from "node:fs";
 import { Client } from "./client.mjs";
 import { loadConfig } from "./config.mjs";
+import { runMiddleware } from "./middleware.mjs";
 import { COMMANDS, PLAY_COMMANDS } from "./registry.mjs";
 
 export { Client } from "./client.mjs";
 export { PlayClient } from "./play/client.mjs";
 export { loadConfig, CONFIG_KEYS } from "./config.mjs";
+export { MiddlewareRefusal, normalizeMiddleware, runMiddleware } from "./middleware.mjs";
 export { COMMANDS, PLAY_COMMANDS, COMMAND_NAMES } from "./registry.mjs";
 export { resolveLocales, toAsc, VALID, UI_TO_ASC } from "./locales.mjs";
 export { makeToken, resolveKey } from "./jwt.mjs";
@@ -34,6 +37,7 @@ export { DEFAULT_PLAY_IMAGES, PLAY_IMAGE_KIND, playImages } from "./play/images.
  * @param {string} [opts.configPath] path to vydanne.config.mjs, when loading from disk
  * @param {"apple"|"google"} [opts.store]
  * @param {boolean} [opts.apply]     perform store writes (default false — dry run)
+ * @param {string[]} [opts.argv]     the command-line arguments to show middleware (default: none)
  */
 export async function runCommand(name, opts = {}) {
   const { store = "apple", apply = false, configPath } = opts;
@@ -49,15 +53,27 @@ export async function runCommand(name, opts = {}) {
   if (store === "google") {
     if (!config.google) throw new Error("vydanne: no `google` block in config — add packageName + a service-account key");
     if (!config.google.serviceAccountKey) throw new Error("vydanne: set PLAY_JSON_KEY_FILE (or google.serviceAccountKey) to the Play service-account JSON");
-    const { PlayClient } = await import("./play/client.mjs");
-    const client = await PlayClient.create({ keyPath: config.google.serviceAccountKey, packageName: config.google.packageName, dryRun });
-    const { run } = await import(`./play/commands/${spec.mod}.mjs`);
-    return { ok: (await run(config, client)) !== false, planned: [] };
   }
 
-  const client = spec.client ? new Client({ keyId: config.keyId, issuerId: config.issuerId, keyPath: config.keyPath, keyContent: config.keyContent, dryRun }) : null;
-  const { run } = await import(`./commands/${spec.mod}.mjs`);
-  // altool authenticates on its own rather than through our JWT, so it needs the raw ids.
-  const ok = await run(config, client, spec.credentials ? { keyId: config.keyId, issuerId: config.issuerId } : undefined);
-  return { ok: ok !== false, planned: client?.planned ?? [] };
+  // The same `middleware` the CLI runs, with the same context, so a gate written for one holds for the other.
+  // `argv` is empty here: a library caller has no command line.
+  const ctx = {
+    tool: "vydanne", version: VERSION, command: name, store, apply, dryRun, writes: Boolean(spec.writes),
+    argv: opts.argv ?? [], config, cwd: process.cwd(), env: process.env,
+  };
+  return runMiddleware(config.middleware, ctx, async () => {
+    if (store === "google") {
+      const { PlayClient } = await import("./play/client.mjs");
+      const client = await PlayClient.create({ keyPath: config.google.serviceAccountKey, packageName: config.google.packageName, dryRun });
+      const { run } = await import(`./play/commands/${spec.mod}.mjs`);
+      return { ok: (await run(config, client)) !== false, planned: [] };
+    }
+    const client = spec.client ? new Client({ keyId: config.keyId, issuerId: config.issuerId, keyPath: config.keyPath, keyContent: config.keyContent, dryRun }) : null;
+    const { run } = await import(`./commands/${spec.mod}.mjs`);
+    // altool authenticates on its own rather than through our JWT, so it needs the raw ids.
+    const ok = await run(config, client, spec.credentials ? { keyId: config.keyId, issuerId: config.issuerId } : undefined);
+    return { ok: ok !== false, planned: client?.planned ?? [] };
+  });
 }
+
+const VERSION = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;

package/src/middleware.mjs

@@ -0,0 +1,125 @@
+/**
+ * Middleware: a consumer's own logic around every command.
+ *
+ * THIS FILE IS IDENTICAL IN vydanne AND zdymak. Both tools take the same `middleware` config key and give
+ * it the same semantics, so a check written for one reads the same in the other. Change both together.
+ *
+ *   // vydanne.config.mjs or zdymak.config.mjs
+ *   export default {
+ *     middleware: [
+ *       // a function: runs for every command
+ *       async (ctx, next) => {
+ *         console.log(`about to run ${ctx.command}`);
+ *         const result = await next();           // the rest of the chain, then the command itself
+ *         console.log('done');
+ *         return result;                          // return nothing and the command's own result is kept
+ *       },
+ *       // an object: the same function, limited to the commands (and stores) it names
+ *       {
+ *         name: 'release-gate',
+ *         commands: ['prerelease'],
+ *         stores: ['google'],                     // vydanne only
+ *         run(ctx, next) {
+ *           if (ctx.apply && !receiptFor(ctx)) ctx.fail('no receipt for this bundle');
+ *           return next();
+ *         },
+ *       },
+ *     ],
+ *   };
+ *
+ * Order is the array order: the first entry is the outermost. Code before `await next()` runs on the way in and
+ * may REFUSE (`ctx.fail(message)` stops the command and exits non-zero); code after it runs on the way out and
+ * sees the command's result. An entry that never calls `next()` skips the command, and says so. `ctx` carries
+ * what the tool knows (see each tool's docs); `ctx.config` is the live config, so a change made on the way in
+ * is seen by the command.
+ *
+ * What middleware is NOT: a plugin system for new commands, and not a sandbox. It runs with the full power of
+ * the config file it lives in, which is already arbitrary code.
+ */
+
+/** Thrown by `ctx.fail`. The CLIs print it as a refusal and exit 1, with no stack trace. */
+export class MiddlewareRefusal extends Error {
+  constructor(reason, middleware) {
+    super(`refused by middleware '${middleware}': ${reason}`);
+    this.name = 'MiddlewareRefusal';
+    this.middleware = middleware;
+    this.reason = reason;
+  }
+}
+
+function names(value, label, where) {
+  if (value == null) return null;
+  const list = Array.isArray(value) ? value : [value];
+  if (!list.every((x) => typeof x === 'string' && x)) {
+    throw new Error(`${where}: '${label}' must be a string or an array of strings`);
+  }
+  return list;
+}
+
+/**
+ * Validate the `middleware` config value and return `{ name, commands, stores, run }` entries.
+ * A bad entry is a config error at load time, never a surprise halfway through a release.
+ */
+export function normalizeMiddleware(list, tool = 'tool') {
+  if (list == null) return [];
+  if (!Array.isArray(list)) {
+    throw new Error(`${tool}: config 'middleware' must be an array of functions or { run } objects, got ${typeof list}`);
+  }
+  return list.map((entry, i) => {
+    const where = `${tool}: config 'middleware'[${i}]`;
+    const fallback = `middleware[${i}]`;
+    if (typeof entry === 'function') return { name: entry.name || fallback, commands: null, stores: null, run: entry };
+    if (entry && typeof entry === 'object' && typeof entry.run === 'function') {
+      return {
+        name: String(entry.name ?? (entry.run.name || fallback)),
+        commands: names(entry.commands, 'commands', where),
+        stores: names(entry.stores, 'stores', where),
+        run: entry.run,
+      };
+    }
+    throw new Error(`${where} must be a function (ctx, next) or an object with a run(ctx, next) function`);
+  });
+}
+
+/**
+ * Run `final` (the command) inside the middleware chain and return its result.
+ *
+ * `ctx` is the tool's context object; `log`, `warn` and `fail` are added to it here, so an entry can say
+ * `ctx.fail('...')` without importing anything.
+ */
+export async function runMiddleware(list, ctx, final) {
+  const chain = normalizeMiddleware(list, ctx.tool);
+  if (chain.length === 0) return final();
+
+  const current = { name: 'middleware' };
+  ctx.log = (...args) => console.log(`[${current.name}]`, ...args);
+  ctx.warn = (...args) => console.warn(`[${current.name}]`, ...args);
+  ctx.fail = (reason) => {
+    throw new MiddlewareRefusal(reason, current.name);
+  };
+
+  const dispatch = async (i) => {
+    if (i === chain.length) return final();
+    const mw = chain[i];
+    if (mw.commands && !mw.commands.includes(ctx.command)) return dispatch(i + 1);
+    if (mw.stores && ctx.store && !mw.stores.includes(ctx.store)) return dispatch(i + 1);
+
+    let called = false;
+    let inner;
+    const next = async () => {
+      if (called) throw new Error(`middleware '${mw.name}' called next() twice`);
+      called = true;
+      inner = await dispatch(i + 1);
+      current.name = mw.name; // control is back with this entry, so its messages carry its name again
+      return inner;
+    };
+
+    current.name = mw.name;
+    const result = await mw.run(ctx, next);
+    if (!called) console.log(`  (${ctx.command} skipped: middleware '${mw.name}' did not call next())`);
+    // An entry that only guards on the way in has nothing to return; the command's own result is kept.
+    return result === undefined ? inner : result;
+  };
+
+  return dispatch(0);
+}

package/types/index.d.ts

@@ -355,8 +355,62 @@ export interface VydanneConfig {
    * a wrong commit as confidently as a right one.
    */
   buildNumberOffset?: number;
+  /**
+   * The app's own logic around every store command, in the order given (the first is outermost). Each entry
+   * is a function `(ctx, next)` or an object `{ name, commands, stores, run }` that limits it. Code before
+   * `await next()` runs first and may refuse with `ctx.fail(reason)`; code after it sees the command's
+   * result. Not run for `auth`, `locales`, `version` or help. See the README, "Middleware".
+   */
+  middleware?: Middleware[];
+}
+
+/** What a middleware entry is handed. `config` is live: a change made before `next()` is seen by the command. */
+export interface MiddlewareContext {
+  tool: "vydanne";
+  version: string;
+  /** The command, e.g. `prerelease`. */
+  command: string;
+  store: Store;
+  /** `--apply` (or VYDANNE_COMMIT=1) was given: the command will write to the store. */
+  apply: boolean;
+  /** The command writes and `apply` is off, so it will only validate. */
+  dryRun: boolean;
+  /** The command is one that can write to a store at all. */
+  writes: boolean;
+  /** The command-line arguments after the command name; empty when run through `runCommand`. */
+  argv: string[];
+  config: ResolvedConfig;
+  cwd: string;
+  env: Record<string, string | undefined>;
+  log(...args: unknown[]): void;
+  warn(...args: unknown[]): void;
+  /** Refuse: stops the command, prints the reason and exits 1. */
+  fail(reason: string): never;
+}
+
+export type MiddlewareFunction = (ctx: MiddlewareContext, next: () => Promise<unknown>) => unknown;
+
+export interface MiddlewareObject {
+  /** Shown in messages; defaults to the function's own name. */
+  name?: string;
+  /** Run only for these commands. */
+  commands?: string | string[];
+  /** Run only for these stores. */
+  stores?: Store | Store[];
+  run: MiddlewareFunction;
+}
+
+export type Middleware = MiddlewareFunction | MiddlewareObject;
+
+/** Thrown by `ctx.fail`. The CLI prints it as a refusal and exits 1. */
+export declare class MiddlewareRefusal extends Error {
+  middleware: string;
+  reason: string;
 }
 
+export declare function normalizeMiddleware(list: unknown, tool?: string): Array<Required<Omit<MiddlewareObject, "commands" | "stores">> & { commands: string[] | null; stores: string[] | null }>;
+export declare function runMiddleware<T>(list: unknown, ctx: Record<string, unknown> & { tool: string; command: string }, final: () => Promise<T>): Promise<T>;
+
 /** Thin ASC REST client (native fetch + ES256 JWT). */
 export declare class Client {
   constructor(opts: { keyId: string; issuerId: string; keyPath?: string; keyContent?: string; dryRun?: boolean });
@@ -416,6 +470,8 @@ export declare function runCommand(
     configPath?: string;
     store?: Store;
     apply?: boolean;
+    /** Shown to middleware as `ctx.argv`. */
+    argv?: string[];
   },
 ): Promise<{ ok: boolean; planned: Array<{ method: string; path: string; attributes: Record<string, unknown> }> }>;