@andrioid/paseo-attention-span 0.0.0-stage → 0.1.1

package/shared/config.ts

@@ -0,0 +1,62 @@
+import { z } from "zod";
+
+// Session types, each with its own prompt template and profile lookup.
+export const SessionKind = z.enum(["review", "fix", "address", "rebase", "refresh", "start"]);
+export type SessionKind = z.infer<typeof SessionKind>;
+
+export const MergeMethod = z.enum(["squash", "merge", "rebase"]);
+export type MergeMethod = z.infer<typeof MergeMethod>;
+
+// An org issue field and how its values rank; values match by name, so "Small" matches "🐇 Small (0.5-2d)".
+const RankedField = z.object({
+  field: z.string(),
+  // Best first. Without it, the field's own option order applies.
+  order: z.array(z.string()).optional(),
+});
+
+// ~/.config/paseo-attention-span/config.json, edited by hand [SRC-01].
+export const AttentionConfig = z.object({
+  // GitHub orgs and "owner/name" repos to cover. Both empty means everything involving me.
+  orgs: z.array(z.string()).default([]),
+  repos: z.array(z.string()).default([]),
+  // Agent profile name per session type. A missing profile falls back to "default",
+  // then to Paseo's defaults [SES-06].
+  profiles: z
+    .object({ default: z.string().default("default") })
+    .catchall(z.string())
+    .default({ default: "default", review: "review" }),
+  // Replaces a built-in prompt template [SES-04].
+  prompts: z.partialRecord(SessionKind, z.string()).default({}),
+  // Where an issue repo's code lives, "owner/name" -> "owner/name", for issues kept apart from the code [SES-07].
+  codeRepos: z.record(z.string(), z.string()).default({}),
+  // Merge method per "owner/name" [PRS-04].
+  mergeMethods: z.record(z.string(), MergeMethod).default({}),
+  waitingTooLongDays: z.number().positive().default(3),
+  // A digest, not a live view: GitHub is asked at most this often unless I press ⟳ [GH-01].
+  refreshMinutes: z.number().min(5).default(15),
+  staleDraftDays: z.number().positive().default(30),
+  mentionDays: z.number().positive().default(30),
+  // How many weeks History shows [HIS-01].
+  historyWeeks: z.number().int().positive().default(4),
+  // Unclaimed issues to pick from [NXT-04]. Repos default to `orgs` and `repos`.
+  nextUp: z
+    .object({
+      repos: z.array(z.string()).optional(),
+      priority: RankedField.optional(),
+      effort: RankedField.optional(),
+      scope: z.object({ field: z.string() }).optional(),
+    })
+    .default({}),
+});
+export type AttentionConfig = z.infer<typeof AttentionConfig>;
+
+// "owner/name" of a Paseo project with a GitHub remote, from its project key.
+export function githubRepoOf(projectKey: string | null | undefined): string | null {
+  return /^remote:github\.com\/(.+)$/i.exec(projectKey ?? "")?.[1] ?? null;
+}
+
+// The repository whose checkout a session on an issue from `repo` works in [SES-07].
+export function codeRepoFor(config: Pick<AttentionConfig, "codeRepos">, repo: string): string {
+  const mapped = Object.entries(config.codeRepos).find(([issues]) => issues.toLowerCase() === repo.toLowerCase());
+  return mapped?.[1] ?? repo;
+}

package/shared/format.ts

@@ -0,0 +1,16 @@
+// "5m", "3h", "4d", "2 months": how long ago an ISO timestamp was.
+export function ago(iso: string, now: Date = new Date()): string {
+  const minutes = Math.max(0, Math.floor((now.getTime() - new Date(iso).getTime()) / 60_000));
+  if (minutes < 60) return `${minutes}m`;
+  const hours = Math.floor(minutes / 60);
+  if (hours < 24) return `${hours}h`;
+  const days = Math.floor(hours / 24);
+  if (days < 60) return `${days}d`;
+  const months = Math.floor(days / 30);
+  if (months < 24) return `${months} months`;
+  return `${Math.floor(days / 365)} years`;
+}
+
+export function daysSince(iso: string, now: Date): number {
+  return (now.getTime() - new Date(iso).getTime()) / 86_400_000;
+}

package/shared/prompts.ts

