gitdog 0.1.0 → 0.1.2

package/README.md

@@ -10,36 +10,36 @@
 
 <p align="center">
   <a href="https://www.npmjs.com/package/gitdog"><img src="https://img.shields.io/npm/v/gitdog?logo=npm&amp;color=CB3837" alt="npm version"></a>
-  <a href="https://www.npmjs.com/package/gitdog"><img src="https://img.shields.io/npm/dm/gitdog?color=555" alt="npm downloads"></a>
   <a href="https://github.com/hyodotdev/gitdog-cli/actions/workflows/ci.yml"><img src="https://github.com/hyodotdev/gitdog-cli/actions/workflows/ci.yml/badge.svg?branch=main" alt="CI"></a>
+  <a href="https://github.com/hyodotdev/gitdog-cli/actions/workflows/release.yml"><img src="https://github.com/hyodotdev/gitdog-cli/actions/workflows/release.yml/badge.svg" alt="npm release"></a>
   <a href="https://nodejs.org"><img src="https://img.shields.io/badge/node-%3E%3D22.14.0-3c873a?logo=nodedotjs&amp;logoColor=white" alt="Node.js 22.14 or later"></a>
   <a href="https://gitdog.dev"><img src="https://img.shields.io/badge/Gitdog-gitdog.dev-111" alt="Gitdog website"></a>
 </p>
 
 <p align="center">
-  <img src="https://raw.githubusercontent.com/hyodotdev/gitdog-cli/main/.github/assets/terminal.svg" alt="Gitdog terminal: connect a project, configure automation and review pending actions" width="800">
+  <img src="https://raw.githubusercontent.com/hyodotdev/gitdog-cli/main/.github/assets/terminal.svg?v=0.1.2" alt="Gitdog terminal: connect a project, configure automation and review pending actions" width="800">
 </p>
 
 Connect repositories, configure Gitdog's issue and discussion assistants, review
 AI actions, and automate project tasks from your terminal or CI.
 
-## Install
+## Run with npx
 
-Requires **Node.js 22.14+**.
+Requires **Node.js 22.14+**. No global installation needed.
 
 ```sh
-npm install --global gitdog
+npx gitdog@latest --help
 ```
 
 ## Quick start
 
 ```sh
-gitdog login
-gitdog github install
-gitdog github recover
-gitdog init owner/repo
-gitdog config set requireApproval true
-gitdog config push
+npx gitdog@latest login
+npx gitdog@latest github install
+npx gitdog@latest github recover
+npx gitdog@latest init owner/repo
+npx gitdog@latest config set requireApproval true
+npx gitdog@latest config push
 ```
 
 GitHub App setup is only needed once. A project connects an existing GitHub
@@ -47,23 +47,23 @@ repository to Gitdog.
 
 ## Everyday commands
 
-| Task                     | Command                      |
-| ------------------------ | ---------------------------- |
-| List projects            | `gitdog projects list`       |
-| Read automation settings | `gitdog config get --remote` |
-| Review pending actions   | `gitdog tickets pending`     |
-| Check code indexing      | `gitdog index status`        |
-| List team members        | `gitdog team members`        |
-| Check usage              | `gitdog usage summary`       |
+| Task                     | Command                                 |
+| ------------------------ | --------------------------------------- |
+| List projects            | `npx gitdog@latest projects list`       |
+| Read automation settings | `npx gitdog@latest config get --remote` |
+| Review pending actions   | `npx gitdog@latest tickets pending`     |
+| Check code indexing      | `npx gitdog@latest index status`        |
+| List team members        | `npx gitdog@latest team members`        |
+| Check usage              | `npx gitdog@latest usage summary`       |
 
-Use `gitdog --help` to explore commands. Add `--json` for scripts.
+Use `npx gitdog@latest --help` to explore commands. Add `--json` for scripts.
 
 ## Use in CI
 
 ```sh
-gitdog keys create --name ci
-gitdog --key-file /path/to/key.json projects list --json
-gitdog keys revoke KEY_ID --yes
+npx gitdog@latest keys create --name ci
+npx --yes gitdog@0.1.2 --key-file /path/to/key.json projects list --json
+npx gitdog@latest keys revoke KEY_ID --yes
 ```
 
 `keys create` prints the private key file's path. Keys are project-scoped and

