fa-mcp-sdk 0.4.79 → 0.4.84

package/bin/fa-mcp.js

@@ -984,7 +984,8 @@ certificate's public and private keys`,
     const scriptsTargetPath = path.join(targetPath, 'scripts');
     await this.copyDirectory(path.join(PROJ_ROOT, 'scripts'), scriptsTargetPath);
     await fs.rm(path.join(targetPath, 'scripts/copy-static.js'), { force: true });
-    await fs.rm(path.join(targetPath, 'scripts/publish.sh'), { force: true });
+    await fs.rm(path.join(targetPath, 'scripts/publish.js'), { force: true });
+    await fs.rm(path.join(targetPath, 'scripts/publish-README.md'), { force: true });
 
     // Rename all .xml files in .run directory to .run.xml
     const runDirPath = path.join(targetPath, '.run');

package/cli-template/.claude/skills/upgrade-guide/SKILL.md

@@ -260,11 +260,11 @@ For any other changed template file, the generated guide must include:
 ### 4.4 Analyze changes in scripts
 
 The CLI copies scripts from `node_modules/fa-mcp-sdk/scripts/` (NOT from `cli-template/scripts/`) into the project's 
-`scripts/` directory, and then removes `copy-static.js` and `publish.sh` (SDK-internal, not needed in downstream projects).
+`scripts/` directory, and then removes `copy-static.js`, `publish.js`, `scripts/publish-README.md` (SDK-internal, not needed in downstream projects).
 
 - Canonical source: `node_modules/fa-mcp-sdk/scripts/<name>.js`
 - Project destination: `scripts/<name>.js`
-- Exclude from upgrade suggestions: `copy-static.js`, `publish.sh` (SDK-only)
+- Exclude from upgrade suggestions: `copy-static.js`, `publish.js`, `scripts/publish-README.md` (SDK-only)
 
 The generated guide must specify the exact source path under `node_modules/fa-mcp-sdk/scripts/...` for any script the 
 user should copy into their project's `scripts/` directory, and skip the excluded SDK-only scripts.

package/cli-template/package.json

@@ -54,7 +54,7 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
     "dotenv": "^17.4.1",
