@apso/cli 0.28.0 → 0.29.1

package/README.md

@@ -314,7 +314,7 @@ apso config reset                  # Reset to defaults
 | `webUrl` | string | Platform web URL |
 | `verbose` | boolean | Enable verbose output |
 | `noColor` | boolean | Disable colored output |
-| `telemetryDisabled` | boolean | Opt out of anonymous telemetry |
+| `telemetryDisabled` | boolean | Opt out of anonymous telemetry (or `apso config set telemetry off`) |
 | `defaultWorkspace` | string | Default workspace slug |
 
 Boolean values accept `true`/`false` or `1`/`0`.
@@ -327,6 +327,7 @@ Environment variables override config file values:
 | `APSO_WEB_URL` | `webUrl` |
 | `APSO_DEBUG=true` | `verbose` |
 | `NO_COLOR` or `APSO_NO_COLOR=true` | `noColor` |
+| `APSO_TELEMETRY=0` / `DO_NOT_TRACK=1` | `telemetryDisabled` |
 
 ### `apso schema`
 
@@ -348,6 +349,32 @@ apso [command] --help       # Show command help
 apso [command] --version    # Show CLI version
 ```
 
+## Telemetry & privacy
+
+The CLI sends anonymous usage data so we can see which commands are used and
+prioritize accordingly. It is opt-out and carries no personal data.
+
+**What is collected:** command name (`generate`, `init`, `deploy`, …), CLI
+version, OS and architecture, Node version, command duration and success, and
+an anonymous install id (a random UUID stored in your CLI config — not derived
+from any machine identifier). If you are logged in, events attribute to your
+Apso account, the same as the web app.
+
+**What is never collected:** your source code, your `.apsorc` or schema
+contents, file paths, environment variable values, or any other file contents.
+
+**Opt out** any of these ways:
+
+```bash
+apso config set telemetry off     # persisted in your CLI config
+export APSO_TELEMETRY=0            # per-shell
+export DO_NOT_TRACK=1             # honors the consoledonottrack.com standard
+```
+
+On first run the CLI prints a one-time notice pointing at these opt-outs.
+See [`docs/telemetry.md`](docs/telemetry.md) for full detail. Aggregate
+public download stats (npm/PyPI) are available via `node scripts/usage-stats.mjs`.
+
 ## Supported languages
 
 | Language | Framework | ORM | Status |

package/dist/commands/config.js

@@ -26,6 +26,19 @@ function parseBoolean(value) {
         return false;
     return null;
 }
+/**
+ * Parse the friendly `telemetry on|off` value into the underlying
+ * `telemetryDisabled` boolean. `off` (opt out) => disabled = true.
+ * Accepts on/off, enabled/disabled, and true/false/1/0.
+ */
+function parseTelemetryToggle(value) {
+    const lower = value.toLowerCase();
+    if (["off", "false", "0", "disabled", "no"].includes(lower))
+        return true;
+    if (["on", "true", "1", "enabled", "yes"].includes(lower))
+        return false;
+    return null;
+}
 class Config extends base_command_1.default {
     async run() {
         const { args, argv } = await this.parse(Config);
@@ -46,6 +59,11 @@ class Config extends base_command_1.default {
             if (!key) {
                 this.error("Usage: apso config get <key>");
             }
+            // Friendly read-alias: `telemetry` reports on/off from telemetryDisabled.
+            if (key === "telemetry") {
+                this.log(config_1.globalConfig.read().telemetryDisabled ? "off" : "on");
+                return;
+            }
             if (!VALID_KEYS.includes(key)) {
                 this.error(`Unknown key: ${key}\nValid keys: ${VALID_KEYS.join(", ")}`);
             }
@@ -59,6 +77,16 @@ class Config extends base_command_1.default {
             if (!key || value === undefined) {
                 this.error("Usage: apso config set <key> <value>");
             }
+            // Friendly write-alias: `telemetry on|off` maps to telemetryDisabled.
+            if (key === "telemetry") {
+                const disabled = parseTelemetryToggle(value);
+                if (disabled === null) {
+                    this.error(`Invalid telemetry value: ${value}. Use on or off.`);
+                }
+                config_1.globalConfig.set("telemetryDisabled", disabled);
+                this.log(`telemetry = ${disabled ? "off" : "on"}`);
+                return;
+            }
             if (!VALID_KEYS.includes(key)) {
                 this.error(`Unknown key: ${key}\nValid keys: ${VALID_KEYS.join(", ")}`);
             }
@@ -94,6 +122,7 @@ Config.examples = [
     `$ apso config`,
     `$ apso config get apiUrl`,
     `$ apso config set verbose true`,
+    `$ apso config set telemetry off`,
     `$ apso config reset`,
 ];
 Config.strict = false;

package/dist/commands/dev.d.ts

@@ -13,8 +13,17 @@ export default class Dev extends BaseCommand {
     /**
      * TypeScript: run `npm run dev` which reads DATABASE_TYPE from .env.
      * PGlite is handled natively by the NestJS app -- no sidecar needed.
+     *
+     * Prefer the `dev` script, but fall back to `start:dev` for templates that
+     * only define the latter (e.g. the v1 service template). See apsoai/cli#102.
      */
     private runTypeScript;
+    /**
+     * Return the first script from `candidates` that exists in the local
+     * package.json. If package.json is missing or unparseable, fall back to the
+     * first candidate so behavior is unchanged when we cannot inspect it.
+     */
+    private resolveNpmScript;
     /**
      * Python: if pglite, start the pglite-server sidecar first, then uvicorn.
      */

package/dist/commands/dev.js

@@ -52,10 +52,37 @@ class Dev extends base_command_1.default {
     /**
      * TypeScript: run `npm run dev` which reads DATABASE_TYPE from .env.
      * PGlite is handled natively by the NestJS app -- no sidecar needed.
+     *
+     * Prefer the `dev` script, but fall back to `start:dev` for templates that
+     * only define the latter (e.g. the v1 service template). See apsoai/cli#102.
      */
     async runTypeScript() {
-        this.log("Starting TypeScript dev server...");
-        await this.spawnAndWait("npm", ["run", "dev"]);
+        const script = this.resolveNpmScript(["dev", "start:dev"]);
+        if (!script) {
+            this.error('No "dev" or "start:dev" script found in package.json.\n' +
+                "Make sure you are in an Apso TypeScript project root.");
+        }
+        this.log(`Starting TypeScript dev server (npm run ${script})...`);
+        await this.spawnAndWait("npm", ["run", script]);
+    }
+    /**
+     * Return the first script from `candidates` that exists in the local
+     * package.json. If package.json is missing or unparseable, fall back to the
+     * first candidate so behavior is unchanged when we cannot inspect it.
+     */
+    resolveNpmScript(candidates) {
+        const pkgPath = path.resolve("package.json");
+        if (!fs.existsSync(pkgPath))
+            return candidates[0];
+        try {
+            // eslint-disable-next-line unicorn/prefer-json-parse-buffer -- JSON.parse's TS type requires a string, not a Buffer
+            const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf8"));
+            const scripts = (pkg.scripts || {});
+            return candidates.find((c) => typeof scripts[c] === "string");
+        }
+        catch {
+            return candidates[0];
+        }
     }
     /**
      * Python: if pglite, start the pglite-server sidecar first, then uvicorn.

package/dist/commands/generate.js

@@ -96,19 +96,31 @@ class Generate extends base_command_1.default {
             console.log(`[apso] Building... ${entity.name}`);
             const entityBuildStart = perf_hooks_1.performance.now();
             const entityRelationships = relationshipMap[entity.name] || [];
-            // Effective HTTP-controller flag (TypeScript REST only for now): entity
-            // overrides the top-level default, which defaults to true. When false, the
-            // controller is neither generated nor wired into the module (a hand-written
-            // controller owns the route). GraphQL uses resolvers, so the flag doesn't
-            // apply there. Python (FastAPI) and Go (Gin) wire routers differently and
-            // don't yet honor this flag — keep it a no-op for them (controllers always
-            // generated) so we never emit broken wiring (a skipped router still
-            // referenced by the index module). Tracked separately for Python/Go.
-            const includeController = language === "typescript" && lowerCaseApiType === "rest"
-                ? ((_b = (_a = entity.http) !== null && _a !== void 0 ? _a : http) !== null && _b !== void 0 ? _b : true)
-                : true;
-            if (!includeController) {
-                console.log(`[apso]   ${entity.name}: http=false — skipping generated controller`);
+            // Effective HTTP flag: entity overrides the top-level default, which
+            // defaults to true. GraphQL uses resolvers, so the flag doesn't apply
+            // there. The flag only does real suppression where a generated route
+            // can't be cleanly overridden without removing it (see apsoai/cli#95):
+            //   - TypeScript (NestJS): suppress the controller + its module wiring.
+            //   - Go (Gin): suppress the handler + its route registration (Gin
+            //     panics on a duplicate method+path, so overriding needs removal).
+            //   - Python (FastAPI): NO-OP. FastAPI matches in registration order, so
+            //     a hand-written APIRouter included before autogen_router in main.py
+            //     shadows the generated route without removing it. We only emit an
+            //     informational notice pointing at that pattern.
+            const effectiveHttp = (_b = (_a = entity.http) !== null && _a !== void 0 ? _a : http) !== null && _b !== void 0 ? _b : true;
+            const httpSuppressible = (language === "typescript" || language === "go") &&
+                lowerCaseApiType === "rest";
+            const includeController = httpSuppressible ? effectiveHttp : true;
+            if (httpSuppressible && !includeController) {
+                const artifact = language === "go" ? "handler + routes" : "controller";
+                console.log(`[apso]   ${entity.name}: http=false — skipping generated ${artifact}`);
+            }
+            else if (language === "python" &&
+                lowerCaseApiType === "rest" &&
+                effectiveHttp === false) {
+                console.log(`[apso]   ${entity.name}: http=false is a no-op for FastAPI — to replace a ` +
+                    `generated route, include your own APIRouter before autogen_router in main.py ` +
+                    `(first match wins). See the custom-endpoints skill.`);
             }
             const generationTasks = [
                 generator.generateEntity({
@@ -177,7 +189,7 @@ class Generate extends base_command_1.default {
             await (0, file_system_1.createFile)(fullPath, file.content);
         }
         // Generate index module
-        const indexFiles = await generator.generateIndexModule(entities, lowerCaseApiType, { emitEvents });
+        const indexFiles = await generator.generateIndexModule(entities, lowerCaseApiType, { emitEvents, http });
         for (const file of indexFiles) {
             const fullPath = path.join(autogenPath, file.path);
             // eslint-disable-next-line no-await-in-loop

package/dist/commands/github/connect.js

@@ -20,7 +20,9 @@ function openBrowser(url) {
         (0, child_process_1.exec)(command, () => resolve());
     });
 }
-const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+const sleep = (ms) => new Promise((r) => {
+    setTimeout(r, ms);
+});
 /**
  * `apso github connect` — walk the user through connecting their GitHub
  * account so the CLI can push generated code to a real repository.

package/dist/commands/link.js

@@ -81,6 +81,7 @@ class Link extends base_command_1.default {
         else if (flags.create) {
             this.log(`Creating service "${flags.create}"...`);
             service = await (0, upgrade_1.withUpgradeRetry)(() => services_1.servicesApi.create(workspace.id, { name: flags.create }));
+            // eslint-disable-next-line no-negated-condition -- clearer as a non-interactive guard in this else-if chain
         }
         else if (!(0, interactive_1.isInteractive)()) {
             this.error((0, interactive_1.missingFlag)("Pass --service <slug> to link an existing service, or --create <name> to make a new one."));

package/dist/commands/update.js

@@ -40,7 +40,7 @@ class Update extends base_command_1.default {
         }
         // Pick the upgrade command based on how the CLI was installed.
         const installRoot = `${this.config.root || ""} ${process.execPath}`;
-        const isBrew = /(?:Cellar|homebrew|\/opt\/homebrew)/i.test(installRoot);
+        const isBrew = /cellar|homebrew|\/opt\/homebrew/i.test(installRoot);
         const cmd = isBrew
             ? "brew upgrade apsoai/tap/apso"
             : "npm install -g @apso/cli@latest";

package/dist/commands/use.js

@@ -55,7 +55,8 @@ class Use extends base_command_1.default {
         this.log(`  Now using workspace: ${ws.name} (${ws.slug})`);
         // Show what's in the workspace so the next step is obvious.
         try {
-            const services = (await services_1.servicesApi.list(ws.id)).data;
+            const listed = await services_1.servicesApi.list(ws.id);
+            const services = listed.data;
             this.log("");
             if (services.length > 0) {
                 this.log("  Services:");

package/dist/hooks/init/telemetry.js

@@ -7,6 +7,12 @@ const telemetry_1 = require("../../lib/telemetry/telemetry");
  */
 const hook = async function (opts) {
     (0, telemetry_1.initTelemetry)();
+    // First-run transparency notice (issue #96). Printed to stderr so it never
+    // pollutes stdout / piped output, shown once per install.
+    if ((0, telemetry_1.shouldShowFirstRunNotice)()) {
+        process.stderr.write(`\n${telemetry_1.FIRST_RUN_NOTICE}\n\n`);
+        (0, telemetry_1.markFirstRunNoticeShown)();
+    }
     if (opts.id) {
         (0, telemetry_1.track)("cli_command_started", { command: opts.id });
     }

package/dist/lib/api/services.js

@@ -72,9 +72,9 @@ function adaptPaginated(raw, mapItem) {
     const items = Array.isArray(raw) ? raw : (_a = raw === null || raw === void 0 ? void 0 : raw.data) !== null && _a !== void 0 ? _a : [];
     const total = (_b = raw === null || raw === void 0 ? void 0 : raw.total) !== null && _b !== void 0 ? _b : items.length;
     const page = (_c = raw === null || raw === void 0 ? void 0 : raw.page) !== null && _c !== void 0 ? _c : 1;
-    const pageSize = items.length || 1;
+    const pageSize = items.length > 0 ? items.length : 1;
     return {
-        data: items.map(mapItem),
+        data: items.map((item) => mapItem(item)),
         meta: {
             total,
             page,
@@ -98,7 +98,7 @@ exports.authApi = {
      * clears stored credentials). Best-effort, never throws.
      */
     async logout() {
-        return;
+        // no-op: logout clears local credentials elsewhere; best-effort, never throws.
     },
 };
 /**
@@ -109,7 +109,7 @@ exports.workspacesApi = {
         var _a;
         const raw = await client_1.api.get("/api/workspaces");
         const items = Array.isArray(raw) ? raw : (_a = raw === null || raw === void 0 ? void 0 : raw.data) !== null && _a !== void 0 ? _a : [];
-        return items.map(adaptWorkspace);
+        return items.map((workspace) => adaptWorkspace(workspace));
     },
     async getById(id) {
         const raw = await client_1.api.get(`/api/workspaces/${id}`);
@@ -261,7 +261,9 @@ exports.buildApi = {
                 options.onProgress(status);
             if (status.status === "success" || status.status === "failed")
                 return status;
-            await new Promise((resolve) => setTimeout(resolve, pollInterval));
+            await new Promise((resolve) => {
+                setTimeout(resolve, pollInterval);
+            });
         }
         /* eslint-enable no-await-in-loop */
         throw new Error("Build timed out");

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

@@ -123,6 +123,16 @@ export interface GlobalConfigFile {
      * Disable telemetry
      */
     telemetryDisabled: boolean;
+    /**
+     * Anonymous install id (random UUID) for opt-out CLI telemetry. Generated
+     * once on first run and persisted here. Not derived from any machine
+     * identifier; carries no PII.
+     */
+    installId?: string;
+    /**
+     * Whether the first-run telemetry transparency notice has been shown.
+     */
+    telemetryNoticeShown: boolean;
 }
 /**
  * Project link stored in .apso/link.json

package/dist/lib/config/types.js

@@ -19,6 +19,7 @@ exports.DEFAULT_GLOBAL_CONFIG = {
     verbose: false,
     noColor: false,
     telemetryDisabled: false,
+    telemetryNoticeShown: false,
 };
 /**
  * Environment variables that can override configuration

package/dist/lib/deploy/server-push.d.ts

@@ -1,4 +1,5 @@
 /// <reference types="node" />
+/// <reference types="node" />
 /** Zip the project source into a buffer, skipping build/vcs/dependency dirs. */
 export declare function zipProject(cwd: string): Buffer;
 /**

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)),
@@ -118,7 +121,7 @@ class TypeScriptGenerator extends base_1.BaseGenerator {
         await (0, parse_1.streamNestedRelationships)(entityName, relationshipMap, nestedJoinsStream);
         nestedJoinsStream.end();
         await new Promise((resolve) => {
-            nestedJoinsStream.on("finish", resolve);
+            nestedJoinsStream.on("finish", () => resolve());
         });
         const svcName = `${entityName}Service`;
         const ctrlName = `${entityName}Controller`;

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 {};