@getstrata/cli 2.1.0 → 2.2.1

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # @getstrata/cli changelog
 
+## 2.2.1
+
+F02 — complete queue durability. Queues have leased reservations, recovery and fenced acknowledgement, but still use Redis lists. Persisted retry schedules, execution deadlines, cancellation and the planned Streams migration remain unfinished. Retries currently wait inside the running worker.
+F10 — production public-route tenancy. Separate anonymous access from development tenant headers, support a trusted-host resolver, reject unknown hosts, and accept forwarded hosts only through configured trusted proxies. The shop still lacks the approved-domain mapping.
+F12 — initial administrator provisioning and migration guidance. Automatic demo seeding is fixed. Secure initial-admin provisioning and a consolidated upgrade/operations guide remain.
+Distributed qualification. Cache generations/fill leases, scheduler ownership, OpenTelemetry, body limits and lifecycle controls now exist. Their implementation should no longer be described as entirely pending, but broader failure and capacity qualification is still required.
+
+## 2.2.0
+
+Consistent model scopes.
+Changed-field model writes.
+Awaited provider startup.
+Shared cache correctness.
+Native HTTP controls and body limits.
+Graceful lifecycle.
+Validated async discovery.
+Stronger model input types.
+OpenTelemetry tracing.
+Distributed scheduler ownership.
+App-owned quota policy.
+Bounded memory throttling.
+
 ## 2.1.0
 
 - refactor(starter): reuse shared config and base repositories - fix(database): await password casts before model writes - fix(database): preserve concrete model types in query results
@@ -48,6 +70,8 @@
 
 ## Unreleased
 
+- Await queue/scheduler application startup and close resources after failed startup or completed work; preserve original failures when cleanup also fails.
+
 - 2.0: migrations no longer implicitly call an app seed export. Seeding requires --seed; fresh accepts the same explicit flag. Missing seed exports are rejected before applying migrations or resetting data.
 
 ## 1.1.9

package/README.md

@@ -19,7 +19,7 @@ strata help
 
 `strata start` does not migrate when `APP_ENV=production`. Run `strata migrate` as an explicit deploy step.
 
