sdd-agent-platform 0.4.2 → 0.5.0

package/node_modules/@sdd-agent-platform/core/src/runtime-paths.ts

@@ -1,253 +1,253 @@
-import path from 'node:path';
-import { assertSafePathSegment, branchToSafePartition, normalizePortablePath } from './path-safety.js';
-import type { SddStage } from './contracts.js';
-
-export function getWorktreesDir(projectRoot: string): string {
-  return path.join(getSddDir(projectRoot), 'worktrees');
-}
-
-export function getSddDir(projectRoot: string): string {
-  return path.join(projectRoot, '.sdd');
-}
-
-export function getProjectConfigPath(projectRoot: string): string {
-  return path.join(getSddDir(projectRoot), 'project.yml');
-}
-
-export function getRunsDir(projectRoot: string): string {
-  return path.join(getSddDir(projectRoot), 'runs');
-}
-
-export function getRunEvidenceRoot(projectRoot: string): string {
-  return getRunsDir(projectRoot);
-}
-
-export function getBranchStageEvidenceDir(projectRoot: string, branch: string, stage: SddStage): string {
-  return path.join(getRunEvidenceRoot(projectRoot), branchToSafePartition(branch), assertKnownSddStage(stage));
-}
-
-export function getBranchStageEvidencePath(projectRoot: string, branch: string, stage: SddStage, fileName: string): string {
-  return path.join(getBranchStageEvidenceDir(projectRoot, branch, stage), normalizeBranchStageEvidenceFileName(fileName));
-}
-
-export function toBranchStageEvidenceRef(branch: string, stage: SddStage, fileName: string): string {
-  return `.sdd/runs/${branchToSafePartition(branch)}/${assertKnownSddStage(stage)}/${normalizeBranchStageEvidenceFileName(fileName)}`;
-}
-
-export function normalizeBranchStageEvidenceRef(value: string): string {
-  const normalized = normalizePortablePath(value);
-  if (path.isAbsolute(value) || !normalized.startsWith('.sdd/runs/')) {
-    throw new Error(`Stage evidence ref must start with .sdd/runs/: ${value}`);
-  }
-  const parts = normalized.split('/');
-  if (parts.length !== 5) {
-    throw new Error(`Stage evidence ref must be .sdd/runs/<branch>/<stage>/<file>: ${value}`);
-  }
-  assertSafePathSegment(parts[2], 'branch');
-  assertKnownSddStage(parts[3]);
-  normalizeBranchStageEvidenceFileName(parts[4]);
-  return parts.join('/');
-}
-
-export function isBranchStageEvidenceRef(value: string): boolean {
-  try {
-    normalizeBranchStageEvidenceRef(value);
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-export function getBranchStageEvidencePathFromRef(projectRoot: string, ref: string): string {
-  return path.join(projectRoot, ...normalizeBranchStageEvidenceRef(ref).split('/'));
-}
-
-export function normalizeStageEvidenceOrLegacyArtifactRef(value: string): string {
-  if (isBranchStageEvidenceRef(value)) {
-    return normalizeBranchStageEvidenceRef(value);
-  }
-  return getRunRelativeArtifactPath(toArtifactRootRelativePath(value));
-}
-
-export function toEvidencePayloadFileName(value: string): string {
-  if (isBranchStageEvidenceRef(value)) {
-    return normalizeBranchStageEvidenceRef(value).split('/')[4];
-  }
-  return toArtifactRootRelativePath(value);
-}
-
-export function getLocalRunIndexPath(projectRoot: string): string {
-  return path.join(getSddDir(projectRoot), 'run-index.json');
-}
-
-export function getRuntimeStorePath(projectRoot: string): string {
-  return path.join(getSddDir(projectRoot), 'runtime.sqlite');
-}
-
-export function getLegacyRunDir(projectRoot: string, runId: string): string {
-  assertSafePathSegment(runId, 'runId');
-  return path.join(getRunsDir(projectRoot), runId);
-}
-
-export function getRunDir(projectRoot: string, runId: string): string {
-  return getLegacyRunDir(projectRoot, runId);
-}
-
-export function getBranchRunRoot(projectRoot: string, branchSlug: string): string {
-  return path.join(getRunsDir(projectRoot), branchToSafePartition(branchSlug));
-}
-
-export function getEvidenceDir(projectRoot: string, branchSlug: string): string {
-  return path.join(getBranchRunRoot(projectRoot, branchSlug), 'evidence');
-}
-
-export function getEvidenceAttachmentPath(projectRoot: string, branchSlug: string, relativeEvidencePath: string): string {
-  const evidenceDir = getEvidenceDir(projectRoot, branchSlug);
-  const normalized = normalizeEvidenceRootRelativePath(relativeEvidencePath);
-  const resolved = path.resolve(evidenceDir, normalized);
-  if (!resolved.startsWith(path.resolve(evidenceDir) + path.sep) && resolved !== path.resolve(evidenceDir)) {
-    throw new Error(`Evidence path escapes evidence directory: ${relativeEvidencePath}`);
-  }
-  return resolved;
-}
-
-export function getLegacyArtifactsDir(projectRoot: string, runId: string): string {
-  return path.join(getLegacyRunDir(projectRoot, runId), 'artifacts');
-}
-
-export function getArtifactsDir(projectRoot: string, runId: string): string {
-  return getLegacyArtifactsDir(projectRoot, runId);
-}
-
-export function getLegacyAgentExecutionsDir(projectRoot: string, runId: string): string {
-  return path.join(getLegacyRunDir(projectRoot, runId), 'agent-executions');
-}
-
-export function getAgentExecutionsDir(projectRoot: string, runId: string): string {
-  return getLegacyAgentExecutionsDir(projectRoot, runId);
-}
-
-export function getLegacyTeamSessionsDir(projectRoot: string, runId: string): string {
-  return path.join(getLegacyRunDir(projectRoot, runId), 'team-sessions');
-}
-
-export function getTeamSessionsDir(projectRoot: string, runId: string): string {
-  return getLegacyTeamSessionsDir(projectRoot, runId);
-}
-
-export function getLegacyWorkerRuntimesDir(projectRoot: string, runId: string): string {
-  return path.join(getLegacyRunDir(projectRoot, runId), 'worker-runtimes');
-}
-
-export function getWorkerRuntimesDir(projectRoot: string, runId: string): string {
-  return getLegacyWorkerRuntimesDir(projectRoot, runId);
-}
-
-export function getLegacyInvocationLedgerPath(projectRoot: string, runId: string): string {
-  return path.join(getLegacyRunDir(projectRoot, runId), 'invocations.jsonl');
-}
-
-export function getInvocationLedgerPath(projectRoot: string, runId: string): string {
-  return getLegacyInvocationLedgerPath(projectRoot, runId);
-}
-
-export function getRouteCacheDir(projectRoot: string): string {
-  return path.join(getSddDir(projectRoot), 'cache', 'routes');
-}
-
-export function getRouteCachePath(projectRoot: string, key: string): string {
-  assertSafePathSegment(key, 'routeCacheKey');
-  return path.join(getRouteCacheDir(projectRoot), `${key}.json`);
-}
-
-export function getLegacyWorkerRuntimeRecordPath(projectRoot: string, runId: string, runtimeId: string): string {
-  assertSafePathSegment(runtimeId, 'runtimeId');
-  return path.join(getLegacyWorkerRuntimesDir(projectRoot, runId), `${runtimeId}.json`);
-}
-
-export function getWorkerRuntimeRecordPath(projectRoot: string, runId: string, runtimeId: string): string {
-  return getLegacyWorkerRuntimeRecordPath(projectRoot, runId, runtimeId);
-}
-
-export function getLegacyAgentExecutionRecordPath(projectRoot: string, runId: string, executionId: string): string {
-  assertSafePathSegment(executionId, 'executionId');
-  return path.join(getLegacyAgentExecutionsDir(projectRoot, runId), `${executionId}.json`);
-}
-
-export function getAgentExecutionRecordPath(projectRoot: string, runId: string, executionId: string): string {
-  return getLegacyAgentExecutionRecordPath(projectRoot, runId, executionId);
-}
-
-export function getLegacyTeamSessionRecordPath(projectRoot: string, runId: string, teamId: string): string {
-  assertSafePathSegment(teamId, 'teamId');
-  return path.join(getLegacyTeamSessionsDir(projectRoot, runId), `${teamId}.json`);
-}
-
-export function getTeamSessionRecordPath(projectRoot: string, runId: string, teamId: string): string {
-  return getLegacyTeamSessionRecordPath(projectRoot, runId, teamId);
-}
-
-export function getLegacyArtifactPath(projectRoot: string, runId: string, relativeArtifactPath: string): string {
-  const artifactsDir = getLegacyArtifactsDir(projectRoot, runId);
-  const resolved = path.resolve(artifactsDir, relativeArtifactPath);
-  if (!resolved.startsWith(path.resolve(artifactsDir) + path.sep) && resolved !== path.resolve(artifactsDir)) {
-    throw new Error(`Artifact path escapes artifacts directory: ${relativeArtifactPath}`);
-  }
-  return resolved;
-}
-
-export function getArtifactPath(projectRoot: string, runId: string, relativeArtifactPath: string): string {
-  return getLegacyArtifactPath(projectRoot, runId, relativeArtifactPath);
-}
-
-export function getRunRelativeArtifactPath(artifactRootRelativePath: string): string {
-  return `artifacts/${normalizeArtifactRootRelativePath(artifactRootRelativePath)}`;
-}
-
-export function toArtifactRootRelativePath(runRelativeArtifactPath: string): string {
-  const portablePath = runRelativeArtifactPath.replace(/\\/g, '/');
-  if (!portablePath.startsWith('artifacts/')) {
-    throw new Error(`Run-relative artifact path must start with artifacts/: ${runRelativeArtifactPath}`);
-  }
-  return normalizeArtifactRootRelativePath(portablePath.slice('artifacts/'.length));
-}
-
-export function normalizeArtifactRootRelativePath(value: string): string {
-  const normalized = normalizePortablePath(value);
-  if (!normalized || normalized === '.' || normalized.startsWith('../') || normalized === '..' || path.isAbsolute(value)) {
-    throw new Error(`Artifact path must be relative and stay under artifacts/: ${value}`);
-  }
-  if (normalized.startsWith('artifacts/')) {
-    throw new Error(`Artifact helper paths must be artifact-root-relative, not run-relative: ${value}`);
-  }
-  return normalized;
-}
-
-export function normalizeEvidenceRootRelativePath(value: string): string {
-  const normalized = normalizePortablePath(value);
-  if (!normalized || normalized === '.' || normalized.startsWith('../') || normalized === '..' || path.isAbsolute(value)) {
-    throw new Error(`Evidence path must be relative and stay under evidence/: ${value}`);
-  }
-  if (normalized.startsWith('evidence/')) {
-    throw new Error(`Evidence helper paths must be evidence-root-relative, not branch-run-relative: ${value}`);
-  }
-  return normalized;
-}
-
-function assertKnownSddStage(stage: string): SddStage {
-  if (!KNOWN_SDD_STAGES.includes(stage as SddStage)) {
-    throw new Error(`Unknown SDD stage: ${stage}`);
-  }
-  return stage as SddStage;
-}
-
-function normalizeBranchStageEvidenceFileName(fileName: string): string {
-  if (path.isAbsolute(fileName) || fileName.includes('/') || fileName.includes('\\') || fileName.includes('..')) {
-    throw new Error(`Stage evidence file name must be a single safe file name: ${fileName}`);
-  }
-  const normalized = normalizePortablePath(fileName);
-  assertSafePathSegment(normalized, 'stageEvidenceFileName');
-  return normalized;
-}
-
-const KNOWN_SDD_STAGES: SddStage[] = ['spec', 'plan', 'tasks', 'verifies', 'do', 'test', 'goal-verify', 'ship'];
+import path from 'node:path';
+import { assertSafePathSegment, branchToSafePartition, normalizePortablePath } from './path-safety.js';
+import type { SddStage } from './contracts.js';
+
+export function getWorktreesDir(projectRoot: string): string {
+  return path.join(getSddDir(projectRoot), 'worktrees');
+}
+
+export function getSddDir(projectRoot: string): string {
+  return path.join(projectRoot, '.sdd');
+}
+
+export function getProjectConfigPath(projectRoot: string): string {
+  return path.join(getSddDir(projectRoot), 'project.yml');
+}
+
+export function getRunsDir(projectRoot: string): string {
+  return path.join(getSddDir(projectRoot), 'runs');
+}
+
+export function getRunEvidenceRoot(projectRoot: string): string {
+  return getRunsDir(projectRoot);
+}
+
+export function getBranchStageEvidenceDir(projectRoot: string, branch: string, stage: SddStage): string {
+  return path.join(getRunEvidenceRoot(projectRoot), branchToSafePartition(branch), assertKnownSddStage(stage));
+}
+
+export function getBranchStageEvidencePath(projectRoot: string, branch: string, stage: SddStage, fileName: string): string {
+  return path.join(getBranchStageEvidenceDir(projectRoot, branch, stage), normalizeBranchStageEvidenceFileName(fileName));
+}
+
+export function toBranchStageEvidenceRef(branch: string, stage: SddStage, fileName: string): string {
+  return `.sdd/runs/${branchToSafePartition(branch)}/${assertKnownSddStage(stage)}/${normalizeBranchStageEvidenceFileName(fileName)}`;
+}
+
+export function normalizeBranchStageEvidenceRef(value: string): string {
+  const normalized = normalizePortablePath(value);
+  if (path.isAbsolute(value) || !normalized.startsWith('.sdd/runs/')) {
+    throw new Error(`Stage evidence ref must start with .sdd/runs/: ${value}`);
+  }
+  const parts = normalized.split('/');
+  if (parts.length !== 5) {
+    throw new Error(`Stage evidence ref must be .sdd/runs/<branch>/<stage>/<file>: ${value}`);
+  }
+  assertSafePathSegment(parts[2], 'branch');
+  assertKnownSddStage(parts[3]);
+  normalizeBranchStageEvidenceFileName(parts[4]);
+  return parts.join('/');
+}
+
+export function isBranchStageEvidenceRef(value: string): boolean {
+  try {
+    normalizeBranchStageEvidenceRef(value);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function getBranchStageEvidencePathFromRef(projectRoot: string, ref: string): string {
+  return path.join(projectRoot, ...normalizeBranchStageEvidenceRef(ref).split('/'));
+}
+
+export function normalizeStageEvidenceOrLegacyArtifactRef(value: string): string {
+  if (isBranchStageEvidenceRef(value)) {
+    return normalizeBranchStageEvidenceRef(value);
+  }
+  return getRunRelativeArtifactPath(toArtifactRootRelativePath(value));
+}
+
+export function toEvidencePayloadFileName(value: string): string {
+  if (isBranchStageEvidenceRef(value)) {
+    return normalizeBranchStageEvidenceRef(value).split('/')[4];
+  }
+  return toArtifactRootRelativePath(value);
+}
+
+export function getLocalRunIndexPath(projectRoot: string): string {
+  return path.join(getSddDir(projectRoot), 'run-index.json');
+}
+
+export function getRuntimeStorePath(projectRoot: string): string {
+  return path.join(getSddDir(projectRoot), 'runtime.sqlite');
+}
+
+export function getLegacyRunDir(projectRoot: string, runId: string): string {
+  assertSafePathSegment(runId, 'runId');
+  return path.join(getRunsDir(projectRoot), runId);
+}
+
+export function getRunDir(projectRoot: string, runId: string): string {
+  return getLegacyRunDir(projectRoot, runId);
+}
+
+export function getBranchRunRoot(projectRoot: string, branchSlug: string): string {
+  return path.join(getRunsDir(projectRoot), branchToSafePartition(branchSlug));
+}
+
+export function getEvidenceDir(projectRoot: string, branchSlug: string): string {
+  return path.join(getBranchRunRoot(projectRoot, branchSlug), 'evidence');
+}
+
+export function getEvidenceAttachmentPath(projectRoot: string, branchSlug: string, relativeEvidencePath: string): string {
+  const evidenceDir = getEvidenceDir(projectRoot, branchSlug);
+  const normalized = normalizeEvidenceRootRelativePath(relativeEvidencePath);
+  const resolved = path.resolve(evidenceDir, normalized);
+  if (!resolved.startsWith(path.resolve(evidenceDir) + path.sep) && resolved !== path.resolve(evidenceDir)) {
+    throw new Error(`Evidence path escapes evidence directory: ${relativeEvidencePath}`);
+  }
+  return resolved;
+}
+
+export function getLegacyArtifactsDir(projectRoot: string, runId: string): string {
+  return path.join(getLegacyRunDir(projectRoot, runId), 'artifacts');
+}
+
+export function getArtifactsDir(projectRoot: string, runId: string): string {
+  return getLegacyArtifactsDir(projectRoot, runId);
+}
+
+export function getLegacyAgentExecutionsDir(projectRoot: string, runId: string): string {
+  return path.join(getLegacyRunDir(projectRoot, runId), 'agent-executions');
+}
+
+export function getAgentExecutionsDir(projectRoot: string, runId: string): string {
+  return getLegacyAgentExecutionsDir(projectRoot, runId);
+}
+
+export function getLegacyTeamSessionsDir(projectRoot: string, runId: string): string {
+  return path.join(getLegacyRunDir(projectRoot, runId), 'team-sessions');
+}
+
+export function getTeamSessionsDir(projectRoot: string, runId: string): string {
+  return getLegacyTeamSessionsDir(projectRoot, runId);
+}
+
+export function getLegacyWorkerRuntimesDir(projectRoot: string, runId: string): string {
+  return path.join(getLegacyRunDir(projectRoot, runId), 'worker-runtimes');
+}
+
+export function getWorkerRuntimesDir(projectRoot: string, runId: string): string {
+  return getLegacyWorkerRuntimesDir(projectRoot, runId);
+}
+
+export function getLegacyInvocationLedgerPath(projectRoot: string, runId: string): string {
+  return path.join(getLegacyRunDir(projectRoot, runId), 'invocations.jsonl');
+}
+
+export function getInvocationLedgerPath(projectRoot: string, runId: string): string {
+  return getLegacyInvocationLedgerPath(projectRoot, runId);
+}
+
+export function getRouteCacheDir(projectRoot: string): string {
+  return path.join(getSddDir(projectRoot), 'cache', 'routes');
+}
+
+export function getRouteCachePath(projectRoot: string, key: string): string {
+  assertSafePathSegment(key, 'routeCacheKey');
+  return path.join(getRouteCacheDir(projectRoot), `${key}.json`);
+}
+
+export function getLegacyWorkerRuntimeRecordPath(projectRoot: string, runId: string, runtimeId: string): string {
+  assertSafePathSegment(runtimeId, 'runtimeId');
+  return path.join(getLegacyWorkerRuntimesDir(projectRoot, runId), `${runtimeId}.json`);
+}
+
+export function getWorkerRuntimeRecordPath(projectRoot: string, runId: string, runtimeId: string): string {
+  return getLegacyWorkerRuntimeRecordPath(projectRoot, runId, runtimeId);
+}
+
+export function getLegacyAgentExecutionRecordPath(projectRoot: string, runId: string, executionId: string): string {
+  assertSafePathSegment(executionId, 'executionId');
+  return path.join(getLegacyAgentExecutionsDir(projectRoot, runId), `${executionId}.json`);
+}
+
+export function getAgentExecutionRecordPath(projectRoot: string, runId: string, executionId: string): string {
+  return getLegacyAgentExecutionRecordPath(projectRoot, runId, executionId);
+}
+
+export function getLegacyTeamSessionRecordPath(projectRoot: string, runId: string, teamId: string): string {
+  assertSafePathSegment(teamId, 'teamId');
+  return path.join(getLegacyTeamSessionsDir(projectRoot, runId), `${teamId}.json`);
+}
+
+export function getTeamSessionRecordPath(projectRoot: string, runId: string, teamId: string): string {
+  return getLegacyTeamSessionRecordPath(projectRoot, runId, teamId);
+}
+
+export function getLegacyArtifactPath(projectRoot: string, runId: string, relativeArtifactPath: string): string {
+  const artifactsDir = getLegacyArtifactsDir(projectRoot, runId);
+  const resolved = path.resolve(artifactsDir, relativeArtifactPath);
+  if (!resolved.startsWith(path.resolve(artifactsDir) + path.sep) && resolved !== path.resolve(artifactsDir)) {
+    throw new Error(`Artifact path escapes artifacts directory: ${relativeArtifactPath}`);
+  }
+  return resolved;
+}
+
+export function getArtifactPath(projectRoot: string, runId: string, relativeArtifactPath: string): string {
+  return getLegacyArtifactPath(projectRoot, runId, relativeArtifactPath);
+}
+
+export function getRunRelativeArtifactPath(artifactRootRelativePath: string): string {
+  return `artifacts/${normalizeArtifactRootRelativePath(artifactRootRelativePath)}`;
+}
+
+export function toArtifactRootRelativePath(runRelativeArtifactPath: string): string {
+  const portablePath = runRelativeArtifactPath.replace(/\\/g, '/');
+  if (!portablePath.startsWith('artifacts/')) {
+    throw new Error(`Run-relative artifact path must start with artifacts/: ${runRelativeArtifactPath}`);
+  }
+  return normalizeArtifactRootRelativePath(portablePath.slice('artifacts/'.length));
+}
+
+export function normalizeArtifactRootRelativePath(value: string): string {
+  const normalized = normalizePortablePath(value);
+  if (!normalized || normalized === '.' || normalized.startsWith('../') || normalized === '..' || path.isAbsolute(value)) {
+    throw new Error(`Artifact path must be relative and stay under artifacts/: ${value}`);
+  }
+  if (normalized.startsWith('artifacts/')) {
+    throw new Error(`Artifact helper paths must be artifact-root-relative, not run-relative: ${value}`);
+  }
+  return normalized;
+}
+
+export function normalizeEvidenceRootRelativePath(value: string): string {
+  const normalized = normalizePortablePath(value);
+  if (!normalized || normalized === '.' || normalized.startsWith('../') || normalized === '..' || path.isAbsolute(value)) {
+    throw new Error(`Evidence path must be relative and stay under evidence/: ${value}`);
+  }
+  if (normalized.startsWith('evidence/')) {
+    throw new Error(`Evidence helper paths must be evidence-root-relative, not branch-run-relative: ${value}`);
+  }
+  return normalized;
+}
+
+function assertKnownSddStage(stage: string): SddStage {
+  if (!KNOWN_SDD_STAGES.includes(stage as SddStage)) {
+    throw new Error(`Unknown SDD stage: ${stage}`);
+  }
+  return stage as SddStage;
+}
+
+function normalizeBranchStageEvidenceFileName(fileName: string): string {
+  if (path.isAbsolute(fileName) || fileName.includes('/') || fileName.includes('\\') || fileName.includes('..')) {
+    throw new Error(`Stage evidence file name must be a single safe file name: ${fileName}`);
+  }
+  const normalized = normalizePortablePath(fileName);
+  assertSafePathSegment(normalized, 'stageEvidenceFileName');
+  return normalized;
+}
+
+const KNOWN_SDD_STAGES: SddStage[] = ['spec', 'plan', 'tasks', 'execute', 'ship'];