@dxos/plugin-github 0.7.4 → 0.13.0

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

@@ -0,0 +1,270 @@
+import * as Schema from 'effect/Schema';
+import { AiService } from '@dxos/ai';
+import * as Operation from '@dxos/compute/Operation';
+import * as Trace from '@dxos/compute/Trace';
+import { Database, Obj } from '@dxos/echo';
+import { Connection } from '@dxos/link';
+import { PullRequest } from '@dxos/types';
+import * as Walkthrough from './Walkthrough.ts';
+/**
+ * Discovery only — list GitHub repositories the connection's token can see.
+ * Returns one descriptor per repo across all the user's orgs (and personal
+ * account). Read-only: NEVER materializes local objects — materialization is
+ * handled by the connector's `materializeTarget` when a `Cursor` is created.
+ *
+ * Orgs and their members are NOT presented as sync targets — they are
+ * auto-synced as part of the sync of any repo they own.
+ */
+export declare const GetGitHubRepositories: Operation.Definition<{
+    readonly connection: import("@dxos/echo/internal").Ref<Connection.Connection & import("@dxos/echo/Entity").OfKind<import("@dxos/echo/internal").EntityKind.Object> & Obj.Unknown>;
+}, {
+    readonly targets: readonly {
+        readonly id: string;
+        readonly name: string;
+        readonly description?: string | undefined;
+        readonly metadata?: {
+            readonly [x: string]: unknown;
+        } | undefined;
+    }[];
+}, never>;
+/**
+ * Find-or-create the empty local root Project for a selected GitHub repo so a
+ * cursor can reference it as its `spec.target`. Keyed by the repo's
+ * GitHub foreign id (`remoteTarget.id`), so it is idempotent across re-selection.
+ */
+export declare const MaterializeGitHubTarget: Operation.Definition<{
+    readonly connection: import("@dxos/echo/internal").Ref<Connection.Connection & import("@dxos/echo/Entity").OfKind<import("@dxos/echo/internal").EntityKind.Object> & Obj.Unknown>;
+    readonly remoteTarget?: {
+        readonly id: string;
+        readonly name: string;
+        readonly description?: string | undefined;
+        readonly metadata?: {
+            readonly [x: string]: unknown;
+        } | undefined;
+    } | undefined;
+}, {
+    readonly target: import("@dxos/echo/internal").Ref<Obj.Unknown>;
+}, never>;
+/**
+ * Per-target options. `maxDaysBack` caps how far back issues/PRs are pulled
+ * (mirrors the Gmail mailbox `daysBack`). Default — when unset — is "sync
+ * everything ever opened or edited."
+ */
+export declare const SyncOptions: Schema.Struct<{
+    readonly maxDaysBack: Schema.optional<Schema.Number>;
+}>;
+export interface SyncOptions extends Schema.Schema.Type<typeof SyncOptions> {
+}
+/**
+ * Reconcile GitHub data for every repo bound to a connection (one cursor per repo).
+ *
+ * Pull-then-push per bound repo: auto-upsert its owning org + members,
+ * three-way merge the repo as a Project and its issues/PRs as Tasks (respecting
+ * `maxDaysBack` if set), then push diverged Project/Task fields back to GitHub.
+ * Sync state (`lastTick`/`lastError`/`spec.snapshots`) is written onto each binding.
+ */
+export declare const SyncGitHubRepositories: Operation.Definition<{
+    readonly connection: import("@dxos/echo/internal").Ref<Connection.Connection & import("@dxos/echo/Entity").OfKind<import("@dxos/echo/internal").EntityKind.Object> & Obj.Unknown>;
+    readonly priority?: string | undefined;
+}, {
+    readonly pulled: {
+        readonly organizations: number;
+        readonly people: number;
+        readonly projects: number;
+        readonly tasks: number;
+        readonly comments: number;
+    };
+}, never>;
+/**
+ * Import a pull request named by a github.com URL or `owner/repo#123` into the space, so it can be
+ * opened, reviewed and walked through without waiting for a sync of the whole repository.
+ *
+ * Idempotent by coordinates — a pull request the space already holds is returned as it stands
+ * rather than duplicated.
+ */
+export declare const ImportPullRequest: Operation.Definition<{
+    readonly reference: string;
+}, {
+    readonly pullRequest: import("@dxos/echo/internal").Ref<PullRequest.PullRequest & import("@dxos/echo/Entity").OfKind<import("@dxos/echo/internal").EntityKind.Object> & Obj.Unknown>;
+    readonly imported: boolean;
+}, Database.Service>;
+/**
+ * Import the pull request the browser extension is looking at, named by the page's own URL.
+ *
+ * Separate from {@link ImportPullRequest} because the extension bridge invokes every page action
+ * with the fixed `{ snapshot, target }` shape and reads an `{ id }` back. Nothing is extracted from
+ * the page: the URL in the snapshot's source names the pull request, and GitHub is the authority on
+ * everything else.
+ */
+export declare const ImportPullRequestFromSnapshot: Operation.Definition<{
+    readonly snapshot: {
+        readonly source: {
+            readonly url: string;
+            readonly title: string;
+            readonly favicon?: string | undefined;
+            readonly clippedAt: string;
+        };
+        readonly selection?: {
+            readonly text: string;
+            readonly html?: string | undefined;
+            readonly htmlTruncated?: boolean | undefined;
+            readonly rect?: {
+                readonly x: number;
+                readonly y: number;
+                readonly width: number;
+                readonly height: number;
+            } | undefined;
+        } | undefined;
+        readonly hints?: {
+            readonly ogTitle?: string | undefined;
+            readonly ogDescription?: string | undefined;
+            readonly ogImage?: string | undefined;
+            readonly jsonLd?: readonly unknown[] | undefined;
+            readonly h1?: string | undefined;
+            readonly firstImage?: string | undefined;
+        } | undefined;
+        readonly imageData?: string | undefined;
+        readonly html?: string | undefined;
+        readonly htmlTruncated?: boolean | undefined;
+    };
+    readonly target: Database.Database;
+}, {
+    readonly id: string;
+}, never>;
+/**
+ * Generate a walkthrough of a pull request: one markdown document narrating the change in reading
+ * order, with its diff chunks spliced in from the patch itself.
+ *
+ * Idempotent by commit — a walkthrough already generated for the pull request's head is returned
+ * unchanged unless `force` says otherwise, since the answer cannot have changed.
+ */
+export declare const GenerateWalkthrough: Operation.Definition<{
+    readonly pullRequest: import("@dxos/echo/internal").Ref<PullRequest.PullRequest & import("@dxos/echo/Entity").OfKind<import("@dxos/echo/internal").EntityKind.Object> & Obj.Unknown>;
+    readonly force?: boolean | undefined;
+}, {
+    readonly walkthrough: import("@dxos/echo/internal").Ref<Walkthrough.Walkthrough & import("@dxos/echo/Entity").OfKind<import("@dxos/echo/internal").EntityKind.Object> & Obj.Unknown>;
+    readonly generated: boolean;
+    readonly covered: number;
+    readonly total: number;
+}, AiService.AiService | Trace.TraceService>;
+/**
+ * Submit an approving review on a pull request, as the space's GitHub connection.
+ *
+ * Falls back to a marked conversation comment where GitHub refuses the review — the author's own
+ * pull request, or a token with no review permission — so the approval is still recorded and still
+ * detectable by an agent deciding whether the pull request is good to land.
+ */
+export declare const SubmitPullRequestApproval: Operation.Definition<{
+    readonly pullRequest: import("@dxos/echo/internal").Ref<PullRequest.PullRequest & import("@dxos/echo/Entity").OfKind<import("@dxos/echo/internal").EntityKind.Object> & Obj.Unknown>;
+    readonly body?: string | undefined;
+}, {
+    readonly reviewId?: number | undefined;
+    readonly commentId?: number | undefined;
+    readonly url?: string | undefined;
+    readonly commented: boolean;
+}, never>;
+/** Post a conversation comment on a pull request, as the space's GitHub connection. */
+export declare const AddPullRequestComment: Operation.Definition<{
+    readonly pullRequest: import("@dxos/echo/internal").Ref<PullRequest.PullRequest & import("@dxos/echo/Entity").OfKind<import("@dxos/echo/internal").EntityKind.Object> & Obj.Unknown>;
+    readonly body: string;
+}, {
+    readonly commentId: number;
+    readonly url?: string | undefined;
+}, never>;
+/** Post a review comment on one line of a pull request's diff, as the space's GitHub connection. */
+export declare const AddPullRequestReviewComment: Operation.Definition<{
+    readonly pullRequest: import("@dxos/echo/internal").Ref<PullRequest.PullRequest & import("@dxos/echo/Entity").OfKind<import("@dxos/echo/internal").EntityKind.Object> & Obj.Unknown>;
+    readonly body: string;
+    readonly commit: string;
+    readonly path: string;
+    readonly line: number;
+    readonly side: "LEFT" | "RIGHT";
+}, {
+    readonly commentId: number;
+    readonly url?: string | undefined;
+}, never>;
+/**
+ * Re-read a stored pull request from GitHub and write back whatever has changed — its title, state,
+ * description, branches and size — so the object in the space does not go stale between syncs.
+ */
+export declare const SyncPullRequest: Operation.Definition<{
+    readonly pullRequest: import("@dxos/echo/internal").Ref<PullRequest.PullRequest & import("@dxos/echo/Entity").OfKind<import("@dxos/echo/internal").EntityKind.Object> & Obj.Unknown>;
+}, {
+    readonly updated: readonly string[];
+}, never>;
+/** Aggregate outcome of a commit's check runs; `none` when the commit has no checks at all. */
+export declare const CiState: Schema.Literals<readonly ["success", "failure", "pending", "none"]>;
+export type CiState = Schema.Schema.Type<typeof CiState>;
+export declare const CheckCounts: Schema.Struct<{
+    readonly total: Schema.Number;
+    readonly passed: Schema.Number;
+    readonly failed: Schema.Number;
+    readonly pending: Schema.Number;
+}>;
+export interface CheckCounts extends Schema.Schema.Type<typeof CheckCounts> {
+}
+/**
+ * Where the reviews stand, from each reviewer's latest verdict: any outstanding request for changes
+ * outweighs approvals, and `none` means no reviewer has approved or asked for changes.
+ */
+export declare const ReviewState: Schema.Literals<readonly ["approved", "changes_requested", "none"]>;
+export type ReviewState = Schema.Schema.Type<typeof ReviewState>;
+/** How one check run ended, folded to what a reader acts on; `skipped` is neither passing nor failing. */
+export declare const CheckOutcome: Schema.Literals<readonly ["success", "failure", "pending", "skipped", "neutral"]>;
+export type CheckOutcome = Schema.Schema.Type<typeof CheckOutcome>;
+/** One check run on the head commit, as the article lists it. */
+export declare const CheckRun: Schema.Struct<{
+    readonly name: Schema.String;
+    readonly outcome: Schema.Literals<readonly ["success", "failure", "pending", "skipped", "neutral"]>;
+    /** GitHub's own `conclusion` (`timed_out`, `cancelled`, …), kept for the label when it says more than the outcome. */
+    readonly conclusion: Schema.optional<Schema.String>;
+    /** Where the run's logs live: the provider's page when it has one, else GitHub's. */
+    readonly url: Schema.optional<Schema.String>;
+    readonly startedAt: Schema.optional<Schema.String>;
+    readonly completedAt: Schema.optional<Schema.String>;
+}>;
+export interface CheckRun extends Schema.Schema.Type<typeof CheckRun> {
+}
+/** Read a pull request's live state and the CI outcome of its head commit from GitHub. */
+export declare const GetPullRequestStatus: Operation.Definition<{
+    readonly pullRequest: import("@dxos/echo/internal").Ref<PullRequest.PullRequest & import("@dxos/echo/Entity").OfKind<import("@dxos/echo/internal").EntityKind.Object> & Obj.Unknown>;
+}, {
+    readonly state: "closed" | "draft" | "merged" | "open";
+    readonly title: string;
+    readonly commit?: string | undefined;
+    readonly body?: string | undefined;
+    readonly ci: "failure" | "none" | "pending" | "success";
+    readonly checks: {
+        readonly total: number;
+        readonly passed: number;
+        readonly failed: number;
+        readonly pending: number;
+    };
+    readonly runs: readonly {
+        readonly name: string;
+        readonly outcome: "failure" | "neutral" | "pending" | "skipped" | "success";
+        readonly conclusion?: string | undefined;
+        readonly url?: string | undefined;
+        readonly startedAt?: string | undefined;
+        readonly completedAt?: string | undefined;
+    }[];
+    readonly review: "approved" | "changes_requested" | "none";
+    readonly approvals: number;
+}, never>;
+/**
+ * Read a pull request's whole change as a unified diff, with the head commit it was taken at so a
+ * line comment on it anchors to the lines the reader saw.
+ */
+export declare const GetPullRequestDiff: Operation.Definition<{
+    readonly pullRequest: import("@dxos/echo/internal").Ref<PullRequest.PullRequest & import("@dxos/echo/Entity").OfKind<import("@dxos/echo/internal").EntityKind.Object> & Obj.Unknown>;
+}, {
+    readonly commit?: string | undefined;
+    readonly diff: string;
+}, never>;
+/**
+ * Progress key for {@link GenerateWalkthrough}, derived from the pull request rather than passed, so
+ * the UI can watch a run it did not start. The absolute URI form is required: a hydration-dependent
+ * one would not match the key the producer mints.
+ */
+export declare const createWalkthroughProgressKey: (pullRequest: PullRequest.PullRequest) => string;
+//# sourceMappingURL=GitHubOperation.d.ts.map

