@zerotal/core 1.11.2 → 1.13.0

package/CHANGELOG.md

@@ -8,6 +8,32 @@ follows the Zerotal monorepo's unified versioning.
 
 ## [Unreleased]
 
+## [1.13.0] — 2026-08-31
+
+### Changed — **BREAKING**
+
+- **`LockDriver.extend()` is required.** Only affects a custom driver; all three built-in
+  ones implement it.
+
+  It shipped optional in 1.5.0 with `acquire(key, owner, ttl)` as the fallback, and the
+  fallback was correct only by coincidence — `acquire` happens to be an owner-guarded refresh
+  on every built-in driver, and nothing in the interface said it had to be. A third-party
+  driver whose `acquire` takes a _free_ lock, which is the ordinary reading of the word, would
+  have had `refresh()` silently take a lock another holder owned. That is the one thing a lock
+  exists to prevent, and the contract was quietly assuming its way past it.
+
+- **`routes:types` and `serve --dev` are retired**, in favour of `route:types` and `dev`.
+  `zt upgrade` rewrites both.
+
+  `serve --dev` **fails with a message** rather than being ignored. The flag is still declared
+  for that reason alone: flag parsing runs non-strict, so deleting it would have left
+  `serve --dev` starting a plain server with no watcher and no explanation — a retired flag
+  that silently changes what a command does is worse than one that is still there.
+
+### Added
+
+- **The `client-tagged-template` codemod**, for the Flow removal above.
+
 ## [1.11.1] — 2026-08-31
 
 ### Added

package/api-surface.md

