@enbox/gitd 0.0.1

package/src/cli/commands/ci.ts

@@ -0,0 +1,300 @@
+/**
+ * `gitd ci` — view CI check suites and check runs.
+ *
+ * Usage:
+ *   gitd ci status [<commit>]              Show latest check suite status
+ *   gitd ci list [--limit <n>]             List recent check suites
+ *   gitd ci show <suite-id>                Show check suite details + runs
+ *   gitd ci create <commit> [--app <name>] Create a check suite (for CI bots)
+ *   gitd ci run <suite-id> <name>          Add a check run to a suite
+ *   gitd ci update <run-id> --status <s>   Update a check run status
+ *
+ * @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 ciCommand(ctx: AgentContext, args: string[]): Promise<void> {
+  const sub = args[0];
+  const rest = args.slice(1);
+
+  switch (sub) {
+    case 'status': return ciStatus(ctx, rest);
+    case 'list':
+    case 'ls': return ciList(ctx, rest);
+    case 'show': return ciShow(ctx, rest);
+    case 'create': return ciCreate(ctx, rest);
+    case 'run': return ciRun(ctx, rest);
+    case 'update': return ciUpdate(ctx, rest);
+    default:
+      console.error('Usage: gitd ci <status|list|show|create|run|update>');
+      process.exit(1);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// ci status
+// ---------------------------------------------------------------------------
+
+async function ciStatus(ctx: AgentContext, args: string[]): Promise<void> {
+  const commitFilter = args[0];
+  const repoContextId = await getRepoContextId(ctx);
+
+  const filter: Record<string, unknown> = { contextId: repoContextId };
+  if (commitFilter) {
+    filter.tags = { commitSha: commitFilter };
+  }
+
+  const { records } = await ctx.ci.records.query('repo/checkSuite' as any, {
+    filter,
+    dateSort   : DateSort.CreatedDescending,
+    pagination : { limit: 1 },
+  });
+
+  if (records.length === 0) {
+    console.log('No CI check suites found.');
+    return;
+  }
+
+  const suite = records[0];
+  const data = await suite.data.json();
+  const tags = suite.tags as Record<string, string> | undefined;
+  const status = tags?.status ?? 'unknown';
+  const conclusion = tags?.conclusion;
+  const commit = tags?.commitSha ?? '?';
+  const branch = tags?.branch;
+  const date = suite.dateCreated?.slice(0, 19)?.replace('T', ' ') ?? '';
+
+  console.log(`CI Status: ${status.toUpperCase()}${conclusion ? ` (${conclusion})` : ''}`);
+  console.log(`  Commit:  ${commit}${branch ? ` (${branch})` : ''}`);
+  console.log(`  App:     ${data.app ?? 'unknown'}`);
+  console.log(`  Date:    ${date}`);
+  console.log(`  ID:      ${suite.id}`);
+}
+
+// ---------------------------------------------------------------------------
+// ci list
+// ---------------------------------------------------------------------------
+
+async function ciList(ctx: AgentContext, args: string[]): Promise<void> {
+  const limit = parseInt(flagValue(args, '--limit') ?? '10', 10);
+  const repoContextId = await getRepoContextId(ctx);
+
+  const { records } = await ctx.ci.records.query('repo/checkSuite' as any, {
+    filter     : { contextId: repoContextId },
+    dateSort   : DateSort.CreatedDescending,
+    pagination : { limit },
+  });
+
+  if (records.length === 0) {
+    console.log('No CI check suites found.');
+    return;
+  }
+
+  console.log(`Check suites (${records.length}):\n`);
+  for (const rec of records) {
+    const data = await rec.data.json();
+    const tags = rec.tags as Record<string, string> | undefined;
+    const status = tags?.status ?? 'unknown';
+    const conclusion = tags?.conclusion;
+    const commit = (tags?.commitSha ?? '?').slice(0, 8);
+    const branch = tags?.branch;
+    const date = rec.dateCreated?.slice(0, 10) ?? '';
+    const statusStr = conclusion ? `${status}:${conclusion}` : status;
+    console.log(`  [${statusStr.toUpperCase().padEnd(18)}] ${commit} ${data.app ?? ''}${branch ? ` (${branch})` : ''}  ${date}`);
+    console.log(`${''.padEnd(24)}id: ${rec.id}`);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// ci show
+// ---------------------------------------------------------------------------
+
+async function ciShow(ctx: AgentContext, args: string[]): Promise<void> {
+  const suiteId = args[0];
+  if (!suiteId) {
+    console.error('Usage: gitd ci show <suite-id>');
+    process.exit(1);
+  }
+
+  const { records: suites } = await ctx.ci.records.query('repo/checkSuite' as any, {
+    filter: { recordId: suiteId },
+  });
+
+  if (suites.length === 0) {
+    console.error(`Check suite ${suiteId} not found.`);
+    process.exit(1);
+  }
+
+  const suite = suites[0];
+  const data = await suite.data.json();
+  const tags = suite.tags as Record<string, string> | undefined;
+  const status = tags?.status ?? 'unknown';
+  const conclusion = tags?.conclusion;
+  const commit = tags?.commitSha ?? '?';
+  const branch = tags?.branch;
+  const date = suite.dateCreated?.slice(0, 19)?.replace('T', ' ') ?? '';
+
+  console.log(`Check Suite: ${data.app ?? 'unknown'}`);
+  console.log(`  Status:     ${status.toUpperCase()}${conclusion ? ` (${conclusion})` : ''}`);
+  console.log(`  Commit:     ${commit}${branch ? ` (${branch})` : ''}`);
+  console.log(`  Created:    ${date}`);
+  console.log(`  ID:         ${suite.id}`);
+
+  // Fetch check runs.
+  const { records: runs } = await ctx.ci.records.query('repo/checkSuite/checkRun' as any, {
+    filter: { contextId: suite.contextId },
+  });
+
+  if (runs.length > 0) {
+    console.log('');
+    console.log(`  Check runs (${runs.length}):`);
+    console.log('  ---');
+    for (const run of runs) {
+      const runData = await run.data.json();
+      const runTags = run.tags as Record<string, string> | undefined;
+      const runStatus = runTags?.status ?? 'unknown';
+      const runConclusion = runTags?.conclusion;
+      const runName = runTags?.name ?? 'unnamed';
+      const statusStr = runConclusion ? `${runStatus}:${runConclusion}` : runStatus;
+      console.log(`  [${statusStr.toUpperCase()}] ${runName}`);
+      if (runData.output) {
+        console.log(`    ${runData.output.title}: ${runData.output.summary}`);
+      }
+      console.log('  ---');
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// ci create
+// ---------------------------------------------------------------------------
+
+async function ciCreate(ctx: AgentContext, args: string[]): Promise<void> {
+  const commitSha = args[0];
+  const app = flagValue(args, '--app') ?? 'gitd-ci';
+  const branch = flagValue(args, '--branch');
+
+  if (!commitSha) {
+    console.error('Usage: gitd ci create <commit-sha> [--app <name>] [--branch <branch>]');
+    process.exit(1);
+  }
+
+  const repoContextId = await getRepoContextId(ctx);
+
+  const tags: Record<string, string> = {
+    commitSha,
+    status: 'queued',
+  };
+  if (branch) { tags.branch = branch; }
+
+  const { status, record } = await ctx.ci.records.create('repo/checkSuite' as any, {
+    data            : { app },
+    tags,
+    parentContextId : repoContextId,
+  } as any);
+
+  if (status.code >= 300) {
+    console.error(`Failed to create check suite: ${status.code} ${status.detail}`);
+    process.exit(1);
+  }
+
+  console.log(`Created check suite for ${commitSha.slice(0, 8)} (app: ${app})`);
+  console.log(`  Suite ID: ${record.id}`);
+}
+
+// ---------------------------------------------------------------------------
+// ci run
+// ---------------------------------------------------------------------------
+
+async function ciRun(ctx: AgentContext, args: string[]): Promise<void> {
+  const suiteId = args[0];
+  const name = args[1];
+
+  if (!suiteId || !name) {
+    console.error('Usage: gitd ci run <suite-id> <name>');
+    process.exit(1);
+  }
+
+  // Look up the suite to get its contextId.
+  const { records: suites } = await ctx.ci.records.query('repo/checkSuite' as any, {
+    filter: { recordId: suiteId },
+  });
+
+  if (suites.length === 0) {
+    console.error(`Check suite ${suiteId} not found.`);
+    process.exit(1);
+  }
+
+  const { status, record } = await ctx.ci.records.create('repo/checkSuite/checkRun' as any, {
+    data            : {},
+    tags            : { name, status: 'queued' },
+    parentContextId : suites[0].contextId,
+  } as any);
+
+  if (status.code >= 300) {
+    console.error(`Failed to create check run: ${status.code} ${status.detail}`);
+    process.exit(1);
+  }
+
+  console.log(`Created check run "${name}" in suite ${suiteId.slice(0, 8)}...`);
+  console.log(`  Run ID: ${record.id}`);
+}
+
+// ---------------------------------------------------------------------------
+// ci update
+// ---------------------------------------------------------------------------
+
+async function ciUpdate(ctx: AgentContext, args: string[]): Promise<void> {
+  const runId = args[0];
+  const newStatus = flagValue(args, '--status');
+  const conclusion = flagValue(args, '--conclusion');
+
+  if (!runId || !newStatus) {
+    console.error('Usage: gitd ci update <run-id> --status <queued|in_progress|completed> [--conclusion <success|failure|cancelled|skipped>]');
+    process.exit(1);
+  }
+
+  if (!['queued', 'in_progress', 'completed'].includes(newStatus)) {
+    console.error(`Invalid status: ${newStatus}. Must be queued, in_progress, or completed.`);
+    process.exit(1);
+  }
+
+  // Find the run record.
+  const { records: runs } = await ctx.ci.records.query('repo/checkSuite/checkRun' as any, {
+    filter: { recordId: runId },
+  });
+
+  if (runs.length === 0) {
+    console.error(`Check run ${runId} not found.`);
+    process.exit(1);
+  }
+
+  const run = runs[0];
+  const existingData = await run.data.json();
+  const existingTags = run.tags as Record<string, string> | undefined;
+
+  const updatedTags: Record<string, string> = { ...existingTags, status: newStatus };
+  if (conclusion) { updatedTags.conclusion = conclusion; }
+
+  const { status } = await run.update({
+    data : existingData,
+    tags : updatedTags,
+  });
+
+  if (status.code >= 300) {
+    console.error(`Failed to update check run: ${status.code} ${status.detail}`);
+    process.exit(1);
+  }
+
+  console.log(`Updated check run ${runId.slice(0, 8)}... → ${newStatus}${conclusion ? ` (${conclusion})` : ''}`);
+}

package/src/cli/commands/clone.ts

@@ -0,0 +1,78 @@
+/**
+ * `gitd clone <did>/<repo>` — clone a repository by DID.
+ *
+ * Convenience wrapper that:
+ * 1. Validates the DID/repo argument
+ * 2. Spawns `git clone did::<did>/<repo>` with inherited stdio
+ *
+ * Usage: gitd clone <did>/<repo> [-- <git-clone-args...>]
+ *
+ * @module
+ */
+
+import { spawn } from 'node:child_process';
+
+// ---------------------------------------------------------------------------
+// Command
+// ---------------------------------------------------------------------------
+
+export async function cloneCommand(args: string[]): Promise<void> {
+  const target = args[0];
+
+  if (!target) {
+    console.error('Usage: gitd clone <did>/<repo> [-- <git-clone-args...>]');
+    console.error('');
+    console.error('Examples:');
+    console.error('  gitd clone did:dht:abc123/my-repo');
+    console.error('  gitd clone did:dht:abc123/my-repo -- --depth 1');
+    process.exit(1);
+  }
+
+  // Parse the target: expect "did:<method>:<id>/<repo>" format.
+  const slashIdx = target.indexOf('/');
+  if (slashIdx === -1 || !target.startsWith('did:')) {
+    console.error(`Invalid target: "${target}"`);
+    console.error('Expected format: did:<method>:<id>/<repo>');
+    console.error('Example: did:dht:abc123/my-repo');
+    process.exit(1);
+  }
+
+  const didPart = target.slice(0, slashIdx);
+  const repoPart = target.slice(slashIdx + 1);
+
+  if (didPart.split(':').length < 3) {
+    console.error(`Invalid DID: "${didPart}"`);
+    console.error('Expected format: did:<method>:<id>');
+    process.exit(1);
+  }
+
+  if (!repoPart) {
+    console.error('Missing repository name after DID.');
+    console.error('Expected format: did:<method>:<id>/<repo>');
+    process.exit(1);
+  }
+
+  // Collect any extra git args after `--`.
+  const dashDashIdx = args.indexOf('--');
+  const extraArgs = dashDashIdx !== -1 ? args.slice(dashDashIdx + 1) : [];
+
+  // Build the DID transport URL: `did::<did>/<repo>`
+  const didUrl = `did::${didPart}/${repoPart}`;
+
+  console.log(`Cloning ${didPart}/${repoPart} via DID transport...`);
+  console.log('');
+
+  // Spawn git clone with inherited stdio so the user sees progress.
+  const exitCode = await new Promise<number>((resolve, reject) => {
+    const child = spawn('git', ['clone', didUrl, ...extraArgs], {
+      stdio : 'inherit',
+      env   : process.env,
+    });
+    child.on('error', reject);
+    child.on('exit', (code) => resolve(code ?? 128));
+  });
+
+  if (exitCode !== 0) {
+    process.exit(exitCode);
+  }
+}

