@plinth-music/cli 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -0,0 +1,88 @@
+# Changelog
+
+Notable changes to `@plinth-music/cli`. Grouped by what a user notices, not by PR.
+
+## 0.4.0 — 2026-08-06
+
+56 commits of product work since `0.3.0` (`v0.3.0..8c921e4`). `0.3.0` shipped four
+commands — `login`, `sync`, `start`, `version` — and synced a single entity type,
+documents. This release is most of a working daemon.
+
+### Five new commands
+
+- **`plinth status`** — daemon liveness, last sync and per-type counts, and how many
+  destructive batches are being held. Also warns when `dist/` is behind the checkout,
+  so a stale bundle can't be mistaken for the merged code (source-install only; a
+  registry install has no checkout to compare against and stays silent).
+- **`plinth confirm`** — review and release the destructive batches the daemon
+  quarantines. Apply, or `--discard`. `--all` is gated behind rendering every batch
+  first and a final default-No.
+- **`plinth refresh-context`** — regenerate the workspace-root `CLAUDE.md` from the
+  current schema and workspace. Your block between the `<!-- BEGIN: user-customisable -->`
+  markers is preserved verbatim; `CLAUDE.local.md` is never touched.
+- **`plinth grounding`** — print the session-start grounding block (current date,
+  entity resolution, write confirmation, workspace rules, workspace memory, user
+  memory). Invoked by the generated Claude Code SessionStart hook.
+- **`plinth voice-gate`** — gate agent-originated copy against the workspace voice
+  rubric. `--hook` runs it as a Claude Code PreToolUse hook that blocks
+  non-compliant Gmail drafts; direct mode gates a file or stdin and can print the
+  raw verdict as JSON.
+
+### Sync covers the workspace, not just documents
+
+`0.3.0` synced documents only — `plinth sync` was a one-shot pull, and `plinth start`
+carried a watcher that pushed local edits for that one type. `0.4.0` syncs
+**documents, projects, tasks, artists, meetings and threads**, each on its own entity
+strategy, in both directions. Alongside that:
+
+- **Ambient pull** — `plinth start` now pulls continuously rather than once at boot.
+- **A user-writable `files/` subtree** — drop any file into the mirror and it syncs.
+- **Rendered read-only blocks** in the mirror: artist contacts in `_artist.md`, a
+  bounded "Recent activity" comment tail on tasks and projects, and project-as-rollup
+  task lists in `projects/<slug>.md`.
+- **Documents round-trip raw markdown** — the HTML conversion layer is gone. Frontmatter
+  (`category`, `is_context_doc`) round-trips faithfully.
+- **`~/.plinth/daemon.log`** — live push/pull is visible instead of silent.
+
+### Your local edits are harder to lose
+
+Most of this release's fixes are one shape: the daemon must never silently discard
+work you did on disk.
+
+- Diverged local edits are reconciled at boot instead of being overwritten.
+- A singleton pull no longer clobbers un-pushed local edits.
+- Bulk deletes and gutting overwrites are quarantined for `plinth confirm` rather
+  than pushed.
+- Task-mirror conflicts are field-typed, and validation failures are written back
+  into the file as a `# sync-error` block instead of vanishing.
+- Rate-limit bursts (429) are throttled and retried, and anything still unsynced is
+  recorded rather than dropped.
+- Renames are classified against a refreshed inode at boot, so a stale one can't turn
+  a rename into a delete-plus-create.
+- Push failures surface the server's own error message instead of a bare 400.
+- Untracked files already on disk at daemon boot are discovered rather than ignored,
+  and the `files/` subtree is scaffolded at boot instead of deadlocking on its own
+  absence.
+
+### Context and grounding for agents
+
+- A workspace-root `CLAUDE.md` and per-artist `CLAUDE.md` / `memory.md` /
+  `daily-log.md` are generated on sync.
+- The workspace and per-artist maps are a content index, not just a folder structure.
+- `workspace-rules.md`, `workspace-memory.md` and a member-private user-memory lane
+  sync bidirectionally.
+- Dates ground to the mapped calendar rather than the retired `key_dates` table.
+
+### Notes
+
+- Requires Node >= 20. The keychain integration (`@napi-rs/keyring`) installs a
+  native prebuild for your platform: macOS Keychain, Windows Credential Manager, or
+  Linux Secret Service.
+- `dist/build-stamp.json` ships in the tarball and records the git SHA the bundle was
+  built from.
+
+## 0.3.0 — 2026-05-20
+
+First published release. `plinth login` with OS-keychain PAT storage, `plinth sync`
+(documents, one-shot pull), an early `plinth start` with a push watcher, and
+`plinth version`.

package/README.md

@@ -2,35 +2,41 @@
 
 Plinth capstone sync daemon and CLI. Mirrors your Plinth workspace to `~/Plinth/<workspace>/` and keeps it bidirectionally synced. AI-native: pair with Claude Code or any LLM agent for context-aware artist management.
 
