windows-development-sandbox 0.0.0-stage → 1.1.0

package/dist/core/detect-toolchains.js

@@ -0,0 +1,58 @@
+import { projectUses } from '../guest/toolchains/versions.js';
+/** Files that show a project uses a language (looked for in the workspace and one folder down). */
+export const MARKERS = {
+    python: ['pyproject.toml', 'requirements.txt', 'setup.py', 'setup.cfg', 'Pipfile', 'uv.lock', 'poetry.lock', '.python-version', '*.py', '*.ipynb'],
+    rust: ['Cargo.toml', 'rust-toolchain', 'rust-toolchain.toml'],
+    msvc: ['*.vcxproj', 'CMakePresets.json', 'CMakeUserPresets.json'],
+    cpp: ['CMakeLists.txt', 'Makefile', 'meson.build', 'premake5.lua', 'Cargo.toml', '*.vcxproj', '*.c', '*.cpp', '*.cc', '*.h', '*.hpp'],
+    dotnet: ['*.sln', '*.slnx', '*.csproj', '*.fsproj', '*.vbproj', 'global.json', '*.cs'],
+    go: ['go.mod', 'go.work', '*.go'],
+    java: ['pom.xml', 'build.gradle', 'build.gradle.kts', 'settings.gradle', 'settings.gradle.kts', 'mvnw', 'gradlew', '.java-version', '.sdkmanrc', '*.java'],
+    ruby: ['Gemfile', '*.gemspec', '.ruby-version', '*.rb'],
+    php: ['composer.json', 'artisan', '.php-version', '*.php'],
+    deno: ['deno.json', 'deno.jsonc', 'deno.lock'],
+    // Windows PowerShell 5.1 runs any .ps1: PowerShell 7 is decided from script contents (hints.pwsh) or this PC.
+    pwsh: [],
+};
+export const AUTO_TOOLCHAINS = Object.keys(MARKERS);
+/** Files of any ecosystem: a folder with none of them is no project yet. */
+const PROJECT_FILES = [...new Set([...Object.values(MARKERS).flat(), 'package.json', 'deno.json', '*.ts', '*.js'])];
+/**
+ * The decision per toolchain. true/false are kept; "auto" is on when the project has one of its marker files, or, in
+ * a folder that is no project yet, when this PC has the language installed. Rust needs a linker (MSVC or C/C++).
+ * hints: reasons found by reading files (a script that calls vcvars/vswhere) or about this PC ("builds Rust with MSVC"),
+ * which turn an "auto" toolchain on like a marker file does.
+ */
+export const decideToolchains = (settings, entries, pcHas, hints = {}) => {
+    const fresh = !projectUses(entries, PROJECT_FILES);
+    const decide = (name) => {
+        const setting = settings[name].enabled;
+        if (setting !== 'auto')
+            return { on: setting, reason: setting ? 'enabled in config' : 'disabled in config' };
+        const marker = MARKERS[name].map((m) => entries.find((e) => projectUses([e], [m]))).find(Boolean);
+        if (marker)
+            return { on: true, reason: marker };
+        if (hints[name])
+            return { on: true, reason: hints[name] };
+        if (fresh && pcHas.includes(name))
+            return { on: true, reason: 'installed on this PC (new folder)' };
+        return { on: false, reason: 'not used by this project' };
+    };
+    const result = Object.fromEntries(AUTO_TOOLCHAINS.map((name) => [name, decide(name)]));
+    // Rust links with MSVC when this PC does (its rustup host is *-msvc), otherwise with MinGW's gcc.
+    if (result.rust.on && settings.msvc.enabled === 'auto' && !result.msvc.on && pcHas.includes('msvc'))
+        result.msvc = { on: true, reason: 'Rust on this PC builds with MSVC' };
+    // MSVC is a 1-2 GB licensed download: "auto" only installs it once its licence is accepted.
+    if (settings.msvc.enabled === 'auto' && result.msvc.on && !settings.msvc.acceptLicense)
+        result.msvc = { on: false, reason: 'would be used (' + result.msvc.reason + '); set toolchains.msvc.acceptLicense to install it' };
+    if (result.rust.on && !result.msvc.on && !result.cpp.on && settings.cpp.enabled !== false)
+        result.cpp = { on: true, reason: 'the linker for Rust' };
+    return result;
+};
+/** The settings with every "auto" replaced by the decision (what the sandbox receives). */
+export const resolveToolchains = (settings, decisions) => {
+    const out = structuredClone(settings);
+    for (const name of AUTO_TOOLCHAINS)
+        out[name].enabled = decisions[name].on;
+    return out;
+};

