sentinelayer-cli 0.1.0

package/src/spec/regenerate.js

@@ -0,0 +1,237 @@
+import pc from "picocolors";
+
+function normalizeHeadingKey(rawHeading) {
+  return String(rawHeading || "")
+    .replace(/\s+/g, " ")
+    .trim()
+    .toLowerCase();
+}
+
+function normalizeSectionBody(lines) {
+  return lines
+    .map((line) => String(line || ""))
+    .join("\n")
+    .replace(/\s+$/gm, "")
+    .trim();
+}
+
+export function inferTemplateFromSpec(markdown) {
+  const match = String(markdown || "").match(/^Template:\s*([a-z0-9-]+)/im);
+  return match ? String(match[1] || "").trim() : "";
+}
+
+export function parseSpecSections(markdown) {
+  const lines = String(markdown || "").split(/\r?\n/);
+  const preambleLines = [];
+  const sections = [];
+  let activeSection = null;
+
+  for (const line of lines) {
+    const heading = line.match(/^##\s+(.+)$/);
+    if (heading) {
+      if (activeSection) {
+        sections.push(activeSection);
+      }
+      activeSection = {
+        headingLine: line,
+        headingText: String(heading[1] || "").trim(),
+        headingKey: normalizeHeadingKey(heading[1]),
+        lines: [line],
+      };
+      continue;
+    }
+
+    if (!activeSection) {
+      preambleLines.push(line);
+      continue;
+    }
+    activeSection.lines.push(line);
+  }
+
+  if (activeSection) {
+    sections.push(activeSection);
+  }
+
+  return {
+    preamble: preambleLines.join("\n").trimEnd(),
+    sections: sections.map((section) => ({
+      headingLine: section.headingLine,
+      headingText: section.headingText,
+      headingKey: section.headingKey,
+      lines: section.lines,
+      body: normalizeSectionBody(section.lines.slice(1)),
+      manualTagged: section.lines.some((line) =>
+        /sentinelayer:manual|\[manual\]/i.test(String(line || ""))
+      ),
+    })),
+  };
+}
+
+export function mergeSpecRegeneration({
+  existingMarkdown,
+  regeneratedMarkdown,
+  preserveManual = true,
+} = {}) {
+  const existing = parseSpecSections(existingMarkdown);
+  const regenerated = parseSpecSections(regeneratedMarkdown);
+
+  const existingByHeading = new Map();
+  for (const section of existing.sections) {
+    if (!existingByHeading.has(section.headingKey)) {
+      existingByHeading.set(section.headingKey, section);
+    }
+  }
+
+  const usedExisting = new Set();
+  const mergedSections = [];
+  const summary = {
+    preservedManualSections: [],
+    replacedGeneratedSections: [],
+    addedGeneratedSections: [],
+    preservedManualOnlySections: [],
+    preservedManualPreamble: false,
+  };
+
+  for (const generatedSection of regenerated.sections) {
+    const existingSection = existingByHeading.get(generatedSection.headingKey);
+    if (!existingSection) {
+      mergedSections.push(generatedSection.lines.join("\n").trimEnd());
+      summary.addedGeneratedSections.push(generatedSection.headingText);
+      continue;
+    }
+
+    usedExisting.add(existingSection.headingKey);
+    const contentDiffers = existingSection.body !== generatedSection.body;
+    const preserveCurrent = preserveManual && (existingSection.manualTagged || contentDiffers);
+
+    if (preserveCurrent) {
+      mergedSections.push(existingSection.lines.join("\n").trimEnd());
+      summary.preservedManualSections.push(existingSection.headingText);
+      continue;
+    }
+
+    mergedSections.push(generatedSection.lines.join("\n").trimEnd());
+    summary.replacedGeneratedSections.push(generatedSection.headingText);
+  }
+
+  if (preserveManual) {
+    for (const existingSection of existing.sections) {
+      if (usedExisting.has(existingSection.headingKey)) {
+        continue;
+      }
+      mergedSections.push(existingSection.lines.join("\n").trimEnd());
+      summary.preservedManualOnlySections.push(existingSection.headingText);
+    }
+  }
+
+  const preambleDiffers = existing.preamble.trim() !== regenerated.preamble.trim();
+  const mergedPreamble =
+    preserveManual && preambleDiffers ? existing.preamble.trimEnd() : regenerated.preamble.trimEnd();
+  if (preserveManual && preambleDiffers && existing.preamble.trim()) {
+    summary.preservedManualPreamble = true;
+  }
+
+  const mergedMarkdown = `${[mergedPreamble, mergedSections.join("\n\n")]
+    .filter((segment) => String(segment || "").trim().length > 0)
+    .join("\n\n")
+    .trimEnd()}\n`;
+
+  return {
+    mergedMarkdown,
+    changed: String(existingMarkdown || "").trimEnd() !== mergedMarkdown.trimEnd(),
+    summary,
+  };
+}
+
+function buildLcsTable(a, b) {
+  const table = Array.from({ length: a.length + 1 }, () => new Array(b.length + 1).fill(0));
+  for (let i = a.length - 1; i >= 0; i -= 1) {
+    for (let j = b.length - 1; j >= 0; j -= 1) {
+      if (a[i] === b[j]) {
+        table[i][j] = table[i + 1][j + 1] + 1;
+      } else {
+        table[i][j] = Math.max(table[i + 1][j], table[i][j + 1]);
+      }
+    }
+  }
+  return table;
+}
+
+export function buildLineDiff(beforeMarkdown, afterMarkdown) {
+  const beforeLines = String(beforeMarkdown || "").split(/\r?\n/);
+  const afterLines = String(afterMarkdown || "").split(/\r?\n/);
+  const lcs = buildLcsTable(beforeLines, afterLines);
+  const operations = [];
+  let i = 0;
+  let j = 0;
+
+  while (i < beforeLines.length && j < afterLines.length) {
+    if (beforeLines[i] === afterLines[j]) {
+      operations.push({ type: "context", line: beforeLines[i] });
+      i += 1;
+      j += 1;
+      continue;
+    }
+    if (lcs[i + 1][j] >= lcs[i][j + 1]) {
+      operations.push({ type: "remove", line: beforeLines[i] });
+      i += 1;
+    } else {
+      operations.push({ type: "add", line: afterLines[j] });
+      j += 1;
+    }
+  }
+
+  while (i < beforeLines.length) {
+    operations.push({ type: "remove", line: beforeLines[i] });
+    i += 1;
+  }
+  while (j < afterLines.length) {
+    operations.push({ type: "add", line: afterLines[j] });
+    j += 1;
+  }
+
+  let added = 0;
+  let removed = 0;
+  for (const op of operations) {
+    if (op.type === "add") {
+      added += 1;
+    } else if (op.type === "remove") {
+      removed += 1;
+    }
+  }
+
+  return {
+    operations,
+    added,
+    removed,
+    changed: added > 0 || removed > 0,
+  };
+}
+
+export function renderLineDiff(diff, options = {}) {
+  const plain = Boolean(options.plain);
+  const maxLines = Number(options.maxLines || 0);
+  const hasLimit = Number.isFinite(maxLines) && maxLines > 0;
+  const rows = [];
+
+  for (const op of diff.operations) {
+    if (op.type === "add") {
+      rows.push(plain ? `+ ${op.line}` : pc.green(`+ ${op.line}`));
+    } else if (op.type === "remove") {
+      rows.push(plain ? `- ${op.line}` : pc.red(`- ${op.line}`));
+    } else {
+      rows.push(`  ${op.line}`);
+    }
+  }
+
+  if (!hasLimit || rows.length <= maxLines) {
+    return rows.join("\n");
+  }
+
+  const headCount = Math.max(1, Math.floor(maxLines / 2));
+  const tailCount = Math.max(1, maxLines - headCount - 1);
+  const omitted = rows.length - headCount - tailCount;
+  return [...rows.slice(0, headCount), `... (${omitted} lines omitted) ...`, ...rows.slice(-tailCount)].join(
+    "\n"
+  );
+}

package/src/spec/templates.js

@@ -0,0 +1,91 @@
+export const SPEC_TEMPLATES = Object.freeze([
+  {
+    id: "saas-app",
+    name: "SaaS App",
+    description: "Web SaaS product with backend APIs and admin operations.",
+    architectureFocus: [
+      "Service/API boundaries and data contracts",
+      "Tenant and authorization boundaries",
+      "Observability and rollback paths",
+    ],
+    securityChecklist: [
+      "AuthN/AuthZ controls are explicit",
+      "Secrets and tokens are never hardcoded",
+      "Audit logging covers critical admin actions",
+      "Rate limits and abuse controls are defined",
+    ],
+  },
+  {
+    id: "api-service",
+    name: "API Service",
+    description: "Backend-first service with deterministic API behavior and reliability guardrails.",
+    architectureFocus: [
+      "Request validation and response schema contracts",
+      "Resilience strategy (timeouts, retries, idempotency)",
+      "Deployment and migration safety",
+    ],
+    securityChecklist: [
+      "Input validation on all external boundaries",
+      "AuthN/AuthZ policy enforced per endpoint",
+      "Dependency and supply-chain controls",
+      "Structured error handling avoids sensitive leakage",
+    ],
+  },
+  {
+    id: "cli-tool",
+    name: "CLI Tool",
+    description: "Deterministic developer CLI with predictable outputs and CI automation support.",
+    architectureFocus: [
+      "Subcommand and flag ergonomics",
+      "Idempotent filesystem operations",
+      "Machine-readable output contracts",
+    ],
+    securityChecklist: [
+      "Safe path handling and traversal guards",
+      "No secret echo in logs or command history",
+      "Destructive actions require explicit confirmation/gates",
+      "Budget and timeout controls for long-running tasks",
+    ],
+  },
+  {
+    id: "library",
+    name: "Library",
+    description: "Reusable package focused on API stability and testability.",
+    architectureFocus: [
+      "Public API surface and versioning strategy",
+      "Backward compatibility guarantees",
+      "Reference tests and fixtures",
+    ],
+    securityChecklist: [
+      "Input sanitization and safe defaults",
+      "Dependency vulnerability monitoring",
+      "Breaking changes require migration guidance",
+      "Error messages avoid exposing internals",
+    ],
+  },
+  {
+    id: "mobile-app",
+    name: "Mobile App",
+    description: "Mobile-first client with secure device/session handling and backend integration.",
+    architectureFocus: [
+      "Offline behavior and sync rules",
+      "Auth/session lifecycle on-device",
+      "API contract and version coordination",
+    ],
+    securityChecklist: [
+      "Secure token storage and rotation",
+      "PII handling and redaction policies",
+      "Transport security and certificate pinning strategy",
+      "Crash/log pipelines avoid sensitive user data",
+    ],
+  },
+]);
+
+export function getTemplateById(templateId) {
+  const normalized = String(templateId || "").trim().toLowerCase();
+  return SPEC_TEMPLATES.find((template) => template.id === normalized) || null;
+}
+
+export function getDefaultTemplate() {
+  return getTemplateById("api-service");
+}

package/src/swarm/dashboard.js

@@ -0,0 +1,247 @@
+import fsp from "node:fs/promises";
+import path from "node:path";
+
+import { resolveOutputRoot } from "../config/service.js";
+
+function normalizeString(value) {
+  return String(value || "").trim();
+}
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+async function pathExists(targetPath) {
+  try {
+    await fsp.access(targetPath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function toAgentRows(summary = {}, events = []) {
+  const byAgent = new Map();
+  for (const agentId of summary.selectedAgents || []) {
+    byAgent.set(agentId, {
+      agentId,
+      eventCount: 0,
+      lastEventType: "",
+      lastTimestamp: "",
+      lastMessage: "",
+      status: summary.completed ? "completed" : "running",
+    });
+  }
+
+  for (const event of events) {
+    const agentId = normalizeString(event.agentId || "unknown").toLowerCase() || "unknown";
+    const current = byAgent.get(agentId) || {
+      agentId,
+      eventCount: 0,
+      lastEventType: "",
+      lastTimestamp: "",
+      lastMessage: "",
+      status: summary.completed ? "completed" : "running",
+    };
+    current.eventCount += 1;
+    current.lastEventType = normalizeString(event.eventType);
+    current.lastTimestamp = normalizeString(event.timestamp);
+    current.lastMessage = normalizeString(event.message);
+    byAgent.set(agentId, current);
+  }
+
+  if (!summary.completed && summary.stop?.blocking) {
+    const omar = byAgent.get("omar") || {
+      agentId: "omar",
+      eventCount: 0,
+      lastEventType: "",
+      lastTimestamp: "",
+      lastMessage: "",
+      status: "stopped",
+    };
+    omar.status = "stopped";
+    byAgent.set("omar", omar);
+  }
+
+  return [...byAgent.values()].sort((left, right) => left.agentId.localeCompare(right.agentId));
+}
+
+export async function resolveSwarmRuntimeFiles({
+  targetPath = ".",
+  outputDir = "",
+  runId = "",
+  env,
+  homeDir,
+} = {}) {
+  const normalizedTargetPath = path.resolve(String(targetPath || "."));
+  const outputRoot = await resolveOutputRoot({
+    cwd: normalizedTargetPath,
+    outputDirOverride: outputDir,
+    env,
+    homeDir,
+  });
+  const swarmsDirectory = path.join(outputRoot, "swarms");
+  const requestedRunId = normalizeString(runId);
+  if (requestedRunId) {
+    const runtimeDirectory = path.join(swarmsDirectory, requestedRunId, "runtime");
+    return {
+      outputRoot,
+      runId: requestedRunId,
+      runtimeDirectory,
+      runtimeJsonPath: path.join(runtimeDirectory, "SWARM_RUNTIME.json"),
+      runtimeEventsPath: path.join(runtimeDirectory, "events.ndjson"),
+    };
+  }
+
+  const entries = await fsp.readdir(swarmsDirectory, { withFileTypes: true });
+  const runtimeCandidates = [];
+  for (const entry of entries) {
+    if (!entry.isDirectory()) {
+      continue;
+    }
+    if (!entry.name.startsWith("swarm-runtime-")) {
+      continue;
+    }
+    const runtimeDirectory = path.join(swarmsDirectory, entry.name, "runtime");
+    const runtimeJsonPath = path.join(runtimeDirectory, "SWARM_RUNTIME.json");
+    if (!(await pathExists(runtimeJsonPath))) {
+      continue;
+    }
+    const stats = await fsp.stat(runtimeJsonPath);
+    runtimeCandidates.push({
+      runId: entry.name,
+      runtimeDirectory,
+      runtimeJsonPath,
+      runtimeEventsPath: path.join(runtimeDirectory, "events.ndjson"),
+      mtimeMs: stats.mtimeMs,
+    });
+  }
+
+  if (runtimeCandidates.length === 0) {
+    throw new Error("No swarm runtime artifacts found.");
+  }
+
+  runtimeCandidates.sort((left, right) => right.mtimeMs - left.mtimeMs);
+  const latest = runtimeCandidates[0];
+  return {
+    outputRoot,
+    runId: latest.runId,
+    runtimeDirectory: latest.runtimeDirectory,
+    runtimeJsonPath: latest.runtimeJsonPath,
+    runtimeEventsPath: latest.runtimeEventsPath,
+  };
+}
+
+export async function loadSwarmDashboardSnapshot({
+  targetPath = ".",
+  outputDir = "",
+  runId = "",
+  env,
+  homeDir,
+} = {}) {
+  const files = await resolveSwarmRuntimeFiles({
+    targetPath,
+    outputDir,
+    runId,
+    env,
+    homeDir,
+  });
+  const summary = JSON.parse(await fsp.readFile(files.runtimeJsonPath, "utf-8"));
+  const eventsRaw = await fsp.readFile(files.runtimeEventsPath, "utf-8");
+  const events = String(eventsRaw || "")
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter(Boolean)
+    .map((line) => JSON.parse(line));
+
+  const snapshot = {
+    runId: summary.runId,
+    planRunId: summary.planRunId,
+    scenario: summary.scenario,
+    engine: summary.engine,
+    execute: Boolean(summary.execute),
+    completed: Boolean(summary.completed),
+    stop: summary.stop || { stopClass: "NONE", reason: "", blocking: false },
+    usage: summary.usage || {},
+    eventCount: events.length,
+    runtimeJsonPath: files.runtimeJsonPath,
+    runtimeEventsPath: files.runtimeEventsPath,
+    runtimeDirectory: files.runtimeDirectory,
+    generatedAt: new Date().toISOString(),
+    agentRows: toAgentRows(summary, events),
+    recentEvents: events.slice(-10),
+  };
+
+  return snapshot;
+}
+
+export function renderSwarmDashboard(snapshot = {}) {
+  const header = [
+    `Swarm run: ${snapshot.runId}`,
+    `Scenario: ${snapshot.scenario}`,
+    `Status: ${snapshot.completed ? "completed" : "running"}${snapshot.stop?.blocking ? ` (${snapshot.stop.stopClass})` : ""}`,
+    `Usage: tokens=${snapshot.usage.outputTokens || 0} tools=${snapshot.usage.toolCalls || 0} runtime_ms=${snapshot.usage.durationMs || 0} cost_usd=${snapshot.usage.costUsd || 0}`,
+  ].join("\n");
+
+  const rows = (snapshot.agentRows || [])
+    .map(
+      (row) =>
+        `- ${row.agentId} status=${row.status} events=${row.eventCount} last=${row.lastEventType || "n/a"}`
+    )
+    .join("\n");
+
+  return `${header}\nAgents:\n${rows || "- none"}`;
+}
+
+export async function watchSwarmDashboard({
+  targetPath = ".",
+  outputDir = "",
+  runId = "",
+  pollSeconds = 2,
+  maxIdleSeconds = 20,
+  env,
+  homeDir,
+  onSnapshot,
+} = {}) {
+  const pollMs = Math.max(250, Math.floor(Number(pollSeconds || 2) * 1000));
+  const maxIdleMs = Math.max(1000, Math.floor(Number(maxIdleSeconds || 20) * 1000));
+  let lastSignature = "";
+  let lastUpdate = Date.now();
+  const snapshots = [];
+
+  while (true) {
+    const snapshot = await loadSwarmDashboardSnapshot({
+      targetPath,
+      outputDir,
+      runId,
+      env,
+      homeDir,
+    });
+    const signature = `${snapshot.eventCount}:${snapshot.usage.toolCalls || 0}:${snapshot.completed}:${snapshot.stop?.stopClass || "NONE"}`;
+    if (signature !== lastSignature) {
+      lastSignature = signature;
+      lastUpdate = Date.now();
+      snapshots.push(snapshot);
+      if (onSnapshot) {
+        await onSnapshot(snapshot);
+      }
+    }
+
+    if (snapshot.completed || snapshot.stop?.blocking) {
+      return {
+        finalSnapshot: snapshot,
+        snapshots,
+        stopReason: snapshot.completed ? "COMPLETED" : snapshot.stop?.stopClass || "STOPPED",
+      };
+    }
+
+    if (Date.now() - lastUpdate >= maxIdleMs) {
+      return {
+        finalSnapshot: snapshot,
+        snapshots,
+        stopReason: "IDLE_TIMEOUT",
+      };
+    }
+    await sleep(pollMs);
+  }
+}