@aventara/access 0.0.0-stage → 1.0.0-rc.1

package/dist/generator/namespace.facts.d.ts

@@ -0,0 +1,28 @@
+import type { AccessPolicies } from "../policies-contract.js";
+/** One relation of a Resource, as the generated row types follow it. */
+type RelationFacts = {
+    readonly name: string;
+    readonly target: string;
+    readonly cardinality: "one" | "many";
+};
+/** One Resource of the namespace. */
+export type ResourceFacts = {
+    readonly name: string;
+    /** The namespace that owns it, when it is not this file's. */
+    readonly foreign: string | undefined;
+    /** Its scalar fields, sorted. */
+    readonly fields: readonly string[];
+    /** Its relations, sorted by name. */
+    readonly relations: readonly RelationFacts[];
+};
+/** The namespace a generated client decides for. */
+export type NamespaceFacts = {
+    readonly namespace: string;
+    /** Its Resources, sorted by name. */
+    readonly resources: readonly ResourceFacts[];
+};
+/** The facts of a pulled policies file. */
+export declare const namespaceFactsOf: (namespace: string, policies: AccessPolicies) => NamespaceFacts;
+/** A property key as TypeScript writes it: bare when it is an identifier, quoted otherwise. */
+export declare const propertyKey: (name: string) => string;
+export {};

package/dist/generator/namespace.facts.js

@@ -0,0 +1,32 @@
+// What a generated client says about its namespace, read from the pulled policies
+// file alone: its Resources (its own and the foreign ones its rules read), each
+// one's scalar fields and relations. The policies file names fields, never their
+// types, so neither does the generated client. Every list is sorted, so the client's
+// text depends on the file's content and never on its member order.
+const byCodeUnit = (a, b) => a < b ? -1 : a > b ? 1 : 0;
+/** The facts of a pulled policies file. */
+export const namespaceFactsOf = (namespace, policies) => ({
+    namespace,
+    resources: Object.keys(policies.schema)
+        .sort(byCodeUnit)
+        .map((name) => {
+        const facts = policies.schema[name];
+        const relations = facts?.relations ?? {};
+        return {
+            name,
+            foreign: facts?.foreign,
+            fields: (facts?.fields ?? [])
+                .filter((field) => relations[field] === undefined)
+                .sort(byCodeUnit),
+            relations: Object.keys(relations)
+                .sort(byCodeUnit)
+                .map((relation) => ({
+                name: relation,
+                target: relations[relation]?.target ?? "",
+                cardinality: relations[relation]?.cardinality ?? "one",
+            })),
+        };
+    }),
+});
+/** A property key as TypeScript writes it: bare when it is an identifier, quoted otherwise. */
+export const propertyKey = (name) => /^[A-Za-z_$][\w$]*$/.test(name) ? name : JSON.stringify(name);

package/dist/generator/orm.translator.d.ts

@@ -0,0 +1,48 @@
+import type { AccessSchema } from "../access-schema.js";
+import type { NamespaceFacts } from "./namespace.facts.js";
+/** What `avaccess schema` read: the `AccessSchema`, and what it left out and why. */
+export type OrmSchemaReading = {
+    readonly schema: AccessSchema;
+    readonly skipped: readonly string[];
+};
+/** The typed functions a translator adds to the generated client. */
+export type OrmClientPart = {
+    /** Their declarations, in TypeScript. */
+    readonly text: string;
+    /** The names they add to the generated `access` object, in order. */
+    readonly members: readonly string[];
+    /** What they read from the translator's copied module, in the internal file. */
+    readonly imports: {
+        readonly values: readonly string[];
+        readonly types: readonly string[];
+    };
+    /** The copied module's types the client file re-exports. */
+    readonly exports: readonly string[];
+};
+/** What `avaccess generate` reads of a translator: `none`, or an ORM's. */
+export type ClientTranslator = {
+    /** The `--orm` value: `none`, or the ORM and its major, `prisma7`. */
+    readonly orm: string;
+    /** The ORM's name and major as a reader says them, `Prisma 7`; `undefined` for `none`. */
+    readonly title: string | undefined;
+    /** The package paths of the translator's own modules, copied after the decisions. */
+    readonly modules: readonly string[];
+    /** The functions the generated client adds for this ORM. */
+    clientPart(namespace: NamespaceFacts): OrmClientPart;
+};
+/** One ORM's translator: its client part, and its schema reader. */
+export type OrmTranslator = ClientTranslator & {
+    readonly title: string;
+    /** The schema `avaccess schema` reads when `--schema` is not given, from the project's root. */
+    readonly defaultSchema: string;
+    /** `avaccess schema`: the ORM's schema at `path` as an `AccessSchema`. */
+    readSchema(path: string): Promise<OrmSchemaReading>;
+};
+/** Every ORM translator, by its `--orm` value: what `avaccess schema` reads with. */
+export declare const ORM_TRANSLATORS: {
+    readonly [orm: string]: OrmTranslator;
+};
+/** Every translator `avaccess generate` takes, by its `--orm` value. */
+export declare const CLIENT_TRANSLATORS: {
+    readonly [orm: string]: ClientTranslator;
+};

