@ttctl/core 0.0.0 → 0.1.0-rc.2

package/dist/configLock.js

@@ -0,0 +1,109 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright (C) 2026 Oleksii PELYKH
+import lockfile from "proper-lockfile";
+import { ConfigError } from "./config.js";
+/**
+ * Wall-clock budget for `acquireConfigLock` contention timeout. The macOS /
+ * Linux baseline configuration produces ≤1.0s total wait: 5 retries × max
+ * 250ms backoff = 1250ms ceiling, but with `factor: 1` the backoff stays
+ * flat at `minTimeout`-`maxTimeout` so the practical envelope is closer to
+ * 5×100ms to 5×250ms = 500ms-1250ms with jitter. Tightens the upper bound
+ * below NFR-LOCK-1's 1.0s plan on the OSes the NFR was authored against.
+ * Windows operates on a 3x carve-out — see the Windows section below.
+ *
+ * Windows carve-out (#362): on Windows CI runners (Azure-hosted, shared,
+ * higher scheduler variance than Linux/macOS), the 1.0s envelope is too
+ * tight for the cross-process serialization test pair in
+ * `configLock-cross-process.test.ts` — both `staged race` and the 2-worker
+ * `serialize cleanly` variant have flaked when the second worker loses its
+ * scheduling slice long enough for its mkdir contention budget to expire
+ * before the first worker releases. Sibling prior art: #171, #180, #270
+ * (all Windows-specific timing fixes for the same `persistAuthToken`
+ * cross-process write path). Extending Windows to ~3.0s (15 retries × 100-
+ * 250ms = 1500-3750ms practical envelope) absorbs the variance without
+ * changing the NFR-LOCK-1 invariant on the OSes where it applies.
+ *
+ * Production impact: a real LOCKED contention surfaces in ~3s on Windows
+ * (vs ~1s elsewhere). The user-facing message already says "typically ≤2s"
+ * — the 3s ceiling does not contradict it, and contended writes are rare
+ * (CLI signin + concurrent MCP tool call on the same config).
+ */
+const WINDOWS_BUDGET_MULTIPLIER = process.platform === "win32" ? 3 : 1;
+const LOCK_RETRY_OPTIONS = {
+    retries: 5 * WINDOWS_BUDGET_MULTIPLIER,
+    factor: 1,
+    minTimeout: 100,
+    maxTimeout: 250,
+};
+/**
+ * Stale-lock threshold. If a lockfile is older than this without a refresh,
+ * `proper-lockfile` treats it as abandoned and overrides it. Defends against
+ * a crashed CLI/MCP that didn't release its lock on exit. The exit-handler
+ * via `signal-exit` is best-effort; the stale threshold is the second line.
+ *
+ * Set to 10s — long enough that a slow signin (network-bound ~2-5s) won't
+ * trip the threshold, short enough that a stranded lock from a SIGKILL'd
+ * process clears within a single user-perceptible retry window.
+ */
+const LOCK_STALE_MS = 10_000;
+/**
+ * Acquire an advisory exclusive lock for `configPath`.
+ *
+ * Implementation: `proper-lockfile` creates `<configPath>.lock` as a
+ * sibling DIRECTORY via atomic `mkdir(2)`. The `mkdir` syscall is atomic on
+ * ext4, APFS, NTFS, and any other filesystem with POSIX-equivalent
+ * semantics — `EEXIST` is the contention signal.
+ *
+ * Why sibling-lockfile and NOT self-lock: the atomic-rename pattern in
+ * `performYamlMutation` swaps the inode at `<configPath>` mid-operation. A
+ * `flock(fd)` on the original inode does NOT survive the rename and a
+ * concurrent locker on the post-rename inode sees no contention. The
+ * sibling pattern sidesteps this — the `.lock` directory's existence is the
+ * lock signal, independent of the config file's inode.
+ *
+ * Cross-platform: works identically on Linux/macOS/Windows — `mkdir`-based
+ * atomic creation is portable. No Windows no-op needed (in contrast to the
+ * existing POSIX-mode logic in `loadConfigFile` and `performYamlMutation`,
+ * which IS Windows-skipped because mode bits aren't meaningful).
+ *
+ * Contention: ≤1.0s wall-clock budget per `LOCK_RETRY_OPTIONS` on macOS /
+ * Linux, ≤3.0s on Windows (Windows scheduler-variance carve-out — see
+ * `LOCK_RETRY_OPTIONS` JSDoc + #362). On timeout, throws
+ * `ConfigError(LOCKED)` naming the path and suggesting retry — never blocks
+ * indefinitely.
+ *
+ * `realpath: false` skips proper-lockfile's pre-flight `realpath()` check.
+ * The caller has already resolved `configPath` to an absolute, symlink-free
+ * path via `assertSafePath`, AND the config file may not exist yet (e.g.,
+ * the lock is acquired BEFORE the stat baseline that throws ENOENT). With
+ * `realpath: true` (the library default), a missing file would surface as
+ * an opaque proper-lockfile error before our own ENOENT path runs.
+ */
+export async function acquireConfigLock(configPath) {
+    let release;
+    try {
+        release = await lockfile.lock(configPath, {
+            stale: LOCK_STALE_MS,
+            retries: LOCK_RETRY_OPTIONS,
+            realpath: false,
+        });
+    }
+    catch (err) {
+        // proper-lockfile throws an Error with a `code` property of "ELOCKED"
+        // when contention exhausts retries. Surface as ConfigError(LOCKED) so
+        // CLI/MCP error renderers can branch on the code rather than the
+        // library-specific marker.
+        const code = err.code;
+        if (code === "ELOCKED") {
+            throw new ConfigError(`Refusing to acquire config lock at ${configPath}.lock: another ttctl process holds it. ` +
+                `Wait for it to finish (CLI signin / MCP tool call typically ≤2s) and retry.`, "LOCKED", configPath);
+        }
+        // Any other error (EACCES on the parent dir, EROFS, etc.) — surface as
+        // PERMISSION so the caller can branch on it. Lock acquisition is
+        // mechanically a write to the parent directory, so permission errors
+        // are the natural failure mode.
+        throw new ConfigError(`Cannot acquire config lock at ${configPath}.lock: ${err.message}`, "PERMISSION", configPath);
+    }
+    return { release };
+}
+//# sourceMappingURL=configLock.js.map

