@doki-land/nifty 0.0.0

package/Readme.md

@@ -0,0 +1,30 @@
+# @doki-land/nifty
+
+**Gitmoji is the default Nifty convention.**
+
+| Layer | Role |
+| --- | --- |
+| `@doki-land/nifty-<platform>` | Node-API `.node`（gitmoji + gix） |
+| `nifty-publisher` | Rust：`petgraph` 拓扑排序 + `npm publish` |
+| `src/cli/` | CLI 实现（`update` / `lint` / `check` / `upload` / `bump` / `publish`） |
+| `cli/nifty.mjs` | npm `bin` shim（jiti 加载 `src/cli`） |
+| `src/` | TypeScript API |
+
+Rust 侧无 `bin` / `cli`。
+
+**本仓开发**（pnpm workspace，`projects/packages/*`）：
+
+```bash
+pnpm install          # 链接 @doki-land/nifty → node_modules/.bin/nifty
+pnpm run build:napi   # 构建 native addon
+pnpm exec nifty bump
+pnpm exec nifty publish --dry-run
+```
+
+**发布后消费**：
+
+```bash
+npm install @doki-land/nifty
+nifty bump
+nifty publish --dry-run
+```

package/cli/nifty.mjs

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+
+import { createJiti } from "jiti";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const jiti = createJiti(import.meta.url, { interopDefault: true });
+const { runCli } = await jiti.import(join(here, "../src/cli/main.ts"));
+
+process.exit(await runCli(process.argv.slice(2)));

package/package.json

@@ -0,0 +1,35 @@
+{
+  "bin": {
+    "nifty": "cli/nifty.mjs"
+  },
+  "dependencies": {
+    "jiti": "^2.4.2"
+  },
+  "description": "Gitmoji-first commit conventions and release helpers (Node-API + TypeScript)",
+  "devDependencies": {
+    "@types/node": "^22.13.10",
+    "typescript": "^5.8.3"
+  },
+  "exports": {
+    ".": "./src/index.ts",
+    "./cli": "./src/cli/index.ts"
+  },
+  "files": [
+    "cli/nifty.mjs",
+    "src"
+  ],
+  "license": "MPL-2.0",
+  "name": "@doki-land/nifty",
+  "optionalDependencies": {
+    "@doki-land/nifty-darwin-arm64": "0.0.0",
+    "@doki-land/nifty-darwin-x64": "0.0.0",
+    "@doki-land/nifty-linux-arm64": "0.0.0",
+    "@doki-land/nifty-linux-x64": "0.0.0",
+    "@doki-land/nifty-win32-x64": "0.0.0"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit"
+  },
+  "type": "module",
+  "version": "0.0.0"
+}

package/src/cli/authArgs.ts

@@ -0,0 +1,52 @@
+import { resolveNpmExecutable } from "./resolveNpm.js";
+
+export type AuthCliOptions = {
+    otp?: string;
+    totpSecret?: string;
+    token?: string;
+    npm: string;
+};
+
+export function parseAuthArgs(argv: string[]): AuthCliOptions {
+    let otp: string | undefined;
+    let totpSecret: string | undefined;
+    let token: string | undefined;
+
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        if (arg === "--otp") {
+            otp = argv[++i];
+        } else if (arg === "--totp-secret") {
+            totpSecret = argv[++i];
+        } else if (arg === "--token") {
+            token = argv[++i];
+        } else if (arg.startsWith("--otp=")) {
+            otp = arg.slice("--otp=".length);
+        } else if (arg.startsWith("--totp-secret=")) {
+            totpSecret = arg.slice("--totp-secret=".length);
+        } else if (arg.startsWith("--token=")) {
+            token = arg.slice("--token=".length);
+        }
+    }
+
+    return {
+        otp,
+        totpSecret,
+        token,
+        npm: resolveNpmExecutable(),
+    };
+}
+
+export function authPayload(options: AuthCliOptions): {
+    otp?: string;
+    totpSecret?: string;
+    token?: string;
+    npm: string;
+} {
+    return {
+        ...(options.otp !== undefined ? { otp: options.otp } : {}),
+        ...(options.totpSecret !== undefined ? { totpSecret: options.totpSecret } : {}),
+        ...(options.token !== undefined ? { token: options.token } : {}),
+        npm: options.npm,
+    };
+}

package/src/cli/bump.ts

