@vzn/vx 0.0.646 → 0.0.648

package/src/workspace/index.ts

@@ -7,10 +7,12 @@ export {
   affectedProjects,
   defaultAffectedBase,
   type FingerprintClaims,
-  refIsHead,
+  headBase,
+  mergeBaseWith,
 } from './affected.js'
 export { applyFilters, parseFilter } from './filter.js'
 export { readClaimedFiles } from './fingerprint.js'
+export { checkBracketLiterals } from './bracket-literal.js'
 export { checkDependencyRules } from './dependency-rules.js'
 export { computeNestedProjectDirs } from './nested-dirs.js'
 export { buildPackageGraph, type PackageGraph } from './package-graph.js'
@@ -19,6 +21,8 @@ export {
   LOCKFILE_NAME,
   LOCKFILE_VERSION,
   LOCK_INVALID,
+  EMPTY_LOCK,
+  lockDigest,
   lockEntryBroken,
   lockfilePath,
   lockKey,
@@ -29,6 +33,7 @@ export {
   type LockedProject,
 } from './lockfile.js'
 export {
+  ConfigsRefused,
   loadProjectConfig,
   loadProjectConfigs,
   loadWorkspaceConfig,
@@ -50,6 +55,7 @@ export {
   checkProjectNames,
   findWorkspaceRoot,
   findProjectConfigs,
+  REVIEW_FILE,
   discoveredProject,
   linkDiscoveredEdges,
   lockedProjects,
@@ -59,6 +65,7 @@ export {
   resolveStoreRoot,
   ROOT_NAME,
   type ConfigDir,
+  type ProjectConfigs,
   type ProjectEntry,
   type ProjectMeta,
 } from './workspace.js'
@@ -67,9 +74,12 @@ export type { LoadReads } from './load-reads.js'
 export {
   applyMigration,
   foldScriptHooks,
+  isStarterConfig,
   PERSISTENT_TODO,
   pruneOrphanPersistentNotes,
   quoteTsLiteral,
+  renderWorkspace,
+  starterProject,
   type ApplyMigrationArgs,
   type MigrationFormat,
   type MigrationMember,

package/src/workspace/json-data.ts

@@ -9,8 +9,7 @@
 // the value, it was silently outside the key on both. So every path
 // refuses it, before schema validation, by this one rule: the first load
 // on the live object (`validateProjectConfig`), the worker before its
-// `JSON.stringify` (config-eval.ts), and the site's playground in its own
-// Worker. The two workers embed `nonJsonPaths` by its source text, so
+// `JSON.stringify` (config-eval.ts). The worker embeds `nonJsonPaths` by its source text, so
 // the function must stay self-contained: no import, no module-scope name.
 //
 // An `undefined` PROPERTY is allowed: JSON drops it, the validator reads
@@ -91,7 +90,7 @@ export function nonJsonPaths(value: unknown): NonJsonValue[] {
   return out
 }
 
-/** The refusal every path gives, the CLI's and the playground's. */
+/** The refusal every path gives. */
 export function nonJsonMessage(configPath: string, found: NonJsonValue): string {
-  return `${configPath}: ${found.path} is ${found.is} — a config must be JSON data, because the cache key folds its JSON`
+  return `${configPath}: ${found.path} is ${found.is} — a config must be JSON data, because the cache key is built from its JSON`
 }

package/src/workspace/lockfile.ts

@@ -3,7 +3,7 @@
 // `vx lock` finds every project's vx.config.*, evaluates each in the
 // CURRENT environment and freezes the resolved objects, by directory, into
 // `.vx/projects.lock.json` at the workspace root. Every run loads configs from
-// it and never evaluates one (owner, 2026-10-14); only `vx lock` writes
+// it and never evaluates one (2026-10-14); only `vx lock` writes
 // it. See docs/design/config-lock-2026-06.md.
 //
 // Verification asymmetry (deliberate):
@@ -15,7 +15,7 @@ import { readFileSync } from 'node:fs'
 import { rename, rm } from 'node:fs/promises'
 import path from 'node:path'
 import type { ProjectConfig } from '../config.js'
-import { relPosix, UserError, xxh3 } from '../util/index.js'
+import { keysSorted, relPosix, UserError, xxh3, xxh3hex } from '../util/index.js'
 import { VERSION } from '../version.js'
 import { validateProjectConfig } from './config-schema.js'
 import { PROJECT_CONFIG_FILENAMES } from './workspace.js'
@@ -46,7 +46,7 @@ export function lockfilePath(root: string): string {
   return path.join(root, LOCKFILE_NAME)
 }
 
-/** What a run says when a crash came from a hand-broken lock entry (M, 2026-10-14). */
+/** What a run says when a crash came from a hand-broken lock entry (2026-10-14). */
 export const LOCK_INVALID = `${LOCKFILE_NAME} is invalid, run \`vx lock\``
 
 /**
@@ -73,9 +73,21 @@ export function lockEntryBroken(root: string): boolean {
   return false
 }
 
+/** What a run or `vx show` says when the lock holds no project. */
+export const EMPTY_LOCK =
+  'The lock holds no project — write a vx.config (`vx init`), then run `vx lock`'
+
 /** What a run says when there is no lock to read. */
 export const NO_LOCK = 'no lock: run `vx lock`'
 
+/** Each read lock's bytes as a digest: every config a run loads from it is a function of them. */
+const digests = new WeakMap<Lockfile, string>()
+
+/** The digest of the bytes `lock` was read from; undefined for a lock no read made. */
+export function lockDigest(lock: Lockfile): string | undefined {
+  return digests.get(lock)
+}
+
 /**
  * Read and shape-validate `.vx/projects.lock.json`. Returns `null` when no lock
  * exists (the common case — the feature is opt-in). The lock is a
@@ -91,7 +103,10 @@ export async function readLockfile(root: string): Promise<Lockfile | null> {
     text = await file.text()
     parsed = JSON.parse(text)
   } catch {
-    throw new UserError(`${LOCKFILE_NAME} is not valid JSON — re-run \`vx lock\` or delete it`)
+    throw new UserError(
+      `${LOCKFILE_NAME} is not valid JSON — re-run \`vx lock\` or delete it`,
+      'VX_E_LOCK',
+    )
   }
   // `Array.isArray` is not redundant with the `typeof` check: `typeof [] ===
   // 'object'` and `[] !== null`, so an array sails through and the NEXT check
@@ -101,22 +116,31 @@ export async function readLockfile(root: string): Promise<Lockfile | null> {
   // already guards this explicitly, which is what makes the omission here an
   // inconsistency rather than an oversight.
   if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
-    throw new UserError(`${LOCKFILE_NAME} must be a JSON object — re-run \`vx lock\``)
+    throw new UserError(`${LOCKFILE_NAME} must be a JSON object — re-run \`vx lock\``, 'VX_E_LOCK')
   }
   const lock = parsed as { version?: unknown; projects?: unknown }
   if (lock.version !== LOCKFILE_VERSION) {
     throw new UserError(
       `${LOCKFILE_NAME} has unsupported version ${String(lock.version)} ` +
         `(this vx expects ${LOCKFILE_VERSION}) — re-run \`vx lock\``,
+      'VX_E_LOCK',
     )
   }
   // Same trap, and this one is worse than a bad message: an ARRAY of entries is
   // ACCEPTED, because `Object.entries` happily walks it — yielding a project
   // at directory "0".
   if (typeof lock.projects !== 'object' || lock.projects === null || Array.isArray(lock.projects)) {
-    throw new UserError(`${LOCKFILE_NAME}: \`projects\` must be an object — re-run \`vx lock\``)
+    throw new UserError(
+      `${LOCKFILE_NAME}: \`projects\` must be an object — re-run \`vx lock\``,
+      'VX_E_LOCK',
+    )
   }
   for (const [dir, entry] of Object.entries(lock.projects)) {
+    // A run joins the key onto the root: `../x` ran a project outside it.
+    if (!isLockKey(dir))
+      throw new UserError(
+        `${LOCKFILE_NAME}: "${dir}" is not a directory under the workspace root — re-run \`vx lock\``,
+      )
     const { file, config } = (entry ?? {}) as { file?: unknown; config?: unknown }
     if (
       typeof entry !== 'object' ||
@@ -128,9 +152,13 @@ export async function readLockfile(root: string): Promise<Lockfile | null> {
       config === null ||
       Array.isArray(config)
     ) {
-      throw new UserError(`${LOCKFILE_NAME}: entry for "${dir}" is malformed — re-run \`vx lock\``)
+      throw new UserError(
+        `${LOCKFILE_NAME}: entry for "${dir}" is malformed — re-run \`vx lock\``,
+        'VX_E_LOCK',
+      )
     }
   }
+  digests.set(parsed as Lockfile, xxh3hex(text))
   return parsed as Lockfile
 }
 
@@ -143,6 +171,18 @@ function validatedDigest(body: string): string {
   return xxh3(`vx-lock-valid-v3\0${VERSION}\0${body}`).toString(16)
 }
 
+/**
+ * Each task's config with its keys sorted (`keysSorted`), so a run's key
+ * check finds it sorted and copies nothing. The tasks keep their order,
+ * which `vx show` lists them in.
+ */
+function taskKeysSorted(key: string, value: unknown): unknown {
+  if (key !== 'tasks' || value === null || typeof value !== 'object' || Array.isArray(value))
+    return value
+  // Entries, not assignment: a task named `__proto__` set the prototype.
+  return Object.fromEntries(Object.entries(value).map(([name, task]) => [name, keysSorted(task)]))
+}
+
 export async function writeLockfile(root: string, lock: Lockfile): Promise<void> {
   // Written beside its name and renamed over it: `Bun.write` truncates in
   // place, so a run, or `vx watch` woken by the write
@@ -154,7 +194,7 @@ export async function writeLockfile(root: string, lock: Lockfile): Promise<void>
     // Minified: the file only vx reads, and it loads faster than pretty
     // JSON (measured, 10k projects: 15.6 ms against 22.5 ms). `vx.lock.json`
     // beside each config is the copy for people.
-    const body = JSON.stringify({ version: lock.version, projects: lock.projects })
+    const body = JSON.stringify({ version: lock.version, projects: lock.projects }, taskKeysSorted)
     await Bun.write(tmp, `${body.slice(0, -1)},"validated":"${validatedDigest(body)}"}\n`)
     await rename(tmp, file)
   } catch (err) {
@@ -191,12 +231,21 @@ export function frozenProjectConfigs(
       throw new UserError(
         `${LOCKFILE_NAME} has no entry for "${meta.name}" (${relPosix(root, meta.configPath)}) — ` +
           'run `vx lock`',
+        'VX_E_LOCK',
       )
     }
     return entry.config
   })
 }
 
+/** An empty, `.` or `..` segment. A regex: a split per key was 1.2 ms of a 10k-project read, this 0.4 ms. */
+const BAD_SEGMENT = /(?:^|\/)\.{0,2}(?:\/|$)/
+
+/** Whether `dir` is a key `lockKey` could give: `.`, or a relative POSIX path with no empty, `.` or `..` segment. */
+function isLockKey(dir: string): boolean {
+  return dir === '.' || (!dir.startsWith('/') && !BAD_SEGMENT.test(dir))
+}
+
 /** A project directory as the lock keys it: root-relative POSIX, `.` for the root. */
 export function lockKey(root: string, dir: string): string {
   return relPosix(root, dir) || '.'

package/src/workspace/migration.ts

@@ -9,10 +9,39 @@ import { existsSync, readFileSync } from 'node:fs'
 import { unlink } from 'node:fs/promises'
 import path from 'node:path'
 import { workspaceFileWritten } from '../handoff.js'
-import { DOT_VX_GITIGNORE, executablePath, gitEnv, relPosix, UserError, ui } from '../util/index.js'
+import {
+  DOT_VX_GITIGNORE,
+  executablePath,
+  gitEnv,
+  refuseSymlink,
+  relPosix,
+  UserError,
+  ui,
+  writeNoFollow,
+} from '../util/index.js'
 import { VERSION } from '../version.js'
 import { WORKSPACE_CONFIG_FILENAMES } from './project-loader.js'
 
+/** The root config `vx init` writes outside a Turbo or Nx repo: no task yet. */
+export function starterProject(format: MigrationFormat): string {
+  return format === 'ts'
+    ? "import type { ProjectConfig } from '@vzn/vx/config'\n\nexport default { tasks: {} } satisfies ProjectConfig\n"
+    : 'export default { tasks: {} }\n'
+}
+
+/**
+ * Whether `file` is `vx init`'s starter, untouched: a migration maps over it
+ * as over no config, so the scripts `vx init` pointed at become tasks.
+ */
+export function isStarterConfig(file: string): boolean {
+  try {
+    // By extension: the mjs starter's text in a .ts file is a user's config.
+    return readFileSync(file, 'utf8') === starterProject(file.endsWith('.ts') ? 'ts' : 'mjs')
+  } catch {
+    return false
+  }
+}
+
 /**
  * Escape an arbitrary string into a single-quoted TS literal. Escapes
  * backslash + quote AND raw newlines/CR — a value with an embedded newline
@@ -208,7 +237,7 @@ export interface ApplyMigrationArgs {
   /**
    * Run after the files are written (not under `dry`): `vx lock`'s step, so
    * the migrated workspace has its .vx/projects.lock.json and its graph rules checked
-   * (owner, 2026-10-14). On success `said` is its line, shown as the
+   * (2026-10-14). On success `said` is its line, shown as the
    * report's `lock` row; a refusal (a graph rule, a plugin not installed
    * yet) prints above the report and the migration still succeeds: its
    * files are written, and `vx lock` is the step to re-run.
@@ -243,7 +272,7 @@ export async function applyMigration(args: ApplyMigrationArgs): Promise<number>
   // the whole workspace, and `--force` would have replaced the hand-written
   // file; `--force` still replaces, as asked.
   const kept: string[] = []
-  // Every project gets a config, a task-less one too (owner, 2026-10-14:
+  // Every project gets a config, a task-less one too (2026-10-14:
   // "no skips. every project gets a config"): solidjs/solid's solid-ssr,
   // with no script Turbo runs, was left with none and read as a project
   // whose tasks are not locked.
@@ -263,7 +292,13 @@ export async function applyMigration(args: ApplyMigrationArgs): Promise<number>
   // A plan never maps a workspace root that has a config (D-45), even
   // under `--force`; its file stays, so it is named with the rest (X-27).
   const rootConfig = metas.find((m) => m.dir === root)?.configPath
-  if (init && rootConfig && !projects.some((p) => p.dir === root && p.tasks.length > 0)) {
+  // A one-package repo's root is a mapped member too: the filter kept it already.
+  if (
+    init &&
+    rootConfig &&
+    !kept.includes(relPosix(root, rootConfig)) &&
+    !projects.some((p) => p.dir === root && p.tasks.length > 0)
+  ) {
     kept.push(relPosix(root, rootConfig))
   }
   if (empty && !init) {
@@ -298,7 +333,7 @@ export async function applyMigration(args: ApplyMigrationArgs): Promise<number>
     files.push({
       relPath: relPosix(root, abs),
       abs,
-      contents: workspaceFile(format, args.plugins ?? []),
+      contents: renderWorkspace(format, args.plugins ?? []),
     })
   }
   // `.vx/.gitignore` keeps the machine-local `.vx/cache` out of git and the
@@ -308,6 +343,15 @@ export async function applyMigration(args: ApplyMigrationArgs): Promise<number>
     files.push({ relPath: '.vx/.gitignore', abs: dotVxIgnore, contents: DOT_VX_GITIGNORE })
   }
 
+  // A plan is a mapper's reading of the repo's own files (an Nx node's
+  // `root`, a workspace glob): one that names `../x` wrote outside it.
+  for (const f of files) {
+    const rel = relPosix(root, f.abs)
+    if (rel === '..' || rel.startsWith('../') || path.isAbsolute(rel)) {
+      throw new UserError(`${f.relPath}: outside the workspace root`)
+    }
+  }
+
   if (!dry && !force) {
     const conflicts = new Set<string>()
     // A discovered project with ANY existing vx config (.ts/.mjs/.js) — refuse
@@ -321,7 +365,7 @@ export async function applyMigration(args: ApplyMigrationArgs): Promise<number>
     // scan alone would miss an existing vx.config.ts at that path and clobber
     // it. This also covers the extraFiles (vx-preset.ts).
     for (const f of files) {
-      if (await Bun.file(f.abs).exists()) conflicts.add(f.relPath)
+      if ((await Bun.file(f.abs).exists()) && !isStarterConfig(f.abs)) conflicts.add(f.relPath)
     }
     if (conflicts.size > 0) {
       throw new UserError(
@@ -342,10 +386,11 @@ export async function applyMigration(args: ApplyMigrationArgs): Promise<number>
   }
   if (dry && args.json !== true) {
     for (const f of files) {
-      process.stdout.write(`── ${f.relPath} ──\n${f.contents}\n`)
+      ui.print('out', ui.excerpt(f.relPath, f.contents))
     }
   } else if (!dry) {
-    for (const f of files) await Bun.write(f.abs, f.contents)
+    for (const f of files) refuseSymlink(f.abs)
+    for (const f of files) await writeNoFollow(f.abs, f.contents)
     for (const f of replaced) await unlink(f)
     // The lock that follows loads its plugins from the file just written.
     workspaceFileWritten()
@@ -387,7 +432,7 @@ export async function applyMigration(args: ApplyMigrationArgs): Promise<number>
   // refuse without: a git work tree (vx keys inputs on git's view) and,
   // with no scripts mapped, a task to run.
   // `vx init` installs vx globally first: the line names vx alone, never
-  // a package manager's runner (owner, 2026-10-22: vx owns the command).
+  // a package manager's runner (2026-10-22: vx owns the command).
   const run = `vx run ${firstTask} --all`
   // A run reads configs only from the lock; with no lock step here
   // (`--no-install`), that run stopped with "no lock: run `vx lock`".
@@ -625,12 +670,15 @@ function exampleConfig(format: MigrationFormat): string {
 
 // ─── TS emission ──────────────────────────────────────────────────────
 
-// Type-only import + `satisfies`, like the project configs: a runtime
-// `import { defineWorkspace } from '@vzn/vx'` loads a SECOND copy of core
-// into every run — measured 2026-09-09 at ~17 ms on a two-package
-// workspace, a fifth of the whole run — for an identity function.
-// No explanatory comment: the file is the user's (owner, 2026-10-06).
-function workspaceFile(format: MigrationFormat, plugins: readonly WorkspacePlugin[]): string {
+// Type-only import + `satisfies`, like the project configs: Bun erases it,
+// so the file loads with nothing installed, and a user's tsc checks it
+// against config.ts alone, where `@vzn/vx` walks core's Bun-only sources
+// (527 errors, J-94). `vx init` writes the same file.
+// No explanatory comment: the file is the user's (2026-10-06).
+export function renderWorkspace(
+  format: MigrationFormat,
+  plugins: readonly WorkspacePlugin[],
+): string {
   const imports = plugins.map((p) => `import { ${p.factory} } from '${p.pkg}'\n`).join('')
   const body = `export default { plugins: [${plugins.map((p) => `${p.factory}()`).join(', ')}] }`
   return format === 'ts'
@@ -667,8 +715,8 @@ function renderConfigFile(p: GeneratedProject, format: MigrationFormat): string
   // package, and Bun erases it, so the config loads in a workspace that
   // runs the vx binary without the package installed. `mjs` is the same
   // object with nothing to erase.
-  // No "generated by" header: the file is the user's from here (owner,
-  // 2026-10-06), and each TODO(vx-migrate) sits on its own task.
+  // No "generated by" header: the file is the user's from here
+  // (2026-10-06), and each TODO(vx-migrate) sits on its own task.
   const lines: string[] = []
   if (format === 'ts') lines.push("import type { ProjectConfig } from '@vzn/vx/config'")
   if (p.importLines.length > 0) lines.push(...p.importLines)
@@ -752,7 +800,10 @@ function ownConfigNamed(
 
 function readManifest(dir: string): { type?: unknown } | undefined {
   try {
-    return JSON.parse(readFileSync(path.join(dir, 'package.json'), 'utf8')) as { type?: unknown }
+    // A byte-order mark is stripped, as npm strips it.
+    return JSON.parse(readFileSync(path.join(dir, 'package.json'), 'utf8').replace(/^/, '')) as {
+      type?: unknown
+    }
   } catch {
     return undefined
   }

package/src/workspace/package-graph.ts

@@ -20,8 +20,9 @@ export interface PackageGraph {
  * no plugin edge names but the task graph does; without it
  * `--filter '...app'` never selected `e2e`, and a CI that runs "what
  * changed and everything depending on it" silently left it out
- * (2026-09-10). The `^task` walk still reads `directDeps`, which carries
- * both — a task edge IS a dependency.
+ * (2026-09-10). Selection, `vx watch` and the dependency rules pass them;
+ * the graph a run or `vx lock` resolves `^task` against does not (it is
+ * built before configs load), so a task edge never widens a `^task` walk.
  */
 export function buildPackageGraph(
   projects: ProjectMeta[],
@@ -30,8 +31,8 @@ export function buildPackageGraph(
   const byName = new Map<string, ProjectMeta>()
   for (const p of projects) byName.set(p.name, p)
 
-  // Two adjacencies. ORDER (`directDeps`, the `^task` walk) is the task
-  // edges and a `discover` plugin's `deps`. REACH (the transitive closures
+  // Two adjacencies. ORDER (`directDeps`, the `^task` walk) is a
+  // `discover` plugin's `deps`, plus the task edges when passed. REACH (the transitive closures
   // `--filter pkg...` and `--affected` read) is ORDER plus a plugin's
   // `reach`, which never orders a build.
   const directDeps = new Map<string, string[]>()