@crustjs/create 0.0.1

package/dist/index.d.ts

@@ -0,0 +1,195 @@
+/**
+* Interpolate `{{var}}` placeholders in a string with values from a context object.
+*
+* Only simple `{{identifier}}` patterns are replaced — no conditionals, loops,
+* or helpers. Whitespace inside the braces is tolerated (e.g. `{{ name }}`).
+* Missing variables are left untouched.
+*
+* @param content - The template string containing `{{var}}` placeholders.
+* @param context - A flat map of variable names to replacement values.
+* @returns The interpolated string.
+*
+* @example
+* ```ts
+* interpolate("Hello, {{name}}!", { name: "world" });
+* // => "Hello, world!"
+* ```
+*/
+declare function interpolate(content: string, context: Record<string, string>): string;
+/**
+* Options for the {@link scaffold} function.
+*
+* @example
+* ```ts
+* const options: ScaffoldOptions = {
+*   template: "../templates/base",
+*   dest: "./my-project",
+*   importMeta: import.meta.url,
+*   context: { name: "my-app", description: "A cool CLI" },
+*   conflict: "abort",
+* };
+* ```
+*/
+interface ScaffoldOptions {
+	/** Relative path to the template directory (resolved against `importMeta`). */
+	readonly template: string;
+	/** Absolute or relative path to the destination directory. */
+	readonly dest: string;
+	/**
+	* The `import.meta.url` of the calling module.
+	* Used to resolve the template path relative to the caller.
+	*/
+	readonly importMeta: string;
+	/**
+	* Variables to interpolate into template file contents.
+	* Keys map to `{{key}}` placeholders in template files.
+	*/
+	readonly context: Record<string, string>;
+	/**
+	* How to handle an existing non-empty destination directory.
+	*
+	* - `"abort"` — throw an error (default)
+	* - `"overwrite"` — proceed and overwrite existing files
+	*
+	* @default "abort"
+	*/
+	readonly conflict?: "abort" | "overwrite";
+}
+/**
+* Result returned by the {@link scaffold} function.
+*/
+interface ScaffoldResult {
+	/** List of all written file paths, relative to the destination directory. */
+	readonly files: readonly string[];
+}
+/**
+* A declarative step to run after scaffolding completes.
+*
+* Steps are executed sequentially in array order by {@link runSteps}.
+*
+* @example
+* ```ts
+* const steps: PostScaffoldStep[] = [
+*   { type: "install" },
+*   { type: "git-init", commit: "Initial commit" },
+*   { type: "open-editor" },
+* ];
+* ```
+*/
+type PostScaffoldStep = {
+	readonly type: "install";
+} | {
+	readonly type: "git-init";
+	readonly commit?: string;
+} | {
+	readonly type: "open-editor";
+} | {
+	readonly type: "command";
+	readonly cmd: string;
+	readonly cwd?: string;
+};
+/**
+* Copy a template directory to a destination, applying variable interpolation
+* and dotfile renaming.
+*
+* Templates are resolved relative to the calling module's `import.meta.url`,
+* so templates bundled inside published npm packages resolve correctly
+* regardless of install location.
+*
+* Call `scaffold()` multiple times to layer/compose templates — for example,
+* a base template followed by a TypeScript-specific overlay.
+*
+* @param options - Scaffold configuration.
+* @returns The list of all written file paths, relative to the destination directory.
+* @throws When `conflict` is `"abort"` and the destination is a non-empty directory.
+*
+* @example
+* ```ts
+* import { scaffold } from "@crustjs/create";
+*
+* const result = await scaffold({
+*   template: "../templates/base",
+*   dest: "./my-project",
+*   importMeta: import.meta.url,
+*   context: { name: "my-app", description: "A cool CLI" },
+* });
+*
+* console.log("Created files:", result.files);
+* ```
+*/
+declare function scaffold(options: ScaffoldOptions): Promise<ScaffoldResult>;
+/**
+* Execute an array of post-scaffold steps sequentially.
+*
+* Each step is a declarative object describing an action to perform after
+* file scaffolding is complete. Steps run in array order; if any step fails,
+* the error propagates immediately (remaining steps are skipped).
+*
+* @param steps - Array of {@link PostScaffoldStep} objects to execute.
+* @param cwd - The working directory for steps (typically the scaffold dest).
+*
+* @example
+* ```ts
+* await runSteps(
+*   [
+*     { type: "install" },
+*     { type: "git-init", commit: "Initial commit" },
+*     { type: "open-editor" },
+*   ],
+*   "./my-project",
+* );
+* ```
+*/
+declare function runSteps(steps: PostScaffoldStep[], cwd: string): Promise<void>;
+/**
+* Detect the package manager for a project directory.
+*
+* Detection strategy (first match wins):
+* 1. Check for lockfiles in `cwd` (bun.lock/bun.lockb → pnpm-lock.yaml → yarn.lock → package-lock.json)
+* 2. Parse the `npm_config_user_agent` environment variable
+* 3. Default to `"npm"`
+*
+* @param cwd - The directory to check for lockfiles. Defaults to `process.cwd()`.
+* @returns The detected package manager name: `"bun"`, `"pnpm"`, `"yarn"`, or `"npm"`.
+*
+* @example
+* ```ts
+* const pm = detectPackageManager("./my-project");
+* // => "bun" (if bun.lock exists)
+* ```
+*/
+declare function detectPackageManager(cwd?: string): string;
+/**
+* Check whether `git` is installed and available on the system PATH.
+*
+* Runs `git --version` and returns `true` if it exits successfully.
+*
+* @returns `true` if git is available, `false` otherwise.
+*
+* @example
+* ```ts
+* if (isGitInstalled()) {
+*   console.log("Git is available");
+* }
+* ```
+*/
+declare function isGitInstalled(): boolean;
+/**
+* Read the current git user's name and email from `git config`.
+*
+* Returns `null` for either field if it is not configured.
+*
+* @returns An object with `name` and `email` (each `string | null`).
+*
+* @example
+* ```ts
+* const user = getGitUser();
+* console.log(user.name);  // "Jane Doe" or null
+* console.log(user.email); // "jane@example.com" or null
+* ```
+*/
+declare function getGitUser(): {
+	name: string | null;
+	email: string | null;
+};
+export { scaffold, runSteps, isGitInstalled, interpolate, getGitUser, detectPackageManager, ScaffoldResult, ScaffoldOptions, PostScaffoldStep };

