@hanzo/build 0.2.0

package/lib/api/git.d.ts

@@ -0,0 +1,27 @@
+/**
+ * A repository's files at one revision, from the platform's native git.
+ *
+ *   GET /v1/git/repos/{name}/tree?ref=&path=   one directory, dirs first
+ *   GET /v1/git/repos/{name}/blob?ref=&path=   one file; binary is base64,
+ *                                              past 1 MiB it is truncated with no content
+ *
+ * A run pushes its branch to native git, so these read what a run wrote at the
+ * branch it wrote it on.
+ */
+import { type Target } from './call.ts';
+export interface Entry {
+    name: string;
+    path: string;
+    dir: boolean;
+    size: number;
+}
+export interface Blob {
+    path: string;
+    /** Text, or '' when the file is binary or past the view cap. */
+    text: string;
+    binary: boolean;
+    truncated: boolean;
+    size: number;
+}
+export declare function tree(t: Target, repo: string, ref: string, path?: string): Promise<Entry[]>;
+export declare function blob(t: Target, repo: string, ref: string, path: string): Promise<Blob>;

package/lib/api/git.js

@@ -0,0 +1,39 @@
+/**
+ * A repository's files at one revision, from the platform's native git.
+ *
+ *   GET /v1/git/repos/{name}/tree?ref=&path=   one directory, dirs first
+ *   GET /v1/git/repos/{name}/blob?ref=&path=   one file; binary is base64,
+ *                                              past 1 MiB it is truncated with no content
+ *
+ * A run pushes its branch to native git, so these read what a run wrote at the
+ * branch it wrote it on.
+ */
+import { call, query, seg } from './call.js';
+const str = (v) => (typeof v === 'string' ? v : '');
+export async function tree(t, repo, ref, path = '') {
+    const raw = await call(t, 'GET', `/v1/git/repos/${seg(repo)}/tree${query({ ref, path })}`);
+    const rows = Array.isArray(raw?.entries) ? raw.entries : [];
+    return rows
+        .map((r) => {
+        const o = (r && typeof r === 'object' ? r : {});
+        return {
+            name: str(o.name),
+            path: str(o.path),
+            dir: o.type === 'tree',
+            size: typeof o.size === 'number' ? o.size : 0,
+        };
+    })
+        .filter((e) => e.path);
+}
+export async function blob(t, repo, ref, path) {
+    const o = (await call(t, 'GET', `/v1/git/repos/${seg(repo)}/blob${query({ ref, path })}`)) ?? {};
+    const binary = o.binary === true;
+    const truncated = o.truncated === true;
+    return {
+        path: str(o.path) || path,
+        text: binary || truncated ? '' : str(o.content),
+        binary,
+        truncated,
+        size: typeof o.size === 'number' ? o.size : 0,
+    };
+}

package/lib/api/github.d.ts

