sdd-agent-platform 0.3.0 → 0.4.1

package/node_modules/@sdd-agent-platform/core/src/worktree/lifecycle.ts

@@ -0,0 +1,269 @@
+import { execFile } from 'node:child_process';
+import { mkdir, readdir, readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { promisify } from 'node:util';
+import { parseProjectConfig } from '../config/project-config.js';
+import { assertSafePathSegment } from '../path-safety.js';
+import { appendEvent } from '../run-state/events.js';
+import { readRunState, writeRunState } from '../run-state/run-state.js';
+import { getProjectConfigPath, getWorktreesDir } from '../runtime-paths.js';
+import { exists } from '../storage/json-io.js';
+import { inspectWorktreeIsolation } from './isolation.js';
+
+const execFileAsync = promisify(execFile);
+
+export const WORKTREE_LIFECYCLE_CONTRACT_VERSION = 'phase-3.8-worktree-lifecycle-v1';
+
+export interface WorktreeLifecycleIssue {
+  field: string;
+  message: string;
+  recommendation: string;
+}
+
+export type WorktreeLifecycleStatus = 'created' | 'kept' | 'removed';
+
+export interface WorktreeLifecycleRecord {
+  contract: typeof WORKTREE_LIFECYCLE_CONTRACT_VERSION;
+  runId: string;
+  taskId: string;
+  worktreeId: string;
+  status: WorktreeLifecycleStatus;
+  branchName: string;
+  worktreePath: string;
+  baseRef: string;
+  createdAt: string;
+  updatedAt: string;
+  removedAt: string | null;
+  keepReason: string | null;
+  dirty: boolean;
+}
+
+export interface WorktreeLifecycleInspection {
+  runId: string;
+  contract: typeof WORKTREE_LIFECYCLE_CONTRACT_VERSION;
+  records: WorktreeLifecycleRecord[];
+  valid: boolean;
+  issues: WorktreeLifecycleIssue[];
+}
+
+export async function createWorktreeLifecycle(projectRoot: string, runId: string, options: { taskId: string; baseRef?: string; worktreeId?: string }): Promise<WorktreeLifecycleRecord> {
+  await assertProjectConfigReadable(projectRoot);
+  const state = await readRunState(projectRoot, runId);
+  const decision = await inspectWorktreeIsolation(projectRoot, { taskId: options.taskId });
+  if (decision.mode === 'blocked' || decision.mode === 'none') {
+    throw new Error(`Cannot create worktree for ${options.taskId}: isolation mode is ${decision.mode}.`);
+  }
+  const gitRoot = await getGitRoot(projectRoot);
+  if (!gitRoot) {
+    throw new Error('Cannot create worktree outside a Git repository.');
+  }
+
+  const worktreeId = options.worktreeId ?? defaultWorktreeId(runId, options.taskId);
+  assertSafePathSegment(worktreeId, 'worktreeId');
+  const currentWorktrees = state.worktrees ?? {};
+  const existing = currentWorktrees[worktreeId];
+  if (existing && existing.status !== 'removed') {
+    throw new Error(`Worktree ${worktreeId} already exists for run ${runId}.`);
+  }
+
+  const baseRef = options.baseRef ?? 'HEAD';
+  const branchName = `sdd-${worktreeId}`;
+  const worktreePath = path.join(getWorktreesDir(projectRoot), worktreeId);
+  await mkdir(path.dirname(worktreePath), { recursive: true });
+  await execFileAsync('git', ['-C', projectRoot, 'worktree', 'add', '-b', branchName, worktreePath, baseRef]);
+
+  const now = new Date().toISOString();
+  const record: WorktreeLifecycleRecord = {
+    contract: WORKTREE_LIFECYCLE_CONTRACT_VERSION,
+    runId,
+    taskId: options.taskId,
+    worktreeId,
+    status: 'created',
+    branchName,
+    worktreePath: path.relative(projectRoot, worktreePath),
+    baseRef,
+    createdAt: now,
+    updatedAt: now,
+    removedAt: null,
+    keepReason: null,
+    dirty: false
+  };
+  await writeRunState(projectRoot, { ...state, worktrees: { ...currentWorktrees, [worktreeId]: record } });
+  await appendEvent(projectRoot, runId, {
+    event: 'worktree_created',
+    runId,
+    summary: `Worktree ${worktreeId} created for ${options.taskId}.`,
+    data: { worktreeId, taskId: options.taskId, path: record.worktreePath, branchName, baseRef }
+  });
+  return record;
+}
+
+export async function inspectWorktreeLifecycle(projectRoot: string, runId: string): Promise<WorktreeLifecycleInspection> {
+  const state = await readRunState(projectRoot, runId);
+  const records = await Promise.all(Object.values(state.worktrees ?? {}).map(async (record) => ({
+    ...record,
+    dirty: record.status === 'removed' ? false : await isGitWorktreeDirty(projectRoot, record.worktreePath)
+  })));
+  const issues: WorktreeLifecycleIssue[] = [];
+  const activePaths = new Set(records.filter((record) => record.status !== 'removed').map((record) => normalizeComparablePath(record.worktreePath)));
+  const registeredPaths = await listGitWorktreePaths(projectRoot);
+
+  for (const record of records) {
+    const absolutePath = path.resolve(projectRoot, record.worktreePath);
+    const comparablePath = normalizeComparablePath(record.worktreePath);
+    const pathExists = await exists(absolutePath);
+    if (record.contract !== WORKTREE_LIFECYCLE_CONTRACT_VERSION) {
+      issues.push(lifecycleIssue('contract', `${record.worktreeId} uses ${record.contract}.`, `Use ${WORKTREE_LIFECYCLE_CONTRACT_VERSION}.`));
+    }
+    if (record.status !== 'removed' && !pathExists) {
+      issues.push(lifecycleIssue('worktreePath', `${record.worktreeId} points to missing worktree path ${record.worktreePath}.`, 'Inspect worktree state and mark removed only through lifecycle remove.'));
+    }
+    if (record.status !== 'removed' && pathExists && !registeredPaths.has(normalizeComparablePath(absolutePath))) {
+      issues.push(lifecycleIssue('worktreePath', `${record.worktreeId} path is not registered in git worktree list.`, 'Inspect git worktree list and reconcile lifecycle state.'));
+    }
+    if (record.status === 'removed' && pathExists) {
+      issues.push(lifecycleIssue('status', `${record.worktreeId} is removed in state but path still exists.`, 'Inspect the path before deleting anything manually.'));
+    }
+    if (record.status !== 'removed' && record.dirty) {
+      issues.push(lifecycleIssue('dirty', `${record.worktreeId} has uncommitted changes.`, 'Keep the worktree or resolve changes before lifecycle remove.'));
+    }
+    if (record.status !== 'removed' && activePaths.has(comparablePath) && Array.from(activePaths).filter((item) => item === comparablePath).length > 1) {
+      issues.push(lifecycleIssue('worktreePath', `${record.worktreeId} shares a path with another active worktree.`, 'Use one lifecycle record per worktree path.'));
+    }
+  }
+
+  for (const orphanPath of await listOrphanWorktreeDirs(projectRoot, activePaths)) {
+    issues.push(lifecycleIssue('orphan', `${orphanPath} exists without active lifecycle state.`, 'Inspect the directory before removing it or recreate lifecycle state.'));
+  }
+
+  return {
+    runId,
+    contract: WORKTREE_LIFECYCLE_CONTRACT_VERSION,
+    records,
+    valid: issues.length === 0,
+    issues
+  };
+}
+
+export async function keepWorktreeLifecycle(projectRoot: string, runId: string, worktreeId: string, options: { reason?: string } = {}): Promise<WorktreeLifecycleRecord> {
+  assertSafePathSegment(worktreeId, 'worktreeId');
+  const state = await readRunState(projectRoot, runId);
+  const record = (state.worktrees ?? {})[worktreeId];
+  if (!record) {
+    throw new Error(`Unknown worktree ${worktreeId} for run ${runId}.`);
+  }
+  const now = new Date().toISOString();
+  const nextRecord: WorktreeLifecycleRecord = {
+    ...record,
+    status: 'kept',
+    updatedAt: now,
+    keepReason: options.reason ?? 'kept for later inspection',
+    dirty: await isGitWorktreeDirty(projectRoot, record.worktreePath)
+  };
+  await writeRunState(projectRoot, { ...state, worktrees: { ...(state.worktrees ?? {}), [worktreeId]: nextRecord } });
+  await appendEvent(projectRoot, runId, {
+    event: 'worktree_kept',
+    runId,
+    summary: `Worktree ${worktreeId} kept.`,
+    data: { worktreeId, reason: nextRecord.keepReason, dirty: nextRecord.dirty }
+  });
+  return nextRecord;
+}
+
+export async function removeWorktreeLifecycle(projectRoot: string, runId: string, worktreeId: string): Promise<WorktreeLifecycleRecord> {
+  assertSafePathSegment(worktreeId, 'worktreeId');
+  const state = await readRunState(projectRoot, runId);
+  const record = (state.worktrees ?? {})[worktreeId];
+  if (!record) {
+    throw new Error(`Unknown worktree ${worktreeId} for run ${runId}.`);
+  }
+  if (record.status === 'removed') {
+    return record;
+  }
+  const dirty = await isGitWorktreeDirty(projectRoot, record.worktreePath);
+  if (dirty) {
+    throw new Error(`Refusing to remove dirty worktree ${worktreeId}. Commit, stash, or keep it first.`);
+  }
+  await execFileAsync('git', ['-C', projectRoot, 'worktree', 'remove', path.resolve(projectRoot, record.worktreePath)]);
+  const now = new Date().toISOString();
+  const nextRecord: WorktreeLifecycleRecord = {
+    ...record,
+    status: 'removed',
+    updatedAt: now,
+    removedAt: now,
+    dirty: false
+  };
+  await writeRunState(projectRoot, { ...state, worktrees: { ...(state.worktrees ?? {}), [worktreeId]: nextRecord } });
+  await appendEvent(projectRoot, runId, {
+    event: 'worktree_removed',
+    runId,
+    summary: `Worktree ${worktreeId} removed.`,
+    data: { worktreeId, path: record.worktreePath }
+  });
+  return nextRecord;
+}
+
+async function assertProjectConfigReadable(projectRoot: string): Promise<void> {
+  const configPath = getProjectConfigPath(projectRoot);
+  const raw = await readFile(configPath, 'utf8');
+  parseProjectConfig(raw, configPath);
+}
+
+function defaultWorktreeId(runId: string, taskId: string): string {
+  return `wt-${runId}-${taskId}`.replace(/[^A-Za-z0-9._-]/g, '-');
+}
+
+async function isGitWorktreeDirty(projectRoot: string, worktreePath: string): Promise<boolean> {
+  const absolutePath = path.resolve(projectRoot, worktreePath);
+  if (!await exists(absolutePath)) {
+    return false;
+  }
+  try {
+    const result = await execFileAsync('git', ['-C', absolutePath, 'status', '--porcelain']);
+    return result.stdout.trim().length > 0;
+  } catch {
+    return true;
+  }
+}
+
+async function listGitWorktreePaths(projectRoot: string): Promise<Set<string>> {
+  try {
+    const result = await execFileAsync('git', ['-C', projectRoot, 'worktree', 'list', '--porcelain']);
+    return new Set(result.stdout.split(/\r?\n/).filter((line) => line.startsWith('worktree ')).map((line) => normalizeComparablePath(path.resolve(line.slice('worktree '.length)))));
+  } catch {
+    return new Set();
+  }
+}
+
+async function listOrphanWorktreeDirs(projectRoot: string, activePaths: Set<string>): Promise<string[]> {
+  const worktreesDir = getWorktreesDir(projectRoot);
+  if (!await exists(worktreesDir)) {
+    return [];
+  }
+  const entries = await readdir(worktreesDir, { withFileTypes: true });
+  const orphans: string[] = [];
+  for (const entry of entries.filter((candidate) => candidate.isDirectory())) {
+    const relativePath = path.relative(projectRoot, path.join(worktreesDir, entry.name));
+    if (!activePaths.has(normalizeComparablePath(relativePath))) {
+      orphans.push(relativePath);
+    }
+  }
+  return orphans;
+}
+
+async function getGitRoot(projectRoot: string): Promise<string | null> {
+  try {
+    const result = await execFileAsync('git', ['-C', projectRoot, 'rev-parse', '--show-toplevel']);
+    return result.stdout.trim();
+  } catch {
+    return null;
+  }
+}
+
+function normalizeComparablePath(filePath: string): string {
+  return filePath.replace(/\\/g, '/').replace(/^\.\//, '');
+}
+
+function lifecycleIssue(field: string, message: string, recommendation: string): WorktreeLifecycleIssue {
+  return { field, message, recommendation };
+}

package/node_modules/@sdd-agent-platform/core/src/worktree/worktree.test.ts

@@ -0,0 +1,150 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { execFile } from 'node:child_process';
+import { mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { promisify } from 'node:util';
+
+import { initProject } from '../config/init-project.js';
+import { doctor } from '../doctor/doctor.js';
+import { readRunEvents } from '../run-state/events.js';
+import { createRun, readRunState } from '../run-state/run-state.js';
+import { taskMarkdownWithFiles, writeBranchDocs } from '../test-support/fixtures.js';
+import { inspectWorktreeIsolation } from './isolation.js';
+import { createWorktreeLifecycle, inspectWorktreeLifecycle, keepWorktreeLifecycle, removeWorktreeLifecycle } from './lifecycle.js';
+
+const execFileAsync = promisify(execFile);
+
+test('worktree isolation blocks writable overlapping tasks and allows read-only', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'sdd-isolation-overlap-'));
+  try {
+    await initProject(root);
+    await writeBranchDocs(root, 'master', `# Tasks\n\n${taskMarkdownWithFiles('T1', ['packages/core/src/index.ts'], [])}\n${taskMarkdownWithFiles('T2', ['./packages/core/src/index.ts'], [])}`);
+
+    const blocked = await inspectWorktreeIsolation(root, {
+      taskId: 'T1',
+      capabilityId: 'native-file-edit',
+      peerTaskIds: ['T2']
+    });
+    const readOnly = await inspectWorktreeIsolation(root, {
+      taskId: 'T1',
+      capabilityId: 'git-local',
+      peerTaskIds: ['T2']
+    });
+
+    assert.equal(blocked.mode, 'blocked');
+    assert.equal(blocked.safeConcurrency, false);
+    assert.deepEqual(blocked.overlaps, [{ peerTaskId: 'T2', files: ['packages/core/src/index.ts'] }]);
+    assert.equal(blocked.gates.find((gate) => gate.name === 'unsafe_concurrency')?.passed, false);
+    assert.equal(readOnly.mode, 'none');
+    assert.equal(readOnly.safeConcurrency, true);
+    assert.equal(readOnly.capabilitySideEffect, 'read_only');
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test('worktree isolation marks high-risk writable task as manual or required', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'sdd-isolation-risk-'));
+  try {
+    await initProject(root);
+    await writeBranchDocs(root, 'master', `# Tasks\n\n${taskMarkdownWithFiles('T1', ['db/schema.sql'], ['database'])}\n${taskMarkdownWithFiles('T2', ['packages/core/src/index.ts'], ['state-machine'])}`);
+
+    const manual = await inspectWorktreeIsolation(root, { taskId: 'T1', capabilityId: 'native-file-edit' });
+    const required = await inspectWorktreeIsolation(root, { taskId: 'T2', capabilityId: 'native-file-edit' });
+
+    assert.equal(manual.mode, 'manual');
+    assert.equal(manual.reasons.some((reason) => reason.includes('manual isolation gate')), true);
+    assert.equal(required.mode, 'required');
+    assert.equal(required.reasons.some((reason) => reason.includes('High-risk writable task')), true);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test('doctor reports worktree isolation contract visibility', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'sdd-isolation-doctor-'));
+  try {
+    await initProject(root);
+
+    const report = await doctor(root, { latestOnly: true });
+    const check = report.checks.find((item) => item.check === 'worktree_isolation_contract');
+
+    assert.equal(check?.level, 'PASS');
+    assert.match(check?.message ?? '', /phase-3\.7-worktree-isolation-contract-v1/);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test('worktree lifecycle creates and removes clean tracked worktree', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'sdd-worktree-clean-'));
+  try {
+    await initProject(root);
+    await writeBranchDocs(root, 'master', `# Tasks\n\n${taskMarkdownWithFiles('T1', ['packages/core/src/index.ts'], [])}`);
+    await initializeGitRepository(root);
+    await createRun(root, { runId: 'run-1' });
+
+    const created = await createWorktreeLifecycle(root, 'run-1', { taskId: 'T1', worktreeId: 'wt-run-1-T1' });
+    const createdState = await readRunState(root, 'run-1');
+    const createdEvents = await readRunEvents(root, 'run-1');
+    const removed = await removeWorktreeLifecycle(root, 'run-1', 'wt-run-1-T1');
+    const inspection = await inspectWorktreeLifecycle(root, 'run-1');
+    const removedEvents = await readRunEvents(root, 'run-1');
+
+    assert.equal(created.status, 'created');
+    assert.equal(created.contract, 'phase-3.8-worktree-lifecycle-v1');
+    assert.equal(createdState.worktrees['wt-run-1-T1'].worktreePath, created.worktreePath);
+    assert.equal(createdEvents.some((event) => event.event === 'worktree_created'), true);
+    assert.equal(removed.status, 'removed');
+    assert.equal(inspection.valid, true);
+    assert.equal(removedEvents.some((event) => event.event === 'worktree_removed'), true);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test('worktree lifecycle refuses dirty remove and can keep for inspection', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'sdd-worktree-dirty-'));
+  try {
+    await initProject(root);
+    await writeBranchDocs(root, 'master', `# Tasks\n\n${taskMarkdownWithFiles('T1', ['packages/core/src/index.ts'], [])}`);
+    await initializeGitRepository(root);
+    await createRun(root, { runId: 'run-1' });
+
+    const created = await createWorktreeLifecycle(root, 'run-1', { taskId: 'T1', worktreeId: 'wt-run-1-T1' });
+    await writeFile(path.join(root, created.worktreePath, 'dirty.txt'), 'dirty', 'utf8');
+    await assert.rejects(removeWorktreeLifecycle(root, 'run-1', 'wt-run-1-T1'), /Refusing to remove dirty worktree/);
+    const kept = await keepWorktreeLifecycle(root, 'run-1', 'wt-run-1-T1', { reason: 'manual inspection' });
+    const inspection = await inspectWorktreeLifecycle(root, 'run-1');
+
+    assert.equal(kept.status, 'kept');
+    assert.equal(kept.dirty, true);
+    assert.equal(inspection.valid, false);
+    assert.equal(inspection.issues.some((issue) => issue.field === 'dirty'), true);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test('doctor reports worktree lifecycle contract visibility', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'sdd-worktree-doctor-'));
+  try {
+    await initProject(root);
+
+    const report = await doctor(root, { latestOnly: true });
+    const check = report.checks.find((item) => item.check === 'worktree_lifecycle_contract');
+
+    assert.equal(check?.level, 'PASS');
+    assert.match(check?.message ?? '', /phase-3\.8-worktree-lifecycle-v1/);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+async function initializeGitRepository(root: string): Promise<void> {
+  await execFileAsync('git', ['-C', root, 'init']);
+  await execFileAsync('git', ['-C', root, 'add', '.']);
+  await execFileAsync('git', ['-C', root, '-c', 'user.name=sdd-test', '-c', 'user.email=sdd-test@example.com', 'commit', '--allow-empty', '-m', 'init']);
+}

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

@@ -0,0 +1,2 @@
+export * from './worktree/isolation.js';
+export * from './worktree/lifecycle.js';

package/node_modules/@sdd-agent-platform/core/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "composite": true,
+    "rootDir": "src",
+    "outDir": "dist",
+    "tsBuildInfoFile": "dist/tsconfig.tsbuildinfo"
+  },
+  "include": [
+    "src/**/*.ts"
+  ],
+  "exclude": [
+    "src/**/*.test.ts"
+  ]
+}

package/package.json

@@ -1,52 +1,67 @@
-{
-  "name": "sdd-agent-platform",
-  "version": "0.3.0",
-  "type": "module",
-  "description": "Local SDD + subagent workflow platform for Claude Code.",
-  "license": "MIT",
-  "homepage": "https://github.com/Timetraps-x/sdd-agent-platform#readme",
-  "bugs": {
-    "url": "https://github.com/Timetraps-x/sdd-agent-platform/issues"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/Timetraps-x/sdd-agent-platform.git"
-  },
-  "keywords": [
-    "sdd",
-    "spec-driven-development",
-    "claude-code",
-    "agent-workflow",
-    "cli"
-  ],
-  "bin": {
-    "sdd": "dist/packages/cli/src/main.js"
-  },
-  "files": [
-    "dist",
-    "README.md",
-    "package.json",
-    "tsconfig.build.json"
-  ],
-  "engines": {
-    "node": ">=22.5.0"
-  },
-  "publishConfig": {
-    "access": "public"
-  },
-  "scripts": {
-    "build": "tsc -p tsconfig.build.json",
-    "prepare": "npm run build",
-    "typecheck": "tsc --noEmit",
-    "test": "node --test --import tsx \"packages/**/*.test.ts\"",
-    "sdd": "tsx packages/cli/src/main.ts"
-  },
-  "workspaces": [
-    "packages/*"
-  ],
-  "devDependencies": {
-    "@types/node": "^24.10.0",
-    "tsx": "^4.20.6",
-    "typescript": "^5.9.0"
-  }
-}
+{
+  "name": "sdd-agent-platform",
+  "version": "0.4.1",
+  "type": "module",
+  "description": "Local SDD + subagent workflow platform for Claude Code.",
+  "license": "MIT",
+  "homepage": "https://github.com/Timetraps-x/sdd-agent-platform#readme",
+  "bugs": {
+    "url": "https://github.com/Timetraps-x/sdd-agent-platform/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Timetraps-x/sdd-agent-platform.git"
+  },
+  "keywords": [
+    "sdd",
+    "spec-driven-development",
+    "claude-code",
+    "agent-workflow",
+    "cli"
+  ],
+  "bin": {
+    "sdd": "packages/cli/dist/main.js"
+  },
+  "files": [
+    "packages/cli/dist",
+    "packages/cli/package.json",
+    "packages/core/dist",
+    "packages/core/package.json",
+    "README.md",
+    "package.json",
+    "tsconfig.build.json"
+  ],
+  "engines": {
+    "node": ">=22.5.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -b tsconfig.build.json",
+    "prepare": "npm run build",
+    "typecheck": "npm run build && tsc --noEmit",
+    "test": "npm run build && node --test --import tsx \"packages/**/*.test.ts\"",
+    "sdd": "npm run build --silent && node packages/cli/dist/main.js"
+  },
+  "workspaces": [
+    "packages/*"
+  ],
+  "dependencies": {
+    "@sdd-agent-platform/core": "file:packages/core"
+  },
+  "devDependencies": {
+    "@types/node": "^24.10.0",
+    "tsx": "^4.20.6",
+    "typescript": "^5.9.0"
+  },
+  "bundleDependencies": [
+    "@sdd-agent-platform/core"
+  ],
+  "main": "index.js",
+  "directories": {
+    "doc": "docs",
+    "example": "examples"
+  },
+  "author": ""
+}

package/packages/cli/dist/args.d.ts

@@ -0,0 +1,23 @@
+import type { AiToolSelection } from '@sdd-agent-platform/core/ai-tools';
+import type { RunStatus } from '@sdd-agent-platform/core/run-state';
+import { type ContextBranchSource } from '@sdd-agent-platform/core/sdd-docs';
+import type { SddResultStatus } from '@sdd-agent-platform/core/artifacts';
+import type { GovernancePolicyOperation } from '@sdd-agent-platform/core/governance';
+import type { ContextBuildMode } from '@sdd-agent-platform/core/context';
+import type { WaveExecutorStrategy } from '@sdd-agent-platform/core/execution';
+import type { TeamModeActivation } from '@sdd-agent-platform/core/router';
+export declare function readContextBuildMode(args: string[], name: string): ContextBuildMode | null;
+export declare function readTeamModeActivation(args: string[], fallback?: TeamModeActivation): TeamModeActivation | undefined;
+export declare function readBranchContext(args: string[]): {
+    branch?: string;
+    branchSource?: ContextBranchSource;
+};
+export declare function readBranchOption(args: string[]): string | undefined;
+export declare function readOptionalPositionalArgument(args: string[]): string | undefined;
+export declare function readResolvedBranch(projectRoot: string, args: string[]): Promise<string>;
+export declare function readWaveExecutorStrategy(args: string[], name: string): WaveExecutorStrategy | null;
+export declare function readRunStatus(args: string[], name: string): RunStatus | null;
+export declare function readGovernancePolicyOperation(value: string | undefined): GovernancePolicyOperation | null;
+export declare function readTaskArtifactOptions(args: string[]): Record<string, string>;
+export declare function readSddResultStatus(args: string[], name: string): SddResultStatus | null;
+export declare function readAiToolSelection(args: string[], allowNone: boolean): AiToolSelection;

package/packages/cli/dist/args.js

@@ -0,0 +1,89 @@
+import { resolveSddContext } from '@sdd-agent-platform/core/sdd-docs';
+import { readOption } from './options.js';
+export function readContextBuildMode(args, name) {
+    const value = readOption(args, name);
+    return value === 'do' || value === 'verify' || value === 'sync-back' || value === 'doctor' ? value : null;
+}
+export function readTeamModeActivation(args, fallback) {
+    if (args.includes('--no-team-mode')) {
+        return 'off';
+    }
+    const inline = args.find((item) => item.startsWith('--team-mode='));
+    const inlineValue = inline?.split('=', 2)[1];
+    if (inlineValue === 'auto' || inlineValue === 'force' || inlineValue === 'off') {
+        return inlineValue;
+    }
+    const index = args.indexOf('--team-mode');
+    if (index >= 0) {
+        const value = args[index + 1];
+        if (value === 'auto' || value === 'force' || value === 'off') {
+            return value;
+        }
+        return 'force';
+    }
+    return fallback;
+}
+export function readBranchContext(args) {
+    const branch = readBranchOption(args);
+    return branch ? { branch, branchSource: 'cli_option' } : {};
+}
+export function readBranchOption(args) {
+    return readOption(args, '--branch') ?? undefined;
+}
+export function readOptionalPositionalArgument(args) {
+    const booleanOptions = new Set(['--approved', '--json', '--no-team-mode', '--force', '--check', '--latest-only', '--all-runs', '--scaffold-docs', '--no-scaffold-docs', '--direct-safe', '--external-unknown', '--architecture', '--checkpoint']);
+    for (let index = 0; index < args.length; index += 1) {
+        const item = args[index];
+        if (!item.startsWith('--')) {
+            return item;
+        }
+        if (item.includes('=')) {
+            continue;
+        }
+        if (!booleanOptions.has(item) && args[index + 1] && !args[index + 1].startsWith('--')) {
+            index += 1;
+        }
+    }
+    return undefined;
+}
+export async function readResolvedBranch(projectRoot, args) {
+    return (await resolveSddContext(projectRoot, readBranchContext(args))).branch;
+}
+export function readWaveExecutorStrategy(args, name) {
+    const value = readOption(args, name) ?? 'fast-stop';
+    return value === 'fast-stop' || value === 'safe-continue' ? value : null;
+}
+export function readRunStatus(args, name) {
+    const value = readOption(args, name);
+    return value === 'created' || value === 'running' || value === 'completed' || value === 'blocked' || value === 'failed' || value === 'archived' ? value : null;
+}
+export function readGovernancePolicyOperation(value) {
+    return value === 'background_executor' || value === 'wave_executor' || value === 'sync_back_apply' || value === 'destructive_git' || value === 'external_interaction' || value === 'cleanup' ? value : null;
+}
+export function readTaskArtifactOptions(args) {
+    const artifacts = {};
+    for (let index = 0; index < args.length; index += 1) {
+        if (args[index] !== '--artifact') {
+            continue;
+        }
+        const value = args[index + 1];
+        const separator = value?.indexOf(':') ?? -1;
+        if (!value || separator <= 0) {
+            continue;
+        }
+        artifacts[value.slice(0, separator)] = value.slice(separator + 1);
+    }
+    return artifacts;
+}
+export function readSddResultStatus(args, name) {
+    const value = readOption(args, name);
+    return value === 'PASS' || value === 'PASS_WITH_GAPS' || value === 'FAIL' || value === 'BLOCKED' || value === 'TIMED_OUT' || value === 'CANCELLED' ? value : null;
+}
+export function readAiToolSelection(args, allowNone) {
+    const value = readOption(args, '--ai') ?? 'auto';
+    if (value === 'auto' || value === 'claude-code' || (allowNone && value === 'none')) {
+        return value;
+    }
+    throw new Error(`Unsupported --ai value: ${value}`);
+}
+//# sourceMappingURL=args.js.map