@hoangsonw/forge 0.1.0

package/package.json

@@ -0,0 +1,89 @@
+{
+  "name": "@hoangsonw/forge",
+  "version": "0.1.0",
+  "description": "Forge - a local-first, multi-agent, programmable software-engineering runtime",
+  "license": "MIT",
+  "author": "Son Nguyen (hoangsonw)",
+  "homepage": "https://github.com/hoangsonw/Forge-Agentic-Coding-CLI#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hoangsonw/Forge-Agentic-Coding-CLI.git"
+  },
+  "bugs": {
+    "url": "https://github.com/hoangsonw/Forge-Agentic-Coding-CLI/issues"
+  },
+  "bin": {
+    "forge": "bin/forge.js"
+  },
+  "main": "./dist/cli/index.js",
+  "type": "commonjs",
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json && node scripts/copy-assets.js",
+    "build:watch": "tsc -w -p tsconfig.json",
+    "clean": "rm -rf dist",
+    "dev": "ts-node src/cli/index.ts",
+    "lint": "eslint 'src/**/*.ts'",
+    "format": "prettier --write 'src/**/*.ts' 'test/**/*.ts'",
+    "format:check": "prettier --check 'src/**/*.ts' 'test/**/*.ts'",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "typecheck": "tsc --noEmit",
+    "prepare": "npm run build",
+    "start": "node ./bin/forge.js",
+    "link": "npm run build && npm link",
+    "unlink": "npm unlink -g @forge/cli",
+    "relink": "npm run unlink --silent; npm run link",
+    "postinstall": "node scripts/postinstall.js"
+  },
+  "files": [
+    "bin/",
+    "dist/",
+    "scripts/",
+    "install/",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "better-sqlite3": "^11.3.0",
+    "chalk": "^4.1.2",
+    "cli-table3": "^0.6.5",
+    "commander": "^12.1.0",
+    "dotenv": "^16.4.5",
+    "ora": "^5.4.1",
+    "prompts": "^2.4.2",
+    "semver": "^7.6.3",
+    "undici": "^6.19.2",
+    "ws": "^8.18.0",
+    "yaml": "^2.5.0",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^7.6.11",
+    "@types/node": "^20.14.0",
+    "@types/prompts": "^2.4.9",
+    "@types/semver": "^7.5.8",
+    "@types/ws": "^8.5.12",
+    "@typescript-eslint/eslint-plugin": "^8.0.0",
+    "@typescript-eslint/parser": "^8.0.0",
+    "@vitest/coverage-v8": "^2.0.0",
+    "eslint": "^8.57.0",
+    "prettier": "^3.8.3",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.5.4",
+    "vitest": "^2.0.0"
+  },
+  "keywords": [
+    "cli",
+    "ai",
+    "coding",
+    "agent",
+    "local-first",
+    "llm",
+    "developer-tools"
+  ]
+}

package/scripts/bundle.js

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+/**
+ * Create an offline bundle: tarball of dist/, package.json, LICENSE, README,
+ * scripts, install/. Used by `forge bundle create` and by enterprise
+ * air-gapped deployments.
+ */
+'use strict';
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+const root = path.resolve(__dirname, '..');
+const outDir = process.argv[2] || path.join(root, 'tmp');
+fs.mkdirSync(outDir, { recursive: true });
+
+const out = path.join(outDir, 'forge-bundle.tar.gz');
+const include = ['dist', 'bin', 'scripts', 'install', 'package.json', 'README.md', 'LICENSE'];
+for (const p of include) {
+  if (!fs.existsSync(path.join(root, p))) {
+    console.error(`[forge bundle] missing ${p}; run npm run build first`);
+    process.exit(1);
+  }
+}
+const res = spawnSync('tar', ['-czf', out, '-C', root, ...include], { stdio: 'inherit' });
+if (res.status !== 0) process.exit(res.status ?? 1);
+console.log(`Wrote ${out}`);

package/scripts/copy-assets.js

