@tinyrack/devsync 1.0.0

package/src/config/xdg.ts

@@ -0,0 +1,138 @@
+import { homedir } from "node:os";
+import { isAbsolute, resolve } from "node:path";
+
+const readTrimmedEnvironmentValue = (
+  environment: NodeJS.ProcessEnv,
+  key: string,
+) => {
+  const value = environment[key];
+
+  if (value === undefined) {
+    return undefined;
+  }
+
+  const trimmedValue = value.trim();
+
+  return trimmedValue === "" ? undefined : trimmedValue;
+};
+
+const bracedXdgConfigHomeToken = "$" + "{XDG_CONFIG_HOME}";
+const bracedXdgConfigHomePrefix = `${bracedXdgConfigHomeToken}/`;
+
+export const resolveHomeDirectory = (
+  environment: NodeJS.ProcessEnv = process.env,
+) => {
+  const configuredValue = readTrimmedEnvironmentValue(environment, "HOME");
+
+  if (configuredValue !== undefined) {
+    return resolve(configuredValue);
+  }
+
+  return resolve(homedir());
+};
+
+export const resolveXdgConfigHome = (
+  environment: NodeJS.ProcessEnv = process.env,
+) => {
+  const configuredValue = readTrimmedEnvironmentValue(
+    environment,
+    "XDG_CONFIG_HOME",
+  );
+
+  if (configuredValue !== undefined) {
+    return resolve(configuredValue);
+  }
+
+  return resolve(resolveHomeDirectory(environment), ".config");
+};
+
+export const resolveDevsyncConfigDirectory = (
+  environment: NodeJS.ProcessEnv = process.env,
+) => {
+  return resolve(resolveXdgConfigHome(environment), "devsync");
+};
+
+export const resolveDevsyncSyncDirectory = (
+  environment: NodeJS.ProcessEnv = process.env,
+) => {
+  return resolve(resolveDevsyncConfigDirectory(environment), "sync");
+};
+
+export const resolveDevsyncAgeDirectory = (
+  environment: NodeJS.ProcessEnv = process.env,
+) => {
+  return resolve(resolveDevsyncConfigDirectory(environment), "age");
+};
+
+export const expandHomePath = (
+  value: string,
+  environment: NodeJS.ProcessEnv = process.env,
+) => {
+  let expandedValue = value.trim();
+
+  if (expandedValue === "~") {
+    expandedValue = resolveHomeDirectory(environment);
+  } else if (expandedValue.startsWith("~/")) {
+    expandedValue = resolve(
+      resolveHomeDirectory(environment),
+      expandedValue.slice(2),
+    );
+  }
+
+  return expandedValue;
+};
+
+export const expandConfiguredPath = (
+  value: string,
+  environment: NodeJS.ProcessEnv = process.env,
+) => {
+  let expandedValue = expandHomePath(value, environment);
+
+  if (expandedValue === "$XDG_CONFIG_HOME") {
+    expandedValue = resolveXdgConfigHome(environment);
+  } else if (expandedValue.startsWith("$XDG_CONFIG_HOME/")) {
+    expandedValue = resolve(
+      resolveXdgConfigHome(environment),
+      expandedValue.slice("$XDG_CONFIG_HOME/".length),
+    );
+  } else if (expandedValue === bracedXdgConfigHomeToken) {
+    expandedValue = resolveXdgConfigHome(environment);
+  } else if (expandedValue.startsWith(bracedXdgConfigHomePrefix)) {
+    expandedValue = resolve(
+      resolveXdgConfigHome(environment),
+      expandedValue.slice(bracedXdgConfigHomePrefix.length),
+    );
+  }
+
+  return expandedValue;
+};
+
+export const resolveConfiguredAbsolutePath = (
+  value: string,
+  environment: NodeJS.ProcessEnv = process.env,
+) => {
+  const expandedValue = expandConfiguredPath(value, environment);
+
+  if (!isAbsolute(expandedValue)) {
+    throw new Error(
+      `Configured path must be absolute or start with ~ or $XDG_CONFIG_HOME: ${value}`,
+    );
+  }
+
+  return resolve(expandedValue);
+};
+
+export const resolveHomeConfiguredAbsolutePath = (
+  value: string,
+  environment: NodeJS.ProcessEnv = process.env,
+) => {
+  const expandedValue = expandHomePath(value, environment);
+
+  if (!isAbsolute(expandedValue)) {
+    throw new Error(
+      `Configured path must be absolute or start with ~: ${value}`,
+    );
+  }
+
+  return resolve(expandedValue);
+};

