create-colonel 1.1.1 → 1.1.2

package/README.md

@@ -26,6 +26,23 @@ Optional flag:
 bunx create-colonel my-app --skip-install
 ```
 
+Telemetry flags:
+
+```bash
+bunx create-colonel my-app \
+	--telemetry yes \
+	--telemetry-endpoint https://colonel-telemetry.vercel.app/api/ingest \
+	--telemetry-provision-endpoint https://colonel-telemetry.vercel.app/api/provision-app \
+	--telemetry-provision-token <token>
+```
+
+When telemetry is enabled and provisioning succeeds, the scaffolded `.env` receives:
+
+- `COLONEL_TELEMETRY_ENABLED`
+- `COLONEL_TELEMETRY_ENDPOINT`
+- `COLONEL_TELEMETRY_APP_ID`
+- `COLONEL_TELEMETRY_KEY`
+
 Use `--skip-install` when you only want scaffolded files and prefer to install dependencies later.
 
 Then run your new app:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-colonel",
-  "version": "1.1.1",
+  "version": "1.1.2",
   "type": "module",
   "files": [
     "src",

package/src/cli.ts

@@ -2,21 +2,156 @@
 
 import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
 import { basename, resolve } from "node:path";
+import { createInterface } from "node:readline/promises";
+import { stdin as input, stdout as output } from "node:process";
+
+type TelemetryConsent = "yes" | "no";
+
+const DEFAULT_TELEMETRY_ENDPOINT = "https://colonel-telemetry.vercel.app/api/ingest";
+
+const deriveProvisionEndpoint = (ingestEndpoint: string): string => {
+    if (ingestEndpoint.endsWith("/api/ingest")) {
+        return `${ingestEndpoint.slice(0, -"/api/ingest".length)}/api/provision-app`;
+    }
+
+    return `${ingestEndpoint.replace(/\/$/, "")}/api/provision-app`;
+};
+
+const upsertEnv = (content: string, key: string, value: string): string => {
+    const line = `${key}=${value}`;
+    const pattern = new RegExp(`^${key}=.*$`, "m");
+    if (pattern.test(content)) {
+        return content.replace(pattern, line);
+    }
+
+    const suffix = content.length === 0 || content.endsWith("\n") ? "" : "\n";
+    return `${content}${suffix}${line}\n`;
+};
+
+const normalizeConsent = (value: string | undefined): TelemetryConsent | null => {
+    if (!value) return null;
+
+    const normalized = value.trim().toLowerCase();
+    if (["y", "yes", "true", "1"].includes(normalized)) return "yes";
+    if (["n", "no", "false", "0"].includes(normalized)) return "no";
+    return null;
+};
+
+const parseOptionValue = (args: string[], name: string): string | undefined => {
+    const index = args.indexOf(name);
+    if (index === -1) return undefined;
+    return args[index + 1];
+};
+
+const trackScaffoldEvent = async (payload: Record<string, unknown>, endpoint: string, appId: string, apiKey: string): Promise<void> => {
+    try {
+        await fetch(endpoint, {
+            method: "POST",
+            headers: {
+                "content-type": "application/json",
+                "x-colonel-telemetry-key": apiKey,
+            },
+            body: JSON.stringify({
+                name: "scaffold_created",
+                timestamp: new Date().toISOString(),
+                source: "create-colonel",
+                appId,
+                environment: process.env.NODE_ENV ?? "development",
+                runtime: "bun",
+                properties: payload,
+            }),
+        });
+    } catch {
+        // Do not block scaffolding on telemetry transport failures.
+    }
+};
+
+const provisionTelemetryApp = async (
+    appName: string,
+    source: string,
+    provisionEndpoint: string,
+    provisionToken: string
+): Promise<{ appId: string; ingestKey: string } | null> => {
+    try {
+        const response = await fetch(provisionEndpoint, {
+            method: "POST",
+            headers: {
+                "content-type": "application/json",
+                authorization: `Bearer ${provisionToken}`,
+            },
+            body: JSON.stringify({ appName, source }),
+        });
+
+        if (!response.ok) return null;
+        const data = (await response.json()) as { appId?: string; ingestKey?: string };
+        if (!data.appId || !data.ingestKey) return null;
+
+        return { appId: data.appId, ingestKey: data.ingestKey };
+    } catch {
+        return null;
+    }
+};
+
+const askTelemetryConsent = async (): Promise<TelemetryConsent> => {
+    if (!input.isTTY || !output.isTTY) {
+        return "no";
+    }
+
+    const rl = createInterface({ input, output });
+    const answer = await rl.question("Share anonymous usage stats to help improve Colonel? (y/N): ");
+    rl.close();
+
+    return normalizeConsent(answer) ?? "no";
+};
+
+const configureTelemetryEnv = (
+    targetDir: string,
+    consent: TelemetryConsent,
+    endpoint: string,
+    appId?: string,
+    apiKey?: string
+): void => {
+    const envPath = resolve(targetDir, ".env");
+    const existing = existsSync(envPath) ? readFileSync(envPath, "utf8") : "";
+
+    let content = upsertEnv(existing, "COLONEL_TELEMETRY_ENABLED", consent === "yes" ? "true" : "false");
+    content = upsertEnv(content, "COLONEL_TELEMETRY_ENDPOINT", endpoint);
+    content = upsertEnv(content, "COLONEL_TELEMETRY_APP_ID", appId ?? "");
+    content = upsertEnv(content, "COLONEL_TELEMETRY_KEY", apiKey ?? "");
+    writeFileSync(envPath, content);
+};
 
 const args = process.argv.slice(2);
 const targetArg = args.find((arg) => !arg.startsWith("-"));
 const skipInstall = args.includes("--skip-install");
 const showHelp = args.includes("--help") || args.includes("-h");
+const telemetryFlag = parseOptionValue(args, "--telemetry");
+const telemetryConsentFromFlag = normalizeConsent(telemetryFlag);
+const telemetryEndpoint = parseOptionValue(args, "--telemetry-endpoint") ?? process.env.COLONEL_TELEMETRY_ENDPOINT ?? DEFAULT_TELEMETRY_ENDPOINT;
+const provisionEndpoint = parseOptionValue(args, "--telemetry-provision-endpoint")
+    ?? process.env.COLONEL_TELEMETRY_PROVISION_ENDPOINT
+    ?? deriveProvisionEndpoint(telemetryEndpoint);
+const provisionToken = parseOptionValue(args, "--telemetry-provision-token")
+    ?? process.env.COLONEL_TELEMETRY_PROVISION_TOKEN;
 
 if (showHelp) {
-    console.log("Usage: bunx create-colonel <project-name> [--skip-install]");
+    console.log("Usage: bunx create-colonel <project-name> [--skip-install] [--telemetry yes|no] [--telemetry-endpoint <url>] [--telemetry-provision-endpoint <url>] [--telemetry-provision-token <token>]");
     console.log("\nOptions:");
     console.log("  --skip-install    Scaffold files without running bun install");
+    console.log("  --telemetry       Set anonymous telemetry consent without interactive prompt");
+    console.log("  --telemetry-endpoint  Override telemetry ingestion endpoint");
+    console.log("  --telemetry-provision-endpoint  Override telemetry app provisioning endpoint");
+    console.log("  --telemetry-provision-token  Bearer token used for telemetry app provisioning");
     process.exit(0);
 }
 
 if (!targetArg) {
-    console.error("Usage: bunx create-colonel <project-name> [--skip-install]");
+    console.error("Usage: bunx create-colonel <project-name> [--skip-install] [--telemetry yes|no] [--telemetry-endpoint <url>] [--telemetry-provision-endpoint <url>] [--telemetry-provision-token <token>]");
+    process.exit(1);
+}
+
+if (telemetryFlag && !telemetryConsentFromFlag) {
+    console.error("Invalid --telemetry value. Use yes or no.");
     process.exit(1);
 }
 
@@ -46,6 +181,24 @@ if (existsSync(resolve(localFrameworkPath, "package.json"))) {
 
 writeFileSync(packageJsonPath, `${JSON.stringify(packageJson, null, 2)}\n`);
 
+const consent = telemetryConsentFromFlag ?? await askTelemetryConsent();
+let provisionedAppId: string | undefined;
+let provisionedIngestKey: string | undefined;
+
+if (consent === "yes" && provisionToken) {
+    const provisioned = await provisionTelemetryApp(
+        basename(targetDir),
+        "create-colonel",
+        provisionEndpoint,
+        provisionToken
+    );
+
+    provisionedAppId = provisioned?.appId;
+    provisionedIngestKey = provisioned?.ingestKey;
+}
+
+configureTelemetryEnv(targetDir, consent, telemetryEndpoint, provisionedAppId, provisionedIngestKey);
+
 if (!skipInstall) {
     console.log("Installing dependencies...");
     const install = Bun.spawnSync(["bun", "install"], {
@@ -60,6 +213,14 @@ if (!skipInstall) {
     }
 }
 
+if (consent === "yes" && provisionedAppId && provisionedIngestKey) {
+    await trackScaffoldEvent({
+        projectName: basename(targetDir),
+        skipInstall,
+        template: "create-colonel",
+    }, telemetryEndpoint, provisionedAppId, provisionedIngestKey);
+}
+
 console.log("\nColonel app created successfully.\n");
 console.log(`  cd ${targetArg}`);
 

package/template/package.json

@@ -1,6 +1,6 @@
 {
   "name": "colonel-app",
-  "version": "1.0.1",
+  "version": "1.1.1",
   "type": "module",
   "private": true,
   "scripts": {
@@ -8,7 +8,7 @@
     "upgrade:colonel": "bun add @coloneldev/framework@latest"
   },
   "dependencies": {
-    "@coloneldev/framework": "^1.0.2",
+    "@coloneldev/framework": "^1.1.2",
     "ejs": "^5.0.1"
   },
   "devDependencies": {

package/template/src/bootstrap/server.ts

@@ -1,4 +1,4 @@
-import { Kernel } from "@coloneldev/framework";
+import { Kernel, createTelemetryClientFromEnv } from "@coloneldev/framework";
 import webRouter  from "../config/routes/web";
 import { existsSync } from "fs";
 import { extensions } from "../config/acceptedStaticContentTypes";
@@ -14,6 +14,10 @@ const viewsRoot = path.resolve(import.meta.dir, "..", "..", "resources", "views"
 const publicRoot = path.resolve(import.meta.dir, "..", "..", "public");
 const controllerRoot = path.resolve(import.meta.dir, "..", "app", "Http", "Controllers");
 const container = new Container();
+const telemetry = createTelemetryClientFromEnv({
+    source: "colonel-app",
+    appId: process.env.COLONEL_TELEMETRY_APP_ID ?? process.env.appName ?? "Colonel",
+});
 
 container.singleton(
     AppInfoService,
@@ -32,6 +36,10 @@ export const server = () => {
         session: {
             enabled: true,
         },
+        telemetry: {
+            client: telemetry,
+            sampleRate: 0.2,
+        },
         controllerResolver: async (name: string) => {
             const modulePath = `${controllerRoot}/${name}.ts`;
             const mod = await import(modulePath);
@@ -45,6 +53,11 @@ export const server = () => {
         }
     }, container);
     const PORT = Number(process.env.PORT) || 5000;
+    telemetry.track("server_start", {
+        port: PORT,
+        environment: process.env.NODE_ENV ?? "development",
+        runtime: "bun",
+    });
     
     console.log(`Server running at http://localhost:${PORT}/`);