package/dist/types/src/types/GitHubOperation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"GitHubOperation.d.ts","sourceRoot":"","sources":["../../../../src/types/GitHubOperation.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AAExC,OAAO,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AACrC,OAAO,KAAK,SAAS,MAAM,yBAAyB,CAAC;AACrD,OAAO,KAAK,KAAK,MAAM,qBAAqB,CAAC;AAC7C,OAAO,EAAE,QAAQ,EAAO,GAAG,EAAO,MAAM,YAAY,CAAC;AAIrD,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAGxC,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE1C,OAAO,KAAK,WAAW,MAAM,kBAAkB,CAAC;AAEhD;;;;;;;;GAQG;AACH,eAAO,MAAM,qBAAqB;;;;;;;;;;;SAShC,CAAC;AAEH;;;;GAIG;AACH,eAAO,MAAM,uBAAuB;;;;;;;;;;;;SASlC,CAAC;AAEH;;;;GAIG;AACH,eAAO,MAAM,WAAW;;EAKtB,CAAC;AAEH,MAAM,WAAW,WAAY,SAAQ,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,WAAW,CAAC;CAAG;AAE9E;;;;;;;GAOG;AACH,eAAO,MAAM,sBAAsB;;;;;;;;;;;SAiBT,CAAC;AAE3B;;;;;;GAMG;AACH,eAAO,MAAM,iBAAiB;;;;;oBAkByB,CAAC;AAExD;;;;;;;GAOG;AACH,eAAO,MAAM,6BAA6B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;SAeN,CAAC;AAErC;;;;;;GAMG;AACH,eAAO,MAAM,mBAAmB;;;;;;;;4CAwBN,CAAC;AAE3B;;;;;;GAMG;AACH,eAAO,MAAM,yBAAyB;;;;;;;;SAsBpC,CAAC;AAEH,uFAAuF;AACvF,eAAO,MAAM,qBAAqB;;;;;;SAgBhC,CAAC;AAEH,oGAAoG;AACpG,eAAO,MAAM,2BAA2B;;;;;;;;;;SAsBtC,CAAC;AAEH;;;GAGG;AACH,eAAO,MAAM,eAAe;;;;SAeQ,CAAC;AAErC,+FAA+F;AAC/F,eAAO,MAAM,OAAO,qEAA6D,CAAC;AAClF,MAAM,MAAM,OAAO,GAAG,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,OAAO,CAAC,CAAC;AAEzD,eAAO,MAAM,WAAW;;;;;EAKtB,CAAC;AACH,MAAM,WAAW,WAAY,SAAQ,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,WAAW,CAAC;CAAG;AAE9E;;;GAGG;AACH,eAAO,MAAM,WAAW,qEAA6D,CAAC;AACtF,MAAM,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,WAAW,CAAC,CAAC;AAEjE,0GAA0G;AAC1G,eAAO,MAAM,YAAY,mFAA2E,CAAC;AACrG,MAAM,MAAM,YAAY,GAAG,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,YAAY,CAAC,CAAC;AAEnE,iEAAiE;AACjE,eAAO,MAAM,QAAQ;;;IAGnB,sHAAsH;;IAEtH,qFAAqF;;;;EAIrF,CAAC;AACH,MAAM,WAAW,QAAS,SAAQ,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,QAAQ,CAAC;CAAG;AAExE,0FAA0F;AAC1F,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;SAwB/B,CAAC;AAEH;;;GAGG;AACH,eAAO,MAAM,kBAAkB;;;;;SAe7B,CAAC;AAEH;;;;GAIG;AACH,eAAO,MAAM,4BAA4B,gBAAiB,WAAW,CAAC,WAAW,KAAG,MACP,CAAC"}

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

