@xpufx/paseo-forges 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 xpufx
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,109 @@
+# forges
+
+Work with Forge/Gitea-family issues from inside Paseo: list open issues for the
+repo backing a workspace, read an issue's body and comments (with parsed agent
+envelopes), change scoped labels, and post comments, all in plugin surfaces
+with no browser. Augment with the provided webhook bridge and scoped labels
+to unlock autonomous agent orchestration.
+
+Pull requests, releases, actions, and everything else are out of scope for now.
+
+Built on [paseo-plugin-helper](https://github.com/xpufx/paseo/tree/main/packages/paseo-plugin-helper), the shared Paseo plugin runtime.
+
+## Screenshots
+
+| Main | Issue List | Issue Detail |
+| :---: | :---: | :---: |
+| <img src="screenshots/forge-main.png" width="100%" alt="Forges Main" /> | <img src="screenshots/forge-list.png" width="100%" alt="Forge Issue List" /> | <img src="screenshots/forge-issue-detail.png" width="100%" alt="Forge Issue Detail" /> |
+
+## Highlights
+
+- **No CLI dependency.** All forge access goes through an embedded TypeScript
+  `fetch` client (`server/forge-client.ts`) against the Gitea-family
+  `/api/v1`. There is no `git`/`fgj`/`fgjx` subprocess and no dependency on any
+  host dotfile.
+- **Daemon-side tokens.** The API token is stored per host in plugin settings
+  and only ever attached to `fetch` calls in the daemon. It never reaches the
+  client.
+- **Live label vocabulary.** Scopes are derived from the labels actually on the
+  board, so a foreign board degrades gracefully instead of failing on an
+  unknown scope.
+- **Paged reads.** Issue list, keyword search, label list, and comment list are
+  all collections: each call returns **one page**, and the default page size is
+  **server-defined and can change**. Treat every list as paged
+  (`limit`/`page`, or follow `Link`/`X-Total-Count`) instead of assuming a
+  single call is complete; one unpaged call is never evidence of "no results".
+  A surface that lists results should page internally rather than render a
+  truncated set (#189).
+- **Example skills.** Our agent workflow ships under `examples/` as a starting
+  point to adapt (see [`examples/README.md`](./examples/README.md)).
+
+Supported forges (verified live, anonymous reads): any Forgejo/Gitea-family
+host, including Forgejo, Gitea, and Codeberg.
+
+## Workflow Augmentation: Turn Issues into Agent Fleet Automation
+
+Out of the box, `forges` gives you in-app issue management, scoped label chips, and steering comments directly inside Paseo.
+
+When augmented with our scoped label taxonomy and lightweight webhook bridge ([`examples/hook-service/`](./examples/hook-service/)), `forges` becomes an autonomous agent coordination layer:
+
+- **Automated Webhook Ingestion:** New issues, label edits, or comments on your forge immediately dispatch events to your orchestrator agent via Paseo's agent transport.
+- **Autonomous Agent Handoffs:** Coding agents pick up assigned tickets, transition `state/` chips (`0-triage` → `1-wip` → `2-review` → `3-verify` → `4-done`), publish structured status envelopes, and pass attention back to the operator when human signoff is required.
+- **Drop-In Scoped Label Taxonomy:** Seed our four core scopes (`state/`, `priority/`, `attention/`, `spec/`) using the generic template in [`examples/labels/label-base.yaml`](./examples/labels/label-base.yaml).
+- **Adaptable Agent Skills:** Ships with zero-CLI skills (using plugin `/api/v1` RPCs directly) as well as CLI-assisted workflows ([`examples/skills/`](./examples/skills/)).
+
+See [`docs/workflow.md`](./docs/workflow.md) for the end-to-end architecture and [`examples/README.md`](./examples/README.md) for starter templates.
+
+## Install
+
+The plugin uses the Paseo 0.8 layout (`index.client.tsx` / `index.server.ts`
+entries, `client/` / `server/` / `shared/` split, manifest
+`requirements.paseo >= 0.8.0`).
+
+```sh
+paseo plugin add xpufx/paseo --path plugins/forges
+```
+
+Or from a local monorepo checkout:
+
+```sh
+paseo plugin add ./plugins/forges
+```
+
+## Configuration
+
+Open the plugin's **Settings** tab inside a workspace.
+
+- **Active forge.** Each workspace watches one active forge at a time. The
+  list holds the workspace's forge remotes (any `parseForgeRemote` form plus
+  a bare `owner/repo`); **Auto** derives the remote from the workspace's git
+  `origin`. An explicit selection wins absolutely: an invalid or unreachable
+  selection fails loudly instead of silently deriving.
+- **API token.** Saved per host in daemon-side plugin settings. Reads work
+  anonymously on public repos; labels and comments need an accepted token with
+  write scope on both public and private repos. For Forgejo/Gitea create the
+  PAT with `read:user`, `read:repository`, and `write:issue` (add
+  `write:repository` if label management still 403s). Edit capability is read
+  from the repo's permission object (`permissions.push`/`admin`, or GitLab
+  `access_level >= 30`), so a token that is accepted but under-scoped shows
+  "token lacks write scope" instead of enabling edits.
+
+## Development
+
+```sh
+npm install --workspace=plugins/forges
+npm run typecheck --workspace=plugins/forges
+npm test --workspace=plugins/forges
+```
+
+The helper audit also applies:
+
+```sh
+node packages/paseo-plugin-helper/bin/paseo-plugin-helper.js audit plugins/forges
+```
+
+See [`docs/specs/forge-workflow-gui.md`](./docs/specs/forge-workflow-gui.md)
+for the data model, RPC contracts, and UI surfaces, and
+[`docs/workflow.md`](./docs/workflow.md) for the end-to-end agent workflow
+(hook service, label usage, agent responsibilities, and what the plugin ships
+versus what an adopter supplies).

