Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 9 additions & 6 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -35,6 +35,15 @@ jobs:
with:
persist-credentials: false

- name: Install pinned Node.js
uses: actions/setup-node@249970729cb0ef3589644e2896645e5dc5ba9c38 # v6
with:
node-version: 24.20.0
package-manager-cache: false

- name: Preflight release assembly without dependencies or credentials
run: node npm/scripts/preflight-release.mjs

- name: Install pinned Rust toolchain
run: rustup toolchain install --no-self-update

Expand Down Expand Up @@ -70,12 +79,6 @@ jobs:
python3 scripts/smoke-inline-tui.py --rapid-resize
python3 scripts/smoke-inline-tui.py --results --rapid-resize

- name: Install pinned Node.js
uses: actions/setup-node@249970729cb0ef3589644e2896645e5dc5ba9c38 # v6
with:
node-version: 24.20.0
package-manager-cache: false

- name: Check npm distribution contract
shell: bash
run: |
Expand Down
57 changes: 5 additions & 52 deletions .github/workflows/release.yml
Original file line number Diff line number Diff line change
Expand Up @@ -134,6 +134,9 @@ jobs:
set -euo pipefail
test "$NPM_PUBLISH_ENABLED" = "true"

- name: Preflight release assembly without dependencies or credentials
run: node npm/scripts/preflight-release.mjs

- name: Check formatting
run: cargo fmt --all -- --check

Expand Down Expand Up @@ -363,58 +366,8 @@ jobs:
shell: bash
run: |
set -euo pipefail
node npm/scripts/pack.mjs --launcher --output-dir release
expected=(
xgen-x86_64-unknown-linux-musl
xgen-aarch64-unknown-linux-musl
xgen-x86_64-apple-darwin
xgen-aarch64-apple-darwin
xgen-x86_64-pc-windows-msvc.exe
xgen-cli.tgz
xgen-cli-linux-x64-musl.tgz
xgen-cli-linux-arm64-musl.tgz
xgen-cli-darwin-x64.tgz
xgen-cli-darwin-arm64.tgz
xgen-cli-win32-x64.tgz
)
test "$(find release -mindepth 1 -maxdepth 1 | wc -l)" -eq "${#expected[@]}"
for asset in "${expected[@]}"; do
test -f "release/$asset" && test ! -L "release/$asset"
done
chmod 0755 \
release/xgen-x86_64-unknown-linux-musl \
release/xgen-aarch64-unknown-linux-musl \
release/xgen-x86_64-apple-darwin \
release/xgen-aarch64-apple-darwin
node npm/scripts/verify-release.mjs \
--directory release \
--tag "$RELEASE_TAG"
install -m 0755 install/xgen-installer.sh release/xgen-installer.sh
install -m 0644 install/xgen-installer.ps1 release/xgen-installer.ps1
install -m 0644 LICENSE release/LICENSE.txt
install -m 0644 crates/xgen-cli/licenses/NATIVE_RUNTIME_PROVENANCE.md \
release/NATIVE_RUNTIME_PROVENANCE.md
install -m 0644 THIRD_PARTY_LICENSES.txt release/THIRD_PARTY_LICENSES.txt
(
cd release
export LC_ALL=C
sha256sum LICENSE.txt NATIVE_RUNTIME_PROVENANCE.md THIRD_PARTY_LICENSES.txt \
xgen-*.tgz xgen-* \
> checksums.sha256
sha256sum -c checksums.sha256
)
expected+=(
xgen-installer.sh
xgen-installer.ps1
LICENSE.txt
NATIVE_RUNTIME_PROVENANCE.md
THIRD_PARTY_LICENSES.txt
checksums.sha256
)
test "$(find release -mindepth 1 -maxdepth 1 | wc -l)" -eq "${#expected[@]}"
for asset in "${expected[@]}"; do
test -f "release/$asset" && test ! -L "release/$asset"
done
node npm/scripts/assemble-release.mjs --directory release --tag "$RELEASE_TAG"
(cd release && sha256sum -c checksums.sha256)
sh scripts/smoke-installer.sh \
release/xgen-x86_64-unknown-linux-musl \
xgen-x86_64-unknown-linux-musl \
Expand Down
10 changes: 9 additions & 1 deletion MEMORY.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# xgen CLI와 연계 도구 공동 개발 메모

