@ghostpaw/questlog 0.9.1 → 0.9.2

package/dist/mcp.js

@@ -384,7 +384,7 @@ async function openQuestlogDb(path) {
 }
 
 // src/version.ts
-var questlogVersion = "0.9.1";
+var questlogVersion = "0.9.2";
 
 // src/surface/questlog_mcp_instructions.ts
 var questlogMcpInstructions = "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.";
@@ -630,8 +630,153 @@ function translateToolError(error, options = {}) {
   );
 }
 
+// src/surfaces/schema_actions.ts
+var requirements = /* @__PURE__ */ new WeakMap();
+function registerSchemaActions(schema, actions) {
+  requirements.set(schema, actions);
+}
+function requiredForAction(schema, action) {
+  return requirements.get(schema)?.[String(action)] ?? [];
+}
+
+// src/surfaces/schema_examples.ts
+function minimalInput(schema, action, name = "") {
+  const constant = "const" in schema ? schema.const : void 0;
+  if (constant !== void 0) return constant;
+  if (schema.enum)
+    return action !== void 0 && schema.enum.includes(action) ? action : schema.enum[0];
+  const branch = schema.oneOf?.[0];
+  if (schema.type === "object" || schema.properties) {
+    action ??= schema.properties?.action?.enum?.[0];
+    const properties = { ...schema.properties, ...branch?.properties };
+    return Object.fromEntries(
+      [
+        .../* @__PURE__ */ new Set([
+          ...schema.required ?? [],
+          ...requiredForAction(schema, action),
+          ...schema.properties?.outcome && ["finish", "abandon", "abandon_and_spawn_followups"].includes(String(action)) ? ["outcome"] : [],
+          ...branch?.required ?? []
+        ])
+      ].map((key) => [
+        key,
+        minimalInput(properties[key] ?? {}, key === "action" ? action : void 0, key)
+      ])
+    );
+  }
+  if (branch) return minimalInput(branch, action, name);
+  if (schema.type === "array") return [minimalInput(schema.items ?? {}, void 0, name)];
+  if (schema.type === "integer" || schema.type === "number")
+    return name === "anchorAt" ? 18e11 : name === "toQuestId" ? 2 : 1;
+  if (schema.type === "boolean") return false;
+  if (schema.type === "null") return null;
+  if (name === "rrule") return "FREQ=WEEKLY";
+  if (name === "title") return "Review release notes";
+  if (name === "objective") return "Check changes against the release";
+  return "release";
+}
+
+// src/surfaces/validate_input.ts
+function validateInput(schema, input, path = "$") {
+  const errors = [];
+  const matchesType = (type) => {
+    switch (type) {
+      case "object":
+        return typeof input === "object" && input !== null && !Array.isArray(input);
+      case "array":
+        return Array.isArray(input);
+      case "integer":
+        return typeof input === "number" && Number.isInteger(input);
+      case "number":
+        return typeof input === "number" && Number.isFinite(input);
+      case "null":
+        return input === null;
+      default:
+        return typeof input === type;
+    }
+  };
+  if (schema.type && !(Array.isArray(schema.type) ? schema.type : [schema.type]).some(matchesType)) {
+    return [`${path}: expected ${String(schema.type)}`];
+  }
+  if (schema.enum && !schema.enum.some((value) => JSON.stringify(value) === JSON.stringify(input)))
+    errors.push(`${path}: expected one of ${JSON.stringify(schema.enum)}`);
+  const constant = "const" in schema ? schema.const : void 0;
+  if (constant !== void 0 && constant !== input)
+    errors.push(`${path}: expected ${JSON.stringify(constant)}`);
+  if (schema.oneOf) {
+    const branches = schema.oneOf.map((branch) => validateInput(branch, input, path));
+    if (!branches.some((errors2) => errors2.length === 0)) {
+      errors.push(
+        ...branches.sort((a, b) => a.length - b.length)[0] ?? [
+          `${path}: must match at least one schema branch`
+        ]
+      );
+    }
+  }
+  if (typeof input === "object" && input !== null && !Array.isArray(input)) {
+    const record = input;
+    for (const name of [...schema.required ?? [], ...requiredForAction(schema, record.action)])
+      if (!Object.hasOwn(record, name)) errors.push(`${path}.${name}: required`);
+    for (const [name, property] of Object.entries(schema.properties ?? {}))
+      if (Object.hasOwn(record, name))
+        errors.push(...validateInput(property, record[name], `${path}.${name}`));
+  }
+  if (Array.isArray(input) && schema.items)
+    input.forEach((value, index) => {
+      errors.push(...validateInput(schema.items, value, `${path}[${index}]`));
+    });
+  return errors;
+}
+
+// src/tools/action_requirements.ts
+var actionRequirements = {
+  shape_work: {
+    create_quest: ["quest"],
+    create_questline: ["questline"],
+    attach_quest_to_questline: ["questId", "questlineId"],
+    detach_quest_from_questline: ["questId"],
+    dismiss_rumor: ["rumorId"],
+    reopen_rumor: ["rumorId"],
+    settle_rumor: ["rumorId"],
+    update_rumor: ["rumorId"]
+  },
+  manage_repeatable: {
+    create: ["repeatableQuest"],
+    archive: ["repeatableQuestId"],
+    update: ["repeatableQuestId"],
+    spawn_due: ["now"]
+  },
+  organize_work: {
+    add_unlock: ["fromQuestId", "toQuestId"],
+    remove_unlock: ["fromQuestId", "toQuestId"],
+    replace_unlocks: ["fromQuestIds", "toQuestId"],
+    archive_questline: ["questlineId"],
+    set_questline_fields: ["questlineId"]
+  },
+  plan_quest: { revise_objective: ["objective"] },
+  run_quest: {
+    abandon_and_spawn_followups: ["followups"],
+    log_effort: ["effortSeconds"]
+  },
+  reward_work: { add: ["reward"], update: ["reward"], replace_repeatable_template: ["rewards"] }
+};
+
 // src/tools/tool_metadata.ts
 function defineQuestlogTool(definition) {
+  const requirements2 = actionRequirements[definition.name];
+  if (requirements2) registerSchemaActions(definition.inputSchema, requirements2);
+  const handler = definition.handler;
+  definition.handler = (db, input) => {
+    const errors = validateInput(definition.inputSchema, input);
+    if (errors.length) {
+      const action = input?.action;
+      const example = minimalInput(definition.inputSchema, action);
+      const message = errors.join("; ");
+      return toolFailure("protocol", "invalid_input", message, message, {
+        recovery: `${message}; pass ${JSON.stringify(example)}`
+      });
+    }
+    return handler(db, input);
+  };
   return definition;
 }
 function stringSchema(description, options = {}) {
@@ -3581,7 +3726,7 @@ var rewardWorkTool = defineQuestlogTool({
           name: stringSchema("Reward name."),
           now: integerSchema("Optional update timestamp for the update action.")
         },
-        []
+        ["kind", "name"]
       ),
       rewards: arraySchema(
         objectSchema(
@@ -4408,7 +4553,7 @@ var shapeWorkTool = defineQuestlogTool({
           title: stringSchema("Questline title."),
           description: stringSchema("Optional questline description.")
         },
-        []
+        ["title"]
       ),
       rumorId: integerSchema("Rumor to settle, dismiss, or reopen."),
       dismissedAt: integerSchema("Optional dismissal timestamp."),
@@ -4690,7 +4835,7 @@ var questlogSurfaceTools = questlogTools.map(
     whenNotToUse: tool.whenNotToUse ?? "",
     readOnly: tool.readOnly,
     sideEffects: tool.sideEffects,
-    inputSchema: { ...tool.inputSchema, type: "object" },
+    inputSchema: tool.inputSchema,
     handler: tool.handler
   })
 );
@@ -4725,47 +4870,6 @@ function isErrorResult(result) {
   return typeof result === "object" && result !== null && "ok" in result && result.ok === false;
 }
 
-// src/surfaces/validate_input.ts
-function validateInput(schema, input, path = "$") {
-  const errors = [];
-  const matchesType = (type) => {
-    switch (type) {
-      case "object":
-        return typeof input === "object" && input !== null && !Array.isArray(input);
-      case "array":
-        return Array.isArray(input);
-      case "integer":
-        return typeof input === "number" && Number.isInteger(input);
-      case "number":
-        return typeof input === "number" && Number.isFinite(input);
-      case "null":
-        return input === null;
-      default:
-        return typeof input === type;
-    }
-  };
-  if (schema.type && !(Array.isArray(schema.type) ? schema.type : [schema.type]).some(matchesType)) {
-    return [`${path}: expected ${String(schema.type)}`];
-  }
-  if (schema.enum && !schema.enum.some((value) => JSON.stringify(value) === JSON.stringify(input)))
-    errors.push(`${path}: expected one of ${JSON.stringify(schema.enum)}`);
-  if (schema.oneOf && !schema.oneOf.some((branch) => validateInput(branch, input, path).length === 0))
-    errors.push(`${path}: must match at least one schema branch`);
-  if (typeof input === "object" && input !== null && !Array.isArray(input)) {
-    const record = input;
-    for (const name of schema.required ?? [])
-      if (!Object.hasOwn(record, name)) errors.push(`${path}.${name}: required`);
-    for (const [name, property] of Object.entries(schema.properties ?? {}))
-      if (Object.hasOwn(record, name))
-        errors.push(...validateInput(property, record[name], `${path}.${name}`));
-  }
-  if (Array.isArray(input) && schema.items)
-    input.forEach((value, index) => {
-      errors.push(...validateInput(schema.items, value, `${path}[${index}]`));
-    });
-  return errors;
-}
-
 // src/surfaces/mcp_server.ts
 var MCP_LATEST_PROTOCOL_VERSION = "2026-07-28";
 var MCP_SUPPORTED_PROTOCOL_VERSIONS = [
@@ -4865,7 +4969,15 @@ Not for: ${tool.whenNotToUse}` : ""),
         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 });
+          return result({
+            content: [
+              {
+                type: "text",
+                text: `${errors.join("\n")}; pass ${JSON.stringify(minimalInput(tool.inputSchema, input?.action))}`
+              }
+            ],
+            isError: true
+          });
         try {
           context ??= Promise.resolve().then(options.context);
           const value = await tool.handler(await context, input);

package/dist/questlog_skill_spec-EM6DGGVN.js

@@ -0,0 +1,74 @@
+#!/usr/bin/env node
+import { questlogMcpInstructions } from './chunk-SVWAEAKC.js';
+import { questlogSkills } from './chunk-6KTQK3ZE.js';
+import { reviewQuestlogTool, questlogSurfaceTools } from './chunk-UTUQPSGO.js';
+import './chunk-QYSIJ2YN.js';
+
+// src/soul.ts
+var questlogSoulTraits = [
+  {
+    principle: "Store the least committed truth first.",
+    provenance: "The worst downstream errors usually start upstream: vague asks are turned into quests, soft ideas become fake deadlines, and half-understood work is treated as fully shaped. Using rumors and clarification before commitment keeps uncertainty where it belongs."
+  },
+  {
+    principle: "Read before you prescribe.",
+    provenance: "Many management mistakes are category mistakes: blocked work gets treated as available, missed schedule as overdue, or resolved work as fully closed when follow-through still remains. Reading the derived state first prevents confident but wrong interventions."
+  },
+  {
+    principle: "Protect history when reality changes.",
+    provenance: "Once execution starts, rewriting a quest into a different commitment destroys the meaning of the record. Honest finishes, abandonments, and follow-up quests preserve what actually happened and keep later review, planning, and reporting trustworthy."
+  },
+  {
+    principle: "Close the last mile, not just the main work.",
+    provenance: "Operational debt often hides in almost-done states: work finished but not claimed, reported, handed off, reviewed, or retired. Treating closure as a real phase prevents stale rewards, lingering initiatives, and misleading progress signals."
+  }
+];
+
+// src/surface/questlog_skill_spec.ts
+var questlogSkillSpec = {
+  name: "questlog",
+  cheatSheet: [
+    "## Install",
+    "",
+    "Linux/macOS:",
+    "",
+    "```sh",
+    "curl -fsSL https://raw.githubusercontent.com/GhostPawJS/questlog/main/install.sh | sh",
+    "```",
+    "",
+    "Installs `~/.local/bin/ghostpaw-questlog` after checking SHA256SUMS.",
+    "",
+    "Windows x64 (PowerShell):",
+    "",
+    "```powershell",
+    "irm https://raw.githubusercontent.com/GhostPawJS/questlog/main/install.ps1 | iex",
+    "```",
+    "",
+    "Run tools as `ghostpaw-questlog ...`; use `~/.local/bin/ghostpaw-questlog` if it is not on PATH.",
+    "",
+    "`questlog` and `ghostpaw-questlog` are the same binary.",
+    "",
+    "- `questlog search <words>` before `add` to avoid duplicates.",
+    '- `ghostpaw-questlog add "..." --tag a,b --due tomorrow`',
+    `- \`questlog list [--view <view>]\`: ${reviewQuestlogTool.inputSchema.properties?.view?.enum?.join(", ")}.`,
+    '- `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."
+  ].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",
+  compatibility: "Release binary ghostpaw-questlog (no runtime needed); MCP stdio via ghostpaw-questlog mcp.",
+  bin: "ghostpaw-questlog",
+  packageName: "@ghostpaw/questlog",
+  server: "ghostpaw-questlog",
+  about: questlogMcpInstructions,
+  tools: questlogSurfaceTools,
+  workflows: questlogSkills,
+  principles: questlogSoulTraits.map((trait) => trait.principle)
+};
+
+export { questlogSkillSpec };

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

