@applica-software-guru/sdd-core 1.8.2 → 1.8.3

package/src/git/git.ts

@@ -85,6 +85,67 @@ export function getGitModifiedFiles(root: string): Set<string> {
   return modified;
 }
 
+export function getCurrentBranch(root: string): string | null {
+  try {
+    return run('git rev-parse --abbrev-ref HEAD', root) || null;
+  } catch {
+    return null;
+  }
+}
+
+export function checkoutBranch(root: string, branch: string): void {
+  try {
+    run(`git checkout ${branch}`, root);
+  } catch {
+    // branch doesn't exist — create it
+    run(`git checkout -b ${branch}`, root);
+  }
+}
+
+export function getJobChangedFiles(
+  root: string,
+  fromCommit: string | null,
+): Array<{ path: string; status: 'new' | 'modified' | 'deleted' }> {
+  const result = new Map<string, 'new' | 'modified' | 'deleted'>();
+
+  try {
+    // Committed changes since the base commit
+    if (fromCommit) {
+      const committed = run(`git diff --name-status ${fromCommit} HEAD`, root);
+      for (const line of committed.split('\n').filter(Boolean)) {
+        const parts = line.split('\t');
+        const flag = parts[0][0]; // first char (A/M/D/R/C)
+        // Renames have two paths: old\tnew — use the new path
+        const path = parts.length >= 3 ? parts[2] : parts[1];
+        const fileStatus: 'new' | 'modified' | 'deleted' =
+          flag === 'A' ? 'new' : flag === 'D' ? 'deleted' : 'modified';
+        result.set(path, fileStatus);
+      }
+    }
+
+    // Uncommitted working tree changes (staged + unstaged + untracked)
+    const porcelain = run('git status --porcelain', root);
+    for (const line of porcelain.split('\n').filter(Boolean)) {
+      const xy = line.substring(0, 2);
+      const rawPath = line.substring(3).trim();
+      // Renamed files show as "old -> new" in porcelain v1
+      const path = rawPath.includes(' -> ') ? rawPath.split(' -> ')[1] : rawPath;
+
+      if (xy[0] === 'D' || xy[1] === 'D') {
+        result.set(path, 'deleted');
+      } else if (xy === '??' || xy[0] === 'A' || xy[1] === 'A') {
+        if (!result.has(path)) result.set(path, 'new');
+      } else {
+        if (!result.has(path)) result.set(path, 'modified');
+      }
+    }
+  } catch {
+    // not a git repo or no commits — return empty
+  }
+
+  return Array.from(result.entries()).map(([path, status]) => ({ path, status }));
+}
+
 export function getChangedFiles(root: string, fromCommit: string | null): Array<{ path: string; status: 'new' | 'modified' | 'deleted' }> {
   try {
     if (!fromCommit) {

package/src/index.ts

@@ -21,8 +21,11 @@ export type {
 export { SDDError, LockFileNotFoundError, ParseError, ProjectNotInitializedError, RemoteError, RemoteNotConfiguredError, RemoteTimeoutError } from "./errors.js";
 export type { ProjectInfo } from "./scaffold/templates.js";
 export { isSDDProject, readConfig, writeConfig } from "./config/config-manager.js";
-export { runAgent } from "./agent/agent-runner.js";
-export type { AgentRunnerOptions } from "./agent/agent-runner.js";
+export { getCurrentBranch, checkoutBranch } from "./git/git.js";
+export { runAgent, startAgent } from "./agent/agent-runner.js";
+export type { AgentRunnerOptions, AgentRunnerHandle } from "./agent/agent-runner.js";
+export { startWorkerDaemon } from "./agent/worker-daemon.js";
+export type { WorkerDaemonOptions } from "./agent/worker-daemon.js";
 export { DEFAULT_AGENTS, resolveAgentCommand } from "./agent/agent-defaults.js";
 export { listSupportedAdapters, SKILL_ADAPTERS, syncSkillAdapters } from "./scaffold/skill-adapters.js";
 export type {
@@ -39,6 +42,8 @@ export { generateDraftEnrichmentPrompt } from "./prompt/draft-prompt-generator.j
 export type { DraftElements } from "./prompt/draft-prompt-generator.js";
 export { resolveApiKey, buildApiConfig, pullDocs, pushDocs, pullPendingCRs, pullOpenBugs, markCRAppliedRemote, markBugResolvedRemote, markDocEnriched, markCREnriched, markBugEnriched, resetProject, DEFAULT_REMOTE_TIMEOUT } from "./remote/api-client.js";
 export type { ApiClientConfig } from "./remote/api-client.js";
+export { registerWorker, workerHeartbeat, workerPoll, workerJobStarted, workerJobOutput, workerJobQuestion, workerJobAnswers, workerJobCompleted } from "./remote/worker-client.js";
+export type { WorkerRegistration, WorkerJobAssignment, WorkerJobAnswer, WorkerState } from "./remote/worker-types.js";
 export { readRemoteState, writeRemoteState } from "./remote/state.js";
 export { pushToRemote, pullFromRemote, pullCRsFromRemote, pullBugsFromRemote, getRemoteStatus, resetRemoteProject } from "./remote/sync-engine.js";
 export type {

package/src/prompt/draft-prompt-generator.ts

@@ -50,5 +50,13 @@ export function generateDraftEnrichmentPrompt(
     sections.push('');
   }
 
+  sections.push(
+    '## Report\n',
+    'At the end of the enrichment, provide a detailed report including:\n' +
+    '- List of enriched files (documents, CRs, bugs)\n' +
+    '- For each file: what was added or completed\n' +
+    '- Any ambiguities resolved or assumptions made'
+  );
+
   return sections.join('\n');
 }

package/src/prompt/prompt-generator.ts

@@ -35,5 +35,13 @@ export function generatePrompt(files: StoryFile[], root?: string): string {
     sections.push(delLines.join('\n'));
   }
 
+  sections.push(
+    '## Report\n\n' +
+    'At the end of your work, provide a detailed report including:\n' +
+    '- List of files created, modified, or deleted\n' +
+    '- Description of actions taken for each file\n' +
+    '- Any issues encountered or decisions made'
+  );
+
   return sections.join('\n\n');
 }

package/src/remote/sync-engine.ts

@@ -139,6 +139,7 @@ export async function pushToRemote(root: string, options?: PushOptions): Promise
       path: normalizePath(f.relativePath),
       title: f.frontmatter.title,
       content: f.body,
+      status: f.frontmatter.status,
     }));
 
     const result = await pushDocs(api, documents);

package/src/remote/worker-client.ts

@@ -0,0 +1,141 @@
+import type { ApiClientConfig } from './api-client.js';
+import type { WorkerRegistration, WorkerJobAssignment, WorkerJobAnswer } from './worker-types.js';
+
+/**
+ * Low-level fetch wrapper for worker endpoints.
+ * Unlike the main api-client, worker requests have different timeout needs
+ * (e.g. long-poll uses 35s timeout) and don't need full retry logic.
+ */
+async function workerRequest<T>(
+  config: ApiClientConfig,
+  method: string,
+  path: string,
+  body?: unknown,
+  timeoutMs?: number,
+): Promise<T> {
+  const url = `${config.baseUrl}${path}`;
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs ?? 10_000);
+
+  try {
+    const res = await fetch(url, {
+      method,
+      headers: {
+        Authorization: `Bearer ${config.apiKey}`,
+        'Content-Type': 'application/json',
+      },
+      body: body != null ? JSON.stringify(body) : undefined,
+      signal: controller.signal,
+    });
+    clearTimeout(timer);
+
+    if (!res.ok) {
+      let detail: string;
+      try {
+        const err = (await res.json()) as { detail?: string };
+        detail = err.detail ?? res.statusText;
+      } catch {
+        detail = res.statusText;
+      }
+      throw new Error(`Worker API error ${res.status}: ${detail}`);
+    }
+
+    // 204 No Content (poll with no job)
+    if (res.status === 204) {
+      return null as T;
+    }
+
+    return (await res.json()) as T;
+  } catch (error) {
+    clearTimeout(timer);
+    throw error;
+  }
+}
+
+/** POST /cli/workers/register */
+export async function registerWorker(
+  config: ApiClientConfig,
+  name: string,
+  agent: string,
+  branch?: string,
+  metadata?: Record<string, unknown>,
+): Promise<WorkerRegistration> {
+  return workerRequest<WorkerRegistration>(
+    config, 'POST', '/cli/workers/register',
+    { name, agent, branch, metadata },
+  );
+}
+
+/** POST /cli/workers/:workerId/heartbeat */
+export async function workerHeartbeat(
+  config: ApiClientConfig,
+  workerId: string,
+  workerStatus: 'online' | 'busy' = 'online',
+): Promise<void> {
+  await workerRequest(
+    config, 'POST', `/cli/workers/${workerId}/heartbeat`,
+    { status: workerStatus },
+  );
+}
+
+/** GET /cli/workers/:workerId/poll — long-poll (up to 35s timeout) */
+export async function workerPoll(
+  config: ApiClientConfig,
+  workerId: string,
+): Promise<WorkerJobAssignment | null> {
+  return workerRequest<WorkerJobAssignment | null>(
+    config, 'GET', `/cli/workers/${workerId}/poll`,
+    undefined,
+    35_000, // 35s to exceed server's 30s hold time
+  );
+}
+
+/** POST /cli/workers/jobs/:jobId/started */
+export async function workerJobStarted(
+  config: ApiClientConfig,
+  jobId: string,
+): Promise<void> {
+  await workerRequest(config, 'POST', `/cli/workers/jobs/${jobId}/started`);
+}
+
+/** POST /cli/workers/jobs/:jobId/output */
+export async function workerJobOutput(
+  config: ApiClientConfig,
+  jobId: string,
+  lines: string[],
+): Promise<void> {
+  await workerRequest(config, 'POST', `/cli/workers/jobs/${jobId}/output`, { lines });
+}
+
+/** POST /cli/workers/jobs/:jobId/question */
+export async function workerJobQuestion(
+  config: ApiClientConfig,
+  jobId: string,
+  content: string,
+): Promise<void> {
+  await workerRequest(config, 'POST', `/cli/workers/jobs/${jobId}/question`, { content });
+}
+
+/** GET /cli/workers/jobs/:jobId/answers?after_sequence=N */
+export async function workerJobAnswers(
+  config: ApiClientConfig,
+  jobId: string,
+  afterSequence: number = 0,
+): Promise<WorkerJobAnswer[]> {
+  return workerRequest<WorkerJobAnswer[]>(
+    config, 'GET', `/cli/workers/jobs/${jobId}/answers?after_sequence=${afterSequence}`,
+  );
+}
+
+/** POST /cli/workers/jobs/:jobId/completed */
+export async function workerJobCompleted(
+  config: ApiClientConfig,
+  jobId: string,
+  exitCode: number,
+  changedFiles?: Array<{ path: string; status: 'new' | 'modified' | 'deleted' }>,
+): Promise<void> {
+  await workerRequest(config, 'POST', `/cli/workers/jobs/${jobId}/completed`, {
+    exit_code: exitCode,
+    changed_files: changedFiles ?? [],
+  });
+}

