@apso/cli 0.43.4 → 0.45.0

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

@@ -16,7 +16,9 @@ export declare class PythonGenerator 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?: {
+        auth?: AuthConfig;
+    }): Promise<GeneratedFile[]>;
     /**
      * Emits a schema-derived manifest of the entities that opted in to
      * domain-event emission (`.apsorc` `emitEvents`), mirroring the TypeScript
@@ -35,6 +37,6 @@ export declare class PythonGenerator extends BaseGenerator {
     generateDomainEvents(entities: Entity[], _apiType?: string, opts?: {
         emitEvents?: boolean;
     }): Promise<GeneratedFile[]>;
-    generateGuards(_entities: Entity[], _auth?: AuthConfig): Promise<GeneratedFile[]>;
+    generateGuards(entities: Entity[], auth?: AuthConfig): Promise<GeneratedFile[]>;
     generateQueryUtils(_entities: Entity[], _apiType: string): Promise<GeneratedFile[]>;
 }

package/dist/lib/generators/python.js

@@ -5,10 +5,13 @@ const tslib_1 = require("tslib");
 const path = tslib_1.__importStar(require("path"));
 const Eta = tslib_1.__importStar(require("eta"));
 const base_1 = require("./base");
+const types_1 = require("../types");
 const field_1 = require("../utils/field");
 const relationships_1 = require("../utils/relationships");
 const casing_1 = require("../utils/casing");
 const events_1 = require("../events");
+const guards_1 = require("../guards");
+const migration_file_1 = require("../ddl/migration-file");
 const pluralize_1 = tslib_1.__importDefault(require("pluralize"));
 /**
  * Python/FastAPI generator that produces SQLAlchemy models, Pydantic schemas,
@@ -225,10 +228,10 @@ class PythonGenerator extends base_1.BaseGenerator {
         const name = migrationName || "auto";
         const filename = `${timestamp}_${name}.py`;
         const upStatements = upSql
-            .map((sql) => `    op.execute("""${sql}""")`)
+            .map((sql) => `    op.execute(${(0, migration_file_1.pyString)(sql)})`)
             .join("\n");
         const downStatements = (downSql || [])
-            .map((sql) => `    op.execute("""${sql}""")`)
+            .map((sql) => `    op.execute(${(0, migration_file_1.pyString)(sql)})`)
             .join("\n");
         const content = `"""${name}"""
 from alembic import op
@@ -278,8 +281,11 @@ ${downStatements || "    pass"}
             },
         ];
     }
-    async generateIndexModule(entities, _apiType) {
-        const content = await this.renderTemplate("./index-module", { entities });
+    async generateIndexModule(entities, _apiType, opts) {
+        const content = await this.renderTemplate("./index-module", {
+            entities,
+            hasAuth: Boolean(opts === null || opts === void 0 ? void 0 : opts.auth),
+        });
         return [
             {
                 path: "__init__.py",
@@ -319,10 +325,27 @@ ${downStatements || "    pass"}
             },
         ];
     }
-    async generateGuards(_entities, _auth) {
-        // Python auth/guards would be implemented differently (e.g., FastAPI dependencies)
-        // This is a placeholder for future implementation
-        return [];
+    async generateGuards(entities, auth) {
+        if (!auth)
+            return [];
+        if ((0, guards_1.hasScopedEntities)(entities))
+            console.warn("[apso] scopeBy is enforced in TypeScript services only; this Python service authenticates requests but does not filter rows by tenant");
+        let data;
+        if ((0, types_1.isJwtAuth)(auth)) {
+            data = { jwt: (0, types_1.resolveJwtAuth)(auth) };
+        }
+        else if ((0, types_1.isApiKeyAuth)(auth)) {
+            const apiKey = (0, guards_1.apiKeyTemplateData)((0, types_1.resolveApiKeyAuth)(auth), entities);
+            data = {
+                apiKey: { ...apiKey, pyModule: apiKey.apiKeyEntity.toLowerCase() },
+            };
+        }
+        else {
+            throw new Error(`auth.provider "${auth.provider}" is generated for TypeScript services only. For Python, use "jwt" (Better Auth issues JWTs with its JWT plugin) or "api-key".`);
+        }
+        return [
+            { path: "auth.py", content: await this.renderTemplate("./auth", data) },
+        ];
     }
     async generateQueryUtils(_entities, _apiType) {
         const queryContent = await this.renderTemplate("./utils/query", {});

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

@@ -16,8 +16,9 @@ export declare class TypeScriptGenerator extends BaseGenerator {
     generateModule(options: EntityGenerationOptions): Promise<GeneratedFile[]>;
     generateMigration(_options: MigrationGenerationOptions): Promise<GeneratedFile[]>;
     generateEnums(entities: Entity[], apiType: string): Promise<GeneratedFile[]>;
-    generateIndexModule(entities: Entity[], apiType: string, _opts?: {
+    generateIndexModule(entities: Entity[], apiType: string, opts?: {
         emitEvents?: boolean;
+        auth?: AuthConfig;
     }): Promise<GeneratedFile[]>;
     generateGuards(entities: Entity[], auth?: AuthConfig): Promise<GeneratedFile[]>;
     /**

package/dist/lib/generators/typescript.js

@@ -109,7 +109,8 @@ class TypeScriptGenerator extends base_1.BaseGenerator {
         ];
     }
     async generateController(options) {
-        const { entity, relationships, relationshipMap } = options;
+        var _a, _b;
+        const { entity, relationships, relationshipMap, auth } = options;
         const { name: entityName } = entity;
         const relationshipsForTemplate = (0, relationships_1.getRelationshipForTemplate)(entityName, relationships);
         // Handle nested relationships for joins
@@ -135,6 +136,12 @@ class TypeScriptGenerator extends base_1.BaseGenerator {
             primaryKeyType,
             associations: [...new Set(relationshipsForTemplate)],
             nestedJoinsFile,
+            // Direct scopeBy fields @CrudAuth adds to every query once a caller is
+            // authenticated. Nested scopes (task.workspaceId) are checked per row by
+            // ScopeGuard only.
+            crudAuth: auth
+                ? ((_b = (_a = (0, guards_1.getScopedEntities)([entity])[0]) === null || _a === void 0 ? void 0 : _a.scopes) !== null && _b !== void 0 ? _b : []).filter((s) => s.direct)
+                : [],
         };
         const controllerContent = await this.renderTemplate("./rest/controller-rest", data);
         const specContent = await this.renderTemplate("./rest/controller-rest-spec", data);
@@ -307,8 +314,13 @@ class TypeScriptGenerator extends base_1.BaseGenerator {
             },
         ];
     }
-    async generateIndexModule(entities, apiType, _opts) {
-        const content = await this.renderTemplate(`./${apiType}/index-module-${apiType}`, { entities });
+    async generateIndexModule(entities, apiType, opts) {
+        // generateGuards emits GuardsModule whenever auth or scopeBy is configured;
+        // listing it here is what turns its global guards on.
+        const content = await this.renderTemplate(`./${apiType}/index-module-${apiType}`, {
+            entities,
+            hasGuards: Boolean(opts === null || opts === void 0 ? void 0 : opts.auth) || (0, guards_1.hasScopedEntities)(entities),
+        });
         return [
             {
                 path: "index.ts",
@@ -319,20 +331,45 @@ class TypeScriptGenerator extends base_1.BaseGenerator {
     async generateGuards(entities, auth) {
         const hasScopes = (0, guards_1.hasScopedEntities)(entities);
         const normalizedAuth = this.normalizeAuthConfig(auth);
-        if (!hasScopes && !normalizedAuth) {
+        const jwt = auth && (0, auth_1.isJwtAuth)(auth) ? (0, auth_1.resolveJwtAuth)(auth) : undefined;
+        const apiKey = auth && (0, auth_1.isApiKeyAuth)(auth)
+            ? (0, guards_1.apiKeyTemplateData)((0, auth_1.resolveApiKeyAuth)(auth), entities)
+            : undefined;
+        const hasAuth = Boolean(normalizedAuth || jwt || apiKey);
+        if (!hasScopes && !hasAuth) {
             return [];
         }
         const scopedEntities = (0, guards_1.getScopedEntities)(entities);
         const files = [];
+        const authEntities = normalizedAuth
+            ? [
+                normalizedAuth.sessionEntity,
+                normalizedAuth.userEntity,
+                ...(normalizedAuth.accountUserEntity
+                    ? [normalizedAuth.accountUserEntity]
+                    : []),
+            ]
+            : apiKey
+                ? [apiKey.apiKeyEntity]
+                : [];
         const templateData = {
             scopedEntities,
             authConfig: normalizedAuth,
+            hasAuth,
+            authProvider: auth === null || auth === void 0 ? void 0 : auth.provider,
+            authEntities,
+            jwt,
+            apiKey,
             generatedAt: new Date().toISOString(),
             generatedBy: "Apso CLI",
         };
         // Generate auth.guard.ts if auth is configured
-        if (normalizedAuth) {
-            const authGuardContent = await this.renderTemplate("./guards/auth.guard.eta", templateData);
+        if (hasAuth) {
+            const authGuardContent = await this.renderTemplate(jwt
+                ? "./guards/jwt-auth.guard.eta"
+                : apiKey
+                    ? "./guards/api-key-auth.guard.eta"
+                    : "./guards/auth.guard.eta", templateData);
             files.push({
                 path: "guards/auth.guard.ts",
                 content: authGuardContent,

package/dist/lib/guards.d.ts

@@ -1,4 +1,4 @@
-import { Entity } from "./types";
+import { Entity, ResolvedApiKeyAuth } from "./types";
 /**
  * Represents a scope field configuration for template rendering
  */
