@fungi.computer/burrow 0.0.0-stage → 0.0.1

package/dist/namespace.d.ts

@@ -0,0 +1,93 @@
+/** Host-only Artifacts namespace. Repository credentials never enter App results. */
+export type ArtifactsRepositoryInfo = Readonly<{
+    id: string;
+    name: string;
+    defaultBranch: string;
+    remote: string;
+    lastPushAt?: string | null;
+    source?: string | null;
+}>;
+/** Initial revocation reference: a Workers token or an already-revoked REST ID. */
+export type ArtifactsCreatedRepository = ArtifactsRepositoryInfo & Readonly<{
+    token: string;
+}>;
+/** Provider commit metadata and parent object IDs. */
+export type ArtifactsCommit = Readonly<{
+    hash: string;
+    treeHash: string;
+    message: string;
+    author: Readonly<{
+        name: string;
+        email: string;
+    }>;
+    committer: Readonly<{
+        name: string;
+        email: string;
+    }>;
+    parents: readonly string[];
+    authoredAt: number;
+    committedAt: number;
+}>;
+/** One provider tree entry, including its mode and object kind. */
+export type ArtifactsTreeEntry = Readonly<{
+    name: string;
+    mode: string;
+    hash: string;
+    type: "blob" | "tree" | "commit";
+}>;
+/** Host-only repository operations; secrets never belong in App results. */
+export type ArtifactsRepositoryHandle = Readonly<{
+    /** Read current provider repository metadata. */
+    info(): Promise<ArtifactsRepositoryInfo>;
+    /** Mint a read or write credential for the requested lifetime; keep it host-only. */
+    createToken(scope: "read" | "write", ttl: number): Promise<Readonly<{
+        id: string;
+        plaintext: string;
+        expiresAt: string;
+    }>>;
+    /** Revoke this exact token or token ID; false means it is no longer present. */
+    revokeToken(tokenOrId: string): Promise<boolean>;
+    /** Fork this repository and return the new destination with its revocation reference. */
+    fork(name: string, options: {
+        description?: string;
+        readOnly: false;
+        defaultBranchOnly: boolean;
+    }): Promise<ArtifactsCreatedRepository>;
+    /** Read a bounded page of commits at the requested ref. */
+    log(options: {
+        ref: string;
+        limit: number;
+        offset: number;
+    }): Promise<readonly ArtifactsCommit[]>;
+    /** Read one commit object, or null if that object is absent. */
+    readCommit(hash: string): Promise<ArtifactsCommit | null>;
+    /** Read one tree object, or null if that object is absent. */
+    readTree(hash: string): Promise<readonly ArtifactsTreeEntry[] | null>;
+    /** Read one blob object, or null if that object is absent. */
+    readBlob(hash: string): Promise<Blob | null>;
+}>;
+/** Configured provider namespace with repository-name-addressed handles. */
+export type ArtifactsNamespace = Readonly<{
+    /** Create a repository; its initial credential must be revoked before activation. */
+    create(name: string, options: {
+        description?: string;
+        readOnly: false;
+        setDefaultBranch: string;
+    }): Promise<ArtifactsCreatedRepository>;
+    /** Address a repository handle; its operations establish live provider availability. */
+    get(name: string): Promise<ArtifactsRepositoryHandle>;
+    /** Read a bounded repository-status page and its optional next cursor. */
+    list(options?: {
+        limit?: number;
+        cursor?: string;
+    }): Promise<Readonly<{
+        repos: readonly Readonly<{
+            name: string;
+            status: string;
+        }>[];
+        total: number;
+        cursor?: string;
+    }>>;
+    /** Delete the named repository; return false when it is already absent. */
+    delete(name: string): Promise<boolean>;
+}>;

package/dist/namespace.js

@@ -0,0 +1 @@
+export {};

package/dist/rest.d.ts

@@ -0,0 +1,17 @@
+import type { ArtifactsNamespace } from "./namespace.js";
+/** Where the REST API is and how to reach it. */
+export type ArtifactsRestOptions = Readonly<{
+    accountId: string;
+    namespace: string;
+    /** A Cloudflare API token with Artifacts read and write. */
+    apiToken: string;
+    /** Defaults to the global `fetch`. */
+    fetch?: typeof fetch;
+}>;
+/** A failed Artifacts REST call, with the binding's error `code`. */
+export declare class ArtifactsRestError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+/** An Artifacts namespace reached over REST, with the binding's shape. */
+export declare function createArtifactsRestNamespace(options: ArtifactsRestOptions): ArtifactsNamespace;

