@ium/tfy-cli 0.1.0-preview.0

package/README.md

@@ -0,0 +1,54 @@
+# TFY CLI Developer Preview
+
+This npm package installs the `tfy` command for TFY Developer Preview dogfood/testing.
+
+Install preview builds explicitly:
+
+```sh
+npm install -g @ium/tfy-cli@preview
+```
+
+Name mapping:
+
+| Layer | Name |
+| --- | --- |
+| npm package | `@ium/tfy-cli` |
+| Installed command | `tfy` |
+| Rust CLI crate | `tfy-cli` |
+
+TFY uses two public install channels only:
+
+- Stable channel: `@ium/tfy-cli` resolves to the most tested release through the npm `latest` dist-tag.
+- Public-test channel: `@ium/tfy-cli@preview` resolves to the newest public testing build with current development work included.
+
+Exact versions remain installable with standard npm syntax, for example `@ium/tfy-cli@0.1.1` or `@ium/tfy-cli@0.1.1-preview.0`; npm version installs use `@<version>`, not `/v<version>`.
+
+Supported prebuilt npm/GitHub Release platforms:
+
+| OS | Architecture | Rust target | npm prebuilt |
+| --- | --- | --- | --- |
+| macOS | Apple Silicon arm64 | `aarch64-apple-darwin` | yes |
+| Linux | x64 | `x86_64-unknown-linux-gnu` | yes |
+| Linux | arm64 | `aarch64-unknown-linux-gnu` | yes |
+| Windows | x64 | `x86_64-pc-windows-msvc` | yes |
+
+Intel Mac (`darwin:x64` / `x86_64-apple-darwin`) is not provided as a prebuilt npm/GitHub Release archive. Intel Mac users can still build from source with `git clone https://github.com/ium-team/tfy && cd tfy && cargo install --path crates/tfy-cli`, or run a locally built binary by setting `TFY_BINARY_PATH`.
+
+
+The npm package name is `@ium/tfy-cli` and differs from the command name because the unscoped `tfy` npm package is already occupied and unscoped `tfy-cli` is blocked by npm similarity policy. The installed executable remains `tfy`.
+
+This is not GA/production-ready. TFY does not claim private Codex hook interception, provider prompt proxying, editor auto-hooks, or universal terminal interception. Setup success is not token-savings success; route-bound raw/ledger/no-negative/positive-savings evidence is still required.
+
+The installer downloads from the matching GitHub Release tag and verifies the `.sha256` file before installing. Preview versions keep the full preview tag, for example `v0.1.1-preview.0`, while release asset names use the base version, for example `tfy-0.1.1-linux-x86_64.tar.gz`.
+
+
+## Publishing note
+
+This package intentionally defaults `publishConfig.tag` to `preview` so accidental `npm publish` does not promote a public-test build to stable. Maintainers should run the root helper before publishing:
+
+```sh
+node scripts/npm-publish-plan.js --version 0.1.1-preview.0 --channel preview --source-ref develop
+node scripts/npm-publish-plan.js --version 0.1.1 --channel stable --source-ref main
+```
+
+The helper validates the channel/version/source metadata and prints the exact `npm publish` command; it does not publish.

package/bin/tfy.js

