@jaimevalasek/aioson 1.3.0

package/src/commands/parallel-doctor.js

@@ -0,0 +1,437 @@
+'use strict';
+
+const fs = require('node:fs/promises');
+const path = require('node:path');
+const { validateProjectContextFile } = require('../context');
+const { exists, ensureDir } = require('../utils');
+const {
+  parseWorkers,
+  renderSharedDecisions,
+  renderAgentStatus,
+  PREREQUISITE_FILES
+} = require('./parallel-init');
+
+const DEFAULT_FIX_WORKERS = 3;
+
+function makeCheck(id, ok, severity, message, hint = '') {
+  return {
+    id,
+    ok: Boolean(ok),
+    severity,
+    message: String(message || ''),
+    hint: String(hint || '')
+  };
+}
+
+function buildLaneFilename(index) {
+  return `agent-${index}.status.md`;
+}
+
+function parseLaneIndex(fileName) {
+  const match = String(fileName || '').match(/^agent-(\d+)\.status\.md$/);
+  if (!match) return null;
+  const value = Number(match[1]);
+  if (!Number.isFinite(value) || value <= 0) return null;
+  return Math.floor(value);
+}
+
+function laneRange(count) {
+  const output = [];
+  for (let i = 1; i <= count; i += 1) {
+    output.push(i);
+  }
+  return output;
+}
+
+function summarizeChecks(checks) {
+  const passed = checks.filter((item) => item.ok).length;
+  const failed = checks.filter((item) => !item.ok && item.severity === 'error').length;
+  const warnings = checks.filter((item) => !item.ok && item.severity === 'warn').length;
+  return {
+    total: checks.length,
+    passed,
+    failed,
+    warnings
+  };
+}
+
+function formatCheckPrefix(check, t) {
+  if (check.ok) return t('parallel_doctor.prefix_ok');
+  if (check.severity === 'warn') return t('parallel_doctor.prefix_warn');
+  return t('parallel_doctor.prefix_fail');
+}
+
+async function collectPrerequisites(targetDir) {
+  const items = [];
+  for (const rel of PREREQUISITE_FILES) {
+    items.push({
+      path: rel,
+      exists: await exists(path.join(targetDir, rel))
+    });
+  }
+  return items;
+}
+
+function resolveExpectedWorkers(state, workersOption) {
+  if (workersOption !== undefined && workersOption !== null) return workersOption;
+  if (state.laneIndices.length > 0) return Math.max(...state.laneIndices);
+  return DEFAULT_FIX_WORKERS;
+}
+
+async function inspectParallelState(targetDir, workersOption) {
+  const parallelDir = path.join(targetDir, '.aioson/context/parallel');
+  const dirExists = await exists(parallelDir);
+  const entries = dirExists ? await fs.readdir(parallelDir) : [];
+  const sharedExists = entries.includes('shared-decisions.md');
+  const laneIndices = entries
+    .map(parseLaneIndex)
+    .filter((value) => value !== null)
+    .sort((a, b) => a - b);
+  const laneFiles = laneIndices.map((index) => buildLaneFilename(index));
+
+  const expectedWorkers = resolveExpectedWorkers(
+    {
+      laneIndices
+    },
+    workersOption
+  );
+  const expectedLaneIndices = laneRange(expectedWorkers);
+  const missingLaneIndices = expectedLaneIndices.filter((index) => !laneIndices.includes(index));
+
+  return {
+    parallelDir,
+    dirExists,
+    entries,
+    sharedExists,
+    laneIndices,
+    laneFiles,
+    expectedWorkers,
+    expectedLaneIndices,
+    missingLaneIndices
+  };
+}
+
+function buildChecks(context, state, prerequisites, workersOption, force, t) {
+  const checks = [];
+
+  checks.push(
+    makeCheck(
+      'context.exists',
+      context.exists,
+      'error',
+      context.exists
+        ? t('parallel_doctor.check_context_exists_ok')
+        : t('parallel_doctor.check_context_exists_missing'),
+      context.exists ? '' : t('parallel_doctor.check_context_exists_hint')
+    )
+  );
+
+  checks.push(
+    makeCheck(
+      'context.parsed',
+      context.parsed,
+      'error',
+      context.parsed
+        ? t('parallel_doctor.check_context_parsed_ok')
+        : t('parallel_doctor.check_context_parsed_invalid'),
+      context.parsed ? '' : t('parallel_doctor.check_context_parsed_hint')
+    )
+  );
+
+  const classification = String(context.data && context.data.classification ? context.data.classification : '');
+  const isMedium = classification === 'MEDIUM';
+  const classificationOk = isMedium || force;
+  checks.push(
+    makeCheck(
+      'context.classification',
+      classificationOk,
+      'error',
+      classificationOk
+        ? t('parallel_doctor.check_context_classification_ok', {
+            classification: classification || t('parallel_doctor.classification_unknown')
+          })
+        : t('parallel_doctor.check_context_classification_invalid', {
+            classification: classification || t('parallel_doctor.classification_unknown')
+          }),
+      classificationOk ? '' : t('parallel_doctor.check_context_classification_hint')
+    )
+  );
+
+  checks.push(
+    makeCheck(
+      'parallel.dir',
+      state.dirExists,
+      'error',
+      state.dirExists
+        ? t('parallel_doctor.check_parallel_dir_ok')
+        : t('parallel_doctor.check_parallel_dir_missing'),
+      state.dirExists ? '' : t('parallel_doctor.check_parallel_dir_hint')
+    )
+  );
+
+  checks.push(
+    makeCheck(
+      'parallel.shared',
+      state.sharedExists,
+      'error',
+      state.sharedExists
+        ? t('parallel_doctor.check_parallel_shared_ok')
+        : t('parallel_doctor.check_parallel_shared_missing'),
+      state.sharedExists ? '' : t('parallel_doctor.check_parallel_shared_hint')
+    )
+  );
+
+  checks.push(
+    makeCheck(
+      'parallel.lanes.present',
+      state.laneIndices.length > 0,
+      'error',
+      state.laneIndices.length > 0
+        ? t('parallel_doctor.check_lanes_present_ok', {
+            count: state.laneIndices.length
+          })
+        : t('parallel_doctor.check_lanes_present_missing'),
+      state.laneIndices.length > 0 ? '' : t('parallel_doctor.check_lanes_present_hint')
+    )
+  );
+
+  checks.push(
+    makeCheck(
+      'parallel.lanes.sequence',
+      state.missingLaneIndices.length === 0,
+      'error',
+      state.missingLaneIndices.length === 0
+        ? t('parallel_doctor.check_lanes_sequence_ok', {
+            workers: state.expectedWorkers
+          })
+        : t('parallel_doctor.check_lanes_sequence_missing', {
+            lanes: state.missingLaneIndices.join(', ')
+          }),
+      state.missingLaneIndices.length === 0 ? '' : t('parallel_doctor.check_lanes_sequence_hint')
+    )
+  );
+
+  if (workersOption !== undefined && workersOption !== null) {
+    checks.push(
+      makeCheck(
+        'parallel.workers.option',
+        state.expectedWorkers === workersOption,
+        'info',
+        t('parallel_doctor.check_workers_option', { workers: workersOption })
+      )
+    );
+  }
+
+  const missingPrereq = prerequisites.filter((item) => !item.exists).length;
+  checks.push(
+    makeCheck(
+      'parallel.prerequisites',
+      missingPrereq === 0,
+      missingPrereq === 0 ? 'info' : 'warn',
+      missingPrereq === 0
+        ? t('parallel_doctor.check_prereq_ok')
+        : t('parallel_doctor.check_prereq_missing', { count: missingPrereq }),
+      missingPrereq === 0 ? '' : t('parallel_doctor.check_prereq_hint')
+    )
+  );
+
+  return checks;
+}
+
+async function applyParallelFixes(targetDir, context, state, options) {
+  const dryRun = Boolean(options.dryRun);
+  const generatedAt = new Date().toISOString();
+  const projectName =
+    String((context.data && context.data.project_name) || '').trim() || path.basename(targetDir) || 'project';
+  const classification = String((context.data && context.data.classification) || 'MEDIUM');
+  const actions = [];
+  let changedCount = 0;
+
+  if (!state.dirExists) {
+    if (!dryRun) {
+      await ensureDir(state.parallelDir);
+    }
+    actions.push({
+      id: 'parallel_dir',
+      applied: true,
+      count: 1
+    });
+    changedCount += 1;
+  } else {
+    actions.push({
+      id: 'parallel_dir',
+      applied: false,
+      skipped: true,
+      count: 0
+    });
+  }
+
+  if (!state.sharedExists) {
+    const sharedPath = path.join(state.parallelDir, 'shared-decisions.md');
+    const content = renderSharedDecisions({
+      projectName,
+      classification,
+      workers: state.expectedWorkers,
+      generatedAt
+    });
+    if (!dryRun) {
+      await ensureDir(path.dirname(sharedPath));
+      await fs.writeFile(sharedPath, content, 'utf8');
+    }
+    actions.push({
+      id: 'shared_decisions',
+      applied: true,
+      count: 1
+    });
+    changedCount += 1;
+  } else {
+    actions.push({
+      id: 'shared_decisions',
+      applied: false,
+      skipped: true,
+      count: 0
+    });
+  }
+
+  if (state.missingLaneIndices.length > 0) {
+    for (const index of state.missingLaneIndices) {
+      const lanePath = path.join(state.parallelDir, buildLaneFilename(index));
+      const content = renderAgentStatus({
+        index,
+        generatedAt
+      });
+      if (!dryRun) {
+        await ensureDir(path.dirname(lanePath));
+        await fs.writeFile(lanePath, content, 'utf8');
+      }
+    }
+    actions.push({
+      id: 'lane_files',
+      applied: true,
+      count: state.missingLaneIndices.length
+    });
+    changedCount += state.missingLaneIndices.length;
+  } else {
+    actions.push({
+      id: 'lane_files',
+      applied: false,
+      skipped: true,
+      count: 0
+    });
+  }
+
+  return {
+    dryRun,
+    actions,
+    changedCount
+  };
+}
+
+async function runParallelDoctor({ args, options = {}, logger, t }) {
+  const targetDir = path.resolve(process.cwd(), args[0] || '.');
+  const dryRun = Boolean(options['dry-run']);
+  const fix = Boolean(options.fix);
+  const force = Boolean(options.force);
+  const workersOptionRaw = options.workers;
+  const workersOption = workersOptionRaw !== undefined ? parseWorkers(workersOptionRaw) : undefined;
+  if (workersOptionRaw !== undefined && workersOption === null) {
+    throw new Error(
+      t('parallel_doctor.invalid_workers', {
+        min: 2,
+        max: 6
+      })
+    );
+  }
+
+  const context = await validateProjectContextFile(targetDir);
+  const prerequisites = await collectPrerequisites(targetDir);
+  let state = await inspectParallelState(targetDir, workersOption);
+  let checks = buildChecks(context, state, prerequisites, workersOption, force, t);
+  let fixResult = null;
+
+  if (fix) {
+    const classification = String((context.data && context.data.classification) || '');
+    if (classification !== 'MEDIUM' && !force) {
+      throw new Error(
+        t('parallel_doctor.requires_medium', {
+          classification: classification || t('parallel_doctor.classification_unknown')
+        })
+      );
+    }
+    fixResult = await applyParallelFixes(targetDir, context, state, {
+      dryRun
+    });
+
+    state = await inspectParallelState(targetDir, workersOption);
+    checks = buildChecks(context, state, prerequisites, workersOption, force, t);
+  }
+
+  const summary = summarizeChecks(checks);
+  const output = {
+    ok: summary.failed === 0,
+    targetDir,
+    workers: state.expectedWorkers,
+    fix: {
+      enabled: fix,
+      dryRun,
+      force,
+      ...(fixResult
+        ? {
+            changedCount: fixResult.changedCount,
+            actions: fixResult.actions
+          }
+        : {})
+    },
+    state: {
+      parallelDir: state.parallelDir,
+      dirExists: state.dirExists,
+      sharedExists: state.sharedExists,
+      laneFiles: state.laneFiles,
+      laneIndices: state.laneIndices,
+      missingLaneIndices: state.missingLaneIndices
+    },
+    checks,
+    summary
+  };
+
+  if (options.json) {
+    return output;
+  }
+
+  logger.log(t('parallel_doctor.report_title', { path: targetDir }));
+  for (const check of checks) {
+    logger.log(
+      t('parallel_doctor.check_line', {
+        prefix: formatCheckPrefix(check, t),
+        id: check.id,
+        message: check.message
+      })
+    );
+    if (check.hint) {
+      logger.log(t('parallel_doctor.hint_line', { hint: check.hint }));
+    }
+  }
+  logger.log(
+    t('parallel_doctor.summary', {
+      passed: summary.passed,
+      failed: summary.failed,
+      warnings: summary.warnings
+    })
+  );
+
+  if (fixResult) {
+    logger.log(
+      dryRun
+        ? t('parallel_doctor.fix_summary_dry_run', { count: fixResult.changedCount })
+        : t('parallel_doctor.fix_summary', { count: fixResult.changedCount })
+    );
+  }
+
+  return output;
+}
+
+module.exports = {
+  runParallelDoctor,
+  parseLaneIndex,
+  summarizeChecks
+};

