zudojs-cli 2.0.1 → 2.1.0

package/dist/src/recipes/catalog/platform/cache.recipe.js

@@ -0,0 +1,55 @@
+/**
+ * zudojs-cli — `zudojs add cache`: an in-memory cache (@zudojs/cache) with
+ * a bounded entry count and a default TTL from the environment.
+ */
+import { zudojsDependencies } from "../../../constants/index.js";
+const source = () => `import {
+  createCacheService,
+  createMemoryCacheAdapter,
+  type CacheService,
+} from "@zudojs/cache";
+
+import type { Integration } from "./integration.js";
+
+let service: CacheService | undefined;
+
+/** The cache. Throws before the runtime has started. */
+export function cache(): CacheService {
+  if (service === undefined) {
+    throw new Error("The cache is not ready: start the runtime first.");
+  }
+  return service;
+}
+
+export const cacheIntegration: Integration = {
+  name: "cache",
+
+  async start({ config }) {
+    service = createCacheService({
+      adapter: createMemoryCacheAdapter({ maxEntries: config.cache.maxEntries }),
+      config: { defaultTtl: config.cache.defaultTtlMs },
+    });
+  },
+
+  async stop() {
+    service = undefined;
+  },
+
+  async health() {
+    return service !== undefined;
+  },
+};
+`;
+export const cacheRecipe = {
+    scope: "app",
+    feature: "cache",
+    summary: "In-memory cache (src/integrations/cache.ts)",
+    dependencies: zudojsDependencies(["@zudojs/cache"]),
+    env: () => [
+        { name: "CACHE_MAX_ENTRIES", value: "10000" },
+        { name: "CACHE_DEFAULT_TTL_MS", value: "60000" },
+    ],
+    configSection: `cache: Object.freeze({ maxEntries: int(config, "cache_max_entries", 10_000), defaultTtlMs: int(config, "cache_default_ttl_ms", 60_000) }),`,
+    integration: { file: "cache.ts", exportName: "cacheIntegration", source },
+};
+//# sourceMappingURL=cache.recipe.js.map

package/dist/src/recipes/catalog/platform/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * zudojs-cli — Recipes backed by @zudojs platform packages.
+ */
+export { cacheRecipe } from "./cache.recipe.js";
+export { messagingRecipe } from "./messaging.recipe.js";
+export { observabilityRecipe } from "./observability.recipe.js";
+export { queueRecipe } from "./queue.recipe.js";
+export { schedulerRecipe } from "./scheduler.recipe.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/src/recipes/catalog/platform/index.js

@@ -0,0 +1,9 @@
+/**
+ * zudojs-cli — Recipes backed by @zudojs platform packages.
+ */
+export { cacheRecipe } from "./cache.recipe.js";
+export { messagingRecipe } from "./messaging.recipe.js";
+export { observabilityRecipe } from "./observability.recipe.js";
+export { queueRecipe } from "./queue.recipe.js";
+export { schedulerRecipe } from "./scheduler.recipe.js";
+//# sourceMappingURL=index.js.map

package/dist/src/recipes/catalog/platform/messaging.recipe.d.ts

@@ -0,0 +1,7 @@
+/**
+ * zudojs-cli — `zudojs add messaging`: an in-process message bus
+ * (@zudojs/messaging), disposed on stop.
+ */
+import type { AppRecipe } from "../../recipe.type.js";
+export declare const messagingRecipe: AppRecipe;
+//# sourceMappingURL=messaging.recipe.d.ts.map

package/dist/src/recipes/catalog/platform/messaging.recipe.js

