ctx-sync 1.0.0

package/dist/core/path-validator.js

@@ -0,0 +1,127 @@
+/**
+ * Path validation module.
+ *
+ * Validates and canonicalises project paths to prevent path traversal
+ * attacks and restrict operations to safe directories (within $HOME
+ * or explicitly approved locations).
+ *
+ * @module core/path-validator
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+/**
+ * Blocked directory prefixes that are never valid project paths.
+ * These are system directories that should never be tracked.
+ */
+const BLOCKED_PREFIXES = [
+    '/etc',
+    '/usr',
+    '/bin',
+    '/sbin',
+    '/var',
+    '/sys',
+    '/proc',
+    '/dev',
+    '/boot',
+    '/lib',
+    '/lib64',
+    '/root',
+];
+/**
+ * Canonicalise a path string.
+ *
+ * Resolves `~` to the home directory, normalises `.` and `..` segments,
+ * and returns an absolute path. Does NOT follow symlinks — use
+ * `fs.realpathSync` separately if you need the real path.
+ *
+ * @param p - The path to canonicalise (may contain `~`).
+ * @returns The resolved absolute path.
+ */
+export function canonicalize(p) {
+    if (!p || p.trim().length === 0) {
+        throw new Error('Path cannot be empty.');
+    }
+    let resolved = p.trim();
+    // Resolve ~ to home directory (respects CTX_SYNC_HOME for testing)
+    const homeDir = process.env['CTX_SYNC_HOME'] ?? os.homedir();
+    if (resolved === '~') {
+        resolved = homeDir;
+    }
+    else if (resolved.startsWith('~/')) {
+        resolved = path.join(homeDir, resolved.slice(2));
+    }
+    // Resolve to absolute path (normalises .. and .)
+    resolved = path.resolve(resolved);
+    return resolved;
+}
+/**
+ * Validate that a project path is safe to use.
+ *
+ * A path is valid if ALL of the following are true:
+ * - It is non-empty and resolves to an absolute path.
+ * - After canonicalisation, it is within the user's home directory.
+ * - It does not land inside a blocked system directory.
+ * - If the path exists and is a symlink, the symlink target is also
+ *   within the home directory.
+ *
+ * @param p - The path to validate (may contain `~`).
+ * @returns The canonicalised, validated absolute path.
+ * @throws If the path is outside the home directory, in a blocked
+ *         directory, or a symlink pointing outside the home directory.
+ */
+export function validateProjectPath(p) {
+    const homeDir = process.env['CTX_SYNC_HOME'] ?? os.homedir();
+    const resolved = canonicalize(p);
+    // Must be within home directory (checked first — paths inside the
+    // effective home are allowed even if they happen to sit under a
+    // system prefix, e.g. during tests on macOS where $TMPDIR is /var/…).
+    const isWithinHome = resolved.startsWith(homeDir + '/') || resolved === homeDir;
+    if (!isWithinHome) {
+        // Provide a more specific error for known system directories
+        for (const blocked of BLOCKED_PREFIXES) {
+            if (resolved === blocked || resolved.startsWith(blocked + '/')) {
+                throw new Error(`Path must be within home directory. Blocked path: ${resolved}\n` +
+                    `System directories like ${blocked}/ are not allowed.`);
+            }
+        }
+        throw new Error(`Path must be within home directory.\n` +
+            `  Path: ${resolved}\n` +
+            `  Home: ${homeDir}\n` +
+            `Only paths under your home directory are allowed.`);
+    }
+    // If the path exists, check for symlinks pointing outside home
+    if (fs.existsSync(resolved)) {
+        const stats = fs.lstatSync(resolved);
+        if (stats.isSymbolicLink()) {
+            let realTarget;
+            try {
+                realTarget = fs.realpathSync(resolved);
+            }
+            catch {
+                throw new Error(`Cannot resolve symlink: ${resolved}\n` +
+                    'Symlinks must point to a valid location within the home directory.');
+            }
+            // Compare using the real home path too (on macOS /var → /private/var)
+            let realHome;
+            try {
+                realHome = fs.realpathSync(homeDir);
+            }
+            catch {
+                realHome = homeDir;
+            }
+            const targetInHome = realTarget.startsWith(homeDir + '/') ||
+                realTarget === homeDir ||
+                realTarget.startsWith(realHome + '/') ||
+                realTarget === realHome;
+            if (!targetInHome) {
+                throw new Error(`Symlink target outside allowed directory.\n` +
+                    `  Symlink: ${resolved}\n` +
+                    `  Target: ${realTarget}\n` +
+                    `Symlinks must point to a location within the home directory.`);
+            }
+        }
+    }
+    return resolved;
+}
+//# sourceMappingURL=path-validator.js.map

