sentinelayer-cli 0.1.0

package/src/commands/daemon/shared.js

@@ -0,0 +1,213 @@
+import pc from "picocolors";
+
+import { getBudgetHealthColor } from "../../daemon/operator-control.js";
+
+// Shared helper utilities for daemon command modules.
+
+export function shouldEmitJson(options, command) {
+  const local = Boolean(options && options.json);
+  const globalFromCommand =
+    command && command.optsWithGlobals ? Boolean(command.optsWithGlobals().json) : false;
+  return local || globalFromCommand;
+}
+
+export function parsePositiveInteger(rawValue, field, fallbackValue) {
+  if (rawValue === undefined || rawValue === null || String(rawValue).trim() === "") {
+    return fallbackValue;
+  }
+  const normalized = Number(rawValue);
+  if (!Number.isFinite(normalized) || normalized <= 0) {
+    throw new Error(`${field} must be a positive integer.`);
+  }
+  return Math.floor(normalized);
+}
+
+export function parseCsv(rawValue) {
+  if (rawValue === undefined || rawValue === null || String(rawValue).trim() === "") {
+    return [];
+  }
+  return String(rawValue)
+    .split(",")
+    .map((item) => item.trim())
+    .filter(Boolean);
+}
+
+export function parseMetadata(rawValue) {
+  if (!rawValue) {
+    return {};
+  }
+  const parsed = JSON.parse(String(rawValue));
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new Error("metadataJson must parse to an object.");
+  }
+  return parsed;
+}
+
+export function parseBoolean(rawValue, fallbackValue) {
+  if (rawValue === undefined || rawValue === null || String(rawValue).trim() === "") {
+    return fallbackValue;
+  }
+  const normalized = String(rawValue).trim().toLowerCase();
+  if (normalized === "true" || normalized === "1" || normalized === "yes") {
+    return true;
+  }
+  if (normalized === "false" || normalized === "0" || normalized === "no") {
+    return false;
+  }
+  throw new Error("Value must be true/false.");
+}
+
+export function printQueueSummary(payload) {
+  console.log(pc.bold("OMAR error daemon queue"));
+  console.log(pc.gray(`Queue: ${payload.queuePath}`));
+  console.log(pc.gray(`State: ${payload.statePath}`));
+  console.log(
+    pc.gray(
+      `visible=${payload.visibleCount} total=${payload.totalCount} stream_offset=${payload.workerState?.streamOffset ?? 0}`
+    )
+  );
+  for (const item of payload.items) {
+    console.log(
+      `- ${item.workItemId} | ${item.severity} | ${item.status} | occurrences=${item.occurrenceCount} | ${item.service} ${item.endpoint}`
+    );
+  }
+}
+
+export function printAssignmentSummary(payload) {
+  console.log(pc.bold("OMAR assignment ledger"));
+  console.log(pc.gray(`Ledger: ${payload.ledgerPath}`));
+  console.log(pc.gray(`Queue: ${payload.queuePath}`));
+  console.log(pc.gray(`Events: ${payload.eventsPath}`));
+  console.log(pc.gray(`visible=${payload.visibleCount} total=${payload.totalCount}`));
+  for (const assignment of payload.assignments) {
+    console.log(
+      `- ${assignment.workItemId} | ${assignment.status} | ${assignment.assignedAgentIdentity || "unassigned"} | stage=${assignment.stage} | lease_expires=${assignment.leaseExpiresAt || "n/a"}`
+    );
+  }
+}
+
+export function printJiraSummary(payload) {
+  console.log(pc.bold("OMAR Jira lifecycle"));
+  console.log(pc.gray(`Lifecycle: ${payload.lifecyclePath}`));
+  console.log(pc.gray(`Events: ${payload.eventsPath}`));
+  console.log(pc.gray(`visible=${payload.visibleCount} total=${payload.totalCount}`));
+  for (const issue of payload.issues) {
+    console.log(
+      `- ${issue.issueKey} | ${issue.status} | work_item=${issue.workItemId} | assignee=${issue.assignee || "n/a"}`
+    );
+  }
+}
+
+export function printBudgetSummary(payload) {
+  console.log(pc.bold("OMAR budget governor"));
+  console.log(pc.gray(`State: ${payload.budgetStatePath}`));
+  console.log(pc.gray(`Events: ${payload.budgetEventsPath}`));
+  console.log(pc.gray(`visible=${payload.visibleCount} total=${payload.totalCount}`));
+  for (const record of payload.records) {
+    const stopCodes = Array.isArray(record.stopReasons)
+      ? record.stopReasons.map((item) => item.code).join(", ")
+      : "";
+    console.log(
+      `- ${record.workItemId} | ${record.lifecycleState} | action=${record.lastAction || "NONE"} | quarantine_until=${record.quarantineUntil || "n/a"}${stopCodes ? ` | stops=${stopCodes}` : ""}`
+    );
+  }
+}
+
+export function formatDurationSeconds(seconds) {
+  const normalized = Number(seconds);
+  if (!Number.isFinite(normalized) || normalized < 0) {
+    return "n/a";
+  }
+  const total = Math.floor(normalized);
+  const hours = Math.floor(total / 3600);
+  const minutes = Math.floor((total % 3600) / 60);
+  const secs = total % 60;
+  if (hours > 0) {
+    return `${hours}h ${minutes}m ${secs}s`;
+  }
+  if (minutes > 0) {
+    return `${minutes}m ${secs}s`;
+  }
+  return `${secs}s`;
+}
+
+export function colorizeBudgetHealth(value) {
+  const normalized = getBudgetHealthColor(value);
+  if (normalized === "RED") {
+    return pc.red(normalized);
+  }
+  if (normalized === "YELLOW") {
+    return pc.yellow(normalized);
+  }
+  return pc.green(normalized);
+}
+
+export function printControlPlaneSummary(payload) {
+  console.log(pc.bold("OMAR operator control plane"));
+  console.log(pc.gray(`State: ${payload.operatorStatePath}`));
+  console.log(pc.gray(`Events: ${payload.operatorEventsPath}`));
+  console.log(pc.gray(`Snapshot: ${payload.runPath}`));
+  console.log(
+    pc.gray(
+      `visible=${payload.visibleWorkItems} total_queue=${payload.totalQueueItems} active_agents=${payload.agentRoster.length}`
+    )
+  );
+  for (const row of payload.workItems) {
+    console.log(
+      `- ${row.workItemId} | ${row.severity} | ${row.workItemStatus} | agent=${row.assignedAgentIdentity || "unassigned"} | budget=${colorizeBudgetHealth(row.budgetHealthColor)} | elapsed=${formatDurationSeconds(row.sessionElapsedSeconds)} | idle=${formatDurationSeconds(row.sessionIdleSeconds)} | jira=${row.jiraIssueKey || "n/a"}`
+    );
+  }
+  if (payload.agentRoster.length > 0) {
+    console.log(pc.bold("Agent roster"));
+    for (const agent of payload.agentRoster) {
+      console.log(
+        `- ${agent.agentIdentity} | work_items=${agent.workItemCount} | active=${agent.activeWorkItemCount} | blocked=${agent.blockedCount} | squashed=${agent.squashedCount} | longest_session=${formatDurationSeconds(agent.maxSessionElapsedSeconds)}`
+      );
+    }
+  }
+}
+
+export function printLineageSummary(payload) {
+  console.log(pc.bold("OMAR artifact lineage"));
+  console.log(pc.gray(`Index: ${payload.indexPath}`));
+  console.log(pc.gray(`Events: ${payload.eventPath}`));
+  console.log(
+    pc.gray(
+      `visible=${payload.visibleCount} total=${payload.totalCount} lineage_run=${payload.lineageRunId || "n/a"}`
+    )
+  );
+  for (const item of payload.workItems) {
+    console.log(
+      `- ${item.workItemId} | ${item.severity} | ${item.workItemStatus} | agent=${item.links?.agentIdentity || "unassigned"} | jira=${item.links?.jiraIssueKey || "n/a"} | budget=${item.links?.budgetLifecycleState || "WITHIN_BUDGET"} | operator_snapshot=${item.links?.latestOperatorSnapshotRunId || "n/a"}`
+    );
+  }
+}
+
+export function printHybridMapSummary(payload) {
+  console.log(pc.bold("OMAR hybrid mapping overlay"));
+  console.log(pc.gray(`Index: ${payload.mapIndexPath}`));
+  console.log(pc.gray(`Events: ${payload.mapEventsPath}`));
+  console.log(pc.gray(`visible=${payload.visibleCount} total=${payload.totalCount}`));
+  for (const map of payload.maps) {
+    console.log(
+      `- ${map.workItemId} | run=${map.runId} | status=${map.status || "n/a"} | seeds=${map.deterministicSeedCount || 0} | scoped=${map.scopedFileCount || 0}`
+    );
+  }
+}
+
+export function printReliabilitySummary(payload) {
+  console.log(pc.bold("OMAR reliability lane"));
+  console.log(pc.gray(`Config: ${payload.configPath}`));
+  console.log(pc.gray(`Billboard: ${payload.billboardPath}`));
+  console.log(pc.gray(`Events: ${payload.eventsPath}`));
+  console.log(
+    pc.gray(
+      `maintenance=${payload.billboard?.enabled ? "ON" : "OFF"} checks=${payload.config?.checks?.length || 0} recent_runs=${payload.recentRuns?.length || 0}`
+    )
+  );
+  for (const run of payload.recentRuns || []) {
+    console.log(
+      `- ${run.runId} | ${run.overallStatus} | failures=${run.failureCount} | ${run.generatedAt}`
+    );
+  }
+}

