@islamihab/kds 0.6.0 → 0.8.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.6.0",
+  version: "0.8.0",
   private: true,
   type: "module",
   bin: {
@@ -18410,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();
@@ -18422,6 +18436,7 @@ var comment = command({
 });
 
 // src/lib/agents.ts
+var agentConfigurationForActor = (actor) => AGENT_CONFIGURATION_OPTIONS.find((entry) => AGENT_HARNESS_LABELS[entry.harness] === actor.harness && entry.model === actor.model)?.id;
 var agentConfigurationLegacyNote = () => {
   const legacy = AGENT_CONFIGURATION_OPTIONS.filter((entry) => entry.lifecycle === "legacy");
   return legacy.length === 0 ? "" : ` (legacy: ${legacy.map((entry) => entry.id).join(", ")})`;
@@ -18436,6 +18451,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")
   },
@@ -18787,6 +18803,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")
@@ -18810,6 +18828,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")
   },
@@ -18884,22 +18905,36 @@ 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")
   },
   options: {
-    ready: exports_external.boolean().default(false).describe("Also route the issue to ready_for_agent")
+    ready: exports_external.boolean().default(false).describe("Also route the issue to ready_for_agent, assigning the running agent when it is identifiable")
   },
   run: async ({ positionals: { id }, options: { ready } }) => {
     const client3 = await backendClient();
     const issue2 = await resolveIssue(client3, id);
     const { branch } = await client3.mutation(api2.issues.start, { id: issue2._id });
+    let assigned;
+    if (ready) {
+      const actor = await agentClaim();
+      const configurationId = actor && agentConfigurationForActor(actor);
+      if (configurationId && configurationId !== issue2.agentConfigurationId) {
+        await client3.mutation(api2.issues.setAgentConfiguration, {
+          id: issue2._id,
+          agentConfigurationId: configurationId
+        });
+        assigned = configurationId;
+      }
+    }
     if (ready && issue2.disposition !== "ready_for_agent") {
       await client3.mutation(api2.issues.route, { id: issue2._id, disposition: "ready_for_agent" });
     }
     console.log(`Started ${issue2.identifier}: in_progress, branch ${branch}`);
     if (ready) {
-      console.log("Routed to ready_for_agent.");
+      console.log(`Routed to ready_for_agent${assigned ? `, assigned ${agentConfiguration(assigned).label}` : ""}.`);
     } else if (issue2.disposition !== "ready_for_agent" && await agentClaim()) {
       console.log(`Note: disposition is ${issue2.disposition}. Pass --ready if this hand-off was intended.`);
     }
@@ -18967,6 +19002,9 @@ ${exports_external.prettifyError(parsed.error)}`);
 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")
   },
@@ -19008,6 +19046,9 @@ var position = exports_external.array(exports_external.coerce.number().int().pos
 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")
   },
@@ -19015,7 +19056,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")
   },
@@ -19104,7 +19145,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)
@@ -19127,6 +19168,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,
@@ -19336,6 +19387,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]
 });
 
@@ -19551,6 +19606,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.6.0",
+  "version": "0.8.0",
   "description": "Command-line client for Kai Dev Studio",
   "license": "MIT",
   "publishConfig": {