oh-my-space 1.1.0 → 1.2.0

package/README.md

@@ -2,25 +2,25 @@
 
 [![npm version](https://img.shields.io/npm/v/oh-my-space.svg)](https://www.npmjs.com/package/oh-my-space)
 
-`oh-my-space` (OMS) is a small CLI for managing multi-repository workspaces with Git submodules. Declare source repositories once, work in normal branches, and let the main project record the exact commit used from each repository.
+`oh-my-space` (OMS) manages multi-repository workspaces with Git submodules. Source repositories use normal branches. The main project records each source repository's exact commit.
 
 ## Who it helps
 
 Use OMS when you:
 
-- develop one product across several repositories and want them checked out side by side;
-- need reproducible workspaces where the main project records each source repository's exact commit;
-- want everyday branch, commit, pull, and push workflows without accidentally working in a detached checkout;
-- want source-commit changes to remain visible until you deliberately record them in the main project;
+- develop one product across several repositories and need adjacent checkouts.
+- need reproducible workspaces with exact source commits recorded in the main project.
+- need branch, commit, pull, and push workflows that avoid accidental detached checkouts.
+- need source-commit changes to remain visible until you record them in the main project.
 - use AI coding tools that need a clear boundary between the main project and source repositories.
 
-OMS keeps Git's reproducibility while automating routine submodule setup and bounded recovery. When a choice depends on your intent, it asks instead of changing repository state silently.
+OMS preserves Git's reproducibility and automates routine submodule setup and bounded recovery. OMS asks when a choice depends on your intent.
 
 ## Requirements
 
 - [Node.js](https://nodejs.org) `>=20.19.0`
 - Git `>=2.40`
-- A Git repository whose top-level directory contains `oms.yaml` before repositories are synchronized
+- A Git repository with `oms.yaml` at its top level before you synchronize repositories
 
 ## Install
 
@@ -52,25 +52,30 @@ repos:
     branch: main # optional; defaults to the remote's default branch
 ```
 
-Synchronize the workspace and inspect its state:
+Synchronize the workspace:
 
 ```bash
 oms sync --all
+```
+
+Inspect its state:
+
+```bash
 oms status
 ```
 
-The source repository is now available at `oms/api/`. Continue with [Getting started](https://github.com/divlook/oh-my-space/blob/main/docs/getting-started.md) to complete the first branch, commit, push, and recorded-commit workflow.
+The source repository is now available at `oms/api/`. Follow [Getting started](https://github.com/divlook/oh-my-space/blob/main/docs/getting-started.md) for your first branch, commit, push, and recorded-commit workflow.
 
 ## Documentation
 
-- [Getting started](https://github.com/divlook/oh-my-space/blob/main/docs/getting-started.md) — set up a workspace and complete the first source change from branch creation through recording the commit in the main project.
-- [How OMS works](https://github.com/divlook/oh-my-space/blob/main/docs/how-oms-works.md) — understand workspace layout, repository boundaries, recorded commits, synchronization, status, safety behavior, and recovery.
-- [Commands](https://github.com/divlook/oh-my-space/blob/main/docs/commands.md) — choose the right command and Git scope; use `oms <command> --help` for exact arguments, options, and exit behavior.
-- [Configure your workspace](https://github.com/divlook/oh-my-space/blob/main/docs/configure-your-workspace.md) — define repositories, remotes, and starting branches in `oms.yaml`.
-- [AI coding tools](https://github.com/divlook/oh-my-space/blob/main/docs/ai-coding-tools.md) — install agent instructions and workspace skills that preserve repository boundaries.
-- [Migration guides](https://github.com/divlook/oh-my-space/blob/main/docs/migrations/README.md) — follow version-specific upgrade instructions.
-- [Development](https://github.com/divlook/oh-my-space/blob/main/docs/development.md) — build, test, and contribute to OMS.
-- [Release channels](https://github.com/divlook/oh-my-space/blob/main/docs/release-channels.md) — install stable or beta releases and maintain npm release channels.
+- [Getting started](https://github.com/divlook/oh-my-space/blob/main/docs/getting-started.md): Read for workspace setup and your first source change.
+- [How OMS works](https://github.com/divlook/oh-my-space/blob/main/docs/how-oms-works.md): Read for layout, repository boundaries, recorded commits, managed trees, synchronization, status, safety, and recovery.
+- [Commands](https://github.com/divlook/oh-my-space/blob/main/docs/commands.md): Read to choose a command and Git scope. Use `oms <command> --help` for exact arguments, options, and exit behavior.
+- [Configure your workspace](https://github.com/divlook/oh-my-space/blob/main/docs/configure-your-workspace.md): Read to define repositories, remotes, and starting branches in `oms.yaml`.
+- [AI coding tools](https://github.com/divlook/oh-my-space/blob/main/docs/ai-coding-tools.md): Read to install agent instructions and workspace skills that preserve repository boundaries.
+- [Migration guides](https://github.com/divlook/oh-my-space/blob/main/docs/migrations/README.md): Read for version-specific upgrade instructions.
+- [Development](https://github.com/divlook/oh-my-space/blob/main/docs/development.md): Read to build, test, or contribute to OMS.
+- [Release channels](https://github.com/divlook/oh-my-space/blob/main/docs/release-channels.md): Read to install stable or beta releases or maintain npm release channels.
 
 ## License
 

package/dist/build-info.json

@@ -1 +1 @@
-{"commit":"6ccf47ab4baa1eec1c4b3e62103189b59f630c66","skills":{"oms-branch":{"version":"1.1.0","omsVersion":">=1.0.0-0"},"oms-pointer":{"version":"1.1.0","omsVersion":">=1.0.0-0"},"oms-workspace":{"version":"1.2.0","omsVersion":">=1.0.0-0"}}}
+{"commit":"b9240ff3a85fd5ffc004faf2f8fa3f1cfa096f5a","skills":{"oms-branch":{"version":"1.2.0","omsVersion":">=1.0.0-0"},"oms-pointer":{"version":"1.2.0","omsVersion":">=1.0.0-0"},"oms-workspace":{"version":"1.4.0","omsVersion":">=1.2.0-0"}}}

package/dist/oms.js

@@ -14539,10 +14539,10 @@ __name(isDirty, "isDirty");
 // scripts/lib/agent.ts
 var OMS_MARKER_START = "<!-- OMS START -->";
 var OMS_MARKER_END = "<!-- OMS END -->";
-var OMS_SCOPE_GUARDRAIL = `- Run \`oms status --json\` before Git work involving \`oms/\` to read root versus submodule state.
+var OMS_SCOPE_GUARDRAIL = `- Run \`oms status --json\` before Git work involving \`oms/\` to identify the main project and each source repository.
 - Treat each \`oms/<alias>/\` directory as a separate Git repository.
-- Use \`oms\` commands for scoped submodule workflows; do not guess root repository versus submodule Git scope.
-- Do not create root commits for existing submodule pointer updates unless the user explicitly runs \`oms record <alias>\`.`;
+- Use \`oms\` commands for workflows in \`oms/<alias>/\`.
+- Create main-project commits for existing pointer updates only when the user explicitly runs \`oms record <alias>\`.`;
 var OMS_INSTRUCTION_BLOCK = `${OMS_MARKER_START}
 ## OMS Workspace Rules
 
@@ -19343,6 +19343,113 @@ async function runDoctor(gitRunner = productionGitRunner) {
 }
 __name(runDoctor, "runDoctor");
 
+// scripts/lib/exec.ts
+import { spawn } from "node:child_process";
+import { realpathSync as realpathSync3 } from "node:fs";
+import { resolve as resolve7 } from "node:path";
+function targetFailure(repoRoot, alias) {
+  const registration = aliasRegistration(repoRoot, alias);
+  if (registration !== "initialized") return registration;
+  if (!submoduleInitialized(repoRoot, alias)) return "checkout is not initialized";
+  const cwd = aliasDir(repoRoot, alias);
+  const top = runGit(cwd, ["rev-parse", "--show-toplevel"]);
+  const actual = runGit(cwd, ["rev-parse", "--absolute-git-dir"]);
+  const expected = runGit(repoRoot, ["rev-parse", "--git-path", `modules/${submodulePath(alias)}`]);
+  try {
+    if (top.success && actual.success && expected.success && realpathSync3(top.stdout.trim()) === realpathSync3(cwd) && realpathSync3(actual.stdout.trim()) === realpathSync3(resolve7(repoRoot, expected.stdout.trim()))) return null;
+  } catch {
+  }
+  return "checkout does not belong to the declared canonical submodule";
+}
+__name(targetFailure, "targetFailure");
+function describe(result) {
+  switch (result.kind) {
+    case "exit":
+      return `exit ${result.code}`;
+    case "signal":
+      return `signal ${result.signal}`;
+    case "spawn":
+      return `spawn failure: ${result.reason}`;
+    case "target":
+      return `target failure: ${result.reason}`;
+    case "interrupted":
+      return "interrupted";
+    case "not-run":
+      return "not run (interrupted invocation)";
+  }
+}
+__name(describe, "describe");
+async function runExec(aliases, options, command) {
+  const [executable, ...args] = command;
+  if (!executable) {
+    R2.error("Usage: oms exec [aliases...] [--all] -- <command> [args...]");
+    return 1;
+  }
+  const loaded = loadForSubmodules();
+  if (!loaded) return 1;
+  const { repos, repoRoot } = loaded;
+  if (refuseInsideManagedTree(repoRoot)) return 1;
+  if (repos.length === 0) {
+    R2.error("No repositories declared in the workspace.");
+    return 1;
+  }
+  const picked = await selectRepos(repos, aliases, options, "exec");
+  if (!picked || picked.length === 0) return 1;
+  const results = [];
+  let interrupted = false;
+  let active2;
+  const interrupt = /* @__PURE__ */ __name(() => {
+    if (interrupted) return;
+    interrupted = true;
+    active2?.kill("SIGINT");
+  }, "interrupt");
+  process.on("SIGINT", interrupt);
+  try {
+    for (const repo of picked) {
+      let result;
+      if (interrupted) {
+        result = { kind: "not-run" };
+      } else {
+        const failure = targetFailure(repoRoot, repo.alias);
+        if (failure) {
+          result = { kind: "target", reason: `${failure}. State preserved; run "oms sync ${repo.alias}".` };
+        } else {
+          R2.step(`${repo.alias}: exec`);
+          result = await new Promise((complete) => {
+            let spawnError;
+            try {
+              active2 = spawn(executable, args, { cwd: aliasDir(repoRoot, repo.alias), shell: false, stdio: "inherit" });
+            } catch (error) {
+              complete({ kind: "spawn", reason: error instanceof Error ? error.message : String(error) });
+              return;
+            }
+            active2.once("error", (error) => {
+              spawnError = error;
+            });
+            active2.once("close", (code, signal) => {
+              active2 = void 0;
+              if (signal === "SIGINT") interrupted = true;
+              if (interrupted) complete({ kind: "interrupted" });
+              else if (spawnError) complete({ kind: "spawn", reason: spawnError.message });
+              else if (signal) complete({ kind: "signal", signal });
+              else complete({ kind: "exit", code: code ?? 1 });
+            });
+          });
+        }
+      }
+      results.push({ alias: repo.alias, result });
+      R2.info(`${repo.alias}: ${describe(result)}`);
+    }
+  } finally {
+    process.off("SIGINT", interrupt);
+  }
+  R2.step("Execution summary");
+  for (const { alias, result } of results) R2.info(`${alias}: ${describe(result)}`);
+  if (interrupted) return 130;
+  return results.every(({ result }) => result.kind === "exit" && result.code === 0) ? 0 : 2;
+}
+__name(runExec, "runExec");
+
 // scripts/lib/help.ts
 var exitHelp = "\nExit codes: 0 ok | 1 usage/config error | 2 one or more git operations failed.";
 var workspaceContextHelp = `
@@ -19411,6 +19518,38 @@ Examples:
   $ oms unsync api --no-commit # leave the removal topology unstaged
   $ oms unsync api --commit    # same as the default; accepted for compatibility
 `;
+var execHelp = `
+Scope: runs only in initialized canonical checkouts at oms/<alias>/, never managed trees.
+OMS performs no preparation: no initialization, registration, fetching, branch switching, pointer
+recording, or repair. Dirty files and detached HEAD are allowed. Unavailable targets fail individually
+with "oms sync <alias>" guidance; later eligible targets still run.
+
+The first -- separates OMS options from the executable and literal arguments. Child --help, --all,
+and additional -- arguments are passed unchanged. OMS does not interpret shell syntax; invoke an
+available shell explicitly when needed. A separator and non-empty executable are required.
+Explicit aliases run once in first-occurrence order; --all takes precedence and uses manifest order.
+Without a selection, OMS prompts only in an interactive terminal; otherwise name aliases or use --all.
+
+Children inherit your environment, permissions, stdin, stdout, and stderr. Output streams live under
+alias-labelled headers, with a final result for every alias. Stdin is consumed sequentially, not replayed
+for each child. Non-zero exits, non-SIGINT signals, spawn failures, and target failures do not stop later
+targets. Numeric child exit codes and failure reasons appear in results, not as the OMS exit code.
+
+Ctrl+C (SIGINT) interrupts the active child and stops later targets. OMS waits for that child to close,
+reports unstarted aliases as not run, and exits 130. A child ending with SIGINT also interrupts the
+invocation. OMS does not forcibly kill children that ignore SIGINT or contain intentionally detached
+descendants; such children can delay exit, and detached descendants may continue running.
+
+This runner is not a sandbox. User commands can change files, Git state, or remote services and access
+the network. OMS performs no additional network operations, implicit commit or push, or rollback.
+Completed effects and changes from failed or interrupted children are preserved.
+Examples:
+  $ oms exec api web -- npm test
+  $ oms exec --all -- node -e 'console.log(process.cwd())'
+  $ oms exec api -- sh -c 'npm test && npm run build'
+Exit codes: 0 all targets succeeded | 1 usage/workspace/selection error | 2 command or target failure
+            130 invocation interrupted
+`;
 var fetchHelp = `
 Preparation initializes existing registrations automatically. An unregistered alias is offered an explicit
 sync; accepting creates a root topology commit, then fetch continues. A multi-alias selection asks once;
@@ -19908,6 +20047,7 @@ __name(exitWith, "exitWith");
 var commandNames = /* @__PURE__ */ new Set([
   "init",
   "doctor",
+  "exec",
   "sync",
   "status",
   "commit",
@@ -19924,6 +20064,9 @@ var commandNames = /* @__PURE__ */ new Set([
   "help"
 ]);
 var collectRepeatable = /* @__PURE__ */ __name((value, acc) => [...acc, value], "collectRepeatable");
+var execSeparator = process.argv[2] === "exec" ? process.argv.indexOf("--", 3) : -1;
+var execCommand = execSeparator === -1 ? [] : process.argv.slice(execSeparator + 1);
+var cliArgs = execSeparator === -1 ? process.argv : process.argv.slice(0, execSeparator);
 var program2 = new Command();
 program2.name("oms").description(
   `Manage source repositories listed in ${MANIFEST_FILENAME} as git submodules under ${DATA_DIRNAME}/<alias>/.`
@@ -19936,6 +20079,9 @@ program2.command("doctor").description(
 ).addHelpText("after", `${workspaceContextHelp}${exitHelp}`).action(async () => {
   await exitWith(runDoctor());
 });
+program2.command("exec").description("Run a command sequentially in initialized canonical source checkouts without preparation.").usage("[aliases...] [--all] -- <command> [args...]").argument("[aliases...]", "repo aliases to execute in (omit for interactive multi-select)").option("--all", "select every declared source repo in manifest order").addHelpText("after", `${execHelp}${workspaceContextHelp}`).action(async (aliases, options) => {
+  await exitWith(runExec(aliases, options, execCommand));
+});
 program2.command("sync").description(
   `Register each repo as a submodule at ${DATA_DIRNAME}/<alias>/ (or initialize and refresh an existing one), checked out on its baseline branch.`
 ).argument("[aliases...]", "repo aliases to sync (omit for interactive multi-select)").option("--all", "sync every registered source repo").option("--list", "print registered repos").option("--commit", "accepted for compatibility; the root topology commit (chore(oms): add ...) is created by default").option("--no-commit", "leave the root topology changes unstaged instead of committing them").addHelpText("after", `${syncHelp}${workspaceContextHelp}${exitHelp}`).action(async (aliases, options) => {
@@ -20017,4 +20163,4 @@ if (requestedCommand && !requestedCommand.startsWith("-") && !commandNames.has(r
   console.error(`error: unknown command '${requestedCommand}'`);
   process.exit(1);
 }
-await program2.parseAsync();
+await program2.parseAsync(cliArgs);

package/package.json

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