@@ -0,0 +1,60 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+const { currentPlatform } = require('../scripts/lib/platform');
+
+const root = path.resolve(__dirname, '..');
+
+function resolveLauncherBinary(options = {}) {
+  const env = options.env || process.env;
+  if (env.TFY_BINARY_PATH) return { binary: env.TFY_BINARY_PATH, target: null };
+  const target = currentPlatform({ platform: options.platform, arch: options.arch });
+  return {
+    binary: path.join(root, 'vendor', target.rustTarget, target.binName),
+    target
+  };
+}
+
+function main(argv = process.argv.slice(2), options = {}) {
+  const env = options.env || process.env;
+  let resolved;
+  try {
+    resolved = resolveLauncherBinary({ env, platform: options.platform, arch: options.arch });
+  } catch (error) {
+    process.stderr.write(`[tfy] ${error.message}\n`);
+    process.stderr.write('[tfy] set TFY_BINARY_PATH to a built tfy binary if you want to run from source on this platform.\n');
+    process.exit(127);
+  }
+
+  const { binary, target } = resolved;
+  if (!fs.existsSync(binary)) {
+    const platformLabel = target ? target.key : 'TFY_BINARY_PATH';
+    process.stderr.write(`[tfy] missing TFY binary for ${platformLabel}: ${binary}\n`);
+    process.stderr.write('[tfy] reinstall the package or set TFY_BINARY_PATH to a built tfy binary.\n');
+    process.exit(127);
+  }
+
+  const result = spawnSync(binary, argv, {
+    stdio: 'inherit',
+    shell: process.platform === 'win32' && /\.(cmd|bat)$/i.test(binary)
+  });
+  if (result.error) {
+    process.stderr.write(`[tfy] failed to execute ${binary}: ${result.error.message}\n`);
+    process.exit(127);
+  }
+  if (result.signal) {
+    process.kill(process.pid, result.signal);
+  } else {
+    process.exit(result.status === null ? 1 : result.status);
+  }
+}
+
+if (require.main === module) main();
+
+module.exports = {
+  main,
+  resolveLauncherBinary
+};

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@ium/tfy-cli",
+  "version": "0.1.0-preview.0",
+  "description": "TFY Developer Preview CLI installer. Installs the `tfy` command; not GA.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ium-team/tfy.git"
+  },
+  "homepage": "https://github.com/ium-team/tfy#readme",
+  "bugs": {
+    "url": "https://github.com/ium-team/tfy/issues"
+  },
+  "keywords": [
+    "tfy",
+    "cli",
+    "ai-agent",
+    "token-saving",
+    "developer-preview"
+  ],
+  "bin": {
+    "tfy": "bin/tfy.js"
+  },
+  "scripts": {
+    "postinstall": "node scripts/install.js",
+    "test": "node test/platform.test.js && node test/checksum.test.js && node test/install.test.js && node test/launcher.test.js && node test/release.test.js"
+  },
+  "files": [
+    "bin/",
+    "scripts/",
+    "vendor/",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "tag": "preview"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}

package/scripts/install.js

