@ontrails/trails 0.2.0

package/src/release/index.ts

@@ -0,0 +1,180 @@
+export {
+  nativeBunPackBinding,
+  nativeBunReleaseBinding,
+  npmReleaseAdapterBinding,
+  releaseBindingCapabilityValues,
+  releaseBindingKindValues,
+  releaseBindingPlacementValues,
+  type ReleaseBindingCapability,
+  type ReleaseBindingDescriptor,
+  type ReleaseBindingKind,
+  type ReleaseBindingPlacement,
+} from './bindings.js';
+export {
+  checkReleaseRules,
+  discoverWorkspaces,
+  formatReleaseCheckReport,
+  loadReleaseConfig,
+  runReleaseCheck,
+  runReleaseCheckCli,
+  type ReleaseCheckReport,
+  type ReleaseCheckInput,
+  type ReleaseCheckResult,
+  type ReleaseConfigLoadResult,
+  type RunReleaseCheckOptions,
+  type WorkspaceInfo,
+} from './check.js';
+export {
+  createContractSourceSnapshots,
+  findPublicTrailContractChangeFacts,
+  findPublicTrailContractChangeFactsFromSnapshots,
+  type ContractReleaseFact,
+  type ContractReleaseFactAspect,
+  type ContractReleaseFactInput,
+  type ContractSourceSnapshot,
+} from './contract-facts.js';
+export {
+  findPackageRouteReleaseFacts,
+  type PackageRouteReleaseDiagnostic,
+  type PackageRouteReleaseFact,
+} from './package-route-facts.js';
+export {
+  defaultReleaseConfig,
+  defaultReleaseRules,
+  releaseConfigSchema,
+  releaseFactTypeSchema,
+  releaseFactTypeValues,
+  releaseIntentSourceSchema,
+  releaseIntentSourceValues,
+  releaseRuleSchema,
+  releaseRuleSeveritySchema,
+  releaseRuleSeverityValues,
+  type ReleaseConfig,
+  type ReleaseConfigInput,
+  type ReleaseFactType,
+  type ReleaseIntentSource,
+  type ReleaseRule,
+  type ReleaseRuleInput,
+} from './config.js';
+export {
+  buildTrailsCliReleaseArtifact,
+  createDeterministicTarGzip,
+  currentTrailsCliReleasePlatform,
+  expectedTrailsCliReleaseAssetNames,
+  runTrailsCliReleaseCli,
+  trailsCliArchiveName,
+  trailsCliChecksumName,
+  trailsCliReleasePlatforms,
+  trailsCliReleasePlatformValues,
+  verifyTrailsCliArchive,
+  type BuildTrailsCliReleaseOptions,
+  type TrailsCliReleaseArtifact,
+  type TrailsCliReleasePlatform,
+  type TrailsCliReleasePlatformDescriptor,
+} from './cli-bundle.js';
+export {
+  parseTrailsCliChecksums,
+  renderTrailsHomebrewFormula,
+  runTrailsHomebrewCli,
+  validateTrailsHomebrewRelease,
+  verifyTrailsHomebrewAssetDirectory,
+  type GitHubReleaseAsset,
+  type GitHubReleaseMetadata,
+  type TrailsCliReleaseChecksums,
+} from './homebrew.js';
+export {
+  createNpmPublishCommand,
+  findPackedFirstPartyDependencyMismatches,
+  publicationActionForRegistryState,
+  runNativeBunPublishCli,
+  trustedPublishingPreflightErrors,
+  unsupportedPublishLifecycleScripts,
+  type NativeBunPublishOptions,
+  type NativeBunPublishPackageJson,
+  type NativeBunPublishWorkspace,
+} from './native-bun-publish.js';
+export {
+  findLockfileWorkspaceMetadataMismatches,
+  isReleasePackCoherenceFile,
+  parseReleasePackCoherenceArgs,
+  runReleasePackCoherenceCli,
+  shouldRunReleasePackCoherenceCheck,
+  syncLockfileWorkspaceMetadataText,
+  type ReleasePackCoherenceLockfileInput,
+  type ReleasePackCoherenceLockfileSyncResult,
+  type ReleasePackCoherenceLockfileWorkspace,
+  type ReleasePackCoherenceInput,
+  type ReleasePackCoherenceParsedArgs,
+  type ReleasePackCoherenceWorkspace,
+} from './pack-coherence.js';
+export {
+  checkRegistryPosture,
+  classifyPackageRegistryState,
+  discoverRegistryWorkspaces,
+  factsFromRegistryResult,
+  formatDistTagSummary,
+  npmRegistryVersionView,
+  npmRegistryView,
+  registryPostureErrors,
+  runRegistryPreflight,
+  runRegistryPreflightCli,
+  type PackageRegistryFacts,
+  type PackageRegistryState,
+  type RegistryCheckPhase,
+  type RegistryPreflightOptions,
+  type RegistryResult,
+  type RegistryVersionView,
+  type RegistryView,
+  type RegistryWorkspace,
+} from './native-bun-registry.js';
+export {
+  collectReleaseNotesInput,
+  dedupeReleaseChanges,
+  extractChangelogEntry,
+  renderReleaseNotes,
+  type ReleaseNotesCollectOptions,
+  type ReleaseNotesChange,
+  type ReleaseNotesInput,
+  type ReleaseNotesPackageVersion,
+  type ReleaseNotesParsedChange,
+} from './notes.js';
+export { runReleaseNotesCli } from './notes-cli.js';
+export {
+  channelIntentForDistTag,
+  evaluateReleasePolicy,
+  labelsForReleasePullRequest,
+  releaseIntentForVersionDelta,
+  runReleasePolicyCli,
+  type ChannelIntent,
+  type PublishIntent,
+  type ReleaseIntent,
+  type ReleasePolicyChangedFile,
+  type ReleasePolicyCommit,
+  type ReleasePolicyDecision,
+  type ReleasePolicyInput,
+  type ReleasePolicyPullRequest,
+  type ReleasePolicyRegistryPackage,
+  type ReleasePolicyReport,
+  type ReleasePolicySourcePullRequest,
+  type StackIntent,
+} from './policy.js';
+export {
+  releaseSmokeCheckValues,
+  runReleaseSmoke,
+  type ReleaseSmokeCheck,
+  type ReleaseSmokeCheckResult,
+  type ReleaseSmokeResult,
+} from './smoke.js';
+export {
+  runLockRoundtripSmoke,
+  type LockRoundtripSmokeOptions,
+  type LockRoundtripSmokeResult,
+} from './lock-roundtrip-smoke.js';
+export {
+  runPackedArtifactsSmoke,
+  type PackedArtifactsSmokeResult,
+} from './packed-artifacts-smoke.js';
+export {
+  runWayfinderDogfoodSmoke,
+  type WayfinderDogfoodSmokeResult,
+} from './wayfinder-dogfood-smoke.js';

