@islamihab/kds 0.5.0 → 0.7.0

package/index.js

@@ -14420,9 +14420,11 @@ var printHelp = (help) => {
     description: `${field.description ?? ""}${isRequired(field) ? " (required)" : ""}`
   }));
   const usageOptions = options?.length ? " [options]" : "";
-  if (help.description)
-    console.log(`${help.description}
+  if (help.description) {
+    console.log(`${help.description}${help.longDescription ? `
+${help.longDescription}` : ""}
 `);
+  }
   console.log(`Usage: ${help.path}${usageCommands}${usageOptions}${usagePositionals}`);
   const labels = [commands, positionals, options].flatMap((entries) => entries ?? []);
   const width = Math.max(...labels.map(({ label }) => label.length));
@@ -14552,7 +14554,13 @@ var command = (def) => {
   const positionalEntries = Object.entries(inputShape.shape.positionals.shape);
   const optionsEntries = optionEntries(inputShape.shape.options.shape);
   const run = async (args, path) => {
-    const help = () => printHelp({ path, description: def.description, positionals: positionalEntries, options: optionsEntries });
+    const help = () => printHelp({
+      path,
+      description: def.description,
+      longDescription: def.longDescription,
+      positionals: positionalEntries,
+      options: optionsEntries
+    });
     if (args.some(isHelpFlag))
       return help();
     const { values, positionals } = parseArgs({ args, positionalEntries, optionsEntries, help });
@@ -14570,7 +14578,13 @@ var group = (def) => {
   const optionsShape = exports_external.object(def.options);
   const optionsEntries = optionEntries(optionsShape.shape);
   const run = async ([sub, ...rest], path) => {
-    const help = () => printHelp({ path, description: def.description, commands: def.commands, options: optionsEntries });
+    const help = () => printHelp({
+      path,
+      description: def.description,
+      longDescription: def.longDescription,
+      commands: def.commands,
+      options: optionsEntries
+    });
     if (!sub && !def.run || sub === "help" || isHelpFlag(sub))
       return help();
     if (def.run && (sub?.startsWith("-") || !sub)) {
@@ -14597,7 +14611,7 @@ import { join } from "path";
 // package.json
 var package_default = {
   name: "cli",
-  version: "0.5.0",
+  version: "0.7.0",
   private: true,
   type: "module",
   bin: {
@@ -15188,6 +15202,14 @@ var ISSUE_OPEN_STATUSES = [
   "changes_requested",
   "approved"
 ];
+var REVIEW_FINDING_CATEGORIES = [
+  "functional_correctness",
+  "maintainability",
+  "security",
+  "performance"
+];
+var REVIEW_FINDING_SEVERITIES = ["critical", "major", "minor", "trivial"];
+var MAX_REVIEW_FINDINGS = 50;
 var ISSUE_LABEL_COLORS = [
   "gray",
   "red",
@@ -18159,9 +18181,10 @@ var runInbox = async (options) => {
 };
 
 // src/lib/input.ts
-var assertSize = (size) => {
-  if (size > MAX_PAGE_HTML_BYTES)
-    throw new Error(`Page is too large (${size} bytes; max ${MAX_PAGE_HTML_BYTES}).`);
+var assertSize = (size, subject = "Page") => {
+  if (size > MAX_PAGE_HTML_BYTES) {
+    throw new Error(`${subject} is too large (${size} bytes; max ${MAX_PAGE_HTML_BYTES}).`);
+  }
 };
 var readBody = async (path) => {
   if (path === "-") {
@@ -18174,6 +18197,18 @@ var readBody = async (path) => {
   return await file2.text();
 };
 var readTextOption = async (value) => value === "-" ? await Bun.stdin.text() : value;
+var readFileOption = async (path) => {
+  if (path === "-") {
+    const text = await Bun.stdin.text();
+    assertSize(new TextEncoder().encode(text).length, "Input");
+    return text;
+  }
+  const file2 = Bun.file(path);
+  if (!await file2.exists())
+    throw new Error(`No file at ${path}.`);
+  assertSize(file2.size, "Input");
+  return await file2.text();
+};
 var readIssueRef = (value) => {
   const trimmed = value.trim();
   if (/^\d+$/.test(trimmed))
@@ -18389,7 +18424,7 @@ var comment = command({
     body: exports_external.string().describe("Comment markdown, or - for stdin")
   },
   options: {
-    attach: exports_external.array(exports_external.string()).optional().describe("Attach a file to the issue (repeatable)").meta({ short: "a" })
+    attach: exports_external.array(exports_external.string()).optional().describe("Attach a file to the issue (repeatable); the printed URL is usable in issue markdown, and removal is dashboard-only").meta({ short: "a" })
   },
   run: async ({ positionals: { id, body }, options: { attach } }) => {
     const client3 = await backendClient();
@@ -18415,6 +18450,7 @@ var agentConfigurationLine = (id) => {
 var create = command({
   name: "create",
   description: "Create an issue and print its identifier",
+  longDescription: "--disposition ready_for_agent requires --agent-config; the agent queue refuses an issue without one.",
   positionals: {
     title: exports_external.string().describe("Issue title")
   },
@@ -18698,6 +18734,37 @@ More issues match; raise --limit past ${options.limit}.`);
   }
 });
 
