From 562489a2ad9ad6d5163ed0ab6c9b5fad82741d49 Mon Sep 17 00:00:00 2001 From: Ofri Wolfus Date: Thu, 29 Oct 2026 14:13:24 +0200 Subject: [PATCH 1/2] feat(cli): complete packaging contracts above branded paths Final ninth replacement layer on f332f658. Squash CLI source branch 54bf92ee (71c54d4d, 06c160bc, 12c956c3, c435ac25, CLI subsets of 8b3aef99/9df42768, and 10a18e26/0badaea0/39035b22 contracts). Shared compiler, worker, logging and floor prerequisites are inherited, not reapplied. Resolve 25dbbfbd/23d6c6d0 path residuals in new npm scripts and CLI fixtures: branded worker-backed I/O, semantic graph containment, and shared tests/deno-info.ts. Preserve L8 walk/static/property guards and generated assets rebuilt identically on both runtimes. Omit the registry static guard by explicit coordinator direction; retain checkout-linked compile and real built-package contracts. Verified full suites sequentially on Deno 2.9.1 and actual 2.3.3: Deno 701/701, Node 24 701/701, browser 433/433 each. Path 24/24, package-enabled 1/1, npm type/script 19/19, public/worker checks, npm archives and JSR dry runs pass. Changed TS lint is clean (baseline 10 findings); optional fixture check retains the inherited system-info logging diagnostic owned by CI. --- .github/workflows/publish.yml | 26 +- .github/workflows/test.yml | 59 +++ .gitignore | 3 + CHANGELOG.md | 19 + base/development.ts | 8 +- base/file-watcher.ts | 2 +- cli/compile.ts | 25 +- cli/init.ts | 76 +++- cli/template-manifest.ts | 38 ++ cli/templates/node/{.npmrc => npmrc} | 0 .../shared/{.gitignore => gitignore} | 0 deno.json | 7 +- docs/api/functions-server.mdx | 2 +- package.json | 8 +- scripts/check-npm-entrypoints.test.ts | 109 ++++++ scripts/check-npm-entrypoints.ts | 68 ++++ scripts/copy-cli-templates.ts | 22 ++ scripts/npm-manifest.test.ts | 61 +++ scripts/npm-manifest.ts | 100 +++++ scripts/verify-npm-archive.ts | 84 +++++ tests/cli-compile.test.ts | 326 +++++++++++++--- tests/cli-init.test.ts | 196 ++++++---- tests/cli-package.test.ts | 352 ++++++++++++++++++ tests/cli-template-utils.ts | 208 +++++++++++ tests/test-registry.ts | 2 + tsconfig.npm.json | 20 + tsup.config.ts | 1 + types/chokidar.d.ts | 22 ++ types/deno-global.d.ts | 101 ----- 29 files changed, 1689 insertions(+), 256 deletions(-) create mode 100644 cli/template-manifest.ts rename cli/templates/node/{.npmrc => npmrc} (100%) rename cli/templates/shared/{.gitignore => gitignore} (100%) create mode 100644 scripts/check-npm-entrypoints.test.ts create mode 100644 scripts/check-npm-entrypoints.ts create mode 100644 scripts/copy-cli-templates.ts create mode 100644 scripts/npm-manifest.test.ts create mode 100644 scripts/npm-manifest.ts create mode 100644 scripts/verify-npm-archive.ts create mode 100644 tests/cli-package.test.ts create mode 100644 tests/cli-template-utils.ts create mode 100644 tsconfig.npm.json create mode 100644 types/chokidar.d.ts delete mode 100644 types/deno-global.d.ts diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml index 2d5f78cb..9618f5fb 100644 --- a/.github/workflows/publish.yml +++ b/.github/workflows/publish.yml @@ -33,6 +33,12 @@ jobs: - name: Build npm artifact run: npm run build:npm + # Publication check: the archive must contain every export, bin, and + # template. Source tests validate the checkout; this validates the + # release artifact. + - name: Verify npm archive contents + run: deno task verify:npm-archive + # Extract version once from deno.json; reused across all publish steps (DRY). - name: Extract version from deno.json id: extract_version @@ -41,23 +47,13 @@ jobs: echo "VERSION=$VERSION" >> $GITHUB_OUTPUT # Rewrite package.json version + exports for npm publish. - # In the repo, exports point to .ts source (for local dev/tests). Here we switch to dist/. + # In the repo, exports point to .ts source (for local dev/tests). The shared + # transform in scripts/npm-manifest.ts switches them to dist/. The package + # contract test applies the same transform, so a shipped-manifest + # regression fails the gate rather than the release. # This runs AFTER npm install + build so the lockfile matches during install. - name: Sync version and exports from deno.json → package.json - run: | - deno eval --node-modules-dir=none " - import pkg from './package.json' with {type:'json'}; - import cfg from './deno.json' with {type:'json'}; - pkg.version = cfg.version; - pkg.exports = { - '.': { import: './dist/mod.js', types: './dist/mod.d.ts' }, - './react': { import: './dist/react/hooks.js', types: './dist/react/hooks.d.ts' }, - './server': { import: './dist/server.js', types: './dist/server.d.ts' }, - './server/build': { import: './dist/server-build.js', types: './dist/server-build.d.ts' }, - './link': { import: './dist/cli/link.js', types: './dist/cli/link.d.ts' }, - }; - await Deno.writeTextFile('./package.json', JSON.stringify(pkg, null, 2) + '\n'); - " + run: deno run -A scripts/npm-manifest.ts - name: Publish to JSR run: | diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index 297be980..83c393b7 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -43,6 +43,23 @@ jobs: CI: true FC_SEED: 42 + package-validation: + name: Package Archive + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - name: Setup Deno + uses: denoland/setup-deno@v2 + with: + deno-version: v2.3.3 # floor: native explicit resource management (V8); see denoland/deno#29282 + + # Validates the JSR upload set and publish-time specifier rewriting + # without publishing. The compile E2E links local source, so it cannot + # cover this package-boundary contract. + - name: Validate JSR package + run: deno publish --dry-run + docs-build: name: Docs Build runs-on: ubuntu-latest @@ -76,6 +93,11 @@ jobs: steps: - uses: actions/checkout@v4 + - name: Setup Deno + uses: denoland/setup-deno@v2 + with: + deno-version: v2.3.3 # floor: native explicit resource management (V8); see denoland/deno#29282 + - name: Setup Node.js uses: actions/setup-node@v4 with: @@ -84,9 +106,46 @@ jobs: - name: Install npm dependencies run: npm install + - name: Type check npm surface + run: npm run check:npm-types + - name: Build npm package run: npm run build:npm + # Archive membership is checked on every push, not only at tag time. + # Same verifier as publish, so a staging regression fails the PR. + - name: Verify npm archive contents + run: deno task verify:npm-archive + + build-contract: + name: Build Contract + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - name: Setup Deno + uses: denoland/setup-deno@v2 + with: + deno-version: v2.3.3 # floor: native explicit resource management (V8); see denoland/deno#29282 + + - name: Setup Node.js + uses: actions/setup-node@v4 + with: + node-version: '24.x' + + - name: Install npm dependencies + run: npm install + + # Builds the current checkout. The suite loads dist in place and must not + # install the package or resolve it from a registry. `prefer-offline` + # keeps the registry traffic down without failing on a dependency that + # the cache does not hold yet. + - name: Package contract + run: deno task test:package + env: + GOATDB_TEST_PACKAGE: '1' + npm_config_prefer_offline: 'true' + test-browser: name: Browser Tests runs-on: ubuntu-latest diff --git a/.gitignore b/.gitignore index 02d0f1d8..ed19c6d3 100644 --- a/.gitignore +++ b/.gitignore @@ -26,6 +26,9 @@ docs/api.json # npm build artifacts dist/ +# npm entrypoint guard test temp dirs +.npm-entrypoints-* + # Benchmark JSON output (generated by deno task bench:json) benchmarks/results/ diff --git a/CHANGELOG.md b/CHANGELOG.md index b4c6270f..51e0cad8 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -42,6 +42,15 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), ### Fixed +- `goatdb init` now scaffolds `.gitignore` and `.npmrc` again when run from the + published npm package. `npm pack` drops dotfile sources, so the templates use + plain names (`gitignore`, `npmrc`) that `init` maps back to their dotted + targets. +- `goatdb init` now exits non-zero when dependency installation fails, reporting + the command, its exit code and its output. Previously a failed `npm install` + only warned, so a broken scaffold looked successful. +- `deno compile` output names now include `.exe` for Windows targets, so + `compile()` returns and logs the path that the compiler actually writes. - A `Date` inside a `map` field now uses the tagged `{ "__t": "D", "__v": }` wire form, the same as every other position. It was copied raw before, so it round-tripped as an ISO string while @@ -77,6 +86,16 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and do not start loading. A fresh unobserved query reports `loading === false` and, when `queryInactivityTimeoutMs` is set, is eligible for auto-close. A closed query is replaced by calling `db.query()` again. +- `compile()` now resolves to the path of the compiled executable + (`Promise`). Callers that ignore the value need no change. + +### Changed + +- `goatdb init` on Deno now requests `react`, `react-dom`, `yargs` and + `@types/react` as `^` ranges and installs all dependencies in one `deno add` + call, bounded by a 180s timeout. Exact pins let a transitive peer resolve a + newer `react` than `react-dom`, which crashes at runtime with "Incompatible + React versions". ## [0.6.1] - 2026-09-01 diff --git a/base/development.ts b/base/development.ts index cf9c1269..64bea074 100644 --- a/base/development.ts +++ b/base/development.ts @@ -5,7 +5,7 @@ import { isWindows } from './os.ts'; type Stringable = { toString(): string }; // Cache Node.js child_process module (loaded lazily) -let childProcessModule: any = undefined; +let childProcessModule: typeof import('node:child_process') | undefined; export async function copyToClipboard(value: string): Promise { if (!isDeno()) return false; @@ -51,6 +51,8 @@ export interface CliOptions { cwd?: string; /** Timeout in milliseconds. Process is killed if it exceeds this. */ timeout?: number; + /** Environment variables to add or override for the command. */ + env?: Record; } function isCliOptions(arg: unknown): arg is CliOptions { @@ -100,6 +102,7 @@ export async function cli( stdout: 'piped', stderr: 'piped', cwd: options.cwd, + env: options.env && { ...Deno.env.toObject(), ...options.env }, signal: ac?.signal, }); try { @@ -129,6 +132,9 @@ export async function cli( const onWindows = isWindows(); const spawnOptions: Record = {}; if (options.cwd) spawnOptions.cwd = options.cwd; + if (options.env) { + spawnOptions.env = { ...globalThis.process.env, ...options.env }; + } // On Windows, .cmd batch scripts (npm.cmd, deno.cmd) can't be found by // name without shell: true. Only safe because all cli() call sites pass // hardcoded commands — never user-supplied input. diff --git a/base/file-watcher.ts b/base/file-watcher.ts index 0867b77e..5b6cd2e4 100644 --- a/base/file-watcher.ts +++ b/base/file-watcher.ts @@ -158,7 +158,7 @@ function createQueuedWatcher( } function createChokidarWatcher( - chokidar: typeof import('chokidar'), + chokidar: { watch: typeof import('chokidar').watch }, dir: string, ): FileWatcher { const underlying = chokidar.watch(dir, { diff --git a/cli/compile.ts b/cli/compile.ts index 8ddc29c4..e4b3e4de 100644 --- a/cli/compile.ts +++ b/cli/compile.ts @@ -148,12 +148,12 @@ export type CompileOptions = * - Node.js: Uses Single Executable Application (SEA) process * * @param options Configuration options for the compilation process - * @returns A Promise that resolves when compilation is complete + * @returns A Promise that resolves to the path of the compiled executable * @group Compilation * * @example * ```typescript - * await compile({ + * const binaryPath = await compile({ * serverEntry: "./server/main.ts", * outputName: "my-app", * os: "linux", @@ -164,7 +164,7 @@ export type CompileOptions = * }); * ``` */ -export async function compile(options: CompileOptions): Promise { +export async function compile(options: CompileOptions): Promise { if (!options.buildDir) { throw new Error('buildDir is required for compilation'); } @@ -180,6 +180,7 @@ export async function compile(options: CompileOptions): Promise { if (options.signing) { await signExecutable(outputFile, options.signing); } + return outputFile; } /** @@ -270,7 +271,7 @@ async function compileDeno(options: CompileOptions): Promise { const buildInfoJsonPath = path.join(buildDir, 'buildInfo.json'); const outputFile = path.join( buildDir, - `${options.outputName || 'app'}-${targetOsArch}`, + denoExecutableName(options.outputName || 'app', targetOsArch), ); let success = false; try { @@ -785,6 +786,22 @@ export function targetFromOSArch(os?: TargetOS, arch?: CPUArch): OSArchTarget { return `${os}-${arch}`; } +/** + * Returns the executable file name that `deno compile` produces for a target. + * + * Deno appends `.exe` when the *target* OS is Windows, regardless of the host + * OS (see deno's `get_os_specific_filepath`). The suffix therefore applies to + * cross-compiled Windows binaries too; without it the returned/logged path and + * the failure cleanup point at a file the compiler never creates. + */ +export function denoExecutableName( + outputName: string, + target: OSArchTarget, +): string { + const ext = target.startsWith('windows-') ? '.exe' : ''; + return `${outputName}-${target}${ext}`; +} + /** * Converts GoatDB OS and architecture parameters to Deno's target format. * diff --git a/cli/init.ts b/cli/init.ts index bfee0398..823af51a 100644 --- a/cli/init.ts +++ b/cli/init.ts @@ -19,6 +19,7 @@ import { } from '../base/json-log/file-impl.ts'; import { cli } from '../base/development.ts'; import { kMinNodeMajor } from './compile.ts'; +import { templateTargetPath } from './template-manifest.ts'; /** * Returns the path to the templates directory. @@ -61,13 +62,48 @@ async function copyTemplateFile( await copyFile(srcPath, fullDestPath); } -async function installDenoDependency( - spec: string, +/** + * Upper bound for dependency installation. A stalled registry must fail with a + * diagnosable error instead of hanging `init` or the worker that invoked it. + */ +const kDependencyInstallTimeoutMs = 180_000; + +function installFailure( + command: string, + result: { result: string; exitCode: number }, +): Error { + // Include the captured output: the child's stderr is the only evidence of + // why the registry or package manager refused the install. + return new Error( + `${command} failed with exit code ${result.exitCode}:\n${result.result}`, + ); +} + +/** + * npm dependencies the Deno scaffold installs, keyed by the import specifier + * `deno add` generates. Ranges keep react and react-dom on the same resolved + * version; exact pins let a transitive peer pull a newer react than react-dom, + * which crashes at runtime with "Incompatible React versions". Exported so the + * compile E2E resolves the same specs the scaffold installs. + */ +export const kDenoTemplateNpmDependencies = { + 'react': 'npm:react@^19.0.0', + 'react-dom/client': 'npm:react-dom@^19.0.0/client', + 'yargs': 'npm:yargs@^17.7.2', + '@types/react': 'npm:@types/react@^19.0.8', +} as const; + +async function installDenoDependencies( + specs: readonly string[], targetDir: string, ): Promise { - const result = await cli('deno', 'add', spec, { cwd: targetDir }); + const command = `deno add ${specs.join(' ')}`; + const result = await cli('deno', 'add', ...specs, { + cwd: targetDir, + timeout: kDependencyInstallTimeoutMs, + }); if (result.exitCode !== 0) { - throw new Error(`Failed to install dependency ${spec}`); + throw installFailure(command, result); } } @@ -132,10 +168,12 @@ export async function bootstrapProject( 'client/index.css', projectDir, ); + // Dotfiles are excluded by npm pack, so templates use plain names and the + // scaffold restores the leading dot. await copyTemplateFile( templateDir, - 'shared/.gitignore', - '.gitignore', + 'shared/gitignore', + templateTargetPath('shared/gitignore', runtime), projectDir, ); @@ -196,12 +234,12 @@ export async function bootstrapProject( projectDir, ); if (!opts.skipDependencies) { - await installDenoDependency('jsr:@goatdb/goatdb', projectDir); - await installDenoDependency('jsr:@std/path', projectDir); - await installDenoDependency('npm:react@19.0.0', projectDir); - await installDenoDependency('npm:react-dom@19.0.0/client', projectDir); - await installDenoDependency('npm:yargs@17.7.2', projectDir); - await installDenoDependency('npm:@types/react@19.0.8', projectDir); + // One command: fewer registry round-trips and one bounded wait. + await installDenoDependencies([ + 'jsr:@goatdb/goatdb', + 'jsr:@std/path', + ...Object.values(kDenoTemplateNpmDependencies), + ], projectDir); } } else if (isNode()) { await copyNodePackageJson(templateDir, projectDir); @@ -211,12 +249,20 @@ export async function bootstrapProject( 'tsconfig.json', projectDir, ); - await copyTemplateFile(templateDir, 'node/.npmrc', '.npmrc', projectDir); + await copyTemplateFile( + templateDir, + 'node/npmrc', + templateTargetPath('node/npmrc', runtime), + projectDir, + ); if (!opts.skipDependencies) { - const result = await cli('npm', 'install', { cwd: projectDir }); + const result = await cli('npm', 'install', { + cwd: projectDir, + timeout: kDependencyInstallTimeoutMs, + }); if (result.exitCode !== 0) { - console.warn('npm install failed:', result.result); + throw installFailure('npm install', result); } } } diff --git a/cli/template-manifest.ts b/cli/template-manifest.ts new file mode 100644 index 00000000..4a6b5c04 --- /dev/null +++ b/cli/template-manifest.ts @@ -0,0 +1,38 @@ +/** + * Template path contract shared by the scaffold and its tests. + * + * WHY: npm pack drops dotfiles. Templates use plain names (`gitignore`, + * `npmrc`) and the scaffold restores the leading dot. One map keeps both + * consumers from drifting when a source is renamed. + */ + +export type TemplateRuntime = 'deno' | 'node'; + +/** + * Key: template source path relative to `cli/templates`. + * Value: generated project path relative to the target directory. + */ +export const kTemplateDotfileTargets: Readonly> = { + 'shared/gitignore': '.gitignore', + 'node/npmrc': '.npmrc', +}; + +/** Resolves a template source path to its generated project path. */ +export function templateTargetPath( + sourceRelative: string, + runtime: TemplateRuntime, +): string { + const dotfileTarget = kTemplateDotfileTargets[sourceRelative]; + if (dotfileTarget !== undefined) { + return dotfileTarget; + } + const prefix = sourceRelative.startsWith('shared/') + ? 'shared/' + : `${runtime}/`; + if (!sourceRelative.startsWith(prefix)) { + throw new Error( + `Template path outside shared/ and ${runtime}/: ${sourceRelative}`, + ); + } + return sourceRelative.slice(prefix.length); +} diff --git a/cli/templates/node/.npmrc b/cli/templates/node/npmrc similarity index 100% rename from cli/templates/node/.npmrc rename to cli/templates/node/npmrc diff --git a/cli/templates/shared/.gitignore b/cli/templates/shared/gitignore similarity index 100% rename from cli/templates/shared/.gitignore rename to cli/templates/shared/gitignore diff --git a/deno.json b/deno.json index b8338e31..6a37202a 100644 --- a/deno.json +++ b/deno.json @@ -14,9 +14,11 @@ "package.json", "tsup.config.ts", "tsconfig.node.json", + "tsconfig.npm.json", ".npmrc", ".github/", "tests/", + "scripts/", "benchmarks/", "docs/", "examples/" @@ -51,6 +53,8 @@ "test": "deno run -A tests/run.ts", "test:smoke": "deno run -A tests/run.ts --runtime=deno --suite=SecurityBoundaries", "test:paths": "deno run -A tests/run.ts --runtime=deno --suite=Path", + "test:package": "deno run -A tests/run.ts --suite=CLI-Package --runtime=node", + "verify:npm-archive": "deno run -A scripts/verify-npm-archive.ts", "bench": "deno run -A benchmarks/run.ts", "bench:json": "deno run -A benchmarks/run.ts --output-json --output-dir=benchmarks/results", "bench:update-docs": "deno run -A benchmarks/update-docs.ts --input-dir=benchmarks/results", @@ -78,7 +82,8 @@ "source-map": "npm:source-map@^0.7.4", "sql.js": "npm:sql.js@^1.11.0", "postject": "npm:postject@1.0.0-alpha.6", - "yargs": "npm:yargs@^17.7.2" + "yargs": "npm:yargs@^17.7.2", + "react-dom": "npm:react-dom@^19.0.0" }, "nodeModulesDir": "auto" } diff --git a/docs/api/functions-server.mdx b/docs/api/functions-server.mdx index d6fe122c..56cb8dda 100644 --- a/docs/api/functions-server.mdx +++ b/docs/api/functions-server.mdx @@ -6,7 +6,7 @@ title: Server Functions ## compile -**compile(options: [CompileOptions](/api/types/compileoptions)): Promise<void>** +**compile(options: [CompileOptions](/api/types/compileoptions)): Promise<string>** Compiles a GoatDB application into a standalone executable. diff --git a/package.json b/package.json index 94606741..63099b9c 100644 --- a/package.json +++ b/package.json @@ -24,7 +24,8 @@ "goatdb": "./dist/cli/init.js" }, "scripts": { - "build:npm": "tsup" + "check:npm-types": "node scripts/check-npm-entrypoints.ts && node --test scripts/check-npm-entrypoints.test.ts scripts/npm-manifest.test.ts && tsc -p tsconfig.npm.json", + "build:npm": "tsup && node scripts/copy-cli-templates.ts" }, "dependencies": { "@goatdb/orderstamp": "npm:@jsr/goatdb__orderstamp@^1.1.1", @@ -34,6 +35,7 @@ "esbuild": "^0.25.4" }, "optionalDependencies": { + "chokidar": "^4.0.3", "postject": "1.0.0-alpha.6" }, "peerDependencies": { @@ -50,11 +52,13 @@ }, "devDependencies": { "@deno/esbuild-plugin": "npm:@jsr/deno__esbuild-plugin@^1.2.1", + "@types/deno": "2.7.0", "@types/node": "^24.0.0", "@types/nodemailer": "^6.4.17", "@types/react": "^19.0.0", "fast-check": "4.10.2", "tsup": "^8.0.0", - "typescript": "^5.9.3" + "typescript": "^5.9.3", + "react-dom": "^19.0.0" } } diff --git a/scripts/check-npm-entrypoints.test.ts b/scripts/check-npm-entrypoints.test.ts new file mode 100644 index 00000000..fabd242c --- /dev/null +++ b/scripts/check-npm-entrypoints.test.ts @@ -0,0 +1,109 @@ +import assert from 'node:assert/strict'; +import { spawnSync } from 'node:child_process'; +import { copyFile, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises'; +import { resolve } from '../base/path.ts'; +import { test } from 'node:test'; +import { fileURLToPath } from 'node:url'; + +const root = fileURLToPath(new URL('../', import.meta.url)); +const guard = resolve(root, 'scripts/check-npm-entrypoints.ts'); + +async function fixture(run: (path: string) => void | Promise) { + // Keep module resolution identical to the real build, without editing its files. + const path = await mkdtemp(resolve(root, '.npm-entrypoints-')); + try { + for ( + const name of ['package.json', 'tsup.config.ts', 'tsconfig.npm.json'] + ) { + await copyFile(resolve(root, name), resolve(path, name)); + } + await run(path); + } finally { + await rm(path, { recursive: true, force: true }); + } +} + +async function replace(path: string, name: string, old: string, value: string) { + const file = resolve(path, name); + const text = await readFile(file, 'utf8'); + assert.ok(text.includes(old), `Mutation target missing: ${old}`); + await writeFile(file, text.replace(old, value)); +} + +function check(path: string, missing?: string) { + const result = spawnSync(process.execPath, [guard, path], { + encoding: 'utf8', + timeout: 10_000, + }); + assert.ifError(result.error); + if (missing) { + assert.equal(result.status, 1, result.stderr); + assert.ok(result.stderr.includes(missing), result.stderr); + } else { + assert.equal(result.status, 0, result.stderr); + } +} + +test('npm entrypoint guard runs as a script from its own path', async () => { + const path = await mkdtemp(resolve(root, '.npm-entrypoints-')); + try { + // Empty cwd: only a live main-module guard reaches checkNpmEntrypoints. + const result = spawnSync(process.execPath, [guard], { + cwd: path, + encoding: 'utf8', + timeout: 10_000, + }); + assert.equal(result.status, 1, result.stderr); + } finally { + await rm(path, { recursive: true, force: true }); + } +}); + +test('npm entrypoint guard accepts the real public entrypoints', async () => { + await fixture((path) => check(path)); +}); + +for ( + const [name, text, value, failure] of [ + ['tsup.config.ts', "server: 'server.ts',", '', 'missing [server.ts]'], + [ + 'tsup.config.ts', + "'cli/init': 'cli/init.ts',", + '', + 'missing [cli/init.ts]', + ], + ['tsconfig.npm.json', '"server.ts",', '', 'missing [server.ts]'], + ['tsconfig.npm.json', '"cli/init.ts",', '', 'missing [cli/init.ts]'], + [ + 'tsup.config.ts', + 'entry: {', + "entry: { extra: 'extra.ts',", + 'extra [extra.ts]', + ], + [ + 'tsup.config.ts', + "server: 'server.ts'", + "renamed: 'server.ts'", + 'tsup output entrypoint drift: missing [server.ts]', + ], + [ + 'package.json', + '"./server.ts"', + '"./new-public.ts"', + 'missing [new-public.ts]', + ], + [ + 'package.json', + './dist/cli/init.js', + './cli/init.js', + 'Unsupported npm bin target', + ], + ] +) { + test(`npm guard rejects ${name}: ${failure}`, async () => { + await fixture(async (path) => { + await replace(path, name, text, value); + check(path, failure); + }); + }); +} diff --git a/scripts/check-npm-entrypoints.ts b/scripts/check-npm-entrypoints.ts new file mode 100644 index 00000000..14e10735 --- /dev/null +++ b/scripts/check-npm-entrypoints.ts @@ -0,0 +1,68 @@ +import { readFile } from 'node:fs/promises'; +import * as path from '../base/path.ts'; +import { pathToFileURL } from 'node:url'; +import ts from 'typescript'; + +async function readConfig(root: string, name: string) { + const text = await readFile(path.resolve(root, name), 'utf8'); + const result = ts.parseConfigFileTextToJson(name, text); + if (result.error) { + throw new Error( + ts.flattenDiagnosticMessageText(result.error.messageText, '\n'), + ); + } + return result.config; +} + +function binSource(target: string): string { + if (!target.startsWith('./dist/') || !target.endsWith('.js')) { + throw new Error(`Unsupported npm bin target: ${target}`); + } + return target.slice('./dist/'.length, -3) + '.ts'; +} + +function assertEntries(label: string, expected: string[], actual: string[]) { + const missing = expected.filter((entry) => !actual.includes(entry)); + const extra = actual.filter((entry) => !expected.includes(entry)); + if (missing.length || extra.length) { + throw new Error( + `${label} entrypoint drift: missing [${missing}]; extra [${extra}]`, + ); + } +} + +async function publicEntries(root: string): Promise { + const manifest = await readConfig(root, 'package.json'); + return [ + ...Object.values(manifest.exports as Record) + .map((entry) => path.normalize(entry)), + ...Object.values(manifest.bin as Record).map(binSource), + ]; +} + +export async function checkNpmEntrypoints(root: string): Promise { + const expected = await publicEntries(root); + const { default: build } = await import( + pathToFileURL(path.resolve(root, 'tsup.config.ts')).href + ); + const config = await readConfig(root, 'tsconfig.npm.json'); + assertEntries('tsup', expected, Object.values(build.entry)); + assertEntries( + 'tsup output', + expected, + Object.keys(build.entry).map((s) => s + '.ts'), + ); + assertEntries( + 'npm types', + expected, + config.include.filter((s: string) => s !== 'types/**/*.d.ts'), + ); +} + +const invokedPath = process.argv[1]; +if ( + invokedPath && + path.equals(path.resolve(invokedPath), path.fromFileUrl(import.meta.url)) +) { + await checkNpmEntrypoints(path.resolve(process.argv[2] ?? '.')); +} diff --git a/scripts/copy-cli-templates.ts b/scripts/copy-cli-templates.ts new file mode 100644 index 00000000..64e6bbd4 --- /dev/null +++ b/scripts/copy-cli-templates.ts @@ -0,0 +1,22 @@ +/** + * Copies the CLI scaffolds into the npm build output. + * + * WHY: `bootstrapProject` resolves templates relative to the bundled bin + * (`dist/cli/templates`). tsup does not copy static files, so without this step + * the published npm CLI cannot scaffold a project. + * + * WHY the destination is removed first: the copy replaces the template tree. + * Merging into an existing tree would keep deleted or renamed source files in + * the build output and ship them in the npm tarball. + */ +import { cpSync, rmSync } from 'node:fs'; +import { resolve } from '../base/path.ts'; +import { log } from '../logging/log.ts'; + +const root = process.cwd(); +const source = resolve(root, 'cli/templates'); +const destination = resolve(root, 'dist/cli/templates'); + +rmSync(destination, { recursive: true, force: true }); +cpSync(source, destination, { recursive: true }); +log({ severity: 'INFO', message: `Copied CLI templates to ${destination}` }); diff --git a/scripts/npm-manifest.test.ts b/scripts/npm-manifest.test.ts new file mode 100644 index 00000000..ce2f95a5 --- /dev/null +++ b/scripts/npm-manifest.test.ts @@ -0,0 +1,61 @@ +import assert from 'node:assert/strict'; +import { test } from 'node:test'; +import { type NpmManifest, productionManifest } from './npm-manifest.ts'; + +function manifest(exports?: NpmManifest['exports']): NpmManifest { + return { name: '@goatdb/goatdb', exports }; +} + +/** Synthetic subpaths: this fixture must never mirror the real package map. */ +test('npm manifest derives dist targets from export source paths', () => { + const shipped = productionManifest( + manifest({ + '.': './alpha.ts', + './nested/entry': './nested/deep/entry.ts', + }), + '1.2.3', + ); + assert.deepEqual(shipped.exports, { + '.': { import: './dist/alpha.js', types: './dist/alpha.d.ts' }, + './nested/entry': { + import: './dist/nested/deep/entry.js', + types: './dist/nested/deep/entry.d.ts', + }, + }); + assert.equal(shipped.version, '1.2.3'); +}); + +test('npm manifest keeps non-export fields intact', () => { + const shipped = productionManifest( + { ...manifest({ './x': './x.ts' }), bin: { goatdb: './dist/cli/init.js' } }, + '0.0.1', + ); + assert.deepEqual(shipped.bin, { goatdb: './dist/cli/init.js' }); +}); + +for ( + const [label, exports, failure] of [ + ['missing exports', undefined, 'npm exports missing'], + ['empty exports', {}, 'npm exports missing'], + [ + 'already transformed entry', + { './x': { import: './dist/x.js', types: './dist/x.d.ts' } }, + "must be a './*.ts' source path", + ], + ['non-ts source', { './x': './x.js' }, "must be a './*.ts' source path"], + ['extensionless source', { './x': './dist/x' }, 'must be a'], + ['bare source', { './x': 'x.ts' }, 'must be a'], + ['empty file name', { './x': './.ts' }, 'must be a'], + ] as const +) { + test(`npm manifest rejects ${label}`, () => { + assert.throws( + () => + productionManifest( + manifest(exports as NpmManifest['exports']), + '1.0.0', + ), + { message: new RegExp(failure.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')) }, + ); + }); +} diff --git a/scripts/npm-manifest.ts b/scripts/npm-manifest.ts new file mode 100644 index 00000000..29bf0e03 --- /dev/null +++ b/scripts/npm-manifest.ts @@ -0,0 +1,100 @@ +/** + * Production manifest transform for the npm package. + * + * WHY: package.json exports point at TypeScript sources for local development, + * while npm ships only `dist`. Publication must therefore rewrite version and + * exports. The publish workflow and the package contract test both call this + * module, so a drift between the dev manifest and the shipped one fails the + * gate instead of the release. + * + * Single source of truth: package.json export values name the public entry + * sources. Dist targets are a pure function of those values (`./a/b.ts` -> + * `./dist/a/b.js`), and scripts/check-npm-entrypoints.ts pins tsup entry names + * to the same source paths. A new public entry therefore needs no edit here. + */ +import { readFile, writeFile } from 'node:fs/promises'; +import { resolve } from '../base/path.ts'; + +export interface NpmExportEntry { + import: string; + types: string; +} + +export interface NpmManifest { + version?: string; + exports?: Record; + [key: string]: unknown; +} + +/** Manifest returned by {@link productionManifest}; every export is built. */ +export interface ProductionManifest extends NpmManifest { + exports: Record; +} + +const kSourcePrefix = './'; +const kSourceExt = '.ts'; +const kDistPrefix = './dist/'; + +/** Maps a `./*.ts` export source to its built counterpart (`./dist/*.`). */ +function distTarget(subpath: string, source: unknown, ext: string): string { + if ( + typeof source !== 'string' || + !source.startsWith(kSourcePrefix) || + !source.endsWith(kSourceExt) || + source.length === kSourcePrefix.length + kSourceExt.length + ) { + throw new Error( + `npm export "${subpath}" must be a './*.ts' source path, got ` + + JSON.stringify(source), + ); + } + return kDistPrefix + source.slice(kSourcePrefix.length, -kSourceExt.length) + + ext; +} + +function distExports(manifest: NpmManifest): Record { + const sources = manifest.exports; + if (sources === undefined || Object.keys(sources).length === 0) { + throw new Error('npm exports missing from package.json'); + } + const exports: Record = {}; + for (const [subpath, source] of Object.entries(sources)) { + exports[subpath] = { + import: distTarget(subpath, source, '.js'), + types: distTarget(subpath, source, '.d.ts'), + }; + } + return exports; +} + +/** Returns the manifest npm must publish. Does not mutate the input. */ +export function productionManifest( + manifest: NpmManifest, + version: string, +): ProductionManifest { + return { ...manifest, version, exports: distExports(manifest) }; +} + +export async function readJson(file: string): Promise { + return JSON.parse(await readFile(file, 'utf8')) as T; +} + +/** Rewrites `/package.json` in place for npm publication. */ +export async function writeNpmManifest(root: string): Promise { + const manifest = await readJson(resolve(root, 'package.json')); + const config = await readJson<{ version: string }>( + resolve(root, 'deno.json'), + ); + const prepared = productionManifest(manifest, config.version); + await writeFile( + resolve(root, 'package.json'), + JSON.stringify(prepared, null, 2) + '\n', + ); +} + +// Guard: the test runner imports this module, so only Deno entry execution may +// touch package.json. `typeof Deno` also blocks Node bundles that define +// import.meta.main for their own entry module. +if (typeof Deno !== 'undefined' && import.meta.main) { + await writeNpmManifest(Deno.args[0] ?? '.'); +} diff --git a/scripts/verify-npm-archive.ts b/scripts/verify-npm-archive.ts new file mode 100644 index 00000000..701489ac --- /dev/null +++ b/scripts/verify-npm-archive.ts @@ -0,0 +1,84 @@ +/** Verifies the npm archive contains every file the package contract promises. + * CI runs this after `build:npm`, so a broken archive fails the PR, not the + * release. */ + +import { readdir } from 'node:fs/promises'; +import { spawnSync } from 'node:child_process'; +import { resolve } from '../base/path.ts'; +import { log } from '../logging/log.ts'; +import { + type NpmManifest, + productionManifest, + readJson, +} from './npm-manifest.ts'; + +interface PackEntry { + files: Array<{ path: string }>; +} + +function normalize(target: string): string { + return target.replace(/^\.\//, ''); +} + +async function requiredShipPaths(root: string): Promise { + const checkout = await readJson(resolve(root, 'package.json')); + const config = await readJson<{ version: string }>( + resolve(root, 'deno.json'), + ); + const manifest = productionManifest(checkout, config.version); + const required = new Set(['README.md', 'LICENSE']); + for (const entry of Object.values(manifest.exports)) { + required.add(normalize(entry.import)); + required.add(normalize(entry.types)); + } + const bin = manifest.bin as Record | undefined; + if (bin?.goatdb !== undefined) { + required.add(normalize(bin.goatdb)); + } + const templateRoot = resolve(root, 'cli/templates'); + for ( + const entry of await readdir(templateRoot, { + recursive: true, + withFileTypes: true, + }) + ) { + if (!entry.isFile()) continue; + const file = resolve(entry.parentPath, entry.name); + required.add(`dist/cli/templates/${file.slice(templateRoot.length + 1)}`); + } + return [...required].sort(); +} + +function packFiles(root: string): Set { + const result = spawnSync('npm', ['pack', '--dry-run', '--json'], { + cwd: root, + encoding: 'utf8', + }); + if (result.status !== 0) { + throw new Error(`npm pack failed:\n${result.stderr || result.stdout}`); + } + const start = result.stdout.indexOf('['); + const end = result.stdout.lastIndexOf(']'); + if (start < 0 || end <= start) { + throw new Error(`npm pack produced no JSON:\n${result.stdout}`); + } + const entries = JSON.parse( + result.stdout.slice(start, end + 1), + ) as PackEntry[]; + if (entries.length !== 1) { + throw new Error(`Expected one package entry, got ${entries.length}`); + } + return new Set(entries[0].files.map((file) => file.path)); +} +const root = resolve(Deno.args[0] ?? '.'); +const shipped = packFiles(root); +const missing = (await requiredShipPaths(root)).filter((file) => + !shipped.has(file) +); +if (missing.length > 0) { + throw new Error(`npm archive is missing:\n${missing.join('\n')}`); +} +log({ + severity: 'INFO', + message: `npm archive contains all ${shipped.size} required files`, +}); diff --git a/tests/cli-compile.test.ts b/tests/cli-compile.test.ts index 40ee8cf4..43a35d30 100644 --- a/tests/cli-compile.test.ts +++ b/tests/cli-compile.test.ts @@ -8,6 +8,7 @@ */ import { TEST, type TestSuite } from './mod.ts'; +import { log } from '../logging/log.ts'; import { assertEquals, assertExists, @@ -17,12 +18,15 @@ import { import * as path from '../base/path.ts'; import { isBrowser, isNode } from '../base/common.ts'; import { + mkdir, pathExists, readTextFile, writeTextFile, } from '../base/json-log/file-impl.ts'; +import { readdir, realpath, symlink } from 'node:fs/promises'; import { bundleServerForSEA, + denoExecutableName, denoTarget, targetFromOSArch, } from '../cli/compile.ts'; @@ -31,12 +35,184 @@ import { goatEntryPoints } from '../cli/link.ts'; import type { Plugin } from 'esbuild'; import { getRuntime } from '../base/runtime/index.ts'; import { cli } from '../base/development.ts'; +import { + assertImportsWork, + assertScaffoldTemplates, + type DenoInfo, + denoInfo, + denoInfoProjectRoot, +} from './cli-template-utils.ts'; + +async function readJsonFile(filePath: path.PosixPath): Promise { + const text = await readTextFile(filePath); + assertExists(text, `Expected JSON file at ${filePath}`); + return JSON.parse(text) as T; +} + +/** + * Fails if the scaffold resolves GoatDB from a registry instead of the checkout. + * This is the regression guard for the E2E installing the published package. + */ +async function assertLocalGoatDB( + testDir: string, + goatdbRoot: string, +): Promise { + if (getRuntime().id === 'deno') { + const denoJson = await readJsonFile<{ + imports?: Record; + }>(path.join(testDir, 'deno.json')); + const goatdbImports = Object.entries(denoJson.imports ?? {}).filter(( + [key], + ) => key === '@goatdb/goatdb' || key.startsWith('@goatdb/goatdb/')); + assertTrue(goatdbImports.length > 0, 'Expected GoatDB import mappings'); + for (const [key, value] of goatdbImports) { + assertTrue( + value.startsWith('./vendor/goatdb/'), + `${key} must point at the local checkout, got ${value}`, + ); + assertTrue( + !value.startsWith('jsr:@goatdb/goatdb'), + `${key} must not resolve the published JSR package`, + ); + } + assertEquals( + await Deno.realPath(path.join(testDir, 'vendor/goatdb')), + await Deno.realPath(goatdbRoot), + 'vendor/goatdb must resolve to the checkout', + ); + return; + } + + const projectPkg = await readJsonFile<{ + dependencies?: Record; + }>(path.join(testDir, 'package.json')); + const dependency = projectPkg.dependencies?.['@goatdb/goatdb']; + assertExists(dependency, 'Expected @goatdb/goatdb dependency'); + assertTrue( + dependency.startsWith('file:'), + `@goatdb/goatdb must use the local file protocol, got ${dependency}`, + ); + const installedPkg = await readJsonFile<{ version: string }>( + path.join(testDir, 'node_modules/@goatdb/goatdb/package.json'), + ); + const checkoutPkg = await readJsonFile<{ version: string }>( + path.join(goatdbRoot, 'package.json'), + ); + assertEquals( + installedPkg.version, + checkoutPkg.version, + 'Installed GoatDB must be the checkout, not the published package', + ); +} + +/** + * Links the checkout's installed dependencies into the generated project. + * + * WHY: The E2E must resolve the current checkout and its pinned local + * dependencies. Running `npm install` here would make the test depend on + * registry availability and a published dependency graph. + */ +async function linkLocalDependencies( + projectDir: string, + repoRoot: string, +): Promise { + const sourceRoot = path.join(repoRoot, 'node_modules'); + const targetRoot = path.join(projectDir, 'node_modules'); + await mkdir(targetRoot); + + const linkDir = async (source: string, target: string): Promise => { + const resolved = await realpath(source); + await symlink( + resolved, + target, + process.platform === 'win32' ? 'junction' : 'dir', + ); + }; + + for (const entry of await readdir(sourceRoot, { withFileTypes: true })) { + if (entry.name.startsWith('.')) continue; + const source = path.join(sourceRoot, entry.name); + if (entry.name.startsWith('@')) { + const targetScope = path.join(targetRoot, entry.name); + await mkdir(targetScope); + for (const child of await readdir(source, { withFileTypes: true })) { + if (child.name.startsWith('.')) continue; + // The checkout is linked below, never an installed copy. + if (entry.name === '@goatdb' && child.name === 'goatdb') continue; + await linkDir( + path.join(source, child.name), + path.join(targetScope, child.name), + ); + } + } else { + await linkDir(source, path.join(targetRoot, entry.name)); + } + } + + // The package under test is the checkout, never an installed copy. + await linkDir(repoRoot, path.join(targetRoot, '@goatdb/goatdb')); +} + +/** + * Adds the template-only npm imports that GoatDB does not export. `linkGoatDB` + * injects the checkout's own import map, so only these two remain external. + * Specs come from the scaffold's own list, so the E2E resolves the same ranges + * `init` installs. + */ +async function addDenoTemplateImports( + testDir: string, + npmDependencies: Readonly>, +): Promise { + const denoJsonPath = path.join(testDir, 'deno.json'); + const denoJson = await readJsonFile<{ + imports?: Record; + }>(denoJsonPath); + const imports = denoJson.imports ?? {}; + const reactDomClient = npmDependencies['react-dom/client']; + const typesReact = npmDependencies['@types/react']; + assertExists(reactDomClient, 'Missing react-dom/client scaffold spec'); + assertExists(typesReact, 'Missing @types/react scaffold spec'); + imports['react-dom/client'] ??= reactDomClient; + imports['@types/react'] ??= typesReact; + denoJson.imports = imports; + await writeTextFile(denoJsonPath, JSON.stringify(denoJson, null, 2) + '\n'); +} + +/** + * Asserts react and react-dom resolve to one version. + * + * WHY: cli/init.ts keeps them aligned with matching ranges. A split resolves at + * runtime with "Incompatible React versions", and no other source test checks + * the generated graph. + */ +function assertReactVersionParity(info: DenoInfo): void { + const versionOf = (name: string): string => { + const versions = new Set( + Object.values(info.npmPackages) + .filter((pkg) => pkg.name === name) + .map((pkg) => pkg.version), + ); + assertEquals( + versions.size, + 1, + `Expected exactly one resolved ${name} version, got ${ + [...versions].join(', ') || 'none' + }`, + ); + return [...versions][0]; + }; + assertEquals( + versionOf('react'), + versionOf('react-dom'), + 'react and react-dom must resolve to one version (cli/init.ts parity)', + ); +} export default function setupCliCompileTests() { TEST( 'CLI-Compile', 'should compute target OS/arch correctly', - async () => { + () => { // Skip in browser if (isBrowser()) return; @@ -69,7 +245,7 @@ export default function setupCliCompileTests() { TEST( 'CLI-Compile', 'should reject unsupported denoTarget windows-arm64', - async () => { + () => { if (isBrowser()) return; assertThrows( () => denoTarget('windows', 'arm64'), @@ -81,7 +257,7 @@ export default function setupCliCompileTests() { TEST( 'CLI-Compile', 'should map denoTarget for all supported platforms', - async () => { + () => { if (isBrowser()) return; assertEquals(denoTarget('mac', 'x64'), 'x86_64-apple-darwin'); assertEquals(denoTarget('mac', 'arm64'), 'aarch64-apple-darwin'); @@ -91,6 +267,23 @@ export default function setupCliCompileTests() { }, ); + TEST( + 'CLI-Compile', + 'denoExecutableName appends .exe only for Windows targets', + () => { + if (isBrowser()) return; + // Deno appends `.exe` based on the TARGET OS, not the host, so this + // cross-platform check guards the path for cross-compiled Windows + // binaries without running a Windows host. + assertEquals(denoExecutableName('app', 'mac-arm64'), 'app-mac-arm64'); + assertEquals(denoExecutableName('app', 'linux-x64'), 'app-linux-x64'); + assertEquals( + denoExecutableName('app', 'windows-x64'), + 'app-windows-x64.exe', + ); + }, + ); + TEST( 'CLI-Compile', 'goatEntryPoints should match deno.json exports', @@ -162,13 +355,12 @@ export default function setupCliCompileTests() { }, ); - // Heavy E2E test — resource-intensive, recommended to run in isolation + // Heavy E2E test - resource-intensive, recommended to run in isolation. // This test is expensive as it: // 1. Bootstraps a full project - // 2. Installs dependencies + // 2. Links the checkout's installed dependencies // 3. Compiles to binary - // 4. Starts the server - // 5. Verifies HTTP responses + // 4. Runs the binary and verifies its CLI surface // // To run: deno task test --test="should compile executable" TEST( @@ -177,24 +369,27 @@ export default function setupCliCompileTests() { async (ctx: TestSuite) => { // Skip in browser - compilation not supported if (isBrowser()) { - console.log('Skipping E2E compile test in browser'); + log({ + severity: 'INFO', + message: 'Skipping E2E compile test in browser', + }); return; } const runtime = getRuntime(); // This is a heavy E2E test - mark it as such - console.log('Running E2E compile test (this may take a while)...'); + log({ severity: 'INFO', message: 'Running E2E compile test' }); const testDir = await ctx.tempDir('compile-e2e'); - // 1. Bootstrap a project - console.log('Bootstrapping project...'); + // 1. Bootstrap without touching the registry. The generated project + // must resolve GoatDB from this checkout, never from the published + // package; otherwise the E2E proves nothing about the current code. + log({ severity: 'INFO', message: 'Bootstrapping project' }); const initModule = await import('../cli/init.ts'); await initModule.bootstrapProject({ targetDir: testDir, - // Compile local sources, not a published GoatDB artifact. Linking below - // supplies its import map before external app dependencies are installed. skipDependencies: true, }); @@ -204,40 +399,73 @@ export default function setupCliCompileTests() { 'Project should be bootstrapped', ); - // 2. Link to local GoatDB sources instead of published package - // This ensures we test against the current codebase, not the published version - console.log('Linking to local GoatDB sources...'); + // Templates are copied before linking. Linking patches config and + // .gitignore, so assert the scaffold effect first. + await assertScaffoldTemplates( + testDir, + runtime.id === 'deno' ? 'deno' : 'node', + runtime.getCWD(), + ); + + // 2. Link the checkout before installing anything, so installation can + // only observe the local source. + log({ severity: 'INFO', message: 'Linking to local GoatDB sources' }); const linkModule = await import('../cli/link.ts'); - // Get path to GoatDB repo root // In bundled Node.js, import.meta.url points to bundled code, not original source. // Use the runtime's CWD which should be the goatdb repo root during tests. const goatdbRoot = runtime.getCWD(); - await linkModule.linkGoatDB(goatdbRoot, testDir); if (runtime.id === 'deno') { - const install = await cli( - 'deno', - 'add', - 'npm:react-dom@19.0.0/client', - { - cwd: testDir, - }, + await addDenoTemplateImports( + testDir, + initModule.kDenoTemplateNpmDependencies, ); - assertEquals(install.exitCode, 0, install.result); + } else { + log({ severity: 'INFO', message: 'Linking local dependencies' }); + await linkLocalDependencies(testDir, goatdbRoot); } - // For Node.js, reinstall to update node_modules with local link - if (runtime.id === 'node') { - console.log('Reinstalling dependencies with local link...'); - const installResult = await cli('npm', 'install', { cwd: testDir }); - if (installResult.exitCode !== 0) { - throw new Error(`npm install failed: ${installResult.result}`); - } + await assertLocalGoatDB(testDir, goatdbRoot); + + // Import execution, not only graph resolution: the generated project + // must load React and GoatDB without throwing. + await assertImportsWork( + testDir, + runtime.id === 'deno' ? 'deno' : 'node', + ); + + // Resolve the real graph, not only the config that describes it. + if (runtime.id === 'deno') { + const entry = 'client/index.tsx'; + const info = await denoInfo(testDir, entry); + assertReactVersionParity(info); + // WHY: `deno info` reports paths in its own cwd spelling. Do not + // canonicalize the temp root with `Deno.realPath` here: Windows + // expands 8.3 aliases (RUNNER~1 -> runneradmin) while `deno info` + // keeps the short spelling. + assertEquals(info.roots.length, 1, 'deno info must report one root'); + const vendorRoot = path.join( + denoInfoProjectRoot(info, entry), + 'vendor/goatdb', + ); + assertTrue( + info.modules.some((module) => + module.local !== undefined && + path.isWithin(vendorRoot, module.local) + ), + 'Generated graph must resolve GoatDB from vendor/goatdb', + ); + assertTrue( + !info.modules.some((module) => + module.specifier.includes('jsr:@goatdb/goatdb') + ), + 'Generated graph must not resolve the published JSR package', + ); } // 3. Compile the project - console.log('Compiling project...'); + log({ severity: 'INFO', message: 'Compiling project' }); const { compile } = await import('../cli/compile.ts'); // Determine server entry based on runtime @@ -255,7 +483,7 @@ export default function setupCliCompileTests() { }); }, }; - await compile({ + const binaryPath = await compile({ buildDir: path.join(testDir, 'build'), serverEntry, jsPath: path.join(testDir, 'client/index.tsx'), @@ -271,23 +499,18 @@ export default function setupCliCompileTests() { assertEquals(pluginBuilds, 1, 'Compile must invoke configured plugin'); - // 4. Verify binary exists - const osName = runtime.getOS(); - - let binaryName: string; - if (runtime.id === 'deno') { - binaryName = `test-app-${targetFromOSArch()}`; - } else { - binaryName = osName === 'windows' ? 'test-app.exe' : 'test-app'; - } - - const binaryPath = path.join(testDir, 'build', binaryName); + // 4. Verify binary exists. `compile` returns the compiler's real output + // path (including `.exe` for Windows targets), so the test never + // re-derives the platform-specific name. assertTrue( - await pathExists(binaryPath), + await pathExists(path.parsePath(binaryPath)), `Binary should exist at ${binaryPath}`, ); - console.log(`Binary compiled successfully: ${binaryPath}`); + log({ + severity: 'INFO', + message: `Binary compiled successfully: ${binaryPath}`, + }); // 5. Verify binary is executable (basic sanity check) const { result: helpOutput, exitCode } = await cli( @@ -303,9 +526,10 @@ export default function setupCliCompileTests() { helpOutput.includes('--help') || helpOutput.includes('Options'), 'Binary should respond to --help', ); - console.log( - 'E2E compile test passed: Binary compiles and is executable', - ); + log({ + severity: 'INFO', + message: 'E2E compile test passed: Binary compiles and is executable', + }); }, ); } diff --git a/tests/cli-init.test.ts b/tests/cli-init.test.ts index 20e03bc2..5a52784d 100644 --- a/tests/cli-init.test.ts +++ b/tests/cli-init.test.ts @@ -20,6 +20,7 @@ import { readTextFile, writeTextFile, } from '../base/json-log/file-impl.ts'; +import { assertScaffoldTemplates, readJson } from './cli-template-utils.ts'; /** * Helper function to check if a file exists @@ -28,11 +29,37 @@ async function fileExists(filePath: path.PosixPath): Promise { return await pathExists(filePath); } +async function invalidInstallProject(ctx: TestSuite): Promise { + const testDir = await ctx.tempDir('install-failure'); + const configName = isDeno() ? 'deno.json' : 'package.json'; + // Invalid JSON fails before registry access, with a real manager diagnostic. + await writeTextFile(path.join(testDir, configName), '{ invalid json'); + return testDir; +} + +function assertInstallFailure(message: string): void { + const command = isDeno() ? 'deno add' : 'npm install'; + const failure = message.match( + /failed with exit code ([1-9]\d*):\s*([\s\S]+)/, + ); + assertTrue(message.includes(command), `Missing command: ${message}`); + assertExists(failure, `Missing numeric nonzero exit or output: ${message}`); + const diagnostic = failure[2]; + assertTrue( + isDeno() + ? /parse|syntax|expected/i.test(diagnostic) && + diagnostic.includes('deno.json') + : diagnostic.includes('EJSONPARSE') && + diagnostic.includes('package.json'), + `Missing package-manager JSON diagnostic: ${diagnostic}`, + ); +} + export default function setupCliInitTests() { TEST( 'CLI-Init', 'should detect runtime correctly', - async (ctx: TestSuite) => { + () => { // Test runtime detection const runtime = isDeno() ? 'deno' : isNode() ? 'node' : 'browser'; assertTrue( @@ -120,6 +147,81 @@ export default function setupCliInitTests() { }, ); + TEST( + 'CLI-Init', + 'generated files match runtime templates byte-for-byte', + async (ctx: TestSuite) => { + const testDir = await ctx.tempDir('init-template-bytes'); + const initModule = await import('../cli/init.ts'); + await initModule.bootstrapProject({ + targetDir: testDir, + skipDependencies: true, + }); + await assertScaffoldTemplates( + testDir, + isDeno() ? 'deno' : 'node', + await getCWD(), + ); + }, + ); + + TEST( + 'CLI-Init', + 'generated config preserves the template contract', + async (ctx: TestSuite) => { + const testDir = await ctx.tempDir('init-config-contract'); + const root = await getCWD(); + const initModule = await import('../cli/init.ts'); + await initModule.bootstrapProject({ + targetDir: testDir, + skipDependencies: true, + }); + + if (isDeno()) { + const actual = await readJson>( + path.join(testDir, 'deno.json'), + ); + const template = await readJson>( + path.join(root, 'cli/templates/deno/deno.json'), + ); + assertExists(actual, 'Generated deno.json missing'); + assertExists(template, 'Deno template missing'); + assertEquals(actual.tasks, template.tasks, 'deno.json tasks drift'); + assertEquals( + actual.compilerOptions, + template.compilerOptions, + 'deno.json compilerOptions drift', + ); + assertEquals(actual.version, template.version); + } else { + const actual = await readJson<{ + dependencies?: Record; + devDependencies?: Record; + engines?: Record; + type?: string; + }>(path.join(testDir, 'package.json')); + const template = await readJson<{ + dependencies?: Record; + }>(path.join(root, 'cli/templates/node/package.json')); + assertExists(actual, 'Generated package.json missing'); + assertExists(template, 'Node template missing'); + assertEquals( + actual.dependencies, + template.dependencies, + 'package.json dependencies drift', + ); + assertEquals( + template.dependencies?.react, + template.dependencies?.['react-dom'], + 'react and react-dom ranges must match', + ); + assertEquals(actual.type, 'module'); + assertEquals(actual.engines?.node, '>=24.0.0'); + assertEquals(actual.devDependencies?.['@types/node'], '^24.0.0'); + } + }, + ); + TEST( 'CLI-Init', 'should use correct import extensions', @@ -164,34 +266,6 @@ export default function setupCliInitTests() { }, ); - TEST( - 'CLI-Init', - 'should create correct directory structure', - async (ctx: TestSuite) => { - const testDir = await ctx.tempDir('init-structure'); - - const initModule = await import('../cli/init.ts'); - await initModule.bootstrapProject({ - targetDir: testDir, - skipDependencies: true, - }); - - // Verify directory structure exists - assertTrue( - await pathExists(path.join(testDir, 'client')), - 'client directory should exist', - ); - assertTrue( - await pathExists(path.join(testDir, 'server')), - 'server directory should exist', - ); - assertTrue( - await pathExists(path.join(testDir, 'common')), - 'common directory should exist', - ); - }, - ); - TEST( 'CLI-Init', 'should not overwrite existing files', @@ -235,43 +309,37 @@ export default function setupCliInitTests() { skipDependencies: true, }); - // Verify HTML template has basic structure - const htmlContent = await readTextFile( - path.join(testDir, 'client/index.html'), - ); - assertTrue( - htmlContent?.includes('') || false, - 'HTML should have doctype', - ); - assertTrue( - htmlContent?.includes('
') || false, - 'HTML should have root div', - ); + const expectations = [ + ['client/index.html', '
'], + ['client/app.tsx', 'useDBReady'], + ['common/schema.ts', 'registerSchemas'], + ] as const; + for (const [file, marker] of expectations) { + const content = await readTextFile(path.join(testDir, file)); + assertTrue( + content?.includes(marker) || false, + `${file} must contain ${marker}`, + ); + } + }, + ); - // Verify React app template - const appContent = await readTextFile( - path.join(testDir, 'client/app.tsx'), - ); - assertTrue( - appContent?.includes('export function App') || false, - 'App component should be exported', - ); - assertTrue( - appContent?.includes('useDBReady') || false, - 'App should use GoatDB hook', - ); + TEST( + 'CLI-Init', + 'dependency install failures are explicit', + async (ctx: TestSuite) => { + const testDir = await invalidInstallProject(ctx); - // Verify schema template - const schemaContent = await readTextFile( - path.join(testDir, 'common/schema.ts'), - ); - assertTrue( - schemaContent?.includes('kSchemaMyItem') || false, - 'Schema should define example item', - ); - assertTrue( - schemaContent?.includes('registerSchemas') || false, - 'Schema should export registration function', + const initModule = await import('../cli/init.ts'); + let error: unknown; + try { + await initModule.bootstrapProject({ targetDir: testDir }); + } catch (caught) { + error = caught; + } + + assertInstallFailure( + error instanceof Error ? error.message : String(error), ); }, ); diff --git a/tests/cli-package.test.ts b/tests/cli-package.test.ts new file mode 100644 index 00000000..82b4379f --- /dev/null +++ b/tests/cli-package.test.ts @@ -0,0 +1,352 @@ +/** + * Built artifact contract for the CLI. + * + * WHY: Source-tree tests cannot see missing dist files, a wrong shipped + * manifest, or an entry point that resolves but cannot load. This suite builds + * the current checkout and loads the build outputs in place. + * + * It must not install the package or resolve it from a registry. Registry + * checks validate the publication process; they do not validate this checkout. + * + * Gated because it runs the production build. Run with: + * GOATDB_TEST_PACKAGE=1 deno task test:package + */ + +import { TEST, type TestSuite } from './mod.ts'; +import { log } from '../logging/log.ts'; +import { assertEquals, assertExists, assertTrue } from './asserts.ts'; +import * as path from '../base/path.ts'; +import { isBrowser, isNode } from '../base/common.ts'; +import { getEnvVar, isWindows } from '../base/os.ts'; +import { cli } from '../base/development.ts'; +import { getRuntime } from '../base/runtime/index.ts'; +import { + mkdir, + readTextFile, + writeTextFile, +} from '../base/json-log/json-log.ts'; +import { chmod } from 'node:fs/promises'; +import { builtinModules } from 'node:module'; +import { pathToFileURL } from 'node:url'; +import { + type NpmManifest, + type ProductionManifest, + productionManifest, +} from '../scripts/npm-manifest.ts'; +import { + assertScaffoldTemplates, + assertTemplateTree, + readJson, +} from './cli-template-utils.ts'; + +/** + * Public API contract: each published subpath must expose its documented + * symbol. A target that exists but exports the wrong surface must fail. + */ +const kPublicExports: Record = { + '.': 'GoatDB', + './react': 'useDB', + './server': 'Server', + './server/build': 'compile', + './link': 'linkGoatDB', +}; + +function packageTestsEnabled(): boolean { + return getEnvVar('GOATDB_TEST_PACKAGE') === '1'; +} + +/** File-only existence probe; every caller checks a file, never a directory. */ +async function fileExists(file: path.PosixPath): Promise { + return (await readTextFile(file)) !== undefined; +} + +function assertCliFailure(output: string): void { + assertTrue( + output.includes('Error during project initialization:'), + `Missing CLI failure prefix:\n${output}`, + ); + assertTrue( + output.includes('EJSONPARSE') && output.includes('package.json'), + `Missing package-manager diagnostic:\n${output}`, + ); +} + +async function readVersion(repoRoot: string): Promise { + const config = await readJson<{ version: string }>( + path.join(repoRoot, 'deno.json'), + ); + assertExists(config?.version, 'deno.json version missing'); + return config.version; +} + +function binTarget(manifest: NpmManifest): string { + const bin = manifest.bin as Record | undefined; + const target = bin?.goatdb; + assertExists(target, 'npm bin target missing'); + return target; +} + +/** Asserts every shipped target exists in the current build. */ +async function assertManifestTargets( + repoRoot: string, + manifest: ProductionManifest, +): Promise { + const entries = Object.entries(manifest.exports); + for (const [subpath, entry] of entries) { + for (const target of [entry.import, entry.types]) { + assertTrue( + await fileExists(path.join(repoRoot, target)), + `Missing build target for ${subpath}: ${target}`, + ); + } + } + for (const subpath of Object.keys(kPublicExports)) { + assertTrue( + entries.some(([entrySubpath]) => entrySubpath === subpath), + `Missing public export: ${subpath}`, + ); + } + const target = binTarget(manifest); + assertTrue( + await fileExists(path.join(repoRoot, target)), + `Missing npm bin target: ${target}`, + ); +} + +/** Loads every public entry and proves its documented symbol is present. */ +async function assertExportsLoad( + repoRoot: string, + manifest: ProductionManifest, +): Promise { + for (const [subpath, entry] of Object.entries(manifest.exports)) { + const module = await import( + pathToFileURL(path.join(repoRoot, entry.import)).href + ); + assertTrue( + Object.keys(module).length > 0, + `Entry point exported nothing: ${subpath}`, + ); + const expected = kPublicExports[subpath]; + if (expected !== undefined) { + assertTrue( + expected in module, + `Entry point must export ${expected}: ${subpath}`, + ); + } + } +} + +function declaredPackages(manifest: NpmManifest): Set { + const declared = new Set(); + for ( + const field of [ + 'dependencies', + 'peerDependencies', + 'optionalDependencies', + ] + ) { + const deps = manifest[field]; + if (typeof deps !== 'object' || deps === null) continue; + for (const name of Object.keys(deps)) declared.add(name); + } + return declared; +} + +function packageName(specifier: string): string { + if (specifier.startsWith('@')) { + return specifier.split('/').slice(0, 2).join('/'); + } + return specifier.split('/')[0]; +} + +/** Import and re-export specifiers, including dynamic imports. */ +const kImportSpecifier = + /(?:^|\n)\s*(?:import|export)\s+[^'"]*?from\s*['"]([^'"]+)['"]|(?:^|\n)\s*import\s*['"]([^'"]+)['"]|\bimport\s*\(\s*['"]([^'"]+)['"]\s*\)/gm; + +async function importSpecifiers(file: path.PosixPath): Promise { + const text = await readTextFile(file); + assertExists(text, `Unable to read dist file: ${file}`); + return [...text.matchAll(kImportSpecifier)].flatMap((match) => + match[1] ?? match[2] ?? match[3] ?? [] + ); +} + +/** Walks the dist graph so transitive bare imports are checked too. */ +async function distBareImports( + entryFiles: path.PosixPath[], +): Promise> { + const visited = new Set(); + const bare = new Set(); + + async function visit(file: path.PosixPath): Promise { + if (visited.has(file)) return; + visited.add(file); + for (const specifier of await importSpecifiers(file)) { + if (specifier.startsWith('.')) { + await visit(path.join(path.dirname(file), specifier)); + } else if ( + !specifier.startsWith('/') && !/^[a-z]+:/i.test(specifier) + ) { + const name = packageName(specifier); + if (!builtinModules.includes(name)) bare.add(name); + } + } + } + + for (const entry of entryFiles) await visit(entry); + return bare; +} + +async function assertDistImports( + repoRoot: string, + manifest: ProductionManifest, +): Promise { + const entries = Object.entries(manifest.exports).map(([, entry]) => + path.join(repoRoot, entry.import) + ); + entries.push(path.join(repoRoot, binTarget(manifest))); + const bare = await distBareImports(entries); + assertTrue(bare.size > 0, 'No imports found in the dist entry points'); + const declared = declaredPackages(manifest); + for (const name of bare) { + assertTrue( + declared.has(name), + `Dist imports undeclared package: ${name}`, + ); + } +} + +/** Fake npm proves the bin reaches the install step without the registry. */ +async function writeNpmShim( + dir: path.PosixPath, + marker: path.PosixPath, +): Promise { + await mkdir(dir); + const shell = path.join(dir, 'npm'); + assertTrue( + await writeTextFile( + shell, + `#!/bin/sh\nprintf ok > "$GOATDB_FAKE_NPM_MARKER"\nexit 0\n`, + ), + 'Unable to write npm shim', + ); + await chmod(shell, 0o755); + assertTrue( + await writeTextFile( + path.join(dir, 'npm.cmd'), + `@echo off\r\n> "%GOATDB_FAKE_NPM_MARKER%" echo ok\r\nexit /b 0\r\n`, + ), + 'Unable to write npm.cmd shim', + ); + assertTrue(await fileExists(marker) === false, 'Shim marker already exists'); +} + +/** Runs the real npm bin and proves it scaffolds from the shipped templates. */ +async function assertDistBinInit( + ctx: TestSuite, + repoRoot: string, + manifest: NpmManifest, +): Promise { + const targetDir = await ctx.tempDir('dist-bin-init'); + const shimDir = await ctx.tempDir('npm-shim'); + const marker = path.join(shimDir, 'invoked'); + await writeNpmShim(shimDir, marker); + const separator = isWindows() ? ';' : ':'; + const result = await cli( + 'node', + path.join(repoRoot, binTarget(manifest)), + 'init', + targetDir, + { + cwd: repoRoot, + env: { + PATH: `${shimDir}${separator}${process.env.PATH ?? ''}`, + GOATDB_FAKE_NPM_MARKER: marker, + }, + timeout: 120_000, + }, + ); + assertEquals(result.exitCode, 0, result.result); + assertTrue( + await fileExists(marker), + `Bin did not invoke npm:\n${result.result}`, + ); + await assertScaffoldTemplates(targetDir, 'node', repoRoot); +} + +async function assertBuiltCli( + repoRoot: string, + manifest: NpmManifest, +): Promise { + const result = await cli( + 'node', + path.join(repoRoot, binTarget(manifest)), + '--help', + { cwd: repoRoot, timeout: 120_000 }, + ); + assertEquals(result.exitCode, 0, result.result); + assertTrue( + result.result.includes('Commands:') && + result.result.includes('init [dir]'), + `Unexpected help output:\n${result.result}`, + ); +} + +async function assertCliFailureContract( + ctx: TestSuite, + repoRoot: string, + manifest: NpmManifest, +): Promise { + const invalid = await ctx.tempDir('invalid-app'); + await writeTextFile(path.join(invalid, 'package.json'), '{ invalid json'); + const result = await cli( + 'node', + path.join(repoRoot, binTarget(manifest)), + 'init', + invalid, + { cwd: repoRoot, timeout: 120_000 }, + ); + assertEquals(result.exitCode, 1, result.result); + assertCliFailure(result.result); +} + +export default function setupCliPackageTests() { + TEST( + 'CLI-Package', + 'built artifact ships templates and loads every public entry point', + async (ctx) => { + if (isBrowser() || !isNode()) return; + if (!packageTestsEnabled()) { + log({ + severity: 'INFO', + message: 'Skipping CLI-Package (set GOATDB_TEST_PACKAGE=1 to run)', + }); + return; + } + const repoRoot = getRuntime().getCWD(); + const build = await cli('npm', 'run', 'build:npm', { + cwd: repoRoot, + timeout: 300_000, + }); + assertEquals(build.exitCode, 0, build.result); + await assertTemplateTree( + path.join(repoRoot, 'dist/cli/templates'), + repoRoot, + ); + + const checkout = await readJson( + path.join(repoRoot, 'package.json'), + ); + assertExists(checkout, 'Checkout package.json missing'); + const version = await readVersion(repoRoot); + const manifest = productionManifest(checkout, version); + + await assertManifestTargets(repoRoot, manifest); + await assertExportsLoad(repoRoot, manifest); + await assertDistImports(repoRoot, manifest); + await assertDistBinInit(ctx, repoRoot, manifest); + await assertBuiltCli(repoRoot, manifest); + await assertCliFailureContract(ctx, repoRoot, manifest); + }, + ); +} diff --git a/tests/cli-template-utils.ts b/tests/cli-template-utils.ts new file mode 100644 index 00000000..308e71a7 --- /dev/null +++ b/tests/cli-template-utils.ts @@ -0,0 +1,208 @@ +/** + * Shared assertions for CLI scaffold contracts. + * + * WHY: Scaffold tests must assert the generated project, not the commands that + * produced it. Exit codes are preconditions; files, resolved modules, and + * runtime behavior are the effects under test. + */ + +import * as path from '../base/path.ts'; +import { cli } from '../base/development.ts'; +import { + getEsbuild, + stopBackgroundCompiler, +} from '../base/build-dependencies.ts'; +import { + readDir, + readTextFile, + writeTextFile, +} from '../base/json-log/json-log.ts'; +import { templateTargetPath } from '../cli/template-manifest.ts'; +import { assertEquals, assertExists, assertTrue } from './asserts.ts'; + +export type CliTemplateRuntime = 'deno' | 'node'; + +import { type DenoInfo, parseDenoInfo } from './deno-info.ts'; +export { + type DenoInfo, + denoInfoProjectRoot, + parseDenoInfo, +} from './deno-info.ts'; + +/** Recursive walk over template files. */ +async function* walkFiles( + dir: path.PosixPath, +): AsyncGenerator { + for (const entry of await readDir(dir)) { + const full = path.join(dir, entry.name); + if (entry.isDirectory) { + yield* walkFiles(full); + } else if (entry.isFile) { + yield full; + } + } +} + +/** + * Maps generated project paths to template source files for one runtime. + * Skipped config files are patched by bootstrap, so they are asserted + * structurally by their own tests. + */ +async function templateFiles( + runtime: CliTemplateRuntime, + repoRoot: string, +): Promise> { + const templateRoot = path.join(repoRoot, 'cli/templates'); + const files = new Map(); + for await (const source of walkFiles(templateRoot)) { + const relative = source.slice(templateRoot.length + 1); + if ( + !relative.startsWith('shared/') && + !relative.startsWith(`${runtime}/`) + ) { + continue; + } + const target = templateTargetPath(relative, runtime); + const existing = files.get(target); + if (existing !== undefined) { + throw new Error( + `Template collision for ${target}: ${existing} and ${source}`, + ); + } + files.set(target, source); + } + return files; +} + +/** Asserts every static template landed with identical bytes. */ +export async function assertScaffoldTemplates( + targetDir: string, + runtime: CliTemplateRuntime, + repoRoot: string, +): Promise { + const files = await templateFiles(runtime, repoRoot); + assertTrue(files.size > 0, 'No template files found'); + for (const [target, source] of files) { + if (target === 'deno.json' || target === 'package.json') continue; + const expected = await readTextFile(source); + assertExists(expected, `Missing template source: ${source}`); + const actual = await readTextFile(path.join(targetDir, target)); + assertExists(actual, `Missing generated file: ${target}`); + assertEquals(actual, expected, `Template content drift: ${target}`); + } +} + +/** Lists every template path relative to cli/templates. */ +export async function allTemplateRelativePaths( + repoRoot: string, +): Promise { + const root = path.join(repoRoot, 'cli/templates'); + const paths: string[] = []; + for await (const source of walkFiles(root)) { + paths.push(source.slice(root.length + 1)); + } + return paths.sort(); +} + +/** Asserts a copied template tree matches cli/templates byte-for-byte. */ +export async function assertTemplateTree( + targetRoot: string, + repoRoot: string, +): Promise { + const sourceRoot = path.join(repoRoot, 'cli/templates'); + const paths = await allTemplateRelativePaths(repoRoot); + assertTrue(paths.length > 0, 'No template files found'); + for (const relative of paths) { + const expected = await readTextFile(path.join(sourceRoot, relative)); + const actual = await readTextFile(path.join(targetRoot, relative)); + assertExists(expected, `Missing template source: ${relative}`); + assertExists(actual, `Missing copied template: ${relative}`); + assertEquals(actual, expected, `Copied template drift: ${relative}`); + } +} + +/** + * Builds and runs a probe that imports the scaffold's public modules. + * + * WHY: A resolvable graph can still throw on import (missing export or split + * React runtime). Node cannot load the checkout's .ts exports directly, so the + * probe is bundled exactly as a Node app would be before it runs. + */ +export async function assertImportsWork( + projectDir: path.PosixPath, + runtime: CliTemplateRuntime, +): Promise { + const sourcePath = path.join(projectDir, 'import-probe.ts'); + const probeName = runtime === 'deno' ? 'import-probe.ts' : 'import-probe.mjs'; + const probePath = path.join(projectDir, probeName); + await writeTextFile( + sourcePath, + [ + "import { createRoot } from 'react-dom/client';", + "import { DataRegistry, GoatDB } from '@goatdb/goatdb';", + "import { useDBReady } from '@goatdb/goatdb/react';", + 'console.log(JSON.stringify({', + ' createRoot: typeof createRoot,', + ' DataRegistry: typeof DataRegistry,', + ' GoatDB: typeof GoatDB,', + ' useDBReady: typeof useDBReady,', + '}));', + ].join('\n'), + ); + if (runtime === 'node') { + const esbuild = await getEsbuild(); + try { + await esbuild.build({ + entryPoints: [sourcePath], + outfile: probePath, + bundle: true, + platform: 'node', + format: 'esm', + // Node 24 defines import.meta.main; the bundled probe is the entry, so + // without this the library's CLI branch runs instead of the probe. + define: { 'import.meta.main': 'false' }, + }); + } finally { + await stopBackgroundCompiler(); + } + } + const { result, exitCode } = runtime === 'deno' + ? await cli('deno', 'run', '-A', probeName, { + cwd: projectDir, + timeout: 120_000, + }) + : await cli('node', probeName, { cwd: projectDir, timeout: 120_000 }); + assertEquals(exitCode, 0, `import probe failed:\n${result}`); + const parsed = JSON.parse(result.trim().split('\n').at(-1)!) as Record< + string, + string + >; + for (const name of Object.keys(parsed)) { + assertEquals(parsed[name], 'function', `${name} export missing`); + } +} + +/** Parses `deno info --json` for a generated entry point. */ +export async function denoInfo( + testDir: string, + entry: string, + timeout = 120_000, +): Promise { + const { result, exitCode } = await cli( + 'deno', + 'info', + '--json', + entry, + { cwd: testDir, timeout }, + ); + assertEquals(exitCode, 0, `deno info failed:\n${result}`); + return parseDenoInfo(result); +} + +/** Reads a JSON file and returns undefined when it does not exist. */ +export async function readJson( + file: path.PosixPath, +): Promise { + const text = await readTextFile(file); + return text === undefined ? undefined : JSON.parse(text) as T; +} diff --git a/tests/test-registry.ts b/tests/test-registry.ts index 3ec2f3a4..44777d0b 100644 --- a/tests/test-registry.ts +++ b/tests/test-registry.ts @@ -32,6 +32,7 @@ import setupE2ELatency from './e2e-latency.test.ts'; import setupClusterLatency from './cluster-latency.test.ts'; import setupCliInitTests from './cli-init.test.ts'; import setupCliCompileTests from './cli-compile.test.ts'; +import setupCliPackageTests from './cli-package.test.ts'; import setupCliBuildAssetsTests from './cli-build-assets.test.ts'; import setupPathTests from './path.test.ts'; import setupCliPathNormalizationTests from './cli-path-normalization.test.ts'; @@ -117,6 +118,7 @@ export async function registerAllTests(): Promise { setupSecurityBoundaries(); // Security boundary invariants (auth, sync, signatures) setupGoatRequestTest(); // HTTP request processing setupCliInitTests(); // CLI scaffolding functionality + setupCliPackageTests(); // Built artifact, bin, and template contract setupMergeLCA(); // Lowest Common Ancestor / merge base setupMergeRecord(); // Record merge and schema upgrade setupMergeCorruption(); // Corruption detection via checksums diff --git a/tsconfig.npm.json b/tsconfig.npm.json new file mode 100644 index 00000000..69dc0e4b --- /dev/null +++ b/tsconfig.npm.json @@ -0,0 +1,20 @@ +// scripts/check-npm-entrypoints.ts checks public entrypoint coverage. +{ + "extends": "./tsconfig.node.json", + "compilerOptions": { + "rootDir": ".", + "noEmit": true, + "declaration": true, + "emitDeclarationOnly": false, + "types": ["node", "deno"] + }, + "include": [ + "mod.ts", + "server.ts", + "server-build.ts", + "react/hooks.ts", + "cli/init.ts", + "cli/link.ts", + "types/**/*.d.ts" + ] +} diff --git a/tsup.config.ts b/tsup.config.ts index dca5a55f..408ef4ee 100644 --- a/tsup.config.ts +++ b/tsup.config.ts @@ -1,6 +1,7 @@ import { defineConfig } from 'tsup'; export default defineConfig({ + // scripts/check-npm-entrypoints.ts checks public entrypoint coverage. entry: { mod: 'mod.ts', 'react/hooks': 'react/hooks.ts', diff --git a/types/chokidar.d.ts b/types/chokidar.d.ts new file mode 100644 index 00000000..51d087ce --- /dev/null +++ b/types/chokidar.d.ts @@ -0,0 +1,22 @@ +// Ambient declarations for the optional, untyped chokidar dependency. +// Used by the npm type check (tsconfig.npm.json); tsup does not bundle it. +declare module 'chokidar' { + export interface FSWatcher { + on( + event: 'add' | 'change' | 'unlink', + listener: (path: string) => void, + ): FSWatcher; + close(): void | Promise; + } + + export function watch( + paths: string | string[], + options?: { + ignored?: unknown; + persistent?: boolean; + ignoreInitial?: boolean; + }, + ): FSWatcher; + + export default { watch }; +} diff --git a/types/deno-global.d.ts b/types/deno-global.d.ts deleted file mode 100644 index 96562836..00000000 --- a/types/deno-global.d.ts +++ /dev/null @@ -1,101 +0,0 @@ -// Minimal Deno global stub for cross-runtime source files compiled under -// tsup/Node.js. npm consumers never run on Deno; we only need TypeScript -// to accept Deno.* in both value positions (Deno.serve()) and type positions -// (variable: Deno.HttpServer). -// -// Using `declare namespace` (not `declare const`) so it works as a type -// namespace for annotations like `private _server?: Deno.HttpServer`. -declare namespace Deno { - // ---- Common types used in type-annotation positions ---- - type HttpServer = any; - type ServeHandlerInfo = any; - type CommandOptions = any; - type ChildProcess = any; - type FsFile = any; - type SeekMode = any; - type InspectOptions = any; - - // ---- Constructable classes ---- - class Command { - constructor(command: string, options?: any); - output(): Promise; - spawn(): any; - } - - // ---- Runtime values ---- - const args: readonly string[]; - const pid: number; - const mainModule: string; - function execPath(): string; - function exit(code?: number): never; - function cwd(): string; - function hostname(): string; - function stat(path: string): Promise; - function lstat(path: string): Promise; - function readDir(path: string): AsyncIterable; - function readFile(path: string, options?: any): Promise; - function readTextFile(path: string, options?: any): Promise; - function writeTextFile( - path: string, - data: string, - options?: any, - ): Promise; - function writeFileSync(path: string, data: Uint8Array, options?: any): void; - function copyFile(from: string, to: string): Promise; - function remove(path: string, options?: any): Promise; - function mkdir(path: string, options?: any): Promise; - function makeTempDir(options?: any): Promise; - function open(path: string, options?: any): Promise; - function symlink( - oldpath: string, - newpath: string, - options?: any, - ): Promise; - function watchFs(paths: string | string[], options?: any): any; - function addSignalListener(signal: string, handler: () => void): void; - function serve(...args: any[]): any; - - const env: { - get(key: string): string | undefined; - toObject(): Record; - [key: string]: any; - }; - - const build: { - os: string; - arch: string; - target: string; - vendor: string; - env?: string | null; - [key: string]: any; - }; - - const version: { - deno: string; - typescript: string; - v8: string; - [key: string]: any; - }; - - const stdout: { - write(data: Uint8Array): Promise; - [key: string]: any; - }; - - namespace errors { - class NotFound extends Error {} - class PermissionDenied extends Error {} - class ConnectionReset extends Error {} - class ConnectionAborted extends Error {} - } - - // SeekMode enum values - namespace SeekMode { - const Start: 0; - const Current: 1; - const End: 2; - } - - // Allow test registration (Deno.test) - function test(...args: any[]): void; -} From c09b313597d58b7a64ef966e8c98d52653b58373 Mon Sep 17 00:00:00 2001 From: Ofri Wolfus Date: Thu, 29 Oct 2026 14:28:02 +0200 Subject: [PATCH 2/2] test(cli): restore checkout registry dependency guard --- tests/no-registry-dependency.test.ts | 126 +++++++++++++++++++++++++++ tests/test-registry.ts | 2 + tests/tests-entry-browser.ts | 2 + 3 files changed, 130 insertions(+) create mode 100644 tests/no-registry-dependency.test.ts diff --git a/tests/no-registry-dependency.test.ts b/tests/no-registry-dependency.test.ts new file mode 100644 index 00000000..0d477d9c --- /dev/null +++ b/tests/no-registry-dependency.test.ts @@ -0,0 +1,126 @@ +/** Static guard: tests must exercise this checkout, never a published package. + * A registry install changes the subject from current code to release behavior. */ + +import { TEST } from './mod.ts'; +import { assertEquals, assertTrue } from './asserts.ts'; +import * as path from '../base/path.ts'; +import { isBrowser } from '../base/common.ts'; +import { getRuntime } from '../base/runtime/index.ts'; +import { scanSourceTree } from './file-walk.ts'; + +const kGuardFile = 'no-registry-dependency.test.ts'; +const kManagers = /^(?:npm|npx|pnpm|yarn|bun|bunx|deno)$/; +const kInstallManagers = /^(?:npm|pnpm|yarn|bun)$/; +const kInstallCommands = /^(?:install|i|add|ci)$/; +const kRunLike = /^(?:npx|bunx|dlx|x)$/; +const kForbiddenSpec = + /(?:@goatdb\/goatdb|@jsr\/goatdb__|npm:@jsr\/goatdb__|jsr:@goatdb\/goatdb)(?![\w-])/; +const kCallStart = + /\b(?:cli|runProcess|spawn|spawnSync|exec|execFile|execFileSync|Deno\.Command)\s*\(/g; +const kQuoted = /(['"`])((?:\\.|[\s\S])*?)\1/g; + +/** Collects string args of each process call, balanced across nested calls. */ +function processCallArgs(text: string): string[][] { + return [...text.matchAll(kCallStart)].map((match) => { + const start = (match.index ?? 0) + match[0].length; + let depth = 1; + let i = start; + for (; depth > 0 && i < text.length; i++) { + if (text[i] === '(') depth++; + else if (text[i] === ')') depth--; + } + const raw = text.slice(start, i - 1); + return [...raw.matchAll(kQuoted)].map((quote) => + quote[2].replace(/\\(.)/g, '$1') + ); + }); +} + +/** Returns violations for package-manager calls that leave the checkout. */ +export function scanRegistryCommands(text: string): string[] { + const violations: string[] = []; + for (const args of processCallArgs(text)) { + const manager = args[0]; + if (manager === undefined || !kManagers.test(manager)) continue; + const rest = args.slice(1); + const spec = rest.find((arg) => kForbiddenSpec.test(arg)); + if (spec !== undefined) { + violations.push( + `${manager} must not resolve GoatDB from a registry: ${spec}`, + ); + continue; + } + const command = rest.find((arg) => !arg.startsWith('-')); + const runLike = kRunLike.test(manager) || + (command !== undefined && kRunLike.test(command)); + if ( + runLike && + rest.some((arg) => arg === 'goatdb' || arg.endsWith('/goatdb')) + ) { + violations.push(`${manager} must not run the published goatdb bin`); + } + if ( + kInstallManagers.test(manager) && command !== undefined && + kInstallCommands.test(command) + ) { + violations.push( + `${manager} ${command} must not install packages during tests`, + ); + } + } + return [...new Set(violations)]; +} + +async function assertNoRegistryConsumption( + root: path.PosixPath, +): Promise { + const violations = await scanSourceTree( + path.join(root, 'tests'), + kGuardFile, + (file, text) => + scanRegistryCommands(text).map((violation) => `${file}: ${violation}`), + ); + assertTrue(violations.length === 0, violations.join('\n')); +} + +export default function setupNoRegistryDependencyTests() { + TEST( + 'TestBoundaries', + 'registry guard classifies package-manager calls', + () => { + for ( + const text of [ + "await cli('npm', 'install',\n '--omit=dev',\n tarball, { cwd });", + "await cli('npx', '--no-install', 'goatdb', 'init');", + "await cli('deno', 'add', 'jsr:@goatdb/goatdb');", + "await cli('npm', 'install', '@goatdb/goatdb');", + "await cli('pnpm', 'dlx', 'goatdb');", + "await cli('npm', 'install', path.join(root, tarball));", + "await runProcess('npm', ['install', '@goatdb/goatdb'], {});", + "await new Deno.Command('npm', { args: ['install', '@goatdb/goatdb'] });", + ] + ) { + assertTrue(scanRegistryCommands(text).length > 0, text); + } + for ( + const text of [ + "await cli('npm', 'run', 'build:npm', { cwd });", + "await cli('node', bin, '--help');", + "await cli('deno', 'info', '--json', 'client/index.tsx');", + "await cli('npm', 'ls', '--depth=0', '--json');", + ] + ) { + assertEquals(scanRegistryCommands(text), [], text); + } + }, + ); + + // Browser runs the pure classifier; checkout scanning needs filesystem access. + if (!isBrowser()) { + TEST( + 'TestBoundaries', + 'tests do not install GoatDB from a registry', + () => assertNoRegistryConsumption(getRuntime().getCWD()), + ); + } +} diff --git a/tests/test-registry.ts b/tests/test-registry.ts index 44777d0b..0bc8c15b 100644 --- a/tests/test-registry.ts +++ b/tests/test-registry.ts @@ -33,6 +33,7 @@ import setupClusterLatency from './cluster-latency.test.ts'; import setupCliInitTests from './cli-init.test.ts'; import setupCliCompileTests from './cli-compile.test.ts'; import setupCliPackageTests from './cli-package.test.ts'; +import setupNoRegistryDependencyTests from './no-registry-dependency.test.ts'; import setupCliBuildAssetsTests from './cli-build-assets.test.ts'; import setupPathTests from './path.test.ts'; import setupCliPathNormalizationTests from './cli-path-normalization.test.ts'; @@ -118,6 +119,7 @@ export async function registerAllTests(): Promise { setupSecurityBoundaries(); // Security boundary invariants (auth, sync, signatures) setupGoatRequestTest(); // HTTP request processing setupCliInitTests(); // CLI scaffolding functionality + setupNoRegistryDependencyTests(); // Test-suite registry boundary setupCliPackageTests(); // Built artifact, bin, and template contract setupMergeLCA(); // Lowest Common Ancestor / merge base setupMergeRecord(); // Record merge and schema upgrade diff --git a/tests/tests-entry-browser.ts b/tests/tests-entry-browser.ts index f766e512..8b2072e8 100644 --- a/tests/tests-entry-browser.ts +++ b/tests/tests-entry-browser.ts @@ -46,6 +46,7 @@ import setupDBConfig from './db-config.test.ts'; import setupPathTests from './path.test.ts'; import setupCliPathNormalizationTests from './cli-path-normalization.test.ts'; import setupPathBoundaryTests from './path-boundaries.test.ts'; +import setupNoRegistryDependencyTests from './no-registry-dependency.test.ts'; import setupPathPropertyTests from './path-property.test.ts'; import setupJsonLogWorkerIO from './json-log-worker-io.test.ts'; import setupAutoClose from './auto-close.test.ts'; @@ -91,6 +92,7 @@ async function main(): Promise { setupPathTests(); setupCliPathNormalizationTests(); setupPathBoundaryTests(); + setupNoRegistryDependencyTests(); setupPathPropertyTests(); setupHealthCheckEndpoint(); // Simple HTTP endpoint check setupHashMap(); // HashSet and HashMap collision-safe cardinality