@@ -0,0 +1,33 @@
+#!/usr/bin/env node
+/**
+ * Copy non-TS assets (e.g. UI public/) into dist after tsc. tsc doesn't copy
+ * .html / .css / static .js files on its own — without this step the
+ * compiled server ends up serving stale public files that were last copied
+ * by hand.
+ *
+ * Directories to mirror:
+ *   src/ui/public   → dist/ui/public
+ */
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const root = path.resolve(__dirname, '..');
+const pairs = [
+  [path.join(root, 'src', 'ui', 'public'), path.join(root, 'dist', 'ui', 'public')],
+];
+
+const copyTree = (src, dst) => {
+  if (!fs.existsSync(src)) return;
+  fs.mkdirSync(dst, { recursive: true });
+  for (const name of fs.readdirSync(src)) {
+    const s = path.join(src, name);
+    const d = path.join(dst, name);
+    const stat = fs.statSync(s);
+    if (stat.isDirectory()) copyTree(s, d);
+    else fs.copyFileSync(s, d);
+  }
+};
+
+for (const [src, dst] of pairs) copyTree(src, dst);

package/scripts/link.sh

@@ -0,0 +1,79 @@
+#!/usr/bin/env bash
+# Forge — dev link helper.
+#
+# Puts the `forge` command on your PATH by linking this checkout into the
+# active Node's global bin. Run once after cloning:
+#
+#   ./scripts/link.sh
+#
+# After this, `forge --version` works from anywhere. Rebuild with
+# `npm run build` (or `npm run build:watch`) to pick up source changes —
+# the shim at bin/forge.js loads dist/ live, so no re-link needed.
+
+set -euo pipefail
+
+cd "$(dirname "$0")/.."
+ROOT="$(pwd)"
+
+say()  { printf '\033[1;36m[forge]\033[0m %s\n' "$*"; }
+warn() { printf '\033[1;33m[forge]\033[0m %s\n' "$*" >&2; }
+fail() { printf '\033[1;31m[forge]\033[0m %s\n' "$*" >&2; exit 1; }
+
+command -v node >/dev/null 2>&1 || fail "Node is not installed. Install Node 20+ first (nvm: https://github.com/nvm-sh/nvm)."
+command -v npm  >/dev/null 2>&1 || fail "npm is not installed. It ships with Node."
+
+NODE_VERSION="$(node -v)"
+NODE_MAJOR="${NODE_VERSION#v}"
+NODE_MAJOR="${NODE_MAJOR%%.*}"
+if [ "${NODE_MAJOR:-0}" -lt 20 ]; then
+  fail "Forge needs Node 20+. You have ${NODE_VERSION}. Upgrade (e.g. \`nvm install 20\`) and re-run."
+fi
+
+say "Node ${NODE_VERSION} OK."
+
+if [ ! -f "${ROOT}/dist/cli/index.js" ] || [ "${ROOT}/src/cli/index.ts" -nt "${ROOT}/dist/cli/index.js" ]; then
+  say "Building dist/ ..."
+  npm run --silent build
+else
+  say "dist/ is fresh — skipping build."
+fi
+
+say "Linking @hoangsonw/forge into $(npm prefix -g)/bin ..."
+npm link --silent
+
+GLOBAL_BIN="$(npm prefix -g)/bin"
+FORGE_BIN="${GLOBAL_BIN}/forge"
+
+if [ ! -e "${FORGE_BIN}" ]; then
+  fail "npm link finished but \`${FORGE_BIN}\` was not created. Check \`npm config get prefix\` and permissions."
+fi
+
+case ":${PATH}:" in
+  *":${GLOBAL_BIN}:"*)
+    ;;
+  *)
+    warn "\`${GLOBAL_BIN}\` is not on your PATH. Add this line to ~/.zshrc (or ~/.bashrc) and reopen your shell:"
+    warn "  export PATH=\"${GLOBAL_BIN}:\$PATH\""
+    ;;
+esac
+
+RESOLVED="$(command -v forge || true)"
+if [ -z "${RESOLVED}" ]; then
+  warn "Linked, but \`forge\` is not resolving on PATH yet. Try opening a new shell."
+  exit 0
+fi
+
+VERSION_OUT="$(forge --version 2>/dev/null || true)"
+say "Linked: ${RESOLVED}"
+[ -n "${VERSION_OUT}" ] && say "forge --version → ${VERSION_OUT}"
+
+cat <<EOF
+
+  Next:
+    forge init                         # create ~/.forge and ./.forge
+    forge run "add a /health endpoint" # first task
+    forge ui                           # launch the dashboard
+    forge doctor                       # health check
+
+  Unlink later with:  npm run unlink
+EOF