@@ -0,0 +1,35 @@
+import * as Schema from 'effect/Schema';
+import { ViewState } from '@dxos/react-ui-attention/types';
+/**
+ * The fields the pull request list can be ordered by. `relevance` ranks what needs the reader first
+ * (see `relevance`); `updated` and `created` are GitHub's times.
+ */
+export declare const SortField: Schema.Literals<readonly ["relevance", "updated", "created", "number", "title"]>;
+export type SortField = Schema.Schema.Type<typeof SortField>;
+export declare const SortDirection: Schema.Literals<readonly ["asc", "desc"]>;
+export type SortDirection = Schema.Schema.Type<typeof SortDirection>;
+export declare const Sort: Schema.Struct<{
+    readonly field: Schema.Literals<readonly ["relevance", "updated", "created", "number", "title"]>;
+    readonly direction: Schema.Literals<readonly ["asc", "desc"]>;
+}>;
+export type Sort = Schema.Schema.Type<typeof Sort>;
+/** The fields the list can be grouped by; `none` is one ungrouped list. */
+export declare const GroupField: Schema.Literals<readonly ["none", "repo", "state", "checks", "author"]>;
+export type GroupField = Schema.Schema.Type<typeof GroupField>;
+export declare const DEFAULT_SORT: Sort;
+export declare const View: Schema.Struct<{
+    readonly query: Schema.String;
+    readonly sort: Schema.optional<Schema.Struct<{
+        readonly field: Schema.Literals<readonly ["relevance", "updated", "created", "number", "title"]>;
+        readonly direction: Schema.Literals<readonly ["asc", "desc"]>;
+    }>>;
+    readonly group: Schema.optional<Schema.Literals<readonly ["none", "repo", "state", "checks", "author"]>>;
+}>;
+export type View = Schema.Schema.Type<typeof View>;
+/**
+ * How a reader has the space's pull requests arranged, keyed by the space and held per device
+ * (`local`), as a task set's list is: the filter, order and grouping are how this reader looks at the
+ * list here, not a property of the space every member would see.
+ */
+export declare const aspect: ViewState.Aspect<View>;
+//# sourceMappingURL=PullRequestsView.d.ts.map

