@mongez/pkgist 1.0.0

package/src/files/package-json.ts

@@ -0,0 +1,191 @@
+import path from "path";
+import { readFile, writeFile } from "./file-manager.js";
+import { joinPath } from "../utils/paths.js";
+import { wrapError } from "../utils/errors.js";
+import type { PackageBase } from "../types/index.js";
+
+// Fields kept verbatim from the source package.json into the build package.json.
+const KEPT_FIELDS = [
+  "name",
+  "description",
+  "keywords",
+  "author",
+  "license",
+  "repository",
+  "homepage",
+  "bugs",
+  "dependencies",
+  "peerDependencies",
+  "sideEffects",
+  "bin",
+  "engines",
+] as const;
+
+export type SourcePackageJson = Record<string, unknown> & {
+  version: string;
+  dependencies?: Record<string, string>;
+  peerDependencies?: Record<string, string>;
+};
+
+/**
+ * Read and parse the package.json at <packageRoot>/package.json.
+ * Throws a BundlerError if the file is missing or malformed.
+ */
+export function readSourcePackageJson(
+  packageRoot: string,
+  packageName: string,
+): SourcePackageJson {
+  const pkgPath = joinPath(packageRoot, "package.json");
+  let raw: string;
+  try {
+    raw = readFile(pkgPath, packageName);
+  } catch {
+    throw wrapError(
+      "read-package-json",
+      packageName,
+      new Error(`package.json not found at ${pkgPath}`),
+    );
+  }
+
+  try {
+    const parsed = JSON.parse(raw) as SourcePackageJson;
+    if (!parsed.version) {
+      throw new Error(`package.json at ${pkgPath} is missing "version" field`);
+    }
+    return parsed;
+  } catch (err) {
+    throw wrapError("parse-package-json", packageName, err);
+  }
+}
+
+/**
+ * Write the new version back into the source package.json.
+ */
+export function writeSourceVersion(
+  packageRoot: string,
+  packageName: string,
+  newVersion: string,
+): void {
+  const pkgPath = joinPath(packageRoot, "package.json");
+  const raw = readFile(pkgPath, packageName);
+  const parsed = JSON.parse(raw) as Record<string, unknown>;
+  parsed.version = newVersion;
+  writeFile(pkgPath, JSON.stringify(parsed, null, 2) + "\n", packageName);
+}
+
+/**
+ * Build and write the clean package.json for the build output directory.
+ */
+export function writeBuildPackageJson(
+  pkg: PackageBase,
+  sourceJson: SourcePackageJson,
+  buildPath: string,
+  newVersion: string,
+): void {
+  const formats = pkg.formats ?? ["esm", "cjs"];
+  const hasEsm = formats.includes("esm");
+  const hasCjs = formats.includes("cjs");
+  const esmOnly = hasEsm && !hasCjs;
+
+  // When preserveModules is on (the default), tsdown keeps one file per source
+  // module and uses native extensions (.mjs/.cjs) so internal cross-file imports
+  // resolve correctly. When bundling, everything is renamed to .js for simplicity.
+  const preserve = pkg.preserveModules !== false;
+  const esmExt  = preserve ? ".mjs"   : ".js";
+  const cjsExt  = preserve ? ".cjs"   : ".js";
+  const esmDts  = preserve ? ".d.mts" : ".d.ts";
+  const cjsDts  = preserve ? ".d.cts" : ".d.ts";
+
+  // Determine entry base names from entries config
+  const rawEntries = pkg.entries ?? ["index.ts"];
+  const entryList = Array.isArray(rawEntries) ? rawEntries : [rawEntries];
+
+  /**
+   * Convert an entry path (relative to srcDir) into:
+   *   basePath   — path without extension, used to build file paths  (e.g. "cli/index")
+   *   exportPath — the key in the exports map                        (e.g. "./cli")
+   *
+   * When the basename is "index" the directory becomes the export path so that
+   * `cli/index.ts` maps to `"./cli"` and `index.ts` maps to `"."`.
+   */
+  function entryPaths(entry: string): { basePath: string; exportPath: string } {
+    const basePath = entry.replace(/\.tsx?$/, "");
+    const parts = basePath.split("/");
+    const last = parts[parts.length - 1];
+    let exportPath: string;
+    if (last === "index") {
+      const dir = parts.slice(0, -1).join("/");
+      exportPath = dir ? `./${dir}` : ".";
+    } else {
+      exportPath = `./${basePath}`;
+    }
+    return { basePath, exportPath };
+  }
+
+  // Primary entry drives `main` / `module` / `types` fields.
+  const { basePath: primaryBase } = entryPaths(entryList[0]!);
+
+  // Build the full exports map — one condition block per entry.
+  const exportsMap: Record<string, unknown> = {};
+
+  for (const entry of entryList) {
+    const { basePath, exportPath } = entryPaths(entry);
+    const conditions: Record<string, unknown> = {};
+
+    if (hasEsm) {
+      conditions["import"] = {
+        types:   `./esm/${basePath}${esmDts}`,
+        default: `./esm/${basePath}${esmExt}`,
+      };
+    }
+    if (hasCjs) {
+      // When preserveModules is on, CJS is built without DTS to avoid a rolldown bug.
+      // TypeScript resolves types correctly from the ESM declarations via the exports map.
+      const cjsTypes = preserve && hasEsm
+        ? `./esm/${basePath}${esmDts}`
+        : `./cjs/${basePath}${cjsDts}`;
+      conditions["require"] = {
+        types:   cjsTypes,
+        default: `./cjs/${basePath}${cjsExt}`,
+      };
+    }
+
+    exportsMap[exportPath] = conditions;
+  }
+
+  const output: Record<string, unknown> = {};
+
+  // Copy allowed fields from source
+  for (const field of KEPT_FIELDS) {
+    if (field in sourceJson && sourceJson[field] !== undefined) {
+      output[field] = sourceJson[field];
+    }
+  }
+
+  // Override name / version
+  output["name"] = pkg.name;
+  output["version"] = newVersion;
+
+  if (esmOnly) {
+    output["type"] = "module";
+  }
+
+  // Entry points
+  const mainType = pkg.mainType ?? "cjs";
+  if (mainType === "esm" || esmOnly) {
+    output["main"] = `./esm/${primaryBase}${esmExt}`;
+  } else {
+    output["main"] = `./cjs/${primaryBase}${cjsExt}`;
+  }
+
+  if (hasEsm) {
+    output["module"] = `./esm/${primaryBase}${esmExt}`;
+  }
+
+  output["types"] = `./esm/${primaryBase}${esmDts}`;
+
+  output["exports"] = exportsMap;
+
+  const pkgPath = joinPath(buildPath, "package.json");
+  writeFile(pkgPath, JSON.stringify(output, null, 2) + "\n", pkg.name);
+}

