fix(desktop): share launch syntax, replay paths, and runtime admission (#12153)

* refactor(desktop): share launch syntax with the offline installer

Refs #12119 and #12120.

* fix(desktop): share build archive readiness admission

Refs #12144

* fix(desktop): honor env unset launch operands

* fix(desktop): retain unknown state home after env removal

* fix(desktop): share captured state replay paths

* fix(desktop): keep traversing launches aligned with retained seeds

* fix(desktop): preserve scalars in traversing launches

* fix(desktop): admit traversing arguments before replay
This commit is contained in:
morluto authored and GitHub committed 2026-11-19 03:36:56 +00:00
1 parent f361ee1222
commit 47461fddab
26 files changed
+1407 -440

No files matched your search

+10 -5
View File
@@ -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
+7 -1
View File
@@ -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`,
+4
View File
@@ -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.
@@ -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`;
@@ -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,
@@ -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<typeof planLaunch>[2],
files: ReadonlyMap<string, StatePath>,
) =>
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" }]]),
+37 -3
View File
@@ -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<string, SeedVersion>,
files: ReadonlyMap<string, StatePath>,
replay: Pick<
ReturnType<typeof capturedHomePlan>,
"homePath" | "launchPath"
> & {
readonly files: ReadonlyMap<string, StatePath>;
readonly restoredFiles: Iterable<string>;
},
): Pick<DesktopAppExportPlan, "command" | "opens"> => {
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<string, string>();
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(
+19 -15
View File
@@ -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<Record<string, string | undefined>>;
readonly home: string;
readonly home: string | undefined;
}
/**
@@ -66,16 +66,15 @@ export const stateDirectories = async (
{ environment, home }: StateLocations,
extra: readonly string[],
): Promise<DesktopApplicationInventory["state_directories"]> => {
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,
+24 -29
View File
@@ -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<string | undefined>,
@@ -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}.`,
};
};
+96 -3
View File
@@ -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"));
},
);
+24 -12
View File
@@ -251,14 +251,15 @@ const launchEnvironment = (
wrapper: ReturnType<typeof unwrapDesktopCommand>,
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<typeof unwrapDesktopCommand>,
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,
),
+3 -3
View File
@@ -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 = <Fallback extends string | undefined>(
value: string | undefined,
fallback: string | (() => string),
): string =>
fallback: Fallback | (() => Fallback),
): string | Fallback =>
value !== undefined && isAbsolute(value)
? value
: typeof fallback === "function"
+1 -1
View File
@@ -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`,
);
+23 -12
View File
@@ -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";
+54
View File
@@ -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}))
`;
+93 -84
View File
@@ -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)
`;
+4 -1
View File
@@ -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",
+165 -54
View File
@@ -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<string, string>();
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, string>,
): 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>,
): 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<string, string>,
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<string | null>();
const parents = new Set<string | null>();
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<DesktopApplicationCapture["state"]["selected_paths"]>,
stateTargets: ReadonlyMap<string, string>,
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,
+31 -34
View File
@@ -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([
+97 -68
View File
@@ -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 = /^\[(?<name>[^\]]+)\]$/u;
// Only LF separates records; Unicode line/paragraph separators are value data.
const ENTRY = /^(?<key>[A-Za-z0-9-]+)[ \t]*=[ \t]*(?<value>.*)$/su;
const VALUE_ESCAPES: Readonly<Record<string, string>> = {
s: " ",
n: "\n",
t: "\t",
r: "\r",
"\\": "\\",
};
const ENTRY = new RegExp(
`^(?<key>${DESKTOP_KEY})${DESKTOP_KEY_SEPARATOR}(?<value>.*)$`,
"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<readonly string[], "unterminated_quote" | "empty_command"> => {
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<Record<string, string>>;
/** 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<string, string> = 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<string, string>,
};
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 {
@@ -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<Record<string, string>>;
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" },
},
];
+81
View File
@@ -0,0 +1,81 @@
/** Shared lexical and prefix rules for the host reader and offline installer. */
export const DESKTOP_VALUE_ESCAPES: Readonly<Record<string, string>> = {
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]*`,
},
],
},
];
+28 -1
View File
@@ -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) =>
+1 -1
View File
@@ -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. */
@@ -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"),
});
});
@@ -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" },