@luckystack/devkit 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,207 @@
+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 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, DEFAULT_DASHBOARD_PATH_PATTERN, type RegisterTemplateKindOptions, 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, devApis, devFunctions, devSyncs, generateTypeMapFile, getInputTypeFromFile, getRegisteredTemplate, getRoutingRules, getSyncClientDataType, getTemplateRules, initializeAll, initializeApis, initializeFunctions, initializeSyncs, isApiFileName, isSyncClientFileName, isSyncFileName, isSyncServerFileName, listRegisteredTemplateKinds, registerDefaultTemplateRules, registerRoutingRules, registerTemplate, registerTemplateKind, registerTemplateRule, removeApiFromFile, removeSyncFromFile, resolveRuntimeTypeText, resolveTemplateKind, setupWatchers, syncMarkerSegment, upsertApiFromFile, upsertSyncFromFile, validateDeploy };