@eventmodelers/cli 1.0.3 → 1.0.5

package/README.md

@@ -101,6 +101,7 @@ Which skills install depends on the chosen stack — see `stacks/<name>/template
 
 ```bash
 npx @eventmodelers/cli init --stack <name>          # scaffold a stack + install + configure (alias: install)
+npx @eventmodelers/cli re-init                      # refresh an already-installed kit's scripts/skills only — never touches the root scaffold
 npx @eventmodelers/cli run                          # start the agent loop (ralph-claude.js) from the installed kit dir
 npx @eventmodelers/cli run --ollama                 # same, via local Ollama (ralph-ollama.js)
 npx @eventmodelers/cli run --bash                   # bash-only loop, no realtime (ralph.sh)
@@ -306,6 +307,19 @@ npx @eventmodelers/cli listen --port 4000            # same, on a different port
 
 `listen` is a dispatcher for `<kit-dir>/code-export.mjs` — a local HTTP server (port 3001 by default) that the eventmodelers board UI posts slice/screen data to, which then gets written under `<kit-dir>/.slices/`. Unlike `fetch`, it does receive screen images, since the board UI pushes them directly.
 
+### Re-init — refresh scripts/skills without touching your app
+
+```bash
+npx @eventmodelers/cli re-init                      # refresh the installed build kit (.build-kit/) + its skills
+npx @eventmodelers/cli re-init --modeling            # refresh the modeling kit (.agent-modeling-kit/) + its skills
+```
+
+`re-init` re-runs `init` against whichever stack `install-manifest.json` says was installed (no need to pass `--stack` again), but skips step 2 of `init` entirely — the root project scaffold (`package.json`, `src/`, `server.ts`, `docker-compose.yml`, etc.) and the root `CLAUDE.md` router are never touched. Use it after upgrading the CLI to pick up fixes to `ralph.js`/`ralph.sh`/skills without re-scaffolding a project you've since built on top of.
+
+Credentials are left alone unless you pass `--force` — same rule `init` already follows when everything required is already configured. `--global` defaults to however skills were originally installed; pass it explicitly to move them.
+
+If the kit dir predates install-manifest.json tracking, or was installed via `init --git <url>` (a community/custom stack, not one of the built-in `STACKS` keys), `re-init` can't tell what to re-copy and tells you to re-run the original `init` command by hand instead.
+
 ### Uninstall
 
 Every `init`/`init-modeling` run writes an install manifest into `<kit-dir>/.eventmodelers/install-manifest.json` recording exactly what it put down. `uninstall` reads that manifest back and removes only:

package/cli.js

@@ -754,6 +754,10 @@ async function installStack(stackKey, stackCfg, options = {}) {
     }
 
     // --- 2. Spread stack scaffold files into the project root ---
+    // Skipped entirely by `re-init` (options.skipRootScaffold) — that command only
+    // refreshes an already-scaffolded project's kit dir + skills, and must never
+    // re-touch root/ files the user has since built on top of, nor the root
+    // CLAUDE.md router below.
     const rootSrc = join(templatesSource, 'root');
     // root/CLAUDE.md is never copied to the project root directly (see step 3 below) —
     // built-in stacks no longer ship one at all, and an outdated community/--git stack
