@rvoh/psychic 2.0.3 → 2.1.0

package/dist/cjs/src/bin/index.js

@@ -1,7 +1,7 @@
 import { CliFileWriter, DreamBin, DreamCLI } from '@rvoh/dream/system';
 import * as fs from 'node:fs/promises';
 import * as path from 'node:path';
-import TypesBuilder from '../cli/helpers/TypesBuilder.js';
+import ASTPsychicTypesBuilder from '../cli/helpers/ASTPsychicTypesBuilder.js';
 import generateController from '../generate/controller.js';
 import generateResource from '../generate/resource.js';
 import isObject from '../helpers/isObject.js';
@@ -54,11 +54,10 @@ export default class PsychicBin {
             await CliFileWriter.revert();
         }
     }
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    static async syncTypes(customTypes = undefined) {
-        DreamCLI.logger.logStartProgress(`syncing types/psychic.ts...`);
-        await TypesBuilder.sync(customTypes);
-        DreamCLI.logger.logEndProgress();
+    static async syncTypes() {
+        await DreamCLI.logger.logProgress(`syncing types/psychic.ts...`, async () => {
+            await new ASTPsychicTypesBuilder().build();
+        });
     }
     static async syncOpenapiTypescriptFiles() {
         DreamCLI.logger.logStartProgress(`syncing openapi types...`);
@@ -117,8 +116,5 @@ export default class PsychicBin {
                 output = { ...output, ...res };
             }
         }
-        if (Object.keys(output).length) {
-            await PsychicBin.syncTypes(output);
-        }
     }
 }

package/dist/cjs/src/cli/helpers/ASTBuilder.js

@@ -0,0 +1,175 @@
+import { DreamApp } from '@rvoh/dream';
+import * as path from 'node:path';
+import ts from 'typescript';
+const f = ts.factory;
+/**
+ * @internal
+ *
+ * This is a base class, which is inherited by the ASTSchemaBuilder,
+ * the ASTKyselyCodegenEnhancer, and the ASTGlobalSchemaBuilder,
+ * each of which is responsible for building up the output of the various
+ * type files consumed by dream internally.
+ *
+ * This base class is just a container for common methods used by all
+ * classes.
+ */
+export default class ASTBuilder {
+    /**
+     * @internal
+     *
+     * builds a new line, useful for injecting new lines into AST statements
+     */
+    newLine() {
+        return f.createIdentifier('\n');
+    }
+    /**
+     * @internal
+     *
+     * given an interface declaration, it will extrace the relevant property statement
+     * by the given property name.
+     */
+    getPropertyFromInterface(interfaceNode, propertyName) {
+        for (const member of interfaceNode.members) {
+            if (ts.isPropertySignature(member)) {
+                if (ts.isIdentifier(member.name) && member.name.text === propertyName) {
+                    return member;
+                }
+            }
+        }
+        return null;
+    }
+    /**
+     * @internal
+     *
+     * returns an array of string type literals which were extracted from
+     * either a type or type union, depending on what is provided
+     * for the typeAlias. this allows you to safely and easily collect
+     * an array of types given an alias
+     */
+    extractStringLiteralTypeNodesFromTypeOrUnion(typeAlias) {
+        const literals = [];
+        if (ts.isUnionTypeNode(typeAlias.type)) {
+            typeAlias.type.types.forEach(typeNode => {
+                if (ts.isLiteralTypeNode(typeNode) && ts.isStringLiteral(typeNode.literal)) {
+                    literals.push(typeNode);
+                }
+            });
+        }
+        else if (ts.isLiteralTypeNode(typeAlias.type) && ts.isStringLiteral(typeAlias.type.literal)) {
+            literals.push(typeAlias.type);
+        }
+        return literals;
+    }
+    /**
+     * @internal
+     *
+     * returns an array of type literals which were extracted from
+     * either a type or type union, depending on what is provided
+     * for the typeAlias. this allows you to safely and easily collect
+     * an array of types given an alias
+     */
+    extractTypeNodesFromTypeOrUnion(typeAlias) {
+        const literals = [];
+        if (typeAlias.type && ts.isUnionTypeNode(typeAlias.type)) {
+            typeAlias.type.types.forEach(typeNode => {
+                literals.push(typeNode);
+            });
+        }
+        else if (typeAlias.type) {
+            literals.push(typeAlias.type);
+        }
+        return literals;
+    }
+    /**
+     * @internal
+     *
+     * returns the provided node iff
+     *   a.) the node is an exported type alias
+     *   b.) the exported name matches the provided name (or else there was no name provided)
+     *
+     *  otherwise, returns null
+     */
+    exportedTypeAliasOrNull(node, exportName) {
+        if (ts.isTypeAliasDeclaration(node) &&
+            node?.modifiers?.some(m => m.kind === ts.SyntaxKind.ExportKeyword) &&
+            (!exportName ? true : node.name.text === exportName))
+            return node;
+        return null;
+    }
+    /**
+     * @internal
+     *
+     * returns the provided node iff
+     *   a.) the node is an exported interface
+     *   b.) the exported name matches the provided name (or else there was no name provided)
+     *
+     *  otherwise, returns null
+     */
+    exportedInterfaceOrNull(node, exportName) {
+        if (ts.isInterfaceDeclaration(node) &&
+            node?.modifiers?.some(m => m.kind === ts.SyntaxKind.ExportKeyword) &&
+            (!exportName ? true : node.name.text === exportName))
+            return node;
+        return null;
+    }
+    /**
+     * @internal
+     *
+     * returns the path to the dream.globals.ts file
+     */
+    psychicTypesPath() {
+        const dreamApp = DreamApp.getOrFail();
+        return path.join(dreamApp.projectRoot, dreamApp.paths.types, 'psychic.ts');
+    }
+    /**
+     * @internal
+     *
+     * safely runs prettier against the provided output. If prettier
+     * is not installed, then the original output is returned
+     */
+    async prettier(output) {
+        try {
+            // dynamically, safely bring in prettier.
+            // ini the event that it fails, we will return the
+            // original output, unformatted, since prettier
+            // is technically not a real dependency of dream,
+            // though psychic and dream apps are provisioned
+            // with prettier by default, so this should usually work
+            const prettier = (await import('prettier')).default;
+            const results = await prettier.format(output, {
+                parser: 'typescript',
+                semi: false,
+                singleQuote: true,
+                tabWidth: 2,
+                lineWidth: 80,
+            });
+            return typeof results === 'string' ? results : output;
+        }
+        catch {
+            // intentional noop, we don't want to raise if prettier
+            // fails, since it is possible for the end user to not
+            // want to use prettier, and it is not a required peer
+            // dependency of dream
+            return output;
+        }
+    }
+    /**
+     * @internal
+     *
+     * given a type node, it will send back the first found generic
+     * provided to that type.
+     */
+    getFirstGenericType(node) {
+        if (ts.isTypeReferenceNode(node)) {
+            if (node.typeArguments && node.typeArguments.length > 0) {
+                return node.typeArguments[0];
+            }
+        }
+        else if (ts.isCallExpression(node)) {
+            if (node.typeArguments && node.typeArguments.length > 0) {
+                return node.typeArguments[0];
+            }
+        }
+        return null;
+    }
+}