package/dist/core/path-validator.js.map

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

package/dist/core/recipients.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Recipients store module.
+ *
+ * Manages the list of team members (recipients) who can decrypt
+ * encrypted state files. The recipients configuration is stored
+ * locally in the config directory and is NEVER synced to Git.
+ *
+ * When multiple recipients are configured, all state files are
+ * encrypted for all recipients simultaneously using Age's
+ * multi-recipient support.
+ *
+ * @module core/recipients
+ */
+import type { TeamMember, RecipientsConfig } from '@ctx-sync/shared';
+/** Recipients config file name (stored in config dir, never synced) */
+export declare const RECIPIENTS_FILE = "recipients.json";
+/**
+ * Compute a fingerprint for an Age public key.
+ *
+ * Uses SHA-256 and formats as colon-separated hex pairs (e.g. A3:F2:9C:...).
+ * This is used for out-of-band key verification.
+ *
+ * @param publicKey - An Age public key (age1...).
+ * @returns A colon-separated hex fingerprint string.
+ */
+export declare function computeFingerprint(publicKey: string): string;
+/**
+ * Read the recipients configuration from the config directory.
+ *
+ * @param configDir - The config directory path (e.g. ~/.config/ctx-sync).
+ * @returns The recipients configuration, or `null` if the file does not exist.
+ */
+export declare function getRecipients(configDir: string): RecipientsConfig | null;
+/**
+ * Save the recipients configuration to the config directory.
+ *
+ * @param configDir - The config directory path.
+ * @param config - The recipients configuration to save.
+ */
+export declare function saveRecipients(configDir: string, config: RecipientsConfig): void;
+/**
+ * Initialize the recipients configuration with the owner's public key.
+ *
+ * Creates the recipients file if it does not exist, setting the owner
+ * as the sole recipient.
+ *
+ * @param configDir - The config directory path.
+ * @param ownerPublicKey - The owner's Age public key (age1...).
+ * @returns The initialised recipients configuration.
+ */
+export declare function initRecipients(configDir: string, ownerPublicKey: string): RecipientsConfig;
+/**
+ * Get all public keys that should be used for encryption.
+ *
+ * Returns the owner's key plus all team member keys. If no recipients
+ * config exists, returns only the provided owner key.
+ *
+ * @param configDir - The config directory path.
+ * @param ownerPublicKey - The owner's Age public key (fallback if no config).
+ * @returns Array of all recipient public keys.
+ */
+export declare function getAllRecipientKeys(configDir: string, ownerPublicKey: string): string[];
+/**
+ * Add a team member to the recipients list.
+ *
+ * @param configDir - The config directory path.
+ * @param name - A human-readable name for the team member.
+ * @param publicKey - The member's Age public key (age1...).
+ * @returns The added team member object.
+ * @throws If the public key is already in the recipients list.
+ * @throws If the public key format is invalid.
+ */
+export declare function addRecipient(configDir: string, name: string, publicKey: string): TeamMember;
+/**
+ * Remove a team member by name.
+ *
+ * @param configDir - The config directory path.
+ * @param name - The name of the team member to remove.
+ * @returns The removed team member object.
+ * @throws If no member with the given name exists.
+ */
+export declare function removeRecipientByName(configDir: string, name: string): TeamMember;
+/**
+ * Remove a team member by public key (revoke).
+ *
+ * @param configDir - The config directory path.
+ * @param publicKey - The Age public key of the member to revoke.
+ * @returns The removed team member object.
+ * @throws If no member with the given key exists.
+ */
+export declare function removeRecipientByKey(configDir: string, publicKey: string): TeamMember;
+/**
+ * List all team members.
+ *
+ * @param configDir - The config directory path.
+ * @returns Array of team members (empty if no recipients config or no members).
+ */
+export declare function listRecipients(configDir: string): TeamMember[];
+//# sourceMappingURL=recipients.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"recipients.d.ts","sourceRoot":"","sources":["../../src/core/recipients.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAKH,OAAO,KAAK,EAAE,UAAU,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAErE,uEAAuE;AACvE,eAAO,MAAM,eAAe,oBAAoB,CAAC;AAEjD;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAK5D;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,gBAAgB,GAAG,IAAI,CAcxE;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAC5B,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,gBAAgB,GACvB,IAAI,CAGN;AAED;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAC5B,SAAS,EAAE,MAAM,EACjB,cAAc,EAAE,MAAM,GACrB,gBAAgB,CAalB;AAED;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CACjC,SAAS,EAAE,MAAM,EACjB,cAAc,EAAE,MAAM,GACrB,MAAM,EAAE,CAaV;AAED;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAC1B,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,MAAM,GAChB,UAAU,CAoDZ;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CACnC,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,MAAM,GACX,UAAU,CAqBZ;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAClC,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,GAChB,UAAU,CAmBZ;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,UAAU,EAAE,CAM9D"}

