arashi 1.25.0 → 1.26.1

package/README.md

@@ -114,9 +114,10 @@ Windows (PowerShell and Git Bash):
 
 Windows manual installation requires `arashi-windows-x64.exe`, `arashi`, `arashi.ps1`, `arashi.bat`, and `arashi-checksums.txt` from the same release. Verify all four payload files, rename the executable to `arashi.bin.exe`, and keep the payload together on PATH.
 
-You can also build from source for local development:
+You can also build from source for local development. Development is pinned to Node.js 24.18.0, which satisfies pnpm 11's Node.js 22.13 minimum, and pnpm 11.20.0; nvm users can select the repository's development runtime with `nvm use`.
 
 ```bash
+nvm use # Optional; reads .nvmrc
 pnpm install
 pnpm run build
 ```
@@ -136,7 +137,8 @@ Arashi currently provides these commands:
 - `arashi status`
 - `arashi remove <branch|path>`
 - `arashi prune [--dry-run]` - clean stale Git worktree metadata
-- `arashi switch [filter] [--repos|--all] [--tab] [--cd|--no-cd] [--tmux|--sesh|--herdr] [--no-default-launch]`
+- `arashi switch [filter] [--repos|--all] [--tab] [--cd|--launch] [--tmux|--sesh|--herdr] [--ignore-configured-launcher]`
+- `arashi completion <bash|zsh|fish>`
 - `arashi shell init <bash|zsh|fish>`
 - `arashi shell install`
 - `arashi pull`
@@ -164,10 +166,12 @@ arashi switch --repos feature-auth-refresh  # child repo worktrees in current wo
 arashi switch --all feature-auth-refresh    # all repos
 arashi switch --repos docs                  # repo-name matching in child repos
 arashi switch --cd feature-auth-refresh     # parent-shell cd when shell integration is active
+arashi switch --launch feature-auth-refresh # force launch while preserving a configured launcher
 arashi switch --tmux feature-auth-refresh   # force a new plain tmux window
 arashi switch --herdr feature-auth-refresh  # open or focus a persistent Herdr workspace
 arashi switch --tab feature-auth-refresh    # request a true tab or managed equivalent
-arashi switch --no-default-launch           # bypass configured sesh/Herdr mode once
+arashi switch --ignore-configured-launcher  # bypass configured sesh/Herdr mode once
+arashi switch --launch --ignore-configured-launcher # force generic automatic launch
 ```
 
 Explicit `--tmux` is a per-invocation launcher override for `create` and `switch`; it is not a persisted configuration mode. It requires an active tmux context whose `TMUX` value is non-empty after trimming, uses the selected worktree path as one argv-safe `tmux new-window -c` argument, and does not fall back to another launcher when the prerequisite or launch fails. On `create`, it implies both launch and switch, while validation failures occur before worktree mutation.
@@ -205,7 +209,7 @@ For contributors working on Arashi itself, the project planning workflow in the
 
 ## Shell Integration
 
-Use shell integration when you want `arashi switch` to change the current shell directory instead of only opening a new terminal or editor context.
+Use shell integration for parent-shell directory switching and native tab completion. Bash, Zsh, and Fish are supported.
 
 The official curl installer can offer this automatically. If you skip it or use npm, install it for the active shell with:
 
@@ -213,14 +217,28 @@ The official curl installer can offer this automatically. If you skip it or use
 arashi shell install
 ```
 
-Or print wrapper code for manual setup:
+`arashi shell install` adds a managed pair to the active shell startup file: the parent-shell wrapper first and completion activation second. Repeating the command is idempotent and upgrades older wrapper-only blocks.
+
+For manual setup, activate the wrapper and completion independently:
 
 ```bash
-arashi shell init bash
-arashi shell init zsh
-arashi shell init fish
+# Bash
+eval "$(command arashi shell init bash)"
+source <(command arashi completion bash)
+
+# Zsh
+eval "$(command arashi shell init zsh)"
+source <(command arashi completion zsh)
+
+# Fish
+command arashi shell init fish | source
+command arashi completion fish | source
 ```
 
+`arashi shell init <shell>` remains wrapper-only. `arashi completion <shell>` emits only deterministic sourceable shell code, including on npm first use when the platform binary must be installed.
+
+Completion covers commands, aliases, options, finite choices, conflicts, and positional boundaries. In an Arashi workspace it also resolves configured repository and group selector segments, switch/remove worktrees and paths, and move source/target references. Dynamic lookup is local and read-only, silent on unavailable or broken metadata, and limited to a 200 ms whole-query budget; it performs no network requests, hooks, prompts, workspace mutations, or child operations. Static completion remains available outside a workspace.
+
 Once installed, you can use `arashi switch --cd <filter>` for one-off parent-shell switching or set `.arashi/config.json` `defaults.switch.mode` to `"cd"` or contextual `"auto"`. The canonical modes are `auto` | `cd` | `launch` | `sesh` | `herdr`.
 
 If shell integration is inactive, `arashi switch --cd` warns and skips launch fallback for that invocation.
