archsync 1.0.0

package/src/commands/setup.js

@@ -0,0 +1,233 @@
+import chalk from 'chalk';
+import ora from 'ora';
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+import { createClient } from '@supabase/supabase-js';
+import { readConfig } from '../core/supabaseClient.js';
+
+const ARCHSYNC_DIR = path.join(os.homedir(), '.archsync');
+const GLOBAL_CONFIG_FILE = path.join(ARCHSYNC_DIR, 'config.json');
+
+const REQUIRED_TABLES = ['projects', 'nodes', 'edges', 'schema_commits'];
+
+/**
+ * Lightweight schema migration list for the CLI.
+ * Each entry contains a unique id and SQL to run.
+ */
+const MIGRATIONS = [
+    {
+        id: '001_core_tables',
+        name: 'Core tables (projects, nodes, edges)',
+        sql: [
+            `CREATE TABLE IF NOT EXISTS projects (
+                id         uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+                name       text NOT NULL,
+                owner_id   uuid,
+                org_id     uuid,
+                created_at timestamptz DEFAULT now()
+            )`,
+            `CREATE TABLE IF NOT EXISTS nodes (
+                id          uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+                project_id  uuid REFERENCES projects(id) ON DELETE CASCADE,
+                user_id     uuid,
+                org_id      uuid,
+                entity_type text,
+                system      text,
+                text        text,
+                x           float8 DEFAULT 0,
+                y           float8 DEFAULT 0,
+                w           float8 DEFAULT 160,
+                h           float8 DEFAULT 60,
+                style       jsonb DEFAULT '{}',
+                data        jsonb DEFAULT '{}',
+                metadata    jsonb DEFAULT '{}',
+                is_manual   boolean DEFAULT false,
+                created_at  timestamptz DEFAULT now(),
+                updated_at  timestamptz DEFAULT now()
+            )`,
+            `CREATE TABLE IF NOT EXISTS edges (
+                id         uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+                project_id uuid REFERENCES projects(id) ON DELETE CASCADE,
+                user_id    uuid,
+                org_id     uuid,
+                source     uuid,
+                target     uuid,
+                relation   text,
+                created_at timestamptz DEFAULT now()
+            )`,
+        ],
+    },
+    {
+        id: '002_schema_commits',
+        name: 'Schema commits table',
+        sql: [
+            `CREATE TABLE IF NOT EXISTS schema_commits (
+                id          uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+                project_id  uuid REFERENCES projects(id) ON DELETE CASCADE,
+                branch      text NOT NULL DEFAULT 'main',
+                commit_hash text,
+                schema_json jsonb,
+                environment text DEFAULT 'dev',
+                created_by  uuid,
+                created_at  timestamptz DEFAULT now()
+            )`,
+        ],
+    },
+    {
+        id: '003_migrations_tracking',
+        name: 'Migrations tracking table',
+        sql: [
+            `CREATE TABLE IF NOT EXISTS archsync_migrations (
+                id         text PRIMARY KEY,
+                name       text NOT NULL,
+                applied_at timestamptz DEFAULT now()
+            )`,
+        ],
+    },
+];
+
+function loadGlobalConfig() {
+    if (!fs.existsSync(GLOBAL_CONFIG_FILE)) return null;
+    try {
+        return JSON.parse(fs.readFileSync(GLOBAL_CONFIG_FILE, 'utf-8'));
+    } catch {
+        return null;
+    }
+}
+
+async function getAppliedMigrations(client) {
+    const { data, error } = await client
+        .from('archsync_migrations')
+        .select('id');
+    if (error) return new Set();
+    return new Set((data || []).map(r => r.id));
+}
+
+async function markApplied(client, id, name) {
+    await client.from('archsync_migrations').upsert({ id, name }, { onConflict: 'id' });
+}
+
+async function checkTablesExist(client) {
+    const results = {};
+    for (const table of REQUIRED_TABLES) {
+        const { error } = await client.from(table).select('id').limit(0);
+        results[table] = !error || (error.code !== '42P01' && error.code !== 'PGRST200');
+    }
+    return results;
+}
+
+export async function setupCommand(options) {
+    console.log(chalk.blue.bold('\n🗄  ArchSync CLI — Database Setup (archsync db:setup)\n'));
+
+    // Resolve credentials: CLI flags > global config > local .archsync.json
+    let supabaseUrl = options.url;
+    let supabaseKey = options.key;
+
+    if (!supabaseUrl || !supabaseKey) {
+        const globalCfg = loadGlobalConfig();
+        if (globalCfg) {
+            supabaseUrl = supabaseUrl || globalCfg.supabaseUrl;
+            supabaseKey = supabaseKey || globalCfg.supabaseKey;
+        }
+    }
+
+    if (!supabaseUrl || !supabaseKey) {
+        const localCfg = readConfig(options.dir);
+        if (localCfg?.supabase) {
+            supabaseUrl = supabaseUrl || localCfg.supabase.url;
+            supabaseKey = supabaseKey || localCfg.supabase.anonKey;
+        }
+    }
+
+    if (!supabaseUrl || !supabaseKey) {
+        console.log(chalk.red('❌ No Supabase credentials found.'));
+        console.log(chalk.yellow('   Run `archsync connect` first, or provide --url and --key flags.'));
+        process.exit(1);
+    }
+
+    const spinner = ora('Connecting to database…').start();
+
+    let client;
+    try {
+        client = createClient(supabaseUrl.trim().replace(/\/$/, ''), supabaseKey.trim());
+        // Sanity-check connection
+        const { error } = await client.from('projects').select('id').limit(0);
+        if (error && error.code !== '42P01' && error.code !== 'PGRST200') {
+            // 42P01 = table doesn't exist yet, that's fine
+            throw new Error(error.message);
+        }
+        spinner.succeed('Connected to database');
+    } catch (err) {
+        spinner.fail('Failed to connect');
+        console.log(chalk.red(`\n  Error: ${err.message}`));
+        process.exit(1);
+    }
+
+    // ─── Schema check ──────────────────────────────────────────────────────
+    const spinner2 = ora('Checking schema…').start();
+    const tableStatus = await checkTablesExist(client);
+    const missing = REQUIRED_TABLES.filter(t => !tableStatus[t]);
+    if (missing.length === 0) {
+        spinner2.succeed('Schema looks good — all required tables exist');
+    } else {
+        spinner2.warn(`Missing tables: ${missing.join(', ')}`);
+    }
+
+    // ─── Run migrations ────────────────────────────────────────────────────
+    const spinner3 = ora('Running pending migrations…').start();
+
+    let appliedIds;
+    try {
+        appliedIds = await getAppliedMigrations(client);
+    } catch {
+        appliedIds = new Set();
+    }
+
+    let appliedCount = 0;
+    let skippedCount = 0;
+    const errors = [];
+
+    for (const migration of MIGRATIONS) {
+        if (appliedIds.has(migration.id)) {
+            skippedCount++;
+            continue;
+        }
+
+        try {
+            // Execute each SQL statement
+            for (const sql of migration.sql) {
+                const { error } = await client.rpc('exec_sql', { sql }).catch(() => ({ error: null }));
+                if (error) {
+                    console.warn(chalk.yellow(`\n  Warning: rpc exec_sql failed for ${migration.id}: ${error.message}`));
+                }
+            }
+            await markApplied(client, migration.id, migration.name).catch(() => {});
+            appliedCount++;
+        } catch (err) {
+            errors.push({ id: migration.id, error: err.message });
+        }
+    }
+
+    if (errors.length > 0) {
+        spinner3.warn(`Migrations completed with ${errors.length} error(s)`);
+        for (const { id, error } of errors) {
+            console.log(chalk.red(`  ✗ ${id}: ${error}`));
+        }
+    } else {
+        spinner3.succeed(`Migrations complete — ${appliedCount} applied, ${skippedCount} skipped`);
+    }
+
+    // ─── Summary ───────────────────────────────────────────────────────────
+    console.log(chalk.gray('\n╔══════════════════════════════════════╗'));
+    console.log(chalk.gray('║') + chalk.white.bold('      Database Setup Summary          ') + chalk.gray('║'));
+    console.log(chalk.gray('╠══════════════════════════════════════╣'));
+    for (const table of REQUIRED_TABLES) {
+        const status = tableStatus[table] ? chalk.green('✓') : chalk.yellow('?');
+        console.log(chalk.gray('║') + `  ${status} ${table.padEnd(30)}  ` + chalk.gray('║'));
+    }
+    console.log(chalk.gray('║') + chalk.green(`  Migrations applied: ${String(appliedCount).padStart(3)}            `) + chalk.gray('║'));
+    console.log(chalk.gray('╚══════════════════════════════════════╝'));
+
+    console.log(chalk.blue('\nNext: ') + chalk.gray('archsync scan && archsync push'));
+}