@@ -0,0 +1,46 @@
+/**
+ * zudojs-cli — `zudojs add messaging`: an in-process message bus
+ * (@zudojs/messaging), disposed on stop.
+ */
+import { zudojsDependencies } from "../../../constants/index.js";
+const source = () => `import { createMessageBus } from "@zudojs/messaging";
+
+import type { Integration } from "./integration.js";
+
+type MessageBus = ReturnType<typeof createMessageBus>;
+
+let bus: MessageBus | undefined;
+
+/** The message bus. Throws before the runtime has started. */
+export function messages(): MessageBus {
+  if (bus === undefined) {
+    throw new Error("The message bus is not running: start the runtime first.");
+  }
+  return bus;
+}
+
+export const messagingIntegration: Integration = {
+  name: "messaging",
+
+  async start() {
+    bus = createMessageBus();
+  },
+
+  async stop() {
+    bus?.dispose();
+    bus = undefined;
+  },
+
+  async health() {
+    return bus !== undefined;
+  },
+};
+`;
+export const messagingRecipe = {
+    scope: "app",
+    feature: "messaging",
+    summary: "In-process message bus (src/integrations/messaging.ts)",
+    dependencies: zudojsDependencies(["@zudojs/messaging"]),
+    integration: { file: "messaging.ts", exportName: "messagingIntegration", source },
+};
+//# sourceMappingURL=messaging.recipe.js.map

package/dist/src/recipes/catalog/platform/observability.recipe.d.ts

@@ -0,0 +1,8 @@
+/**
+ * zudojs-cli — `zudojs add observability`: logger, metrics and tracer
+ * (@zudojs/observability), flushed and shut down on stop. Console
+ * exporters are on outside production.
+ */
+import type { AppRecipe } from "../../recipe.type.js";
+export declare const observabilityRecipe: AppRecipe;
+//# sourceMappingURL=observability.recipe.d.ts.map

package/dist/src/recipes/catalog/platform/observability.recipe.js

@@ -0,0 +1,49 @@
+/**
+ * zudojs-cli — `zudojs add observability`: logger, metrics and tracer
+ * (@zudojs/observability), flushed and shut down on stop. Console
+ * exporters are on outside production.
+ */
+import { zudojsDependencies } from "../../../constants/index.js";
+const source = () => `import { createObservability } from "@zudojs/observability";
+
+import type { Integration } from "./integration.js";
+
+type Observability = ReturnType<typeof createObservability>;
+
+let instance: Observability | undefined;
+
+/** Logger, metrics and tracer. Throws before the runtime has started. */
+export function observability(): Observability {
+  if (instance === undefined) {
+    throw new Error("Observability is not started: start the runtime first.");
+  }
+  return instance;
+}
+
+export const observabilityIntegration: Integration = {
+  name: "observability",
+
+  async start({ config }) {
+    instance = createObservability({
+      serviceName: config.observability.serviceName,
+      environment: config.nodeEnv,
+      useConsoleExporters: config.nodeEnv !== "production",
+    });
+  },
+
+  async stop() {
+    await instance?.shutdown();
+    instance = undefined;
+  },
+};
+`;
+export const observabilityRecipe = {
+    scope: "app",
+    feature: "observability",
+    summary: "Metrics, tracing and structured logs (src/integrations/observability.ts)",
+    dependencies: zudojsDependencies(["@zudojs/observability"]),
+    env: (context) => [{ name: "SERVICE_NAME", value: context.projectSlug }],
+    configSection: `observability: Object.freeze({ serviceName: text(config, "service_name", "app") }),`,
+    integration: { file: "observability.ts", exportName: "observabilityIntegration", source },
+};
+//# sourceMappingURL=observability.recipe.js.map

package/dist/src/recipes/catalog/platform/queue.recipe.d.ts

@@ -0,0 +1,7 @@
+/**
+ * zudojs-cli — `zudojs add queue`: an in-process job queue (@zudojs/queue)
+ * with an example processor; closed (draining in-flight jobs) on stop.
+ */
+import type { AppRecipe } from "../../recipe.type.js";
+export declare const queueRecipe: AppRecipe;
+//# sourceMappingURL=queue.recipe.d.ts.map

package/dist/src/recipes/catalog/platform/queue.recipe.js

