djournal 0.10.0 → 0.12.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.
@@ -25,16 +25,19 @@ so.
25
25
  djournal uninstall --harness codex
26
26
  djournal uninstall --harness claude-code
27
27
  djournal uninstall --harness pi
28
+ djournal uninstall --harness grok-bot
28
29
  ```
29
30
 
30
31
  ## Uninstall multiple harnesses
31
32
 
32
33
  ```bash
33
- djournal uninstall --harness codex,claude-code,pi
34
+ djournal uninstall --harness codex,claude-code,pi,grok-bot
34
35
  ```
35
36
 
36
37
  Partial uninstall removes only the selected harness integration and keeps the
37
- remaining harnesses installed.
38
+ remaining harnesses installed. For Grok Bot that is the owned `.grokbot/` and
39
+ `integrations/grok-bot/` files. Shared `.agents/` content remains until a full
40
+ uninstall.
38
41
 
39
42
  ## What remains durable
40
43
 
@@ -0,0 +1,50 @@
1
+ # Journal Hub recipe for Grok Bot
2
+
3
+ This directory is the shareable setup recipe for a Journal Hub bot. It is not
4
+ a published Team Bot or public template. Some teams cannot publish public bot
5
+ templates; this recipe is the open-source way to recreate the hub.
6
+
7
+ Install djournal into a project, register the portable journal skills, and
8
+ brief peer engineering bots. The hub does not replace those bots.
9
+
10
+ ## Roles
11
+
12
+ **Journal Hub** installs and explains the journal, registers skills, and
13
+ reconciles shared history. Reconciliation is asynchronous: review `share`,
14
+ `sync`, and conflicts when asked. Do not block peer bots on that review.
15
+
16
+ **Engineering bots** write and resume their own journal entries. They use the
17
+ installed skills and the `djournal` / `journal` CLI against the project root.
18
+ They do not wait for the hub to take a turn before they can journal.
19
+
20
+ Local-only work stays unpublished until a person explicitly shares it. The hub
21
+ does not force publication.
22
+
23
+ ## What the hub sets up
24
+
25
+ 1. Confirm the project root, sync mode, peer engineering bots, and hub display
26
+ name by running [getting-started.md](getting-started.md). Ask one question
27
+ at a time.
28
+ 2. Install the CLI (`npm install -g djournal`, or `npx djournal` for a one-off).
29
+ 3. Run `djournal install --harness grok-bot --target <project-root>`.
30
+ 4. Register each installed `.agents/skills/*/SKILL.md` as a Grok shared
31
+ workflow. Follow [skill-registration.md](skill-registration.md). Rewrite
32
+ paths from the install target. Do not hardcode a machine path, owner, or
33
+ agent id.
34
+ 5. Register [checkup.md](checkup.md) as **Checkup with Journal Hub**.
35
+ 6. Send [peer-briefing.md](peer-briefing.md) to the engineering bots named
36
+ during setup.
37
+
38
+ Grok Bot cannot emit SessionStart or Stop hooks. Do not invent hook files.
39
+ `AGENTS.md`, the skills, and the CLI are the harness.
40
+
41
+ ## Files
42
+
43
+ | File | Use |
44
+ | --- | --- |
45
+ | `getting-started.md` | First-run questions and install steps |
46
+ | `skill-registration.md` | Map package skills to Grok workflow ids |
47
+ | `checkup.md` | Later share/sync/conflict review |
48
+ | `peer-briefing.md` | Short message for engineering bots |
49
+
50
+ Package docs: `docs/grok-bot.md`.
@@ -0,0 +1,41 @@
1
+ ---
2
+ name: Checkup with Journal Hub
3
+ description: Review djournal status, shared work, and sync conflicts for a project without taking over engineering bots or publishing local-only work.
4
+ ---
5
+
6
+ # Checkup with Journal Hub
7
+
8
+ Use this when someone asks the hub to review journal health. Engineering bots
9
+ keep writing their own entries. This checkup is an asynchronous reconcile
10
+ pass.
11
+
12
+ ## Steps
13
+
14
+ 1. If `<project-root>` is not already known, ask for the directory that
15
+ contains `.djournal.json`. Ask only that question, then continue.
16
+ 2. Read status and install health:
17
+
18
+ ```bash
19
+ djournal status --target <project-root>
20
+ djournal doctor --target <project-root>
21
+ djournal work list --target <project-root>
22
+ ```
23
+
24
+ 3. Report which work items are `local_only` and which are shared. Do not run
25
+ `djournal share` unless the operator explicitly chooses a work item to
26
+ publish.
27
+ 4. When sync is enabled, pull the shared projection and report conflicts:
28
+
29
+ ```bash
30
+ djournal pull --target <project-root>
31
+ ```
32
+
33
+ If the command reports conflicts, quote the conflict paths and stop. Do not
34
+ overwrite either side.
35
+ 5. Run `djournal sync --target <project-root>` only for a work item the
36
+ operator has already shared and only when they ask to project it.
37
+ 6. Summarize what peers should do next. Point them at the journal skills and
38
+ `djournal` / `journal` commands. Do not ask them to wait for another hub
39
+ turn before they journal.
40
+
41
+ Hooks are not part of this harness. A missing hook file is healthy.
@@ -0,0 +1,50 @@
1
+ ---
2
+ name: journal-hub-getting-started
3
+ description: Set up djournal for Grok Bot by confirming the project root, sync mode, peer engineering bots, and hub display name, then installing the skill-only harness.
4
+ ---
5
+
6
+ # Journal Hub getting started
7
+
8
+ Run this once when a Journal Hub bot is imported. Ask the questions below one
9
+ at a time. Wait for the answer before asking the next question. Use the
10
+ answers only for this setup. Do not invent project paths, bot names, or a
11
+ display name.
12
+
13
+ ## Questions
14
+
15
+ 1. **Project root.** Which directory should receive the journal install? It
16
+ must be the directory that will contain `.djournal.json` and `.agents/`.
17
+ Call that path `<project-root>` in later commands.
18
+ 2. **Sync mode.** Should shared journal history live in that same repository
19
+ (`colocated`) or in a separate journal repository (`standalone`)? Leave sync
20
+ disabled until the operator asks to turn it on.
21
+ 3. **Engineering bots.** Which peer bots should write journal entries
22
+ themselves? Record display names only. Agent ids are not required.
23
+ 4. **Hub display name.** What should people call this Journal Hub?
24
+
25
+ ## After the answers
26
+
27
+ 1. Install the CLI if it is not already available:
28
+
29
+ ```bash
30
+ npm install -g djournal
31
+ ```
32
+
33
+ Use `npx djournal` when a global install is not appropriate.
34
+
35
+ 2. Install the skill-only harness. This copies rules, skills, `AGENTS.md`, the
36
+ project marker, and this recipe. It does not write hook config.
37
+
38
+ ```bash
39
+ djournal install --harness grok-bot --target <project-root>
40
+ ```
41
+
42
+ 3. Register journal skills from `<project-root>/.agents/skills` using
43
+ `skill-registration.md`. Resolve every rule path from `<project-root>`.
44
+ 4. Register `checkup.md` as the shared workflow **Checkup with Journal Hub**
45
+ (`journal-hub-checkup`).
46
+ 5. Send `peer-briefing.md` to each engineering bot from step 3, with
47
+ `<project-root>` and the hub display name filled in.
48
+
49
+ Do not publish a public bot template as part of this setup. Do not share or
50
+ sync work unless the operator explicitly asks.
@@ -0,0 +1,22 @@
1
+ # Peer engineering bot briefing
2
+
3
+ Send this to each engineering bot named during getting started. Replace the
4
+ angle-bracket fields. Keep the message short.
5
+
6
+ ```text
7
+ <hub-display-name> can help with the project journal, and you can use it
8
+ without waiting for the hub.
9
+
10
+ Project root: <project-root>
11
+ Install (already done when the hub finished setup):
12
+ djournal install --harness grok-bot --target <project-root>
13
+
14
+ Use the journal skills and the djournal / journal CLI against that root.
15
+ Start meaningful work with the journal workflow skill. Resume, plan, research,
16
+ decide, and close entries yourself.
17
+
18
+ <hub-display-name> is an async reconciler. Ask it to run Checkup with Journal
19
+ Hub when you want status, share/sync review, or conflict paths. Local-only
20
+ work stays unpublished until someone explicitly shares it. There are no Grok
21
+ session hooks; skills and the CLI are the integration.
22
+ ```
@@ -0,0 +1,61 @@
1
+ # Register journal skills in Grok Bot
2
+
3
+ Grok Bot loads shared workflows. It does not load `.agents/skills` by itself
4
+ and it has no session hooks. After `djournal install --harness grok-bot`,
5
+ register each installed skill with the harness **UpdateSkill** action.
6
+
7
+ Keep the upstream skill files generic. Rewrite a copy for the payload. Do not
8
+ edit the installed `SKILL.md` files in place, and do not embed a workspace
9
+ path, owner name, or agent id.
10
+
11
+ ## Suggested workflow ids
12
+
13
+ | Installed skill directory | Suggested workflow id |
14
+ | --- | --- |
15
+ | `journal-workflow` | `journal-workflow` |
16
+ | `resume` | `journal-resume` |
17
+ | `init-work` | `journal-init-work` |
18
+ | `switch` | `journal-switch` |
19
+ | `journal` | `journal-entry` |
20
+ | `plan` | `journal-plan` |
21
+ | `recall` | `journal-recall` |
22
+ | `decision` | `journal-decision` |
23
+ | `document` | `journal-document` |
24
+ | `research-codebase` | `journal-research-codebase` |
25
+ | `research-web` | `journal-research-web` |
26
+ | `reinforce` | `journal-reinforce` |
27
+ | `audit` | `journal-audit` |
28
+ | `reconcile` | `journal-reconcile` |
29
+
30
+ Hub-only prose in this recipe is not an upstream skill:
31
+
32
+ | Recipe file | Suggested workflow id | Title |
33
+ | --- | --- | --- |
34
+ | `getting-started.md` | `journal-hub-getting-started` | Journal Hub getting started |
35
+ | `checkup.md` | `journal-hub-checkup` | Checkup with Journal Hub |
36
+
37
+ ## Build an UpdateSkill payload
38
+
39
+ 1. Set `<project-root>` to the install target (the directory that contains
40
+ `.djournal.json` and `.agents/`).
41
+ 2. Read `<project-root>/.agents/skills/<directory>/SKILL.md`.
42
+ 3. Take `name` and `description` from the YAML frontmatter. Use the suggested
43
+ workflow id from the table. Do not invent a project-specific id.
44
+ 4. Rewrite the body into the UpdateSkill payload:
45
+ - Point rule reads at `<project-root>/.agents/rules/...`. Journal root
46
+ resolution stays the procedure in `<project-root>/.agents/rules/STATE.md`:
47
+ use `.djournal.json` in the project root when it exists, otherwise the
48
+ project-local `.journal`.
49
+ - Write CLI examples as `djournal <command> --target <project-root>` or
50
+ `journal <command> --target <project-root>`. Replace `<project-root>` with
51
+ the confirmed install target at registration time.
52
+ - When one skill should point at another, use a Grok sibling link:
53
+ `[Journal workflow](sand-workflow:journal-workflow)`. Use the suggested id
54
+ after `sand-workflow:`.
55
+ 5. Register that id, name, description, and rewritten body with UpdateSkill.
56
+ 6. Repeat for every row, then register the two hub workflows from this
57
+ directory the same way.
58
+
59
+ Re-run this mapping after `djournal upgrade` when skill text changes. The
60
+ portable package files remain the source. The registered workflows are a
61
+ projection for Grok Bot.
@@ -23,12 +23,13 @@ const {
23
23
  } = require("../update-checker.js");
24
24
 
25
25
  const SCHEMA_VERSION = 1;
26
- const SUPPORTED_HARNESSES = ["codex", "claude-code", "pi"];
26
+ const SUPPORTED_HARNESSES = ["codex", "claude-code", "pi", "grok-bot"];
27
27
  const FUTURE_HARNESSES = ["opencode", "zed"];
28
28
  const HARNESS_CONFIG_PATHS = {
29
29
  codex: ".codex/hooks.json",
30
30
  "claude-code": ".claude/settings.json",
31
31
  };
32
+ const GROK_BOT_ASSET_DIRECTORIES = [".grokbot", "integrations/grok-bot"];
32
33
  const MANIFEST_PATH = ".journal/.install/manifest.json";
33
34
  const TRANSACTION_PATH = ".journal/.install/transaction.json";
34
35
  const PROJECT_MARKER_PATH = ".djournal.json";
@@ -288,6 +289,7 @@ function detectHarnesses(target, options = {}) {
288
289
  "claude-code": exists("claude") || fs.existsSync(path.join(target, ".claude")) || fs.existsSync(path.join(target, "CLAUDE.md")),
289
290
  opencode: exists("opencode") || fs.existsSync(path.join(target, ".opencode")) || fs.existsSync(path.join(target, "opencode.json")),
290
291
  pi: exists("pi") || fs.existsSync(path.join(target, ".pi")),
292
+ "grok-bot": fs.existsSync(path.join(target, ".grokbot")),
291
293
  zed: exists("zed") || fs.existsSync(path.join(target, ".zed")),
292
294
  };
293
295
  return {
@@ -299,6 +301,7 @@ function detectHarnesses(target, options = {}) {
299
301
 
300
302
  function normalizeHarness(name) {
301
303
  if (name === "claude") return "claude-code";
304
+ if (name === "grok" || name === "grokbot") return "grok-bot";
302
305
  return name;
303
306
  }
304
307
 
@@ -500,6 +503,16 @@ function harnessFragment(sourceRoot, harness) {
500
503
  return parseJson(fs.readFileSync(path.join(sourceRoot, relative)), relative);
501
504
  }
502
505
 
506
+ function listOwnedAssets(sourceRoot, directory) {
507
+ const absolute = path.join(sourceRoot, directory);
508
+ if (!fs.existsSync(absolute) || !fs.statSync(absolute).isDirectory()) {
509
+ throw new InstallerError(`missing harness assets: ${directory}`, "MISSING_ASSETS");
510
+ }
511
+ const files = listFiles(absolute).map((relative) => `${directory}/${relative}`);
512
+ if (!files.length) throw new InstallerError(`missing harness assets: ${directory}`, "MISSING_ASSETS");
513
+ return files;
514
+ }
515
+
503
516
  function planInstall(sourceRoot, target, harnesses, oldManifest, store) {
504
517
  const old = recordMap(oldManifest);
505
518
  const records = [];
@@ -538,6 +551,14 @@ function planInstall(sourceRoot, target, harnesses, oldManifest, store) {
538
551
  );
539
552
  records.push(extension.record); operations.push(extension.op);
540
553
  }
554
+ if (harnesses.includes("grok-bot")) {
555
+ for (const directory of GROK_BOT_ASSET_DIRECTORIES) {
556
+ for (const relative of listOwnedAssets(sourceRoot, directory)) {
557
+ const result = copyRecord(sourceRoot, target, relative, old.get(relative), "grok-bot");
558
+ records.push(result.record); operations.push(result.op);
559
+ }
560
+ }
561
+ }
541
562
 
542
563
  const desired = new Set(records.map((record) => record.path));
543
564
  for (const record of oldManifest?.files || []) {
@@ -1212,6 +1233,49 @@ function doctor(options) {
1212
1233
  detail: `${assetStatus}; Pi project trust required`,
1213
1234
  });
1214
1235
  }
1236
+ if (loadedManifest?.harnesses?.includes("grok-bot")) {
1237
+ const agentsReady = fs.existsSync(path.join(target, ".agents/rules")) && fs.existsSync(path.join(target, ".agents/skills"));
1238
+ checks.push({
1239
+ name: "grok-bot agents",
1240
+ ok: agentsReady,
1241
+ detail: agentsReady ? ".agents rules and skills present" : "missing .agents rules or skills",
1242
+ });
1243
+ let markerOk = false;
1244
+ let markerDetail = "missing project marker";
1245
+ try {
1246
+ const marker = readProjectMarker(target);
1247
+ markerOk = Boolean(marker?.projectKey && marker?.journalRoot);
1248
+ if (markerOk) markerDetail = "project marker present";
1249
+ } catch (error) {
1250
+ markerDetail = error.message;
1251
+ }
1252
+ checks.push({ name: "grok-bot marker", ok: markerOk, detail: markerDetail });
1253
+ const commandAvailable = options.commandExists || commandExists;
1254
+ const cli = ["djournal", "journal"].find((command) => commandAvailable(command));
1255
+ checks.push({
1256
+ name: "grok-bot cli",
1257
+ ok: true,
1258
+ detail: cli
1259
+ ? `${cli} on PATH; register skills from integrations/grok-bot/skill-registration.md; hooks are not used`
1260
+ : "djournal CLI not on PATH; register skills from integrations/grok-bot/skill-registration.md; hooks are not used",
1261
+ });
1262
+ const owned = loadedManifest.files.filter((item) => item.harness === "grok-bot");
1263
+ const statuses = owned.map((record) => recordStatus(target, record));
1264
+ const assetStatus = owned.length && statuses.every((item) => item === "clean" || item === "modified")
1265
+ ? (statuses.every((item) => item === "clean") ? "clean" : "modified")
1266
+ : "missing";
1267
+ checks.push({
1268
+ name: "grok-bot assets",
1269
+ ok: assetStatus === "clean" || assetStatus === "modified",
1270
+ detail: `${assetStatus}; instruction/skill-only; register skills from integrations/grok-bot/skill-registration.md`,
1271
+ });
1272
+ } else if (detected.evidence["grok-bot"]) {
1273
+ checks.push({
1274
+ name: "grok-bot",
1275
+ ok: true,
1276
+ detail: "marker present; install with djournal install --harness grok-bot. Hooks are not used. See docs/grok-bot.md",
1277
+ });
1278
+ }
1215
1279
  const { inspectSnapshot } = require("../recall/snapshot.js");
1216
1280
  const recallCache = inspectSnapshot(projectContext(target, options), options);
1217
1281
  checks.push({
@@ -0,0 +1,108 @@
1
+ "use strict";
2
+
3
+ const fs = require("node:fs");
4
+ const path = require("node:path");
5
+ const { spawnSync } = require("node:child_process");
6
+ const { InstallerError, projectContext } = require("./installer/index.js");
7
+ const { ENTRY_DIRECTORIES, documentFromDescriptor } = require("./recall/corpus.js");
8
+
9
+ // Reject symlinked components both while listing and immediately before opening.
10
+ function entryPath(root, relative) {
11
+ const parts = relative.split("/");
12
+ if (path.isAbsolute(relative) || parts.some((part) => !part || part === "." || part === ".." || part.includes("\\"))) {
13
+ throw new InstallerError("Entry path must stay inside its work item", "UNSAFE_PATH");
14
+ }
15
+ let file = root;
16
+ for (const part of parts) {
17
+ file = path.join(file, part);
18
+ if (fs.lstatSync(file).isSymbolicLink()) throw new InstallerError("Symbolic links cannot be opened as journal entries", "UNSAFE_PATH");
19
+ }
20
+ return file;
21
+ }
22
+
23
+ function listEntries(options) {
24
+ const context = projectContext(path.resolve(options.target), options);
25
+ if (!options.work || /[/\\]/.test(options.work) || [".", ".."].includes(options.work)) {
26
+ throw new InstallerError("Invalid work item", "INVALID_WORK");
27
+ }
28
+ const root = path.resolve(context.journalRoot);
29
+ const workRelative = `work/${options.work}`;
30
+ entryPath(root, workRelative);
31
+ const records = [];
32
+ function walk(relative, area) {
33
+ const directory = entryPath(root, relative);
34
+ for (const item of fs.readdirSync(directory, { withFileTypes: true })) {
35
+ if (item.isSymbolicLink()) continue;
36
+ const child = `${relative}/${item.name}`;
37
+ if (item.isDirectory()) walk(child, area);
38
+ else if (item.isFile() && path.extname(item.name).toLowerCase() === ".md") {
39
+ const absolute = entryPath(root, child);
40
+ const { document } = documentFromDescriptor({ absolute, relative: child, area, kind: "entry", workSlug: options.work }, new Map(), []);
41
+ const fallback = item.name.match(/^\d{4}-\d{2}-\d{2}/)?.[0] || "";
42
+ const date = Number.isFinite(Date.parse(document.createdAt)) ? document.createdAt : fallback;
43
+ records.push({ root, relative: child, title: document.title, entryType: document.entryType, date });
44
+ }
45
+ }
46
+ }
47
+ for (const area of ENTRY_DIRECTORIES) {
48
+ const relative = `${workRelative}/${area}`;
49
+ try {
50
+ const stat = fs.lstatSync(path.join(root, relative));
51
+ if (stat.isDirectory() && !stat.isSymbolicLink()) walk(relative, area);
52
+ } catch (error) { if (error.code !== "ENOENT") throw error; }
53
+ }
54
+ return records.sort((a, b) => b.date.localeCompare(a.date) || b.relative.localeCompare(a.relative));
55
+ }
56
+
57
+ // Parse an executable and arguments, not a shell program. Keep filename data
58
+ // out of shell evaluation, including spaces, quotes, and command substitutions.
59
+ function editorArgs(command) {
60
+ const args = [];
61
+ let word = "", quote = "", started = false;
62
+ for (let i = 0; i < command.length; i += 1) {
63
+ const char = command[i];
64
+ if (char === "\\" && quote !== "'" && i + 1 < command.length &&
65
+ (/[\s\\'"]/.test(command[i + 1]))) {
66
+ word += command[++i]; started = true;
67
+ } else if (quote) {
68
+ if (char === quote) quote = "";
69
+ else word += char;
70
+ } else if (char === "'" || char === '"') {
71
+ quote = char; started = true;
72
+ } else if (/\s/.test(char)) {
73
+ if (started) { args.push(word); word = ""; started = false; }
74
+ } else { word += char; started = true; }
75
+ }
76
+ if (quote) throw new InstallerError("Unclosed quote in VISUAL or EDITOR", "EDITOR_CONFIG");
77
+ if (started) args.push(word);
78
+ if (!args[0]) throw new InstallerError("Set VISUAL or EDITOR to a terminal editor command", "EDITOR_CONFIG");
79
+ return args;
80
+ }
81
+
82
+ function openEntry(entry, options = {}) {
83
+ const file = entryPath(entry.root, entry.relative);
84
+ if (!fs.statSync(file).isFile()) throw new InstallerError("Journal entry is no longer a regular file", "INVALID_ENTRY");
85
+ const env = options.env || process.env;
86
+ const command = env.VISUAL?.trim() || env.EDITOR?.trim() || (process.platform === "win32" ? "notepad" : "vi");
87
+ const [bin, ...args] = editorArgs(command);
88
+ const result = (options.spawnSync || spawnSync)(bin, [...args, file], { stdio: "inherit", cwd: options.cwd, env, shell: false });
89
+ if (result.error) throw new InstallerError(`Cannot start editor ${bin}: ${result.error.message}. Check VISUAL or EDITOR.`, "EDITOR_ERROR");
90
+ if (result.status !== 0) throw new InstallerError(`Editor ${bin} exited with ${result.signal || result.status}.`, "EDITOR_ERROR");
91
+ }
92
+
93
+ function recallEntry(result, options) {
94
+ if (typeof result.path !== "string" || !result.path.startsWith(".journal/work/")) {
95
+ throw new InstallerError("Recall result is not a canonical journal path", "UNSAFE_PATH");
96
+ }
97
+ const relative = result.path.slice(".journal/".length);
98
+ const parts = relative.split("/");
99
+ if (parts[1] !== result.workSlug || path.extname(relative).toLowerCase() !== ".md" ||
100
+ !(parts.length === 3 && parts[2] === "work.md" || parts.length >= 4 && ENTRY_DIRECTORIES.includes(parts[2]))) {
101
+ throw new InstallerError("Recall result is not a journal entry or work file", "UNSAFE_PATH");
102
+ }
103
+ const root = path.resolve(projectContext(path.resolve(options.target), options).journalRoot);
104
+ entryPath(root, relative);
105
+ return { root, relative };
106
+ }
107
+
108
+ module.exports = { listEntries, openEntry, recallEntry };
@@ -0,0 +1,72 @@
1
+ "use strict";
2
+
3
+ const { createPrompt, useState, useKeypress, usePagination } = require("@inquirer/core");
4
+
5
+ function filterFields(workItems = []) {
6
+ const values = (items) => [[undefined, "Any"], ...items.map((value) => [value, value.replaceAll("_", " ")])];
7
+ return [
8
+ { key: "work", label: "Work", values: [[undefined, "All work"], ...workItems.map((work) => [work.slug, work.title])], help: "Restrict results to a work item." },
9
+ { key: "kind", label: "Kind", values: values(["work", "entry"]), help: "Search work descriptions, entries, or both." },
10
+ { key: "type", label: "Entry type", values: values(["plan", "implementation", "status", "manual", "research", "doc", "decision"]), help: "Applies to entries; work descriptions have no entry type." },
11
+ { key: "status", label: "Work status", values: values(["draft", "active", "paused", "completed", "archived"]), help: "Include work items with this status." },
12
+ { key: "visibility", label: "Visibility", values: values(["local_only", "private_synced", "team_shared"]), help: "Restrict results by work visibility." },
13
+ { key: "limit", label: "Result limit", help: "Type a number from 1 to 100, or use Left/Right. Limit is per result kind." },
14
+ ];
15
+ }
16
+
17
+ function filterSummary(filters) {
18
+ const labels = { work: "Work", kind: "Kind", type: "Type", status: "Status", visibility: "Visibility" };
19
+ const scope = Object.entries(labels).filter(([key]) => filters[key])
20
+ .map(([key, label]) => `${label}: ${filters[key]}`);
21
+ return [...(scope.length ? scope : ["All work / all types"]), `Limit: ${filters.limit}`].join(" | ");
22
+ }
23
+
24
+ const filterPrompt = createPrompt((config, done) => {
25
+ const [draft, setDraft] = useState({ ...config.filters });
26
+ const [active, setActive] = useState(0);
27
+ const [digits, setDigits] = useState(null);
28
+ const [error, setError] = useState("");
29
+ const { fields, theme } = config;
30
+ const field = fields[active];
31
+ const validLimit = digits === null || (Number(digits) >= 1 && Number(digits) <= 100);
32
+ useKeypress((key, rl) => {
33
+ rl.clearLine(0);
34
+ if (key.ctrl && key.name === "r") {
35
+ setDraft({ limit: 10 }); setDigits(null); setError("");
36
+ } else if (key.name === "up" || key.name === "down") {
37
+ if (!validLimit) { setError("Enter a limit from 1 to 100."); return; }
38
+ setActive((active + (key.name === "up" ? -1 : 1) + fields.length) % fields.length);
39
+ setDigits(null); setError("");
40
+ } else if (key.name === "left" || key.name === "right") {
41
+ const offset = key.name === "left" ? -1 : 1;
42
+ const next = { ...draft };
43
+ if (field.key === "limit") next.limit = Math.max(1, Math.min(100, draft.limit + offset));
44
+ else {
45
+ const index = Math.max(0, field.values.findIndex(([value]) => value === draft[field.key]));
46
+ const [value] = field.values[(index + offset + field.values.length) % field.values.length];
47
+ if (value === undefined) delete next[field.key]; else next[field.key] = value;
48
+ }
49
+ setDraft(next); setDigits(null); setError("");
50
+ } else if (field.key === "limit" && (/^[0-9]$/.test(key.sequence) || key.name === "backspace")) {
51
+ const text = key.name === "backspace" ? (digits ?? String(draft.limit)).slice(0, -1) : (digits ?? "") + key.sequence;
52
+ setDigits(text); setError(Number(text) < 1 || Number(text) > 100 ? "Limit must be between 1 and 100." : "");
53
+ if (Number(text) >= 1 && Number(text) <= 100) setDraft({ ...draft, limit: Number(text) });
54
+ } else if (key.name === "enter" || key.name === "return") {
55
+ if (!validLimit) setError("Enter a limit from 1 to 100.");
56
+ else done(draft);
57
+ }
58
+ });
59
+ const valueOf = (item) => item.key === "limit" ? (digits ?? String(draft.limit))
60
+ : item.values.find(([value]) => value === draft[item.key])?.[1] || draft[item.key] || "Any";
61
+ const page = usePagination({
62
+ items: fields, active, pageSize: Math.min(fields.length, config.pageSize), loop: true,
63
+ renderItem: ({ item, isActive }) => {
64
+ const text = theme.style.line(`${isActive ? ">" : " "} ${item.label.padEnd(12)} ${isActive ? "< " : " "}${valueOf(item)}${isActive ? " >" : ""}`);
65
+ return isActive ? theme.style.highlight(text) : text;
66
+ },
67
+ });
68
+ return [theme.style.message(config.message).trimEnd(), [page,
69
+ error ? theme.style.detail(`Error: ${error}`) : theme.style.detail(`${valueOf(field)} — ${field.help}`)].join("\n")];
70
+ });
71
+
72
+ module.exports = { filterFields, filterSummary, filterPrompt };
@@ -0,0 +1,87 @@
1
+ "use strict";
2
+
3
+ const { createPrompt, useState, useRef, useEffect, useKeypress, usePagination } = require("@inquirer/core");
4
+
5
+ const DEBOUNCE_MS = 250;
6
+
7
+ // Own the query and result lifecycle so returning from filters or an editor can
8
+ // restore the input, and Enter can never select results for an earlier query.
9
+ const searchPrompt = createPrompt((config, done) => {
10
+ const [query, setQuery] = useState(config.query || "");
11
+ const [result, setResult] = useState({ choices: [], message: "" });
12
+ const [status, setStatus] = useState(query.trim() ? "waiting" : "idle");
13
+ const [error, setError] = useState("");
14
+ const [active, setActive] = useState(0);
15
+ const request = useRef();
16
+ const { theme } = config;
17
+
18
+ useEffect((rl) => { if (config.query) rl.write(config.query); }, []);
19
+ useEffect(() => {
20
+ const controller = new AbortController();
21
+ request.current = controller;
22
+ if (!query.trim()) return () => controller.abort();
23
+ const timer = setTimeout(async () => {
24
+ setStatus("loading");
25
+ try {
26
+ const next = await config.source(query.trim(), { signal: controller.signal });
27
+ if (controller.signal.aborted) return;
28
+ setResult(next);
29
+ setActive(0);
30
+ setStatus("idle");
31
+ } catch (failure) {
32
+ if (controller.signal.aborted) return;
33
+ setResult({ choices: [], message: "" });
34
+ setError(failure.message || String(failure));
35
+ setStatus("idle");
36
+ }
37
+ }, DEBOUNCE_MS);
38
+ return () => { clearTimeout(timer); controller.abort(); };
39
+ }, [query]);
40
+
41
+ const ready = status === "idle";
42
+ const choices = result.choices;
43
+ const selected = ready ? choices[active] : undefined;
44
+ useKeypress((key, rl) => {
45
+ if (key.name === "tab") {
46
+ request.current?.abort();
47
+ done({ value: "filters", query });
48
+ } else if (key.name === "enter" || key.name === "return") {
49
+ if (ready && selected) done({ value: selected.value, query });
50
+ else rl.write(query); // Readline clears its input on Enter.
51
+ } else if (key.name === "up" || key.name === "down") {
52
+ // Readline history navigation must not replace the editable query.
53
+ rl.line = query;
54
+ rl.cursor = query.length;
55
+ if (ready) setActive(Math.max(0, Math.min(choices.length - 1, active + (key.name === "up" ? -1 : 1))));
56
+ } else if (rl.line !== query) {
57
+ // Invalidate synchronously, before a promise or another key can complete.
58
+ request.current?.abort();
59
+ if (!rl.line.trim()) setResult({ choices: [], message: "" });
60
+ setError("");
61
+ setActive(0);
62
+ setStatus(rl.line.trim() ? "waiting" : "idle");
63
+ setQuery(rl.line);
64
+ }
65
+ });
66
+
67
+ const page = usePagination({
68
+ items: choices, active, pageSize: config.pageSize, loop: false,
69
+ renderItem: ({ item, isActive }) => {
70
+ const text = ` ${isActive ? theme.icon.cursor : " "} ${item.name}`;
71
+ return !ready ? theme.style.disabled(text) : isActive ? theme.style.highlight(text) : text;
72
+ },
73
+ });
74
+ const message = !ready ? "Updating results..."
75
+ : result.message || "Type to search the journal.";
76
+ const padded = (text, lines) => [...text.split("\n"), ...Array(lines).fill(" ")].slice(0, lines).join("\n");
77
+ const position = ready && choices.length ? `${active + 1}/${choices.length} ` : "";
78
+ return [
79
+ `${theme.style.message(config.message)} > ${theme.style.answer(query)}`,
80
+ [theme.style.line(config.scope),
81
+ padded(theme.style.detail(error ? `Error: ${error}` : position + message), 2),
82
+ padded(page, config.pageSize),
83
+ padded(selected?.description ? theme.style.detail(selected.description) : " ", 2)].join("\n"),
84
+ ];
85
+ });
86
+
87
+ module.exports = { searchPrompt, DEBOUNCE_MS };