package/src/index.ts

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

package/src/lib/string.ts

@@ -0,0 +1,3 @@
+export const ensureTrailingNewline = (value: string) => {
+  return value.endsWith("\n") ? value : `${value}\n`;
+};

package/src/lib/validation.ts

@@ -0,0 +1,11 @@
+import type { z } from "zod";
+
+export const formatInputIssues = (issues: z.ZodIssue[]): string => {
+  return issues
+    .map((issue) => {
+      const path = issue.path.length === 0 ? "input" : issue.path.join(".");
+
+      return `- ${path}: ${issue.message}`;
+    })
+    .join("\n");
+};

package/src/services/add.ts

@@ -0,0 +1,178 @@
+import {
+  type ResolvedSyncConfig,
+  type ResolvedSyncConfigEntry,
+  readSyncConfig,
+  type SyncConfigEntryKind,
+  type SyncMode,
+} from "#app/config/sync.ts";
+
+import {
+  createSyncConfigDocument,
+  createSyncConfigDocumentEntry,
+  sortSyncConfigEntries,
+  writeValidatedSyncConfig,
+} from "./config-file.ts";
+import { DevsyncError } from "./error.ts";
+import { getPathStats } from "./filesystem.ts";
+import {
+  buildConfiguredHomeLocalPath,
+  buildRepoPathWithinRoot,
+  doPathsOverlap,
+  resolveCommandTargetPath,
+} from "./paths.ts";
+import { ensureSyncRepository, type SyncContext } from "./runtime.ts";
+
+export type SyncAddRequest = Readonly<{
+  secret: boolean;
+  target: string;
+}>;
+
+export type SyncAddResult = Readonly<{
+  alreadyTracked: boolean;
+  configPath: string;
+  kind: SyncConfigEntryKind;
+  localPath: string;
+  mode: SyncMode;
+  repoPath: string;
+  syncDirectory: string;
+}>;
+
+const buildAddEntryCandidate = async (
+  targetPath: string,
+  config: ResolvedSyncConfig,
+  context: Pick<SyncContext, "paths">,
+) => {
+  const targetStats = await getPathStats(targetPath);
+
+  if (targetStats === undefined) {
+    throw new DevsyncError(`Sync target does not exist: ${targetPath}`);
+  }
+
+  const kind = (() => {
+    if (targetStats.isDirectory()) {
+      return "directory" as const;
+    }
+
+    if (targetStats.isFile() || targetStats.isSymbolicLink()) {
+      return "file" as const;
+    }
+
+    throw new DevsyncError(`Unsupported sync target type: ${targetPath}`);
+  })();
+
+  if (doPathsOverlap(targetPath, context.paths.syncDirectory)) {
+    throw new DevsyncError(
+      `Sync target must not overlap the sync directory: ${targetPath}`,
+    );
+  }
+
+  if (doPathsOverlap(targetPath, config.age.identityFile)) {
+    throw new DevsyncError(
+      `Sync target must not contain the age identity file: ${targetPath}`,
+    );
+  }
+
+  const repoPath = buildRepoPathWithinRoot(
+    targetPath,
+    context.paths.homeDirectory,
+    "Sync target",
+  );
+
+  return {
+    configuredLocalPath: buildConfiguredHomeLocalPath(repoPath),
+    kind,
+    localPath: targetPath,
+    mode: "normal",
+    name: repoPath,
+    overrides: [],
+    repoPath,
+  } satisfies ResolvedSyncConfigEntry;
+};
+
+export const addSyncTarget = async (
+  request: SyncAddRequest,
+  context: SyncContext,
+): Promise<SyncAddResult> => {
+  const target = request.target.trim();
+
+  if (target.length === 0) {
+    throw new DevsyncError("Target path is required.");
+  }
+
+  await ensureSyncRepository(context);
+
+  const config = await readSyncConfig(
+    context.paths.syncDirectory,
+    context.environment,
+  );
+  const candidate = await buildAddEntryCandidate(
+    resolveCommandTargetPath(target, context.environment, context.cwd),
+    config,
+    context,
+  );
+  const existingEntry = config.entries.find((entry) => {
+    return (
+      entry.localPath === candidate.localPath ||
+      entry.repoPath === candidate.repoPath
+    );
+  });
+  let alreadyTracked = false;
+
+  if (existingEntry !== undefined) {
+    if (
+      existingEntry.localPath === candidate.localPath &&
+      existingEntry.repoPath === candidate.repoPath &&
+      existingEntry.kind === candidate.kind
+    ) {
+      alreadyTracked = true;
+    } else {
+      throw new DevsyncError(
+        `Sync target conflicts with an existing entry: ${existingEntry.repoPath}`,
+      );
+    }
+  }
+
+  const nextConfig = createSyncConfigDocument(config);
+  const desiredMode: SyncMode = request.secret ? "secret" : "normal";
+  let mode = existingEntry?.mode ?? (request.secret ? "secret" : "normal");
+
+  if (!alreadyTracked) {
+    nextConfig.entries = sortSyncConfigEntries([
+      ...nextConfig.entries,
+      createSyncConfigDocumentEntry({
+        ...candidate,
+        mode: desiredMode,
+      }),
+    ]);
+    mode = desiredMode;
+  } else if (request.secret && existingEntry?.mode !== "secret") {
+    nextConfig.entries = nextConfig.entries.map((entry) => {
+      if (entry.repoPath !== candidate.repoPath) {
+        return entry;
+      }
+
+      return {
+        ...entry,
+        mode: "secret",
+      };
+    });
+
+    mode = "secret";
+  }
+
+  if (!alreadyTracked || (request.secret && existingEntry?.mode !== "secret")) {
+    await writeValidatedSyncConfig(context.paths.syncDirectory, nextConfig, {
+      environment: context.environment,
+    });
+  }
+
+  return {
+    alreadyTracked,
+    configPath: context.paths.configPath,
+    kind: candidate.kind,
+    localPath: candidate.localPath,
+    mode,
+    repoPath: candidate.repoPath,
+    syncDirectory: context.paths.syncDirectory,
+  };
+};