package/src/commands/daemon.js

@@ -0,0 +1,11 @@
+import { registerDaemonCoreCommands } from "./daemon/core.js";
+import { registerDaemonExtendedCommands } from "./daemon/extended.js";
+
+export function registerDaemonCommand(program) {
+  const daemon = program
+    .command("daemon")
+    .description("OMAR daemon controls for error-event intake and routed queue management");
+
+  registerDaemonCoreCommands(daemon);
+  registerDaemonExtendedCommands(daemon);
+}

package/src/commands/guide.js

@@ -0,0 +1,174 @@
+import fs from "node:fs";
+import fsp from "node:fs/promises";
+import path from "node:path";
+
+import pc from "picocolors";
+
+import {
+  defaultGuideExportFileName,
+  generateBuildGuide,
+  renderGuideExport,
+  SUPPORTED_GUIDE_EXPORT_FORMATS,
+} from "../guide/generator.js";
+import { renderTerminalMarkdown } from "../ui/markdown.js";
+
+function shouldEmitJson(options, command) {
+  const local = Boolean(options && options.json);
+  const globalFromCommand =
+    command && command.optsWithGlobals ? Boolean(command.optsWithGlobals().json) : false;
+  return local || globalFromCommand;
+}
+
+function resolveSpecPath(targetPath, explicitSpecFile) {
+  const explicit = String(explicitSpecFile || "").trim();
+  if (explicit) {
+    return path.resolve(targetPath, explicit);
+  }
+
+  const candidates = [path.join(targetPath, "SPEC.md"), path.join(targetPath, "docs", "spec.md")];
+  const found = candidates.find((candidate) => fs.existsSync(candidate));
+  if (!found) {
+    throw new Error("No spec file found. Provide --spec-file or generate SPEC.md first.");
+  }
+  return found;
+}
+
+function resolveExportFormat(rawFormat) {
+  const normalized = String(rawFormat || "").trim().toLowerCase();
+  if (!SUPPORTED_GUIDE_EXPORT_FORMATS.includes(normalized)) {
+    throw new Error(
+      `Unsupported export format '${rawFormat}'. Use one of: ${SUPPORTED_GUIDE_EXPORT_FORMATS.join(", ")}`
+    );
+  }
+  return normalized;
+}
+
+export function registerGuideCommand(program) {
+  const guide = program.command("guide").description("Generate and export phase-by-phase build guides");
+
+  guide
+    .command("generate")
+    .description("Generate BUILD_GUIDE.md from SPEC content")
+    .option("--path <path>", "Target workspace path", ".")
+    .option("--spec-file <path>", "Spec file path relative to --path")
+    .option("--output-file <path>", "Output guide path relative to --path", "BUILD_GUIDE.md")
+    .option("--json", "Emit machine-readable output")
+    .action(async (options, command) => {
+      const targetPath = path.resolve(process.cwd(), String(options.path || "."));
+      const outputPath = path.resolve(targetPath, String(options.outputFile || "BUILD_GUIDE.md").trim());
+      const specPath = resolveSpecPath(targetPath, options.specFile);
+      const specMarkdown = await fsp.readFile(specPath, "utf-8");
+
+      const guideDoc = generateBuildGuide({
+        specMarkdown,
+        projectPath: targetPath,
+        specPath,
+      });
+
+      await fsp.mkdir(path.dirname(outputPath), { recursive: true });
+      await fsp.writeFile(outputPath, `${guideDoc.markdown.trimEnd()}\n`, "utf-8");
+
+      const payload = {
+        command: "guide generate",
+        targetPath,
+        specPath,
+        outputPath,
+        phases: guideDoc.phases.map((phase) => ({
+          title: phase.title,
+          effort: phase.effort.label,
+          dependencies: phase.dependencies,
+        })),
+      };
+
+      if (shouldEmitJson(options, command)) {
+        console.log(JSON.stringify(payload, null, 2));
+        return;
+      }
+
+      console.log(pc.bold("Build guide generated"));
+      console.log(pc.gray(`Spec: ${specPath}`));
+      console.log(pc.gray(`Output: ${outputPath}`));
+      console.log(pc.gray(`Phases: ${guideDoc.phases.length}`));
+    });
+
+  guide
+    .command("export")
+    .description("Export build-guide phases into issue tracker-friendly format")
+    .requiredOption(
+      "--format <type>",
+      `Export format (${SUPPORTED_GUIDE_EXPORT_FORMATS.join("|")})`
+    )
+    .option("--path <path>", "Target workspace path", ".")
+    .option("--spec-file <path>", "Spec file path relative to --path")
+    .option("--output-file <path>", "Output export file path relative to --path")
+    .option("--json", "Emit machine-readable output")
+    .action(async (options, command) => {
+      const targetPath = path.resolve(process.cwd(), String(options.path || "."));
+      const format = resolveExportFormat(options.format);
+      const outputName =
+        String(options.outputFile || "").trim() || defaultGuideExportFileName(format);
+      const outputPath = path.resolve(targetPath, outputName);
+      const specPath = resolveSpecPath(targetPath, options.specFile);
+      const specMarkdown = await fsp.readFile(specPath, "utf-8");
+
+      const guideDoc = generateBuildGuide({
+        specMarkdown,
+        projectPath: targetPath,
+        specPath,
+      });
+      const exportBody = renderGuideExport({ format, guide: guideDoc });
+
+      await fsp.mkdir(path.dirname(outputPath), { recursive: true });
+      await fsp.writeFile(outputPath, `${exportBody.trimEnd()}\n`, "utf-8");
+
+      const payload = {
+        command: "guide export",
+        format,
+        targetPath,
+        specPath,
+        outputPath,
+        issueCount: guideDoc.tickets.length,
+      };
+
+      if (shouldEmitJson(options, command)) {
+        console.log(JSON.stringify(payload, null, 2));
+        return;
+      }
+
+      console.log(pc.bold("Build guide export generated"));
+      console.log(pc.gray(`Format: ${format}`));
+      console.log(pc.gray(`Output: ${outputPath}`));
+      console.log(pc.gray(`Issues: ${guideDoc.tickets.length}`));
+    });
+
+  guide
+    .command("show")
+    .description("Render an existing BUILD_GUIDE artifact in terminal markdown")
+    .option("--path <path>", "Target workspace path", ".")
+    .option("--file <path>", "Guide file path relative to --path", "BUILD_GUIDE.md")
+    .option("--plain", "Disable terminal markdown styling")
+    .option("--json", "Emit machine-readable output")
+    .action(async (options, command) => {
+      const targetPath = path.resolve(process.cwd(), String(options.path || "."));
+      const guidePath = path.resolve(targetPath, String(options.file || "BUILD_GUIDE.md").trim());
+      if (!fs.existsSync(guidePath)) {
+        throw new Error(`Guide artifact not found: ${guidePath}`);
+      }
+
+      const markdown = await fsp.readFile(guidePath, "utf-8");
+      const payload = {
+        command: "guide show",
+        guidePath,
+        lineCount: markdown.split(/\r?\n/).length,
+        preview: markdown,
+      };
+
+      if (shouldEmitJson(options, command)) {
+        console.log(JSON.stringify(payload, null, 2));
+        return;
+      }
+
+      console.log(renderTerminalMarkdown(markdown, { plain: Boolean(options.plain) }));
+    });
+}
+