@@ -761,7 +765,7 @@ async function installStack(stackKey, stackCfg, options = {}) {
     // copy must never let it slip through to root and clobber the shared router there.
     const stackRootClaudeSrc = join(rootSrc, 'CLAUDE.md');
     const stackShipsOwnRootClaude = existsSync(stackRootClaudeSrc);
-    if (existsSync(rootSrc)) {
+    if (!options.skipRootScaffold && existsSync(rootSrc)) {
       console.log('📦 Installing project files...');
       // .gitignore is the one file every stack's root/ ships that can collide with
       // another already-installed kit's own .gitignore (e.g. modeling-kit + a build-kit
@@ -796,7 +800,7 @@ async function installStack(stackKey, stackCfg, options = {}) {
     // instead of silently guessing either way.
     const rootClaudeDest = join(targetDir, 'CLAUDE.md');
     const sharedRootClaude = join(__dirname, 'shared', 'root-claude', 'CLAUDE.md');
-    const routerContent = existsSync(sharedRootClaude) ? readFileSync(sharedRootClaude, 'utf-8') : null;
+    const routerContent = options.skipRootScaffold ? null : (existsSync(sharedRootClaude) ? readFileSync(sharedRootClaude, 'utf-8') : null);
     if (routerContent !== null) {
       if (!existsSync(rootClaudeDest)) {
         writeFileSync(rootClaudeDest, routerContent);
@@ -1161,39 +1165,50 @@ function ensureMcpRegistered(projectDir, baseUrl) {
 // process spawns `claude` (true for `run --modeling`'s own spawn). It is NOT true
 // for an interactive session opened directly in the project right after
 // `init`/`init-config` — that `claude` process inherits the user's shell env,
-// which never had a reason to already have this var set. Without a `.env` to
-// resolve it from, `.mcp.json`'s `${EVENTMODELERS_TOKEN}` placeholder resolves to
-// empty, the MCP server gets an empty x-token header, and the connection fails —
-// silently, until something happens to trigger the `connect` skill's own Step 3.5,
-// which writes this same file. Do it here too so a fresh interactive session works
-// without depending on that skill having run first.
+// which never had a reason to already have this var set.
+//
+// A plain `.env` file does NOT fix this — Claude Code never sources one; per its
+// own docs, an unresolved `.mcp.json` placeholder is left as the literal
+// `${EVENTMODELERS_TOKEN}` text, which fails auth and falls back to an OAuth
+// flow the eventmodelers server can't actually satisfy for this client. The
+// only things Claude Code itself resolves `.mcp.json` placeholders against are
+// the inherited shell env and its own settings files' `env` block. `.claude/
+// settings.local.json` is the documented per-user, gitignored-by-convention
+// scope for exactly this — same idea as `.eventmodelers/config.json` already
+// holding the raw token, just in the one file Claude Code's own process env
+// actually consults before expanding `.mcp.json`.
 function ensureEnvToken(targetDir, token) {
   if (!token) return;
-  const envPath = join(targetDir, '.env');
-  const line = `EVENTMODELERS_TOKEN=${token}`;
-
-  if (existsSync(envPath)) {
-    const content = readFileSync(envPath, 'utf-8');
-    if (/^EVENTMODELERS_TOKEN=/m.test(content)) {
-      const updated = content.replace(/^EVENTMODELERS_TOKEN=.*$/m, line);
-      if (updated !== content) writeFileSync(envPath, updated);
-    } else {
-      appendFileSync(envPath, `${content === '' || content.endsWith('\n') ? '' : '\n'}${line}\n`);
+  const claudeDir = join(targetDir, '.claude');
+  mkdirSync(claudeDir, { recursive: true });
+  const settingsPath = join(claudeDir, 'settings.local.json');
+
+  let settings = {};
+  if (existsSync(settingsPath)) {
+    try {
+      settings = JSON.parse(readFileSync(settingsPath, 'utf-8'));
+    } catch {
+      settings = {};
     }
-  } else {
-    writeFileSync(envPath, `${line}\n`);
   }
 
+  settings.env = settings.env || {};
+  settings.env.EVENTMODELERS_TOKEN = token;
+  writeFileSync(settingsPath, JSON.stringify(settings, null, 2));
+
+  // settings.local.json is gitignored by Claude Code's own convention, but make
+  // sure nothing here relies on that silently — it now holds a live secret.
   const gitignorePath = join(targetDir, '.gitignore');
+  const entry = '.claude/settings.local.json';
   if (existsSync(gitignorePath)) {
     const content = readFileSync(gitignorePath, 'utf-8');
-    if (!content.split('\n').map((l) => l.trim()).includes('.env')) {
-      appendFileSync(gitignorePath, `${content === '' || content.endsWith('\n') ? '' : '\n'}.env\n`);
+    if (!content.split('\n').map((l) => l.trim()).includes(entry)) {
+      appendFileSync(gitignorePath, `${content === '' || content.endsWith('\n') ? '' : '\n'}${entry}\n`);
     }
   } else {
-    writeFileSync(gitignorePath, '.env\n');
+    writeFileSync(gitignorePath, `${entry}\n`);
   }
-  console.log('  ✓ Wrote EVENTMODELERS_TOKEN to .env (gitignored)');
+  console.log('  ✓ Wrote EVENTMODELERS_TOKEN to .claude/settings.local.json (gitignored)');
 }
 
 // `run --modeling`: modeling-kit's one and only runtime mode — there is no
@@ -1609,6 +1624,49 @@ credentialFlags(program
     });
   });
 
+// Every kit config `re-init` can refresh, keyed the same way install-manifest.json's
+// `stack` field is — looked up after reading that manifest so re-init knows exactly
+// which templates to re-copy without the user having to pass --stack again.
+const REINITIABLE_STACKS = { ...STACKS, [MODELING_KIT.key]: MODELING_KIT, [BLANK_BUILD_KIT.key]: BLANK_BUILD_KIT };
+
+credentialFlags(program
+  .command('re-init')
+  .description('Refresh an already-installed kit from the current CLI version — re-copies skills and the kit dir (.build-kit or .agent-modeling-kit) so you pick up script/skill updates after upgrading. Unlike `init`, never touches the project root scaffold or the root CLAUDE.md router, and leaves existing credentials alone unless --force is passed.')
+  .option('--modeling', 'Refresh the modeling kit (.agent-modeling-kit) instead of a build kit')
+  .option('--global', 'Re-install skills into ~/.claude/skills/ instead of the project — defaults to however they were originally installed')
+  .option('-f, --force', 'Re-prompt for credentials even if a config already has everything required — overwrites the existing config.json'))
+  .action(async (opts, command) => {
+    const globalOpts = command.optsWithGlobals();
+    const targetDir = process.cwd();
+
+    const kitDirName = opts.modeling ? MODELING_KIT.kitDirName : STACKS.node.kitDirName;
+    const kitDir = join(targetDir, kitDirName);
+
+    if (!existsSync(kitDir)) {
+      console.error(`❌ No ${kitDirName}/ found in ${targetDir} — run \`init${opts.modeling ? ' --modeling' : ''}\` first.`);
+      process.exit(1);
+    }
+
+    const manifest = readJsonSafe(join(kitDir, '.eventmodelers', 'install-manifest.json'));
+    const stackKey = opts.modeling ? MODELING_KIT.key : manifest.stack;
+    const stackCfg = stackKey ? REINITIABLE_STACKS[stackKey] : null;
+
+    if (!stackCfg) {
+      console.error(`❌ Can't tell which stack ${relative(targetDir, kitDir)} was installed from (${manifest.stack ? `"${manifest.stack}" isn't one re-init recognizes — likely a --git community stack` : 'its install manifest predates this tracking, or is missing'}).`);
+      console.error('   Re-run the original `init --git <url> --stack <name>` command by hand instead.');
+      process.exit(1);
+    }
+
+    await installStack(stackKey, stackCfg, {
+      configPath: globalOpts.config,
+      print: globalOpts.print,
+      global: opts.global !== undefined ? opts.global : !!manifest.global,
+      force: opts.force,
+      credentialOverrides: credentialOverridesFromOpts(opts),
+      skipRootScaffold: true,
+    });
+  });
+
 program
   .command('init-mcp')
   .description('Register the eventmodelers MCP server in .claude/settings.json (and optionally another harness)')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eventmodelers/cli",
-  "version": "1.0.3",
+  "version": "1.0.5",
   "description": "Eventmodelers CLI — real-time Claude agent + skills for Claude Code, for any stack (Node, Supabase, Axon, Cratis, or modeling-only)",
   "type": "module",
   "bin": {

package/shared/skills/connect/SKILL.md

@@ -150,7 +150,7 @@ Always run this step (not only when Step 3 ran) — it's idempotent and safe to
 
 The eventmodelers backend exposes the same board capabilities as an MCP server at `<BASE_URL>/mcp`, authenticated with the same `TOKEN` via an `x-token` header. Register it in the project's `.mcp.json` so Claude Code (or any other MCP-aware host) can connect and expose tools as `mcp__eventmodelers__<tool_name>`.
 
-**Do not put the raw token in `.mcp.json`** — that file is typically committed to share server config with the team. Instead reference an environment variable and keep the actual secret in a gitignored `.env` file:
+**Do not put the raw token in `.mcp.json`** — that file is typically committed to share server config with the team. Instead reference an environment variable and set the actual secret in `.claude/settings.local.json`'s `env` block:
 
 1. Read the existing `.mcp.json` at the project root if present (it may already list other MCP servers, e.g. a browser-automation server used by `discover-storyboard` — merge into `mcpServers`, never replace the whole file). If absent, start from `{"mcpServers": {}}`.
 2. Add or update the `eventmodelers` entry:
@@ -165,8 +165,14 @@ The eventmodelers backend exposes the same board capabilities as an MCP server a
      }
    }
    ```
-3. Ensure a project-root `.env` file contains `EVENTMODELERS_TOKEN=<TOKEN>` (append/update the line; create the file if missing).
-4. Ensure `.env` is listed in `.gitignore` (same check-then-append pattern as Step 3 uses for `.eventmodelers/config.json`) — it holds the same secret and must never be committed.
+3. Read the existing `.claude/settings.local.json` if present and merge in — never clobber `permissions`/`enabledMcpjsonServers` or anything else already there. Ensure it has `EVENTMODELERS_TOKEN` set under `env` (create the file with just this key if it doesn't exist yet):
+   ```json
+   {
+     "env": { "EVENTMODELERS_TOKEN": "<TOKEN>" }
+   }
+   ```
+   A plain `.env` file does **not** work here — Claude Code never sources one, so a `${EVENTMODELERS_TOKEN}` placeholder in `.mcp.json` would be left unexpanded (sent as the literal `${EVENTMODELERS_TOKEN}` text), which fails auth and pushes the client into an OAuth flow the eventmodelers server can't satisfy for this client. `.claude/settings.local.json`'s `env` block — alongside the inherited shell environment — is the only thing Claude Code actually resolves `.mcp.json` placeholders against.
+4. Ensure `.claude/settings.local.json` is listed in `.gitignore` (same check-then-append pattern as Step 3 uses for `.eventmodelers/config.json`) — it now holds the same secret and must never be committed. (Gitignored by Claude Code's own convention already, but don't rely on that silently.)
 
 MCP tools only become visible to the current agent session after the host (re)connects to the server — a brand-new `.mcp.json` entry written mid-session may need the user to approve the new server or reconnect (e.g. Claude Code's `/mcp` command) before `mcp__eventmodelers__*` tools appear in the tool list. That's expected and not an error: tell the user once, then let every other skill fall back to curl automatically until the tools show up.
 
@@ -226,7 +232,7 @@ The `token` field is a secret. It is never logged or shown after initial confirm
 
 ## Security notes
 
-- The config file (`.eventmodelers/config.json`) and the `.env` file holding `EVENTMODELERS_TOKEN` are both workspace-local and gitignored — never commit either.
+- The config file (`.eventmodelers/config.json`) and `.claude/settings.local.json` (holding `EVENTMODELERS_TOKEN` under `env`) are both workspace-local and gitignored — never commit either.
 - `.mcp.json` itself is safe to commit — it only ever contains the `${EVENTMODELERS_TOKEN}` placeholder, never the literal token.
 - The token grants write access to all boards in its organization — treat it like a password.
 - If a skill receives a `401`/`403` (curl) or an access-denied tool error (MCP) mid-session, re-invoke this skill to refresh the config before retrying.