@xiaofandegeng/rmemo 0.0.3

package/CHANGELOG.md

@@ -0,0 +1,8 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## Unreleased
+
+- TBD
+

package/CONTRIBUTING.md

@@ -0,0 +1,28 @@
+# Contributing
+
+Thanks for contributing to `rmemo`.
+
+## Dev Setup
+
+Requirements:
+- Node.js >= 18
+
+Run tests:
+
+```bash
+npm test
+```
+
+## What To Work On
+
+Good first contributions:
+- Improve scan heuristics (monorepo/subprojects/api contracts) without hardcoding to one framework
+- Improve `check` output formatting and fix hints
+- Add more safe default rules/templates for common project types
+
+## Pull Requests
+
+- Keep changes focused and small.
+- Add/adjust tests in `test/` when behavior changes.
+- If you change CLI flags/commands, update both `README.md` and `README.zh-CN.md`.
+

package/DEVELOPMENT_PLAN.md

@@ -0,0 +1,77 @@
+# Development Plan
+
+This plan is optimized for "daily use" and long-term maintainability. Each milestone should keep the tool usable.
+
+## v0.1 (Shipped)
+
+Done:
+- CLI: `init`, `scan`, `log`, `context`, `print`
+- Repo scan (git-aware) -> `.repo-memory/manifest.json` + `.repo-memory/index.json`
+- Context Pack generator -> `.repo-memory/context.md`
+
+## v0.2 (Make Memory More Useful) (Shipped)
+
+Goals:
+- Produce a better "project memory" without tying to any specific repo type.
+- Reduce manual work to keep rules/todos/journal consistent.
+
+Done:
+- Add `rmemo status` (+ `--format md|json` + `--mode brief|full`):
+  - Summarize "Next / Blockers / Recent log" from `.repo-memory/*`
+  - Output should be pasteable to issues/PR descriptions
+- Improve scan heuristics:
+  - Detect monorepo candidates (workspaces, pnpm, turborepo, packages/apps)
+  - Detect common app folders (web/admin/backend/miniapp/mp) as hints only
+  - Detect API contract files and doc roots (openapi/swagger/docs)
+- Add `rmemo start` as a daily entrypoint (scan + context + status brief)
+- Add todo helpers: `rmemo todo add|block|ls`
+
+## v0.3 (Rules Become Enforceable) (Shipped)
+
+Goals:
+- Prevent "AI drift" by making key conventions executable.
+
+Done:
+- Add `.repo-memory/rules.json` (generated by `init`):
+  - Structure rules: required dirs/files, forbidden paths, naming regexes
+- Add `rmemo check`:
+  - Validate repo against rules.json (no network)
+  - Exit code for CI usage
+  - Print actionable diff-like messages
+- Add forbidden content scanning: `forbiddenContent`
+- Add `--staged` mode (pre-commit optimized, reads staged content from git index)
+- Add `rmemo hook install`:
+  - Install a pre-commit hook to run `rmemo check` (opt-in)
+
+## v0.4 (Workflow: Start/Stop The Day) (Shipped)
+
+Goals:
+- Make the daily routine effortless.
+
+Done:
+- Add `rmemo done`:
+  - Promptless mode: take stdin to append to journal
+  - Optionally extract "next steps" into todos.md
+- Unify journal format for `log/done`
+- Add todo lifecycle: `rmemo todo done|unblock` (remove by index)
+
+## v0.5 (Polish + Adoption) (In Progress)
+
+Goals:
+- Make it easy for others to adopt.
+
+Tasks:
+- Add packaging metadata:
+  - repository/homepage/bugs fields
+  - `files` allowlist for npm
+  - `npm pack --dry-run` in CI
+- Prepare npm publishing (name might be taken; decide final package name)
+- Add docs:
+  - "How I use this with Cursor/Claude/ChatGPT"
+  - Examples of rules.md templates for web + miniapp projects
+- Add `CHANGELOG.md` + `CONTRIBUTING.md`
+
+## v0.6 (Optional)
+
+- `rmemo scan --format md|json` to print scan results to stdout
+- `rmemo check` output improvements (grouping + fix hints)

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/README.md