package/src/commands/parallel-init.js

@@ -0,0 +1,249 @@
+'use strict';
+
+const fs = require('node:fs/promises');
+const path = require('node:path');
+const { validateProjectContextFile } = require('../context');
+const { ensureDir, exists, toRelativeSafe } = require('../utils');
+const { recordRuntimeOperation } = require('../execution-gateway');
+
+const MIN_WORKERS = 2;
+const MAX_WORKERS = 6;
+const DEFAULT_WORKERS = 3;
+const PREREQUISITE_FILES = [
+  '.aioson/context/discovery.md',
+  '.aioson/context/architecture.md',
+  '.aioson/context/prd.md'
+];
+
+function normalizeClassification(value) {
+  return String(value || '').trim().toUpperCase();
+}
+
+function parseWorkers(value) {
+  if (value === undefined || value === null || value === '') return DEFAULT_WORKERS;
+  const num = Number(value);
+  if (!Number.isFinite(num)) return null;
+  const normalized = Math.floor(num);
+  if (normalized < MIN_WORKERS || normalized > MAX_WORKERS) return null;
+  return normalized;
+}
+
+function renderSharedDecisions(input) {
+  return `# Shared Decisions
+
+## Session
+- Project: ${input.projectName}
+- Classification: ${input.classification}
+- Workers: ${input.workers}
+- Generated at: ${input.generatedAt}
+
+## Protocol
+- Record only decisions that affect more than one parallel lane.
+- When a decision changes a contract, update all impacted lane files.
+- Keep entries concise and include rationale plus impact.
+
+## Decision Log
+| time | decision | rationale | impact |
+|------|----------|-----------|--------|
+| ${input.generatedAt} | Parallel workspace initialized | Baseline orchestration context created | Ready for @orchestrator assignment |
+`;
+}
+
+function renderAgentStatus(input) {
+  const lane = `agent-${input.index}`;
+  return `# Parallel Lane Status - ${lane}
+
+## Metadata
+- lane: ${lane}
+- role: @dev
+- owner: [unassigned]
+- status: pending
+- priority: medium
+- updated_at: ${input.generatedAt}
+
+## Scope
+- [define module or feature boundary]
+
+## Dependencies
+- [list dependencies on other lanes or shared decisions]
+
+## Deliverables
+- [ ] Code changes completed
+- [ ] Self-check completed
+- [ ] Handoff note written
+
+## Blockers
+- [none]
+
+## Notes
+- Created by \`aioson parallel:init\`.
+`;
+}
+
+async function collectPrerequisites(targetDir) {
+  const items = [];
+  for (const rel of PREREQUISITE_FILES) {
+    const abs = path.join(targetDir, rel);
+    items.push({
+      path: rel,
+      exists: await exists(abs)
+    });
+  }
+  return items;
+}
+
+function buildTargetFiles(targetDir, workers) {
+  const parallelDir = path.join(targetDir, '.aioson/context/parallel');
+  const files = [path.join(parallelDir, 'shared-decisions.md')];
+  for (let i = 1; i <= workers; i += 1) {
+    files.push(path.join(parallelDir, `agent-${i}.status.md`));
+  }
+  return files;
+}
+
+async function runParallelInit({ args, options = {}, logger, t }) {
+  const targetDir = path.resolve(process.cwd(), args[0] || '.');
+  const dryRun = Boolean(options['dry-run']);
+  const force = Boolean(options.force);
+  const workers = parseWorkers(options.workers);
+
+  if (workers === null) {
+    throw new Error(
+      t('parallel_init.invalid_workers', {
+        min: MIN_WORKERS,
+        max: MAX_WORKERS
+      })
+    );
+  }
+
+  const context = await validateProjectContextFile(targetDir);
+  const contextPath = path.join(targetDir, '.aioson/context/project.context.md');
+  if (!context.exists) {
+    throw new Error(t('parallel_init.context_missing', { path: contextPath }));
+  }
+  if (!context.parsed) {
+    throw new Error(t('parallel_init.context_invalid', { path: contextPath }));
+  }
+
+  const classification = normalizeClassification(
+    options.classification || (context.data && context.data.classification) || ''
+  );
+  if (classification !== 'MEDIUM' && !force) {
+    throw new Error(
+      t('parallel_init.requires_medium', {
+        classification: classification || t('parallel_init.classification_unknown')
+      })
+    );
+  }
+
+  const generatedAt = new Date().toISOString();
+  const projectName =
+    String((context.data && context.data.project_name) || '').trim() || path.basename(targetDir) || 'project';
+  const prerequisiteChecks = await collectPrerequisites(targetDir);
+  const missingPrerequisites = prerequisiteChecks
+    .filter((item) => !item.exists)
+    .map((item) => item.path);
+
+  const targetFiles = buildTargetFiles(targetDir, workers);
+  const existingFiles = [];
+  for (const absPath of targetFiles) {
+    if (await exists(absPath)) {
+      existingFiles.push(toRelativeSafe(targetDir, absPath));
+    }
+  }
+
+  if (existingFiles.length > 0 && !force) {
+    throw new Error(
+      t('parallel_init.already_exists', {
+        count: existingFiles.length
+      })
+    );
+  }
+
+  if (!dryRun) {
+    const parallelDir = path.join(targetDir, '.aioson/context/parallel');
+    await ensureDir(parallelDir);
+
+    const sharedContent = renderSharedDecisions({
+      projectName,
+      classification: classification || 'MEDIUM',
+      workers,
+      generatedAt
+    });
+    await fs.writeFile(path.join(parallelDir, 'shared-decisions.md'), sharedContent, 'utf8');
+
+    for (let i = 1; i <= workers; i += 1) {
+      const statusContent = renderAgentStatus({ index: i, generatedAt });
+      await fs.writeFile(path.join(parallelDir, `agent-${i}.status.md`), statusContent, 'utf8');
+    }
+  }
+
+  const output = {
+    ok: true,
+    targetDir,
+    classification: classification || 'MEDIUM',
+    workers,
+    dryRun,
+    force,
+    generatedAt,
+    files: targetFiles.map((absPath) => toRelativeSafe(targetDir, absPath)),
+    existingFiles,
+    prerequisites: prerequisiteChecks,
+    missingPrerequisites
+  };
+
+  if (!dryRun) {
+    output.runtime = await recordRuntimeOperation(targetDir, {
+      agentName: 'orchestrator',
+      source: 'orchestration',
+      sessionKey: 'parallel:workspace',
+      title: 'Parallel orchestration workspace',
+      goal: 'Prepare and manage parallel development lanes',
+      runTitle: 'parallel:init',
+      message: 'Parallel workspace initialization started',
+      summary: `Parallel workspace initialized with ${workers} lanes`,
+      eventType: 'parallel.initialized',
+      phase: 'parallel',
+      payload: {
+        command: 'parallel:init',
+        classification: output.classification,
+        workers,
+        files: output.files,
+        missingPrerequisites
+      }
+    });
+  }
+
+  if (options.json) {
+    return output;
+  }
+
+  logger.log(
+    dryRun
+      ? t('parallel_init.dry_run_prepared', { path: path.join(targetDir, '.aioson/context/parallel') })
+      : t('parallel_init.prepared', { path: path.join(targetDir, '.aioson/context/parallel') })
+  );
+  logger.log(t('parallel_init.workers_count', { count: workers }));
+  logger.log(t('parallel_init.files_count', { count: output.files.length }));
+  if (missingPrerequisites.length > 0) {
+    logger.log(
+      t('parallel_init.missing_prereq_count', {
+        count: missingPrerequisites.length
+      })
+    );
+  }
+  for (const file of output.files) {
+    logger.log(t('parallel_init.file_line', { file }));
+  }
+
+  return output;
+}
+
+module.exports = {
+  runParallelInit,
+  parseWorkers,
+  normalizeClassification,
+  renderSharedDecisions,
+  renderAgentStatus,
+  PREREQUISITE_FILES
+};