@enbox/gitd 0.0.1

package/src/org.ts

@@ -0,0 +1,147 @@
+/**
+ * Forge Organization Protocol — organization and team management.
+ *
+ * Organizations are DIDs themselves. An org DID installs the forge protocols
+ * and manages repos. Organization members and teams provide sub-organization
+ * grouping with their own role scoping.
+ *
+ * @module
+ */
+
+import type { ProtocolDefinition } from '@enbox/dwn-sdk-js';
+
+import { defineProtocol } from '@enbox/api';
+
+// ---------------------------------------------------------------------------
+// Data types
+// ---------------------------------------------------------------------------
+
+/** Data shape for an organization record. */
+export type OrgData = {
+  name : string;
+  description? : string;
+  homepage? : string;
+  avatar? : string;
+};
+
+/** Data shape for an organization member (owner or member). */
+export type OrgMemberData = {
+  did : string;
+  alias? : string;
+};
+
+/** Data shape for a team within an organization. */
+export type TeamData = {
+  name : string;
+  description? : string;
+  privacy : 'visible' | 'secret';
+};
+
+/** Data shape for a team member. */
+export type TeamMemberData = {
+  did : string;
+  alias? : string;
+};
+
+// ---------------------------------------------------------------------------
+// Schema map
+// ---------------------------------------------------------------------------
+
+/** Maps protocol type names to their TypeScript data shapes. */
+export type ForgeOrgSchemaMap = {
+  org : OrgData;
+  owner : OrgMemberData;
+  member : OrgMemberData;
+  team : TeamData;
+  teamMember : TeamMemberData;
+};
+
+// ---------------------------------------------------------------------------
+// Protocol definition
+// ---------------------------------------------------------------------------
+
+export const ForgeOrgDefinition = {
+  protocol  : 'https://enbox.org/protocols/forge/org',
+  published : true,
+  types     : {
+    org: {
+      schema      : 'https://enbox.org/schemas/forge/org',
+      dataFormats : ['application/json'],
+    },
+    owner: {
+      schema      : 'https://enbox.org/schemas/forge/org-member',
+      dataFormats : ['application/json'],
+    },
+    member: {
+      schema      : 'https://enbox.org/schemas/forge/org-member',
+      dataFormats : ['application/json'],
+    },
+    team: {
+      schema      : 'https://enbox.org/schemas/forge/team',
+      dataFormats : ['application/json'],
+    },
+    teamMember: {
+      schema      : 'https://enbox.org/schemas/forge/team-member',
+      dataFormats : ['application/json'],
+    },
+  },
+  structure: {
+    org: {
+      $recordLimit : { max: 1, strategy: 'reject' },
+      $actions     : [{ who: 'anyone', can: ['read'] }],
+
+      owner: {
+        $role    : true,
+        $actions : [{ who: 'anyone', can: ['read'] }],
+        $tags    : {
+          $requiredTags       : ['did'],
+          $allowUndefinedTags : false,
+          did                 : { type: 'string' },
+        },
+      },
+
+      member: {
+        $role    : true,
+        $actions : [
+          { who: 'anyone', can: ['read'] },
+          { role: 'org/owner', can: ['create', 'delete'] },
+        ],
+        $tags: {
+          $requiredTags       : ['did'],
+          $allowUndefinedTags : false,
+          did                 : { type: 'string' },
+        },
+      },
+
+      team: {
+        $actions: [
+          { who: 'anyone', can: ['read'] },
+          { role: 'org/owner', can: ['create', 'update', 'delete'] },
+        ],
+
+        teamMember: {
+          $role    : true,
+          $actions : [
+            { who: 'anyone', can: ['read'] },
+            { role: 'org/owner', can: ['create', 'delete'] },
+          ],
+          $tags: {
+            $requiredTags       : ['did'],
+            $allowUndefinedTags : false,
+            did                 : { type: 'string' },
+          },
+        },
+      },
+    },
+  },
+} as const satisfies ProtocolDefinition;
+
+// ---------------------------------------------------------------------------
+// Typed protocol export
+// ---------------------------------------------------------------------------
+
+/** Typed Forge Org protocol for use with `dwn.using()`. */
+export const ForgeOrgProtocol = defineProtocol(
+  ForgeOrgDefinition,
+  {} as ForgeOrgSchemaMap,
+);

package/src/patches.ts