@@ -0,0 +1,237 @@
+import { existsSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { findWorkspaceRoot } from "./workspace.js";
+
+export type BumpKind = "patch" | "minor" | "major";
+
+export type BumpOptions = {
+    /** Explicit target version. When set, overrides `kind`. */
+    version?: string;
+    kind?: BumpKind;
+    cwd?: string;
+    dryRun?: boolean;
+};
+
+export type BumpReport = {
+    root: string;
+    from: string;
+    to: string;
+    kind?: BumpKind;
+    cargo: string[];
+    npm: string[];
+};
+
+const DEFAULT_KIND: BumpKind = "patch";
+
+export async function runBump(argv: string[]): Promise<void> {
+    const options = parseBumpArgs(argv);
+    const report = bumpWorkspace(options);
+    printReport(report, options.dryRun);
+}
+
+function parseBumpArgs(argv: string[]): BumpOptions {
+    let version: string | undefined;
+    let kind: BumpKind = DEFAULT_KIND;
+    let cwd: string | undefined;
+    let dryRun = false;
+
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        if (arg === "--dry-run") {
+            dryRun = true;
+        } else if (arg === "-C" || arg === "--cwd") {
+            cwd = argv[++i];
+        } else if (arg === "--version" || arg === "-v") {
+            version = argv[++i];
+        } else if (arg === "--patch") {
+            kind = "patch";
+        } else if (arg === "--minor") {
+            kind = "minor";
+        } else if (arg === "--major") {
+            kind = "major";
+        } else if (arg === "-h" || arg === "--help") {
+            printBumpHelp();
+            process.exit(0);
+        } else if (!arg.startsWith("-")) {
+            if (isBumpKind(arg)) {
+                kind = arg;
+            } else {
+                version = arg;
+            }
+        }
+    }
+
+    if (version) {
+        assertVersion(version);
+    }
+    return { version, kind, cwd, dryRun };
+}
+
+function isBumpKind(value: string): value is BumpKind {
+    return value === "patch" || value === "minor" || value === "major";
+}
+
+function assertVersion(version: string): void {
+    if (!/^\d+\.\d+\.\d+(-[\w.-]+)?$/.test(version)) {
+        throw new Error(`invalid version ${version}, expected semver like 0.0.0`);
+    }
+}
+
+export function bumpWorkspace(options: BumpOptions): BumpReport {
+    const root = findWorkspaceRoot(options.cwd ?? process.cwd());
+    const cratesDir = join(root, "projects", "crates");
+    const packagesDir = join(root, "projects", "packages");
+
+    const cargoPaths = collectCargoManifests(cratesDir);
+    const npmPaths = collectPackageManifests(packagesDir);
+    const from = readWorkspaceVersion(cargoPaths, npmPaths);
+    const to = options.version ?? bumpSemver(from, options.kind ?? DEFAULT_KIND);
+    assertVersion(to);
+
+    const cargo = cargoPaths.map((path) => bumpCargoManifest(path, to, options.dryRun));
+    const npm = npmPaths.map((path) => bumpPackageManifest(path, to, options.dryRun));
+
+    return {
+        root,
+        from,
+        to,
+        kind: options.version ? undefined : options.kind ?? DEFAULT_KIND,
+        cargo,
+        npm,
+    };
+}
+
+function readWorkspaceVersion(cargoPaths: string[], npmPaths: string[]): string {
+    const versions = new Set<string>();
+    for (const path of cargoPaths) {
+        versions.add(readCargoVersion(path));
+    }
+    for (const path of npmPaths) {
+        versions.add(readPackageVersion(path));
+    }
+    if (versions.size === 0) {
+        throw new Error("no crate or package versions found in workspace");
+    }
+    if (versions.size > 1) {
+        throw new Error(`workspace versions are out of sync: ${[...versions].sort().join(", ")}`);
+    }
+    return [...versions][0];
+}
+
+function readCargoVersion(path: string): string {
+    const original = readFileSync(path, "utf8");
+    const match = original.match(/^version\s*=\s*"([^"]*)"/m);
+    if (!match) {
+        throw new Error(`no [package].version found in ${path}`);
+    }
+    return match[1];
+}
+
+function readPackageVersion(path: string): string {
+    const parsed = JSON.parse(readFileSync(path, "utf8")) as { version?: string };
+    if (!parsed.version) {
+        throw new Error(`no version field in ${path}`);
+    }
+    return parsed.version;
+}
+
+export function bumpSemver(version: string, kind: BumpKind): string {
+    const match = version.match(/^(\d+)\.(\d+)\.(\d+)(?:-.*)?$/);
+    if (!match) {
+        throw new Error(`cannot bump non-semver version ${version}`);
+    }
+    let major = Number(match[1]);
+    let minor = Number(match[2]);
+    let patch = Number(match[3]);
+
+    switch (kind) {
+        case "patch":
+            patch += 1;
+            break;
+        case "minor":
+            minor += 1;
+            patch = 0;
+            break;
+        case "major":
+            major += 1;
+            minor = 0;
+            patch = 0;
+            break;
+    }
+
+    return `${major}.${minor}.${patch}`;
+}
+
+function collectCargoManifests(cratesDir: string): string[] {
+    if (!existsSync(cratesDir)) {
+        return [];
+    }
+    return readdirSync(cratesDir, { withFileTypes: true })
+        .filter((entry) => entry.isDirectory())
+        .map((entry) => join(cratesDir, entry.name, "Cargo.toml"))
+        .filter((path) => existsSync(path));
+}
+
+function collectPackageManifests(packagesDir: string): string[] {
+    if (!existsSync(packagesDir)) {
+        return [];
+    }
+    return readdirSync(packagesDir, { withFileTypes: true })
+        .filter((entry) => entry.isDirectory() && entry.name !== "node_modules")
+        .map((entry) => join(packagesDir, entry.name, "package.json"))
+        .filter((path) => existsSync(path));
+}
+
+function bumpCargoManifest(path: string, version: string, dryRun?: boolean): string {
+    const original = readFileSync(path, "utf8");
+    const next = original.replace(/^version\s*=\s*"[^"]*"/m, `version = "${version}"`);
+    if (next === original) {
+        throw new Error(`no [package].version found in ${path}`);
+    }
+    if (!dryRun) {
+        writeFileSync(path, next, "utf8");
+    }
+    return path;
+}
+
+function bumpPackageManifest(path: string, version: string, dryRun?: boolean): string {
+    const original = readFileSync(path, "utf8");
+    const parsed = JSON.parse(original) as { version?: string };
+    if (!parsed.version) {
+        throw new Error(`no version field in ${path}`);
+    }
+    parsed.version = version;
+    const next = `${JSON.stringify(parsed, null, 4)}\n`;
+    if (!dryRun) {
+        writeFileSync(path, next, "utf8");
+    }
+    return path;
+}
+
+function printReport(report: BumpReport, dryRun?: boolean): void {
+    const prefix = dryRun ? "would bump" : "bumped";
+    const kind = report.kind ? ` (${report.kind})` : "";
+    console.log(`${prefix} workspace ${report.root} ${report.from} -> ${report.to}${kind}`);
+    for (const path of report.cargo) {
+        console.log(`  cargo: ${path}`);
+    }
+    for (const path of report.npm) {
+        console.log(`  npm: ${path}`);
+    }
+}
+
+function printBumpHelp(): void {
+    console.log(`nifty bump — align all crate and package versions in the workspace
+
+Usage:
+  nifty bump                 # bump patch (default)
+  nifty bump patch
+  nifty bump minor
+  nifty bump major
+  nifty bump 1.2.3           # set explicit version
+  nifty bump --version 1.2.3
+  nifty bump --dry-run
+  nifty bump -C <cwd>
+`);
+}

