@avantmedia/specforge 0.0.0 → 0.19.0-rc.1

package/README.md

@@ -1 +1,57 @@
-Placeholder reserving this name. See https://github.com/avantmedialtd/specforge
+# SpecForge — headless web server
+
+Browse [OpenSpec](https://github.com/Fission-AI/OpenSpec) workspaces in your
+browser. This package ships `specforge-serve`, the standalone SpecForge web
+server: one binary with the UI embedded, no separate assets to deploy.
+
+Version 0.19.0-rc.1.
+
+## Run it
+
+```bash
+# In any directory containing an openspec/ workspace
+npx @avantmedia/specforge@0.19.0-rc.1
+```
+
+It binds `127.0.0.1:4317` and serves the UI there.
+
+For a server you intend to leave running — a remote dev box or a homelab
+machine — install it rather than using `npx`, which re-resolves the package on
+every invocation:
+
+```bash
+npm install -g @avantmedia/specforge@0.19.0-rc.1
+specforge-serve
+```
+
+## Options
+
+```
+--bind <addr>   interface to bind [env: SPECFORGE_WEB_BIND] (default: 127.0.0.1)
+--port <port>   port to listen on  [env: SPECFORGE_WEB_PORT] (default: 4317)
+--help          print the full reference and exit
+```
+
+**`--bind` on a non-loopback interface publishes the workspace-reading API to
+everyone who can reach the port, without authentication.** The default is
+loopback; only widen it on a network you trust.
+
+## Platforms
+
+macOS (Apple Silicon and Intel), Linux (x64 and arm64), and Windows (x64). The
+matching binary is selected automatically at install time — only one is
+downloaded.
+
+The Linux binaries are statically linked against musl, so they run on musl
+distributions such as Alpine as well as on glibc distributions, including older
+long-term-support releases.
+
+## Notes
+
+Installing through npm needs no macOS quarantine step: files extracted by a
+package manager are not flagged the way a browser download is. The binaries are
+**not** code-signed — packages carry npm build provenance, which attests where
+they were built, not who authored them.
+
+The desktop application and the terminal UI are distributed separately, from
+[GitHub Releases](https://github.com/avantmedialtd/specforge/releases/latest).

package/bin/specforge-serve.mjs

@@ -0,0 +1,58 @@
+#!/usr/bin/env node
+// The `specforge-serve` entry point of the `@avantmedia/specforge` wrapper.
+//
+// This file does as little as possible: find the binary that the matching
+// platform package installed, hand it every argument untouched, and get out of
+// the way. It deliberately does not parse, validate, or rewrite arguments —
+// `specforge-serve --help` is the binary's own help, and a flag added to the
+// server must never need a change here to reach it.
+
+import { createRequire } from "node:module";
+import { readFileSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import path from "node:path";
+
+import {
+  exitCodeFor,
+  locateBinary,
+  supportedKeysFrom,
+  unsupportedMessage,
+} from "../lib/resolve.mjs";
+
+const require = createRequire(import.meta.url);
+const here = path.dirname(fileURLToPath(import.meta.url));
+
+const binary = locateBinary({
+  platform: process.platform,
+  arch: process.arch,
+  resolvePackageJson: (specifier) => require.resolve(specifier),
+});
+
+if (binary === null) {
+  const manifest = JSON.parse(
+    readFileSync(path.join(here, "..", "package.json"), "utf8"),
+  );
+  console.error(
+    unsupportedMessage(
+      process.platform,
+      process.arch,
+      supportedKeysFrom(manifest.optionalDependencies),
+    ),
+  );
+  process.exit(1);
+}
+
+// `stdio: "inherit"` hands the real terminal to the server, so its startup
+// address and its non-loopback bind warning reach the user directly rather than
+// through a buffer this process would have to relay.
+const result = spawnSync(binary, process.argv.slice(2), { stdio: "inherit" });
+
+if (result.error) {
+  console.error(
+    `specforge-serve: failed to execute ${binary}\n${result.error.message}`,
+  );
+  process.exit(1);
+}
+
+process.exit(exitCodeFor(result));

package/lib/resolve.mjs

@@ -0,0 +1,114 @@
+// Platform resolution for the `@avantmedia/specforge` wrapper.
+//
+// This module ships inside the published wrapper package, so it must be plain
+// JavaScript that runs under a bare `node` with no build step — the repo's
+// TypeScript config deliberately scopes `include` to `src`, and nothing here is
+// compiled before publication.
+//
+// The wrapper carries no binary of its own. Each supported target is published
+// as a separate `@avantmedia/specforge-<os>-<cpu>` package, declared in the
+// wrapper's `optionalDependencies` and filtered by npm's `os`/`cpu` fields, so
+// installing the wrapper downloads exactly one of them. Everything below is the
+// logic that finds that one package at run time.
+
+import path from "node:path";
+
+/** npm's platform key for a target: `process.platform` + `-` + `process.arch`. */
+export function platformKey(platform, arch) {
+  return `${platform}-${arch}`;
+}
+
+/** The published platform package name for a platform key. */
+export function packageNameFor(key) {
+  return `@avantmedia/specforge-${key}`;
+}
+
+/** The executable's file name, which carries an extension only on Windows. */
+export function binaryNameFor(platform) {
+  return platform === "win32" ? "specforge-serve.exe" : "specforge-serve";
+}
+
+/**
+ * The platform keys this wrapper was published with.
+ *
+ * Read from the wrapper's own `optionalDependencies` rather than a hard-coded
+ * list: the generator writes that field and the platform packages from one
+ * table, so deriving the keys back out keeps a single source of truth and means
+ * a wrapper can never advertise support it did not ship.
+ */
+export function supportedKeysFrom(optionalDependencies) {
+  const prefix = packageNameFor("");
+  return Object.keys(optionalDependencies ?? {})
+    .filter((name) => name.startsWith(prefix))
+    .map((name) => name.slice(prefix.length))
+    .sort();
+}
+
+/**
+ * Locate the platform binary, or return `null` when no platform package is
+ * present.
+ *
+ * `null` covers two distinct situations that are indistinguishable here and
+ * identical to the caller: the host is a target we never published, or the host
+ * is supported but the package manager resolved the `optionalDependencies` to
+ * nothing. The latter is a recurring npm defect rather than a theoretical case,
+ * which is why a missing package is a value to handle and not an exception to
+ * let escape.
+ *
+ * `resolvePackageJson` is injected so the failure branches stay testable
+ * without publishing or installing anything.
+ */
+export function locateBinary({ platform, arch, resolvePackageJson }) {
+  const pkg = packageNameFor(platformKey(platform, arch));
+  let manifestPath;
+  try {
+    manifestPath = resolvePackageJson(`${pkg}/package.json`);
+  } catch {
+    return null;
+  }
+  return path.join(path.dirname(manifestPath), "bin", binaryNameFor(platform));
+}
+
+/**
+ * The message shown when no binary could be located.
+ *
+ * It names the detected platform explicitly, because the most common report is
+ * "it doesn't work on my machine" from a container whose architecture the user
+ * has not thought about, and points at the release downloads so an unsupported
+ * platform still has a path forward.
+ */
+export function unsupportedMessage(platform, arch, supportedKeys) {
+  const key = platformKey(platform, arch);
+  const known = supportedKeys.includes(key);
+
+  const reason = known
+    ? `The platform package ${packageNameFor(key)} is not installed.\n` +
+      `Your platform (${key}) is supported, so this is usually a package\n` +
+      `manager that resolved optional dependencies to nothing — a known npm\n` +
+      `issue. Reinstalling, or removing the lockfile and node_modules and\n` +
+      `installing again, normally fixes it.`
+    : `No SpecForge server build is published for your platform (${key}).\n` +
+      `Published platforms: ${supportedKeys.join(", ")}.`;
+
+  return (
+    `specforge-serve: could not find a binary to run.\n\n${reason}\n\n` +
+    `Prebuilt archives for every released platform are available at\n` +
+    `https://github.com/avantmedialtd/specforge/releases/latest`
+  );
+}
+
+/**
+ * Translate a finished child process into this process's exit code.
+ *
+ * A child killed by a signal reports `status: null`, and exiting 0 there would
+ * report success for a server that was terminated. The shell convention of
+ * `128 + signal` keeps `Ctrl-C` distinguishable from a clean shutdown.
+ */
+export function exitCodeFor({ status, signal }) {
+  if (typeof status === "number") return status;
+  if (signal) {
+    const numbers = { SIGINT: 2, SIGQUIT: 3, SIGKILL: 9, SIGTERM: 15 };
+    return 128 + (numbers[signal] ?? 0);
+  }
+  return 1;
+}

package/package.json

@@ -1,9 +1,39 @@
 {
   "name": "@avantmedia/specforge",
-  "version": "0.0.0",
-  "description": "Placeholder reserving this name for npm trusted publishing. Do not install.",
+  "version": "0.19.0-rc.1",
   "license": "MIT",
-  "repository": { "type": "git", "url": "git+https://github.com/avantmedialtd/specforge.git" },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/avantmedialtd/specforge.git"
+  },
   "homepage": "https://github.com/avantmedialtd/specforge#readme",
-  "publishConfig": { "access": "public" }
+  "bugs": {
+    "url": "https://github.com/avantmedialtd/specforge/issues"
+  },
+  "description": "Run the SpecForge headless web server — browse OpenSpec workspaces in a browser.",
+  "keywords": [
+    "specforge",
+    "openspec",
+    "spec-driven",
+    "cli",
+    "server"
+  ],
+  "bin": {
+    "specforge-serve": "bin/specforge-serve.mjs"
+  },
+  "files": [
+    "bin",
+    "lib",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "optionalDependencies": {
+    "@avantmedia/specforge-darwin-arm64": "0.19.0-rc.1",
+    "@avantmedia/specforge-darwin-x64": "0.19.0-rc.1",
+    "@avantmedia/specforge-linux-x64": "0.19.0-rc.1",
+    "@avantmedia/specforge-linux-arm64": "0.19.0-rc.1",
+    "@avantmedia/specforge-win32-x64": "0.19.0-rc.1"
+  }
 }