@dereekb/dbx-cli 13.11.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Hapier Creative LLC.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/firebase-api-manifest/src/generate-api-manifest/bind-validators.d.ts

@@ -0,0 +1,44 @@
+/**
+ * For a given Params type name (e.g. `SetProfileUsernameParams`), derives the
+ * canonical arktype validator identifier (`setProfileUsernameParamsType`) by
+ * naming convention and confirms it is exported from the resolved package.
+ *
+ * Verification is best-effort: we string-search the package's `src/index.ts`
+ * and follow `export * from './...';` re-exports recursively until we find
+ * the declaration of the validator. The convention everywhere in the codebase
+ * is `export const <name>ParamsType = ... as Type<<Name>Params>`.
+ */
+/**
+ * Derives the canonical arktype validator identifier from a Params type name.
+ *
+ * `SetProfileUsernameParams` → `setProfileUsernameParamsType`.
+ *
+ * @param paramsTypeName - PascalCase Params type identifier.
+ * @returns The lowerCamelCase validator identifier (or empty string for empty input).
+ */
+export declare function deriveValidatorName(paramsTypeName: string): string;
+/**
+ * Inputs for {@link isExportedFromPackage}.
+ */
+export interface IsExportedInput {
+    readonly packageRoot: string;
+    readonly identifier: string;
+}
+/**
+ * Confirms an identifier is exported from `packageRoot/src/index.ts` —
+ * directly or via re-export chains.
+ *
+ * @param input - Package root + identifier to look up.
+ * @returns `true` when the identifier is reachable from the barrel.
+ */
+export declare function isExportedFromPackage(input: IsExportedInput): boolean;
+/**
+ * Walks the `src/lib` tree under a package and returns the absolute file
+ * paths of every `.ts` file (used as a fallback when index-chain lookup
+ * misses the identifier — some packages rely on flat barrels that don't
+ * `export *`).
+ *
+ * @param packageRoot - Absolute path to the source package's root directory.
+ * @returns Absolute paths of every non-spec `.ts` file under `src`.
+ */
+export declare function listPackageTsFiles(packageRoot: string): string[];

package/firebase-api-manifest/src/generate-api-manifest/emit.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Renders the final manifest TS module — banner + grouped imports + the
+ * `<NAMESPACE>` array literal. Formatted with the workspace prettier config
+ * so the output matches what `prettier --write` would produce on the
+ * committed file.
+ *
+ * The reusable `CliApiManifest` type is imported from `@dereekb/dbx-cli` so
+ * any consuming app gets it from the shared dbx-cli barrel.
+ */
+import type { CollectedEntry } from './types';
+/**
+ * Inputs for {@link renderManifest}.
+ */
+export interface RenderManifestInput {
+    readonly outputFile: string;
+    readonly entries: readonly CollectedEntry[];
+    readonly projectName: string;
+    readonly namespace: string;
+}
+/**
+ * Renders the manifest TS source for a CLI app and formats it with the
+ * workspace prettier config so the output matches a `prettier --write` of the
+ * committed file.
+ *
+ * @param input - Output file path, collected entries, project name (banner),
+ *   and the manifest namespace identifier.
+ * @returns Prettier-formatted TypeScript source.
+ */
+export declare function renderManifest(input: RenderManifestInput): Promise<string>;

package/firebase-api-manifest/src/generate-api-manifest/extract-crud.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Walks `<Group>ModelCrudFunctionsConfig` and `<Group>FunctionTypeMap` type
+ * aliases in a `<model>.api.ts` source. Returns one entry per callable leaf,
+ * keyed by (model, verb, specifier).
+ *
+ * Mirrors `extractCrudEntries` from
+ * packages/dbx-components-mcp/src/tools/model-api-shared/extract-crud.ts —
+ * keep the two in lockstep when the .api.ts convention changes.
+ */
+import type { CrudExtraction } from './types';
+/**
+ * Inputs for {@link extractCrudEntries}.
+ */
+export interface ExtractCrudInput {
+    readonly name: string;
+    readonly text: string;
+}
+/**
+ * Extracts CRUD + standalone entries from a `.api.ts` source by walking its
+ * `<Group>ModelCrudFunctionsConfig` and `<Group>FunctionTypeMap` aliases.
+ *
+ * @param source - The source file's name + text.
+ * @returns The extracted entries, group name, model keys, and `*Functions` class name.
+ */
+export declare function extractCrudEntries(source: ExtractCrudInput): CrudExtraction;

