mirror-mind 0.0.0-stage → 0.32.1

package/ts/src/identity/identityStore.ts

@@ -0,0 +1,80 @@
+// TS identity-table writes — the port of storage/identity.py upsert_identity and
+// update_identity_metadata. These are the deterministic write primitives behind
+// journey and identity management. `id` and `now` are injected so parity runs
+// match the Python oracle (Python generates a random UUID id and a microsecond
+// now).
+
+import type { WritableDatabase } from "#db/database.ts";
+import { assertNewIdentityKey } from "./identityKey.ts";
+
+/** The writable columns of an identity row (version is TEXT, e.g. "1.0.0"). */
+export interface IdentityRow {
+  id: string;
+  layer: string;
+  key: string;
+  content: string;
+  version: string;
+  metadata: string | null;
+}
+
+/**
+ * INSERT the identity when (layer, key) is absent, else UPDATE it — mirroring
+ * upsert_identity. On INSERT, created_at and updated_at are both the injected
+ * now; on UPDATE only updated_at changes and the existing id and created_at are
+ * preserved (the WHERE is on the unique (layer, key), so the injected id is
+ * ignored for an update, exactly as Python reuses existing.id).
+ *
+ * This is the only INSERT into `identity`, so it is where a new journey slug or
+ * persona id is held to its grammar (CR104): an INSERT whose key breaks it throws
+ * `InvalidIdentityKeyError` and writes nothing. An UPDATE never checks, because a
+ * key that already exists predates the grammar and must stay writable.
+ */
+export function upsertIdentity(db: WritableDatabase, identity: IdentityRow, nowIso: string): void {
+  const existing = db
+    .prepare("SELECT id FROM identity WHERE layer = ? AND key = ?")
+    .get(identity.layer, identity.key);
+  if (existing !== undefined) {
+    db.prepare(
+      "UPDATE identity SET content = ?, version = ?, updated_at = ?, metadata = ? " +
+        "WHERE layer = ? AND key = ?",
+    ).run(
+      identity.content,
+      identity.version,
+      nowIso,
+      identity.metadata,
+      identity.layer,
+      identity.key,
+    );
+  } else {
+    assertNewIdentityKey(identity.layer, identity.key);
+    db.prepare(
+      "INSERT INTO identity (id, layer, key, content, version, created_at, updated_at, metadata) " +
+        "VALUES (?, ?, ?, ?, ?, ?, ?, ?)",
+    ).run(
+      identity.id,
+      identity.layer,
+      identity.key,
+      identity.content,
+      identity.version,
+      nowIso,
+      nowIso,
+      identity.metadata,
+    );
+  }
+}
+
+/** UPDATE only metadata and updated_at — mirrors update_identity_metadata. */
+export function updateIdentityMetadata(
+  db: WritableDatabase,
+  layer: string,
+  key: string,
+  metadata: string,
+  nowIso: string,
+): void {
+  db.prepare("UPDATE identity SET metadata = ?, updated_at = ? WHERE layer = ? AND key = ?").run(
+    metadata,
+    nowIso,
+    layer,
+    key,
+  );
+}

package/ts/src/identity/journeyListing.ts

