studiograph 1.3.48-next.13 → 1.3.48-next.130

package/dist/cli/commands/sync.js

@@ -3,18 +3,147 @@
  *
  * Pull and push changes across the workspace:
  *   - the .studiograph config repo (if it has a git remote)
- *   - each entity collection that is a git repo with a remote
+ *   - each entity folder that is a git repo with a remote
  *
  * Works with both GitHub remotes and the embedded git server.
  */
 import { Command } from 'commander';
 import { log, outro, text, password as passwordPrompt } from '@clack/prompts';
-import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'fs';
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'fs';
 import { join } from 'path';
 import { Workspace } from '../../core/workspace.js';
 import { AuthService } from '../../services/auth-service.js';
 import { ConnectorManager } from '../../mcp/connector-manager.js';
-import { gitPull, gitPush, gitPushWithCredentials, gitSetRemote, gitHasRemote } from '../../utils/git.js';
+import { buildConfigBundle } from '../../core/secrets/bundle.js';
+import { gitClone, gitPull, gitPush, gitPushWithCredentials, gitSetRemote, gitHasRemote } from '../../utils/git.js';
+import { getStudiographToken, setStudiographToken, clearStudiographToken } from '../../core/user-config.js';
+async function resolveRemoteAuth(base, _workspaceRoot, opts) {
+    // 1-2. Explicit token or env var
+    const explicitToken = opts.token || process.env.STUDIOGRAPH_TOKEN;
+    if (explicitToken) {
+        const token = explicitToken.trim();
+        return {
+            httpHeader: { 'Authorization': `Bearer ${token}` },
+            gitCredentials: { username: '_token_', password: token },
+        };
+    }
+    // 3. Explicit email/password or env vars
+    const email = opts.email || process.env.STUDIOGRAPH_EMAIL;
+    const password = opts.password || process.env.STUDIOGRAPH_PASSWORD;
+    if (email && password) {
+        const httpHeader = await loginForCookie(base, email, password);
+        return { httpHeader, gitCredentials: { username: email, password } };
+    }
+    // 4. Stored per-user token from ~/.studiograph/user.json
+    const storedToken = getStudiographToken(base);
+    if (storedToken) {
+        const httpHeader = { 'Authorization': `Bearer ${storedToken}` };
+        // Probe a cheap authenticated endpoint so a revoked / expired / rebuilt-DB
+        // token doesn't wedge push/pull. On 401, clear it and fall through to the
+        // interactive mint so users can recover without hand-editing user.json.
+        const probe = await fetch(`${base}/api/auth/tokens`, { headers: httpHeader }).catch(() => null);
+        if (probe?.ok) {
+            return { httpHeader, gitCredentials: { username: '_token_', password: storedToken } };
+        }
+        if (probe?.status === 401) {
+            clearStudiographToken(base);
+            log.info('Stored CLI token is no longer valid — signing in again.');
+        }
+        else if (probe) {
+            // Non-401 response (5xx, unreachable, etc.) → keep the token, use it;
+            // the real request will surface the underlying error.
+            return { httpHeader, gitCredentials: { username: '_token_', password: storedToken } };
+        }
+    }
+    // 5. Interactive prompts — then mint a token for future runs.
+    if (!process.stdin.isTTY) {
+        throw new Error('No credentials provided and stdin is not a TTY. Use --token, --email + --password, or set STUDIOGRAPH_TOKEN.');
+    }
+    const emailPrompt = await text({ message: 'Email:', validate: (v) => v.includes('@') ? undefined : 'Enter a valid email' });
+    if (typeof emailPrompt === 'symbol') {
+        outro('Cancelled');
+        process.exit(0);
+    }
+    const passPrompt = await passwordPrompt({ message: 'Password:' });
+    if (typeof passPrompt === 'symbol') {
+        outro('Cancelled');
+        process.exit(0);
+    }
+    const emailStr = String(emailPrompt);
+    const passStr = String(passPrompt);
+    const httpHeader = await loginForCookie(base, emailStr, passStr);
+    // Mint a CLI token and save it, so subsequent push/pull runs skip the prompt.
+    try {
+        const mintRes = await fetch(`${base}/api/auth/tokens`, {
+            method: 'POST',
+            headers: { ...httpHeader, 'Content-Type': 'application/json' },
+            body: JSON.stringify({ name: `cli-${process.platform}-${Date.now()}` }),
+        });
+        if (mintRes.ok) {
+            const body = await mintRes.json();
+            if (body.token) {
+                setStudiographToken(base, body.token);
+                log.info('Saved personal API token to ~/.studiograph/user.json for future runs');
+            }
+        }
+    }
+    catch { /* non-fatal — just means next run prompts again */ }
+    return { httpHeader, gitCredentials: { username: emailStr, password: passStr } };
+}
+async function loginForCookie(base, email, password) {
+    const loginRes = await fetch(`${base}/api/auth/login`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ email, password }),
+    });
+    if (!loginRes.ok) {
+        const body = await loginRes.json().catch(() => ({}));
+        throw new Error(`Login failed: ${body.error || loginRes.statusText}`);
+    }
+    const cookies = loginRes.headers.getSetCookie?.() ?? [];
+    const tokenCookie = cookies.find(c => c.startsWith('__sg_token='));
+    if (!tokenCookie) {
+        throw new Error('Login succeeded but no session cookie was returned');
+    }
+    return { 'Cookie': tokenCookie.split(';')[0] };
+}
+/**
+ * Login with email + password and return the raw JWT (extracted from the
+ * `__sg_token` cookie). Same endpoint as {@link loginForCookie} but pulls
+ * the bare token instead of a Cookie header — needed when callers want to
+ * persist the token for reuse (server-auth.json) or pass it as the
+ * password in HTTP Basic auth (git-http expects basic-auth, not cookies).
+ */
+async function loginForJwt(base, email, password) {
+    const loginRes = await fetch(`${base}/api/auth/login`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ email, password }),
+    });
+    if (!loginRes.ok) {
+        const body = await loginRes.json().catch(() => ({}));
+        throw new Error(`Login failed: ${body.error || loginRes.statusText}`);
+    }
+    const cookies = loginRes.headers.getSetCookie?.() ?? [];
+    const tokenCookie = cookies.find(c => c.startsWith('__sg_token='));
+    if (!tokenCookie) {
+        throw new Error('Login succeeded but no session cookie was returned');
+    }
+    return tokenCookie.split(';')[0].replace('__sg_token=', '');
+}
+/**
+ * Persist a successful login to `<workspace>/.studiograph/server-auth.json`
+ * so future runs of the same command don't re-prompt for credentials. Mode
+ * 0600 — the JWT is bearer-equivalent. Mirrors the file format `studiograph
+ * join` and `studiograph clone` write so any tool that reads
+ * server-auth.json sees a consistent shape.
+ */
+function persistServerAuth(workspaceRoot, serverUrl, email, jwtToken) {
+    const studiographDir = join(workspaceRoot, '.studiograph');
+    if (!existsSync(studiographDir))
+        mkdirSync(studiographDir, { recursive: true });
+    writeFileSync(join(studiographDir, 'server-auth.json'), JSON.stringify({ serverUrl, email, jwtToken }, null, 2), { encoding: 'utf-8', mode: 0o600 });
+}
 async function getRepoEntries(workspace, workspaceRoot) {
     const entries = [];
     // The .studiograph config directory is itself a git repo (when GitHub-provisioned)
@@ -24,8 +153,8 @@ async function getRepoEntries(workspace, workspaceRoot) {
     }
     const config = await workspace.loadConfig();
     for (const repo of config.repos) {
-        if (repo.private)
-            continue; // private repos are local-only
+        if (repo.personal)
+            continue; // personal repos are local-only
         const repoPath = join(workspaceRoot, repo.path);
         if (!isGitRepo(repoPath) || !gitHasRemote(repoPath))
             continue;
@@ -42,7 +171,7 @@ function isGitRepo(path) {
 function logManualGuidance(entryPath) {
     log.info(`     cd ${entryPath} && git pull --rebase`);
 }
-async function pullRemoteConfig(remoteUrl) {
+async function pullRemoteConfig(remoteUrl, includeData = false, authOpts = {}) {
     const workspace = new Workspace();
     if (!workspace.isWorkspace()) {
         console.error('❌ Not a Studiograph workspace. Run `studiograph init` first.');
@@ -50,72 +179,50 @@ async function pullRemoteConfig(remoteUrl) {
         return;
     }
     const base = remoteUrl.replace(/\/+$/, '');
-    // Prompt for admin credentials
-    const email = await text({ message: 'Admin email:', validate: (v) => v.includes('@') ? undefined : 'Enter a valid email' });
-    if (typeof email === 'symbol') {
-        outro('Cancelled');
-        process.exit(0);
-        return;
-    }
-    const password = await passwordPrompt({ message: 'Password:' });
-    if (typeof password === 'symbol') {
-        outro('Cancelled');
-        process.exit(0);
-        return;
-    }
-    // Login to get session token
-    log.info('Authenticating...');
-    let token;
+    const workspaceRoot = workspace.getWorkspacePath();
+    const sgDir = join(workspaceRoot, '.studiograph');
+    // Resolve authentication (API key, email+password, env vars, or interactive prompts)
+    let auth;
     try {
-        const loginRes = await fetch(`${base}/api/auth/login`, {
-            method: 'POST',
-            headers: { 'Content-Type': 'application/json' },
-            body: JSON.stringify({ email, password }),
-        });
-        if (!loginRes.ok) {
-            const body = await loginRes.json().catch(() => ({}));
-            outro(`Login failed: ${body.error || loginRes.statusText}`);
-            process.exit(1);
-            return;
-        }
-        const cookies = loginRes.headers.getSetCookie?.() ?? [];
-        const tokenCookie = cookies.find(c => c.startsWith('__sg_token='));
-        if (!tokenCookie) {
-            outro('Login succeeded but no session cookie was returned');
-            process.exit(1);
-            return;
-        }
-        token = tokenCookie.split(';')[0];
+        log.info('Authenticating...');
+        auth = await resolveRemoteAuth(base, workspaceRoot, authOpts);
     }
     catch (err) {
-        outro(`Could not connect to ${base}: ${err.message}`);
+        outro(err.message);
         process.exit(1);
         return;
     }
     // Fetch config bundle (fall back to auth seed for older servers)
     log.info('Fetching workspace config...');
-    const workspaceRoot = workspace.getWorkspacePath();
-    const sgDir = join(workspaceRoot, '.studiograph');
     try {
         const bundleRes = await fetch(`${base}/api/config/bundle`, {
-            headers: { 'Cookie': token },
+            headers: auth.httpHeader,
         });
         if (bundleRes.ok) {
             const bundle = await bundleRes.json();
-            // 1. Auth seed
+            // 1. Auth seed — remote is authoritative for pull, so overwrite any
+            // local-shadow rows (e.g. post-clone setup-wizard credentials that
+            // would otherwise shadow the real production password_hash).
             writeFileSync(join(sgDir, 'auth-seed.json'), JSON.stringify(bundle.authSeed, null, 2), 'utf-8');
-            const authService = new AuthService(sgDir);
-            authService.applySeed();
+            // AuthService appends `.studiograph` to the path it's given —
+            // pass workspace root, not `sgDir`, or we end up with
+            // `.studiograph/.studiograph/auth.db` (disjoint from the running server).
+            const authService = new AuthService(workspaceRoot);
+            authService.applySeed({ mode: 'overwrite' });
             authService.close();
             log.success(`Team: ${bundle.authSeed.users.length} user${bundle.authSeed.users.length === 1 ? '' : 's'}`);
-            // 2. Workspace config — merge: keep local-only fields (server_url), update shared fields
+            // 2. Workspace config — merge: keep local-only fields (server_url), update shared fields.
+            //
+            // Phase 9b: route through `workspace.writeConfig()` so this CLI
+            // pull path shares the same schema validator + dual-write seam as
+            // every other writer.
             if (bundle.workspace) {
                 const local = await workspace.loadConfig().catch(() => ({}));
                 const merged = { ...local, ...bundle.workspace };
                 if (local.server_url)
                     merged.server_url = local.server_url;
-                writeFileSync(join(sgDir, 'workspace.json'), JSON.stringify(merged, null, 2), 'utf-8');
-                log.success(`Workspace config: ${bundle.workspace.repos?.length ?? 0} collection${(bundle.workspace.repos?.length ?? 0) === 1 ? '' : 's'}`);
+                workspace.writeConfig(merged);
+                log.success(`Workspace config: ${bundle.workspace.repos?.length ?? 0} folder${(bundle.workspace.repos?.length ?? 0) === 1 ? '' : 's'}`);
             }
             // 3. ABOUT.md
             if (bundle.about !== null && bundle.about !== undefined) {
@@ -132,21 +239,33 @@ async function pullRemoteConfig(remoteUrl) {
                 }
                 log.success(`Sources: ${sourceNames.join(', ')}`);
             }
-            // 5. Connectors (sanitized — no secrets)
+            // 5. Connectors (sanitized — no secrets).
+            //
+            // Phase 9b: route through `ConnectorManager.saveWorkspaceConfig` so
+            // every connector save runs the same schema validator + stripSecrets
+            // pass. The bundle is already sanitized server-side; the re-strip
+            // is idempotent and preserves the single-seam invariant.
             if (bundle.connectors && bundle.connectors.length > 0) {
-                const connectorsDir = join(sgDir, 'connectors');
-                mkdirSync(connectorsDir, { recursive: true });
                 for (const conn of bundle.connectors) {
-                    writeFileSync(join(connectorsDir, `${conn.name}.json`), JSON.stringify(conn, null, 2), 'utf-8');
+                    ConnectorManager.saveWorkspaceConfig(conn, workspaceRoot);
                 }
                 log.success(`Connectors: ${bundle.connectors.map(c => c.name).join(', ')}`);
             }
-            outro(`Pulled config from ${base}`);
+            // Pull workspace data (markdown files) if requested
+            if (includeData) {
+                try {
+                    await pullRemoteData(base, auth, workspaceRoot);
+                }
+                catch (err) {
+                    log.error(`Data pull failed: ${err.message}`);
+                }
+            }
+            outro(`Pulled from ${base}${includeData ? ' (config + data)' : ' (config)'}`);
         }
         else if (bundleRes.status === 404) {
             // Older server — fall back to auth seed only
             log.info('Server does not support config bundle, falling back to auth seed...');
-            const seedRes = await fetch(`${base}/api/auth/seed`, { headers: { 'Cookie': token } });
+            const seedRes = await fetch(`${base}/api/auth/seed`, { headers: auth.httpHeader });
             if (!seedRes.ok) {
                 const body = await seedRes.json().catch(() => ({}));
                 outro(`Failed to fetch seed: ${body.error || seedRes.statusText}`);
@@ -155,8 +274,9 @@ async function pullRemoteConfig(remoteUrl) {
             }
             const seed = await seedRes.json();
             writeFileSync(join(sgDir, 'auth-seed.json'), JSON.stringify(seed, null, 2), 'utf-8');
-            const authService = new AuthService(sgDir);
-            authService.applySeed();
+            // AuthService appends `.studiograph` — pass workspace root, not `sgDir`.
+            const authService = new AuthService(workspaceRoot);
+            authService.applySeed({ mode: 'overwrite' });
             authService.close();
             outro(`Pulled ${seed.users.length} user${seed.users.length === 1 ? '' : 's'} from ${base}`);
         }
@@ -167,17 +287,147 @@ async function pullRemoteConfig(remoteUrl) {
         }
     }
     catch (err) {
+        // Phase 9c: surface SchemaViolationError with its redaction-safe
+        // message (field path + classification, no values). The error class
+        // is detected by name to avoid pulling the schemas module into the
+        // CLI bundle import graph just for an instanceof check.
+        if (err?.name === 'SchemaViolationError' || err?.code === 'schema_violation') {
+            outro(`Schema violation:\n${err.message}`);
+            process.exit(1);
+        }
         outro(`Failed: ${err.message}`);
         process.exit(1);
     }
 }
+// ─── Remote data pull (git-based) ───────────────────────────────────────────
+// Clones or pulls each folder from the remote's embedded git HTTP server
+// (/git/:repo). Uses git's native conflict detection — diverged folders
+// are reported, not silently overwritten.
+async function pullRemoteData(base, auth, workspaceRoot) {
+    // Reload config — it was just updated by pullRemoteConfig
+    const workspace = new Workspace(workspaceRoot);
+    const config = await workspace.loadConfig();
+    let cloned = 0, updated = 0, upToDate = 0, diverged = 0, errors = 0;
+    for (const repo of config.repos) {
+        if (repo.personal)
+            continue; // personal folders don't sync
+        const repoPath = join(workspaceRoot, repo.path);
+        const remoteUrl = `${base}/git/${repo.name}`;
+        // Clone if missing
+        if (!existsSync(join(repoPath, '.git'))) {
+            try {
+                if (existsSync(repoPath))
+                    rmSync(repoPath, { recursive: true, force: true });
+                mkdirSync(repoPath, { recursive: true });
+                gitClone(remoteUrl, repoPath, { silent: true, credentials: auth.gitCredentials });
+                log.success(`${repo.name}: cloned`);
+                cloned++;
+            }
+            catch (err) {
+                log.error(`${repo.name}: clone failed — ${err.message}`);
+                errors++;
+            }
+            continue;
+        }
+        // Ensure remote points at the requested server (may have been cloned elsewhere)
+        try {
+            gitSetRemote(repoPath, remoteUrl);
+        }
+        catch { /* non-fatal */ }
+        try {
+            const result = gitPull(repoPath, { credentials: auth.gitCredentials });
+            if (result === 'updated') {
+                log.success(`${repo.name}: updated`);
+                updated++;
+            }
+            else if (result === 'up-to-date') {
+                upToDate++;
+            }
+            else {
+                log.warn(`${repo.name}: diverged — has local commits not on the server`);
+                log.info(`     cd ${repoPath} && git pull --rebase`);
+                diverged++;
+            }
+        }
+        catch (err) {
+            log.error(`${repo.name}: ${err.message}`);
+            errors++;
+        }
+    }
+    log.info(`Data: ${cloned} cloned, ${updated} updated, ${upToDate} up to date${diverged ? `, ${diverged} diverged` : ''}${errors ? `, ${errors} failed` : ''}`);
+    if (diverged) {
+        throw new Error('One or more folders diverged — resolve conflicts and retry');
+    }
+    if (errors) {
+        throw new Error('One or more folders failed to pull');
+    }
+}
+// ─── Remote data push (git-based) ───────────────────────────────────────────
+// Pushes each local folder to the remote's embedded git HTTP server.
+// Uses git's native conflict detection — rejected pushes require a pull first.
+async function pushRemoteData(base, auth, workspace, workspaceRoot) {
+    const config = await workspace.loadConfig();
+    let pushed = 0, nothingToPush = 0, created = 0, rejected = 0, errors = 0;
+    for (const repo of config.repos) {
+        if (repo.personal)
+            continue; // personal folders don't sync to a remote we don't control
+        const repoPath = join(workspaceRoot, repo.path);
+        if (!existsSync(join(repoPath, '.git'))) {
+            log.warn(`${repo.name}: not a git repo — skipping`);
+            continue;
+        }
+        try {
+            // Ensure folder exists on remote (idempotent; 409 means it already exists)
+            const status = await ensureServerFolder(base, repo.name, !!repo.personal, auth.httpHeader);
+            if (status === 'created') {
+                log.info(`${repo.name}: created on server`);
+                created++;
+            }
+            // Point origin at the remote's git server
+            gitSetRemote(repoPath, `${base}/git/${repo.name}`);
+            // Push with credentials
+            const result = gitPushWithCredentials(repoPath, auth.gitCredentials);
+            if (result === 'rejected') {
+                log.warn(`${repo.name}: push rejected — run \`studiograph pull --remote ${base} --data\` first`);
+                rejected++;
+                continue;
+            }
+            if (result === 'pushed') {
+                log.success(`${repo.name}: pushed`);
+                pushed++;
+            }
+            else {
+                nothingToPush++;
+            }
+        }
+        catch (err) {
+            log.error(`${repo.name}: ${err.message}`);
+            errors++;
+        }
+    }
+    log.info(`Data: ${pushed} pushed${created ? `, ${created} created` : ''}, ${nothingToPush} unchanged${rejected ? `, ${rejected} rejected` : ''}${errors ? `, ${errors} failed` : ''}`);
+    if (rejected) {
+        throw new Error('One or more folders were rejected — pull and retry');
+    }
+    if (errors) {
+        throw new Error('One or more folders failed to push');
+    }
+}
 // ─── pull ─────────────────────────────────────────────────────────────────────
 export const pullCommand = new Command('pull')
     .description('Pull latest changes from remote across the workspace')
     .option('--remote <url>', 'Pull config from a remote Studiograph server')
+    .option('--data', 'Also pull workspace folder data (markdown files) from the remote server')
+    .option('--token <token>', 'Use a personal API token instead of email/password (also reads STUDIOGRAPH_TOKEN)')
+    .option('--email <email>', 'Email for non-interactive auth (also reads STUDIOGRAPH_EMAIL)')
+    .option('--password <password>', 'Password for non-interactive auth (also reads STUDIOGRAPH_PASSWORD)')
     .action(async (opts) => {
     if (opts.remote) {
-        return pullRemoteConfig(opts.remote);
+        return pullRemoteConfig(opts.remote, opts.data, {
+            token: opts.token,
+            email: opts.email,
+            password: opts.password,
+        });
     }
     const workspace = new Workspace();
     if (!workspace.isWorkspace()) {
@@ -203,13 +453,21 @@ export const pullCommand = new Command('pull')
             else if (result === 'up-to-date') {
                 log.info('.studiograph: already up to date');
             }
+            else {
+                // Diverged / any other non-clean state — surface it the same way
+                // the folder loop does so the user actually sees the problem
+                // instead of walking into a silent no-op.
+                log.warn('.studiograph: diverged — has local commits not on the server');
+                logManualGuidance(configPath);
+                hasConflict = true;
+            }
         }
         catch (error) {
             log.error(`.studiograph: ${error instanceof Error ? error.message : 'Unknown error'}`);
             hasError = true;
         }
     }
-    // ── Step 2: reload config — picks up any new collections added server-side ─
+    // ── Step 2: reload config — picks up any new folders added server-side ─
     // Must use a fresh Workspace instance — loadConfig() caches this.config on
     // first call, so the original instance would return stale data after the pull.
     const freshWorkspace = new Workspace(workspaceRoot);
@@ -220,13 +478,12 @@ export const pullCommand = new Command('pull')
         freshWorkspace.writeConfig(config);
     }
     const serverUrl = (config.server_url ?? savedServerUrl)?.replace(/\/+$/, '');
-    // ── Step 3: pull or clone each collection ────────────────────────────────
+    // ── Step 3: pull or clone each folder ────────────────────────────────
     // Resolve git credentials for the embedded server:
     //   1. Stored JWT from `studiograph join` — per-user access control (preferred)
-    //   2. API key from auth-seed.json — admin access (fallback for workspace owners)
+    //   2. Stored personal API token from ~/.studiograph/user.json
     let serverGitCredentials;
     if (serverUrl) {
-        // Try stored JWT first (saved by studiograph join)
         const serverAuthPath = join(workspaceRoot, '.studiograph', 'server-auth.json');
         if (existsSync(serverAuthPath)) {
             try {
@@ -237,29 +494,22 @@ export const pullCommand = new Command('pull')
             }
             catch { /* non-fatal */ }
         }
-        // Fall back to API key (used by workspace owners who set up with `studiograph serve`)
         if (!serverGitCredentials) {
-            try {
-                const seedPath = join(workspaceRoot, '.studiograph', 'auth-seed.json');
-                if (existsSync(seedPath)) {
-                    const seed = JSON.parse(readFileSync(seedPath, 'utf-8'));
-                    const apiKey = seed.apiKey;
-                    if (apiKey)
-                        serverGitCredentials = { username: '_apikey_', password: apiKey };
-                }
+            const storedToken = getStudiographToken(serverUrl);
+            if (storedToken) {
+                serverGitCredentials = { username: '_token_', password: storedToken };
             }
-            catch { /* non-fatal */ }
         }
     }
     for (const repo of config.repos) {
-        if (repo.private)
+        if (repo.personal)
             continue;
         const repoPath = join(workspaceRoot, repo.path);
-        // New collection — directory missing or exists but isn't a git repo (e.g. failed clone)
+        // New folder — directory missing or exists but isn't a git repo (e.g. failed clone)
         if (!isGitRepo(repoPath)) {
             const cloneUrl = serverUrl ? `${serverUrl}/git/${repo.name}` : null;
             if (!cloneUrl) {
-                log.warn(`${repo.name}: new collection has no remote — skipping`);
+                log.warn(`${repo.name}: new folder has no remote — skipping`);
                 continue;
             }
             try {
@@ -278,7 +528,7 @@ export const pullCommand = new Command('pull')
             }
             continue;
         }
-        // Existing collection — pull if it has a remote
+        // Existing folder — pull if it has a remote
         if (!isGitRepo(repoPath) || !gitHasRemote(repoPath))
             continue;
         try {
@@ -300,12 +550,15 @@ export const pullCommand = new Command('pull')
             hasError = true;
         }
     }
-    // Apply auth seed if it was updated by pulling .studiograph
+    // Apply auth seed if it was updated by pulling .studiograph.
+    // Overwrite mode: the seed file just came from the remote config repo
+    // and is authoritative over any local-shadow rows.
     const seedPath = join(workspaceRoot, '.studiograph', 'auth-seed.json');
     if (existsSync(seedPath)) {
         try {
-            const authService = new AuthService(join(workspaceRoot, '.studiograph'));
-            authService.applySeed();
+            // AuthService appends `.studiograph` — pass workspace root.
+            const authService = new AuthService(workspaceRoot);
+            authService.applySeed({ mode: 'overwrite' });
             authService.close();
         }
         catch {
@@ -317,12 +570,12 @@ export const pullCommand = new Command('pull')
         process.exit(1);
     }
     else if (hasError) {
-        outro('❌ Pull failed for one or more collections.');
+        outro('❌ Pull failed for one or more folders.');
         process.exit(1);
     }
 });
 // ─── Remote config push ─────────────────────────────────────────────────────
-async function pushRemoteConfig(remoteUrl) {
+async function pushRemoteConfig(remoteUrl, includeData = false, authOpts = {}) {
     const workspace = new Workspace();
     if (!workspace.isWorkspace()) {
         console.error('❌ Not a Studiograph workspace. Run `studiograph init` first.');
@@ -332,45 +585,14 @@ async function pushRemoteConfig(remoteUrl) {
     const base = remoteUrl.replace(/\/+$/, '');
     const workspaceRoot = workspace.getWorkspacePath();
     const sgDir = join(workspaceRoot, '.studiograph');
-    // Prompt for admin credentials
-    const email = await text({ message: 'Admin email:', validate: (v) => v.includes('@') ? undefined : 'Enter a valid email' });
-    if (typeof email === 'symbol') {
-        outro('Cancelled');
-        process.exit(0);
-        return;
-    }
-    const password = await passwordPrompt({ message: 'Password:' });
-    if (typeof password === 'symbol') {
-        outro('Cancelled');
-        process.exit(0);
-        return;
-    }
-    // Login
-    log.info('Authenticating...');
-    let token;
+    // Resolve authentication (API key, email+password, env vars, or interactive prompts)
+    let auth;
     try {
-        const loginRes = await fetch(`${base}/api/auth/login`, {
-            method: 'POST',
-            headers: { 'Content-Type': 'application/json' },
-            body: JSON.stringify({ email, password }),
-        });
-        if (!loginRes.ok) {
-            const body = await loginRes.json().catch(() => ({}));
-            outro(`Login failed: ${body.error || loginRes.statusText}`);
-            process.exit(1);
-            return;
-        }
-        const cookies = loginRes.headers.getSetCookie?.() ?? [];
-        const tokenCookie = cookies.find(c => c.startsWith('__sg_token='));
-        if (!tokenCookie) {
-            outro('Login succeeded but no session cookie was returned');
-            process.exit(1);
-            return;
-        }
-        token = tokenCookie.split(';')[0];
+        log.info('Authenticating...');
+        auth = await resolveRemoteAuth(base, workspaceRoot, authOpts);
     }
     catch (err) {
-        outro(`Could not connect to ${base}: ${err.message}`);
+        outro(err.message);
         process.exit(1);
         return;
     }
@@ -402,13 +624,24 @@ async function pushRemoteConfig(remoteUrl) {
     }
     // Connectors (workspace-level, already sanitized)
     const connectors = ConnectorManager.loadWorkspaceConfigs(workspaceRoot);
-    const bundle = { workspace: config, about, authSeed, sources, connectors };
+    // Phase 3: route the bundle through the same sanitizer the server's
+    // GET /api/config/bundle endpoint uses. CLI push and server export now
+    // produce byte-identical output for the same workspace state — bootstrap
+    // class fields (jwtSecret, deprecated apiKey) drop here so the POST
+    // endpoint's strict-reject doesn't bounce older client builds.
+    const bundle = buildConfigBundle({
+        workspace: config,
+        about,
+        authSeed: (authSeed ?? { users: [] }),
+        sources,
+        connectors: connectors,
+    });
     // Push to remote
     log.info('Pushing config...');
     try {
         const res = await fetch(`${base}/api/config/bundle`, {
             method: 'POST',
-            headers: { 'Content-Type': 'application/json', 'Cookie': token },
+            headers: { ...auth.httpHeader, 'Content-Type': 'application/json' },
             body: JSON.stringify(bundle),
         });
         if (!res.ok) {
@@ -423,7 +656,16 @@ async function pushRemoteConfig(remoteUrl) {
                 log.success(item);
             }
         }
-        outro(`Pushed config to ${base}`);
+        // Push workspace data (markdown files) if requested
+        if (includeData) {
+            try {
+                await pushRemoteData(base, auth, workspace, workspaceRoot);
+            }
+            catch (err) {
+                log.error(`Data push failed: ${err.message}`);
+            }
+        }
+        outro(`Pushed to ${base}${includeData ? ' (config + data)' : ' (config)'}`);
     }
     catch (err) {
         outro(`Failed: ${err.message}`);
@@ -449,27 +691,42 @@ async function serverFetch(serverUrl, path, authHeader) {
     }
     return res.json();
 }
-async function ensureServerCollection(serverUrl, repoName, isPrivate, authHeader) {
+async function ensureServerFolder(serverUrl, repoName, isPersonal, authHeader) {
+    const headers = { 'Content-Type': 'application/json' };
+    if (typeof authHeader === 'string') {
+        headers['Authorization'] = authHeader;
+    }
+    else {
+        Object.assign(headers, authHeader);
+    }
     const res = await fetch(`${serverUrl}/api/repos`, {
         method: 'POST',
-        headers: { 'Authorization': authHeader, 'Content-Type': 'application/json' },
-        body: JSON.stringify({ name: repoName, ...(isPrivate ? { private: true } : {}) }),
+        headers,
+        body: JSON.stringify({ name: repoName, ...(isPersonal ? { personal: true } : {}) }),
     });
     if (res.ok)
         return 'created';
     if (res.status === 409)
         return 'exists'; // already exists
     const body = await res.json().catch(() => ({}));
-    throw new Error(body.error || `Failed to create collection "${repoName}": ${res.statusText}`);
+    throw new Error(body.error || `Failed to create folder "${repoName}": ${res.statusText}`);
 }
 // ─── push ─────────────────────────────────────────────────────────────────────
 export const pushCommand = new Command('push')
     .description('Push local commits to remote across the workspace')
-    .argument('[collection]', 'Push a specific collection (default: all)')
+    .argument('[folder]', 'Push a specific folder (default: all)')
     .option('--remote <url>', 'Push config to a remote Studiograph server')
-    .action(async (collection, opts) => {
+    .option('--data', 'Also push workspace folder data (markdown files) to the remote server')
+    .option('--token <token>', 'Use a personal API token instead of email/password (also reads STUDIOGRAPH_TOKEN)')
+    .option('--email <email>', 'Email for non-interactive auth (also reads STUDIOGRAPH_EMAIL)')
+    .option('--password <password>', 'Password for non-interactive auth (also reads STUDIOGRAPH_PASSWORD)')
+    .action(async (folder, opts) => {
     if (opts.remote) {
-        return pushRemoteConfig(opts.remote);
+        return pushRemoteConfig(opts.remote, opts.data, {
+            token: opts.token,
+            email: opts.email,
+            password: opts.password,
+        });
     }
     const workspace = new Workspace();
     if (!workspace.isWorkspace()) {
@@ -480,12 +737,19 @@ export const pushCommand = new Command('push')
     const workspaceRoot = workspace.getWorkspacePath();
     const config = await workspace.loadConfig();
     const serverUrl = config.server_url?.replace(/\/+$/, '');
-    // Build list of repos to push
-    let repos = config.repos.filter(r => !r.private || serverUrl); // include private only when pushing to server
-    if (collection) {
-        const match = repos.find(r => r.name === collection);
+    // Build list of repos to push. Personal folders are included when
+    // pushing to a server — they're per-user, but git-http
+    // (canAccessFolder → hasRepoAccess) gates by owner so only the owner
+    // ever succeeds. Server-side, personal folders are auto-provisioned
+    // on login by auth-api.ts#ensurePrivateFolder, so the per-folder
+    // ensureServerFolder() call is skipped for them below (the
+    // createSharedFolder path would reject `entries-<number>` as a
+    // reserved name even though the folder already exists).
+    let repos = config.repos.filter(r => !r.personal || serverUrl);
+    if (folder) {
+        const match = repos.find(r => r.name === folder);
         if (!match) {
-            log.error(`Collection "${collection}" not found in workspace.`);
+            log.error(`Folder "${folder}" not found in workspace.`);
             process.exit(1);
             return;
         }
@@ -496,34 +760,44 @@ export const pushCommand = new Command('push')
         // Resolve credentials: JWT (per-user) → API key (admin) → prompt
         let authHeader;
         let gitCredentials;
-        // 1. Stored JWT from `studiograph join` (per-user access control)
+        // 1. Stored JWT from `studiograph join` (per-user access control).
+        //
+        // Auth-header format note: the main API auth middleware (server/
+        // index.ts:215) accepts Basic only as `email:<password>` — it does
+        // NOT accept JWT-as-Basic-password. The git-http handler does
+        // (routes/git-http.ts authenticateBasic has explicit branches for
+        // `eyJ...` JWTs and `sg_...` tokens). So one stored JWT yields two
+        // different headers: `Bearer <jwt>` for API calls (serverFetch,
+        // ensureServerFolder) and Basic with JWT-as-password for git push
+        // (gitPushWithCredentials → askpass). Same logic for stored API
+        // tokens below.
         const pushServerAuthPath = join(workspaceRoot, '.studiograph', 'server-auth.json');
         try {
             if (existsSync(pushServerAuthPath)) {
                 const sa = JSON.parse(readFileSync(pushServerAuthPath, 'utf-8'));
                 if (sa.email && sa.jwtToken) {
-                    authHeader = makeBasicAuth(sa.email, sa.jwtToken);
+                    authHeader = `Bearer ${sa.jwtToken}`;
                     gitCredentials = { username: sa.email, password: sa.jwtToken };
                 }
             }
         }
         catch { /* non-fatal */ }
-        // 2. API key fallback (workspace owners who set up with `studiograph serve`)
-        if (!authHeader) {
-            try {
-                const seedPathPush = join(workspaceRoot, '.studiograph', 'auth-seed.json');
-                if (existsSync(seedPathPush)) {
-                    const seed = JSON.parse(readFileSync(seedPathPush, 'utf-8'));
-                    const pushApiKey = seed.apiKey;
-                    if (pushApiKey) {
-                        authHeader = makeBasicAuth('_apikey_', pushApiKey);
-                        gitCredentials = { username: '_apikey_', password: pushApiKey };
-                    }
-                }
+        // 2. Stored personal API token fallback
+        if (!authHeader && serverUrl) {
+            const storedToken = getStudiographToken(serverUrl);
+            if (storedToken) {
+                authHeader = `Bearer ${storedToken}`;
+                gitCredentials = { username: '_token_', password: storedToken };
             }
-            catch { /* non-fatal */ }
         }
-        // 3. Interactive credential prompt as last resort
+        // 3. Interactive credential prompt as last resort. After successful
+        // auth, exchange the password for a JWT and persist it to
+        // server-auth.json so the next run skips the prompt entirely.
+        // Without this step, every push prompts again — the previous
+        // behavior used the typed password as Basic auth ad-hoc and never
+        // wrote the file (a real DX papercut surfaced after `studiograph
+        // clone` deleted server-auth.json or a Railway restart invalidated
+        // the JWT secret).
         if (!authHeader) {
             const email = await text({ message: 'Email:', validate: (v) => v.includes('@') ? undefined : 'Enter a valid email' });
             if (typeof email === 'symbol') {
@@ -537,8 +811,21 @@ export const pushCommand = new Command('push')
                 process.exit(0);
                 return;
             }
-            authHeader = makeBasicAuth(String(email), String(pass));
-            gitCredentials = { username: String(email), password: String(pass) };
+            try {
+                const jwtToken = await loginForJwt(serverUrl, String(email), String(pass));
+                persistServerAuth(workspaceRoot, serverUrl, String(email), jwtToken);
+                // Bearer for API calls; Basic with JWT-as-password for git push.
+                // See header-format note on the stored-JWT branch above.
+                authHeader = `Bearer ${jwtToken}`;
+                gitCredentials = { username: String(email), password: jwtToken };
+            }
+            catch (err) {
+                // Surface the underlying auth failure rather than silently
+                // falling through with bogus basic-auth that'll fail later.
+                outro(`Authentication failed: ${err.message}`);
+                process.exit(1);
+                return;
+            }
         }
         // All three branches above either set credentials or exit — this is a safety guard
         if (!authHeader || !gitCredentials) {
@@ -546,14 +833,60 @@ export const pushCommand = new Command('push')
             process.exit(1);
             return;
         }
-        // Validate credentials
+        // Validate credentials. If a stored JWT or token has been
+        // invalidated (Railway restart that regenerated the JWT secret,
+        // server-side token revoke, etc.), fall through to the interactive
+        // prompt instead of exiting — typing email+password should always
+        // be a viable last resort. We bound the retry to one attempt so
+        // bad credentials don't loop forever.
+        let validated = false;
         try {
             await serverFetch(serverUrl, '/api/workspace', authHeader);
+            validated = true;
         }
         catch (err) {
-            outro(`Authentication failed: ${err.message}`);
-            process.exit(1);
-            return;
+            // Stored credential failed. Clear it so the next run can't loop
+            // on the same stale value, then drop to a fresh prompt below.
+            try {
+                rmSync(pushServerAuthPath, { force: true });
+            }
+            catch { /* non-fatal */ }
+        }
+        if (!validated) {
+            log.warn('Stored credentials rejected — re-authenticate.');
+            const email = await text({ message: 'Email:', validate: (v) => v.includes('@') ? undefined : 'Enter a valid email' });
+            if (typeof email === 'symbol') {
+                outro('Cancelled');
+                process.exit(0);
+                return;
+            }
+            const pass = await passwordPrompt({ message: 'Password:' });
+            if (typeof pass === 'symbol') {
+                outro('Cancelled');
+                process.exit(0);
+                return;
+            }
+            try {
+                const jwtToken = await loginForJwt(serverUrl, String(email), String(pass));
+                persistServerAuth(workspaceRoot, serverUrl, String(email), jwtToken);
+                // Bearer for API calls; Basic with JWT-as-password for git push.
+                // See header-format note on the stored-JWT branch above.
+                authHeader = `Bearer ${jwtToken}`;
+                gitCredentials = { username: String(email), password: jwtToken };
+            }
+            catch (err) {
+                outro(`Authentication failed: ${err.message}`);
+                process.exit(1);
+                return;
+            }
+            try {
+                await serverFetch(serverUrl, '/api/workspace', authHeader);
+            }
+            catch (err) {
+                outro(`Authentication failed: ${err.message}`);
+                process.exit(1);
+                return;
+            }
         }
         let hasError = false;
         for (const repo of repos) {
@@ -562,11 +895,24 @@ export const pushCommand = new Command('push')
                 log.warn(`${repo.name}: not a git repo, skipping`);
                 continue;
             }
+            // Personal folders skip the /api/repos POST. Detection has TWO
+            // sources because `studiograph clone` strips the `personal: true`
+            // flag from cloned workspace.json (alongside r2_config and
+            // railway — see memory:studiograph_clone_strips_config). So we
+            // also infer from the reserved name pattern: anything matching
+            // `entries-<digit>` is owned by the user with that id and was
+            // auto-provisioned server-side via auth-api.ts#ensurePrivateFolder
+            // on login. The /api/repos path goes through createSharedFolder
+            // which rejects this exact pattern; the git push that follows
+            // hits git-http directly where canAccessFolder gates by owner.
+            const isPersonalByPattern = /^entries-\d+$/.test(repo.name);
+            const skipServerFolderEnsure = !!repo.personal || isPersonalByPattern;
             try {
-                // Ensure collection exists on server
-                const status = await ensureServerCollection(serverUrl, repo.name, !!repo.private, authHeader);
-                if (status === 'created') {
-                    log.info(`${repo.name}: created on server`);
+                if (!skipServerFolderEnsure) {
+                    const status = await ensureServerFolder(serverUrl, repo.name, false, authHeader);
+                    if (status === 'created') {
+                        log.info(`${repo.name}: created on server`);
+                    }
                 }
                 // Set origin to server git URL
                 gitSetRemote(repoPath, `${serverUrl}/git/${repo.name}`);
@@ -598,12 +944,12 @@ export const pushCommand = new Command('push')
     // Fallback: plain git push for repos that already have remotes
     const entries = await getRepoEntries(workspace, workspaceRoot);
     if (entries.length === 0) {
-        log.info('No collections with remotes to push to. Use `studiograph join` to connect to a server.');
+        log.info('No folders with remotes to push to. Use `studiograph join` to connect to a server.');
         return;
     }
     let hasError = false;
     for (const entry of entries) {
-        if (collection && entry.name !== collection)
+        if (folder && entry.name !== folder)
             continue;
         try {
             let result = gitPush(entry.path);
@@ -625,7 +971,7 @@ export const pushCommand = new Command('push')
         }
     }
     if (hasError) {
-        outro('Push failed for one or more collections.');
+        outro('Push failed for one or more folders.');
         process.exit(1);
     }
 });