@fungi.computer/burrow 0.0.0-stage → 0.0.1

package/docs/api/index.md

@@ -0,0 +1,207 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+[**@fungi.computer/burrow**](README.md)
+
+---
+
+[@fungi.computer/burrow](README.md) / index
+
+# index
+
+## Classes
+
+### ArtifactsRestError
+
+A failed Artifacts REST call, with the binding's error `code`.
+
+#### Extends
+
+- `Error`
+
+#### Constructors
+
+##### Constructor
+
+```ts
+new ArtifactsRestError(code, message): ArtifactsRestError;
+```
+
+###### Parameters
+
+| Parameter | Type     |
+| --------- | -------- |
+| `code`    | `string` |
+| `message` | `string` |
+
+###### Returns
+
+[`ArtifactsRestError`](#artifactsresterror)
+
+###### Overrides
+
+```ts
+Error.constructor;
+```
+
+#### Properties
+
+##### code
+
+```ts
+readonly code: string;
+```
+
+## Type Aliases
+
+### ArtifactsRepository
+
+```ts
+type ArtifactsRepository = Readonly<{
+  id: string;
+  name: string;
+  defaultBranch: string;
+}>;
+```
+
+Stable repository identity exposed to callers; no credentials or remote URL.
+
+---
+
+### GitExchange
+
+```ts
+type GitExchange = Readonly<{
+  protocol?: string;
+  signal?: AbortSignal;
+}> &
+  | Readonly<{
+  repository: string;
+  operation: "upload-pack-advertisement" | "receive-pack-advertisement";
+}>
+  | Readonly<{
+  repository: string;
+  operation: "upload-pack" | "receive-pack";
+  body: ReadableStream<Uint8Array>;
+}>;
+```
+
+One admitted Git smart-HTTP advertisement or byte-stream exchange.
+
+---
+
+### Artifacts
+
+```ts
+type Artifacts = Readonly<{
+  ensureRepository: Promise<
+    Readonly<{
+      id: string;
+      name: string;
+      defaultBranch: string;
+    }>
+  >;
+  forkRepository: Promise<
+    Readonly<{
+      repository: ArtifactsRepository;
+      mainHead: string;
+      disposition: "created" | "existing";
+    }>
+  >;
+  recoverForkRepository: Promise<Readonly<{
+    repository: ArtifactsRepository;
+    mainHead: string;
+    disposition: "created" | "existing";
+  }> | null>;
+  resolveRepository: Promise<
+    Readonly<{
+      id: string;
+      name: string;
+      defaultBranch: string;
+    }>
+  >;
+  readDefaultBranchHead: Promise<string | null>;
+  readBranchHeads: Promise<readonly string[]>;
+  readRefs: Promise<
+    readonly Readonly<{
+      name: string;
+      hash: string;
+    }>[]
+  >;
+  exchangeGit: Promise<Response>;
+}>;
+```
+
+Configured repository owner; authorization belongs to its calling host.
+
+---
+
+### ArtifactsRestOptions
+
+```ts
+type ArtifactsRestOptions = Readonly<{
+  accountId: string;
+  namespace: string;
+  apiToken: string;
+  fetch?: typeof fetch;
+}>;
+```
+
+Where the REST API is and how to reach it.
+
+## Functions
+
+### createArtifactsRestNamespace()
+
+```ts
+function createArtifactsRestNamespace(options): ArtifactsNamespace;
+```
+
+An Artifacts namespace reached over REST, with the binding's shape.
+
+#### Parameters
+
+| Parameter | Type                                            |
+| --------- | ----------------------------------------------- |
+| `options` | [`ArtifactsRestOptions`](#artifactsrestoptions) |
+
+#### Returns
+
+[`ArtifactsNamespace`](namespace.md#artifactsnamespace)
+
+## References
+
+### createCloudflareArtifacts
+
+Re-exports [createCloudflareArtifacts](cloudflare.md#createcloudflareartifacts)
+
+---
+
+### CloudflareArtifactsNamespace
+
+Re-exports
+[CloudflareArtifactsNamespace](cloudflare.md#cloudflareartifactsnamespace)
+
+---
+
+### CloudflareArtifactsOptions
+
+Re-exports
+[CloudflareArtifactsOptions](cloudflare.md#cloudflareartifactsoptions)
+
+---
+
+### ArtifactsNamespace
+
+Re-exports [ArtifactsNamespace](namespace.md#artifactsnamespace)
+
+---
+
+### ArtifactsCommit
+
+Re-exports [ArtifactsCommit](namespace.md#artifactscommit)
+
+---
+
+### ArtifactsRepositoryInfo
+
+Re-exports [ArtifactsRepositoryInfo](namespace.md#artifactsrepositoryinfo)

package/docs/api/namespace.md

@@ -0,0 +1,234 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+[**@fungi.computer/burrow**](README.md)
+
+---
+
+[@fungi.computer/burrow](README.md) / namespace
+
+# namespace
+
+## Type Aliases
+
+### ArtifactsRepositoryInfo
+
+```ts
+type ArtifactsRepositoryInfo = Readonly<{
+  id: string;
+  name: string;
+  defaultBranch: string;
+  remote: string;
+  lastPushAt?: string | null;
+  source?: string | null;
+}>;
+```
+
+Host-only Artifacts namespace. Repository credentials never enter App results.
+
+---
+
+### ArtifactsCreatedRepository
+
+```ts
+type ArtifactsCreatedRepository = ArtifactsRepositoryInfo &
+  Readonly<{
+    token: string;
+  }>;
+```
+
+Initial revocation reference: a Workers token or an already-revoked REST ID.
+
+---
+
+### ArtifactsCommit
+
+```ts
+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;
+}>;
+```
+
+Provider commit metadata and parent object IDs.
+
+---
+
+### ArtifactsTreeEntry
+
+```ts
+type ArtifactsTreeEntry = Readonly<{
+  name: string;
+  mode: string;
+  hash: string;
+  type: "blob" | "tree" | "commit";
+}>;
+```
+
+One provider tree entry, including its mode and object kind.
+
+---
+
+### ArtifactsRepositoryHandle
+
+```ts
+type ArtifactsRepositoryHandle = Readonly<{
+  info: Promise<
+    Readonly<{
+      id: string;
+      name: string;
+      defaultBranch: string;
+      remote: string;
+      lastPushAt?: string | null;
+      source?: string | null;
+    }>
+  >;
+  createToken: Promise<
+    Readonly<{
+      id: string;
+      plaintext: string;
+      expiresAt: string;
+    }>
+  >;
+  revokeToken: Promise<boolean>;
+  fork: Promise<ArtifactsCreatedRepository>;
+  log: Promise<
+    readonly 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;
+    }>[]
+  >;
+  readCommit: Promise<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;
+  }> | null>;
+  readTree: Promise<
+    | readonly Readonly<{
+        name: string;
+        mode: string;
+        hash: string;
+        type: "blob" | "tree" | "commit";
+      }>[]
+    | null
+  >;
+  readBlob: Promise<Blob | null>;
+}>;
+```
+
+Host-only repository operations; secrets never belong in App results.
+
+---
+
+### ArtifactsNamespace
+
+```ts
+type ArtifactsNamespace = Readonly<{
+  create: Promise<ArtifactsCreatedRepository>;
+  get: Promise<Readonly<{
+     info: Promise<Readonly<{
+        id: string;
+        name: string;
+        defaultBranch: string;
+        remote: string;
+        lastPushAt?: string | null;
+        source?: string | null;
+     }>>;
+     createToken: Promise<Readonly<{
+        id: string;
+        plaintext: string;
+        expiresAt: string;
+     }>>;
+     revokeToken: Promise<boolean>;
+     fork: Promise<ArtifactsCreatedRepository>;
+     log: Promise<readonly Readonly<{
+        hash: string;
+        treeHash: string;
+        message: string;
+        author: Readonly<{
+           name: ...;
+           email: ...;
+        }>;
+        committer: Readonly<{
+           name: ...;
+           email: ...;
+        }>;
+        parents: readonly ...[];
+        authoredAt: number;
+        committedAt: number;
+     }>[]>;
+     readCommit: Promise<
+        | Readonly<{
+        hash: string;
+        treeHash: string;
+        message: string;
+        author: Readonly<{
+           name: ...;
+           email: ...;
+        }>;
+        committer: Readonly<{
+           name: ...;
+           email: ...;
+        }>;
+        parents: readonly ...[];
+        authoredAt: number;
+        committedAt: number;
+      }>
+       | null>;
+     readTree: Promise<
+        | readonly Readonly<{
+        name: string;
+        mode: string;
+        hash: string;
+        type: ... | ... | ...;
+      }>[]
+       | null>;
+     readBlob: Promise<Blob | null>;
+  }>>;
+  list: Promise<Readonly<{
+     repos: readonly Readonly<{
+        name: string;
+        status: string;
+     }>[];
+     total: number;
+     cursor?: string;
+  }>>;
+  delete: Promise<boolean>;
+}>;
+```
+
+Configured provider namespace with repository-name-addressed handles.

package/docs/home.ts

@@ -0,0 +1,27 @@
+import { createArtifactsRestNamespace } from "@fungi.computer/burrow";
+
+// Local provider fixture: this example never contacts Cloudflare.
+const namespace = createArtifactsRestNamespace({
+  accountId: "example-account",
+  namespace: "default",
+  apiToken: "example-only",
+  fetch: async () =>
+    Response.json({
+      success: true,
+      errors: [],
+      result: [
+        {
+          id: "repository-notes",
+          name: "notes",
+          default_branch: "main",
+          remote:
+            "https://example.artifacts.cloudflare.net/git/default/notes.git",
+          status: "ready",
+        },
+      ],
+      result_info: { total_pages: 1, total_count: 1 },
+    }),
+});
+
+const { repos } = await namespace.list();
+console.log(repos.map((repository) => repository.name)); // ["notes"]

package/package.json

@@ -1,6 +1,71 @@
 {
   "name": "@fungi.computer/burrow",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.0.1",
+  "author": "Levi <levi@technomancy.dev>",
+  "description": "Configured Artifacts repository and Git protocol owner",
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./cloudflare": {
+      "types": "./dist/cloudflare.d.ts",
+      "import": "./dist/cloudflare.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "docs/api",
+    "docs/home.ts"
+  ],
+  "dependencies": {
+    "effect": "4.0.2",
+    "isomorphic-git": "1.42.2"
+  },
+  "devDependencies": {
+    "@cloudflare/workers-types": "5.20260828.1",
+    "@types/node": "24.13.3",
+    "typescript": "5.9.3",
+    "vitest": "4.1.11"
+  },
+  "botanical": {
+    "role": "package",
+    "operations": {
+      "lint": "required",
+      "typecheck": "required",
+      "build": "required",
+      "test": "required",
+      "docs": "required",
+      "pack": "required",
+      "smoke": "required",
+      "stranger": "required"
+    }
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/fungi-computer/burrow.git"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "lint": "eslint src test --max-warnings=0 && ../../node_modules/.bin/oxlint --config ../../oxlint.config.ts --deny-warnings src test",
+    "test": "../../node_modules/.bin/vitest run",
+    "pack": "mkdir -p ../../.botanical/burrow-pack && pnpm pack --pack-destination ../../.botanical/burrow-pack",
+    "smoke": "node --input-type=module -e \"Promise.all([import('./dist/index.js'), import('./dist/cloudflare.js')]).then(() => {})\"",
+    "format:check": "node ../../tooling/repository/scripts/format-package-check.mjs",
+    "lint:anti-slop": "node ../../tooling/repository/scripts/lint-package-anti-slop.mjs",
+    "stranger": "tsx ../../tooling/repository/src/artifacts/cli.ts --repo-root ../.. .",
+    "docs": "tsx ../../tooling/repository/src/docs/cli.ts check --root ../..",
+    "docs:write": "tsx ../../tooling/repository/src/docs/cli.ts write --root ../.."
+  }
 }