aioffice 1.6.0

package/README.md

@@ -0,0 +1,112 @@
+# aioffice
+
+**AIOffice** is an AI-native command-line tool and [MCP](https://modelcontextprotocol.io)
+server for working with real Office documents — `.docx`, `.xlsx`, and `.pptx`.
+It creates, reads, queries, edits, renders, validates, and converts Office files
+through a single stable JSON surface designed for AI agents and scripts.
+
+This npm package is a thin installer: on install it downloads the correct
+self-contained native binary for your platform from the official
+[GitHub release](https://github.com/onecer/AIOffice/releases) and verifies it
+against the release's `SHA256SUMS`. There are no other dependencies.
+
+## Install
+
+Global install (adds an `aioffice` command to your PATH):
+
+```sh
+npm install -g aioffice
+aioffice version
+aioffice doctor
+```
+
+Or run on demand without installing, via `npx`:
+
+```sh
+npx aioffice doctor
+npx aioffice create report.docx --title "Q3 Report"
+```
+
+> On the first run, `npx` will download and SHA256-verify the native binary if
+> the postinstall step did not already do so.
+
+## Use as an MCP server
+
+AIOffice speaks MCP over stdio. Point your MCP client at the `aioffice mcp`
+command:
+
+```json
+{
+  "mcpServers": {
+    "aioffice": {
+      "command": "aioffice",
+      "args": ["mcp"]
+    }
+  }
+}
+```
+
+If you installed globally, `aioffice` resolves from your PATH. If you prefer not
+to install globally, use `npx` as the command instead:
+
+```json
+{
+  "mcpServers": {
+    "aioffice": {
+      "command": "npx",
+      "args": ["-y", "aioffice", "mcp"]
+    }
+  }
+}
+```
+
+The MCP transport is plain stdio JSON-RPC; the npm shim passes stdin/stdout
+through transparently.
+
+## How installation works
+
+1. `install.js` (run as a postinstall script) detects your platform and CPU
+   architecture and maps them to the matching release asset:
+
+   | OS / arch        | Asset                      |
+   | ---------------- | -------------------------- |
+   | macOS arm64      | `aioffice-mac-arm64`       |
+   | macOS x64        | `aioffice-mac-x64`         |
+   | Linux x64        | `aioffice-linux-x64`       |
+   | Linux arm64      | `aioffice-linux-arm64`     |
+   | Windows x64      | `aioffice-win-x64.exe`     |
+   | Windows arm64    | `aioffice-win-arm64.exe`   |
+
+2. It downloads `SHA256SUMS` and the binary from the release
+   `v{package version}`, computes the SHA256 of the download, and **refuses to
+   install** if it does not match the published checksum.
+3. On success the binary is placed in this package's `bin/` directory and made
+   executable (`chmod +x` on Unix). The install is idempotent — re-running it
+   skips work when a verified binary is already present.
+
+If the download or verification fails, installation aborts with a clear message
+that includes the direct download URL so you can install the binary manually.
+
+## Environment overrides
+
+Both are useful for testing or for serving binaries from a private mirror:
+
+| Variable                     | Default                                                           | Purpose                                  |
+| ---------------------------- | ---------------------------------------------------------------- | ---------------------------------------- |
+| `AIOFFICE_DOWNLOAD_VERSION`  | `v{package version}` (e.g. `v1.6.0`)                             | Release tag to download.                 |
+| `AIOFFICE_DOWNLOAD_BASEURL`  | `https://github.com/onecer/AIOffice/releases/download`           | Base URL for the assets + `SHA256SUMS`.  |
+
+The binary is fetched from `{BASEURL}/{VERSION}/{asset}` and the checksum file
+from `{BASEURL}/{VERSION}/SHA256SUMS`.
+
+```sh
+# Example: install a specific version from a local mirror
+AIOFFICE_DOWNLOAD_VERSION=v1.6.0 \
+AIOFFICE_DOWNLOAD_BASEURL=https://mirror.example.com/aioffice \
+npm install -g aioffice
+```
+
+## License
+
+Apache-2.0. See the [AIOffice repository](https://github.com/onecer/AIOffice)
+for source, full documentation, and the AI-facing surface contract.

package/bin/aioffice.js

@@ -0,0 +1,78 @@
+#!/usr/bin/env node
+'use strict';
+
+// bin/aioffice.js — thin launcher for the AIOffice native binary.
+//
+// Locates the downloaded binary (bin/aioffice[.exe]). If it is missing (e.g.
+// postinstall was skipped, as `npm` does with --ignore-scripts, or under some
+// `npx` flows), it runs the install step on demand, then spawns the binary
+// with the inherited argv and stdio (full pass-through). The child's exit code
+// is propagated. stdio:'inherit' keeps `aioffice mcp` (stdin/stdout JSON-RPC)
+// transparent.
+
+const path = require('path');
+const fs = require('fs');
+const { spawn } = require('child_process');
+
+const { binaryName } = require('../platform');
+
+const BINARY = path.join(__dirname, binaryName());
+
+function spawnBinary() {
+  if (!fs.existsSync(BINARY)) {
+    process.stderr.write(
+      'aioffice: native binary not found after install. ' +
+        'See messages above; you may need to reinstall or download it ' +
+        'manually from https://github.com/onecer/AIOffice/releases\n',
+    );
+    process.exit(1);
+  }
+
+  const child = spawn(BINARY, process.argv.slice(2), { stdio: 'inherit' });
+
+  child.on('error', (err) => {
+    process.stderr.write(`aioffice: failed to launch binary: ${err.message}\n`);
+    process.exit(1);
+  });
+
+  // Forward termination signals so Ctrl-C / kill reach the native process.
+  for (const sig of ['SIGINT', 'SIGTERM', 'SIGHUP']) {
+    process.on(sig, () => {
+      if (!child.killed) {
+        try {
+          child.kill(sig);
+        } catch (_) {
+          /* ignore */
+        }
+      }
+    });
+  }
+
+  child.on('exit', (code, signal) => {
+    if (signal) {
+      // Re-raise the signal so the parent's exit status reflects it.
+      process.kill(process.pid, signal);
+      return;
+    }
+    process.exit(code == null ? 0 : code);
+  });
+}
+
+async function main() {
+  if (!fs.existsSync(BINARY)) {
+    // Lazy install (postinstall was skipped or `npx` first run).
+    process.stderr.write('aioffice: binary not present, installing...\n');
+    try {
+      const install = require('../install');
+      await install.main();
+    } catch (err) {
+      process.stderr.write(
+        (err && err.message ? err.message : String(err)) + '\n',
+      );
+      process.exit(1);
+    }
+  }
+  spawnBinary();
+}
+
+main();

package/install.js

@@ -0,0 +1,239 @@
+'use strict';
+
+// install.js — postinstall step for the "aioffice" npm package.
+//
+// Downloads the platform-specific AIOffice binary from the matching GitHub
+// release, verifies it against the release's SHA256SUMS file, and installs it
+// (executable) into bin/. Uses ONLY Node builtins (https, fs, path, crypto) —
+// no third-party dependencies.
+//
+// Environment overrides (handy for testing + private mirrors):
+//   AIOFFICE_DOWNLOAD_VERSION  — release tag to download (default: v{package version})
+//   AIOFFICE_DOWNLOAD_BASEURL  — base URL for the release assets
+//                                (default: https://github.com/onecer/AIOffice/releases/download)
+//
+// The full asset URL is: {BASEURL}/{VERSION}/{asset}
+// and the checksum file:  {BASEURL}/{VERSION}/SHA256SUMS
+
+const fs = require('fs');
+const path = require('path');
+const https = require('https');
+const crypto = require('crypto');
+
+const { assetName, binaryName } = require('./platform');
+const pkg = require('./package.json');
+
+const DEFAULT_BASEURL = 'https://github.com/onecer/AIOffice/releases/download';
+const REPO_RELEASES = 'https://github.com/onecer/AIOffice/releases';
+
+const BIN_DIR = path.join(__dirname, 'bin');
+
+// Resolve the release tag. A bare package version "1.6.0" becomes "v1.6.0";
+// an explicit override is used verbatim (it may or may not carry a leading v).
+function resolveVersion() {
+  const override = process.env.AIOFFICE_DOWNLOAD_VERSION;
+  if (override && override.trim()) return override.trim();
+  return `v${pkg.version}`;
+}
+
+function resolveBaseUrl() {
+  const override = process.env.AIOFFICE_DOWNLOAD_BASEURL;
+  if (override && override.trim()) return override.trim().replace(/\/+$/, '');
+  return DEFAULT_BASEURL;
+}
+
+// GET a URL into a Buffer, following redirects (GitHub asset URLs 302 to a CDN).
+function fetchBuffer(url, redirectsLeft = 5) {
+  return new Promise((resolve, reject) => {
+    const req = https.get(
+      url,
+      { headers: { 'User-Agent': `aioffice-npm/${pkg.version}`, Accept: '*/*' } },
+      (res) => {
+        const { statusCode, headers } = res;
+        if (statusCode >= 300 && statusCode < 400 && headers.location) {
+          res.resume(); // drain
+          if (redirectsLeft <= 0) {
+            reject(new Error(`Too many redirects fetching ${url}`));
+            return;
+          }
+          const next = new URL(headers.location, url).toString();
+          resolve(fetchBuffer(next, redirectsLeft - 1));
+          return;
+        }
+        if (statusCode !== 200) {
+          res.resume();
+          reject(
+            new Error(
+              `Download failed (HTTP ${statusCode}) for ${url}`,
+            ),
+          );
+          return;
+        }
+        const chunks = [];
+        res.on('data', (c) => chunks.push(c));
+        res.on('end', () => resolve(Buffer.concat(chunks)));
+      },
+    );
+    req.on('error', reject);
+    req.setTimeout(120000, () => {
+      req.destroy(new Error(`Download timed out after 120s for ${url}`));
+    });
+  });
+}
+
+function sha256(buf) {
+  return crypto.createHash('sha256').update(buf).digest('hex');
+}
+
+// Parse a sha256sum-style file: lines of "<hex>␠␠<filename>".
+// Returns a Map of filename -> lowercase hex digest.
+function parseSha256Sums(text) {
+  const map = new Map();
+  for (const raw of text.split(/\r?\n/)) {
+    const line = raw.trim();
+    if (!line) continue;
+    const m = line.match(/^([0-9a-fA-F]{64})[\s*]+(.+)$/);
+    if (!m) continue;
+    map.set(m[2].trim(), m[1].toLowerCase());
+  }
+  return map;
+}
+
+async function main() {
+  const version = resolveVersion();
+  const baseUrl = resolveBaseUrl();
+  const asset = assetName(); // throws a clear error on unsupported platform
+  const localName = binaryName();
+  const dest = path.join(BIN_DIR, localName);
+
+  const assetUrl = `${baseUrl}/${version}/${asset}`;
+  const sumsUrl = `${baseUrl}/${version}/SHA256SUMS`;
+
+  fs.mkdirSync(BIN_DIR, { recursive: true });
+
+  // --- Idempotency: skip if a correct binary is already present. -----------
+  // We need the expected digest to know it's correct, so fetch SHA256SUMS
+  // first. If the network is unavailable but a binary already exists, trust it
+  // (a prior install verified it) rather than failing a re-run.
+  let sums;
+  try {
+    const sumsBuf = await fetchBuffer(sumsUrl);
+    sums = parseSha256Sums(sumsBuf.toString('utf8'));
+  } catch (err) {
+    if (fs.existsSync(dest) && fs.statSync(dest).size > 0) {
+      console.error(
+        `aioffice: could not fetch SHA256SUMS (${err.message}); ` +
+          'a binary is already installed, keeping it.',
+      );
+      return;
+    }
+    fail(
+      `Could not download the checksum file.\n  ${err.message}`,
+      version,
+      asset,
+      assetUrl,
+    );
+  }
+
+  const expected = sums.get(asset);
+  if (!expected) {
+    fail(
+      `Release ${version} has no checksum entry for "${asset}".\n` +
+        `  Known entries: ${[...sums.keys()].join(', ') || '(none)'}`,
+      version,
+      asset,
+      assetUrl,
+    );
+  }
+
+  if (fs.existsSync(dest) && fs.statSync(dest).size > 0) {
+    const have = sha256(fs.readFileSync(dest));
+    if (have === expected) {
+      ensureExecutable(dest);
+      console.log(
+        `aioffice: ${localName} already installed and verified (${version}).`,
+      );
+      return;
+    }
+    // Present but wrong (partial/stale download) — re-download below.
+    console.error('aioffice: existing binary failed verification, re-downloading.');
+  }
+
+  // --- Download the binary. -------------------------------------------------
+  console.log(`aioffice: downloading ${asset} (${version})...`);
+  let binBuf;
+  try {
+    binBuf = await fetchBuffer(assetUrl);
+  } catch (err) {
+    fail(
+      `Could not download the binary.\n  ${err.message}`,
+      version,
+      asset,
+      assetUrl,
+    );
+  }
+
+  // --- Verify SHA256 BEFORE writing the final file. ------------------------
+  const actual = sha256(binBuf);
+  if (actual !== expected) {
+    fail(
+      'SHA256 checksum mismatch — the download may be corrupt or tampered ' +
+        'with. Nothing was installed.\n' +
+        `  expected: ${expected}\n  actual:   ${actual}`,
+      version,
+      asset,
+      assetUrl,
+    );
+  }
+
+  // Write atomically: temp file -> rename.
+  const tmp = `${dest}.download-${process.pid}`;
+  fs.writeFileSync(tmp, binBuf);
+  fs.renameSync(tmp, dest);
+  ensureExecutable(dest);
+
+  console.log(
+    `aioffice: installed ${localName} (${version}), SHA256 verified.`,
+  );
+}
+
+function ensureExecutable(file) {
+  if (process.platform !== 'win32') {
+    try {
+      fs.chmodSync(file, 0o755);
+    } catch (_) {
+      /* best-effort */
+    }
+  }
+}
+
+function fail(message, version, asset, assetUrl) {
+  const lines = [
+    '',
+    'aioffice: installation failed.',
+    `  ${message.replace(/\n/g, '\n  ')}`,
+    '',
+    'You can download the binary manually from:',
+    `  ${assetUrl}`,
+    `  (release page: ${REPO_RELEASES}/tag/${version})`,
+    'then place it in this package\'s bin/ directory as ' +
+      `"${binaryName()}"` +
+      (process.platform === 'win32' ? '.' : ' and run chmod +x on it.'),
+    '',
+    'Env overrides: AIOFFICE_DOWNLOAD_VERSION, AIOFFICE_DOWNLOAD_BASEURL.',
+    '',
+  ];
+  const err = new Error(lines.join('\n'));
+  err.handled = true;
+  throw err;
+}
+
+// Allow `require('./install')` (used by the bin shim) to call main() directly.
+module.exports = { main, parseSha256Sums, resolveVersion, resolveBaseUrl };
+
+if (require.main === module) {
+  main().catch((err) => {
+    process.stderr.write((err && err.message ? err.message : String(err)) + '\n');
+    process.exit(1);
+  });
+}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "aioffice",
+  "version": "1.6.0",
+  "description": "AIOffice — an AI-native CLI + MCP server for creating, reading, editing, rendering and validating real Office documents (.docx/.xlsx/.pptx). Installs a single self-contained native binary downloaded and SHA256-verified from the GitHub release.",
+  "bin": {
+    "aioffice": "bin/aioffice.js"
+  },
+  "scripts": {
+    "postinstall": "node install.js"
+  },
+  "files": [
+    "bin/aioffice.js",
+    "install.js",
+    "platform.js"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/onecer/AIOffice.git"
+  },
+  "homepage": "https://github.com/onecer/AIOffice#readme",
+  "bugs": {
+    "url": "https://github.com/onecer/AIOffice/issues"
+  },
+  "keywords": [
+    "office",
+    "docx",
+    "xlsx",
+    "pptx",
+    "ooxml",
+    "mcp",
+    "ai",
+    "cli",
+    "word",
+    "excel",
+    "powerpoint",
+    "automation"
+  ],
+  "license": "Apache-2.0",
+  "author": "onecer"
+}

package/platform.js

@@ -0,0 +1,67 @@
+'use strict';
+
+// platform.js — maps the running platform to the GitHub release asset name and
+// to the local binary filename. This is the single source of truth for the
+// platform mapping; install.js and bin/aioffice.js both import it.
+//
+// Asset map (must match the names of the assets attached to each GitHub
+// release v{version}):
+//   darwin + arm64 -> aioffice-mac-arm64
+//   darwin + x64   -> aioffice-mac-x64
+//   linux  + x64   -> aioffice-linux-x64
+//   linux  + arm64 -> aioffice-linux-arm64
+//   win32  + x64   -> aioffice-win-x64.exe
+//   win32  + arm64 -> aioffice-win-arm64.exe
+
+// platform -> arch -> release asset name
+const ASSETS = {
+  darwin: {
+    arm64: 'aioffice-mac-arm64',
+    x64: 'aioffice-mac-x64',
+  },
+  linux: {
+    x64: 'aioffice-linux-x64',
+    arm64: 'aioffice-linux-arm64',
+  },
+  win32: {
+    x64: 'aioffice-win-x64.exe',
+    arm64: 'aioffice-win-arm64.exe',
+  },
+};
+
+/**
+ * The local filename the downloaded binary is stored under, inside bin/.
+ * Windows needs a .exe extension so the OS will execute it; every other
+ * platform uses a plain "aioffice".
+ * @param {string} [platform=process.platform]
+ * @returns {string}
+ */
+function binaryName(platform = process.platform) {
+  return platform === 'win32' ? 'aioffice.exe' : 'aioffice';
+}
+
+/**
+ * Resolve the GitHub release asset name for the given platform/arch.
+ * Throws a clear, actionable error on an unsupported combination.
+ * @param {string} [platform=process.platform]
+ * @param {string} [arch=process.arch]
+ * @returns {string} the release asset filename
+ */
+function assetName(platform = process.platform, arch = process.arch) {
+  const byArch = ASSETS[platform];
+  const asset = byArch && byArch[arch];
+  if (!asset) {
+    const supported = Object.entries(ASSETS)
+      .flatMap(([p, m]) => Object.keys(m).map((a) => `${p}/${a}`))
+      .join(', ');
+    throw new Error(
+      `aioffice: unsupported platform "${platform}/${arch}". ` +
+        `Supported: ${supported}. ` +
+        'If you believe this platform should be supported, please open an ' +
+        'issue at https://github.com/onecer/AIOffice/issues',
+    );
+  }
+  return asset;
+}
+
+module.exports = { ASSETS, assetName, binaryName };