package/src/remote/worker-types.ts

@@ -0,0 +1,40 @@
+/** Worker registration response from the server */
+export interface WorkerRegistration {
+  id: string;
+  project_id: string;
+  name: string;
+  status: string;
+  agent: string;
+  branch?: string;
+  last_heartbeat_at: string | null;
+  registered_at: string;
+  is_online: boolean;
+}
+
+/** Job assignment returned by the poll endpoint */
+export interface WorkerJobAssignment {
+  job_id: string;
+  entity_type: string | null;
+  entity_id: string | null;
+  prompt: string;
+  agent: string;
+  model?: string;
+  branch?: string;
+}
+
+/** Answer message from the user */
+export interface WorkerJobAnswer {
+  id: string;
+  job_id: string;
+  kind: 'answer';
+  content: string;
+  sequence: number;
+  created_at: string;
+}
+
+/** Local worker state persisted in .sdd/worker.json */
+export interface WorkerState {
+  workerId: string;
+  name: string;
+  registeredAt: string;
+}

package/src/scaffold/templates.generated.ts

@@ -228,13 +228,14 @@ name: sdd-remote
 description: >
   Remote sync workflow for Story Driven Development. Use when the user asks
   to update local state from remote changes, process remote drafts, and push
-  enriched items back.
+  enriched items back. Also applies when running a remote worker job (enrich
+  or sync).
 license: MIT
 compatibility: Requires sdd CLI (npm i -g @applica-software-guru/sdd)
 allowed-tools: Bash(sdd:*) Read Glob Grep
 metadata:
   author: applica-software-guru
