@kubilaycakmak/projectfreeze 0.0.0-stage → 0.1.0-dev.5

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kubilay Cakmak
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,51 @@
-# Temporary Holding Version
+# ProjectFreeze
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+ProjectFreeze is a free, open-source tool for discovering and managing developer workloads on your computer. Open the terminal interface with `projectfreeze`, use versioned JSON from scripts, or connect an MCP client over stdio. The daemon runs under your account and keeps ownership and operation history in a private SQLite database.
+
+## Quick start
+
+```sh
+npx @kubilaycakmak/projectfreeze@next
+```
+
+Run this in an interactive terminal to download and open the current npm prerelease. Confirm the npm installation prompt if it appears. If PowerShell blocks the `npx.ps1` shim, run `npx.cmd @kubilaycakmak/projectfreeze@next`.
+
+Freeze, Sleep, and Force Terminate can interrupt running work. Save your work and review the selected processes before using these controls. See [License and liability](#license-and-liability).
+
+## Requirements
+
+Use Node.js 24.11.0 or later in the 24.x series, or Node.js 26.x, with `npm` and `npx` on your `PATH`. The npm package includes native helpers for the platforms below. The core CLI runs under your user account without a compiler, administrator or root access, or Docker.
+
+| Platform | Tested operating systems and architectures |
+| --- | --- |
+| Windows | Windows 11 (x64 and ARM64) and Windows Server 2025 (x64) |
+| macOS | macOS 15 (Intel x64 and Apple silicon ARM64) |
+| Linux | Ubuntu 24.04 (x64 and ARM64). The native helper uses glibc and requires a mounted `/proc` filesystem. |
+
+Node.js 24 verification covered Windows 11 ARM64, Windows Server 2025, macOS, and Linux. Node.js 26 was tested on Windows and Linux x64, including a manual Windows 11 test. Optional integrations have their own prerequisites, including Docker for Compose and Docker checkpoints, CRIU for native Linux checkpoints, and a user systemd manager for Linux service control. See the [operations guide](docs/operations.md) and [integration requirements](docs/interfaces.md#recipes).
+
+## Using the menu
+
+Use the arrow keys to select a project, Enter to inspect it, and Tab to switch views. Use `/` to search, `f` to Freeze, `z` for Sleep, `w` for Wake, and `q` to disconnect. Press `?` for the full key reference. ProjectFreeze asks you to review candidate processes before adoption.
+
+Append `menu --plain` to the quick-start command for a line-driven fallback. To run individual commands, pass them after the package name.
+
+```sh
+npx @kubilaycakmak/projectfreeze@next discover --json
+npx @kubilaycakmak/projectfreeze@next listeners
+npx @kubilaycakmak/projectfreeze@next inspect PROJECT
+npx @kubilaycakmak/projectfreeze@next freeze PROJECT
+npx @kubilaycakmak/projectfreeze@next resume PROJECT
+```
+
+Freeze preserves process memory and usually retains bound ports. Sleep shuts down approved resources and requires a durable restart recipe. Wake starts a fresh workload and waits for configured readiness. Checkpoint and restore depend on the eligible local backend and capture scope.
+
+The development build adds Ports and Services views and a two-step `k` force-termination command for one owned native project. Build the local helper with `npm run build:native` and open the development menu with `node bin/projectfreeze.js`. Set `PROJECTFREEZE_HOME` to a separate absolute directory to test alongside an installed copy.
+
+- [Commands, recipes, and MCP](docs/interfaces.md)
+- [Architecture, security, and recovery](docs/operations.md)
+- [Development, verification, and packaging](CONTRIBUTING.md)
+
+## License and liability
+
+ProjectFreeze is provided “as is” under the MIT License, without warranties. Use it at your own risk. The authors and copyright holders disclaim liability for claims, damages, or other losses arising from the software or its use to the extent permitted by applicable law. See the [MIT License](LICENSE) for the full terms.

package/bin/projectfreeze.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { main } from '../src/cli.js';
+
+await main(process.argv.slice(2));

package/docs/interfaces.md

@@ -0,0 +1,98 @@
+# Commands, recipes, and MCP
+
+With no arguments, a terminal session opens the interactive interface. A redirected session produces a project listing. `--json` uses a single object with `schemaVersion: 1`, `ok`, and either `data` or `error`. A failed operation can carry its durable journal as `data` with `ok: false`.
+
+| Command | Behavior |
+| --- | --- |
+| `list`, `discover`, `inspect PROJECT` | Report registered projects, candidate projects, and scoped observations. |
+| `menu`, `menu --plain` | Open the live keyboard interface or its line-driven fallback. |
+| `--version` | Print the installed package version. The live menu shows the same version in its header. |
+| `listeners` | List TCP endpoints and PIDs for locally observable processes. Unassigned entries are read-only. |
+| `ports` | List local TCP listeners and bound UDP sockets. Reports a PID when ownership is available. |
+| `services` | List running services visible to the local Windows SCM, systemd system and user managers, or the current macOS launchd domain. |
+| `adopt [PROJECT] --cwd DIR --member PID@BIRTH@BOOT --confirm` | Approve exact identities from current discovery. An optional registered project ID sets the destination. Repeat `--member` and `--exclude` as needed. `--recipe FILE` supplies restart settings. |
+| `run --cwd DIR -- EXECUTABLE ARG...` | Launch literal arguments. Use a fully qualified executable or an absolute PATH entry. |
+| `run --recipe FILE` | Launch a reviewed JSON recipe. |
+| `freeze PROJECT...`, `resume PROJECT...` | Suspend owned execution or release recorded suspensions. |
+| `sleep PROJECT...`, `wake PROJECT...` | Stop reviewed resources or start from a durable recipe. |
+| `checkpoint PROJECT --backend criu\|docker` | Capture supported local state. |
+| `restore PROJECT --checkpoint ID` | Restore a verified capture while the workload is stopped. |
+| `reconcile [PROJECT...]` | Compare stored state against current resources. |
+| `history`, `operation ID`, `cancel ID` | Read operations and request cancellation. |
+| `daemon start\|status\|stop\|foreground` | Control daemon lifecycle. |
+| `mcp` | Run the local MCP stdio server. |
+
+Mutating commands wait for an operation result unless `--detach` is given. The operation has a UUID, action, project list, status, UTC timestamps, pending step, and per-resource outcomes. Closing the terminal or interrupting the CLI disconnects the client. `cancel ID` requests cancellation before the next resource boundary. Completed effects and in-flight native calls can survive cancellation.
+
+The live menu rescans on entry and periodically. Tab or Left/Right switches between Projects, Ports, Services, and History. Arrow keys and Page Up/Down move the selection or scroll details. Enter opens the selection or confirms a preview. Escape goes back or cancels. Search with `/` and use Space to select multiple projects. Ports and Services are read-only views. Ports reads local OS tables without probing the network. Linux Ports shows the current network namespace. Socket ownership or service manager access can depend on the current account. Discovered processes need explicit ownership review before control.
+
+Press `?` to open the grouped shortcut reference. In a narrow terminal, scroll with the arrow keys or Page Up/Down. Home and End jump to the top and bottom. Press `?` again or Esc to return to the current view. When the CLI entry point is observable, Projects omits ProjectFreeze CLI processes from other installations. Their listening sockets remain visible in Ports.
+
+Project details show the ownership confidence, declared dependencies, registered services and sharing policies, and recent incomplete operations. Press Space in project details to collapse or expand the process tree. From the project list, Space toggles selection instead.
+
+Select one owned native project and press `k` to review force termination. The preview lists the exact process IDs. Press Enter to continue, then type `KILL` and press Enter again to authorize SIGKILL on Linux and macOS or TerminateProcess on Windows. Esc cancels either prompt. Force termination skips graceful shutdown and suppresses automatic restart. Use `w` to start again when a restart recipe is available. ProjectFreeze rejects a changed process set and directs projects with registered services or active dependents to their service shutdown workflow.
+
+## Test Sleep and Wake
+
+Use the included `examples/stream-test.mjs` to create a launch recipe and see the process identity at the client. From a dedicated test directory, run `node /path/to/stream-test.mjs --recipe stream.recipe.json 8788`. Press `l`, enter the recipe path, and confirm with Enter. In another terminal run `curl -N http://127.0.0.1:8788/stream` (`curl.exe` on Windows). Select the project, press `z`, and confirm. The stream ends and the listener disappears. Press `w`, confirm, and reconnect with curl to see the new PID. The fixture includes a graceful shutdown command. Choose an unused port if `8788` is occupied.
+
+Run `node examples/demo.js` from the package directory for an isolated loopback demonstration of discovery, adoption, freeze, resume, sleep, and wake. On a Linux host where CRIU works with the current user's permissions, run `node examples/demo.js --checkpoint` to capture a disposable workload, stop it, and restore it. Both demos use temporary state and clean up their own workloads.
+
+| Exit code | Meaning |
+| --- | --- |
+| 0 | Successful command or accepted detached operation |
+| 1 | Internal failure |
+| 2 | Invalid input |
+| 3 | Resource or identity missing |
+| 4 | Permission or policy denied |
+| 5 | Capability unavailable on this host or capture scope |
+| 6 | Operation conflict |
+| 7 | Partial or interrupted operation |
+| 8 | Cancelled |
+| 9 | Prerequisite or daemon unavailable |
+
+## Recipes
+
+```json
+{
+  "cwd": "/absolute/project/path",
+  "instance": "web",
+  "argv": ["node", "server.js"],
+  "env": ["APP_DATABASE_URL"],
+  "dependencies": [],
+  "ready": { "address": "127.0.0.1", "port": 8080 },
+  "stop": ["node", "shutdown.js"],
+  "timeout": 10000,
+  "restart": "never"
+}
+```
+
+`argv` and `stop` are literal argument arrays. For shell scripts select the shell explicitly and supply its arguments. Windows recipes can call `cmd.exe` or `powershell.exe` explicitly to interpret shell commands. Keep secret values out of literal arguments and recipe files. `env` names refer to values in the daemon environment at launch. Start or restart the daemon from an environment containing the required values. The daemon passes a small platform environment and the listed references to workloads. Output streams of managed launches are discarded to keep secret-bearing logs out of state. Configure application logging at the workload boundary.
+
+Set `instance` to give a workload its own durable project ID inside a shared directory. For example, `web` and `worker` can use separate recipes in one checkout. Recipes without an instance keep the directory's original ID. To adopt into a named project for the first time, include its instance in the reviewed recipe. To add processes to an existing project, pass its ID to `adopt`, or open that project and press `a`. Approve only the identities that belong to that workload.
+
+`ready` connects to a loopback TCP port observed on an owned process. `stop` should implement application-specific graceful shutdown. Without `stop`, POSIX uses SIGTERM. Windows requires `stop` or specifically approved `--force` termination. `restart: "on-failure"` permits up to three retries while the launch supervisor remains available. Linux may specify `cgroup` as an existing delegated cgroup v2 parent directory. `containers` entries name a Compose `project`, `service`, and explicit `shared` boolean. Exclusive services must be existing containers with matching Compose labels and restart policy `no`.
+
+On Linux, set `systemd` to an array such as `[{"unit":"worker.service","shared":false},{"unit":"worker.timer","shared":false}]`. Link the reviewed unit files into your user manager with `systemctl --user link /absolute/project/worker.service /absolute/project/worker.timer`. Keep unit files within the project, restrict write access to their owner, set the service `WorkingDirectory` to the project, and configure `SendSIGKILL=no`. The adapter controls only the exact loaded units. It rejects drop-ins and activation or lifecycle dependencies outside the exclusive reviewed set. Active timers in that set are stopped before service suspension or shutdown and restarted after recovery.
+
+Use `supervisors` to associate existing platform resources with a project recipe. Set `shared` to `true` for observation-only resources. Cross-project references are also treated as shared.
+
+| Platform | Example entry | Verified scope |
+| --- | --- | --- |
+| macOS | `{"kind":"launchd","name":"com.example.worker","plist":"/absolute/project/worker.plist","shared":false}` | A loaded GUI user LaunchAgent with an owner-controlled project plist, matching executable and working directory, one observable process, and no automatic activation. |
+| Windows | `{"kind":"scm","name":"ExampleWorker","shared":false}` | An existing manual-start, own-process service with an executable in the project, no dependencies, dependents, triggers, or recovery actions, and a current-user or LocalService account. SCM decides which controls the service supports. |
+| Windows | `{"kind":"task","name":"\\ExampleTimer","shared":false}` | An existing low-privilege task for the current user with a single project executable and matching working directory. Running or queued tasks delay freeze and sleep. Only idle activation is disabled and restored. |
+
+Register and authorize platform resources through the operating system before giving ProjectFreeze their definitions. Worker output, arguments, and credentials remain in the owning supervisor. ProjectFreeze pins reviewed definitions and rejects changed fingerprints. PowerShell on Windows executes the installed adapter with the existing execution policy.
+
+## MCP
+
+```json
+{
+  "mcpServers": {
+    "projectfreeze": { "command": "projectfreeze", "args": ["mcp"] }
+  }
+}
+```
+
+The stdio server implements initialization, `tools/list`, `tools/call`, cancellation, and progress notifications for operations requested with a progress token. Tool schemas are returned by `tools/list`. The `ports` and `services` tools expose the same read-only inventory as their CLI commands. Tool output uses the CLI data shapes and the same daemon ownership checks. The MCP host grants local permissions to its process and must use its approval UI when requesting ambiguous adoption, launching code, or forcing shutdown. See the [MCP stdio transport specification](https://modelcontextprotocol.io/specification/2025-11-25/basic/transports).

package/docs/operations.md

@@ -0,0 +1,42 @@
+# Architecture, security, and recovery
+
+```mermaid
+flowchart LR
+  TUI[Terminal UI] --> IPC[Authenticated local IPC]
+  CLI[CLI and JSON] --> IPC
+  MCP[MCP stdio] --> IPC
+  IPC --> Engine[Operation engine]
+  Engine <--> State[(Private SQLite state)]
+  Engine --> Native[Native process helper]
+  Engine --> Docker[Local Docker engine]
+  Engine --> CRIU[Linux CRIU]
+```
+
+The daemon serializes mutations and journals pending effects and outcomes. POSIX uses a socket in a user-owned 0700 directory or loopback when the state path exceeds the socket system limit. Windows uses loopback and an endpoint file in a directory with a restricted user and SYSTEM ACL. Both transports authenticate each connection and its request and response using fresh nonces and HMAC. There is no HTTP management surface. Same-account programs that can read state are inside the trust boundary. The daemon performs no elevation, firewall edits, service installation, or workload downloads. A user-approved command executes with that user's permissions.
+
+## Scope and metrics
+
+Candidates combine process metadata, manifest paths, executable metadata, ancestry, and TCP listeners where observable. They are observations. Adoption records exact process identities after review. Native launches use a staged handshake to record identity before allowing application execution. Linux opens PID file descriptors for process control. macOS rechecks the process creation identity and uses a task audit token. Windows checks a process handle and creation time and groups managed descendants in a Job Object. Read the primary references for [Linux pidfds](https://man7.org/linux/man-pages/man2/pidfd_send_signal.2.html), [cgroup v2](https://docs.kernel.org/admin-guide/cgroup-v2.html), [macOS process interfaces](https://github.com/apple-oss-distributions/xnu/blob/main/bsd/sys/proc_info.h), and [Windows Job Objects](https://learn.microsoft.com/en-us/windows/win32/procthread/job-objects).
+
+CPU is sampled as percent of one logical core. Resident-memory figures sum observed process RSS and can count shared pages more than once. A project dependency is listed by reference. Compose services referenced by multiple projects are treated as shared. Listening port results describe the authorized TCP scan. An absent result can also indicate an out-of-scope listener.
+
+One canonical directory can hold several durable projects with named recipe instances. Discovery groups unclaimed processes by directory and requires individual review before assigning them to a project. Nearby monorepo manifests can produce separate discovery groups. Detached or reparented processes remain candidates when an executable, script path, or observable working directory still ties them to a project. They require individual review when they escape native containment. The current process scan provides no reliable historical command reconstruction. The systemd and native supervisor adapters coordinate only registered resources with verified definitions and permissions.
+
+## Recovering a workload
+
+1. Run `projectfreeze history` or `projectfreeze operation ID` to see the recorded intent and completed effects.
+2. Run `projectfreeze inspect PROJECT` and `projectfreeze reconcile PROJECT` to verify identities and current state.
+3. If a freeze completed partially, `projectfreeze resume PROJECT` releases recorded ProjectFreeze suspensions. A process that was already suspended is left for its original owner. After an interruption during an unrecorded effect, inspect the pending step before taking manual action.
+4. If shutdown was partial, inspect which resources remain and retry the reviewed action. Verify that any stopped dependency is safe to restart before wake. A successful wake checks TCP readiness when configured. Application-level recovery may also require credential, connection, timer, and pending I/O checks.
+
+Daemon restart preserves workloads and state. Native launch supervisors persist exit receipts independently of the daemon. The `on-failure` policy consumes a recorded nonzero exit on the same boot and stops after three restart attempts. A missing receipt or a changed boot identity requires review. A package upgrade should stop the daemon, install the verified package, and start it against the same state directory. Keep recoverable metadata and the old package until reconciliation succeeds. Windows launches use a hash-addressed helper copy inside private state so an active launch supervisor cannot lock the installed npm package during removal.
+
+When upgrading on Windows from `0.1.0-dev.0`, install the new tarball in a separate npm prefix while old workloads are alive. The old launcher can hold its installed executable open. Stop the old daemon, invoke the new installation with the same `PROJECTFREEZE_HOME`, and verify that `inspect` sees the original workload. Remove the old installation after its workloads exit and the launcher releases its executable.
+
+## Checkpoints
+
+If the daemon stops during restore, run `projectfreeze reconcile PROJECT`. It clears the interruption only when it can verify the journaled restored process or original running container, or after the host boot changes. If it cannot identify the outcome, the project stays partial and rejects lifecycle changes. Review the restore journal and backend logs before intervening at the OS level. A host restart clears the old-boot effect and allows a cold wake. Keep the checkpoint files for diagnosis.
+
+The native adapter invokes [Linux CRIU](https://github.com/checkpoint-restore/criu) with `check`, `dump`, and `restore`. Docker delegates to the local [Docker checkpoint CLI](https://docs.docker.com/reference/cli/docker/checkpoint/). Docker images stay under the original container's engine-managed checkpoint directory, which must be readable for integrity checks. The capture can contain process memory and secrets. The manifest records image hashes, backend version, scope, and host prerequisites. Restore requires the original project and a compatible backend and host. The current implementation restricts restore to the original boot. Successful capture depends on CRIU permissions, kernel support, capture scope, and backing files. A checkpoint does not roll back external side effects or guarantee surviving network sessions. Windows and macOS native operation use freeze/resume and sleep/wake. The candidate provides no VM snapshot integration.
+
+The Docker checkpoint adapter requires a workload already configured for host networking. Isolated network namespaces hit an [upstream restore failure](https://github.com/moby/moby/issues/50750) on the tested engine. Keep the existing isolation and use pause/unpause or stop/start for those containers. ProjectFreeze never changes a container's network mode.

package/examples/demo.js

@@ -0,0 +1,72 @@
+import { execFile, spawn } from 'node:child_process';
+import { createServer } from 'node:net';
+import { copyFile, mkdtemp, realpath, writeFile, unlink, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { promisify } from 'node:util';
+import { setTimeout as delay } from 'node:timers/promises';
+import { fileURLToPath } from 'node:url';
+
+const exec = promisify(execFile);
+const cli = fileURLToPath(new URL('../bin/projectfreeze.js', import.meta.url));
+const checkpoint = process.argv[2] === '--checkpoint';
+if (checkpoint && process.platform !== 'linux') throw new Error('The checkpoint demo requires Linux with a working CRIU installation.');
+const base = await realpath(await mkdtemp(join(tmpdir(), 'pf-demo-')));
+const worker = join(base, 'workload.mjs');
+const marker = join(base, 'stop');
+const port = await new Promise(resolve => {
+  const server = createServer();
+  server.listen(0, '127.0.0.1', () => { const port = server.address().port; server.close(() => resolve(port)); });
+});
+const env = { ...process.env, PROJECTFREEZE_HOME: join(base, 'state'), PF_DEMO_PORT: String(port), PF_DEMO_STOP_FILE: marker };
+const recipe = join(base, 'recipe.json');
+const start = [process.execPath, worker];
+const stop = [process.execPath, '-e', 'require("node:fs").writeFileSync(process.argv[1], "stop")', marker];
+const run = async (...args) => {
+  const result = await exec(process.execPath, [cli, '--json', ...args], { env, windowsHide: true }).catch(error => error);
+  const reply = JSON.parse(result.stdout);
+  if (!reply.ok) throw new Error(JSON.stringify(reply.error ?? reply.data));
+  return reply.data;
+};
+let id, external;
+try {
+  if (checkpoint) {
+    ({ projects: [id] } = await run('run', '--cwd', base, '--', '/usr/bin/sleep', '120'));
+    const capture = await run('checkpoint', id);
+    const image = capture.outcomes.find(row => row.status === 'captured').target;
+    console.log(`Checkpoint ${image}`);
+    await run('sleep', id);
+    console.log(`Restore ${(await run('restore', id, '--checkpoint', image)).status}`);
+    console.log(`Restored ${(await run('inspect', id)).processCount} process(es)`);
+  } else {
+    await copyFile(new URL('./workload.js', import.meta.url), worker);
+    await writeFile(join(base, 'package.json'), '{}');
+    await writeFile(recipe, JSON.stringify({ cwd: base, instance: 'demo', argv: start, stop, env: ['PF_DEMO_PORT', 'PF_DEMO_STOP_FILE'],
+      ready: { address: '127.0.0.1', port } }));
+    external = spawn(start[0], start.slice(1), { cwd: base, env, windowsHide: true, stdio: 'ignore' });
+    const deadline = Date.now() + 10000;
+    while (!(await fetch(`http://127.0.0.1:${port}/health`, { signal: AbortSignal.timeout(300) }).then(reply => reply.ok, () => false))) {
+      if (Date.now() >= deadline || external.exitCode !== null) throw new Error('The demo listener did not start.');
+      await delay(150);
+    }
+    const discovered = (await run('discover')).find(project => project.cwd === base);
+    const member = discovered?.processes.find(row => row.pid === external.pid);
+    if (!member) throw new Error('The independently launched demo process was not discovered.');
+    console.log(`Discovered PID ${member.pid} on 127.0.0.1:${port}`);
+    ({ projects: [id] } = await run('adopt', '--cwd', base, '--member', `${member.pid}@${member.birth}@${member.boot}`, '--confirm', '--recipe', recipe));
+    console.log(`Adopted ${id} ${JSON.stringify((await run('inspect', id)).ports)}`);
+    for (const command of ['freeze', 'resume', 'sleep', 'wake', 'sleep']) {
+      if (command === 'wake') await unlink(marker);
+      console.log(`${command} ${(await run(command, id)).status}`);
+    }
+  }
+} finally {
+  if (id) {
+    await run('resume', id).catch(() => {});
+    await run('sleep', id).catch(() => {});
+  }
+  if (external?.exitCode === null) external.kill();
+  await run('daemon', 'stop').catch(() => {});
+  await delay(500);
+  await rm(base, { recursive: true, force: true, maxRetries: 5 });
+}

package/examples/stream-test.mjs

@@ -0,0 +1,71 @@
+import { createServer } from 'node:http';
+import { access, unlink, writeFile } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const host = '127.0.0.1';
+const [mode, path, recipePort] = process.argv.slice(2);
+if (mode === '--stop') {
+  await writeFile(path, '', { flag: 'wx' }).catch(error => { if (error.code !== 'EEXIST') throw error; });
+} else if (mode === '--recipe') {
+  const file = resolve(path);
+  const cwd = dirname(file);
+  const port = parsePort(recipePort ?? 8788, 1);
+  const script = fileURLToPath(import.meta.url);
+  const marker = join(cwd, `.stream-stop-${port}`);
+  const recipe = { cwd, argv: [process.execPath, script, String(port), marker], stop: [process.execPath, script, '--stop', marker],
+    ready: { address: host, port }, timeout: 12000 };
+  await writeFile(file, `${JSON.stringify(recipe, null, 2)}\n`, { flag: 'wx' });
+  console.log(file);
+} else {
+  await serve(parsePort(mode ?? 8788, 0), path);
+}
+
+function parsePort(value, minimum) {
+  const port = Number(value);
+  if (!Number.isInteger(port) || port < minimum || port > 65535) throw new RangeError(`Pass a TCP port between ${minimum} and 65535.`);
+  return port;
+}
+
+async function serve(port, marker) {
+  let count = 0;
+  let closing = false;
+  const clients = new Set();
+  const server = createServer((request, response) => {
+    if (request.method !== 'GET' || request.url !== '/stream') {
+      response.writeHead(404).end('Use GET /stream.\n');
+      return;
+    }
+    response.writeHead(200, { 'Content-Type': 'text/plain; charset=utf-8', 'Cache-Control': 'no-store' });
+    response.flushHeaders();
+    clients.add(response);
+    response.on('close', () => clients.delete(response));
+  });
+  const timer = setInterval(() => {
+    const line = `#${++count} ${new Date().toISOString()} PID=${process.pid}\n`;
+    for (const client of clients) if (!client.writableNeedDrain) client.write(line);
+  }, 1000);
+  timer.unref();
+  const watch = marker && setInterval(async () => {
+    if (await access(marker).then(() => true, () => false)) close();
+  }, 150);
+  watch?.unref();
+
+  server.once('error', error => {
+    console.error(`Could not listen on ${host}:${port} (${error.code ?? error.message}).`);
+    process.exitCode = 1;
+  });
+  server.listen(port, host, () => console.log(`PID=${process.pid} http://${host}:${server.address().port}/stream`));
+  function close() {
+    if (closing) return;
+    closing = true;
+    clearInterval(timer);
+    clearInterval(watch);
+    for (const client of clients) client.end();
+    server.close(async () => {
+      if (marker) await unlink(marker).catch(error => { if (error.code !== 'ENOENT') process.exitCode = 1; });
+    });
+  }
+  process.once('SIGINT', close);
+  process.once('SIGTERM', close);
+}

package/examples/workload.js

@@ -0,0 +1,29 @@
+import { createServer } from 'node:http';
+import { stat } from 'node:fs/promises';
+
+const port = Number(process.env.PF_DEMO_PORT ?? 8787);
+if (!Number.isInteger(port) || port < 1 || port > 65535) throw new Error('Set PF_DEMO_PORT to an integer from 1 to 65535.');
+const server = createServer((request, response) => {
+  response.setHeader('Content-Type', 'text/plain; charset=utf-8');
+  response.setHeader('X-Content-Type-Options', 'nosniff');
+  response.setHeader('Cache-Control', 'no-store');
+  const found = ['GET', 'HEAD'].includes(request.method) && request.url === '/health';
+  response.writeHead(found ? 200 : 404);
+  response.end(found ? 'ok\n' : 'not found\n');
+});
+server.requestTimeout = 10000;
+server.headersTimeout = 5000;
+server.maxHeadersCount = 32;
+server.on('connect', (_request, socket) => socket.destroy());
+server.on('upgrade', (_request, socket) => socket.destroy());
+server.listen({ host: '127.0.0.1', port, exclusive: true });
+
+const close = () => server.close(() => process.exit(0));
+process.on('SIGTERM', close);
+process.on('SIGINT', close);
+if (process.env.PF_DEMO_STOP_FILE) {
+  const timer = setInterval(async () => {
+    if (await stat(process.env.PF_DEMO_STOP_FILE).then(() => true, () => false)) { clearInterval(timer); close(); }
+  }, 200);
+  timer.unref();
+}

package/helpers/projectfreeze-darwin-arm64.sha256

@@ -0,0 +1 @@
+b3f0ea865bb15a190943b5991f1dfdf27a3899d45b544da8c4b764918fbccec3  projectfreeze-darwin-arm64

package/helpers/projectfreeze-darwin-x64.sha256

@@ -0,0 +1 @@
+a6c4ea1a02966c053d5c120a83795634f9d20a9228e2b36ae022fd44c97201d1  projectfreeze-darwin-x64

package/helpers/projectfreeze-linux-arm64.sha256

@@ -0,0 +1 @@
+b0f44b4db7167593a90d893dde2277e4f942ccc1e382b4401586d1c7418a8893  projectfreeze-linux-arm64

package/helpers/projectfreeze-linux-x64.sha256

@@ -0,0 +1 @@
+d68927c3ed60670f3f9c49c941d596c52951f915b127ee6e8f968f0e945c7d1a  projectfreeze-linux-x64

package/helpers/projectfreeze-win32-arm64.exe.sha256

@@ -0,0 +1 @@
+78454be06120e57c03865edcbf873234d86c05ad1140d800de2717267aa4b765  projectfreeze-win32-arm64.exe

package/helpers/projectfreeze-win32-x64.exe.sha256

@@ -0,0 +1 @@
+f2feb9d1960997a3817081e9127fb59831992dfdfe72b159b9d39b38845abce1  projectfreeze-win32-x64.exe

package/package.json

@@ -1,6 +1,19 @@
 {
   "name": "@kubilaycakmak/projectfreeze",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0-dev.5",
+  "description": "Local management for developer project execution environments",
+  "type": "module",
+  "bin": { "projectfreeze": "bin/projectfreeze.js" },
+  "engines": { "node": "^24.11.0 || ^26.0.0" },
+  "os": ["linux", "darwin", "win32"],
+  "cpu": ["x64", "arm64"],
+  "license": "MIT",
+  "repository": "github:kubilaycakmak/ProjectFreeze",
+  "files": ["bin", "src", "helpers", "docs", "examples"],
+  "scripts": {
+    "build:native": "node scripts/build-native.js",
+    "test": "node --test test/*.test.js",
+    "demo": "node examples/demo.js",
+    "check": "node --check bin/projectfreeze.js"
+  }
+}

package/src/cli.js

@@ -0,0 +1,135 @@
+import { readFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { parseArgs } from 'node:util';
+import manifest from '../package.json' with { type: 'json' };
+import { Fault, exitCode, problem } from './errors.js';
+import { daemon, request, waitOperation } from './ipc.js';
+
+const usage = `ProjectFreeze
+
+  projectfreeze                         Open the interactive terminal
+  projectfreeze --version               Print the installed version
+  projectfreeze menu                    Open the interactive terminal
+  projectfreeze menu --plain            Use line input and text output
+  projectfreeze list | discover | listeners | ports | services | history
+  projectfreeze inspect PROJECT
+  projectfreeze adopt [PROJECT] --cwd DIR --member PID@BIRTH@BOOT --confirm [--recipe FILE]
+  projectfreeze run --cwd DIR -- EXECUTABLE [ARG ...]
+  projectfreeze run --recipe FILE
+  projectfreeze freeze | resume | sleep | wake PROJECT [PROJECT ...]
+  projectfreeze checkpoint PROJECT [--backend criu|docker]
+  projectfreeze restore PROJECT --checkpoint ID
+  projectfreeze reconcile [PROJECT ...]
+  projectfreeze operation ID | cancel ID
+  projectfreeze daemon start|status|stop|foreground
+  projectfreeze mcp                       Start the local stdio server
+
+Options: --json, --detach, --cwd, --recipe, --member, --exclude, --confirm, --force.
+Sleep with --force approves forced shutdown of the reviewed exclusive scope.
+Press Ctrl-C to disconnect from a running operation. Use cancel ID to request cancellation.
+`;
+
+const mutations = new Set(['adopt', 'run', 'freeze', 'resume', 'sleep', 'wake', 'checkpoint', 'restore', 'reconcile']);
+const readActions = new Set(['list', 'discover', 'inspect', 'listeners', 'ports', 'services', 'history', 'operation', 'cancel']);
+const terminalText = value => String(value).replace(/[\p{Cc}\p{Cf}]/gu, ' ');
+const opts = {
+  json: { type: 'boolean' }, plain: { type: 'boolean' }, detach: { type: 'boolean' }, force: { type: 'boolean' }, confirm: { type: 'boolean' },
+  cwd: { type: 'string' }, recipe: { type: 'string' }, member: { type: 'string', multiple: true },
+  exclude: { type: 'string', multiple: true }, backend: { type: 'string' }, checkpoint: { type: 'string' },
+  help: { type: 'boolean', short: 'h' }, version: { type: 'boolean' }
+};
+
+function target(raw) {
+  const [pid, birth, boot, extra] = raw.split('@');
+  if (extra !== undefined || !pid || !birth || !boot) throw new Fault('USAGE', 'Process identities use PID@BIRTH@BOOT.');
+  return { pid: Number(pid), birth, boot };
+}
+
+function format(data) {
+  if (Array.isArray(data) && data.every(row => row.cwd)) {
+    return data.length ? data.map(row => `${row.id}\t${row.state}\t${row.processCount} process(es)\tTCP ${[...new Set(row.ports.map(p => p.port))].join(', ') || 'none'}\t${row.cwd}`).join('\n') : 'No projects in authorized scope.';
+  }
+  if (data?.outcomes) return [`${data.action} ${data.id} ${data.status}`, ...data.outcomes.map(row =>
+    `  ${row.target}  ${row.status}${row.message ? `  ${row.message}` : ''}`)].join('\n');
+  return JSON.stringify(data, null, 2);
+}
+
+export async function main(args) {
+  const separator = args.indexOf('--');
+  const flags = separator < 0 ? args : args.slice(0, separator);
+  const literal = separator < 0 ? [] : args.slice(separator + 1);
+  let json = flags.includes('--json');
+  try {
+    const { positionals, values } = parseArgs({ args: flags, allowPositionals: true, options: opts });
+    json = Boolean(values.json);
+    let [action, ...ids] = positionals;
+    if (values.help || action === 'help') { process.stdout.write(usage); return; }
+    if (values.version) {
+      const version = manifest.version;
+      process.stdout.write(`${json ? JSON.stringify({ schemaVersion: 1, ok: true, data: { version } }) : version}\n`);
+      return;
+    }
+    if (action === 'mcp') { await (await import('./mcp.js')).serve(); return; }
+    if (action === '_daemon' || (action === 'daemon' && ids[0] === 'foreground')) { await daemon(); return; }
+    const terminal = process.stdin.isTTY && process.stdout.isTTY && process.env.TERM !== 'dumb';
+    if (action === 'menu' || (!action && !json && (terminal || values.plain))) {
+      if (json || ids.length) throw new Fault('USAGE', 'Run projectfreeze menu with an optional --plain flag.');
+      if (terminal && !values.plain) await (await import('./tui.js')).interactive();
+      else await (await import('./line-menu.js')).lineMenu();
+      return;
+    }
+    action ??= 'list';
+    let input = {};
+    let auto = true;
+    if (action === 'daemon') {
+      if (!['start', 'status', 'stop'].includes(ids[0]) || ids.length !== 1) throw new Fault('USAGE', 'Choose daemon start, status, stop, or foreground.');
+      action = `daemon-${ids[0]}`;
+      auto = false;
+    } else if (mutations.has(action)) {
+      const cwd = resolve(values.cwd ?? '.');
+      let file;
+      if (values.recipe) {
+        try { file = JSON.parse(await readFile(resolve(values.recipe), 'utf8')); }
+        catch { throw new Fault('USAGE', 'The recipe file could not be read as JSON.'); }
+      }
+      if (action === 'adopt') {
+        if (ids.length > 1) throw new Fault('USAGE', 'Choose at most one registered project for adoption.');
+        input = { id: ids[0], cwd, recipe: file, confirm: values.confirm, members: values.member?.map(target), exclude: values.exclude?.map(target) };
+      }
+      else if (action === 'run') input = { recipe: file ? { ...file, cwd: resolve(values.cwd ?? file.cwd ?? '.') } : { cwd, argv: literal } };
+      else input = { ids, force: values.force, backend: values.backend, checkpoint: values.checkpoint };
+    } else if (readActions.has(action)) {
+      if (['inspect', 'operation', 'cancel'].includes(action)) {
+        if (ids.length !== 1) throw new Fault('USAGE', 'This command requires one identifier.');
+        input = { id: ids[0] };
+      } else if (ids.length) throw new Fault('USAGE', 'This command takes no positional arguments.');
+    } else throw new Fault('USAGE', 'Unknown command. Run projectfreeze --help.');
+
+    const reply = await request(action, input, auto);
+    let result = reply;
+    if (mutations.has(action) && !values.detach) {
+      if (!json && process.stderr.isTTY) process.stderr.write(`Operation ${reply.id} started.\n`);
+      result = await waitOperation(reply.id, op => {
+        if (!json && process.stderr.isTTY && op.status === 'running' && op.pending) process.stderr.write(`  ${op.pending}\n`);
+      });
+    }
+    const status = result?.status;
+    const fault = result?.outcomes?.find(outcome => outcome.status === 'failed');
+    const code = status === 'partial' || status === 'interrupted' ? 'PARTIAL' : status === 'cancelled' ? 'CANCELLED' : status === 'failed' ? fault?.code ?? 'INTERNAL' : null;
+    const display = () => {
+      if (action === 'listeners' || action === 'ports') return result.length ? result.map(row =>
+        [`${row.protocol ? `${row.protocol.toUpperCase()} ` : ''}${row.address.includes(':') ? `[${row.address}]` : row.address}:${row.port}`,
+          `PID ${row.pid ?? 'unknown'}`, row.name ?? row.image ?? 'unassigned', row.scope].map(terminalText).join('\t')).join('\n') : 'No local endpoints observed.';
+      if (action === 'services') return [...result.rows.map(row => [row.manager, row.name, `PID ${row.pid ?? 'unknown'}`, row.description ?? ''].map(terminalText).join('\t')),
+        ...result.unavailable.map(scope => `${scope} service manager unavailable`)].join('\n') || 'No running services observed.';
+      return format(result);
+    };
+    process.stdout.write(`${json ? JSON.stringify({ schemaVersion: 1, ok: !code, data: result }) : display()}\n`);
+    if (code) process.exitCode = exitCode(code);
+  } catch (error) {
+    const detail = error?.code?.startsWith?.('ERR_PARSE_ARGS') ? { code: 'USAGE', message: 'Invalid command-line arguments. Run projectfreeze --help.' } : problem(error);
+    const output = json ? JSON.stringify({ schemaVersion: 1, ok: false, error: detail }) : `${detail.code} ${detail.message}`;
+    (json ? process.stdout : process.stderr).write(`${output}\n`);
+    process.exitCode = exitCode(detail.code);
+  }
+}