package/src/commands/status.js

@@ -0,0 +1,56 @@
+import chalk from 'chalk';
+import fs from 'fs';
+import path from 'path';
+import { readConfig, getSupabaseClient, fetchLatestSchema } from '../core/supabaseClient.js';
+import { hashSchema, schemasEqual } from '../core/hashEngine.js';
+
+const LOCAL_SCHEMA_FILE = '.archsync-schema.json';
+
+export async function statusCommand() {
+    console.log(chalk.blue.bold('\n📊 ArchSync CLI — Status\n'));
+
+    const config = readConfig();
+    if (!config) {
+        console.log(chalk.red('❌ No .archsync.json found. Run `archsync init` first.'));
+        process.exit(1);
+    }
+
+    console.log(chalk.gray('─── Configuration ──────────────────'));
+    console.log(chalk.white(`  Framework:  ${chalk.bold(config.framework)}`));
+    console.log(chalk.white(`  Project ID: ${chalk.bold(config.projectId || 'Not linked')}`));
+    console.log(chalk.white(`  Supabase:   ${config.supabase?.url ? chalk.green('Configured') : chalk.yellow('Not configured')}`));
+    console.log(chalk.white(`  AST Mode:   ${config.scan?.ast ? chalk.green('Enabled') : chalk.gray('Disabled')}`));
+
+    const schemaPath = path.resolve(LOCAL_SCHEMA_FILE);
+    if (fs.existsSync(schemaPath)) {
+        const schema = JSON.parse(fs.readFileSync(schemaPath, 'utf-8'));
+        console.log(chalk.gray('\n─── Local Schema ───────────────────'));
+        console.log(chalk.white(`  Nodes:      ${chalk.bold(schema.nodes?.length || 0)}`));
+        console.log(chalk.white(`  Edges:      ${chalk.bold(schema.edges?.length || 0)}`));
+        console.log(chalk.white(`  Hash:       ${chalk.gray(schema.hash || 'N/A')}`));
+        console.log(chalk.white(`  Generated:  ${chalk.gray(schema.meta?.generatedAt || 'Unknown')}`));
+
+        // Check sync status
+        if (config.projectId && config.supabase?.url) {
+            try {
+                const client = getSupabaseClient(config);
+                const remote = await fetchLatestSchema(client, config.projectId);
+                if (remote) {
+                    const inSync = schemasEqual(schema, remote);
+                    console.log(chalk.gray('\n─── Sync Status ────────────────────'));
+                    console.log(chalk.white(`  Status:     ${inSync ? chalk.green.bold('✅ In Sync') : chalk.yellow.bold('⚠ Out of Sync')}`));
+                } else {
+                    console.log(chalk.gray('\n─── Sync Status ────────────────────'));
+                    console.log(chalk.yellow(`  Status:     No remote schema (run archsync push)`));
+                }
+            } catch (err) {
+                console.log(chalk.gray('\n─── Sync Status ────────────────────'));
+                console.log(chalk.red(`  Status:     Error: ${err.message}`));
+            }
+        }
+    } else {
+        console.log(chalk.gray('\n  No local schema. Run `archsync scan` first.'));
+    }
+
+    console.log('');
+}