package/dist/cjs/src/cli/helpers/ASTPsychicTypesBuilder.js

@@ -0,0 +1,59 @@
+import { CliFileWriter, DreamCLI } from '@rvoh/dream/system';
+import ts from 'typescript';
+import PsychicApp from '../../psychic-app/index.js';
+import ASTBuilder from './ASTBuilder.js';
+const f = ts.factory;
+/**
+ * Responsible for building dream globals, which can be found at
+ * types/dream.globals.ts.
+ *
+ * This class leverages internal AST building mechanisms built into
+ * typescript to manually build up object literals and interfaces
+ * for our app to consume.
+ */
+export default class ASTPsychicTypesBuilder extends ASTBuilder {
+    async build() {
+        const logger = DreamCLI.logger;
+        const sourceFile = ts.createSourceFile('', '', ts.ScriptTarget.Latest, false, ts.ScriptKind.TS);
+        await logger.logProgress('[psychic] building psychic types', async () => {
+            const output = await this.prettier(this.printStatements(this.buildPsychicTypes(), sourceFile));
+            await CliFileWriter.write(this.psychicTypesPath(), output);
+        });
+    }
+    /**
+     * @internal
+     *
+     * builds up the `export const psychicTypes = ...` statement within the types/psychic.ts
+     * file. It does this by leveraging low-level AST utils built into typescript
+     * to manually build up an object literal, cast it as a const, and write it to
+     * an exported variable.
+     */
+    buildPsychicTypes() {
+        const psychicApp = PsychicApp.getOrFail();
+        const psychicTypesObjectLiteral = f.createObjectLiteralExpression([
+            f.createPropertyAssignment(f.createIdentifier('openapiNames'), f.createArrayLiteralExpression(Object.keys(psychicApp.openapi).map(key => f.createStringLiteral(key)))),
+        ], true);
+        // add "as const" to the end of the schema object we
+        // have built before returning it
+        const constAssertion = f.createAsExpression(psychicTypesObjectLiteral, f.createKeywordTypeNode(ts.SyntaxKind.ConstKeyword));
+        const psychicTypesObjectLiteralConst = f.createVariableStatement(undefined, f.createVariableDeclarationList([
+            f.createVariableDeclaration(f.createIdentifier('psychicTypes'), undefined, undefined, constAssertion),
+        ], ts.NodeFlags.Const));
+        const defaultExportIdentifier = f.createIdentifier('psychicTypes');
+        const exportDefaultStatement = f.createExportDefault(defaultExportIdentifier);
+        return [psychicTypesObjectLiteralConst, this.newLine(), exportDefaultStatement];
+    }
+    /**
+     * @internal
+     *
+     * writes the compiled statements to string.
+     *
+     */
+    printStatements(statements, sourceFile) {
+        const printer = ts.createPrinter({ newLine: ts.NewLineKind.LineFeed, omitTrailingSemicolon: true });
+        const result = printer.printList(ts.ListFormat.SourceFileStatements, f.createNodeArray(statements), sourceFile);
+        // TODO: add autogenerate disclaimer
+        return `\
+${result}`;
+    }
+}

