@tinyrack/devsync 1.0.3 → 1.1.0

package/README.md

@@ -6,7 +6,7 @@ A personal CLI tool for git-backed configuration sync.
 
 ## Features
 
-- Flat sync-focused CLI: `init`, `add`, `set`, `forget`, `push`, `pull`, `cd`
+- Flat sync-focused CLI: `init`, `add`, `set`, `forget`, `list`, `status`, `doctor`, `push`, `pull`, `cd`
 - Git-backed sync repository under `~/.config/devsync/sync`
 - Age-encrypted secret file support
 - Rule-based `normal`, `secret`, and `ignore` modes
@@ -129,6 +129,30 @@ cd ~/mytool && devsync forget ./settings.json
 devsync forget .config/mytool
 ```
 
+### `list`
+
+Show tracked entries, modes, and override rules.
+
+```bash
+devsync list
+```
+
+### `status`
+
+Show planned push and pull changes for the current sync config.
+
+```bash
+devsync status
+```
+
+### `doctor`
+
+Check the sync repository, config, age identity, and tracked local paths.
+
+```bash
+devsync doctor
+```
+
 ### `push`
 
 Mirror local config into the sync repository.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tinyrack/devsync",
-  "version": "1.0.3",
+  "version": "1.1.0",
   "description": "A personal CLI tool for git-backed configuration sync.",
   "type": "module",
   "license": "MIT",

package/src/cli/commands/doctor.ts

@@ -0,0 +1,20 @@
+import { Command } from "@oclif/core";
+
+import { formatSyncDoctorResult } from "#app/cli/sync-output.ts";
+import { runSyncDoctor } from "#app/services/doctor.ts";
+import { createSyncContext } from "#app/services/runtime.ts";
+
+export default class SyncDoctor extends Command {
+  public static override summary =
+    "Check sync repository, config, age identity, and tracked local paths";
+
+  public override async run(): Promise<void> {
+    const result = await runSyncDoctor(createSyncContext());
+
+    process.stdout.write(formatSyncDoctorResult(result));
+
+    if (result.hasFailures) {
+      this.exit(1);
+    }
+  }
+}

package/src/cli/commands/index.ts

@@ -1,17 +1,23 @@
 import SyncAdd from "#app/cli/commands/add.ts";
 import SyncCd from "#app/cli/commands/cd.ts";
+import SyncDoctor from "#app/cli/commands/doctor.ts";
 import SyncForget from "#app/cli/commands/forget.ts";
 import SyncInit from "#app/cli/commands/init.ts";
+import SyncList from "#app/cli/commands/list.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";
+import SyncStatus from "#app/cli/commands/status.ts";
 
 export const COMMANDS = {
   add: SyncAdd,
   cd: SyncCd,
+  doctor: SyncDoctor,
   forget: SyncForget,
   init: SyncInit,
+  list: SyncList,
   pull: SyncPull,
   push: SyncPush,
+  status: SyncStatus,
   set: SyncSet,
 };

package/src/cli/commands/list.ts

@@ -0,0 +1,17 @@
+import { Command } from "@oclif/core";
+
+import { formatSyncListResult } from "#app/cli/sync-output.ts";
+import { listSyncConfig } from "#app/services/list.ts";
+import { createSyncContext } from "#app/services/runtime.ts";
+
+export default class SyncList extends Command {
+  public static override summary = "Show tracked sync entries and overrides";
+
+  public override async run(): Promise<void> {
+    const output = formatSyncListResult(
+      await listSyncConfig(createSyncContext()),
+    );
+
+    process.stdout.write(output);
+  }
+}

package/src/cli/commands/status.ts

@@ -0,0 +1,18 @@
+import { Command } from "@oclif/core";
+
+import { formatSyncStatusResult } from "#app/cli/sync-output.ts";
+import { createSyncContext } from "#app/services/runtime.ts";
+import { getSyncStatus } from "#app/services/status.ts";
+
+export default class SyncStatus extends Command {
+  public static override summary =
+    "Show planned push and pull changes for the current sync config";
+
+  public override async run(): Promise<void> {
+    const output = formatSyncStatusResult(
+      await getSyncStatus(createSyncContext()),
+    );
+
+    process.stdout.write(output);
+  }
+}

package/src/cli/sync-output.test.ts

@@ -2,11 +2,14 @@ import { describe, expect, it } from "vitest";
 
 import {
   formatSyncAddResult,
+  formatSyncDoctorResult,
   formatSyncForgetResult,
   formatSyncInitResult,
+  formatSyncListResult,
   formatSyncPullResult,
   formatSyncPushResult,
   formatSyncSetResult,
+  formatSyncStatusResult,
 } from "#app/cli/sync-output.ts";
 
 describe("sync output formatting", () => {
@@ -102,4 +105,69 @@ describe("sync output formatting", () => {
       "local paths would be removed.\nNo filesystem changes were made.\n",
     );
   });
+
+  it("formats list, status, and doctor results", () => {
+    expect(
+      formatSyncListResult({
+        configPath: "/tmp/sync/config.json",
+        entries: [
+          {
+            kind: "directory",
+            localPath: "/tmp/home/.config/tool",
+            mode: "normal",
+            name: ".config/tool",
+            overrides: [{ mode: "secret", selector: "token.json" }],
+            repoPath: ".config/tool",
+          },
+        ],
+        recipientCount: 1,
+        ruleCount: 1,
+        syncDirectory: "/tmp/sync",
+      }),
+    ).toContain("override token.json: secret\n");
+    expect(
+      formatSyncStatusResult({
+        configPath: "/tmp/sync/config.json",
+        entryCount: 1,
+        pull: {
+          configPath: "/tmp/sync/config.json",
+          decryptedFileCount: 1,
+          deletedLocalCount: 2,
+          directoryCount: 1,
+          dryRun: true,
+          plainFileCount: 0,
+          preview: ["bundle", "bundle/token.txt"],
+          symlinkCount: 0,
+          syncDirectory: "/tmp/sync",
+        },
+        push: {
+          configPath: "/tmp/sync/config.json",
+          deletedArtifactCount: 1,
+          directoryCount: 1,
+          dryRun: true,
+          encryptedFileCount: 1,
+          plainFileCount: 0,
+          preview: ["bundle", "bundle/token.txt"],
+          symlinkCount: 0,
+          syncDirectory: "/tmp/sync",
+        },
+        recipientCount: 1,
+        ruleCount: 0,
+        syncDirectory: "/tmp/sync",
+      }),
+    ).toContain("Push preview: bundle, bundle/token.txt\n");
+    expect(
+      formatSyncDoctorResult({
+        checks: [
+          { detail: "ok", level: "ok", name: "git" },
+          { detail: "warn", level: "warn", name: "entries" },
+          { detail: "fail", level: "fail", name: "age" },
+        ],
+        configPath: "/tmp/sync/config.json",
+        hasFailures: true,
+        hasWarnings: true,
+        syncDirectory: "/tmp/sync",
+      }),
+    ).toContain("Summary: 1 ok, 1 warnings, 1 failures.\n");
+  });
 });

package/src/cli/sync-output.ts

@@ -1,10 +1,13 @@
 import { ensureTrailingNewline } from "#app/lib/string.ts";
 import type { SyncAddResult } from "#app/services/add.ts";
+import type { SyncDoctorResult } from "#app/services/doctor.ts";
 import type { SyncForgetResult } from "#app/services/forget.ts";
 import type { SyncInitResult } from "#app/services/init.ts";
+import type { SyncListResult } from "#app/services/list.ts";
 import type { SyncPullResult } from "#app/services/pull.ts";
 import type { SyncPushResult } from "#app/services/push.ts";
 import type { SyncSetResult } from "#app/services/set.ts";
+import type { SyncStatusResult } from "#app/services/status.ts";
 
 export const formatSyncInitResult = (result: SyncInitResult) => {
   const lines = [
@@ -127,3 +130,71 @@ export const formatSyncPullResult = (result: SyncPullResult) => {
 
   return ensureTrailingNewline(lines.join("\n"));
 };
+
+export const formatSyncListResult = (result: SyncListResult) => {
+  const lines = [
+    "Tracked sync configuration.",
+    `Sync directory: ${result.syncDirectory}`,
+    `Config file: ${result.configPath}`,
+    `Summary: ${result.recipientCount} recipients, ${result.entries.length} entries, ${result.ruleCount} rules.`,
+    ...(result.entries.length === 0
+      ? ["Entries: none"]
+      : result.entries.flatMap((entry) => {
+          return [
+            `- ${entry.repoPath} [${entry.kind}, ${entry.mode}] -> ${entry.localPath}`,
+            ...(entry.overrides.length === 0
+              ? []
+              : entry.overrides.map((override) => {
+                  return `  override ${override.selector}: ${override.mode}`;
+                })),
+          ];
+        })),
+  ];
+
+  return ensureTrailingNewline(lines.join("\n"));
+};
+
+export const formatSyncStatusResult = (result: SyncStatusResult) => {
+  const lines = [
+    "Sync status overview.",
+    `Sync directory: ${result.syncDirectory}`,
+    `Config file: ${result.configPath}`,
+    `Summary: ${result.recipientCount} recipients, ${result.entryCount} entries, ${result.ruleCount} rules.`,
+    `Push plan: ${result.push.plainFileCount} plain files, ${result.push.encryptedFileCount} encrypted files, ${result.push.symlinkCount} symlinks, ${result.push.directoryCount} directory roots, ${result.push.deletedArtifactCount} stale repository artifacts.`,
+    ...(result.push.preview.length === 0
+      ? ["Push preview: no tracked paths"]
+      : [`Push preview: ${result.push.preview.join(", ")}`]),
+    `Pull plan: ${result.pull.plainFileCount} plain files, ${result.pull.decryptedFileCount} decrypted files, ${result.pull.symlinkCount} symlinks, ${result.pull.directoryCount} directory roots, ${result.pull.deletedLocalCount} local paths.`,
+    ...(result.pull.preview.length === 0
+      ? ["Pull preview: no tracked paths"]
+      : [`Pull preview: ${result.pull.preview.join(", ")}`]),
+  ];
+
+  return ensureTrailingNewline(lines.join("\n"));
+};
+
+export const formatSyncDoctorResult = (result: SyncDoctorResult) => {
+  const counts = result.checks.reduce(
+    (accumulator, check) => {
+      accumulator[check.level] += 1;
+
+      return accumulator;
+    },
+    {
+      fail: 0,
+      ok: 0,
+      warn: 0,
+    },
+  );
+  const lines = [
+    result.hasFailures ? "Sync doctor found issues." : "Sync doctor passed.",
+    `Sync directory: ${result.syncDirectory}`,
+    `Config file: ${result.configPath}`,
+    `Summary: ${counts.ok} ok, ${counts.warn} warnings, ${counts.fail} failures.`,
+    ...result.checks.map((check) => {
+      return `[${check.level.toUpperCase()}] ${check.name}: ${check.detail}`;
+    }),
+  ];
+
+  return ensureTrailingNewline(lines.join("\n"));
+};

package/src/services/doctor.ts

@@ -0,0 +1,142 @@
+import { readSyncConfig } from "#app/config/sync.ts";
+
+import { countConfiguredRules } from "./config-file.ts";
+import { pathExists } from "./filesystem.ts";
+import { ensureRepository } from "./git.ts";
+import type { SyncContext } from "./runtime.ts";
+
+export type DoctorCheckLevel = "fail" | "ok" | "warn";
+
+export type DoctorCheck = Readonly<{
+  detail: string;
+  level: DoctorCheckLevel;
+  name: string;
+}>;
+
+export type SyncDoctorResult = Readonly<{
+  checks: readonly DoctorCheck[];
+  configPath: string;
+  hasFailures: boolean;
+  hasWarnings: boolean;
+  syncDirectory: string;
+}>;
+
+const ok = (name: string, detail: string): DoctorCheck => ({
+  detail,
+  level: "ok",
+  name,
+});
+
+const warn = (name: string, detail: string): DoctorCheck => ({
+  detail,
+  level: "warn",
+  name,
+});
+
+const fail = (name: string, detail: string): DoctorCheck => ({
+  detail,
+  level: "fail",
+  name,
+});
+
+export const runSyncDoctor = async (
+  context: SyncContext,
+): Promise<SyncDoctorResult> => {
+  const checks: DoctorCheck[] = [];
+
+  try {
+    await ensureRepository(context.paths.syncDirectory);
+    checks.push(ok("git", "Sync directory is a git repository."));
+  } catch (error: unknown) {
+    checks.push(
+      fail(
+        "git",
+        error instanceof Error ? error.message : "Git repository check failed.",
+      ),
+    );
+
+    return {
+      checks,
+      configPath: context.paths.configPath,
+      hasFailures: true,
+      hasWarnings: false,
+      syncDirectory: context.paths.syncDirectory,
+    };
+  }
+
+  let config: Awaited<ReturnType<typeof readSyncConfig>>;
+
+  try {
+    config = await readSyncConfig(
+      context.paths.syncDirectory,
+      context.environment,
+    );
+    checks.push(
+      ok(
+        "config",
+        `Loaded config with ${config.entries.length} entries, ${countConfiguredRules(config)} rules, and ${config.age.recipients.length} recipients.`,
+      ),
+    );
+  } catch (error: unknown) {
+    checks.push(
+      fail(
+        "config",
+        error instanceof Error
+          ? error.message
+          : "Sync configuration could not be read.",
+      ),
+    );
+
+    return {
+      checks,
+      configPath: context.paths.configPath,
+      hasFailures: true,
+      hasWarnings: false,
+      syncDirectory: context.paths.syncDirectory,
+    };
+  }
+
+  checks.push(
+    (await pathExists(config.age.identityFile))
+      ? ok("age", `Age identity file exists at ${config.age.identityFile}.`)
+      : fail("age", `Age identity file is missing: ${config.age.identityFile}`),
+  );
+
+  checks.push(
+    config.entries.length === 0
+      ? warn("entries", "No sync entries are configured yet.")
+      : ok("entries", `Tracked ${config.entries.length} sync entries.`),
+  );
+
+  const missingEntries = config.entries.filter((entry) => {
+    return !context.environment || entry.localPath.length > 0;
+  });
+
+  let missingCount = 0;
+
+  for (const entry of missingEntries) {
+    if (!(await pathExists(entry.localPath))) {
+      missingCount += 1;
+    }
+  }
+
+  checks.push(
+    missingCount === 0
+      ? ok("local-paths", "All tracked local paths currently exist.")
+      : warn(
+          "local-paths",
+          `${missingCount} tracked local path${missingCount === 1 ? " is" : "s are"} missing.`,
+        ),
+  );
+
+  const hasFailures = checks.some((check) => check.level === "fail");
+  const hasWarnings = checks.some((check) => check.level === "warn");
+
+  return {
+    checks,
+    configPath: context.paths.configPath,
+    hasFailures,
+    hasWarnings,
+    syncDirectory: context.paths.syncDirectory,
+  };
+};

package/src/services/list.ts

@@ -0,0 +1,63 @@
+import {
+  formatSyncOverrideSelector,
+  readSyncConfig,
+  type SyncMode,
+} from "#app/config/sync.ts";
+
+import { countConfiguredRules } from "./config-file.ts";
+import { ensureSyncRepository, type SyncContext } from "./runtime.ts";
+
+export type SyncListOverride = Readonly<{
+  mode: SyncMode;
+  selector: string;
+}>;
+
+export type SyncListEntry = Readonly<{
+  kind: "directory" | "file";
+  localPath: string;
+  mode: SyncMode;
+  name: string;
+  overrides: readonly SyncListOverride[];
+  repoPath: string;
+}>;
+
+export type SyncListResult = Readonly<{
+  configPath: string;
+  entries: readonly SyncListEntry[];
+  recipientCount: number;
+  ruleCount: number;
+  syncDirectory: string;
+}>;
+
+export const listSyncConfig = async (
+  context: SyncContext,
+): Promise<SyncListResult> => {
+  await ensureSyncRepository(context);
+
+  const config = await readSyncConfig(
+    context.paths.syncDirectory,
+    context.environment,
+  );
+
+  return {
+    configPath: context.paths.configPath,
+    entries: config.entries.map((entry) => {
+      return {
+        kind: entry.kind,
+        localPath: entry.localPath,
+        mode: entry.mode,
+        name: entry.name,
+        overrides: entry.overrides.map((override) => {
+          return {
+            mode: override.mode,
+            selector: formatSyncOverrideSelector(override),
+          };
+        }),
+        repoPath: entry.repoPath,
+      };
+    }),
+    recipientCount: config.age.recipients.length,
+    ruleCount: countConfiguredRules(config),
+    syncDirectory: context.paths.syncDirectory,
+  };
+};

package/src/services/local-materialization.ts

@@ -316,8 +316,8 @@ export const countDeletedLocalNodes = async (
   entry: ResolvedSyncConfigEntry,
   desiredKeys: ReadonlySet<string>,
   config: ResolvedSyncConfig,
+  existingKeys: Set<string> = new Set<string>(),
 ) => {
-  const existingKeys = new Set<string>();
   const preservedIgnoredKeys = new Set<string>();
 
   await collectLocalLeafKeys(entry.localPath, entry.repoPath, existingKeys);

package/src/services/pull.ts

@@ -1,4 +1,4 @@
-import { readSyncConfig } from "#app/config/sync.ts";
+import { type ResolvedSyncConfig, readSyncConfig } from "#app/config/sync.ts";
 
 import {
   applyEntryMaterialization,
@@ -24,16 +24,32 @@ export type SyncPullResult = Readonly<{
   syncDirectory: string;
 }>;
 
-export const pullSync = async (
-  request: SyncPullRequest,
-  context: SyncContext,
-): Promise<SyncPullResult> => {
-  await ensureSyncRepository(context);
+export type PullPlan = Readonly<{
+  counts: ReturnType<typeof buildPullCounts>;
+  deletedLocalCount: number;
+  desiredKeys: ReadonlySet<string>;
+  existingKeys: ReadonlySet<string>;
+  materializations: readonly ReturnType<typeof buildEntryMaterialization>[];
+}>;
 
-  const config = await readSyncConfig(
-    context.paths.syncDirectory,
-    context.environment,
-  );
+const collectDesiredKeys = (
+  materializations: readonly ReturnType<typeof buildEntryMaterialization>[],
+) => {
+  const keys = new Set<string>();
+
+  for (const materialization of materializations) {
+    for (const key of materialization.desiredKeys) {
+      keys.add(key);
+    }
+  }
+
+  return keys;
+};
+
+export const buildPullPlan = async (
+  config: ResolvedSyncConfig,
+  context: SyncContext,
+): Promise<PullPlan> => {
   const snapshot = await buildRepositorySnapshot(
     context.paths.syncDirectory,
     config,
@@ -43,6 +59,7 @@ export const pullSync = async (
   });
 
   let deletedLocalCount = 0;
+  const existingKeys = new Set<string>();
 
   for (let index = 0; index < config.entries.length; index += 1) {
     const entry = config.entries[index];
@@ -56,20 +73,72 @@ export const pullSync = async (
       entry,
       materialization.desiredKeys,
       config,
+      existingKeys,
     );
-
-    if (!request.dryRun) {
-      await applyEntryMaterialization(entry, materialization, config);
-    }
   }
 
-  const counts = buildPullCounts(materializations);
+  return {
+    counts: buildPullCounts(materializations),
+    deletedLocalCount,
+    desiredKeys: collectDesiredKeys(materializations),
+    existingKeys,
+    materializations,
+  };
+};
 
+export const buildPullPlanPreview = (plan: PullPlan) => {
+  const desired = [...plan.desiredKeys].sort((left, right) => {
+    return left.localeCompare(right);
+  });
+  const deleted = [...plan.existingKeys]
+    .filter((key) => {
+      return !plan.desiredKeys.has(key);
+    })
+    .sort((left, right) => {
+      return left.localeCompare(right);
+    });
+
+  return [...desired.slice(0, 4), ...deleted.slice(0, 4)].slice(0, 6);
+};
+
+export const buildPullResultFromPlan = (
+  plan: PullPlan,
+  context: SyncContext,
+  dryRun: boolean,
+): SyncPullResult => {
   return {
     configPath: context.paths.configPath,
-    deletedLocalCount,
-    dryRun: request.dryRun,
+    deletedLocalCount: plan.deletedLocalCount,
+    dryRun,
     syncDirectory: context.paths.syncDirectory,
-    ...counts,
+    ...plan.counts,
   };
 };
+
+export const pullSync = async (
+  request: SyncPullRequest,
+  context: SyncContext,
+): Promise<SyncPullResult> => {
+  await ensureSyncRepository(context);
+
+  const config = await readSyncConfig(
+    context.paths.syncDirectory,
+    context.environment,
+  );
+  const plan = await buildPullPlan(config, context);
+
+  for (let index = 0; index < config.entries.length; index += 1) {
+    const entry = config.entries[index];
+    const materialization = plan.materializations[index];
+
+    if (entry === undefined || materialization === undefined) {
+      continue;
+    }
+
+    if (!request.dryRun) {
+      await applyEntryMaterialization(entry, materialization, config);
+    }
+  }
+
+  return buildPullResultFromPlan(plan, context, request.dryRun);
+};

package/src/services/push.ts

@@ -2,6 +2,7 @@ import { mkdtemp, rm } from "node:fs/promises";
 import { join } from "node:path";
 
 import {
+  type ResolvedSyncConfig,
   readSyncConfig,
   resolveSyncArtifactsDirectoryPath,
 } from "#app/config/sync.ts";
@@ -31,6 +32,14 @@ export type SyncPushResult = Readonly<{
   syncDirectory: string;
 }>;
 
+export type PushPlan = Readonly<{
+  counts: ReturnType<typeof buildPushCounts>;
+  deletedArtifactCount: number;
+  desiredArtifactKeys: ReadonlySet<string>;
+  existingArtifactKeys: ReadonlySet<string>;
+  snapshot: ReadonlyMap<string, SnapshotNode>;
+}>;
+
 const buildPushCounts = (snapshot: ReadonlyMap<string, SnapshotNode>) => {
   let directoryCount = 0;
   let encryptedFileCount = 0;
@@ -63,16 +72,10 @@ const buildPushCounts = (snapshot: ReadonlyMap<string, SnapshotNode>) => {
   };
 };
 
-export const pushSync = async (
-  request: SyncPushRequest,
+export const buildPushPlan = async (
+  config: ResolvedSyncConfig,
   context: SyncContext,
-): Promise<SyncPushResult> => {
-  await ensureSyncRepository(context);
-
-  const config = await readSyncConfig(
-    context.paths.syncDirectory,
-    context.environment,
-  );
+): Promise<PushPlan> => {
   const snapshot = await buildLocalSnapshot(config);
   const artifacts = await buildRepoArtifacts(snapshot, config);
   const desiredArtifactKeys = new Set(
@@ -88,6 +91,56 @@ export const pushSync = async (
     return !desiredArtifactKeys.has(key);
   }).length;
 
+  return {
+    counts: buildPushCounts(snapshot),
+    deletedArtifactCount,
+    desiredArtifactKeys,
+    existingArtifactKeys,
+    snapshot,
+  };
+};
+
+export const buildPushPlanPreview = (plan: PushPlan) => {
+  const createdOrUpdated = [...plan.snapshot.keys()].sort((left, right) => {
+    return left.localeCompare(right);
+  });
+  const deleted = [...plan.existingArtifactKeys]
+    .filter((key) => {
+      return !plan.desiredArtifactKeys.has(key);
+    })
+    .sort((left, right) => {
+      return left.localeCompare(right);
+    });
+
+  return [...createdOrUpdated.slice(0, 4), ...deleted.slice(0, 4)].slice(0, 6);
+};
+
+export const buildPushResultFromPlan = (
+  plan: PushPlan,
+  context: SyncContext,
+  dryRun: boolean,
+): SyncPushResult => {
+  return {
+    configPath: context.paths.configPath,
+    deletedArtifactCount: plan.deletedArtifactCount,
+    dryRun,
+    syncDirectory: context.paths.syncDirectory,
+    ...plan.counts,
+  };
+};
+
+export const pushSync = async (
+  request: SyncPushRequest,
+  context: SyncContext,
+): Promise<SyncPushResult> => {
+  await ensureSyncRepository(context);
+
+  const config = await readSyncConfig(
+    context.paths.syncDirectory,
+    context.environment,
+  );
+  const plan = await buildPushPlan(config, context);
+
   if (!request.dryRun) {
     const stagingRoot = await mkdtemp(
       join(context.paths.syncDirectory, ".devsync-sync-push-"),
@@ -95,6 +148,8 @@ export const pushSync = async (
     const nextArtifactsDirectory = join(stagingRoot, "files");
 
     try {
+      const artifacts = await buildRepoArtifacts(plan.snapshot, config);
+
       await writeArtifactsToDirectory(nextArtifactsDirectory, artifacts);
 
       await replacePathAtomically(
@@ -109,13 +164,5 @@ export const pushSync = async (
     }
   }
 
-  const counts = buildPushCounts(snapshot);
-
-  return {
-    configPath: context.paths.configPath,
-    deletedArtifactCount,
-    dryRun: request.dryRun,
-    syncDirectory: context.paths.syncDirectory,
-    ...counts,
-  };
+  return buildPushResultFromPlan(plan, context, request.dryRun);
 };

package/src/services/status.ts

@@ -0,0 +1,57 @@
+import { readSyncConfig } from "#app/config/sync.ts";
+
+import { countConfiguredRules } from "./config-file.ts";
+import {
+  buildPullPlan,
+  buildPullPlanPreview,
+  buildPullResultFromPlan,
+} from "./pull.ts";
+import {
+  buildPushPlan,
+  buildPushPlanPreview,
+  buildPushResultFromPlan,
+} from "./push.ts";
+import { ensureSyncRepository, type SyncContext } from "./runtime.ts";
+
+export type SyncStatusResult = Readonly<{
+  configPath: string;
+  entryCount: number;
+  pull: ReturnType<typeof buildPullResultFromPlan> & {
+    preview: readonly string[];
+  };
+  push: ReturnType<typeof buildPushResultFromPlan> & {
+    preview: readonly string[];
+  };
+  recipientCount: number;
+  ruleCount: number;
+  syncDirectory: string;
+}>;
+
+export const getSyncStatus = async (
+  context: SyncContext,
+): Promise<SyncStatusResult> => {
+  await ensureSyncRepository(context);
+
+  const config = await readSyncConfig(
+    context.paths.syncDirectory,
+    context.environment,
+  );
+  const pushPlan = await buildPushPlan(config, context);
+  const pullPlan = await buildPullPlan(config, context);
+
+  return {
+    configPath: context.paths.configPath,
+    entryCount: config.entries.length,
+    pull: {
+      ...buildPullResultFromPlan(pullPlan, context, true),
+      preview: buildPullPlanPreview(pullPlan),
+    },
+    push: {
+      ...buildPushResultFromPlan(pushPlan, context, true),
+      preview: buildPushPlanPreview(pushPlan),
+    },
+    recipientCount: config.age.recipients.length,
+    ruleCount: countConfiguredRules(config),
+    syncDirectory: context.paths.syncDirectory,
+  };
+};

package/src/services/sync.service.test.ts

@@ -5,13 +5,16 @@ import { afterEach, describe, expect, it } from "vitest";
 
 import { syncSecretArtifactSuffix } from "#app/config/sync.ts";
 import { addSyncTarget } from "#app/services/add.ts";
+import { runSyncDoctor } from "#app/services/doctor.ts";
 import { DevsyncError } from "#app/services/error.ts";
 import { forgetSyncTarget } from "#app/services/forget.ts";
 import { initializeSync } from "#app/services/init.ts";
+import { listSyncConfig } from "#app/services/list.ts";
 import { pullSync } from "#app/services/pull.ts";
 import { pushSync } from "#app/services/push.ts";
 import { createSyncContext } from "#app/services/runtime.ts";
 import { setSyncTargetMode } from "#app/services/set.ts";
+import { getSyncStatus } from "#app/services/status.ts";
 import {
   createAgeKeyPair,
   createTemporaryDirectory,
@@ -1022,4 +1025,145 @@ describe("sync service", () => {
       ),
     ).rejects.toThrowError();
   });
+
+  it("lists tracked entries with overrides", async () => {
+    const workspace = await createWorkspace();
+    const homeDirectory = join(workspace, "home");
+    const xdgConfigHome = join(workspace, "xdg");
+    const bundleDirectory = join(homeDirectory, "bundle");
+    const tokenFile = join(bundleDirectory, "token.txt");
+    const ageKeys = await createAgeKeyPair();
+
+    await writeIdentityFile(xdgConfigHome, ageKeys.identity);
+    await mkdir(bundleDirectory, { recursive: true });
+    await writeFile(tokenFile, "secret\n");
+
+    const context = createSyncContext({
+      environment: createSyncEnvironment(homeDirectory, xdgConfigHome),
+    });
+
+    await initializeSync(
+      {
+        identityFile: "$XDG_CONFIG_HOME/devsync/age/keys.txt",
+        recipients: [ageKeys.recipient],
+      },
+      context,
+    );
+    await addSyncTarget(
+      {
+        secret: false,
+        target: bundleDirectory,
+      },
+      context,
+    );
+    await setSyncTargetMode(
+      {
+        recursive: false,
+        state: "secret",
+        target: tokenFile,
+      },
+      context,
+    );
+
+    const result = await listSyncConfig(context);
+
+    expect(result.entries).toEqual([
+      {
+        kind: "directory",
+        localPath: bundleDirectory,
+        mode: "normal",
+        name: "bundle",
+        overrides: [{ mode: "secret", selector: "token.txt" }],
+        repoPath: "bundle",
+      },
+    ]);
+    expect(result.ruleCount).toBe(1);
+  });
+
+  it("builds status previews for push and pull plans", async () => {
+    const workspace = await createWorkspace();
+    const homeDirectory = join(workspace, "home");
+    const xdgConfigHome = join(workspace, "xdg");
+    const bundleDirectory = join(homeDirectory, "bundle");
+    const plainFile = join(bundleDirectory, "plain.txt");
+    const ageKeys = await createAgeKeyPair();
+
+    await writeIdentityFile(xdgConfigHome, ageKeys.identity);
+    await mkdir(bundleDirectory, { recursive: true });
+    await writeFile(plainFile, "plain\n");
+
+    const context = createSyncContext({
+      environment: createSyncEnvironment(homeDirectory, xdgConfigHome),
+    });
+
+    await initializeSync(
+      {
+        identityFile: "$XDG_CONFIG_HOME/devsync/age/keys.txt",
+        recipients: [ageKeys.recipient],
+      },
+      context,
+    );
+    await addSyncTarget(
+      {
+        secret: false,
+        target: bundleDirectory,
+      },
+      context,
+    );
+    await pushSync(
+      {
+        dryRun: false,
+      },
+      context,
+    );
+
+    const status = await getSyncStatus(context);
+
+    expect(status.push.preview).toContain("bundle/plain.txt");
+    expect(status.pull.preview).toContain("bundle/plain.txt");
+    expect(status.push.plainFileCount).toBe(1);
+    expect(status.pull.plainFileCount).toBe(1);
+  });
+
+  it("reports doctor warnings for missing tracked local paths", async () => {
+    const workspace = await createWorkspace();
+    const homeDirectory = join(workspace, "home");
+    const xdgConfigHome = join(workspace, "xdg");
+    const trackedFile = join(homeDirectory, ".gitconfig");
+    const ageKeys = await createAgeKeyPair();
+
+    await writeIdentityFile(xdgConfigHome, ageKeys.identity);
+    await mkdir(homeDirectory, { recursive: true });
+    await writeFile(trackedFile, "[user]\n  name = test\n");
+
+    const context = createSyncContext({
+      environment: createSyncEnvironment(homeDirectory, xdgConfigHome),
+    });
+
+    await initializeSync(
+      {
+        identityFile: "$XDG_CONFIG_HOME/devsync/age/keys.txt",
+        recipients: [ageKeys.recipient],
+      },
+      context,
+    );
+    await addSyncTarget(
+      {
+        secret: false,
+        target: trackedFile,
+      },
+      context,
+    );
+    await rm(trackedFile);
+
+    const result = await runSyncDoctor(context);
+
+    expect(result.hasFailures).toBe(false);
+    expect(result.hasWarnings).toBe(true);
+    expect(result.checks).toContainEqual({
+      detail: "1 tracked local path is missing.",
+      level: "warn",
+      name: "local-paths",
+    });
+  });
 });