@tinyrack/devsync 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 winetree94
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,159 @@
+# devsync
+
+A personal CLI tool for git-backed configuration sync.
+
+`devsync` is a Node.js + TypeScript command-line utility for managing a synced configuration repository under your XDG config directory. It tracks files and directories under `HOME`, stores plain and encrypted artifacts in a git-backed sync repo, and can push local state into that repo or pull the repo back onto the machine.
+
+## Features
+
+- Flat sync-focused CLI: `init`, `add`, `set`, `forget`, `push`, `pull`, `cd`
+- Git-backed sync repository under `~/.config/devsync/sync`
+- Age-encrypted secret file support
+- Rule-based `normal`, `secret`, and `ignore` modes
+- Direct TypeScript execution with Node.js 24+
+- Shell autocomplete via oclif
+
+## Requirements
+
+- Node.js 24+
+- npm
+- git
+
+## Installation
+
+Install globally:
+
+```bash
+npm install -g @tinyrack/devsync
+```
+
+Run without installing globally:
+
+```bash
+npx @tinyrack/devsync --help
+```
+
+Run the CLI locally:
+
+```bash
+npm run start -- --help
+```
+
+For development with file watching:
+
+```bash
+npm run dev
+```
+
+The published package name is `@tinyrack/devsync`, but the installed command is still `devsync`.
+
+If you want the `devsync` command available from this checkout during development:
+
+```bash
+npm link
+```
+
+## Storage Layout
+
+- Sync repo: `~/.config/devsync/sync`
+- Default age identity file: `$XDG_CONFIG_HOME/devsync/age/keys.txt`
+- Tracked artifacts live under `~/.config/devsync/sync/files`
+- Secret file artifacts use the suffix `.devsync.secret`, for example `token.json.devsync.secret`
+
+## Usage
+
+```bash
+devsync <command>
+```
+
+Or without linking:
+
+```bash
+npm run start -- <command>
+```
+
+## Commands
+
+### `init`
+
+Initialize the git-backed sync directory.
+
+```bash
+devsync init
+devsync init https://example.com/my-sync-repo.git
+devsync init --identity "$XDG_CONFIG_HOME/devsync/age/keys.txt" --recipient age1...
+```
+
+### `add`
+
+Track a local file or directory under your home directory.
+
+```bash
+devsync add ~/.gitconfig
+devsync add ./.zshrc
+devsync add ~/.config/mytool --secret
+```
+
+### `set`
+
+Set mode for a tracked directory root, child file, or child subtree.
+
+```bash
+devsync set secret ~/.config/mytool/token.json
+devsync set ignore ~/.config/mytool/cache --recursive
+cd ~/.ssh && devsync set ignore known_hosts
+devsync set normal .config/mytool/public.json
+```
+
+### `forget`
+
+Remove a tracked local path or repository path from sync config.
+
+```bash
+devsync forget ~/.gitconfig
+cd ~/mytool && devsync forget ./settings.json
+devsync forget .config/mytool
+```
+
+### `push`
+
+Mirror local config into the sync repository.
+
+```bash
+devsync push
+devsync push --dry-run
+```
+
+### `pull`
+
+Apply the sync repository to local config paths.
+
+```bash
+devsync pull
+devsync pull --dry-run
+```
+
+### `cd`
+
+Print the sync directory in non-interactive mode, or open a shell there in interactive mode.
+
+```bash
+devsync cd
+devsync cd --print
+```
+
+## Development
+
+Validation commands:
+
+```bash
+npm run typecheck
+biome check .
+npm run test
+```
+
+Or run the full validation sequence:
+
+```bash
+npm run check
+```

package/package.json