@@ -0,0 +1,210 @@
+#!/usr/bin/env node
+'use strict';
+
+const crypto = require('crypto');
+const fs = require('fs');
+const https = require('https');
+const os = require('os');
+const path = require('path');
+const { spawnSync } = require('child_process');
+const { currentPlatform, archiveName, cleanVersion } = require('./lib/platform');
+const { parseChecksum } = require('./lib/checksum');
+
+const root = path.resolve(__dirname, '..');
+const pkg = require(path.join(root, 'package.json'));
+const DEFAULT_DOWNLOAD_TIMEOUT_MS = 30_000;
+const DEFAULT_REDIRECT_LIMIT = 5;
+
+function log(message) {
+  process.stderr.write(`[tfy installer] ${message}\n`);
+}
+
+function fail(message) {
+  process.stderr.write(`[tfy installer] error: ${message}\n`);
+  process.exit(1);
+}
+
+function sha256(file) {
+  const hash = crypto.createHash('sha256');
+  hash.update(fs.readFileSync(file));
+  return hash.digest('hex');
+}
+
+function ensureExecutable(file) {
+  if (process.platform !== 'win32') fs.chmodSync(file, 0o755);
+}
+
+function defaultInstallPaths(platformTarget) {
+  const vendorDir = path.join(root, 'vendor', platformTarget.rustTarget);
+  return { vendorDir, installedBin: path.join(vendorDir, platformTarget.binName) };
+}
+
+function manualInstallDestination(source) {
+  const name = path.basename(source) || (process.platform === 'win32' ? 'tfy.exe' : 'tfy');
+  return path.join(root, 'vendor', 'manual', name);
+}
+
+function copyLocalBinary(source, destination = manualInstallDestination(source)) {
+  if (!fs.existsSync(source)) throw new Error(`TFY_BINARY_PATH does not exist: ${source}`);
+  fs.mkdirSync(path.dirname(destination), { recursive: true });
+  fs.copyFileSync(source, destination);
+  ensureExecutable(destination);
+  log(`installed local TFY binary from ${source}`);
+  return destination;
+}
+
+function installLocalBinary(source, options = {}) {
+  const resolvedSource = path.resolve(source);
+  let destination = options.destinationBinary;
+  if (!destination) {
+    try {
+      const platformTarget = options.platformTarget || currentPlatform(options);
+      destination = defaultInstallPaths(platformTarget).installedBin;
+    } catch (error) {
+      destination = manualInstallDestination(resolvedSource);
+      log(`${error.message}; copied local binary to ${destination}. Set TFY_BINARY_PATH at runtime on unsupported platforms.`);
+    }
+  }
+  return copyLocalBinary(resolvedSource, destination);
+}
+
+function canonicalReleaseBase(version) {
+  const cleanVersion = String(version).replace(/^v/, '');
+  return `https://github.com/ium-team/tfy/releases/download/v${cleanVersion}`;
+}
+
+function defaultReleaseVersion(version) {
+  return cleanVersion(version);
+}
+
+function releaseUrls(version, platformTarget) {
+  const asset = archiveName(version, platformTarget);
+  const base = canonicalReleaseBase(version);
+  const archiveUrl = `${base}/${asset}`;
+  return { asset, archiveUrl, checksumUrl: `${archiveUrl}.sha256` };
+}
+
+function download(url, destination, options = {}) {
+  const timeoutMs = options.timeoutMs ?? DEFAULT_DOWNLOAD_TIMEOUT_MS;
+  const redirectLimit = options.redirectLimit ?? DEFAULT_REDIRECT_LIMIT;
+  return new Promise((resolve, reject) => {
+    function fetch(currentUrl, remainingRedirects) {
+      const request = https.get(currentUrl, response => {
+        if ([301, 302, 303, 307, 308].includes(response.statusCode)) {
+          response.resume();
+          if (remainingRedirects <= 0) return reject(new Error(`too many redirects downloading ${url}`));
+          if (!response.headers.location) return reject(new Error(`redirect missing Location for ${currentUrl}`));
+          const nextUrl = new URL(response.headers.location, currentUrl).toString();
+          return fetch(nextUrl, remainingRedirects - 1);
+        }
+        if (response.statusCode !== 200) {
+          response.resume();
+          return reject(new Error(`download failed ${response.statusCode}: ${currentUrl}`));
+        }
+        const out = fs.createWriteStream(destination, { flags: 'wx' });
+        response.pipe(out);
+        out.on('finish', () => out.close(resolve));
+        out.on('error', reject);
+      });
+      request.setTimeout(timeoutMs, () => request.destroy(new Error(`download timed out: ${currentUrl}`)));
+      request.on('error', reject);
+    }
+    fetch(url, redirectLimit);
+  });
+}
+
+function normalizeArchiveEntry(entry) {
+  return String(entry).replace(/\\/g, '/').replace(/^\.\//, '');
+}
+
+function validateArchiveEntries(entries, platformTarget) {
+  const normalized = entries.map(normalizeArchiveEntry).filter(Boolean);
+  if (normalized.length !== 1 || normalized[0] !== platformTarget.binName) {
+    throw new Error(`archive must contain only ${platformTarget.binName}; found: ${normalized.join(', ') || '(empty)'}`);
+  }
+  const entry = normalized[0];
+  if (path.posix.isAbsolute(entry) || entry.split('/').includes('..')) {
+    throw new Error(`unsafe archive entry: ${entry}`);
+  }
+  return entry;
+}
+
+function listArchiveEntries(archivePath) {
+  const listed = spawnSync('tar', ['-tzf', archivePath], { encoding: 'utf8' });
+  if (listed.status !== 0) {
+    throw new Error(`failed to inspect archive ${archivePath}: ${(listed.stderr || '').trim()}`);
+  }
+  return listed.stdout.split(/\r?\n/).filter(Boolean);
+}
+
+function installVerifiedArchive({ archivePath, checksumPath, asset, platformTarget, vendorDirectory, destinationBinary }) {
+  const expected = parseChecksum(fs.readFileSync(checksumPath, 'utf8'), asset);
+  const actual = sha256(archivePath);
+  if (actual !== expected) throw new Error(`checksum mismatch for ${asset}: expected ${expected}, got ${actual}`);
+
+  validateArchiveEntries(listArchiveEntries(archivePath), platformTarget);
+  const extractDir = fs.mkdtempSync(path.join(os.tmpdir(), 'tfy-extract-'));
+  const extractedPath = path.join(extractDir, platformTarget.binName);
+  const tar = spawnSync('tar', ['-xzf', archivePath, '-C', extractDir], { stdio: 'inherit' });
+  if (tar.status !== 0) throw new Error(`failed to extract ${asset} with tar`);
+  const realExtractRoot = fs.realpathSync(extractDir);
+  const realExtractedParent = fs.realpathSync(path.dirname(extractedPath));
+  if (realExtractedParent !== realExtractRoot) throw new Error(`archive extracted outside temp directory: ${platformTarget.binName}`);
+  const stat = fs.lstatSync(extractedPath);
+  if (!stat.isFile() || stat.isSymbolicLink()) throw new Error(`archive entry is not a regular binary file: ${platformTarget.binName}`);
+
+  fs.mkdirSync(vendorDirectory, { recursive: true });
+  fs.copyFileSync(extractedPath, destinationBinary);
+  ensureExecutable(destinationBinary);
+}
+
+async function installFromRelease(options = {}) {
+  const platformTarget = options.platformTarget || currentPlatform(options);
+  const version = defaultReleaseVersion(options.version || process.env.TFY_RELEASE_VERSION || pkg.version);
+  const { asset, archiveUrl, checksumUrl } = releaseUrls(version, platformTarget);
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'tfy-npm-'));
+  const archivePath = path.join(tmp, asset);
+  const checksumPath = `${archivePath}.sha256`;
+  const downloadFile = options.downloadFile || download;
+  const defaults = defaultInstallPaths(platformTarget);
+  const vendorDirectory = options.vendorDirectory || defaults.vendorDir;
+  const destinationBinary = options.destinationBinary || defaults.installedBin;
+  log(`downloading ${archiveUrl}`);
+  await downloadFile(archiveUrl, archivePath);
+  await downloadFile(checksumUrl, checksumPath);
+  installVerifiedArchive({ archivePath, checksumPath, asset, platformTarget, vendorDirectory, destinationBinary });
+  log(`installed ${destinationBinary}`);
+}
+
+async function main() {
+  if (process.env.TFY_SKIP_INSTALL === '1') {
+    log('TFY_SKIP_INSTALL=1; skipping binary install');
+    return;
+  }
+  if (process.env.TFY_BINARY_PATH) {
+    installLocalBinary(process.env.TFY_BINARY_PATH);
+    return;
+  }
+  await installFromRelease();
+}
+
+if (require.main === module) {
+  main().catch(error => fail(error.message));
+}
+
+module.exports = {
+  canonicalReleaseBase,
+  copyLocalBinary,
+  defaultInstallPaths,
+  defaultReleaseVersion,
+  download,
+  installFromRelease,
+  installLocalBinary,
+  manualInstallDestination,
+  installVerifiedArchive,
+  listArchiveEntries,
+  normalizeArchiveEntry,
+  releaseUrls,
+  sha256,
+  validateArchiveEntries
+};