@@ -0,0 +1,203 @@
+/**
+ * Forge Patches Protocol — pull requests, code review, and merge tracking.
+ *
+ * A "patch" is a proposed change (equivalent to a GitHub PR). Each patch
+ * tracks revisions (force-pushes), reviews (approve/reject/comment),
+ * inline review comments, status transitions, and merge results.
+ *
+ * Composes with the Forge Repo protocol via `uses` for role-based authorization.
+ *
+ * @module
+ */
+
+import type { ProtocolDefinition } from '@enbox/dwn-sdk-js';
+
+import { defineProtocol } from '@enbox/api';
+
+// ---------------------------------------------------------------------------
+// Data types
+// ---------------------------------------------------------------------------
+
+/** Data shape for a patch (pull request) record. */
+export type PatchData = {
+  title : string;
+  body : string;
+  number? : number;
+};
+
+/** Data shape for a revision (force-push snapshot). */
+export type RevisionData = {
+  description? : string;
+  diffStat : { additions: number; deletions: number; filesChanged: number };
+};
+
+/** Data shape for a code review. */
+export type ReviewData = {
+  body?: string;
+};
+
+/** Data shape for an inline review comment. */
+export type ReviewCommentData = {
+  body : string;
+  diffHunk? : string;
+};
+
+/** Data shape for a patch status change event. */
+export type PatchStatusChangeData = {
+  reason?: string;
+};
+
+/** Data shape for a merge result. */
+export type MergeResultData = {
+  mergedBy: string;
+};
+
+// ---------------------------------------------------------------------------
+// Schema map
+// ---------------------------------------------------------------------------
+
+/** Maps protocol type names to their TypeScript data shapes. */
+export type ForgePatchesSchemaMap = {
+  patch : PatchData;
+  revision : RevisionData;
+  review : ReviewData;
+  reviewComment : ReviewCommentData;
+  statusChange : PatchStatusChangeData;
+  mergeResult : MergeResultData;
+};
+
+// ---------------------------------------------------------------------------
+// Protocol definition
+// ---------------------------------------------------------------------------
+
+export const ForgePatchesDefinition = {
+  protocol  : 'https://enbox.org/protocols/forge/patches',
+  published : true,
+  uses      : {
+    repo: 'https://enbox.org/protocols/forge/repo',
+  },
+  types: {
+    patch: {
+      schema      : 'https://enbox.org/schemas/forge/patch',
+      dataFormats : ['application/json'],
+    },
+    revision: {
+      schema      : 'https://enbox.org/schemas/forge/revision',
+      dataFormats : ['application/json'],
+    },
+    review: {
+      schema      : 'https://enbox.org/schemas/forge/review',
+      dataFormats : ['application/json'],
+    },
+    reviewComment: {
+      schema      : 'https://enbox.org/schemas/forge/review-comment',
+      dataFormats : ['application/json'],
+    },
+    statusChange: {
+      schema      : 'https://enbox.org/schemas/forge/patch-status-change',
+      dataFormats : ['application/json'],
+    },
+    mergeResult: {
+      schema      : 'https://enbox.org/schemas/forge/merge-result',
+      dataFormats : ['application/json'],
+    },
+  },
+  structure: {
+    repo: {
+      $ref: 'repo:repo',
+
+      patch: {
+        $actions: [
+          { role: 'repo:repo/contributor', can: ['create', 'read'] },
+          { role: 'repo:repo/maintainer', can: ['create', 'read', 'update', 'delete'] },
+          { who: 'author', of: 'repo/patch', can: ['create', 'update'] },
+        ],
+        $tags: {
+          $requiredTags       : ['status', 'baseBranch'],
+          $allowUndefinedTags : false,
+          status              : { type: 'string', enum: ['draft', 'open', 'closed', 'merged'] },
+          number              : { type: 'string' },
+          baseBranch          : { type: 'string' },
+          headBranch          : { type: 'string' },
+          sourceDid           : { type: 'string' },
+        },
+
+        revision: {
+          $immutable : true,
+          $actions   : [
+            { role: 'repo:repo/contributor', can: ['read'] },
+            { who: 'author', of: 'repo/patch', can: ['create'] },
+          ],
+          $tags: {
+            $requiredTags       : ['headCommit', 'baseCommit'],
+            $allowUndefinedTags : false,
+            headCommit          : { type: 'string' },
+            baseCommit          : { type: 'string' },
+            commitCount         : { type: 'integer', minimum: 1 },
+          },
+        },
+
+        review: {
+          $immutable : true,
+          $actions   : [
+            { role: 'repo:repo/contributor', can: ['create', 'read'] },
+            { role: 'repo:repo/maintainer', can: ['create', 'read'] },
+          ],
+          $tags: {
+            $requiredTags       : ['verdict'],
+            $allowUndefinedTags : false,
+            verdict             : { type: 'string', enum: ['approve', 'reject', 'comment'] },
+            revisionRecordId    : { type: 'string' },
+          },
+
+          reviewComment: {
+            $actions: [
+              { role: 'repo:repo/contributor', can: ['create', 'read'] },
+              { role: 'repo:repo/maintainer', can: ['create', 'read'] },
+            ],
+            $tags: {
+              $allowUndefinedTags : true,
+              path                : { type: 'string' },
+              line                : { type: 'integer' },
+              side                : { type: 'string', enum: ['left', 'right'] },
+            },
+          },
+        },
+
+        statusChange: {
+          $immutable : true,
+          $actions   : [
+            { role: 'repo:repo/contributor', can: ['read'] },
+            { role: 'repo:repo/maintainer', can: ['create'] },
+            { who: 'author', of: 'repo/patch', can: ['create'] },
+          ],
+        },
+
+        mergeResult: {
+          $immutable   : true,
+          $recordLimit : { max: 1, strategy: 'reject' },
+          $actions     : [
+            { role: 'repo:repo/contributor', can: ['read'] },
+            { role: 'repo:repo/maintainer', can: ['create'] },
+          ],
+          $tags: {
+            $requiredTags       : ['mergeCommit', 'strategy'],
+            $allowUndefinedTags : false,
+            mergeCommit         : { type: 'string' },
+            strategy            : { type: 'string', enum: ['merge', 'squash', 'rebase'] },
+          },
+        },
+      },
+    },
+  },
+} as const satisfies ProtocolDefinition;
+
+// ---------------------------------------------------------------------------
+// Typed protocol export
+// ---------------------------------------------------------------------------
+
+/** Typed Forge Patches protocol for use with `dwn.using()`. */
+export const ForgePatchesProtocol = defineProtocol(
+  ForgePatchesDefinition,
+  {} as ForgePatchesSchemaMap,
+);

