@prostgles/prostgles 2.3.6-dev.1787224693 → 2.3.6-dev.1787240381

package/dist/server/src/cli/getCliAgentsFile.js

@@ -1,108 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.getCliAgentsFile = void 0;
-const utils_1 = require("../../../common/utils");
-/**
- * This exhaustive map keeps the generated guidance in step with SchemaConfig.
- * Adding or removing a config property requires its guidance to be updated too.
- */
-const schemaConfigGuidance = {
-    access_control: "Configure database permissions with `access_control` using the Prostgles `dbPermissions` shape.",
-    connection: "Keep non-secret connection presentation settings in `connection`; database URLs belong in `.env`.",
-    databaseConfig: "Use `databaseConfig` for host-managed database features such as file storage and REST access.",
-    functions: "Put privileged operations, cross-table workflows, and server-only business logic in top-level `functions`.",
-    id: "Keep `id` stable because it identifies the deployed configuration.",
-    joins: "Use `joins` only for relationships that cannot be inferred from foreign keys.",
-    onInitSQL: "Use `onInitSQL` only for SQL initialization that cannot be expressed by `tableConfig`.",
-    onMount: "Use `onMount` for startup integration work and return cleanup logic when resources are opened.",
-    services: "Register Docker-backed runtimes with `services` so Prostgles can expose and control them.",
-    tableConfig: "Define tables and columns in `tableConfig`, including constraints and indexes.",
-    tableConfigMigrations: "For schema changes that transform existing data, increment `tableConfigMigrations.version` and use `onMigrate`.",
-    tableHooks: "Define `tableHooks` as a separate top-level config property.",
-    watchSchemaType: "Set `watchSchemaType` only when schema watching must differ from the default.",
-    workspaces: "Define typed `workspaces` as useful default dashboards that bring related data together.",
-};
-const connectionGuidance = {
-    db_schema_filter: "Use `connection.db_schema_filter` only for connection-level schema visibility.",
-    display_options: "Use `connection.display_options` for connection-wide display behavior.",
-    table_options: "Populate `connection.table_options` for every user-facing table so data renders clearly. Add useful labels and icons, column renderers and styles, and a practical `card` layout with header, subheader, avatar, and visible columns where appropriate.",
-};
-const getCliAgentsFile = () => (0, utils_1.fixIndent)(`
-    # Prostgles configuration
-
-    Build the application around the typed Prostgles schema config.
-
-    ## Config structure
-
-    - Import \`DBGeneratedSchema\` from \`generated/DBGeneratedSchema\`, create the typed config helper with \`const prostgles = defineConfig<DBGeneratedSchema>()\`, and default-export \`prostgles({ ... })\`. Keep the helper name \`prostgles\` so function return types can be discovered during schema generation.
-    - Run \`npm run dev\` after schema or function changes. It rebuilds the config and refreshes \`generated/DBGeneratedSchema.ts\`, including \`GeneratedFunctionSchema\` for clients.
-    - ${schemaConfigGuidance.id}
-    - ${schemaConfigGuidance.connection} ${connectionGuidance.db_schema_filter} ${connectionGuidance.display_options}
-    - ${schemaConfigGuidance.databaseConfig}
-    - ${schemaConfigGuidance.access_control} 
-    - ${schemaConfigGuidance.watchSchemaType}
-    - ${schemaConfigGuidance.onInitSQL} ${schemaConfigGuidance.onMount}
-
-    ## Services
-
-    - If a server function needs a non-Node.js runtime or system dependencies, implement that work as a service instead of running it directly in the function.
-    - Define services under \`src/services/<serviceName>/\`, with the typed \`*.service.ts\` definition beside a \`src/\` Docker build context. Declare a health check and typed endpoints for every operation the app calls.
-    - Register each service in \`src/serviceManager.ts\` and expose its config through the top-level \`services\` property. Service names must not collide with built-in Prostgles services or another app service.
-    - Import the exported \`serviceManager\` in server functions and use \`getServiceWithRetries(serviceName)\` before calling an endpoint. This is the host-owned instance shown in the Prostgles Services UI; do not construct another \`ServiceManager\`.
-
-    ## Typed database object
-
-    - The Prostgles \`dbo\` object available in \`onMount\`, \`tableHooks\`, and server functions is \`DBOFullyTyped<DBGeneratedSchema>\`. Table names, columns, filters, selects, inserts, updates, and results are fully typed.
-    - Keep the schema generic connected when moving code into separate modules. Use \`ProstglesOnMount<DBGeneratedSchema>\` for \`onMount\`, \`TableHooks<DBGeneratedSchema>\` for hooks, and the typed function definers for functions.
-    - Prefer typed \`dbo\` table handlers and let TypeScript infer values. Casts should be very rare; before adding one, check the table definition, JSONB schema, generated schema, and helper generic.
-    - Every table and view handler supports realtime \`subscribe\` and \`subscribeOne\`, for example \`dbo.orders.subscribe(filter, params, onData)\`. Prefer subscriptions over polling the database. Keep the returned subscription handler and call \`unsubscribe()\` during cleanup; an \`onMount\` callback can return that cleanup function.
-
-    ## Project structure
-
-    - Keep \`src/index.ts\` focused on composing and exporting the config.
-    - Put server functions in \`src/functions/\`, table definitions in \`src/tableConfigs/\`, display metadata in \`src/tableOptions/\`, and hooks in \`src/tableHooks/\`. Add domain subfolders when a folder becomes crowded.
-    - Use semantic names ending in \`*.function.ts\`, \`*.tableConfig.ts\`, \`*.tableOptions.ts\`, and \`*.tableHooks.ts\`. Examples: \`deployProject.function.ts\`, \`orders.tableConfig.ts\`, \`customers.tableOptions.ts\`, and \`users.tableHooks.ts\`.
-    - The generated ESLint config enforces these suffixes inside their corresponding folders. Run \`npm run lint\` before committing.
-
-    ## Tests
-
-    - Run \`npm test\` before committing. Tests use \`@prostgles/prostgles/testing\` to start the real app against fresh state and project databases without opening the UI.
-    - Keep deployment tests in \`tests/\`. Each call to \`createTestDeployment\` starts a disposable PostgreSQL Docker container bound only to \`127.0.0.1\`, creates fresh state and project databases, and removes the container during cleanup.
-    - Deployment stdout and stderr remain available after cleanup in \`.prostgles/test-logs/\`. The exact file is returned as \`deployment.logPath\`.
-    - Test logs may be large. Inspect them with \`tail\` or search them with \`rg\`; do not read an entire log unless its size is known to be small.
-    - If the deployment fixture blocks a valid scenario, inspect \`deployment.logPath\` and report the issue against \`@prostgles/prostgles\`; do not weaken the app or its assertions to work around the fixture.
-    - Add test users through the fixture's \`users\` option and connect with \`connectProjectAs(userKey)\`. Sessions are seeded directly, so deployment tests do not need to exercise the login UI.
-    - Add deterministic database state with the fixture's \`seed\` callback. Never use development or production database URLs for test setup.
-
-    ## Tables, display options, and hooks
-
-    - ${schemaConfigGuidance.tableConfig} ${schemaConfigGuidance.tableConfigMigrations}
-    - ${schemaConfigGuidance.tableHooks} Use hooks such as \`beforeEach\`, \`afterEach\`, and \`afterAll\` for application behavior instead of PostgreSQL triggers as this allows interaction with typescript and provides full type safety.
-    - ${connectionGuidance.table_options} Keep each table's options in its matching \`*.tableOptions.ts\` module and merge them under \`connection.table_options\`.
-    - Give every JSONB column a \`jsonbSchema\` or \`jsonbSchemaType\` so its contents are validated and typed.
-    - Follow PostgreSQL schema best practices: use primary and foreign keys, appropriate nullability, unique constraints, and indexes. Model fixed sets of values as lookup tables with \`isLookupTable\` and references instead of \`CHECK (value IN (...))\` constraints.
-    - ${schemaConfigGuidance.joins}
-
-    ## Workspaces
-
-    - ${schemaConfigGuidance.workspaces} Include tables and, where useful, aggregate SQL results, bar charts, time charts, maps, and summary statistics.
-    - Keep window IDs stable and ensure every layout item references the matching window ID.
-
-    ## File storage
-
-    - Enable managed file storage with \`databaseConfig.file_table_config\`. For local storage, use \`{ fileTable: "files", storageType: { type: "local" } }\`. Prostgles creates and manages the file table and serves its files.
-    - For S3 storage, use \`storageType: { type: "S3", credential_id }\`; configure the credential in Prostgles and never put access keys in this repository.
-    - Reference \`files.id\` from application tables with foreign keys rather than storing file URLs. Referencing tables must have a primary key. Use \`referencedTables\` when file type or size restrictions are required.
-    - Use \`delayedDelete\` when files should remain recoverable for a retention period. Enable \`extractText\` and provide an \`annotationsTable\` only when document extraction or annotations are needed.
-    - Local file data lives outside PostgreSQL. Use persistent storage and include it in deployment backups.
-
-    ## Server-side functions
-
-    - ${schemaConfigGuidance.functions}
-    - Organize \`functions\` into groups shaped as \`{ userFilter, functions }\`. The group filter controls which authenticated users receive those functions.
-    - Create a schema-aware group helper with \`createFunctionGroupDefiner<DBGeneratedSchema>()\`. For function maps kept in separate modules, use \`createFunctionsDefiner<DBGeneratedSchema>()\` so names, database context, inputs, and return types remain inferred across imports.
-    - Define individual functions with \`defineFunction({ input, description, run })\`. Inputs use Prostgles JSONB field definitions and are validated before \`run\` executes.
-    - Functions have restricted database access by default. Set \`unrestrictedDbAccess: true\` only when the function needs raw SQL, transactions, or client DB-handler generation.
-    - Keep secrets on the server and use database transactions for multi-step writes.`);
-exports.getCliAgentsFile = getCliAgentsFile;
-//# sourceMappingURL=getCliAgentsFile.js.map