갱신: 2026-11-19 (KST)
갱신: 2026-11-20 (KST)

## 사용자가 정한 방향

Expand All @@ -14,6 +14,14 @@

## 책임과 개발 범위

2026-11-20 구현·로컬 검증: [Native build 전 공통 조립 검사](docs/adr/0089-release-assembly-preflight.md).
PR Fast/Linux와 release quality에서 dependency·credential 없는 임시 환경으로 실제 pack→조립→checksum을
검사한다. Production과 같은 entrypoint를 쓰며 입력/출력은 platform catalog에서 파생한다.
Stable/prerelease 두 fixture·잘못된 입력 6개와 static/호출 시점 의존성 누락을 검증했다(로컬 약7~9초).
별도 공개 rc.8 실제 asset으로 17개 조립 결과·게시본 byte parity·Linux installer smoke도 통과했다.
Native ABI·실제 모델·registry 전파 문제 해결이나 전체 CI 시간 단축은 이 결과로 주장하지 않는다.
이번 작업은 배포 경로만 변경하며 현재 사용자 배포본은 rc.8을 유지한다.

2026-11-19 구현·배포·공개 설치 검증 완료: [최초 사용과 기본 preview 설치](docs/adr/0088-first-use-preview-distribution.md).
실행 파일 없는 bootstrap을 기본 설치로 받는 문제를 고쳐 첫 stable 전에는 검증한 launcher preview를
`latest`로 제공한다. Provider/model 오입력 재선택과 정적 오류 복구 안내, 현재 OpenAI preset 안내를
Expand Down
44 changes: 44 additions & 0 deletions docs/adr/0089-release-assembly-preflight.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,44 @@
# ADR-0089: Native build 전에 실행하는 공통 조립 검사

- 날짜: 2026-11-20
- 상태: 채택, 구현·로컬 검증 완료
- 범위: 일반 배포 검증. CLI runtime·권한·journal·모델 입력은 바꾸지 않는다.

## 근거와 결정

rc.7은 5개 native build 뒤 assembly verifier의 `semver` import 누락으로 실패했다.
rc.8에 추가한 무의존성 import 검사는 module load만 확인하므로 함수 실행 중의 의존성 누락은 못 잡는다.
따라서 실제 pack·검증·checksum 생성을 native compiler보다 먼저 실행한다.

`npm/scripts/assemble-release.mjs`를 production과 검사 양쪽의 공통 entrypoint로 둔다.
입력 native asset·platform tarball 목록은 `npm/platforms.json`에서 파생한다. Launcher pack,
원본 계약·binary byte parity 검증, installer·고지 복사와 checksum 생성을 같은 코드로 수행한다.
입력·출력 집합과 regular-file 조건을 검사하고 덮어쓰지 않는다. `checksums.sha256`은 기존 형식을
유지하되, 예전 shell glob이 중복 나열하던 tgz를 포함해 각 파일을 한 번만 기록한다.

`npm/scripts/preflight-release.mjs`는 공개 source 중 필요한 파일만 새 임시 환경에 복사한다.
`node_modules`·user config를 복사하지 않고 npm cache·HOME·설정을 별도로 둔다. 환경변수는 toolchain에
필요한 항목만 허용하며 npm은 offline·ignore-scripts로 실행한다. Compiler·model·registry 게시·token은
필요하지 않다. 두 fixture version(stable/prerelease)에서 실제 packer와 공통 entrypoint를 호출한다.
Payload는 `ASSEMBLY_FIXTURE_ONLY` byte이며 native 프로그램처럼 실행하거나 artifact로 업로드하지 않는다.

Fast/Linux는 Node.js 설치 직후 Rust toolchain·npm ci 전에 이 검사를 수행한다. Release quality에서도
npm ci·compile 전에 수행하고 native jobs는 기존대로 quality 성공을 기다린다. Workflow 계약 검사는
이 순서와 공통 entrypoint 연결을 확인한다. 실제 native inspection·실행·installer 검사는 유지한다.

## 검증과 한계

