issy 0.8.0 → 0.9.0

package/README.md

@@ -1,5 +1,5 @@
 <p align="center">
-  <img src="https://raw.githubusercontent.com/miketromba/issy/main/assets/issy-logo.png" alt="issy" width="600" />
+  <img src="https://raw.githubusercontent.com/miketromba/issy/main/assets/issy-banner.png" alt="issy" width="600" />
 </p>
 
 <p align="center">
@@ -10,7 +10,8 @@
 
 <p align="center">
   <strong>AI-native issue tracking.</strong><br>
-  Tell your coding assistant what to track. It handles the rest.
+  Tell your coding assistant what to track. It handles the rest.<br>
+  <a href="https://issy.sh">issy.sh</a>
 </p>
 
 ---
@@ -77,6 +78,7 @@ Once installed globally, you can run commands from your terminal:
 ```bash
 issy                          # Start the web UI
 issy list                     # List open issues (roadmap order)
+issy list --unblocked         # List open issues with no open blockers
 issy next                     # Show next issue to work on
 issy create --title "Bug"     # Create an issue
 ```
@@ -123,12 +125,15 @@ Opens a local read-only UI at `http://localhost:1554` for browsing issues.
 issy init                     # Create .issy/issues/ directory
 issy init --seed              # Create with a welcome issue
 issy list                     # List open issues (roadmap order)
+issy list --unblocked         # List open issues with no open blockers
 issy next                     # Show next issue to work on
 issy search "auth"            # Fuzzy search
 issy read 0001                # View issue
 issy create --title "Bug" --after 0002    # Create issue after #0002
+issy create --title "Feature" --depends-on 0012,0035 --last  # Blocked by issues
 issy create --title "Bug" --body "Details here" --last  # Create with body content
 issy update 0001 --before 0003            # Reposition in roadmap
+issy update 0001 --depends-on 0012,0035   # Replace blockers
 issy update 0001 --body "New details"     # Replace body content
 issy close 0001               # Close issue
 issy reopen 0001 --after 0004 # Reopen and place in roadmap
@@ -159,6 +164,14 @@ issy list --sort priority     # Sort by priority instead
 issy list --sort created      # Sort by creation date
 ```
 
+The `Blk` column in `issy list` shows the count of currently open blockers. `-` means the issue is unblocked. Use `issy list --unblocked` to show only open issues that have no open blockers. Dependency IDs that do not match an existing issue are ignored.
+
+Issues can declare blockers with `depends_on`:
+
+```yaml
+depends_on: 0012, 0035
+```
+
 ### Hooks
 
 issy supports optional hook files in `.issy/` that inject context into stdout after successful operations. The file contents are printed directly, making them visible to AI agents in their command output.
@@ -210,6 +223,7 @@ scope: medium
 type: bug
 status: open
 order: a0
+depends_on: 0012, 0035
 created: 2025-01-15T10:30:00
 ---
 
@@ -227,6 +241,7 @@ session isn't established, causing a redirect loop.
 | `status` | `open`, `closed` |
 | `labels` | comma-separated (optional) |
 | `order` | fractional index key (managed by issy) |
+| `depends_on` | comma-separated blocking issue IDs (optional) |
 
 ## Configuration
 

package/dist/cli.js

@@ -355,6 +355,9 @@ function generateFrontmatter(data) {
   if (data.order) {
     lines.push(`order: ${data.order}`);
   }
+  if (data.depends_on) {
+    lines.push(`depends_on: ${data.depends_on}`);
+  }
   lines.push(`created: ${data.created}`);
   if (data.updated) {
     lines.push(`updated: ${data.updated}`);
@@ -363,6 +366,44 @@ function generateFrontmatter(data) {
   return lines.join(`
 `);
 }
+function parseDependencyIds(dependsOn) {
+  if (!dependsOn)
+    return [];
+  const seen = new Set;
+  const ids = [];
+  for (const token of dependsOn.split(/[,\s]+/)) {
+    const value = token.trim().replace(/^['"]+|['"]+$/g, "").replace(/^#/, "");
+    if (!/^\d+$/.test(value))
+      continue;
+    const id = value.padStart(4, "0");
+    if (seen.has(id))
+      continue;
+    seen.add(id);
+    ids.push(id);
+  }
+  return ids;
+}
+function filterExistingDependencyIds(dependsOn, issues, excludeId) {
+  const existingIds = new Set(issues.map((issue) => issue.id));
+  const excludedId = excludeId?.padStart(4, "0");
+  return parseDependencyIds(dependsOn).filter((id) => existingIds.has(id) && id !== excludedId);
+}
+function formatExistingDependencyIds(dependsOn, issues, excludeId) {
+  return filterExistingDependencyIds(dependsOn, issues, excludeId).join(", ");
+}
+function getDependencyIssues(issue, issues) {
+  const dependencyIds = filterExistingDependencyIds(issue.frontmatter.depends_on, issues, issue.id);
+  if (dependencyIds.length === 0)
+    return [];
+  const issueById = new Map(issues.map((i) => [i.id, i]));
+  return dependencyIds.map((id) => issueById.get(id)).filter((dependency) => Boolean(dependency));
+}
+function getBlockingIssues(issue, issues) {
+  return getDependencyIssues(issue, issues).filter((dependency) => dependency.frontmatter.status === "open");
+}
+function isIssueUnblocked(issue, issues) {
+  return issue.frontmatter.status === "open" && getBlockingIssues(issue, issues).length === 0;
+}
 function getIssueIdFromFilename(filename) {
   const match = filename.match(/^(\d+)-/);
   return match ? match[1] : filename.replace(".md", "");
@@ -496,6 +537,8 @@ async function createIssue(input) {
   const issueNumber = await getNextIssueNumber();
   const slug = createSlug(input.title);
   const filename = `${issueNumber}-${slug}.md`;
+  const existingIssues = await getAllIssues();
+  const dependsOn = formatExistingDependencyIds(input.depends_on, existingIssues, issueNumber);
   const frontmatter = {
     title: input.title,
     priority,
@@ -504,6 +547,7 @@ async function createIssue(input) {
     labels: input.labels || undefined,
     status: "open",
     order: input.order || undefined,
+    depends_on: dependsOn || undefined,
     created: formatDate()
   };
   const body = input.body ?? `
