add documentation for ai agents (#3115)

* add documentation for ai agents * docs: consolidate CLAUDE.md and CONTRIBUTING.md, add style guidelines - Refactor CLAUDE.md to reference CONTRIBUTING.md for build/test/format info - Expand CONTRIBUTING.md with comprehensive build targets, env vars, and testing - Add code style guidelines section with conventional commits - Standardize SDK prettier config to use single quotes (matching web) - Add project-level Claude Code settings to disable co-author attribution * style(sdk): apply prettier with single quotes Run prettier across sdk/base and sdk/package to apply the standardized quote style (single quotes matching web). * docs: add USER.md for per-developer TODO filtering - Add agents/USER.md to .gitignore (contains user identifier) - Document session startup flow in CLAUDE.md: - Create USER.md if missing, prompting for identifier - Filter TODOs by @username tags - Offer relevant TODOs on session start * docs: add i18n documentation task to agent TODOs * docs: document i18n ID patterns in core/ Add agents/i18n-patterns.md covering rust-i18n setup, translation file format, t!() macro usage, key naming conventions, and locale selection. Remove completed TODO item and add reference in CLAUDE.md. * chore: clarify that all builds work on any OS with Docker
2026-03-30 20:14:49 +00:00 · 2026-02-06 00:10:16 +01:00
parent 86ca23c093
commit f2142f0bb3
280 changed files with 6793 additions and 5515 deletions
--- a/sdk/package/lib/health/HealthCheck.ts
+++ b/sdk/package/lib/health/HealthCheck.ts
@@ -1,10 +1,10 @@
-import { Effects, HealthCheckId } from "../../../base/lib/types"
-import { HealthCheckResult } from "./checkFns/HealthCheckResult"
-import { Trigger } from "../trigger"
-import { TriggerInput } from "../trigger/TriggerInput"
-import { defaultTrigger } from "../trigger/defaultTrigger"
-import { once, asError, Drop } from "../util"
-import { object, unknown } from "ts-matches"
+import { Effects, HealthCheckId } from '../../../base/lib/types'
+import { HealthCheckResult } from './checkFns/HealthCheckResult'
+import { Trigger } from '../trigger'
+import { TriggerInput } from '../trigger/TriggerInput'
+import { defaultTrigger } from '../trigger/defaultTrigger'
+import { once, asError, Drop } from '../util'
+import { object, unknown } from 'ts-matches'

 export type HealthCheckParams = {
  id: HealthCheckId
@@ -59,15 +59,15 @@ export class HealthCheck extends Drop {
            try {
              let { result, message } = await o.fn()
              if (
-                result === "failure" &&
+                result === 'failure' &&
                performance.now() - started <= gracePeriod
              )
-                result = "starting"
+                result = 'starting'
              await effects.setHealth({
                name: o.name,
                id: o.id,
                result,
-                message: message || "",
+                message: message || '',
              })
              this.currentValue.lastResult = result
            } catch (e) {
@@ -76,11 +76,11 @@ export class HealthCheck extends Drop {
                id: o.id,
                result:
                  performance.now() - started <= gracePeriod
-                    ? "starting"
-                    : "failure",
-                message: asMessage(e) || "",
+                    ? 'starting'
+                    : 'failure',
+                message: asMessage(e) || '',
              })
-              this.currentValue.lastResult = "failure"
+              this.currentValue.lastResult = 'failure'
            }
          }
        } else triggered = false
--- a/sdk/package/lib/health/checkFns/HealthCheckResult.ts
+++ b/sdk/package/lib/health/checkFns/HealthCheckResult.ts
@@ -1,3 +1,3 @@
-import { T } from "../../../../base/lib"
+import { T } from '../../../../base/lib'

-export type HealthCheckResult = Omit<T.NamedHealthCheckResult, "name">
+export type HealthCheckResult = Omit<T.NamedHealthCheckResult, 'name'>
--- a/sdk/package/lib/health/checkFns/checkPortListening.ts
+++ b/sdk/package/lib/health/checkFns/checkPortListening.ts
@@ -1,17 +1,17 @@
-import { Effects } from "../../../../base/lib/types"
-import { stringFromStdErrOut } from "../../util"
-import { HealthCheckResult } from "./HealthCheckResult"
-import { promisify } from "node:util"
-import * as CP from "node:child_process"
+import { Effects } from '../../../../base/lib/types'
+import { stringFromStdErrOut } from '../../util'
+import { HealthCheckResult } from './HealthCheckResult'
+import { promisify } from 'node:util'
+import * as CP from 'node:child_process'

 const cpExec = promisify(CP.exec)

 export function containsAddress(x: string, port: number, address?: bigint) {
  const readPorts = x
-    .split("\n")
+    .split('\n')
    .filter(Boolean)
    .splice(1)
-    .map((x) => x.split(" ").filter(Boolean)[1]?.split(":"))
+    .map((x) => x.split(' ').filter(Boolean)[1]?.split(':'))
    .filter((x) => x?.length > 1)
    .map(([addr, p]) => [BigInt(`0x${addr}`), Number.parseInt(p, 16)] as const)
  return !!readPorts.find(
@@ -46,19 +46,19 @@ export async function checkPortListening(
          BigInt(0),
        ) ||
        containsAddress(
-          await cpExec("cat /proc/net/udp", {}).then(stringFromStdErrOut),
+          await cpExec('cat /proc/net/udp', {}).then(stringFromStdErrOut),
          port,
        ) ||
        containsAddress(
-          await cpExec("cat /proc/net/udp6", {}).then(stringFromStdErrOut),
+          await cpExec('cat /proc/net/udp6', {}).then(stringFromStdErrOut),
          port,
          BigInt(0),
        )
      if (hasAddress) {
-        return { result: "success", message: options.successMessage }
+        return { result: 'success', message: options.successMessage }
      }
      return {
-        result: "failure",
+        result: 'failure',
        message: options.errorMessage,
      }
    }),
