@foundation0/git 1.2.5 → 1.3.1

package/README.md

@@ -1,291 +1,291 @@
-# git
-
-`@foundation0/git` exposes a generated Git API object where methods follow the shape `repo.issue.create(...)`, `repo.pr.merge(...)`, etc.
-
-The API client maps GH-style feature paths to Gitea REST endpoints and executes real HTTP requests through `fetch`.
-
-## Install
-
-Install globally:
-
-```bash
-pnpm add -g @foundation0/git
-```
-
-Run MCP server through npm without a global install:
-
-```bash
-npx -y -p @foundation0/git f0-git-mcp --help
-```
-
-Using pnpm:
-
-```bash
-pnpm dlx @foundation0/git f0-git-mcp --help
-```
-
-## Installation in this monorepo
-
-From repo root:
-
-```bash
-pnpm install
-```
-
-Run tests:
-
-```bash
-pnpm -C packages/git test
-```
-
-## Quick start
-
-```ts
-import { createGitServiceApi } from '@foundation0/git'
-
-const api = createGitServiceApi({
-  config: {
-    platform: 'GITEA',
-    giteaHost: 'https://gitea.example.com',
-    giteaToken: process.env.GITEA_TOKEN,
-  },
-  defaultOwner: 'example-org',
-  defaultRepo: 'example-repo',
-})
-```
-
-You can also import the singleton:
-
-```ts
-import { gitServiceApi } from '@foundation0/git'
-```
-
-All methods return:
-
-```ts
-type GitServiceApiExecutionResult = {
-  mapping: GitApiFeatureMapping
-  request: {
-    url: string
-    method: string
-    headers: Record<string, string>
-    query: string[]
-    body?: unknown
-  }
-  status: number
-  ok: boolean
-  body: unknown
-}
-```
-
-## Core request shapes
-
-Write methods accept request fields directly (recommended), or you can set the raw request body with `data` / `json` / `payload` / `requestBody`.
-
-```ts
-await api.repo.issue.create({
-  title: 'Bug report',
-  body: 'Describe issue details',
-  labels: ['bug'],
-})
-
-// equivalent explicit-body form
-await api.repo.issue.create({
-  data: { title: 'Bug report', body: 'Describe issue details', labels: ['bug'] },
-})
-```
-
-Use `headers` to pass custom headers and `query` for additional URL params.
-
-```ts
-await api.repo.issue.list({
-  headers: { 'X-Request-Id': 'local' },
-  query: { state: 'open', limit: 20, page: 1 },
-})
-```
-
-## Popular workflow examples
-
-### 1) Issue lifecycle (most used)
-
-```ts
-// List issues in the default repo
-await api.repo.issue.list()
-
-// Create a new issue
-await api.repo.issue.create({
-  data: {
-    title: 'Login fails with 401',
-    body: 'Repro: open login page and click submit.',
-    labels: ['bug'],
-  },
-})
-
-// View an issue
-await api.repo.issue.view('17')
-
-// Comment on an issue
-await api.repo.issue.comment('17', {
-  data: { body: 'We are investigating this now.' },
-})
-
-// Edit title/body
-await api.repo.issue.edit('17', {
-  data: {
-    title: 'Login fails with 401 (investigating)',
-    body: 'Updated with steps to reproduce.',
-  },
-})
-
-// Close and reopen
-await api.repo.issue.close('17', { reason: 'not_planned' })
-await api.repo.issue.reopen('17')
-```
-
-### 2) Pull request workflow
-
-```ts
-// Open a pull request
-await api.repo.pr.create({
-  data: {
-    title: 'chore: improve error handling',
-    body: 'Adds retries and better messaging.',
-    head: 'feature/error-handling',
-    base: 'main',
-  },
-})
-
-// List and inspect PRs
-await api.repo.pr.list({ query: { state: 'open' } })
-await api.repo.pr.view('42')
-
-// Add a review comment
-await api.repo.pr.comment('42', {
-  data: { body: 'Looks good, please add one test for this branch.' },
-})
-
-// Manage PR lifecycle
-await api.repo.pr.close('42')
-await api.repo.pr.reopen('42')
-await api.repo.pr.merge('42')
-```
-
-### 3) Release flow
-
-```ts
-await api.repo.release.create({
-  data: {
-    tag_name: 'v1.2.0',
-    name: 'v1.2.0',
-    body: 'Changelog and upgrade notes.',
-  },
-})
-
-await api.repo.release.list()
-await api.repo.release.view('v1.2.0')
-await api.repo.release.delete('v1.2.0')
-```
-
-### 4) Repository setup and sync
-
-```ts
-// Read current repo
-await api.repo.view()
-
-// Create repository for authenticated user
-await api.repo.create({ data: { name: 'new-repo', description: 'Automation workspace' } })
-
-// Fork and sync mirror repo
-await api.repo.fork()
-await api.repo.sync()
-```
-
-### 5) Team triage with labels
-
-```ts
-await api.repo.label.listManaged()
-
-await api.repo.label.upsert('priority-high', {
-  color: '#d73a4a',
-  description: 'Initial escalation label',
-})
-
-await api.repo.label.getByName('priority-high')
-
-await api.repo.label.upsert('priority-high', {
-  color: '#fbca04',
-  description: 'Escalated issue',
-})
-
-await api.repo.label.deleteByName('priority-high')
-```
-
-### 6) Search and discovery
-
-```ts
-await api.search.issues({
-  query: {
-    q: 'repo:example-org/example-repo is:open',
-    sort: 'created',
-  },
-})
-
-await api.search.prs({
-  query: {
-    q: 'repo:example-org/example-repo is:pr is:open',
-    sort: 'updated',
-  },
-})
-
-await api.search.repos({
-  query: {
-    q: 'name:example-repo',
-    limit: 10,
-  },
-})
-```
-
-### 7) CI workflow dispatch
-
-```ts
-await api.workflow.list()
-await api.workflow.view('ci.yml')
-await api.workflow.run('ci.yml', {
-  data: {
-    ref: 'main',
-  },
-})
-await api.workflow.disable('ci.yml')
-await api.workflow.enable('ci.yml')
-```
-
-### 8) Security material for automation
-
-```ts
-await api.secret.list()
-await api.variable.list()
-await api.variable.set('CANARY', {
-  data: {
-    value: 'true',
-  },
-})
-```
-
-## Targeting a specific repository
-
-Defaults can be replaced per call by passing owner/repo arguments.
-
-```ts
-await api.repo.issue.create('acme', 'infra', {
-  data: {
-    title: 'Issue in another repo',
-    body: 'Cross-repo task',
-  },
-})
-```
-
-## Notes
-
-1) Some endpoints expose top-level methods too (for example `api.issue.create(...)`), but `repo.*` is the canonical usage style for this package.
-2) This package currently ships with Gitea mapping, with `PLATFORM`/`GITEA_*` configuration ready for multi-platform expansion.
-3) Use the generated feature matrix/spec to discover every mapped command before adding new workflows.
+# git
+
+`@foundation0/git` exposes a generated Git API object where methods follow the shape `repo.issue.create(...)`, `repo.pr.merge(...)`, etc.
+
+The API client maps GH-style feature paths to Gitea REST endpoints and executes real HTTP requests through `fetch`.
+
+## Install
+
+Install globally:
+
+```bash
+pnpm add -g @foundation0/git
+```
+
+Run MCP server through npm without a global install:
+
+```bash
+npx -y -p @foundation0/git f0-git-mcp --help
+```
+
+Using pnpm:
+
+```bash
+pnpm dlx @foundation0/git f0-git-mcp --help
+```
+
+## Installation in this monorepo
+
+From repo root:
+
+```bash
+pnpm install
+```
+
+Run tests:
+
+```bash
+pnpm -C packages/git test
+```
+
+## Quick start
+
+```ts
+import { createGitServiceApi } from '@foundation0/git'
+
+const api = createGitServiceApi({
+  config: {
+    platform: 'GITEA',
+    giteaHost: 'https://gitea.example.com',
+    giteaToken: process.env.GITEA_TOKEN,
+  },
+  defaultOwner: 'example-org',
+  defaultRepo: 'example-repo',
+})
+```
+
+You can also import the singleton:
+
+```ts
+import { gitServiceApi } from '@foundation0/git'
+```
+
+All methods return:
+
+```ts
+type GitServiceApiExecutionResult = {
+  mapping: GitApiFeatureMapping
+  request: {
+    url: string
+    method: string
+    headers: Record<string, string>
+    query: string[]
+    body?: unknown
+  }
+  status: number
+  ok: boolean
+  body: unknown
+}
+```
+
+## Core request shapes
+
+Write methods accept request fields directly (recommended), or you can set the raw request body with `data` / `json` / `payload` / `requestBody`.
+
+```ts
+await api.repo.issue.create({
+  title: 'Bug report',
+  body: 'Describe issue details',
+  labels: ['bug'],
+})
+
+// equivalent explicit-body form
+await api.repo.issue.create({
+  data: { title: 'Bug report', body: 'Describe issue details', labels: ['bug'] },
+})
+```
+
+Use `headers` to pass custom headers and `query` for additional URL params.
+
+```ts
+await api.repo.issue.list({
+  headers: { 'X-Request-Id': 'local' },
+  query: { state: 'open', limit: 20, page: 1 },
+})
+```
+
+## Popular workflow examples
+
+### 1) Issue lifecycle (most used)
+
+```ts
+// List issues in the default repo
+await api.repo.issue.list()
+
+// Create a new issue
+await api.repo.issue.create({
+  data: {
+    title: 'Login fails with 401',
+    body: 'Repro: open login page and click submit.',
+    labels: ['bug'],
+  },
+})
+
+// View an issue
+await api.repo.issue.view('17')
+
+// Comment on an issue
+await api.repo.issue.comment('17', {
+  data: { body: 'We are investigating this now.' },
+})
+
+// Edit title/body
+await api.repo.issue.edit('17', {
+  data: {
+    title: 'Login fails with 401 (investigating)',
+    body: 'Updated with steps to reproduce.',
+  },
+})
+
+// Close and reopen
+await api.repo.issue.close('17', { reason: 'not_planned' })
+await api.repo.issue.reopen('17')
+```
+
+### 2) Pull request workflow
+
+```ts
+// Open a pull request
+await api.repo.pr.create({
+  data: {
+    title: 'chore: improve error handling',
+    body: 'Adds retries and better messaging.',
+    head: 'feature/error-handling',
+    base: 'main',
+  },
+})
+
+// List and inspect PRs
+await api.repo.pr.list({ query: { state: 'open' } })
+await api.repo.pr.view('42')
+
+// Add a review comment
+await api.repo.pr.comment('42', {
+  data: { body: 'Looks good, please add one test for this branch.' },
+})
+
+// Manage PR lifecycle
+await api.repo.pr.close('42')
+await api.repo.pr.reopen('42')
+await api.repo.pr.merge('42')
+```
+
+### 3) Release flow
+
+```ts
+await api.repo.release.create({
+  data: {
+    tag_name: 'v1.2.0',
+    name: 'v1.2.0',
+    body: 'Changelog and upgrade notes.',
+  },
+})
+
+await api.repo.release.list()
+await api.repo.release.view('v1.2.0')
+await api.repo.release.delete('v1.2.0')
+```
+
+### 4) Repository setup and sync
+
+```ts
+// Read current repo
+await api.repo.view()
+
+// Create repository for authenticated user
+await api.repo.create({ data: { name: 'new-repo', description: 'Automation workspace' } })
+
+// Fork and sync mirror repo
+await api.repo.fork()
+await api.repo.sync()
+```
+
+### 5) Team triage with labels
+
+```ts
+await api.repo.label.listManaged()
+
+await api.repo.label.upsert('priority-high', {
+  color: '#d73a4a',
+  description: 'Initial escalation label',
+})
+
+await api.repo.label.getByName('priority-high')
+
+await api.repo.label.upsert('priority-high', {
+  color: '#fbca04',
+  description: 'Escalated issue',
+})
+
+await api.repo.label.deleteByName('priority-high')
+```
+
+### 6) Search and discovery
+
+```ts
+await api.search.issues({
+  query: {
+    q: 'repo:example-org/example-repo is:open',
+    sort: 'created',
+  },
+})
+
+await api.search.prs({
+  query: {
+    q: 'repo:example-org/example-repo is:pr is:open',
+    sort: 'updated',
+  },
+})
+
+await api.search.repos({
+  query: {
+    q: 'name:example-repo',
+    limit: 10,
+  },
+})
+```
+
+### 7) CI workflow dispatch
+
+```ts
+await api.workflow.list()
+await api.workflow.view('ci.yml')
+await api.workflow.run('ci.yml', {
+  data: {
+    ref: 'main',
+  },
+})
+await api.workflow.disable('ci.yml')
+await api.workflow.enable('ci.yml')
+```
+
+### 8) Security material for automation
+
+```ts
+await api.secret.list()
+await api.variable.list()
+await api.variable.set('CANARY', {
+  data: {
+    value: 'true',
+  },
+})
+```
+
+## Targeting a specific repository
+
+Defaults can be replaced per call by passing owner/repo arguments.
+
+```ts
+await api.repo.issue.create('acme', 'infra', {
+  data: {
+    title: 'Issue in another repo',
+    body: 'Cross-repo task',
+  },
+})
+```
+
+## Notes
+
+1) Some endpoints expose top-level methods too (for example `api.issue.create(...)`), but `repo.*` is the canonical usage style for this package.
+2) This package currently ships with Gitea mapping, with `PLATFORM`/`GITEA_*` configuration ready for multi-platform expansion.
+3) Use the generated feature matrix/spec to discover every mapped command before adding new workflows.