package/dist/generator/orm.translator.js

@@ -0,0 +1,29 @@
+// The translator seam: one translator per ORM major, chosen with `--orm`. A client
+// translator gives `avaccess generate` the modules it copies after the decisions and
+// the typed functions the generated client adds for its ORM; an ORM translator also
+// gives `avaccess schema` the reader that turns its ORM's schema into an
+// `AccessSchema`. The decisions stay ORM-neutral: they answer in Aventara's `where`,
+// and only a translator speaks an ORM's words.
+//
+// `none` (the default for `generate`, ruled 2026-10-23) adds nothing: the client
+// answers in the neutral `where` and names no ORM. Prisma 7 is the first ORM
+// (`prisma7`). Drizzle follows as `drizzle1` once Drizzle ORM v1 is stable.
+import { prisma7Translator } from "./prisma7/prisma7.translator.js";
+/** Every ORM translator, by its `--orm` value: what `avaccess schema` reads with. */
+export const ORM_TRANSLATORS = {
+    prisma7: prisma7Translator,
+};
+/** `--orm none`: a client that answers in the neutral `where` and names no ORM. */
+const NO_TRANSLATOR = {
+    orm: "none",
+    title: undefined,
+    modules: [],
+    clientPart: () => ({
+        text: "",
+        members: [],
+        imports: { values: [], types: [] },
+        exports: [],
+    }),
+};
+/** Every translator `avaccess generate` takes, by its `--orm` value. */
+export const CLIENT_TRANSLATORS = { none: NO_TRANSLATOR, ...ORM_TRANSLATORS };

package/dist/generator/prisma7/prisma-schema.reader.d.ts

@@ -0,0 +1,9 @@
+import type { AccessSchema } from "../../access-schema.js";
+/** What the reader made of a schema: the `AccessSchema`, and what it left out and why. */
+type PrismaSchemaReading = {
+    readonly schema: AccessSchema;
+    readonly skipped: readonly string[];
+};
+/** Reads the Prisma schema at `path` (a `.prisma` file or a folder of them) as an `AccessSchema`. */
+export declare const readPrismaSchema: (path: string) => Promise<PrismaSchemaReading>;
+export {};

package/dist/generator/prisma7/prisma-schema.reader.js