package/dist/types/src/types/PullRequestsView.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PullRequestsView.d.ts","sourceRoot":"","sources":["../../../../src/types/PullRequestsView.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AAExC,OAAO,EAAE,SAAS,EAAE,MAAM,gCAAgC,CAAC;AAE3D;;;GAGG;AACH,eAAO,MAAM,SAAS,kFAA0E,CAAC;AACjG,MAAM,MAAM,SAAS,GAAG,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,SAAS,CAAC,CAAC;AAE7D,eAAO,MAAM,aAAa,2CAAmC,CAAC;AAC9D,MAAM,MAAM,aAAa,GAAG,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,aAAa,CAAC,CAAC;AAErE,eAAO,MAAM,IAAI;;;EAAgE,CAAC;AAClF,MAAM,MAAM,IAAI,GAAG,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,IAAI,CAAC,CAAC;AAEnD,2EAA2E;AAC3E,eAAO,MAAM,UAAU,yEAAiE,CAAC;AACzF,MAAM,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,UAAU,CAAC,CAAC;AAE/D,eAAO,MAAM,YAAY,EAAE,IAAgD,CAAC;AAE5E,eAAO,MAAM,IAAI;;;;;;;EAIf,CAAC;AACH,MAAM,MAAM,IAAI,GAAG,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,IAAI,CAAC,CAAC;AAEnD;;;;GAIG;AACH,eAAO,MAAM,MAAM,EAAE,SAAS,CAAC,MAAM,CAAC,IAAI,CAKxC,CAAC"}

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