@@ -28,3 +28,13 @@ export declare function getScopedEntities(entities: Entity[]): ScopedEntityConfi
  * Checks if any entities have scopeBy configured.
  */
 export declare function hasScopedEntities(entities: Entity[]): boolean;
+/** API key settings plus what the key entity offers, as the guard templates use them. */
+export interface ApiKeyTemplateData extends ResolvedApiKeyAuth {
+    hasStatus: boolean;
+    hasExpiresAt: boolean;
+}
+/**
+ * Check the API key entity exists and has the hash field, and note whether it
+ * has `status` and `expiresAt`, which the guard then enforces.
+ */
+export declare function apiKeyTemplateData(apiKey: ResolvedApiKeyAuth, entities: Entity[]): ApiKeyTemplateData;

package/dist/lib/guards.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.hasScopedEntities = exports.getScopedEntities = void 0;
+exports.apiKeyTemplateData = exports.hasScopedEntities = exports.getScopedEntities = void 0;
 const tslib_1 = require("tslib");
 const pluralize_1 = tslib_1.__importDefault(require("pluralize"));
 /**
@@ -62,3 +62,22 @@ function hasScopedEntities(entities) {
     return entities.some((entity) => entity.scopeBy);
 }
 exports.hasScopedEntities = hasScopedEntities;
+/**
+ * Check the API key entity exists and has the hash field, and note whether it
+ * has `status` and `expiresAt`, which the guard then enforces.
+ */
+function apiKeyTemplateData(apiKey, entities) {
+    var _a;
+    const entity = entities.find((e) => e.name === apiKey.apiKeyEntity);
+    if (!entity)
+        throw new Error(`auth.apiKeyEntity "${apiKey.apiKeyEntity}" is not an entity in .apsorc; add it with a "${apiKey.keyField}" text field`);
+    const fields = new Set(((_a = entity.fields) !== null && _a !== void 0 ? _a : []).map((f) => f.name));
+    if (!fields.has(apiKey.keyField))
+        throw new Error(`Entity ${apiKey.apiKeyEntity} needs a "${apiKey.keyField}" text field holding each key's hex SHA-256 (auth.keyField)`);
+    return {
+        ...apiKey,
+        hasStatus: fields.has("status"),
+        hasExpiresAt: fields.has("expiresAt"),
+    };
+}
+exports.apiKeyTemplateData = apiKeyTemplateData;

