@phreshos/cli 0.1.3 → 0.1.5

package/dist/create.js

@@ -0,0 +1,139 @@
+import { projectDependency, installProjectDependencies, projectPackageManager, projectScript } from "./project-dependency.js";
+import prompts from "./prompts.js";
+import { accent, bold } from "./style.js";
+import { cpSync, existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { basename, dirname, extname, relative, resolve } from "node:path";
+/** Creates a complete Program from the bundled Phresh Program snapshot. */
+export default async function create(options = {}, directory = process.cwd()) {
+    const interaction = prompts();
+    interaction.begin("Create Program", "Phresh Program");
+    const requested = options.directory ?? (interaction.interactive
+        ? await interaction.ask("A new directory will contain the complete Server and Client project.", "Where should the Program be created?", "my-program")
+        : undefined);
+    if (!requested)
+        throw new Error("create needs a <directory> when no terminal is attached");
+    const target = resolve(directory, requested);
+    const identity = basename(target);
+    if (!programIdentity.test(identity))
+        throw new Error(`The directory name must be a kebab-case Program identity; received "${identity}"`);
+    if (existsSync(target))
+        throw new Error(`The destination already exists: ${target}`);
+    const name = options.name ?? (interaction.interactive
+        ? await interaction.ask("This name is shown to people; the directory name remains the Program identity.", "What name should people see?", title(identity))
+        : title(identity));
+    if (!name.trim())
+        throw new Error("--name must not be empty");
+    const install = options.install !== false;
+    const detected = projectPackageManager(directory).name;
+    const manager = options.packageManager ?? (install && interaction.interactive
+        ? packageManager(await interaction.choose("The generated project remains portable; this choice installs its dependencies now.", "Which package manager should be used?", packageManagers, detected))
+        : detected);
+    const parent = dirname(target);
+    mkdirSync(parent, { recursive: true });
+    const staging = mkdtempSync(resolve(parent, `.${identity}-`));
+    const bundled = template();
+    let placed = false;
+    try {
+        cpSync(bundled.directory, staging, { recursive: true });
+        renameSync(resolve(staging, "gitignore"), resolve(staging, ".gitignore"));
+        customize(staging, target, identity, name, manager);
+        renameSync(staging, target);
+        placed = true;
+        // A project inside this repository becomes a real workspace member
+        // only at its final path. Install there so package selection sees the
+        // same project boundary that subsequent commands will see.
+        if (install)
+            await interaction.progress("Installing dependencies", "Dependencies installed", () => installProjectDependencies(target, manager, interaction.interactive ? "capture" : "inherit"));
+    }
+    catch (error) {
+        rmSync(placed ? target : staging, { recursive: true, force: true });
+        throw error;
+    }
+    interaction.finish("Done");
+    console.log(bold("\nOpen the project"));
+    console.log(accent(`cd ${relative(directory, target) || "."}`));
+    if (!install) {
+        console.log(bold("\nInstall dependencies"));
+        console.log(accent(installCommand(manager)));
+    }
+    const script = projectScript(target, manager, bundled.development ? "dev" : "start");
+    console.log(bold(`\n${bundled.development ? "Run Development Program" : "Run Program"}`));
+    console.log(accent(script));
+    console.log(bold("\nYou can now open the project and start building your Program"));
+}
+function template() {
+    const candidates = [
+        resolve(import.meta.dirname, "template"),
+        resolve(import.meta.dirname, "..", "dist", "template")
+    ];
+    for (const directory of candidates) {
+        if (!existsSync(directory))
+            continue;
+        const descriptionPath = resolve(dirname(directory), "template.json");
+        if (!existsSync(descriptionPath))
+            throw new Error("The CLI template description has not been built — run its build command and try again");
+        const description = JSON.parse(readFileSync(descriptionPath, "utf-8"));
+        if (typeof description.development !== "boolean")
+            throw new Error("The CLI template description is invalid — run its build command and try again");
+        return { directory, development: description.development };
+    }
+    throw new Error("The CLI template has not been built — run its build command and try again");
+}
+function customize(directory, finalDirectory, identity, name, manager) {
+    for (const path of textFiles(directory)) {
+        let content = readFileSync(path, "utf-8");
+        content = content.replaceAll("phresh-program", identity).replaceAll("Phresh Program", name);
+        if (basename(path) === "README.md") {
+            content = content
+                .replaceAll("bun install", `${manager} install`)
+                .replaceAll("bun phresh ", "phresh ");
+        }
+        writeFileSync(path, content);
+    }
+    const manifestPath = resolve(directory, "package.json");
+    const manifest = JSON.parse(readFileSync(manifestPath, "utf-8"));
+    manifest.name = identity;
+    for (const dependencies of [manifest.dependencies, manifest.devDependencies]) {
+        if (!dependencies)
+            continue;
+        for (const [dependency, range] of Object.entries(dependencies)) {
+            if (!isProjectPackage(dependency))
+                continue;
+            dependencies[dependency] = projectDependency(dependency, range, finalDirectory).manifestSpecifier;
+        }
+    }
+    writeFileSync(manifestPath, JSON.stringify(manifest, null, 4) + "\n");
+}
+function textFiles(directory) {
+    const files = [];
+    for (const entry of readdirSync(directory, { withFileTypes: true })) {
+        const path = resolve(directory, entry.name);
+        if (entry.isDirectory())
+            files.push(...textFiles(path));
+        else if (entry.isFile() && (textExtensions.has(extname(entry.name)) || textNames.has(entry.name)))
+            files.push(path);
+    }
+    return files;
+}
+function packageManager(value) {
+    if (value === "bun" || value === "npm" || value === "pnpm" || value === "yarn")
+        return value;
+    throw new Error(`The package manager must be bun, npm, pnpm, or yarn; received "${value}"`);
+}
+function isProjectPackage(value) {
+    return value === "@phreshos/core"
+        || value === "@phreshos/client"
+        || value === "@phreshos/server"
+        || value === "@phreshos/react"
+        || value === "@phreshos/cli";
+}
+function title(identity) {
+    return identity.split("-").map(word => word[0].toUpperCase() + word.slice(1)).join(" ");
+}
+function installCommand(manager) {
+    return `${manager} install`;
+}
+const programIdentity = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const textExtensions = new Set([".css", ".html", ".json", ".md", ".ts", ".tsx"]);
+const textNames = new Set([".gitignore", "gitignore"]);
+const packageManagers = ["bun", "npm", "pnpm", "yarn"];

package/dist/derive.js

@@ -27,14 +27,14 @@ export default function derive(config, directory, which) {
         name: config.name,
         version: config.version,
         description: config.description,
-        // Like icons, the document stays where the author put it for an
+        // Like the icon, the document stays where the author put it for an
         // attached run. Installation and packaging give it its canonical
         // name; the runtime receives an absolute source path here because a
         // derived description has no file beside which to resolve it.
         apiDocs: config.apiDocs && resolve(directory, config.apiDocs),
-        // Where they already are. Unlike pack, which stages them, this
-        // points into the authoring tree and leaves it alone.
-        icons: config.icons && resolve(directory, config.icons),
+        // Where it already is. Unlike pack, which gives it its canonical
+        // name, this points into the authoring tree and leaves it alone.
+        icon: config.icon && resolve(directory, config.icon),
         // Beside the source, and said out loud. A program built from an
         // object resolves what it leaves unsaid against the *system's*
         // working directory — so silence here means a program keeps what

package/dist/init.js

@@ -1,8 +1,8 @@
 import {} from "@phreshos/core";
 import { configFile, readManifest } from "./project.js";
-import { bold, dim, heading, line } from "./style.js";
+import { dim } from "./style.js";
 import ensureProjectDependency, { projectScript } from "./project-dependency.js";
-import { createInterface } from "node:readline/promises";
+import prompts from "./prompts.js";
 import { existsSync, writeFileSync } from "node:fs";
 import { resolve } from "node:path";
 /**
@@ -16,151 +16,130 @@ import { resolve } from "node:path";
 export default async function init(options = {}, directory = process.cwd(), coreRange = "^0.1.0") {
     const manifest = await readManifest(directory);
     const path = resolve(directory, configFile);
-    const interactive = Boolean(process.stdin.isTTY && process.stdout.isTTY);
+    const interaction = prompts();
+    const { interactive, ask, yes } = interaction;
     const explicitShape = options.server === true || options.client === true;
     if (existsSync(path) && options.force !== true && !interactive)
         throw new Error(`${configFile} already exists — use --force to replace it`);
-    const readline = interactive ? createInterface({ input: process.stdin, output: process.stdout }) : null;
-    async function ask(explanation, question, fallback) {
-        if (!readline)
-            throw new Error(`${question} Supply the corresponding option when no terminal is attached`);
-        const suffix = fallback === undefined ? "" : ` ${dim(`(${fallback})`)}`;
-        console.log(`  ${dim(explanation)}`);
-        const said = (await readline.question(`  ${bold(question)}${suffix} `)).trim();
-        console.log("");
-        return said || fallback || "";
+    interaction.begin("Initialize Program", manifest.name);
+    if (existsSync(path) && options.force !== true) {
+        interaction.detail(configFile, "already initialized");
+        if (!await yes("The existing configuration must be replaced before this project can be initialized again.", "Replace it?", false)) {
+            interaction.finish("No changes made");
+            return;
+        }
     }
-    async function yes(explanation, question, fallback) {
-        return (await ask(explanation, question, fallback ? "Y/n" : "y/N")).toLowerCase().startsWith("y");
+    interaction.detail("identity", manifest.name, "package.json");
+    if (manifest.version)
+        interaction.detail("version", manifest.version, "package.json");
+    if (manifest.description)
+        interaction.detail("description", manifest.description, "package.json");
+    let serverSelected = options.server === true;
+    let clientSelected = options.client === true;
+    if (!explicitShape) {
+        if (!interactive)
+            throw new Error("Choose at least one half with --server, --client, or both");
+        serverSelected = await yes("A Server runs on the host machine and can keep working without an open desktop.", "Does this Program have a Server?", true);
+        clientSelected = !serverSelected || await yes("A Client runs through a desktop and provides the Program's visual interface.", "Does this Program have a Client?", true);
     }
-    try {
-        if (existsSync(path) && options.force !== true) {
-            heading(configFile, "already initialized");
-            if (!await yes("The existing configuration must be replaced before this project can be initialized again.", "Replace it?", false)) {
-                console.log(`  ${dim("No changes made.")}\n`);
-                return;
-            }
-        }
-        heading("Initialize Program", manifest.name);
-        line("identity", manifest.name, "package.json");
-        if (manifest.version)
-            line("version", manifest.version, "package.json");
-        if (manifest.description)
-            line("description", manifest.description, "package.json");
-        console.log("");
-        let serverSelected = options.server === true;
-        let clientSelected = options.client === true;
-        if (!explicitShape) {
-            if (!interactive)
-                throw new Error("Choose at least one half with --server, --client, or both");
-            serverSelected = await yes("A Server runs on the host machine and can keep working without an open desktop.", "Does this Program have a Server?", true);
-            clientSelected = !serverSelected || await yes("A Client runs through a desktop and provides the Program's visual interface.", "Does this Program have a Client?", true);
-        }
-        if (!serverSelected && !clientSelected)
-            throw new Error("A Program must have a server half, a client half, or both");
-        const name = options.name ?? (interactive ? await ask("This name is shown to people; the package name remains the Program identity.", "What name should people see?", manifest.name) : undefined);
-        if (name !== undefined && name.trim().length === 0)
-            throw new Error("--name must not be empty");
-        let apiDocs = options.apiDocs;
-        if (interactive && apiDocs === undefined) {
-            const suggested = ["api-docs.md", "README.md"].find(file => existsSync(resolve(directory, file)));
-            if (await yes("API documentation explains only the services this Program itself provides.", "Does this Program provide API documentation?", Boolean(suggested))) {
-                apiDocs = await ask("The path is resolved from the project root and becomes the official API entry point.", "Where is the API documentation file?", suggested);
-            }
-        }
-        if (apiDocs !== undefined && apiDocs.trim().length === 0)
-            throw new Error("An API documentation path must not be empty");
-        let buildCommand = options.buildCommand;
-        if (interactive && buildCommand === undefined) {
-            const suggested = manifest.scripts?.build && projectScript(directory, manifest.packageManager, "build");
-            const builds = await yes("Production operations need the Program's built files.", "Build before start, install, and pack?", Boolean(suggested));
-            if (builds)
-                buildCommand = await ask("This command produces the production Server and Client files.", "What command builds the Program?", suggested || undefined);
+    if (!serverSelected && !clientSelected)
+        throw new Error("A Program must have a server half, a client half, or both");
+    const name = options.name ?? (interactive ? await ask("This name is shown to people; the package name remains the Program identity.", "What name should people see?", manifest.name) : undefined);
+    if (name !== undefined && name.trim().length === 0)
+        throw new Error("--name must not be empty");
+    let apiDocs = options.apiDocs;
+    if (interactive && apiDocs === undefined) {
+        const suggested = ["api-docs.md", "README.md"].find(file => existsSync(resolve(directory, file)));
+        if (await yes("API documentation explains only the services this Program itself provides.", "Does this Program provide API documentation?", false)) {
+            apiDocs = await ask("The path is resolved from the project root and becomes the official API entry point.", "Where is the API documentation file?", suggested);
         }
-        if (buildCommand !== undefined && buildCommand.trim().length === 0)
-            throw new Error("A build command must not be empty");
-        let server;
-        if (serverSelected) {
-            const location = options.serverLocation ?? (interactive ? await ask("The system runs the production Server from this project-relative directory.", "Where are the production Server files?", "build/server") : "");
-            const startCommand = options.serverStartCommand ?? (interactive ? await ask("This command runs inside the production Server directory.", "What command starts the production Server?", "node main.js") : "");
-            if (!location)
-                throw new Error("--server-location is required without a terminal");
-            if (!startCommand)
-                throw new Error("--server-start-command is required without a terminal");
-            let development = options.serverDevelopmentStartCommand;
-            if (interactive && development === undefined) {
-                const suggested = manifest.scripts?.dev && projectScript(directory, manifest.packageManager, "dev");
-                if (await yes("Development mode can run the Server directly from the project source.", "Run the Server from source during development?", Boolean(suggested && !clientSelected))) {
-                    development = await ask("This command remains attached to the phresh dev session.", "What command starts the development Server?", suggested || undefined);
-                }
+    }
+    if (apiDocs !== undefined && apiDocs.trim().length === 0)
+        throw new Error("An API documentation path must not be empty");
+    let buildCommand = options.buildCommand;
+    if (interactive && buildCommand === undefined) {
+        const suggested = manifest.scripts?.build && projectScript(directory, manifest.packageManager, "build");
+        const builds = await yes("Production operations need the Program's built files.", "Build before start, install, and pack?", Boolean(suggested));
+        if (builds)
+            buildCommand = await ask("This command produces the production Server and Client files.", "What command builds the Program?", suggested || undefined);
+    }
+    if (buildCommand !== undefined && buildCommand.trim().length === 0)
+        throw new Error("A build command must not be empty");
+    let server;
+    if (serverSelected) {
+        const location = options.serverLocation ?? (interactive ? await ask("The system runs the production Server from this project-relative directory.", "Where are the production Server files?", clientSelected ? "dist/server" : "dist") : "");
+        const startCommand = options.serverStartCommand ?? (interactive ? await ask("This command runs inside the production Server directory.", "What command starts the production Server?", "node main.js") : "");
+        if (!location)
+            throw new Error("--server-location is required without a terminal");
+        if (!startCommand)
+            throw new Error("--server-start-command is required without a terminal");
+        let development = options.serverDevelopmentStartCommand;
+        if (interactive && development === undefined) {
+            const suggested = manifest.scripts?.dev && projectScript(directory, manifest.packageManager, "dev");
+            if (await yes("Development mode can run the Server directly from the project source.", "Run the Server from source during development?", Boolean(suggested && !clientSelected))) {
+                development = await ask("This command remains attached to the phresh dev session.", "What command starts the development Server?", suggested || undefined);
             }
-            if (development !== undefined && development.trim().length === 0)
-                throw new Error("A server development command must not be empty");
-            server = { location, startCommand, ...development && { development: { startCommand: development } } };
         }
-        let client;
-        if (clientSelected) {
-            const location = options.clientLocation ?? (interactive ? await ask("The system serves the production Client from this project-relative directory.", "Where are the production Client files?", "dist") : "");
-            if (!location)
-                throw new Error("--client-location is required without a terminal");
-            let developmentUrl = options.clientDevelopmentUrl;
-            let developmentStartCommand = options.clientDevelopmentStartCommand;
-            if (interactive && developmentUrl === undefined && developmentStartCommand === undefined) {
-                const suggested = manifest.scripts?.dev && projectScript(directory, manifest.packageManager, "dev");
-                if (await yes("A development server can provide live updates instead of built Client files.", "Use a Client development server?", Boolean(suggested))) {
-                    developmentUrl = await ask("The desktop opens this exact HTTP or HTTPS address during phresh dev.", "What URL serves the development Client?", "http://localhost:5173/");
-                    if (await yes("The CLI can own the development server and stop it when the session ends.", "Should phresh dev start the Client server?", Boolean(suggested))) {
-                        developmentStartCommand = await ask("This command remains attached to the phresh dev session.", "What command starts the Client development server?", suggested || undefined);
-                    }
+        if (development !== undefined && development.trim().length === 0)
+            throw new Error("A server development command must not be empty");
+        server = { location, startCommand, ...development && { development: { startCommand: development } } };
+    }
+    let client;
+    if (clientSelected) {
+        const location = options.clientLocation ?? (interactive ? await ask("The system serves the production Client from this project-relative directory.", "Where are the production Client files?", serverSelected ? "dist/client" : "dist") : "");
+        if (!location)
+            throw new Error("--client-location is required without a terminal");
+        let developmentUrl = options.clientDevelopmentUrl;
+        let developmentStartCommand = options.clientDevelopmentStartCommand;
+        if (interactive && developmentUrl === undefined && developmentStartCommand === undefined) {
+            const suggested = manifest.scripts?.dev && projectScript(directory, manifest.packageManager, "dev");
+            if (await yes("A development server can provide live updates instead of built Client files.", "Use a Client development server?", Boolean(suggested))) {
+                developmentUrl = await ask("The desktop opens this exact HTTP or HTTPS address during phresh dev.", "What URL serves the development Client?", "http://localhost:5173/");
+                if (await yes("The CLI can own the development server and stop it when the session ends.", "Should phresh dev start the Client server?", Boolean(suggested))) {
+                    developmentStartCommand = await ask("This command remains attached to the phresh dev session.", "What command starts the Client development server?", suggested || undefined);
                 }
             }
-            if (developmentStartCommand !== undefined && developmentUrl === undefined)
-                throw new Error("--client-development-url is required with --client-development-start-command");
-            if (developmentUrl !== undefined && developmentUrl.trim().length === 0)
-                throw new Error("A client development URL must not be empty");
-            if (developmentUrl !== undefined && !httpUrl(developmentUrl))
-                throw new Error("A client development URL must use HTTP or HTTPS");
-            if (developmentStartCommand !== undefined && developmentStartCommand.trim().length === 0)
-                throw new Error("A client development command must not be empty");
-            client = {
-                location,
-                ...developmentUrl && { development: { url: developmentUrl, ...developmentStartCommand && { startCommand: developmentStartCommand } } }
-            };
         }
-        const described = {
-            identity: manifest.name,
-            name,
-            version: manifest.version,
-            description: manifest.description,
-            apiDocs,
-            buildCommand
+        if (developmentStartCommand !== undefined && developmentUrl === undefined)
+            throw new Error("--client-development-url is required with --client-development-start-command");
+        if (developmentUrl !== undefined && developmentUrl.trim().length === 0)
+            throw new Error("A client development URL must not be empty");
+        if (developmentUrl !== undefined && !httpUrl(developmentUrl))
+            throw new Error("A client development URL must use HTTP or HTTPS");
+        if (developmentStartCommand !== undefined && developmentStartCommand.trim().length === 0)
+            throw new Error("A client development command must not be empty");
+        client = {
+            location,
+            ...developmentUrl && { development: { url: developmentUrl, ...developmentStartCommand && { startCommand: developmentStartCommand } } }
         };
-        const config = server
-            ? { ...described, server, ...client && { client } }
-            : { ...described, client: client };
-        await ensureProjectDependency("@phreshos/core", coreRange, directory);
-        writeFileSync(path, compose(config));
-        heading(configFile, "created");
-        if (config.server)
-            line("server", config.server.startCommand, `./${config.server.location}`);
-        if (config.client)
-            line("client", `./${config.client.location}`);
-        console.log("");
-        const next = [config.server?.development || config.client?.development ? "phresh dev" : null, "phresh start", "phresh install"].filter(Boolean);
-        console.log(`  ${dim("Next:")} ${next.join(`  ${dim("or")}  `)}`);
-        if (config.client) {
-            heading("Client requirements");
-            line("base URL", "./", "required for production assets");
-            if (config.client.development)
-                line("CORS", "enabled", "required on the development server");
-            console.log("");
-        }
-        else
-            console.log("");
     }
-    finally {
-        readline?.close();
+    const described = {
+        identity: manifest.name,
+        name,
+        version: manifest.version,
+        description: manifest.description,
+        apiDocs,
+        buildCommand
+    };
+    const config = server
+        ? { ...described, server, ...client && { client } }
+        : { ...described, client: client };
+    await ensureProjectDependency("@phreshos/core", coreRange, directory);
+    writeFileSync(path, compose(config));
+    if (config.server)
+        interaction.detail("server", config.server.startCommand, `./${config.server.location}`);
+    if (config.client)
+        interaction.detail("client", `./${config.client.location}`);
+    const next = [config.server?.development || config.client?.development ? "phresh dev" : null, "phresh start", "phresh install"].filter(Boolean);
+    interaction.message();
+    interaction.message(`${dim("Next:")} ${next.join(`  ${dim("or")}  `)}`);
+    if (config.client) {
+        interaction.message();
+        interaction.detail("base URL", "./", "required for production assets");
+        if (config.client.development)
+            interaction.detail("CORS", "enabled", "required on the development server");
     }
+    interaction.finish(`${configFile} created`);
 }
 function compose(config) {
     const blocks = [
@@ -184,8 +163,7 @@ function compose(config) {
         `import { defineConfig } from "@phreshos/core"`,
         "",
         "export default defineConfig({",
-        "",
-        blocks.filter(Boolean).join(",\n\n"),
+        blocks.filter(Boolean).join(",\n"),
         "})",
         ""
     ].join("\n");
@@ -200,9 +178,9 @@ function half(name, values) {
         if (typeof value === "string")
             return `        ${key}: ${JSON.stringify(value)}`;
         const nested = Object.entries(value).map(([nestedKey, nestedValue]) => `            ${nestedKey}: ${JSON.stringify(nestedValue)}`);
-        return `        ${key}: {\n\n${nested.join(",\n\n")}\n        }`;
+        return `        ${key}: {\n${nested.join(",\n")}\n        }`;
     });
-    return `    ${name}: {\n\n${inside.join(",\n\n")}\n    }`;
+    return `    ${name}: {\n${inside.join(",\n")}\n    }`;
 }
 function httpUrl(value) {
     try {

package/dist/pack.js

@@ -17,7 +17,7 @@ import build from "./build-command.js";
  * a declared half always has a location, even when the system chose it.
  *
  * There is **no wrapping directory**. `program.json`, `server/`,
- * `client/` and `icons/` sit at the package's root, and the directory
+ * `client/` and optional `icon.png` sit at the package's root, and the directory
  * the system installs into is named from the program's own `identity`.
  * The archive itself therefore needs no second naming layer.
  *
@@ -41,11 +41,8 @@ export default async function pack(directory = process.cwd()) {
         if (!zip.getEntry("client/index.html"))
             throw new Error(`The client files have no index.html — ${config.client.location} is not where a client half is`);
     }
-    // Icons are the program's own affair rather than either half's: a
-    // headless program is shown too. Packaged like a half, and like a
-    // half their place is not the program's to choose.
-    if (config.icons)
-        place(zip, directory, config.icons, "icons");
+    if (config.icon)
+        file(zip, directory, config.icon, "icon.png", "Program icon");
     if (config.apiDocs)
         document(zip, directory, config.apiDocs);
     zip.addFile("program.json", Buffer.from(JSON.stringify(program(config, version), null, 4) + "\n"));
@@ -64,6 +61,7 @@ function program(config, version) {
         version,
         description: config.description,
         apiDocs: config.apiDocs ? "api-docs.md" : undefined,
+        icon: config.icon ? "icon.png" : undefined,
         ...config.server && { server: { location: "server", start: config.server.start, installCommand: config.server.installCommand, startCommand: config.server.startCommand } },
         ...config.client && { client: { location: "client", start: config.client.start, title: config.client.title, size: config.client.size, position: config.client.position, layer: config.client.layer, minimize: config.client.minimize } }
     };
@@ -77,8 +75,11 @@ function place(zip, directory, location, half) {
     zip.addLocalFolder(from, half);
 }
 function document(zip, directory, location) {
+    file(zip, directory, location, "api-docs.md", "API documentation file");
+}
+function file(zip, directory, location, target, label) {
     const from = resolve(directory, location);
     if (!existsSync(from) || !statSync(from).isFile())
-        throw new Error(`The API documentation file is not at ${location}`);
-    zip.addFile("api-docs.md", readFileSync(from));
+        throw new Error(`The ${label} is not at ${location}`);
+    zip.addFile(target, readFileSync(from));
 }

package/dist/program-intake.js

@@ -1,6 +1,6 @@
 import { connect } from "node:net";
 import { homedir } from "node:os";
-import { join } from "node:path";
+import { isAbsolute, join } from "node:path";
 /**
  * The local Program intake, from the CLI's side.
  *
@@ -19,7 +19,15 @@ import { join } from "node:path";
  * the Program says, then how it ended. None pretends to be a remote method
  * returning through an unrelated transport.
  */
-export const socketPath = join(homedir(), ".phreshos", "intake.sock");
+export function programIntakePath(environment = process.env, userHome = homedir()) {
+    const instanceHome = environment.PHRESHOS_HOME;
+    if (instanceHome === undefined)
+        return join(userHome, ".phreshos", "intake.sock");
+    if (!isAbsolute(instanceHome))
+        throw new Error("PHRESHOS_HOME must be an absolute filesystem path");
+    return join(instanceHome, "intake.sock");
+}
+export const socketPath = programIntakePath();
 export default function speak(question, heard, path = socketPath, signal) {
     return new Promise(function (settle, refuse) {
         const socket = connect(path);