dxcomplete 0.1.0

package/src/init.ts

@@ -0,0 +1,227 @@
+import { copyFile, mkdir, readdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { INSTALL_MANIFEST_PATH, writeInstallManifest } from "./install-manifest.js";
+import { fileExists, resolvePackageRoot } from "./package-root.js";
+import { getUpgradeManagedFiles } from "./upgrade.js";
+
+export type InitOptions = {
+  targetDir: string;
+  force?: boolean;
+  dryRun?: boolean;
+  includeGithubWorkflow?: boolean;
+};
+
+export type InitResult = {
+  targetDir: string;
+  written: string[];
+  skipped: string[];
+  planned: string[];
+};
+
+type CopyOptions = Required<Pick<InitOptions, "force" | "dryRun">>;
+
+export async function initProject(options: InitOptions): Promise<InitResult> {
+  const targetDir = path.resolve(options.targetDir);
+  const force = options.force ?? false;
+  const dryRun = options.dryRun ?? false;
+  const includeGithubWorkflow = options.includeGithubWorkflow ?? true;
+  const packageRoot = await resolvePackageRoot();
+
+  const result: InitResult = {
+    targetDir,
+    written: [],
+    skipped: [],
+    planned: []
+  };
+
+  await copyDirectory(
+    path.join(packageRoot, "docs"),
+    path.join(targetDir, "dxcomplete", "docs"),
+    { force, dryRun },
+    result
+  );
+
+  await copyDirectory(
+    path.join(packageRoot, "templates", "process"),
+    path.join(targetDir, "dxcomplete", "process"),
+    { force, dryRun },
+    result
+  );
+
+  await writeWorkspaceConfig(targetDir, { force, dryRun }, result);
+
+  await copyDirectory(
+    path.join(packageRoot, "templates", "next", "pages"),
+    path.join(targetDir, "pages"),
+    { force, dryRun },
+    result
+  );
+
+  await copyFileIfAvailable(
+    path.join(packageRoot, "templates", "next", "vercel.json"),
+    path.join(targetDir, "vercel.json"),
+    { force, dryRun },
+    result
+  );
+
+  if (includeGithubWorkflow) {
+    await copyDirectory(
+      path.join(packageRoot, "templates", "github", "workflows"),
+      path.join(targetDir, ".github", "workflows"),
+      { force, dryRun },
+      result
+    );
+  }
+
+  await writeScaffoldManifest(packageRoot, targetDir, { force, dryRun }, result);
+
+  return result;
+}
+
+async function writeScaffoldManifest(
+  packageRoot: string,
+  targetDir: string,
+  options: CopyOptions,
+  result: InitResult
+): Promise<void> {
+  const managedFiles = getUpgradeManagedFiles(packageRoot, targetDir);
+  const managedDestinations = new Set(managedFiles.map((file) => file.destinationRelative));
+  const skippedManagedFile = result.skipped.some((file) => managedDestinations.has(file));
+
+  if (skippedManagedFile && !options.force) {
+    result.skipped.push(INSTALL_MANIFEST_PATH);
+    return;
+  }
+
+  if (options.dryRun) {
+    result.planned.push(INSTALL_MANIFEST_PATH);
+    return;
+  }
+
+  await writeInstallManifest(targetDir, managedFiles);
+  result.written.push(INSTALL_MANIFEST_PATH);
+}
+
+async function copyFileIfAvailable(
+  sourcePath: string,
+  destinationPath: string,
+  options: CopyOptions,
+  result: InitResult
+): Promise<void> {
+  if (!(await fileExists(sourcePath))) {
+    return;
+  }
+
+  const relativeDestination = path.relative(result.targetDir, destinationPath);
+  const exists = await fileExists(destinationPath);
+
+  if (exists && !options.force) {
+    result.skipped.push(relativeDestination);
+    return;
+  }
+
+  if (options.dryRun) {
+    result.planned.push(relativeDestination);
+    return;
+  }
+
+  await mkdir(path.dirname(destinationPath), { recursive: true });
+  await copyFile(sourcePath, destinationPath);
+  result.written.push(relativeDestination);
+}
+
+async function writeWorkspaceConfig(
+  targetDir: string,
+  options: CopyOptions,
+  result: InitResult
+): Promise<void> {
+  const destinationPath = path.join(targetDir, "dxcomplete", "workspace.json");
+  const relativeDestination = path.relative(result.targetDir, destinationPath);
+  const exists = await fileExists(destinationPath);
+
+  if (exists && !options.force) {
+    result.skipped.push(relativeDestination);
+    return;
+  }
+
+  if (options.dryRun) {
+    result.planned.push(relativeDestination);
+    return;
+  }
+
+  const workspaceId = slugifyWorkspaceId(path.basename(targetDir)) || "dxcomplete-workspace";
+  const workspaceName = titleizeWorkspaceName(path.basename(targetDir)) || "DX Complete Workspace";
+  const content = `${JSON.stringify(
+    {
+      workspaceId,
+      name: workspaceName,
+      bootstrapMembers: []
+    },
+    null,
+    2
+  )}\n`;
+
+  await mkdir(path.dirname(destinationPath), { recursive: true });
+  await writeFile(destinationPath, content, "utf8");
+  result.written.push(relativeDestination);
+}
+
+async function copyDirectory(
+  sourceDir: string,
+  destinationDir: string,
+  options: CopyOptions,
+  result: InitResult
+): Promise<void> {
+  const entries = await readdir(sourceDir, { withFileTypes: true });
+
+  if (!options.dryRun) {
+    await mkdir(destinationDir, { recursive: true });
+  }
+
+  for (const entry of entries) {
+    const sourcePath = path.join(sourceDir, entry.name);
+    const destinationPath = path.join(destinationDir, entry.name);
+
+    if (entry.isDirectory()) {
+      await copyDirectory(sourcePath, destinationPath, options, result);
+      continue;
+    }
+
+    if (!entry.isFile()) {
+      continue;
+    }
+
+    const relativeDestination = path.relative(result.targetDir, destinationPath);
+    const exists = await fileExists(destinationPath);
+
+    if (exists && !options.force) {
+      result.skipped.push(relativeDestination);
+      continue;
+    }
+
+    if (options.dryRun) {
+      result.planned.push(relativeDestination);
+      continue;
+    }
+
+    await mkdir(path.dirname(destinationPath), { recursive: true });
+    await copyFile(sourcePath, destinationPath);
+    result.written.push(relativeDestination);
+  }
+}
+
+function slugifyWorkspaceId(value: string): string {
+  return value
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+}
+
+function titleizeWorkspaceName(value: string): string {
+  return value
+    .trim()
+    .replace(/[-_]+/g, " ")
+    .replace(/\s+/g, " ")
+    .replace(/\b\w/g, (letter) => letter.toUpperCase());
+}

package/src/install-manifest.ts

@@ -0,0 +1,144 @@
+import { createHash } from "node:crypto";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { fileExists } from "./package-root.js";
+import {
+  DXCOMPLETE_PACKAGE_VERSION,
+  WORKSPACE_COMPATIBILITY_VERSION
+} from "./version.js";
+
+export const INSTALL_MANIFEST_PATH = path.join("dxcomplete", ".install-manifest.json");
+export const INSTALL_MANIFEST_SCHEMA_VERSION = 1;
+
+export type UpgradeManagedFile = {
+  destinationRelative: string;
+  sourceRelative: string;
+  sourcePath: string;
+  destinationPath: string;
+  strategy: "copy" | "merge-vercel";
+};
+
+export type InstallManifest = {
+  schemaVersion: number;
+  packageVersion: string;
+  workspaceCompatibility: number;
+  installedAt: string;
+  managedFiles: Record<string, InstallManifestFile>;
+};
+
+export type InstallManifestFile = {
+  sha256: string;
+  source: string;
+  strategy: UpgradeManagedFile["strategy"];
+};
+
+export async function readInstallManifest(targetDir: string): Promise<InstallManifest | undefined> {
+  const manifestPath = path.join(targetDir, INSTALL_MANIFEST_PATH);
+
+  if (!(await fileExists(manifestPath))) {
+    return undefined;
+  }
+
+  const parsed = JSON.parse(await readFile(manifestPath, "utf8")) as unknown;
+  return parseInstallManifest(parsed, manifestPath);
+}
+
+export async function writeInstallManifest(targetDir: string, files: UpgradeManagedFile[]): Promise<void> {
+  const managedFiles: Record<string, InstallManifestFile> = {};
+
+  for (const file of files) {
+    if (!(await fileExists(file.destinationPath))) {
+      continue;
+    }
+
+    managedFiles[file.destinationRelative] = {
+      sha256: await hashFile(file.destinationPath),
+      source: file.sourceRelative,
+      strategy: file.strategy
+    };
+  }
+
+  const manifest: InstallManifest = {
+    schemaVersion: INSTALL_MANIFEST_SCHEMA_VERSION,
+    packageVersion: DXCOMPLETE_PACKAGE_VERSION,
+    workspaceCompatibility: WORKSPACE_COMPATIBILITY_VERSION,
+    installedAt: new Date().toISOString(),
+    managedFiles
+  };
+
+  const manifestPath = path.join(targetDir, INSTALL_MANIFEST_PATH);
+  await mkdir(path.dirname(manifestPath), { recursive: true });
+  await writeFile(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`, "utf8");
+}
+
+export async function hashFile(filePath: string): Promise<string> {
+  return hashContent(await readFile(filePath));
+}
+
+export function hashContent(content: string | Buffer): string {
+  return createHash("sha256").update(content).digest("hex");
+}
+
+function parseInstallManifest(value: unknown, source: string): InstallManifest {
+  if (!value || typeof value !== "object") {
+    throw new Error(`${source} must be a JSON object.`);
+  }
+
+  const input = value as Record<string, unknown>;
+  const schemaVersion = readNumber(input.schemaVersion, "schemaVersion", source);
+  const packageVersion = readString(input.packageVersion, "packageVersion", source);
+  const workspaceCompatibility = readNumber(input.workspaceCompatibility, "workspaceCompatibility", source);
+  const installedAt = readString(input.installedAt, "installedAt", source);
+  const managedFiles = parseManagedFiles(input.managedFiles, source);
+
+  return {
+    schemaVersion,
+    packageVersion,
+    workspaceCompatibility,
+    installedAt,
+    managedFiles
+  };
+}
+
+function parseManagedFiles(value: unknown, source: string): Record<string, InstallManifestFile> {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error(`${source} managedFiles must be a JSON object.`);
+  }
+
+  const output: Record<string, InstallManifestFile> = {};
+  for (const [filePath, fileValue] of Object.entries(value as Record<string, unknown>)) {
+    if (!fileValue || typeof fileValue !== "object" || Array.isArray(fileValue)) {
+      throw new Error(`${source} managedFiles.${filePath} must be a JSON object.`);
+    }
+
+    const file = fileValue as Record<string, unknown>;
+    const strategy = readString(file.strategy, `managedFiles.${filePath}.strategy`, source);
+    if (strategy !== "copy" && strategy !== "merge-vercel") {
+      throw new Error(`${source} managedFiles.${filePath}.strategy must be copy or merge-vercel.`);
+    }
+
+    output[filePath] = {
+      sha256: readString(file.sha256, `managedFiles.${filePath}.sha256`, source),
+      source: readString(file.source, `managedFiles.${filePath}.source`, source),
+      strategy
+    };
+  }
+
+  return output;
+}
+
+function readString(value: unknown, key: string, source: string): string {
+  if (typeof value !== "string" || !value.trim()) {
+    throw new Error(`${source} ${key} must be a non-empty string.`);
+  }
+
+  return value;
+}
+
+function readNumber(value: unknown, key: string, source: string): number {
+  if (typeof value !== "number" || !Number.isInteger(value) || value < 0) {
+    throw new Error(`${source} ${key} must be a non-negative integer.`);
+  }
+
+  return value;
+}