@@ -0,0 +1,89 @@
+import type { ActionId, Target } from "./attention";
+import type { AttentionConfig, SessionKind } from "./config";
+
+// Built-in prompt templates [SES-04]. A template in config.json replaces one.
+// Placeholders: {{repo}} {{number}} {{title}} {{url}} {{head}} {{base}} {{stack}} {{context}}
+export const PROMPT_TEMPLATES: Record<SessionKind, string> = {
+  review: `Review pull request {{repo}}#{{number}}: "{{title}}" ({{url}}). You are in a checkout of the PR branch.
+
+1. Review: read the description and the diff against {{base}}.
+2. Investigate: dig into anything risky or unclear in the code it touches.
+3. Browser sweep, only if you're equipped to (you can run this repo's app and have browser tools): work out which pages and screens the change affects and check each one. If you can't, skip this and say so. Don't spend the session getting the app to run.
+4. Report back:
+   - Findings, most important first.
+   - Verdict: approve, request changes or comment, with a one-line reason.
+   - Draft review comments, ready to paste, each with file:line.
+
+Do not post anything to GitHub.
+
+{{context}}`,
+
+  fix: `The checks on pull request {{repo}}#{{number}} "{{title}}" ({{url}}) are failing.
+
+Find the cause and fix it on branch {{head}}. Run the relevant checks locally. Commit, but do not push: tell me what you changed and wait for me.
+
+{{context}}`,
+
+  address: `Pull request {{repo}}#{{number}} "{{title}}" ({{url}}) has review comments. You are on branch {{head}}.
+
+Evaluate each comment: is it right, and what would fixing it take?
+- If the fix is trivial, apply it. Trivial means no behavior change: typos, naming, comments, formatting, or a small refactor the reviewer spelled out. Commit, but don't push.
+- Anything that changes behavior or needs a judgment call: don't apply it.
+
+Then report back on every comment: what you changed, and for the rest, your evaluation and what you propose. Do not reply on GitHub.
+
+{{context}}`,
+
+  rebase: `Bring pull request {{repo}}#{{number}} "{{title}}" ({{url}}) up to date with its base, {{base}}.
+
+Stack, bottom first: {{stack}}
+
+1. Fetch, then rebase. For a stack, check out the top branch and run \`git rebase --update-refs origin/{{base}}\` so every branch in the stack moves together.
+2. If the rebase had no conflicts, push every rebased branch with \`git push --force-with-lease\` and tell me it's done.
+3. If you resolved conflicts, do NOT push. Explain each resolution and wait. Push with \`--force-with-lease\` only after I reply "push".
+
+{{context}}`,
+
+  refresh: `Draft pull request {{repo}}#{{number}} "{{title}}" ({{url}}) has gone stale.
+
+Stack, bottom first: {{stack}}
+
+Rebase it onto the latest {{base}} the same way as any update: \`git rebase --update-refs\` for a stack. If there were no conflicts, push with \`git push --force-with-lease\`. If you resolved conflicts, do NOT push: explain each resolution and wait until I reply "push". Then tell me briefly what the draft still needs.
+
+{{context}}`,
+
+  start: `Start work on issue {{repo}}#{{number}} "{{title}}" ({{url}}).
+
+Read the issue and the code it touches, then propose a plan before changing anything.
+
+{{context}}`,
+};
+
+export const ACTION_SESSION: Partial<Record<ActionId, SessionKind>> = {
+  review: "review",
+  fix: "fix",
+  address: "address",
+  rebase: "rebase",
+  refresh: "refresh",
+  start: "start",
+};
+
+export function renderPrompt(
+  kind: SessionKind,
+  target: Target,
+  context: string,
+  config: Pick<AttentionConfig, "prompts">,
+): string {
+  const template = config.prompts[kind] ?? PROMPT_TEMPLATES[kind];
+  const values: Record<string, string> = {
+    repo: target.repo,
+    number: String(target.number),
+    title: target.title,
+    url: target.url,
+    head: target.headRefName ?? "",
+    base: target.baseRefName ?? target.defaultBranch ?? "",
+    stack: (target.stack ?? [{ number: target.number }]).map((pr) => `#${pr.number}`).join(" → "),
+    context: context.trim(),
+  };
+  return template.replace(/\{\{(\w+)\}\}/g, (match, name: string) => values[name] ?? match).trim();
+}

package/shared/rpc.ts