package/src/commands/validate.js

@@ -0,0 +1,245 @@
+import chalk from 'chalk';
+import fs from 'fs';
+import path from 'path';
+
+const LOCAL_SCHEMA_FILE = '.archsync-schema.json';
+
+// ─── Validation rules ─────────────────────────────────────────
+
+function findOrphanNodes(nodes, edges) {
+    const connected = new Set();
+    for (const edge of edges) {
+        connected.add(edge.source);
+        connected.add(edge.target);
+    }
+    return nodes.filter(n => !connected.has(n.id));
+}
+
+function findDuplicateEntities(nodes) {
+    const seen = new Map(); // name+type → first node
+    const duplicates = [];
+    for (const node of nodes) {
+        const key = `${node.entityType}::${node.text || node.name || node.id}`;
+        if (seen.has(key)) {
+            duplicates.push({ original: seen.get(key), duplicate: node });
+        } else {
+            seen.set(key, node);
+        }
+    }
+    return duplicates;
+}
+
+function findCircularDependencies(nodes, edges) {
+    // Build adjacency list
+    const adj = new Map();
+    for (const node of nodes) adj.set(node.id, []);
+    for (const edge of edges) {
+        if (adj.has(edge.source)) {
+            adj.get(edge.source).push(edge.target);
+        }
+    }
+
+    const visited = new Set();
+    const inStack = new Set();
+    const cycles = [];
+
+    function dfs(id, stack) {
+        if (inStack.has(id)) {
+            // Found a cycle — record the cycle path
+            const cycleStart = stack.indexOf(id);
+            cycles.push(stack.slice(cycleStart));
+            return;
+        }
+        if (visited.has(id)) return;
+        visited.add(id);
+        inStack.add(id);
+        stack.push(id);
+        for (const neighbour of (adj.get(id) || [])) {
+            dfs(neighbour, stack);
+        }
+        stack.pop();
+        inStack.delete(id);
+    }
+
+    for (const node of nodes) {
+        if (!visited.has(node.id)) {
+            dfs(node.id, []);
+        }
+    }
+
+    // Deduplicate cycles by sorted key
+    const seen = new Set();
+    return cycles.filter(cycle => {
+        const key = [...cycle].sort().join(',');
+        if (seen.has(key)) return false;
+        seen.add(key);
+        return true;
+    });
+}
+
+function findMissingRequiredFields(nodes) {
+    const missing = [];
+    for (const node of nodes) {
+        const problems = [];
+        if (!node.id) problems.push('id');
+        if (!node.entityType) problems.push('entityType');
+        if (!node.system) problems.push('system');
+        if (!node.text && !node.name) problems.push('text/name');
+        if (problems.length > 0) {
+            missing.push({ node, missingFields: problems });
+        }
+    }
+    return missing;
+}
+
+function findDanglingEdges(nodes, edges) {
+    const nodeIds = new Set(nodes.map(n => n.id));
+    return edges.filter(e => !nodeIds.has(e.source) || !nodeIds.has(e.target));
+}
+
+// ─── Reporting helpers ────────────────────────────────────────
+
+function nodeLabel(node) {
+    const name = node.text || node.name || node.id || '?';
+    const type = node.entityType || 'unknown';
+    return `[${type}] ${name}`;
+}
+
+// ─── Command ──────────────────────────────────────────────────
+
+export async function validateCommand(options) {
+    console.log(chalk.blue.bold('\n✅ ArchSync CLI — Schema Validation\n'));
+
+    const schemaPath = path.resolve(LOCAL_SCHEMA_FILE);
+    if (!fs.existsSync(schemaPath)) {
+        console.log(chalk.red('❌ No local schema found. Run `archsync scan` first.'));
+        process.exit(1);
+    }
+
+    let schema;
+    try {
+        schema = JSON.parse(fs.readFileSync(schemaPath, 'utf-8'));
+    } catch (err) {
+        console.log(chalk.red(`❌ Failed to parse schema file: ${err.message}`));
+        process.exit(1);
+    }
+
+    const nodes = schema.nodes || [];
+    const edges = schema.edges || [];
+
+    const warnings = [];
+    const errors = [];
+
+    // ── Rule 1: Missing required fields ──────────────────────
+    const missingFields = findMissingRequiredFields(nodes);
+    for (const { node, missingFields: fields } of missingFields) {
+        errors.push({
+            rule: 'missing-required-fields',
+            message: `Node is missing required field(s): ${fields.join(', ')}`,
+            node,
+        });
+    }
+
+    // ── Rule 2: Duplicate entities ────────────────────────────
+    const duplicates = findDuplicateEntities(nodes);
+    for (const { original, duplicate } of duplicates) {
+        warnings.push({
+            rule: 'duplicate-entity',
+            message: `Duplicate entity: ${nodeLabel(duplicate)} (also at ${original.metadata?.sourceFile || '?'})`,
+            node: duplicate,
+        });
+    }
+
+    // ── Rule 3: Orphan nodes ──────────────────────────────────
+    if (nodes.length > 1) {
+        const orphans = findOrphanNodes(nodes, edges);
+        for (const node of orphans) {
+            warnings.push({
+                rule: 'orphan-node',
+                message: `Orphan node with no edges: ${nodeLabel(node)}`,
+                node,
+            });
+        }
+    }
+
+    // ── Rule 4: Circular dependencies ─────────────────────────
+    const cycles = findCircularDependencies(nodes, edges);
+    for (const cycle of cycles) {
+        const names = cycle.map(id => {
+            const n = nodes.find(n => n.id === id);
+            return n ? (n.text || n.name || id) : id;
+        });
+        warnings.push({
+            rule: 'circular-dependency',
+            message: `Circular dependency detected: ${names.join(' → ')} → ${names[0]}`,
+            cycle,
+        });
+    }
+
+    // ── Rule 5: Dangling edges (edges pointing to missing nodes)
+    const dangling = findDanglingEdges(nodes, edges);
+    for (const edge of dangling) {
+        errors.push({
+            rule: 'dangling-edge',
+            message: `Edge references missing node(s): ${edge.source} → ${edge.target} [${edge.relation}]`,
+            edge,
+        });
+    }
+
+    // ── Rule 6: Empty schema ───────────────────────────────────
+    if (nodes.length === 0) {
+        warnings.push({
+            rule: 'empty-schema',
+            message: 'Schema has no nodes. Run `archsync scan` to populate it.',
+        });
+    }
+
+    // ─── Report ───────────────────────────────────────────────
+    console.log(chalk.gray('─── Validation Report ─────────────────────────────'));
+    console.log(chalk.gray(`  Nodes checked:  ${nodes.length}`));
+    console.log(chalk.gray(`  Edges checked:  ${edges.length}`));
+    console.log('');
+
+    if (errors.length === 0 && warnings.length === 0) {
+        console.log(chalk.green('  Schema is valid. No issues found.'));
+    }
+
+    if (warnings.length > 0) {
+        console.log(chalk.yellow(`  WARNINGS (${warnings.length})`));
+        console.log(chalk.yellow('  ' + '─'.repeat(46)));
+        for (const w of warnings) {
+            console.log(chalk.yellow(`  ⚠  [${w.rule}] ${w.message}`));
+            if (w.node?.metadata?.sourceFile) {
+                console.log(chalk.gray(`       at: ${w.node.metadata.sourceFile}`));
+            }
+        }
+        console.log('');
+    }
+
+    if (errors.length > 0) {
+        console.log(chalk.red(`  ERRORS (${errors.length})`));
+        console.log(chalk.red('  ' + '─'.repeat(46)));
+        for (const e of errors) {
+            console.log(chalk.red(`  ✖  [${e.rule}] ${e.message}`));
+            if (e.node?.metadata?.sourceFile) {
+                console.log(chalk.gray(`       at: ${e.node.metadata.sourceFile}`));
+            }
+        }
+        console.log('');
+    }
+
+    // ─── Summary ──────────────────────────────────────────────
+    console.log(chalk.gray('─── Summary ───────────────────────────────────────'));
+    console.log(chalk.yellow(`  Warnings: ${warnings.length}`));
+    console.log(errors.length > 0
+        ? chalk.red(`  Errors:   ${errors.length}`)
+        : chalk.green(`  Errors:   ${errors.length}`)
+    );
+
+    if (errors.length > 0) {
+        console.log(chalk.red('\n  Validation failed. Fix errors before pushing.\n'));
+        process.exit(1);
+    } else {
+        console.log(chalk.green('\n  Validation passed.\n'));
+    }
+}