@@ -0,0 +1,31 @@
+import { Obj, Type } from '@dxos/echo';
+import { PullRequest } from '@dxos/types';
+declare const Walkthrough_base: Type.ObjClass<Walkthrough, {
+    readonly pullRequest: import("@dxos/echo/internal").Ref<PullRequest.PullRequest & import("@dxos/echo/Entity").OfKind<import("@dxos/echo/internal").EntityKind.Object> & Obj.Unknown>;
+    readonly title?: string | undefined;
+    readonly body: string;
+    readonly commit: string;
+    readonly generatedAt?: string | undefined;
+    readonly model?: string | undefined;
+    readonly covered?: number | undefined;
+    readonly total?: number | undefined;
+}, {}>;
+/**
+ * A narrated reading of a pull request: one markdown document whose prose, headings and ```diff
+ * fences describe the change in the order a reviewer should meet it.
+ *
+ * Generated against ONE commit and stale the moment the branch moves, which is why `commit` is part
+ * of the record rather than something to infer — see {@link isStale}.
+ */
+export declare class Walkthrough extends Walkthrough_base {
+}
+/** Factory wrapper around `Obj.make` for {@link Walkthrough}. */
+export declare const make: (props: Obj.MakeProps<typeof Walkthrough>) => Walkthrough;
+/** Returns true when value is a Walkthrough object. */
+export declare const instanceOf: (value: unknown) => value is Walkthrough;
+/** The label a walkthrough of this pull request carries. */
+export declare const makeTitle: (pullRequest: PullRequest.PullRequest, title?: string) => string;
+/** Whether the walkthrough describes a commit other than the one given. */
+export declare const isStale: (walkthrough: Walkthrough, head: string) => boolean;
+export {};
+//# sourceMappingURL=Walkthrough.d.ts.map

package/dist/types/src/types/Walkthrough.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Walkthrough.d.ts","sourceRoot":"","sources":["../../../../src/types/Walkthrough.ts"],"names":[],"mappings":"AAQA,OAAO,EAA2B,GAAG,EAAO,IAAI,EAAE,MAAM,YAAY,CAAC;AACrE,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;;;;;;;;;;;AAE1C;;;;;;GAMG;AACH,qBAAa,WAAY,SAAQ,gBAkChC;CAAG;AAEJ,iEAAiE;AACjE,eAAO,MAAM,IAAI,UAAW,GAAG,CAAC,SAAS,CAAC,OAAO,WAAW,CAAC,KAAG,WAA2C,CAAC;AAE5G,uDAAuD;AACvD,eAAO,MAAM,UAAU,UAAW,OAAO,KAAG,KAAK,IAAI,WAAiD,CAAC;AAEvG,4DAA4D;AAC5D,eAAO,MAAM,SAAS,gBAAiB,WAAW,CAAC,WAAW,qBAA8B,MACzC,CAAC;AAEpD,2EAA2E;AAC3E,eAAO,MAAM,OAAO,gBAAiB,WAAW,QAAQ,MAAM,KAAG,OAAsC,CAAC"}

package/dist/types/src/types/Walkthrough.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=Walkthrough.test.d.ts.map

package/dist/types/src/types/Walkthrough.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Walkthrough.test.d.ts","sourceRoot":"","sources":["../../../../src/types/Walkthrough.test.ts"],"names":[],"mappings":""}

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

@@ -0,0 +1,5 @@
+export * as GitHubCapabilities from './GitHubCapabilities.ts';
+export * as GitHubEvents from './GitHubEvents.ts';
+export * as GitHubOperation from './GitHubOperation.ts';
+export * as Walkthrough from './Walkthrough.ts';
+//# sourceMappingURL=index.d.ts.map

package/dist/types/src/types/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/types/index.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,kBAAkB,MAAM,yBAAyB,CAAC;AAC9D,OAAO,KAAK,YAAY,MAAM,mBAAmB,CAAC;AAClD,OAAO,KAAK,eAAe,MAAM,sBAAsB,CAAC;AACxD,OAAO,KAAK,WAAW,MAAM,kBAAkB,CAAC"}

package/dist/types/src/walkthrough/fill.d.ts

@@ -0,0 +1,28 @@
+import { type PatchHunk } from './patch.ts';
+export type WalkthroughFill = {
+    body: string;
+    /** Hunks no fence claimed, in patch order — what the appended section covers. */
+    missed: {
+        path: string;
+        hunks: PatchHunk[];
+    }[];
+    /** Files the patch changed without changing any line: renames and mode changes. */
+    textless: string[];
+    /** Machine-written or binary files, named in the appendix rather than rendered. */
+    generated: string[];
+    /** Fences naming a file the patch does not contain; left in place with a note. */
+    unresolved: string[];
+    /** Hunks the body accounts for, over the patch's total. */
+    covered: number;
+    total: number;
+};
+/**
+ * Fills the walkthrough's empty diff fences from the pull request's own patch, then reports what the
+ * prose never mentioned.
+ *
+ * The model is asked for placeholders — a path and a line range — rather than diff content, because
+ * a model that transcribes a diff gets lines subtly wrong and the result is a review artefact that
+ * lies about the change. Here the bytes come from git and only the selection is the model's.
+ */
+export declare const fillWalkthrough: (body: string, patch: string) => WalkthroughFill;
+//# sourceMappingURL=fill.d.ts.map