+// src/commands/issues/mark-addressed.ts
+var parseFindingRef = (value) => {
+  const match = /^(.+):([1-9]\d*)$/.exec(value);
+  if (!match?.[1] || !match[2])
+    throw new Error(`--finding takes path:line, got "${value}".`);
+  return { path: match[1], line: Number(match[2]) };
+};
+var markAddressed = command({
+  name: "mark-addressed",
+  description: "Mark review findings addressed by a commit and resolve their conversations",
+  positionals: {
+    id: exports_external.string().describe("Issue identifier, number, or URL")
+  },
+  options: {
+    commit: exports_external.string().describe("The commit sha that addressed the findings").meta({ short: "c" }),
+    finding: exports_external.array(exports_external.string()).optional().describe("Mark only this finding, as path:line (repeatable; default all)")
+  },
+  run: async ({ positionals: { id }, options: { commit, finding } }) => {
+    const client3 = await backendClient();
+    const issue2 = await resolveIssue(client3, id);
+    const result = await client3.action(api2.githubReviewer.markAddressed, {
+      id: issue2._id,
+      commitSha: commit,
+      findings: finding?.map(parseFindingRef)
+    });
+    const already = result.alreadyMarked.length ? ` (${result.alreadyMarked.length} already marked)` : "";
+    console.log(`Marked ${result.marked.length} on ${result.identifier} as addressed in ${commit}${already}.`);
+    console.log(result.resolved ? `Resolved ${result.resolved} conversation${result.resolved === 1 ? "" : "s"}.` : "All conversations already resolved.");
+  }
+});
+
 // src/commands/issues/relate.ts
 var relate = command({
   name: "relate",
@@ -18735,6 +18802,8 @@ var remove2 = command({
 var route = command({
   name: "route",
   description: "Route an issue to a disposition (wontfix also cancels it)",
+  longDescription: `The disposition says who acts next; needs_triage is the default. Routing to
+ready_for_agent requires the issue to carry an agent configuration (set --agent-config).`,
   positionals: {
     id: exports_external.string().describe("Issue identifier, number, or URL"),
     disposition: exports_external.enum(ISSUE_DISPOSITIONS).describe("Where the issue goes next")
@@ -18758,6 +18827,9 @@ var route = command({
 var set2 = command({
   name: "set",
   description: "Set an issue's status, priority, estimate, due date, project, milestone, parent, agent configuration, or labels",
+  longDescription: `Status normally moves through the workflow commands and the linked pull request;
+--status is the correction path. Clearing the agent configuration is refused while
+the issue sits in ready_for_agent.`,
   positionals: {
     id: exports_external.string().describe("Issue identifier, number, or URL")
   },
@@ -18832,6 +18904,8 @@ var shellArg = (value) => /^[\w./-]+$/.test(value) ? value : `'${value.replaceAl
 var start = command({
   name: "start",
   description: "Claim implementation work: move unstarted or changes_requested work to in_progress with its branch",
+  longDescription: `Starting never routes the issue: the note printed when the disposition is not
+ready_for_agent is informational, and --ready belongs only to an explicit hand-off.`,
   positionals: {
     id: exports_external.string().describe("Issue identifier, number, or URL")
   },
@@ -18859,15 +18933,16 @@ var start = command({
 // src/commands/issues/start-review.ts
 var startReview = command({
   name: "start-review",
-  description: "Claim review work: move a ready_for_review issue to in_review",
+  description: "Claim review work: move a ready_for_review issue to in_review and announce the review on its pull request",
   positionals: {
     id: exports_external.string().describe("Issue identifier, number, or URL")
   },
   run: async ({ positionals: { id } }) => {
     const client3 = await backendClient();
     const issue2 = await resolveIssue(client3, id);
-    await client3.mutation(api2.issues.startReview, { id: issue2._id });
-    console.log(`Reviewing ${issue2.identifier}: in_review`);
+    const started = await client3.action(api2.githubReviewer.startReview, { id: issue2._id });
+    console.log(`Reviewing ${started.identifier}: in_review`);
+    console.log(`Announced on ${started.prUrl}; check run open.`);
   }
 });
 
@@ -18886,11 +18961,81 @@ var submit = command({
   }
 });
 
+// src/commands/issues/submit-review.ts
+var findingsSchema = exports_external.array(exports_external.object({
+  path: exports_external.string().min(1),
+  line: exports_external.number().int().positive(),
+  startLine: exports_external.number().int().positive().optional(),
+  category: exports_external.enum(REVIEW_FINDING_CATEGORIES),
+  severity: exports_external.enum(REVIEW_FINDING_SEVERITIES),
+  summary: exports_external.string().min(1),
+  body: exports_external.string().min(1),
+  diff: exports_external.string().optional()
+})).min(1).max(MAX_REVIEW_FINDINGS);
+var readFindings = async (path) => {
+  const text = await readFileOption(path);
+  let json2;
+  try {
+    json2 = JSON.parse(text);
+  } catch {
+    throw new Error("The findings file is not valid JSON.");
+  }
+  const parsed = findingsSchema.safeParse(json2);
+  if (!parsed.success)
+    throw new Error(`The findings file is invalid:
+${exports_external.prettifyError(parsed.error)}`);
+  return parsed.data;
+};
+var submitReview = command({
+  name: "submit-review",
+  description: "Submit the review verdict on an issue's linked pull request as the reviewer App",
+  longDescription: `Findings are a JSON array (at most ${MAX_REVIEW_FINDINGS}) of objects with path, line, category,
+severity, summary, and body, plus optional startLine and diff.
+Categories: ${REVIEW_FINDING_CATEGORIES.join(", ")}; severities: ${REVIEW_FINDING_SEVERITIES.join(", ")}.`,
+  positionals: {
+    id: exports_external.string().describe("Issue identifier, number, or URL")
+  },
+  options: {
+    approve: exports_external.boolean().default(false).describe("Approve: bare APPROVE plus a clean bill"),
+    "request-changes": exports_external.boolean().default(false).describe("Request changes from a findings file"),
+    findings: exports_external.string().optional().describe("Findings JSON file, or - for stdin (with --request-changes)"),
+    bill: exports_external.string().optional().describe("Clean-bill text, or - for stdin (with --approve)")
+  },
+  run: async ({ positionals: { id }, options }) => {
+    if (options.approve === options["request-changes"]) {
+      throw new Error("Pass exactly one of --approve or --request-changes.");
+    }
+    if (options.approve && options.findings !== undefined)
+      throw new Error("--findings goes with --request-changes.");
+    if (options["request-changes"] && options.bill !== undefined)
+      throw new Error("--bill goes with --approve.");
+    let verdict;
+    if (options.approve) {
+      if (options.bill === undefined)
+        throw new Error("--approve needs the clean bill: --bill <text>, or - for stdin.");
+      verdict = { kind: "approve", bill: await readTextOption(options.bill) };
+    } else {
+      if (options.findings === undefined) {
+        throw new Error("--request-changes needs the findings: --findings <file>, or - for stdin.");
+      }
+      verdict = { kind: "request_changes", findings: await readFindings(options.findings) };
+    }
+    const client3 = await backendClient();
+    const issue2 = await resolveIssue(client3, id);
+    const submitted = await client3.action(api2.githubReviewer.submitReview, { id: issue2._id, verdict });
+    console.log(`Submitted review on ${submitted.identifier}: ${submitted.prUrl}`);
+    console.log(submitted.summary);
+  }
+});
+
 // src/commands/issues/tasks.ts
 var position = exports_external.array(exports_external.coerce.number().int().positive());
 var tasks = command({
   name: "tasks",
   description: "Show an issue's checklist, or add, tick, promote, and drop its tasks",
+  longDescription: `Tasks have no identifier, status, disposition, or feed, and ticking one files no
+activity. Task numbers resolve against the listing as printed, so one call may
+address several rows even as removals renumber it.`,
   positionals: {
     id: exports_external.string().describe("Issue identifier, number, or URL")
   },
@@ -18898,7 +19043,7 @@ var tasks = command({
     add: exports_external.array(exports_external.string()).optional().describe("Add a task (repeatable)").meta({ short: "a" }),
     check: position.optional().describe("Tick a task by its number (repeatable)"),
     uncheck: position.optional().describe("Untick a task by its number (repeatable)"),
-    convert: position.optional().describe("Promote a task into its own issue (repeatable)"),
+    convert: position.optional().describe("Promote a task into a sub-issue (repeatable); the new issue inherits the project and milestone, arrives in needs_triage, and consumes the task \u2014 a related issue instead when this issue is already a sub-issue"),
     remove: position.optional().describe("Drop a task by its number (repeatable)"),
     json: exports_external.boolean().default(false).describe("Print as JSON")
   },
@@ -18987,7 +19132,7 @@ var update2 = command({
   options: {
     title: exports_external.string().optional().describe("New title").meta({ short: "t" }),
     description: exports_external.string().optional().describe("New markdown description, or - for stdin").meta({ short: "d" }),
-    attach: exports_external.array(exports_external.string()).optional().describe("Attach a file to the issue (repeatable)").meta({ short: "a" })
+    attach: exports_external.array(exports_external.string()).optional().describe("Attach a file to the issue (repeatable); the printed URL is usable in issue markdown, and removal is dashboard-only").meta({ short: "a" })
   },
   run: async ({ positionals: { id }, options: { title, description, attach } }) => {
     if (title === undefined && description === undefined && attach === undefined)
@@ -19010,6 +19155,16 @@ var update2 = command({
 var issues = group({
   name: "issues",
   description: "Track and triage issues",
+  longDescription: `An issue moves on three independent axes: status (the lifecycle, in order: backlog,
+todo, in_progress, ready_for_review, in_review, changes_requested, approved, done,
+canceled), priority, and disposition (who acts next). The workflow commands \u2014 start,
+submit, start-review, submit-review \u2014 and the linked pull request move the status;
+each refuses an issue outside its own status, and \`set -s\` is for corrections.
+The repo link is never set by hand: work on a branch whose name contains the issue
+identifier and the branch, pull request, and status track automatically \u2014 a change
+request moves the issue to changes_requested, an approval to approved (one
+outstanding change request outweighs any number of approvals), and a merge lands
+it as done.`,
   commands: [
     create,
     list2,
@@ -19021,6 +19176,8 @@ var issues = group({
     start,
     submit,
     startReview,
+    submitReview,
+    markAddressed,
     tasks,
     relate,
     unrelate,
@@ -19217,6 +19374,10 @@ var versions2 = command({
 var pages = group({
   name: "pages",
   description: "Publish HTML documents to the web",
+  longDescription: `Themed pages (the default) render inside the site chrome under a strict CSP: only
+the site theme's styles apply \u2014 inline style attributes and author scripts are
+dropped. A self-contained document with its own CSS or JS needs raw mode, which
+serves it verbatim. A page keeps its URL across updates and reverts.`,
   commands: [create3, list3, get2, update3, versions2, revert, remove3]
 });
 
@@ -19432,6 +19593,8 @@ var update4 = command({
 var projects = group({
   name: "projects",
   description: "Manage projects",
+  longDescription: `Connect a repository (set --repo) to make --here resolve in that checkout and to
+let issue branches and pull requests link automatically.`,
   commands: [create4, list4, get3, update4, set3, remove4]
 });
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@islamihab/kds",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "Command-line client for Kai Dev Studio",
   "license": "MIT",
   "publishConfig": {