gitdog 0.0.0-stage → 0.1.0

package/dist/projects.d.ts

@@ -0,0 +1,55 @@
+import { type Ui } from "./ui.js";
+import type { Api } from "./client.js";
+export declare const BOOLEAN_SETTINGS: readonly ["issueAssistantEnabled", "autoFormatIssue", "autoAnswerQuestions", "tagMaintainersForCodeChanges", "requireApproval", "discussionAssistantEnabled", "autoFormatDiscussion", "autoAnswerDiscussionQuestions", "tagMaintainersForDiscussionCodeChanges", "requireApprovalForDiscussions"];
+export declare const STYLE_SETTINGS: readonly ["issueResponseStyle", "discussionResponseStyle"];
+export type Settings = Record<(typeof BOOLEAN_SETTINGS)[number], boolean> & Partial<Record<(typeof STYLE_SETTINGS)[number], string>>;
+export type Project = {
+    repository: string;
+    settings: Partial<Settings>;
+};
+export type ProjectConfig = {
+    version: 1;
+    defaultProject: string;
+    projects: Record<string, Project>;
+};
+export type Repository = {
+    _id: string;
+    githubRepo: string;
+    settings: Settings;
+    isActive: boolean;
+    [key: string]: unknown;
+};
+export declare function repositoryName(value: string): string;
+export declare function aliasName(value: string): string;
+export declare function validateSettings(value: unknown, complete?: boolean): Partial<Settings>;
+export declare function validateProjectConfig(value: unknown): ProjectConfig;
+export declare function findConfig(explicit?: string, cwd?: string): Promise<string | undefined>;
+export declare class ProjectContext {
+    readonly api: Api;
+    readonly ui: Ui;
+    readonly selected?: string | undefined;
+    readonly configOption?: string | undefined;
+    constructor(api: Api, ui: Ui, selected?: string | undefined, configOption?: string | undefined);
+    config(): Promise<{
+        path: string;
+        value: ProjectConfig;
+    }>;
+    target(override?: string): Promise<string>;
+    repository(override?: string): Promise<Repository>;
+    available(reconnectRepositoryId?: string): Promise<Record<string, unknown>[]>;
+    connect(name: string, reconnectRepositoryId?: string): Promise<Repository>;
+    init(name?: string, alias?: string, force?: boolean): Promise<void>;
+    use(selection?: string, add?: string, list?: boolean): Promise<void>;
+    localProject(): Promise<{
+        path: string;
+        value: ProjectConfig;
+        alias: string;
+        project: Project;
+    }>;
+    configGet(key?: string, remote?: boolean): Promise<void>;
+    configSet(key: string, text: string): Promise<void>;
+    configPull(force?: boolean): Promise<void>;
+    configPush(dryRun?: boolean, yes?: boolean): Promise<void>;
+}
+export declare function chooseProject(ui: Ui, api: Api): Promise<string>;
+export declare const limitParser: (value: string) => number;

package/dist/projects.js