package/dist/core/disk.d.ts

@@ -0,0 +1,16 @@
+export declare const GB: number;
+/** 1536 -> "1.5 KB". */
+export declare const humanBytes: (bytes: number) => string;
+/** Size on disk, never following links or junctions (a link counts as 0, so a planted junction cannot make us walk this PC's disk). */
+export declare const sizeOf: (p: string) => number;
+/** Free bytes on the drive that holds `dir` (which may not exist yet: the nearest existing parent is asked); null if unknown. */
+export declare const freeBytesAt: (dir: string) => number | null;
+export interface DiskUsage {
+    drive: string;
+    totalBytes: number;
+    freeBytes: number;
+    usedBytes: number;
+    holdsStorage: boolean;
+}
+/** Every local drive's size and free space, and which one holds the sandbox storage. */
+export declare const diskUsage: (storageRoot: string) => DiskUsage[];

package/dist/core/disk.js

@@ -0,0 +1,55 @@
+// Sizes and free space on disk, shared by `data`, `repair`, `setup` and the storage cleanup.
+import fs from 'node:fs';
+import path from 'node:path';
+import _ from 'lodash';
+export const GB = 1024 ** 3;
+/** 1536 -> "1.5 KB". */
+export const humanBytes = (bytes) => {
+    const units = ['B', 'KB', 'MB', 'GB', 'TB'];
+    const i = bytes <= 0 ? 0 : Math.min(units.length - 1, Math.floor(Math.log(bytes) / Math.log(1024)));
+    const value = bytes / 1024 ** i;
+    return (i === 0 ? String(bytes) : value.toFixed(value < 10 ? 1 : 0)) + ' ' + units[i];
+};
+/** Size on disk, never following links or junctions (a link counts as 0, so a planted junction cannot make us walk this PC's disk). */
+export const sizeOf = (p) => {
+    try {
+        const stat = fs.lstatSync(p);
+        if (stat.isSymbolicLink())
+            return 0;
+        if (!stat.isDirectory())
+            return stat.size;
+        return _.sumBy(fs.readdirSync(p, { withFileTypes: true }), (d) => (d.isSymbolicLink() ? 0 : sizeOf(path.join(p, d.name))));
+    }
+    catch {
+        return 0;
+    }
+};
+/** Free bytes on the drive that holds `dir` (which may not exist yet: the nearest existing parent is asked); null if unknown. */
+export const freeBytesAt = (dir) => {
+    let at = path.resolve(dir);
+    while (!fs.existsSync(at) && path.dirname(at) !== at)
+        at = path.dirname(at);
+    try {
+        const s = fs.statfsSync(at);
+        return s.bavail * s.bsize;
+    }
+    catch {
+        return null;
+    }
+};
+/** Every local drive's size and free space, and which one holds the sandbox storage. */
+export const diskUsage = (storageRoot) => {
+    const storageDrive = path.parse(path.resolve(storageRoot)).root.toUpperCase();
+    return 'CDEFGHIJKLMNOPQRSTUVWXYZ'.split('').map((letter) => letter + ':\\').flatMap((drive) => {
+        try {
+            const s = fs.statfsSync(drive);
+            const totalBytes = s.blocks * s.bsize;
+            if (!totalBytes)
+                return [];
+            return [{ drive, totalBytes, freeBytes: s.bavail * s.bsize, usedBytes: totalBytes - s.bfree * s.bsize, holdsStorage: drive.toUpperCase() === storageDrive }];
+        }
+        catch {
+            return [];
+        }
+    });
+};

package/dist/core/local-config.d.ts

