@nema-project/nema 0.0.0-stage → 0.1.4

package/dist/secrets/file.js

@@ -0,0 +1,89 @@
+// secrets/file.js
+import { randomUUID } from "node:crypto";
+import { closeSync, fstatSync, fsyncSync, lstatSync, mkdirSync, openSync, readFileSync, renameSync, unlinkSync, writeSync } from "node:fs";
+import path from "node:path";
+import { createInterface } from "node:readline";
+import { openPrivateFile, privateModeMatches, protectPrivatePath } from "./permissions.js";
+var SecretFileError = class extends Error {
+  kind;
+  constructor(kind, message) {
+    super(message);
+    this.kind = kind;
+    this.name = "SecretFileError";
+  }
+};
+var INVALID_VALUE = "\u5FC5\u987B\u662F\u4E00\u884C\u975E\u7A7A\u6587\u672C";
+var isValidLine = (value) => value !== "" && !/[\u0000-\u001f\u007f]/.test(value);
+var symlinkError = (file) => new SecretFileError("symlink", `${path.basename(file)} \u6587\u4EF6\u662F\u7B26\u53F7\u94FE\u63A5\uFF0C\u5DF2\u62D2\u7EDD\u3002`);
+function saveSecretLine(file, value, dirMode = 448) {
+  if (!isValidLine(value))
+    throw new SecretFileError("invalid", INVALID_VALUE);
+  try {
+    if (lstatSync(file).isSymbolicLink())
+      throw symlinkError(file);
+  } catch (e) {
+    if (e.code !== "ENOENT")
+      throw e;
+  }
+  const dir = path.dirname(file);
+  mkdirSync(dir, { recursive: true, mode: dirMode });
+  protectPrivatePath(dir, dirMode);
+  const tmp = `${file}.${process.pid}.${randomUUID()}.tmp`;
+  const fd = openSync(tmp, "wx", 384);
+  try {
+    try {
+      writeSync(fd, value);
+      fsyncSync(fd);
+    } finally {
+      closeSync(fd);
+    }
+    protectPrivatePath(tmp, 384);
+    renameSync(tmp, file);
+  } catch (e) {
+    try {
+      unlinkSync(tmp);
+    } catch {
+    }
+    throw e;
+  }
+}
+function readSecretLine(file, missingMessage, invalidMessage) {
+  let fd;
+  try {
+    fd = openPrivateFile(file);
+  } catch (e) {
+    if (e.code === "ENOENT")
+      throw new Error(missingMessage);
+    if (e.code === "ELOOP")
+      throw symlinkError(file);
+    throw e;
+  }
+  try {
+    const st = fstatSync(fd);
+    if (!st.isFile() || !privateModeMatches(st)) {
+      throw new SecretFileError("mode", `${path.basename(file)} \u6587\u4EF6\u6743\u9650\u5FC5\u987B\u662F 0600`);
+    }
+    const value = readFileSync(fd, "utf8").replace(/\r?\n$/, "");
+    if (!isValidLine(value))
+      throw new Error(invalidMessage);
+    return value;
+  } finally {
+    closeSync(fd);
+  }
+}
+async function readStdinLine(stdin) {
+  const lines = createInterface({ input: stdin });
+  let value = "";
+  for await (const line of lines) {
+    value = line.trim();
+    break;
+  }
+  lines.close();
+  return value;
+}
+export {
+  SecretFileError,
+  readSecretLine,
+  readStdinLine,
+  saveSecretLine
+};

package/dist/secrets/github.d.ts

@@ -0,0 +1,10 @@
+import type { Out } from "../direct/authCommands.js";
+export declare const githubTokenPath: (nemaHome: string) => string;
+export declare function saveGithubToken(nemaHome: string, token: string): void;
+export declare function readGithubToken(nemaHome: string): string;
+/** `nema auth github`: reads one line from stdin. Never prints the token. */
+export declare function authGithub(o: {
+    nemaHome: string;
+    out: Out;
+    stdin: NodeJS.ReadableStream;
+}): Promise<number>;

