@papillon6814/pi-gh 0.0.0-stage → 0.2.0

package/dist/src/core/types.d.ts

@@ -0,0 +1,95 @@
+export type Profile = {
+    model: string;
+    thinking: string;
+    tier: 'basic' | 'upper';
+};
+export type AgentAssignment = {
+    model: string;
+    thinking: string;
+    reason: string;
+    upperTierApproval?: string;
+};
+export type Criterion = {
+    id: string;
+    requirement: string;
+    verification: string;
+    expectedResult: string;
+};
+export type FieldDefinition = {
+    id: string;
+    label: string;
+    type: 'string' | 'text' | 'string-list' | 'criteria';
+    required: boolean;
+    description?: string;
+    options?: string[];
+    minLength?: number;
+    maxLength?: number;
+    minItems?: number;
+    maxItems?: number;
+};
+export type TemplateDefinition = {
+    version: 1;
+    id: string;
+    name: string;
+    description: string;
+    kind: 'parent' | 'task';
+    fields: FieldDefinition[];
+    agents: string[];
+    modelPolicy: string;
+};
+export type ModelPolicy = {
+    version: 1;
+    agents: Record<string, Profile[]>;
+};
+export type Draft = {
+    version: 1;
+    template: string;
+    repo: string;
+    title: string;
+    labels?: string[];
+    parentIssue?: number;
+    fields: Record<string, string | string[] | Criterion[]>;
+    agents: Record<string, AgentAssignment>;
+};
+export type CapturedInput = {
+    path: string;
+    bytes: Buffer;
+};
+export type TemplateBundle = {
+    template: TemplateDefinition;
+    policy: ModelPolicy;
+    inputs: CapturedInput[];
+};
+export type ValidationProblem = {
+    code: string;
+    path: string;
+    message: string;
+};
+export type ValidatedIssue = {
+    draft: Draft;
+    bundle: TemplateBundle;
+    draftInput: CapturedInput;
+};
+export type Preview = {
+    repo: string;
+    title: string;
+    body: string;
+    agents: Draft['agents'];
+    labels?: string[];
+    digest: string;
+    sensitive: boolean;
+};
+export type SubmitOutcome = {
+    status: 'created';
+    url: string;
+} | {
+    status: 'rejected';
+    problems: ValidationProblem[];
+} | {
+    status: 'not-started';
+    message: string;
+} | {
+    status: 'unknown';
+    message: string;
+    candidateUrl?: string;
+};

package/dist/src/core/types.js

@@ -0,0 +1 @@
+export {};

package/dist/src/github-api.d.ts

@@ -0,0 +1,28 @@
+import { type GhOptions } from './core/gh-process.js';
+export type JsonObject = Record<string, unknown>;
+export declare function object(value: unknown): JsonObject;
+export declare function array(value: unknown): unknown[];
+export declare const projectFieldsQuery = "query($projectId:ID!,$cursor:String){node(id:$projectId){__typename ... on ProjectV2{id title fields(first:100,after:$cursor){nodes{__typename ... on ProjectV2Field{id name dataType} ... on ProjectV2SingleSelectField{id name dataType options{id name}} ... on ProjectV2IterationField{id name dataType}} pageInfo{hasNextPage endCursor}}}}}";
+export declare const projectItemsQuery = "query($projectId:ID!,$cursor:String){node(id:$projectId){__typename ... on ProjectV2{id title items(first:100,after:$cursor){nodes{id content{__typename ... on Issue{id number repository{nameWithOwner}}} fieldValues(first:100){nodes{__typename ... on ProjectV2ItemFieldTextValue{text field{... on ProjectV2Field{id}}} ... on ProjectV2ItemFieldNumberValue{number field{... on ProjectV2Field{id}}} ... on ProjectV2ItemFieldDateValue{date field{... on ProjectV2Field{id}}} ... on ProjectV2ItemFieldSingleSelectValue{optionId field{... on ProjectV2SingleSelectField{id}}}} pageInfo{hasNextPage endCursor}}} pageInfo{hasNextPage endCursor}}}}}";
+export declare const addProjectIssueMutation = "mutation($projectId:ID!,$contentId:ID!){addProjectV2ItemById(input:{projectId:$projectId,contentId:$contentId}){item{id}}}";
+export declare const updateProjectFieldMutation = "mutation($projectId:ID!,$itemId:ID!,$fieldId:ID!,$value:ProjectV2FieldValue!){updateProjectV2ItemFieldValue(input:{projectId:$projectId,itemId:$itemId,fieldId:$fieldId,value:$value}){projectV2Item{id}}}";
+export declare class GithubApi {
+    private options;
+    private bytes;
+    constructor(options: GhOptions);
+    private args;
+    private decode;
+    rest(endpoint: string): Promise<unknown>;
+    restList(endpoint: string): Promise<unknown[]>;
+    issue(repo: string, number: number): Promise<JsonObject>;
+    graphql(query: string, variables: JsonObject): Promise<JsonObject>;
+    project(projectId: string, kind: 'fields' | 'items'): Promise<JsonObject>;
+    mutateRest(endpoint: string, method: 'POST' | 'PATCH', body: JsonObject): Promise<{
+        status: 'ok' | 'not-started' | 'unknown';
+        data?: unknown;
+    }>;
+    mutateGraphql(query: string, variables: JsonObject): Promise<{
+        status: 'ok' | 'not-started' | 'unknown';
+        data?: unknown;
+    }>;
+}

