jiradc-cli 1.0.41 → 1.0.43

package/dist/index.js

@@ -2393,33 +2393,45 @@ async function withNames(client, structureId, rows) {
     itemId: r.itemId
   }));
 }
+function resolveEnclosingRow(opts, fallback = 0) {
+  const { parent, under } = opts;
+  if (parent !== void 0 && under !== void 0 && parent !== under) {
+    throw new CliUsageError(
+      `--parent (${parent}) and --under (${under}) are the same option and disagree`,
+      "They are aliases; pass only one."
+    );
+  }
+  return parent ?? under ?? fallback;
+}
 
 // src/commands/structure/folder/create.ts
 function create7(parent) {
   const cmd = parent.command("create").description("Create a folder in a structure");
   scopeIdOption(cmd, "structure", { mandatory: true });
   cmd.requiredOption("--name <text>", "Folder name", text);
-  cmd.option("--under <rowId>", "Parent folder row id (0 = top level)", integer, 0);
+  cmd.option("--under <rowId>", "Parent folder row id (0 = top level)", integer);
+  cmd.option("--parent <rowId>", "Alias for --under", integer);
   examples(cmd, ["--structure 42 --name Backlog", '--structure 42 --name "Phase Two" --under 1001']);
   cmd.action(async (opts) => {
+    const under = resolveEnclosingRow(opts);
     const client = getClient();
     const structureId = await resolveStructureId(client, opts.structure);
     const forest = await client.structure.getForest({ structureId });
-    if (opts.under !== 0) {
-      assertRowExists(parseForest(forest), opts.under, structureId, "Target parent row");
+    if (under !== 0) {
+      assertRowExists(parseForest(forest), under, structureId, "Target parent row");
     }
     const result = await client.structure.createFolder({
       structureId,
       version: forest.version,
       name: opts.name,
-      under: opts.under
+      under
     });
     output({
       structureId,
       itemId: result.itemId,
       rowId: result.newRowIds?.[0] ?? null,
       name: opts.name,
-      under: opts.under
+      under
     });
   });
 }
@@ -2460,7 +2472,8 @@ function get7(parent) {
 function list8(parent) {
   const cmd = parent.command("list").description("List folders in a structure");
   scopeIdOption(cmd, "structure", { mandatory: true });
-  cmd.option("--parent <rowId>", "Only look under this folder row (default: top level)", integer, 0);
+  cmd.option("--parent <rowId>", "Only look under this folder row (default: top level)", integer);
+  cmd.option("--under <rowId>", "Alias for --parent", integer);
   cmd.option("--depth <n>", "How many levels below the parent to include", integer, 1);
   cmd.option("--query <text>", "Only folders whose name contains this text, at any depth", text);
   paginationOptions(cmd, { defaultLimit: 25 });
@@ -2476,7 +2489,8 @@ function list8(parent) {
       const structureId = await resolveStructureId(client, opts.structure);
       const forest = await client.structure.getForest({ structureId });
       const rows = parseForest(forest);
-      const scoped = opts.query ? opts.parent === 0 ? rows : descendantsOf(rows, opts.parent) : withinDepth(rows, opts.parent, opts.depth);
+      const parent2 = resolveEnclosingRow(opts);
+      const scoped = opts.query ? parent2 === 0 ? rows : descendantsOf(rows, parent2) : withinDepth(rows, parent2, opts.depth);
       const folders = scoped.filter((r) => r.isFolder);
       let named = await withNames(client, structureId, folders);
       if (opts.query) {
@@ -2515,16 +2529,19 @@ function get8(parent) {
 function list9(parent) {
   const cmd = parent.command("list").description("List every structure visible to you");
   cmd.option("--permissions", "Include each structure\u2019s permission rules");
+  cmd.option("--query <text>", "Only structures whose name contains this text", text);
   paginationOptions(cmd, { defaultLimit: 25 });
   cmd.option("--all", "Collect every match, not just one page");
-  examples(cmd, ["", "--limit 50", "--all --permissions"]);
+  examples(cmd, ["", "--query billing", "--limit 50", "--all --permissions"]);
   cmd.action(async (opts) => {
     if (opts.all && process.argv.includes("--limit")) {
       const { CliUsageError: CliUsageError2 } = await import("./dist-JXPWCMQP.js");
       throw new CliUsageError2("--all and --limit ask for opposite things; pass one or the other");
     }
     const client = getClient();
-    const { structures } = await client.structure.list({ withPermissions: opts.permissions });
+    const { structures: found } = await client.structure.list({ withPermissions: opts.permissions });
+    const needle = opts.query?.toLowerCase();
+    const structures = needle ? found.filter((s) => (s.name ?? "").toLowerCase().includes(needle)) : found;
     const start = opts.start ?? 0;
     const page = opts.all ? structures.slice(start) : structures.slice(start, start + opts.limit);
     output({ total: structures.length, start, count: page.length, structures: page });
@@ -2536,24 +2553,26 @@ function add(parent) {
   const cmd = parent.command("add").description("Add an issue to a structure, under a folder");
   scopeIdOption(cmd, "structure", { mandatory: true });
   cmd.requiredOption("--issue <key>", "Issue key to place, e.g. PROJ-123", text);
-  cmd.option("--under <rowId>", "Parent folder row id (0 = top level)", integer, 0);
+  cmd.option("--under <rowId>", "Parent folder row id (0 = top level)", integer);
+  cmd.option("--parent <rowId>", "Alias for --under", integer);
   examples(cmd, ["--structure 42 --issue PROJ-123 --under 1001", '--structure "My Structure" --issue PROJ-123']);
   cmd.action(async (opts) => {
+    const under = resolveEnclosingRow(opts);
     const client = getClient();
     const structureId = await resolveStructureId(client, opts.structure);
     const issue = await client.issues.get({ issueKeyOrId: opts.issue, fields: ["summary"] });
     const issueId = Number(issue.id);
     const forest = await client.structure.getForest({ structureId });
     const rows = parseForest(forest);
-    if (opts.under !== 0) assertRowExists(rows, opts.under, structureId, "Target parent row");
-    const already = childrenOf(rows, opts.under).find((r) => r.itemType === "issue" && r.itemNumericId === issueId);
-    const elsewhere = rows.filter((r) => r.itemType === "issue" && r.itemNumericId === issueId && r.parentRowId !== opts.under).map((r) => ({ rowId: r.rowId, parentRowId: r.parentRowId }));
+    if (under !== 0) assertRowExists(rows, under, structureId, "Target parent row");
+    const already = childrenOf(rows, under).find((r) => r.itemType === "issue" && r.itemNumericId === issueId);
+    const elsewhere = rows.filter((r) => r.itemType === "issue" && r.itemNumericId === issueId && r.parentRowId !== under).map((r) => ({ rowId: r.rowId, parentRowId: r.parentRowId }));
     if (already) {
       output({
         structureId,
         issue: issue.key,
         rowId: already.rowId,
-        under: opts.under,
+        under,
         added: false,
         reason: "already under this parent",
         alsoAppearsAt: elsewhere
@@ -2563,13 +2582,13 @@ function add(parent) {
     const result = await client.structure.updateForest({
       structureId,
       version: forest.version,
-      actions: [{ action: "add", under: opts.under, after: 0, before: 0, forest: addSpec(issueId) }]
+      actions: [{ action: "add", under, after: 0, before: 0, forest: addSpec(issueId) }]
     });
     output({
       structureId,
       issue: issue.key,
       rowId: result.newRowIds?.[0] ?? null,
-      under: opts.under,
+      under,
       added: true,
       alsoAppearsAt: elsewhere
     });
@@ -2580,17 +2599,36 @@ function add(parent) {
 function list10(parent) {
   const cmd = parent.command("list").description("List rows (issues and folders) under a parent row");
   scopeIdOption(cmd, "structure", { mandatory: true });
-  cmd.option("--parent <rowId>", "Parent row id (0 = top level)", integer, 0);
+  cmd.option("--parent <rowId>", "Parent row id (0 = top level)", integer);
+  cmd.option("--under <rowId>", "Alias for --parent", integer);
   cmd.option("--depth <n>", "How many levels below the parent to include", integer, 1);
+  cmd.option("--issue <key>", "Only rows for this issue, wherever they are in the structure", text);
   paginationOptions(cmd, { defaultLimit: 25 });
   cmd.option("--all", "Collect every match, not just one page");
-  examples(cmd, ["--structure 42", '--structure "My Structure" --parent 1001 --depth 2']);
+  examples(cmd, [
+    "--structure 42",
+    '--structure "My Structure" --parent 1001 --depth 2',
+    '--structure "My Structure" --issue PROJ-123'
+  ]);
   cmd.action(
     async (opts) => {
       const client = getClient();
       const structureId = await resolveStructureId(client, opts.structure);
       const rows = parseForest(await client.structure.getForest({ structureId }));
-      const scoped = withinDepth(rows, opts.parent, opts.depth);
+      if (opts.issue !== void 0 && (opts.parent !== void 0 || opts.under !== void 0)) {
+        throw new CliUsageError(
+          "--issue and --parent ask different questions; pass one",
+          "--issue finds an issue wherever it sits; --parent lists what is under a row."
+        );
+      }
+      let scoped;
+      if (opts.issue !== void 0) {
+        const issue = await client.issues.get({ issueKeyOrId: opts.issue, fields: ["summary"] });
+        const issueId = Number(issue.id);
+        scoped = rows.filter((r) => r.itemType === "issue" && r.itemNumericId === issueId);
+      } else {
+        scoped = withinDepth(rows, resolveEnclosingRow(opts), opts.depth);
+      }
       const start = opts.start ?? 0;
       const page = opts.all ? scoped.slice(start) : scoped.slice(start, start + opts.limit);
       output({
@@ -2609,22 +2647,27 @@ function move(parent) {
   const cmd = parent.command("move").description("Move a row to a different parent");
   subjectArg(cmd, "rowId", { description: "Row id to move (not the issue id)", parser: positiveInt });
   scopeIdOption(cmd, "structure", { mandatory: true });
-  cmd.requiredOption("--under <rowId>", "New parent row id (0 = top level)", integer);
+  cmd.option("--under <rowId>", "New parent row id (0 = top level)", integer);
+  cmd.option("--parent <rowId>", "Alias for --under", integer);
   examples(cmd, ["1002 --structure 42 --under 1001", '1002 --structure "My Structure" --under 0']);
   cmd.action(async (rowId, opts) => {
+    if (opts.under === void 0 && opts.parent === void 0) {
+      throw new CliUsageError("A destination is required", "Pass --under <rowId> (or its alias --parent).");
+    }
+    const under = resolveEnclosingRow(opts);
     const client = getClient();
     const structureId = await resolveStructureId(client, opts.structure);
     const forest = await client.structure.getForest({ structureId });
     const rows = parseForest(forest);
     assertRowExists(rows, rowId, structureId);
-    if (opts.under !== 0) assertRowExists(rows, opts.under, structureId, "Target parent row");
+    if (under !== 0) assertRowExists(rows, under, structureId, "Target parent row");
     const row = rows.find((r) => r.rowId === rowId);
     const result = await client.structure.updateForest({
       structureId,
       version: forest.version,
-      actions: [{ action: "move", rowId, under: opts.under, after: 0, before: 0 }]
+      actions: [{ action: "move", rowId, under, after: 0, before: 0 }]
     });
-    output({ structureId, rowId, from: row.parentRowId, under: opts.under, moved: result.successfulActions > 0 });
+    output({ structureId, rowId, from: row.parentRowId, under, moved: result.successfulActions > 0 });
   });
 }
 
@@ -2668,39 +2711,56 @@ function search3(parent) {
     parser: nonEmpty
   });
   scopeIdOption(cmd, "structure", { mandatory: true });
-  cmd.option("--fields <fields>", "Comma-separated fields to return", text);
+  cmd.option("--fields <fields>", "Comma-separated fields to return, by name or id", text);
+  cmd.option("--all-fields", "Return all fields instead of defaults");
   paginationOptions(cmd, { defaultLimit: 25, maxLimit: 50 });
   examples(cmd, [
     `"child of folder('Billing')" --structure "My Structure"`,
     `"descendants of folder('Billing')" --structure 42 --limit 50`
   ]);
-  cmd.action(async (sjql, opts) => {
-    for (const [name, value] of [
-      ["--structure", opts.structure],
-      ["<sjql>", sjql]
-    ]) {
-      if (value.includes('"')) {
+  cmd.action(
+    async (sjql, opts) => {
+      for (const [name, value] of [
+        ["--structure", opts.structure],
+        ["<sjql>", sjql]
+      ]) {
+        if (value.includes('"')) {
+          throw new CliUsageError(
+            `${name} must not contain a double quote \u2014 S-JQL uses single quotes inside, e.g. "child of folder('Billing')"`
+          );
+        }
+      }
+      const client = getClient();
+      const fields = await selectFields(client, opts, SEARCH_DEFAULT_FIELDS);
+      const jql = `issue in structure("${opts.structure}", "${sjql}")`;
+      let res;
+      try {
+        res = await client.issues.search({
+          jql,
+          startAt: opts.start ?? 0,
+          maxResults: opts.limit,
+          fields
+        });
+      } catch (err) {
+        const detail = err.response?.data;
+        const raw = detail === void 0 ? "" : JSON.stringify(detail);
+        if (!raw.includes("Structure query")) throw err;
+        const suggestion = /did you mean ([^"]+?)\?/.exec(raw)?.[1];
         throw new CliUsageError(
-          `${name} must not contain a double quote \u2014 S-JQL uses single quotes inside, e.g. "child of folder('Billing')"`
+          `Structure rejected the query ${JSON.stringify(sjql)}`,
+          suggestion !== void 0 ? `The query is S-JQL, not JQL. Structure suggests: ${suggestion}.` : `The query is S-JQL, not JQL \u2014 use shapes like "child of folder('Name')", "descendants of folder('Name')" or "issue in (PROJ-123)", with single quotes inside.`,
+          detail
         );
       }
+      output({
+        jql,
+        total: res.total,
+        startAt: res.startAt,
+        count: res.issues?.length ?? 0,
+        issues: (res.issues ?? []).map(transformIssue)
+      });
     }
-    const client = getClient();
-    const jql = `issue in structure("${opts.structure}", "${sjql}")`;
-    const res = await client.issues.search({
-      jql,
-      startAt: opts.start ?? 0,
-      maxResults: opts.limit,
-      fields: opts.fields
-    });
-    output({
-      jql,
-      total: res.total,
-      startAt: res.startAt,
-      count: res.issues?.length ?? 0,
-      issues: (res.issues ?? []).map(transformIssue)
-    });
-  });
+  );
 }
 
 // src/commands/structure/index.ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jiradc-cli",
-  "version": "1.0.41",
+  "version": "1.0.43",
   "publish": true,
   "type": "module",
   "main": "dist/index.js",