@trinacria/cli 0.1.1-alpha.1

package/dist/templates/cron-example/README.md

@@ -0,0 +1,68 @@
+# Cron Example App
+
+App minimale di esempio per usare `@trinacria/cron`.
+
+Mostra:
+
+- job a intervallo (`interval`)
+- job con espressione cron (`cron`)
+- protezione overlap con `allowConcurrent: false`
+- hook `onError` e `onEvent` del plugin
+
+## Requisiti
+
+- build dei package framework:
+
+```bash
+npm run build:packages
+```
+
+## Setup
+
+```bash
+cp apps/cron-example/.env.example apps/cron-example/.env.development
+```
+
+## Avvio
+
+```bash
+npm run dev -w cron-example
+```
+
+Oppure dalla root:
+
+```bash
+npm run dev:cron-example
+```
+
+## Docker quick start
+
+1. Crea il file `.env` da template:
+
+```bash
+cp apps/cron-example/.env.example apps/cron-example/.env
+```
+
+2. Avvia il container:
+
+```bash
+docker compose \
+  --env-file apps/cron-example/.env \
+  -f apps/cron-example/docker-compose.yml \
+  up --build -d
+```
+
+3. Ferma il container:
+
+```bash
+docker compose \
+  --env-file apps/cron-example/.env \
+  -f apps/cron-example/docker-compose.yml \
+  down
+```
+
+## Job inclusi
+
+- `cron-example:heartbeat` ogni `HEARTBEAT_INTERVAL_MS` (default `10000`)
+- `cron-example:minute-tick` ogni minuto (`* * * * *`)
+- `cron-example:overlap-guard-demo` ogni 5 secondi ma con lavoro da 8 secondi per mostrare skip overlap

package/dist/templates/cron-example/docker-compose.yml

@@ -0,0 +1,11 @@
+services:
+  app:
+    build:
+      context: ../..
+      dockerfile: apps/cron-example/Dockerfile
+    environment:
+      ENV: production
+      CRON_ENABLED: ${DOCKER_CRON_ENABLED}
+      CRON_TICK_MS: ${DOCKER_CRON_TICK_MS}
+      HEARTBEAT_INTERVAL_MS: ${DOCKER_HEARTBEAT_INTERVAL_MS}
+    restart: unless-stopped

package/dist/templates/cron-example/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "cron-example",
+  "private": true,
+  "type": "commonjs",
+  "scripts": {
+    "start": "node ../../packages/cli/dist/index.js start",
+    "build": "node ../../packages/cli/dist/index.js build",
+    "dev": "node ../../packages/cli/dist/index.js dev"
+  },
+  "dependencies": {
+    "@trinacria/cli": "*",
+    "@trinacria/core": "*",
+    "@trinacria/cron": "*"
+  }
+}

package/dist/templates/cron-example/src/config.service.ts

@@ -0,0 +1,46 @@
+import { createToken } from "@trinacria/core";
+
+export interface AppConfig {
+  readonly CRON_ENABLED: boolean;
+  readonly CRON_TICK_MS: number;
+  readonly HEARTBEAT_INTERVAL_MS: number;
+}
+
+export const CONFIG_SERVICE = createToken<ConfigService>(
+  "CRON_EXAMPLE_CONFIG_SERVICE",
+);
+
+function parseBoolean(value: string | undefined, fallback: boolean): boolean {
+  if (value == null || value.trim() === "") {
+    return fallback;
+  }
+
+  const normalized = value.trim().toLowerCase();
+  return normalized === "1" || normalized === "true" || normalized === "yes";
+}
+
+function parseNumber(value: string | undefined, fallback: number): number {
+  if (value == null || value.trim() === "") {
+    return fallback;
+  }
+
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed)) {
+    return fallback;
+  }
+
+  return parsed;
+}
+
+export class ConfigService {
+  getAll(): AppConfig {
+    return {
+      CRON_ENABLED: parseBoolean(process.env.CRON_ENABLED, true),
+      CRON_TICK_MS: parseNumber(process.env.CRON_TICK_MS, 1_000),
+      HEARTBEAT_INTERVAL_MS: parseNumber(
+        process.env.HEARTBEAT_INTERVAL_MS,
+        10_000,
+      ),
+    };
+  }
+}

package/dist/templates/cron-example/src/main.ts

@@ -0,0 +1,41 @@
+import { ConsoleLogger, TrinacriaApp, valueProvider } from "@trinacria/core";
+import { createCronPlugin } from "@trinacria/cron";
+import { CONFIG_SERVICE, ConfigService } from "./config.service";
+import { CronModule } from "./modules/cron/cron.module";
+
+async function bootstrap() {
+  const app = new TrinacriaApp();
+  const configService = new ConfigService();
+  const config = configService.getAll();
+  const logger = new ConsoleLogger("cron-example");
+
+  app.registerGlobalProvider(valueProvider(CONFIG_SERVICE, configService));
+
+  if (config.CRON_ENABLED) {
+    app.use(
+      createCronPlugin({
+        cronTickMs: config.CRON_TICK_MS,
+        onError: (error, job) => {
+          logger.error(`Cron job error: ${job.name}`, error);
+        },
+        onEvent: (event) => {
+          logger.info(
+            `Cron event job=${event.jobName} status=${event.status} attempts=${event.attempts} durationMs=${event.durationMs}`,
+          );
+        },
+      }),
+    );
+
+    await app.registerModule(CronModule);
+    logger.info("Cron plugin enabled");
+  } else {
+    logger.warn("Cron disabled (CRON_ENABLED=false)");
+  }
+
+  await app.start();
+}
+
+bootstrap().catch((error) => {
+  console.error(error);
+  process.exit(1);
+});