package/src/services/config-file.ts

@@ -0,0 +1,101 @@
+import {
+  formatSyncConfig,
+  formatSyncOverrideSelector,
+  parseSyncConfig,
+  type ResolvedSyncConfig,
+  type ResolvedSyncConfigEntry,
+  type ResolvedSyncOverride,
+  resolveSyncConfigFilePath,
+  type SyncConfig,
+} from "#app/config/sync.ts";
+
+import { writeTextFileAtomically } from "./filesystem.ts";
+
+type SyncConfigDocumentEntry = SyncConfig["entries"][number];
+
+export const sortSyncOverrides = (
+  overrides: readonly Pick<ResolvedSyncOverride, "match" | "mode" | "path">[],
+) => {
+  return [...overrides].sort((left, right) => {
+    return formatSyncOverrideSelector(left).localeCompare(
+      formatSyncOverrideSelector(right),
+    );
+  });
+};
+
+export const createSyncConfigDocumentEntry = (
+  entry: Pick<
+    ResolvedSyncConfigEntry,
+    "configuredLocalPath" | "kind" | "name" | "mode" | "overrides" | "repoPath"
+  >,
+): SyncConfigDocumentEntry => {
+  return {
+    kind: entry.kind,
+    localPath: entry.configuredLocalPath,
+    mode: entry.mode,
+    name: entry.name,
+    ...(entry.overrides.length === 0
+      ? {}
+      : {
+          overrides: Object.fromEntries(
+            sortSyncOverrides(entry.overrides).map((override) => {
+              return [formatSyncOverrideSelector(override), override.mode];
+            }),
+          ),
+        }),
+    repoPath: entry.repoPath,
+  };
+};
+
+export const createSyncConfigDocument = (
+  config: ResolvedSyncConfig,
+): SyncConfig => {
+  return {
+    version: 1,
+    age: {
+      identityFile: config.age.configuredIdentityFile,
+      recipients: [...config.age.recipients],
+    },
+    entries: config.entries.map((entry) => {
+      return createSyncConfigDocumentEntry(entry);
+    }),
+  };
+};
+
+export const sortSyncConfigEntries = (
+  entries: readonly SyncConfigDocumentEntry[],
+) => {
+  return [...entries].sort((left, right) => {
+    return left.repoPath.localeCompare(right.repoPath);
+  });
+};
+
+export const countConfiguredRules = (config: ResolvedSyncConfig) => {
+  return config.entries.reduce((total, entry) => {
+    return total + entry.overrides.length;
+  }, 0);
+};
+
+export const writeValidatedSyncConfig = async (
+  syncDirectory: string,
+  config: SyncConfig,
+  dependencies: Readonly<{
+    environment: NodeJS.ProcessEnv;
+  }>,
+) => {
+  const resolvedConfig = parseSyncConfig(
+    {
+      ...config,
+      entries: sortSyncConfigEntries(config.entries),
+    },
+    dependencies.environment,
+  );
+  const nextConfig = createSyncConfigDocument(resolvedConfig);
+
+  await writeTextFileAtomically(
+    resolveSyncConfigFilePath(syncDirectory),
+    formatSyncConfig(nextConfig),
+  );
+
+  return nextConfig;
+};