package/src/git/index.ts

@@ -0,0 +1 @@
+export { gitCommitTagPush, isGitRepo, currentBranch } from "./operations.js";

package/src/git/operations.ts

@@ -0,0 +1,87 @@
+import simpleGit, { SimpleGit } from "simple-git";
+import fs from "fs";
+import path from "path";
+import { joinPath } from "../utils/paths.js";
+import { wrapError } from "../utils/errors.js";
+import { logger } from "../utils/logger.js";
+
+/**
+ * Returns true if the given directory is inside a git repository.
+ */
+export async function isGitRepo(dir: string): Promise<boolean> {
+  try {
+    const git: SimpleGit = simpleGit(dir);
+    const result = await git.checkIsRepo();
+    return result;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Perform git operations for a package after a successful build:
+ * 1. git add -A (in the package root)
+ * 2. git commit -m <message>
+ * 3. git push origin <branch>
+ * 4. git tag v<version>
+ * 5. git push origin <tag>
+ */
+export async function gitCommitTagPush(
+  packageRoot: string,
+  packageName: string,
+  version: string,
+  commitMessage: string,
+  branch: string,
+  dryRun: boolean,
+): Promise<void> {
+  const isRepo = await isGitRepo(packageRoot);
+  if (!isRepo) {
+    logger.warn(`[git] ${packageName}: directory is not a git repo — skipping git operations`);
+    return;
+  }
+
+  const tag = `v${version}`;
+  logger.step(`[git] ${packageName}: commit "${commitMessage}", tag ${tag}, push to ${branch}`);
+
+  if (dryRun) {
+    logger.info(`[dry-run] git add + commit "${commitMessage}" + tag ${tag} + push`);
+    return;
+  }
+
+  const git: SimpleGit = simpleGit(packageRoot);
+
+  try {
+    // Stage all changes
+    await git.add("-A");
+
+    // Commit
+    await git.commit(commitMessage);
+
+    // Push to remote
+    await git.push("origin", branch);
+
+    // Tag
+    await git.addTag(tag);
+
+    // Push tags
+    await git.pushTags("origin");
+
+    logger.success(`[git] ${packageName}: pushed ${branch}, tagged ${tag}`);
+  } catch (err) {
+    throw wrapError("git-operations", packageName, err);
+  }
+}
+
+/**
+ * Resolve the current branch name in the given directory.
+ * Falls back to "main" if the directory is not a git repo.
+ */
+export async function currentBranch(dir: string): Promise<string> {
+  try {
+    const git: SimpleGit = simpleGit(dir);
+    const branch = await git.revparse(["--abbrev-ref", "HEAD"]);
+    return branch.trim() || "main";
+  } catch {
+    return "main";
+  }
+}

package/src/index.ts

@@ -0,0 +1,26 @@
+// Public API — used by builder config files via: import { defineConfig } from "@mongez/bundler"
+export { defineConfig } from "./config/define-config.js";
+
+// Type exports
+export type {
+  PackageBase,
+  StandalonePackage,
+  FamilyPackage,
+  Family,
+  BundlerConfig,
+  BuilderSettings,
+  BuildOptions,
+} from "./types/index.js";
+
+// Re-export loadConfig for programmatic usage
+export { loadConfig, findDefaultConfigPath } from "./config/load-config.js";
+export type { LoadedConfig } from "./config/load-config.js";
+
+// Programmatic build API
+export { buildPackage } from "./build/package-builder.js";
+export type { BuildResult } from "./build/package-builder.js";
+export { buildFamily } from "./build/family-builder.js";
+export { runParallel } from "./build/parallel-builder.js";
+
+// Version utilities
+export { resolveVersion } from "./version/increment.js";

package/src/publish/index.ts

@@ -0,0 +1 @@
+export { publishPackage } from "./npm-publisher.js";

package/src/publish/npm-publisher.ts

@@ -0,0 +1,36 @@
+import { exec } from "../utils/exec.js";
+import { logger } from "../utils/logger.js";
+import type { PackageBase } from "../types/index.js";
+
+/**
+ * Run `npm publish` from the build output directory.
+ */
+export async function publishPackage(
+  pkg: PackageBase,
+  buildPath: string,
+  dryRun: boolean,
+): Promise<void> {
+  if (pkg.publish === false) {
+    logger.info(`[publish] ${pkg.name}: publish=false, skipping`);
+    return;
+  }
+
+  const access = pkg.access ?? "public";
+
+  if (dryRun) {
+    logger.info(`[dry-run] npm publish --access ${access} from ${buildPath}`);
+    return;
+  }
+
+  logger.step(`Publishing ${pkg.name}@... to npm (access: ${access})`);
+
+  await exec(
+    "npm-publish",
+    pkg.name,
+    "npm",
+    ["publish", "--access", access],
+    buildPath,
+  );
+
+  logger.success(`Published ${pkg.name}`);
+}

package/src/types/config.ts

@@ -0,0 +1,33 @@
+import type { StandalonePackage, Family } from "./package.js";
+
+export interface BuilderSettings {
+  /** Maximum number of packages compiled in parallel. default: 4 */
+  concurrency?: number;
+  /**
+   * Directory where versioned build artifacts are stored.
+   * Relative path is resolved from the config file location.
+   * e.g. "../builds" → <configDir>/../builds
+   */
+  buildDir: string;
+  /**
+   * Directory where source snapshots are copied before compilation.
+   * Relative path is resolved from the config file location.
+   * Optional — if absent, no source backup is performed.
+   */
+  sourcesDir?: string;
+}
+
+export interface BundlerConfig {
+  settings: BuilderSettings;
+  standalone?: StandalonePackage[];
+  families?: Family[];
+}
+
+/** Runtime options injected by the CLI into every build operation */
+export interface BuildOptions {
+  dryRun: boolean;
+  noPublish: boolean;
+  noGit: boolean;
+  concurrency?: number;
+  configPath: string;
+}

package/src/types/index.ts

@@ -0,0 +1,2 @@
+export type { PackageBase, StandalonePackage, FamilyPackage, Family } from "./package.js";
+export type { BundlerConfig, BuilderSettings, BuildOptions } from "./config.js";

package/src/types/package.ts

@@ -0,0 +1,81 @@
+export interface PackageBase {
+  /** npm package name, e.g. "@mongez/reinforcements" */
+  name: string;
+  /** relative path to package root, resolved from the builder config file location */
+  root: string;
+  /** package type — affects jsx transform for react packages */
+  type?: "typescript" | "react";
+  /** primary output format — determines "main" field in built package.json */
+  mainType?: "cjs" | "esm";
+  /** output formats to produce. default: ["esm", "cjs"] */
+  formats?: ("esm" | "cjs")[];
+  /** entry files inside srcDir. default: ["index.ts"] */
+  entries?: string | string[];
+  /** source directory relative to root. default: "src" */
+  srcDir?: string;
+  /** minify output. default: false */
+  minify?: boolean;
+  /** emit sourcemaps. default: true */
+  sourcemap?: boolean;
+  /** emit d.ts declarations. default: true */
+  dts?: boolean;
+  /**
+   * Preserve the original module structure in the output instead of bundling
+   * everything into a single index.js.
+   *
+   * When true, each source file becomes its own output file (e.g.
+   * `src/array/chunk.ts` → `esm/array/chunk.mjs`). Produces much more useful
+   * stack traces because file names are preserved.
+   *
+   * When false, all sources are bundled into a single `esm/index.js` +
+   * `cjs/index.js`. Useful for tiny single-file packages.
+   *
+   * @default true
+   */
+  preserveModules?: boolean;
+  /**
+   * Files to copy into the build directory.
+   * A plain string copies from the package root to the build root with the same name.
+   * A tuple [src, dest] copies src (relative to package root) to dest (relative to build dir).
+   */
+  clone?: (string | [string, string])[];
+  /** run npm publish after build. default: true */
+  publish?: boolean;
+  /** npm access scope. default: "public" */
+  access?: "public" | "restricted";
+  /** git commit message. if absent, git operations are skipped entirely */
+  commit?: string;
+  /** git branch to push to. default: current branch */
+  branch?: string;
+}
+
+export interface StandalonePackage extends PackageBase {
+  /**
+   * Version strategy:
+   * - "auto" / "patch" → patch-bump the current version from source package.json
+   * - "minor"          → minor-bump (x.Y.0)
+   * - "major"          → major-bump (X.0.0)
+   * - semver string    → use exactly this version string
+   * - omitted          → defaults to "auto"
+   */
+  version?: "auto" | "patch" | "minor" | "major" | string;
+}
+
+export interface FamilyPackage extends PackageBase {
+  // No per-package version — version comes from the family definition
+}
+
+export interface Family {
+  /** Identifier used with `build:family <name>` */
+  name: string;
+  /**
+   * Version strategy for all packages in this family.
+   * - "auto"  → patch-bump from the first package's current version
+   * - string  → use exactly this version string
+   * default: "auto"
+   */
+  version?: "auto" | "patch" | "minor" | "major" | string;
+  /** git commit message that overrides per-package commit */
+  commit?: string;
+  packages: FamilyPackage[];
+}

package/src/utils/errors.ts

@@ -0,0 +1,40 @@
+/** Base error class for all bundler errors. Carries a step name for structured logging. */
+export class BundlerError extends Error {
+  constructor(
+    public readonly step: string,
+    public readonly packageName: string,
+    message: string,
+    public readonly cause?: unknown,
+  ) {
+    super(message);
+    this.name = "BundlerError";
+    if (cause instanceof Error && cause.stack) {
+      this.stack = `${this.stack}\nCaused by: ${cause.stack}`;
+    }
+  }
+}
+
+/** Wrap any thrown value into a BundlerError with context. */
+export function wrapError(
+  step: string,
+  packageName: string,
+  error: unknown,
+): BundlerError {
+  if (error instanceof BundlerError) return error;
+  const msg =
+    error instanceof Error
+      ? error.message
+      : typeof error === "string"
+        ? error
+        : JSON.stringify(error);
+  return new BundlerError(step, packageName, `[${step}] ${packageName}: ${msg}`, error);
+}
+
+/** Throw a wrapped error immediately. */
+export function failWith(
+  step: string,
+  packageName: string,
+  error: unknown,
+): never {
+  throw wrapError(step, packageName, error);
+}

package/src/utils/exec.ts

@@ -0,0 +1,58 @@
+import { execa } from "execa";
+import { wrapError } from "./errors.js";
+
+export interface ExecResult {
+  stdout: string;
+  stderr: string;
+  exitCode: number;
+}
+
+/**
+ * Run a shell command and return stdout/stderr.
+ * Throws a BundlerError on non-zero exit.
+ */
+export async function exec(
+  step: string,
+  packageName: string,
+  command: string,
+  args: string[],
+  cwd?: string,
+): Promise<ExecResult> {
+  try {
+    const result = await execa(command, args, {
+      cwd,
+      all: true,
+      reject: false,
+    });
+    if (result.exitCode !== 0) {
+      const combined = result.all ?? result.stderr ?? "";
+      throw new Error(
+        `Command "${command} ${args.join(" ")}" exited with code ${result.exitCode}.\n${combined}`,
+      );
+    }
+    return {
+      stdout: result.stdout ?? "",
+      stderr: result.stderr ?? "",
+      exitCode: result.exitCode,
+    };
+  } catch (err) {
+    throw wrapError(step, packageName, err);
+  }
+}
+
+/**
+ * Run a command and ignore its output.  Does NOT throw on non-zero exit.
+ * Useful for optional operations (e.g. `git tag -d`).
+ */
+export async function execSilent(
+  command: string,
+  args: string[],
+  cwd?: string,
+): Promise<number> {
+  try {
+    const result = await execa(command, args, { cwd, reject: false });
+    return result.exitCode ?? 0;
+  } catch {
+    return 1;
+  }
+}

package/src/utils/index.ts

@@ -0,0 +1,4 @@
+export * from "./errors.js";
+export * from "./logger.js";
+export * from "./exec.js";
+export * from "./paths.js";

package/src/utils/logger.ts

@@ -0,0 +1,44 @@
+import chalk from "chalk";
+
+export type LogLevel = "info" | "success" | "warn" | "error" | "debug" | "step";
+
+let _verbose = false;
+
+export function setVerbose(v: boolean): void {
+  _verbose = v;
+}
+
+export function log(level: LogLevel, message: string): void {
+  const ts = new Date().toISOString().replace("T", " ").replace("Z", "");
+  switch (level) {
+    case "info":
+      console.log(chalk.cyan(`[${ts}] INFO  ${message}`));
+      break;
+    case "success":
+      console.log(chalk.green(`[${ts}] OK    ${message}`));
+      break;
+    case "warn":
+      console.warn(chalk.yellow(`[${ts}] WARN  ${message}`));
+      break;
+    case "error":
+      console.error(chalk.red(`[${ts}] ERROR ${message}`));
+      break;
+    case "step":
+      console.log(chalk.blueBright(`[${ts}] STEP  ${message}`));
+      break;
+    case "debug":
+      if (_verbose) {
+        console.log(chalk.gray(`[${ts}] DEBUG ${message}`));
+      }
+      break;
+  }
+}
+
+export const logger = {
+  info: (msg: string) => log("info", msg),
+  success: (msg: string) => log("success", msg),
+  warn: (msg: string) => log("warn", msg),
+  error: (msg: string) => log("error", msg),
+  step: (msg: string) => log("step", msg),
+  debug: (msg: string) => log("debug", msg),
+};

package/src/utils/paths.ts

@@ -0,0 +1,48 @@
+import path from "path";
+
+/** Normalise any path to forward-slash form (Windows-safe). */
+export function toForwardSlash(p: string): string {
+  return p.replace(/\\/g, "/");
+}
+
+/** Join path segments and normalise the result to forward slashes. */
+export function joinPath(...segments: string[]): string {
+  return toForwardSlash(path.join(...segments));
+}
+
+/** Resolve an absolute path from segments and normalise to forward slashes. */
+export function resolvePath(...segments: string[]): string {
+  return toForwardSlash(path.resolve(...segments));
+}
+
+/**
+ * Given a package name like "@mongez/reinforcements",
+ * return just the scoped part without the scope prefix: "reinforcements".
+ */
+export function scopelessName(packageName: string): string {
+  const slash = packageName.indexOf("/");
+  return slash === -1 ? packageName : packageName.slice(slash + 1);
+}
+
+/**
+ * Build the versioned build output path:
+ *   <buildDir>/<scopeless-name>/<version>/
+ */
+export function buildOutputPath(
+  buildDir: string,
+  packageName: string,
+  version: string,
+): string {
+  return joinPath(buildDir, scopelessName(packageName), version);
+}
+
+/**
+ * Build the sources snapshot path:
+ *   <sourcesDir>/<scopeless-name>/
+ */
+export function sourceSnapshotPath(
+  sourcesDir: string,
+  packageName: string,
+): string {
+  return joinPath(sourcesDir, scopelessName(packageName));
+}