oh-my-space 0.13.0 → 0.14.0

package/README.md

@@ -75,7 +75,7 @@ oms/
 Start a branch, commit inside the submodule, push it, then record the pointer move in your project history. Each command stays in a single Git scope:
 
 ```bash
-oms switch api feature/login         # local branch, no remote needed
+oms branch switch api feature/login  # local branch, no remote needed
 oms commit api -m "feat: add login"  # commit inside oms/api (submodule only)
 oms push api                         # creates origin/feature/login (submodule branch only)
 oms record api                       # commit the moved oms/api pointer in your project history
@@ -83,7 +83,7 @@ oms record api                       # commit the moved oms/api pointer in your
 
 `oms commit` and `oms push` stay inside the submodule and never touch the root gitlink; `oms record` is the only command that commits an existing root pointer update. After a successful `oms commit`/`oms pull`/`oms push`, `oms` prints an `oms record <alias>` hint when the pointer has moved. Run `oms status --json` for a machine-readable view of which scope changed.
 
-Omit the alias or branch on `oms switch` and `oms checkout` to pick one interactively — synced submodules, and local or `origin/*` branches respectively.
+Omit the alias or branch on `oms branch switch` and `oms branch checkout` to pick one interactively — synced submodules, and local or `origin/*` branches respectively.
 
 ## Listing branches
 
@@ -92,7 +92,7 @@ Omit the alias or branch on `oms switch` and `oms checkout` to pick one interact
 ```bash
 oms branch list api
 oms branch list
-oms branch # choose list or delete interactively
+oms branch # choose list, switch, checkout, or delete interactively
 ```
 
 Before listing, OMS safely initializes an existing registered submodule when needed, reconciles every remote declared for that alias in `oms.yaml`, and runs `git fetch <remote> --prune` sequentially in manifest order. A failed fetch is retried once. If both attempts fail, cached refs remain visible as `stale`; a failed remote without usable refs is `unavailable`. These degraded states still exit 0 when local refs can be inspected. Extra local remotes are not fetched or included in the remote inventory, although an actual configured upstream on one of them remains visible for its local branch.
@@ -113,7 +113,7 @@ When `branch` is omitted from `oms.yaml`, a successful origin fetch refreshes `o
 oms branch delete api feature/login        # safe delete (git branch -d)
 oms branch delete api feature/login --force # force delete (git branch -D)
 oms branch delete                           # pick alias, then branch, interactively
-oms branch                                  # interactive list/delete action selector
+oms branch                                  # interactive list/switch/checkout/delete action selector
 ```
 
 - **Local only.** It never deletes a remote branch or a remote-tracking ref, never fetches or pushes, and never stages or commits the root gitlink. A missing local branch whose name exists on `origin` is reported as local-only.
@@ -133,7 +133,7 @@ oms branch                                  # interactive list/delete action sel
 
 `oms` does not replace Git submodules. It adds a small command layer for the workflow details that make submodules awkward. Submodules already give you a reproducible pin (the parent records each source's exact commit), visibility (`git status` shows when a pointer moved), and history (the pointer travels with your commits). The friction is in everyday branch work, and that is what `oms` smooths over:
 
-- **Start branches locally.** `oms switch <alias> <branch>` starts a local branch right away, even before it exists on the remote. `oms checkout <alias> <branch>` fetches origin and checks out an existing remote branch as a tracking branch. The remote branch is created lazily on your first `oms push`.
+- **Start branches locally.** `oms branch switch <alias> <branch>` starts a local branch right away, even before it exists on the remote. `oms branch checkout <alias> <branch>` fetches origin and checks out an existing remote branch as a tracking branch. The remote branch is created lazily on your first `oms push`.
 - **Stay on a branch.** `oms sync` attaches the baseline branch at the pinned commit instead of leaving a detached HEAD, so everyday submodule work never strands you off a branch.
 - **Keep pointer moves visible, commit them explicitly.** `oms pull` and `oms push` synchronize only the submodule branch — they never stage or commit the root gitlink. The moved pointer shows up in `git status`, `oms status` flags when a submodule has drifted from the recorded pointer, and `oms record <alias>` commits that pointer update in the parent repo.
 
@@ -173,7 +173,7 @@ The three skills are named by the Git domain each manages:
 | --- | --- | --- |
 | `oms-workspace` | Scope-ambiguous Git work in the workspace — committing from the root, a moved `oms status` pointer, a push, or adding/removing a repo with `oms sync`/`oms unsync`. | Establishes workspace state and root-versus-submodule scope before acting, and separates repo add/remove topology from recording a moved pointer. |
 | `oms-pointer` | After `oms commit` or `oms pull` moves a submodule's commit. | Records the moved root pointer with `oms record`, so a submodule change is not left without a recorded pointer and the root pointer is not committed by mistake. |
-| `oms-branch` | Starting or switching a branch inside a submodule. | Chooses `oms switch` (new local branch) versus `oms checkout` (track a remote branch) and avoids detached HEAD. |
+| `oms-branch` | Starting or switching a branch inside a submodule. | Chooses `oms branch switch` (new local branch) versus `oms branch checkout` (track a remote branch) and avoids detached HEAD. |
 
 Skill firing is best-effort — an agent loads a skill only when it judges the skill's description relevant — so the skills complement, rather than replace, `oms <command> --help` and the always-on marker block inside `oms/`. Each skill defers exact `oms status --json` field semantics to `oms status --help`, the version-matched authoritative source that ships with the installed CLI.
 
@@ -189,8 +189,8 @@ Skill firing is best-effort — an agent loads a skill only when it judges the s
 | `oms status [alias...]` / `--all` | anywhere under root | Prints branch, pointer state (`ok`/`moved`/`uninit`/`missing`/`conflict`), dirtiness, and ahead/behind for each submodule. | `moved` means the working commit differs from the recorded pointer — record it with `oms record`. `--json` prints one machine-readable object on stdout for tooling and agents. |
 | `oms commit [alias]` | workspace root or inside `oms/<alias>/` | Commits source changes inside the selected submodule only; never the root gitlink. | `-m <message>` is required (repeatable). Commits existing staged changes as-is, otherwise stages all with `git add -A`. Infers the alias from the current `oms/<alias>/` directory. |
 | `oms record [alias]` | workspace root or inside `oms/<alias>/` | Commits an existing root gitlink pointer update for one alias (`chore(oms): update <alias> submodule to <sha>`). | Root repo only, path-limited to `oms/<alias>`; refuses unrelated staged changes. Not for adds/removals — use `oms sync`/`oms unsync`. |
-| `oms switch [alias] [branch]` | workspace root | `git switch` to a LOCAL branch, creating it locally if it does not exist yet (no remote required). | `--from <ref>` sets the start point for a new branch. Omit alias/branch to pick interactively (or create a new branch). |
-| `oms checkout [alias] [branch]` | workspace root | `git fetch origin --prune`, then check out a REMOTE branch (`origin/*`) as a local tracking branch (or switch to an existing local counterpart). | Omit alias/branch to pick interactively. To create a brand-new local branch, use `oms switch`. |
+| `oms branch switch [alias] [branch]` | workspace root | `git switch` to a LOCAL branch, creating it locally if it does not exist yet (no remote required). | `--from <ref>` sets the start point for a new branch. Omit alias/branch to pick interactively (or create a new branch). |
+| `oms branch checkout [alias] [branch]` | workspace root | `git fetch origin --prune`, then check out a REMOTE branch (`origin/*`) as a local tracking branch (or switch to an existing local counterpart). | Omit alias/branch to pick interactively. To create a brand-new local branch, use `oms branch switch`. |
 | `oms branch list [alias]` | workspace root | Safely prepares one declared submodule, refreshes all declared remotes, and lists local and remote-tracking branches. | Shows baseline certainty, current/baseline flags, exact upstream divergence, detached HEAD, and per-remote `fresh`/`stale`/`unavailable` state. Never switches a branch or changes a root gitlink outside an explicitly accepted `oms sync`. |
 | `oms branch delete [alias] [branch]` | workspace root | Deletes one LOCAL branch inside one initialized submodule with `git branch -d` (safe) or `-D` (`--force`). | Local only — never deletes a remote or remote-tracking ref, never touches the root gitlink. Protects the current branch and every resolved baseline (see below). Omit alias/branch to pick interactively; a registered-but-uninitialized alias is initialized first. Exit 0 on success, 1 on input/precondition errors, 2 on a declined/failed/concurrent deletion. |
 | `oms fetch ...` | workspace root | `git fetch <remote> --prune` in each submodule. | `--remote <name>` (repeatable) picks the remote(s); omit to choose interactively, defaults to `origin`. |
@@ -256,6 +256,7 @@ JSON schema: [`oms.schema.json`](./oms.schema.json) (also reachable at `https://
 
 Detailed migration steps are organized per version under [`docs/migrations/`](./docs/migrations/).
 
+- [0.13.x → 0.14.0](./docs/migrations/0.13.x-to-0.14.0.md) — relocates `oms switch` / `oms checkout` under the `oms branch` group as `oms branch switch` / `oms branch checkout` (top-level commands removed, no aliases)
 - [0.11.x → 0.12.0](./docs/migrations/0.11.x-to-0.12.0.md) — adds `oms branch delete` and makes `oms sync` reconcile declarative `.gitmodules` metadata with stricter baseline validation and a durable finalization recovery preflight
 - [0.9.x → 0.10.0](./docs/migrations/0.9.x-to-0.10.0.md) — scopes each command to a single Git boundary and makes root pointer commits explicit via `oms record`
 - [0.7.x → 0.8.0](./docs/migrations/0.7.x-to-0.8.0.md) — splits `oms checkout` into `oms switch` (local branches) and `oms checkout` (remote branches)

package/dist/build-info.json

@@ -1 +1 @@
-{"commit":"be1d798a55c5e7fae0b33ef6057661a1ac25a5d7"}
+{"commit":"a0692fa946bc1ae17a53ecdda5077dad9dbd894d"}

package/dist/oms.js

@@ -16033,7 +16033,7 @@ async function resolveInitializedAlias(repos, repoRoot, alias, actionLabel) {
   }
   const initialized2 = repos.filter((r) => submoduleInitialized(repoRoot, r.alias));
   if (initialized2.length === 0) {
-    R2.error(`No synced submodules to ${actionLabel}. Run "oms sync" first.`);
+    R2.error(`No synced submodules available for "oms ${actionLabel}". Run "oms sync" first.`);
     return null;
   }
   if (!process.stdin.isTTY) {
@@ -16041,7 +16041,7 @@ async function resolveInitializedAlias(repos, repoRoot, alias, actionLabel) {
     return null;
   }
   const choice = await xe({
-    message: `Select a source repo to ${actionLabel}`,
+    message: `Select a source repo for "oms ${actionLabel}"`,
     options: initialized2.map((r) => ({
       value: r.alias,
       label: r.alias,
@@ -17118,6 +17118,72 @@ async function runBranchList(aliasArg) {
 }
 __name(runBranchList, "runBranchList");
 
+// scripts/lib/branch-ops.ts
+async function runSwitch(alias, branch, options) {
+  const loaded = loadForSubmodules();
+  if (!loaded) return 1;
+  const { repos, repoRoot } = loaded;
+  const repo = await resolveInitializedAlias(repos, repoRoot, alias, "branch switch");
+  if (!repo) return 1;
+  const dir = aliasDir(repoRoot, repo.alias);
+  let target = branch;
+  if (!target) {
+    const picked = await pickBranch(listLocalBranches(dir), `${repo.alias}: select a local branch`, true);
+    if (!picked) return 1;
+    target = picked;
+  }
+  if (localBranchExists(dir, target)) {
+    R2.step(`${repo.alias}: git switch ${target}`);
+    const r2 = runSub(repoRoot, repo.alias, ["switch", target], true);
+    if (!r2.success) return 2;
+    R2.success(`${repo.alias}: on ${target}`);
+    return 0;
+  }
+  const args = ["switch", "-c", target, ...options.from ? [options.from] : []];
+  R2.step(`${repo.alias}: git ${args.join(" ")}`);
+  const r = runSub(repoRoot, repo.alias, args, true);
+  if (!r.success) return 2;
+  R2.success(`${repo.alias}: created new local branch ${target}. Push it with "oms push ${repo.alias}".`);
+  return 0;
+}
+__name(runSwitch, "runSwitch");
+async function runCheckout(alias, branch) {
+  const loaded = loadForSubmodules();
+  if (!loaded) return 1;
+  const { repos, repoRoot } = loaded;
+  const repo = await resolveInitializedAlias(repos, repoRoot, alias, "branch checkout");
+  if (!repo) return 1;
+  const dir = aliasDir(repoRoot, repo.alias);
+  R2.step(`${repo.alias}: git fetch origin --prune`);
+  const fetch2 = runSub(repoRoot, repo.alias, ["fetch", "origin", "--prune"], true);
+  if (!fetch2.success) return 2;
+  let target = branch;
+  if (!target) {
+    const picked = await pickBranch(listRemoteBranches(dir), `${repo.alias}: select a remote branch (origin/*)`, false);
+    if (!picked) return 1;
+    target = picked;
+  }
+  if (localBranchExists(dir, target)) {
+    R2.step(`${repo.alias}: git switch ${target}`);
+    const r = runSub(repoRoot, repo.alias, ["switch", target], true);
+    if (!r.success) return 2;
+    R2.success(`${repo.alias}: on ${target}`);
+    return 0;
+  }
+  if (remoteBranchExists(dir, target)) {
+    R2.step(`${repo.alias}: git switch -c ${target} origin/${target}`);
+    const r = runSub(repoRoot, repo.alias, ["switch", "-c", target, `origin/${target}`], true);
+    if (!r.success) return 2;
+    R2.success(`${repo.alias}: on ${target} (tracking origin/${target})`);
+    return 0;
+  }
+  R2.error(
+    `${repo.alias}: "${target}" not found on origin. To create a new local branch, run "oms branch switch ${repo.alias} ${target}".`
+  );
+  return 1;
+}
+__name(runCheckout, "runCheckout");
+
 // scripts/lib/branch-delete.ts
 function interactive2() {
   return Boolean(process.stdin.isTTY) || promptQueueActive();
@@ -17136,6 +17202,8 @@ async function runBranch(command) {
     message: "Select a branch action",
     options: [
       { value: "list", label: "list branches in a submodule" },
+      { value: "switch", label: "switch to or create a local branch in a submodule" },
+      { value: "checkout", label: "check out a remote branch in a submodule" },
       { value: "delete", label: "delete a local branch in a submodule" }
     ]
   });
@@ -17144,6 +17212,8 @@ async function runBranch(command) {
     return 1;
   }
   if (action === "list") return runBranchList(void 0);
+  if (action === "switch") return runSwitch(void 0, void 0, {});
+  if (action === "checkout") return runCheckout(void 0, void 0);
   if (action === "delete") return runBranchDelete(void 0, void 0, {});
   return 1;
 }
@@ -17218,7 +17288,7 @@ function checkSubmodulePreconditions(repoRoot, repo) {
     if (!anchored) {
       return {
         ok: false,
-        reason: `${repo.alias}: submodule HEAD is detached and not anchored to the recorded gitlink. Attach it with "oms switch ${repo.alias} <branch>" first.`
+        reason: `${repo.alias}: submodule HEAD is detached and not anchored to the recorded gitlink. Attach it with "oms branch switch ${repo.alias} <branch>" first.`
       };
     }
   }
@@ -17408,72 +17478,6 @@ async function runBranchDelete(aliasArg, branchArg, options) {
 }
 __name(runBranchDelete, "runBranchDelete");
 
-// scripts/lib/branch-ops.ts
-async function runSwitch(alias, branch, options) {
-  const loaded = loadForSubmodules();
-  if (!loaded) return 1;
-  const { repos, repoRoot } = loaded;
-  const repo = await resolveInitializedAlias(repos, repoRoot, alias, "switch");
-  if (!repo) return 1;
-  const dir = aliasDir(repoRoot, repo.alias);
-  let target = branch;
-  if (!target) {
-    const picked = await pickBranch(listLocalBranches(dir), `${repo.alias}: select a local branch`, true);
-    if (!picked) return 1;
-    target = picked;
-  }
-  if (localBranchExists(dir, target)) {
-    R2.step(`${repo.alias}: git switch ${target}`);
-    const r2 = runSub(repoRoot, repo.alias, ["switch", target], true);
-    if (!r2.success) return 2;
-    R2.success(`${repo.alias}: on ${target}`);
-    return 0;
-  }
-  const args = ["switch", "-c", target, ...options.from ? [options.from] : []];
-  R2.step(`${repo.alias}: git ${args.join(" ")}`);
-  const r = runSub(repoRoot, repo.alias, args, true);
-  if (!r.success) return 2;
-  R2.success(`${repo.alias}: created new local branch ${target}. Push it with "oms push ${repo.alias}".`);
-  return 0;
-}
-__name(runSwitch, "runSwitch");
-async function runCheckout(alias, branch) {
-  const loaded = loadForSubmodules();
-  if (!loaded) return 1;
-  const { repos, repoRoot } = loaded;
-  const repo = await resolveInitializedAlias(repos, repoRoot, alias, "checkout");
-  if (!repo) return 1;
-  const dir = aliasDir(repoRoot, repo.alias);
-  R2.step(`${repo.alias}: git fetch origin --prune`);
-  const fetch2 = runSub(repoRoot, repo.alias, ["fetch", "origin", "--prune"], true);
-  if (!fetch2.success) return 2;
-  let target = branch;
-  if (!target) {
-    const picked = await pickBranch(listRemoteBranches(dir), `${repo.alias}: select a remote branch (origin/*)`, false);
-    if (!picked) return 1;
-    target = picked;
-  }
-  if (localBranchExists(dir, target)) {
-    R2.step(`${repo.alias}: git switch ${target}`);
-    const r = runSub(repoRoot, repo.alias, ["switch", target], true);
-    if (!r.success) return 2;
-    R2.success(`${repo.alias}: on ${target}`);
-    return 0;
-  }
-  if (remoteBranchExists(dir, target)) {
-    R2.step(`${repo.alias}: git switch -c ${target} origin/${target}`);
-    const r = runSub(repoRoot, repo.alias, ["switch", "-c", target, `origin/${target}`], true);
-    if (!r.success) return 2;
-    R2.success(`${repo.alias}: on ${target} (tracking origin/${target})`);
-    return 0;
-  }
-  R2.error(
-    `${repo.alias}: "${target}" not found on origin. To create a new local branch, run "oms switch ${repo.alias} ${target}".`
-  );
-  return 1;
-}
-__name(runCheckout, "runCheckout");
-
 // scripts/lib/commit.ts
 async function runCommit(alias, options) {
   const loaded = loadForSubmodules();
@@ -17496,7 +17500,7 @@ async function runCommit(alias, options) {
     return 1;
   }
   if (currentBranch(dir) === null) {
-    R2.error(`${selected}: detached HEAD. Run "oms switch ${selected} <branch>" before committing.`);
+    R2.error(`${selected}: detached HEAD. Run "oms branch switch ${selected} <branch>" before committing.`);
     return 1;
   }
   const messages = options.message ?? [];
@@ -17657,7 +17661,7 @@ async function runDoctor() {
     const dir = aliasDir(repoRoot, repo.alias);
     const branch = currentBranch(dir);
     if (!branch) {
-      R2.warn(`${repo.alias}: detached HEAD. Run "oms switch ${repo.alias} <branch>" to get on a branch.`);
+      R2.warn(`${repo.alias}: detached HEAD. Run "oms branch switch ${repo.alias} <branch>" to get on a branch.`);
       warnings++;
     } else {
       R2.success(`${repo.alias}: submodule OK (branch=${branch})`);
@@ -17805,7 +17809,7 @@ function pullRepo(repo, repoRoot, remote) {
   const branch = currentBranch(aliasDir(repoRoot, repo.alias));
   if (!branch) {
     R2.error(
-      `${repo.alias}: detached HEAD. Run "oms switch ${repo.alias} <branch>" before pulling.`
+      `${repo.alias}: detached HEAD. Run "oms branch switch ${repo.alias} <branch>" before pulling.`
     );
     return "failed";
   }
@@ -17834,7 +17838,7 @@ function pushRepo(repo, repoRoot, remotes) {
   const branch = currentBranch(aliasDir(repoRoot, repo.alias));
   if (!branch) {
     R2.error(
-      `${repo.alias}: detached HEAD. Run "oms switch ${repo.alias} <branch>" before pushing.`
+      `${repo.alias}: detached HEAD. Run "oms branch switch ${repo.alias} <branch>" before pushing.`
     );
     return "failed";
   }
@@ -18438,8 +18442,6 @@ var commandNames = /* @__PURE__ */ new Set([
   "status",
   "commit",
   "record",
-  "switch",
-  "checkout",
   "branch",
   "fetch",
   "pull",
@@ -18477,19 +18479,19 @@ program2.command("commit").description("Commit source changes inside the selecte
 program2.command("record").description("Commit an existing root gitlink pointer update for the selected submodule (root repo only).").argument("[alias]", "registered source alias (omit to infer from the current oms/<alias>/ directory)").addHelpText("after", `${recordHelp}${exitHelp}`).action(async (alias) => {
   await exitWith(runRecord(alias));
 });
-program2.command("switch").description(
+var branchCommand = program2.command("branch").description("Inspect, switch, checkout, or delete submodule branches (interactive action selector).").addHelpText("after", exitHelp).action(async () => {
+  await exitWith(runBranch(branchCommand));
+});
+branchCommand.command("switch").description(
   "Switch a submodule to a LOCAL branch, creating it locally if it does not exist yet (no remote required)."
 ).argument("[alias]", "registered source alias (omit to pick interactively)").argument("[branch]", "local branch name (omit to pick from local branches or create one)").option("--from <ref>", "start point for a new branch (default: current HEAD)").addHelpText("after", exitHelp).action(async (alias, branch, options) => {
   await exitWith(runSwitch(alias, branch, options));
 });
-program2.command("checkout").description(
+branchCommand.command("checkout").description(
   "Fetch origin, then check out a REMOTE branch (origin/*) as a local tracking branch."
 ).argument("[alias]", "registered source alias (omit to pick interactively)").argument("[branch]", "remote branch name (omit to pick from origin/* branches)").addHelpText("after", exitHelp).action(async (alias, branch) => {
   await exitWith(runCheckout(alias, branch));
 });
-var branchCommand = program2.command("branch").description("Inspect or delete submodule branches (interactive action selector).").addHelpText("after", exitHelp).action(async () => {
-  await exitWith(runBranch(branchCommand));
-});
 branchCommand.command("list").description("Prepare one submodule, refresh declared remotes, and list local and remote branches.").argument("[alias]", "declared source alias (the sole alias is selected automatically)").addHelpText(
   "after",
   `

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oh-my-space",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "description": "Manage multi-repo workspaces with Git submodules.",
   "license": "MIT",
   "homepage": "https://github.com/divlook/oh-my-space",