@@ -0,0 +1,61 @@
+/**
+ * zudojs-cli — `zudojs add queue`: an in-process job queue (@zudojs/queue)
+ * with an example processor; closed (draining in-flight jobs) on stop.
+ */
+import { zudojsDependencies } from "../../../constants/index.js";
+const source = () => `import { createInMemoryQueue, createQueueName } from "@zudojs/queue";
+
+import type { Integration } from "./integration.js";
+
+/** Payload of the jobs this app queues. */
+export type JobData = Readonly<Record<string, unknown>>;
+
+type JobQueue = ReturnType<typeof createInMemoryQueue<JobData>>;
+
+let queue: JobQueue | undefined;
+
+/** The job queue. Throws before the runtime has started. */
+export function jobs(): JobQueue {
+  if (queue === undefined) {
+    throw new Error("The job queue is not running: start the runtime first.");
+  }
+  return queue;
+}
+
+export const queueIntegration: Integration = {
+  name: "queue",
+
+  async start({ config, logger }) {
+    queue = createInMemoryQueue<JobData>(createQueueName("jobs"), {
+      concurrency: config.queue.concurrency,
+      logger: {
+        info: (message, data) => logger.info(message, data),
+        error: (message, data) => logger.error(message, data),
+      },
+    });
+    // Example processor: add yours, then queue work with jobs().add("log", { ... }).
+    queue.process("log", async (job) => {
+      logger.info("Processed job", { id: job.id });
+    });
+  },
+
+  async stop() {
+    await queue?.close();
+    queue = undefined;
+  },
+
+  async health() {
+    return queue !== undefined;
+  },
+};
+`;
+export const queueRecipe = {
+    scope: "app",
+    feature: "queue",
+    summary: "In-process job queue (src/integrations/queue.ts)",
+    dependencies: zudojsDependencies(["@zudojs/queue"]),
+    env: () => [{ name: "QUEUE_CONCURRENCY", value: "5" }],
+    configSection: `queue: Object.freeze({ concurrency: int(config, "queue_concurrency", 5) }),`,
+    integration: { file: "queue.ts", exportName: "queueIntegration", source },
+};
+//# sourceMappingURL=queue.recipe.js.map

package/dist/src/recipes/catalog/platform/scheduler.recipe.d.ts

@@ -0,0 +1,7 @@
+/**
+ * zudojs-cli — `zudojs add scheduler`: a cron scheduler (@zudojs/scheduler)
+ * with an example job; in-flight jobs are aborted and awaited on stop.
+ */
+import type { AppRecipe } from "../../recipe.type.js";
+export declare const schedulerRecipe: AppRecipe;
+//# sourceMappingURL=scheduler.recipe.d.ts.map

package/dist/src/recipes/catalog/platform/scheduler.recipe.js

@@ -0,0 +1,56 @@
+/**
+ * zudojs-cli — `zudojs add scheduler`: a cron scheduler (@zudojs/scheduler)
+ * with an example job; in-flight jobs are aborted and awaited on stop.
+ */
+import { zudojsDependencies } from "../../../constants/index.js";
+const source = () => `import { Scheduler } from "@zudojs/scheduler";
+
+import type { Integration } from "./integration.js";
+
+let scheduler: Scheduler | undefined;
+
+/** The scheduler. Throws before the runtime has started. */
+export function schedules(): Scheduler {
+  if (scheduler === undefined) {
+    throw new Error("The scheduler is not running: start the runtime first.");
+  }
+  return scheduler;
+}
+
+export const schedulerIntegration: Integration = {
+  name: "scheduler",
+
+  async start({ logger }) {
+    scheduler = new Scheduler({
+      onError: ({ jobId, error }) => logger.error("Scheduled job failed", { jobId, error }),
+    });
+    // Example job: replace with yours.
+    scheduler.define({
+      id: "heartbeat",
+      name: "Heartbeat",
+      handler: async () => {
+        logger.debug("Scheduler heartbeat");
+      },
+    });
+    scheduler.cron("*/5 * * * *", "heartbeat", { timezone: "UTC" });
+    scheduler.start();
+  },
+
+  async stop() {
+    await scheduler?.stop({ timeoutMs: 10_000 });
+    scheduler = undefined;
+  },
+
+  async health() {
+    return scheduler !== undefined;
+  },
+};
+`;
+export const schedulerRecipe = {
+    scope: "app",
+    feature: "scheduler",
+    summary: "Cron scheduler (src/integrations/scheduler.ts)",
+    dependencies: zudojsDependencies(["@zudojs/scheduler"]),
+    integration: { file: "scheduler.ts", exportName: "schedulerIntegration", source },
+};
+//# sourceMappingURL=scheduler.recipe.js.map

