@hanzo/build 0.2.4 → 0.2.6

package/README.md

@@ -5,7 +5,9 @@ the database, the sign-in and the storage already there.
 
 The builder is one component, `<Builder host={…} />` from `@hanzo/build`, with
 three hosts: this page (hanzo.build), and the Dev section of the Hanzo app at
-hanzo.ai/dev and hanzo.app/dev. None of them forks it.
+hanzo.ai/dev and hanzo.app/dev. None of them forks it. hanzo.build is this
+frontend. A click stays on this origin — sign-in returns to `/auth/callback`
+here — and github.com is opened only for the repository grant.
 
 ```
 pnpm install
@@ -67,6 +69,11 @@ hanzo.id token for `Host.admin`. One left column, never two.
 |---|---|
 | `''` | New — the empty state and the composer |
 | `sess_<32 hex>` | one run, live |
+| `-/automations` | repeating work, read from `/v1/auto/flows` |
+| `-/codebases` | the forge's repositories |
+| `-/sync` | bring granted repositories onto the forge |
+| `-/projects` | the forge's boards |
+| `-/issues` | the forge's issues |
 | `-/artifacts` | what the org has built |
 | `-/templates` | the public starters |
 | `<slug>` | a project's workspace |
@@ -76,16 +83,19 @@ collide.
 
 ## What is on the screen
 
-**The rail** (hanzo.build). New, Artifacts, Customize (the platform's
-plugins), More (Templates, Machines, Docs), then the org's coding runs newest
-first with a live status dot, and the account. Collapse is an explicit toggle
-kept in this browser. A host with its own rail draws `DevSection` there instead.
+**The rail** (hanzo.build). New, then Automations, then the forge — Codebase, Projects, Issues —
+then Artifacts, Customize (the platform's plugins), More (Templates, Machines,
+Docs), then the org's coding runs newest first with a live status dot, and the
+account. Collapse is an explicit toggle kept in this browser. A host with its
+own rail draws `DevSection` there instead.
 
 **New.** "What's up next?", and at the foot the composer: where the run runs
-(Default is the platform's sandbox; the org's machines follow), the repository
-and the branch — both searchable, paged popovers opening upward — then the
+(Default is the platform's sandbox; the org's machines follow), the codebase
+and the branch — the forge's repositories, filtered as you type — then the
 ask. Under it: attach (files ride the prompt as text), dictate, Build or Plan,
-and the model and effort. A repository row can be added to a project.
+and the model and effort. A codebase can be added to a project. Opening a
+codebase or an issue from its own screen lands here with that choice already
+made.
 
 **A run.** The transcript as it streams, steering while it works, Stop, and
 the pull request once it pushes one.
@@ -104,7 +114,11 @@ picker and open-in-tab; Share and Publish; the console dock under it.
 | `GET /v1/agent/sessions/{id}` · `GET /v1/agent/sessions/stream?root=` | a run, and its live feed (SSE over fetch) |
 | `POST /v1/agent/sessions/{id}/message` · `/stop` | steer, stop |
 | `GET /v1/agent/targets` | the org's machines |
-| `GET /v1/provider/github/repos` · `…/{owner}/{repo}/branches` | the chips' pagers |
+| `GET /v1/auto/flows` · `POST /v1/auto/flows` · `POST /v1/auto/flows/{id}/enable` | automations |
+| `GET /v1/provider/github/repos` · `POST /v1/provider/github/repos/import` | granted repositories, and bringing them onto the forge |
+| `GET /v1/git/repos` · `GET /v1/git/repos/{name}` | the codebase chip, and its branches |
+| `GET /v1/task/projects` · `GET /v1/task/board` · `GET /v1/task/projects/{key}/issues` | boards and issues, read from the forge |
+| `GET /v1/provider/github/repos` · `…/{owner}/{repo}/branches` | kept for a host that still asks GitHub |
 | `POST /v1/provider/github/user/connect` | connect a person's GitHub |
 | `GET /v1/projects` · `POST /v1/projects/fork` · `GET /v1/templates` | artifacts, templates |
 | `GET /v1/git/repos/{name}/tree` · `/blob` | Files and Code |
@@ -121,6 +135,7 @@ src/
   index.ts      the library surface
   builder.tsx   the rail and the pane the address names
   landing.tsx   New
+  forge.tsx     Codebase, Automations, Projects, Issues
   run.tsx       one run
   project.tsx   a project's workspace
   shelf.tsx     Artifacts and Templates

package/lib/account.d.ts

@@ -1,4 +1,7 @@
 import type { RailSession } from '@hanzo/ui/chat';
+/** The builder listens, so a settings control on this page opens the account dialog. */
+export declare function onAccount(fn: () => void): () => void;
+export declare function revealAccount(): void;
 export declare function Account({ open, onOpenChange }: {
     open: boolean;
     onOpenChange: (o: boolean) => void;

package/lib/account.js

@@ -8,10 +8,33 @@ import { LogOut, Settings } from '@hanzogui/lucide-icons-2';
 import { Button, Dialog, DialogContent, DialogTitle, Input } from '@hanzo/ui';
 import { useMemo, useState } from 'react';
 import { useHost } from './host.js';
+let reveal = null;
+/** The builder listens, so a settings control on this page opens the account dialog. */
+export function onAccount(fn) {
+    reveal = fn;
+    return () => {
+        if (reveal === fn)
+            reveal = null;
+    };
+}
+export function revealAccount() {
+    reveal?.();
+}
+/** A settings address on another host. This page's own account is the dialog itself. */
+function accountSettings(href) {
+    if (typeof window === 'undefined')
+        return false;
+    try {
+        return new URL(href, window.location.origin).origin !== window.location.origin;
+    }
+    catch {
+        return false;
+    }
+}
 export function Account({ open, onOpenChange }) {
     const host = useHost();
     const who = host.person;
-    return (_jsx(Dialog, { open: open, onOpenChange: onOpenChange, children: _jsxs(DialogContent, { maxW: 360, children: [_jsx(DialogTitle, { children: "Account" }), _jsxs(YStack, { gap: "$1", children: [_jsx(SizableText, { size: "$3", color: "$ink", numberOfLines: 1, children: who?.name || who?.email || 'Signed out' }), who?.email && who.name ? (_jsx(SizableText, { size: "$2", color: "$soft", numberOfLines: 1, children: who.email })) : null, host.org ? (_jsxs(SizableText, { size: "$1", color: "$soft", children: ["Organization: ", host.org] })) : null] }), _jsxs(XStack, { gap: "$2", justify: "flex-end", flexWrap: "wrap", children: [_jsxs(Button, { variant: "outline", size: "sm", onPress: () => host.open(host.links.settings), children: [_jsx(Settings, { size: 14 }), " Settings"] }), host.signOut ? (_jsxs(Button, { variant: "outline", size: "sm", onPress: () => host.signOut?.(), children: [_jsx(LogOut, { size: 14 }), " Sign out"] })) : null] })] }) }));
+    return (_jsx(Dialog, { open: open, onOpenChange: onOpenChange, children: _jsxs(DialogContent, { maxW: 360, children: [_jsx(DialogTitle, { children: "Account" }), _jsxs(YStack, { gap: "$1", children: [_jsx(SizableText, { size: "$3", color: "$ink", numberOfLines: 1, children: who?.name || who?.email || 'Signed out' }), who?.email && who.name ? (_jsx(SizableText, { size: "$2", color: "$soft", numberOfLines: 1, children: who.email })) : null, host.org ? (_jsxs(SizableText, { size: "$1", color: "$soft", children: ["Organization: ", host.org] })) : null] }), _jsxs(XStack, { gap: "$2", justify: "flex-end", flexWrap: "wrap", children: [accountSettings(host.links.settings) ? (_jsxs(Button, { variant: "outline", size: "sm", onPress: () => host.open(host.links.settings), children: [_jsx(Settings, { size: 14 }), " Settings"] })) : null, host.signOut ? (_jsxs(Button, { variant: "outline", size: "sm", onPress: () => host.signOut?.(), children: [_jsx(LogOut, { size: 14 }), " Sign out"] })) : null] })] }) }));
 }
 export function Find({ open, onOpenChange, recents, onOpen, }) {
     const [q, setQ] = useState('');

package/lib/api/auto.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Automations: flows that run themselves.
+ *
+ *   GET    /v1/auto/flows              {data: [flow]}   newest updated first
+ *   GET    /v1/auto/flows/{id}         the flow and its latest version (the name)
+ *   POST   /v1/auto/flows              a disabled draft
+ *   POST   /v1/auto/flows/{id}/enable
+ *   POST   /v1/auto/flows/{id}/disable
+ *
+ * The list page records the id and whether the trigger is armed. The name lives
+ * on the latest version, so each row is read once more.
+ */
+import { type Target } from './call.ts';
+export interface Automation {
+    id: string;
+    name: string;
+    /** ENABLED or DISABLED. */
+    status: string;
+    /** Unix milliseconds, or 0. */
+    updated: number;
+}
+export declare function automation(raw: unknown): Automation | null;
+export declare function flows(t: Target): Promise<Automation[]>;
+/** A disabled draft. Creating it does not arm the trigger. */
+export declare function add(t: Target, name: string): Promise<Automation>;
+/** Arm or disarm the trigger. A disarmed flow can still be started on demand. */
+export declare function arm(t: Target, id: string, on: boolean): Promise<void>;

package/lib/api/auto.js

@@ -0,0 +1,67 @@
+/**
+ * Automations: flows that run themselves.
+ *
+ *   GET    /v1/auto/flows              {data: [flow]}   newest updated first
+ *   GET    /v1/auto/flows/{id}         the flow and its latest version (the name)
+ *   POST   /v1/auto/flows              a disabled draft
+ *   POST   /v1/auto/flows/{id}/enable
+ *   POST   /v1/auto/flows/{id}/disable
+ *
+ * The list page records the id and whether the trigger is armed. The name lives
+ * on the latest version, so each row is read once more.
+ */
+import { call, seg } from './call.js';
+const str = (v) => (typeof v === 'string' ? v : '');
+const obj = (v) => v && typeof v === 'object' ? v : {};
+export function automation(raw) {
+    const o = obj(raw);
+    const id = str(o.id);
+    if (!id)
+        return null;
+    const version = obj(o.version);
+    return {
+        id,
+        name: str(version.displayName) || str(o.displayName) || id,
+        status: str(o.status) || 'DISABLED',
+        updated: typeof o.updated === 'number' ? o.updated : 0,
+    };
+}
+export async function flows(t) {
+    const raw = await call(t, 'GET', '/v1/auto/flows');
+    const data = Array.isArray(obj(raw).data) ? obj(raw).data : [];
+    const rows = data.map(automation).filter((a) => a !== null).slice(0, 40);
+    return Promise.all(rows.map(async (a) => {
+        if (a.name !== a.id)
+            return a;
+        try {
+            return automation(await call(t, 'GET', `/v1/auto/flows/${seg(a.id)}`)) ?? a;
+        }
+        catch {
+            return a;
+        }
+    }));
+}
+/** A disabled draft. Creating it does not arm the trigger. */
+export async function add(t, name) {
+    const displayName = name.trim();
+    if (!displayName)
+        throw new Error('Name the automation');
+    const raw = await call(t, 'POST', '/v1/auto/flows', {
+        displayName,
+        trigger: {
+            name: 'trigger',
+            type: 'PIECE_TRIGGER',
+            displayName: 'Start',
+            strategy: 'MANUAL',
+            settings: { pieceName: 'core', triggerName: 'manual' },
+        },
+    });
+    const row = automation(raw);
+    if (!row)
+        throw new Error('The automation was created and did not come back named');
+    return row;
+}
+/** Arm or disarm the trigger. A disarmed flow can still be started on demand. */
+export async function arm(t, id, on) {
+    await call(t, 'POST', `/v1/auto/flows/${seg(id)}/${on ? 'enable' : 'disable'}`);
+}

package/lib/api/codebases.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Codebases on the forge, the org's own git.
+ *
+ *   GET /v1/git/repos          {data: [repo]}   most recently updated first
+ *   GET /v1/git/repos/{name}   one repo, with its branch names
+ *
+ * A coding run addresses a repository by its name. The org is the tenant on
+ * the request, so the name is the whole address — `owner/name` is a path the
+ * engine refuses.
+ */
+import { type Target } from './call.ts';
+export interface Codebase {
+    org: string;
+    name: string;
+    description: string;
+    /** HEAD's branch, or 'main' when the forge did not say. */
+    branch: string;
+    public: boolean;
+    /** The https remote `git clone` takes, or ''. */
+    clone: string;
+    updated: string;
+    branches: string[];
+}
+/** What the composer chip stores. `forge` marks a choice made from this list. */
+export interface ForgeRepo {
+    owner: string;
+    name: string;
+    full_name: string;
+    private: boolean;
+    default_branch: string;
+    pushed_at: string;
+    installation_id: number;
+    forge: true;
+    clone: string;
+}
+export declare function codebase(raw: unknown, org?: string): Codebase | null;
+/** A chip row remembered as a forge codebase, when the list had not seen it yet. */
+export declare function chosen(r: {
+    owner: string;
+    name: string;
+    full_name?: string;
+    private?: boolean;
+    default_branch?: string;
+}, clone?: string): ForgeRepo;
+/** The chip's row for a codebase the forge listed. */
+export declare function asRepo(c: Codebase): ForgeRepo;
+/** Provision an empty repository. The name is the handle and the last path segment. */
+export declare function create(t: Target, name: string, description?: string): Promise<Codebase>;
+export declare function codebases(t: Target, q?: string): Promise<Codebase[]>;
+/** One codebase, so the branch chip can list what HEAD can point at. */
+export declare function one(t: Target, name: string): Promise<Codebase | null>;

package/lib/api/codebases.js

@@ -0,0 +1,91 @@
+/**
+ * Codebases on the forge, the org's own git.
+ *
+ *   GET /v1/git/repos          {data: [repo]}   most recently updated first
+ *   GET /v1/git/repos/{name}   one repo, with its branch names
+ *
+ * A coding run addresses a repository by its name. The org is the tenant on
+ * the request, so the name is the whole address — `owner/name` is a path the
+ * engine refuses.
+ */
+import { call, seg } from './call.js';
+const str = (v) => (typeof v === 'string' ? v : '');
+const obj = (v) => v && typeof v === 'object' ? v : {};
+export function codebase(raw, org = '') {
+    const o = obj(raw);
+    const name = str(o.name);
+    if (!name)
+        return null;
+    const branches = (Array.isArray(o.branches) ? o.branches : []).filter((b) => typeof b === 'string' && b !== '');
+    const branch = str(o.defaultBranch) || 'main';
+    return {
+        org: str(o.org) || org,
+        name,
+        description: str(o.description),
+        branch,
+        public: o.public === true,
+        clone: str(o.cloneUrl),
+        updated: str(o.updatedAt),
+        branches: branches.length ? branches : [branch],
+    };
+}
+/** A chip row remembered as a forge codebase, when the list had not seen it yet. */
+export function chosen(r, clone = '') {
+    return {
+        owner: r.owner,
+        name: r.name,
+        full_name: r.full_name || (r.owner ? `${r.owner}/${r.name}` : r.name),
+        private: r.private === true,
+        default_branch: r.default_branch || 'main',
+        pushed_at: '',
+        installation_id: 0,
+        forge: true,
+        clone,
+    };
+}
+/** The chip's row for a codebase the forge listed. */
+export function asRepo(c) {
+    const owner = c.org;
+    return {
+        owner,
+        name: c.name,
+        full_name: owner ? `${owner}/${c.name}` : c.name,
+        private: !c.public,
+        default_branch: c.branch || 'main',
+        pushed_at: c.updated,
+        installation_id: 0,
+        forge: true,
+        clone: c.clone,
+    };
+}
+function rows(raw) {
+    if (Array.isArray(raw))
+        return raw;
+    const o = obj(raw);
+    return Array.isArray(o.data) ? o.data : [];
+}
+const NAME = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+/** Provision an empty repository. The name is the handle and the last path segment. */
+export async function create(t, name, description = '') {
+    const handle = name.trim().replace(/\.git$/, '');
+    if (!NAME.test(handle))
+        throw new Error('A repository name starts with a letter or number, and may contain letters, numbers, dots, underscores and hyphens.');
+    const raw = await call(t, 'POST', '/v1/git/repos', { name: handle, description: description.trim() });
+    const row = codebase(raw, t.org ?? '');
+    if (!row)
+        throw new Error('The forge created a repository and did not name it');
+    return row;
+}
+export async function codebases(t, q = '') {
+    const raw = await call(t, 'GET', '/v1/git/repos');
+    const needle = q.trim().toLowerCase();
+    return rows(raw)
+        .map((r) => codebase(r, t.org ?? ''))
+        .filter((c) => c !== null)
+        .filter((c) => !needle || `${c.org}/${c.name} ${c.description}`.toLowerCase().includes(needle));
+}
+/** One codebase, so the branch chip can list what HEAD can point at. */
+export async function one(t, name) {
+    const raw = await call(t, 'GET', `/v1/git/repos/${seg(name)}`);
+    return codebase(raw, t.org ?? '');
+}

package/lib/api/coding.d.ts

@@ -26,7 +26,7 @@ export declare const unhonoured: (mode: Mode | undefined, target?: string) => st
 export interface Ask {
     /** The task, in the words you would use with a colleague. */
     prompt: string;
-    /** `owner/name`. Omitted starts something new, in a repository named for it. */
+    /** The repository's name in the caller's org. A slash is not a name. Omitted starts something new. */
     repo?: string;
     /** The branch to start from. Omitted takes the repository's default. */
     base?: string;

package/lib/api/github.d.ts

@@ -76,3 +76,34 @@ export declare function connection(t: Target): Promise<Connection>;
 /** Where to send the person to authorize the platform's GitHub App — github.com only. */
 export declare function connect(t: Target): Promise<string>;
 export declare function disconnect(t: Target): Promise<void>;
+/** One repository the GitHub connection grants this organization. */
+export interface Grant {
+    owner: string;
+    name: string;
+    /** `owner/name`, the selector the importer accepts. */
+    fullName: string;
+    private: boolean;
+    branch: string;
+    /** Already mirrored onto the forge. */
+    imported: boolean;
+    /** `synced`, `conflict`, or '' while it has not landed. */
+    status: string;
+}
+export interface Grants {
+    repos: Grant[];
+    /** Accounts the connection could not read. */
+    unread: string[];
+}
+export interface Account {
+    name: string;
+    count: number;
+    /** Named as unread and carrying no repositories. */
+    blocked: boolean;
+}
+export declare function grant(raw: unknown): Grant | null;
+/** Accounts the grant names, plus any account that could not be read. */
+export declare function accounts(g: Grants): Account[];
+/** Every repository the GitHub connection grants, with whether the forge already has it. */
+export declare function grants(t: Target, signal?: AbortSignal): Promise<Grants>;
+/** Queue a mirror of the named repositories onto the forge. The names are `owner/name`. */
+export declare function bring(t: Target, repos: string[]): Promise<number>;

package/lib/api/github.js

@@ -71,3 +71,53 @@ export async function connect(t) {
 export async function disconnect(t) {
     await call(t, 'POST', '/v1/provider/github/user/disconnect');
 }
+export function grant(raw) {
+    const r = obj(raw);
+    const name = str(r.name);
+    if (!name)
+        return null;
+    const full = str(r.fullName) || str(r.full_name);
+    const owner = str(r.owner) || (full.includes('/') ? full.slice(0, full.indexOf('/')) : '');
+    return {
+        owner,
+        name,
+        fullName: full || (owner ? `${owner}/${name}` : name),
+        private: r.private === true,
+        branch: str(r.defaultBranch) || str(r.default_branch) || 'main',
+        imported: r.imported === true,
+        status: str(r.syncStatus) || str(r.sync_status),
+    };
+}
+/** Accounts the grant names, plus any account that could not be read. */
+export function accounts(g) {
+    const counts = new Map();
+    for (const r of g.repos) {
+        if (!r.owner)
+            continue;
+        counts.set(r.owner, (counts.get(r.owner) ?? 0) + 1);
+    }
+    const unread = new Set(g.unread.filter(Boolean));
+    const names = new Set([...counts.keys(), ...unread]);
+    return [...names]
+        .sort((a, b) => a.localeCompare(b))
+        .map((name) => {
+        const count = counts.get(name) ?? 0;
+        return { name, count, blocked: unread.has(name) && count === 0 };
+    });
+}
+/** Every repository the GitHub connection grants, with whether the forge already has it. */
+export async function grants(t, signal) {
+    const raw = obj(await call(t, 'GET', '/v1/provider/github/repos', undefined, { signal }));
+    return {
+        repos: (Array.isArray(raw.repos) ? raw.repos : []).map(grant).filter((r) => r !== null),
+        unread: (Array.isArray(raw.unread) ? raw.unread : []).filter((x) => typeof x === 'string' && x !== ''),
+    };
+}
+/** Queue a mirror of the named repositories onto the forge. The names are `owner/name`. */
+export async function bring(t, repos) {
+    const names = repos.map((n) => n.trim()).filter(Boolean);
+    if (names.length === 0)
+        throw new Error('Choose a repository first');
+    const raw = obj(await call(t, 'POST', '/v1/provider/github/repos/import', { repos: names }));
+    return num(raw.queued);
+}

package/lib/api/turn.d.ts

@@ -21,6 +21,25 @@ export declare function decode(payload: unknown): Record<string, unknown> | stri
  * the run's, from its record: a plan run's final status says the plan.
  */
 export declare function said(e: Pick<Event, 'kind' | 'payload'>, mode?: string): string;
+/** One line of the shell: a command the run started, or output that followed it. */
+export interface ShellLine {
+    role: 'cmd' | 'out';
+    text: string;
+}
+/**
+ * The shell beside the transcript. A tool call is the command; a log line, and
+ * any stdout or stderr the payload carried, is the output. Status stays in the
+ * transcript. Each line is capped so a payload that carried a file body cannot
+ * fill the pane.
+ */
+export declare function shell(events: Pick<Event, 'kind' | 'payload' | 'seq'>[]): ShellLine[];
+/** A step the run named. Done is a step whose status has settled. */
+export interface StepLine {
+    name: string;
+    done: boolean;
+}
+/** Tool calls, in the order they were first named. A later status for the same step wins. */
+export declare function steps(events: Pick<Event, 'kind' | 'payload' | 'seq'>[]): StepLine[];
 export interface Outcome {
     /** The last lifecycle status the run narrated, or ''. */
     status: string;

package/lib/api/turn.js

@@ -80,6 +80,66 @@ export function said(e, mode = '') {
         return str(body.error) || 'The run hit an error';
     return str(body.step) || str(body.name);
 }
+/**
+ * The shell beside the transcript. A tool call is the command; a log line, and
+ * any stdout or stderr the payload carried, is the output. Status stays in the
+ * transcript. Each line is capped so a payload that carried a file body cannot
+ * fill the pane.
+ */
+export function shell(events) {
+    const cap = 4000;
+    const clip = (s) => (s.length > cap ? `${s.slice(0, cap)}…` : s);
+    const out = [];
+    const push = (role, text) => {
+        const line = clip(text);
+        if (line)
+            out.push({ role, text: line });
+    };
+    for (const e of [...events].sort((a, b) => a.seq - b.seq)) {
+        if (e.kind !== 'log' && e.kind !== 'tool-call')
+            continue;
+        const body = decode(e.payload);
+        if (typeof body === 'string') {
+            push('out', body);
+            continue;
+        }
+        if (!body)
+            continue;
+        const step = str(body.step);
+        const message = str(body.message) || str(body.text) || str(body.command);
+        const stdout = str(body.stdout);
+        const stderr = str(body.stderr);
+        if (e.kind === 'tool-call' && step)
+            push('cmd', step);
+        if (message && message !== step)
+            push('out', message);
+        if (stdout)
+            push('out', stdout);
+        if (stderr)
+            push('out', stderr);
+    }
+    return out.slice(-400);
+}
+/** Tool calls, in the order they were first named. A later status for the same step wins. */
+export function steps(events) {
+    const order = [];
+    const done = new Map();
+    for (const e of [...events].sort((a, b) => a.seq - b.seq)) {
+        if (e.kind !== 'tool-call')
+            continue;
+        const body = decode(e.payload);
+        if (!body || typeof body === 'string')
+            continue;
+        const name = str(body.step);
+        if (!name)
+            continue;
+        if (!done.has(name))
+            order.push(name);
+        const status = str(body.status);
+        done.set(name, status === 'ok' || status === 'done' || status === 'error');
+    }
+    return order.map((name) => ({ name, done: done.get(name) === true }));
+}
 /**
  * What the run narrated about how it ended, latest winning. Status text only:
  * the branch and the pull request are read from the run's record (`pull`).

package/lib/api/work.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Projects and issues, as the forge holds them.
+ *
+ * A project is a board. A board is a repository that has work on it, so the
+ * list is the forge's answer and not a second copy of it.
+ *
+ *   GET /v1/task/projects                     the boards
+ *   GET /v1/task/board                        every board's issues
+ *   GET /v1/task/projects/{key}/issues        one board's issues
+ *
+ * Creating, renaming and deleting a board are forge operations. This surface
+ * reads the work and opens a run against it.
+ */
+import { type Target } from './call.ts';
+export interface Board {
+    id: string;
+    key: string;
+    name: string;
+    description: string;
+}
+export interface Work {
+    id: string;
+    /** `<key>#<number>`, the handle a person reads. */
+    identifier: string;
+    project: string;
+    number: number;
+    kind: string;
+    title: string;
+    status: string;
+    priority: string;
+    assignee: string;
+    /** The repository the item is bound to, or ''. */
+    repo: string;
+}
+export declare function board(raw: unknown): Board | null;
+export declare function work(raw: unknown): Work | null;
+export declare function boards(t: Target): Promise<Board[]>;
+/** A board's issues, or every board's when `key` is empty. */
+export declare function issues(t: Target, key?: string): Promise<Work[]>;

