@ghostpaw/questlog 0.9.2 → 0.10.1

package/dist/open_questlog_db-LAEH7UDM.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export { openQuestlogDb } from './chunk-ZHTX64KD.js';

package/dist/{questlog_skill_spec-EM6DGGVN.js → questlog_skill_spec-HEW2B6EB.js}

@@ -1,7 +1,8 @@
 #!/usr/bin/env node
 import { questlogMcpInstructions } from './chunk-SVWAEAKC.js';
-import { questlogSkills } from './chunk-6KTQK3ZE.js';
-import { reviewQuestlogTool, questlogSurfaceTools } from './chunk-UTUQPSGO.js';
+import { questlogSkills } from './chunk-D2W5MYNO.js';
+import { reviewQuestlogTool, questlogSurfaceTools } from './chunk-55JAQORX.js';
+import './chunk-N7V7VUI5.js';
 import './chunk-QYSIJ2YN.js';
 
 // src/soul.ts
@@ -57,7 +58,8 @@ var questlogSkillSpec = {
     "- Use `--json` on any plain command.",
     "- Exit codes: 0 ok / 1 error / 2 usage / 3 needs input.",
     "- Database: `~/.ghostpaw/questlog.db`; override with `--db` or `GHOSTPAW_QUESTLOG_DB`.",
-    "- Use one database per agent or project."
+    "- Use one database per agent or project.",
+    "- Webhooks: `questlog hook add <url>`, `questlog tick --dry-run`, `questlog watch`. Read `questlog skill webhooks` for events, signing, verification, and cron setup."
   ].join("\n"),
   description: "Use the release binary ghostpaw-questlog to manage local tasks, calendar commitments, and recurring work. Use when planning, executing, reviewing, or organizing work.",
   license: "MIT",

package/dist/run_hook_command-C42BQC36.js

@@ -0,0 +1,95 @@
+#!/usr/bin/env node
+import { parseCliArgs } from './chunk-GVD6A3RR.js';
+import { watchQuestlog, testHook, removeHook, hookLabel, listHooks, addHook } from './chunk-N7V7VUI5.js';
+
+// src/surface/run_hook_command.ts
+async function runHookCommand(command, args, io, open) {
+  let db;
+  try {
+    if (args.includes("--help") || args.includes("-h")) {
+      io.stdout.write(
+        "questlog hook add <url> [--tag name] [--events types] [--min-gap seconds] [--secret-stdin] [--json]\nquestlog hook list|remove <id>|test <id>|label [name]\nquestlog watch [--interval seconds] [--json]\n"
+      );
+      return 0;
+    }
+    const action = command === "watch" ? "watch" : args.shift();
+    if (!["add", "list", "remove", "test", "label", "watch"].includes(action ?? ""))
+      throw new Error("Expected hook add, list, remove, test, or label");
+    const values = parseCliArgs(args, {
+      command,
+      flags: [
+        { name: "json", type: "boolean" },
+        ...action === "add" ? [
+          { name: "tag", type: "string" },
+          { name: "events", type: "string" },
+          { name: "min-gap", type: "integer" },
+          { name: "secret-stdin", type: "boolean" }
+        ] : action === "watch" ? [{ name: "interval", type: "number" }] : []
+      ],
+      positionals: action === "add" ? [{ name: "url", type: "string", required: true }] : ["remove", "test"].includes(action ?? "") ? [{ name: "id", type: "integer", required: true }] : action === "label" ? [{ name: "name", type: "string" }] : []
+    });
+    if (action === "watch" && values.interval !== void 0 && Number(values.interval) < 5)
+      throw new Error("Interval must be at least 5 seconds");
+    db = await open();
+    let result;
+    switch (action) {
+      case "add": {
+        let secret;
+        if (values.secretStdin) {
+          secret = "";
+          for await (const chunk of io.stdin) secret += String(chunk);
+          secret = secret.replace(/\r?\n$/, "");
+        }
+        result = addHook(db, {
+          url: String(values.url),
+          ...values.tag === void 0 ? {} : { tag: String(values.tag) },
+          ...values.events === void 0 ? {} : { events: String(values.events).split(",") },
+          ...values.minGap === void 0 ? {} : { minGap: Number(values.minGap) },
+          ...secret === void 0 ? {} : { secret }
+        });
+        break;
+      }
+      case "list":
+        result = listHooks(db);
+        break;
+      case "label":
+        result = { label: hookLabel(db, values.name) };
+        break;
+      case "remove":
+        removeHook(db, Number(values.id));
+        result = { removed: Number(values.id) };
+        break;
+      case "test":
+        result = await testHook(db, Number(values.id));
+        break;
+      case "watch": {
+        const controller = new AbortController();
+        const stop = () => controller.abort();
+        process.on("SIGINT", stop);
+        process.on("SIGTERM", stop);
+        try {
+          await watchQuestlog(db, {
+            signal: controller.signal,
+            interval: Number(values.interval ?? 60),
+            onTick: (tick) => io.stdout.write(`${JSON.stringify(tick)}
+`)
+          });
+        } finally {
+          process.off("SIGINT", stop);
+          process.off("SIGTERM", stop);
+        }
+        return 0;
+      }
+    }
+    io.stdout.write(`${JSON.stringify(result, null, 2)}
+`);
+    return 0;
+  } catch {
+    io.stderr.write("Invalid webhook command or unavailable target. Run questlog hook --help.\n");
+    return 2;
+  } finally {
+    db?.close();
+  }
+}
+
+export { runHookCommand };