package/dist/src/recipes/catalog/redis.recipe.d.ts

@@ -0,0 +1,8 @@
+/**
+ * zudojs-cli — `zudojs add redis`: a node-redis client with config from
+ * REDIS_URL, connected on start (failing fast when Redis is unreachable),
+ * reconnecting afterwards, with a PING health check.
+ */
+import type { AppRecipe } from "../recipe.type.js";
+export declare const redisRecipe: AppRecipe;
+//# sourceMappingURL=redis.recipe.d.ts.map

package/dist/src/recipes/catalog/redis.recipe.js

@@ -0,0 +1,79 @@
+/**
+ * zudojs-cli — `zudojs add redis`: a node-redis client with config from
+ * REDIS_URL, connected on start (failing fast when Redis is unreachable),
+ * reconnecting afterwards, with a PING health check.
+ */
+import { DEPENDENCY_VERSION_RANGES } from "../../resolvers/dependency/dependencyVersions.constant.js";
+const source = () => `import { createClient } from "redis";
+
+import type { Integration } from "./integration.js";
+
+/** Connection attempts before start() gives up on an unreachable server. */
+const STARTUP_ATTEMPTS = 5;
+
+/**
+ * Creates the client. Reconnects forever once connected, but gives up
+ * after STARTUP_ATTEMPTS while \`isStarting()\` so start() fails fast.
+ */
+function createRedisClient(url: string, isStarting: () => boolean) {
+  return createClient({
+    url,
+    socket: {
+      connectTimeout: 5_000,
+      reconnectStrategy: (retries: number, cause: Error) =>
+        isStarting() && retries >= STARTUP_ATTEMPTS ? cause : Math.min(retries * 200, 3_000),
+    },
+  });
+}
+
+type RedisClient = ReturnType<typeof createRedisClient>;
+
+let client: RedisClient | undefined;
+
+/** The connected Redis client. Throws before the runtime has started. */
+export function redis(): RedisClient {
+  if (client === undefined) {
+    throw new Error("Redis is not connected: start the runtime first.");
+  }
+  return client;
+}
+
+export const redisIntegration: Integration = {
+  name: "redis",
+
+  async start({ config, logger }) {
+    let connected = false;
+    const next = createRedisClient(config.redis.url, () => !connected);
+    next.on("error", (error: unknown) => {
+      logger.error("Redis connection error", { error });
+    });
+    await next.connect();
+    connected = true;
+    client = next;
+  },
+
+  async stop() {
+    const current = client;
+    client = undefined;
+    if (current?.isOpen) await current.close();
+  },
+
+  async health() {
+    if (client === undefined || !client.isReady) return false;
+    return (await client.ping()) === "PONG";
+  },
+};
+`;
+export const redisRecipe = {
+    scope: "app",
+    feature: "redis",
+    summary: "Redis client (src/integrations/redis.ts) with a health check",
+    dependencies: { redis: DEPENDENCY_VERSION_RANGES.redis },
+    env: () => [{ name: "REDIS_URL", value: "redis://localhost:6379" }],
+    configSection: `redis: Object.freeze({ url: text(config, "redis_url", "redis://localhost:6379") }),`,
+    integration: { file: "redis.ts", exportName: "redisIntegration", source },
+    nextSteps: () => [
+        `Use it anywhere after start: import { redis } from "./integrations/redis.js"; await redis().set("key", "value");`,
+    ],
+};
+//# sourceMappingURL=redis.recipe.js.map