@@ -1,8 +1,9 @@
 #!/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';
+import { isErrorResult, questlogVersion, resolveQuestlogDbPath } from './chunk-DKH623HU.js';
+import { validateInput, questlogSurfaceTools } from './chunk-UTUQPSGO.js';
+import { minimalInput } from './chunk-QYSIJ2YN.js';
 
 // src/surfaces/mcp_server.ts
 var MCP_LATEST_PROTOCOL_VERSION = "2026-07-28";
@@ -103,7 +104,15 @@ Not for: ${tool.whenNotToUse}` : ""),
         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 });
+          return result({
+            content: [
+              {
+                type: "text",
+                text: `${errors.join("\n")}; pass ${JSON.stringify(minimalInput(tool.inputSchema, input?.action))}`
+              }
+            ],
+            isError: true
+          });
         try {
           context ??= Promise.resolve().then(options.context);
           const value = await tool.handler(await context, input);

package/dist/{skill_markdown-7HCMSJYR.js → skill_markdown-HXYQ3K6U.js}

@@ -1,4 +1,6 @@
 #!/usr/bin/env node
+import { minimalInput } from './chunk-QYSIJ2YN.js';
+
 // src/surfaces/skill_markdown.ts
 function renderSkillMarkdown(spec, { referencesBase = "references" } = {}) {
   if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(spec.name) || spec.name.length > 64)
@@ -26,7 +28,7 @@ function renderSkillMarkdown(spec, { referencesBase = "references" } = {}) {
     "",
     `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> ...\`)` : ""}.`,
+    `CLI: \`${spec.bin} call <tool> '<JSON object>'\` or \`${spec.bin} <tool> --parameter value\`.`,
     "",
     `Inspect schemas with \`${spec.bin} describe <tool>\`. Use \`--db <path>\` to select a database.`,
     ""