@@ -529,6 +573,8 @@ async function updateIssue(id, input) {
   if (!issue) {
     throw new Error(`Issue not found: ${id}`);
   }
+  const allIssues = await getAllIssues();
+  const dependsOn = input.depends_on !== undefined ? formatExistingDependencyIds(input.depends_on, allIssues, issue.id) : undefined;
   const updatedFrontmatter = {
     ...issue.frontmatter,
     ...input.title && { title: input.title },
@@ -540,6 +586,9 @@ async function updateIssue(id, input) {
     },
     ...input.status && { status: input.status },
     ...input.order && { order: input.order },
+    ...input.depends_on !== undefined && {
+      depends_on: dependsOn || undefined
+    },
     updated: formatDate()
   };
   const updatedContent = input.body !== undefined ? `
@@ -2039,6 +2088,14 @@ function filterByQuery(issues, query) {
         if (issue.frontmatter.status !== statusValue) {
           return false;
         }
+      } else if (statusValue === "unblocked") {
+        if (!isIssueUnblocked(issue, issues)) {
+          return false;
+        }
+      } else if (statusValue === "blocked") {
+        if (issue.frontmatter.status !== "open" || isIssueUnblocked(issue, issues)) {
+          return false;
+        }
       }
     }
     if (parsed.qualifiers.priority) {
@@ -2126,7 +2183,23 @@ function typeSymbol(type) {
 }
 function formatIssueRow(issue) {
   const status = issue.frontmatter.status === "open" ? "OPEN  " : "CLOSED";
-  return `  ${issue.id}  ${prioritySymbol(issue.frontmatter.priority)}   ${typeSymbol(issue.frontmatter.type)}    ${status}  ${issue.frontmatter.title}`;
+  const blocked = issue.blockers > 0 ? String(issue.blockers) : "-";
+  return `  ${issue.id}  ${prioritySymbol(issue.frontmatter.priority)}   ${typeSymbol(issue.frontmatter.type)}    ${status}  ${blocked.padEnd(3)}  ${issue.frontmatter.title}`;
+}
+function printDependsOn(issue, issues) {
+  const dependencyIssues = getDependencyIssues(issue, issues);
+  if (dependencyIssues.length === 0)
+    return;
+  console.log(`  Depends on:  ${dependencyIssues.map((i) => `#${i.id}`).join(", ")}`);
+}
+function getDependsOnArg(values) {
+  const value = values["depends-on"];
+  return typeof value === "string" ? value : undefined;
+}
+async function resolveDependsOn(value, excludeId) {
+  if (value === undefined)
+    return;
+  return formatExistingDependencyIds(value, await getAllIssues(), excludeId);
 }
 async function resolvePosition(opts) {
   const openIssues = await getOpenIssuesByOrder();
@@ -2158,7 +2231,7 @@ function hasHelpFlag(commandArgs) {
 async function listIssues(options) {
   const allIssues = await getAllIssues();
   const queryParts = [];
-  if (!options.all)
+  if (!options.all && !options.unblocked)
     queryParts.push("is:open");
   if (options.priority)
     queryParts.push(`priority:${options.priority}`);
@@ -2170,17 +2243,23 @@ async function listIssues(options) {
     queryParts.push(`sort:${options.sort}`);
   if (options.search)
     queryParts.push(options.search);
-  const query = queryParts.join(" ") || "is:open";
-  const issues = filterByQuery(allIssues, query);
+  const query = queryParts.join(" ");
+  let issues = query ? filterByQuery(allIssues, query) : allIssues;
+  if (options.unblocked) {
+    issues = issues.filter((issue) => isIssueUnblocked(issue, allIssues));
+  }
   if (issues.length === 0) {
     console.log("No issues found.");
     return;
   }
   console.log(`
-  ID    Pri  Type  Status   Title`);
+  ID    Pri  Type  Status  Blk  Title`);
   console.log(`  ${"-".repeat(100)}`);
   for (const issue of issues) {
-    console.log(formatIssueRow(issue));
+    console.log(formatIssueRow({
+      ...issue,
+      blockers: getBlockingIssues(issue, allIssues).length
+    }));
   }
   console.log(`
   Total: ${issues.length} issue(s)
@@ -2188,6 +2267,7 @@ async function listIssues(options) {
 }
 async function readIssue(id) {
   const issue = await getIssue(id);
+  const allIssues = await getAllIssues();
   if (!issue) {
     console.error(`Issue not found: ${id}`);
     process.exit(1);
@@ -2206,6 +2286,7 @@ ${"=".repeat(70)}`);
   if (issue.frontmatter.labels) {
     console.log(`  Labels:      ${issue.frontmatter.labels}`);
   }
