chore: configure scoped npm publishing

Author: newbe36524

.github/workflows/npm-publish-dev.yml

@@ -0,0 +1,65 @@
+name: Publish npm dev
+
+on:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: read
+  id-token: write
+
+concurrency:
+  group: npm-publish-dev-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  publish-dev:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: repos/imgbin
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: npm
+          cache-dependency-path: repos/imgbin/package-lock.json
+          registry-url: https://registry.npmjs.org
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build package
+        run: npm run build
+
+      - name: Run tests
+        run: npm test
+
+      - name: Prepare dev version
+        id: version
+        run: |
+          version="$(npm run --silent publish:prepare-dev-version)"
+          echo "version=$version" >> "$GITHUB_OUTPUT"
+          echo "Prepared dev version: $version"
+
+      - name: Verify packed files
+        run: npm run pack:check
+
+      - name: Publish to npm dev dist-tag
+        run: npm publish --tag dev --provenance --access public
+
+      - name: Summarize publish result
+        run: |
+          {
+            echo "## npm dev publish"
+            echo
+            echo "- Version: ${{ steps.version.outputs.version }}"
+            echo "- Dist-tag: dev"
+            echo "- Registry: npmjs.org"
+          } >> "$GITHUB_STEP_SUMMARY"

.github/workflows/npm-publish-release.yml

@@ -0,0 +1,66 @@
+name: Publish npm release
+
+on:
+  push:
+    tags:
+      - v*
+
+permissions:
+  contents: read
+  id-token: write
+
+concurrency:
+  group: npm-publish-release-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  publish-release:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: repos/imgbin
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: npm
+          cache-dependency-path: repos/imgbin/package-lock.json
+          registry-url: https://registry.npmjs.org
+
+      - name: Verify release tag matches package version
+        id: version
+        run: |
+          version="$(npm run --silent publish:verify-release -- "$GITHUB_REF_NAME")"
+          echo "version=$version" >> "$GITHUB_OUTPUT"
+          echo "Validated release version: $version"
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build package
+        run: npm run build
+
+      - name: Run tests
+        run: npm test
+
+      - name: Verify packed files
+        run: npm run pack:check
+
+      - name: Publish to npm latest dist-tag
+        run: npm publish --tag latest --provenance --access public
+
+      - name: Summarize publish result
+        run: |
+          {
+            echo "## npm stable publish"
+            echo
+            echo "- Version: ${{ steps.version.outputs.version }}"
+            echo "- Dist-tag: latest"
+            echo "- Tag: ${{ github.ref_name }}"
+            echo "- Registry: npmjs.org"
+          } >> "$GITHUB_STEP_SUMMARY"

README.md

