[Bug][Linux] Empty XDG data variables hide registered file handlers and icons

[GCSimba]

Current-version update — 2026-10-07

Rechecked on 2026-10-07 against the newest public release, 0.2.1-alpha.1, and upstream master at 5badb15009ae1756c3afe0ae0cef1faafc290ccc. The empty-XDG-default fix remains applicable and is now combined with the desktop Name/Icon patch. Actual Linux GIO/XDG and desktop-entry verification passed 15 cases, filling the earlier native-Linux verification gap. All five product commits are preserved in the published current-baseline integration; both the full build and full lint passed.

Current patch index and verification limits. No all-checks-pass, upstream acceptance or released-fix claim is made. This update is AI-assisted with Codex; the published commits retain its co-author.

The original report and its verification history are preserved below.

---

Summary

I reproduced an empty-value handling defect in desktopDataDirectories() on master at 5badb15009ae1756c3afe0ae0cef1faafc290ccc (0.2.1-alpha.1). Empty XDG_DATA_HOME and XDG_DATA_DIRS bypass the defaults, although the XDG Base Directory Specification requires the defaults for both unset and empty values.

This can hide registered file handlers below $HOME/.local/share/applications and prevent their named icons from being found. An empty XDG_DATA_DIRS also removes /usr/local/share and /usr/share from the lookup. The Open In icon route uses the same directory resolver.

The source regression, real-filesystem fixtures, and Loader/WebServer HTTP scenario were verified on Windows with Linux environment facts and OS commands injected where stated below. This report does not claim a native Linux desktop launch or a browser recording.

Minimal reproduction

From a checkout of the baseline above, using Node 24:

node --input-type=module -e '
import { desktopDataDirectories } from "./packages/util/native-command/src/desktop-entry.ts";
const unset = desktopDataDirectories("/home/fixture", {});
const empty = desktopDataDirectories("/home/fixture", { XDG_DATA_HOME: "", XDG_DATA_DIRS: "" });
console.log(JSON.stringify({ sameDirectories: JSON.stringify(unset) === JSON.stringify(empty), empty }, null, 2));
'

Before the patch:

{
  "sameDirectories": false,
  "empty": [""]
}

Expected: sameDirectories is true. On Linux, both environments should resolve to /home/fixture/.local/share, /usr/local/share, and /usr/share, in that order.

The empty-value failure is independent of installing GIO: the shared resolver itself drops the required defaults. In a real-filesystem fixture with the GIO result injected, an installed user handler is found when the data-home is unset but omitted when it is empty. The launch-validation path can then reject that same handler as unregistered. A separate real Loader/WebServer test reproduces HTTP 404 instead of 200 for an existing desktop-entry SVG icon.

Root cause and patch

The baseline implementation uses ?? for both variables. Empty strings are not nullish, so XDG_DATA_HOME="" becomes an empty root and XDG_DATA_DIRS="" becomes an empty list after splitting and filtering.

The production change uses || for those two defaults. It preserves non-empty overrides, data-home precedence, and system-directory order. Tests cover all nine unset/empty/configured combinations, installed-handler discovery and launch validation, and real HTTP icon responses. The package README pair and JSDoc describe the defaults.

• XDG fix: b53b512d387b18f2af50ae66c245c270f6cec968
• Branch, verified tip: 1e2685aad89441032aa09cafdd45651c5c67cd2f

The branch also contains an independent Windows documentation-test portability commit. It replaces a privileged file symlink with a directory junction, keeps the real-path escape assertions, and unlinks the junction in finally. Its test content matches the previously published portability correction; it is not another newly discovered XDG defect. The XDG commit can be cherry-picked independently.

No public TypeScript type, package export, dependency, permission policy, configuration format, or durable/wire format changes are involved. This patch handles empty defaults only; it does not add non-empty path validation or broaden icon-theme support.

Validation

Development host: Windows; Node 24.19.0; Corepack pnpm 11.7.0. The results below apply to the combined branch tip named above. No check or hook was bypassed.

Red and green regression

Before the production change:

node node_modules/vitest/vitest.mjs run packages/util/native-command/tests/desktop-entry.spec.ts packages/util/native-command/tests/file-applications-linux.spec.ts packages/host/open-in-app/tests/host-routes.spec.ts -t 'desktopDataDirectories|empty XDG_DATA_HOME'

Observed result: exit 1; 7 failed, 4 passed, 19 skipped by the name filter. Five directory-matrix cases failed on empty values, the handler fixture returned an empty application list, and the Loader-backed icon request returned HTTP 404 rather than 200.

After the fix:

corepack pnpm exec vitest run packages/util/native-command/tests/desktop-entry.spec.ts packages/util/native-command/tests/file-applications-linux.spec.ts packages/host/open-in-app/tests/host-routes.spec.ts -t 'desktopDataDirectories|empty XDG_DATA_HOME'