package/src/commands/watch.js

@@ -0,0 +1,70 @@
+import chalk from 'chalk';
+import ora from 'ora';
+import path from 'path';
+import { watch } from 'chokidar';
+import { readConfig } from '../core/supabaseClient.js';
+import { scanCommand } from './scan.js';
+
+export async function watchCommand(options) {
+    console.log(chalk.blue.bold('\n👁️  ArchSync CLI — Watch Mode\n'));
+
+    const config = readConfig(options.dir);
+    if (!config) {
+        console.log(chalk.red('❌ No .archsync.json found. Run `archsync init` first.'));
+        process.exit(1);
+    }
+
+    const debounce = parseInt(options.debounce || '2000', 10);
+    const watchDir = path.resolve(options.dir || '.');
+    const includePatterns = config.scan?.include || ['**/*.{js,ts,jsx,tsx,dart}'];
+    const excludePatterns = config.scan?.exclude || ['**/node_modules/**'];
+
+    console.log(chalk.gray(`  Watching: ${watchDir}`));
+    console.log(chalk.gray(`  Debounce: ${debounce}ms`));
+    console.log(chalk.gray(`  Press Ctrl+C to stop\n`));
+
+    let timer = null;
+    let scanning = false;
+
+    const triggerScan = () => {
+        if (scanning) return;
+        if (timer) clearTimeout(timer);
+
+        timer = setTimeout(async () => {
+            scanning = true;
+            console.log(chalk.gray(`\n[${new Date().toLocaleTimeString()}] Change detected, rescanning...`));
+            try {
+                await scanCommand({ dir: options.dir || '.', ast: config.scan?.ast });
+            } catch (err) {
+                console.log(chalk.red(`  Scan error: ${err.message}`));
+            }
+            scanning = false;
+        }, debounce);
+    };
+
+    const watcher = watch(includePatterns, {
+        cwd: watchDir,
+        ignored: excludePatterns,
+        ignoreInitial: true,
+        persistent: true,
+    });
+
+    watcher
+        .on('add', (filePath) => {
+            console.log(chalk.green(`  + ${filePath}`));
+            triggerScan();
+        })
+        .on('change', (filePath) => {
+            console.log(chalk.yellow(`  ~ ${filePath}`));
+            triggerScan();
+        })
+        .on('unlink', (filePath) => {
+            console.log(chalk.red(`  - ${filePath}`));
+            triggerScan();
+        });
+
+    // Initial scan
+    console.log(chalk.gray('Running initial scan...'));
+    await scanCommand({ dir: options.dir || '.', ast: config.scan?.ast });
+    console.log(chalk.green('\n✅ Watching for changes...'));
+}