@@ -0,0 +1,78 @@
+/**
+ * GitHub, as the platform's GitHub App sees it for the signed-in person.
+ *
+ *   GET  /v1/provider/github/repos?q=&owner=&limit=&after=           most recently pushed first
+ *   GET  /v1/provider/github/repos/{owner}/{repo}/branches?q=&limit=&after=   default first
+ *   GET  /v1/provider/github/user              the person's own connection
+ *   POST /v1/provider/github/user/connect      → {authorizeUrl}
+ *   POST /v1/provider/github/user/disconnect
+ *
+ * Paged by an opaque `after` cursor; `next` is the cursor for the page after
+ * this one, or empty on the last. Rows are read defensively: a field the
+ * platform left out is an empty value here, never `undefined` in a label.
+ *
+ * `connected` false with repositories is an org admin seeing the org's
+ * installations; false with none is the cue to connect. GitHub returns a
+ * connecting person to the console's /connectors?complete=github&grant=<id>,
+ * which completes it.
+ */
+import { type Target } from './call.ts';
+export interface Repo {
+    owner: string;
+    name: string;
+    /** `owner/name`. */
+    full_name: string;
+    private: boolean;
+    default_branch: string;
+    /** RFC 3339, or '' when GitHub did not say. */
+    pushed_at: string;
+    /** The App installation that grants access, or 0 for the person's own grant. */
+    installation_id: number;
+}
+export interface Repos {
+    repos: Repo[];
+    next: string;
+    /** How many repositories match, across every page. */
+    total: number;
+    /** The installations that could not be read: a short list is then not the whole one. */
+    unread: string[];
+    /** Whether this answer is the person's OWN GitHub. */
+    connected: boolean;
+}
+export interface Branch {
+    name: string;
+    /** The sha it points at, or ''. */
+    commit: string;
+    default: boolean;
+}
+export interface Branches {
+    branches: Branch[];
+    next: string;
+    total: number;
+}
+export interface Connection {
+    /** Whether this deployment can connect anyone at all. */
+    configured: boolean;
+    connected: boolean;
+    /** The GitHub login, when connected. */
+    login: string;
+}
+export declare function repo(raw: unknown): Repo;
+export declare function branch(raw: unknown): Branch;
+export interface RepoQuery {
+    q?: string;
+    owner?: string;
+    limit?: number;
+    after?: string;
+}
+export declare function repos(t: Target, p?: RepoQuery, signal?: AbortSignal): Promise<Repos>;
+export interface BranchQuery {
+    q?: string;
+    limit?: number;
+    after?: string;
+}
+export declare function branches(t: Target, owner: string, name: string, p?: BranchQuery, signal?: AbortSignal): Promise<Branches>;
+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>;

package/lib/api/github.js

