fluffy-context 1.0.0-beta.1 → 1.0.0-beta.2

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # 发布说明
 
+## 1.0.0-beta.2
+
+- 新增 `ctx upgrade`：已有项目数据预检、带 SHA-256 清单的流式备份、v1 导入或状态对齐、完整日志无损归档、投影重建及历史哈希验证。
+- `--dry-run` 不写数据；默认向 stderr 输出按实际字节、记录和日志段计数的阶段进度，stdout 保持 JSON；`--no-progress` 可关闭进度。
+- 成功后恢复原运行时状态，保留禁用策略；失败保留备份及现场。支持原始数据未改变时恢复缺失回执的中断导入。
+- 备份排除旧备份、开发产物、锁及运行时临时凭据；拒绝符号链接，避免向项目外读写。压缩不丢弃事件，也不自动提升知识可信状态。
+
+升级本地命令：`npm install --global fluffy-context@1.0.0-beta.2`。关闭目标项目的 agent/MCP 会话后，运行 `ctx upgrade --dry-run` 预览，再运行 `ctx upgrade` 执行。备份会额外占用磁盘；当前全链校验仍需将事件加载到内存，数十个分支的长期真实项目验收仍待完成。
+
 ## 1.0.0-beta.1
 
 这是项目认知层的首个 beta，面向愿意验证新工作流的用户；npm `latest` 保持 0.8.0。本版本不承诺所有 agent 都会自动调用工具，也不将字符估算宣传为真实 token 节省。

package/README.md

@@ -6,7 +6,9 @@
 
 它是 LLM 与项目之间的一层本地记忆：保存工作进度，积累经过验证的项目知识，按当前任务提供有长度预算的上下文。CLI 命令是 `ctx`，也提供 MCP 和 JavaScript / TypeScript API。
 
-> 本文对应 **1.0.0-beta.1**。稳定通道仍为 0.8.0；以下新工作流需要安装 beta。[升级说明与已知限制](CHANGELOG.md) · [1.0 后续计划](ROADMAP-1.0.md)
+> 本文对应 **1.0.0-beta.2**。稳定通道仍为 0.8.0；以下新工作流需要安装 beta。[升级说明与已知限制](CHANGELOG.md) · [1.0 后续计划](ROADMAP-1.0.md)
+
+**beta.2 新增 `ctx upgrade`**，用于已有项目的数据升级与日志归档；beta.1 不含这个命令。
 
 ## 它能帮你做什么
 
@@ -58,6 +60,23 @@ ctx checkpoint --title "支付回调修复" --progress "已定位重复回调导
 
 这些命令返回 JSON，方便 agent 和脚本读取。你也可以直接在终端使用。
 
+## 已有项目怎样升级
+
+使用包含 `upgrade` 的新版 ctx，先关闭这个项目的 agent/MCP 会话，然后在项目目录执行：
+
+```sh
+ctx upgrade --dry-run     # 只检查数据和备份大小，不写入、不停运行时
+ctx upgrade              # 备份、迁移、归档、验证
+```
+
+其它项目可用 `ctx upgrade --path /path/to/project`。终端显示各阶段进度：备份按实际字节、迁移按记录、日志校验和压缩按段计数；百分比表示当前阶段，不是剩余时间预测。脚本可用 `--no-progress` 关闭进度，stdout 始终返回 JSON。
+
+升级保留任务、知识状态和完整事件历史，支持仅有旧 Context 数据的项目，也支持已有认知日志的 0.8.0 项目。运行时升级前会停止，成功后恢复原来的运行状态；禁用策略保持不变。
+
+备份保存在 `.context/backups/upgrade-*/`，包含 `data/` 原文件、`backup.json` 哈希清单和成功后的 `upgrade.json` 回执。备份不包含旧备份、开发打包产物、锁和运行时临时凭据。**备份会额外占用磁盘，日志压缩节省量不包含备份体积。**
+
+重复升级不会重复导入相同数据，但每次执行都会创建独立备份。校验失败时会报错并保留现场，不删除历史、不自动覆盖还原；关闭其它写入者后可以重试。压缩后的日志不能与 0.8.0 混用，完成后用新版 ctx 重新连接 agent。
+
 ## 怎样接入你的 AI 编程工具
 
 接入后，理想的日常流程是：**任务开始取上下文 → 开发与验证 → 阶段结束存进度**。不需要人每轮对话都操作 ctx，但 agent 是否会触发取决于宿主的接入方式。

package/ROADMAP-1.0.md

@@ -1,6 +1,6 @@
 # fluffy-context 1.0：可用的项目认知层
 
