Package for npm publish

.github/workflows/ci.yml

@@ -0,0 +1,32 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+jobs:
+  build-and-test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+
+      - run: bun install --frozen-lockfile
+
+      - run: bun run lint
+
+      - run: bun run tsc
+
+      - run: bun run format:check
+
+      - run: bun run build
+
+      - run: node scripts/smoke-test.mjs

.github/workflows/publish.yml

@@ -0,0 +1,35 @@
+name: Publish to npm
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          registry-url: "https://registry.npmjs.org"
+
+      - run: bun install --frozen-lockfile
+
+      - run: bun run lint
+
+      - run: bun run build
+
+      - run: node scripts/smoke-test.mjs
+
+      - run: npm publish --access public --provenance
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

.prettierignore

@@ -2,3 +2,4 @@ node_modules
 dist
 build
 bun.lock
+scripts/fixtures

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pensar AI, Inc.
+
+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 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.

README.md

@@ -22,6 +22,18 @@ Given a repository, Surface:
 | PHP                   | Laravel                                                                   |
 | Specs                 | OpenAPI / Swagger (JSON + YAML)                                           |
 
+## Install
+
+```bash
+# Global CLI
+npm install -g @pensar/surface
+# or
+bun add -g @pensar/surface
+
+# As a library
+npm install @pensar/surface
+```
+
 ## Usage
 
 ```bash
@@ -90,6 +102,20 @@ The `--json` output includes a summary block for quick consumption:
 }
 ```
 