+  printDependsOn(issue, allIssues);
   if (issue.frontmatter.order) {
     console.log(`  Order:       ${issue.frontmatter.order}`);
   }
@@ -2228,10 +2309,13 @@ async function searchIssuesCommand(query, options) {
   console.log(`
   Search results for "${query}":`);
   console.log(`
-  ID    Pri  Type  Status   Title`);
+  ID    Pri  Type  Status  Blk  Title`);
   console.log(`  ${"-".repeat(100)}`);
   for (const issue of issues) {
-    console.log(formatIssueRow(issue));
+    console.log(formatIssueRow({
+      ...issue,
+      blockers: getBlockingIssues(issue, allIssues).length
+    }));
   }
   console.log(`
   Found: ${issues.length} issue(s)
@@ -2257,6 +2341,7 @@ async function createIssueCommand(options) {
       scope: options.scope,
       type: options.type,
       labels: options.labels,
+      depends_on: await resolveDependsOn(options.dependsOn) || undefined,
       order
     };
     const issue = await createIssue(input);
@@ -2293,6 +2378,9 @@ async function updateIssueCommand(id, options) {
       scope: options.scope,
       type: options.type,
       labels: options.labels,
+      ...options.dependsOn !== undefined && {
+        depends_on: await resolveDependsOn(options.dependsOn, id) || ""
+      },
       order
     });
     console.log(`Updated issue: ${issue.filename}`);
