ctx-sync 1.0.0

package/dist/core/services-handler.js

@@ -0,0 +1,176 @@
+/**
+ * Services handler module.
+ *
+ * Manages running-service state: dev servers, background processes,
+ * and any port-bound services associated with a project. Services are
+ * persisted in `services.age` (encrypted) and restored via the command
+ * approval workflow — no command is ever auto-executed.
+ *
+ * @module core/services-handler
+ */
+import { readState, writeState } from './state-manager.js';
+// ─── Helpers ──────────────────────────────────────────────────────────────
+/**
+ * Build an empty `ServiceState`.
+ */
+function emptyState() {
+    return { services: [] };
+}
+// ─── Public API ───────────────────────────────────────────────────────────
+/**
+ * Create a new `Service` entry.
+ *
+ * @param project   - The project name this service belongs to.
+ * @param name      - Human-readable service name (e.g. "api-server").
+ * @param port      - Port the service listens on.
+ * @param command   - Shell command to start the service.
+ * @param autoStart - Whether the service should be suggested on restore.
+ * @returns A typed `Service` object.
+ */
+export function createService(project, name, port, command, autoStart = false) {
+    return { project, name, port, command, autoStart };
+}
+/**
+ * Validate a service entry.
+ *
+ * Checks:
+ *  - name is non-empty
+ *  - port is a positive integer in range 1–65535
+ *  - command is non-empty
+ *
+ * @returns An array of human-readable error strings (empty = valid).
+ */
+export function validateService(service) {
+    const errors = [];
+    if (!service.name || service.name.trim().length === 0) {
+        errors.push('Service name cannot be empty.');
+    }
+    if (!service.command || service.command.trim().length === 0) {
+        errors.push('Service command cannot be empty.');
+    }
+    if (!Number.isInteger(service.port) ||
+        service.port < 1 ||
+        service.port > 65535) {
+        errors.push(`Port must be an integer between 1 and 65535, got ${String(service.port)}.`);
+    }
+    return errors;
+}
+/**
+ * Load all services from encrypted state.
+ *
+ * @param syncDir    - The sync directory (e.g. ~/.context-sync).
+ * @param privateKey - Age private key for decryption.
+ * @returns The decrypted `ServiceState`, or an empty state if the file
+ *          does not exist.
+ */
+export async function loadServices(syncDir, privateKey) {
+    const state = await readState(syncDir, privateKey, 'services');
+    return state ?? emptyState();
+}
+/**
+ * Load services for a specific project.
+ *
+ * @param syncDir    - The sync directory.
+ * @param privateKey - Age private key.
+ * @param project    - Project name to filter by.
+ * @returns Array of services belonging to the project (may be empty).
+ */
+export async function loadProjectServices(syncDir, privateKey, project) {
+    const state = await loadServices(syncDir, privateKey);
+    return state.services.filter((s) => s.project === project);
+}
+/**
+ * Save (overwrite) the entire services state.
+ *
+ * @param syncDir   - The sync directory.
+ * @param state     - The complete `ServiceState` to persist.
+ * @param publicKey - Age public key for encryption.
+ */
+export async function saveServices(syncDir, state, publicKey) {
+    await writeState(syncDir, state, publicKey, 'services');
+}
+/**
+ * Add a service to the encrypted state.
+ *
+ * If a service with the same project + name already exists, it is
+ * replaced (upsert semantics).
+ *
+ * @param syncDir    - The sync directory.
+ * @param service    - The service to add/replace.
+ * @param publicKey  - Age public key for encryption.
+ * @param privateKey - Age private key for decryption (needed to read existing state).
+ */
+export async function addService(syncDir, service, publicKey, privateKey) {
+    const state = await loadServices(syncDir, privateKey);
+    // Remove any existing entry with the same project + name (upsert)
+    state.services = state.services.filter((s) => !(s.project === service.project && s.name === service.name));
+    state.services.push(service);
+    await saveServices(syncDir, state, publicKey);
+}
+/**
+ * Remove a service by project + name.
+ *
+ * @param syncDir    - The sync directory.
+ * @param project    - Project name.
+ * @param name       - Service name.
+ * @param publicKey  - Age public key for encryption.
+ * @param privateKey - Age private key for decryption.
+ * @returns `true` if a service was removed, `false` if it was not found.
+ */
+export async function removeService(syncDir, project, name, publicKey, privateKey) {
+    const state = await loadServices(syncDir, privateKey);
+    const before = state.services.length;
+    state.services = state.services.filter((s) => !(s.project === project && s.name === name));
+    if (state.services.length === before) {
+        return false;
+    }
+    await saveServices(syncDir, state, publicKey);
+    return true;
+}
+/**
+ * Remove all services for a project.
+ *
+ * @param syncDir    - The sync directory.
+ * @param project    - Project name.
+ * @param publicKey  - Age public key for encryption.
+ * @param privateKey - Age private key for decryption.
+ * @returns Number of services removed.
+ */
+export async function removeProjectServices(syncDir, project, publicKey, privateKey) {
+    const state = await loadServices(syncDir, privateKey);
+    const before = state.services.length;
+    state.services = state.services.filter((s) => s.project !== project);
+    const removed = before - state.services.length;
+    if (removed > 0) {
+        await saveServices(syncDir, state, publicKey);
+    }
+    return removed;
+}
+/**
+ * List unique project names that have services.
+ *
+ * @param syncDir    - The sync directory.
+ * @param privateKey - Age private key.
+ * @returns Sorted array of project names.
+ */
+export async function listServiceProjects(syncDir, privateKey) {
+    const state = await loadServices(syncDir, privateKey);
+    const projects = new Set(state.services.map((s) => s.project));
+    return [...projects].sort();
+}
+/**
+ * Get services that are marked as auto-start for a project.
+ *
+ * These are the services that `ctx-sync restore` or
+ * `ctx-sync service start` should suggest starting.
+ *
+ * @param syncDir    - The sync directory.
+ * @param privateKey - Age private key.
+ * @param project    - Project name.
+ * @returns Services marked with `autoStart: true`.
+ */
+export async function getAutoStartServices(syncDir, privateKey, project) {
+    const services = await loadProjectServices(syncDir, privateKey, project);
+    return services.filter((s) => s.autoStart);
+}
+//# sourceMappingURL=services-handler.js.map

