@enrichlayer/el-linear 1.17.0 → 1.18.0

package/dist/commands/comments.js

@@ -1,6 +1,6 @@
 import { readFileSync } from "node:fs";
 import { resolveUserDisplayName } from "../config/resolver.js";
-import { CREATE_COMMENT_MUTATION, LIST_COMMENTS_QUERY, UPDATE_COMMENT_MUTATION, } from "../queries/comments.js";
+import { CREATE_COMMENT_MUTATION, DELETE_COMMENT_MUTATION, LIST_COMMENTS_QUERY, UPDATE_COMMENT_MUTATION, } from "../queries/comments.js";
 import { autoLinkReferences, } from "../utils/auto-link-references.js";
 import { applyFooter } from "../utils/footer.js";
 import { createGraphQLService, } from "../utils/graphql-service.js";
@@ -260,6 +260,15 @@ async function handleListComments(issueId, options, command) {
         },
     });
 }
+async function handleDeleteComment(commentId, _options, command) {
+    const rootOpts = getRootOpts(command);
+    const graphQLService = await createGraphQLService(rootOpts);
+    const result = await graphQLService.rawRequest(DELETE_COMMENT_MUTATION, { id: commentId });
+    if (!result.commentDelete.success) {
+        throw new Error(`Failed to delete comment "${commentId}"`);
+    }
+    outputSuccess({ id: commentId, deleted: true });
+}
 export function setupCommentsCommands(program) {
     const comments = program
         .command("comments")
@@ -291,4 +300,11 @@ export function setupCommentsCommands(program) {
         .addHelpText("after", "\nBoth UUID and identifiers like ABC-123 are supported.")
         .option("-l, --limit <number>", "limit results", "25")
         .action(handleAsyncCommand(handleListComments));
+    comments
+        .command("delete <commentId>")
+        .alias("remove")
+        .alias("rm")
+        .description("Delete a comment by its id.")
+        .addHelpText("after", "\nTakes a comment id (the `id` field from `comments list` / `comments create`), not an issue identifier.")
+        .action(handleAsyncCommand(handleDeleteComment));
 }

package/dist/commands/issues/branch.d.ts

@@ -13,5 +13,52 @@ export declare function toBranchName(linearBranchName: string, prefix?: string):
 /**
  * Check out a new git branch. Warns and skips if not in a git repo.
  * Throws if the branch already exists.
+ *
+ * Returns `true` if the branch was actually checked out, `false` if the
+ * checkout was skipped (not in a git repo). Callers gate follow-on work
+ * (e.g. writing the `branch.<branch>.linearIssue` marker) on the result so
+ * they don't emit a second, contradictory warning about a branch that was
+ * never created.
+ */
+export declare function gitCheckoutBranch(branchName: string): boolean;
+/**
+ * Extract the canonical (uppercase) Linear identifier embedded in a branch
+ * name — `feature/DEV-4293-slug` → `DEV-4293`, `dev-4293-slug` → `DEV-4293`.
+ * Returns null when the branch carries no identifier token.
+ */
+export declare function extractIssueIdentifierFromBranch(branch: string): string | null;
+/**
+ * Record the Linear issue a branch implements as durable git metadata:
+ * `git config branch.<branch>.linearIssue <identifier>`. This is the signal
+ * DEV-4241's PreToolUse hook reads to confirm a workflow was established
+ * before allowing tracked-file edits — far more robust than parsing the
+ * branch name shape (which legitimately varies: `dev-4083-slug`,
+ * `fe-630-slug`, `emw-280-slug`), and it stays fast + offline (a local
+ * git config read, no API call).
+ *
+ * Best-effort by design: a failure to write the marker must never abort the
+ * issue-creation flow that triggered it. Callers in a known-good repo
+ * context wrap this and warn on failure; the standalone `mark-branch`
+ * command does its own repo/branch validation first so it can surface a
+ * clear error instead.
+ *
+ * No `--` ref-terminator (unlike the checkout/rename calls above): `git
+ * config <key> <value>` takes exactly two positional operands, the key is
+ * always our `branch.`-prefixed literal, and a value beginning with `-` is
+ * stored verbatim rather than parsed as a flag — so there's no
+ * flag-injection surface to defend here.
+ */
+export declare function setBranchLinearIssue(branch: string, identifier: string): void;
+/**
+ * Read back the `branch.<branch>.linearIssue` marker, or null when unset.
+ */
+export declare function getBranchLinearIssue(branch: string): string | null;
+/**
+ * Current branch's short name, or null when detached / not in a repo.
+ *
+ * Uses `symbolic-ref` rather than `rev-parse --abbrev-ref`: the former
+ * resolves the name even on an unborn branch (fresh repo, no commits yet)
+ * and still fails — yielding null — on a detached HEAD, which is exactly
+ * the "no named branch" signal callers want.
  */
-export declare function gitCheckoutBranch(branchName: string): void;
+export declare function currentGitBranch(): string | null;

package/dist/commands/issues/branch.js

@@ -25,6 +25,12 @@ export function toBranchName(linearBranchName, prefix = "feature/") {
 /**
  * Check out a new git branch. Warns and skips if not in a git repo.
  * Throws if the branch already exists.
+ *
+ * Returns `true` if the branch was actually checked out, `false` if the
+ * checkout was skipped (not in a git repo). Callers gate follow-on work
+ * (e.g. writing the `branch.<branch>.linearIssue` marker) on the result so
+ * they don't emit a second, contradictory warning about a branch that was
+ * never created.
  */
 export function gitCheckoutBranch(branchName) {
     try {
@@ -34,7 +40,7 @@ export function gitCheckoutBranch(branchName) {
     }
     catch {
         outputWarning("Not inside a git repository — skipping branch checkout.");
-        return;
+        return false;
     }
     // `--` separates the new-branch name from any ref. Without it, a
     // branch name starting with `-` (server bug, malicious team member
@@ -45,4 +51,78 @@ export function gitCheckoutBranch(branchName) {
     // prefix callers would lose the defense without this terminator.
     // Defense-in-depth (DEV-4064).
     execFileSync("git", ["checkout", "-b", branchName, "--"], { stdio: "pipe" });
+    return true;
+}
+// First Linear-style identifier token in a branch name, in any position, so
+// it survives a configurable prefix (`feature/DEV-123-slug`) and the bare
+// Linear shape (`dev-123-slug`). Anchored on a non-word boundary so it
+// doesn't match mid-token.
+const BRANCH_IDENTIFIER_REGEX = /(?:^|[^A-Za-z0-9])([A-Za-z]+-\d+)(?![A-Za-z0-9])/;
+/**
+ * Extract the canonical (uppercase) Linear identifier embedded in a branch
+ * name — `feature/DEV-4293-slug` → `DEV-4293`, `dev-4293-slug` → `DEV-4293`.
+ * Returns null when the branch carries no identifier token.
+ */
+export function extractIssueIdentifierFromBranch(branch) {
+    const match = branch.match(BRANCH_IDENTIFIER_REGEX);
+    return match ? match[1].toUpperCase() : null;
+}
+/**
+ * Record the Linear issue a branch implements as durable git metadata:
+ * `git config branch.<branch>.linearIssue <identifier>`. This is the signal
+ * DEV-4241's PreToolUse hook reads to confirm a workflow was established
+ * before allowing tracked-file edits — far more robust than parsing the
+ * branch name shape (which legitimately varies: `dev-4083-slug`,
+ * `fe-630-slug`, `emw-280-slug`), and it stays fast + offline (a local
+ * git config read, no API call).
+ *
+ * Best-effort by design: a failure to write the marker must never abort the
+ * issue-creation flow that triggered it. Callers in a known-good repo
+ * context wrap this and warn on failure; the standalone `mark-branch`
+ * command does its own repo/branch validation first so it can surface a
+ * clear error instead.
+ *
+ * No `--` ref-terminator (unlike the checkout/rename calls above): `git
+ * config <key> <value>` takes exactly two positional operands, the key is
+ * always our `branch.`-prefixed literal, and a value beginning with `-` is
+ * stored verbatim rather than parsed as a flag — so there's no
+ * flag-injection surface to defend here.
+ */
+export function setBranchLinearIssue(branch, identifier) {
+    execFileSync("git", ["config", `branch.${branch}.linearIssue`, identifier], {
+        stdio: "pipe",
+    });
+}
+/**
+ * Read back the `branch.<branch>.linearIssue` marker, or null when unset.
+ */
+export function getBranchLinearIssue(branch) {
+    try {
+        return execFileSync("git", ["config", "--get", `branch.${branch}.linearIssue`], { stdio: "pipe" })
+            .toString()
+            .trim();
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Current branch's short name, or null when detached / not in a repo.
+ *
+ * Uses `symbolic-ref` rather than `rev-parse --abbrev-ref`: the former
+ * resolves the name even on an unborn branch (fresh repo, no commits yet)
+ * and still fails — yielding null — on a detached HEAD, which is exactly
+ * the "no named branch" signal callers want.
+ */
+export function currentGitBranch() {
+    try {
+        return execFileSync("git", ["symbolic-ref", "--short", "HEAD"], {
+            stdio: "pipe",
+        })
+            .toString()
+            .trim();
+    }
+    catch {
+        return null;
+    }
 }

package/dist/commands/issues.js

@@ -17,7 +17,7 @@ import { handleAsyncCommand, outputSuccess, outputWarning, warnIfTruncated, } fr
 import { getRootOpts } from "../utils/root-opts.js";
 import { formatCsv, formatMarkdown, formatTable, } from "../utils/table-formatter.js";
 import { parsePositiveInt, parsePriorityFilter, splitList, validatePriority, } from "../utils/validators.js";
-import { gitCheckoutBranch, toBranchName } from "./issues/branch.js";
+import { currentGitBranch, extractIssueIdentifierFromBranch, getBranchLinearIssue, gitCheckoutBranch, setBranchLinearIssue, toBranchName, } from "./issues/branch.js";
 import { maybeAutoLink, prepareAutoLinkedDescription, readDescriptionFile, resolveDescription, } from "./issues/description.js";
 import { handleLinkReferencesIssue } from "./issues/link-references.js";
 import { buildIncomingRelationEntries, buildOutgoingRelationEntries, createRelations, } from "./issues/relations.js";
@@ -472,8 +472,25 @@ async function handleCreateIssue(title, options, command) {
     }
     let branch;
     if (options.checkout && result.branchName) {
-        branch = toBranchName(result.branchName);
-        gitCheckoutBranch(branch);
+        const branchName = toBranchName(result.branchName);
+        // Only treat the branch as created (and surface it in the output) when
+        // the checkout actually happened — outside a git repo gitCheckoutBranch
+        // warns and skips, and claiming a branch / a missing marker afterward
+        // would be a contradictory second warning (DEV-4293 cycle-1).
+        if (gitCheckoutBranch(branchName)) {
+            branch = branchName;
+            // Record the issue→branch link as git metadata (DEV-4293) so the
+            // DEV-4241 hook can confirm a workflow was established without parsing
+            // the branch name. Best-effort: never let a marker-write failure abort
+            // a successful issue creation.
+            try {
+                setBranchLinearIssue(branch, result.identifier);
+            }
+            catch {
+                outputWarning(`Created branch ${branch} but could not record its Linear issue marker. ` +
+                    `Run 'el-linear issues mark-branch ${result.identifier}' from the branch to set it.`);
+            }
+        }
     }
     const output = {
         ...result,
@@ -794,6 +811,14 @@ async function handleRetrolink(options, command) {
         execFileSync("git", ["branch", "-m", "--", oldBranch, newBranch], {
             stdio: "pipe",
         });
+        // Record the issue→branch link (DEV-4293), same as `create --checkout`.
+        try {
+            setBranchLinearIssue(newBranch, result.identifier);
+        }
+        catch {
+            outputWarning(`Renamed branch to ${newBranch} but could not record its Linear issue marker. ` +
+                `Run 'el-linear issues mark-branch ${result.identifier}' from the branch to set it.`);
+        }
     }
     outputSuccess({
         ...result,
@@ -801,6 +826,43 @@ async function handleRetrolink(options, command) {
         ...(newBranch ? { branch: newBranch } : {}),
     });
 }
+async function handleMarkBranch(issueId, _options, _command) {
+    const branch = currentGitBranch();
+    if (!branch) {
+        throw new Error("Not on a named git branch (detached HEAD or not in a repository).");
+    }
+    if (branch === "main" || branch === "master") {
+        throw new Error(`Refusing to mark the '${branch}' branch.`);
+    }
+    // Resolve the identifier to record. An explicit arg wins; otherwise infer
+    // it from the branch name. Both paths are offline — the marker's whole
+    // value is letting the hook verify a workflow without a network call, so
+    // we don't round-trip to the API just to normalize an identifier.
+    let identifier;
+    if (issueId) {
+        // Accepts a bare identifier (DEV-123), a branch-style token
+        // (dev-123-slug), or a Linear URL — extract normalizes all three.
+        identifier = extractIssueIdentifierFromBranch(issueId);
+        if (!identifier) {
+            throw new Error(`'${issueId}' is not a Linear issue identifier (expected a shape like DEV-123).`);
+        }
+    }
+    else {
+        identifier = extractIssueIdentifierFromBranch(branch);
+        if (!identifier) {
+            throw new Error(`Branch '${branch}' has no Linear identifier to infer. ` +
+                `Pass one explicitly: 'el-linear issues mark-branch DEV-123'.`);
+        }
+    }
+    const previous = getBranchLinearIssue(branch);
+    setBranchLinearIssue(branch, identifier);
+    outputSuccess({
+        branch,
+        linearIssue: identifier,
+        ...(previous && previous !== identifier ? { previous } : {}),
+        marked: true,
+    });
+}
 export function setupIssuesCommands(program) {
     const issues = program
         .command("issues")
@@ -1001,4 +1063,11 @@ export function setupIssuesCommands(program) {
         .option("--title <title>", "override auto-generated title (default: first commit message)")
         .option("--base <branch>", "base branch for log comparison", "main")
         .action(handleAsyncCommand(handleRetrolink));
+    issues
+        .command("mark-branch [issueId]")
+        .description("Record the current branch's Linear issue as git metadata (branch.<branch>.linearIssue).")
+        .addHelpText("after", "\nManual recovery for branches not created via 'issues create --checkout' / 'retrolink'.\n" +
+        "With no argument, infers the identifier from the branch name (e.g. dev-4293-slug -> DEV-4293).\n" +
+        "Accepts a bare identifier (DEV-123), a branch-style token, or a Linear URL.")
+        .action(handleAsyncCommand(handleMarkBranch));
 }

package/dist/queries/comments-types.d.ts

@@ -52,4 +52,9 @@ export interface UpdateCommentResponse {
         comment: UpdatedCommentResourceNode | null;
     };
 }
+export interface DeleteCommentResponse {
+    commentDelete: {
+        success: boolean;
+    };
+}
 export {};

package/dist/queries/comments.d.ts

@@ -1,3 +1,4 @@
 export declare const LIST_COMMENTS_QUERY = "\n  query ListComments($issueId: String!, $first: Int) {\n    issue(id: $issueId) {\n      id\n      identifier\n      comments(first: $first, orderBy: createdAt) {\n        nodes {\n          id\n          body\n          createdAt\n          updatedAt\n          user {\n            id\n            name\n            displayName\n            url\n          }\n        }\n      }\n    }\n  }\n";
 export declare const CREATE_COMMENT_MUTATION = "\n  mutation CreateComment($input: CommentCreateInput!) {\n    commentCreate(input: $input) {\n      success\n      comment {\n        id\n        body\n        createdAt\n        updatedAt\n        user {\n          id\n          name\n          displayName\n          url\n        }\n      }\n    }\n  }\n";
 export declare const UPDATE_COMMENT_MUTATION = "\n  mutation UpdateComment($id: String!, $input: CommentUpdateInput!) {\n    commentUpdate(id: $id, input: $input) {\n      success\n      comment {\n        id\n        body\n        createdAt\n        updatedAt\n        user {\n          id\n          name\n          displayName\n          url\n        }\n        issue {\n          id\n          identifier\n        }\n      }\n    }\n  }\n";
+export declare const DELETE_COMMENT_MUTATION = "\n  mutation DeleteComment($id: String!) {\n    commentDelete(id: $id) {\n      success\n    }\n  }\n";

package/dist/queries/comments.js

@@ -62,3 +62,16 @@ export const UPDATE_COMMENT_MUTATION = `
     }
   }
 `;
+// commentDelete returns a DeletePayload (`{ success }`) — no `comment` node,
+// since the entity is gone. The @linear/sdk exposes this as
+// `client.deleteComment(id)`, but the standalone comment commands all go
+// through raw mutations on `graphQLService` (create/update need `bodyData`,
+// which the SDK's typed input wraps awkwardly), so delete stays on the same
+// raw path for a consistent, single-mock test surface.
+export const DELETE_COMMENT_MUTATION = `
+  mutation DeleteComment($id: String!) {
+    commentDelete(id: $id) {
+      success
+    }
+  }
+`;

package/dist/utils/graphql-issues-service.js

@@ -359,7 +359,7 @@ export class GraphQLIssuesService {
         const finalProjectId = projectIdArg
             ? this.resolveProjectId(projectIdArg, resolveResult)
             : undefined;
-        const finalAssigneeId = this.resolveAssigneeId(args.assigneeId, resolveResult);
+        const finalAssigneeId = await this.resolveAssigneeId(args.assigneeId, resolveResult);
         const finalDelegateId = await this.resolveDelegateId(args.delegateId, resolveResult);
         // Map the public discriminant back to the internal filter shape:
         // `{ kind: "id", id }` → `{ kind: "id", id: <resolvedUuid> }`
@@ -877,10 +877,20 @@ export class GraphQLIssuesService {
         }
         return filter;
     }
-    resolveAssigneeId(assigneeId, resolveResult) {
-        if (!assigneeId || isUuid(assigneeId) || !assigneeId.includes("@")) {
+    async resolveAssigneeId(assigneeId, resolveResult) {
+        if (!assigneeId || isUuid(assigneeId)) {
             return assigneeId;
         }
+        // A plain name (no `@`) resolves via the user lookup — same as
+        // `resolveDelegateId`. Without this, a non-config full name like
+        // "Yury Tsukerman" fell through unchanged and was sent to the
+        // GraphQL filter as a bogus UUID, producing an opaque "Argument
+        // Validation Error" instead of resolving (or a clean not-found).
+        // `resolveUserId` matches displayName then name and throws a
+        // structured notFound / multiple-matches error (DEV-4312).
+        if (!assigneeId.includes("@")) {
+            return this.linearService.resolveUserId(assigneeId);
+        }
         const userNodes = resolveResult.users?.nodes;
         if (!userNodes?.length) {
             throw notFoundError("User", assigneeId);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@enrichlayer/el-linear",
-  "version": "1.17.0",
+  "version": "1.18.0",
   "description": "A pragmatic CLI for Linear.app — deterministic team/label/member resolution, structured issue validation, configurable term enforcement, and a GraphQL escape hatch.",
   "main": "dist/main.js",
   "types": "dist/main.d.ts",