@life-os/cli 0.0.1 → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,17 +1,129 @@
1
- # @life-os/cli
1
+ # @lifeos/cli — `lifeos`
2
2
 
3
- Bootstrap CLI package for the Life OS project.
3
+ Headless, config-aware command-line interface over a LifeOS vault, built for AI
4
+ agents (Claude Code, etc.). Lets an agent read and query your LifeOS notes,
5
+ tasks, PARA and tags **without opening Obsidian or Aino**.
4
6
 
5
- ## Install
7
+ ## Why it exists
8
+
9
+ Unlike the official Obsidian CLI (a remote control for a _running_ app), `lifeos`
10
+ works directly on the vault folder. It reuses the same engine
11
+ (`@lifeos/vault-lifeos-service` → `@lifeos/query-core` + `@lifeos/markdown-indexer`)
12
+ that powers Aino and the daemons, so query results match exactly what you see in
13
+ the plugin.
14
+
15
+ **Config-aware:** it reads your real settings from the same sources the rest of
16
+ LifeOS uses, in this order:
17
+
18
+ 1. `.obsidian/plugins/periodic-para/data.json`
19
+ 2. `.obsidian/plugins/lifeos-pro/data.json`
20
+ 3. `.lifeos/settings.json` (Aino's vault-portable settings)
21
+
22
+ So PARA folder names, periodic-note formats, habit/section headers and templates
23
+ all come from _your_ configuration, not hardcoded defaults. Run `lifeos config`
24
+ to see exactly what was picked up.
25
+
26
+ ## Vault selection (first match wins)
27
+
28
+ 1. `vault=<path>` option
29
+ 2. `$LIFEOS_VAULT` env var
30
+ 3. Walk up from the current directory for a `.obsidian/` or `.lifeos/` folder
31
+ 4. The folder Aino last opened (`userData/bootstrap.json` → `lastOpenedFolder`)
32
+
33
+ The cwd walk comes before the Aino fallback by design: the agent skill is
34
+ installed _inside_ a vault and runs from that vault's directory, so the cwd is
35
+ the most reliable signal of which vault the user means. Aino's last-opened folder
36
+ is only used when running outside any vault.
37
+
38
+ ## Commands
39
+
40
+ ```bash
41
+ # Read / query
42
+ lifeos config # effective settings + where they came from
43
+ lifeos tasks [todo|done|all] # list tasks (filters: tag=, keyword=, due=today|week|overdue, limit=)
44
+ lifeos search query=<text> # find notes (type=file default | tag | content); add `case` for content
45
+ lifeos read file=<name>|path=<p> # print a note
46
+
47
+ # Periodic notes — daily|weekly|monthly|quarterly|yearly (path from periodicNotesPath + format)
48
+ lifeos daily [date=YYYY-MM-DD] # show the note path + whether it exists
49
+ lifeos weekly:read [date=] # read the note
50
+ lifeos monthly:append content=<t> # append to the note (creates it if missing)
51
+
52
+ # Write
53
+ lifeos append path=<p> content=<t> # append text to an existing note
54
+ lifeos create path=<p> [content=] # create a note (add `overwrite` to replace)
55
+ lifeos task done|todo ref=<f>:<n> # toggle a task by its file:line reference
56
+
57
+ lifeos help
58
+ ```
59
+
60
+ Every command accepts `--json` for machine-readable output.
61
+
62
+ ### Examples
6
63
 
7
64
  ```bash
8
- npm install -g @life-os/cli
65
+ lifeos config vault="~/Documents/My Vault"
66
+ lifeos tasks todo due=week limit=20
67
+ lifeos tasks done tag=个人品牌 --json
68
+ lifeos search query=项目 type=file
69
+ lifeos read file="WOT-分享会.README"
70
+ lifeos append path="1. 项目/x.md" content="- new bullet"
71
+ lifeos create path="3. 资源/RAG 调研" content="# RAG 调研"
72
+ lifeos task done ref="0. 周期笔记/2025/Daily/05/2025-05-30.md:14"
9
73
  ```
10
74
 
11
- ## Run
75
+ Writes take an explicit `path=` / `ref=` (no name guessing), so the agent should
76
+ `search` / `tasks` first to get the exact target, then write.
77
+
78
+ ## Syntax
79
+
80
+ Options use `key=value` (or `--key=value`); flags are bare `--flag`. This mirrors
81
+ the Obsidian CLI convention so agent prompting transfers.
82
+
83
+ ## Build & test
84
+
85
+ ```bash
86
+ pnpm -C apps/lifeos-cli build
87
+ pnpm -C apps/lifeos-cli test
88
+ ```
89
+
90
+ ## Scope
91
+
92
+ This CLI is the **vault data layer** of LifeOS: read/query/(soon) write of note
93
+ content, tasks, PARA and tags. It deliberately does **not** wrap the plugin's UI
94
+ views or background network sync (Google Calendar / CalDAV / two-way task sync) —
95
+ those stay in the plugin and Aino.
96
+
97
+ ### Periodic-note resolution
98
+
99
+ All five period types reuse `@lifeos/shared`'s `buildPeriodicNotePath` — the exact
100
+ formatter the plugin and Aino use (ISO weeks, matching the plugin's `getPeriodicFile`)
101
+ — over the resolved `periodicNotesPath` + per-type format, so they land on the same
102
+ files. Weekday/month tokens (`dddd`/`MMMM`) use native `Intl` with a locale
103
+ (`locale=`, default system). Every form prints the resolved path and `Exists`
104
+ status; if a vault's config diverges from how existing notes were named (e.g.
105
+ Aino's `.lifeos/settings.json` has a `_dddd` suffix the on-disk files lack), that
106
+ shows up as `Exists: no` rather than a silent mis-write.
107
+
108
+ ### Known limitations / next
109
+
110
+ - `tasks`/`search` content scan re-reads files per call (no persistent cache) —
111
+ fine for one-shot CLI use, but not for tight loops.
112
+ - `search type=content` is a plain substring match (no regex yet).
113
+
114
+ ## Publishing
115
+
116
+ The workspace package is `@lifeos/cli`; it is published to public npm as
117
+ **`@life-os/cli`** (its own org, since the `@lifeos/*` source scope is
118
+ workspace-internal — see `docs/decisions/scope-strategy.md`).
119
+
120
+ `pnpm -C apps/lifeos-cli build:release` bundles the CLI and all internal
121
+ `@lifeos/*` deps into a single self-contained `dist/lifeos.mjs` (via esbuild) and
122
+ stages a clean, dependency-free package under `apps/lifeos-cli/release/`. Then:
12
123
 
13
124
  ```bash
14
- lifeos
125
+ pnpm -C apps/lifeos-cli build:release:dry-run # bundle + npm pack --dry-run
126
+ cd apps/lifeos-cli/release && npm publish # publishes @life-os/cli
15
127
  ```
16
128
 
17
- The current release only verifies that the CLI is installed correctly.
129
+ End users then `npm i -g @life-os/cli`; the installed command is `lifeos`.