package/dist/core/services-handler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"services-handler.js","sourceRoot":"","sources":["../../src/core/services-handler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAE3D,6EAA6E;AAE7E;;GAEG;AACH,SAAS,UAAU;IACjB,OAAO,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAC;AAC1B,CAAC;AAED,6EAA6E;AAE7E;;;;;;;;;GASG;AACH,MAAM,UAAU,aAAa,CAC3B,OAAe,EACf,IAAY,EACZ,IAAY,EACZ,OAAe,EACf,SAAS,GAAG,KAAK;IAEjB,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,SAAS,EAAE,CAAC;AACrD,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,eAAe,CAAC,OAAgB;IAC9C,MAAM,MAAM,GAAa,EAAE,CAAC;IAE5B,IAAI,CAAC,OAAO,CAAC,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACtD,MAAM,CAAC,IAAI,CAAC,+BAA+B,CAAC,CAAC;IAC/C,CAAC;IACD,IAAI,CAAC,OAAO,CAAC,OAAO,IAAI,OAAO,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC5D,MAAM,CAAC,IAAI,CAAC,kCAAkC,CAAC,CAAC;IAClD,CAAC;IACD,IACE,CAAC,MAAM,CAAC,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC;QAC/B,OAAO,CAAC,IAAI,GAAG,CAAC;QAChB,OAAO,CAAC,IAAI,GAAG,KAAK,EACpB,CAAC;QACD,MAAM,CAAC,IAAI,CACT,oDAAoD,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,GAAG,CAC5E,CAAC;IACJ,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,OAAe,EACf,UAAkB;IAElB,MAAM,KAAK,GAAG,MAAM,SAAS,CAAe,OAAO,EAAE,UAAU,EAAE,UAAU,CAAC,CAAC;IAC7E,OAAO,KAAK,IAAI,UAAU,EAAE,CAAC;AAC/B,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CACvC,OAAe,EACf,UAAkB,EAClB,OAAe;IAEf,MAAM,KAAK,GAAG,MAAM,YAAY,CAAC,OAAO,EAAE,UAAU,CAAC,CAAC;IACtD,OAAO,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,KAAK,OAAO,CAAC,CAAC;AAC7D,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,OAAe,EACf,KAAmB,EACnB,SAAiB;IAEjB,MAAM,UAAU,CAAC,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,UAAU,CAAC,CAAC;AAC1D,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU,CAC9B,OAAe,EACf,OAAgB,EAChB,SAAiB,EACjB,UAAkB;IAElB,MAAM,KAAK,GAAG,MAAM,YAAY,CAAC,OAAO,EAAE,UAAU,CAAC,CAAC;IAEtD,kEAAkE;IAClE,KAAK,CAAC,QAAQ,GAAG,KAAK,CAAC,QAAQ,CAAC,MAAM,CACpC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,KAAK,OAAO,CAAC,OAAO,IAAI,CAAC,CAAC,IAAI,KAAK,OAAO,CAAC,IAAI,CAAC,CACnE,CAAC;IACF,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IAE7B,MAAM,YAAY,CAAC,OAAO,EAAE,KAAK,EAAE,SAAS,CAAC,CAAC;AAChD,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,OAAe,EACf,OAAe,EACf,IAAY,EACZ,SAAiB,EACjB,UAAkB;IAElB,MAAM,KAAK,GAAG,MAAM,YAAY,CAAC,OAAO,EAAE,UAAU,CAAC,CAAC;IACtD,MAAM,MAAM,GAAG,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC;IACrC,KAAK,CAAC,QAAQ,GAAG,KAAK,CAAC,QAAQ,CAAC,MAAM,CACpC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,KAAK,OAAO,IAAI,CAAC,CAAC,IAAI,KAAK,IAAI,CAAC,CACnD,CAAC;IAEF,IAAI,KAAK,CAAC,QAAQ,CAAC,MAAM,KAAK,MAAM,EAAE,CAAC;QACrC,OAAO,KAAK,CAAC;IACf,CAAC;IAED,MAAM,YAAY,CAAC,OAAO,EAAE,KAAK,EAAE,SAAS,CAAC,CAAC;IAC9C,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,qBAAqB,CACzC,OAAe,EACf,OAAe,EACf,SAAiB,EACjB,UAAkB;IAElB,MAAM,KAAK,GAAG,MAAM,YAAY,CAAC,OAAO,EAAE,UAAU,CAAC,CAAC;IACtD,MAAM,MAAM,GAAG,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC;IACrC,KAAK,CAAC,QAAQ,GAAG,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,KAAK,OAAO,CAAC,CAAC;IACrE,MAAM,OAAO,GAAG,MAAM,GAAG,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC;IAE/C,IAAI,OAAO,GAAG,CAAC,EAAE,CAAC;QAChB,MAAM,YAAY,CAAC,OAAO,EAAE,KAAK,EAAE,SAAS,CAAC,CAAC;IAChD,CAAC;IAED,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CACvC,OAAe,EACf,UAAkB;IAElB,MAAM,KAAK,GAAG,MAAM,YAAY,CAAC,OAAO,EAAE,UAAU,CAAC,CAAC;IACtD,MAAM,QAAQ,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC;IAC/D,OAAO,CAAC,GAAG,QAAQ,CAAC,CAAC,IAAI,EAAE,CAAC;AAC9B,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,oBAAoB,CACxC,OAAe,EACf,UAAkB,EAClB,OAAe;IAEf,MAAM,QAAQ,GAAG,MAAM,mBAAmB,CAAC,OAAO,EAAE,UAAU,EAAE,OAAO,CAAC,CAAC;IACzE,OAAO,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;AAC7C,CAAC"}

