@enrichlayer/el-linear 1.4.0 → 1.6.0

package/dist/commands/init/oauth.js

@@ -0,0 +1,308 @@
+/**
+ * Wizard step for OAuth 2.0 (PKCE flow) authorization.
+ *
+ * Flow:
+ *   1. Present a "what is this?" intro pointing the user at Linear's OAuth
+ *      app registration page. (Until we ship a shared OAuth client_id,
+ *      every user registers their own app.)
+ *   2. Prompt for `client_id`, optional `client_secret`, port, scopes.
+ *   3. Generate PKCE verifier + state, build the authorize URL.
+ *   4. Try to open the system browser; fall back to printing the URL.
+ *   5. Spin a localhost listener (or fall back to pasted-code prompt) to
+ *      receive the redirect.
+ *   6. Exchange code for tokens.
+ *   7. Validate by calling `viewer { ... }` with the new bearer token.
+ *   8. Persist `oauth.json` to the active profile.
+ *
+ * Idempotent: if a fresh `oauth.json` already exists, offer keep / re-auth /
+ * revoke before doing anything else.
+ */
+import { spawn } from "node:child_process";
+import { checkbox, input, password, select } from "@inquirer/prompts";
+import { DEFAULT_CALLBACK_PATH, runLocalhostCallback, } from "../../auth/oauth-callback.js";
+import { ALL_SCOPES, buildAuthorizeUrl, DEFAULT_SCOPES, generatePkce, generateState, SCOPE_DESCRIPTIONS, validateScopes, } from "../../auth/oauth-client.js";
+import { promptForPastedCode } from "../../auth/oauth-headless.js";
+import { clearOAuthState, OAUTH_STATE_VERSION, readOAuthState, writeOAuthState, } from "../../auth/oauth-storage.js";
+import { exchangeCodeForTokens, revokeToken, } from "../../auth/oauth-token.js";
+import { GraphQLService } from "../../utils/graphql-service.js";
+import { sanitizeForLog } from "./token.js";
+const DEFAULT_PORT = 8765;
+const REGISTRATION_URL = "https://linear.app/settings/api/applications/new";
+const VIEWER_QUERY = /* GraphQL */ `
+  query {
+    viewer {
+      id
+      name
+      email
+      displayName
+      organization {
+        urlKey
+        name
+      }
+    }
+  }
+`;
+const TS = (msg) => `  ${msg}`;
+function logLine(msg) {
+    console.log(msg);
+}
+/**
+ * Open `url` in the system browser. Forks per-platform:
+ *   - darwin → `open <url>`
+ *   - win32  → `start "" "<url>"` (cmd builtin)
+ *   - other  → `xdg-open <url>` (Linux / BSD with desktop env)
+ *
+ * Returns once the spawn call succeeds — does NOT wait for the browser to
+ * actually load. Throws on spawn failure (e.g. xdg-open not installed in
+ * a barebones container).
+ */
+export async function openSystemBrowser(url) {
+    return new Promise((resolve, reject) => {
+        let cmd;
+        let args;
+        if (process.platform === "darwin") {
+            cmd = "open";
+            args = [url];
+        }
+        else if (process.platform === "win32") {
+            cmd = "cmd";
+            // `start "" "<url>"` — empty title means "use the URL".
+            args = ["/c", "start", "", url];
+        }
+        else {
+            cmd = "xdg-open";
+            args = [url];
+        }
+        const child = spawn(cmd, args, { stdio: "ignore", detached: true });
+        child.once("error", reject);
+        // Don't keep the parent alive on the child — we don't track its exit.
+        child.unref();
+        // Linux's xdg-open immediately exits with the result code. Wait
+        // until the next tick so a synchronous `error` event has a chance
+        // to fire before we resolve.
+        setImmediate(() => resolve());
+    });
+}
+/**
+ * Prompt for what to do with existing OAuth state. Returns a discriminated
+ * tagged union so the caller can branch cleanly.
+ */
+async function handleExistingState(existing, options) {
+    if (options.force)
+        return { kind: "reauth" };
+    logLine(TS(`Existing OAuth tokens found for client ${existing.clientId} (${existing.scopes.join(",")}).`));
+    const choice = await select({
+        message: "What would you like to do?",
+        choices: [
+            { name: "Keep existing tokens (no changes)", value: "keep" },
+            { name: "Re-authorize (replace tokens)", value: "reauth" },
+            { name: "Revoke and remove", value: "revoke" },
+        ],
+        default: "keep",
+    });
+    if (choice === "keep")
+        return { kind: "keep", state: existing };
+    if (choice === "revoke") {
+        const result = await revokeToken({ accessToken: existing.accessToken }, options.fetchImpl);
+        await clearOAuthState();
+        logLine(TS(result.ok
+            ? "✓ Token revoked and oauth.json removed."
+            : `Revoke endpoint returned ${result.status} (${sanitizeForLog(result.message ?? "")}). Local oauth.json removed anyway.`));
+        return { kind: "revoked" };
+    }
+    return { kind: "reauth" };
+}
+/** Extract the port from a stored `http://localhost:NNN/...` redirect URI, if any. */
+function extractPortFromRedirect(state) {
+    if (!state)
+        return null;
+    const match = state.registeredRedirectUri.match(/:(\d+)\//);
+    if (!match)
+        return null;
+    const n = Number.parseInt(match[1], 10);
+    return Number.isInteger(n) ? n : null;
+}
+/** Walk the user through their OAuth-app registration values. */
+async function promptRegistration(defaults) {
+    logLine("");
+    logLine(TS(`Register a Linear OAuth app: ${REGISTRATION_URL}`));
+    logLine(TS(`Set the redirect URL to: http://localhost:${defaults.port ?? DEFAULT_PORT}${DEFAULT_CALLBACK_PATH}`));
+    logLine(TS("Then paste the client_id (and client_secret, if your app is configured as confidential)."));
+    logLine("");
+    const port = Number.parseInt(await input({
+        message: "Localhost callback port:",
+        default: String(defaults.port ?? DEFAULT_PORT),
+        validate: (value) => {
+            const n = Number.parseInt(value, 10);
+            if (!Number.isInteger(n) || n < 1024 || n > 65535) {
+                return "Port must be an integer between 1024 and 65535";
+            }
+            return true;
+        },
+    }), 10);
+    const clientId = (await input({
+        message: "Linear OAuth client_id:",
+        validate: (v) => v.trim().length > 0 || "client_id cannot be empty",
+    })).trim();
+    const clientSecret = (await password({
+        message: "Linear OAuth client_secret (optional, hidden — press enter to skip):",
+        mask: "*",
+        validate: () => true,
+    })).trim();
+    const scopes = (await checkbox({
+        message: "Scopes (space to toggle, enter to confirm):",
+        choices: ALL_SCOPES.map((s) => ({
+            name: `${s} — ${SCOPE_DESCRIPTIONS[s]}`,
+            value: s,
+            checked: DEFAULT_SCOPES.includes(s),
+        })),
+        validate: (selections) => selections.length > 0 || "Pick at least one scope",
+    }));
+    return {
+        clientId,
+        clientSecret: clientSecret || undefined,
+        port,
+        scopes: validateScopes(scopes),
+    };
+}
+/**
+ * Default viewer-validation routine. Calls `viewer { ... }` with the new
+ * bearer token to confirm Linear accepted it. Reused for both the wizard
+ * step's success path and the test seam.
+ */
+async function defaultValidateViewer(oauthToken) {
+    const service = new GraphQLService({ oauthToken });
+    let data;
+    try {
+        data = await service.rawRequest(VIEWER_QUERY);
+    }
+    catch (err) {
+        const raw = err instanceof Error ? err.message : String(err);
+        throw new Error(`Could not validate the OAuth access token via viewer: ${sanitizeForLog(raw)}`);
+    }
+    const viewer = data?.viewer;
+    if (!viewer || typeof viewer !== "object" || typeof viewer.id !== "string") {
+        throw new Error("OAuth token validated but the response was missing a viewer with id. Try a different scope set.");
+    }
+    return viewer;
+}
+/**
+ * Run the OAuth step. Returns the final stored state + viewer info.
+ *
+ * If the user opts to keep their existing tokens, returns the existing
+ * state unchanged (no network calls).
+ */
+export async function runOAuthStep(options = {}) {
+    const validateViewer = options.validateViewer ?? defaultValidateViewer;
+    const existing = await readOAuthState();
+    if (existing && !options.force) {
+        const handled = await handleExistingState(existing, options);
+        if (handled.kind === "keep") {
+            // Validate the existing token actually works; if it's already
+            // expired and unrefreshable, the next `el-linear` invocation
+            // would fall over — fail loudly here.
+            try {
+                const viewer = await validateViewer(handled.state.accessToken);
+                logLine(TS(`✓ Existing OAuth tokens verified — authenticated as ${viewer.displayName} <${viewer.email}>.`));
+                return { state: handled.state, viewer };
+            }
+            catch (err) {
+                const raw = err instanceof Error ? err.message : String(err);
+                logLine(TS(`Existing token failed validation (${sanitizeForLog(raw)}). Continuing with re-authorization…`));
+            }
+        }
+        // Both `reauth` and `revoked` fall through to the re-auth flow.
+    }
+    const reg = await promptRegistration({
+        port: options.port ?? extractPortFromRedirect(existing) ?? DEFAULT_PORT,
+    });
+    const redirectUri = `http://localhost:${reg.port}${DEFAULT_CALLBACK_PATH}`;
+    const pkce = generatePkce();
+    const state = generateState();
+    const authorizeUrl = buildAuthorizeUrl({
+        clientId: reg.clientId,
+        redirectUri,
+        scopes: reg.scopes,
+        state,
+        codeChallenge: pkce.challenge,
+    });
+    logLine("");
+    logLine(TS("Opening your browser to authorize…"));
+    logLine(TS(`If it doesn't open, visit: ${authorizeUrl}`));
+    const useBrowser = !options.noBrowser;
+    let browserOpened = false;
+    if (useBrowser) {
+        try {
+            await (options.openBrowser ?? openSystemBrowser)(authorizeUrl);
+            browserOpened = true;
+        }
+        catch (err) {
+            const raw = err instanceof Error ? err.message : String(err);
+            logLine(TS(`Could not open a browser automatically (${raw}). Falling back to manual.`));
+        }
+    }
+    let callback;
+    if (browserOpened) {
+        try {
+            callback = await (options.runLocalhostCallbackImpl ?? runLocalhostCallback)({
+                port: reg.port,
+                expectedState: state,
+            });
+        }
+        catch (err) {
+            const raw = err instanceof Error ? err.message : String(err);
+            logLine(TS(`Localhost listener failed (${sanitizeForLog(raw)}). Falling back to manual paste.`));
+            callback = await promptForPastedCode({ expectedState: state });
+        }
+    }
+    else {
+        callback = await promptForPastedCode({ expectedState: state });
+    }
+    logLine(TS("Exchanging authorization code for tokens…"));
+    const exchanged = await exchangeCodeForTokens({
+        clientId: reg.clientId,
+        clientSecret: reg.clientSecret,
+        code: callback.code,
+        redirectUri,
+        codeVerifier: pkce.verifier,
+    }, options.fetchImpl);
+    const newState = {
+        v: OAUTH_STATE_VERSION,
+        clientId: reg.clientId,
+        clientSecret: reg.clientSecret,
+        registeredRedirectUri: redirectUri,
+        accessToken: exchanged.accessToken,
+        refreshToken: exchanged.refreshToken,
+        tokenType: exchanged.tokenType,
+        scopes: exchanged.scopes.length > 0 ? exchanged.scopes : reg.scopes,
+        expiresAt: exchanged.expiresAt,
+        obtainedAt: Date.now(),
+    };
+    logLine(TS("Validating against viewer…"));
+    const viewer = await validateViewer(newState.accessToken);
+    await writeOAuthState(newState);
+    logLine(TS(`✓ Authorized as ${viewer.displayName} <${viewer.email}> (${viewer.organization.name}).`));
+    return { state: newState, viewer };
+}
+/**
+ * `init oauth --revoke`: revoke the active profile's tokens and remove
+ * `oauth.json`. Best-effort on the network call.
+ */
+export async function runOAuthRevoke(options = {}) {
+    const existing = await readOAuthState();
+    if (!existing) {
+        return { revoked: false, message: "No OAuth state to revoke." };
+    }
+    const result = await revokeToken({ accessToken: existing.accessToken }, options.fetchImpl);
+    await clearOAuthState();
+    if (result.ok) {
+        return {
+            revoked: true,
+            message: "✓ Token revoked and oauth.json removed.",
+        };
+    }
+    return {
+        revoked: false,
+        message: `Revoke endpoint returned ${result.status} (${sanitizeForLog(result.message ?? "")}). Local oauth.json removed anyway.`,
+    };
+}

package/dist/commands/init/shared.js

@@ -174,7 +174,6 @@ export async function clearAliasesProgress() {
  * Print a step header in the wizard. Step strings like "1/4" or "2/4 (skipped)".
  */
 export function printStep(label, title) {
-    // biome-ignore lint/suspicious/noConsole: wizard output is meant for stdout
     console.log(`\n[${label}] ${title}`);
 }
 /**

package/dist/commands/init/token.js

@@ -91,7 +91,6 @@ export async function runTokenStep(options = {}) {
     if (existing && !options.force) {
         try {
             const viewer = await validateToken(existing);
-            // biome-ignore lint/suspicious/noConsole: wizard
             console.log(`  Existing token works — authenticated as ${viewer.displayName} <${viewer.email}>.`);
             const replace = await confirm({
                 message: "Replace this token?",
@@ -104,13 +103,10 @@ export async function runTokenStep(options = {}) {
         catch (err) {
             const raw = err instanceof Error ? err.message : String(err);
             const message = sanitizeForLog(raw);
-            // biome-ignore lint/suspicious/noConsole: wizard
             console.log(`  Existing token failed validation (${message}). You'll need to provide a new one.`);
         }
     }
-    // biome-ignore lint/suspicious/noConsole: wizard
     console.log(`  Generate a personal API token: ${TOKEN_GENERATION_URL}`);
-    // biome-ignore lint/suspicious/noConsole: wizard
     console.log("  The token stays on your machine. el-linear only sends it to Linear's API. " +
         "It's stored at ~/.config/el-linear/token (mode 0600).");
     // Up to three attempts before giving up.
@@ -123,17 +119,14 @@ export async function runTokenStep(options = {}) {
             validate: (input) => input.trim().length > 0 || "Token cannot be empty",
         })).trim();
         try {
-            // biome-ignore lint/suspicious/noConsole: wizard
             console.log("  Validating…");
             const viewer = await validateToken(token);
             await writeToken(token);
-            // biome-ignore lint/suspicious/noConsole: wizard
             console.log(`  ✓ Authenticated as ${viewer.displayName} <${viewer.email}> (${viewer.organization.name}).`);
             return { token, viewer };
         }
         catch (err) {
             const raw = err instanceof Error ? err.message : String(err);
-            // biome-ignore lint/suspicious/noConsole: wizard
             console.log(`  ✗ ${sanitizeForLog(raw)}`);
         }
     }

package/dist/commands/init/workspace.js

@@ -33,7 +33,6 @@ export async function runWorkspaceStep(token, workspaceUrlKey, existing) {
     for (const t of teams) {
         teamMap[t.key] = t.id;
     }
-    // biome-ignore lint/suspicious/noConsole: wizard
     console.log(`  Workspace: ${workspaceUrlKey} (${teams.length} teams)`);
     const currentDefault = existing.defaultTeam || "";
     // `change` reflects what the user agreed to: `true` means "open the picker
@@ -53,7 +52,6 @@ export async function runWorkspaceStep(token, workspaceUrlKey, existing) {
         };
     }
     if (teams.length === 0) {
-        // biome-ignore lint/suspicious/noConsole: wizard
         console.log("  No teams visible to this token. Skipping default-team picker.");
         return {
             workspaceUrlKey,

package/dist/commands/issue-id.js

@@ -72,7 +72,9 @@ export function setupIssueIdCommand(program) {
             return;
         }
         const rootOpts = command.parent?.opts() ?? {};
-        const service = createGraphQLService({ apiToken: rootOpts.apiToken });
+        const service = await createGraphQLService({
+            apiToken: rootOpts.apiToken,
+        });
         const result = (await service.rawRequest(ISSUE_QUERY, {
             id: parsed.issueId,
         }));

package/dist/commands/issues.js

@@ -7,10 +7,10 @@ import { resolveDefaultStatus } from "../config/status-defaults.js";
 import { enforceTerms } from "../config/term-enforcer.js";
 import { LIST_COMMENTS_QUERY } from "../queries/comments.js";
 import { GET_ISSUE_RELATIONS_QUERY, GET_ISSUE_STATE_HISTORY_QUERY, ISSUE_RELATION_CREATE_MUTATION, SCAN_ISSUES_QUERY, UPDATE_ISSUE_MUTATION, } from "../queries/issues.js";
-import { getApiToken } from "../utils/auth.js";
 import { autoLinkReferences, } from "../utils/auto-link-references.js";
 import { downloadLinearUploads } from "../utils/download-uploads.js";
-import { FileService } from "../utils/file-service.js";
+import { createFileService } from "../utils/file-service.js";
+import { applyFooter } from "../utils/footer.js";
 import { createGraphQLAttachmentsService } from "../utils/graphql-attachments-service.js";
 import { GraphQLIssuesService } from "../utils/graphql-issues-service.js";
 import { createGraphQLService, } from "../utils/graphql-service.js";
@@ -19,6 +19,7 @@ import { wrapIssueReferencesAsLinks } from "../utils/issue-reference-wrapper.js"
 import { createLinearService, } from "../utils/linear-service.js";
 import { logger } from "../utils/logger.js";
 import { handleAsyncCommand, outputSuccess, outputWarning, } from "../utils/output.js";
+import { getRootOpts } from "../utils/root-opts.js";
 import { formatCsv, formatMarkdown, formatTable, } from "../utils/table-formatter.js";
 import { validateReferences } from "../utils/validate-references.js";
 import { parsePriorityFilter, splitList, validatePriority, } from "../utils/validators.js";
@@ -78,14 +79,43 @@ function readDescriptionFile(filePath) {
     return fs.readFileSync(filePath, "utf8").trim();
 }
 /**
- * Resolve the description from --description, --description-file, or both.
- * --description-file takes precedence when both are provided.
+ * Resolve the description from --description, --description-file, or
+ * --template (looked up in `config.descriptionTemplates`).
+ *
+ * Precedence:
+ *   --description-file > --description > --template
+ *
+ * Passing --template alongside --description or --description-file is a
+ * usage error — the explicit body and a template both producing content
+ * would be silently dropping one. We throw so the user picks one.
  */
 function resolveDescription(options) {
-    if (options.descriptionFile) {
+    const hasInline = typeof options.description === "string" && options.description.length > 0;
+    const hasFile = Boolean(options.descriptionFile);
+    const hasTemplate = typeof options.template === "string" && options.template;
+    if (hasTemplate && (hasInline || hasFile)) {
+        throw new Error("--template is mutually exclusive with --description / --description-file. " +
+            "Pick one.");
+    }
+    if (hasFile) {
         return readDescriptionFile(options.descriptionFile);
     }
-    return options.description;
+    if (hasInline) {
+        return options.description;
+    }
+    if (hasTemplate) {
+        const templates = loadConfig().descriptionTemplates ?? {};
+        const body = templates[options.template];
+        if (!body) {
+            const available = Object.keys(templates).sort();
+            const hint = available.length
+                ? `Available templates: ${available.join(", ")}`
+                : "No templates configured. Add one under `descriptionTemplates` in your config.";
+            throw new Error(`Template "${options.template}" not found. ${hint}`);
+        }
+        return body;
+    }
+    return undefined;
 }
 function isImageFile(filename) {
     const ext = filename.lastIndexOf(".");
@@ -296,9 +326,9 @@ async function handleListIssues(options, command) {
     if (options.label && !options.labels) {
         options.labels = options.label;
     }
-    const rootOpts = command.parent.parent.opts();
-    const graphQLService = createGraphQLService(rootOpts);
-    const linearService = createLinearService(rootOpts);
+    const rootOpts = getRootOpts(command);
+    const graphQLService = await createGraphQLService(rootOpts);
+    const linearService = await createLinearService(rootOpts);
     const issuesService = new GraphQLIssuesService(graphQLService, linearService);
     const hasFilters = options.team ||
         options.labels ||
@@ -337,9 +367,9 @@ async function handleSearchIssues(query, options, command) {
     if (options.label && !options.labels) {
         options.labels = options.label;
     }
-    const rootOpts = command.parent.parent.opts();
-    const graphQLService = createGraphQLService(rootOpts);
-    const linearService = createLinearService(rootOpts);
+    const rootOpts = getRootOpts(command);
+    const graphQLService = await createGraphQLService(rootOpts);
+    const linearService = await createLinearService(rootOpts);
     const issuesService = new GraphQLIssuesService(graphQLService, linearService);
     const searchArgs = {
         query,
@@ -417,8 +447,7 @@ async function uploadAttachmentsIfNeeded(options, rootOpts) {
     const paths = Array.isArray(options.attachment)
         ? options.attachment
         : [options.attachment];
-    const apiToken = getApiToken(rootOpts);
-    const fileService = new FileService(apiToken);
+    const fileService = await createFileService(rootOpts);
     const results = [];
     for (const filePath of paths) {
         const result = await fileService.uploadFile(filePath);
@@ -442,12 +471,21 @@ function buildDescriptionWithAttachments(baseDescription, uploadResults) {
     return description;
 }
 async function handleCreateIssue(title, options, command) {
-    const rootOpts = command.parent.parent.opts();
+    const rootOpts = getRootOpts(command);
     const { teamInput, teamId, assigneeId, labelIds, status, subscriberIds } = await resolveCreateInputs(title, options, rootOpts);
     const uploadResults = await uploadAttachmentsIfNeeded(options, rootOpts);
-    const description = buildDescriptionWithAttachments(resolveDescription(options) || "", uploadResults);
-    const graphQLService = createGraphQLService(rootOpts);
-    const linearService = createLinearService(rootOpts);
+    const descriptionWithAttachments = buildDescriptionWithAttachments(resolveDescription(options) || "", uploadResults);
+    // Append messageFooter (config or --footer flag) so auto-link picks up any
+    // issue refs in the footer too. --no-footer skips both flag and config.
+    // Commander parses --no-footer as `options.footer === false`.
+    const noFooter = options.footer === false;
+    const explicitFooter = typeof options.footer === "string" ? options.footer : undefined;
+    const description = applyFooter(descriptionWithAttachments, {
+        footer: explicitFooter,
+        noFooter,
+    }) ?? "";
+    const graphQLService = await createGraphQLService(rootOpts);
+    const linearService = await createLinearService(rootOpts);
     const issuesService = new GraphQLIssuesService(graphQLService, linearService);
     // Wrap valid issue identifiers as markdown links before creating, so the description
     // saved on Linear has clickable refs from the start. Self-reference can't apply here
@@ -486,7 +524,7 @@ async function handleCreateIssue(title, options, command) {
     // so only create separate attachment records for non-image files.
     const attachments = [];
     if (uploadResults.length > 0) {
-        const attachmentsService = createGraphQLAttachmentsService(rootOpts);
+        const attachmentsService = await createGraphQLAttachmentsService(rootOpts);
         for (const uploadResult of uploadResults) {
             if (!isImageFile(uploadResult.filename)) {
                 const attachment = await attachmentsService.createAttachment({
@@ -517,9 +555,9 @@ async function handleCreateIssue(title, options, command) {
     outputSuccess(output);
 }
 async function handleHistoryIssue(issueId, _options, command) {
-    const rootOpts = command.parent.parent.opts();
-    const graphQLService = createGraphQLService(rootOpts);
-    const linearService = createLinearService(rootOpts);
+    const rootOpts = getRootOpts(command);
+    const graphQLService = await createGraphQLService(rootOpts);
+    const linearService = await createLinearService(rootOpts);
     const resolvedId = await linearService.resolveIssueId(issueId);
     const result = await graphQLService.rawRequest(GET_ISSUE_STATE_HISTORY_QUERY, {
         id: resolvedId,
@@ -547,9 +585,9 @@ async function handleHistoryIssue(issueId, _options, command) {
     });
 }
 async function handleRelateIssue(issueId, options, command) {
-    const rootOpts = command.parent.parent.opts();
-    const graphQLService = createGraphQLService(rootOpts);
-    const linearService = createLinearService(rootOpts);
+    const rootOpts = getRootOpts(command);
+    const graphQLService = await createGraphQLService(rootOpts);
+    const linearService = await createLinearService(rootOpts);
     const sourceId = await linearService.resolveIssueId(issueId);
     const relations = await createRelations(sourceId, options, graphQLService, linearService);
     if (relations.length === 0) {
@@ -620,9 +658,9 @@ function buildRelationEntries(nodes, peerKey, direction, normalizeType) {
     return entries;
 }
 async function handleRelatedIssues(issueId, _options, command) {
-    const rootOpts = command.parent.parent.opts();
-    const graphQLService = createGraphQLService(rootOpts);
-    const linearService = createLinearService(rootOpts);
+    const rootOpts = getRootOpts(command);
+    const graphQLService = await createGraphQLService(rootOpts);
+    const linearService = await createLinearService(rootOpts);
     const resolvedId = await linearService.resolveIssueId(issueId);
     const result = await graphQLService.rawRequest(GET_ISSUE_RELATIONS_QUERY, {
         id: resolvedId,
@@ -813,10 +851,10 @@ async function handleLinkReferencesBatch(teamInput, options, graphQLService, lin
         },
     });
 }
-function handleLinkReferencesIssue(issueIdOrTeamFlag, options, command) {
-    const rootOpts = command.parent.parent.opts();
-    const graphQLService = createGraphQLService(rootOpts);
-    const linearService = createLinearService(rootOpts);
+async function handleLinkReferencesIssue(issueIdOrTeamFlag, options, command) {
+    const rootOpts = getRootOpts(command);
+    const graphQLService = await createGraphQLService(rootOpts);
+    const linearService = await createLinearService(rootOpts);
     if (options.team) {
         if (issueIdOrTeamFlag) {
             throw new Error("Provide either an issueId positional argument OR --team, not both. With --team, omit the issueId.");
@@ -832,20 +870,20 @@ function handleLinkReferencesIssue(issueIdOrTeamFlag, options, command) {
     return handleLinkReferencesSingle(issueIdOrTeamFlag, options, graphQLService, linearService);
 }
 async function handleReadIssue(issueIds, _options, command) {
-    const rootOpts = command.parent.parent.opts();
-    const graphQLService = createGraphQLService(rootOpts);
-    const linearService = createLinearService(rootOpts);
+    const rootOpts = getRootOpts(command);
+    const graphQLService = await createGraphQLService(rootOpts);
+    const linearService = await createLinearService(rootOpts);
     const issuesService = new GraphQLIssuesService(graphQLService, linearService);
-    const apiToken = getApiToken(rootOpts);
+    const fileService = await createFileService(rootOpts);
     if (issueIds.length === 1) {
         const issue = await issuesService.getIssueById(issueIds[0]);
-        const resolved = await downloadLinearUploads(issue, apiToken);
+        const resolved = await downloadLinearUploads(issue, fileService);
         outputSuccess(resolved);
     }
     else {
         const results = await Promise.all(issueIds.map(async (id) => {
             const issue = await issuesService.getIssueById(id);
-            return downloadLinearUploads(issue, apiToken);
+            return downloadLinearUploads(issue, fileService);
         }));
         outputSuccess(results);
     }
@@ -863,9 +901,9 @@ async function handleUpdateIssue(issueId, options, command) {
         options.description = readDescriptionFile(options.descriptionFile);
     }
     validateUpdateOptions(options);
-    const rootOpts = command.parent.parent.opts();
-    const graphQLService = createGraphQLService(rootOpts);
-    const linearService = createLinearService(rootOpts);
+    const rootOpts = getRootOpts(command);
+    const graphQLService = await createGraphQLService(rootOpts);
+    const linearService = await createLinearService(rootOpts);
     if (options.appendDescription) {
         const resolved = await linearService.resolveIssueId(issueId);
         const current = await graphQLService.rawRequest("query($id: String!) { issue(id: $id) { description } }", { id: resolved });
@@ -952,9 +990,9 @@ async function handleRetrolink(options, command) {
     const description = commits.length > 0
         ? commits.map((msg) => `- ${msg}`).join("\n")
         : `Retrolinked from branch: ${currentBranch}`;
-    const rootOpts = command.parent.parent.opts();
-    const graphQLService = createGraphQLService(rootOpts);
-    const linearService = createLinearService(rootOpts);
+    const rootOpts = getRootOpts(command);
+    const graphQLService = await createGraphQLService(rootOpts);
+    const linearService = await createLinearService(rootOpts);
     const issuesService = new GraphQLIssuesService(graphQLService, linearService);
     let result;
     if (options.issue) {
@@ -1035,8 +1073,9 @@ export function setupIssuesCommands(program) {
         .option("-t, --title <title>", "issue title (alternative to positional argument)")
         .option("-d, --description <desc>", "issue description")
         .option("--description-file <path>", "read description from file (use - for stdin)")
+        .option("--template <name>", "use a named description template from config.descriptionTemplates")
         .option("-a, --assignee <assignee>", "assign to user (name, alias, or UUID)")
-        .option("-p, --priority <priority>", "priority: name (urgent/high/medium/low) or number (1-4)")
+        .option("-p, --priority <priority>", "priority: name (none/urgent/high/medium/normal/low) or number (0-4)")
         .option("--project <project>", "add to project (name or ID)")
         .option("--team <team>", "team key or name (default: from config)")
         .option("--labels <labels>", "labels (comma-separated names, auto-resolved per team)")
@@ -1056,6 +1095,8 @@ export function setupIssuesCommands(program) {
         .option("--checkout", "create and checkout a git branch named after the issue")
         .option("--skip-validation", "skip all validation (labels, description, assignee, project)")
         .option("--no-auto-link", "skip auto-linking issue references found in the description")
+        .option("--footer <text>", "text appended to the description (overrides config.messageFooter)")
+        .option("--no-footer", "skip the configured messageFooter for this issue")
         .action(handleAsyncCommand((titleArg, options, command) => {
         // Normalize --label alias to --labels
         if (options.label && !options.labels) {
@@ -1087,7 +1128,7 @@ export function setupIssuesCommands(program) {
         .option("--append-description <text>", "append text to the existing description")
         .option("-s, --status <status>", "new status name or ID")
         .option("--state <status>", "alias for --status (new status name or ID)")
-        .option("-p, --priority <priority>", "new priority: name (urgent/high/medium/low) or number (1-4)")
+        .option("-p, --priority <priority>", "new priority: name (none/urgent/high/medium/normal/low) or number (0-4)")
         .option("--assignee <assignee>", "new assignee (name, alias, or UUID)")
         .option("--project <project>", "new project (name or ID)")
         .option("--labels <labels>", "labels (comma-separated names or IDs)")