@reliverse/dler 1.7.15 → 1.7.17

package/README.md

@@ -15,7 +15,7 @@
 - 🎯 optimized for speed and modern workflows
 - ✨ packed with powerful features under the hood
 - 🛠️ converts typescript aliases to relative paths
-- 🔌 16 built-in helper [dler commands](#-commands) included
+- 🔌 18 built-in helper [dler commands](#-commands) included
 - 📝 highly configurable flow via a configuration file
 - 🔜 `libraries` plugin —> dler monorepo implementation
 - 🧼 cleans up your internal logs from the build dist
@@ -119,7 +119,7 @@ bun dev # bun src/cli.ts --dev
 
 ## 🔌 commands
 
-dler ships with a flexible command system (prev. plugins) and **16 built-in commands** (from [reliverse addons](https://reliverse.org/addons) collection).
+dler ships with a flexible command system (prev. plugins) and **18 built-in commands** (from [reliverse addons](https://reliverse.org/addons) collection).
 
 feel free to create your own commands. commands can be implemented as built-in directly in `src/app/<command>/impl/*` and then imported from `src/app/<command>/cmd.ts`; or implemented in your own library and then imported from `src/app/<command>/cmd.ts`.
 
@@ -127,7 +127,7 @@ if you run just `dler` — it will display a list of commands which you can laun
 
 ## **available commands**
 
-[agg](#1-agg) [build](#2-build) [check](#3-check) [conv](#4-conv) [copy](#5-copy) [init](#6-init) [inject](#7-inject) [libs](#8-libs) [merge](#9-merge) [mock](#10-mock) [migrate](#11-migrate) [pub](#12-pub) [rempts](#13-rempts) [rename](#14-rename) [spell](#15-spell) [split](#16-split)
+[agg](#1-agg) [build](#2-build) [check](#3-check) [conv](#4-conv) [copy](#6-copy) [init](#7-init) [inject](#8-inject) [libs](#9-libs) [merge](#10-merge) [migrate](#11-migrate) [pub](#12-pub) [rempts](#13-rempts) [rename](#14-rename) [spell](#15-spell) [split](#16-split) [pack](#17-pack) [unpack](#18-unpack)
 
 ### 1. `agg`
 
@@ -284,7 +284,7 @@ deep imports like `dep/some/file` or `@org/dep/some/thing` are always resolved t
 - **Dev-only Dependencies**: Packages that are only in `devDependencies` but imported in production code
 - **Duplicate Dependencies**: Packages listed in both `dependencies` and `devDependencies`
 
-### 5. `copy`
+### 6. `copy`
 
 ```bash
 # simple example:
@@ -294,15 +294,15 @@ bun dler copy --s "src/**/*.ts" --d "dist"
 bun dler copy --s ".temp/packages/*/lib/**/*" --d "src/libs/sdk/sdk-impl/rules/external"
 ```
 
-### 6. `init`
+### 7. `init`
 
 not yet documented.
 
-### 7. `inject`
+### 8. `inject`
 
 not yet documented.
 
-### 8. `libs`
+### 9. `libs`
 
 builds and publishes specific subdirectories of your main project as standalone packages.
 
@@ -338,7 +338,7 @@ libslist: {
 
 - more magic commands coming soon...
 
-### 9. `merge`
+### 10. `merge`
 
 merges multiple files into a single file. The command is built for both CI and interactive use, with support for glob patterns and advanced options.
 
@@ -349,13 +349,15 @@ merges multiple files into a single file. The command is built for both CI and i
 - supports both glob patterns and simple paths
 - preserves directory structure when merging to a directory
 - generates source maps for merged output
-- creates and updates templates for mock project structures
 - handles file deduplication
 - supports custom separators and comment styles
 - provides interactive mode with prompts
 - includes backup functionality
 - validates file permissions and sizes
 - enforces output path conflict detection
+- handles both single file and directory output modes
+- implements interactive prompts via `@reliverse/rempts`
+- provides reporting with logging via `@reliverse/relinka`
 
 **usage examples:**
 
@@ -365,13 +367,35 @@ bun dler merge --s "src/**/*.ts" --d "dist/merged.ts"
 
 # advanced example:
 bun dler merge --s ".temp1/packages/*/lib/**/*" --d ".temp2/merged.ts" --sort "mtime" --header "// Header" --footer "// Footer" --dedupe
+```
 
-# generate mock template:
-bun dler merge --s "src/templates" --d "templates/my-template.ts" --as-template
+**arguments:**
 
-# update mock template:
-bun dler merge --s "src/templates" --d "templates/my-template.ts" --as-template --update-template REACT_DLER_TEMPLATE
-```
+- `--s`: Input glob patterns (array)
+- `--d`: Output file path or directory
+- `--ignore`: Extra ignore patterns (array)
+- `--format`: Fallback extension when output path is omitted (default: "txt")
+- `--stdout`: Print to stdout
+- `--noPath`: Don't inject relative path below each file
+- `--pathAbove`: Print file path above each file's content (default: true)
+- `--separator`: Custom separator (default: "\n\n")
+- `--comment`: Custom comment prefix (e.g. '# ')
+- `--forceComment`: Force custom comment prefix for all file types
+- `--batch`: Disable interactive prompts (CI/non-interactive mode)
+- `--recursive`: Recursively process all files in subdirectories (default: true)
+- `--preserveStructure`: Preserve source directory structure in output (default: true)
+- `--increment`: Attach an incrementing index to each output filename
+- `--concurrency`: Number of concurrent file operations (default: 8)
+- `--sort`: Sort files by: name, path, mtime, none (default: path)
+- `--dryRun`: Show what would be done, but don't write files
+- `--backup`: Backup output files before overwriting
+- `--dedupe`: Remove duplicate file contents in merge
+- `--header`: Header text to add at the start of merged output
+- `--footer`: Footer text to add at the end of merged output
+- `--select-files`: Prompt for file selection before merging
+- `--interactive`: Enable interactive mode with prompts
+- `--depth`: Depth level to start processing from (default: 0)
+- `--sourcemap`: Generate source map for the merged output
 
 **implementation details:**
 
@@ -380,182 +404,10 @@ bun dler merge --s "src/templates" --d "templates/my-template.ts" --as-template
 - implements concurrent file operations with `p-map`
 - provides file type detection and appropriate comment styles
 - includes safety checks for file sizes and permissions
-- supports template generation with TypeScript type definitions
 - handles both single file and directory output modes
 - implements interactive prompts via `@reliverse/rempts`
 - provides reporting with logging via `@reliverse/relinka`
 
-### 10. `mock`
-
-bootstraps file structure based on the specified mock template. The command is designed to create project structures from predefined or custom templates, with built-in safety checks and cleanup capabilities.
-
-**key features:**
-
-- creates project structures from predefined templates (basic, api, react)
-- supports custom template files
-- handles path conflicts with force option
-- provides cleanup functionality
-- includes dry run mode for previewing changes
-- validates file types and content
-- enforces rate limiting for file operations
-- supports custom whitelabel prefixes
-- preserves directory structure
-- handles both text and binary files
-
-**usage examples:**
-
-```bash
-# use default react template:
-bun dler mock --template react
-
-# use custom template file:
-bun dler mock --template-file templates/my-template.ts
-
-# preview changes without applying:
-bun dler mock --template react --dry-run
-
-# clean up existing mock structure:
-bun dler mock --template react --cleanup
-```
-
-**integration with merge command:**
-The mock command works seamlessly with the merge command to create and update templates:
-
-1. **create template from existing files:**
-
-   ```bash
-   # create a template from your project structure
-   bun dler merge --s "src/templates" --d "templates/my-template.ts" --as-template
-   ```
-
-2. **use the template with mock:**
-
-   ```bash
-   # use the generated template
-   bun dler mock --template-file templates/my-template.ts
-   ```
-
-3. **update existing template:**
-
-   ```bash
-   # update a specific template in the file
-   bun dler merge --s "src/templates" --d "templates/my-template.ts" --update-template REACT_DLER_TEMPLATE
-   ```
-
-**implementation details:**
-
-- uses `jiti` for dynamic template file loading
-- implements template validation and type checking
-- provides detailed error handling and reporting
-- supports multiple template constants in a single file
-- handles file system operations safely with permissions checks
-- includes cleanup of empty directories
-- provides verbose logging option
-- enforces output path conflict detection
-
-**programmatic usage:**
-Both merge and mock commands can be used programmatically through the `@reliverse/dler-sdk` package:
-
-```typescript
-import { merge, mock } from "@reliverse/dler-sdk";
-
-// Merge files programmatically
-await merge({
-  source: ["src/**/*.ts"],
-  destination: "dist/merged.ts",
-  options: {
-    sort: "mtime",
-    header: "// Header",
-    footer: "// Footer",
-    dedupe: true,
-    sourcemap: true
-  }
-});
-
-// Create mock structure programmatically
-await mock({
-  template: "react",
-  options: {
-    templateFile: "templates/my-template.ts",
-    cleanup: false,
-    dryRun: false,
-    verbose: true,
-    whitelabel: "MYAPP",
-    force: true
-  }
-});
-
-// Create and use custom template
-const template = await merge({
-  source: ["src/templates"],
-  destination: "templates/my-template.ts",
-  options: {
-    asTemplate: true,
-    whitelabel: "MYAPP"
-  }
-});
-
-await mock({
-  template: "custom",
-  options: {
-    templateFile: "templates/my-template.ts"
-  }
-});
-```
-
-**sdk types:**
-
-```typescript
-// Merge command options
-interface MergeOptions {
-  source: string[];
-  destination?: string;
-  options?: {
-    ignore?: string[];
-    format?: string;
-    stdout?: boolean;
-    noPath?: boolean;
-    pathAbove?: boolean;
-    separator?: string;
-    comment?: string;
-    forceComment?: boolean;
-    batch?: boolean;
-    recursive?: boolean;
-    preserveStructure?: boolean;
-    increment?: boolean;
-    concurrency?: number;
-    sort?: "name" | "path" | "mtime" | "none";
-    dryRun?: boolean;
-    backup?: boolean;
-    dedupe?: boolean;
-    header?: string;
-    footer?: string;
-    selectFiles?: boolean;
-    interactive?: boolean;
-    asTemplate?: boolean;
-    ctn?: string;
-    whitelabel?: string;
-    sourcemap?: boolean;
-    updateTemplate?: string;
-    dev?: boolean;
-  };
-}
-
-// Mock command options
-interface MockOptions {
-  template: string;
-  options?: {
-    templateFile?: string;
-    templateConsts?: string;
-    cleanup?: boolean;
-    dryRun?: boolean;
-    verbose?: boolean;
-    whitelabel?: string;
-    force?: boolean;
-  };
-}
-```
-
 ### 11. `migrate`
 
 helps migrate between different libraries and module resolution strategies. currently supports:
@@ -655,7 +507,7 @@ dler migrate --lib nodenext-bundler --target nodenext --dryRun
 - handles both relative and alias imports
 - supports both .ts and .tsx files
 
-#### `console-relinka`
+**`console-relinka`**:
 
 [@reliverse/relinka](https://github.com/reliverse/relinka)'s best friend. Converts between different logging formats (console, consola method/object, and relinka's function/method/object styles).
 
@@ -677,7 +529,7 @@ dler relinka --input src/app.ts --from relinkaMethod --to relinkaObject
 dler relinka --input src/app.ts --from relinkaFunction --to consolaObject
 ```
 
-**Supported formats:**
+**Supported formats**:
 
 - `console`: Standard console logging (`console.log(message, ...args)`)
 - `consolaMethod`: Consola method style (`consola.log(message, ...args)`)
@@ -686,7 +538,7 @@ dler relinka --input src/app.ts --from relinkaFunction --to consolaObject
 - `relinkaMethod`: Relinka method style (`relinka.level(message, ...args)`)
 - `relinkaObject`: Relinka object style (`relinka({ level, message, title?, args? })`)
 
-**Special features:**
+**Special features**:
 
 - Preserves additional arguments in all formats
 - Handles special box format with title and message
@@ -694,7 +546,7 @@ dler relinka --input src/app.ts --from relinkaFunction --to consolaObject
 - Supports conversion between any combination of formats
 - Supports both consola method and object styles
 
-#### next steps after migration
+**next steps after migration**:
 
 - for path-pathkit:
   1. run 'bun install' to install @reliverse/pathkit
@@ -751,6 +603,8 @@ bun dler rename ...
 
 ### 15. `spell`
 
+> Contributors: Please check the [docs/cmds/SPELLS.md](./docs/cmds/SPELLS.md) file for more technical details.
+
 **available spell types:**
 
 - `replace-line` — injects contents from one file into another
@@ -826,7 +680,118 @@ splits your code/text file into multiple files.
 bun dler split ...
 ```
 
-## api (for advanced users)
+### 17. `pack`
+
+packs a directory of templates into TypeScript modules. This command is useful for creating reusable template packages that can be distributed and used by other projects.
+
+**key features:**
+
+- Converts directory structure into TypeScript modules
+- Handles binary files with automatic hashing and storage
+- Preserves JSON comments and formatting
+- Supports custom whitelabeling
+- Generates type-safe template definitions
+- Creates an aggregator module for easy imports
+- Tracks file metadata (update time and content hash)
+- Supports selective file updates
+- Handles file conflicts gracefully
+- Preserves JSON type information for package.json and tsconfig.json
+
+**usage examples:**
+
+```bash
+# Basic usage
+dler pack --dir ./templates --output ./dist-templates
+
+# With custom whitelabel
+dler pack --dir ./templates --output ./dist-templates --whitelabel MYAPP
+
+# Update specific files only
+dler pack --dir ./templates --output ./dist-templates --files "src/index.ts,src/config.ts"
+
+# Force overwrite existing files
+dler pack --dir ./templates --output ./dist-templates --force
+
+# Update mode (default: true)
+dler pack --dir ./templates --output ./dist-templates --update
+```
+
+**arguments:**
+
+- `--dir`: Directory containing templates to process (required)
+- `--output`: Output directory for generated modules (default: "my-templates")
+- `--whitelabel`: Custom prefix to use instead of 'DLER' (default: "DLER")
+- `--cdn`: Remote CDN for binary assets upload (not yet implemented)
+- `--force`: Force overwrite existing files (default: false)
+- `--update`: Update existing templates and add new ones (default: true)
+- `--files`: Comma-separated list of specific files to update
+- `--lastUpdate`: Override lastUpdate timestamp
+
+**output structure:**
+
+```bash
+output/
+├── impl/
+│   ├── binaries/ # binary files stored with hash-based names (dler reads/writes this dir when --cdn is not used)
+│   │   └── [hashed-files]
+│   ├── template1.ts
+│   └── template2.ts
+├── types.ts
+└── mod.ts
+```
+
+### 18. `unpack`
+
+creates file structure from packed templates. This command is the counterpart to `pack` and is used to extract and restore template files from a packed template package.
+
+**key features:**
+
+- Restores complete directory structure from packed templates
+- Handles binary files with automatic lookup
+- Preserves JSON comments and formatting
+- Supports custom output locations
+- Maintains file permissions and structure
+- Validates template integrity
+- Supports cleanup of existing template files
+- Provides dry-run mode for previewing changes
+- Handles empty directory cleanup
+
+**usage examples:**
+
+```bash
+# Basic usage
+dler unpack ./dist-templates --output ./my-project
+
+# With custom output directory
+dler unpack ./dist-templates --output ./custom-location
+
+# Preview changes without applying
+dler unpack ./dist-templates --output ./my-project --dry-run
+
+# Clean up existing template files before unpacking
+dler unpack ./dist-templates --output ./my-project --cleanup
+```
+
+**arguments:**
+
+- `templatesDir`: Directory containing mod.ts (required)
+- `--output`: Where to write files (default: "unpacked")
+- `--cdn`: Remote CDN base for binary assets download (not yet implemented)
+- `--cleanup`: Clean up template files before unpacking (default: false)
+- `--dry-run`: Preview changes without applying them (default: false)
+
+**implementation details:**
+
+- Uses `jiti` for dynamic template file loading
+- Implements template validation and type checking
+- Provides detailed error handling and reporting
+- Handles file system operations safely
+- Preserves JSON comments and formatting
+- Supports binary file restoration
+- Cleans up empty directories after unpacking
+- Validates template structure before unpacking
+
+## api (for advanced usage)
 
 the sdk lets you build custom dler cli plugins or even extend your own cli tools.
 
@@ -853,6 +818,14 @@ special thanks to the project that inspired `@reliverse/dler`:
 
 - [unjs/unbuild](https://github.com/unjs/unbuild#readme)
 
+## contributors
+
+### scripts
+
+- `libs:pack`: Creates two templates, `cfg` and `sdk`, based on dist-libs directory structure (using **dler pack** command).
+- `libs:unpack`: Creates a project structure using all templates from the `cfg` and `sdk` templates (using **dler unpack** command).
+- `libs:example`: Since `libs:unpack`'s serves as a dist-libs mock, then `libs:example` helps easily test dler's features like `resolveAllCrossLibs()`.
+
 ## support
 
 - if dler saves you time and effort, please consider supporting its development: [github sponsors](https://github.com/sponsors/blefnk);

package/bin/app/agg/run.js

@@ -1,14 +1,8 @@
 import { selectPrompt, runCmd, confirmPrompt, inputPrompt } from "@reliverse/rempts";
-import { existsSync } from "node:fs";
-import { resolve } from "node:path";
 import { getAggCmd } from "../cmds.js";
-async function loadConfig() {
-  const configPath = resolve(".config/dler.ts");
-  if (!existsSync(configPath)) return null;
-  return (await import(configPath)).default;
-}
+import { getConfigDler } from "../../libs/sdk/sdk-impl/config/load.js";
 export async function promptAggCommand() {
-  const config = await loadConfig();
+  const config = await getConfigDler();
   let selectedLibName = null;
   if (config?.libsList && Object.keys(config.libsList).length > 0) {
     const libs = Object.entries(config.libsList).map(([name, lib]) => ({

package/bin/app/build/cmd.js

@@ -1,7 +1,7 @@
 import { defineArgs, defineCommand } from "@reliverse/rempts";
-import { dlerPub } from "./impl.js";
-import { ensureDlerConfig } from "../../libs/sdk/sdk-impl/cfg/init.js";
-import { loadConfig } from "../../libs/sdk/sdk-impl/cfg/load.js";
+import { dlerPub } from "../pub/impl.js";
+import { ensureDlerConfig } from "../../libs/sdk/sdk-impl/config/init.js";
+import { getConfigDler } from "../../libs/sdk/sdk-impl/config/load.js";
 import { removeDistFolders } from "../../libs/sdk/sdk-mod.js";
 export default defineCommand({
   meta: {
@@ -16,7 +16,7 @@ export default defineCommand({
   }),
   async run({ args }) {
     await ensureDlerConfig(args.dev);
-    const config = await loadConfig();
+    const config = await getConfigDler();
     await removeDistFolders(
       config.distNpmDirName,
       config.distJsrDirName,

package/bin/app/build/impl.d.ts

@@ -1,11 +1,7 @@
-import type { DlerConfig } from "../../libs/sdk/sdk-types.js";
+import type { DlerConfig } from "../../libs/sdk/sdk-impl/config/types.js";
 /**
  * Main entry point for the dler build and publish process.
  * Handles building and publishing for both main project and libraries.
+ * @see `src/app/pub/impl.ts` for pub main function implementation.
  */
 export declare function dlerBuild(isDev: boolean, config?: DlerConfig): Promise<void>;
-/**
- * Main entry point for the dler build and publish process.
- * Handles building and publishing for both main project and libraries.
- */
-export declare function dlerPub(isDev: boolean, config?: DlerConfig): Promise<void>;

package/bin/app/build/impl.js

@@ -1,7 +1,7 @@
 import { bumpHandler, isBumpDisabled, setBumpDisabledValueTo } from "@reliverse/bleump";
 import path from "@reliverse/pathkit";
 import fs from "@reliverse/relifso";
-import { loadConfig } from "../../libs/sdk/sdk-impl/cfg/load.js";
+import { getConfigDler } from "../../libs/sdk/sdk-impl/config/load.js";
 import { processLibraryFlow } from "../../libs/sdk/sdk-impl/library-flow.js";
 import { processRegularFlow } from "../../libs/sdk/sdk-impl/regular-flow.js";
 import { finalizeBuildPub } from "../../libs/sdk/sdk-impl/utils/finalize.js";
@@ -14,7 +14,7 @@ export async function dlerBuild(isDev, config) {
   let effectiveConfig = config;
   try {
     if (!effectiveConfig) {
-      effectiveConfig = await loadConfig();
+      effectiveConfig = await getConfigDler();
     }
     if (effectiveConfig.logsFreshFile) {
       await fs.remove(path.join(PROJECT_ROOT, effectiveConfig.logsFileName));
@@ -53,47 +53,3 @@ export async function dlerBuild(isDev, config) {
     handleDlerError(error);
   }
 }
-export async function dlerPub(isDev, config) {
-  const timer = createPerfTimer();
-  let effectiveConfig = config;
-  try {
-    if (!effectiveConfig) {
-      effectiveConfig = await loadConfig();
-    }
-    if (effectiveConfig.logsFreshFile) {
-      await fs.remove(path.join(PROJECT_ROOT, effectiveConfig.logsFileName));
-    }
-    await removeDistFolders(
-      effectiveConfig.distNpmDirName,
-      effectiveConfig.distJsrDirName,
-      effectiveConfig.libsDirDist,
-      effectiveConfig.libsList
-    );
-    const bumpIsDisabled = await isBumpDisabled();
-    if (!bumpIsDisabled && !effectiveConfig.commonPubPause) {
-      try {
-        await bumpHandler(
-          effectiveConfig.bumpMode,
-          false,
-          effectiveConfig.bumpFilter,
-          effectiveConfig.bumpSet
-        );
-        await setBumpDisabledValueTo(true);
-      } catch {
-        throw new Error("[.config/dler.ts] Failed to set bumpDisable to true");
-      }
-    }
-    await processRegularFlow(timer, isDev, effectiveConfig);
-    await processLibraryFlow(timer, isDev, effectiveConfig);
-    await finalizeBuildPub(
-      timer,
-      effectiveConfig.commonPubPause,
-      effectiveConfig.libsList,
-      effectiveConfig.distNpmDirName,
-      effectiveConfig.distJsrDirName,
-      effectiveConfig.libsDirDist
-    );
-  } catch (error) {
-    handleDlerError(error);
-  }
-}

package/bin/app/conv/cmd.d.ts

@@ -1,33 +1,8 @@
-declare const _default: import("@reliverse/rempts").Command<{
-    type: {
-        type: "string";
-        required: true;
-        description: string;
-    };
-    input: {
-        type: "string";
-        required: true;
-        description: string;
-    };
-    output: {
-        type: "string";
-        description: string;
-    };
-    pattern: {
-        type: "string";
-        description: string;
-    };
-    replacement: {
-        type: "string";
-        description: string;
-    };
-    line: {
-        type: "number";
-        description: string;
-    };
-    transform: {
-        type: "string";
-        description: string;
-    };
-}>;
-export default _default;
+/**
+ * Recursively inlines (or rewrites) aliased import / re-export statements for all libraries.
+ *
+ * @param alias     Prefix used in module specifiers (default: "~")
+ * @param subFolders Ordered sub-folder candidates to look for when chasing other libs
+ * @returns Absolute paths of files that were modified
+ */
+export declare function resolveCrossLibs(alias?: string, subFolders?: ("npm" | "jsr")[]): Promise<string[]>;