package/dist/{serve_questlog_mcp-KFUYJB2P.js → serve_questlog_mcp-W3R63HW4.js}

@@ -1,8 +1,9 @@
 #!/usr/bin/env node
-import { openQuestlogDb } from './chunk-3B6FMHZU.js';
+import { openQuestlogDb } from './chunk-ZHTX64KD.js';
 import { questlogMcpInstructions } from './chunk-SVWAEAKC.js';
-import { isErrorResult, questlogVersion, resolveQuestlogDbPath } from './chunk-DKH623HU.js';
-import { validateInput, questlogSurfaceTools } from './chunk-UTUQPSGO.js';
+import { isErrorResult, resolveQuestlogDbPath } from './chunk-IL2QRKZL.js';
+import { validateInput, questlogSurfaceTools } from './chunk-55JAQORX.js';
+import { questlogVersion } from './chunk-N7V7VUI5.js';
 import { minimalInput } from './chunk-QYSIJ2YN.js';
 
 // src/surfaces/mcp_server.ts

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@ghostpaw/questlog",
-	"version": "0.9.2",
+	"version": "0.10.1",
 	"description": "Unified task and calendar model for Node.js — SQLite, zero dependencies, with a built-in LLM tool facade",
 	"type": "module",
 	"exports": {

package/skills/questlog/SKILL.md

@@ -29,7 +29,7 @@ Run tools as `ghostpaw-questlog ...`; use `~/.local/bin/ghostpaw-questlog` if it
 
 - `questlog search <words>` before `add` to avoid duplicates.
 - `ghostpaw-questlog add "..." --tag a,b --due tomorrow`
-- `questlog list [--view <view>]`: questlines, quests.active, quests.available, quests.blocked, quests.deferred, quests.due_soon, quests.in_progress, quests.missed_scheduled, quests.open, quests.overdue, quests.resolved, quests.scheduled_for_day, quests.scheduled_now, repeatables.due_anchors, rumors.
+- `questlog list [--view <view>]`: deliveries, questlines, quests.active, quests.available, quests.blocked, quests.deferred, quests.due_soon, quests.in_progress, quests.missed_scheduled, quests.open, quests.overdue, quests.resolved, quests.scheduled_for_day, quests.scheduled_now, repeatables.due_anchors, rumors.
 - `questlog done <id> --outcome "..."`
 - `questlog search <words>`
 - `questlog show <id>`
@@ -37,6 +37,7 @@ Run tools as `ghostpaw-questlog ...`; use `~/.local/bin/ghostpaw-questlog` if it
 - Exit codes: 0 ok / 1 error / 2 usage / 3 needs input.
 - Database: `~/.ghostpaw/questlog.db`; override with `--db` or `GHOSTPAW_QUESTLOG_DB`.
 - Use one database per agent or project.
+- Webhooks: `questlog hook add <url>`, `questlog tick --dry-run`, `questlog watch`. Read `questlog skill webhooks` for events, signing, verification, and cron setup.
 
 ## Appendix: MCP and tool calls
 
@@ -50,6 +51,28 @@ CLI: `ghostpaw-questlog call <tool> '<JSON object>'` or `ghostpaw-questlog <tool
 
 Inspect schemas with `ghostpaw-questlog describe <tool>`. Use `--db <path>` to select a database.
 
+### manage_hooks
+
+List or remove outbound webhook targets, run a tick, or inspect pending and failed deliveries.
+
+Use when: Use to operate configured outbound webhooks. Add and test targets with the CLI.
+
+Not for: Use quest tools to change work itself.
+
+Writes: writes_state.
+
+| Parameter | Type | Required | Values / description |
+| --- | --- | --- | --- |
+| action | string | yes | list, remove, tick, deliveries. Operation. |
+| id | integer | no | Target id. |
+| dry_run | boolean | no | Preview only. |
+
+```sh
+ghostpaw-questlog call manage_hooks '{"action":"list"}'
+ghostpaw-questlog call manage_hooks '{"action":"remove","id":1}'
+ghostpaw-questlog call manage_hooks '{"action":"tick"}'
+```
+
 ### search_questlog
 
 Search quests and rumors by text when you need to find an existing item before inspecting or changing it.
@@ -83,7 +106,7 @@ Read-only.
 
 | Parameter | Type | Required | Values / description |
 | --- | --- | --- | --- |
-| view | string | yes | questlines, quests.active, quests.available, quests.blocked, quests.deferred, quests.due_soon, quests.in_progress, quests.missed_scheduled, quests.open, quests.overdue, quests.resolved, quests.scheduled_for_day, quests.scheduled_now, repeatables.due_anchors, rumors. Which operational review surface to return. |
+| view | string | yes | deliveries, questlines, quests.active, quests.available, quests.blocked, quests.deferred, quests.due_soon, quests.in_progress, quests.missed_scheduled, quests.open, quests.overdue, quests.resolved, quests.scheduled_for_day, quests.scheduled_now, repeatables.due_anchors, rumors. Which operational review surface to return. |
 | filters | object | no | Optional filters for supported review surfaces. |
 | filters.questlineId | integer | no | Optional questline id used by quest views. |
 | filters.tagNames | array | no | Optional tag names used by quest views. |
@@ -92,7 +115,7 @@ Read-only.
 | now | integer | no | Optional evaluation timestamp for time-sensitive views. |
 
 ```sh
-ghostpaw-questlog call review_questlog '{"view":"questlines"}'
+ghostpaw-questlog call review_questlog '{"view":"deliveries"}'
 ```
 
 ### inspect_questlog_item
@@ -376,6 +399,7 @@ ghostpaw-questlog call retire_work '{"action":"hide","target":{"kind":"quest","i
 
 ### Workflow guides
 
+- `ghostpaw-questlog skill webhooks` ([webhooks](references/webhooks.md)): Configure signed outbound event webhooks and verify deliveries.
 - `ghostpaw-questlog skill archive-delete-and-prune` ([archive-delete-and-prune](references/archive-delete-and-prune.md)): Choose the right retirement action for each kind of work so history stays honest and hiding does not get confused with archival or terminal execution truth.
 - `ghostpaw-questlog skill choose-work-shape` ([choose-work-shape](references/choose-work-shape.md)): Choose the right structure for new work by separating uncertainty, one-shot execution, multi-step arcs, and recurring patterns.
 - `ghostpaw-questlog skill clarify-ambiguous-requests` ([clarify-ambiguous-requests](references/clarify-ambiguous-requests.md)): Treat ambiguity as a real state, capture uncertainty honestly, and only commit work structure once the next executable shape is clear.

package/skills/questlog/references/webhooks.md

@@ -0,0 +1,91 @@
+# Webhooks
+
+Use `questlog` to configure opt-in outbound automation. No server or scheduler is added.
+No targets means no network calls. `manage_hooks` supports list, remove, tick with
+`dry_run`, and deliveries; add/test are CLI-only. `review_questlog` view `deliveries`
+and `questlog show <id>` expose pending/failed deliveries.
+
+```sh
+questlog hook add https://example.org/wake --min-gap 60
+questlog hook add https://example.org/team --tag work --events quest.due,quest.overdue --secret-stdin
+questlog hook label work
+questlog hook list
+questlog tick --dry-run
+questlog tick
+questlog watch --interval 60
+questlog hook test 1
+questlog review deliveries
+questlog show 12
+questlog hook remove 1
+```
+
+`hook add` prints its random 32-byte signing secret once, also as `secret` in `--json`.
+Save it securely. `--secret-stdin` supplies one via stdin; there is no secret flag.
+List output redacts userinfo/query strings. Removal deletes the target and deliveries.
+Default scope is the database; `--tag` matches quest tags, never rumors.
+`--events` defaults to all types. The DB label defaults to the filename without its
+path/extension (`questlog` in memory); set it to a name suitable for disclosure.
+
+```cron
+* * * * * questlog tick
+```
+
+Cron's PATH may need `$HOME/.local/bin/questlog tick --db /path/to/quests.db`.
+Watch defaults to 60 seconds (minimum 5); SIGINT/SIGTERM finishes the current tick.
+Tick exits 0 even when deliveries need retries. Dry-run records nothing and sends nothing.
+
+Events are detected from the model at tick time:
+
+- `quest.due`: an unresolved, undeleted quest reaches its effective due time (own `due_at`, otherwise its undeleted questline's due time).
+- `quest.overdue`: that effective deadline is strictly earlier than now and the quest remains unresolved.
+- `quest.unblocked`: an unresolved quest is available, all active prerequisites have succeeded or been deleted, and at least one prerequisite succeeded after its unlock was installed. Occurrence time is the latest active prerequisite success or not-before time, whichever is later.
+- `repeatable.spawned`: a concrete repeatable instance was created; occurrence time is its creation time. Tick first materializes due anchors through the existing spawn operation.
+- `rumor.captured`: an undeleted rumor was created; occurrence time is its creation time, even if subsequently settled or dismissed.
+
+Persistent event keys contain type, entity ids, and occurrence time. Restarts and repeated
+ticks do not repeat occurrences. Removed transitions between ticks cannot be reconstructed.
+Only occurrences at/after target creation are assigned; tags are evaluated at assignment.
+Tick materializes due repeatables using the existing spawn path, including during preview
+with rollback. Batches contain only ids, event types, timestamps, and the DB label:
+
+```json
+{"type":"questlog.events","db":"work","deliveryId":"d_…","sentAt":"2026-10-28T10:00:00.000Z","events":[{"id":"e_…","type":"quest.due","questId":12,"occurredAt":"2026-10-28T09:59:00.000Z"}]}
+```
+
+Headers are `content-type: application/json`, `user-agent: questlog/<version>`,
+`x-questlog-delivery: <deliveryId>`, `x-questlog-timestamp: <unix seconds>`, and
+`x-questlog-signature: sha256=<hex HMAC-SHA256(secret, timestamp + "." + rawBody)>`.
+No titles, objectives, details, or tag text are sent. `hook test` sends a logged `hook.test`
+event immediately, ignoring the min gap. Add and test are CLI-only in the tool facade;
+`manage_hooks` supports list, remove, tick (with `dry_run`), and deliveries.
+
+2xx delivers. Timeout is 5 seconds. Failures retry after 30 s, 1 m, 2 m, 4 m, doubling
+to 1 h plus <1 s jitter, subject to the target's min gap. Eight failures mark failed.
+Retries keep the delivery id/events; new events queue behind them. Keep the last 500
+delivered log entries per target and all pending/failed entries. Transactional claims
+lease work for two minutes. A crash after receipt may retry: dedupe at the receiver.
+
+### Verifying a delivery
+
+Compute HMAC-SHA256 over `timestamp + "." + rawBody` with the secret and compare in constant
+time. Reject timestamps older than 5 minutes (and timestamps too far in the future), then
+dedupe on `x-questlog-delivery`. Use durable deduplication storage in a production receiver.
+This 15-line Node example uses an in-memory set:
+
+```js
+import { createHmac, timingSafeEqual } from 'node:crypto';
+import { createServer } from 'node:http';
+const secret = process.env.WEBHOOK_SECRET, seen = new Set();
+createServer(async (req, res) => {
+  const chunks = []; for await (const chunk of req) chunks.push(chunk);
+  const rawBody = Buffer.concat(chunks), h = req.headers;
+  const timestamp = h['x-questlog-timestamp'], id = h['x-questlog-delivery'];
+  const age = Date.now() / 1000 - Number(timestamp);
+  const expected = createHmac('sha256', secret).update(timestamp + '.').update(rawBody).digest();
+  const signature = String(h['x-questlog-signature'] || '');
+  const actual = Buffer.from(signature.slice(7), 'hex');
+  if (!id || !/^\d+$/.test(timestamp) || age > 300 || age < -300 || !/^sha256=[a-f0-9]{64}$/.test(signature) || actual.length !== expected.length || !timingSafeEqual(actual, expected)) { res.writeHead(401).end(); return; }
+  if (!seen.has(id)) { seen.add(id); console.log(JSON.parse(rawBody)); }
+  res.writeHead(204).end();
+}).listen(8080, '127.0.0.1');
+```

package/dist/open_questlog_db-SH3DAU4C.js

@@ -1,2 +0,0 @@
-#!/usr/bin/env node
-export { openQuestlogDb } from './chunk-3B6FMHZU.js';