@etus/bhono-app 0.1.1

package/templates/base/.claude/skills/linear/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "linear-issues-scripts",
+  "version": "1.0.0",
+  "description": "Scripts to retrieve Linear issues using the TypeScript SDK",
+  "type": "module",
+  "scripts": {
+    "setup": "tsx scripts/setup-credentials.ts",
+    "list-teams": "tsx list-teams.ts",
+    "get-issues": "tsx get-issues.ts"
+  },
+  "keywords": [
+    "linear",
+    "issues",
+    "sdk"
+  ],
+  "author": "",
+  "license": "ISC",
+  "dependencies": {
+    "@linear/sdk": "^68.1.0",
+    "dotenv": "^17.2.3"
+  },
+  "devDependencies": {
+    "@types/node": "^25.0.3",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3"
+  }
+}

package/templates/base/.claude/skills/linear/reference.md

@@ -0,0 +1,263 @@
+# Linear Operations - Quick Reference
+
+## Command Summary
+
+| Operation | Command (Named Flags - Recommended) |
+|-----------|-------------------------------------|
+| Create issue | `npx tsx scripts/issues/create.ts --title "title" [options] --json` |
+| Update issue | `npx tsx scripts/issues/update.ts --issue ABC-123 [options] --json` |
+| List issues | `npx tsx scripts/issues/list.ts [teamId] --json` |
+| Get issue | `npx tsx scripts/issues/get.ts ABC-123 --json` |
+| Archive issue | `npx tsx scripts/issues/archive.ts ABC-123 --json` |
+| List teams | `npx tsx scripts/list-teams.ts --json` |
+| List statuses | `npx tsx scripts/status/list.ts [teamId] --json` |
+| Update status | `npx tsx scripts/status/update.ts ABC-123 <stateId> --json` |
+| Create comment | `npx tsx scripts/comments/create.ts ABC-123 "text" --json` |
+| List comments | `npx tsx scripts/comments/list.ts ABC-123 --json` |
+| List labels | `npx tsx scripts/labels/list.ts [teamId] --json` |
+| Create label | `npx tsx scripts/labels/create.ts "name" [teamId] --json` |
+| Add label | `npx tsx scripts/labels/add-to-issue.ts ABC-123 <labelId> --json` |
+| Current user | `npx tsx scripts/users/me.ts --json` |
+| List users | `npx tsx scripts/users/list.ts [teamId] --json` |
+
+## Create Issue Options
+
+```bash
+# Named flags (recommended)
+npx tsx scripts/issues/create.ts --title "Issue title" [options] --json
+
+# Legacy positional (backwards compatible)
+npx tsx scripts/issues/create.ts "Issue title" [teamId] [options] --json
+```
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `--title <text>` | String | Issue title (required) |
+| `--teamId <id>` | ID | Team ID (optional if configured) |
+| `--description <text>` | String | Issue description (markdown supported) |
+| `--state <id>` | ID | Initial workflow state ID |
+| `--priority <0-4>` | Int | Priority level |
+| `--assignee <id>` | ID | User ID to assign |
+| `--labels <ids>` | IDs | Comma-separated label IDs |
+| `--project <id>` | ID | Project ID |
+| `--estimate <points>` | Int | Point estimate |
+| `--due <YYYY-MM-DD>` | Date | Due date |
+| `--parent <id>` | ID | Parent issue ID or identifier (e.g., AA-123) for sub-issues |
+| `--cycle <id>` | ID | Cycle/sprint ID |
+
+## Update Issue Options
+
+```bash
+# Named flags (recommended)
+npx tsx scripts/issues/update.ts --issue ABC-123 [options] --json
+
+# Legacy positional (backwards compatible)
+npx tsx scripts/issues/update.ts ABC-123 [options] --json
+```
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `--issue <id>` | ID | Issue ID or identifier (required) |
+| `--title <text>` | String | New title |
+| `--description <text>` | String | New description (markdown) |
+| `--state <id>` | ID | Workflow state ID |
+| `--priority <0-4>` | Int | Priority level |
+| `--assignee <id>` | ID/null | User ID (`none` to unassign) |
+| `--labels <ids>` | IDs | Label IDs (replaces existing) |
+| `--project <id>` | ID/null | Project ID (`none` to remove) |
+| `--estimate <points>` | Int/null | Point estimate (`none` to clear) |
+| `--due <YYYY-MM-DD>` | Date/null | Due date (`none` to clear) |
+| `--parent <id>` | ID/null | Parent issue ID or identifier (e.g., AA-123) (`none` to remove) |
+| `--cycle <id>` | ID/null | Cycle/sprint ID (`none` to remove) |
+
+## Priority Levels
+
+- `0` - No priority
+- `1` - Urgent (🔴)
+- `2` - High (🟠)
+- `3` - Medium (🟡)
+- `4` - Low (🔵)
+
+## Mentions & Embeds
+
+Use URLs in description fields - Linear auto-converts them:
+
+| Type | Format | Result |
+|------|--------|--------|
+| User mention | `https://linear.app/workspace/profiles/username` | @username |
+| Issue mention | `https://linear.app/workspace/issue/AA-123` | Clickable AA-123 |
+| YouTube | `https://www.youtube.com/watch?v=...` | Embedded video |
+| Figma | `https://www.figma.com/file/...` | Embedded design |
+| Loom | `https://www.loom.com/share/...` | Embedded video |
+
+**Note:** `@username` syntax only works in UI, not API. Use profile URLs.
+
+## Common JQ Patterns
+
+```bash
+# Extract team ID by name
+jq -r '.teams[] | select(.name == "Engineering") | .id'
+
+# Extract issue IDs
+jq -r '.issues[].id'
+
+# Filter urgent issues
+jq '.issues[] | select(.priority == 1)'
+
+# Count issues
+jq '.issues | length'
+
+# Get first team
+jq -r '.teams[0].id'
+
+# Extract identifier (AA-123)
+jq -r '.identifier'
+
+# Get status name
+jq -r '.status'
+```
+
+## Bash Patterns
+
+```bash
+# Store result in variable
+RESULT=$(npx tsx scripts/issues/list.ts --json)
+
+# Extract field
+TEAM_ID=$(echo $RESULT | jq -r '.teams[0].id')
+
+# Loop through items
+for ID in $(echo $RESULT | jq -r '.issues[].id'); do
+  # do something with $ID
+done
+
+# Conditional execution (named flags)
+if npx tsx scripts/issues/create.ts --title "Bug fix" --json; then
+  echo "Success"
+fi
+
+# Chain commands
+TEAM_ID=$(npx tsx scripts/list-teams.ts --json | jq -r '.teams[0].id') && \
+npx tsx scripts/issues/list.ts $TEAM_ID --json
+
+# Create and update issue
+ISSUE=$(npx tsx scripts/issues/create.ts --title "New task" --json)
+ISSUE_ID=$(echo $ISSUE | jq -r '.identifier')
+npx tsx scripts/issues/update.ts --issue $ISSUE_ID --priority 2 --json
+```
+
+## Typical Response Structures
+
+**Teams:**
+```json
+{
+  "teams": [
+    {"id": "uuid", "name": "Engineering", "key": "ENG"}
+  ],
+  "projects": [
+    {"id": "uuid", "name": "Q1 Project", "teamId": "uuid"}
+  ]
+}
+```
+
+**Issues:**
+```json
+{
+  "issues": [
+    {
+      "id": "uuid",
+      "identifier": "ENG-123",
+      "title": "Bug fix",
+      "status": "In Progress",
+      "priority": 1,
+      "priorityLabel": "Urgent",
+      "url": "https://linear.app/..."
+    }
+  ]
+}
+```
+
+**Issue Details:**
+```json
+{
+  "id": "uuid",
+  "identifier": "ENG-123",
+  "title": "Bug fix",
+  "description": "Full description...",
+  "status": "In Progress",
+  "priority": 1,
+  "priorityLabel": "Urgent",
+  "assignee": {"id": "...", "name": "...", "email": "..."},
+  "creator": {"id": "...", "name": "...", "email": "..."},
+  "url": "https://linear.app/...",
+  "createdAt": "2025-01-01T00:00:00.000Z",
+  "updatedAt": "2025-01-02T00:00:00.000Z"
+}
+```
+
+**Statuses:**
+```json
+{
+  "statuses": [
+    {
+      "id": "uuid",
+      "name": "In Progress",
+      "type": "started",
+      "color": "#f2c94c",
+      "position": 2
+    }
+  ]
+}
+```
+
+**Comments:**
+```json
+{
+  "comments": [
+    {
+      "id": "uuid",
+      "body": "Comment text",
+      "createdAt": "2025-01-01T00:00:00.000Z",
+      "updatedAt": "2025-01-01T00:00:00.000Z",
+      "user": {"id": "...", "name": "...", "email": "..."}
+    }
+  ]
+}
+```
+
+## Error Messages
+
+| Error | Cause | Solution |
+|-------|-------|----------|
+| LINEAR_API_KEY not found | No credentials | Run `npx tsx scripts/setup-credentials.ts` |
+| Module not found | Missing dependencies | Run `npm install` |
+| Issue not found | Invalid ID | Check issue ID/identifier |
+| Team not found | Invalid team ID | Use `list-teams.ts` to get valid IDs |
+| Permission denied | File permissions | Run `chmod 600 ~/.linear/credentials` |
+
+## Authentication Locations
+
+Priority order (first found is used):
+
+1. **Environment variable:** `$LINEAR_API_KEY`
+2. **User credentials:** `~/.linear/credentials`
+3. **Project .env:** `.env` in project root
+
+## File Structure
+
+```
+.
+├── scripts/
+│   ├── issues/       # Issue operations
+│   ├── comments/     # Comment operations
+│   ├── status/       # Status operations
+│   ├── labels/       # Label operations
+│   └── users/        # User operations
+├── scripts/
+│   └── setup-credentials.ts  # Setup wizard
+├── lib/
+│   ├── client.ts    # Linear client
+│   └── output.ts    # Output formatting
+├── list-teams.ts    # List teams/projects
+└── get-issues.ts    # Get issues (legacy)
+```