package/src/release/lock-roundtrip-smoke.ts

@@ -0,0 +1,255 @@
+/**
+ * Lock round-trip invariant (TRL-1200).
+ *
+ * For every committed `trails.lock` in the repo, a fresh `trails compile`
+ * against a cold per-user store followed by `trails validate` must be
+ * green, and the recompiled lock must be byte-identical to the committed
+ * one. Evidence the toolchain cannot reproduce does not merge.
+ *
+ * Failures name the divergence and the command that fixes it. Hand-editing
+ * a lock is never the remediation.
+ */
+
+import { existsSync, readFileSync } from 'node:fs';
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+
+import { copyLockRoundtripWorkspace } from './lock-roundtrip-workspace.js';
+
+const trailsBinFor = (repoRoot: string): string =>
+  join(repoRoot, 'apps/trails/bin/trails.ts');
+
+export interface LockRoundtripSmokeResult {
+  readonly check: 'lock-roundtrip';
+  readonly lockCount: number;
+  readonly message: string;
+  readonly passed: true;
+}
+
+export interface LockRoundtripSmokeOptions {
+  /** Override lock discovery with explicit repo-relative lock paths. */
+  readonly lockPaths?: readonly string[];
+  readonly repoRoot?: string;
+}
+
+const discoverCommittedLocks = (repoRoot: string): readonly string[] => {
+  const result = Bun.spawnSync({
+    cmd: ['git', 'ls-files', '--', 'trails.lock', '*/trails.lock'],
+    cwd: repoRoot,
+    stderr: 'pipe',
+    stdout: 'pipe',
+  });
+  if (result.exitCode !== 0) {
+    throw new Error(
+      `lock-roundtrip: git ls-files failed: ${result.stderr.toString()}`
+    );
+  }
+  return result.stdout
+    .toString()
+    .split('\n')
+    .map((line) => line.trim())
+    .filter((line) => line.length > 0);
+};
+
+const resolveAppModule = (appDir: string): string => {
+  if (existsSync(join(appDir, 'src', 'app.ts'))) {
+    return './src/app.ts';
+  }
+  const packageJsonPath = join(appDir, 'package.json');
+  if (existsSync(packageJsonPath)) {
+    const parsed = JSON.parse(readFileSync(packageJsonPath, 'utf8')) as {
+      readonly main?: unknown;
+    };
+    if (typeof parsed.main === 'string') {
+      return parsed.main;
+    }
+  }
+  throw new Error(
+    `lock-roundtrip: unable to resolve the app module for "${appDir}" — expected src/app.ts or a package.json "main" entry.`
+  );
+};
+
+const runTrailsCommand = (
+  repoRoot: string,
+  stateHome: string,
+  args: readonly string[]
+): { readonly exitCode: number; readonly output: string } => {
+  const result = Bun.spawnSync({
+    cmd: [process.execPath, trailsBinFor(repoRoot), ...args],
+    cwd: repoRoot,
+    env: {
+      ...process.env,
+      NO_COLOR: '1',
+      TRAILS_STATE_HOME: stateHome,
+      XDG_STATE_HOME: stateHome,
+    } as Record<string, string | undefined>,
+    stderr: 'pipe',
+    stdout: 'pipe',
+  });
+  return {
+    exitCode: result.exitCode,
+    output: `${result.stdout.toString()}${result.stderr.toString()}`,
+  };
+};
+
+const summarizeEntryIds = (value: unknown): readonly string[] => {
+  if (typeof value !== 'object' || value === null) {
+    return [];
+  }
+  const { topoGraph } = value as {
+    readonly topoGraph?: { readonly entries?: readonly { id?: string }[] };
+  };
+  return (topoGraph?.entries ?? [])
+    .map((entry) => entry.id)
+    .filter((id): id is string => typeof id === 'string');
+};
+
+/** Name what diverged between the committed and recompiled lock bytes. */
+const describeLockDivergence = (
+  committed: string,
+  recompiled: string
+): readonly string[] => {
+  const details: string[] = [];
+  let committedParsed: unknown;
+  let recompiledParsed: unknown;
+  try {
+    committedParsed = JSON.parse(committed);
+    recompiledParsed = JSON.parse(recompiled);
+  } catch {
+    return ['committed lock is not valid JSON'];
+  }
+  const committedLock = committedParsed as Record<string, unknown>;
+  const recompiledLock = recompiledParsed as Record<string, unknown>;
+
+  for (const section of ['scope', 'summary', 'topoGraphHash', 'version']) {
+    const left = JSON.stringify(committedLock[section]);
+    const right = JSON.stringify(recompiledLock[section]);
+    if (left !== right) {
+      details.push(`${section}: committed ${left} vs recompiled ${right}`);
+    }
+  }
+
+  const committedIds = new Set(summarizeEntryIds(committedParsed));
+  const recompiledIds = new Set(summarizeEntryIds(recompiledParsed));
+  const missing = [...committedIds].filter((id) => !recompiledIds.has(id));
+  const added = [...recompiledIds].filter((id) => !committedIds.has(id));
+  if (missing.length > 0) {
+    details.push(`entries only in committed lock: ${missing.join(', ')}`);
+  }
+  if (added.length > 0) {
+    details.push(`entries only in recompiled lock: ${added.join(', ')}`);
+  }
+  if (details.length === 0) {
+    details.push('topoGraph entry content differs (same ids, different facts)');
+  }
+  return details;
+};
+
+const checkSingleLock = async (
+  repoRoot: string,
+  lockPath: string
+): Promise<void> => {
+  const absoluteLockPath = resolve(repoRoot, lockPath);
+  const appDir = dirname(absoluteLockPath);
+  const relativeAppDir = relative(repoRoot, appDir) || '.';
+  const appModule = resolveAppModule(appDir);
+  const committedBytes = readFileSync(absoluteLockPath, 'utf8');
+  const stateHome = await mkdtemp(join(tmpdir(), 'lock-roundtrip-'));
+  const fixCommand = `bun apps/trails/bin/trails.ts compile --module ${appModule} --root-dir ${relativeAppDir} --permit '{"id":"lock-refresh","scopes":["topo:write"]}'`;
+  const remediation = `Fix: run \`${fixCommand}\` and commit the refreshed trails.lock. Never hand-edit the lock.`;
+
+  try {
+    const compileResult = runTrailsCommand(repoRoot, stateHome, [
+      'compile',
+      '--module',
+      appModule,
+      '--root-dir',
+      relativeAppDir,
+      '--permit',
+      '{"id":"lock-roundtrip-gate","scopes":["topo:write"]}',
+      '--json',
+    ]);
+    if (compileResult.exitCode !== 0) {
+      throw new Error(
+        `lock-roundtrip: cold compile failed for ${lockPath}.\n${compileResult.output}\n${remediation}`
+      );
+    }
+
+    const validateResult = runTrailsCommand(repoRoot, stateHome, [
+      'validate',
+      '--module',
+      appModule,
+      '--root-dir',
+      relativeAppDir,
+      '--json',
+    ]);
+    if (validateResult.exitCode !== 0) {
+      throw new Error(
+        `lock-roundtrip: validate failed for ${lockPath} after a cold recompile.\n${validateResult.output}\n${remediation}`
+      );
+    }
+
+    const recompiledBytes = readFileSync(absoluteLockPath, 'utf8');
+    if (recompiledBytes !== committedBytes) {
+      const details = describeLockDivergence(committedBytes, recompiledBytes);
+      throw new Error(
+        [
+          `lock-roundtrip: ${lockPath} is not byte-identical after a cold recompile.`,
+          ...details.map((detail) => `  - ${detail}`),
+          remediation,
+        ].join('\n')
+      );
+    }
+  } finally {
+    await rm(stateHome, { force: true, recursive: true });
+  }
+};
+
+export const runLockRoundtripSmoke = async (
+  options?: LockRoundtripSmokeOptions
+): Promise<LockRoundtripSmokeResult> => {
+  const repoRoot = resolve(options?.repoRoot ?? process.cwd());
+  const lockPaths = options?.lockPaths ?? discoverCommittedLocks(repoRoot);
+
+  for (const lockPath of lockPaths) {
+    const path = relative(repoRoot, resolve(repoRoot, lockPath));
+    if (path === '..' || path.startsWith(`..${sep}`) || isAbsolute(path)) {
+      throw new Error(
+        `lock-roundtrip: lock path must stay inside repoRoot: ${lockPath}`
+      );
+    }
+  }
+  if (lockPaths.length > 0) {
+    const workspace = await mkdtemp(
+      join(tmpdir(), 'lock-roundtrip-workspace-')
+    );
+    try {
+      await copyLockRoundtripWorkspace(
+        repoRoot,
+        workspace,
+        lockPaths.map((path) => relative(repoRoot, resolve(repoRoot, path)))
+      );
+      for (const lockPath of lockPaths) {
+        await checkSingleLock(
+          workspace,
+          relative(repoRoot, resolve(repoRoot, lockPath))
+        );
+      }
+    } finally {
+      await rm(workspace, { force: true, recursive: true });
+    }
+  }
+
+  const message =
+    lockPaths.length === 0
+      ? 'lock-roundtrip: no committed trails.lock files found — nothing to verify'
+      : `lock-roundtrip: ${lockPaths.length} committed trails.lock file(s) recompiled cold — validate green, byte-identical (${lockPaths.join(', ')})`;
+
+  return {
+    check: 'lock-roundtrip',
+    lockCount: lockPaths.length,
+    message,
+    passed: true,
+  };
+};

