mirror-mind 0.33.3 → 0.33.4

package/docs/releases/index.md

@@ -12,6 +12,7 @@ Future release notes should use the structure defined in [Release Notes](../proc
 
 ## Releases
 
+- [v0.33.4 — A Name Is a Key](v0.33.4.md) — patch release of three first-run corrections: two from a contributor's PR #43 and CR141, which its review opened. `init --help` created a home named `--help`, `init ../escaped` created one outside `.mirror-minds`, and `init "My User"` put a space into `MIRROR_USER`; a user name is now a kebab-case key like a journey slug or a persona id, refused otherwise with a name that would work and nothing created. `identity edit` on Windows opens Notepad when no editor is named. Existing homes untouched. No migration.
 - [v0.33.3 — Mirror Finds Itself Under Any Path](v0.33.3.md) — patch release of one Change Request, CR140, carried by a contributor's PR #42: Mirror read its own install path from `URL.pathname`, so a checkout or package under a path with a space or a non-ASCII character read as `Install: unknown`, the welcome card showed no update, and `runtime update` refused. The path is now a filesystem path, a guard keeps the idiom out, and an `unknown` install names the path it looked up from. On Windows, npm's global layout is recognized and npm runs with no shell, verified on Windows in CI for the two files they touch; there is still no Windows product. Affected installs update once by hand. No migration.
 - [v0.33.2 — Git Runs Where Mirror Lives](v0.33.2.md) — patch release of one Change Request, CR138: on a clone install, `runtime status`, `version`, and `diagnose` describe the install from any directory, and `diagnose` grades Mirror's own tree. Git now runs only in the install's own checkout, so a checkout someone else made can no longer run a `core.fsmonitor` command through these commands; `version --start PATH` is the one explicit exception. Package installs were never exposed. No migration.
 - [v0.33.1 — The Install Answers For Itself](v0.33.1.md) — patch release of six RS010 Change Requests: the welcome card, the status line, and both `release-notes` readers answer for the install that is running, never for the cwd or the repository around the install. A package asks its own tree and the npm registry, a clone its own checkout and remote; `pending` says `unknown` when it cannot tell, and a `--ref` value can no longer run a command through git. No migration.

package/docs/releases/v0.33.4.md

@@ -0,0 +1,104 @@
+---
+digest: >
+  v0.33.4 is a maintenance release of three first-run corrections, two from a
+  contributor's PR #43 and one Change Request, CR141, that its review opened.
+  `mirror init --help` created a home named `--help`; `init ../escaped` created
+  one outside `.mirror-minds`; `init "My User"` put a space into `MIRROR_USER`
+  for every wiring command. A user name is now a kebab-case key, like a journey
+  slug or a persona id, refused otherwise with a name that would work and
+  nothing created. And `identity edit` on Windows opens Notepad when no editor
+  is named, instead of failing to start nano. Existing homes are untouched; no
+  migration.
+---
+
+# v0.33.4 — A Name Is a Key
+
+**Date:** 2026-10-17
+
+## Highlights
+
+- **`init` takes a kebab-case key for a user name, and nothing else** (CR141, from the
+  review of PR #43). `init ../escaped` created `~/escaped`, outside the directory the
+  product owns; `init "My User"` put a space into `MIRROR_USER`, which every wiring
+  command `init` prints then carried; `init a/b` nested. Each is refused before anything
+  is created, with the sentence `identity set` already uses: the consequence, the rule,
+  and a key that would work.
+- **`init --help` no longer creates a home named `--help`** (PR #43 by
+  @rodrigoimmaginario). The command has no flags; a word that starts with `-` gets the
+  usage line and exit 2.
+- **`identity edit` opens Notepad on Windows when no editor is named** (PR #43). The
+  order is unchanged, `EDITOR`, then `VISUAL`, then the platform's default: `notepad` on
+  Windows, where nano exists only inside Git Bash, `nano` elsewhere.
+- **Existing homes are untouched.** `init` only creates; a home with another kind of name
+  keeps it.
+
+## Where We Started
+
+A contributor's first run on Windows met two small things and sent a PR for each:
+`init --help` created a home, and `identity edit` with no `EDITOR` set failed to start
+nano. The first was not a Windows bug at all; it reproduced on macOS in a second.
+
+Its review asked what else `init` accepted. The answer was anything. The name becomes
+`~/.mirror-minds/<user>` and the value of `MIRROR_USER`, and the repository had already
+decided, in CR104, that a key which goes into paths and shell commands must be one plain
+word a shell cannot split, substitute, or read as an option. Journey slugs and persona
+ids had met that rule since `v0.32.0`. The user name was the last key of its kind that
+did not.
+
+## What Changed
+
+**One sentence for every key.** `newUserNameProblem` joins `newIdentityKeyProblem` in
+`ts/src/identity/identityKey.ts`, both over one builder, so `init`, `identity set`,
+`identity edit`, and `seed` refuse a non-key the same way. The key is printed escaped: a
+name with a newline or a `;` in it cannot forge output or a command. `runInit` asks before
+`initUserHome`, so a refusal leaves `$HOME` as it was: no home, no identity directory, no
+config file.
+
+**The test is the PR's, widened.** `../escaped`, `My User`, `a/b`, and an accented name go
+through the real front door; each asserts the exit, the sentence with its suggestion, and
+an empty home afterwards. PR #43's own `init --help` test stands beside it.
+
+**Notepad, with its evidence still owed.** The platform is a dependency of
+`resolveEditor`, so both defaults are tested on every OS. The PR verified the Windows
+round trip on an unchanged buffer, which prints `No changes detected.` whether Notepad
+blocked or returned at once; early Windows 11 Notepad did return at once. A round trip
+that changes the buffer is asked for on the PR, and the default ships as the better of
+the two available answers: nano could not start at all.
+
+### What you will notice
+
+- A first `mirror init` with a name that is not a plain lowercase word is refused with
+  a name that would work. `mirror init your-name`, as Getting Started has always said,
+  is unchanged.
+- On Windows, `mirror identity edit …` opens Notepad instead of failing.
+- Nothing else.
+
+## Upgrading
+
+```bash
+mirror runtime update          # or: npm install -g mirror-mind
+```
+
+There is no database migration and no runtime wiring change. If `v0.33.3`'s note applied
+to you, a Mirror under a path with a space or an accent, and you have not yet taken its
+one manual update, take it first; from `v0.33.3` on, `runtime update` works.
+
+## Conscious Exclusions
+
+- **Selecting an existing home by name.** `MIRROR_USER` pointing at a home created
+  before this rule, under whatever name, still selects it. Only creation is constrained.
+- **`init`'s wiring lines on Windows.** They print `ln -s`, which Windows has no answer
+  to; that waits for the runtimes to be verified there, as the contributor's PR says.
+- **Counting verdicts as front-door errors** (CR139), unchanged since `v0.33.2`.
+
+## What We Learned
+
+A fix for an instance invites the question "what else?", and the cheapest moment to ask
+it is the review. The `-` check was right; the class was one line away, and the rule
+already existed with its sentence, its escaping, and its tests. When a repository has
+decided something once, the second instance should cost a reference, not a decision.
+
+## Next Horizon
+
+CR139, the verdict loop, is the visible next step in RS010. The contributor's Windows
+series, if it comes, begins with the suite on `windows-latest`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mirror-mind",
-  "version": "0.33.3",
+  "version": "0.33.4",
   "description": "Mirror Mind: a local-first memory and identity framework for agentic AI runtimes (Pi, Claude Code, Gemini CLI, Codex)",
   "license": "MIT",
   "repository": {

package/plugins/mirror-mind/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "mirror-mind",
-  "version": "0.33.3",
+  "version": "0.33.4",
   "description": "Mirror Mind — local-first memory and identity for agentic runtimes.",
   "author": {
     "name": "Mirror Mind"

package/ts/src/frontDoor/cli.ts

@@ -43,7 +43,7 @@ import { type Database, openDatabaseReadOnly, type WritableDatabase } from "#db/
 import { ensureDatabaseReady } from "#db/readyOnOpen.ts";
 import { assertSchemaState, SchemaStateError } from "#db/schemaState.ts";
 import { allDescriptors, descriptorsByLayer } from "#descriptor/descriptorRead.ts";
-import { newIdentityKeyProblem } from "#identity/identityKey.ts";
+import { newIdentityKeyProblem, newUserNameProblem } from "#identity/identityKey.ts";
 import { identityRowExists, listIdentityByLayer } from "#identity/identityRead.ts";
 import { listJourneysForListCommand } from "#identity/journeyListing.ts";
 import { listPersonas } from "#identity/personaListing.ts";
@@ -885,10 +885,20 @@ function isInit(argv: readonly string[]): boolean {
  */
 function runInit(argv: readonly string[], env: NodeJS.ProcessEnv = process.env): number {
   const user = argv[1];
-  if (!user) {
+  // A word that starts with `-` is a flag this command does not have, not a
+  // user: `init --help` once created a home named `--help`.
+  if (!user || user.startsWith("-")) {
     console.error("Usage: init <user>");
     return 2;
   }
+  // And any other word is a key: the home's directory name and the value of
+  // MIRROR_USER in the wiring commands printed below. CR104's rule for slugs
+  // and persona ids, asked before anything is created (CR141).
+  const problem = newUserNameProblem(user);
+  if (problem !== null) {
+    console.error(`Error: ${problem}`);
+    return 2;
+  }
   try {
     const identityRoot = initUserHome(user);
     const mirrorHome = dirname(identityRoot);

package/ts/src/identity/identityEdit.ts

@@ -34,6 +34,8 @@ export interface IdentityEditDeps {
   /** The editor argv[0], resolved the way Python resolves it. */
   editor?: string | undefined;
   visual?: string | undefined;
+  /** Decides the editor when neither variable is set. Default: this process's. */
+  platform?: NodeJS.Platform;
   nowIso: () => string;
   /** Injected so a test can watch the buffer without driving a real editor. */
   spawn?: typeof spawnSync;
@@ -42,9 +44,16 @@ export interface IdentityEditDeps {
   newId: () => string;
 }
 
-/** Python's `os.environ.get("EDITOR") or os.environ.get("VISUAL") or "nano"`. */
+/**
+ * Python's `os.environ.get("EDITOR") or os.environ.get("VISUAL") or "nano"`,
+ * with one platform default: Windows has no nano outside Git Bash, so a
+ * PowerShell user with neither variable set saw `Editor 'nano' could not be
+ * started.` Notepad ships with every Windows and blocks until it is closed,
+ * which is what the edit needs. Either variable still wins when set.
+ */
 export function resolveEditor(deps: IdentityEditDeps): string {
-  return deps.editor || deps.visual || "nano";
+  const platform = deps.platform ?? process.platform;
+  return deps.editor || deps.visual || (platform === "win32" ? "notepad" : "nano");
 }
 
 /**

package/ts/src/identity/identityKey.ts

@@ -44,11 +44,27 @@ export function identityKeyBreaksGrammar(layer: string, key: string): boolean {
  */
 export function newIdentityKeyProblem(layer: string, key: string): string | null {
   const keyName = KEY_NAMES.get(layer);
-  if (keyName === undefined || isKebabSlug(key)) return null;
+  if (keyName === undefined) return null;
+  return keyProblem(layer, keyName, key);
+}
+
+/**
+ * Why `init` cannot take `user`, or null when it can (CR141). A user name is
+ * a key of the same kind: it becomes `~/.mirror-minds/<user>` and the value of
+ * `MIRROR_USER` in every wiring command `init` prints. `init ../escaped` once
+ * created `~/escaped`, outside the directory the product owns.
+ */
+export function newUserNameProblem(user: string): string | null {
+  return keyProblem("user home", "user name", user);
+}
+
+/** The one sentence every key refusal is, or null when `key` is a kebab-case slug. */
+function keyProblem(created: string, keyName: string, key: string): string | null {
+  if (isKebabSlug(key)) return null;
   const suggestion = kebabSlug(key);
   const example = suggestion ? `, for example ${pyRepr(suggestion)}` : "";
   return (
-    `no ${layer} was created: ${pyRepr(key)} is not a ${keyName}. ` +
+    `no ${created} was created: ${pyRepr(key)} is not a ${keyName}. ` +
     `Use lowercase letters, digits, and single hyphens, up to 80 characters${example}.`
   );
 }