@supaku/agentfactory-cli 0.7.5 → 0.7.7

package/dist/src/__tests__/subpath-exports.test.js

@@ -39,4 +39,14 @@ describe('@supaku/agentfactory-cli subpath exports', () => {
         expect(mod.runLogAnalyzer).toBeDefined();
         expect(typeof mod.runLogAnalyzer).toBe('function');
     });
+    it('exports runLinear from ./linear', async () => {
+        const mod = await import('../lib/linear-runner.js');
+        expect(mod.runLinear).toBeDefined();
+        expect(typeof mod.runLinear).toBe('function');
+    });
+    it('exports parseLinearArgs from ./linear', async () => {
+        const mod = await import('../lib/linear-runner.js');
+        expect(mod.parseLinearArgs).toBeDefined();
+        expect(typeof mod.parseLinearArgs).toBe('function');
+    });
 });

package/dist/src/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":";AACA;;;;;GAKG;AAEH,QAAA,MAAM,OAAO,QAAkB,CAAA;AAE/B,iBAAS,SAAS,IAAI,IAAI,CAoBzB"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":";AACA;;;;;GAKG;AAEH,QAAA,MAAM,OAAO,QAAkB,CAAA;AAE/B,iBAAS,SAAS,IAAI,IAAI,CAqBzB"}

package/dist/src/index.js

@@ -21,6 +21,7 @@ Commands:
   cleanup         Clean up orphaned git worktrees
   queue-admin     Manage Redis work queue and sessions
   analyze-logs    Analyze agent session logs for errors
+  linear          Linear issue tracker operations
   help            Show this help message
 
 Run 'agentfactory <command> --help' for command-specific options.