package/src/services/crypto.ts

@@ -0,0 +1,83 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+
+import {
+  armor,
+  Decrypter,
+  Encrypter,
+  generateIdentity,
+  identityToRecipient,
+} from "age-encryption";
+
+import { ensureTrailingNewline } from "#app/lib/string.ts";
+
+export const readAgeIdentityLines = async (identityFile: string) => {
+  const contents = await readFile(identityFile, "utf8");
+  const identities = contents
+    .split(/\r?\n/u)
+    .map((line) => line.trim())
+    .filter((line) => {
+      return line !== "" && !line.startsWith("#");
+    });
+
+  if (identities.length === 0) {
+    throw new Error(`No age identities found in ${identityFile}`);
+  }
+
+  return identities;
+};
+
+export const readAgeRecipientsFromIdentityFile = async (
+  identityFile: string,
+) => {
+  const identities = await readAgeIdentityLines(identityFile);
+  const recipients = await Promise.all(
+    identities.map(async (identity) => {
+      return await identityToRecipient(identity);
+    }),
+  );
+
+  return [...new Set(recipients)];
+};
+
+export const createAgeIdentityFile = async (identityFile: string) => {
+  const identity = await generateIdentity();
+  const recipient = await identityToRecipient(identity);
+
+  await mkdir(dirname(identityFile), { recursive: true });
+  await writeFile(identityFile, ensureTrailingNewline(identity), "utf8");
+
+  return {
+    identity,
+    recipient,
+  };
+};
+
+export const encryptSecretFile = async (
+  contents: Uint8Array,
+  recipients: readonly string[],
+) => {
+  const encrypter = new Encrypter();
+
+  for (const recipient of recipients) {
+    encrypter.addRecipient(recipient);
+  }
+
+  const ciphertext = await encrypter.encrypt(contents);
+
+  return armor.encode(ciphertext);
+};
+
+export const decryptSecretFile = async (
+  armoredCiphertext: string,
+  identityFile: string,
+) => {
+  const decrypter = new Decrypter();
+  const identities = await readAgeIdentityLines(identityFile);
+
+  for (const identity of identities) {
+    decrypter.addIdentity(identity);
+  }
+
+  return await decrypter.decrypt(armor.decode(armoredCiphertext));
+};

package/src/services/error.ts

@@ -0,0 +1,6 @@
+export class DevsyncError extends Error {
+  public constructor(message: string) {
+    super(message);
+    this.name = "DevsyncError";
+  }
+}

package/src/services/filesystem.ts

