@applica-software-guru/sdd-core 1.3.4 → 1.4.0

package/src/remote/sync-engine.ts

@@ -0,0 +1,296 @@
+import { readFile, writeFile, mkdir } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { resolve, dirname, posix } from 'node:path';
+import { createHash } from 'node:crypto';
+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 { readRemoteState, writeRemoteState } from './state.js';
+import type {
+  PushResult,
+  PullResult,
+  PullConflict,
+  PullEntitiesResult,
+  RemoteStatusResult,
+  RemoteDocResponse,
+} from './types.js';
+
+function sha256(content: string): string {
+  return createHash('sha256').update(content, 'utf-8').digest('hex');
+}
+
+/** Normalize path separators to forward slash for remote consistency */
+function normalizePath(p: string): string {
+  return p.split('\\').join('/');
+}
+
+/**
+ * Build a markdown file with frontmatter for a pulled document.
+ */
+function buildStoryMarkdown(title: string, body: string, version: number, status: string = 'synced'): string {
+  const fm = {
+    title,
+    status,
+    author: 'remote',
+    'last-modified': new Date().toISOString(),
+    version: `${version}.0`,
+  };
+  return matter.stringify(body, fm);
+}
+
+/**
+ * Build a markdown file for a pulled change request.
+ */
+function buildCRMarkdown(title: string, body: string, createdAt: string, status: string = 'draft'): string {
+  const fm = {
+    title,
+    status,
+    author: 'remote',
+    'created-at': createdAt,
+  };
+  return matter.stringify(body, fm);
+}
+
+/**
+ * Build a markdown file for a pulled bug.
+ */
+function buildBugMarkdown(title: string, body: string, createdAt: string, status: string = 'open'): string {
+  const fm = {
+    title,
+    status,
+    author: 'remote',
+    'created-at': createdAt,
+  };
+  return matter.stringify(body, fm);
+}
+
+// ─── Push ────────────────────────────────────────────────────────────────
+
+export async function pushToRemote(root: string, paths?: string[]): Promise<PushResult> {
+  const config = await readConfig(root);
+  const api = buildApiConfig(config);
+
+  const files = await parseAllStoryFiles(root);
+  const toPush = files.filter((f) => {
+    if (paths && paths.length > 0) return paths.includes(f.relativePath);
+    return f.frontmatter.status !== 'synced';
+  });
+
+  if (toPush.length === 0) {
+    return { created: 0, updated: 0, pushed: [] };
+  }
+
+  const documents = toPush.map((f) => ({
+    path: normalizePath(f.relativePath),
+    title: f.frontmatter.title,
+    content: f.body,
+  }));
+
+  const result = await pushDocs(api, documents);
+
+  // 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(),
+    };
+  }
+  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');
+    }
+  }
+
+  return {
+    created: result.created,
+    updated: result.updated,
+    pushed: toPush.map((f) => f.relativePath),
+  };
+}
+
+// ─── Pull Documents ──────────────────────────────────────────────────────
+
+export async function pullFromRemote(root: string): Promise<PullResult> {
+  const config = await readConfig(root);
+  const api = buildApiConfig(config);
+
+  const remoteDocs = await pullDocs(api);
+  const state = await readRemoteState(root);
+
+  const created: string[] = [];
+  const updated: string[] = [];
+  const conflicts: PullConflict[] = [];
+
+  for (const doc of remoteDocs) {
+    const localPath = doc.path;
+    const absPath = resolve(root, localPath);
+    const tracked = state.documents[localPath];
+
+    if (!existsSync(absPath)) {
+      // New file — create locally, preserving remote status
+      const dir = dirname(absPath);
+      if (!existsSync(dir)) {
+        await mkdir(dir, { recursive: true });
+      }
+      const localStatus = doc.status === 'draft' ? 'draft' : 'synced';
+      const markdown = buildStoryMarkdown(doc.title, doc.content, doc.version, localStatus);
+      await writeFile(absPath, markdown, 'utf-8');
+      created.push(localPath);
+      updateDocState(state, doc, localPath, markdown);
+    } else if (!tracked || doc.version > tracked.remoteVersion) {
+      // Remote is newer — check for local changes
+      const localContent = await readFile(absPath, 'utf-8');
+      const localHash = sha256(localContent);
+
+      if (tracked && localHash !== tracked.localHash) {
+        // Local file changed since last sync AND remote changed → conflict
+        conflicts.push({
+          path: localPath,
+          localVersion: tracked.remoteVersion.toString(),
+          remoteVersion: doc.version,
+          reason: 'Both local and remote have changes since last sync',
+        });
+      } else {
+        // Local unchanged — safe to overwrite
+        const localStatus = doc.status === 'draft' ? 'draft' : 'synced';
+        const markdown = buildStoryMarkdown(doc.title, doc.content, doc.version, localStatus);
+        await writeFile(absPath, markdown, 'utf-8');
+        updated.push(localPath);
+        updateDocState(state, doc, localPath, markdown);
+      }
+    }
+    // If versions match, skip
+  }
+
+  state.lastPull = new Date().toISOString();
+  await writeRemoteState(root, state);
+
+  return { created, updated, conflicts };
+}
+
+function updateDocState(
+  state: { documents: Record<string, { remoteId: string; remoteVersion: number; localHash: string; lastSynced: string }> },
+  doc: RemoteDocResponse,
+  localPath: string,
+  markdownContent: string,
+): void {
+  state.documents[localPath] = {
+    remoteId: doc.id,
+    remoteVersion: doc.version,
+    localHash: sha256(markdownContent),
+    lastSynced: new Date().toISOString(),
+  };
+}
+
+// ─── Pull CRs ────────────────────────────────────────────────────────────
+
+export async function pullCRsFromRemote(root: string): Promise<PullEntitiesResult> {
+  const config = await readConfig(root);
+  const api = buildApiConfig(config);
+
+  const remoteCRs = await fetchPendingCRs(api);
+  const crDir = resolve(root, 'change-requests');
+  if (!existsSync(crDir)) {
+    await mkdir(crDir, { recursive: true });
+  }
+
+  let created = 0;
+  let updated = 0;
+
+  for (const cr of remoteCRs) {
+    const filename = `CR-${cr.id.substring(0, 8)}.md`;
+    const absPath = resolve(crDir, filename);
+    const crStatus = cr.status === 'draft' ? 'draft' : 'pending';
+    const markdown = buildCRMarkdown(cr.title, cr.body, cr.created_at, crStatus);
+
+    if (existsSync(absPath)) {
+      updated++;
+    } else {
+      created++;
+    }
+    await writeFile(absPath, markdown, 'utf-8');
+  }
+
+  return { created, updated };
+}
+
+// ─── Pull Bugs ───────────────────────────────────────────────────────────
+
+export async function pullBugsFromRemote(root: string): Promise<PullEntitiesResult> {
+  const config = await readConfig(root);
+  const api = buildApiConfig(config);
+
+  const remoteBugs = await fetchOpenBugs(api);
+  const bugsDir = resolve(root, 'bugs');
+  if (!existsSync(bugsDir)) {
+    await mkdir(bugsDir, { recursive: true });
+  }
+
+  let created = 0;
+  let updated = 0;
+
+  for (const bug of remoteBugs) {
+    const filename = `BUG-${bug.id.substring(0, 8)}.md`;
+    const absPath = resolve(bugsDir, filename);
+    const bugStatus = bug.status === 'draft' ? 'draft' : 'open';
+    const markdown = buildBugMarkdown(bug.title, bug.body, bug.created_at, bugStatus);
+
+    if (existsSync(absPath)) {
+      updated++;
+    } else {
+      created++;
+    }
+    await writeFile(absPath, markdown, 'utf-8');
+  }
+
+  return { created, updated };
+}
+
+// ─── Remote Status ───────────────────────────────────────────────────────
+
+export async function getRemoteStatus(root: string): Promise<RemoteStatusResult> {
+  const config = await readConfig(root);
+
+  if (!config.remote?.url) {
+    return { configured: false, url: null, connected: false, localPending: 0, remoteDocs: 0 };
+  }
+
+  const files = await parseAllStoryFiles(root);
+  const localPending = files.filter((f) => f.frontmatter.status !== 'synced').length;
+
+  try {
+    const api = buildApiConfig(config);
+    const docs = await pullDocs(api);
+    return {
+      configured: true,
+      url: config.remote.url,
+      connected: true,
+      localPending,
+      remoteDocs: docs.length,
+    };
+  } catch {
+    return {
+      configured: true,
+      url: config.remote.url,
+      connected: false,
+      localPending,
+      remoteDocs: 0,
+    };
+  }
+}