@@ -0,0 +1,56 @@
+import { defineRpc } from "@getpaseo/plugin";
+import { z } from "zod";
+import type { AttentionView, ItemDetails, Target } from "./attention";
+import { SessionKind } from "./config";
+import type { ConfigStatus, CoverageCheck, SetupStatus } from "./setup";
+
+// Both sides are this plugin, so the types are checked by TypeScript, not repeated as schemas.
+const view = z.custom<AttentionView>();
+const target = z.custom<Target>();
+const done = z.object({ ok: z.literal(true) });
+
+// The cached view. Feeds older than their schedule are refreshed from GitHub first; `refresh` fetches that feed now (⟳).
+export const getAttention = defineRpc({ name: "attention.get", input: z.object({ refresh: z.enum(["live", "history"]).optional() }), output: view });
+export const dismissItem = defineRpc({ name: "attention.dismiss", input: z.object({ key: z.string() }), output: view });
+// Undo one dismissal [ATT-08].
+export const undismissItem = defineRpc({ name: "attention.undismiss", input: z.object({ key: z.string() }), output: view });
+export const restoreDismissed = defineRpc({ name: "attention.restore-dismissed", input: z.object({}), output: view });
+// Adds one entry to codeRepos in config.json [SES-07].
+export const setCodeRepo = defineRpc({ name: "config.set-code-repo", input: z.object({ issueRepo: z.string(), codeRepo: z.string() }), output: view });
+// What the setup checklist shows when nothing loads [SET-01].
+export const setupStatus = defineRpc({ name: "setup.status", input: z.object({}), output: z.custom<SetupStatus>() });
+// The settings screen: the orgs and repos in config.json, each checked on GitHub as it's added [SRC-02].
+export const getCoverage = defineRpc({ name: "config.coverage", input: z.object({}), output: z.custom<ConfigStatus>() });
+export const checkCoverage = defineRpc({ name: "config.check-coverage", input: z.object({ kind: z.enum(["org", "repo"]), name: z.string() }), output: z.custom<CoverageCheck>() });
+export const setCoverage = defineRpc({ name: "config.set-coverage", input: z.object({ orgs: z.array(z.string()), repos: z.array(z.string()) }), output: done });
+// Remember the scope chips picked on Next up [NXT-03].
+export const setScopes = defineRpc({ name: "next-up.scopes", input: z.object({ scopes: z.array(z.string()) }), output: done });
+
+// GitHub changes, each from an explicit tap [SAFE-01].
+export const updateBranch = defineRpc({ name: "pr.update-branch", input: z.object({ target }), output: done });
+export const mergePullRequest = defineRpc({ name: "pr.merge", input: z.object({ target }), output: done });
+export const closePullRequest = defineRpc({ name: "pr.close", input: z.object({ target, comment: z.string().optional() }), output: done });
+export const claimIssue = defineRpc({ name: "issue.claim", input: z.object({ target }), output: done });
+export const unclaimIssue = defineRpc({ name: "issue.unclaim", input: z.object({ target }), output: done });
+// `ready: false` and `on: false` are the Undo of each.
+export const setReady = defineRpc({ name: "pr.ready", input: z.object({ target, ready: z.boolean() }), output: done });
+export const setAutoMerge = defineRpc({ name: "pr.auto-merge", input: z.object({ target, on: z.boolean() }), output: done });
+export const react = defineRpc({ name: "comment.react", input: z.object({ subjectIds: z.array(z.string()), on: z.boolean() }), output: done });
+export const rerunFailed = defineRpc({ name: "checks.rerun", input: z.object({ repo: z.string(), runIds: z.array(z.number()) }), output: done });
+
+// What an item's sheet shows beyond the card [ATT-06]. `checks` asks for failing checks too, for Rerun.
+export const itemDetails = defineRpc({
+  name: "item.details",
+  input: z.object({ subject: z.object({ kind: z.enum(["pr", "issue"]), repo: z.string(), number: z.number() }), target: target.optional(), checks: z.boolean() }),
+  output: z.custom<ItemDetails>(),
+});
+
+// The branch a session on an issue starts from, when its code lives in another repo [SES-07].
+export const defaultBranch = defineRpc({ name: "repo.default-branch", input: z.object({ repo: z.string() }), output: z.object({ name: z.string().nullable() }) });
+
+// Context for a session prompt: failing logs, unresolved threads, descriptions [SES-04].
+export const sessionContext = defineRpc({
+  name: "session.context",
+  input: z.object({ kind: SessionKind, target }),
+  output: z.object({ context: z.string() }),
+});

package/shared/setup.ts

@@ -0,0 +1,27 @@
+// What getting started needs, for the setup checklist [SET-01] and the settings screen [SRC-02].
+
+export interface ConfigStatus {
+  // Why config.json can't be read, if it can't. The settings screen won't overwrite it then.
+  error: string | null;
+  orgs: string[];
+  repos: string[];
+}
+
+export interface SetupStatus {
+  gh: {
+    found: boolean;
+    // The account gh is signed in as; null when it isn't, with gh's reason in `error`.
+    login: string | null;
+    error: string | null;
+  };
+  config: ConfigStatus;
+}
+
+// Nothing loads until these are fixed, so the checklist takes the tabs' place.
+export function blocks(status: SetupStatus): boolean {
+  return !status.gh.found || !status.gh.login || !!status.config.error;
+}
+
+// An org or repo checked on GitHub before it's saved: its exact name, or why it can't be added.
+export type CoverageCheck = { name: string; error: null } | { name: null; error: string };
+export type CoverageKind = "org" | "repo";