@apso/cli 0.28.0 → 0.29.0

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/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.28.0",
+  "version": "0.29.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@apso/cli",
-      "version": "0.28.0",
+      "version": "0.29.0",
       "license": "Apache-2.0",
       "dependencies": {
         "@biomejs/biome": "^1.9.4",

package/oclif.manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.28.0",
+  "version": "0.29.0",
   "commands": {
     "config": {
       "id": "config",
@@ -14,6 +14,7 @@
         "$ apso config",
         "$ apso config get apiUrl",
         "$ apso config set verbose true",
+        "$ apso config set telemetry off",
         "$ apso config reset"
       ],
       "flags": {},

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@apso/cli",
-  "version": "0.28.0",
+  "version": "0.29.0",
   "mcpName": "io.github.apsoai/apso",
   "description": "Apso CLI",
   "author": "Apso by Mavric - @mavric",