zyrk 0.2.3 → 0.3.7

package/README.md

@@ -1,16 +1,15 @@
 # zyrk
 
-[![CI](https://github.com/kingjethro999/nexu/actions/workflows/ci.yml/badge.svg)](https://github.com/kingjethro999/nexu/actions/workflows/ci.yml)
+[![CI](https://github.com/kingjethro999/zyrk/actions/workflows/ci.yml/badge.svg)](https://github.com/kingjethro999/zyrk/actions/workflows/ci.yml)
 [![Node.js](https://img.shields.io/badge/Node.js-24%2B-339933?logo=node.js&logoColor=white)](https://nodejs.org/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 
 An npm-compatible package manager built around **one verified package store per
 OS user**, with dependency-aware package instances linked into projects.
 
-**Pre-release and under active construction.** The current CLI can fetch and run
-one-off tools with `dlx` and `create`. Ordinary project installation, dependency
-editing, garbage collection, repair, and deployment are still being built. Check
-`zyrk --help` for the implemented command surface.
+**Pre-release and under active construction.** `zyrk install` installs project
+dependencies through verified shared storage; `dlx` and `create` run one-off
+tools. Check `zyrk --help` and the limitations below before adopting it.
 
 ## Why zyrk exists
 
@@ -30,8 +29,13 @@ be reported only after reproducible measurements and compatibility tests.
 
 ## Try the current CLI
 
-Once the `zyrk` package is published, install it with `npm install -g zyrk`,
-then run `zyrk --help`.
+Install from npm:
+
+```bash
+npm install -g zyrk
+zyrk --help
+zyrk --version
+```
 
 Requires **Node.js 24 or newer**. The source runs directly with Node's native
 TypeScript support; no compilation step or native toolchain is required to
@@ -40,17 +44,65 @@ install zyrk itself.
 From a checkout:
 
 ```bash
-git clone https://github.com/kingjethro999/nexu.git zyrk
+git clone https://github.com/kingjethro999/zyrk.git zyrk
 cd zyrk
 npm ci
 node bin/zyrk.js --help
 node bin/zyrk.js --version
 ```
 
-For an npm-distributed build, use the exact package name listed on its npm page
-and check that its repository points to `kingjethro999/nexu`. The executable is
-`zyrk`. The existing [npm publishing action](.github/workflows/npm-publish.yml)
-uses the repository’s `NPM_TOKEN` secret when a GitHub release is created.
+### One-line install (shell)
+
+Linux / macOS:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/kingjethro999/zyrk/main/install.sh | sh
+```
+
+Windows (PowerShell):
+
+```powershell
+irm https://raw.githubusercontent.com/kingjethro999/zyrk/main/install.ps1 | iex
+```
+
+### Install project dependencies
+
+```bash
+zyrk install                     # dependencies + devDependencies
+zyrk install react               # add and save a registry package
+zyrk install -D typescript        # save a development dependency
+zyrk i --frozen-lockfile          # require an unchanged compatible lock
+zyrk install --offline --frozen-lockfile
+zyrk install --omit=dev           # project production roots only
+zyrk install --lockfile-only      # write selections without installing
+```
+
+zyrk resolves exact versions, verifies archive integrity before extraction, and
+creates dependency-aware realizations in the per-user store. Project
+`node_modules` contains links to those realizations. Two projects selecting the
+same dependency context reuse the same files; incompatible versions and peer
+contexts stay separate. Normal CJS and ESM imports continue to work.
+
+`package-lock.json` records npm selections plus a `zyrk` extension. Warm installs
+reuse compatible locked selections; frozen installs reject drift. Non-frozen
+installation can adopt supported npm v2/v3 lockfiles without reselecting versions.
+Offline installs use locked verified sources and fail if an input is missing.
+Manifest, lock, and projection changes are journaled for process-crash recovery;
+a failed resolution, verification, or build-policy check keeps the prior graph.
+
+Dependency install scripts and implicit native builds are blocked by default.
+`--ignore-scripts` explicitly produces an **intentionally unbuilt** installation.
+Root install hooks are reported and never run automatically. Script approval,
+private native builds, runtime-mutable packages, workspaces, overrides, Git/local
+sources, and authenticated or mixed scoped registries are not supported by this
+install path yet. Unsupported platform constraints and failed optional packages
+currently fail installation instead of being silently omitted. macOS/Windows
+compatibility and framework support remain unverified.
+
+Use `--registry=https://your-registry.example/` for a compatible unauthenticated
+registry. The adapter reads the default registry from user/project `.npmrc`, and
+fails closed on scoped registry routing or disabled TLS verification. Tool
+commands (`dlx`/`create`) still use their existing public-registry configuration.
 
 ### Run a one-off tool
 
@@ -79,15 +131,16 @@ not a sandbox.
 
 ### Current command coverage
 
-| Surface                                                                                | Current behavior                                                      |
-| -------------------------------------------------------------------------------------- | --------------------------------------------------------------------- |
-| `--help`, `--version`                                                                  | Show the CLI surface and package version.                             |
-| `dlx`, `create`                                                                        | Resolve, fetch, verify archives, and run temporary tool environments. |
-| `publish`, `unpublish`, `access`, `deprecate`, `dist-tag`, `owner`                     | Explicitly delegate to your npm CLI.                                  |
-| `token`, `adduser`, `login`, `logout`, `whoami`, `ping`, `pack`                        | Explicitly delegate to your npm CLI.                                  |
-| `install`, `add`, `remove`, `update`, `run`, `exec`                                    | Report `ZYRK_NOT_IMPLEMENTED`.                                        |
-| `store`, `projects`, `repair`, `import`, `deploy`, `docker`                            | Report `ZYRK_NOT_IMPLEMENTED`.                                        |
-| `list`, `why`, `doctor`, `approve-builds`, `rebuild`, `audit`, `patch`, `patch-commit` | Report `ZYRK_NOT_IMPLEMENTED`.                                        |
+| Surface                                                                                | Current behavior                                                                    |
+| -------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
+| `install`, `i`                                                                         | Resolve or reuse the lock, verify sources, and publish shared project dependencies. |
+| `--help`, `--version`                                                                  | Show the CLI surface and package version.                                           |
+| `dlx`, `create`                                                                        | Resolve, fetch, verify archives, and run temporary tool environments.               |
+| `publish`, `unpublish`, `access`, `deprecate`, `dist-tag`, `owner`                     | Explicitly delegate to your npm CLI.                                                |
+| `token`, `adduser`, `login`, `logout`, `whoami`, `ping`, `pack`                        | Explicitly delegate to your npm CLI.                                                |
+| `add`, `remove`, `update`, `run`, `exec`                                               | Report `ZYRK_NOT_IMPLEMENTED`.                                                      |
+| `store`, `projects`, `repair`, `import`, `deploy`, `docker`                            | Report `ZYRK_NOT_IMPLEMENTED`.                                                      |
+| `list`, `why`, `doctor`, `approve-builds`, `rebuild`, `audit`, `patch`, `patch-commit` | Report `ZYRK_NOT_IMPLEMENTED`.                                                      |
 
 Native commands that support `--json` return a versioned result envelope.
 `dlx` and `create` reject that option because the tool owns stdout. Delegated
@@ -173,7 +226,7 @@ GitHub release is created; ordinary commits do not trigger that action.
 
 The contributor guide is [AGENTS.md](AGENTS.md). Bug reports and reproducible
 compatibility cases belong in
-[GitHub issues](https://github.com/kingjethro999/nexu/issues).
+[GitHub issues](https://github.com/kingjethro999/zyrk/issues).
 
 ## Naming and local state
 

package/VERSION

@@ -1 +1 @@
-v0.2.3
+v0.3.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zyrk",
-  "version": "0.2.3",
+  "version": "0.3.7",
   "description": "Storage-efficient Node package manager: one verified store per user, shared across projects through links.",
   "license": "MIT",
   "type": "module",
@@ -36,12 +36,12 @@
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/kingjethro999/nexu.git"
+    "url": "git+https://github.com/kingjethro999/zyrk.git"
   },
   "bugs": {
-    "url": "https://github.com/kingjethro999/nexu/issues"
+    "url": "https://github.com/kingjethro999/zyrk/issues"
   },
-  "homepage": "https://github.com/kingjethro999/nexu#readme",
+  "homepage": "https://github.com/kingjethro999/zyrk#readme",
   "keywords": [
     "package-manager",
     "npm",

package/src/cli/main.ts

@@ -4,7 +4,7 @@
  * This is the roadmap skeleton, not the whole implementation: `dlx` and
  * `create` run temporary tool environments; `--help`, `--version`, the
  * global-install rejection, and explicit npm delegation do their jobs.
- * Every other native dependency command fails with ZYRK_NOT_IMPLEMENTED
+ * `install` publishes a verified shared project graph. Other dependency commands fail with ZYRK_NOT_IMPLEMENTED
  * rather than pretending to work; unknown commands fail with ZYRK_USAGE
  * and the help text.
  * Nothing here launches a subprocess: rejection happens before resolution,
@@ -12,6 +12,8 @@
  * process (SPEC 15.3.1).
  */
 
+import { installProject, type InstallOptions } from "../install/run.ts";
+import { installRegistry } from "../install/registry.ts";
 import { readFileSync } from "node:fs";
 import * as path from "node:path";
 import { fileURLToPath } from "node:url";
@@ -60,7 +62,7 @@ for (const [names] of NATIVE_COMMANDS) {
 }
 
 /** Commands with a real implementation behind runCli. */
-const IMPLEMENTED_COMMANDS = new Set(["dlx", "create"]);
+const IMPLEMENTED_COMMANDS = new Set(["dlx", "create", "install", "i"]);
 
 export function helpText(version: string): string {
   const lines = [
@@ -301,6 +303,89 @@ export async function runCli(options: RunCliOptions): Promise<number> {
       );
     }
   }
+  if (
+    !parsed.help &&
+    !parsed.version &&
+    (parsed.command === "install" || parsed.command === "i")
+  ) {
+    if (isGlobalInstallRequest(parsed.command, parsed.commandArgs, options.env))
+      return emit(fail(globalInstallError(parsed.command), parsed));
+    try {
+      if (
+        parsed.commandArgs.includes("--help") ||
+        parsed.commandArgs.includes("-h")
+      ) {
+        return emit(
+          ok(
+            "Usage: zyrk install [package[@version] ...] [-D] [--save-exact] [--frozen-lockfile] [--offline] [--ignore-scripts] [--lockfile-only] [--omit=dev] [--registry=https://registry.npmjs.org/] [--json]\n",
+            parsed,
+          ),
+        );
+      }
+      const specs: string[] = [];
+      const flags: Partial<InstallOptions> = {};
+      let registryUrl: string | undefined;
+      for (const token of parsed.commandArgs) {
+        if (token === "--frozen-lockfile") flags.frozen = true;
+        else if (token === "--offline") flags.offline = true;
+        else if (token === "--ignore-scripts") flags.ignoreScripts = true;
+        else if (token === "--lockfile-only") flags.lockfileOnly = true;
+        else if (token === "--omit=dev" || token === "--production")
+          flags.omitDev = true;
+        else if (token === "-D" || token === "--save-dev") flags.saveDev = true;
+        else if (token === "-E" || token === "--save-exact")
+          flags.saveExact = true;
+        else if (token === "--no-global" || token === "--global=false")
+          continue;
+        else if (token.startsWith("--registry="))
+          registryUrl = token.slice("--registry=".length);
+        else if (token.startsWith("-"))
+          throw new ZyrkError("ZYRK_USAGE", "Unsupported install option.", {
+            remedy:
+              "Run zyrk install --help for supported options; use --registry=URL for a custom registry.",
+          });
+        else specs.push(token);
+      }
+      const cwd = options.cwd ?? process.cwd();
+      const tools = options.tools
+        ? await options.tools()
+        : {
+            registry: await installRegistry({
+              cwd,
+              env: options.env,
+              version,
+              ...(registryUrl === undefined ? {} : { registry: registryUrl }),
+            }),
+            store: await Store.open({
+              root: resolveStoreRoot({ env: options.env }).root,
+              create: true,
+            }),
+          };
+      const result = await installProject({
+        ...flags,
+        specs,
+        projectDir: cwd,
+        ...tools,
+      });
+      if (parsed.json)
+        return emit({
+          exitCode: 0,
+          stdout: `${JSON.stringify({ schemaVersion: CLI_JSON_SCHEMA_VERSION, status: "ok", ...result })}\n`,
+          stderr: "",
+        });
+      const summary =
+        result.readiness === "lockfile-only"
+          ? "Lockfile written; dependencies were not installed."
+          : `Installed ${result.packages} packages using shared storage (${result.reused} realizations reused); ${result.readiness}.`;
+      return emit({
+        exitCode: 0,
+        stdout: `${summary}\n`,
+        stderr: result.warnings.map((w) => `zyrk: ${w}\n`).join(""),
+      });
+    } catch (error) {
+      return emit(fail(toZyrkError(error, "zyrk install failed."), parsed));
+    }
+  }
   if (
     !parsed.help &&
     !parsed.version &&

package/src/commands/dependencies.ts

@@ -0,0 +1,154 @@
+/** Parse dependency edits; the installer owns resolution and atomic publication. */
+import npa from "npm-package-arg";
+import { ZyrkError } from "../errors.ts";
+import type { RegistryClient } from "../fetch/registry.ts";
+import type { Store } from "../store/layout.ts";
+import { packageName } from "../install/lock.ts";
+import {
+  installProject,
+  type InstallOptions,
+  type InstallResult,
+} from "../install/run.ts";
+
+export type DependencyCommand = "add" | "remove" | "update" | "import";
+
+function usage(command: DependencyCommand, reason: string): ZyrkError {
+  return new ZyrkError(
+    "ZYRK_USAGE",
+    `Cannot ${command} dependencies: ${reason}.`,
+    {
+      remedy:
+        "Use add <spec...>, remove <name...>, update [--latest] [name...], or import --from npm; review zyrk --help for supported options.",
+    },
+  );
+}
+
+export async function runDependencyCommand(options: {
+  command: DependencyCommand;
+  args: readonly string[];
+  projectDir: string;
+  store: Store;
+  registry: RegistryClient;
+}): Promise<InstallResult> {
+  const { command } = options;
+  const install: InstallOptions = {
+    projectDir: options.projectDir,
+    store: options.store,
+    registry: options.registry,
+  };
+  const names: string[] = [];
+  let from: string | undefined;
+  let latest = false;
+  let positional = false;
+  for (let i = 0; i < options.args.length; i++) {
+    const arg = options.args[i]!;
+    if (!positional && arg === "--") {
+      positional = true;
+      continue;
+    }
+    if (!positional && arg.startsWith("-")) {
+      switch (arg) {
+        case "-D":
+        case "--save-dev":
+          if (command !== "add")
+            throw usage(command, "--save-dev is only valid for add");
+          install.saveDev = true;
+          break;
+        case "-O":
+        case "--save-optional":
+          if (command !== "add")
+            throw usage(command, "--save-optional is only valid for add");
+          install.saveOptional = true;
+          break;
+        case "-E":
+        case "--save-exact":
+          if (command !== "add" && command !== "update")
+            throw usage(
+              command,
+              "--save-exact is only valid for add or update",
+            );
+          install.saveExact = true;
+          break;
+        case "--latest":
+          if (command !== "update")
+            throw usage(command, "--latest is only valid for update");
+          latest = true;
+          break;
+        case "--ignore-scripts":
+          install.ignoreScripts = true;
+          break;
+        case "--lockfile-only":
+          install.lockfileOnly = true;
+          break;
+        case "--from":
+          if (command !== "import" || from !== undefined)
+            throw usage(command, "unexpected --from option");
+          from = options.args[++i];
+          if (from === undefined) throw usage(command, "--from requires npm");
+          break;
+        default:
+          if (
+            arg.startsWith("--from=") &&
+            command === "import" &&
+            from === undefined
+          ) {
+            from = arg.slice(7);
+            break;
+          }
+          if (
+            command === "add" &&
+            ["-g", "--global", "--global=true"].includes(arg)
+          )
+            throw new ZyrkError(
+              "ZYRK_GLOBAL_INSTALL_UNSUPPORTED",
+              "Cannot install global dependencies through zyrk.",
+              { remedy: "Run npm install --global directly instead." },
+            );
+          throw usage(command, "an unsupported option was supplied");
+      }
+    } else names.push(arg);
+  }
+  if (install.saveDev && install.saveOptional)
+    throw usage(command, "development and optional dependency groups conflict");
+  switch (command) {
+    case "add":
+      if (!names.length)
+        throw usage(command, "at least one package specification is required");
+      for (const name of names) {
+        try {
+          const parsed = npa(name);
+          if (
+            !parsed.name ||
+            !packageName(parsed.name) ||
+            !["version", "range", "tag", "alias"].includes(parsed.type)
+          )
+            throw new Error("unsupported");
+        } catch {
+          throw usage(command, "a registry package specification is invalid");
+        }
+      }
+      install.specs = names;
+      break;
+    case "remove":
+    case "update":
+      if (command === "remove" && !names.length)
+        throw usage(command, "at least one direct dependency name is required");
+      if (names.some((name) => !packageName(name)))
+        throw usage(
+          command,
+          "expected direct dependency names without versions",
+        );
+      install.mutation =
+        command === "remove" ? { remove: names } : { update: names, latest };
+      break;
+    case "import":
+      if (from !== "npm" || names.length)
+        throw usage(
+          command,
+          "import requires --from npm and no package arguments",
+        );
+      install.importNpm = true;
+      break;
+  }
+  return installProject(install);
+}