package/src/remote/types.ts

@@ -0,0 +1,102 @@
+/** Mirrors the sdd-flow API response for documents */
+export interface RemoteDocResponse {
+  id: string;
+  project_id: string;
+  path: string;
+  title: string;
+  status: string;
+  version: number;
+  content: string;
+  last_modified_by: string | null;
+  created_at: string;
+  updated_at: string;
+}
+
+/** Bulk push response from POST /cli/push-docs */
+export interface RemoteDocBulkResponse {
+  created: number;
+  updated: number;
+  documents: RemoteDocResponse[];
+}
+
+/** Mirrors the sdd-flow API response for change requests */
+export interface RemoteCRResponse {
+  id: string;
+  project_id: string;
+  title: string;
+  body: string;
+  status: string;
+  author_id: string;
+  assignee_id: string | null;
+  target_files: string[] | null;
+  closed_at: string | null;
+  created_at: string;
+  updated_at: string;
+}
+
+/** Mirrors the sdd-flow API response for bugs */
+export interface RemoteBugResponse {
+  id: string;
+  project_id: string;
+  title: string;
+  body: string;
+  status: string;
+  severity: string;
+  author_id: string;
+  assignee_id: string | null;
+  closed_at: string | null;
+  created_at: string;
+  updated_at: string;
+}
+
+/** Tracks per-document remote sync state */
+export interface RemoteDocState {
+  remoteId: string;
+  remoteVersion: number;
+  localHash: string;
+  lastSynced: string;
+}
+
+/** Persisted to .sdd/remote-state.json */
+export interface RemoteState {
+  lastPull?: string;
+  lastPush?: string;
+  documents: Record<string, RemoteDocState>;
+}
+
+/** Result of a push operation */
+export interface PushResult {
+  created: number;
+  updated: number;
+  pushed: string[];
+}
+
+/** A conflict detected during pull */
+export interface PullConflict {
+  path: string;
+  localVersion: string;
+  remoteVersion: number;
+  reason: string;
+}
+
+/** Result of a pull operation */
+export interface PullResult {
+  created: string[];
+  updated: string[];
+  conflicts: PullConflict[];
+}
+
+/** Result of a pull CRs/Bugs operation */
+export interface PullEntitiesResult {
+  created: number;
+  updated: number;
+}
+
+/** Result of remote status check */
+export interface RemoteStatusResult {
+  configured: boolean;
+  url: string | null;
+  connected: boolean;
+  localPending: number;
+  remoteDocs: number;
+}