package/dist/src/github-api.js

@@ -0,0 +1,100 @@
+import { runGh } from './core/gh-process.js';
+import { fail, parseJson, record } from './core/data.js';
+export function object(value) { if (!record(value))
+    fail('GITHUB_RESPONSE', '', 'Expected a GitHub object.'); return value; }
+export function array(value) { if (!Array.isArray(value))
+    fail('GITHUB_RESPONSE', '', 'Expected a GitHub array.'); return value; }
+export const projectFieldsQuery = `query($projectId:ID!,$cursor:String){node(id:$projectId){__typename ... on ProjectV2{id title fields(first:100,after:$cursor){nodes{__typename ... on ProjectV2Field{id name dataType} ... on ProjectV2SingleSelectField{id name dataType options{id name}} ... on ProjectV2IterationField{id name dataType}} pageInfo{hasNextPage endCursor}}}}}`;
+export const projectItemsQuery = `query($projectId:ID!,$cursor:String){node(id:$projectId){__typename ... on ProjectV2{id title items(first:100,after:$cursor){nodes{id content{__typename ... on Issue{id number repository{nameWithOwner}}} fieldValues(first:100){nodes{__typename ... on ProjectV2ItemFieldTextValue{text field{... on ProjectV2Field{id}}} ... on ProjectV2ItemFieldNumberValue{number field{... on ProjectV2Field{id}}} ... on ProjectV2ItemFieldDateValue{date field{... on ProjectV2Field{id}}} ... on ProjectV2ItemFieldSingleSelectValue{optionId field{... on ProjectV2SingleSelectField{id}}}} pageInfo{hasNextPage endCursor}}} pageInfo{hasNextPage endCursor}}}}}`;
+export const addProjectIssueMutation = `mutation($projectId:ID!,$contentId:ID!){addProjectV2ItemById(input:{projectId:$projectId,contentId:$contentId}){item{id}}}`;
+export const updateProjectFieldMutation = `mutation($projectId:ID!,$itemId:ID!,$fieldId:ID!,$value:ProjectV2FieldValue!){updateProjectV2ItemFieldValue(input:{projectId:$projectId,itemId:$itemId,fieldId:$fieldId,value:$value}){projectV2Item{id}}}`;
+export class GithubApi {
+    options;
+    bytes = 0;
+    constructor(options) {
+        this.options = options;
+    }
+    args(endpoint, method) { return ['api', '--hostname', 'github.com', '--method', method, '-H', 'Accept: application/vnd.github+json', '-H', 'X-GitHub-Api-Version: 2026-03-10', endpoint]; }
+    decode(stdout) { this.bytes += Buffer.byteLength(stdout); if (this.bytes > 1048576)
+        fail('GITHUB_LIMIT', '', 'Combined response limit exceeded.'); return parseJson(Buffer.from(stdout)); }
+    async rest(endpoint) { const r = await runGh(this.args(endpoint, 'GET'), '', this.options); if (r.status !== 'ok')
+        fail('GITHUB_READ', '', 'GitHub read failed.'); return this.decode(r.stdout); }
+    async restList(endpoint) {
+        const all = [];
+        for (let page = 1; page <= 100; page++) {
+            const items = array(await this.rest(endpoint + (endpoint.includes('?') ? '&' : '?') + 'per_page=100&page=' + page));
+            all.push(...items);
+            if (items.length < 100)
+                return all;
+        }
+        fail('GITHUB_LIMIT', '', 'Pagination limit exceeded.');
+    }
+    async issue(repo, number) {
+        const v = object(await this.rest('repos/' + repo + '/issues/' + number));
+        if (v.pull_request !== undefined || v.number !== number || !Number.isSafeInteger(v.id) || v.id < 1 || typeof v.node_id !== 'string' || !/^I_[A-Za-z0-9_-]+$/.test(v.node_id) || typeof v.html_url !== 'string' || v.html_url.toLowerCase() !== ('https://github.com/' + repo + '/issues/' + number).toLowerCase())
+            fail('GITHUB_IDENTITY', '', 'Expected the exact GitHub Issue, not a PR.');
+        return v;
+    }
+    async graphql(query, variables) {
+        const r = await runGh([...this.args('graphql', 'POST'), '--input', '-'], JSON.stringify({ query, variables }), this.options);
+        if (r.status !== 'ok')
+            fail('GITHUB_READ', '', 'GraphQL read failed.');
+        const v = object(this.decode(r.stdout));
+        if (v.errors !== undefined)
+            fail('GITHUB_READ', '', 'GraphQL returned errors.');
+        return object(v.data);
+    }
+    async project(projectId, kind) {
+        const nodes = [];
+        const cursors = new Set();
+        let cursor = null, title;
+        for (let page = 0; page < 100; page++) {
+            const response = await this.graphql(kind === 'fields' ? projectFieldsQuery : projectItemsQuery, { projectId, cursor });
+            const project = object(response.node);
+            if (project.__typename !== 'ProjectV2' || project.id !== projectId)
+                fail('GITHUB_IDENTITY', '', 'Expected the exact Projects V2 node.');
+            title = project.title;
+            const connection = object(project[kind]), items = array(connection.nodes);
+            nodes.push(...items);
+            if (kind === 'items')
+                for (const raw of items) {
+                    const item = object(raw), values = object(item.fieldValues);
+                    if (values.pageInfo !== undefined && object(values.pageInfo).hasNextPage !== false)
+                        fail('GITHUB_LIMIT', '', 'Item field values were truncated.');
+                }
+            const info = object(connection.pageInfo);
+            if (info.hasNextPage === false)
+                return { id: projectId, title, [kind]: nodes };
+            if (info.hasNextPage !== true || typeof info.endCursor !== 'string' || !info.endCursor || cursors.has(info.endCursor))
+                fail('GITHUB_LIMIT', '', 'Invalid or repeated pagination cursor.');
+            cursor = info.endCursor;
+            cursors.add(cursor);
+        }
+        fail('GITHUB_LIMIT', '', 'Pagination limit exceeded.');
+    }
+    async mutateRest(endpoint, method, body) {
+        const r = await runGh([...this.args(endpoint, method), '--input', '-'], JSON.stringify(body), this.options);
+        if (r.status !== 'ok')
+            return { status: r.status };
+        try {
+            return { status: 'ok', data: this.decode(r.stdout) };
+        }
+        catch {
+            return { status: 'unknown' };
+        }
+    }
+    async mutateGraphql(query, variables) {
+        const r = await runGh([...this.args('graphql', 'POST'), '--input', '-'], JSON.stringify({ query, variables }), this.options);
+        if (r.status !== 'ok')
+            return { status: r.status };
+        try {
+            const v = object(this.decode(r.stdout));
+            if (v.errors !== undefined)
+                return { status: 'unknown' };
+            return { status: 'ok', data: object(v.data) };
+        }
+        catch {
+            return { status: 'unknown' };
+        }
+    }
+}