package/src/refs.ts

@@ -0,0 +1,94 @@
+/**
+ * Forge Git Refs Protocol — mirrors git branch/tag refs as DWN records.
+ *
+ * This protocol provides a DWN-native view of git ref pointers (branches, tags)
+ * so that other DWN participants can subscribe to ref changes via
+ * `RecordsSubscribe`. The actual git object data stays in git — these records
+ * only track the ref name → commit SHA mapping.
+ *
+ * Uses `$ref` to compose with the Repo protocol for role-based authorization:
+ * only maintainers can update refs in the repo owner's DWN.
+ *
+ * @module
+ */
+
+import type { ProtocolDefinition } from '@enbox/dwn-sdk-js';
+
+import { defineProtocol } from '@enbox/api';
+
+// ---------------------------------------------------------------------------
+// Data types
+// ---------------------------------------------------------------------------
+
+/** Data shape for a git ref record (branch or tag pointer). */
+export type GitRefData = {
+  /** Full ref name, e.g. `refs/heads/main` or `refs/tags/v1.0.0`. */
+  name: string;
+
+  /** The commit SHA-1 (or SHA-256) this ref points to. */
+  target: string;
+
+  /** Ref type discriminator. */
+  type: 'branch' | 'tag';
+
+  /** For annotated tags, the tagger/committer info. */
+  tagger?: string;
+
+  /** For annotated tags, the tag message. */
+  message?: string;
+};
+
+// ---------------------------------------------------------------------------
+// Schema map
+// ---------------------------------------------------------------------------
+
+/** Maps protocol type names to their TypeScript data shapes. */
+export type ForgeRefsSchemaMap = {
+  ref: GitRefData;
+};
+
+// ---------------------------------------------------------------------------
+// Protocol definition
+// ---------------------------------------------------------------------------
+
+export const ForgeRefsDefinition = {
+  protocol  : 'https://enbox.org/protocols/forge/refs',
+  published : true,
+  uses      : {
+    repo: 'https://enbox.org/protocols/forge/repo',
+  },
+  types: {
+    ref: {
+      schema      : 'https://enbox.org/schemas/forge/git-ref',
+      dataFormats : ['application/json'],
+    },
+  },
+  structure: {
+    repo: {
+      $ref : 'repo:repo',
+      ref  : {
+        $actions: [
+          { who: 'anyone', can: ['read'] },
+          { role: 'repo:repo/maintainer', can: ['create', 'update', 'delete'] },
+        ],
+        $tags: {
+          $requiredTags       : ['name', 'type'],
+          $allowUndefinedTags : false,
+          name                : { type: 'string' },
+          type                : { type: 'string', enum: ['branch', 'tag'] },
+          target              : { type: 'string' },
+        },
+      },
+    },
+  },
+} as const satisfies ProtocolDefinition;
+
+// ---------------------------------------------------------------------------
+// Typed protocol export
+// ---------------------------------------------------------------------------
+
+/** Typed Forge Refs protocol for use with `web5.using()`. */
+export const ForgeRefsProtocol = defineProtocol(
+  ForgeRefsDefinition,
+  {} as ForgeRefsSchemaMap,
+);

