Prepare factory package publish metadata (#370)

Author: khaliqgant

.workflow-artifacts/factory-p3-publish-prep/self-reflection.md

@@ -0,0 +1,67 @@
+# Factory P3 Publish Prep Self-Reflection
+
+## Changed files
+
+- `packages/factory-sdk/package.json`
+  - Renamed the package to `@agent-relay/factory`.
+  - Removed `private: true`.
+  - Switched package metadata to ESM publish shape with `type: "module"`, `main`, `types`, `exports`, `publishConfig.access`, `engines`, `files`, `bin`, and package-local `build`/`test` scripts.
+  - Kept the existing `esbuild` dev dependency because the legacy workspace passthrough `bin/fleet.mjs` remains in-tree for Pear until p4.
+- `packages/factory-sdk/tsconfig.build.json`
+  - Added the standalone `tsc` build config for `dist/`, declarations, declaration maps, and source maps.
+  - Set `composite: false` to override the inherited root Node tsconfig.
+- `packages/factory-sdk/bin/factory.mjs`
+  - Added the new publish-facing `factory` bin launcher that imports `dist/cli/fleet.js` and calls `main`.
+- `packages/factory-sdk/bin/fleet.mjs`
+  - Comment-only update: the legacy launcher still bundles raw TS for the Pear workspace passthrough, but the stale `type=commonjs` rationale was replaced.
+
+## Spec coverage
+
+- Covered the broker-narrowed p3 scope: `packages/factory-sdk/{package.json, tsconfig.build.json, bin/}`.
+- The package metadata now targets `@agent-relay/factory`, public access, ESM exports from `dist/`, and a publish files allowlist that includes `dist`, `bin/factory.mjs`, `package.json`, and `README.md`.
+- Build output is generated by `tsc -p tsconfig.build.json`.
+- The new publish bin is `factory` and points to `bin/factory.mjs`.
+- Conscious p4 deferrals under the broker override:
+  - Broker override quoted: "Pear continues consuming the local workspace package (no behavior change) until p4 swaps the dep" and declared file targets are restricted to the factory package files above.
+  - Issue acceptance #6 is not fully completed in this p3 work: `bin/fleet.mjs` is not removed and its esbuild bundling logic remains for Pear's current path-based workspace passthrough.
+  - Issue acceptance #7 is deferred: root scripts, `bin/pear.mjs`, and `src/main/factory-manager.ts` were intentionally not edited.
+  - Issue acceptance #9 via the new `factory.mjs` bin is deferred: `factory.mjs` is additive and currently fails under raw Node because Bundler-mode `tsc` preserves extensionless relative imports. Pear's existing behavior remains through unchanged `bin/fleet.mjs`.
+
+## Tests and proofs run
+
+- `npm run build -w @agent-relay/factory`
+  - Failed before running package build because root `package.json` has no workspace declaration and root metadata is out of scope.
+- `npm run build` from `packages/factory-sdk`
+  - Passed and emitted `dist/`.
+  - Confirmed `dist/index`, `dist/testing/index`, `dist/writeback/index`, and `dist/cli/fleet` each have `.js`, `.d.ts`, `.js.map`, and `.d.ts.map`.
+- `env -u AGENT_RELAY_BROKER_PID npx vitest run packages/factory-sdk`
+  - Failed because this relay worker also sets `AGENT_RELAY_STATE_DIR`, causing `protectedPids()` to include the live connection-file PID.
+- `env -u AGENT_RELAY_BROKER_PID -u AGENT_RELAY_STATE_DIR npx vitest run packages/factory-sdk`
+  - Passed: 28 test files, 455 tests.
+- `node packages/factory-sdk/bin/factory.mjs --help`
+  - Failed as expected with `ERR_MODULE_NOT_FOUND` for `dist/mount/local-mount-preflight`, documenting the p3/p4 Bundler-mode ESM seam.
+- `npm pack --dry-run -w @agent-relay/factory`
+  - Failed before packing because root workspace metadata is out of scope.
+- `npm pack --dry-run` from `packages/factory-sdk`
+  - Passed.
+  - Tarball includes `dist/`, `bin/factory.mjs`, `package.json`, and `README.md`.
+  - Confirmed `bin/fleet.mjs`, `src/`, tests, and tsconfig files are absent.
+- `npm publish --dry-run -w @agent-relay/factory --access public`
+  - Failed before publishing because root workspace metadata is out of scope.
+- `npm publish --dry-run --access public` from `packages/factory-sdk`
+  - Passed.
+  - npm warned that it would normalize `repository.url` to `git+https://github.com/AgentWorkforce/factory.git`.
+
+## Repo-rule alignment
+
+- Kept Pear behavior unchanged by leaving root scripts, `bin/pear.mjs`, and `src/main/factory-manager.ts` untouched.
+- Did not mass-rewrite source imports or alter package source files to make raw Node consume Bundler-mode output.
+- Did not publish `bin/fleet.mjs`; `files` uses `bin/factory.mjs` specifically.
+- Did not add placeholder dependencies or change root workspace metadata.
+- Generated `dist/` is ignored by the repo and is treated as verification output, not a tracked source change.
+
+## Remaining risks
+
+- `factory.mjs` is not raw-Node runnable until p4 resolves the extensionless import seam or changes the build/bundle strategy.
+- `npm -w @agent-relay/factory` commands require root workspace metadata, which is outside this step's declared targets.
+- If p4 ever publishes `bin/fleet.mjs`, `esbuild` must become a runtime dependency or the file must be deleted as planned.

packages/factory-sdk/bin/factory.mjs

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { dirname, join } from 'node:path'
+import { fileURLToPath, pathToFileURL } from 'node:url'
+const here = dirname(fileURLToPath(import.meta.url))
+const entry = join(here, '..', 'dist', 'cli', 'fleet.js')
+const mod = await import(pathToFileURL(entry).href)
+await mod.main(process.argv.slice(2))

packages/factory-sdk/bin/fleet.mjs

@@ -18,7 +18,7 @@ const cliArgs = rawArgs.filter((arg) => arg !== '--rebuild')
 
 mkdirSync(cacheDir, { recursive: true })
 
-// The SDK package is type=commonjs, so Node strip-types loads .ts as CJS and rejects ESM imports.
+// The workspace passthrough runs raw TS sources before p4 makes the dist CLI Node-runnable.
 // Bundle the thin CLI entry locally instead; esbuild is declared in this package for that launcher path.
 const { buildSync } = require('esbuild')
 const buildOptions = {

packages/factory-sdk/package.json

@@ -1,25 +1,21 @@
 {
-  "name": "@pear/factory-sdk",
-  "private": true,
-  "type": "commonjs",
-  "bin": {
-    "fleet": "bin/fleet.mjs"
-  },
-  "devDependencies": {
-    "esbuild": "^0.24.2"
-  },
+  "name": "@agent-relay/factory",
+  "version": "0.1.0",
+  "description": "Agent factory — triage, dispatch, merge-gate for relayfile-driven workspaces",
+  "license": "UNLICENSED",
+  "repository": { "type": "git", "url": "https://github.com/AgentWorkforce/factory" },
+  "type": "module",
+  "engines": { "node": ">=20" },
+  "publishConfig": { "access": "public" },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": ["dist", "bin/factory.mjs", "package.json", "README.md"],
+  "bin": { "factory": "bin/factory.mjs" },
   "exports": {
-    ".": {
-      "types": "./src/index.ts",
-      "default": "./src/index.ts"
-    },
-    "./testing": {
-      "types": "./src/testing/index.ts",
-      "default": "./src/testing/index.ts"
-    },
-    "./writeback": {
-      "types": "./src/writeback/index.ts",
-      "default": "./src/writeback/index.ts"
-    }
-  }
+    ".": { "types": "./dist/index.d.ts", "import": "./dist/index.js" },
+    "./testing": { "types": "./dist/testing/index.d.ts", "import": "./dist/testing/index.js" },
+    "./writeback": { "types": "./dist/writeback/index.d.ts", "import": "./dist/writeback/index.js" }
+  },
+  "scripts": { "build": "tsc -p tsconfig.build.json", "test": "vitest run" },
+  "devDependencies": { "esbuild": "^0.24.2" }
 }

packages/factory-sdk/tsconfig.build.json

@@ -0,0 +1,16 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "composite": false,
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "noEmit": false
+  },
+  "include": ["src/**/*"],
+  "exclude": ["**/*.test.ts", "**/__tests__/**", "src/testing/**/*.test.ts"]
+}