@phreshos/cli 0.1.12 → 0.1.13

package/README.md

@@ -57,20 +57,22 @@ native per-user service. The selected release and the service entry therefore
 cannot become two competing sources of truth if installation is interrupted.
 It never reads a source checkout and never requires Bun or TypeScript.
 
-The System runs under `launchd` on macOS and a real `systemd --user` manager on
-Linux. In Linux containers with no init manager, it runs as a detached
-user-owned background process that survives the terminal but ends with the
-container. Automatic startup is unavailable there rather than being reported
-as enabled. `start` and `stop` change current execution only; where a native
-manager exists, `enable` and `disable` change automatic startup only. Successful
-installation and startup show the desktop address. `status` reports that same
-address with the installed version, service readiness, and automatic startup
-without changing them; `version` reports only the installed System release.
+The System runs under `launchd` on macOS, a real `systemd --user` manager on
+Linux, and a least-privilege per-user scheduled task on Windows. In Linux
+containers with no init manager, it runs as a detached user-owned background
+process that survives the terminal but ends with the container. Automatic
+startup is unavailable there rather than being reported as enabled. `start`
+and `stop` change current execution only; where a native manager exists,
+`enable` and `disable` change automatic startup only. Successful installation
+and startup show the desktop address. `status` reports that same address with
+the installed version, service readiness, and automatic startup without
+changing them; `version` reports only the installed System release.
 
 Installation files and persistent System state have separate homes. Removing
 the System unregisters its service and removes its release files while keeping
-`~/.phreshos`, including Programs and owner data. Windows remains unsupported
-until the System has an equally strong local-intake authorization model there.
+`~/.phreshos`, including Programs and owner data. Local Program intake uses an
+owner-only socket file on POSIX and an owner-created duplex named pipe on
+Windows; neither becomes a network endpoint or introduces a bearer secret.
 
 ## create
 

package/dist/intake-address.js

@@ -0,0 +1,14 @@
+import { createHash } from "node:crypto";
+import { join } from "node:path";
+/** Address the same owner-local intake without turning it into a network port. */
+export default function intakeAddress(storage, platform = process.platform) {
+    if (platform !== "win32")
+        return join(storage, "intake.sock");
+    // Windows pipe names share one machine-wide namespace. The storage root
+    // separates users and isolated instances while case folding follows the
+    // filesystem they came from. Access remains the pipe creator's default
+    // duplex ACL; the name is identity, not a secret or an authorization.
+    const owner = storage.replaceAll("\\", "/").replace(/\/+$/, "").toLowerCase();
+    const identity = createHash("sha256").update(owner).digest("hex").slice(0, 32);
+    return `\\\\.\\pipe\\phreshos-${identity}-intake`;
+}

package/dist/program-intake.js

@@ -1,14 +1,15 @@
 import { connect } from "node:net";
 import { homedir } from "node:os";
 import { isAbsolute, join } from "node:path";
+import intakeAddress from "./intake-address.js";
 /**
  * The local Program intake, from the CLI's side.
  *
- * A socket file rather than a port, because the file's permissions are
- * the authorization: only the account that owns this machine can open
- * it, and that account is exactly who may run and install programs on
- * it. Nothing is sent to prove anything, because being able to connect
- * is the proof.
+ * An owner-local IPC address rather than a port: a mode-0600 socket file
+ * on POSIX and an owner-created duplex named pipe on Windows. Only the
+ * account that owns this machine can complete the channel, and that account
+ * is exactly who may run and install programs on it. Nothing is sent to
+ * prove anything, because being able to connect is the proof.
  *
  * A message is a line. Closing our own side to mark the end of a
  * question would make lifetime ambiguous. A line delimiter keeps the
@@ -23,10 +24,10 @@ import { isAbsolute, join } from "node:path";
 export function programIntakePath(environment = process.env, userHome = homedir()) {
     const instanceHome = environment.PHRESHOS_HOME;
     if (instanceHome === undefined)
-        return join(userHome, ".phreshos", "intake.sock");
+        return intakeAddress(join(userHome, ".phreshos"));
     if (!isAbsolute(instanceHome))
         throw new Error("PHRESHOS_HOME must be an absolute filesystem path");
-    return join(instanceHome, "intake.sock");
+    return intakeAddress(instanceHome);
 }
 export const socketPath = programIntakePath();
 export default function speak(question, heard, path = socketPath, signal) {

package/dist/system/installation.js

@@ -3,6 +3,7 @@ import { existsSync, mkdirSync, writeFileSync } from "node:fs";
 import { mkdir, mkdtemp, open, readFile, readdir, readlink, rename, rm, symlink, writeFile } from "node:fs/promises";
 import { dirname, isAbsolute, join, relative, resolve } from "node:path";
 import { requireSuccess } from "./process.js";
+import npmInvocation from "./npm.js";
 import { minimumSystemNodeVersion } from "./node.js";
 import AdmZip from "adm-zip";
 /** Owns immutable release directories and the one atomic active record. */