@@ -0,0 +1,20 @@
+import type { Config, LocalConfigFile, Overrides } from './types.js';
+export declare const LOCAL_CONFIG_NAME = ".sandbox-config.json";
+/** Validates a folder's settings and resolves its relative paths against that folder. */
+export declare const normalizeOverrides: (data: unknown, dir: string, source: string) => Overrides;
+/**
+ * Protections a project file may only make stricter, never looser. A repo can ship the file, so it must not be able to
+ * switch off what you turned on (or turn on what you turned off). The strictest of the two values always wins.
+ */
+export declare const ON_IS_SAFER: string[];
+export declare const OFF_IS_SAFER: string[];
+export declare const GIT_STRICTNESS: Record<string, number>;
+export declare const NEVER_LOOSER: string[];
+/** Applies validated overrides. Mappings with the same guest folder replace the configured ones. */
+export declare const applyOverrides: (config: Config, ov: Overrides) => Config;
+/** Human-readable list of what a local config changes, with risky items flagged. */
+export declare const describeOverrides: (ov: Overrides) => string[];
+export declare const readLocalConfig: (dir: string) => LocalConfigFile | null;
+export declare const trustStorePath: (storageRoot: string) => string;
+export declare const isTrusted: (store: string, file: string, hash: string) => boolean;
+export declare const saveTrust: (store: string, file: string, hash: string) => void;

package/dist/core/local-config.js

@@ -0,0 +1,77 @@
+// A project's .sandbox-config.json: validated against the LocalOverrides schema (a safe subset of settings), applied
+// over the user config, and only used once you have approved this exact version of the file.
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import _ from 'lodash';
+import { mergeConfig } from './config.js';
+import { describeIssues, LocalOverrides } from './schema.js';
+import { expandPath, fail, fileExists, parseJsonc, tryReadJson, writeJson } from './util.js';
+export const LOCAL_CONFIG_NAME = '.sandbox-config.json';
+/** Validates a folder's settings and resolves its relative paths against that folder. */
+export const normalizeOverrides = (data, dir, source) => {
+    const parsed = LocalOverrides.safeParse(data);
+    if (!parsed.success)
+        fail(source + ' is not valid:\n  - ' + describeIssues(parsed.error).join('\n  - '));
+    const overrides = parsed.data;
+    const scripts = overrides.scripts?.map((s) => expandPath(s, dir));
+    const missing = scripts?.filter((s) => !fileExists(s)) ?? [];
+    if (missing.length)
+        fail(source + ' is not valid:\n  - scripts: file not found: ' + missing.join(', '));
+    return { ...overrides, scripts, mappings: overrides.mappings?.map((m) => ({ ...m, host: expandPath(m.host, dir) })) };
+};
+/**
+ * Protections a project file may only make stricter, never looser. A repo can ship the file, so it must not be able to
+ * switch off what you turned on (or turn on what you turned off). The strictest of the two values always wins.
+ */
+export const ON_IS_SAFER = ['readOnly', 'network.blockPrivateRanges', 'sandbox.protectedClient', 'downloads.requireChecksum'];
+export const OFF_IS_SAFER = ['sandbox.networking', 'sandbox.clipboard', 'sandbox.audioInput', 'sandbox.videoInput', 'sandbox.printerRedirection', 'sandbox.vGpu', 'claudeProfile.copyCredentials'];
+export const GIT_STRICTNESS = { full: 0, readonly: 1, none: 2 };
+export const NEVER_LOOSER = [...ON_IS_SAFER, ...OFF_IS_SAFER, 'provisioning.git.access'];
+const keepStrictest = (yours, merged) => {
+    ON_IS_SAFER.forEach((p) => _.set(merged, p, Boolean(_.get(yours, p)) || Boolean(_.get(merged, p))));
+    OFF_IS_SAFER.forEach((p) => _.set(merged, p, Boolean(_.get(yours, p)) && Boolean(_.get(merged, p))));
+    if (GIT_STRICTNESS[yours.provisioning.git.access] > GIT_STRICTNESS[merged.provisioning.git.access])
+        merged.provisioning.git.access = yours.provisioning.git.access;
+};
+/** Applies validated overrides. Mappings with the same guest folder replace the configured ones. */
+export const applyOverrides = (config, ov) => {
+    const { harness, mappings, scripts: _scripts, $schema: _schema, ...rest } = ov;
+    const next = mergeConfig(config, rest);
+    keepStrictest(config, next);
+    if (harness)
+        next.defaultHarness = harness;
+    if (mappings)
+        next.mappings = [..._.reject(config.mappings, (m) => mappings.some((o) => o.guest.toLowerCase() === m.guest.toLowerCase())), ...mappings];
+    return next;
+};
+const flatten = (value, prefix = '') => _.isPlainObject(value) ? Object.entries(value).flatMap(([k, v]) => flatten(v, prefix ? prefix + '.' + k : k)) : [prefix + ' = ' + JSON.stringify(value)];
+/** Human-readable list of what a local config changes, with risky items flagged. */
+export const describeOverrides = (ov) => {
+    const { harness, mappings = [], scripts = [], $schema: _schema, ...sections } = ov;
+    const lines = [
+        ...(harness ? ['agent = ' + harness] : []),
+        ...mappings.map((m) => (m.readOnly ? 'read-only' : 'READ/WRITE') + ' folder ' + m.host + '  ->  ' + m.guest),
+        ...scripts.map((s) => 'runs inside the sandbox: ' + s),
+        ...flatten(sections),
+    ];
+    const risky = _.compact([
+        mappings.some((m) => !m.readOnly) && 'a READ/WRITE mapping lets the agent change files outside your workspace',
+    ]);
+    // These are only used when they are stricter than your own settings, so a project can never loosen them.
+    const limited = NEVER_LOOSER.filter((p) => _.has(sections, p)).map((p) => p + ' is only used if it is stricter than your own setting');
+    return [...lines, ...risky.map((r) => '!! ' + r), ...limited.map((r) => '   ' + r)];
+};
+export const readLocalConfig = (dir) => {
+    const file = path.join(dir, LOCAL_CONFIG_NAME);
+    if (!fileExists(file))
+        return null;
+    const raw = fs.readFileSync(file);
+    return { path: file, hash: crypto.createHash('sha256').update(raw).digest('hex'), data: parseJsonc(raw.toString('utf8'), file) };
+};
+// ---- approvals (host-only: <storage>\trusted-configs.json) ----------------------------------------------------------
+export const trustStorePath = (storageRoot) => path.join(storageRoot, 'trusted-configs.json');
+const loadTrust = (store) => tryReadJson(store) ?? {};
+const key = (file) => path.resolve(file).toLowerCase();
+export const isTrusted = (store, file, hash) => loadTrust(store)[key(file)] === hash;
+export const saveTrust = (store, file, hash) => writeJson(store, { ...loadTrust(store), [key(file)]: hash });