package/lib/api/work.js

@@ -0,0 +1,67 @@
+/**
+ * Projects and issues, as the forge holds them.
+ *
+ * A project is a board. A board is a repository that has work on it, so the
+ * list is the forge's answer and not a second copy of it.
+ *
+ *   GET /v1/task/projects                     the boards
+ *   GET /v1/task/board                        every board's issues
+ *   GET /v1/task/projects/{key}/issues        one board's issues
+ *
+ * Creating, renaming and deleting a board are forge operations. This surface
+ * reads the work and opens a run against it.
+ */
+import { call, seg } from './call.js';
+const str = (v) => (typeof v === 'string' ? v : '');
+const obj = (v) => v && typeof v === 'object' ? v : {};
+function rows(raw) {
+    if (Array.isArray(raw))
+        return raw;
+    const o = obj(raw);
+    if (Array.isArray(o.data))
+        return o.data;
+    if (Array.isArray(o.issues))
+        return o.issues;
+    return [];
+}
+export function board(raw) {
+    const o = obj(raw);
+    const key = str(o.key);
+    if (!key)
+        return null;
+    return { id: str(o.id) || key, key, name: str(o.name) || key, description: str(o.description) };
+}
+export function work(raw) {
+    const o = obj(raw);
+    const title = str(o.title);
+    const project = str(o.projectKey);
+    const number = typeof o.number === 'number' ? o.number : 0;
+    if (!title && !project)
+        return null;
+    return {
+        id: str(o.id) || `${project}#${number}`,
+        identifier: str(o.identifier) || (project && number ? `${project}#${number}` : ''),
+        project,
+        number,
+        kind: str(o.kind) || 'issue',
+        title: title || 'Untitled',
+        status: str(o.status) || 'backlog',
+        priority: str(o.priority) || 'none',
+        assignee: str(o.assignee),
+        repo: str(o.repo),
+    };
+}
+export async function boards(t) {
+    const raw = await call(t, 'GET', '/v1/task/projects');
+    return rows(raw)
+        .map(board)
+        .filter((b) => b !== null);
+}
+/** A board's issues, or every board's when `key` is empty. */
+export async function issues(t, key = '') {
+    const path = key ? `/v1/task/projects/${seg(key)}/issues` : '/v1/task/board';
+    const raw = await call(t, 'GET', path);
+    return rows(raw)
+        .map(work)
+        .filter((w) => w !== null);
+}