package/dist/types/src/walkthrough/fill.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fill.d.ts","sourceRoot":"","sources":["../../../../src/walkthrough/fill.ts"],"names":[],"mappings":"AAKA,OAAO,EAAkB,KAAK,SAAS,EAAoD,MAAM,YAAY,CAAC;AAgB9G,MAAM,MAAM,eAAe,GAAG;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,iFAAiF;IACjF,MAAM,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,SAAS,EAAE,CAAA;KAAE,EAAE,CAAC;IAC/C,mFAAmF;IACnF,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,mFAAmF;IACnF,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,kFAAkF;IAClF,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,2DAA2D;IAC3D,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;CACf,CAAC;AAgFF;;;;;;;GAOG;AACH,eAAO,MAAM,eAAe,SAAU,MAAM,SAAS,MAAM,KAAG,eA4F7D,CAAC"}

package/dist/types/src/walkthrough/fill.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=fill.test.d.ts.map

package/dist/types/src/walkthrough/fill.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fill.test.d.ts","sourceRoot":"","sources":["../../../../src/walkthrough/fill.test.ts"],"names":[],"mappings":""}

package/dist/types/src/walkthrough/generate.d.ts

@@ -0,0 +1,67 @@
+import * as Effect from 'effect/Effect';
+import { Database } from '@dxos/echo';
+import { PullRequest } from '@dxos/types';
+import { Walkthrough } from '#types';
+/** What the pull request looks like on GitHub right now, as against the local mirror of it. */
+export type RemoteFacts = {
+    title?: string;
+    description?: string;
+    baseBranch?: string;
+    headBranch?: string;
+    /** Head SHA. Absent means the walkthrough cannot be pinned to a commit, so it is always stale. */
+    commit?: string;
+};
+export type GenerateOptions<R = never> = {
+    pullRequest: PullRequest.PullRequest;
+    remote: RemoteFacts;
+    /** The whole unified diff, which the chunks are filled from. */
+    diff: string;
+    /** Regenerate even where a walkthrough for this head already exists. */
+    force?: boolean;
+    /** Identifier recorded on the result, so a regression can be attributed after the default moves. */
+    model: string;
+    /**
+     * Runs the model over the prompt. Injected so the decision logic can be tested without one, and
+     * generic in its requirement so the model service it needs is DECLARED by the caller rather than
+     * quietly dropped — a requirement erased here is a defect at the first real invocation.
+     */
+    narrate: (prompt: string) => Effect.Effect<string, never, R>;
+    /** Phase reporter; `current` counts against {@link GENERATE_PHASES}. */
+    report?: (message: string, current: number) => void;
+    /**
+     * Diff size past which the walkthrough is planned into chapters and narrated a chapter at a time.
+     * Zero forces the two-stage path; `Infinity` forces the one-shot path.
+     */
+    chapterThresholdChars?: number;
+};
+export type GenerateResult = {
+    walkthrough: Walkthrough.Walkthrough;
+    /** How the body was written: one prompt, or a plan plus a prompt per chapter. */
+    strategy?: 'one-shot' | 'chaptered';
+    /** Whether the model ran, as against an existing walkthrough being returned unchanged. */
+    generated: boolean;
+    covered: number;
+    total: number;
+};
+/** Phases a caller's progress meter counts, so it is determinate rather than a spinner. */
+export declare const GENERATE_PHASES = 5;
+/**
+ * Decides whether to regenerate, runs the model, fills the chunks, and stores the result.
+ *
+ * Split from the operation handler so the part with the decisions in it can be tested against a real
+ * database without a network or a model: what the handler adds is two HTTP calls.
+ */
+export declare const generateWalkthrough: <R = never>({ pullRequest, remote, diff, force, model, narrate, report, chapterThresholdChars, }: GenerateOptions<R>) => Effect.Effect<GenerateResult, never, Database.Service | R>;
+/** The walkthrough already written for this pull request, if any. */
+export declare const findWalkthrough: (pullRequest: PullRequest.PullRequest) => Effect.Effect<Walkthrough.Walkthrough | undefined, never, Database.Service>;
+/**
+ * The newest of however many were written, ties broken by id.
+ *
+ * Two generations racing on one pull request both see none and both add: the check and the write
+ * are separate steps, and ECHO has neither a uniqueness constraint nor an atomic upsert to close
+ * that. Picking deterministically makes the duplicate inert instead — every reader lands on the
+ * same object, and the next regeneration updates that one in place rather than forking again. The
+ * loser stays in the space; removing it from a read path would delete another client's object.
+ */
+export declare const newestWalkthrough: (walkthroughs: readonly Walkthrough.Walkthrough[]) => Walkthrough.Walkthrough | undefined;
+//# sourceMappingURL=generate.d.ts.map

