@azizbekdevuz/gitguard-schema 1.0.0

package/dist/snapshot.js

@@ -0,0 +1,88 @@
+import { z } from 'zod';
+// Conflict block extracted from a file
+export const ConflictBlockSchema = z.object({
+    startLine: z.number(),
+    endLine: z.number(),
+    oursContent: z.string(),
+    theirsContent: z.string(),
+    context: z.string(), // surrounding lines for context
+});
+// Unmerged file with conflict details
+export const UnmergedFileSchema = z.object({
+    path: z.string(),
+    stageOurs: z.string().optional(), // mode info
+    stageTheirs: z.string().optional(),
+    stageBase: z.string().optional(),
+    conflictBlocks: z.array(ConflictBlockSchema).max(3), // up to 3 blocks
+});
+// Branch info from porcelain v2
+export const BranchInfoSchema = z.object({
+    head: z.string(), // branch name or "(detached)"
+    oid: z.string(), // current commit hash
+    upstream: z.string().optional(),
+    aheadBehind: z.object({
+        ahead: z.number(),
+        behind: z.number(),
+    }).optional(),
+});
+// Reflog entry
+export const ReflogEntrySchema = z.object({
+    hash: z.string(),
+    selector: z.string(), // e.g., HEAD@{0}
+    action: z.string(),
+    message: z.string(),
+});
+// Log entry
+export const LogEntrySchema = z.object({
+    hash: z.string(),
+    refs: z.array(z.string()), // decorations
+    message: z.string(),
+});
+// Rebase state info
+export const RebaseStateSchema = z.object({
+    inProgress: z.boolean(),
+    type: z.enum(['merge', 'apply', 'none']),
+    headName: z.string().optional(), // original branch
+    onto: z.string().optional(),
+    currentStep: z.number().optional(),
+    totalSteps: z.number().optional(),
+});
+// Diff stat for a file
+export const DiffStatSchema = z.object({
+    path: z.string(),
+    additions: z.number(),
+    deletions: z.number(),
+    binary: z.boolean().optional(),
+});
+// Main snapshot schema
+export const SnapshotV1Schema = z.object({
+    version: z.literal(1),
+    timestamp: z.string().datetime(),
+    platform: z.enum(['win32', 'darwin', 'linux']),
+    repoRoot: z.string(),
+    gitDir: z.string(),
+    // Branch state
+    branch: BranchInfoSchema,
+    isDetachedHead: z.boolean(),
+    // Rebase state
+    rebaseState: RebaseStateSchema,
+    // Working tree status
+    unmergedFiles: z.array(UnmergedFileSchema).max(5), // increased for better conflict exploration
+    stagedFiles: z.array(z.string()),
+    modifiedFiles: z.array(z.string()),
+    untrackedFiles: z.array(z.string()),
+    // History
+    recentLog: z.array(LogEntrySchema).max(30),
+    recentReflog: z.array(ReflogEntrySchema).max(30),
+    // NEW: Commit graph for history visualization
+    commitGraph: z.string().optional(), // git log --graph --oneline output
+    // NEW: Diff stats for file-level summary
+    diffStats: z.array(DiffStatSchema).optional(),
+    // NEW: Merge metadata
+    mergeHead: z.string().optional(), // MERGE_HEAD commit if in merge
+    mergeMessage: z.string().optional(), // Default merge commit message
+    // Raw outputs for debugging
+    rawStatus: z.string(),
+    rawBranches: z.string(),
+});
+//# sourceMappingURL=snapshot.js.map

package/dist/snapshot.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot.js","sourceRoot":"","sources":["../src/snapshot.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@azizbekdevuz/gitguard-schema",
+  "version": "1.0.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "dev": "tsc --watch"
+  },
+  "dependencies": {
+    "zod": "^3.24.1"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.2"
+  }
+}

package/src/analysis.ts