package/dist/cjs/src/cli/index.js

@@ -66,7 +66,7 @@ export default class PsychicCLI {
         program
             .command('generate:resource')
             .alias('g:resource')
-            .description('create a Dream model, migration, controller, serializer, and spec placeholders')
+            .description('Generates a Dream model with corresponding spec factory, serializer, migration, and controller with the inheritance chain leading to that controller, with fleshed out specs for each resourceful action in the controller.')
             .option('--singular', 'generates a "resource" route instead of "resources", along with the necessary controller and spec changes')
             .option('--only <onlyActions>', `comma separated list of resourceful endpionts (e.g. "--only=create,show"); any of:
                               - index
@@ -91,7 +91,7 @@ export default class PsychicCLI {
         program
             .command('generate:controller')
             .alias('g:controller')
-            .description('create a controller')
+            .description('Generates a controller and the inheritance chain leading to that controller, and a spec skeleton for the controller.')
             .argument('<controllerName>', 'the name of the controller to create, including namespaces, e.g. Posts or Api/V1/Posts')
             .argument('[actions...]', 'the names of controller actions to create')
             .action(async (controllerName, actions) => {
@@ -101,7 +101,7 @@ export default class PsychicCLI {
         });
         program
             .command('setup:sync:enums')
-            .description('generates an initializer in your app for syncing enums to a particular path.')
+            .description('Generates an initializer in your app for syncing enums to a particular path.')
             .argument('<outfile>', 'the path from your backend directory to the location which you want the enums copied. Should end with .ts, i.e. "../client/src/api/enums.ts"')
             .option('--initializer-filename <initializerFilename>', 'the name you want the file to be in your initializers folder. defaults to `sync-enums.ts`')
             .action(async (outfile, { initializerName, }) => {
@@ -114,7 +114,7 @@ export default class PsychicCLI {
         });
         program
             .command('setup:sync:openapi-redux')
-            .description('generates openapi redux bindings to connect one of your openapi files to one of your clients')
+            .description('Generates openapi redux bindings to connect one of your openapi files to one of your clients.')
             .option('--schema-file <schemaFile>', 'the path from your api root to the openapi file you wish to use to generate your schema, i.e. ./src/openapi/openapi.json')
             .option('--api-file <apiFile>', 'the path to the boilerplate api file that will be used to scaffold your backend endpoints together with, i.e. ../client/app/api.ts')
             .option('--api-import <apiImport>', 'the camelCased name of the export from your api module, i.e. emptyBackendApi')
@@ -136,7 +136,7 @@ export default class PsychicCLI {
         });
         program
             .command('setup:sync:openapi-typescript')
-            .description('generates an initializer in your app for converting one of your openapi files to typescript')
+            .description('Generates an initializer in your app for converting one of your openapi files to typescript.')
             .argument('<openapiFilepath>', 'the path from your backend directory to the openapi file you wish to scan, i.e. "./src/openapi/openapi.json"')
             .argument('<outfile>', 'the path from your backend directory to the location which you want the openapi types written to. Must end with .d.ts, i.e. "./src/conf/openapi/openapi.types.d.ts"')
             .option('--initializer-filename <initializerFilename>', 'the name you want the file to be in your initializers folder. defaults to `sync-openapi-typescript.ts`')
@@ -150,7 +150,7 @@ export default class PsychicCLI {
         });
         program
             .command('routes')
-            .description('examines your current models, building a type-map of the associations so that the ORM can understand your relational setup. This is commited to your repo, and synced to the dream repo for consumption within the underlying library.')
+            .description('Prints a list of routes defined by the application, including path arguments and the controller/action reached by the route.')
             .action(async () => {
             await initializePsychicApp();
             PsychicBin.printRoutes();
@@ -158,7 +158,7 @@ export default class PsychicCLI {
         });
         program
             .command('sync')
-            .description('sync introspects your database, updating your schema to reflect, and then syncs the new schema with the installed dream node module, allowing it provide your schema to the underlying kysely integration')
+            .description("Generates types from the current state of the database. Generates OpenAPI specs from @OpenAPI decorated controller actions. Additional sync actions may be customized with `on('cli:sync', async () => {})` in conf/app.ts or in an initializer in `conf/initializers/`.")
             .option('--ignore-errors')
             .option('--schema-only')
             .action(async (options) => {
@@ -184,13 +184,13 @@ export default class PsychicCLI {
         });
         program
             .command('sync:routes')
-            .description('reads the routes generated by your app and generates a cache file, which is then used to give autocomplete support to the route helper, amoongst other things.')
+            .description('Reads the routes generated by your app and generates a cache file, which is then used to give autocomplete support to the route helper and other things.')
             .action(async () => {
             await PsychicBin.syncRoutes();
         });
         program
             .command('sync:openapi')
-            .description('syncs openapi.json file to current state of all psychic controllers within the app')
+            .description('Syncs openapi.json file to current state of all psychic controllers within the app')
             .action(async () => {
             await initializePsychicApp();
             await PsychicBin.syncOpenapiJson();

package/dist/esm/src/bin/index.js

@@ -1,7 +1,7 @@
 import { CliFileWriter, DreamBin, DreamCLI } from '@rvoh/dream/system';
 import * as fs from 'node:fs/promises';
 import * as path from 'node:path';
-import TypesBuilder from '../cli/helpers/TypesBuilder.js';
+import ASTPsychicTypesBuilder from '../cli/helpers/ASTPsychicTypesBuilder.js';
 import generateController from '../generate/controller.js';
 import generateResource from '../generate/resource.js';
 import isObject from '../helpers/isObject.js';
@@ -54,11 +54,10 @@ export default class PsychicBin {
             await CliFileWriter.revert();
         }
     }
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    static async syncTypes(customTypes = undefined) {
-        DreamCLI.logger.logStartProgress(`syncing types/psychic.ts...`);
-        await TypesBuilder.sync(customTypes);
-        DreamCLI.logger.logEndProgress();
+    static async syncTypes() {
+        await DreamCLI.logger.logProgress(`syncing types/psychic.ts...`, async () => {
+            await new ASTPsychicTypesBuilder().build();
+        });
     }
     static async syncOpenapiTypescriptFiles() {
         DreamCLI.logger.logStartProgress(`syncing openapi types...`);
@@ -117,8 +116,5 @@ export default class PsychicBin {
                 output = { ...output, ...res };
             }
         }
-        if (Object.keys(output).length) {
-            await PsychicBin.syncTypes(output);
-        }
     }
 }

package/dist/esm/src/cli/helpers/ASTBuilder.js

@@ -0,0 +1,175 @@
+import { DreamApp } from '@rvoh/dream';
+import * as path from 'node:path';
+import ts from 'typescript';
+const f = ts.factory;
+/**
+ * @internal
+ *
+ * This is a base class, which is inherited by the ASTSchemaBuilder,
+ * the ASTKyselyCodegenEnhancer, and the ASTGlobalSchemaBuilder,
+ * each of which is responsible for building up the output of the various
+ * type files consumed by dream internally.
+ *
+ * This base class is just a container for common methods used by all
+ * classes.
+ */
+export default class ASTBuilder {
+    /**
+     * @internal
+     *
+     * builds a new line, useful for injecting new lines into AST statements
+     */
+    newLine() {
+        return f.createIdentifier('\n');
+    }
+    /**
+     * @internal
+     *
+     * given an interface declaration, it will extrace the relevant property statement
+     * by the given property name.
+     */
+    getPropertyFromInterface(interfaceNode, propertyName) {
+        for (const member of interfaceNode.members) {
+            if (ts.isPropertySignature(member)) {
+                if (ts.isIdentifier(member.name) && member.name.text === propertyName) {
+                    return member;
+                }
+            }
+        }
+        return null;
+    }
+    /**
+     * @internal
+     *
+     * returns an array of string type literals which were extracted from
+     * either a type or type union, depending on what is provided
+     * for the typeAlias. this allows you to safely and easily collect
+     * an array of types given an alias
+     */
+    extractStringLiteralTypeNodesFromTypeOrUnion(typeAlias) {
+        const literals = [];
+        if (ts.isUnionTypeNode(typeAlias.type)) {
+            typeAlias.type.types.forEach(typeNode => {
+                if (ts.isLiteralTypeNode(typeNode) && ts.isStringLiteral(typeNode.literal)) {
+                    literals.push(typeNode);
+                }
+            });
+        }
+        else if (ts.isLiteralTypeNode(typeAlias.type) && ts.isStringLiteral(typeAlias.type.literal)) {
+            literals.push(typeAlias.type);
+        }
+        return literals;
+    }
+    /**
+     * @internal
+     *
+     * returns an array of type literals which were extracted from
+     * either a type or type union, depending on what is provided
+     * for the typeAlias. this allows you to safely and easily collect
+     * an array of types given an alias
+     */
+    extractTypeNodesFromTypeOrUnion(typeAlias) {
+        const literals = [];
+        if (typeAlias.type && ts.isUnionTypeNode(typeAlias.type)) {
+            typeAlias.type.types.forEach(typeNode => {
+                literals.push(typeNode);
+            });
+        }
+        else if (typeAlias.type) {
+            literals.push(typeAlias.type);
+        }
+        return literals;
+    }
+    /**
+     * @internal
+     *
+     * returns the provided node iff
+     *   a.) the node is an exported type alias
+     *   b.) the exported name matches the provided name (or else there was no name provided)
+     *
+     *  otherwise, returns null
+     */
+    exportedTypeAliasOrNull(node, exportName) {
+        if (ts.isTypeAliasDeclaration(node) &&
+            node?.modifiers?.some(m => m.kind === ts.SyntaxKind.ExportKeyword) &&
+            (!exportName ? true : node.name.text === exportName))
+            return node;
+        return null;
+    }
+    /**
+     * @internal
+     *
+     * returns the provided node iff
+     *   a.) the node is an exported interface
+     *   b.) the exported name matches the provided name (or else there was no name provided)
+     *
+     *  otherwise, returns null
+     */
+    exportedInterfaceOrNull(node, exportName) {
+        if (ts.isInterfaceDeclaration(node) &&
+            node?.modifiers?.some(m => m.kind === ts.SyntaxKind.ExportKeyword) &&
+            (!exportName ? true : node.name.text === exportName))
+            return node;
+        return null;
+    }
+    /**
+     * @internal
+     *
+     * returns the path to the dream.globals.ts file
+     */
+    psychicTypesPath() {
+        const dreamApp = DreamApp.getOrFail();
+        return path.join(dreamApp.projectRoot, dreamApp.paths.types, 'psychic.ts');
+    }
+    /**
+     * @internal
+     *
+     * safely runs prettier against the provided output. If prettier
+     * is not installed, then the original output is returned
+     */
+    async prettier(output) {
+        try {
+            // dynamically, safely bring in prettier.
+            // ini the event that it fails, we will return the
+            // original output, unformatted, since prettier
+            // is technically not a real dependency of dream,
+            // though psychic and dream apps are provisioned
+            // with prettier by default, so this should usually work
+            const prettier = (await import('prettier')).default;
+            const results = await prettier.format(output, {
+                parser: 'typescript',
+                semi: false,
+                singleQuote: true,
+                tabWidth: 2,
+                lineWidth: 80,
+            });
+            return typeof results === 'string' ? results : output;
+        }
+        catch {
+            // intentional noop, we don't want to raise if prettier
+            // fails, since it is possible for the end user to not
+            // want to use prettier, and it is not a required peer
+            // dependency of dream
+            return output;
+        }
+    }
+    /**
+     * @internal
+     *
+     * given a type node, it will send back the first found generic
+     * provided to that type.
+     */
+    getFirstGenericType(node) {
+        if (ts.isTypeReferenceNode(node)) {
+            if (node.typeArguments && node.typeArguments.length > 0) {
+                return node.typeArguments[0];
+            }
+        }
+        else if (ts.isCallExpression(node)) {
+            if (node.typeArguments && node.typeArguments.length > 0) {
+                return node.typeArguments[0];
+            }
+        }
+        return null;
+    }
+}

package/dist/esm/src/cli/helpers/ASTPsychicTypesBuilder.js

@@ -0,0 +1,59 @@
+import { CliFileWriter, DreamCLI } from '@rvoh/dream/system';
+import ts from 'typescript';
+import PsychicApp from '../../psychic-app/index.js';
+import ASTBuilder from './ASTBuilder.js';
+const f = ts.factory;
+/**
+ * Responsible for building dream globals, which can be found at
+ * types/dream.globals.ts.
+ *
+ * This class leverages internal AST building mechanisms built into
+ * typescript to manually build up object literals and interfaces
+ * for our app to consume.
+ */
+export default class ASTPsychicTypesBuilder extends ASTBuilder {
+    async build() {
+        const logger = DreamCLI.logger;
+        const sourceFile = ts.createSourceFile('', '', ts.ScriptTarget.Latest, false, ts.ScriptKind.TS);
+        await logger.logProgress('[psychic] building psychic types', async () => {
+            const output = await this.prettier(this.printStatements(this.buildPsychicTypes(), sourceFile));
+            await CliFileWriter.write(this.psychicTypesPath(), output);
+        });
+    }
+    /**
+     * @internal
+     *
+     * builds up the `export const psychicTypes = ...` statement within the types/psychic.ts
+     * file. It does this by leveraging low-level AST utils built into typescript
+     * to manually build up an object literal, cast it as a const, and write it to
+     * an exported variable.
+     */
+    buildPsychicTypes() {
+        const psychicApp = PsychicApp.getOrFail();
+        const psychicTypesObjectLiteral = f.createObjectLiteralExpression([
+            f.createPropertyAssignment(f.createIdentifier('openapiNames'), f.createArrayLiteralExpression(Object.keys(psychicApp.openapi).map(key => f.createStringLiteral(key)))),
+        ], true);
+        // add "as const" to the end of the schema object we
+        // have built before returning it
+        const constAssertion = f.createAsExpression(psychicTypesObjectLiteral, f.createKeywordTypeNode(ts.SyntaxKind.ConstKeyword));
+        const psychicTypesObjectLiteralConst = f.createVariableStatement(undefined, f.createVariableDeclarationList([
+            f.createVariableDeclaration(f.createIdentifier('psychicTypes'), undefined, undefined, constAssertion),
+        ], ts.NodeFlags.Const));
+        const defaultExportIdentifier = f.createIdentifier('psychicTypes');
+        const exportDefaultStatement = f.createExportDefault(defaultExportIdentifier);
+        return [psychicTypesObjectLiteralConst, this.newLine(), exportDefaultStatement];
+    }
+    /**
+     * @internal
+     *
+     * writes the compiled statements to string.
+     *
+     */
+    printStatements(statements, sourceFile) {
+        const printer = ts.createPrinter({ newLine: ts.NewLineKind.LineFeed, omitTrailingSemicolon: true });
+        const result = printer.printList(ts.ListFormat.SourceFileStatements, f.createNodeArray(statements), sourceFile);
+        // TODO: add autogenerate disclaimer
+        return `\
+${result}`;
+    }
+}

package/dist/esm/src/cli/index.js

@@ -66,7 +66,7 @@ export default class PsychicCLI {
         program
             .command('generate:resource')
             .alias('g:resource')
-            .description('create a Dream model, migration, controller, serializer, and spec placeholders')
+            .description('Generates a Dream model with corresponding spec factory, serializer, migration, and controller with the inheritance chain leading to that controller, with fleshed out specs for each resourceful action in the controller.')
             .option('--singular', 'generates a "resource" route instead of "resources", along with the necessary controller and spec changes')
             .option('--only <onlyActions>', `comma separated list of resourceful endpionts (e.g. "--only=create,show"); any of:
                               - index
@@ -91,7 +91,7 @@ export default class PsychicCLI {
         program
             .command('generate:controller')
             .alias('g:controller')
-            .description('create a controller')
+            .description('Generates a controller and the inheritance chain leading to that controller, and a spec skeleton for the controller.')
             .argument('<controllerName>', 'the name of the controller to create, including namespaces, e.g. Posts or Api/V1/Posts')
             .argument('[actions...]', 'the names of controller actions to create')
             .action(async (controllerName, actions) => {
@@ -101,7 +101,7 @@ export default class PsychicCLI {
         });
         program
             .command('setup:sync:enums')
-            .description('generates an initializer in your app for syncing enums to a particular path.')
+            .description('Generates an initializer in your app for syncing enums to a particular path.')
             .argument('<outfile>', 'the path from your backend directory to the location which you want the enums copied. Should end with .ts, i.e. "../client/src/api/enums.ts"')
             .option('--initializer-filename <initializerFilename>', 'the name you want the file to be in your initializers folder. defaults to `sync-enums.ts`')
             .action(async (outfile, { initializerName, }) => {
@@ -114,7 +114,7 @@ export default class PsychicCLI {
         });
         program
             .command('setup:sync:openapi-redux')
-            .description('generates openapi redux bindings to connect one of your openapi files to one of your clients')
+            .description('Generates openapi redux bindings to connect one of your openapi files to one of your clients.')
             .option('--schema-file <schemaFile>', 'the path from your api root to the openapi file you wish to use to generate your schema, i.e. ./src/openapi/openapi.json')
             .option('--api-file <apiFile>', 'the path to the boilerplate api file that will be used to scaffold your backend endpoints together with, i.e. ../client/app/api.ts')
             .option('--api-import <apiImport>', 'the camelCased name of the export from your api module, i.e. emptyBackendApi')
@@ -136,7 +136,7 @@ export default class PsychicCLI {
         });
         program
             .command('setup:sync:openapi-typescript')
-            .description('generates an initializer in your app for converting one of your openapi files to typescript')
+            .description('Generates an initializer in your app for converting one of your openapi files to typescript.')
             .argument('<openapiFilepath>', 'the path from your backend directory to the openapi file you wish to scan, i.e. "./src/openapi/openapi.json"')
             .argument('<outfile>', 'the path from your backend directory to the location which you want the openapi types written to. Must end with .d.ts, i.e. "./src/conf/openapi/openapi.types.d.ts"')
             .option('--initializer-filename <initializerFilename>', 'the name you want the file to be in your initializers folder. defaults to `sync-openapi-typescript.ts`')
@@ -150,7 +150,7 @@ export default class PsychicCLI {
         });
         program
             .command('routes')
-            .description('examines your current models, building a type-map of the associations so that the ORM can understand your relational setup. This is commited to your repo, and synced to the dream repo for consumption within the underlying library.')
+            .description('Prints a list of routes defined by the application, including path arguments and the controller/action reached by the route.')
             .action(async () => {
             await initializePsychicApp();
             PsychicBin.printRoutes();
@@ -158,7 +158,7 @@ export default class PsychicCLI {
         });
         program
             .command('sync')
-            .description('sync introspects your database, updating your schema to reflect, and then syncs the new schema with the installed dream node module, allowing it provide your schema to the underlying kysely integration')
+            .description("Generates types from the current state of the database. Generates OpenAPI specs from @OpenAPI decorated controller actions. Additional sync actions may be customized with `on('cli:sync', async () => {})` in conf/app.ts or in an initializer in `conf/initializers/`.")
             .option('--ignore-errors')
             .option('--schema-only')
             .action(async (options) => {
@@ -184,13 +184,13 @@ export default class PsychicCLI {
         });
         program
             .command('sync:routes')
-            .description('reads the routes generated by your app and generates a cache file, which is then used to give autocomplete support to the route helper, amoongst other things.')
+            .description('Reads the routes generated by your app and generates a cache file, which is then used to give autocomplete support to the route helper and other things.')
             .action(async () => {
             await PsychicBin.syncRoutes();
         });
         program
             .command('sync:openapi')
-            .description('syncs openapi.json file to current state of all psychic controllers within the app')
+            .description('Syncs openapi.json file to current state of all psychic controllers within the app')
             .action(async () => {
             await initializePsychicApp();
             await PsychicBin.syncOpenapiJson();

package/dist/types/src/bin/index.d.ts

@@ -13,7 +13,7 @@ export default class PsychicBin {
         schemaOnly?: boolean;
     }): Promise<void>;
     static postSync(): Promise<void>;
-    static syncTypes(customTypes?: any): Promise<void>;
+    static syncTypes(): Promise<void>;
     static syncOpenapiTypescriptFiles(): Promise<void>;
     static syncOpenapiJson(): Promise<void>;
     static syncRoutes(): Promise<void>;

package/dist/types/src/cli/helpers/ASTBuilder.d.ts

@@ -0,0 +1,89 @@
+import ts from 'typescript';
+/**
+ * @internal
+ *
+ * This is a base class, which is inherited by the ASTSchemaBuilder,
+ * the ASTKyselyCodegenEnhancer, and the ASTGlobalSchemaBuilder,
+ * each of which is responsible for building up the output of the various
+ * type files consumed by dream internally.
+ *
+ * This base class is just a container for common methods used by all
+ * classes.
+ */
+export default class ASTBuilder {
+    /**
+     * @internal
+     *
+     * builds a new line, useful for injecting new lines into AST statements
+     */
+    protected newLine(): ts.Identifier;
+    /**
+     * @internal
+     *
+     * given an interface declaration, it will extrace the relevant property statement
+     * by the given property name.
+     */
+    protected getPropertyFromInterface(interfaceNode: ts.InterfaceDeclaration, propertyName: string): ts.PropertySignature | null;
+    /**
+     * @internal
+     *
+     * returns an array of string type literals which were extracted from
+     * either a type or type union, depending on what is provided
+     * for the typeAlias. this allows you to safely and easily collect
+     * an array of types given an alias
+     */
+    protected extractStringLiteralTypeNodesFromTypeOrUnion(typeAlias: ts.TypeAliasDeclaration): (ts.LiteralTypeNode & {
+        literal: {
+            text: string;
+        };
+    })[];
+    /**
+     * @internal
+     *
+     * returns an array of type literals which were extracted from
+     * either a type or type union, depending on what is provided
+     * for the typeAlias. this allows you to safely and easily collect
+     * an array of types given an alias
+     */
+    protected extractTypeNodesFromTypeOrUnion(typeAlias: ts.TypeAliasDeclaration | ts.PropertySignature): ts.TypeNode[];
+    /**
+     * @internal
+     *
+     * returns the provided node iff
+     *   a.) the node is an exported type alias
+     *   b.) the exported name matches the provided name (or else there was no name provided)
+     *
+     *  otherwise, returns null
+     */
+    protected exportedTypeAliasOrNull(node: ts.Node, exportName?: string): ts.TypeAliasDeclaration | null;
+    /**
+     * @internal
+     *
+     * returns the provided node iff
+     *   a.) the node is an exported interface
+     *   b.) the exported name matches the provided name (or else there was no name provided)
+     *
+     *  otherwise, returns null
+     */
+    protected exportedInterfaceOrNull(node: ts.Node, exportName?: string): ts.InterfaceDeclaration | null;
+    /**
+     * @internal
+     *
+     * returns the path to the dream.globals.ts file
+     */
+    protected psychicTypesPath(): string;
+    /**
+     * @internal
+     *
+     * safely runs prettier against the provided output. If prettier
+     * is not installed, then the original output is returned
+     */
+    protected prettier(output: string): Promise<string>;
+    /**
+     * @internal
+     *
+     * given a type node, it will send back the first found generic
+     * provided to that type.
+     */
+    protected getFirstGenericType(node: ts.Node): ts.TypeNode | null;
+}

package/dist/types/src/cli/helpers/ASTPsychicTypesBuilder.d.ts

@@ -0,0 +1,28 @@
+import ASTBuilder from './ASTBuilder.js';
+/**
+ * Responsible for building dream globals, which can be found at
+ * types/dream.globals.ts.
+ *
+ * This class leverages internal AST building mechanisms built into
+ * typescript to manually build up object literals and interfaces
+ * for our app to consume.
+ */
+export default class ASTPsychicTypesBuilder extends ASTBuilder {
+    build(): Promise<void>;
+    /**
+     * @internal
+     *
+     * builds up the `export const psychicTypes = ...` statement within the types/psychic.ts
+     * file. It does this by leveraging low-level AST utils built into typescript
+     * to manually build up an object literal, cast it as a const, and write it to
+     * an exported variable.
+     */
+    private buildPsychicTypes;
+    /**
+     * @internal
+     *
+     * writes the compiled statements to string.
+     *
+     */
+    private printStatements;
+}

package/package.json

@@ -2,7 +2,7 @@
   "type": "module",
   "name": "@rvoh/psychic",
   "description": "Typescript web framework",
-  "version": "2.0.3",
+  "version": "2.1.0",
   "author": "RVOHealth",
   "repository": {
     "type": "git",
@@ -81,7 +81,7 @@
     "@rvoh/dream": "^2.0.3",
     "@types/express": "^5.0.1",
     "commander": "^12.1.0",
-    "express": "^5.1.0",
+    "express": "^5.2.1",
     "openapi-typescript": "^7.8.0"
   },
   "devDependencies": {
@@ -90,7 +90,7 @@
     "@rvoh/dream": "^2.0.3",
     "@rvoh/dream-spec-helpers": "^2.0.0",
     "@rvoh/psychic-spec-helpers": "^2.0.0",
-    "@types/express": "^5.0.1",
+    "@types/express": "^5.0.6",
     "@types/express-session": "^1.18.2",
     "@types/node": "^22.17.1",
     "@types/passport": "^0",
@@ -99,7 +99,7 @@
     "@types/supertest": "^6.0.3",
     "@typescript/analyze-trace": "^0.10.1",
     "eslint": "^9.19.0",
-    "express": "^5.1.0",
+    "express": "^5.2.1",
     "express-session": "^1.18.2",
     "jsdom": "^26.1.0",
     "kysely": "^0.28.5",

package/dist/cjs/src/cli/helpers/TypesBuilder.js

@@ -1,23 +0,0 @@
-import { DreamApp } from '@rvoh/dream';
-import { CliFileWriter } from '@rvoh/dream/system';
-import * as path from 'node:path';
-import PsychicApp from '../../psychic-app/index.js';
-export default class TypesBuilder {
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    static async sync(customTypes = undefined) {
-        const dreamApp = DreamApp.getOrFail();
-        const schemaPath = path.join(dreamApp.projectRoot, dreamApp.paths.types, 'psychic.ts');
-        await CliFileWriter.write(schemaPath, this.build(customTypes));
-    }
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    static build(customTypes = undefined) {
-        const psychicApp = PsychicApp.getOrFail();
-        const output = {
-            openapiNames: Object.keys(psychicApp.openapi),
-            ...(customTypes || {}),
-        };
-        return `const psychicTypes = ${JSON.stringify(output, null, 2)} as const
-
-export default psychicTypes`;
-    }
-}

package/dist/esm/src/cli/helpers/TypesBuilder.js

@@ -1,23 +0,0 @@
-import { DreamApp } from '@rvoh/dream';
-import { CliFileWriter } from '@rvoh/dream/system';
-import * as path from 'node:path';
-import PsychicApp from '../../psychic-app/index.js';
-export default class TypesBuilder {
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    static async sync(customTypes = undefined) {
-        const dreamApp = DreamApp.getOrFail();
-        const schemaPath = path.join(dreamApp.projectRoot, dreamApp.paths.types, 'psychic.ts');
-        await CliFileWriter.write(schemaPath, this.build(customTypes));
-    }
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    static build(customTypes = undefined) {
-        const psychicApp = PsychicApp.getOrFail();
-        const output = {
-            openapiNames: Object.keys(psychicApp.openapi),
-            ...(customTypes || {}),
-        };
-        return `const psychicTypes = ${JSON.stringify(output, null, 2)} as const
-
-export default psychicTypes`;
-    }
-}

package/dist/types/src/cli/helpers/TypesBuilder.d.ts

@@ -1,7 +0,0 @@
-export default class TypesBuilder {
-    static sync(customTypes?: any): Promise<void>;
-    static build(customTypes?: any): string;
-}
-export interface PsychicTypeSync {
-    openapiNames: string[];
-}