Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
41 changes: 40 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -644,6 +644,40 @@ webhook behind it. A 400 with `{"error"}` refuses a bad argument, such as a
malformed `--since`, which `quest` reports as a usage error. `quest/core` exports each read's types and their parsers;
`quest/github`'s `GitHubForge` answers the same reads from GitHub.

### Work on a repository Kixel Quest hosts

A repository can move off GitHub with Kixel Quest as its whole forge. Its
remote is then a Kixel Quest URL, `https://kixel.quest/<owner>/<repo>.git`,
and its PRs are `https://kixel.quest/<owner>/<repo>/pull/<number>`; that alone
tells `quest` the repository lives there, so every read and write goes to
Kixel Quest, with the token `records.json` pairs with it, and never to GitHub.
`QUEST_FORGE=github` cannot reach such a repository, and a failure there names
no override. `quest start` claims with a draft PR there, `quest iterate`,
`ready`, and `release` take and give back holds that Kixel Quest records rather
than labels, and `quest merge --land <sha>` records a pick of that head, which
Kixel Quest's queue lands by fast-forwarding the base and drops once the head
moves, so it takes no `--squash`, `--rebase`, or `--direct`. `quest review`
records its rounds in the PR body there too.

Where `gh` cannot reach, `quest pr` opens, edits, and comments on PRs and
resolves review threads, with `gh pr`'s flags; it works on GitHub too:

```sh
quest pr create --title "Plan the forge" --body-file .tmp/body.md --draft
quest pr edit 12 --body-file .tmp/body.md
quest pr comment 12 --thread <thread-id> --body "Fixed in the head."
quest pr resolve 12 <thread-id>
```

The writes are `POST /forge/<write>`, beside the reads: `open`, `close`,
`edit`, `comment`, `resolve`, `hold`, `ready`, `release`, and `pick`, each
answering `{"value", "asOf"}` with `asOf` null. A 409 with `{"error"}` refuses
the write as things stand, such as a PR another session holds, a second open
PR on a claimed quest branch, or a pick of a head that moved, and `quest`
reports it as a refusal; a 400 refuses a malformed argument as a usage error.
`quest/core` exports the `ForgeWrites` interface and each write's types and
parsers, and the CLI's `GitHubWrites` makes the same writes to GitHub.

## Own a pull request