package/dist/core/state-manager.d.ts

@@ -0,0 +1,96 @@
+/**
+ * State manager module.
+ *
+ * Provides read/write operations for all encrypted state files (.age)
+ * and the plaintext manifest. State is always encrypted before writing
+ * to disk — no plaintext JSON is ever written (except manifest.json
+ * which contains only version and timestamps).
+ *
+ * @module core/state-manager
+ */
+import type { StateFile, EnvVars, DockerState, MentalContext, ServiceState, DirectoryState, Manifest } from '@ctx-sync/shared';
+/**
+ * Union of all encrypted state data types.
+ */
+export type StateData = StateFile | EnvVars | DockerState | MentalContext | ServiceState | DirectoryState;
+/**
+ * Map of state file type to filename constant.
+ */
+export declare const STATE_FILE_MAP: {
+    readonly state: "state.age";
+    readonly 'env-vars': "env-vars.age";
+    readonly 'docker-state': "docker-state.age";
+    readonly 'mental-context': "mental-context.age";
+    readonly services: "services.age";
+    readonly directories: "directories.age";
+};
+/** Valid state file types */
+export type StateFileType = keyof typeof STATE_FILE_MAP;
+/**
+ * Read and decrypt an encrypted state file.
+ *
+ * Reads the specified `.age` file from the sync directory, decrypts it
+ * using the provided private key, and returns the parsed typed data.
+ *
+ * @param stateDir - The sync directory path (e.g. ~/.context-sync).
+ * @param privateKey - The Age private key for decryption.
+ * @param fileType - The type of state file to read.
+ * @returns The decrypted and parsed state data, or `null` if the file does not exist.
+ * @throws If decryption fails (wrong key, corrupted file, etc.).
+ */
+export declare function readState<T = StateData>(stateDir: string, privateKey: string, fileType: StateFileType): Promise<T | null>;
+/**
+ * Encrypt and write state data to disk.
+ *
+ * Serialises the data as JSON in memory, encrypts it with Age, and writes
+ * the resulting `.age` file. **Never writes plaintext JSON to disk.**
+ *
+ * Supports both single-recipient and multi-recipient encryption. When
+ * `publicKey` is a single string, encrypts for one recipient. When
+ * it is an array, encrypts for all recipients (team support).
+ *
+ * Also updates the manifest to record the file's modification time.
+ *
+ * @param stateDir - The sync directory path.
+ * @param data - The state data to encrypt and write.
+ * @param publicKey - A single Age public key or an array of public keys.
+ * @param fileType - The type of state file to write.
+ * @throws If the filename ends in `.json` (safety check against plaintext writes).
+ */
+export declare function writeState(stateDir: string, data: StateData, publicKey: string | string[], fileType: StateFileType): Promise<void>;
+/**
+ * Read the plaintext manifest.json from the sync directory.
+ *
+ * The manifest contains only version and timestamps — no sensitive data.
+ * If the file does not exist, returns `null`.
+ *
+ * @param stateDir - The sync directory path.
+ * @returns The parsed manifest, or `null` if it does not exist.
+ */
+export declare function readManifest(stateDir: string): Manifest | null;
+/**
+ * Write the plaintext manifest.json to the sync directory.
+ *
+ * The manifest is the only plaintext file in the sync repo.
+ * It contains only version and timestamps — no sensitive data.
+ *
+ * @param stateDir - The sync directory path.
+ * @param data - The manifest data to write.
+ */
+export declare function writeManifest(stateDir: string, data: Manifest): void;
+/**
+ * List all encrypted state files present in the sync directory.
+ *
+ * @param stateDir - The sync directory path.
+ * @returns Array of filenames that exist on disk.
+ */
+export declare function listStateFiles(stateDir: string): string[];
+/**
+ * Check if a specific state file exists in the sync directory.
+ *
+ * @param stateDir - The sync directory path.
+ * @param fileType - The type of state file to check.
+ * @returns `true` if the file exists.
+ */
+export declare function stateFileExists(stateDir: string, fileType: StateFileType): boolean;
+//# sourceMappingURL=state-manager.d.ts.map

