@tenonhq/dovetail-core 0.0.124 → 0.0.126

package/README.md

@@ -26,13 +26,18 @@ Quick reference:
 ```bash
 npx dove watch         # HUMAN-ONLY local dev: multi-scope watch + dashboard (hidden from --help; stop before git checkout — see #155)
 npx dove push          # build + push current files
-npx dove refresh       # pull manifest + new files (aliases: pull, r)
+npx dove refresh       # pull manifest + new files, scope-wide (alias: r; bare `dove pull` does the same)
+npx dove pull <table> <sys_id>   # mirror ONE record: its folder + its manifest key, nothing else (--dry-run, --sys-ids, --from-update-set)
 npx dove build         # local build only
 npx dove deploy        # deploy built artifacts
 npx dove dashboard     # update-set dashboard web UI
 npx dove migrate       # migrate a Sincronia project to Dovetail (dry-run by default; --apply to write)
 ```
 
+`dove watch` refuses to start (exit 1) inside a Claude Code tool shell — any shell with `CLAUDECODE` set — because a branch switch mid-watch overwrites instance records. A human who really means to run it from such a shell (e.g. an IDE terminal that inherited the variable) can set `DOVE_ALLOW_WATCH_IN_CLAUDE=1`. Other `CLAUDE_CODE_*` variables only print a warning.
+
+The watcher also records the git `HEAD` when it starts and re-reads it before every push. If `HEAD` moved (a checkout, branch switch, reset or pull), it drops the queued changes, pushes nothing, logs an error and pauses syncing until you restart it on the branch you mean to sync. Outside a git work tree this check is off.
+
 See [`UPDATE_SET_COMMANDS.md`](UPDATE_SET_COMMANDS.md) for the full update-set CLI surface.
 
 ### `dove create sys_update_set`
@@ -41,7 +46,8 @@ See [`UPDATE_SET_COMMANDS.md`](UPDATE_SET_COMMANDS.md) for the full update-set C
 
 - `--scope` decides the application. It is **required** with `--ci`; interactively it is confirmed in the summary.
 - Only `name` and `description` map onto the op; other `--field` values are ignored with a warning.
-- The set is created, not activated — use `npx dove switchUpdateSet --name "<name>" -s <scope>` (or `npx dove createUpdateSet`, which creates and activates in one step).
+- An in-progress set with the same name already in that scope is refused (exit 1) rather than duplicated.
+- The set is created, not activated — the success line prints its sys_id; use `npx dove switchUpdateSet --sysId <sys_id> -s <scope>` (or `npx dove createUpdateSet`, which creates and activates in one step).
 
 ## Plugins
 

package/dist/MultiScopeWatcher.js

@@ -50,6 +50,7 @@ const path = __importStar(require("path"));
 const fs = __importStar(require("fs"));
 const ConfigManager = __importStar(require("./config"));
 const projectFiles_1 = require("./projectFiles");
