harbor-templater 0.0.0

package/README.md

@@ -0,0 +1,394 @@
+# harbor-templater
+
+A new CLI generated with oclif
+
+## Dynamic Templates (WIP)
+
+This CLI is being extended into a dynamic project scaffolder (Vite-style) driven by a JSON template.
+
+- Template JSON spec: ./docs/template-json.md
+- Examples: ./docs/examples/
+
+[![oclif](https://img.shields.io/badge/cli-oclif-brightgreen.svg)](https://oclif.io)
+[![Version](https://img.shields.io/npm/v/harbor-templater.svg)](https://npmjs.org/package/harbor-templater)
+[![Downloads/week](https://img.shields.io/npm/dw/harbor-templater.svg)](https://npmjs.org/package/harbor-templater)
+
+<!-- toc -->
+* [harbor-templater](#harbor-templater)
+* [Usage](#usage)
+* [Commands](#commands)
+<!-- tocstop -->
+
+# Usage
+
+<!-- usage -->
+```sh-session
+$ npm install -g harbor-templater
+$ harbor-templater COMMAND
+running command...
+$ harbor-templater (--version)
+harbor-templater/0.0.0 win32-x64 node-v24.1.0
+$ harbor-templater --help [COMMAND]
+USAGE
+  $ harbor-templater COMMAND
+...
+```
+<!-- usagestop -->
+
+# Commands
+
+<!-- commands -->
+* [`harbor-templater help [COMMAND]`](#harbor-templater-help-command)
+* [`harbor-templater init`](#harbor-templater-init)
+* [`harbor-templater plugins`](#harbor-templater-plugins)
+* [`harbor-templater plugins add PLUGIN`](#harbor-templater-plugins-add-plugin)
+* [`harbor-templater plugins:inspect PLUGIN...`](#harbor-templater-pluginsinspect-plugin)
+* [`harbor-templater plugins install PLUGIN`](#harbor-templater-plugins-install-plugin)
+* [`harbor-templater plugins link PATH`](#harbor-templater-plugins-link-path)
+* [`harbor-templater plugins remove [PLUGIN]`](#harbor-templater-plugins-remove-plugin)
+* [`harbor-templater plugins reset`](#harbor-templater-plugins-reset)
+* [`harbor-templater plugins uninstall [PLUGIN]`](#harbor-templater-plugins-uninstall-plugin)
+* [`harbor-templater plugins unlink [PLUGIN]`](#harbor-templater-plugins-unlink-plugin)
+* [`harbor-templater plugins update`](#harbor-templater-plugins-update)
+
+## `harbor-templater help [COMMAND]`
+
+Display help for harbor-templater.
+
+```
+USAGE
+  $ harbor-templater help [COMMAND...] [-n]
+
+ARGUMENTS
+  [COMMAND...]  Command to show help for.
+
+FLAGS
+  -n, --nested-commands  Include all nested commands in the output.
+
+DESCRIPTION
+  Display help for harbor-templater.
+```
+
+_See code: [@oclif/plugin-help](https://github.com/oclif/plugin-help/blob/v6.2.36/src/commands/help.ts)_
+
+## `harbor-templater init`
+
+Scaffold a project from a JSON template
+
+```
+USAGE
+  $ harbor-templater init -t <value> [-o <value>] [--answer <value>...] [--defaults] [--dryRun]
+    [--conflict error|skip|overwrite|prompt] [--force] [--allowMissingEnv]
+
+FLAGS
+  -o, --out=<value>        [default: .] Base output directory (relative targets resolve from here)
+  -t, --template=<value>   (required) Path or URL to a template JSON file
+      --allowMissingEnv    Do not fail if an environment variable is missing for an environment step
+      --answer=<value>...  Provide an answer: --answer key=value (repeatable)
+      --conflict=<option>  [default: prompt] When a target already exists: error|skip|overwrite|prompt
+                           <options: error|skip|overwrite|prompt>
+      --defaults           Do not prompt; use defaults and provided --answer values
+      --dryRun             Print actions without writing files or running commands
+      --force              Overwrite existing files when copying
+
+DESCRIPTION
+  Scaffold a project from a JSON template
+
+EXAMPLES
+  $ harbor-templater init --template ./docs/examples/minimal.template.json --out ./my-app
+
+  $ 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/v0.0.0/src/commands/init/index.ts)_
+
+## `harbor-templater plugins`
+
+List installed plugins.
+
+```
+USAGE
+  $ harbor-templater plugins [--json] [--core]
+
+FLAGS
+  --core  Show core plugins.
+
+GLOBAL FLAGS
+  --json  Format output as json.
+
+DESCRIPTION
+  List installed plugins.
+
+EXAMPLES
+  $ harbor-templater plugins
+```
+
+_See code: [@oclif/plugin-plugins](https://github.com/oclif/plugin-plugins/blob/v5.4.54/src/commands/plugins/index.ts)_
+
+## `harbor-templater plugins add PLUGIN`
+
+Installs a plugin into harbor-templater.
+
+```
+USAGE
+  $ harbor-templater plugins add PLUGIN... [--json] [-f] [-h] [-s | -v]
+
+ARGUMENTS
+  PLUGIN...  Plugin to install.
+
+FLAGS
+  -f, --force    Force npm to fetch remote resources even if a local copy exists on disk.
+  -h, --help     Show CLI help.
+  -s, --silent   Silences npm output.
+  -v, --verbose  Show verbose npm output.
+
+GLOBAL FLAGS
+  --json  Format output as json.
+
+DESCRIPTION
+  Installs a plugin into harbor-templater.
+
+  Uses npm to install plugins.
+
+  Installation of a user-installed plugin will override a core plugin.
+
+  Use the HARBOR_TEMPLATER_NPM_LOG_LEVEL environment variable to set the npm loglevel.
+  Use the HARBOR_TEMPLATER_NPM_REGISTRY environment variable to set the npm registry.
+
+ALIASES
+  $ harbor-templater plugins add
+
+EXAMPLES
+  Install a plugin from npm registry.
+
+    $ harbor-templater plugins add myplugin
+
+  Install a plugin from a github url.
+
+    $ harbor-templater plugins add https://github.com/someuser/someplugin
+
+  Install a plugin from a github slug.
+
+    $ harbor-templater plugins add someuser/someplugin
+```
+
+## `harbor-templater plugins:inspect PLUGIN...`
+
+Displays installation properties of a plugin.
+
+```
+USAGE
+  $ harbor-templater plugins inspect PLUGIN...
+
+ARGUMENTS
+  PLUGIN...  [default: .] Plugin to inspect.
+
+FLAGS
+  -h, --help     Show CLI help.
+  -v, --verbose
+
+GLOBAL FLAGS
+  --json  Format output as json.
+
+DESCRIPTION
+  Displays installation properties of a plugin.
+
+EXAMPLES
+  $ harbor-templater plugins inspect myplugin
+```
+
+_See code: [@oclif/plugin-plugins](https://github.com/oclif/plugin-plugins/blob/v5.4.54/src/commands/plugins/inspect.ts)_
+
+## `harbor-templater plugins install PLUGIN`
+
+Installs a plugin into harbor-templater.
+
+```
+USAGE
+  $ harbor-templater plugins install PLUGIN... [--json] [-f] [-h] [-s | -v]
+
+ARGUMENTS
+  PLUGIN...  Plugin to install.
+
+FLAGS
+  -f, --force    Force npm to fetch remote resources even if a local copy exists on disk.
+  -h, --help     Show CLI help.
+  -s, --silent   Silences npm output.
+  -v, --verbose  Show verbose npm output.
+
+GLOBAL FLAGS
+  --json  Format output as json.
+
+DESCRIPTION
+  Installs a plugin into harbor-templater.
+
+  Uses npm to install plugins.
+
+  Installation of a user-installed plugin will override a core plugin.
+
+  Use the HARBOR_TEMPLATER_NPM_LOG_LEVEL environment variable to set the npm loglevel.
+  Use the HARBOR_TEMPLATER_NPM_REGISTRY environment variable to set the npm registry.
+
+ALIASES
+  $ harbor-templater plugins add
+
+EXAMPLES
+  Install a plugin from npm registry.
+
+    $ harbor-templater plugins install myplugin
+
+  Install a plugin from a github url.
+
+    $ harbor-templater plugins install https://github.com/someuser/someplugin
+
+  Install a plugin from a github slug.
+
+    $ harbor-templater plugins install someuser/someplugin
+```
+
+_See code: [@oclif/plugin-plugins](https://github.com/oclif/plugin-plugins/blob/v5.4.54/src/commands/plugins/install.ts)_
+
+## `harbor-templater plugins link PATH`
+
+Links a plugin into the CLI for development.
+
+```
+USAGE
+  $ harbor-templater plugins link PATH [-h] [--install] [-v]
+
+ARGUMENTS
+  PATH  [default: .] path to plugin
+
+FLAGS
+  -h, --help          Show CLI help.
+  -v, --verbose
+      --[no-]install  Install dependencies after linking the plugin.
+
+DESCRIPTION
+  Links a plugin into the CLI for development.
+
+  Installation of a linked plugin will override a user-installed or core plugin.
+
+  e.g. If you have a user-installed or core plugin that has a 'hello' command, installing a linked plugin with a 'hello'
+  command will override the user-installed or core plugin implementation. This is useful for development work.
+
+
+EXAMPLES
+  $ harbor-templater plugins link myplugin
+```
+
+_See code: [@oclif/plugin-plugins](https://github.com/oclif/plugin-plugins/blob/v5.4.54/src/commands/plugins/link.ts)_
+
+## `harbor-templater plugins remove [PLUGIN]`
+
+Removes a plugin from the CLI.
+
+```
+USAGE
+  $ harbor-templater plugins remove [PLUGIN...] [-h] [-v]
+
+ARGUMENTS
+  [PLUGIN...]  plugin to uninstall
+
+FLAGS
+  -h, --help     Show CLI help.
+  -v, --verbose
+
+DESCRIPTION
+  Removes a plugin from the CLI.
+
+ALIASES
+  $ harbor-templater plugins unlink
+  $ harbor-templater plugins remove
+
+EXAMPLES
+  $ harbor-templater plugins remove myplugin
+```
+
+## `harbor-templater plugins reset`
+
+Remove all user-installed and linked plugins.
+
+```
+USAGE
+  $ harbor-templater plugins reset [--hard] [--reinstall]
+
+FLAGS
+  --hard       Delete node_modules and package manager related files in addition to uninstalling plugins.
+  --reinstall  Reinstall all plugins after uninstalling.
+```
+
+_See code: [@oclif/plugin-plugins](https://github.com/oclif/plugin-plugins/blob/v5.4.54/src/commands/plugins/reset.ts)_
+
+## `harbor-templater plugins uninstall [PLUGIN]`
+
+Removes a plugin from the CLI.
+
+```
+USAGE
+  $ harbor-templater plugins uninstall [PLUGIN...] [-h] [-v]
+
+ARGUMENTS
+  [PLUGIN...]  plugin to uninstall
+
+FLAGS
+  -h, --help     Show CLI help.
+  -v, --verbose
+
+DESCRIPTION
+  Removes a plugin from the CLI.
+
+ALIASES
+  $ harbor-templater plugins unlink
+  $ harbor-templater plugins remove
+
+EXAMPLES
+  $ harbor-templater plugins uninstall myplugin
+```
+
+_See code: [@oclif/plugin-plugins](https://github.com/oclif/plugin-plugins/blob/v5.4.54/src/commands/plugins/uninstall.ts)_
+
+## `harbor-templater plugins unlink [PLUGIN]`
+
+Removes a plugin from the CLI.
+
+```
+USAGE
+  $ harbor-templater plugins unlink [PLUGIN...] [-h] [-v]
+
+ARGUMENTS
+  [PLUGIN...]  plugin to uninstall
+
+FLAGS
+  -h, --help     Show CLI help.
+  -v, --verbose
+
+DESCRIPTION
+  Removes a plugin from the CLI.
+
+ALIASES
+  $ harbor-templater plugins unlink
+  $ harbor-templater plugins remove
+
+EXAMPLES
+  $ harbor-templater plugins unlink myplugin
+```
+
+## `harbor-templater plugins update`
+
+Update installed plugins.
+
+```
+USAGE
+  $ harbor-templater plugins update [-h] [-v]
+
+FLAGS
+  -h, --help     Show CLI help.
+  -v, --verbose
+
+DESCRIPTION
+  Update installed plugins.
+```
+
+_See code: [@oclif/plugin-plugins](https://github.com/oclif/plugin-plugins/blob/v5.4.54/src/commands/plugins/update.ts)_
+<!-- commandsstop -->

package/bin/dev.cmd

@@ -0,0 +1,3 @@
+@echo off
+
+node --loader ts-node/esm --no-warnings=ExperimentalWarning "%~dp0\dev" %*

package/bin/dev.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env -S node --loader ts-node/esm --disable-warning=ExperimentalWarning
+
+import {execute} from '@oclif/core'
+
+await execute({development: true, dir: import.meta.url})

package/bin/run.cmd

@@ -0,0 +1,3 @@
+@echo off
+
+node "%~dp0\run" %*

package/bin/run.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+
+import {execute} from '@oclif/core'
+
+await execute({dir: import.meta.url})

package/dist/commands/init/index.d.ts

@@ -0,0 +1,16 @@
+import { Command } from "@oclif/core";
+export default class Init extends Command {
+    static description: string;
+    static examples: string[];
+    static flags: {
+        template: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        out: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        answer: import("@oclif/core/interfaces").OptionFlag<string[] | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        defaults: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        dryRun: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        conflict: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        force: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        allowMissingEnv: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+    };
+    run(): Promise<void>;
+}

package/dist/commands/init/index.js

@@ -0,0 +1,302 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+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 { applyEnvironmentReplacements } from "../../lib/environment.js";
+import { copyPath, 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";
+export default class Init extends Command {
+    static description = "Scaffold a project from a JSON template";
+    static examples = [
+        `<%= config.bin %> <%= command.id %> --template ./docs/examples/minimal.template.json --out ./my-app`,
+        `<%= config.bin %> <%= command.id %> -t template.json -o . --answer projectDir=./my-app --defaults`,
+    ];
+    static flags = {
+        template: Flags.string({
+            char: "t",
+            description: "Path or URL to a template JSON file",
+            required: true,
+        }),
+        out: Flags.string({
+            char: "o",
+            description: "Base output directory (relative targets resolve from here)",
+            default: ".",
+        }),
+        answer: Flags.string({
+            description: "Provide an answer: --answer key=value (repeatable)",
+            multiple: true,
+        }),
+        defaults: Flags.boolean({
+            description: "Do not prompt; use defaults and provided --answer values",
+            default: false,
+        }),
+        dryRun: Flags.boolean({
+            description: "Print actions without writing files or running commands",
+            default: false,
+        }),
+        conflict: Flags.string({
+            description: "When a target already exists: error|skip|overwrite|prompt",
+            options: ["error", "skip", "overwrite", "prompt"],
+            default: "prompt",
+        }),
+        force: Flags.boolean({
+            description: "Overwrite existing files when copying",
+            default: false,
+        }),
+        allowMissingEnv: Flags.boolean({
+            description: "Do not fail if an environment variable is missing for an environment step",
+            default: false,
+        }),
+    };
+    async run() {
+        const { flags } = await this.parse(Init);
+        const outDir = path.resolve(flags.out);
+        await ensureDir(outDir);
+        const initialAnswers = parseAnswers(flags.answer ?? []);
+        const template = await loadTemplate(flags.template);
+        const ctx = buildInitialContext(outDir, initialAnswers);
+        await collectAnswers({
+            questions: templateQuestions(template),
+            ctx,
+            defaults: flags.defaults,
+        });
+        const steps = templateSteps(template);
+        await executeSteps({
+            steps,
+            ctx,
+            log: (m) => this.log(m),
+            dryRun: flags.dryRun,
+            force: flags.force,
+            conflict: flags.conflict,
+            defaults: flags.defaults,
+            allowMissingEnv: flags.allowMissingEnv,
+        });
+    }
+}
+function parseAnswers(pairs) {
+    const out = {};
+    for (const pair of pairs) {
+        const idx = pair.indexOf("=");
+        if (idx === -1)
+            throw new Error(`Invalid --answer: ${pair} (expected key=value)`);
+        const key = pair.slice(0, idx).trim();
+        const value = pair.slice(idx + 1).trim();
+        out[key] = value;
+    }
+    return out;
+}
+async function loadTemplate(templateRef) {
+    if (templateRef.startsWith("http://") || templateRef.startsWith("https://")) {
+        const response = await fetch(templateRef);
+        if (!response.ok) {
+            throw new Error(`Failed to download template: ${response.status} ${response.statusText}`);
+        }
+        return (await response.json());
+    }
+    const raw = await fs.readFile(path.resolve(templateRef), "utf8");
+    return JSON.parse(raw);
+}
+async function collectAnswers(args) {
+    for (const q of args.questions) {
+        if (!evaluateCondition(args.ctx, q.when))
+            continue;
+        if (q.id in args.ctx.answers)
+            continue;
+        if (args.defaults) {
+            if (q.default !== undefined) {
+                args.ctx.answers[q.id] = q.default;
+                continue;
+            }
+            if (q.required)
+                throw new Error(`Missing required answer: ${q.id}`);
+            continue;
+        }
+        args.ctx.answers[q.id] = await promptForQuestion(q);
+        if (q.required &&
+            (args.ctx.answers[q.id] === "" || args.ctx.answers[q.id] == null)) {
+            throw new Error(`Missing required answer: ${q.id}`);
+        }
+    }
+}
+async function promptForQuestion(q) {
+    switch (q.type) {
+        case "input":
+            return await input({
+                message: q.message,
+                default: typeof q.default === "string" ? q.default : undefined,
+            });
+        case "confirm":
+            return await confirm({
+                message: q.message,
+                default: typeof q.default === "boolean" ? q.default : undefined,
+            });
+        case "select": {
+            const choices = (q.options ?? []).map((o) => ({
+                name: o.label,
+                value: o.value,
+            }));
+            return await select({
+                message: q.message,
+                choices,
+                default: typeof q.default === "string" ? q.default : undefined,
+            });
+        }
+        case "multiselect": {
+            const defaultValues = new Set(Array.isArray(q.default) ? q.default : []);
+            const choices = (q.options ?? []).map((o) => ({
+                name: o.label,
+                value: o.value,
+                checked: defaultValues.has(o.value),
+            }));
+            return await checkbox({ message: q.message, choices });
+        }
+    }
+}
+async function executeSteps(args) {
+    for (const step of args.steps) {
+        if (!evaluateCondition(args.ctx, step.when))
+            continue;
+        switch (step.type) {
+            case "copy": {
+                const target = resolveTargetPath(args.ctx.outDir, interpolate(step.target, args.ctx));
+                const src = await resolveSource(interpolate(step.source, args.ctx));
+                if (args.dryRun) {
+                    args.log(`copy ${step.source} -> ${target}`);
+                    break;
+                }
+                const policy = effectiveConflictPolicy(args);
+                if (src.kind === "dir") {
+                    const shouldProceed = await handleDirConflict({
+                        policy,
+                        source: step.source,
+                        target,
+                        defaults: args.defaults,
+                    });
+                    if (!shouldProceed) {
+                        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,
+                    });
+                }
+                else {
+                    // If target ends with '/', treat it as directory and keep filename
+                    const finalTarget = looksLikeDirTarget(step.target)
+                        ? path.join(target, path.basename(src.path))
+                        : target;
+                    const shouldProceed = await handleFileConflict({
+                        policy,
+                        source: step.source,
+                        target: finalTarget,
+                        defaults: args.defaults,
+                    });
+                    if (!shouldProceed) {
+                        args.log(`skip copy ${step.source} -> ${finalTarget} (exists)`);
+                        break;
+                    }
+                    await copyPath(src.path, finalTarget, {
+                        force: policy === "overwrite" || args.force,
+                    });
+                }
+                break;
+            }
+            case "merge": {
+                const target = resolveTargetPath(args.ctx.outDir, interpolate(step.target, args.ctx));
+                const src = await resolveSource(interpolate(step.source, args.ctx));
+                if (src.kind !== "file")
+                    throw new Error("merge source must resolve to a file");
+                if (args.dryRun) {
+                    args.log(`merge ${step.source} -> ${target}`);
+                    break;
+                }
+                await mergeIntoTarget(src.path, target, step.merge ?? {});
+                break;
+            }
+            case "environment": {
+                const target = resolveTargetPath(args.ctx.outDir, interpolate(step.target, args.ctx));
+                if (args.dryRun) {
+                    args.log(`environment ${target}`);
+                    break;
+                }
+                await applyEnvironmentReplacements(target, step.variables, {
+                    allowMissing: args.allowMissingEnv,
+                });
+                break;
+            }
+            case "command": {
+                const cwd = resolveTargetPath(args.ctx.outDir, step.workingDirectory
+                    ? interpolate(step.workingDirectory, args.ctx)
+                    : args.ctx.outDir);
+                const cmd = interpolate(step.command, args.ctx);
+                if (args.dryRun) {
+                    args.log(`command (${cwd}): ${cmd}`);
+                    break;
+                }
+                await runShellCommand(cmd, cwd);
+                break;
+            }
+        }
+    }
+}
+function effectiveConflictPolicy(args) {
+    // If user asked for no prompting, don't prompt on conflicts.
+    if (args.defaults && args.conflict === "prompt")
+        return "error";
+    return args.conflict;
+}
+async function handleFileConflict(args) {
+    const exists = await pathExists(args.target);
+    if (!exists)
+        return true;
+    switch (args.policy) {
+        case "overwrite":
+            return true;
+        case "skip":
+            return false;
+        case "error":
+            throw new Error(`Target exists: ${args.target}`);
+        case "prompt":
+            return await confirm({
+                message: `Overwrite ${args.target}?`,
+                default: false,
+            });
+    }
+}
+async function handleDirConflict(args) {
+    const exists = await pathExists(args.target);
+    if (!exists)
+        return true;
+    switch (args.policy) {
+        case "overwrite":
+            return true;
+        case "skip":
+            return false;
+        case "error":
+            throw new Error(`Target exists: ${args.target}`);
+        case "prompt":
+            return await confirm({
+                message: `Directory exists. Merge/overwrite into ${args.target}?`,
+                default: false,
+            });
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1 @@
+export { run } from '@oclif/core';

package/dist/index.js

@@ -0,0 +1 @@
+export { run } from '@oclif/core';

package/dist/lib/commands.d.ts

@@ -0,0 +1 @@
+export declare function runShellCommand(command: string, cwd: string): Promise<void>;

package/dist/lib/commands.js

@@ -0,0 +1,13 @@
+import { spawn } from "node:child_process";
+export async function runShellCommand(command, cwd) {
+    await new Promise((resolve, reject) => {
+        const child = spawn(command, { cwd, shell: true, stdio: "inherit" });
+        child.on("error", reject);
+        child.on("exit", (code) => {
+            if (code === 0)
+                resolve();
+            else
+                reject(new Error(`Command failed (${code}): ${command}`));
+        });
+    });
+}

package/dist/lib/environment.d.ts

@@ -0,0 +1,3 @@
+export declare function applyEnvironmentReplacements(targetPath: string, variables: Record<string, string>, options: {
+    allowMissing: boolean;
+}): Promise<void>;

package/dist/lib/environment.js

@@ -0,0 +1,14 @@
+import fs from "node:fs/promises";
+export async function applyEnvironmentReplacements(targetPath, variables, options) {
+    let contents = await fs.readFile(targetPath, "utf8");
+    for (const [envName, placeholder] of Object.entries(variables)) {
+        const value = process.env[envName];
+        if (value == null) {
+            if (options.allowMissing)
+                continue;
+            throw new Error(`Missing environment variable: ${envName}`);
+        }
+        contents = contents.split(placeholder).join(value);
+    }
+    await fs.writeFile(targetPath, contents, "utf8");
+}

package/dist/lib/fs-ops.d.ts

@@ -0,0 +1,6 @@
+export declare function ensureDir(dirPath: string): Promise<void>;
+export declare function pathExists(targetPath: string): Promise<boolean>;
+export declare function copyPath(sourcePath: string, targetPath: string, options: {
+    force: boolean;
+}): Promise<void>;
+export declare function looksLikeDirTarget(target: string): boolean;

package/dist/lib/fs-ops.js

@@ -0,0 +1,32 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+export async function ensureDir(dirPath) {
+    await fs.mkdir(dirPath, { recursive: true });
+}
+export async function pathExists(targetPath) {
+    return await fs
+        .access(targetPath)
+        .then(() => true)
+        .catch(() => false);
+}
+export async function copyPath(sourcePath, targetPath, options) {
+    const stat = await fs.stat(sourcePath);
+    if (stat.isDirectory()) {
+        await ensureDir(targetPath);
+        // Node 18+ supports fs.cp
+        await fs.cp(sourcePath, targetPath, {
+            recursive: true,
+            force: options.force,
+        });
+        return;
+    }
+    await ensureDir(path.dirname(targetPath));
+    if (!options.force) {
+        if (await pathExists(targetPath))
+            throw new Error(`Target exists: ${targetPath}`);
+    }
+    await fs.copyFile(sourcePath, targetPath);
+}
+export function looksLikeDirTarget(target) {
+    return target.endsWith("/") || target.endsWith("\\");
+}

package/dist/lib/merge.d.ts

@@ -0,0 +1,5 @@
+export type MergeOptions = {
+    format?: "json" | "yaml" | "text";
+    strategy?: "deep" | "shallow" | "append" | "prepend";
+};
+export declare function mergeIntoTarget(sourcePath: string, targetPath: string, options: MergeOptions): Promise<void>;

package/dist/lib/merge.js

@@ -0,0 +1,65 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { ensureDir } from "./fs-ops.js";
+export async function mergeIntoTarget(sourcePath, targetPath, options) {
+    const format = options.format ?? "json";
+    const strategy = options.strategy ?? "deep";
+    if (format === "yaml") {
+        throw new Error("YAML merge is not implemented yet");
+    }
+    await ensureDir(path.dirname(targetPath));
+    if (format === "text") {
+        const incoming = await fs.readFile(sourcePath, "utf8");
+        let existing = "";
+        try {
+            existing = await fs.readFile(targetPath, "utf8");
+        }
+        catch {
+            // doesn't exist
+        }
+        const merged = strategy === "prepend"
+            ? `${incoming}${existing}`
+            : strategy === "append"
+                ? `${existing}${incoming}`
+                : incoming;
+        await fs.writeFile(targetPath, merged, "utf8");
+        return;
+    }
+    // json
+    const incoming = JSON.parse(await fs.readFile(sourcePath, "utf8"));
+    let existing = {};
+    try {
+        existing = JSON.parse(await fs.readFile(targetPath, "utf8"));
+    }
+    catch {
+        existing = {};
+    }
+    const merged = strategy === "shallow"
+        ? shallowMerge(existing, incoming)
+        : deepMerge(existing, incoming);
+    await fs.writeFile(targetPath, `${JSON.stringify(merged, null, 2)}\n`, "utf8");
+}
+function shallowMerge(a, b) {
+    if (!isPlainObject(a) || !isPlainObject(b))
+        return b;
+    return { ...a, ...b };
+}
+function deepMerge(a, b) {
+    if (Array.isArray(a) && Array.isArray(b))
+        return [...a, ...b];
+    if (!isPlainObject(a) || !isPlainObject(b))
+        return b;
+    const out = { ...a };
+    for (const [key, value] of Object.entries(b)) {
+        if (Object.hasOwn(out, key)) {
+            out[key] = deepMerge(out[key], value);
+        }
+        else {
+            out[key] = value;
+        }
+    }
+    return out;
+}
+function isPlainObject(value) {
+    return value != null && typeof value === "object" && !Array.isArray(value);
+}

package/dist/lib/sources.d.ts

@@ -0,0 +1,8 @@
+export type ResolvedSource = {
+    kind: "file";
+    path: string;
+} | {
+    kind: "dir";
+    path: string;
+};
+export declare function resolveSource(source: string): Promise<ResolvedSource>;

package/dist/lib/sources.js

@@ -0,0 +1,77 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { x as untar } from "tar";
+export async function resolveSource(source) {
+    if (source.startsWith("http://") || source.startsWith("https://")) {
+        return await downloadUrlToTempFile(source);
+    }
+    if (source.startsWith("github:")) {
+        return await downloadGitHubToTemp(source);
+    }
+    // local filesystem
+    const localPath = path.resolve(source);
+    const stat = await fs.stat(localPath);
+    return stat.isDirectory()
+        ? { kind: "dir", path: localPath }
+        : { kind: "file", path: localPath };
+}
+async function downloadUrlToTempFile(url) {
+    const response = await fetch(url);
+    if (!response.ok)
+        throw new Error(`Failed to download ${url}: ${response.status} ${response.statusText}`);
+    const buffer = Buffer.from(await response.arrayBuffer());
+    const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), "harbor-templater-url-"));
+    const filePath = path.join(tmpDir, "download");
+    await fs.writeFile(filePath, buffer);
+    return { kind: "file", path: filePath };
+}
+// github:<owner>/<repo>#<ref>:<path>
+// If <path> points to a directory, returns kind=dir.
+async function downloadGitHubToTemp(source) {
+    const parsed = parseGitHubSource(source);
+    const tarballUrl = `https://codeload.github.com/${parsed.owner}/${parsed.repo}/tar.gz/${parsed.ref}`;
+    const response = await fetch(tarballUrl);
+    if (!response.ok) {
+        throw new Error(`Failed to download ${tarballUrl}: ${response.status} ${response.statusText}`);
+    }
+    const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), "harbor-templater-gh-"));
+    const tarPath = path.join(tmpDir, "repo.tgz");
+    const buffer = Buffer.from(await response.arrayBuffer());
+    await fs.writeFile(tarPath, buffer);
+    // GitHub tarballs wrap content in a single top-level folder: <repo>-<shaOrRef>/
+    const extractDir = path.join(tmpDir, "extract");
+    await fs.mkdir(extractDir);
+    await untar({ file: tarPath, cwd: extractDir });
+    const entries = await fs.readdir(extractDir);
+    if (entries.length === 0)
+        throw new Error("Downloaded GitHub tarball was empty");
+    const firstEntry = entries[0];
+    if (!firstEntry)
+        throw new Error("Downloaded GitHub tarball was empty");
+    const root = path.join(extractDir, firstEntry);
+    const candidate = path.join(root, parsed.subpath);
+    const stat = await fs.stat(candidate);
+    return stat.isDirectory()
+        ? { kind: "dir", path: candidate }
+        : { kind: "file", path: candidate };
+}
+function parseGitHubSource(input) {
+    const trimmed = input.slice("github:".length);
+    const hashIdx = trimmed.indexOf("#");
+    const colonIdx = trimmed.indexOf(":");
+    if (hashIdx === -1 || colonIdx === -1 || colonIdx < hashIdx) {
+        throw new Error(`Invalid github source: ${input}. Expected github:<owner>/<repo>#<ref>:<path>`);
+    }
+    const repoPart = trimmed.slice(0, hashIdx);
+    const refPart = trimmed.slice(hashIdx + 1, colonIdx);
+    const pathPart = trimmed.slice(colonIdx + 1);
+    const [owner, repo] = repoPart.split("/");
+    if (!owner || !repo)
+        throw new Error(`Invalid github source: ${input} (missing owner/repo)`);
+    if (!refPart)
+        throw new Error(`Invalid github source: ${input} (missing ref)`);
+    if (!pathPart)
+        throw new Error(`Invalid github source: ${input} (missing path)`);
+    return { owner, repo, ref: refPart, subpath: pathPart };
+}

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

@@ -0,0 +1,12 @@
+import type { Condition, JSONTemplate, TemplateQuestion, TemplateStep, ValueRef } from "./template-json.js";
+export type TemplateContext = {
+    answers: Record<string, unknown>;
+    outDir: string;
+};
+export declare function buildInitialContext(outDir: string, initialAnswers?: Record<string, unknown>): TemplateContext;
+export declare function getRefValue(ctx: TemplateContext, ref: ValueRef): unknown;
+export declare function evaluateCondition(ctx: TemplateContext, condition?: Condition): boolean;
+export declare function interpolate(input: string, ctx: TemplateContext): string;
+export declare function resolveTargetPath(outDir: string, target: string): string;
+export declare function templateQuestions(template: JSONTemplate): TemplateQuestion[];
+export declare function templateSteps(template: JSONTemplate): TemplateStep[];

package/dist/lib/template-engine.js

@@ -0,0 +1,76 @@
+import path from "node:path";
+export function buildInitialContext(outDir, initialAnswers) {
+    return {
+        answers: { ...(initialAnswers ?? {}) },
+        outDir,
+    };
+}
+export function getRefValue(ctx, ref) {
+    const refPath = ref.ref;
+    if (!refPath)
+        return undefined;
+    const parts = refPath.split(".");
+    let current = ctx;
+    for (const part of parts) {
+        if (current == null)
+            return undefined;
+        if (typeof current !== "object")
+            return undefined;
+        const record = current;
+        current = record[part];
+    }
+    return current;
+}
+export function evaluateCondition(ctx, condition) {
+    if (!condition)
+        return true;
+    switch (condition.op) {
+        case "eq":
+            return getRefValue(ctx, condition.left) === condition.right;
+        case "neq":
+            return getRefValue(ctx, condition.left) !== condition.right;
+        case "in": {
+            const value = getRefValue(ctx, condition.left);
+            return Array.isArray(condition.right) && condition.right.includes(value);
+        }
+        case "notIn": {
+            const value = getRefValue(ctx, condition.left);
+            return Array.isArray(condition.right) && !condition.right.includes(value);
+        }
+        case "truthy":
+            return Boolean(getRefValue(ctx, condition.value));
+        case "falsy":
+            return !getRefValue(ctx, condition.value);
+        case "exists": {
+            const value = getRefValue(ctx, condition.value);
+            return value !== undefined && value !== null;
+        }
+        case "and":
+            return condition.conditions.every((c) => evaluateCondition(ctx, c));
+        case "or":
+            return condition.conditions.some((c) => evaluateCondition(ctx, c));
+        case "not":
+            return !evaluateCondition(ctx, condition.condition);
+    }
+}
+const INTERPOLATION = /\{\{\s*([^}]+?)\s*\}\}/g;
+export function interpolate(input, ctx) {
+    return input.replace(INTERPOLATION, (_match, expr) => {
+        const trimmed = String(expr ?? "").trim();
+        // Support {{answers.foo}} and {{outDir}}
+        if (trimmed === "outDir")
+            return ctx.outDir;
+        // Any other expression is treated as a ref path
+        const value = getRefValue(ctx, { ref: trimmed });
+        return value == null ? "" : String(value);
+    });
+}
+export function resolveTargetPath(outDir, target) {
+    return path.isAbsolute(target) ? target : path.resolve(outDir, target);
+}
+export function templateQuestions(template) {
+    return template.questions ?? [];
+}
+export function templateSteps(template) {
+    return template.steps;
+}

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

@@ -0,0 +1,71 @@
+export type JSONTemplate = {
+    author?: string;
+    description?: string;
+    name: string;
+    version: string;
+    questions?: TemplateQuestion[];
+    steps: TemplateStep[];
+};
+export type TemplateQuestion = {
+    id: string;
+    type: "input" | "confirm" | "select" | "multiselect";
+    message: string;
+    default?: string | boolean | string[];
+    required?: boolean;
+    options?: Array<{
+        label: string;
+        value: string;
+    }>;
+    when?: Condition;
+};
+export type TemplateStep = CopyStep | MergeStep | EnvironmentStep | CommandStep;
+type StepBase = {
+    when?: Condition;
+};
+export type CopyStep = StepBase & {
+    type: "copy";
+    source: string;
+    target: string;
+    exclude?: string[];
+};
+export type MergeStep = StepBase & {
+    type: "merge";
+    source: string;
+    target: string;
+    merge?: {
+        format?: "json" | "yaml" | "text";
+        strategy?: "deep" | "shallow" | "append" | "prepend";
+    };
+};
+export type EnvironmentStep = StepBase & {
+    type: "environment";
+    target: string;
+    variables: Record<string, string>;
+};
+export type CommandStep = StepBase & {
+    type: "command";
+    command: string;
+    workingDirectory?: string;
+};
+export type ValueRef = {
+    ref: string;
+};
+export type Condition = {
+    op: "eq" | "neq";
+    left: ValueRef;
+    right: unknown;
+} | {
+    op: "in" | "notIn";
+    left: ValueRef;
+    right: unknown[];
+} | {
+    op: "truthy" | "falsy" | "exists";
+    value: ValueRef;
+} | {
+    op: "and" | "or";
+    conditions: Condition[];
+} | {
+    op: "not";
+    condition: Condition;
+};
+export {};

package/dist/lib/template-json.js

@@ -0,0 +1 @@
+export {};

package/oclif.manifest.json

@@ -0,0 +1,94 @@
+{
+  "commands": {
+    "init": {
+      "aliases": [],
+      "args": {},
+      "description": "Scaffold a project from a JSON template",
+      "examples": [
+        "<%= config.bin %> <%= command.id %> --template ./docs/examples/minimal.template.json --out ./my-app",
+        "<%= config.bin %> <%= command.id %> -t template.json -o . --answer projectDir=./my-app --defaults"
+      ],
+      "flags": {
+        "template": {
+          "char": "t",
+          "description": "Path or URL to a template JSON file",
+          "name": "template",
+          "required": true,
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "out": {
+          "char": "o",
+          "description": "Base output directory (relative targets resolve from here)",
+          "name": "out",
+          "default": ".",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "answer": {
+          "description": "Provide an answer: --answer key=value (repeatable)",
+          "name": "answer",
+          "hasDynamicHelp": false,
+          "multiple": true,
+          "type": "option"
+        },
+        "defaults": {
+          "description": "Do not prompt; use defaults and provided --answer values",
+          "name": "defaults",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "dryRun": {
+          "description": "Print actions without writing files or running commands",
+          "name": "dryRun",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "conflict": {
+          "description": "When a target already exists: error|skip|overwrite|prompt",
+          "name": "conflict",
+          "default": "prompt",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "options": [
+            "error",
+            "skip",
+            "overwrite",
+            "prompt"
+          ],
+          "type": "option"
+        },
+        "force": {
+          "description": "Overwrite existing files when copying",
+          "name": "force",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "allowMissingEnv": {
+          "description": "Do not fail if an environment variable is missing for an environment step",
+          "name": "allowMissingEnv",
+          "allowNo": false,
+          "type": "boolean"
+        }
+      },
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "init",
+      "pluginAlias": "harbor-templater",
+      "pluginName": "harbor-templater",
+      "pluginType": "core",
+      "strict": true,
+      "enableJsonFlag": false,
+      "isESM": true,
+      "relativePath": [
+        "dist",
+        "commands",
+        "init",
+        "index.js"
+      ]
+    }
+  },
+  "version": "0.0.0"
+}

package/package.json

@@ -0,0 +1,95 @@
+{
+  "name": "harbor-templater",
+  "description": "A CLI tool for scaffolding projects using Harbor templates",
+  "version": "0.0.0",
+  "author": "Ben Di Giorgio",
+  "bin": {
+    "harbor-templater": "./bin/run.js"
+  },
+  "bugs": "https://github.com/bendigiorgio/harbor-templater/issues",
+  "dependencies": {
+    "@inquirer/prompts": "^8.2.0",
+    "@oclif/core": "^4",
+    "@oclif/plugin-help": "^6",
+    "@oclif/plugin-plugins": "^5",
+    "picomatch": "^4.0.3",
+    "tar": "^7.5.3"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.3.11",
+    "@commitlint/cli": "^20.3.1",
+    "@commitlint/config-conventional": "^20.3.1",
+    "@eslint/compat": "^1",
+    "@oclif/prettier-config": "^0.2.1",
+    "@oclif/test": "^4",
+    "@semantic-release/changelog": "^6.0.3",
+    "@semantic-release/commit-analyzer": "^13.0.1",
+    "@semantic-release/exec": "^7.1.0",
+    "@semantic-release/git": "^10.0.1",
+    "@semantic-release/github": "^12.0.2",
+    "@semantic-release/npm": "^13.1.3",
+    "@semantic-release/release-notes-generator": "^14.1.0",
+    "@types/chai": "^4",
+    "@types/mocha": "^10",
+    "@types/node": "^24.10.9",
+    "@types/picomatch": "^4.0.2",
+    "chai": "^4",
+    "eslint": "^9",
+    "eslint-config-oclif": "^6",
+    "eslint-config-prettier": "^10",
+    "husky": "^9.1.7",
+    "mocha": "^10",
+    "oclif": "^4",
+    "semantic-release": "^25.0.2",
+    "shx": "^0.3.3",
+    "ts-node": "^10",
+    "typescript": "^5"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "files": [
+    "./bin",
+    "./dist",
+    "./oclif.manifest.json"
+  ],
+  "homepage": "https://github.com/bendigiorgio/harbor-templater",
+  "keywords": [
+    "oclif"
+  ],
+  "license": "MIT",
+  "main": "dist/index.js",
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "oclif": {
+    "bin": "harbor-templater",
+    "dirname": "harbor-templater",
+    "commands": "./dist/commands",
+    "plugins": [
+      "@oclif/plugin-help",
+      "@oclif/plugin-plugins"
+    ],
+    "topicSeparator": " "
+  },
+  "repository": "bendigiorgio/harbor-templater",
+  "scripts": {
+    "build": "shx rm -rf dist && shx rm -f tsconfig.tsbuildinfo && tsc -p tsconfig.json",
+    "format": "biome format",
+    "lint": "biome lint",
+    "check": "biome check",
+    "lint:fix": "biome lint --fix",
+    "postpack": "shx rm -f oclif.manifest.json",
+    "posttest": "pnpm run lint",
+    "prepack": "pnpm run build && oclif manifest && oclif readme",
+    "prepublishOnly": "pnpm test && pnpm run build && pnpm run prepack",
+    "prepare": "husky",
+    "commitlint": "commitlint --edit",
+    "release": "semantic-release",
+    "test": "mocha --forbid-only \"test/**/*.test.ts\"",
+    "version": "oclif readme && git add README.md"
+  },
+  "types": "dist/index.d.ts",
+  "packageManager": "pnpm@10.12.1+sha512.f0dda8580f0ee9481c5c79a1d927b9164f2c478e90992ad268bbb2465a736984391d6333d2c327913578b2804af33474ca554ba29c04a8b13060a717675ae3ac"
+}