pi-anchor 0.2.3 → 0.3.0

package/dist/index.d.cts

@@ -1,213 +1,7 @@
+import { a as AnchorStatus, b as Anchor, A as AnchorStore, T as TouchMatchResult, S as SettlementProposal } from './store-t2_TDhJn.cjs';
+export { c as AnchorDecayPolicy, d as AnchorDurability, e as AnchorEvidence, f as AnchorPriority, g as AnchorStoreState, D as DEFAULT_DECAY_POLICY, h as DURABLE_DECAY_POLICY, E as EPHEMERAL_DECAY_POLICY, i as acquireSyncLock, j as atomicRenameWithRetry, k as detectDurability, l as detectRecurrence, m as detectTargetDate, n as getDefaultStorageDir, o as getEphemeralDecayPolicy, p as getTodayDateString } from './store-t2_TDhJn.cjs';
 import { ExtensionContext } from '@earendil-works/pi-coding-agent';
 
-/**
- * Anchor Data Contracts & Type Definitions
- * Single Global Source of Truth with Zero Workspace Contamination.
- */
-type AnchorStatus = 'active' | 'sleeping' | 'settled' | 'graveyard';
-type AnchorPriority = 'p0' | 'p1' | 'p2';
-type AnchorDurability = 'ephemeral' | 'durable';
-interface AnchorDecayPolicy {
-    /** Days before an untouched active anchor transitions to sleeping */
-    activeDays: number;
-    /** Days an anchor remains sleeping before dropping to graveyard */
-    sleepDays: number;
-    /** Total maximum days before permanent graveyard sweep (9999 = never) */
-    graveyardDays: number;
-}
-interface AnchorEvidence {
-    settledAt?: number;
-    settledBy?: 'one-tap-settlement' | 'manual-command' | 'verification-test';
-    commitHash?: string;
-    summary?: string;
-    touchedFiles?: string[];
-}
-interface Anchor {
-    /** Unique sequential identifier, e.g., 'anc-1' */
-    id: string;
-    /** Short imperative title of the task */
-    title: string;
-    /** Optional detailed context or notes */
-    description?: string;
-    /** Task priority */
-    priority: AnchorPriority;
-    /** Current lifecycle status */
-    status: AnchorStatus;
-    /** Durability tier: ephemeral (short-lived reminder, 48h TTL) or durable (long-term architecture vision) */
-    durability: AnchorDurability;
-    /** Canonical project name (e.g. 'PPT', 'X', or 'global') */
-    project: string;
-    /** Canonical root directory where the task was anchored (empty string for global tasks) */
-    cwd: string;
-    /** Creation timestamp in ms */
-    createdAt: number;
-    /** Last update timestamp in ms */
-    updatedAt: number;
-    /** Last touched timestamp in ms (resets on file touch) */
-    lastTouchedAt: number;
-    /** Associated file paths or globs, e.g. ['src/auth/*.ts'] */
-    files: string[];
-    /** Expected completion date in format 'YYYY-MM-DD' (e.g. '2026-09-24') */
-    targetDate?: string;
-    /** Optional shell command for automated physical verification (e.g. 'npm test') */
-    verifyCommand?: string;
-    /** Topic or domain tags, e.g. ['auth', 'security'] */
-    tags: string[];
-    /** Optional recurrence pattern: 'daily' for recurring daily habits */
-    recurrence?: 'daily';
-    /** Last completed date string 'YYYY-MM-DD' for recurring tasks */
-    lastCompletedDate?: string;
-    /** Decay policy overrides */
-    decay: AnchorDecayPolicy;
-    /** Settlement evidence metadata upon closure */
-    evidence?: AnchorEvidence;
-}
-interface AnchorStoreState {
-    version: number;
-    anchors: Anchor[];
-    lastSweepAt: number;
-    nextId?: number;
-}
-interface TouchMatchResult {
-    anchor: Anchor;
-    score: number;
-    matchedFiles: string[];
-    reason: 'exact-file' | 'dir-prefix' | 'tag-keyword';
-}
-interface SettlementProposal {
-    anchor: Anchor;
-    matchedFiles: string[];
-    reason: string;
-    recommendedAction: 'settle' | 'defer';
-}
-declare const EPHEMERAL_DECAY_POLICY: AnchorDecayPolicy;
-declare const DURABLE_DECAY_POLICY: AnchorDecayPolicy;
-declare const DEFAULT_DECAY_POLICY: AnchorDecayPolicy;
-
-/**
- * Detect whether a task is a short-term ephemeral reminder or a long-term architectural vision
- */
-declare function detectDurability(title: string): AnchorDurability;
-/**
- * Get custom ephemeral decay policy based on temporal span (e.g. 后天, 大后天)
- */
-declare function getEphemeralDecayPolicy(title: string): AnchorDecayPolicy;
-/**
- * Detect expected completion date from title keywords or explicit date string, returning 'YYYY-MM-DD'
- */
-declare function detectTargetDate(titleOrDate: string, now?: number): string | undefined;
-/**
- * Detect recurring patterns, e.g. daily habits
- */
-declare function detectRecurrence(title: string): 'daily' | undefined;
-/**
- * Get current date string 'YYYY-MM-DD' in local timezone
- */
-declare function getTodayDateString(timestamp?: number): string;
-/**
- * Resolve the default storage directory for Anchor (~/.anchor).
- * Hierarchy:
- * 1. Process environment: ANCHOR_DIR
- * 2. Canonical user-global store: ~/.anchor/
- * 3. Legacy Pi harness fallback: ~/.pi/agent/anchors/ (migrates automatically if present)
- */
-declare function getDefaultStorageDir(): string;
-/**
- * Acquire exclusive lockfile using atomic 'wx' file creation (zero external dependencies).
- * Features:
- * - 0 async infection (100% synchronous)
- * - Automatic stale lock eviction (>5000ms or dead PID)
- * - Exponential backoff with jitter
- */
-declare function acquireSyncLock(lockPath: string, maxWaitMs?: number, staleTimeoutMs?: number): () => void;
-/**
- * Windows-tolerant atomic rename with exponential spin-retry to combat NTFS EBUSY/EPERM file locks
- */
-declare function atomicRenameWithRetry(tempPath: string, targetPath: string, maxAttempts?: number): void;
-declare class AnchorStore {
-    readonly storageDir: string;
-    readonly statePath: string;
-    readonly archivePath: string;
-    readonly graveyardPath: string;
-    constructor(customStorageDir?: string);
-    get lockPath(): string;
-    /**
-     * Execute mutation within a cross-process exclusive lock
-     */
-    withLock<T>(fn: () => T): T;
-    private ensureDirs;
-    /**
-     * Load store state. If corrupt or missing, returns safe default.
-     */
-    loadState(): AnchorStoreState;
-    /**
-     * Atomically save store state via temp file + atomic rename with Windows NTFS spin-retry
-     */
-    saveState(state: AnchorStoreState): void;
-    private generateId;
-    /**
-     * Create a new Anchor with automatic project and cwd tagging
-     */
-    create(input: {
-        title: string;
-        description?: string;
-        priority?: AnchorPriority;
-        durability?: AnchorDurability;
-        recurrence?: 'daily';
-        cwd?: string;
-        project?: string;
-        targetDate?: string;
-        files?: string[];
-        tags?: string[];
-        verifyCommand?: string;
-        decay?: AnchorDecayPolicy;
-    }): Anchor;
-    private findAnchorIndex;
-    /**
-     * Get an anchor by ID (supports 'anc-1', '#anc-1', '1', '01')
-     */
-    get(id: string): Anchor | undefined;
-    /**
-     * List anchors. By default, if cwd is provided, only returns anchors
-     * belonging to this cwd or marked as global (''). Pass all: true for global view.
-     */
-    list(filter?: {
-        status?: AnchorStatus;
-        priority?: AnchorPriority;
-        cwd?: string;
-        all?: boolean;
-        now?: number;
-    }): Anchor[];
-    /**
-     * Update an existing anchor
-     */
-    update(id: string, patch: Partial<Omit<Anchor, 'id' | 'createdAt'>>): Anchor;
-    /**
-     * Touch an anchor to refresh its decay window and reactivate sleeping state
-     */
-    touch(id: string, timestamp?: number): Anchor;
-    /**
-     * Settle an anchor (recurring daily habits complete for today and wake up tomorrow)
-     */
-    settle(id: string, evidence?: AnchorEvidence, now?: number): Anchor;
-    /**
-     * Reverse/undo the last settled anchor, popping it from archive.jsonl back into state.json
-     */
-    undoSettle(): Anchor;
-    /**
-     * Evict anchor to graveyard.jsonl upon total decay expiry
-     */
-    dropToGraveyard(id: string, reason: string): Anchor;
-    getArchive(filter?: {
-        cwd?: string;
-        all?: boolean;
-    }): Anchor[];
-    getGraveyard(filter?: {
-        cwd?: string;
-        all?: boolean;
-    }): Anchor[];
-}
-
 interface DecayEvaluation {
     currentStatus: AnchorStatus;
     nextStatus: AnchorStatus;
@@ -241,6 +35,16 @@ declare function normalizePath(filePath: string, baseCwd?: string): string;
  * Compare two workspace CWDs safely (case-insensitive on Windows, supports subdirectory scoping)
  */
 declare function isSameOrSubPath(anchorCwd?: string, targetCwd?: string): boolean;
+/**
+ * Extract explicit file or directory paths mentioned in natural language title/description
+ * (e.g. "D:/College/优化/EXTERNAL_ARCHITECTURE_INSPIRATIONS.md", "src/auth/jwt.ts")
+ */
+declare function extractPathsFromText(text?: string): string[];
+/**
+ * Determine whether an anchor specifically targets a given workspace directory (`targetCwd`),
+ * checking `anchor.cwd`, `anchor.project`, and `anchor.files`.
+ */
+declare function isAnchorTargetingWorkspace(anchor: Anchor, targetCwd?: string): boolean;
 /**
  * Match touched files against an anchor's registered physical patterns
  * Only anchors with explicit files/globs/prefixes are matched against file touches.
@@ -253,6 +57,35 @@ declare function matchAnchorAgainstTouchedFiles(anchor: Anchor, touchedFiles: st
  */
 declare function findMatchedAnchors(anchors: Anchor[], touchedFiles: string[]): TouchMatchResult[];
 
+declare class SessionTouchObserver {
+    private touchedFiles;
+    private modifiedFiles;
+    private inspectedFiles;
+    private committed;
+    private commitMessages;
+    clear(): void;
+    /**
+     * Observe and record a tool call invocation, separating inspection from mutation
+     */
+    recordToolCall(toolName: string, input: Record<string, unknown>): void;
+    /**
+     * Add a file path manually (e.g. from git status diff)
+     */
+    addTouchedFile(filePath: string, isModified?: boolean): void;
+    getModifiedFiles(): string[];
+    getInspectedFiles(): string[];
+    getTouchedFiles(): string[];
+    hasCommitted(): boolean;
+    getCommitMessages(): string[];
+    /**
+     * Check if any commit message explicitly references or resolves an anchor
+     */
+    matchesCommit(anchor: Anchor): {
+        matched: boolean;
+        message?: string;
+    };
+}
+
 /**
  * Execute physical verification test command for an anchor
  */
@@ -261,9 +94,18 @@ declare function runPhysicalVerification(anchor: Anchor, cwd: string): {
     output: string;
 };
 /**
- * Generate settlement candidates based on files touched during the session
+ * Real-time autonomous settlement during active session:
+ * Triggered immediately when a non-error shell command runs `git commit` or a matching `verifyCommand`.
+ * Works for BOTH file-bound and file-less (`files: []`) anchors!
  */
-declare function generateSettlementProposals(store: AnchorStore, touchedFiles: string[], cwd?: string): SettlementProposal[];
+declare function tryRealtimeAutoSettle(store: AnchorStore, observer: SessionTouchObserver, cwd?: string, executedCommand?: string): Array<{
+    anchor: Anchor;
+    reason: string;
+}>;
+/**
+ * Generate settlement candidates based on files touched or commits made during the session
+ */
+declare function generateSettlementProposals(store: AnchorStore, touchedFiles: string[], cwd?: string, observer?: SessionTouchObserver): SettlementProposal[];
 /**
  * Format settlement proposal into terminal-ready card
  */
@@ -288,6 +130,14 @@ declare function classifyAnchor(anchor: Anchor, now?: number): AnchorQuadrant;
  * Group active anchors by cognitive quadrant
  */
 declare function groupAnchorsByQuadrant(anchors: Anchor[], now?: number): GroupedAnchors;
+/**
+ * Sort unfinished anchors into a single compact, priority-driven engineering list:
+ * 1. Active before Sleeping (quiet)
+ * 2. Matching current workspace before other workspaces
+ * 3. Due Today / Overdue before open-ended
+ * 4. Priority (P0 -> P1 -> P2)
+ */
+declare function sortAnchorsForDisplay(anchors: Anchor[], cwd?: string, now?: number): Anchor[];
 /**
  * Strip ANSI escape codes from string
  */
@@ -340,7 +190,7 @@ declare function formatRelativeTime(timestamp: number, now?: number): string;
  */
 declare function formatRemainingTtl(anchor: Anchor, now?: number): string | undefined;
 /**
- * Format origin creation workspace folder (provenance: where the task was born/created)
+ * Format origin workspace / project label concisely
  */
 declare function formatOrigin(anchor: Anchor | string): string;
 /**
@@ -354,39 +204,10 @@ declare function updateAnchorStatusBar(ctx: ExtensionContext, store: AnchorStore
  */
 declare function updateStartupBanner(ctx: ExtensionContext, store: AnchorStore): void;
 /**
- * Clean, columnar-aligned checklist with Target Date and Creation Time columns
+ * Clean, flat priority-sorted engineering checklist (includes both active and quiet/sleeping tasks so nothing is ever lost)
  */
 declare function openAnchorDashboard(ctx: ExtensionContext, store: AnchorStore): Promise<void>;
 
-declare class SessionTouchObserver {
-    private touchedFiles;
-    private modifiedFiles;
-    private inspectedFiles;
-    private committed;
-    private commitMessages;
-    clear(): void;
-    /**
-     * Observe and record a tool call invocation, separating inspection from mutation
-     */
-    recordToolCall(toolName: string, input: Record<string, unknown>): void;
-    /**
-     * Add a file path manually (e.g. from git status diff)
-     */
-    addTouchedFile(filePath: string, isModified?: boolean): void;
-    getModifiedFiles(): string[];
-    getInspectedFiles(): string[];
-    getTouchedFiles(): string[];
-    hasCommitted(): boolean;
-    getCommitMessages(): string[];
-    /**
-     * Check if any commit message explicitly references or resolves an anchor
-     */
-    matchesCommit(anchor: Anchor): {
-        matched: boolean;
-        message?: string;
-    };
-}
-
 /**
  * Universal multi-language comment generator.
  * Maps file extension to safe comment syntax.
@@ -451,4 +272,4 @@ declare class AnchorProtocol {
     };
 }
 
-export { type AgentAdapter, type Anchor, type AnchorDecayPolicy, type AnchorDurability, type AnchorEvidence, type AnchorPriority, AnchorProtocol, type AnchorQuadrant, type AnchorStatus, AnchorStore, type AnchorStoreState, COMMENT_FORMATS, DEFAULT_DECAY_POLICY, DURABLE_DECAY_POLICY, type DecayEvaluation, EPHEMERAL_DECAY_POLICY, type GroupedAnchors, SessionTouchObserver, type SettlementProposal, type SweepResult, type TouchMatchResult, acquireSyncLock, atomicRenameWithRetry, classifyAnchor, detectDurability, detectRecurrence, detectTargetDate, evaluateAnchorDecay, findMatchedAnchors, formatCreationTime, formatOrigin, formatRelativeTime, formatRemainingTtl, formatSettlementCard, formatTargetDate, generateSettlementProposals, getDefaultStorageDir, getDisplayWidth, getEphemeralDecayPolicy, getTodayDateString, globToRegExp, groupAnchorsByQuadrant, hasActiveUI, isSameOrSubPath, makeSafeTaskAnnotation, matchAnchorAgainstTouchedFiles, normalizePath, openAnchorDashboard, padToWidth, renderActiveAnchorsContext, renderColdStartAnchorsContext, runPhysicalVerification, stripAnsi, sweepStore, truncateToWidth, updateAnchorStatusBar, updateStartupBanner };
+export { type AgentAdapter, Anchor, AnchorProtocol, type AnchorQuadrant, AnchorStatus, AnchorStore, COMMENT_FORMATS, type DecayEvaluation, type GroupedAnchors, SessionTouchObserver, SettlementProposal, type SweepResult, TouchMatchResult, classifyAnchor, evaluateAnchorDecay, extractPathsFromText, findMatchedAnchors, formatCreationTime, formatOrigin, formatRelativeTime, formatRemainingTtl, formatSettlementCard, formatTargetDate, generateSettlementProposals, getDisplayWidth, globToRegExp, groupAnchorsByQuadrant, hasActiveUI, isAnchorTargetingWorkspace, isSameOrSubPath, makeSafeTaskAnnotation, matchAnchorAgainstTouchedFiles, normalizePath, openAnchorDashboard, padToWidth, renderActiveAnchorsContext, renderColdStartAnchorsContext, runPhysicalVerification, sortAnchorsForDisplay, stripAnsi, sweepStore, truncateToWidth, tryRealtimeAutoSettle, updateAnchorStatusBar, updateStartupBanner };