package/src/commands/ingest.js

@@ -0,0 +1,58 @@
+import path from "node:path";
+
+import pc from "picocolors";
+
+import { formatIngestSummary, generateCodebaseIngest } from "../ingest/engine.js";
+
+function shouldEmitJson(options, command) {
+  const local = Boolean(options && options.json);
+  const globalFromCommand =
+    command && command.optsWithGlobals ? Boolean(command.optsWithGlobals().json) : false;
+  return local || globalFromCommand;
+}
+
+export function registerIngestCommand(program) {
+  const ingest = program
+    .command("ingest")
+    .description("Run deterministic codebase ingest and mapping");
+
+  ingest
+    .command("map")
+    .description("Generate CODEBASE_INGEST.json with stack/risk hints")
+    .option("--path <path>", "Target repository path", ".")
+    .option("--output-file <path>", "Explicit output file path relative to --path")
+    .option("--output-dir <path>", "Artifact root used when output file is not provided")
+    .option("--json", "Emit machine-readable output")
+    .action(async (options, command) => {
+      const targetPath = path.resolve(process.cwd(), String(options.path || "."));
+      const result = await generateCodebaseIngest({
+        rootPath: targetPath,
+        outputFile: options.outputFile,
+        outputDir: options.outputDir,
+      });
+
+      const emitJson = shouldEmitJson(options, command);
+      if (emitJson) {
+        console.log(
+          JSON.stringify(
+            {
+              command: "ingest map",
+              targetPath,
+              outputPath: result.outputPath,
+              summary: result.ingest.summary,
+              frameworks: result.ingest.frameworks,
+              entryPoints: result.ingest.entryPoints,
+              riskSurfaces: result.ingest.riskSurfaces,
+            },
+            null,
+            2
+          )
+        );
+        return;
+      }
+
+      console.log(pc.bold("Codebase ingest completed"));
+      console.log(pc.gray(`Output: ${result.outputPath}`));
+      console.log(formatIngestSummary(result.ingest));
+    });
+}