- 로컬 전체 preflight는 약 7~9초였다. 두 version의 6개 package 조립·17개 asset·checksum 전체 포함과
중복 부재를 확인했다. 추가 파일·raw/package 불일치·마지막 platform tarball 누락은 각 version에서 거절했다.
- 임시 source에서 static `semver` import를 재삽입하자 1.2초에 거절했다. 함수 호출 시 `import('semver')`를
추가한 경우 기존 import-only 검사는 통과했지만 새 preflight는 1.4초에 거절했다. 이 변경은 제품 source에 남기지 않았다.
- 설계에 쓰지 않은 공개 rc.8의 실제 5개 native asset·5개 platform package를 SHA-256으로 확인한 뒤,
`node_modules` 없는 checkout에서 새 assembler로 조립했다. 17개 결과 중 checksum manifest를 제외한
모든 파일이 게시본의 SHA-256과 같았다. 새 manifest도 각 파일의 실제 hash와 일치했다.
- 그 bundle의 실제 Linux binary·복사한 installer로 기존 설치·재설치·손상 checksum 거절·symlink 거절·
protocol·license·REPL smoke가 통과했다. npm20개와 workflow·문서 검사도 통과했다.
- 독립 diff 검토 도구는 인증 오류로 실행하지 못해 직접 검토했다.

이는 packaging 경로를 앞에서 검사하는 변경이다. 가짜 byte로 CPU/OS ABI나 실제 native 실행을 검증하지
않으며, 전체 CI·release 시간이 단축됐다는 측정도 아니다. npm registry 반영 지연과 Windows optional
package 누락 원인은 별도 문제로 남는다. 이번 변경을 위해 새 release tag나 package를 게시하지 않는다.
6 changes: 6 additions & 0 deletions docs/development/releasing.md
Original file line number Diff line number Diff line change
Expand Up @@ -40,7 +40,13 @@ binary를 감싸는 선택형 설치 채널이며 제품 runtime을 다시 구

로컬 확인:

릴리즈 전 보완과 version·문서 변경을 한 PR에 모아 검증한다. 먼저 아래 preflight를 실행해
조립 경로를 확인한 뒤 Rust 검사와 tag 생성으로 넘어간다. 이 검사는 약 7~9초의 로컬 byte fixture
검사이며 실제 OS build·실행·서명이나 npm 게시를 대신하지 않는다. 자세한 경계는
[ADR-0089](../adr/0089-release-assembly-preflight.md)를 따른다.

