@ghostpaw/questlog 0.8.0 → 0.9.1

package/dist/serve_questlog_mcp-QSHMNNFT.js

@@ -0,0 +1,212 @@
+#!/usr/bin/env node
+import { openQuestlogDb } from './chunk-3B6FMHZU.js';
+import { questlogMcpInstructions } from './chunk-SVWAEAKC.js';
+import { validateInput, isErrorResult, questlogVersion, resolveQuestlogDbPath } from './chunk-KRQDV4KF.js';
+import { questlogSurfaceTools } from './chunk-3Y5F3SMB.js';
+
+// src/surfaces/mcp_server.ts
+var MCP_LATEST_PROTOCOL_VERSION = "2026-07-28";
+var MCP_SUPPORTED_PROTOCOL_VERSIONS = [
+  MCP_LATEST_PROTOCOL_VERSION,
+  "2025-11-25",
+  "2025-06-18",
+  "2025-03-26",
+  "2024-11-05"
+];
+function createMcpServer(options) {
+  let initialized = false;
+  let context;
+  const serverInfo = { name: options.name, version: options.version };
+  const record = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+  const error = (id, code, message, data) => ({
+    jsonrpc: "2.0",
+    id,
+    error: { code, message, ...data === void 0 ? {} : { data } }
+  });
+  const handleMessage = async (msg) => {
+    if (!record(msg) || msg.jsonrpc !== "2.0" || typeof msg.method !== "string" || Object.hasOwn(msg, "id") && msg.id !== null && typeof msg.id !== "string" && typeof msg.id !== "number")
+      return error(null, -32600, "Invalid Request");
+    if (!Object.hasOwn(msg, "id")) return void 0;
+    const id = msg.id;
+    if (msg.params !== void 0 && !record(msg.params)) return error(id, -32602, "Invalid params");
+    const params = record(msg.params) ? msg.params : {};
+    const meta = record(params._meta) ? params._meta : {};
+    const requested = meta["io.modelcontextprotocol/protocolVersion"];
+    const modern = requested !== void 0;
+    if (modern && !MCP_SUPPORTED_PROTOCOL_VERSIONS.includes(
+      requested
+    ))
+      return error(id, -32022, "Unsupported protocol version", {
+        supported: [...MCP_SUPPORTED_PROTOCOL_VERSIONS],
+        requested
+      });
+    const result = (value) => ({
+      jsonrpc: "2.0",
+      id,
+      result: modern ? {
+        ...value,
+        resultType: "complete",
+        _meta: { "io.modelcontextprotocol/serverInfo": serverInfo }
+      } : value
+    });
+    if (!modern && msg.method === "initialize") {
+      initialized = true;
+      const version = MCP_SUPPORTED_PROTOCOL_VERSIONS.slice(1).find((v) => v === params.protocolVersion) ?? "2025-11-25";
+      return result({
+        protocolVersion: version,
+        capabilities: { tools: { listChanged: false } },
+        serverInfo: { ...serverInfo, ...options.title ? { title: options.title } : {} },
+        ...options.instructions ? { instructions: options.instructions } : {}
+      });
+    }
+    if (!modern && !initialized)
+      return error(
+        id,
+        -32602,
+        `Protocol version required. Supported versions: ${MCP_SUPPORTED_PROTOCOL_VERSIONS.join(", ")}`
+      );
+    if (modern && !record(meta["io.modelcontextprotocol/clientCapabilities"]))
+      return error(id, -32602, "clientCapabilities must be an object");
+    switch (msg.method) {
+      case "ping":
+        return result({});
+      case "server/discover":
+        return result({
+          supportedVersions: [...MCP_SUPPORTED_PROTOCOL_VERSIONS],
+          capabilities: { tools: {} },
+          ...options.instructions ? { instructions: options.instructions } : {},
+          ttlMs: 6e4,
+          cacheScope: "public"
+        });
+      case "tools/list":
+        return result({
+          tools: options.tools.map((tool) => ({
+            name: tool.name,
+            ...tool.title ? { title: tool.title } : {},
+            description: tool.description + (tool.whenToUse ? `
+
+Use when: ${tool.whenToUse}` : "") + (tool.whenNotToUse ? `
+Not for: ${tool.whenNotToUse}` : ""),
+            inputSchema: tool.inputSchema,
+            annotations: options.annotations?.(tool) ?? {
+              readOnlyHint: tool.readOnly ?? false,
+              destructiveHint: !tool.readOnly,
+              idempotentHint: tool.readOnly ?? false,
+              openWorldHint: false
+            }
+          })),
+          ...modern ? { ttlMs: 6e4, cacheScope: "public" } : {}
+        });
+      case "tools/call": {
+        const tool = options.tools.find((tool2) => tool2.name === params.name);
+        if (!tool) return error(id, -32602, `Unknown tool: ${String(params.name)}`);
+        const input = params.arguments === void 0 ? {} : params.arguments;
+        const errors = validateInput(tool.inputSchema, input);
+        if (errors.length)
+          return result({ content: [{ type: "text", text: errors.join("\n") }], isError: true });
+        try {
+          context ??= Promise.resolve().then(options.context);
+          const value = await tool.handler(await context, input);
+          return result({
+            content: [{ type: "text", text: JSON.stringify(value) ?? "null" }],
+            ...record(value) ? { structuredContent: value } : {},
+            isError: (options.isErrorResult ?? isErrorResult)(value)
+          });
+        } catch (cause) {
+          return result({
+            content: [
+              { type: "text", text: cause instanceof Error ? cause.message : String(cause) }
+            ],
+            isError: true
+          });
+        }
+      }
+      default:
+        return error(id, -32601, "Method not found");
+    }
+  };
+  return {
+    handleMessage,
+    async handleLine(line) {
+      let msg;
+      try {
+        msg = JSON.parse(line);
+      } catch {
+        return JSON.stringify(error(null, -32700, "Parse error"));
+      }
+      const response = await handleMessage(msg);
+      return response === void 0 ? void 0 : JSON.stringify(response);
+    }
+  };
+}
+
+// src/surfaces/mcp_stdio.ts
+async function serveMcpStdio(server, options = {}) {
+  const input = options.input ?? process.stdin;
+  const output = options.output ?? process.stdout;
+  input.setEncoding("utf8");
+  let buffer = "";
+  const respond = async (line) => {
+    if (!line.trim()) return;
+    const response = await server.handleLine(line.replace(/\r$/, ""));
+    if (response !== void 0)
+      await new Promise(
+        (resolve, reject) => output.write(`${response}
+`, (error) => error ? reject(error) : resolve())
+      );
+  };
+  for await (const chunk of input) {
+    buffer += String(chunk);
+    let end = buffer.indexOf("\n");
+    while (end !== -1) {
+      const line = buffer.slice(0, end);
+      buffer = buffer.slice(end + 1);
+      await respond(line);
+      end = buffer.indexOf("\n");
+    }
+  }
+  await respond(buffer);
+}
+
+// src/surface/questlog_mcp_options.ts
+function questlogMcpOptions(context) {
+  return {
+    name: "ghostpaw-questlog",
+    version: questlogVersion,
+    title: "Questlog",
+    instructions: questlogMcpInstructions,
+    tools: questlogSurfaceTools,
+    context,
+    annotations: (tool) => ({
+      readOnlyHint: tool.readOnly ?? false,
+      destructiveHint: Boolean(
+        tool.inputSchema.properties?.action?.enum?.some(
+          (action) => typeof action === "string" && /delete|retire|merge|trash|hide|remove|replace|archive|abandon|dismiss/.test(action)
+        )
+      ),
+      idempotentHint: tool.readOnly ?? false,
+      openWorldHint: false
+    })
+  };
+}
+
+// src/surface/serve_questlog_mcp.ts
+async function serveQuestlogMcp(options = {}) {
+  let owned;
+  const server = createMcpServer(
+    questlogMcpOptions(async () => {
+      if (options.db) return options.db;
+      owned = await openQuestlogDb(
+        resolveQuestlogDbPath(options.dbPath === void 0 ? {} : { flag: options.dbPath })
+      );
+      return owned;
+    })
+  );
+  try {
+    await serveMcpStdio(server);
+  } finally {
+    owned?.close();
+  }
+}
+
+export { serveQuestlogMcp };