-  version: "1.0"
+  version: "1.1"
 ---
 
 # SDD Remote - Pull, Enrich, Push
@@ -244,6 +245,9 @@ metadata:
 Use this skill to synchronize local SDD docs with remote updates, enrich draft content,
 and publish the enriched result to remote in active states.
 
+This skill also applies when a **remote worker job** is dispatched from SDD Flow, as the
+worker runs these same workflows on behalf of the user.
+
 ## Detection
 
 This workflow applies when:
@@ -251,79 +255,91 @@ This workflow applies when:
 - \`.sdd/config.yaml\` exists in the project root
 - The user asks to update local state from remote, pull pending CRs/bugs/docs,
   enrich drafts, or push pending remote updates
+- A remote worker job prompt instructs you to follow this workflow
 
-## Workflow
+## Workflows
+
+### Enrich Workflow (CR)
 
-Follow this sequence in order:
+Follow this sequence to enrich a draft Change Request:
 
-1. Verify remote configuration
+1. Pull remote updates:
 
 \`\`\`bash
-test -f .sdd/config.yaml && sdd remote status
+sdd pull --crs-only
 \`\`\`
 
-If remote is not configured or disconnected, run:
+3. Generate draft TODO list:
 
 \`\`\`bash
-sdd remote init
+sdd drafts
 \`\`\`
 
-Then stop and ask the user for URL/API key if needed.
+4. Enrich the draft with technical details, acceptance criteria, edge cases, and
+   any relevant information from the project documentation and comments.
 
-2. Pull remote updates (docs + CRs + bugs)
+5. Transition the enriched CR to pending:
 
 \`\`\`bash
-sdd pull
+sdd mark-drafts-enriched
 \`\`\`
 
-Optional scoped pulls:
+This performs: \`draft → pending\`
+
+6. Push the enriched content:
 
 \`\`\`bash
-sdd pull --docs-only
-sdd pull --crs-only
-sdd pull --bugs-only
+sdd push
 \`\`\`
 
-3. Generate draft TODO list for your coding agent
+### Enrich Workflow (Document)
+
+Follow this sequence to enrich a document:
+
+1. Pull remote updates:
 
 \`\`\`bash
-sdd drafts
+sdd pull --docs-only
 \`\`\`
 
-This command lists all local draft docs, CRs, and bugs and prints a minimal TODO-style prompt.
-Give that prompt to your coding agent. If additional context is needed, the agent can fetch it directly from project files.
+3. Locate the document file in \`product/\` or \`system/\` and update its content
+   with the enriched version.
 
-4. Transition enriched drafts to active states
+4. Push the enriched content:
 
 \`\`\`bash
-sdd mark-drafts-enriched
+sdd push
 \`\`\`
 
-This performs:
+If the document was in \`draft\` status, it will transition to \`new\` on the server.
+
+### Sync Workflow (Project-level)
 
-- Document: \`draft -> new\`
-- Change Request: \`draft -> pending\`
-- Bug: \`draft -> open\`
+Follow this sequence for a full project sync (all pending items):
 
-5. Push local pending updates to remote
+1. Pull the latest specs:
 
 \`\`\`bash
-sdd push
+sdd pull
 \`\`\`
 
-6. Verify final remote sync state
+3. Run the \`sdd\` skill — it handles the full loop: open bugs, pending CRs,
+   documentation sync, code implementation, mark-synced, and commit.
+
+4. Push:
 
 \`\`\`bash
-sdd remote status
+sdd push
 \`\`\`
 
 ## Rules
 
 1. Always check remote configuration before pull/push (\`sdd remote status\`)
-2. Do not use \`sdd push --all\` unless the user explicitly asks for a full reseed
-3. If pull reports conflicts, do not overwrite local files blindly; report conflicts and ask how to proceed
-4. Do not edit files inside \`.sdd/\` manually
-5. Keep status transitions explicit: enrich first, then \`sdd mark-drafts-enriched\`, then push
+3. Do not use \`sdd push --all\` unless the user explicitly asks for a full reseed
+4. If pull reports conflicts, do not overwrite local files blindly; report conflicts and ask how to proceed
+5. Do not edit files inside \`.sdd/\` manually
+6. Keep status transitions explicit: enrich first, then \`sdd mark-drafts-enriched\`, then push
+7. **Always commit before pushing** when the sync workflow makes code changes
 
 ## Related commands
 
@@ -332,6 +348,8 @@ sdd remote status
 - \`sdd pull\`
 - \`sdd drafts\`
 - \`sdd mark-drafts-enriched\`
+- \`sdd sync\`
+- \`sdd mark-synced\`
 - \`sdd push\`
 `;