package/client/active-forge.ts

@@ -0,0 +1,47 @@
+import { useMemo } from "react";
+import { useAgent, useWorkspace } from "@getpaseo/plugin/client";
+import type { PluginWorkspaceSnapshot } from "@getpaseo/plugin";
+import {
+  activeForgeForDirectory,
+  forgeContextContract,
+  forgeSettingsContract,
+  resolveForgeTarget,
+  type ForgeRepoIdentity,
+} from "../shared/issues.js";
+import { usePluginSettings, useRpcQuery } from "paseo-plugin-helper/client";
+
+/** Workspace directory backing an agent, or undefined while it cannot resolve. */
+export function useAgentDirectory(agentId: string): string | undefined {
+  const workspaceId = useAgent(agentId, (agent: { workspaceId: string }) => agent?.workspaceId) as
+    | string
+    | null;
+  return (
+    useWorkspace(workspaceId ?? "", (workspace: PluginWorkspaceSnapshot) => workspace?.directory) ??
+    undefined
+  );
+}
+
+/**
+ * Active forge identity for a workspace directory, mirroring the server's
+ * resolution: an explicit selection wins absolutely, otherwise the git origin
+ * remote is derived via `forgeContextContract`. The git-context query is
+ * cache-keyed, so per-item callers share one request. Null when nothing
+ * resolves, which callers treat as "every link is foreign".
+ */
+export function useActiveForgeIdentity(
+  directory: string | undefined | null,
+): ForgeRepoIdentity | null {
+  const { settings } = usePluginSettings(forgeSettingsContract);
+  const context = useRpcQuery(forgeContextContract, { directory: directory ?? undefined });
+  const target = activeForgeForDirectory(settings, directory) ?? "";
+  const derivedRemote = context.data?.derivedRemote ?? null;
+  return useMemo(() => {
+    const resolved = resolveForgeTarget(target, derivedRemote);
+    return resolved.ok ? { host: resolved.host, repo: resolved.repo } : null;
+  }, [target, derivedRemote]);
+}
+
+/** Active forge identity for the workspace backing a timeline agent. */
+export function useActiveForgeIdentityForAgent(agentId: string): ForgeRepoIdentity | null {
+  return useActiveForgeIdentity(useAgentDirectory(agentId));
+}

package/client/board-alert.tsx