package/scripts/metrics.sh

@@ -0,0 +1,33 @@
+#!/usr/bin/env bash
+# Regenerate docs/metrics.json from the current source tree.
+# Every number cited in the docs comes from this script so claims are verifiable.
+set -euo pipefail
+cd "$(dirname "$0")/.."
+
+loc_total=$(find src -name "*.ts" | xargs wc -l | tail -1 | awk '{print $1}')
+loc_tests=$(find test -name "*.test.ts" | xargs wc -l | tail -1 | awk '{print $1}')
+test_files=$(find test -name "*.test.ts" | wc -l | tr -d ' ')
+test_count=$(npx vitest run --reporter=default 2>&1 | grep -E "Tests " | awk '{print $2}' | head -1)
+tools=$(ls src/tools/*.ts | grep -v registry | wc -l | tr -d ' ')
+cli_commands=$(ls src/cli/commands/*.ts | wc -l | tr -d ' ')
+providers=$(grep -l "implements ModelProvider\|extends OpenAIProvider" src/models/*.ts | wc -l | tr -d ' ')
+slash=$(grep -c "^    name:" src/cli/repl-commands.ts)
+ci_jobs=$(grep -cE "^  [a-z][a-z-]*:$" .github/workflows/ci.yml)
+release_jobs=$(grep -cE "^  [a-z][a-z-]*:$" .github/workflows/release.yml)
+agents=$(ls src/agents/*.ts | grep -v base | grep -v registry | wc -l | tr -d ' ')
+
+cat <<EOF
+loc_total        $loc_total
+loc_tests        $loc_tests
+test_files       $test_files
+test_count       $test_count
+tools            $tools
+cli_commands     $cli_commands
+providers        $providers
+slash            $slash
+ci_jobs          $ci_jobs
+release_jobs     $release_jobs
+agents           $agents
+EOF
+echo
+echo "Edit docs/metrics.json with these values to keep docs in sync."

package/scripts/postinstall.js

@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+'use strict';
+/**
+ * Post-install hook for `npm install -g @hoangsonw/forge`.
+ *
+ * 1. Creates the ~/.forge skeleton (idempotent).
+ * 2. If FORGE_BINARY_PATH is set, stops there — treat Forge as "run from
+ *    source" (useful in monorepos and CI).
+ * 3. If FORGE_SKIP_DOWNLOAD is set, stops there too (hermetic installs).
+ * 4. Otherwise downloads the platform binary from GitHub Releases, verifies
+ *    SHA-256 + signature, and installs to ~/.forge/bin/.
+ *
+ * We never fail `npm install` — any failure degrades to "use the compiled JS
+ * shipped with the package". The CLI shim handles the fallback.
+ */
+const os = require('os');
+const fs = require('fs');
+const path = require('path');
+
+const forgeHome = process.env.FORGE_HOME || path.join(os.homedir(), '.forge');
+const dirs = ['bin', 'models', 'memory', 'plugins', 'skills', 'agents', 'mcp', 'mcp/tokens', 'logs', 'global', 'projects'];
+try {
+  fs.mkdirSync(forgeHome, { recursive: true });
+  for (const d of dirs) fs.mkdirSync(path.join(forgeHome, d), { recursive: true });
+} catch (err) {
+  console.warn('[forge] postinstall: could not create ~/.forge:', String(err));
+  return;
+}
+
+if (process.env.FORGE_SKIP_DOWNLOAD === '1' || process.env.FORGE_BINARY_PATH) {
+  return;
+}
+
+// Binary download is attempted lazily by the CLI itself on first run. This
+// keeps npm install fast and avoids failing in air-gapped environments. See
+// src/release/download.ts.