@cleocode/contracts 2026.4.154 → 2026.4.157

package/src/operations/nexus.ts

@@ -963,6 +963,238 @@ export interface NexusContractsLinkTasksParams {
 /** Result of `nexus.contracts-link-tasks`. */
 export type NexusContractsLinkTasksResult = unknown;
 
+// ============================================================================
+// T1510 — Phase 2 dispatch ops (clusters, flows, context, projects.*, diff,
+//          refresh-bridge, query-cte, hot-paths, hot-nodes, cold-symbols)
+// ============================================================================
+
+/** Parameters for `nexus.clusters`. */
+export interface NexusClustersParams {
+  /** Project ID (optional, auto-generated from repoPath). */
+  projectId?: string;
+  /** Path to project directory (optional, defaults to cwd). */
+  repoPath?: string;
+}
+/** One detected Louvain community entry. */
+export interface NexusCommunityEntry {
+  id: string;
+  label: string | null;
+  symbolCount: number;
+  cohesion: number;
+}
+/** Result of `nexus.clusters`. */
+export interface NexusClustersResult {
+  projectId: string;
+  repoPath: string;
+  count: number;
+  communities: NexusCommunityEntry[];
+}
+
+/** Parameters for `nexus.flows`. */
+export interface NexusFlowsParams {
+  /** Project ID (optional, auto-generated from repoPath). */
+  projectId?: string;
+  /** Path to project directory (optional, defaults to cwd). */
+  repoPath?: string;
+}
+/** One detected execution flow entry. */
+export interface NexusFlowEntry {
+  id: string;
+  label: string | null;
+  stepCount: number;
+  processType: string;
+  entryPointId: string | null;
+}
+/** Result of `nexus.flows`. */
+export interface NexusFlowsResult {
+  projectId: string;
+  repoPath: string;
+  count: number;
+  flows: NexusFlowEntry[];
+}
+
+/** Parameters for `nexus.context`. */
+export interface NexusContextParams {
+  /** Symbol name to look up (required). */
+  symbol: string;
+  /** Project ID (optional, auto-generated from cwd). */
+  projectId?: string;
+  /** Max callers/callees per side (default: 20). */
+  limit?: number;
+  /** When true, fetch source code content. */
+  content?: boolean;
+}
+/** Result of `nexus.context`. */
+export type NexusContextResult = unknown;
+
+/** Parameters for `nexus.projects.list`. */
+export type NexusProjectsListParams = Record<string, never>;
+/** Result of `nexus.projects.list`. */
+export type NexusProjectsListResult = unknown;
+
+/** Parameters for `nexus.projects.register`. */
+export interface NexusProjectsRegisterParams {
+  /** Path to the project directory (required). */
+  path: string;
+  /** Custom project name (optional). */
+  name?: string;
+}
+/** Result of `nexus.projects.register`. */
+export interface NexusProjectsRegisterResult {
+  hash: string;
+  path: string;
+}
+
+/** Parameters for `nexus.projects.remove`. */
+export interface NexusProjectsRemoveParams {
+  /** Project name or hash to remove (required). */
+  nameOrHash: string;
+}
+/** Result of `nexus.projects.remove`. */
+export interface NexusProjectsRemoveResult {
+  removed: string;
+}
+
+/** Parameters for `nexus.projects.scan`. */
+export interface NexusProjectsScanParams {
+  /** Comma-separated search roots (optional). */
+  roots?: string;
+  /** Maximum directory traversal depth (default: 4). */
+  maxDepth?: number;
+  /** Auto-register all discovered unregistered projects. */
+  autoRegister?: boolean;
+  /** Also report already-registered projects. */
+  includeExisting?: boolean;
+}
+/** Result of `nexus.projects.scan`. */
+export type NexusProjectsScanResult = unknown;
+
+/** Parameters for `nexus.projects.clean`. */
+export interface NexusProjectsCleanParams {
+  /** Dry-run only (no deletions). */
+  dryRun?: boolean;
+  /** JS regex matched against project_path. */
+  pattern?: string;
+  /** Match paths containing a .temp/ segment. */
+  includeTemp?: boolean;
+  /** Match paths containing tmp/test/fixture/scratch/sandbox segments. */
+  includeTests?: boolean;
+  /** Also match unhealthy rows. */
+  matchUnhealthy?: boolean;
+  /** Also match never-indexed rows. */
+  matchNeverIndexed?: boolean;
+}
+/** Result of `nexus.projects.clean`. */
+export type NexusProjectsCleanResult = unknown;
+
+/** Parameters for `nexus.refresh-bridge`. */
+export interface NexusRefreshBridgeParams {
+  /** Path to project directory (optional, defaults to cwd). */
+  repoPath?: string;
+  /** Override the project ID. */
+  projectId?: string;
+}
+/** Result of `nexus.refresh-bridge`. */
+export interface NexusRefreshBridgeResult {
+  path: string;
+  written: boolean;
+  projectId: string;
+  repoPath: string;
+}
+
+/** Parameters for `nexus.diff`. */
+export interface NexusDiffParams {
+  /** Git ref for the "before" snapshot (default: HEAD~1). */
+  beforeRef?: string;
+  /** Git ref for the "after" snapshot (default: HEAD). */
+  afterRef?: string;
+  /** Repository path (optional, defaults to cwd). */
+  repoPath?: string;
+  /** Override the project ID. */
+  projectId?: string;
+}
+/** Result of `nexus.diff`. */
+export type NexusDiffResult = unknown;
+
+/** Parameters for `nexus.query-cte`. */
+export interface NexusQueryCteParams {
+  /** CTE SQL or template alias (required). */
+  cte: string;
+  /** Positional parameters for the CTE (optional). */
+  params?: string[];
+}
+/** Result of `nexus.query-cte`. */
+export type NexusQueryCteResult = unknown;
+
+/** One hot-path relation edge. */
+export interface NexusHotPath {
+  sourceId: string;
+  targetId: string;
+  type: string;
+  weight: number;
+  lastAccessedAt: string | null;
+  coAccessedCount: number;
+}
+/** Parameters for `nexus.hot-paths`. */
+export interface NexusHotPathsParams {
+  /** Maximum number of edges to return (default: 20). */
+  limit?: number;
+}
+/** Result of `nexus.hot-paths`. */
+export interface NexusHotPathsResult {
+  paths: NexusHotPath[];
+  count: number;
+  note?: string;
+}
+
+/** One hot-node symbol. */
+export interface NexusHotNode {
+  nodeId: string;
+  sourceId: string;
+  label: string;
+  filePath: string | null;
+  kind: string;
+  totalWeight: number;
+  pathCount: number;
+}
+/** Parameters for `nexus.hot-nodes`. */
+export interface NexusHotNodesParams {
+  /** Maximum number of nodes to return (default: 20). */
+  limit?: number;
+}
+/** Result of `nexus.hot-nodes`. */
+export interface NexusHotNodesResult {
+  nodes: NexusHotNode[];
+  count: number;
+  note?: string;
+}
+
+/** One cold symbol. */
+export interface NexusColdSymbol {
+  nodeId: string;
+  sourceId: string;
+  label: string;
+  filePath: string | null;
+  kind: string;
+  lastAccessedAt: string | null;
+  lastAccessed: string | null;
+  ageDays: number | null;
+  pathCount: number;
+  maxWeight: number;
+}
+/** Parameters for `nexus.cold-symbols`. */
+export interface NexusColdSymbolsParams {
+  /** Age threshold in days (default: 30). */
+  days?: number;
+}
+/** Result of `nexus.cold-symbols`. */
+export interface NexusColdSymbolsResult {
+  symbols: NexusColdSymbol[];
+  count: number;
+  thresholdDays: number;
+  note?: string;
+}
+
 // ============================================================================
 // Typed Operations Union (T1424 — Wave D typed-dispatch migration)
 // ============================================================================
@@ -1034,4 +1266,19 @@ export type NexusOps = {
     NexusContractsLinkTasksResult,
   ];
   readonly 'conduit-scan': readonly [NexusConduitScanParams, NexusConduitScanResult];
+  // T1510 — Phase 2 dispatch ops
+  readonly clusters: readonly [NexusClustersParams, NexusClustersResult];
+  readonly flows: readonly [NexusFlowsParams, NexusFlowsResult];
+  readonly context: readonly [NexusContextParams, NexusContextResult];
+  readonly 'projects.list': readonly [NexusProjectsListParams, NexusProjectsListResult];
+  readonly 'projects.register': readonly [NexusProjectsRegisterParams, NexusProjectsRegisterResult];
+  readonly 'projects.remove': readonly [NexusProjectsRemoveParams, NexusProjectsRemoveResult];
+  readonly 'projects.scan': readonly [NexusProjectsScanParams, NexusProjectsScanResult];
+  readonly 'projects.clean': readonly [NexusProjectsCleanParams, NexusProjectsCleanResult];
+  readonly 'refresh-bridge': readonly [NexusRefreshBridgeParams, NexusRefreshBridgeResult];
+  readonly diff: readonly [NexusDiffParams, NexusDiffResult];
+  readonly 'query-cte': readonly [NexusQueryCteParams, NexusQueryCteResult];
+  readonly 'hot-paths': readonly [NexusHotPathsParams, NexusHotPathsResult];
+  readonly 'hot-nodes': readonly [NexusHotNodesParams, NexusHotNodesResult];
+  readonly 'cold-symbols': readonly [NexusColdSymbolsParams, NexusColdSymbolsResult];
 };