@@ -0,0 +1,236 @@
+import React from "react";
+import { Linking, Pressable, StyleSheet, Text, View } from "react-native";
+import { z } from "zod";
+import type {
+  PluginTimelineItemProps,
+  PluginTimelineTransformerContribution,
+} from "@getpaseo/plugin/client";
+import {
+  Badge,
+  ForgeIcon,
+} from "paseo-plugin-helper/client";
+import {
+  boardAlertTimelineSchema,
+  classifyForgeUrl,
+  parseBoardAlert,
+} from "../shared/issues.js";
+import { useActiveForgeIdentityForAgent } from "./active-forge.js";
+import { ForeignLinkBadge } from "./foreign-link.js";
+import { LabelChipList } from "./label-chip.js";
+
+const boardAlertCardSchema = boardAlertTimelineSchema.extend({
+  text: z.string(),
+});
+type BoardAlertCardData = z.infer<typeof boardAlertCardSchema>;
+type BoardAlertIssueRowData = z.infer<typeof boardAlertTimelineSchema>;
+
+function transformTextItem<T extends { text: string }>(item: T) {
+  const parsed = parseBoardAlert(item.text);
+  if (!parsed) return undefined;
+  return {
+    items: [
+      {
+        type: "plugin" as const,
+        kind: "forge-board-alert",
+        version: 1,
+        data: { ...parsed, text: item.text },
+      },
+    ],
+  } as any;
+}
+
+/**
+ * Board-alert timeline transformer: raw autonomous-check dumps become
+ * typed `forge-board-alert` items so the composer renders the
+ * structured timeline card below instead of a text wall.
+ */
+export const forgeBoardAlertUserTransformer: PluginTimelineTransformerContribution<"user_message"> = {
+  id: "forge-board-alert-user",
+  query: { itemType: "user_message" },
+  transform({ item }) {
+    return transformTextItem(item);
+  },
+};
+
+export const forgeBoardAlertAssistantTransformer: PluginTimelineTransformerContribution<"assistant_message"> = {
+  id: "forge-board-alert-assistant",
+  query: { itemType: "assistant_message" },
+  transform({ item }) {
+    return transformTextItem(item);
+  },
+};
+
+function BoardAlertIssueRow({
+  theme,
+  issue,
+  foreign,
+}: {
+  theme: PluginTimelineItemProps<BoardAlertIssueRowData>["theme"];
+  issue: BoardAlertIssueRowData["issues"][number];
+  foreign: boolean;
+}) {
+  const open = issue.url
+    ? () => {
+        Linking.openURL(issue.url as string).catch(() => {});
+      }
+    : undefined;
+  return (
+    <View style={styles.issueRow}>
+      <ForgeIcon host={issue.url} size={13} color={theme.colors.foregroundMuted} />
+      <Badge variant="info" label={`#${issue.number}`} />
+      <View style={styles.issueBody}>
+        {open ? (
+          <Pressable onPress={open} hitSlop={8}>
+            <Text style={[styles.issueTitle, styles.issueTitleLink, { color: theme.colors.accent }]}>
+              {issue.title}
+            </Text>
+          </Pressable>
+        ) : (
+          <Text style={[styles.issueTitle, { color: theme.colors.foreground }]}>
+            {issue.title}
+          </Text>
+        )}
+        {issue.url ? (
+          <Pressable onPress={open} hitSlop={8}>
+            <Text style={[styles.issueUrl, { color: theme.colors.accent }]}>
+              {issue.url}
+            </Text>
+          </Pressable>
+        ) : null}
+        <LabelChipList
+          labels={issue.labels.map((name) => ({ name }))}
+          style={styles.issueLabels}
+        />
+        {issue.action ? (
+          <Text style={[styles.issueAction, { color: theme.colors.foregroundMuted }]}>
+            {issue.action}
+          </Text>
+        ) : null}
+      </View>
+      {foreign ? <ForeignLinkBadge /> : null}
+    </View>
+  );
+}
+
+export function ForgeBoardAlertCard({
+  item,
+  theme,
+  agentId,
+}: PluginTimelineItemProps<BoardAlertCardData>) {
+  const activeForge = useActiveForgeIdentityForAgent(agentId);
+  const count = item.data.issues.length;
+  return (
+    <View
+      style={[
+        styles.card,
+        {
+          backgroundColor: theme.colors.surface1,
+          borderColor: theme.colors.border,
+        },
+      ]}
+    >
+      <Text style={[styles.bodyText, { color: theme.colors.foreground }]}>
+        {item.data.text}
+      </Text>
+      <View style={styles.header}>
+        <ForgeIcon
+          host={activeForge?.host ?? item.data.issues[0]?.url}
+          size={14}
+          color={theme.colors.accent}
+        />
+        <Text style={[styles.title, { color: theme.colors.foreground }]}>
+          Forge Board Alert
+        </Text>
+        <Badge
+          variant="warning"
+          label={count === 1 ? "1 actionable" : `${count} actionable`}
+        />
+      </View>
+      <Text style={[styles.headline, { color: theme.colors.foregroundMuted }]}>
+        {item.data.headline}
+      </Text>
+      <View style={styles.issues}>
+        {item.data.issues.map((issue) => (
+          <BoardAlertIssueRow
+            key={issue.number}
+            theme={theme}
+            issue={issue}
+            foreign={classifyForgeUrl(issue.url, activeForge) === "foreign"}
+          />
+        ))}
+      </View>
+      <Text style={[styles.footer, { color: theme.colors.foregroundMuted }]}>
+        via forge
+      </Text>
+    </View>
+  );
+}
+
+export const forgeBoardAlertRenderer = {
+  kind: "forge-board-alert",
+  version: 1,
+  schema: boardAlertCardSchema,
+  Component: ForgeBoardAlertCard,
+};
+
+const styles = StyleSheet.create({
+  card: {
+    borderRadius: 8,
+    borderWidth: 1,
+    padding: 8,
+    marginVertical: 2,
+    gap: 6,
+  },
+  header: {
+    flexDirection: "row",
+    alignItems: "center",
+    gap: 6,
+  },
+  title: {
+    fontSize: 12,
+    fontWeight: "600",
+    flex: 1,
+  },
+  bodyText: {
+    fontSize: 13,
+  },
+  headline: {
+    fontSize: 11,
+  },
+  issues: {
+    gap: 8,
+  },
+  issueRow: {
+    flexDirection: "row",
+    alignItems: "flex-start",
+    gap: 8,
+  },
+  issueBody: {
+    flex: 1,
+    gap: 2,
+  },
+  issueTitle: {
+    fontSize: 13,
+    fontWeight: "600",
+  },
+  issueTitleLink: {
+    textDecorationLine: "underline",
+  },
+  issueUrl: {
+    fontSize: 11,
+    textDecorationLine: "underline",
+  },
+  issueLabels: {
+    flexDirection: "row",
+    flexWrap: "wrap",
+    gap: 4,
+  },
+  issueAction: {
+    fontSize: 11,
+    fontStyle: "italic",
+  },
+  footer: {
+    fontSize: 10,
+    fontStyle: "italic",
+  },
+});

package/client/foreign-link.tsx

@@ -0,0 +1,33 @@
+import React from "react";
+import { Text } from "react-native";
+import { Badge } from "paseo-plugin-helper/client";
+
+/** Shared label for the cross-repo marker, so every surface reads the same. */
+export const FOREIGN_LINK_LABEL = "foreign";
+
+/** Accessible description of the marker for pressable link rows. */
+export const FOREIGN_LINK_HINT = "Points at a different forge repo";
+
+/** Compact `foreign` badge for a link row laid out with flexbox. */
+export function ForeignLinkBadge() {
+  return (
+    <Badge
+      variant="warning"
+      styleVariant="outline"
+      icon="Globe"
+      label={FOREIGN_LINK_LABEL}
+    />
+  );
+}
+
+/**
+ * Inline `foreign` marker for a link rendered inside a <Text> (markdown
+ * spans). Purely additive: the link keeps its own navigation handler.
+ */
+export function ForeignInlineMark({ color }: { color: string }) {
+  return (
+    <Text style={{ fontSize: 10, fontWeight: "700", color }}>
+      {` ${FOREIGN_LINK_LABEL}`}
+    </Text>
+  );
+}