@@ -0,0 +1,183 @@
+import { randomUUID } from "node:crypto";
+import {
+  access,
+  chmod,
+  lstat,
+  mkdir,
+  mkdtemp,
+  readdir,
+  readFile,
+  readlink,
+  rename,
+  rm,
+  symlink,
+  writeFile,
+} from "node:fs/promises";
+import { basename, dirname, join } from "node:path";
+
+import { DevsyncError } from "./error.ts";
+
+export const pathExists = async (path: string) => {
+  try {
+    await access(path);
+
+    return true;
+  } catch (error: unknown) {
+    if (error instanceof Error && "code" in error && error.code === "ENOENT") {
+      return false;
+    }
+
+    throw error;
+  }
+};
+
+export const getPathStats = async (path: string) => {
+  try {
+    return await lstat(path);
+  } catch (error: unknown) {
+    if (error instanceof Error && "code" in error && error.code === "ENOENT") {
+      return undefined;
+    }
+
+    throw error;
+  }
+};
+
+export const listDirectoryEntries = async (path: string) => {
+  const entries = await readdir(path, { withFileTypes: true });
+
+  return entries.sort((left, right) => {
+    return left.name.localeCompare(right.name);
+  });
+};
+
+export const buildExecutableMode = (executable: boolean) => {
+  return executable ? 0o755 : 0o644;
+};
+
+export const isExecutableMode = (mode: number | bigint) => {
+  return (Number(mode) & 0o111) !== 0;
+};
+
+export const writeFileNode = async (
+  path: string,
+  node: Readonly<{
+    contents: string | Uint8Array;
+    executable: boolean;
+  }>,
+) => {
+  await mkdir(dirname(path), { recursive: true });
+  await writeFile(path, node.contents);
+  await chmod(path, buildExecutableMode(node.executable));
+};
+
+export const writeSymlinkNode = async (path: string, linkTarget: string) => {
+  await mkdir(dirname(path), { recursive: true });
+  await rm(path, { force: true, recursive: true });
+  await symlink(linkTarget, path);
+};
+
+export const copyFilesystemNode = async (
+  sourcePath: string,
+  targetPath: string,
+  stats?: Awaited<ReturnType<typeof lstat>>,
+) => {
+  const sourceStats = stats ?? (await lstat(sourcePath));
+
+  if (sourceStats.isDirectory()) {
+    await mkdir(targetPath, { recursive: true });
+
+    const entries = await listDirectoryEntries(sourcePath);
+
+    for (const entry of entries) {
+      await copyFilesystemNode(
+        join(sourcePath, entry.name),
+        join(targetPath, entry.name),
+      );
+    }
+
+    return;
+  }
+
+  if (sourceStats.isSymbolicLink()) {
+    await writeSymlinkNode(targetPath, await readlink(sourcePath));
+
+    return;
+  }
+
+  if (!sourceStats.isFile()) {
+    throw new DevsyncError(`Unsupported filesystem entry: ${sourcePath}`);
+  }
+
+  await writeFileNode(targetPath, {
+    contents: await readFile(sourcePath),
+    executable: isExecutableMode(sourceStats.mode),
+  });
+};
+
+export const replacePathAtomically = async (
+  targetPath: string,
+  nextPath: string,
+) => {
+  const backupPath = join(
+    dirname(targetPath),
+    `.${basename(targetPath)}.devsync-sync-backup-${randomUUID()}`,
+  );
+  const existingStats = await getPathStats(targetPath);
+  let targetMoved = false;
+
+  try {
+    if (existingStats !== undefined) {
+      await rename(targetPath, backupPath);
+      targetMoved = true;
+    }
+
+    await rename(nextPath, targetPath);
+
+    if (targetMoved) {
+      await rm(backupPath, { force: true, recursive: true });
+    }
+  } catch (error: unknown) {
+    if (targetMoved && !(await pathExists(targetPath))) {
+      await rename(backupPath, targetPath).catch(() => {});
+    }
+
+    throw error;
+  } finally {
+    await rm(backupPath, { force: true, recursive: true }).catch(() => {});
+  }
+};
+
+export const removePathAtomically = async (targetPath: string) => {
+  const stats = await getPathStats(targetPath);
+
+  if (stats === undefined) {
+    return;
+  }
+
+  const backupPath = join(
+    dirname(targetPath),
+    `.${basename(targetPath)}.devsync-sync-remove-${randomUUID()}`,
+  );
+
+  await rename(targetPath, backupPath);
+  await rm(backupPath, { force: true, recursive: true });
+};
+
+export const writeTextFileAtomically = async (
+  targetPath: string,
+  contents: string,
+) => {
+  await mkdir(dirname(targetPath), { recursive: true });
+  const stagingDirectory = await mkdtemp(
+    join(dirname(targetPath), `.${basename(targetPath)}.devsync-sync-`),
+  );
+  const stagedPath = join(stagingDirectory, basename(targetPath));
+
+  try {
+    await writeFile(stagedPath, contents, "utf8");
+    await replacePathAtomically(targetPath, stagedPath);
+  } finally {
+    await rm(stagingDirectory, { force: true, recursive: true });
+  }
+};