@@ -2341,6 +2429,7 @@ async function reopenIssueCommand(id, options) {
 }
 async function nextIssueCommand() {
   const issue = await getNextIssue();
+  const allIssues = await getAllIssues();
   if (!issue) {
     console.log("No open issues.");
     return;
@@ -2359,6 +2448,7 @@ ${"=".repeat(70)}`);
   if (issue.frontmatter.labels) {
     console.log(`  Labels:      ${issue.frontmatter.labels}`);
   }
+  printDependsOn(issue, allIssues);
   if (issue.frontmatter.order) {
     console.log(`  Order:       ${issue.frontmatter.order}`);
   }
@@ -2386,6 +2476,7 @@ Options:
 Commands:
   list                    List all open issues (roadmap order)
     --all, -a             Include closed issues
+    --unblocked           Only show open issues with no open blockers
     --priority, -p <p>    Filter by priority (high, medium, low)
     --scope <s>           Filter by scope (small, medium, large)
     --type, -t <t>        Filter by type (bug, improvement)
@@ -2406,6 +2497,7 @@ Commands:
     --scope <s>           Scope (small, medium, large)
     --type <t>            Type (bug, improvement)
     --labels, -l <l>      Comma-separated labels
+    --depends-on <ids>    Comma-separated blocking issue IDs
     --before <id>         Insert before this issue in roadmap
     --after <id>          Insert after this issue in roadmap
     --first               Insert at the beginning of the roadmap
@@ -2418,6 +2510,7 @@ Commands:
     --scope <s>           New scope
     --type <t>            New type
     --labels, -l <l>      New labels
+    --depends-on <ids>    Replace blocking issue IDs (empty clears)
     --before <id>         Move before this issue in roadmap
     --after <id>          Move after this issue in roadmap
     --first               Move to the beginning of the roadmap
@@ -2435,6 +2528,7 @@ Commands:
 
 Examples:
   issy list
+  issy list --unblocked
   issy list --priority high --type bug
   issy next
   issy read 0001
@@ -2456,6 +2550,7 @@ List all open issues in roadmap order.
 
 Options:
   --all, -a             Include closed issues
+  --unblocked           Only show open issues with no open blockers
   --priority, -p <p>    Filter by priority (high, medium, low)
   --scope <s>           Filter by scope (small, medium, large)
   --type, -t <t>        Filter by type (bug, improvement)
@@ -2468,6 +2563,7 @@ Options:
         args: args.slice(1),
         options: {
           all: { type: "boolean", short: "a" },
+          unblocked: { type: "boolean" },
           priority: { type: "string", short: "p" },
           scope: { type: "string" },
           type: { type: "string", short: "t" },
@@ -2545,6 +2641,7 @@ Options:
   --scope <s>           Scope: small, medium, large
   --type <t>            Type: bug, improvement (default: improvement)
   --labels, -l <l>      Comma-separated labels
+  --depends-on <ids>    Comma-separated blocking issue IDs
   --before <id>         Insert before this issue in roadmap
   --after <id>          Insert after this issue in roadmap
   --first               Insert at the beginning of the roadmap
@@ -2552,6 +2649,7 @@ Options:
 
 Examples:
   issy create --title "Fix login bug" --type bug --priority high --after 0002
+  issy create --title "Add export" --depends-on 0001,0002 --last
   issy create --title "Add dark mode" --last
 `);
         return;
@@ -2565,6 +2663,7 @@ Examples:
           scope: { type: "string" },
           type: { type: "string" },
           labels: { type: "string", short: "l" },
+          "depends-on": { type: "string" },
           before: { type: "string" },
           after: { type: "string" },
           first: { type: "boolean" },
@@ -2572,7 +2671,10 @@ Examples:
         },
         allowPositionals: true
       });
