@geminilight/mindos 0.5.9 → 0.5.11

package/bin/lib/sync.js

@@ -1,6 +1,7 @@
 import { execSync } from 'node:child_process';
 import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
 import { resolve } from 'node:path';
+import { homedir } from 'node:os';
 import { CONFIG_PATH, MINDOS_DIR } from './constants.js';
 import { bold, dim, cyan, green, red, yellow } from './colors.js';
 
@@ -129,12 +130,24 @@ function autoPull(mindRoot) {
       }
     }
   }
+
+  // Retry any pending pushes (handles previous push failures)
+  try {
+    const unpushed = gitExec('git rev-list --count @{u}..HEAD', mindRoot);
+    if (parseInt(unpushed) > 0) {
+      execSync('git push', { cwd: mindRoot, stdio: 'pipe' });
+      saveSyncState({ ...loadSyncState(), lastSync: new Date().toISOString(), lastError: null });
+    }
+  } catch {
+    // No upstream tracking or push failed — ignore silently, autoCommitAndPush handles primary pushes
+  }
 }
 
 // ── Exported API ────────────────────────────────────────────────────────────
 
 let activeWatcher = null;
 let activePullInterval = null;
+let activeShutdownHandler = null;
 
 /**
  * Interactive sync init — configure remote git repo
@@ -187,18 +200,43 @@ export async function initSync(mindRoot, opts = {}) {
     try { execSync('git checkout -b main', { cwd: mindRoot, stdio: 'pipe' }); } catch {}
   }
 
+  // 1b. Ensure .gitignore exists
+  const gitignorePath = resolve(mindRoot, '.gitignore');
+  if (!existsSync(gitignorePath)) {
+    writeFileSync(gitignorePath, [
+      '# MindOS auto-generated',
+      '.DS_Store',
+      'Thumbs.db',
+      '*.tmp',
+      '*.bak',
+      '*.swp',
+      '*.sync-conflict',
+      'node_modules/',
+      '.obsidian/',
+      '',
+    ].join('\n'), 'utf-8');
+  }
+
   // Handle token for HTTPS
   if (token && remoteUrl.startsWith('https://')) {
     const urlObj = new URL(remoteUrl);
-    urlObj.username = 'oauth2';
-    urlObj.password = token;
-    // Configure credential helper
-    try { execSync(`git config credential.helper store`, { cwd: mindRoot, stdio: 'pipe' }); } catch {}
-    // Store the credential
+    // Choose credential helper by platform
+    const platform = process.platform;
+    let helper;
+    if (platform === 'darwin') helper = 'osxkeychain';
+    else if (platform === 'win32') helper = 'manager';
+    else helper = 'store';
+    try { execSync(`git config credential.helper '${helper}'`, { cwd: mindRoot, stdio: 'pipe' }); } catch {}
+    // Store the credential via git credential approve
     try {
       const credInput = `protocol=${urlObj.protocol.replace(':', '')}\nhost=${urlObj.host}\nusername=oauth2\npassword=${token}\n\n`;
       execSync('git credential approve', { cwd: mindRoot, input: credInput, stdio: 'pipe' });
     } catch {}
+    // For 'store' helper, restrict file permissions AFTER credential file is created
+    if (helper === 'store') {
+      const credFile = resolve(process.env.HOME || homedir(), '.git-credentials');
+      try { execSync(`chmod 600 "${credFile}"`, { stdio: 'pipe' }); } catch {}
+    }
   }
 
   // 4. Set remote
@@ -257,6 +295,7 @@ export async function initSync(mindRoot, opts = {}) {
  * Start file watcher + periodic pull
  */
 export async function startSyncDaemon(mindRoot) {
+  if (activeWatcher) return null; // already running — idempotent guard
   const config = loadSyncConfig();
   if (!config.enabled) return null;
   if (!mindRoot || !isGitRepo(mindRoot)) return null;
@@ -281,10 +320,20 @@ export async function startSyncDaemon(mindRoot) {
   // Pull on startup
   autoPull(mindRoot);
 
+  // Graceful shutdown: flush pending changes before exit
+  const gracefulShutdown = () => {
+    if (commitTimer) { clearTimeout(commitTimer); commitTimer = null; }
+    try { autoCommitAndPush(mindRoot); } catch {}
+    stopSyncDaemon();
+  };
+  process.on('SIGTERM', gracefulShutdown);
+  process.on('SIGINT', gracefulShutdown);
+
   activeWatcher = watcher;
   activePullInterval = pullInterval;
+  activeShutdownHandler = gracefulShutdown;
 
-  return { watcher, pullInterval };
+  return { watcher, pullInterval, gracefulShutdown };
 }
 
 /**
@@ -299,6 +348,11 @@ export function stopSyncDaemon() {
     clearInterval(activePullInterval);
     activePullInterval = null;
   }
+  if (activeShutdownHandler) {
+    process.removeListener('SIGTERM', activeShutdownHandler);
+    process.removeListener('SIGINT', activeShutdownHandler);
+    activeShutdownHandler = null;
+  }
 }
 
 /**
@@ -336,14 +390,10 @@ export function getSyncStatus(mindRoot) {
  */
 export function manualSync(mindRoot) {
   if (!mindRoot || !isGitRepo(mindRoot)) {
-    console.error(red('Not a git repository. Run `mindos sync init` first.'));
-    process.exit(1);
+    throw new Error('Not a git repository. Run `mindos sync init` first.');
   }
-  console.log(dim('Pulling...'));
   autoPull(mindRoot);
-  console.log(dim('Committing & pushing...'));
   autoCommitAndPush(mindRoot);
-  console.log(green('✔ Sync complete'));
 }
 
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geminilight/mindos",
-  "version": "0.5.9",
+  "version": "0.5.11",
   "description": "MindOS — Human-Agent Collaborative Mind System. Local-first knowledge base that syncs your mind to all AI Agents via MCP.",
   "keywords": [
     "mindos",
@@ -54,8 +54,10 @@
     "!assets/capture-demo.mjs",
     "!assets/demo-flow.html",
     "!assets/demo-flow-zh.html",
+    "!assets/images",
     "!mcp/node_modules",
-    "!mcp/dist"
+    "!mcp/dist",
+    "!mcp/package-lock.json"
   ],
   "scripts": {
     "setup": "node scripts/setup.js",

package/skills/project-wiki/SKILL.md

@@ -34,15 +34,72 @@ description: "组织和维护 Vibe Coding 项目的 wiki 文档体系。当用
 
 ## 文件体系
 
+### 编号体系：十位 = 层级，个位 = 序号
+
+编号按**"战略 → 架构 → 规范 → 阶段 → 运维 → 日志"**分层，均匀分布，奇数十位留空备用。
+
+```
+wiki/
+├── 0x  战略 Strategy       — 全局视角，不看代码也能读懂
+│   ├── 00-product-proposal.md
+│   ├── 01-project-roadmap.md
+│   ├── 02-business-model.md          # 有商业化需求时
+│   └── 03-technical-pillars.md       # 有技术壁垒/研究方向时
+│
+├── 2x  架构 Architecture   — 系统是怎么建的（描述事实）
+│   ├── 20-system-architecture.md
+│   └── 21-design-principle.md        # 有自定义视觉语言时
+│
+├── 3x  （空，留给接口/API 文档）
+│
+├── 4x  规范 Conventions    — 怎么参与开发（约束行为）
+│   ├── 40-conventions.md
+│   └── 41-dev-pitfall-patterns.md    # 踩坑经验
+│
+├── 5x  （空）
+│
+├── 6x  阶段 Stages         — 各阶段详细 spec（按需查阅）
+│   ├── 60-stage-a.md
+│   ├── 61-stage-b.md
+│   └── ...
+│
+├── 7x  （空）
+│
+├── 8x  运维 Operations     — 坑、复盘、backlog
+│   ├── 80-known-pitfalls.md
+│   ├── 81-postmortem-*.md
+│   ├── 84-design-exploration.md      # 有 UI 探索时
+│   └── 85-backlog.md
+│
+├── 9x  日志 Log
+│   └── 90-changelog.md
+│
+├── specs/                   — 任务 spec（活跃的，完成后归档）
+│   └── task-spec-xxx.md
+├── refs/                    — 参考资料（外部机制说明、技术调研）
+└── archive/                 — 已完结的 spec 和历史文档
+```
+
+| 区段 | 用途 | 扩展性 |
+|------|------|--------|
+| `0x` | 战略：产品方向、路线图、商业、壁垒 | 最多 10 个全局文档 |
+| `2x` | 架构：系统设计 + 设计系统 | 可加 22-data-model 等 |
+| `3x` | 留空 | 未来放 API reference、协议文档 |
+| `4x` | 规范：开发流程 + 踩坑经验 | 可加 42-testing-standards 等 |
+| `5x` | 留空 | 未来按需定义 |
+| `6x` | 阶段：各功能的详细 spec | 最多 10 个阶段 |
+| `7x` | 留空 | 未来按需定义 |
+| `8x` | 运维：已知坑、复盘、backlog | 可加 82-xxx、83-xxx |
+| `9x` | 日志 | changelog、release notes |
+
 ### 核心模型：Why / What / How / Look × 全局 / 阶段
 
 | | 全局（稳定，新阶段才改） | 阶段（增量更新） |
 |---|---|---|
 | **Why** | `00-product-proposal.md` | — |
-| **What** | `01-project-roadmap.md` — 功能索引 | `1X-stage-X.md` — 设计决策 |
-| **How** | `02-system-architecture.md` — 架构 + 类型 | `1X-stage-X.md` — API、数据模型、受影响文件 |
-| **API** | `04-api-reference.md` — 完整 API 参考 | `1X-stage-X.md` — 新增 API 的设计决策 |
-| **Look** | `03-design-principle.md` — 视觉语言 | — |
+| **What** | `01-project-roadmap.md` — 功能索引 | `6X-stage-X.md` — 设计决策 |
+| **How** | `20-system-architecture.md` — 架构 + 类型 | `6X-stage-X.md` — API、数据模型、受影响文件 |
+| **Look** | `21-design-principle.md` — 视觉语言 | — |
 
 **关键规则：** stage 文件同时包含 What 和 How。一个功能的设计决策、API 契约、数据模型放在一个文件里。全局文件只做索引和导航，不重复 stage 的细节。
 
@@ -62,58 +119,29 @@ description: "组织和维护 Vibe Coding 项目的 wiki 文档体系。当用
 |------|------|--------|---------|
 | 00 | `product-proposal.md` | Agent + 你 | 产品愿景、产品定位、**不做什么**、目标用户、功能矩阵、路线图叙事 |
 | 01 | `project-roadmap.md` | Agent + 你 | 阶段总览表、全量功能索引（功能×状态×stage链接）、里程碑 |
-| 02 | `system-architecture.md` | Agent | 技术栈、目录结构、数据流、核心类型、环境变量（300-500 行） |
+| 20 | `system-architecture.md` | Agent | 技术栈、目录结构、数据流、核心类型、环境变量（300-500 行） |
 
 ### 按需文件（第二梯队）
 
 | 编号 | 文件 | 何时需要 |
 |------|------|---------|
-| 03 | `design-principle.md` | 有自定义视觉语言时（非默认 UI 库样式） |
-| 04 | `api-reference.md` | API 超过 5 条路由，或 stage 归档后仍需查 API 细节 |
-| 05 | `glossary.md` | 项目有领域术语，Agent 容易用错词或混用近义词 |
-| 06 | `conventions.md` | 有明确的编码偏好/约束（库选择、命名、错误处理模式等） |
-| 1X | `stage-X.md` | 功能复杂度超过一句话能说清（150-300 行） |
-| — | `task-spec-xxx.md` | 小功能 / 改进点的 spec，包含需求描述和验收标准；实现完成后归档或合并进对应 stage 文件 |
+| 02 | `business-model.md` | 有商业化/变现需求时 |
+| 03 | `technical-pillars.md` | 有明确的技术壁垒或研究方向时 |
+| 21 | `design-principle.md` | 有自定义视觉语言时（非默认 UI 库样式） |
+| 30 | `api-reference.md` | API 超过 5 条路由，或 stage 归档后仍需查 API 细节 |
+| 40 | `conventions.md` | 有明确的编码偏好/约束（库选择、命名、错误处理模式等） |
+| 41 | `dev-pitfall-patterns.md` | 踩坑积累到需要系统性记录时 |
+| 6X | `stage-X.md` | 功能复杂度超过一句话能说清（150-300 行） |
+| — | `specs/task-spec-xxx.md` | 小功能 / 改进点的 spec；实现完成后归档到 `archive/` |
+| — | `refs/xxx.md` | 外部机制说明、技术调研、协议文档 |
 | 80 | `known-pitfalls.md` | 踩坑即记，不等阶段结束 |
-| 81 | `development-guide.md` | 有非显而易见的配置要求时 |
-| 82 | `postmortem-*.md` | 多个 bug 互相关联、暴露系统性问题时（单点问题用 pitfalls，系统性问题用 postmortem） |
+| 81 | `postmortem-*.md` | 多个 bug 互相关联、暴露系统性问题时（单点问题用 pitfalls，系统性问题用 postmortem） |
 | 84 | `design-exploration.md` | 有 UI 设计探索、原型记录等创意过程产物时 |
 | 85 | `backlog.md` | 有临时 bug、技术债、改进想法需要追踪时 |
-| 8X | `external-*.md` | 依赖外部系统私有数据格式时 |
 | 90 | `changelog.md` | 发版时从 `85-backlog.md` 已完成条目整理写入，面向用户描述变更，不记内部实现细节 |
 
 > 每个文件的详细说明和"为什么需要"的论证见 `references/file-reference.md`。
 
-### 目录结构与编号规范
-
-```
-wiki/
-├── 00-product-proposal.md        # Why
-├── 01-project-roadmap.md         # What（全局索引）
-├── 02-system-architecture.md     # How（全局）
-├── 03-design-principle.md        # Look（全局）
-├── 04-api-reference.md           # API（全局）
-├── 05-glossary.md                # 术语表（有领域术语时）
-├── 06-conventions.md             # 编码约定（有明确偏好时）
-├── 10-stage-a.md                 # 阶段文件
-├── 11-stage-b.md
-├── ...
-├── 80-known-pitfalls.md          # 辅助参考
-├── 81-development-guide.md
-├── 82-postmortem-*.md            # 系统性问题复盘（多 bug 关联时）
-├── 84-design-exploration.md      # 设计探索/原型记录（有 UI 探索时）
-├── 85-backlog.md                 # Bug、技术债、改进想法
-├── 90-changelog.md               # 日志
-└── archive/                      # 已完结阶段归档
-```
-
-| 区段 | 用途 |
-|------|------|
-| `00-09` | 全局文件，按阅读优先级排列 |
-| `10-79` | 阶段文件，按时间递增 |
-| `80-89` | 辅助参考文件 |
-| `90-99` | 日志类文件 |
-
 ### Stage 文件生命周期
 
 阶段完全交付且后续阶段不再引用其 API/数据模型时 → 移入 `wiki/archive/`，`01-project-roadmap.md` 中保留索引行并标注 `[archived]`。
@@ -126,11 +154,11 @@ wiki/
 
 | 场景 | 路径 |
 |------|------|
-| 新对话 / 新功能 | `00-product-proposal` → `02-system-architecture` → 当前 `stage-X` |
-| 修 Bug | `02-system-architecture` → `80-known-pitfalls` → 相关 `stage-X` |
-| 修 Bug（反复出现） | `82-postmortem-*` → `02-system-architecture` → `80-known-pitfalls` → 相关 `stage-X` |
-| UI 调整 | `03-design-principle` → `02-system-architecture`（目录结构）→ 相关组件 |
-| 了解全貌 | `00-product-proposal` → `01-project-roadmap` → `02-system-architecture` |
+| 新对话 / 新功能 | `00-product-proposal` → `20-system-architecture` → 当前 `6X-stage-X` |
+| 修 Bug | `20-system-architecture` → `80-known-pitfalls` → 相关 `6X-stage-X` |
+| 修 Bug（反复出现） | `81-postmortem-*` → `20-system-architecture` → `80-known-pitfalls` → 相关 `6X-stage-X` |
+| UI 调整 | `21-design-principle` → `20-system-architecture`（目录结构）→ 相关组件 |
+| 了解全貌 | `00-product-proposal` → `01-project-roadmap` → `20-system-architecture` |
 
 ---
 
@@ -177,20 +205,21 @@ Skill 触发时生成 wiki 结构，但 wiki 的日常同步发生在每次开
 
 | 当你做了这件事 | 更新哪个文件 |
 |--------------|------------|
-| 新增/修改 API 路由 | `wiki/04-api-reference.md` 追加或修改对应条目 |
+| 新增/修改 API 路由 | `wiki/30-api-reference.md` 追加或修改对应条目 |
 | 完成一个 stage 的功能 | `wiki/01-project-roadmap.md` 对应行状态改为 ✅ |
 | 遇到非显而易见的坑 | `wiki/80-known-pitfalls.md` 追加一条（现象、原因、解法） |
-| 多个 bug 互相关联、暴露系统性问题 | 新建 `wiki/82-postmortem-*.md`（单点问题用 pitfalls，系统性问题用 postmortem） |
-| 架构变更（新模块、新数据流） | `wiki/02-system-architecture.md` 更新对应章节 |
+| 多个 bug 互相关联、暴露系统性问题 | 新建 `wiki/81-postmortem-*.md`（单点问题用 pitfalls，系统性问题用 postmortem） |
+| 架构变更（新模块、新数据流） | `wiki/20-system-architecture.md` 更新对应章节 |
 | 阶段全部交付 | `wiki/90-changelog.md` 补一笔（从 backlog 已完成条目整理） |
 | 发现 bug / 技术债 / 改进想法 | `wiki/85-backlog.md` 追加一条 |
-| 新增设计 token / 动效 | `wiki/03-design-principle.md` 追加对应条目 |
+| 新增设计 token / 动效 | `wiki/21-design-principle.md` 追加对应条目 |
 | 出现新领域术语 | `wiki/05-glossary.md` 追加定义，防止 Agent 后续用词混乱 |
 | 重命名 / 移动 wiki 文件 | 同步更新所有引用该文件的链接 |
 
 **新建文件时机：**
-- 新功能复杂度超过一句话说清 → 新建 `wiki/1X-stage-X.md`
-- 小功能 / 改进点需要 spec → 新建 `wiki/task-spec-xxx.md`（实现完成后归档或合并进 stage 文件）
+- 新功能复杂度超过一句话说清 → 新建 `wiki/6X-stage-X.md`
+- 小功能 / 改进点需要 spec → 新建 `wiki/specs/task-spec-xxx.md`（实现完成后归档到 `archive/`）
+- 外部机制调研 → 新建 `wiki/refs/xxx.md`
 
 **定期检查（每个阶段开始时）：**
 - 扫描 wiki/ 下所有文件，更新 `Last verified` 日期
@@ -209,15 +238,15 @@ Skill 触发时生成 wiki 结构，但 wiki 的日常同步发生在每次开
 |---------|---------------|
 | `product-proposal.tmpl.md` | `00-product-proposal.md` |
 | `project-roadmap.tmpl.md` | `01-project-roadmap.md` |
-| `system-architecture.tmpl.md` | `02-system-architecture.md` |
-| `design-principle.tmpl.md` | `03-design-principle.md` |
-| `api-reference.tmpl.md` | `04-api-reference.md` |
-| `glossary.tmpl.md` | `05-glossary.md` |
-| `conventions.tmpl.md` | `06-conventions.md` |
-| `stage-x.tmpl.md` | `1X-stage-X.md` |
+| `business-model.tmpl.md` | `02-business-model.md` |
+| `technical-pillars.tmpl.md` | `03-technical-pillars.md` |
+| `system-architecture.tmpl.md` | `20-system-architecture.md` |
+| `design-principle.tmpl.md` | `21-design-principle.md` |
+| `api-reference.tmpl.md` | `30-api-reference.md` |
+| `conventions.tmpl.md` | `40-conventions.md` |
+| `stage-x.tmpl.md` | `6X-stage-X.md` |
 | `known-pitfalls.tmpl.md` | `80-known-pitfalls.md` |
-| `development-guide.tmpl.md` | `81-development-guide.md` |
-| `postmortem.tmpl.md` | `82-postmortem-*.md` |
+| `postmortem.tmpl.md` | `81-postmortem-*.md` |
 | `design-exploration.tmpl.md` | `84-design-exploration.md` |
 | `backlog.tmpl.md` | `85-backlog.md` |
 | `changelog.tmpl.md` | `90-changelog.md` |