@edd_remonts/create-hermes-workspace 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Eduardo Inerarte
+
+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,132 @@
+# @edd_remonts/create-hermes-workspace
+
+[![npm version](https://img.shields.io/npm/v/@edd_remonts/create-hermes-workspace.svg)](https://www.npmjs.com/package/@edd_remonts/create-hermes-workspace)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
+[![Node ≥ 18](https://img.shields.io/badge/node-%E2%89%A518-brightgreen.svg)](https://nodejs.org)
+[![Docker](https://img.shields.io/badge/docker-required-blue.svg)](https://www.docker.com)
+
+> Bootstrap a [Hermes Agent](https://github.com/nousresearch/hermes-agent) workspace with one command. Clones the canonical `create-hermes-workspace` repo, copies `.env.example` → `.env`, and prints what to do next.
+
+## Install
+
+You don't install it — you run it. The whole point is a single `npx` invocation.
+
+```bash
+npx @edd_remonts/create-hermes-workspace
+```
+
+The first run downloads the package, executes the CLI, and exits. There's nothing to add to your `package.json` and nothing to remove.
+
+## Usage
+
+```bash
+# Default — creates ./hermes-workspace
+npx @edd_remonts/create-hermes-workspace
+
+# Custom folder
+npx @edd_remonts/create-hermes-workspace my-projects
+
+# Absolute path
+npx @edd_remonts/create-hermes-workspace /opt/workspaces/hermes
+
+# Help
+npx @edd_remonts/create-hermes-workspace --help
+
+# Version
+npx @edd_remonts/create-hermes-workspace --version
+```
+
+### What it does
+
+1. Verifies you have Node 18 or higher.
+2. Validates the target folder name (POSIX-safe characters only).
+3. Refuses to overwrite a non-empty folder.
+4. Shallow-clones [`eddremonts86/create-hermes-workspace`](https://github.com/eddremonts86/create-hermes-workspace) from GitHub.
+5. Copies the cloned `.env.example` to `.env` so you can start editing.
+6. Prints a "what to do next" panel pointing you at `docker compose up -d`.
+
+No telemetry, no analytics, no network calls beyond the `git clone`.
+
+## Requirements
+
+- **Node.js 18 or higher** — to run the CLI itself.
+- **Git** — to clone the workspace repo (`brew install git`, `apt install git`, etc.).
+- **SSH access to GitHub** — the CLI uses `git@github.com:...` so the repo must be reachable over SSH. Run `ssh -T git@github.com` once to confirm. (If you only have HTTPS auth, see [FAQ](#faq).)
+- **Docker** — only required *after* the CLI finishes, to start the workspace container.
+
+## Programmatic API
+
+This package is a CLI, not a library. It has no exported JavaScript API. If you need to script workspace creation, run the CLI from your shell:
+
+```bash
+npx --yes @edd_remonts/create-hermes-workspace "$WORKSPACE_NAME"
+```
+
+Exit codes:
+
+| Code | Meaning |
+|------|---------|
+| `0`  | Success. |
+| `2`  | Pre-flight failure (invalid name, target not empty, Node < 18). |
+| `3`  | `git` not found on `PATH`. |
+| `4`  | `git clone` failed (network, auth, repo missing). |
+| other | Bubbled up from `git clone`. |
+
+## What gets cloned
+
+The CLI pulls [`eddremonts86/create-hermes-workspace`](https://github.com/eddremonts86/create-hermes-workspace), which contains:
+
+- `Dockerfile` + `docker-compose.yml` — pre-wired for the Hermes agent.
+- `.env.example` — annotated, with only the keys a colleague must set.
+- `AGENTS.md` — the workflow rules (superpowers methodology, 4 hard gates).
+- `Makefile` — `make up`, `make shell`, `make new-project NAME=foo`, `make reset`.
+- `scripts/bootstrap.sh` — non-Docker one-shot installer.
+- `skills/` — a curated subset of reusable skills.
+- `README.md` — the world-class onboarding doc (this is the one to read next).
+
+After cloning, **`cd` into the folder and read its README**. That's where the workspace workflow lives.
+
+## FAQ
+
+**Q: I have a "Permission denied (publickey)" error.**
+A: The CLI uses SSH. Set up an SSH key on GitHub: https://docs.github.com/en/authentication/connecting-to-github-with-ssh. Or clone the repo manually with HTTPS first, then re-run the CLI.
+
+**Q: I already have a folder called `hermes-workspace`.**
+A: The CLI refuses to overwrite a non-empty folder. Either remove it (`rm -rf hermes-workspace`) or pass a different name (`npx @edd_remonts/create-hermes-workspace my-v2-ws`).
+
+**Q: Can I run this on Windows?**
+A: Yes — use [WSL2](https://learn.microsoft.com/en-us/windows/wsl/install) (Windows Subsystem for Linux). Run the CLI from inside your WSL distribution. Native PowerShell works for the `git clone` but Docker Desktop's WSL2 backend is the supported path for the container.
+
+**Q: Why isn't this just `npm install -g`?**
+A: Because you don't want it globally — you want it on-demand, always at the latest version, and never on your `package.json`. `npx` is exactly the right tool for "run this once, then forget about it."
+
+**Q: How is this different from `@edd_remonts/create-edd-app`?**
+A: They solve different problems:
+- `@edd_remonts/create-hermes-workspace` (this package) → **the dev environment**: agent, skills, Dockerfile, env config. One per machine.
+- `@edd_remonts/create-edd-app` → **a single application**: TanStack Start + Drizzle + shadcn stack. One per project.
+
+You'll usually run this once, then run `create-edd-app` many times inside it.
+
+**Q: My .env was overwritten!**
+A: The CLI only copies `.env.example` → `.env` if `.env` doesn't already exist (or if the target folder was just created by the clone). It will not overwrite an existing `.env`. If you want to re-copy, `cp .env.example .env` manually.
+
+**Q: How do I publish a new version?**
+A: Inside this package's repo: `npm version patch` (or `minor` / `major`), then `npm publish --access public`. The package's `scripts/publish.sh` (in the workspace repo, not here) wraps that with a token-prompt dance.
+
+**Q: Is telemetry collected?**
+A: No. The CLI makes exactly one network call: `git clone`. No analytics, no phone-home, no error reporting.
+
+## See also
+
+- [`eddremonts86/create-hermes-workspace`](https://github.com/eddremonts86/create-hermes-workspace) — the repo this CLI clones. **Read its README after running the CLI.**
+- [`@edd_remonts/create-edd-app`](https://www.npmjs.com/package/@edd_remonts/create-edd-app) — bootstrap a new app from the edd-app-template.
+- [`nousresearch/hermes-agent`](https://github.com/nousresearch/hermes-agent) — the underlying agent runtime.
+- [`eddremonts86/edd-app-template`](https://github.com/eddremonts86/edd-app-template) — the default app scaffold used inside a workspace.
+
+## License
+
+MIT © 2026 Eduardo Inerarte. See [LICENSE](./LICENSE) for the full text.
+
+## Contributing
+
+Issues and PRs welcome at https://github.com/eddremonts86/create-hermes-workspace/issues.

package/bin/create-hermes-workspace.js

@@ -0,0 +1,121 @@
+#!/usr/bin/env node
+// create-hermes-workspace — bootstrap a Hermes Agent workspace with one command.
+// Tests pass CHW_FAKE_GIT to avoid real network access in CI.
+import { spawnSync } from 'node:child_process';
+import { existsSync, mkdirSync, copyFileSync, statSync, writeFileSync, chmodSync, readFileSync, readdirSync } from 'node:fs';
+import { join, resolve, isAbsolute } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = fileURLToPath(new URL('.', import.meta.url));
+const PKG_PATH = join(__dirname, '..', 'package.json');
+const PKG = JSON.parse(readFileSync(PKG_PATH, 'utf8'));
+const REPO_URL = PKG.repository.url.replace(/^git\+/, '').replace(/\.git$/, '') + '.git';
+
+// ---- arg parsing -----------------------------------------------------------
+const args = process.argv.slice(2);
+if (args.includes('--help') || args.includes('-h')) {
+  printHelp();
+  process.exit(0);
+}
+if (args.includes('--version') || args.includes('-V')) {
+  process.stdout.write(`${PKG.version}\n`);
+  process.exit(0);
+}
+const targetArg = args.find((a) => !a.startsWith('-'));
+const target = resolve(process.cwd(), targetArg || 'hermes-workspace');
+
+// ---- preconditions --------------------------------------------------------
+const major = parseInt(process.versions.node.split('.')[0], 10);
+if (major < 18) {
+  process.stderr.write(`\u2716  Node 18 or higher required. You are running ${process.versions.node}.\n`);
+  process.exit(2);
+}
+if (!/^[A-Za-z0-9._\-/]+$/.test(target)) {
+  process.stderr.write(`\u2716  Invalid target folder: ${target}\n`);
+  process.exit(2);
+}
+if (existsSync(target)) {
+  const st = statSync(target);
+  if (st.isDirectory()) {
+    // Allow if empty
+    if (readdirSync(target).length > 0) {
+      process.stderr.write(`\u2716  Target folder already exists and is not empty: ${target}\n`);
+      process.stderr.write(`   Re-run with a different name, or remove it first: rm -rf ${target}\n`);
+      process.exit(2);
+    }
+  } else {
+    process.stderr.write(`\u2716  Target exists and is not a directory: ${target}\n`);
+    process.exit(2);
+  }
+}
+
+// ---- clone -----------------------------------------------------------------
+let clone;
+if (process.env.CHW_FAKE_GIT) {
+  // Test mode: simulate clone by mkdir + writing a fake .env.example
+  clone = { status: 0, stdout: '', stderr: '' };
+  mkdirSync(target, { recursive: true });
+  writeFileSync(join(target, '.env.example'), '# test fixture\nFOO=bar\n');
+  writeFileSync(join(target, 'README.md'), '# fixture\n');
+} else {
+  const git = process.env.CHW_GIT_BIN || 'git';
+  // Sanity check: git is on PATH
+  const probe = spawnSync(git, ['--version'], { stdio: 'pipe' });
+  if (probe.status !== 0) {
+    process.stderr.write(`\u2716  git is required but was not found on PATH.\n`);
+    process.stderr.write(`   Install git: https://git-scm.com/downloads\n`);
+    process.exit(3);
+  }
+  process.stdout.write(`\u2937  Cloning ${REPO_URL} into ${target}\u2026\n`);
+  clone = spawnSync(git, ['clone', '--depth', '1', REPO_URL, target], {
+    stdio: ['ignore', 'inherit', 'inherit'],
+  });
+  if (clone.status !== 0) {
+    process.stderr.write(`\u2716  git clone failed (exit ${clone.status}).\n`);
+    process.exit(clone.status || 4);
+  }
+}
+
+// ---- .env.example -> .env --------------------------------------------------
+try {
+  const envExample = join(target, '.env.example');
+  if (existsSync(envExample)) {
+    copyFileSync(envExample, join(target, '.env'));
+    process.stdout.write(`\u2713  Created .env from .env.example \u2014 open it and fill in your keys.\n`);
+  }
+} catch (e) {
+  // Warn but don't abort
+  process.stderr.write(`\u26a0  Could not copy .env.example to .env: ${e.message}\n`);
+  process.stderr.write(`   You can copy it manually: cp .env.example .env\n`);
+}
+
+// ---- success panel ---------------------------------------------------------
+process.stdout.write(`\n\u2705  Hermes workspace ready in ${target}\n\n`);
+process.stdout.write(`  Next steps:\n`);
+process.stdout.write(`    1. cd ${target}\n`);
+process.stdout.write(`    2. Open .env and fill in your AI provider keys (MINIMAX_API_KEY, etc.)\n`);
+process.stdout.write(`    3. docker compose up -d              # start the container\n`);
+process.stdout.write(`    4. docker compose exec hermes bash   # open a shell inside\n`);
+process.stdout.write(`    5. Inside the container: hermes chat  # talk to the agent\n\n`);
+process.stdout.write(`  Docs:   https://github.com/eddremonts86/create-hermes-workspace\n`);
+process.stdout.write(`  Issues: https://github.com/eddremonts86/create-hermes-workspace/issues\n\n`);
+process.exit(0);
+
+function printHelp() {
+  process.stdout.write(`create-hermes-workspace v${PKG.version}\n\n`);
+  process.stdout.write(`Usage: create-hermes-workspace [folder] [options]\n\n`);
+  process.stdout.write(`Bootstrap a Hermes Agent workspace by cloning the canonical\n`);
+  process.stdout.write(`create-hermes-workspace repo into <folder> (default: ./hermes-workspace).\n\n`);
+  process.stdout.write(`Arguments:\n`);
+  process.stdout.write(`  [folder]              Target folder. Relative paths resolve from $PWD.\n`);
+  process.stdout.write(`                       Defaults to ./hermes-workspace.\n\n`);
+  process.stdout.write(`Options:\n`);
+  process.stdout.write(`  -h, --help            Show this help.\n`);
+  process.stdout.write(`  -V, --version         Print version and exit.\n\n`);
+  process.stdout.write(`Examples:\n`);
+  process.stdout.write(`  $ create-hermes-workspace\n`);
+  process.stdout.write(`  $ create-hermes-workspace my-ws\n`);
+  process.stdout.write(`  $ create-hermes-workspace /tmp/hermes-ws\n\n`);
+  process.stdout.write(`Repo:   https://github.com/eddremonts86/create-hermes-workspace\n`);
+  process.stdout.write(`npm:    https://www.npmjs.com/package/@edd_remonts/create-hermes-workspace\n`);
+}

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@edd_remonts/create-hermes-workspace",
+  "version": "0.1.0",
+  "description": "Bootstrap a Hermes Agent workspace with one command.",
+  "type": "module",
+  "bin": {
+    "create-hermes-workspace": "bin/create-hermes-workspace.js"
+  },
+  "files": [
+    "bin/",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test 'test/**/*.test.js'"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/eddremonts86/create-hermes-workspace.git"
+  },
+  "bugs": {
+    "url": "https://github.com/eddremonts86/create-hermes-workspace/issues"
+  },
+  "homepage": "https://github.com/eddremonts86/create-hermes-workspace#readme",
+  "keywords": [
+    "hermes",
+    "hermes-agent",
+    "workspace",
+    "scaffold",
+    "create",
+    "cli"
+  ],
+  "author": "Eduardo Inerarte <eddremonts86@gmail.com>",
+  "license": "MIT",
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  }
+}