package/dist/types/src/walkthrough/generate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"generate.d.ts","sourceRoot":"","sources":["../../../../src/walkthrough/generate.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AAGxC,OAAO,EAAE,QAAQ,EAAoB,MAAM,YAAY,CAAC;AACxD,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE1C,OAAO,EAAE,WAAW,EAAE,MAAM,QAAQ,CAAC;AAkBrC,+FAA+F;AAC/F,MAAM,MAAM,WAAW,GAAG;IACxB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,kGAAkG;IAClG,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF,MAAM,MAAM,eAAe,CAAC,CAAC,GAAG,KAAK,IAAI;IACvC,WAAW,EAAE,WAAW,CAAC,WAAW,CAAC;IACrC,MAAM,EAAE,WAAW,CAAC;IACpB,gEAAgE;IAChE,IAAI,EAAE,MAAM,CAAC;IACb,wEAAwE;IACxE,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,oGAAoG;IACpG,KAAK,EAAE,MAAM,CAAC;IACd;;;;OAIG;IACH,OAAO,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC;IAC7D,wEAAwE;IACxE,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IACpD;;;OAGG;IACH,qBAAqB,CAAC,EAAE,MAAM,CAAC;CAChC,CAAC;AAEF,MAAM,MAAM,cAAc,GAAG;IAC3B,WAAW,EAAE,WAAW,CAAC,WAAW,CAAC;IACrC,iFAAiF;IACjF,QAAQ,CAAC,EAAE,UAAU,GAAG,WAAW,CAAC;IACpC,0FAA0F;IAC1F,SAAS,EAAE,OAAO,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;CACf,CAAC;AAEF,2FAA2F;AAC3F,eAAO,MAAM,eAAe,IAAI,CAAC;AAEjC;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,GAAI,CAAC,GAAG,KAAK,wFAS1C,eAAe,CAAC,CAAC,CAAC,KAAG,MAAM,CAAC,MAAM,CAAC,cAAc,EAAE,KAAK,EAAE,QAAQ,CAAC,OAAO,GAAG,CAAC,CAkD7E,CAAC;AAuCL,qEAAqE;AACrE,eAAO,MAAM,eAAe,gBACb,WAAW,CAAC,WAAW,KACnC,MAAM,CAAC,MAAM,CAAC,WAAW,CAAC,WAAW,GAAG,SAAS,EAAE,KAAK,EAAE,QAAQ,CAAC,OAAO,CAM1E,CAAC;AAEJ;;;;;;;;GAQG;AACH,eAAO,MAAM,iBAAiB,iBACd,SAAS,WAAW,CAAC,WAAW,EAAE,KAC/C,WAAW,CAAC,WAAW,GAAG,SAad,CAAC"}

package/dist/types/src/walkthrough/generate.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=generate.test.d.ts.map

package/dist/types/src/walkthrough/generate.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"generate.test.d.ts","sourceRoot":"","sources":["../../../../src/walkthrough/generate.test.ts"],"names":[],"mappings":""}

package/dist/types/src/walkthrough/generated.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Whether a path is machine-written or unreadable.
+ *
+ * `.changeset/` entries count: the changeset is a consequence of the change the walkthrough already
+ * describes, and a section about it tells the reader nothing the rest of the document did not.
+ */
+export declare const isGeneratedPath: (path: string) => boolean;
+/** A file git could not diff as text, whatever its extension says. */
+export declare const isBinaryPatch: (preamble: readonly string[]) => boolean;
+/**
+ * Whether this file is one the walkthrough should leave alone.
+ *
+ * A hunk count of zero is NOT generated on its own: a rename or a mode change is still a change a
+ * reviewer has to know about, and {@link fillWalkthrough} reports it separately.
+ */
+export declare const isGeneratedFile: (file: {
+    path: string;
+    preamble: readonly string[];
+}) => boolean;
+//# sourceMappingURL=generated.d.ts.map

package/dist/types/src/walkthrough/generated.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"generated.d.ts","sourceRoot":"","sources":["../../../../src/walkthrough/generated.ts"],"names":[],"mappings":"AAwCA;;;;;GAKG;AACH,eAAO,MAAM,eAAe,SAAU,MAAM,KAAG,OAU9C,CAAC;AAEF,sEAAsE;AACtE,eAAO,MAAM,aAAa,aAAc,SAAS,MAAM,EAAE,KAAG,OACsC,CAAC;AAEnG;;;;;GAKG;AACH,eAAO,MAAM,eAAe,SAAU;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,KAAG,OAC1B,CAAC"}

package/dist/types/src/walkthrough/generated.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=generated.test.d.ts.map

package/dist/types/src/walkthrough/generated.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"generated.test.d.ts","sourceRoot":"","sources":["../../../../src/walkthrough/generated.test.ts"],"names":[],"mappings":""}

package/dist/types/src/walkthrough/headings.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Puts a blank line before every heading outside a code fence.
+ *
+ * A heading may legally interrupt a paragraph, so the model and the chapter join both emit one on
+ * the very next line — which the walkthrough's source-level editor shows flush against the prose.
+ */
+export declare const spaceHeadings: (markdown: string) => string;
+//# sourceMappingURL=headings.d.ts.map