-App commands from `src/cli/register.ts` merge with this list. Generated apps add `queue:work`, failed-job commands, `make:*`, `openapi:*`, and `schedule:run`.
+App commands from `src/cli/register.ts` merge with this list. Generated apps add `queue:work`, failed-job commands, `make:*`, `openapi:*`, and `schedule:run`. User-auth starters also add explicit `auth:provision-admin`; its `initialAdmin` subpath reads bounded password input from a pipe and redacts provisioning errors. The app owns its transactional one-time claim and user schema. See [initial-admin provisioning](https://github.com/EyK-26/strata/blob/main/docs/INITIAL-ADMIN.md) before adoption.
 
 ## Running it
 
@@ -51,7 +51,7 @@ From the current working directory, `strata` loads `strata.config.ts` if present
 | `migrate` | `src/db/migrate.ts` |
 | `fresh` | `src/db/fresh.ts` |
 
-`src/cli/register.ts` can export `commands` or `registerCommands()` to add your own commands. Generated apps ship `queue:work`, which boots the app (`bootstrapApp` / `createApp`) rather than the monorepo provider stack, plus `make:*`, failed-job commands, `openapi:*`, and `schedule:run`.
+`src/cli/register.ts` can export `commands` or `registerCommands()` to add your own commands. Generated apps ship `queue:work`, which boots the app (`bootstrapApp` / `createApp`) rather than the monorepo provider stack, plus `make:*`, failed-job commands, `openapi:*`, and `schedule:run`. User-auth starters also add explicit `auth:provision-admin`; its `initialAdmin` subpath reads bounded password input from a pipe and redacts provisioning errors. The app owns its transactional one-time claim and user schema. See [initial-admin provisioning](https://github.com/EyK-26/strata/blob/main/docs/INITIAL-ADMIN.md) before adoption.
 
 Helpers live on package subpaths: `@getstrata/cli/queueWorker`, `@getstrata/cli/queueFailed`, `@getstrata/cli/scaffold`, `@getstrata/cli/openapi`, and `@getstrata/cli/schedule`. `queue:work` takes `{ boot, close }` and does not call `assertProductionSecrets()` (that belongs in app boot). Scaffold commands resolve paths from the app working directory (`src/modules`, `src/db/migrations`, `src/jobs`, `views/` or `resources/views`). See [docs/BUILDING-APPS.md](https://github.com/EyK-26/strata/blob/main/docs/BUILDING-APPS.md#extending-the-cli).
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@getstrata/cli",
-  "version": "2.1.0",
+  "version": "2.2.1",
   "description": "Strata CLI: framework commands for Bun apps (dev, start, migrate, run)",
   "type": "module",
   "license": "MIT",
@@ -36,6 +36,10 @@
     "./schedule": {
       "import": "./src/schedule.ts",
       "default": "./src/schedule.ts"
+    },
+    "./initialAdmin": {
+      "import": "./src/initialAdmin.ts",
+      "default": "./src/initialAdmin.ts"
     }
   },
   "files": [
@@ -46,8 +50,8 @@
   ],
   "scripts": {},
   "peerDependencies": {
-    "@getstrata/bootstrap": "^2.1.0",
-    "@getstrata/core": "^2.1.0"
+    "@getstrata/bootstrap": "^2.2.1",
+    "@getstrata/core": "^2.2.1"
   },
   "publishConfig": {
     "access": "public"

package/src/initialAdmin.ts

@@ -0,0 +1,99 @@
+import { stdin } from "node:process";
+
+type InitialAdminInput = {
+  email: string;
+  name: string;
+  password: string;
+  tenantId?: number;
+};
+
+type InitialAdminOptions = {
+  tenantRequired: boolean;
+  provision: (input: InitialAdminInput) => Promise<void>;
+  /** Trusted test/embedding input; never accept password arguments or environment defaults. */
+  input?: AsyncIterable<Uint8Array>;
+};
+
+async function runInitialAdminCommand(args: string[], options: InitialAdminOptions): Promise<void> {
+  const flags = new Map<string, string>();
+  let passwordStdin = false;
+  for (let index = 0; index < args.length; index++) {
+    const flag = args[index];
+    if (flag === "--password-stdin" && !passwordStdin) {
+      passwordStdin = true;
+    } else if (flag === "--email" || flag === "--name" || flag === "--tenant") {
+      const value = args[++index];
+      if (!value || value.startsWith("--") || flags.has(flag)) {
+        throw new Error("Initial-admin options must have one explicit value each.");
+      }
+      flags.set(flag, value);
+    } else {
+      throw new Error("Use --email, --name, --password-stdin and, for tenant apps, --tenant.");
+    }
+  }
+  const email = (flags.get("--email") ?? "").trim().toLowerCase();
+  const name = (flags.get("--name") ?? "").trim();
+  if (!/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email) || email.length > 254 || /[\p{C}]/u.test(email)) {
+    throw new Error("A valid initial-admin email is required.");
+  }
+  if (!name || name.length > 200 || /[\p{C}]/u.test(name)) {
+    throw new Error("A nonempty initial-admin name without control characters is required.");
+  }
+  const tenantRaw = flags.get("--tenant");
+  const tenantId = tenantRaw === undefined ? undefined : Number(tenantRaw);
+  if (options.tenantRequired) {
+    if (!tenantRaw || !/^[1-9]\d*$/.test(tenantRaw) || !Number.isSafeInteger(tenantId)) {
+      throw new Error("An existing positive safe-integer tenant ID is required.");
+    }
+  } else if (tenantRaw !== undefined) {
+    throw new Error("This application does not accept a tenant option.");
+  }
+  if (!passwordStdin || (!options.input && stdin.isTTY)) {
+    throw new Error(
+      "Provide --password-stdin through a pipe; interactive terminal input is refused.",
+    );
+  }
+  const chunks: Uint8Array[] = [];
+  let size = 0;
+  // Bcrypt accepts at most 72 UTF-8 bytes; allow a single terminal CRLF.
+  for await (const chunk of options.input ?? stdin) {
+    size += chunk.byteLength;
+    if (size > 74) throw new Error("Initial-admin password exceeds the supported byte limit.");
+    chunks.push(chunk);
+  }
+  const bytes = new Uint8Array(size);
+  let offset = 0;
+  for (const chunk of chunks) {
+    bytes.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  let password: string;
+  try {
+    password = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true })
+      .decode(bytes)
+      .replace(/\r?\n$/, "");
+  } catch {
+    throw new Error("Initial-admin password must be valid UTF-8.");
+  }
+  if (
+    [...password].length < 16 ||
+    new TextEncoder().encode(password).byteLength > 72 ||
+    /[\p{C}]/u.test(password) ||
+    password === "StrataDemo!ChangeMe"
+  ) {
+    throw new Error(
+      "Use a unique password of at least 16 characters and at most 72 UTF-8 bytes, without control characters or demo defaults.",
+    );
+  }
+  try {
+    await options.provision({ email, name, password, tenantId });
+  } catch {
+    // Drivers/observers can include bound values in errors. Never forward credential-bearing causes.
+    throw new Error(
+      "Initial-admin provisioning failed. Check schema, tenant, existing admins/accounts and the one-time claim; no account is promoted or overwritten.",
+    );
+  }
+}
+
+export type { InitialAdminInput, InitialAdminOptions };
+export { runInitialAdminCommand };

package/src/queueFailed.ts

@@ -1,6 +1,10 @@
-import { createFailedJobService } from "@getstrata/core/queue/createAppQueue";
+import {
+  createAppQueue,
+  createFailedJobService,
+  resolveQueueConfig,
+} from "@getstrata/core/queue/createAppQueue";
 import { jobRegistry } from "@getstrata/core/queue/jobRegistry";
-import { runQueueJob } from "@getstrata/core/queue/jobRunner";
+import { resolveApplicationQueue } from "@getstrata/core/runtime/applicationRegistry";
 import type { StrataCommand } from "./types.ts";
 
 type QueueFailedBoot = () => unknown | Promise<unknown>;
@@ -25,26 +29,30 @@ async function queueRetryCommand(id?: string, boot?: QueueFailedBoot): Promise<v
     throw new Error("queue:retry requires a failed job id.");
   }
 