```bash
node npm/scripts/preflight-release.mjs
cargo fmt --all -- --check
cargo clippy --workspace --all-targets --locked -- -D warnings
cargo test --workspace --locked
Expand Down
59 changes: 59 additions & 0 deletions npm/scripts/assemble-release.mjs
Original file line number Diff line number Diff line change
@@ -0,0 +1,59 @@
import assert from 'node:assert/strict';
import { spawnSync } from 'node:child_process';
import { createHash } from 'node:crypto';
import { chmod, constants, copyFile, lstat, readFile, readdir, writeFile } from 'node:fs/promises';
import path from 'node:path';
import { fileURLToPath } from 'node:url';

import { distributionMetadata, npmRoot, repoRoot } from './config.mjs';
import { verifyRelease } from './verify-release.mjs';

const supportingFiles = [
['install/xgen-installer.sh', 'xgen-installer.sh', 0o755],
['install/xgen-installer.ps1', 'xgen-installer.ps1', 0o644],
['LICENSE', 'LICENSE.txt', 0o644],
['crates/xgen-cli/licenses/NATIVE_RUNTIME_PROVENANCE.md', 'NATIVE_RUNTIME_PROVENANCE.md', 0o644],
['THIRD_PARTY_LICENSES.txt', 'THIRD_PARTY_LICENSES.txt', 0o644],
];

async function checkFiles(directory, expected) {
assert.deepEqual((await readdir(directory)).sort(), [...expected].sort(), 'release asset set differs');
for (const filename of expected) {
assert((await lstat(path.join(directory, filename))).isFile(), `${filename} must be a regular file`);
}
}

export async function assembleRelease(directory, tag) {
const { catalog } = await distributionMetadata();
const incoming = catalog.platforms.flatMap(({ asset, tarball }) => [asset, tarball]);
await checkFiles(directory, incoming);
for (const specification of catalog.platforms) {
if (specification.os !== 'win32') await chmod(path.join(directory, specification.asset), 0o755);
}
const pack = spawnSync(process.execPath, [path.join(npmRoot, 'scripts/pack.mjs'), '--launcher', '--output-dir', directory], {
encoding: 'utf8', maxBuffer: 4 * 1024 * 1024,
});
assert.equal(pack.status, 0, pack.stderr || pack.error?.message);
await verifyRelease(directory, tag);
for (const [source, destination, mode] of supportingFiles) {
const output = path.join(directory, destination);
await copyFile(path.join(repoRoot, source), output, constants.COPYFILE_EXCL);
await chmod(output, mode);
}
const outputs = [...incoming, 'xgen-cli.tgz', ...supportingFiles.map(([, destination]) => destination)];
await checkFiles(directory, outputs);
const checksums = await Promise.all(outputs.sort().map(async (filename) => {
const digest = createHash('sha256').update(await readFile(path.join(directory, filename))).digest('hex');
return `${digest} ${filename}\n`;
}));
await writeFile(path.join(directory, 'checksums.sha256'), checksums.join(''), { flag: 'wx', mode: 0o644 });
await checkFiles(directory, [...outputs, 'checksums.sha256']);
console.log(`release assembly: PASS (${outputs.length + 1} assets)`);
}

if (fileURLToPath(import.meta.url) === path.resolve(process.argv[1])) {
const options = process.argv.slice(2);
assert(options.length === 4 && options[0] === '--directory' && options[2] === '--tag',
'usage: assemble-release.mjs --directory DIR --tag vSEMVER');
await assembleRelease(path.resolve(options[1]), options[3]);
}
111 changes: 111 additions & 0 deletions npm/scripts/preflight-release.mjs
Original file line number Diff line number Diff line change
@@ -0,0 +1,111 @@
// Exercise the production assembly entrypoint with local byte fixtures, never native binaries.
import assert from 'node:assert/strict';
import { spawnSync } from 'node:child_process';
import { createHash } from 'node:crypto';
import { copyFile, lstat, mkdir, mkdtemp, readFile, readdir, rm, writeFile } from 'node:fs/promises';
import os from 'node:os';
import path from 'node:path';

import { launcherRoot, npmRoot, repoRoot } from './config.mjs';
import './check.mjs';

const started = performance.now();
const root = await mkdtemp(path.join(os.tmpdir(), 'xgen-release-preflight-'));

async function copy(source, destination) {
assert((await lstat(source)).isFile(), 'preflight sources must be regular files');
await mkdir(path.dirname(destination), { recursive: true });
await copyFile(source, destination);
}

function run(snapshot, relative, args, env) {
const result = spawnSync(process.execPath, [path.join(snapshot, relative), ...args], {
cwd: snapshot, env, encoding: 'utf8', timeout: 60_000, maxBuffer: 4 * 1024 * 1024,
});
assert(!result.error, result.error?.message);
return result;
}

try {
for (const version of ['0.0.0-preflight.0', '0.0.0']) {
const snapshot = path.join(root, version);
await mkdir(snapshot);
for (const filename of await readdir(path.join(npmRoot, 'scripts'))) {
if (filename.endsWith('.mjs')) await copy(path.join(npmRoot, 'scripts', filename), path.join(snapshot, 'npm/scripts', filename));
}
for (const filename of [
'LICENSE', 'THIRD_PARTY_LICENSES.txt', 'install/xgen-installer.sh', 'install/xgen-installer.ps1',
'crates/xgen-cli/licenses/NATIVE_RUNTIME_PROVENANCE.md', 'npm/platforms.json',
]) await copy(path.join(repoRoot, filename), path.join(snapshot, filename));
const launcher = JSON.parse(await readFile(path.join(launcherRoot, 'package.json'), 'utf8'));
for (const filename of launcher.files) {
const source = filename === 'LICENSE' ? path.join(repoRoot, filename) : path.join(launcherRoot, filename);
await copy(source, path.join(snapshot, 'npm/packages/cli', filename));
}
launcher.version = version;
launcher.optionalDependencies = Object.fromEntries(Object.keys(launcher.optionalDependencies).map((name) => [name, version]));
await writeFile(path.join(snapshot, 'npm/packages/cli/package.json'), JSON.stringify(launcher));
const workspace = JSON.parse(await readFile(path.join(npmRoot, 'package.json'), 'utf8'));
workspace.version = version;
const lock = JSON.parse(await readFile(path.join(npmRoot, 'package-lock.json'), 'utf8'));
lock.version = version;
lock.packages[''].version = version;
await writeFile(path.join(snapshot, 'npm/package.json'), JSON.stringify(workspace));
await writeFile(path.join(snapshot, 'npm/package-lock.json'), JSON.stringify(lock));
await writeFile(path.join(snapshot, 'Cargo.toml'), `[workspace.package]\nversion = "${version}"\n`);
const fixtureHome = path.join(snapshot, 'home');
await mkdir(fixtureHome, { mode: 0o700 });
const npmrc = path.join(fixtureHome, '.npmrc');
await writeFile(npmrc, '');
await writeFile(path.join(fixtureHome, 'global.npmrc'), '');
const allowed = new Set(['PATH', 'LANG', 'LC_ALL', 'SYSTEMROOT', 'WINDIR', 'COMSPEC', 'PATHEXT', 'TMP', 'TEMP', 'TMPDIR', 'NPM_EXECPATH']);
const env = { ...Object.fromEntries(Object.entries(process.env).filter(([name]) => allowed.has(name.toUpperCase()))), HOME: fixtureHome, USERPROFILE: fixtureHome,
npm_config_userconfig: npmrc, npm_config_globalconfig: path.join(fixtureHome, 'global.npmrc'), npm_config_cache: path.join(fixtureHome, 'cache'),
npm_config_offline: 'true', npm_config_audit: 'false', npm_config_fund: 'false',
npm_config_ignore_scripts: 'true', npm_config_update_notifier: 'false',
};
assert.equal((await readdir(path.join(snapshot, 'npm'))).includes('node_modules'), false);
const catalog = JSON.parse(await readFile(path.join(snapshot, 'npm/platforms.json'), 'utf8'));
const inputs = path.join(snapshot, 'inputs');
await mkdir(inputs);
for (const [index, specification] of catalog.platforms.entries()) {
// Distinct binary-like payloads test byte parity. Nothing here can run as a native program.
await writeFile(path.join(inputs, specification.asset), Buffer.from(`ASSEMBLY_FIXTURE_ONLY\0${version}\0${index}\n`));
const packed = run(snapshot, 'npm/scripts/pack.mjs', ['--target', specification.target,
'--binary', path.join(inputs, specification.asset), '--output-dir', inputs], env);
assert.equal(packed.status, 0, packed.stderr);
}
const inputNames = await readdir(inputs);
async function candidate(name) {
const directory = path.join(snapshot, name);
await mkdir(directory);
for (const filename of inputNames) await copy(path.join(inputs, filename), path.join(directory, filename));
return directory;
}
const directory = await candidate('bundle');
const assembled = run(snapshot, 'npm/scripts/assemble-release.mjs', ['--directory', directory, '--tag', `v${version}`], env);
assert.equal(assembled.status, 0, assembled.stderr);
const entries = (await readFile(path.join(directory, 'checksums.sha256'), 'utf8')).trim().split('\n');
const names = [];
for (const line of entries) {
const [, digest, filename] = /^([0-9a-f]{64}) (.+)$/.exec(line);
assert.equal(digest, createHash('sha256').update(await readFile(path.join(directory, filename))).digest('hex'));
names.push(filename);
}
assert.equal(new Set(names).size, names.length, 'checksum entries must be unique');
assert.deepEqual(names.sort(), (await readdir(directory)).filter((filename) => filename !== 'checksums.sha256').sort());
for (const fault of ['extra', 'mismatch', 'missing']) {
const damaged = await candidate(fault);
if (fault === 'extra') await writeFile(path.join(damaged, 'unexpected.txt'), 'fixture');
if (fault === 'mismatch') await writeFile(path.join(damaged, catalog.platforms[0].asset), 'different fixture');
if (fault === 'missing') await rm(path.join(damaged, catalog.platforms.at(-1).tarball));
const rejected = run(snapshot, 'npm/scripts/assemble-release.mjs', ['--directory', damaged, '--tag', `v${version}`], env);
assert.notEqual(rejected.status, 0);
assert(rejected.stderr.includes(fault === 'mismatch' ? 'must contain the exact GitHub release binary' : 'release asset set differs'), rejected.stderr);
}
}
console.log(`release preflight: PASS (stable/prerelease assembly, checksum coverage, 6 rejected input sets; ${((performance.now() - started) / 1000).toFixed(1)}s; fixture bytes only)`);
} finally {
// Every file in this private directory is created by this preflight; no user configuration is copied.
await rm(root, { recursive: true, force: true });
}
Loading