package/src/commands/init.js

@@ -0,0 +1,55 @@
+import process from "node:process";
+
+import { loadConfig } from "../config/service.js";
+
+function applyConfigEnvDefaults(resolvedConfig) {
+  if (!process.env.SENTINELAYER_API_URL && resolvedConfig.apiUrl) {
+    process.env.SENTINELAYER_API_URL = resolvedConfig.apiUrl;
+  }
+  if (!process.env.SENTINELAYER_WEB_URL && resolvedConfig.webUrl) {
+    process.env.SENTINELAYER_WEB_URL = resolvedConfig.webUrl;
+  }
+  if (!process.env.SENTINELAYER_TOKEN && resolvedConfig.sentinelayerToken) {
+    process.env.SENTINELAYER_TOKEN = resolvedConfig.sentinelayerToken;
+  }
+  if (!process.env.OPENAI_API_KEY && resolvedConfig.openaiApiKey) {
+    process.env.OPENAI_API_KEY = resolvedConfig.openaiApiKey;
+  }
+  if (!process.env.ANTHROPIC_API_KEY && resolvedConfig.anthropicApiKey) {
+    process.env.ANTHROPIC_API_KEY = resolvedConfig.anthropicApiKey;
+  }
+  if (!process.env.GOOGLE_API_KEY && resolvedConfig.googleApiKey) {
+    process.env.GOOGLE_API_KEY = resolvedConfig.googleApiKey;
+  }
+}
+
+export function registerInitCommand(program, invokeLegacy) {
+  program
+    .command("init [projectName]")
+    .description("Run scaffold/auth generation flow")
+    .option("--non-interactive", "Disable prompts and require interview payload")
+    .option("--interview-file <path>", "Load interview JSON from file")
+    .option("--skip-browser-open", "Do not auto-open browser during auth")
+    .action(async (projectName, options) => {
+      const config = await loadConfig();
+      applyConfigEnvDefaults(config.resolved);
+
+      const legacyArgs = [];
+      const normalizedProjectName = String(projectName || "").trim();
+      if (normalizedProjectName) {
+        legacyArgs.push(normalizedProjectName);
+      }
+      if (options.nonInteractive) {
+        legacyArgs.push("--non-interactive");
+      }
+      const interviewFile = String(options.interviewFile || "").trim();
+      if (interviewFile) {
+        legacyArgs.push("--interview-file", interviewFile);
+      }
+      if (options.skipBrowserOpen) {
+        legacyArgs.push("--skip-browser-open");
+      }
+
+      await invokeLegacy(legacyArgs);
+    });
+}

package/src/commands/legacy-args.js

@@ -0,0 +1,30 @@
+function wantsJsonOutput(commandOptions, command) {
+  const local = Boolean(commandOptions && commandOptions.json);
+  const globalFromCommand =
+    command && command.optsWithGlobals ? Boolean(command.optsWithGlobals().json) : false;
+  return local || globalFromCommand;
+}
+
+function appendPathFlag(args, maybePath) {
+  const value = String(maybePath || "").trim();
+  if (value) {
+    args.push("--path", value);
+  }
+}
+
+function appendOutputDirFlag(args, maybeOutputDir) {
+  const value = String(maybeOutputDir || "").trim();
+  if (value) {
+    args.push("--output-dir", value);
+  }
+}
+
+export function buildLegacyArgs(baseArgs, { commandOptions = {}, command } = {}) {
+  const args = [...baseArgs];
+  appendPathFlag(args, commandOptions.path);
+  appendOutputDirFlag(args, commandOptions.outputDir);
+  if (wantsJsonOutput(commandOptions, command)) {
+    args.push("--json");
+  }
+  return args;
+}