claude-nomad 0.32.4 → 0.34.0

package/src/commands.doctor.version.ts

@@ -5,17 +5,17 @@ import { fileURLToPath } from 'node:url';
 
 import { dim, green, infoGlyph, okGlyph, warnGlyph, yellow } from './color.ts';
 import { addItem, type DoctorSection } from './commands.doctor.format.ts';
-import { HOME, UPSTREAM_REPO_SLUG } from './config.ts';
+import { HOME } from './config.ts';
 
 /**
  * Soft, offline-tolerant release-version check appended to `cmdDoctor`. Reads
- * the local `package.json.version`, compares it to the latest release tag on
- * the upstream GitHub repo (cached 1h, 3s curl timeout), and emits one of:
+ * the local `package.json.version`, compares it to the latest published version
+ * on the npm registry (cached 1h, 3s curl timeout), and emits one of:
  *   - `✓ claude-nomad: <local> (latest)` when local == latest
  *   - `⚠︎ claude-nomad: <local> -> <latest>` when local < latest
  *   - `ℹ︎ claude-nomad: <local> (ahead of latest release <latest>)` when local > latest
  * Every failure path (offline, curl missing, non-2xx, malformed JSON, missing
- * `tag_name`, missing/unreadable package.json) is a SILENT skip; this module
+ * `version`, missing/unreadable package.json) is a SILENT skip; this module
  * never sets `process.exitCode` and never writes to stderr.
  */
 