@@ -0,0 +1,73 @@
+/**
+ * GitHub, as the platform's GitHub App sees it for the signed-in person.
+ *
+ *   GET  /v1/provider/github/repos?q=&owner=&limit=&after=           most recently pushed first
+ *   GET  /v1/provider/github/repos/{owner}/{repo}/branches?q=&limit=&after=   default first
+ *   GET  /v1/provider/github/user              the person's own connection
+ *   POST /v1/provider/github/user/connect      → {authorizeUrl}
+ *   POST /v1/provider/github/user/disconnect
+ *
+ * Paged by an opaque `after` cursor; `next` is the cursor for the page after
+ * this one, or empty on the last. Rows are read defensively: a field the
+ * platform left out is an empty value here, never `undefined` in a label.
+ *
+ * `connected` false with repositories is an org admin seeing the org's
+ * installations; false with none is the cue to connect. GitHub returns a
+ * connecting person to the console's /connectors?complete=github&grant=<id>,
+ * which completes it.
+ */
+import { call, query, seg } from './call.js';
+const str = (v) => (typeof v === 'string' ? v : '');
+const num = (v) => (typeof v === 'number' && Number.isFinite(v) ? v : 0);
+const obj = (v) => v && typeof v === 'object' ? v : {};
+export function repo(raw) {
+    const r = obj(raw);
+    const owner = str(r.owner);
+    const name = str(r.name);
+    return {
+        owner,
+        name,
+        full_name: str(r.full_name) || (owner && name ? `${owner}/${name}` : name),
+        private: r.private === true,
+        default_branch: str(r.default_branch),
+        pushed_at: str(r.pushed_at),
+        installation_id: num(r.installation_id),
+    };
+}
+export function branch(raw) {
+    const b = obj(raw);
+    return { name: str(b.name), commit: str(b.commit), default: b.default === true };
+}
+export async function repos(t, p = {}, signal) {
+    const raw = obj(await call(t, 'GET', `/v1/provider/github/repos${query({ q: p.q?.trim(), owner: p.owner, limit: p.limit ?? 50, after: p.after })}`, undefined, { signal }));
+    return {
+        repos: (Array.isArray(raw.repos) ? raw.repos : []).map(repo).filter((r) => r.name),
+        next: str(raw.next),
+        total: num(raw.total),
+        unread: (Array.isArray(raw.unread) ? raw.unread : []).filter((x) => typeof x === 'string'),
+        connected: raw.connected === true,
+    };
+}
+export async function branches(t, owner, name, p = {}, signal) {
+    const raw = obj(await call(t, 'GET', `/v1/provider/github/repos/${seg(owner)}/${seg(name)}/branches${query({ q: p.q?.trim(), limit: p.limit ?? 50, after: p.after })}`, undefined, { signal }));
+    return {
+        branches: (Array.isArray(raw.branches) ? raw.branches : []).map(branch).filter((b) => b.name),
+        next: str(raw.next),
+        total: num(raw.total),
+    };
+}
+export async function connection(t) {
+    const raw = obj(await call(t, 'GET', '/v1/provider/github/user'));
+    return { configured: raw.configured === true, connected: raw.connected === true, login: str(raw.login) };
+}
+/** Where to send the person to authorize the platform's GitHub App — github.com only. */
+export async function connect(t) {
+    const raw = obj(await call(t, 'POST', '/v1/provider/github/user/connect'));
+    const url = str(raw.authorizeUrl);
+    if (!/^https:\/\/github\.com\//.test(url))
+        throw new Error('The platform did not name a GitHub address to connect at');
+    return url;
+}
+export async function disconnect(t) {
+    await call(t, 'POST', '/v1/provider/github/user/disconnect');
+}

package/lib/api/models.d.ts

@@ -0,0 +1,17 @@
+/**
+ * The models a run can be routed through, from the platform's own catalog.
+ *
+ *   GET /v1/models → {data: [{id, …}]}
+ *
+ * `enso` is the router: it picks a model per step, which is why it is the
+ * default and why it is not a model a person has to understand to use.
+ */
+import { type Target } from './call.ts';
+export interface Model {
+    id: string;
+    label: string;
+}
+export declare const ENSO = "enso";
+/** A readable name for an id: `anthropic/claude-opus-5.5` → `Claude Opus 5.5`, `zen5-coder` → `Zen5 Coder`. */
+export declare function label(id: string): string;
+export declare function models(t: Target): Promise<Model[]>;

package/lib/api/models.js

@@ -0,0 +1,28 @@
+/**
+ * The models a run can be routed through, from the platform's own catalog.
+ *
+ *   GET /v1/models → {data: [{id, …}]}
+ *
+ * `enso` is the router: it picks a model per step, which is why it is the
+ * default and why it is not a model a person has to understand to use.
+ */
+import { call } from './call.js';
+export const ENSO = 'enso';
+/** A readable name for an id: `anthropic/claude-opus-5.5` → `Claude Opus 5.5`, `zen5-coder` → `Zen5 Coder`. */
+export function label(id) {
+    const tail = id.slice(id.lastIndexOf('/') + 1).replace(/:.*$/, '');
+    return tail
+        .split('-')
+        .filter(Boolean)
+        .map((w) => (/^\d/.test(w) ? w : w[0].toUpperCase() + w.slice(1)))
+        .join(' ');
+}
+export async function models(t) {
+    const raw = await call(t, 'GET', '/v1/models');
+    const rows = Array.isArray(raw?.data) ? raw.data : [];
+    const ids = rows
+        .map((r) => (r && typeof r === 'object' && typeof r.id === 'string' ? r.id : ''))
+        .filter((id) => id && !id.endsWith(':batch'));
+    const out = [...new Set([ENSO, ...ids])];
+    return out.map((id) => ({ id, label: label(id) }));
+}

package/lib/api/places.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Where a run can run: the platform's sandbox, or one of the org's machines.
+ *
+ *   GET /v1/agent/targets → {targets: [...]}, newest first
+ *
+ * The sandbox is not a row the platform lists — it is what a run gets when it
+ * names no target — so it is the first place here and carries no id. A machine
+ * can take a run only while it is online.
+ */
+import { type Target } from './call.ts';
+export interface Place {
+    /** `tgt_…`, or '' for the sandbox. */
+    id: string;
+    label: string;
+    /** laptop | gpu | cloud | … as the platform names it; 'sandbox' for the sandbox. */
+    kind: string;
+    /** online | offline | draining; the sandbox is always online. */
+    status: string;
+    /** "10 vCPU / 122G / 1× GB10", when the machine reported one. */
+    capacity: string;
+}
+export declare const SANDBOX: Place;
+export declare function places(t: Target): Promise<Place[]>;
+/** Whether a run sent here now would be taken. */
+export declare const ready: (p: Place) => boolean;

package/lib/api/places.js

@@ -0,0 +1,31 @@
+/**
+ * Where a run can run: the platform's sandbox, or one of the org's machines.
+ *
+ *   GET /v1/agent/targets → {targets: [...]}, newest first
+ *
+ * The sandbox is not a row the platform lists — it is what a run gets when it
+ * names no target — so it is the first place here and carries no id. A machine
+ * can take a run only while it is online.
+ */
+import { call } from './call.js';
+export const SANDBOX = { id: '', label: 'Hanzo sandbox', kind: 'sandbox', status: 'online', capacity: '' };
+const str = (v) => (typeof v === 'string' ? v : '');
+export async function places(t) {
+    const raw = (await call(t, 'GET', '/v1/agent/targets')) ?? {};
+    const rows = Array.isArray(raw.targets) ? raw.targets : [];
+    const machines = rows
+        .map((r) => {
+        const o = (r && typeof r === 'object' ? r : {});
+        return {
+            id: str(o.id),
+            label: str(o.label) || str(o.host) || str(o.id),
+            kind: str(o.kind),
+            status: str(o.status),
+            capacity: str(o.capacity),
+        };
+    })
+        .filter((p) => p.id);
+    return [SANDBOX, ...machines];
+}
+/** Whether a run sent here now would be taken. */
+export const ready = (p) => p.status === 'online';

package/lib/api/platform.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Adding a repository to a project, which is how a project is published.
+ *
+ *   POST /v1/platform/apps {repo, ref, name, partOf, mode, tag?}
+ *     → 202 {app, build?: {id, job, image, status}, declaration: {mode, ref, review, live, …}}
+ *   GET  /v1/platform/builds → {builds: [{id, repo, commit, status, startedAt, duration}]}
+ *
+ * The declaration is a values file in universe. `branch` (the default) opens a
+ * review and deploys nothing; `commit` writes main and CD applies it — and it
+ * refuses to name an image that is not built yet, so publishing to main is two
+ * calls: build on a branch, then commit that tag once the build is green. An
+ * org admin gets both; anyone else gets the review link.
+ */
+import { type Target } from './call.ts';
+export interface Declare {
+    /** The https clone URL. */
+    repo: string;
+    /** Branch, tag or sha to build. */
+    ref: string;
+    /** The app's name: a DNS-1123 label. */
+    name: string;
+    /** The project it joins. */
+    project: string;
+    mode: 'branch' | 'commit';
+    /** Release an image an earlier call built, instead of building. */
+    tag?: string;
+}
+export interface Declared {
+    build: {
+        id: string;
+        job: string;
+        image: string;
+        status: string;
+    } | null;
+    mode: string;
+    /** Where the declaration landed: main for a commit, the review branch otherwise. */
+    ref: string;
+    /** The pull request to open for a branch write, or ''. */
+    review: string;
+    /** Whether anything can deploy from this write. */
+    live: boolean;
+}
+export interface Build {
+    id: string;
+    repo: string;
+    commit: string;
+    status: string;
+    startedAt: string;
+    duration: string;
+}
+/** A DNS-1123 label from anything: what an app may be named. */
+export declare function label(s: string): string;
+/** An https address, or '' — a review link is shown as a link only when it is one. */
+export declare const https: (url: string) => string;
+export declare function body(d: Declare): Record<string, string>;
+export declare function declare(t: Target, d: Declare): Promise<Declared>;
+export declare function builds(t: Target): Promise<Build[]>;
+/** The clone URL for a GitHub repository. */
+export declare const clone: (fullName: string) => string;

package/lib/api/platform.js

@@ -0,0 +1,69 @@
+/**
+ * Adding a repository to a project, which is how a project is published.
+ *
+ *   POST /v1/platform/apps {repo, ref, name, partOf, mode, tag?}
+ *     → 202 {app, build?: {id, job, image, status}, declaration: {mode, ref, review, live, …}}
+ *   GET  /v1/platform/builds → {builds: [{id, repo, commit, status, startedAt, duration}]}
+ *
+ * The declaration is a values file in universe. `branch` (the default) opens a
+ * review and deploys nothing; `commit` writes main and CD applies it — and it
+ * refuses to name an image that is not built yet, so publishing to main is two
+ * calls: build on a branch, then commit that tag once the build is green. An
+ * org admin gets both; anyone else gets the review link.
+ */
+import { call } from './call.js';
+const str = (v) => (typeof v === 'string' ? v : '');
+const obj = (v) => v && typeof v === 'object' ? v : {};
+/** A DNS-1123 label from anything: what an app may be named. */
+export function label(s) {
+    const out = s
+        .toLowerCase()
+        .replace(/[^a-z0-9-]+/g, '-')
+        .replace(/-+/g, '-')
+        .replace(/^-+|-+$/g, '')
+        .slice(0, 63)
+        .replace(/-+$/g, '');
+    return out || 'app';
+}
+/** An https address, or '' — a review link is shown as a link only when it is one. */
+export const https = (url) => (/^https:\/\/[^\s]+$/.test(url) ? url : '');
+export function body(d) {
+    const out = {
+        repo: d.repo,
+        ref: d.ref || 'main',
+        name: label(d.name),
+        partOf: label(d.project),
+        mode: d.mode,
+    };
+    if (d.tag)
+        out.tag = d.tag;
+    return out;
+}
+export async function declare(t, d) {
+    const raw = obj(await call(t, 'POST', '/v1/platform/apps', body(d)));
+    const b = raw.build ? obj(raw.build) : null;
+    const dec = obj(raw.declaration);
+    return {
+        build: b ? { id: str(b.id), job: str(b.job), image: str(b.image), status: str(b.status) } : null,
+        mode: str(dec.mode),
+        ref: str(dec.ref),
+        review: https(str(dec.review)),
+        live: dec.live === true,
+    };
+}
+export async function builds(t) {
+    const raw = obj(await call(t, 'GET', '/v1/platform/builds'));
+    return (Array.isArray(raw.builds) ? raw.builds : []).map((r) => {
+        const o = obj(r);
+        return {
+            id: str(o.id),
+            repo: str(o.repo),
+            commit: str(o.commit),
+            status: str(o.status),
+            startedAt: str(o.startedAt),
+            duration: str(o.duration),
+        };
+    });
+}
+/** The clone URL for a GitHub repository. */
+export const clone = (fullName) => `https://github.com/${fullName}.git`;

package/lib/api/projects.d.ts

@@ -0,0 +1,52 @@
+/**
+ * The org's projects: what it has built, and where each one is served.
+ *
+ *   GET /v1/projects → Project[]
+ *
+ * `slug` is the one key every surface shares — the address under /dev, the
+ * site's name, the `project` a run is tagged with.
+ */
+import { type Target } from './call.ts';
+export interface Project {
+    slug: string;
+    name: string;
+    /** The clone URL, or '' for a project with no repository. */
+    repo: string;
+    /** The branch pushes to which rebuild it, or ''. */
+    branch: string;
+    status: string;
+    /** The deployed address, or '' when nothing has shipped. */
+    live: string;
+    updated: number;
+}
+/** An address the preview may frame: https, or http on loopback when the builder is local too. */
+export declare function safe(url: string, local?: boolean): string;
+export declare function project(raw: unknown): Project;
+export declare function projects(t: Target): Promise<Project[]>;
+/** The repository name a project's clone URL names — the last path segment, without `.git`. */
+export declare function name(clone: string): string;
+/** A starter from the public catalog. */
+export interface Template {
+    slug: string;
+    title: string;
+    category: string;
+    description: string;
+    framework: string;
+    /** The repository the starter is cut from. */
+    source: string;
+}
+/** The public catalog. It is reference content: no bearer, no org. */
+export declare function templates(t: Target): Promise<Template[]>;
+/**
+ * Take a copy of a starter: a project whose repository is the starter's own,
+ * so what opens is that template rather than a model's imitation of it.
+ */
+export declare function fork(t: Target, slug: string): Promise<Project>;
+/** `owner/name` from a clone URL — its last two path segments, without `.git`. */
+export declare function address(clone: string): string;
+/**
+ * Whether a run worked on this project's repository. A run's record can be
+ * moved into any project of the org, so a project shows only the runs on its
+ * own code — their branch is what Files, Code and Publish read.
+ */
+export declare function ours(runRepo: string, projectClone: string): boolean;

package/lib/api/projects.js

@@ -0,0 +1,97 @@
+/**
+ * The org's projects: what it has built, and where each one is served.
+ *
+ *   GET /v1/projects → Project[]
+ *
+ * `slug` is the one key every surface shares — the address under /dev, the
+ * site's name, the `project` a run is tagged with.
+ */
+import { call } from './call.js';
+const str = (v) => (typeof v === 'string' ? v : '');
+const loopback = (host) => host === 'localhost' || host === '127.0.0.1';
+/** Whether this page itself is served from loopback — local work. */
+const here = () => typeof window !== 'undefined' && loopback(window.location.hostname);
+/** An address the preview may frame: https, or http on loopback when the builder is local too. */
+export function safe(url, local = here()) {
+    try {
+        const u = new URL(url);
+        if (u.protocol === 'https:')
+            return u.toString();
+        // Loopback only for a builder that is itself on loopback: a published row
+        // must not point colleagues' browsers at their own local services.
+        if (local && u.protocol === 'http:' && loopback(u.hostname))
+            return u.toString();
+    }
+    catch {
+        /* not an address */
+    }
+    return '';
+}
+export function project(raw) {
+    const p = (raw && typeof raw === 'object' ? raw : {});
+    const repo = (p.repo && typeof p.repo === 'object' ? p.repo : {});
+    return {
+        slug: str(p.slug),
+        name: str(p.name) || str(p.slug),
+        repo: str(repo.url),
+        branch: str(repo.branch),
+        status: str(p.status),
+        live: safe(str(p.liveUrl)),
+        updated: typeof p.updatedAt === 'number' ? p.updatedAt : 0,
+    };
+}
+export async function projects(t) {
+    const raw = await call(t, 'GET', '/v1/projects');
+    const rows = Array.isArray(raw) ? raw : Array.isArray(raw?.data) ? raw.data : [];
+    return rows
+        .map(project)
+        .filter((p) => p.slug)
+        .sort((a, b) => b.updated - a.updated);
+}
+/** The repository name a project's clone URL names — the last path segment, without `.git`. */
+export function name(clone) {
+    const cut = clone.replace(/\.git$/, '').replace(/\/+$/, '');
+    return cut.slice(cut.lastIndexOf('/') + 1);
+}
+/** The public catalog. It is reference content: no bearer, no org. */
+export async function templates(t) {
+    const raw = await call({ api: t.api, token: () => null, org: null }, 'GET', '/v1/templates');
+    const rows = Array.isArray(raw?.data) ? raw.data : [];
+    return rows
+        .map((r) => {
+        const o = (r && typeof r === 'object' ? r : {});
+        return {
+            slug: str(o.slug),
+            title: str(o.title) || str(o.slug),
+            category: str(o.category),
+            description: str(o.description),
+            framework: str(o.framework),
+            source: str(o.source),
+        };
+    })
+        .filter((x) => x.slug);
+}
+/**
+ * Take a copy of a starter: a project whose repository is the starter's own,
+ * so what opens is that template rather than a model's imitation of it.
+ */
+export async function fork(t, slug) {
+    return project(await call(t, 'POST', '/v1/projects/fork', { slug }));
+}
+/** `owner/name` from a clone URL — its last two path segments, without `.git`. */
+export function address(clone) {
+    const parts = clone.replace(/\.git$/, '').replace(/\/+$/, '').split('/');
+    return parts.length >= 2 ? `${parts[parts.length - 2]}/${parts[parts.length - 1]}` : '';
+}
+/**
+ * Whether a run worked on this project's repository. A run's record can be
+ * moved into any project of the org, so a project shows only the runs on its
+ * own code — their branch is what Files, Code and Publish read.
+ */
+export function ours(runRepo, projectClone) {
+    if (!projectClone)
+        return true;
+    const want = address(projectClone).toLowerCase();
+    const have = runRepo.toLowerCase();
+    return have === want || (!have.includes('/') && have === want.split('/')[1]);
+}