@kitelev/exocortex-cli 16.240.18 → 16.241.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.
Files changed (3) hide show
  1. package/README.md +69 -21
  2. package/dist/index.js +258 -252
  3. package/package.json +1 -1
package/README.md CHANGED
@@ -119,20 +119,40 @@ npx @kitelev/exocortex-cli apply <cmd> [path] [options]
119
119
 
120
120
  **Options:**
121
121
 
122
- | Option | Default | Description |
123
- | ---------------------- | ------- | ----------------------------------------------------------------- |
124
- | `--vault <path>` | cwd | Path to Obsidian vault |
125
- | `--dry-run` | off | Evaluate precondition and preview; do not write |
126
- | `--yes` | off | Skip destructive-command confirmation |
127
- | `--input <json>` | — | JSON object forwarded to `service_call` groundings as `userInput` |
128
- | `--seed <uuid>` | — | Deterministic UID seed for test/replay |
129
- | `--frozen-clock <iso>` | — | Freeze clock to an ISO timestamp for test/replay |
122
+ | Option | Default | Description |
123
+ | ---------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
124
+ | `--vault <path>` | cwd | Path to Obsidian vault |
125
+ | `--dry-run` | off | Evaluate precondition and preview; do not write |
126
+ | `--yes` | off | Skip destructive-command confirmation |
127
+ | `--input <json>` | — | JSON object forwarded to `service_call` groundings as `userInput` |
128
+ | `--seed <uuid>` | — | Deterministic UID seed for test/replay |
129
+ | `--frozen-clock <iso>` | — | Freeze clock to an ISO timestamp for test/replay |
130
+ | `--json` | off | Emit a machine-readable `{command,target,created:[…]}` envelope |
131
+ | `--use-cache` | off | Load the triple store from the persistent cache (the next `--use-cache` process picks the mutation up as a delta) (#4264) |
132
+ | `--write-through` | off | With `--use-cache`: fold the mutation into the cache in this process so the next process is a plain hit; refused without `--use-cache` (#4264) |
130
133
 
131
134
  **Behavior:**
132
135
 
133
136
  - The precondition is evaluated per target; a non-passing ASK aborts before the grounding runs.
134
137
  - Commands marked `exocmd__Command_destructive: true` refuse to run without `--dry-run` or `--yes`.
135
138
  - Multi-target runs (stdin) use continue-on-error semantics and print a `N/M` summary; the exit code is `5` if any target failed.
139
+ - `--use-cache` (#4264): the triple store comes from `<vault>/.exocortex/cache/triples.json`
140
+ (hit / delta / rebuild, same loader as `query --use-cache`) instead of a full vault parse.
141
+ By default the mutating process leaves the cache file untouched (**delta-only**): the next
142
+ `--use-cache` process folds the change in as its own delta (only the changed files + their
143
+ referrers re-parsed), and its preconditions see the write. With `--write-through` the
144
+ writer pays that delta itself right after the grounding executed, so the next process is a
145
+ plain hit — worth it when readers outnumber writers (measured on the bot's 3-writer chain,
146
+ delta-only is 1–3 s cheaper and 0.2–0.6 GB lighter in the writer; #4264 has the matrix).
147
+ `--write-through` without `--use-cache` is refused (exit 2) before anything is applied.
148
+ Best-effort: a write-through that cannot persist prints a `⚠ triple cache:` warning and
149
+ leaves the exit code and stdout untouched; the next reader refreshes the cache itself. A
150
+ change the delta cannot express (TBox-form asset, FileSpace declaration) is left to the
151
+ next reader's rebuild. One stderr line per cache phase (`⚡ triple cache: hit`,
152
+ `💾 triple cache: write-through persisted (N file(s) re-parsed)`); stdout is unchanged.
153
+ Without the flag nothing is read from or written to the cache. On a cache built by
154
+ `index` the store additionally carries the inferred layer (as `query --use-cache` does);
155
+ use `index --no-inference` if a precondition must see the explicit graph only.
136
156
 
137
157
  **Examples:**
138
158
 
@@ -306,19 +326,30 @@ Create a new vault asset with auto-generated UUID, timestamps, and frontmatter.
306
326
  npx @kitelev/exocortex-cli create --class ztlk__PermanentNote --label "My Note" --vault ~/vault
307
327
  ```
308
328
 
309
- | Option | Default | Description |
310
- | ---------------------------- | ------------- | ------------------------------------------------------- |
311
- | `--class <name>` | **required** | Class short name (e.g. `ztlk__PermanentNote`) or UUID |
312
- | `--label <text>` | **required** | Human-readable label for the asset |
313
- | `--vault <path>` | cwd | Path to Obsidian vault |
314
- | `--aliases <names...>` | — | Additional aliases for the asset |
315
- | `--property <key=value...>` | — | Property key-value pairs (repeatable) |
316
- | `--body <text>` | — | Markdown body content (use `-` to read from stdin) |
317
- | `--body-file <path>` | — | Read body content from a file |
318
- | `--dry-run` | off | Preview the exact file content (stderr) without writing |
319
- | `--created-by <uuid>` | — | Creator UUID |
320
- | `--timezone <tz>` | `Asia/Almaty` | Timezone for timestamps |
321
- | `--skip-wikilink-validation` | off | Skip wikilink existence validation |
329
+ | Option | Default | Description |
330
+ | ---------------------------- | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
331
+ | `--class <name>` | **required** | Class short name (e.g. `ztlk__PermanentNote`) or UUID |
332
+ | `--label <text>` | **required** | Human-readable label for the asset |
333
+ | `--vault <path>` | cwd | Path to Obsidian vault |
334
+ | `--aliases <names...>` | — | Additional aliases for the asset |
335
+ | `--property <key=value...>` | — | Property key-value pairs (repeatable) |
336
+ | `--body <text>` | — | Markdown body content (use `-` to read from stdin) |
337
+ | `--body-file <path>` | — | Read body content from a file |
338
+ | `--dry-run` | off | Preview the exact file content (stderr) without writing |
339
+ | `--created-by <uuid>` | — | Creator UUID |
340
+ | `--timezone <tz>` | `Asia/Almaty` | Timezone for timestamps |
341
+ | `--skip-wikilink-validation` | off | Skip wikilink existence validation |
342
+ | `--validate` | off | SHACL-lite conformance gate BEFORE writing (refuses a non-conformant asset) |
343
+ | `--use-cache` | off | Cached vault load for `--validate`; the next `--use-cache` process picks the new asset up as a delta (#4264) |
344
+ | `--write-through` | off | With `--use-cache`: fold the created asset into an existing cache in this process (next process = hit); refused without `--use-cache` (#4264) |
345
+
346
+ `--use-cache` governs the two places `create` touches the triple graph: the vault context
347
+ `--validate` loads (through the shared loader — hit / delta / rebuild instead of a full
348
+ parse) and, together with `--write-through`, the write-through of the new asset into an
349
+ EXISTING `.exocortex/cache/triples.json` after a real write (an absent cache is never built
350
+ by `create`; without `--write-through` the next `--use-cache` process picks the asset up as
351
+ a delta). The default `create` path parses no RDF, and SHACL shape loading
352
+ (`ShapeLoader.loadFromVaultFS`) is not covered by the flag.
322
353
 
323
354
  ```bash
324
355
  # With custom properties and body from stdin
@@ -330,6 +361,23 @@ echo "# Content" | npx @kitelev/exocortex-cli create \
330
361
  --vault ~/vault
331
362
  ```
332
363
 
364
+ ### resolve-inline-buttons
365
+
366
+ Print the inline command button-set the plugin would render for an asset — binding-match (Layer A, class hierarchy) ∩ precondition-eval (Layer B). Alias: `resolve-buttons`. The authoritative button-visibility oracle (issue #3833): strictly more complete than `apply <cmd> --dry-run`, which checks the precondition only.
367
+
368
+ ```bash
369
+ npx @kitelev/exocortex-cli resolve-inline-buttons <target> [--json] [--show-hidden] [--use-cache] --vault ~/vault
370
+ ```
371
+
372
+ | Option | Default | Description |
373
+ | ---------------- | ------- | --------------------------------------------------------------------------------------- |
374
+ | `--vault <path>` | cwd | Path to Obsidian vault |
375
+ | `--json` | off | Structured `{target, classes, prototype, visible[], hidden[]}` instead of text |
376
+ | `--show-hidden` | off | Also list commands that bind but are hidden by their precondition |
377
+ | `--use-cache` | off | Load the triple store from the persistent cache (read-only; nothing is written) (#4264) |
378
+
379
+ With `--use-cache` one stderr line names the load mode (`⚡ triple cache: hit` / delta / rebuild); the stdout document is the same as without the flag, except that a cache built by `index` also carries the inferred layer (see `apply --use-cache`).
380
+
333
381
  ### resolve
334
382
 
335
383
  Resolve a UUID (full or partial, minimum 4 hex characters) to a file path. Exits `1` if the UUID is not found.