package/dist/src/recipes/catalog/storage.recipe.d.ts

@@ -0,0 +1,7 @@
+/**
+ * zudojs-cli — `zudojs add storage`: object storage on the local disk
+ * (@zudojs/storage `LocalObjectStorage`) under STORAGE_DIRECTORY.
+ */
+import type { AppRecipe } from "../recipe.type.js";
+export declare const storageRecipe: AppRecipe;
+//# sourceMappingURL=storage.recipe.d.ts.map

package/dist/src/recipes/catalog/storage.recipe.js

@@ -0,0 +1,49 @@
+/**
+ * zudojs-cli — `zudojs add storage`: object storage on the local disk
+ * (@zudojs/storage `LocalObjectStorage`) under STORAGE_DIRECTORY.
+ */
+import { zudojsDependencies } from "../../constants/index.js";
+const source = () => `import { mkdir } from "node:fs/promises";
+
+import { LocalObjectStorage } from "@zudojs/storage";
+
+import type { Integration } from "./integration.js";
+
+let storage: LocalObjectStorage | undefined;
+
+/** The object store. Throws before the runtime has started. */
+export function objectStorage(): LocalObjectStorage {
+  if (storage === undefined) {
+    throw new Error("Object storage is not ready: start the runtime first.");
+  }
+  return storage;
+}
+
+export const storageIntegration: Integration = {
+  name: "storage",
+
+  async start({ config }) {
+    await mkdir(config.storage.directory, { recursive: true });
+    storage = new LocalObjectStorage(config.storage.directory);
+  },
+
+  async stop() {
+    storage = undefined;
+  },
+
+  async health() {
+    return storage !== undefined;
+  },
+};
+`;
+export const storageRecipe = {
+    scope: "app",
+    feature: "storage",
+    summary: "Local object storage (src/integrations/storage.ts)",
+    dependencies: zudojsDependencies(["@zudojs/storage"]),
+    env: () => [{ name: "STORAGE_DIRECTORY", value: "./.data/storage" }],
+    configSection: `storage: Object.freeze({ directory: text(config, "storage_directory", "./.data/storage") }),`,
+    integration: { file: "storage.ts", exportName: "storageIntegration", source },
+    gitignore: () => [".data/"],
+};
+//# sourceMappingURL=storage.recipe.js.map

package/dist/src/recipes/catalog/websockets.recipe.d.ts

@@ -0,0 +1,10 @@
+/**
+ * zudojs-cli — `zudojs add websockets`: a `ws` WebSocketServer attached to
+ * the app's HTTP server at WEBSOCKET_PATH. Browser connections are only
+ * accepted from CORS_ORIGINS (cross-site WebSocket hijacking), messages
+ * are capped at 64 KiB, and open sockets are closed with 1001 when
+ * shutdown begins so the HTTP server can stop.
+ */
+import type { AppRecipe } from "../recipe.type.js";
+export declare const websocketsRecipe: AppRecipe;
+//# sourceMappingURL=websockets.recipe.d.ts.map

package/dist/src/recipes/catalog/websockets.recipe.js