@@ -0,0 +1,134 @@
+import { z } from 'zod';
+
+// Issue types we detect
+export const IssueTypeSchema = z.enum([
+  'merge_conflict',
+  'detached_head',
+  'rebase_in_progress',
+  'clean',
+  'unknown',
+]);
+
+export type IssueType = z.infer<typeof IssueTypeSchema>;
+
+// Danger levels for plan steps
+export const DangerLevelSchema = z.enum(['safe', 'caution', 'dangerous']);
+
+export type DangerLevel = z.infer<typeof DangerLevelSchema>;
+
+// Choice for conflict resolution
+export const HunkChoiceSchema = z.enum(['ours', 'theirs', 'manual', 'combine']);
+
+export type HunkChoice = z.infer<typeof HunkChoiceSchema>;
+
+// ==========================================
+// Repo Graph for Visualization
+// ==========================================
+
+export const GraphNodeSchema = z.object({
+  id: z.string(),
+  type: z.enum(['commit', 'branch', 'tag', 'head', 'remote']),
+  label: z.string(),
+  sha: z.string().optional(),
+  isCurrent: z.boolean().optional(),
+  isDetached: z.boolean().optional(),
+});
+
+export type GraphNode = z.infer<typeof GraphNodeSchema>;
+
+export const GraphEdgeSchema = z.object({
+  from: z.string(),
+  to: z.string(),
+  type: z.enum(['parent', 'branch', 'merge']).optional(),
+});
+
+export type GraphEdge = z.infer<typeof GraphEdgeSchema>;
+
+export const RepoGraphSchema = z.object({
+  nodes: z.array(GraphNodeSchema),
+  edges: z.array(GraphEdgeSchema),
+  headRef: z.string().optional(),
+  mergeHeadRef: z.string().optional(),
+});
+
+export type RepoGraph = z.infer<typeof RepoGraphSchema>;
+
+// ==========================================
+// Conflict Hunks
+// ==========================================
+
+export const ConflictHunkSchema = z.object({
+  index: z.number(),
+  startLine: z.number().optional(),
+  endLine: z.number().optional(),
+  baseText: z.string(),
+  oursText: z.string(),
+  theirsText: z.string(),
+  explanation: z.string().optional(),
+  suggestedChoice: HunkChoiceSchema.optional(),
+  suggestedContent: z.string().optional(),
+});
+
+export type ConflictHunk = z.infer<typeof ConflictHunkSchema>;
+
+export const ConflictFileSchema = z.object({
+  path: z.string(),
+  highLevelSummary: z.string().optional(),
+  hunks: z.array(ConflictHunkSchema),
+});
+
+export type ConflictFile = z.infer<typeof ConflictFileSchema>;
+
+// ==========================================
+// Plan Steps
+// ==========================================
+
+export const PlanStepSchema = z.object({
+  index: z.number(),
+  title: z.string(),
+  rationale: z.string().optional(),
+  commands: z.array(z.string()),
+  verify: z.array(z.string()),
+  undo: z.array(z.string()),
+  dangerLevel: DangerLevelSchema,
+});
+
+export type PlanStep = z.infer<typeof PlanStepSchema>;
+
+// ==========================================
+// Full Analysis Result
+// ==========================================
+
+export const AnalysisResultSchema = z.object({
+  issueType: IssueTypeSchema,
+  summary: z.string(),
+  repoGraph: RepoGraphSchema.optional(),
+  conflicts: z.array(ConflictFileSchema).optional(),
+  plan: z.array(PlanStepSchema),
+});
+
+export type AnalysisResult = z.infer<typeof AnalysisResultSchema>;
+
+// ==========================================
+// Agent API Request/Response
+// ==========================================
+
+export const AnalyzeRequestSchema = z.object({
+  snapshot: z.any(), // SnapshotV1
+  options: z.object({
+    includeGraph: z.boolean().optional(),
+    maxConflictFiles: z.number().optional(),
+    maxHunksPerFile: z.number().optional(),
+  }).optional(),
+});
+
+export type AnalyzeRequest = z.infer<typeof AnalyzeRequestSchema>;
+
+export const AnalyzeResponseSchema = z.object({
+  success: z.boolean(),
+  analysis: AnalysisResultSchema.optional(),
+  error: z.string().optional(),
+  durationMs: z.number().optional(),
+});
+
+export type AnalyzeResponse = z.infer<typeof AnalyzeResponseSchema>;

package/src/api.ts

