@kairyou/agent-tools 0.19.0 → 0.20.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kairyou/agent-tools",
-  "version": "0.19.0",
+  "version": "0.20.0",
   "description": "Reusable Agent Skills, plus runtime capabilities (statusline, provider usage, vision) for Codex, Claude Code, and opencode.",
   "license": "MIT",
   "repository": {

package/skills/systems/at-zentao/SKILL.md

@@ -72,6 +72,7 @@ node <skill-root>/scripts/zentao-cli.mjs get bug <id>
 node <skill-root>/scripts/zentao-cli.mjs get task <id>
 node <skill-root>/scripts/zentao-cli.mjs get story <id>
 node <skill-root>/scripts/zentao-cli.mjs get bug <id> --download-dir <path>
+node <skill-root>/scripts/zentao-cli.mjs hours task <id>
 ```
 
 `get` downloads token-gated inline images and attachments into a temporary
@@ -89,6 +90,7 @@ node <skill-root>/scripts/zentao-cli.mjs start task <id>
 node <skill-root>/scripts/zentao-cli.mjs pause task <id>
 node <skill-root>/scripts/zentao-cli.mjs resume task <id>
 node <skill-root>/scripts/zentao-cli.mjs log-hours task <id>
+node <skill-root>/scripts/zentao-cli.mjs edit-hours task <id> <effort-id>
 node <skill-root>/scripts/zentao-cli.mjs finish task <id>
 ```
 
@@ -99,6 +101,7 @@ Input shapes:
 {"resolution":"fixed","resolvedBuild":"trunk","comment":"Root cause and result, commit abc1234."}
 {"realStarted":"2026-08-11 09:00:00","comment":"Started implementation."}
 {"date":"2026-08-11","consumed":2,"left":14,"work":"Implemented the first part of the task."}
+{"work":"Corrected work description, commit abc1234."}
 {"currentConsumed":1.5,"realStarted":"2026-08-11 09:00:00","finishedDate":"2026-08-11 10:30:00"}
 ```
 
@@ -109,7 +112,9 @@ computes a task's total consumed hours from its current ZenTao value.
 accepts `realStarted` and otherwise uses the current time. The CLI preserves
 the task's current hours when starting or resuming it.
 `log-hours` defaults `date` to today, requires positive remaining hours,
-and keeps the task open. Use `finish` when the task is complete.
+and keeps the task open. `hours` is read-only. `edit-hours` preserves omitted
+fields from the existing record and updates it through ZenTao's native effort
+workflow. Use `finish` when the task is complete.
 
 ## Usage
 
@@ -128,6 +133,9 @@ lifecycle requests such as `开始`, `暂停`, `继续`, `start`, `pause`, and
 `resume`, and time-entry requests such as `填工时`, `记录工时`, `log hours`,
 and `worklog`. Users do not need to know the internal CLI commands. Reuse any
 date, hours, or work description already supplied instead of asking twice.
+Recognize corrections to an existing time entry. Run `hours`, identify the
+record from returned ids and values, and ask when more than one record could
+match; never guess or call `log-hours` again to compensate for a mistake.
 
 If a list response includes pager data showing more items than returned, tell
 the user the shown and total counts. Do not silently imply the list is complete.
@@ -180,6 +188,11 @@ Bug resolutions are `fixed`, `notrepro`, `duplicate`, `bydesign`, `external`,
 write-back comment is one sentence containing root cause, change summary, and
 the commit hash when committed.
 
+Immediately before confirming any ZenTao write that cites the latest commit,
+run `git rev-parse HEAD` and `git log -1 --format=%h`. Do not reuse a hash from
+earlier conversation. If HEAD is not the item-specific commit, identify the
+relevant commit and tell the user instead of blindly citing HEAD.
+
 For tasks, ask whether to record the current work after the verified result.
 For an incomplete task, collect the actual `consumed` hours and work date. When
 the task has a numeric current `left`, suggest the new `left` by subtracting the
@@ -191,6 +204,15 @@ collect `currentConsumed` and draft a `finish` write. Never infer consumed
 hours. Show all submitted values and require the same explicit ZenTao
 confirmation before either write.
 
+To correct an existing time entry, use `hours` to select its effort id. Show
+the current and proposed `date`, `consumed`, `left`, and `work`, then obtain
+explicit confirmation and call `edit-hours` once. Preserve every field the
+user did not change. Stop when ownership cannot be verified or the edit route
+is unsupported. If the proposed `left` is zero, explicitly warn that ZenTao
+may change the task status as part of its native recalculation. Never edit an
+action comment as a substitute for correcting the underlying work-hour record,
+and never delete a record.
+
 When the user wants to record hours and pause, show both exact writes in one
 confirmation, then run `log-hours` before `pause`. Stop if the hour write fails.
 Do not add lifecycle support for `activate`, `cancel`, or `close`.

package/skills/systems/at-zentao/scripts/zentao-cli.mjs

@@ -459,10 +459,13 @@ async function readInput() {
   return value;
 }
 
-function formBody(fields) {
+function formBody(fields, includeEmpty = []) {
   const body = new URLSearchParams();
+  const keepEmpty = new Set(includeEmpty);
   for (const [key, value] of Object.entries(fields)) {
-    if (value !== undefined && value !== null && value !== "") body.set(key, String(value));
+    if (value !== undefined && value !== null && (value !== "" || keepEmpty.has(key))) {
+      body.set(key, String(value));
+    }
   }
   return body;
 }
@@ -484,8 +487,8 @@ async function workhourVariant(client, id) {
   ];
   for (const variant of variants) {
     try {
-      decodeLegacy(await client.json(variant.route));
-      return variant;
+      const form = decodeLegacy(await client.json(variant.route));
+      return { ...variant, form };
     } catch (error) {
       const unavailable = error instanceof CliError && (
         (error.code === "http_error" && error.status === 404) ||
@@ -500,6 +503,88 @@ async function workhourVariant(client, id) {
   );
 }
 
+function effortRecords(form) {
+  const candidates = [
+    form?.efforts,
+    form?.estimates,
+    form?.workhours,
+    form?.taskEfforts,
+    form?.task?.efforts,
+    form?.task?.estimates,
+  ];
+  const collection = candidates.find((value) => value && typeof value === "object");
+  if (!collection) return [];
+  const entries = Array.isArray(collection)
+    ? collection.map((value) => [null, value])
+    : Object.entries(collection);
+  const records = entries
+    .filter(([, value]) => value && typeof value === "object")
+    .map(([key, value]) => ({
+      ...(value.id === undefined && /^\d+$/.test(key || "") ? { id: Number(key) } : {}),
+      ...pick(value, ["id", "date", "consumed", "left", "work"]),
+    }));
+  return records;
+}
+
+function effortFromEditForm(form) {
+  const effort = form?.effort || form?.estimate || form?.workhour ||
+    (form?.id !== undefined ? form : null);
+  if (!effort || typeof effort !== "object") {
+    throw new CliError("response_error", "ZenTao returned no editable work-hour record");
+  }
+  return effort;
+}
+
+function verifyEffortTask(effort, taskId) {
+  if (effort.objectType !== undefined && effort.objectType !== "task") {
+    throw new CliError("ownership_error", "The work-hour record does not belong to a task");
+  }
+  const owner = effort.objectID ?? effort.task ?? effort.taskID;
+  if (owner === undefined || String(owner) !== String(taskId)) {
+    throw new CliError("ownership_error", "The work-hour record does not belong to the requested task");
+  }
+}
+
+async function editableEffortVariant(client, effortId) {
+  const variants = [
+    { route: `task-editeffort-${effortId}.json`, legacy: false },
+    { route: `task-editestimate-${effortId}.json`, legacy: true },
+  ];
+  for (const variant of variants) {
+    try {
+      const form = decodeLegacy(await client.json(variant.route));
+      return { ...variant, effort: effortFromEditForm(form) };
+    } catch (error) {
+      const unavailable = error instanceof CliError && (
+        (error.code === "http_error" && error.status === 404) ||
+        error.code === "response_error"
+      );
+      if (!unavailable) throw error;
+    }
+  }
+  throw new CliError(
+    "unsupported_version",
+    "ZenTao exposes neither editEffort nor editEstimate for this work-hour record"
+  );
+}
+
+function effortFields(effort, input) {
+  const date = effortDate(input.date ?? effort.date);
+  const consumed = Number(input.consumed ?? effort.consumed);
+  const left = Number(input.left ?? effort.left);
+  const work = input.work ?? effort.work ?? "";
+  if (!Number.isFinite(consumed) || consumed <= 0) {
+    throw new CliError("usage_error", "consumed must be positive");
+  }
+  if (!Number.isFinite(left) || left < 0) {
+    throw new CliError("usage_error", "left must be zero or positive");
+  }
+  if (typeof work !== "string") {
+    throw new CliError("usage_error", "work must be a string");
+  }
+  return { date, consumed, left, work: work.trim() };
+}
+
 function localDateTime(date = new Date()) {
   const part = (value) => String(value).padStart(2, "0");
   return `${date.getFullYear()}-${part(date.getMonth() + 1)}-${part(date.getDate())} ${part(date.getHours())}:${part(date.getMinutes())}:${part(date.getSeconds())}`;
@@ -537,7 +622,9 @@ function help() {
   zentao-cli.mjs start task <id>           # JSON on stdin
   zentao-cli.mjs pause task <id>           # JSON on stdin
   zentao-cli.mjs resume task <id>          # JSON on stdin
+  zentao-cli.mjs hours task <id>
   zentao-cli.mjs log-hours task <id>       # JSON on stdin
+  zentao-cli.mjs edit-hours task <id> <effort-id> # JSON on stdin
   zentao-cli.mjs finish task <id>          # JSON on stdin`;
 }
 