package/dist/core/state-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"state-manager.d.ts","sourceRoot":"","sources":["../../src/core/state-manager.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAKH,OAAO,KAAK,EACV,SAAS,EACT,OAAO,EACP,WAAW,EACX,aAAa,EACb,YAAY,EACZ,cAAc,EACd,QAAQ,EACT,MAAM,kBAAkB,CAAC;AAG1B;;GAEG;AACH,MAAM,MAAM,SAAS,GACjB,SAAS,GACT,OAAO,GACP,WAAW,GACX,aAAa,GACb,YAAY,GACZ,cAAc,CAAC;AAEnB;;GAEG;AACH,eAAO,MAAM,cAAc;;;;;;;CAOjB,CAAC;AAEX,6BAA6B;AAC7B,MAAM,MAAM,aAAa,GAAG,MAAM,OAAO,cAAc,CAAC;AAExD;;;;;;;;;;;GAWG;AACH,wBAAsB,SAAS,CAAC,CAAC,GAAG,SAAS,EAC3C,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,aAAa,GACtB,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAenB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,UAAU,CAC9B,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,SAAS,EACf,SAAS,EAAE,MAAM,GAAG,MAAM,EAAE,EAC5B,QAAQ,EAAE,aAAa,GACtB,OAAO,CAAC,IAAI,CAAC,CAwBf;AAED;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,QAAQ,GAAG,IAAI,CAc9D;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,GAAG,IAAI,CAMpE;AAyBD;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,EAAE,CAOzD;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,aAAa,GAAG,OAAO,CAGlF"}

