@adityaaria/agent-os 1.0.0

package/scripts/lib/cli-utils.mjs

@@ -0,0 +1,148 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+/**
+ * Creates a CLI argument parser from process.argv.
+ * @param {string[]} argv - process.argv.slice(2)
+ */
+export function createCli(argv) {
+  const args = [...argv];
+
+  function hasFlag(name) {
+    return args.includes(name);
+  }
+
+  function takeOption(name) {
+    const index = args.indexOf(name);
+    if (index === -1) return null;
+    const value = args[index + 1] ?? null;
+    args.splice(index, 2);
+    return value;
+  }
+
+  return { hasFlag, takeOption, args };
+}
+
+/**
+ * Returns true if the user passed --help or -h.
+ * @param {string[]} argv
+ */
+export function wantsHelp(argv) {
+  return argv.includes('--help') || argv.includes('-h');
+}
+
+/**
+ * Renders a formatted help text block and exits cleanly.
+ * @param {object} config
+ * @param {string} config.command - The subcommand name
+ * @param {string} config.description - One-line description
+ * @param {string[]} config.usage - Usage lines (one per variant)
+ * @param {Array<{flag: string, desc: string, default?: string}>} [config.required] - Required flags
+ * @param {Array<{flag: string, desc: string, default?: string}>} [config.options] - Optional flags
+ * @param {string[]} [config.examples] - Example command lines
+ */
+export function showHelp(config) {
+  const lines = [];
+  lines.push(`agent-os ${config.command} — ${config.description}`);
+  lines.push('');
+
+  lines.push('Usage:');
+  for (const usage of config.usage) {
+    lines.push(`  ${usage}`);
+  }
+  lines.push('');
+
+  if (config.required?.length) {
+    lines.push('Required:');
+    const maxLen = Math.max(...config.required.map((o) => o.flag.length));
+    for (const opt of config.required) {
+      lines.push(`  ${opt.flag.padEnd(maxLen + 2)} ${opt.desc}`);
+    }
+    lines.push('');
+  }
+
+  if (config.options?.length) {
+    lines.push('Options:');
+    const maxLen = Math.max(...config.options.map((o) => o.flag.length));
+    for (const opt of config.options) {
+      const defaultStr = opt.default ? `  [default: ${opt.default}]` : '';
+      lines.push(`  ${opt.flag.padEnd(maxLen + 2)} ${opt.desc}${defaultStr}`);
+    }
+    lines.push('');
+  }
+
+  if (config.examples?.length) {
+    lines.push('Examples:');
+    for (const example of config.examples) {
+      lines.push(`  ${example}`);
+    }
+    lines.push('');
+  }
+
+  console.log(lines.join('\n'));
+  process.exit(0);
+}
+
+/**
+ * Collects multiple validation errors, then displays them all at once with
+ * a usage example, and exits with code 1.
+ * @param {string[]} errors - List of error messages
+ * @param {string} [example] - Example command to show
+ * @param {string} [command] - Command name for --help hint
+ */
+export function failAll(errors, example, command) {
+  if (errors.length === 0) return;
+
+  console.error(`\n✗ ERROR: ${errors.length} issue${errors.length > 1 ? 's' : ''} found:\n`);
+  for (const error of errors) {
+    console.error(`  • ${error}`);
+  }
+
+  if (example) {
+    console.error(`\nExample:`);
+    console.error(`  ${example}`);
+  }
+
+  if (command) {
+    console.error(`\nRun 'agent-os ${command} --help' for full usage.`);
+  }
+
+  console.error('');
+  process.exit(1);
+}
+
+/**
+ * Simple single-error fail (for runtime errors after validation).
+ * @param {string} message
+ */
+export function fail(message) {
+  console.error(message);
+  process.exit(1);
+}
+
+/**
+ * Resolves a CLI flag value with a smart default.
+ * If the value is already set (from CLI), returns it.
+ * Otherwise checks if the default file/directory exists and returns it.
+ * @param {string|null} value - The CLI-provided value
+ * @param {string} defaultPath - The default path to try
+ * @returns {string|null}
+ */
+export function resolveDefault(value, defaultPath) {
+  if (value) return value;
+  const resolved = path.resolve(process.cwd(), defaultPath);
+  if (fs.existsSync(resolved)) return resolved;
+  return null;
+}
+
+/**
+ * Resolves a default that does not require the file to exist yet
+ * (e.g., state files that will be created on first run).
+ * @param {string|null} value
+ * @param {string} defaultPath
+ * @returns {string|null}
+ */
+export function resolveDefaultPath(value, defaultPath) {
+  if (value) return value;
+  return defaultPath;
+}