@@ -337,7 +355,7 @@ Example config header:
 
 `defaults.switch.mode` accepts `auto` | `cd` | `launch` | `sesh` | `herdr`. Contextual `auto` checks strict managed contexts in the order tmux → Herdr → cmux → integrated IDE → managed Kitty, then uses parent-shell `cd` when shell integration is active, and otherwise follows terminal/platform launch fallback. An absent mode preserves the built-in automatic `launch` behavior rather than newly preferring `cd`.
 
-Explicit launcher flags take precedence over `--cd` / `--no-cd`, which take precedence over the configured mode and automatic context detection. `--no-default-launch` bypasses only configured `sesh` or `herdr`. `--herdr` remains available on both `create` and `switch`; Herdr launch uses `herdr worktree open` with the Git-resolved non-bare main checkout and selected worktree.
+Explicit launcher flags take precedence over `--cd` / `--launch`, which take precedence over the configured mode and automatic context detection. `--launch` forces launch while preserving a configured launcher. `--ignore-configured-launcher` bypasses only configured `sesh` or `herdr`; combine both canonical flags to force generic automatic launch. `--herdr` remains available on both `create` and `switch`; Herdr launch uses `herdr worktree open` with the Git-resolved non-bare main checkout and selected worktree.
 
 Legacy switch-only `launchMode` and `launch_mode` fields remain readable for a bounded compatibility window. Arashi warns with the exact replacement `defaults.switch.mode` on stderr; migrate promptly. Ambiguous `cd` plus an explicit legacy launcher and conflicting legacy aliases are rejected.
 

package/bin/arashi.js

@@ -1,10 +1,11 @@
 #!/usr/bin/env node
 import { spawn } from "node:child_process";
-import { existsSync } from "node:fs";
-import { dirname, join } from "node:path";
-import { fileURLToPath, pathToFileURL } from "node:url";
+import { existsSync, realpathSync } from "node:fs";
+import { dirname, join, posix, win32 } from "node:path";
+import { fileURLToPath } from "node:url";
 import { formatInstallError, getPlatformInfo, installBinary } from "./install-binary.js";
 import { runNpmManagedUpdate } from "./update.js";