package/src/cli/commands/daemon.ts

@@ -0,0 +1,129 @@
+/**
+ * `gitd daemon` — start the unified shim daemon.
+ *
+ * Starts all enabled ecosystem shims in a single process.  Each shim
+ * runs on its own port and speaks the native protocol of its ecosystem
+ * (GitHub REST API, npm registry, GOPROXY, OCI Distribution, etc.).
+ *
+ * Usage:
+ *   gitd daemon                                Start all shims with defaults
+ *   gitd daemon --config ./daemon.json         Use a config file
+ *   gitd daemon --only github,npm              Only start specific shims
+ *   gitd daemon --disable go,oci               Start all except specific shims
+ *   gitd daemon --list                         List available shims and exit
+ *
+ * Config file format (gitd.daemon.json):
+ *   {
+ *     "shims": {
+ *       "github": { "enabled": true, "port": 8181 },
+ *       "npm":    { "enabled": true, "port": 4873 },
+ *       "go":     { "enabled": true, "port": 4874 },
+ *       "oci":    { "enabled": true, "port": 5555 }
+ *     }
+ *   }
+ *
+ * @module
+ */
+
+import { existsSync, readFileSync } from 'node:fs';
+
+import type { AgentContext } from '../agent.js';
+import type { DaemonConfig } from '../../daemon/adapter.js';
+
+import { builtinAdapters } from '../../daemon/adapters/index.js';
+import { flagValue } from '../flags.js';
+import { startDaemon } from '../../daemon/server.js';
+
+// ---------------------------------------------------------------------------
+// Config loading
+// ---------------------------------------------------------------------------
+
+/** Default config file name searched in CWD. */
+const DEFAULT_CONFIG_FILES = [
+  'gitd.daemon.json',
+  '.gitd-daemon.json',
+];
+
+/**
+ * Load and merge config from file + CLI flags.
+ */
+function loadConfig(args: string[]): DaemonConfig {
+  // Start with empty config (all defaults).
+  let config: DaemonConfig = {};
+
+  // Load config file if specified or found in CWD.
+  const configPath = flagValue(args, '--config');
+  if (configPath) {
+    if (!existsSync(configPath)) {
+      console.error(`Config file not found: ${configPath}`);
+      process.exit(1);
+    }
+    config = JSON.parse(readFileSync(configPath, 'utf-8'));
+  } else {
+    // Auto-discover config in CWD.
+    for (const name of DEFAULT_CONFIG_FILES) {
+      if (existsSync(name)) {
+        config = JSON.parse(readFileSync(name, 'utf-8'));
+        console.log(`[daemon] Using config from ${name}`);
+        break;
+      }
+    }
+  }
+
+  // Apply --only filter (disables everything not listed).
+  const only = flagValue(args, '--only');
+  if (only) {
+    const ids = new Set(only.split(',').map((s) => s.trim()));
+    if (!config.shims) { config.shims = {}; }
+    for (const adapter of builtinAdapters) {
+      if (!config.shims[adapter.id]) { config.shims[adapter.id] = {}; }
+      config.shims[adapter.id].enabled = ids.has(adapter.id);
+    }
+  }
+
+  // Apply --disable filter.
+  const disable = flagValue(args, '--disable');
+  if (disable) {
+    const ids = new Set(disable.split(',').map((s) => s.trim()));
+    if (!config.shims) { config.shims = {}; }
+    for (const id of ids) {
+      if (!config.shims[id]) { config.shims[id] = {}; }
+      config.shims[id].enabled = false;
+    }
+  }
+
+  return config;
+}
+
+// ---------------------------------------------------------------------------
+// Command
+// ---------------------------------------------------------------------------
+
+export async function daemonCommand(ctx: AgentContext, args: string[]): Promise<void> {
+  // --list: show available shims and exit.
+  if (args.includes('--list')) {
+    console.log('Available shims:\n');
+    for (const adapter of builtinAdapters) {
+      console.log(`  ${adapter.id.padEnd(12)} ${adapter.name.padEnd(24)} default port: ${adapter.defaultPort}  env: ${adapter.portEnvVar}`);
+    }
+    console.log(`\nTotal: ${builtinAdapters.length} adapters`);
+    return;
+  }
+
+  const config = loadConfig(args);
+  const instance = await startDaemon({ ctx, config });
+
+  // Register signal handlers for graceful shutdown.
+  const shutdown = async (): Promise<void> => {
+    console.log('\n[daemon] Shutting down...');
+    await instance.stop();
+    console.log('[daemon] All shims stopped.');
+    process.exit(0);
+  };
+
+  process.on('SIGINT', shutdown);
+  process.on('SIGTERM', shutdown);
+
+  // Keep the process alive.
+  await new Promise(() => {});
+}

