fluffy-context 0.2.0 → 0.3.0

package/dist/src/runtime/types.d.ts

@@ -0,0 +1,294 @@
+export type ContextStatus = 'draft' | 'active' | 'stable' | 'archived' | 'deleted';
+export type SnapshotMode = 'baseline' | 'patch';
+export interface GitState {
+    root: string | null;
+    branch: string | null;
+    commit: string | null;
+}
+export interface ContextMetadata {
+    id: string;
+    schemaVersion: 1;
+    title: string;
+    projectRoot: string;
+    branch: string | null;
+    commit: string | null;
+    createdAt: string;
+    updatedAt: string;
+    lastUsedAt: string | null;
+    usageCount: number;
+    status: ContextStatus;
+    currentSnapshotId: string | null;
+    tags: string[];
+    dependencies: string[];
+}
+export interface StructuredContext {
+    progressSummary: string;
+    lastError: string | null;
+    completed: string[];
+    pendingTasks: string[];
+    decisions: string[];
+    risks: string[];
+    relatedFiles: string[];
+}
+export type ContextPatch = Partial<StructuredContext>;
+export interface Snapshot {
+    snapshotId: string;
+    schemaVersion: 1;
+    contextId: string;
+    parentSnapshotId: string | null;
+    baseSnapshotId: string;
+    mode: SnapshotMode;
+    createdAt: string;
+    branch: string | null;
+    commit: string | null;
+    contentHash: string;
+    rebuildHash: string;
+    content?: StructuredContext;
+    patch?: ContextPatch;
+}
+export interface Manifest {
+    schemaVersion: 1;
+    layoutVersion: 'compact-json-v1';
+    projectId: string;
+    projectRoot: string;
+    initializedAt: string;
+}
+export interface IndexEntry {
+    contextId: string;
+    title: string;
+    status: ContextStatus;
+    branch: string | null;
+    commit: string | null;
+    currentSnapshotId: string | null;
+    updatedAt: string;
+}
+export interface IndexFile {
+    schemaVersion: 1;
+    rebuiltAt: string;
+    contexts: IndexEntry[];
+}
+export interface CheckpointInput {
+    contextId?: string;
+    absorbNotes?: boolean;
+    title?: string;
+    progressSummary?: string;
+    lastError?: string | null;
+    completed?: string[];
+    pendingTasks?: string[];
+    decisions?: string[];
+    risks?: string[];
+    relatedFiles?: string[];
+}
+export type NoteKind = 'problem' | 'action' | 'observation' | 'decision';
+export type NoteStatus = 'open' | 'resolved';
+export type NoteActor = 'agent' | 'human';
+export interface Note {
+    noteId: string;
+    schemaVersion: 1;
+    kind: NoteKind;
+    message: string;
+    actor: NoteActor;
+    contextId: string | null;
+    snapshotId: string | null;
+    relatedFiles: string[];
+    status: NoteStatus;
+    absorbedBySnapshotId: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface NoteInput {
+    kind?: NoteKind;
+    actor?: NoteActor;
+    contextId?: string;
+    snapshotId?: string;
+    relatedFiles?: string[];
+    status?: NoteStatus;
+}
+export interface NoteFile {
+    schemaVersion: 1;
+    items: Note[];
+}
+export interface NoteQuery {
+    contextId?: string;
+    openOnly?: boolean;
+    limit?: number;
+    maxChars?: number;
+}
+export interface ActivityItem {
+    type: 'note' | 'checkpoint';
+    occurredAt: string;
+    contextId: string;
+    snapshotId?: string;
+    noteId?: string;
+    kind?: NoteKind;
+    message?: string;
+    actor?: NoteActor;
+    status?: NoteStatus;
+    absorbedBySnapshotId?: string | null;
+    title?: string;
+}
+export interface ActivityQuery extends NoteQuery {
+    since?: string;
+}
+export interface ActivityResult {
+    projectRoot: string;
+    items: ActivityItem[];
+}
+export type KnowledgeStatus = 'candidate' | 'verified' | 'deprecated' | 'rejected';
+export type DeadendStatus = 'candidate' | 'verified' | 'obsolete' | 'rejected';
+export interface Knowledge {
+    knowledgeId: string;
+    kind: string;
+    statement: string;
+    scope: string;
+    confidence: number;
+    status: KnowledgeStatus;
+    sourceContextIds: string[];
+    sourceSnapshotIds: string[];
+    supportingEvidence: string[];
+    createdAt: string;
+    updatedAt: string;
+}
+export interface KnowledgeInput {
+    kind?: string;
+    scope?: string;
+    sourceContextId?: string;
+    sourceSnapshotId?: string;
+    evidence?: string[];
+}
+export interface KnowledgeDiscoverOptions {
+    scope?: string;
+    statuses?: KnowledgeStatus[];
+    limit?: number;
+    maxChars?: number;
+}
+export interface KnowledgeDiscoveryHit {
+    knowledge: Knowledge;
+    score: number;
+    matchedTerms: string[];
+    matchedFields: string[];
+    why: string[];
+}
+export interface KnowledgeConflictGroup {
+    scope: string;
+    knowledgeIds: string[];
+    statements: string[];
+}
+export interface KnowledgeDiscoveryResult {
+    query: string;
+    total: number;
+    truncated: boolean;
+    hits: KnowledgeDiscoveryHit[];
+    duplicateIds: string[][];
+    possibleConflicts: KnowledgeConflictGroup[];
+}
+export interface DeadendDiscoverOptions {
+    scope?: string;
+    statuses?: DeadendStatus[];
+    limit?: number;
+    maxChars?: number;
+}
+export interface DeadendDiscoveryHit {
+    deadend: Deadend;
+    score: number;
+    matchedTerms: string[];
+    matchedFields: string[];
+}
+export interface DeadendDiscoveryResult {
+    query: string;
+    total: number;
+    truncated: boolean;
+    hits: DeadendDiscoveryHit[];
+}
+export interface DeadendInput {
+    scope?: string;
+    sourceContextId?: string;
+    sourceSnapshotId?: string;
+    evidence?: string[];
+}
+export interface Deadend {
+    deadendId: string;
+    attempt: string;
+    reason: string;
+    observedEvidence: string[];
+    scope: string;
+    status: DeadendStatus;
+    sourceContextId: string | null;
+    sourceSnapshotId: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface KnowledgeFile {
+    schemaVersion: 1;
+    items: Knowledge[];
+}
+export interface DeadendFile {
+    schemaVersion: 1;
+    items: Deadend[];
+}
+export interface ResumeSummary extends StructuredContext {
+    branchOrCommitDrift: boolean;
+}
+export interface ResumeResult {
+    context: ContextMetadata;
+    snapshot: Snapshot;
+    resumeSummary: ResumeSummary;
+    details: StructuredContext;
+}
+export interface AgentLoadOptions {
+    contextId?: string;
+    maxChars?: number;
+    includeDetails?: boolean;
+    query?: string;
+    scope?: string;
+}
+export interface AgentLoadResult {
+    projectRoot: string;
+    context: ContextMetadata;
+    snapshot: Snapshot;
+    resumeSummary: ResumeSummary;
+    details?: StructuredContext;
+    knowledge: KnowledgeDiscoveryResult | null;
+    verifiedDeadendIds: string[];
+}
+export interface AgentSaveResult {
+    projectRoot: string;
+    result: CheckpointResult;
+}
+export interface ContextSearchOptions {
+    contextId?: string;
+    scope?: string;
+    limit?: number;
+    maxChars?: number;
+}
+export interface ContextSearchHit {
+    context: ContextMetadata;
+    snapshotId: string;
+    score: number;
+    matchedTerms: string[];
+    matchedFields: string[];
+    summary: ResumeSummary;
+}
+export interface ContextSearchResult {
+    projectRoot: string;
+    query: string;
+    total: number;
+    truncated: boolean;
+    hits: ContextSearchHit[];
+    knowledge: KnowledgeDiscoveryResult;
+    verifiedDeadendIds: string[];
+}
+export type CheckpointResult = {
+    status: 'saved';
+    context: ContextMetadata;
+    snapshot: Snapshot;
+} | {
+    status: 'no_change';
+    context: ContextMetadata;
+    snapshot: Snapshot;
+} | {
+    status: 'rate_limited';
+    context: ContextMetadata;
+    snapshot: Snapshot;
+    retryAt: string;
+};

package/dist/src/storage/atomic-write.d.ts

@@ -0,0 +1 @@
+export declare function atomicWriteJson(filePath: string, value: unknown): Promise<void>;

package/dist/src/storage/json-store.d.ts

@@ -0,0 +1,6 @@
+export declare class JsonStoreError extends Error {
+    readonly filePath: string;
+    constructor(filePath: string, message: string);
+}
+export declare function isRecord(value: unknown): value is Record<string, unknown>;
+export declare function readJson<T>(filePath: string, validate?: (value: unknown) => value is T): Promise<T>;

package/dist/src/storage/layout.d.ts

@@ -0,0 +1,13 @@
+export declare function contextRoot(projectRoot: string): string;
+export declare function manifestPath(projectRoot: string): string;
+export declare function indexPath(projectRoot: string): string;
+export declare function ignoredPath(projectRoot: string): string;
+export declare function contextsRoot(projectRoot: string): string;
+export declare function contextDirectory(projectRoot: string, contextId: string): string;
+export declare function contextMetadataPath(projectRoot: string, contextId: string): string;
+export declare function snapshotsDirectory(projectRoot: string, contextId: string): string;
+export declare function snapshotPath(projectRoot: string, contextId: string, snapshotId: string): string;
+export declare function locksDirectory(projectRoot: string): string;
+export declare function knowledgePath(projectRoot: string): string;
+export declare function deadendsPath(projectRoot: string): string;
+export declare function notesPath(projectRoot: string): string;

package/dist/src/storage/lock.d.ts

@@ -0,0 +1 @@
+export declare function withLock<T>(lockPath: string, operation: () => Promise<T>): Promise<T>;

package/dist/src/version.d.ts

@@ -0,0 +1 @@
+export declare const VERSION = "0.3.0";

package/dist/src/version.js

@@ -1 +1 @@
-export const VERSION = '0.2.0';
+export const VERSION = '0.3.0';

package/package.json

@@ -1,41 +1,73 @@
 {
   "name": "fluffy-context",
-  "version": "0.2.0",
-  "description": "面向 AI 编程会话的本地上下文运行时 CLI",
+  "version": "0.3.0",
+  "description": "Local context management CLI and MCP tools for AI coding agents",
+  "license": "MIT",
+  "author": "FluffyChi-Xing",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/FluffyChi-Xing/fluffy-context.git"
+  },
+  "homepage": "https://github.com/FluffyChi-Xing/fluffy-context#readme",
+  "bugs": {
+    "url": "https://github.com/FluffyChi-Xing/fluffy-context/issues"
+  },
   "type": "module",
   "keywords": [
-    "context-runtime",
     "ai-agent",
-    "coding-agent",
-    "developer-tools",
+    "agent-context",
+    "claude-code",
     "cli",
     "context-management",
-    "session-resume",
-    "knowledge-base",
-    "deadend-tracking",
-    "snapshot"
+    "context-runtime",
+    "developer-tools",
+    "mcp",
+    "model-context-protocol",
+    "session-resume"
   ],
   "bin": {
     "ctx": "dist/src/cli/main.js"
   },
+  "types": "./dist/src/agent/index.d.ts",
   "exports": {
-    ".": "./dist/src/agent/index.js",
-    "./agent": "./dist/src/agent/index.js",
-    "./version": "./dist/src/version.js"
+    ".": {
+      "types": "./dist/src/agent/index.d.ts",
+      "default": "./dist/src/agent/index.js"
+    },
+    "./agent": {
+      "types": "./dist/src/agent/index.d.ts",
+      "default": "./dist/src/agent/index.js"
+    },
+    "./version": {
+      "types": "./dist/src/version.d.ts",
+      "default": "./dist/src/version.js"
+    }
   },
   "files": [
-    "dist/src"
+    "dist/src",
+    "README.md",
+    "LICENSE",
+    "skills/fluffy-context/SKILL.md"
   ],
   "engines": {
     "node": ">=20.19.0"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",
-    "test": "npm run build && node --test dist/test/*.test.js",
+    "typecheck": "tsc -p tsconfig.test.json --noEmit",
+    "test": "tsc -p tsconfig.test.json && node --test dist/test/*.test.js",
+    "pack:check": "tsc -p tsconfig.test.json && node --test dist/test/package-smoke.test.js",
+    "prepack": "npm run build",
+    "prepublishOnly": "npm test && npm run pack:check",
     "ctx": "npm run build && node dist/src/cli/main.js"
   },
   "devDependencies": {
+    "@modelcontextprotocol/client": "^2.0.0",
     "@types/node": "^22.10.0",
     "typescript": "^5.7.2"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/server": "^2.0.0",
+    "zod": "^4.4.3"
   }
 }