+import { stringifyWrapperJsonEnvelope } from "./update-options.js";
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -65,7 +66,10 @@ export async function ensureInstalled(options = {}) {
   const rootDir = options.rootDir ?? join(binDir, "..");
   const platform = options.platform ?? currentPlatform;
   const arch = options.arch ?? currentArch;
-  const log = options.log ?? console.log;
+  const sourceOutputFirstUse =
+    options.argv?.[0] === "completion" ||
+    (options.argv?.[0] === "shell" && options.argv?.[1] === "init");
+  const log = sourceOutputFirstUse ? () => {} : (options.log ?? console.log);
   const installBinaryImpl = options.installBinaryImpl ?? installBinary;
 
   if (hasRunnableBinary({ arch, binDir, existsSyncImpl: options.existsSyncImpl, platform })) {
@@ -84,12 +88,35 @@ export function isExplicitUpdateCommand(argv) {
   return argv[0] === "update";
 }
 
-async function runExplicitInstall(options) {
+async function runExplicitInstall(argv, options) {
   const binDir = options.binDir ?? __dirname;
   const rootDir = options.rootDir ?? join(binDir, "..");
   const installBinaryImpl = options.installBinaryImpl ?? installBinary;
+  const json = argv.includes("--json") || argv.includes("-j");
+  const log = options.log ?? console.log;
 
-  await installBinaryImpl({ ...options, binDir, rootDir });
+  try {
+    const result = await installBinaryImpl({
+      ...options,
+      binDir,
+      log: json ? () => {} : options.log,
+      rootDir,
+    });
+    if (json) log(stringifyWrapperJsonEnvelope("install", { data: result, ok: true }));
+    return 0;
+  } catch (error) {
+    if (!json) throw error;
+    log(
+      stringifyWrapperJsonEnvelope("install", {
+        error: {
+          code: "INSTALL_FAILED",
+          message: error instanceof Error ? error.message : String(error),
+        },
+        ok: false,
+      }),
+    );
+    return 1;
+  }
 }
 
 function spawnArashi(argv, options = {}) {
@@ -97,7 +124,7 @@ function spawnArashi(argv, options = {}) {
   const platform = options.platform ?? currentPlatform;
   const windows = platform === "win32";
   const spawnImpl = options.spawnImpl ?? spawn;
-  const wrapperPath = join(binDir, getWrapperName(platform));
+  const wrapperPath = (windows ? win32 : posix).join(binDir, getWrapperName(platform));
   const binaryPath = resolveBinaryPath({
     arch: options.arch,
     binDir,
@@ -108,10 +135,10 @@ function spawnArashi(argv, options = {}) {
   return new Promise((resolve) => {
     const child = windows
       ? spawnImpl(binaryPath, argv, {
-        stdio: "inherit",
-        windowsHide: false,
-      })
-      : spawnImpl(wrapperPath, argv, { stdio: "inherit" });
+          stdio: "inherit",
+          windowsHide: false,
+        })
+      : spawnImpl("/bin/bash", [wrapperPath, ...argv], { stdio: "inherit" });
 
     child.on("exit", (code, signal) => {
       if (typeof code === "number") {
@@ -135,15 +162,14 @@ export async function runEntrypoint(argv = process.argv.slice(2), options = {})
 
   try {
     if (isExplicitInstallCommand(argv)) {
-      await runExplicitInstall(options);
-      return 0;
+      return await runExplicitInstall(argv.slice(1), options);
     }
 
     if (isExplicitUpdateCommand(argv)) {
       return runNpmManagedUpdate(argv.slice(1), options);
     }
 
-    await ensureInstalled(options);
+    await ensureInstalled({ ...options, argv });
   } catch (error) {
     errorLog(formatInstallError(error));
     return 1;
@@ -152,7 +178,12 @@ export async function runEntrypoint(argv = process.argv.slice(2), options = {})
   return spawnArashi(argv, options);
 }
 
-const invokedPath = process.argv[1] ? pathToFileURL(process.argv[1]).href : "";
-if (import.meta.url === invokedPath) {
+let invokedDirectly = false;
+try {
+  invokedDirectly = Boolean(process.argv[1]) && realpathSync(process.argv[1]) === realpathSync(__filename);
+} catch {
+  // A missing or inaccessible argv path cannot be a direct invocation of this module.
+}
+if (invokedDirectly) {
   process.exitCode = await runEntrypoint();
 }

package/bin/update-options.js

@@ -0,0 +1,80 @@
+export const UPDATE_INSPECTION_CONFLICT_CODE = "UPDATE_INSPECTION_CONFLICT";
+export const UPDATE_INSPECTION_CONFLICT_MESSAGE =
+  "--check cannot be combined with --dry-run; choose one inspection mode.";
+export const UPDATE_UNKNOWN_OPTION_CODE = "UPDATE_UNKNOWN_OPTION";
+
+export class UpdateUnknownOptionError extends Error {
+  constructor(options) {
+    const suffix = options.length === 1 ? "" : "s";
+    super(`Unknown option${suffix}: ${options.join(", ")}`);
+    this.name = "UpdateUnknownOptionError";
+    this.code = UPDATE_UNKNOWN_OPTION_CODE;
+    this.details = { options };
+  }
+}
+
+export class UpdateInspectionConflictError extends Error {
+  constructor() {
+    super(UPDATE_INSPECTION_CONFLICT_MESSAGE);
+    this.name = "UpdateInspectionConflictError";
+    this.code = UPDATE_INSPECTION_CONFLICT_CODE;
+    this.details = { options: ["--check", "--dry-run"] };
+  }
+}
+
+export function parseUpdateArgs(argv = []) {
+  const delimiter = argv.indexOf("--");
+  const optionArgv = delimiter === -1 ? argv : argv.slice(0, delimiter);
+  const recognizedLongs = new Set(["--check", "--dry-run", "--json", "--yes"]);
+  const recognizedShorts = new Set(["j", "n", "y"]);
+  const groupedShorts = new Set();
+  const unknownOptions = [];
+  for (const token of optionArgv) {
+    if (recognizedLongs.has(token)) continue;
+    if (token.startsWith("--")) {
+      unknownOptions.push(token);
+      continue;
+    }
+    if (!/^-[^-]/.test(token)) continue;
+    const characters = token.slice(1).split("");
+    if (!characters.every((character) => recognizedShorts.has(character))) {
+      unknownOptions.push(token);
+      continue;
+    }
+    for (const character of characters) groupedShorts.add(character);
+  }
+  const has = (long, short) => optionArgv.includes(long) || optionArgv.includes(short) || groupedShorts.has(short.slice(1));
+  return {
+    check: optionArgv.includes("--check"),
+    dryRun: has("--dry-run", "-n"),
+    json: has("--json", "-j"),
+    unknownOptions,
+    yes: has("--yes", "-y"),
+  };
+}
+
+export function assertValidUpdateInspectionOptions(options) {
+  if (options.unknownOptions?.length > 0) {
+    throw new UpdateUnknownOptionError(options.unknownOptions);
+  }
+  if (options.check && options.dryRun) {
+    throw new UpdateInspectionConflictError();
+  }
+}
+
+export function createWrapperJsonEnvelope(command, result) {
+  if (result.ok) {
+    return { command, data: result.data ?? {}, ok: true, schemaVersion: 1, warnings: [] };
+  }
+  return {
+    command,
+    error: result.error,
+    ok: false,
+    schemaVersion: 1,
+    warnings: [],
+  };
+}
+
+export function stringifyWrapperJsonEnvelope(command, result) {
+  return JSON.stringify(createWrapperJsonEnvelope(command, result), null, 2);
+}

package/bin/update.js

@@ -5,16 +5,15 @@ import { createInterface } from "node:readline/promises";
 import { fileURLToPath } from "node:url";
 import { getPlatformInfo, installBinary, MANUAL_INSTALL_URL, PACKAGE_NAME } from "./install-binary.js";
 import { prepareSpawnCommand } from "./prepare-spawn-command.js";
+import {
+  assertValidUpdateInspectionOptions,
+  parseUpdateArgs,
+  stringifyWrapperJsonEnvelope,
+} from "./update-options.js";
 
 export const UPDATE_COMMAND_DESCRIPTION = "Check for and apply Arashi updates";
 
-export function parseUpdateArgs(argv = []) {
-  return {
-    check: argv.includes("--check"),
-    dryRun: argv.includes("--dry-run"),
-    yes: argv.includes("--yes") || argv.includes("-y"),
-  };
-}
+export { parseUpdateArgs } from "./update-options.js";
 
 function normalizeVersion(version) {
   return String(version ?? "").trim().replace(/^v/, "").split("+")[0];
@@ -247,7 +246,7 @@ function defaultRootDir(binDir) {
   return join(binDir ?? fileURLToPath(new URL(".", import.meta.url)), "..");
 }
 
-export async function runNpmManagedUpdate(argv = [], options = {}) {
+async function runNpmManagedUpdateCore(argv = [], options = {}) {
   const flags = parseUpdateArgs(argv);
   const log = options.log ?? console.log;
   const errorLog = options.error ?? console.error;
@@ -305,6 +304,11 @@ export async function runNpmManagedUpdate(argv = [], options = {}) {
     return 0;
   }
 
+  if (flags.json) {
+    log("JSON inspection: no changes made.");
+    return 0;
+  }
+
   if (!(await confirmUpdate({ promptImpl: options.promptImpl, yes: flags.yes }))) {
     errorLog("Update skipped. Rerun with --yes for non-interactive updates or use --dry-run to inspect the plan.");
     return 1;
@@ -384,12 +388,89 @@ export async function runNpmManagedUpdate(argv = [], options = {}) {
   }
 }
 
+export async function runNpmManagedUpdate(argv = [], options = {}) {
+  const flags = parseUpdateArgs(argv);
+  const log = options.log ?? console.log;
+  const errorLog = options.error ?? console.error;
+
+  try {
+    assertValidUpdateInspectionOptions(flags);
+  } catch (error) {
+    if (flags.json) {
+      log(
+        stringifyWrapperJsonEnvelope("update", {
+          error: { code: error.code, details: error.details, message: error.message },
+          ok: false,
+        }),
+      );
+    } else {
+      errorLog(error.message);
+    }
+    return 2;
+  }
+
+  if (flags.json && flags.yes) {
+    log(
+      stringifyWrapperJsonEnvelope("update", {
+        error: {
+          code: "JSON_UNSUPPORTED_FOR_MODE",
+          details: { mode: "installer-apply" },
+          message: "JSON output is not supported for installer-apply.",
+        },
+        ok: false,
+      }),
+    );
+    return 1;
+  }
+
+  if (!flags.json) return runNpmManagedUpdateCore(argv, options);
+
+  const messages = [];
+  const errors = [];
+  const exitCode = await runNpmManagedUpdateCore(argv, {
+    ...options,
+    error: (message) => errors.push(message),
+    log: (message) => messages.push(message),
+  });
+  if (exitCode === 0) {
+    log(stringifyWrapperJsonEnvelope("update", { data: { messages }, ok: true }));
+  } else {
+    log(
+      stringifyWrapperJsonEnvelope("update", {
+        error: {
+          code: "UPDATE_FAILED",
+          details: { messages },
+          message: errors.join("\n") || "Update failed.",
+        },
+        ok: false,
+      }),
+    );
+  }
+  return exitCode;
+}
+
 export async function runDirectBinaryUpdate(argv = [], options = {}) {
   const flags = parseUpdateArgs(argv);
   const log = options.log ?? console.log;
   const errorLog = options.error ?? console.error;
   const currentVersion = options.currentVersion;
 
+  try {
+    assertValidUpdateInspectionOptions(flags);
+  } catch (error) {
+    if (flags.json) {
+      log(
+        stringifyWrapperJsonEnvelope("update", {
+          error: { code: error.code, details: error.details, message: error.message },
+          ok: false,
+        }),
+      );
+    } else {
+      errorLog(error.message);
+    }
+    return 2;
+  }
+
   let release;
   try {
     release = options.latestRelease ?? (await fetchLatestGitHubRelease(options));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arashi",
-  "version": "1.25.0",
+  "version": "1.26.1",
   "description": "Git worktree manager for meta-repositories - The eye of the storm for your development workflow",
   "keywords": [
     "cli",
@@ -32,6 +32,7 @@
     "bin/install-binary.js",
     "bin/prepare-spawn-command.js",
     "bin/update.js",
+    "bin/update-options.js",
     "bin/arashi.bat",
     "bin/arashi.ps1",
     "schema/config.schema.json",
@@ -50,12 +51,13 @@
   "type": "module",
   "scripts": {
     "dev": "node src/index.ts",
-    "build": "bun build src/index.ts --compile --minify --outfile bin/arashi.bin",
-    "build:debug": "bun build src/index.ts --compile --sourcemap --outfile bin/arashi.bin",
-    "build:all": "pnpm run build:mac && pnpm run build:linux && pnpm run build:windows",
-    "build:mac": "bun build src/index.ts --compile --target=bun-darwin-arm64 --outfile bin/arashi-macos-arm64",
-    "build:linux": "bun build src/index.ts --compile --target=bun-linux-x64 --outfile bin/arashi-linux-x64",
-    "build:windows": "bun build src/index.ts --compile --target=bun-windows-x64 --outfile bin/arashi-windows-x64.exe",
+    "build": "pnpm run completion:check && bun build src/index.ts --compile --minify --outfile bin/arashi.bin",
+    "build:debug": "pnpm run completion:check && bun build src/index.ts --compile --sourcemap --outfile bin/arashi.bin",
+    "build:all": "pnpm run completion:check && pnpm run build:mac && pnpm run build:linux && pnpm run build:windows",
+    "buildAll": "pnpm run completion:check && pnpm run build:all",
+    "build:mac": "pnpm run completion:check && bun build src/index.ts --compile --target=bun-darwin-arm64 --outfile bin/arashi-macos-arm64",
+    "build:linux": "pnpm run completion:check && bun build src/index.ts --compile --target=bun-linux-x64 --outfile bin/arashi-linux-x64",
+    "build:windows": "pnpm run completion:check && bun build src/index.ts --compile --target=bun-windows-x64 --outfile bin/arashi-windows-x64.exe",
     "test": "node scripts/test/run-tests.ts",
     "typecheck": "tsc --noEmit",
     "lint": "oxlint -D no-explicit-any .",
@@ -66,10 +68,12 @@
     "schema:check": "pnpm run schema:publish && git diff --exit-code -- schema/config.schema.json",
     "contract:generate": "node scripts/contracts/cli-commands.ts",
     "contract:check": "node scripts/contracts/cli-commands.ts --check",
+    "completion:generate": "node scripts/completions.ts",
+    "completion:check": "node scripts/completions.ts --check",
     "format": "oxfmt --config .oxfmtrc.json --write .",
     "format:check": "oxfmt --config .oxfmtrc.json --check .",
     "quality:changed": "node scripts/quality/changed-files-quality.ts",
-    "prepublishOnly": "pnpm run schema:publish",
+    "prepublishOnly": "pnpm run completion:check && pnpm run schema:publish",
     "prepare": "husky"
   },
   "devDependencies": {
@@ -98,5 +102,5 @@
   "engines": {
     "node": ">=18.0.0"
   },
-  "packageManager": "pnpm@10.15.1"
+  "packageManager": "pnpm@11.20.0"
 }