package/src/cli/context.ts

@@ -0,0 +1,26 @@
+import { resolve } from "node:path";
+
+import { loadConfig } from "../config/loadConfig.js";
+
+/** Parse shared CLI flags used across nifty commands. */
+export function parseCliContext(argv: string[]): { cwd: string; dryRun: boolean } {
+    let cwd = process.cwd();
+    let dryRun = false;
+
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        if (arg === "--dry-run") {
+            dryRun = true;
+        } else if (arg === "-C" || arg === "--cwd") {
+            cwd = resolve(argv[++i] ?? cwd);
+        }
+    }
+
+    return { cwd, dryRun };
+}
+
+/** Ensure `nifty.config.*` exists before running a command (skip create on `--dry-run`). */
+export async function bootstrapNiftyConfig(argv: string[]): Promise<void> {
+    const { cwd, dryRun } = parseCliContext(argv);
+    await loadConfig({ cwd, createIfMissing: !dryRun });
+}

package/src/cli/index.ts

@@ -0,0 +1,8 @@
+export { runCli } from "./main.js";
+export { bumpSemver, bumpWorkspace, runBump, type BumpKind, type BumpOptions, type BumpReport } from "./bump.js";
+export { runPublish, type PublishOptions, type PublishReport } from "./publish.js";
+export { runTrust, type TrustReport } from "./trust.js";
+export { runUpdate } from "./update.js";
+export { runLint } from "./lint.js";
+export { runUpload } from "./upload.js";
+export { findWorkspaceRoot, listWorkspacePackages, type WorkspacePackage } from "./workspace.js";

