diff --git a/docs/desktop-application-capture.md b/docs/desktop-application-capture.md index 78481021b9..5516829280 100644 --- a/docs/desktop-application-capture.md +++ b/docs/desktop-application-capture.md @@ -59,12 +59,17 @@ the current directory, as it would from a shell, and a relative path to it is resolved there. An `env -i`, `env --ignore-environment` or `env -` prefix drops the -inherited environment before applying any assignments in the command. The -short options can be combined, as in `env -iC /path/to/work app`. +inherited environment. Use `env -u NAME` or `env --unset=NAME` to remove +individual variables. Assignments in the command are applied afterward. +The short options can be combined, as in `env -iC /path/to/work app`. Inventory uses the resulting XDG roots and the Linux system search path -when the prefix leaves `PATH` unset. During capture, REA passes its run -token after the prefix's assignments so it can still identify the app's -processes after the launcher exits. +when the prefix leaves `PATH` unset. For a direct launch that removes +the inherited `HOME`, REA uses an absolute replacement if provided. +Otherwise it reports that the application's default home paths are +unknown and still discovers state in explicitly set absolute XDG roots. +Use `--state-path` to include other known paths. During capture, REA +passes its run token after the prefix's assignments so it can still +identify the app's processes after the launcher exits. A nested desktop file uses a dashed ID: `vendor/app.desktop` has ID `vendor-app`. REA checks path spellings that can encode that ID within each diff --git a/docs/desktop-application-export.md b/docs/desktop-application-export.md index 91e22f3d99..5203dfd787 100644 --- a/docs/desktop-application-export.md +++ b/docs/desktop-application-export.md @@ -153,7 +153,13 @@ The class declares: captured working directory (`"$HOME"` when that was the home, as for a desktop entry without `Path`), which a relative argument or program path such as `./app` also needs, and still starts if that folder is missing. The - export refuses a capture that saw no application window. + export refuses a capture that saw no application window. When a launch path + traversed a parent directory through a symlink, export uses the recorded + physical state paths to place the seed and respell the launch together. + A file argument follows the file's seed location. A launch directory must + preserve the relative paths to its retained files. If those files cannot + share a replay location, capture again with an explicit home or XDG + directory without parent traversal. - The seed's document, opened at launch, so the app shows it rather than its start screen: when the seed holds exactly one file the state view gives the `document` role, and the desktop entry's `Exec` takes files (a `%f`, `%F`, diff --git a/docs/desktop-build-computer.md b/docs/desktop-build-computer.md index a6bb953502..824d942350 100644 --- a/docs/desktop-build-computer.md +++ b/docs/desktop-build-computer.md @@ -47,6 +47,10 @@ Node.js, procps `ps`, the Docker CLI, a Docker daemon reachable without `sudo`, 20 GB free where Docker keeps images, agentenv-framework 0.9.1485, the runtime archive of this REA version, the build settings in the registration or the environment, and the skill. Each failure names its fix. +Doctor reads the selected runtime archive without extracting it. The archive +must supply one launcher at `scripts/rea.mjs` under a visible top folder. +When doctor can identify the intended folder, it reports its declared package +version even if the launcher is unusable. It also reports, without counting them against `healthy`, whether a model endpoint for solver runs is configured and which agentenv containers earlier builds left. Pass `--json` for the full report. diff --git a/src/application/desktop/DesktopApplicationExport.test.ts b/src/application/desktop/DesktopApplicationExport.test.ts index 4304f2fbba..c4a35f5a2a 100644 --- a/src/application/desktop/DesktopApplicationExport.test.ts +++ b/src/application/desktop/DesktopApplicationExport.test.ts @@ -1,6 +1,13 @@ import { execFile } from "node:child_process"; import { createHash } from "node:crypto"; -import { access, readFile, writeFile } from "node:fs/promises"; +import { + access, + mkdir, + readFile, + realpath, + symlink, + writeFile, +} from "node:fs/promises"; import { join } from "node:path"; import { promisify } from "node:util"; @@ -287,6 +294,268 @@ describe("exportDesktopApplication", () => { }); }); +it.skipIf(process.platform === "win32")( + "replays a traversing launch root at the same path used for seed files and selected aliases", + async () => { + const home = await realpath( + await createTestTempDirectory("desktop-source-"), + ); + const base = `${home}/profiles//current/..`; + const logical = `${base}/./notes`; + await mkdir(`${home}/profiles`); + await mkdir(`${home}/resolved/profile`, { recursive: true }); + await mkdir(`${home}/resolved/notes`); + await symlink(`${home}/resolved/profile`, `${home}/profiles/current`); + const physical = await realpath(logical); + const settings = `${physical}/settings.ini`; + const text = "[ui]\nwrap=false\n"; + await writeFile(settings, text); + const local = capture(); + const { result, directory } = await exportCapture({ + ...local, + host: { ...local.host, home }, + application: { + ...local.application, + argv: [ + "env", + `XDG_CONFIG_HOME=${base}`, + "MODE=dark", + "sh", + "-c", + 'test "$MODE" = dark && test "$2" = --theme=dark && test "$3" = --line=10 && cat "$XDG_CONFIG_HOME/notes/settings.ini" "$1" "$4"', + "notes", + `${logical}/settings.ini`, + "--theme=dark", + "--line=10", + "settings.ini", + ], + working_directory: logical, + state_directories: [{ path: logical, exists_at_start: true }], + }, + state: { + ...local.state, + roots: [home], + content_roots: [physical], + state_directories: [physical], + selected_paths: [ + { path: `${home}/settings`, physical, kind: "directory" }, + ], + checkpoints: [ + checkpoint("baseline", "baseline", [], [retained(settings, text)]), + ], + }, + }); + if (result instanceof Error) throw result; + expect(result.normalized_result).toMatchObject({ + paths: ["resolved/notes"], + seed_files: ["resolved/notes/settings.ini"], + }); + + const replay = await createTestTempDirectory("desktop-replay-"); + const { stdout } = await execute("python3", [ + "-I", + "-B", + "-c", + `import ast, subprocess, sys +from pathlib import Path +module = Path(sys.argv[1]) +home = Path(sys.argv[2]) +tree = ast.parse(module.read_text(encoding="utf-8")) +launch = next(node for node in ast.walk(tree) if isinstance(node, ast.Call) and getattr(node.func, "id", "") == "Launch") +command = ast.literal_eval(next(key.value for key in launch.keywords if key.arg == "command")) +tree.body = [node for node in tree.body + if not isinstance(node, ast.ClassDef) + and (not isinstance(node, ast.ImportFrom) or not node.module.startswith("agentenv_protocol"))] +scope = {"__file__": str(module)} +exec(compile(tree, str(module), "exec"), scope) +scope["_seed_home"](home) +scope["_ensure_state_aliases"](home) +assert (home / "settings/settings.ini").read_bytes() == (home / "resolved/notes/settings.ini").read_bytes() +assert not (home / "profiles").exists() +subprocess.run(command, env={"HOME": str(home), "PATH": "/usr/bin:/bin"}, check=True)`, + join(directory, "envs/notes/notes_app.py"), + replay, + ]); + expect(stdout).toBe(text.repeat(3)); + }, +); + +it.each([ + { option: "--theme=dark/variant", refused: false }, + { option: "--settings=dark", refused: true }, +])( + "requires observed path evidence before refusing $option", + async ({ option, refused }) => { + const local = capture(); + const logical = `${HOME}/profiles/current/../notes`; + const physical = `${HOME}/resolved/notes`; + const external = "/mnt/shared/themes"; + const { result, directory } = await exportCapture({ + ...local, + application: { + ...local.application, + argv: ["notes", option, "settings.ini"], + working_directory: logical, + state_directories: [ + { path: logical, exists_at_start: true }, + { path: `${logical}/dark`, exists_at_start: true }, + ], + }, + state: { + ...local.state, + content_roots: [physical, external], + state_directories: [physical, external], + selected_paths: [], + checkpoints: [ + checkpoint( + "baseline", + "baseline", + [], + [retained(`${physical}/settings.ini`, "[ui]\nwrap=false\n")], + ), + ], + }, + }); + if (refused) { + expect(result).toBeInstanceOf(AnalysisInputError); + expect(await exists(directory)).toBe(false); + return; + } + if (result instanceof Error) throw result; + const module = await readFile( + join(directory, "envs/notes/notes_app.py"), + "utf8", + ); + const launch = module + .split("\n") + .find((line) => line.includes("launch=Launch(")); + expect(launch).toContain(option); + expect(launch).toContain("resolved/notes/settings.ini"); + }, +); + +it("writes portable seed names for state paths with empty or self-directory components", async () => { + const local = capture(); + const physical = `${HOME}/.config/notes`; + const { result, directory } = await exportCapture({ + ...local, + application: { + ...local.application, + state_directories: [ + { path: `${HOME}/./.config//notes`, exists_at_start: true }, + ], + }, + state: { + ...local.state, + content_roots: [physical], + state_directories: [physical], + checkpoints: [ + checkpoint( + "baseline", + "baseline", + [], + [retained(`${physical}/settings.ini`, "[ui]\nwrap=false\n")], + ), + ], + }, + }); + if (result instanceof Error) throw result; + expect(result.normalized_result).toMatchObject({ + seed_files: [".config/notes/settings.ini"], + }); + expect( + await readFile( + join(directory, "envs/notes/seed/.config/notes/settings.ini"), + "utf8", + ), + ).toBe("[ui]\nwrap=false\n"); +}); + +it("refuses a traversing launch root with conflicting seed locations", async () => { + const local = capture(); + const base = `${HOME}/profiles/current/..`; + const settings = [`${HOME}/first/notes`, `${HOME}/second/notesrc`]; + const { result, directory } = await exportCapture({ + ...local, + application: { + ...local.application, + argv: ["env", `XDG_CONFIG_HOME=${base}`, "notes"], + state_directories: [ + { path: `${base}/notes`, exists_at_start: true }, + { path: `${base}/notesrc`, exists_at_start: true }, + ], + }, + state: { + ...local.state, + content_roots: settings, + state_directories: settings, + }, + }); + expect(result).toBeInstanceOf(AnalysisInputError); + if (!(result instanceof AnalysisInputError)) + throw new Error("expected export refusal"); + expect(result.userMessage).toContain("do not agree on a replay location"); + expect(await exists(directory)).toBe(false); +}); + +it.each(["file", "directory", "ancestor"] as const)( + "reconciles a traversing %s launch path with a separately selected seed", + async (kind) => { + const local = capture(); + const base = `${HOME}/profiles/current/..`; + const logical = `${base}/notes`; + const physical = `${HOME}/resolved/notes`; + const settings = `${physical}/settings.ini`; + const selected = `${HOME}/Documents/settings.ini`; + const { result, directory } = await exportCapture({ + ...local, + application: { + ...local.application, + argv: + kind === "file" + ? ["notes", `${logical}/settings.ini`] + : [ + "env", + `XDG_CONFIG_HOME=${kind === "directory" ? logical : base}`, + "notes", + ], + state_directories: [{ path: logical, exists_at_start: true }], + }, + state: { + ...local.state, + content_roots: [physical], + state_directories: [physical], + selected_paths: [{ path: selected, physical: settings, kind: "file" }], + checkpoints: [ + checkpoint( + "baseline", + "baseline", + [], + [retained(settings, "[ui]\nwrap=false\n")], + ), + ], + }, + }); + if (kind !== "file") { + expect(result).toBeInstanceOf(AnalysisInputError); + expect(await exists(directory)).toBe(false); + return; + } + if (result instanceof Error) throw result; + expect(result.normalized_result).toMatchObject({ + seed_files: ["Documents/settings.ini"], + }); + const module = await readFile( + join(directory, "envs/notes/notes_app.py"), + "utf8", + ); + const launch = module + .split("\n") + .find((line) => line.includes("launch=Launch(")); + expect(launch).toContain("Documents/settings.ini"); + }, +); + it("seeds the app's state at its own path and retains a selected alias", async () => { const local = capture(); const physical = `${HOME}/.config/notes`; diff --git a/src/application/desktop/DesktopApplicationExport.ts b/src/application/desktop/DesktopApplicationExport.ts index 34e96530df..2b3033846d 100644 --- a/src/application/desktop/DesktopApplicationExport.ts +++ b/src/application/desktop/DesktopApplicationExport.ts @@ -240,7 +240,10 @@ const planExport = async ( paths, seed: context.seed, }); - const launch = planLaunch(capture, electron, seeds, files); + const launch = planLaunch(capture, electron, seeds, { + ...stateFiles, + restoredFiles: versions.seeds.keys(), + }); const plan: DesktopAppExportPlan = { viewPolicy: request.viewPolicy, name: source, diff --git a/src/application/desktop/DesktopExportLaunch.test.ts b/src/application/desktop/DesktopExportLaunch.test.ts index 05766c645e..665c36907a 100644 --- a/src/application/desktop/DesktopExportLaunch.test.ts +++ b/src/application/desktop/DesktopExportLaunch.test.ts @@ -2,8 +2,21 @@ import { describe, expect, it } from "vitest"; import type { DesktopApplicationCapture } from "../../domain/desktop/desktopCapture.js"; import type { DesktopApplicationState } from "../../domain/desktop/desktopState.js"; +import { capturedHomePlan } from "../../domain/desktop/appExport.js"; import { planLaunch } from "./DesktopExportLaunch.js"; +const launchWithReplay = ( + capture: DesktopApplicationCapture, + electron: boolean, + seeds: Parameters[2], + files: ReadonlyMap, +) => + planLaunch(capture, electron, seeds, { + ...capturedHomePlan(capture), + files, + restoredFiles: seeds.keys(), + }); + const HOME = "/home/ada"; type StatePath = DesktopApplicationState["paths"][number]; @@ -35,7 +48,7 @@ describe("planLaunch captured paths", () => { const seeds = new Map([ ["selected/project.txt", { sha256: "a".repeat(64), format: "text" }], ]); - const launch = planLaunch(capture, false, seeds, files); + const launch = launchWithReplay(capture, false, seeds, files); expect(launch.opens).toEqual({ kind: "captured" }); expect(launch.command[2]).toContain('cd "$HOME"/'); expect(launch.command[2]).toMatch(/'-C'[^;]+\$HOME[^;]+selected/u); @@ -71,7 +84,7 @@ describe("planLaunch captured paths", () => { const seeds = new Map([ ["Documents/books.db", { sha256: "a".repeat(64), format: "text" }], ]); - const launch = planLaunch(capture, false, seeds, files); + const launch = launchWithReplay(capture, false, seeds, files); expect(launch.opens).toEqual({ kind: "captured" }); expect(launch.command.join(" ")).toContain("Documents/books.db"); expect(launch.command.join(" ")).not.toContain("/mnt/data/books.db"); @@ -103,9 +116,12 @@ describe("planLaunch captured paths", () => { const files = new Map([ ["Documents/books.db", file("/mnt/data/books.db", "document")], ]); - const command = planLaunch(capture, false, new Map(), files).command.join( - " ", - ); + const command = launchWithReplay( + capture, + false, + new Map(), + files, + ).command.join(" "); expect(command).toContain("/mnt/other/unselected.db"); }); }); @@ -132,9 +148,12 @@ describe("planLaunch URL and argument spelling", () => { const files = new Map([ ["Documents/A budget.svg", file(physical, "document")], ]); - const command = planLaunch(capture, false, new Map(), files).command.join( - " ", - ); + const command = launchWithReplay( + capture, + false, + new Map(), + files, + ).command.join(" "); expect(command).toContain("/Documents/%41%20budget.svg?mode=edit#page"); }); @@ -159,9 +178,12 @@ describe("planLaunch URL and argument spelling", () => { const files = new Map([ ["Documents/A budget.svg", file(physical, "document")], ]); - const command = planLaunch(capture, false, new Map(), files).command.join( - " ", - ); + const command = launchWithReplay( + capture, + false, + new Map(), + files, + ).command.join(" "); expect(command).toContain("file://localhost"); expect(command).toContain("/Documents/%41%20budget.svg?mode=edit#page"); expect(command).not.toContain("/data/%41%20budget.svg"); @@ -198,9 +220,12 @@ describe("planLaunch URL and argument spelling", () => { }, } as unknown as DesktopApplicationCapture; - const command = planLaunch(capture, false, new Map(), files).command.join( - " ", - ); + const command = launchWithReplay( + capture, + false, + new Map(), + files, + ).command.join(" "); expect(command).toContain(`"$HOME"/'.config/geany/profiles/work'`); expect(command).toContain("'--line=10'"); @@ -230,7 +255,7 @@ describe("planLaunch URL and argument spelling", () => { const note = file(`${HOME}/work/note.txt`, "document"); files.set("work/note.txt", note); - const command = planLaunch( + const command = launchWithReplay( capture, false, new Map([["work/note.txt", { sha256: "a".repeat(64), format: "text" }]]), diff --git a/src/application/desktop/DesktopExportLaunch.ts b/src/application/desktop/DesktopExportLaunch.ts index 474ab272b3..bdcf2d8d16 100644 --- a/src/application/desktop/DesktopExportLaunch.ts +++ b/src/application/desktop/DesktopExportLaunch.ts @@ -1,8 +1,9 @@ import { - capturedHomePath, + type capturedHomePlan, launchCommand, type DesktopAppExportPlan, } from "../../domain/desktop/appExport.js"; +import { AnalysisInputError } from "../../domain/analysisErrorCore.js"; import { electronLaunchArguments } from "../../domain/desktop/appExportInstall.js"; import type { DesktopApplicationCapture } from "../../domain/desktop/desktopCapture.js"; import { @@ -114,14 +115,46 @@ export const planLaunch = ( capture: DesktopApplicationCapture, electron: boolean, seeds: ReadonlyMap, - files: ReadonlyMap, + replay: Pick< + ReturnType, + "homePath" | "launchPath" + > & { + readonly files: ReadonlyMap; + readonly restoredFiles: Iterable; + }, ): Pick => { const { application, host } = capture; + const { files, homePath: homeOf } = replay; const isDocument = (home: string) => files.get(home)?.role === "document"; - const homeOf = capturedHomePath(capture); + const retained = new Map(); + for (const home of replay.restoredFiles) { + const file = files.get(home); + if (file !== undefined) retained.set(file.path, home); + } + const fileSources = [...files.values()].map((file) => file.path); + const observedFile = (path: string) => + fileSources.some((physical) => isWithinAny(physical, [path])); + const mapTraversal = (path: string, as: "explicit" | "inferred") => { + const mapped = replay.launchPath( + path, + retained, + as === "inferred" ? observedFile : undefined, + ); + if (mapped === null) + throw new AnalysisInputError("export_desktop_application", { + userMessage: `Captured paths under ${JSON.stringify(path)} do not agree on a replay location.`, + remediationAction: + "Capture the app again with an explicit state directory that does not traverse parent segments.", + conformsToInputContract: true, + }); + return mapped; + }; const capturedDirectory = application.application_working_directory ?? application.working_directory; const seedDirectory = (directory: string): string => { + const mapped = mapTraversal(directory, "explicit"); + if (mapped?.kind === "mapped") + return mapped.path === "" ? host.home : `${host.home}/${mapped.path}`; if (!directory.startsWith(`${host.home}/`)) return directory; const relative = directory.slice(host.home.length + 1); const seed = homeOf(directory) ?? relative; @@ -161,6 +194,7 @@ export const planLaunch = ( isCaptured: capturedLaunchPaths(capture, files, homeOf), spell: (path) => homeOf(`${host.home}/${path}`) ?? path, mapOutside: homeOf, + mapTraversal, }); return { command: launchCommand( diff --git a/src/desktop/ApplicationStateDirectories.ts b/src/desktop/ApplicationStateDirectories.ts index 665fe89d6c..a206e66e1f 100644 --- a/src/desktop/ApplicationStateDirectories.ts +++ b/src/desktop/ApplicationStateDirectories.ts @@ -9,7 +9,7 @@ import { errorMessage } from "../kernel/errorMessage.js"; /** The environment whose XDG folders, and the home whose dot-folders, may hold the application's state. */ interface StateLocations { readonly environment: Readonly>; - readonly home: string; + readonly home: string | undefined; } /** @@ -66,16 +66,15 @@ export const stateDirectories = async ( { environment, home }: StateLocations, extra: readonly string[], ): Promise => { - const config = xdgBase( - environment.XDG_CONFIG_HOME, - appendCallerPath(home, ".config"), - ); + const homeChild = (path: string) => + home === undefined ? undefined : appendCallerPath(home, path); + const config = xdgBase(environment.XDG_CONFIG_HOME, homeChild(".config")); const bases = [ config, - xdgBase(environment.XDG_DATA_HOME, appendCallerPath(home, ".local/share")), - xdgBase(environment.XDG_STATE_HOME, appendCallerPath(home, ".local/state")), - xdgBase(environment.XDG_CACHE_HOME, appendCallerPath(home, ".cache")), - ]; + xdgBase(environment.XDG_DATA_HOME, homeChild(".local/share")), + xdgBase(environment.XDG_STATE_HOME, homeChild(".local/state")), + xdgBase(environment.XDG_CACHE_HOME, homeChild(".cache")), + ].filter((base): base is string => base !== undefined); const variants = new Set( names .filter( @@ -88,20 +87,25 @@ export const stateDirectories = async ( .flatMap((name) => [name, name.toLowerCase()]), ); const lowered = new Set([...variants].map((name) => name.toLowerCase())); - const dotfiles = (await readdir(home).catch(() => [] as string[])) - .filter((entry) => appNamedDotfile(entry, variants)) - .map((entry) => appendCallerPath(home, entry)); + const dotfiles = + home === undefined + ? [] + : (await readdir(home).catch(() => [] as string[])) + .filter((entry) => appNamedDotfile(entry, variants)) + .map((entry) => appendCallerPath(home, entry)); // A folder present in another letter case than any name, such as GIMP's `~/.config/GIMP`, is the application's too. const recased = await Promise.all([ ...bases.map((base) => recasedEntries(base, "", lowered)), - recasedEntries(home, ".", lowered), + ...(home === undefined ? [] : [recasedEntries(home, ".", lowered)]), ]); const paths = new Set([ ...[...variants].flatMap((name) => [ ...bases.map((base) => appendCallerPath(base, name)), - appendCallerPath(home, `.${name}`), + ...(home === undefined ? [] : [appendCallerPath(home, `.${name}`)]), // KDE's settings file, such as Tellico's `~/.config/tellicorc`, which the app may first write during the capture. - ...(name.length < 3 ? [] : [appendCallerPath(config, `${name}rc`)]), + ...(config === undefined || name.length < 3 + ? [] + : [appendCallerPath(config, `${name}rc`)]), ]), ...recased.flat(), ...dotfiles, diff --git a/src/desktop/DesktopBuildDoctorFacts.ts b/src/desktop/DesktopBuildDoctorFacts.ts index b01ba1a0c2..f9833ab8db 100644 --- a/src/desktop/DesktopBuildDoctorFacts.ts +++ b/src/desktop/DesktopBuildDoctorFacts.ts @@ -20,6 +20,7 @@ import { RetainedRegularFileCleanupFailure, } from "../process/RegularFileRead.js"; import { DESKTOP_EXPORT_FRAMEWORK_VERSION } from "../domain/desktop/appExport.js"; +import { PYTHON_BUILD_ARCHIVE_PROBE } from "../domain/desktop/appBuildArchive.js"; import { PRODUCT_IDENTITY } from "../identity.js"; import { execFileOutputFailure } from "../process/ExecFileOutput.js"; import { describeSystemPs, resolveSystemPs } from "../process/systemPs.js"; @@ -46,25 +47,6 @@ const CONFIG_BYTES = 1024 * 1024; const missingPath = (cause: unknown): boolean => cause instanceof Error && "code" in cause && cause.code === "ENOENT"; -/** Inspect the same tar compression formats as the build's Python extractor without extracting files. */ -const ARCHIVE_VERSION = String.raw` -import json, pathlib, sys, tarfile -roots, versions = set(), {} -with tarfile.open(sys.argv[1], "r|*") as archive: - for entry in archive: - parts = pathlib.PurePosixPath(entry.name).parts - if len(parts) == 3 and parts[1:] == ("scripts", "rea.mjs") and (entry.isfile() or entry.issym()): - roots.add(parts[0]) - elif len(parts) == 2 and parts[1] == "package.json" and entry.isfile() and entry.size <= 1048576: - stream = archive.extractfile(entry) - if stream is not None: - try: - versions[parts[0]] = json.load(stream).get("version") - except (ValueError, UnicodeError, AttributeError): - pass -print(json.dumps({"version": versions.get(next(iter(roots))) if len(roots) == 1 else None})) -`; - /** Read what a desktop build needs from this host, changing nothing. */ export const readDesktopBuildFacts = async ( input: DesktopBuildFactsInput, @@ -277,7 +259,12 @@ const agentEnvVersion = async ( return reported.ok ? agentEnvReportedVersion(reported.stdout) : undefined; }; -/** The setup-packed archive is named by its version; another is read for its package version. */ +const archiveObservationSchema = z.object({ + version: z.string().nullable(), + problem: z.string().nullable(), +}); + +/** Read layout and package version for the selected archive without extracting it. */ const archiveFact = async ( input: DesktopBuildFactsInput, pythonForArchive: () => Promise, @@ -302,7 +289,6 @@ const archiveFact = async ( detail: `REA could not inspect ${path}: ${errorMessage(cause)}`, }; } - if (source === "cache") return { path, source, status: "current" }; const python = await pythonForArchive(); if (python === undefined) return { @@ -314,7 +300,7 @@ const archiveFact = async ( const packed = await attempt(input, python, [ "-I", "-c", - ARCHIVE_VERSION, + PYTHON_BUILD_ARCHIVE_PROBE, path, ]); if (!packed.ok) @@ -324,15 +310,24 @@ const archiveFact = async ( status: "unknown", detail: `REA could not inspect ${path}: ${packed.reason}`, }; - let version: unknown; - try { - version = (JSON.parse(packed.stdout) as { version?: unknown }).version; - } catch { - version = undefined; + const parsed = safeParseJson(packed.stdout); + const observation = parsed.ok + ? archiveObservationSchema.safeParse(parsed.value) + : undefined; + if (observation?.success === true && observation.data.problem !== null) { + const { version, problem } = observation.data; + return { + path, + source, + status: "invalid", + detail: `${version === null ? path : `${path} declares REA ${version}`}. ${problem}`, + }; } + const version = + observation?.success === true ? observation.data.version : null; return version === PRODUCT_IDENTITY.packageVersion ? { path, source, status: "current" } - : typeof version !== "string" + : version === null ? { path, source, @@ -343,7 +338,7 @@ const archiveFact = async ( path, source, status: "stale", - detail: `${path} holds REA ${typeof version === "string" ? version : "of an unknown version"}; this is REA ${PRODUCT_IDENTITY.packageVersion}.`, + detail: `${path} holds REA ${version}; this is REA ${PRODUCT_IDENTITY.packageVersion}.`, }; }; diff --git a/src/desktop/LinuxApplicationInventory.test.ts b/src/desktop/LinuxApplicationInventory.test.ts index 5b84671e72..6813afa520 100644 --- a/src/desktop/LinuxApplicationInventory.test.ts +++ b/src/desktop/LinuxApplicationInventory.test.ts @@ -1170,6 +1170,99 @@ it.skipIf(process.platform === "win32").each([ describe.skipIf(process.platform !== "linux")( "clean env launch inventory", () => { + it.each([false, true])( + "drops inherited PATH and XDG config before applying replacements: %s", + async (explicit) => { + const installed = await fixture(); + const { home, bin, environment } = installed; + const ambient = join(home, "ambient"); + const selected = join(home, "selected"); + await writeFile(join(bin, "true"), "#!/bin/sh\nexit 2\n", { + mode: 0o755, + }); + const prefix = [ + "/usr/bin/env", + "-uPATH", + "--unset", + "XDG_CONFIG_HOME", + "-C", + home, + ...(explicit ? [`PATH=${bin}`, `XDG_CONFIG_HOME=${selected}`] : []), + ]; + await writeFile( + join( + environment.XDG_DATA_DIRS, + "applications/org.example.notes.desktop", + ), + `[Desktop Entry]\nType=Application\nName=Notes\nExec=${prefix.join(" ")} true -u argument\n`, + ); + const inventory = await inventoryOf("org.example.notes", { + ...installed, + environment: { ...environment, XDG_CONFIG_HOME: ambient }, + }); + expect(inventory.argv).toEqual([...prefix, "true", "-u", "argument"]); + expect(inventory.executable.path).toBe( + explicit ? join(bin, "true") : "/bin/true", + ); + expect(inventory.application_working_directory).toBe(home); + const paths = inventory.state_directories.map(({ path }) => path); + expect(paths).toContain( + join(explicit ? selected : join(home, ".config"), "true"), + ); + expect(paths).not.toContain(join(ambient, "true")); + }, + ); + + it.each([undefined, "relative-home", "/selected-profile"])( + "discovers explicit XDG roots after HOME is unset with replacement %s", + async (replacement) => { + const { home, bin, environment } = await fixture(); + const config = join(home, "selected-config"); + await mkdir(join(config, "notes-app"), { recursive: true }); + const prefix = [ + "/usr/bin/env", + "-uHOME", + `XDG_CONFIG_HOME=${config}`, + ...(replacement === undefined ? [] : [`HOME=${replacement}`]), + ]; + await writeFile( + join( + environment.XDG_DATA_DIRS, + "applications/org.example.notes.desktop", + ), + `[Desktop Entry]\nType=Application\nName=Notes\nExec=${prefix.join(" ")} ${bin}/notes-app\n`, + ); + const inspected = await inspectLinuxApplication({ + desktopEntry: "org.example.notes", + executable: undefined, + arguments: [], + environment: { + ...environment, + HOME: home, + XDG_DATA_HOME: "relative-data", + }, + home, + callerDirectory: home, + }); + if (!inspected.ok) throw new Error(inspected.error.reason); + expect(inspected.value.inventory.state_directories).toContainEqual({ + path: join(config, "notes-app"), + exists_at_start: true, + }); + const paths = inspected.value.inventory.state_directories.map( + ({ path }) => path, + ); + expect(paths).not.toContain(join(home, ".notes-app")); + expect(paths).not.toContain(join(home, ".local/share/notes-app")); + const homeUnknown = inspected.value.limitations.some((limitation) => + limitation.includes("default home state paths are unknown"), + ); + expect(homeUnknown).toBe(replacement !== "/selected-profile"); + if (!homeUnknown) + expect(paths).toContain("/selected-profile/.notes-app"); + }, + ); + it.each([ ["-i", false], ["--ignore-environment", true], @@ -1204,9 +1297,9 @@ describe.skipIf(process.platform !== "linux")( explicit ? join(bin, "true") : "/bin/true", ); const paths = inventory.state_directories.map(({ path }) => path); - expect(paths).toContain( - join(explicit ? selected : join(home, ".config"), "true"), - ); + if (explicit) expect(paths).toContain(join(selected, "true")); + else expect(paths).toEqual([]); + expect(paths).not.toContain(join(home, ".config/true")); expect(paths).not.toContain(join(ambient, "true")); }, ); diff --git a/src/desktop/LinuxApplicationInventory.ts b/src/desktop/LinuxApplicationInventory.ts index 633ee82763..f035a070e0 100644 --- a/src/desktop/LinuxApplicationInventory.ts +++ b/src/desktop/LinuxApplicationInventory.ts @@ -251,14 +251,15 @@ const launchEnvironment = ( wrapper: ReturnType, inherited: LinuxApplicationRequest["environment"], ) => { - if (!wrapper.clearEnvironment) { - const environment = { ...inherited, ...wrapper.environment }; - return { environment, lookupEnvironment: environment }; - } - const environment = wrapper.environment; - // GNU env's execvp searches the Linux system path when PATH is absent. + const inheritedEnvironment = wrapper.clearEnvironment ? {} : { ...inherited }; + for (const name of wrapper.unsetEnvironment ?? []) + delete inheritedEnvironment[name]; + const environment = { ...inheritedEnvironment, ...wrapper.environment }; + // GNU env's execvp searches the Linux system path when the prefix removes PATH. + const pathRemoved = + wrapper.clearEnvironment || wrapper.unsetEnvironment?.includes("PATH"); const lookupEnvironment = - environment.PATH === undefined + pathRemoved && environment.PATH === undefined ? { ...environment, PATH: "/bin:/usr/bin" } : environment; return { environment, lookupEnvironment }; @@ -428,13 +429,14 @@ const directLaunchStateHome = ( wrapper: ReturnType, packageKind: Package["kind"], hostHome: string, -): string => { +): string | undefined => { // Sandbox-managed directories continue to use the host home. if (wrapper.kind !== "direct" || packageKind === "snap") return hostHome; const launchHome = wrapper.environment.HOME; - return launchHome !== undefined && isAbsolute(launchHome) - ? launchHome - : hostHome; + if (launchHome !== undefined && isAbsolute(launchHome)) return launchHome; + if (wrapper.clearEnvironment || wrapper.unsetEnvironment?.includes("HOME")) + return undefined; + return hostHome; }; /** Resolve what the request launches, where it came from and where it may keep state. */ @@ -447,6 +449,11 @@ export const inspectLinuxApplication = async ( if (!command.ok) return command; const { argv, workingDirectory, entry } = command.value; const wrapper = unwrapDesktopCommand(argv); + if (wrapper.invalidUnset) + return err({ + reason: "desktop_entry_invalid", + detail: "env unset does not name a variable", + }); const directory = await envApplicationDirectory( wrapper.chdir?.path, workingDirectory, @@ -517,6 +524,11 @@ export const inspectLinuxApplication = async ( wrapper.kind === "flatpak" ? null : path, entry, ); + const stateHome = directLaunchStateHome(wrapper, package_.kind, request.home); + if (stateHome === undefined) + limitations.push( + "The launch prefix provides no absolute HOME after removing the inherited value. The application's default home state paths are unknown. Select known locations with --state-path.", + ); return ok({ inventory: { desktop_entry: entry, @@ -535,7 +547,7 @@ export const inspectLinuxApplication = async ( names, { environment, - home: directLaunchStateHome(wrapper, package_.kind, request.home), + home: stateHome, }, sandboxDirectories, ), diff --git a/src/desktop/XdgBase.ts b/src/desktop/XdgBase.ts index 649cf546c5..85c3fc3eb2 100644 --- a/src/desktop/XdgBase.ts +++ b/src/desktop/XdgBase.ts @@ -9,10 +9,10 @@ import { isAbsolute } from "node:path"; * The fallback may be a thunk so a caller whose default needs the host account * never pays for that lookup when the variable already decides the folder. */ -export const xdgBase = ( +export const xdgBase = ( value: string | undefined, - fallback: string | (() => string), -): string => + fallback: Fallback | (() => Fallback), +): string | Fallback => value !== undefined && isAbsolute(value) ? value : typeof fallback === "function" diff --git a/src/domain/desktop/appBuild.test.ts b/src/domain/desktop/appBuild.test.ts index 040a98880f..20a9f0c649 100644 --- a/src/domain/desktop/appBuild.test.ts +++ b/src/domain/desktop/appBuild.test.ts @@ -62,7 +62,7 @@ describe("build bundle renderer", () => { { id: "env", type: "deploy_env", env_id: "mousepad" }, ]); const script = text(bundle.files, "envs/mousepad/install-rea.sh"); - expect(script).toContain("/opt/rea/payload/*/scripts/rea.mjs"); + expect(script).toContain('ln -sfn "$launcher" /opt/rea/rea.mjs'); expect(script).toContain( `/opt/rea/node-v${BUILD_NODE_VERSION}-linux-*/bin/node`, ); diff --git a/src/domain/desktop/appBuild.ts b/src/domain/desktop/appBuild.ts index 04839a142a..ce84f4b93f 100644 --- a/src/domain/desktop/appBuild.ts +++ b/src/domain/desktop/appBuild.ts @@ -35,6 +35,7 @@ import { INSTALL_SCRIPT, type ExportPackageFile } from "./appExportInstall.js"; import { isArmoredKey } from "./aptRepositories.js"; import { DEBIAN_PACKAGE_NAME } from "./debianPackageFile.js"; import { sha256Hex } from "../../kernel/sha256Hex.js"; +import { PYTHON_BUILD_ARCHIVE } from "./appBuildArchive.js"; /** The Node.js release the build layer runs REA with: the one REA pins. */ export const BUILD_NODE_VERSION = "24.22.1"; @@ -226,23 +227,32 @@ mkdir -p /opt/rea/payload${ : ` cp ${packageFile} ${BUILD_PACKAGE_FILE}` } -python3 - <<'PY' +launcher=$(python3 - <<'PY' import glob +from pathlib import Path import tarfile -for name, into in [(path, "/opt/rea") for path in glob.glob("node-*.tar.xz")] + [("${REA_PAYLOAD}", "/opt/rea/payload")]: +${PYTHON_BUILD_ARCHIVE} +payload = Path("/opt/rea/payload") +with tarfile.open("${REA_PAYLOAD}") as archive: + archive.extractall(payload, filter="tar") + entry, _, problem = inspect_rea_archive(archive) + if problem is not None: + raise SystemExit(problem) +launcher = payload / entry +if not launcher.is_file() or not launcher.resolve().is_relative_to(payload.resolve()): + raise SystemExit("The selected scripts/rea.mjs did not extract as a regular file.") + +for name in glob.glob("node-*.tar.xz"): with tarfile.open(name) as archive: - archive.extractall(into, filter="tar") + archive.extractall("/opt/rea", filter="tar") +print(launcher) PY -set -- /opt/rea/payload/*/scripts/rea.mjs -if [ "$#" -ne 1 ] || [ ! -f "$1" ]; then - echo "The REA archive must hold one top folder with scripts/rea.mjs." >&2 - exit 1 -fi +) ln -sf /opt/rea/node-v${BUILD_NODE_VERSION}-linux-*/bin/node /usr/local/bin/node # The archive's top folder is caller-chosen and may contain spaces. The launcher # runs a fixed path so the shell does not split that folder before Node opens it. -ln -sfn "$1" /opt/rea/rea.mjs +ln -sfn "$launcher" /opt/rea/rea.mjs printf '#!/bin/sh\\nexec /usr/local/bin/node /opt/rea/rea.mjs "$@"\\n' > /usr/local/bin/rea chmod 755 /usr/local/bin/rea rm -f node-*.tar.xz ${REA_PAYLOAD} @@ -371,12 +381,13 @@ if [ -z "$desktop" ]; then echo "No installed desktop entry $entry.desktop was found, so its command cannot be adjusted for Electron." >&2 exit 1 fi -set -- /opt/rea/payload/*/dist/domain/desktop/appExportInstall.js -if [ "$#" -ne 1 ] || [ ! -f "$1" ]; then +launcher=$(readlink /opt/rea/rea.mjs) +policy="\${launcher%/scripts/rea.mjs}/dist/domain/desktop/appExportInstall.js" +if [ ! -f "$policy" ]; then echo "The REA archive must include dist/domain/desktop/appExportInstall.js so an Electron app can use REA's launch policy." >&2 exit 1 fi -/usr/local/bin/node --input-type=module - "$1" "$desktop" <<'JS' +/usr/local/bin/node --input-type=module - "$policy" "$desktop" <<'JS' import { readFileSync, writeFileSync } from "node:fs"; import { pathToFileURL } from "node:url"; diff --git a/src/domain/desktop/appBuildArchive.ts b/src/domain/desktop/appBuildArchive.ts new file mode 100644 index 0000000000..509146ccdb --- /dev/null +++ b/src/domain/desktop/appBuildArchive.ts @@ -0,0 +1,54 @@ +/** The build runtime's archive layout, interpreted by both doctor and the offline installer. */ +export const PYTHON_BUILD_ARCHIVE = String.raw` +import json +from pathlib import PurePosixPath + + +def inspect_rea_archive(archive, read_version=False): + launchers, versions = {}, {} + for entry in archive: + parts = PurePosixPath(entry.name).parts + if len(parts) == 3 and parts[1:] == ("scripts", "rea.mjs"): + launchers[parts[0]] = entry + elif read_version and len(parts) == 2 and parts[1] == "package.json": + versions.pop(parts[0], None) + if entry.isfile() and entry.size <= 1048576: + with archive.extractfile(entry) as stream: + try: + version = json.load(stream).get("version") + except (ValueError, AttributeError): + continue + if isinstance(version, str): + versions[parts[0]] = version + + # A hidden root never participated in the installer's original shell glob. + visible = [root for root in launchers if not root.startswith(".")] + if len(visible) != 1: + observed_root = next(iter(launchers)) if len(launchers) == 1 else None + return (None, versions.get(observed_root), + "The REA archive must hold one visible top folder with scripts/rea.mjs.") + + root = visible[0] + entry = launchers[root] + if entry.isfile(): + return (PurePosixPath(root, "scripts", "rea.mjs"), versions.get(root), None) + if entry.issym() or entry.islnk(): + try: + stream = archive.extractfile(entry) + except (KeyError, RecursionError): + stream = None + if stream is not None: + stream.close() + return (PurePosixPath(root, "scripts", "rea.mjs"), versions.get(root), None) + return (None, versions.get(root), + "scripts/rea.mjs must resolve to a regular file supplied by the archive.") +`; + +export const PYTHON_BUILD_ARCHIVE_PROBE = `${PYTHON_BUILD_ARCHIVE} +import sys +import tarfile + +with tarfile.open(sys.argv[1]) as archive: + _, version, problem = inspect_rea_archive(archive, read_version=True) +print(json.dumps({"version": version, "problem": problem})) +`; diff --git a/src/domain/desktop/appDownloadDesktop.ts b/src/domain/desktop/appDownloadDesktop.ts index 0de7522cd1..ace90f5470 100644 --- a/src/domain/desktop/appDownloadDesktop.ts +++ b/src/domain/desktop/appDownloadDesktop.ts @@ -1,103 +1,112 @@ -/** Python used by the offline installer to locate the program in a desktop Exec value. - * It follows desktopEntry's key spacing, value unescaping, command quoting and env-prefix rules; - * the original spelling of all other arguments remains intact. */ -export const rewriteAppImageDesktop = String.raw`import re +import { + DESKTOP_KEY_SEPARATOR, + DESKTOP_VALUE_ESCAPE, + DESKTOP_VALUE_ESCAPES, + ENV_PREFIX, + ENV_UNSET_NAME, + ENV_WRAPPER, + EXEC_LEXEME, + QUOTED_ESCAPE, +} from "./desktopLaunchSyntax.js"; + +const pythonJson = (value: unknown): string => + `json.loads(${JSON.stringify(JSON.stringify(value))})`; + +/** Run the desktop launch grammar in Python, retaining raw source spans so + * the installer can replace one program without reformatting its arguments. */ +export const rewriteAppImageDesktop = String.raw`import json +import re import sys source, destination, app_run = sys.argv[1:] -escapes = {"s": " ", "n": "\n", "t": "\t", "r": "\r", "\\": "\\"} -launch_key = re.compile(r"[ \t]*(TryExec|Exec)[ \t]*=[ \t]*") +value_escapes = ${pythonJson(DESKTOP_VALUE_ESCAPES)} +value_lexeme = re.compile(${pythonJson(String.raw`${DESKTOP_VALUE_ESCAPE}|([\s\S])`)}) +exec_lexeme = re.compile(${pythonJson(EXEC_LEXEME)}) +quoted_escape = re.compile(${pythonJson(QUOTED_ESCAPE)}) +env_wrapper = re.compile(${pythonJson(ENV_WRAPPER)}) +env_unset_name = re.compile(${pythonJson(ENV_UNSET_NAME)}) +env_phases = ${pythonJson(ENV_PREFIX)} +launch_key = re.compile(${pythonJson(String.raw`[ \t]*(TryExec|Exec)${DESKTOP_KEY_SEPARATOR}`)}) + +def exec_tokens(raw): + # Decode the value layer while recording where its characters came from. + value, offsets = [], [0] + for part in value_lexeme.finditer(raw): + escaped, character = part.groups() + value.append(character if escaped is None else value_escapes[escaped]) + offsets.append(part.end()) + value = "".join(value) + + tokens, parts = [], [] + cursor = 0 + while cursor < len(value): + part = exec_lexeme.match(value, cursor) + if part is None: + raise ValueError("unterminated quote in desktop Exec") + quoted, unquoted, separator = part.groups() + if separator is not None: + if parts: + tokens.append(("".join(parts), offsets[start], offsets[cursor])) + parts = [] + else: + if not parts: + start = cursor + parts.append(unquoted if quoted is None else quoted_escape.sub(r"\1", quoted)) + cursor = part.end() + if parts: + tokens.append(("".join(parts), offsets[start], offsets[cursor])) + return tokens def program_span(raw): - # Keep raw offsets while decoding the desktop value, so rewriting preserves - # field codes and all original argument spelling. - value, offsets = [], [] - i = 0 - while i < len(raw): - start = i - if raw[i] == "\\" and i + 1 < len(raw) and raw[i + 1] in escapes: - value.append(escapes[raw[i + 1]]) - i += 2 - else: - value.append(raw[i]) - i += 1 - offsets.append((start, i)) - tokens = [] - token = None - start = 0 - quoted = False - i = 0 - while i < len(value): - c = value[i] - if quoted: - if c == "\\" and i + 1 < len(value) and value[i + 1] in ('"', "\u0060", "$", "\\"): - token += value[i + 1] - i += 1 - elif c == '"': - quoted = False - else: - token += c - elif c == '"': - quoted = True - if token is None: - token = "" - start = i - elif c in (" ", "\t"): - if token is not None: - tokens.append((token, offsets[start][0], offsets[i - 1][1])) - token = None - else: - if token is None: - token = "" - start = i - token += c - i += 1 - if quoted: - raise ValueError("unterminated quote in desktop Exec") - if token is not None: - tokens.append((token, offsets[start][0], offsets[-1][1])) + tokens = exec_tokens(raw) index = 0 - if tokens and tokens[0][0].split("/")[-1] == "env": + if tokens and env_wrapper.fullmatch(tokens[0][0]): index = 1 - directory = None - while index < len(tokens): - option = tokens[index][0] - if option == "--ignore-environment" or re.fullmatch(r"-i+", option): - index += 1 - continue - short_directory = re.fullmatch(r"-i*C(.*)", option, re.DOTALL) - if option == "--chdir" or (short_directory and not short_directory[1]): - index += 1 - directory = tokens[index][0] if index < len(tokens) else "" - elif option.startswith("--chdir="): - directory = option[len("--chdir="):] - elif short_directory: - directory = short_directory[1] - else: - break - index += 1 + directory, clear_environment, unsets = None, False, [] + for phase in env_phases: + while index < len(tokens): + for rule in phase["rules"]: + matched = re.fullmatch(rule["pattern"], tokens[index][0]) + if matched is None: + continue + index += 1 + kind = rule["kind"] + if kind == "clear" or ("clear" in rule and matched[rule["clear"]]): + clear_environment = True + if kind in ("chdir", "unset"): + value = matched[rule["operand"]] if "operand" in rule else None + if value is None: + value = tokens[index][0] if index < len(tokens) else "" + index += 1 + if kind == "chdir": + directory = value + else: + unsets.append(value) + break + else: + break + if not phase["repeat"]: + break + if not clear_environment and any(env_unset_name.fullmatch(name) is None for name in unsets): + raise ValueError("invalid env unset name in desktop Exec") if directory == "": raise ValueError("missing env chdir directory in desktop Exec") - if index < len(tokens) and tokens[index][0] == "--": - index += 1 - if index < len(tokens) and tokens[index][0] == "-": - index += 1 - while index < len(tokens) and re.match(r"^[A-Za-z_][A-Za-z0-9_]*=", tokens[index][0]): - index += 1 if index >= len(tokens) or not tokens[index][0]: raise ValueError("missing program in desktop Exec") return tokens[index][1:] -with open(source, encoding="utf-8") as f: - lines = f.readlines() -with open(destination, "w", encoding="utf-8") as f: - for line in lines: +rewritten = [] +with open(source, encoding="utf-8", newline="\n") as f: + for line in f: key = launch_key.match(line) if key and key.group(1) == "TryExec": continue if key: - raw = line[key.end():].rstrip("\n") + newline = "\r\n" if line.endswith("\r\n") else "\n" if line.endswith("\n") else "" + raw = line[key.end():len(line) - len(newline)] start, end = program_span(raw) - line = "Exec=" + raw[:start] + app_run + raw[end:] + "\n" - f.write(line) + line = line[:key.end()] + raw[:start] + app_run + raw[end:] + newline + rewritten.append(line) +with open(destination, "w", encoding="utf-8", newline="") as f: + f.writelines(rewritten) `; diff --git a/src/domain/desktop/appExport.test.ts b/src/domain/desktop/appExport.test.ts index f7026d20c4..e8b0871a15 100644 --- a/src/domain/desktop/appExport.test.ts +++ b/src/domain/desktop/appExport.test.ts @@ -4,7 +4,7 @@ import type { DesktopApplicationCapture } from "./desktopCapture.js"; import type { DesktopApplicationState } from "./desktopState.js"; import { - capturedHomePath, + capturedHomePlan, exportedStateFiles, appModuleFile, className, @@ -20,6 +20,9 @@ import { } from "./appExport.js"; import type { LaunchDocument } from "./seedDocument.js"; +const capturedHomePath = (capture: DesktopApplicationCapture) => + capturedHomePlan(capture).homePath; + const plan: DesktopAppExportPlan = { name: "mousepad", className: "Mousepad", diff --git a/src/domain/desktop/appExport.ts b/src/domain/desktop/appExport.ts index af9757d53f..26b208c38b 100644 --- a/src/domain/desktop/appExport.ts +++ b/src/domain/desktop/appExport.ts @@ -40,7 +40,11 @@ import type { DesktopApplicationState } from "./desktopState.js"; import { isWithinAny } from "./desktopStateDiff.js"; import { SQLITE_SIDECARS } from "./stateFormats.js"; import { SEED_HOME } from "./hostIdentity.js"; -import { capturedFileUrl, type LaunchDocument } from "./seedDocument.js"; +import { + capturedFileUrl, + type LaunchDocument, + type TraversingSeedPath, +} from "./seedDocument.js"; import { posix } from "node:path"; import { roleFacts, stateDirectoryOf } from "./stateRoles.js"; import { shellQuote } from "./shellQuote.js"; @@ -202,30 +206,55 @@ export const ownedPaths = ( ); }; -/** A captured path's home-relative path, in the innermost walked state directory's own spelling unless that leaves the home. */ -const capturedHomePlan = (capture: DesktopApplicationCapture) => { +/** Omit portable no-op components without interpreting traversal through links. */ +const replaySegments = (path: string): string[] => + path.split("/").filter((part) => part !== "" && part !== "."); + +const portableRelative = (path: string): string | null => { + const parts = replaySegments(path); + return parts.includes("..") ? null : parts.join("/"); +}; + +/** Keep source spellings and projected replay names separate. */ +export const capturedHomePlan = (capture: DesktopApplicationCapture) => { const { home } = capture.host; const relative = (path: string) => - path.startsWith(`${home}/`) ? path.slice(home.length + 1) : null; + path === home + ? "" + : path.startsWith(`${home}/`) + ? path.slice(home.length + 1) + : null; + const portable = (path: string) => { + const name = relative(path); + return name === null ? null : portableRelative(name); + }; + const replayName = (logical: string, physical: string) => + portable(logical) ?? + (relative(logical) === null ? null : portable(physical)); const logical = capture.application.state_directories; const walked = capture.state.state_directories ?? []; // The capture records one walked spelling per state directory, in order; lists of other lengths cannot be paired. - const renamed = (walked.length === logical.length ? walked : []) - .flatMap((physical, index) => { + const renamed = (walked.length === logical.length ? walked : []).flatMap( + (physical, index) => { const path = logical[index]?.path; - return path === undefined ? [] : [{ physical, logical: path }]; - }) - .sort((left, right) => right.physical.length - left.physical.length); + return path === undefined + ? [] + : [{ physical, logical: path, target: replayName(path, physical) }]; + }, + ); const selections = [...(capture.state.selected_paths ?? [])]; - const stateAliases = capturedStateAliases(capture); + const stateTargets = new Map(); + for (const { physical, target } of renamed) + if (target !== null && !stateTargets.has(physical)) + stateTargets.set(physical, target); + const stateAliases = capturedStateAliases(selections, stateTargets, portable); const aliasPaths = [...stateAliases].sort( (left, right) => right.alias.length - left.alias.length, ); const selectedSpelling = (path: string) => { for (const { alias, target } of aliasPaths) { - const prefix = `${home}/${alias}`; - if (isWithinAny(path, [prefix])) - return `${home}/${target}${path.slice(prefix.length)}`; + if (isWithinAny(path, [alias])) + return `${target}${path.slice(alias.length)}`; } return path; }; @@ -262,18 +291,26 @@ const capturedHomePlan = (capture: DesktopApplicationCapture) => { // ~/.config/notes when that folder was walked at ~/settings/notes. const spellings = [ ...renamed, - ...selections.map(({ physical, path }) => ({ - physical, - logical: selectedSpelling(path), - })), + ...selections.map(({ physical, path }) => { + const target = replayName(path, physical); + return { + physical, + logical: path, + target: target === null ? null : selectedSpelling(target), + }; + }), ].sort((left, right) => right.physical.length - left.physical.length); const spell = (path: string) => { - for (const { physical, logical } of spellings) { - if (!isWithinAny(path, [physical])) continue; - const spelled = relative(`${logical}${path.slice(physical.length)}`); - if (spelled !== null) return { spelled, specificity: physical.length }; + for (const { physical, target } of spellings) { + if (target === null || !isWithinAny(path, [physical])) continue; + const suffix = portableRelative(path.slice(physical.length)); + if (suffix !== null) + return { + spelled: [target, suffix].filter(Boolean).join("/"), + specificity: physical.length, + }; } - const plain = relative(path); + const plain = portable(path); return plain === null ? undefined : { spelled: plain, specificity: 0 }; }; const homePath = (path: string) => { @@ -299,44 +336,118 @@ const capturedHomePlan = (capture: DesktopApplicationCapture) => { } return own?.spelled ?? null; }; - return { homePath, stateAliases }; + const traversed = spellings.flatMap(({ logical, physical, target }) => { + const parts = replaySegments(logical); + // An unresolved walk retains its parent traversal in the recorded path. + // It contributes no evidence about a replay destination. + return parts.includes("..") && portableRelative(physical) !== null + ? [{ logical: parts.join("/"), physical, portable: target !== null }] + : []; + }); + // A directory keeps the relative names the application will look up below + // it. The retained layout can include more-specific selections than this + // state root, so verify those names against the same map that seeds them. + const replayTree = ( + physical: string, + retained: ReadonlyMap, + ): string | null => { + const mapped = homePath(physical); + if (mapped === null) return null; + for (const [file, seed] of retained) { + if (!isWithinAny(file, [physical])) continue; + const suffix = portableRelative(file.slice(physical.length)); + if ( + suffix === null || + selectedSpelling([mapped, suffix].filter(Boolean).join("/")) !== seed + ) + return null; + } + return mapped; + }; + const agree = ( + paths: ReadonlySet, + ): string | null | undefined => + paths.size === 0 + ? undefined + : paths.size === 1 + ? (paths.values().next().value ?? null) + : null; + /** + * Replay a path with parent traversal only when the capture establishes a + * portable destination. Inferred arguments must name observed state before + * its replay can fail. Undefined means no traversal match, while null means + * the matched paths cannot share a replay location. + */ + const launchPath = ( + absolute: string, + retained: ReadonlyMap, + inferredPathObserved?: (physical: string) => boolean, + ): TraversingSeedPath | null | undefined => { + if (traversed.length === 0) return undefined; + const parts = replaySegments(absolute); + if (!parts.includes("..")) return undefined; + const source = parts.join("/"); + const direct = new Set(); + const parents = new Set(); + let specificity = 0; + for (const { logical, physical, portable } of traversed) { + if (isWithinAny(source, [logical])) { + const suffix = portableRelative(source.slice(logical.length)); + if (suffix === null || logical.length < specificity) continue; + if (logical.length > specificity) direct.clear(); + specificity = logical.length; + const file = suffix === "" ? physical : `${physical}/${suffix}`; + if ( + inferredPathObserved !== undefined && + !inferredPathObserved(file) && + !recorded.some((path) => isWithinAny(path, [file])) + ) + continue; + direct.add(portable ? replayTree(file, retained) : null); + } else if (isWithinAny(logical, [source])) { + // For a launch root above the observed state files, retain their + // relative names. Every paired path must imply the same replay base. + const suffix = logical.slice(source.length + 1); + const target = portable ? replayTree(physical, retained) : null; + parents.add( + suffix === target + ? "" + : target?.endsWith(`/${suffix}`) === true + ? target.slice(0, -(suffix.length + 1)) + : null, + ); + } + } + if (specificity > 0 && direct.size === 0) return { kind: "unobserved" }; + const path = agree(specificity > 0 ? direct : parents); + return typeof path === "string" ? { kind: "mapped", path } : path; + }; + return { homePath, launchPath, stateAliases }; }; -/** A captured path's home-relative spelling in the shared export plan. */ -export const capturedHomePath = (capture: DesktopApplicationCapture) => - capturedHomePlan(capture).homePath; - /** Selected links to an app state root must keep both the app's name and the selected name. */ const capturedStateAliases = ( - capture: DesktopApplicationCapture, + selections: NonNullable, + stateTargets: ReadonlyMap, + portable: (path: string) => string | null, ): { readonly alias: string; readonly target: string; readonly kind: "file" | "directory" | "unknown"; }[] => { - const { home } = capture.host; - const walked = capture.state.state_directories ?? []; - const roots = capture.application.state_directories; - if (walked.length !== roots.length) return []; - const relative = (path: string) => - path.startsWith(`${home}/`) ? path.slice(home.length + 1) : null; - const aliases = (capture.state.selected_paths ?? []).flatMap( - ({ path, physical, kind }) => { - const index = walked.indexOf(physical); - const state = index < 0 ? undefined : roots[index]?.path; - const alias = relative(path); - const target = state === undefined ? null : relative(state); - const recorded: "file" | "directory" | "unknown" = - kind === "directory" - ? "directory" - : kind === "file" - ? "file" - : "unknown"; - return alias === null || target === null || alias === target - ? [] - : [{ alias, target, kind: recorded }]; - }, - ); + const aliases = selections.flatMap(({ path, physical, kind }) => { + const alias = portable(path); + const target = stateTargets.get(physical) ?? null; + const recorded: "file" | "directory" | "unknown" = + kind === "directory" ? "directory" : kind === "file" ? "file" : "unknown"; + return alias === null || + alias === "" || + target === null || + target === "" || + alias === target + ? [] + : [{ alias, target, kind: recorded }]; + }); const retained: { alias: string; target: string; @@ -413,7 +524,8 @@ export const exportedStateFiles = ( capture: DesktopApplicationCapture, state: DesktopApplicationState, ) => { - const { homePath, stateAliases } = capturedHomePlan(capture); + const replay = capturedHomePlan(capture); + const { homePath } = replay; const homePaths = (paths: readonly string[]) => paths.map(homePath).filter((path): path is string => path !== null); const { files, dconf, collisions } = stateFilesByHomePath( @@ -441,8 +553,7 @@ export const exportedStateFiles = ( stateDirectories, ); return { - homePath, - stateAliases, + ...replay, files, dconf, collisions, diff --git a/src/domain/desktop/desktopEntry.test.ts b/src/domain/desktop/desktopEntry.test.ts index 04e04b7495..3010a22ec6 100644 --- a/src/domain/desktop/desktopEntry.test.ts +++ b/src/domain/desktop/desktopEntry.test.ts @@ -9,6 +9,7 @@ import { tokenizeDesktopExec, unwrapDesktopCommand, } from "./desktopEntry.js"; +import { DESKTOP_LAUNCH_CASES } from "./desktopLaunchSyntax.fixture.js"; describe("parseDesktopEntry", () => { it("reads the main group and ignores localized keys and other groups", () => { @@ -177,40 +178,36 @@ describe("expandDesktopExec", () => { }); describe("unwrapDesktopCommand", () => { - it("combines a clean environment with an env-selected launch directory", () => { - expect( - unwrapDesktopCommand([ - "env", - "-i", - "-C", - "/tmp", - "--", - "A=1", - "app", - "--ignore-environment", - ]), - ).toEqual({ - kind: "direct", - program: "app", - index: 6, - argumentIndex: 7, - environment: { A: "1" }, - clearEnvironment: true, - chdir: { path: "/tmp", start: 2, end: 4 }, - }); - }); - - it("keeps an env operand named -- after an assignment distinct from the option terminator", () => { - expect( - unwrapDesktopCommand(["env", "MODE=selected", "--", "notes"]), - ).toEqual({ - kind: "direct", - program: "--", - environment: { MODE: "selected" }, - index: 2, - argumentIndex: 3, - }); - }); + it.each(DESKTOP_LAUNCH_CASES)( + "reads $name from an authored Exec value", + ({ + prefix, + program, + suffix, + decodedProgram, + environment, + clear, + unsets, + chdir, + }) => { + const parsed = parseDesktopEntry( + `[Desktop Entry]\nExec=${prefix}${program}${suffix}\n`, + ); + if (!parsed.ok) throw new Error(parsed.error); + const tokens = tokenizeDesktopExec(parsed.value.exec ?? ""); + if (!tokens.ok) throw new Error(tokens.error); + const command = unwrapDesktopCommand(tokens.value); + expect(command.kind).toBe("direct"); + expect(command.program).toBe(decodedProgram); + expect(tokens.value[command.index]).toBe(decodedProgram); + expect(command.argumentIndex).toBe(command.index + 1); + expect(command.environment).toEqual(environment); + expect(command.clearEnvironment).toBe(clear); + expect(command.unsetEnvironment).toEqual(unsets); + expect(command.invalidUnset).toBeUndefined(); + expect(command.chdir).toEqual(chdir); + }, + ); it("keeps env assignments as the program's environment", () => { expect( unwrapDesktopCommand([ diff --git a/src/domain/desktop/desktopEntry.ts b/src/domain/desktop/desktopEntry.ts index 03945263b9..cb5bf88d8e 100644 --- a/src/domain/desktop/desktopEntry.ts +++ b/src/domain/desktop/desktopEntry.ts @@ -1,4 +1,16 @@ import { err, ok, type Result } from "../result.js"; +import { + DESKTOP_KEY, + DESKTOP_KEY_SEPARATOR, + DESKTOP_VALUE_ESCAPE, + DESKTOP_VALUE_ESCAPES, + ENV_PREFIX, + ENV_UNSET_NAME, + ENV_WRAPPER, + EXEC_LEXEME, + QUOTABLE, + QUOTED_ESCAPE, +} from "./desktopLaunchSyntax.js"; /** The unlocalized `[Desktop Entry]` keys a desktop capture uses. */ export interface DesktopEntry { @@ -16,20 +28,17 @@ export interface DesktopEntry { const GROUP = /^\[(?[^\]]+)\]$/u; // Only LF separates records; Unicode line/paragraph separators are value data. -const ENTRY = /^(?[A-Za-z0-9-]+)[ \t]*=[ \t]*(?.*)$/su; -const VALUE_ESCAPES: Readonly> = { - s: " ", - n: "\n", - t: "\t", - r: "\r", - "\\": "\\", -}; +const ENTRY = new RegExp( + `^(?${DESKTOP_KEY})${DESKTOP_KEY_SEPARATOR}(?.*)$`, + "su", +); +const valueEscape = new RegExp(DESKTOP_VALUE_ESCAPE, "gu"); /** Undo the escapes the desktop entry format allows in string values. */ const unescapeValue = (value: string): string => value.replace( - /\\(.)/gu, - (match, next: string) => VALUE_ESCAPES[next] ?? match, + valueEscape, + (match, next: string) => DESKTOP_VALUE_ESCAPES[next] ?? match, ); /** @@ -78,7 +87,8 @@ const listValue = (value: string | undefined): readonly string[] => { const character = value.charAt(index); const next = value.charAt(index + 1); if (character === "\\" && next.length > 0) { - entry += next === ";" ? ";" : (VALUE_ESCAPES[next] ?? `\\${next}`); + entry += + next === ";" ? ";" : (DESKTOP_VALUE_ESCAPES[next] ?? `\\${next}`); index += 1; } else if (character === ";") { entries.push(entry); @@ -135,7 +145,8 @@ export const parseDesktopEntry = ( }); }; -const QUOTED_ESCAPES = new Set(['"', "`", "$", "\\"]); +const execLexeme = new RegExp(EXEC_LEXEME, "uy"); +const quotedEscape = new RegExp(QUOTED_ESCAPE, "gu"); /** Split an `Exec` value into arguments with the specification's quoting rules. */ export const tokenizeDesktopExec = ( @@ -143,31 +154,25 @@ export const tokenizeDesktopExec = ( ): Result => { const tokens: string[] = []; let current: string | undefined; - let quoted = false; - for (let index = 0; index < exec.length; index += 1) { - const character = exec.charAt(index); - if (quoted) { - const next = exec.charAt(index + 1); - if (character === "\\" && QUOTED_ESCAPES.has(next)) { - current = `${current ?? ""}${next}`; - index += 1; - } else if (character === '"') quoted = false; - else current = `${current ?? ""}${character}`; - } else if (character === '"') { - quoted = true; - current ??= ""; - } else if (character === " " || character === "\t") { + execLexeme.lastIndex = 0; + while (execLexeme.lastIndex < exec.length) { + const part = execLexeme.exec(exec); + if (part === null) return err("unterminated_quote"); + const [, quoted, unquoted, separator] = part; + if (separator !== undefined) { if (current !== undefined) tokens.push(current); current = undefined; - } else current = `${current ?? ""}${character}`; + } else + current = + (current ?? "") + (quoted?.replace(quotedEscape, "$1") ?? unquoted!); } - if (quoted) return err("unterminated_quote"); if (current !== undefined) tokens.push(current); return tokens.length === 0 ? err("empty_command") : ok(tokens); }; /** Reserved characters an unquoted `Exec` argument must not contain. */ const EXEC_RESERVED = /[\t\n\r "'\\><~|&;$*?#()`]/u; +const quotable = new RegExp(QUOTABLE, "gu"); /** * Quote `Exec` arguments so `tokenizeDesktopExec` reads them back. The @@ -179,7 +184,7 @@ export const formatDesktopExec = (argv: readonly string[]): string => .map((argument) => argument.length > 0 && !EXEC_RESERVED.test(argument) ? argument - : `"${argument.replace(/[\\"`$]/gu, (character) => `\\${character}`)}"`, + : `"${argument.replace(quotable, (character) => `\\${character}`)}"`, ) .join(" "); @@ -271,6 +276,10 @@ export type DesktopCommandWrapper = { readonly environment: Readonly>; /** Present when the env wrapper discards all inherited variables. */ readonly clearEnvironment?: true; + /** Variables env removes from the inherited environment before assignments. */ + readonly unsetEnvironment?: readonly string[]; + /** A malformed unset name is ignored by GNU env only for a clean launch. */ + readonly invalidUnset?: true; /** The last env chdir option and the argv span that carries its operand. */ readonly chdir?: { readonly path: string; @@ -357,71 +366,91 @@ const flatpakApplication = (argv: readonly string[], start: number) => { return { application_id: null, argumentIndex: argv.length }; }; +const envUnsetName = new RegExp(`^(?:${ENV_UNSET_NAME})$`, "u"); +const envWrapper = new RegExp(`^${ENV_WRAPPER}$`, "u"); +const envPhases = ENV_PREFIX.map(({ repeat, rules }) => ({ + repeat, + rules: rules.map((rule) => ({ + rule, + pattern: new RegExp(`^(?:${rule.pattern})$`, "u"), + })), +})); + +const envMatch = (phase: (typeof envPhases)[number], token: string) => { + for (const { rule, pattern } of phase.rules) { + const captures = pattern.exec(token); + if (captures !== null) return { rule, captures }; + } + return undefined; +}; + const desktopEnvironment = (argv: readonly string[]) => { let index = 1; let clearEnvironment = false; let chdir: DesktopCommandWrapper["chdir"]; + const unsetEnvironment: string[] = []; // No prototype, so an assignment such as `__proto__=x` stays a variable. const environment: Record = Object.create(null); - while (index < argv.length) { - const option = argv[index]!; - if (/^-i+$/u.test(option) || option === "--ignore-environment") { - clearEnvironment = true; + for (const phase of envPhases) { + while (index < argv.length) { + const token = argv[index]!; + const match = envMatch(phase, token); + if (match === undefined) break; + const { rule, captures } = match; + const start = index; index += 1; - continue; + if (rule.kind === "clear") clearEnvironment = true; + if (rule.kind === "assignment") { + const split = token.indexOf("="); + environment[token.slice(0, split)] = token.slice(split + 1); + } + if (rule.kind === "chdir" || rule.kind === "unset") { + const attached = + rule.operand === undefined ? undefined : captures[rule.operand]; + const separate = attached === undefined; + const value = separate ? (argv[index] ?? "") : attached; + if (separate) index += 1; + const combined = + rule.clear !== undefined && Boolean(captures[rule.clear]); + clearEnvironment ||= combined; + if (rule.kind === "unset") unsetEnvironment.push(value); + else + chdir = { + path: value, + start, + end: index, + ...(combined ? { includesClearEnvironment: true as const } : {}), + }; + } + if (!phase.repeat) break; } - const shortDirectory = /^-(i*)C(.*)$/su.exec(option); - const separate = shortDirectory?.[2] === "" || option === "--chdir"; - const path = separate - ? (argv[index + 1] ?? "") - : option.startsWith("--chdir=") - ? option.slice("--chdir=".length) - : shortDirectory?.[2]; - if (path === undefined) break; - const start = index; - index += separate ? 2 : 1; - const combined = Boolean(shortDirectory?.[1]); - if (combined) clearEnvironment = true; - chdir = { - path, - start, - end: index, - ...(combined ? { includesClearEnvironment: true as const } : {}), - }; } - // Only the option terminator before the first operand belongs to env; - // a later `--` can name the command or belong to the application. - if (argv[index] === "--") index += 1; - if (argv[index] === "-") { - clearEnvironment = true; - index += 1; - } - while (/^[A-Za-z_][A-Za-z0-9_]*=/u.test(argv[index] ?? "")) { - const assignment = argv[index] ?? ""; - const split = assignment.indexOf("="); - environment[assignment.slice(0, split)] = assignment.slice(split + 1); - index += 1; - } - return { index, chdir, clearEnvironment, environment }; + return { index, chdir, clearEnvironment, environment, unsetEnvironment }; }; /** Apply env prefixes and recognise flatpak run launchers. */ export const unwrapDesktopCommand = ( argv: readonly string[], ): DesktopCommandWrapper => { - const { index, chdir, clearEnvironment, environment } = - argv[0]?.split("/").at(-1) === "env" + const { index, chdir, clearEnvironment, environment, unsetEnvironment } = + envWrapper.test(argv[0] ?? "") ? desktopEnvironment(argv) : { index: 0, chdir: undefined, clearEnvironment: false, + unsetEnvironment: [], environment: Object.create(null) as Record, }; const program = argv[index] ?? ""; const wrapperOptions = { ...(chdir === undefined ? {} : { chdir }), ...(clearEnvironment ? { clearEnvironment: true as const } : {}), + ...(unsetEnvironment.length === 0 ? {} : { unsetEnvironment }), + ...(!clearEnvironment && + unsetEnvironment.some((name) => !envUnsetName.test(name)) + ? { invalidUnset: true as const } + : {}), }; if (program.split("/").at(-1) === "flatpak" && argv[index + 1] === "run") return { diff --git a/src/domain/desktop/desktopLaunchSyntax.fixture.ts b/src/domain/desktop/desktopLaunchSyntax.fixture.ts new file mode 100644 index 0000000000..e90dce05e4 --- /dev/null +++ b/src/domain/desktop/desktopLaunchSyntax.fixture.ts @@ -0,0 +1,123 @@ +/** Raw slices around the program, plus the host's interpretation. */ +export const DESKTOP_LAUNCH_CASES: readonly { + name: string; + prefix: string; + program: string; + suffix: string; + decodedProgram: string; + environment: Readonly>; + clear?: true; + unsets?: readonly string[]; + chdir?: { + path: string; + start: number; + end: number; + includesClearEnvironment?: true; + }; +}[] = [ + { + name: "direct command", + prefix: "", + program: "drawio", + suffix: " %U", + decodedProgram: "drawio", + environment: {}, + }, + { + name: "quoted wrapper and value escapes before the program", + prefix: String.raw`"/usr/bin/env" -- "GTK_THEME=\sAdwaita\\\\😀" `, + program: '"draw.io for Linux"', + suffix: '\t--title="drawing" %U', + decodedProgram: "draw.io for Linux", + environment: { GTK_THEME: " Adwaita\\😀" }, + }, + { + name: "separate clean and chdir operands", + prefix: 'env -i -C "/tmp/work folder" -- A=old A=new ', + program: "drawio", + suffix: " --ignore-environment %U", + decodedProgram: "drawio", + environment: { A: "new" }, + clear: true, + chdir: { path: "/tmp/work folder", start: 2, end: 4 }, + }, + { + name: "combined clean and chdir option", + prefix: "env -iiC/tmp -- ", + program: "drawio", + suffix: " %U", + decodedProgram: "drawio", + environment: {}, + clear: true, + chdir: { path: "/tmp", start: 1, end: 2, includesClearEnvironment: true }, + }, + { + name: "combined clean and unset with a path-taking option", + prefix: 'env -iiu GTK_THEME -iC "/tmp/work folder" -- GTK_THEME=new ', + program: "drawio", + suffix: " --unset=argument %U", + decodedProgram: "drawio", + environment: { GTK_THEME: "new" }, + clear: true, + unsets: ["GTK_THEME"], + chdir: { + path: "/tmp/work folder", + start: 3, + end: 5, + includesClearEnvironment: true, + }, + }, + { + name: "attached short and separate or attached long unset operands", + prefix: "env -uPATH --unset XDG_CACHE_HOME --unset=XDG_CONFIG_HOME ", + program: "drawio", + suffix: " %U", + decodedProgram: "drawio", + environment: {}, + unsets: ["PATH", "XDG_CACHE_HOME", "XDG_CONFIG_HOME"], + }, + { + name: "short unset consumes the rest of its option as its name", + prefix: "env -ui NAME=value ", + program: "drawio", + suffix: " %U", + decodedProgram: "drawio", + environment: { NAME: "value" }, + unsets: ["i"], + }, + { + name: "long clean option", + prefix: "env --ignore-environment QT_QPA_PLATFORM=xcb ", + program: "drawio", + suffix: " %U", + decodedProgram: "drawio", + environment: { QT_QPA_PLATFORM: "xcb" }, + clear: true, + }, + { + name: "dash reset after option terminator", + prefix: "env -- - ", + program: "drawio", + suffix: " %U", + decodedProgram: "drawio", + environment: {}, + clear: true, + }, + { + name: "last chdir option overrides an empty attached operand", + prefix: "env --chdir= -C /old --chdir=/tmp -- ", + program: "drawio", + suffix: " %U", + decodedProgram: "drawio", + environment: {}, + chdir: { path: "/tmp", start: 4, end: 5 }, + }, + { + name: "option-looking program after an assignment", + prefix: "env MODE=selected ", + program: "--", + suffix: " drawio %U", + decodedProgram: "--", + environment: { MODE: "selected" }, + }, +]; diff --git a/src/domain/desktop/desktopLaunchSyntax.ts b/src/domain/desktop/desktopLaunchSyntax.ts new file mode 100644 index 0000000000..7645cffe8c --- /dev/null +++ b/src/domain/desktop/desktopLaunchSyntax.ts @@ -0,0 +1,81 @@ +/** Shared lexical and prefix rules for the host reader and offline installer. */ +export const DESKTOP_VALUE_ESCAPES: Readonly> = { + s: " ", + n: "\n", + t: "\t", + r: "\r", + "\\": "\\", +}; + +// Keep each match's raw span available to consumers that rewrite a token. +const escapeKeys = Object.keys(DESKTOP_VALUE_ESCAPES) + .join("") + .replaceAll("\\", "\\\\"); +export const DESKTOP_VALUE_ESCAPE = String.raw`\\([${escapeKeys}])`; +export const DESKTOP_KEY = String.raw`[A-Za-z0-9-]+`; +export const DESKTOP_KEY_SEPARATOR = String.raw`[ \t]*=[ \t]*`; + +export const QUOTABLE = String.raw`["\x60$\\]`; +export const QUOTED_ESCAPE = String.raw`\\(${QUOTABLE})`; +// The two backslash alternatives are disjoint: an escaped quotation mark +// cannot backtrack into a closing delimiter. +const QUOTED_PART = String.raw`"((?:\\${QUOTABLE}|\\(?!${QUOTABLE})|[^"\\])*)"`; +export const EXEC_LEXEME = String.raw`${QUOTED_PART}|([^" \t]+)|([ \t]+)`; + +export type EnvRule = + | { + readonly kind: "clear" | "separator" | "assignment"; + readonly pattern: string; + } + | { + readonly kind: "chdir" | "unset"; + readonly pattern: string; + readonly operand?: number; + readonly clear?: number; + }; + +/** Unsetting a variable accepts any nonempty name without NUL or equals. */ +export const ENV_UNSET_NAME = String.raw`[^=\x00]+`; + +const envOperandRules = ( + kind: "chdir" | "unset", + shortOption: "C" | "u", +): readonly EnvRule[] => [ + { kind, pattern: `--${kind}` }, + { kind, pattern: String.raw`--${kind}=([\s\S]*)`, operand: 1 }, + { + kind, + pattern: String.raw`-(i*)${shortOption}([\s\S]+)?`, + operand: 2, + clear: 1, + }, +]; + +/** An env launcher may be bare or identified by a path ending in /env. */ +export const ENV_WRAPPER = String.raw`(?:[\s\S]*/)?env`; +// A failed match advances to the next phase. After assignments begin, an +// option-looking operand is a program token. +export const ENV_PREFIX: readonly { + readonly repeat: boolean; + readonly rules: readonly EnvRule[]; +}[] = [ + { + repeat: true, + rules: [ + { kind: "clear", pattern: "-i+|--ignore-environment" }, + ...envOperandRules("chdir", "C"), + ...envOperandRules("unset", "u"), + ], + }, + { repeat: false, rules: [{ kind: "separator", pattern: "--" }] }, + { repeat: false, rules: [{ kind: "clear", pattern: "-" }] }, + { + repeat: true, + rules: [ + { + kind: "assignment", + pattern: String.raw`[A-Za-z_][A-Za-z0-9_]*=[\s\S]*`, + }, + ], + }, +]; diff --git a/src/domain/desktop/seedDocument.ts b/src/domain/desktop/seedDocument.ts index b7aa50487e..fbdd90044f 100644 --- a/src/domain/desktop/seedDocument.ts +++ b/src/domain/desktop/seedDocument.ts @@ -14,6 +14,16 @@ export type LaunchDocument = /** No document, for the reason given, which follows "since". */ | { readonly kind: "none"; readonly reason: string }; +/** An inferred argument under a traversed root can still lack path evidence. */ +export type TraversingSeedPath = + | { readonly kind: "mapped"; readonly path: string } + | { readonly kind: "unobserved" }; + +type MapTraversal = ( + absolutePath: string, + as: "explicit" | "inferred", +) => TraversingSeedPath | undefined; + /** Parse a captured Linux file URL independently of the exporter host OS. */ export const capturedFileUrl = ( value: string, @@ -38,6 +48,7 @@ const homePathOf = ( known: (path: string) => boolean, knownSeed: (path: string) => boolean, mapOutside?: (path: string) => string | null, + mapTraversal?: MapTraversal, ): | (({ readonly homePath: string } | { readonly seedPath: string }) & { readonly source: string; @@ -60,6 +71,16 @@ const homePathOf = ( input = parsed.path; parsedUrl = parsed.url; } + if (parsedUrl === undefined && mapTraversal !== undefined) { + // Only filesystem paths can traverse a captured symlink. File URLs + // above have already been interpreted under their URL rules. + const absolute = posix.isAbsolute(input); + const raw = absolute ? input : `${workingDirectory}/${input}`; + const replayed = mapTraversal(raw, absolute ? "explicit" : "inferred"); + if (replayed?.kind === "unobserved") return undefined; + if (replayed?.kind === "mapped") + return { seedPath: replayed.path, source: raw, url: undefined }; + } const path = posix.resolve(workingDirectory, input); if (path.startsWith(`${home}/`)) return { @@ -96,6 +117,8 @@ export const openSeedDocument = ( readonly isCaptured?: (homePath: string) => boolean; /** The selected seed spelling for a captured absolute path outside the home. */ readonly mapOutside?: (absolutePath: string) => string | null; + /** A portable replay name established from the raw captured traversal. */ + readonly mapTraversal?: MapTraversal; }, ): { readonly argv: readonly string[]; readonly opens: LaunchDocument } => { const { home, exec, documents } = facts; @@ -130,11 +153,14 @@ export const openSeedDocument = ( namesCaptured, isCapturedSeed, facts.mapOutside, + facts.mapTraversal, ); if (parsed === undefined) return value; const absolute = "seedPath" in parsed - ? `${home}/${parsed.seedPath}` + ? parsed.seedPath === "" + ? home + : `${home}/${parsed.seedPath}` : absoluteSeed(parsed.homePath); if (absolute === undefined) return value; if (parsed.url === undefined) return absolute; @@ -204,6 +230,7 @@ export const openSeedDocument = ( namesCaptured, isCapturedSeed, facts.mapOutside, + facts.mapTraversal, ); }) .map((path) => diff --git a/src/ports/DesktopBuildHost.ts b/src/ports/DesktopBuildHost.ts index 1ddc5aaa4b..0876e589f1 100644 --- a/src/ports/DesktopBuildHost.ts +++ b/src/ports/DesktopBuildHost.ts @@ -75,7 +75,7 @@ export interface DesktopBuildFacts { readonly archive: { readonly path: string; readonly source: "environment" | "cache"; - readonly status: "current" | "missing" | "stale" | "unknown"; + readonly status: "current" | "missing" | "stale" | "invalid" | "unknown"; readonly detail?: string; }; /** Each considered client's registration, by setting names only. */ diff --git a/tests/boundary/providers/desktopBuildInstall.test.ts b/tests/boundary/providers/desktopBuildInstall.test.ts index f2c8949ed2..691667f0de 100644 --- a/tests/boundary/providers/desktopBuildInstall.test.ts +++ b/tests/boundary/providers/desktopBuildInstall.test.ts @@ -6,6 +6,7 @@ import { readFile, readlink, stat, + symlink, writeFile, } from "node:fs/promises"; import { dirname, join } from "node:path"; @@ -13,12 +14,16 @@ import { fileURLToPath } from "node:url"; import { promisify } from "node:util"; import { describe, expect, it } from "vitest"; import { createTestTempDirectory } from "../../fixtures/temporaryDirectory.js"; +import { PRODUCT_IDENTITY } from "../../../src/identity.js"; +import { readDesktopBuildFacts } from "../../../src/desktop/DesktopBuildDoctorFacts.js"; +import { defaultBuildComputerArchive } from "../../../src/desktop/BuildComputerEnvironment.js"; +import { ArtifactResourceScope } from "../../../src/resources/index.js"; import { expandDesktopExec, parseDesktopEntry, tokenizeDesktopExec, - unwrapDesktopCommand, } from "../../../src/domain/desktop/desktopEntry.js"; +import { DESKTOP_LAUNCH_CASES } from "../../../src/domain/desktop/desktopLaunchSyntax.fixture.js"; import { BUILD_NODE_VERSION, renderBuildBundle, @@ -140,24 +145,16 @@ describe("download install scripts", () => { expect(failed?.stderr).toContain("drawio.desktop"); }); - it.each([ - "", - "-- ", - "-C /opt --chdir=/tmp -- ", - "-iC/tmp -- ", - "--ignore-environment ", - "-- - ", - "--chdir= -C /tmp -- ", - ])( - "keeps an env %sprefix and its assignments when it points the AppImage's entry at AppRun", - async (delimiter) => { + it.each(DESKTOP_LAUNCH_CASES)( + "replaces only the executable in an AppImage entry with $name", + async ({ prefix, program, suffix }) => { const root = await stage("rea-appimage-env-"); const image = join(root, "env/vendor/app.AppImage"); await writeFile( image, STUB_APPIMAGE.replace( "'Exec=drawio %U'", - `'Exec=env ${delimiter}QT_QPA_PLATFORM=xcb "GTK_THEME=Adwaita dark" drawio %U'`, + () => `'Exec=${prefix}${program}${suffix}'`, ), ); await chmod(image, 0o755); @@ -172,39 +169,10 @@ describe("download install scripts", () => { join(root, "local-share/applications/drawio.desktop"), "utf8", ), - ).toContain( - `\nExec=env ${delimiter}QT_QPA_PLATFORM=xcb "GTK_THEME=Adwaita dark" ${appRun} %U\n`, - ); + ).toContain(`\nExec=${prefix}${appRun}${suffix}\n`); }, ); - it("points an Exec spaced around its = at AppRun and drops a spaced TryExec, as the desktop entry parser reads them", async () => { - const root = await stage("rea-appimage-spaced-"); - const image = join(root, "env/vendor/app.AppImage"); - await writeFile( - image, - STUB_APPIMAGE.replace( - "'Exec=drawio %U' 'TryExec=drawio'", - "'Exec = drawio %U' ' TryExec =drawio'", - ), - ); - await chmod(image, 0o755); - await runDownloadInstall( - renderBuildBundle(appImageRequest("drawio"), localPayload), - root, - ); - - const appRun = join(root, "opt/rea-apps/drawio/squashfs-root/AppRun"); - expect( - await readFile( - join(root, "local-share/applications/drawio.desktop"), - "utf8", - ), - ).toBe( - `[Desktop Entry]\nName=draw.io\nExec=${appRun} %U\nIcon=drawio\n\n[Desktop Action New]\nExec=${appRun} --new-window\n`, - ); - }); - it("unpacks a tarball without xz under its folder and installs the entry REA wrote for its program", async () => { const root = await stage("rea-tarball-install-"); const program = join(root, "src/notes-2.0/bin/notes"); @@ -256,6 +224,56 @@ describe("download install scripts", () => { }); }); +it("preserves Exec key spacing and line endings while removing TryExec", async () => { + const root = await stage("rea-appimage-spaced-"); + const image = join(root, "env/vendor/app.AppImage"); + const source = join(root, "source.desktop"); + await writeFile( + source, + '[Desktop Entry]\r\nExec = drawio %U\r\n TryExec =drawio\r\n\r\n[Desktop Action New]\r\nExec="drawio" --new-window', + ); + await writeFile( + image, + STUB_APPIMAGE + `cp -- "${source}" squashfs-root/drawio.desktop\n`, + ); + await chmod(image, 0o755); + await runDownloadInstall( + renderBuildBundle(appImageRequest("drawio"), localPayload), + root, + ); + + const appRun = join(root, "opt/rea-apps/drawio/squashfs-root/AppRun"); + expect( + await readFile( + join(root, "local-share/applications/drawio.desktop"), + "utf8", + ), + ).toBe( + `[Desktop Entry]\r\nExec = ${appRun} %U\r\n\r\n[Desktop Action New]\r\nExec=${appRun} --new-window`, + ); +}); + +it.each([ + ['env "drawio %U', "unterminated quote"], + ["env -i", "missing program"], + ["env --chdir= drawio %U", "missing env chdir directory"], + ["env --unset= drawio %U", "invalid env unset name"], +])("rejects a malformed AppImage Exec value %s", async (exec, reason) => { + const root = await stage("rea-appimage-invalid-exec-"); + const image = join(root, "env/vendor/app.AppImage"); + await writeFile( + image, + STUB_APPIMAGE.replace("'Exec=drawio %U'", () => `'Exec=${exec}'`), + ); + await chmod(image, 0o755); + await expect( + runDownloadInstall( + renderBuildBundle(appImageRequest("drawio"), localPayload), + root, + ), + ).rejects.toMatchObject({ stderr: expect.stringContaining(reason) }); +}); + describe("download install scripts and archive links", () => { it("refuses a tarball whose links point outside its folder, leaving the files they name untouched", async () => { for (const link of ["hardlink", "symlink"]) { @@ -298,16 +316,32 @@ describe("download install scripts and archive links", () => { const shellQuote = (value: string): string => `'${value.replaceAll("'", `'"'"'`)}'`; -describe("installed launch paths", () => { - it("keeps an archive folder with spaces as the rea entrypoint", async () => { - const root = await createTestTempDirectory("rea-launcher-spaces-"); +it.each([ + { folder: "REA Build", link: null, cached: false, problem: null }, + { folder: "runtime", link: "cli.mjs", cached: false, problem: null }, + { + folder: ".runtime", + link: null, + cached: false, + problem: "visible top folder", + }, + { + folder: "runtime", + link: "missing.mjs", + cached: true, + problem: "regular file supplied by the archive", + }, +])( + "agrees on build runtime archive readiness for %j", + async ({ folder, link, cached, problem }) => { + const root = await createTestTempDirectory("rea-launcher-layout-"); const nodeDir = join( root, "node-src", `node-v${BUILD_NODE_VERSION}-linux-x64`, "bin", ); - const payloadDir = join(root, "payload-src", "REA Build", "scripts"); + const payloadDir = join(root, "payload-src", folder, "scripts"); await mkdir(nodeDir, { recursive: true }); await mkdir(payloadDir, { recursive: true }); const marker = join(root, "node-args"); @@ -315,9 +349,17 @@ describe("installed launch paths", () => { await writeFile( join(nodeDir, "node"), `#!/bin/sh\nprintf '%s\\n' "$@" > ${shellQuote(marker)}\n`, + { mode: 0o755 }, ); - await chmod(join(nodeDir, "node"), 0o755); - await writeFile(join(payloadDir, "rea.mjs"), entrypoint); + await writeFile( + join(payloadDir, "..", "package.json"), + JSON.stringify({ version: PRODUCT_IDENTITY.packageVersion }), + ); + if (link === null) await writeFile(join(payloadDir, "rea.mjs"), entrypoint); + else { + if (problem === null) await writeFile(join(payloadDir, link), entrypoint); + await symlink(link, join(payloadDir, "rea.mjs")); + } await execute("tar", [ "-cJf", join(root, "node-amd64.tar.xz"), @@ -325,13 +367,55 @@ describe("installed launch paths", () => { join(root, "node-src"), `node-v${BUILD_NODE_VERSION}-linux-x64`, ]); + const archive = join(root, "rea-payload.tar"); await execute("tar", [ "-cf", - join(root, "rea-payload.tar"), + archive, "-C", join(root, "payload-src"), - "REA Build", + folder, ]); + const resources = new ArtifactResourceScope(); + const environment = { + HOME: root, + USERPROFILE: root, + PATH: "", + XDG_CACHE_HOME: join(root, "cache"), + ...(cached ? {} : { REA_BUILD_COMPUTER_REA_ARCHIVE: archive }), + }; + if (cached) { + const cachePath = defaultBuildComputerArchive(environment, "linux"); + await mkdir(dirname(cachePath), { recursive: true }); + await writeFile(cachePath, await readFile(archive)); + } + try { + const facts = await readDesktopBuildFacts({ + environment, + platform: "linux", + resources, + signal: new AbortController().signal, + run: async (command, args) => { + const { stdout, stderr } = await execute(command, args); + return { + stdout, + stderr, + stdoutBytes: Buffer.byteLength(stdout), + stderrBytes: Buffer.byteLength(stderr), + }; + }, + clientIds: [], + registrations: async () => [], + }); + expect(facts.archive.status).toBe( + problem === null ? "current" : "invalid", + ); + if (problem !== null) { + expect(facts.archive.detail).toContain(problem); + expect(facts.archive.detail).toContain(PRODUCT_IDENTITY.packageVersion); + } + } finally { + await resources.close(); + } const bundle = renderBuildBundle( request({ kind: "archive", package: "mousepad", extra_packages: [] }), localPayload, @@ -342,18 +426,26 @@ describe("installed launch paths", () => { await mkdir(join(root, "bin"), { recursive: true }); const scriptPath = join(root, "install-rea.sh"); await writeFile(scriptPath, script); - await chmod(scriptPath, 0o755); - await execute("sh", [scriptPath], { cwd: root }); + const installed = execute("sh", [scriptPath], { cwd: root }); + if (problem !== null) { + await expect(installed).rejects.toMatchObject({ + stderr: expect.stringContaining(problem), + }); + return; + } + await installed; const linked = join(root, "opt/rea/rea.mjs"); expect(await readlink(linked)).toBe( - join(root, "opt/rea/payload/REA Build/scripts/rea.mjs"), + join(root, "opt/rea/payload", folder, "scripts/rea.mjs"), ); expect(await readFile(linked, "utf8")).toBe(entrypoint); await execute(join(root, "bin/rea"), ["--version"]); expect(await readFile(marker, "utf8")).toBe(`${linked}\n--version\n`); - }); + }, +); +describe("installed launch paths", () => { it.each(["", "/usr/bin/env -- REA_TEST_ENV=selected "])( "rewrites and launches an Electron-style command with the shared launch policy (prefix %j)", async (prefix) => { @@ -370,11 +462,19 @@ describe("installed launch paths", () => { localPayload, ); const root = await createTestTempDirectory("rea-electron-launch-"); - const policy = join( - root, - "opt/rea/payload/rea/dist/domain/desktop/appExportInstall.js", - ); + const runtime = join(root, "opt/rea/payload/rea"); + const policy = join(runtime, "dist/domain/desktop/appExportInstall.js"); await mkdir(dirname(policy), { recursive: true }); + const launcher = join(runtime, "scripts/rea.mjs"); + await mkdir(dirname(launcher), { recursive: true }); + await writeFile(launcher, ""); + await symlink(launcher, join(root, "opt/rea/rea.mjs")); + const unrelatedPolicy = join( + root, + "opt/rea/payload/unrelated/dist/domain/desktop/appExportInstall.js", + ); + await mkdir(dirname(unrelatedPolicy), { recursive: true }); + await writeFile(unrelatedPolicy, ""); const source = fileURLToPath( new URL( "../../../src/domain/desktop/appExportInstall.ts", @@ -450,38 +550,3 @@ describe("installed launch paths", () => { }, ); }); - -it("preserves a quoted env executable when rewriting an AppImage entry", async () => { - const root = await stage("rea-appimage-quoted-env-"); - const image = join(root, "env/vendor/app.AppImage"); - await writeFile( - image, - STUB_APPIMAGE.replace( - "'Exec=drawio %U'", - "'Exec=\"/usr/bin/env\" QT_QPA_PLATFORM=xcb drawio %U'", - ), - ); - await chmod(image, 0o755); - await runDownloadInstall( - renderBuildBundle(appImageRequest("drawio"), localPayload), - root, - ); - const text = await readFile( - join(root, "local-share/applications/drawio.desktop"), - "utf8", - ); - expect(text).toContain( - `Exec="/usr/bin/env" QT_QPA_PLATFORM=xcb ${join(root, "opt/rea-apps/drawio/squashfs-root/AppRun")} %U`, - ); - const parsed = parseDesktopEntry(text); - expect(parsed.ok).toBe(true); - if (!parsed.ok) throw new Error("invalid desktop entry"); - const tokens = tokenizeDesktopExec(parsed.value.exec ?? ""); - expect(tokens.ok).toBe(true); - if (!tokens.ok) throw new Error("invalid Exec"); - expect(unwrapDesktopCommand(tokens.value)).toMatchObject({ - kind: "direct", - environment: { QT_QPA_PLATFORM: "xcb" }, - program: join(root, "opt/rea-apps/drawio/squashfs-root/AppRun"), - }); -}); diff --git a/tests/boundary/providers/desktopLaunchCommand.test.ts b/tests/boundary/providers/desktopLaunchCommand.test.ts index d736b19c89..51767a524b 100644 --- a/tests/boundary/providers/desktopLaunchCommand.test.ts +++ b/tests/boundary/providers/desktopLaunchCommand.test.ts @@ -11,7 +11,10 @@ import { tmpdir } from "node:os"; import { join } from "node:path"; import { pathToFileURL } from "node:url"; -import { launchCommand } from "../../../src/domain/desktop/appExport.js"; +import { + capturedHomePlan, + launchCommand, +} from "../../../src/domain/desktop/appExport.js"; import { planLaunch } from "../../../src/application/desktop/DesktopExportLaunch.js"; import type { DesktopApplicationCapture } from "../../../src/domain/desktop/desktopCapture.js"; @@ -43,7 +46,11 @@ it.skipIf(process.platform === "win32").each([ } as unknown as DesktopApplicationCapture; const { command: [program, ...args], - } = planLaunch(capture, false, new Map(), new Map()); + } = planLaunch(capture, false, new Map(), { + ...capturedHomePlan(capture), + files: new Map(), + restoredFiles: [], + }); const result = spawnSync(program!, args, { encoding: "utf8", env: { ...process.env, HOME: home, REA_REPLAY_MARKER: "inherited" },