@apso/cli 0.28.0 → 0.29.1

package/dist/lib/telemetry/telemetry.js

@@ -1,15 +1,20 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.__testing = exports.shutdownTelemetry = exports.elapsedMs = exports.captureException = exports.track = exports.initTelemetry = void 0;
+exports.__testing = exports.shutdownTelemetry = exports.elapsedMs = exports.captureException = exports.track = exports.markFirstRunNoticeShown = exports.shouldShowFirstRunNotice = exports.FIRST_RUN_NOTICE = exports.initTelemetry = void 0;
 const tslib_1 = require("tslib");
 /**
  * CLI telemetry — usage analytics (PostHog) + error reporting (Sentry).
  *
  * Wired to the same Apso systems the web app and build engine use so CLI usage
  * shows up in the same funnels. Fully opt-out:
- *   - `apso config set telemetryDisabled true`
- *   - env DO_NOT_TRACK=1  (honors the console.dev standard)
- *   - env APSO_TELEMETRY_DISABLED=1
+ *   - `apso config set telemetry off` (or `telemetryDisabled true`)
+ *   - env APSO_TELEMETRY=0
+ *   - env DO_NOT_TRACK=1  (honors the consoledonottrack.com standard)
+ *   - env APSO_TELEMETRY_DISABLED=1  (legacy alias)
+ *
+ * The anonymous id is a random UUID persisted in the CLI config (`installId`),
+ * never derived from any machine identifier. No code, schema, or file contents
+ * are ever collected.
  *
  * Everything here is best-effort and MUST NOT throw or block a command. All
  * public functions swallow their own errors. The PostHog project keys and the
@@ -38,27 +43,49 @@ catch {
 let posthog = null;
 let enabled = false;
 let sentryOn = false;
+let authenticatedUser = false;
 let distinctId = "cli-anonymous";
 let environment = "production";
 let startedAt = Date.now();
+let noticePending = false;
 function isDisabled(telemetryDisabled) {
     if (process.env.DO_NOT_TRACK === "1" || process.env.DO_NOT_TRACK === "true")
         return true;
+    // Canonical opt-out env var (issue #96); APSO_TELEMETRY_DISABLED is a legacy alias.
+    if (process.env.APSO_TELEMETRY === "0" || process.env.APSO_TELEMETRY === "false")
+        return true;
     if (process.env.APSO_TELEMETRY_DISABLED === "1")
         return true;
-    return !!telemetryDisabled;
+    return Boolean(telemetryDisabled);
 }
-/** Stable, non-PII fallback id for logged-out users (no username, no MAC). */
+/** Stable, non-PII fallback id (only used if the config write fails). */
 function anonMachineId() {
     const seed = `${os_1.default.hostname()}|${os_1.default.platform()}|${os_1.default.arch()}`;
     return "cli_" + (0, crypto_1.createHash)("sha256").update(seed).digest("hex").slice(0, 20);
 }