@@ -702,6 +789,36 @@ export async function run(argv, { env = process.env } = {}) {
     return legacyResult(response);
   }
 
+  if (command === "hours") {
+    if (args[0] !== "task") throw new CliError("usage_error", "hours supports tasks only");
+    const id = positiveId(args[1]);
+    const variant = await workhourVariant(client, id);
+    return { records: effortRecords(variant.form) };
+  }
+
+  if (command === "edit-hours") {
+    if (args[0] !== "task") throw new CliError("usage_error", "edit-hours supports tasks only");
+    const taskId = positiveId(args[1]);
+    const effortId = positiveId(args[2]);
+    const input = await readInput();
+    const allowed = ["date", "consumed", "left", "work"];
+    if (!allowed.some((field) => Object.hasOwn(input, field))) {
+      throw new CliError("usage_error", "at least one work-hour field is required");
+    }
+    if (input.work !== undefined && typeof input.work !== "string") {
+      throw new CliError("usage_error", "work must be a string when provided");
+    }
+    const variant = await editableEffortVariant(client, effortId);
+    verifyEffortTask(variant.effort, taskId);
+    const fields = effortFields(variant.effort, input);
+    const response = await client.json(variant.route, {
+      method: "POST",
+      headers: { "content-type": "application/x-www-form-urlencoded" },
+      body: formBody(fields, ["work"]),
+    });
+    return legacyResult(response);
+  }
+
   if (command === "finish") {
     if (args[0] !== "task") throw new CliError("usage_error", "finish supports tasks only");
     const id = positiveId(args[1]);