package/dist/index.js

@@ -0,0 +1,249 @@
+// @bun
+// src/interpolate.ts
+function interpolate(content, context) {
+  return content.replace(/\{\{\s*(\w+)\s*\}\}/g, (match, key) => {
+    if (key in context) {
+      return context[key];
+    }
+    return match;
+  });
+}
+// src/scaffold.ts
+import {
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  statSync,
+  writeFileSync
+} from "fs";
+import { dirname, join, relative, resolve } from "path";
+import { fileURLToPath } from "url";
+
+// src/isBinary.ts
+function isBinary(buffer) {
+  const length = Math.min(buffer.length, 8192);
+  for (let i = 0;i < length; i++) {
+    if (buffer[i] === 0) {
+      return true;
+    }
+  }
+  return false;
+}
+
+// src/scaffold.ts
+function walkDir(dir) {
+  const files = [];
+  const entries = readdirSync(dir);
+  for (const entry of entries) {
+    const fullPath = join(dir, entry);
+    const stat = statSync(fullPath);
+    if (stat.isDirectory()) {
+      files.push(...walkDir(fullPath));
+    } else {
+      files.push(fullPath);
+    }
+  }
+  return files;
+}
+function renameDotfile(relativePath) {
+  const dir = dirname(relativePath);
+  const base = relativePath.slice(dir === "." ? 0 : dir.length + 1);
+  if (base.startsWith("_") && !base.startsWith("__")) {
+    const renamed = `.${base.slice(1)}`;
+    return dir === "." ? renamed : join(dir, renamed);
+  }
+  return relativePath;
+}
+function isNonEmptyDir(dirPath) {
+  if (!existsSync(dirPath)) {
+    return false;
+  }
+  const stat = statSync(dirPath);
+  if (!stat.isDirectory()) {
+    return false;
+  }
+  const entries = readdirSync(dirPath);
+  return entries.length > 0;
+}
+async function scaffold(options) {
+  const { template, dest, importMeta, context, conflict = "abort" } = options;
+  const templateDir = fileURLToPath(new URL(template, importMeta));
+  const destDir = resolve(dest);
+  if (conflict === "abort" && isNonEmptyDir(destDir)) {
+    throw new Error(`Destination directory "${destDir}" already exists and is non-empty. Use conflict: "overwrite" to proceed.`);
+  }
+  const templateFiles = walkDir(templateDir);
+  const writtenFiles = [];
+  for (const absolutePath of templateFiles) {
+    const relFromTemplate = relative(templateDir, absolutePath);
+    const destRelPath = renameDotfile(relFromTemplate);
+    const destFilePath = join(destDir, destRelPath);
+    mkdirSync(dirname(destFilePath), { recursive: true });
+    const buffer = readFileSync(absolutePath);
+    if (isBinary(buffer)) {
+      writeFileSync(destFilePath, buffer);
+    } else {
+      const content = buffer.toString("utf-8");
+      const interpolated = interpolate(content, context);
+      writeFileSync(destFilePath, interpolated, "utf-8");
+    }
+    writtenFiles.push(destRelPath);
+  }
+  return { files: writtenFiles };
+}
+// src/utils.ts
+import { existsSync as existsSync2 } from "fs";
+import { join as join2 } from "path";
+var LOCKFILE_MAP = [
+  ["bun.lock", "bun"],
+  ["bun.lockb", "bun"],
+  ["pnpm-lock.yaml", "pnpm"],
+  ["yarn.lock", "yarn"],
+  ["package-lock.json", "npm"]
+];
+function detectPackageManager(cwd) {
+  const dir = cwd ?? process.cwd();
+  for (const [lockfile, manager] of LOCKFILE_MAP) {
+    if (existsSync2(join2(dir, lockfile))) {
+      return manager;
+    }
+  }
+  const userAgent = process.env.npm_config_user_agent;
+  if (userAgent) {
+    if (userAgent.startsWith("bun"))
+      return "bun";
+    if (userAgent.startsWith("pnpm"))
+      return "pnpm";
+    if (userAgent.startsWith("yarn"))
+      return "yarn";
+    if (userAgent.startsWith("npm"))
+      return "npm";
+  }
+  return "npm";
+}
+function isGitInstalled() {
+  try {
+    const result = Bun.spawnSync(["git", "--version"]);
+    return result.exitCode === 0;
+  } catch {
+    return false;
+  }
+}
+function getGitUser() {
+  return {
+    name: readGitConfig("user.name"),
+    email: readGitConfig("user.email")
+  };
+}
+function readGitConfig(key) {
+  try {
+    const result = Bun.spawnSync(["git", "config", key]);
+    if (result.exitCode !== 0) {
+      return null;
+    }
+    const value = result.stdout.toString().trim();
+    return value.length > 0 ? value : null;
+  } catch {
+    return null;
+  }
+}
+
+// src/steps.ts
+async function runSteps(steps, cwd) {
+  for (const step of steps) {
+    switch (step.type) {
+      case "install":
+        await runInstall(cwd);
+        break;
+      case "git-init":
+        await runGitInit(cwd, step.commit);
+        break;
+      case "open-editor":
+        await runOpenEditor(cwd);
+        break;
+      case "command":
+        await runCommand(step.cmd, step.cwd ?? cwd);
+        break;
+    }
+  }
+}
+async function runInstall(cwd) {
+  const pm = detectPackageManager(cwd);
+  const proc = Bun.spawn([pm, "install"], {
+    cwd,
+    stdout: "inherit",
+    stderr: "inherit"
+  });
+  const exitCode = await proc.exited;
+  if (exitCode !== 0) {
+    throw new Error(`"${pm} install" exited with code ${exitCode}`);
+  }
+}
+async function runGitInit(cwd, commit) {
+  await spawnChecked(["git", "init"], cwd, "git init");
+  if (commit) {
+    await ensureGitIdentity(cwd);
+    await spawnChecked(["git", "add", "."], cwd, "git add");
+    await spawnChecked(["git", "commit", "-m", commit], cwd, "git commit");
+  }
+}
+async function runOpenEditor(cwd) {
+  const editor = process.env.EDITOR || "code";
+  try {
+    const proc = Bun.spawn([editor, cwd], {
+      stdout: "ignore",
+      stderr: "ignore"
+    });
+    const raceResult = await Promise.race([
+      proc.exited.then((code) => ({ kind: "exited", code })),
+      new Promise((resolve2) => setTimeout(() => resolve2({ kind: "timeout" }), 500))
+    ]);
+    if (raceResult.kind === "exited" && raceResult.code !== 0) {
+      console.warn(`Warning: could not open editor "${editor}" (exit code ${raceResult.code})`);
+    }
+  } catch {
+    console.warn(`Warning: could not open editor "${editor}"`);
+  }
+}
+async function runCommand(cmd, cwd) {
+  const proc = Bun.spawn(["sh", "-c", cmd], {
+    cwd,
+    stdout: "inherit",
+    stderr: "inherit"
+  });
+  const exitCode = await proc.exited;
+  if (exitCode !== 0) {
+    throw new Error(`Command "${cmd}" exited with code ${exitCode}`);
+  }
+}
+async function ensureGitIdentity(cwd) {
+  const hasName = Bun.spawnSync(["git", "config", "user.name"], { cwd }).exitCode === 0;
+  const hasEmail = Bun.spawnSync(["git", "config", "user.email"], { cwd }).exitCode === 0;
+  if (!hasName) {
+    await spawnChecked(["git", "config", "user.name", "Crust"], cwd, "git config user.name");
+  }
+  if (!hasEmail) {
+    await spawnChecked(["git", "config", "user.email", "crust@scaffolded.project"], cwd, "git config user.email");
+  }
+}
+async function spawnChecked(cmd, cwd, label) {
+  const proc = Bun.spawn(cmd, {
+    cwd,
+    stdout: "ignore",
+    stderr: "pipe"
+  });
+  const exitCode = await proc.exited;
+  if (exitCode !== 0) {
+    const stderr = await new Response(proc.stderr).text();
+    throw new Error(`"${label}" failed with exit code ${exitCode}${stderr ? `: ${stderr.trim()}` : ""}`);
+  }
+}
+export {
+  scaffold,
+  runSteps,
+  isGitInstalled,
+  interpolate,
+  getGitUser,
+  detectPackageManager
+};

package/package.json

@@ -0,0 +1,51 @@
+{
+	"name": "@crustjs/create",
+	"version": "0.0.1",
+	"description": "Headless scaffolding engine for building create-xxx tools",
+	"type": "module",
+	"license": "MIT",
+	"author": "chenxin-yan",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/chenxin-yan/crust.git",
+		"directory": "packages/create"
+	},
+	"homepage": "https://crustjs.com",
+	"bugs": {
+		"url": "https://github.com/chenxin-yan/crust/issues"
+	},
+	"keywords": [
+		"cli",
+		"scaffold",
+		"create",
+		"template",
+		"generator",
+		"bun",
+		"typescript"
+	],
+	"files": [
+		"dist"
+	],
+	"exports": {
+		".": {
+			"import": "./dist/index.js",
+			"types": "./dist/index.d.ts"
+		}
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"scripts": {
+		"build": "bunup",
+		"dev": "bunup --watch",
+		"check:types": "tsc --noEmit",
+		"test": "bun test"
+	},
+	"devDependencies": {
+		"@crustjs/config": "0.0.0",
+		"bunup": "^0.16.29"
+	},
+	"peerDependencies": {
+		"typescript": "^5"
+	}
+}