@@ -0,0 +1,349 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { dirname, join, resolve } from "node:path";
+import { exists, readJson, writeJson } from "./storage.js";
+import { asRecord, integer } from "./ui.js";
+export const BOOLEAN_SETTINGS = [
+    "issueAssistantEnabled",
+    "autoFormatIssue",
+    "autoAnswerQuestions",
+    "tagMaintainersForCodeChanges",
+    "requireApproval",
+    "discussionAssistantEnabled",
+    "autoFormatDiscussion",
+    "autoAnswerDiscussionQuestions",
+    "tagMaintainersForDiscussionCodeChanges",
+    "requireApprovalForDiscussions",
+];
+export const STYLE_SETTINGS = [
+    "issueResponseStyle",
+    "discussionResponseStyle",
+];
+export function repositoryName(value) {
+    if (!/^[a-z\d](?:[a-z\d-]*[a-z\d])?\/[\w.-]+$/i.test(value) ||
+        value.endsWith("/.") ||
+        value.endsWith("/.."))
+        throw new Error("Use a GitHub repository name such as owner/repo.");
+    return value;
+}
+export function aliasName(value) {
+    if (!/^[a-z\d][a-z\d_-]{0,63}$/i.test(value) ||
+        ["__proto__", "constructor", "prototype"].includes(value))
+        throw new Error("Project aliases must use letters, numbers, underscores or hyphens (1–64 characters).");
+    return value;
+}
+export function validateSettings(value, complete = false) {
+    const record = asRecord(value);
+    if (!record)
+        throw new Error("Settings must be a JSON object.");
+    const settings = {};
+    for (const [key, item] of Object.entries(record)) {
+        if (BOOLEAN_SETTINGS.includes(key)) {
+            if (typeof item !== "boolean")
+                throw new Error(`${key} must be true or false.`);
+        }
+        else if (STYLE_SETTINGS.includes(key)) {
+            if (typeof item !== "string")
+                throw new Error(`${key} must be a string.`);
+        }
+        else
+            throw new Error(`Unknown setting: ${key}. Run gitdog config keys.`);
+        settings[key] = item;
+    }
+    if (complete &&
+        BOOLEAN_SETTINGS.some((key) => typeof settings[key] !== "boolean"))
+        throw new Error("The server returned incomplete project settings. Update Gitdog before applying settings.");
+    return settings;
+}
+export function validateProjectConfig(value) {
+    const config = asRecord(value);
+    const projects = asRecord(config?.projects);
+    if (config?.version !== 1 ||
+        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.");
+    const result = {};
+    for (const [alias, value] of Object.entries(projects)) {
+        aliasName(alias);
+        const project = asRecord(value);
+        if (typeof project?.repository !== "string")
+            throw new Error(`Missing repository for ${alias}.`);
+        result[alias] = {
+            repository: repositoryName(project.repository),
+            settings: validateSettings(project.settings ?? {}),
+        };
+    }
+    return {
+        version: 1,
+        defaultProject: config.defaultProject,
+        projects: result,
+    };
+}
+export async function findConfig(explicit, cwd = process.cwd()) {
+    if (explicit)
+        return resolve(cwd, explicit);
+    let directory = resolve(cwd);
+    while (true) {
+        const path = join(directory, "gitdog.json");
+        if (await exists(path))
+            return path;
+        const parent = dirname(directory);
+        if (parent === directory)
+            return undefined;
+        directory = parent;
+    }
+}
+export class ProjectContext {
+    api;
+    ui;
+    selected;
+    configOption;
+    constructor(api, ui, selected, configOption) {
+        this.api = api;
+        this.ui = ui;
+        this.selected = selected;
+        this.configOption = configOption;
+    }
+    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.");
+        const value = await readJson(path);
+        if (value === undefined)
+            throw new Error(`No project configuration at ${path}. Run gitdog init.`);
+        return { path, value: validateProjectConfig(value) };
+    }
+    async target(override) {
+        const selection = override ?? this.selected;
+        if (selection?.includes("/"))
+            return repositoryName(selection);
+        if (selection && /^[a-z0-9]{20,64}$/.test(selection)) {
+            const path = await findConfig(this.configOption);
+            const raw = path ? await readJson(path) : undefined;
+            if (!raw ||
+                !Object.hasOwn(validateProjectConfig(raw).projects, selection))
+                return selection;
+        }
+        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.`);
+        return value.projects[alias].repository;
+    }
+    async repository(override) {
+        const target = await this.target(override);
+        const repository = target.includes("/")
+            ? 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}.`);
+        return repository;
+    }
+    async available(reconnectRepositoryId) {
+        const repositories = [];
+        const seen = new Set();
+        let cursor;
+        for (let page = 0; page < 500; page++) {
+            const result = await this.api.call("action", "github/action:listUserRepositories", {
+                ...(cursor ? { cursor } : {}),
+                ...(reconnectRepositoryId ? { reconnectRepositoryId } : {}),
+            });
+            repositories.push(...result.repositories);
+            if (result.continueCursor === null)
+                return repositories;
+            if (seen.has(result.continueCursor))
+                throw new Error("GitHub returned a repeated repository page. Try again later.");
+            seen.add(result.continueCursor);
+            cursor = result.continueCursor;
+        }
+        throw new Error("Too many repository pages. Use projects available --cursor for explicit pagination.");
+    }
+    async connect(name, reconnectRepositoryId) {
+        repositoryName(name);
+        const [owner, repo] = name.split("/");
+        const existing = await this.api.call("query", "repositories/query:get", { owner, repo });
+        if (existing && !reconnectRepositoryId)
+            return existing;
+        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.`);
+        const item = matches[0];
+        if (typeof item.installationId !== "number" || typeof item.id !== "number")
+            throw new Error("GitHub returned invalid repository identifiers.");
+        this.ui.info(`Connecting ${name} and scheduling repository indexing…`);
+        await this.api.call("action", "repositories/action:createAndIndex", {
+            installationId: item.installationId,
+            githubRepositoryId: item.id,
+            ...(reconnectRepositoryId ? { reconnectRepositoryId } : {}),
+        });
+        const result = await this.api.call("query", "repositories/query:get", { owner, repo });
+        if (!result)
+            throw new Error("The connection was accepted but is not readable yet. Check projects list before retrying.");
+        return result;
+    }
+    async init(name, alias = "default", force = false) {
+        this.ui.banner();
+        aliasName(alias);
+        const path = (await findConfig(this.configOption)) ??
+            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.`);
+        if (!name) {
+            let detected;
+            try {
+                const { stdout } = await promisify(execFile)("git", ["remote", "get-url", "origin"], { timeout: 5000 });
+                const match = /^(?:git@github\.com:|https:\/\/github\.com\/|ssh:\/\/git@github\.com\/)([^\s]+?)\/?$/.exec(stdout.trim());
+                if (match)
+                    detected = repositoryName(match[1].replace(/\.git$/, ""));
+            }
+            catch {
+                /* A project can be initialized outside a Git checkout. */
+            }
+            this.ui.info("1 / 3  Choose a GitHub repository");
+            name = await this.ui.ask("Repository (owner/repo)", detected);
+        }
+        this.ui.info("2 / 3  Connect your Gitdog project");
+        const repo = await this.connect(name);
+        const value = {
+            version: 1,
+            defaultProject: alias,
+            projects: {
+                [alias]: {
+                    repository: repo.githubRepo,
+                    settings: validateSettings(repo.settings, true),
+                },
+            },
+        };
+        this.ui.info("3 / 3  Save project settings");
+        await writeJson(path, value);
+        this.ui.output({
+            initialized: true,
+            project: repo.githubRepo,
+            alias,
+            config: path,
+        });
+        this.ui.info("✓ Ready. Try gitdog status, gitdog config get, or gitdog 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.");
+            if (Object.hasOwn(value.projects, add))
+                throw new Error(`Alias ${add} already exists. Choose a new alias.`);
+            const repo = await this.repository(selection);
+            value.projects[add] = {
+                repository: repo.githubRepo,
+                settings: validateSettings(repo.settings, true),
+            };
+            value.defaultProject = add;
+        }
+        else if (selection) {
+            if (!Object.hasOwn(value.projects, selection))
+                throw new Error(`Unknown alias ${selection}. Use --add alias to add a project.`);
+            value.defaultProject = selection;
+        }
+        if (selection || add)
+            await writeJson(path, value);
+        this.ui.output(list
+            ? Object.entries(value.projects).map(([name, project]) => ({
+                name,
+                githubRepo: project.repository,
+                status: name === value.defaultProject ? "active" : "",
+            }))
+            : {
+                alias: value.defaultProject,
+                project: value.projects[value.defaultProject].repository,
+            });
+    }
+    async localProject() {
+        const { path, value } = await this.config();
+        const alias = this.selected ?? value.defaultProject;
+        const match = Object.hasOwn(value.projects, alias)
+            ? alias
+            : 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.");
+        return { path, value, alias: match, project: value.projects[match] };
+    }
+    async configGet(key, remote = false) {
+        const settings = remote
+            ? (await this.repository()).settings
+            : (await this.localProject()).project.settings;
+        if (key && !Object.hasOwn(settings, key))
+            throw new Error(`Setting ${key} is not set.`);
+        this.ui.output(key ? settings[key] : settings);
+    }
+    async configSet(key, text) {
+        const value = BOOLEAN_SETTINGS.includes(key)
+            ? text === "true"
+                ? true
+                : text === "false"
+                    ? false
+                    : text
+            : text;
+        const patch = validateSettings({ [key]: value });
+        const local = await this.localProject();
+        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.");
+    }
+    async configPull(force = false) {
+        const local = await this.localProject();
+        const settings = validateSettings((await this.repository(local.project.repository)).settings, true);
+        await this.ui.confirm("Replace local settings with server settings?", force);
+        local.project.settings = settings;
+        await writeJson(local.path, local.value);
+        this.ui.output({ pulled: true, settings });
+    }
+    async configPush(dryRun = false, yes = false) {
+        const local = await this.localProject();
+        const repo = await this.repository(local.project.repository);
+        const before = validateSettings(repo.settings, true);
+        const after = validateSettings({ ...before, ...local.project.settings }, true);
+        const changes = Object.entries(after)
+            .filter(([key, value]) => before[key] !== value)
+            .map(([key, value]) => ({
+            key,
+            before: before[key] ?? null,
+            after: value,
+        }));
+        if (!this.ui.json)
+            this.ui.output({ project: repo.githubRepo, changes });
+        if (dryRun || changes.length === 0) {
+            this.ui.output({
+                dryRun,
+                applied: false,
+                project: repo.githubRepo,
+                changes,
+            });
+            return;
+        }
+        await this.ui.confirm(`Apply ${changes.length} setting change(s) to ${repo.githubRepo}?`, yes);
+        await this.api.call("mutation", "repositories/mutation:updateSettings", {
+            repositoryId: repo._id,
+            settings: after,
+        });
+        const actual = validateSettings((await this.repository(local.project.repository)).settings, true);
+        if (Object.entries(after).some(([key, value]) => actual[key] !== value))
+            throw new Error("Settings changed during verification. Run config get --remote and compare before retrying.");
+        this.ui.output({
+            applied: true,
+            project: repo.githubRepo,
+            changes,
+            settings: actual,
+        });
+    }
+}
+export async function chooseProject(ui, api) {
+    const repos = await api.call("query", "repositories/query:list");
+    ui.output(repos);
+    return ui.ask("Repository to use (owner/repo)");
+}
+export const limitParser = (value) => integer(value, 1, 500);

