@aegean-org/necode-cli 1.0.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2025 Mario Zechner
+Copyright (c) 2025-2026 Can Bölük
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,115 @@
+# @aegean-org/necode-cli
+
+NE-focused coding agent CLI.
+
+[中文](#中文) | [English](#english)
+
+## 中文
+
+### 安装
+
+```sh
+npm install -g @aegean-org/necode-cli
+necode
+```
+
+包发布在 npm registry，包名是 `@aegean-org/necode-cli`，安装后的命令是 `necode`。这是一个集成 CLI 包，安装时会从公开的 `liangwei/necode-cli-releases` GitHub Releases 下载当前平台二进制；普通用户不需要安装 Bun，也不需要单独安装内部 `pi-*` 包。
+
+### 登录
+
+在 TUI 中执行 `/login` 登录 NE。正常对话前必须完成 NE 登录。
+
+### 本地文献 RAG
+
+索引本地文献：
+
+```text
+/rag-import <file-or-directory>
+```
+
+在输入中引用已索引文献：
+
+```text
+@文献
+@文献:keyword
+@doc
+@doc:keyword
+```
+
+选择文献后会插入可读标题，例如 `@文献:"Paper Title"` 或 `@doc:"Paper Title"`。
+
+### 默认 MCP 服务
+
+necode 默认引入这些外部 MCP 服务：
+
+- `noteexpress`: NE / NoteExpress MCP 服务
+- `qingtibase`: 青提 MCP 服务
+
+在 TUI 中使用 `/mcp list` 查看连接状态和可用工具。
+
+### 发布
+
+只发布 `@aegean-org/necode-cli` 一个 npm 包。内部 workspace 包会编译进平台二进制，并作为 `liangwei/necode-cli-releases` 的 GitHub Release assets 分发，不单独发布到 npm。
+
+```sh
+npm run build:necode:binaries -- --targets win32-x64
+npm run pack:necode -- --targets win32-x64
+npm run publish:necode -- --targets win32-x64
+```
+
+npm 包会保持小体积，并包含二进制校验清单。跨平台包需要先把 `darwin-arm64,darwin-x64,linux-arm64,linux-x64,win32-x64` 的二进制都放到 `packages/coding-agent/binaries/`，发布时还要先把这些文件上传到 `liangwei/necode-cli-releases` 的匹配版本 GitHub Release。
+
+## English
+
+### Install
+
+```sh
+npm install -g @aegean-org/necode-cli
+necode
+```
+
+The package is published to the npm registry as `@aegean-org/necode-cli`, and the installed command is `necode`. It is an integrated CLI package; install downloads the matching platform binary from the public `liangwei/necode-cli-releases` GitHub Releases, so normal users do not need Bun or separate internal `pi-*` packages.
+
+### Login
+
+Run `/login` in the TUI to sign in with NE. A valid NE login is required before normal chat usage.
+
+### Local Literature RAG
+
+Index local papers:
+
+```text
+/rag-import <file-or-directory>
+```
+
+Use indexed literature explicitly in a prompt:
+
+```text
+@文献
+@文献:keyword
+@doc
+@doc:keyword
+```
+
+Selecting an indexed document inserts a readable title such as `@文献:"Paper Title"` or `@doc:"Paper Title"`.
+
+### Default MCP Servers
+
+necode includes these default external MCP servers:
+
+- `noteexpress`: NE / NoteExpress MCP server
+- `qingtibase`: Qingti MCP server
+
+Use `/mcp list` inside the TUI to check whether they are connected and which tools are available.
+
+### Publishing
+
+Only `@aegean-org/necode-cli` is published to npm. Internal workspace packages are compiled into platform binaries distributed as `liangwei/necode-cli-releases` GitHub Release assets instead of being published separately.
+
+```sh
+npm run build:necode:binaries -- --targets win32-x64
+npm run pack:necode -- --targets win32-x64
+npm run publish:necode -- --targets win32-x64
+```
+
+The npm package stays small and contains a checked binary manifest. A cross-platform package requires binaries for `darwin-arm64,darwin-x64,linux-arm64,linux-x64,win32-x64` to exist in `packages/coding-agent/binaries/` first, and publish runs must upload those files to the matching release in `liangwei/necode-cli-releases` before `npm publish`.

package/bin/necode.js

@@ -0,0 +1,54 @@
+#!/usr/bin/env node
+import { spawnSync } from "node:child_process";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const FAILURE_EXIT_CODE = 1;
+const SUCCESS_EXIT_CODE = 0;
+const USER_ARGV_OFFSET = 2;
+const BINARIES = Object.freeze({
+	"darwin-arm64": "necode-cli-darwin-arm64",
+	"darwin-x64": "necode-cli-darwin-x64",
+	"linux-arm64": "necode-cli-linux-arm64",
+	"linux-x64": "necode-cli-linux-x64",
+	"win32-x64": "necode-cli-windows-x64.exe",
+});
+
+function resolveBinary() {
+	const key = `${process.platform}-${process.arch}`;
+	const binaryName = BINARIES[key];
+	if (!binaryName) {
+		throw new Error(`Unsupported platform: ${key}`);
+	}
+	const packageRoot = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
+	const binaryPath = path.join(packageRoot, "binaries", binaryName);
+	if (!fs.existsSync(binaryPath)) {
+		throw new Error(`Installed necode binary is missing: ${binaryPath}. Reinstall without --ignore-scripts.`);
+	}
+	return binaryPath;
+}
+
+function run() {
+	const binaryPath = resolveBinary();
+	const result = spawnSync(binaryPath, process.argv.slice(USER_ARGV_OFFSET), {
+		stdio: "inherit",
+		windowsHide: false,
+	});
+	if (result.error) {
+		throw result.error;
+	}
+	if (result.signal) {
+		process.stderr.write(`necode terminated by signal ${result.signal}\n`);
+		process.exit(FAILURE_EXIT_CODE);
+	}
+	process.exit(result.status ?? SUCCESS_EXIT_CODE);
+}
+
+try {
+	run();
+} catch (error) {
+	const message = error instanceof Error ? error.message : String(error);
+	process.stderr.write(`error: ${message}\n`);
+	process.exit(FAILURE_EXIT_CODE);
+}

package/binary-manifest.json

@@ -0,0 +1,31 @@
+{
+	"version": "1.0.0",
+	"repository": "liangwei/necode-cli-releases",
+	"assets": {
+		"darwin-arm64": {
+			"filename": "necode-cli-darwin-arm64",
+			"sha256": "210cfe0ca226da82e3fab887b93ff7173af88ca7e7310b509340ee4f1c61592c",
+			"size": 201537632
+		},
+		"darwin-x64": {
+			"filename": "necode-cli-darwin-x64",
+			"sha256": "dbad795f958ab25880adffa69a2ef40aa10d4012b776a75374a5c6e963c14c9c",
+			"size": 206981312
+		},
+		"linux-arm64": {
+			"filename": "necode-cli-linux-arm64",
+			"sha256": "264eb62fd60083e7a7f1bbf5834acd90eab2728712c6629a9ab38404105df0ab",
+			"size": 227387536
+		},
+		"linux-x64": {
+			"filename": "necode-cli-linux-x64",
+			"sha256": "aaa36b9f039077c39d771af3906df68cdef7f01ee06675861e778133ab4cb944",
+			"size": 243677312
+		},
+		"win32-x64": {
+			"filename": "necode-cli-windows-x64.exe",
+			"sha256": "4f09f4336ff11d019395d21a595540eb964dd0fb6f05e85539ab389169ba86c6",
+			"size": 231872000
+		}
+	}
+}

package/package.json

@@ -0,0 +1,45 @@
+{
+	"name": "@aegean-org/necode-cli",
+	"version": "1.0.0",
+	"description": "necode coding agent with read, bash, edit, write tools and session management",
+	"author": "Can Boluk",
+	"contributors": [
+		"Mario Zechner"
+	],
+	"license": "MIT",
+	"keywords": [
+		"coding-agent",
+		"ai",
+		"llm",
+		"cli",
+		"tui",
+		"agent"
+	],
+	"type": "module",
+	"bin": {
+		"necode": "bin/necode.js"
+	},
+	"files": [
+		"bin",
+		"scripts",
+		"binary-manifest.json",
+		"README.md",
+		"CHANGELOG.md",
+		"LICENSE"
+	],
+	"engines": {
+		"node": ">=18"
+	},
+	"scripts": {
+		"postinstall": "node scripts/install-integrated-binary.js"
+	},
+	"os": [
+		"darwin",
+		"linux",
+		"win32"
+	],
+	"cpu": [
+		"arm64",
+		"x64"
+	]
+}

package/scripts/install-integrated-binary.js

@@ -0,0 +1,82 @@
+#!/usr/bin/env node
+import { createHash } from "node:crypto";
+import * as fs from "node:fs";
+import * as fsp from "node:fs/promises";
+import * as path from "node:path";
+import { Readable } from "node:stream";
+import { pipeline } from "node:stream/promises";
+import { fileURLToPath } from "node:url";
+
+const EXECUTABLE_MODE = 0o755;
+const FAILURE_EXIT_CODE = 1;
+const packageRoot = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
+const manifestPath = path.join(packageRoot, "binary-manifest.json");
+const binariesDir = path.join(packageRoot, "binaries");
+
+async function readManifest() {
+	const manifest = JSON.parse(await fsp.readFile(manifestPath, "utf8"));
+	if (typeof manifest.version !== "string") throw new Error("binary-manifest.json is missing version");
+	if (typeof manifest.repository !== "string") throw new Error("binary-manifest.json is missing repository");
+	if (!manifest.assets || typeof manifest.assets !== "object") throw new Error("binary-manifest.json is missing assets");
+	return manifest;
+}
+
+function resolveAsset(manifest) {
+	const platformKey = `${process.platform}-${process.arch}`;
+	const asset = manifest.assets[platformKey];
+	if (!asset) {
+		const supported = Object.keys(manifest.assets).sort().join(", ");
+		throw new Error(`Unsupported platform ${platformKey}. Supported platforms: ${supported}`);
+	}
+	if (typeof asset.filename !== "string") throw new Error(`Asset ${platformKey} is missing filename`);
+	if (typeof asset.sha256 !== "string") throw new Error(`Asset ${platformKey} is missing sha256`);
+	return asset;
+}
+
+function releaseAssetUrl(manifest, asset) {
+	const tag = `v${manifest.version}`;
+	return `https://github.com/${manifest.repository}/releases/download/${tag}/${asset.filename}`;
+}
+
+async function sha256File(filePath) {
+	const hash = createHash("sha256");
+	for await (const chunk of fs.createReadStream(filePath)) {
+		hash.update(chunk);
+	}
+	return hash.digest("hex");
+}
+
+async function downloadFile(url, outputPath) {
+	const response = await fetch(url);
+	if (!response.ok) throw new Error(`Failed to download ${url}: ${response.status} ${response.statusText}`);
+	if (!response.body) throw new Error(`Failed to download ${url}: response body is empty`);
+	await pipeline(Readable.fromWeb(response.body), fs.createWriteStream(outputPath, { mode: EXECUTABLE_MODE }));
+}
+
+async function installBinary() {
+	const manifest = await readManifest();
+	const asset = resolveAsset(manifest);
+	const finalPath = path.join(binariesDir, asset.filename);
+	const tmpPath = `${finalPath}.tmp-${process.pid}`;
+	await fsp.mkdir(binariesDir, { recursive: true });
+	await fsp.rm(tmpPath, { force: true });
+	try {
+		await downloadFile(releaseAssetUrl(manifest, asset), tmpPath);
+		const actualSha256 = await sha256File(tmpPath);
+		if (actualSha256 !== asset.sha256) {
+			throw new Error(`Checksum mismatch for ${asset.filename}: expected ${asset.sha256}, got ${actualSha256}`);
+		}
+		await fsp.rename(tmpPath, finalPath);
+		if (process.platform !== "win32") await fsp.chmod(finalPath, EXECUTABLE_MODE);
+	} finally {
+		await fsp.rm(tmpPath, { force: true });
+	}
+}
+
+try {
+	await installBinary();
+} catch (error) {
+	const message = error instanceof Error ? error.message : String(error);
+	process.stderr.write(`error: ${message}\n`);
+	process.exit(FAILURE_EXIT_CODE);
+}