kizlo 0.17.0 → 0.19.0

package/dist/cli/daemon/watch.js

@@ -2,9 +2,9 @@ import { integrationEnv, resolveWordPressConnection } from "../../kizlo.js";
 import { node } from "../../integrations/node/integration.js";
 import { log } from "./logger.js";
 import { loadEnvFiles } from "../utils.js";
-import { resolveConfig, resolveWordPressClientDir } from "./config.js";
+import { resolveConfig } from "./config.js";
 import { IntrospectionFetchError } from "../../wordpress/fetch-introspection.js";
-import { generateOnce, generateWordPressOnce, generateWorkspaceClientOnce, reportGenerationError } from "./generate.js";
+import { generateIntrospectionOnce, generateOnce, reportGenerationError } from "./generate.js";
 import { acquire, lockPath, release } from "./lock.js";
 import path from "node:path";
 import { FSWatcher } from "chokidar";
@@ -19,51 +19,49 @@ function debounce(fn, delay) {
 }
 async function regenerate(cfg, credentials) {
 	try {
-		if (await generateOnce(cfg, { credentials })) log.success("Contract updated");
-		else log.warn(`No Kizlo server found in ${cfg.serverEntry}`);
+		const result = await generateOnce(cfg, { credentials });
+		if (result.contract === "built") log.success("Contract updated");
+		else if (result.contract === "empty" && cfg.server) log.warn(`No Kizlo server found in ${cfg.server.entry}`);
 	} catch (error) {
 		reportGenerationError("Failed to update the Kizlo contract:", error);
 	}
 }