@@ -0,0 +1,150 @@
+# rmemo
+
+Repo memory + dev journal CLI: scan any project, persist conventions/progress, and generate an AI-ready context pack.
+
+[English](./README.md) | [简体中文](./README.zh-CN.md)
+
+Docs:
+- [Usage (AI Workflow)](./docs/USAGE.md)
+- [Releasing](./RELEASING.md)
+
+## Why
+
+When you resume work the next day, AI tools often:
+- forget project-specific rules and structure
+- re-invent decisions you already made
+- drift away from established conventions
+
+`rmemo` fixes this by storing the "repo memory" inside the repo and generating a single `Context Pack` you can paste into any AI.
+
+## Install
+
+For now, run it directly with Node:
+
+```bash
+node bin/rmemo.js init
+node bin/rmemo.js log "Finished user list page; next: add search filters"
+node bin/rmemo.js context
+node bin/rmemo.js print
+```
+
+Later you can publish to npm and install globally.
+
+## Use On Any Repo
+
+From the target repo root:
+
+```bash
+node /path/to/rmemo/bin/rmemo.js init
+node /path/to/rmemo/bin/rmemo.js log "Did X; next: Y"
+node /path/to/rmemo/bin/rmemo.js context
+node /path/to/rmemo/bin/rmemo.js print
+```
+
+Or without changing directories:
+
+```bash
+node /path/to/rmemo/bin/rmemo.js --root /path/to/your-repo init
+```
+
+## Files It Creates
+
+- `.repo-memory/manifest.json`: detected structure, tech stack hints, key files
+- `.repo-memory/index.json`: file list for context generation
+- `.repo-memory/rules.md`: your conventions and constraints (human-written)
+- `.repo-memory/todos.md`: next steps and blockers (human-written)
+- `.repo-memory/journal/YYYY-MM-DD.md`: daily progress log (human-written)
+- `.repo-memory/context.md`: generated AI-ready context pack (generated)
+
+## Commands
+
+```bash
+rmemo init
+rmemo scan
+rmemo log <text>
+rmemo context
+rmemo print
+rmemo status
+rmemo check
+rmemo hook install
+rmemo start
+rmemo done
+```
+
+## Enforcing Rules (CI / Hooks)
+
+`rmemo` supports executable repo rules in `.repo-memory/rules.json`.
+
+Example:
+
+```json
+{
+  "schema": 1,
+  "requiredPaths": ["README.md"],
+  "forbiddenPaths": [".env", ".env.*"],
+  "forbiddenContent": [
+    {
+      "include": ["**/*"],
+      "exclude": ["**/*.png", "**/*.jpg", "**/*.zip"],
+      "match": "BEGIN PRIVATE KEY",
+      "message": "Do not commit private keys."
+    }
+  ],
+  "namingRules": [
+    {
+      "include": ["src/pages/**"],
+      "target": "basename",
+      "match": "^[a-z0-9-]+\\.vue$",
+      "message": "Page filenames must be kebab-case."
+    }
+  ]
+}
+```
+
+Run:
+
+```bash
+rmemo check
+```
+
+Pre-commit usage (faster, checks only staged files):
+
+```bash
+rmemo check --staged
+```
+
+Install a pre-commit hook (runs `rmemo check` before commit):
+
+```bash
+rmemo hook install
+```
+
+Start-of-day entrypoint (scan + generate context + print status):
+
+```bash
+rmemo start
+```
+
+End-of-day note (append to journal; supports stdin):
+
+```bash
+rmemo done "Finished X; decided Y"
+echo "Finished X; decided Y" | rmemo done
+rmemo done --next "Tomorrow: implement Z" --blocker "Waiting for API spec" "Summary: ..."
+```
+
+Todo helpers:
+
+```bash
+rmemo todo add "Implement user search"
+rmemo todo block "Backend API missing"
+rmemo todo ls
+rmemo todo done 1
+rmemo todo unblock 1
+```
+
+## Roadmap (short)
+
+- v0.2: better heuristics for monorepos, miniapp projects, and API contracts
+- v0.3: `rmemo check` to enforce structure/rules (CI + git hook)
+- v0.4: VS Code extension (quick log + generate/print context)

