@zerotal/core 1.7.2 → 1.7.4

package/CHANGELOG.md

@@ -8,6 +8,39 @@ follows the Zerotal monorepo's unified versioning.
 
 ## [Unreleased]
 
+## [1.7.3] — 2026-08-20
+
+### Fixed
+
+- **`make:request` generates a file that compiles.** The stub imported `@zerotal/validator`,
+  which a scaffolded app does not depend on — it depends on the `zerotal` umbrella — so the
+  generated file failed to resolve until the import was changed by hand. It also annotated
+  `rules(): Record<string, FieldRule>`, the one thing `FormRequest`'s own docblock warns
+  against: `validate()` reads the narrow return type through `ReturnType<T['rules']>`, so the
+  annotation widened it back and every validated field arrived as `unknown`, silently, with a
+  cast somewhere downstream the first sign of it.
+
+- **Every other `make:*` stub names a package the app has too.** The same fault ran through
+  nine generators: `make:command`, `make:controller`, `make:middleware` and `make:provider`
+  named `@zerotal/core`; `make:job` `@zerotal/queue`; `make:observer` `@zerotal/orm`;
+  `make:policy` `@zerotal/auth`; `make:test` `@zerotal/testing`. A scaffolded app depends on
+  none of them — it has the `zerotal` umbrella — so each wrote a file that did not resolve.
+  They now emit `zerotal` and its subpaths.
+
+  `make:resource` was worse: `Resource`, `ResourceCollection` and `PaginatedData` are not on
+  `@zerotal/core`'s root entry at all, so that stub was broken against the scoped name as
+  well. It emits `zerotal/http`, where they live.
+
+  `make:notification` keeps `@zerotal/notifications`: there is no umbrella subpath for it, and
+  the `api` template installs it directly.
+
+  A single test now runs all thirteen generators and fails on any import that is neither the
+  umbrella, a Bun/Node builtin, a relative path, nor one of the scoped packages a template
+  actually installs. Each generator's own test had only checked that the output mentioned the
+  class being made, which is why none of this showed.
+
+## [1.7.2] — 2026-08-18
+
 ### Added
 
 - **`@zerotal/core/errors`** — a subpath for the error classes, so a module that can run in a
@@ -19,7 +52,6 @@ follows the Zerotal monorepo's unified versioning.
   The rule this makes workable: **core's root entry is server-only.** Anything that might be
   bundled for a browser imports from a narrow subpath.
 
-
 ## [1.7.1] — 2026-08-16
 
 ### Changed

package/api-surface.md