package/dist/types/src/walkthrough/headings.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"headings.d.ts","sourceRoot":"","sources":["../../../../src/walkthrough/headings.ts"],"names":[],"mappings":"AASA;;;;;GAKG;AACH,eAAO,MAAM,aAAa,aAAc,MAAM,KAAG,MAuBhD,CAAC"}

package/dist/types/src/walkthrough/headings.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=headings.test.d.ts.map

package/dist/types/src/walkthrough/headings.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"headings.test.d.ts","sourceRoot":"","sources":["../../../../src/walkthrough/headings.test.ts"],"names":[],"mappings":""}

package/dist/types/src/walkthrough/index.d.ts

@@ -0,0 +1,9 @@
+export * from './fill.ts';
+export * from './generate.ts';
+export * from './generated.ts';
+export * from './headings.ts';
+export * from './patch.ts';
+export * from './plan.ts';
+export * from './prompt.ts';
+export * from './score.ts';
+//# sourceMappingURL=index.d.ts.map

package/dist/types/src/walkthrough/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/walkthrough/index.ts"],"names":[],"mappings":"AAIA,cAAc,WAAW,CAAC;AAC1B,cAAc,eAAe,CAAC;AAC9B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,eAAe,CAAC;AAC9B,cAAc,YAAY,CAAC;AAC3B,cAAc,WAAW,CAAC;AAC1B,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC"}

package/dist/types/src/walkthrough/patch.d.ts

@@ -0,0 +1,48 @@
+/** A `@@` hunk, kept as the verbatim lines git emitted so filling a chunk is lossless. */
+export type PatchHunk = {
+    /** The `@@ -a,b +c,d @@ section` line. */
+    header: string;
+    /** Body lines (context, additions, removals), without the header. */
+    lines: string[];
+    /** 1-based inclusive span in the file AFTER the change; `afterEnd < afterStart` for a pure removal. */
+    afterStart: number;
+    afterEnd: number;
+    /** The same span in the file BEFORE it, which is all a pure removal has. */
+    beforeStart: number;
+    beforeEnd: number;
+    added: number;
+    removed: number;
+};
+export type PatchFile = {
+    /** Path after the change, or the pre-image path when the file was deleted. */
+    path: string;
+    /** Headers git emitted before the first hunk (`diff --git`, `index`, `---`, `+++`). */
+    preamble: string[];
+    hunks: PatchHunk[];
+    added: number;
+    removed: number;
+};
+/**
+ * Splits a multi-file unified diff — what `GET /repos/…/pulls/N` returns under the `diff` media type
+ * — into files and hunks. Hunk bodies are carried verbatim rather than re-derived, so a chunk filled
+ * from one is byte-identical to what git produced.
+ */
+export declare const parsePatch: (patch: string) => PatchFile[];
+/** The hunk text a diff fence holds: the `@@` header and its body, as git wrote them. */
+export declare const renderHunks: (hunks: PatchHunk[]) => string;
+/**
+ * Whether a hunk shows any of `[start, end]` of the post-change file.
+ *
+ * A pure removal spans nothing after the change (`afterEnd === afterStart - 1`), so it is treated as
+ * occupying the single position the lines were removed from — otherwise no range could ever select
+ * it, including the one this module's own {@link hunkRange} reports for it.
+ */
+export declare const hunkOverlaps: (hunk: PatchHunk, start: number, end: number) => boolean;
+/**
+ * The span a set of hunks covers, for a fence's `lines=` attribute.
+ *
+ * Measured after the change, except where nothing survives it: a deleted file's post-image is empty
+ * and would otherwise read as `Lines 0`, so its range is quoted from the pre-image instead.
+ */
+export declare const hunkRange: (hunks: PatchHunk[]) => string | undefined;
+//# sourceMappingURL=patch.d.ts.map

package/dist/types/src/walkthrough/patch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"patch.d.ts","sourceRoot":"","sources":["../../../../src/walkthrough/patch.ts"],"names":[],"mappings":"AAIA,0FAA0F;AAC1F,MAAM,MAAM,SAAS,GAAG;IACtB,0CAA0C;IAC1C,MAAM,EAAE,MAAM,CAAC;IACf,qEAAqE;IACrE,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,uGAAuG;IACvG,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,4EAA4E;IAC5E,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF,MAAM,MAAM,SAAS,GAAG;IACtB,8EAA8E;IAC9E,IAAI,EAAE,MAAM,CAAC;IACb,uFAAuF;IACvF,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,KAAK,EAAE,SAAS,EAAE,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;CACjB,CAAC;AAKF;;;;GAIG;AACH,eAAO,MAAM,UAAU,UAAW,MAAM,KAAG,SAAS,EAmFnD,CAAC;AAEF,yFAAyF;AACzF,eAAO,MAAM,WAAW,UAAW,SAAS,EAAE,KAAG,MACwB,CAAC;AAE1E;;;;;;GAMG;AACH,eAAO,MAAM,YAAY,SAAU,SAAS,SAAS,MAAM,OAAO,MAAM,KAAG,OACE,CAAC;AAE9E;;;;;GAKG;AACH,eAAO,MAAM,SAAS,UAAW,SAAS,EAAE,KAAG,MAAM,GAAG,SAUvD,CAAC"}