package/dist/configLock.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"configLock.js","sourceRoot":"","sources":["../src/configLock.ts"],"names":[],"mappings":"AAAA,yCAAyC;AACzC,oCAAoC;AAEpC,OAAO,QAAQ,MAAM,iBAAiB,CAAC;AAEvC,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAoB1C;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,yBAAyB,GAAG,OAAO,CAAC,QAAQ,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAEvE,MAAM,kBAAkB,GAAG;IACzB,OAAO,EAAE,CAAC,GAAG,yBAAyB;IACtC,MAAM,EAAE,CAAC;IACT,UAAU,EAAE,GAAG;IACf,UAAU,EAAE,GAAG;CAChB,CAAC;AAEF;;;;;;;;;GASG;AACH,MAAM,aAAa,GAAG,MAAM,CAAC;AAE7B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CAAC,UAAkB;IACxD,IAAI,OAA4B,CAAC;IACjC,IAAI,CAAC;QACH,OAAO,GAAG,MAAM,QAAQ,CAAC,IAAI,CAAC,UAAU,EAAE;YACxC,KAAK,EAAE,aAAa;YACpB,OAAO,EAAE,kBAAkB;YAC3B,QAAQ,EAAE,KAAK;SAChB,CAAC,CAAC;IACL,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,sEAAsE;QACtE,sEAAsE;QACtE,iEAAiE;QACjE,2BAA2B;QAC3B,MAAM,IAAI,GAAI,GAA6B,CAAC,IAAI,CAAC;QACjD,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;YACvB,MAAM,IAAI,WAAW,CACnB,sCAAsC,UAAU,yCAAyC;gBACvF,6EAA6E,EAC/E,QAAQ,EACR,UAAU,CACX,CAAC;QACJ,CAAC;QACD,uEAAuE;QACvE,iEAAiE;QACjE,qEAAqE;QACrE,gCAAgC;QAChC,MAAM,IAAI,WAAW,CACnB,iCAAiC,UAAU,UAAW,GAAa,CAAC,OAAO,EAAE,EAC7E,YAAY,EACZ,UAAU,CACX,CAAC;IACJ,CAAC;IACD,OAAO,EAAE,OAAO,EAAE,CAAC;AACrB,CAAC"}