package/templates/base/.claude/skills/linear/scripts/comments/create.ts

@@ -0,0 +1,47 @@
+import { client } from "../../lib/client.js";
+import { outputWithJq } from "../../lib/output.js";
+
+async function createComment() {
+	const issueId = process.argv[2];
+	const body = process.argv[3];
+
+	if (!issueId || !body) {
+		console.error("Error: Please provide issue ID and comment body");
+		console.error(
+			"Usage: npx tsx scripts/comments/create.ts <issueId> <body>"
+		);
+		process.exit(1);
+	}
+
+	const commentPayload = await client.createComment({
+		issueId,
+		body,
+	});
+
+	const comment = await commentPayload.comment;
+
+	if (!comment) {
+		console.error("Failed to create comment");
+		process.exit(1);
+	}
+
+	const user = await comment.user;
+
+	outputWithJq({
+		id: comment.id,
+		body: comment.body,
+		createdAt: comment.createdAt,
+		user: user
+			? {
+					id: user.id,
+					name: user.name,
+					email: user.email,
+				}
+			: null,
+	});
+}
+
+createComment().catch((error) => {
+	console.error("Error creating comment:", error.message);
+	process.exit(1);
+});

package/templates/base/.claude/skills/linear/scripts/comments/list.ts

@@ -0,0 +1,47 @@
+import { client } from "../../lib/client.js";
+import { outputWithJq } from "../../lib/output.js";
+
+async function listComments() {
+	const issueId = process.argv[2];
+
+	if (!issueId) {
+		console.error("Error: Please provide issue ID");
+		console.error("Usage: npx tsx scripts/comments/list.ts <issueId>");
+		process.exit(1);
+	}
+
+	const issue = await client.issue(issueId);
+
+	if (!issue) {
+		console.error("Issue not found");
+		process.exit(1);
+	}
+
+	const commentsResponse = await issue.comments();
+
+	const comments = await Promise.all(
+		commentsResponse.nodes.map(async (comment) => {
+			const user = await comment.user;
+			return {
+				id: comment.id,
+				body: comment.body,
+				createdAt: comment.createdAt,
+				updatedAt: comment.updatedAt,
+				user: user
+					? {
+							id: user.id,
+							name: user.name,
+							email: user.email,
+						}
+					: null,
+			};
+		})
+	);
+
+	outputWithJq({ comments });
+}
+
+listComments().catch((error) => {
+	console.error("Error listing comments:", error.message);
+	process.exit(1);
+});