package/src/sdd.ts

@@ -5,6 +5,7 @@ import { ProjectNotInitializedError } from "./errors.js";
 import { parseAllStoryFiles } from "./parser/story-parser.js";
 import { generatePrompt } from "./prompt/prompt-generator.js";
 import { generateApplyPrompt } from "./prompt/apply-prompt-generator.js";
+import { generateDraftEnrichmentPrompt } from "./prompt/draft-prompt-generator.js";
 import { validate } from "./validate/validator.js";
 import { initProject } from "./scaffold/init.js";
 import { isSDDProject, readConfig, writeConfig } from "./config/config-manager.js";
@@ -17,6 +18,14 @@ import {
   type SyncAdaptersOptions,
   type SyncAdaptersResult,
 } from "./scaffold/skill-adapters.js";
+import {
+  pushToRemote,
+  pullFromRemote,
+  pullCRsFromRemote,
+  pullBugsFromRemote,
+  getRemoteStatus,
+} from "./remote/sync-engine.js";
+import type { PushResult, PullResult, PullEntitiesResult, RemoteStatusResult } from "./remote/types.js";
 
 export class SDD {
   private root: string;
@@ -60,7 +69,7 @@ export class SDD {
   async pending(): Promise<import("./types.js").StoryFile[]> {
     this.ensureInitialized();
     const files = await parseAllStoryFiles(this.root);
-    return files.filter((f) => f.frontmatter.status !== "synced");
+    return files.filter((f) => f.frontmatter.status !== "synced" && f.frontmatter.status !== "draft");
   }
 
   async sync(): Promise<string> {
@@ -70,12 +79,16 @@ export class SDD {
 
   async applyPrompt(): Promise<string | null> {
     this.ensureInitialized();
-    const [bugs, changeRequests, pendingFiles] = await Promise.all([
+    const [bugs, changeRequests, pendingFiles, drafts, allFiles, config] = await Promise.all([
       this.openBugs(),
       this.pendingChangeRequests(),
       this.pending(),
+      this.drafts(),
+      parseAllStoryFiles(this.root),
+      readConfig(this.root),
     ]);
-    return generateApplyPrompt(bugs, changeRequests, pendingFiles, this.root);
+    const projectContext = allFiles.filter((f) => f.frontmatter.status !== "draft");
+    return generateApplyPrompt(bugs, changeRequests, pendingFiles, this.root, drafts, projectContext, config.description);
   }
 
   async validate(): Promise<ValidationResult> {
@@ -120,7 +133,7 @@ export class SDD {
 
   async pendingChangeRequests(): Promise<ChangeRequest[]> {
     const all = await this.changeRequests();
-    return all.filter((cr) => cr.frontmatter.status === "draft");
+    return all.filter((cr) => cr.frontmatter.status === "pending");
   }
 
   async markCRApplied(paths?: string[]): Promise<string[]> {
@@ -129,12 +142,12 @@ export class SDD {
     const marked: string[] = [];
 
     for (const cr of all) {
-      if (cr.frontmatter.status === "applied") continue;
+      if (cr.frontmatter.status !== "pending") continue;
       if (paths && paths.length > 0 && !paths.includes(cr.relativePath)) continue;
 
       const absPath = resolve(this.root, cr.relativePath);
       const content = await readFile(absPath, "utf-8");
-      const updated = content.replace(/^status:\s*draft/m, "status: applied");
+      const updated = content.replace(/^status:\s*pending/m, "status: applied");
       await writeFile(absPath, updated, "utf-8");
       marked.push(cr.relativePath);
     }
@@ -171,6 +184,101 @@ export class SDD {
     return marked;
   }
 
+  // ── Drafts ───────────────────────────────────────────────────────────
+
+  async drafts(): Promise<{ docs: import("./types.js").StoryFile[]; crs: ChangeRequest[]; bugs: Bug[] }> {
+    this.ensureInitialized();
+    const [files, crs, bugs] = await Promise.all([
+      parseAllStoryFiles(this.root),
+      this.changeRequests(),
+      this.bugs(),
+    ]);
+    return {
+      docs: files.filter((f) => f.frontmatter.status === "draft"),
+      crs: crs.filter((cr) => cr.frontmatter.status === "draft"),
+      bugs: bugs.filter((b) => b.frontmatter.status === "draft"),
+    };
+  }
+
+  async draftEnrichmentPrompt(): Promise<string | null> {
+    this.ensureInitialized();
+    const drafts = await this.drafts();
+    const allFiles = await parseAllStoryFiles(this.root);
+    const projectContext = allFiles.filter((f) => f.frontmatter.status !== "draft");
+    const config = await readConfig(this.root);
+    return generateDraftEnrichmentPrompt(drafts, projectContext, config.description);
+  }
+
+  async markDraftsEnriched(paths?: string[]): Promise<string[]> {
+    this.ensureInitialized();
+    const marked: string[] = [];
+
+    // Story files: draft → new
+    const files = await parseAllStoryFiles(this.root);
+    for (const file of files) {
+      if (file.frontmatter.status !== "draft") continue;
+      if (paths && paths.length > 0 && !paths.includes(file.relativePath)) continue;
+      const absPath = resolve(this.root, file.relativePath);
+      const content = await readFile(absPath, "utf-8");
+      const updated = content.replace(/^status:\s*draft/m, "status: new");
+      await writeFile(absPath, updated, "utf-8");
+      marked.push(file.relativePath);
+    }
+
+    // CRs: draft → pending
+    const crs = await this.changeRequests();
+    for (const cr of crs) {
+      if (cr.frontmatter.status !== "draft") continue;
+      if (paths && paths.length > 0 && !paths.includes(cr.relativePath)) continue;
+      const absPath = resolve(this.root, cr.relativePath);
+      const content = await readFile(absPath, "utf-8");
+      const updated = content.replace(/^status:\s*draft/m, "status: pending");
+      await writeFile(absPath, updated, "utf-8");
+      marked.push(cr.relativePath);
+    }
+
+    // Bugs: draft → open
+    const allBugs = await this.bugs();
+    for (const bug of allBugs) {
+      if (bug.frontmatter.status !== "draft") continue;
+      if (paths && paths.length > 0 && !paths.includes(bug.relativePath)) continue;
+      const absPath = resolve(this.root, bug.relativePath);
+      const content = await readFile(absPath, "utf-8");
+      const updated = content.replace(/^status:\s*draft/m, "status: open");
+      await writeFile(absPath, updated, "utf-8");
+      marked.push(bug.relativePath);
+    }
+
+    return marked;
+  }
+
+  // ── Remote sync ──────────────────────────────────────────────────────
+
+  async remoteStatus(): Promise<RemoteStatusResult> {
+    this.ensureInitialized();
+    return getRemoteStatus(this.root);
+  }
+
+  async push(paths?: string[]): Promise<PushResult> {
+    this.ensureInitialized();
+    return pushToRemote(this.root, paths);
+  }
+
+  async pull(): Promise<PullResult> {
+    this.ensureInitialized();
+    return pullFromRemote(this.root);
+  }
+
+  async pullCRs(): Promise<PullEntitiesResult> {
+    this.ensureInitialized();
+    return pullCRsFromRemote(this.root);
+  }
+
+  async pullBugs(): Promise<PullEntitiesResult> {
+    this.ensureInitialized();
+    return pullBugsFromRemote(this.root);
+  }
+
   private ensureInitialized(): void {
     if (!isSDDProject(this.root)) {
       throw new ProjectNotInitializedError(this.root);

package/src/types.ts

@@ -1,4 +1,4 @@
-export type StoryFileStatus = 'new' | 'changed' | 'deleted' | 'synced';
+export type StoryFileStatus = 'draft' | 'new' | 'changed' | 'deleted' | 'synced';
 
 export interface StoryFrontmatter {
   title: string;
@@ -49,20 +49,26 @@ export interface ValidationIssue {
 export interface StoryStatus {
   files: Array<{
     relativePath: string;
-    status: 'new' | 'changed' | 'deleted' | 'synced';
+    status: StoryFileStatus;
     version: string;
     lastModified: string;
   }>;
 }
 
+export interface RemoteConfig {
+  url: string;
+  'api-key'?: string;
+}
+
 export interface SDDConfig {
   description: string;
   'last-sync-commit'?: string;
   agent?: string;
   agents?: Record<string, string>;
+  remote?: RemoteConfig;
 }
 
-export type ChangeRequestStatus = 'draft' | 'applied';
+export type ChangeRequestStatus = 'draft' | 'pending' | 'applied';
 
 export interface ChangeRequestFrontmatter {
   title: string;
@@ -77,7 +83,7 @@ export interface ChangeRequest {
   body: string;
 }
 
-export type BugStatus = 'open' | 'resolved';
+export type BugStatus = 'draft' | 'open' | 'resolved';
 
 export interface BugFrontmatter {
   title: string;