package/dist/configWriter.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Failure surface for `persistAuthToken` and `clearAuthToken`. Carries the
+ * YAML config path AND, for persist-failures-after-signin, the captured
+ * bearer token verbatim as a "rescue line" so the operator can manually
+ * write it to disk before re-running signin.
+ *
+ * The bearer is INTENTIONALLY in the message — without it, a write-back
+ * failure (read-only filesystem, full disk, kernel I/O error) silently
+ * loses the just-acquired session and forces a full re-signin. The cost of
+ * a bearer in stderr is bounded: the user sees it in their own terminal,
+ * the persist failure is rare, and the recovery is "save this manually".
+ */
+export declare class AuthTokenPersistError extends Error {
+    readonly configPath: string;
+    readonly cause?: NodeJS.ErrnoException | undefined;
+    readonly bearerRescue?: string | undefined;
+    readonly name = "AuthTokenPersistError";
+    constructor(message: string, configPath: string, cause?: NodeJS.ErrnoException | undefined, bearerRescue?: string | undefined);
+}
+/**
+ * Persist a captured bearer token to the SAME YAML config file the user
+ * authored. Surgically mutates `auth.token` via `yaml.parseDocument` +
+ * `setIn` to preserve comments, key order, and scalar styles. Atomic on
+ * POSIX (temp + rename + fsync).
+ *
+ * Path safety gates fire BEFORE the read: symlinks and sync-root paths are
+ * refused with `ConfigError(PERMISSION)` (not `AuthTokenPersistError`)
+ * because they reflect static filesystem state, not a transient I/O
+ * failure. Callers route both error classes through the same user-visible
+ * "signin couldn't persist the token" message.
+ *
+ * On any I/O failure after the bearer was captured, the error message
+ * carries the bearer verbatim as a "rescue line" — the operator can copy
+ * it into the config manually rather than redoing signin.
+ *
+ * Cross-process write-back is serialized by an advisory sibling lockfile
+ * (`<configPath>.lock`, atomic-mkdir-based via `proper-lockfile`). Two
+ * concurrent ttctl processes (e.g., CLI signin AND a long-running MCP
+ * tool call) cannot interleave their write-paths — one waits up to 1s and
+ * sees the other's committed file, then proceeds with its own
+ * read/parse/mutate/write cycle on the up-to-date contents. On contention
+ * timeout, throws `ConfigError(LOCKED)` — never blocks indefinitely.
+ *
+ * The mtime-drift check inside the locked region is the second line of
+ * defense for lock-disregarding writers (manual editor save during a
+ * persist window) — those still get caught and refused.
+ */
+export declare function persistAuthToken(configPath: string, token: string): Promise<void>;
+/**
+ * Remove the `auth.token` field from the YAML config file. Distinct from
+ * "set token to empty string" — `deleteIn` removes the field entirely so
+ * the next load sees Form A/B (credentials only) or Form C/Empty
+ * depending on what remains.
+ *
+ * Per security-architect's Stage 2 input: post-signout state must NEVER
+ * be `auth: { token: "" }` — empty-string is data and could be replayed
+ * as a (malformed) bearer. Removal is the only safe shape.
+ */
+export declare function clearAuthToken(configPath: string): Promise<void>;
+/**
+ * Write a freshly-authored config file to `configPath`.
+ *
+ * Sibling primitive to `performYamlMutation` for the bootstrap case
+ * (`ttctl auth init`): no pre-existing file is read or mutated — the YAML
+ * content is supplied verbatim by the caller from interactive prompts. The
+ * same atomic / safety invariants apply:
+ *
+ *   - Path safety gate (`assertSafePath`) — refuses sync-roots and
+ *     pre-existing symlinks at `configPath`. A non-existent path is
+ *     accepted (the whole point of init).
+ *   - Pre-existence gate — refuses unless `opts.force` is true. The
+ *     refusal is `ConfigError(PERMISSION)` so CLI/MCP error renderers
+ *     route it through the same exit-code + message contract as the
+ *     other write-path failures.
+ *   - Schema validation — the supplied content is parsed and validated
+ *     against `ConfigLoadSchema` BEFORE we touch disk. The strict load
+ *     schema catches malformed YAML composed by an interactive flow
+ *     (e.g. quoting bug) before we lock it in place.
+ *   - Atomic write — temp at `0o600`, fsync, defensive chmod, rename,
+ *     fsync(parent dir). Same dance as `persistAuthToken`'s temp path so
+ *     a crashed init never leaves a partial config.
+ *
+ * On `force` overwrite: the existing file is replaced atomically; the
+ * mtime-drift guard from `performYamlMutation` does NOT apply here because
+ * the bootstrap operation explicitly asks for replacement. Symlink and
+ * sync-root refusals still fire.
+ *
+ * Parent directories are created with `mkdir -p` semantics (the bootstrap
+ * is allowed to create its own `~/.ttctl.yaml` even if that means creating
+ * a fresh home — though in practice the parent is always `homedir()` which
+ * already exists; the recursive flag is for `--config <path>` cases that
+ * specify a not-yet-existing project dir).
+ */
+export declare function writeNewConfig(configPath: string, content: string, opts: {
+    force: boolean;
+}): Promise<void>;
+//# sourceMappingURL=configWriter.d.ts.map

package/dist/configWriter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"configWriter.d.ts","sourceRoot":"","sources":["../src/configWriter.ts"],"names":[],"mappings":"AA2GA;;;;;;;;;;;GAWG;AACH,qBAAa,qBAAsB,SAAQ,KAAK;aAI5B,UAAU,EAAE,MAAM;aAClB,KAAK,CAAC,EAAE,MAAM,CAAC,cAAc;aAC7B,YAAY,CAAC,EAAE,MAAM;IALvC,SAAkB,IAAI,2BAA2B;gBAE/C,OAAO,EAAE,MAAM,EACC,UAAU,EAAE,MAAM,EAClB,KAAK,CAAC,EAAE,MAAM,CAAC,cAAc,YAAA,EAC7B,YAAY,CAAC,EAAE,MAAM,YAAA;CAIxC;AAglBD;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAsB,gBAAgB,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAevF;AAED;;;;;;;;;GASG;AACH,wBAAsB,cAAc,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAOtE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAsB,cAAc,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE;IAAE,KAAK,EAAE,OAAO,CAAA;CAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAoEjH"}