@openparachute/hub 0.3.0-rc.1 → 0.5.0

package/src/commands/install.ts

@@ -1,16 +1,24 @@
-import { lstatSync, readFileSync } from "node:fs";
+import { existsSync, lstatSync, readFileSync, realpathSync } from "node:fs";
 import { createConnection } from "node:net";
 import { homedir } from "node:os";
-import { join } from "node:path";
+import { dirname, join } from "node:path";
 import { autoWireScribeAuth } from "../auto-wire.ts";
 import { CONFIG_DIR, SERVICES_MANIFEST_PATH } from "../config.ts";
+import {
+  type ModuleManifest,
+  ModuleManifestError,
+  readModuleManifest,
+  validateModuleManifest,
+} from "../module-manifest.ts";
 import { assignServicePort } from "../port-assign.ts";
 import {
   CANONICAL_PORT_MAX,
   CANONICAL_PORT_MIN,
-  getSpec,
+  FIRST_PARTY_FALLBACKS,
+  type FirstPartyFallback,
+  type ServiceSpec,
+  composeServiceSpec,
   isCanonicalPort,
-  knownServices,
 } from "../service-spec.ts";
 import { findService, readManifest, upsertService } from "../services-manifest.ts";
 import { start as lifecycleStart } from "./lifecycle.ts";
