@gjsify/xdp 0.0.0-stage → 0.64.54

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,3 +1,63 @@
1
- # Temporary Holding Version
1
+ # @gjsify/xdp
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ libportal's Background portal on every desktop: the real `gi://Xdp` on Linux, and a driver where there is none. Start-at-login and background permission are asked by capability, never by mechanism ([ADR 0144](../../../docs/adr/0144-background-and-autostart-are-asked-through-libportal.md)).
4
+
5
+ Part of the [gjsify](https://github.com/gjsify/gjsify) project. **Tier 3 (experimental, ADR 0003)**: new, one platform, no promise yet.
6
+
7
+ ## Installation
8
+
9
+ ```bash
10
+ gjsify install @gjsify/xdp
11
+ ```
12
+
13
+ `@gjsify/xdp` is not published on npm yet; the first publish is a queued maintainer action (`status/pending-npm-bootstrap.json`).
14
+
15
+ ## Usage
16
+
17
+ ```typescript
18
+ import { Portal, BackgroundFlags, XdpGtk4 } from '@gjsify/xdp';
19
+ ```
20
+
21
+ On Linux these are libportal's own types: `Portal` is `Xdp.Portal`, with no gjsify object in between.
22
+
23
+ For a host that may have no libportal typelib or no Background portal, use the entry point with the fallback:
24
+
25
+ ```typescript
26
+ import { requestBackground, setBackgroundStatus, BackgroundFlags } from '@gjsify/xdp/background';
27
+
28
+ const outcome = await requestBackground({
29
+ appId: 'org.example.App',
30
+ reason: 'Keep syncing in the tray',
31
+ commandline: ['/usr/bin/example', '--tray'],
32
+ flags: BackgroundFlags.AUTOSTART,
33
+ });
34
+ // 'granted' | 'denied'; a cancelled request rejects with Gio.IOErrorEnum.CANCELLED
35
+ await setBackgroundStatus('Syncing');
36
+ ```
37
+
38
+ A request is the **whole wish**, not a delta: without `AUTOSTART` it removes an existing entry.
39
+
40
+ ## Platforms
41
+
42
+ | Platform | State |
43
+ |---|---|
44
+ | Linux | `src/portal.ts` re-exports `Xdp.Portal` and `Xdp.BackgroundFlags`; `XdpGtk4.parent_new_gtk` is real |
45
+ | Linux, no Background portal | `@gjsify/xdp/background` writes `$XDG_CONFIG_HOME/autostart/<app-id>.desktop` |
46
+ | Windows (unpackaged) | `@gjsify/xdp/background` writes `HKCU\Software\Microsoft\Windows\CurrentVersion\Run` with `reg.exe` (argv array, no shell); asks nothing, resolves `granted`. A packaged (MSIX) program (path under `WindowsApps`) throws by name; `ACTIVATABLE` is accepted and ignored; `set_background_status` is a no-op. **Not run on Windows**: argv and mapping are tested on Linux with a stand-in `reg.exe` |
47
+ | macOS | no driver yet (ADR 0144 § 2) |
48
+ | Browser, NativeScript | named throwing stub (`ENOTSUP`); `XdpGtk4.parent_new_gtk` returns `null` |
49
+
50
+ ## Fallback semantics
51
+
52
+ - The fallback asks nothing and always resolves `granted`. `commandline` is required there; without it the call rejects with `INVALID_ARGUMENT`.
53
+ - The probe reads `org.freedesktop.portal.Background` `version` on the session bus. Only "nobody serves it" (ServiceUnknown, NameHasNoOwner, UnknownObject, UnknownInterface, UnknownMethod, UnknownProperty, or no session bus) means *no portal* and falls through to the file. Any other error is a portal that answered badly: it is thrown and **never** falls through.
54
+ - The file carries `X-GJSIFY-Background=true`. Only a file with that marker is replaced or deleted. A file without it belongs to someone else and is left alone in both directions: an existing entry counts as the wish fulfilled.
55
+ - A portal on the bus but no `Xdp` typelib installed also falls back to the file.
56
+ - `Exec` is quoted per the Desktop Entry spec; an argument with a newline or NUL is refused.
57
+ - `set_background_status` without a portal completes and changes nothing.
58
+
59
+ ## Testing
60
+
61
+ `gjsify run test` runs the pure suites on Node and everything on GJS. The GJS run serves a fake Background portal on a peer-to-peer `Gio.DBusServer` (`src/fake-portal.ts`) and uses temporary config directories. It covers granted, denied, cancelled, a broken portal (no fallthrough), an absent portal (fallthrough, whole-wish), marker-only deletion, and flag values against the typelib.
62
+
63
+ **Unverified:** no real xdg-desktop-portal backend has been measured; the fake serves what libportal's client calls.
@@ -0,0 +1 @@
1
+ var e=Object.defineProperty,__name=(t,n)=>e(t,`name`,{value:n,configurable:!0});export{__name};
@@ -0,0 +1 @@
1
+ import"./_virtual/_rolldown/runtime.js";import{autostartFileName as e,desktopFileText as t,isOwnedFile as n}from"./desktop-entry.js";import r from"gi://Gio?version=2.0";import i from"gi://GLib?version=2.0";function autostartFilePath(t,n){return i.build_filenamev([t,`autostart`,e(n)])}function readIfPresent(e){try{let[,t]=e.load_contents(null);return new TextDecoder().decode(t)}catch(e){if(e.matches(r.io_error_quark(),r.IOErrorEnum.NOT_FOUND))return null;throw e}}function applyAutostartFile(e){let a=autostartFilePath(e.configDir,e.appId),o=r.File.new_for_path(a),s=readIfPresent(o),c=s!==null&&n(s);if(!e.autostart){c&&o.delete(null);return}if(s!==null&&!c)return;i.mkdir_with_parents(i.path_get_dirname(a),493);let l=o.replace(null,!1,r.FileCreateFlags.REPLACE_DESTINATION,null);try{l.write_all(new TextEncoder().encode(t(e)),null)}finally{l.close(null)}}export{applyAutostartFile,autostartFilePath};
@@ -0,0 +1 @@
1
+ import"./_virtual/_rolldown/runtime.js";import{applyAutostartFile as e}from"./autostart-file.js";import{AUTOSTART_FLAG as t,classifyProbeError as n,outcomeOf as r,wantsAutostart as i}from"./wish.js";import{createWindowsPortal as a,spawnTool as o}from"./portal.windows.js";import s from"gi://Gio?version=2.0";import c from"gi://GLib?version=2.0";const l={sessionBus:()=>new Promise((e,t)=>{s.bus_get(s.BusType.SESSION,null,(n,r)=>{try{e(s.bus_get_finish(r))}catch(e){t(e)}})}),async loadPortal(){let e;try{e=await import(`gi://Xdp?version=1.0`)}catch{return null}return new e.default.Portal},configDir:()=>c.get_user_config_dir(),platform:()=>c.getenv(`OS`)===`Windows_NT`?`windows`:`other`,windowsPortal:e=>a(o,e)};async function portalFor(e,t){return e.platform()===`windows`?e.windowsPortal(t):await probeBackgroundPortal(e)===`present`?await e.loadPortal():null}function call(e){return new Promise((t,n)=>{e.call(`org.freedesktop.portal.Desktop`,`/org/freedesktop/portal/desktop`,`org.freedesktop.DBus.Properties`,`Get`,new c.Variant(`(ss)`,[`org.freedesktop.portal.Background`,`version`]),null,s.DBusCallFlags.NONE,-1,null,(e,r)=>{try{t(e.call_finish(r))}catch(e){n(e)}})})}async function probeBackgroundPortal(e){let t;try{t=await e.sessionBus()}catch{return`absent`}try{return await call(t),`present`}catch(e){if(n(e instanceof c.Error?s.DBusError.get_remote_error(e):null)===`absent`)return`absent`;throw e}}async function requestBackground(t,n=l){t.cancellable?.set_error_if_cancelled();let a=await portalFor(n,t.appId);if(a===null){if(!t.commandline)throw c.Error.new_literal(s.io_error_quark(),s.IOErrorEnum.INVALID_ARGUMENT,`requestBackground: without a Background portal a command line is needed to write the autostart file`);return e({appId:t.appId,name:t.name??t.appId,commandline:t.commandline,autostart:i(t.flags),configDir:n.configDir()}),`granted`}return r(await new Promise((e,n)=>{a.request_background(t.parent??null,t.reason??null,t.commandline?[...t.commandline]:null,t.flags,t.cancellable??null,(t,r)=>{try{e(a.request_background_finish(r))}catch(e){n(e)}})}))}async function setBackgroundStatus(e,t=null,n=l){t?.set_error_if_cancelled();let r=await portalFor(n,``);r!==null&&await new Promise((n,i)=>{r.set_background_status(e,t,(e,t)=>{try{r.set_background_status_finish(t),n()}catch(e){i(e)}})})}export{t as AUTOSTART_FLAG,probeBackgroundPortal,l as realHost,requestBackground,setBackgroundStatus,i as wantsAutostart};
@@ -0,0 +1 @@
1
+ import{BackgroundFlags as e,createStub as t}from"./stub.js";const n=t(`browser`),r=n.Portal,i=n.XdpGtk4,a=n.requestBackground,o=n.setBackgroundStatus;export{e as BackgroundFlags,r as Portal,i as XdpGtk4,a as requestBackground,o as setBackgroundStatus};
@@ -0,0 +1,5 @@
1
+ import"./_virtual/_rolldown/runtime.js";const e=`X-GJSIFY-Background`,t=/[\s"'\\><~|&;$*?#()`]/,n={test:e=>e.includes(`\0`)||e.includes(`
2
+ `)||e.includes(`\r`)};function quoteExecArg(e){if(n.test(e))throw RangeError(`an autostart command-line argument cannot contain a newline or NUL`);let r=e.replaceAll(`%`,`%%`);return(e===``||t.test(e))&&(r=`"${r.replaceAll(/["`$\\]/g,`\\$&`)}"`),r.replaceAll(`\\`,`\\\\`)}function execLine(e){if(e.length===0)throw RangeError(`an autostart command line needs at least the program`);return e.map(quoteExecArg).join(` `)}function escapeString(e){return e.replaceAll(`\\`,`\\\\`).replaceAll(`
3
+ `,`\\n`).replaceAll(`\r`,`\\r`).replaceAll(` `,`\\t`)}function desktopFileText(t){return[`[Desktop Entry]`,`Type=Application`,`Name=${escapeString(t.name)}`,`Exec=${execLine(t.commandline)}`,`X-GNOME-Autostart-enabled=true`,`${e}=true`,``].join(`
4
+ `)}function isOwnedFile(e){let t=``;for(let n of e.split(`
5
+ `)){let e=n.trim();if(e.startsWith(`[`)&&e.endsWith(`]`))t=e;else if(t===`[Desktop Entry]`&&e===`X-GJSIFY-Background=true`)return!0}return!1}const r=/^[A-Za-z0-9_-][A-Za-z0-9._-]*$/;function autostartFileName(e){if(!r.test(e)||e.includes(`..`))throw RangeError(`"${e}" is not usable as an autostart file name`);return`${e}.desktop`}export{e as OWNER_MARKER_KEY,autostartFileName,desktopFileText,escapeString,execLine,isOwnedFile,quoteExecArg};
@@ -0,0 +1 @@
1
+ import{refusal as e,subsetOf as t}from"./refusal.js";import{AUTOSTART_FLAG as n,outcomeOf as r,wantsAutostart as i}from"./wish.js";import{probeBackgroundPortal as a,requestBackground as o,setBackgroundStatus as s}from"./background.js";import{BackgroundFlags as c,Portal as l,XdpGtk4 as u}from"./portal.js";export{n as AUTOSTART_FLAG,c as BackgroundFlags,l as Portal,u as XdpGtk4,r as outcomeOf,a as probeBackgroundPortal,e as refusal,o as requestBackground,s as setBackgroundStatus,t as subsetOf,i as wantsAutostart};
@@ -0,0 +1 @@
1
+ import{BackgroundFlags as e,createStub as t}from"./stub.js";const n=t(`nativescript`),r=n.Portal,i=n.XdpGtk4,a=n.requestBackground,o=n.setBackgroundStatus;export{e as BackgroundFlags,r as Portal,i as XdpGtk4,a as requestBackground,o as setBackgroundStatus};
@@ -0,0 +1 @@
1
+ import e from"gi://Xdp?version=1.0";import t from"gi://XdpGtk4?version=1.0";const n=e.Portal,r=e.BackgroundFlags,i={parent_new_gtk:t.parent_new_gtk};export{r as BackgroundFlags,n as Portal,i as XdpGtk4};
@@ -0,0 +1,2 @@
1
+ import"./_virtual/_rolldown/runtime.js";import{refusal as e,subsetOf as t}from"./refusal.js";import{wantsAutostart as n}from"./wish.js";import r from"gi://Gio?version=2.0";import i from"gi://GLib?version=2.0";const a=`HKCU\\Software\\Microsoft\\Windows\\CurrentVersion\\Run`;function quoteWindowsArg(e){if(e.includes(`\0`)||e.includes(`
2
+ `)||e.includes(`\r`))throw RangeError(`a Run-key command-line argument cannot contain a newline or NUL`);if(e!==``&&!/[\s"]/.test(e))return e;let t=`"`,n=0;for(let r of e){if(r===`\\`){n++;continue}t+=r===`"`?`\\`.repeat(n*2+1)+`"`:`\\`.repeat(n)+r,n=0}return`${t}${`\\`.repeat(n*2)}"`}function runCommandLine(e){if(e.length===0)throw RangeError(`a Run-key command line needs at least the program`);return e.map(quoteWindowsArg).join(` `)}function addArgv(e,t){return[`reg`,`add`,a,`/v`,e,`/t`,`REG_SZ`,`/d`,runCommandLine(t),`/f`]}const queryArgv=e=>[`reg`,`query`,a,`/v`,e],deleteArgv=e=>[`reg`,`delete`,a,`/v`,e,`/f`];function isPackagedProgram(e){return/[\\/]WindowsApps[\\/]/i.test(e)}function failure(e,t){return i.Error.new_literal(r.io_error_quark(),e,t)}async function applyRunKey(t,i){if(!n(i.flags)){if(await t(queryArgv(i.appId))===null)return;if(await t(deleteArgv(i.appId))===null)throw failure(r.IOErrorEnum.FAILED,`reg.exe could not delete the Run value "${i.appId}"`);return}let a=i.commandline;if(!a||a.length===0)throw failure(r.IOErrorEnum.INVALID_ARGUMENT,`a command line is needed to write the Run value`);if(isPackagedProgram(a[0]))throw e(`request_background for a packaged (MSIX) app`,`windows`);if(await t(addArgv(i.appId,a))===null)throw failure(r.IOErrorEnum.FAILED,`reg.exe could not write the Run value "${i.appId}"`)}const spawnTool=e=>new Promise(t=>{let n;try{n=r.Subprocess.new([...e],r.SubprocessFlags.STDOUT_PIPE|r.SubprocessFlags.STDERR_SILENCE)}catch{t(null);return}n.communicate_utf8_async(null,null,(e,n)=>{try{let[,r]=e.communicate_utf8_finish(n);t(e.get_successful()?r??``:null)}catch{t(null)}})}),o=new Set([`request_background`,`request_background_finish`,`set_background_status`,`set_background_status_finish`]);function createWindowsPortal(e,n){let settle=(e,t)=>{let n={};e.then(()=>t(n,{error:void 0}),e=>t(n,{error:e}))};return t({request_background(t,r,i,a,o,s){settle((async()=>{o?.set_error_if_cancelled(),await applyRunKey(e,{appId:n,commandline:i,flags:a})})(),s)},request_background_finish(e){if(e.error!==void 0)throw e.error;return!0},set_background_status(e,t,n){settle(Promise.resolve(),n)},set_background_status_finish(e){return!0}},o,`windows`)}export{a as RUN_KEY,addArgv,applyRunKey,createWindowsPortal,deleteArgv,failure,isPackagedProgram,queryArgv,quoteWindowsArg,runCommandLine,spawnTool};
@@ -0,0 +1 @@
1
+ import"./_virtual/_rolldown/runtime.js";function refusal(e,t){let n=Error(`[@gjsify/xdp] ${e} is outside the Background subset of libportal that @gjsify/xdp serves on ${t}`);return n.code=`ENOTSUP`,n.gjsifyModule=`xdp`,n.gjsifyMember=e,n}function subsetOf(e,t,n){return new Proxy(e,{get(e,r,i){if(typeof r==`symbol`||t.has(r)||r===`then`)return Reflect.get(e,r,i);throw refusal(`Portal.${r}`,n)}})}export{refusal,subsetOf};
@@ -0,0 +1 @@
1
+ import"./_virtual/_rolldown/runtime.js";function unsupported(e,t){let n=Error(`[@gjsify/xdp/${e}] ${t} is not available on the ${e} platform: a page and a phone app have lifetimes of their own, so there is no background mode to ask for.`);throw n.code=`ENOTSUP`,n.errno=-45,n.syscall=t,n.gjsifyModule=`xdp`,n.gjsifyRuntime=e,n}const e={NONE:0,AUTOSTART:1,ACTIVATABLE:2};function createStub(e){class Portal{constructor(){unsupported(e,`Portal`)}static new(){return unsupported(e,`Portal.new`)}}return{Portal,XdpGtk4:{parent_new_gtk:e=>null},requestBackground:()=>unsupported(e,`requestBackground`),setBackgroundStatus:()=>unsupported(e,`setBackgroundStatus`)}}export{e as BackgroundFlags,createStub};
@@ -0,0 +1 @@
1
+ import"./_virtual/_rolldown/runtime.js";const e=1;function wantsAutostart(e){return(e&1)!=0}function outcomeOf(e){return e?`granted`:`denied`}const t=new Set([`org.freedesktop.DBus.Error.ServiceUnknown`,`org.freedesktop.DBus.Error.NameHasNoOwner`,`org.freedesktop.DBus.Error.UnknownObject`,`org.freedesktop.DBus.Error.UnknownInterface`,`org.freedesktop.DBus.Error.UnknownMethod`,`org.freedesktop.DBus.Error.UnknownProperty`]);function classifyProbeError(e){return e!==null&&t.has(e)?`absent`:`broken`}export{e as AUTOSTART_FLAG,classifyProbeError,outcomeOf,wantsAutostart};
@@ -0,0 +1,15 @@
1
+ export interface AutostartFileRequest {
2
+ readonly appId: string;
3
+ readonly name: string;
4
+ readonly commandline: readonly string[];
5
+ readonly autostart: boolean;
6
+ /** `$XDG_CONFIG_HOME`; the file lands in its `autostart/` directory. */
7
+ readonly configDir: string;
8
+ }
9
+ export declare function autostartFilePath(configDir: string, appId: string): string;
10
+ /**
11
+ * Make the autostart file match the wish. A file without our marker belongs to someone else —
12
+ * the person or another tool — and is left alone in both directions: an entry that already
13
+ * exists is the wish fulfilled, and one we did not write is not ours to delete.
14
+ */
15
+ export declare function applyAutostartFile(request: AutostartFileRequest): void;
@@ -0,0 +1,2 @@
1
+ declare const _default: () => Promise<void>;
2
+ export default _default;
@@ -0,0 +1,50 @@
1
+ import Gio from 'gi://Gio?version=2.0';
2
+ import type Xdp from 'gi://Xdp?version=1.0';
3
+ import { type BackgroundOutcome } from './wish.js';
4
+ export { AUTOSTART_FLAG, wantsAutostart, type BackgroundOutcome } from './wish.js';
5
+ /** The four members of the subset (ADR 0144 § 1), so a test can hand in a stand-in. */
6
+ export type BackgroundPortal = Pick<Xdp.Portal, 'request_background' | 'request_background_finish' | 'set_background_status' | 'set_background_status_finish'>;
7
+ export interface BackgroundRequest {
8
+ /** Must equal the desktop file's basename; it also names the fallback autostart file. */
9
+ readonly appId: string;
10
+ /** `Name=` of the fallback file; defaults to the app id. */
11
+ readonly name?: string;
12
+ /** Shown in the portal's dialog. Not used by the fallback, which asks nothing. */
13
+ readonly reason?: string;
14
+ /** What starts at login. Required by the fallback; the portal derives a default without it. */
15
+ readonly commandline?: readonly string[];
16
+ /** `Xdp.BackgroundFlags` bits; without AUTOSTART the request removes an existing entry. */
17
+ readonly flags: number;
18
+ readonly parent?: Xdp.Parent | null;
19
+ readonly cancellable?: Gio.Cancellable | null;
20
+ }
21
+ /** The seams a test replaces. Everything defaults to the real host. */
22
+ export interface BackgroundHost {
23
+ sessionBus(): Promise<Gio.DBusConnection>;
24
+ /** The libportal client, or `null` when the typelib is not installed. */
25
+ loadPortal(): Promise<BackgroundPortal | null>;
26
+ configDir(): string;
27
+ /** `'windows'` selects the HKCU Run key driver, which needs no portal and no typelib. */
28
+ platform(): 'windows' | 'other';
29
+ windowsPortal(appId: string): BackgroundPortal;
30
+ }
31
+ export declare const realHost: BackgroundHost;
32
+ /**
33
+ * Is there a Background portal on the session bus? Only "nobody serves it" returns `'absent'`;
34
+ * a portal that answers with any other error is broken and the error is thrown, because falling
35
+ * through to a file there would override a portal that said no.
36
+ */
37
+ export declare function probeBackgroundPortal(host: Pick<BackgroundHost, 'sessionBus'>): Promise<'present' | 'absent'>;
38
+ /**
39
+ * libportal's `request_background`, with a fallback for a host that has no Background portal.
40
+ * Resolves `granted` or `denied`; a cancelled request rejects with `Gio.IOErrorEnum.CANCELLED`
41
+ * and a broken portal rejects with its error. The fallback writes or deletes
42
+ * `$XDG_CONFIG_HOME/autostart/<app-id>.desktop`, asks nothing, and so resolves `granted`.
43
+ */
44
+ export declare function requestBackground(request: BackgroundRequest, host?: BackgroundHost): Promise<BackgroundOutcome>;
45
+ /**
46
+ * libportal's `set_background_status`. Without a portal there is no status line to set, so it
47
+ * completes and changes nothing observable: a decoration call that throws makes every consumer
48
+ * write a `try` that means nothing (ADR 0144 § 1).
49
+ */
50
+ export declare function setBackgroundStatus(message: string | null, cancellable?: Gio.Cancellable | null, host?: BackgroundHost): Promise<void>;
@@ -0,0 +1,11 @@
1
+ import { BackgroundFlags } from './stub.js';
2
+ export { BackgroundFlags };
3
+ export declare const Portal: {
4
+ new (): {};
5
+ "new"(): never;
6
+ };
7
+ export declare const XdpGtk4: {
8
+ parent_new_gtk: (_window: unknown) => null;
9
+ };
10
+ export declare const requestBackground: () => never;
11
+ export declare const setBackgroundStatus: () => never;
@@ -0,0 +1,20 @@
1
+ /** The key that marks a file as ours. The driver deletes nothing without it. */
2
+ export declare const OWNER_MARKER_KEY = "X-GJSIFY-Background";
3
+ /**
4
+ * One argument of an `Exec` line. Three layers apply in this order, each from the spec:
5
+ * `%` is a field-code introducer so a literal one is `%%`; a reserved character puts the
6
+ * argument in double quotes with `"` `` ` `` `$` `\` backslash-escaped; and the file format
7
+ * then reads `\\` as one backslash, so every backslash is doubled once more.
8
+ */
9
+ export declare function quoteExecArg(arg: string): string;
10
+ export declare function execLine(commandline: readonly string[]): string;
11
+ /** The `string` value type of the Desktop Entry spec. */
12
+ export declare function escapeString(value: string): string;
13
+ export interface AutostartEntry {
14
+ readonly name: string;
15
+ readonly commandline: readonly string[];
16
+ }
17
+ export declare function desktopFileText(entry: AutostartEntry): string;
18
+ /** True when `text` is a desktop file this package wrote: the marker, in the `[Desktop Entry]` group. */
19
+ export declare function isOwnedFile(text: string): boolean;
20
+ export declare function autostartFileName(appId: string): string;
@@ -0,0 +1,2 @@
1
+ declare const _default: () => Promise<void>;
2
+ export default _default;
@@ -0,0 +1,24 @@
1
+ export interface PortalAnswer {
2
+ /** The Request.Response code: 0 = the person answered, 1 = the person cancelled, 2 = ended otherwise. */
3
+ readonly response: number;
4
+ readonly background?: boolean;
5
+ readonly autostart?: boolean;
6
+ /** Fail the method call itself with a D-Bus error, as a broken portal does. */
7
+ readonly fail?: boolean;
8
+ }
9
+ export interface BackgroundCall {
10
+ readonly parentWindow: string;
11
+ readonly reason: string | null;
12
+ readonly autostart: boolean | null;
13
+ readonly commandline: string[] | null;
14
+ readonly flags: number | null;
15
+ }
16
+ export interface FakePortal {
17
+ /** Serve the Background interface (default) or take it off the bus, as on a host without the portal. */
18
+ setPresent(present: boolean): void;
19
+ answerWith(answer: PortalAnswer): void;
20
+ readonly calls: BackgroundCall[];
21
+ readonly statuses: string[];
22
+ }
23
+ /** One fake per process; later calls return the same one, so a test sets its own answer. */
24
+ export declare function startFakePortal(): Promise<FakePortal>;
@@ -0,0 +1,4 @@
1
+ export { Portal, BackgroundFlags, XdpGtk4 } from './portal.js';
2
+ export { probeBackgroundPortal, requestBackground, setBackgroundStatus, type BackgroundHost, type BackgroundPortal, type BackgroundRequest, } from './background.js';
3
+ export { AUTOSTART_FLAG, wantsAutostart, outcomeOf, type BackgroundOutcome } from './wish.js';
4
+ export { refusal, subsetOf, type RefusalError } from './refusal.js';
@@ -0,0 +1,11 @@
1
+ import { BackgroundFlags } from './stub.js';
2
+ export { BackgroundFlags };
3
+ export declare const Portal: {
4
+ new (): {};
5
+ "new"(): never;
6
+ };
7
+ export declare const XdpGtk4: {
8
+ parent_new_gtk: (_window: unknown) => null;
9
+ };
10
+ export declare const requestBackground: () => never;
11
+ export declare const setBackgroundStatus: () => never;
@@ -0,0 +1,10 @@
1
+ import Xdp from 'gi://Xdp?version=1.0';
2
+ import XdpGtk4Library from 'gi://XdpGtk4?version=1.0';
3
+ export declare const Portal: typeof Xdp.Portal;
4
+ export type Portal = InstanceType<typeof Xdp.Portal>;
5
+ export declare const BackgroundFlags: typeof Xdp.BackgroundFlags;
6
+ export type BackgroundFlags = Xdp.BackgroundFlags;
7
+ /** `XdpGtk4.parent_new_gtk`, real here and `null` on the platforms that show no portal dialog. */
8
+ export declare const XdpGtk4: {
9
+ parent_new_gtk: typeof XdpGtk4Library.parent_new_gtk;
10
+ };
@@ -0,0 +1,2 @@
1
+ declare const _default: () => Promise<void>;
2
+ export default _default;
@@ -0,0 +1,37 @@
1
+ import Gio from 'gi://Gio?version=2.0';
2
+ import GLib from 'gi://GLib?version=2.0';
3
+ export declare const RUN_KEY = "HKCU\\Software\\Microsoft\\Windows\\CurrentVersion\\Run";
4
+ /** stdout when the tool exits 0, `null` otherwise (including a tool that is missing). */
5
+ export type RunTool = (argv: readonly string[]) => Promise<string | null>;
6
+ export declare function quoteWindowsArg(arg: string): string;
7
+ export declare function runCommandLine(commandline: readonly string[]): string;
8
+ export declare function addArgv(appId: string, commandline: readonly string[]): string[];
9
+ export declare const queryArgv: (appId: string) => string[];
10
+ export declare const deleteArgv: (appId: string) => string[];
11
+ /** A packaged (MSIX) app lives under `WindowsApps` and needs `StartupTask`, which is not built. */
12
+ export declare function isPackagedProgram(program: string): boolean;
13
+ export declare function failure(code: number, message: string): GLib.Error;
14
+ /**
15
+ * Make the Run value match the wish. Removing a missing value is done: it is looked up first,
16
+ * because `reg delete` exits non-zero for "not there".
17
+ */
18
+ export declare function applyRunKey(run: RunTool, request: {
19
+ appId: string;
20
+ commandline?: readonly string[] | null;
21
+ flags: number;
22
+ }): Promise<void>;
23
+ /** The same `runTool` shape as adwaita-app's appearance/run-tool.ts: argv array, no shell. */
24
+ export declare const spawnTool: RunTool;
25
+ type Settled = {
26
+ readonly error: unknown;
27
+ } | {
28
+ readonly error?: undefined;
29
+ };
30
+ /** The four Background members of `Xdp.Portal`, over the Run key; every other member throws by name. */
31
+ export declare function createWindowsPortal(run: RunTool, appId: string): {
32
+ request_background(_parent: unknown, _reason: string | null, commandline: string[] | null, flags: number, cancellable: Gio.Cancellable | null, callback: (source: object, result: object) => void): void;
33
+ request_background_finish(result: Settled): boolean;
34
+ set_background_status(_status: string | null, _cancellable: unknown, callback: (s: object, r: object) => void): void;
35
+ set_background_status_finish(_result: unknown): boolean;
36
+ };
37
+ export {};
@@ -0,0 +1,2 @@
1
+ declare const _default: () => Promise<void>;
2
+ export default _default;
@@ -0,0 +1,8 @@
1
+ export interface RefusalError extends Error {
2
+ code: string;
3
+ gjsifyModule: string;
4
+ gjsifyMember: string;
5
+ }
6
+ export declare function refusal(member: string, platform: string): RefusalError;
7
+ /** `target` restricted to `members`; any other property read throws {@link refusal}. */
8
+ export declare function subsetOf<T extends object>(target: T, members: ReadonlySet<string | symbol>, platform: string): T;
@@ -0,0 +1,2 @@
1
+ declare const _default: () => Promise<void>;
2
+ export default _default;
@@ -0,0 +1,18 @@
1
+ /** `XDP_BACKGROUND_FLAG_*`: values, not behaviour, so they stay real. */
2
+ export declare const BackgroundFlags: {
3
+ readonly NONE: 0;
4
+ readonly AUTOSTART: 1;
5
+ readonly ACTIVATABLE: 2;
6
+ };
7
+ export type BackgroundFlags = (typeof BackgroundFlags)[keyof typeof BackgroundFlags];
8
+ export declare function createStub(runtime: string): {
9
+ Portal: {
10
+ new (): {};
11
+ "new"(): never;
12
+ };
13
+ XdpGtk4: {
14
+ parent_new_gtk: (_window: unknown) => null;
15
+ };
16
+ requestBackground: () => never;
17
+ setBackgroundStatus: () => never;
18
+ };
@@ -0,0 +1,2 @@
1
+ declare const _default: () => Promise<void>;
2
+ export default _default;
@@ -0,0 +1,17 @@
1
+ /** `XDP_BACKGROUND_FLAG_AUTOSTART`. `wish.gjs.spec.ts` holds this against the typelib's own value. */
2
+ export declare const AUTOSTART_FLAG: number;
3
+ export type BackgroundOutcome = 'granted' | 'denied';
4
+ /**
5
+ * A request is the whole wish, not a delta (ADR 0144 § 1): without AUTOSTART it removes an
6
+ * existing entry. This one predicate is the rule an implementer gets wrong by instinct.
7
+ */
8
+ export declare function wantsAutostart(flags: number): boolean;
9
+ /** `request_background_finish`'s boolean: `false` is the person saying no. Cancelled and broken throw instead. */
10
+ export declare function outcomeOf(granted: boolean): BackgroundOutcome;
11
+ export type ProbeVerdict = 'absent' | 'broken';
12
+ /**
13
+ * Whether a failed probe means "no Background portal here" (fall through to the autostart file) or
14
+ * "a portal answered and is unwell" (throw, never fall through). `remoteError` is the D-Bus error
15
+ * name, or `null` for an error that did not come off the wire.
16
+ */
17
+ export declare function classifyProbeError(remoteError: string | null): ProbeVerdict;
@@ -0,0 +1,2 @@
1
+ declare const _default: () => Promise<void>;
2
+ export default _default;
@@ -0,0 +1,2 @@
1
+ declare const _default: () => Promise<void>;
2
+ export default _default;
package/package.json CHANGED
@@ -1,6 +1,93 @@
1
1
  {
2
- "name": "@gjsify/xdp",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
2
+ "name": "@gjsify/xdp",
3
+ "version": "0.64.54",
4
+ "description": "libportal's Background portal on every desktop: the real `gi://Xdp` on Linux, and a driver where there is none. Start-at-login and background permission by capability, never by mechanism.",
5
+ "module": "lib/esm/index.js",
6
+ "types": "lib/types/index.d.ts",
7
+ "type": "module",
8
+ "sideEffects": false,
9
+ "exports": {
10
+ ".": {
11
+ "types": "./lib/types/index.d.ts",
12
+ "default": "./lib/esm/index.js"
13
+ },
14
+ "./background": {
15
+ "types": "./lib/types/background.d.ts",
16
+ "default": "./lib/esm/background.js"
17
+ },
18
+ "./browser": {
19
+ "types": "./lib/types/browser.d.ts",
20
+ "default": "./lib/esm/browser.js"
21
+ },
22
+ "./nativescript": {
23
+ "types": "./lib/types/nativescript.d.ts",
24
+ "default": "./lib/esm/nativescript.js"
25
+ }
26
+ },
27
+ "files": [
28
+ "lib",
29
+ "!lib/types/fake-portal.d.ts",
30
+ "!lib/types/**/*.spec.d.ts"
31
+ ],
32
+ "scripts": {
33
+ "clear": "gjsify clear lib tmp tsconfig.tsbuildinfo test.gjs.mjs test.node.mjs",
34
+ "check": "gjsify tsc --noEmit",
35
+ "build": "gjsify run build:gjsify && gjsify run build:types",
36
+ "build:gjsify": "gjsify build --library 'src/**/*.{ts,js}' --exclude 'src/**/*.spec.{mts,ts}' 'src/test.{mts,ts}' 'src/test.gjs.mts' 'src/fake-portal.ts'",
37
+ "build:types": "gjsify tsc",
38
+ "build:test": "gjsify run build:test:gjs && gjsify run build:test:node",
39
+ "build:test:gjs": "gjsify build src/test.gjs.mts --app gjs --outfile test.gjs.mjs",
40
+ "build:test:node": "gjsify build src/test.mts --app node --outfile test.node.mjs",
41
+ "test": "gjsify run build:gjsify && gjsify run build:test && gjsify run test:node && gjsify run test:gjs",
42
+ "test:gjs": "gjsify env DBUS_SESSION_BUS_ADDRESS=unix:path=/nonexistent XDG_RUNTIME_DIR=/nonexistent gjsify run test.gjs.mjs",
43
+ "test:node": "node test.node.mjs"
44
+ },
45
+ "keywords": [
46
+ "gjs",
47
+ "libportal",
48
+ "xdp",
49
+ "portal",
50
+ "background",
51
+ "autostart"
52
+ ],
53
+ "dependencies": {
54
+ "@girs/gio-2.0": "5.4.0",
55
+ "@girs/gjs": "5.4.0",
56
+ "@girs/glib-2.0": "5.4.0",
57
+ "@girs/gobject-2.0": "5.4.0",
58
+ "@girs/xdp-1.0": "5.4.0",
59
+ "@girs/xdpgtk4-1.0": "5.4.0"
60
+ },
61
+ "devDependencies": {
62
+ "@gjsify/cli": "0.64.54",
63
+ "@gjsify/unit": "0.64.54",
64
+ "typescript": "^6.0.3"
65
+ },
66
+ "license": "MIT",
67
+ "repository": {
68
+ "type": "git",
69
+ "url": "git+https://github.com/gjsify/gjsify.git",
70
+ "directory": "packages/gjs/xdp"
71
+ },
72
+ "bugs": {
73
+ "url": "https://github.com/gjsify/gjsify/issues"
74
+ },
75
+ "homepage": "https://github.com/gjsify/gjsify/tree/main/packages/gjs/xdp#readme",
76
+ "gjsify": {
77
+ "tier": 3,
78
+ "runtimes": {
79
+ "gjs": "polyfill",
80
+ "node": "polyfill",
81
+ "browser": "none",
82
+ "nativescript": "none"
83
+ },
84
+ "os": {
85
+ "linux": "supported",
86
+ "darwin": "none",
87
+ "win32": "supported"
88
+ },
89
+ "osNotes": {
90
+ "darwin": "No driver yet: ADR 0144 § 2 decides on SMAppService behind a new native bridge, which does not exist."
91
+ }
92
+ }
93
+ }