package/src/registry.ts

@@ -0,0 +1,132 @@
+/**
+ * Forge Package Registry Protocol — DID-scoped package publishing.
+ *
+ * Packages are scoped to the publisher's DID (no global namespace squatting).
+ * Versions and tarballs are `$immutable` — once published, content cannot be
+ * silently replaced. Third-party attestations enable build reproducibility chains.
+ *
+ * @module
+ */
+
+import type { ProtocolDefinition } from '@enbox/dwn-sdk-js';
+
+import { defineProtocol } from '@enbox/api';
+
+// ---------------------------------------------------------------------------
+// Data types
+// ---------------------------------------------------------------------------
+
+/** Data shape for a package record. */
+export type PackageData = {
+  name : string;
+  description? : string;
+  keywords? : string[];
+  repository? : string;
+};
+
+/** Data shape for a package version record. */
+export type PackageVersionData = {
+  semver : string;
+  engines? : Record<string, string>;
+  dependencies?: Record<string, string>;
+};
+
+/** Data shape for a third-party attestation. */
+export type AttestationData = {
+  attestorDid : string;
+  claim : string;
+  sourceCommit?: string;
+  sourceRepo? : string;
+};
+
+// ---------------------------------------------------------------------------
+// Schema map
+// ---------------------------------------------------------------------------
+
+/** Maps protocol type names to their TypeScript data shapes. */
+export type ForgeRegistrySchemaMap = {
+  package : PackageData;
+  version : PackageVersionData;
+  tarball : Uint8Array;
+  attestation : AttestationData;
+};
+
+// ---------------------------------------------------------------------------
+// Protocol definition
+// ---------------------------------------------------------------------------
+
+export const ForgeRegistryDefinition = {
+  protocol  : 'https://enbox.org/protocols/forge/registry',
+  published : true,
+  types     : {
+    package: {
+      schema      : 'https://enbox.org/schemas/forge/package',
+      dataFormats : ['application/json'],
+    },
+    version: {
+      schema      : 'https://enbox.org/schemas/forge/package-version',
+      dataFormats : ['application/json'],
+    },
+    tarball: {
+      dataFormats: ['application/gzip', 'application/octet-stream'],
+    },
+    attestation: {
+      schema      : 'https://enbox.org/schemas/forge/attestation',
+      dataFormats : ['application/json'],
+    },
+  },
+  structure: {
+    package: {
+      $actions : [{ who: 'anyone', can: ['read'] }],
+      // Only owner can create packages (no create in $actions = owner-only)
+      $tags    : {
+        $requiredTags       : ['name', 'ecosystem'],
+        $allowUndefinedTags : false,
+        name                : { type: 'string', maxLength: 214 },
+        ecosystem           : { type: 'string', enum: ['npm', 'cargo', 'pip', 'go', 'oci'] },
+        description         : { type: 'string' },
+      },
+
+      version: {
+        $immutable : true,
+        $actions   : [
+          { who: 'anyone', can: ['read'] },
+          { who: 'author', of: 'package', can: ['create'] },
+        ],
+        $tags: {
+          $requiredTags       : ['semver'],
+          $allowUndefinedTags : false,
+          semver              : { type: 'string' },
+          deprecated          : { type: 'boolean' },
+        },
+
+        tarball: {
+          $immutable   : true,
+          $recordLimit : { max: 1, strategy: 'reject' },
+          $actions     : [
+            { who: 'anyone', can: ['read'] },
+            { who: 'author', of: 'package', can: ['create'] },
+          ],
+        },
+
+        attestation: {
+          $immutable : true,
+          $actions   : [
+            { who: 'anyone', can: ['read'] },
+            // Third-party attestors need a permission grant from the package owner
+          ],
+        },
+      },
+    },
+  },
+} as const satisfies ProtocolDefinition;
+
+// ---------------------------------------------------------------------------
+// Typed protocol export
+// ---------------------------------------------------------------------------
+
+/** Typed Forge Registry protocol for use with `dwn.using()`. */
+export const ForgeRegistryProtocol = defineProtocol(
+  ForgeRegistryDefinition,
+  {} as ForgeRegistrySchemaMap,
+);