package/dist/core/state-manager.js

@@ -0,0 +1,165 @@
+/**
+ * State manager module.
+ *
+ * Provides read/write operations for all encrypted state files (.age)
+ * and the plaintext manifest. State is always encrypted before writing
+ * to disk — no plaintext JSON is ever written (except manifest.json
+ * which contains only version and timestamps).
+ *
+ * @module core/state-manager
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { STATE_FILES, VERSION } from '@ctx-sync/shared';
+import { encryptState, encryptStateForRecipients, decryptState } from './encryption.js';
+/**
+ * Map of state file type to filename constant.
+ */
+export const STATE_FILE_MAP = {
+    state: STATE_FILES.STATE,
+    'env-vars': STATE_FILES.ENV_VARS,
+    'docker-state': STATE_FILES.DOCKER_STATE,
+    'mental-context': STATE_FILES.MENTAL_CONTEXT,
+    services: STATE_FILES.SERVICES,
+    directories: STATE_FILES.DIRECTORIES,
+};
+/**
+ * Read and decrypt an encrypted state file.
+ *
+ * Reads the specified `.age` file from the sync directory, decrypts it
+ * using the provided private key, and returns the parsed typed data.
+ *
+ * @param stateDir - The sync directory path (e.g. ~/.context-sync).
+ * @param privateKey - The Age private key for decryption.
+ * @param fileType - The type of state file to read.
+ * @returns The decrypted and parsed state data, or `null` if the file does not exist.
+ * @throws If decryption fails (wrong key, corrupted file, etc.).
+ */
+export async function readState(stateDir, privateKey, fileType) {
+    const filename = STATE_FILE_MAP[fileType];
+    const filePath = path.join(stateDir, filename);
+    if (!fs.existsSync(filePath)) {
+        return null;
+    }
+    const ciphertext = fs.readFileSync(filePath, 'utf-8');
+    if (!ciphertext.trim()) {
+        return null;
+    }
+    return decryptState(ciphertext, privateKey);
+}
+/**
+ * Encrypt and write state data to disk.
+ *
+ * Serialises the data as JSON in memory, encrypts it with Age, and writes
+ * the resulting `.age` file. **Never writes plaintext JSON to disk.**
+ *
+ * Supports both single-recipient and multi-recipient encryption. When
+ * `publicKey` is a single string, encrypts for one recipient. When
+ * it is an array, encrypts for all recipients (team support).
+ *
+ * Also updates the manifest to record the file's modification time.
+ *
+ * @param stateDir - The sync directory path.
+ * @param data - The state data to encrypt and write.
+ * @param publicKey - A single Age public key or an array of public keys.
+ * @param fileType - The type of state file to write.
+ * @throws If the filename ends in `.json` (safety check against plaintext writes).
+ */
+export async function writeState(stateDir, data, publicKey, fileType) {
+    const filename = STATE_FILE_MAP[fileType];
+    // Safety check: never write plaintext JSON state files
+    if (filename.endsWith('.json')) {
+        throw new Error(`Cannot write unencrypted state file: ${filename}. ` +
+            'State files must be encrypted as .age files.');
+    }
+    // Ensure the directory exists
+    fs.mkdirSync(stateDir, { recursive: true });
+    // Encrypt for single or multiple recipients
+    const ciphertext = Array.isArray(publicKey)
+        ? await encryptStateForRecipients(data, publicKey)
+        : await encryptState(data, publicKey);
+    const filePath = path.join(stateDir, filename);
+    fs.writeFileSync(filePath, ciphertext, 'utf-8');
+    // Update manifest with new modification timestamp
+    updateManifestEntry(stateDir, filename);
+}
+/**
+ * Read the plaintext manifest.json from the sync directory.
+ *
+ * The manifest contains only version and timestamps — no sensitive data.
+ * If the file does not exist, returns `null`.
+ *
+ * @param stateDir - The sync directory path.
+ * @returns The parsed manifest, or `null` if it does not exist.
+ */
+export function readManifest(stateDir) {
+    const filePath = path.join(stateDir, STATE_FILES.MANIFEST);
+    if (!fs.existsSync(filePath)) {
+        return null;
+    }
+    const content = fs.readFileSync(filePath, 'utf-8');
+    if (!content.trim()) {
+        return null;
+    }
+    return JSON.parse(content);
+}
+/**
+ * Write the plaintext manifest.json to the sync directory.
+ *
+ * The manifest is the only plaintext file in the sync repo.
+ * It contains only version and timestamps — no sensitive data.
+ *
+ * @param stateDir - The sync directory path.
+ * @param data - The manifest data to write.
+ */
+export function writeManifest(stateDir, data) {
+    // Ensure the directory exists
+    fs.mkdirSync(stateDir, { recursive: true });
+    const filePath = path.join(stateDir, STATE_FILES.MANIFEST);
+    fs.writeFileSync(filePath, JSON.stringify(data, null, 2), 'utf-8');
+}
+/**
+ * Update a single entry in the manifest with a new modification timestamp.
+ *
+ * If the manifest does not exist, a new one is created.
+ *
+ * @param stateDir - The sync directory path.
+ * @param filename - The state file name (e.g. 'state.age').
+ */
+function updateManifestEntry(stateDir, filename) {
+    const manifest = readManifest(stateDir) ?? {
+        version: VERSION,
+        lastSync: new Date().toISOString(),
+        files: {},
+    };
+    manifest.files[filename] = {
+        lastModified: new Date().toISOString(),
+    };
+    manifest.lastSync = new Date().toISOString();
+    writeManifest(stateDir, manifest);
+}
+/**
+ * List all encrypted state files present in the sync directory.
+ *
+ * @param stateDir - The sync directory path.
+ * @returns Array of filenames that exist on disk.
+ */
+export function listStateFiles(stateDir) {
+    if (!fs.existsSync(stateDir)) {
+        return [];
+    }
+    const entries = fs.readdirSync(stateDir);
+    return entries.filter((entry) => entry.endsWith('.age'));
+}
+/**
+ * Check if a specific state file exists in the sync directory.
+ *
+ * @param stateDir - The sync directory path.
+ * @param fileType - The type of state file to check.
+ * @returns `true` if the file exists.
+ */
+export function stateFileExists(stateDir, fileType) {
+    const filename = STATE_FILE_MAP[fileType];
+    return fs.existsSync(path.join(stateDir, filename));
+}
+//# sourceMappingURL=state-manager.js.map