package/dist/skill_markdown-7HCMSJYR.js

@@ -0,0 +1,80 @@
+#!/usr/bin/env node
+// src/surfaces/skill_markdown.ts
+function renderSkillMarkdown(spec, { referencesBase = "references" } = {}) {
+  if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(spec.name) || spec.name.length > 64)
+    throw new Error("Invalid skill name");
+  if (!spec.description.trim() || spec.description.length > 1024 || !spec.description.includes("Use when"))
+    throw new Error("Invalid skill description");
+  if (spec.compatibility && spec.compatibility.length > 500)
+    throw new Error("Invalid compatibility");
+  const lines = ["---", `name: ${spec.name}`, `description: ${JSON.stringify(spec.description)}`];
+  for (const key of ["license", "compatibility"])
+    if (spec[key]) lines.push(`${key}: ${JSON.stringify(spec[key])}`);
+  if (spec.metadata) {
+    lines.push("metadata:");
+    for (const key of Object.keys(spec.metadata).sort())
+      lines.push(`  ${JSON.stringify(key)}: ${JSON.stringify(spec.metadata[key])}`);
+  }
+  lines.push(
+    "---",
+    "",
+    `# ${spec.name}`,
+    "",
+    spec.about,
+    "",
+    "## Calling tools",
+    "",
+    `MCP: connect to ${spec.server}, then call a tool by name with its JSON arguments.`,
+    "",
+    `CLI: \`${spec.bin} call <tool> '<JSON object>'\` or \`${spec.bin} <tool> --parameter value\`${spec.packageName ? ` (without a global install: \`npx -y ${spec.packageName} <tool> ...\`)` : ""}.`,
+    "",
+    `Inspect schemas with \`${spec.bin} describe <tool>\`. Use \`--db <path>\` to select a database.`,
+    ""
+  );
+  for (const tool of spec.tools) {
+    lines.push(
+      `## ${tool.name}`,
+      "",
+      tool.description,
+      "",
+      `Use when: ${tool.whenToUse ?? ""}`,
+      "",
+      `Not for: ${tool.whenNotToUse ?? ""}`,
+      "",
+      tool.readOnly ? "Read-only." : `Writes: ${tool.sideEffects ?? "state"}.`,
+      "",
+      "| Parameter | Type | Required | Values / description |",
+      "| --- | --- | --- | --- |"
+    );
+    for (const [name, property] of Object.entries(tool.inputSchema.properties ?? {}))
+      lines.push(
+        `| ${name} | ${property.type ?? property.oneOf?.map((branch) => branch.type).join(" / ") ?? "any"} | ${tool.inputSchema.required?.includes(name) ? "yes" : "no"} | ${(property.enum ? `${property.enum.join(", ")}. ` : "") + (property.description ?? "").replaceAll("|", "\\|").replaceAll("\n", " ")} |`
+      );
+    lines.push("");
+  }
+  lines.push(
+    "## Workflow guides",
+    "",
+    ...spec.workflows.map(
+      (workflow) => `- [${workflow.name}](${referencesBase}/${workflow.name}.md): ${workflow.description}`
+    ),
+    "",
+    "## Principles",
+    "",
+    ...spec.principles.map((principle) => `- ${principle}`),
+    ""
+  );
+  const output = lines.join("\n");
+  if (!spec.cheatSheet) return output;
+  const title = `# ${spec.name}
+
+`;
+  const start = output.indexOf(title) + title.length;
+  return `${output.slice(0, start)}${spec.cheatSheet}
+
+## Appendix: MCP and tool calls
+
+${output.slice(start).replace(/^## /gm, "### ")}`;
+}
+
+export { renderSkillMarkdown };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@ghostpaw/questlog",
-	"version": "0.8.0",
+	"version": "0.9.1",
 	"description": "Unified task and calendar model for Node.js — SQLite, zero dependencies, with a built-in LLM tool facade",
 	"type": "module",
 	"exports": {
@@ -135,7 +135,8 @@
 		"typescript": "^5.9.3"
 	},
 	"bin": {
-		"ghostpaw-questlog": "./dist/cli.js"
+		"ghostpaw-questlog": "./dist/cli.js",
+		"questlog": "./dist/cli.js"
 	},
 	"mcpName": "io.github.GhostPawJS/questlog"
 }