@@ -0,0 +1,189 @@
+import { z } from 'zod';
+import { SnapshotV1Schema, type SnapshotV1 } from './snapshot.js';
+import { PlanV1Schema, type PlanV1, VerificationResultSchema, type VerificationResult } from './plan.js';
+import { SignalsSchema, type Signals } from './signals.js';
+
+// ==========================================
+// Session API Types
+// ==========================================
+
+// POST /api/sessions - Create new session
+export const CreateSessionRequestSchema = z.object({
+  snapshot: SnapshotV1Schema,
+});
+
+export type CreateSessionRequest = z.infer<typeof CreateSessionRequestSchema>;
+
+export const CreateSessionResponseSchema = z.object({
+  sessionId: z.string(),
+});
+
+export type CreateSessionResponse = z.infer<typeof CreateSessionResponseSchema>;
+
+// GET /api/sessions/[id] - Get session details
+export const TraceOutputSchema = z.object({
+  stage: z.string(),
+  output: z.unknown(),
+  createdAt: z.string(),
+  durationMs: z.number().nullable(),
+});
+
+export type TraceOutput = z.infer<typeof TraceOutputSchema>;
+
+export const SessionSummarySchema = z.object({
+  id: z.string(),
+  title: z.string().nullable(),
+  createdAt: z.string(),
+});
+
+export type SessionSummary = z.infer<typeof SessionSummarySchema>;
+
+export const GetSessionResponseSchema = z.object({
+  session: SessionSummarySchema,
+  snapshot: SnapshotV1Schema,
+  signals: SignalsSchema.nullable(),
+  plan: PlanV1Schema.nullable(),
+  traces: z.array(TraceOutputSchema),
+});
+
+export type GetSessionResponse = z.infer<typeof GetSessionResponseSchema>;
+
+// ==========================================
+// Plan API Types
+// ==========================================
+
+// POST /api/sessions/[id]/plan - Generate plan
+export const GeneratePlanRequestSchema = z.object({
+  dangerousAllowed: z.boolean().optional().default(false),
+});
+
+export type GeneratePlanRequest = z.infer<typeof GeneratePlanRequestSchema>;
+
+export const GeneratePlanResponseSchema = z.object({
+  plan: PlanV1Schema,
+});
+
+export type GeneratePlanResponse = z.infer<typeof GeneratePlanResponseSchema>;
+
+// ==========================================
+// Verify API Types
+// ==========================================
+
+// POST /api/sessions/[id]/verify - Verify progress
+export const VerifyProgressRequestSchema = z.object({
+  snapshot: SnapshotV1Schema,
+});
+
+export type VerifyProgressRequest = z.infer<typeof VerifyProgressRequestSchema>;
+
+export const VerifyProgressResponseSchema = VerificationResultSchema;
+
+export type VerifyProgressResponse = VerificationResult;
+
+// ==========================================
+// Explain API Types
+// ==========================================
+
+// POST /api/sessions/[id]/explain - Get AI explanation
+export const ExplainConflictRequestSchema = z.object({
+  type: z.literal('conflict'),
+  fileIndex: z.number(),
+  blockIndex: z.number(),
+});
+
+export const ExplainStateRequestSchema = z.object({
+  type: z.literal('state'),
+});
+
+export const ExplainRequestSchema = z.discriminatedUnion('type', [
+  ExplainConflictRequestSchema,
+  ExplainStateRequestSchema,
+]);
+
+export type ExplainRequest = z.infer<typeof ExplainRequestSchema>;
+
+// Conflict explanation response
+export const ConflictExplanationSchema = z.object({
+  summary: z.string(),
+  oursInterpretation: z.string(),
+  theirsInterpretation: z.string(),
+  suggestedResolution: z.string(),
+  riskNotes: z.string().optional(),
+});
+
+export type ConflictExplanation = z.infer<typeof ConflictExplanationSchema>;
+
+// State explanation response
+export const StateExplanationSchema = z.object({
+  summary: z.string(),
+  howItHappened: z.string(),
+  currentPosition: z.string(),
+  safeNextSteps: z.array(z.string()),
+  warnings: z.array(z.string()).optional(),
+});
+
+export type StateExplanation = z.infer<typeof StateExplanationSchema>;
+
+export const ExplainResponseSchema = z.object({
+  explanation: z.union([ConflictExplanationSchema, StateExplanationSchema]),
+});
+
+export type ExplainResponse = z.infer<typeof ExplainResponseSchema>;
+
+// ==========================================
+// Auth API Types
+// ==========================================
+
+// POST /api/auth/register - Register new user
+export const RegisterRequestSchema = z.object({
+  name: z.string().optional(),
+  email: z.string().email(),
+  password: z.string().min(8),
+});
+
+export type RegisterRequest = z.infer<typeof RegisterRequestSchema>;
+
+export const RegisterResponseSchema = z.object({
+  user: z.object({
+    id: z.string(),
+    name: z.string().nullable(),
+    email: z.string(),
+  }),
+});
+
+export type RegisterResponse = z.infer<typeof RegisterResponseSchema>;
+
+// ==========================================
+// Error Response
+// ==========================================
+
+export const ApiErrorSchema = z.object({
+  error: z.string(),
+});
+
+export type ApiError = z.infer<typeof ApiErrorSchema>;
+
+// ==========================================
+// History Types (for session list page)
+// ==========================================
+
+export const SessionListItemSchema = z.object({
+  id: z.string(),
+  title: z.string().nullable(),
+  createdAt: z.string(),
+  os: z.string().nullable(),
+  hasPlan: z.boolean(),
+  issueType: z.string().nullable(),
+  risk: z.string().nullable(),
+});
+
+export type SessionListItem = z.infer<typeof SessionListItemSchema>;
+
+export const SessionListResponseSchema = z.object({
+  sessions: z.array(SessionListItemSchema),
+  total: z.number(),
+  page: z.number(),
+  pageSize: z.number(),
+});
+
+export type SessionListResponse = z.infer<typeof SessionListResponseSchema>;

package/src/index.ts