-/** Watches the server directory and regenerates the contract on change. */
-async function watch(cfg, credentials) {
+/** Watches the server directory and regenerates the contract on change. Only called when a server is present. */
+async function watch(cfg, server, credentials) {
 	const watcher = new FSWatcher({
 		persistent: true,
 		ignoreInitial: true,
-		ignored: path.resolve(cfg.cwd, cfg.generatedDir)
+		ignored: path.resolve(cfg.cwd, server.contractDir)
 	});
 	const onChange = debounce(() => regenerate(cfg, credentials), 300);
-	watcher.add(path.resolve(cfg.cwd, cfg.serverDir));
+	watcher.add(path.resolve(cfg.cwd, server.dir));
 	watcher.on("all", () => void onChange());
 	return watcher;
 }
 /**
-* Report one generation's pass under its own name. The poll refreshes two, and one message for both sent
-* a client-only workspace looking for a WordPress service its project does not have.
-*
-* Each reporter carries the last failure it reported, because most of what can fail here cannot clear
-* without the user acting — WordPress down, credentials wrong, a document that will not parse, an
-* introspection version this package does not speak — and repeating the same line every few seconds says
-* nothing the first one did not. A failure that reads differently is a different answer and is reported.
-* The state is per reporter rather than per process, so restarting the watcher reports afresh, and one
-* generation failing never silences the other.
+* Report the introspection poll's pass. It carries the last failure it reported, because most of what
+* can fail here cannot clear without the user acting (WordPress down, credentials wrong, a document
+* that will not parse, an introspection version this package does not speak), and repeating the same
+* line every few seconds says nothing the first one did not. A failure that reads differently is a
+* different answer and is reported. The state is per reporter rather than per process, so restarting the
+* watcher reports afresh.
 */
-function reportGeneration(subject, stack) {
+function reportGeneration(stack) {
 	let reported;
 	return async (run) => {
 		try {
-			if (await run() === "generated") log.success(`WordPress ${subject} updated`);
+			if (await run() === "generated") log.success("WordPress introspection updated");
 			stack?.answered();
 			if (reported !== void 0) {
 				reported = void 0;
-				log.success(`Updating the WordPress ${subject} again`);
+				log.success("Updating the WordPress introspection again");
 			}
 		} catch (error) {
 			if (error instanceof IntrospectionFetchError && error.unreachable && await stack?.ended()) return;
 			const message = error instanceof Error ? error.message : String(error);
 			if (message === reported) return;
 			reported = message;
-			reportGenerationError(`Failed to update the WordPress ${subject}:`, error);
+			reportGenerationError("Failed to update the WordPress introspection:", error);
 		}
 	};
 }
@@ -96,26 +94,20 @@ function endOnStoppedStack(stack, now = Date.now) {
 	};
 }
 /**
-* One pass of the WordPress poll. `cfg` covers an app's client next to its contract; `wordpressClientDir`
-* covers a workspace that has only the client. A project has one or the other, but both are refreshed
-* together so the plugin's PHP changing is picked up either way. Each is refreshed independently, so a
-* service that cannot generate does not cost the pass its client.
-*
-* Both reporters share one stack guard, so a stopped stack ends the session once rather than once per
-* generation the pass refreshes.
+* One pass of the introspection poll: refetch and rewrite `introspection.ts` when WordPress has changed.
+* A server-backed app and a package that ships only procedures both take this same pass, since each has
+* exactly one introspection to keep current; the plugin's PHP changing is picked up either way. The
+* contract is not refreshed here; the file watcher rebuilds it on a server source change.
 */
-function createWordPressRefresh(cwd, cfg, wordpressClientDir, options, stack) {
-	const guard = stack ? endOnStoppedStack(stack) : void 0;
-	const service = reportGeneration("service", guard);
-	const client = reportGeneration("client", guard);
+function createWordPressRefresh(cfg, options, stack) {
+	const introspection = reportGeneration(stack ? endOnStoppedStack(stack) : void 0);
 	return async () => {
-		if (cfg) await service(() => generateWordPressOnce(cfg, options));
-		if (wordpressClientDir) await client(() => generateWorkspaceClientOnce(cwd, wordpressClientDir, options));
+		await introspection(() => generateIntrospectionOnce(cfg, options));
 	};
 }
 /** Run {@link createWordPressRefresh} on a timer, skipping a tick while the previous one is still going. */
-function refreshWordPress(cwd, cfg, wordpressClientDir, credentials, stack) {
-	const refresh = createWordPressRefresh(cwd, cfg, wordpressClientDir, { credentials }, stack);
+function refreshWordPress(cfg, credentials, stack) {
+	const refresh = createWordPressRefresh(cfg, { credentials }, stack);
 	let refreshing = false;
 	const timer = setInterval(() => {
 		if (refreshing) return;
@@ -128,12 +120,11 @@ function refreshWordPress(cwd, cfg, wordpressClientDir, credentials, stack) {
 	return timer;
 }
 /**
-* Acquire the single-instance lock, generate the contract once, and start the file
-* watcher. Returns a synchronous `stop()` that closes the watcher and releases the
-* lock — or `undefined` when another watcher already holds the lock (a framework dev
-* script, or a second `kizlo dev`), or when no server `dir` is configured, in which case
-* the caller carries on without watching. Used by `kizlo dev`, both when it boots a local
-* stack and when it runs the watcher alone, so a single terminal covers the whole dev loop.
+* Acquire the single-instance lock, generate once, and start the file watcher. Returns a synchronous
+* `stop()` that closes the watcher and releases the lock, or `undefined` when another watcher already
+* holds the lock (a framework dev script, or a second `kizlo dev`), or when nothing is configured to
+* generate, in which case the caller carries on without watching. Used by `kizlo dev`, both when it
+* boots a local stack and when it runs the watcher alone, so a single terminal covers the whole dev loop.
 */
 async function startWatcher(cwd, opts) {
 	const lock = lockPath(cwd);
@@ -144,26 +135,22 @@ async function startWatcher(cwd, opts) {
 	let handedOver = false;
 	try {
 		const cfg = await resolveConfig(cwd, { dir: opts?.dir });
-		const wordpressClientDir = await resolveWordPressClientDir(cwd);
-		if (!cfg && !wordpressClientDir) {
+		if (!cfg) {
 			log.info("skipping the contract generation.");
 			return;
 		}
 		loadEnvFiles(cwd);
 		const { credentials } = resolveWordPressConnection(void 0, integrationEnv([node()]));
-		if (wordpressClientDir) try {
-			if (await generateWorkspaceClientOnce(cwd, wordpressClientDir, { credentials }) === "generated") log.success("WordPress client generated");
-		} catch (error) {
-			reportGenerationError("Failed to generate the WordPress client:", error);
-		}
-		if (cfg) try {
-			if (await generateOnce(cfg, { credentials })) log.success("Contract generated");
-			else log.warn(`No Kizlo server found in ${cfg.serverEntry}`);
+		try {
+			const result = await generateOnce(cfg, { credentials });
+			if (result.contract === "built") log.success("Contract generated");
+			else if (result.contract === "empty" && cfg.server) log.warn(`No Kizlo server found in ${cfg.server.entry}`);
+			else if (result.introspection === "generated") log.success("WordPress introspection generated");
 		} catch (error) {
 			reportGenerationError("Failed to generate the Kizlo contract:", error);
 		}
-		const watcher = cfg ? await watch(cfg, credentials) : void 0;
-		const wordpressRefresh = refreshWordPress(cwd, cfg, wordpressClientDir, credentials, opts?.stack);
+		const watcher = cfg.server ? await watch(cfg, cfg.server, credentials) : void 0;
+		const wordpressRefresh = refreshWordPress(cfg, credentials, opts?.stack);
 		let stopped = false;
 		handedOver = true;
 		return () => {

package/dist/cli/wp/constants.d.ts

@@ -34,9 +34,7 @@ declare const CREDENTIALS_REL = ".kizlo/test.json";
  * working dir rather than next to the generated files on purpose: it describes one machine's last
  * fetch, so a fresh clone has to regenerate rather than trust a cache it never populated.
  */
-declare const WORDPRESS_META_REL = ".kizlo/wordpress.meta.json";
-/** Same, for the standalone client written by `wordpressClientDir`. Separate so the two never share one ETag. */
-declare const WORDPRESS_CLIENT_META_REL = ".kizlo/wordpress.client.meta.json";
+declare const INTROSPECTION_META_REL = ".kizlo/introspection.meta.json";
 /**
  * Fixed folder the local WordPress install lives in, relative to the config root. The whole install
  * (core, themes, uploads, plugins) is bind-mounted here; `kizlo dev reset` wipes it. It sits under
@@ -56,4 +54,4 @@ declare const DEFAULT_PLUGINS: PluginSource[];
 declare const TEST_ADMIN: Omit<TestAdminUser, "id" | "applicationPassword">;
 declare const TEST_USER: Omit<TestUser, "id">;
 //#endregion
-export { COMPOSE_FILE, CONFIG_FILES, CREDENTIALS_REL, DEFAULT_PLUGINS, DEFAULT_PORT, DEFAULT_WORDPRESS_TAG, LOCAL_DIR_REL, OPCACHE_INI, REMAP_ENTRYPOINT, SEED_MARKER_OPTION, SEED_VERSION, TEST_ADMIN, TEST_USER, WORDPRESS_CLIENT_META_REL, WORDPRESS_META_REL, githubRelease, kizloRelease };
+export { COMPOSE_FILE, CONFIG_FILES, CREDENTIALS_REL, DEFAULT_PLUGINS, DEFAULT_PORT, DEFAULT_WORDPRESS_TAG, INTROSPECTION_META_REL, LOCAL_DIR_REL, OPCACHE_INI, REMAP_ENTRYPOINT, SEED_MARKER_OPTION, SEED_VERSION, TEST_ADMIN, TEST_USER, githubRelease, kizloRelease };

package/dist/cli/wp/constants.js

@@ -44,9 +44,7 @@ const CREDENTIALS_REL = ".kizlo/test.json";
 * working dir rather than next to the generated files on purpose: it describes one machine's last
 * fetch, so a fresh clone has to regenerate rather than trust a cache it never populated.
 */
-const WORDPRESS_META_REL = ".kizlo/wordpress.meta.json";
-/** Same, for the standalone client written by `wordpressClientDir`. Separate so the two never share one ETag. */
-const WORDPRESS_CLIENT_META_REL = ".kizlo/wordpress.client.meta.json";
+const INTROSPECTION_META_REL = ".kizlo/introspection.meta.json";
 /**
 * Fixed folder the local WordPress install lives in, relative to the config root. The whole install
 * (core, themes, uploads, plugins) is bind-mounted here; `kizlo dev reset` wipes it. It sits under
@@ -83,4 +81,4 @@ const TEST_USER = {
 };
 
 //#endregion
-export { COMPOSE_FILE, CONFIG_FILES, CREDENTIALS_REL, DEFAULT_PLUGINS, DEFAULT_PORT, DEFAULT_WORDPRESS_TAG, LOCAL_DIR_REL, OPCACHE_INI, REMAP_ENTRYPOINT, SEED_MARKER_OPTION, SEED_VERSION, TEST_ADMIN, TEST_USER, WORDPRESS_CLIENT_META_REL, WORDPRESS_META_REL, githubRelease, kizloRelease };
+export { COMPOSE_FILE, CONFIG_FILES, CREDENTIALS_REL, DEFAULT_PLUGINS, DEFAULT_PORT, DEFAULT_WORDPRESS_TAG, INTROSPECTION_META_REL, LOCAL_DIR_REL, OPCACHE_INI, REMAP_ENTRYPOINT, SEED_MARKER_OPTION, SEED_VERSION, TEST_ADMIN, TEST_USER, githubRelease, kizloRelease };

package/dist/cli/wp/types.d.ts

@@ -53,13 +53,16 @@ interface SeedContext {
 /**
  * A plugin to ensure installed + active during bootstrap. A bare string is a
  * wp.org slug (the installed name and the install source are the same). The
- * object form is for any other source — a zip URL or a local path — where the
- * installed slug (`name`, used for activation checks) can't be derived from the
- * source. `source` is passed straight to `wp plugin install`.
+ * object form names an install source explicitly, either a wp.org slug or a zip
+ * URL, when the installed slug (`name`, used for activation checks) cannot be
+ * derived from the source or the wp.org release must be pinned. `version` is
+ * passed to `wp plugin install --version` when present. `source` is passed
+ * straight to `wp plugin install`.
  */
 type PluginSource = string | {
   name: string;
   source: string;
+  version?: string;
 };
 /**
  * A local plugin directory to bind-mount into the dev stack (`kizlo dev`) instead

package/dist/cli/wp/utils.d.ts

@@ -14,15 +14,15 @@ import { DevPluginSource, Fixture, PluginSource, SettleContext, TestCredentials
  * Bumping `SEED_VERSION` invalidates older marks and forces a reseed.
  */
 declare function isSeeded(): Promise<boolean>;
-/** Resolve a `PluginSource` to the `(name, source)` pair `ensurePlugin` needs. */
-declare function resolvePluginSource(plugin: PluginSource): [name: string, source: string];
+/** Resolve a `PluginSource` to the arguments `ensurePlugin` needs. */
+declare function resolvePluginSource(plugin: PluginSource): [name: string, source: string, version?: string];
 /**
  * Ensure a plugin is active without ever re-downloading. Plugin files persist in
  * the `wp_data` volume, so an already-installed plugin is just activated; the
  * download (`source` = release zip URL or wp.org slug) happens only when the files
  * are absent (i.e. after `wp reset` wipes the volume).
  */
-declare function ensurePlugin(name: string, source: string): Promise<void>;
+declare function ensurePlugin(name: string, source: string, version?: string): Promise<void>;
 /**
  * Activate a bind-mounted local plugin by its directory basename (the slug the
  * mount lands at under `wp-content/plugins`). Idempotent: the files arrive via the

package/dist/cli/wp/utils.js

@@ -29,9 +29,14 @@ async function isSeeded() {
 	]);
 	return marker.code === 0 && marker.stdout.trim() === SEED_VERSION;
 }
-/** Resolve a `PluginSource` to the `(name, source)` pair `ensurePlugin` needs. */
+/** Resolve a `PluginSource` to the arguments `ensurePlugin` needs. */
 function resolvePluginSource(plugin) {
-	return typeof plugin === "string" ? [plugin, plugin] : [plugin.name, plugin.source];
+	if (typeof plugin === "string") return [plugin, plugin];
+	return plugin.version === void 0 ? [plugin.name, plugin.source] : [
+		plugin.name,
+		plugin.source,
+		plugin.version
+	];
 }
 /**
 * Ensure a plugin is active without ever re-downloading. Plugin files persist in
@@ -39,7 +44,7 @@ function resolvePluginSource(plugin) {
 * download (`source` = release zip URL or wp.org slug) happens only when the files
 * are absent (i.e. after `wp reset` wipes the volume).
 */
-async function ensurePlugin(name, source) {
+async function ensurePlugin(name, source, version) {
 	if ((await compose([
 		"exec",
 		"-T",
@@ -69,6 +74,7 @@ async function ensurePlugin(name, source) {
 		"plugin",
 		"install",
 		source,
+		...version === void 0 ? [] : [`--version=${version}`],
 		"--activate"
 	]);
 }

package/dist/comment/errors.js

@@ -22,7 +22,6 @@ const LIST_COMMENT_ERROR_MAP = defineErrorMap({
 	}
 });
 const SUBMIT_COMMENT_ERROR_MAP = defineErrorMap({
-	COMMENT_USER_NOT_FOUND: {},
 	COMMENT_ID_NOT_FOUND: {},
 	COMMENT_CLOSED: {},
 	COMMENT_LOGIN_REQUIRED: {},

package/dist/comment/index.js

@@ -98,26 +98,26 @@ const COMMENT_PROCEDURES = {
 		const connInfo = await context.getConnInfo();
 		if (!connInfo?.ip) throw new Error("Connection IP is required.");
 		if (!connInfo?.userAgent) throw new Error("Connection user agent is required.");
-		const user = await context.getAuthUser();
-		if (!user) {
+		const session = await context.getSession();
+		if (!session) {
 			if (!input.body.captchaToken) throw errors.COMMENT_CAPTCHA_REQUIRED();
 			if (!await context.verifyCaptcha(input.body.captchaToken)) throw errors.COMMENT_CAPTCHA_INVALID();
 		}
-		const response = await context.wordpress.kizlo.comments.create({
-			user_id: user?.id,
+		const submission = {
 			author_ip: connInfo.ip,
 			user_agent: connInfo.userAgent,
 			content: input.body.content,
 			post_id: input.body.postId,
+			user_email: session?.email,
 			author_email: input.body.authorEmail,
 			author_name: input.body.authorName,
 			author_url: input.body.authorUrl,
 			parent: input.body.parentId
-		});
+		};
+		const response = await context.wordpress.kizlo.comments.create(submission);
 		if (response.error) switch (response.error.code) {
 			case "require_name_email": throw errors.COMMENT_NAME_EMAIL_REQUIRED();
 			case "require_valid_email": throw errors.COMMENT_INVALID_EMAIL();
-			case "kizlo_invalid_user": throw errors.COMMENT_USER_NOT_FOUND();
 			case "require_valid_comment": throw errors.COMMENT_EMPTY_CONTENT();
 			case "not_logged_in": throw errors.COMMENT_LOGIN_REQUIRED();
 			case "comment_closed": throw errors.COMMENT_CLOSED();

package/dist/config.d.ts

@@ -2,14 +2,28 @@ import { Fixture } from "./cli/wp/types.js";
 import "./test.js";
 
 //#region src/config.d.ts
+
+/**
+ * Where Kizlo generates, and what it watches. A string is the home directory Kizlo owns the layout
+ * under: sources in `<dir>/server`, and the generated files (`contract.json`, the barrel, and
+ * `introspection.ts`) under `<dir>/server/generated`. The object form sets each path on its own. Omit
+ * `server` and there are no sources to watch and no contract is built, so only the introspection is
+ * generated (the shape a package that ships procedures but no server takes).
+ */
+type KizloDir = string | {
+  /** Server sources (extensions and procedures). Watched by `kizlo dev`; its presence is what builds a contract. */
+  server?: string;
+  /** Where `contract.json` and the generated barrel are written. Defaults to `generated/` under `server`. */
+  contract?: string;
+  /** Where the generated `introspection.ts` is written. Defaults to `generated/` under `server`. */
+  introspection?: string;
+};
 interface KizloDevConfig {
   /**
-   * Run local WordPress under `kizlo dev`. When `true`, `kizlo dev` boots a Docker WordPress in
-   * `.kizlo/local` alongside the contract watcher; when unset or `false`, it runs the watcher alone
-   * (for a project pointing at your own WordPress). Set for you by `kizlo create` / `kizlo init`
-   * when you choose local WordPress.
+   * Run the dev stack. On by default when local WordPress is enabled; set `false` to keep local
+   * WordPress on for `kizlo test` while `kizlo dev` runs the contract watcher alone.
    */
-  local?: boolean;
+  enable?: boolean;
   /** Published WP port (default 8080). */
   port?: number;
   /**
@@ -17,8 +31,8 @@ interface KizloDevConfig {
    * Hub: a bare version (`"7.1.0"`), or a full tag (`"7.1.0-php8.3-apache"`) when you need
    * a specific PHP. Defaults to `latest`, so an unconfigured project gets current WordPress.
    *
-   * Worth setting once you commit a generated WordPress client, which is derived from
-   * whatever the stack serves: on `latest` that client goes stale the day WordPress ships.
+   * Worth setting once you commit a generated introspection, which is derived from
+   * whatever the stack serves: on `latest` that introspection goes stale the day WordPress ships.
    *
    * An existing install keeps the core files it was provisioned with, so changing this
    * takes effect on the next `kizlo dev reset` and Kizlo says so when the two disagree.
@@ -45,27 +59,24 @@ interface KizloDevConfig {
 }
 interface KizloTestConfig {
   /**
-   * Run local WordPress under `kizlo test`. When `true`, `kizlo test` boots a disposable Docker
-   * WordPress, seeds it, and runs your suite against it; when unset or `false`, `kizlo test` just
-   * runs your project's test script. Set for you by `kizlo create` / `kizlo init` when you choose
-   * local WordPress.
+   * Run the test stack. On by default when local WordPress is enabled; set `false` to keep local
+   * WordPress on for `kizlo dev` while `kizlo test` just runs the project's own test script.
+   */
+  enable?: boolean;
+  /**
+   * Fall back to the dev stack's `version` and `fixtures` when this stack leaves them unset (default
+   * `true`), so the two stacks a local-WordPress project always wants together are declared once.
+   * Set `false` to configure the test stack independently, taking Kizlo's defaults where it is silent.
    */
-  local?: boolean;
+  inherit?: boolean;
   /** Published WP port (default 8889). */
   port?: number;
   /**
    * WordPress version the local stack boots, given as the tag after `wordpress:` on Docker
-   * Hub: a bare version (`"7.1.0"`), or a full tag (`"7.1.0-php8.3-apache"`) when you need
-   * a specific PHP. Defaults to `latest`, so an unconfigured project gets current WordPress.
-   *
-   * Worth setting once you commit a generated WordPress client, which is derived from
-   * whatever the stack serves: on `latest` that client goes stale the day WordPress ships.
-   *
-   * An existing install keeps the core files it was provisioned with, so changing this
-   * takes effect on the next `kizlo test reset` and Kizlo says so when the two disagree.
+   * Hub. Falls back to the dev stack's `version` unless `inherit` is `false`; defaults to `latest`.
    */
   version?: string;
-  /** Integration fixtures to install + seed. */
+  /** Integration fixtures to install + seed. Falls back to the dev stack's `fixtures` unless `inherit` is `false`. */
   fixtures?: Fixture[];
   /**
    * Package manager used to launch the test script (default: auto-detected from
@@ -78,20 +89,12 @@ interface KizloTestConfig {
    */
   command?: string;
 }
-interface KizloGlobalConfig {
-  /**
-   * Kizlo's home directory. Kizlo owns the layout inside it: your server
-   * (`server/`, whose `index.ts` exports `procedures` plus your integrations), the
-   * browser `client.ts`, and the generated contract.
-   * @default 'src/lib/kizlo' (or 'lib/kizlo' without a src dir)
-   */
-  dir?: string;
+interface KizloLocalConfig {
   /**
-   * Import alias prefix for generated imports (e.g. `@`). Recorded by `kizlo init`
-   * from your `--alias` flag or its prompt, so later runs reuse it instead of asking
-   * again; an empty string (`""`) is the recorded choice to use relative imports.
+   * Enable local Docker WordPress (default `true` in this object form). Set `false` to keep the
+   * stacks configured but off, the same as omitting `local` entirely.
    */
-  alias?: string;
+  enable?: boolean;
   /**
    * Base name for the local Docker stacks (`kizlo-<name>-dev`, `kizlo-<name>-test`). Defaults
    * to the sanitized `package.json` name, falling back to the config dir basename.
@@ -99,8 +102,8 @@ interface KizloGlobalConfig {
   name?: string;
   /**
    * Give each branch its own local Docker stacks, by appending the checked-out branch to
-   * {@link name} (`kizlo-<name>-<branch>-dev`). Off unless set, since the stacks it isolates
-   * are the ones an existing project is already using.
+   * {@link KizloLocalConfig.name} (`kizlo-<name>-<branch>-dev`). Off unless set, since the stacks it
+   * isolates are the ones an existing project is already using.
    *
    * Turn it on when you work in several checkouts at once, typically git worktrees: without it
    * every checkout of a project resolves to one stack, so parallel `kizlo dev` and `kizlo test`
@@ -109,20 +112,31 @@ interface KizloGlobalConfig {
    * A detached `HEAD` names no branch and keeps the unsuffixed stack.
    */
   worktrees?: boolean;
-  /**
-   * Directory to write the WordPress client into, as `<wordpressClientDir>/wordpress.ts`. For a package or
-   * workspace that ships procedures but no Kizlo server: there is no procedure tree to build a contract from,
-   * yet those procedures still call the generated tree, so they need the client on its own.
-   *
-   * Independent of `dir`. An app leaves this unset and gets its client inside `dir` alongside the
-   * contract; set both only if a project is somehow each of those things at once.
-   */
-  wordpressClientDir?: string;
-  /** Local WordPress and contract watcher run by `kizlo dev`. */
+  /** The dev stack run by `kizlo dev`. */
   dev?: KizloDevConfig;
-  /** WordPress test environment run by `kizlo test`. */
+  /** The test stack run by `kizlo test`. Inherits `version` and `fixtures` from {@link KizloLocalConfig.dev}. */
   test?: KizloTestConfig;
 }
+interface KizloGlobalConfig {
+  /**
+   * Where Kizlo generates, and what it watches. A string names the home directory Kizlo owns the
+   * layout under; the object form sets the server, contract, and introspection paths independently.
+   * @default 'src/lib/kizlo' (or 'lib/kizlo' without a src dir)
+   */
+  dir?: KizloDir;
+  /**
+   * Import alias prefix for generated imports (e.g. `@`). Recorded by `kizlo init`
+   * from your `--alias` flag or its prompt, so later runs reuse it instead of asking
+   * again; an empty string (`""`) is the recorded choice to use relative imports.
+   */
+  alias?: string;
+  /**
+   * Local Docker WordPress, off unless set. `true` enables both the dev and test stacks with
+   * defaults; the object form enables and configures them, and is where the stack name, the
+   * per-branch `worktrees` toggle, and the two stacks live.
+   */
+  local?: boolean | KizloLocalConfig;
+}
 declare function defineConfig(config: KizloGlobalConfig): KizloGlobalConfig;
 //#endregion
-export { KizloDevConfig, KizloGlobalConfig, KizloTestConfig, defineConfig };
+export { KizloDevConfig, KizloDir, KizloGlobalConfig, KizloLocalConfig, KizloTestConfig, defineConfig };

package/dist/context.d.ts

@@ -20,7 +20,7 @@ interface ContextConfig {
   /** WordPress plugins the registered integrations need, checked against what each response reports. */
   integrationPlugins?: IntegrationPluginRequirement[];
 }
-type AuthUserFn = () => Promise<AuthUser | null>;
+type SessionFn = () => Promise<AuthUser | null>;
 type ConnInfoFn = () => Promise<ConnInfo | null>;
 type VerifyCaptchaFn = (token: string) => Promise<boolean>;
 type VerifyPreviewTokenFn = (token: string) => Promise<PreviewTokenPayload | null>;
@@ -46,8 +46,8 @@ interface ProcedureContext {
   config: ContextConfig;
   /** Resolve the caller's connection info (IP, geo) via the geo adapter, or `null`. */
   getConnInfo: ConnInfoFn;
-  /** Resolve the authenticated user via the auth adapter, or `null`. */
-  getAuthUser: AuthUserFn;
+  /** Resolve the authenticated session via the auth adapter, or `null`. */
+  getSession: SessionFn;
   /** Read and write cookies through the cookies adapter. */
   cookies: CookiesStorage;
   /** Verify a CAPTCHA token via the captcha adapter. */
@@ -84,7 +84,7 @@ declare class Context {
     email: EmailService;
     getConnInfo: ConnInfoFn;
     verifyCaptcha: VerifyCaptchaFn;
-    getAuthUser: AuthUserFn;
+    getSession: SessionFn;
     verifyPreviewToken: VerifyPreviewTokenFn;
     cookies: CookiesStorage;
     invokedBy: "client";
@@ -98,7 +98,7 @@ declare class Context {
     wordpress: WordPressTransport;
     settings: SettingsService;
     email: EmailService;
-    getAuthUser: AuthUserFn;
+    getSession: SessionFn;
     getConnInfo: ConnInfoFn;
     verifyCaptcha: VerifyCaptchaFn;
     verifyPreviewToken: VerifyPreviewTokenFn;
@@ -107,9 +107,9 @@ declare class Context {
   private createRestCookieStorage;
   private createVerifyCaptchaFn;
   private createConnInfoFn;
-  private createGetUserFn;
+  private createGetSessionFn;
   private createVerifyPreviewTokenFn;
   private createLogger;
 }
 //#endregion
-export { AuthUserFn, ConnInfoFn, Context, ContextConfig, ProcedureContext, VerifyCaptchaFn, VerifyPreviewTokenFn };
+export { ConnInfoFn, Context, ContextConfig, ProcedureContext, SessionFn, VerifyCaptchaFn, VerifyPreviewTokenFn };

package/dist/context.js

@@ -102,7 +102,7 @@ var Context = class {
 			email: this.email,
 			getConnInfo: this.createConnInfoFn(request),
 			verifyCaptcha: this.createVerifyCaptchaFn(request),
-			getAuthUser: this.createGetUserFn(request),
+			getSession: this.createGetSessionFn(request),
 			verifyPreviewToken: this.createVerifyPreviewTokenFn(),
 			cookies: this.createRestCookieStorage(request, headers),
 			invokedBy: "client"
@@ -118,7 +118,7 @@ var Context = class {
 			wordpress: this.wordpress,
 			settings: this.settings,
 			email: this.email,
-			getAuthUser: this.createGetUserFn(null),
+			getSession: this.createGetSessionFn(null),
 			getConnInfo: this.createConnInfoFn(null),
 			verifyCaptcha: this.createVerifyCaptchaFn(null),
 			verifyPreviewToken: this.createVerifyPreviewTokenFn(),
@@ -176,9 +176,9 @@ var Context = class {
 			return await this.config.adapters?.geo?.getConnInfo?.(request) ?? null;
 		};
 	}
-	createGetUserFn(request) {
+	createGetSessionFn(request) {
 		return async () => {
-			return await Promise.resolve(this.config.adapters?.auth?.getUser?.(request)) ?? null;
+			return await Promise.resolve(this.config.adapters?.auth?.getSession?.(request)) ?? null;
 		};
 	}
 	createVerifyPreviewTokenFn() {