@muthuishere/vsync 0.3.0 → 0.5.0

package/src/repoconfig.ts

@@ -33,8 +33,15 @@ export type ConfigFile = {
     gh?: { repo: string };
     gcp?: { project: string };
   };
+  // Optional audit-log block. Absent on disk → defaults to `{ enabled: true }`
+  // (audit is on by default — see SPEC-v0.4 §9). Explicit `{ enabled: false }`
+  // round-trips through save/load unchanged.
+  audit?: { enabled: boolean };
 };
 
+/** Per-(repo, env) audit preference, defaulted. Source of truth for callers. */
+export const DEFAULT_AUDIT_ENABLED = true;
+
 /** Full path for a given (repo, env). env is lowercased; repo is taken as-is. */
 export function configFilePath(repo: string, env: string): string {
   if (!repo) throw new Error("repo is required");
@@ -95,6 +102,10 @@ export async function loadConfigFile(
   const json = gunzipSync(buf).toString("utf8");
   const parsed = JSON.parse(json);
   validateConfigFile(parsed);
+  // Default-on for `audit` — absent block means "enabled" per spec §9.
+  if (parsed.audit === undefined) {
+    parsed.audit = { enabled: DEFAULT_AUDIT_ENABLED };
+  }
   return parsed;
 }
 
@@ -160,4 +171,12 @@ export function validateConfigFile(cfg: unknown): asserts cfg is ConfigFile {
       throw new Error("config: sync.gcp.project must be a string if sync.gcp is present");
     }
   }
+  if (c.audit !== undefined) {
+    if (typeof c.audit !== "object" || c.audit === null) {
+      throw new Error("config: audit must be an object if present");
+    }
+    if (typeof c.audit.enabled !== "boolean") {
+      throw new Error("config: audit.enabled must be a boolean");
+    }
+  }
 }

package/src/templates/docs.md.ts

@@ -73,6 +73,33 @@ plus the salt from the per-repo config. To decrypt by hand:
 
 Easier: just \`vsync pull\` again to restore from S3.
 
+## Audit log
+
+Every \`pull\`, \`push\`, \`import\`, and \`export\` appends a CSV row to
+\`s3://<bucket>/<repo>/<env>/audit.csv\` capturing timestamp, action,
+hostname, local IP, OS user, git email, and a free-form \`meta\` JSON
+cell. Best-effort: an audit-write failure prints a warning and never
+fails the parent command.
+
+On by default. Three ways to opt out:
+
+- \`--no-audit\` on a single invocation
+- \`cfg.audit.enabled: false\` in the per-repo config
+- \`vsync init <env> --audit=off\` at setup (or pick "off" at the first-time prompt)
+
+Tag a row with context via four merging input paths, in increasing
+priority order: \`$VSYNC_AUDIT_META\` (JSON) < \`$VSYNC_AUDIT_NOTE\` <
+\`--meta key=value\` (repeatable) < \`--note=<text>\`. Later sources
+overwrite same-named keys from earlier ones.
+
+View the log with \`vsync audit <env>\` (\`--limit=N\`, \`--all\`, \`--csv\`).
+Pretty table by default, newest first; \`--csv\` is raw passthrough.
+
+Honesty clause: transparency for honest users, not tamper-proof
+(anyone with bucket write can rewrite the file). It can't recover
+already-pulled secrets either — once a teammate has pulled, they hold
+a local copy.
+
 ## Rules for AI agents working in this repo
 
 1. **Never commit anything under \`infra/vault/\`.** Add it to