package/dist/core/state-manager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"state-manager.js","sourceRoot":"","sources":["../../src/core/state-manager.ts"],"names":[],"mappings":"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"}

package/dist/core/transport.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Transport security validation module.
+ *
+ * Validates Git remote URLs to ensure only secure transport protocols
+ * (SSH and HTTPS) are used. Rejects insecure protocols such as HTTP,
+ * git://, and ftp:// to prevent data exposure in transit.
+ *
+ * @module core/transport
+ */
+/**
+ * Validate that a Git remote URL uses a secure transport protocol.
+ *
+ * Accepts:
+ * - SSH URLs: `git@github.com:user/repo.git`
+ * - HTTPS URLs: `https://github.com/user/repo.git`
+ * - Local paths: `/path/to/repo.git` or `file:///path/to/repo.git`
+ *
+ * Rejects:
+ * - HTTP URLs: `http://...`
+ * - Git protocol: `git://...`
+ * - FTP protocol: `ftp://...`
+ * - Empty or malformed URLs
+ *
+ * @param url - The Git remote URL to validate.
+ * @throws If the URL is empty, malformed, or uses an insecure protocol.
+ */
+export declare function validateRemoteUrl(url: string): void;
+//# sourceMappingURL=transport.d.ts.map

package/dist/core/transport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport.d.ts","sourceRoot":"","sources":["../../src/core/transport.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AASH;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAoEnD"}