package/scripts/lib/run-utils.mjs

@@ -0,0 +1,185 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+export const runStatuses = ['pending', 'running', 'passed', 'failed', 'blocked'];
+
+export function buildStatusCounts(steps) {
+  const counts = Object.fromEntries(runStatuses.map((status) => [status, 0]));
+  for (const step of steps) {
+    if (counts[step.status] === undefined) counts[step.status] = 0;
+    counts[step.status]++;
+  }
+  return counts;
+}
+
+export function deriveRunStatus(steps) {
+  const counts = buildStatusCounts(steps);
+  if (counts.failed > 0 || counts.blocked > 0) return 'failed';
+  if (counts.running > 0) return 'running';
+  if (steps.length > 0 && counts.passed === steps.length) return 'complete';
+  return 'pending';
+}
+
+function extractSection(content, sectionName) {
+  const regex = new RegExp(`^# ${sectionName}\\n([\\s\\S]*?)(?:\\n# |$)`, 'm');
+  const match = content.match(regex);
+  return match ? match[1].trim() : null;
+}
+
+export function summarizeRun(runDir) {
+  const planPath = path.join(runDir, 'plan.json');
+  const stepsPath = path.join(runDir, 'steps.json');
+  if (!fs.existsSync(planPath) || !fs.existsSync(stepsPath)) return null;
+
+  const plan = JSON.parse(fs.readFileSync(planPath, 'utf8'));
+  const steps = JSON.parse(fs.readFileSync(stepsPath, 'utf8'));
+
+  const reportPath = path.join(runDir, 'master-report.md');
+  let reportDetails = null;
+  if (fs.existsSync(reportPath)) {
+    const content = fs.readFileSync(reportPath, 'utf8');
+    reportDetails = {
+      evidence: extractSection(content, 'Evidence')
+    };
+  }
+
+  return {
+    runDir,
+    runId: plan.run?.id ?? path.basename(runDir),
+    status: deriveRunStatus(steps),
+    total: steps.length,
+    counts: buildStatusCounts(steps),
+    plan,
+    steps,
+    reportDetails
+  };
+}
+
+export function collectRuns(runRoot) {
+  const absoluteRunRoot = path.resolve(process.cwd(), runRoot);
+  if (!fs.existsSync(absoluteRunRoot)) {
+    throw new Error(`Run root not found: ${absoluteRunRoot}`);
+  }
+
+  return fs.readdirSync(absoluteRunRoot, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => summarizeRun(path.join(absoluteRunRoot, entry.name)))
+    .filter(Boolean)
+    .sort((a, b) => a.runId.localeCompare(b.runId));
+}
+
+export function collectRun(runDir) {
+  const absoluteRunDir = path.resolve(process.cwd(), runDir);
+  const summary = summarizeRun(absoluteRunDir);
+  if (!summary) {
+    throw new Error(`Run directory is missing plan.json or steps.json: ${absoluteRunDir}`);
+  }
+  return summary;
+}
+
+export function loadReportChannel(channelConfig, channelName) {
+  const absoluteConfigPath = path.resolve(process.cwd(), channelConfig);
+  if (!fs.existsSync(absoluteConfigPath)) {
+    throw new Error(`Channel config not found: ${absoluteConfigPath}`);
+  }
+
+  const config = JSON.parse(fs.readFileSync(absoluteConfigPath, 'utf8'));
+  const channel = config.channels?.[channelName];
+  if (!channel) {
+    throw new Error(`Report channel not found: ${channelName}`);
+  }
+
+  return {
+    name: channelName,
+    configPath: absoluteConfigPath,
+    outputBaseDir: path.dirname(absoluteConfigPath),
+    channel
+  };
+}
+
+export function assertEnabledChannel(channelContext) {
+  if (channelContext.channel.enabled === false) {
+    throw new Error(`Report channel is disabled: ${channelContext.name}`);
+  }
+}
+
+function escapeCsvValue(value) {
+  const text = String(value ?? '');
+  if (!/[",\n\r]/.test(text)) return text;
+  return `"${text.replaceAll('"', '""')}"`;
+}
+
+export function renderRunSummariesCsv(summaries) {
+  const rows = Array.isArray(summaries) ? summaries : [summaries];
+  const headers = ['runId', 'status', 'total', 'pending', 'running', 'passed', 'failed', 'blocked', 'runDir'];
+  const lines = [headers.join(',')];
+
+  for (const summary of rows) {
+    lines.push([
+      summary.runId,
+      summary.status,
+      summary.total,
+      summary.counts.pending ?? 0,
+      summary.counts.running ?? 0,
+      summary.counts.passed ?? 0,
+      summary.counts.failed ?? 0,
+      summary.counts.blocked ?? 0,
+      summary.runDir
+    ].map(escapeCsvValue).join(','));
+  }
+
+  return `${lines.join('\n')}\n`;
+}
+
+export function renderReport(plan) {
+  const sectionBody = {
+    'Executive Summary': [
+      `Trigger: ${plan.trigger}`,
+      `Prompt: ${plan.prompt}`,
+      `Validation Status: ${plan.validation.status}`
+    ],
+    Scope: [
+      `Mode: ${plan.mode}`,
+      `Skill Chain: ${plan.skillChain.join(' -> ')}`
+    ],
+    'Knowledge Confidence': [
+      'Score: N/A. Reason: Execution stub does not inspect project knowledge.'
+    ],
+    'Knowledge Classification': [
+      'Classification: N/A. Reason: Execution stub only renders a validated plan.'
+    ],
+    'Traceability Matrix': [
+      '| Step | Skill | Depends On | Status |',
+      '| ---- | ----- | ---------- | ------ |',
+      ...plan.executionPlan.map((step) => (
+        `| ${step.step} | ${step.skill} | ${step.dependsOn.join(', ') || 'N/A. Reason: First step.'} | ${step.status} |`
+      ))
+    ],
+    Evidence: plan.executionEvidence?.length > 0
+      ? plan.executionEvidence
+      : ['N/A. Reason: Skills were not executed by this stub.'],
+    'Root Cause': [
+      'N/A. Reason: Root cause is produced by the executing skill.'
+    ],
+    Impact: [
+      'N/A. Reason: Impact is produced by the executing skill.'
+    ],
+    Recommendation: [
+      'Quick Win: Review this validated execution plan before running skills.',
+      'Long Term Improvement: Replace this stub with gated skill execution.'
+    ],
+    'Quality Gate': [
+      `Plan Validation: ${plan.validation.status}`
+    ],
+    'Enterprise Readiness': [
+      'N/A. Reason: Enterprise readiness is assessed after execution evidence exists.'
+    ],
+    'Final Decision': [
+      plan.validation.status === 'PASS' ? 'CONDITIONAL PASS' : 'FAIL'
+    ]
+  };
+
+  return plan.masterReport.sections
+    .map((section) => `# ${section}\n${sectionBody[section].join('\n')}`)
+    .join('\n\n') + '\n';
+}

package/scripts/lib/telegram-audit-log.mjs

@@ -0,0 +1,50 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+/**
+ * Appends an audit entry to the telegram audit log JSONL file.
+ *
+ * @param {Object} options
+ * @param {string} options.runRoot - The absolute path to the .agent-os/runs or equivalent root directory
+ * @param {Object} options.entry - The audit log entry to append
+ */
+export function appendAuditEntry({ runRoot, entry }) {
+  if (!runRoot) return;
+
+  const logPath = path.join(runRoot, '..', 'project', 'reports', 'telegram-audit-log.jsonl');
+  
+  // Ensure directory exists
+  fs.mkdirSync(path.dirname(logPath), { recursive: true });
+  
+  // Prepare entry with timestamp if not provided
+  const logEntry = {
+    timestamp: new Date().toISOString(),
+    ...entry
+  };
+  
+  // Append as JSONL
+  fs.appendFileSync(logPath, `${JSON.stringify(logEntry)}\n`, 'utf8');
+}
+
+/**
+ * Reads and parses the telegram audit log.
+ *
+ * @param {Object} options
+ * @param {string} options.runRoot - The absolute path to the .agent-os/runs or equivalent root directory
+ * @returns {Array<Object>} The parsed audit log entries
+ */
+export function readAuditLog({ runRoot }) {
+  if (!runRoot) return [];
+  
+  const logPath = path.join(runRoot, '..', 'project', 'reports', 'telegram-audit-log.jsonl');
+  if (!fs.existsSync(logPath)) {
+    return [];
+  }
+  
+  const content = fs.readFileSync(logPath, 'utf8');
+  return content
+    .split('\n')
+    .map(line => line.trim())
+    .filter(Boolean)
+    .map(line => JSON.parse(line));
+}