package/dist/secrets/github.js

@@ -0,0 +1,29 @@
+// secrets/github.js
+import path from "node:path";
+import { readSecretLine, readStdinLine, saveSecretLine } from "./file.js";
+var MISSING_TOKEN = "\u672A\u4FDD\u5B58 GitHub \u4EE4\u724C\uFF1A\u8BF7\u8FD0\u884C nema auth github";
+var INVALID_STORED_TOKEN = "GitHub \u4EE4\u724C\u6587\u4EF6\u5185\u5BB9\u65E0\u6548\u3002\u8BF7\u91CD\u65B0\u628A\u4EE4\u724C\u4ECE\u6807\u51C6\u8F93\u5165\u4EA4\u7ED9 nema auth github\u3002";
+var githubTokenPath = (nemaHome) => path.join(nemaHome, "github-token");
+function saveGithubToken(nemaHome, token) {
+  saveSecretLine(githubTokenPath(nemaHome), token);
+}
+function readGithubToken(nemaHome) {
+  return readSecretLine(githubTokenPath(nemaHome), MISSING_TOKEN, INVALID_STORED_TOKEN);
+}
+async function authGithub(o) {
+  const token = await readStdinLine(o.stdin);
+  try {
+    saveGithubToken(o.nemaHome, token);
+    o.out.log("\u5DF2\u4FDD\u5B58 GitHub \u4EE4\u724C");
+    return 0;
+  } catch (e) {
+    o.out.error(e instanceof Error ? e.message : String(e));
+    return 1;
+  }
+}
+export {
+  authGithub,
+  githubTokenPath,
+  readGithubToken,
+  saveGithubToken
+};

package/dist/secrets/permissions.d.ts

@@ -0,0 +1,7 @@
+export declare const WINDOWS_ACL_SCRIPT: string;
+export declare function protectPrivatePath(file: string, mode?: number): void;
+export declare function privateModeMatches(st: {
+    mode: number;
+}, platform?: NodeJS.Platform): boolean;
+/** Refuse links on all platforms, and verify the Windows DACL and opened file identity. */
+export declare function openPrivateFile(file: string): number;

package/dist/secrets/permissions.js

