@opensip-tools/contracts 1.0.4

package/src/persistence/store.ts

@@ -0,0 +1,233 @@
+/**
+ * JSON file persistence for opensip-tools results.
+ *
+ * Sessions land at `<project>/opensip-tools/.runtime/sessions/`
+ * (per-project). Each run creates one file:
+ * `{timestamp}-{tool}-{recipe}.json`.
+ *
+ * The CLI bootstrap calls `configurePersistencePaths(projectPaths)`
+ * once on startup with paths from `resolveProjectPaths(cwd)`. Until
+ * that call, the module falls back to a user-global location
+ * (`~/.opensip-tools/`) so any caller who imports persistence helpers
+ * before the CLI's preAction hook still gets a valid path. The
+ * fallback is also exercised by tests that don't bootstrap a CLI.
+ */
+
+import { randomUUID } from 'node:crypto';
+import { mkdirSync, readFileSync, readdirSync, writeFileSync, unlinkSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { basename, join } from 'node:path';
+
+import { logger } from '@opensip-tools/core';
+
+import type { ProjectPaths } from '@opensip-tools/core';
+
+export interface StoredSession {
+  readonly id: string;
+  readonly tool: 'fit' | 'sim';
+  readonly timestamp: string;
+  readonly cwd: string;
+  readonly recipe?: string;
+  readonly score: number;
+  readonly passed: boolean;
+  readonly summary: {
+    readonly total: number;
+    readonly passed: number;
+    readonly failed: number;
+    readonly errors: number;
+    readonly warnings: number;
+  };
+  readonly checks: readonly {
+    readonly checkSlug: string;
+    readonly passed: boolean;
+    readonly violationCount?: number;
+    readonly findings: readonly {
+      readonly ruleId: string;
+      readonly message: string;
+      readonly severity: string;
+      readonly filePath?: string;
+      readonly line?: number;
+      readonly column?: number;
+      readonly suggestion?: string;
+      readonly category?: string;
+    }[];
+    readonly durationMs: number;
+  }[];
+  readonly durationMs: number;
+}
+
+/** Check catalog entry for dashboard display */
+export interface CheckCatalogEntry {
+  readonly slug: string;
+  readonly name: string;
+  readonly icon: string;
+  readonly description: string;
+  readonly longDescription?: string;
+  readonly tags: readonly string[];
+  readonly confidence: 'high' | 'medium' | 'low';
+  readonly source: 'built-in' | 'community';
+}
+
+/** Recipe catalog entry for dashboard display */
+export interface RecipeCatalogEntry {
+  readonly name: string;
+  readonly displayName: string;
+  readonly description: string;
+  readonly tags: readonly string[];
+  readonly selectorType: string;
+  readonly mode: string;
+  readonly timeout: number;
+}
+
+/**
+ * Fallback path: user-global `~/.opensip-tools/`, used by tests and
+ * any code path that imports persistence helpers before the CLI has
+ * called `configurePersistencePaths`. New code should not rely on
+ * this fallback — call `configurePersistencePaths` first.
+ */
+export const TOOLS_HOME = join(homedir(), '.opensip-tools');
+
+/** Mutable per-process state — set by `configurePersistencePaths`. */
+let storeDir: string = join(TOOLS_HOME, 'sessions');
+let reportsDir: string = join(TOOLS_HOME, 'reports');
+const MAX_SESSIONS = 100;
+
+/**
+ * Configure where this module writes sessions and reports. Called
+ * once by the CLI bootstrap with the project paths. Idempotent and
+ * safe to call repeatedly (e.g. tests that switch project dirs).
+ */
+export function configurePersistencePaths(paths: Pick<ProjectPaths, 'sessionsDir' | 'reportsDir'>): void {
+  storeDir = paths.sessionsDir;
+  reportsDir = paths.reportsDir;
+}
+
+/** Ensure directory exists — mkdirSync with recursive is idempotent */
+function ensureDir(dir: string): void {
+  mkdirSync(dir, { recursive: true });
+}
+
+/** Sanitize a string for use in a filename — strip path separators and special chars */
+export function sanitizeForFilename(s: string): string {
+  return s.replaceAll('..', '-').replaceAll(/[/\\:*?"<>|.]/g, '-');
+}
+
+/** Save a session result to disk */
+export function saveSession(session: StoredSession): string {
+  ensureDir(storeDir);
+  const safeRecipe = session.recipe ? `-${sanitizeForFilename(session.recipe)}` : '';
+  const filename = `${session.timestamp.replaceAll(/[:.]/g, '-')}-${session.tool}${safeRecipe}.json`;
+  // Ensure filename stays within the sessions directory
+  const filepath = join(storeDir, basename(filename));
+  writeFileSync(filepath, JSON.stringify(session, null, 2), 'utf8');
+
+  pruneOldSessions();
+  return filepath;
+}
+
+/** Count session files in the store directory */
+export function countSessions(): number {
+  ensureDir(storeDir);
+  return readdirSync(storeDir).filter(f => f.endsWith('.json')).length;
+}
+
+/** Delete all sessions. Returns the number of files deleted. */
+export function clearAllSessions(): number {
+  ensureDir(storeDir);
+  const files = readdirSync(storeDir).filter(f => f.endsWith('.json'));
+  for (const file of files) {
+    unlinkSync(join(storeDir, file));
+  }
+  return files.length;
+}
+
+/** Delete sessions older than the given number of days. Returns the number of files deleted. */
+export function clearSessionsOlderThan(days: number): number {
+  ensureDir(storeDir);
+  const cutoff = Date.now() - days * 24 * 60 * 60 * 1000;
+  const files = readdirSync(storeDir).filter(f => f.endsWith('.json'));
+  let deleted = 0;
+
+  for (const file of files) {
+    try {
+      const filepath = join(storeDir, file);
+      const raw = readFileSync(filepath, 'utf8');
+      const session = JSON.parse(raw) as { timestamp?: string };
+      if (session.timestamp) {
+        const sessionTime = new Date(session.timestamp).getTime();
+        if (!Number.isNaN(sessionTime) && sessionTime < cutoff) {
+          unlinkSync(filepath);
+          deleted++;
+        }
+      }
+    } catch {
+      // Skip files that can't be read/parsed
+    }
+  }
+
+  return deleted;
+}
+
+/** Load all sessions, newest first. Optional limit to avoid reading everything. */
+export function loadSessions(limit?: number): StoredSession[] {
+  ensureDir(storeDir);
+  const files = readdirSync(storeDir)
+    .filter(f => f.endsWith('.json'))
+    .sort()
+    // eslint-disable-next-line unicorn/no-array-reverse -- target ES2022; Array#toReversed is ES2023 and not in the lib
+    .reverse();
+
+  const toRead = limit ? files.slice(0, limit) : files;
+  const sessions: StoredSession[] = [];
+  for (const file of toRead) {
+    try {
+      const raw = readFileSync(join(storeDir, file), 'utf8');
+      sessions.push(JSON.parse(raw) as StoredSession);
+    } catch {
+      // Warn about corrupted files — don't crash
+      logger.warn({ evt: 'cli.session.corrupted', module: 'cli:persistence', msg: `Skipping corrupted session file: ${file}`, file });
+    }
+  }
+  return sessions;
+}
+
+/** Load the most recent session */
+export function loadLatestSession(): StoredSession | null {
+  const sessions = loadSessions(1);
+  return sessions[0] ?? null;
+}
+
+/** Prune sessions beyond the max count */
+function pruneOldSessions(): void {
+  const files = readdirSync(storeDir)
+    .filter(f => f.endsWith('.json'))
+    .sort()
+    // eslint-disable-next-line unicorn/no-array-reverse -- target ES2022; Array#toReversed is ES2023 and not in the lib
+    .reverse();
+
+  if (files.length <= MAX_SESSIONS) return;
+
+  for (const file of files.slice(MAX_SESSIONS)) {
+    try {
+      unlinkSync(join(storeDir, file));
+    } catch {
+      // Best effort
+    }
+  }
+}
+
+/** Get the store directory path */
+export function getStoreDir(): string {
+  return storeDir;
+}
+
+/** Get the reports directory path, creating it if needed */
+export function getReportsDir(): string {
+  ensureDir(reportsDir);
+  return reportsDir;
+}
+
+/** Generate a unique session ID */
+export function generateSessionId(): string {
+  return randomUUID();
+}

package/src/types.ts

@@ -0,0 +1,306 @@
+import type { StoredSession } from './persistence/store.js';
+
+// =============================================================================
+// CLI OPTIONS TYPES
+// =============================================================================
+
+/** Options for the `fit` subcommand (derived from Commander flags). */
+export interface FitOptions {
+  recipe?: string;
+  check?: string;
+  tags?: string;
+  list: boolean;
+  recipes: boolean;
+  json: boolean;
+  verbose: boolean;
+  findings: boolean;
+  reportTo?: string;
+  apiKey?: string;
+  exclude: string[];
+  cwd: string;
+  /** Explicit path to opensip-tools.config.yml (overrides package.json pointer and default location). */
+  config?: string;
+  debug: boolean;
+  /** Architecture-gate: save the current run's findings as a baseline. Mutually exclusive with --gate-compare. */
+  gateSave?: boolean;
+  /** Architecture-gate: compare current findings against a saved baseline; exit 1 if regressions found. Mutually exclusive with --gate-save. */
+  gateCompare?: boolean;
+  /** Path to the baseline file used by --gate-save / --gate-compare. Default: opensip-tools/.runtime/baseline.sarif */
+  baseline?: string;
+}
+
+/** Options for the `init` subcommand. */
+export interface InitOptions {
+  cwd: string;
+  json: boolean;
+  debug: boolean;
+  /**
+   * Comma-separated language list. When omitted, init detects the
+   * project's primary language(s) by inspecting filesystem markers
+   * (Cargo.toml, pyproject.toml, etc.) and exits 2 with a prompt if
+   * the result is ambiguous.
+   */
+  language?: string;
+  /**
+   * Overwrite an existing opensip-tools.config.yml or example files
+   * without prompting. Default false — the safe behavior is to refuse
+   * overwriting.
+   */
+  force: boolean;
+}
+
+/** Options for `sim` subcommand. */
+export interface ToolOptions {
+  cwd: string;
+  json: boolean;
+  debug: boolean;
+  /** Recipe name to run. Defaults to the built-in `default` if omitted. */
+  recipe?: string;
+  /** Filter by scenario kind (load / chaos / invariant / fix-evaluation). */
+  kind?: string;
+}
+
+/**
+ * Backwards-compatible alias — commands that previously accepted CliArgs
+ * can accept this union instead. The shape covers all fields used by any command.
+ */
+export interface CliArgs {
+  command: string;
+  json: boolean;
+  check?: string;
+  recipe?: string;
+  cwd: string;
+  help: boolean;
+  list: boolean;
+  listRecipes: boolean;
+  verbose: boolean;
+  reportTo?: string;
+  apiKey?: string;
+  exclude: string[];
+  findings: boolean;
+  tags?: string;
+  /** Suppress banner/boxes; show only the pass-fail summary line. */
+  quiet?: boolean;
+  /** Open the HTML dashboard in the default browser after a successful run. */
+  open?: boolean;
+  /** Explicit opensip-tools.config.yml path from --config flag. */
+  config?: string;
+  /** Architecture-gate flags — see FitOptions for details. */
+  gateSave?: boolean;
+  gateCompare?: boolean;
+  baseline?: string;
+  /**
+   * Sim-only: filter scenarios by kind.
+   * One of 'load' | 'chaos' | 'invariant' | 'fix-evaluation', or undefined for all.
+   */
+  kind?: string;
+}
+
+/** Structured JSON output format */
+export interface CliOutput {
+  readonly version: '1.0';
+  readonly tool: 'fit' | 'sim';
+  readonly timestamp: string;
+  readonly recipe?: string;
+  readonly score: number;
+  readonly passed: boolean;
+  readonly summary: { total: number; passed: number; failed: number; errors: number; warnings: number };
+  readonly checks: readonly CheckOutput[];
+  readonly durationMs: number;
+}
+
+export interface CheckOutput {
+  readonly checkSlug: string;
+  readonly passed: boolean;
+  readonly violationCount?: number;
+  readonly findings: readonly FindingOutput[];
+  readonly durationMs: number;
+}
+
+export interface FindingOutput {
+  readonly ruleId: string;
+  readonly message: string;
+  readonly severity: 'error' | 'warning';
+  readonly filePath?: string;
+  readonly line?: number;
+  readonly column?: number;
+  readonly suggestion?: string;
+}
+
+export interface TableRow {
+  check: string;
+  status: 'PASS' | 'FAIL' | 'TIMEOUT';
+  errors: number;
+  warnings: number;
+  validated: string;
+  ignored: number;
+  duration: string;
+  durationMs: number;
+}
+
+export interface SummaryOptions {
+  passed: number;
+  failed: number;
+  totalErrors: number;
+  totalWarnings: number;
+  totalIgnored: number;
+  durationMs: number;
+}
+
+// =============================================================================
+// CommandResult — union type for all command results
+// =============================================================================
+
+/** Union type for all command results — App.tsx dispatches on result.type */
+export type CommandResult =
+  | FitDoneResult
+  | SimDoneResult
+  | ListChecksResult
+  | ListRecipesResult
+  | HistoryResult
+  | DashboardResult
+  | InitResult
+  | ExperimentalResult
+  | PluginResult
+  | ClearDoneResult
+  | HelpResult
+  | ErrorResult;
+
+export interface ClearDoneResult {
+  type: 'clear-done';
+  action: 'done' | 'cancelled' | 'empty';
+  deletedCount: number;
+  sessionCount: number;
+}
+
+export interface FitDoneResult {
+  type: 'fit-done';
+  rows: TableRow[];
+  summary: SummaryOptions;
+  label: string;
+  cwd: string;
+  findings?: {
+    checks: {
+      checkSlug: string;
+      errorCount: number;
+      warningCount: number;
+      error?: string;
+      violations?: {
+        severity: 'error' | 'warning';
+        message: string;
+        file?: string;
+        line?: number;
+        suggestion?: string;
+      }[];
+    }[];
+  };
+  reportStatus?: {
+    url: string;
+    findingCount: number;
+    runCount: number;
+    success: boolean;
+    error?: string;
+    chunksTotal?: number;
+    chunksSucceeded?: number;
+  };
+  /** Whether the run should cause a non-zero exit code (based on failOnErrors/failOnWarnings config) */
+  shouldFail?: boolean;
+  /** Whether an opensip-tools.config.yml was found in the target directory */
+  configFound?: boolean;
+}
+
+export interface ListChecksResult {
+  type: 'list-checks';
+  checks: { slug: string; description: string; tags: string[] }[];
+  totalCount: number;
+}
+
+export interface ListRecipesResult {
+  type: 'list-recipes';
+  recipes: { name: string; description: string; checkCount: string }[];
+}
+
+export interface HistoryResult {
+  type: 'history';
+  sessions: StoredSession[];
+}
+
+export interface DashboardResult {
+  type: 'dashboard';
+  path: string;
+  opened: boolean;
+}
+
+export interface InitResult {
+  type: 'init';
+  created: boolean;
+  path: string;
+  alreadyExists: boolean;
+  cwd: string;
+  configFilename: string;
+  /** Languages selected for this scaffold (post-detection or from --language). */
+  languages?: readonly ('typescript' | 'rust' | 'python' | 'go' | 'java' | 'cpp')[];
+  /**
+   * Every file init created, in display order. Includes the config
+   * file plus example check / recipe / scenario scaffolds. Empty
+   * when alreadyExists is true (nothing was written).
+   */
+  createdFiles?: readonly string[];
+  /** True when init appended `opensip-tools/.runtime/` to .gitignore. */
+  gitignoreUpdated?: boolean;
+  /**
+   * When detection is ambiguous and --language wasn't passed, init
+   * exits without writing anything and surfaces this error so the
+   * user can re-invoke with --language <list>.
+   */
+  ambiguousLanguageError?: {
+    detected: readonly string[];
+    message: string;
+  };
+}
+
+export interface ExperimentalResult {
+  type: 'experimental';
+  tool: 'sim';
+  cwd: string;
+  /** Optional `--kind` filter (load / chaos / invariant / fix-evaluation). */
+  kind?: string;
+}
+
+/** Outcome of a `sim --recipe <name>` run. */
+export interface SimDoneResult {
+  type: 'sim-done';
+  recipeName: string;
+  cwd: string;
+  totalScenarios: number;
+  passedScenarios: number;
+  failedScenarios: number;
+  scenarios: {
+    scenarioId: string;
+    scenarioName: string;
+    kind: 'load' | 'chaos' | 'invariant' | 'fix-evaluation';
+    passed: boolean;
+    durationMs: number;
+    error?: string;
+  }[];
+  durationMs: number;
+  /** Whether the run should cause a non-zero exit code (any scenario failed). */
+  shouldFail?: boolean;
+}
+
+export interface PluginResult {
+  type: 'plugin';
+  action: 'list' | 'install' | 'remove' | 'sync' | 'add';
+  [key: string]: unknown;
+}
+
+export interface HelpResult {
+  type: 'help';
+}
+
+export interface ErrorResult {
+  type: 'error';
+  message: string;
+  suggestion?: string;
+  exitCode: number;
+}

package/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src"
+  },
+  "include": ["src"]
+}

package/vitest.config.ts

@@ -0,0 +1,16 @@
+import { defineConfig } from 'vitest/config';
+export default defineConfig({
+  test: {
+    include: ['src/**/*.test.ts'],
+    passWithNoTests: true,
+    coverage: {
+      include: ['src/**'],
+      exclude: [
+        'src/**/*.test.ts',
+        'src/**/__tests__/**',
+        'src/**/index.ts',
+        'src/types.ts',
+      ],
+    },
+  },
+});