hanzo.ai/lib/go-modules.ts

// `go get hanzo.ai/iam` — the import path is the site, not the host holding the code.
//
// The go tool asks for the import path with ?go-get=1 and reads one meta tag out
// of the answer. A static export has no middleware to write that tag, so it is
// page metadata, and every module below therefore needs a page at its own name.
//
// The tag points at GITHUB and not the forge, which is measured rather than
// preferred: an unauthenticated clone of git.hanzo.ai answers `could not read
// Username`, so a tag naming it would fail for everyone who is not us —
// including proxy.golang.org, which fetches anonymously and is what makes a
// module resolvable at all.
//
// A module is listed only if `github.com/hanzoai/<name>` answers 200 to an
// anonymous request AND the repository name equals the module name. Publishing a
// path that resolves to nothing is worse than publishing none: `go get` fails at
// the clone, after the tool has already told the caller the path is real.


/** Modules whose name is free at the root, so they get their own page. */
export const OWNED = [
  'lz4/v4',
  'openai',
  'openrouter',
  'sdk',
  'sendgrid',
  'age',
  'agent',
  'base-ha',
  'builder',
  'cd',
  'cek',
  'ci',
  'cpy3',
  'csqlite',
  'dashscope-go-sdk',
  'dashscopego',
  'dbx',
  'egress',
  'finance',
  'flags',
  'framework',
  'gochimp3',
  'graph',
  'grpc-web',
  'ingress-parser',
  'insights-go',
  'kafka',
  'kms-operator',
  'livekit',
  'log',
  'ltx',
  'namespace',
  'notify',
  'o11y-foundry',
  'onnxgo',
  'orm',
  'otel-collector',
  'pdf',
  'proto',
  'pubsub-go',
  'replicate',
  'search-go',
  'sqlcipher',
  'sqlite',
  'sqlite-vec',
  'tygoja',
  'vfs',
  'xorm',
  'yaegi',
  'zip',
] as const

/** Modules whose name is already a product page. That page carries the tag. */
export const SHARED = [
  'account',
  'ai',
  'authz',
  'base',
  'captable',
  'cloud',
  'commerce',
  'dashboards',
  'dataroom',
  'docdb',
  'functions',
  'hsm',
  'iam',
  'idv',
  'ingress',
  'metrics',
  'o11y',
  'pricing',
  'pubsub',
  's3',
  'status',
  'tasks',
  'visor',
  'zen',
] as const

export const MODULES = [...OWNED, ...SHARED]

/** The tag, defined once. `go-source` is what pkg.go.dev links "source" to. */
export function goImport(name: string) {
  const path = `hanzo.ai/${name}`
  const repo = repoOf(name)
  return {
    'go-import': `${path} git ${repo}`,
    'go-source': `${path} ${repo} ${repo}/tree/main{/dir} ${repo}/blob/main{/dir}/{file}#L{line}`,
  }
}

/**
 * Modules whose CODE lives in the hanzo-go org rather than hanzoai. The import
 * path does not move with them — `hanzo.ai/openai` is the name a consumer pins
 * whichever org holds the git repo — so this is the one place the two facts are
 * allowed to differ, and it exists so moving a repo between orgs is a one-line
 * edit here instead of a break for everyone who pinned it.
 *
 * GitHub does redirect a moved repo, so a stale URL keeps working. That is a
 * courtesy and not a contract: it is lost the day someone creates a new repo at
 * the old name, and the failure then is a clone that succeeds against the WRONG
 * code. Name the real location.
 */
const GO_ORG = new Set(['tygoja', 'lz4', 'openai', 'openrouter', 'sendgrid', 'sdk'])

/**
 * The REPOSITORY a module path lives in, which is the path's first segment and
 * never the whole path. A major-version module is `hanzo.ai/lz4/v4` and its repo
 * is `lz4` — the `/vN` suffix is part of the MODULE path by Go's own rule and was
 * never part of the repo name. Splitting here is what lets a versioned module be
 * listed at all; comparing the full path to a repo name rejects every one of
 * them, which is why lz4/v4, datastore-go/v2, gateway/v2, gomail/v2, iamsdk/v2
 * and kv-go/v9 were absent from this list despite their repos being public.
 */
export const repoOf = (name: string) => {
  const repo = name.split('/')[0]
  return `https://github.com/${GO_ORG.has(repo) ? 'hanzo-go' : 'hanzoai'}/${repo}`
}

/**
 * The module path a repo's go.mod declares, where it is not the repository's own
 * GitHub address. It is the only path `go get` accepts for the module, and the one
 * pkg.go.dev files it under: asked for the GitHub address of a repo that declares
 * another path, the go tool fetches the repo and then refuses it, and pkg.go.dev
 * has no page. Each value is read from that repo's go.mod; when a module's
 * `module` line moves, its entry here moves in the same change.
 */
const DECLARED: Record<string, string> = {
  'lz4/v4': 'hanzo.ai/lz4/v4',
  ci: 'hanzo.ai/ci',
  finance: 'hanzo.ai/finance',
  onnxgo: 'hanzo.ai/onnxgo',
  proto: 'hanzo.ai/proto',
  tygoja: 'hanzo.ai/tygoja',
  zip: 'hanzo.ai/zip',
  flags: 'github.com/hanzoai/flags/go',
  openai: 'github.com/hanzoai/go-openai',
  openrouter: 'github.com/hanzoai/go-openrouter',
  sdk: 'github.com/hanzoai/go-sdk/v8',
  sendgrid: 'github.com/hanzoai/sendgrid-go',
}

/** The path `go get` accepts for a module, and pkg.go.dev's name for it. */
export const modulePathOf = (name: string) =>
  DECLARED[name] ?? repoOf(name).replace(/^https:\/\//, '')

/**
 * Modules pkg.go.dev has no page for, so their page says so instead of linking one.
 * pkg.go.dev files hanzo.ai/proto as another path of github.com/hanzoai/proto,
 * whose go.mod declares hanzo.ai/proto, and answers 404 for both; a request to
 * fetch it answers that the module could not be found.
 */
export const UNREFERENCED: ReadonlySet<string> = new Set(['proto'])