@ghostpaw/questlog 0.9.0 → 0.9.2

package/dist/{chunk-3Y5F3SMB.js → chunk-UTUQPSGO.js}

@@ -1,4 +1,6 @@
 #!/usr/bin/env node
+import { registerSchemaActions, minimalInput, requiredForAction } from './chunk-QYSIJ2YN.js';
+
 // src/questlines/map_questline_row.ts
 function mapQuestlineRow(row) {
   return {
@@ -1080,8 +1082,181 @@ function listRumors(db) {
   return db.prepare("SELECT * FROM rumors WHERE deleted_at IS NULL ORDER BY created_at DESC, id DESC").all().map(mapRumorRow);
 }
 
+// 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_types.ts
+function withOptionalFields(result, options) {
+  if (options.next && options.next.length > 0) {
+    result.next = options.next;
+  }
+  if (options.warnings && options.warnings.length > 0) {
+    result.warnings = options.warnings;
+  }
+  return result;
+}
+function toolWarning(code, message) {
+  return { code, message };
+}
+function toolSuccess(summary, data, options = {}) {
+  return withOptionalFields(
+    {
+      ok: true,
+      outcome: "success",
+      summary,
+      entities: options.entities ?? [],
+      data
+    },
+    options
+  );
+}
+function toolNoOp(summary, data, options = {}) {
+  return withOptionalFields(
+    {
+      ok: true,
+      outcome: "no_op",
+      summary,
+      entities: options.entities ?? [],
+      data
+    },
+    options
+  );
+}
+function toolNeedsClarification(code, question, missing, options = {}) {
+  return withOptionalFields(
+    {
+      ok: false,
+      outcome: "needs_clarification",
+      summary: question,
+      entities: options.entities ?? [],
+      clarification: {
+        code,
+        question,
+        missing,
+        options: options.options
+      }
+    },
+    options
+  );
+}
+function toolFailure(kind, code, summary, message, options = {}) {
+  return withOptionalFields(
+    {
+      ok: false,
+      outcome: "error",
+      summary,
+      entities: options.entities ?? [],
+      error: {
+        kind,
+        code,
+        message,
+        recovery: options.recovery,
+        details: options.details
+      }
+    },
+    options
+  );
+}
+
 // src/tools/tool_metadata.ts
 function defineQuestlogTool(definition) {
+  const requirements = actionRequirements[definition.name];
+  if (requirements) registerSchemaActions(definition.inputSchema, requirements);
+  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 = {}) {
@@ -1243,79 +1418,6 @@ function summarizeCount(count, singular, plural = `${singular}s`) {
   return `Found ${count} ${plural}.`;
 }
 
-// src/tools/tool_types.ts
-function withOptionalFields(result, options) {
-  if (options.next && options.next.length > 0) {
-    result.next = options.next;
-  }
-  if (options.warnings && options.warnings.length > 0) {
-    result.warnings = options.warnings;
-  }
-  return result;
-}
-function toolWarning(code, message) {
-  return { code, message };
-}
-function toolSuccess(summary, data, options = {}) {
-  return withOptionalFields(
-    {
-      ok: true,
-      outcome: "success",
-      summary,
-      entities: options.entities ?? [],
-      data
-    },
-    options
-  );
-}
-function toolNoOp(summary, data, options = {}) {
-  return withOptionalFields(
-    {
-      ok: true,
-      outcome: "no_op",
-      summary,
-      entities: options.entities ?? [],
-      data
-    },
-    options
-  );
-}
-function toolNeedsClarification(code, question, missing, options = {}) {
-  return withOptionalFields(
-    {
-      ok: false,
-      outcome: "needs_clarification",
-      summary: question,
-      entities: options.entities ?? [],
-      clarification: {
-        code,
-        question,
-        missing,
-        options: options.options
-      }
-    },
-    options
-  );
-}
-function toolFailure(kind, code, summary, message, options = {}) {
-  return withOptionalFields(
-    {
-      ok: false,
-      outcome: "error",
-      summary,
-      entities: options.entities ?? [],
-      error: {
-        kind,
-        code,
-        message,
-        recovery: options.recovery,
-        details: options.details
-      }
-    },
-    options
-  );
-}
-
 // src/tools/review_questlog_tool.ts
 function hasQuestFilters(filters) {
   return Boolean(
@@ -3191,7 +3293,7 @@ var rewardWorkTool = defineQuestlogTool({
           name: stringSchema("Reward name."),
           now: integerSchema("Optional update timestamp for the update action.")
         },
-        []
+        ["kind", "name"]
       ),
       rewards: arraySchema(
         objectSchema(
@@ -4018,7 +4120,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."),
@@ -4300,9 +4402,9 @@ var questlogSurfaceTools = questlogTools.map(
     whenNotToUse: tool.whenNotToUse ?? "",
     readOnly: tool.readOnly,
     sideEffects: tool.sideEffects,
-    inputSchema: { ...tool.inputSchema, type: "object" },
+    inputSchema: tool.inputSchema,
     handler: tool.handler
   })
 );
 
-export { getQuestDetail, questlogSurfaceTools, reviewQuestlogTool };
+export { getQuestDetail, questlogSurfaceTools, reviewQuestlogTool, validateInput };

package/dist/cli.js

@@ -3,7 +3,7 @@
 function checkNodeVersion(version, stderr) {
   if (Number(version.split(".")[0]) >= 24) return true;
   stderr.write(
-    `questlog needs Node 24+ (found ${version}). Install Node 24 or put it first on PATH.
+    `questlog needs Node 24+ (found ${version}). Install Node 24+ (e.g. via nvm, mise or your package manager) or put it first on PATH.
 `
   );
   return false;
@@ -13,5 +13,5 @@ function checkNodeVersion(version, stderr) {
 if (!checkNodeVersion(process.versions.node, process.stderr)) {
   process.exitCode = 2;
 } else {
-  await import('./cli_main-ED5BJPSR.js');
+  await import('./cli_main-XNZP4TY2.js');
 }

package/dist/{cli_main-ED5BJPSR.js → cli_main-XNZP4TY2.js}

@@ -1,9 +1,30 @@
 #!/usr/bin/env node
-import { validateInput, isErrorResult, questlogVersion, resolveQuestlogDbPath } from './chunk-RUSE7ZFF.js';
-import { reviewQuestlogTool, getQuestDetail, questlogSurfaceTools } from './chunk-3Y5F3SMB.js';
+import { isErrorResult, questlogVersion, resolveQuestlogDbPath } from './chunk-DKH623HU.js';
+import { questlogSkills } from './chunk-6KTQK3ZE.js';
+import { reviewQuestlogTool, validateInput, getQuestDetail, questlogSurfaceTools } from './chunk-UTUQPSGO.js';
+import { minimalInput } from './chunk-QYSIJ2YN.js';
+import { isSea } from 'node:sea';
 import { readFileSync, existsSync } from 'node:fs';
 import { resolve } from 'node:path';
 
+var npmEntry = false;
+function markNpmEntry() {
+  npmEntry = true;
+}
+function cliVersion(version, {
+  sea = isSea,
+  npm = npmEntry,
+  platform = process.platform,
+  arch = process.arch
+} = {}) {
+  let binary = false;
+  try {
+    binary = sea();
+  } catch {
+  }
+  const target = `${platform === "win32" ? "windows" : platform}-${arch}`;
+  return `questlog ${version} (${binary ? `binary, ${target}` : npm ? "npm" : "library"})`;
+}
 var CliUsageError = class extends Error {
   exitCode = 2;
 };
@@ -71,7 +92,7 @@ function parseCliArgs(argv, spec) {
     if (arg.type === "boolean" && raw === void 0) raw = negative ? "false" : "true";
     if (raw === void 0) {
       const next = argv[i + 1];
-      if (next === void 0 || next.startsWith("--"))
+      if (next === void 0 || /^--[a-z]/i.test(next))
         throw new CliUsageError(`Missing value: --${arg.name}`);
       raw = next;
       i++;
@@ -202,7 +223,7 @@ ${r.error.message}
       ["title", detail.title],
       ["objective", detail.objective],
       ["state", detail.state],
-      ["tags", detail.tagNames.map((tag) => `#${tag}`).join(" ")],
+      ["tags", detail.tagNames.length ? detail.tagNames.map((tag) => `#${tag}`).join(" ") : "-"],
       ["due", detail.effectiveDueAt == null ? "-" : formatPlainDate(detail.effectiveDueAt, true)],
       ["created", formatPlainDate(detail.createdAt, true)]
     ];
@@ -240,9 +261,10 @@ function questlogPlainCommands() {
     {
       spec: {
         command: "add",
-        description: "Create a quest. Objective defaults to the title.",
+        description: 'Create a quest: add "My title" or add --title "My title". Objective defaults to the title.',
+        positionals: [{ name: "positionalTitle", type: "string" }],
         flags: [
-          { name: "title", type: "string", required: true },
+          { name: "title", type: "string" },
           { name: "tag", type: "array" },
           { name: "objective", type: "string" },
           {
@@ -255,9 +277,15 @@ function questlogPlainCommands() {
       },
       tool: "shape_work",
       input: (v) => {
+        if (v.title !== void 0 && v.positionalTitle !== void 0)
+          throw new CliUsageError(
+            "give the title once: either as the first argument or with --title"
+          );
+        const title = v.positionalTitle ?? v.title;
+        if (title === void 0) throw new CliUsageError("Missing required argument: title");
         const quest = {
-          title: v.title,
-          objective: v.objective ?? v.title
+          title,
+          objective: v.objective ?? title
         };
         if (v.tag !== void 0)
           quest.tags = v.tag.flatMap(
@@ -342,6 +370,7 @@ function selectedDbPath(options) {
 var questlogCliOptions = {
   bin: "ghostpaw-questlog",
   version: questlogVersion,
+  versionLine: () => cliVersion(questlogVersion),
   description: "Local task and calendar library",
   tools: questlogSurfaceTools,
   describeDb: (options) => `Database: ${selectedDbPath(options)}
@@ -358,13 +387,14 @@ Use --db <path> or GHOSTPAW_QUESTLOG_DB to override the default ~/.ghostpaw/ques
   closeContext: (db) => db.close(),
   commands: {
     plain: questlogPlainCommands(),
+    guides: questlogSkills,
     mcp: async (options) => {
-      const { serveQuestlogMcp } = await import('./serve_questlog_mcp-J4ZHNEOT.js');
+      const { serveQuestlogMcp } = await import('./serve_questlog_mcp-KFUYJB2P.js');
       await serveQuestlogMcp(options.db === void 0 ? {} : { dbPath: options.db });
     },
     skill: async () => {
-      const { renderSkillMarkdown } = await import('./skill_markdown-7HCMSJYR.js');
-      const { questlogSkillSpec } = await import('./questlog_skill_spec-JLZH3JL2.js');
+      const { renderSkillMarkdown } = await import('./skill_markdown-HXYQ3K6U.js');
+      const { questlogSkillSpec } = await import('./questlog_skill_spec-EM6DGGVN.js');
       return renderSkillMarkdown(questlogSkillSpec);
     }
   }
@@ -452,7 +482,7 @@ ${options.tools.map((tool2) => `${tool2.name}  ${tool2.description}`).join("\n")
     return 0;
   }
   if (["--version", "-v"].includes(command)) {
-    stdout.write(`${options.version}
+    stdout.write(`${options.versionLine?.() ?? options.version}
 `);
     return 0;
   }
@@ -470,7 +500,26 @@ ${options.tools.map((tool2) => `${tool2.name}  ${tool2.description}`).join("\n")
   }
   if (command === "skill") {
     if (!options.commands?.skill) return fail("skill command unavailable");
-    stdout.write(await options.commands.skill());
+    if (args.length > 1) return fail(`Usage: ${options.bin} skill [--list | <guide> | --help]`);
+    const guide = args[0];
+    if (guide === "--help" || guide === "-h") {
+      stdout.write(
+        `Usage:
+  ${options.bin} skill
+  ${options.bin} skill --list
+  ${options.bin} skill <guide>
+`
+      );
+    } else if (guide === "--list") {
+      stdout.write(
+        `${(options.commands.guides ?? []).map((entry) => `${entry.name}  ${entry.description.replace(/\s+/g, " ")}`).join("\n")}
+`
+      );
+    } else if (guide) {
+      const entry = options.commands.guides?.find((entry2) => entry2.name === guide);
+      if (!entry) return fail(`unknown guide ${guide}; run ${options.bin} skill --list`);
+      stdout.write(entry.content);
+    } else stdout.write(await options.commands.skill());
     return 0;
   }
   if (command === "mcp") {
@@ -599,7 +648,11 @@ ${JSON.stringify(tool.inputSchema, null, 2)}
     return fail(`Invalid input: ${cause instanceof Error ? cause.message : String(cause)}`, 1);
   }
   const errors = validateInput(tool.inputSchema, input);
-  if (errors.length) return fail(errors.join("\n"), 1);
+  if (errors.length)
+    return fail(
+      `${errors.join("\n")}; pass ${JSON.stringify(minimalInput(tool.inputSchema, input?.action))}`,
+      1
+    );
   let context;
   try {
     context = await options.openContext(ctxOptions);
@@ -623,4 +676,5 @@ ${JSON.stringify(tool.inputSchema, null, 2)}
 }
 
 // src/cli_main.ts
+markNpmEntry();
 process.exitCode = await runToolCli(process.argv.slice(2), questlogCliOptions);

package/dist/index.cjs

@@ -3183,8 +3183,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 = {}) {
@@ -4727,7 +4872,7 @@ var rewardWorkTool = defineQuestlogTool({
           name: stringSchema("Reward name."),
           now: integerSchema("Optional update timestamp for the update action.")
         },
-        []
+        ["kind", "name"]
       ),
       rewards: arraySchema(
         objectSchema(
@@ -5393,7 +5538,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."),