package/src/cli/commands/github-api.ts

@@ -0,0 +1,30 @@
+/**
+ * `gitd github-api` — start the GitHub API compatibility shim.
+ *
+ * Usage:
+ *   gitd github-api [--port <port>]
+ *
+ * Starts a read-only HTTP server that translates GitHub REST API v3
+ * requests into DWN queries.  Default port: 8181.
+ *
+ * @module
+ */
+
+import type { AgentContext } from '../agent.js';
+
+import { startShimServer } from '../../github-shim/server.js';
+import { flagValue, parsePort } from '../flags.js';
+
+// ---------------------------------------------------------------------------
+// Command
+// ---------------------------------------------------------------------------
+
+export async function githubApiCommand(ctx: AgentContext, args: string[]): Promise<void> {
+  const port = parsePort(flagValue(args, '--port') ?? process.env.GITD_GITHUB_API_PORT ?? '8181');
+
+  console.log('Starting GitHub API compatibility shim...');
+  startShimServer({ ctx, port });
+
+  // Keep the process alive — the server runs until Ctrl+C.
+  await new Promise(() => {});
+}

package/src/cli/commands/init.ts

@@ -0,0 +1,69 @@
+/**
+ * `gitd init` — create a forge repository record on the local DWN
+ * and initialize a bare git repository on the filesystem.
+ *
+ * Usage: gitd init <name> [--description <text>] [--branch <name>] [--repos <path>]
+ *
+ * @module
+ */
+
+import type { AgentContext } from '../agent.js';
+
+import { flagValue } from '../flags.js';
+import { GitBackend } from '../../git-server/git-backend.js';
+
+// ---------------------------------------------------------------------------
+// Command
+// ---------------------------------------------------------------------------
+
+export async function initCommand(ctx: AgentContext, args: string[]): Promise<void> {
+  const name = args[0];
+  const description = flagValue(args, '--description') ?? flagValue(args, '-d');
+  const branch = flagValue(args, '--branch') ?? flagValue(args, '-b') ?? 'main';
+  const reposPath = flagValue(args, '--repos') ?? process.env.GITD_REPOS ?? './repos';
+
+  if (!name) {
+    console.error('Usage: gitd init <name> [--description <text>] [--branch <name>] [--repos <path>]');
+    process.exit(1);
+  }
+
+  // Check if a repo already exists (singleton).
+  const { records: existing } = await ctx.repo.records.query('repo');
+  if (existing.length > 0) {
+    const data = await existing[0].data.json();
+    console.error(`Repository "${data.name}" already exists (recordId: ${existing[0].id}).`);
+    console.error('The forge-repo protocol allows only one repo record per DWN.');
+    process.exit(1);
+  }
+
+  // Initialize the bare git repository on disk.
+  const backend = new GitBackend({ basePath: reposPath });
+  const gitPath = await backend.initRepo(ctx.did, name);
+
+  // Create the DWN repo record.
+  const { status, record } = await ctx.repo.records.create('repo', {
+    data: {
+      name,
+      description   : description ?? '',
+      defaultBranch : branch,
+      dwnEndpoints  : [],
+    },
+    tags: {
+      name,
+      visibility: 'public',
+    },
+  });
+
+  if (status.code >= 300) {
+    console.error(`Failed to create repo: ${status.code} ${status.detail}`);
+    process.exit(1);
+  }
+
+  console.log(`Initialized forge repo "${name}" (branch: ${branch})`);
+  console.log(`  DID:       ${ctx.did}`);
+  console.log(`  Record ID: ${record.id}`);
+  console.log(`  Context:   ${record.contextId}`);
+  console.log(`  Git path:  ${gitPath}`);
+}
+
+