@apso/cli 0.27.0 → 0.29.0

package/dist/lib/generators/base.d.ts

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

package/dist/lib/generators/go.d.ts

@@ -32,7 +32,28 @@ export declare class GoGenerator extends BaseGenerator {
     generateModule(_options: EntityGenerationOptions): Promise<GeneratedFile[]>;
     generateMigration(options: MigrationGenerationOptions): Promise<GeneratedFile[]>;
     generateEnums(entities: Entity[], _apiType: string): Promise<GeneratedFile[]>;
-    generateIndexModule(entities: Entity[], _apiType: string): Promise<GeneratedFile[]>;
+    generateIndexModule(entities: Entity[], _apiType: string, opts?: {
+        emitEvents?: boolean;
+        http?: boolean;
+    }): Promise<GeneratedFile[]>;
+    /**
+     * Emits a schema-derived manifest of the entities that opted in to
+     * domain-event emission (`.apsorc` `emitEvents`), mirroring the TypeScript
+     * generator. See apsoai/cli#82.
+     *
+     * Per the Apso Distribution Model the domain-event engine (the transactional
+     * GORM hook/callback, mapper, relay, delivery) is NOT generated here; it
+     * ships as a versioned library wired by the `domain-events` skill. The CLI's
+     * only job is to declare WHICH entities participate, via a single generated
+     * file: `events/event_emitting_entities.go`.
+     *
+     * Returns an empty array when no entity is opted in.
+     *
+     * Resolution mirrors TS: `entity.emitEvents ?? <top-level emitEvents> ?? false`.
+     */
+    generateDomainEvents(entities: Entity[], _apiType?: string, opts?: {
+        emitEvents?: boolean;
+    }): Promise<GeneratedFile[]>;
     generateGuards(_entities: Entity[], auth?: AuthConfig): Promise<GeneratedFile[]>;
     generateQueryUtils(_entities: Entity[], _apiType: string): Promise<GeneratedFile[]>;
 }

package/dist/lib/generators/go.js

@@ -8,6 +8,7 @@ const base_1 = require("./base");
 const field_1 = require("../utils/field");
 const relationships_1 = require("../utils/relationships");
 const casing_1 = require("../utils/casing");
