@hiveai/core 0.3.3 → 0.4.1

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import { z } from 'zod';
 
-declare const MemoryScopeSchema: z.ZodEnum<["personal", "team", "module"]>;
+declare const MemoryScopeSchema: z.ZodEnum<["personal", "team", "module", "shared"]>;
 declare const MemoryStatusSchema: z.ZodEnum<["draft", "proposed", "validated", "deprecated", "stale", "rejected"]>;
 declare const MemoryTypeSchema: z.ZodEnum<["convention", "decision", "gotcha", "architecture", "glossary", "attempt", "session_recap"]>;
 declare const AnchorSchema: z.ZodObject<{
@@ -18,7 +18,7 @@ declare const AnchorSchema: z.ZodObject<{
 }>;
 declare const MemoryFrontmatterSchema: z.ZodEffects<z.ZodObject<{
     id: z.ZodString;
-    scope: z.ZodDefault<z.ZodEnum<["personal", "team", "module"]>>;
+    scope: z.ZodDefault<z.ZodEnum<["personal", "team", "module", "shared"]>>;
     module: z.ZodOptional<z.ZodString>;
     type: z.ZodEnum<["convention", "decision", "gotcha", "architecture", "glossary", "attempt", "session_recap"]>;
     status: z.ZodDefault<z.ZodEnum<["draft", "proposed", "validated", "deprecated", "stale", "rejected"]>>;
@@ -46,11 +46,18 @@ declare const MemoryFrontmatterSchema: z.ZodEffects<z.ZodObject<{
     last_read_at: z.ZodDefault<z.ZodNullable<z.ZodString>>;
     topic: z.ZodOptional<z.ZodString>;
     revision_count: z.ZodDefault<z.ZodNumber>;
+    /**
+     * When true, the AI MUST NOT act on this memory autonomously.
+     * It must surface the information to the human developer and wait
+     * for explicit confirmation before modifying any code.
+     * Used for cross-repo breaking changes, dependency bumps, contract diffs.
+     */
+    requires_human_approval: z.ZodDefault<z.ZodBoolean>;
 }, "strip", z.ZodTypeAny, {
     type: "convention" | "decision" | "gotcha" | "architecture" | "glossary" | "attempt" | "session_recap";
     status: "draft" | "proposed" | "validated" | "deprecated" | "stale" | "rejected";
     id: string;
-    scope: "personal" | "team" | "module";
+    scope: "personal" | "team" | "module" | "shared";
     anchor: {
         paths: string[];
         symbols: string[];
@@ -64,6 +71,7 @@ declare const MemoryFrontmatterSchema: z.ZodEffects<z.ZodObject<{
     related_ids: string[];
     last_read_at: string | null;
     revision_count: number;
+    requires_human_approval: boolean;
     module?: string | undefined;
     domain?: string | undefined;
     author?: string | undefined;
@@ -74,7 +82,7 @@ declare const MemoryFrontmatterSchema: z.ZodEffects<z.ZodObject<{
     created_at: string | Date;
     module?: string | undefined;
     status?: "draft" | "proposed" | "validated" | "deprecated" | "stale" | "rejected" | undefined;
-    scope?: "personal" | "team" | "module" | undefined;
+    scope?: "personal" | "team" | "module" | "shared" | undefined;
     anchor?: {
         commit?: string | undefined;
         paths?: string[] | undefined;
@@ -90,11 +98,12 @@ declare const MemoryFrontmatterSchema: z.ZodEffects<z.ZodObject<{
     last_read_at?: string | null | undefined;
     topic?: string | undefined;
     revision_count?: number | undefined;
+    requires_human_approval?: boolean | undefined;
 }>, {
     type: "convention" | "decision" | "gotcha" | "architecture" | "glossary" | "attempt" | "session_recap";
     status: "draft" | "proposed" | "validated" | "deprecated" | "stale" | "rejected";
     id: string;
-    scope: "personal" | "team" | "module";
+    scope: "personal" | "team" | "module" | "shared";
     anchor: {
         paths: string[];
         symbols: string[];
@@ -108,6 +117,7 @@ declare const MemoryFrontmatterSchema: z.ZodEffects<z.ZodObject<{
     related_ids: string[];
     last_read_at: string | null;
     revision_count: number;
+    requires_human_approval: boolean;
     module?: string | undefined;
     domain?: string | undefined;
     author?: string | undefined;
@@ -118,7 +128,7 @@ declare const MemoryFrontmatterSchema: z.ZodEffects<z.ZodObject<{
     created_at: string | Date;
     module?: string | undefined;
     status?: "draft" | "proposed" | "validated" | "deprecated" | "stale" | "rejected" | undefined;
-    scope?: "personal" | "team" | "module" | undefined;
+    scope?: "personal" | "team" | "module" | "shared" | undefined;
     anchor?: {
         commit?: string | undefined;
         paths?: string[] | undefined;
@@ -134,7 +144,24 @@ declare const MemoryFrontmatterSchema: z.ZodEffects<z.ZodObject<{
     last_read_at?: string | null | undefined;
     topic?: string | undefined;
     revision_count?: number | undefined;
+    requires_human_approval?: boolean | undefined;
 }>;
+declare const CrossRepoProvenanceSchema: z.ZodOptional<z.ZodObject<{
+    source_name: z.ZodString;
+    source_path: z.ZodString;
+    source_id: z.ZodString;
+    imported_at: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    source_name: string;
+    source_path: string;
+    source_id: string;
+    imported_at: string;
+}, {
+    source_name: string;
+    source_path: string;
+    source_id: string;
+    imported_at: string;
+}>>;
 
 type MemoryScope = z.infer<typeof MemoryScopeSchema>;
 type MemoryStatus = z.infer<typeof MemoryStatusSchema>;
@@ -163,6 +190,7 @@ declare function buildFrontmatter(input: {
     commit?: string;
     topic?: string;
     status?: MemoryFrontmatter["status"];
+    relatedIds?: string[];
 }): MemoryFrontmatter;
 
 declare const HAIVE_DIR = ".ai";
@@ -359,6 +387,31 @@ declare function queryCodeMap(map: CodeMap, options: CodeMapQueryOptions): {
 };
 
 declare const CONFIG_FILE = "haive.config.json";
+/** A remote or local repo to pull shared memories from. */
+interface CrossRepoSource {
+    /** Human-readable name for this source (used in imported memory tags). */
+    name: string;
+    /** Local filesystem path to the other project's root (relative or absolute). */
+    path?: string;
+    /** Git URL — clone/fetch performed automatically. */
+    git?: string;
+    /** Only import memories matching all of these filters. */
+    filter?: {
+        /** Only import memories with these tags. */
+        tags?: string[];
+        /** Only import memories of these types. */
+        types?: string[];
+    };
+}
+/** An API contract file to snapshot and monitor for breaking changes. */
+interface ContractFile {
+    /** Human-readable name for this contract. */
+    name: string;
+    /** Path to the contract file, relative to the project root. */
+    path: string;
+    /** Format of the contract file. */
+    format: "openapi" | "graphql" | "proto" | "typescript" | "json-schema";
+}
 interface HaiveConfig {
     /** Autopilot mode: maximum autonomy, minimum human intervention. Default: false. */
     autopilot?: boolean;
@@ -384,6 +437,35 @@ interface HaiveConfig {
      * the template. Default: true in autopilot, false otherwise.
      */
     autoContext?: boolean;
+    /**
+     * Other repos to pull `shared`-scoped memories from during `haive sync`.
+     * Each source must have either `path` (local) or `git` (remote URL).
+     *
+     * Example:
+     *   { "name": "backend", "path": "../repo-backend", "filter": { "tags": ["api-contract"] } }
+     */
+    crossRepoSources?: CrossRepoSource[];
+    /**
+     * API contract files to snapshot and watch for breaking changes.
+     * `haive sync` compares the current file against `.ai/contracts/<name>.lock`
+     * and creates a `gotcha` memory if a breaking change is detected.
+     *
+     * Example:
+     *   { "name": "payment-api", "path": "docs/openapi.yaml", "format": "openapi" }
+     */
+    contractFiles?: ContractFile[];
+    /**
+     * Local path to a shared team-knowledge hub repo.
+     * Used by `haive hub pull` and `haive hub push`.
+     * Can be relative (resolved from project root) or absolute.
+     */
+    hubPath?: string;
+    /**
+     * Lock file paths to watch for dependency version changes.
+     * Auto-detected if not specified (package.json, pom.xml, go.mod, etc.).
+     * Set to [] to disable dependency tracking entirely.
+     */
+    dependencyFiles?: string[];
 }
 declare const DEFAULT_CONFIG: HaiveConfig;
 declare const AUTOPILOT_DEFAULTS: HaiveConfig;
@@ -391,4 +473,83 @@ declare function configPath(paths: HaivePaths): string;
 declare function loadConfig(paths: HaivePaths): Promise<HaiveConfig>;
 declare function saveConfig(paths: HaivePaths, config: HaiveConfig): Promise<void>;
 
-export { AUTOPILOT_DEFAULTS, type Anchor, AnchorSchema, type AutoPromoteRule, type BudgetPart, type BudgetSlice, type BuildCodeMapOptions, CHARS_PER_TOKEN, CODE_MAP_FILE, CONFIG_FILE, type CodeExport, type CodeExportKind, type CodeFileEntry, type CodeMap, type CodeMapQueryOptions, type ConfidenceLevel, type ConfidenceThresholds, DECAY_DAYS, DEFAULT_AUTO_PROMOTE_RULE, DEFAULT_CONFIDENCE_THRESHOLDS, DEFAULT_CONFIG, HAIVE_DIR, type HaiveConfig, type HaivePaths, type LoadedMemory, MEMORIES_DIR, type Memory, type MemoryFrontmatter, MemoryFrontmatterSchema, type MemoryScope, MemoryScopeSchema, type MemoryStatus, MemoryStatusSchema, type MemoryType, MemoryTypeSchema, type MemoryUsage, PROJECT_CONTEXT_FILE, type TruncateOptions, type TruncateResult, USAGE_FILE, type UsageIndex, type VerifyOptions, type VerifyResult, allocateBudget, buildCodeMap, buildFrontmatter, bumpRead, codeMapPath, configPath, deriveConfidence, emptyUsage, emptyUsageIndex, estimateTokens, extractSnippet, findProjectRoot, getUsage, inferModulesFromPaths, isAutoPromoteEligible, isDecaying, listMarkdownFilesRecursive, literalMatchesAllTokens, literalMatchesAnyToken, loadCodeMap, loadConfig, loadMemoriesFromDir, loadMemory, loadUsageIndex, memoryFilePath, memoryMatchesAnchorPaths, newMemoryId, parseMemory, pathsOverlap, pickSnippetNeedle, queryCodeMap, recordRejection, relPathFrom, resolveHaivePaths, saveCodeMap, saveConfig, saveUsageIndex, serializeMemory, stripPrivate, tokenizeQuery, trackReads, truncateToTokens, usagePath, verifyAnchor };
+interface CrossRepoReport {
+    source: string;
+    imported: string[];
+    updated: string[];
+    skipped: string[];
+    errors: string[];
+}
+/**
+ * Pull shared memories from all configured cross-repo sources.
+ * Returns one report per source.
+ */
+declare function pullCrossRepoSources(paths: HaivePaths, config: HaiveConfig, projectRoot: string): Promise<CrossRepoReport[]>;
+
+interface DependencySnapshot {
+    file: string;
+    format: string;
+    captured_at: string;
+    deps: Record<string, string>;
+}
+interface DepChange {
+    name: string;
+    from: string;
+    to: string;
+    /** true if the major version number changed */
+    isMajorBump: boolean;
+}
+interface DepTrackResult {
+    file: string;
+    changes: DepChange[];
+}
+/**
+ * Resolve which manifest files to track.
+ * Uses config.dependencyFiles if set, otherwise auto-detects from KNOWN_MANIFESTS.
+ */
+declare function resolveManifestFiles(projectRoot: string, configuredFiles?: string[]): string[];
+/**
+ * Check all manifest files for version changes since last snapshot.
+ * Returns one result per file that has changes.
+ */
+declare function trackDependencies(projectRoot: string, haiveDir: string, manifestFiles: string[]): Promise<DepTrackResult[]>;
+
+interface ContractSnapshot {
+    name: string;
+    path: string;
+    format: string;
+    captured_at: string;
+    hash: string;
+    endpoints?: string[];
+    types?: string[];
+    fields?: Record<string, string[]>;
+    raw_lines?: string[];
+}
+interface BreakingChange {
+    kind: "endpoint_removed" | "endpoint_added" | "type_removed" | "type_added" | "field_removed" | "field_added" | "content_changed";
+    description: string;
+    severity: "breaking" | "additive" | "unknown";
+}
+interface ContractDiffResult {
+    contract: string;
+    file: string;
+    changes: BreakingChange[];
+    unchanged: boolean;
+}
+declare function contractLockPath(haiveDir: string, name: string): string;
+/**
+ * Take a snapshot of a contract file and save it to .ai/contracts/<name>.lock.
+ * Returns the snapshot.
+ */
+declare function snapshotContract(projectRoot: string, haiveDir: string, contract: ContractFile): Promise<ContractSnapshot>;
+/**
+ * Compare a contract file against its stored snapshot.
+ * Returns the diff result. If no snapshot exists, creates one and returns unchanged.
+ */
+declare function diffContract(projectRoot: string, haiveDir: string, contract: ContractFile): Promise<ContractDiffResult>;
+/**
+ * Check all configured contract files for changes.
+ */
+declare function watchContracts(projectRoot: string, haiveDir: string, contractFiles: ContractFile[]): Promise<ContractDiffResult[]>;
+
+export { AUTOPILOT_DEFAULTS, type Anchor, AnchorSchema, type AutoPromoteRule, type BreakingChange, type BudgetPart, type BudgetSlice, type BuildCodeMapOptions, CHARS_PER_TOKEN, CODE_MAP_FILE, CONFIG_FILE, type CodeExport, type CodeExportKind, type CodeFileEntry, type CodeMap, type CodeMapQueryOptions, type ConfidenceLevel, type ConfidenceThresholds, type ContractDiffResult, type ContractFile, type ContractSnapshot, CrossRepoProvenanceSchema, type CrossRepoReport, type CrossRepoSource, DECAY_DAYS, DEFAULT_AUTO_PROMOTE_RULE, DEFAULT_CONFIDENCE_THRESHOLDS, DEFAULT_CONFIG, type DepChange, type DepTrackResult, type DependencySnapshot, HAIVE_DIR, type HaiveConfig, type HaivePaths, type LoadedMemory, MEMORIES_DIR, type Memory, type MemoryFrontmatter, MemoryFrontmatterSchema, type MemoryScope, MemoryScopeSchema, type MemoryStatus, MemoryStatusSchema, type MemoryType, MemoryTypeSchema, type MemoryUsage, PROJECT_CONTEXT_FILE, type TruncateOptions, type TruncateResult, USAGE_FILE, type UsageIndex, type VerifyOptions, type VerifyResult, allocateBudget, buildCodeMap, buildFrontmatter, bumpRead, codeMapPath, configPath, contractLockPath, deriveConfidence, diffContract, emptyUsage, emptyUsageIndex, estimateTokens, extractSnippet, findProjectRoot, getUsage, inferModulesFromPaths, isAutoPromoteEligible, isDecaying, listMarkdownFilesRecursive, literalMatchesAllTokens, literalMatchesAnyToken, loadCodeMap, loadConfig, loadMemoriesFromDir, loadMemory, loadUsageIndex, memoryFilePath, memoryMatchesAnchorPaths, newMemoryId, parseMemory, pathsOverlap, pickSnippetNeedle, pullCrossRepoSources, queryCodeMap, recordRejection, relPathFrom, resolveHaivePaths, resolveManifestFiles, saveCodeMap, saveConfig, saveUsageIndex, serializeMemory, snapshotContract, stripPrivate, tokenizeQuery, trackDependencies, trackReads, truncateToTokens, usagePath, verifyAnchor, watchContracts };