@@ -27,6 +27,38 @@ You can bootstrap local configuration from the checked-in example:
 cp .env.example .env
 ```
 
+## Release automation
+
+ImgBin includes a GitHub Actions based npm publishing flow for both prerelease and stable channels.
+
+### Publishing channels
+
+- Pushes to `main` publish a unique prerelease build to the npm `dev` dist-tag.
+- Stable releases publish only from Git tags in the `vX.Y.Z` format and target the npm `latest` dist-tag.
+- The stable release workflow fails if the Git tag version does not exactly match `repos/imgbin/package.json`.
+
+### Trusted publishing prerequisites
+
+Before the workflows can publish successfully:
+
+1. configure npm trusted publishing for the `HagiCode-org/imgbin` GitHub repository,
+2. ensure the publishing package owner has access to the `@hagicode/imgbin` package on npm, and
+3. keep GitHub Actions enabled for the repository.
+
+The workflows are designed to publish with GitHub OIDC identity and provenance, not a long-lived `NPM_TOKEN`.
+
+### Local release verification
+
+Before pushing a release tag, run the same checks used by CI:
+
+```bash
+npm run build
+npm test
+npm run pack:check
+```
+
+For a stable release, update `package.json` to the target version first and then push a matching tag such as `v0.1.0`.
+
 ## Usage guide
 
 ### Quick start for the current HagiCode site workflow

package-lock.json

@@ -1,7 +1,15 @@
 {
-  "name": "imgbin",
+  "name": "@hagicode/imgbin",
   "version": "0.1.0",
   "description": "CLI tooling for generating, annotating, and indexing image assets.",
+  "homepage": "https://github.com/HagiCode-org/imgbin#readme",
+  "bugs": {
+    "url": "https://github.com/HagiCode-org/imgbin/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/HagiCode-org/imgbin.git"
+  },
   "type": "module",
   "bin": {
     "imgbin": "dist/cli.js"
@@ -15,6 +23,9 @@
     "build": "tsc -p tsconfig.json",
     "clean": "rm -rf dist .vitest-temp .tmp coverage",
     "dev": "tsx src/cli.ts",
+    "pack:check": "node scripts/verify-package.mjs",
+    "publish:prepare-dev-version": "node scripts/prepare-dev-version.mjs",
+    "publish:verify-release": "node scripts/verify-release-version.mjs",
     "test": "vitest run",
     "test:watch": "vitest"
   },
@@ -27,6 +38,11 @@
   "engines": {
     "node": ">=20"
   },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true,
+    "registry": "https://registry.npmjs.org/"
+  },
   "dependencies": {
     "commander": "^14.0.1",
     "dotenv": "^17.2.3",

package.json

@@ -0,0 +1,32 @@
+#!/usr/bin/env node
+
+import fs from "node:fs";
+import path from "node:path";
+import process from "node:process";
+
+const packageJsonPath = path.resolve(process.argv[2] ?? "package.json");
+const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, "utf8"));
+
+const match = String(packageJson.version).match(
+  /^(?<major>0|[1-9]\d*)\.(?<minor>0|[1-9]\d*)\.(?<patch>0|[1-9]\d*)(?:[-+].*)?$/,
+);
+
+if (!match?.groups) {
+  throw new Error(`Unsupported package version: ${packageJson.version}`);
+}
+
+const baseVersion = `${match.groups.major}.${match.groups.minor}.${match.groups.patch}`;
+const timestamp = new Date()
+  .toISOString()
+  .replace(/[-:]/g, "")
+  .replace("T", "")
+  .replace(/\.\d{3}Z$/, "");
+const runNumber = process.env.GITHUB_RUN_NUMBER ?? "0";
+const runAttempt = process.env.GITHUB_RUN_ATTEMPT ?? "0";
+const shortSha = (process.env.GITHUB_SHA ?? "local").slice(0, 7).toLowerCase();
+const devVersion = `${baseVersion}-dev.${timestamp}.${runNumber}.${runAttempt}.${shortSha}`;
+
+packageJson.version = devVersion;
+fs.writeFileSync(packageJsonPath, `${JSON.stringify(packageJson, null, 2)}\n`);
+
+process.stdout.write(devVersion);

scripts/prepare-dev-version.mjs

@@ -0,0 +1,40 @@
+#!/usr/bin/env node
+
+import fs from "node:fs";
+import path from "node:path";
+import process from "node:process";
+import { execFileSync } from "node:child_process";
+
+const repoRoot = path.resolve(process.argv[2] ?? ".");
+const packageJsonPath = path.join(repoRoot, "package.json");
+const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, "utf8"));
+const binPath = packageJson.bin?.imgbin;
+
+if (!binPath) {
+  throw new Error("package.json must define bin.imgbin before publishing.");
+}
+
+const resolvedBinPath = path.join(repoRoot, binPath);
+if (!fs.existsSync(resolvedBinPath)) {
+  throw new Error(`Missing built CLI entrypoint: ${binPath}`);
+}
+
+const npmCommand = process.platform === "win32" ? "npm.cmd" : "npm";
+const output = execFileSync(npmCommand, ["pack", "--dry-run", "--json"], {
+  cwd: repoRoot,
+  encoding: "utf8",
+});
+const [packSummary] = JSON.parse(output);
+const packedFiles = new Set((packSummary?.files ?? []).map((file) => file.path));
+const requiredFiles = [binPath, "README.md", "prompts/default-analysis-prompt.txt"];
+const missingFiles = requiredFiles.filter((file) => !packedFiles.has(file));
+
+if (missingFiles.length > 0) {
+  throw new Error(
+    `npm pack is missing required publish files: ${missingFiles.join(", ")}`,
+  );
+}
+
+process.stdout.write(
+  `Verified ${packSummary.name} with ${packSummary.files.length} packed files.\n`,
+);

scripts/verify-package.mjs

@@ -0,0 +1,33 @@
+#!/usr/bin/env node
+
+import fs from "node:fs";
+import path from "node:path";
+import process from "node:process";
+
+const tagName = process.argv[2] ?? process.env.GITHUB_REF_NAME;
+
+if (!tagName) {
+  throw new Error("Missing release tag. Pass a tag name or set GITHUB_REF_NAME.");
+}
+
+const match = String(tagName).match(
+  /^v(?<major>0|[1-9]\d*)\.(?<minor>0|[1-9]\d*)\.(?<patch>0|[1-9]\d*)$/,
+);
+
+if (!match?.groups) {
+  throw new Error(
+    `Release tags must use the stable vX.Y.Z format. Received: ${tagName}`,
+  );
+}
+
+const expectedVersion = `${match.groups.major}.${match.groups.minor}.${match.groups.patch}`;
+const packageJsonPath = path.resolve(process.argv[3] ?? "package.json");
+const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, "utf8"));
+
+if (packageJson.version !== expectedVersion) {
+  throw new Error(
+    `Tag ${tagName} does not match package.json version ${packageJson.version}.`,
+  );
+}
+
+process.stdout.write(expectedVersion);