Merge pull request #123 from linearis-oss/bugfix/fix-consumer-install-120

fix: replace postinstall with prepare to fix consumer install

Author: iamfj

.github/workflows/ci.yml

@@ -75,3 +75,28 @@ jobs:
 
       - name: TypeScript type check
         run: npx tsc --noEmit
+
+  smoke-test:
+    name: Smoke test package install
+    runs-on: ubuntu-latest
+    needs: [test]
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v6
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: 22
+          cache: "npm"
+
+      - name: Install deps
+        run: npm ci
+
+      - name: Pack and install
+        run: |
+          npm pack
+          npm install -g ./linearis-*.tgz
+          linearis --help
+          npm uninstall -g linearis

.github/workflows/publish.yml

@@ -60,7 +60,7 @@ jobs:
         run: npm test
 
       - name: Publish to npm
-        run: npm publish --provenance --access public
+        run: npx clean-publish --access public -- --provenance
         env:
           NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
 

AGENTS.md

@@ -20,7 +20,7 @@ For human contributor guidelines, see [CONTRIBUTING.md](CONTRIBUTING.md).
 ## Quick Commands
 
 ```bash
-npm install          # install deps + codegen + lefthook
+npm install          # install deps, codegen, and lefthook (via prepare hook)
 npm test             # unit tests (vitest)
 npm run build        # compile to dist/
 npm run generate     # regenerate GraphQL types from .graphql files
@@ -71,6 +71,7 @@ CLI Input → Command → Resolver → Service → JSON Output
 8. **Never edit `src/gql/`** — it is generated by codegen.
 9. **`USAGE.md` is generated and git-ignored** — produced by `npm run generate:usage` during build, included in the npm package but not committed.
 10. **Production dependencies must be pinned** to exact versions (no `^` or `~`). Dev dependencies may use ranges.
+11. **No `postinstall` scripts.** Use `prepare` for dev setup hooks (codegen, lefthook). Consumer installs must never execute dev-only commands.
 
 ## Decision Tree: Adding Functionality
 

CONTRIBUTING.md

@@ -21,7 +21,7 @@ Requires **Node.js >= 22**.
 ```bash
 git clone https://github.com/linearis-oss/linearis.git
 cd linearis
-npm install        # Install deps + GraphQL codegen + lefthook
+npm install        # Install deps, codegen, and lefthook (via prepare hook)
 npm start          # Development mode (tsx, no compilation)
 npm test           # Run tests
 npm run build      # Compile to dist/
@@ -41,6 +41,16 @@ npm run build          # Compile TypeScript (required before integration tests)
 
 Integration tests (`tests/integration/`) require `LINEAR_API_TOKEN` in your environment. They are skipped automatically when the token is absent.
 
+## Publishing
+
+To publish a new version locally (maintainers only):
+
+```bash
+npm run release    # Runs tests, builds, and publishes via clean-publish
+```
+
+In CI, publishing is handled automatically by the publish workflow when a version tag is pushed. The workflow uses `clean-publish` to strip dev artifacts (scripts, devDependencies, etc.) from the published package.
+
 ## Pull Requests
 
 1. Fork the repo and create your branch from `main`

package-lock.json

@@ -30,11 +30,11 @@
     "lint:check": "biome lint .",
     "check": "biome check --write .",
     "check:ci": "biome check .",
+    "release": "npm test && npm run build && npx clean-publish --access public",
     "prestart": "npm run generate",
     "predev": "npm run generate",
-    "postinstall": "npm run generate && lefthook install",
     "prebuild": "npm run generate && npm run generate:usage",
-    "prepare": "lefthook install",
+    "prepare": "npm run generate && lefthook install",
     "prepack": "npm run build",
     "prepublishOnly": "npm test"
   },
@@ -76,6 +76,7 @@
     "@types/node": "^24.0.0",
     "@vitest/coverage-v8": "^4.0.0",
     "@vitest/ui": "^4.0.0",
+    "clean-publish": "^6.0.5",
     "lefthook": "^2.1.0",
     "tsx": "^4.20.5",
     "typescript": "^6.0.0",
@@ -84,5 +85,11 @@
   "graphql": {
     "schema": "https://api.linear.app/graphql",
     "documents": "**/*.graphql"
+  },
+  "clean-publish": {
+    "fields": [
+      "scripts",
+      "graphql"
+    ]
   }
 }