@vpxa/aikit 0.1.86 → 0.1.88

package/packages/tools/dist/index.d.ts

@@ -291,6 +291,7 @@ interface Checkpoint {
   data: Record<string, unknown>;
   files?: string[];
   notes?: string;
+  gitSha?: string;
 }
 declare function checkpointSave(label: string, data: Record<string, unknown>, options?: {
   files?: string[];
@@ -300,6 +301,41 @@ declare function checkpointSave(label: string, data: Record<string, unknown>, op
 declare function checkpointLoad(id: string, cwd?: string): Checkpoint | undefined;
 declare function checkpointList(cwd?: string): Checkpoint[];
 declare function checkpointLatest(cwd?: string): Checkpoint | undefined;
+/**
+ * Diff two checkpoints by ID — shows added/removed/modified keys in data.
+ */
+declare function checkpointDiff(fromId: string, toId: string, cwd?: string): {
+  fromId: string;
+  toId: string;
+  added: string[];
+  removed: string[];
+  modified: string[];
+} | undefined;
+/**
+ * List history of a checkpoint label — git log of that ref's commits.
+ * Falls back to filesystem scan if git unavailable.
+ */
+declare function checkpointHistory(label: string, options?: {
+  cwd?: string;
+  limit?: number;
+}): Array<{
+  sha?: string;
+  id: string;
+  createdAt: string;
+  label: string;
+}>;
+declare function checkpointGC(options?: {
+  label?: string;
+  keepLast?: number;
+  maxAgeDays?: number;
+  dryRun?: boolean;
+  cwd?: string;
+}): {
+  deleted: number;
+  kept: number;
+  labels: string[];
+  deletedIds: string[];
+};
 //#endregion
 //#region packages/tools/src/codemod.d.ts
 interface CodemodRule {
@@ -1220,6 +1256,34 @@ interface GitContextResult {
 }
 declare function gitContext(options?: GitContextOptions): Promise<GitContextResult>;
 //#endregion
+//#region packages/tools/src/git-utils.d.ts
+/** Regex for valid git ref slug segments */
+declare const GIT_REF_SLUG_PATTERN: RegExp;
+/**
+ * Check if git is available in the given directory.
+ * Results are cached per resolved root path.
+ */
+declare function gitAvailable(cwd: string): boolean;
+/**
+ * Execute a git command with a 10-second timeout.
+ * Returns trimmed stdout on success, undefined on failure.
+ * Never throws — failures are logged and return undefined.
+ */
+declare function gitExec(args: string[], cwd: string, input?: string): string | undefined;
+/**
+ * Create a slugified ref segment from a label.
+ * Lowercase, replace non-alphanumeric with dashes, trim leading/trailing dashes, max 60 chars.
+ */
+declare function slugForRef(label: string): string;
+/**
+ * Commit content to a git orphan ref.
+ * Creates: blob -> single-entry tree -> commit (with optional parent) -> update-ref.
+ * Returns the commit SHA on success, undefined on failure.
+ */
+declare function gitCommitToRef(ref: string, filename: string, content: string, message: string, cwd: string): string | undefined;
+/** Reset the git availability cache (useful for testing). */
+declare function resetGitCache(): void;
+//#endregion
 //#region packages/tools/src/graph-query.d.ts
 interface GraphQueryOptions {
   /** Action: query nodes, traverse from a node, get stats, or add data */
@@ -1420,6 +1484,57 @@ declare function laneMerge(name: string, cwd?: string): LaneMergeResult;
 /** Discard a lane entirely. */
 declare function laneDiscard(name: string, cwd?: string): boolean;
 //#endregion
+//#region packages/tools/src/lease.d.ts
+interface Lease {
+  id: string;
+  agent: string;
+  files: string[];
+  symbols?: string[];
+  intent: string;
+  status: 'active' | 'released' | 'expired';
+  acquiredAt: string;
+  expiresAt: string;
+  releasedAt?: string;
+}
+interface LeaseConflict {
+  leaseId: string;
+  agent: string;
+  overlappingFiles: string[];
+  overlappingSymbols?: string[];
+  intent: string;
+}
+interface HotspotEntry {
+  path: string;
+  leaseCount: number;
+  conflictCount: number;
+  lastContested: string;
+}
+declare function acquireLease(opts: {
+  agent: string;
+  files: string[];
+  intent: string;
+  symbols?: string[];
+  ttl_minutes?: number;
+  cwd?: string;
+}): {
+  lease: Lease;
+  conflicts: LeaseConflict[];
+};
+declare function releaseLease(opts: {
+  id: string;
+  cwd?: string;
+}): {
+  released: boolean;
+  lease?: Lease;
+};
+declare function listActiveLeases(opts?: {
+  agent?: string;
+  cwd?: string;
+}): {
+  leases: Lease[];
+  hotspots: Record<string, HotspotEntry>;
+};
+//#endregion
 //#region packages/tools/src/measure.d.ts
 /**
  * aikit_measure — Code complexity and size metrics.
@@ -1546,8 +1661,9 @@ declare function processLogs(id: string, tail?: number): string[];
 interface QueueItem {
   id: string;
   title: string;
-  status: 'pending' | 'in-progress' | 'done' | 'failed';
+  status: 'pending' | 'blocked' | 'in-progress' | 'done' | 'failed';
   data?: unknown;
+  dependsOn?: string[];
   createdAt: string;
   updatedAt: string;
   error?: string;
@@ -1559,11 +1675,14 @@ interface QueueState {
 /** Create a new named queue. */
 declare function queueCreate(name: string, cwd?: string): QueueState;
 /** Push an item onto a queue. Creates the queue if it doesn't exist. */
-declare function queuePush(name: string, title: string, data?: unknown, cwd?: string): QueueItem;
+declare function queuePush(name: string, title: string, data?: unknown, cwd?: string, dependsOn?: string[]): QueueItem;
 /** Take the next pending item from a queue and mark it in-progress. */
 declare function queueNext(name: string, cwd?: string): QueueItem | null;
-/** Mark a queue item as done. */
-declare function queueDone(name: string, id: string, cwd?: string): QueueItem;
+/** Mark a queue item as done. Automatically unblocks dependents whose deps are all satisfied. */
+declare function queueDone(name: string, id: string, cwd?: string): {
+  item: QueueItem;
+  unblocked: QueueItem[];
+};
 /** Mark a queue item as failed with an error message. */
 declare function queueFail(name: string, id: string, error: string, cwd?: string): QueueItem;
 /** Get the current state of a queue. */
@@ -1572,12 +1691,20 @@ declare function queueGet(name: string, cwd?: string): QueueState | null;
 declare function queueList(cwd?: string): Array<{
   name: string;
   pending: number;
+  blocked: number;
   done: number;
   failed: number;
   total: number;
 }>;
-/** Clear completed items from a queue. */
+/** Clear completed and failed items from a queue. Keeps pending, blocked, and in-progress items. */
 declare function queueClear(name: string, cwd?: string): number;
+/** View queue items organized as a DAG with topologically-sorted execution waves. */
+declare function queueDag(name: string, cwd?: string): {
+  waves: string[][];
+  blocked: string[];
+  completed: string[];
+  failed: string[];
+};
 /** Delete a queue entirely. */
 declare function queueDelete(name: string, cwd?: string): boolean;
 //#endregion
@@ -2224,4 +2351,4 @@ declare function addToWorkset(name: string, files: string[], cwd?: string): Work
  */
 declare function removeFromWorkset(name: string, files: string[], cwd?: string): Workset | null;
 //#endregion
-export { type AuditCheck, type AuditData, type AuditOptions, type AuditRecommendation, type BatchOperation, type BatchOptions, type BatchResult, type ChangelogEntry, type ChangelogFormat, type ChangelogOptions, type ChangelogResult, type CheckOptions, type CheckResult, type CheckSummaryResult, type Checkpoint, type ClassifyTrigger, type CodemodChange, type CodemodOptions, type CodemodResult, type CodemodRule, type CompactOptions, type CompactResult, type CompressOutputOptions, type CompressionContext, type CompressionMode, type CompressionResult, type CompressionRule, type ConstraintRef, type DeadSymbol, type DeadSymbolOptions, type DeadSymbolResult, type DelegateOptions, type DelegateResult, type DiffChange, type DiffFile, type DiffHunk, type DiffParseOptions, type DigestFieldEntry, type DigestOptions, type DigestResult, type DigestSource, type DogfoodLogEntry, type DogfoodLogGroupedEntry, type DogfoodLogOptions, type DogfoodLogResult, type EncodeOperation, type EncodeOptions, type EncodeResult, type EnvInfoOptions, type EnvInfoResult, type EvalOptions, type EvalResult, type EvidenceEntry, type EvidenceMapAction, type EvidenceMapResult, type EvidenceMapState, type EvidenceStatus, type Example, FileCache, type FileCacheEntry, type FileCacheStats, type FileMetrics, type FileSummaryOptions, type FileSummaryResult, type FindExamplesOptions, type FindExamplesResult, type FindOptions, type FindResult, type FindResults, type ForgeClassifyCeremony, type ForgeClassifyOptions, type ForgeClassifyResult, type ForgeGroundOptions, type ForgeGroundResult, type ForgeTier, type GateConfig, type GateDecision, type GateResult, type GitContextOptions, type GitContextResult, type GraphAugmentOptions, type GraphAugmentedResult, type GraphQueryOptions, type GraphQueryResult, type GuideRecommendation, type GuideResult, type HealthCheck, type HealthResult, type HttpMethod, type HttpRequestOptions, type HttpRequestResult, type KBError, type KBErrorCode, type KBNextHint, type KBResponse, type KBResponseMeta, type LaneDiffEntry, type LaneDiffResult, type LaneMergeResult, type LaneMeta, type ManagedProcess, type MeasureOptions, type MeasureResult, type OnboardMode, type OnboardOptions, type OnboardResult, type OnboardStepResult, type ParsedError, type ParsedGitStatus, type ParsedOutput, type ParsedTestResult, type ParsedTestSummary, type QueueItem, type QueueState, type RegexTestOptions, type RegexTestResult, type RenameChange, type RenameOptions, type RenameResult, type ReplayEntry, type ReplayOptions, type RestorePoint, type SafetyGate, type SafetyGateResult, type SchemaValidateOptions, type SchemaValidateResult, type ScopeMapEntry, type ScopeMapOptions, type ScopeMapResult, type SessionDigestOptions, type SessionDigestResult, type Snippet, type SnippetAction, type SnippetOptions, type SnippetResult, type StashEntry, type StratumCard, type StratumCardOptions, type StratumCardResult, type SymbolGraphContext, type SymbolInfo, type SymbolOptions, type TestRunOptions, type TestRunResult, type TimeOptions, type TimeResult, type TimeoutAction, type TraceNode, type TraceOptions, type TraceResult, type TransformOptions, type TransformResult, type TypedUnknownSeed, type UnknownType, type ValidationError, type WatchEvent, type WatchHandle, type WatchOptions, type WebFetchMode, type WebFetchOptions, type WebFetchResult, type WebSearchOptions, type WebSearchResult, type WebSearchResultItem, type Workset, addToWorkset, analyzeFile, audit, autoClaimTestFailures, batch, bookendReorder, bpeSurprise, changelog, check, checkpointLatest, checkpointList, checkpointLoad, checkpointSave, classifyExitCode, codemod, compact, compressOutput, compressTerminalOutput, cosineSimilarity, createRestorePoint, dataTransform, delegate, delegateListModels, deleteWorkset, detectOutputTool, diffParse, digest, dogfoodLog, encode, envInfo, errorResponse, escapeRegExp, estimateTokens, evaluate, evidenceMap, fileSummary, find, findDeadSymbols, findExamples, forgeClassify, forgeGround, formatChangelog, getRegisteredRules, getWorkset, gitContext, graphAugmentSearch, graphQuery, guide, headTailTruncate, health, httpRequest, laneCreate, laneDiff, laneDiscard, laneList, laneMerge, laneStatus, listRestorePoints, listWorksets, measure, okResponse, onboard, paragraphTruncate, parseBiome, parseGitStatus, parseOutput, parseSearchResults, parseTsc, parseVitest, processList, processLogs, processStart, processStatus, processStop, queueClear, queueCreate, queueDelete, queueDone, queueFail, queueGet, queueList, queueNext, queuePush, regexTest, registerRule, registerRules, removeFromWorkset, rename, replayAppend, replayCapture, replayClear, replayList, replayTrim, resolvePath, restoreFromPoint, saveWorkset, schemaValidate, scopeMap, scoreLine, scoreLines, segment, sessionDigest, sessionDigestSampling, shannonEntropy, snippet, stashClear, stashDelete, stashGet, stashList, stashSet, stratumCard, summarizeCheckResult, symbol, testRun, timeUtils, trace, truncateToTokenBudget, watchList, watchStart, watchStop, webFetch, webSearch };
+export { type AuditCheck, type AuditData, type AuditOptions, type AuditRecommendation, type BatchOperation, type BatchOptions, type BatchResult, type ChangelogEntry, type ChangelogFormat, type ChangelogOptions, type ChangelogResult, type CheckOptions, type CheckResult, type CheckSummaryResult, type Checkpoint, type ClassifyTrigger, type CodemodChange, type CodemodOptions, type CodemodResult, type CodemodRule, type CompactOptions, type CompactResult, type CompressOutputOptions, type CompressionContext, type CompressionMode, type CompressionResult, type CompressionRule, type ConstraintRef, type DeadSymbol, type DeadSymbolOptions, type DeadSymbolResult, type DelegateOptions, type DelegateResult, type DiffChange, type DiffFile, type DiffHunk, type DiffParseOptions, type DigestFieldEntry, type DigestOptions, type DigestResult, type DigestSource, type DogfoodLogEntry, type DogfoodLogGroupedEntry, type DogfoodLogOptions, type DogfoodLogResult, type EncodeOperation, type EncodeOptions, type EncodeResult, type EnvInfoOptions, type EnvInfoResult, type EvalOptions, type EvalResult, type EvidenceEntry, type EvidenceMapAction, type EvidenceMapResult, type EvidenceMapState, type EvidenceStatus, type Example, FileCache, type FileCacheEntry, type FileCacheStats, type FileMetrics, type FileSummaryOptions, type FileSummaryResult, type FindExamplesOptions, type FindExamplesResult, type FindOptions, type FindResult, type FindResults, type ForgeClassifyCeremony, type ForgeClassifyOptions, type ForgeClassifyResult, type ForgeGroundOptions, type ForgeGroundResult, type ForgeTier, GIT_REF_SLUG_PATTERN, type GateConfig, type GateDecision, type GateResult, type GitContextOptions, type GitContextResult, type GraphAugmentOptions, type GraphAugmentedResult, type GraphQueryOptions, type GraphQueryResult, type GuideRecommendation, type GuideResult, type HealthCheck, type HealthResult, type HotspotEntry, type HttpMethod, type HttpRequestOptions, type HttpRequestResult, type KBError, type KBErrorCode, type KBNextHint, type KBResponse, type KBResponseMeta, type LaneDiffEntry, type LaneDiffResult, type LaneMergeResult, type LaneMeta, type Lease, type LeaseConflict, type ManagedProcess, type MeasureOptions, type MeasureResult, type OnboardMode, type OnboardOptions, type OnboardResult, type OnboardStepResult, type ParsedError, type ParsedGitStatus, type ParsedOutput, type ParsedTestResult, type ParsedTestSummary, type QueueItem, type QueueState, type RegexTestOptions, type RegexTestResult, type RenameChange, type RenameOptions, type RenameResult, type ReplayEntry, type ReplayOptions, type RestorePoint, type SafetyGate, type SafetyGateResult, type SchemaValidateOptions, type SchemaValidateResult, type ScopeMapEntry, type ScopeMapOptions, type ScopeMapResult, type SessionDigestOptions, type SessionDigestResult, type Snippet, type SnippetAction, type SnippetOptions, type SnippetResult, type StashEntry, type StratumCard, type StratumCardOptions, type StratumCardResult, type SymbolGraphContext, type SymbolInfo, type SymbolOptions, type TestRunOptions, type TestRunResult, type TimeOptions, type TimeResult, type TimeoutAction, type TraceNode, type TraceOptions, type TraceResult, type TransformOptions, type TransformResult, type TypedUnknownSeed, type UnknownType, type ValidationError, type WatchEvent, type WatchHandle, type WatchOptions, type WebFetchMode, type WebFetchOptions, type WebFetchResult, type WebSearchOptions, type WebSearchResult, type WebSearchResultItem, type Workset, acquireLease, addToWorkset, analyzeFile, audit, autoClaimTestFailures, batch, bookendReorder, bpeSurprise, changelog, check, checkpointDiff, checkpointGC, checkpointHistory, checkpointLatest, checkpointList, checkpointLoad, checkpointSave, classifyExitCode, codemod, compact, compressOutput, compressTerminalOutput, cosineSimilarity, createRestorePoint, dataTransform, delegate, delegateListModels, deleteWorkset, detectOutputTool, diffParse, digest, dogfoodLog, encode, envInfo, errorResponse, escapeRegExp, estimateTokens, evaluate, evidenceMap, fileSummary, find, findDeadSymbols, findExamples, forgeClassify, forgeGround, formatChangelog, getRegisteredRules, getWorkset, gitAvailable, gitCommitToRef, gitContext, gitExec, graphAugmentSearch, graphQuery, guide, headTailTruncate, health, httpRequest, laneCreate, laneDiff, laneDiscard, laneList, laneMerge, laneStatus, listActiveLeases, listRestorePoints, listWorksets, measure, okResponse, onboard, paragraphTruncate, parseBiome, parseGitStatus, parseOutput, parseSearchResults, parseTsc, parseVitest, processList, processLogs, processStart, processStatus, processStop, queueClear, queueCreate, queueDag, queueDelete, queueDone, queueFail, queueGet, queueList, queueNext, queuePush, regexTest, registerRule, registerRules, releaseLease, removeFromWorkset, rename, replayAppend, replayCapture, replayClear, replayList, replayTrim, resetGitCache, resolvePath, restoreFromPoint, saveWorkset, schemaValidate, scopeMap, scoreLine, scoreLines, segment, sessionDigest, sessionDigestSampling, shannonEntropy, slugForRef, snippet, stashClear, stashDelete, stashGet, stashList, stashSet, stratumCard, summarizeCheckResult, symbol, testRun, timeUtils, trace, truncateToTokenBudget, watchList, watchStart, watchStop, webFetch, webSearch };