package/dist/storage.d.ts

@@ -0,0 +1,24 @@
+export declare const DEFAULT_API_URL = "https://calm-hippopotamus-56.convex.cloud";
+export declare const DEFAULT_SITE_URL = "https://gitdog.dev";
+export type Tokens = {
+    token: string;
+    refreshToken: string;
+};
+export type Session = Tokens & {
+    apiUrl: string;
+    siteUrl: string;
+};
+export declare function configDirectory(): string;
+export declare function readJson(path: string): Promise<unknown | undefined>;
+export declare function writeJson(path: string, value: unknown, privateFile?: boolean, signal?: AbortSignal): Promise<void>;
+export declare function validTokens(value: unknown): value is Tokens;
+export declare function validateUrl(value: string, label: string): string;
+export declare class SessionStore {
+    readonly path: string;
+    read(): Promise<Session | undefined>;
+    save(session: Session, signal?: AbortSignal): Promise<void>;
+    clear(): Promise<void>;
+    locked<T>(callback: () => Promise<T>, requestDeadline?: number, signal?: AbortSignal): Promise<T>;
+}
+export declare function tokenExpiresSoon(token: string): boolean;
+export declare function exists(path: string): Promise<boolean>;

package/dist/storage.js

@@ -0,0 +1,147 @@
+import { chmod, mkdir, open, readFile, rename, rm, stat, } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { randomUUID } from "node:crypto";
+import { asRecord } from "./ui.js";
+export const DEFAULT_API_URL = "https://calm-hippopotamus-56.convex.cloud";
+export const DEFAULT_SITE_URL = "https://gitdog.dev";
+export function configDirectory() {
+    return (process.env.GITDOG_CONFIG_DIR ||
+        join(process.env.XDG_CONFIG_HOME || join(homedir(), ".config"), "gitdog"));
+}
+export async function readJson(path) {
+    try {
+        return JSON.parse(await readFile(path, "utf8"));
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return undefined;
+        throw new Error(`Cannot read ${path}. Check its permissions and JSON syntax.`);
+    }
+}
+export async function writeJson(path, value, privateFile = false, signal) {
+    signal?.throwIfAborted();
+    await mkdir(dirname(path), {
+        recursive: true,
+        mode: privateFile ? 0o700 : 0o755,
+    });
+    if (privateFile)
+        await chmod(dirname(path), 0o700);
+    const temporary = `${path}.${randomUUID()}.tmp`;
+    try {
+        const file = await open(temporary, "wx", privateFile ? 0o600 : 0o644);
+        try {
+            signal?.throwIfAborted();
+            await file.writeFile(`${JSON.stringify(value, null, 2)}\n`);
+        }
+        finally {
+            await file.close();
+        }
+        signal?.throwIfAborted();
+        await rename(temporary, path);
+    }
+    finally {
+        await rm(temporary, { force: true });
+    }
+}
+export function validTokens(value) {
+    const item = asRecord(value);
+    return (typeof item?.token === "string" &&
+        item.token.length > 0 &&
+        typeof item.refreshToken === "string" &&
+        item.refreshToken.length > 0);
+}
+export function validateUrl(value, label) {
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        throw new Error(`${label} must be an absolute URL.`);
+    }
+    const loopback = ["localhost", "127.0.0.1", "[::1]"].includes(url.hostname);
+    if ((url.protocol !== "https:" && !(url.protocol === "http:" && loopback)) ||
+        url.username ||
+        url.password ||
+        url.pathname !== "/" ||
+        url.search ||
+        url.hash) {
+        throw new Error(`${label} must be an HTTPS origin (HTTP is allowed for localhost development).`);
+    }
+    return url.origin;
+}
+export class SessionStore {
+    path = join(configDirectory(), "session.json");
+    async read() {
+        const value = await readJson(this.path);
+        if (value === undefined)
+            return undefined;
+        const item = asRecord(value);
+        if (!validTokens(value) ||
+            typeof item?.apiUrl !== "string" ||
+            typeof item.siteUrl !== "string")
+            throw new Error("Invalid saved session. Run gitdog logout, then gitdog login.");
+        return {
+            ...value,
+            apiUrl: validateUrl(item.apiUrl, "Saved API URL"),
+            siteUrl: validateUrl(item.siteUrl, "Saved site URL"),
+        };
+    }
+    async save(session, signal) {
+        await writeJson(this.path, session, true, signal);
+    }
+    async clear() {
+        await rm(this.path, { force: true });
+    }
+    async locked(callback, requestDeadline, signal) {
+        signal?.throwIfAborted();
+        await mkdir(dirname(this.path), { recursive: true, mode: 0o700 });
+        const path = `${this.path}.lock`;
+        const deadline = Math.min(Date.now() + 10_000, requestDeadline ?? Infinity);
+        let handle;
+        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}.`);
+            try {
+                handle = await open(path, "wx", 0o600);
+            }
+            catch (error) {
+                if (error.code !== "EEXIST")
+                    throw error;
+                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()))));
+            }
+        }
+        try {
+            signal?.throwIfAborted();
+            return await callback();
+        }
+        finally {
+            await handle.close();
+            await rm(path, { force: true });
+        }
+    }
+}
+export function tokenExpiresSoon(token) {
+    try {
+        const payload = asRecord(JSON.parse(Buffer.from(token.split(".")[1], "base64url").toString("utf8")));
+        return (typeof payload?.exp !== "number" ||
+            payload.exp * 1000 < Date.now() + 60_000);
+    }
+    catch {
+        return true;
+    }
+}
+export async function exists(path) {
+    try {
+        await stat(path);
+        return true;
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return false;
+        throw error;
+    }
+}

package/dist/ui.d.ts

@@ -0,0 +1,17 @@
+export declare const VERSION = "0.1.0";
+export declare const DOG: string;
+export declare function redactSecrets(value: string): string;
+export declare function clean(value: string): string;
+export declare class Ui {
+    readonly json: boolean;
+    constructor(json?: boolean);
+    color(text: string, code?: number): string;
+    banner(): void;
+    info(message: string): void;
+    output(value: unknown): void;
+    table(rows: Record<string, unknown>[], keys: string[]): void;
+    ask(question: string, fallback?: string): Promise<string>;
+    confirm(message: string, yes?: boolean): Promise<void>;
+}
+export declare function asRecord(value: unknown): Record<string, unknown> | undefined;
+export declare function integer(value: string, minimum?: number, maximum?: number): number;