package/skills/questlog/SKILL.md

@@ -7,9 +7,25 @@ compatibility: "Node.js 24 or newer. MCP stdio or ghostpaw-questlog CLI."
 
 # questlog
 
+No install? Use `npx -y @ghostpaw/questlog <command>`.
+`questlog` and `ghostpaw-questlog` are the same binary.
+
+- `questlog search <words>` before `add` to avoid duplicates.
+- `questlog add --title "..." --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 done <id> --outcome "..."`
+- `questlog search <words>`
+- `questlog show <id>`
+- 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.
+
+## Appendix: MCP and tool calls
+
 Questlog manages local tasks, calendar commitments, and recurring work. Search before creating work, inspect before changing it, and keep uncertain work as rumors. Use unlock prerequisites to sequence work. run_quest refuses blocked starts unless force is true. Review commitments and resolve work with an honest outcome.
 
-## Calling tools
+### Calling tools
 
 MCP: connect to ghostpaw-questlog, then call a tool by name with its JSON arguments.
 
@@ -17,7 +33,7 @@ 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.
 
-## search_questlog
+### search_questlog
 
 Search quests and rumors by text when you need to find an existing item before inspecting or changing it.
 
@@ -34,7 +50,7 @@ Read-only.
 | kinds | array | no | Optional entity kinds to search. |
 | mode | string | no | browse, identify_one. Whether to browse results normally or ask for clarification when several matches are found. |
 
