project-mgr 0.1.0 → 0.1.2

package/.env_sample

@@ -1,5 +1,7 @@
-# SQLite database path. Relative paths are resolved from the current directory.
-PMGR_DB_PATH=./data/project-mgr.sqlite
+# Optional SQLite database override. When unset, the database is stored at
+# ~/.local/share/project-mgr/project-mgr.sqlite.
+# Use a literal absolute path here; .env files do not expand ~ or $HOME.
+# PMGR_DB_PATH=/absolute/path/to/project-mgr.sqlite
 
 # For isolated manual testing, use a separate database instead:
-# PMGR_DB_PATH=./data/manual-test.sqlite
+# PMGR_DB_PATH=/tmp/project-mgr-manual-test.sqlite

package/CHANGELOG.md

@@ -2,14 +2,26 @@
 
 ## Unreleased
 
+## 0.1.2 - 2026-08-03
+
+### Changed
+
+- Moved the default database from the command's working directory to the stable per-user path `~/.local/share/project-mgr/project-mgr.sqlite`.
+
+## 0.1.1 - 2026-08-03
+
+### Changed
+
+- Documented npm execution with `npx` and optional global installation.
+
+## 0.1.0 - 2026-08-03
+
 ### Fixed
 
 - Approved the required `better-sqlite3` and `esbuild` build scripts for reproducible frozen pnpm installs.
 - Made empty human-readable list queries explicit while preserving `[]` JSON output.
 - Added top-level CLI action shorthand while keeping `status <action>` compatibility.
 
-## 0.1.0 - 2026-08-03
-
 ### Added
 
 - A local TypeScript CLI and SQLite append-only project status ledger.

package/README.md

@@ -6,7 +6,32 @@
 
 The first release provides only a local CLI and SQLite. It has no HTTP API, long-running service, or agent skills. Data stays on the local machine and requires no account or cloud service.
 
-## Install and run
+## Run from npm
+
+Requires Node.js 22+.
+
+Run without installing:
+
+```bash
+npx --yes project-mgr current
+```
+
+Or install the CLI globally:
+
+```bash
+npm install --global project-mgr
+pmgr current
+```
+
+The database defaults to `~/.local/share/project-mgr/project-mgr.sqlite`, regardless of the directory where `pmgr` is executed. The CLI resolves this to an absolute path using the current user's home directory and creates the parent directory automatically.
+
+Set `PMGR_DB_PATH` to use another location:
+
+```bash
+PMGR_DB_PATH=/absolute/path/projects.sqlite npx --yes project-mgr current
+```
+
+## Build from source
 
 Requires Node.js 22+ and pnpm 10.30.2.
 
@@ -30,26 +55,26 @@ During development, run the TypeScript CLI directly:
 pnpm pmgr current
 ```
 
-The default configuration in `.env_sample` is:
+The default database path is:
 
-```dotenv
-PMGR_DB_PATH=./data/project-mgr.sqlite
+```text
+~/.local/share/project-mgr/project-mgr.sqlite
 ```
 
-Set `PMGR_DB_PATH` in `.env` to use another location, or override it for one command:
+`PMGR_DB_PATH` is optional in `.env_sample`. Set it in `.env` to use another location, or override it for one command:
 
 ```bash
 PMGR_DB_PATH=/absolute/path/projects.sqlite pnpm start current
 ```
 
-Relative paths are resolved from the working directory of the command. When `pnpm start ...` runs from this project's root, the default database is `./data/project-mgr.sqlite`. It is created automatically when the first valid command runs.
+Use a literal absolute path in `.env`; `.env` files do not expand `~` or `$HOME`. The database is created automatically when the first valid command runs.
 
 ### Use an isolated test database
 
 For manual testing, set a persistent path in `.env` that is separate from production data:
 
 ```dotenv
-PMGR_DB_PATH=./data/manual-test.sqlite
+PMGR_DB_PATH=/tmp/project-mgr-manual-test.sqlite
 ```
 
 Then run commands normally:
@@ -65,7 +90,7 @@ pnpm start history --project test-project
 
 Project keys must match exactly: a record added to `test-project` is not part of `project-mgr` history. Empty human-readable list queries print `No entries found.`; with `--json`, they print `[]`.
 