package/firebase-api-manifest/src/generate-api-manifest/find-api-files.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Walks a package's `src/lib/**\/*.api.ts` and returns the files that declare
+ * an abstract `*Functions` class along with the class name. Used to map a
+ * class identifier from `<APP>_FIREBASE_FUNCTIONS_CONFIG` back to the source
+ * `*.api.ts`.
+ */
+import type { ApiFileMatch } from './types';
+/**
+ * Walks `packageRoot/src/lib/**\/*.api.ts` and returns the files that declare
+ * an abstract `*Functions` class along with the class name and the
+ * extracted CRUD entries.
+ *
+ * @param packageRoot - Absolute path to the source package's root directory.
+ * @returns One {@link ApiFileMatch} per qualifying `.api.ts`.
+ */
+export declare function findApiFiles(packageRoot: string): ApiFileMatch[];

package/firebase-api-manifest/src/generate-api-manifest/main.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Generates an API manifest TS file for any dbx-components CLI app.
+ *
+ * Pipeline (build-time, run via `nx run <cli>:generate-api-manifest`):
+ *
+ *   1. Parse the app's `<APP>_FIREBASE_FUNCTIONS_CONFIG` from the file passed
+ *      via --functions-config to enumerate the `*Functions` abstract classes
+ *      used by the app, including their source-module specifier
+ *      ("@dereekb/firebase", "demo-firebase", "./model", "./development",
+ *      ...). The leading-app prefix is matched generically by
+ *      `/FIREBASE_FUNCTIONS_CONFIG$/` so any app variable name works.
+ *
+ *   2. Resolve each module to a source-package root via the workspace's
+ *      tsconfig.base.json `paths`.
+ *
+ *   3. Walk that package's `src/lib/**\/*.api.ts`, run the CRUD-entry walker
+ *      on each, and pick the file whose abstract `*Functions` class name
+ *      matches the entry's class identifier.
+ *
+ *   4. For each CRUD entry with a `paramsTypeName`, derive the canonical
+ *      arktype validator name (lowercaseFirst + `Type`) and confirm it is
+ *      exported from the package's barrel chain. Warn on miss; the entry is
+ *      still emitted with `paramsValidator: undefined`. `--strict` makes a
+ *      miss fatal.
+ *
+ *   5. Emit the manifest to the path passed via --output with grouped
+ *      per-package imports + the `<NAMESPACE>_API_MANIFEST` array literal.
+ *      Skip the write if the file content is byte-identical (preserves mtime
+ *      for incremental builds).
+ *
+ * Flags:
+ *   --functions-config=<path>   (required) path to the app's functions.ts.
+ *                                Absolute or workspace-relative.
+ *   --output=<path>             (required) path to the manifest TS file to write.
+ *                                Absolute or workspace-relative.
+ *   --project=<name>            Project name shown in the regenerate banner
+ *                                (defaults to "<cli>"). Also used to derive
+ *                                the manifest namespace (e.g. "demo-cli" ->
+ *                                DEMO_CLI_API_MANIFEST).
+ *   --only=<model[,model]>      Filter the emitted entries to those models.
+ *   --strict                    Exit 1 if any validator is missing.
+ *
+ * Run from any cwd; workspace-relative paths resolve against `process.cwd()`
+ * (Nx invokes with cwd: "{workspaceRoot}").
+ */
+export {};

package/firebase-api-manifest/src/generate-api-manifest/parse-functions.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Parses the `<APP>_FIREBASE_FUNCTIONS_CONFIG` variable from a CLI app's
+ * `functions.ts` and returns the (groupKey, className, importedFromModule)
+ * tuple for every entry.
+ *
+ * We follow the import declaration of the abstract-class identifier to know
+ * which package the `*.api.ts` lives in. The variable name is matched
+ * generically by `/FIREBASE_FUNCTIONS_CONFIG$/` so any app-prefix works.
+ */
+import type { FunctionsGroup } from './types';
+/**
+ * Parses the `<APP>_FIREBASE_FUNCTIONS_CONFIG` literal at `functionsTsPath`
+ * into one entry per group declared in the config object.
+ *
+ * @param functionsTsPath - Absolute path to the app's `functions.ts`.
+ * @returns One {@link FunctionsGroup} per `<groupKey>: [<Class>, ...]` pair.
+ */
+export declare function parseFunctionsConfig(functionsTsPath: string): FunctionsGroup[];

