@jitsusama/agentic-harness.core 0.1.0

package/dist/review/draft/publish.js

@@ -0,0 +1,118 @@
+/**
+ * Running a plan, honestly.
+ *
+ * Publishing a review is several requests, and the interesting
+ * case is the one where some of them work. A posted review
+ * with one failed reply is not a failure to report as "could
+ * not publish", because the review is now on the change and
+ * saying otherwise would have someone post it twice. So every
+ * operation reports its own outcome, execution continues past
+ * a failure, and the caller learns exactly which items landed.
+ */
+/** The message an unusable error becomes. */
+function messageOf(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+/** Every operation failed for the same reason. */
+function allFailed(plan, error) {
+    return {
+        ok: false,
+        outcomes: plan.ops.map((op) => ({
+            op,
+            ok: false,
+            itemIds: op.itemIds,
+            error,
+        })),
+    };
+}
+/**
+ * Perform one operation. Returns what the provider handed
+ * back, or throws for the caller to record.
+ */
+async function perform(op, provider, change) {
+    const conversation = provider.conversation;
+    if (!conversation) {
+        throw new Error(`the ${provider.id} provider has no conversation facet`);
+    }
+    if (op.kind === "review") {
+        return conversation.postReview(change, {
+            verdict: op.verdict,
+            body: op.body,
+            comments: op.comments,
+        });
+    }
+    if (op.kind === "comment") {
+        return conversation.comment(change, op.body);
+    }
+    if (op.kind === "commentOn") {
+        if (!conversation.commentOn) {
+            // The planner only makes one of these for a provider declaring
+            // `fileLevelComments: "standalone"`, which is a promise of this
+            // method, so reaching here means the declaration was wrong. Said
+            // plainly rather than swallowed: the remark is in the draft still,
+            // and publishing again after the provider is fixed will send it.
+            throw new Error(`the ${provider.id} provider says a remark about a whole file has to be posted on its own, and then offers no way to post one`);
+        }
+        return conversation.commentOn(change, op.comment.anchor, op.comment.body);
+    }
+    if (op.kind === "reply") {
+        return conversation.reply(change, op.thread, op.body);
+    }
+    if (op.kind === "resolve") {
+        await conversation.resolve(change, op.thread);
+        return undefined;
+    }
+    if (op.kind === "unresolve") {
+        if (!conversation.unresolve) {
+            throw new Error(`the ${provider.id} provider cannot reopen a resolved thread`);
+        }
+        await conversation.unresolve(change, op.thread);
+        return undefined;
+    }
+    if (!conversation.react) {
+        throw new Error(`the ${provider.id} provider cannot post reactions`);
+    }
+    await conversation.react(change, op.subject, op.reaction);
+    return undefined;
+}
+/**
+ * Run a compiled plan against a provider.
+ *
+ * Operations run in the order the plan puts them and a
+ * failure does not stop the ones after it, because the
+ * alternative is a review posted with half its replies
+ * missing and no record of which half.
+ */
+export async function publishPlan(plan, provider) {
+    if (plan.ops.length === 0)
+        return { ok: true, outcomes: [] };
+    if (plan.target.kind !== "proposal") {
+        return allFailed(plan, "this target is not hosted anywhere, so there is no change " +
+            "to publish to; render the review as a document instead");
+    }
+    if (!provider.conversation) {
+        return allFailed(plan, `the ${provider.id} provider has no conversation facet`);
+    }
+    const change = plan.target.change;
+    const outcomes = [];
+    for (const op of plan.ops) {
+        try {
+            const posted = await perform(op, provider, change);
+            outcomes.push({
+                op,
+                ok: true,
+                itemIds: op.itemIds,
+                ...(posted ? { posted } : {}),
+            });
+        }
+        catch (error) {
+            outcomes.push({
+                op,
+                ok: false,
+                itemIds: op.itemIds,
+                error: messageOf(error),
+            });
+        }
+    }
+    return { ok: outcomes.every((entry) => entry.ok), outcomes };
+}

package/dist/review/draft/render.d.ts

@@ -0,0 +1,32 @@
+/**
+ * A review with nowhere to post, written down.
+ *
+ * Reviewing a stack of branches nobody has proposed is a real
+ * activity, and the fact that no server will accept the result
+ * does not make the result worthless. So a draft can always
+ * become a document: the summary, the remarks grouped by the
+ * file they are about, and the verdict recorded the way git
+ * records a verdict, as a trailer.
+ *
+ * The trailer vocabulary is borrowed rather than invented.
+ * `Reviewed-by` is what a reviewer stamps on work they accept
+ * and `Nacked-by` is the long-standing way to record an
+ * objection; a review that takes no position gets no trailer,
+ * because that is what taking no position means.
+ */
+import type { Actor } from "../change.js";
+import type { DraftState } from "./state.js";
+/** Who is reviewing, and anything else the document needs. */
+export interface RenderOptions {
+    /** The reviewer, for the verdict trailer. */
+    author?: Actor;
+}
+/** A review, written out. */
+export interface ReviewDocument {
+    title: string;
+    markdown: string;
+    /** Trailers recording the verdict, ready to append. */
+    trailers: string[];
+}
+/** Render a draft as a document. */
+export declare function renderDraft(state: DraftState, options?: RenderOptions): ReviewDocument;

package/dist/review/draft/render.js

@@ -0,0 +1,100 @@
+/**
+ * A review with nowhere to post, written down.
+ *
+ * Reviewing a stack of branches nobody has proposed is a real
+ * activity, and the fact that no server will accept the result
+ * does not make the result worthless. So a draft can always
+ * become a document: the summary, the remarks grouped by the
+ * file they are about, and the verdict recorded the way git
+ * records a verdict, as a trailer.
+ *
+ * The trailer vocabulary is borrowed rather than invented.
+ * `Reviewed-by` is what a reviewer stamps on work they accept
+ * and `Nacked-by` is the long-standing way to record an
+ * objection; a review that takes no position gets no trailer,
+ * because that is what taking no position means.
+ */
+import { anchorPath } from "../anchor.js";
+import { bullet } from "./continuation.js";
+/** How to name what was reviewed. */
+function describeTarget(target) {
+    if (target.kind === "proposal") {
+        return `${target.change.repo.key} ${target.change.id}`;
+    }
+    if (target.kind === "range") {
+        return `${target.base}..${target.head}`;
+    }
+    return target.refs.join(", ");
+}
+/** Where in a file a remark points. */
+function describeLocation(anchor) {
+    if (anchor.subject === "change")
+        return "the change as a whole";
+    if (anchor.subject === "file")
+        return "the file as a whole";
+    const lines = anchor.startLine && anchor.startLine !== anchor.line
+        ? `${anchor.startLine}-${anchor.line}`
+        : `${anchor.line}`;
+    return `line ${lines} (${anchor.blob})`;
+}
+/** Findings in file order, each file keeping its own order. */
+function groupByFile(findings) {
+    const grouped = new Map();
+    for (const finding of findings) {
+        // A remark about the change names no file, so it groups
+        // under a heading of its own rather than under one.
+        const path = anchorPath(finding.anchor) ?? "the change as a whole";
+        const existing = grouped.get(path);
+        if (existing)
+            existing.push(finding);
+        else
+            grouped.set(path, [finding]);
+    }
+    return grouped;
+}
+/** How the reviewer is named in a trailer. */
+function nameFor(author) {
+    return author.name ? `${author.name} <${author.id}>` : author.id;
+}
+/**
+ * The trailers recording a verdict. Approval and objection
+ * both have long-standing spellings; taking no position has
+ * no trailer, which is the point of taking no position.
+ */
+function verdictTrailers(state, author) {
+    if (!author || !state.verdict)
+        return [];
+    if (state.verdict === "approve")
+        return [`Reviewed-by: ${nameFor(author)}`];
+    if (state.verdict === "request-changes") {
+        return [`Nacked-by: ${nameFor(author)}`];
+    }
+    return [];
+}
+/** Render a draft as a document. */
+export function renderDraft(state, options) {
+    const subject = describeTarget(state.target);
+    const title = `Review of ${subject}`;
+    const trailers = verdictTrailers(state, options?.author);
+    const sections = [`# ${title}`];
+    if (state.summary)
+        sections.push(state.summary);
+    const findings = state.items.filter((item) => item.kind === "finding");
+    for (const [path, forFile] of groupByFile(findings)) {
+        const remarks = forFile.map((finding) => bullet(describeLocation(finding.anchor), finding.body));
+        sections.push(`## ${path}`, remarks.join("\n"));
+    }
+    const replies = state.items.filter((item) => item.kind === "reply");
+    if (replies.length > 0) {
+        const lines = replies.map((item) => item.kind === "reply"
+            ? bullet(`in reply to ${item.thread.id}`, item.body)
+            : "");
+        sections.push("## Replies", lines.join("\n"));
+    }
+    if (findings.length === 0 && replies.length === 0 && !state.summary) {
+        sections.push("No remarks.");
+    }
+    if (trailers.length > 0)
+        sections.push(trailers.join("\n"));
+    return { title, markdown: `${sections.join("\n\n")}\n`, trailers };
+}

package/dist/review/draft/state.d.ts

@@ -0,0 +1,98 @@
+/**
+ * What a review session accumulates.
+ *
+ * A person's review is not what a forge calls a review. It
+ * mixes new anchored remarks with replies into threads
+ * somebody else started, resolutions, reactions and a
+ * verdict, and no backend accepts that mixture as one
+ * operation. So the mixture is held here, addressable and
+ * serializable, and the work of turning it into whatever the
+ * backend will accept happens later, once and visibly.
+ *
+ * The state is plain data and every operation returns a new
+ * one. That is what lets a draft be persisted after each
+ * change, rendered without a provider, and tested without
+ * either.
+ */
+import type { Anchor } from "../anchor.js";
+import type { ReviewTarget } from "../change.js";
+import type { Message, Reaction, Thread, Verdict } from "../conversation.js";
+/** A new anchored remark. */
+export interface FindingItem {
+    kind: "finding";
+    id: string;
+    anchor: Anchor;
+    body: string;
+}
+/** A reply into a thread that already exists. */
+export interface ReplyItem {
+    kind: "reply";
+    id: string;
+    /** The whole thread: providers key replies differently. */
+    thread: Thread;
+    body: string;
+}
+/** A resolution of a thread that already exists. */
+export interface ResolutionItem {
+    kind: "resolution";
+    id: string;
+    thread: Thread;
+}
+/**
+ * A reopening of a thread that is currently resolved.
+ *
+ * Mirrors the resolution rather than adding a flag to it, so the plan
+ * compiler branches on a kind the way it does for every other item, and
+ * so a draft can express everything `review_say` can. It could close a
+ * thread and not open one, and that asymmetry is the shape of bug this
+ * work came out of.
+ */
+export interface UnresolutionItem {
+    kind: "unresolution";
+    id: string;
+    thread: Thread;
+}
+/** A reaction to a message. */
+export interface ReactionItem {
+    kind: "reaction";
+    id: string;
+    subject: Message;
+    reaction: Reaction;
+}
+/** One thing the review will do. */
+export type DraftItem = FindingItem | ReplyItem | ResolutionItem | UnresolutionItem | ReactionItem;
+/** A review being composed. */
+export interface DraftState {
+    id: string;
+    target: ReviewTarget;
+    items: DraftItem[];
+    verdict?: Verdict;
+    /** The summary that accompanies the verdict. */
+    summary?: string;
+    createdAt: string;
+    updatedAt: string;
+    /**
+     * Highest item number handed out so far. Ids stay stable
+     * across removals, so this only ever climbs.
+     */
+    lastNumber: number;
+}
+/** A fresh draft about a target. */
+export declare function emptyDraft(id: string, target: ReviewTarget): DraftState;
+/** Add a new anchored remark. */
+export declare function addFinding(state: DraftState, finding: {
+    anchor: Anchor;
+    body: string;
+}): DraftState;
+/** Add a reply into an existing thread. */
+export declare function addReply(state: DraftState, thread: Thread, body: string): DraftState;
+/** Mark an existing thread to be resolved. */
+export declare function addResolution(state: DraftState, thread: Thread): DraftState;
+/** Mark an existing thread to be reopened. */
+export declare function addUnresolution(state: DraftState, thread: Thread): DraftState;
+/** React to a message. */
+export declare function addReaction(state: DraftState, subject: Message, reaction: Reaction): DraftState;
+/** Choose the verdict and its summary. */
+export declare function setVerdict(state: DraftState, verdict: Verdict, summary?: string): DraftState;
+/** Drop an item by id. Ignores an id that is not there. */
+export declare function removeItem(state: DraftState, id: string): DraftState;

package/dist/review/draft/state.js

@@ -0,0 +1,83 @@
+/**
+ * What a review session accumulates.
+ *
+ * A person's review is not what a forge calls a review. It
+ * mixes new anchored remarks with replies into threads
+ * somebody else started, resolutions, reactions and a
+ * verdict, and no backend accepts that mixture as one
+ * operation. So the mixture is held here, addressable and
+ * serializable, and the work of turning it into whatever the
+ * backend will accept happens later, once and visibly.
+ *
+ * The state is plain data and every operation returns a new
+ * one. That is what lets a draft be persisted after each
+ * change, rendered without a provider, and tested without
+ * either.
+ */
+/** A fresh draft about a target. */
+export function emptyDraft(id, target) {
+    const now = new Date().toISOString();
+    return {
+        id,
+        target,
+        items: [],
+        createdAt: now,
+        updatedAt: now,
+        lastNumber: 0,
+    };
+}
+/**
+ * Append an item, handing it the next number. Numbers are
+ * never reused, so a finding a person referred to by number
+ * keeps that number even after an earlier one is dropped.
+ */
+function append(state, build) {
+    const next = state.lastNumber + 1;
+    return {
+        ...state,
+        items: [...state.items, build(String(next))],
+        lastNumber: next,
+        updatedAt: new Date().toISOString(),
+    };
+}
+/** Add a new anchored remark. */
+export function addFinding(state, finding) {
+    return append(state, (id) => ({
+        kind: "finding",
+        id,
+        anchor: finding.anchor,
+        body: finding.body,
+    }));
+}
+/** Add a reply into an existing thread. */
+export function addReply(state, thread, body) {
+    return append(state, (id) => ({ kind: "reply", id, thread, body }));
+}
+/** Mark an existing thread to be resolved. */
+export function addResolution(state, thread) {
+    return append(state, (id) => ({ kind: "resolution", id, thread }));
+}
+/** Mark an existing thread to be reopened. */
+export function addUnresolution(state, thread) {
+    return append(state, (id) => ({ kind: "unresolution", id, thread }));
+}
+/** React to a message. */
+export function addReaction(state, subject, reaction) {
+    return append(state, (id) => ({ kind: "reaction", id, subject, reaction }));
+}
+/** Choose the verdict and its summary. */
+export function setVerdict(state, verdict, summary) {
+    return {
+        ...state,
+        verdict,
+        summary,
+        updatedAt: new Date().toISOString(),
+    };
+}
+/** Drop an item by id. Ignores an id that is not there. */
+export function removeItem(state, id) {
+    const items = state.items.filter((item) => item.id !== id);
+    if (items.length === state.items.length)
+        return state;
+    return { ...state, items, updatedAt: new Date().toISOString() };
+}

package/dist/review/draft/store.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Where drafts live between sessions.
+ *
+ * A review is composed over hours, sometimes across a
+ * restart, and the substrate owns that storage rather than
+ * leaving each consumer to invent its own. One flat directory
+ * of JSON files, each holding a whole draft: legible to a
+ * person who goes looking, cheap to list, and with no index to
+ * fall out of step with the files it describes.
+ */
+import type { ReviewTarget } from "../change.js";
+import type { Verdict } from "../conversation.js";
+import type { DraftState } from "./state.js";
+/** Enough of a draft to choose between them. */
+export interface DraftSummary {
+    id: string;
+    target: ReviewTarget;
+    /** How many things the review will do. */
+    itemCount: number;
+    verdict?: Verdict;
+    updatedAt: string;
+}
+/** Durable home for drafts. */
+export interface DraftStore {
+    save(state: DraftState): Promise<void>;
+    load(id: string): Promise<DraftState | undefined>;
+    /** Newest first. */
+    list(): Promise<DraftSummary[]>;
+    forTarget(target: ReviewTarget): Promise<DraftSummary[]>;
+    remove(id: string): Promise<void>;
+}
+/** Open a store rooted at a directory. */
+export declare function createDraftStore(root: string): DraftStore;

package/dist/review/draft/store.js

@@ -0,0 +1,100 @@
+/**
+ * Where drafts live between sessions.
+ *
+ * A review is composed over hours, sometimes across a
+ * restart, and the substrate owns that storage rather than
+ * leaving each consumer to invent its own. One flat directory
+ * of JSON files, each holding a whole draft: legible to a
+ * person who goes looking, cheap to list, and with no index to
+ * fall out of step with the files it describes.
+ */
+import { mkdir, readdir, readFile, rm, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { targetKey } from "../keys.js";
+/**
+ * File name for a draft. The id is folded to something safe
+ * so an id carrying a slash or a pair of dots cannot name a
+ * path outside the store.
+ */
+function fileFor(id) {
+    const safe = id.replace(/[^A-Za-z0-9._-]/g, "_").replace(/^\.+/, "_");
+    return `${safe}.json`;
+}
+/** Read and parse one draft, or nothing if it is unreadable. */
+async function readDraft(path) {
+    try {
+        const text = await readFile(path, "utf8");
+        const parsed = JSON.parse(text);
+        if (!isDraftState(parsed))
+            return undefined;
+        return parsed;
+    }
+    catch {
+        // A missing file is the common case, and a half-written
+        // or hand-edited one should not take the listing down.
+        return undefined;
+    }
+}
+/** Whether parsed JSON has the shape of a draft. */
+function isDraftState(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const candidate = value;
+    return (typeof candidate.id === "string" &&
+        typeof candidate.updatedAt === "string" &&
+        Array.isArray(candidate.items) &&
+        typeof candidate.target === "object" &&
+        candidate.target !== null);
+}
+/** The summary of a draft. */
+function summarize(state) {
+    return {
+        id: state.id,
+        target: state.target,
+        itemCount: state.items.length,
+        ...(state.verdict ? { verdict: state.verdict } : {}),
+        updatedAt: state.updatedAt,
+    };
+}
+/** Open a store rooted at a directory. */
+export function createDraftStore(root) {
+    async function everyDraft() {
+        let names;
+        try {
+            names = await readdir(root);
+        }
+        catch {
+            // Nothing has been saved yet, so there is no directory.
+            return [];
+        }
+        const drafts = await Promise.all(names
+            .filter((name) => name.endsWith(".json"))
+            .map((name) => readDraft(join(root, name))));
+        return drafts.filter((draft) => draft !== undefined);
+    }
+    async function summaries() {
+        const drafts = await everyDraft();
+        return drafts
+            .map(summarize)
+            .sort((a, b) => b.updatedAt.localeCompare(a.updatedAt));
+    }
+    return {
+        async save(state) {
+            await mkdir(root, { recursive: true });
+            const path = join(root, fileFor(state.id));
+            await writeFile(path, `${JSON.stringify(state, null, "\t")}\n`, "utf8");
+        },
+        async load(id) {
+            return readDraft(join(root, fileFor(id)));
+        },
+        list: summaries,
+        async forTarget(target) {
+            const key = targetKey(target);
+            const all = await summaries();
+            return all.filter((entry) => targetKey(entry.target) === key);
+        },
+        async remove(id) {
+            await rm(join(root, fileFor(id)), { force: true });
+        },
+    };
+}

package/dist/review/elsewhere.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Whether a checkout and the repo in play are two different places.
+ *
+ * The comparison only. Each caller phrases its own sentence, because
+ * the same fact means different things: proposing a branch into
+ * another repo cannot work at all, while listing another repo's
+ * changes works perfectly and answers the wrong question.
+ */
+/**
+ * Both names when the checkout's remote and the repo key disagree, or
+ * undefined when they agree or when there is nothing to compare.
+ *
+ * Silent where silence is right: a local repo names no remote it
+ * could have meant instead, a checkout with no origin gives nothing
+ * to compare, and a trailing `.git`, a trailing slash or a difference
+ * of case are spellings rather than differences.
+ *
+ * The remote comes back without its credential, because this pair is
+ * only ever built to be said out loud. A remote that authenticates
+ * inline puts a token where a username goes, and a refusal naming it
+ * would print that token into the transcript, into any log kept of
+ * it, and into whatever the person reading it pastes somewhere else.
+ */
+export declare function repoElsewhere(checkoutRemote: string | undefined, repoKey: string): {
+    checkout: string;
+    repo: string;
+} | undefined;

package/dist/review/elsewhere.js

@@ -0,0 +1,39 @@
+/**
+ * Whether a checkout and the repo in play are two different places.
+ *
+ * The comparison only. Each caller phrases its own sentence, because
+ * the same fact means different things: proposing a branch into
+ * another repo cannot work at all, while listing another repo's
+ * changes works perfectly and answers the wrong question.
+ */
+import { withoutCredentials } from "../remote/index.js";
+/**
+ * Both names when the checkout's remote and the repo key disagree, or
+ * undefined when they agree or when there is nothing to compare.
+ *
+ * Silent where silence is right: a local repo names no remote it
+ * could have meant instead, a checkout with no origin gives nothing
+ * to compare, and a trailing `.git`, a trailing slash or a difference
+ * of case are spellings rather than differences.
+ *
+ * The remote comes back without its credential, because this pair is
+ * only ever built to be said out loud. A remote that authenticates
+ * inline puts a token where a username goes, and a refusal naming it
+ * would print that token into the transcript, into any log kept of
+ * it, and into whatever the person reading it pastes somewhere else.
+ */
+export function repoElsewhere(checkoutRemote, repoKey) {
+    // A key is provider:slug, and a slug may contain a colon of its
+    // own, so the split is on the first one with the rest rejoined.
+    const slug = repoKey.split(":").slice(1).join(":");
+    if (slug === "" || repoKey.startsWith("local:"))
+        return undefined;
+    if (!checkoutRemote || checkoutRemote === "")
+        return undefined;
+    const tidied = withoutCredentials(checkoutRemote)
+        .replace(/\.git$/, "")
+        .replace(/\/$/, "");
+    if (tidied.toLowerCase().includes(slug.toLowerCase()))
+        return undefined;
+    return { checkout: tidied, repo: repoKey };
+}