Before a session pushes to an existing PR, it takes the PR, so two agents
Expand All @@ -656,6 +690,9 @@ quest release 128 <token> # hand it back
quest merge 128 --land <sha> # auto-merge bound to that head; takes no label
```

`quest ready 128` without a token only marks a draft ready, refusing while any
session holds it, for a draft its starter reviewed without taking a hold.

A taken PR carries the `quest:active` label while an agent works on it.
Sessions often share a GitHub account, so taking it prints a hold token: the
ID of the timeline event that added the label. Every command refuses while a
Expand Down Expand Up @@ -715,7 +752,9 @@ GitHub keeps auto-merge across a writer's push, so disable it before pushing
to the PR; `quest status` and `quest wait` report a head that moved since.
The commands accept the same PR argument and authentication as
`quest wait`, and exit 0 when done, 3 when refused, 2 for invalid arguments,
and 1 for other failures.
and 1 for other failures. On a repository
[Kixel Quest hosts](#work-on-a-repository-kixel-quest-hosts), they write there
instead.

This repository lands through GitHub's merge queue. Its required `Queue` check
passes a merge group only when the group's build, `just check` and `just test`
Expand Down
30 changes: 0 additions & 30 deletions quest/m1/forge-writes.md

This file was deleted.

32 changes: 32 additions & 0 deletions quest/m1/kixel-pull-reads.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,32 @@
# [M] PR bodies and comments for repositories Kixel Quest hosts

## Goal

An agent working on a repository Kixel Quest hosts reads a PR's body,
comments, and reviews through `quest`, and is steered to `quest pr` when it
reaches for `gh`, so `/quest-iterate` and `/quest-review` run there without
`gh`.

## Plan

The forge writes gave `quest pr` its create, edit, comment, and resolve, but
an agent still reads a PR's body and discussion with `gh pr view`, which
cannot reach Kixel Quest, and nothing tells it to use `quest pr` instead.

- Add a `view` read to the forge interface and its wire, typed in
`quest/core` like the others: the body, title, comments, and reviews, as
`quest pr view <pr>` prints them. GitHub's backend reads them as `gh pr view
--comments` shows them.
- `quest hook` denies `gh pr` and `gh api` calls in a checkout whose origin
is on Kixel Quest, naming the `quest pr` command to run, through a checked
rule in `src/cli/rules.ts` that adds one line to the Checked section `quest
context` prints: ✅ hook denial with a Checked line (rejected: a prose rule in
`quest context` only; neither). The maintainer settled this in
[moq-dev/quest#769](https://github.com/moq-dev/quest/pull/769#issuecomment-6944655958),
since an agent without it tries `gh`, fails, and has no pointer to the
command that works.

Tests: against the fake Kixel Quest, `quest pr view` prints a PR's body and
comments; and the hook denies `gh pr view` in a checkout whose origin is on
Kixel Quest while it lets the same call through on a GitHub checkout.

138 changes: 97 additions & 41 deletions src/cli/claims.ts
Original file line number Diff line number Diff line change
Expand Up @@ -2,20 +2,49 @@
// `src/github/claims.ts` decides them. Commands that must not disturb held work look here first,
// and `quest start` records a claim the same way, judging readiness by the upstream tree.
import { git } from "./git";
import { type Remote, readRemote, remoteRepository, requireRemote } from "./github";
import { type Remote, readRemote, remoteHost, remoteRepository, requireRemote } from "./github";
import { type GitHubDependencies, GitHub, object, repositoryPath, string } from "../github/client";
import type { Claim, Forge, Holdings, OpenPull, Repository } from "../core";
import type { Claim, Forge, ForgeWrites, Holdings, OpenPull, Repository } from "../core";
import { questBranches } from "../github/claims";
import { GitHubForge } from "../github/forge";
import { landingCheck } from "./landed";
import { GitHubWrites } from "./writes";
import { type Snapshot, snapshot } from "./tree";

export interface ClaimDependencies {
/** Called only when the remote is on GitHub, so other forges need no token. */
github(): GitHubDependencies;
/** The forge answering reads of a repository on GitHub, such as its claims and open PRs. */
forge(repository: Repository): Promise<Forge>;
/** Kixel Quest, for remotes on it; without it, no remote is. */
kixel?: {
/** The repository `url` on Kixel Quest names, or null for none. */
hosted(url: string): Repository | null;
/** Kixel Quest's backend for a repository it hosts, which both reads and writes there. */
forge(repository: Repository): Forge & ForgeWrites;
};
warn(message: string): void;
}

/** The forge an upstream's PRs and claims live on, GitHub or Kixel Quest. */
export interface Hosting {
/** Where PRs open and claims are checked. */
repository: Repository;
/** The repository the remote pushes to: `repository` itself, or a fork. */
head: Repository;
defaultBranch: string;
/** Where this checkout's tree sits in the repository: empty at the top level, else a path ending in `/`. */
prefix: string;
/** The forge answering reads of `repository`, chosen on first use. */
forge(): Promise<Forge>;
/** The forge's own answers, never an index that may lag, for a read that verifies or rewrites what it read. */
live(): Forge;
/** The forge taking writes to `repository`, created on first use. */
writes(): ForgeWrites;
/** A link to `path` on the default branch, where the forge shows files. */
link(path: string): string | null;
}

/**
* Where claims live: the furthest repository up the remote's fork chain that
* keeps quests, so a contributor's fork claims on the project it came from,
Expand All @@ -26,38 +55,49 @@ export interface Upstream {
git: string;
/** The URL the remote pushes to, where a claim branch is pushed. Read from git on first use. */
readonly push: string;
github: {
client: GitHub;
/** Where PRs open and claims are checked. */
repository: Repository;
/** The repository the remote pushes to: `repository` itself, or a fork. */
head: Repository;
defaultBranch: string;
/** Where this checkout's tree sits in the repository: empty at the top level, else a path ending in `/`. */
prefix: string;
/** The forge answering reads of `repository`, chosen on first use. */
forge(): Promise<Forge>;
} | null;
/** The forge PRs open on, or null off GitHub and Kixel Quest. */
hosting: Hosting | null;
/** `hosting` on GitHub, with its client for what only GitHub answers; null elsewhere. */
github: (Hosting & { client: GitHub }) | null;
}

/**
* The upstream of `remote`. On GitHub, it walks from the remote's repository
* up to each parent whose default branch holds the quest tree's README, and
* stops at the first parent without one; a failed lookup fails rather than
* stops the walk. An ancestor is reached with the same URL scheme as the
* remote. Off GitHub, the remote is its own upstream. The head repository is
* where the remote pushes, which may be a fork even when it fetches from upstream.
* remote. Off GitHub, the remote is its own upstream, and on Kixel Quest, which
* keeps no forks, it is the repository there. The head repository is where the
* remote pushes, which may be a fork even when it fetches from upstream.
*/
export async function upstream(root: string, remote: Remote, deps: ClaimDependencies): Promise<Upstream> {
const source = remoteRepository(remote);
if (source.repository === null)
const kixel = deps.kixel;
const source = remoteHost(remote, kixel ? (url) => kixel.hosted(url) : null);
if (source?.forge !== "github") {
const repository = source?.repository ?? null;
let hosted: (Forge & ForgeWrites) | undefined;
const forge = () => (hosted ??= kixel!.forge(repository!));
return {
git: remote.name,
get push() {
return remote.used().push;
},
hosting:
repository === null
? null
: {
repository,
head: repository,
defaultBranch: defaultBranch(root, remote.name),
prefix: git(root, ["rev-parse", "--show-prefix"]),
forge: async () => forge(),
live: forge,
writes: forge,
link: () => null,
},
github: null,
};
}

const client = new GitHub(deps.github());
const self = await repositoryInfo(client, source.repository);
Expand All @@ -72,23 +112,38 @@ export async function upstream(root: string, remote: Remote, deps: ClaimDependen
const prefix = git(root, ["rev-parse", "--show-prefix"]);
const up = await base(client, self, prefix);
let forge: Promise<Forge> | undefined;
let writes: ForgeWrites | undefined;
const { owner, repo } = up.repository;
const github = {
client,
repository: up.repository,
head,
defaultBranch: up.defaultBranch,
prefix,
forge: () => (forge ??= deps.forge(up.repository)),
live: () => new GitHubForge(deps.github()),
writes: () => (writes ??= new GitHubWrites(deps.github(), landingCheck(root))),
link: (path: string) =>
`https://github.com/${owner}/${repo}/blob/${up.defaultBranch}/${encodeURI(prefix + path)}`,
};
return {
// Reach an ancestor the way the remote is reached, so the same credentials work.
git: up === self ? remote.name : /^https:/.test(source.url) ? up.https : up.ssh,
get push() {
return remote.used().push;
},
github: {
client,
repository: up.repository,
head,
defaultBranch: up.defaultBranch,
prefix,
forge: () => (forge ??= deps.forge(up.repository)),
},
hosting: github,
github,
};
}