package/src/release/lock-roundtrip-workspace.ts

@@ -0,0 +1,107 @@
+import {
+  cp,
+  lstat,
+  mkdir,
+  readFile,
+  readlink,
+  stat,
+  symlink,
+  writeFile,
+} from 'node:fs/promises';
+import { basename, dirname, relative, sep } from 'node:path';
+
+const trackedInputPaths = (source: string): Set<string> => {
+  const result = Bun.spawnSync({
+    cmd: ['git', 'ls-files', '-z'],
+    cwd: source,
+    stderr: 'pipe',
+    stdout: 'pipe',
+  });
+  if (result.exitCode !== 0) {
+    throw new Error(
+      `lock-roundtrip: unable to list tracked inputs: ${result.stderr.toString()}`
+    );
+  }
+  const paths = new Set<string>();
+  for (const file of result.stdout.toString().split('\0').filter(Boolean)) {
+    let path = file.split('/').join(sep);
+    while (path !== '.') {
+      paths.add(path);
+      path = dirname(path);
+    }
+  }
+  return paths;
+};
+
+const isDisposablePath = (segments: readonly string[]): boolean =>
+  segments.some(
+    (part, index) =>
+      part === '.tmp-tests' ||
+      part === '.trails-tmp' ||
+      part === '.turbo' ||
+      (part === 'worktrees' && segments[index - 1] === '.claude') ||
+      (part === 'notes' && segments[index - 1] === '.agents')
+  );
+
+/**
+ * Copy current working files for compile/validate without writing to their owner.
+ * Workspace dependency links resolve within the copy; only Bun's installed
+ * dependency store stays shared. Callers still need a stable tree while copying
+ * and must not modify installed dependencies during checks.
+ */
+export const copyLockRoundtripWorkspace = async (
+  source: string,
+  destination: string,
+  lockPaths: readonly string[]
+): Promise<void> => {
+  const trackedPaths = trackedInputPaths(source);
+  const fixtureRoots = lockPaths
+    .filter((path) => isDisposablePath(path.split(sep)))
+    .map((path) => dirname(path));
+  await cp(source, destination, {
+    dereference: true,
+    filter: async (path, target) => {
+      const name = basename(path);
+      const relativePath = relative(source, path);
+      const segments = relativePath.split(sep);
+      const selectedFixture = fixtureRoots.some(
+        (root) =>
+          root === relativePath ||
+          root.startsWith(`${relativePath}${sep}`) ||
+          relativePath.startsWith(`${root}${sep}`)
+      );
+      if (
+        name === '.git' ||
+        (isDisposablePath(segments) &&
+          !selectedFixture &&
+          !trackedPaths.has(relativePath))
+      ) {
+        return false;
+      }
+      const entry = await lstat(path);
+      const inDependencies = segments.includes('node_modules');
+      if (inDependencies && entry.isSymbolicLink()) {
+        await mkdir(dirname(target), { recursive: true });
+        await symlink(await readlink(path), target);
+        return false;
+      }
+      if (name === '.bun' && basename(dirname(path)) === 'node_modules') {
+        await mkdir(dirname(target), { recursive: true });
+        await symlink(path, target, 'dir');
+        return false;
+      }
+      const materialized = entry.isSymbolicLink() ? await stat(path) : entry;
+      if (materialized.isFile()) {
+        // Bun's large-file copy can emit source metadata events on macOS.
+        // Explicit byte I/O keeps a guarded checkout free of copy side effects.
+        await mkdir(dirname(target), { recursive: true });
+        await writeFile(target, await readFile(path), {
+          mode: materialized.mode,
+        });
+        return false;
+      }
+      return true;
+    },
+    recursive: true,
+  });
+};