package/firebase-api-manifest/src/generate-api-manifest/resolve-package.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Resolves a workspace module specifier (e.g. "@dereekb/firebase",
+ * "demo-firebase", "./model", "./development") to a source-package root and
+ * canonical import name.
+ *
+ * Reads the workspace tsconfig.base.json `compilerOptions.paths` to map bare
+ * specifiers to their `src/index.ts` entry. Relative specifiers are resolved
+ * against the importing file's directory and then walked back up to the
+ * nearest `package.json` that owns them.
+ */
+import type { PackageRef } from './types';
+/**
+ * Inputs accepted by {@link resolveModuleToPackage}.
+ */
+export interface ResolveModuleInput {
+    readonly workspaceRoot: string;
+    readonly importingFile: string;
+    readonly moduleSpecifier: string;
+}
+/**
+ * Reads `tsconfig.base.json` and returns the `compilerOptions.paths` map
+ * (canonical bare specifier → absolute path to its `src/index.ts`).
+ *
+ * @param workspaceRoot - Workspace root directory.
+ * @returns Cached map of canonical specifiers to absolute index paths.
+ */
+export declare function loadTsconfigPaths(workspaceRoot: string): Map<string, string>;
+/**
+ * Resolves a module specifier to the source-package that owns it.
+ *
+ * @param input - Workspace root + importing-file location + the specifier.
+ * @returns The {@link PackageRef} of the owning package, or `undefined` when unresolved.
+ */
+export declare function resolveModuleToPackage(input: ResolveModuleInput): PackageRef | undefined;
+/**
+ * Walks up from `startPath` until it finds a directory containing a `package.json`
+ * with a `name` field, then returns its package name + root.
+ *
+ * @param workspaceRoot - Stop walking when this directory is reached.
+ * @param startPath - Path to walk up from.
+ * @returns The package name + root, or `undefined` if no package.json is found.
+ */
+export declare function locatePackageForPath(workspaceRoot: string, startPath: string): PackageRef | undefined;
+/**
+ * Returns the workspace-root-relative path with forward slashes for display.
+ *
+ * @param workspaceRoot - Workspace root directory.
+ * @param absolutePath - Absolute path to make relative.
+ * @returns The workspace-relative path with forward slashes.
+ */
+export declare function relPath(workspaceRoot: string, absolutePath: string): string;
+/**
+ * Type-narrowed `isAbsolute` re-export so the generator scripts only depend on
+ * `node:path` indirectly through this module.
+ *
+ * @param value - Path to test.
+ * @returns `true` when the path is absolute.
+ */
+export declare function isAbsolutePathLike(value: string): boolean;

package/firebase-api-manifest/src/generate-api-manifest/types.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Internal types shared between the generator's pipeline stages.
+ *
+ * The runtime manifest types (`CliApiManifest`, `CliApiManifestEntry`,
+ * `CliApiVerb`) live in `packages/dbx-cli/src/lib/manifest/types.ts` and are
+ * re-exported from `@dereekb/dbx-cli`. The generator emits TypeScript that
+ * imports those runtime types — it does not reference them itself.
+ */
+export interface FunctionsGroup {
+    readonly groupKey: string;
+    readonly className: string;
+    readonly importedFromModule: string;
+}
+export interface PackageRef {
+    readonly packageName: string;
+    readonly packageRoot: string;
+}
+export interface CrudEntry {
+    readonly model: string;
+    readonly verb: string;
+    readonly specifier?: string;
+    readonly paramsTypeName?: string;
+    readonly resultTypeName?: string;
+    readonly line: number;
+}
+export interface CrudExtraction {
+    readonly groupName: string | undefined;
+    readonly modelKeys: readonly string[];
+    readonly entries: readonly CrudEntry[];
+    readonly functionsClassName?: string;
+}
+export interface ApiFileMatch {
+    readonly filePath: string;
+    readonly className: string;
+    readonly extraction: CrudExtraction;
+}
+export interface CollectedEntry {
+    readonly entry: CrudEntry & {
+        readonly groupName: string;
+        readonly sourceFile: string;
+    };
+    readonly packageName?: string;
+    readonly validatorName?: string;
+}

package/index.cjs.default.js

@@ -0,0 +1 @@
+exports._default = require('./index.cjs.js').default;