package/scripts/lib/checksum.js

@@ -0,0 +1,18 @@
+'use strict';
+
+function parseChecksum(text, asset) {
+  const expectedName = String(asset);
+  for (const line of String(text).split(/\r?\n/)) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    const parts = trimmed.split(/\s+/);
+    const hash = parts[0];
+    if (!/^[a-fA-F0-9]{64}$/.test(hash || '')) continue;
+    if (parts.length === 1) return hash.toLowerCase();
+    const filename = parts.slice(1).join(' ').replace(/^\*/, '');
+    if (filename === expectedName) return hash.toLowerCase();
+  }
+  throw new Error(`No checksum entry found for ${asset}`);
+}
+
+module.exports = { parseChecksum };

package/scripts/lib/platform.js

@@ -0,0 +1,82 @@
+'use strict';
+
+const SUPPORTED = new Map([
+  ['darwin:arm64', { platform: 'darwin', arch: 'arm64', rustTarget: 'aarch64-apple-darwin', archivePlatform: 'darwin', archiveArch: 'arm64', binName: 'tfy' }],
+  ['linux:x64', { platform: 'linux', arch: 'x64', rustTarget: 'x86_64-unknown-linux-gnu', archivePlatform: 'linux', archiveArch: 'x86_64', binName: 'tfy' }],
+  ['linux:arm64', { platform: 'linux', arch: 'arm64', rustTarget: 'aarch64-unknown-linux-gnu', archivePlatform: 'linux', archiveArch: 'arm64', binName: 'tfy' }],
+  ['win32:x64', { platform: 'win32', arch: 'x64', rustTarget: 'x86_64-pc-windows-msvc', archivePlatform: 'windows', archiveArch: 'x86_64', binName: 'tfy.exe' }]
+]);
+
+function cloneTarget(key, target) {
+  return { ...target, key };
+}
+
+function sourceBuildGuidance() {
+  return 'Intel Mac prebuilt npm installs are not currently provided. Build from source with `git clone https://github.com/ium-team/tfy && cd tfy && cargo install --path crates/tfy-cli`, or set TFY_BINARY_PATH to a built tfy binary.';
+}
+
+function supportedPlatformList() {
+  return Array.from(SUPPORTED.keys()).join(', ');
+}
+
+function unsupportedPlatformMessage(platform, arch) {
+  const key = `${platform}:${arch}`;
+  return `Unsupported TFY npm platform ${key}. Supported prebuilt platforms: ${supportedPlatformList()}. ${sourceBuildGuidance()}`;
+}
+
+function currentPlatform(options = {}) {
+  return resolvePlatform(options.platform || process.platform, options.arch || process.arch);
+}
+
+function resolvePlatform(platform, arch) {
+  const key = `${platform}:${arch}`;
+  const resolved = SUPPORTED.get(key);
+  if (!resolved) {
+    throw new Error(unsupportedPlatformMessage(platform, arch));
+  }
+  return cloneTarget(key, resolved);
+}
+
+function supportedTargets() {
+  return Array.from(SUPPORTED.entries()).map(([key, target]) => cloneTarget(key, target));
+}
+
+function resolveRustTarget(rustTarget) {
+  const resolved = supportedTargets().find(target => target.rustTarget === rustTarget);
+  if (!resolved) {
+    const supported = supportedTargets().map(target => target.rustTarget).join(', ');
+    throw new Error(`Unsupported TFY Rust target ${rustTarget}. Supported: ${supported}`);
+  }
+  return resolved;
+}
+
+function cleanVersion(version) {
+  return String(version).replace(/^v/, '');
+}
+
+function baseVersion(version) {
+  return cleanVersion(version).replace(/-preview\.\d+$/, '');
+}
+
+function assetBaseName(version, target) {
+  return `tfy-${baseVersion(version)}-${target.archivePlatform}-${target.archiveArch}`;
+}
+
+function archiveName(version, target) {
+  return `${assetBaseName(version, target)}.tar.gz`;
+}
+
+module.exports = {
+  SUPPORTED,
+  archiveName,
+  assetBaseName,
+  baseVersion,
+  cleanVersion,
+  currentPlatform,
+  sourceBuildGuidance,
+  resolvePlatform,
+  resolveRustTarget,
+  supportedPlatformList,
+  supportedTargets,
+  unsupportedPlatformMessage
+};