@@ -0,0 +1,86 @@
+// secrets/permissions.js
+import { spawnSync } from "node:child_process";
+import { chmodSync, closeSync, constants, fstatSync, lstatSync, openSync } from "node:fs";
+import path from "node:path";
+var WINDOWS_ACL_SCRIPT = String.raw`
+$ErrorActionPreference = 'Stop'
+$file = $env:NEMA_PRIVATE_PATH
+$sid = [System.Security.Principal.WindowsIdentity]::GetCurrent().User
+if ([System.IO.Directory]::Exists($file)) { $item = [System.IO.DirectoryInfo]::new($file); $isDirectory = $true }
+elseif ([System.IO.File]::Exists($file)) { $item = [System.IO.FileInfo]::new($file); $isDirectory = $false }
+else { throw 'Path not found' }
+if ($item.Attributes -band [System.IO.FileAttributes]::ReparsePoint) { throw 'Reparse point refused' }
+if ($env:NEMA_PRIVATE_ACTION -eq 'protect') {
+  if ($isDirectory) { $acl = [System.Security.AccessControl.DirectorySecurity]::new() }
+  else { $acl = [System.Security.AccessControl.FileSecurity]::new() }
+  $acl.SetOwner($sid)
+  $acl.SetAccessRuleProtection($true, $false)
+  foreach ($principal in @($sid.Value, 'S-1-5-18', 'S-1-5-32-544')) {
+    $identity = [System.Security.Principal.SecurityIdentifier]::new($principal)
+    if ($isDirectory) {
+      $rule = [System.Security.AccessControl.FileSystemAccessRule]::new($identity, 'FullControl', 'ContainerInherit,ObjectInherit', 'None', 'Allow')
+    } else {
+      $rule = [System.Security.AccessControl.FileSystemAccessRule]::new($identity, 'FullControl', 'Allow')
+    }
+    $acl.AddAccessRule($rule)
+  }
+  $item.SetAccessControl($acl)
+}
+$acl = $item.GetAccessControl()
+if ($acl.GetOwner([System.Security.Principal.SecurityIdentifier]).Value -ne $sid.Value) { throw 'Unexpected owner' }
+$allowed = @($sid.Value, 'S-1-5-18', 'S-1-5-32-544')
+$hasOwner = $false
+foreach ($rule in $acl.GetAccessRules($true, $true, [System.Security.Principal.SecurityIdentifier])) {
+  if ($rule.AccessControlType -eq 'Allow') {
+    if ($allowed -notcontains $rule.IdentityReference.Value) { throw 'Non-private ACL' }
+    if ($rule.IdentityReference.Value -eq $sid.Value -and ($rule.FileSystemRights -band [System.Security.AccessControl.FileSystemRights]::ReadData)) { $hasOwner = $true }
+  }
+}
+if (-not $hasOwner) { throw 'Owner cannot read' }
+`;
+function windowsAcl(file, action) {
+  const exe = path.join(process.env.SystemRoot ?? "C:\\Windows", "System32", "WindowsPowerShell", "v1.0", "powershell.exe");
+  const result = spawnSync(exe, ["-NoLogo", "-NoProfile", "-NonInteractive", "-Command", WINDOWS_ACL_SCRIPT], {
+    env: { ...process.env, NEMA_PRIVATE_PATH: path.resolve(file), NEMA_PRIVATE_ACTION: action },
+    // A cold PowerShell on a busy Windows runner can take longer than a local call.
+    stdio: "ignore",
+    windowsHide: true,
+    timeout: 45e3
+  });
+  if (result.error || result.status !== 0) {
+    const reason = result.error?.code ?? (result.status === null ? "unknown" : `powershell exit ${result.status}`);
+    throw new Error(`${path.basename(file)}: \u65E0\u6CD5\u9A8C\u8BC1\u79C1\u6709 Windows ACL / cannot verify private Windows ACL (${reason})`);
+  }
+}
+function protectPrivatePath(file, mode = 384) {
+  if (process.platform === "win32")
+    windowsAcl(file, "protect");
+  else
+    chmodSync(file, mode);
+}
+function privateModeMatches(st, platform = process.platform) {
+  return platform === "win32" || (st.mode & 511) === 384;
+}
+function openPrivateFile(file) {
+  const before = lstatSync(file);
+  if (before.isSymbolicLink())
+    throw Object.assign(new Error("Symbolic link refused"), { code: "ELOOP" });
+  const fd = openSync(file, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0) | (constants.O_NONBLOCK ?? 0));
+  try {
+    const opened = fstatSync(fd);
+    if (!opened.isFile() || before.dev !== opened.dev || before.ino !== opened.ino)
+      throw new Error("Private file changed while opening");
+    if (process.platform === "win32")
+      windowsAcl(file, "check");
+    return fd;
+  } catch (error) {
+    closeSync(fd);
+    throw error;
+  }
+}
+export {
+  WINDOWS_ACL_SCRIPT,
+  openPrivateFile,
+  privateModeMatches,
+  protectPrivatePath
+};

package/dist/systemGit.d.ts

