Release 0.9.2 — npm + Docker distribution

First public release of @st-gr/sail-proxy. Highlights:

- CLI installable via `npm install -g @st-gr/sail-proxy`, with
  interactive setup that parses an SAP BTP AI Core service key into
  ~/.sail-proxy/.env. Defaults to deployment auto-discovery so
  `sail-proxy run` is functional after first-run.
- Gateway and ollama services bundled into the npm tarball with their
  production dependencies and @libs alias resolution. CLI's run/
  ollama-start spawn from the bundled layout.
- Provider APIs: OpenAI (chat + embeddings), Anthropic, OpenRouter,
  AWS Bedrock (invoke/converse, streaming variants), Ollama API
  compatibility on port 11434.
- API key + AWS credential management with persistent storage.
- Logs subsystem: tail, follow, since, clear.
- Docker images for gateway, admin, ollama, nginx.

Publish pipeline hardened against npm publish lifecycle pitfalls
(workspace: protocol rewriting, registry-manifest re-read after
pack, bundled-dep packaging, regression guards in publish-npm.js).

Author: st-gr

ci/ci-pipeline.js

@@ -91,7 +91,7 @@ async function parseDockerComposeConfig() {
       config.volumes.valkey = valkeyMatch[1];
     }
 
-    // Parse image names (format: "image: ${DOCKER_REGISTRY:-ghcr.io}/${DOCKER_ORGANIZATION:-st-gr}/sail-proxy-NAME:${DOCKER_TAG:-1.0.0}")
+    // Parse image names (format: "image: ${DOCKER_REGISTRY:-ghcr.io}/${DOCKER_ORGANIZATION:-st-gr}/sail-proxy-NAME:${DOCKER_TAG:-latest}")
     const imageRegex = /image:\s*\$\{DOCKER_REGISTRY:-([^}]+)\}\/\$\{DOCKER_ORGANIZATION:-([^}]+)\}\/(sail-proxy-\w+):\$\{DOCKER_TAG:-[^}]+\}/g;
     let match;
     while ((match = imageRegex.exec(content)) !== null) {

cli-tools/bundle-gateway-libs.js

@@ -0,0 +1,68 @@
+#!/usr/bin/env node
+
+/**
+ * Populate npm-dist/sail-proxy/bundled/gateway/node_modules/@libs/<name>/ from
+ * the already-bundled bundled/gateway/libs/<name>/ tree.
+ *
+ * The gateway's TypeScript sources use `import ... from '@libs/<name>'` and the
+ * tsconfig defines `paths: { "@libs/*": ["libs/*"] }`. tsc does not rewrite path
+ * aliases on emit, so the compiled JS still contains literal `require("@libs/...")`.
+ * In production the only way to resolve those without a runtime path-mapper is
+ * Node's standard module resolution — which means each lib must appear under
+ * `node_modules/@libs/<name>/`.
+ *
+ * The Docker image accomplishes this with a symlink (`ln -sf ./libs node_modules/@libs`).
+ * Internal symlinks in npm tarballs are unreliable cross-platform (Windows in
+ * particular), so this script does a real copy. Libs are tens of KB total.
+ *
+ * Must run AFTER `npm install --production` in bundled/gateway/, otherwise
+ * npm's pruning pass would strip our @libs entries as "extraneous".
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const projectRoot = path.resolve(__dirname, '..');
+const gatewayBundleDir = path.join(projectRoot, 'npm-dist', 'sail-proxy', 'bundled', 'gateway');
+const libsSrc = path.join(gatewayBundleDir, 'libs');
+const libsDst = path.join(gatewayBundleDir, 'node_modules', '@libs');
+
+function main() {
+  if (!fs.existsSync(libsSrc)) {
+    throw new Error(
+      `bundled/gateway/libs not found at ${libsSrc} — bundle:gateway must run before bundle:gateway-aliases.`
+    );
+  }
+
+  fs.rmSync(libsDst, { force: true, recursive: true });
+  fs.mkdirSync(libsDst, { recursive: true });
+
+  const entries = fs.readdirSync(libsSrc, { withFileTypes: true });
+  const copied = [];
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const src = path.join(libsSrc, entry.name);
+    const dst = path.join(libsDst, entry.name);
+    fs.cpSync(src, dst, { recursive: true });
+    copied.push(entry.name);
+  }
+
+  if (copied.length === 0) {
+    throw new Error(`No lib subdirectories found under ${libsSrc}`);
+  }
+
+  console.log(
+    `✅ Mirrored ${copied.length} libs into ${path.relative(projectRoot, libsDst)}: ${copied.join(', ')}`
+  );
+}
+
+if (require.main === module) {
+  try {
+    main();
+  } catch (err) {
+    console.error('❌ bundle-gateway-libs failed:', err.message);
+    process.exit(1);
+  }
+}
+
+module.exports = { main };

cli-tools/bundle-service-key-parser.js

@@ -0,0 +1,79 @@
+#!/usr/bin/env node
+
+/**
+ * Bundle libs/service-key-parser into npm-dist/sail-proxy as a real node_modules
+ * entry (not a symlink) so `npm pack` includes it via bundledDependencies.
+ *
+ * In a pnpm workspace, npm-dist/sail-proxy/node_modules/@sap-llm-gateway/service-key-parser
+ * is a symlink to ../../../../libs/service-key-parser. npm pack does not follow that
+ * external symlink even with bundledDependencies set, so the published tarball has
+ * no copy of the lib and `npm install @st-gr/sail-proxy` fails with E404 on the dep.
+ *
+ * This script replaces the symlink with a real directory containing only the built
+ * artifacts and a stripped package.json. pnpm install will re-link on next run.
+ */
+
+const { execSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+
+const projectRoot = path.resolve(__dirname, '..');
+const libDir = path.join(projectRoot, 'libs', 'service-key-parser');
+const targetDir = path.join(
+  projectRoot,
+  'npm-dist',
+  'sail-proxy',
+  'node_modules',
+  '@sap-llm-gateway',
+  'service-key-parser'
+);
+
+function main() {
+  if (!fs.existsSync(libDir)) {
+    throw new Error(`libs/service-key-parser not found at ${libDir}`);
+  }
+
+  execSync('pnpm build', { cwd: libDir, stdio: 'inherit' });
+
+  const distSrc = path.join(libDir, 'dist');
+  if (!fs.existsSync(distSrc)) {
+    throw new Error(`Build output missing: ${distSrc}`);
+  }
+
+  // Replace symlink (or stale dir) with a fresh real directory.
+  fs.rmSync(targetDir, { force: true, recursive: true });
+  fs.mkdirSync(targetDir, { recursive: true });
+
+  fs.cpSync(distSrc, path.join(targetDir, 'dist'), { recursive: true });
+
+  // Ship a minimal package.json — keep main/types/version, drop scripts/devDeps
+  // so npm install on the consumer side has nothing to run.
+  const libPkg = JSON.parse(fs.readFileSync(path.join(libDir, 'package.json'), 'utf8'));
+  const shipped = {
+    name: libPkg.name,
+    version: libPkg.version,
+    main: libPkg.main,
+    types: libPkg.types,
+    dependencies: libPkg.dependencies || {}
+  };
+  fs.writeFileSync(
+    path.join(targetDir, 'package.json'),
+    JSON.stringify(shipped, null, 2) + '\n',
+    'utf8'
+  );
+
+  console.log(
+    `✅ Bundled @sap-llm-gateway/service-key-parser@${libPkg.version} into ${path.relative(projectRoot, targetDir)}`
+  );
+}
+
+if (require.main === module) {
+  try {
+    main();
+  } catch (err) {
+    console.error('❌ bundle-service-key-parser failed:', err.message);
+    process.exit(1);
+  }
+}
+
+module.exports = { main };

cli-tools/publish-npm.js

@@ -0,0 +1,111 @@
+#!/usr/bin/env node
+
+/**
+ * Publish npm-dist/sail-proxy to npmjs.com.
+ *
+ * The bug this script defends against: npm publish (npm/cli's lib/commands/publish.js)
+ * re-reads package.json from disk AFTER pack() returns, and ships THAT manifest to
+ * the registry. If a postpack hook restores workspace:* between the tarball being
+ * built and the manifest being re-read, the tarball is correct but the registry
+ * metadata gets workspace:*, and `npm install` fails with EUNSUPPORTEDPROTOCOL.
+ *
+ * Defenses:
+ *   1. The npm-dist/sail-proxy package.json must NOT have a postpack hook that
+ *      restores workspace:* — verified below.
+ *   2. We pre-rewrite workspace:* before invoking npm publish (prepack does this
+ *      too, so it's defense in depth).
+ *   3. We verify the on-disk dependency state matches what we expect to ship,
+ *      ABORTING if any @sap-llm-gateway dep still has workspace:*.
+ *   4. The wrapper restores workspace:* in a finally block so the working tree
+ *      is clean whether publish succeeded, failed, or the user interrupted.
+ */
+
+const { execSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+
+const projectRoot = path.resolve(__dirname, '..');
+const pkgDir = path.join(projectRoot, 'npm-dist', 'sail-proxy');
+const pkgJsonPath = path.join(pkgDir, 'package.json');
+const prepareForPack = require('./prepare-for-pack');
+const restoreWorkspace = require('./restore-workspace-protocol');
+
+function run(cmd) {
+  execSync(cmd, { cwd: pkgDir, stdio: 'inherit' });
+}
+
+function readPkg() {
+  return JSON.parse(fs.readFileSync(pkgJsonPath, 'utf8'));
+}
+
+function assertNoPostpackHook() {
+  const pkg = readPkg();
+  if (pkg.scripts && pkg.scripts.postpack) {
+    throw new Error(
+      `Refusing to publish: npm-dist/sail-proxy/package.json has a postpack hook ` +
+      `(${pkg.scripts.postpack}). npm publish re-reads package.json from disk after ` +
+      `pack() runs, so a postpack hook that restores workspace:* will poison the ` +
+      `registry manifest while leaving the tarball correct. Remove the postpack ` +
+      `hook — the wrapper's finally block handles workspace:* restoration after ` +
+      `publish completes.`
+    );
+  }
+}
+
+function assertNoWorkspaceProtocol(stage) {
+  const pkg = readPkg();
+  const offenders = [];
+  for (const [name, version] of Object.entries(pkg.dependencies || {})) {
+    if (typeof version === 'string' && version.startsWith('workspace:')) {
+      offenders.push(`${name}: ${version}`);
+    }
+  }
+  if (offenders.length > 0) {
+    throw new Error(
+      `Refusing to publish: ${stage}, package.json still has workspace: protocol in ` +
+      `dependencies:\n  ${offenders.join('\n  ')}\n` +
+      `This is the exact state npm publish would re-read for the registry manifest. ` +
+      `Run prepare-for-pack.js or check that the prepack hook is wired up.`
+    );
+  }
+}
+
+let exitCode = 0;
+let cleanupNeeded = false;
+
+try {
+  run('npm run check-version');
+
+  // Defense 1: bail early if the postpack-restore footgun is back.
+  assertNoPostpackHook();
+
+  // Defense 2: rewrite workspace:* before npm publish reads the file.
+  prepareForPack.main();
+  cleanupNeeded = true;
+
+  // Defense 3: verify on-disk state is publishable.
+  // This is the same disk state npm's publish.js will re-read at line 112
+  // (after pack/postpack runs) for the registry manifest.
+  assertNoWorkspaceProtocol('after prepare-for-pack');
+
+  const extraArgs = process.argv.slice(2).join(' ');
+  run(`npm publish${extraArgs ? ' ' + extraArgs : ''}`);
+} catch (err) {
+  if (err && err.message && err.message.startsWith('Refusing to publish')) {
+    console.error('\n❌ ' + err.message);
+    exitCode = 1;
+  } else {
+    exitCode = typeof err.status === 'number' ? err.status : 1;
+  }
+} finally {
+  if (cleanupNeeded) {
+    try {
+      restoreWorkspace.main();
+    } catch (cleanupErr) {
+      console.error('⚠️  Cleanup (restore-workspace-protocol) failed:', cleanupErr.message);
+      if (exitCode === 0) exitCode = 1;
+    }
+  }
+}
+
+process.exit(exitCode);