harbor-templater 1.0.0 → 1.2.0

package/README.md

@@ -27,7 +27,7 @@ $ npm install -g harbor-templater
 $ harbor-templater COMMAND
 running command...
 $ harbor-templater (--version)
-harbor-templater/1.0.0 linux-x64 node-v24.12.0
+harbor-templater/1.2.0 linux-x64 node-v24.12.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.0.0/src/commands/init/index.ts)_
+_See code: [src/commands/init/index.ts](https://github.com/bendigiorgio/harbor-templater/blob/v1.2.0/src/commands/init/index.ts)_
 
 ## `harbor-templater plugins`
 

package/dist/index.d.ts

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

package/dist/index.js

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

package/dist/lib/commands.js

@@ -1,13 +1,45 @@
 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" });
+        const child = spawn(command, {
+            cwd,
+            shell: true,
+            stdio: ["inherit", "pipe", "pipe"],
+        });
+        const stdoutChunks = [];
+        const stderrChunks = [];
+        const maxCaptureBytes = 64 * 1024;
+        let stdoutBytes = 0;
+        let stderrBytes = 0;
+        child.stdout?.on("data", (chunk) => {
+            process.stdout.write(chunk);
+            if (stdoutBytes < maxCaptureBytes) {
+                stdoutChunks.push(chunk);
+                stdoutBytes += chunk.length;
+            }
+        });
+        child.stderr?.on("data", (chunk) => {
+            process.stderr.write(chunk);
+            if (stderrBytes < maxCaptureBytes) {
+                stderrChunks.push(chunk);
+                stderrBytes += chunk.length;
+            }
+        });
         child.on("error", reject);
         child.on("exit", (code) => {
             if (code === 0)
-                resolve();
-            else
-                reject(new Error(`Command failed (${code}): ${command}`));
+                return resolve();
+            const stdout = Buffer.concat(stdoutChunks).toString("utf8");
+            const stderr = Buffer.concat(stderrChunks).toString("utf8");
+            const details = [
+                stdout.trim() ? `stdout:\n${stdout.trim()}` : "",
+                stderr.trim() ? `stderr:\n${stderr.trim()}` : "",
+            ]
+                .filter(Boolean)
+                .join("\n\n");
+            reject(new Error(details
+                ? `Command failed (${code}): ${command}\n\n${details}`
+                : `Command failed (${code}): ${command}`));
         });
     });
 }

package/dist/lib/sources.js