package/dist/templates/cron-example/src/modules/cron/cron.module.ts

@@ -0,0 +1,15 @@
+import { defineModule } from "@trinacria/core";
+import { cronProvider } from "@trinacria/cron";
+import { CONFIG_SERVICE } from "../../config.service";
+import { ExampleCronJobsProvider } from "./example-cron-jobs.provider";
+import { CRON_EXAMPLE_JOBS_PROVIDER } from "./cron.tokens";
+
+export const CronModule = defineModule({
+  name: "CronModule",
+  providers: [
+    cronProvider(CRON_EXAMPLE_JOBS_PROVIDER, ExampleCronJobsProvider, [
+      CONFIG_SERVICE,
+    ]),
+  ],
+  exports: [CRON_EXAMPLE_JOBS_PROVIDER],
+});

package/dist/templates/cron-example/src/modules/cron/cron.tokens.ts

@@ -0,0 +1,6 @@
+import { createToken } from "@trinacria/core";
+import type { CronJobProvider } from "@trinacria/cron";
+
+export const CRON_EXAMPLE_JOBS_PROVIDER = createToken<CronJobProvider>(
+  "CRON_EXAMPLE_JOBS_PROVIDER",
+);

package/dist/templates/cron-example/src/modules/cron/example-cron-jobs.provider.ts

@@ -0,0 +1,48 @@
+import { ConsoleLogger } from "@trinacria/core";
+import type { CronJobDefinition, CronJobProvider } from "@trinacria/cron";
+import { ConfigService } from "../../config.service";
+
+function wait(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+export class ExampleCronJobsProvider implements CronJobProvider {
+  private readonly logger = new ConsoleLogger("cron-example:jobs");
+
+  constructor(private readonly config: ConfigService) {}
+
+  jobs(): readonly CronJobDefinition[] {
+    const { HEARTBEAT_INTERVAL_MS } = this.config.getAll();
+
+    return [
+      {
+        name: "cron-example:heartbeat",
+        schedule: { type: "interval", everyMs: HEARTBEAT_INTERVAL_MS },
+        runOnInit: true,
+        run: ({ scheduledAt }) => {
+          this.logger.info(
+            `[heartbeat] scheduledAt=${scheduledAt.toISOString()} intervalMs=${HEARTBEAT_INTERVAL_MS}`,
+          );
+        },
+      },
+      {
+        name: "cron-example:minute-tick",
+        schedule: { type: "cron", expression: "* * * * *" },
+        run: ({ scheduledAt }) => {
+          this.logger.info(
+            `[minute-tick] scheduledAt=${scheduledAt.toISOString()}`,
+          );
+        },
+      },
+      {
+        name: "cron-example:overlap-guard-demo",
+        schedule: { type: "interval", everyMs: 5_000 },
+        allowConcurrent: false,
+        run: async () => {
+          await wait(8_000);
+          this.logger.info("[overlap-guard-demo] completed");
+        },
+      },
+    ];
+  }
+}

package/dist/templates/cron-example/trinacria.config.mjs

@@ -0,0 +1,12 @@
+/** @type {import('@trinacria/cli').TrinacriaConfig} */
+
+const config = {
+  entry: "src/main.ts",
+  outDir: "dist",
+  watchDir: "src",
+  env: "development",
+  crashLoopWindowMs: 15_000,
+  maxConsecutiveCrashRestarts: 3,
+};
+
+export default config;

package/dist/templates/cron-example/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "types": ["node"],
+    "target": "ES2022",
+    "module": "CommonJS",
+    "strict": true,
+    "declaration": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "rootDir": "src",
+    "outDir": "dist"
+  },
+  "include": ["src"]
+}

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@trinacria/cli",
+  "version": "0.1.1-alpha.1",
+  "private": false,
+  "license": "MIT",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "trinacria": "dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc && node scripts/copy-templates.mjs && chmod +x dist/index.js",
+    "test": "tsx --test test/**/*.test.ts",
+    "test:coverage": "tsx --test --experimental-test-coverage --test-coverage-include=src/**/*.ts test/**/*.test.ts"
+  },
+  "dependencies": {
+    "chokidar": "^5.0.0",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3"
+  },
+  "peerDependencies": {
+    "@trinacria/core": "*"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/tascaenzo/trinacria.git",
+    "directory": "packages/cli"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ]
+}