@@ -66,7 +66,7 @@ export async function checkPortListening(
      setTimeout(
        () =>
          resolve({
-            result: "failure",
+            result: 'failure',
            message:
              options.timeoutMessage || `Timeout trying to check port ${port}`,
          }),
--- a/sdk/package/lib/health/checkFns/checkWebUrl.ts
+++ b/sdk/package/lib/health/checkFns/checkWebUrl.ts
@@ -1,8 +1,8 @@
-import { Effects } from "../../../../base/lib/types"
-import { asError } from "../../util"
-import { HealthCheckResult } from "./HealthCheckResult"
-import { timeoutPromise } from "./index"
-import "isomorphic-fetch"
+import { Effects } from '../../../../base/lib/types'
+import { asError } from '../../util'
+import { HealthCheckResult } from './HealthCheckResult'
+import { timeoutPromise } from './index'
+import 'isomorphic-fetch'

 /**
 * This is a helper function to check if a web url is reachable.
@@ -23,7 +23,7 @@ export const checkWebUrl = async (
    .then(
      (x) =>
        ({
-          result: "success",
+          result: 'success',
          message: successMessage,
        }) as const,
    )
@@ -31,6 +31,6 @@ export const checkWebUrl = async (
      console.warn(`Error while fetching URL: ${url}`)
      console.error(JSON.stringify(e))
      console.error(asError(e))
-      return { result: "failure" as const, message: errorMessage }
+      return { result: 'failure' as const, message: errorMessage }
    })
 }
--- a/sdk/package/lib/health/checkFns/index.ts
+++ b/sdk/package/lib/health/checkFns/index.ts
@@ -1,9 +1,9 @@
-import { runHealthScript } from "./runHealthScript"
-export { checkPortListening } from "./checkPortListening"
-export { HealthCheckResult } from "./HealthCheckResult"
-export { checkWebUrl } from "./checkWebUrl"
+import { runHealthScript } from './runHealthScript'
+export { checkPortListening } from './checkPortListening'
+export { HealthCheckResult } from './HealthCheckResult'
+export { checkWebUrl } from './checkWebUrl'

-export function timeoutPromise(ms: number, { message = "Timed out" } = {}) {
+export function timeoutPromise(ms: number, { message = 'Timed out' } = {}) {
  return new Promise<never>((resolve, reject) =>
    setTimeout(() => reject(new Error(message)), ms),
  )
--- a/sdk/package/lib/health/checkFns/runHealthScript.ts
+++ b/sdk/package/lib/health/checkFns/runHealthScript.ts
@@ -1,7 +1,7 @@
-import { HealthCheckResult } from "./HealthCheckResult"
-import { timeoutPromise } from "./index"
-import { SubContainer } from "../../util/SubContainer"
-import { SDKManifest } from "../../types"
+import { HealthCheckResult } from './HealthCheckResult'
+import { timeoutPromise } from './index'
+import { SubContainer } from '../../util/SubContainer'
+import { SDKManifest } from '../../types'

 /**
 * Running a health script, is used when we want to have a simple
@@ -27,10 +27,10 @@ export const runHealthScript = async <Manifest extends SDKManifest>(
    console.warn(errorMessage)
    console.warn(JSON.stringify(e))
    console.warn(e.toString())
-    throw { result: "failure", message: errorMessage } as HealthCheckResult
+    throw { result: 'failure', message: errorMessage } as HealthCheckResult
  })
  return {
-    result: "success",
+    result: 'success',
    message: message(res.stdout.toString()),
  } as HealthCheckResult
 }
--- a/sdk/package/lib/health/index.ts
+++ b/sdk/package/lib/health/index.ts
@@ -1,3 +1,3 @@
-import "./checkFns"
+import './checkFns'

-export { HealthCheck } from "./HealthCheck"
+export { HealthCheck } from './HealthCheck'