@@ -0,0 +1,16 @@
+export * from './snapshot.js';
+export * from './signals.js';
+export * from './api.js';
+
+// Export from plan.js but exclude types that are redefined in analysis.js
+export {
+  RiskLevelSchema,
+  RiskLevel,
+  PlanV1Schema,
+  PlanV1,
+  VerificationResultSchema,
+  VerificationResult,
+} from './plan.js';
+
+// Export everything from analysis.js (has updated IssueType, PlanStep, etc.)
+export * from './analysis.js';

package/src/plan.ts

@@ -0,0 +1,74 @@
+import { z } from 'zod';
+
+// Issue types we handle
+export const IssueTypeSchema = z.enum([
+  'merge_conflict',
+  'detached_head',
+  'rebase_in_progress',
+  'clean',
+  'unknown',
+]);
+
+export type IssueType = z.infer<typeof IssueTypeSchema>;
+
+// Risk levels
+export const RiskLevelSchema = z.enum(['low', 'medium', 'high']);
+
+export type RiskLevel = z.infer<typeof RiskLevelSchema>;
+
+// A single step in the recovery plan
+export const PlanStepSchema = z.object({
+  id: z.string(),
+  title: z.string(),
+  description: z.string(),
+  commands: z.array(z.string()), // git commands to execute
+  expected: z.string(), // what should happen after running
+  undo: z.object({
+    possible: z.boolean(),
+    commands: z.array(z.string()), // commands to undo this step
+    description: z.string(),
+  }),
+  dangerous: z.boolean(), // requires explicit dangerous_allowed flag
+  warning: z.string().optional(), // warning text for dangerous operations
+  requiresUserInput: z.boolean().default(false), // e.g., editing conflict markers
+  userInputHint: z.string().optional(),
+});
+
+export type PlanStep = z.infer<typeof PlanStepSchema>;
+
+// Complete recovery plan
+export const PlanV1Schema = z.object({
+  version: z.literal(1),
+  timestamp: z.string().datetime(),
+  issueType: IssueTypeSchema,
+  issueSummary: z.string(),
+  risk: RiskLevelSchema,
+  steps: z.array(PlanStepSchema),
+
+  // Alternative safer approaches if dangerous operations are suggested
+  saferAlternatives: z.array(z.object({
+    description: z.string(),
+    tradeoff: z.string(), // what you lose by using safer approach
+    steps: z.array(PlanStepSchema),
+  })).optional(),
+
+  // Reflog-based recovery path (always included for safety)
+  reflogRecovery: z.object({
+    description: z.string(),
+    relevantEntries: z.array(z.string()), // reflog selectors like HEAD@{2}
+    recoveryCommand: z.string(),
+  }).optional(),
+});
+
+export type PlanV1 = z.infer<typeof PlanV1Schema>;
+
+// Verification result after user runs some steps
+export const VerificationResultSchema = z.object({
+  stepsCompleted: z.array(z.string()), // step IDs
+  issueResolved: z.boolean(),
+  remainingIssues: z.array(z.string()),
+  nextStepId: z.string().optional(),
+  guidance: z.string(),
+});
+
+export type VerificationResult = z.infer<typeof VerificationResultSchema>;

package/src/signals.ts

@@ -0,0 +1,47 @@
+import { z } from 'zod';
+import { IssueTypeSchema, RiskLevelSchema } from './plan.js';
+
+// Normalized signals from snapshot for agent processing
+export const SignalsSchema = z.object({
+  // Detected issues
+  hasConflicts: z.boolean(),
+  conflictCount: z.number(),
+  conflictFiles: z.array(z.string()),
+
+  isDetachedHead: z.boolean(),
+  detachedAt: z.string().optional(), // commit hash
+
+  isRebaseInProgress: z.boolean(),
+  rebaseType: z.enum(['merge', 'apply', 'none']),
+  rebaseOnto: z.string().optional(),
+
+  // Branch context
+  currentBranch: z.string(),
+  upstreamBranch: z.string().optional(),
+  aheadCount: z.number(),
+  behindCount: z.number(),
+
+  // Working tree state
+  hasStagedChanges: z.boolean(),
+  hasUnstagedChanges: z.boolean(),
+  hasUntrackedFiles: z.boolean(),
+
+  // Recovery hints from reflog
+  recentCheckouts: z.array(z.object({
+    from: z.string(),
+    to: z.string(),
+    reflogSelector: z.string(),
+  })),
+  recentResets: z.array(z.object({
+    type: z.string(), // soft, mixed, hard
+    target: z.string(),
+    reflogSelector: z.string(),
+  })),
+
+  // Classification result
+  primaryIssue: IssueTypeSchema,
+  secondaryIssues: z.array(IssueTypeSchema),
+  estimatedRisk: RiskLevelSchema,
+});
+
+export type Signals = z.infer<typeof SignalsSchema>;