@applica-software-guru/sdd-core 1.4.1 → 1.5.0

package/src/remote/api-client.ts

@@ -1,15 +1,30 @@
 import type { SDDConfig } from '../types.js';
-import { RemoteError, RemoteNotConfiguredError } from '../errors.js';
+import { RemoteError, RemoteNotConfiguredError, RemoteTimeoutError } from '../errors.js';
 import type {
   RemoteDocResponse,
   RemoteDocBulkResponse,
   RemoteCRResponse,
+  RemoteCRBulkResponse,
   RemoteBugResponse,
+  RemoteBugBulkResponse,
 } from './types.js';
 
+/** Default timeout for remote operations (seconds) */
+export const DEFAULT_REMOTE_TIMEOUT = 300;
+
+/** Status codes that trigger a retry (server not ready / cold start) */
+const RETRYABLE_STATUS_CODES = new Set([502, 503, 504]);
+
+/** Initial backoff delay in ms */
+const INITIAL_BACKOFF_MS = 3_000;
+
+/** Maximum backoff delay in ms */
+const MAX_BACKOFF_MS = 30_000;
+
 export interface ApiClientConfig {
   baseUrl: string;
   apiKey: string;
+  timeout: number;
 }
 
 /**
@@ -25,7 +40,12 @@ export function resolveApiKey(config: SDDConfig): string | null {
  * Build an ApiClientConfig from the SDD project config.
  * Throws RemoteNotConfiguredError if URL or API key is missing.
  */
-export function buildApiConfig(config: SDDConfig): ApiClientConfig {
+/**
+ * Build an ApiClientConfig from the SDD project config.
+ * Throws RemoteNotConfiguredError if URL or API key is missing.
+ * An optional timeoutOverride (from --timeout flag) takes precedence over config.
+ */
+export function buildApiConfig(config: SDDConfig, timeoutOverride?: number): ApiClientConfig {
   if (!config.remote?.url) {
     throw new RemoteNotConfiguredError();
   }
@@ -36,9 +56,24 @@ export function buildApiConfig(config: SDDConfig): ApiClientConfig {
   return {
     baseUrl: config.remote.url.replace(/\/+$/, ''),
     apiKey,
+    timeout: timeoutOverride ?? config.remote.timeout ?? DEFAULT_REMOTE_TIMEOUT,
   };
 }
 
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function isRetryable(error: unknown): boolean {
+  if (error instanceof RemoteError) {
+    return RETRYABLE_STATUS_CODES.has(error.statusCode);
+  }
+  // Network errors (ECONNREFUSED, ENOTFOUND, fetch abort due to connection failure)
+  if (error instanceof TypeError) return true;
+  const code = (error as NodeJS.ErrnoException).code;
+  return code === 'ECONNREFUSED' || code === 'ECONNRESET' || code === 'ENOTFOUND' || code === 'UND_ERR_CONNECT_TIMEOUT';
+}
+
 async function request<T>(
   config: ApiClientConfig,
   method: string,
@@ -51,24 +86,82 @@ async function request<T>(
     'Content-Type': 'application/json',
   };
 
-  const res = await fetch(url, {
-    method,
-    headers,
-    body: body != null ? JSON.stringify(body) : undefined,
-  });
+  const deadline = Date.now() + config.timeout * 1_000;
+  let backoff = INITIAL_BACKOFF_MS;
+  let attempt = 0;
+
+  while (true) {
+    attempt++;
+    const remaining = deadline - Date.now();
+    if (remaining <= 0) {
+      throw new RemoteTimeoutError(config.timeout);
+    }
+
+    // Per-request timeout: min of remaining budget and 60s
+    const perRequestTimeout = Math.min(remaining, 60_000);
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), perRequestTimeout);
 
-  if (!res.ok) {
-    let message: string;
     try {
-      const err = (await res.json()) as { detail?: string };
-      message = err.detail ?? res.statusText;
-    } catch {
-      message = res.statusText;
+      const res = await fetch(url, {
+        method,
+        headers,
+        body: body != null ? JSON.stringify(body) : undefined,
+        signal: controller.signal,
+      });
+
+      clearTimeout(timer);
+
+      if (!res.ok) {
+        let message: string;
+        try {
+          const err = (await res.json()) as { detail?: string };
+          message = err.detail ?? res.statusText;
+        } catch {
+          message = res.statusText;
+        }
+        const remoteErr = new RemoteError(res.status, message);
+
+        if (RETRYABLE_STATUS_CODES.has(res.status) && Date.now() + backoff < deadline) {
+          process.stderr.write(`  ⏳ Server not ready (${res.status}), retrying in ${Math.round(backoff / 1000)}s... (attempt ${attempt})\n`);
+          await sleep(backoff);
+          backoff = Math.min(backoff * 2, MAX_BACKOFF_MS);
+          continue;
+        }
+
+        throw remoteErr;
+      }
+
+      return (await res.json()) as T;
+    } catch (error) {
+      clearTimeout(timer);
+
+      if (error instanceof RemoteError || error instanceof RemoteTimeoutError) {
+        throw error;
+      }
+
+      // Retryable network/connection error
+      if (isRetryable(error) && Date.now() + backoff < deadline) {
+        process.stderr.write(`  ⏳ Cannot reach server, retrying in ${Math.round(backoff / 1000)}s... (attempt ${attempt})\n`);
+        await sleep(backoff);
+        backoff = Math.min(backoff * 2, MAX_BACKOFF_MS);
+        continue;
+      }
+
+      // AbortError from our own timeout
+      if ((error as Error).name === 'AbortError') {
+        if (Date.now() + backoff < deadline) {
+          process.stderr.write(`  ⏳ Request timed out, retrying in ${Math.round(backoff / 1000)}s... (attempt ${attempt})\n`);
+          await sleep(backoff);
+          backoff = Math.min(backoff * 2, MAX_BACKOFF_MS);
+          continue;
+        }
+        throw new RemoteTimeoutError(config.timeout);
+      }
+
+      throw error;
     }
-    throw new RemoteError(res.status, message);
   }
-
-  return (await res.json()) as T;
 }
 
 /** GET /cli/pull-docs */
@@ -89,11 +182,27 @@ export async function fetchPendingCRs(config: ApiClientConfig): Promise<RemoteCR
   return request<RemoteCRResponse[]>(config, 'GET', '/cli/pending-crs');
 }
 
