@ihelpee/prumo-plugin-github-project 0.0.0-stage → 0.18.2

package/LICENSE

@@ -0,0 +1,51 @@
+Prumo Software License
+
+Copyright (c) 2026 IHELPEE TECNOLOGIA LTDA (https://ihelpee.com). All rights reserved.
+
+This license applies to Prumo version 0.17.0 and later: the @ihelpee/prumo
+package, its plugins and i18n packages, and their documentation (the
+"Software"). Versions published before 0.17.0 remain under the license each
+one was published with (MIT or Apache-2.0); this license does not change them.
+
+1. Grant. IHELPEE TECNOLOGIA LTDA ("IHELPEE") grants you a free,
+   non-exclusive, non-transferable, revocable license to install and run the
+   Software, as published by IHELPEE, to check your own projects. Your
+   projects may be commercial: a company may use the Software on the code of
+   the products it sells.
+
+2. Commercial exploitation is reserved. Only IHELPEE may make money from the
+   Software itself. Unless IHELPEE agrees in writing, you may not charge for,
+   or receive any payment or other consideration for, the Software or any
+   product or service whose value comes mainly from it, such as reselling
+   it, bundling it, hosting it, or paid consulting, training, support,
+   setup or certification built on it.
+
+3. Restrictions. Unless IHELPEE agrees in writing, you may not:
+   a. copy, modify, translate or create derivative works of the Software,
+      except copies made by installing and running it;
+   b. redistribute, sell, sublicense, rent or publish the Software, alone or
+      as part of another product;
+   c. offer the Software, or a substantial part of its functionality, to
+      third parties as a hosted or managed service;
+   d. reverse engineer, decompile or disassemble the Software, except where
+      the law allows it despite this restriction;
+   e. remove or alter any copyright, trademark or license notice.
+
+4. Trademarks. This license grants no right to the "Prumo" name, logo or
+   other marks. See docs/TRADEMARK.md.
+
+5. Termination. This license ends automatically if you breach it. On
+   termination you must stop using the Software and delete your copies.
+
+6. No warranty. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY
+   KIND, EXPRESS OR IMPLIED, INCLUDING MERCHANTABILITY, FITNESS FOR A
+   PARTICULAR PURPOSE AND NON-INFRINGEMENT.
+
+7. Limitation of liability. TO THE EXTENT PERMITTED BY LAW, IHELPEE IS NOT
+   LIABLE FOR ANY DAMAGES ARISING FROM THE USE OF, OR INABILITY TO USE, THE
+   SOFTWARE.
+
+8. Governing law. This license is governed by the laws of the Federative
+   Republic of Brazil.
+
+Other licensing: alexgotardi@gmail.com

package/README.md

@@ -1,3 +1,72 @@
-# Temporary Holding Version
+# @ihelpee/prumo-plugin-github-project
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Experimental, read-only GitHub Projects v2 and Issues client used by Prumo's pipeline plugin.
+It returns GitHub data in plain typed objects and does not decide whether an issue mutation is
+allowed. The pipeline owns that policy.
+
+## What it provides
+
+- `GitHubProjectClient` for GraphQL requests and issue details.
+- `parseIssueRef` for `owner/repo#123` references and GitHub issue URLs.
+- Issue data including title, body, state, assignees, comments, sub-issues and a selected project
+  status.
+- Optional project number filtering when an issue belongs to more than one project.
+
+This package does not create, edit, close, assign or move issues. It has no retry or pagination
+loop: the current issue-details query reads bounded pages (up to 100 comments, 50 sub-issues and
+10 project items).
+
+## Installation
+
+Install it with Prumo and the pipeline plugin at matching versions:
+
+```bash
+pnpm add @ihelpee/prumo @ihelpee/prumo-plugin-github-project @ihelpee/prumo-plugin-pipeline
+```
+
+## Use the client
+
+Provide a token with access to the target issue and project. The client reads `GH_TOKEN` or
+`GITHUB_TOKEN` when no token is passed explicitly.
+
+```ts
+import {
+  GitHubProjectClient,
+  parseIssueRef,
+} from '@ihelpee/prumo-plugin-github-project';
+
+const client = new GitHubProjectClient({ token: process.env.GH_TOKEN });
+const issue = await client.getIssueDetails(parseIssueRef('owner/repo#123'), 13);
+
+console.log(issue.projectStatus, issue.assignees, issue.subIssues);
+```
+
+The `apiUrl` option can point the client at a compatible GitHub API endpoint. Set `locale` to
+`en` or `pt-BR` to localize client-generated diagnostics; English is the default.
+
+## Use with the pipeline plugin
+
+Register both plugins in `prumo.config.ts`:
+
+```ts
+import { defineConfig } from '@ihelpee/prumo';
+import githubProject from '@ihelpee/prumo-plugin-github-project';
+import pipeline from '@ihelpee/prumo-plugin-pipeline';
+
+export default defineConfig({ plugins: [githubProject, pipeline] });
+```
+
+The pipeline uses this client to read issue and project state before evaluating its own
+preflight policy. See the [pipeline README](https://github.com/ihelpee/prumo/blob/main/packages/plugin-pipeline/README.md)
+for its commands and configuration.
+
+## Errors and access
+
+Requests fail with an explicit diagnostic when the token is missing, GitHub returns an HTTP or
+GraphQL error, or the issue cannot be found. Use a token with the least privilege that can read
+the repository issue and the requested project. The client does not log or persist the token.
+
+## Compatibility
+
+Use the same release version as `@ihelpee/prumo` and its companion plugins. This package is
+experimental; its API may change between minor releases.

package/dist/client.d.ts

@@ -0,0 +1,19 @@
+import type { SupportedLocale } from '@ihelpee/prumo/core';
+import type { GitHubIssueRef, RawIssueDetails } from './types.js';
+export interface GitHubClientOptions {
+    token?: string;
+    apiUrl?: string;
+    /** Language of error messages; English when absent. */
+    locale?: SupportedLocale;
+}
+export declare class GitHubProjectClient {
+    private readonly token;
+    private readonly apiUrl;
+    private readonly locale;
+    constructor(options?: GitHubClientOptions);
+    hasToken(): boolean;
+    private assertToken;
+    graphql<T = any>(query: string, variables?: Record<string, unknown>): Promise<T>;
+    getIssueDetails(ref: GitHubIssueRef, projectId?: string | number): Promise<RawIssueDetails>;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAE3D,OAAO,KAAK,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAElE,MAAM,WAAW,mBAAmB;IAClC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,uDAAuD;IACvD,MAAM,CAAC,EAAE,eAAe,CAAC;CAC1B;AAED,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA8B;gBAEzC,OAAO,GAAE,mBAAwB;IAM7C,QAAQ,IAAI,OAAO;IAInB,OAAO,CAAC,WAAW;IAMb,OAAO,CAAC,CAAC,GAAG,GAAG,EAAE,KAAK,EAAE,MAAM,EAAE,SAAS,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GAAG,OAAO,CAAC,CAAC,CAAC;IAwBpF,eAAe,CAAC,GAAG,EAAE,cAAc,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC;CAwHlG"}

package/dist/client.js

@@ -0,0 +1,141 @@
+import { messages } from './messages.js';
+export class GitHubProjectClient {
+    token;
+    apiUrl;
+    locale;
+    constructor(options = {}) {
+        this.token = options.token || process.env.GH_TOKEN || process.env.GITHUB_TOKEN || '';
+        this.apiUrl = options.apiUrl || 'https://api.github.com';
+        this.locale = options.locale;
+    }
+    hasToken() {
+        return Boolean(this.token && this.token.trim().length > 0);
+    }
+    assertToken() {
+        if (!this.hasToken()) {
+            throw new Error(messages.t(this.locale, 'tokenMissing'));
+        }
+    }
+    async graphql(query, variables = {}) {
+        this.assertToken();
+        const res = await fetch(`${this.apiUrl}/graphql`, {
+            method: 'POST',
+            headers: {
+                Authorization: `Bearer ${this.token}`,
+                'Content-Type': 'application/json',
+                'User-Agent': 'prumo-plugin-github-project',
+            },
+            body: JSON.stringify({ query, variables }),
+        });
+        if (!res.ok) {
+            throw new Error(`GitHub GraphQL HTTP ${res.status}: ${res.statusText}`);
+        }
+        const payload = (await res.json());
+        if (payload.errors && payload.errors.length > 0) {
+            throw new Error(`GitHub GraphQL error: ${payload.errors.map((e) => e.message).join('; ')}`);
+        }
+        return payload.data;
+    }
+    async getIssueDetails(ref, projectId) {
+        this.assertToken();
+        const query = `
+      query GetIssueDetails($owner: String!, $repo: String!, $number: Int!) {
+        repository(owner: $owner, name: $repo) {
+          issue(number: $number) {
+            number
+            title
+            body
+            state
+            assignees(first: 20) {
+              nodes {
+                login
+              }
+            }
+            comments(first: 100) {
+              nodes {
+                id
+                author {
+                  login
+                }
+                body
+                createdAt
+              }
+            }
+            projectItems(first: 10) {
+              nodes {
+                id
+                project {
+                  number
+                  title
+                }
+                fieldValues(first: 20) {
+                  nodes {
+                    ... on ProjectV2ItemFieldSingleSelectValue {
+                      name
+                    }
+                  }
+                }
+              }
+            }
+            subIssues(first: 50) {
+              nodes {
+                id
+                number
+                title
+                state
+              }
+            }
+          }
+        }
+      }
+    `;
+        try {
+            const data = await this.graphql(query, {
+                owner: ref.owner,
+                repo: ref.repo,
+                number: ref.number,
+            });
+            const issue = data.repository?.issue;
+            if (!issue) {
+                throw new Error(messages.t(this.locale, 'issueNotFound', { issue: `${ref.owner}/${ref.repo}#${ref.number}` }));
+            }
+            let projectStatus = null;
+            if (issue.projectItems?.nodes && issue.projectItems.nodes.length > 0) {
+                for (const item of issue.projectItems.nodes) {
+                    if (!projectId || String(item.project?.number) === String(projectId)) {
+                        const statusVal = item.fieldValues?.nodes?.find((f) => Boolean(f?.name));
+                        if (statusVal?.name) {
+                            projectStatus = statusVal.name;
+                            break;
+                        }
+                    }
+                }
+            }
+            return {
+                owner: ref.owner,
+                repo: ref.repo,
+                number: issue.number,
+                title: issue.title ?? '',
+                body: issue.body ?? '',
+                state: issue.state ?? 'OPEN',
+                assignees: (issue.assignees?.nodes ?? []).map((a) => a.login),
+                comments: (issue.comments?.nodes ?? []).map((c) => ({
+                    id: c.id,
+                    author: c.author?.login ?? 'ghost',
+                    body: c.body ?? '',
+                    createdAt: c.createdAt,
+                })),
+                subIssues: (issue.subIssues?.nodes ?? []).map((s) => ({
+                    id: s.id,
+                    number: s.number,
+                    title: s.title,
+                    state: s.state,
+                })),
+                projectStatus,
+            };
+        }
+        catch (err) {
+            throw new Error(messages.t(this.locale, 'loadFailed', { issue: `${ref.owner}/${ref.repo}#${ref.number}`, error: err.message }));
+        }
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export * from './types.js';
+export * from './client.js';
+export declare function activate(): void;
+declare const _default: {
+    activate: typeof activate;
+};
+export default _default;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAE5B,wBAAgB,QAAQ,IAAI,IAAI,CAE/B;;;;AAED,wBAEE"}

package/dist/index.js

@@ -0,0 +1,8 @@
+export * from './types.js';
+export * from './client.js';
+export function activate() {
+    // Fine client plugin — exposes raw GraphQL/REST queries
+}
+export default {
+    activate,
+};

package/dist/messages.d.ts

@@ -0,0 +1,3 @@
+/** Error messages. English is canonical; other locales fall back to it per key. */
+export declare const messages: import("@ihelpee/prumo/core").Translator<"tokenMissing" | "issueNotFound" | "loadFailed" | "invalidRef">;
+//# sourceMappingURL=messages.d.ts.map

package/dist/messages.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"messages.d.ts","sourceRoot":"","sources":["../src/messages.ts"],"names":[],"mappings":"AAEA,mFAAmF;AACnF,eAAO,MAAM,QAAQ,0GAcnB,CAAC"}

package/dist/messages.js

@@ -0,0 +1,16 @@
+import { defineMessages } from '@ihelpee/prumo/core';
+/** Error messages. English is canonical; other locales fall back to it per key. */
+export const messages = defineMessages({
+    en: {
+        tokenMissing: 'GH_TOKEN or GITHUB_TOKEN is not set. Set the environment variable, or use PIPELINE_FIXTURE=<path> to run offline.',
+        issueNotFound: 'Issue {issue} not found on GitHub',
+        loadFailed: 'Failed to load GitHub data for {issue}: {error}',
+        invalidRef: "Invalid issue reference: '{raw}'. Expected 'owner/repo#123' or a GitHub URL",
+    },
+    'pt-BR': {
+        tokenMissing: 'GH_TOKEN ou GITHUB_TOKEN ausente no ambiente. Defina a variável de ambiente ou utilize PIPELINE_FIXTURE=<path> para executar offline.',
+        issueNotFound: 'Issue {issue} não encontrada no GitHub',
+        loadFailed: 'Falha ao carregar dados do GitHub para {issue}: {error}',
+        invalidRef: "Referência de issue inválida: '{raw}'. Formato esperado: 'owner/repo#123' ou URL do GitHub",
+    },
+});

package/dist/types.d.ts

@@ -0,0 +1,39 @@
+import type { SupportedLocale } from '@ihelpee/prumo/core';
+export interface GitHubIssueRef {
+    owner: string;
+    repo: string;
+    number: number;
+}
+export declare function parseIssueRef(raw: string, locale?: SupportedLocale): GitHubIssueRef;
+export interface RawProjectItem {
+    id: string;
+    projectId?: string;
+    status: string | null;
+    title: string;
+    updatedAt?: string;
+}
+export interface RawIssueComment {
+    id: string;
+    author: string;
+    body: string;
+    createdAt: string;
+}
+export interface RawSubIssue {
+    id: string;
+    number: number;
+    title: string;
+    state: string;
+}
+export interface RawIssueDetails {
+    owner: string;
+    repo: string;
+    number: number;
+    title: string;
+    body: string;
+    state: string;
+    assignees: string[];
+    comments: RawIssueComment[];
+    subIssues: RawSubIssue[];
+    projectStatus?: string | null;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAG3D,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,eAAe,GAAG,cAAc,CAqBnF;AAED,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,QAAQ,EAAE,eAAe,EAAE,CAAC;IAC5B,SAAS,EAAE,WAAW,EAAE,CAAC;IACzB,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC/B"}

package/dist/types.js

@@ -0,0 +1,21 @@
+import { messages } from './messages.js';
+export function parseIssueRef(raw, locale) {
+    const trimmed = raw.trim();
+    const match = trimmed.match(/^([^/]+)\/([^#]+)#(\d+)$/);
+    if (match) {
+        return {
+            owner: match[1],
+            repo: match[2],
+            number: Number.parseInt(match[3], 10),
+        };
+    }
+    const urlMatch = trimmed.match(/github\.com\/([^/]+)\/([^/]+)\/issues\/(\d+)/);
+    if (urlMatch) {
+        return {
+            owner: urlMatch[1],
+            repo: urlMatch[2],
+            number: Number.parseInt(urlMatch[3], 10),
+        };
+    }
+    throw new Error(messages.t(locale, 'invalidRef', { raw }));
+}

package/package.json

@@ -1,6 +1,50 @@
 {
   "name": "@ihelpee/prumo-plugin-github-project",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.18.2",
+  "type": "module",
+  "description": "Thin GitHub Project v2 and Issue client: raw GraphQL queries for items, status, comments, sub-issues.",
+  "author": "Alex Gotardi <alexgotardi@gmail.com> (https://github.com/alexgotardi)",
+  "license": "SEE LICENSE IN LICENSE",
+  "homepage": "https://github.com/ihelpee/prumo#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ihelpee/prumo.git"
+  },
+  "bugs": {
+    "url": "https://github.com/ihelpee/prumo/issues"
+  },
+  "maturity": "experimental",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "package.json",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "prumo": ">=0.12.0",
+  "contributes": {
+    "activate": "./dist/index.js",
+    "description": "Raw GitHub Project and Issue queries without domain business rules."
+  },
+  "peerDependencies": {
+    "@ihelpee/prumo": "^0.18.2"
+  },
+  "devDependencies": {
+    "@ihelpee/prumo": "0.18.2",
+    "@ihelpee/prumo-plugin-typescript": "0.18.2"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "verify": "prumo gate --root ."
+  }
 }