package/dist/core/transport.js

@@ -0,0 +1,79 @@
+/**
+ * Transport security validation module.
+ *
+ * Validates Git remote URLs to ensure only secure transport protocols
+ * (SSH and HTTPS) are used. Rejects insecure protocols such as HTTP,
+ * git://, and ftp:// to prevent data exposure in transit.
+ *
+ * @module core/transport
+ */
+/** Allowed transport protocols for Git remotes.
+ *  file: is permitted because local-path remotes have no network transit. */
+const ALLOWED_PROTOCOLS = ['https:', 'ssh:', 'file:'];
+/** SSH remote URL pattern: git@host:user/repo.git */
+const SSH_PATTERN = /^[a-zA-Z0-9._-]+@[a-zA-Z0-9._-]+:.+$/;
+/**
+ * Validate that a Git remote URL uses a secure transport protocol.
+ *
+ * Accepts:
+ * - SSH URLs: `git@github.com:user/repo.git`
+ * - HTTPS URLs: `https://github.com/user/repo.git`
+ * - Local paths: `/path/to/repo.git` or `file:///path/to/repo.git`
+ *
+ * Rejects:
+ * - HTTP URLs: `http://...`
+ * - Git protocol: `git://...`
+ * - FTP protocol: `ftp://...`
+ * - Empty or malformed URLs
+ *
+ * @param url - The Git remote URL to validate.
+ * @throws If the URL is empty, malformed, or uses an insecure protocol.
+ */
+export function validateRemoteUrl(url) {
+    if (!url || typeof url !== 'string') {
+        throw new Error('Git remote URL is required.\n' +
+            'Provide an SSH (git@host:user/repo.git) or HTTPS (https://host/user/repo.git) URL.');
+    }
+    const trimmed = url.trim();
+    if (trimmed.length === 0) {
+        throw new Error('Git remote URL is required.\n' +
+            'Provide an SSH (git@host:user/repo.git) or HTTPS (https://host/user/repo.git) URL.');
+    }
+    // Check for SSH-style URLs first (git@host:user/repo.git)
+    if (SSH_PATTERN.test(trimmed)) {
+        return; // SSH URLs are always secure
+    }
+    // Allow absolute filesystem paths — no network transit, no security concern
+    if (trimmed.startsWith('/')) {
+        return;
+    }
+    // Try to parse as a URL with a protocol
+    let parsed;
+    try {
+        parsed = new URL(trimmed);
+    }
+    catch {
+        throw new Error(`Invalid Git remote URL: ${trimmed}\n` +
+            'Expected SSH (git@host:user/repo.git) or HTTPS (https://host/user/repo.git) URL.');
+    }
+    // Check for insecure protocols with specific error messages
+    if (parsed.protocol === 'http:') {
+        throw new Error(`Insecure Git remote: ${trimmed}\n` +
+            'HTTP transmits data in plaintext. Use HTTPS instead:\n' +
+            `  ${trimmed.replace(/^http:/, 'https:')}`);
+    }
+    if (parsed.protocol === 'git:') {
+        throw new Error(`Insecure Git remote: ${trimmed}\n` +
+            'The git:// protocol transmits data in plaintext. Use SSH or HTTPS instead.');
+    }
+    if (parsed.protocol === 'ftp:') {
+        throw new Error(`Insecure Git remote: ${trimmed}\n` +
+            'FTP transmits data in plaintext. Use SSH or HTTPS instead.');
+    }
+    // Check against allowed protocols
+    if (!ALLOWED_PROTOCOLS.includes(parsed.protocol)) {
+        throw new Error(`Unsupported Git remote protocol: ${parsed.protocol}\n` +
+            'Only SSH and HTTPS are supported.');
+    }
+}
+//# sourceMappingURL=transport.js.map