package/dist/api-keys.d.ts

@@ -11,5 +11,7 @@ export type ProjectKey = {
 };
 export declare function projectHttpUrl(apiUrl: string): string;
 export declare function readProjectKey(path: string): Promise<ProjectKey>;
+/** Refuse key paths that Git would track, so secrets are not committed. */
+export declare function assertUntrackedKeyPath(path: string): Promise<void>;
 export declare function saveProjectKey(path: string, key: ProjectKey): Promise<void>;
 export declare function callWithProjectKey<T>(apiUrl: string, keyFile: string | undefined, rawKey: string | undefined, kind: string, path: string, args: unknown, timeoutMs: number): Promise<T>;

package/dist/api-keys.js

@@ -1,7 +1,9 @@
-import { mkdir, open, readFile, rm } from "node:fs/promises";
-import { dirname, resolve } from "node:path";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { mkdir, open, readFile, realpath, rm } from "node:fs/promises";
+import { dirname, join, relative, resolve } from "node:path";
 import { asRecord } from "./ui.js";
-import { validateUrl } from "./storage.js";
+import { exists, validateUrl } from "./storage.js";
 export function projectHttpUrl(apiUrl) {
     return validateUrl(process.env.GITDOG_HTTP_URL ??
         apiUrl.replace(/\.convex\.cloud$/, ".convex.site"), "Project HTTP URL");
@@ -39,6 +41,48 @@ export async function readProjectKey(path) {
         expiresAt: key.expiresAt,
     };
 }
+/** Refuse key paths that Git would track, so secrets are not committed. */
+export async function assertUntrackedKeyPath(path) {
+    let directory = dirname(path);
+    while (!(await exists(directory))) {
+        const parent = dirname(directory);
+        if (parent === directory)
+            return;
+        directory = parent;
+    }
+    const canonicalDirectory = await realpath(directory);
+    const canonicalPath = join(canonicalDirectory, relative(directory, path));
+    try {
+        const { stdout } = await promisify(execFile)("git", ["rev-parse", "--is-inside-work-tree"], {
+            cwd: canonicalDirectory,
+            env: { ...process.env, LC_ALL: "C" },
+            timeout: 5000,
+        });
+        if (stdout.trim() === "false")
+            return;
+        if (stdout.trim() !== "true")
+            throw new Error("Unexpected Git work tree result");
+    }
+    catch (error) {
+        const gitError = error;
+        if (gitError.code === 128 &&
+            /fatal: not a git repository/i.test(gitError.stderr ?? ""))
+            return;
+        throw new Error("Could not verify the key path with Git. Fix Git configuration or choose the default private key location.");
+    }
+    try {
+        await promisify(execFile)("git", ["check-ignore", "-q", "--", canonicalPath], {
+            cwd: canonicalDirectory,
+            env: { ...process.env, LC_ALL: "C" },
+            timeout: 5000,
+        });
+    }
+    catch (error) {
+        if (error.code === 1)
+            throw new Error("The key file would be inside a Git repository and not ignored. Choose a path outside the repository or add it to .gitignore.");
+        throw new Error("Could not verify Git ignore rules for the key path. No key was issued.");
+    }
+}
 export async function saveProjectKey(path, key) {
     await mkdir(dirname(path), { recursive: true, mode: 0o700 });
     const handle = await open(path, "wx", 0o600);

package/dist/auth.js

@@ -112,7 +112,7 @@ export async function createLoginListener(timeoutMs = 300_000) {
         response.end("Gitdog received your sign-in. Return to your terminal to finish. You can close this tab.");
         finish(undefined, value);
     });