package/dist/core/recipients.js

@@ -0,0 +1,206 @@
+/**
+ * Recipients store module.
+ *
+ * Manages the list of team members (recipients) who can decrypt
+ * encrypted state files. The recipients configuration is stored
+ * locally in the config directory and is NEVER synced to Git.
+ *
+ * When multiple recipients are configured, all state files are
+ * encrypted for all recipients simultaneously using Age's
+ * multi-recipient support.
+ *
+ * @module core/recipients
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as crypto from 'node:crypto';
+/** Recipients config file name (stored in config dir, never synced) */
+export const RECIPIENTS_FILE = 'recipients.json';
+/**
+ * Compute a fingerprint for an Age public key.
+ *
+ * Uses SHA-256 and formats as colon-separated hex pairs (e.g. A3:F2:9C:...).
+ * This is used for out-of-band key verification.
+ *
+ * @param publicKey - An Age public key (age1...).
+ * @returns A colon-separated hex fingerprint string.
+ */
+export function computeFingerprint(publicKey) {
+    const hash = crypto.createHash('sha256').update(publicKey).digest('hex');
+    // Format as colon-separated pairs: A3:F2:9C:...
+    const pairs = hash.substring(0, 32).match(/.{2}/g) ?? [];
+    return pairs.join(':').toUpperCase();
+}
+/**
+ * Read the recipients configuration from the config directory.
+ *
+ * @param configDir - The config directory path (e.g. ~/.config/ctx-sync).
+ * @returns The recipients configuration, or `null` if the file does not exist.
+ */
+export function getRecipients(configDir) {
+    const filePath = path.join(configDir, RECIPIENTS_FILE);
+    if (!fs.existsSync(filePath)) {
+        return null;
+    }
+    const content = fs.readFileSync(filePath, 'utf-8');
+    if (!content.trim()) {
+        return null;
+    }
+    return JSON.parse(content);
+}
+/**
+ * Save the recipients configuration to the config directory.
+ *
+ * @param configDir - The config directory path.
+ * @param config - The recipients configuration to save.
+ */
+export function saveRecipients(configDir, config) {
+    const filePath = path.join(configDir, RECIPIENTS_FILE);
+    fs.writeFileSync(filePath, JSON.stringify(config, null, 2), 'utf-8');
+}
+/**
+ * Initialize the recipients configuration with the owner's public key.
+ *
+ * Creates the recipients file if it does not exist, setting the owner
+ * as the sole recipient.
+ *
+ * @param configDir - The config directory path.
+ * @param ownerPublicKey - The owner's Age public key (age1...).
+ * @returns The initialised recipients configuration.
+ */
+export function initRecipients(configDir, ownerPublicKey) {
+    const existing = getRecipients(configDir);
+    if (existing) {
+        return existing;
+    }
+    const config = {
+        ownerPublicKey,
+        members: [],
+    };
+    saveRecipients(configDir, config);
+    return config;
+}
+/**
+ * Get all public keys that should be used for encryption.
+ *
+ * Returns the owner's key plus all team member keys. If no recipients
+ * config exists, returns only the provided owner key.
+ *
+ * @param configDir - The config directory path.
+ * @param ownerPublicKey - The owner's Age public key (fallback if no config).
+ * @returns Array of all recipient public keys.
+ */
+export function getAllRecipientKeys(configDir, ownerPublicKey) {
+    const config = getRecipients(configDir);
+    if (!config) {
+        return [ownerPublicKey];
+    }
+    const keys = [config.ownerPublicKey];
+    for (const member of config.members) {
+        keys.push(member.publicKey);
+    }
+    return keys;
+}
+/**
+ * Add a team member to the recipients list.
+ *
+ * @param configDir - The config directory path.
+ * @param name - A human-readable name for the team member.
+ * @param publicKey - The member's Age public key (age1...).
+ * @returns The added team member object.
+ * @throws If the public key is already in the recipients list.
+ * @throws If the public key format is invalid.
+ */
+export function addRecipient(configDir, name, publicKey) {
+    // Validate key format
+    if (!publicKey.startsWith('age1')) {
+        throw new Error(`Invalid Age public key format. Expected key starting with "age1", got: ${publicKey.substring(0, 10)}...`);
+    }
+    const config = getRecipients(configDir);
+    if (!config) {
+        throw new Error('Recipients configuration not initialised. Run `ctx-sync init` first.');
+    }
+    // Check for duplicate key
+    if (config.ownerPublicKey === publicKey) {
+        throw new Error('Cannot add your own key as a team member.');
+    }
+    const existingMember = config.members.find((m) => m.publicKey === publicKey);
+    if (existingMember) {
+        throw new Error(`Public key already registered for team member "${existingMember.name}".`);
+    }
+    // Check for duplicate name
+    const existingName = config.members.find((m) => m.name.toLowerCase() === name.toLowerCase());
+    if (existingName) {
+        throw new Error(`Team member with name "${name}" already exists. Use a unique name.`);
+    }
+    const fingerprint = computeFingerprint(publicKey);
+    const member = {
+        name,
+        publicKey,
+        addedAt: new Date().toISOString(),
+        fingerprint,
+    };
+    config.members.push(member);
+    saveRecipients(configDir, config);
+    return member;
+}
+/**
+ * Remove a team member by name.
+ *
+ * @param configDir - The config directory path.
+ * @param name - The name of the team member to remove.
+ * @returns The removed team member object.
+ * @throws If no member with the given name exists.
+ */
+export function removeRecipientByName(configDir, name) {
+    const config = getRecipients(configDir);
+    if (!config) {
+        throw new Error('Recipients configuration not initialised. Run `ctx-sync init` first.');
+    }
+    const index = config.members.findIndex((m) => m.name.toLowerCase() === name.toLowerCase());
+    if (index === -1) {
+        throw new Error(`No team member found with name "${name}".`);
+    }
+    const removed = config.members[index];
+    config.members.splice(index, 1);
+    saveRecipients(configDir, config);
+    // Safe: index was validated above so removed is always defined
+    return removed;
+}
+/**
+ * Remove a team member by public key (revoke).
+ *
+ * @param configDir - The config directory path.
+ * @param publicKey - The Age public key of the member to revoke.
+ * @returns The removed team member object.
+ * @throws If no member with the given key exists.
+ */
+export function removeRecipientByKey(configDir, publicKey) {
+    const config = getRecipients(configDir);
+    if (!config) {
+        throw new Error('Recipients configuration not initialised. Run `ctx-sync init` first.');
+    }
+    const index = config.members.findIndex((m) => m.publicKey === publicKey);
+    if (index === -1) {
+        throw new Error(`No team member found with public key "${publicKey}".`);
+    }
+    const removed = config.members[index];
+    config.members.splice(index, 1);
+    saveRecipients(configDir, config);
+    // Safe: index was validated above so removed is always defined
+    return removed;
+}
+/**
+ * List all team members.
+ *
+ * @param configDir - The config directory path.
+ * @returns Array of team members (empty if no recipients config or no members).
+ */
+export function listRecipients(configDir) {
+    const config = getRecipients(configDir);
+    if (!config) {
+        return [];
+    }
+    return config.members;
+}
+//# sourceMappingURL=recipients.js.map

