@luckystack/devkit 0.10.2 → 0.12.0

package/dist/index.d.ts

@@ -1,280 +1,15 @@
-import { ServicesConfigShape, DeployConfigShape } from '@luckystack/core';
-
-interface GenerateTypeMapOptions {
-    quiet?: boolean;
-}
-declare const generateTypeMapFile: (options?: GenerateTypeMapOptions) => void;
-
-declare const getInputTypeFromFile: (filePath: string) => string;
-declare const getSyncClientDataType: (filePath: string) => string;
-
-declare const API_VERSION_TOKEN_REGEX: RegExp;
-declare const SYNC_VERSION_TOKEN_REGEX: RegExp;
-
-declare const assertValidRouteNaming: ({ srcDir, context, }: {
-    srcDir: string;
-    context: string;
-}) => void;
-declare const assertNoDuplicateNormalizedRouteKeys: ({ srcDir, context, }: {
-    srcDir: string;
-    context: string;
-}) => void;
-
-interface FunctionModule {
-    /**
-     * Key path under the injected `functions` object. `shared/rbac/engine.ts`
-     * with root `shared` yields `['rbac', 'engine']`, reachable as
-     * `functions.rbac.engine`.
-     */
-    keyPath: string[];
-    /** Workspace-relative, forward-slash path to the source file (with `.ts`). */
-    sourcePath: string;
-    /** Workspace-relative, forward-slash root directory that claimed this key path. */
-    rootPath: string;
-}
-/** Dotted rendering of a key path, e.g. `rbac.engine`. */
-declare const formatFunctionKeyPath: (keyPath: string[]) => string;
-/**
- * Last segment of a key path — the module's file name, which is also the alias
- * a default-only export is published under (`functions.sleep.sleep`).
- *
- * Discovery never produces an empty key path; the guard exists so the callers
- * get a real string instead of threading `string | undefined` through every
- * emitter.
- */
-declare const functionModuleFileName: (keyPath: string[]) => string;
-declare const formatFunctionKeyConflict: (keyPath: string[], firstSourcePath: string, secondSourcePath: string) => string;
-declare const formatFunctionNamespaceConflict: (moduleKeyPath: string[], moduleSourcePath: string, nestedKeyPath: string[], nestedSourcePath: string) => string;
-interface CollectFunctionModulesOptions {
-    /**
-     * Override the configured roots (absolute paths). Tests pass this;
-     * production callers omit it and get `getServerFunctionDirs()`.
-     */
-    roots?: string[];
-    /**
-     * When provided, a collision REPORTS through this callback and the offending
-     * module is skipped instead of throwing. The dev loader passes it so a
-     * duplicate does not hard-crash a running dev server; the build-time
-     * generators omit it so the same duplicate fails the build loudly.
-     */
-    onConflict?: (message: string) => void;
-}
-/**
- * Discover every server function module across the configured
- * `paths.serverFunctionDirs` roots (default `['functions', 'shared']`), in
- * config order, and derive its `functions.*` key path from its location
- * relative to the root that owns it.
- *
- * Throws on a cross-root key collision or a module/namespace collision (unless
- * `onConflict` is supplied), so a broken registry fails the BUILD instead of
- * producing a map that is silently missing entries at runtime.
- */
-declare const collectFunctionModules: (options?: CollectFunctionModulesOptions) => FunctionModule[];
-interface RenderedFunctionsMap {
-    /** `import * as fn0 from '...'` lines, in emission order. */
-    imports: string[];
-    /** The full `export const functions = { ... };` declaration. */
-    source: string;
-}
-/**
- * Render discovered modules into the `functions` export of a generated
- * production runtime-map file. The emitted object is NESTED, matching what the
- * dev loader builds and what `apiTypes.generated.ts` declares.
- *
- * @param modules      Output of {@link collectFunctionModules}.
- * @param importPrefix Prefix that turns a workspace-relative source path into a
- *                     specifier relative to the generated file (`'../../'` for
- *                     the standard `server/prod/` output location).
- * @param varPrefix    Import alias prefix; aliases are `<varPrefix><n>`.
- */
-declare const renderFunctionsMap: ({ modules, importPrefix, varPrefix, }: {
-    modules: FunctionModule[];
-    importPrefix: string;
-    varPrefix?: string;
-}) => RenderedFunctionsMap;
-
-interface RoutingRules {
-    /** Folder name that marks an API directory. Default: `_api`. */
-    apiMarker: string;
-    /** Folder name that marks a sync directory. Default: `_sync`. */
-    syncMarker: string;
-    /** Suffix matcher for API files: must end with `_v<number>.ts`. */
-    apiVersionRegex: RegExp;
-    /** Suffix matcher for sync server files: must end with `_server_v<number>.ts`. */
-    syncServerVersionRegex: RegExp;
-    /** Suffix matcher for sync client files: must end with `_client_v<number>.ts`. */
-    syncClientVersionRegex: RegExp;
-    /** Combined sync regex (server or client). */
-    syncVersionRegex: RegExp;
-    /**
-     * Predicate called for each candidate file/folder during discovery.
-     * Return `true` to skip. Path is provided as a forward-slash relative
-     * string from the workspace root (e.g. `src/dashboard/__tests__/foo_v1.ts`).
-     */
-    ignore: (relativePath: string) => boolean;
-    /**
-     * Single-character prefix that marks a folder as **invisible-parent** for
-     * page routing: `src/_housing/renting/page.tsx` resolves to `/renting`
-     * (the `_housing` segment is stripped from the URL). A `page.tsx` placed
-     * directly inside an `_<name>` folder is invalid (no URL segment left).
-     *
-     * Default: `'_'`. Override only if you need a different prefix scheme.
-     */
-    privateFolderPrefix: string;
-    /**
-     * Folder names that are reserved for framework-internal use and may NEVER
-     * host a `page.tsx`. Scaffold + page-discovery emit a hard error when a
-     * page is placed inside one. Extend (do not replace) the defaults if you
-     * add your own internal folder convention.
-     *
-     * Defaults: `_api`, `_sync`, `_function(s)`, `_component(s)`, `_provider(s)`,
-     * `_locale(s)`, `_socket(s)`, `_shared`, `_server`. The semantic markers
-     * (`_api`, `_sync`) are also reserved by the API/sync routers.
-     */
-    scaffoldIgnoredFolders: string[];
-    /**
-     * Optional predicate. Return `true` for a given absolute file path to
-     * disable template injection entirely for that file. Useful when a
-     * consumer wants to opt some part of the tree out of the scaffold
-     * (e.g. `/src/migrations/**` lives by hand). The argument is the
-     * absolute path the chokidar watcher provides; the predicate is
-     * called BEFORE the `isInApiFolder` / `isPageFile` checks fire.
-     */
-    disableTemplateInjection?: (filePath: string) => boolean;
-}
-declare const registerRoutingRules: (overrides: Partial<RoutingRules>) => RoutingRules;
-declare const getRoutingRules: () => RoutingRules;
-declare const apiMarkerSegment: () => string;
-declare const syncMarkerSegment: () => string;
-declare const isApiFileName: (fileName: string) => boolean;
-declare const isSyncServerFileName: (fileName: string) => boolean;
-declare const isSyncClientFileName: (fileName: string) => boolean;
-declare const isSyncFileName: (fileName: string) => boolean;
-
-/**
- * The six template kinds the framework ships out of the box. Consumers may
- * register additional kinds (e.g. `page_marketing`) via `registerTemplateKind`.
- */
-type BuiltInTemplateKind = 'api' | 'sync_server' | 'sync_client_paired' | 'sync_client_standalone' | 'page_plain' | 'page_dashboard';
-type TemplateKind = BuiltInTemplateKind | (string & {});
-declare const BUILT_IN_TEMPLATE_KINDS: readonly BuiltInTemplateKind[];
-declare const BUILT_IN_TEMPLATE_FILENAMES: Record<BuiltInTemplateKind, string>;
-/**
- * Structural classification of the file an injection is being computed for.
- * `templateInjector.ts` derives this from the folder + filename conventions
- * (controlled separately via `registerRoutingRules`). Selection rules match
- * against it to choose a template kind.
- */
-interface TemplateMatchContext {
-    /** Absolute path of the file being created. */
-    filePath: string;
-    /** Structural kind derived from the route conventions. */
-    fileKind: 'api' | 'sync_server' | 'sync_client' | 'page';
-    /** For `sync_client`: whether a paired `_server_v<N>.ts` exists on disk. */
-    hasPairedServer: boolean;
-    /** Path relative to `src/` (forward slashes), or `null` if outside src. */
-    srcRelativePath: string | null;
-}
-/** A single template-selection rule. First matching rule (by priority) wins. */
-interface TemplateRule {
-    kind: TemplateKind;
-    match: (ctx: TemplateMatchContext) => boolean;
-    /** Higher runs first. Built-in defaults use 10 (specific) / 0 (catch-all). */
-    priority: number;
-}
-interface RegisterTemplateKindOptions {
-    /** Predicate deciding when this kind is chosen. */
-    match: (ctx: TemplateMatchContext) => boolean;
-    /** Optional inline template body (same as calling `registerTemplate`). */
-    content?: string;
-    /** Higher runs first. Defaults to 100 so consumer kinds beat the built-ins. */
-    priority?: number;
-}
-declare const DEFAULT_DASHBOARD_PATH_PATTERN: RegExp;
-/**
- * Override the template body for a given kind. Subsequent injections emit the
- * supplied content with the standard `{{REL_PATH}}` / `{{PAGE_PATH}}` /
- * `{{SYNC_NAME}}` placeholder substitution. Resolution order in the injector
- * is: consumer file (`.luckystack/templates/<kind>.template.*`) → this
- * override → bundled disk template.
- */
-declare const registerTemplate: (kind: TemplateKind, content: string) => void;
-/** Read the registered content override for a kind, or `null` when none. */
-declare const getRegisteredTemplate: (kind: TemplateKind) => string | null;
-/** Drop every content override. Test-only. */
-declare const clearTemplateOverrides: () => void;
-/** Diagnostic: kinds that currently have a content override. */
-declare const listRegisteredTemplateKinds: () => readonly TemplateKind[];
-/**
- * Register a selection rule. Rules are evaluated by descending `priority`,
- * ties broken by descending registration order (so a later registration —
- * e.g. a consumer overlay — beats an earlier same-priority default).
- */
-declare const registerTemplateRule: (rule: TemplateRule) => void;
-/**
- * Register a brand-new template kind: its selection predicate plus (optionally)
- * its inline content. Equivalent to `registerTemplateRule` + `registerTemplate`
- * in one call. Default priority 100 so custom kinds win over the built-ins.
- */
-declare const registerTemplateKind: (kind: TemplateKind, options: RegisterTemplateKindOptions) => void;
-/** Drop every selection rule (including the built-in defaults). */
-declare const clearTemplateRules: () => void;
-/** Read the active rules in evaluation order (priority desc, then newest first). */
-declare const getTemplateRules: () => readonly TemplateRule[];
-/** Evaluate the active rules against a context; returns the first matching kind. */
-declare const resolveTemplateKind: (ctx: TemplateMatchContext) => TemplateKind | null;
-declare const registerDefaultTemplateRules: () => void;
-
-declare const devApis: Record<string, unknown>;
-declare const devSyncs: Record<string, unknown>;
-declare const devFunctions: Record<string, unknown>;
-declare const initializeAll: () => Promise<void>;
-declare const initializeApis: () => Promise<void>;
-declare const upsertApiFromFile: (filePath: string) => Promise<void>;
-declare const removeApiFromFile: (filePath: string) => void;
-declare const initializeSyncs: () => Promise<void>;
-declare const upsertSyncFromFile: (filePath: string) => Promise<void>;
-declare const removeSyncFromFile: (filePath: string) => void;
-declare const initializeFunctions: () => Promise<void>;
-
-declare const setupWatchers: () => void;
-
-type ResolveResult = {
-    status: 'success';
-    typeText: string;
-} | {
-    status: 'error';
-    message: string;
-};
-declare const clearRuntimeTypeResolverCache: () => void;
-declare const resolveRuntimeTypeText: ({ typeText, filePath, }: {
-    typeText: string;
-    filePath?: string;
-}) => ResolveResult;
-
-type ValidationSeverity = 'error' | 'warning';
-interface ValidationFinding {
-    severity: ValidationSeverity;
-    code: string;
-    message: string;
-    /** Human-readable location pointer (e.g. `services.config.ts > presets.api`). */
-    location?: string;
-}
-interface ValidateDeployInput {
-    services: ServicesConfigShape;
-    deploy: DeployConfigShape;
-    /**
-     * Environment values to consult for `synchronizedEnvKeys` / `urlEnvKey`
-     * presence checks. Defaults to `process.env`. Pass a fixture for tests.
-     */
-    env?: Record<string, string | undefined>;
-}
-interface ValidateDeployResult {
-    ok: boolean;
-    findings: ValidationFinding[];
-    errorCount: number;
-    warningCount: number;
-}
-declare const validateDeploy: ({ services, deploy, env, }: ValidateDeployInput) => ValidateDeployResult;
-
-export { API_VERSION_TOKEN_REGEX, BUILT_IN_TEMPLATE_FILENAMES, BUILT_IN_TEMPLATE_KINDS, type BuiltInTemplateKind, type CollectFunctionModulesOptions, DEFAULT_DASHBOARD_PATH_PATTERN, type FunctionModule, type RegisterTemplateKindOptions, type RenderedFunctionsMap, type RoutingRules, SYNC_VERSION_TOKEN_REGEX, type TemplateKind, type TemplateMatchContext, type TemplateRule, type ValidateDeployInput, type ValidateDeployResult, type ValidationFinding, type ValidationSeverity, apiMarkerSegment, assertNoDuplicateNormalizedRouteKeys, assertValidRouteNaming, clearRuntimeTypeResolverCache, clearTemplateOverrides, clearTemplateRules, collectFunctionModules, devApis, devFunctions, devSyncs, formatFunctionKeyConflict, formatFunctionKeyPath, formatFunctionNamespaceConflict, functionModuleFileName, generateTypeMapFile, getInputTypeFromFile, getRegisteredTemplate, getRoutingRules, getSyncClientDataType, getTemplateRules, initializeAll, initializeApis, initializeFunctions, initializeSyncs, isApiFileName, isSyncClientFileName, isSyncFileName, isSyncServerFileName, listRegisteredTemplateKinds, registerDefaultTemplateRules, registerRoutingRules, registerTemplate, registerTemplateKind, registerTemplateRule, removeApiFromFile, removeSyncFromFile, renderFunctionsMap, resolveRuntimeTypeText, resolveTemplateKind, setupWatchers, syncMarkerSegment, upsertApiFromFile, upsertSyncFromFile, validateDeploy };
+export { generateTypeMapFile } from './typeMapGenerator.js';
+export { getInputTypeFromFile, getSyncClientDataType, } from './typeMap/extractors.js';
+export { API_VERSION_TOKEN_REGEX, SYNC_VERSION_TOKEN_REGEX, } from './routeConventions.js';
+export { assertNoDuplicateNormalizedRouteKeys, assertValidRouteNaming, } from './routeNamingValidation.js';
+export { collectFunctionModules, renderFunctionsMap, formatFunctionKeyPath, functionModuleFileName, formatFunctionKeyConflict, formatFunctionNamespaceConflict, } from './functionRegistry.js';
+export type { FunctionModule, RenderedFunctionsMap, CollectFunctionModulesOptions, } from './functionRegistry.js';
+export { registerRoutingRules, getRoutingRules, apiMarkerSegment, syncMarkerSegment, isApiFileName, isSyncFileName, isSyncServerFileName, isSyncClientFileName, } from './routingRules.js';
+export type { RoutingRules } from './routingRules.js';
+export { registerTemplate, getRegisteredTemplate, clearTemplateOverrides, listRegisteredTemplateKinds, registerTemplateRule, registerTemplateKind, clearTemplateRules, getTemplateRules, resolveTemplateKind, registerDefaultTemplateRules, BUILT_IN_TEMPLATE_KINDS, BUILT_IN_TEMPLATE_FILENAMES, DEFAULT_DASHBOARD_PATH_PATTERN, } from './templateRegistry.js';
+export type { TemplateKind, BuiltInTemplateKind, TemplateRule, TemplateMatchContext, RegisterTemplateKindOptions, } from './templateRegistry.js';
+export { devApis, devSyncs, devFunctions, initializeAll, initializeApis, initializeSyncs, initializeFunctions, upsertApiFromFile, removeApiFromFile, upsertSyncFromFile, removeSyncFromFile, } from './loader.js';
+export { setupWatchers } from './hotReload.js';
+export { resolveRuntimeTypeText, clearRuntimeTypeResolverCache } from './runtimeTypeResolver.js';
+export { validateDeploy } from './validateDeploy.js';
+export type { ValidateDeployInput, ValidateDeployResult, ValidationFinding, ValidationSeverity, } from './validateDeploy.js';