+  const jobId = Number(id);
+  if (!Number.isSafeInteger(jobId) || jobId <= 0)
+    throw new Error("queue:retry requires a positive integer failed job id.");
   await boot?.();
   const failedJobs = createFailedJobService();
-  const failedJob = await failedJobs.retry(Number.parseInt(id, 10));
-
-  const job = jobRegistry.create(failedJob.job_name);
-
-  if (!job) {
-    throw new Error(`Unknown job "${failedJob.job_name}".`);
+  // App boot owns its configured queue; standalone CLI dispatch owns and closes its queue.
+  const queue = boot
+    ? resolveApplicationQueue()
+    : createAppQueue(resolveQueueConfig().driver, process.env.REDIS_URL, failedJobs);
+  try {
+    await failedJobs.retry(jobId, async (failedJob) => {
+      const job = jobRegistry.create(failedJob.job_name);
+      if (!job) throw new Error(`Unknown job "${failedJob.job_name}".`);
+      jobRegistry.track(failedJob.job_name, job);
+      if (failedJob.job_id !== null && failedJob.job_id !== undefined) {
+        if (!queue.replay)
+          throw new Error("Configured queue cannot preserve the failed-job identity");
+        await queue.replay(job, failedJob.payload, failedJob.job_id);
+      } else await queue.dispatch(job, failedJob.payload);
+    });
+    console.log(`Enqueued failed job #${jobId}.`);
+  } finally {
+    if (!boot) await queue.close?.();
   }
-
-  await runQueueJob(
-    {
-      name: failedJob.job_name,
-      payload: failedJob.payload,
-      attempts: 0,
-    },
-    failedJobs,
-  );
-
-  console.log(`Retried failed job #${id}.`);
 }
 
 async function queueFlushFailedCommand(boot?: QueueFailedBoot): Promise<void> {

package/src/queueWorker.ts

@@ -1,6 +1,6 @@
 import {
   installGracefulShutdownSignals,
-  registerShutdownHandler,
+  LifecycleCoordinator,
 } from "@getstrata/core/lifecycle/gracefulShutdown";
 import { createFailedJobService, createQueueWorker } from "@getstrata/core/queue/createAppQueue";
 
@@ -10,35 +10,91 @@ type QueueWorkerClose = () => unknown | Promise<unknown>;
 async function runQueueWorkerCommand(options: {
   boot: QueueWorkerBoot;
   close?: QueueWorkerClose;
+  flush?: QueueWorkerClose;
+  drain?: QueueWorkerClose;
+  lifecycle?: LifecycleCoordinator;
   failedJobs?: ReturnType<typeof createFailedJobService>;
 }): Promise<void> {
   const redisUrl = process.env.REDIS_URL;
-
-  if (!redisUrl) {
-    throw new Error("queue:work requires REDIS_URL to be set.");
+  if (!redisUrl) throw new Error("queue:work requires REDIS_URL to be set.");
+  const lifecycle = options.lifecycle ?? new LifecycleCoordinator();
+  if (lifecycle.isShuttingDown) throw new Error("Cannot start a worker during shutdown.");
+  let worker: ReturnType<typeof createQueueWorker> | undefined;
+  let running: Promise<void> | undefined;
+  let booting: Promise<unknown> | undefined;
+  let stopping = false;
+  const name = `queue:${crypto.randomUUID()}`;
+  lifecycle.register(
+    `${name}:stop`,
+    () => {
+      stopping = true;
+      worker?.requestStop();
+    },
+    "stop",
+  );
+  lifecycle.register(
+    `${name}:drain`,
+    async () => {
+      // Completion, including failed startup/run, means no admitted worker remains.
+      await booting?.catch(() => {});
+      await running?.catch(() => {});
+      await options.drain?.();
+    },
+    "drain",
+  );
+  lifecycle.register(
+    `${name}:flush`,
+    async () => {
+      await options.flush?.();
+    },
+    "flush",
+  );
+  lifecycle.register(
+    `${name}:close`,
+    async () => {
+      try {
+        await worker?.close?.();
+      } finally {
+        await options.close?.();
+      }
+    },
+    "close",
+  );
+  lifecycle.register(
+    `${name}:force`,
+    () => {
+      worker?.requestStop();
+      worker?.close?.();
+    },
+    "force",
+  );
+  const uninstall = installGracefulShutdownSignals(undefined, lifecycle);
+  let failure: unknown;
+  let failed = false;
+  try {
+    booting = (async () => {
+      await options.boot();
+    })();
+    await booting;
+    if (!stopping && !lifecycle.isShuttingDown) {
+      worker = createQueueWorker(redisUrl, options.failedJobs ?? createFailedJobService());
+      console.log("[queue:work] Listening for jobs on Redis...");
+      running = worker.run();
+      await running;
+      console.log("[queue:work] Worker stopped.");
+    }
+  } catch (error) {
+    failed = true;
+    failure = error;
   }
-
-  await options.boot();
-
-  const failedJobs = options.failedJobs ?? createFailedJobService();
-
-  console.log("[queue:work] Listening for jobs on Redis...");
-  const worker = createQueueWorker(redisUrl, failedJobs);
-
-  registerShutdownHandler("queue-worker", async () => {
-    worker.requestStop();
-  });
-
-  if (options.close) {
-    registerShutdownHandler("database", async () => {
-      await options.close?.();
-    });
-  }
-
-  installGracefulShutdownSignals();
-
-  await worker.run();
-  console.log("[queue:work] Worker stopped.");
+  const result = await lifecycle.shutdown("WORKER_FINISHED");
+  uninstall();
+  if (!result.successful)
+    throw new AggregateError(
+      [...(failed ? [failure] : []), ...result.errors.map((entry) => entry.error)],
+      "Queue startup/runtime or shutdown failed.",
+    );
+  if (failed) throw failure;
 }
 
 export type { QueueWorkerBoot, QueueWorkerClose };

package/src/schedule.ts

@@ -1,25 +1,87 @@
+import {
+  installGracefulShutdownSignals,
+  LifecycleCoordinator,
+} from "@getstrata/core/lifecycle/gracefulShutdown";
 import { appSchedule, runDueScheduledTasks } from "@getstrata/core/scheduler/schedule";
 
 type LoadAppSchedule = () => void | Promise<void>;
+type CloseScheduledApp = () => void | Promise<void>;
 
-function createScheduleRunCommand(loadSchedule: LoadAppSchedule) {
+function createScheduleRunCommand(
+  loadSchedule: LoadAppSchedule,
+  close?: CloseScheduledApp,
+  options: {
+    lifecycle?: LifecycleCoordinator;
+    flush?: CloseScheduledApp;
+    drain?: CloseScheduledApp;
+  } = {},
+) {
   return async function scheduleRunCommand(): Promise<void> {
-    await loadSchedule();
-
-    const due = appSchedule.dueTasks();
-
-    if (due.length === 0) {
-      console.log("No scheduled tasks due.");
-      return;
+    const lifecycle = options.lifecycle ?? new LifecycleCoordinator();
+    if (lifecycle.isShuttingDown) throw new Error("Cannot start scheduling during shutdown.");
+    const admission = new AbortController();
+    let stopping = false;
+    let execution: Promise<void> | undefined;
+    const name = `scheduler:${crypto.randomUUID()}`;
+    lifecycle.register(
+      `${name}:stop`,
+      () => {
+        stopping = true;
+        admission.abort();
+      },
+      "stop",
+    );
+    lifecycle.register(
+      `${name}:drain`,
+      async () => {
+        await execution?.catch(() => {});
+        await options.drain?.();
+      },
+      "drain",
+    );
+    lifecycle.register(
+      `${name}:flush`,
+      async () => {
+        await options.flush?.();
+      },
+      "flush",
+    );
+    lifecycle.register(
+      `${name}:close`,
+      async () => {
+        await close?.();
+      },
+      "close",
+    );
+    const uninstall = installGracefulShutdownSignals(undefined, lifecycle);
+    let failed = false;
+    let failure: unknown;
+    try {
+      execution = (async () => {
+        await loadSchedule();
+        if (stopping) return;
+        const due = appSchedule.dueTasks();
+        if (due.length === 0) console.log("No scheduled tasks due.");
+        else {
+          for (const task of due) console.log(`Running scheduled task: ${task.name}`);
+          await runDueScheduledTasks(appSchedule, new Date(), { signal: admission.signal });
+        }
+      })();
+      await execution;
+    } catch (error) {
+      failed = true;
+      failure = error;
     }
-
-    for (const task of due) {
-      console.log(`Running scheduled task: ${task.name}`);
-    }
-
-    await runDueScheduledTasks(appSchedule);
+    const result = await lifecycle.shutdown("SCHEDULE_FINISHED");
+    uninstall();
+    if (!result.successful)
+      throw new AggregateError(
+        [...(failed ? [failure] : []), ...result.errors.map((entry) => entry.error)],
+        "Scheduler startup/runtime or shutdown failed.",
+      );
+    if (failed) throw failure;
   };
 }
 
-export type { LoadAppSchedule };
+export type { CloseScheduledApp, LoadAppSchedule };
 export { createScheduleRunCommand };