supipowers 1.2.6 → 1.5.0

package/src/text.ts

@@ -0,0 +1,19 @@
+/** Normalizes Windows CRLF line endings to LF. */
+export function normalizeLineEndings(text: string): string {
+  return text.replace(/\r\n/g, "\n");
+}
+
+/** Removes a single outer markdown code fence wrapper when present. */
+export function stripMarkdownCodeFence(text: string): string {
+  const trimmed = text.trim();
+  if (!trimmed.startsWith("```")) {
+    return trimmed;
+  }
+
+  const lines = trimmed.split("\n");
+  if (lines.length >= 3 && lines[0]!.startsWith("```") && lines[lines.length - 1] === "```") {
+    return lines.slice(1, -1).join("\n").trim();
+  }
+
+  return trimmed;
+}

package/src/types.ts

@@ -1,3 +1,6 @@
+import type { TSchema } from "@sinclair/typebox";
+import type { AgentSession, AgentSessionOptions, ExecOptions, ExecResult } from "./platform/types.js";
+
 // src/types.ts — Shared type definitions for supipowers
 
 /** Task complexity level */
@@ -35,12 +38,14 @@ export interface Notification {
   detail?: string;
 }
 
-/** Quality gate result */
-export interface GateResult {
-  gate: string;
-  passed: boolean;
-  issues: GateIssue[];
-}
+/** Canonical quality gate identifiers */
+export type CommandGateId = "lint" | "typecheck" | "format" | "test-suite" | "build";
+export type GateId = "lsp-diagnostics" | CommandGateId;
+
+export type ConfigScope = "project" | "global";
+
+/** Aggregate gate execution status */
+export type GateStatus = "passed" | "failed" | "skipped" | "blocked";
 
 /** A single issue from a quality gate */
 export interface GateIssue {
@@ -48,23 +53,315 @@ export interface GateIssue {
   message: string;
   file?: string;
   line?: number;
+  detail?: string;
+}
+
+/** A single quality gate result */
+export interface GateResult {
+  gate: GateId;
+  status: GateStatus;
+  summary: string;
+  issues: GateIssue[];
+  metadata?: Record<string, unknown>;
+}
+
+/** Aggregate quality-gate summary */
+export interface GateSummary {
+  passed: number;
+  failed: number;
+  skipped: number;
+  blocked: number;
 }
 
 /** Review report */
 export interface ReviewReport {
-  profile: string;
   timestamp: string;
+  selectedGates: GateId[];
   gates: GateResult[];
-  passed: boolean;
+  summary: GateSummary;
+  overallStatus: Exclude<GateStatus, "skipped">;
+}
+
+/** AI review pipeline levels */
+export type ReviewLevel = "quick" | "deep" | "multi-agent";
+
+/** Scope selection modes for /supi:review */
+export type ReviewScopeMode = "pull-request" | "uncommitted" | "commit" | "custom";
+
+/** Structured review output status */
+export type ReviewOutputStatus = "passed" | "failed" | "blocked";
+
+/** Review finding severity */
+export type ReviewFindingSeverity = "error" | "warning" | "info";
+
+/** Prioritization tier for review findings */
+export type ReviewFindingPriority = "P0" | "P1" | "P2" | "P3";
+
+/** Validation verdict for a review finding */
+export type ReviewValidationVerdict = "confirmed" | "rejected" | "uncertain";
+
+/** Review session lifecycle status */
+export type ReviewSessionStatus = "running" | "completed" | "blocked" | "cancelled";
+
+/** User decision after reviewing consolidated/current findings */
+export type ReviewPostConsolidationAction =
+  | "fix-now"
+  | "document-only"
+  | "discuss-before-fixing";
+
+/** File-level diff summary within a review scope */
+export interface ReviewScopeFile {
+  path: string;
+  additions: number;
+  deletions: number;
+  diff: string;
+}
+
+/** Aggregate statistics for a review scope */
+export interface ReviewScopeStats {
+  filesChanged: number;
+  excludedFiles: number;
+  additions: number;
+  deletions: number;
 }
 
+/** Review scope selected by the command pipeline */
+export interface ReviewScope {
+  mode: ReviewScopeMode;
+  description: string;
+  diff: string;
+  files: ReviewScopeFile[];
+  stats: ReviewScopeStats;
+  baseBranch?: string;
+  commit?: string;
+  customInstructions?: string;
+}
+
+/** Per-finding validation metadata */
+export interface ReviewFindingValidation {
+  verdict: ReviewValidationVerdict;
+  reasoning: string;
+  validatedBy: string;
+  validatedAt: string;
+}
+
+/** Canonical review finding produced by AI reviewers */
+export interface ReviewFinding {
+  id: string;
+  title: string;
+  severity: ReviewFindingSeverity;
+  priority: ReviewFindingPriority;
+  confidence: number;
+  file: string | null;
+  lineStart: number | null;
+  lineEnd: number | null;
+  body: string;
+  suggestion: string | null;
+  agent?: string;
+  validation?: ReviewFindingValidation;
+}
+
+/** Structured output returned by review agents */
+export interface ReviewOutput {
+  findings: ReviewFinding[];
+  summary: string;
+  status: ReviewOutputStatus;
+}
+
+/** Config entry for one review agent */
+export interface ReviewAgentConfig {
+  name: string;
+  enabled: boolean;
+  data: string;
+  model: string | null;
+}
+
+/** Top-level review agent pipeline config */
+export interface ReviewAgentsConfig {
+  agents: ReviewAgentConfig[];
+}
+
+/** Loaded review agent definition from markdown frontmatter + prompt body */
+export interface ReviewAgentDefinition {
+  name: string;
+  description: string;
+  focus: string | null;
+  prompt: string;
+  filePath: string;
+}
+/** Review agent definition combined with pipeline config */
+export interface ConfiguredReviewAgent extends ReviewAgentDefinition {
+  enabled: boolean;
+  data: string;
+  model: string | null;
+  scope?: "global" | "project";
+}
+
+
+
+/** Persisted summary for one review iteration */
+export interface ReviewIterationSummary {
+  iteration: number;
+  findings: number;
+  status: ReviewOutputStatus;
+  file: string;
+  createdAt: string;
+}
+/** Aggregate status of an auto-fix pass */
+export type ReviewFixOutputStatus = "applied" | "partial" | "skipped" | "blocked";
+
+/** Structured result returned by the review fixer */
+export interface ReviewFixOutput {
+  fixes: ReviewFixRecord[];
+  summary: string;
+  status: ReviewFixOutputStatus;
+}
+
+
+
+/** Persisted auto-fix attempt */
+export interface ReviewFixRecord {
+  findingIds: string[];
+  file: string | null;
+  status: "applied" | "skipped" | "failed";
+  summary: string;
+}
+
+/** Paths to persisted review session artifacts */
+export interface ReviewSessionArtifacts {
+  scope: string;
+  iterationsDir: string;
+  agentsDir: string;
+  rawFindings?: string;
+  validatedFindings?: string;
+  consolidatedFindings?: string;
+  findingsReport?: string;
+}
+
+/** Persisted /supi:review session metadata */
+export interface ReviewSession {
+  id: string;
+  createdAt: string;
+  updatedAt: string;
+  level: ReviewLevel;
+  status: ReviewSessionStatus;
+  scope: ReviewScope;
+  validateFindings: boolean;
+  consolidate: boolean;
+  postConsolidationAction: ReviewPostConsolidationAction | null;
+  maxIterations: number;
+  currentIteration: number;
+  iterations: ReviewIterationSummary[];
+  fixes: ReviewFixRecord[];
+  artifacts: ReviewSessionArtifacts;
+  agents: string[];
+}
+
+
+/** Config for the lsp-diagnostics gate */
+export interface LspDiagnosticsGateConfig {
+  enabled: boolean;
+}
+
+/** Shared config for command-driven gates. */
+export type CommandGateConfig =
+  | { enabled: false; command?: string | null }
+  | { enabled: true; command: string };
+
+export type LintGateConfig = CommandGateConfig;
+export type TypecheckGateConfig = CommandGateConfig;
+export type FormatGateConfig = CommandGateConfig;
+export type TestSuiteGateConfig = CommandGateConfig;
+export type BuildGateConfig = CommandGateConfig;
+
+/** Canonical quality gate config map */
+export interface QualityGatesConfig {
+  "lsp-diagnostics"?: LspDiagnosticsGateConfig;
+  "lint"?: LintGateConfig;
+  "typecheck"?: TypecheckGateConfig;
+  "format"?: FormatGateConfig;
+  "test-suite"?: TestSuiteGateConfig;
+  "build"?: BuildGateConfig;
+}
+
+/** Gate filter options provided by commands */
+export interface GateFilters {
+  only?: GateId[];
+  skip?: GateId[];
+}
+
+/** Project facts used by gate setup/detection */
+export interface ProjectFacts {
+  cwd: string;
+  packageScripts: Record<string, string>;
+  lockfiles: string[];
+  activeTools: string[];
+  existingGates: QualityGatesConfig;
+}
+
+/** Recommendation returned by gate auto-detection */
+export interface GateDetectionResult<TConfig = unknown> {
+  suggestedConfig: TConfig | null;
+  confidence: "high" | "medium" | "low";
+  reason: string;
+}
+
+/** Shared runtime context passed to each gate */
+export interface GateExecutionContext {
+  cwd: string;
+  changedFiles: string[];
+  scopeFiles: string[];
+  fileScope: "changed-files" | "all-files";
+  exec: (cmd: string, args: string[], opts?: ExecOptions) => Promise<ExecResult>;
+  execShell: (command: string, opts?: ExecOptions) => Promise<ExecResult>;
+  getLspDiagnostics: (
+    scopeFiles: string[],
+    fileScope: GateExecutionContext["fileScope"]
+  ) => Promise<GateIssue[]>;
+  createAgentSession: (
+    opts: Pick<AgentSessionOptions, "cwd" | "model" | "thinkingLevel">
+  ) => Promise<AgentSession>;
+  activeTools: string[];
+  reviewModel?: Pick<ResolvedModel, "model" | "thinkingLevel">;
+}
+
+/** Registered quality gate contract */
+export interface GateDefinition<TConfig> {
+  id: GateId;
+  description: string;
+  configSchema: TSchema;
+  detect(projectFacts: ProjectFacts): GateDetectionResult<TConfig> | null;
+  run(context: GateExecutionContext, config: TConfig): Promise<GateResult>;
+}
+
+/** A proposed quality-gate configuration */
+export interface SetupProposal {
+  gates: QualityGatesConfig;
+}
+
+/** Result of running the setup flow */
+export type SetupGatesResult =
+  | { status: "proposed"; proposal: SetupProposal }
+  | { status: "invalid"; proposal: SetupProposal; errors: string[] }
+  | { status: "cancelled"; proposal?: SetupProposal; errors?: string[] };
+
 // ── Release types ──────────────────────────────────────────
 
 /** Semantic version bump type */
 export type BumpType = "major" | "minor" | "patch";
 
-/** Release channel target */
-export type ReleaseChannel = "github" | "npm";
+/** Release channel target (built-in IDs or user-defined custom channel IDs) */
+export type ReleaseChannel = string;
+
+/** User-defined custom release channel configuration */
+export interface CustomChannelConfig {
+  /** Display name shown in the channel selection UI */
+  label: string;
+  /** Shell command template with ${tag}, ${version}, ${changelog} placeholders */
+  publishCommand: string;
+  /** Shell command to detect availability — exit code 0 means available. When omitted, always available. */
+  detectCommand?: string;
+}
 
 /** A single parsed commit entry */
 export interface CommitEntry {
@@ -97,7 +394,7 @@ export interface ReleaseResult {
 
 /** Context-mode integration settings */
 export interface ContextModeConfig {
-  /** Master toggle for all context-mode integration (default: true) */
+  /** Master toggle for all supi-context-mode integration (default: true) */
   enabled: boolean;
   /** Byte threshold above which tool results are compressed (default: 4096) */
   compressionThreshold: number;
@@ -170,33 +467,46 @@ export interface ResolvedModel {
 /** Config shape */
 export interface SupipowersConfig {
   version: string;
-  defaultProfile: string;
+  quality: {
+    gates: QualityGatesConfig;
+  };
   lsp: {
     setupGuide: boolean;
   };
-  notifications: {
-    verbosity: "quiet" | "normal" | "verbose";
-  };
   qa: {
     framework: string | null;
-    command: string | null;
     e2e: boolean;
   };
   release: {
     channels: ReleaseChannel[];
+    /** Tag format template. Use ${version} as placeholder. Default: "v${version}" */
+    tagFormat: string;
+    /** User-defined custom release channels keyed by channel ID */
+    customChannels: Record<string, CustomChannelConfig>;
   };
   contextMode: ContextModeConfig;
   mcp: McpManagementConfig;
 }
 
-/** Profile shape */
-export interface Profile {
-  name: string;
-  gates: {
-    lspDiagnostics: boolean;
-    aiReview: { enabled: boolean; depth: "quick" | "deep" };
-    codeQuality: boolean;
-    testSuite: boolean;
-    e2e: boolean;
-  };
+
+/** Persisted state for /supi:generate docs — tracks which docs are monitored and the last checked commit */
+export interface DocDriftState {
+  trackedFiles: string[];
+  lastCommit: string | null;
+  lastRunAt: string | null;
+}
+
+/** A single drift finding from a sub-agent doc review */
+export interface DriftFinding {
+  file: string;
+  description: string;
+  severity: "info" | "warning" | "error";
+  relatedFiles?: string[];
 }
+
+/** Result of a headless doc-drift check (multi-agent pipeline) */
+export interface DriftCheckResult {
+  drifted: boolean;
+  summary: string;
+  findings: DriftFinding[];
+}

package/src/utils/paths.ts

@@ -0,0 +1,39 @@
+import { fileURLToPath } from "node:url";
+import * as path from "node:path";
+
+/**
+ * Returns the directory of the calling module, correctly resolved on all
+ * platforms.
+ *
+ * The naive alternative — `path.dirname(new URL(import.meta.url).pathname)` —
+ * is broken on Windows: `URL.pathname` for a `file:///C:/foo/bar.ts` URL
+ * yields `/C:/foo/bar.ts` (leading slash before the drive letter), which
+ * `path.dirname` on Windows converts to a backslash path. Those backslashes,
+ * when later embedded in a bash command, are consumed as escape sequences and
+ * silently corrupt the path.
+ *
+ * `fileURLToPath` handles the Windows case correctly, stripping the leading
+ * slash and returning a proper `C:\foo\bar.ts` path.
+ *
+ * @param importMetaUrl Pass `import.meta.url` from the caller.
+ */
+export function moduleDir(importMetaUrl: string): string {
+  return path.dirname(fileURLToPath(importMetaUrl));
+}
+
+/**
+ * Normalizes path separators to forward slashes so the path is safe to embed
+ * in bash commands or shell-script arguments on Windows.
+ *
+ * Git Bash (and WSL) on Windows interpret `\` as an escape character, so a
+ * native Windows path like `C:\Users\foo\bar` silently becomes `C:Usersfoobar`
+ * when passed as a bash argument. Forward slashes are accepted by both Git
+ * Bash and Node.js file APIs on Windows, so this conversion is safe to apply
+ * universally.
+ *
+ * Use on every path that will be passed to `platform.exec("bash", [...])` or
+ * embedded as a literal in an AI prompt that contains bash commands.
+ */
+export function toBashPath(p: string): string {
+  return p.replace(/\\/g, "/");
+}

package/src/visual/companion.ts

@@ -2,6 +2,7 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import { fileURLToPath } from "node:url";
 import type { VisualServerInfo, VisualEvent } from "./types.js";
+import { normalizeLineEndings } from "../text.js";
 import type { PlatformPaths } from "../platform/types.js";
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
@@ -32,7 +33,7 @@ export function readEvents(sessionDir: string): VisualEvent[] {
   const eventsFile = path.join(sessionDir, ".events");
   if (!fs.existsSync(eventsFile)) return [];
 
-  const content = fs.readFileSync(eventsFile, "utf-8");
+  const content = normalizeLineEndings(fs.readFileSync(eventsFile, "utf-8"));
   const events: VisualEvent[] = [];
 
   for (const line of content.split("\n")) {
@@ -60,9 +61,10 @@ export function getScriptsDir(): string {
   return path.join(__dirname, "scripts");
 }
 
-/** Parse server info from start-server.sh JSON output */
+/** Parse server info from launcher output or server logs. */
 export function parseServerInfo(stdout: string): VisualServerInfo | null {
-  for (const line of stdout.split("\n")) {
+  const normalizedStdout = normalizeLineEndings(stdout);
+  for (const line of normalizedStdout.split("\n")) {
     if (!line.trim()) continue;
     try {
       const data = JSON.parse(line);

package/src/visual/start-server.ts

@@ -0,0 +1,101 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { getScriptsDir, readServerInfo } from "./companion.js";
+import { stopVisualServer } from "./stop-server.js";
+import type { VisualServerInfo } from "./types.js";
+
+const DEFAULT_HOST = "127.0.0.1";
+const START_TIMEOUT_MS = 5_000;
+const POLL_INTERVAL_MS = 100;
+
+interface StartServerOptions {
+  sessionDir: string;
+  host?: string;
+  urlHost?: string;
+}
+
+/** Start the visual companion server and wait for its connection info. */
+export async function startVisualServer(opts: StartServerOptions): Promise<VisualServerInfo | null> {
+  const host = opts.host ?? DEFAULT_HOST;
+  const urlHost = opts.urlHost ?? deriveUrlHost(host);
+  const scriptsDir = getScriptsDir();
+  const pidFile = path.join(opts.sessionDir, ".server.pid");
+
+  fs.mkdirSync(opts.sessionDir, { recursive: true });
+  stopVisualServer(opts.sessionDir);
+  cleanupStartupArtifacts(opts.sessionDir);
+
+  try {
+    const subprocess = Bun.spawn(["node", "index.js"], {
+      cwd: scriptsDir,
+      env: {
+        ...process.env,
+        SUPI_VISUAL_DIR: opts.sessionDir,
+        SUPI_VISUAL_HOST: host,
+        SUPI_VISUAL_URL_HOST: urlHost,
+      },
+      stdin: "ignore",
+      stdout: "ignore",
+      stderr: "ignore",
+      detached: true,
+    });
+
+    subprocess.unref();
+    fs.writeFileSync(pidFile, String(subprocess.pid));
+
+    const serverInfo = await pollForServerStart(opts.sessionDir, subprocess.pid, START_TIMEOUT_MS);
+    if (serverInfo) {
+      return serverInfo;
+    }
+
+    stopVisualServer(opts.sessionDir);
+    // stopVisualServer may leave artifacts when kill returns a non-ESRCH error;
+    // force-clean so the caller never inherits stale state.
+    fs.rmSync(pidFile, { force: true });
+    cleanupStartupArtifacts(opts.sessionDir);
+    return null;
+  } catch {
+    fs.rmSync(pidFile, { force: true });
+    return null;
+  }
+}
+
+function deriveUrlHost(host: string): string {
+  return host === "127.0.0.1" || host === "localhost" ? "localhost" : host;
+}
+
+function cleanupStartupArtifacts(sessionDir: string): void {
+  fs.rmSync(path.join(sessionDir, ".server-info"), { force: true });
+}
+
+async function pollForServerStart(
+  sessionDir: string,
+  pid: number,
+  timeoutMs: number,
+): Promise<VisualServerInfo | null> {
+  const deadline = Date.now() + timeoutMs;
+
+  while (Date.now() < deadline) {
+    const serverInfo = readServerInfo(sessionDir);
+    if (serverInfo) {
+      return isProcessAlive(pid) ? serverInfo : null;
+    }
+
+    if (!isProcessAlive(pid)) {
+      return null;
+    }
+
+    await Bun.sleep(POLL_INTERVAL_MS);
+  }
+
+  return null;
+}
+
+function isProcessAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}

package/src/visual/stop-server.ts

@@ -0,0 +1,39 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+export function stopVisualServer(
+  sessionDir: string,
+ ): { status: "stopped" | "not_running" | "failed" } {
+  const pidFile = path.join(sessionDir, ".server.pid");
+
+  if (!fs.existsSync(pidFile)) {
+    return { status: "not_running" };
+  }
+
+  const raw = fs.readFileSync(pidFile, "utf-8").trim();
+  const pid = parseInt(raw, 10);
+
+  if (isNaN(pid)) {
+    // Corrupt PID file — clean up and treat as not running
+    cleanupServerArtifacts(sessionDir);
+    return { status: "not_running" };
+  }
+
+  try {
+    process.kill(pid);
+  } catch (error) {
+    const code = (error as NodeJS.ErrnoException).code;
+    if (code !== "ESRCH") {
+      return { status: "failed" };
+    }
+  }
+
+  cleanupServerArtifacts(sessionDir);
+  return { status: "stopped" };
+}
+
+function cleanupServerArtifacts(sessionDir: string): void {
+  fs.rmSync(path.join(sessionDir, ".server.pid"), { force: true });
+  fs.rmSync(path.join(sessionDir, ".server.log"), { force: true });
+  fs.rmSync(path.join(sessionDir, ".server-info"), { force: true });
+}