+/** POST /cli/push-crs */
+export async function pushCRs(
+  config: ApiClientConfig,
+  changeRequests: Array<{ path: string; title: string; body: string; id?: string }>,
+): Promise<RemoteCRBulkResponse> {
+  return request<RemoteCRBulkResponse>(config, 'POST', '/cli/push-crs', { change_requests: changeRequests });
+}
+
 /** GET /cli/open-bugs */
 export async function fetchOpenBugs(config: ApiClientConfig): Promise<RemoteBugResponse[]> {
   return request<RemoteBugResponse[]>(config, 'GET', '/cli/open-bugs');
 }
 
+/** POST /cli/push-bugs */
+export async function pushBugs(
+  config: ApiClientConfig,
+  bugs: Array<{ path: string; title: string; body: string; severity?: string; id?: string }>,
+): Promise<RemoteBugBulkResponse> {
+  return request<RemoteBugBulkResponse>(config, 'POST', '/cli/push-bugs', { bugs });
+}
+
 /** POST /cli/crs/:crId/applied */
 export async function markCRAppliedRemote(
   config: ApiClientConfig,

package/src/remote/state.ts

@@ -10,7 +10,7 @@ function stateFilePath(root: string): string {
 }
 
 function emptyState(): RemoteState {
-  return { documents: {} };
+  return { documents: {}, changeRequests: {}, bugs: {} };
 }
 
 export async function readRemoteState(root: string): Promise<RemoteState> {

package/src/remote/sync-engine.ts

@@ -6,7 +6,9 @@ import matter from 'gray-matter';
 
 import { readConfig } from '../config/config-manager.js';
 import { parseAllStoryFiles } from '../parser/story-parser.js';
-import { buildApiConfig, pullDocs, pushDocs, fetchPendingCRs, fetchOpenBugs } from './api-client.js';
+import { parseAllCRFiles } from '../parser/cr-parser.js';
+import { parseAllBugFiles } from '../parser/bug-parser.js';
+import { buildApiConfig, pullDocs, pushDocs, pushCRs, pushBugs, fetchPendingCRs, fetchOpenBugs } from './api-client.js';
 import { readRemoteState, writeRemoteState } from './state.js';
 import type {
   PushResult,
@@ -71,12 +73,21 @@ function buildBugMarkdown(title: string, body: string, createdAt: string, status
 export interface PushOptions {
   paths?: string[];
   all?: boolean;
+  timeout?: number;
 }
 
 export async function pushToRemote(root: string, options?: PushOptions): Promise<PushResult> {
   const config = await readConfig(root);
-  const api = buildApiConfig(config);
+  const api = buildApiConfig(config, options?.timeout);
+  const state = await readRemoteState(root);
+  if (!state.changeRequests) state.changeRequests = {};
+  if (!state.bugs) state.bugs = {};
+
+  let totalCreated = 0;
+  let totalUpdated = 0;
+  const allPushed: string[] = [];
 
+  // ── Documents ──────────────────────────────────────────────────────────
   const files = await parseAllStoryFiles(root);
   const toPush = files.filter((f) => {
     if (options?.paths && options.paths.length > 0) return options.paths.includes(f.relativePath);
@@ -84,57 +95,141 @@ export async function pushToRemote(root: string, options?: PushOptions): Promise
     return f.frontmatter.status !== 'synced';
   });
 
-  if (toPush.length === 0) {
-    return { created: 0, updated: 0, pushed: [] };
+  if (toPush.length > 0) {
+    const documents = toPush.map((f) => ({
+      path: normalizePath(f.relativePath),
+      title: f.frontmatter.title,
+      content: f.body,
+    }));
+
+    const result = await pushDocs(api, documents);
+
+    for (const doc of result.documents) {
+      const localPath = doc.path;
+      const absPath = resolve(root, localPath);
+      const rawContent = existsSync(absPath) ? await readFile(absPath, 'utf-8') : '';
+      state.documents[localPath] = {
+        remoteId: doc.id,
+        remoteVersion: doc.version,
+        localHash: sha256(rawContent),
+        lastSynced: new Date().toISOString(),
+      };
+    }
+
+    // Mark local files as synced (drafts are excluded — they need AI enrichment first)
+    for (const f of toPush) {
+      if (f.frontmatter.status === 'draft') continue;
+      const absPath = resolve(root, f.relativePath);
+      const content = await readFile(absPath, 'utf-8');
+      const updated = content.replace(/^status:\s*(new|changed)/m, 'status: synced');
+      if (updated !== content) {
+        await writeFile(absPath, updated, 'utf-8');
+      }
+    }
+
+    totalCreated += result.created;
+    totalUpdated += result.updated;
+    allPushed.push(...toPush.map((f) => f.relativePath));
   }
 
-  const documents = toPush.map((f) => ({
-    path: normalizePath(f.relativePath),
-    title: f.frontmatter.title,
-    content: f.body,
-  }));
+  // ── Change Requests ────────────────────────────────────────────────────
+  const crFiles = await parseAllCRFiles(root);
+  const crsToPush = crFiles.filter((cr) => {
+    if (options?.paths && options.paths.length > 0) return options.paths.includes(cr.relativePath);
+    if (options?.all) return true;
+    return cr.frontmatter.status !== 'applied';
+  });
 
-  const result = await pushDocs(api, documents);
+  if (crsToPush.length > 0) {
+    const crPayload = crsToPush.map((cr) => {
+      const tracked = state.changeRequests![normalizePath(cr.relativePath)];
+      return {
+        path: normalizePath(cr.relativePath),
+        title: cr.frontmatter.title,
+        body: cr.body,
+        ...(tracked ? { id: tracked.remoteId } : {}),
+      };
+    });
+
+    const crResult = await pushCRs(api, crPayload);
+
+    for (const cr of crResult.change_requests) {
+      const localPath = crsToPush.find(
+        (f) => f.frontmatter.title === cr.title,
+      )?.relativePath;
+      if (localPath) {
+        const absPath = resolve(root, localPath);
+        const rawContent = existsSync(absPath) ? await readFile(absPath, 'utf-8') : '';
+        state.changeRequests![normalizePath(localPath)] = {
+          remoteId: cr.id,
+          localHash: sha256(rawContent),
+          lastSynced: new Date().toISOString(),
+        };
+      }
+    }
 
-  // Update remote state
-  const state = await readRemoteState(root);
-  for (const doc of result.documents) {
-    const localPath = doc.path;
-    const absPath = resolve(root, localPath);
-    const rawContent = existsSync(absPath) ? await readFile(absPath, 'utf-8') : '';
-    state.documents[localPath] = {
-      remoteId: doc.id,
-      remoteVersion: doc.version,
-      localHash: sha256(rawContent),
-      lastSynced: new Date().toISOString(),
-    };
+    totalCreated += crResult.created;
+    totalUpdated += crResult.updated;
+    allPushed.push(...crsToPush.map((cr) => cr.relativePath));
   }
-  state.lastPush = new Date().toISOString();
-  await writeRemoteState(root, state);
 
-  // Mark local files as synced (drafts are excluded — they need AI enrichment first)
-  for (const f of toPush) {
-    if (f.frontmatter.status === 'draft') continue;
-    const absPath = resolve(root, f.relativePath);
-    const content = await readFile(absPath, 'utf-8');
-    const updated = content.replace(/^status:\s*(new|changed)/m, 'status: synced');
-    if (updated !== content) {
-      await writeFile(absPath, updated, 'utf-8');
+  // ── Bugs ───────────────────────────────────────────────────────────────
+  const bugFiles = await parseAllBugFiles(root);
+  const bugsToPush = bugFiles.filter((bug) => {
+    if (options?.paths && options.paths.length > 0) return options.paths.includes(bug.relativePath);
+    if (options?.all) return true;
+    return bug.frontmatter.status !== 'resolved';
+  });
+
+  if (bugsToPush.length > 0) {
+    const bugPayload = bugsToPush.map((bug) => {
+      const tracked = state.bugs![normalizePath(bug.relativePath)];
+      return {
+        path: normalizePath(bug.relativePath),
+        title: bug.frontmatter.title,
+        body: bug.body,
+        ...(tracked ? { id: tracked.remoteId } : {}),
+      };
+    });
+
+    const bugResult = await pushBugs(api, bugPayload);
+
+    for (const bug of bugResult.bugs) {
+      const localPath = bugsToPush.find(
+        (b) => b.frontmatter.title === bug.title,
+      )?.relativePath;
+      if (localPath) {
+        const absPath = resolve(root, localPath);
+        const rawContent = existsSync(absPath) ? await readFile(absPath, 'utf-8') : '';
+        state.bugs![normalizePath(localPath)] = {
+          remoteId: bug.id,
+          localHash: sha256(rawContent),
+          lastSynced: new Date().toISOString(),
+        };
+      }
     }
+
+    totalCreated += bugResult.created;
+    totalUpdated += bugResult.updated;
+    allPushed.push(...bugsToPush.map((bug) => bug.relativePath));
   }
 
+  // ── Finalize ───────────────────────────────────────────────────────────
+  state.lastPush = new Date().toISOString();
+  await writeRemoteState(root, state);
+
   return {
-    created: result.created,
-    updated: result.updated,
-    pushed: toPush.map((f) => f.relativePath),
+    created: totalCreated,
+    updated: totalUpdated,
+    pushed: allPushed,
   };
 }
 
 // ─── Pull Documents ──────────────────────────────────────────────────────
 
-export async function pullFromRemote(root: string): Promise<PullResult> {
+export async function pullFromRemote(root: string, timeout?: number): Promise<PullResult> {
   const config = await readConfig(root);
-  const api = buildApiConfig(config);
+  const api = buildApiConfig(config, timeout);
 
   const remoteDocs = await pullDocs(api);
   const state = await readRemoteState(root);
@@ -206,9 +301,9 @@ function updateDocState(
 
 // ─── Pull CRs ────────────────────────────────────────────────────────────
 
-export async function pullCRsFromRemote(root: string): Promise<PullEntitiesResult> {
+export async function pullCRsFromRemote(root: string, timeout?: number): Promise<PullEntitiesResult> {
   const config = await readConfig(root);
-  const api = buildApiConfig(config);
+  const api = buildApiConfig(config, timeout);
 
   const remoteCRs = await fetchPendingCRs(api);
   const crDir = resolve(root, 'change-requests');
@@ -238,9 +333,9 @@ export async function pullCRsFromRemote(root: string): Promise<PullEntitiesResul
 
 // ─── Pull Bugs ───────────────────────────────────────────────────────────
 
-export async function pullBugsFromRemote(root: string): Promise<PullEntitiesResult> {
+export async function pullBugsFromRemote(root: string, timeout?: number): Promise<PullEntitiesResult> {
   const config = await readConfig(root);
-  const api = buildApiConfig(config);
+  const api = buildApiConfig(config, timeout);
 
   const remoteBugs = await fetchOpenBugs(api);
   const bugsDir = resolve(root, 'bugs');
@@ -270,7 +365,7 @@ export async function pullBugsFromRemote(root: string): Promise<PullEntitiesResu
 
 // ─── Remote Status ───────────────────────────────────────────────────────
 
-export async function getRemoteStatus(root: string): Promise<RemoteStatusResult> {
+export async function getRemoteStatus(root: string, timeout?: number): Promise<RemoteStatusResult> {
   const config = await readConfig(root);
 
   if (!config.remote?.url) {
@@ -281,7 +376,7 @@ export async function getRemoteStatus(root: string): Promise<RemoteStatusResult>
   const localPending = files.filter((f) => f.frontmatter.status !== 'synced').length;
 
   try {
-    const api = buildApiConfig(config);
+    const api = buildApiConfig(config, timeout);
     const docs = await pullDocs(api);
     return {
       configured: true,

package/src/remote/types.ts

@@ -49,6 +49,20 @@ export interface RemoteBugResponse {
   updated_at: string;
 }
 
+/** Bulk push response from POST /cli/push-crs */
+export interface RemoteCRBulkResponse {
+  created: number;
+  updated: number;
+  change_requests: RemoteCRResponse[];
+}
+
+/** Bulk push response from POST /cli/push-bugs */
+export interface RemoteBugBulkResponse {
+  created: number;
+  updated: number;
+  bugs: RemoteBugResponse[];
+}
+
 /** Tracks per-document remote sync state */
 export interface RemoteDocState {
   remoteId: string;
@@ -57,11 +71,20 @@ export interface RemoteDocState {
   lastSynced: string;
 }
 
+/** Tracks per-entity remote sync state (CRs, bugs) */
+export interface RemoteEntityState {
+  remoteId: string;
+  localHash: string;
+  lastSynced: string;
+}
+
 /** Persisted to .sdd/remote-state.json */
 export interface RemoteState {
   lastPull?: string;
   lastPush?: string;
   documents: Record<string, RemoteDocState>;
+  changeRequests?: Record<string, RemoteEntityState>;
+  bugs?: Record<string, RemoteEntityState>;
 }
 
 /** Result of a push operation */

package/src/sdd.ts

@@ -254,29 +254,29 @@ export class SDD {
 
   // ── Remote sync ──────────────────────────────────────────────────────
 
-  async remoteStatus(): Promise<RemoteStatusResult> {
+  async remoteStatus(timeout?: number): Promise<RemoteStatusResult> {
     this.ensureInitialized();
-    return getRemoteStatus(this.root);
+    return getRemoteStatus(this.root, timeout);
   }
 
-  async push(paths?: string[], options?: { all?: boolean }): Promise<PushResult> {
+  async push(paths?: string[], options?: { all?: boolean; timeout?: number }): Promise<PushResult> {
     this.ensureInitialized();
-    return pushToRemote(this.root, { paths, all: options?.all });
+    return pushToRemote(this.root, { paths, all: options?.all, timeout: options?.timeout });
   }
 
-  async pull(): Promise<PullResult> {
+  async pull(timeout?: number): Promise<PullResult> {
     this.ensureInitialized();
-    return pullFromRemote(this.root);
+    return pullFromRemote(this.root, timeout);
   }
 
-  async pullCRs(): Promise<PullEntitiesResult> {
+  async pullCRs(timeout?: number): Promise<PullEntitiesResult> {
     this.ensureInitialized();
-    return pullCRsFromRemote(this.root);
+    return pullCRsFromRemote(this.root, timeout);
   }
 
-  async pullBugs(): Promise<PullEntitiesResult> {
+  async pullBugs(timeout?: number): Promise<PullEntitiesResult> {
     this.ensureInitialized();
-    return pullBugsFromRemote(this.root);
+    return pullBugsFromRemote(this.root, timeout);
   }
 
   private ensureInitialized(): void {

package/src/types.ts

@@ -58,6 +58,7 @@ export interface StoryStatus {
 export interface RemoteConfig {
   url: string;
   'api-key'?: string;
+  timeout?: number;
 }
 
 export interface SDDConfig {