package/dist/core/project-policy.d.ts

@@ -0,0 +1,15 @@
+import type { Config } from './types.js';
+/** The protections of a running sandbox, by setting path (`sandbox.networking`, `provisioning.git.access`, ...). */
+export type Protections = Record<string, boolean | string>;
+export declare const protectionsOf: (config: Config) => Protections;
+export interface JoinCheck {
+    /** Settings this project needs stricter than the running sandbox: the launch is refused. */
+    stricter: string[];
+    /** Settings it would have looser: it gets the sandbox's (stricter) value; shown as a note. */
+    looser: string[];
+}
+/**
+ * Compares a project's effective protections with the running sandbox's. Hub projects are always read/write
+ * (Windows Sandbox maps the hub once, read/write), so a read-only project counts as stricter.
+ */
+export declare const checkJoin: (running: Protections, wanted: Protections) => JoinCheck;

package/dist/core/project-policy.js

@@ -0,0 +1,35 @@
+// Joining a running sandbox from another project. Its protections (network, LAN block, git access, clipboard, the
+// .wsb device settings, read-only) are machine-wide: they were fixed when the sandbox booted for the first project.
+// A second project may never loosen them, and a project that needs a STRICTER setting than the running sandbox has
+// cannot get it there without changing it for the sessions already running, so that launch is refused with a clear
+// message. A project asking for less than the sandbox has simply runs with the sandbox's (stricter) setting.
+// Pure: the host checks it before registering a project, the tests drive it directly.
+import _ from 'lodash';
+import { GIT_STRICTNESS, NEVER_LOOSER, OFF_IS_SAFER, ON_IS_SAFER } from './local-config.js';
+export const protectionsOf = (config) => Object.fromEntries(NEVER_LOOSER.map((p) => [p, _.get(config, p)]));
+/** 1 = `wanted` is stricter than `running`, -1 = looser, 0 = the same. */
+const compare = (setting, running, wanted) => {
+    if (setting === 'provisioning.git.access')
+        return Math.sign((GIT_STRICTNESS[String(wanted)] ?? 0) - (GIT_STRICTNESS[String(running)] ?? 0));
+    if (ON_IS_SAFER.includes(setting))
+        return Number(Boolean(wanted)) - Number(Boolean(running));
+    if (OFF_IS_SAFER.includes(setting))
+        return Number(Boolean(running)) - Number(Boolean(wanted));
+    return 0;
+};
+/**
+ * Compares a project's effective protections with the running sandbox's. Hub projects are always read/write
+ * (Windows Sandbox maps the hub once, read/write), so a read-only project counts as stricter.
+ */
+export const checkJoin = (running, wanted) => {
+    const stricter = [];
+    const looser = [];
+    for (const setting of NEVER_LOOSER) {
+        const result = compare(setting, setting === 'readOnly' ? false : running[setting], wanted[setting]);
+        if (result > 0)
+            stricter.push(setting + ' = ' + JSON.stringify(wanted[setting]) + ' (the running sandbox has ' + JSON.stringify(setting === 'readOnly' ? false : running[setting]) + ')');
+        if (result < 0)
+            looser.push(setting + ' stays ' + JSON.stringify(running[setting]));
+    }
+    return { stricter, looser };
+};

