oh-my-space 0.3.1 → 0.5.0

package/README.md

@@ -1,6 +1,6 @@
 # oh-my-space
 
-`oh-my-space` provides the `oms` CLI for managing external source repositories declared in `sources.yaml`. Each registered repo lives as a bare clone under `sources/<alias>/.bare/` and the baseline branch (and any additional ones you ask for) checks out as a Git worktree at `sources/<alias>/<branch>/`.
+`oh-my-space` provides the `oms` CLI for managing external source repositories declared in `oms.yaml`. Each registered repo lives as a bare clone under `oms/<alias>/.bare/` and the baseline branch (and any additional ones you ask for) checks out as a Git worktree at `oms/<alias>/<branch>/`.
 
 Package name: `oh-my-space`
 
@@ -32,9 +32,10 @@ bun install -g oh-my-space
 
 ## Quick start
 
-Create a `sources.yaml` in your project root:
+Run `oms init` to scaffold a starter `oms.yaml` (also adds `oms/` to `.gitignore`), or create one by hand in your project root:
 
 ```yaml
+# yaml-language-server: $schema=https://raw.githubusercontent.com/divlook/oh-my-space/main/oms.schema.json
 repos:
   - alias: api
     url: git@github.com:example/api.git
@@ -46,7 +47,8 @@ repos:
 Sync and explore:
 
 ```bash
-oms doctor                         # validate sources.yaml + bare/worktree state
+oms init                           # scaffold a starter oms.yaml
+oms doctor                         # validate oms.yaml + bare/worktree state
 oms sync --list                    # list registered source repos
 oms sync <alias>...                # bare-clone + create the baseline worktree
 oms sync --all                     # sync every registered source repo
@@ -57,14 +59,14 @@ oms worktree remove <alias> <br>   # remove a single worktree
 oms unsync <alias>...              # remove ALL worktrees + the bare clone
 ```
 
-`oms sync` adds `sources/` to your workspace `.gitignore` on first run; the bare clone and worktrees stay out of your project history.
+`oms sync` adds `oms/` to your workspace `.gitignore` on first run; the bare clone and worktrees stay out of your project history.
 
 ## Layout
 
 For an alias `api` with the baseline branch `main` and an extra `feature/foo` worktree:
 
 ```
-sources/
+oms/
 └── api/
     ├── .bare/             # git clone --bare result
     ├── .git               # 'gitdir: ./.bare' placeholder
@@ -77,13 +79,14 @@ Slash-containing branch names are kept nested as directories.
 
 ## Managing source repositories
 
-`sources.yaml` declares each source repo with `alias`, `url`, and optional `branch` (the baseline). Additional worktrees are created on demand with `oms worktree add` and are *not* persisted in `sources.yaml` — they're treated as per-machine working space.
+`oms.yaml` declares each source repo with `alias`, `url`, and optional `branch` (the baseline). Additional worktrees are created on demand with `oms worktree add` and are *not* persisted in `oms.yaml` — they're treated as per-machine working space.
 
 | Command | Runs in | Does | Notes |
 | --- | --- | --- | --- |
-| `oms doctor` | project root or child path | Checks `sources.yaml`, git availability, `.gitignore`, and each alias's bare clone + `remote.origin.fetch`. | Returns exit 2 if any warning is raised. |
-| `oms sync <alias>` / `--all` | workspace root | Bare-clones missing repos, fetches origin, creates the baseline worktree. | Adds `sources/` to `.gitignore` if absent. |
-| `oms unsync <alias>` / `--all` | workspace root | Removes every worktree, the bare clone, and the `.git` placeholder for the alias. | Keeps the `sources.yaml` entry. Use `--force` to discard uncommitted changes. |
+| `oms init` | current directory | Writes a starter `oms.yaml` and adds `oms/` to `.gitignore`. | Refuses if `oms.yaml` exists; use `--force` to overwrite. |
+| `oms doctor` | project root or child path | Checks `oms.yaml`, git availability, `.gitignore`, and each alias's bare clone + `remote.origin.fetch`. | Returns exit 2 if any warning is raised. |
+| `oms sync <alias>` / `--all` | workspace root | Bare-clones missing repos, fetches origin, creates the baseline worktree. | Adds `oms/` to `.gitignore` if absent. |
+| `oms unsync <alias>` / `--all` | workspace root | Removes every worktree, the bare clone, and the `.git` placeholder for the alias. | Keeps the `oms.yaml` entry. Use `--force` to discard uncommitted changes. |
 | `oms fetch ...` | workspace root | `git fetch origin --prune` on each bare clone. | Worktrees are not touched. |
 | `oms pull ...` | workspace root | `git pull --ff-only` on the baseline worktree of each selected alias. | Requires the worktree to be on its branch with upstream set (the default after `oms sync`). |
 | `oms push <alias>...` | workspace root | `git push` on the baseline worktree of each explicitly listed alias. | No `--all`, no force, no automatic upstream setup. |