@@ -2,6 +2,7 @@ import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import { x as untar } from "tar";
+import { runShellCommand } from "./commands.js";
 export async function resolveSource(source) {
     if (source.startsWith("http://") || source.startsWith("https://")) {
         return await downloadUrlToTempFile(source);
@@ -30,6 +31,34 @@ async function downloadUrlToTempFile(url) {
 // If <path> points to a directory, returns kind=dir.
 async function downloadGitHubToTemp(source) {
     const parsed = parseGitHubSource(source);
+    const transport = (process.env.HARBOR_TEMPLATER_GITHUB_TRANSPORT ?? "auto")
+        .trim()
+        .toLowerCase();
+    if (transport !== "auto" && transport !== "tarball" && transport !== "git") {
+        throw new Error(`Invalid HARBOR_TEMPLATER_GITHUB_TRANSPORT: ${process.env.HARBOR_TEMPLATER_GITHUB_TRANSPORT}. Expected auto|tarball|git.`);
+    }
+    if (transport === "tarball") {
+        return await downloadGitHubTarballToTemp(parsed);
+    }
+    if (transport === "git") {
+        return await downloadGitHubViaGitToTemp(parsed);
+    }
+    // auto
+    try {
+        return await downloadGitHubTarballToTemp(parsed);
+    }
+    catch (error) {
+        // Private repos via codeload typically return 404 (and sometimes 403).
+        // In those cases, fall back to git so the user's local credentials are used.
+        const message = String(error.message ?? error);
+        if (message.includes(" 404 ") || message.includes(" 403 ")) {
+            return await downloadGitHubViaGitToTemp(parsed);
+        }
+        throw error;
+    }
+}
+async function downloadGitHubTarballToTemp(parsed) {
+    const subpath = normalizeGitHubSubpath(parsed.subpath);
     const tarballUrl = `https://codeload.github.com/${parsed.owner}/${parsed.repo}/tar.gz/${parsed.ref}`;
     const response = await fetch(tarballUrl);
     if (!response.ok) {
@@ -50,12 +79,75 @@ async function downloadGitHubToTemp(source) {
     if (!firstEntry)
         throw new Error("Downloaded GitHub tarball was empty");
     const root = path.join(extractDir, firstEntry);
-    const candidate = path.join(root, parsed.subpath);
+    const candidate = path.join(root, subpath);
     const stat = await fs.stat(candidate);
     return stat.isDirectory()
         ? { kind: "dir", path: candidate }
         : { kind: "file", path: candidate };
 }
+async function downloadGitHubViaGitToTemp(parsed) {
+    const subpath = normalizeGitHubSubpath(parsed.subpath);
+    const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), "harbor-templater-gh-git-"));
+    const repoDir = path.join(tmpDir, "repo");
+    const extractDir = path.join(tmpDir, "extract");
+    await fs.mkdir(repoDir, { recursive: true });
+    await fs.mkdir(extractDir, { recursive: true });
+    const httpsUrl = `https://github.com/${parsed.owner}/${parsed.repo}.git`;
+    const sshUrl = `git@github.com:${parsed.owner}/${parsed.repo}.git`;
+    const preferred = (process.env.HARBOR_TEMPLATER_GITHUB_CLONE_PROTOCOL ?? "")
+        .trim()
+        .toLowerCase();
+    const urls = preferred === "ssh"
+        ? [sshUrl, httpsUrl]
+        : preferred === "https" || preferred === ""
+            ? [httpsUrl, sshUrl]
+            : (() => {
+                throw new Error(`Invalid HARBOR_TEMPLATER_GITHUB_CLONE_PROTOCOL: ${process.env.HARBOR_TEMPLATER_GITHUB_CLONE_PROTOCOL}. Expected https|ssh.`);
+            })();
+    await runShellCommand("git init", repoDir);
+    let lastError;
+    for (const [idx, url] of urls.entries()) {
+        try {
+            if (idx === 0) {
+                await runShellCommand(`git remote add origin ${escapeShellArg(url)}`, repoDir);
+            }
+            else {
+                await runShellCommand(`git remote set-url origin ${escapeShellArg(url)}`, repoDir);
+            }
+            // Fetch only what's needed for the requested ref.
+            await runShellCommand(`git fetch --depth 1 origin ${escapeShellArg(parsed.ref)}`, repoDir);
+            const archivePath = path.join(tmpDir, "archive.tar");
+            await runShellCommand(`git archive --format=tar --output=${escapeShellArg(archivePath)} FETCH_HEAD ${escapeShellArg(subpath)}`, repoDir);
+            await untar({ file: archivePath, cwd: extractDir });
+            const candidate = path.join(extractDir, subpath);
+            const stat = await fs.stat(candidate);
+            return stat.isDirectory()
+                ? { kind: "dir", path: candidate }
+                : { kind: "file", path: candidate };
+        }
+        catch (error) {
+            lastError = error;
+        }
+    }
+    throw new Error(`Failed to fetch GitHub source via git for ${parsed.owner}/${parsed.repo}#${parsed.ref}:${subpath}. Ensure you have access to the repo and that your git credentials (credential helper / SSH agent) are configured.\n\n${String(lastError?.message ?? lastError)}`);
+}
+function normalizeGitHubSubpath(input) {
+    const cleaned = input.replaceAll("\\\\", "/").trim();
+    if (cleaned.length === 0)
+        throw new Error("GitHub source path cannot be empty");
+    if (cleaned.includes("\u0000"))
+        throw new Error("GitHub source path contains invalid characters");
+    if (path.posix.isAbsolute(cleaned))
+        throw new Error("GitHub source path must be relative");
+    const segments = cleaned.split("/");
+    if (segments.some((s) => s === ".."))
+        throw new Error("GitHub source path must not contain '..'");
+    return cleaned;
+}
+function escapeShellArg(value) {
+    // Minimal POSIX-style escaping (works on macOS/Linux shells; Windows uses separate .cmd entrypoints).
+    return `'${value.replaceAll("'", "'\\''")}'`;
+}
 function parseGitHubSource(input) {
     const trimmed = input.slice("github:".length);
     const hashIdx = trimmed.indexOf("#");

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

@@ -1,4 +1,5 @@
 export type JSONTemplate = {
+    $schema?: string;
     author?: string;
     description?: string;
     name: string;

package/oclif.manifest.json

@@ -90,5 +90,5 @@
       ]
     }
   },
-  "version": "1.0.0"
+  "version": "1.2.0"
 }

package/package.json

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