@@ -85,7 +85,7 @@ function readLocalVersion(): string | null {
  * Load the cached latest-tag entry. Returns the parsed entry when the file
  * exists, parses cleanly, and matches the expected shape (`checked_at` finite
  * number, `latest` strict-semver string); any failure surfaces as `null` so
- * the caller falls through to `fetchLatestTag`. Treating malformed cache as a
+ * the caller falls through to `fetchLatestVersion`. Treating malformed cache as a
  * miss is the safer default than crashing or surfacing the error.
  */
 function loadCache(): CacheEntry | null {
@@ -121,29 +121,26 @@ function saveCache(latest: string): void {
 }
 
 /**
- * Fetch the latest release tag from the upstream GitHub releases API. Uses
+ * Fetch the latest published version from the npm registry. Uses
  * `execFileSync('curl', ...)` rather than `node:https` because curl honors
  * system proxies and respects the `-m` timeout reliably. curl is optional, not
  * a hard dependency: this is its only consumer, so a host without curl simply
  * skips the version line. 3-second timeout, fail-fast on non-2xx (`-f`), silent
  * (`-s`), follow redirects (`-L`). Returns `null` on ANY failure path (curl
- * missing from PATH, a missing `tag_name` field, or a tag that fails
- * strict-semver validation after the leading `v` strip). Release tags ship as
- * `v<semver>` per `release-please-config.json`'s `include-v-in-tag: true`.
+ * missing from PATH, a missing or non-string `version` field, or a version that
+ * fails strict-semver validation). The npm registry `version` field is already
+ * bare semver (no leading `v` strip needed).
  */
-function fetchLatestTag(): string | null {
+function fetchLatestVersion(): string | null {
   try {
-    const url = `https://api.github.com/repos/${UPSTREAM_REPO_SLUG}/releases/latest`;
-    const raw = execFileSync(
-      'curl',
-      ['-fsSL', '-m', '3', '-H', 'Accept: application/vnd.github+json', url],
-      { stdio: ['ignore', 'pipe', 'pipe'] },
-    ).toString();
-    const parsed = JSON.parse(raw) as { tag_name?: unknown };
-    if (typeof parsed.tag_name !== 'string') return null;
-    const tag = parsed.tag_name.startsWith('v') ? parsed.tag_name.slice(1) : parsed.tag_name;
-    if (!STRICT_SEMVER.test(tag)) return null;
-    return tag;
+    const url = 'https://registry.npmjs.org/claude-nomad/latest';
+    const raw = execFileSync('curl', ['-fsSL', '-m', '3', url], {
+      stdio: ['ignore', 'pipe', 'pipe'],
+    }).toString();
+    const parsed = JSON.parse(raw) as { version?: unknown };
+    if (typeof parsed.version !== 'string') return null;
+    if (!STRICT_SEMVER.test(parsed.version)) return null;
+    return parsed.version;
   } catch {
     return null;
   }
@@ -174,7 +171,7 @@ export function reportVersionCheck(section: DoctorSection): void {
     latest = cached.latest;
   }
   if (latest === null) {
-    latest = fetchLatestTag();
+    latest = fetchLatestVersion();
     if (latest === null) return;
     saveCache(latest);
   }

package/src/commands.update.ts

@@ -1,191 +1,30 @@
-import { existsSync } from 'node:fs';
+import { execFileSync } from 'node:child_process';
 
-import { cmdDoctor } from './commands.doctor.ts';
-import { currentBranch, headSha, reinstallIfNeeded } from './commands.update.git.ts';
-import { defaultPrompt, tryAutoResolveMergeConflict } from './commands.update.resolve.ts';
-import { REPO_HOME } from './config.ts';
-import { commitRegeneratedLockfile, precommitForkExtras } from './update.fork-extras.ts';
-import { loadTopology } from './update.topology.ts';
-import { die, gitOrFatal, gitStatusPorcelainZ, log, warn } from './utils.ts';
+import { type SpawnSyncFn } from './gh-actions.ts';
+import { NomadFatal } from './utils.ts';
 
 /**
- * Caller-supplied options for `cmdUpdate`. All flags optional; defaults are
- * conservative (no dirty-tree override, prompt for fork push, mutate state).
- */
-export type CmdUpdateOpts = {
-  /** When true, run topology detection + pre-flight only; print would-be git
-   * commands without mutating the repo. Skips the trailing `cmdDoctor` call. */
-  dryRun?: boolean;
-  /** When true, proceed even when `gitStatusPorcelainZ(REPO_HOME)` is
-   * non-empty. Emits a WARN log line before continuing. */
-  force?: boolean;
-  /** Fork topology only: when true, push the post-merge HEAD to `origin/main`
-   * without prompting. When false/unset, the user is prompted y/N. */
-  pushOrigin?: boolean;
-  /** Test injection point for the interactive y/N prompt. Production code
-   * reads one line from `/dev/tty`; tests override this to return a
-   * deterministic answer without a real controlling terminal. */
-  prompt?: (question: string) => string;
-};
-
-/**
- * Perform a vanilla update by fast-forward pulling `origin/main`.
- *
- * Non-ff pulls (someone else pushed in the meantime) surface as `NomadFatal`
- * via `gitOrFatal`. If `opts.dryRun` is true, logs the would-be pull command
- * instead of executing it. Takes the full `CmdUpdateOpts` so the signature
- * stays symmetric with `runFork` even though only `dryRun` is consulted
- * today.
- *
- * @param opts - Update options; only `dryRun` is observed for this topology.
- * @returns `true` when this path already ran `npm install` and committed the merged lockfile (so the caller should skip `reinstallIfNeeded`). Vanilla `--ff-only` pulls never conflict, so this is always `false`.
- */
-function runVanilla(opts: CmdUpdateOpts): boolean {
-  if (opts.dryRun === true) {
-    log('DRY-RUN: would run `git pull --ff-only origin main`');
-    return false;
-  }
-  gitOrFatal(['pull', '--ff-only', 'origin', 'main'], 'git pull', REPO_HOME);
-  return false;
-}
-
-/**
- * Perform a fork-style update by fetching from `upstream`, merging `upstream/main` into `main`, and optionally pushing the merge to `origin`.
+ * Update the claude-nomad CLI to the latest published npm release by running
+ * `npm update -g claude-nomad`.
  *
- * The prompt step is gated by `pushOrigin` (no prompt when explicit) and by
- * `dryRun` (no prompt, no push when previewing). When `opts.dryRun === true`
- * the function only logs the git actions it would perform and returns
- * without running any commands. When `opts.pushOrigin === true` the function
- * pushes to `origin/main` without prompting; otherwise it prompts (via
- * `opts.prompt` if provided, or the default `/dev/tty` prompt) and only
- * pushes when the answer is `y` or `yes` (case-insensitive). Non-affirmative
- * answers skip the push and log a "run later" hint.
+ * Design decision D-01: self-update and data sync are separate concerns. This
+ * command only updates the CLI binary; it does NOT run `nomad pull`, `nomad
+ * doctor`, or any git operation. Use `nomad pull` after updating if you want
+ * to sync config state.
  *
- * When the merge (and any extras precommit) leaves `HEAD` unchanged from
- * `beforeSha`, there is nothing new to push: the function logs a one-line
- * "already in sync" and returns without pushing or prompting (issue #66). An
- * auto-resolved conflict always advances `HEAD` via its merge commit, so that
- * path is never mistaken for a no-op.
+ * Uses an argv-array (no shell) with an injectable `run` for test isolation.
  *
- * @param opts - Update options; respected fields are:
- *   - `dryRun`: when true, log actions instead of executing them
- *   - `pushOrigin`: when true, push to `origin/main` without prompting
- *   - `prompt`: optional prompt function used for interactive confirmation
- * @param beforeSha - `HEAD` SHA captured before the fork update began; the
- *   post-merge `HEAD` is compared against it to detect a no-op. When omitted
- *   (dry-run preview) the no-op short-circuit is skipped.
+ * @param run - Subprocess runner; defaults to `execFileSync`. Inject a fake in
+ *   tests to assert the exact args without touching the real npm registry.
  */
-function runFork(opts: CmdUpdateOpts, beforeSha?: string): boolean {
-  const promptFn = opts.prompt ?? defaultPrompt;
-  if (opts.dryRun === true) {
-    log('DRY-RUN: would run `git fetch upstream`');
-    log('DRY-RUN: would run `git merge upstream/main`');
-    if (opts.pushOrigin === true) {
-      log('DRY-RUN: would run `git push origin main`');
-    } else {
-      log('DRY-RUN: would prompt before pushing to origin/main');
-    }
-    return false;
-  }
-  gitOrFatal(['fetch', 'upstream'], 'git fetch upstream', REPO_HOME);
-  // Pre-commit whitelisted extras (issue #112): otherwise untracked
-  // shared/extras/ content that upstream also adds makes the merge abort
-  // pre-merge with no UU state, so the lone-lockfile auto-resolve never fires.
-  precommitForkExtras();
-  let autoResolved = false;
+export function cmdUpdate(run: SpawnSyncFn = execFileSync): void {
   try {
-    gitOrFatal(['merge', 'upstream/main'], 'git merge upstream/main', REPO_HOME);
+    run('npm', ['update', '-g', 'claude-nomad'], { stdio: 'inherit' });
   } catch (err) {
-    if (!tryAutoResolveMergeConflict(opts)) throw err;
-    autoResolved = true;
-  }
-  // No-op merge (and no extras precommit): HEAD never moved, so there is
-  // nothing new to push. A `beforeSha` of undefined (dry-run never reaches
-  // here) can never equal a real SHA, so the comparison is self-guarding.
-  if (headSha() === beforeSha) {
-    log('already in sync with origin/main, nothing to push');
-    return autoResolved;
-  }
-  if (opts.pushOrigin === true) {
-    gitOrFatal(['push', 'origin', 'main'], 'git push origin main', REPO_HOME);
-    return autoResolved;
-  }
-  const answer = promptFn(
-    'Push merge to origin/main? (y publishes to your private mirror so other hosts see it; N keeps it local) [y/N] ',
-  ).toLowerCase();
-  if (answer === 'y' || answer === 'yes') {
-    gitOrFatal(['push', 'origin', 'main'], 'git push origin main', REPO_HOME);
-  } else {
-    log('skipping push to origin (run `git push origin main` later)');
-  }
-  return autoResolved;
-}
-
-/**
- * Perform a topology-aware repository update.
- *
- * Detects `vanilla` (`origin` -> public) vs `fork` (`upstream` -> public,
- * `origin` -> private mirror) layouts, runs the right git invocation, runs
- * `npm install` only when `package-lock.json` changed in the update, and
- * ends with `cmdDoctor()` so the version-check PASS line confirms the
- * upgrade landed.
- *
- * Pre-flight (each fatal unless overridden):
- *   1. `REPO_HOME` exists.
- *   2. Topology resolves to `vanilla` or `fork`.
- *   3. `--push-origin` is fork-only (rejected on `vanilla`).
- *   4. Current branch is `main`.
- *   5. Working tree clean per `gitStatusPorcelainZ` (override with `force`).
- *
- * Fork-topology prompts read one line from `/dev/tty`; tests inject
- * `opts.prompt` to bypass the TTY read.
- *
- * @param opts - Update options. `dryRun` runs pre-flight + logs the would-be git, install, and doctor actions without mutating the repo or invoking `cmdDoctor`. `force` proceeds past a dirty working tree. `pushOrigin` (fork topology only) skips the y/N prompt. `prompt` injects a synchronous answer function for tests.
- */
-export function cmdUpdate(opts: CmdUpdateOpts = {}): void {
-  if (!existsSync(REPO_HOME)) die(`repo not cloned at ${REPO_HOME}`);
-
-  const topology = loadTopology();
-  if (topology === 'unknown') {
-    die(
-      `could not detect upstream remote in ${REPO_HOME}. Run \`git fetch <remote>\` and \`git merge <remote>/main\` manually.`,
-    );
-  }
-
-  if (topology === 'vanilla' && opts.pushOrigin === true) {
-    die('`--push-origin` is only valid for fork topology');
-  }
-
-  const branch = currentBranch();
-  if (branch !== 'main') {
-    die(`current branch is \`${branch}\`, expected \`main\``);
-  }
-
-  const status = gitStatusPorcelainZ(REPO_HOME);
-  if (status.length > 0) {
-    if (opts.force !== true) {
-      die('working tree is not clean, use `--force` to override');
+    const e = err as NodeJS.ErrnoException;
+    if (e.code === 'ENOENT') {
+      throw new NomadFatal('npm not found on PATH; install Node.js/npm and retry.');
     }
-    warn('working tree is not clean, proceeding because --force was passed');
+    throw new NomadFatal(`npm update -g claude-nomad failed: ${e.message}`);
   }
-
-  log(`topology: ${topology}`);
-
-  if (opts.dryRun === true) {
-    if (topology === 'vanilla') runVanilla(opts);
-    else runFork(opts);
-    log('DRY-RUN: would run `npm install` only if `package-lock.json` changed');
-    log('DRY-RUN: would run `nomad doctor` to confirm the upgrade');
-    return;
-  }
-
-  const beforeSha = headSha();
-  const installAlreadyRan = topology === 'vanilla' ? runVanilla(opts) : runFork(opts, beforeSha);
-
-  if (!installAlreadyRan) reinstallIfNeeded(beforeSha);
-  // Secondary item of issue #112: a post-merge `npm install` that regenerated
-  // package-lock.json leaves uncommitted drift the trailing doctor flags.
-  // Commit just the lockfile (fork topology only) so the repo is clean.
-  if (topology === 'fork') commitRegeneratedLockfile();
-  cmdDoctor();
 }

package/src/config.ts

@@ -31,14 +31,6 @@ export const CLAUDE_HOME = resolve(HOME, '.claude');
 // eslint-disable-next-line @typescript-eslint/prefer-nullish-coalescing
 export const REPO_HOME = process.env.NOMAD_REPO || resolve(HOME, 'claude-nomad');
 
-/**
- * Upstream GitHub repository slug for the release-version check in
- * `nomad doctor`. Hardcoded for the same reason `REPO_HOME` is hardcoded:
- * the deployed sync target is canonical for this CLI. Source of truth for
- * the `GET /repos/<slug>/releases/latest` call in `reportVersionCheck`.
- */
-export const UPSTREAM_REPO_SLUG = 'funkadelic/claude-nomad';
-
 /**
  * The official Claude Code settings JSON schema. Source of truth for
  * `SCHEMA_KEYS` (kept current by `scripts/sync-settings-keys.ts`) and the
@@ -189,6 +181,7 @@ export const PUSH_ALLOWED_STATIC = [
   'hosts/',
   'path-map.json',
   '.gitleaksignore', // written by nomad push Allow action (D-04)
+  '.gitleaks.overlay.toml', // user-owned gitleaks allowlist overlay layered on the bundled base
 ] as const;
 
 /**

package/src/init.gh-onboard.ts

@@ -0,0 +1,139 @@
+import { execFileSync } from 'node:child_process';
+
+import { REPO_HOME } from './config.ts';
+import { ghAuthStatus, readOriginRemote, type SpawnSyncFn } from './gh-actions.ts';
+import { die, log, NomadFatal } from './utils.ts';
+
+/**
+ * Default private GitHub repository name used by `ensureOriginRepo` when no
+ * explicit `--repo <name>` flag is provided. Users can override with
+ * `nomad init --repo <name>`.
+ */
+export const DEFAULT_REPO_NAME = 'claude-nomad-config';
+
+/**
+ * Validate a user-supplied GitHub repository name. Accepts only characters
+ * that GitHub allows: alphanumerics, hyphens, underscores, and dots, up to
+ * 100 characters. This blocks argument-injection or path-escape attempts when
+ * the name flows into subprocess argv (T-32-06).
+ */
+function isValidRepoName(name: string): boolean {
+  return /^[A-Za-z0-9._-]{1,100}$/.test(name);
+}
+
+/**
+ * Timeout for the network-bound `gh` calls in the onboarding create flow. These
+ * hit the GitHub API (repo creation, user lookup) and may also refresh auth, so
+ * a tight bound risks a false NomadFatal on a slow link. Generous on purpose:
+ * this is a one-time, user-initiated step, not the soft doctor version probe.
+ */
+const GH_NETWORK_TIMEOUT_MS = 30_000;
+
+/**
+ * Ensure REPO_HOME has a GitHub `origin` remote. When one already exists the
+ * function is a no-op (D-09 idempotency). When none exists, a new private
+ * repository named `repoName` is created via `gh repo create`, the owner is
+ * resolved from `gh api user`, and `git remote add origin` is wired into
+ * REPO_HOME. All subprocess calls use the argv-array form via the injectable
+ * `run` runner; no shell strings are used (T-32-06).
+ *
+ * `gh` is a hard prerequisite on this path: missing or unauthenticated `gh`
+ * results in a `NomadFatal` (D-08), not a soft tip.
+ *
+ * @param repoName - The GitHub repository name to create (validated by
+ *   `isValidRepoName` before any subprocess call).
+ * @param run - Injectable subprocess runner; defaults to `execFileSync`.
+ */
+export function ensureOriginRepo(repoName: string, run: SpawnSyncFn = execFileSync): void {
+  if (!isValidRepoName(repoName)) {
+    die(
+      `invalid repo name: ${JSON.stringify(repoName)}. Use only letters, digits, hyphens, underscores, and dots (1-100 chars).`,
+    );
+  }
+
+  // Fast idempotency path: if origin is already wired, nothing to do (D-09).
+  try {
+    readOriginRemote(REPO_HOME, run);
+    return;
+  } catch {
+    // No origin configured; fall through to the create flow.
+  }
+
+  // gh is a hard prerequisite when no origin is present (D-08).
+  const ghStatus = ghAuthStatus(run);
+  if (ghStatus === 'gh-not-installed') {
+    die('gh CLI is required for nomad init. Install: https://cli.github.com');
+  }
+  if (ghStatus === 'gh-probe-error') {
+    die('could not verify gh CLI status (network issue?). Retry, or check `gh auth status`.');
+  }
+  if (ghStatus !== null) {
+    die('gh CLI is not authenticated. Run `gh auth login` and retry.');
+  }
+
+  // Initialize REPO_HOME as a git repo so `git remote add` below has a
+  // repository to write to. On a first host REPO_HOME is a brand-new empty
+  // directory (just mkdir'd by cmdInit); without this `git remote add` fails
+  // with "not a git repository". `git init` is idempotent: re-running on an
+  // already-initialized repo reinitializes harmlessly and leaves the branch
+  // and config untouched.
+  try {
+    run('git', ['init', '-b', 'main'], { cwd: REPO_HOME, stdio: ['ignore', 'ignore', 'pipe'] });
+  } catch (err) {
+    const e = err as NodeJS.ErrnoException;
+    throw new NomadFatal(`git init failed: ${e.message}`);
+  }
+
+  // Create the private repo on GitHub. When the repo already exists on the
+  // account, gh exits non-zero; treat that as a no-op and fall through to wire
+  // origin rather than failing (D-09 idempotency: a prior run may have created
+  // the repo but died before `git remote add`). Any other failure is fatal.
+  try {
+    run('gh', ['repo', 'create', repoName, '--private'], {
+      stdio: ['ignore', 'pipe', 'pipe'],
+      timeout: GH_NETWORK_TIMEOUT_MS,
+    });
+  } catch (err) {
+    const e = err as NodeJS.ErrnoException & { stderr?: Buffer | string };
+    const detail = String(e.stderr ?? '') + e.message;
+    if (!/already exists/i.test(detail)) {
+      throw new NomadFatal(`gh repo create failed: ${e.message}`);
+    }
+    log(`repo ${repoName} already exists on your account; reusing it and wiring origin`);
+  }
+
+  // Resolve the authenticated user's login for the remote URL.
+  let owner: string;
+  try {
+    owner = run('gh', ['api', 'user', '--jq', '.login'], {
+      stdio: ['ignore', 'pipe', 'ignore'],
+      timeout: GH_NETWORK_TIMEOUT_MS,
+    })
+      .toString()
+      .trim();
+  } catch (err) {
+    const e = err as NodeJS.ErrnoException;
+    throw new NomadFatal(`gh api user failed: ${e.message}`);
+  }
+
+  // Guard an empty or null login: `gh api user --jq .login` yields an empty
+  // string or the literal "null" when the field is absent. Either would wire a
+  // malformed remote (git accepts any URL string) that fails confusingly only
+  // at first push, so fail fast here with a clear message instead.
+  if (owner.length === 0 || owner === 'null') {
+    throw new NomadFatal('gh api user returned an empty login; cannot wire origin remote.');
+  }
+
+  // Wire origin in the local git working tree.
+  try {
+    run('git', ['remote', 'add', 'origin', `git@github.com:${owner}/${repoName}.git`], {
+      cwd: REPO_HOME,
+      stdio: ['ignore', 'ignore', 'pipe'],
+    });
+  } catch (err) {
+    const e = err as NodeJS.ErrnoException;
+    throw new NomadFatal(`git remote add failed: ${e.message}`);
+  }
+
+  log(`created private repo ${owner}/${repoName} and wired origin`);
+}

package/src/init.ts

@@ -11,6 +11,7 @@ import {
   readOriginRemote,
   type SpawnSyncFn,
 } from './gh-actions.ts';
+import { DEFAULT_REPO_NAME, ensureOriginRepo } from './init.gh-onboard.ts';
 import { snapshotIntoShared } from './init.snapshot.ts';
 import { die, log } from './utils.ts';
 import { writeJsonAtomic } from './utils.fs.ts';
@@ -60,6 +61,13 @@ function preflightConflict(repoHome: string): string | null {
  * `{"projects":{}}`. No auto-commit; no lock (no concurrent-mutator surface
  * on a fresh target).
  *
+ * When no `origin` remote exists in REPO_HOME, a private GitHub repository is
+ * created via `gh` and wired as `origin` before scaffolding (D-06/D-07). The
+ * repo name defaults to {@link DEFAULT_REPO_NAME} but can be overridden with
+ * `opts.repoName`. `gh` is a hard prerequisite on this path and its absence or
+ * unauthenticated state results in a NomadFatal (D-08). When `origin` already
+ * exists the step is a no-op (D-09 idempotency).
+ *
  * When `opts.snapshot` is true, the user's current `~/.claude/` SHARED_LINKS
  * are overlaid onto `shared/` and `~/.claude/settings.json` (if present) is
  * translated into `hosts/<HOST>.json`. The placeholder `shared/CLAUDE.md`
@@ -70,16 +78,26 @@ function preflightConflict(repoHome: string): string | null {
  * partial state is unsafe to merge with.
  */
 export function cmdInit(
-  opts: { snapshot?: boolean; keepActions?: boolean; run?: SpawnSyncFn } = {},
+  opts: { snapshot?: boolean; keepActions?: boolean; repoName?: string; run?: SpawnSyncFn } = {},
 ): void {
   const snapshot = opts.snapshot === true;
   const keepActions = opts.keepActions === true;
 
+  // Create REPO_HOME, then refuse to clobber an already-initialized tree BEFORE
+  // any onboarding side effects. ensureOriginRepo can create a GitHub repo and
+  // wire a remote, so the conflict guard must run first: otherwise a re-init on
+  // an already-scaffolded REPO_HOME that lacks an origin would create a stray
+  // private repo and wire it, then abort with "already initialized".
+  mkdirSync(REPO_HOME, { recursive: true });
+
   const conflict = preflightConflict(REPO_HOME);
   if (conflict !== null) {
     die(`already initialized; refusing to clobber ${conflict}`);
   }
 
+  // Wire the backing GitHub repo. Idempotent when origin already exists (D-09).
+  ensureOriginRepo(opts.repoName ?? DEFAULT_REPO_NAME, opts.run);
+
   // Create the directory structure first so the subsequent file writes have
   // a parent. `recursive: true` is a no-op when the dir already exists, but
   // the preflight guarantees it does not.

package/src/nomad.dispatch.ts

@@ -24,6 +24,101 @@ export function parseFlags(argv: string[], known: Set<string>): Set<string> | nu
   return seen;
 }
 
+/** Parsed result from {@link parseInitArgs}. */
+export type InitArgs = {
+  /** True when `--snapshot` was present. */
+  snapshot: boolean;
+  /** True when `--keep-actions` was present. */
+  keepActions: boolean;
+  /** Optional repo name supplied via `--repo <name>`. */
+  repoName: string | undefined;
+};
+
+/**
+ * Extract the value following a `--flag <value>` pair. Returns the value
+ * string on success, or `null` when the next token is missing or starts with
+ * `--` (which would indicate the flag was supplied without a value).
+ */
+function extractFlagValue(argv: string[], i: number): string | null {
+  const val = argv[i + 1];
+  if (val === undefined || val.startsWith('--')) return null;
+  return val;
+}
+
+/** Internal state threaded through the parseInitArgs loop. */
+type InitParseState = {
+  snapshot: boolean;
+  keepActions: boolean;
+  repoName: string | undefined;
+  sawSnapshot: boolean;
+  sawKeepActions: boolean;
+  sawRepo: boolean;
+};
+
+/**
+ * Apply one token from the init argv to the parse state. Returns `true` on
+ * success or `false` when the token is invalid (unknown flag, duplicate, or
+ * `--repo` with no valid value). Advances `i` by mutation via the returned
+ * increment: 1 for boolean flags, 2 for `--repo <value>`.
+ */
+function applyInitToken(
+  argv: string[],
+  i: number,
+  st: InitParseState,
+): { ok: boolean; advance: number } {
+  const token = argv[i];
+  if (token === '--snapshot') {
+    if (st.sawSnapshot) return { ok: false, advance: 0 };
+    st.sawSnapshot = true;
+    st.snapshot = true;
+    return { ok: true, advance: 1 };
+  }
+  if (token === '--keep-actions') {
+    if (st.sawKeepActions) return { ok: false, advance: 0 };
+    st.sawKeepActions = true;
+    st.keepActions = true;
+    return { ok: true, advance: 1 };
+  }
+  if (token === '--repo') {
+    if (st.sawRepo) return { ok: false, advance: 0 };
+    st.sawRepo = true;
+    const val = extractFlagValue(argv, i);
+    if (val === null) return { ok: false, advance: 0 };
+    st.repoName = val;
+    return { ok: true, advance: 2 };
+  }
+  return { ok: false, advance: 0 };
+}
+
+/**
+ * Argv parser for `nomad init [--snapshot] [--keep-actions] [--repo <name>]`.
+ *
+ * Handles boolean `--snapshot` and `--keep-actions` flags plus an optional
+ * value-bearing `--repo <name>`. Returns `null` on any parse error: unknown
+ * flag, duplicate flag, `--repo` with no value, or `--repo` whose value
+ * starts with `--`.
+ *
+ * @param argv The full process argv array (parsing starts at index 3).
+ * @returns Parsed init arguments, or `null` on any parse error.
+ */
+export function parseInitArgs(argv: string[]): InitArgs | null {
+  const st: InitParseState = {
+    snapshot: false,
+    keepActions: false,
+    repoName: undefined,
+    sawSnapshot: false,
+    sawKeepActions: false,
+    sawRepo: false,
+  };
+  let i = 3;
+  while (i < argv.length) {
+    const { ok, advance } = applyInitToken(argv, i, st);
+    if (!ok) return null;
+    i += advance;
+  }
+  return { snapshot: st.snapshot, keepActions: st.keepActions, repoName: st.repoName };
+}
+
 /** Parsed result from {@link parseRedactArgs}. */
 export type RedactArgs = {
   /** Validated session id. */

package/src/nomad.help.ts

@@ -6,6 +6,8 @@
  * into the README. Channel is stderr, exit code is 1.
  */
 
+import pkg from '../package.json' with { type: 'json' };
+
 /**
  * Column (0-indexed) at which every command and flag description starts. Sized
  * to clear the longest label (`--resume-cmd <id>`, which ends at column 24)
@@ -28,6 +30,8 @@ const row = (label: string, desc: string): string => label.padEnd(DESC_COL) + de
 const cont = (text: string): string => ' '.repeat(DESC_COL) + text;
 
 export const DEFAULT_HELP = [
+  `claude-nomad v${pkg.version}`,
+  '',
   'usage: nomad <command> [flags]',
   '',
   'Commands:',
@@ -43,9 +47,16 @@ export const DEFAULT_HELP = [
   row('  diff', 'Offline preview of what `pull` would change against local repo state.'),
   cont('No git pull, no lock acquired.'),
   '',
-  row('  init', 'Scaffold an empty ~/claude-nomad/ repo (shared/, hosts/, path-map).'),
+  row(
+    '  init',
+    'Create a private GitHub repo via gh (if none exists), scaffold shared/, hosts/, path-map.',
+  ),
   row('       --snapshot', 'Overlay the current ~/.claude/ into shared/ as the initial seed.'),
   row('       --keep-actions', 'Skip auto-disabling GitHub Actions on the private mirror.'),
+  row(
+    '       --repo <name>',
+    'Name for the new GitHub repo (default: claude-nomad-config). No-op when origin exists.',
+  ),
   '',
   row('  doctor', 'Read-only health check (symlinks, host file, path-map,'),
   cont('gitleaks, gitlinks).'),
@@ -76,13 +87,7 @@ export const DEFAULT_HELP = [
   row('       --rule <id>', 'Limit redaction to one gitleaks rule id.'),
   row('       --dry-run', 'Show what would change without writing.'),
   '',
-  row('  update', 'Topology-aware upgrade of ~/claude-nomad/ to the latest upstream.'),
-  row('       --dry-run', 'Detect topology + pre-flight, print would-be git commands only.'),
-  row('       --force', 'Proceed even when the working tree is not clean.'),
-  row(
-    '       --push-origin',
-    'Fork topology only: push the merge to origin/main without prompting.',
-  ),
+  row('  update', 'Update the claude-nomad CLI to the latest npm release.'),
   '',
   row('  --version', 'Print the installed CLI version as bare semver to stdout; exits 0.'),
   '',