gitdog 0.1.1 → 0.1.2

package/README.md

@@ -17,29 +17,29 @@
 </p>
 
 <p align="center">
-  <img src="https://raw.githubusercontent.com/hyodotdev/gitdog-cli/main/.github/assets/terminal.svg?v=0.1.1" 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/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

@@ -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));
@@ -212,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)")
@@ -324,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)
@@ -339,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);
     })
@@ -516,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")
@@ -527,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)}.`);
@@ -568,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

@@ -48,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 &&
@@ -63,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);
@@ -114,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) {
@@ -134,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) {
@@ -143,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) {
@@ -174,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.");
@@ -196,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 {
@@ -231,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);
@@ -274,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) {
@@ -298,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

@@ -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"),

package/dist/ui.d.ts

@@ -1,4 +1,4 @@
-export declare const VERSION = "0.1.1";
+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;

package/dist/ui.js

@@ -1,6 +1,6 @@
 import { createInterface } from "node:readline/promises";
 import { stripVTControlCharacters } from "node:util";
-export const VERSION = "0.1.1";
+export const VERSION = "0.1.2";
 export const DOG = String.raw `
   ▗██▄▄                      ▄▄██▖
   ██▀▜██▙▄  ▙▄            ▄▟██▛▀██

package/package.json

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