@@ -0,0 +1,81 @@
+{
+  "name": "@tinyrack/devsync",
+  "version": "1.0.0",
+  "description": "A personal CLI tool for git-backed configuration sync.",
+  "type": "module",
+  "license": "MIT",
+  "author": "winetree94",
+  "repository": {
+    "type": "git",
+    "url": "https://git.winetree94.com/winetree94/devsync.git"
+  },
+  "homepage": "https://git.winetree94.com/winetree94/devsync",
+  "bugs": {
+    "url": "https://git.winetree94.com/winetree94/devsync/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "cli",
+    "sync",
+    "dotfiles",
+    "config-sync",
+    "devsync"
+  ],
+  "imports": {
+    "#app/*": "./src/*"
+  },
+  "bin": {
+    "devsync": "./src/index.ts"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "oclif": {
+    "bin": "devsync",
+    "dirname": "devsync",
+    "commands": {
+      "strategy": "explicit",
+      "target": "./src/cli/commands/index.ts",
+      "identifier": "COMMANDS"
+    },
+    "topicSeparator": " ",
+    "plugins": [
+      "@oclif/plugin-autocomplete"
+    ],
+    "additionalHelpFlags": [
+      "-h"
+    ]
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "scripts": {
+    "dev": "node --watch src/index.ts",
+    "start": "node src/index.ts",
+    "typecheck": "tsc -p tsconfig.json",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "coverage": "vitest run --coverage",
+    "check": "npm run typecheck && biome check . && npm run test",
+    "check:fix": "biome check --write .",
+    "format": "biome format --write ."
+  },
+  "dependencies": {
+    "@oclif/core": "^4.9.0",
+    "@oclif/plugin-autocomplete": "^3.2.41",
+    "age-encryption": "^0.3.0",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.4.8",
+    "@types/node": "^25.5.0",
+    "@vitest/coverage-v8": "^4.1.0",
+    "execa": "^9.6.1",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.0"
+  }
+}

package/src/cli/commands/add.ts

@@ -0,0 +1,40 @@
+import { Args, Command, Flags } from "@oclif/core";
+
+import { formatSyncAddResult } from "#app/cli/sync-output.ts";
+import { addSyncTarget } from "#app/services/add.ts";
+import { createSyncContext } from "#app/services/runtime.ts";
+
+export default class SyncAdd extends Command {
+  public static override summary =
+    "Add a local file or directory under your home directory to sync config.json";
+
+  public static override args = {
+    target: Args.string({
+      description:
+        "Local file or directory under your home directory to track, including cwd-relative paths",
+      required: true,
+    }),
+  };
+
+  public static override flags = {
+    secret: Flags.boolean({
+      default: false,
+      description: "Set the added target mode to secret in sync config.json",
+    }),
+  };
+
+  public override async run(): Promise<void> {
+    const { args, flags } = await this.parse(SyncAdd);
+    const output = formatSyncAddResult(
+      await addSyncTarget(
+        {
+          secret: flags.secret,
+          target: args.target,
+        },
+        createSyncContext(),
+      ),
+    );
+
+    process.stdout.write(output);
+  }
+}

package/src/cli/commands/cd.ts

@@ -0,0 +1,80 @@
+import { spawn } from "node:child_process";
+import { mkdir } from "node:fs/promises";
+
+import { Command, Flags } from "@oclif/core";
+
+import { resolveDevsyncSyncDirectory } from "#app/config/xdg.ts";
+import { ensureTrailingNewline } from "#app/lib/string.ts";
+
+const readEnvironmentVariable = (name: "ComSpec" | "SHELL") => {
+  return process.env[name]?.trim();
+};
+
+const resolveCommandShell = () => {
+  if (process.platform === "win32") {
+    return {
+      args: [] as string[],
+      command: readEnvironmentVariable("ComSpec") || "cmd.exe",
+    };
+  }
+
+  return {
+    args: ["-i"],
+    command: readEnvironmentVariable("SHELL") || "/bin/sh",
+  };
+};
+
+const spawnShellInDirectory = async (directory: string) => {
+  await mkdir(directory, { recursive: true });
+
+  const shell = resolveCommandShell();
+
+  await new Promise<void>((resolve, reject) => {
+    const child = spawn(shell.command, shell.args, {
+      cwd: directory,
+      stdio: "inherit",
+    });
+
+    child.once("error", reject);
+    child.once("exit", (code, signal) => {
+      if (signal !== null) {
+        reject(new Error(`Shell exited with signal ${signal}.`));
+
+        return;
+      }
+
+      if (code === 0) {
+        resolve();
+
+        return;
+      }
+
+      reject(new Error(`Shell exited with code ${code ?? 1}.`));
+    });
+  });
+};
+
+export default class SyncCd extends Command {
+  public static override summary =
+    "Open a shell in the sync directory or print its path";
+
+  public static override flags = {
+    print: Flags.boolean({
+      default: false,
+      description: "Print the sync directory path instead of opening a shell",
+    }),
+  };
+
+  public override async run(): Promise<void> {
+    const { flags } = await this.parse(SyncCd);
+    const syncDirectory = resolveDevsyncSyncDirectory();
+
+    if (flags.print || !process.stdin.isTTY || !process.stdout.isTTY) {
+      process.stdout.write(ensureTrailingNewline(syncDirectory));
+
+      return;
+    }
+
+    await spawnShellInDirectory(syncDirectory);
+  }
+}

package/src/cli/commands/forget.ts

@@ -0,0 +1,32 @@
+import { Args, Command } from "@oclif/core";
+
+import { formatSyncForgetResult } from "#app/cli/sync-output.ts";
+import { forgetSyncTarget } from "#app/services/forget.ts";
+import { createSyncContext } from "#app/services/runtime.ts";
+
+export default class SyncForget extends Command {
+  public static override summary =
+    "Remove a tracked local path or repository path from sync config.json";
+
+  public static override args = {
+    target: Args.string({
+      description:
+        "Tracked local path (including cwd-relative) or repository path to forget",
+      required: true,
+    }),
+  };
+
+  public override async run(): Promise<void> {
+    const { args } = await this.parse(SyncForget);
+    const output = formatSyncForgetResult(
+      await forgetSyncTarget(
+        {
+          target: args.target,
+        },
+        createSyncContext(),
+      ),
+    );
+
+    process.stdout.write(output);
+  }
+}

package/src/cli/commands/index.ts

@@ -0,0 +1,17 @@
+import SyncAdd from "#app/cli/commands/add.ts";
+import SyncCd from "#app/cli/commands/cd.ts";
+import SyncForget from "#app/cli/commands/forget.ts";
+import SyncInit from "#app/cli/commands/init.ts";
+import SyncPull from "#app/cli/commands/pull.ts";
+import SyncPush from "#app/cli/commands/push.ts";
+import SyncSet from "#app/cli/commands/set.ts";
+
+export const COMMANDS = {
+  add: SyncAdd,
+  cd: SyncCd,
+  forget: SyncForget,
+  init: SyncInit,
+  pull: SyncPull,
+  push: SyncPush,
+  set: SyncSet,
+};

package/src/cli/commands/init.ts

@@ -0,0 +1,43 @@
+import { Args, Command, Flags } from "@oclif/core";
+
+import { formatSyncInitResult } from "#app/cli/sync-output.ts";
+import { initializeSync } from "#app/services/init.ts";
+import { createSyncContext } from "#app/services/runtime.ts";
+
+export default class SyncInit extends Command {
+  public static override summary = "Initialize the git-backed sync directory";
+
+  public static override args = {
+    repository: Args.string({
+      description: "Remote URL or local git repository path to clone",
+      required: false,
+    }),
+  };
+
+  public static override flags = {
+    identity: Flags.string({
+      description:
+        "Age identity file path to persist in config.json for later pulls",
+    }),
+    recipient: Flags.string({
+      description: "Age recipient public key to persist in config.json",
+      multiple: true,
+    }),
+  };
+
+  public override async run(): Promise<void> {
+    const { args, flags } = await this.parse(SyncInit);
+    const output = formatSyncInitResult(
+      await initializeSync(
+        {
+          identityFile: flags.identity,
+          recipients: flags.recipient ?? [],
+          repository: args.repository,
+        },
+        createSyncContext(),
+      ),
+    );
+
+    process.stdout.write(output);
+  }
+}

package/src/cli/commands/pull.ts

@@ -0,0 +1,31 @@
+import { Command, Flags } from "@oclif/core";
+
+import { formatSyncPullResult } from "#app/cli/sync-output.ts";
+import { pullSync } from "#app/services/pull.ts";
+import { createSyncContext } from "#app/services/runtime.ts";
+
+export default class SyncPull extends Command {
+  public static override summary =
+    "Apply the git-backed sync repository to local config paths";
+
+  public static override flags = {
+    "dry-run": Flags.boolean({
+      default: false,
+      description: "Preview local config changes without writing files",
+    }),
+  };
+
+  public override async run(): Promise<void> {
+    const { flags } = await this.parse(SyncPull);
+    const output = formatSyncPullResult(
+      await pullSync(
+        {
+          dryRun: flags["dry-run"],
+        },
+        createSyncContext(),
+      ),
+    );
+
+    process.stdout.write(output);
+  }
+}

package/src/cli/commands/push.ts

@@ -0,0 +1,31 @@
+import { Command, Flags } from "@oclif/core";
+
+import { formatSyncPushResult } from "#app/cli/sync-output.ts";
+import { pushSync } from "#app/services/push.ts";
+import { createSyncContext } from "#app/services/runtime.ts";
+
+export default class SyncPush extends Command {
+  public static override summary =
+    "Mirror local config into the git-backed sync repository";
+
+  public static override flags = {
+    "dry-run": Flags.boolean({
+      default: false,
+      description: "Preview sync repository changes without writing files",
+    }),
+  };
+
+  public override async run(): Promise<void> {
+    const { flags } = await this.parse(SyncPush);
+    const output = formatSyncPushResult(
+      await pushSync(
+        {
+          dryRun: flags["dry-run"],
+        },
+        createSyncContext(),
+      ),
+    );
+
+    process.stdout.write(output);
+  }
+}

package/src/cli/commands/set.ts

@@ -0,0 +1,47 @@
+import { Args, Command, Flags } from "@oclif/core";
+
+import { formatSyncSetResult } from "#app/cli/sync-output.ts";
+import { createSyncContext } from "#app/services/runtime.ts";
+import { setSyncTargetMode } from "#app/services/set.ts";
+
+export default class SyncSet extends Command {
+  public static override summary =
+    "Set sync mode for a tracked directory root, child file, or child subtree";
+
+  public static override args = {
+    state: Args.string({
+      description: "Mode to apply: normal, secret, or ignore",
+      options: ["normal", "secret", "ignore"],
+      required: true,
+    }),
+    target: Args.string({
+      description:
+        "Tracked local path (including cwd-relative) or repository path inside a tracked directory",
+      required: true,
+    }),
+  };
+
+  public static override flags = {
+    recursive: Flags.boolean({
+      default: false,
+      description:
+        "Apply the mode to a directory subtree or update a tracked directory root default",
+    }),
+  };
+
+  public override async run(): Promise<void> {
+    const { args, flags } = await this.parse(SyncSet);
+    const output = formatSyncSetResult(
+      await setSyncTargetMode(
+        {
+          recursive: flags.recursive,
+          state: args.state as "ignore" | "normal" | "secret",
+          target: args.target,
+        },
+        createSyncContext(),
+      ),
+    );
+
+    process.stdout.write(output);
+  }
+}