package/dist/core/recipients.js.map

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

package/dist/core/services-handler.d.ts

@@ -0,0 +1,113 @@
+/**
+ * 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 type { Service, ServiceState } from '@ctx-sync/shared';
+/**
+ * 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 declare function createService(project: string, name: string, port: number, command: string, autoStart?: boolean): Service;
+/**
+ * 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 declare function validateService(service: Service): string[];
+/**
+ * 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 declare function loadServices(syncDir: string, privateKey: string): Promise<ServiceState>;
+/**
+ * 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 declare function loadProjectServices(syncDir: string, privateKey: string, project: string): Promise<Service[]>;
+/**
+ * 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 declare function saveServices(syncDir: string, state: ServiceState, publicKey: string): Promise<void>;
+/**
+ * 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 declare function addService(syncDir: string, service: Service, publicKey: string, privateKey: string): Promise<void>;
+/**
+ * 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 declare function removeService(syncDir: string, project: string, name: string, publicKey: string, privateKey: string): Promise<boolean>;
+/**
+ * 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 declare function removeProjectServices(syncDir: string, project: string, publicKey: string, privateKey: string): Promise<number>;
+/**
+ * List unique project names that have services.
+ *
+ * @param syncDir    - The sync directory.
+ * @param privateKey - Age private key.
+ * @returns Sorted array of project names.
+ */
+export declare function listServiceProjects(syncDir: string, privateKey: string): Promise<string[]>;
+/**
+ * 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 declare function getAutoStartServices(syncDir: string, privateKey: string, project: string): Promise<Service[]>;
+//# sourceMappingURL=services-handler.d.ts.map

package/dist/core/services-handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"services-handler.d.ts","sourceRoot":"","sources":["../../src/core/services-handler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAc9D;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAC3B,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,SAAS,UAAQ,GAChB,OAAO,CAET;AAED;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,EAAE,CAoB1D;AAED;;;;;;;GAOG;AACH,wBAAsB,YAAY,CAChC,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,YAAY,CAAC,CAGvB;AAED;;;;;;;GAOG;AACH,wBAAsB,mBAAmB,CACvC,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,OAAO,EAAE,CAAC,CAGpB;AAED;;;;;;GAMG;AACH,wBAAsB,YAAY,CAChC,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,YAAY,EACnB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,IAAI,CAAC,CAEf;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,UAAU,CAC9B,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,OAAO,EAChB,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,IAAI,CAAC,CAUf;AAED;;;;;;;;;GASG;AACH,wBAAsB,aAAa,CACjC,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,OAAO,CAAC,CAalB;AAED;;;;;;;;GAQG;AACH,wBAAsB,qBAAqB,CACzC,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,MAAM,CAAC,CAWjB;AAED;;;;;;GAMG;AACH,wBAAsB,mBAAmB,CACvC,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,MAAM,EAAE,CAAC,CAInB;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,oBAAoB,CACxC,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,OAAO,EAAE,CAAC,CAGpB"}