-状态：第一阶段实现及三批实际使用驱动的迭代，发布候选版本 1.0.0-beta.1，稳定通道仍为 0.8.0。基线：0.8.0。目标不是保存更多对话，而是让不同 agent 在适当时刻取得可信项目知识，并留下可被下次工作验证和复用的结果。
+状态：第一阶段实现及三批实际使用驱动的迭代，当前版本 1.0.0-beta.2，稳定通道仍为 0.8.0。基线：0.8.0。目标不是保存更多对话，而是让不同 agent 在适当时刻取得可信项目知识，并留下可被下次工作验证和复用的结果。
 
 ## 产品约束
 
@@ -68,3 +68,7 @@ Claude Hook 同时修复输出契约：按照 [Claude 官方 Hook 文档](https:
 - 接入修复批：40 项测试通过，从 tarball 安装并逐文件核验 106 个文件；真实 init 发现并修复旧源码路径被误判为 MCP 冲突的问题；默认 inject 去除重复 provenance 包装。
 - 存储治理批：114 项完整回归通过，dev.1 全局产物逐文件核验 110 个文件。真实首段从 1,050,216 字节压缩到 189,044 字节，解压后与升级前备份逐字节一致；全链 749 条事件校验通过。结果与安装回执在 `.context/builds/`，未将测试夹具写入真实项目。
 - 检索品质批：真实 `knowledge discover --limit 1 --max-chars 450` 暴露全库成对诊断膨胀，并将不符合查询治理条件的记录带出。dev.2 让诊断使用同样过滤、保守冲突规则、候选扫描上限和正文预算，默认查询不泄漏候选或无关记录。
+
+## beta.2 升级入口
+
+新增 `ctx upgrade`，提供只读预览、流式哈希备份、数据迁移与无损日志归档、阶段进度和运行时状态恢复。缺失导入回执且原始数据未变时可以重试；更复杂的损坏恢复仍需人工检查。已有项目不需要手动串联底层迁移与归档命令。

package/dist/src/agent/index.d.ts

@@ -2,6 +2,7 @@ export * from './api.js';
 export { injectContext } from '../compiler/inject.js';
 export { importMemory } from '../cognition/import-memory.js';
 export { setupProject } from '../runtime/setup.js';
+export { upgradeProject } from '../runtime/upgrade.js';
 export type { MaterializeRecipeInput, TransitionRecipeInput, } from '../cognition/recipes.js';
 export type { MaterializeSkillInput, RecordSkillInvocationInput, RecordSkillOutcomeInput, TransitionSkillInput, } from '../cognition/skills.js';
 export type { AcceptEvolutionCandidateInput, ProposeEvolutionInput, ProposeEvolutionResult, TransitionEvolutionProposalInput, } from '../cognition/evolution.js';

package/dist/src/agent/index.js

@@ -2,6 +2,7 @@ export * from './api.js';
 export { injectContext } from '../compiler/inject.js';
 export { importMemory } from '../cognition/import-memory.js';
 export { setupProject } from '../runtime/setup.js';
+export { upgradeProject } from '../runtime/upgrade.js';
 export { contextCompile } from './api.js';
 export { compileContext } from '../compiler/compile.js';
 export { canonicalJson, contentHash, estimateTokens, rebuildManifestHash, validateManifestIdentity } from '../compiler/identity.js';

package/dist/src/cli/main.js

@@ -14,6 +14,8 @@ import { readGitWorktreeState } from '../git/git-adapter.js';
 import { inspectClaudeIntegration, installClaudeIntegration } from '../integrations/claude-code.js';
 import { doctor, status } from '../runtime/diagnostics.js';
 import { setupProject } from '../runtime/setup.js';
+import { upgradeProject } from '../runtime/upgrade.js';
+import { consoleProgress } from './progress.js';
 import { importMemory } from '../cognition/import-memory.js';
 import { injectContext } from '../compiler/inject.js';
 import { discoverKnowledge, learnKnowledge, listKnowledge, verifyKnowledge, recordDeadend, listDeadends, verifyDeadend, transitionKnowledge, transitionDeadend } from '../runtime/knowledge.js';
@@ -87,6 +89,12 @@ function graphHopsOption(args) {
 const recipeBudgets = (value) => value === undefined ? undefined : Object.fromEntries(value.split(',').map((item) => { const [section, budget] = item.split('=', 2); const parsed = Number(budget); if (!section || !Number.isSafeInteger(parsed) || parsed < 0 || parsed > 100_000)
     throw new Error('--budgets must be section=non-negative-integer up to 100000'); return [section, parsed]; }));
 const HELP = {
+    upgrade: `usage: ctx upgrade [--path <path>] [--dry-run] [--no-progress]
+
+Back up and upgrade existing project data to the 1.0 beta layout, preserving all history.
+Close other agent/MCP sessions first. Progress goes to stderr; stdout remains JSON.
+--dry-run validates and previews without writing or stopping the runtime.
+--no-progress suppresses progress output. The prior runtime running state is restored on success.`,
     init: `usage: ctx init [path] [--path <path>] [--no-start] [--no-integrations]
 
 Initialize, migrate, verify, install project guidance and start the runtime. Re-running init preserves policy.
@@ -472,7 +480,7 @@ Stop the local runtime through authenticated loopback IPC.`,
 Internal runtime daemon entry point.`,
 };
 function usage() {
-    return `usage: ctx init|inject|import|report|checkpoint|resume|orient|compile|expand|usage|agent|hook|integrate|status|doctor|learn|knowledge|deadend|deadends|note|activity|migrate|runtime|filesystem|feedback|skill|recipe|evolution|journal [options]
+    return `usage: ctx init|upgrade|inject|import|report|checkpoint|resume|orient|compile|expand|usage|agent|hook|integrate|status|doctor|learn|knowledge|deadend|deadends|note|activity|migrate|runtime|filesystem|feedback|skill|recipe|evolution|journal [options]
 
 Run \"ctx <command> --help\" for command details.`;
 }
@@ -535,6 +543,19 @@ async function run(args) {
     const command = args[0];
     const target = option(args, '--path');
     switch (command) {
+        case 'upgrade': {
+            validateOptions(args.slice(1), ['--path', '--dry-run', '--no-progress'], ['--path']);
+            validatePositionals(positionals(args.slice(1), ['--path']), 0, HELP.upgrade);
+            try {
+                print(await upgradeProject(target, { dryRun: args.includes('--dry-run'), onProgress: args.includes('--no-progress') ? undefined : consoleProgress() }));
+            }
+            catch (error) {
+                if (process.stderr.isTTY && !args.includes('--no-progress'))
+                    process.stderr.write('\n');
+                throw error;
+            }
+            return;
+        }
         case 'init': {
             validateOptions(args.slice(1), ['--path', '--no-start', '--no-integrations'], ['--path']);
             const values = positionals(args.slice(1), ['--path']);

package/dist/src/cli/progress.d.ts

@@ -0,0 +1,2 @@
+import type { ProgressReporter } from '../cognition/progress.js';
+export declare function consoleProgress(stream?: Pick<NodeJS.WriteStream, 'write' | 'isTTY'>): ProgressReporter;

package/dist/src/cli/progress.js

@@ -0,0 +1,21 @@
+export function consoleProgress(stream = process.stderr) {
+    let lastPhase = '';
+    let lastBucket = -1;
+    let lastWrite = 0;
+    return ({ phase, completed, total, unit = '' }) => {
+        const ratio = total === null ? null : total === 0 ? 1 : Math.min(1, completed / total);
+        const bucket = ratio === null ? -1 : Math.floor(ratio * 10);
+        const changed = phase !== lastPhase;
+        if (!changed && bucket === lastBucket && (ratio !== 1 || lastBucket === 10))
+            return;
+        if (!changed && ratio !== 1 && Date.now() - lastWrite < 100)
+            return;
+        const filled = ratio === null ? 0 : Math.floor(ratio * 20);
+        const bar = ratio === null ? '····················' : '#'.repeat(filled) + '-'.repeat(20 - filled);
+        const value = ratio === null ? 'working' : `${Math.floor(ratio * 100)}% ${completed}/${total} ${unit}`;
+        stream.write(`${stream.isTTY ? '\r\x1b[2K' : ''}[${bar}] ${phase} ${value}${stream.isTTY && phase !== 'complete' && phase !== 'preview-complete' ? '' : '\n'}`);
+        lastPhase = phase;
+        lastBucket = bucket;
+        lastWrite = Date.now();
+    };
+}

package/dist/src/cognition/journal.d.ts

@@ -1,4 +1,5 @@
 import type { CognitionEvent, CognitionEventSource, CognitionEventType, CognitionGitAnchor } from './types.js';
+import type { ProgressReporter } from './progress.js';
 export interface AppendEventInput<T = Record<string, unknown>> {
     eventId?: string;
     type: CognitionEventType;
@@ -19,11 +20,13 @@ export interface AppendEventInput<T = Record<string, unknown>> {
 export declare function eventHash<T>(event: Omit<CognitionEvent<T>, 'hash'>): string;
 export declare function readJournal(startPath?: string, options?: {
     allowPartialTail?: boolean;
+    onProgress?: ProgressReporter;
 }): Promise<CognitionEvent[]>;
 export declare function verifyJournal(startPath?: string): Promise<CognitionEvent[]>;
 export declare function compactJournal(startPath?: string, options?: {
     apply?: boolean;
     minBytes?: number;
+    onProgress?: ProgressReporter;
 }): Promise<{
     applied: boolean;
     eligible: string[];

package/dist/src/cognition/journal.js

@@ -258,6 +258,8 @@ export async function readJournal(startPath, options = {}) {
     const events = [];
     let previousHash = null;
     const files = await journalFiles(projectRoot);
+    options.onProgress?.({ phase: 'verify-journal', completed: 0, total: files.length, unit: 'segments' });
+    let completed = 0;
     for (const file of files) {
         const content = (await readSegment(projectRoot, file)).toString('utf8');
         const lines = content.split('\n');
@@ -283,6 +285,7 @@ export async function readJournal(startPath, options = {}) {
             previousHash = event.hash;
             events.push(event);
         }
+        options.onProgress?.({ phase: 'verify-journal', completed: ++completed, total: files.length, unit: 'segments' });
     }
     return events;
 }
@@ -295,7 +298,7 @@ export async function compactJournal(startPath, options = {}) {
     if (!Number.isSafeInteger(minBytes) || minBytes < 0)
         throw new Error('minBytes must be a non-negative integer');
     const operation = async () => {
-        const events = await verifyJournal(root);
+        const events = await readJournal(root, { allowPartialTail: false, onProgress: options.onProgress });
         const before = await journalStorage(root);
         const eligible = [];
         for (const file of await journalFiles(root)) {
@@ -303,13 +306,16 @@ export async function compactJournal(startPath, options = {}) {
                 eligible.push(file);
         }
         if (options.apply) {
-            for (const file of eligible)
+            options.onProgress?.({ phase: 'archive', completed: 0, total: eligible.length, unit: 'segments' });
+            for (const [index, file] of eligible.entries()) {
                 await archiveSegment(root, file);
+                options.onProgress?.({ phase: 'archive', completed: index + 1, total: eligible.length, unit: 'segments' });
+            }
             // Complete deletion after an interrupted publication, but only after validation.
             for (const file of await journalFiles(root))
                 if (file.endsWith('.gz'))
                     await archiveSegment(root, file);
-            const replay = await verifyJournal(root);
+            const replay = await readJournal(root, { allowPartialTail: false, onProgress: options.onProgress });
             if (replay.length !== events.length || replay.at(-1)?.hash !== events.at(-1)?.hash)
                 throw new Error('journal replay changed during compaction');
         }

package/dist/src/cognition/migration-v1.d.ts

@@ -1,5 +1,6 @@
+import type { ProgressReporter } from './progress.js';
 import { type MigrationReport } from './types.js';
-export declare function importV1(startPath?: string): Promise<MigrationReport>;
+export declare function importV1(startPath?: string, onProgress?: ProgressReporter): Promise<MigrationReport>;
 export declare function reconcileV1State(startPath?: string): Promise<void>;
 export declare function verifyV1Import(startPath?: string): Promise<{
     verified: boolean;

package/dist/src/cognition/migration-v1.js

@@ -41,13 +41,14 @@ async function readOptional(filePath) {
         throw error;
     }
 }
-async function sourceRecords(projectRoot) {
+async function sourceRecords(projectRoot, onProgress) {
     const sources = [];
     const records = [];
     const snapshotAnchors = new Map();
     const v1ManifestPath = manifestPath(projectRoot);
     sources.push({ filePath: v1ManifestPath, content: await readFile(v1ManifestPath, 'utf8') });
     const contextIds = (await readdir(contextsRoot(projectRoot))).sort();
+    onProgress?.({ phase: 'scan-contexts', completed: 0, total: contextIds.length, unit: 'contexts' });
     for (const contextId of contextIds) {
         const contextFile = contextMetadataPath(projectRoot, contextId);
         const contextContent = await readFile(contextFile, 'utf8');
@@ -73,6 +74,7 @@ async function sourceRecords(projectRoot) {
                 sourceHash: sha256(content),
             });
         }
+        onProgress?.({ phase: 'scan-contexts', completed: contextIds.indexOf(contextId) + 1, total: contextIds.length, unit: 'contexts' });
     }
     const noteFile = path.join(projectRoot, '.context', 'notes.json');
     const knowledgeFile = path.join(projectRoot, '.context', 'knowledge.json');
@@ -106,7 +108,11 @@ async function writeV2Metadata(projectRoot) {
     const v1 = await loadManifest(projectRoot);
     const manifest = { schemaVersion: 2, layoutVersion: COGNITION_LAYOUT_VERSION, projectId: v1.projectId, createdAt: new Date().toISOString(), policyVersion: 1 };
     const policy = { schemaVersion: 2, enabled: true, autoStart: true, allowHookStartup: true, inactivityTimeoutMs: 300_000, promptIntentMaxChars: 500, filesystemEventsEnabled: false, retentionMaxBytes: 64 * 1024 * 1024 };
-    await Promise.all([atomicWriteJson(cognitionManifestPath(projectRoot), manifest), atomicWriteJson(cognitionPolicyPath(projectRoot), policy)]);
+    // Interrupted imports must not replace an existing project's opt-out policy.
+    if (await readOptional(cognitionManifestPath(projectRoot)) === null)
+        await atomicWriteJson(cognitionManifestPath(projectRoot), manifest);
+    if (await readOptional(cognitionPolicyPath(projectRoot)) === null)
+        await atomicWriteJson(cognitionPolicyPath(projectRoot), policy);
 }
 async function quarantineReadiness(projectRoot, readiness) {
     await mkdir(cognitionQuarantineDirectory(projectRoot), { recursive: true });
@@ -117,7 +123,7 @@ async function quarantineReadiness(projectRoot, readiness) {
         issues: readiness.issues,
     });
 }
-export async function importV1(startPath) {
+export async function importV1(startPath, onProgress) {
     const projectRoot = await resolveProjectRoot(startPath);
     return withLock(`${locksDirectory(projectRoot)}/cognition-migration.lock`, async () => {
         const readiness = await migrationReadiness(projectRoot);
@@ -126,7 +132,7 @@ export async function importV1(startPath) {
             await quarantineReadiness(projectRoot, report);
             return report;
         }
-        const { records, sourceHash } = await sourceRecords(projectRoot);
+        const { records, sourceHash } = await sourceRecords(projectRoot, onProgress);
         const existingReceipt = await readOptional(cognitionV1ImportPath(projectRoot));
         if (existingReceipt) {
             const receipt = JSON.parse(existingReceipt);
@@ -138,6 +144,7 @@ export async function importV1(startPath) {
         }
         await writeV2Metadata(projectRoot);
         const importedEventIds = [];
+        onProgress?.({ phase: 'import-records', completed: 0, total: records.length, unit: 'records' });
         for (const record of records) {
             const event = await appendEvent(projectRoot, {
                 type: eventType(record),
@@ -148,6 +155,7 @@ export async function importV1(startPath) {
                 payload: { record: record.record, sourcePath: record.sourcePath, sourceHash: record.sourceHash, anchorProvenance: record.git.branch === null && record.git.head === null ? 'global' : 'snapshot' },
             });
             importedEventIds.push(event.event.eventId);
+            onProgress?.({ phase: 'import-records', completed: importedEventIds.length, total: records.length, unit: 'records' });
         }
         await rebuildProjections(projectRoot);
         await atomicWriteJson(cognitionV1SyncPath(projectRoot), { schemaVersion: 2, fingerprint: await v1Fingerprint(projectRoot), updatedAt: new Date().toISOString() });

package/dist/src/cognition/progress.d.ts

@@ -0,0 +1,7 @@
+export interface ProgressUpdate {
+    phase: string;
+    completed: number;
+    total: number | null;
+    unit?: string;
+}
+export type ProgressReporter = (update: ProgressUpdate) => void;

package/dist/src/cognition/progress.js

@@ -0,0 +1 @@
+export {};

package/dist/src/cognition/readiness.d.ts

@@ -1,2 +1,3 @@
 import type { MigrationReadiness } from './types.js';
-export declare function migrationReadiness(startPath?: string): Promise<MigrationReadiness>;
+import type { ProgressReporter } from './progress.js';
+export declare function migrationReadiness(startPath?: string, onProgress?: ProgressReporter): Promise<MigrationReadiness>;

package/dist/src/cognition/readiness.js

@@ -14,7 +14,7 @@ async function exists(filePath) {
         return false;
     }
 }
-export async function migrationReadiness(startPath) {
+export async function migrationReadiness(startPath, onProgress) {
     const projectRoot = await resolveProjectRoot(startPath);
     const counts = { contexts: 0, snapshots: 0, notes: 0, knowledge: 0, deadends: 0 };
     const issues = [];
@@ -40,7 +40,8 @@ export async function migrationReadiness(startPath) {
     catch (error) {
         issues.push(`v1 contexts: ${error instanceof Error ? error.message : 'unavailable'}`);
     }
-    for (const contextId of contextIds) {
+    onProgress?.({ phase: 'inspect-contexts', completed: 0, total: contextIds.length, unit: 'contexts' });
+    for (const [index, contextId] of contextIds.entries()) {
         try {
             const context = await readJson(contextMetadataPath(projectRoot, contextId));
             if (context.schemaVersion !== 1 || context.id !== contextId || context.projectRoot !== projectRoot) {
@@ -58,6 +59,7 @@ export async function migrationReadiness(startPath) {
         catch (error) {
             issues.push(`context ${contextId}: ${error instanceof Error ? error.message : 'invalid'}`);
         }
+        onProgress?.({ phase: 'inspect-contexts', completed: index + 1, total: contextIds.length, unit: 'contexts' });
     }
     try {
         counts.notes = (await listNotes(projectRoot, { limit: Number.MAX_SAFE_INTEGER, maxChars: Number.MAX_SAFE_INTEGER })).length;

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

@@ -0,0 +1,63 @@
+import type { ProgressReporter } from '../cognition/progress.js';
+export declare function upgradeProject(startPath?: string, options?: {
+    dryRun?: boolean;
+    onProgress?: ProgressReporter;
+}): Promise<{
+    runtime: import("../cognition/types.js").RuntimeStatus;
+    restartRuntime: boolean;
+    applied: boolean;
+    backup: {
+        directory: string;
+        files: number;
+        bytes: number;
+    };
+    journal: {
+        verified: boolean;
+        eventCount: number;
+        addedEvents: number;
+    };
+    storage: {
+        applied: boolean;
+        eligible: string[];
+        events: number;
+        headHash: string | null;
+        bytesBefore: number;
+        bytesAfter: number;
+        savedBytes: number;
+        archives: number;
+    };
+    projectRoot: string;
+    targetVersion: string;
+    counts: {
+        contexts: number;
+        snapshots: number;
+        notes: number;
+        knowledge: number;
+        deadends: number;
+    };
+    existingEvents: number;
+    migration: string;
+    backupBytes: number;
+    warning: string;
+} | {
+    applied: boolean;
+    projectRoot: string;
+    targetVersion: string;
+    counts: {
+        contexts: number;
+        snapshots: number;
+        notes: number;
+        knowledge: number;
+        deadends: number;
+    };
+    existingEvents: number;
+    migration: string;
+    backupBytes: number;
+    storage: {
+        bytes: number;
+        expandedBytes: number | null;
+        archives: number;
+        segments: number;
+    };
+    warning: string;
+}>;

package/dist/src/runtime/upgrade.js

@@ -0,0 +1,175 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { createReadStream, createWriteStream } from 'node:fs';
+import { lstat, mkdir, readFile, readdir } from 'node:fs/promises';
+import { Transform } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+import path from 'node:path';
+import { resolveProjectRoot } from '../project/project-resolver.js';
+import { atomicWriteJson } from '../storage/atomic-write.js';
+import { cognitionManifestPath, cognitionV1ImportPath, contextRoot, locksDirectory } from '../storage/layout.js';
+import { withLock } from '../storage/lock.js';
+import { loadManifest } from './init.js';
+import { migrationReadiness } from '../cognition/readiness.js';
+import { importV1, reconcileV1State, verifyV1Import } from '../cognition/migration-v1.js';
+import { compactJournal, readJournal } from '../cognition/journal.js';
+import { journalStorage } from '../cognition/journal-segments.js';
+import { loadRuntimePolicy } from '../cognition/policy.js';
+import { runtimeStatus, startRuntime, stopRuntime } from '../cognition/runtime.js';
+import { rebuildProjections } from '../cognition/projections.js';
+import { v1Synced } from '../cognition/v1-bridge.js';
+import { COGNITION_LAYOUT_VERSION } from '../cognition/types.js';
+import { VERSION } from '../version.js';
+const excluded = new Set(['backups', 'builds', 'locks', 'cognition/runtime/lease.json', 'cognition/runtime/secret', 'cognition/runtime/startup.json']);
+async function exists(file) {
+    try {
+        await lstat(file);
+        return true;
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return false;
+        throw error;
+    }
+}
+async function inventory(root) {
+    const files = [];
+    async function visit(relative) {
+        if (excluded.has(relative))
+            return;
+        const file = path.join(root, relative);
+        const stat = await lstat(file);
+        if (stat.isSymbolicLink())
+            throw new Error(`upgrade refuses symlink: ${relative || '.context'}`);
+        if (stat.isDirectory()) {
+            for (const name of (await readdir(file)).sort())
+                await visit(relative ? `${relative}/${name}` : name);
+        }
+        else if (stat.isFile())
+            files.push({ relative, bytes: stat.size });
+        else
+            throw new Error(`upgrade refuses unsupported file: ${relative}`);
+    }
+    await visit('');
+    return files;
+}
+async function hashFile(file) {
+    const hash = createHash('sha256');
+    for await (const chunk of createReadStream(file))
+        hash.update(chunk);
+    return hash.digest('hex');
+}
+async function backup(root, destination, progress) {
+    const files = await inventory(root);
+    const total = files.reduce((sum, file) => sum + file.bytes, 0);
+    const manifest = [];
+    let completed = 0;
+    progress?.({ phase: 'backup', completed, total, unit: 'bytes' });
+    for (const file of files) {
+        const source = path.join(root, file.relative);
+        const target = path.join(destination, 'data', file.relative);
+        await mkdir(path.dirname(target), { recursive: true });
+        const hash = createHash('sha256');
+        let bytes = 0;
+        await pipeline(createReadStream(source), new Transform({ transform(chunk, _encoding, callback) {
+                hash.update(chunk);
+                bytes += chunk.length;
+                completed += chunk.length;
+                progress?.({ phase: 'backup', completed, total, unit: 'bytes' });
+                callback(null, chunk);
+            } }), createWriteStream(target, { flags: 'wx' }));
+        const sha256 = hash.digest('hex');
+        if (bytes !== file.bytes || await hashFile(target) !== sha256 || await hashFile(source) !== sha256)
+            throw new Error(`backup changed during copy: ${file.relative}`);
+        manifest.push({ ...file, sha256 });
+    }
+    if (JSON.stringify(await inventory(root)) !== JSON.stringify(files))
+        throw new Error('project data changed during backup; close other agents and retry');
+    await atomicWriteJson(path.join(destination, 'backup.json'), { version: VERSION, completedAt: new Date().toISOString(), excluded: [...excluded], files: manifest });
+    return { directory: destination, files: files.length, bytes: total };
+}
+async function locked(root, names, action) {
+    if (!names.length)
+        return action();
+    return withLock(path.join(locksDirectory(root), `${names[0]}.lock`), () => locked(root, names.slice(1), action));
+}
+export async function upgradeProject(startPath, options = {}) {
+    const root = await resolveProjectRoot(startPath);
+    const progress = options.onProgress;
+    progress?.({ phase: 'inspect', completed: 0, total: null });
+    // Read-only preflight; never initialize a missing or invalid legacy store.
+    const files = await inventory(contextRoot(root));
+    const manifest = await loadManifest(root);
+    const readiness = await migrationReadiness(root, progress);
+    if (!readiness.eligible)
+        throw new Error(`upgrade preflight failed: ${readiness.issues.join('; ')}`);
+    if (readiness.v2Present) {
+        const cognition = JSON.parse(await readFile(cognitionManifestPath(root), 'utf8'));
+        if (cognition.schemaVersion !== 2 || cognition.layoutVersion !== COGNITION_LAYOUT_VERSION || cognition.projectId !== manifest.projectId)
+            throw new Error('unsupported cognition manifest; upgrade refused');
+        await loadRuntimePolicy(root);
+    }
+    const initial = await readJournal(root, { allowPartialTail: false, onProgress: progress });
+    const storage = await journalStorage(root);
+    const receiptPresent = await exists(cognitionV1ImportPath(root));
+    if (receiptPresent) {
+        const receipt = JSON.parse(await readFile(cognitionV1ImportPath(root), 'utf8'));
+        if (!readiness.v2Present || receipt.schemaVersion !== 2 || typeof receipt.sourceHash !== 'string' || !Array.isArray(receipt.eventIds))
+            throw new Error('invalid migration receipt; upgrade refused');
+    }
+    const plan = { projectRoot: root, targetVersion: VERSION, counts: readiness.counts, existingEvents: initial.length,
+        migration: receiptPresent ? 'reconcile' : readiness.v2Present ? 'resume-import' : 'import',
+        backupBytes: files.reduce((sum, file) => sum + file.bytes, 0), storage,
+        warning: 'Close all agent/MCP sessions before applying. Archived journals cannot be opened with 0.8.0.' };
+    if (options.dryRun) {
+        progress?.({ phase: 'preview-complete', completed: 1, total: 1 });
+        return { ...plan, applied: false };
+    }
+    return locked(root, ['upgrade', 'cognition-runtime-start'], async () => {
+        const wasRunning = (await runtimeStatus(root)).running;
+        progress?.({ phase: 'stop-runtime', completed: 0, total: null });
+        if (wasRunning)
+            await stopRuntime(root);
+        let savedBackup = null;
+        let result;
+        try {
+            result = await locked(root, ['setup', 'checkpoint', 'knowledge', 'deadends', 'notes'], async () => {
+                const backups = path.join(contextRoot(root), 'backups');
+                if (await exists(backups) && (await lstat(backups)).isSymbolicLink())
+                    throw new Error('upgrade refuses symlinked backup directory');
+                const destination = path.join(backups, `upgrade-${Date.now()}-${randomUUID()}`);
+                savedBackup = await locked(root, ['cognition-migration', 'cognition-journal'], () => backup(contextRoot(root), destination, progress));
+                const before = await readJournal(root, { allowPartialTail: false, onProgress: progress });
+                progress?.({ phase: 'migrate', completed: 0, total: null });
+                if (!receiptPresent) {
+                    const migration = await importV1(root, progress);
+                    if (!migration.applied)
+                        throw new Error(migration.issues.join('; '));
+                    const verification = await verifyV1Import(root);
+                    if (!verification.verified)
+                        throw new Error(verification.issues.join('; '));
+                }
+                else if (!await v1Synced(root))
+                    await reconcileV1State(root);
+                const compacted = await compactJournal(root, { apply: true, onProgress: progress });
+                progress?.({ phase: 'rebuild-projections', completed: 0, total: null });
+                await rebuildProjections(root);
+                const after = await readJournal(root, { allowPartialTail: false, onProgress: progress });
+                if (after.length < before.length || before.some((event, index) => after[index].hash !== event.hash))
+                    throw new Error('upgrade changed historical journal events');
+                const complete = { ...plan, applied: true, backup: savedBackup, journal: { verified: true, eventCount: after.length, addedEvents: after.length - before.length }, storage: compacted };
+                await atomicWriteJson(path.join(destination, 'upgrade.json'), { ...complete, completedAt: new Date().toISOString() });
+                return complete;
+            });
+        }
+        catch (error) {
+            throw new Error(`upgrade failed; runtime remains stopped. ${savedBackup ? `Backup: ${savedBackup.directory}. ` : 'No completed backup. '} ${error instanceof Error ? error.message : String(error)}`);
+        }
+        // The startup lock must be released before launching a new runtime.
+        return { ...result, restartRuntime: wasRunning };
+    }).then(async (result) => {
+        progress?.({ phase: 'restore-runtime', completed: 0, total: null });
+        const runtime = result.restartRuntime ? await startRuntime(root) : await runtimeStatus(root);
+        progress?.({ phase: 'complete', completed: 1, total: 1 });
+        return { ...result, runtime };
+    });
+}

package/dist/src/version.d.ts

@@ -1 +1 @@
-export declare const VERSION = "1.0.0-beta.1";
+export declare const VERSION = "1.0.0-beta.2";

package/dist/src/version.js

@@ -1 +1 @@
-export const VERSION = '1.0.0-beta.1';
+export const VERSION = '1.0.0-beta.2';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fluffy-context",
-  "version": "1.0.0-beta.1",
+  "version": "1.0.0-beta.2",
   "description": "Local context management CLI and MCP tools for AI coding agents",
   "license": "MIT",
   "author": "FluffyChi-Xing",

package/skills/fluffy-context/SKILL.md

@@ -10,7 +10,9 @@ compatibility: 需要 Node.js >=20.19.0；Git 可选。CLI 通过 npm 全局安
 
 ## 使用原则
 
-- 当前 beta 为 1.0.0-beta.1。每批通过测试后执行 `npm run install:local` 从 tarball 更新全局 ctx，查看 `.context/builds/install-*.json` 哈希核验回执。不要以源码链接安装代替这一验收。
+- `1.0.0-beta.2` 新增 `ctx upgrade`，用于已有项目数据升级。先关闭其它 agent/MCP 写入会话；用 `--dry-run` 只读检查，再执行 `ctx upgrade` 自动备份、迁移、压缩和验证。阶段进度在 stderr，stdout 为 JSON，可用 `--no-progress` 关闭进度。备份在 `.context/backups/upgrade-*`；重复执行不重复导入，但会新增备份。已发布 beta.1 不包含此命令。
+
+- 当前 beta 为 1.0.0-beta.2。每批通过测试后执行 `npm run install:local` 从 tarball 更新全局 ctx，查看 `.context/builds/install-*.json` 哈希核验回执。不要以源码链接安装代替这一验收。
 - knowledge discover 的诊断只覆盖符合当前状态、scope 和 query 的记录，最多 10 组；不要将 possibleConflicts 当成已确认矛盾。默认查询不能通过诊断字段泄漏候选内容。
 - `ctx journal compact` 默认预览；`--apply` 保留完整事件和哈希链进行 gzip 归档。约 1 MiB 的段也会在追加或 init 时自动维护。归档项目不能再用 0.8.0 读取或写入，常驻 MCP 连接升级后需要重启。
 - `retentionMaxBytes` 限制可选观察事件，不限制重要语义写入；在 report 查看 admission.dropped。默认 inject 只返回精简证据包，需要候选来源详情时使用 `--explain`。