@@ -3034,7 +3034,7 @@ interface LockDriver = {
   acquire: (key: string, owner: string, ttlSeconds: number) => Promise<boolean>
   dispose?: () => void
   exists: (key: string) => Promise<boolean>
-  extend?: (key: string, owner: string, ttlSeconds: number) => Promise<boolean>
+  extend: (key: string, owner: string, ttlSeconds: number) => Promise<boolean>
   forceRelease: (key: string) => Promise<void>
   release: (key: string, owner: string) => Promise<boolean>
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zerotal/core",
-  "version": "1.11.2",
+  "version": "1.13.0",
   "license": "MIT",
   "maturity": "stable",
   "private": false,

package/src/command/CommandRunner.ts

@@ -392,7 +392,9 @@ export class CommandRunner {
 
     // route:types reads the same booted router, so it is available wherever
     // route:list is — including in CI containers that only ever run `--check`.
-    this.register(RouteTypesCommand, ["routes:types"]);
+    //
+    // The `routes:types` alias was retired in 1.13.0; `zt upgrade` rewrites it.
+    this.register(RouteTypesCommand);
 
     // Non-web commands (console, worker, test).
     if (this._app._env !== "web") {

package/src/command/builtin/DevCommand.ts

@@ -80,9 +80,10 @@ export class DevCommand extends ServeCommand {
   ];
 
   override async run(): Promise<void> {
-    // `dev` is `serve --dev` — set the flag the parent branches on rather than
-    // duplicating its port resolution, asset config and banner.
-    this.flags["dev"] = true;
+    // Set the parent's own switch rather than the `dev` flag, which is now
+    // reserved for refusing `serve --dev` by name. Same supervisor, same port
+    // resolution, same banner — this subclasses so the two cannot drift.
+    this._dev = true;
     await super.run();
   }
 }

package/src/command/builtin/ServeCommand.ts

@@ -48,9 +48,15 @@ export class ServeCommand extends Command {
       default: 3000,
     },
     {
+      // Declared only so it can be refused by name. Removing it outright would be
+      // worse than keeping it: `parseFlagsAndArgs` runs with `strict: false`, so an
+      // undeclared `--dev` is parsed and dropped, and `serve --dev` would have gone
+      // on starting a plain server with no watcher and no message. A retired flag
+      // that silently changes what a command does is the failure this release is
+      // otherwise about.
       name: "dev",
       type: "boolean",
-      description: "Start in dev mode with file watching, auto-rebuild, and browser reload",
+      description: "Retired in 1.13.0 — use `zt dev`",
       default: false,
     },
     {
@@ -74,8 +80,26 @@ export class ServeCommand extends Command {
     },
   ];
 
+  /**
+   * Set by {@link DevCommand} rather than by a flag, so `serve --dev` can be
+   * refused while `dev` keeps the supervisor it subclasses.
+   *
+   * @internal
+   */
+  protected _dev = false;
+
   async run(): Promise<void> {
-    const isDev = this.flags["dev"] as boolean;
+    if (this.flags["dev"] === true && !this._dev) {
+      this.error(
+        "`serve --dev` was retired in 1.13.0. Use `bun zt dev` — it is the same supervisor, " +
+          "the same processes and the same restart behaviour, plus the flags that only make " +
+          "sense with a deck on screen (--only, --without, --list, --stream).",
+      );
+      process.exitCode = 1;
+      return;
+    }
+
+    const isDev = this._dev;
     const isWorker = this.flags["dev-worker"] as boolean;
 
     // ── DEV ORCHESTRATOR (Process 1) ────────────────────────────────────────

package/src/lock/LockManager.ts

@@ -135,13 +135,12 @@ export class ManagedLock {
     if (!this._acquired) return false;
     const ttl = ttlSeconds ?? this._ttl;
 
-    // `extend` is optional on the contract so a driver written against 1.x still
-    // satisfies it. `acquire` is the fallback because on every built-in driver it
-    // is an owner-guarded refresh — which is exactly what this needs, and is the
-    // behaviour the memory driver had to be fixed to honour.
-    const extended = this._driver.extend
-      ? await this._driver.extend(this._key, this._owner, ttl)
-      : await this._driver.acquire(this._key, this._owner, ttl);
+    // `extend` is required on the contract since 1.13.0, so there is no fallback
+    // here any more. The one it replaced — `acquire(key, owner, ttl)` — worked only
+    // because every built-in driver happens to make `acquire` an owner-guarded
+    // refresh, which the interface never required and a third-party driver had no
+    // reason to know.
+    const extended = await this._driver.extend(this._key, this._owner, ttl);
 
     if (!extended) {
       this._acquired = false;

package/src/lock/drivers/LockDriver.ts

@@ -32,11 +32,16 @@ export interface LockDriver {
    * returns `false` when the key is free or held by someone else, so a holder
    * that lost the lock learns about it rather than extending a stranger's.
    *
-   * **Optional** so a driver written against 1.x still satisfies this interface.
-   * {@link ManagedLock.refresh} falls back to `acquire(key, owner, ttl)`, which
-   * is an owner-guarded refresh on all three built-in drivers.
+   * **Required since 1.13.0.** It shipped optional in 1.5.0 with `acquire()` as a
+   * fallback, and the fallback was only ever correct by coincidence: `acquire` is
+   * an owner-guarded refresh on all three built-in drivers, and nothing in this
+   * interface said it had to be. A third-party driver whose `acquire` takes a free
+   * lock — the ordinary reading of the word — would have had `refresh()` silently
+   * steal a lock another holder owned, which is the one thing a lock exists to
+   * prevent. Requiring the method turns an assumption the contract never stated
+   * into something a driver has to answer.
    */
-  extend?(key: string, owner: string, ttlSeconds: number): Promise<boolean>;
+  extend(key: string, owner: string, ttlSeconds: number): Promise<boolean>;
 
   /** Release background resources (timers, DB connections). */
   dispose?(): void;

package/src/upgrade/codemods/client-tagged-template.ts

@@ -0,0 +1,108 @@
+/**
+ * Ledger #5 — `Component.client(…)` gives way to the `$` tagged template.
+ *
+ * This one is a security fix wearing an ergonomics change's clothes, and that is
+ * why it shipped in a minor rather than waiting for 2.0. `client()` takes a
+ * **string** and queues it to be evaluated in the browser, so the caller owns the
+ * escaping — and its own docblock had to say *never interpolate unescaped user
+ * input*, which is a warning about a footgun rather than a design. `$` is a tagged
+ * template, so every `${…}` is encoded as a JS literal before it reaches the page
+ * and the caller cannot get it wrong by forgetting.
+ *
+ * ## What this rewrites, and what it hands back
+ *
+ * A call whose argument is **one template literal or one plain string** is
+ * mechanical: the quotes become backticks and `client(` becomes `` $` ``. Nothing
+ * about the expression changes.
+ *
+ * A call whose argument is **anything else** is a handover. `client(expr)` where
+ * `expr` is a variable, a concatenation, or a function call is exactly the shape
+ * the security note was about — the string was built somewhere else, possibly out
+ * of user input, and turning it into `` $`${expr}` `` would change its meaning:
+ * the tag would encode the whole expression as a *string literal* rather than
+ * splicing it as code. That is a silent behaviour change, so a person decides.
+ *
+ * Getting this backwards is the failure worth avoiding. A codemod that
+ * mechanically wrapped every argument would leave an app that compiles, runs, and
+ * quietly does nothing where it used to run a script.
+ */
+import type { Change, Codemod, CodemodResult, Manual, SourceFile } from "../types.ts";
+
+/**
+ * `this.client(` followed by a single template literal with no substitution of its
+ * own, to the closing `)`.
+ *
+ * Backtick-delimited, containing no backtick and no `${`, so the match cannot run
+ * past the end of the literal.
+ *
+ * A **bare `$` is allowed, and has to be.** `$refs`, `$el` and the `$flow` magics
+ * are the whole reason anyone calls this — the method's own docblock example is
+ * `` this.client(`$refs.titleInput.focus()`) ``. An earlier draft excluded `$`
+ * outright to keep `${` out, which skipped every realistic call site while passing
+ * a test suite written around `alert(1)`.
+ */
+const PLAIN_TEMPLATE = /\bthis\.client\(\s*`((?:[^`\\$]|\$(?!\{))*)`\s*\)/g;
+
+/**
+ * `this.client('…')` / `this.client("…")` with no escape, no backtick and no `${`.
+ *
+ * `${` matters more here than in the template case: promoting a quoted string to a
+ * template literal turns a literal `${…}` into an interpolation, which is a change
+ * in meaning rather than in syntax.
+ */
+const PLAIN_STRING = /\bthis\.client\(\s*(['"])((?:(?!\1)(?:[^\\`$]|\$(?!\{)))*)\1\s*\)/g;
+
+/** Any remaining `this.client(`, for the handover pass. */
+const ANY_CALL = /\bthis\.client\(/;
+
+export const clientTaggedTemplate: Codemod = {
+  version: "1.13.0",
+  name: "client-tagged-template",
+  description: "Rewrite this.client(…) to the $ tagged template, which encodes interpolations",
+  ledger: 5,
+
+  run(files: SourceFile[]): CodemodResult {
+    const changes: Change[] = [];
+    const manual: Manual[] = [];
+
+    for (const { file, contents } of files) {
+      let next = contents;
+      const notes: string[] = [];
+
+      const templateHits = next.match(PLAIN_TEMPLATE)?.length ?? 0;
+      if (templateHits > 0) {
+        next = next.replace(PLAIN_TEMPLATE, (_m, body: string) => `this.$\`${body}\``);
+        notes.push(`${templateHits} × \`client(\\\`…\\\`)\` → \`$\\\`…\\\`\``);
+      }
+
+      const stringHits = next.match(PLAIN_STRING)?.length ?? 0;
+      if (stringHits > 0) {
+        // The body carried no backtick or `${`, so promoting the quotes cannot
+        // change what the expression means.
+        next = next.replace(PLAIN_STRING, (_m, _q: string, body: string) => `this.$\`${body}\``);
+        notes.push(`${stringHits} × \`client("…")\` → \`$\\\`…\\\`\``);
+      }
+
+      // Whatever is left took an argument this cannot read.
+      next.split("\n").forEach((line, i) => {
+        if (!ANY_CALL.test(line)) return;
+        manual.push({
+          file,
+          line: i + 1,
+          text: line.trim(),
+          reason:
+            "`client()` with an argument that is not a single literal — a variable, a " +
+            "concatenation, a call. This is the shape the security note was about, so it is " +
+            "worth reading rather than rewriting: if the string is built from user input, the " +
+            "fix is to interpolate through `$` so the value is encoded, not to wrap the " +
+            "finished string. Wrapping it as `` $`${expr}` `` would encode the whole thing as a " +
+            "string literal and stop running it as code.",
+        });
+      });
+
+      if (next !== contents) changes.push({ file, summary: notes.join(", "), contents: next });
+    }
+
+    return { changes, manual };
+  },
+};

package/src/upgrade/codemods/index.ts

@@ -9,7 +9,8 @@
  */
 import type { Codemod } from "../types.ts";
 import { deprecatedAliases } from "./deprecated-aliases.ts";
+import { clientTaggedTemplate } from "./client-tagged-template.ts";
 
-export const CODEMODS: Codemod[] = [deprecatedAliases];
+export const CODEMODS: Codemod[] = [clientTaggedTemplate, deprecatedAliases];
 
-export { deprecatedAliases };
+export { deprecatedAliases, clientTaggedTemplate };