@@ -0,0 +1,14 @@
+/** `rev-parse --path-format=absolute` (worktree mapping) needs Git 2.31. */
+export declare const MIN_GIT_VERSION: readonly [2, 31, 0];
+export declare function parseGitVersion(output: string): [number, number, number] | null;
+/** PATH a Mac app gets when Finder opens it. Anything else is left alone, including a test that cleared PATH. */
+export declare const FINDER_GIT_PATH: string[];
+/** Install locations Finder does not put on PATH. Homebrew (Apple silicon, then Intel) and MacPorts. */
+export declare const EXTRA_GIT_DIRECTORIES: string[];
+export declare function gitPathForFinderLaunch(currentPath: string | undefined, presentDirectories: readonly string[], platform?: NodeJS.Platform): string | undefined;
+/**
+ * Nema runs the git the user already has, so fetch uses their own credential helpers and SSH setup.
+ * A Mac app opened from Finder only has /usr/bin on PATH; Homebrew and MacPorts git are added in that case.
+ * Resolves with the `git --version` line; rejects with code NEMA_GIT_UNAVAILABLE and install guidance.
+ */
+export declare function requireSystemGit(run?: () => Promise<string>): Promise<string>;

package/dist/systemGit.js

@@ -0,0 +1,75 @@
+// systemGit.js
+import { execFile } from "node:child_process";
+import { accessSync, constants } from "node:fs";
+import path from "node:path";
+import { promisify } from "node:util";
+var execFileAsync = promisify(execFile);
+var MIN_GIT_VERSION = [2, 31, 0];
+var MIN_TEXT = MIN_GIT_VERSION.join(".");
+var INSTALL_URL = "https://git-scm.com/downloads";
+function parseGitVersion(output) {
+  const match = /git version (\d+)\.(\d+)(?:\.(\d+))?/.exec(output);
+  return match ? [Number(match[1]), Number(match[2]), Number(match[3] ?? 0)] : null;
+}
+function meetsMinimum(version) {
+  for (let i = 0; i < 3; i++)
+    if (version[i] !== MIN_GIT_VERSION[i])
+      return version[i] > MIN_GIT_VERSION[i];
+  return true;
+}
+function unavailable(reason, cause) {
+  return Object.assign(new Error(`Nema \u9700\u8981 Git ${MIN_TEXT} \u6216\u66F4\u9AD8\u7248\u672C\uFF1A${reason.zh}\u3002\u8BF7\u4ECE ${INSTALL_URL} \u5B89\u88C5\u540E\u91CD\u65B0\u6253\u5F00 Nema\u3002 / Nema needs Git ${MIN_TEXT} or later: ${reason.en}. Install it from ${INSTALL_URL} and reopen Nema.`, { cause }), { code: "NEMA_GIT_UNAVAILABLE" });
+}
+var FINDER_GIT_PATH = ["/usr/bin", "/bin", "/usr/sbin", "/sbin"];
+var EXTRA_GIT_DIRECTORIES = ["/opt/homebrew/bin", "/usr/local/bin", "/opt/local/bin"];
+function gitPathForFinderLaunch(currentPath, presentDirectories, platform = process.platform) {
+  if (platform !== "darwin")
+    return currentPath;
+  const parts = (currentPath ?? "").split(":").filter(Boolean);
+  if (parts.length === 0 || parts.some((part) => !FINDER_GIT_PATH.includes(part)))
+    return currentPath;
+  const prefix = presentDirectories.filter((dir) => EXTRA_GIT_DIRECTORIES.includes(dir) && !parts.includes(dir));
+  return prefix.length ? [...prefix, ...parts].join(":") : currentPath;
+}
+function directoriesWithGit(directories) {
+  return directories.filter((dir) => {
+    try {
+      accessSync(path.join(dir, "git"), constants.X_OK);
+      return true;
+    } catch {
+      return false;
+    }
+  });
+}
+async function gitVersionOutput() {
+  if (process.platform === "darwin") {
+    const next = gitPathForFinderLaunch(process.env.PATH, directoriesWithGit(EXTRA_GIT_DIRECTORIES));
+    if (next && next !== process.env.PATH)
+      process.env.PATH = next;
+  }
+  const { stdout } = await execFileAsync("git", ["--version"], { timeout: 15e3, windowsHide: true });
+  return stdout;
+}
+async function requireSystemGit(run = gitVersionOutput) {
+  let output;
+  try {
+    output = await run();
+  } catch (error) {
+    throw unavailable({ zh: "\u627E\u4E0D\u5230\u53EF\u7528\u7684 git", en: "git could not be run" }, error);
+  }
+  const line = output.trim().split("\n")[0] ?? "";
+  const version = parseGitVersion(line);
+  if (!version)
+    throw unavailable({ zh: `\u65E0\u6CD5\u8BC6\u522B git \u7248\u672C\uFF08${line}\uFF09`, en: `its version is unreadable (${line})` });
+  if (!meetsMinimum(version))
+    throw unavailable({ zh: `\u5F53\u524D\u662F ${version.join(".")}`, en: `found ${version.join(".")}` });
+  return line;
+}
+export {
+  EXTRA_GIT_DIRECTORIES,
+  FINDER_GIT_PATH,
+  MIN_GIT_VERSION,
+  gitPathForFinderLaunch,
+  parseGitVersion,
+  requireSystemGit
+};

