blokctl 1.1.0 → 1.3.0

package/dist/commands/create/project.d.ts

@@ -1,5 +1,10 @@
 import type { OptionValues } from "commander";
 export declare function createProject(opts: OptionValues, version: string, currentPath?: boolean, localRepoPath?: string): Promise<void>;
+export declare function generateSharedNodesFile(_triggers: string[], _repoSource: string): string;
+export declare function generateSharedWorkflowsFile(triggers: string[], runtimeKinds?: string[], examples?: boolean): string;
+export declare function generateTriggerEntryFile(triggerKind: string, selectedTriggers?: string[]): string;
+export declare function generateCronExampleWorkflowFile(): string;
+export declare function generateCronServerFile(): string;
 export declare function updateQueueProvider(triggerDestDir: string, provider: string, explicit: boolean): void;
 export declare function getProviderDependencies(triggers: string[], pubsubProvider: string, queueProvider: string, explicitQueueProvider?: boolean): Record<string, string>;
 export declare function getProviderEnvVars(triggers: string[], pubsubProvider: string, queueProvider: string, explicitQueueProvider?: boolean): string;

package/dist/commands/create/project.js

@@ -14,7 +14,7 @@ import { rewriteObservabilityEnvBlock } from "../../services/observability-mutat
 import { manager as pm } from "../../services/package-manager.js";
 import { detectRuntimes } from "../../services/runtime-detector.js";
 import { createTriggerConfig, generateRuntimeEnvVars, generateSupervisordConfig, generateTriggerEnvVars, generateTriggerSupervisordConfig, setupRuntime, writeProjectConfig, } from "../../services/runtime-setup.js";
-import { computeDefaultConstraint } from "../../services/semver-utils.js";
+import { computeDefaultConstraint, formatVersionMismatch, satisfiesConstraint } from "../../services/semver-utils.js";
 import { resolveObservabilitySelection } from "../observability/apply.js";
 import { OBSERVABILITY_MODULE_IDS, allObservabilityModules, getObservabilityModule, } from "../observability/descriptor.js";
 import { agents_md, claude_md, examples_url, node_file, package_dependencies, package_dev_dependencies, } from "./utils/Examples.js";
@@ -22,7 +22,7 @@ const exec = util.promisify(child_process.exec);
 const HOME_DIR = `${os.homedir()}/.blok`;
 const GITHUB_REPO_LOCAL = `${HOME_DIR}/blok`;
 const GITHUB_REPO_REMOTE = "https://github.com/well-prado/blok.git";