package/src/releases.ts

@@ -0,0 +1,124 @@
+/**
+ * Forge Releases Protocol — release management with immutable assets.
+ *
+ * Release assets use `$immutable` to guarantee supply chain integrity:
+ * once a binary is published, its data cannot be silently replaced.
+ *
+ * @module
+ */
+
+import type { ProtocolDefinition } from '@enbox/dwn-sdk-js';
+
+import { defineProtocol } from '@enbox/api';
+
+// ---------------------------------------------------------------------------
+// Data types
+// ---------------------------------------------------------------------------
+
+/** Data shape for a release record. */
+export type ReleaseData = {
+  name : string;
+  body? : string;
+};
+
+/** Data shape for a release asset metadata. */
+export type AssetData = {
+  filename : string;
+  contentType : string;
+  size : number;
+};
+
+/** Data shape for a release signature. */
+export type SignatureData = {
+  algorithm : string;
+  publicKey? : string;
+};
+
+// ---------------------------------------------------------------------------
+// Schema map
+// ---------------------------------------------------------------------------
+
+/** Maps protocol type names to their TypeScript data shapes. */
+export type ForgeReleasesSchemaMap = {
+  release : ReleaseData;
+  asset : Uint8Array;
+  signature : SignatureData;
+};
+
+// ---------------------------------------------------------------------------
+// Protocol definition
+// ---------------------------------------------------------------------------
+
+export const ForgeReleasesDefinition = {
+  protocol  : 'https://enbox.org/protocols/forge/releases',
+  published : true,
+  uses      : {
+    repo: 'https://enbox.org/protocols/forge/repo',
+  },
+  types: {
+    release: {
+      schema      : 'https://enbox.org/schemas/forge/release',
+      dataFormats : ['application/json'],
+    },
+    asset: {
+      dataFormats: ['application/octet-stream', 'application/gzip', 'application/zip', 'application/x-tar'],
+    },
+    signature: {
+      dataFormats: ['application/pgp-signature', 'application/json'],
+    },
+  },
+  structure: {
+    repo: {
+      $ref: 'repo:repo',
+
+      release: {
+        $actions: [
+          { who: 'anyone', can: ['read'] },
+          { role: 'repo:repo/maintainer', can: ['create', 'update', 'delete'] },
+        ],
+        $tags: {
+          $requiredTags       : ['tagName'],
+          $allowUndefinedTags : false,
+          tagName             : { type: 'string' },
+          commitSha           : { type: 'string' },
+          prerelease          : { type: 'boolean' },
+          draft               : { type: 'boolean' },
+        },
+
+        asset: {
+          $immutable : true,
+          $actions   : [
+            { who: 'anyone', can: ['read'] },
+            { role: 'repo:repo/maintainer', can: ['create', 'delete'] },
+          ],
+          $tags: {
+            $requiredTags       : ['filename', 'contentType'],
+            $allowUndefinedTags : false,
+            filename            : { type: 'string' },
+            contentType         : { type: 'string' },
+            size                : { type: 'integer' },
+          },
+        },
+
+        signature: {
+          $immutable   : true,
+          $recordLimit : { max: 1, strategy: 'reject' },
+          $actions     : [
+            { who: 'anyone', can: ['read'] },
+            { role: 'repo:repo/maintainer', can: ['create'] },
+          ],
+        },
+      },
+    },
+  },
+} as const satisfies ProtocolDefinition;
+
+// ---------------------------------------------------------------------------
+// Typed protocol export
+// ---------------------------------------------------------------------------
+
+/** Typed Forge Releases protocol for use with `dwn.using()`. */
+export const ForgeReleasesProtocol = defineProtocol(
+  ForgeReleasesDefinition,
+  {} as ForgeReleasesSchemaMap,
+);