harbor-templater 1.3.0 → 1.4.0

package/README.md

@@ -27,7 +27,7 @@ $ npm install -g harbor-templater
 $ harbor-templater COMMAND
 running command...
 $ harbor-templater (--version)
-harbor-templater/1.3.0 linux-x64 node-v24.12.0
+harbor-templater/1.4.0 linux-x64 node-v24.13.0
 $ harbor-templater --help [COMMAND]
 USAGE
   $ harbor-templater COMMAND
@@ -100,7 +100,7 @@ EXAMPLES
   $ harbor-templater init -t template.json -o . --answer projectDir=./my-app --defaults
 ```
 
-_See code: [src/commands/init/index.ts](https://github.com/bendigiorgio/harbor-templater/blob/v1.3.0/src/commands/init/index.ts)_
+_See code: [src/commands/init/index.ts](https://github.com/bendigiorgio/harbor-templater/blob/v1.4.0/src/commands/init/index.ts)_
 
 ## `harbor-templater plugins`
 

package/dist/commands/init/index.js

@@ -4,8 +4,9 @@ import { checkbox, confirm, input, select } from "@inquirer/prompts";
 import { Command, Flags } from "@oclif/core";
 import picomatch from "picomatch";
 import { runShellCommand } from "../../lib/commands.js";
+import { applyRenameToBasename, copyDirWithTransforms, copyFileMaybeRender, } from "../../lib/copy-transform.js";
 import { applyEnvironmentReplacements } from "../../lib/environment.js";
-import { copyPath, ensureDir, looksLikeDirTarget, pathExists, } from "../../lib/fs-ops.js";
+import { ensureDir, looksLikeDirTarget, pathExists } from "../../lib/fs-ops.js";
 import { mergeIntoTarget } from "../../lib/merge.js";
 import { resolveSource } from "../../lib/sources.js";
 import { buildInitialContext, evaluateCondition, interpolate, resolveTargetPath, templateQuestions, templateSteps, } from "../../lib/template-engine.js";
@@ -170,56 +171,84 @@ async function executeSteps(args) {
                 }
                 const policy = effectiveConflictPolicy(args);
                 if (src.kind === "dir") {
-                    const shouldProceed = await handleDirConflict({
+                    const decision = await handleDirConflict({
                         policy,
-                        source: step.source,
                         target,
                         defaults: args.defaults,
                     });
-                    if (!shouldProceed) {
+                    if (!decision.proceed) {
                         args.log(`skip copy ${step.source} -> ${target} (exists)`);
                         break;
                     }
-                    const excludeMatcher = step.exclude?.length
-                        ? picomatch(step.exclude, { dot: true })
-                        : null;
-                    await fs.cp(src.path, target, {
-                        recursive: true,
-                        force: policy === "overwrite" || args.force,
-                        filter: excludeMatcher
-                            ? (srcEntry) => {
-                                const rel = path
-                                    .relative(src.path, srcEntry)
-                                    .replaceAll("\\", "/");
-                                // keep root
-                                if (!rel)
-                                    return true;
-                                return !excludeMatcher(rel);
-                            }
-                            : undefined,
+                    const force = policy === "overwrite" || args.force || Boolean(decision.overwrite);
+                    await copyDirWithTransforms(src.path, target, {
+                        ctx: args.ctx,
+                        force,
+                        include: step.include,
+                        exclude: step.exclude,
+                        rename: step.rename,
+                        render: step.render,
                     });
                 }
                 else {
                     // If target ends with '/', treat it as directory and keep filename
                     const finalTarget = looksLikeDirTarget(step.target)
-                        ? path.join(target, path.basename(src.path))
+                        ? path.join(target, applyRenameToBasename(path.basename(src.path), step.rename, args.ctx))
                         : target;
-                    const shouldProceed = await handleFileConflict({
+                    const decision = await handleFileConflict({
                         policy,
-                        source: step.source,
                         target: finalTarget,
                         defaults: args.defaults,
                     });
-                    if (!shouldProceed) {
+                    if (!decision.proceed) {
                         args.log(`skip copy ${step.source} -> ${finalTarget} (exists)`);
                         break;
                     }
-                    await copyPath(src.path, finalTarget, {
-                        force: policy === "overwrite" || args.force,
+                    const force = policy === "overwrite" || args.force || Boolean(decision.overwrite);
+                    const shouldRender = Boolean(step.render &&
+                        (() => {
+                            const rel = path.basename(src.path).replaceAll("\\", "/");
+                            const include = picomatch(step.render.include, { dot: true });
+                            const exclude = step.render.exclude?.length
+                                ? picomatch(step.render.exclude, { dot: true })
+                                : null;
+                            return include(rel) && !exclude?.(rel);
+                        })());
+                    await copyFileMaybeRender(src.path, finalTarget, {
+                        ctx: args.ctx,
+                        force,
+                        render: shouldRender,
                     });
                 }
                 break;
             }
+            case "move": {
+                const from = resolveTargetPath(args.ctx.outDir, interpolate(step.from, args.ctx));
+                const to = resolveTargetPath(args.ctx.outDir, interpolate(step.to, args.ctx));
+                if (args.dryRun) {
+                    args.log(`move ${from} -> ${to}`);
+                    break;
+                }
+                if (!(await pathExists(from))) {
+                    throw new Error(`Move source does not exist: ${from}`);
+                }
+                const policy = effectiveConflictPolicy(args);
+                const decision = await handleFileConflict({
+                    policy,
+                    target: to,
+                    defaults: args.defaults,
+                });
+                if (!decision.proceed) {
+                    args.log(`skip move ${from} -> ${to} (exists)`);
+                    break;
+                }
+                if (decision.overwrite && (await pathExists(to))) {
+                    await fs.rm(to, { recursive: true, force: true });
+                }
+                await ensureDir(path.dirname(to));
+                await movePath(from, to);
+                break;
+            }
             case "merge": {
                 const target = resolveTargetPath(args.ctx.outDir, interpolate(step.target, args.ctx));
                 const src = await resolveSource(interpolate(step.source, args.ctx));
@@ -258,6 +287,26 @@ async function executeSteps(args) {
         }
     }
 }
+async function movePath(from, to) {
+    try {
+        await fs.rename(from, to);
+        return;
+    }
+    catch (error) {
+        const code = error?.code;
+        if (code !== "EXDEV")
+            throw error;
+    }
+    // Cross-device fallback.
+    const stat = await fs.stat(from);
+    if (stat.isDirectory()) {
+        await fs.cp(from, to, { recursive: true, force: true });
+        await fs.rm(from, { recursive: true, force: true });
+        return;
+    }
+    await fs.copyFile(from, to);
+    await fs.rm(from, { force: true });
+}
 function effectiveConflictPolicy(args) {
     // If user asked for no prompting, don't prompt on conflicts.
     if (args.defaults && args.conflict === "prompt")
@@ -267,36 +316,40 @@ function effectiveConflictPolicy(args) {
 async function handleFileConflict(args) {
     const exists = await pathExists(args.target);
     if (!exists)
-        return true;
+        return { proceed: true, overwrite: false };
     switch (args.policy) {
         case "overwrite":
-            return true;
+            return { proceed: true, overwrite: true };
         case "skip":
-            return false;
+            return { proceed: false, overwrite: false };
         case "error":
             throw new Error(`Target exists: ${args.target}`);
         case "prompt":
-            return await confirm({
+            return (await confirm({
                 message: `Overwrite ${args.target}?`,
                 default: false,
-            });
+            }))
+                ? { proceed: true, overwrite: true }
+                : { proceed: false, overwrite: false };
     }
 }
 async function handleDirConflict(args) {
     const exists = await pathExists(args.target);
     if (!exists)
-        return true;
+        return { proceed: true, overwrite: false };
     switch (args.policy) {
         case "overwrite":
-            return true;
+            return { proceed: true, overwrite: true };
         case "skip":
-            return false;
+            return { proceed: false, overwrite: false };
         case "error":
             throw new Error(`Target exists: ${args.target}`);
         case "prompt":
-            return await confirm({
+            return (await confirm({
                 message: `Directory exists. Merge/overwrite into ${args.target}?`,
                 default: false,
-            });
+            }))
+                ? { proceed: true, overwrite: true }
+                : { proceed: false, overwrite: false };
     }
 }

package/dist/lib/copy-transform.d.ts

@@ -0,0 +1,20 @@
+import type { TemplateContext } from "./template-engine.js";
+export type RenderOptions = {
+    include: string[];
+    exclude?: string[];
+};
+export type CopyTransformOptions = {
+    ctx: TemplateContext;
+    force: boolean;
+    include?: string[];
+    exclude?: string[];
+    rename?: Record<string, string>;
+    render?: RenderOptions;
+};
+export declare function copyDirWithTransforms(sourceDir: string, targetDir: string, options: CopyTransformOptions): Promise<void>;
+export declare function copyFileMaybeRender(sourceFile: string, targetFile: string, options: {
+    ctx: TemplateContext;
+    force: boolean;
+    render: boolean;
+}): Promise<void>;
+export declare function applyRenameToBasename(basename: string, rename: Record<string, string> | undefined, ctx: TemplateContext): string;

package/dist/lib/copy-transform.js

@@ -0,0 +1,134 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import picomatch from "picomatch";
+import { ensureDir } from "./fs-ops.js";
+import { interpolate } from "./template-engine.js";
+export async function copyDirWithTransforms(sourceDir, targetDir, options) {
+    const includeMatcher = options.include?.length
+        ? picomatch(options.include, { dot: true })
+        : null;
+    const excludeMatcher = options.exclude?.length
+        ? picomatch(options.exclude, { dot: true })
+        : null;
+    const renderMatcher = options.render
+        ? {
+            include: picomatch(options.render.include, { dot: true }),
+            exclude: options.render.exclude?.length
+                ? picomatch(options.render.exclude, { dot: true })
+                : null,
+        }
+        : null;
+    const renamePairs = normalizeRename(options.rename, options.ctx);
+    async function walk(currentSourceDir) {
+        const entries = await fs.readdir(currentSourceDir, { withFileTypes: true });
+        for (const entry of entries) {
+            const srcPath = path.join(currentSourceDir, entry.name);
+            const relNative = path.relative(sourceDir, srcPath);
+            const rel = relNative.replaceAll(path.sep, "/");
+            // Exclude directories early to avoid traversing large trees.
+            if (entry.isDirectory() && excludeMatcher && excludeMatcher(`${rel}/x`)) {
+                continue;
+            }
+            if (entry.isDirectory()) {
+                await walk(srcPath);
+                continue;
+            }
+            if (entry.isFile()) {
+                if (excludeMatcher?.(rel))
+                    continue;
+                if (includeMatcher && !includeMatcher(rel))
+                    continue;
+                const renamedRel = validateRelativePath(applyRename(rel, renamePairs));
+                const dstPath = path.join(targetDir, ...renamedRel.split("/"));
+                const shouldRender = Boolean(renderMatcher?.include(rel) && !renderMatcher.exclude?.(rel));
+                await copyFileMaybeRender(srcPath, dstPath, {
+                    ctx: options.ctx,
+                    force: options.force,
+                    render: Boolean(shouldRender),
+                });
+                continue;
+            }
+            // For now, ignore other filesystem entry types (symlinks, sockets, etc)
+            throw new Error(`Unsupported entry type in template source: ${srcPath}`);
+        }
+    }
+    await walk(sourceDir);
+}
+export async function copyFileMaybeRender(sourceFile, targetFile, options) {
+    await ensureDir(path.dirname(targetFile));
+    if (!options.force) {
+        // Match old behavior: fail if target exists.
+        await fs.access(targetFile).then(() => {
+            throw new Error(`Target exists: ${targetFile}`);
+        }, () => undefined);
+    }
+    if (!options.render) {
+        await fs.copyFile(sourceFile, targetFile);
+        return;
+    }
+    const buffer = Buffer.from(await fs.readFile(sourceFile));
+    const text = decodeUtf8TextOrNull(buffer);
+    if (text == null) {
+        // Binary-safe behavior: copy bytes unchanged.
+        await fs.writeFile(targetFile, buffer);
+        return;
+    }
+    const rendered = interpolate(text, options.ctx);
+    await fs.writeFile(targetFile, rendered, "utf8");
+}
+function decodeUtf8TextOrNull(buffer) {
+    // Cheap binary heuristic: NUL bytes are extremely uncommon in text files.
+    if (buffer.includes(0))
+        return null;
+    try {
+        const decoder = new TextDecoder("utf-8", { fatal: true });
+        return decoder.decode(buffer);
+    }
+    catch {
+        return null;
+    }
+}
+function normalizeRename(rename, ctx) {
+    if (!rename)
+        return [];
+    const pairs = [];
+    for (const [token, replacementRaw] of Object.entries(rename)) {
+        const replacement = interpolate(replacementRaw, ctx);
+        if (!token)
+            continue;
+        pairs.push([token, replacement]);
+    }
+    // Apply longer tokens first to reduce surprising partial overlaps.
+    pairs.sort((a, b) => b[0].length - a[0].length);
+    return pairs;
+}
+function applyRename(input, pairs) {
+    let out = input;
+    for (const [token, replacement] of pairs) {
+        out = out.split(token).join(replacement);
+    }
+    return out;
+}
+export function applyRenameToBasename(basename, rename, ctx) {
+    const pairs = normalizeRename(rename, ctx);
+    const renamed = applyRename(basename, pairs);
+    if (renamed.includes("/") || renamed.includes("\\")) {
+        throw new Error(`Invalid rename result for basename (must not include path separators): ${renamed}`);
+    }
+    if (renamed.includes("\u0000")) {
+        throw new Error("Invalid rename result for basename (NUL byte)");
+    }
+    return renamed;
+}
+function validateRelativePath(rel) {
+    const cleaned = rel.replaceAll("\\", "/");
+    if (cleaned.startsWith("/"))
+        throw new Error(`Invalid relative path: ${rel}`);
+    if (cleaned.includes("\u0000"))
+        throw new Error("Invalid relative path (NUL byte)");
+    const parts = cleaned.split("/");
+    if (parts.some((p) => p === "..")) {
+        throw new Error(`Invalid relative path (path traversal): ${rel}`);
+    }
+    return cleaned;
+}

package/dist/lib/template-json.d.ts

@@ -19,7 +19,7 @@ export type TemplateQuestion = {
     }>;
     when?: Condition;
 };
-export type TemplateStep = CopyStep | MergeStep | EnvironmentStep | CommandStep;
+export type TemplateStep = CopyStep | MergeStep | EnvironmentStep | CommandStep | MoveStep;
 type StepBase = {
     when?: Condition;
 };
@@ -27,7 +27,18 @@ export type CopyStep = StepBase & {
     type: "copy";
     source: string;
     target: string;
+    include?: string[];
     exclude?: string[];
+    rename?: Record<string, string>;
+    render?: {
+        include: string[];
+        exclude?: string[];
+    };
+};
+export type MoveStep = StepBase & {
+    type: "move";
+    from: string;
+    to: string;
 };
 export type MergeStep = StepBase & {
     type: "merge";

package/oclif.manifest.json

@@ -90,5 +90,5 @@
       ]
     }
   },
-  "version": "1.3.0"
+  "version": "1.4.0"
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "harbor-templater",
   "description": "A CLI tool for scaffolding projects using Harbor templates",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "author": "Ben Di Giorgio",
   "bin": {
     "harbor-templater": "./bin/run.js"