package/dist/src/operation-input.d.ts

@@ -0,0 +1,35 @@
+import type { CapturedInput } from './core/types.js';
+export declare const githubReads: readonly ["gh_issue_get", "gh_issue_list", "gh_subissues_list", "gh_dependencies_list", "gh_project_get", "gh_project_items"];
+export declare const githubWrites: readonly ["gh_issue_edit", "gh_issue_close", "gh_subissue_add", "gh_dependency_add", "gh_project_add_issue", "gh_project_field_update"];
+export type GithubOperation = typeof githubReads[number] | typeof githubWrites[number];
+export type GithubArgs = {
+    repo?: string;
+    issue?: number;
+    state?: 'open' | 'closed' | 'all';
+    projectId?: string;
+    changePath?: string;
+};
+export type FieldValue = {
+    text?: string;
+    number?: number;
+    date?: string;
+    singleSelectOptionId?: string;
+};
+export type Change = {
+    version: 1;
+    repo: string;
+    operation: string;
+    issue?: number;
+    title?: string;
+    body?: string;
+    reason?: 'completed' | 'not_planned';
+    relatedIssue?: number;
+    projectId?: string;
+    itemId?: string;
+    fieldId?: string;
+    value?: FieldValue;
+};
+export declare function positive(value: unknown): asserts value is number;
+export declare function nodeId(value: unknown, prefix: string): asserts value is string;
+export declare function validateGithubArgs(name: GithubOperation, args: unknown): asserts args is GithubArgs;
+export declare function validateChange(name: GithubOperation, input: CapturedInput): Change;

package/dist/src/operation-input.js