-      await createIssueCommand(values);
+      await createIssueCommand({
+        ...values,
+        dependsOn: getDependsOnArg(values)
+      });
       break;
     }
     case "update": {
@@ -2588,6 +2690,7 @@ Options:
   --scope <s>           New scope: small, medium, large
   --type <t>            New type: bug, improvement
   --labels, -l <l>      New labels (comma-separated)
+  --depends-on <ids>    Replace blocking issue IDs (empty clears)
   --before <id>         Move before this issue in roadmap
   --after <id>          Move after this issue in roadmap
   --first               Move to the beginning of the roadmap
@@ -2595,6 +2698,7 @@ Options:
 
 Examples:
   issy update 0001 --priority low --after 0003
+  issy update 0002 --depends-on 0001,0003
   issy update 0002 --title "Renamed issue" --first
 `);
         return;
@@ -2613,6 +2717,7 @@ Examples:
           scope: { type: "string" },
           type: { type: "string" },
           labels: { type: "string", short: "l" },
+          "depends-on": { type: "string" },
           before: { type: "string" },
           after: { type: "string" },
           first: { type: "boolean" },
@@ -2620,7 +2725,10 @@ Examples:
         },
         allowPositionals: true
       });
-      await updateIssueCommand(id, values);
+      await updateIssueCommand(id, {
+        ...values,
+        dependsOn: getDependsOnArg(values)
+      });
       break;
     }
     case "close": {

package/dist/main.js

@@ -366,6 +366,9 @@ function generateFrontmatter(data) {
   if (data.order) {
     lines.push(`order: ${data.order}`);
   }
+  if (data.depends_on) {
+    lines.push(`depends_on: ${data.depends_on}`);
+  }
   lines.push(`created: ${data.created}`);
   if (data.updated) {
     lines.push(`updated: ${data.updated}`);
@@ -374,6 +377,44 @@ function generateFrontmatter(data) {
   return lines.join(`
 `);
 }
+function parseDependencyIds(dependsOn) {
+  if (!dependsOn)
+    return [];
+  const seen = new Set;
+  const ids = [];
+  for (const token of dependsOn.split(/[,\s]+/)) {
+    const value = token.trim().replace(/^['"]+|['"]+$/g, "").replace(/^#/, "");
+    if (!/^\d+$/.test(value))
+      continue;
+    const id = value.padStart(4, "0");
+    if (seen.has(id))
+      continue;
+    seen.add(id);
+    ids.push(id);
+  }
+  return ids;
+}
+function filterExistingDependencyIds(dependsOn, issues, excludeId) {
+  const existingIds = new Set(issues.map((issue) => issue.id));
+  const excludedId = excludeId?.padStart(4, "0");
+  return parseDependencyIds(dependsOn).filter((id) => existingIds.has(id) && id !== excludedId);
+}
+function formatExistingDependencyIds(dependsOn, issues, excludeId) {
+  return filterExistingDependencyIds(dependsOn, issues, excludeId).join(", ");
+}
+function getDependencyIssues(issue, issues) {
+  const dependencyIds = filterExistingDependencyIds(issue.frontmatter.depends_on, issues, issue.id);
+  if (dependencyIds.length === 0)
+    return [];
+  const issueById = new Map(issues.map((i) => [i.id, i]));
+  return dependencyIds.map((id) => issueById.get(id)).filter((dependency) => Boolean(dependency));
+}
+function getBlockingIssues(issue, issues) {
+  return getDependencyIssues(issue, issues).filter((dependency) => dependency.frontmatter.status === "open");
+}
+function isIssueUnblocked(issue, issues) {
+  return issue.frontmatter.status === "open" && getBlockingIssues(issue, issues).length === 0;
+}
 function getIssueIdFromFilename(filename) {
   const match = filename.match(/^(\d+)-/);
   return match ? match[1] : filename.replace(".md", "");
@@ -507,6 +548,8 @@ async function createIssue(input) {
   const issueNumber = await getNextIssueNumber();
   const slug = createSlug(input.title);
   const filename = `${issueNumber}-${slug}.md`;
+  const existingIssues = await getAllIssues();
+  const dependsOn = formatExistingDependencyIds(input.depends_on, existingIssues, issueNumber);
   const frontmatter = {
     title: input.title,
     priority,
@@ -515,6 +558,7 @@ async function createIssue(input) {
     labels: input.labels || undefined,
     status: "open",
     order: input.order || undefined,
+    depends_on: dependsOn || undefined,
     created: formatDate()
   };
   const body = input.body ?? `
@@ -540,6 +584,8 @@ async function updateIssue(id, input) {
   if (!issue) {
     throw new Error(`Issue not found: ${id}`);
   }
+  const allIssues = await getAllIssues();
+  const dependsOn = input.depends_on !== undefined ? formatExistingDependencyIds(input.depends_on, allIssues, issue.id) : undefined;
   const updatedFrontmatter = {
     ...issue.frontmatter,
     ...input.title && { title: input.title },
@@ -551,6 +597,9 @@ async function updateIssue(id, input) {
     },
     ...input.status && { status: input.status },
     ...input.order && { order: input.order },
+    ...input.depends_on !== undefined && {
+      depends_on: dependsOn || undefined
+    },
     updated: formatDate()
   };
   const updatedContent = input.body !== undefined ? `
@@ -2050,6 +2099,14 @@ function filterByQuery(issues, query) {
         if (issue.frontmatter.status !== statusValue) {
           return false;
         }
+      } else if (statusValue === "unblocked") {
+        if (!isIssueUnblocked(issue, issues)) {
+          return false;
+        }
+      } else if (statusValue === "blocked") {
+        if (issue.frontmatter.status !== "open" || isIssueUnblocked(issue, issues)) {
+          return false;
+        }
       }
     }
     if (parsed.qualifiers.priority) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "issy",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "AI-native issue tracking. Markdown files in .issues/, managed by your coding assistant.",
   "type": "module",
   "license": "MIT",
@@ -35,8 +35,8 @@
     "lint": "biome check src bin"
   },
   "dependencies": {
-    "@miketromba/issy-app": "^0.8.0",
-    "@miketromba/issy-core": "^0.8.0",
+    "@miketromba/issy-app": "^0.9.0",
+    "@miketromba/issy-core": "^0.9.0",
     "update-notifier": "^7.3.1"
   }
 }