@antelopejs/interface-dms-builder 0.4.0 → 0.5.0

package/dist/mapping.d.ts

@@ -2,12 +2,20 @@ import type { CategoryRef, PageRef } from "./addressing";
 import type { ResourceRef } from "./resources";
 import type { OpResult } from "./results";
 import type { TableViewSettings } from "./table-view";
+/** The semantic tones of the dashboard, which a status pill and a tab are drawn in. */
 export type DisplayTone = "neutral" | "primary" | "secondary" | "success" | "warning" | "error" | "info";
+/** One value of a badge column: the value the database holds, its label and the tone it is drawn in. */
 export interface BadgeItem {
     value: string;
     label: string;
     tone: DisplayTone;
 }
+/**
+ * How a column is drawn beyond its declaration. A `badge` is a string column of few values, drawn
+ * as a status pill and filtered by a list of those values; a `price` is a number column drawn as an
+ * amount, in `currency` (an ISO 4217 code such as `USD`) and in the DataType's default currency,
+ * euros, when it states none.
+ */
 export type ColumnDisplay = {
     kind: "badge";
     items: BadgeItem[];
@@ -15,63 +23,177 @@ export type ColumnDisplay = {
     kind: "price";
     currency?: string;
 };
+/** Tabs above a TableView: "All", then one tab per value of the column's badge. */
 export interface TabsChoice {
+    /** A column of the relation whose `display` is a badge, and which is `filterable`. */
     column: string;
 }
+/** One column of a mapped relation, as the integrator chose to show it. */
 export interface MappedField {
     column: string;
+    /** One of the column's `accepts`; the first when omitted. */
     declared?: string;
+    /**
+     * The column's header. Sent, it is written as sent.
+     *
+     * Left out, a plain column takes its name, humanized. A relation column takes the label its
+     * controller holds when its relation was mapped before and held the column, and otherwise the
+     * title of the relation it points at, in singular ("Customer", not "Customer id", D3), unless
+     * the database commented the column with a short first sentence, which titles it instead (L2).
+     * The target's title is the `title` it is mapped with, else its page's title when it was mapped
+     * before, else its name humanized.
+     */
     label?: string;
     listable?: boolean;
     filterable?: boolean;
     sortable?: boolean;
     searchable?: boolean;
+    /**
+     * How the column is drawn: a badge needs a `string` declaration and a price a `number` one. A
+     * relation column takes none.
+     *
+     * Left out, a column of a relation mapped before keeps the display its controller holds, and a
+     * column of a relation not mapped before takes the one the analysis proposes (D1, D2), read from
+     * the column's profile at map time, else from the connection's last analysis, else from its name
+     * alone, which proposes a price but no badge; a warning `display_not_proposed` says when no
+     * profile or analysis was there. A kept or proposed display the column's declaration does not
+     * suit is dropped, not refused. Null writes the column plain, over any display it had.
+     */
     display?: ColumnDisplay | null;
+    /**
+     * `"schema.name"` of another mapped relation this column refers to, by that relation's
+     * single-column key: the column becomes a relation column showing the target's `label`.
+     *
+     * Left out, a column the database declares a foreign key onto a relation of this call or one
+     * mapped before, with a TableView and a single-column key that the foreign key uses, becomes a
+     * relation column onto it. Null writes the column plain, as its own value.
+     */
     relation?: string | null;
 }
+/** One relation to map, as the integrator chose to show it. */
 export interface MappedResource {
+    /** `"schema.name"`. */
     relation: string;
+    /** Defaults to the PascalCase singular of the relation's name. */
     className?: string;
+    /** The column relation columns pointing here show, and the TableView's `labelKey`. */
     label?: string;
+    /** The page's title and the TableView's caption; the relation's name, humanized, when omitted. */
     title?: string;
+    /**
+     * The icon the menu shows beside the page, an icon name such as `i-ph-shopping-cart`. Left out,
+     * a new page has none and a page mapped before keeps its own.
+     */
     icon?: string;
+    /** What the page is for, in a sentence. Left out, a new page has none and a page mapped before keeps its own. */
     description?: string;
+    /**
+     * Where the page sorts among its category's pages, lowest first; pages with the same order sort
+     * by title. Left out, a new page takes 100 and a page mapped before keeps its own. Pages
+     * written by hand or by the assistant leave the order at 0 unless they set one, so a dashboard
+     * created in the connection's category comes before the mapped tables; give a dashboard an
+     * order below 100 to be sure of it.
+     */
     order?: number;
+    /**
+     * Displays, views and footer figures written to the page's TableView by the same checks as
+     * `ConfigureTableView`: a refused choice is a warning `page_not_written` and the page keeps
+     * what it had. Left out, the page keeps its own. Column names are the ones mapped here.
+     */
     tableOptions?: TableViewSettings;
+    /**
+     * False maps the relation for stats only: its controller serves no route, so queries can name
+     * it as a resource, and it gets no TableView or page. Forced false without a key.
+     */
     tableView: boolean;
+    /** False serves the TableView without new, edit and delete, every field read-only. */
     writable: boolean;
+    /** The columns to declare; key columns are added when left out. */
     fields: MappedField[];
+    /**
+     * Tabs on the TableView's rows by a badge column, written to the page's TableView over any
+     * `tabs` it holds. The column must be filterable and drawn as a badge, whether it was sent or
+     * taken as its `display` default.
+     *
+     * Left out, a page already mapped keeps the tabs it has, and a relation not mapped before is
+     * tabbed by the column the analysis proposes (T1) among its filterable badge columns, when one
+     * suits. Null writes none: it adds no tabs to a new relation, and removes from a page already
+     * mapped the tabs a mapping wrote from a badge, as a `display` of null removes the badge. Tabs
+     * edited by hand are kept.
+     */
     tabs?: TabsChoice | null;
 }
+/** A relation the integrator decided not to map, so an analysis does not propose it again. */
 export interface ExcludedRelation {
+    /** `"schema.name"`. */
     relation: string;
     reason: string;
 }
+/** Which relations of a connection to map, into which module of the project. */
 export interface MapResourcesInput {
+    /** The project module the tables are written into, bound to the connection's database. */
     module: string;
+    /**
+     * The id of the builder's catalog connection to the database, also used in routes and as the
+     * pages' category.
+     */
     connection: string;
+    /** Relations to map, or to map again: a mapped relation is rewritten from the new choices. */
     resources: MappedResource[];
+    /** Relations recorded as left out. Mapping one later removes it from the record. */
     excluded?: ExcludedRelation[];
+    /**
+     * The pages a person approved removing, as `PreviewMapResources` answered them. When present,
+     * `MapResources` plans on the state it finds, writes nothing and refuses with `invalid_config`
+     * naming the pages when that plan removes a page not in this list; an empty list approves none.
+     * Left out, `MapResources` removes the pages the choices no longer call for, as before.
+     * `PreviewMapResources` ignores it.
+     */
     approvedPageRemovals?: PageRef[];
 }
+/** A column a TableView does not show, and why. */
 export interface LeftOutColumn {
     relation: string;
     column: string;
     reason: string;
 }
+/** What was written for one mapped relation. */
 export interface MappedResult {
     relation: string;
+    /** The resource queries name it by, TableView or not. */
     ref: ResourceRef;
     page?: PageRef;
     files: string[];
 }
+/** What `MapResources` wrote, and what it left off the TableViews. */
 export interface MapResourcesResult {
     resources: MappedResult[];
     leftOut: LeftOutColumn[];
+    /** The connection's category in the module, which the pages are in and stats pages go under. */
     category?: CategoryRef;
 }
+/** What `MapResources` would remove for the same input, answered by `PreviewMapResources`. */
 export interface MapResourcesPreview {
+    /**
+     * The pages of relations already mapped with a TableView that the input maps with `tableView`
+     * false, which `MapResources` removes. Empty when the call removes no page.
+     */
     pagesToRemove: PageRef[];
 }
+/**
+ * Writes table classes, models, DataAPI controllers and TableView pages over relations of a
+ * database the project does not own, into a module bound to it. Names are the database's own,
+ * verbatim; `_id` is declared only where the relation has a key; nothing creates or alters a
+ * table. The builder reads the relations' descriptions through its catalog connection, and
+ * checks every choice in `input` against them.
+ *
+ * A relation already mapped is rewritten from the new choices: its table class and controller,
+ * and its page, which is created, kept or removed as `tableView` says.
+ */
 export declare const MapResources: (input: MapResourcesInput) => Promise<OpResult<MapResourcesResult>>;
+/**
+ * Answers which pages `MapResources` would remove for `input`, and writes nothing. It plans the
+ * mapping as `MapResources` does and refuses what that refuses, so a caller can ask a person
+ * before a mapping that removes a page.
+ */
 export declare const PreviewMapResources: (input: MapResourcesInput) => Promise<OpResult<MapResourcesPreview>>;

package/dist/mapping.js

@@ -2,6 +2,21 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.PreviewMapResources = exports.MapResources = void 0;
 const interface_core_1 = require("@antelopejs/interface-core");
+/**
+ * Writes table classes, models, DataAPI controllers and TableView pages over relations of a
+ * database the project does not own, into a module bound to it. Names are the database's own,
+ * verbatim; `_id` is declared only where the relation has a key; nothing creates or alters a
+ * table. The builder reads the relations' descriptions through its catalog connection, and
+ * checks every choice in `input` against them.
+ *
+ * A relation already mapped is rewritten from the new choices: its table class and controller,
+ * and its page, which is created, kept or removed as `tableView` says.
+ */
 exports.MapResources = (0, interface_core_1.InterfaceFunction)();
+/**
+ * Answers which pages `MapResources` would remove for `input`, and writes nothing. It plans the
+ * mapping as `MapResources` does and refuses what that refuses, so a caller can ask a person
+ * before a mapping that removes a page.
+ */
 exports.PreviewMapResources = (0, interface_core_1.InterfaceFunction)();
 //# sourceMappingURL=mapping.js.map

package/dist/mapping.js.map

@@ -1 +1 @@
-{"version":3,"file":"mapping.js","sourceRoot":"","sources":["../src/mapping.ts"],"names":[],"mappings":";;;AAAA,+DAA+D;AAiNlD,QAAA,YAAY,GACvB,IAAA,kCAAiB,GAEd,CAAC;AAOO,QAAA,mBAAmB,GAC9B,IAAA,kCAAiB,GAEd,CAAC"}
+{"version":3,"file":"mapping.js","sourceRoot":"","sources":["../src/mapping.ts"],"names":[],"mappings":";;;AAAA,+DAA+D;AAuM/D;;;;;;;;;GASG;AACU,QAAA,YAAY,GACvB,IAAA,kCAAiB,GAEd,CAAC;AAEN;;;;GAIG;AACU,QAAA,mBAAmB,GAC9B,IAAA,kCAAiB,GAEd,CAAC"}

package/dist/operation-map.d.ts

@@ -1,3 +1,10 @@
+/**
+ * Every operation of the builder, by the name it is exported under.
+ *
+ * A caller that picks an operation at run time, such as a route that forwards a
+ * named request, indexes this map and keeps each operation's parameter and
+ * result types, rather than reading the namespace import as an untyped record.
+ */
 export declare const Operations: {
     AddBlock: (input: import("./operations").AddBlockInput, opts?: import("./results").MutationOpts | undefined) => Promise<import("./results").OpResult<{
         path: import("./addressing").BlockPath;
@@ -11,6 +18,7 @@ export declare const Operations: {
         route: string;
     }>>;
     AnalyseDatabase: (input: import("./analysis").AnalyseDatabaseInput) => Promise<import("./results").OpResult<import("./analysis").AnalysisState>>;
+    CheckDatabaseConnection: (input: import("./database").DatabaseCheckInput) => Promise<import("./results").OpResult<import("./database").DatabaseAccess>>;
     ComposePage: (input: import("./compose").ComposePageInput, opts?: import("./results").MutationOpts | undefined) => Promise<import("./results").OpResult<import("./compose").ComposePageData>>;
     ConfigureBlock: (path: string, patch: import("./values").ConfigObject, opts?: import("./operations").ConfigureBlockOpts | undefined) => Promise<import("./results").OpResult>;
     ConfigureCategory: (ref: string, patch: Partial<import("./structure").EditableCategoryMeta>) => Promise<import("./results").OpResult>;
@@ -18,8 +26,9 @@ export declare const Operations: {
     ConfigureModule: (id: string, entry: import("./project").ModuleEntryInput, opts?: import("./project").ProjectConfigOpts | undefined) => Promise<import("./results").OpResult<import("./project").ProjectConfigResult>>;
     ConfigurePage: (ref: string, patch: Partial<import("./structure").EditablePageMeta>, opts?: import("./results").MutationOpts | undefined) => Promise<import("./results").OpResult<{
         ref: import("./addressing").PageRef;
+        version: string;
     }>>;
-    ConfigureProject: (steps: import("./project").ProjectConfigStep[], opts?: import("./project").ProjectConfigOpts | undefined) => Promise<import("./results").OpResult<import("./project").ProjectConfigResult>>;
+    ConfigureProject: (steps: import("./project").ProjectConfigStep[], opts?: import("./project").ConfigureProjectOpts | undefined) => Promise<import("./results").OpResult<import("./project").ProjectConfigResult>>;
     ConfigureQuery: (query: string, patch: Partial<import("./queries").AddQueryInput>, opts?: import("./results").MutationOpts | undefined) => Promise<import("./results").OpResult>;
     ConfigureResource: (ref: string, patch: import("./resources").EditableResourceMeta, opts?: import("./results").MutationOpts | undefined) => Promise<import("./results").OpResult>;
     ConfigureTableView: (page: string, settings: import("./table-view").TableViewSettings, opts?: import("./table-view").ConfigureTableViewOpts | undefined) => Promise<import("./results").OpResult<{
@@ -37,16 +46,23 @@ export declare const Operations: {
         ref: import("./resources").ResourceRef;
         files: import("./resources").ResourceFiles;
     }>>;
+    CreateThemeLayer: () => Promise<import("./results").OpResult<import("./theme").ThemeLayer>>;
     DeleteCategory: (ref: string) => Promise<import("./results").OpResult>;
     DeletePage: (ref: string, opts?: import("./results").MutationOpts | undefined) => Promise<import("./results").OpResult>;
     DeleteResource: (ref: string, opts?: import("./resources").DeleteResourceOpts | undefined) => Promise<import("./results").OpResult>;
     GetAnalysis: (id: string) => Promise<import("./results").OpResult<import("./analysis").AnalysisState>>;
     GetCatalog: () => Promise<import("./catalog").BlockCatalog>;
+    GetDatabaseConnection: (connection: string) => Promise<import("./results").OpResult<import("./database").DatabaseConnection>>;
+    GetDatabaseProject: () => Promise<import("./results").OpResult<import("./database").DatabaseProject>>;
+    GetLatestAnalysis: (connection: string) => Promise<import("./results").OpResult<import("./analysis").AnalysisState>>;
     GetMapping: (connection: string, module: string) => Promise<import("./results").OpResult<import("./analysis").MappedRelation[]>>;
     GetPageStructure: (ref: string) => Promise<import("./results").OpResult<import("./structure").PageStructure>>;
     GetResourceStructure: (ref: string) => Promise<import("./results").OpResult<import("./resources").ResourceStructure>>;
+    GetTheme: () => Promise<import("./results").OpResult<import("./theme").ThemeStructure>>;
     ListCategories: () => Promise<import("./structure").CategorySummary[]>;
+    ListDatabaseConnections: () => Promise<import("./database").CatalogConnectionEntry[]>;
     ListDataSources: (response?: string | undefined) => Promise<import("./catalog").DataSourceDescriptor[]>;
+    ListEntryConnections: (module: string) => Promise<import("./results").OpResult<import("./database").EntryConnection[]>>;
     ListPages: () => Promise<import("./structure").PageSummary[]>;
     ListQueryTemplates: (resourceType?: string | undefined) => Promise<import("./queries").QueryTemplateDescriptor[]>;
     ListResources: () => Promise<import("./resources").ResourceSummary[]>;
@@ -57,10 +73,20 @@ export declare const Operations: {
     PreviewQuery: (request: import("./drafts").QueryPreviewRequest) => Promise<import("./results").OpResult<import("./queries").QueryPreview>>;
     RefreshSourceIndex: (scope?: import("./operations").RefreshScope | undefined) => Promise<void>;
     RemoveBlock: (path: string, opts?: import("./results").MutationOpts | undefined) => Promise<import("./results").OpResult>;
+    RemoveDatabaseConnection: (connection: string, opts?: import("./project").ProjectConfigOpts | undefined) => Promise<import("./results").OpResult<import("./project").ProjectConfigResult>>;
     RemoveField: (path: string, opts?: import("./results").MutationOpts | undefined) => Promise<import("./results").OpResult>;
     RemoveQuery: (query: string, opts?: import("./results").MutationOpts | undefined) => Promise<import("./results").OpResult>;
+    RepairDatabaseConnections: (opts?: import("./project").ProjectConfigOpts | undefined) => Promise<import("./results").OpResult<import("./project").ProjectConfigResult>>;
+    SampleDatabaseRows: (connection: string, request: import("./database").RowSampleRequest) => Promise<import("./results").OpResult<import("./database").RowSample>>;
+    SetDatabaseConnectionUrl: (connection: string, url: string) => Promise<import("./results").OpResult<{
+        variable: string;
+    }>>;
     SetPageBlocks: (page: string, draft: import("./drafts").PageDraft, opts?: import("./results").MutationOpts | undefined) => Promise<import("./results").OpResult<{
         version: string;
     }>>;
+    SetTheme: (draft: import("./theme").ThemeDraft, opts?: import("./results").MutationOpts | undefined) => Promise<import("./results").OpResult<{
+        version: string;
+    }>>;
 };
+/** The name of one operation in `Operations`. */
 export type OperationName = keyof typeof Operations;

package/dist/operation-map.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.Operations = void 0;
 const analysis_1 = require("./analysis");
 const compose_1 = require("./compose");
+const database_1 = require("./database");
 const drafts_1 = require("./drafts");
 const mapping_1 = require("./mapping");
 const operations_1 = require("./operations");
@@ -10,12 +11,21 @@ const project_1 = require("./project");
 const queries_1 = require("./queries");
 const resources_1 = require("./resources");
 const table_view_1 = require("./table-view");
+const theme_1 = require("./theme");
+/**
+ * Every operation of the builder, by the name it is exported under.
+ *
+ * A caller that picks an operation at run time, such as a route that forwards a
+ * named request, indexes this map and keeps each operation's parameter and
+ * result types, rather than reading the namespace import as an untyped record.
+ */
 exports.Operations = {
     AddBlock: operations_1.AddBlock,
     AddField: resources_1.AddField,
     AddModule: project_1.AddModule,
     AddQuery: queries_1.AddQuery,
     AnalyseDatabase: analysis_1.AnalyseDatabase,
+    CheckDatabaseConnection: database_1.CheckDatabaseConnection,
     ComposePage: compose_1.ComposePage,
     ConfigureBlock: operations_1.ConfigureBlock,
     ConfigureCategory: operations_1.ConfigureCategory,
@@ -30,16 +40,23 @@ exports.Operations = {
     CreateLocalModule: project_1.CreateLocalModule,
     CreatePage: operations_1.CreatePage,
     CreateResource: resources_1.CreateResource,
+    CreateThemeLayer: theme_1.CreateThemeLayer,
     DeleteCategory: operations_1.DeleteCategory,
     DeletePage: operations_1.DeletePage,
     DeleteResource: resources_1.DeleteResource,
     GetAnalysis: analysis_1.GetAnalysis,
     GetCatalog: operations_1.GetCatalog,
+    GetDatabaseConnection: database_1.GetDatabaseConnection,
+    GetDatabaseProject: database_1.GetDatabaseProject,
+    GetLatestAnalysis: analysis_1.GetLatestAnalysis,
     GetMapping: analysis_1.GetMapping,
     GetPageStructure: operations_1.GetPageStructure,
     GetResourceStructure: resources_1.GetResourceStructure,
+    GetTheme: theme_1.GetTheme,
     ListCategories: operations_1.ListCategories,
+    ListDatabaseConnections: database_1.ListDatabaseConnections,
     ListDataSources: operations_1.ListDataSources,
+    ListEntryConnections: database_1.ListEntryConnections,
     ListPages: operations_1.ListPages,
     ListQueryTemplates: queries_1.ListQueryTemplates,
     ListResources: resources_1.ListResources,
@@ -50,8 +67,13 @@ exports.Operations = {
     PreviewQuery: drafts_1.PreviewQuery,
     RefreshSourceIndex: operations_1.RefreshSourceIndex,
     RemoveBlock: operations_1.RemoveBlock,
+    RemoveDatabaseConnection: database_1.RemoveDatabaseConnection,
     RemoveField: resources_1.RemoveField,
     RemoveQuery: queries_1.RemoveQuery,
+    RepairDatabaseConnections: database_1.RepairDatabaseConnections,
+    SampleDatabaseRows: database_1.SampleDatabaseRows,
+    SetDatabaseConnectionUrl: database_1.SetDatabaseConnectionUrl,
     SetPageBlocks: drafts_1.SetPageBlocks,
+    SetTheme: theme_1.SetTheme,
 };
 //# sourceMappingURL=operation-map.js.map

package/dist/operation-map.js.map

@@ -1 +1 @@
-{"version":3,"file":"operation-map.js","sourceRoot":"","sources":["../src/operation-map.ts"],"names":[],"mappings":";;;AAAA,yCAAsE;AACtE,uCAAwC;AACxC,qCAAsE;AACtE,uCAA8D;AAC9D,6CAiBsB;AACtB,uCAKmB;AACnB,uCAKmB;AACnB,2CASqB;AACrB,6CAAkD;AASrC,QAAA,UAAU,GAAG;IACxB,QAAQ,EAAR,qBAAQ;IACR,QAAQ,EAAR,oBAAQ;IACR,SAAS,EAAT,mBAAS;IACT,QAAQ,EAAR,kBAAQ;IACR,eAAe,EAAf,0BAAe;IACf,WAAW,EAAX,qBAAW;IACX,cAAc,EAAd,2BAAc;IACd,iBAAiB,EAAjB,8BAAiB;IACjB,cAAc,EAAd,0BAAc;IACd,eAAe,EAAf,yBAAe;IACf,aAAa,EAAb,0BAAa;IACb,gBAAgB,EAAhB,0BAAgB;IAChB,cAAc,EAAd,wBAAc;IACd,iBAAiB,EAAjB,6BAAiB;IACjB,kBAAkB,EAAlB,+BAAkB;IAClB,cAAc,EAAd,2BAAc;IACd,iBAAiB,EAAjB,2BAAiB;IACjB,UAAU,EAAV,uBAAU;IACV,cAAc,EAAd,0BAAc;IACd,cAAc,EAAd,2BAAc;IACd,UAAU,EAAV,uBAAU;IACV,cAAc,EAAd,0BAAc;IACd,WAAW,EAAX,sBAAW;IACX,UAAU,EAAV,uBAAU;IACV,UAAU,EAAV,qBAAU;IACV,gBAAgB,EAAhB,6BAAgB;IAChB,oBAAoB,EAApB,gCAAoB;IACpB,cAAc,EAAd,2BAAc;IACd,eAAe,EAAf,4BAAe;IACf,SAAS,EAAT,sBAAS;IACT,kBAAkB,EAAlB,4BAAkB;IAClB,aAAa,EAAb,yBAAa;IACb,YAAY,EAAZ,sBAAY;IACZ,mBAAmB,EAAnB,6BAAmB;IACnB,SAAS,EAAT,sBAAS;IACT,aAAa,EAAb,sBAAa;IACb,YAAY,EAAZ,qBAAY;IACZ,kBAAkB,EAAlB,+BAAkB;IAClB,WAAW,EAAX,wBAAW;IACX,WAAW,EAAX,uBAAW;IACX,WAAW,EAAX,qBAAW;IACX,aAAa,EAAb,sBAAa;CACd,CAAC"}
+{"version":3,"file":"operation-map.js","sourceRoot":"","sources":["../src/operation-map.ts"],"names":[],"mappings":";;;AAAA,yCAKoB;AACpB,uCAAwC;AACxC,yCAUoB;AACpB,qCAAsE;AACtE,uCAA8D;AAC9D,6CAiBsB;AACtB,uCAKmB;AACnB,uCAKmB;AACnB,2CASqB;AACrB,6CAAkD;AAClD,mCAA+D;AAE/D;;;;;;GAMG;AACU,QAAA,UAAU,GAAG;IACxB,QAAQ,EAAR,qBAAQ;IACR,QAAQ,EAAR,oBAAQ;IACR,SAAS,EAAT,mBAAS;IACT,QAAQ,EAAR,kBAAQ;IACR,eAAe,EAAf,0BAAe;IACf,uBAAuB,EAAvB,kCAAuB;IACvB,WAAW,EAAX,qBAAW;IACX,cAAc,EAAd,2BAAc;IACd,iBAAiB,EAAjB,8BAAiB;IACjB,cAAc,EAAd,0BAAc;IACd,eAAe,EAAf,yBAAe;IACf,aAAa,EAAb,0BAAa;IACb,gBAAgB,EAAhB,0BAAgB;IAChB,cAAc,EAAd,wBAAc;IACd,iBAAiB,EAAjB,6BAAiB;IACjB,kBAAkB,EAAlB,+BAAkB;IAClB,cAAc,EAAd,2BAAc;IACd,iBAAiB,EAAjB,2BAAiB;IACjB,UAAU,EAAV,uBAAU;IACV,cAAc,EAAd,0BAAc;IACd,gBAAgB,EAAhB,wBAAgB;IAChB,cAAc,EAAd,2BAAc;IACd,UAAU,EAAV,uBAAU;IACV,cAAc,EAAd,0BAAc;IACd,WAAW,EAAX,sBAAW;IACX,UAAU,EAAV,uBAAU;IACV,qBAAqB,EAArB,gCAAqB;IACrB,kBAAkB,EAAlB,6BAAkB;IAClB,iBAAiB,EAAjB,4BAAiB;IACjB,UAAU,EAAV,qBAAU;IACV,gBAAgB,EAAhB,6BAAgB;IAChB,oBAAoB,EAApB,gCAAoB;IACpB,QAAQ,EAAR,gBAAQ;IACR,cAAc,EAAd,2BAAc;IACd,uBAAuB,EAAvB,kCAAuB;IACvB,eAAe,EAAf,4BAAe;IACf,oBAAoB,EAApB,+BAAoB;IACpB,SAAS,EAAT,sBAAS;IACT,kBAAkB,EAAlB,4BAAkB;IAClB,aAAa,EAAb,yBAAa;IACb,YAAY,EAAZ,sBAAY;IACZ,mBAAmB,EAAnB,6BAAmB;IACnB,SAAS,EAAT,sBAAS;IACT,aAAa,EAAb,sBAAa;IACb,YAAY,EAAZ,qBAAY;IACZ,kBAAkB,EAAlB,+BAAkB;IAClB,WAAW,EAAX,wBAAW;IACX,wBAAwB,EAAxB,mCAAwB;IACxB,WAAW,EAAX,uBAAW;IACX,WAAW,EAAX,qBAAW;IACX,yBAAyB,EAAzB,oCAAyB;IACzB,kBAAkB,EAAlB,6BAAkB;IAClB,wBAAwB,EAAxB,mCAAwB;IACxB,aAAa,EAAb,sBAAa;IACb,QAAQ,EAAR,gBAAQ;CACT,CAAC"}

package/dist/operations.d.ts

@@ -4,10 +4,13 @@ import type { ResourceRef } from "./resources";
 import type { MutationOpts, OpResult } from "./results";
 import type { CategorySummary, EditableCategoryMeta, EditablePageMeta, PagePermission, PageStructure, PageSummary } from "./structure";
 import type { ConfigObject } from "./values";
+/** Reconcile scope for `RefreshSourceIndex`. Omit to reconcile everything. */
 export interface RefreshScope {
     page?: PageRef;
 }
+/** Input for `CreatePage`. Attaches to an EXISTING category only in v1. */
 export interface CreatePageInput {
+    /** Unique route id/slug — duplicate → `duplicate_name`. */
     name: string;
     displayName: string;
     category: CategoryRef;
@@ -15,49 +18,103 @@ export interface CreatePageInput {
     order?: number;
     description?: string;
     permission?: PagePermission;
+    /**
+     * Override the default category-relative placement with an explicit folder
+     * relative to the src root; the page lands at `src/<dir>/<name>/page.ts` and
+     * the nearest barrel is wired. Must stay within the src tree.
+     */
     dir?: string;
+    /**
+     * The project module to write into, by its id in the project configuration. Unset, the
+     * project's own module. A module is one of the project's local modules with an `src/index.ts`;
+     * what it writes may only use declarations from that same module.
+     */
     module?: string;
 }
+/** Input for `CreateCategory`. */
 export interface CreateCategoryInput {
     name: string;
     displayName: string;
     parent?: CategoryRef;
     icon?: string;
     order?: number;
+    /** As `CreatePageInput.module`. */
     module?: string;
 }
+/** Input for `AddBlock`. */
 export interface AddBlockInput {
     page: PageRef;
+    /** Omit = top-level static; else must be an editable container. */
     parent?: BlockPath;
     slot?: string;
+    /** Position among siblings; default = append. */
     index?: number;
+    /** Unique among siblings — duplicate → `duplicate_name`. */
     name: string;
+    /**
+     * Child metadata emitted alongside `slot` in the third argument of `.child()`
+     * — `{ colSpan: 2 }` for a grid child. Ignored for a top-level block.
+     */
     meta?: ConfigObject;
+    /** A block type from the catalog. */
     type: string;
     config: ConfigObject;
+    /**
+     * Required for controller-leading block types (catalog `controllerArg: true`,
+     * e.g. `TableView`): the resource whose DataAPI class is the leading argument.
+     * The engine emits it as the imported class identifier. Rejected for other
+     * block types.
+     */
     controller?: ResourceRef;
 }
+/** Destination for `MoveBlock`. */
 export interface MoveDest {
     parent?: BlockPath;
     slot?: string;
     index: number;
 }
+/** Options for `ConfigureBlock`. */
 export interface ConfigureBlockOpts extends MutationOpts {
+    /** Replace the whole options object instead of merging. */
     replace?: boolean;
+    /**
+     * Patch the block's child metadata (`slot`, `colSpan`, …) as well. A key set
+     * to `undefined` is removed. Rejected on a top-level block, which has no
+     * `.child()` call to carry it.
+     */
     meta?: ConfigObject;
 }
 export declare const ListPages: () => Promise<PageSummary[]>;
 export declare const ListCategories: () => Promise<CategorySummary[]>;
 export declare const GetCatalog: () => Promise<BlockCatalog>;
+/**
+ * The sources a developer declared beside their own routes, optionally narrowed
+ * to those a given block can read.
+ *
+ * Separate from the catalog because they come and go with module loads, and a
+ * caller asking for them wants what is registered now.
+ */
 export declare const ListDataSources: (response?: string | undefined) => Promise<DataSourceDescriptor[]>;
 export declare const GetPageStructure: (ref: string) => Promise<OpResult<PageStructure>>;
+/**
+ * Force reconcile against disk (e.g. after a vibe-mode excursion). Deduped:
+ * mtime-gated, scoped, and coalesced — safe to over-call.
+ */
 export declare const RefreshSourceIndex: (scope?: RefreshScope | undefined) => Promise<void>;
 export declare const CreatePage: (input: CreatePageInput) => Promise<OpResult<{
     ref: PageRef;
     filepath: string;
 }>>;
+/**
+ * Patch a page's metadata. The result carries the page's ref, which the patch
+ * can change: a page's category decides its route, so moving it between
+ * categories moves its URL — reported as a `route_changed` warning, since
+ * nothing redirects the old one. It also carries the version of the page file
+ * it wrote, which a draft held across the patch saves against.
+ */
 export declare const ConfigurePage: (ref: string, patch: Partial<EditablePageMeta>, opts?: MutationOpts | undefined) => Promise<OpResult<{
     ref: PageRef;
+    version: string;
 }>>;
 export declare const DeletePage: (ref: string, opts?: MutationOpts | undefined) => Promise<OpResult>;
 export declare const CreateCategory: (input: CreateCategoryInput) => Promise<OpResult<{

package/dist/operations.js

@@ -5,10 +5,28 @@ const interface_core_1 = require("@antelopejs/interface-core");
 exports.ListPages = (0, interface_core_1.InterfaceFunction)();
 exports.ListCategories = (0, interface_core_1.InterfaceFunction)();
 exports.GetCatalog = (0, interface_core_1.InterfaceFunction)();
+/**
+ * The sources a developer declared beside their own routes, optionally narrowed
+ * to those a given block can read.
+ *
+ * Separate from the catalog because they come and go with module loads, and a
+ * caller asking for them wants what is registered now.
+ */
 exports.ListDataSources = (0, interface_core_1.InterfaceFunction)();
 exports.GetPageStructure = (0, interface_core_1.InterfaceFunction)();
+/**
+ * Force reconcile against disk (e.g. after a vibe-mode excursion). Deduped:
+ * mtime-gated, scoped, and coalesced — safe to over-call.
+ */
 exports.RefreshSourceIndex = (0, interface_core_1.InterfaceFunction)();
 exports.CreatePage = (0, interface_core_1.InterfaceFunction)();
+/**
+ * Patch a page's metadata. The result carries the page's ref, which the patch
+ * can change: a page's category decides its route, so moving it between
+ * categories moves its URL — reported as a `route_changed` warning, since
+ * nothing redirects the old one. It also carries the version of the page file
+ * it wrote, which a draft held across the patch saves against.
+ */
 exports.ConfigurePage = (0, interface_core_1.InterfaceFunction)();
 exports.DeletePage = (0, interface_core_1.InterfaceFunction)();
 exports.CreateCategory = (0, interface_core_1.InterfaceFunction)();

package/dist/operations.js.map

@@ -1 +1 @@
-{"version":3,"file":"operations.js","sourceRoot":"","sources":["../src/operations.ts"],"names":[],"mappings":";;;AAAA,+DAA+D;AAqGlD,QAAA,SAAS,GAAG,IAAA,kCAAiB,GAAgC,CAAC;AAC9D,QAAA,cAAc,GACzB,IAAA,kCAAiB,GAAoC,CAAC;AAC3C,QAAA,UAAU,GAAG,IAAA,kCAAiB,GAA+B,CAAC;AAS9D,QAAA,eAAe,GAC1B,IAAA,kCAAiB,GAA0D,CAAC;AACjE,QAAA,gBAAgB,GAC3B,IAAA,kCAAiB,GAAsD,CAAC;AAM7D,QAAA,kBAAkB,GAC7B,IAAA,kCAAiB,GAA2C,CAAC;AAElD,QAAA,UAAU,GACrB,IAAA,kCAAiB,GAId,CAAC;AAOO,QAAA,aAAa,GACxB,IAAA,kCAAiB,GAMd,CAAC;AACO,QAAA,UAAU,GACrB,IAAA,kCAAiB,GAA4D,CAAC;AAEnE,QAAA,cAAc,GACzB,IAAA,kCAAiB,GAEd,CAAC;AACO,QAAA,iBAAiB,GAC5B,IAAA,kCAAiB,GAKd,CAAC;AACO,QAAA,cAAc,GACzB,IAAA,kCAAiB,GAA2C,CAAC;AAElD,QAAA,QAAQ,GACnB,IAAA,kCAAiB,GAKd,CAAC;AACO,QAAA,cAAc,GACzB,IAAA,kCAAiB,GAMd,CAAC;AACO,QAAA,SAAS,GACpB,IAAA,kCAAiB,GAEd,CAAC;AACO,QAAA,WAAW,GACtB,IAAA,kCAAiB,GAEd,CAAC"}
+{"version":3,"file":"operations.js","sourceRoot":"","sources":["../src/operations.ts"],"names":[],"mappings":";;;AAAA,+DAA+D;AAqGlD,QAAA,SAAS,GAAG,IAAA,kCAAiB,GAAgC,CAAC;AAC9D,QAAA,cAAc,GACzB,IAAA,kCAAiB,GAAoC,CAAC;AAC3C,QAAA,UAAU,GAAG,IAAA,kCAAiB,GAA+B,CAAC;AAE3E;;;;;;GAMG;AACU,QAAA,eAAe,GAC1B,IAAA,kCAAiB,GAA0D,CAAC;AACjE,QAAA,gBAAgB,GAC3B,IAAA,kCAAiB,GAAsD,CAAC;AAE1E;;;GAGG;AACU,QAAA,kBAAkB,GAC7B,IAAA,kCAAiB,GAA2C,CAAC;AAElD,QAAA,UAAU,GACrB,IAAA,kCAAiB,GAId,CAAC;AACN;;;;;;GAMG;AACU,QAAA,aAAa,GACxB,IAAA,kCAAiB,GAMd,CAAC;AACO,QAAA,UAAU,GACrB,IAAA,kCAAiB,GAA4D,CAAC;AAEnE,QAAA,cAAc,GACzB,IAAA,kCAAiB,GAEd,CAAC;AACO,QAAA,iBAAiB,GAC5B,IAAA,kCAAiB,GAKd,CAAC;AACO,QAAA,cAAc,GACzB,IAAA,kCAAiB,GAA2C,CAAC;AAElD,QAAA,QAAQ,GACnB,IAAA,kCAAiB,GAKd,CAAC;AACO,QAAA,cAAc,GACzB,IAAA,kCAAiB,GAMd,CAAC;AACO,QAAA,SAAS,GACpB,IAAA,kCAAiB,GAEd,CAAC;AACO,QAAA,WAAW,GACtB,IAAA,kCAAiB,GAEd,CAAC"}

package/dist/project.d.ts

@@ -1,28 +1,54 @@
 import type { OpResult } from "./results";
 import type { ConfigObject } from "./values";
+/** One `importOverrides` entry: a pin when `id` is absent, a named connection when it is set. */
 export interface ImportOverrideInput {
     interface: string;
+    /** The module that provides it; omitted for a connection to a standalone interface. */
     source?: string;
     id?: string;
 }
+/**
+ * What a project-config operation writes into one module's entry of `antelope.config.ts`.
+ *
+ * Secrets never pass through it: `env` maps a config path to the *name* of an environment
+ * variable, written into `envOverrides`, and the value stays wherever the environment keeps it.
+ */
 export interface ModuleEntryInput {
+    /** The module's source, as `antelope.config.ts` spells it. */
     source?: ConfigObject;
+    /** Plain configuration values; merged key by key into an existing entry. */
     config?: ConfigObject;
+    /** Config path under the module's `config`, e.g. `url`, to the variable that supplies it. */
     env?: Record<string, string>;
+    /** Added to the module's own; a pin that contradicts an existing one is refused. */
     importOverrides?: ImportOverrideInput[];
+    /** Merged into the module's own. */
     exportPriority?: Record<string, number>;
+    /**
+     * Interfaces the module implements that core must never offer from it, such as the raw-client
+     * interface of a database module serving an external database. Added to the module's own.
+     */
     disabledExports?: string[];
 }
+/** Adds a module entry. Refused when the id exists. */
 export interface AddModuleStep {
     op: "AddModule";
     id: string;
     entry: ModuleEntryInput;
 }
+/** Merges into an existing module entry. */
 export interface ConfigureModuleStep {
     op: "ConfigureModule";
     id: string;
     entry: ModuleEntryInput;
 }
+/**
+ * Scaffolds a local module at `path` (relative to the project root) and adds its entry: a
+ * `package.json` carrying the project's interface dependencies, a `tsconfig.json` with the
+ * project's compiler options, and an `src/index.ts`. The entry watches and rebuilds it as the
+ * project's own module is. With `connection`, its `dmsBuilder.database` record names that
+ * connection: the module holds that connection's tables, and goes with it when it is removed.
+ */
 export interface CreateLocalModuleStep {
     op: "CreateLocalModule";
     id: string;
@@ -30,26 +56,62 @@ export interface CreateLocalModuleStep {
     entry?: ModuleEntryInput;
     connection?: string;
 }
+/**
+ * Removes a module entry and the `envOverrides` entries that supply its config. Its files stay.
+ * Refused while another module's `importOverrides` names it as a source.
+ */
 export interface RemoveModuleStep {
     op: "RemoveModule";
     id: string;
 }
+/** Removes the named connection `id` to `interface` from every module's `importOverrides`. */
 export interface RemoveConnectionStep {
     op: "RemoveConnection";
     interface: string;
     id: string;
 }
 export type ProjectConfigStep = AddModuleStep | ConfigureModuleStep | CreateLocalModuleStep | RemoveModuleStep | RemoveConnectionStep;
+/** Options for a project-config operation. */
 export interface ProjectConfigOpts {
+    /** Answer the changes the steps would make, and write nothing. */
     dryRun?: boolean;
 }
+/** Options for `CreateLocalModule`. */
 export interface CreateLocalModuleOpts extends ProjectConfigOpts {
+    /** The connection whose tables the module holds, as `CreateLocalModuleStep.connection`. */
     connection?: string;
 }
+/** A variable's development value, sent with the batch that maps it. */
+export interface ProjectVariable {
+    name: string;
+    value: string;
+}
+/** Options for `ConfigureProject`. */
+export interface ConfigureProjectOpts extends ProjectConfigOpts {
+    /**
+     * Development values of variables the steps map in their `env`, written into the project's
+     * `.env` before the configuration. A variable the steps do not map is refused. Ignored on a dry run.
+     *
+     * Owner path only: the MCP tool `builder_configure_project` never passes it, so only an
+     * owner-authenticated entry writes `.env` through it.
+     */
+    variables?: ProjectVariable[];
+}
+/** The files a project-config operation wrote, or would write. */
 export interface ProjectConfigResult {
     files: string[];
 }
-export declare const ConfigureProject: (steps: ProjectConfigStep[], opts?: ProjectConfigOpts | undefined) => Promise<OpResult<ProjectConfigResult>>;
+/**
+ * Applies steps to `antelope.config.ts` in order, as one edit: every step is validated before
+ * anything is written, and none is written if one is refused. The configuration must be a
+ * `defineConfig({ … })` (or plain object) literal with a literal `modules`. With `variables`,
+ * `.env` is written first, once a dry run accepted the steps, and put back when the configuration
+ * cannot be written.
+ */
+export declare const ConfigureProject: (steps: ProjectConfigStep[], opts?: ConfigureProjectOpts | undefined) => Promise<OpResult<ProjectConfigResult>>;
+/** One `AddModule` step. */
 export declare const AddModule: (id: string, entry: ModuleEntryInput, opts?: ProjectConfigOpts | undefined) => Promise<OpResult<ProjectConfigResult>>;
+/** One `ConfigureModule` step. */
 export declare const ConfigureModule: (id: string, entry: ModuleEntryInput, opts?: ProjectConfigOpts | undefined) => Promise<OpResult<ProjectConfigResult>>;
+/** One `CreateLocalModule` step; `opts.connection` is the step's `connection`. */
 export declare const CreateLocalModule: (id: string, path: string, entry?: ModuleEntryInput | undefined, opts?: CreateLocalModuleOpts | undefined) => Promise<OpResult<ProjectConfigResult>>;