@@ -0,0 +1,88 @@
+import { fail, keys, record, parseJson } from './core/data.js';
+import { validateRepo } from './core/labels-input.js';
+export const githubReads = ['gh_issue_get', 'gh_issue_list', 'gh_subissues_list', 'gh_dependencies_list', 'gh_project_get', 'gh_project_items'];
+export const githubWrites = ['gh_issue_edit', 'gh_issue_close', 'gh_subissue_add', 'gh_dependency_add', 'gh_project_add_issue', 'gh_project_field_update'];
+export function positive(value) { if (!Number.isSafeInteger(value) || value < 1)
+    fail('ARGUMENT', '', 'Expected a positive Issue number.'); }
+export function nodeId(value, prefix) { if (typeof value !== 'string' || !new RegExp('^' + prefix + '[A-Za-z0-9_-]{1,200}$').test(value))
+    fail('ARGUMENT', '', 'Invalid GitHub node ID.'); }
+export function validateGithubArgs(name, args) {
+    if (!record(args))
+        fail('ARGUMENT', '', 'Expected an argument object.');
+    if (githubWrites.includes(name)) {
+        keys(args, ['changePath'], 'arguments');
+        if (typeof args.changePath !== 'string' || !args.changePath.trim())
+            fail('ARGUMENT', '', 'Expected changePath.');
+        return;
+    }
+    if (name.startsWith('gh_project_')) {
+        keys(args, ['projectId'], 'arguments');
+        nodeId(args.projectId, 'PVT_');
+        return;
+    }
+    keys(args, name === 'gh_issue_list' ? ['repo', 'state'] : ['repo', 'issue'], 'arguments');
+    validateRepo(args.repo);
+    if (name === 'gh_issue_list') {
+        if (args.state !== undefined && !['open', 'closed', 'all'].includes(args.state))
+            fail('ARGUMENT', '', 'Unknown Issue state.');
+    }
+    else
+        positive(args.issue);
+}
+const changes = {
+    'issue-edit': { name: 'gh_issue_edit', keys: ['issue', 'title', 'body'] },
+    'issue-close': { name: 'gh_issue_close', keys: ['issue', 'reason'] },
+    'subissue-add': { name: 'gh_subissue_add', keys: ['issue', 'relatedIssue'] },
+    'dependency-add': { name: 'gh_dependency_add', keys: ['issue', 'relatedIssue'] },
+    'project-add-issue': { name: 'gh_project_add_issue', keys: ['issue', 'projectId'] },
+    'project-field-update': { name: 'gh_project_field_update', keys: ['projectId', 'itemId', 'fieldId', 'value'] }
+};
+export function validateChange(name, input) {
+    const raw = parseJson(input.bytes);
+    if (!record(raw) || raw.version !== 1 || typeof raw.operation !== 'string')
+        fail('ARGUMENT', '', 'Expected version 1 change.');
+    const definition = changes[raw.operation];
+    if (!definition || definition.name !== name)
+        fail('ARGUMENT', '', 'Change does not match the tool operation.');
+    keys(raw, ['version', 'repo', 'operation', ...definition.keys], 'change');
+    validateRepo(raw.repo);
+    if (raw.operation !== 'project-field-update')
+        positive(raw.issue);
+    if (raw.operation === 'issue-edit') {
+        if (raw.title === undefined && raw.body === undefined)
+            fail('ARGUMENT', '', 'No edit requested.');
+        if (raw.title !== undefined && (typeof raw.title !== 'string' || !raw.title.trim() || raw.title.length > 256 || /[\u0000-\u001f\u007f]/.test(raw.title)))
+            fail('ARGUMENT', '', 'Invalid title.');
+        if (raw.body !== undefined && (typeof raw.body !== 'string' || raw.body.length > 65536))
+            fail('ARGUMENT', '', 'Invalid body.');
+    }
+    if (raw.operation === 'issue-close' && raw.reason !== undefined && !['completed', 'not_planned'].includes(raw.reason))
+        fail('ARGUMENT', '', 'Invalid close reason.');
+    if (raw.operation === 'subissue-add' || raw.operation === 'dependency-add') {
+        positive(raw.relatedIssue);
+        if (raw.relatedIssue === raw.issue)
+            fail('ARGUMENT', '', 'Self-links are forbidden.');
+    }
+    if (raw.operation.startsWith('project-'))
+        nodeId(raw.projectId, 'PVT_');
+    if (raw.operation === 'project-field-update') {
+        nodeId(raw.itemId, 'PVTI_');
+        if (typeof raw.fieldId !== 'string' || !/^PVT(F|SSF)_[A-Za-z0-9_-]{1,200}$/.test(raw.fieldId))
+            fail('ARGUMENT', '', 'Invalid field ID.');
+        if (!record(raw.value) || Object.keys(raw.value).length !== 1)
+            fail('ARGUMENT', '', 'Expected one typed field value.');
+        keys(raw.value, ['text', 'number', 'date', 'singleSelectOptionId'], 'field value');
+        const v = raw.value;
+        if ('text' in v && (typeof v.text !== 'string' || v.text.length > 20000))
+            fail('ARGUMENT', '', 'Invalid text.');
+        if ('number' in v && (typeof v.number !== 'number' || !Number.isFinite(v.number)))
+            fail('ARGUMENT', '', 'Invalid number.');
+        if ('date' in v) {
+            if (typeof v.date !== 'string' || !/^\d{4}-\d{2}-\d{2}$/.test(v.date) || !Number.isFinite(Date.parse(v.date)) || new Date(v.date).toISOString().slice(0, 10) !== v.date)
+                fail('ARGUMENT', '', 'Invalid ISO date.');
+        }
+        if ('singleSelectOptionId' in v && (typeof v.singleSelectOptionId !== 'string' || !/^[A-Za-z0-9_-]{1,200}$/.test(v.singleSelectOptionId)))
+            fail('ARGUMENT', '', 'Invalid option ID.');
+    }
+    return raw;
+}