package/dist/wp/commands.d.ts

@@ -0,0 +1,15 @@
+import type { Out } from "../direct/authCommands.js";
+export type WpRun = {
+    nemaHome: string;
+    hubUrl: string;
+    cwd: string;
+    out: Out;
+};
+export type WpGetRun = WpRun & {
+    id: string;
+    dir?: string;
+    stdout?: boolean;
+    force?: boolean;
+};
+export declare function runWpList(o: WpRun): Promise<number>;
+export declare function runWpGet(o: WpGetRun): Promise<number>;

package/dist/wp/commands.js

@@ -0,0 +1,103 @@
+// wp/commands.js
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { repoInfo } from "../report/git.js";
+import { getFromHub } from "../report/send.js";
+import { ensureReportToken } from "../report/token.js";
+async function fetchJson(o, route) {
+  const info = await repoInfo(o.cwd);
+  if (!info) {
+    o.out.error("\u4E0D\u5728 git \u4ED3\u5E93\u91CC");
+    return { ok: false, code: 1 };
+  }
+  let token;
+  try {
+    token = ensureReportToken(o.nemaHome);
+  } catch (e) {
+    o.out.error(e instanceof Error ? e.message : String(e));
+    return { ok: false, code: 1 };
+  }
+  const sep = route.includes("?") ? "&" : "?";
+  const res = await getFromHub(o.hubUrl, `${route}${sep}gitCommonDir=${encodeURIComponent(info.gitCommonDir)}`, token);
+  if (res.status === 0 || res.status >= 500) {
+    o.out.error("Nema \u6682\u65F6\u4E0D\u53EF\u8FBE");
+    return { ok: false, code: 1 };
+  }
+  if (res.status === 204) {
+    o.out.error("\u8FD9\u4E2A\u4ED3\u5E93\u6CA1\u6709\u7ED1\u5B9A\u5230 Nema \u91CC\u4EFB\u4F55\u672A\u5F52\u6863\u7684 workspace");
+    return { ok: false, code: 1 };
+  }
+  if (res.status >= 400) {
+    let message = `Nema \u62D2\u7EDD\u4E86\u8BF7\u6C42\uFF08HTTP ${res.status}\uFF09`;
+    try {
+      const v = JSON.parse(res.text);
+      if (typeof v.error === "string")
+        message = v.error;
+    } catch {
+    }
+    o.out.error(message);
+    return { ok: false, code: 1 };
+  }
+  try {
+    return { ok: true, json: JSON.parse(res.text) };
+  } catch {
+    o.out.error("Nema \u8FD4\u56DE\u4E86\u65E0\u6CD5\u89E3\u6790\u7684\u5185\u5BB9");
+    return { ok: false, code: 1 };
+  }
+}
+async function runWpList(o) {
+  const r = await fetchJson(o, "/report/workpackages");
+  if (!r.ok)
+    return r.code;
+  const items = Array.isArray(r.json) ? r.json : [];
+  if (items.length === 0) {
+    o.out.log("\u5F53\u524D\u4ED3\u5E93\u6CA1\u6709\u5DF2\u6279\u51C6\u7684\u5F00\u53D1\u5305");
+    return 0;
+  }
+  for (const w of items)
+    o.out.log(`${w.id}  ${w.title}  (${w.tasks} \u4E2A\u4EFB\u52A1)`);
+  return 0;
+}
+var reportBlock = (id) => `> \u505A\u5B8C\u6BCF\u4E2A\u4EFB\u52A1\u540E\u8FD0\u884C\uFF1Anema report --entries ${id} --task <n> --summary "\u2026" --commits <sha,\u2026> --files <path,\u2026>
+
+`;
+async function runWpGet(o) {
+  if (!/^W-[1-9]\d*$/.test(o.id)) {
+    o.out.error(`\u5F00\u53D1\u5305\u7F16\u53F7\u5E94\u5F62\u5982 W-2\uFF0C\u5B9E\u9645\u4E3A ${o.id}`);
+    return 1;
+  }
+  const r = await fetchJson(o, `/report/workpackages/${o.id}`);
+  if (!r.ok)
+    return r.code;
+  const wp = r.json;
+  const plan = reportBlock(wp.id) + wp.plan;
+  if (o.stdout) {
+    o.out.log(`${wp.spec}
+
+${plan}`);
+    return 0;
+  }
+  const base = path.join(path.resolve(o.cwd, o.dir ?? "."), ".nema", wp.id);
+  const files = [
+    { file: path.join(base, "spec.md"), content: wp.spec },
+    { file: path.join(base, "plan.md"), content: plan }
+  ];
+  if (!o.force) {
+    for (const f of files) {
+      if (existsSync(f.file) && readFileSync(f.file, "utf8") !== f.content) {
+        o.out.error(`${f.file} \u5DF2\u5B58\u5728\u4E14\u5185\u5BB9\u4E0D\u540C\uFF1B\u52A0 --force \u8986\u76D6`);
+        return 1;
+      }
+    }
+  }
+  mkdirSync(base, { recursive: true });
+  for (const f of files)
+    writeFileSync(f.file, f.content);
+  for (const f of files)
+    o.out.log(`\u5DF2\u5199\u5165 ${f.file}`);
+  return 0;
+}
+export {
+  runWpGet,
+  runWpList
+};