@@ -46,17 +48,38 @@ function renderSkillMarkdown(spec, { referencesBase = "references" } = {}) {
       "| Parameter | Type | Required | Values / description |",
       "| --- | --- | --- | --- |"
     );
-    for (const [name, property] of Object.entries(tool.inputSchema.properties ?? {}))
+    const rows = (schema, prefix = "") => {
+      const properties = { ...schema.properties };
+      const required = new Set(schema.required);
+      for (const branch of schema.oneOf ?? []) {
+        for (const [key, value] of Object.entries(branch.properties ?? {}))
+          properties[key] ??= value;
+        for (const key of branch.required ?? []) required.add(key);
+      }
+      for (const [name, property] of Object.entries(properties)) {
+        if (prefix && Object.keys(properties).length > 8 && !required.has(name)) continue;
+        const path = `${prefix}${name}`;
+        lines.push(
+          `| ${path} | ${property.type ?? property.oneOf?.map((branch) => branch.type).join(" / ") ?? "any"} | ${required.has(name) ? "yes" : "no"} | ${((property.enum ? `${property.enum.join(", ")}. ` : "") + (property.description ?? "")).replaceAll("|", "\\|").replaceAll("\n", " ")} |`
+        );
+        if (property.properties || property.oneOf) rows(property, `${path}.`);
+      }
+    };
+    rows(tool.inputSchema);
+    lines.push("", "```sh");
+    for (const action of tool.inputSchema.properties?.action?.enum?.slice(0, 3) ?? [void 0]) {
       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", " ")} |`
+        `${spec.bin} call ${tool.name} '${JSON.stringify(minimalInput(tool.inputSchema, action))}'`
       );