-    "fa-mcp-sdk": "^0.4.79"
+    "fa-mcp-sdk": "^0.4.84"
   },
   "devDependencies": {
     "@types/express": "^5.0.6",

package/cli-template/readme-docs/SKILLS.md

@@ -39,7 +39,7 @@ Generates a migration guide for upgrading the `fa-mcp-sdk` dependency in this pr
 - `config/*.yaml` — new/removed/changed keys and defaults (correlates `default.yaml`, `_local.yaml`, `local.yaml`)
 - `cli-template/` — `package.json` (new deps only), `tsconfig.json`, `.oxlintrc.json`, `.oxfmtrc.json`, `CLAUDE.md`, `deploy/`,
   `.claude/skills/`, `.run/` (from `r/`)
-- `scripts/` — new or updated SDK utilities (excluding SDK-internal `copy-static.js`, `publish.sh`)
+- `scripts/` — new or updated SDK utilities (excluding SDK-internal `copy-static.js`, `publish.js`, `scripts/publish-README.md`)
 - `dist/core/index.js` — added/removed/renamed exports and breaking type changes
 - project `src/` — imports and config keys affected by the upgrade
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "fa-mcp-sdk",
   "productName": "FA MCP SDK",
-  "version": "0.4.79",
+  "version": "0.4.84",
   "description": "Core infrastructure and templates for building Model Context Protocol (MCP) servers with TypeScript",
   "type": "module",
   "main": "dist/core/index.js",

package/scripts/publish-README.md

@@ -0,0 +1,69 @@
+# scripts/publish.js
+
+Cross-platform publish script. Bumps the patch version, commits the changes,
+pushes to `master`, and runs `npm publish`.
+
+## Usage
+
+```bash
+node scripts/publish.js              # default: bump + commit tracked changes + push + publish
+node scripts/publish.js --no-bump    # publish current version as-is, no bump
+node scripts/publish.js --add-all    # also include untracked files in the commit
+node scripts/publish.js --no-bump --add-all   # combine
+node scripts/publish.js --help
+```
+
+## Flags
+
+| Flag             | Short | Effect                                                                                 |
+|------------------|-------|----------------------------------------------------------------------------------------|
+| `--no-bump`      | `-n`  | Skip patch version bump. Publish the current `package.json` version as-is.             |
+| `--add-all`      | `-a`  | Stage untracked files too (`git add --all`). Default stages only tracked changes.      |
+| `--help`         | `-h`  | Show usage and exit.                                                                   |
+
+## Workflow
+
+1. **Branch check** — must be on `master`. Otherwise prints a warning and exits.
+2. **Build** — runs `npm run cb` (clean + build). Aborts on failure.
+3. **Version bump** (skipped with `--no-bump`):
+   - Reads current version from `package.json`.
+   - Increments patch: `0.4.79` → `0.4.80`.
+   - Writes new version into `package.json` (replaces first occurrence only).
+   - Updates the `fa-mcp-sdk` dependency line in `cli-template/package.json` to `"^<new-version>"`.
+4. **Stage changes**:
+   - Default: `git add -u` — stages modifications and deletions to **tracked** files only.
+   - With `--add-all`: `git add --all` — also stages untracked files.
+5. **Commit + push** — if anything is staged, commits with the version string as the message
+   (`--no-verify`, bypasses hooks) and pushes to `origin master`. If the index is empty, both steps are skipped.
+6. **Publish** — runs `npm publish`.
+7. **Pause** — waits for Enter before exiting (matches the original bash behavior for interactive runs).
+
+## What gets committed (default mode)
+
+| File state                                         | Committed by default? | With `--add-all`? |
+|----------------------------------------------------|-----------------------|-------------------|
+| Bumped `package.json` (tracked + modified)         | ✅ Yes                | ✅ Yes            |
+| Bumped `cli-template/package.json`                 | ✅ Yes                | ✅ Yes            |
+| Other tracked files you modified (no `git add`)    | ✅ Yes                | ✅ Yes            |
+| Tracked files you deleted (no `git add`)           | ✅ Yes                | ✅ Yes            |
+| Untracked files (new files, not in git)            | ❌ No                 | ✅ Yes            |
+| Files you already `git add`-ed manually            | ✅ Yes                | ✅ Yes            |
+
+Rationale: `git add -u` mirrors `git commit -a` semantics — pick up edits to tracked files but never silently include
+brand-new files. Use `--add-all` when you explicitly want untracked files in the release commit.
+
+## Edge cases
+
+- **Wrong branch** — script exits without making any changes. No bump, no publish.
+- **Build fails** — script aborts before version bump and before any git operations.
+- **Nothing staged** (e.g., `--no-bump` and clean working tree) — `git commit`/`push` are skipped,
+  but `npm publish` still runs. Useful for re-publishing a version that was rolled back on the registry.
+- **Pre-existing manual `git add`** — those files are also committed; the script does not reset the index.
+- **Re-running after a failed publish** — use `--no-bump` to avoid double-incrementing the version.
+
+## Errors and pause behavior
+
+On any failure (build, git, etc.) the script:
+1. Prints a red error line.
+2. Waits for Enter (so you can read the output when run via double-click in IDE/Explorer).
+3. Exits with code `0` (matches the original bash; keeps the terminal window open in interactive shells).

package/scripts/publish.js

@@ -0,0 +1,127 @@
+#!/usr/bin/env node
+/**
+ * Publish package to npm.
+ * Usage:
+ *   node scripts/publish.js            # bumps patch version, stages tracked modifications, commits, pushes, publishes
+ *   node scripts/publish.js --no-bump  # publishes current version as-is (no bump)
+ *   node scripts/publish.js --add-all  # also stages untracked files (git add --all)
+ *   node scripts/publish.js --help
+ *
+ * Default staging behavior: `git add -u` — modified tracked files go in (incl. the bumped package.json).
+ * Untracked files are ignored unless --add-all is passed.
+ */
+
+import { spawnSync, execSync } from 'child_process';
+import { readFileSync, writeFileSync } from 'fs';
+import { createInterface } from 'readline';
+
+const EXPECTED_BRANCH = 'master';
+
+const c = {
+  r: '\x1b[0;31m',
+  g: '\x1b[0;32m',
+  y: '\x1b[0;33m',
+  m: '\x1b[0;35m',
+  0: '\x1b[0m',
+};
+
+const args = process.argv.slice(2);
+const noBump = args.includes('--no-bump') || args.includes('-n');
+const addAll = args.includes('--add-all') || args.includes('-a');
+
+if (args.includes('--help') || args.includes('-h')) {
+  console.log('Usage: node scripts/publish.js [--no-bump|-n] [--add-all|-a]');
+  console.log('  --no-bump, -n   Publish current version without bumping the patch number');
+  console.log('  --add-all, -a   Also stage untracked files (git add --all).');
+  console.log('                  By default only modified tracked files are staged (git add -u).');
+  process.exit(0);
+}
+
+function pause(msg = 'Press Enter to continue ...') {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise((resolve) => rl.question(msg, () => {
+    rl.close();
+    resolve();
+  }));
+}
+
+async function abort(msg) {
+  console.error(`${c.r}${msg || '**** ERROR ****'}${c[0]}`);
+  process.exit(0);
+}
+
+function run(cmd) {
+  const result = spawnSync(cmd, { shell: true, stdio: 'inherit' });
+  return result.status ?? 1;
+}
+
+function bumpVersion() {
+  const pkgPath = 'package.json';
+  const pkgRaw = readFileSync(pkgPath, 'utf8');
+  const pkg = JSON.parse(pkgRaw);
+  const oldVersion = pkg.version;
+  console.log(`${c.m}**** Old version is ${c.g}${oldVersion}${c.m} ****${c[0]}`);
+
+  const [major = 0, minor = 0, patch = 0] = oldVersion.split('.').map(Number);
+  const newVersion = `${major}.${minor}.${patch + 1}`;
+
+  console.log(
+    `${c.m}**** Bumping version of ${c.g}${pkg.name}${c.m}: ${c.y}${oldVersion}${c.m} -> ${c.g}${newVersion}${c.m} ****${c[0]}`,
+  );
+
+  // Replace only the first occurrence (the package's own "version" field).
+  writeFileSync(pkgPath, pkgRaw.replace(oldVersion, newVersion));
+
+  // Update fa-mcp-sdk dependency in cli-template/package.json: "fa-mcp-sdk": "^X.Y.Z"
+  const tplPath = 'cli-template/package.json';
+  const tplRaw = readFileSync(tplPath, 'utf8');
+  writeFileSync(tplPath, tplRaw.replace(/("fa-mcp-sdk":\s*")\^?[^"]+(")/, `$1^${newVersion}$2`));
+
+  return newVersion;
+}
+
+async function main() {
+  let branchName;
+  try {
+    branchName = execSync('git symbolic-ref --short HEAD', { encoding: 'utf8' }).trim();
+  } catch {
+    await abort(`${c.y}**** Version will not be bumped since retcode is not equals 0 ****${c[0]}`);
+  }
+
+  if (branchName !== EXPECTED_BRANCH) {
+    console.log(
+      `${c.y}**** git branch should be ${c.m}{${EXPECTED_BRANCH}}${c.y}, current: ${c.m}${branchName}${c.y} ****${c[0]}`,
+    );
+    process.exit(0);
+  }
+
+  if (run('npm run cb') !== 0) {
+    await abort(`${c.y}**** Typescript build failed ****${c[0]}`);
+  }
+
+  let version;
+  if (noBump) {
+    version = JSON.parse(readFileSync('package.json', 'utf8')).version;
+    console.log(`${c.y}**** Skipping version bump, publishing current ${c.g}${version}${c.y} ****${c[0]}`);
+  } else {
+    version = bumpVersion();
+  }
+
+  // -u stages modifications/deletions to tracked files (incl. the bumped package.json files),
+  // but does NOT include untracked files. --add-all switches to `git add --all` (also untracked).
+  const stageCmd = addAll ? 'git add --all' : 'git add -u';
+  if (run(stageCmd) !== 0) await abort();
+
+  const staged = execSync('git diff --cached --name-only', { encoding: 'utf8' }).trim();
+  if (staged) {
+    if (run(`git commit --no-verify -m "${version}"`) !== 0) await abort();
+    if (run(`git push origin refs/heads/${EXPECTED_BRANCH}:${EXPECTED_BRANCH}`) !== 0) await abort();
+  } else {
+    console.log(`${c.y}**** Nothing staged, skipping git commit/push ****${c[0]}`);
+  }
+
+  run('npm publish');
+  process.exit(0);
+}
+
+main();

package/scripts/publish.sh

@@ -1,78 +0,0 @@
-#!/bin/bash
-
-expected_branch="master"
-
-c='\033[0;35m'
-y='\033[0;33m'
-r='\033[0;31m'
-c0='\033[0;0m'
-g='\033[0;32m'
-
-echo_r() { /bin/echo -e ${r}"$1"${c0};  };
-
-# shellcheck disable=SC2120
-exit_on_error(){
-  if [[ $? -ne 0 ]] ; then
-    if [[ -n "$1" ]]; then
-      echo_r "$1";
-    else
-      echo -e "${r}**** ERROR ****${c0}"
-    fi;
-    read -p "Press any key to resume ..."
-    exit 0
-  fi
-}
-
-set +e
-
-branch_name=$(git symbolic-ref --short HEAD)
-exit_on_error "$y**** Version will not be bumped since retcode is not equals 0 ****$c0"
-
-if [[ "$branch_name" != "$expected_branch" ]] ; then
-  echo -e "${y}**** git branch should be ${c}{$expected_branch}${y}, current: ${c}${branch_name}${y}  ****$c0"
-  read -p "Press any key to resume ..."
-  exit 0
-fi
-
-npm run cb
-exit_on_error "$y**** Typescript build failed ****$c0"
-
-old_version=''
-new_version=''
-
-update_version(){
-    old_version=`cat package.json | grep version | head -1 | awk -F: '{ print $2 }' | sed 's/[\",]//g' | tr -d '[[:space:]]'`
-    echo -e "$c**** Old version is $g$old_version$c ****$c0"
-    version_split=( ${old_version//./ } )
-    major=${version_split[0]:-0}
-    minor=${version_split[1]:-0}
-    patch=${version_split[2]:-0}
-    let "patch=patch+1"
-    new_version="${major}.${minor}.${patch}"
-
-    repo=`cat package.json | grep name | head -1 | awk -F: '{ print $2 }' | sed 's/[\",]//g' | tr -d '[[:space:]]'`
-    echo -e "$c**** Bumping version of $g$repo$c: $y$old_version$c -> $g$new_version$c  ****$c0"
-    sed -i -e "0,/$old_version/s/$old_version/$new_version/" package.json
-    # Update the dependency version in cli-template/package.json: "fa-mcp-sdk": "^<new_version>"
-    # Version match is built on a regular expression that allows any current version (with an optional ^)
-    sed -i -E "s/(\"fa-mcp-sdk\":\s*\")\^?[^\"]+(\"[,\r\n\s]*)/\1^${new_version}\2/" cli-template/package.json
-    echo -e "$g"
-    npm version 2>&1 | head -2 | tail -1
-    echo -e "$c0"
-}
-
-
-update_version
-exit_on_error
-
-git add --all
-exit_on_error
-
-git commit --no-verify -m "$new_version"
-exit_on_error
-
-git push origin refs/heads/${expected_branch}:${expected_branch}
-exit_on_error
-# npm pack --dry-run
-npm publish
-read -p "Press any key to resume ..."