package/package.json

@@ -1,6 +1,28 @@
 {
   "name": "@nema-project/nema",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.4",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "nema": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "src/report/SKILL.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Nema-Project/nema-room.git"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.32.1",
+    "commander": "^15.0.0",
+    "smol-toml": "^1.9.1",
+    "ws": "^8.22.0",
+    "zod": "^4.6.7"
+  }
+}

package/src/report/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: nema-report
+description: Report finished, committed work to Nema so it can track which requirements are implemented. Use after you finish a unit of work and commit it in a repository that Nema follows.
+---
+
+# Report finished work to Nema
+
+When you have finished a unit of work and committed it, tell Nema what you did. Run this from inside the repository:
+
+```sh
+nema report --summary "<one line: what you finished>" --commits <sha>[,<sha>...] --entries <id>[,<id>...] --files <path>[,<path>...]
+```
+
+- Report once per finished unit of work, after the commits exist. Don't report work that is unfinished or not yet committed.
+- `--commits`: the commits that hold this work (`git log` shows them).
+- `--entries`: reference requirement ids like R-7 when you know them. Leave the flag out when you don't.
+- `--files`: list only files you changed, as paths relative to the repository root.
+- Keep the summary short and factual. Never include secrets, tokens, keys or credentials anywhere in a report.
+- If `.nema/W-*/plan.md` exists in your working tree, report each finished task with `--entries W-n --task <n>`.
+
+If the command says Nema is unreachable, the report is kept locally and sent later. You don't need to retry. If it says the repository isn't bound to Nema, stop reporting for this repository.

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.