package/dist/rest.js

@@ -0,0 +1,288 @@
+import * as Schema from "effect/Schema";
+const repoSchema = Schema.Struct({
+    id: Schema.String,
+    name: Schema.String,
+    default_branch: Schema.String,
+    remote: Schema.String,
+    last_push_at: Schema.optional(Schema.NullOr(Schema.String)),
+    source: Schema.optional(Schema.NullOr(Schema.String)),
+    status: Schema.optional(Schema.String),
+});
+const envelopeSchema = Schema.Struct({
+    success: Schema.Boolean,
+    result: Schema.Unknown,
+    errors: Schema.Array(Schema.Struct({ code: Schema.Number, message: Schema.String })),
+    result_info: Schema.optional(Schema.Struct({
+        cursor: Schema.optional(Schema.NullOr(Schema.String)),
+        total_pages: Schema.optional(Schema.Number),
+        total_count: Schema.optional(Schema.Number),
+    })),
+});
+const tokenSchema = Schema.Struct({
+    id: Schema.NonEmptyString,
+    plaintext: Schema.NonEmptyString,
+    expires_at: Schema.NonEmptyString,
+});
+const createdSchema = Schema.Struct({
+    ...repoSchema.fields,
+    token: Schema.NonEmptyString,
+});
+const listedTokensSchema = Schema.Array(Schema.Struct({
+    id: Schema.NonEmptyString,
+    state: Schema.Literals(["active", "expired", "revoked"]),
+}));
+/** The string codes the binding throws, from the REST API's numeric codes. */
+const errorCodes = new Map([
+    [10200, "NOT_FOUND"],
+    [10201, "ALREADY_EXISTS"],
+    [10302, "IMPORT_IN_PROGRESS"],
+    [10303, "FORK_IN_PROGRESS"],
+]);
+/** A failed Artifacts REST call, with the binding's error `code`. */
+export class ArtifactsRestError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+    }
+}
+function decode(schema, raw) {
+    try {
+        return Schema.decodeUnknownSync(schema)(raw);
+    }
+    catch {
+        throw new ArtifactsRestError("INVALID_RESPONSE", "Artifacts returned an invalid response");
+    }
+}
+function toInfo(repo) {
+    return {
+        id: repo.id,
+        name: repo.name,
+        defaultBranch: repo.default_branch,
+        remote: repo.remote,
+        lastPushAt: repo.last_push_at ?? null,
+        source: repo.source ?? null,
+    };
+}
+/** An Artifacts namespace reached over REST, with the binding's shape. */
+export function createArtifactsRestNamespace(options) {
+    const base = `https://api.cloudflare.com/client/v4/accounts/${encodeURIComponent(options.accountId)}/artifacts/namespaces/${encodeURIComponent(options.namespace)}`;
+    const send = options.fetch ?? ((input, init) => fetch(input, init));
+    const request = async (path, init = {}) => {
+        const headers = new Headers(init.headers);
+        headers.set("Authorization", `Bearer ${options.apiToken}`);
+        if (init.body !== undefined)
+            headers.set("Content-Type", "application/json");
+        return send(`${base}${path}`, { ...init, headers, redirect: "manual" });
+    };
+    const json = async (path, init = {}) => {
+        const response = await request(path, init);
+        if (response.status >= 300 && response.status < 400) {
+            await response.body?.cancel();
+            throw new ArtifactsRestError("REDIRECT_REFUSED", "Artifacts redirect refused");
+        }
+        let raw;
+        try {
+            raw = await response.json();
+        }
+        catch {
+            throw new ArtifactsRestError("INVALID_RESPONSE", "Artifacts returned an invalid response");
+        }
+        const body = decode(envelopeSchema, raw);
+        if (!response.ok || !body.success) {
+            const [first] = body.errors;
+            throw new ArtifactsRestError((first && errorCodes.get(first.code)) ?? "INTERNAL_ERROR", `Artifacts request failed (${String(response.status)})`);
+        }
+        return body;
+    };
+    const bytes = async (path) => {
+        const response = await request(path);
+        if (response.status === 404) {
+            await response.body?.cancel();
+            return null;
+        }
+        if (!response.ok)
+            throw new ArtifactsRestError("INTERNAL_ERROR", `Artifacts read failed (${String(response.status)})`);
+        return new Uint8Array(await response.arrayBuffer());
+    };
+    const orNull = async (read) => {
+        try {
+            return await read();
+        }
+        catch (error) {
+            if (error instanceof ArtifactsRestError && error.code === "NOT_FOUND")
+                return null;
+            throw error;
+        }
+    };
+    const repoPath = (name) => `/repos/${encodeURIComponent(name)}`;
+    const revokedInitialTokenIds = new Set();
+    const mintedTokenIds = new Map();
+    const readInitialTokens = async (path) => {
+        const page = await json(path);
+        const tokens = decode(listedTokensSchema, page.result);
+        if (page.result_info?.total_pages !== 1 ||
+            page.result_info.total_count !== tokens.length ||
+            tokens.length > 100)
+            throw new Error("Artifacts initial token page is incomplete");
+        return tokens;
+    };
+    const finishCreated = async (name, raw) => {
+        try {
+            const created = Schema.decodeUnknownSync(createdSchema)(raw);
+            if (created.name !== name)
+                throw new Error("Artifacts repository identity conflicts");
+            const tokenPath = `${repoPath(name)}/tokens?state=all&per_page=100&page=1`;
+            const listed = await readInitialTokens(tokenPath);
+            const active = listed.filter((token) => token.state === "active");
+            const [initial] = active;
+            if (active.length !== 1 || !initial)
+                throw new Error("Artifacts initial token is ambiguous");
+            await json(`/tokens/${encodeURIComponent(initial.id)}`, {
+                method: "DELETE",
+            });
+            const verified = await readInitialTokens(tokenPath);
+            if (verified.filter((token) => token.id === initial.id && token.state === "revoked").length !== 1 ||
+                verified.some((token) => token.state === "active"))
+                throw new Error("Artifacts initial token revocation was not verified");
+            revokedInitialTokenIds.add(initial.id);
+            return { ...toInfo(created), token: initial.id };
+        }
+        catch {
+            // Only a successful create/fork reply reaches this cleanup. Existing
+            // repositories and the fork's source are never deleted by this path.
+            await json(repoPath(name), { method: "DELETE" });
+            throw new ArtifactsRestError("INITIAL_TOKEN_REFUSED", "Artifacts initial token cleanup refused repository activation");
+        }
+    };
+    return {
+        async create(name, opts) {
+            const created = await json("/repos", {
+                method: "POST",
+                body: JSON.stringify({
+                    name,
+                    description: opts.description,
+                    default_branch: opts.setDefaultBranch,
+                    read_only: false,
+                }),
+            });
+            return finishCreated(name, created.result);
+        },
+        async list(opts = {}) {
+            const query = new URLSearchParams({ limit: String(opts.limit ?? 200) });
+            if (opts.cursor !== undefined)
+                query.set("cursor", opts.cursor);
+            const page = await json(`/repos?${query.toString()}`);
+            const repos = decode(Schema.Array(repoSchema), page.result).map((repo) => ({
+                name: repo.name,
+                status: repo.status ?? "ready",
+            }));
+            const cursor = page.result_info?.cursor ?? undefined;
+            return cursor === undefined
+                ? { repos, total: repos.length }
+                : { repos, total: repos.length, cursor };
+        },
+        async delete(name) {
+            return ((await orNull(() => json(repoPath(name), { method: "DELETE" }))) !==
+                null);
+        },
+        async get(name) {
+            const path = repoPath(name);
+            return Promise.resolve({
+                async info() {
+                    return toInfo(decode(repoSchema, (await json(path)).result));
+                },
+                async createToken(scope, ttl) {
+                    const created = await json("/tokens", {
+                        method: "POST",
+                        body: JSON.stringify({ repo: name, scope, ttl }),
+                    });
+                    const token = decode(tokenSchema, created.result);
+                    mintedTokenIds.set(token.plaintext, token.id);
+                    return {
+                        id: token.id,
+                        plaintext: token.plaintext,
+                        expiresAt: token.expires_at,
+                    };
+                },
+                async revokeToken(tokenOrId) {
+                    if (revokedInitialTokenIds.delete(tokenOrId))
+                        return false;
+                    const id = mintedTokenIds.get(tokenOrId) ?? tokenOrId;
+                    const revoked = await orNull(() => json(`/tokens/${encodeURIComponent(id)}`, { method: "DELETE" }));
+                    for (const [plaintext, tokenId] of mintedTokenIds)
+                        if (tokenId === id)
+                            mintedTokenIds.delete(plaintext);
+                    return revoked !== null;
+                },
+                async fork(target, opts) {
+                    const forked = await json(`${path}/fork`, {
+                        method: "POST",
+                        body: JSON.stringify({
+                            name: target,
+                            description: opts.description,
+                            read_only: false,
+                            default_branch_only: opts.defaultBranchOnly,
+                        }),
+                    });
+                    return finishCreated(target, forked.result);
+                },
+                async log(opts) {
+                    const query = new URLSearchParams({
+                        ref: opts.ref,
+                        limit: String(opts.limit),
+                        offset: String(opts.offset),
+                    });
+                    const page = await orNull(() => json(`${path}/log?${query.toString()}`));
+                    // The binding answers an unknown ref with no history.
+                    return page === null
+                        ? []
+                        : decodeCommits(decode(Schema.Array(commitSchema), page.result));
+                },
+                async readCommit(hash) {
+                    const page = await orNull(() => json(`${path}/commit/${encodeURIComponent(hash)}`));
+                    return page === null
+                        ? null
+                        : (decodeCommits(decode(Schema.Array(commitSchema), [page.result]))[0] ?? null);
+                },
+                async readTree(hash) {
+                    const page = await orNull(() => json(`${path}/tree/${encodeURIComponent(hash)}`));
+                    return page === null
+                        ? null
+                        : decodeTree(decode(Schema.Array(treeSchema), page.result));
+                },
+                async readBlob(hash) {
+                    const content = await bytes(`${path}/blob/${encodeURIComponent(hash)}`);
+                    return content === null ? null : new Blob([new Uint8Array(content)]);
+                },
+            });
+        },
+    };
+}
+const commitSchema = Schema.Struct({
+    hash: Schema.String,
+    treeHash: Schema.String,
+    message: Schema.String,
+    author: Schema.Struct({ name: Schema.String, email: Schema.String }),
+    committer: Schema.Struct({ name: Schema.String, email: Schema.String }),
+    parents: Schema.Array(Schema.String),
+    authoredAt: Schema.Number,
+    committedAt: Schema.Number,
+});
+const treeSchema = Schema.Struct({
+    name: Schema.String,
+    mode: Schema.String,
+    hash: Schema.String,
+    type: Schema.Literals(["blob", "tree", "commit"]),
+});
+function decodeCommits(commits) {
+    return commits.map((commit) => ({
+        ...commit,
+        author: { ...commit.author },
+        committer: { ...commit.committer },
+        parents: [...commit.parents],
+    }));
+}
+function decodeTree(entries) {
+    return [...entries];
+}

