Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
fix(open-knowledge): correct sync dialog for missing credential + resume after reconnect (#1743)
Andrew Mikofalvyfc3e907b5049
diff --git a/.changeset/sync-no-credential-recovery.md b/.changeset/sync-no-credential-recovery.mdnew file mode 100644index 000000000..b5e106332--- /dev/null+++ b/.changeset/sync-no-credential-recovery.md@@ -0,0 +1,5 @@+---+"@inkeep/open-knowledge": patch+---++Fix the sync status dialog and recovery when a GitHub credential is missing. Previously a credential-less fetch/push was misclassified as a retryable network error, so the popover showed "Offline" with a raw `could not read Username … Device not configured` stderr blob and "Sync now" / "Retry" buttons that could never succeed — and the one useful action, reconnecting GitHub, was never offered. Now this is classified as an auth error (`auth-no-credential`): the dialog reads "Reconnect required" with a clear one-line message ("GitHub sign-in is missing or expired. Reconnect to resume syncing.") and a single "Connect GitHub" button. Reconnecting resumes sync without an app restart, and the auth-error state no longer persists across restarts. The server also sets `GIT_TERMINAL_PROMPT=0` so git fails fast instead of attempting a no-TTY prompt.diff --git a/packages/app/src/components/SyncStatusBadge.test.ts b/packages/app/src/components/SyncStatusBadge.test.tsindex 2645d558f..0578c7d48 100644--- a/packages/app/src/components/SyncStatusBadge.test.ts+++ b/packages/app/src/components/SyncStatusBadge.test.ts@@ -120,6 +120,15 @@ describe('formatSyncFailureCode — neutral collapsed copy', () => {expect(formatSyncFailureCode('auth-403')).not.toBe(formatPushFailureCode('auth-403'));expect(formatSyncFailureCode('auth-403')).toBe(formatPullFailureCode('auth-403'));});++ test('auth-no-credential copy directs the user to reconnect (all three formatters)', async () => {+ const { formatSyncFailureCode, formatPushFailureCode, formatPullFailureCode } = await import(+ './SyncStatusBadge'+ );+ for (const fmt of [formatSyncFailureCode, formatPushFailureCode, formatPullFailureCode]) {+ expect(fmt('auth-no-credential')).toMatch(/reconnect/i);+ }+ });});describe('computeSyncErrorLines — collapse + label truth table', () => {diff --git a/packages/app/src/components/SyncStatusBadge.tsx b/packages/app/src/components/SyncStatusBadge.tsxindex 3b6588774..879d101f2 100644--- a/packages/app/src/components/SyncStatusBadge.tsx+++ b/packages/app/src/components/SyncStatusBadge.tsx@@ -169,6 +169,8 @@ export function formatPushFailureCode(code: SyncErrorCode): string {return t`GitHub authentication failed. Try signing in again.`;case 'auth-scope-mismatch':return t`Your GitHub token is missing required scopes. Try signing in again.`;+ case 'auth-no-credential':+ return t`GitHub sign-in is missing or expired. Reconnect to resume syncing.`;case 'semantic-protected-branch':return t`The default branch is protected — pushes need a pull request.`;default:@@ -184,6 +186,8 @@ export function formatPullFailureCode(code: SyncErrorCode): string {return t`GitHub authentication failed. Try signing in again.`;case 'auth-scope-mismatch':return t`Your GitHub token is missing required scopes. Try signing in again.`;+ case 'auth-no-credential':+ return t`GitHub sign-in is missing or expired. Reconnect to resume syncing.`;default:return t`Fetch failed — check the server logs for details.`;}@@ -197,6 +201,8 @@ export function formatSyncFailureCode(code: SyncErrorCode): string {return t`GitHub authentication failed. Try signing in again.`;case 'auth-scope-mismatch':return t`Your GitHub token is missing required scopes. Try signing in again.`;+ case 'auth-no-credential':+ return t`GitHub sign-in is missing or expired. Reconnect to resume syncing.`;case 'semantic-protected-branch':return t`The default branch is protected — pushes need a pull request.`;default:diff --git a/packages/app/src/locales/en/messages.json b/packages/app/src/locales/en/messages.jsonindex 4feac0cc7..2d9b163f6 100644--- a/packages/app/src/locales/en/messages.json+++ b/packages/app/src/locales/en/messages.json@@ -1662,6 +1662,7 @@"u3wRF-": ["Published"],"u6Hp4N": ["Markdown"],"u7H-Wn": ["Show panel (", ["panelShortcutLabel"], ")"],+ "uCaIdy": ["GitHub sign-in is missing or expired. Reconnect to resume syncing."],"uF9ruK": ["Saving"],"uH_S-u": [["loadErrorTitle"], ": ", ["message"]],"uKRYiW": ["Sync status unavailable — server error."],diff --git a/packages/app/src/locales/en/messages.po b/packages/app/src/locales/en/messages.poindex 41faf8dbb..496bd32fe 100644--- a/packages/app/src/locales/en/messages.po+++ b/packages/app/src/locales/en/messages.po@@ -2442,6 +2442,10 @@ msgstr "Git identity isn't set — commits use a default author. Set yours so temsgid "GitHub authentication failed. Try signing in again."msgstr "GitHub authentication failed. Try signing in again."+#: src/components/SyncStatusBadge.tsx+msgid "GitHub sign-in is missing or expired. Reconnect to resume syncing."+msgstr "GitHub sign-in is missing or expired. Reconnect to resume syncing."+#: src/lib/keyboard-shortcuts.tsmsgid "Global"msgstr "Global"diff --git a/packages/app/src/locales/pseudo/messages.json b/packages/app/src/locales/pseudo/messages.jsonindex 87b1a965e..ab0de2ed6 100644--- a/packages/app/src/locales/pseudo/messages.json+++ b/packages/app/src/locales/pseudo/messages.json@@ -1662,6 +1662,7 @@"u3wRF-": ["Ƥũƀĺĩśĥēď"],"u6Hp4N": ["Ḿàŕķďōŵń"],"u7H-Wn": ["Śĥōŵ ƥàńēĺ (", ["panelShortcutLabel"], ")"],+ "uCaIdy": ["ĜĩţĤũƀ śĩĝń-ĩń ĩś ḿĩśśĩńĝ ōŕ ēxƥĩŕēď. Ŕēćōńńēćţ ţō ŕēśũḿē śŷńćĩńĝ."],"uF9ruK": ["Śàvĩńĝ"],"uH_S-u": [["loadErrorTitle"], ": ", ["message"]],"uKRYiW": ["Śŷńć śţàţũś ũńàvàĩĺàƀĺē — śēŕvēŕ ēŕŕōŕ."],diff --git a/packages/app/src/locales/pseudo/messages.po b/packages/app/src/locales/pseudo/messages.poindex 78fce2596..2397597cd 100644--- a/packages/app/src/locales/pseudo/messages.po+++ b/packages/app/src/locales/pseudo/messages.po@@ -2437,6 +2437,10 @@ msgstr ""msgid "GitHub authentication failed. Try signing in again."msgstr ""+#: src/components/SyncStatusBadge.tsx+msgid "GitHub sign-in is missing or expired. Reconnect to resume syncing."+msgstr ""+#: src/lib/keyboard-shortcuts.tsmsgid "Global"msgstr ""diff --git a/packages/core/src/schemas/api/sync-seed.ts b/packages/core/src/schemas/api/sync-seed.tsindex f3ef94b1a..2cd4b6e88 100644--- a/packages/core/src/schemas/api/sync-seed.ts+++ b/packages/core/src/schemas/api/sync-seed.ts@@ -45,6 +45,7 @@ export const SYNC_ERROR_CODES = ['auth-403','auth-401','auth-scope-mismatch',+ 'auth-no-credential','semantic-protected-branch',] as const;diff --git a/packages/server/src/api-extension.test.ts b/packages/server/src/api-extension.test.tsindex 49fabd306..13dae834d 100644--- a/packages/server/src/api-extension.test.ts+++ b/packages/server/src/api-extension.test.ts@@ -3,7 +3,9 @@ import { existsSync, mkdirSync, symlinkSync, writeFileSync } from 'node:fs';import { mkdtemp, rm } from 'node:fs/promises';import { tmpdir } from 'node:os';import { join, resolve } from 'node:path';-import { safeSubdir, sanitizeFilename } from './api-extension.ts';+import { resumeSyncOnAuthEvent, safeSubdir, sanitizeFilename } from './api-extension.ts';+import type { AuthEvent } from './local-ops/types.ts';+import type { SyncEngine } from './sync-engine.ts';describe('safeSubdir', () => {const baseDir = '/home/user/content';@@ -540,3 +542,53 @@ describe('handleUploadAsset — same-dir sha256 dedup (FR-2)', () => {expect(res.deduped).toBe(false);});});++describe('resumeSyncOnAuthEvent (reconnect → resume wiring)', () => {+ const makeEngineStub = (impl?: () => Promise<void>) => {+ const calls: number[] = [];+ const engine = {+ notifyCredentialsChanged: () => {+ calls.push(Date.now());+ return impl ? impl() : Promise.resolve();+ },+ } as unknown as SyncEngine;+ return { engine, calls, getSyncEngine: () => engine };+ };++ const completeEvent: AuthEvent = { type: 'complete', host: 'github.com', login: 'octocat' };+ const verificationEvent: AuthEvent = {+ type: 'verification',+ user_code: 'ABCD-1234',+ verification_uri: 'https://github.com/login/device',+ expires_in: 900,+ };+ const errorEvent: AuthEvent = { type: 'error', message: 'denied' };++ test('a complete event resumes sync via notifyCredentialsChanged', () => {+ const stub = makeEngineStub();+ resumeSyncOnAuthEvent(completeEvent, stub.getSyncEngine);+ expect(stub.calls.length).toBe(1);+ });++ test('non-complete events do not resume sync', () => {+ const stub = makeEngineStub();+ resumeSyncOnAuthEvent(verificationEvent, stub.getSyncEngine);+ resumeSyncOnAuthEvent(errorEvent, stub.getSyncEngine);+ expect(stub.calls.length).toBe(0);+ });++ test('absent getSyncEngine is a no-op (engine dormant / not yet constructed)', () => {+ expect(() => resumeSyncOnAuthEvent(completeEvent, undefined)).not.toThrow();+ });++ test('a null engine is a no-op', () => {+ expect(() => resumeSyncOnAuthEvent(completeEvent, () => null)).not.toThrow();+ });++ test('a rejected notifyCredentialsChanged is swallowed (best-effort)', async () => {+ const stub = makeEngineStub(() => Promise.reject(new Error('boom')));+ expect(() => resumeSyncOnAuthEvent(completeEvent, stub.getSyncEngine)).not.toThrow();+ expect(stub.calls.length).toBe(1);+ await Promise.resolve();+ });+});diff --git a/packages/server/src/api-extension.ts b/packages/server/src/api-extension.tsindex bb3afd32e..277f0b1eb 100644--- a/packages/server/src/api-extension.ts+++ b/packages/server/src/api-extension.ts@@ -559,6 +559,16 @@ export function __resetRenameTelemetryForTesting(): void {_renameAttributionCounter = null;}+export function resumeSyncOnAuthEvent(+ event: AuthEvent,+ getSyncEngine?: () => SyncEngine | null,+): void {+ if (event.type !== 'complete') return;+ void getSyncEngine?.()+ ?.notifyCredentialsChanged()+ .catch(() => {});+}+export const ROLLBACK_ORIGIN = {source: 'local' as const,skipStoreHooks: false,@@ -8283,6 +8293,7 @@ export function createApiExtension(options: ApiExtensionOptions): Extension {});return;}+ resumeSyncOnAuthEvent(event, getSyncEngine);if (!res.writableEnded && !res.destroyed) {try {res.write(`${JSON.stringify(event)}\n`);diff --git a/packages/server/src/error-classification.test.ts b/packages/server/src/error-classification.test.tsindex a3ab27bbb..6368385cf 100644--- a/packages/server/src/error-classification.test.ts+++ b/packages/server/src/error-classification.test.ts@@ -109,6 +109,47 @@ describe('classifyGitError', () => {expect(r.subclass).toBe('scope-mismatch');expect(r.retryable).toBe(false);});++ test('no credential — "could not read Username … Device not configured" (no GIT_TERMINAL_PROMPT)', () => {+ const r = classifyGitError(+ mkErr(+ 'fatal: could not read Username',+ "fatal: could not read Username for 'https://github.com': Device not configured",+ ),+ );+ expect(r.class).toBe('auth');+ expect(r.subclass).toBe('no-credential');+ expect(r.retryable).toBe(false);+ expect(r.userFacingCode).toBe('auth-no-credential');+ });++ test('no credential — "terminal prompts disabled" (with GIT_TERMINAL_PROMPT=0)', () => {+ const r = classifyGitError(+ mkErr(+ 'fatal: could not read Username',+ "fatal: could not read Username for 'https://github.com': terminal prompts disabled",+ ),+ );+ expect(r.class).toBe('auth');+ expect(r.subclass).toBe('no-credential');+ expect(r.retryable).toBe(false);+ expect(r.userFacingCode).toBe('auth-no-credential');+ });++ test('no credential — could not read Password', () => {+ const r = classifyGitError(+ mkErr(+ 'fatal',+ "could not read Password for 'https://github.com': terminal prompts disabled",+ ),+ );+ expect(r.class).toBe('auth');+ expect(r.subclass).toBe('no-credential');+ });++ test('deriveUserFacingCode maps auth/no-credential', () => {+ expect(deriveUserFacingCode('auth', 'no-credential')).toBe('auth-no-credential');+ });});describe('Class 3 — Semantic (non-retryable)', () => {@@ -400,11 +441,13 @@ describe('classifyGitError', () => {'auth-403','auth-401','auth-scope-mismatch',+ 'auth-no-credential','semantic-protected-branch',]);const samples = [mkErr('Could not resolve host: github.com'),mkErr('HTTP 403: forbidden'),+ mkErr("fatal: could not read Username for 'https://github.com': terminal prompts disabled"),mkErr('CONFLICT'),mkErr('lfs storage quota exceeded'),mkErr('Unknown error'),diff --git a/packages/server/src/error-classification.ts b/packages/server/src/error-classification.tsindex 538374f97..a41fe19de 100644--- a/packages/server/src/error-classification.ts+++ b/packages/server/src/error-classification.ts@@ -1,7 +1,13 @@import type { SyncErrorCode } from '@inkeep/open-knowledge-core';type NetworkSubclass = 'dns' | 'timeout' | '5xx' | '429' | 'connection-refused' | 'unknown-network';-type AuthSubclass = '401' | '403' | 'expired-token' | 'scope-mismatch' | 'unknown-auth';+type AuthSubclass =+ | '401'+ | '403'+ | 'expired-token'+ | 'scope-mismatch'+ | 'no-credential'+ | 'unknown-auth';type SemanticSubclass =| 'non-fast-forward'| 'protected-branch'@@ -66,6 +72,7 @@ export function deriveUserFacingCode(if (cls === 'auth' && subclass === '403') return 'auth-403';if (cls === 'auth' && subclass === '401') return 'auth-401';if (cls === 'auth' && subclass === 'scope-mismatch') return 'auth-scope-mismatch';+ if (cls === 'auth' && subclass === 'no-credential') return 'auth-no-credential';if (cls === 'semantic' && subclass === 'protected-branch') return 'semantic-protected-branch';return null;}@@ -93,6 +100,11 @@ const AUTH_PATTERNS: RegExp[] = [/fatal:.*repository.*not found/i, // often auth-related on private repos];+const NO_CREDENTIAL_PATTERNS: RegExp[] = [+ /could not read (username|password)/i,+ /terminal prompts disabled/i,+];+const SCOPE_MISMATCH_PATTERNS: RegExp[] = [/insufficient scopes/i,/missing.*scope/i,@@ -245,6 +257,15 @@ function classifyGitErrorBase(error: Error | unknown): ClassifiedErrorBase {};}+ if (matchesAny(combined, NO_CREDENTIAL_PATTERNS)) {+ return {+ class: 'auth',+ subclass: 'no-credential',+ retryable: false,+ message: 'No GitHub credential available — reconnect to resume syncing',+ rawStderr: raw,+ };+ }if (matchesAny(combined, SCOPE_MISMATCH_PATTERNS)) {return {class: 'auth',diff --git a/packages/server/src/git-handle.test.ts b/packages/server/src/git-handle.test.tsindex 7dea521f3..eadaf9843 100644--- a/packages/server/src/git-handle.test.ts+++ b/packages/server/src/git-handle.test.ts@@ -26,6 +26,10 @@ describe('buildGitEnv', () => {expect(env.LC_ALL).toBe('C');});+ test('disables terminal prompts (no-TTY server-spawned git)', () => {+ expect(buildGitEnv().GIT_TERMINAL_PROMPT).toBe('0');+ });+test('preserves PATH so a bare-command credential helper resolves', () => {withEnv('PATH', '/custom/bin:/usr/bin', () => {expect(buildGitEnv().PATH).toBe('/custom/bin:/usr/bin');diff --git a/packages/server/src/git-handle.ts b/packages/server/src/git-handle.tsindex 584d647b9..71ba2f48b 100644--- a/packages/server/src/git-handle.ts+++ b/packages/server/src/git-handle.ts@@ -21,7 +21,7 @@ type CredentialHelperUnsafeGitOptions = SimpleGitOptions & {};export function buildGitEnv(): Record<string, string> {- const env: Record<string, string> = { LANG: 'C', LC_ALL: 'C' };+ const env: Record<string, string> = { LANG: 'C', LC_ALL: 'C', GIT_TERMINAL_PROMPT: '0' };if (process.env.PATH !== undefined) {env.PATH = process.env.PATH;}diff --git a/packages/server/src/sync-engine.test.ts b/packages/server/src/sync-engine.test.tsindex 57888a0f7..bcac7e406 100644--- a/packages/server/src/sync-engine.test.ts+++ b/packages/server/src/sync-engine.test.ts@@ -1351,3 +1351,85 @@ describe('SyncEngine getStatus() with restored state', () => {expect(status.lastPushedSha).toBe('abc123');});});++interface InternalState {+ state: SyncState;+ pausedReason?: string;+ pushError?: string;+ pullError?: string;+ pushErrorCode?: string;+ pullErrorCode?: string;+}++describe('SyncEngine auth-error recovery', () => {+ const statePath = () => join(okDir, 'sync-state.json');++ test('does not restore a persisted auth-error pausedReason (re-attempts on restart)', async () => {+ writeFileSync(+ statePath(),+ JSON.stringify({+ version: 1,+ lastSyncUtc: null,+ lastFetchUtc: null,+ lastPushedSha: null,+ consecutiveFailures: 0,+ inflightConflicts: [],+ pausedReason: 'auth-error',+ }),+ 'utf-8',+ );+ const engine = makeEngine({ syncEnabled: false });+ await engine.start();+ expect(engine.getStatus().pausedReason).toBeUndefined();+ });++ test('saveStateNow does not persist auth-error when set in-memory', async () => {+ const engine = makeEngine({ syncEnabled: true });+ const internal = engine as unknown as InternalState;+ internal.state = 'auth-error';+ internal.pausedReason = 'auth-error';++ await engine.destroy(); // saveStateNow flushes the in-memory pausedReason++ const reloaded = JSON.parse(readFileSync(statePath(), 'utf-8')) as { pausedReason?: string };+ expect(reloaded.pausedReason).toBeUndefined();+ });++ test('notifyCredentialsChanged clears auth-error and re-evaluates', async () => {+ const engine = makeEngine({ syncEnabled: true });+ const internal = engine as unknown as InternalState;+ internal.state = 'auth-error';+ internal.pausedReason = 'auth-error';+ internal.pushError = 'no credential';+ internal.pullError = 'no credential';+ internal.pushErrorCode = 'auth-no-credential';+ internal.pullErrorCode = 'auth-no-credential';+ expect(engine.getStatus().state).toBe('auth-error');++ await engine.notifyCredentialsChanged();++ const status = engine.getStatus();+ expect(status.state).not.toBe('auth-error');+ expect(status.pausedReason).toBeUndefined();+ expect(status.pushError).toBeUndefined();+ expect(status.pullError).toBeUndefined();+ expect(status.pushErrorCode).toBeUndefined();+ expect(status.pullErrorCode).toBeUndefined();+ expect(status.state).toBe('dormant');+ await engine.destroy();+ });++ test('notifyCredentialsChanged is a no-op when sync is disabled', async () => {+ const engine = makeEngine({ syncEnabled: false });+ (engine as unknown as InternalState).pausedReason = 'auth-error';+ await engine.notifyCredentialsChanged();+ expect(engine.getStatus().pausedReason).toBe('auth-error');+ });++ test('notifyCredentialsChanged is a no-op when not parked on auth-error', async () => {+ const engine = makeEngine({ syncEnabled: true });+ const before = engine.getStatus().state;+ await engine.notifyCredentialsChanged();+ expect(engine.getStatus().state).toBe(before);+ });+});diff --git a/packages/server/src/sync-engine.ts b/packages/server/src/sync-engine.tsindex 3486b4bed..e284ba120 100644--- a/packages/server/src/sync-engine.ts+++ b/packages/server/src/sync-engine.ts@@ -442,6 +442,29 @@ export class SyncEngine {void this.probePushPermissionInternal('refresh');}+ async notifyCredentialsChanged(): Promise<void> {+ if (!this.syncEnabled) return;+ if (this.state !== 'auth-error' && this.pausedReason !== 'auth-error') return;++ this.pausedReason = undefined;+ this.clearPushError();+ this.clearPullError();+ this.consecutiveFailures = 0;++ this.hasRemote = await this.probeRemote();+ if (!this.hasRemote) {+ this.transitionTo('dormant');+ this.saveStateNow();+ return;+ }++ this.transitionTo('idle');+ this.schedulePull(0);+ this.schedulePush();+ this.saveStateNow();+ void this.probePushPermissionInternal('refresh');+ }+async trigger(op: 'sync' | 'push' | 'pull' = 'sync'): Promise<void> {this.consecutiveFailures = 0;if (@@ -768,7 +791,8 @@ export class SyncEngine {private async runPullCycle(): Promise<void> {if (this.pullInFlight) return;- if (this.state === 'dormant' || this.state === 'disabled') return;+ if (this.state === 'dormant' || this.state === 'disabled' || this.state === 'auth-error')+ return;if (this.state === 'conflict') {this.schedulePull(); // retry after interval but don't fetch while conflictedreturn;@@ -1578,7 +1602,9 @@ export class SyncEngine {private saveStateNow(): void {try {const persistedReason =- this.pausedReason === 'no-push-permission' ? undefined : this.pausedReason;+ this.pausedReason === 'no-push-permission' || this.pausedReason === 'auth-error'+ ? undefined+ : this.pausedReason;const data: PersistedSyncState = {version: 1,lastSyncUtc: this.lastSyncUtc,@@ -1606,7 +1632,9 @@ export class SyncEngine {this.lastPushedSha = data.lastPushedSha ?? null;this.consecutiveFailures = data.consecutiveFailures ?? 0;this.pausedReason =- data.pausedReason === 'no-push-permission' ? undefined : data.pausedReason;+ data.pausedReason === 'no-push-permission' || data.pausedReason === 'auth-error'+ ? undefined+ : data.pausedReason;const inflightFiles = data.inflightConflicts ?? [];if (inflightFiles.length > 0) {