/** The branch `remote`'s HEAD names, as `git ls-remote --symref` reports it. */
function defaultBranch(root: string, remote: string): string {
const match = /^ref: refs\/heads\/(\S+)\tHEAD$/m.exec(git(root, ["ls-remote", "--symref", remote, "HEAD"]));
if (match === null) throw new Error(`${remote} names no default branch`);
return match[1]!;
}

type Info = Awaited<ReturnType<typeof repositoryInfo>>;

/** `self`, or the nearest fork ancestor whose default branch keeps the quest tree at `prefix`. */
Expand Down Expand Up @@ -151,7 +206,7 @@ function listRemote(root: string, remote: string, patterns: string[]): Map<strin
/**
* Which of `branches` someone holds: pushed to `remote` or its upstream, or the
* head of an open PR in either. Without the remote it warns and checks nothing;
* off GitHub it checks branches only.
* off GitHub and Kixel Quest it checks branches only.
*/
export async function claims(
root: string,
Expand All @@ -164,8 +219,8 @@ export async function claims(
}

/**
* The upstream of `remote` for reading claims, warning when off GitHub that
* only branches count. Without the remote it warns and returns `null`.
* The upstream of `remote` for reading claims, warning when off GitHub and
* Kixel Quest that only branches count. Without the remote it warns and returns `null`.
*/
export async function reach(root: string, name: string, deps: ClaimDependencies): Promise<Upstream | null> {
const remote = readRemote(root, name);
Expand All @@ -174,31 +229,32 @@ export async function reach(root: string, name: string, deps: ClaimDependencies)
return null;
}
const up = await upstream(root, remote, deps);
if (up.github === null) deps.warn(`${name} is not on GitHub, so only its branches were checked for claims`);
if (up.hosting === null)
deps.warn(`${name} is not on GitHub or Kixel Quest, so only its branches were checked for claims`);
return up;
}