+    }
+    lines.push("```");
     lines.push("");
   }
   lines.push(
     "## Workflow guides",
     "",
     ...spec.workflows.map(
-      (workflow) => `- [${workflow.name}](${referencesBase}/${workflow.name}.md): ${workflow.description}`
+      (workflow) => `- \`${spec.bin} skill ${workflow.name}\` ([${workflow.name}](${referencesBase}/${workflow.name}.md)): ${workflow.description}`
     ),
     "",
     "## Principles",
@@ -65,7 +88,12 @@ function renderSkillMarkdown(spec, { referencesBase = "references" } = {}) {
     ""
   );
   const output = lines.join("\n");
-  if (!spec.cheatSheet) return output;
+  const fallback = spec.packageName ? `
+## Without the binary
+
+Use \`npx -y ${spec.packageName} ...\` in npm-based environments (Node 24+). Harnesses that embed it in code can import \`${spec.packageName}\` as a library.
+` : "";
+  if (!spec.cheatSheet) return output + fallback;
   const title = `# ${spec.name}
 
 `;
@@ -74,7 +102,7 @@ function renderSkillMarkdown(spec, { referencesBase = "references" } = {}) {
 
 ## Appendix: MCP and tool calls
 
-${output.slice(start).replace(/^## /gm, "### ")}`;
+${output.slice(start).replace(/^## /gm, "### ")}${fallback}`;
 }
 
 export { renderSkillMarkdown };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@ghostpaw/questlog",
-	"version": "0.9.1",
+	"version": "0.9.2",
 	"description": "Unified task and calendar model for Node.js — SQLite, zero dependencies, with a built-in LLM tool facade",
 	"type": "module",
 	"exports": {
@@ -127,7 +127,7 @@
 	"devDependencies": {
 		"@biomejs/biome": "2.4.4",
 		"@types/node": "^25.3.0",
-		"esbuild": "^0.27.4",
+		"esbuild": "^0.28.2",
 		"fflate": "0.8.3",
 		"preact": "^10.29.0",
 		"sql.js-fts5": "^1.4.0",
@@ -138,5 +138,8 @@
 		"ghostpaw-questlog": "./dist/cli.js",
 		"questlog": "./dist/cli.js"
 	},
-	"mcpName": "io.github.GhostPawJS/questlog"
+	"mcpName": "io.github.GhostPawJS/questlog",
+	"overrides": {
+		"esbuild": "$esbuild"
+	}
 }