-**Status: early access. `login` and `sync` (pull-only, documents) are implemented; the watcher and other entity types land in subsequent PRs. See V1_SPEC §5 M3 in the plinth monorepo for the full milestone plan.**
+**Status: early access.** Two-way sync runs as a daemon across documents, projects, tasks, artists, meetings, threads and a user-writable `files/` subtree. See `V1_SPEC` §5 M3 in the plinth monorepo for the full milestone plan, and [`CHANGELOG.md`](CHANGELOG.md) for what landed when.
 
-## Commands
+## Install
 
-Implemented today:
+```sh
+npm i -g @plinth-music/cli
+```
 
-- `plinth login --workspace <slug>` — issue a PAT in the browser, paste it back, store in the OS keychain (macOS Keychain / Linux Secret Service / Windows Credential Manager).
-- `plinth sync [--workspace <slug>]` — one-shot pull of documents into `~/Plinth/<workspace>/`. Defaults to the active workspace if `--workspace` is omitted.
+Requires Node >= 20. A Homebrew tap (signed + notarised) is planned; npm is the only install path today.
 
-Planned (not yet implemented):
+## Getting started
 
-- `plinth start` — run the sync daemon (file watcher + cloud subscription).
-- `plinth status` — print last-synced-at per entity type and pending changes.
-- `plinth refresh-context` — regenerate `CLAUDE.md` from the current Plinth schema + workspace.
-- `plinth export workspace` — generate an export bundle.
-- `plinth update` — detect install method (brew vs npm-global) and upgrade in place.
-- `plinth logout --workspace <slug>` — revoke local PAT reference, retain mirror files.
+```sh
+plinth login --workspace <slug>   # issue a PAT in the browser, paste it back
+plinth sync                       # one-shot pull into ~/Plinth/<slug>/
+plinth start                      # run the daemon: continuous pull + watch + push
+```
 
-## Install (once published)
+## Commands
 
-Neither path is published yet.
+- `plinth login --workspace <slug>` — issue a personal access token in the browser, paste it back, store it in the OS keychain (macOS Keychain / Linux Secret Service / Windows Credential Manager).
+- `plinth sync [--workspace <slug>]` — one-shot pull into `~/Plinth/<workspace>/`. Also generates the workspace-root `CLAUDE.md` (a thin TOC + entity model + skill pointers) and an empty `CLAUDE.local.md` stub on first sync, and silently refreshes `CLAUDE.md` on a schema-version change. Defaults to the active workspace if `--workspace` is omitted.
+- `plinth start` — run the long-running sync daemon: pull the latest, then watch the mirror for local edits and push them. Logs to `~/.plinth/daemon.log`.
+- `plinth status` — local sync state: daemon liveness, last sync and per-type counts, and any destructive batches being held. Warns when a source install's `dist/` is behind its checkout.
+- `plinth confirm` — review and release destructive batches the daemon has quarantined (apply, or `--discard`).
+- `plinth refresh-context [--workspace <slug>]` — force-regenerate the workspace-root `CLAUDE.md` from the current Plinth schema + workspace. The user-customisable block between the `<!-- BEGIN: user-customisable -->` / `<!-- END -->` markers is always preserved verbatim; `CLAUDE.local.md` is never touched.
+- `plinth grounding` — print the session-start grounding block (current date, entity resolution, write confirmation, workspace rules, workspace memory, user memory). Invoked by the generated Claude Code SessionStart hook.
+- `plinth voice-gate` — gate agent-originated copy against the workspace voice rubric. `--hook` runs it as a Claude Code PreToolUse hook that blocks non-compliant Gmail drafts; direct mode takes `--file <path>` or stdin and prints the verdict (`--json` for the raw response).
+- `plinth version` — print the installed version.
 
-```sh
-# npm (cross-platform)
-npm i -g @plinth-music/cli
+Planned (not yet implemented):
 
-# Homebrew (macOS, signed + notarised)
-brew install plinth-music/tap/plinth-cli
-```
+- `plinth export workspace` — generate an export bundle.
+- `plinth update` — detect install method (brew vs npm-global) and upgrade in place.
+- `plinth logout --workspace <slug>` — revoke the local PAT reference, retain mirror files.
 
 ## Develop
 
@@ -39,7 +45,7 @@ Requires [Bun](https://bun.sh/) (latest).
 ```sh
 bun install
 bun run build      # produces dist/cli.js
-bun test           # builds, then runs the smoke test
+bun test           # builds, then runs the suite
 bun run typecheck  # strict tsc, no emit
 ```
 
@@ -50,6 +56,8 @@ The built CLI is a standard Node-compatible ESM bundle with a `#!/usr/bin/env no
 ./dist/cli.js --help
 ```
 
+Releasing is documented in [`docs/RELEASING.md`](docs/RELEASING.md).
+
 ## License
 
 MIT — see `LICENSE`.

package/dist/build-stamp.json

@@ -0,0 +1,5 @@
+{
+  "sha": "1b7b9899ac3b1a049f45aab804272a571c2dded5",
+  "dirty": false,
+  "built_at": "2026-08-07T07:14:30.099Z"
+}