-## review_questlog
+### review_questlog
 
 Review one operational questlog surface such as available quests, open rumors, blocked work, or due repeatable anchors.
 
@@ -50,7 +66,7 @@ Read-only.
 | filters | object | no | Optional filters for supported review surfaces. |
 | now | integer | no | Optional evaluation timestamp for time-sensitive views. |
 
-## inspect_questlog_item
+### inspect_questlog_item
 
 Inspect one specific questlog item in depth and return its richer structured detail and important related refs.
 
@@ -66,7 +82,7 @@ Read-only.
 | detailLevel | string | no | compact, full. How much detail to return. |
 | now | integer | no | Optional evaluation timestamp for time-sensitive detail. |
 
-## capture_rumor
+### capture_rumor
 
 Capture uncertain incoming work as a rumor so it can be triaged later without prematurely turning it into committed execution.
 
@@ -82,7 +98,7 @@ Writes: writes_state.
 | details | string | no | Optional supporting context that explains why the rumor might matter. |
 | now | integer | no | Optional creation timestamp for the rumor. |
 
-## shape_work
+### shape_work
 
 Create a quest (with timing, tags, and objective in one call), create a questline, settle a rumor into concrete work, or manage quest-questline membership. Use create_quest for clear commitments — include tags and timing directly to avoid follow-up calls.
 
@@ -107,7 +123,7 @@ Writes: writes_state.
 | title | string | no | New title for the update_rumor action. |
 | details | string | no | New or enriched context text for the update_rumor action. |
 
-## plan_quest
+### plan_quest
 
 Refine a quest by revising its objective before actual start or by changing its temporal planning fields.
 
@@ -130,7 +146,7 @@ Writes: writes_state.
 | estimateSeconds | integer | no | Optional active-effort estimate in seconds. |
 | now | integer | no | Optional update timestamp. |
 
-## run_quest
+### run_quest
 
 Run quest lifecycle actions such as starting, logging effort, finishing, abandoning, or abandoning and spawning follow-up quests atomically.
 
@@ -152,7 +168,7 @@ Writes: writes_state.
 | resolvedAt | integer | no | Optional resolved timestamp for finish or abandon actions. |
 | followups | array | no | Follow-up quests to create atomically. Required for abandon_and_spawn_followups. |
 
-## organize_work
+### organize_work
 
 Organize grouping and dependency structure by updating questlines or changing hard unlock prerequisites between concrete quests.
 
@@ -176,7 +192,7 @@ Writes: writes_state.
 | fromQuestIds | array | no | Full prerequisite quest id set. |
 | now | integer | no | Optional timestamp. |
 
-## manage_repeatable
+### manage_repeatable
 
 Manage recurring work definitions by creating, updating, previewing, spawning, or archiving repeatable quests.
 
@@ -205,7 +221,7 @@ Writes: writes_state.
 | archivedAt | integer | no | Optional archive timestamp. |
 | now | integer | no | Evaluation or update timestamp. |
 
-## tag_work
+### tag_work
 
 Classify work by adding, removing, or replacing tags on quests and by replacing the future tag template set on repeatable quests.
 
@@ -222,7 +238,7 @@ Writes: writes_state.
 | tagNames | array | yes | Tag names to add, remove, or replace. |
 | now | integer | no | Optional timestamp for the tag mutation. |
 
-## reward_work
+### reward_work
 
 Manage rewards by adding, updating, removing, or claiming quest rewards, or by replacing future reward templates on repeatable quests.
 
@@ -241,7 +257,7 @@ Writes: writes_state.
 | claimedAt | integer | no | Optional claim timestamp. |
 | now | integer | no | Optional timestamp for removal or template replacement. |
 
-## retire_work
+### retire_work
 
 Hide an item from normal active operation without rewriting history by soft-deleting a rumor, quest, questline, or repeatable quest.
 
@@ -257,7 +273,7 @@ Writes: writes_state.
 | target | object | yes | The target to hide. |
 | deletedAt | integer | no | Optional timestamp to record when the item became hidden. |
 
-## Workflow guides
+### Workflow guides
 
 - [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.
 - [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.
@@ -285,7 +301,7 @@ Writes: writes_state.
 - [settle-rumor-into-structure](references/settle-rumor-into-structure.md): Turn a ready rumor into committed quest or questline structure without losing provenance or pretending vague intake is settled.
 - [tag-and-filter-portfolios](references/tag-and-filter-portfolios.md): Use tags for cross-cutting classification and portfolio filtering without confusing tags for status, timing, or dependency modeling.
 
-## Principles
+### Principles
 
 - Store the least committed truth first.
 - Read before you prescribe.