noggin-cli 0.1.3 → 0.4.2

package/README.md

@@ -4,8 +4,8 @@ A small, single-user working-memory tree for in-flight work — your
 second brain for the stuff you can't fit in your head.
 
 Lives in `~/.noggin.yaml` by default. Override per call with `--file
-<path>`, or set `$NOGGIN_FILE` to point every invocation at a
-different file. (The VS Code extension sets `NOGGIN_FILE` in its
+<path>`, or set `$NOGGIN` to point every invocation at a
+different file. (The VS Code extension sets `NOGGIN` in its
 terminals so the CLI follows whichever noggin you have open.) Driven
 by [`noggin.mjs`](noggin.mjs) next to this file. The YAML file is the source
 of truth; the CLI is the only sanctioned way to read or write it.
@@ -110,10 +110,12 @@ Every command takes:
 The file is resolved in this order:
 
 1. `--file <path>`
-2. `$NOGGIN_FILE` environment variable
+2. `$NOGGIN` environment variable
 3. `~/.noggin.yaml`
 
-Use `noggin where` at any time to print which file would be used and
+Use `noggin where` at any time to print the canonical location of
+the noggin currently in use (a round-trippable string like
+`~/.noggin.yaml`, `./.noggin.yaml`, or an absolute path).
 why.
 
 Commands that change or inspect a target also take `--goto [path]`.
@@ -135,7 +137,8 @@ Common flags can appear before or after the verb.
 | `show [<path>] [--no-children\|--with-descendants] [--with-siblings] [--with-all] [--with-notes] [--goto [path]]` | Current-position view: ancestor spine, sibling peers, current-item details, and first-level children. Default target is active. `--no-children` omits children. `--with-siblings` also includes the full sibling row at every ancestor depth (sibling subtrees stay collapsed). `--with-descendants` expands the target's subtree recursively. `--with-all` = `--with-siblings --with-descendants`. `--with-notes` appends note bodies. `--no-children` and `--with-descendants` are mutually exclusive. |
 | `note [<path>] <text…> [--goto [path]]` | Append a timestamped note. |
 | `delete <path> [--recursive]` | Remove an item. Refuses if the item has descendants unless `--recursive` is passed, in which case the whole subtree is deleted. If the active item is inside the deleted subtree, active falls back to the deleted item's parent (or becomes empty if it was a root). |
-| `where` | Print which noggin file would be used and why (flag / env / default). |
+| `where` | Print the canonical location string of the noggin in use. |
+| `copy <from> <to>` | Append every item from the `<from>` noggin into the `<to>` noggin. Whole-noggin, append-only. Source roots become new roots of dest, after any existing dest content. Keys are regenerated; notes, done state, and `createdAt` are preserved verbatim. Source is not modified. Dest's `active` is unchanged. v1 copies the entire source; subtree slicing is reserved for a later version. |
 | `help` | Print full help. |
 
 ### Tree output
@@ -156,30 +159,33 @@ append them after the tree.
 
 ### JSON output
 
-`--json` and `--with-json` emit a stable envelope shared with the VS Code
-extension's language-model tools, so a single consumer can target both
-surfaces.
+`--json` and `--with-json` emit a stable response envelope shared with
+the VS Code extension's language-model tools, so a single consumer can
+target both surfaces.
 
 ```jsonc
 // success
 {
   "status": "ok",
-  "schemaVersion": 2,        // JSON_SCHEMA_VERSION — bump on breaking changes
+  "envelopeVersion": 3,      // RESPONSE_ENVELOPE_VERSION — bump on breaking changes
   "verb": "push",            // command that produced this payload
-  "file": "/…/.noggin.yaml", // resolved noggin file
   "data": { … }              // verb-specific (CurrentTreeView, DeleteResult, …)
 }
 
 // error (written to stderr; exit code matches error.exitCode)
 {
   "status": "error",
-  "schemaVersion": 2,
+  "envelopeVersion": 3,
   "verb": "push",
-  "file": "/…/.noggin.yaml",
   "error": { "code": "title-required", "message": "…", "exitCode": 2 }
 }
 ```
 
+`envelopeVersion` versions the wrapper shape (and the per-verb
+payloads inside `data`), independently of the on-disk document's
+`schemaVersion` (see [File schema](#file-schema-v1)). The two rev
+on different cadences.
+
 Inside `data`, a small whitelist of fields whose value matches their
 declared default is **omitted** to keep payloads focused. A consumer
 that doesn't see one of these fields should treat it as the default:
@@ -193,11 +199,12 @@ that doesn't see one of these fields should treat it as the default:
 | `activeKey` | `null` (no active item) |
 | `descendantCount` | `0` (in `DeleteResult`) |
 | `view` | `null` (delete left the tree empty) |
-| `exists` | `false` (in `where` output) |
-| `env` | `null` (in `where` output, no `$NOGGIN_FILE` set) |
 
 Everything else is always present, including the envelope itself
-(`status`, `schemaVersion`, `verb`, `file`, `data` / `error`).
+(`status`, `envelopeVersion`, `verb`, `data` / `error`).
+
+`where --json` is a special case: `data` is a plain string (the
+canonical location of the noggin), not a structured object.
 
 `ViewNode.children` is special: it's already a tri-state encoded by
 presence (see `CurrentTreeView` below). Pruning doesn't touch it.
@@ -272,8 +279,59 @@ Returned in `data` by `delete`. Always carries the deletion record;
 
 #### `where`
 
-Returns the `FileResolution` shape: `{ file, source, exists,
-defaultFile, env }` with all fields always present.
+Returns the canonical location string of the noggin currently in use
+— the same string `openNoggin()` would accept to reopen it. The
+string is round-trippable: `~/.noggin.yaml` stays as `~/.noggin.yaml`,
+`./.noggin.yaml` stays as `./.noggin.yaml`, absolute paths stay
+absolute. Both the human and `--json` output are this single string.
+
+## JavaScript API
+
+For consumers embedding noggin in a Node process (the VS Code
+extension, custom tooling), there's a small public API beyond the
+CLI:
+
+```js
+import { fileNoggin } from 'noggin/backends/file';
+
+const noggin = await fileNoggin('/path/to/.noggin.yaml', { watch: true });
+const view = await noggin.push({ title: 'spike storage layer' });
+console.log(noggin.active?.title);
+noggin.onDidChange(() => render(noggin.items));
+await noggin.dispose();
+```
+
+### Public surface
+
+| What | Where |
+|---|---|
+| `Noggin` class — live noggin with verb methods, accessors, events | `noggin/noggin-api.mjs` |
+| `fileNoggin(path, opts?): Promise<Noggin>` — open a file-backed noggin | `noggin/backends/file.mjs` |
+| `applyX(doc, opts, ctx?)` — pure verb functions over `NogginDocument` | `noggin/noggin-api.mjs` |
+| `fromYaml` / `toYaml` / `fromJson` / `toJson` — serializers | `noggin/serializers/{yaml,json}.mjs` |
+| `NogginError`, `NogginErrorCode` — typed errors | `noggin/noggin-api.mjs` |
+| `formatSuccess` / `formatError` — response envelope helpers | `noggin/noggin-api.mjs` |
+| `SCHEMA_VERSION`, `RESPONSE_ENVELOPE_VERSION` — constants | `noggin/noggin-api.mjs` |
+
+All `Noggin` verb methods return `Promise`. Per-instance calls are
+serialized (in-process queue); cross-process callers should treat
+the file as advisory-locked at the application layer.
+
+### `NogginDocument` shape
+
+The serialized form (what the JSON Schema validates, what
+serializers convert to/from) is just:
+
+```ts
+interface NogginDocument {
+  schemaVersion: 1;
+  active: ItemKey | null;
+  items: Item[];
+}
+```
+
+A live `Noggin` does not expose `schemaVersion` — that's a wire
+concern, owned by the serializers.
 
 ## File schema (v1)
 
@@ -281,6 +339,28 @@ The CLI reads and writes a single YAML file. Writes are atomic: the
 CLI writes to `<file>.tmp-<pid>-<ts>` and renames over the real path,
 so a partial write never corrupts the user's file.
 
+A machine-readable JSON Schema for the noggin data model is published
+at the repo root as [`noggin.schema.json`](../noggin.schema.json).
+The schema describes the shape itself, independent of any particular
+producer or consumer — YAML 1.2 is a JSON superset, so the same schema
+validates both YAML and JSON renderings. To get autocomplete and inline
+validation in VS Code, install the Red Hat YAML extension and add to
+your settings:
+
+```jsonc
+"yaml.schemas": {
+  "https://dornstein.github.io/noggin/noggin.schema.json": [
+    ".noggin.yaml",
+    "**/.noggin/*.yaml"
+  ]
+}
+```
+
+The CLI enforces stronger invariants than JSON Schema can express
+(unique keys, `parentKey`/`active` referential integrity, the "done
+items have no open descendants" rule unless force-closed) — see
+[Invariants](#invariants) below.
+
 ### Top-level shape
 
 ```yaml

package/SKILL.md

@@ -79,6 +79,7 @@ stable IDs. Don't store them.
 | "Add a note about X" | `note <text>` (active) or `note <path> <text>` |
 | "Rename this" | `edit [<path>] --title <new title>` |
 | "Drop this" / "never mind, delete it" | `delete <path>` (add `--recursive` if it has children) |
+| "Migrate my noggin into this repo" / "copy the home noggin into this folder" | `copy <from> <to>` (whole-noggin, append-only; preserves notes and timestamps) |
 
 Default to `push` for active side-quests, `add` for everything that
 can wait. The cost of `add` is near zero — capture stray "we should
@@ -115,15 +116,22 @@ also…" remarks rather than letting them evaporate.
    `#nogginPop`, `#nogginNote`, `#nogginEdit`,
    `#nogginMove`, `#nogginDelete`) over shelling out to `noggin.mjs`. The tools always
    target the noggin the user has open in the editor. If you do shell
-   out, the CLI honors the `NOGGIN_FILE` env var, which the extension
+   out, the CLI honors the `NOGGIN` env var, which the extension
    sets in every terminal — so `node noggin.mjs ...` in a VS Code
    terminal still hits the right file. Use `noggin where` if you need
    to confirm which file the CLI would touch.
-11. **Outside VS Code (Copilot CLI, Claude Code, Codex), prefer the MCP
+11. **Outside VS Code (GitHub Copilot CLI, Claude Code, Codex), prefer the MCP
    tools** (`noggin_show`, `noggin_push`, etc.) when the host has the
    noggin MCP server wired up — they return the same JSON envelope as
    the CLI with no spawn cost. Fall back to `noggin.mjs` only when no
    tool surface is available.
+12. **The MCP server is multi-noggin: every tool call requires a `noggin`
+   parameter** — a canonical location string like `~/.noggin.yaml`,
+   `./.noggin.yaml`, or `file:///abs/path.yaml`. There is no
+   server-wide default. Pass the location the user is working with;
+   if you don't know it, ask. Use `noggin_where` to confirm a noggin
+   is reachable, or `noggin_factories` to discover what location forms
+   the server accepts.
 
 ## Resumption note template