+const events_1 = require("../events");
 const pluralize_1 = tslib_1.__importDefault(require("pluralize"));
 /**
  * Go/Gin generator that produces GORM models, DTOs, Gin handlers,
@@ -336,12 +337,20 @@ ${downStatements}
             },
         ];
     }
-    async generateIndexModule(entities, _apiType) {
-        const entitiesData = entities.map((entity) => ({
-            name: entity.name,
-            camelName: (0, casing_1.camelCase)(entity.name),
-            kebabName: (0, casing_1.kebabCase)(entity.name),
-        }));
+    async generateIndexModule(entities, _apiType, opts) {
+        // Effective HTTP flag per entity (entity override > top-level default >
+        // true). When false we skip the handler + route registration but keep the
+        // service and model, matching the handler suppression in generate.ts.
+        // See apsoai/cli#95.
+        const entitiesData = entities.map((entity) => {
+            var _a, _b;
+            return ({
+                name: entity.name,
+                camelName: (0, casing_1.camelCase)(entity.name),
+                kebabName: (0, casing_1.kebabCase)(entity.name),
+                http: (_b = (_a = entity.http) !== null && _a !== void 0 ? _a : opts === null || opts === void 0 ? void 0 : opts.http) !== null && _b !== void 0 ? _b : true,
+            });
+        });
         const content = await this.renderTemplate("./index-module", {
             entities: entitiesData,
         });
@@ -370,6 +379,38 @@ ${modelRefs}
             },
         ];
     }
+    /**
+     * Emits a schema-derived manifest of the entities that opted in to
+     * domain-event emission (`.apsorc` `emitEvents`), mirroring the TypeScript
+     * generator. See apsoai/cli#82.
+     *
+     * Per the Apso Distribution Model the domain-event engine (the transactional
+     * GORM hook/callback, mapper, relay, delivery) is NOT generated here; it
+     * ships as a versioned library wired by the `domain-events` skill. The CLI's
+     * only job is to declare WHICH entities participate, via a single generated
+     * file: `events/event_emitting_entities.go`.
+     *
+     * Returns an empty array when no entity is opted in.
+     *
+     * Resolution mirrors TS: `entity.emitEvents ?? <top-level emitEvents> ?? false`.
+     */
+    async generateDomainEvents(entities, _apiType, opts) {
+        const emittingEntities = (0, events_1.getEventEmittingEntities)(entities, opts === null || opts === void 0 ? void 0 : opts.emitEvents);
+        if (emittingEntities.length === 0) {
+            return [];
+        }
+        const content = await this.renderTemplate("./events/event-emitting-entities", {
+            emittingEntities: emittingEntities.map((entity) => ({
+                name: entity.name,
+            })),
+        });
+        return [
+            {
+                path: "events/event_emitting_entities.go",
+                content,
+            },
+        ];
+    }
     async generateGuards(_entities, auth) {
         const content = await this.renderTemplate("./middleware/auth", {
             auth,

package/dist/lib/generators/python.d.ts

@@ -17,6 +17,24 @@ export declare class PythonGenerator extends BaseGenerator {
     generateMigration(options: MigrationGenerationOptions): Promise<GeneratedFile[]>;
     generateEnums(entities: Entity[], _apiType: string): Promise<GeneratedFile[]>;
     generateIndexModule(entities: Entity[], _apiType: string): Promise<GeneratedFile[]>;
+    /**
+     * Emits a schema-derived manifest of the entities that opted in to
+     * domain-event emission (`.apsorc` `emitEvents`), mirroring the TypeScript
+     * generator. See apsoai/cli#81.
+     *
+     * Per the Apso Distribution Model the domain-event engine (the transactional
+     * SQLAlchemy session hook, mapper, relay, delivery) is NOT generated here; it
+     * ships as a versioned library wired by the `domain-events` skill. The CLI's
+     * only job is to declare WHICH entities participate, via a single generated
+     * file: `events/event_emitting_entities.py`.
+     *
+     * Returns an empty array when no entity is opted in.
+     *
+     * Resolution mirrors TS: `entity.emitEvents ?? <top-level emitEvents> ?? false`.
+     */
+    generateDomainEvents(entities: Entity[], _apiType?: string, opts?: {
+        emitEvents?: boolean;
+    }): Promise<GeneratedFile[]>;
     generateGuards(_entities: Entity[], _auth?: AuthConfig): Promise<GeneratedFile[]>;
     generateQueryUtils(_entities: Entity[], _apiType: string): Promise<GeneratedFile[]>;
 }

package/dist/lib/generators/python.js

@@ -8,6 +8,7 @@ const base_1 = require("./base");
 const field_1 = require("../utils/field");
 const relationships_1 = require("../utils/relationships");
 const casing_1 = require("../utils/casing");
+const events_1 = require("../events");
 const pluralize_1 = tslib_1.__importDefault(require("pluralize"));
 /**
  * Python/FastAPI generator that produces SQLAlchemy models, Pydantic schemas,
@@ -281,6 +282,38 @@ ${downStatements || "    pass"}
             },
         ];
     }
+    /**
+     * Emits a schema-derived manifest of the entities that opted in to
+     * domain-event emission (`.apsorc` `emitEvents`), mirroring the TypeScript
+     * generator. See apsoai/cli#81.
+     *
+     * Per the Apso Distribution Model the domain-event engine (the transactional
+     * SQLAlchemy session hook, mapper, relay, delivery) is NOT generated here; it
+     * ships as a versioned library wired by the `domain-events` skill. The CLI's
+     * only job is to declare WHICH entities participate, via a single generated
+     * file: `events/event_emitting_entities.py`.
+     *
+     * Returns an empty array when no entity is opted in.
+     *
+     * Resolution mirrors TS: `entity.emitEvents ?? <top-level emitEvents> ?? false`.
+     */
+    async generateDomainEvents(entities, _apiType, opts) {
+        const emittingEntities = (0, events_1.getEventEmittingEntities)(entities, opts === null || opts === void 0 ? void 0 : opts.emitEvents);
+        if (emittingEntities.length === 0) {
+            return [];
+        }
+        const content = await this.renderTemplate("./events/event-emitting-entities", {
+            emittingEntities: emittingEntities.map((entity) => ({
+                name: entity.name,
+            })),
+        });
+        return [
+            {
+                path: "events/event_emitting_entities.py",
+                content,
+            },
+        ];
+    }
     async generateGuards(_entities, _auth) {
         // Python auth/guards would be implemented differently (e.g., FastAPI dependencies)
         // This is a placeholder for future implementation

package/dist/lib/generators/typescript.js

@@ -85,6 +85,9 @@ class TypeScriptGenerator extends base_1.BaseGenerator {
             createPrimaryKey,
             primaryKeyType,
             snakeCasedName: (0, casing_1.snakeCase)(name),
+            // Honor an explicit per-entity `table` override; otherwise derive from
+            // the entity name. See apsoai/cli#98.
+            tableName: entity.table || (0, casing_1.snakeCase)(name),
             createdAt,
             updatedAt,
             pluralizedName: (0, casing_1.camelCase)((0, pluralize_1.default)(name)),

package/dist/lib/git.js

@@ -55,7 +55,7 @@ exports.getOriginUrl = getOriginUrl;
 function parseRepoFullName(url) {
     if (!url)
         return null;
-    const m = url.match(/github\.com[:/]([^/]+)\/(.+?)(?:\.git)?\/?$/i);
+    const m = url.match(/github\.com[/:]([^/]+)\/(.+?)(?:\.git)?\/?$/i);
     return m ? `${m[1]}/${m[2]}` : null;
 }
 exports.parseRepoFullName = parseRepoFullName;

package/dist/lib/migrate/sandbox.js

@@ -67,7 +67,9 @@ function buildEntityClasses(entities, relationshipMap = {}) {
     const classMap = new Map();
     for (const entityDef of entities) {
         const className = entityDef.name;
-        const tableName = (0, casing_1.snakeCase)(entityDef.name);
+        // Honor an explicit per-entity `table` override so local migration tests
+        // match the generated entity's table name. See apsoai/cli#98.
+        const tableName = entityDef.table || (0, casing_1.snakeCase)(entityDef.name);
         const EntityClass = { [className]: class {
             } }[className];
         typeorm.Entity(tableName)(EntityClass);

package/dist/lib/telemetry/telemetry.d.ts

@@ -1,11 +1,29 @@
 declare function isDisabled(telemetryDisabled: boolean): boolean;
-/** 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). */
 declare function anonMachineId(): string;
+/**
+ * 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.
+ */
+declare function getOrCreateInstallId(currentInstallId?: string): string;
 /**
  * Initialize telemetry. Call once at process start (init hook). Safe to call
  * when disabled — it just no-ops everything downstream.
  */
 export declare function initTelemetry(): void;
+/**
+ * The one-time transparency notice text (issue #96). Printed to stderr by the
+ * init hook so it never pollutes stdout / piped output.
+ */
+export declare const FIRST_RUN_NOTICE: string;
+/**
+ * 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().
+ */
+export declare function shouldShowFirstRunNotice(): boolean;
+/** Persist that the transparency notice has been shown. Best-effort. */
+export declare function markFirstRunNoticeShown(): void;
 /** Emit a PostHog event. No-op when disabled. */
 export declare function track(event: string, properties?: Record<string, unknown>): void;
 /** Report an exception to Sentry. No-op when disabled. */
@@ -17,5 +35,6 @@ export declare function shutdownTelemetry(): Promise<void>;
 export declare const __testing: {
     isDisabled: typeof isDisabled;
     anonMachineId: typeof anonMachineId;
+    getOrCreateInstallId: typeof getOrCreateInstallId;
 };
 export {};

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.
  */

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "@apso/cli",
-  "version": "0.27.0",
+  "version": "0.29.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@apso/cli",
-      "version": "0.27.0",
+      "version": "0.29.0",
       "license": "Apache-2.0",
       "dependencies": {
         "@biomejs/biome": "^1.9.4",
@@ -17,6 +17,7 @@
         "@oclif/plugin-plugins": "^3",
         "@oclif/plugin-warn-if-update-available": "^2.1.1",
         "@sentry/node": "^10.68.0",
+        "adm-zip": "^0.6.0",
         "debug": "^4.3.4",
         "eta": "^2.0.0",
         "inquirer": "^8.2.7",
@@ -35,6 +36,7 @@
       "devDependencies": {
         "@jest/globals": "^29.5.0",
         "@oclif/test": "^2.4.7",
+        "@types/adm-zip": "^0.5.8",
         "@types/chai": "^4",
         "@types/inquirer": "^8.2.12",
         "@types/mocha": "^10",
@@ -2659,6 +2661,16 @@
         "url": "https://github.com/sponsors/isaacs"
       }
     },
+    "node_modules/@types/adm-zip": {
+      "version": "0.5.8",
+      "resolved": "https://registry.npmjs.org/@types/adm-zip/-/adm-zip-0.5.8.tgz",
+      "integrity": "sha512-RVVH7QvZYbN+ihqZ4kX/dMiowf6o+Jk1fNwiSdx0NahBJLU787zkULhGhJM8mf/obmLGmgdMM0bXsQTmyfbR7Q==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@types/node": "*"
+      }
+    },
     "node_modules/@types/babel__core": {
       "version": "7.20.1",
       "resolved": "https://registry.npmjs.org/@types/babel__core/-/babel__core-7.20.1.tgz",
@@ -3556,6 +3568,15 @@
         "node": ">=0.4.0"
       }
     },
+    "node_modules/adm-zip": {
+      "version": "0.6.0",
+      "resolved": "https://registry.npmjs.org/adm-zip/-/adm-zip-0.6.0.tgz",
+      "integrity": "sha512-XleryMhbuksdKtofnWZ9Sk+4CUTbms4Mb/EU32SZwToAyZ5RgVos/ki8n+yr0LWHOGKuakbXTuuYNHLQjhddgg==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=14.0"
+      }
+    },
     "node_modules/agent-base": {
       "version": "6.0.2",
       "resolved": "https://registry.npmjs.org/agent-base/-/agent-base-6.0.2.tgz",