Skip to content

The open-source agent harness - the runtime layer that turns an LLM into a working agent.

Feat: add cross platform support (#374)

SidakSethi-Singh5d721387d87a
diff --git a/.changeset/windows-build-scripts.md b/.changeset/windows-build-scripts.md
new file mode 100644
index 000000000..4a794407d
--- /dev/null
+++ b/.changeset/windows-build-scripts.md
@@ -0,0 +1,7 @@
+---
+'@truefoundry/trueforge-core': patch
+'@truefoundry/trueforge-ui': patch
+'@truefoundry/trueforge': patch
+---
+
+Keep `npx @truefoundry/trueforge` working on native Windows: import Kysely migrations with `pathToFileURL`, and keep sandbox guest paths POSIX. Source development stays Unix/WSL; CI also runs unit and SQLite store tests on Windows.
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 7e0916cbe..c29f34909 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -134,7 +134,7 @@ jobs:
typecheck-and-build:
name: Format, Typecheck, Lint and Build
runs-on: ubuntu-latest
- timeout-minutes: 20
+ timeout-minutes: 30
steps:
- name: Check out repository code
@@ -172,13 +172,40 @@ jobs:
- name: Build
run: pnpm build
+ windows-test:
+ name: Test (Windows)
+ runs-on: windows-latest
+ timeout-minutes: 30
+
+ steps:
+ - name: Check out repository code
+ uses: actions/checkout@v7
+
+ - name: Setup pnpm
+ uses: pnpm/action-setup@v6
+
+ - name: Setup Node.js
+ uses: actions/setup-node@v7
+ with:
+ node-version: '24'
+ cache: 'pnpm'
+
+ - name: Install dependencies
+ run: pnpm install --frozen-lockfile
+
+ - name: Test
+ run: pnpm test
+
+ - name: SQLite store tests
+ run: pnpm test:store:sqlite
+
# Path-gated tests only — format/lint are covered by the global job above.
package-checks:
name: Package (${{ matrix.package }})
needs: detect-changes
if: needs.detect-changes.outputs.packages != '[]'
runs-on: ubuntu-latest
- timeout-minutes: 25
+ timeout-minutes: 30
strategy:
fail-fast: false
matrix:
@@ -287,6 +314,7 @@ jobs:
- detect-changes
- migration-order
- typecheck-and-build
+ - windows-test
- package-checks
- chart-checks
- store-tests
@@ -298,15 +326,17 @@ jobs:
DETECT_CHANGES: ${{ needs.detect-changes.result }}
MIGRATION_ORDER: ${{ needs.migration-order.result }}
TYPECHECK_AND_BUILD: ${{ needs.typecheck-and-build.result }}
+ WINDOWS_TEST: ${{ needs.windows-test.result }}
PACKAGE_CHECKS: ${{ needs.package-checks.result }}
CHART_CHECKS: ${{ needs.chart-checks.result }}
STORE_TESTS: ${{ needs.store-tests.result }}
run: |
ok() { [ "$1" = success ] || [ "$1" = skipped ]; }
- echo "detect-changes=$DETECT_CHANGES migration-order=$MIGRATION_ORDER typecheck-and-build=$TYPECHECK_AND_BUILD package-checks=$PACKAGE_CHECKS chart-checks=$CHART_CHECKS store-tests=$STORE_TESTS"
+ echo "detect-changes=$DETECT_CHANGES migration-order=$MIGRATION_ORDER typecheck-and-build=$TYPECHECK_AND_BUILD windows-test=$WINDOWS_TEST package-checks=$PACKAGE_CHECKS chart-checks=$CHART_CHECKS store-tests=$STORE_TESTS"
[ "$DETECT_CHANGES" = success ] || exit 1
[ "$MIGRATION_ORDER" = success ] || exit 1
[ "$TYPECHECK_AND_BUILD" = success ] || exit 1
+ [ "$WINDOWS_TEST" = success ] || exit 1
ok "$PACKAGE_CHECKS" || exit 1
ok "$CHART_CHECKS" || exit 1
ok "$STORE_TESTS" || exit 1
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index 71f981105..fafe91803 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -6,7 +6,7 @@
# On every push to main, changesets/action/select-mode chooses:
# - pending `.changeset/*.md` → version job opens/updates the Version Packages PR
# (install only; that PR is gated by CI.yml)
-# - none pending + unpublished versions → pack (build/test) then publish
+# - none pending + unpublished versions → pack (build/test) + Windows npx smoke, then publish
# Merge the Version Packages PR to publish. There is no separate publish Action
# and no `v*` tag trigger.
#
@@ -136,9 +136,36 @@ jobs:
with:
publish-plan-artifact-id: ${{ needs.select-mode.outputs.publish-plan-artifact-id }}
+ windows-npx-smoke:
+ name: Windows npx smoke
+ if: needs.select-mode.outputs.mode == 'publish'
+ needs: select-mode
+ runs-on: windows-latest
+ timeout-minutes: 30
+ permissions:
+ contents: read
+ steps:
+ - name: Check out repo
+ uses: actions/checkout@v7
+ with:
+ persist-credentials: false
+
+ - uses: pnpm/action-setup@v6
+
+ - name: Set up Node.js
+ uses: actions/setup-node@v7
+ with:
+ node-version: 24
+ cache: pnpm
+
+ - run: pnpm install --frozen-lockfile
+
+ - name: Pack and boot published CLI
+ run: pnpm smoke:npx
+
publish:
name: Publish packages
- needs: pack
+ needs: [pack, windows-npx-smoke]
runs-on: ubuntu-latest
timeout-minutes: 20
outputs:
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 85322a1fc..45727e557 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -55,6 +55,8 @@ Open a feature request in the issue tracker, or upvote an existing request that
## Prerequisites
+Source development (`pnpm install`, `pnpm dev`, `pnpm standalone:dev`, `pnpm build`) is supported on **macOS, Linux, and Windows via WSL2**. Native Windows (PowerShell / cmd) is not a supported at this time.
+
- **Node.js 22.14+** (see [`.nvmrc`](.nvmrc); pnpm 11.16 needs 22.13+, and `better-sqlite3` v13 needs Node-API 10)
- **pnpm** (version pinned via `packageManager` in [`package.json`](package.json); `corepack enable` handles it)
- **Docker** - only needed for Postgres/Redis dev infra, the smoke test, and local SDK generation (maintainers). Fork contributors do not generate the SDK.
@@ -181,6 +183,7 @@ Workspace tasks go through `package.json` scripts - if a repeatable workflow is
| `pnpm test` / `pnpm typecheck` | Workspace checks |
| `pnpm lint` / `pnpm format` | ESLint (with fixes) / Prettier |
| `pnpm smoke` / `pnpm smoke:down` | Full Docker Compose stack + health check |
+| `pnpm smoke:npx` | Pack the published CLI and boot it like `npx` |
| `pnpm chart:lint` / `pnpm chart:template` | Validate the Helm chart |
| `pnpm clean` / `pnpm clean:all` | Remove build outputs (+ `node_modules` for `:all`) |
diff --git a/RELEASING.md b/RELEASING.md
index 596b17280..d35fb1ad0 100644
--- a/RELEASING.md
+++ b/RELEASING.md
@@ -53,8 +53,9 @@ No `v*` tag publish. [`release.yml`](.github/workflows/release.yml) does both ve
`@truefoundry/trueforge-sdk` via `pnpm changeset:sdk-regen`.
2. Merge to `main`. Pending changesets → **Version Packages** PR
(`pnpm run version`). Review and merge.
-3. With no pending changesets, **pack** (build/test) then **publish** via npm
- trusted publishing (OIDC; no `NPM_TOKEN`).
+3. With no pending changesets, **pack** (build/test) and **Windows npx smoke**
+ run in parallel, then **publish** via npm trusted publishing (OIDC; no
+ `NPM_TOKEN`).
4. If `@truefoundry/trueforge` was published, **Release** calls **Build and
prepare chart release** as a reusable workflow on the same commit (so a
newer `main` push cannot change the Dockerfile / shortSha). GitHub's
diff --git a/docs/quickstart.mdx b/docs/quickstart.mdx
index bd80f898a..f280af296 100644
--- a/docs/quickstart.mdx
+++ b/docs/quickstart.mdx
@@ -10,7 +10,7 @@ TrueForge runs in [two modes](/introduction#two-ways-to-run-it): **local mode**
<Tabs>
<Tab title="npx (Local)">
- Requires [Node.js](https://nodejs.org) 22.14 or newer. One command, no other infrastructure — the UI and backend run locally, and data is stored in a local SQLite file:
+ Requires [Node.js](https://nodejs.org) 22.14 or newer on macOS, Linux, or Windows. One command, no other infrastructure — the UI and backend run locally, and data is stored in a local SQLite file:
```bash
npx @truefoundry/trueforge@latest
diff --git a/package.json b/package.json
index fbbf93b24..75d5cac3d 100644
--- a/package.json
+++ b/package.json
@@ -16,9 +16,9 @@
"clean:all": "node scripts/clean.mjs --dependencies",
"clean": "node scripts/clean.mjs",
"dev:infra": "docker compose -f docker-compose.dev.yml up",
- "dev:no-watch": "STANDALONE=false NODE_ENV=development pnpm --parallel --filter @truefoundry/trueforge --filter frontend dev:no-watch",
- "dev:server:ui": "pnpm --filter frontend build && pnpm --filter @truefoundry/trueforge build:frontend-assets && STANDALONE=false NODE_ENV=development pnpm --parallel --filter @truefoundry/trueforge-core --filter @truefoundry/trueforge dev",
- "dev": "STANDALONE=false NODE_ENV=development pnpm --parallel --filter @truefoundry/trueforge-core --filter @truefoundry/trueforge --filter frontend dev",
+ "dev:no-watch": "cross-env STANDALONE=false NODE_ENV=development pnpm --parallel --filter @truefoundry/trueforge --filter frontend dev:no-watch",
+ "dev:server:ui": "pnpm --filter frontend build && pnpm --filter @truefoundry/trueforge build:frontend-assets && cross-env STANDALONE=false NODE_ENV=development pnpm --parallel --filter @truefoundry/trueforge-core --filter @truefoundry/trueforge dev",
+ "dev": "cross-env STANDALONE=false NODE_ENV=development pnpm --parallel --filter @truefoundry/trueforge-core --filter @truefoundry/trueforge --filter frontend dev",
"format:check": "prettier --check \"**/*.{js,jsx,ts,tsx,json,md}\" --cache --cache-location .prettiercache --cache-strategy content --error-on-unmatched-pattern --config .prettierrc",
"format:fix": "prettier --write \"**/*.{js,jsx,ts,tsx,json,md}\" --cache --cache-location .prettiercache --cache-strategy content --config .prettierrc",
"format": "prettier --write . --cache --cache-location .prettiercache --cache-strategy content --config .prettierrc",
@@ -31,12 +31,13 @@
"sdk:generate": "bash scripts/generate-sdk.sh",
"sdk:types": "pnpm --filter @truefoundry/trueforge-sdk exec tsc --project ./tsconfig.cjs.json --emitDeclarationOnly --noCheck",
"smoke:down": "docker compose down",
+ "smoke:npx": "pnpm build && node scripts/npx-smoke.mjs",
"smoke": "docker compose up --build --wait && node -e \"Promise.all([fetch('http://127.0.0.1:8791/healthz'), fetch('http://127.0.0.1:8791/')]).then(async ([health, ui]) => { if (!health.ok) throw new Error('healthz returned ' + health.status); const html = await ui.text(); if (!ui.ok || !html.includes('id=\\\"root\\\"')) throw new Error('UI did not return its app shell'); console.log('healthz and UI OK'); })\"",
- "standalone:dev:no-watch": "STANDALONE=true NODE_ENV=development pnpm --parallel --filter @truefoundry/trueforge --filter frontend dev:no-watch",
- "standalone:dev": "STANDALONE=true NODE_ENV=development pnpm --parallel --filter @truefoundry/trueforge-core --filter @truefoundry/trueforge --filter frontend dev",
- "standalone:start": "STANDALONE=true NODE_ENV=production pnpm --filter @truefoundry/trueforge start",
- "start": "STANDALONE=false NODE_ENV=production pnpm --filter @truefoundry/trueforge start",
- "start:controller": "STANDALONE=false NODE_ENV=production pnpm --filter @truefoundry/trueforge start:controller",
+ "standalone:dev:no-watch": "cross-env STANDALONE=true NODE_ENV=development pnpm --parallel --filter @truefoundry/trueforge --filter frontend dev:no-watch",
+ "standalone:dev": "cross-env STANDALONE=true NODE_ENV=development pnpm --parallel --filter @truefoundry/trueforge-core --filter @truefoundry/trueforge --filter frontend dev",
+ "standalone:start": "cross-env STANDALONE=true NODE_ENV=production pnpm --filter @truefoundry/trueforge start",
+ "start": "cross-env STANDALONE=false NODE_ENV=production pnpm --filter @truefoundry/trueforge start",
+ "start:controller": "cross-env STANDALONE=false NODE_ENV=production pnpm --filter @truefoundry/trueforge start:controller",
"push-sandbox-image-to-daytona": "pnpm --filter @truefoundry/trueforge push-sandbox-image-to-daytona",
"test:frontend": "pnpm --filter frontend test",
"test:chart-version": "bash tests/scripts/resolve-chart-version.test.sh",
@@ -57,6 +58,7 @@
"@changesets/cli": "^3.0.1",
"@eslint-react/eslint-plugin": "^5.18.6",
"@eslint/js": "^10.0.1",
+ "cross-env": "^10.1.0",
"eslint": "^10.9.1",
"eslint-plugin-react-hooks": "^7.1.1",
"husky": "^9.1.7",
diff --git a/packages/frontend/package.json b/packages/frontend/package.json
index c778f99b8..1fbeb12f2 100644
--- a/packages/frontend/package.json
+++ b/packages/frontend/package.json
@@ -20,7 +20,7 @@
"pretypecheck": "pnpm run ui:build",
"typecheck": "tsc --noEmit",
"pretest": "pnpm run ui:build",
- "test": "NODE_OPTIONS='--conditions=trueforge-dev' tsx --test \"tests/**/*.test.ts\""
+ "test": "cross-env NODE_OPTIONS=--conditions=trueforge-dev tsx --test \"tests/**/*.test.ts\""
},
"dependencies": {
"@assistant-ui/core": "0.2.22",
@@ -38,6 +38,7 @@
"@types/react": "^19.2.17",
"@types/react-dom": "^19.2.2",
"@vitejs/plugin-react": "^4.7.0",
+ "cross-env": "^10.1.0",
"tailwindcss": "4.3.3",
"tsx": "^4.16.2",
"typescript": "^5.9.3",
diff --git a/packages/frontend/src/index.css b/packages/frontend/src/index.css
index 1526df9f8..4eaaebd32 100644
--- a/packages/frontend/src/index.css
+++ b/packages/frontend/src/index.css
@@ -25,12 +25,7 @@ body {
/* Primary CTA fill: gradient isn't a valid Tailwind color token, so paint it as background-image. */
.harness-primary-gradient button.bg-primary-button-bg,
.harness-primary-gradient .auth-screen-button {
- background-image: radial-gradient(
- 289.46% 144.73% at 8.33% 7.41%,
- #b27aff 0%,
- #155dfc 58.99%,
- #4f39f6 100%
- );
+ background-image: radial-gradient(289.46% 144.73% at 8.33% 7.41%, #b27aff 0%, #155dfc 58.99%, #4f39f6 100%);
}
.harness-primary-gradient[data-theme='light'] aside.bg-sidebar-bg button.bg-primary-button-bg {
diff --git a/packages/trueforge-core/src/core/sandbox/Sandbox.ts b/packages/trueforge-core/src/core/sandbox/Sandbox.ts
index 2a8b0a774..41740b8d3 100644
--- a/packages/trueforge-core/src/core/sandbox/Sandbox.ts
+++ b/packages/trueforge-core/src/core/sandbox/Sandbox.ts
@@ -21,7 +21,7 @@ import { ensureExecSuccess, shellEscape, type SandboxProvider } from './provider
import { SandboxNotAvailableError, validateNoPathTraversal } from './SandboxErrors';
import { formatSandboxId, rawSandboxId } from './sandboxRef';
// Import submodules, not the ./skills barrel, to avoid a cycle (the mounters import from Sandbox).
-import { dirname, join, relative } from 'node:path';
+import { dirname, join, relative } from 'node:path/posix';
import type { ISkillMounter } from './skills/ISkillMounter';
/** Layout derived from install remotePath (always `…/mcp_client.py`). */
diff --git a/packages/trueforge-ui/package.json b/packages/trueforge-ui/package.json
index 39ef9c0ed..23fdaf84c 100644
--- a/packages/trueforge-ui/package.json
+++ b/packages/trueforge-ui/package.json
@@ -58,7 +58,7 @@
],
"scripts": {
"prebuild": "pnpm -w run sdk:types",
- "build": "rm -rf dist && tailwindcss --input src/build-styles.css --output dist/styles.css --minify && tsup",
+ "build": "node ../../scripts/rm-path.mjs dist && tailwindcss --input src/build-styles.css --output dist/styles.css --minify && tsup",
"dev:watch": "pnpm run \"/^(dev:watch:js|dev:watch:css)$/\"",
"dev:watch:js": "tsup --watch",
"dev:watch:css": "tailwindcss --input src/build-styles.css --output dist/styles.css --watch",
diff --git a/packages/trueforge-ui/test/packageExports.smoke.mjs b/packages/trueforge-ui/test/packageExports.smoke.mjs
index f23bc4c37..3991d12d4 100644
--- a/packages/trueforge-ui/test/packageExports.smoke.mjs
+++ b/packages/trueforge-ui/test/packageExports.smoke.mjs
@@ -2,9 +2,11 @@ import assert from 'node:assert/strict';
import { execFileSync } from 'node:child_process';
import { mkdir, mkdtemp, readdir, rm, symlink, writeFile } from 'node:fs/promises';
import path from 'node:path';
-import { execPath } from 'node:process';
+import { execPath, platform } from 'node:process';
import { fileURLToPath, URL } from 'node:url';
+const win32Shell = platform === 'win32' ? { shell: true } : {};
+
// Create a temporary directory to test the package exports
const packageRoot = fileURLToPath(new URL('..', import.meta.url));
const tempDir = await mkdtemp(path.join(packageRoot, 'test', '.package-smoke-'));
@@ -15,12 +17,14 @@ try {
execFileSync('pnpm', ['--filter', '@truefoundry/trueforge-sdk', 'build'], {
cwd: path.resolve(packageRoot, '../..'),
stdio: 'inherit',
+ ...win32Shell,
});
// create a tarball of the package
execFileSync('pnpm', ['pack', '--pack-destination', tempDir], {
cwd: packageRoot,
stdio: 'inherit',
+ ...win32Shell,
});
// confirm that the tarball was created
@@ -35,10 +39,9 @@ try {
execFileSync('tar', ['-xzf', path.join(tempDir, tarballName), '--strip-components=1', '-C', packageDir]);
// Plugin adapter depends on @truefoundry/trueforge-sdk (workspace:* in monorepo) — expose it to the smoke consumer.
- await symlink(
- path.resolve(packageRoot, '../trueforge-sdk'),
- path.join(tempDir, 'node_modules', '@truefoundry', 'trueforge-sdk'),
- );
+ const sdkSource = path.resolve(packageRoot, '../trueforge-sdk');
+ const sdkLink = path.join(tempDir, 'node_modules', '@truefoundry', 'trueforge-sdk');
+ await symlink(sdkSource, sdkLink, platform === 'win32' ? 'junction' : undefined);
// create a package.json for the consumer
await writeFile(
diff --git a/packages/trueforge/package.json b/packages/trueforge/package.json
index 011b8115c..1c56d5fc8 100644
--- a/packages/trueforge/package.json
+++ b/packages/trueforge/package.json
@@ -32,19 +32,19 @@
"build:gen:local-sandbox": "node scripts/generate-local-sandbox-scripts.mjs",
"build:gen:watch": "node --watch-path=catalog/model-catalog.yaml --watch-path=catalog/mcp-catalog.yaml --watch-path=catalog/skill-catalog.yaml --watch-path=catalog/sandbox-catalog.yaml --watch-path=src/sandbox/local/scripts scripts/generate-dev.mjs",
"build:gen": "pnpm run build:gen:local-sandbox && node scripts/generate-catalog.mjs",
- "build:clean": "rm -rf dist",
- "build": "pnpm run build:gen && tsc --noEmit && pnpm run build:clean && tsup && chmod +x dist/cli.js && pnpm run build:frontend-assets",
- "dev:serve": "NODE_OPTIONS='--conditions=trueforge-dev' NODE_ENV=development tsx watch --env-file=.env src/main.ts",
+ "build:clean": "node ../../scripts/rm-path.mjs dist",
+ "build": "pnpm run build:gen && tsc --noEmit && pnpm run build:clean && tsup && node ../../scripts/chmod-path.mjs dist/cli.js 755 && pnpm run build:frontend-assets",
+ "dev:serve": "cross-env NODE_OPTIONS=--conditions=trueforge-dev NODE_ENV=development tsx watch --env-file=.env src/main.ts",
"dev": "pnpm run \"/^(build:gen:watch|dev:serve|dev:controller)$/\"",
"dev:no-watch": "pnpm run \"/^(dev:serve:no-watch|dev:controller:no-watch)$/\"",
- "dev:serve:no-watch": "NODE_OPTIONS='--conditions=trueforge-dev' NODE_ENV=development tsx --env-file=.env src/main.ts",
- "dev:controller": "NODE_OPTIONS='--conditions=trueforge-dev' NODE_ENV=development tsx watch --env-file=.env src/controller-main.ts",
- "dev:controller:no-watch": "NODE_OPTIONS='--conditions=trueforge-dev' NODE_ENV=development tsx --env-file=.env src/controller-main.ts",
- "start": "NODE_ENV=production node --env-file=.env dist/main.js",
- "start:controller": "NODE_ENV=production node --env-file=.env dist/controller-main.js",
+ "dev:serve:no-watch": "cross-env NODE_OPTIONS=--conditions=trueforge-dev NODE_ENV=development tsx --env-file=.env src/main.ts",
+ "dev:controller": "cross-env NODE_OPTIONS=--conditions=trueforge-dev NODE_ENV=development tsx watch --env-file=.env src/controller-main.ts",
+ "dev:controller:no-watch": "cross-env NODE_OPTIONS=--conditions=trueforge-dev NODE_ENV=development tsx --env-file=.env src/controller-main.ts",
+ "start": "cross-env NODE_ENV=production node --env-file=.env dist/main.js",
+ "start:controller": "cross-env NODE_ENV=production node --env-file=.env dist/controller-main.js",
"push-sandbox-image-to-daytona": "node scripts/push-sandbox-image-to-daytona.mjs",
- "migrate": "NODE_OPTIONS='--conditions=trueforge-dev' STANDALONE=false tsx --env-file=.env src/db/postgres/migrate-cli.ts",
- "openapi:write": "pnpm run build:gen && NODE_OPTIONS='--conditions=trueforge-dev' tsx --env-file=.env.test scripts/write-openapi.ts",
+ "migrate": "cross-env NODE_OPTIONS=--conditions=trueforge-dev STANDALONE=false tsx --env-file=.env src/db/postgres/migrate-cli.ts",
+ "openapi:write": "pnpm run build:gen && cross-env NODE_OPTIONS=--conditions=trueforge-dev tsx --env-file=.env.test scripts/write-openapi.ts",
"pack:dry": "pnpm pack --dry-run",
"predev:no-watch": "pnpm --filter @truefoundry/trueforge-core build:gen && pnpm run build:gen",
"predev": "pnpm --filter @truefoundry/trueforge-core build:gen && pnpm run build:gen",
@@ -52,9 +52,9 @@
"test:eventsub": "jest --config jest.eventsub.config.cjs",
"test:store:postgres": "jest --config jest.store.postgres.config.cjs",
"test:store:sqlite": "jest --config jest.store.sqlite.config.cjs",
- "test": "pnpm run build:gen && NODE_OPTIONS='--conditions=trueforge-dev' node --env-file=.env.test ./node_modules/jest/bin/jest.js --config jest.unit.config.cjs",
- "test:local-sandbox:contract": "pnpm run build:gen && NODE_OPTIONS='--conditions=trueforge-dev' node --env-file=.env.test ./node_modules/jest/bin/jest.js --config jest.local-sandbox.contract.config.cjs",
- "smoke:local-sandbox": "pnpm run build:gen && NODE_OPTIONS='--conditions=trueforge-dev' jest --config jest.local-sandbox.smoke.config.cjs --runInBand --forceExit tests/sandbox/local/smoke.test.ts",
+ "test": "pnpm run build:gen && cross-env NODE_OPTIONS=--conditions=trueforge-dev node --env-file=.env.test ./node_modules/jest/bin/jest.js --config jest.unit.config.cjs",
+ "test:local-sandbox:contract": "pnpm run build:gen && cross-env NODE_OPTIONS=--conditions=trueforge-dev node --env-file=.env.test ./node_modules/jest/bin/jest.js --config jest.local-sandbox.contract.config.cjs",
+ "smoke:local-sandbox": "pnpm run build:gen && cross-env NODE_OPTIONS=--conditions=trueforge-dev jest --config jest.local-sandbox.smoke.config.cjs --runInBand --forceExit tests/sandbox/local/smoke.test.ts",
"smoke:local-sandbox:lima": "bash scripts/local-sandbox/smoke-lima.sh",
"probe:loopback": "pnpm exec tsx scripts/local-sandbox/probe-loopback.ts",
"typecheck": "pnpm run build:gen && tsc --noEmit && tsc --noEmit -p tests/db/tsconfig.json && tsc --noEmit -p tests/unit/tsconfig.json"
@@ -91,6 +91,7 @@
"@types/jest": "^29.5.14",
"@types/node": "^24.13.3",
"@types/pg": "^8.23.1",
+ "cross-env": "^10.1.0",
"jest": "^29.7.0",
"tsup": "^8.5.1",
"tsx": "^4.23.12",
diff --git a/packages/trueforge/src/db/migratePostgres.ts b/packages/trueforge/src/db/migratePostgres.ts
index b00aba9a0..df853deec 100644
--- a/packages/trueforge/src/db/migratePostgres.ts
+++ b/packages/trueforge/src/db/migratePostgres.ts
@@ -4,6 +4,7 @@ import path from 'node:path';
import type { Kysely } from 'kysely';
import { FileMigrationProvider, Migrator } from 'kysely/migration';
+import { importAbsoluteModule } from '../util/crossPlatform';
import { ensureTrueforgeSchema, TRUEFORGE_SCHEMA } from './postgres/schema';
import type { Database } from './postgres/types';
@@ -13,6 +14,7 @@ function createMigrator(db: Kysely<Database>): Migrator {
provider: new FileMigrationProvider({
fs,
path,
+ import: importAbsoluteModule,
migrationFolder: path.join(import.meta.dirname, 'postgres', 'migrations'),
}),
migrationTableSchema: TRUEFORGE_SCHEMA,
diff --git a/packages/trueforge/src/db/migrateSqlite.ts b/packages/trueforge/src/db/migrateSqlite.ts
index a17a1a8ab..67a67286b 100644
--- a/packages/trueforge/src/db/migrateSqlite.ts
+++ b/packages/trueforge/src/db/migrateSqlite.ts
@@ -4,6 +4,7 @@ import path from 'node:path';
import type { Kysely } from 'kysely';
import { FileMigrationProvider, Migrator } from 'kysely/migration';
+import { importAbsoluteModule } from '../util/crossPlatform';
import type { Database } from './sqlite/types';
/**
@@ -22,6 +23,7 @@ export async function migrateSqliteToLatest(db: Kysely<Database>): Promise<void>
provider: new FileMigrationProvider({
fs,
path,
+ import: importAbsoluteModule,
migrationFolder: path.join(import.meta.dirname, 'sqlite', 'migrations'),
}),
});
diff --git a/packages/trueforge/src/util/crossPlatform.ts b/packages/trueforge/src/util/crossPlatform.ts
new file mode 100644
index 000000000..5da7638cf
--- /dev/null
+++ b/packages/trueforge/src/util/crossPlatform.ts
@@ -0,0 +1,10 @@
+import { pathToFileURL } from 'node:url';
+
+/** Dynamic-import an absolute module path (e.g. Kysely migration files). */
+export function importAbsoluteModule(filePath: string): Promise<unknown> {
+ // Tests load TypeScript migrations from src/; production loads compiled .js from dist/.
+ if (filePath.endsWith('.ts')) {
+ return import(filePath);
+ }
+ return import(pathToFileURL(filePath).href);
+}
diff --git a/packages/trueforge/tests/unit/sandbox/local/core/codeModeSocket.test.ts b/packages/trueforge/tests/unit/sandbox/local/core/codeModeSocket.test.ts
index 2a84d8516..86459bb89 100644
--- a/packages/trueforge/tests/unit/sandbox/local/core/codeModeSocket.test.ts
+++ b/packages/trueforge/tests/unit/sandbox/local/core/codeModeSocket.test.ts
@@ -8,6 +8,8 @@ import {
} from '../../../../../src/sandbox/local/core/CodeModeUdsTransport';
import { LocalSandboxProvider } from '../../../../../src/sandbox/local/provider/LocalSandboxProvider';
+const describeUnix = process.platform === 'win32' ? describe.skip : describe;
+
async function mkdirWithRealpathBytes(bytes: number): Promise<string> {
const prefix = '/tmp';
const realPrefix = realpathSync(prefix);
@@ -24,7 +26,7 @@ async function mkdirWithRealpathBytes(bytes: number): Promise<string> {
return dir;
}
-describe('Code Mode UDS parent length', () => {
+describeUnix('Code Mode UDS parent length', () => {
it('allows a 65-byte realpath parent and listens', async () => {
const dir = await mkdirWithRealpathBytes(MAX_CODE_MODE_SOCKET_PARENT_BYTES);
try {
@@ -46,11 +48,8 @@ describe('Code Mode UDS parent length', () => {
});
});
-describe('LocalSandboxProvider.isSupported socket probe', () => {
+describeUnix('LocalSandboxProvider.isSupported socket probe', () => {
it('returns unsupported when the configured parent is over the byte limit', async () => {
- if (process.platform !== 'darwin' && process.platform !== 'linux') {
- return;
- }
const dir = await mkdirWithRealpathBytes(MAX_CODE_MODE_SOCKET_PARENT_BYTES + 1);
try {
const support = await LocalSandboxProvider.isSupported({ codeModeSocketParentPath: dir });
diff --git a/packages/trueforge/tests/unit/sandbox/local/provider/missingRoot.test.ts b/packages/trueforge/tests/unit/sandbox/local/provider/missingRoot.test.ts
index 783245a5d..8b96f249d 100644
--- a/packages/trueforge/tests/unit/sandbox/local/provider/missingRoot.test.ts
+++ b/packages/trueforge/tests/unit/sandbox/local/provider/missingRoot.test.ts
@@ -5,6 +5,8 @@ import { join } from 'node:path';
import { createLogger } from 'winston';
import { LocalSandboxProvider } from '../../../../../src/sandbox/local/provider/LocalSandboxProvider';
+const describeUnix = process.platform === 'win32' ? describe.skip : describe;
+
async function makeProvider(sandboxRootPathParent: string): Promise<LocalSandboxProvider> {
const codeModeSocketParentPath = join(tmpdir(), 'cm');
await mkdir(codeModeSocketParentPath, { recursive: true, mode: 0o700 });
@@ -16,7 +18,7 @@ async function makeProvider(sandboxRootPathParent: string): Promise<LocalSandbox
});
}
-describe('LocalSandboxProvider missing root', () => {
+describeUnix('LocalSandboxProvider missing root', () => {
it('throws SandboxNotAvailableError when the sandbox root does not exist', async () => {
const sandboxRootPathParent = await mkdtemp(join(tmpdir(), 'tfy-local-missing-'));
const provider = await makeProvider(sandboxRootPathParent);
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 589ebd40e..297eaa74f 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -26,6 +26,9 @@ importers:
'@eslint/js':
specifier: ^10.0.1
+ cross-env:
+ specifier: ^10.1.0
+ version: 10.1.0
eslint:
specifier: ^10.9.1
@@ -96,6 +99,9 @@ importers:
'@vitejs/plugin-react':
specifier: ^4.7.0
+ cross-env:
+ specifier: ^10.1.0
+ version: 10.1.0
tailwindcss:
specifier: 4.3.3
version: 4.3.3
@@ -205,6 +211,9 @@ importers:
'@types/pg':
specifier: ^8.23.1
version: 8.23.1
+ cross-env:
+ specifier: ^10.1.0
+ version: 10.1.0
jest:
specifier: ^29.7.0
@@ -1050,6 +1059,9 @@ packages:
'@daytona/[email protected]':
resolution: {integrity: sha512-uuUpiPWX0eaWbIFmYJZzt72xDtHEUAKRW62JxsoubUPSs/iNeCUcOA8GivSULWKLZCKZJQAvKJUl7y2B+73RTw==}
+ '@epic-web/[email protected]':
+ resolution: {integrity: sha512-lrTPqgvfFQtR/eY/qkIzp98OGdNJu0m5ji3q/nJI8v3SXkRKEnWiOxMmbvcSoAIzv/cGiuvRy57k4suKQSAdwA==}
+
'@esbuild/[email protected]':
resolution: {integrity: sha512-Hhmwd6CInZ3dwpuGTF8fJG6yoWmsToE+vYgD4nytZVxcu1ulHpUQRAB1UJ8+N1Am3Mz4+xOByoQoSZf4D+CpkA==}
engines: {node: '>=18'}
@@ -4552,6 +4564,11 @@ packages:
resolution: {integrity: sha512-izNAxJyRWUP8ljBoDSub5WyrVOUlT4SLGShswE7eoRBpp6QUsSycYxLBMJlbshgPBMcPT/nrfgjNY2918ayv2A==}
engines: {node: '>=18'}
+ resolution: {integrity: sha512-GsYosgnACZTADcmEyJctkJIoqAhHjttw7RsFrVoJNXbsWWqaq6Ym+7kZjq6mS45O0jij6vtiReppKQEtqWy6Dw==}
+ engines: {node: '>=20'}
+ hasBin: true
+
resolution: {integrity: sha512-uV2QOWP2nWzsy2aMp8aRibhi9dlzF5Hgh5SHaB9OiTGEyDTiJJyx0uy51QXdyWbtAHNua4XJzUKca3OzKUd3vA==}
engines: {node: '>= 8'}
@@ -8468,6 +8485,8 @@ snapshots:
- debug
- supports-color
+ '@epic-web/[email protected]': {}
+
'@esbuild/[email protected]':
optional: true
@@ -11874,6 +11893,11 @@ snapshots:
dependencies:
luxon: 3.7.2
+ dependencies:
+ '@epic-web/invariant': 1.0.0
+ cross-spawn: 7.0.6
+
dependencies:
path-key: 3.1.1
diff --git a/scripts/chmod-path.mjs b/scripts/chmod-path.mjs
new file mode 100644
index 000000000..d1d0b712e
--- /dev/null
+++ b/scripts/chmod-path.mjs
@@ -0,0 +1,8 @@
+import { chmodSync } from 'node:fs';
+import path from 'node:path';
+
+const [target, modeOctal] = process.argv.slice(2);
+if (target === undefined || modeOctal === undefined) {
+ throw new Error('usage: chmod-path.mjs <path> <mode-octal>');
+}
+chmodSync(path.resolve(target), parseInt(modeOctal, 8));
diff --git a/scripts/npx-smoke.mjs b/scripts/npx-smoke.mjs
new file mode 100644
index 000000000..805313a73
--- /dev/null
+++ b/scripts/npx-smoke.mjs
@@ -0,0 +1,89 @@
+import { execFileSync, spawn } from 'node:child_process';
+import { mkdtemp, readdir, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { execPath, platform } from 'node:process';
+import { setTimeout as delay } from 'node:timers/promises';
+import { fileURLToPath } from 'node:url';
+
+const rootDir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const win32 = platform === 'win32';
+const shell = win32 ? { shell: true } : {};
+const host = '127.0.0.1';
+const port = 18_790;
+const origin = `http://${host}:${String(port)}`;
+const packDir = await mkdtemp(path.join(tmpdir(), 'trueforge-pack-'));
+const consumerDir = await mkdtemp(path.join(tmpdir(), 'trueforge-npx-'));
+let child;
+
+try {
+ for (const filter of ['@truefoundry/trueforge-core', '@truefoundry/trueforge-sdk', '@truefoundry/trueforge']) {
+ execFileSync('pnpm', ['--filter', filter, 'pack', '--pack-destination', packDir], {
+ cwd: rootDir,
+ stdio: 'pipe',
+ ...shell,
+ });
+ }
+
+ const tarballs = (await readdir(packDir)).filter(name => name.endsWith('.tgz')).map(name => path.join(packDir, name));
+ execFileSync('npm', ['install', ...tarballs], { cwd: consumerDir, stdio: 'inherit', ...shell });
+
+ child = spawn(
+ execPath,
+ [path.join(consumerDir, 'node_modules', '@truefoundry', 'trueforge', 'dist', 'cli.js'), '--port', String(port)],
+ {
+ cwd: consumerDir,
+ env: {
+ ...process.env,
+ HOST: host,
+ STANDALONE: 'true',
+ SQLITE_PATH: path.join(consumerDir, 'db.sqlite'),
+ NODE_ENV: 'production',
+ },
+ stdio: 'inherit',
+ },
+ );
+
+ const deadline = Date.now() + 90_000;
+ let lastError;
+ let ready = false;
+ while (Date.now() < deadline) {
+ if (child.exitCode !== null) {
+ throw new Error(`CLI exited before ready (code=${String(child.exitCode)})`);
+ }
+ try {
+ const signal = globalThis.AbortSignal.timeout(2_000);
+ const [health, ui] = await Promise.all([
+ globalThis.fetch(`${origin}/healthz`, { signal }),
+ globalThis.fetch(`${origin}/`, { signal }),
+ ]);
+ const html = await ui.text();
+ if (health.ok && ui.ok && html.includes('id="root"')) {
+ ready = true;
+ break;
+ }
+ lastError = new Error(`healthz=${String(health.status)} ui=${String(ui.status)}`);
+ } catch (error) {
+ lastError = error;
+ }
+ await delay(500);
+ }
+ if (!ready) {
+ throw new Error('packed CLI did not become ready', { cause: lastError });
+ }
+ console.log('packed CLI healthz and UI OK');
+} finally {
+ if (child?.pid !== undefined) {
+ try {
+ if (win32) {
+ execFileSync('taskkill', ['/pid', String(child.pid), '/T', '/F'], { stdio: 'ignore' });
+ } else {
+ child.kill('SIGTERM');
+ }
+ } catch {
+ // already gone
+ }
+ }
+ await rm(packDir, { recursive: true, force: true });
+ await rm(consumerDir, { recursive: true, force: true });
+}
diff --git a/scripts/rm-path.mjs b/scripts/rm-path.mjs
new file mode 100644
index 000000000..2ec6505e9
--- /dev/null
+++ b/scripts/rm-path.mjs
@@ -0,0 +1,6 @@
+import { rmSync } from 'node:fs';
+import path from 'node:path';
+
+for (const target of process.argv.slice(2)) {
+ rmSync(path.resolve(target), { recursive: true, force: true });
+}