@@ -0,0 +1,53 @@
+// `list journeys` read primitives — the port of the journey branch of
+// memory.cli.inspect.cmd_list (`_extract_status` / `_extract_description`).
+//
+// Deliberately NOT reused from journey/journeyOptions.ts: that module ports a
+// different Python method (`list_journey_options`, behind the `journeys`
+// top-level command) with a full-line status regex and no description
+// truncation. This command's Python source (memory.cli.inspect) extracts a
+// single \w+ status word, tries a Portuguese "## Descrição" heading before an
+// English "## Description" fallback (two separate searches, not one
+// alternation — order matters when content could contain both), and caps the
+// description at 120 chars, not 150. Porting it as its own function keeps the
+// two Python call sites' independent behavior independently reproduced.
+
+import type { Database } from "#db/database.ts";
+import { optionalString, requireString } from "#db/rowDecode.ts";
+
+export interface JourneyListRow {
+  key: string;
+  status: string;
+  description: string;
+}
+
+/** Port of `_extract_status`: the first `**Status:** <word>`, or "unknown". */
+export function extractStatus(content: string): string {
+  const match = content.match(/\*\*Status:\*\*\s*(\w+)/);
+  return match ? match[1] : "unknown";
+}
+
+/**
+ * Port of `_extract_description`: try a Portuguese "## Descrição" section
+ * first, then an English "## Description" section, ending at a blank line or
+ * the next heading; trimmed and capped at 120 chars.
+ */
+function extractDescription(content: string): string {
+  const pt = content.match(/## Descrição\s*\n+(.+?)(?:\n\n|\n##)/s);
+  const match = pt ?? content.match(/## Description\s*\n+(.+?)(?:\n\n|\n##)/s);
+  return match ? match[1].trim().slice(0, 120) : "";
+}
+
+/** Port of `mem.get_identity(layer="journey")`, pre-sorted by key (Python re-sorts a no-op). */
+export function listJourneysForListCommand(db: Database): JourneyListRow[] {
+  return db
+    .prepare("SELECT key, content FROM identity WHERE layer = 'journey' ORDER BY key")
+    .all()
+    .map((row) => {
+      const content = optionalString(row, "content") ?? "";
+      return {
+        key: requireString(row, "key"),
+        status: extractStatus(content),
+        description: extractDescription(content),
+      };
+    });
+}

package/ts/src/identity/personaInspect.ts

@@ -0,0 +1,44 @@
+// `inspect persona` read primitives — the port of memory.cli.inspect._inspect_persona
+// and its shared _persona_metadata helper. `inspect extension`/`runtime-catalog`/
+// `llm-calls`/`embedding-provenance` share the extension catalog / ops-tail
+// machinery and stay on Python, bound to CV22.DS7.TS1.
+
+import type { Database } from "#db/database.ts";
+import { optionalString, requireString } from "#db/rowDecode.ts";
+
+export interface PersonaInspectRow {
+  version: string;
+  updatedAt: string;
+  content: string;
+  /** Parsed JSON object metadata, or {} for null/malformed/non-object metadata. */
+  metadata: Record<string, unknown>;
+}
+
+/** Port of `_persona_metadata`: {} for null, malformed JSON, or a non-object payload. */
+function parseMetadataObject(raw: string | null): Record<string, unknown> {
+  if (!raw) return {};
+  try {
+    const parsed = JSON.parse(raw) as unknown;
+    return parsed !== null && typeof parsed === "object" && !Array.isArray(parsed)
+      ? (parsed as Record<string, unknown>)
+      : {};
+  } catch {
+    return {};
+  }
+}
+
+/** Port of `mem.store.get_identity("persona", persona_id)`, projected for inspect. */
+export function getPersonaInspect(db: Database, personaId: string): PersonaInspectRow | null {
+  const row = db
+    .prepare(
+      "SELECT version, updated_at, content, metadata FROM identity WHERE layer = 'persona' AND key = ?",
+    )
+    .get(personaId);
+  if (row === undefined) return null;
+  return {
+    version: requireString(row, "version"),
+    updatedAt: requireString(row, "updated_at"),
+    content: requireString(row, "content"),
+    metadata: parseMetadataObject(optionalString(row, "metadata")),
+  };
+}

package/ts/src/identity/personaListing.ts

@@ -0,0 +1,37 @@
+// `list personas` read primitives — the port of the persona branch of
+// memory.cli.inspect.cmd_list. Distinct from persona/detectPersona.ts's
+// `routingRows`: same JSON shape, different call site/output (this one also
+// needs `version`).
+
+import type { Database } from "#db/database.ts";
+import { optionalString, requireString } from "#db/rowDecode.ts";
+
+export interface PersonaListRow {
+  key: string;
+  version: string;
+  routingKeywords: string[];
+}
+
+/** Port of `_persona_metadata(identity).get("routing_keywords") or []`. */
+function parseRoutingKeywords(metadata: string | null): string[] {
+  if (!metadata) return [];
+  try {
+    const parsed = JSON.parse(metadata) as Record<string, unknown>;
+    if (!Array.isArray(parsed.routing_keywords)) return [];
+    return parsed.routing_keywords.filter((item): item is string => typeof item === "string");
+  } catch {
+    return [];
+  }
+}
+
+/** Port of `mem.get_identity(layer="persona")`, pre-sorted by key (Python re-sorts a no-op). */
+export function listPersonas(db: Database): PersonaListRow[] {
+  return db
+    .prepare("SELECT key, version, metadata FROM identity WHERE layer = 'persona' ORDER BY key")
+    .all()
+    .map((row) => ({
+      key: requireString(row, "key"),
+      version: requireString(row, "version"),
+      routingKeywords: parseRoutingKeywords(optionalString(row, "metadata")),
+    }));
+}

package/ts/src/identity/setIdentity.ts

@@ -0,0 +1,64 @@
+// TS identity write surface — the port of IdentityService.set_identity.
+//
+// set_identity is the deterministic write behind `mm-identity` and `mm-seed`:
+// create or update an identity prompt for a (layer, key). It is a thin
+// orchestration over the upsertIdentity primitive with one load-bearing rule —
+// when metadata is None the existing row's metadata is inherited (read before
+// write) rather than overwritten with null. `id` and `now` are injected so parity
+// runs match the Python oracle (Python builds an Identity() with a random UUID id
+// and stamps a microsecond now inside upsert_identity).
+
+import type { WritableDatabase } from "#db/database.ts";
+import { optionalString } from "#db/rowDecode.ts";
+import { type IdentityRow, upsertIdentity } from "./identityStore.ts";
+
+/** Inputs to set_identity. `version` defaults to "1.0.0"; a null/absent metadata inherits. */
+export interface SetIdentityInput {
+  id: string;
+  layer: string;
+  key: string;
+  content: string;
+  /** Defaults to "1.0.0", matching the Python Identity model default. */
+  version?: string;
+  /**
+   * A pre-serialized JSON string, or null/undefined to inherit the existing row's
+   * metadata (Python treats `metadata is None` as "keep what is there"). Unlike
+   * journeys, set_identity never serializes JSON itself — the string passes through.
+   */
+  metadata?: string | null;
+}
+
+/**
+ * Port of IdentityService.set_identity: resolve the effective metadata (inherit on
+ * None), default the version, and upsert. Delegates INSERT/UPDATE semantics —
+ * including id/created_at preservation on update — to upsertIdentity.
+ */
+export function setIdentity(db: WritableDatabase, input: SetIdentityInput, nowIso: string): void {
+  const row: IdentityRow = {
+    id: input.id,
+    layer: input.layer,
+    key: input.key,
+    content: input.content,
+    version: input.version ?? "1.0.0",
+    metadata: resolveMetadata(db, input),
+  };
+  upsertIdentity(db, row, nowIso);
+}
+
+/**
+ * When metadata is provided, use it verbatim. When it is null or absent, inherit
+ * the existing row's metadata (or null when there is no existing row) — mirroring
+ * `metadata = existing.metadata if existing else None`.
+ */
+function resolveMetadata(db: WritableDatabase, input: SetIdentityInput): string | null {
+  if (input.metadata !== undefined && input.metadata !== null) {
+    return input.metadata;
+  }
+  const existing = db
+    .prepare("SELECT metadata FROM identity WHERE layer = ? AND key = ?")
+    .get(input.layer, input.key);
+  if (existing === undefined) {
+    return null;
+  }
+  return optionalString(existing, "metadata");
+}

package/ts/src/index.ts

@@ -0,0 +1,231 @@
+// Mirror Mind TypeScript core — package entry point and public API surface.
+//
+// The core was grown as a database-seam strangler of the Python core that
+// lived in `src/memory/` until CV22.DS10.TS5 deleted it (see
+// docs/project/roadmap/cv22-typescript-core-port/). This file
+// is the deliberate public surface: everything a consumer of the package should
+// use is re-exported here, read and write. Internal modules still import each
+// other by deep path; only the public API lives here, and it is kept in sync as
+// the strangler grows (CR011).
+
+// --- Consult command core ---
+export type {
+  ConsultAskCommand,
+  ConsultCreditsCommand,
+  ConsultParseResult,
+} from "./consult/args.ts";
+export { CONSULT_USAGE, ConsultArgError, parseConsultArgs } from "./consult/args.ts";
+export type {
+  ConsultContextLoader,
+  ConsultContextRequest,
+  RunConsultOptions,
+} from "./consult/core.ts";
+export {
+  buildConsultLlmRequest,
+  runConsult,
+  runConsultAsk,
+  runConsultCredits,
+  SYSTEM_PREAMBLE,
+} from "./consult/core.ts";
+export type { ConsultTier } from "./consult/modelCatalog.ts";
+export { CONSULT_TIERS, LLM_FAMILIES, resolveConsultModel } from "./consult/modelCatalog.ts";
+export type { CreditInfo as ConsultCreditInfo } from "./consult/render.ts";
+export {
+  BALANCE_BAR_WIDTH,
+  renderConsultAsk,
+  renderCost,
+  renderCredits,
+  USD_TO_BRL,
+} from "./consult/render.ts";
+
+// --- Conversation extraction ---
+export type {
+  ConversationExtractionOptions,
+  ConversationExtractionResult,
+} from "./conversation/extraction.ts";
+export { runConversationExtraction } from "./conversation/extraction.ts";
+export type { BackupRecord } from "./db/backupGate.ts";
+export { BackupGateError, requireBackup, sha256File } from "./db/backupGate.ts";
+export { assertCopyTarget, CopyOnlyGuardError } from "./db/copyGuard.ts";
+// --- Database seam ---
+export type {
+  Database,
+  OpenOptions,
+  PreparedQuery,
+  Row,
+  SqlValue,
+  WritableDatabase,
+  WritablePreparedQuery,
+} from "./db/database.ts";
+export {
+  openDatabaseCopyForWrite,
+  openDatabaseForWrite,
+  openDatabaseReadOnly,
+  snapshotDatabaseTo,
+  withTransaction,
+} from "./db/database.ts";
+export { blobToFloat32, parseUtcMs } from "./db/decode.ts";
+export { assertFtsIntegrity, FtsIntegrityError } from "./db/ftsIntegrity.ts";
+export { optionalNumber, optionalString, requireString } from "./db/rowDecode.ts";
+export { assertSchemaState, KNOWN_MIGRATION_IDS, SchemaStateError } from "./db/schemaState.ts";
+// --- Extension context provider runtime (DS7.TS2) ---
+export type {
+  CollectExtensionContextOptions,
+  CollectedExtensionContext,
+  ExtensionContextDiagnostic,
+  ExtensionContextRequest,
+  ExtensionContextSection,
+} from "./extensions/contextRuntime.ts";
+export {
+  collectExtensionContext,
+  MIRROR_CONTEXT_PROTOCOL,
+  renderExtensionSections,
+  selectExtensionBindings,
+} from "./extensions/contextRuntime.ts";
+export type {
+  ExistingMemoryForCuration,
+  ExtractedMemory,
+  ExtractedTask,
+  ExtractionMessage,
+} from "./extraction/conversation.ts";
+export {
+  curateAgainstExisting,
+  extractMemories,
+  extractTasks,
+  formatTranscript,
+  naiveSummary,
+} from "./extraction/conversation.ts";
+export { parseJsonResponse } from "./extraction/json.ts";
+// --- Front-door routing ---
+export type { FrontDoorEngine, RouteDecision } from "./frontDoor/routing.ts";
+export { routeMemoryCommand } from "./frontDoor/routing.ts";
+// --- Identity (read model + writes) ---
+export type { IdentityRow } from "./identity/identityStore.ts";
+export { updateIdentityMetadata, upsertIdentity } from "./identity/identityStore.ts";
+export type { SetIdentityInput } from "./identity/setIdentity.ts";
+export { setIdentity } from "./identity/setIdentity.ts";
+// --- Journeys (options + writes) ---
+export type {
+  JourneyHierarchy,
+  JourneyIdentityRow,
+  JourneyOption,
+} from "./journey/journeyOptions.ts";
+export { groupJourneysByParent, listJourneyOptions } from "./journey/journeyOptions.ts";
+export type { JourneyAssociationCounts } from "./journey/journeyRemoval.ts";
+export {
+  countJourneyAssociations,
+  JourneyRemovalError,
+  removeJourney,
+} from "./journey/journeyRemoval.ts";
+export type { CreateJourneyInput, JourneyFields } from "./journey/journeyWrite.ts";
+export {
+  createJourney,
+  JOURNEY_LAYER,
+  JourneyNotFoundError,
+  journeyMetadata,
+  setParentJourney,
+  setProjectPath,
+} from "./journey/journeyWrite.ts";
+// --- Memory (listing + reinforcement writes) ---
+export type { ListRecentFilters, MemorySummary } from "./memory/listing.ts";
+export {
+  buildListRecentQuery,
+  countMemoriesByType,
+  listRecentMemorySummaries,
+} from "./memory/listing.ts";
+export { logAccess, logUse } from "./memory/reinforcement.ts";
+export type { MirrorContextOptions } from "./mirror/context.ts";
+export { loadMirrorContext, relevantAttachments } from "./mirror/context.ts";
+export type {
+  ResolvedMirrorDefaults,
+  ResolveMirrorDefaultsInput,
+} from "./mirror/defaultResolution.ts";
+export { detectJourney, resolveMirrorDefaults } from "./mirror/defaultResolution.ts";
+export type { MirrorLoadInput, RenderedMirrorLoad } from "./mirror/orchestration.ts";
+export {
+  deactivateMirrorState,
+  listActiveMirrorJourneys,
+  logMirrorResponse,
+  runMirrorLoad,
+  titleFromSummary,
+} from "./mirror/orchestration.ts";
+export type {
+  ReceptionJourney,
+  ReceptionPersona,
+  ReceptionResult,
+} from "./mirror/reception.ts";
+export { EMPTY_RECEPTION_RESULT, RECEPTION_PROMPT, runReception } from "./mirror/reception.ts";
+// --- Mirror Mode and operating-mode orchestration (DS7.US4) ---
+export type { OperatingModeState } from "./mode/operatingMode.ts";
+export {
+  activateOperatingMode,
+  deactivateOperatingMode,
+  getActiveOperatingMode,
+  renderModeActivation,
+  renderModeStatus,
+} from "./mode/operatingMode.ts";
+// --- Persona routing ---
+export type { PersonaMatch, PersonaRoutingRow } from "./persona/detectPersona.ts";
+export { detectPersona, normalizeRoutingText } from "./persona/detectPersona.ts";
+
+// --- External providers (DS5 substrate) ---
+export type { ProviderConfig, ProviderConfigOptions, ProviderName } from "./providers/config.ts";
+export { ProviderConfigError, resolveProviderConfig } from "./providers/config.ts";
+export type { CreditInfo, CreditProvider, ReplayCreditFixture } from "./providers/credits.ts";
+export {
+  assertReplayCreditFixture,
+  loadReplayCreditProvider,
+  ReplayCreditProvider,
+} from "./providers/credits.ts";
+export type { EmbeddingProvider, ReplayEmbeddingFixture } from "./providers/embedding.ts";
+export {
+  assertReplayEmbeddingFixture,
+  loadReplayEmbeddingProvider,
+  ReplayEmbeddingProvider,
+} from "./providers/embedding.ts";
+export type {
+  LlmProvider,
+  LlmRequest,
+  LlmResponse,
+  LlmRole,
+  ReplayLlmFixture,
+} from "./providers/llm.ts";
+export {
+  assertReplayLlmFixture,
+  loadReplayLlmProvider,
+  ReplayLlmProvider,
+} from "./providers/llm.ts";
+export type { RedactionOptions } from "./providers/redaction.ts";
+export {
+  assertFixtureSafe,
+  redactJson,
+  redactString,
+  UnsafeFixtureError,
+} from "./providers/redaction.ts";
+export type { ReplayFixture } from "./providers/replay.ts";
+export { loadReplayFixture } from "./providers/replay.ts";
+// --- Hybrid search ranker ---
+export type {
+  FreshSearchFilters,
+  FreshSearchOptions,
+  FreshSearchResult,
+} from "./search/memorySearch.ts";
+export {
+  accessCountsByMemoryId,
+  DEFAULT_SEARCH_RANKER_CONFIG,
+  ftsLexicalScores,
+  ftsQuery,
+  listSearchMemoryRows,
+  searchMemories,
+} from "./search/memorySearch.ts";
+export type { RankableMemory, RankedMemory, RankerConfig, SearchWeights } from "./search/ranker.ts";
+export {
+  cosineSimilarity,
+  hybridScore,
+  rankMemories,
+  recencyScore,
+  reinforcementScore,
+} from "./search/ranker.ts";
+export { expandHome, normalizeProjectPath } from "./util/paths.ts";
+export { newId, nowIso, toMicrosecondIso } from "./util/pyGenerators.ts";
+// --- Python-compatibility utilities ---

package/ts/src/init/init.ts

@@ -0,0 +1,111 @@
+// `init` — bootstrap a user home from repository identity templates. The port
+// of memory.cli.init. Filesystem-only: no database is opened or touched.
+//
+// Deliberate, verified divergence: Python's `main()` never catches
+// FileExistsError/FileNotFoundError from init_user_home, so those paths exit
+// via an uncaught exception — a raw Python traceback with this machine's
+// absolute file paths on stderr, exit 1. That traceback is an implementation
+// leak, not a designed CLI contract (unlike, say, `identity get`'s deliberate
+// one-line not-found message) — it is not meaningful or possible to replicate
+// byte-for-byte (it depends on Python's own call stack and module paths, which
+// drift on every refactor and reveal nothing product-relevant). This port
+// preserves the observable CONTRACT instead: exit 1, and a stderr message that
+// names the failure. See the CLI wiring in ../frontDoor/cli.ts.
+
+import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { runningTreeRoot } from "#runtime/treeRoot.ts";
+
+/** Port of Python's uncaught `FileNotFoundError` for a missing templates root. */
+export class TemplatesNotFoundError extends Error {}
+
+/** Port of Python's uncaught `FileExistsError` for a non-empty identity root. */
+export class IdentityRootExistsError extends Error {
+  readonly path: string;
+  constructor(path: string) {
+    super(`Identity root already exists and is not empty: ${path}`);
+    this.path = path;
+  }
+}
+
+/**
+ * `<tree root>/templates/identity`. Python's `find_templates_identity_root`
+ * walked up from its own file for the directory; since CV22.DS10.US3 the tree
+ * root is one resolver shared with release notes and the welcome card, and
+ * the templates ship in the package at the same path as in the checkout.
+ */
+export function templatesIdentityRoot(treeRoot: string = runningTreeRoot()): string {
+  const candidate = join(treeRoot, "templates", "identity");
+  if (existsSync(candidate)) return candidate;
+  throw new TemplatesNotFoundError(`Could not find templates/identity under ${treeRoot}.`);
+}
+
+/**
+ * Where `init` creates a user's home: `<home>/.mirror-minds/<user>`, the path
+ * `MIRROR_USER=<user>` resolves to.
+ *
+ * Python's `default_user_home` hardcoded the legacy `~/.mirror/<user>` and told
+ * the person to set MIRROR_HOME by hand. CV22.DS10.US3 (D3) has `init` write
+ * `MIRROR_USER` into the config file instead, and a legacy home would then
+ * make every later command print the legacy-path warning (D14).
+ */
+export function defaultUserHome(user: string, home: string = homedir()): string {
+  return join(home, ".mirror-minds", user);
+}
+
+/** Every `.yaml` file under `root`, recursively (mirrors `Path.rglob("*.yaml")`). */
+function yamlFilesRecursive(root: string): string[] {
+  const out: string[] = [];
+  for (const entry of readdirSync(root, { withFileTypes: true })) {
+    const full = join(root, entry.name);
+    if (entry.isDirectory()) out.push(...yamlFilesRecursive(full));
+    else if (entry.isFile() && full.endsWith(".yaml")) out.push(full);
+  }
+  return out;
+}
+
+/**
+ * Port of `_substitute_user_name`: replace every `{{user_name}}` token in every
+ * `.yaml` file under `identityRoot` with `user`, writing back only files that
+ * actually contained the token. Non-`.yaml` files (e.g. `README.md`) are
+ * intentionally left untouched, matching the Python glob scope exactly.
+ */
+function substituteUserName(identityRoot: string, user: string): void {
+  for (const file of yamlFilesRecursive(identityRoot)) {
+    const content = readFileSync(file, "utf8");
+    if (content.includes("{{user_name}}")) {
+      writeFileSync(file, content.replaceAll("{{user_name}}", user), "utf8");
+    }
+  }
+}
+
+export interface InitUserHomeOptions {
+  /** Overrides the located templates root (tests only; production auto-locates it). */
+  templatesIdentityRoot?: string;
+  /** Overrides the destination home (tests only; production uses defaultUserHome). */
+  userHome?: string;
+}
+
+/**
+ * Port of `init_user_home`: locate the identity templates, refuse a non-empty
+ * existing destination, copy the template tree, substitute `{{user_name}}` in
+ * every `.yaml` file, and return the destination identity root.
+ */
+export function initUserHome(user: string, options: InitUserHomeOptions = {}): string {
+  const templatesRoot = options.templatesIdentityRoot ?? templatesIdentityRoot();
+  if (!existsSync(templatesRoot)) {
+    throw new TemplatesNotFoundError(`Identity templates not found: ${templatesRoot}`);
+  }
+
+  const destinationHome = options.userHome ?? defaultUserHome(user);
+  const identityRoot = join(destinationHome, "identity");
+  if (existsSync(identityRoot) && readdirSync(identityRoot).length > 0) {
+    throw new IdentityRootExistsError(identityRoot);
+  }
+
+  mkdirSync(destinationHome, { recursive: true });
+  cpSync(templatesRoot, identityRoot, { recursive: true });
+  substituteUserName(identityRoot, user);
+  return identityRoot;
+}