package/dist/core/prompt.d.ts

@@ -0,0 +1,4 @@
+/** A yes/no question (default no). */
+export declare const askYesNo: (question: string, defaultYes?: boolean) => Promise<boolean>;
+/** Asks the user to type `expected` (a stronger confirmation than yes/no). */
+export declare const askTyped: (question: string, expected: string) => Promise<boolean>;

package/dist/core/prompt.js

@@ -0,0 +1,15 @@
+// Questions asked on the terminal, all through @inquirer/prompts. Without an interactive terminal the answer is always "no".
+import { confirm, input } from '@inquirer/prompts';
+/** A yes/no question (default no). */
+export const askYesNo = async (question, defaultYes = false) => {
+    if (!process.stdin.isTTY)
+        return false;
+    return confirm({ message: question, default: defaultYes });
+};
+/** Asks the user to type `expected` (a stronger confirmation than yes/no). */
+export const askTyped = async (question, expected) => {
+    if (!process.stdin.isTTY)
+        return false;
+    const answer = await input({ message: question + ' Type "' + expected + '" to confirm:' });
+    return answer.trim().toLowerCase() === expected;
+};

package/dist/core/safe-paths.d.ts

@@ -0,0 +1,4 @@
+/** A read/write folder mapped into the sandbox must not contain, or sit inside, any protected folder. */
+export declare const assertSafeMapping: (folder: string, packageRoot: string, storageRoot: string) => void;
+/** The agent gets read/write access to the workspace, so refuse folders that would let it reach the tool itself, its storage, or the OS. */
+export declare const assertSafeWorkspace: (workspace: string, packageRoot: string, storageRoot: string) => void;

package/dist/core/safe-paths.js