@@ -207,8 +208,8 @@ function requireDirectory(path) {
     mkdirSync(path, { recursive: true, mode: 0o700 });
 }
 async function installProductionDependencies(directory) {
-    const npm = process.platform === "win32" ? "npm.cmd" : "npm";
-    await requireSuccess(npm, ["install", "--omit=dev", "--no-audit", "--no-fund", "--package-lock=false"], { cwd: directory });
+    const npm = npmInvocation(["install", "--omit=dev", "--no-audit", "--no-fund", "--package-lock=false"]);
+    await requireSuccess(npm.command, npm.args, { cwd: directory });
 }
 function releaseRecord(value) {
     return record(value)

package/dist/system/npm.js

@@ -0,0 +1,8 @@
+import { win32 } from "node:path";
+/** Invoke npm without asking a platform command shell to interpret its shim. */
+export default function npmInvocation(args, platform = process.platform, executable = process.execPath) {
+    if (platform !== "win32")
+        return { command: "npm", args };
+    const npm = win32.join(win32.dirname(executable), "node_modules", "npm", "bin", "npm-cli.js");
+    return { command: executable, args: [npm, ...args] };
+}

package/dist/system/paths.js

@@ -1,3 +1,4 @@
+import intakeAddress from "../intake-address.js";
 import { homedir } from "node:os";
 import { isAbsolute, join } from "node:path";
 /** The installation is separate from the persistent state it operates on. */
@@ -15,7 +16,7 @@ export default function systemPaths(platform = process.platform, userHome = home
         releases: join(root, "releases"),
         current: join(root, "current"),
         storage,
-        intake: join(storage, "intake.sock"),
+        intake: intakeAddress(storage, platform),
         log: join(storage, "service.log")
     };
 }

package/dist/system/service/index.js

@@ -1,11 +1,14 @@
 import { homedir } from "node:os";
 import LinuxSystemService from "./linux.js";
 import MacOSSystemService from "./macos.js";
+import WindowsSystemService from "./windows.js";
 /** Select the per-user service implementation available in this environment. */
 export default function systemService(platform = process.platform, userHome = homedir()) {
     if (platform === "darwin")
         return new MacOSSystemService(userHome);
     if (platform === "linux")
         return new LinuxSystemService(userHome);
+    if (platform === "win32")
+        return new WindowsSystemService(userHome);
     throw new Error(`PhreshOS System services are not supported on ${platform}`);
 }

package/dist/system/service/macos.js