package/README.zh-CN.md

@@ -0,0 +1,156 @@
+# rmemo
+
+面向任何代码仓库的“项目记忆 + 开发日志”CLI：自动扫描项目结构，沉淀约定/进度，一键生成可直接粘贴给 AI 的 Context Pack。
+
+[English](./README.md) | [简体中文](./README.zh-CN.md)
+
+文档：
+- [使用方式（配合 AI 开发）](./docs/USAGE.zh-CN.md)
+- [发布说明](./RELEASING.md)
+
+## 为什么需要它
+
+隔天继续开发时，AI 工具经常会：
+- 忘记项目结构和约定（目录边界、命名、规范）
+- 重复做你已经做过的决策
+- 逐渐偏离仓库里既有的模式（AI drift）
+
+`rmemo` 的思路是把“项目记忆”放回仓库本身：把规则、进度、下一步、结构索引固化为文件，然后生成一个统一的 `Context Pack`，你可以把它喂给任何 AI（不绑定某一个模型/产品）。
+
+## 安装 / 运行
+
+目前是零依赖 Node 直接运行：
+
+```bash
+node bin/rmemo.js init
+node bin/rmemo.js log "完成用户列表页；下一步：加筛选条件"
+node bin/rmemo.js context
+node bin/rmemo.js print
+```
+
+后续可以发布到 npm，再全局安装。
+
+## 用在任意项目
+
+在目标项目根目录执行：
+
+```bash
+node /path/to/rmemo/bin/rmemo.js init
+node /path/to/rmemo/bin/rmemo.js log "做了 X；下一步 Y"
+node /path/to/rmemo/bin/rmemo.js context
+node /path/to/rmemo/bin/rmemo.js print
+```
+
+或者不切目录，直接指定仓库根路径：
+
+```bash
+node /path/to/rmemo/bin/rmemo.js --root /path/to/your-repo init
+```
+
+## 它会创建哪些文件
+
+- `.repo-memory/manifest.json`：检测到的结构信息、技术栈提示、关键文件
+- `.repo-memory/index.json`：文件索引（用于生成 context）
+- `.repo-memory/rules.md`：你的规则/约定（手写）
+- `.repo-memory/rules.json`：可执行规则（用于 `check`）
+- `.repo-memory/todos.md`：下一步与阻塞（手写/命令追加）
+- `.repo-memory/journal/YYYY-MM-DD.md`：按天顺序记录进度（手写/命令追加）
+- `.repo-memory/context.md`：生成的 AI 上下文包（生成文件）
+
+## 命令
+
+```bash
+rmemo init
+rmemo scan
+rmemo log <text>
+rmemo status
+rmemo check
+rmemo hook install
+rmemo start
+rmemo done
+rmemo todo add <text>
+rmemo todo block <text>
+rmemo todo ls
+rmemo context
+rmemo print
+```
+
+## 可执行规则（CI / Hooks）
+
+`rmemo` 支持在 `.repo-memory/rules.json` 里写规则，并用 `rmemo check` 在本地或 CI 执行。
+
+示例：
+
+```json
+{
+  "schema": 1,
+  "requiredPaths": ["README.md"],
+  "forbiddenPaths": [".env", ".env.*"],
+  "forbiddenContent": [
+    {
+      "include": ["**/*"],
+      "exclude": ["**/*.png", "**/*.jpg", "**/*.zip"],
+      "match": "BEGIN PRIVATE KEY",
+      "message": "禁止提交私钥内容。"
+    }
+  ],
+  "namingRules": [
+    {
+      "include": ["src/pages/**"],
+      "target": "basename",
+      "match": "^[a-z0-9-]+\\.vue$",
+      "message": "页面文件名必须是 kebab-case。"
+    }
+  ]
+}
+```
+
+执行检查：
+
+```bash
+rmemo check
+```
+
+Pre-commit 使用（更快，只检查暂存区文件）：
+
+```bash
+rmemo check --staged
+```
+
+安装 git pre-commit hook（提交前自动执行 `rmemo check`）：
+
+```bash
+rmemo hook install
+```
+
+## 日常工作流（推荐）
+
+开工（扫描结构 + 生成 context + 打印 status，方便你粘贴给 AI）：
+
+```bash
+rmemo start
+```
+
+收工（写入当天 journal；可选同时更新 Next/Blockers）：
+
+```bash
+rmemo done "今天完成了什么/做了什么决策"
+echo "今天总结..." | rmemo done
+rmemo done --next "明天第一步做什么" --blocker "当前阻塞是什么" "今天总结..."
+```
+
+手动维护下一步/阻塞（不想打开文件改）：
+
+```bash
+rmemo todo add "实现用户搜索"
+rmemo todo block "后端接口还没出"
+rmemo todo ls
+rmemo todo done 1
+rmemo todo unblock 1
+```
+
+## Roadmap（简版）
+
+- v0.2：增强通用扫描（monorepo/子项目/API 契约/文档根目录）
+- v0.3：规则能力增强 + 更好的 `check` 输出 + hooks/CI 体验打磨
+- v0.4：VS Code 扩展（快速 log/start/done）