package/src/release/pipeline.ts

@@ -0,0 +1,100 @@
+/**
+ * Release pipeline contracts — canonical 4-step release flow types.
+ *
+ * Defines the type surface shared by `@cleocode/core/release/pipeline` and
+ * `@cleocode/cleo/cli/commands/release` for the canonical pipeline:
+ *
+ *   start → verify → publish → reconcile
+ *
+ * All types are project-agnostic. Concrete commands and version-scheme rules
+ * resolve at runtime from `.cleo/project-context.json`.
+ *
+ * @task T1597
+ * @adr ADR-063
+ */
+
+/**
+ * Supported version schemes. Mirrors `version.scheme` in
+ * `.cleo/project-context.json`. `auto` defers to per-project detection
+ * (CalVer for projects whose current version matches `YYYY.M.P`, SemVer
+ * otherwise).
+ */
+export type ReleaseVersionScheme = 'calver' | 'semver' | 'sha' | 'auto';
+
+/**
+ * Handle returned by {@link releaseStart} and threaded through the rest of
+ * the pipeline. Persisted under `.cleo/release/handle.json` so that
+ * `cleo release verify` / `publish` / `reconcile` can resume without
+ * re-passing `--version` on every step.
+ */
+export interface ReleaseHandle {
+  /** Resolved version string (e.g. "2026.4.155" or "1.4.2"). */
+  version: string;
+  /** Resolved release tag (e.g. "v2026.4.155"). */
+  tag: string;
+  /** Active version scheme used for validation. */
+  scheme: ReleaseVersionScheme;
+  /** Branch the release is being cut from (resolved from git). */
+  branch: string;
+  /** ISO-8601 timestamp of `releaseStart`. */
+  startedAt: string;
+  /** Absolute project root the pipeline is operating against. */
+  projectRoot: string;
+  /** Optional epic ID this release ships (for reconcile auto-completion). */
+  epicId?: string;
+}
+
+/** Per-gate verification status. */
+export interface ReleaseGateStatus {
+  /** Canonical gate name (test/lint/typecheck/audit/security-scan). */
+  gate: string;
+  /** Whether the gate passed. */
+  passed: boolean;
+  /** Tool that was invoked (resolved via project-context). */
+  tool?: string;
+  /** Human-readable reason on failure. */
+  reason?: string;
+}
+
+/** Result of {@link releaseVerify}. */
+export interface VerifyResult {
+  /** All gates passed AND all child tasks have green gates. */
+  passed: boolean;
+  /** Per-gate results. */
+  gates: ReleaseGateStatus[];
+  /** Tasks discovered as children of the release epic with ungreen gates. */
+  ungreenChildren: Array<{
+    taskId: string;
+    missingGates: string[];
+  }>;
+  /** Total tasks examined under the release epic (0 if no epic). */
+  childrenExamined: number;
+}
+
+/** Result of {@link releasePublish}. */
+export interface PublishResult {
+  /** Whether publish succeeded. */
+  success: boolean;
+  /** Command that was executed (after project-context resolution). */
+  command: string;
+  /** Combined stdout/stderr (truncated). */
+  output: string;
+  /** Artifact identifier on the registry, when extractable (e.g. npm tag). */
+  artifact?: string;
+  /** Whether the publish was a dry-run (no remote mutation). */
+  dryRun: boolean;
+}
+
+/** Result of {@link releaseReconcile}. */
+export interface ReleaseReconcileResult {
+  /** Whether reconcile completed without errors. */
+  success: boolean;
+  /** The tag reconciled. */
+  tag: string;
+  /** Tasks auto-completed by archive-reason invariant. */
+  reconciledTasks: string[];
+  /** Tasks that need operator follow-up. */
+  unreconciledTasks: string[];
+  /** Errors raised by any invariant. */
+  errors: string[];
+}