@xtrn/cli 1.0.0

package/README.md

@@ -0,0 +1,79 @@
+# @xtrn/cli
+
+CLI toolkit for developing and submitting XTRN tool servers.
+
+## Install
+
+```bash
+bun add -g @xtrn/cli
+```
+
+Or use per-project:
+
+```bash
+bun add -d @xtrn/cli
+```
+
+## Commands
+
+### `xtrn init <name> <version>`
+
+Scaffold a new XTRN server project.
+
+```bash
+xtrn init my-server v1.0.0
+cd my-server
+bun install
+xtrn dev
+```
+
+Creates a directory with:
+- `index.ts` — Server entry point with example configuration
+- `package.json` — Dependencies and scripts
+- `tsconfig.json` — TypeScript configuration
+- `.dev.vars.example` — OAuth environment variable template
+- `README.md` — Full API guide
+
+Arguments:
+- `name` — Server name in slug format (e.g., `my-server`)
+- `version` — Semver with v prefix (e.g., `v1.0.0`)
+
+### `xtrn dev [entry] [--port=N]`
+
+Start a local dev server using wrangler with Durable Objects.
+
+```bash
+xtrn dev                    # ./index.ts on port 1234
+xtrn dev ./server.ts        # Custom entry point
+xtrn dev --port=3000        # Custom port
+```
+
+Automatically loads `.dev.vars` for OAuth secrets and other environment variables.
+
+### `xtrn submit`
+
+Submit your server to the [xtrn-servers](https://github.com/AbhinavPalacharla/xtrn-servers) registry.
+
+```bash
+xtrn submit
+```
+
+This forks the xtrn-servers repo and opens a PR with your server code. Requires [GitHub CLI](https://cli.github.com/) (`gh`).
+
+## Getting Started
+
+```bash
+bun add -g @xtrn/cli
+xtrn init my-server v1.0.0
+cd my-server
+bun install
+xtrn dev
+```
+
+Then open `http://localhost:1234/details`.
+
+See [@xtrn/server](https://www.npmjs.com/package/@xtrn/server) for the full server framework API.
+
+## License
+
+MIT

package/dist/cli.js

@@ -0,0 +1,66 @@
+#!/usr/bin/env node
+import{spawn as V}from"node:child_process";import*as R from"node:fs";import*as _ from"node:path";import{spawn as Y}from"node:child_process";import*as x from"node:fs";import*as M from"node:os";import*as g from"node:path";function X(o){let n=o;while(!0){let s=g.join(n,"node_modules");if(x.existsSync(s))return s;let t=g.dirname(n);if(t===n)return null;n=t}}function O(o,n,s){let t=g.dirname(o),e=X(t);if(!e)console.warn("[xtrn] Warning: node_modules not found for symlink");let i=g.join(s,"node_modules");if(e&&!x.existsSync(i))x.symlinkSync(e,i,"junction");let a=`export { XTRNState } from "@xtrn/server";
+export { default } from "${o}";
+`;x.writeFileSync(g.join(s,"_cf_entry.ts"),a);let c=`name = "xtrn-dev"
+main = "_cf_entry.ts"
+compatibility_date = "2026-02-14"
+compatibility_flags = ["nodejs_compat"]
+
+[vars]
+${Object.entries(n).map(([m,l])=>`${m} = "${l}"`).join(`
+`)}
+
+[[durable_objects.bindings]]
+name = "XTRN_STATE"
+class_name = "XTRNState"
+
+[[migrations]]
+tag = "v1"
+new_sqlite_classes = ["XTRNState"]
+`;x.writeFileSync(g.join(s,"wrangler.toml"),c)}async function A(o,n){let s=g.dirname(o),t=g.basename(o),e=g.join(n,t);x.copyFileSync(o,e);let i=X(s);if(!i)console.warn("[xtrn] Warning: node_modules not found for symlink");let a=g.join(n,"node_modules");if(i&&!x.existsSync(a))x.symlinkSync(i,a,"junction");let c=`export { XTRNState } from "@xtrn/server";
+export { default } from "${`./${t}`}";
+`,m=g.join(n,"_cf_entry.ts");x.writeFileSync(m,c);let l=`name = "xtrn-dev"
+main = "_cf_entry.ts"
+compatibility_date = "2026-02-14"
+compatibility_flags = ["nodejs_compat"]
+
+[[durable_objects.bindings]]
+name = "XTRN_STATE"
+class_name = "XTRNState"
+
+[[migrations]]
+tag = "v1"
+new_sqlite_classes = ["XTRNState"]
+`;return x.writeFileSync(g.join(n,"wrangler.toml"),l),await Z(n),g.join(n,"_cf_entry.js")}function Z(o){return new Promise((n,s)=>{let t=Y("wrangler",["deploy","--dry-run","--outdir","."],{cwd:o,stdio:["ignore","pipe","pipe"]}),e="";t.stdout?.on("data",()=>{}),t.stderr?.on("data",(i)=>{e+=i.toString()}),t.on("error",(i)=>{s(Error(`Failed to spawn wrangler: ${i.message}`))}),t.on("close",(i)=>{if(i!==0){s(Error(`wrangler deploy --dry-run failed (exit ${i}):
+${e}`));return}n()})})}function $(){return x.mkdtempSync(g.join(M.tmpdir(),"xtrn-dev-"))}function S(o){x.rmSync(o,{recursive:!0,force:!0})}import*as N from"node:fs";import*as F from"node:path";import{Miniflare as G}from"miniflare";function K(o,n,s,t){let e=t||F.dirname(o);return{modules:!0,scriptPath:o,modulesRoot:e,compatibilityDate:"2026-02-14",compatibilityFlags:["nodejs_compat"],durableObjects:{XTRN_STATE:"XTRNState"},durableObjectsPersist:!0,port:n,bindings:s}}async function C(o,n,s,t){let e=K(o,n,s,t),i=new G(e);return await i.ready,i}function q(o){if(!N.existsSync(o))return{};let n=N.readFileSync(o,"utf-8"),s={};for(let t of n.split(`
+`)){let e=t.trim();if(!e||e.startsWith("#"))continue;let i=e.indexOf("=");if(i===-1)continue;s[e.slice(0,i)]=e.slice(i+1)}return s}async function W(o){return await(await o.dispatchFetch("http://localhost/details")).json()}var r={reset:"\x1B[0m",bold:"\x1B[1m",dim:"\x1B[2m",cyan:"\x1B[36m",green:"\x1B[32m",yellow:"\x1B[33m",magenta:"\x1B[35m",white:"\x1B[37m",red:"\x1B[31m",gray:"\x1B[90m"};function P(o){let n="./index.ts",s=1234;for(let t of o)if(t.startsWith("--port="))s=Number.parseInt(t.slice(t.indexOf("=")+1),10);else if(!t.startsWith("--"))n=t;return{entryPoint:_.resolve(n),port:s}}async function k(o){for(let s=0;s<5;s++){try{let t=await fetch(`http://localhost:${o}/details`);if(t.ok)return await t.json()}catch{}await new Promise((t)=>setTimeout(t,200))}throw Error("Failed to fetch /details after server ready")}function D(o,n){let s=`http://localhost:${o}`;if(console.log(""),console.log(`  ${r.bold}${r.cyan}${n.name}${r.reset} ${r.dim}${n.version}${r.reset}`),console.log(`  ${r.green}➜${r.reset} ${r.bold}${s}${r.reset}`),console.log(""),n.tools.length>0){console.log(`  ${r.bold}${r.white}Tools${r.reset}`);for(let t of n.tools){let e=t.tags.length>0?` ${r.dim}${t.tags.map((i)=>`[${i}]`).join(" ")}${r.reset}`:"";console.log(`    ${r.cyan}${t.name}${r.reset}${e} ${r.gray}— ${t.description}${r.reset}`)}console.log("")}if(n.config.length>0){console.log(`  ${r.bold}${r.white}Config${r.reset}`);for(let t of n.config)console.log(`    ${r.yellow}${t.key}${r.reset} ${r.dim}${t.type}${r.reset}`);console.log("")}if(n.oauth)console.log(`  ${r.bold}${r.white}OAuth${r.reset}  ${r.magenta}${n.oauth.provider}${r.reset}`),console.log(`    ${r.dim}authorize${r.reset}  ${n.oauth.authorization_url}`),console.log(`    ${r.dim}token${r.reset}      ${n.oauth.token_url}`),console.log(`    ${r.dim}callback${r.reset}   ${n.oauth.callback_url}`),console.log(`    ${r.dim}scopes${r.reset}     ${n.oauth.scopes.join(", ")}`),console.log("")}function nn(o,n){let s=_.join(o,"wrangler.toml"),t=V("npx",["wrangler","dev","--config",s,"--port",String(n)],{cwd:o,stdio:["ignore","pipe","pipe"]}),e="",i=new Promise((a,f)=>{let c=(l)=>{if(l.toString().includes("Ready on"))t.stdout?.off("data",c),a()},m=(l)=>{e+=l.toString()};t.stdout?.on("data",c),t.stderr?.on("data",m),t.on("error",(l)=>f(l)),t.on("close",(l)=>{if(l!==0&&l!==null)f(Error(e.trim()||`wrangler exited with code ${l}`))})});return i.then(()=>{e="",t.stderr?.on("data",(a)=>{let f=a.toString();if(f.includes("ERROR")||f.includes("Error")||f.includes("error:"))process.stderr.write(`${r.red}[xtrn dev]${r.reset} ${f}`)})}),{proc:t,ready:i}}async function I(o){let{entryPoint:n,port:s}=P(o),t=_.dirname(n);if(!R.existsSync(n))console.error(`${r.red}[xtrn dev]${r.reset} Entry point not found: ${n}`),process.exit(1);if(!R.existsSync(_.join(t,"package.json")))console.error(`${r.red}[xtrn dev]${r.reset} No package.json found in ${t}`),process.exit(1);let e=_.join(t,".dev.vars"),i=q(e),a=$();O(n,i,a);let f=null,c=()=>{if(console.log(`
+${r.dim}[xtrn dev] Shutting down...${r.reset}`),f)f.kill(),f=null;S(a),process.exit(0)};process.on("SIGINT",c),process.on("SIGTERM",c);try{console.log(`${r.dim}[xtrn dev] Starting...${r.reset}`);let m=nn(a,s);f=m.proc,f.on("error",(u)=>{console.error(`${r.red}[xtrn dev]${r.reset} Failed to start: ${u.message}`),S(a),process.exit(1)}),f.on("close",(u)=>{if(u!==0&&u!==null)console.error(`${r.red}[xtrn dev]${r.reset} Process exited with code ${u}`);S(a),process.exit(u??1)}),await m.ready;let l=await k(s);D(s,l),await new Promise(()=>{})}catch(m){if(f)f.kill();if(S(a),m instanceof Error)console.error(`${r.red}[xtrn dev]${r.reset} ${m.message}`);process.exit(1)}}import{mkdir as U,readFile as tn,writeFile as sn}from"node:fs/promises";import{dirname as on,join as h}from"node:path";import{fileURLToPath as en}from"node:url";async function H(o){let n=o[0],s=o[1]??"v1.0.0";if(!n)console.error("Error: <name> argument is required"),console.error("Usage: xtrn new <name> [version]"),process.exit(1);let t=s.startsWith("v")?s:`v${s}`,e=t.replace(/^v/,"");if(!/^\d+\.\d+\.\d+$/.test(e))console.error(`Error: Invalid version "${s}". Expected semver (e.g., v1.0.0)`),process.exit(1);let i=en(import.meta.url),a=on(i),f=h(a,"../../templates"),c=h(process.cwd(),n);try{await U(c,{recursive:!1})}catch(m){if(m instanceof Error&&"code"in m&&m.code==="EEXIST")console.error(`Error: Directory "${n}" already exists`),process.exit(1);throw m}try{let m=[{src:"index.ts.template",dst:"index.ts"},{src:"package.json.template",dst:"package.json"},{src:"tsconfig.json.template",dst:"tsconfig.json"}];for(let l of m){let u=h(f,l.src),j=h(c,l.dst),w=await tn(u,"utf-8");if(w=w.replace(/\{\{NAME\}\}/g,n),w=w.replace(/\{\{VERSION\}\}/g,t),w=w.replace(/\{\{VERSION_BARE\}\}/g,e),l.dst==="package.json"){let d=JSON.parse(w);d.dependencies["@xtrn/server"]="^1.0.0",d.devDependencies.xtrn="^1.0.0",d.scripts.submit="xtrn submit",w=`${JSON.stringify(d,null,"\t")}
+`}await sn(j,w,"utf-8")}console.log(`✓ Created ${n}/`),console.log(""),console.log("Next steps:"),console.log(`  cd ${n}`),console.log("  bun install"),console.log("  bun run dev")}catch(m){try{await U(c,{recursive:!0})}catch{}throw m}}import{spawn as rn}from"node:child_process";import*as y from"node:fs";import{cp as J,mkdir as z,readFile as an,readdir as fn,writeFile as mn}from"node:fs/promises";import*as T from"node:os";import*as v from"node:path";var p="xtrnai/servers",ln=new Set(["node_modules","bun.lock",".dev.vars","dist","_cf_entry.ts","wrangler.toml",".wrangler",".git",".github"]);function b(o,n,s){return new Promise((t)=>{let e=rn(o,n,{stdio:"pipe",cwd:s?.cwd}),i="",a="";e.stdout.on("data",(f)=>{i+=f.toString()}),e.stderr.on("data",(f)=>{a+=f.toString()}),e.on("close",(f)=>{t({stdout:i.trim(),stderr:a.trim(),code:f??1})}),e.on("error",()=>{t({stdout:"",stderr:`Failed to execute: ${o}`,code:1})})})}async function xn(){if((await b("gh",["--version"])).code!==0)console.error("[xtrn submit] GitHub CLI (gh) is not installed."),console.error(""),console.error("Install it:"),console.error("  macOS:   brew install gh"),console.error("  Linux:   https://github.com/cli/cli/blob/trunk/docs/install_linux.md"),console.error("  Windows: winget install --id GitHub.cli"),console.error(""),console.error("Then authenticate:"),console.error("  gh auth login"),process.exit(1);if((await b("gh",["auth","status"])).code!==0)console.error("[xtrn submit] GitHub CLI is not authenticated."),console.error(""),console.error("Run:"),console.error("  gh auth login"),process.exit(1)}function gn(o){if(!y.existsSync(v.join(o,"index.ts")))console.error("[xtrn submit] No index.ts found in current directory."),console.error("Run this command from your XTRN server project root."),process.exit(1);if(!y.existsSync(v.join(o,"package.json")))console.error("[xtrn submit] No package.json found in current directory."),console.error("Run this command from your XTRN server project root."),process.exit(1)}async function cn(o){let n=v.resolve(o,"index.ts"),s=$(),t=null;try{console.log("[xtrn submit] Bundling server...");let e=await A(n,s);console.log("[xtrn submit] Starting headless Miniflare..."),t=await C(e,0,{});let i=await W(t),a=i.name,f=i.version;if(typeof a!=="string"||!a)throw Error("Server /details missing 'name' field");if(typeof f!=="string"||!f)throw Error("Server /details missing 'version' field");return console.log(`[xtrn submit] Detected: ${a} v${f}`),{name:a,version:f}}finally{if(t)await t.dispose();S(s)}}async function B(o,n){await z(n,{recursive:!0});let s=await fn(o,{withFileTypes:!0});for(let t of s){if(ln.has(t.name))continue;let e=v.join(o,t.name),i=v.join(n,t.name);if(t.isDirectory())await B(e,i);else await J(e,i)}}function un(o){let n=JSON.parse(o),s=(t)=>{if(!t||typeof t!=="object")return;let e={};for(let[i,a]of Object.entries(t))if(typeof a==="string"&&(a.startsWith("file:")||a.startsWith("link:")||a.startsWith("workspace:")))e[i]="^1.0.0";else e[i]=a;return e};if(n.dependencies)n.dependencies=s(n.dependencies);if(n.devDependencies)n.devDependencies=s(n.devDependencies);return`${JSON.stringify(n,null,"\t")}
+`}async function vn(o,n){console.log("[xtrn submit] Preparing files..."),await B(o,n);let s=v.join(n,"package.json");if(y.existsSync(s)){let t=await an(s,"utf-8"),e=un(t);await mn(s,e,"utf-8"),console.log("[xtrn submit] Rewrote package.json (local deps → ^1.0.0)")}}async function yn(o,n,s){let t=y.mkdtempSync(v.join(T.tmpdir(),"xtrn-submit-")),e=v.join(t,"xtrn-servers");try{console.log(`[xtrn submit] Forking ${p}...`);let i=await b("gh",["repo","fork",p,"--clone=true","--default-branch-only"],{cwd:t});if(i.code!==0&&!i.stderr.includes("already exists"))throw Error(`Fork failed: ${i.stderr}`);if(!y.existsSync(e))throw Error(`Expected cloned repo at ${e}, not found. Output: ${i.stdout} ${i.stderr}`);let a=`submit/${o}/v${n}`;console.log(`[xtrn submit] Creating branch ${a}...`);let f=await b("git",["checkout","-b",a],{cwd:e});if(f.code!==0)throw Error(`Branch creation failed: ${f.stderr}`);let c=v.join(e,"servers",o,`v${n}`);await z(c,{recursive:!0}),await J(s,c,{recursive:!0}),console.log("[xtrn submit] Committing...");let m=await b("git",["add","."],{cwd:e});if(m.code!==0)throw Error(`git add failed: ${m.stderr}`);let l=await b("git",["commit","-m",`Add ${o} v${n}`],{cwd:e});if(l.code!==0)throw Error(`git commit failed: ${l.stderr}`);console.log("[xtrn submit] Pushing...");let u=await b("git",["push","origin",a],{cwd:e});if(u.code!==0)throw Error(`git push failed: ${u.stderr}`);console.log("[xtrn submit] Creating pull request...");let j=await b("gh",["pr","create","--repo",p,"--title",`Add ${o} v${n}`,"--body",`Automated submission via \`xtrn submit\` CLI.
+
+**Server:** ${o}
+**Version:** v${n}`],{cwd:e});if(j.code!==0)throw Error(`PR creation failed: ${j.stderr}`);return j.stdout}finally{y.rmSync(t,{recursive:!0,force:!0})}}async function L(o){let n=process.cwd();await xn(),gn(n);let{name:s,version:t}=await cn(n),e=y.mkdtempSync(v.join(T.tmpdir(),"xtrn-prepared-"));try{await vn(n,e);let i=await yn(s,t,e);console.log(""),console.log("✓ Pull request created!"),console.log(`  ${i}`),console.log(""),console.log("Your server will be reviewed and deployed automatically once merged.")}finally{y.rmSync(e,{recursive:!0,force:!0})}}var Q="1.0.0",E=`
+xtrn v${Q} — XTRN server development toolkit
+
+Usage:
+  xtrn new <name> <version>      Scaffold a new XTRN server project
+  xtrn dev [entry] [--port=N]    Start dev server with wrangler
+  xtrn submit                    Submit server to xtrn-servers registry
+  xtrn --help                    Show this help
+  xtrn --version                 Show version
+
+New arguments:
+  name                           Server name in slug format (e.g., my-server)
+  version                        Semver with v prefix (e.g., v1.0.0)
+
+Dev options:
+  entry                          Entry point file (default: ./index.ts)
+  --port=N                       Port to run on (default: 1234)
+
+Examples:
+  xtrn new my-server v1.0.0      Create a new server project
+  xtrn dev                       Start dev server with ./index.ts on port 1234
+  xtrn dev ./server.ts           Start dev server with custom entry
+  xtrn dev --port=3000           Start dev server on port 3000
+  xtrn submit                    Fork xtrn-servers and open PR
+`.trim();async function wn(){let o=process.argv.slice(2),n=o[0];if(!n||n==="--help"||n==="-h")console.log(E),process.exit(0);if(n==="--version"||n==="-v")console.log(`xtrn v${Q}`),process.exit(0);if(n==="new"){let s=o.slice(1);if(s.includes("--help")||s.includes("-h"))console.log(E),process.exit(0);await H(s);return}if(n==="dev"){let s=o.slice(1);if(s.includes("--help")||s.includes("-h"))console.log(E),process.exit(0);await I(s);return}if(n==="submit"){let s=o.slice(1);if(s.includes("--help")||s.includes("-h"))console.log(E),process.exit(0);await L(s);return}console.error(`Unknown command: ${n}`),console.error('Run "xtrn --help" for usage.'),process.exit(1)}wn().catch((o)=>{console.error("[xtrn] Fatal:",o),process.exit(1)});

package/package.json

@@ -0,0 +1,34 @@
+{
+	"name": "@xtrn/cli",
+	"version": "1.0.0",
+	"type": "module",
+	"bin": {
+		"xtrn": "./dist/cli.js"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"files": [
+		"dist",
+		"templates"
+	],
+	"scripts": {
+		"build": "bun run build:clean && bun run build:bun && bun run build:types",
+		"build:clean": "rm -rf dist",
+		"build:bun": "bun build src/cli.ts --outdir dist --target node --format esm --minify --external miniflare",
+		"build:types": "tsc -p tsconfig.build.json",
+		"build:watch": "bun run build:types --watch",
+		"prepublishOnly": "bun run build",
+		"test": "bun test"
+	},
+	"devDependencies": {
+		"@biomejs/biome": "2.3.4",
+		"@types/bun": "latest",
+		"@xtrn/server": "workspace:*",
+		"typescript": "^5.0.0",
+		"zod": "^4.3.6"
+	},
+	"dependencies": {
+		"miniflare": "^3.20250115.0"
+	}
+}

package/templates/README.md.template

@@ -0,0 +1,289 @@
+# {{NAME}}
+
+An XTRN server. Built with [@xtrn/server](https://www.npmjs.com/package/@xtrn/server) on Hono + Cloudflare Workers with Zod v4 validation, OAuth 2.0 integration, and lifecycle management via Durable Objects.
+
+## Getting Started
+
+```bash
+# Install dependencies
+bun install
+
+# Start dev server (port 1234)
+xtrn dev
+
+# Custom port
+xtrn dev --port=3000
+```
+
+Then open `http://localhost:1234/details`.
+
+## Server API
+
+Import everything from `@xtrn/server/server`:
+
+```typescript
+import { XTRNServer, defineConfig, ToolTag } from "@xtrn/server/server";
+import { z } from "zod";
+```
+
+### OPEN Server
+
+No configuration or authentication required.
+
+```typescript
+import { XTRNServer, defineConfig } from "@xtrn/server/server";
+import { z } from "zod";
+
+const server = new XTRNServer({
+  name: "hello-world",
+  version: "1.0.0",
+  config: defineConfig({}),
+});
+
+server.registerTool({
+  name: "greet",
+  description: "Returns a friendly greeting",
+  schema: z.object({
+    name: z.string().describe("Name of the person to greet"),
+  }),
+  handler: (ctx) => {
+    return ctx.res.text(`Hello, ${ctx.req.name}!`);
+  },
+});
+
+export default server;
+```
+
+### Config-Only Server
+
+Requires users to provide configuration values (API keys, preferences).
+
+```typescript
+import { XTRNServer, defineConfig } from "@xtrn/server/server";
+import { z } from "zod";
+
+const server = new XTRNServer({
+  name: "config-server",
+  version: "1.0.0",
+  config: defineConfig({
+    userConfig: [
+      { key: "apiKey", type: "string" },
+      { key: "maxRetries", type: "number" },
+      { key: "debugMode", type: "boolean" },
+    ],
+  }),
+});
+
+server.registerTool({
+  name: "fetch-data",
+  description: "Fetch data using API key",
+  schema: z.object({ id: z.string() }),
+  handler: (ctx) => {
+    // ctx.config.apiKey — string
+    // ctx.config.maxRetries — number
+    // ctx.config.debugMode — boolean
+    return ctx.res.json({ id: ctx.req.id, key: ctx.config.apiKey });
+  },
+});
+
+export default server;
+```
+
+### OAuth-Only Server
+
+Requires users to complete an OAuth flow. The platform provides a fresh access token directly.
+
+```typescript
+import { XTRNServer, defineConfig } from "@xtrn/server/server";
+import { z } from "zod";
+
+const server = new XTRNServer({
+  name: "github-server",
+  version: "1.0.0",
+  config: defineConfig({
+    oauthConfig: {
+      provider: "github",
+      authorization_url: "https://github.com/login/oauth/authorize",
+      token_url: "https://github.com/login/oauth/access_token",
+      scopes: ["repo", "user"],
+    },
+  }),
+});
+
+server.registerTool({
+  name: "get-repos",
+  description: "List user repositories",
+  schema: z.object({
+    sort: z.enum(["created", "updated", "pushed"]).default("updated"),
+  }),
+  handler: async (ctx) => {
+    // ctx.accessToken — ready-to-use access token string
+    const resp = await fetch("https://api.github.com/user/repos?sort=" + ctx.req.sort, {
+      headers: { Authorization: `Bearer ${ctx.accessToken}` },
+    });
+    return ctx.res.json(await resp.json());
+  },
+});
+
+export default server;
+```
+
+### Config + OAuth Server
+
+Combines both user configuration and OAuth authentication.
+
+```typescript
+import { XTRNServer, defineConfig, ToolTag } from "@xtrn/server/server";
+import { z } from "zod";
+
+const server = new XTRNServer({
+  name: "calendar-server",
+  version: "1.0.0",
+  config: defineConfig({
+    userConfig: [
+      { key: "timezone", type: "string" },
+    ],
+    oauthConfig: {
+      provider: "google-calendar",
+      authorization_url: "https://accounts.google.com/o/oauth2/v2/auth",
+      token_url: "https://oauth2.googleapis.com/token",
+      scopes: ["https://www.googleapis.com/auth/calendar"],
+    },
+  }),
+});
+
+server.registerTool({
+  name: "list-events",
+  description: "List calendar events",
+  tags: [ToolTag.Mutation],
+  schema: z.object({
+    maxResults: z.number().default(10),
+  }),
+  handler: async (ctx) => {
+    // ctx.config.timezone — string (from X-XTRN-Config header)
+    // ctx.accessToken — string (from X-XTRN-Access-Token header)
+    const resp = await fetch(
+      "https://www.googleapis.com/calendar/v3/calendars/primary/events",
+      { headers: { Authorization: `Bearer ${ctx.accessToken}` } },
+    );
+    return ctx.res.json(await resp.json());
+  },
+});
+
+export default server;
+```
+
+## OAuth Configuration
+
+```typescript
+type OAuthConfig = {
+  provider: string;
+  authorization_url: string;
+  token_url: string;
+  scopes: string[];
+};
+```
+
+OAuth secrets are managed via environment variables (not in code):
+
+| Variable | Description |
+|----------|-------------|
+| `OAUTH_CLIENT_ID` | OAuth application client ID |
+| `OAUTH_CLIENT_SECRET` | OAuth application client secret |
+| `OAUTH_CALLBACK_URL` | OAuth redirect/callback URL |
+
+Set these in a `.dev.vars` file for local development:
+
+```env
+OAUTH_CLIENT_ID=your-client-id
+OAUTH_CLIENT_SECRET=your-client-secret
+OAUTH_CALLBACK_URL=http://localhost:1234/auth/callback
+```
+
+## Context Object
+
+| Property | Type | Availability | Description |
+|----------|------|--------------|-------------|
+| `ctx.req` | `T` (inferred from schema) | Always | Validated tool parameters |
+| `ctx.config` | `Object` (inferred from userConfig) | Always (`{}` if no userConfig) | Validated user configuration |
+| `ctx.accessToken` | `string` | OAuth servers only | Access token from platform |
+| `ctx.res` | `XTRNResponse` | Always | Response helper methods |
+
+## Tool Tags
+
+```typescript
+import { ToolTag } from "@xtrn/server/server";
+
+server.registerTool({
+  name: "delete-item",
+  description: "Permanently delete an item",
+  tags: [ToolTag.Mutation, ToolTag.Destructive],
+  schema: z.object({ id: z.string() }),
+  handler: (ctx) => {
+    return ctx.res.json({ deleted: true });
+  },
+});
+```
+
+| Tag | Meaning |
+|-----|---------|
+| `ToolTag.Mutation` | Tool modifies data |
+| `ToolTag.Destructive` | Tool performs an irreversible action |
+
+## Response Helpers
+
+```typescript
+ctx.res.json({ data: "value" })        // 200 JSON
+ctx.res.text("plain text")             // 200 text
+ctx.res.badRequestArgs("invalid x")    // 400 Bad Request
+ctx.res.unauthorized()                 // 401 Unauthorized
+ctx.res.error("something failed")      // 500 Internal Server Error
+```
+
+## Built-in Routes
+
+| Route | Method | Description |
+|-------|--------|-------------|
+| `/details` | GET | Server metadata, tool definitions, JSON schemas |
+| `/tools/{name}` | POST | Execute a tool |
+| `/wind-down` | POST | Stop accepting new requests (graceful shutdown) |
+| `/active-requests` | GET | Current in-flight request count and state |
+| `/reset` | POST | Reset server state (dev only) |
+
+## Calling Tools
+
+Tools are called via POST to `/tools/{name}`. Configuration and tokens go in headers; tool parameters go in the body.
+
+| Header | Format | When Required |
+|--------|--------|---------------|
+| `X-XTRN-Config` | `base64(JSON.stringify({...}))` | Server has `userConfig` |
+| `X-XTRN-Access-Token` | `base64(access_token)` | Server has `oauthConfig` |
+
+```bash
+# OPEN server
+curl -X POST http://localhost:1234/tools/greet \
+  -H "Content-Type: application/json" \
+  -d '{"name": "Alice"}'
+
+# With user config
+curl -X POST http://localhost:1234/tools/fetch-data \
+  -H "Content-Type: application/json" \
+  -H "X-XTRN-Config: $(echo '{"apiKey":"secret-123"}' | base64)" \
+  -d '{"id": "abc-123"}'
+
+# With OAuth
+curl -X POST http://localhost:1234/tools/get-repos \
+  -H "Content-Type: application/json" \
+  -H "X-XTRN-Access-Token: $(echo 'gho_xxxxxxxxxxxx' | base64)" \
+  -d '{"sort": "updated"}'
+```
+
+## Submitting Your Server
+
+When your server is ready, submit it to the registry:
+
+```bash
+xtrn submit
+```
+
+This forks the [xtrn-servers](https://github.com/AbhinavPalacharla/xtrn-servers) repo and opens a PR with your server code. Requires [GitHub CLI](https://cli.github.com/) (`gh`).

package/templates/dev-vars.example.template

@@ -0,0 +1,4 @@
+# OAuth credentials (uncomment and fill in for OAuth servers)
+# OAUTH_CLIENT_ID=your-client-id
+# OAUTH_CLIENT_SECRET=your-client-secret
+# OAUTH_CALLBACK_URL=http://localhost:1234/auth/callback

package/templates/index.ts.template

@@ -0,0 +1,22 @@
+import { XTRNServer, defineConfig } from "@xtrn/server";
+import { z } from "zod";
+
+const server = new XTRNServer({
+	name: "{{NAME}}",
+	version: "{{VERSION}}",
+	config: defineConfig({}),
+});
+
+// Register your tools here
+// server.registerTool({
+// 	name: "example",
+// 	description: "An example tool",
+// 	schema: z.object({
+// 		input: z.string().describe("Example input"),
+// 	}),
+// 	handler: (ctx) => {
+// 		return ctx.res.json({ result: ctx.req.input });
+// 	},
+// });
+
+export default server;

package/templates/package.json.template

@@ -0,0 +1,20 @@
+{
+	"name": "{{NAME}}",
+	"version": "{{VERSION_BARE}}",
+	"module": "index.ts",
+	"type": "module",
+	"private": true,
+	"scripts": {
+		"dev": "xtrn dev"
+	},
+	"dependencies": {
+		"@xtrn/server": "^0.1.0",
+		"zod": "^4.0.0"
+	},
+	"devDependencies": {
+		"@types/bun": "latest"
+	},
+	"peerDependencies": {
+		"typescript": "^5"
+	}
+}

package/templates/tsconfig.json.template

@@ -0,0 +1,22 @@
+{
+	"compilerOptions": {
+		"lib": ["ESNext"],
+		"target": "ESNext",
+		"module": "Preserve",
+		"moduleDetection": "force",
+		"jsx": "react-jsx",
+		"allowJs": true,
+		"moduleResolution": "bundler",
+		"allowImportingTsExtensions": true,
+		"verbatimModuleSyntax": true,
+		"noEmit": true,
+		"strict": true,
+		"skipLibCheck": true,
+		"noFallthroughCasesInSwitch": true,
+		"noUncheckedIndexedAccess": true,
+		"noImplicitOverride": true,
+		"noUnusedLocals": false,
+		"noUnusedParameters": false,
+		"noPropertyAccessFromIndexSignature": false
+	}
+}