+## Programmatic API
+
+```ts
+import { map, type MapResult, type EndpointInfo } from "@pensar/surface";
+
+const result: MapResult = map("./my-project", { includeInternal: false });
+
+for (const endpoint of result.endpoints) {
+  console.log(`${endpoint.method} ${endpoint.path} (${endpoint.framework})`);
+}
+```
+
+The package exports `map`, `impact`, `detectServices`, `findFunctions`, the formatters (`formatTable`, `formatJson`, `formatNdjson`, `formatMarkdown`, plus their `formatImpact*` siblings), and all public types from `src/index.ts`.
+
 ## Development
 
 Requires [Bun](https://bun.sh).
@@ -109,6 +135,12 @@ bun run lint
 
 # Format check
 bun run format:check
+
+# Build the npm publish bundle (dist/)
+bun run build
+
+# Smoke-test the built bundle
+bun run test:smoke
 ```
 
 ## Architecture

package.json

@@ -1,17 +1,42 @@
 {
-  "name": "surface",
+  "name": "@pensar/surface",
   "version": "0.1.0",
-  "module": "src/index.ts",
+  "description": "White-box endpoint discovery for source code repositories.",
+  "license": "MIT",
   "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
   "bin": {
-    "surface": "src/cli.ts"
+    "surface": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pensarai/surface.git"
   },
   "scripts": {
+    "build": "tsup && node scripts/postbuild.mjs",
     "lint": "eslint src/",
     "lint:fix": "eslint src/ --fix",
     "format": "prettier --write .",
     "format:check": "prettier --check .",
-    "tsc": "tsc --noEmit"
+    "tsc": "tsc --noEmit",
+    "test:smoke": "node scripts/smoke-test.mjs",
+    "prepublishOnly": "npm run build && npm run test:smoke"
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
@@ -21,6 +46,7 @@
     "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-unused-imports": "^4.4.1",
     "prettier": "^3.8.1",
+    "tsup": "^8.5.0",
     "typescript-eslint": "^8.57.1"
   },
   "peerDependencies": {

scripts/fixtures/tiny-express/index.js

@@ -0,0 +1,17 @@
+// Minimal Express app — used by scripts/smoke-test.mjs to exercise surface's
+// map() against a known-shape input. Two routes is enough: the smoke test
+// only asserts non-empty.
+
+const express = require("express");
+
+const app = express();
+
+app.get("/health", (req, res) => {
+  res.json({ ok: true });
+});
+
+app.post("/users", (req, res) => {
+  res.json({ created: true });
+});
+
+app.listen(3000);

scripts/fixtures/tiny-express/package.json

@@ -0,0 +1,9 @@
+{
+  "name": "tiny-express-fixture",
+  "version": "0.0.0",
+  "private": true,
+  "type": "commonjs",
+  "dependencies": {
+    "express": "^4.19.2"
+  }
+}

scripts/postbuild.mjs

@@ -0,0 +1,21 @@
+// Post-build: prepend a shebang to the CLI entry and mark it executable.
+// tsup's per-entry banner is awkward to drive from config — this is simpler.
+
+import { chmodSync, readFileSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { dirname } from "node:path";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const cliPath = resolve(here, "..", "dist", "cli.js");
+
+const SHEBANG = "#!/usr/bin/env node\n";
+
+const current = readFileSync(cliPath, "utf-8");
+const stripped = current.startsWith("#!")
+  ? current.slice(current.indexOf("\n") + 1)
+  : current;
+writeFileSync(cliPath, SHEBANG + stripped);
+chmodSync(cliPath, 0o755);
+
+console.log(`postbuild: shebang + +x applied to ${cliPath}`);

scripts/smoke-test.mjs

@@ -0,0 +1,49 @@
+// Smoke test: import the published bundle, run map() against a tiny fixture,
+// and confirm we get a non-empty endpoint set.
+//
+// Runs under Node (the consumer runtime). Gates `prepublishOnly` and CI so a
+// broken dist/ cannot reach npm.
+
+import { existsSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const distEntry = resolve(here, "..", "dist", "index.js");
+
+if (!existsSync(distEntry)) {
+  console.error(
+    `smoke-test: dist/index.js missing — run \`npm run build\` first`,
+  );
+  process.exit(1);
+}
+
+const { map } = await import(distEntry);
+
+if (typeof map !== "function") {
+  console.error(`smoke-test: expected map to be a function, got ${typeof map}`);
+  process.exit(1);
+}
+
+const fixture = resolve(here, "fixtures", "tiny-express");
+const result = map(fixture);
+
+if (!result || typeof result !== "object") {
+  console.error(`smoke-test: map() returned non-object: ${result}`);
+  process.exit(1);
+}
+
+const endpoints = result.endpoints;
+const count = endpoints?.size ?? endpoints?.length ?? 0;
+
+if (count === 0) {
+  console.error(
+    `smoke-test: expected at least one endpoint from tiny-express fixture, got 0`,
+  );
+  console.error(`  result keys: ${Object.keys(result).join(", ")}`);
+  process.exit(1);
+}
+
+console.log(
+  `smoke-test: OK — found ${count} endpoint(s) in tiny-express fixture`,
+);

src/cli.ts

@@ -1,7 +1,7 @@
 #!/usr/bin/env bun
 
 import { resolve } from "path";
-import { existsSync, readFileSync } from "fs";
+import { existsSync, readFileSync, writeFileSync } from "fs";
 import { execFileSync } from "child_process";
 import { mkdtempSync, rmSync } from "fs";
 import { tmpdir } from "os";
@@ -387,7 +387,7 @@ function resolveDiffText(args: ParsedArgs, targetPath: string): string | null {
 
 function writeOutput(output: string, path?: string) {
   if (path) {
-    Bun.write(path, output);
+    writeFileSync(path, output);
     console.error(`Results saved to ${path}`);
   } else {
     console.log(output);

tsup.config.ts

@@ -0,0 +1,16 @@
+import { defineConfig } from "tsup";
+
+export default defineConfig({
+  entry: {
+    index: "src/index.ts",
+    cli: "src/cli.ts",
+  },
+  format: ["esm"],
+  dts: true,
+  clean: true,
+  outDir: "dist",
+  target: "node18",
+  splitting: false,
+  sourcemap: false,
+  shims: false,
+});