package/src/cli/lint.ts

@@ -0,0 +1,109 @@
+import { loadNiftyNative } from "../native.js";
+
+const KNOWN_GITMOJIS = ["✨", "🎨", "🚀", "🐛", "🚑", "🔥", "💥", "♻️", "🔧", "📝", "👷", "🧹", "⬆️", "🧪", "🔨", "📦"];
+
+type LintOptions = {
+    subjects: string[];
+    from?: string;
+    to?: string;
+    cwd?: string;
+};
+
+type LintDiagnostic = {
+    rule: string;
+    severity: "error" | "warning";
+    message: string;
+    subject?: string;
+};
+
+export async function runLint(argv: string[], check: boolean): Promise<void> {
+    const options = parseLintArgs(argv);
+    const native = loadNiftyNative();
+    const subjects: string[] = [];
+
+    if (options.subjects.length > 0) {
+        subjects.push(...options.subjects);
+    } else {
+        const cwd = options.cwd ?? process.cwd();
+        const repoRoot = native.git["discover-root"](cwd);
+        const toRef = options.to ?? "HEAD";
+        const commits = native.git["collect-commits"](repoRoot, options.from, toRef);
+        subjects.push(...commits.map((commit) => commit.subject));
+    }
+
+    const diagnostics = subjects.flatMap((subject) => lintSubject(subject, native));
+    for (const item of diagnostics) {
+        const prefix = item.severity === "error" ? "error" : "warning";
+        const suffix = item.subject ? ` (${item.subject})` : "";
+        console.log(`${prefix} [${item.rule}] ${item.message}${suffix}`);
+    }
+
+    const errorCount = diagnostics.filter((item) => item.severity === "error").length;
+    if (check && errorCount > 0) {
+        throw new Error(`found ${errorCount} lint error(s)`);
+    }
+}
+
+function parseLintArgs(argv: string[]): LintOptions {
+    const options: LintOptions = { subjects: [] };
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        if (arg === "--from") {
+            options.from = argv[++i];
+        } else if (arg === "--to") {
+            options.to = argv[++i];
+        } else if (arg === "-C" || arg === "--cwd") {
+            options.cwd = argv[++i];
+        } else if (arg === "-s" || arg === "--subject") {
+            options.subjects.push(argv[++i]);
+        }
+    }
+    return options;
+}
+
+function lintSubject(subject: string, native: ReturnType<typeof loadNiftyNative>): LintDiagnostic[] {
+    const out: LintDiagnostic[] = [];
+    if (!native.gitmoji["validate-subject"](subject)) {
+        out.push({
+            rule: "gitmoji/subject",
+            severity: "error",
+            message: "commit subject must start with a known gitmoji followed by a space",
+            subject,
+        });
+        return out;
+    }
+
+    const gitmoji = native.gitmoji["leading-gitmoji"](subject);
+    if (gitmoji && !KNOWN_GITMOJIS.includes(gitmoji)) {
+        out.push({
+            rule: "gitmoji/known",
+            severity: "error",
+            message: `gitmoji ${gitmoji} is not in the Nifty known gitmoji list`,
+            subject,
+        });
+    }
+
+    const body = native.gitmoji["strip-gitmoji"](subject).trim();
+    if (!body) {
+        out.push({
+            rule: "gitmoji/body",
+            severity: "warning",
+            message: "commit subject body must not be empty after the gitmoji prefix",
+            subject,
+        });
+    }
+
+    if (gitmoji) {
+        const expected = native.gitmoji["format-subject"](gitmoji, body);
+        if (expected !== subject.trim()) {
+            out.push({
+                rule: "gitmoji/format",
+                severity: "warning",
+                message: `subject should be formatted as ${expected}`,
+                subject,
+            });
+        }
+    }
+
+    return out;
+}

package/src/cli/main.ts