package/templates/base/.claude/skills/linear/scripts/issues/archive.ts

@@ -0,0 +1,30 @@
+import { client } from "../../lib/client.js";
+import { outputWithJq } from "../../lib/output.js";
+
+async function archiveIssue() {
+	const issueId = process.argv[2];
+
+	if (!issueId) {
+		console.error("Error: Please provide issue ID");
+		console.error("Usage: npx tsx scripts/issues/archive.ts <issueId>");
+		process.exit(1);
+	}
+
+	const issuePayload = await client.archiveIssue(issueId);
+	const success = issuePayload.success;
+
+	if (!success) {
+		console.error("Failed to archive issue");
+		process.exit(1);
+	}
+
+	outputWithJq({
+		success: true,
+		message: "Issue archived successfully",
+	});
+}
+
+archiveIssue().catch((error) => {
+	console.error("Error archiving issue:", error.message);
+	process.exit(1);
+});

package/templates/base/.claude/skills/linear/scripts/issues/create.ts

@@ -0,0 +1,279 @@
+import { client } from "../../lib/client.js";
+import { outputWithJq } from "../../lib/output.js";
+import { getTeamIdOrExit } from "../../lib/config.js";
+
+/**
+ * Check if a string looks like an issue identifier (e.g., AA-123, ENG-456)
+ */
+function isIssueIdentifier(str: string): boolean {
+	return /^[A-Z]+-\d+$/i.test(str);
+}
+
+/**
+ * Resolve an issue identifier (AA-123) to its UUID.
+ * If already a UUID, returns as-is.
+ */
+async function resolveIssueId(idOrIdentifier: string): Promise<string> {
+	if (!isIssueIdentifier(idOrIdentifier)) {
+		// Assume it's already a UUID
+		return idOrIdentifier;
+	}
+
+	// Look up the issue by identifier
+	const issue = await client.issue(idOrIdentifier);
+	if (!issue) {
+		throw new Error(`Issue not found: ${idOrIdentifier}`);
+	}
+	return issue.id;
+}
+
+interface CreateOptions {
+	title: string;
+	teamId: string;
+	description?: string;
+	stateId?: string;
+	priority?: number;
+	assigneeId?: string;
+	labelIds?: string[];
+	projectId?: string;
+	estimate?: number;
+	dueDate?: string;
+	parentId?: string;
+	cycleId?: string;
+}
+
+function printUsage() {
+	console.error("Usage: npx tsx scripts/issues/create.ts --title <title> [options] --json");
+	console.error("       npx tsx scripts/issues/create.ts <title> [teamId] [options] --json  (legacy)");
+	console.error("");
+	console.error("Options:");
+	console.error("  --title <text>       Issue title (required)");
+	console.error("  --teamId <id>        Team ID (optional if configured)");
+	console.error("  --description <text> Issue description (markdown supported)");
+	console.error("  --state <id>         Initial workflow state ID");
+	console.error("  --priority <0-4>     Priority: 0=None, 1=Urgent, 2=High, 3=Medium, 4=Low");
+	console.error("  --assignee <id>      User ID to assign the issue to");
+	console.error("  --labels <ids>       Comma-separated label IDs");
+	console.error("  --project <id>       Project ID to associate with");
+	console.error("  --estimate <points>  Point estimate");
+	console.error("  --due <YYYY-MM-DD>   Due date");
+	console.error("  --parent <id>        Parent issue ID or identifier (e.g., AA-123) for sub-issues");
+	console.error("  --cycle <id>         Cycle/sprint ID");
+	console.error("  --json               Output as JSON (recommended for scripting)");
+	console.error("");
+	console.error("Examples:");
+	console.error("  npx tsx scripts/issues/create.ts --title \"Fix login bug\" --json");
+	console.error("  npx tsx scripts/issues/create.ts --title \"New feature\" --priority 2 --assignee user-123 --json");
+	console.error("  npx tsx scripts/issues/create.ts \"Fix login bug\" --json  (legacy positional)");
+}
+
+function getArgValue(args: string[], flag: string): string | undefined {
+	const index = args.indexOf(flag);
+	if (index !== -1 && args[index + 1] && !args[index + 1].startsWith("--")) {
+		return args[index + 1];
+	}
+	return undefined;
+}
+
+function parseArgs(): CreateOptions | null {
+	const args = process.argv.slice(2);
+
+	if (args.length === 0) {
+		console.error("Error: Please provide issue title");
+		console.error("Use --title \"title\" or provide as first argument");
+		console.error("");
+		printUsage();
+		return null;
+	}
+
+	let title: string | undefined;
+	let teamIdArg: string | undefined;
+	let optionsStartIndex = 0;
+
+	// Check for --title flag (new named pattern - recommended)
+	title = getArgValue(args, "--title");
+
+	// Check for --teamId flag
+	teamIdArg = getArgValue(args, "--teamId");
+
+	// If no --title flag, check for positional title (legacy backwards compatibility)
+	if (!title && args[0] && !args[0].startsWith("--")) {
+		title = args[0];
+		optionsStartIndex = 1;
+
+		// Check for positional teamId (legacy)
+		if (!teamIdArg && args[1] && !args[1].startsWith("--")) {
+			teamIdArg = args[1];
+			optionsStartIndex = 2;
+		}
+	}
+
+	if (!title) {
+		console.error("Error: Please provide issue title");
+		console.error("Use --title \"title\" or provide as first argument");
+		console.error("");
+		printUsage();
+		return null;
+	}
+
+	// Get teamId from arg or config
+	const teamId = teamIdArg || getTeamIdOrExit(undefined);
+
+	const options: CreateOptions = { title, teamId };
+
+	// Parse named options
+	for (let i = optionsStartIndex; i < args.length; i++) {
+		const arg = args[i];
+		const nextArg = args[i + 1];
+
+		// Skip already-processed flags
+		if (arg === "--title" || arg === "--teamId") {
+			if (nextArg && !nextArg.startsWith("--")) {
+				i++; // Skip the value too
+			}
+			continue;
+		}
+
+		switch (arg) {
+			case "--description":
+				if (nextArg && !nextArg.startsWith("--")) {
+					options.description = nextArg;
+					i++;
+				}
+				break;
+			case "--state":
+				if (nextArg && !nextArg.startsWith("--")) {
+					options.stateId = nextArg;
+					i++;
+				}
+				break;
+			case "--priority":
+				if (nextArg && !nextArg.startsWith("--")) {
+					const priority = parseInt(nextArg);
+					if (priority >= 0 && priority <= 4) {
+						options.priority = priority;
+					} else {
+						console.error("Error: Priority must be 0-4");
+						return null;
+					}
+					i++;
+				}
+				break;
+			case "--assignee":
+				if (nextArg && !nextArg.startsWith("--")) {
+					options.assigneeId = nextArg;
+					i++;
+				}
+				break;
+			case "--labels":
+				if (nextArg && !nextArg.startsWith("--")) {
+					options.labelIds = nextArg.split(",").map(id => id.trim());
+					i++;
+				}
+				break;
+			case "--project":
+				if (nextArg && !nextArg.startsWith("--")) {
+					options.projectId = nextArg;
+					i++;
+				}
+				break;
+			case "--estimate":
+				if (nextArg && !nextArg.startsWith("--")) {
+					options.estimate = parseInt(nextArg);
+					i++;
+				}
+				break;
+			case "--due":
+				if (nextArg && !nextArg.startsWith("--")) {
+					options.dueDate = nextArg;
+					i++;
+				}
+				break;
+			case "--parent":
+				if (nextArg && !nextArg.startsWith("--")) {
+					options.parentId = nextArg;
+					i++;
+				}
+				break;
+			case "--cycle":
+				if (nextArg && !nextArg.startsWith("--")) {
+					options.cycleId = nextArg;
+					i++;
+				}
+				break;
+			case "--json":
+				// Handled by outputWithJq
+				break;
+			default:
+				// Ignore unknown flags
+				break;
+		}
+	}
+
+	return options;
+}
+
+async function createIssue() {
+	const options = parseArgs();
+	if (!options) {
+		process.exit(1);
+	}
+
+	// Resolve parentId if it's an identifier (AA-123) to UUID
+	let resolvedParentId: string | undefined;
+	if (options.parentId) {
+		resolvedParentId = await resolveIssueId(options.parentId);
+	}
+
+	// Build the input object with only defined fields
+	const input = {
+		title: options.title,
+		teamId: options.teamId,
+		...(options.description !== undefined && { description: options.description }),
+		...(options.stateId !== undefined && { stateId: options.stateId }),
+		...(options.priority !== undefined && { priority: options.priority }),
+		...(options.assigneeId !== undefined && { assigneeId: options.assigneeId }),
+		...(options.labelIds !== undefined && { labelIds: options.labelIds }),
+		...(options.projectId !== undefined && { projectId: options.projectId }),
+		...(options.estimate !== undefined && { estimate: options.estimate }),
+		...(options.dueDate !== undefined && { dueDate: options.dueDate }),
+		...(resolvedParentId !== undefined && { parentId: resolvedParentId }),
+		...(options.cycleId !== undefined && { cycleId: options.cycleId }),
+	};
+
+	const issuePayload = await client.createIssue(input);
+	const issue = await issuePayload.issue;
+
+	if (!issue) {
+		console.error("Failed to create issue");
+		process.exit(1);
+	}
+
+	// Fetch additional details for output
+	const state = await issue.state;
+	const assignee = await issue.assignee;
+	const project = await issue.project;
+	const parent = await issue.parent;
+
+	outputWithJq({
+		id: issue.id,
+		identifier: issue.identifier,
+		title: issue.title,
+		description: issue.description,
+		url: issue.url,
+		priority: issue.priority,
+		priorityLabel: issue.priorityLabel,
+		estimate: issue.estimate,
+		dueDate: issue.dueDate,
+		state: state ? { id: state.id, name: state.name } : null,
+		assignee: assignee ? { id: assignee.id, name: assignee.name, email: assignee.email } : null,
+		project: project ? { id: project.id, name: project.name } : null,
+		parent: parent ? { id: parent.id, identifier: parent.identifier } : null,
+		createdAt: issue.createdAt,
+	});
+}
+
+createIssue().catch((error) => {
+	console.error("Error creating issue:", error.message);
+	process.exit(1);
+});