/**
* Which of `branches` someone holds, as the upstream's forge decides it on GitHub. `tips` are the
* upstream's `quest/*` branches, when already read; the fork's are read through git too. Off GitHub,
* every branch pushed upstream holds its quest.
* Which of `branches` someone holds, as the upstream's forge decides it. `tips` are the upstream's
* `quest/*` branches, when already read; the fork's are read through git too. Off GitHub and Kixel
* Quest, every branch pushed upstream holds its quest.
*/
export async function held(
root: string,
up: Upstream,
branches: string[],
tips: Map<string, string> = remoteBranches(root, up.git),
): Promise<Holdings> {
if (up.github === null)
if (up.hosting === null)
return {
claims: [...new Set(branches)]
.sort()
.filter((branch) => tips.has(branch))
.map((branch) => ({ branch, url: null, pull: null })),
landed: new Map(),
};
const { repository, head } = up.github;
const forge = await up.github.forge();
const { repository, head } = up.hosting;
const forge = await up.hosting.forge();
const sources = {
upstream: { repository, tips },
...(same(head, repository) ? {} : { fork: { repository: head, tips: remoteBranches(root, up.push) } }),
Expand All @@ -208,8 +264,8 @@ export async function held(

/**
* The open drafts in the upstream of the remote `name`, from any head
* repository. Reading them needs GitHub, so without the remote, off GitHub,
* or when GitHub cannot be reached or refuses, it warns that they were
* repository. Reading them needs a forge, so without the remote, off GitHub
* and Kixel Quest, or when the forge cannot be reached or refuses, it warns that they were
* skipped and returns none, leaving the caller the quest tree.
*/
export async function openDrafts(root: string, name: string, deps: ClaimDependencies): Promise<OpenPull[]> {
Expand All @@ -220,11 +276,11 @@ export async function openDrafts(root: string, name: string, deps: ClaimDependen
}
try {
const up = await upstream(root, remote, deps);
if (up.github === null) {
deps.warn(`${name} is not on GitHub, so draft PRs were skipped`);
if (up.hosting === null) {
deps.warn(`${name} is not on GitHub or Kixel Quest, so draft PRs were skipped`);
return [];
}
const pulls = (await (await up.github.forge()).pulls(up.github.repository)).value;
const pulls = (await (await up.hosting.forge()).pulls(up.hosting.repository)).value;
return pulls.filter((pull) => pull.draft).sort((a, b) => a.number - b.number);
} catch (error) {
deps.warn(`draft PRs were skipped: ${error instanceof Error ? error.message : String(error)}`);
Expand Down
Loading
Loading