@@ -0,0 +1,37 @@
+// Which folders may be shared with the sandbox. The agent gets read/write access to what is mapped, so nothing that
+// would let it reach this tool, its storage, your settings or the OS may be mapped.
+import { userDir } from './config.js';
+import { fail, isInsideOrEqual, isRootPath, isUserProfile } from './util.js';
+/** Folders the agent must never be able to write: the tool itself, its storage and your settings for it. */
+const protectedFolders = (packageRoot, storageRoot) => [
+    ['this tool\'s install folder', packageRoot],
+    ['the sandbox storage folder', storageRoot],
+    ['your sandbox settings folder', userDir()],
+];
+/** A read/write folder mapped into the sandbox must not contain, or sit inside, any protected folder. */
+export const assertSafeMapping = (folder, packageRoot, storageRoot) => {
+    if (isRootPath(folder) || isUserProfile(folder))
+        fail('A whole drive or user profile cannot be mapped into the sandbox: ' + folder, 'Map a specific folder instead.');
+    for (const [label, dir] of protectedFolders(packageRoot, storageRoot)) {
+        if (isInsideOrEqual(dir, folder) || isInsideOrEqual(folder, dir))
+            fail(folder + ' cannot be mapped into the sandbox: it overlaps ' + label + ' (' + dir + ').', 'Map a folder that is not inside (and does not contain) ' + dir + '.');
+    }
+};
+/** The agent gets read/write access to the workspace, so refuse folders that would let it reach the tool itself, its storage, or the OS. */
+export const assertSafeWorkspace = (workspace, packageRoot, storageRoot) => {
+    if (isRootPath(workspace))
+        fail('A whole drive cannot be the workspace: ' + workspace, 'Run sandbox claude from a project folder (or pass --workspace <folder>).');
+    if (isUserProfile(workspace))
+        fail('Your whole user profile cannot be the workspace: ' + workspace, 'Run sandbox claude from a project folder (or pass --workspace <folder>).');
+    for (const [label, dir] of protectedFolders(packageRoot, storageRoot)) {
+        if (isInsideOrEqual(dir, workspace))
+            fail(workspace + ' cannot be the workspace: it is inside ' + label + ' (' + dir + '), so the agent could change the code that runs on this PC.', dir === packageRoot ? 'Developing windows-development-sandbox itself? Install it as a copy instead of a link: run `npm run install:global` in the repository, then sandbox claude works there.' : 'Run sandbox claude from a project folder somewhere else.');
+        if (isInsideOrEqual(workspace, dir))
+            fail(workspace + ' cannot be the workspace: it contains ' + label + ' (' + dir + '), which the agent must not be able to change.', 'Run sandbox claude from a project folder that does not contain it.');
+    }
+    for (const name of ['WINDIR', 'SystemRoot', 'ProgramFiles', 'ProgramFiles(x86)', 'ProgramData']) {
+        const dir = process.env[name];
+        if (dir && isInsideOrEqual(dir, workspace))
+            fail('A system folder cannot be the workspace: ' + workspace, 'Run sandbox claude from a project folder.');
+    }
+};

package/dist/core/schema/common.d.ts

@@ -0,0 +1,17 @@
+import { z } from 'zod';
+export declare const GuestPath: z.ZodString;
+export declare const Name: z.ZodString;
+export declare const Strings: z.ZodArray<z.ZodString>;
+export declare const toggle: (description: string) => z.ZodObject<{
+    enabled: z.ZodBoolean;
+}, z.core.$strict>;
+export declare const SchemaRef: z.ZodString;
+export declare const GitAccess: z.ZodEnum<{
+    readonly: "readonly";
+    full: "full";
+    none: "none";
+}>;
+/** true, false, or "auto": only when the project uses it (found from files like go.mod in the workspace or one level down). */
+export declare const Enabled: z.ZodUnion<readonly [z.ZodBoolean, z.ZodLiteral<"auto">]>;
+export declare const enabled: (what: string, markers: string) => z.ZodUnion<readonly [z.ZodBoolean, z.ZodLiteral<"auto">]>;
+export declare const Packages: (what: string, example: string) => z.ZodArray<z.ZodString>;

package/dist/core/schema/common.js

@@ -0,0 +1,15 @@
+// Building blocks shared by the settings schemas.
+import { z } from 'zod';
+import { isValidGuestPath } from '../../shared/guest-paths.js';
+// Rules (and RESERVED_GUEST) live in shared/guest-paths.ts: the host re-checks them before writing the .wsb.
+export const GuestPath = z.string().refine(isValidGuestPath, 'reserved or invalid guest path (a folder under C:\\ other than Windows, Program Files, Users, AgentData, Mirror, ..., or on drive D: to Z:)');
+export const Name = z.string().regex(/^[A-Za-z0-9_-]+$/, 'letters, numbers, - and _ only');
+export const Strings = z.array(z.string());
+export const toggle = (description) => z.strictObject({ enabled: z.boolean().describe(description) });
+export const SchemaRef = z.string().describe('Path or URL of the JSON Schema for editor autocomplete and docs.');
+export const GitAccess = z.enum(['full', 'readonly', 'none'])
+    .describe('full: normal git. readonly: status/log/diff/show/blame only (no commit, push, checkout, ...). none: no git at all; .git is hidden from the agent.');
+/** true, false, or "auto": only when the project uses it (found from files like go.mod in the workspace or one level down). */
+export const Enabled = z.union([z.boolean(), z.literal('auto')]);
+export const enabled = (what, markers) => Enabled.describe(what + ' true, false, or "auto" = only when the project has ' + markers + '.');
+export const Packages = (what, example) => Strings.describe(what + ', installed once and kept (e.g. ' + example + ').');