@@ -91,9 +94,10 @@ Slash-containing branch names are kept nested as directories.
 | `oms worktree list [alias]` | anywhere under root | Lists every worktree for the alias (or all aliases). | |
 | `oms worktree remove <alias> <branch>` | workspace root | `git worktree remove <branch>` plus parent-directory cleanup for slash branches. | `--force` discards uncommitted changes. |
 
-## `sources.yaml` format
+## `oms.yaml` format
 
 ```yaml
+# yaml-language-server: $schema=https://raw.githubusercontent.com/divlook/oh-my-space/main/oms.schema.json
 repos:
   - alias: service-a
     url: git@github.com:example/service-a.git
@@ -109,28 +113,14 @@ Rules:
 - `url` is required.
 - `branch` is optional; when omitted the bare clone's default branch is used as the baseline worktree.
 
-## Migrating from 0.2.x
+JSON schema: [`oms.schema.json`](./oms.schema.json) (also reachable at `https://raw.githubusercontent.com/divlook/oh-my-space/main/oms.schema.json` for YAML LSPs).
 
-0.2.x stored each alias as a Git submodule. 0.3.0 replaces that with a bare clone + worktrees. The data model is breaking — `oms sync` refuses to run while `.gitmodules` still registers a `sources/<alias>` path. Convert your workspace manually:
+## Migrating between versions
 
-```bash
-# 1. For each alias in sources.yaml, deinit and remove the submodule.
-git submodule deinit -f sources/<alias>
-git rm -f sources/<alias>
-rm -rf .git/modules/<alias>
-
-# 2. Drop the now-empty .gitmodules if nothing else uses it.
-[ -s .gitmodules ] || rm -f .gitmodules
-
-# 3. Add sources/ to .gitignore (oms sync will also do this).
-grep -qxF 'sources/' .gitignore 2>/dev/null || echo 'sources/' >> .gitignore
+자세한 마이그레이션 절차는 [`docs/migrations/`](./docs/migrations/) 에 버전별로 정리되어 있습니다.
 
-# 4. Re-sync with the new model.
-oms sync --all
-
-# 5. Commit the result.
-git add . && git commit -m "chore: migrate to oh-my-space 0.3.0 (bare + worktree)"
-```
+- [0.3.x → 0.4.0](./docs/migrations/0.3.x-to-0.4.0.md) — `sources.yaml`/`sources/` 가 `oms.yaml`/`oms/` 로 rename
+- [0.2.x → 0.3.0](./docs/migrations/0.2.x-to-0.3.0.md) — submodule 에서 bare clone + worktree 로 데이터 모델 전환
 
 ## License
 

package/dist/oms.js

@@ -10,7 +10,14 @@ const ALIAS_PATTERN = /^[a-z0-9][a-z0-9-]*$/;
 const ALLOWED_TOP_KEYS = new Set(["repos"]);
 const ALLOWED_ITEM_KEYS = new Set(["alias", "url", "branch"]);
 const FETCH_REFSPEC = "+refs/heads/*:refs/remotes/origin/*";
-const GITIGNORE_ENTRY = "sources/";
+const MANIFEST_FILENAME = "oms.yaml";
+const DATA_DIRNAME = "oms";
+const GITIGNORE_ENTRY = `${DATA_DIRNAME}/`;
+const GITIGNORE_COMMENT = "# managed by oms";
+const LEGACY_MANIFEST = "sources.yaml";
+const LEGACY_DATA_DIRNAME = "sources";
+const LEGACY_MIGRATION_DOC = "docs/migrations/0.3.x-to-0.4.0.md";
+const SUBMODULE_MIGRATION_DOC = "docs/migrations/0.2.x-to-0.3.0.md";
 const MIN_GIT_MAJOR = 2;
 const MIN_GIT_MINOR = 40;
 const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