package/docs/api/README.md

@@ -0,0 +1,15 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+**@fungi.computer/burrow**
+
+---
+
+# @fungi.computer/burrow
+
+## Modules
+
+| Module                      | Description |
+| --------------------------- | ----------- |
+| [cloudflare](cloudflare.md) | -           |
+| [index](index.md)           | -           |
+| [namespace](namespace.md)   | -           |

package/docs/api/cloudflare.md

@@ -0,0 +1,271 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+[**@fungi.computer/burrow**](README.md)
+
+---
+
+[@fungi.computer/burrow](README.md) / cloudflare
+
+# cloudflare
+
+## Classes
+
+### ArtifactsForkStuckError
+
+A repository did not finish importing or forking within the readiness window.
+
+#### Extends
+
+- `Error`
+
+#### Constructors
+
+##### Constructor
+
+```ts
+new ArtifactsForkStuckError(repository, status): ArtifactsForkStuckError;
+```
+
+###### Parameters
+
+| Parameter    | Type                                        |
+| ------------ | ------------------------------------------- |
+| `repository` | `string`                                    |
+| `status`     | `"importing"` \| `"forking"` \| `"missing"` |
+
+###### Returns
+
+[`ArtifactsForkStuckError`](#artifactsforkstuckerror)
+
+###### Overrides
+
+```ts
+Error.constructor;
+```
+
+#### Properties
+
+##### name
+
+```ts
+readonly name: "ArtifactsForkStuckError" = "ArtifactsForkStuckError";
+```
+
+###### Overrides
+
+```ts
+Error.name;
+```
+
+##### repository
+
+```ts
+readonly repository: string;
+```
+
+##### status
+
+```ts
+readonly status: "importing" | "forking" | "missing";
+```
+
+## Type Aliases
+
+### CloudflareArtifactsRepositoryHandle
+
+```ts
+type CloudflareArtifactsRepositoryHandle = Readonly<{
+  info?: () => Promise<ArtifactsRepositoryInfo>;
+  createToken: Promise<
+    Readonly<{
+      id: string;
+      plaintext: string;
+      expiresAt: string;
+    }>
+  >;
+  revokeToken: Promise<boolean>;
+  fork: Promise<
+    Readonly<{
+      id: string;
+      name: string;
+      remote: string;
+      defaultBranch: string;
+      token: string;
+    }>
+  >;
+}>;
+```
+
+Repository handle accepted by the Cloudflare Artifacts namespace.
+
+---
+
+### CloudflareArtifactsRepositoryMetadata
+
+```ts
+type CloudflareArtifactsRepositoryMetadata = Readonly<{
+  id: string;
+  name: string;
+  defaultBranch: string;
+  remote: string;
+  parentRepository: string | null;
+}>;
+```
+
+Provider identity recorded at creation; used to pin later remote access.
+
+---
+
+### CloudflareArtifactsRepositoryMetadataStore
+
+```ts
+type CloudflareArtifactsRepositoryMetadataStore = Readonly<{
+  read: Promise<Readonly<{
+    id: string;
+    name: string;
+    defaultBranch: string;
+    remote: string;
+    parentRepository: string | null;
+  }> | null>;
+  readPending: Promise<Readonly<{
+    metadata: CloudflareArtifactsRepositoryMetadata;
+    initialToken: string;
+  }> | null>;
+  recordPending: Promise<void>;
+  activate: Promise<void>;
+}>;
+```
+
+Host-owned durable metadata and pending initial-token revocation records.
+
+---
+
+### CloudflareArtifactsNamespace
+
+```ts
+type CloudflareArtifactsNamespace = Readonly<{
+  get: Promise<
+    Readonly<{
+      info?: () => Promise<ArtifactsRepositoryInfo>;
+      createToken: Promise<
+        Readonly<{
+          id: string;
+          plaintext: string;
+          expiresAt: string;
+        }>
+      >;
+      revokeToken: Promise<boolean>;
+      fork: Promise<
+        Readonly<{
+          id: string;
+          name: string;
+          remote: string;
+          defaultBranch: string;
+          token: string;
+        }>
+      >;
+    }>
+  >;
+  list: Promise<
+    Readonly<{
+      repos: readonly Readonly<{
+        name: string;
+      }>[];
+      total: number;
+      cursor?: string;
+    }>
+  >;
+  create: Promise<
+    Readonly<{
+      id: string;
+      name: string;
+      remote: string;
+      defaultBranch: string;
+      token: string;
+    }>
+  >;
+}>;
+```
+
+The maintained Cloudflare namespace methods used by this private adapter.
+
+---
+
+### CloudflareArtifactsRepositoryPage
+
+```ts
+type CloudflareArtifactsRepositoryPage = Readonly<{
+  repos: readonly Readonly<{
+    name: string;
+  }>[];
+  total: number;
+  cursor?: string;
+}>;
+```
+
+Repository listing page used to observe fork/import readiness.
+
+---
+
+### CloudflareArtifactsOptions
+
+```ts
+type CloudflareArtifactsOptions = Readonly<{
+  namespace: CloudflareArtifactsNamespace;
+  repositories: CloudflareArtifactsRepositoryMetadataStore;
+  gitHttp?: typeof http;
+  gitFetch?: typeof fetch;
+}>;
+```
+
+Provider, durable metadata store and optional Git protocol transports.
+
+## Functions
+
+### exchangeCloudflareArtifactsGit()
+
+```ts
+function exchangeCloudflareArtifactsGit(
+  metadata,
+  input,
+  credential,
+  gitFetch,
+): Promise<Response>;
+```
+
+Execute Git with an already-held repo credential. The custody owner chooses
+metadata and credential; caller URLs and authorization headers never enter.
+
+#### Parameters
+
+| Parameter    | Type                                                                                                                                         |
+| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------- |
+| `metadata`   | [`CloudflareArtifactsRepositoryMetadata`](#cloudflareartifactsrepositorymetadata)                                                            |
+| `input`      | [`GitExchange`](index.md#gitexchange)                                                                                                        |
+| `credential` | `string`                                                                                                                                     |
+| `gitFetch`   | \{ (`input`, `init?`): `Promise`\<`Response`\>; (`input`, `init?`): `Promise`\<`Response`\>; (`input`, `init?`): `Promise`\<`Response`\>; \} |
+
+#### Returns
+
+`Promise`\<`Response`\>
+
+---
+
+### createCloudflareArtifacts()
+
+```ts
+function createCloudflareArtifacts(options): Artifacts;
+```
+
+Configure the Artifacts owner once; provider remotes and credentials stay
+private.
+
+#### Parameters
+
+| Parameter | Type                                                        |
+| --------- | ----------------------------------------------------------- |
+| `options` | [`CloudflareArtifactsOptions`](#cloudflareartifactsoptions) |
+
+#### Returns
+
+[`Artifacts`](index.md#artifacts)