package/dist/server/src/cli/getCliAgentsFile.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"getCliAgentsFile.js","sourceRoot":"","sources":["../../../../src/cli/getCliAgentsFile.ts"],"names":[],"mappings":";;;AAAA,yCAA0C;AAW1C;;;GAGG;AACH,MAAM,oBAAoB,GAAG;IAC3B,cAAc,EACZ,iGAAiG;IACnG,UAAU,EACR,mGAAmG;IACrG,cAAc,EACZ,+FAA+F;IACjG,SAAS,EACP,4GAA4G;IAC9G,EAAE,EAAE,oEAAoE;IACxE,KAAK,EACH,+EAA+E;IACjF,SAAS,EACP,wFAAwF;IAC1F,OAAO,EACL,gGAAgG;IAClG,QAAQ,EACN,2FAA2F;IAC7F,WAAW,EACT,gFAAgF;IAClF,qBAAqB,EACnB,iHAAiH;IACnH,UAAU,EAAE,8DAA8D;IAC1E,eAAe,EACb,+EAA+E;IACjF,UAAU,EACR,0FAA0F;CAC9D,CAAC;AAEjC,MAAM,kBAAkB,GAAG;IACzB,gBAAgB,EACd,gFAAgF;IAClF,eAAe,EACb,wEAAwE;IAC1E,aAAa,EACX,yPAAyP;CAC/N,CAAC;AAExB,MAAM,gBAAgB,GAAG,GAAG,EAAE,CACnC,IAAA,iBAAS,EAAC;;;;;;;;;QASJ,oBAAoB,CAAC,EAAE;QACvB,oBAAoB,CAAC,UAAU,IAAI,kBAAkB,CAAC,gBAAgB,IAAI,kBAAkB,CAAC,eAAe;QAC5G,oBAAoB,CAAC,cAAc;QACnC,oBAAoB,CAAC,cAAc;QACnC,oBAAoB,CAAC,eAAe;QACpC,oBAAoB,CAAC,SAAS,IAAI,oBAAoB,CAAC,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;QAmC9D,oBAAoB,CAAC,WAAW,IAAI,oBAAoB,CAAC,qBAAqB;QAC9E,oBAAoB,CAAC,UAAU;QAC/B,kBAAkB,CAAC,aAAa;;;QAGhC,oBAAoB,CAAC,KAAK;;;;QAI1B,oBAAoB,CAAC,UAAU;;;;;;;;;;;;;QAa/B,oBAAoB,CAAC,SAAS;;;;;sFAKgD,CAAC,CAAC;AA7E3E,QAAA,gBAAgB,oBA6E2D"}