@@ -0,0 +1,64 @@
+import { runBump } from "./bump.js";
+import { bootstrapNiftyConfig } from "./context.js";
+import { runLint } from "./lint.js";
+import { runPublish } from "./publish.js";
+import { runTrust } from "./trust.js";
+import { runUpdate } from "./update.js";
+import { runUpload } from "./upload.js";
+
+export async function runCli(argv: string[]): Promise<number> {
+    const [command, ...rest] = argv;
+
+    if (!command || command === "-h" || command === "--help") {
+        printHelp();
+        return 0;
+    }
+
+    try {
+        await bootstrapNiftyConfig(rest);
+        switch (command) {
+            case "update":
+                await runUpdate(rest);
+                return 0;
+            case "lint":
+                await runLint(rest, false);
+                return 0;
+            case "check":
+                await runLint(rest, true);
+                return 0;
+            case "upload":
+                await runUpload(rest);
+                return 0;
+            case "bump":
+                await runBump(rest);
+                return 0;
+            case "publish":
+                await runPublish(rest);
+                return 0;
+            case "trust":
+                await runTrust(rest);
+                return 0;
+            default:
+                console.error(`unknown command: ${command}`);
+                printHelp();
+                return 1;
+        }
+    } catch (error) {
+        console.error(`error: ${error instanceof Error ? error.message : String(error)}`);
+        return 1;
+    }
+}
+
+function printHelp(): void {
+    console.log(`nifty — Nifty tooling for hybrid cargo + npm projects
+
+Usage:
+  nifty update [-i] [-C cwd]
+  nifty lint [--from ref] [--to ref] [-s subject] [-C cwd]
+  nifty check [--from ref] [--to ref] [-s subject] [-C cwd]
+  nifty upload (--release | --pages | --both) [options]
+  nifty bump [patch|minor|major|version] [--dry-run] [-C cwd]
+  nifty publish [--dry-run] [--tag <tag>] [--access public] [-C cwd]
+  nifty trust [--only <pkg>] [--dry-run] [-C cwd]
+`);
+}

package/src/cli/publish.ts

@@ -0,0 +1,85 @@
+import { loadNiftyNative } from "../native.js";
+import { authPayload, parseAuthArgs } from "./authArgs.js";
+
+export type PublishOptions = {
+    cwd?: string;
+    dryRun?: boolean;
+    tag?: string;
+    access?: string;
+};
+
+export type PublishReport = {
+    root: string;
+    order: string[];
+    published: string[];
+    skipped: string[];
+};
+
+export async function runPublish(argv: string[]): Promise<void> {
+    const options = parsePublishArgs(argv);
+    const native = loadNiftyNative();
+    const report = native.publisher["publish-workspace"]({
+        cwd: options.cwd,
+        dryRun: options.dryRun,
+        tag: options.tag,
+        access: options.access,
+        ...authPayload(options.auth),
+    });
+    printReport(report, options.dryRun);
+}
+
+function parsePublishArgs(argv: string[]) {
+    let cwd: string | undefined;
+    let dryRun = false;
+    let tag: string | undefined;
+    let access = "public";
+    const auth = parseAuthArgs(argv);
+
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        if (arg === "--dry-run") {
+            dryRun = true;
+        } else if (arg === "-C" || arg === "--cwd") {
+            cwd = argv[++i];
+        } else if (arg === "--tag") {
+            tag = argv[++i];
+        } else if (arg === "--access") {
+            access = argv[++i];
+        } else if (arg === "-h" || arg === "--help") {
+            printPublishHelp();
+            process.exit(0);
+        } else if (arg.startsWith("-")) {
+            continue;
+        }
+    }
+
+    return { cwd, dryRun, tag, access, auth };
+}
+
+function printReport(report: PublishReport, dryRun?: boolean): void {
+    const prefix = dryRun ? "would publish" : "published";
+    console.log(`${prefix} workspace ${report.root}`);
+    if (report.skipped.length > 0) {
+        console.log(`skipped private packages: ${report.skipped.join(", ")}`);
+    }
+    console.log("publish order:");
+    for (const name of report.order) {
+        const marker = report.published.includes(name) ? prefix : "pending";
+        console.log(`  ${marker}: ${name}`);
+    }
+}
+
+function printPublishHelp(): void {
+    console.log(`nifty publish — publish workspace npm packages in dependency order
+
+OTP/TOTP is generated in nifty-publisher (set NPM_TOTP_SECRET in .env.placeholder.local).
+
+Usage:
+  nifty publish
+  nifty publish --dry-run
+  nifty publish --tag next
+  nifty publish --access public
+  nifty publish --otp 123456
+  nifty publish -C <cwd>
+`);
+}

package/src/cli/resolveNpm.ts

@@ -0,0 +1,16 @@
+import { existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+/** Resolve npm next to the active Node binary (Windows needs `npm.cmd`). */
+export function resolveNpmExecutable(): string {
+    if (process.env.NIFTY_NPM) {
+        return process.env.NIFTY_NPM;
+    }
+
+    const sibling = join(dirname(process.execPath), process.platform === "win32" ? "npm.cmd" : "npm");
+    if (existsSync(sibling)) {
+        return sibling;
+    }
+
+    return process.platform === "win32" ? "npm.cmd" : "npm";
+}