Observed result: exit 0; 11 passed, 19 skipped by the name filter.

Related tests and focused coverage

corepack pnpm exec vitest run packages/util/native-command/tests/desktop-entry.spec.ts packages/util/native-command/tests/file-applications.spec.ts packages/util/native-command/tests/file-applications-linux.spec.ts packages/util/native-command/tests/file-applications-linux-native.spec.ts packages/host/open-in-app/tests/resolver.spec.ts packages/host/open-in-app/tests/icons.spec.ts packages/host/open-in-app/tests/host-routes.spec.ts --coverage --coverage.include='packages/util/native-command/src/desktop-entry.ts'

Observed result: exit 0; 93 passed, 3 skipped. The three skipped cases require native Linux/GIO and cover configured, unset, and empty data-home values. They were not executed on this Windows host and remain a Linux-native verification gap.

Coverage for desktop-entry.ts: statements 100% (38/38), branches 100% (28/28), functions 100% (4/4), lines 100% (28/28).

The filesystem, desktop-entry parsing, and image bytes in the handler fixture are real; GIO output and command execution are injected. The HTTP scenario boots the actual Loader/WebServer composition and checks the response status, media type, and SVG bytes; Linux platform facts, executable resolution, and launch are injected. These checks do not substitute for native GIO or a desktop GUI run.

Documentation, lint, and submission checks

• corepack pnpm run verify-translation-pairing --write packages/util/native-command/README.md: passed.
• corepack pnpm run lint: passed, including its Host library and Desktop bundle builds.
• corepack pnpm run doc-sync: 42 passed, 0 failed, 0 skipped in 324.25 seconds.
• A plain-Node smoke importing packages/util/native-command/lib/index.js passed all nine directory combinations.
• git diff --check and corepack pnpm --silent run change-scope --base upstream/master: passed; nine changed paths, no unrelated generated output, lockfile, or vendor changes.
• Normal pre-commit hooks passed. The normal pre-push pnpm run typecheck hook passed, including Host builds, Desktop bundles, and Client TypeScript checks. Local and remote branch SHAs match.

The first doc-sync attempt passed 41 gates but failed the unchanged upstream Windows file-symlink fixture with EPERM. After the independent portability correction, the entire documentation-site group passed:

corepack pnpm exec vitest run scripts/project-doc-site.spec.ts scripts/verify-doc-site-fragments.spec.ts website/tests/mermaid-viewer.spec.ts website/tests/image-viewer.spec.ts website/tests/code-groups.spec.ts website/tests/page-markdown-actions.spec.ts website/tests/raw-markdown.spec.ts

Observed result: 151 passed, no skipped cases. A negative control temporarily disabling the real-path containment check made the escape regression fail on the external image path; the production check was restored, with no production diff. The full 42-gate run above includes the corrected fixture.

The fork has no Actions runs for this head; these are local results, not an upstream or remote CI-pass claim. No full repository coverage run, real-model run, or native Linux launch is claimed.

Duplicate search and scope

On 2026-10-05, I rechecked public Discussions for XDG_DATA_HOME, XDG_DATA_DIRS, desktopDataDirectories, and XDG empty, and fetched master again. I did not find an equivalent public report in that scope; this is not a claim that no one has privately found it. The earlier audit also inspected upstream history and the helper on the 20 newest public fork default branches.

• #1664 proposes splitting Harness-owned data by XDG class; this report concerns lookup defaults for already installed desktop entries and icons.
• #7252 concerns unavailable artwork and icon-search coverage with non-empty data directories; this patch does not address those limitations.

This is submitted as a Discussion under the current contribution policy. The immutable fork commits are available for inspection or cherry-picking.

AI-assisted source audit, reproduction, and implementation. Both commits include Co-authored-by: Codex <noreply@openai.com>. The commands and limitations above reflect the checks actually performed.

[luoyukun3-oss]

Confirmed on the released line (0.1.7-rc.2), and it is visible in one line:

@deepseek-ai/dsh-native-command/lib/index.js:317

return [env.XDG_DATA_HOME ?? join(home, ".local", "share"),
        ...(env.XDG_DATA_DIRS ?? "/usr/local/share:/usr/share").split(":").filter(Boolean)];

?? only falls through on null/undefined, so an empty string is kept as-is — the default is bypassed
exactly as you describe, and .filter(Boolean) then drops the empty entry entirely rather than
substituting it. Both variables are affected by the same expression.

So this is not master-only either. Note the consequence you already point out: with an empty
XDG_DATA_HOME the per-user applications directory disappears from the list, which hides registered
handlers and their named icons.