@phreshos/cli 0.1.4 → 0.1.5

package/dist/create.js

@@ -1,83 +1,88 @@
-import { projectDependency, installProjectDependencies, projectPackageManager } from "./project-dependency.js";
-import questions from "./questions.js";
-import { dim, heading, line } from "./style.js";
+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 Get Started snapshot. */
+/** Creates a complete Program from the bundled Phresh Program snapshot. */
 export default async function create(options = {}, directory = process.cwd()) {
-    const prompts = questions();
+    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 {
-        const requested = options.directory ?? (prompts.interactive
-            ? await prompts.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 ?? (prompts.interactive
-            ? await prompts.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 && prompts.interactive
-            ? packageManager(await prompts.ask("The generated project remains portable; this choice installs its dependencies now.", "Which package manager should be used?", detected))
-            : detected);
-        heading("Create Program", name);
-        line("identity", identity);
-        line("directory", target);
-        line("template", "Get Started");
+        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)
-            line("packages", manager);
-        console.log("");
-        const parent = dirname(target);
-        mkdirSync(parent, { recursive: true });
-        const staging = mkdtempSync(resolve(parent, `.${identity}-`));
-        try {
-            cpSync(template(), staging, { recursive: true });
-            renameSync(resolve(staging, "gitignore"), resolve(staging, ".gitignore"));
-            customize(staging, target, identity, name, manager);
-            if (install)
-                await installProjectDependencies(staging, manager);
-            renameSync(staging, target);
-        }
-        catch (error) {
-            rmSync(staging, { recursive: true, force: true });
-            throw error;
-        }
-        heading(name, "created");
-        line("directory", target);
-        line("packages", install ? "installed" : "not installed");
-        console.log("");
-        console.log(`  ${dim("Next:")} cd ${relative(directory, target) || "."}`);
-        if (!install)
-            console.log(`        ${manager} install`);
-        console.log("        phresh dev");
-        console.log("");
+            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;
     }
-    finally {
-        prompts.close();
+    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")
     ];
-    const found = candidates.find(existsSync);
-    if (!found)
-        throw new Error("The CLI template has not been built — run its build command and try again");
-    return found;
+    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("get-started", identity).replaceAll("Get Started", name);
+        content = content.replaceAll("phresh-program", identity).replaceAll("Phresh Program", name);
         if (basename(path) === "README.md") {
             content = content
                 .replaceAll("bun install", `${manager} install`)
@@ -125,6 +130,10 @@ function isProjectPackage(value) {
 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 { dim, heading, line } from "./style.js";
+import { dim } from "./style.js";
 import ensureProjectDependency, { projectScript } from "./project-dependency.js";
-import questions from "./questions.js";
+import prompts from "./prompts.js";
 import { existsSync, writeFileSync } from "node:fs";
 import { resolve } from "node:path";
 /**
@@ -16,139 +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 prompts = questions();
-    const { interactive, ask, yes } = prompts;
+    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`);
-    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);
+    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;
         }
-        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);
+    }
+    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);
+    }
+    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 {
-        prompts.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 = [

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);

package/dist/project-dependency.js

@@ -1,7 +1,7 @@
 import { line } from "./style.js";
 import { spawn } from "node:child_process";
 import { existsSync, readFileSync } from "node:fs";
-import { relative, resolve } from "node:path";
+import { isAbsolute, relative, resolve } from "node:path";
 /** Returns the package-manager command that runs one project script. */
 export function projectScript(directory, declared, script) {
     return `${projectPackageManager(directory, declared).name} run ${script}`;
@@ -9,19 +9,20 @@ export function projectScript(directory, declared, script) {
 /**
  * Resolves an SDK through the one source policy shared by `init` and `create`.
  *
- * A CLI running from this repository uses its sibling dev-kit. A distributed
- * CLI has no such sibling and keeps the published range embedded in its
- * generated template.
+ * A Program inside this repository's workspace uses its sibling dev-kit. A
+ * standalone project or distributed CLI keeps the published range embedded
+ * in the generated template. Local packages therefore never leak their own
+ * workspace-only development graph into an unrelated project.
  */
 export function projectDependency(name, range, directory) {
-    const workspace = manifestAt(resolve(import.meta.dirname, "..", "..", ".."));
+    const workspaceDirectory = resolve(import.meta.dirname, "..", "..", "..");
+    const workspace = manifestAt(workspaceDirectory);
     const sourceDirectory = resolve(import.meta.dirname, "..", "..", localDirectories[name]);
     const manifest = manifestAt(sourceDirectory);
-    if (workspace?.name === "@phreshos/workspace" && manifest?.name === name && manifest.version && accepts(range, manifest.version)) {
-        const local = relative(directory, sourceDirectory).replaceAll("\\", "/") || ".";
+    if (workspace?.name === "@phreshos/workspace" && workspaceIncludes(workspaceDirectory, directory, workspace.workspaces) && manifest?.name === name && manifest.version && accepts(range, manifest.version)) {
         return {
-            installSpecifier: sourceDirectory,
-            manifestSpecifier: `file:${local}`,
+            installSpecifier: `${name}@workspace:*`,
+            manifestSpecifier: "workspace:*",
             local: true
         };
     }
@@ -37,10 +38,10 @@ export function projectPackageManager(directory, declared, preferred) {
     return managers[named ?? "npm"];
 }
 /** Installs the dependencies already declared by a generated project. */
-export async function installProjectDependencies(directory, preferred) {
+export async function installProjectDependencies(directory, preferred, output = "inherit") {
     const manifest = manifestAt(directory);
     const manager = projectPackageManager(directory, manifest?.packageManager, preferred);
-    await run(manager.name, manager.installArgs, directory);
+    await run(manager.name, manager.installArgs, directory, output);
     return manager.name;
 }
 /**
@@ -61,19 +62,24 @@ export default async function ensureProjectDependency(name, range, directory = p
     await run(manager.name, [...manager.addArgs(section), source.installSpecifier], directory);
     console.log("");
 }
-function run(command, args, directory) {
+function run(command, args, directory, output = "inherit") {
     return new Promise(function (settle, refuse) {
+        let diagnostic = "";
         const child = spawn(command, args, {
             cwd: directory,
-            stdio: "inherit",
+            stdio: output === "capture" ? ["ignore", "pipe", "pipe"] : "inherit",
             shell: process.platform === "win32"
         });
+        if (output === "capture") {
+            child.stdout?.on("data", chunk => { diagnostic += String(chunk); });
+            child.stderr?.on("data", chunk => { diagnostic += String(chunk); });
+        }
         child.once("error", error => refuse(new Error(`Could not run ${command}: ${error.message}`)));
         child.once("exit", function (code, signal) {
             if (signal)
                 refuse(new Error(`${command} ended on ${signal}`));
             else if (code !== 0)
-                refuse(new Error(`${command} exited with ${code ?? 0}`));
+                refuse(new Error(`${command} exited with ${code ?? 0}${diagnostic.trim() ? `\n\n${diagnostic.trim()}` : ""}`));
             else
                 settle();
         });
@@ -82,6 +88,18 @@ function run(command, args, directory) {
 function accepts(range, version) {
     return range === "workspace:*" || range === version || range === `^${version}` || range === `~${version}`;
 }
+function workspaceIncludes(root, directory, patterns) {
+    const local = relative(root, resolve(directory)).replaceAll("\\", "/");
+    if (!local || local === ".." || local.startsWith("../") || isAbsolute(local))
+        return false;
+    return patterns?.some(function (pattern) {
+        if (!pattern.endsWith("/*"))
+            return local === pattern;
+        const prefix = pattern.slice(0, -1);
+        const child = local.startsWith(prefix) ? local.slice(prefix.length) : "";
+        return Boolean(child) && !child.includes("/");
+    }) ?? false;
+}
 function manifestAt(directory) {
     const path = resolve(directory, "package.json");
     if (!existsSync(path))