@enbox/gitd 0.0.1

package/src/cli/commands/release.ts

@@ -0,0 +1,189 @@
+/**
+ * `gitd release` — create, list, and show releases with immutable assets.
+ *
+ * Usage:
+ *   gitd release create <tag> [--name <name>] [--body <text>] [--commit <sha>] [--prerelease] [--draft]
+ *   gitd release show <tag>
+ *   gitd release list [--limit <n>]
+ *
+ * @module
+ */
+
+import type { AgentContext } from '../agent.js';
+
+import { DateSort } from '@enbox/dwn-sdk-js';
+
+import { flagValue } from '../flags.js';
+import { getRepoContextId } from '../repo-context.js';
+
+// ---------------------------------------------------------------------------
+// Sub-command dispatch
+// ---------------------------------------------------------------------------
+
+export async function releaseCommand(ctx: AgentContext, args: string[]): Promise<void> {
+  const sub = args[0];
+  const rest = args.slice(1);
+
+  switch (sub) {
+    case 'create': return releaseCreate(ctx, rest);
+    case 'show': return releaseShow(ctx, rest);
+    case 'list':
+    case 'ls': return releaseList(ctx, rest);
+    default:
+      console.error('Usage: gitd release <create|show|list>');
+      process.exit(1);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// release create
+// ---------------------------------------------------------------------------
+
+async function releaseCreate(ctx: AgentContext, args: string[]): Promise<void> {
+  const tagName = args[0];
+  const name = flagValue(args, '--name') ?? tagName;
+  const body = flagValue(args, '--body') ?? '';
+  const commitSha = flagValue(args, '--commit');
+  const prerelease = args.includes('--prerelease');
+  const draft = args.includes('--draft');
+
+  if (!tagName) {
+    console.error('Usage: gitd release create <tag> [--name <name>] [--body <text>] [--commit <sha>] [--prerelease] [--draft]');
+    process.exit(1);
+  }
+
+  const repoContextId = await getRepoContextId(ctx);
+
+  const tags: Record<string, unknown> = { tagName };
+  if (commitSha) { tags.commitSha = commitSha; }
+  if (prerelease) { tags.prerelease = true; }
+  if (draft) { tags.draft = true; }
+
+  const { status, record } = await ctx.releases.records.create('repo/release' as any, {
+    data            : { name, body },
+    tags,
+    parentContextId : repoContextId,
+  } as any);
+
+  if (status.code >= 300) {
+    console.error(`Failed to create release: ${status.code} ${status.detail}`);
+    process.exit(1);
+  }
+
+  console.log(`Created release ${tagName}${name !== tagName ? ` ("${name}")` : ''}`);
+  console.log(`  Record ID: ${record.id}`);
+  if (prerelease) { console.log('  Pre-release: yes'); }
+  if (draft) { console.log('  Draft: yes'); }
+}
+
+// ---------------------------------------------------------------------------
+// release show
+// ---------------------------------------------------------------------------
+
+async function releaseShow(ctx: AgentContext, args: string[]): Promise<void> {
+  const tagName = args[0];
+  if (!tagName) {
+    console.error('Usage: gitd release show <tag>');
+    process.exit(1);
+  }
+
+  const repoContextId = await getRepoContextId(ctx);
+  const release = await findReleaseByTag(ctx, repoContextId, tagName);
+  if (!release) {
+    console.error(`Release ${tagName} not found.`);
+    process.exit(1);
+  }
+
+  const data = await release.data.json();
+  const tags = release.tags as Record<string, unknown> | undefined;
+  const date = release.dateCreated?.slice(0, 10) ?? '';
+  const commit = tags?.commitSha as string | undefined;
+  const prerelease = tags?.prerelease === true;
+  const draft = tags?.draft === true;
+
+  console.log(`Release: ${data.name ?? tagName}`);
+  console.log(`  Tag:        ${tags?.tagName ?? tagName}`);
+  if (commit) { console.log(`  Commit:     ${commit}`); }
+  console.log(`  Created:    ${date}`);
+  if (prerelease) { console.log('  Pre-release: yes'); }
+  if (draft) { console.log('  Draft: yes'); }
+  console.log(`  ID:         ${release.id}`);
+
+  if (data.body) {
+    console.log('');
+    console.log(`  ${data.body}`);
+  }
+
+  // Fetch assets.
+  const { records: assets } = await ctx.releases.records.query('repo/release/asset' as any, {
+    filter: { contextId: release.contextId },
+  });
+
+  if (assets.length > 0) {
+    console.log('');
+    console.log(`  Assets (${assets.length}):`);
+    for (const asset of assets) {
+      const assetTags = asset.tags as Record<string, unknown> | undefined;
+      const filename = assetTags?.filename ?? 'unknown';
+      const size = assetTags?.size as number | undefined;
+      const sizeStr = size ? ` (${formatBytes(size)})` : '';
+      console.log(`    ${filename}${sizeStr}`);
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// release list
+// ---------------------------------------------------------------------------
+
+async function releaseList(ctx: AgentContext, args: string[]): Promise<void> {
+  const limit = parseInt(flagValue(args, '--limit') ?? '20', 10);
+  const repoContextId = await getRepoContextId(ctx);
+
+  const { records } = await ctx.releases.records.query('repo/release' as any, {
+    filter     : { contextId: repoContextId },
+    dateSort   : DateSort.CreatedDescending,
+    pagination : { limit },
+  });
+
+  if (records.length === 0) {
+    console.log('No releases found.');
+    return;
+  }
+
+  console.log(`Releases (${records.length}):\n`);
+  for (const rec of records) {
+    const data = await rec.data.json();
+    const tags = rec.tags as Record<string, unknown> | undefined;
+    const tagName = tags?.tagName ?? '?';
+    const date = rec.dateCreated?.slice(0, 10) ?? '';
+    const prerelease = tags?.prerelease === true ? ' [pre-release]' : '';
+    const draft = tags?.draft === true ? ' [draft]' : '';
+    console.log(`  ${String(tagName).padEnd(20)} ${data.name ?? ''}${prerelease}${draft}  ${date}`);
+    console.log(`${''.padEnd(22)}id: ${rec.id}`);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+async function findReleaseByTag(
+  ctx: AgentContext,
+  repoContextId: string,
+  tagName: string,
+): Promise<any | undefined> {
+  const { records } = await ctx.releases.records.query('repo/release' as any, {
+    filter: {
+      contextId : repoContextId,
+      tags      : { tagName },
+    },
+  });
+  return records[0];
+}
+
+function formatBytes(bytes: number): string {
+  if (bytes < 1024) { return `${bytes} B`; }
+  if (bytes < 1024 * 1024) { return `${(bytes / 1024).toFixed(1)} KB`; }
+  return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}

package/src/cli/commands/repo.ts

@@ -0,0 +1,160 @@
+/**
+ * `gitd repo` — repository management commands.
+ *
+ * Usage:
+ *   gitd repo info                           Show repository metadata
+ *   gitd repo add-collaborator <did> <role>  Grant a role
+ *   gitd repo remove-collaborator <did>      Revoke a collaborator role
+ *
+ * Roles: maintainer, triager, contributor
+ *
+ * @module
+ */
+
+import type { AgentContext } from '../agent.js';
+
+import { flagValue } from '../flags.js';
+import { getRepoContextId } from '../repo-context.js';
+
+// ---------------------------------------------------------------------------
+// Valid roles
+// ---------------------------------------------------------------------------
+
+const VALID_ROLES = ['maintainer', 'triager', 'contributor'] as const;
+type Role = typeof VALID_ROLES[number];
+
+// ---------------------------------------------------------------------------
+// Sub-command dispatch
+// ---------------------------------------------------------------------------
+
+export async function repoCommand(ctx: AgentContext, args: string[]): Promise<void> {
+  const sub = args[0];
+  const rest = args.slice(1);
+
+  switch (sub) {
+    case 'info': return repoInfo(ctx);
+    case 'add-collaborator': return addCollaborator(ctx, rest);
+    case 'remove-collaborator': return removeCollaborator(ctx, rest);
+    default:
+      console.error('Usage: gitd repo <info|add-collaborator|remove-collaborator>');
+      process.exit(1);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// repo info
+// ---------------------------------------------------------------------------
+
+async function repoInfo(ctx: AgentContext): Promise<void> {
+  const { records } = await ctx.repo.records.query('repo');
+
+  if (records.length === 0) {
+    console.error('No repository found. Run `gitd init <name>` first.');
+    process.exit(1);
+  }
+
+  const record = records[0];
+  const data = await record.data.json();
+
+  console.log(`Repository: ${data.name}`);
+  console.log(`  DID:            ${ctx.did}`);
+  console.log(`  Record ID:      ${record.id}`);
+  console.log(`  Context ID:     ${record.contextId}`);
+  console.log(`  Default Branch: ${data.defaultBranch}`);
+  if (data.description) {
+    console.log(`  Description:    ${data.description}`);
+  }
+  if (data.dwnEndpoints?.length > 0) {
+    console.log(`  DWN Endpoints:  ${data.dwnEndpoints.join(', ')}`);
+  }
+  if (data.gitEndpoints && data.gitEndpoints.length > 0) {
+    console.log(`  Git Endpoints:  ${data.gitEndpoints.join(', ')}`);
+  }
+
+  // List collaborators per role.
+  for (const role of VALID_ROLES) {
+    const { records: collabs } = await ctx.repo.records.query(`repo/${role}` as any);
+    if (collabs.length > 0) {
+      console.log(`\n  ${role}s:`);
+      for (const collab of collabs) {
+        const collabData = await collab.data.json();
+        const alias = collabData.alias ? ` (${collabData.alias})` : '';
+        console.log(`    - ${collabData.did}${alias}`);
+      }
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// repo add-collaborator
+// ---------------------------------------------------------------------------
+
+async function addCollaborator(ctx: AgentContext, args: string[]): Promise<void> {
+  const did = args[0];
+  const role = args[1] as Role | undefined;
+  const alias = flagValue(args, '--alias') ?? flagValue(args, '-a');
+
+  if (!did || !role) {
+    console.error('Usage: gitd repo add-collaborator <did> <role> [--alias <name>]');
+    console.error(`  Roles: ${VALID_ROLES.join(', ')}`);
+    process.exit(1);
+  }
+
+  if (!VALID_ROLES.includes(role)) {
+    console.error(`Invalid role: ${role}. Must be one of: ${VALID_ROLES.join(', ')}`);
+    process.exit(1);
+  }
+
+  const repoContextId = await getRepoContextId(ctx);
+
+  const { status, record } = await ctx.repo.records.create(`repo/${role}` as any, {
+    data            : { did, alias: alias ?? '' },
+    tags            : { did },
+    parentContextId : repoContextId,
+    recipient       : did,
+  });
+
+  if (status.code >= 300) {
+    console.error(`Failed to add collaborator: ${status.code} ${status.detail}`);
+    process.exit(1);
+  }
+
+  console.log(`Added ${role}: ${did}`);
+  console.log(`  Record ID: ${record.id}`);
+}
+
+// ---------------------------------------------------------------------------
+// repo remove-collaborator
+// ---------------------------------------------------------------------------
+
+async function removeCollaborator(ctx: AgentContext, args: string[]): Promise<void> {
+  const did = args[0];
+
+  if (!did) {
+    console.error('Usage: gitd repo remove-collaborator <did>');
+    process.exit(1);
+  }
+
+  let found = false;
+
+  for (const role of VALID_ROLES) {
+    const { records: collabs } = await ctx.repo.records.query(`repo/${role}` as any, {
+      filter: { tags: { did } },
+    });
+
+    for (const collab of collabs) {
+      const { status } = await collab.delete();
+      if (status.code < 300) {
+        console.log(`Removed ${role} role for ${did} (recordId: ${collab.id})`);
+        found = true;
+      }
+    }
+  }
+
+  if (!found) {
+    console.error(`No collaborator roles found for DID: ${did}`);
+    process.exit(1);
+  }
+}
+
+

package/src/cli/commands/serve.ts

@@ -0,0 +1,153 @@
+/**
+ * `gitd serve` — start the git transport sidecar server.
+ *
+ * Starts a smart HTTP git server that serves bare repositories and
+ * authenticates pushes using DID-signed tokens. After each successful
+ * push, git refs are mirrored to DWN records via ForgeRefsProtocol and
+ * a git bundle is synced to a DWN record via ForgeRepoProtocol.
+ *
+ * Usage: gitd serve [--port <port>] [--repos <path>] [--prefix <path>]
+ *                       [--public-url <url>]
+ *
+ * Environment:
+ *   GITD_PORT        — server port (default: 9418)
+ *   GITD_REPOS       — base path for bare repos (default: ./repos)
+ *   GITD_PREFIX      — URL path prefix (default: none)
+ *   GITD_PUBLIC_URL  — public URL for the server (enables DID service registration)
+ *
+ * @module
+ */
+
+import type { AgentContext } from '../agent.js';
+
+import { createBundleSyncer } from '../../git-server/bundle-sync.js';
+import { createDidSignatureVerifier } from '../../git-server/verify.js';
+import { createDwnPushAuthorizer } from '../../git-server/push-authorizer.js';
+import { createGitServer } from '../../git-server/server.js';
+import { createPushAuthenticator } from '../../git-server/auth.js';
+import { createRefSyncer } from '../../git-server/ref-sync.js';
+import { getRepoContext } from '../repo-context.js';
+import { registerGitService } from '../../git-server/did-service.js';
+import { restoreFromBundles } from '../../git-server/bundle-restore.js';
+import { flagValue, parsePort } from '../flags.js';
+
+// ---------------------------------------------------------------------------
+// Command
+// ---------------------------------------------------------------------------
+
+export async function serveCommand(ctx: AgentContext, args: string[]): Promise<void> {
+  const port = parsePort(flagValue(args, '--port') ?? process.env.GITD_PORT ?? '9418');
+  const basePath = flagValue(args, '--repos') ?? process.env.GITD_REPOS ?? './repos';
+  const pathPrefix = flagValue(args, '--prefix') ?? process.env.GITD_PREFIX;
+  const publicUrl = flagValue(args, '--public-url') ?? process.env.GITD_PUBLIC_URL;
+
+  // Look up the repo context (contextId + visibility) for ref/bundle syncing.
+  const { contextId: repoContextId, visibility } = await getRepoContext(ctx);
+
+  // DID-based signature verification for push tokens.
+  const verifySignature = createDidSignatureVerifier();
+
+  // DWN-based push authorization — checks role records.
+  const authorizePush = createDwnPushAuthorizer({
+    repo     : ctx.repo,
+    ownerDid : ctx.did,
+  });
+
+  const authenticatePush = createPushAuthenticator({
+    verifySignature,
+    authorizePush,
+  });
+
+  // Post-push callbacks — run ref sync and bundle sync after each push.
+  const syncRefs = createRefSyncer({
+    refs          : ctx.refs,
+    repoContextId : repoContextId,
+  });
+
+  const syncBundle = createBundleSyncer({
+    repo          : ctx.repo,
+    repoContextId : repoContextId,
+    visibility,
+  });
+
+  // Compose both post-push callbacks into a single handler.
+  const onPushComplete = async (did: string, repo: string, repoPath: string): Promise<void> => {
+    await Promise.all([
+      syncRefs(did, repo, repoPath),
+      syncBundle(did, repo, repoPath),
+    ]);
+  };
+
+  // Auto-restore repos from DWN bundles when not found on disk.
+  const onRepoNotFound = async (_did: string, _repo: string, repoPath: string): Promise<boolean> => {
+    console.log(`Restoring repo from DWN bundles → ${repoPath}`);
+    const result = await restoreFromBundles({ repo: ctx.repo, repoPath });
+    if (result.success) {
+      console.log(`Restored ${result.bundlesApplied} bundle(s), tip: ${result.tipCommit}`);
+    } else {
+      console.error(`Bundle restore failed: ${result.error}`);
+    }
+    return result.success;
+  };
+
+  const server = await createGitServer({
+    basePath,
+    port,
+    pathPrefix,
+    authenticatePush,
+    onPushComplete,
+    onRepoNotFound,
+  });
+
+  // Register the git endpoint in the DID document (if public URL is provided).
+  if (publicUrl) {
+    try {
+      await registerGitService(ctx.web5, publicUrl);
+      console.log(`Registered GitTransport service: ${publicUrl}`);
+
+      // Update the repo record with the git endpoint.
+      const { records } = await ctx.repo.records.query('repo');
+      if (records.length > 0) {
+        const record = records[0];
+        const data = await record.data.json();
+        const gitEndpoints = data.gitEndpoints ?? [];
+        if (!gitEndpoints.includes(publicUrl)) {
+          gitEndpoints.push(publicUrl);
+          await record.update({
+            data: { ...data, gitEndpoints },
+          });
+        }
+      }
+    } catch (err) {
+      console.warn(`Warning: Could not register git service: ${(err as Error).message}`);
+    }
+  }
+
+  console.log(`gitd server listening on port ${server.port}`);
+  console.log(`  DID:     ${ctx.did}`);
+  console.log(`  Repos:   ${basePath}`);
+  if (pathPrefix) {
+    console.log(`  Prefix:  ${pathPrefix}`);
+  }
+  if (publicUrl) {
+    console.log(`  Public:  ${publicUrl}`);
+  }
+  console.log('');
+  console.log(`Clone URL: git clone http://localhost:${server.port}/${ctx.did}/<repo>`);
+  if (publicUrl) {
+    console.log(`Public:    git clone did::${ctx.did}/<repo>`);
+  }
+  console.log('');
+  console.log('Press Ctrl+C to stop.');
+
+  // Keep the process alive.
+  await new Promise<void>(() => {
+    process.on('SIGINT', async () => {
+      console.log('\nShutting down...');
+      await server.stop();
+      process.exit(0);
+    });
+  });
+}
+
+

package/src/cli/commands/setup.ts

@@ -0,0 +1,97 @@
+/**
+ * `gitd setup` — configure git to use DID-based remotes and push auth.
+ *
+ * Creates symlinks for `git-remote-did` and `git-remote-did-credential` in
+ * a directory on the user's PATH, and configures the git credential helper
+ * for any host using the DID transport.
+ *
+ * Usage: gitd setup [--bin-dir <path>]
+ *
+ * The default bin directory is `~/.gitd/bin`. The command also ensures
+ * that directory is in the user's PATH (prints instructions if not).
+ *
+ * @module
+ */
+
+import { homedir } from 'node:os';
+import { existsSync, mkdirSync, symlinkSync, unlinkSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+
+import { flagValue } from '../flags.js';
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+const DEFAULT_BIN_DIR = join(homedir(), '.gitd', 'bin');
+
+/** Binary names that must be on PATH for git DID transport to work. */
+const BINARIES = ['git-remote-did', 'git-remote-did-credential'] as const;
+
+// ---------------------------------------------------------------------------
+// Command
+// ---------------------------------------------------------------------------
+
+export async function setupCommand(args: string[]): Promise<void> {
+  const binDir = flagValue(args, '--bin-dir') ?? DEFAULT_BIN_DIR;
+
+  // Ensure the bin directory exists.
+  mkdirSync(binDir, { recursive: true });
+
+  // Find the dist directory — relative to this compiled file.
+  // In the installed package: dist/esm/cli/commands/setup.js
+  // Binary sources:           dist/esm/git-remote/main.js
+  //                           dist/esm/git-remote/credential-main.js
+  const thisFile = new URL(import.meta.url).pathname;
+  const distEsm = resolve(thisFile, '..', '..', '..');
+  const remoteBin = join(distEsm, 'git-remote', 'main.js');
+  const credentialBin = join(distEsm, 'git-remote', 'credential-main.js');
+
+  const sourceMap: Record<string, string> = {
+    'git-remote-did'            : remoteBin,
+    'git-remote-did-credential' : credentialBin,
+  };
+
+  for (const name of BINARIES) {
+    const linkPath = join(binDir, name);
+    const target = sourceMap[name];
+
+    if (!existsSync(target)) {
+      console.error(`Warning: source binary not found at ${target}`);
+      console.error('  Run `bun run build` first, or install @enbox/gitd globally.');
+      continue;
+    }
+
+    // Remove existing symlink if present.
+    if (existsSync(linkPath)) {
+      unlinkSync(linkPath);
+    }
+
+    symlinkSync(target, linkPath);
+    console.log(`  Linked: ${name} -> ${target}`);
+  }
+
+  // Check if binDir is on PATH.
+  const pathDirs = (process.env.PATH ?? '').split(':');
+  const onPath = pathDirs.some((d) => resolve(d) === resolve(binDir));
+
+  console.log('');
+  if (onPath) {
+    console.log(`Setup complete. ${binDir} is already on your PATH.`);
+  } else {
+    console.log('Setup complete. Add the bin directory to your PATH:');
+    console.log('');
+    console.log(`  export PATH="${binDir}:$PATH"`);
+    console.log('');
+    console.log('Add that line to your ~/.bashrc or ~/.zshrc to make it permanent.');
+  }
+
+  console.log('');
+  console.log('You can now clone repos via DID:');
+  console.log('  git clone did::<did>/<repo>');
+  console.log('');
+  console.log('Or use the convenience wrapper:');
+  console.log('  gitd clone <did>/<repo>');
+}
+
+

package/src/cli/commands/shim.ts

@@ -0,0 +1,79 @@
+/**
+ * `gitd shim` — start a package manager / registry compatibility shim.
+ *
+ * Usage:
+ *   gitd shim npm [--port 4873]   Start npm registry shim
+ *   gitd shim go  [--port 4874]   Start Go module proxy shim
+ *   gitd shim oci [--port 5555]   Start OCI/Docker registry shim
+ *
+ * Each shim starts a local HTTP proxy that speaks the native protocol of
+ * the ecosystem tool, resolving DID-scoped packages from DWN records.
+ *
+ * @module
+ */
+
+import type { AgentContext } from '../agent.js';
+
+import { startGoShim } from '../../shims/go/server.js';
+import { startNpmShim } from '../../shims/npm/server.js';
+import { startOciShim } from '../../shims/oci/server.js';
+import { flagValue, parsePort } from '../flags.js';
+
+// ---------------------------------------------------------------------------
+// Default ports
+// ---------------------------------------------------------------------------
+
+const DEFAULT_NPM_PORT = '4873';
+const DEFAULT_GO_PORT = '4874';
+const DEFAULT_OCI_PORT = '5555';
+
+// ---------------------------------------------------------------------------
+// Command
+// ---------------------------------------------------------------------------
+
+export async function shimCommand(ctx: AgentContext, args: string[]): Promise<void> {
+  const sub = args[0];
+  const rest = args.slice(1);
+
+  switch (sub) {
+    case 'npm': {
+      const port = parsePort(
+        flagValue(rest, '--port') ?? process.env.GITD_NPM_SHIM_PORT ?? DEFAULT_NPM_PORT,
+      );
+      console.log('Starting npm registry shim...');
+      startNpmShim({ ctx, port });
+      await new Promise(() => {});
+      break;
+    }
+
+    case 'go': {
+      const port = parsePort(
+        flagValue(rest, '--port') ?? process.env.GITD_GO_SHIM_PORT ?? DEFAULT_GO_PORT,
+      );
+      console.log('Starting Go module proxy shim...');
+      startGoShim({ ctx, port });
+      await new Promise(() => {});
+      break;
+    }
+
+    case 'oci':
+    case 'docker': {
+      const port = parsePort(
+        flagValue(rest, '--port') ?? process.env.GITD_OCI_SHIM_PORT ?? DEFAULT_OCI_PORT,
+      );
+      console.log('Starting OCI/Docker registry shim...');
+      startOciShim({ ctx, port });
+      await new Promise(() => {});
+      break;
+    }
+
+    default:
+      console.error('Usage: gitd shim <npm|go|oci> [--port <port>]');
+      console.error('');
+      console.error('Shims:');
+      console.error(`  npm     npm registry proxy (default port: ${DEFAULT_NPM_PORT})`);
+      console.error(`  go      Go module proxy (default port: ${DEFAULT_GO_PORT})`);
+      console.error(`  oci     OCI/Docker registry proxy (default port: ${DEFAULT_OCI_PORT})`);
+      process.exit(1);
+  }
+}