@@ -0,0 +1,84 @@
+/**
+ * zudojs-cli — `zudojs add websockets`: a `ws` WebSocketServer attached to
+ * the app's HTTP server at WEBSOCKET_PATH. Browser connections are only
+ * accepted from CORS_ORIGINS (cross-site WebSocket hijacking), messages
+ * are capped at 64 KiB, and open sockets are closed with 1001 when
+ * shutdown begins so the HTTP server can stop.
+ */
+import { DEPENDENCY_VERSION_RANGES } from "../../resolvers/dependency/dependencyVersions.constant.js";
+const source = () => `import { WebSocketServer, type WebSocket } from "ws";
+
+import type { Integration } from "./integration.js";
+
+let server: WebSocketServer | undefined;
+
+/** The WebSocket server. Throws before the runtime has started. */
+export function websockets(): WebSocketServer {
+  if (server === undefined) {
+    throw new Error("The WebSocket server is not running: start the runtime first.");
+  }
+  return server;
+}
+
+/** Sends \`data\` to every open connection. */
+export function broadcast(data: string): void {
+  for (const socket of websockets().clients) {
+    if (socket.readyState === socket.OPEN) socket.send(data);
+  }
+}
+
+export const websocketsIntegration: Integration = {
+  name: "websockets",
+
+  async start({ config, httpServer, logger }) {
+    if (httpServer === undefined) {
+      throw new Error("WebSockets need the HTTP server: pass httpServer to createApp().");
+    }
+    const allowed = new Set(config.corsOrigins);
+    server = new WebSocketServer({
+      server: httpServer,
+      path: config.websockets.path,
+      maxPayload: 64 * 1024,
+      // A browser always sends Origin; refuse pages from origins not in
+      // CORS_ORIGINS. Clients without Origin are not browsers.
+      verifyClient: ({ origin }: { origin?: string }) =>
+        origin === undefined || origin === "" || allowed.has(origin),
+    });
+    server.on("connection", (socket: WebSocket) => {
+      socket.on("error", (error: Error) => logger.warn("WebSocket error", { error }));
+      // Example handler: echo each message back. Replace with your protocol.
+      socket.on("message", (data) => socket.send(data.toString()));
+    });
+  },
+
+  async drain() {
+    for (const socket of server?.clients ?? []) socket.close(1001, "Server shutting down");
+  },
+
+  async stop() {
+    const current = server;
+    server = undefined;
+    if (current === undefined) return;
+    for (const socket of current.clients) socket.terminate();
+    await new Promise<void>((resolve) => current.close(() => resolve()));
+  },
+
+  async health() {
+    return server !== undefined;
+  },
+};
+`;
+export const websocketsRecipe = {
+    scope: "app",
+    feature: "websockets",
+    summary: "WebSocket server attached to the HTTP server (src/integrations/websockets.ts)",
+    dependencies: { ws: DEPENDENCY_VERSION_RANGES.ws },
+    devDependencies: { "@types/ws": DEPENDENCY_VERSION_RANGES["@types/ws"] },
+    env: () => [{ name: "WEBSOCKET_PATH", value: "/ws" }],
+    configSection: `websockets: Object.freeze({ path: text(config, "websocket_path", "/ws") }),`,
+    integration: { file: "websockets.ts", exportName: "websocketsIntegration", source },
+    nextSteps: () => [
+        `Connect to ws://localhost:<PORT>/ws; browsers must be on an origin listed in CORS_ORIGINS.`,
+    ],
+};
+//# sourceMappingURL=websockets.recipe.js.map

package/dist/src/recipes/docker/docker.compose.d.ts

@@ -0,0 +1,19 @@
+/**
+ * zudojs-cli — `compose.yaml` for `zudojs add docker`.
+ *
+ * One service per backend app plus one per enabled integration that needs
+ * a server: `postgres` (database), `redis` and `mailpit` (email, SMTP on
+ * 1025, web UI on 8025). Backing services publish on 127.0.0.1 only, and
+ * the Postgres password is read from `.env` (POSTGRES_PASSWORD): compose
+ * refuses to start without it, so no credential is written into the file.
+ */
+import type { ProjectRecipeContext } from "../recipe.type.js";
+/**
+ * Whether compose runs a `postgres` service. The `database` capability is
+ * recorded for MySQL and SQLite projects too, which used to get a Postgres
+ * container and a DATABASE_URL overriding their own.
+ */
+export declare function usesPostgres(context: ProjectRecipeContext): boolean;
+/** Renders `compose.yaml`. */
+export declare function renderComposeFile(context: ProjectRecipeContext): string;
+//# sourceMappingURL=docker.compose.d.ts.map