package/dist/src/operations.d.ts

@@ -0,0 +1,3 @@
+import { type GithubOperation, type GithubArgs } from './operation-input.js';
+import type { OperationContext, OperationResult } from './service-types.js';
+export declare function runGithubOperation(name: GithubOperation, args: GithubArgs, ctx: OperationContext): Promise<OperationResult>;

package/dist/src/operations.js

@@ -0,0 +1,137 @@
+import { createHash } from 'node:crypto';
+import { resolve } from 'node:path';
+import { loadDraft } from './core/draft.js';
+import { maskDecodedSecrets } from './core/secrets.js';
+import { fail } from './core/data.js';
+import { safeResult, errorResult, rejected } from './result.js';
+import { authorize, recheckAuthority } from './service.js';
+import { GithubApi, object, array, addProjectIssueMutation, updateProjectFieldMutation } from './github-api.js';
+import { githubReads, githubWrites, validateGithubArgs, validateChange } from './operation-input.js';
+function active(ctx) { return !ctx.signal.aborted && ctx.isCurrent(); }
+function requireActive(ctx) { if (!active(ctx))
+    fail('STALE_OPERATION', '', 'Session changed or operation was cancelled.'); }
+function digest(bytes, before) { return createHash('sha256').update(bytes).update(JSON.stringify(before)).digest('hex'); }
+function fieldValue(item, fieldId) {
+    return array(object(item.fieldValues).nodes).map(object).find(v => v.field !== undefined && object(v.field).id === fieldId);
+}
+function equalField(item, c) { const value = fieldValue(item, c.fieldId); if (!value)
+    return false; const [key, wanted] = Object.entries(c.value)[0]; return value[key === 'singleSelectOptionId' ? 'optionId' : key] === wanted; }
+function verifyItem(item, repo) { const content = object(item.content); if (content.__typename !== 'Issue' || object(content.repository).nameWithOwner?.toString().toLowerCase() !== repo.toLowerCase())
+    fail('GITHUB_IDENTITY', '', 'Project item does not belong to the specified repository Issue.'); }
+async function snapshot(api, c) {
+    const s = { noop: false };
+    if (c.issue !== undefined)
+        s.issue = await api.issue(c.repo, c.issue);
+    if (c.operation === 'issue-edit') {
+        s.noop = (c.title === undefined || c.title === s.issue.title) && (c.body === undefined || c.body === s.issue.body);
+        return s;
+    }
+    if (c.operation === 'issue-close') {
+        s.noop = s.issue.state === 'closed' && s.issue.state_reason === (c.reason ?? 'completed');
+        return s;
+    }
+    if (c.operation === 'subissue-add' || c.operation === 'dependency-add') {
+        s.related = await api.issue(c.repo, c.relatedIssue);
+        const suffix = c.operation === 'subissue-add' ? 'sub_issues' : 'dependencies/blocked_by';
+        s.relations = await api.restList('repos/' + c.repo + '/issues/' + c.issue + '/' + suffix);
+        s.noop = s.relations.some(v => object(v).id === s.related.id);
+        return s;
+    }
+    const fields = await api.project(c.projectId, 'fields'), items = await api.project(c.projectId, 'items');
+    s.project = { id: fields.id };
+    if (c.operation === 'project-add-issue') {
+        s.item = array(items.items).map(object).find(item => item.content !== null && object(item.content).id === s.issue.node_id);
+        if (s.item) {
+            verifyItem(s.item, c.repo);
+            s.noop = true;
+        }
+        return s;
+    }
+    s.item = array(items.items).map(object).find(item => item.id === c.itemId);
+    if (!s.item)
+        fail('GITHUB_IDENTITY', '', 'Item is not in the specified project.');
+    verifyItem(s.item, c.repo);
+    s.field = array(fields.fields).map(object).find(field => field.id === c.fieldId);
+    if (!s.field)
+        fail('GITHUB_IDENTITY', '', 'Field is not in the specified project.');
+    const key = Object.keys(c.value)[0], types = { text: 'TEXT', number: 'NUMBER', date: 'DATE', singleSelectOptionId: 'SINGLE_SELECT' };
+    if (s.field.dataType !== types[key])
+        fail('ARGUMENT', '', 'Field type does not match the supplied value.');
+    if (key === 'singleSelectOptionId' && !array(s.field.options).some(v => object(v).id === c.value.singleSelectOptionId))
+        fail('ARGUMENT', '', 'Option is not in the specified field.');
+    s.noop = equalField(s.item, c);
+    const current = fieldValue(s.item, c.fieldId);
+    s.item = { id: s.item.id, content: s.item.content, fieldValues: { nodes: current ? [current] : [] } };
+    s.field = { id: s.field.id, name: s.field.name, dataType: s.field.dataType, ...(key === 'singleSelectOptionId' ? { options: array(s.field.options).filter(v => object(v).id === c.value.singleSelectOptionId) } : {}) };
+    return s;
+}
+async function apply(api, c, before) {
+    const endpoint = 'repos/' + c.repo + '/issues/' + c.issue;
+    switch (c.operation) {
+        case 'issue-edit': return api.mutateRest(endpoint, 'PATCH', { ...(c.title !== undefined ? { title: c.title } : {}), ...(c.body !== undefined ? { body: c.body } : {}) });
+        case 'issue-close': return api.mutateRest(endpoint, 'PATCH', { state: 'closed', state_reason: c.reason ?? 'completed' });
+        case 'subissue-add': return api.mutateRest(endpoint + '/sub_issues', 'POST', { sub_issue_id: before.related.id });
+        case 'dependency-add': return api.mutateRest(endpoint + '/dependencies/blocked_by', 'POST', { issue_id: before.related.id });
+        case 'project-add-issue': return api.mutateGraphql(addProjectIssueMutation, { projectId: c.projectId, contentId: before.issue.node_id });
+        case 'project-field-update': return api.mutateGraphql(updateProjectFieldMutation, { projectId: c.projectId, itemId: c.itemId, fieldId: c.fieldId, value: c.value });
+        default: fail('ARGUMENT', '', 'Unknown change.');
+    }
+}
+export async function runGithubOperation(name, args, ctx) {
+    let mutationStarted = false;
+    try {
+        if (![...githubReads, ...githubWrites].includes(name))
+            return rejected('ARGUMENT', 'Unknown operation.');
+        validateGithubArgs(name, args);
+        requireActive(ctx);
+        const write = githubWrites.includes(name);
+        if (write && !ctx.interactive && !ctx.permissions)
+            return rejected('APPROVAL_UI_REQUIRED', 'External changes require local approval or an exact permission grant.');
+        let machineAuthority = false;
+        const api = new GithubApi({ signal: ctx.signal, beforeStart: () => active(ctx), beforeStartAsync: async () => !machineAuthority || !!ctx.permissions && await ctx.permissions.isCurrent() });
+        if (!write) {
+            let data;
+            if (name === 'gh_project_get' || name === 'gh_project_items')
+                data = await api.project(args.projectId, name === 'gh_project_get' ? 'fields' : 'items');
+            else if (name === 'gh_issue_list')
+                data = (await api.restList('repos/' + args.repo + '/issues?state=' + (args.state ?? 'all'))).filter(v => object(v).pull_request === undefined);
+            else {
+                const issue = await api.issue(args.repo, args.issue);
+                data = name === 'gh_issue_get' ? issue : await api.restList('repos/' + args.repo + '/issues/' + args.issue + '/' + (name === 'gh_subissues_list' ? 'sub_issues' : 'dependencies/blocked_by'));
+            }
+            requireActive(ctx);
+            return safeResult({ status: 'read', data });
+        }
+        const path = resolve(ctx.cwd, args.changePath), input = await loadDraft(path), change = validateChange(name, input);
+        if (maskDecodedSecrets(change).sensitive)
+            return rejected('SENSITIVE', 'Remove secret candidates before applying.');
+        if (!ctx.interactive && !ctx.permissions?.allows(name, change.repo, change.projectId))
+            return rejected('PERMISSION_DENIED', 'No matching operation/repository/project/actor permission.');
+        const before = await snapshot(api, change);
+        requireActive(ctx);
+        const preview = { operation: name, change, before };
+        if (maskDecodedSecrets(preview).sensitive)
+            return rejected('SENSITIVE', 'Remove secret candidates before applying.');
+        if (before.noop)
+            return safeResult({ status: 'noop', data: { repo: change.repo, operation: name } });
+        const hash = digest(input.bytes, before), machine = await authorize({ operation: name, text: JSON.stringify(preview, null, 2), digest: hash }, ctx, change.repo, name, change.projectId);
+        machineAuthority = machine;
+        const latest = await loadDraft(path), nextChange = validateChange(name, latest), next = await snapshot(api, nextChange);
+        requireActive(ctx);
+        if (digest(latest.bytes, next) !== hash || maskDecodedSecrets({ change: nextChange, before: next }).sensitive)
+            return rejected('APPROVAL_MISMATCH', 'Input or remote state changed; preview again.');
+        await recheckAuthority(ctx, machine);
+        mutationStarted = true;
+        const result = await apply(api, change, before);
+        if (result.status !== 'ok')
+            return safeResult({ status: result.status, message: result.status === 'unknown' ? 'Change outcome is uncertain; inspect GitHub before retrying.' : 'Change did not start.' });
+        const verified = await snapshot(api, change);
+        requireActive(ctx);
+        if (!verified.noop)
+            return safeResult({ status: 'unknown', message: 'Write returned, but the requested state could not be verified. Inspect GitHub before retrying.' });
+        return safeResult({ status: 'applied', data: { repo: change.repo, operation: name, ...(change.projectId ? { projectId: change.projectId } : {}), ...(verified.issue ? { issue: verified.issue } : {}), ...(verified.item ? { itemId: verified.item.id } : {}) } });
+    }
+    catch (error) {
+        return mutationStarted ? safeResult({ status: 'unknown', message: 'Change or its verification was interrupted; inspect GitHub before retrying.' }) : errorResult(error);
+    }
+}