@@ -11,10 +11,9 @@ export default class MacOSSystemService {
     plist;
     domain;
     target;
-    constructor(userHome, run = execute, label = defaultLabel) {
+    constructor(userHome, run = execute, label = defaultLabel, uid = process.getuid?.()) {
         this.run = run;
         this.label = label;
-        const uid = process.getuid?.();
         if (uid === undefined)
             throw new Error("The current macOS user could not be identified");
         this.plist = join(userHome, "Library", "LaunchAgents", `${this.label}.plist`);

package/dist/system/service/windows-runner.js

@@ -0,0 +1,45 @@
+import { spawn } from "node:child_process";
+import { open, writeFile } from "node:fs/promises";
+const payload = decode(process.argv[2]);
+const output = await open(payload.definition.output, "a", 0o600);
+try {
+    const child = spawn(payload.definition.executable, [payload.definition.entry], {
+        cwd: payload.definition.directory,
+        stdio: ["ignore", output.fd, output.fd]
+    });
+    await new Promise(function (settle, refuse) {
+        child.once("spawn", settle);
+        child.once("error", refuse);
+    });
+    if (child.pid === undefined)
+        throw new Error("The PhreshOS System process has no pid");
+    await writeFile(payload.state, JSON.stringify({ runner: process.pid, child: child.pid }), { mode: 0o600 });
+    const result = await new Promise(settle => {
+        child.once("close", (code, signal) => settle({ code, signal }));
+    });
+    process.exitCode = result.signal ? 1 : result.code ?? 1;
+}
+finally {
+    await output.close();
+}
+function decode(encoded) {
+    let value;
+    try {
+        value = JSON.parse(Buffer.from(encoded ?? "", "base64url").toString("utf8"));
+    }
+    catch {
+        throw new Error("The PhreshOS System task payload is invalid");
+    }
+    if (!value || typeof value !== "object")
+        throw new Error("The PhreshOS System task payload is invalid");
+    const candidate = value;
+    if (typeof candidate.state !== "string" || !definition(candidate.definition))
+        throw new Error("The PhreshOS System task payload is invalid");
+    return { state: candidate.state, definition: candidate.definition };
+}
+function definition(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const candidate = value;
+    return ["executable", "entry", "directory", "output"].every(name => typeof candidate[name] === "string" && candidate[name] !== "");
+}

package/dist/system/service/windows.js

@@ -0,0 +1,238 @@
+import { execute } from "../process.js";
+import { randomUUID } from "node:crypto";
+import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+const scheduler = "schtasks.exe";
+const powershell = "powershell.exe";
+const defaultTask = "PhreshOS System";
+const runner = fileURLToPath(new URL("./windows-runner.js", import.meta.url));
+/** A per-user Windows Task Scheduler service requiring no administrator rights. */
+export default class WindowsSystemService {
+    userHome;
+    run;
+    task;
+    constructor(userHome, run = execute, task = defaultTask) {
+        this.userHome = userHome;
+        this.run = run;
+        this.task = task;
+        this.state = join(userHome, ".phreshos", "system-service.json");
+    }
+    state;
+    async inspect() {
+        const result = await this.run(powershell, powershellArguments(inspectScript(this.task)));
+        if (result.code === 3)
+            return absent();
+        if (result.code !== 0)
+            throw failure(powershell, result);
+        const match = /^([0-4]),([01])$/.exec(result.stdout.trim());
+        if (!match)
+            throw new Error("The PhreshOS System scheduled task returned an invalid state");
+        const pid = match[1] === "4" ? (await this.readState())?.child : undefined;
+        return {
+            registered: true,
+            automaticStartup: true,
+            enabled: match[2] === "1",
+            running: match[1] === "4",
+            ...(pid && alive(pid) ? { pid } : {})
+        };
+    }
+    async register(definition) {
+        await this.stop();
+        await mkdir(dirname(definition.output), { recursive: true });
+        await mkdir(dirname(this.state), { recursive: true });
+        await rm(this.state, { force: true });
+        const sid = await this.userSid();
+        const temporary = join(this.userHome, `.phreshos-system-${randomUUID()}.xml`);
+        try {
+            await writeFile(temporary, utf16(task(this.task, sid, definition, this.state)));
+            await this.require(scheduler, ["/Create", "/TN", this.task, "/XML", temporary, "/F"]);
+        }
+        finally {
+            await rm(temporary, { force: true });
+        }
+    }
+    async unregister() {
+        const state = await this.inspect();
+        if (!state.registered) {
+            await rm(this.state, { force: true });
+            return;
+        }
+        if (state.running)
+            await this.stop();
+        await this.require(scheduler, ["/Delete", "/TN", this.task, "/F"]);
+        await rm(this.state, { force: true });
+    }
+    async start() {
+        const state = await this.inspect();
+        if (!state.registered)
+            throw new Error("The PhreshOS System service is not registered");
+        if (state.running)
+            return;
+        // Task Scheduler refuses an explicit run while a task is disabled.
+        // Enablement names future logons, not current execution, so borrow it
+        // only for the launch and restore the persisted choice immediately.
+        if (!state.enabled)
+            await this.change("/Enable");
+        try {
+            await this.require(scheduler, ["/Run", "/TN", this.task]);
+        }
+        finally {
+            if (!state.enabled)
+                await this.change("/Disable");
+        }
+    }
+    async stop() {
+        const state = await this.inspect();
+        if (!state.registered || !state.running)
+            return;
+        await this.require(scheduler, ["/End", "/TN", this.task]);
+        const until = Date.now() + 5_000;
+        while (Date.now() < until) {
+            const processes = await this.readState();
+            if (!(await this.inspect()).running && !running(processes))
+                break;
+            await new Promise(settle => setTimeout(settle, 50));
+        }
+        const processes = await this.readState();
+        if (running(processes)) {
+            if (processes?.child && alive(processes.child))
+                process.kill(processes.child);
+            await settle(processes?.child);
+            if (processes?.runner && alive(processes.runner))
+                process.kill(processes.runner);
+            await settle(processes?.runner);
+        }
+        if ((await this.inspect()).running || running(await this.readState()))
+            throw new Error("The PhreshOS System scheduled task did not stop");
+        await rm(this.state, { force: true });
+    }
+    async enable() {
+        await this.requireRegistered();
+        await this.change("/Enable");
+    }
+    async disable() {
+        await this.requireRegistered();
+        await this.change("/Disable");
+    }
+    async userSid() {
+        const result = await this.run(powershell, powershellArguments("[Console]::Out.Write([Security.Principal.WindowsIdentity]::GetCurrent().User.Value)"));
+        if (result.code !== 0)
+            throw failure(powershell, result);
+        const sid = result.stdout.trim();
+        if (!/^S-[0-9]+(?:-[0-9]+)+$/.test(sid))
+            throw new Error("The current Windows user could not be identified");
+        return sid;
+    }
+    async readState() {
+        try {
+            const value = JSON.parse(await readFile(this.state, "utf8"));
+            if (integer(value.runner) && integer(value.child))
+                return { runner: value.runner, child: value.child };
+        }
+        catch { }
+        return undefined;
+    }
+    async requireRegistered() {
+        if (!(await this.inspect()).registered)
+            throw new Error("The PhreshOS System service is not registered");
+    }
+    async change(action) {
+        await this.require(scheduler, ["/Change", "/TN", this.task, action]);
+    }
+    async require(command, args) {
+        const result = await this.run(command, args);
+        if (result.code !== 0)
+            throw failure(command, result);
+    }
+}
+function absent() {
+    return { registered: false, automaticStartup: true, enabled: false, running: false };
+}
+function inspectScript(name) {
+    const selected = quotePowerShell(name);
+    return `$task = Get-ScheduledTask -TaskName ${selected} -TaskPath '\\' -ErrorAction SilentlyContinue; if ($null -eq $task) { exit 3 }; [Console]::Out.Write(("{0},{1}" -f [int]$task.State, [int]$task.Settings.Enabled))`;
+}
+function task(name, sid, definition, state) {
+    const payload = Buffer.from(JSON.stringify({ definition, state })).toString("base64url");
+    const argumentsValue = `"${runner}" ${payload}`;
+    return `<?xml version="1.0" encoding="UTF-16"?>
+<Task version="1.4" xmlns="http://schemas.microsoft.com/windows/2004/02/mit/task">
+  <RegistrationInfo>
+    <Description>PhreshOS System</Description>
+    <URI>\\${xml(name)}</URI>
+  </RegistrationInfo>
+  <Triggers>
+    <LogonTrigger>
+      <Enabled>true</Enabled>
+      <UserId>${xml(sid)}</UserId>
+    </LogonTrigger>
+  </Triggers>
+  <Principals>
+    <Principal id="User">
+      <UserId>${xml(sid)}</UserId>
+      <LogonType>InteractiveToken</LogonType>
+      <RunLevel>LeastPrivilege</RunLevel>
+    </Principal>
+  </Principals>
+  <Settings>
+    <MultipleInstancesPolicy>IgnoreNew</MultipleInstancesPolicy>
+    <DisallowStartIfOnBatteries>false</DisallowStartIfOnBatteries>
+    <StopIfGoingOnBatteries>false</StopIfGoingOnBatteries>
+    <AllowHardTerminate>true</AllowHardTerminate>
+    <StartWhenAvailable>true</StartWhenAvailable>
+    <AllowStartOnDemand>true</AllowStartOnDemand>
+    <Enabled>true</Enabled>
+    <ExecutionTimeLimit>PT0S</ExecutionTimeLimit>
+    <RestartOnFailure>
+      <Interval>PT1M</Interval>
+      <Count>999</Count>
+    </RestartOnFailure>
+  </Settings>
+  <Actions Context="User">
+    <Exec>
+      <Command>${xml(definition.executable)}</Command>
+      <Arguments>${xml(argumentsValue)}</Arguments>
+      <WorkingDirectory>${xml(definition.directory)}</WorkingDirectory>
+    </Exec>
+  </Actions>
+</Task>
+`;
+}
+function powershellArguments(script) {
+    return ["-NoLogo", "-NoProfile", "-NonInteractive", "-ExecutionPolicy", "Bypass", "-Command", script];
+}
+function quotePowerShell(value) {
+    return `'${value.replaceAll("'", "''")}'`;
+}
+function xml(value) {
+    return value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll('"', "&quot;").replaceAll("'", "&apos;");
+}
+function utf16(value) {
+    return Buffer.concat([Buffer.from([0xff, 0xfe]), Buffer.from(value, "utf16le")]);
+}
+function failure(command, result) {
+    return new Error(result.stderr.trim() || result.stdout.trim() || `${command} exited with code ${result.code}`);
+}
+function integer(value) {
+    return typeof value === "number" && Number.isSafeInteger(value) && value > 0;
+}
+function alive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function running(value) {
+    return Boolean(value && (alive(value.runner) || alive(value.child)));
+}
+async function settle(pid) {
+    if (!pid)
+        return;
+    const until = Date.now() + 1_000;
+    while (Date.now() < until && alive(pid))
+        await new Promise(resolve => setTimeout(resolve, 25));
+}

package/dist/template/package.json

@@ -16,7 +16,7 @@
         "react-dom": "^19.2.8"
     },
     "devDependencies": {
-        "@phreshos/cli": "^0.1.12",
+        "@phreshos/cli": "^0.1.13",
         "@types/node": "^26.2.0",
         "@types/react": "^19.2.18",
         "@types/react-dom": "^19.2.4",

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@phreshos/cli",
     "type": "module",
-  "version": "0.1.12",
+  "version": "0.1.13",
     "description": "The Phresh command-line interface for Program projects and system management.",
     "engines": {
         "node": ">=20.10"
@@ -15,6 +15,7 @@
         "verify:system-release": "node --run compile && node scripts/verify-system-release.mjs",
         "verify:linux-service": "node --run compile && node scripts/verify-linux-service.mjs",
         "verify:macos-service": "node --run compile && node scripts/verify-macos-service.mjs",
+        "verify:windows-service": "node --run compile && node scripts/verify-windows-service.mjs",
         "prepack": "node --run build"
     },
     "bin": {