create-neoink 0.1.0

package/README.md

@@ -0,0 +1,54 @@
+# create-neoink
+
+Scaffold a Neovim plugin built with [neoink](https://github.com/NicholasZolton/neoink)
+(React → Neovim).
+
+```bash
+bun create neoink my-plugin
+# or
+bunx create-neoink my-plugin
+```
+
+Generates a self-contained plugin project:
+
+```
+my-plugin/
+  host.tsx              a starter React app (a small counter)
+  plugin/my-plugin.lua  registers :MyPlugin, jobstarts the built host
+  package.json          @neoinkjs/* + react deps, build scripts
+  tsconfig.json .gitignore .luarc.json README.md
+```
+
+Then:
+
+```bash
+cd my-plugin
+bun install
+bun run build      # -> dist/host (standalone binary; nothing needed at runtime)
+# in Neovim: :MyPlugin
+```
+
+Edit `host.tsx` — it's an ordinary React app; neoink renders it into a Neovim
+window. Install it with any plugin manager (the generated README has a lazy.nvim
+snippet).
+
+## Developing against a local neoink checkout
+
+Before the `@neoinkjs/*` packages are published (or to hack on neoink itself),
+point the generated project at a checkout:
+
+```bash
+bunx create-neoink my-plugin --local /path/to/neoink
+```
+
+This wires `tsconfig.json` paths to the checkout's source and symlinks a single
+React copy (so hooks don't throw "invalid hook call"), instead of depending on
+the published packages.
+
+## Options
+
+- `--name <name>` — plugin/command base name (default: the target directory
+  name). `my-plugin` → command `:MyPlugin`.
+- `--local <path>` — wire to a neoink checkout instead of the registry.
+
+Requires [Bun](https://bun.sh) to build and run.

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "create-neoink",
+  "version": "0.1.0",
+  "description": "Scaffold a Neovim plugin built with neoink (React → Neovim).",
+  "license": "MIT",
+  "author": "Nicholas Zolton",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/NicholasZolton/neoink.git",
+    "directory": "packages/create-neoink"
+  },
+  "homepage": "https://github.com/NicholasZolton/neoink#readme",
+  "keywords": ["neovim", "nvim", "react", "tui", "neoink", "create", "scaffold"],
+  "type": "module",
+  "bin": {
+    "create-neoink": "./src/index.ts"
+  },
+  "files": ["src"],
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/index.ts

@@ -0,0 +1,365 @@
+#!/usr/bin/env bun
+/**
+ * create-neoink — scaffold a Neovim plugin built with neoink.
+ *
+ *   bun create neoink <dir>            # wired to the published @neoinkjs/* packages
+ *   bunx create-neoink <dir>
+ *   bunx create-neoink <dir> --local /path/to/neoink   # wired to a local checkout
+ *
+ * Generates a self-contained plugin project: a starter `host.tsx`, the Neovim
+ * `plugin/<name>.lua` that jobstarts the built host, build scripts, tsconfig,
+ * and a README. `--local` points it at a neoink checkout (tsconfig paths + a
+ * React symlink) for developing before the packages are on npm; otherwise it
+ * depends on `@neoinkjs/*` from the registry.
+ */
+import { mkdirSync, writeFileSync, existsSync } from "node:fs";
+import { basename, resolve, join, relative, dirname } from "node:path";
+
+interface Args {
+  dir: string;
+  name: string;
+  local?: string; // absolute path to a neoink checkout
+}
+
+function parseArgs(argv: string[]): Args {
+  let dir: string | undefined;
+  let name: string | undefined;
+  let local: string | undefined;
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]!;
+    if (a === "--local") local = resolve(argv[++i] ?? "");
+    else if (a === "--name") name = argv[++i];
+    else if (!a.startsWith("-") && dir === undefined) dir = a;
+  }
+  if (dir === undefined) {
+    console.error("usage: create-neoink <dir> [--name <plugin-name>] [--local <path-to-neoink>]");
+    process.exit(1);
+  }
+  const pkgName = (name ?? basename(dir)).replace(/[^a-zA-Z0-9-]/g, "-").toLowerCase();
+  return { dir: resolve(dir), name: pkgName, local };
+}
+
+/** kebab/space -> PascalCase, for the `:Command` name. */
+function pascal(s: string): string {
+  return s
+    .split(/[-_\s]+/)
+    .filter(Boolean)
+    .map((w) => w.charAt(0).toUpperCase() + w.slice(1))
+    .join("");
+}
+
+function main(): void {
+  const args = parseArgs(process.argv.slice(2));
+  const command = pascal(args.name);
+  const luaName = args.name;
+
+  if (existsSync(args.dir)) {
+    console.error(`refusing to overwrite existing path: ${args.dir}`);
+    process.exit(1);
+  }
+  mkdirSync(join(args.dir, "plugin"), { recursive: true });
+
+  const write = (rel: string, content: string): void => {
+    const p = join(args.dir, rel);
+    mkdirSync(dirname(p), { recursive: true });
+    writeFileSync(p, content);
+  };
+
+  // ── package.json ──────────────────────────────────────────────────────────
+  const scripts = args.local
+    ? {
+        // Absolute target: --local is inherently machine-specific (the checkout
+        // path is baked in), and it avoids the off-by-one a relative path from
+        // node_modules/ invites. Keeps a single React instance shared with the
+        // checkout so hooks don't throw "invalid hook call".
+        "link-react": "rm -rf node_modules/react && ln -s " + join(args.local, "node_modules/react") + " node_modules/react",
+        build: "bun run link-react && bun build ./host.tsx --compile --outfile dist/host",
+        "build:js": "bun run link-react && bun build ./host.tsx --target=bun --outfile dist/host.js",
+      }
+    : {
+        build: "bun build ./host.tsx --compile --outfile dist/host",
+        "build:js": "bun build ./host.tsx --target=bun --outfile dist/host.js",
+      };
+  const pkg: Record<string, unknown> = {
+    name: args.name,
+    version: "0.0.0",
+    private: true,
+    type: "module",
+    scripts,
+    devDependencies: {
+      "@types/bun": "latest",
+      "@types/react": "^19.0.0",
+      "@typescript/native-preview": "latest",
+    },
+  };
+  if (!args.local) {
+    pkg.dependencies = {
+      "@neoinkjs/core": "^0.1.0",
+      "@neoinkjs/components": "^0.1.0",
+      "@neoinkjs/plugin": "^0.1.0",
+      react: "^19.0.0",
+    };
+  }
+  write("package.json", JSON.stringify(pkg, null, 2) + "\n");
+
+  // ── tsconfig.json ─────────────────────────────────────────────────────────
+  const paths = args.local
+    ? {
+        "@neoinkjs/*": [relative(args.dir, join(args.local, "packages")) + "/*/src/index.ts"],
+      }
+    : undefined;
+  const tsconfig = {
+    compilerOptions: {
+      lib: ["ESNext"],
+      target: "ESNext",
+      module: "ESNext",
+      moduleResolution: "bundler",
+      jsx: "react-jsx",
+      jsxImportSource: "react",
+      types: ["bun", "react"],
+      strict: true,
+      skipLibCheck: true,
+      allowImportingTsExtensions: true,
+      noEmit: true,
+      ...(paths ? { paths } : {}),
+    },
+    include: ["host.tsx", "src", "test"],
+  };
+  write("tsconfig.json", JSON.stringify(tsconfig, null, 2) + "\n");
+
+  // ── host.tsx (starter app) ────────────────────────────────────────────────
+  write(
+    "host.tsx",
+    `/**
+ * ${args.name} — neoink plugin host. Mounts <App/> into a Neovim window with
+ * @neoinkjs/plugin's mount(). Built to dist/host (see package.json), which
+ * plugin/${luaName}.lua jobstarts. The import.meta.main guard keeps mount()
+ * from firing when this module is merely imported (e.g. by a test).
+ */
+import React, { useState } from "react";
+import { mount } from "@neoinkjs/plugin";
+import { useApp, useInput, type Key } from "@neoinkjs/core";
+import { Box, Text } from "@neoinkjs/components";
+
+export function App(): React.ReactElement {
+  const [count, setCount] = useState(0);
+  const { exit } = useApp();
+
+  useInput((input: string, key: Key) => {
+    if (input === "+" || input === "k" || key.upArrow) setCount((c) => c + 1);
+    else if (input === "-" || input === "j" || key.downArrow) setCount((c) => c - 1);
+    else if (input === "q" || key.escape) exit();
+  });
+
+  return (
+    <Box flexDirection="column" borderStyle="round" borderColor="cyan" paddingLeft={2} paddingRight={2} paddingTop={1} paddingBottom={1}>
+      <Text bold color="cyan">${command}</Text>
+      <Box marginTop={1}>
+        <Text>count: <Text bold color="yellow">{String(count)}</Text></Text>
+      </Box>
+      <Box marginTop={1}>
+        <Text color="gray">j/k or +/- to change · q to quit</Text>
+      </Box>
+    </Box>
+  );
+}
+
+if (import.meta.main) {
+  const handle = await mount(<App />, { style: "float" });
+  await handle.waitUntilExit();
+  handle.unmount();
+  process.exit(0);
+}
+`,
+  );
+
+  // ── plugin/<name>.lua ─────────────────────────────────────────────────────
+  const luaPath = args.local
+    ? `-- neoink is a local checkout; point package.path at its bundled Lua.
+local neoink_lua = "${join(args.local, "packages/plugin/lua")}"`
+    : `-- neoink's Lua bootstrap ships inside the installed @neoinkjs/plugin package.
+local neoink_lua = here .. "/node_modules/@neoinkjs/plugin/lua"`;
+  write(
+    `plugin/${luaName}.lua`,
+    `-- Neovim entry point for ${args.name}. Registers :${command}, which jobstarts
+-- this project's build output (dist/host if compiled, else \`bun run
+-- dist/host.js\`) over neoink's RPC stdio channel.
+local this_file = debug.getinfo(1, "S").source:sub(2)
+local here = vim.fn.fnamemodify(this_file, ":h:h") -- project root
+
+${luaPath}
+if not package.path:find(neoink_lua, 1, true) then
+  package.path = neoink_lua .. "/?.lua;" .. neoink_lua .. "/?/init.lua;" .. package.path
+end
+
+vim.api.nvim_create_user_command("${command}", function()
+  require("neoink").start({ dir = here })
+end, {
+  desc = "Open ${args.name} (built with neoink)",
+})
+`,
+  );
+
+  // ── .gitignore / .luarc.json / README ─────────────────────────────────────
+  write(".gitignore", "dist/\nnode_modules/\n");
+  write(
+    ".luarc.json",
+    JSON.stringify(
+      {
+        $schema: "https://raw.githubusercontent.com/LuaLS/vscode-lua/master/setting/schema.json",
+        "runtime.version": "LuaJIT",
+        "diagnostics.globals": ["vim"],
+        "workspace.checkThirdParty": false,
+      },
+      null,
+      2,
+    ) + "\n",
+  );
+
+  const installNote = args.local
+    ? `> Wired to a local neoink checkout at \`${args.local}\` (tsconfig paths + a
+> React symlink via the \`link-react\` script). Publish neoink and switch to the
+> \`@neoinkjs/*\` dependencies for a normal install.`
+    : `Depends on the published \`@neoinkjs/*\` packages plus \`react\`.`;
+  write(
+    "README.md",
+    `# ${args.name}
+
+A Neovim plugin built with [neoink](https://github.com/NicholasZolton/neoink).
+Run \`:${command}\` to open it.
+
+${installNote}
+
+## Develop
+
+\`\`\`bash
+bun install
+bunx tsgo --noEmit   # typecheck
+bun run build        # -> dist/host (standalone binary)
+\`\`\`
+
+## Install (lazy.nvim)
+
+\`\`\`lua
+{
+  dir = "${args.dir}",           -- or "you/${args.name}" once pushed to GitHub
+  name = "${args.name}",
+  build = "bun install && bun run build",
+  cmd = "${command}",
+}
+\`\`\`
+
+Edit \`host.tsx\` — it's a normal React app; neoink renders it into a Neovim
+window. \`plugin/${luaName}.lua\` registers the \`:${command}\` command.
+
+## Zero-dependency installs (prebuilt binaries)
+
+By default \`build\` compiles the host locally (users need Bun). To let users
+install with **nothing** installed:
+
+1. Push a version tag (\`git tag v0.1.0 && git push --tags\`).
+   \`.github/workflows/release.yml\` cross-compiles the host for macOS/Linux
+   (arm64 + x64) and attaches the binaries to the GitHub Release.
+2. Point your plugin manager's build step at the downloader and set your repo:
+
+   \`\`\`lua
+   build = "NEOINK_PLUGIN_REPO=you/${args.name} bun scripts/fetch-host.ts",
+   \`\`\`
+
+   \`scripts/fetch-host.ts\` downloads the binary matching the user's platform
+   from your latest release, and falls back to a local \`bun --compile\` if the
+   download fails (no release yet, offline, or an unsupported platform).
+`,
+  );
+
+  // ── Phase 3: prebuilt-binary CI + download flow (opt-in) ──────────────────
+  // A release workflow cross-compiles the host for every platform and attaches
+  // the binaries to a GitHub Release; `scripts/fetch-host.ts` downloads the one
+  // matching the user's platform (falling back to a local compile). Zero-dep
+  // installs when the author opts in; see the generated README.
+  write(
+    ".github/workflows/release.yml",
+    `name: release
+on:
+  push:
+    tags: ["v*"]
+permissions:
+  contents: write
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: oven-sh/setup-bun@v2
+      - run: bun install
+      - name: cross-compile host for every platform
+        run: |
+          for t in bun-darwin-arm64 bun-darwin-x64 bun-linux-x64 bun-linux-arm64; do
+            bun build ./host.tsx --compile --target=$t --outfile "host-$t"
+          done
+      - uses: softprops/action-gh-release@v2
+        with:
+          files: host-bun-*
+`,
+  );
+  write(
+    "scripts/fetch-host.ts",
+    `#!/usr/bin/env bun
+/**
+ * Fetch the prebuilt host binary for this platform from the plugin's latest
+ * GitHub release, or fall back to a local \`bun build --compile\`. Point a
+ * plugin manager's build step here (e.g. lazy.nvim \`build = "bun
+ * scripts/fetch-host.ts"\`) and set NEOINK_PLUGIN_REPO="you/${args.name}" for
+ * zero-dependency installs; with no repo set (or on an unsupported platform,
+ * or offline) it just compiles locally, so it always produces dist/host.
+ */
+import { mkdirSync, chmodSync } from "node:fs";
+
+const REPO = process.env.NEOINK_PLUGIN_REPO ?? "";
+
+function target(): string | null {
+  const p = process.platform;
+  const a = process.arch;
+  if (p === "darwin" && a === "arm64") return "bun-darwin-arm64";
+  if (p === "darwin" && a === "x64") return "bun-darwin-x64";
+  if (p === "linux" && a === "x64") return "bun-linux-x64";
+  if (p === "linux" && a === "arm64") return "bun-linux-arm64";
+  return null;
+}
+
+function localBuild(): never {
+  console.log("building host locally (bun --compile)…");
+  const proc = Bun.spawnSync(["bun", "build", "./host.tsx", "--compile", "--outfile", "dist/host"], {
+    stdout: "inherit",
+    stderr: "inherit",
+  });
+  process.exit(proc.exitCode ?? 1);
+}
+
+const t = target();
+if (!REPO || t === null) localBuild();
+
+mkdirSync("dist", { recursive: true });
+const url = \`https://github.com/\${REPO}/releases/latest/download/host-\${t}\`;
+try {
+  const res = await fetch(url);
+  if (!res.ok) throw new Error(\`HTTP \${res.status}\`);
+  await Bun.write("dist/host", res);
+  chmodSync("dist/host", 0o755);
+  console.log(\`downloaded prebuilt host (\${t})\`);
+} catch (err) {
+  console.log(\`prebuilt download failed (\${String(err)}); building locally\`);
+  localBuild();
+}
+`,
+  );
+
+  console.log(`\n✓ created ${args.name} at ${args.dir}\n`);
+  console.log("next:");
+  console.log(`  cd ${relative(process.cwd(), args.dir) || args.dir}`);
+  console.log("  bun install");
+  console.log("  bun run build");
+  console.log(`  # then in Neovim: :${command}\n`);
+}
+
+main();