+/**
+ * Read (or lazily create + persist) the anonymous install id: a random UUID
+ * stored in the CLI config. Not derived from any machine identifier. Falls
+ * back to a stable hashed id only if the config can't be written.
+ */
+function getOrCreateInstallId(currentInstallId) {
+    if (currentInstallId)
+        return currentInstallId;
+    const id = (0, crypto_1.randomUUID)();
+    try {
+        config_1.globalConfig.write({ installId: id });
+        return id;
+    }
+    catch {
+        return anonMachineId();
+    }
+}
 /**
  * Initialize telemetry. Call once at process start (init hook). Safe to call
  * when disabled — it just no-ops everything downstream.
  */
 function initTelemetry() {
-    var _a, _b, _c;
+    var _a, _b, _c, _d;
     try {
         startedAt = Date.now();
         const cfg = config_1.globalConfig.read();
@@ -70,10 +97,13 @@ function initTelemetry() {
         environment = (cfg.apiUrl || "").includes("staging")
             ? "staging"
             : "production";
+        // Show the transparency notice once, on the first enabled run.
+        noticePending = !cfg.telemetryNoticeShown;
         const creds = config_1.credentials.read();
-        distinctId = ((_a = creds === null || creds === void 0 ? void 0 : creds.user) === null || _a === void 0 ? void 0 : _a.id) || anonMachineId();
+        authenticatedUser = Boolean((_a = creds === null || creds === void 0 ? void 0 : creds.user) === null || _a === void 0 ? void 0 : _a.id);
+        distinctId = ((_b = creds === null || creds === void 0 ? void 0 : creds.user) === null || _b === void 0 ? void 0 : _b.id) || getOrCreateInstallId(cfg.installId);
         posthog = new posthog_node_1.PostHog(environment === "staging" ? POSTHOG_KEY_STAGING : POSTHOG_KEY_PROD, { host: POSTHOG_HOST, flushAt: 1, flushInterval: 0 });
-        if ((_b = creds === null || creds === void 0 ? void 0 : creds.user) === null || _b === void 0 ? void 0 : _b.email) {
+        if ((_c = creds === null || creds === void 0 ? void 0 : creds.user) === null || _c === void 0 ? void 0 : _c.email) {
             // Attach identity so CLI events attribute to the same person as the app.
             posthog.identify({
                 distinctId,
@@ -88,7 +118,7 @@ function initTelemetry() {
                 release: `apso-cli@${cliVersion}`,
                 tracesSampleRate: 0,
             });
-            Sentry.setUser({ id: distinctId, email: (_c = creds === null || creds === void 0 ? void 0 : creds.user) === null || _c === void 0 ? void 0 : _c.email });
+            Sentry.setUser({ id: distinctId, email: (_d = creds === null || creds === void 0 ? void 0 : creds.user) === null || _d === void 0 ? void 0 : _d.email });
             Sentry.setTag("cli_version", cliVersion);
             sentryOn = true;
         }
@@ -105,9 +135,35 @@ function commonProps() {
         os: os_1.default.platform(),
         arch: os_1.default.arch(),
         node_version: process.version,
-        authenticated: distinctId !== anonMachineId() && !distinctId.startsWith("cli_"),
+        authenticated: authenticatedUser,
     };
 }
+/**
+ * The one-time transparency notice text (issue #96). Printed to stderr by the
+ * init hook so it never pollutes stdout / piped output.
+ */
+exports.FIRST_RUN_NOTICE = "Apso collects anonymous usage data (command name, CLI version, OS) to improve the tool.\n" +
+    "No code, schema, file contents, or personal data is collected.\n" +
+    "Opt out any time: apso config set telemetry off  (or APSO_TELEMETRY=0, or DO_NOT_TRACK=1)";
+/**
+ * True once per install: telemetry is enabled and the notice hasn't been shown
+ * yet. The init hook prints the notice and then calls markFirstRunNoticeShown().
+ */
+function shouldShowFirstRunNotice() {
+    return enabled && noticePending;
+}
+exports.shouldShowFirstRunNotice = shouldShowFirstRunNotice;
+/** Persist that the transparency notice has been shown. Best-effort. */
+function markFirstRunNoticeShown() {
+    noticePending = false;
+    try {
+        config_1.globalConfig.write({ telemetryNoticeShown: true });
+    }
+    catch {
+        // ignore — worst case the notice shows again next run
+    }
+}
+exports.markFirstRunNoticeShown = markFirstRunNoticeShown;
 /** Emit a PostHog event. No-op when disabled. */
 function track(event, properties = {}) {
     try {
@@ -159,4 +215,4 @@ async function shutdownTelemetry() {
     }
 }
 exports.shutdownTelemetry = shutdownTelemetry;
-exports.__testing = { isDisabled, anonMachineId };
+exports.__testing = { isDisabled, anonMachineId, getOrCreateInstallId };

package/dist/lib/templates/entities/entity.eta

@@ -47,7 +47,7 @@ import {<%= assocName %>} from '../<%= assocName %>/<%= assocName %>.entity';
 
 const { CREATE, UPDATE } = CrudValidationGroups;
 
-@Entity('<%= it.snakeCasedName %>')
+@Entity('<%= it.tableName %>')
 <% it.indexes.forEach((index) => { %>
 @Index([<%~ index.fields.map((field) => `"${field}"`).join(', ') %>]<% if (index.unique) { %>, { unique: true } <% } %>)
 <% }) %>

package/dist/lib/templates/go/events/event-emitting-entities.eta

@@ -0,0 +1,21 @@
+<%~ includeFile('../header.eta') %>
+package events
+
+import "app/autogen/models"
+
+// Schema-derived manifest of entities that opted in to domain-event emission
+// (.apsorc `emitEvents`). The domain-event engine itself (the transactional
+// GORM hook/callback, mapper, relay, and delivery) is NOT generated here; it
+// ships as a versioned library wired by the `domain-events` skill. This file
+// only declares WHICH entities participate, mirroring the TypeScript manifest.
+
+// EventEmittingModels are the opted-in model instances (for the engine to
+// register GORM hooks/callbacks against).
+var EventEmittingModels = []interface{}{
+<% it.emittingEntities.forEach((entity) => { %>	models.<%= entity.name %>{},
+<% }) %>}
+
+// EventEmittingEntityNames are the opted-in entity names.
+var EventEmittingEntityNames = []string{
+<% it.emittingEntities.forEach((entity) => { %>	"<%= entity.name %>",
+<% }) %>}

package/dist/lib/templates/go/index-module.eta

@@ -1,17 +1,17 @@
 <%~ includeFile('./header.eta', it) %>
-
+<% const httpEntities = it.entities.filter((entity) => entity.http); %>
 package routes
 
 import (
-	"app/autogen/handlers"
-	"app/autogen/services"
+<% if (httpEntities.length > 0) { %>	"app/autogen/handlers"
+<% } %>	"app/autogen/services"
 	"github.com/gin-gonic/gin"
 	"gorm.io/gorm"
 )
 
 // RegisterAllRoutes registers all entity routes
 func RegisterAllRoutes(r *gin.RouterGroup, db *gorm.DB) {
-<% it.entities.forEach((entity) => { %>
+<% httpEntities.forEach((entity) => { %>
 	// <%= entity.name %> routes
 	<%= entity.camelName %>Service := services.New<%= entity.name %>Service(db)
 	<%= entity.camelName %>Handler := handlers.New<%= entity.name %>Handler(<%= entity.camelName %>Service)
@@ -38,7 +38,7 @@ func NewServices(db *gorm.DB) *Services {
 
 // Handlers holds all handler instances
 type Handlers struct {
-<% it.entities.forEach((entity) => { %>
+<% httpEntities.forEach((entity) => { %>
 	<%= entity.name %>Handler *handlers.<%= entity.name %>Handler
 <% }) %>
 }
@@ -46,7 +46,7 @@ type Handlers struct {
 // NewHandlers creates all handler instances
 func NewHandlers(s *Services) *Handlers {
 	return &Handlers{
-<% it.entities.forEach((entity) => { %>
+<% httpEntities.forEach((entity) => { %>
 		<%= entity.name %>Handler: handlers.New<%= entity.name %>Handler(s.<%= entity.name %>Service),
 <% }) %>
 	}

package/dist/lib/templates/python/events/event-emitting-entities.eta

@@ -0,0 +1,22 @@
+<%~ includeFile('../header.eta') %>
+<% it.emittingEntities.forEach((entity) => { %>
+from ..models.<%= entity.name.toLowerCase() %> import <%= entity.name %>
+<% }) %>
+
+# Schema-derived manifest of entities that opted in to domain-event emission
+# (`.apsorc` `emitEvents`). The domain-event engine itself (the transactional
+# SQLAlchemy session hook, mapper, relay, and delivery) is NOT generated here;
+# it ships as a versioned library wired by the `domain-events` skill. This file
+# only declares WHICH entities participate, mirroring the TypeScript manifest.
+
+EVENT_EMITTING_ENTITIES = [
+<% it.emittingEntities.forEach((entity) => { %>
+    <%= entity.name %>,
+<% }) %>
+]
+
+EVENT_EMITTING_ENTITY_NAMES = [
+<% it.emittingEntities.forEach((entity) => { %>
+    "<%= entity.name %>",
+<% }) %>
+]

package/dist/lib/types/entity.d.ts

@@ -26,6 +26,12 @@ export interface ScopeOptions {
 }
 export interface Entity {
     name: string;
+    /**
+     * Explicit database table name. When set, it overrides the default table
+     * name derived from `name` (snake_case). Use it to avoid SQL reserved words
+     * (e.g. an entity `Order` deriving to the reserved word `order`).
+     */
+    table?: string;
     created_at?: boolean;
     updated_at?: boolean;
     primaryKeyType?: "serial" | "uuid";

package/dist/lib/types/generator.d.ts

@@ -246,6 +246,7 @@ export interface LanguageGenerator {
      */
     generateIndexModule(entities: Entity[], apiType: string, opts?: {
         emitEvents?: boolean;
+        http?: boolean;
     }): Promise<GeneratedFile[]>;
     /**
      * Generate guard files (auth, scope, etc.)

package/dist/lib/utils/template.d.ts

@@ -6,6 +6,16 @@ export declare const PROJECT_NAME_PATTERN: RegExp;
  * Removes the .git directory after cloning.
  */
 export declare function cloneTemplate(projectPath: string, language: TargetLanguage, log: (msg: string) => void): void;
+/**
+ * Ensure the scaffolded project has a `.env` file.
+ *
+ * Templates ship `.env.local` (and `.env.example`) but the NestJS env loader
+ * reads `.env` by default, so a fresh scaffold would silently ignore the
+ * shipped values and run on built-in defaults (wrong port, wrong database).
+ * Copy `.env.local` (preferred) or `.env.example` to `.env` when no `.env`
+ * exists yet. See apsoai/cli#103.
+ */
+export declare function ensureEnvFile(projectPath: string, log: (msg: string) => void): void;
 /**
  * Initialize a fresh git repository in the given directory.
  */

package/dist/lib/utils/template.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.initGitRepo = exports.cloneTemplate = exports.PROJECT_NAME_PATTERN = exports.TEMPLATE_REPOS = void 0;
+exports.initGitRepo = exports.ensureEnvFile = exports.cloneTemplate = exports.PROJECT_NAME_PATTERN = exports.TEMPLATE_REPOS = void 0;
 const tslib_1 = require("tslib");
 const fs = tslib_1.__importStar(require("fs"));
 const path = tslib_1.__importStar(require("path"));
@@ -35,8 +35,32 @@ function cloneTemplate(projectPath, language, log) {
             `Please check your network connection and ensure the repository exists at ${repoUrl}`);
     }
     shelljs_1.default.rm("-rf", path.join(projectPath, ".git"));
+    ensureEnvFile(projectPath, log);
 }
 exports.cloneTemplate = cloneTemplate;
+/**
+ * Ensure the scaffolded project has a `.env` file.
+ *
+ * Templates ship `.env.local` (and `.env.example`) but the NestJS env loader
+ * reads `.env` by default, so a fresh scaffold would silently ignore the
+ * shipped values and run on built-in defaults (wrong port, wrong database).
+ * Copy `.env.local` (preferred) or `.env.example` to `.env` when no `.env`
+ * exists yet. See apsoai/cli#103.
+ */
+function ensureEnvFile(projectPath, log) {
+    const envPath = path.join(projectPath, ".env");
+    if (fs.existsSync(envPath))
+        return;
+    for (const source of [".env.local", ".env.example"]) {
+        const sourcePath = path.join(projectPath, source);
+        if (fs.existsSync(sourcePath)) {
+            fs.copyFileSync(sourcePath, envPath);
+            log(`Created .env from ${source}`);
+            return;
+        }
+    }
+}
+exports.ensureEnvFile = ensureEnvFile;
 /**
  * Initialize a fresh git repository in the given directory.
  */