@@ -316,6 +316,7 @@ class HttpContext = {
   new <TParams extends Record<string, unknown> = Record<string, string>>(request: Request, container: ScopedResolver): HttpContext<TParams>
   static fake: (url?: string, init?: RequestInit, container?: ScopedResolver) => HttpContext
   static tryGet: () => HttpContext | undefined
+  __: (key: string, replacements?: Replacements, locale?: string) => string
   _afterResponseCallbacks: (() => Promise<void>)[]
   _pageResolver?: (pageName: string) => number | undefined
   _primeBody: (data: Record<string, unknown>) => void
@@ -368,7 +369,6 @@ class HttpContext = {
   string: (key: string, fallback?: string) => string | undefined
   subdomain: (name: string) => string | null
   subdomains: Record<string, string>
-  t: (key: string, replacements?: Replacements, locale?: string) => string
   took: number
   user?: UserModel | undefined
   view: {    (markup: ViewMarkup, status?: number): void;    <P extends Record<string, unknown> = Record<string, never>>(component: (ctx: HttpContext, props: P) => ViewMarkup | Promise<ViewMarkup>, props?: P | undefined, status?: number): void | Promise<void>;}
@@ -1101,6 +1101,7 @@ interface WebhookOptions = {
 interface WebSocketHandlers = {
   close?: (ws: unknown, code: number, reason: string) => void
   drain?: (ws: unknown) => void
+  idleTimeout?: number
   message: (ws: unknown, message: string | Uint8Array) => void
   open?: (ws: unknown) => void
 }
@@ -1111,7 +1112,7 @@ type AppScopeInstaller = () => () => void
 
 type ArgDef = {    name: string;    required?: boolean;    default?: string;}
 
-type BindingToken = keyof ContainerBindings | ClassToken<T> | AbstractToken<T>
+type BindingToken = ClassToken<T> | AbstractToken<T> | keyof ContainerBindings
 
 type ClassRef = abstract new (...args: never[]) => unknown
 
@@ -1139,7 +1140,7 @@ type FileRouteResolver = (ctx: FileRouteContext) => boolean
 
 type FileRoutingConfig = {    [x: string]: FileRoutingEntry;}
 
-type FileRoutingEntry = string | {    dir: string;    prefix?: string;    middleware?: MiddlewareInput;}
+type FileRoutingEntry = string | { dir: string; prefix?: string; middleware?: MiddlewareInput }
 
 type FlagDef = {    name: string;    short?: string;    type: 'string' | 'boolean' | 'number';    description?: string;    default?: unknown;}
 
@@ -1177,7 +1178,7 @@ type RouteTarget = string
 
 type RoutingConfig = {    [x: string]: RoutingEntry;}
 
-type RoutingEntry = string | {    file: string;    prefix?: string;    middleware?: MiddlewareInput;}
+type RoutingEntry = string | { file: string; prefix?: string; middleware?: MiddlewareInput }
 
 type SameSite = 'Strict' | 'Lax' | 'None'
 
@@ -2428,7 +2429,7 @@ interface RegisteredConfigValidator = {
   validate: ConfigValidator
 }
 
-type AssetLoaderKind = 'text' | 'file' | 'json' | 'dataurl' | 'base64' | 'toml'
+type AssetLoaderKind = 'file' | 'dataurl' | 'base64' | 'text' | 'json' | 'toml'
 
 type ConfigIssueLevel = 'error' | 'warning'
 
@@ -2645,10 +2646,211 @@ const t = {    readonly string: () => Def<string | undefined>;    readonly numbe
 
 type EnvOutput = { readonly [K in keyof S]: InferDef<S[K]>; }
 
-type FieldType = 'string' | 'number' | 'boolean' | 'url' | 'enum' | 'port'
+type FieldType = 'string' | 'number' | 'boolean' | 'enum' | 'url' | 'port'
 
 type InferDef = D extends Def<infer T> ? T : never
 
+## ./errors  `(./src/errors/index.ts)`
+
+class BadRequestError = {
+  new (message?: string): BadRequestError
+  headers?: Record<string, string>
+  readonly code: string
+  readonly context?: Record<string, unknown> | undefined
+  readonly status: number
+}
+
+class BindingNotFoundError = {
+  new (token: string): BindingNotFoundError
+  readonly code: string
+  readonly context?: Record<string, unknown> | undefined
+  readonly status: number
+}
+
+class BootCheckError = {
+  new (failures: BootCheckFailure[]): BootCheckError
+  readonly code: string
+  readonly context?: Record<string, unknown> | undefined
+  readonly failures: BootCheckFailure[]
+  readonly status: number
+}
+
+class CircularDependencyError = {
+  new (chain: string[]): CircularDependencyError
+  readonly code: string
+  readonly context?: Record<string, unknown> | undefined
+  readonly status: number
+}
+
+class ConfigError = {
+  new (message: string): ConfigError
+  readonly code: string
+  readonly context?: Record<string, unknown> | undefined
+  readonly status: number
+}
+
+class ConfigValidationError = {
+  new (issues: Array<{ namespace: string; message: string; }>): ConfigValidationError
+  readonly code: string
+  readonly context?: Record<string, unknown> | undefined
+  readonly issues: {    namespace: string;    message: string;}[]
+  readonly status: number
+}
+
+class ConflictError = {
+  new (message?: string): ConflictError
+  headers?: Record<string, string>
+  readonly code: string
+  readonly context?: Record<string, unknown> | undefined
+  readonly status: number
+}
+
+class ContainerLockedError = {
+  new (method: string): ContainerLockedError
+  readonly code: string
+  readonly context?: Record<string, unknown> | undefined
+  readonly status: number
+}
+
+class ContextOutsideRequestError = {
+  new (): ContextOutsideRequestError
+  headers?: Record<string, string>
+  readonly code: string
+  readonly context?: Record<string, unknown> | undefined
+  readonly status: number
+}
+
+class FacadeAccessedBeforeBootError = {
+  new (facadeKey: string): FacadeAccessedBeforeBootError
+  readonly code: string
+  readonly context?: Record<string, unknown> | undefined
+  readonly status: number
+}
+
+class FacadeBindingMissingError = {
+  new (facadeKey: string): FacadeBindingMissingError
+  readonly code: string
+  readonly context?: Record<string, unknown> | undefined
+  readonly status: number
+}
+
+class ForbiddenError = {
+  new (message?: string): ForbiddenError
+  headers?: Record<string, string>
+  readonly code: string
+  readonly context?: Record<string, unknown> | undefined
+  readonly status: number
+}
+
+class GoneError = {
+  new (message?: string): GoneError
+  headers?: Record<string, string>
+  readonly code: string
+  readonly context?: Record<string, unknown> | undefined
+  readonly status: number
+}
+
+class HttpError = {
+  new (message: string, status: number, code?: string, headers?: Record<string, string>): HttpError
+  headers?: Record<string, string>
+  readonly code: string
+  readonly context?: Record<string, unknown> | undefined
+  readonly status: number
+}
+
+class MethodNotAllowedError = {
+  new (allowed?: string[], message?: string): MethodNotAllowedError
+  headers?: Record<string, string>
+  readonly code: string
+  readonly context?: Record<string, unknown> | undefined
+  readonly status: number
+}
+
+class NotFoundError = {
+  new (message?: string): NotFoundError
+  headers?: Record<string, string>
+  readonly code: string
+  readonly context?: Record<string, unknown> | undefined
+  readonly status: number
+}
+
+class ScopedAfterFlushError = {
+  new (message: string): ScopedAfterFlushError
+  readonly code: string
+  readonly context?: Record<string, unknown> | undefined
+  readonly status: number
+}
+
+class ScopedOutsideRequestError = {
+  new (message: string): ScopedOutsideRequestError
+  readonly code: string
+  readonly context?: Record<string, unknown> | undefined
+  readonly status: number
+}
+
+class ServiceUnavailableError = {
+  new (reason?: string, retryAfter?: number): ServiceUnavailableError
+  headers?: Record<string, string>
+  readonly code: string
+  readonly context?: Record<string, unknown> | undefined
+  readonly retryAfter?: number | undefined
+  readonly status: number
+}
+
+class SyncResolutionError = {
+  new (message: string): SyncResolutionError
+  readonly code: string
+  readonly context?: Record<string, unknown> | undefined
+  readonly status: number
+}
+
+class TooManyRequestsError = {
+  new (retryAfter?: number, message?: string): TooManyRequestsError
+  headers?: Record<string, string>
+  readonly code: string
+  readonly context?: Record<string, unknown> | undefined
+  readonly retryAfter?: number | undefined
+  readonly status: number
+}
+
+class UnauthorizedError = {
+  new (message?: string): UnauthorizedError
+  headers?: Record<string, string>
+  readonly code: string
+  readonly context?: Record<string, unknown> | undefined
+  readonly status: number
+}
+
+class UnprocessableEntityError = {
+  new (message?: string): UnprocessableEntityError
+  headers?: Record<string, string>
+  readonly code: string
+  readonly context?: Record<string, unknown> | undefined
+  readonly status: number
+}
+
+class ValidationError = {
+  new (message: string, errors: Record<string, string[]>): ValidationError
+  headers?: Record<string, string>
+  readonly code: string
+  readonly context?: Record<string, unknown> | undefined
+  readonly errors: Record<string, string[]>
+  readonly status: number
+}
+
+class ZerotalError = {
+  new (message: string, code: string, status?: number, context?: Record<string, unknown> | undefined): ZerotalError
+  readonly code: string
+  readonly context?: Record<string, unknown> | undefined
+  readonly status: number
+}
+
+interface BootCheckFailure = {
+  provider: string
+  reason: string
+  token: string
+}
+
 ## ./facades  `(./src/facade/facades/index.ts)`
 
 const App = {    readonly container: Container;    readonly instance: () => Application;    readonly environment: () => Application['environment'];    readonly isProduction: () => boolean;    readonly isLocal: () => boolean;    readonly make: <T>(token: BindingToken<T>, consumer?: unknown) => Promise<T>;    readonly makeSync: <T>(token: BindingToken<T>) => T;    readonly build: <T>(ctor: new (...args: unknown[]) => T) => Promise<T>;    readonly tryMake: <K extends keyof ContainerBindings>(token: K) => ContainerBindings[K] | undefined;    readonly bound: (token: BindingToken) => boolean;    readonly bind: <T>(token: BindingToken<T>, factory: Factory<T>) => Container;    readonly singleton: <T>(token: BindingToken<T>, factory: Factory<T>) => Container;    readonly scoped: <T>(token: BindingToken<T>, factory: Factory<T>) => Container;    readonly value: <T>(token: BindingToken<T>, instance: T) => Container;    readonly alias: (from: unknown, to: unknown) => Container;    readonly forget: (token: BindingToken) => boolean;}
@@ -2995,7 +3197,7 @@ interface WebContext = {
   view: (markup: string | {    toString(): string;}, status?: number) => void
 }
 
-type AnsiColor = 'cyan' | 'yellow' | 'green' | 'blue' | 'red' | 'dim'
+type AnsiColor = 'red' | 'green' | 'yellow' | 'blue' | 'cyan' | 'dim'
 
 type Channel = 'web' | 'json' | 'cli'
 
@@ -3256,11 +3458,11 @@ interface LoggingConfigShape = {
   slowQueryMs?: number
 }
 
-type ChannelConfig = {    driver: 'console';    level?: LogLevel;    format?: 'json' | 'pretty';} | {    driver: 'single';    level?: LogLevel;    path: string;} | {    driver: 'daily';    level?: LogLevel;    path: string;    days?: number;} | {    driver: 'stack';    level?: LogLevel;    channels: string[];} | {    driver: 'null';}
+type ChannelConfig = { driver: 'console'; level?: LogLevel; format?: 'json' | 'pretty' } | { driver: 'single'; level?: LogLevel; path: string } | { driver: 'daily'; level?: LogLevel; path: string; days?: number } | { driver: 'stack'; level?: LogLevel; channels: string[] } | { driver: 'null' }
 
-type LogLevel = 'error' | 'info' | 'warn' | 'debug' | 'fatal'
+type LogLevel = 'debug' | 'info' | 'warn' | 'error' | 'fatal'
 
-type TableData = Record<string, unknown> | readonly Record<string, unknown>[]
+type TableData = Record<string, unknown> | ReadonlyArray<Record<string, unknown>>
 
 ## ./macros/config  `(./src/macros/config.macro.ts)`
 
@@ -3294,14 +3496,37 @@ interface HttpMetricsSnapshot = {
 
 const route = RouteBuilder
 
+function action = <N extends RouteTarget>(name: N, params?: RouteParamValues | undefined, query?: RouteQuery | undefined) => RouteAction
+
+function defineRouteMethods = (table: Readonly<Record<string, string>>) => void
+
 function defineRoutes = (table: RouteTable) => void
 
 function hasRoute = (name: string) => boolean
 
 function resetRoutes = () => void
 
+function routeMethod = (name: string) => string | undefined
+
+interface RouteAction = {
+  method: string
+  url: string
+}
+
+interface RouteMethodRegistry = {}
+
+type MethodedRouteName = never
+
+type RouteArgs = [params?: RouteParamValues, query?: RouteQuery]
+
+type RouteParamValues = {    [x: string]: RouteParamValue | readonly RouteParamValue[];}
+
+type RouteQuery = {    [x: string]: string | number | boolean | readonly (string | number | boolean)[] | null | undefined;}
+
 type RouteTable = Readonly<Record<string, string>> | ReadonlyMap<string, string>
 
+type RouteTarget = string
+
 ## ./security  `(./src/security/index.ts)`
 
 class CryptKeyMissingError = {
@@ -3339,7 +3564,7 @@ interface RedactGraphOptions = {
   tooDeep: string
 }
 
-type HashAlgorithm = 'bcrypt' | 'argon2id' | 'argon2i' | 'argon2d'
+type HashAlgorithm = 'argon2id' | 'argon2i' | 'argon2d' | 'bcrypt'
 
 ## ./storage  `(./src/storage/index.ts)`
 

package/package.json

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

package/src/command/builtin/MakeCommandCommand.ts

@@ -14,8 +14,8 @@ export function toKebab(name: string): string {
 
 /** Source for a new CLI command class extending `Command`. */
 export function commandStub(name: string): string {
-  return `import { Command } from '@zerotal/core';
-import type { ArgDef, FlagDef } from '@zerotal/core';
+  return `import { Command } from 'zerotal';
+import type { ArgDef, FlagDef } from 'zerotal';
 
 export class ${name} extends Command {
   static commandName = '${toKebab(name)}';

package/src/command/builtin/MakeControllerCommand.ts

@@ -5,7 +5,7 @@ import { Command } from "../Command.ts";
 
 /** Source for a minimal controller with a single `index` action. */
 export function basicStub(name: string): string {
-  return `import type { HttpContext } from '@zerotal/core';
+  return `import type { HttpContext } from 'zerotal';
 
 export class ${name} {
   async index(ctx: HttpContext): Promise<void> {
@@ -17,7 +17,7 @@ export class ${name} {
 
 /** Source for a resourceful controller with full CRUD action stubs. */
 export function resourceStub(name: string): string {
-  return `import type { HttpContext } from '@zerotal/core';
+  return `import type { HttpContext } from 'zerotal';
 
 export class ${name} {
   async index(ctx: HttpContext): Promise<void> {

package/src/command/builtin/MakeJobCommand.ts

@@ -27,7 +27,7 @@ export class MakeJobCommand extends Command {
     }
     await Bun.write(
       path,
-      `import { Job, JobRegistry } from '@zerotal/queue';
+      `import { Job, JobRegistry } from 'zerotal/queue';
 
 export class ${name} extends Job {
   readonly queue = 'default';

package/src/command/builtin/MakeMiddlewareCommand.ts

@@ -5,7 +5,7 @@ import { Command } from "../Command.ts";
 
 /** Source for a pass-through middleware class implementing `Pipe<HttpContext>`. */
 export function middlewareStub(name: string): string {
-  return `import type { HttpContext, Pipe, NextFn } from '@zerotal/core';
+  return `import type { HttpContext, Pipe, NextFn } from 'zerotal';
 
 export class ${name} implements Pipe<HttpContext> {
   async handle(ctx: HttpContext, next: NextFn): Promise<Response | void> {

package/src/command/builtin/MakeObserverCommand.ts

@@ -47,7 +47,7 @@ export class MakeObserverCommand extends Command {
 }
 
 function _stub(name: string, model: string): string {
-  return `import type { ModelObserver } from '@zerotal/orm';
+  return `import type { ModelObserver } from 'zerotal/orm';
 
 export class ${name} implements ModelObserver {
   creating(${model.toLowerCase()}: Record<string, unknown>): void {

package/src/command/builtin/MakePolicyCommand.ts

@@ -41,7 +41,7 @@ export class MakePolicyCommand extends Command {
 
 /** Source for a new authorization policy class extending `Policy`. */
 export function policyStub(name: string, model: string): string {
-  return `import { Policy } from '@zerotal/auth';
+  return `import { Policy } from 'zerotal/auth';
 // import type { ${model} } from '../models/${model}.ts';
 // import type { User } from '../models/User.ts';
 

package/src/command/builtin/MakeProviderCommand.ts

@@ -6,7 +6,7 @@ import { Command } from "../Command.ts";
 import { registerProvider } from "../../build/codemod.ts";
 
 function providerStub(name: string): string {
-  return `import { ServiceProvider } from '@zerotal/core';
+  return `import { ServiceProvider } from 'zerotal';
 
 export class ${name} extends ServiceProvider {
   override onRegister(): void {

package/src/command/builtin/MakeRequestCommand.ts

@@ -31,13 +31,23 @@ export class MakeRequestCommand extends Command {
   }
 }
 
+// Two things this stub deliberately does not do.
+//
+// It imports from `zerotal/validator`, not `@zerotal/validator`: a scaffolded app
+// depends on the umbrella, so the scoped name resolves to nothing and the file it
+// just generated does not compile.
+//
+// And it leaves `rules()` unannotated. `validate()` reads the narrow return type
+// through `ReturnType<T['rules']>`, so writing `Record<string, FieldRule>` there
+// widens it back and every validated field arrives as `unknown` — silently, with
+// the first sign a cast somewhere downstream. `FormRequest`'s own docblock says
+// so; the generator used to emit exactly what it warns against.
 function stub(name: string): string {
-  return `import { FormRequest } from '@zerotal/validator';
-import type { RuleBuilder }  from '@zerotal/validator';
-import type { FieldRule }    from '@zerotal/validator';
+  return `import { FormRequest } from 'zerotal/validator';
+import type { RuleBuilder } from 'zerotal/validator';
 
 export class ${name} extends FormRequest {
-  rules(r: RuleBuilder): Record<string, FieldRule> {
+  rules(r: RuleBuilder) {
     return {
       // example: title: r.string().min(3).max(255),
     };

package/src/command/builtin/MakeResourceCommand.ts

@@ -35,8 +35,8 @@ export class MakeResourceCommand extends Command {
 function _stub(name: string): string {
   const model = name.replace(/Resource$/, "");
   const snake = model.replace(/([A-Z])/g, (char, index) => (index ? "-" : "") + char.toLowerCase());
-  return `import { Resource, ResourceCollection } from '@zerotal/core';
-import type { PaginatedData } from '@zerotal/core';
+  return `import { Resource, ResourceCollection } from 'zerotal/http';
+import type { PaginatedData } from 'zerotal/http';
 
 export class ${name} extends Resource<${model}> {
   toArray(): Record<string, unknown> {

package/src/command/builtin/MakeTestCommand.ts

@@ -11,8 +11,8 @@ export function featureTestStub(name: string): string {
   // edit rather than one you have to rewrite.
   const resource = pluralize(subject.toLowerCase());
   return `import { describe, it, beforeAll, afterAll } from 'bun:test';
-import { migrateDatabase, refreshDatabase, assertDatabaseHas } from '@zerotal/testing';
-import type { TestApp } from '@zerotal/testing';
+import { migrateDatabase, refreshDatabase, assertDatabaseHas } from 'zerotal/testing';
+import type { TestApp } from 'zerotal/testing';
 import { createApp } from '../helpers.ts';
 
 let app: TestApp;

package/src/router/routes.ts

@@ -197,10 +197,16 @@ export const route: RouteBuilder = Object.assign(
 /**
  * Augmented by `types/routes.generated.ts` with the HTTP method of every named
  * route, exactly as {@link RouteRegistry} is augmented with their patterns.
+ *
+ * @internal The generator writes the augmentation; an app never names this.
  */
 export interface RouteMethodRegistry {}
 
-/** A name the generated table knows a verb for. */
+/**
+ * A name the generated table knows a verb for.
+ *
+ * @internal Derived from {@link RouteMethodRegistry}, which the generator owns.
+ */
 export type MethodedRouteName = Extract<keyof RouteMethodRegistry, string>;
 
 const methodTable = new Map<string, string>();
@@ -217,7 +223,11 @@ export function defineRouteMethods(table: Readonly<Record<string, string>>): voi
   for (const [name, method] of Object.entries(table)) methodTable.set(name, method);
 }
 
-/** The verb a named route answers on, or undefined when it was never registered. */
+/**
+ * The verb a named route answers on, or undefined when it was never registered.
+ *
+ * @internal The read side of {@link defineRouteMethods}; apps call `action()`.
+ */
 export function routeMethod(name: string): string | undefined {
   return methodTable.get(name);
 }