package/bin/rmemo.js

@@ -0,0 +1,63 @@
+#!/usr/bin/env node
+import { cmdInit } from "../src/cmd/init.js";
+import { cmdScan } from "../src/cmd/scan.js";
+import { cmdLog } from "../src/cmd/log.js";
+import { cmdContext } from "../src/cmd/context.js";
+import { cmdPrint } from "../src/cmd/print.js";
+import { cmdStatus } from "../src/cmd/status.js";
+import { cmdCheck } from "../src/cmd/check.js";
+import { cmdHook } from "../src/cmd/hook.js";
+import { cmdStart } from "../src/cmd/start.js";
+import { cmdDone } from "../src/cmd/done.js";
+import { cmdTodo } from "../src/cmd/todo.js";
+import { parseArgs, printHelp } from "../src/lib/args.js";
+import { exitWithError } from "../src/lib/io.js";
+
+const argv = process.argv.slice(2);
+const { cmd, rest, flags } = parseArgs(argv);
+
+try {
+  switch (cmd) {
+    case "init":
+      await cmdInit({ flags });
+      break;
+    case "scan":
+      await cmdScan({ flags });
+      break;
+    case "log":
+      await cmdLog({ rest, flags });
+      break;
+    case "context":
+      await cmdContext({ flags });
+      break;
+    case "print":
+      await cmdPrint({ flags });
+      break;
+    case "status":
+      await cmdStatus({ flags });
+      break;
+    case "check":
+      await cmdCheck({ flags });
+      break;
+    case "hook":
+      await cmdHook({ rest, flags });
+      break;
+    case "start":
+      await cmdStart({ flags });
+      break;
+    case "done":
+      await cmdDone({ rest, flags });
+      break;
+    case "todo":
+      await cmdTodo({ rest, flags });
+      break;
+    case "help":
+    case undefined:
+      printHelp();
+      break;
+    default:
+      exitWithError(`Unknown command: ${cmd}\n\nRun: rmemo help`);
+  }
+} catch (err) {
+  exitWithError(err?.stack || err?.message || String(err));
+}

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@xiaofandegeng/rmemo",
+  "version": "0.0.3",
+  "description": "Repo memory + dev journal CLI: scan any project, persist conventions/progress, and generate an AI-ready context pack.",
+  "type": "module",
+  "bin": {
+    "rmemo": "bin/rmemo.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+ssh://git@github.com/xiaofandegeng/rmemo.git"
+  },
+  "bugs": {
+    "url": "https://github.com/xiaofandegeng/rmemo/issues"
+  },
+  "homepage": "https://github.com/xiaofandegeng/rmemo#readme",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "node --test",
+    "pack:dry": "npm_config_cache=.npm-cache npm pack --dry-run"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "test/",
+    "README.md",
+    "README.zh-CN.md",
+    "LICENSE",
+    "DEVELOPMENT_PLAN.md",
+    "CHANGELOG.md",
+    "CONTRIBUTING.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "ai",
+    "developer-tools",
+    "cli",
+    "context",
+    "journal",
+    "knowledge-base"
+  ]
+}