package/dist/lib/plan/baseline.d.ts

@@ -0,0 +1,22 @@
+import { ApsorcType } from "../apsorc-parser";
+export interface SavedPlan {
+    before: ApsorcType;
+    after: ApsorcType;
+}
+export interface Baseline {
+    schema: ApsorcType;
+    /** Where the schema came from, for messages. */
+    source: string;
+}
+/** Where each language's migrations live, and the extension of one. */
+export declare const migrationsDir: (projectDir: string, apsorc?: ApsorcType) => string;
+export declare const migrationExtension: (apsorc?: ApsorcType) => ".ts" | ".py" | ".sql";
+/** The newest migration with a saved plan, by its timestamp prefix. */
+export declare function latestPlannedMigration(projectDir: string, apsorc?: ApsorcType): {
+    file: string;
+    planFile: string;
+    saved: SavedPlan;
+} | undefined;
+export declare function resolveBaseline(projectDir: string, apsorc: ApsorcType, explicit?: string, planPath?: string): Baseline;
+/** A baseline as a file, for steps that scaffold it into a project copy. */
+export declare function baselineFile(baseline: Baseline): string;

package/dist/lib/plan/baseline.js

@@ -0,0 +1,100 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.baselineFile = exports.resolveBaseline = exports.latestPlannedMigration = exports.migrationExtension = exports.migrationsDir = void 0;
+const tslib_1 = require("tslib");
+/**
+ * Find the deployed schema without being told. Every migration
+ * `apso migrate generate` writes is committed with its plan, and the plan
+ * records the schema before and after it, so the newest one says what the
+ * database looks like once the migrations run. A service whose migrations
+ * predate this falls back to the .apsorc from the last commit that touched
+ * its migrations.
+ */
+const child_process_1 = require("child_process");
+const fs = tslib_1.__importStar(require("fs"));
+const os = tslib_1.__importStar(require("os"));
+const path = tslib_1.__importStar(require("path"));
+/** Where each language's migrations live, and the extension of one. */
+const migrationsDir = (projectDir, apsorc) => (apsorc === null || apsorc === void 0 ? void 0 : apsorc.language) === "python"
+    ? path.join(projectDir, "alembic", "versions")
+    : (apsorc === null || apsorc === void 0 ? void 0 : apsorc.language) === "go"
+        ? path.join(projectDir, "migrations")
+        : path.join(projectDir, (apsorc === null || apsorc === void 0 ? void 0 : apsorc.rootFolder) || "src", "migrations");
+exports.migrationsDir = migrationsDir;
+const migrationExtension = (apsorc) => (apsorc === null || apsorc === void 0 ? void 0 : apsorc.language) === "python"
+    ? ".py"
+    : (apsorc === null || apsorc === void 0 ? void 0 : apsorc.language) === "go"
+        ? ".sql"
+        : ".ts";
+exports.migrationExtension = migrationExtension;
+/** The newest migration with a saved plan, by its timestamp prefix. */
+function latestPlannedMigration(projectDir, apsorc) {
+    const dir = (0, exports.migrationsDir)(projectDir, apsorc);
+    if (!fs.existsSync(dir))
+        return undefined;
+    const plans = fs
+        .readdirSync(dir)
+        .filter((f) => /^\d+[_-].+\.plan\.json$/.test(f))
+        .sort((a, b) => Number(b.split(/[_-]/)[0]) - Number(a.split(/[_-]/)[0]));
+    for (const planFile of plans) {
+        const saved = JSON.parse(fs.readFileSync(path.join(dir, planFile)).toString());
+        if (!saved.before || !saved.after)
+            continue;
+        const file = planFile.replace(/\.plan\.json$/, (0, exports.migrationExtension)(apsorc));
+        return {
+            file: path.relative(projectDir, path.join(dir, file)),
+            planFile: path.relative(projectDir, path.join(dir, planFile)),
+            saved,
+        };
+    }
+    return undefined;
+}
+exports.latestPlannedMigration = latestPlannedMigration;
+const git = (cwd, args) => (0, child_process_1.execFileSync)("git", args, {
+    cwd,
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "ignore"],
+});
+function resolveBaseline(projectDir, apsorc, explicit, planPath) {
+    if (explicit)
+        return {
+            schema: JSON.parse(fs.readFileSync(path.resolve(explicit)).toString()),
+            source: explicit,
+        };
+    // A plan in progress remembers the baseline it was started from.
+    if (planPath && fs.existsSync(planPath)) {
+        const working = JSON.parse(fs.readFileSync(planPath).toString());
+        if (working.before)
+            return {
+                schema: working.before,
+                source: path.relative(projectDir, planPath),
+            };
+    }
+    const latest = latestPlannedMigration(projectDir, apsorc);
+    if (latest)
+        return { schema: latest.saved.after, source: latest.planFile };
+    try {
+        const dir = path.relative(projectDir, (0, exports.migrationsDir)(projectDir, apsorc));
+        const sha = git(projectDir, ["log", "-1", "--format=%H", "--", dir]).trim();
+        if (sha) {
+            // "<sha>:./.apsorc" is relative to cwd, so symlinked paths don't matter.
+            const schema = JSON.parse(git(projectDir, ["show", `${sha}:./.apsorc`]));
+            return {
+                schema,
+                source: `.apsorc at ${sha.slice(0, 7)}, the last commit that changed ${dir}`,
+            };
+        }
+    }
+    catch {
+        // No git, no history for the migrations, or no .apsorc in that commit.
+    }
+    throw new Error("Can't tell which schema is deployed: no migration from apso migrate generate yet, and no git history for the migrations folder. Pass the deployed .apsorc once with --baseline; later runs find it on their own.");
+}
+exports.resolveBaseline = resolveBaseline;
+/** A baseline as a file, for steps that scaffold it into a project copy. */
+function baselineFile(baseline) {
+    const file = path.join(fs.mkdtempSync(path.join(os.tmpdir(), "apso-baseline-")), ".apsorc");
+    fs.writeFileSync(file, JSON.stringify(baseline.schema, null, 2));
+    return file;
+}
+exports.baselineFile = baselineFile;