package/dist/core/transport.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport.js","sourceRoot":"","sources":["../../src/core/transport.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH;6EAC6E;AAC7E,MAAM,iBAAiB,GAAG,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAU,CAAC;AAE/D,qDAAqD;AACrD,MAAM,WAAW,GAAG,sCAAsC,CAAC;AAE3D;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,iBAAiB,CAAC,GAAW;IAC3C,IAAI,CAAC,GAAG,IAAI,OAAO,GAAG,KAAK,QAAQ,EAAE,CAAC;QACpC,MAAM,IAAI,KAAK,CACb,+BAA+B;YAC7B,oFAAoF,CACvF,CAAC;IACJ,CAAC;IAED,MAAM,OAAO,GAAG,GAAG,CAAC,IAAI,EAAE,CAAC;IAE3B,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACzB,MAAM,IAAI,KAAK,CACb,+BAA+B;YAC7B,oFAAoF,CACvF,CAAC;IACJ,CAAC;IAED,0DAA0D;IAC1D,IAAI,WAAW,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;QAC9B,OAAO,CAAC,6BAA6B;IACvC,CAAC;IAED,4EAA4E;IAC5E,IAAI,OAAO,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;QAC5B,OAAO;IACT,CAAC;IAED,wCAAwC;IACxC,IAAI,MAAW,CAAC;IAChB,IAAI,CAAC;QACH,MAAM,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,CAAC;IAC5B,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,KAAK,CACb,2BAA2B,OAAO,IAAI;YACpC,kFAAkF,CACrF,CAAC;IACJ,CAAC;IAED,4DAA4D;IAC5D,IAAI,MAAM,CAAC,QAAQ,KAAK,OAAO,EAAE,CAAC;QAChC,MAAM,IAAI,KAAK,CACb,wBAAwB,OAAO,IAAI;YACjC,wDAAwD;YACxD,KAAK,OAAO,CAAC,OAAO,CAAC,QAAQ,EAAE,QAAQ,CAAC,EAAE,CAC7C,CAAC;IACJ,CAAC;IAED,IAAI,MAAM,CAAC,QAAQ,KAAK,MAAM,EAAE,CAAC;QAC/B,MAAM,IAAI,KAAK,CACb,wBAAwB,OAAO,IAAI;YACjC,4EAA4E,CAC/E,CAAC;IACJ,CAAC;IAED,IAAI,MAAM,CAAC,QAAQ,KAAK,MAAM,EAAE,CAAC;QAC/B,MAAM,IAAI,KAAK,CACb,wBAAwB,OAAO,IAAI;YACjC,4DAA4D,CAC/D,CAAC;IACJ,CAAC;IAED,kCAAkC;IAClC,IAAI,CAAC,iBAAiB,CAAC,QAAQ,CAAC,MAAM,CAAC,QAA8C,CAAC,EAAE,CAAC;QACvF,MAAM,IAAI,KAAK,CACb,oCAAoC,MAAM,CAAC,QAAQ,IAAI;YACrD,mCAAmC,CACtC,CAAC;IACJ,CAAC;AACH,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+/**
+ * ctx-sync — Sync your complete development context across machines.
+ *
+ * CLI entry point. Uses Commander.js for command parsing and routing.
+ *
+ * @module ctx-sync
+ */
+import { Command } from 'commander';
+/**
+ * Create and configure the root CLI program.
+ *
+ * @returns The configured Commander program instance.
+ */
+export declare function createProgram(): Command;
+/**
+ * Main entry point — parse CLI arguments and execute the matched command.
+ */
+export declare function main(argv?: string[]): Promise<void>;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAEA;;;;;;GAMG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAsBpC;;;;GAIG;AACH,wBAAgB,aAAa,IAAI,OAAO,CA6BvC;AAED;;GAEG;AACH,wBAAsB,IAAI,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAGzD"}