package/src/cmd/check.js

@@ -0,0 +1,30 @@
+import { resolveRoot } from "../lib/paths.js";
+import { runCheck } from "../core/check.js";
+
+export async function cmdCheck({ flags }) {
+  const root = resolveRoot(flags);
+  const maxFiles = Number(flags["max-files"] || 4000);
+  const preferGit = flags["no-git"] ? false : true;
+  const stagedOnly = !!flags.staged;
+
+  const res = await runCheck(root, { maxFiles, preferGit, stagedOnly });
+
+  for (const e of res.errors) {
+    process.stderr.write(`ERROR: ${e}\n`);
+  }
+
+  if (res.violations.length) {
+    for (const v of res.violations.slice(0, 200)) {
+      process.stderr.write(`VIOLATION: ${v.message}\n`);
+    }
+    if (res.violations.length > 200) process.stderr.write(`...and ${res.violations.length - 200} more\n`);
+  }
+
+  if (res.ok) {
+    process.stdout.write("OK: rules check passed\n");
+  } else if (!res.errors.length && res.violations.length) {
+    process.stderr.write(`FAIL: ${res.violations.length} violation(s)\n`);
+  }
+
+  process.exitCode = res.exitCode;
+}

package/src/cmd/context.js

@@ -0,0 +1,15 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { resolveRoot } from "../lib/paths.js";
+import { generateContext } from "../core/context.js";
+import { contextPath } from "../lib/paths.js";
+
+export async function cmdContext({ flags }) {
+  const root = resolveRoot(flags);
+  const snipLines = Number(flags["snip-lines"] || 120);
+  const recentDays = Number(flags["recent-days"] || 7);
+  const s = await generateContext(root, { snipLines, recentDays });
+  await fs.writeFile(contextPath(root), s, "utf8");
+  process.stdout.write(`Wrote: ${path.relative(process.cwd(), contextPath(root))}\n`);
+}
+

package/src/cmd/done.js

@@ -0,0 +1,55 @@
+import path from "node:path";
+import { resolveRoot } from "../lib/paths.js";
+import { readStdinText } from "../lib/stdin.js";
+import { appendJournalEntry } from "../core/journal.js";
+import { addTodoBlocker, addTodoNext } from "../core/todos.js";
+
+function normalizeNote(s) {
+  const t = String(s || "").trim();
+  if (!t) return "";
+  // Collapse consecutive blank lines.
+  return t.replace(/\n{3,}/g, "\n\n").trim();
+}
+
+async function appendJournal(root, text) {
+  return await appendJournalEntry(root, { kind: "Done", text });
+}
+
+async function maybeAppendNext(root, nextText) {
+  if (!nextText) return null;
+  const p = await addTodoNext(root, nextText);
+  return p;
+}
+
+export async function cmdDone({ rest, flags }) {
+  const root = resolveRoot(flags);
+
+  const next = flags.next ? String(flags.next).trim() : "";
+  const blocker = flags.blocker ? String(flags.blocker).trim() : "";
+  const argText = normalizeNote(rest.join(" "));
+  const stdinText = argText ? "" : normalizeNote(await readStdinText());
+
+  const text = argText || stdinText;
+  if (!text) {
+    process.stderr.write(
+      [
+        "Missing note text.",
+        "Usage:",
+        "  rmemo done \"today summary\"",
+        "  echo \"today summary\" | rmemo done",
+        "Options:",
+        "  --next \"tomorrow's next step\""
+      ].join("\n") + "\n"
+    );
+    process.exitCode = 2;
+    return;
+  }
+
+  const jp = await appendJournal(root, text);
+  const tp = await maybeAppendNext(root, next);
+  const bp = blocker ? await addTodoBlocker(root, blocker) : null;
+
+  process.stdout.write(`Wrote journal: ${path.relative(process.cwd(), jp)}\n`);
+  if (tp) process.stdout.write(`Updated todos: ${path.relative(process.cwd(), tp)}\n`);
+  if (bp && bp !== tp) process.stdout.write(`Updated todos: ${path.relative(process.cwd(), bp)}\n`);
+}