-`data/` is ignored by Git, so test data is not committed. Delete `data/manual-test.sqlite` when it is no longer needed.
+Delete `/tmp/project-mgr-manual-test.sqlite` when it is no longer needed.
 
 Automated tests use an in-memory database or SQLite files in the system temporary directory; they do not read or write the default database. `PMGR_DB_PATH=:memory:` also works for one command, but each CLI command runs in a separate process and its data disappears when the command exits, so it is not suitable for consecutive manual tests.
 
@@ -166,7 +191,7 @@ Exports omit the database-internal `id` and `recordedAt` fields and can be impor
 ```bash
 pnpm start export --format jsonl > project-statuses.jsonl
 
-PMGR_DB_PATH=./data/restored.sqlite \
+PMGR_DB_PATH=/tmp/project-mgr-restored.sqlite \
   pnpm start import project-statuses.jsonl
 ```
 

package/README_CN.md

@@ -6,7 +6,32 @@
 
 首版只提供本地 CLI 和 SQLite，不包含 HTTP API、常驻服务或 Agent Skills。数据默认保存在本机，无需账号或云服务。
 
-## 安装与运行
+## 从 npm 运行
+
+需要 Node.js 22+。
+
+无需安装即可运行：
+
+```bash
+npx --yes project-mgr current
+```
+
+也可以全局安装 CLI：
+
+```bash
+npm install --global project-mgr
+pmgr current
+```
+
+无论在哪个目录执行 `pmgr`，数据库都默认位于 `~/.local/share/project-mgr/project-mgr.sqlite`。CLI 会根据当前用户的主目录将其解析为绝对路径，并自动创建父目录。
+
+通过 `PMGR_DB_PATH` 指定其他位置：
+
+```bash
+PMGR_DB_PATH=/absolute/path/projects.sqlite npx --yes project-mgr current
+```
+
+## 从源码构建
 
 需要 Node.js 22+ 和 pnpm 10.30.2。
 
@@ -30,26 +55,26 @@ pnpm start current
 pnpm pmgr current
 ```
 
-默认配置位于 `.env_sample`：
+默认数据库路径是：
 
-```dotenv
-PMGR_DB_PATH=./data/project-mgr.sqlite
+```text
+~/.local/share/project-mgr/project-mgr.sqlite
 ```
 
-通过 `.env` 中的 `PMGR_DB_PATH` 指定其他位置，也可以为单条命令临时覆盖：
+`.env_sample` 中的 `PMGR_DB_PATH` 是可选配置。可以在 `.env` 中指定其他位置，也可以为单条命令临时覆盖：
 
 ```bash
 PMGR_DB_PATH=/absolute/path/projects.sqlite pnpm start current
 ```
 
-路径基于启动命令的当前工作目录计算。从本项目根目录执行 `pnpm start ...` 时，默认位置就是 `./data/project-mgr.sqlite`。数据库会在第一次执行有效命令时自动创建。
+在 `.env` 中应填写字面量绝对路径；`.env` 文件不会展开 `~` 或 `$HOME`。数据库会在第一次执行有效命令时自动创建。
 
 ### 使用独立测试数据库
 
 手工测试时，建议在 `.env` 中固定设置一个与正式数据分离的路径：
 
 ```dotenv
-PMGR_DB_PATH=./data/manual-test.sqlite
+PMGR_DB_PATH=/tmp/project-mgr-manual-test.sqlite
 ```
 
 随后正常执行命令：
@@ -65,7 +90,7 @@ pnpm start history --project test-project
 
 项目键必须完全一致：写入 `test-project` 的记录不会出现在 `project-mgr` 的历史中。人类可读的空列表查询会输出 `No entries found.`；使用 `--json` 时则输出 `[]`。
 
-`data/` 已加入 Git ignore，测试数据不会进入版本库。不需要保留时，可以删除 `data/manual-test.sqlite`。
+不需要保留时，可以删除 `/tmp/project-mgr-manual-test.sqlite`。
 
 自动化测试会使用内存数据库或系统临时目录中的 SQLite 文件，不会读写默认数据库。`PMGR_DB_PATH=:memory:` 也可用于单条命令，但每个 CLI 命令都是独立进程，命令结束后数据就会消失，不适合连续手工测试。
 