@@ -18,51 +25,51 @@ const useColor = process.stdout.isTTY;
 const dim = (s) => (useColor ? `\x1b[2m${s}\x1b[0m` : s);
 function validateSources(data) {
     if (!data || typeof data !== "object" || Array.isArray(data)) {
-        throw new Error("sources.yaml: root must be a mapping");
+        throw new Error(`${MANIFEST_FILENAME}: root must be a mapping`);
     }
     const obj = data;
     for (const key of Object.keys(obj)) {
         if (!ALLOWED_TOP_KEYS.has(key)) {
-            throw new Error(`sources.yaml: unknown top-level key "${key}"`);
+            throw new Error(`${MANIFEST_FILENAME}: unknown top-level key "${key}"`);
         }
     }
     const { repos } = obj;
     if (!Array.isArray(repos)) {
-        throw new Error('sources.yaml: "repos" must be an array');
+        throw new Error(`${MANIFEST_FILENAME}: "repos" must be an array`);
     }
     if (repos.length === 0) {
-        throw new Error('sources.yaml: "repos" must have at least one item');
+        throw new Error(`${MANIFEST_FILENAME}: "repos" must have at least one item`);
     }
     const validated = [];
     const seen = new Set();
     repos.forEach((item, idx) => {
         const where = `repos[${idx}]`;
         if (!item || typeof item !== "object" || Array.isArray(item)) {
-            throw new Error(`sources.yaml: ${where} must be a mapping`);
+            throw new Error(`${MANIFEST_FILENAME}: ${where} must be a mapping`);
         }
         const r = item;
         for (const key of Object.keys(r)) {
             if (!ALLOWED_ITEM_KEYS.has(key)) {
-                throw new Error(`sources.yaml: ${where} has unknown key "${key}"`);
+                throw new Error(`${MANIFEST_FILENAME}: ${where} has unknown key "${key}"`);
             }
         }
         if (typeof r.alias !== "string" || r.alias.length === 0) {
-            throw new Error(`sources.yaml: ${where} missing required "alias"`);
+            throw new Error(`${MANIFEST_FILENAME}: ${where} missing required "alias"`);
         }
         if (!ALIAS_PATTERN.test(r.alias)) {
-            throw new Error(`sources.yaml: ${where}.alias "${r.alias}" must match ${ALIAS_PATTERN}`);
+            throw new Error(`${MANIFEST_FILENAME}: ${where}.alias "${r.alias}" must match ${ALIAS_PATTERN}`);
         }
         if (seen.has(r.alias)) {
-            throw new Error(`sources.yaml: duplicate alias "${r.alias}"`);
+            throw new Error(`${MANIFEST_FILENAME}: duplicate alias "${r.alias}"`);
         }
         seen.add(r.alias);
         if (typeof r.url !== "string" || r.url.length === 0) {
-            throw new Error(`sources.yaml: ${where} missing required "url"`);
+            throw new Error(`${MANIFEST_FILENAME}: ${where} missing required "url"`);
         }
         let branch;
         if (r.branch !== undefined) {
             if (typeof r.branch !== "string" || r.branch.length === 0) {
-                throw new Error(`sources.yaml: ${where}.branch must be a non-empty string`);
+                throw new Error(`${MANIFEST_FILENAME}: ${where}.branch must be a non-empty string`);
             }
             branch = r.branch;
         }
@@ -111,7 +118,7 @@ function runGit(cwd, args, inheritOutput = false) {
         stdout: inheritOutput ? "" : (result.stdout ?? ""),
     };
 }
-/** Run git from sources/<alias>/ with safe.bareRepository=all, so the .git placeholder routes to .bare. */
+/** Run git from oms/<alias>/ with safe.bareRepository=all, so the .git placeholder routes to .bare. */
 function runBareGit(repoRoot, alias, args, inheritOutput = false) {
     return runGit(aliasDir(repoRoot, alias), ["-c", "safe.bareRepository=all", ...args], inheritOutput);
 }
@@ -131,7 +138,7 @@ function isGitVersionSupported(v) {
 function findWorkspaceRoot(options = {}) {
     let current = resolve(options.cwd ?? process.cwd());
     while (true) {
-        if (existsSync(join(current, "sources.yaml")))
+        if (existsSync(join(current, MANIFEST_FILENAME)))
             return current;
         const parent = dirname(current);
         if (parent === current)
@@ -140,7 +147,7 @@ function findWorkspaceRoot(options = {}) {
     }
 }
 function aliasDir(repoRoot, alias) {
-    return join(repoRoot, "sources", alias);
+    return join(repoRoot, DATA_DIRNAME, alias);
 }
 function bareDir(repoRoot, alias) {
     return join(aliasDir(repoRoot, alias), ".bare");
@@ -167,19 +174,68 @@ function isRegisteredSubmodule(repoRoot, sourcePath) {
         .split("\n")
         .some((line) => line.trim().split(/\s+/)[1] === sourcePath);
 }
-/** Returns true when .gitmodules registers any sources/<alias> entry for the loaded repos. */
+/** Returns true when .gitmodules registers any sources/<alias> or oms/<alias> entry for the loaded repos. */
 function hasLegacySubmoduleLayout(repoRoot, repos) {
     if (!existsSync(join(repoRoot, ".gitmodules")))
         return false;
-    return repos.some((repo) => isRegisteredSubmodule(repoRoot, `sources/${repo.alias}`));
+    return repos.some((repo) => isRegisteredSubmodule(repoRoot, `${LEGACY_DATA_DIRNAME}/${repo.alias}`)
+        || isRegisteredSubmodule(repoRoot, `${DATA_DIRNAME}/${repo.alias}`));
 }
 function abortOnLegacy(repoRoot, repos) {
     if (!hasLegacySubmoduleLayout(repoRoot, repos))
         return false;
-    log.error('detected legacy submodule layout (.gitmodules registers sources/<alias>). oh-my-space 0.3.0 uses bare clone + worktrees.\n' +
-        '  See README "Migrating from 0.2.x" for the manual steps. Aborting to avoid destructive change.');
+    log.error('detected legacy submodule layout (.gitmodules registers an alias path). oh-my-space 0.3.0+ uses bare clone + worktrees.\n' +
+        `  See ${SUBMODULE_MIGRATION_DOC} for the manual steps. Aborting to avoid destructive change.`);
     return true;
 }
+/** Inspect a single directory for 0.3.x rename artifacts. */
+function detectLegacyRenameArtifactsAt(dir) {
+    const manifest = existsSync(join(dir, LEGACY_MANIFEST));
+    const data = existsSync(join(dir, LEGACY_DATA_DIRNAME));
+    if (!manifest && !data)
+        return null;
+    return { manifest, data };
+}
+function emitLegacyRenameMessage(dir, found) {
+    const artifacts = [
+        found.manifest ? `'${LEGACY_MANIFEST}'` : null,
+        found.data ? `'${LEGACY_DATA_DIRNAME}/'` : null,
+    ]
+        .filter((s) => s !== null)
+        .join(" and ");
+    log.error(`detected legacy ${artifacts} at ${dir}.\n` +
+        `  oh-my-space 0.4.0 renamed the manifest to ${MANIFEST_FILENAME} and the data directory to ${DATA_DIRNAME}/.\n` +
+        `  See ${LEGACY_MIGRATION_DOC} for the manual steps. Aborting to avoid destructive change.`);
+}
+/** Block when the active oms.yaml workspace still has legacy artifacts at its root. */
+function abortOnLegacyRenameAt(repoRoot) {
+    const found = detectLegacyRenameArtifactsAt(repoRoot);
+    if (!found)
+        return false;
+    emitLegacyRenameMessage(repoRoot, found);
+    return true;
+}
+/**
+ * When oms.yaml could not be found, walk upward looking for a 0.3.x manifest (sources.yaml).
+ * Only the manifest is trusted as a positive signal — a stray sources/ directory by itself
+ * could belong to an unrelated tool. Returns true if a hint was emitted.
+ */
+function emitLegacyRenameHintWalkUp(options = {}) {
+    let current = resolve(options.cwd ?? process.cwd());
+    while (true) {
+        if (existsSync(join(current, LEGACY_MANIFEST))) {
+            emitLegacyRenameMessage(current, {
+                manifest: true,
+                data: existsSync(join(current, LEGACY_DATA_DIRNAME)),
+            });
+            return true;
+        }
+        const parent = dirname(current);
+        if (parent === current)
+            return false;
+        current = parent;
+    }
+}
 function ensureGitignore(repoRoot) {
     const path = join(repoRoot, ".gitignore");
     let content = "";
@@ -192,7 +248,8 @@ function ensureGitignore(repoRoot) {
             return;
     }
     const needsNewline = content.length > 0 && !content.endsWith("\n");
-    writeFileSync(path, `${content}${needsNewline ? "\n" : ""}${GITIGNORE_ENTRY}\n`);
+    const block = `${GITIGNORE_COMMENT}\n${GITIGNORE_ENTRY}\n`;
+    writeFileSync(path, `${content}${needsNewline ? "\n" : ""}${block}`);
     log.info(`added ${GITIGNORE_ENTRY} to .gitignore`);
 }
 function setupBareRepo(repo, repoRoot) {
@@ -210,7 +267,7 @@ function setupBareRepo(repo, repoRoot) {
         return false;
     }
     // Write the placeholder before any further runBareGit calls, otherwise git ascends
-    // out of sources/<alias>/ looking for a repo and touches the wrong .git.
+    // out of oms/<alias>/ looking for a repo and touches the wrong .git.
     writeFileSync(gitPlaceholderPath(repoRoot, alias), "gitdir: ./.bare\n");
     const config = runBareGit(repoRoot, alias, [
         "config",
@@ -265,7 +322,7 @@ function listExistingWorktrees(repoRoot, alias) {
         if (!path || bare)
             continue;
         const rel = relative(aliasPath, path);
-        // Skip worktrees outside sources/<alias>/ (shouldn't happen, but be safe)
+        // Skip worktrees outside oms/<alias>/ (shouldn't happen, but be safe)
         if (rel.startsWith(".."))
             continue;
         entries.push({ branch, path, relativePath: rel });
@@ -295,7 +352,7 @@ function cleanupEmptyParents(repoRoot, alias, branch) {
 function addWorktree(repo, repoRoot, branch) {
     const wtPath = worktreePath(repoRoot, repo.alias, branch);
     if (existsSync(wtPath)) {
-        log.warn(`${repo.alias}: sources/${repo.alias}/${branch} already exists; skipping.`);
+        log.warn(`${repo.alias}: ${DATA_DIRNAME}/${repo.alias}/${branch} already exists; skipping.`);
         return true;
     }
     log.step(`${repo.alias}: git worktree add --track -B ${branch} ${branch} origin/${branch}`);
@@ -331,7 +388,7 @@ function syncRepo(repo, repoRoot) {
         if (existsSync(aliasPath)) {
             const stray = readdirSync(aliasPath).filter((e) => e !== ".git");
             if (stray.length > 0) {
-                log.error(`${alias}: sources/${alias}/ already exists but is not a bare clone. Move or remove it manually, then retry.`);
+                log.error(`${alias}: ${DATA_DIRNAME}/${alias}/ already exists but is not a bare clone. Move or remove it manually, then retry.`);
                 return "failed";
             }
         }
@@ -365,7 +422,7 @@ function syncRepo(repo, repoRoot) {
         }
         const branch = repo.branch ?? detectDefaultBranch(repoRoot, alias);
         if (!branch) {
-            log.error(`${alias}: could not determine default branch from bare clone. Set "branch:" in sources.yaml.`);
+            log.error(`${alias}: could not determine default branch from bare clone. Set "branch:" in ${MANIFEST_FILENAME}.`);
             return "failed";
         }
         if (!addWorktree(repo, repoRoot, branch))
@@ -404,7 +461,7 @@ function unsyncRepo(repo, repoRoot, force) {
         for (const wt of worktrees) {
             const status = runGit(wt.path, ["status", "--porcelain"]);
             if (status.success && status.stdout.trim().length > 0) {
-                log.error(`${repo.alias}: worktree at sources/${repo.alias}/${wt.relativePath} has uncommitted changes. Commit, stash, or pass --force.`);
+                log.error(`${repo.alias}: worktree at ${DATA_DIRNAME}/${repo.alias}/${wt.relativePath} has uncommitted changes. Commit, stash, or pass --force.`);
                 return "failed";
             }
         }
@@ -528,12 +585,12 @@ function exitFromResults(results) {
 function loadRepos(options = {}) {
     const repoRoot = findWorkspaceRoot(options);
     if (!repoRoot) {
-        log.error("Could not find sources.yaml in the current directory or its parents. Create a sources.yaml in this project, then retry.");
+        log.error(`Could not find ${MANIFEST_FILENAME} in the current directory or its parents. Create a ${MANIFEST_FILENAME} in this project, then retry.`);
         return null;
     }
     try {
-        const sourcesPath = join(repoRoot, "sources.yaml");
-        return { repos: validateSources(parseYaml(readFileSync(sourcesPath, "utf8"))), repoRoot };
+        const manifestPath = join(repoRoot, MANIFEST_FILENAME);
+        return { repos: validateSources(parseYaml(readFileSync(manifestPath, "utf8"))), repoRoot };
     }
     catch (e) {
         log.error(e instanceof Error ? e.message : String(e));
@@ -565,9 +622,13 @@ async function selectRepos(repos, aliases, options, actionLabel) {
 }
 async function runSync(aliases, options) {
     const loaded = loadRepos();
-    if (!loaded)
+    if (!loaded) {
+        emitLegacyRenameHintWalkUp();
         return 1;
+    }
     const { repos, repoRoot } = loaded;
+    if (abortOnLegacyRenameAt(repoRoot))
+        return 1;
     if (options.list) {
         printList(repos);
         return 0;
@@ -585,9 +646,13 @@ async function runSync(aliases, options) {
 }
 async function runManage(command, aliases, options) {
     const loaded = loadRepos();
-    if (!loaded)
+    if (!loaded) {
+        emitLegacyRenameHintWalkUp();
         return 1;
+    }
     const { repos, repoRoot } = loaded;
+    if (abortOnLegacyRenameAt(repoRoot))
+        return 1;
     if (abortOnLegacy(repoRoot, repos))
         return 1;
     const picked = await selectRepos(repos, aliases, options, command);
@@ -601,9 +666,13 @@ async function runManage(command, aliases, options) {
 }
 async function runUnsync(aliases, options) {
     const loaded = loadRepos();
-    if (!loaded)
+    if (!loaded) {
+        emitLegacyRenameHintWalkUp();
         return 1;
+    }
     const { repos, repoRoot } = loaded;
+    if (abortOnLegacyRenameAt(repoRoot))
+        return 1;
     if (abortOnLegacy(repoRoot, repos))
         return 1;
     const picked = await selectRepos(repos, aliases, options, "unsync");
@@ -628,9 +697,13 @@ async function runUnsync(aliases, options) {
 }
 async function runWorktreeAdd(alias, branch) {
     const loaded = loadRepos();
-    if (!loaded)
+    if (!loaded) {
+        emitLegacyRenameHintWalkUp();
         return 1;
+    }
     const { repos, repoRoot } = loaded;
+    if (abortOnLegacyRenameAt(repoRoot))
+        return 1;
     if (abortOnLegacy(repoRoot, repos))
         return 1;
     const repo = repos.find((r) => r.alias === alias);
@@ -643,7 +716,7 @@ async function runWorktreeAdd(alias, branch) {
         return 1;
     }
     if (existsSync(worktreePath(repoRoot, alias, branch))) {
-        log.error(`${alias}: worktree for ${branch} already exists at sources/${alias}/${branch}.`);
+        log.error(`${alias}: worktree for ${branch} already exists at ${DATA_DIRNAME}/${alias}/${branch}.`);
         return 1;
     }
     log.step(`${alias}: git fetch origin --prune (refresh before add)`);
@@ -655,9 +728,13 @@ async function runWorktreeAdd(alias, branch) {
 }
 async function runWorktreeList(alias) {
     const loaded = loadRepos();
-    if (!loaded)
+    if (!loaded) {
+        emitLegacyRenameHintWalkUp();
         return 1;
+    }
     const { repos, repoRoot } = loaded;
+    if (abortOnLegacyRenameAt(repoRoot))
+        return 1;
     if (abortOnLegacy(repoRoot, repos))
         return 1;
     const targets = alias ? repos.filter((r) => r.alias === alias) : repos;
@@ -680,7 +757,7 @@ async function runWorktreeList(alias) {
             rows.push({
                 alias: repo.alias,
                 branch: wt.branch,
-                path: `sources/${repo.alias}/${wt.relativePath}`,
+                path: `${DATA_DIRNAME}/${repo.alias}/${wt.relativePath}`,
             });
         }
     }
@@ -694,9 +771,13 @@ async function runWorktreeList(alias) {
 }
 async function runWorktreeRemove(alias, branch, options) {
     const loaded = loadRepos();
-    if (!loaded)
+    if (!loaded) {
+        emitLegacyRenameHintWalkUp();
         return 1;
+    }
     const { repos, repoRoot } = loaded;
+    if (abortOnLegacyRenameAt(repoRoot))
+        return 1;
     if (abortOnLegacy(repoRoot, repos))
         return 1;
     const repo = repos.find((r) => r.alias === alias);
@@ -721,13 +802,36 @@ async function runWorktreeRemove(alias, branch, options) {
     log.success(`${alias}: removed worktree for ${branch}`);
     return 0;
 }
+const INIT_TEMPLATE = `# yaml-language-server: $schema=https://raw.githubusercontent.com/divlook/oh-my-space/main/oms.schema.json
+repos:
+  - alias: example
+    url: git@github.com:example/repo.git
+    branch: main
+`;
+/** 현재 디렉터리에 기본 oms.yaml 템플릿을 생성합니다. */
+async function runInit(options) {
+    const target = join(process.cwd(), MANIFEST_FILENAME);
+    if (existsSync(target) && !options.force) {
+        log.error(`${MANIFEST_FILENAME} already exists at ${target}. Use --force to overwrite.`);
+        return 1;
+    }
+    writeFileSync(target, INIT_TEMPLATE);
+    log.success(`created ${MANIFEST_FILENAME} at ${target}`);
+    ensureGitignore(process.cwd());
+    log.info(`edit alias/url/branch, then run "oms sync".`);
+    return 0;
+}
 async function runDoctor() {
     const loaded = loadRepos();
-    if (!loaded)
+    if (!loaded) {
+        emitLegacyRenameHintWalkUp();
         return 1;
+    }
     const { repos, repoRoot } = loaded;
+    if (abortOnLegacyRenameAt(repoRoot))
+        return 1;
     log.success(`Workspace root: ${repoRoot}`);
-    log.success(`sources.yaml: ${repos.length} repo(s) configured`);
+    log.success(`${MANIFEST_FILENAME}: ${repos.length} repo(s) configured`);
     const git = spawnSync("git", ["--version"], {
         encoding: "utf8",
         stdio: ["ignore", "pipe", "pipe"],
@@ -748,7 +852,7 @@ async function runDoctor() {
         warnings++;
     }
     if (hasLegacySubmoduleLayout(repoRoot, repos)) {
-        log.warn('detected legacy submodule layout (.gitmodules registers sources/<alias>). See README "Migrating from 0.2.x".');
+        log.warn(`detected legacy submodule layout (.gitmodules registers an alias path). See ${SUBMODULE_MIGRATION_DOC}.`);
         warnings++;
     }
     const gi = join(repoRoot, ".gitignore");
@@ -768,14 +872,14 @@ async function runDoctor() {
         }
         const refspec = runBareGit(repoRoot, repo.alias, ["config", "--get", "remote.origin.fetch"]);
         if (!refspec.success || refspec.stdout.trim().length === 0) {
-            log.warn(`${repo.alias}: bare clone is missing remote.origin.fetch. Run: git -C sources/${repo.alias}/.bare -c safe.bareRepository=all config remote.origin.fetch '${FETCH_REFSPEC}'`);
+            log.warn(`${repo.alias}: bare clone is missing remote.origin.fetch. Run: git -C ${DATA_DIRNAME}/${repo.alias}/.bare -c safe.bareRepository=all config remote.origin.fetch '${FETCH_REFSPEC}'`);
             warnings++;
         }
         else {
             log.success(`${repo.alias}: bare clone OK (refspec: ${refspec.stdout.trim()})`);
         }
         if (!existsSync(gitPlaceholderPath(repoRoot, repo.alias))) {
-            log.warn(`${repo.alias}: missing .git placeholder at sources/${repo.alias}/.git. Recreate with: echo 'gitdir: ./.bare' > sources/${repo.alias}/.git`);
+            log.warn(`${repo.alias}: missing .git placeholder at ${DATA_DIRNAME}/${repo.alias}/.git. Recreate with: echo 'gitdir: ./.bare' > ${DATA_DIRNAME}/${repo.alias}/.git`);
             warnings++;
         }
     }
@@ -801,6 +905,7 @@ async function exitWith(action) {
 }
 const exitHelp = "\nExit codes: 0 ok | 1 usage/config error | 2 one or more git operations failed.";
 const commandNames = new Set([
+    "init",
     "doctor",
     "sync",
     "fetch",
@@ -813,19 +918,27 @@ const commandNames = new Set([
 const program = new Command();
 program
     .name("oms")
-    .description("Manage source repositories listed in sources.yaml as bare clones + worktrees under sources/<alias>/.")
+    .description(`Manage source repositories listed in ${MANIFEST_FILENAME} as bare clones + worktrees under ${DATA_DIRNAME}/<alias>/.`)
     .version(readPackageVersion())
     .addHelpText("after", exitHelp);
+program
+    .command("init")
+    .description(`Create a starter ${MANIFEST_FILENAME} in the current directory.`)
+    .option("--force", `overwrite an existing ${MANIFEST_FILENAME}`)
+    .addHelpText("after", exitHelp)
+    .action(async (options) => {
+    await exitWith(runInit(options));
+});
 program
     .command("doctor")
-    .description("Check sources.yaml, git availability, bare-clone state, and .gitignore for each registered alias.")
+    .description(`Check ${MANIFEST_FILENAME}, git availability, bare-clone state, and .gitignore for each registered alias.`)
     .addHelpText("after", exitHelp)
     .action(async () => {
     await exitWith(runDoctor());
 });
 program
     .command("sync")
-    .description("Bare-clone each registered repo into sources/<alias>/.bare and create the baseline worktree at sources/<alias>/<branch>/.")
+    .description(`Bare-clone each registered repo into ${DATA_DIRNAME}/<alias>/.bare and create the baseline worktree at ${DATA_DIRNAME}/<alias>/<branch>/.`)
     .argument("[aliases...]", "repo aliases to sync (omit for interactive multi-select)")
     .option("--all", "sync every registered source repo")
     .option("--list", "print registered repos")
@@ -861,7 +974,7 @@ program
 });
 program
     .command("unsync")
-    .description("Remove all worktrees and the bare clone for each alias (keeps sources.yaml entry).")
+    .description(`Remove all worktrees and the bare clone for each alias (keeps ${MANIFEST_FILENAME} entry).`)
     .argument("[aliases...]", "repo aliases to unsync (omit for interactive multi-select)")
     .option("--all", "unsync every registered source repo")
     .option("--force", "discard uncommitted changes in worktrees")
@@ -875,7 +988,7 @@ const worktreeCmd = program
     .addHelpText("after", exitHelp);
 worktreeCmd
     .command("add")
-    .description("Create a worktree for <branch> at sources/<alias>/<branch>/.")
+    .description(`Create a worktree for <branch> at ${DATA_DIRNAME}/<alias>/<branch>/.`)
     .argument("<alias>", "registered source alias")
     .argument("<branch>", "branch name (may include slashes)")
     .addHelpText("after", exitHelp)
@@ -892,7 +1005,7 @@ worktreeCmd
 });
 worktreeCmd
     .command("remove")
-    .description("Remove the worktree at sources/<alias>/<branch>.")
+    .description(`Remove the worktree at ${DATA_DIRNAME}/<alias>/<branch>.`)
     .argument("<alias>", "registered source alias")
     .argument("<branch>", "branch name (may include slashes)")
     .option("--force", "discard uncommitted changes")

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "oh-my-space",
-  "version": "0.3.1",
-  "description": "CLI for managing external source repositories declared in sources.yaml.",
+  "version": "0.5.0",
+  "description": "CLI for managing external source repositories declared in oms.yaml.",
   "license": "MIT",
   "homepage": "https://github.com/divlook/oh-my-space",
   "repository": {
@@ -12,8 +12,8 @@
     "url": "https://github.com/divlook/oh-my-space/issues"
   },
   "keywords": [
-    "sources",
-    "submodule",
+    "oms",
+    "worktree",
     "git",
     "cli"
   ],