package/src/core/credentialStore.js

@@ -0,0 +1,76 @@
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+
+const ARCHSYNC_DIR = path.join(os.homedir(), '.archsync');
+const CREDENTIALS_FILE = path.join(ARCHSYNC_DIR, 'credentials.json');
+
+/**
+ * Ensures ~/.archsync/ directory exists.
+ */
+function ensureDir() {
+    if (!fs.existsSync(ARCHSYNC_DIR)) {
+        fs.mkdirSync(ARCHSYNC_DIR, { recursive: true, mode: 0o700 });
+    }
+}
+
+/**
+ * Save credentials to ~/.archsync/credentials.json.
+ * @param {string} apiKey  - Supabase access token or API key
+ * @param {string} userId  - User UUID
+ * @param {string} email   - User email (optional, for display)
+ */
+export function saveCredentials(apiKey, userId, email = '') {
+    ensureDir();
+    const credentials = {
+        apiKey,
+        userId,
+        email,
+        savedAt: new Date().toISOString(),
+    };
+    fs.writeFileSync(CREDENTIALS_FILE, JSON.stringify(credentials, null, 2), { mode: 0o600 });
+}
+
+/**
+ * Load credentials from ~/.archsync/credentials.json.
+ * Returns null if file doesn't exist or is malformed.
+ * @returns {{ apiKey: string, userId: string, email: string, savedAt: string } | null}
+ */
+export function loadCredentials() {
+    if (!fs.existsSync(CREDENTIALS_FILE)) return null;
+    try {
+        return JSON.parse(fs.readFileSync(CREDENTIALS_FILE, 'utf-8'));
+    } catch {
+        return null;
+    }
+}
+
+/**
+ * Remove ~/.archsync/credentials.json (logout).
+ */
+export function clearCredentials() {
+    if (fs.existsSync(CREDENTIALS_FILE)) {
+        fs.unlinkSync(CREDENTIALS_FILE);
+    }
+}
+
+/**
+ * Check if a valid credential exists (either stored file or env var).
+ * @returns {boolean}
+ */
+export function isAuthenticated() {
+    if (process.env.ARCHSYNC_API_KEY) return true;
+    const creds = loadCredentials();
+    return !!(creds && creds.apiKey);
+}
+
+/**
+ * Resolve the API key from env or stored credentials.
+ * Env var ARCHSYNC_API_KEY takes precedence (for CI).
+ * @returns {string | null}
+ */
+export function getApiKey() {
+    if (process.env.ARCHSYNC_API_KEY) return process.env.ARCHSYNC_API_KEY;
+    const creds = loadCredentials();
+    return creds?.apiKey || null;
+}