package/dist/lib/plan/index.d.ts

@@ -0,0 +1,52 @@
+interface PlanField {
+    name: string;
+    type: string;
+    values?: string[];
+    nullable?: boolean;
+    default?: string | null;
+}
+interface PlanEntity {
+    name: string;
+    fields?: PlanField[];
+}
+interface PlanRelationship {
+    from: string;
+    to: string;
+    type: string;
+}
+export interface PlanSchema {
+    entities: PlanEntity[];
+    relationships?: PlanRelationship[];
+}
+export type QuestionKind = "removedField" | "removedEntity" | "enumValue" | "backfill" | "cast" | "relation";
+export interface Question {
+    id: string;
+    kind: QuestionKind;
+    /** What changed, in words, for the agent and the person reading the plan. */
+    subject: string;
+    /** Allowed answers. "sql" and "split:..." also need `sql`. */
+    options: string[];
+    /** Set only when exactly one reading fits; still needs an answer. */
+    suggested?: string;
+    answer?: string;
+    /** A SQL expression, or one per target field for a split. */
+    sql?: string | Record<string, string>;
+}
+export interface Plan {
+    version: 1;
+    from: string;
+    to: string;
+    questions: Question[];
+}
+export declare const hashSchema: (s: PlanSchema) => string;
+/** Every answer this question will accept is valid; anything else stays open. */
+export declare function isAnswered(q: Question): boolean;
+export declare const openQuestions: (plan: Plan) => Question[];
+export declare function planMigration(before: PlanSchema, after: PlanSchema, previous?: Plan): Plan;
+/**
+ * Plan with --answer values (<question id>=<option>) applied on top of the
+ * plan in progress. Throws a message for the user when an answer is malformed,
+ * names no question, or is not one of its options.
+ */
+export declare function planWithAnswers(before: PlanSchema, after: PlanSchema, previous: Plan | undefined, answers: string[]): Plan;
+export {};