-const GITHUB_REPO_RELEASE_TAG = "v1.1.0";
+const GITHUB_REPO_RELEASE_TAG = "v1.3.0";
 const RUNTIME_HELLO_EXAMPLES = {
     go: "runtime-go-hello.ts",
     rust: "runtime-rust-hello.ts",
@@ -55,7 +55,7 @@ export async function createProject(opts, version, currentPath = false, localRep
     let examples = opts.examples ?? false;
     let selectedRuntimeKinds = opts.runtimes ? parseCommaSeparated(opts.runtimes) : ["node"];
     let selectedManager = opts.packageManager || "npm";
-    let pubsubProvider = opts.pubsubProvider || "gcp";
+    let pubsubProvider = opts.pubsubProvider || "nats";
     let queueProvider = opts.queueProvider || "kafka";
     let explicitQueueProvider = Boolean(opts.queueProvider);
     let selectedObsTier = opts.obsStack ? parseObsTier(opts.obsStack) : "none";
@@ -154,6 +154,7 @@ export async function createProject(opts, version, currentPath = false, localRep
                     ? p.select({
                         message: "Select Pub/Sub provider",
                         options: [
+                            { label: "NATS (local, zero cloud setup)", value: "nats" },
                             { label: "Google Cloud Pub/Sub", value: "gcp" },
                             { label: "AWS SNS/SQS", value: "aws" },
                             { label: "Azure Service Bus", value: "azure" },
@@ -212,7 +213,7 @@ export async function createProject(opts, version, currentPath = false, localRep
         });
         projectName = blokctlProject.projectName;
         selectedTriggers = blokctlProject.triggers;
-        pubsubProvider = blokctlProject.pubsubProvider || "gcp";
+        pubsubProvider = blokctlProject.pubsubProvider || "nats";
         explicitQueueProvider = blokctlProject.queueProvider != null;
         queueProvider = blokctlProject.queueProvider || "kafka";
         selectedRuntimeKinds = blokctlProject.runtimes;
@@ -453,6 +454,14 @@ export async function createProject(opts, version, currentPath = false, localRep
             fsExtra.ensureDirSync(wsServerDir);
             fsExtra.writeFileSync(`${wsServerDir}/WSServer.ts`, generateWSServerFile());
         }
+        if (selectedTriggers.includes("cron")) {
+            const cronServerDir = `${dirPath}/src/triggers/cron/runner`;
+            fsExtra.ensureDirSync(cronServerDir);
+            fsExtra.writeFileSync(`${cronServerDir}/CronServer.ts`, generateCronServerFile());
+            const cronWorkflowDir = `${dirPath}/src/workflows/cron`;
+            fsExtra.ensureDirSync(cronWorkflowDir);
+            fsExtra.writeFileSync(`${cronWorkflowDir}/heartbeat.ts`, generateCronExampleWorkflowFile());
+        }
         for (const triggerKind of selectedTriggers) {
             const triggerNodesDir = `${repoSource}/triggers/${triggerKind}/src/nodes`;
             if (fsExtra.existsSync(triggerNodesDir)) {
@@ -500,13 +509,7 @@ export async function createProject(opts, version, currentPath = false, localRep
             fsExtra.ensureDirSync(`${dirPath}/infra/milvus`);
             fsExtra.copySync(`${repoSource}/infra/development`, `${dirPath}/infra/postgresql`);
             fsExtra.copySync(`${repoSource}/infra/milvus`, `${dirPath}/infra/milvus`);
-            const needsHelpers = selectedTriggers.includes("sse") || selectedTriggers.includes("websocket") || selectedTriggers.includes("mcp");
-            const examplesNodesContent = needsHelpers
-                ? node_file
-                    .replace(`import type { NodeBase } from "@blokjs/shared";`, `import type { NodeBase } from "@blokjs/shared";\nimport { HELPER_NODES } from "@blokjs/helpers";`)
-                    .replace(`} = {\n\t"@blokjs/api-call": ApiCall,`, `} = {\n\t...HELPER_NODES,\n\t"@blokjs/api-call": ApiCall,`)
-                : node_file;
-            fsExtra.writeFileSync(`${dirPath}/src/Nodes.ts`, examplesNodesContent);
+            fsExtra.writeFileSync(`${dirPath}/src/Nodes.ts`, node_file);
             fsExtra.copySync(`${repoSource}/sdk`, `${dirPath}/public/sdk`);
             const tsExamplesSrc = `${repoSource}/examples/ts-workflows`;
             const tsExamplesDest = `${dirPath}/src/workflows/examples`;
@@ -551,7 +554,7 @@ export async function createProject(opts, version, currentPath = false, localRep
             "@blokjs/trigger-worker": "triggers/worker",
             "@blokjs/core": "core/core",
         };
-        const BLOKJS_DEP_RANGE = "^1.1.0";
+        const BLOKJS_DEP_RANGE = "^1.3.0";
         for (const depGroup of ["dependencies", "devDependencies", "peerDependencies"]) {
             const deps = packageJsonContent[depGroup];
             if (!deps)
@@ -636,6 +639,16 @@ export async function createProject(opts, version, currentPath = false, localRep
                 ? `file:${path.resolve(repoSource, "triggers/worker")}`
                 : BLOKJS_DEP_RANGE;
         }
+        if (selectedTriggers.includes("cron")) {
+            triggerPackageDeps["@blokjs/trigger-cron"] = localRepoPath
+                ? `file:${path.resolve(repoSource, "triggers/cron")}`
+                : BLOKJS_DEP_RANGE;
+        }
+        if (selectedTriggers.includes("grpc")) {
+            triggerPackageDeps["@blokjs/trigger-grpc"] = localRepoPath
+                ? `file:${path.resolve(repoSource, "triggers/grpc")}`
+                : BLOKJS_DEP_RANGE;
+        }
         if (selectedTriggers.includes("sse")) {
             const sseDeps = {
                 "@blokjs/api-call": localRepoPath
@@ -705,6 +718,14 @@ export async function createProject(opts, version, currentPath = false, localRep
                 const rt = detectedRuntimes.find((r) => r.kind === kind);
                 if (!rt)
                     continue;
+                if (rt.minVersion) {
+                    const constraint = computeDefaultConstraint(rt.minVersion);
+                    if (!rt.version || !satisfiesConstraint(rt.version, constraint)) {
+                        console.log(`\n${formatVersionMismatch(rt.label, rt.version, constraint, rt.installHint)}`);
+                        console.log(color.yellow(`  Skipping ${rt.label} setup. After upgrading, add it with \`blokctl runtime add ${rt.kind}\`.\n`));
+                        continue;
+                    }
+                }
                 try {
                     const config = await setupRuntime(rt, repoSource, dirPath, s);
                     runtimeConfigs.push(config);
@@ -858,20 +879,21 @@ export async function createProject(opts, version, currentPath = false, localRep
             console.log(error.message);
     }
 }
-function generateSharedNodesFile(triggers, _repoSource) {
+export function generateSharedNodesFile(_triggers, _repoSource) {
     const imports = [
         'import { dirname, join } from "node:path";',
         'import { fileURLToPath } from "node:url";',
         'import ApiCall from "@blokjs/api-call";',
         'import IfElse from "@blokjs/if-else";',
+        'import { HELPER_NODES } from "@blokjs/helpers";',
         'import { discoverNodes } from "@blokjs/runner";',
         'import type { NodeBase } from "@blokjs/shared";',
     ];
-    const explicit = ["ApiCall as unknown as NodeBase", "IfElse as unknown as NodeBase"];
-    if (triggers.includes("sse") || triggers.includes("websocket")) {
-        imports.push('import { HELPER_NODES } from "@blokjs/helpers";');
-        explicit.push("...(Object.values(HELPER_NODES) as unknown as NodeBase[])");
-    }
+    const explicit = [
+        "ApiCall as unknown as NodeBase",
+        "IfElse as unknown as NodeBase",
+        "...(Object.values(HELPER_NODES) as unknown as NodeBase[])",
+    ];
     return `${imports.join("\n")}
 
 // Published nodes (npm) are registered explicitly below. Your OWN nodes under
@@ -890,32 +912,42 @@ for (const node of [${explicit.join(", ")}, ...local]) {
 export default nodes;
 `;
 }
-function generateSharedWorkflowsFile(triggers, runtimeKinds = [], examples = false) {
+export function generateSharedWorkflowsFile(triggers, runtimeKinds = [], examples = false) {
     const imports = [];
     const workflowEntries = [];
     for (const trigger of triggers) {
         if (trigger === "http") {
-            imports.push("// HTTP workflows are auto-discovered from workflows/json/");
+            imports.push("// HTTP JSON workflows are auto-discovered from workflows/json/");
+            imports.push('import CountriesHandleDsl from "./workflows/http/countries-handle-dsl";');
+            workflowEntries.push('\t"countries-dsl": await CountriesHandleDsl,');
         }
         else if (trigger === "sse") {
             imports.push('import SSEStreamDemo from "./workflows/sse/events/stream-demo";');
-            workflowEntries.push('\t"sse-stream-demo": SSEStreamDemo,');
+            workflowEntries.push('\t"sse-stream-demo": await SSEStreamDemo,');
             if (triggers.includes("http")) {
                 imports.push('import SSEPublishDemo from "./workflows/sse/events/publish-demo";');
-                workflowEntries.push('\t"sse-publish-demo": SSEPublishDemo,');
+                workflowEntries.push('\t"sse-publish-demo": await SSEPublishDemo,');
             }
         }
         else if (trigger === "websocket") {
             imports.push('import WSEchoDemo from "./workflows/websocket/events/echo-demo";');
-            workflowEntries.push('\t"ws-echo-demo": WSEchoDemo,');
+            workflowEntries.push('\t"ws-echo-demo": await WSEchoDemo,');
         }
         else if (trigger === "pubsub") {
             imports.push('import OnPubSubMessage from "./workflows/pubsub/messages/on-message";');
-            workflowEntries.push('\t"on-pubsub-message": OnPubSubMessage,');
+            workflowEntries.push('\t"on-pubsub-message": await OnPubSubMessage,');
+            if (triggers.includes("http")) {
+                imports.push('import PublishOrder from "./workflows/pubsub/publish-order";');
+                workflowEntries.push('\t"publish-order": await PublishOrder,');
+            }
         }
         else if (trigger === "queue" || trigger === "worker") {
             imports.push(`import ProcessJob from "./workflows/${trigger}/jobs/process-job";`);
-            workflowEntries.push('\t"process-job": ProcessJob,');
+            workflowEntries.push('\t"process-job": await ProcessJob,');
+        }
+        else if (trigger === "cron") {
+            imports.push('import CronHeartbeat from "./workflows/cron/heartbeat";');
+            workflowEntries.push('\t"cron-heartbeat": await CronHeartbeat,');
         }
     }
     if (examples) {
@@ -945,7 +977,7 @@ ${entriesSection}
 export default workflows;
 `;
 }
-function generateTriggerEntryFile(triggerKind, selectedTriggers = [triggerKind]) {
+export function generateTriggerEntryFile(triggerKind, selectedTriggers = [triggerKind]) {
     if (triggerKind === "http") {
         const sseAlsoSelected = selectedTriggers.includes("sse");
         const wsAlsoSelected = selectedTriggers.includes("websocket");
@@ -1285,6 +1317,63 @@ export default class App {
 if (process.env.DISABLE_TRIGGER_RUN !== "true") {
 	new App().run();
 }
+`;
+    }
+    if (triggerKind === "cron") {
+        return `import { DefaultLogger } from "@blokjs/runner";
+import { type Span, metrics, trace } from "@opentelemetry/api";
+import CronServer from "./runner/CronServer";
+
+export default class App {
+	private cronServer: CronServer = <CronServer>{};
+	protected trigger_initializer = 0;
+	protected initializer = 0;
+	protected tracer = trace.getTracer(
+		process.env.PROJECT_NAME || "trigger-cron-server",
+		process.env.PROJECT_VERSION || "0.0.1",
+	);
+	private logger = new DefaultLogger();
+	protected app_cold_start = metrics.getMeter("default").createGauge("initialization", {
+		description: "Application cold start",
+	});
+
+	constructor() {
+		this.initializer = performance.now();
+		this.cronServer = new CronServer();
+	}
+
+	async run() {
+		this.tracer.startActiveSpan("initialization", async (span: Span) => {
+			await this.cronServer.listen();
+			this.initializer = performance.now() - this.initializer;
+
+			this.logger.log(\`Cron trigger initialized in \${(this.initializer).toFixed(2)}ms\`);
+			this.app_cold_start.record(this.initializer, {
+				pid: process.pid,
+				env: process.env.NODE_ENV,
+				app: process.env.APP_NAME,
+			});
+			span.end();
+		});
+	}
+}
+
+if (process.env.DISABLE_TRIGGER_RUN !== "true") {
+	new App().run();
+}
+`;
+    }
+    if (triggerKind === "grpc") {
+        return `import { GrpcServer } from "@blokjs/trigger-grpc";
+import nodes from "../../Nodes";
+import workflows from "../../Workflows";
+
+const host = process.env.GRPC_HOST || "0.0.0.0";
+const port = Number(process.env.GRPC_PORT || process.env.PORT || 4003);
+
+if (process.env.DISABLE_TRIGGER_RUN !== "true") {
+	new GrpcServer({ host, port, nodes, workflows }).start();
+}
 `;
     }
     return `// Entry point for ${triggerKind} trigger
@@ -1292,6 +1381,45 @@ if (process.env.DISABLE_TRIGGER_RUN !== "true") {
 console.log("${triggerKind} trigger not yet implemented");
 `;
 }
+export function generateCronExampleWorkflowFile() {
+    return `import { node, step, workflow } from "@blokjs/core";
+
+/**
+ * Cron heartbeat — fires on a schedule, NOT on an HTTP request. \`blokctl dev\`
+ * boots it via src/triggers/cron/index.ts and it fires every minute. The
+ * schedule accepts an optional leading seconds field (e.g. \`* * * * * *\` for
+ * every second). Add more cron workflows by exporting them and registering
+ * them in src/Workflows.ts.
+ */
+export default workflow(
+	"Cron Heartbeat",
+	{ version: "1.0.0", trigger: { cron: { schedule: "* * * * *", timezone: "UTC" } } },
+	() => {
+		step("heartbeat", node("@blokjs/expr"), { expression: "({ ok: true, at: Date.now() })" }, { ephemeral: true });
+	},
+);
+`;
+}
+export function generateCronServerFile() {
+    return `import { CronTrigger } from "@blokjs/trigger-cron";
+import nodes from "../../../Nodes";
+import workflows from "../../../Workflows";
+
+/**
+ * CronServer — the cron trigger for this project.
+ *
+ * CronTrigger.listen() populates the NodeMap, registers workflows with the
+ * WorkflowRegistry, then schedules a CronJob for every workflow whose trigger
+ * is \`{ cron: { schedule, timezone? } }\`. There is no port to bind — the
+ * scheduled job timers keep the process alive. Non-cron workflows sharing this
+ * Workflows.ts are ignored by the scheduler (they run under their own trigger).
+ */
+export default class CronServer extends CronTrigger {
+	protected nodes: Record<string, import("@blokjs/runner").BlokService<unknown>> = nodes;
+	protected workflows: Record<string, import("@blokjs/helper").WorkflowV2Builder> = workflows;
+}
+`;
+}
 function generateSSEServerFile() {
     return `import { serve } from "@hono/node-server";
 import { DefaultLogger, NodeMap, WorkflowRegistry } from "@blokjs/runner";
@@ -1578,8 +1706,12 @@ function updatePubSubProvider(triggerDestDir, provider) {
         },
     };
     const config = adapterConfigs[provider];
-    if (!config)
+    if (!config) {
+        content = content.replace(/import \{ GCPPubSubAdapter, PubSubTrigger \} from ["']@blokjs\/trigger-pubsub["'];/, 'import { PubSubTrigger } from "@blokjs/trigger-pubsub";');
+        content = content.replace(/\n\tprotected adapter = new GCPPubSubAdapter\(\{[\s\S]*?\}\);\n/, "");
+        fsExtra.writeFileSync(serverPath, content);
         return;
+    }
     content = content.replace(/import \{ (\w+), (\w+) \} from ["']@blokjs\/trigger-pubsub["'];/, `import { ${config.importName}, PubSubTrigger } from "@blokjs/trigger-pubsub";`);
     content = content.replace(/(export default class \w+ extends PubSubTrigger \{[\s\S]*?)\n\tprotected adapter = new \w+\(\{[\s\S]*?\}\);/, `$1\n\tprotected adapter = ${config.init};`);
     fsExtra.writeFileSync(serverPath, content);
@@ -1637,6 +1769,7 @@ export function updateQueueProvider(triggerDestDir, provider, explicit) {
 export function getProviderDependencies(triggers, pubsubProvider, queueProvider, explicitQueueProvider = false) {
     const deps = {};
     const pubsubProviderDeps = {
+        nats: { nats: "^2.28.0" },
         gcp: { "@google-cloud/pubsub": "^5.0.0" },
         aws: { "@aws-sdk/client-sns": "^3.980.0", "@aws-sdk/client-sqs": "^3.980.0" },
         azure: { "@azure/service-bus": "^7.9.5" },
@@ -1661,6 +1794,10 @@ export function getProviderDependencies(triggers, pubsubProvider, queueProvider,
 export function getProviderEnvVars(triggers, pubsubProvider, queueProvider, explicitQueueProvider = false) {
     const lines = [];
     const pubsubEnvVars = {
+        nats: `
+# NATS (local pub/sub broker — zero cloud setup)
+NATS_SERVERS=localhost:4222
+BLOK_PUBSUB_ADAPTER=nats`,
         gcp: `
 # Google Cloud Pub/Sub
 GCP_PROJECT_ID=my-project