gitdog 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,77 @@
-# Temporary Holding Version
+<p align="center">
+  <img src="https://raw.githubusercontent.com/hyodotdev/gitdog-cli/main/.github/assets/gitdog-logo.png" alt="Gitdog" width="112" height="112">
+</p>
 
-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.
+<h1 align="center">Gitdog CLI</h1>
+
+<p align="center">
+  Your GitHub assistant. Now in the terminal.
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/gitdog"><img src="https://img.shields.io/npm/v/gitdog?logo=npm&amp;color=CB3837" alt="npm version"></a>
+  <a href="https://www.npmjs.com/package/gitdog"><img src="https://img.shields.io/npm/dm/gitdog?color=555" alt="npm downloads"></a>
+  <a href="https://github.com/hyodotdev/gitdog-cli/actions/workflows/ci.yml"><img src="https://github.com/hyodotdev/gitdog-cli/actions/workflows/ci.yml/badge.svg?branch=main" alt="CI"></a>
+  <a href="https://nodejs.org"><img src="https://img.shields.io/badge/node-%3E%3D22.14.0-3c873a?logo=nodedotjs&amp;logoColor=white" alt="Node.js 22.14 or later"></a>
+  <a href="https://gitdog.dev"><img src="https://img.shields.io/badge/Gitdog-gitdog.dev-111" alt="Gitdog website"></a>
+</p>
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/hyodotdev/gitdog-cli/main/.github/assets/terminal.svg" alt="Gitdog terminal: connect a project, configure automation and review pending actions" width="800">
+</p>
+
+Connect repositories, configure Gitdog's issue and discussion assistants, review
+AI actions, and automate project tasks from your terminal or CI.
+
+## Install
+
+Requires **Node.js 22.14+**.
+
+```sh
+npm install --global gitdog
+```
+
+## Quick start
+
+```sh
+gitdog login
+gitdog github install
+gitdog github recover
+gitdog init owner/repo
+gitdog config set requireApproval true
+gitdog config push
+```
+
+GitHub App setup is only needed once. A project connects an existing GitHub
+repository to Gitdog.
+
+## Everyday commands
+
+| Task                     | Command                      |
+| ------------------------ | ---------------------------- |
+| List projects            | `gitdog projects list`       |
+| Read automation settings | `gitdog config get --remote` |
+| Review pending actions   | `gitdog tickets pending`     |
+| Check code indexing      | `gitdog index status`        |
+| List team members        | `gitdog team members`        |
+| Check usage              | `gitdog usage summary`       |
+
+Use `gitdog --help` to explore commands. Add `--json` for scripts.
+
+## Use in CI
+
+```sh
+gitdog keys create --name ci
+gitdog --key-file /path/to/key.json projects list --json
+gitdog keys revoke KEY_ID --yes
+```
+
+`keys create` prints the private key file's path. Keys are project-scoped and
+read-only by default; add `--write` for settings and ticket delete/restore. Keep key
+files out of Git.
+
+---
+
+[Command reference](https://github.com/hyodotdev/gitdog-cli/blob/main/docs/REFERENCE.md)
+· [Gitdog](https://gitdog.dev)
+· [Report an issue](https://github.com/hyodotdev/gitdog-cli/issues)

package/dist/api-catalog.json

@@ -0,0 +1,432 @@
+[
+    {
+        "path": "admin/mutation:deleteAiLog",
+        "kind": "mutation",
+        "args": "{\n    logId: v.id(\"aiLogs\"),\n  }"
+    },
+    {
+        "path": "admin/mutation:updateAiLogStatus",
+        "kind": "mutation",
+        "args": "{\n    logId: v.id(\"aiLogs\"),\n    status: v.union(\n      v.literal(\"success\"),\n      v.literal(\"failed\"),\n      v.literal(\"pending_approval\"),\n      v.literal(\"approved\"),\n      v.literal(\"rejected\"),\n      v.literal(\"request_changes\"),\n    ),\n    userFeedback: v.optional(v.string()),\n  }"
+    },
+    {
+        "path": "admin/paymentMutation:addTokens",
+        "kind": "mutation",
+        "args": "{\n    subscriptionId: v.id(\"subscriptions\"),\n    tokensToAdd: v.number(),\n    operationId: v.string(),\n    adminNote: v.optional(v.string()),\n  }"
+    },
+    {
+        "path": "admin/paymentMutation:cancelSubscription",
+        "kind": "mutation",
+        "args": "{\n    subscriptionId: v.id(\"subscriptions\"),\n    operationId: v.string(),\n    adminNote: v.optional(v.string()),\n  }"
+    },
+    {
+        "path": "admin/paymentMutation:reactivateSubscription",
+        "kind": "mutation",
+        "args": "{\n    subscriptionId: v.id(\"subscriptions\"),\n    operationId: v.string(),\n    adminNote: v.optional(v.string()),\n  }"
+    },
+    {
+        "path": "admin/paymentMutation:reconcileGeminiChatUsage",
+        "kind": "mutation",
+        "args": "{\n    reservationKey: v.string(),\n    evidenceSource: v.union(\n  v.literal(\"google_api_response\"),\n  v.literal(\"google_cloud_billing_export\"),\n  v.literal(\"google_support_confirmation\"),\n  v.literal(\"anthropic_api_response\"),\n  v.literal(\"anthropic_usage_report\"),\n  v.literal(\"anthropic_support_confirmation\"),\n  v.literal(\"openai_api_response\"),\n  v.literal(\"openai_usage_report\"),\n  v.literal(\"openai_support_confirmation\"),\n),\n    evidenceReference: v.string(),\n    outcome: v.union(\n      v.object({ kind: v.literal(\"known_not_billed\") }),\n      v.object({\n        kind: v.literal(\"known_billed\"),\n        actualInputTokens: v.number(),\n        actualOutputTokens: v.number(),\n        providerRequestId: v.optional(v.string()),\n      }),\n    ),\n  }"
+    },
+    {
+        "path": "admin/paymentMutation:reconcileGeminiEmbeddingUsage",
+        "kind": "mutation",
+        "args": "{\n    reservationKey: v.string(),\n    evidenceSource: v.union(\n  v.literal(\"google_api_response\"),\n  v.literal(\"google_cloud_billing_export\"),\n  v.literal(\"google_support_confirmation\"),\n  v.literal(\"openai_api_response\"),\n  v.literal(\"openai_billing_export\"),\n  v.literal(\"openai_support_confirmation\"),\n),\n    evidenceReference: v.string(),\n    outcome: v.union(\n      v.object({ kind: v.literal(\"known_not_billed\") }),\n      v.object({\n        kind: v.literal(\"known_billed\"),\n        actualProviderTokens: v.number(),\n      }),\n    ),\n  }"
+    },
+    {
+        "path": "admin/paymentMutation:refundTokens",
+        "kind": "mutation",
+        "args": "{\n    subscriptionId: v.id(\"subscriptions\"),\n    tokensToRefund: v.number(),\n    adminNote: v.optional(v.string()),\n    paymentLogId: v.id(\"paymentLogs\"),\n  }"
+    },
+    {
+        "path": "admin/paymentMutation:requeueSubscriptionInvoiceReview",
+        "kind": "mutation",
+        "args": "{\n    manualReviewId: v.id(\"paymentSettlementManualReviews\"),\n    evidenceReference: v.string(),\n    confirmRetry: v.literal(true),\n  }"
+    },
+    {
+        "path": "admin/paymentMutation:updatePaymentLog",
+        "kind": "mutation",
+        "args": "{\n    paymentLogId: v.id(\"paymentLogs\"),\n    status: v.optional(\n      v.union(\n        v.literal(\"success\"),\n        v.literal(\"failed\"),\n        v.literal(\"pending\"),\n        v.literal(\"refunded\"),\n        v.literal(\"canceled\"),\n      ),\n    ),\n    adminNote: v.optional(v.string()),\n  }"
+    },
+    {
+        "path": "admin/paymentQuery:getPaymentStats",
+        "kind": "query",
+        "args": "{\n    year: v.optional(v.number()),\n    month: v.optional(v.number()), // 0-11 (January = 0)\n  }"
+    },
+    {
+        "path": "admin/paymentQuery:listOpenSettlementReviews",
+        "kind": "query",
+        "args": "{ limit: v.optional(v.number()) }"
+    },
+    {
+        "path": "admin/paymentQuery:listPaymentLogs",
+        "kind": "query",
+        "args": "{\n    limit: v.optional(v.number()),\n    cursor: v.optional(v.string()),\n    statusFilter: v.optional(\n      v.union(\n        v.literal(\"success\"),\n        v.literal(\"failed\"),\n        v.literal(\"pending\"),\n        v.literal(\"refunded\"),\n        v.literal(\"canceled\"),\n      ),\n    ),\n    eventTypeFilter: v.optional(v.string()),\n  }"
+    },
+    {
+        "path": "admin/paymentQuery:listPaymentLogsByUser",
+        "kind": "query",
+        "args": "{\n    year: v.optional(v.number()),\n    month: v.optional(v.number()), // 0-11 (January = 0)\n  }"
+    },
+    {
+        "path": "admin/paymentQuery:listSubscriptions",
+        "kind": "query",
+        "args": "{\n    limit: v.optional(v.number()),\n  }"
+    },
+    {
+        "path": "admin/query:getAiLogById",
+        "kind": "query",
+        "args": "{\n    logId: v.id(\"aiLogs\"),\n  }"
+    },
+    {
+        "path": "admin/query:getAiLogStats",
+        "kind": "query",
+        "args": "{}"
+    },
+    {
+        "path": "admin/query:isAdmin",
+        "kind": "query",
+        "args": "{}"
+    },
+    {
+        "path": "admin/query:listAiLogs",
+        "kind": "query",
+        "args": "{\n    status: v.optional(\n      v.union(\n        v.literal(\"success\"),\n        v.literal(\"failed\"),\n        v.literal(\"pending_approval\"),\n        v.literal(\"approved\"),\n        v.literal(\"rejected\"),\n        v.literal(\"request_changes\"),\n      ),\n    ),\n    workflowType: v.optional(v.string()),\n    limit: v.optional(v.number()),\n    cursor: v.optional(v.string()),\n  }"
+    },
+    {
+        "path": "admin/query:listAiLogsByIndexing",
+        "kind": "query",
+        "args": "{\n    limit: v.optional(v.number()),\n    cursor: v.optional(v.number()),\n  }"
+    },
+    {
+        "path": "admin/query:listAiLogsByTicket",
+        "kind": "query",
+        "args": "{\n    limit: v.optional(v.number()),\n    cursor: v.optional(v.number()), // createdAt timestamp for cursor-based pagination\n  }"
+    },
+    {
+        "path": "apiKeys/action:create",
+        "kind": "action",
+        "args": "{\n    repositoryId: v.id(\"repositories\"),\n    name: v.string(),\n    scopes: v.array(v.union(v.literal(\"read\"), v.literal(\"write\"))),\n    expiresInDays: v.number(),\n  }"
+    },
+    {
+        "path": "apiKeys/mutation:revoke",
+        "kind": "mutation",
+        "args": "{ keyId: v.id(\"projectApiKeys\") }"
+    },
+    {
+        "path": "apiKeys/query:list",
+        "kind": "query",
+        "args": "{\n    repositoryId: v.id(\"repositories\"),\n    paginationOpts: paginationOptsValidator,\n  }"
+    },
+    {
+        "path": "github/action:listUserRepositories",
+        "kind": "action",
+        "args": "{\n    cursor: v.optional(v.string()),\n    reconnectRepositoryId: v.optional(v.string()),\n  }"
+    },
+    {
+        "path": "github/action:recoverOAuthInstallation",
+        "kind": "action",
+        "args": "{}"
+    },
+    {
+        "path": "github/action:retryRepositoryAccessReconciliation",
+        "kind": "action",
+        "args": "{ installationId: v.number() }"
+    },
+    {
+        "path": "github/action:saveInstallation",
+        "kind": "action",
+        "args": "{\n    installationId: v.number(),\n  }"
+    },
+    {
+        "path": "github/query:getInstallation",
+        "kind": "query",
+        "args": "{\n    installationId: v.number(),\n  }"
+    },
+    {
+        "path": "github/query:getUserInstallation",
+        "kind": "query",
+        "args": "{}"
+    },
+    {
+        "path": "github/query:getUserInstallations",
+        "kind": "query",
+        "args": "{}"
+    },
+    {
+        "path": "invitations/action:create",
+        "kind": "action",
+        "args": "{\n    repositoryId: v.id(\"repositories\"),\n    inviteeGithubUsername: v.string(),\n    role: v.literal(\"viewer\"),\n  }"
+    },
+    {
+        "path": "invitations/mutation:accept",
+        "kind": "mutation",
+        "args": "{\n    invitationId: v.id(\"invitations\"),\n  }"
+    },
+    {
+        "path": "invitations/mutation:cancel",
+        "kind": "mutation",
+        "args": "{\n    invitationId: v.id(\"invitations\"),\n  }"
+    },
+    {
+        "path": "invitations/mutation:reject",
+        "kind": "mutation",
+        "args": "{\n    invitationId: v.id(\"invitations\"),\n  }"
+    },
+    {
+        "path": "invitations/query:getPendingForRepository",
+        "kind": "query",
+        "args": "{\n    repositoryId: v.id(\"repositories\"),\n  }"
+    },
+    {
+        "path": "invitations/query:listForRepository",
+        "kind": "query",
+        "args": "{\n    repositoryId: v.id(\"repositories\"),\n  }"
+    },
+    {
+        "path": "invitations/query:listPending",
+        "kind": "query",
+        "args": "{}"
+    },
+    {
+        "path": "notifications/mutation:markAllAsRead",
+        "kind": "mutation",
+        "args": "{}"
+    },
+    {
+        "path": "notifications/mutation:markAsRead",
+        "kind": "mutation",
+        "args": "{\n    notificationId: v.id(\"notifications\"),\n  }"
+    },
+    {
+        "path": "notifications/query:getUnreadCount",
+        "kind": "query",
+        "args": "{}"
+    },
+    {
+        "path": "notifications/query:list",
+        "kind": "query",
+        "args": "{\n    limit: v.optional(v.number()),\n  }"
+    },
+    {
+        "path": "notifications/query:listUnread",
+        "kind": "query",
+        "args": "{}"
+    },
+    {
+        "path": "repoIndexing/mutation:initializeIndexing",
+        "kind": "mutation",
+        "args": "{\n    repositoryId: v.id(\"repositories\"),\n  }"
+    },
+    {
+        "path": "repoIndexing/query:getFileContent",
+        "kind": "query",
+        "args": "{\n    repositoryId: v.id(\"repositories\"),\n    filePath: v.string(),\n  }"
+    },
+    {
+        "path": "repoIndexing/query:getFileList",
+        "kind": "query",
+        "args": "{\n    repositoryId: v.id(\"repositories\"),\n    limit: v.optional(v.number()),\n  }"
+    },
+    {
+        "path": "repoIndexing/query:getIndexingLogs",
+        "kind": "query",
+        "args": "{\n    repositoryId: v.id(\"repositories\"),\n    limit: v.optional(v.number()),\n  }"
+    },
+    {
+        "path": "repoIndexing/query:getIndexingStatus",
+        "kind": "query",
+        "args": "{\n    repositoryId: v.id(\"repositories\"),\n  }"
+    },
+    {
+        "path": "repoLearnings/query:countByRepository",
+        "kind": "query",
+        "args": "{\n    repositoryId: v.id(\"repositories\"),\n  }"
+    },
+    {
+        "path": "repositories/action:createAndIndex",
+        "kind": "action",
+        "args": "{\n    installationId: v.number(),\n    githubRepositoryId: v.number(),\n    reconnectRepositoryId: v.optional(v.string()),\n  }"
+    },
+    {
+        "path": "repositories/action:syncRepository",
+        "kind": "action",
+        "args": "{\n    repositoryId: v.id(\"repositories\"),\n  }"
+    },
+    {
+        "path": "repositories/mutation:remove",
+        "kind": "mutation",
+        "args": "{ repositoryId: v.id(\"repositories\") }"
+    },
+    {
+        "path": "repositories/mutation:toggleActive",
+        "kind": "mutation",
+        "args": "{\n    repositoryId: v.id(\"repositories\"),\n    isActive: v.optional(v.boolean()),\n  }"
+    },
+    {
+        "path": "repositories/mutation:updateSettings",
+        "kind": "mutation",
+        "args": "{\n    repositoryId: v.id(\"repositories\"),\n    settings: v.object({\n      issueAssistantEnabled: v.boolean(),\n      autoFormatIssue: v.boolean(),\n      autoAnswerQuestions: v.boolean(),\n      tagMaintainersForCodeChanges: v.boolean(),\n      issueResponseStyle: v.optional(v.string()),\n      requireApproval: v.boolean(),\n      discussionAssistantEnabled: v.boolean(),\n      autoFormatDiscussion: v.boolean(),\n      autoAnswerDiscussionQuestions: v.boolean(),\n      tagMaintainersForDiscussionCodeChanges: v.boolean(),\n      discussionResponseStyle: v.optional(v.string()),\n      requireApprovalForDiscussions: v.boolean(),\n    }),\n  }"
+    },
+    {
+        "path": "repositories/query:get",
+        "kind": "query",
+        "args": "{\n    owner: v.string(),\n    repo: v.string(),\n  }"
+    },
+    {
+        "path": "repositories/query:getById",
+        "kind": "query",
+        "args": "{\n    repositoryId: v.id(\"repositories\"),\n  }"
+    },
+    {
+        "path": "repositories/query:getConnectedRepos",
+        "kind": "query",
+        "args": "{}"
+    },
+    {
+        "path": "repositories/query:getReconnectTarget",
+        "kind": "query",
+        "args": "{\n    reconnectRepositoryId: v.string(),\n  }"
+    },
+    {
+        "path": "repositories/query:list",
+        "kind": "query",
+        "args": "{}"
+    },
+    {
+        "path": "repositoryMembers/mutation:leave",
+        "kind": "mutation",
+        "args": "{\n    repositoryId: v.id(\"repositories\"),\n  }"
+    },
+    {
+        "path": "repositoryMembers/mutation:remove",
+        "kind": "mutation",
+        "args": "{\n    memberId: v.id(\"repositoryMembers\"),\n  }"
+    },
+    {
+        "path": "repositoryMembers/query:getMyRole",
+        "kind": "query",
+        "args": "{\n    repositoryId: v.id(\"repositories\"),\n  }"
+    },
+    {
+        "path": "repositoryMembers/query:list",
+        "kind": "query",
+        "args": "{\n    repositoryId: v.id(\"repositories\"),\n  }"
+    },
+    {
+        "path": "subscriptions/action:createCheckoutUrl",
+        "kind": "action",
+        "args": "{\n    plan: v.literal(\"pro\"),\n  }"
+    },
+    {
+        "path": "subscriptions/action:createTokenPackCheckoutUrl",
+        "kind": "action",
+        "args": "{\n    packSize: v.union(v.literal(\"small\"), v.literal(\"large\")),\n  }"
+    },
+    {
+        "path": "subscriptions/query:calculateOverage",
+        "kind": "query",
+        "args": "{}"
+    },
+    {
+        "path": "subscriptions/query:canPerformAction",
+        "kind": "query",
+        "args": "{}"
+    },
+    {
+        "path": "subscriptions/query:getCurrent",
+        "kind": "query",
+        "args": "{}"
+    },
+    {
+        "path": "subscriptions/query:getPricingInfo",
+        "kind": "query",
+        "args": "{}"
+    },
+    {
+        "path": "ticketActions/action:approve",
+        "kind": "action",
+        "args": "{\n    actionId: v.id(\"ticketActions\"),\n  }"
+    },
+    {
+        "path": "ticketActions/action:reject",
+        "kind": "action",
+        "args": "{\n    actionId: v.id(\"ticketActions\"),\n  }"
+    },
+    {
+        "path": "ticketActions/action:requestChanges",
+        "kind": "action",
+        "args": "{\n    actionId: v.id(\"ticketActions\"),\n    feedback: v.string(),\n  }"
+    },
+    {
+        "path": "ticketActions/query:getById",
+        "kind": "query",
+        "args": "{\n    id: v.id(\"ticketActions\"),\n  }"
+    },
+    {
+        "path": "ticketActions/query:listByTicket",
+        "kind": "query",
+        "args": "{\n    ticketId: v.id(\"tickets\"),\n  }"
+    },
+    {
+        "path": "tickets/mutation:restore",
+        "kind": "mutation",
+        "args": "{\n    id: v.id(\"tickets\"),\n  }"
+    },
+    {
+        "path": "tickets/mutation:softDelete",
+        "kind": "mutation",
+        "args": "{\n    id: v.id(\"tickets\"),\n  }"
+    },
+    {
+        "path": "tickets/query:getById",
+        "kind": "query",
+        "args": "{\n    id: v.id(\"tickets\"),\n  }"
+    },
+    {
+        "path": "tickets/query:list",
+        "kind": "query",
+        "args": "{\n    githubRepo: v.optional(v.string()),\n    status: v.optional(v.union(v.literal(\"open\"), v.literal(\"closed\"))),\n    ticketType: v.optional(\n      v.union(v.literal(\"issue\"), v.literal(\"discussion\")),\n    ),\n    search: v.optional(v.string()),\n    limit: v.optional(v.number()),\n    offset: v.optional(v.number()),\n  }"
+    },
+    {
+        "path": "tickets/query:listPendingApproval",
+        "kind": "query",
+        "args": "{\n    githubRepo: v.optional(v.string()),\n    ticketType: v.optional(\n      v.union(v.literal(\"issue\"), v.literal(\"discussion\")),\n    ),\n    search: v.optional(v.string()),\n    limit: v.optional(v.number()),\n    offset: v.optional(v.number()),\n  }"
+    },
+    {
+        "path": "tokenUsage/query:getCurrentMonthUsage",
+        "kind": "query",
+        "args": "{}"
+    },
+    {
+        "path": "tokenUsage/query:getUsageByRepository",
+        "kind": "query",
+        "args": "{}"
+    },
+    {
+        "path": "users/action:ensureProfile",
+        "kind": "action",
+        "args": "{}"
+    },
+    {
+        "path": "users/mutation:attestLegalEligibility",
+        "kind": "mutation",
+        "args": "{\n    minimumAgeConfirmed: v.literal(true),\n    professionalUseConfirmed: v.literal(true),\n    termsAccepted: v.literal(true),\n    privacyPolicyAccepted: v.literal(true),\n    displayedTermsVersion: v.string(),\n    displayedPrivacyPolicyVersion: v.string(),\n  }"
+    },
+    {
+        "path": "users/mutation:ensureProfileFromAuth",
+        "kind": "mutation",
+        "args": "{}"
+    },
+    {
+        "path": "users/query:getCurrentUser",
+        "kind": "query",
+        "args": "{}"
+    },
+    {
+        "path": "users/query:getProfile",
+        "kind": "query",
+        "args": "{ userId: v.id(\"users\") }"
+    }
+]

package/dist/api-keys.d.ts

@@ -0,0 +1,15 @@
+export type ProjectKey = {
+    version: 1;
+    apiKey: string;
+    apiUrl: string;
+    httpUrl: string;
+    keyId: string;
+    repositoryId: string;
+    name: string;
+    scopes: string[];
+    expiresAt: number;
+};
+export declare function projectHttpUrl(apiUrl: string): string;
+export declare function readProjectKey(path: string): Promise<ProjectKey>;
+export declare function saveProjectKey(path: string, key: ProjectKey): Promise<void>;
+export declare function callWithProjectKey<T>(apiUrl: string, keyFile: string | undefined, rawKey: string | undefined, kind: string, path: string, args: unknown, timeoutMs: number): Promise<T>;

package/dist/api-keys.js

@@ -0,0 +1,93 @@
+import { mkdir, open, readFile, rm } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { asRecord } from "./ui.js";
+import { validateUrl } from "./storage.js";
+export function projectHttpUrl(apiUrl) {
+    return validateUrl(process.env.GITDOG_HTTP_URL ??
+        apiUrl.replace(/\.convex\.cloud$/, ".convex.site"), "Project HTTP URL");
+}
+export async function readProjectKey(path) {
+    let value;
+    try {
+        value = JSON.parse(await readFile(resolve(path), "utf8"));
+    }
+    catch {
+        throw new Error("Cannot read the API key file. Check its path, permissions and JSON syntax.");
+    }
+    const key = asRecord(value);
+    if (key?.version !== 1 ||
+        typeof key.apiKey !== "string" ||
+        !/^gdk_[a-f0-9]{64}$/.test(key.apiKey) ||
+        typeof key.apiUrl !== "string" ||
+        typeof key.httpUrl !== "string" ||
+        typeof key.keyId !== "string" ||
+        typeof key.repositoryId !== "string" ||
+        typeof key.name !== "string" ||
+        !Array.isArray(key.scopes) ||
+        !key.scopes.every((scope) => typeof scope === "string") ||
+        typeof key.expiresAt !== "number")
+        throw new Error("Invalid Gitdog project API key file.");
+    return {
+        version: 1,
+        apiKey: key.apiKey,
+        apiUrl: validateUrl(key.apiUrl, "Key API URL"),
+        httpUrl: validateUrl(key.httpUrl, "Key HTTP URL"),
+        keyId: key.keyId,
+        repositoryId: key.repositoryId,
+        name: key.name,
+        scopes: key.scopes,
+        expiresAt: key.expiresAt,
+    };
+}
+export async function saveProjectKey(path, key) {
+    await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+    const handle = await open(path, "wx", 0o600);
+    try {
+        await handle.writeFile(JSON.stringify(key, null, 2) + "\n");
+    }
+    catch (error) {
+        await handle.close();
+        await rm(path, { force: true });
+        throw error;
+    }
+    await handle.close();
+}
+export async function callWithProjectKey(apiUrl, keyFile, rawKey, kind, path, args, timeoutMs) {
+    const deadline = Date.now() + timeoutMs;
+    if (rawKey && keyFile)
+        throw new Error("Select GITDOG_API_KEY or a key file, not both.");
+    const credential = keyFile ? await readProjectKey(keyFile) : undefined;
+    if (credential && credential.apiUrl !== apiUrl)
+        throw new Error("This API key file belongs to another API URL. Select the matching --api-url.");
+    const key = credential?.apiKey ?? rawKey;
+    if (!key || !/^gdk_[a-f0-9]{64}$/.test(key))
+        throw new Error("Invalid Gitdog project API key.");
+    if (kind === "action")
+        throw new Error("This command requires an owner login. Project API keys cannot manage accounts, keys, billing or GitHub actions.");
+    const remaining = deadline - Date.now();
+    if (remaining <= 0)
+        throw new Error("Project API request timed out.");
+    const response = await fetch(`${credential?.httpUrl ?? projectHttpUrl(apiUrl)}/v1/cli`, {
+        method: "POST",
+        redirect: "error",
+        signal: AbortSignal.timeout(remaining),
+        headers: { "Content-Type": "application/json", "X-Gitdog-Api-Key": key },
+        body: JSON.stringify({ kind, path, args }),
+    });
+    let result;
+    try {
+        result = asRecord(await response.json());
+    }
+    catch {
+        throw new Error(`Project API returned HTTP ${response.status} without a JSON response.`);
+    }
+    if (!response.ok) {
+        const error = asRecord(result?.error);
+        throw new Error(typeof error?.message === "string"
+            ? error.message
+            : `Project API returned HTTP ${response.status}.`);
+    }
+    if (!result || !Object.hasOwn(result, "value"))
+        throw new Error("Invalid project API response.");
+    return result.value;
+}

package/dist/auth.d.ts

@@ -0,0 +1,13 @@
+import { SessionStore } from "./storage.js";
+import { type Ui } from "./ui.js";
+export declare const CALLBACK_PATH = "/gitdog/callback";
+export declare function openBrowser(url: string, signal?: AbortSignal): Promise<boolean>;
+export declare function createLoginListener(timeoutMs?: number): Promise<{
+    redirectTo: string;
+    signal: AbortSignal;
+    code: Promise<string>;
+    close: () => Promise<void>;
+}>;
+export declare function validateAuthRedirect(value: string, apiUrl: string): void;
+export declare function login(apiUrl: string, siteUrl: string, ui: Ui, noBrowser?: boolean): Promise<void>;
+export declare function logout(ui: Ui, localOnly?: boolean, store?: SessionStore): Promise<void>;