@@ -49,6 +57,15 @@ export interface InstallOpts {
    * Defaults to a symlink check against bun's global node_modules prefix.
    */
   isLinked?: (pkg: string) => boolean;
+  /**
+   * Returns the absolute path a global symlink points at, or null if no
+   * symlink exists. Used by local-path installs to skip a redundant
+   * `bun add -g <abspath>` when the path is already wired up — repeatedly
+   * `bun add -g <abspath>`'ing the same path appends duplicate entries to
+   * `~/.bun/install/global/package.json` until the lockfile parser breaks
+   * (hub#89). Defaults to a `readlink` against bun's global prefixes.
+   */
+  linkedPath?: (pkg: string) => string | null;
   /**
    * Optional npm dist-tag or exact version to install. When set, the
    * `bun add -g` call is composed as `<package>@<tag>` so RC testers can
@@ -82,6 +99,12 @@ export interface InstallOpts {
    * the call without spawning a real child.
    */
   startService?: (short: string) => Promise<number>;
+  /**
+   * `parachute install vault` only: skip the vault-name prompt by forwarding
+   * `--vault-name <name>` to `parachute-vault init`. Used by `parachute setup`
+   * (#45) to pre-collect the answer up front. Ignored for non-vault installs.
+   */
+  vaultName?: string;
   /**
    * `parachute install scribe` only: pre-pick the transcription provider so
    * the prompt doesn't fire. Validated against scribe's known providers — an
@@ -106,6 +129,19 @@ export interface InstallOpts {
    * unless the test populates services.json directly.
    */
   portProbe?: (port: number) => Promise<boolean>;
+  /**
+   * Test seam for reading `<packageDir>/.parachute/module.json`. Production
+   * uses the real file reader; tests inject a map from package-dir → manifest
+   * (or throw to simulate malformed JSON). Returns null when the package
+   * doesn't ship a manifest.
+   */
+  readManifest?: (packageDir: string) => Promise<ModuleManifest | null>;
+  /**
+   * Test seam for reading `<absPath>/package.json` during local-path install.
+   * Production reads + parses the file; tests inject a stub. Returns the
+   * package's `name` (used to find the install dir post-bun-add).
+   */
+  readPackageName?: (absPath: string) => string | null;
 }
 
 async function defaultRunner(cmd: readonly string[]): Promise<number> {
@@ -133,6 +169,24 @@ function defaultIsLinked(pkg: string): boolean {
   return false;
 }
 
+function defaultLinkedPath(pkg: string): string | null {
+  // bun has two install shapes for "linked-style" globals:
+  //   - `bun link`: <prefix>/node_modules/<pkg> is itself a symlink to source.
+  //   - `bun add -g <abspath>`: <prefix>/node_modules/<pkg> is a real dir
+  //     whose entries (package.json, etc.) are file-level symlinks to source.
+  // Resolving <prefix>/node_modules/<pkg>/package.json follows the link to
+  // the source package.json in either shape; dirname is the source dir.
+  for (const prefix of bunGlobalPrefixes()) {
+    const pkgJson = join(prefix, ...pkg.split("/"), "package.json");
+    try {
+      return dirname(realpathSync(pkgJson));
+    } catch {
+      // Not present at this prefix; try the next.
+    }
+  }
+  return null;
+}
+
 /**
  * Short-timeout TCP probe of `127.0.0.1:<port>`. Used by `parachute install`
  * to detect canonical slots that something else is already on. Fail-open:
@@ -206,32 +260,192 @@ function defaultFindGlobalInstall(pkg: string): string | null {
   return null;
 }
 
-export async function install(service: string, opts: InstallOpts = {}): Promise<number> {
+function defaultReadPackageName(absPath: string): string | null {
+  try {
+    const parsed = JSON.parse(readFileSync(join(absPath, "package.json"), "utf8"));
+    return typeof parsed?.name === "string" && parsed.name.length > 0 ? parsed.name : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Resolve the absolute path to the installed package directory. Local-path
+ * installs are their own source. Npm installs land under a bun globals
+ * prefix; we locate via `findGlobalInstall`. Returns null when the dir
+ * can't be located (first-party fallback path: not fatal; third-party:
+ * the manifest read downstream surfaces the error).
+ */
+function resolveInstallDir(
+  target: ResolvedTarget,
+  findGlobalInstall: (pkg: string) => string | null,
+): string | null {
+  if (target.kind === "local-path") {
+    // The local checkout itself is the source. We could also re-read from
+    // bun's globals after install, but reading the original avoids any
+    // weirdness with bun symlinking the dir vs. copying it.
+    return target.absPath;
+  }
+  const pkgJsonPath = findGlobalInstall(target.packageName);
+  return pkgJsonPath ? dirname(pkgJsonPath) : null;
+}
+
+/**
+ * Read the installed package's `.parachute/module.json`.
+ *
+ * Returns `null` when the package doesn't ship one (first-party falls back to
+ * the vendored manifest; third-party hard-errors at the call site). Returns
+ * `"error"` when the manifest exists but is malformed (or the install
+ * directory itself can't be located post-install) — caller treats both as
+ * an install-aborting error and the helper has already logged.
+ */
+async function readInstalledManifest(
+  target: ResolvedTarget,
+  packageDir: string | null,
+  deps: {
+    readManifest: (packageDir: string) => Promise<ModuleManifest | null>;
+    log: (line: string) => void;
+  },
+): Promise<ModuleManifest | null | "error"> {
+  if (!packageDir) {
+    // First-party fallback path (typical in tests): we don't actually need
+    // a real install dir — the vendored manifest covers us.
+    // Third-party: bun-add succeeded but we couldn't locate the install dir;
+    // caller already logged a probe-list — just say nothing's there.
+    return null;
+  }
+  try {
+    return await deps.readManifest(packageDir);
+  } catch (err) {
+    if (err instanceof ModuleManifestError) {
+      deps.log(`✗ ${target.packageName}: invalid .parachute/module.json — ${err.message}`);
+    } else {
+      const msg = err instanceof Error ? err.message : String(err);
+      deps.log(`✗ ${target.packageName}: failed to read .parachute/module.json — ${msg}`);
+    }
+    return "error";
+  }
+}
+
+/**
+ * What `parachute install <input>` resolved to. The CLI accepts three forms,
+ * and the resolution decides everything downstream — package name to bun-add,
+ * whether a vendored fallback applies, whether a missing
+ * `.parachute/module.json` is a hard error.
+ */
+type ResolvedTarget =
+  | {
+      readonly kind: "first-party";
+      readonly short: string;
+      readonly packageName: string;
+      readonly fallback: FirstPartyFallback;
+    }
+  | {
+      readonly kind: "npm";
+      readonly packageName: string;
+    }
+  | {
+      readonly kind: "local-path";
+      readonly absPath: string;
+      readonly packageName: string;
+    };
+
+/**
+ * Map an `<input>` (shortname / npm package / absolute path) to a target.
+ * Returns null on resolution failure (with logs already written).
+ *
+ * Order matters: first-party shortnames win over a hypothetical npm package
+ * literally named "vault", and absolute-path detection has to come before the
+ * "anything else is npm" fallback.
+ */
+function resolveInstallTarget(
+  input: string,
+  opts: InstallOpts,
+  log: (line: string) => void,
+): ResolvedTarget | null {
+  // Aliases (lens → notes) apply only to shortnames — npm packages and
+  // absolute paths pass through unaltered.
+  const aliased = SERVICE_ALIASES[input];
+  const candidate = aliased ?? input;
+
+  const fb = FIRST_PARTY_FALLBACKS[candidate];
+  if (fb) {
+    if (aliased !== undefined) {
+      log(`"${input}" has been renamed to "${aliased}"; installing ${aliased}.`);
+    }
+    return {
+      kind: "first-party",
+      short: candidate,
+      packageName: fb.package,
+      fallback: fb,
+    };
+  }
+
+  if (input.startsWith("/")) {
+    if (!existsSync(input)) {
+      log(`unknown service: "${input}" (path does not exist)`);
+      return null;
+    }
+    const readName = opts.readPackageName ?? defaultReadPackageName;
+    const packageName = readName(input);
+    if (!packageName) {
+      log(`✗ ${input} has no readable package.json — can't install as a Parachute module.`);
+      return null;
+    }
+    return { kind: "local-path", absPath: input, packageName };
+  }
+
+  // Anything else is treated as an npm package (bare or @scope/name). The
+  // module.json contract gates this — third-party packages without a
+  // manifest fail post-install with a clear error, not silently.
+  return { kind: "npm", packageName: input };
+}
+
+export async function install(input: string, opts: InstallOpts = {}): Promise<number> {
   const runner = opts.runner ?? defaultRunner;
   const manifestPath = opts.manifestPath ?? SERVICES_MANIFEST_PATH;
   const configDir = opts.configDir ?? CONFIG_DIR;
   const now = opts.now ?? (() => new Date());
   const log = opts.log ?? ((line) => console.log(line));
   const isLinked = opts.isLinked ?? defaultIsLinked;
+  const linkedPath = opts.linkedPath ?? defaultLinkedPath;
   const findGlobalInstall = opts.findGlobalInstall ?? defaultFindGlobalInstall;
+  const readManifest = opts.readManifest ?? readModuleManifest;
 
-  const aliased = SERVICE_ALIASES[service];
-  if (aliased !== undefined) {
-    log(`"${service}" has been renamed to "${aliased}"; installing ${aliased}.`);
-  }
-  const resolvedService = aliased ?? service;
+  const target = resolveInstallTarget(input, opts, log);
+  if (!target) return 1;
 
-  const spec = getSpec(resolvedService);
-  if (!spec) {
-    log(`unknown service: "${resolvedService}"`);
-    log(`known services: ${knownServices().join(", ")}`);
-    return 1;
+  // bun-add gate: skip when the package is already wired up.
+  //   - first-party + isLinked: scribe-style `bun link` against an unpublished
+  //     local checkout. `bun add -g` would 404.
+  //   - local-path + symlink already points at this path: re-installing the
+  //     same checkout. `bun add -g <abspath>` accumulates duplicate entries
+  //     in `~/.bun/install/global/package.json` until bun's lockfile parser
+  //     gives up (hub#89 — caught during paraclaw smoke testing 2026-04-27).
+  // Otherwise run `bun add -g <spec>` so bun's link plumbing produces a
+  // binary on PATH.
+  const localAlreadyLinkedTo = target.kind === "local-path" ? linkedPath(target.packageName) : null;
+  // Compare via realpath on the input side too, so symlinks in the path
+  // the user typed don't make us miss an existing match.
+  let targetReal: string | undefined;
+  if (target.kind === "local-path") {
+    try {
+      targetReal = realpathSync(target.absPath);
+    } catch {
+      targetReal = target.absPath;
+    }
   }
-
-  if (isLinked(spec.package)) {
-    log(`${spec.package} is already linked globally (bun link) — skipping bun add.`);
+  if (target.kind === "first-party" && isLinked(target.packageName)) {
+    log(`${target.packageName} is already linked globally (bun link) — skipping bun add.`);
+  } else if (target.kind === "local-path" && localAlreadyLinkedTo === targetReal) {
+    log(`${target.packageName} is already linked at ${target.absPath} — skipping bun add.`);
   } else {
-    const addSpec = opts.tag ? `${spec.package}@${opts.tag}` : spec.package;
+    const addSpec =
+      target.kind === "local-path"
+        ? target.absPath
+        : opts.tag
+          ? `${target.packageName}@${opts.tag}`
+          : target.packageName;
     log(`Installing ${addSpec}…`);
     const addCode = await runner(["bun", "add", "-g", addSpec]);
     if (addCode !== 0) {
@@ -242,9 +456,11 @@ export async function install(service: string, opts: InstallOpts = {}): Promise<
       // Bailing here on exit code alone means the caller-visible install
       // fails and downstream init/seed never runs — so probe the global
       // prefix before treating non-zero as fatal.
-      const foundAt = findGlobalInstall(spec.package);
+      const foundAt = findGlobalInstall(target.packageName);
       if (foundAt) {
-        log(`bun add reported exit ${addCode} but ${spec.package} is installed at ${foundAt}.`);
+        log(
+          `bun add reported exit ${addCode} but ${target.packageName} is installed at ${foundAt}.`,
+        );
         log(
           "Known bun 1.2.x lockfile quirk — the package landed despite the warning. Proceeding. `bun upgrade` to 1.3.x avoids it.",
         );
@@ -262,11 +478,69 @@ export async function install(service: string, opts: InstallOpts = {}): Promise<
     }
   }
 
+  // Read the installed `.parachute/module.json` (target convention). For
+  // first-party we fall back to the vendored manifest when absent; for
+  // third-party (npm / local-path) the manifest is the contract — its
+  // absence hard-errors here. See
+  // `parachute-patterns/patterns/module-json-extensibility.md`.
+  const installDir = resolveInstallDir(target, findGlobalInstall);
+  const installedManifest = await readInstalledManifest(target, installDir, {
+    readManifest,
+    log,
+  });
+  if (installedManifest === "error") return 1;
+
+  let manifest: ModuleManifest;
+  let extras = undefined as FirstPartyFallback["extras"] | undefined;
+  if (target.kind === "first-party") {
+    manifest = installedManifest ?? target.fallback.manifest;
+    extras = target.fallback.extras;
+  } else {
+    if (!installedManifest) {
+      log(`✗ ${target.packageName} does not ship .parachute/module.json — not a Parachute module.`);
+      log(
+        "  Authors: see parachute-patterns/patterns/module-json-extensibility.md for the contract.",
+      );
+      return 1;
+    }
+    // Third-party `name` collides with a first-party shortname → reject
+    // before we mint a services.json row that would hide a real first-party
+    // install. (Scope namespace is also `name`; collision == squatting.)
+    if (FIRST_PARTY_FALLBACKS[installedManifest.name] !== undefined) {
+      log(
+        `✗ ${target.packageName}: module name "${installedManifest.name}" collides with a first-party Parachute module.`,
+      );
+      return 1;
+    }
+    manifest = installedManifest;
+  }
+
+  const short = target.kind === "first-party" ? target.short : manifest.name;
+  const spec: ServiceSpec = composeServiceSpec({
+    packageName: target.packageName,
+    manifest,
+    extras,
+  });
+  // services.json key. Third-party modules key by `manifest.name` (canonical
+  // short — what `parachute start <svc>` accepts). First-party services keep
+  // keying by `manifestName` ("parachute-vault" etc.) because the upstream
+  // services write themselves to services.json under that name; switching the
+  // CLI seed alone would create dueling rows. The first-party migration to
+  // name-keyed rows happens when each upstream ships its own module.json
+  // (parachute-hub#56 follow-ups). See parachute-hub#85.
+  const entryName = target.kind === "first-party" ? spec.manifestName : manifest.name;
+
   if (spec.init) {
-    log(`Running ${spec.init.join(" ")}…`);
-    const initCode = await runner(spec.init);
+    // Forward --vault-name from the InstallOpts when set so `parachute setup`
+    // (and any future programmatic caller) can pre-answer the name prompt.
+    const initCmd =
+      short === "vault" && opts.vaultName
+        ? [...spec.init, "--vault-name", opts.vaultName]
+        : spec.init;
+    log(`Running ${initCmd.join(" ")}…`);
+    const initCode = await runner(initCmd);
     if (initCode !== 0) {
-      log(`${spec.init.join(" ")} exited ${initCode}`);
+      log(`${initCmd.join(" ")} exited ${initCode}`);
       return initCode;
     }
   }
@@ -278,15 +552,10 @@ export async function install(service: string, opts: InstallOpts = {}): Promise<
   // user-edited ports survive across upgrades. Compiled-in service-side
   // fallbacks (vault → 1940 etc.) stay; this just adds a CLI-managed
   // override.
-  const preInitEntry = findService(spec.manifestName, manifestPath);
+  const preInitEntry = findService(entryName, manifestPath);
   const probe = opts.portProbe ?? defaultPortProbe;
-  const occupied = await collectOccupiedPorts(
-    manifestPath,
-    spec.manifestName,
-    preInitEntry?.port,
-    probe,
-  );
-  const envPath = join(configDir, resolvedService, ".env");
+  const occupied = await collectOccupiedPorts(manifestPath, entryName, preInitEntry?.port, probe);
+  const envPath = join(configDir, short, ".env");
   const canonicalPort = spec.seedEntry?.().port ?? preInitEntry?.port;
   const portResult = assignServicePort({
     envPath,
@@ -306,20 +575,24 @@ export async function install(service: string, opts: InstallOpts = {}): Promise<
   // parachute-hub#44 reported notes not appearing in services.json on a fresh
   // bun 1.2.x install; the gate logic was already correct, but a verify-step
   // turns silent loss into something an operator can spot.
-  let entry = findService(spec.manifestName, manifestPath);
+  let entry = findService(entryName, manifestPath);
   if (!entry && spec.seedEntry) {
     const seedBase = spec.seedEntry();
+    // seedEntryFromManifest sets `name = manifest.manifestName`; for
+    // third-party we override to `entryName` (= manifest.name) so the row
+    // matches the lifecycle lookup key. First-party leaves it alone.
+    const withName = seedBase.name === entryName ? seedBase : { ...seedBase, name: entryName };
     const seed =
-      seedBase.port === portResult.port ? seedBase : { ...seedBase, port: portResult.port };
+      withName.port === portResult.port ? withName : { ...withName, port: portResult.port };
     upsertService(seed, manifestPath);
-    entry = findService(spec.manifestName, manifestPath);
+    entry = findService(entryName, manifestPath);
     if (entry) {
       log(
-        `Seeded services.json entry for ${spec.manifestName} (placeholder; service's own boot will overwrite).`,
+        `Seeded services.json entry for ${entryName} (placeholder; service's own boot will overwrite).`,
       );
     } else {
       log(
-        `⚠ tried to seed services.json entry for ${spec.manifestName}, but the readback came back empty.`,
+        `⚠ tried to seed services.json entry for ${entryName}, but the readback came back empty.`,
       );
       log(`  manifest path: ${manifestPath}`);
       log("  Re-run `parachute install` once the underlying issue is resolved.");
@@ -329,18 +602,29 @@ export async function install(service: string, opts: InstallOpts = {}): Promise<
     // different one (collision). Reflect the CLI's choice so the hub and
     // status views stay consistent with the .env we just wrote.
     upsertService({ ...entry, port: portResult.port }, manifestPath);
-    entry = findService(spec.manifestName, manifestPath);
+    entry = findService(entryName, manifestPath);
     log(
-      `Updated services.json port to ${portResult.port} for ${spec.manifestName} (was ${preInitEntry?.port ?? "—"}).`,
+      `Updated services.json port to ${portResult.port} for ${entryName} (was ${preInitEntry?.port ?? "—"}).`,
     );
   }
 
+  // Stamp installDir on the row. Lifecycle reads it back to find the
+  // module's `.parachute/module.json` (third-party startCmd) and to spawn
+  // with cwd. Done after seed/port-update so we cover all paths uniformly:
+  // the service's own init may have written the row without installDir, and
+  // the seed itself doesn't carry it (composeServiceSpec → seedEntry uses
+  // the manifest, which doesn't know its own install location).
+  if (entry && installDir && entry.installDir !== installDir) {
+    upsertService({ ...entry, installDir }, manifestPath);
+    entry = findService(entryName, manifestPath);
+  }
+
   if (!entry) {
     log(
-      `Installed, but no services.json entry for "${spec.manifestName}" yet. Run \`parachute status\` after the service has started.`,
+      `Installed, but no services.json entry for "${entryName}" yet. Run \`parachute status\` after the service has started.`,
     );
   } else {
-    log(`✓ ${spec.manifestName} registered on port ${entry.port}`);
+    log(`✓ ${entryName} registered on port ${entry.port}`);
     if (!isCanonicalPort(entry.port)) {
       log(
         `⚠ port ${entry.port} is outside the canonical Parachute range (${CANONICAL_PORT_MIN}–${CANONICAL_PORT_MAX}); may conflict with other software.`,
@@ -368,7 +652,7 @@ export async function install(service: string, opts: InstallOpts = {}): Promise<
   // ourselves if it was already running, mirroring the auto-wire pattern.
   // Failure here doesn't fail the install: a flaky restart shouldn't undo a
   // successful `bun add`.
-  if (resolvedService === "scribe") {
+  if (short === "scribe") {
     const setupOpts: SetupScribeProviderOpts = { configDir, log };
     if (opts.scribeProvider) setupOpts.preselectProvider = opts.scribeProvider;
     if (opts.scribeKey) setupOpts.preselectKey = opts.scribeKey;
@@ -389,11 +673,9 @@ export async function install(service: string, opts: InstallOpts = {}): Promise<
     const startService =
       opts.startService ??
       ((short: string) => lifecycleStart(short, { manifestPath, configDir, log }));
-    const startCode = await startService(resolvedService);
+    const startCode = await startService(short);
     if (startCode !== 0) {
-      log(
-        `⚠ ${resolvedService} didn't start cleanly. Run manually: parachute start ${resolvedService}`,
-      );
+      log(`⚠ ${short} didn't start cleanly. Run manually: parachute start ${short}`);
     }
   }
 
@@ -411,10 +693,17 @@ export async function install(service: string, opts: InstallOpts = {}): Promise<
   // last line of the install always reflects ground truth, not an early
   // snapshot. Surfaced by parachute-hub#44 — defensive logging that turns a
   // missing entry into a visible failure rather than a silent one.
-  const finalEntry = findService(spec.manifestName, manifestPath);
+  let finalEntry = findService(entryName, manifestPath);
+  // Re-stamp installDir if the service's first boot rewrote the row without
+  // it. Lifecycle commands beyond install (start/stop/restart/logs) need it
+  // present; we own this field, services don't have to know it exists.
+  if (finalEntry && installDir && finalEntry.installDir !== installDir) {
+    upsertService({ ...finalEntry, installDir }, manifestPath);
+    finalEntry = findService(entryName, manifestPath);
+  }
   if (!finalEntry) {
     log(
-      `⚠ ${spec.manifestName} is not in services.json after install. \`parachute status\` won't see it. Re-run install or file a bug.`,
+      `⚠ ${entryName} is not in services.json after install. \`parachute status\` won't see it. Re-run install or file a bug.`,
     );
   }