package/dist/src/paths.d.ts

@@ -0,0 +1,4 @@
+import type { Operation, IssueArgs, FormArgs, OperationContext } from './service-types.js';
+export declare function validateArguments(operation: Operation, args: unknown): void;
+export declare function templatePath(args: IssueArgs | FormArgs, ctx: OperationContext): string;
+export declare function inputPath(path: string, ctx: OperationContext): string;

package/dist/src/paths.js

@@ -0,0 +1,21 @@
+import { resolve, join } from 'node:path';
+import { fail, record } from './core/data.js';
+export function validateArguments(operation, args) {
+    if (!record(args))
+        fail('ARGUMENT', '', 'Arguments must be an object.');
+    const label = operation.startsWith('gh_labels_'), form = operation === 'gh_issue_form';
+    const allowed = label ? ['changePath'] : form ? ['template', 'templatePath'] : ['draftPath', 'template', 'templatePath'];
+    if (Object.keys(args).some(key => !allowed.includes(key)))
+        fail('ARGUMENT', '', 'Unknown argument.');
+    for (const key of [label ? 'changePath' : form ? '' : 'draftPath', 'templatePath'])
+        if (key && args[key] !== undefined && (typeof args[key] !== 'string' || !args[key].trim()))
+            fail('ARGUMENT', key, 'A non-empty path is required.');
+    if (!form && typeof args[label ? 'changePath' : 'draftPath'] !== 'string')
+        fail('ARGUMENT', '', 'Input path is required.');
+    if (args.template !== undefined && !['parent', 'task'].includes(args.template))
+        fail('ARGUMENT', 'template', 'Unknown standard template.');
+    if (args.template !== undefined && args.templatePath !== undefined)
+        fail('ARGUMENT', 'template', 'Choose standard or custom template, not both.');
+}
+export function templatePath(args, ctx) { return args.templatePath ? resolve(ctx.cwd, args.templatePath) : join(ctx.packageRoot, 'templates', (args.template ?? 'task') + '.yml'); }
+export function inputPath(path, ctx) { return resolve(ctx.cwd, path); }