@@ -0,0 +1,394 @@
+// A Prisma 7 schema (`schema.prisma`, or a folder of `.prisma` files) read as the
+// `AccessSchema` a service authors its rules against with `definePolicies`. It reads
+// what the Aventara framework's Prisma 7 discovery reads for the same facts, so an
+// Aventara app's discovered model and this reader agree on every Resource: each
+// model's scalar and relation fields, enums, the reference pairs a relation holds,
+// its inverse, and the field tuples that identify a row.
+//
+// It is a bounded reader, not a parser: Prisma's schema language puts each field and
+// each block attribute on one line of its own (a declaration split over lines is a
+// Prisma validation error), so it reads line by line. It locates tokens and never
+// evaluates them: `@default(...)`, `@map`, `@db.*`, `@@index` and `@@schema` are
+// read past. What it cannot model (an `Unsupported(...)` column, a composite `type`,
+// a `view`, an `@ignore`d field or model) is left out and reported, never guessed.
+import { readdir, readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { BEACON_TABLE } from "../../beacon/beacon.store.js";
+/** Prisma's built-in scalars, as Access (and the framework) name them. */
+const SCALARS = {
+    String: "string",
+    Boolean: "boolean",
+    Int: "int",
+    Float: "float",
+    BigInt: "bigint",
+    Decimal: "decimal",
+    DateTime: "datetime",
+    Bytes: "bytes",
+    Json: "json",
+};
+/** A line without its comment: `//` outside a string literal ends the line. */
+const withoutComment = (line) => {
+    let quoted = false;
+    for (let index = 0; index < line.length; index += 1) {
+        const char = line[index];
+        if (char === "\\" && quoted) {
+            index += 1;
+        }
+        else if (char === '"') {
+            quoted = !quoted;
+        }
+        else if (!quoted && char === "/" && line[index + 1] === "/") {
+            return line.slice(0, index);
+        }
+    }
+    return line;
+};
+/** The `@name(args)` and `@@name(args)` attributes of a line, in order, with their raw arguments. */
+const attributesOf = (text) => {
+    const attributes = [];
+    let index = 0;
+    while (index < text.length) {
+        if (text[index] !== "@") {
+            index += 1;
+            continue;
+        }
+        const start = index;
+        while (text[index] === "@") {
+            index += 1;
+        }
+        const nameMatch = /^[A-Za-z_][\w.]*/.exec(text.slice(index));
+        const name = `${text.slice(start, index)}${nameMatch?.[0] ?? ""}`;
+        index += nameMatch?.[0].length ?? 0;
+        let args;
+        if (text[index] === "(") {
+            let depth = 0;
+            let quoted = false;
+            const open = index;
+            for (; index < text.length; index += 1) {
+                const char = text[index];
+                if (quoted) {
+                    if (char === "\\") {
+                        index += 1;
+                    }
+                    else if (char === '"') {
+                        quoted = false;
+                    }
+                }
+                else if (char === '"') {
+                    quoted = true;
+                }
+                else if (char === "(") {
+                    depth += 1;
+                }
+                else if (char === ")") {
+                    depth -= 1;
+                    if (depth === 0) {
+                        index += 1;
+                        break;
+                    }
+                }
+            }
+            args = text.slice(open + 1, index - 1);
+        }
+        attributes.push({ name, args });
+    }
+    return attributes;
+};
+/** An attribute's arguments split at the commas outside brackets, parentheses and strings. */
+const argumentsOf = (args) => {
+    const parts = [];
+    let depth = 0;
+    let quoted = false;
+    let current = "";
+    for (let index = 0; index < args.length; index += 1) {
+        const char = args[index] ?? "";
+        if (quoted) {
+            current += char;
+            if (char === "\\") {
+                current += args[index + 1] ?? "";
+                index += 1;
+            }
+            else if (char === '"') {
+                quoted = false;
+            }
+            continue;
+        }
+        if (char === '"') {
+            quoted = true;
+        }
+        else if (char === "(" || char === "[") {
+            depth += 1;
+        }
+        else if (char === ")" || char === "]") {
+            depth -= 1;
+        }
+        else if (char === "," && depth === 0) {
+            parts.push(current.trim());
+            current = "";
+            continue;
+        }
+        current += char;
+    }
+    if (current.trim() !== "") {
+        parts.push(current.trim());
+    }
+    return parts;
+};
+/** The named argument `name:` of an attribute, or its first positional one when `name` is `undefined`. */
+const argumentOf = (args, name) => {
+    for (const part of argumentsOf(args ?? "")) {
+        const named = /^([A-Za-z_]\w*)\s*:\s*([\s\S]*)$/.exec(part);
+        if (name === undefined ? named === null : named?.[1] === name) {
+            return name === undefined ? part : named?.[2]?.trim();
+        }
+    }
+    return undefined;
+};
+/** The field names of a `[a, b(sort: Desc)]` list. */
+const fieldListOf = (list) => {
+    const inner = /^\[([\s\S]*)\]$/.exec(list?.trim() ?? "")?.[1];
+    if (inner === undefined) {
+        return undefined;
+    }
+    return argumentsOf(inner)
+        .map((member) => /^[A-Za-z_]\w*/.exec(member)?.[0] ?? "")
+        .filter((member) => member !== "");
+};
+/** A string literal's value: `"Mentorship"` → `Mentorship`. */
+const stringOf = (literal) => /^"((?:[^"\\]|\\.)*)"$/.exec(literal?.trim() ?? "")?.[1];
+const FIELD = /^([A-Za-z_]\w*)\s+([A-Za-z_]\w*(?:\([^)]*\))?)(\[\])?(\?)?(.*)$/;
+/** The `.prisma` files at `path`: the file itself, or every one under the folder, by path. */
+const schemaFiles = async (path) => {
+    if (path.endsWith(".prisma")) {
+        return [path];
+    }
+    const files = [];
+    const walk = async (folder) => {
+        const entries = await readdir(folder, { withFileTypes: true });
+        for (const entry of entries) {
+            const full = resolve(folder, entry.name);
+            if (entry.isDirectory()) {
+                await walk(full);
+            }
+            else if (entry.isFile() && entry.name.endsWith(".prisma")) {
+                files.push(full);
+            }
+        }
+    };
+    await walk(path);
+    return files.sort();
+};
+/** Reads the schema's blocks: models with their lines, enums with their values. */
+const blocksOf = (sources, skipped) => {
+    const models = [];
+    const enums = new Map();
+    const composites = new Set();
+    for (const { file, text } of sources) {
+        let block;
+        for (const raw of text.split(/\r?\n/)) {
+            const line = withoutComment(raw).trim();
+            if (line === "") {
+                continue;
+            }
+            if (block === undefined) {
+                const opened = /^(\w+)\s+([A-Za-z_]\w*)\s*\{$/.exec(line);
+                if (opened !== null) {
+                    block = { kind: opened[1] ?? "", name: opened[2] ?? "", lines: [] };
+                }
+                continue;
+            }
+            if (line === "}") {
+                if (block.kind === "model") {
+                    const fields = [];
+                    const blockAttributes = [];
+                    for (const member of block.lines) {
+                        if (member.startsWith("@@")) {
+                            blockAttributes.push(...attributesOf(member));
+                            continue;
+                        }
+                        const field = FIELD.exec(member);
+                        if (field === null) {
+                            continue;
+                        }
+                        fields.push({
+                            name: field[1] ?? "",
+                            type: field[2] ?? "",
+                            list: field[3] !== undefined,
+                            optional: field[4] !== undefined,
+                            attributes: attributesOf(field[5] ?? ""),
+                        });
+                    }
+                    models.push({ name: block.name, file, fields, blockAttributes });
+                }
+                else if (block.kind === "enum") {
+                    enums.set(block.name, block.lines
+                        .filter((member) => !member.startsWith("@@"))
+                        .map((member) => /^[A-Za-z_]\w*/.exec(member)?.[0] ?? "")
+                        .filter((member) => member !== ""));
+                }
+                else if (block.kind === "type") {
+                    composites.add(block.name);
+                }
+                else if (block.kind === "view") {
+                    skipped.push(`view ${block.name}: a view is not a Resource Access reads; left out`);
+                }
+                block = undefined;
+                continue;
+            }
+            block.lines.push(line);
+        }
+    }
+    return { models, enums, composites };
+};
+const has = (attributes, name) => attributes.some((attribute) => attribute.name === name);
+/** The relation's name, from `@relation("Name")` or `@relation(name: "Name")`. */
+const relationNameOf = (field) => {
+    const relation = field.attributes.find((attribute) => attribute.name === "@relation");
+    if (relation === undefined) {
+        return null;
+    }
+    return (stringOf(argumentOf(relation.args, "name")) ??
+        stringOf(argumentOf(relation.args, undefined)) ??
+        null);
+};
+/** Whether a model is the ownership beacon's table: named, or mapped to, `_aventara_beacon`. */
+const isBeaconTable = (model) => BEACON_NAMES.includes(model.name) ||
+    model.blockAttributes.some((attribute) => attribute.name === "@@map" &&
+        BEACON_NAMES.includes(stringOf(argumentOf(attribute.args, undefined) ??
+            argumentOf(attribute.args, "name")) ?? ""));
+/** The beacon table's names: a service's `_aventara_beacon`, the Access server's `aventaraBeacon` (Prisma model `AventaraBeacon`). */
+const BEACON_NAMES = [
+    BEACON_TABLE,
+    "aventaraBeacon",
+    "AventaraBeacon",
+];
+/** Reads the Prisma schema at `path` (a `.prisma` file or a folder of them) as an `AccessSchema`. */
+export const readPrismaSchema = async (path) => {
+    const sources = await Promise.all((await schemaFiles(path)).map(async (file) => ({
+        file,
+        text: await readFile(file, "utf8"),
+    })));
+    const skipped = [];
+    const { models: declared, enums, composites } = blocksOf(sources, skipped);
+    const models = declared.filter((model) => {
+        if (has(model.blockAttributes, "@@ignore")) {
+            skipped.push(`model ${model.name}: @@ignore; left out`);
+            return false;
+        }
+        if (isBeaconTable(model)) {
+            skipped.push(`model ${model.name}: the ownership beacon's table, which no rule reads; left out`);
+            return false;
+        }
+        return true;
+    });
+    const byName = new Map(models.map((model) => [model.name, model]));
+    const ignoredModels = new Set(declared.filter((model) => !byName.has(model.name)).map((m) => m.name));
+    const resources = {};
+    for (const model of models) {
+        const fields = {};
+        const columns = new Map();
+        for (const field of model.fields) {
+            const where = `${model.name}.${field.name}`;
+            if (has(field.attributes, "@ignore")) {
+                skipped.push(`${where}: @ignore; left out`);
+                continue;
+            }
+            const scalar = SCALARS[field.type];
+            if (scalar !== undefined || enums.has(field.type)) {
+                fields[field.name] = {
+                    kind: "scalar",
+                    type: scalar !== undefined ? { scalar } : { enum: field.type },
+                    nullable: field.optional,
+                    list: field.list,
+                };
+                if (!field.list) {
+                    columns.set(field.name, field);
+                }
+                continue;
+            }
+            const target = byName.get(field.type);
+            if (target === undefined) {
+                skipped.push(`${where}: ${field.type.startsWith("Unsupported(")
+                    ? "an Unsupported column"
+                    : composites.has(field.type)
+                        ? `the composite type ${field.type}`
+                        : ignoredModels.has(field.type)
+                            ? `a relation to the ignored model ${field.type}`
+                            : `the type ${field.type}, which the schema does not declare`}; left out`);
+                continue;
+            }
+            const name = relationNameOf(field);
+            const partners = target.fields.filter((candidate) => candidate.type === model.name &&
+                relationNameOf(candidate) === name &&
+                !(target.name === model.name && candidate.name === field.name));
+            const relation = field.attributes.find((attribute) => attribute.name === "@relation");
+            const referenceFields = fieldListOf(argumentOf(relation?.args, "fields"));
+            const references = fieldListOf(argumentOf(relation?.args, "references"));
+            const cardinality = field.list ? "many" : "one";
+            const fact = {
+                kind: "relation",
+                target: target.name,
+                cardinality,
+                nullable: cardinality === "one" && field.optional,
+                ...(partners.length === 1 && partners[0] !== undefined
+                    ? { inverse: partners[0].name }
+                    : {}),
+                ...(referenceFields !== undefined &&
+                    referenceFields.length > 0 &&
+                    references !== undefined &&
+                    references.length > 0
+                    ? {
+                        referenceFields: referenceFields,
+                        references: references,
+                    }
+                    : {}),
+            };
+            fields[field.name] = fact;
+        }
+        // Identifiers, as discovery lists them: each field's `@id` then `@unique`, in
+        // field order, then `@@id`, then each `@@unique`; a tuple once; none over a
+        // field that is not a column here, and none over a nullable one.
+        const criteria = [];
+        for (const field of model.fields) {
+            if (has(field.attributes, "@id")) {
+                criteria.push([field.name]);
+            }
+            if (has(field.attributes, "@unique")) {
+                criteria.push([field.name]);
+            }
+        }
+        for (const name of ["@@id", "@@unique"]) {
+            for (const attribute of model.blockAttributes) {
+                if (attribute.name !== name) {
+                    continue;
+                }
+                const members = fieldListOf(argumentOf(attribute.args, "fields")) ??
+                    fieldListOf(argumentOf(attribute.args, undefined));
+                if (members !== undefined) {
+                    criteria.push(members);
+                }
+            }
+        }
+        const seen = new Set();
+        const identifiers = [];
+        for (const members of criteria) {
+            const key = JSON.stringify(members);
+            if (seen.has(key)) {
+                continue;
+            }
+            seen.add(key);
+            if (members.length > 0 &&
+                members.every((member) => columns.get(member)?.optional === false)) {
+                identifiers.push(members);
+            }
+        }
+        resources[model.name] = { fields, identifiers };
+    }
+    return {
+        schema: {
+            enums: Object.fromEntries([...enums].map(([name, values]) => [name, { values }])),
+            resources,
+        },
+        skipped,
+    };
+};

package/dist/generator/prisma7/prisma-where.translator.d.ts

@@ -0,0 +1,73 @@
+import { type AccessWhere } from "../../aventara-where.translator.js";
+import type { AccessFields } from "../../policies.decider.js";
+import type { AccessPolicies } from "../../policies-contract.js";
+/** A Prisma `where`: plain data any `<Model>WhereInput` accepts. */
+export type PrismaWhere = {
+    [key: string]: unknown;
+};
+/** A Prisma `select` of scalar fields. */
+export type PrismaSelect = {
+    [field: string]: true;
+};
+/** What `prismaExists` needs of a model's delegate on the Prisma client. */
+export type PrismaFindFirst = {
+    findFirst(args: {
+        where: PrismaWhere;
+        select: PrismaSelect;
+    }): PromiseLike<unknown>;
+};
+/** Aventara's `where` on a Resource of `policies`, as Prisma's `where` on its model. */
+export declare const toPrismaWhere: (policies: AccessPolicies, resource: string, where: AccessWhere) => PrismaWhere;
+/**
+ * A scope (`scopeOf`'s answer) as Prisma's `where`: every row (`{}`), no row
+ * (`{ OR: [] }`, which Prisma matches with nothing), or the translated condition.
+ */
+export declare const toPrismaScope: (policies: AccessPolicies, resource: string, scope: boolean | AccessWhere) => PrismaWhere;
+/**
+ * A `fieldsOf` read answer as Prisma's `select`: the Resource's scalar fields a read
+ * shows on every row. A field governed for reading is selected only when the answer
+ * opens it on every row (one governed for writing only is read as any other); a
+ * field it opens on some rows only is left out, since a `select` cannot depend on
+ * the row (ask `fieldsOf` for those). Relations are never selected: a related row
+ * would not be scoped.
+ */
+export declare const toPrismaSelect: (policies: AccessPolicies, resource: string, fields: AccessFields) => PrismaSelect;
+/** The property of the Prisma client that holds a model's delegate: its name, first letter lowered. */
+export declare const prismaDelegateOf: (resource: string) => string;
+/**
+ * Core's `exists`, through the service's Prisma client: whether a row of `resource`
+ * meets `where`, unscoped. It selects the row's first identifier and nothing else.
+ */
+export declare const existsThroughPrisma: (client: object, policies: AccessPolicies, resource: string, where: AccessWhere) => Promise<boolean>;
+/**
+ * The Prisma client the ownership beacon is read and written through: a model over
+ * the `_aventara_beacon` table, keyed by the namespace,
+ * `model AventaraBeacon { id String @id  namespace String @unique  value String  createdAt DateTime @default(now())  @@map("_aventara_beacon") }`.
+ */
+export type PrismaBeaconClient = {
+    readonly aventaraBeacon: {
+        findUnique(args: {
+            where: {
+                namespace: string;
+            };
+            select: {
+                value: true;
+            };
+        }): PromiseLike<unknown>;
+        create(args: {
+            data: {
+                namespace: string;
+                value: string;
+            };
+        }): PromiseLike<unknown>;
+    };
+};
+/**
+ * The beacon store over the service's Prisma client: `read` a namespace's row in
+ * `_aventara_beacon`, `create` one. What `avaccess push --beacon` and `pull --beacon`
+ * load, and what the client's `checkBeacons` reads through.
+ */
+export declare const beaconThroughPrisma: (client: PrismaBeaconClient) => {
+    read(namespace: string): Promise<string | null>;
+    create(namespace: string, value: string): Promise<void>;
+};