@@ -166,7 +191,7 @@ pnpm start import --file statuses.jsonl --json
 ```bash
 pnpm start export --format jsonl > project-statuses.jsonl
 
-PMGR_DB_PATH=./data/restored.sqlite \
+PMGR_DB_PATH=/tmp/project-mgr-restored.sqlite \
   pnpm start import project-statuses.jsonl
 ```
 

package/dist/db.js

@@ -1,5 +1,6 @@
 import Database from "better-sqlite3";
 import { mkdirSync } from "node:fs";
+import { homedir } from "node:os";
 import { dirname, resolve } from "node:path";
 import { validateStatusEntry, ValidationError, } from "./domain.js";
 const migration = `
@@ -28,7 +29,7 @@ CREATE INDEX IF NOT EXISTS idx_status_entries_project_occurred ON status_entries
 `;
 export function databasePath() {
     return (process.env.PMGR_DB_PATH ||
-        resolve(process.cwd(), "data", "project-mgr.sqlite"));
+        resolve(homedir(), ".local", "share", "project-mgr", "project-mgr.sqlite"));
 }
 export function openLedger(path = databasePath()) {
     if (path !== ":memory:")

package/docs/architecture.md

@@ -57,7 +57,7 @@ The `project_id, occurred_at DESC, id DESC` index supports current-status and hi
 
 After opening the database, `openLedger()` enables foreign keys, creates the migration table, and checks for and applies migration 1 within a `BEGIN IMMEDIATE` transaction. The immediate transaction prevents migration checks and writes from interleaving when several local processes open the database for the first time at once.
 
-The database path is read from `PMGR_DB_PATH` first; otherwise, it uses `data/project-mgr.sqlite` in the process working directory. Non-memory databases create their parent directory automatically.
+The database path is read from `PMGR_DB_PATH` first; otherwise, it uses the absolute path `~/.local/share/project-mgr/project-mgr.sqlite`, resolved from the current user's home directory. Non-memory databases create their parent directory automatically.
 
 ## Write flow
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "project-mgr",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Local-first append-only project status ledger",
   "type": "module",
   "bin": {

package/src/db.ts

@@ -1,5 +1,6 @@
 import Database from "better-sqlite3";
 import { mkdirSync } from "node:fs";
+import { homedir } from "node:os";
 import { dirname, resolve } from "node:path";
 import {
   type Source,
@@ -46,7 +47,7 @@ CREATE INDEX IF NOT EXISTS idx_status_entries_project_occurred ON status_entries
 export function databasePath(): string {
   return (
     process.env.PMGR_DB_PATH ||
-    resolve(process.cwd(), "data", "project-mgr.sqlite")
+    resolve(homedir(), ".local", "share", "project-mgr", "project-mgr.sqlite")
   );
 }
 

package/test/core.test.ts

@@ -1,6 +1,6 @@
 import assert from "node:assert/strict";
 import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
-import { tmpdir } from "node:os";
+import { homedir, tmpdir } from "node:os";
 import { join } from "node:path";
 import test from "node:test";
 import { run } from "../src/cli.js";
@@ -171,7 +171,7 @@ test("import validates before transaction and default source is import", () => {
   db.close();
 });
 
-test("database path uses environment override and file migration creates parent directory", () => {
+test("database path has a stable default and environment override creates its parent directory", () => {
   const directory = mkdtempSync(join(tmpdir(), "pmgr-"));
   const previous = process.env.PMGR_DB_PATH;
   process.env.PMGR_DB_PATH = join(directory, "nested", "ledger.sqlite");
@@ -180,7 +180,10 @@ test("database path uses environment override and file migration creates parent
   db.close();
   if (previous === undefined) delete process.env.PMGR_DB_PATH;
   else process.env.PMGR_DB_PATH = previous;
-  assert.match(databasePath(), /data\/project-mgr\.sqlite$/);
+  assert.equal(
+    databasePath(),
+    join(homedir(), ".local", "share", "project-mgr", "project-mgr.sqlite"),
+  );
   rmSync(directory, { recursive: true, force: true });
 });