+const gitHead_1 = require("./gitHead");
 const DEBOUNCE_MS = 300;
 class MultiScopeWatcherManager {
     scopeWatchers = new Map();
@@ -58,6 +59,12 @@ class MultiScopeWatcherManager {
     cachedScope = null;
     pendingScopes = new Map(); // scope -> first change timestamp
     globalProcessQueue = null;
+    // Branch-switch guard: the git HEAD the watcher started on. The watcher
+    // cannot tell a `git checkout` from real edits, so it re-reads HEAD before
+    // every push and halts if it moved. null = not a git work tree (guard off).
+    gitRootDir = null;
+    gitHeadAtStart = null;
+    syncHalted = false;
     async startWatchingAllScopes(options) {
         var opts = options || { monitorIntervalMs: 120000 };
         try {
@@ -68,6 +75,7 @@ class MultiScopeWatcherManager {
                 Logger_1.logger.error("No scopes defined in dove.config.js");
                 throw new Error("No scopes defined in configuration");
             }
+            await this.recordGitHeadAtStart();
             const scopes = Object.keys(config.scopes);
             Logger_1.logger.info(`Starting multi-scope watch for ${scopes.length} scopes: ${scopes.join(", ")}`);
             // Start watching each scope
@@ -122,6 +130,8 @@ class MultiScopeWatcherManager {
             }, DEBOUNCE_MS);
         }
         watcher.on("change", (filePath) => {
+            if (this.syncHalted)
+                return;
             Logger_1.logger.info(`[${scopeName}] File changed: ${path.relative(sourceDirectory, filePath)}`);
             scopeWatcher.pushQueue.push(filePath);
             if (!this.pendingScopes.has(scopeName)) {
@@ -130,6 +140,8 @@ class MultiScopeWatcherManager {
             this.globalProcessQueue();
         });
         watcher.on("add", (filePath) => {
+            if (this.syncHalted)
+                return;
             Logger_1.logger.info(`[${scopeName}] File added: ${path.relative(sourceDirectory, filePath)}`);
             scopeWatcher.pushQueue.push(filePath);
             if (!this.pendingScopes.has(scopeName)) {
@@ -346,6 +358,10 @@ class MultiScopeWatcherManager {
         }
     }
     async processAllPendingScopes() {
+        if (this.syncHalted) {
+            this.dropPendingChanges();
+            return;
+        }
         // Sort scopes by first file change timestamp (FIFO)
         var sorted = Array.from(this.pendingScopes.entries()).sort(function (a, b) {
             return a[1] - b[1];
@@ -355,10 +371,80 @@ class MultiScopeWatcherManager {
             var scopeName = sorted[i][0];
             var scopeWatcher = this.scopeWatchers.get(scopeName);
             if (scopeWatcher && scopeWatcher.pushQueue.length > 0) {
+                // Re-check right before every push: a checkout can land mid-flush.
+                if (!(await this.isGitHeadUnchanged())) {
+                    return;
+                }
                 await this.processScopeQueue(scopeWatcher);
             }
         }
     }
+    // Records the git HEAD of the project root so later flushes can detect a
+    // branch switch. Outside a git work tree the guard is off (today's behaviour).
+    async recordGitHeadAtStart() {
+        this.syncHalted = false;
+        this.gitRootDir = null;
+        this.gitHeadAtStart = null;
+        var rootDir = null;
+        try {
+            rootDir = ConfigManager.getRootDir();
+        }
+        catch (e) {
+            rootDir = null;
+        }
+        if (typeof rootDir !== "string" || rootDir === "") {
+            Logger_1.logger.debug("[MultiScope] No project root — branch-switch guard off");
+            return;
+        }
+        var head = await (0, gitHead_1.readGitHead)(rootDir);
+        if (!head) {
+            Logger_1.logger.debug("[MultiScope] Not a git work tree — branch-switch guard off");
+            return;
+        }
+        this.gitRootDir = rootDir;
+        this.gitHeadAtStart = head;
+        Logger_1.logger.debug("[MultiScope] Branch-switch guard armed at HEAD " + head);
+    }
+    // True when it is safe to push: no guard (not a git work tree) or HEAD is
+    // where it was at start. Otherwise halts syncing and returns false.
+    async isGitHeadUnchanged() {
+        if (this.syncHalted) {
+            this.dropPendingChanges();
+            return false;
+        }
+        if (!this.gitHeadAtStart || !this.gitRootDir) {
+            return true;
+        }
+        var current = await (0, gitHead_1.readGitHead)(this.gitRootDir);
+        if (current === this.gitHeadAtStart) {
+            return true;
+        }
+        this.haltForBranchChange(current);
+        return false;
+    }
+    dropPendingChanges() {
+        var dropped = 0;
+        this.scopeWatchers.forEach(function (scopeWatcher) {
+            dropped += scopeWatcher.pushQueue.length;
+            scopeWatcher.pushQueue = [];
+        });
+        this.pendingScopes.clear();
+        return dropped;
+    }
+    // HEAD moved (or can no longer be read): the queued "changes" are most
+    // likely the other branch's files, so pushing them would overwrite live
+    // records. Drop them and pause until the user restarts the watcher.
+    haltForBranchChange(currentHead) {
+        this.syncHalted = true;
+        var dropped = this.dropPendingChanges();
+        var from = this.gitHeadAtStart ? this.gitHeadAtStart.slice(0, 12) : "unknown";
+        var to = currentHead ? currentHead.slice(0, 12) : "unreadable";
+        Logger_1.logger.error("Git HEAD changed since the watcher started (" + from + " -> " + to + "). " +
+            "A branch switch or checkout rewrites the working tree, so pushing now would " +
+            "overwrite instance records with that tree. Dropped " + dropped +
+            " queued file(s); nothing was pushed. Syncing is PAUSED — stop the watcher " +
+            "(Ctrl+C) and restart it on the branch you mean to sync.");
+    }
     async processScopeQueue(scopeWatcher) {
         if (scopeWatcher.pushQueue.length === 0)
             return;
@@ -591,6 +677,9 @@ class MultiScopeWatcherManager {
             this.globalProcessQueue = null;
         }
         this.pendingScopes.clear();
+        this.syncHalted = false;
+        this.gitRootDir = null;
+        this.gitHeadAtStart = null;
         // Stop update set monitoring
         if (this.updateSetCheckInterval) {
             clearInterval(this.updateSetCheckInterval);

package/dist/allScopesCommands.js

@@ -373,9 +373,18 @@ async function initScopesCommand(args) {
 }
 async function watchAllScopesCommand(args) {
     (0, commands_1.setLogLevel)(args);
-    // Soft guard, not a hard fail: `watch` is a human-only local-dev tool and a
-    // branch switch mid-watch overwrites instance records. Warn an agent off it
-    // but leave the human path untouched. See TenonHQ/Dovetail#155.
+    // `watch` is a human-only local-dev tool and a branch switch mid-watch
+    // overwrites instance records. An agent's shell call blocks on (or
+    // backgrounds) the daemon, so a warning alone can't stop it: fail closed in
+    // a Claude Code tool shell (CLAUDECODE) unless a human sets the override.
+    // The broader CLAUDE_CODE_* signal also matches humans' config variables,
+    // so it only warns. See TenonHQ/Dovetail#155.
+    if ((0, claudeSession_1.isClaudeCodeToolShell)() && !(0, claudeSession_1.isWatchInClaudeAllowed)()) {
+        Logger_1.logger.error(claudeSession_1.WATCH_BLOCKED_IN_CLAUDE_ERROR);
+        FileLogger_1.fileLogger.warn("watch refused inside a Claude Code tool shell (TenonHQ/Dovetail#155)");
+        process.exit(1);
+        return;
+    }
     if ((0, claudeSession_1.isClaudeCodeSession)()) {
         Logger_1.logger.warn(claudeSession_1.WATCH_HUMAN_ONLY_WARNING);
         FileLogger_1.fileLogger.warn("dove watch started inside a Claude Code session (TenonHQ/Dovetail#155)");

package/dist/appUtils.js

@@ -36,7 +36,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.createAndAssignUpdateSet = exports.swapScope = exports.buildFiles = exports.summarizeRecord = exports.pushFiles = exports.getAppFileList = exports.groupAppFiles = exports.processMissingFiles = exports.refreshAllFiles = exports.findMissingFiles = exports.syncManifest = exports.narrowManifestToRecord = exports.narrowManifestToTables = exports.processManifest = exports.normalizeManifestKeys = exports.toSafeFolderName = exports.stampMetadataContent = exports.emptyMetadataFile = exports.EMPTY_METADATA_CONTENT = void 0;
+exports.createAndAssignUpdateSet = exports.swapScope = exports.buildFiles = exports.summarizeRecord = exports.pushFiles = exports.getAppFileList = exports.groupAppFiles = exports.processMissingFiles = exports.refreshAllFiles = exports.findMissingFiles = exports.syncManifest = exports.narrowManifestToRecord = exports.narrowManifestToTables = exports.processManifest = exports.normalizeManifestKeys = exports.duplicateFolderName = exports.toSafeFolderName = exports.stampMetadataContent = exports.emptyMetadataFile = exports.EMPTY_METADATA_CONTENT = void 0;
 const path_1 = __importDefault(require("path"));
 const progress_1 = __importDefault(require("progress"));
 const fUtils = __importStar(require("./FileUtils"));
@@ -294,6 +294,16 @@ const toSafeFolderName = (record) => {
     return isUnsafe ? record.sys_id : name;
 };
 exports.toSafeFolderName = toSafeFolderName;
+/**
+ * The key a record gets when its folder name is already taken by a different
+ * record in the same table: the display key plus the first 8 hex chars of its
+ * sys_id. Shared by every writer that resolves key collisions so a record keeps
+ * the same folder whichever path mirrored it.
+ */
+const duplicateFolderName = (key, sysId) => {
+    return key + " (" + String(sysId || "").substring(0, 8) + ")";
+};
+exports.duplicateFolderName = duplicateFolderName;
 /**
  * Re-keys manifest records from sys_id to a filesystem-safe folder name.
  * Some ServiceNow tables return records keyed by sys_id instead of display name.
@@ -316,7 +326,7 @@ const normalizeManifestKeys = (manifest) => {
             var displayKey = (0, exports.toSafeFolderName)(record);
             // Handle duplicate folder names by appending sys_id suffix
             if (normalized[displayKey]) {
-                displayKey = displayKey + " (" + record.sys_id.substring(0, 8) + ")";
+                displayKey = (0, exports.duplicateFolderName)(displayKey, record.sys_id);
             }
             // Keep record.name === manifest key so all writers (which build the folder
             // path from record.name) and push (which looks up by folder name) agree.

package/dist/claudeSession.js

@@ -5,14 +5,17 @@
  * `dove watch` auto-syncs the working tree to the instance, and a git branch
  * switch mid-watch pushes the post-switch file state over live records. An
  * agent can't guarantee it stops the watcher before every branch operation, so
- * the command is hidden from `--help` and warns when it detects it is running
- * inside a Claude Code session. See TenonHQ/Dovetail#155.
+ * the command is hidden from `--help`, refuses to start in a Claude Code tool
+ * shell (`CLAUDECODE`), and only warns on the broader `CLAUDE_CODE_*` signal.
+ * See TenonHQ/Dovetail#155.
  *
  * Pure functions — no I/O — so the detection is unit-testable without touching
  * `process.env` directly.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.WATCH_HUMAN_ONLY_WARNING = void 0;
+exports.WATCH_BLOCKED_IN_CLAUDE_ERROR = exports.WATCH_ALLOW_IN_CLAUDE_ENV = exports.WATCH_HUMAN_ONLY_WARNING = void 0;
+exports.isClaudeCodeToolShell = isClaudeCodeToolShell;
+exports.isWatchInClaudeAllowed = isWatchInClaudeAllowed;
 exports.isClaudeCodeSession = isClaudeCodeSession;
 // Claude Code exports `CLAUDECODE=1` into every tool shell, plus a family of
 // `CLAUDE_CODE_*` variables (e.g. `CLAUDE_CODE_SESSION_ID`, which claude-plans
@@ -20,13 +23,55 @@ exports.isClaudeCodeSession = isClaudeCodeSession;
 var CLAUDE_SESSION_FLAG = "CLAUDECODE";
 var CLAUDE_SESSION_PREFIX = "CLAUDE_CODE_";
 /**
- * @description Human-only warning printed when `dove watch` starts inside a
- * Claude Code session. Non-blocking by design (TenonHQ/Dovetail#155).
+ * @description Human-only warning printed when `dove watch` starts with a
+ * Claude Code signal that does not block it (a `CLAUDE_CODE_*` config
+ * variable, or `CLAUDECODE` with the human override). TenonHQ/Dovetail#155.
  */
 exports.WATCH_HUMAN_ONLY_WARNING = "⚠ `dove watch` is a human-only local-dev tool — it auto-syncs to the " +
     "instance and a branch switch mid-watch overwrites records. Don't run this " +
     "inside Claude Code. Use `npx dove push --diff <branch>` / `npx dove refresh` / " +
     "`npx dove status` instead. See TenonHQ/Dovetail#155.";
+/**
+ * @description Env var a human sets to `1` to run `dove watch` anyway from a
+ * shell that carries `CLAUDECODE` (e.g. an IDE terminal that inherited it).
+ */
+exports.WATCH_ALLOW_IN_CLAUDE_ENV = "DOVE_ALLOW_WATCH_IN_CLAUDE";
+/**
+ * @description Error printed when `dove watch` refuses to start inside a
+ * Claude Code tool shell. Names the human override.
+ */
+exports.WATCH_BLOCKED_IN_CLAUDE_ERROR = "`dove watch` refused: this is a Claude Code tool shell (CLAUDECODE is set). " +
+    "The watcher auto-syncs to the instance and a branch switch mid-watch " +
+    "overwrites records. Use `npx dove push --diff <branch>` / `npx dove refresh` / " +
+    "`npx dove status` instead. A human who really means to run it from this " +
+    "shell can set " +
+    exports.WATCH_ALLOW_IN_CLAUDE_ENV +
+    "=1. See TenonHQ/Dovetail#155.";
+/**
+ * @description Reports whether the environment is a Claude Code tool shell:
+ * `CLAUDECODE` set to a non-empty value. This is the hard-block signal — the
+ * broader `CLAUDE_CODE_*` prefix match also hits humans with config variables
+ * (e.g. `CLAUDE_CODE_USE_BEDROCK`) in their shell profile, so it only warns.
+ * @param {NodeJS.ProcessEnv} env - Environment to inspect (defaults to `process.env`).
+ * @returns {boolean} True when `CLAUDECODE` is set.
+ */
+function isClaudeCodeToolShell(env = process.env) {
+    if (!env || typeof env !== "object")
+        return false;
+    return hasValue(env[CLAUDE_SESSION_FLAG]);
+}
+/**
+ * @description True when the human override for running `dove watch` inside a
+ * Claude Code tool shell is set to exactly `1`.
+ * @param {NodeJS.ProcessEnv} env - Environment to inspect (defaults to `process.env`).
+ * @returns {boolean} Whether the override is active.
+ */
+function isWatchInClaudeAllowed(env = process.env) {
+    if (!env || typeof env !== "object")
+        return false;
+    var value = env[exports.WATCH_ALLOW_IN_CLAUDE_ENV];
+    return typeof value === "string" && value.trim() === "1";
+}
 /**
  * @description Reports whether the given environment looks like a Claude Code
  * session: `CLAUDECODE` is set, or any `CLAUDE_CODE_*` variable is set, to a

package/dist/commander.js

@@ -13,12 +13,38 @@ const schemaCommand_1 = require("./schemaCommand");
 const claudeCommand_1 = require("./claudeCommand");
 const createRecordCommand_1 = require("./createRecordCommand");
 const deleteRecordCommand_1 = require("./deleteRecordCommand");
+const pullRecordCommand_1 = require("./pullRecordCommand");
 const reconcileCommand_1 = require("./reconcileCommand");
 const migrateCommand_1 = require("./migrateCommand");
 const clickupCommands_1 = require("./clickupCommands");
 const loginCommand_1 = require("./loginCommand");
 const knowledgeDiffCommand_1 = require("./knowledgeDiffCommand");
 const yargs_1 = __importDefault(require("yargs"));
+/**
+ * @description A bare `dove pull` (no table, no --from-update-set) is a real,
+ * all-scope refresh, and refresh has no dry run. Per-record-only flags must
+ * never fall through to it: a forgotten table would otherwise overwrite local
+ * edits across every scope.
+ * @param {Record<string, unknown>} argv - Parsed `pull` arguments.
+ * @returns {string | undefined} The refusal message, or undefined when the invocation is fine.
+ */
+function barePullRefusal(argv) {
+    if (argv.table || argv.fromUpdateSet)
+        return undefined;
+    const hasValue = function (v) {
+        if (Array.isArray(v))
+            return v.some(hasValue);
+        if (typeof v === "string")
+            return v.trim() !== "";
+        return v !== undefined && v !== null && v !== false;
+    };
+    const dryRun = argv.dryRun === true;
+    if (!dryRun && !hasValue(argv.sysId) && !hasValue(argv.sysIds) && !hasValue(argv["sys-ids"]))
+        return undefined;
+    return ((dryRun ? "--dry-run" : "--sys-ids") +
+        " needs a table: a per-record pull is 'dove pull <table> <sys_id...>' (or --from-update-set <sys_id>). " +
+        "A bare 'dove pull' is a full refresh of every scope and has no dry run, so nothing was run.");
+}
 /**
  * @description Registers every `dove` command, the global options, and the
  * parser-strictness rules on a yargs instance. Split out from initCommands so
@@ -40,7 +66,7 @@ function configureCli(cli) {
         // the parser honest about what is actually accepted.
         alias: ["e", "env-file", "envFile"],
         type: "string",
-        describe: "Path to a .env file to load for this command (default: .env in the project root). Lets one checkout target multiple instances.",
+        describe: "Instance name or path of a .env file to load for this command (default: .env in the project root). A bare name like 'prod' loads .env.prod from the current directory. Lets one checkout target multiple instances.",
     })
         .global("env")
         .option("debug", {
@@ -87,10 +113,7 @@ function configureCli(cli) {
     }, async (args) => {
         await (0, allScopesCommands_1.watchAllScopesCommand)(args);
     })
-        .command(
-    // `pull` is the verb people reach for ("pull before push") and it appears
-    // in downstream docs and scripts — alias it rather than silently no-op.
-    ["refresh", "r", "pull"], "Pull latest manifest and file contents from the ServiceNow instance", (cmdArgs) => {
+        .command(["refresh", "r"], "Pull latest manifest and file contents from the ServiceNow instance (scope-wide; for one record see `dove pull <table> <sysId>`)", (cmdArgs) => {
         cmdArgs.options({
             ...sharedOptions,
             force: {
@@ -128,6 +151,87 @@ function configureCli(cli) {
         return cmdArgs;
     }, async (args) => {
         await (0, commands_1.refreshCommand)(args);
+    })
+        .command(
+    // Two commands in one verb, chosen by the positional:
+    //   dove pull                       → the historic alias of `dove refresh`
+    //                                     ("pull before push" is in dozens of
+    //                                     docs and scripts), scope-wide.
+    //   dove pull <table> <sysId...>    → per-record mirror (TenonHQ/Dovetail#319):
+    //                                     ONE record folder + ONE manifest entry,
+    //                                     every other entry byte-identical.
+    // The refresh-only flags (-t/--table, --metadata-only, --benchmark) are
+    // deliberately NOT declared here: -t would collide with the positional
+    // table, and strictCommands tolerates undeclared flags, so the handler
+    // turns a stray -t into an error instead of a silent no-op.
+    "pull [table] [sysId..]", "Mirror one or more records by sys_id into the repo without a scope refresh; with no table, same as `dove refresh`", (cmdArgs) => {
+        cmdArgs
+            .positional("table", {
+            type: "string",
+            describe: "ServiceNow table of the record(s), e.g. sys_security_acl",
+        })
+            // Singular on purpose: yargs camel-cases `--sys-ids` to `sysIds`, and a
+            // positional of the same name would swallow the flag.
+            .positional("sysId", {
+            type: "string",
+            describe: "One or more record sys_ids (space- or comma-separated)",
+        })
+            .options({
+            ...sharedOptions,
+            "sys-ids": {
+                type: "string",
+                describe: "Comma-separated sys_ids (alternative to the positional list)",
+            },
+            "from-update-set": {
+                type: "string",
+                describe: "Pull every per-record capture (<table>_<sys_id>) in this update set; schema/choice-set captures are reported and skipped",
+            },
+            scope: {
+                alias: "s",
+                type: "string",
+                describe: "Target scope. Per-record: every record must belong to it (a mismatch refuses the whole pull). Bare pull: refresh this scope only.",
+            },
+            force: {
+                alias: "f",
+                type: "boolean",
+                default: false,
+                describe: "Overwrite local files even when content matches the instance",
+            },
+            "dry-run": {
+                type: "boolean",
+                default: false,
+                describe: "Per-record only: list the files and manifest keys the pull would touch, write nothing",
+            },
+        })
+            .check(function (argv) {
+            const refusal = barePullRefusal(argv);
+            if (refusal !== undefined)
+                throw new Error(refusal);
+            return true;
+        });
+        return cmdArgs;
+    }, async (args) => {
+        const pullArgs = args;
+        if (barePullRefusal(args) !== undefined) {
+            // The builder's .check() has already reported it; never fall through
+            // to a real refresh even when the parser was told not to exit.
+            process.exitCode = 1;
+            return;
+        }
+        if (!pullArgs.table && !pullArgs.fromUpdateSet) {
+            // Bare pull == refresh. The refresh-only flags arrive undeclared
+            // (strictCommands tolerates them, yargs still camel-cases them), so
+            // they pass straight through; a bare `-t <table>` is re-mapped to
+            // refresh's --table so the old `dove pull -t x` spelling keeps working.
+            const refreshArgs = args;
+            const stray = pullArgs.t;
+            if (typeof stray === "string" || Array.isArray(stray)) {
+                refreshArgs.table = stray;
+            }
+            await (0, commands_1.refreshCommand)(refreshArgs);
+            return;
+        }
+        await (0, pullRecordCommand_1.pullRecordCommand)(pullArgs);
     })
         .command(["push [target]"], "[DESTRUCTIVE] Push all files from current local files to ServiceNow instance.", (cmdArgs) => {
         cmdArgs.options({
@@ -331,6 +435,10 @@ function configureCli(cli) {
                 type: "string",
                 describe: "Name or partial name of the update set to switch to",
             },
+            sysId: {
+                type: "string",
+                describe: "Exact sys_id of the update set to switch to (unambiguous when names repeat)",
+            },
             scope: {
                 alias: "s",
                 type: "string",

package/dist/createRecordCommand.js

@@ -302,6 +302,27 @@ async function createUpdateSetRecord(client, scope, fields) {
     if (typeof scopeSysId !== "string" || scopeSysId.trim() === "") {
         throw new Error('Scope "' + scope + '" resolved without a sys_id.');
     }
+    // Refuse a duplicate: a second in-progress set with the same name in the
+    // same scope (e.g. a retry after a timeout that had already succeeded) makes
+    // every later activate-by-name ambiguous.
+    var existingSets = await (0, snClient_1.unwrapSNResponse)(client.getInProgressUpdateSetsByName(name, scopeSysId));
+    if (Array.isArray(existingSets) && existingSets.length > 0) {
+        var existingIds = existingSets
+            .map(function (row) {
+            return row && typeof row.sys_id === "string" ? row.sys_id : "?";
+        })
+            .join(", ");
+        throw new Error('An in-progress update set named "' +
+            name +
+            '" already exists in scope ' +
+            scope +
+            " (" +
+            existingIds +
+            "). Refusing to create a duplicate — reuse it with " +
+            "npx dove switchUpdateSet --sysId <sys_id> -s " +
+            scope +
+            ", or pick a different name.");
+    }
     FileLogger_1.fileLogger.debug("createUpdateSet op:", JSON.stringify({ name: name, scope: scope, application: scopeSysId }));
     var created = await (0, snClient_1.unwrapSNResponse)(client.createUpdateSet(name, scopeSysId, description));
     var createdSysId = created && typeof created.sys_id === "string" ? created.sys_id : "";
@@ -468,8 +489,8 @@ async function createRecordCommand(args) {
                 " (" +
                 createdSet.scopeSysId +
                 ").");
-            Logger_1.logger.info("Not activated. To route pushes to it: npx dove switchUpdateSet --name " +
-                JSON.stringify(createdSet.name) +
+            Logger_1.logger.info("Not activated. To route pushes to it: npx dove switchUpdateSet --sysId " +
+                createdSet.sysId +
                 " -s " +
                 createdSet.scope);
             return;

package/dist/envArg.js

@@ -5,33 +5,47 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.parseEnvArg = parseEnvArg;
 exports.resolveEnvArgPath = resolveEnvArgPath;
+const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
 /**
  * Per-invocation .env selection for the `dove` CLI.
  *
- * Every command accepts `--env <path>` (alias `-e`, also `--env-file` /
+ * Every command accepts `--env <name|path>` (alias `-e`, also `--env-file` /
  * `--envFile`) so a single checkout can target multiple instances by pointing
  * at different credential files, e.g.:
  *
- *   npx dove push --env .env.prod
- *   npx dove status -e ../envs/workshop.env
+ *   npx dove push --env prod                 (bare name → <cwd>/.env.prod)
+ *   npx dove push --env .env.prod            (explicit filename)
+ *   npx dove status -e ../envs/workshop.env  (relative or absolute path)
+ *
+ * A bare instance name resolves exactly like `dove-sn --env <name>` and the
+ * MCP tools' per-call `env` (see resolveEnvArgPath for the full rules).
+ *
+ * Unlike `dove-sn`, a missing file is NOT an error here: `dove login --env`
+ * creates the file it is pointed at, so the selected path may not exist yet.
  *
  * The flag is parsed from raw argv before config/env load (see bootstrap.ts)
  * and also registered as a global yargs option so it appears in `--help`.
  */
 // Flag spellings that select an env file. `-e` is the short alias.
 var ENV_FLAGS = ["--env", "--env-file", "--envFile", "-e"];
+// Prefix a bare instance name is expanded with (`prod` → `.env.prod`).
+var BARE_NAME_PREFIX = ".env.";
 /**
- * @description Extracts the env-file path from a raw argv slice. Supports both
- * `--env <path>` and `--env=<path>` (and the `-e` / `--env-file` spellings).
- * Returns the last occurrence so a later flag overrides an earlier one.
+ * @description Extracts the env-file selector from a raw argv slice. Supports
+ * both `--env <value>` and `--env=<value>` (and the `-e` / `--env-file`
+ * spellings). Returns the last occurrence so a later flag overrides an earlier one.
  * @param {string[]} argv - Arguments after the node + script entries (process.argv.slice(2)).
- * @returns {string|undefined} The raw path string, or undefined when absent.
+ * @returns {string|undefined} The raw selector (bare name or path), or undefined when absent.
  */
 function parseEnvArg(argv) {
+    if (!Array.isArray(argv))
+        return undefined;
     var found;
     for (var i = 0; i < argv.length; i++) {
         var arg = argv[i];
+        if (typeof arg !== "string")
+            continue;
         // `--env=path` / `-e=path`
         var eq = arg.match(/^(--env|--env-file|--envFile|-e)=(.*)$/);
         if (eq) {
@@ -47,20 +61,55 @@ function parseEnvArg(argv) {
             }
         }
     }
-    if (found === undefined || found === "")
+    if (found === undefined || found.trim() === "")
         return undefined;
     return found;
 }
 /**
- * @description Resolves a raw env-file argument to an absolute path. Relative
- * paths resolve against the directory the command was run from (cwd), matching
- * where the user typed the path.
+ * @description Resolves a raw `--env` selector to an absolute env-file path.
+ * Mirrors `dove-sn`'s resolveEnvSelection (packages/servicenow/src/loadEnv.ts):
+ *   1. An absolute path, or any value containing a path separator, is a path;
+ *      relative paths resolve against cwd (unchanged legacy behavior).
+ *   2. A value that exists as a file in cwd (e.g. `my.env`) is that file.
+ *   3. A value starting with `.` or containing a `.` (e.g. `.env.prod`,
+ *      `workshop.env`) is an explicit filename in cwd, used as-is even when
+ *      it does not exist yet — `dove login --env` may be about to create it.
+ *   4. Anything else is a bare instance name: `prod` → `<cwd>/.env.prod`.
+ * Does not check existence; a missing file keeps dove's historical behavior
+ * (nothing is loaded from it).
  * @param {string} rawPath - The value returned by parseEnvArg.
- * @param {string} [cwd] - Base directory for relative paths (defaults to process.cwd()).
+ * @param {string} [cwd] - Base directory for relative paths and bare names (defaults to process.cwd()).
  * @returns {string} An absolute path to the requested .env file.
+ * @throws {Error} When rawPath is not a non-empty string.
  */
 function resolveEnvArgPath(rawPath, cwd) {
-    if (path_1.default.isAbsolute(rawPath))
-        return rawPath;
-    return path_1.default.resolve(cwd || process.cwd(), rawPath);
+    if (typeof rawPath !== "string" || rawPath.trim().length === 0) {
+        throw new Error("--env must be a non-empty env-file name or path.");
+    }
+    var value = rawPath.trim();
+    var base = typeof cwd === "string" && cwd.length > 0 ? cwd : process.cwd();
+    if (path_1.default.isAbsolute(value) || /[\\/]/.test(value)) {
+        return path_1.default.resolve(base, value);
+    }
+    var literal = path_1.default.resolve(base, value);
+    if (isExistingFile(literal)) {
+        return literal;
+    }
+    if (value.indexOf(".") !== -1) {
+        return literal;
+    }
+    return path_1.default.resolve(base, BARE_NAME_PREFIX + value);
+}
+/**
+ * @description True when the path exists and is a regular file. Never throws.
+ * @param {string} candidate - Absolute path to test.
+ * @returns {boolean}
+ */
+function isExistingFile(candidate) {
+    try {
+        return fs_1.default.statSync(candidate).isFile();
+    }
+    catch (e) {
+        return false;
+    }
 }