-    const timer = setTimeout(() => finish(new Error("Sign-in timed out. Run gitdog login to try again.")), timeoutMs);
+    const timer = setTimeout(() => finish(new Error("Sign-in timed out. Run npx gitdog@latest login to try again.")), timeoutMs);
     try {
         await new Promise((resolve, reject) => {
             server.once("error", reject);
@@ -195,11 +195,11 @@ export async function login(apiUrl, siteUrl, ui, noBrowser = false) {
         }
         catch {
             listener.signal.throwIfAborted();
-            throw new Error("Could not finish sign-in. Check that the CLI loopback callback is deployed, then run gitdog login again.");
+            throw new Error("Could not finish sign-in. Check that the CLI loopback callback is deployed, then run npx gitdog@latest login again.");
         }
         const tokens = asRecord(exchange)?.tokens;
         if (!validTokens(tokens))
-            throw new Error("Sign-in did not return a session. Run gitdog login again.");
+            throw new Error("Sign-in did not return a session. Run npx gitdog@latest login again.");
         client.setAuth(tokens.token);
         const user = asRecord(await invoke(client, "query", "users/query:getCurrentUser"));
         if (!user)
@@ -210,7 +210,7 @@ export async function login(apiUrl, siteUrl, ui, noBrowser = false) {
         ui.output(`✓ Signed in as ${String(user.name ?? "GitHub user")}.`);
         if (user.requiresCurrentLegalAttestation)
             ui.info(`Complete account consent at ${siteUrl}/legal/consent before running AI workflows.`);
-        ui.info("Next: gitdog init");
+        ui.info("Next: npx gitdog@latest init");
     }
     finally {
         await listener.close();

package/dist/catalog.js

@@ -3,6 +3,6 @@ export const API_CATALOG = catalog;
 export function publicOperation(path) {
     const operation = API_CATALOG.find((entry) => entry.path === path);
     if (!operation)
-        throw new Error("Unknown public operation. Run gitdog api list. Internal functions cannot be called.");
+        throw new Error("Unknown public operation. Run npx gitdog@latest api list. Internal functions cannot be called.");
     return operation;
 }

package/dist/client.js

@@ -60,15 +60,15 @@ export class GitdogApi {
         }
         const initial = await this.store.read();
         if (!initial)
-            throw new Error("You are not logged in. Run gitdog login.");
+            throw new Error("You are not logged in. Run npx gitdog@latest login.");
         if (initial.apiUrl !== this.apiUrl)
-            throw new Error("This session belongs to another API URL. Run gitdog login --api-url <url> first.");
+            throw new Error("This session belongs to another API URL. Run npx gitdog@latest login --api-url <url> first.");
         this.session = initial;
         if (tokenExpiresSoon(initial.token)) {
             this.session = await this.store.locked(async () => {
                 const current = await this.store.read();
                 if (!current || current.apiUrl !== this.apiUrl)
-                    throw new Error("Session changed. Run gitdog login again.");
+                    throw new Error("Session changed. Run npx gitdog@latest login again.");
                 if (!tokenExpiresSoon(current.token))
                     return current;
                 let result;
@@ -78,11 +78,11 @@ export class GitdogApi {
                     });
                 }
                 catch {
-                    throw new Error("Could not refresh your session. Check your connection or run gitdog login again.");
+                    throw new Error("Could not refresh your session. Check your connection or run npx gitdog@latest login again.");
                 }
                 const tokens = asRecord(result)?.tokens;
                 if (!validTokens(tokens))
-                    throw new Error("Your session expired. Run gitdog login again.");
+                    throw new Error("Your session expired. Run npx gitdog@latest login again.");
                 const updated = { ...current, ...tokens };
                 await this.store.save(updated);
                 return updated;

package/dist/commands.js

@@ -7,7 +7,7 @@ import { login, logout, openBrowser } from "./auth.js";
 import { API_CATALOG, publicOperation } from "./catalog.js";
 import { BOOLEAN_SETTINGS, STYLE_SETTINGS, ProjectContext, limitParser, } from "./projects.js";
 import { DEFAULT_API_URL, DEFAULT_SITE_URL, SessionStore, validateUrl, configDirectory, exists, } from "./storage.js";
-import { readProjectKey, saveProjectKey, projectHttpUrl } from "./api-keys.js";
+import { assertUntrackedKeyPath, readProjectKey, saveProjectKey, projectHttpUrl, } from "./api-keys.js";
 import { Ui, VERSION, asRecord, integer } from "./ui.js";
 const text = (value) => typeof value === "string" ? value : undefined;
 const number = (value) => typeof value === "number" ? value : undefined;
@@ -44,7 +44,7 @@ export function createProgram(dependencies = {}) {
         .option("-y, --yes", "Confirm the requested operation without prompting")
         .showHelpAfterError()
         .showSuggestionAfterError()
-        .addHelpText("after", `\nGetting started:\n  gitdog login\n  gitdog init\n  gitdog config set requireApproval true\n  gitdog config push --dry-run\n  gitdog config push\n\nFirebase-style aliases also work: projects:list, projects:create, config:push.\nRun gitdog <command> --help for details.`);
+        .addHelpText("after", `\nGetting started:\n  npx gitdog@latest login\n  npx gitdog@latest init\n  npx gitdog@latest config set requireApproval true\n  npx gitdog@latest config push --dry-run\n  npx gitdog@latest config push\n\nFirebase-style aliases also work: projects:list, projects:create, config:push.\nRun npx gitdog@latest <command> --help for details.`);
     async function context(command) {
         const options = command.optsWithGlobals();
         const ui = dependencies.ui ?? new Ui(flag(options.json));
@@ -104,10 +104,14 @@ export function createProgram(dependencies = {}) {
             ui.output({
                 name: "gitdog",
                 version: VERSION,
-                next: ["gitdog login", "gitdog init", "gitdog --help"],
+                next: [
+                    "npx gitdog@latest login",
+                    "npx gitdog@latest init",
+                    "npx gitdog@latest --help",
+                ],
             });
         else
-            ui.output("Get started\n  1. gitdog login       Sign in with GitHub\n  2. gitdog init        Connect a project\n  3. gitdog status      Check your assistant\n\nRun gitdog --help to explore all commands.");
+            ui.output("Get started\n  1. npx gitdog@latest login       Sign in with GitHub\n  2. npx gitdog@latest init        Connect a project\n  3. npx gitdog@latest status      Check your assistant\n\nRun npx gitdog@latest --help to explore all commands.");
     });
     command(program, "login", "Sign in with GitHub using your browser", async ({ apiUrl, siteUrl, ui }, _args, opts) => login(apiUrl, siteUrl, ui, opts.browser === false)).option("--no-browser", "Print the sign-in URL without opening a browser");
     command(program, "logout", "Revoke this session and remove saved credentials", async ({ ui }, _args, opts) => logout(ui, flag(opts.local))).option("--local", "Remove local credentials without contacting the server");
@@ -120,7 +124,7 @@ export function createProgram(dependencies = {}) {
             !process.env.GITDOG_API_KEY &&
             !(await new SessionStore().read())) {
             if (!process.stdin.isTTY || ui.json)
-                throw new Error("Run gitdog login before gitdog init.");
+                throw new Error("Run npx gitdog@latest login before npx gitdog@latest init.");
             await login(apiUrl, siteUrl, ui);
         }
         await project.init(args[0], text(opts.alias) ?? "default", flag(opts.force));
@@ -164,6 +168,8 @@ export function createProgram(dependencies = {}) {
         const out = text(opts.out);
         if (out && (await exists(resolve(out))))
             throw new Error("The output file already exists. Choose a new private path.");
+        if (out)
+            await assertUntrackedKeyPath(resolve(out));
         const name = text(opts.name) ?? "CLI key";
         const scopes = flag(opts.write) ? ["read", "write"] : ["read"];
         const issued = await api.call("action", "apiKeys/action:create", {
@@ -210,7 +216,7 @@ export function createProgram(dependencies = {}) {
             expiresAt: issued.expiresAt,
             keyFile,
         });
-        ui.info(`Key saved privately. Use: gitdog --key-file ${JSON.stringify(keyFile)} projects list`);
+        ui.info(`Key saved privately. Use: npx gitdog@latest --key-file ${JSON.stringify(keyFile)} projects list`);
     })
         .option("--name <name>", "Key name", "CLI key")
         .option("--write", "Grant project settings and ticket write access (read access is always included)")
@@ -322,7 +328,7 @@ export function createProgram(dependencies = {}) {
         do {
             const remaining = deadline - Date.now();
             if (flag(opts.wait) && remaining <= 0)
-                throw new Error("Timed out waiting for indexing. Indexing continues on the server; check gitdog index status.");
+                throw new Error("Timed out waiting for indexing. Indexing continues on the server; check npx gitdog@latest index status.");
             const state = await api.call("query", "repoIndexing/query:getIndexingStatus", { repositoryId: repo._id }, flag(opts.wait) ? { timeoutMs: remaining } : undefined);
             const record = asRecord(state);
             if (!record)
@@ -337,14 +343,14 @@ export function createProgram(dependencies = {}) {
                 last = fingerprint;
             }
             if (record.status === "failed" || record.ragStatus === "failed")
-                throw new Error("Indexing failed. Run gitdog index logs for details.");
+                throw new Error("Indexing failed. Run npx gitdog@latest index logs for details.");
             if (record.status === "completed" &&
                 ["completed", "skipped"].includes(String(record.ragStatus))) {
                 ui.output(state);
                 return;
             }
             if (Date.now() >= deadline)
-                throw new Error("Timed out waiting for indexing. Indexing continues on the server; check gitdog index status.");
+                throw new Error("Timed out waiting for indexing. Indexing continues on the server; check npx gitdog@latest index status.");
             await new Promise((resolve) => setTimeout(resolve, Math.min(2000, Math.max(1, deadline - Date.now()))));
         } while (true);
     })
@@ -514,7 +520,7 @@ export function createProgram(dependencies = {}) {
             await openBrowser(url);
         ui.output({
             url,
-            next: "After GitHub authorization, run gitdog github recover, then gitdog projects available.",
+            next: "After GitHub authorization, run npx gitdog@latest github recover, then npx gitdog@latest projects available.",
         });
     })
         .option("--app <slug>", "GitHub App slug (use gitdogbot-dev for development)", "gitdogbot")
@@ -525,7 +531,7 @@ export function createProgram(dependencies = {}) {
             if (result?.status !== "recovered") {
                 ui.output({ ...result, recoveredCount: count });
                 if (result?.status === "reauth_required")
-                    throw new Error("Refresh GitHub authorization with gitdog login, then run github recover again.");
+                    throw new Error("Refresh GitHub authorization with npx gitdog@latest login, then run github recover again.");
                 return;
             }
             ui.info(`Recovered installation ${String(result.installationId)}.`);
@@ -566,7 +572,7 @@ export function createProgram(dependencies = {}) {
         if (operation.path === "apiKeys/action:create")
             throw new Error("Use keys create to issue API keys securely into a private file.");
         if (!operation.path.startsWith("admin/"))
-            throw new Error("Use gitdog api call for non-admin operations.");
+            throw new Error("Use npx gitdog@latest api call for non-admin operations.");
         const data = await jsonArguments(text(opts.data) ?? "{}");
         if (operation.kind !== "query") {
             if (!ui.json)

package/dist/projects.js

@@ -1,5 +1,6 @@
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
+import { homedir } from "node:os";
 import { dirname, join, resolve } from "node:path";
 import { exists, readJson, writeJson } from "./storage.js";
 import { asRecord, integer } from "./ui.js";
@@ -47,7 +48,7 @@ export function validateSettings(value, complete = false) {
                 throw new Error(`${key} must be a string.`);
         }
         else
-            throw new Error(`Unknown setting: ${key}. Run gitdog config keys.`);
+            throw new Error(`Unknown setting: ${key}. Run npx gitdog@latest config keys.`);
         settings[key] = item;
     }
     if (complete &&
@@ -62,7 +63,7 @@ export function validateProjectConfig(value) {
         typeof config.defaultProject !== "string" ||
         !projects ||
         !Object.hasOwn(projects, config.defaultProject))
-        throw new Error("Invalid gitdog.json. Run gitdog init in a new directory, or repair the project configuration.");
+        throw new Error("Invalid gitdog.json. Run npx gitdog@latest init in a new directory, or repair the project configuration.");
     const result = {};
     for (const [alias, value] of Object.entries(projects)) {
         aliasName(alias);
@@ -83,13 +84,18 @@ export function validateProjectConfig(value) {
 export async function findConfig(explicit, cwd = process.cwd()) {
     if (explicit)
         return resolve(cwd, explicit);
+    // Stop at the repository root or home so a file planted in a shared parent
+    // directory cannot choose the project.
     let directory = resolve(cwd);
+    const home = resolve(homedir());
     while (true) {
         const path = join(directory, "gitdog.json");
         if (await exists(path))
             return path;
         const parent = dirname(directory);
-        if (parent === directory)
+        if (parent === directory ||
+            directory === home ||
+            (await exists(join(directory, ".git"))))
             return undefined;
         directory = parent;
     }
@@ -108,10 +114,10 @@ export class ProjectContext {
     async config() {
         const path = await findConfig(this.configOption);
         if (!path)
-            throw new Error("No gitdog.json found. Run gitdog init, or pass --project owner/repo.");
+            throw new Error("No gitdog.json found. Run npx gitdog@latest init, or pass --project owner/repo.");
         const value = await readJson(path);
         if (value === undefined)
-            throw new Error(`No project configuration at ${path}. Run gitdog init.`);
+            throw new Error(`No project configuration at ${path}. Run npx gitdog@latest init.`);
         return { path, value: validateProjectConfig(value) };
     }
     async target(override) {
@@ -128,7 +134,7 @@ export class ProjectContext {
         const { value } = await this.config();
         const alias = selection ?? value.defaultProject;
         if (!Object.hasOwn(value.projects, alias))
-            throw new Error(`Unknown project alias ${alias}. Run gitdog use --list.`);
+            throw new Error(`Unknown project alias ${alias}. Run npx gitdog@latest use --list.`);
         return value.projects[alias].repository;
     }
     async repository(override) {
@@ -137,7 +143,7 @@ export class ProjectContext {
             ? await this.api.call("query", "repositories/query:get", { owner: target.split("/")[0], repo: target.split("/")[1] })
             : await this.api.call("query", "repositories/query:getById", { repositoryId: target });
         if (!repository)
-            throw new Error(`Project ${target} is not connected or accessible. Run gitdog projects create ${target}.`);
+            throw new Error(`Project ${target} is not connected or accessible. Run npx gitdog@latest projects create ${target}.`);
         return repository;
     }
     async available(reconnectRepositoryId) {
@@ -168,7 +174,7 @@ export class ProjectContext {
         const available = await this.available(reconnectRepositoryId);
         const matches = available.filter((item) => String(item.fullName).toLowerCase() === name.toLowerCase());
         if (matches.length !== 1)
-            throw new Error(`Repository ${name} is unavailable. Run gitdog github install, authorize it, then gitdog github recover. Check projects available.`);
+            throw new Error(`Repository ${name} is unavailable. Run npx gitdog@latest github install, authorize it, then npx gitdog@latest github recover. Check projects available.`);
         const item = matches[0];
         if (typeof item.installationId !== "number" || typeof item.id !== "number")
             throw new Error("GitHub returned invalid repository identifiers.");
@@ -190,7 +196,7 @@ export class ProjectContext {
             join(process.cwd(), "gitdog.json");
         const previous = await readJson(path);
         if (previous !== undefined && !force)
-            throw new Error(`Project configuration already exists at ${path}. Use gitdog use --add, or --force to replace it.`);
+            throw new Error(`Project configuration already exists at ${path}. Use npx gitdog@latest use --add, or --force to replace it.`);
         if (!name) {
             let detected;
             try {
@@ -225,14 +231,14 @@ export class ProjectContext {
             alias,
             config: path,
         });
-        this.ui.info("✓ Ready. Try gitdog status, gitdog config get, or gitdog tickets list.");
+        this.ui.info("✓ Ready. Try npx gitdog@latest status, npx gitdog@latest config get, or npx gitdog@latest tickets list.");
     }
     async use(selection, add, list = false) {
         const { path, value } = await this.config();
         if (add) {
             aliasName(add);
             if (!selection)
-                throw new Error("Use gitdog use owner/repo --add alias.");
+                throw new Error("Use npx gitdog@latest use owner/repo --add alias.");
             if (Object.hasOwn(value.projects, add))
                 throw new Error(`Alias ${add} already exists. Choose a new alias.`);
             const repo = await this.repository(selection);
@@ -268,7 +274,7 @@ export class ProjectContext {
             : Object.keys(value.projects).find((key) => value.projects[key].repository.toLowerCase() ===
                 alias.toLowerCase());
         if (!match)
-            throw new Error("This project has no local settings. Add it with gitdog use owner/repo --add alias.");
+            throw new Error("This project has no local settings. Add it with npx gitdog@latest use owner/repo --add alias.");
         return { path, value, alias: match, project: value.projects[match] };
     }
     async configGet(key, remote = false) {
@@ -292,7 +298,7 @@ export class ProjectContext {
         local.project.settings = { ...local.project.settings, ...patch };
         await writeJson(local.path, local.value);
         this.ui.output({ saved: true, settings: patch });
-        this.ui.info("Saved locally. Run gitdog config push to apply.");
+        this.ui.info("Saved locally. Run npx gitdog@latest config push to apply.");
     }
     async configPull(force = false) {
         const local = await this.localProject();

package/dist/storage.js

@@ -1,4 +1,4 @@
-import { chmod, mkdir, open, readFile, rename, rm, stat, } from "node:fs/promises";
+import { chmod, mkdir, open, readFile, rename, rmdir, rm, stat, } from "node:fs/promises";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 import { randomUUID } from "node:crypto";
@@ -80,7 +80,7 @@ export class SessionStore {
         if (!validTokens(value) ||
             typeof item?.apiUrl !== "string" ||
             typeof item.siteUrl !== "string")
-            throw new Error("Invalid saved session. Run gitdog logout, then gitdog login.");
+            throw new Error("Invalid saved session. Run npx gitdog@latest logout, then npx gitdog@latest login.");
         return {
             ...value,
             apiUrl: validateUrl(item.apiUrl, "Saved API URL"),
@@ -102,13 +102,24 @@ export class SessionStore {
         while (!handle) {
             signal?.throwIfAborted();
             if (Date.now() >= deadline)
-                throw new Error(`Authentication lock timed out. Check that another Gitdog process is not running; stale lock: ${path}.`);
+                throw new Error(`Authentication lock timed out. Check that another Gitdog process is not running; stale lock: ${path} (recovery gate: ${path}.recovery).`);
             try {
-                handle = await open(path, "wx", 0o600);
+                const created = await open(path, "wx", 0o600);
+                try {
+                    await created.writeFile(String(process.pid));
+                }
+                catch (error) {
+                    await created.close();
+                    await rm(path, { force: true });
+                    throw error;
+                }
+                handle = created;
             }
             catch (error) {
                 if (error.code !== "EEXIST")
                     throw error;
+                if (await removeAbandonedLock(path))
+                    continue;
                 if (Date.now() >= deadline)
                     throw new Error(`Another Gitdog process is updating authentication. Retry later; if it crashed, remove ${path}.`);
                 await new Promise((resolve) => setTimeout(resolve, Math.min(100, Math.max(1, deadline - Date.now()))));
@@ -124,6 +135,42 @@ export class SessionStore {
         }
     }
 }
+/** Remove a lock whose recorded owner process no longer exists. */
+async function removeAbandonedLock(path) {
+    const recovery = `${path}.recovery`;
+    try {
+        await mkdir(recovery, { mode: 0o700 });
+    }
+    catch {
+        return false;
+    }
+    try {
+        // Re-read under the recovery mutex: another waiter may have replaced the
+        // dead owner's lock with a live lock before this cleaner acquired the gate.
+        const content = (await readFile(path, "utf8")).trim();
+        if (!/^[1-9]\d*$/.test(content))
+            return false;
+        const owner = Number(content);
+        if (!Number.isSafeInteger(owner) || owner === process.pid)
+            return false;
+        try {
+            process.kill(owner, 0);
+            return false;
+        }
+        catch (error) {
+            if (error.code !== "ESRCH")
+                return false;
+        }
+        await rm(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+    finally {
+        await rmdir(recovery);
+    }
+}
 export function tokenExpiresSoon(token) {
     try {
         const payload = asRecord(JSON.parse(Buffer.from(token.split(".")[1], "base64url").toString("utf8")));

package/dist/ui.d.ts

@@ -1,7 +1,9 @@
-export declare const VERSION = "0.1.0";
+export declare const VERSION = "0.1.2";
 export declare const DOG: string;
 export declare function redactSecrets(value: string): string;
 export declare function clean(value: string): string;
+/** Escape characters JSON.stringify leaves raw; the JSON value is unchanged. */
+export declare function safeJson(value: unknown): string;
 export declare class Ui {
     readonly json: boolean;
     constructor(json?: boolean);

package/dist/ui.js

@@ -1,20 +1,46 @@
 import { createInterface } from "node:readline/promises";
 import { stripVTControlCharacters } from "node:util";
-export const VERSION = "0.1.0";
+export const VERSION = "0.1.2";
 export const DOG = String.raw `
-    / \__
-   (    @\___
-   /         O
-  /   (_____/
- /_____/   U
+  ▗██▄▄                      ▄▄██▖
+  ██▀▜██▙▄  ▙▄            ▄▟██▛▀██
+ ▐█▌   ▀███▄▐██▄        ▄███▀   ▜█▌
+ ▐█▌     ███████▙      ▝▀▀▀     ▐█▌
+ ██▌   ▄█████████▌              ▐█▌
+ ▐█▌ ▄████████████              ▐█▌
+ ▐█▙▟████████████▌              ▜█▘
+  ▀▝▀▘     ▀▀███▛
+
+         ▄█▙▖          ▄█▙▖
+         ▜██▌    ▄▄    ▜██▘
+             ▄███▛▜███▄
+           ▗███▌    ▐███▖
+           █████▄  ▄█████
+  ▗▄       ▝▜██▛▀  ▀▜██▛▘       ▄▖
+  ▐██▄▖                      ▗▄██▌
+  ▟█████▙▄▖              ▗▄▄█████▙
+ ▐█▛███████████▄▄▄▄▄▄███████████▜█▌
+  ▀ ▝██████████████████████████▘ ▀
+     ▝▜██████████████████████▛▘
+       ▝▜██████████████████▀▘
+          ▀▀▜█▜██████▛█▛▀▘
+                ▀▀▀▀
 `;
 export function redactSecrets(value) {
     return value
         .replace(/\beyJ[\w-]+\.[\w-]+\.[\w-]+\b/g, "[redacted token]")
         .replace(/\bgdk_[a-f0-9]{64}\b/g, "[redacted API key]");
 }
+// C1 controls and bidirectional overrides can drive or spoof terminals.
+const UNSAFE_UNICODE = /[\u0080-\u009f\u202a-\u202e\u2066-\u2069]/g;
 export function clean(value) {
-    return redactSecrets(stripVTControlCharacters(value).replace(/[\x00-\x08\x0b-\x1f\x7f]/g, ""));
+    return redactSecrets(stripVTControlCharacters(value)
+        .replace(/[\x00-\x08\x0b-\x1f\x7f]/g, "")
+        .replace(UNSAFE_UNICODE, ""));
+}
+/** Escape characters JSON.stringify leaves raw; the JSON value is unchanged. */
+export function safeJson(value) {
+    return redactSecrets(JSON.stringify(value ?? null, null, 2)).replace(UNSAFE_UNICODE, (character) => `\\u${character.charCodeAt(0).toString(16).padStart(4, "0")}`);
 }
 export class Ui {
     json;
@@ -31,7 +57,7 @@ export class Ui {
     banner() {
         if (this.json || process.env.GITDOG_NO_BANNER === "1")
             return;
-        process.stdout.write(this.color(DOG) + this.color(`  G I T D O G  /  ${VERSION}\n`, 1));
+        process.stdout.write(this.color(DOG, 1) + this.color(`  G I T D O G  /  ${VERSION}\n`, 1));
         process.stdout.write("  Your repositories. A very good assistant.\n\n");
     }
     info(message) {
@@ -40,7 +66,7 @@ export class Ui {
     }
     output(value) {
         if (this.json) {
-            process.stdout.write(`${redactSecrets(JSON.stringify(value ?? null, null, 2))}\n`);
+            process.stdout.write(`${safeJson(value)}\n`);
             return;
         }
         if (typeof value === "string") {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gitdog",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Manage Gitdog projects, GitHub automation and API keys from your terminal",
   "type": "module",
   "bin": {