@@ -47,6 +48,9 @@ switch (command) {
     case 'analyze-logs':
         import('./analyze-logs');
         break;
+    case 'linear':
+        import('./linear');
+        break;
     case 'help':
     case '--help':
     case '-h':

package/dist/src/lib/linear-runner.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Linear CLI Runner — process-agnostic Linear operations.
+ *
+ * All 15 command implementations extracted from packages/core/src/linear-cli.ts.
+ * This module does NOT call process.exit, read process.argv, or load dotenv.
+ */
+export interface LinearRunnerConfig {
+    command: string;
+    args: Record<string, string | string[] | boolean>;
+    positionalArgs: string[];
+    apiKey?: string;
+}
+export interface LinearRunnerResult {
+    output: unknown;
+}
+/**
+ * Parse CLI arguments into a structured object.
+ *
+ * Supports:
+ * - `--key value` pairs
+ * - JSON array values: `--labels '["Bug", "Feature"]'`
+ * - Comma-separated values for array fields: `--labels "Bug,Feature"`
+ * - Boolean flags: `--dry-run` (value = "true")
+ *
+ * Returns the command (first non-flag arg), named args, and positional args.
+ */
+export declare function parseLinearArgs(argv: string[]): {
+    command: string | undefined;
+    args: Record<string, string | string[] | boolean>;
+    positionalArgs: string[];
+};
+export declare function runLinear(config: LinearRunnerConfig): Promise<LinearRunnerResult>;
+//# sourceMappingURL=linear-runner.d.ts.map

package/dist/src/lib/linear-runner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"linear-runner.d.ts","sourceRoot":"","sources":["../../../src/lib/linear-runner.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAUH,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,MAAM,CAAA;IACf,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,OAAO,CAAC,CAAA;IACjD,cAAc,EAAE,MAAM,EAAE,CAAA;IACxB,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB;AAED,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,OAAO,CAAA;CAChB;AAOD;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG;IAC/C,OAAO,EAAE,MAAM,GAAG,SAAS,CAAA;IAC3B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,OAAO,CAAC,CAAA;IACjD,cAAc,EAAE,MAAM,EAAE,CAAA;CACzB,CA2CA;AAymBD,wBAAsB,SAAS,CAAC,MAAM,EAAE,kBAAkB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CA2MvF"}

package/dist/src/lib/linear-runner.js

@@ -0,0 +1,681 @@
+/**
+ * Linear CLI Runner — process-agnostic Linear operations.
+ *
+ * All 15 command implementations extracted from packages/core/src/linear-cli.ts.
+ * This module does NOT call process.exit, read process.argv, or load dotenv.
+ */
+import { createLinearAgentClient } from '@supaku/agentfactory-linear';
+import { checkPRDeploymentStatus, formatDeploymentStatus, } from '@supaku/agentfactory';
+// ── Arg parsing ────────────────────────────────────────────────────
+/** Fields that should be split on commas to create arrays */
+const ARRAY_FIELDS = new Set(['labels']);
+/**
+ * Parse CLI arguments into a structured object.
+ *
+ * Supports:
+ * - `--key value` pairs
+ * - JSON array values: `--labels '["Bug", "Feature"]'`
+ * - Comma-separated values for array fields: `--labels "Bug,Feature"`
+ * - Boolean flags: `--dry-run` (value = "true")
+ *
+ * Returns the command (first non-flag arg), named args, and positional args.
+ */
+export function parseLinearArgs(argv) {
+    const command = argv[0] && !argv[0].startsWith('--') ? argv[0] : undefined;
+    const rest = command ? argv.slice(1) : argv;
+    const args = {};
+    const positionalArgs = [];
+    for (let i = 0; i < rest.length; i++) {
+        const arg = rest[i];
+        if (arg.startsWith('--')) {
+            const key = arg.slice(2);
+            const value = rest[i + 1];
+            if (value && !value.startsWith('--')) {
+                // Support JSON array format: --labels '["Bug", "Feature"]'
+                if (value.startsWith('[') && value.endsWith(']')) {
+                    try {
+                        const parsed = JSON.parse(value);
+                        if (Array.isArray(parsed)) {
+                            args[key] = parsed;
+                            i++;
+                            continue;
+                        }
+                    }
+                    catch {
+                        // Not valid JSON, fall through to normal handling
+                    }
+                }
+                // Only split on comma for known array fields
+                if (ARRAY_FIELDS.has(key) && value.includes(',')) {
+                    args[key] = value.split(',').map((v) => v.trim());
+                }
+                else {
+                    args[key] = value;
+                }
+                i++;
+            }
+            else {
+                args[key] = true;
+            }
+        }
+        else {
+            positionalArgs.push(arg);
+        }
+    }
+    return { command, args, positionalArgs };
+}
+// ── Command implementations ────────────────────────────────────────
+async function getIssue(client, issueId) {
+    const issue = await client.getIssue(issueId);
+    const state = await issue.state;
+    const team = await issue.team;
+    const project = await issue.project;
+    const labels = await issue.labels();
+    return {
+        id: issue.id,
+        identifier: issue.identifier,
+        title: issue.title,
+        description: issue.description,
+        url: issue.url,
+        status: state?.name,
+        team: team?.name,
+        project: project?.name,
+        labels: labels.nodes.map((l) => l.name),
+        createdAt: issue.createdAt,
+        updatedAt: issue.updatedAt,
+    };
+}
+async function createIssue(client, options) {
+    const team = await client.getTeam(options.team);
+    const createPayload = {
+        teamId: team.id,
+        title: options.title,
+    };
+    if (options.description) {
+        createPayload.description = options.description;
+    }
+    if (options.parentId) {
+        createPayload.parentId = options.parentId;
+    }
+    if (options.project) {
+        const projects = await client.linearClient.projects({
+            filter: { name: { eq: options.project } },
+        });
+        if (projects.nodes.length > 0) {
+            createPayload.projectId = projects.nodes[0].id;
+        }
+    }
+    if (options.state) {
+        const statuses = await client.getTeamStatuses(team.id);
+        const stateId = statuses[options.state];
+        if (stateId) {
+            createPayload.stateId = stateId;
+        }
+    }
+    if (options.labels && options.labels.length > 0) {
+        const allLabels = await client.linearClient.issueLabels();
+        const labelIds = [];
+        for (const labelName of options.labels) {
+            const label = allLabels.nodes.find((l) => l.name.toLowerCase() === labelName.toLowerCase());
+            if (label) {
+                labelIds.push(label.id);
+            }
+        }
+        if (labelIds.length > 0) {
+            createPayload.labelIds = labelIds;
+        }
+    }
+    const payload = await client.linearClient.createIssue(createPayload);
+    if (!payload.success) {
+        throw new Error('Failed to create issue');
+    }
+    const issue = await payload.issue;
+    if (!issue) {
+        throw new Error('Issue created but not returned');
+    }
+    return {
+        id: issue.id,
+        identifier: issue.identifier,
+        title: issue.title,
+        url: issue.url,
+    };
+}
+async function updateIssue(client, issueId, options) {
+    const issue = await client.getIssue(issueId);
+    const team = await issue.team;
+    const updateData = {};
+    if (options.title) {
+        updateData.title = options.title;
+    }
+    if (options.description) {
+        updateData.description = options.description;
+    }
+    if (options.state && team) {
+        const statuses = await client.getTeamStatuses(team.id);
+        const stateId = statuses[options.state];
+        if (stateId) {
+            updateData.stateId = stateId;
+        }
+    }
+    if (options.labels && options.labels.length > 0) {
+        const allLabels = await client.linearClient.issueLabels();
+        const labelIds = [];
+        for (const labelName of options.labels) {
+            const label = allLabels.nodes.find((l) => l.name.toLowerCase() === labelName.toLowerCase());
+            if (label) {
+                labelIds.push(label.id);
+            }
+        }
+        updateData.labelIds = labelIds;
+    }
+    const updatedIssue = await client.updateIssue(issue.id, updateData);
+    const state = await updatedIssue.state;
+    return {
+        id: updatedIssue.id,
+        identifier: updatedIssue.identifier,
+        title: updatedIssue.title,
+        status: state?.name,
+        url: updatedIssue.url,
+    };
+}
+async function listComments(client, issueId) {
+    const comments = await client.getIssueComments(issueId);
+    return comments.map((c) => ({
+        id: c.id,
+        body: c.body,
+        createdAt: c.createdAt,
+    }));
+}
+async function createComment(client, issueId, body) {
+    const comment = await client.createComment(issueId, body);
+    return {
+        id: comment.id,
+        body: comment.body,
+        createdAt: comment.createdAt,
+    };
+}
+async function addRelation(client, issueId, relatedIssueId, relationType) {
+    const result = await client.createIssueRelation({
+        issueId,
+        relatedIssueId,
+        type: relationType,
+    });
+    return {
+        success: result.success,
+        relationId: result.relationId,
+        issueId,
+        relatedIssueId,
+        type: relationType,
+    };
+}
+async function listRelations(client, issueId) {
+    const result = await client.getIssueRelations(issueId);
+    return {
+        issueId,
+        relations: result.relations.map((r) => ({
+            id: r.id,
+            type: r.type,
+            relatedIssue: r.relatedIssueIdentifier ?? r.relatedIssueId,
+            createdAt: r.createdAt,
+        })),
+        inverseRelations: result.inverseRelations.map((r) => ({
+            id: r.id,
+            type: r.type,
+            sourceIssue: r.issueIdentifier ?? r.issueId,
+            createdAt: r.createdAt,
+        })),
+    };
+}
+async function removeRelation(client, relationId) {
+    const result = await client.deleteIssueRelation(relationId);
+    return {
+        success: result.success,
+        relationId,
+    };
+}
+async function listBacklogIssues(client, projectName) {
+    const projects = await client.linearClient.projects({
+        filter: { name: { eqIgnoreCase: projectName } },
+    });
+    if (projects.nodes.length === 0) {
+        throw new Error(`Project not found: ${projectName}`);
+    }
+    const project = projects.nodes[0];
+    const issues = await client.linearClient.issues({
+        filter: {
+            project: { id: { eq: project.id } },
+            state: { name: { eqIgnoreCase: 'Backlog' } },
+        },
+    });
+    const results = [];
+    for (const issue of issues.nodes) {
+        const state = await issue.state;
+        const labels = await issue.labels();
+        results.push({
+            id: issue.id,
+            identifier: issue.identifier,
+            title: issue.title,
+            description: issue.description,
+            url: issue.url,
+            priority: issue.priority,
+            status: state?.name,
+            labels: labels.nodes.map((l) => l.name),
+        });
+    }
+    results.sort((a, b) => {
+        const aPriority = a.priority || 5;
+        const bPriority = b.priority || 5;
+        return aPriority - bPriority;
+    });
+    return results;
+}
+async function getBlockingIssues(client, issueId) {
+    const relations = await client.getIssueRelations(issueId);
+    const blockingIssues = [];
+    for (const relation of relations.inverseRelations) {
+        if (relation.type === 'blocks') {
+            const blockingIssue = await client.getIssue(relation.issueId);
+            const state = await blockingIssue.state;
+            const statusName = state?.name ?? 'Unknown';
+            if (statusName !== 'Accepted') {
+                blockingIssues.push({
+                    identifier: blockingIssue.identifier,
+                    title: blockingIssue.title,
+                    status: statusName,
+                });
+            }
+        }
+    }
+    return blockingIssues;
+}
+async function listUnblockedBacklogIssues(client, projectName) {
+    const projects = await client.linearClient.projects({
+        filter: { name: { eqIgnoreCase: projectName } },
+    });
+    if (projects.nodes.length === 0) {
+        throw new Error(`Project not found: ${projectName}`);
+    }
+    const project = projects.nodes[0];
+    const issues = await client.linearClient.issues({
+        filter: {
+            project: { id: { eq: project.id } },
+            state: { name: { eqIgnoreCase: 'Backlog' } },
+        },
+    });
+    const results = [];
+    for (const issue of issues.nodes) {
+        const blockingIssues = await getBlockingIssues(client, issue.id);
+        const state = await issue.state;
+        const labels = await issue.labels();
+        results.push({
+            id: issue.id,
+            identifier: issue.identifier,
+            title: issue.title,
+            description: issue.description,
+            url: issue.url,
+            priority: issue.priority,
+            status: state?.name,
+            labels: labels.nodes.map((l) => l.name),
+            blocked: blockingIssues.length > 0,
+            blockedBy: blockingIssues,
+        });
+    }
+    const unblockedResults = results.filter((r) => !r.blocked);
+    unblockedResults.sort((a, b) => {
+        const aPriority = a.priority || 5;
+        const bPriority = b.priority || 5;
+        return aPriority - bPriority;
+    });
+    return unblockedResults;
+}
+async function checkBlocked(client, issueId) {
+    const blockingIssues = await getBlockingIssues(client, issueId);
+    return {
+        issueId,
+        blocked: blockingIssues.length > 0,
+        blockedBy: blockingIssues,
+    };
+}
+async function listSubIssues(client, issueId) {
+    const graph = await client.getSubIssueGraph(issueId);
+    return {
+        parentId: graph.parentId,
+        parentIdentifier: graph.parentIdentifier,
+        subIssueCount: graph.subIssues.length,
+        subIssues: graph.subIssues.map((node) => ({
+            id: node.issue.id,
+            identifier: node.issue.identifier,
+            title: node.issue.title,
+            status: node.issue.status,
+            priority: node.issue.priority,
+            labels: node.issue.labels,
+            url: node.issue.url,
+            blockedBy: node.blockedBy,
+            blocks: node.blocks,
+        })),
+    };
+}
+async function listSubIssueStatuses(client, issueId) {
+    const statuses = await client.getSubIssueStatuses(issueId);
+    return {
+        parentIssue: issueId,
+        subIssueCount: statuses.length,
+        subIssues: statuses,
+        allFinishedOrLater: statuses.every((s) => ['Finished', 'Delivered', 'Accepted', 'Canceled'].includes(s.status)),
+        incomplete: statuses.filter((s) => !['Finished', 'Delivered', 'Accepted', 'Canceled'].includes(s.status)),
+    };
+}
+async function updateSubIssue(client, issueId, options) {
+    const issue = await client.getIssue(issueId);
+    if (options.state) {
+        await client.updateIssueStatus(issue.id, options.state);
+    }
+    if (options.comment) {
+        await client.createComment(issue.id, options.comment);
+    }
+    const updatedIssue = await client.getIssue(issueId);
+    const state = await updatedIssue.state;
+    return {
+        id: updatedIssue.id,
+        identifier: updatedIssue.identifier,
+        title: updatedIssue.title,
+        status: state?.name,
+        url: updatedIssue.url,
+    };
+}
+async function checkDeployment(prNumber, format = 'json') {
+    const result = await checkPRDeploymentStatus(prNumber);
+    if (!result) {
+        throw new Error(`Could not get deployment status for PR #${prNumber}. Make sure the PR exists and you have access to it.`);
+    }
+    if (format === 'markdown') {
+        return formatDeploymentStatus(result);
+    }
+    return result;
+}
+async function createBlocker(client, options) {
+    // 1. Fetch source issue to resolve team/project
+    const sourceIssue = await client.getIssue(options.sourceIssueId);
+    const sourceTeam = await sourceIssue.team;
+    const sourceProject = await sourceIssue.project;
+    const teamName = options.team ?? sourceTeam?.name;
+    if (!teamName) {
+        throw new Error('Could not resolve team from source issue. Provide --team explicitly.');
+    }
+    const team = await client.getTeam(teamName);
+    const projectName = options.project ?? sourceProject?.name;
+    // 2. Deduplicate: check for existing Icebox issues with same title + "Needs Human" label
+    if (projectName) {
+        const projects = await client.linearClient.projects({
+            filter: { name: { eqIgnoreCase: projectName } },
+        });
+        if (projects.nodes.length > 0) {
+            const existingIssues = await client.linearClient.issues({
+                filter: {
+                    project: { id: { eq: projects.nodes[0].id } },
+                    state: { name: { eqIgnoreCase: 'Icebox' } },
+                    labels: { name: { eqIgnoreCase: 'Needs Human' } },
+                },
+            });
+            const duplicate = existingIssues.nodes.find((i) => i.title.toLowerCase() === options.title.toLowerCase());
+            if (duplicate) {
+                // Add a +1 comment to the existing issue
+                await client.createComment(duplicate.id, `+1 — Also needed by ${sourceIssue.identifier}`);
+                return {
+                    id: duplicate.id,
+                    identifier: duplicate.identifier,
+                    title: duplicate.title,
+                    url: duplicate.url,
+                    sourceIssue: sourceIssue.identifier,
+                    relation: 'blocks',
+                    deduplicated: true,
+                };
+            }
+        }
+    }
+    // 3. Create the blocker issue
+    const createPayload = {
+        teamId: team.id,
+        title: options.title,
+    };
+    // Description with source reference
+    const descParts = [];
+    if (options.description) {
+        descParts.push(options.description);
+    }
+    descParts.push(`\n---\n*Source issue: ${sourceIssue.identifier}*`);
+    createPayload.description = descParts.join('\n\n');
+    // Set state to Icebox
+    const statuses = await client.getTeamStatuses(team.id);
+    const iceboxStateId = statuses['Icebox'];
+    if (iceboxStateId) {
+        createPayload.stateId = iceboxStateId;
+    }
+    // Set "Needs Human" label
+    const allLabels = await client.linearClient.issueLabels();
+    const needsHumanLabel = allLabels.nodes.find((l) => l.name.toLowerCase() === 'needs human');
+    if (needsHumanLabel) {
+        createPayload.labelIds = [needsHumanLabel.id];
+    }
+    // Set project
+    if (projectName) {
+        const projects = await client.linearClient.projects({
+            filter: { name: { eqIgnoreCase: projectName } },
+        });
+        if (projects.nodes.length > 0) {
+            createPayload.projectId = projects.nodes[0].id;
+        }
+    }
+    const payload = await client.linearClient.createIssue(createPayload);
+    if (!payload.success) {
+        throw new Error('Failed to create blocker issue');
+    }
+    const blockerIssue = await payload.issue;
+    if (!blockerIssue) {
+        throw new Error('Blocker issue created but not returned');
+    }
+    // 4. Create blocking relation: blocker blocks source
+    await client.createIssueRelation({
+        issueId: blockerIssue.id,
+        relatedIssueId: sourceIssue.id,
+        type: 'blocks',
+    });
+    // 5. Post comment on source issue
+    await client.createComment(sourceIssue.id, `\u{1F6A7} Human blocker created: [${blockerIssue.identifier}](${blockerIssue.url}) — ${options.title}`);
+    // 6. Optionally assign
+    if (options.assignee) {
+        const users = await client.linearClient.users({
+            filter: {
+                or: [
+                    { name: { eqIgnoreCase: options.assignee } },
+                    { email: { eq: options.assignee } },
+                ],
+            },
+        });
+        if (users.nodes.length > 0) {
+            await client.linearClient.updateIssue(blockerIssue.id, {
+                assigneeId: users.nodes[0].id,
+            });
+        }
+    }
+    return {
+        id: blockerIssue.id,
+        identifier: blockerIssue.identifier,
+        title: blockerIssue.title,
+        url: blockerIssue.url,
+        sourceIssue: sourceIssue.identifier,
+        relation: 'blocks',
+        deduplicated: false,
+    };
+}
+// ── Commands that don't require LINEAR_API_KEY ─────────────────────
+const NO_API_KEY_COMMANDS = new Set(['check-deployment']);
+// ── Main runner ────────────────────────────────────────────────────
+export async function runLinear(config) {
+    const { command, args, positionalArgs, apiKey } = config;
+    // Lazy client — only created for commands that need it
+    let _client = null;
+    function client() {
+        if (!_client) {
+            if (!apiKey) {
+                throw new Error('LINEAR_API_KEY environment variable is required');
+            }
+            _client = createLinearAgentClient({ apiKey });
+        }
+        return _client;
+    }
+    // Validate API key for commands that need it
+    if (!NO_API_KEY_COMMANDS.has(command) && !apiKey) {
+        throw new Error('LINEAR_API_KEY environment variable is required');
+    }
+    // Helper: get first positional or error
+    function requirePositional(name) {
+        const val = positionalArgs[0];
+        if (!val || val.startsWith('--')) {
+            throw new Error(`Missing required argument: <${name}>`);
+        }
+        return val;
+    }
+    // Parse sub-options from the original args (for commands that re-parse after positional)
+    function subArgs() {
+        return args;
+    }
+    let output;
+    switch (command) {
+        case 'get-issue': {
+            const issueId = requirePositional('issue-id');
+            output = await getIssue(client(), issueId);
+            break;
+        }
+        case 'create-issue': {
+            if (!args.title || !args.team) {
+                throw new Error('Usage: af-linear create-issue --title "Title" --team "Team" [--description "..."] [--project "..."] [--labels "Label1,Label2"] [--state "Backlog"] [--parentId "..."]');
+            }
+            output = await createIssue(client(), {
+                title: args.title,
+                team: args.team,
+                description: args.description,
+                project: args.project,
+                labels: args.labels,
+                state: args.state,
+                parentId: args.parentId,
+            });
+            break;
+        }
+        case 'update-issue': {
+            const issueId = requirePositional('issue-id');
+            const opts = subArgs();
+            output = await updateIssue(client(), issueId, {
+                title: opts.title,
+                description: opts.description,
+                state: opts.state,
+                labels: opts.labels,
+            });
+            break;
+        }
+        case 'list-comments': {
+            const issueId = requirePositional('issue-id');
+            output = await listComments(client(), issueId);
+            break;
+        }
+        case 'create-comment': {
+            const issueId = requirePositional('issue-id');
+            if (!args.body) {
+                throw new Error('Usage: af-linear create-comment <issue-id> --body "Comment text"');
+            }
+            output = await createComment(client(), issueId, args.body);
+            break;
+        }
+        case 'list-backlog-issues': {
+            if (!args.project) {
+                throw new Error('Usage: af-linear list-backlog-issues --project "ProjectName"');
+            }
+            output = await listBacklogIssues(client(), args.project);
+            break;
+        }
+        case 'list-unblocked-backlog': {
+            if (!args.project) {
+                throw new Error('Usage: af-linear list-unblocked-backlog --project "ProjectName"');
+            }
+            output = await listUnblockedBacklogIssues(client(), args.project);
+            break;
+        }
+        case 'check-blocked': {
+            const issueId = requirePositional('issue-id');
+            output = await checkBlocked(client(), issueId);
+            break;
+        }
+        case 'add-relation': {
+            const issueId = positionalArgs[0];
+            const relatedIssueId = positionalArgs[1];
+            const relationType = args.type;
+            if (!issueId ||
+                issueId.startsWith('--') ||
+                !relatedIssueId ||
+                relatedIssueId.startsWith('--') ||
+                !relationType ||
+                !['related', 'blocks', 'duplicate'].includes(relationType)) {
+                throw new Error('Usage: af-linear add-relation <issue-id> <related-issue-id> --type <related|blocks|duplicate>');
+            }
+            output = await addRelation(client(), issueId, relatedIssueId, relationType);
+            break;
+        }
+        case 'list-relations': {
+            const issueId = requirePositional('issue-id');
+            output = await listRelations(client(), issueId);
+            break;
+        }
+        case 'remove-relation': {
+            const relationId = requirePositional('relation-id');
+            output = await removeRelation(client(), relationId);
+            break;
+        }
+        case 'list-sub-issues': {
+            const issueId = requirePositional('issue-id');
+            output = await listSubIssues(client(), issueId);
+            break;
+        }
+        case 'list-sub-issue-statuses': {
+            const issueId = requirePositional('issue-id');
+            output = await listSubIssueStatuses(client(), issueId);
+            break;
+        }
+        case 'update-sub-issue': {
+            const issueId = requirePositional('issue-id');
+            const opts = subArgs();
+            output = await updateSubIssue(client(), issueId, {
+                state: opts.state,
+                comment: opts.comment,
+            });
+            break;
+        }
+        case 'check-deployment': {
+            const prArg = requirePositional('pr-number');
+            const prNumber = parseInt(prArg, 10);
+            if (isNaN(prNumber)) {
+                throw new Error('PR number must be a valid integer');
+            }
+            const format = args.format || 'json';
+            output = await checkDeployment(prNumber, format);
+            break;
+        }
+        case 'create-blocker': {
+            const sourceIssueId = requirePositional('source-issue-id');
+            if (!args.title) {
+                throw new Error('Usage: af-linear create-blocker <source-issue-id> --title "Title" [--description "..."] [--team "..."] [--project "..."] [--assignee "user@email.com"]');
+            }
+            output = await createBlocker(client(), {
+                title: args.title,
+                sourceIssueId,
+                description: args.description,
+                team: args.team,
+                project: args.project,
+                assignee: args.assignee,
+            });
+            break;
+        }
+        default:
+            throw new Error(`Unknown command: ${command}`);
+    }
+    return { output };
+}

package/dist/src/lib/worker-runner.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"worker-runner.d.ts","sourceRoot":"","sources":["../../../src/lib/worker-runner.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAmBH,MAAM,WAAW,kBAAkB;IACjC,0BAA0B;IAC1B,MAAM,EAAE,MAAM,CAAA;IACd,iCAAiC;IACjC,MAAM,EAAE,MAAM,CAAA;IACd,+CAA+C;IAC/C,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,6CAA6C;IAC7C,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,mDAAmD;IACnD,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,gFAAgF;IAChF,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,iDAAiD;IACjD,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,uDAAuD;IACvD,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAA;CACpB;AAwED;;;;;GAKG;AACH,wBAAsB,SAAS,CAC7B,MAAM,EAAE,kBAAkB,EAC1B,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,IAAI,CAAC,CAm4Bf"}
+{"version":3,"file":"worker-runner.d.ts","sourceRoot":"","sources":["../../../src/lib/worker-runner.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAmBH,MAAM,WAAW,kBAAkB;IACjC,0BAA0B;IAC1B,MAAM,EAAE,MAAM,CAAA;IACd,iCAAiC;IACjC,MAAM,EAAE,MAAM,CAAA;IACd,+CAA+C;IAC/C,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,6CAA6C;IAC7C,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,mDAAmD;IACnD,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,gFAAgF;IAChF,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,iDAAiD;IACjD,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,uDAAuD;IACvD,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAA;CACpB;AAwED;;;;;GAKG;AACH,wBAAsB,SAAS,CAC7B,MAAM,EAAE,kBAAkB,EAC1B,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,IAAI,CAAC,CAw5Bf"}

package/dist/src/lib/worker-runner.js

@@ -54,6 +54,7 @@ export async function runWorker(config, signal) {
     let shutdownInProgress = false;
     let consecutiveHeartbeatFailures = 0;
     let reregistrationInProgress = false;
+    let claimFailureCount = 0;
     const activeOrchestrators = new Map();
     // Logger — will be re-created after registration with worker context
     let log = createLogger({}, { showTimestamp: true });
@@ -241,6 +242,10 @@ export async function runWorker(config, signal) {
         });
         if (result.data) {
             consecutiveHeartbeatFailures = 0;
+            if (claimFailureCount > 0) {
+                log.info('Claim race summary since last heartbeat', { claimFailures: claimFailureCount });
+                claimFailureCount = 0;
+            }
             log.debug('Heartbeat acknowledged', {
                 activeCount,
                 pendingWorkCount: result.data.pendingWorkCount,
@@ -608,6 +613,19 @@ export async function runWorker(config, signal) {
         workerShortId = registration.workerId.substring(0, 8);
         // Update logger with worker context
         log = createLogger({ workerId, workerShortId }, { showTimestamp: true });
+        // Auto-inherit projects from server if not explicitly configured
+        if (!config.projects?.length) {
+            try {
+                const serverConfig = await apiRequest('/api/config');
+                if (serverConfig?.projects?.length) {
+                    config.projects = serverConfig.projects;
+                    log.info('Auto-inherited projects from server', { projects: config.projects });
+                }
+            }
+            catch {
+                log.debug('Could not fetch server config, using no project filter');
+            }
+        }
         // Set up heartbeat
         heartbeatTimer = setInterval(() => sendHeartbeat(), registration.heartbeatInterval);
         // Send initial heartbeat
@@ -644,7 +662,8 @@ export async function runWorker(config, signal) {
                             }
                         }
                         else {
-                            log.warn(`Failed to claim work: ${item.issueIdentifier}`);
+                            claimFailureCount++;
+                            log.debug(`Failed to claim work: ${item.issueIdentifier}`);
                         }
                     }
                 }

package/dist/src/linear.d.ts

@@ -0,0 +1,37 @@
+#!/usr/bin/env node
+/**
+ * AgentFactory Linear CLI
+ *
+ * Thin wrapper around the linear runner.
+ *
+ * Usage:
+ *   af-linear <command> [options]
+ *
+ * Commands:
+ *   get-issue <id>              Get issue details
+ *   create-issue                Create a new issue
+ *   update-issue <id>           Update an existing issue
+ *   list-comments <issueId>     List comments on an issue
+ *   create-comment <issueId>    Create a comment on an issue
+ *   list-backlog-issues         List backlog issues for a project
+ *   list-unblocked-backlog      List unblocked backlog issues
+ *   check-blocked <id>          Check if an issue is blocked
+ *   add-relation <id> <id>      Create relation between issues
+ *   list-relations <id>         List relations for an issue
+ *   remove-relation <id>        Remove a relation by ID
+ *   list-sub-issues <id>        List sub-issues of a parent issue
+ *   list-sub-issue-statuses <id> List sub-issue statuses (lightweight)
+ *   update-sub-issue <id>       Update sub-issue status with comment
+ *   check-deployment <PR>       Check Vercel deployment status for a PR
+ *   create-blocker <source-id>  Create a human-needed blocker issue
+ *
+ * Array Values:
+ *   --labels accepts comma-separated: --labels "Bug,Feature"
+ *   For values with commas, use JSON: --labels '["Bug", "UI, UX"]'
+ *   Text fields (--description, --title, --body) preserve commas.
+ *
+ * Environment:
+ *   LINEAR_API_KEY              Required API key for authentication
+ */
+export {};
+//# sourceMappingURL=linear.d.ts.map

package/dist/src/linear.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"linear.d.ts","sourceRoot":"","sources":["../../src/linear.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG"}

package/dist/src/linear.js

@@ -0,0 +1,118 @@
+#!/usr/bin/env node
+/**
+ * AgentFactory Linear CLI
+ *
+ * Thin wrapper around the linear runner.
+ *
+ * Usage:
+ *   af-linear <command> [options]
+ *
+ * Commands:
+ *   get-issue <id>              Get issue details
+ *   create-issue                Create a new issue
+ *   update-issue <id>           Update an existing issue
+ *   list-comments <issueId>     List comments on an issue
+ *   create-comment <issueId>    Create a comment on an issue
+ *   list-backlog-issues         List backlog issues for a project
+ *   list-unblocked-backlog      List unblocked backlog issues
+ *   check-blocked <id>          Check if an issue is blocked
+ *   add-relation <id> <id>      Create relation between issues
+ *   list-relations <id>         List relations for an issue
+ *   remove-relation <id>        Remove a relation by ID
+ *   list-sub-issues <id>        List sub-issues of a parent issue
+ *   list-sub-issue-statuses <id> List sub-issue statuses (lightweight)
+ *   update-sub-issue <id>       Update sub-issue status with comment
+ *   check-deployment <PR>       Check Vercel deployment status for a PR
+ *   create-blocker <source-id>  Create a human-needed blocker issue
+ *
+ * Array Values:
+ *   --labels accepts comma-separated: --labels "Bug,Feature"
+ *   For values with commas, use JSON: --labels '["Bug", "UI, UX"]'
+ *   Text fields (--description, --title, --body) preserve commas.
+ *
+ * Environment:
+ *   LINEAR_API_KEY              Required API key for authentication
+ */
+import path from 'path';
+import { config } from 'dotenv';
+// Load environment variables from .env.local
+config({ path: path.resolve(process.cwd(), '.env.local') });
+import { runLinear, parseLinearArgs } from './lib/linear-runner.js';
+function printHelp() {
+    console.log(`
+AgentFactory Linear CLI — Linear issue tracker operations
+
+Usage:
+  af-linear <command> [options]
+
+Commands:
+  get-issue <id>                Get issue details
+  create-issue                  Create a new issue
+  update-issue <id>             Update an existing issue
+  list-comments <issueId>       List comments on an issue
+  create-comment <issueId>      Create a comment on an issue
+  list-backlog-issues           List backlog issues for a project
+  list-unblocked-backlog        List unblocked backlog issues
+  check-blocked <id>            Check if an issue is blocked
+  add-relation <id> <id>        Create relation between issues
+  list-relations <id>           List relations for an issue
+  remove-relation <id>          Remove a relation by ID
+  list-sub-issues <id>          List sub-issues of a parent issue
+  list-sub-issue-statuses <id>  List sub-issue statuses (lightweight)
+  update-sub-issue <id>         Update sub-issue status with comment
+  check-deployment <PR>         Check Vercel deployment status for a PR
+  create-blocker <source-id>    Create a human-needed blocker issue
+  help                          Show this help message
+
+Options:
+  --help, -h                    Show this help message
+
+Array Values:
+  --labels accepts comma-separated: --labels "Bug,Feature"
+  For values with commas, use JSON: --labels '["Bug", "UI, UX"]'
+
+Environment:
+  LINEAR_API_KEY                Required API key for authentication
+  LINEAR_ACCESS_TOKEN           Alternative to LINEAR_API_KEY
+
+Examples:
+  af-linear get-issue PROJ-123
+  af-linear create-issue --title "Add auth" --team "Engineering" --project "Backend"
+  af-linear update-issue PROJ-123 --state "Finished"
+  af-linear list-backlog-issues --project "MyProject"
+  af-linear check-deployment 42
+`);
+}
+async function main() {
+    const { command, args, positionalArgs } = parseLinearArgs(process.argv.slice(2));
+    if (!command || command === 'help' || args['help'] || args['h']) {
+        printHelp();
+        return;
+    }
+    const apiKey = process.env.LINEAR_API_KEY || process.env.LINEAR_ACCESS_TOKEN;
+    const result = await runLinear({
+        command,
+        args,
+        positionalArgs,
+        apiKey,
+    });
+    // check-deployment with markdown format outputs a string, not JSON
+    if (typeof result.output === 'string') {
+        console.log(result.output);
+    }
+    else {
+        console.log(JSON.stringify(result.output, null, 2));
+    }
+    // Exit with error code if deployment check failed
+    if (command === 'check-deployment' &&
+        typeof result.output === 'object' &&
+        result.output !== null &&
+        'anyFailed' in result.output &&
+        result.output.anyFailed) {
+        process.exit(1);
+    }
+}
+main().catch((error) => {
+    console.error('Error:', error instanceof Error ? error.message : error);
+    process.exit(1);
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@supaku/agentfactory-cli",
-  "version": "0.7.5",
+  "version": "0.7.7",
   "type": "module",
   "description": "CLI tools for AgentFactory — local orchestrator, remote worker, queue admin",
   "author": "Supaku (https://supaku.com)",
@@ -33,7 +33,8 @@
     "af-worker-fleet": "./dist/src/worker-fleet.js",
     "af-cleanup": "./dist/src/cleanup.js",
     "af-queue-admin": "./dist/src/queue-admin.js",
-    "af-analyze-logs": "./dist/src/analyze-logs.js"
+    "af-analyze-logs": "./dist/src/analyze-logs.js",
+    "af-linear": "./dist/src/linear.js"
   },
   "main": "./dist/src/index.js",
   "module": "./dist/src/index.js",
@@ -73,6 +74,11 @@
       "types": "./dist/src/lib/analyze-logs-runner.d.ts",
       "import": "./dist/src/lib/analyze-logs-runner.js",
       "default": "./dist/src/lib/analyze-logs-runner.js"
+    },
+    "./linear": {
+      "types": "./dist/src/lib/linear-runner.d.ts",
+      "import": "./dist/src/lib/linear-runner.js",
+      "default": "./dist/src/lib/linear-runner.js"
     }
   },
   "files": [
@@ -82,9 +88,9 @@
   ],
   "dependencies": {
     "dotenv": "^17.2.3",
-    "@supaku/agentfactory-linear": "0.7.5",
-    "@supaku/agentfactory-server": "0.7.5",
-    "@supaku/agentfactory": "0.7.5"
+    "@supaku/agentfactory": "0.7.7",
+    "@supaku/agentfactory-server": "0.7.7",
+    "@supaku/agentfactory-linear": "0.7.7"
   },
   "devDependencies": {
     "@types/node": "^22.5.4",