package/dist/src/permissions.d.ts

@@ -0,0 +1,10 @@
+export type PermissionLease = {
+    allows: (operation: string, repo: string, projectId?: string) => boolean;
+    isCurrent: () => Promise<boolean>;
+};
+export type Actor = {
+    child: boolean;
+    headless: boolean;
+};
+export declare function permissionPath(): string;
+export declare function loadPermissions(path: string, actor: Actor): Promise<PermissionLease | undefined>;

package/dist/src/permissions.js

@@ -0,0 +1,100 @@
+import { constants } from 'node:fs';
+import { open, lstat } from 'node:fs/promises';
+import { resolve, dirname, join } from 'node:path';
+import { homedir } from 'node:os';
+import { createHash } from 'node:crypto';
+import { fail, keys, record, parseJson } from './core/data.js';
+import { validateRepo } from './core/labels-input.js';
+const allowed = new Set(['gh_issue_submit', 'gh_label_create', 'gh_label_edit', 'gh_issue_labels', 'gh_issue_edit', 'gh_issue_close', 'gh_subissue_add', 'gh_dependency_add', 'gh_project_add_issue', 'gh_project_field_update']);
+export function permissionPath() { return join(homedir(), '.pi', 'agent', 'pi-gh-permissions.json'); }
+async function capture(path) {
+    const absolute = resolve(path);
+    let parent = dirname(absolute);
+    try {
+        const named = await lstat(absolute);
+        if (!named.isFile() || named.size > 65536 || (named.mode & 0o077) !== 0 || (process.getuid && named.uid !== process.getuid()))
+            fail('PERMISSION_FILE', '', 'Use an owner-only regular permission file.');
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return undefined;
+        throw error;
+    }
+    while (true) {
+        const s = await lstat(parent);
+        if (!s.isDirectory() || s.isSymbolicLink())
+            fail('PERMISSION_FILE', '', 'Permission parents must be real directories.');
+        const next = dirname(parent);
+        if (next === parent)
+            break;
+        parent = next;
+    }
+    let handle;
+    try {
+        handle = await open(absolute, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return undefined;
+        throw error;
+    }
+    try {
+        const s = await handle.stat();
+        if (!s.isFile() || s.size > 65536 || (s.mode & 0o077) !== 0 || (process.getuid && s.uid !== process.getuid()))
+            fail('PERMISSION_FILE', '', 'Use an owner-only regular permission file.');
+        const buffer = Buffer.alloc(65537);
+        let used = 0;
+        while (used < buffer.length) {
+            const read = await handle.read(buffer, used, buffer.length - used, used);
+            if (read.bytesRead === 0)
+                break;
+            used += read.bytesRead;
+        }
+        if (used > 65536)
+            fail('PERMISSION_FILE', '', 'Permission file exceeds limit.');
+        const bytes = buffer.subarray(0, used), after = await handle.stat(), named = await lstat(absolute);
+        if (named.isSymbolicLink() || s.ino !== named.ino || s.dev !== named.dev || s.size !== after.size || s.size !== used || s.mode !== after.mode || s.uid !== after.uid || s.mode !== named.mode || s.mtimeMs !== after.mtimeMs)
+            fail('PERMISSION_FILE', '', 'Permission file changed while reading.');
+        return JSON.stringify({ inode: s.ino, device: s.dev, mode: s.mode, bytes: bytes.toString('base64') });
+    }
+    finally {
+        await handle.close();
+    }
+}
+export async function loadPermissions(path, actor) {
+    const captured = await capture(path);
+    if (captured === undefined)
+        return undefined;
+    const encoded = JSON.parse(captured);
+    const raw = parseJson(Buffer.from(encoded.bytes, 'base64'));
+    if (!record(raw))
+        fail('PERMISSION_FORMAT', '', 'Expected permission object.');
+    keys(raw, ['version', 'grants'], 'permissions');
+    if (raw.version !== 1 || !Array.isArray(raw.grants) || raw.grants.length > 100)
+        fail('PERMISSION_FORMAT', '', 'Expected version 1 and at most 100 grants.');
+    const grants = raw.grants.map(value => {
+        if (!record(value))
+            fail('PERMISSION_FORMAT', '', 'Expected grant object.');
+        keys(value, ['repo', 'operations', 'allowChild', 'allowHeadless', 'projectIds'], 'grant');
+        validateRepo(value.repo);
+        if (!Array.isArray(value.operations) || !value.operations.length || value.operations.some(x => typeof x !== 'string' || !allowed.has(x)) || new Set(value.operations).size !== value.operations.length)
+            fail('PERMISSION_FORMAT', '', 'Unknown or repeated operation.');
+        for (const key of ['allowChild', 'allowHeadless'])
+            if (value[key] !== undefined && typeof value[key] !== 'boolean')
+                fail('PERMISSION_FORMAT', '', 'Actor flags must be booleans.');
+        if (value.projectIds !== undefined && (!Array.isArray(value.projectIds) || value.projectIds.length > 100 || value.projectIds.some(x => typeof x !== 'string' || !/^PVT_[A-Za-z0-9_-]+$/.test(x))))
+            fail('PERMISSION_FORMAT', '', 'Expected exact project IDs.');
+        return { repo: value.repo, operations: value.operations, allowChild: value.allowChild === true, allowHeadless: value.allowHeadless === true, projectIds: (value.projectIds ?? []) };
+    });
+    const digest = createHash('sha256').update(captured).digest('hex');
+    return {
+        allows: (operation, repo, projectId) => grants.some(g => g.repo.toLowerCase() === repo.toLowerCase() && g.operations.includes(operation) && (!actor.child || g.allowChild) && (!actor.headless || g.allowHeadless) && (!projectId || g.projectIds.includes(projectId))),
+        isCurrent: async () => { try {
+            const next = await capture(path);
+            return next !== undefined && createHash('sha256').update(next).digest('hex') === digest;
+        }
+        catch {
+            return false;
+        } }
+    };
+}

package/dist/src/result.d.ts

@@ -0,0 +1,4 @@
+import type { OperationResult } from './service-types.js';
+export declare function safeResult(result: OperationResult): OperationResult;
+export declare function rejected(code: string, message: string): OperationResult;
+export declare function errorResult(error: unknown): OperationResult;