oh-my-space 0.7.1 → 0.9.0

package/README.md

@@ -10,7 +10,7 @@ Command name: `oms`
 
 Git submodules give you three things for free: 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). What they make awkward is day-to-day branch work. `oms` keeps the native benefits and removes the friction:
 
-- **Create a new branch locally, with no remote precondition.** `oms checkout <alias> <branch>` makes the branch right away even if it does not exist on the remote yet. The remote branch is created lazily on your first `oms push`.
+- **Create a new branch locally, with no remote precondition.** `oms switch <alias> <branch>` makes the branch right away even if it does not exist on the remote yet; `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`.
 - **Always on a branch, never detached.** `oms sync` attaches the baseline branch at the pinned commit instead of leaving a detached HEAD.
 - **Pointer moves stay visible.** `oms pull` / `oms push` stage the updated gitlink in the parent so you can see and commit it; `oms status` surfaces drift.
 
@@ -67,16 +67,19 @@ oms sync --list                   # list registered source repos
 oms sync <alias>...               # add/initialize submodules on their baseline branch
 oms sync --all                    # sync every registered source repo
 oms status                        # branch / pointer / dirty / ahead-behind per submodule
-oms checkout <alias> <branch>     # switch (or create a brand-new local branch)
+oms switch <alias> <branch>       # switch to a local branch, or create a brand-new one
+oms checkout <alias> <branch>     # fetch origin, then check out a remote branch (tracking)
 oms push <alias>...               # push the branch (lazy remote) + stage the pointer
 oms push <alias> --remote upstream  # target a specific remote (repeatable; defaults to origin)
 oms unsync <alias>...             # deinitialize and remove a submodule
 ```
 
+For `oms switch` and `oms checkout`, omitting the alias and/or branch prompts you to pick one interactively (synced submodules, and local or `origin/*` branches respectively).
+
 A typical new-branch flow:
 
 ```bash
-oms checkout api feature/login    # local branch, no remote needed
+oms switch api feature/login      # local branch, no remote needed
 # ... edit, commit inside oms/api ...
 oms push api                      # creates origin/feature/login and stages the pointer
 git add oms/api && git commit     # record the pointer in your project history
@@ -104,7 +107,8 @@ oms/
 | `oms doctor` | project root or child path | Checks `oms.yaml`, git availability, that the workspace is a git repo, and each alias's submodule state. | Returns exit 2 if any warning is raised. |
 | `oms sync <alias>` / `--all` | workspace root | Registers missing repos with `git submodule add`, initializes registered-but-uninitialized ones, fetches, and attaches the baseline branch. | Reproduces the recorded pointer on a fresh clone. |
 | `oms status [alias...]` / `--all` | anywhere under root | Prints branch, pointer state (`ok`/`moved`/`uninit`), dirtiness, and ahead/behind for each submodule. | `moved` means the working commit differs from the recorded pointer — stage/commit it. |
-| `oms checkout <alias> <branch>` | workspace root | `git switch` to the branch; creates it locally if it exists nowhere yet (no remote required). | `--from <ref>` sets the start point for a new branch. |
+| `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 fetch ...` | workspace root | `git fetch <remote> --prune` in each submodule. | `--remote <name>` (repeatable) picks the remote(s); omit to choose interactively, defaults to `origin`. |
 | `oms pull ...` | workspace root | `git pull --ff-only <remote>` on each submodule's current branch, then stages the moved pointer. | Requires the submodule to be on a branch. `--remote <name>` selects a single remote (defaults to `origin`). |
 | `oms push <alias>...` | workspace root | `git push <remote> <branch>` (creating the remote branch on first push), then stages the moved pointer. | `--remote <name>` (repeatable) picks the remote(s), defaults to `origin`; upstream is set only for `origin`. `--commit` also commits the pointer update in the parent. |
@@ -128,7 +132,12 @@ repos:
 Rules:
 
 - `repos` must be a non-empty array.
-- `alias` must be unique and match `/^[a-z0-9][a-z0-9-]*$/`.
+- `alias` must be unique.
+  - Used as the directory name under `oms/<alias>/`.
+  - First character: ASCII lowercase letter or digit.
+  - Remaining characters: ASCII lowercase letters, digits, `-`, `_`, `@`.
+  - Not allowed: uppercase letters, `/`, `\`, `.`, whitespace.
+  - Pattern: `/^[a-z0-9][a-z0-9_@-]*$/`.
 - `remotes` is required and must include an `origin` entry; each value is a clonable git URL. `origin` becomes the submodule's primary remote, and additional remotes are configured on `oms sync`.
 - `branch` is optional; when omitted the remote's default branch is used as the baseline.
 
@@ -138,6 +147,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.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)
 - [0.5.x → 0.6.0](./docs/migrations/0.5.x-to-0.6.0.md) — switches the data model from bare clone + worktrees back to git submodules
 - [0.3.x → 0.4.0](./docs/migrations/0.3.x-to-0.4.0.md) — renames `sources.yaml`/`sources/` to `oms.yaml`/`oms/`
 - [0.2.x → 0.3.0](./docs/migrations/0.2.x-to-0.3.0.md) — (historical) switched submodules to bare clone + worktrees

package/dist/build-info.json

@@ -1 +1 @@
-{"commit":"b3b6890088ebe3eb5dd965d2fdd730a60b5a0a01"}
+{"commit":"b2c2b0bb4e51a35fc36da6d65f40229c896f1d70"}

package/dist/oms.js

@@ -4,9 +4,9 @@ import { existsSync, readFileSync, readdirSync, rmSync, rmdirSync, writeFileSync
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { Command } from "commander";
-import { cancel, isCancel, log, multiselect, select } from "@clack/prompts";
+import { cancel, isCancel, log, multiselect, select, text } from "@clack/prompts";
 import { parse as parseYaml } from "yaml";
-const ALIAS_PATTERN = /^[a-z0-9][a-z0-9-]*$/;
+const ALIAS_PATTERN = /^[a-z0-9][a-z0-9_@-]*$/;
 const REMOTE_NAME_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._/-]*$/;
 const ALLOWED_TOP_KEYS = new Set(["repos"]);
 const ALLOWED_ITEM_KEYS = new Set(["alias", "remotes", "branch"]);
@@ -138,6 +138,88 @@ async function selectInteractive(repos, actionLabel) {
         .map((alias) => repos.find((r) => r.alias === alias))
         .filter((r) => r !== undefined);
 }
+/**
+ * Resolve a single alias for a per-repo branch command (switch/checkout). An explicit alias is
+ * validated and must be a synced submodule; when omitted, the user picks one interactively from the
+ * synced submodules. Returns null (with a clear message) on an unknown/unsynced alias, an empty set,
+ * a non-interactive shell, or cancellation.
+ */
+async function resolveInitializedAlias(repos, repoRoot, alias, actionLabel) {
+    if (alias) {
+        const repo = repos.find((r) => r.alias === alias);
+        if (!repo) {
+            log.error(`Unknown alias "${alias}". Use "oms sync --list" to see registered aliases.`);
+            return null;
+        }
+        if (!submoduleInitialized(repoRoot, alias)) {
+            log.error(`${alias}: not synced. Run "oms sync ${alias}" first.`);
+            return null;
+        }
+        return repo;
+    }
+    const initialized = repos.filter((r) => submoduleInitialized(repoRoot, r.alias));
+    if (initialized.length === 0) {
+        log.error(`No synced submodules to ${actionLabel}. Run "oms sync" first.`);
+        return null;
+    }
+    if (!process.stdin.isTTY) {
+        log.error(`No alias given and stdin is not a TTY. Pass an alias: "oms ${actionLabel} <alias>".`);
+        return null;
+    }
+    const choice = await select({
+        message: `Select a source repo to ${actionLabel}`,
+        options: initialized.map((r) => ({
+            value: r.alias,
+            label: r.alias,
+            hint: r.branch ? `branch: ${r.branch}` : undefined,
+        })),
+    });
+    if (isCancel(choice)) {
+        cancel("Cancelled.");
+        return null;
+    }
+    return initialized.find((r) => r.alias === choice) ?? null;
+}
+/** Sentinel chosen in pickBranch to create a new branch instead of selecting an existing one. */
+const CREATE_NEW_BRANCH = "\0create-new-branch";
+/**
+ * Prompt for a branch from the given list. When allowCreate is set, a "create new branch" option
+ * collects a name via a text prompt. Returns null (with a clear message) on a non-interactive shell,
+ * an empty list with no create option, an empty name, or cancellation.
+ */
+async function pickBranch(branches, message, allowCreate) {
+    if (!process.stdin.isTTY) {
+        log.error(`No branch given and stdin is not a TTY. Pass a branch name explicitly.`);
+        return null;
+    }
+    if (branches.length === 0 && !allowCreate) {
+        log.error(`No branches available to select.`);
+        return null;
+    }
+    const options = [
+        ...(allowCreate ? [{ value: CREATE_NEW_BRANCH, label: "+ create new branch" }] : []),
+        ...branches.map((b) => ({ value: b, label: b })),
+    ];
+    const choice = await select({ message, options });
+    if (isCancel(choice)) {
+        cancel("Cancelled.");
+        return null;
+    }
+    if (choice === CREATE_NEW_BRANCH) {
+        const name = await text({ message: "New branch name", placeholder: "feature/login" });
+        if (isCancel(name)) {
+            cancel("Cancelled.");
+            return null;
+        }
+        const trimmed = name.trim();
+        if (!trimmed) {
+            log.error("Branch name is empty.");
+            return null;
+        }
+        return trimmed;
+    }
+    return choice;
+}
 /**
  * Decide which remote(s) a fetch/pull/push targets for one repo. Honors an explicit --remote list,
  * otherwise prompts interactively on a TTY (origin preselected) and falls back to origin off-TTY.
@@ -286,6 +368,25 @@ function localBranchExists(dir, branch) {
 function remoteBranchExists(dir, branch) {
     return runGit(dir, ["rev-parse", "--verify", "--quiet", `refs/remotes/origin/${branch}`]).success;
 }
+/** Local branch short names (refs/heads), e.g. ["main", "dev"]. Empty on failure or none. */
+function listLocalBranches(dir) {
+    const r = runGit(dir, ["for-each-ref", "--format=%(refname:short)", "refs/heads"]);
+    if (!r.success)
+        return [];
+    return r.stdout.split("\n").map((s) => s.trim()).filter((s) => s.length > 0);
+}
+/** Remote branch short names under origin, with the "origin/" prefix stripped and origin/HEAD excluded. */
+function listRemoteBranches(dir) {
+    const r = runGit(dir, ["for-each-ref", "--format=%(refname:short)", "refs/remotes/origin"]);
+    if (!r.success)
+        return [];
+    return r.stdout
+        .split("\n")
+        .map((s) => s.trim())
+        .filter((s) => s.length > 0 && s !== "origin/HEAD")
+        .map((s) => (s.startsWith("origin/") ? s.slice("origin/".length) : s))
+        .filter((s) => s !== "HEAD");
+}
 function isDirty(dir) {
     const r = runGit(dir, ["status", "--porcelain"]);
     return r.success && r.stdout.trim().length > 0;
@@ -591,7 +692,7 @@ function pullRepo(repo, repoRoot, remote) {
     }
     const branch = currentBranch(aliasDir(repoRoot, repo.alias));
     if (!branch) {
-        log.error(`${repo.alias}: detached HEAD. Run "oms checkout ${repo.alias} <branch>" before pulling.`);
+        log.error(`${repo.alias}: detached HEAD. Run "oms switch ${repo.alias} <branch>" before pulling.`);
         return "failed";
     }
     log.step(`${repo.alias}/${branch}: git pull --ff-only ${remote} ${branch}`);
@@ -611,7 +712,7 @@ function pushRepo(repo, repoRoot, remotes, commit) {
     }
     const branch = currentBranch(aliasDir(repoRoot, repo.alias));
     if (!branch) {
-        log.error(`${repo.alias}: detached HEAD. Run "oms checkout ${repo.alias} <branch>" before pushing.`);
+        log.error(`${repo.alias}: detached HEAD. Run "oms switch ${repo.alias} <branch>" before pushing.`);
         return "failed";
     }
     for (const remote of remotes) {
@@ -792,47 +893,87 @@ async function runUnsync(aliases, options) {
     }
     return exitFromResults(results);
 }
-async function runCheckout(alias, branch, options) {
+/**
+ * LOCAL branch management: switch the submodule to an existing local branch or create a new one.
+ * No remote is consulted — creating a brand-new branch needs no remote precondition and sets no
+ * upstream (that is checkout's job). Omitting alias and/or branch prompts for them interactively.
+ */
+async function runSwitch(alias, branch, options) {
     const loaded = loadForSubmodules();
     if (!loaded)
         return 1;
     const { repos, repoRoot } = loaded;
-    const repo = repos.find((r) => r.alias === alias);
-    if (!repo) {
-        log.error(`Unknown alias "${alias}". Use "oms sync --list" to see registered aliases.`);
+    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)) {
+        log.step(`${repo.alias}: git switch ${target}`);
+        const r = runSub(repoRoot, repo.alias, ["switch", target], true);
+        if (!r.success)
+            return 2;
+        log.success(`${repo.alias}: on ${target}`);
+        return 0;
     }
-    if (!submoduleInitialized(repoRoot, alias)) {
-        log.error(`${alias}: not synced. Run "oms sync ${alias}" first.`);
+    // Brand-new local branch: no remote precondition, no upstream tracking (use "oms checkout" for that).
+    const args = ["switch", "-c", target, ...(options.from ? [options.from] : [])];
+    log.step(`${repo.alias}: git ${args.join(" ")}`);
+    const r = runSub(repoRoot, repo.alias, args, true);
+    if (!r.success)
+        return 2;
+    log.success(`${repo.alias}: created new local branch ${target}. Push it with "oms push ${repo.alias}".`);
+    return 0;
+}
+/**
+ * REMOTE branch exploration: fetch origin, then check out a remote branch as a local tracking
+ * branch (or switch to an existing local counterpart). Omitting alias and/or branch prompts for
+ * them interactively. Creating brand-new local branches is "oms switch"'s job.
+ */
+async function runCheckout(alias, branch) {
+    const loaded = loadForSubmodules();
+    if (!loaded)
         return 1;
-    }
-    const dir = aliasDir(repoRoot, alias);
-    // Best-effort refresh so an existing remote branch is recognized; offline is fine.
-    runSub(repoRoot, alias, ["fetch", "origin", "--quiet"]);
-    if (localBranchExists(dir, branch)) {
-        log.step(`${alias}: git switch ${branch}`);
-        const r = runSub(repoRoot, alias, ["switch", branch], true);
+    const { repos, repoRoot } = loaded;
+    const repo = await resolveInitializedAlias(repos, repoRoot, alias, "checkout");
+    if (!repo)
+        return 1;
+    const dir = aliasDir(repoRoot, repo.alias);
+    log.step(`${repo.alias}: git fetch origin --prune`);
+    const fetch = runSub(repoRoot, repo.alias, ["fetch", "origin", "--prune"], true);
+    if (!fetch.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)) {
+        log.step(`${repo.alias}: git switch ${target}`);
+        const r = runSub(repoRoot, repo.alias, ["switch", target], true);
         if (!r.success)
             return 2;
-        log.success(`${alias}: on ${branch}`);
+        log.success(`${repo.alias}: on ${target}`);
         return 0;
     }
-    if (remoteBranchExists(dir, branch)) {
-        log.step(`${alias}: git switch -c ${branch} origin/${branch}`);
-        const r = runSub(repoRoot, alias, ["switch", "-c", branch, `origin/${branch}`], true);
+    if (remoteBranchExists(dir, target)) {
+        log.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;
-        log.success(`${alias}: on ${branch} (tracking origin/${branch})`);
+        log.success(`${repo.alias}: on ${target} (tracking origin/${target})`);
         return 0;
     }
-    // Brand-new branch: created locally, no remote precondition. Push later with "oms push".
-    const args = ["switch", "-c", branch, ...(options.from ? [options.from] : [])];
-    log.step(`${alias}: git ${args.join(" ")}`);
-    const r = runSub(repoRoot, alias, args, true);
-    if (!r.success)
-        return 2;
-    log.success(`${alias}: created new local branch ${branch}. Push it with "oms push ${alias}".`);
-    return 0;
+    log.error(`${repo.alias}: "${target}" not found on origin. To create a new local branch, run "oms switch ${repo.alias} ${target}".`);
+    return 1;
 }
 /** Parse the leading status char from `git submodule status` (' ' ok, '+' moved, '-' uninit, 'U' conflict). */
 function pinState(repoRoot, alias) {
@@ -978,7 +1119,7 @@ async function runDoctor() {
         const dir = aliasDir(repoRoot, repo.alias);
         const branch = currentBranch(dir);
         if (!branch) {
-            log.warn(`${repo.alias}: detached HEAD. Run "oms checkout ${repo.alias} <branch>" to get on a branch.`);
+            log.warn(`${repo.alias}: detached HEAD. Run "oms switch ${repo.alias} <branch>" to get on a branch.`);
             warnings++;
         }
         else {
@@ -1024,6 +1165,7 @@ const commandNames = new Set([
     "doctor",
     "sync",
     "status",
+    "switch",
     "checkout",
     "fetch",
     "pull",
@@ -1072,14 +1214,23 @@ program
     await exitWith(runStatus(aliases, options));
 });
 program
-    .command("checkout")
-    .description("Switch a submodule to <branch>, creating it locally if it does not exist yet (no remote required).")
-    .argument("<alias>", "registered source alias")
-    .argument("<branch>", "branch name (may include slashes)")
+    .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(runCheckout(alias, branch, options));
+    await exitWith(runSwitch(alias, branch, options));
+});
+program
+    .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));
 });
 const collectRemote = (value, acc) => [...acc, value];
 program

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oh-my-space",
-  "version": "0.7.1",
+  "version": "0.9.0",
   "description": "CLI for managing external source repositories declared in oms.yaml.",
   "license": "MIT",
   "homepage": "https://github.com/divlook/oh-my-space",