gitnexushub 0.4.5 → 0.6.0

package/dist/api.d.ts

@@ -33,6 +33,44 @@ export interface IndexResult {
     fullName: string;
     status: string;
 }
+/**
+ * Response from `POST /api/repos/:id/install-ci-bundle`.
+ *
+ * Hub mints a long-lived CI token + renders the single Claude-led
+ * workflow YAML. `token` and `ciToken` are the same value emitted
+ * twice for back-compat with the v1 client (which read `ciToken`)
+ * and any future caller that reads the more conventional `token`.
+ * Use `ciToken` — the field name documents intent.
+ *
+ * `workflowYaml` is the rendered `.github/workflows/gitnexus.yml`
+ * contents. The CLI base64-encodes and PUTs it via the GitHub
+ * Contents API; no template assembly happens client-side.
+ */
+export interface InstallCiBundle {
+    /** CI token. Same value as `ciToken` — emitted twice for back-compat. */
+    token: string;
+    /** CI token (preferred field name; documents intent). */
+    ciToken: string;
+    /** First 12 chars of the token for display in the CLI summary. */
+    ciTokenPrefix?: string;
+    /** Repo secret name the workflow YAML references for the gnx_ token. */
+    ciTokenSecretName?: string;
+    /** Repo secret name the workflow YAML references for Claude OAuth. */
+    claudeOauthSecretName?: string;
+    /** Rendered `.github/workflows/gitnexus.yml` contents. */
+    workflowYaml: string;
+    /** Hub MCP endpoint URL embedded in the workflow YAML. */
+    hubMcpUrl?: string;
+    /** owner/repo this token + workflow target. */
+    repoFullName: string;
+    /**
+     * Map of relative-path → file-content. Currently always
+     * `{ '.github/workflows/gitnexus.yml': workflowYaml }` — emitted as
+     * an object so future installs can ship sidecar config files (e.g.
+     * `.gitnexus.toml`) without bumping the response shape.
+     */
+    files?: Record<string, string>;
+}
 export interface RepoDetail {
     id: string;
     name: string;
@@ -121,6 +159,24 @@ export interface WikiUploadStatus {
     active: WikiUploadSessionRow | null;
     last: WikiUploadSessionRow | null;
 }
+export interface WikiGroupingContext {
+    communityGroups: string;
+    interCommunityEdges: string;
+    crossCommunityProcesses: string;
+    filesWithExports: string;
+    directoryTree: string;
+    communityMapping?: Array<{
+        label: string;
+        files: string[];
+    }>;
+    filesWithExportsRaw?: Array<{
+        filePath: string;
+        symbols: Array<{
+            name: string;
+            type: string;
+        }>;
+    }>;
+}
 export declare class HubAPI {
     private hubUrl;
     private token;
@@ -135,6 +191,14 @@ export declare class HubAPI {
     listRepos(): Promise<HubRepo[]>;
     getConnectContext(repoFullName: string): Promise<ConnectContext>;
     indexRepo(fullName: string): Promise<IndexResult>;
+    /**
+     * Mint a CI token for the given repo and fetch the rendered
+     * Claude-led workflow YAML in one call. Hub atomically revokes
+     * any prior `GitNexus CI` token for this repo and mints a fresh
+     * one — calling this repeatedly is safe and idempotent (the prior
+     * token stops working, the new one starts).
+     */
+    installCiBundle(repoId: string): Promise<InstallCiBundle>;
     getRepo(repoId: string): Promise<RepoDetail>;
     meta(repoId: string): Promise<RepoMeta>;
     sync(repoId: string, params: {
@@ -158,7 +222,32 @@ export declare class HubAPI {
     }>;
     wikiUploadStatus(repoId: string): Promise<WikiUploadStatus>;
     getWikiConfig(): Promise<WikiConfig>;
-    wikiGroupingContext(repoId: string): Promise<any>;
+    wikiGroupingContext(repoId: string): Promise<WikiGroupingContext>;
+    wikiStatus(repoId: string): Promise<{
+        status: string;
+        fromCommit?: string | null;
+        generatedAt?: string | null;
+        pageCount?: number;
+        generating?: boolean;
+    } | null>;
+    wikiTree(repoId: string): Promise<{
+        tree: Array<{
+            name: string;
+            slug: string;
+            files: string[];
+            children?: Array<{
+                name: string;
+                slug: string;
+                files: string[];
+            }>;
+        }>;
+    } | null>;
+    wikiPage(repoId: string, slug: string): Promise<{
+        slug: string;
+        title: string;
+        content: string;
+        updatedAt: string;
+    } | null>;
     wikiLeafContext(repoId: string, moduleName: string, filePaths: string[]): Promise<any>;
     wikiOverviewContext(repoId: string, moduleFiles: Record<string, string[]>): Promise<any>;
     wikiPromptTemplates(repoId: string): Promise<{

package/dist/api.js

@@ -77,6 +77,16 @@ export class HubAPI {
     async indexRepo(fullName) {
         return this.post('/api/repos/public', { fullName });
     }
+    /**
+     * Mint a CI token for the given repo and fetch the rendered
+     * Claude-led workflow YAML in one call. Hub atomically revokes
+     * any prior `GitNexus CI` token for this repo and mints a fresh
+     * one — calling this repeatedly is safe and idempotent (the prior
+     * token stops working, the new one starts).
+     */
+    async installCiBundle(repoId) {
+        return this.post(`/api/repos/${repoId}/install-ci-bundle`, {});
+    }
     async getRepo(repoId) {
         return this.request(`/api/repos/${repoId}`);
     }
@@ -143,6 +153,30 @@ export class HubAPI {
     async wikiGroupingContext(repoId) {
         return this.request(`/api/repos/${repoId}/wiki/context/grouping`);
     }
+    async wikiStatus(repoId) {
+        try {
+            return await this.request(`/api/repos/${repoId}/wiki/status`);
+        }
+        catch {
+            return null;
+        }
+    }
+    async wikiTree(repoId) {
+        try {
+            return await this.request(`/api/repos/${repoId}/wiki/tree`);
+        }
+        catch {
+            return null;
+        }
+    }
+    async wikiPage(repoId, slug) {
+        try {
+            return await this.request(`/api/repos/${repoId}/wiki/page/${encodeURIComponent(slug)}`);
+        }
+        catch {
+            return null;
+        }
+    }
     async wikiLeafContext(repoId, moduleName, filePaths) {
         const params = new URLSearchParams({ name: moduleName, files: filePaths.join(',') });
         return this.request(`/api/repos/${repoId}/wiki/context/leaf?${params}`);

package/dist/index.js

@@ -18,6 +18,7 @@ import { removeProjectContext } from './context.js';
 import { runSync } from './sync-command.js';
 import { ok, info, warn, fail, resolveAuth, DEFAULT_HUB_URL, EDITORS } from './cli-helpers.js';
 import { runConnect } from './connect-command.js';
+import { runInstallCi } from './install-ci-command.js';
 import { registerWikiCommand } from './wiki/index.js';
 const BANNER = [
     ' ██████╗ ██╗████████╗███╗   ██╗███████╗██╗  ██╗██╗   ██╗███████╗',
@@ -111,6 +112,32 @@ program
         process.exit(1);
     }
 });
+// ─── install-ci command ───────────────────────────────────────────
+//
+// Opens a PR on the user's GitHub repo that adds the GitNexus PR
+// review workflow. Mints a long-lived CI token via the Hub, sets it
+// (and CLAUDE_CODE_OAUTH_TOKEN, when a local Claude Code login is
+// detected) as repo Actions secrets, and base64-PUTs the rendered
+// workflow YAML through the user's `gh` CLI. v2 ships a single
+// workflow file; Claude is the primary review mechanism, no opt-out.
+program
+    .command('install-ci')
+    .description('Open a PR adding the GitNexus PR review workflow + set Actions secrets')
+    .option('--hub <url>', `Hub URL (default: saved config or ${DEFAULT_HUB_URL})`)
+    .option('--claude-token <token>', 'Claude OAuth token from `claude setup-token` (leaks to argv — prefer the CLAUDE_CODE_OAUTH_TOKEN env var)')
+    .option('--claude-token-file <path>', 'Path to a file containing the Claude OAuth token (alternative to --claude-token / env var)')
+    .action(async (opts) => {
+    try {
+        printBanner();
+        await runInstallCi(opts);
+    }
+    catch (err) {
+        console.error('');
+        fail(err.message);
+        console.error('');
+        process.exit(1);
+    }
+});
 // ─── wiki commands ────────────────────────────────────────────────
 registerWikiCommand(program);
 program.parse();

package/dist/install-ci-command.d.ts

@@ -0,0 +1,176 @@
+/**
+ * `gnx install-ci` (v2) — opens a PR on the user's GitHub repo that
+ * adds the single Claude-led GitNexus CI workflow, using the user's
+ * local `gh` CLI rather than a Hub-side OAuth-write grant.
+ *
+ * v1 shipped three workflow files (gitnexus.yml + claude.yml +
+ * claude-code-review.yml) and a `--no-claude` opt-out. v2 collapses
+ * to one file and makes Claude mandatory: the workflow's only review
+ * mechanism is the `anthropics/claude-code-action@v1` step, primed
+ * with a pre-computed Context Pack from `Akon-Labs/gitnexus-check@v2`.
+ *
+ * Pivot rationale (unchanged from v1): we don't want the Hub to keep
+ * a write-capable GitHub token per user. Doing the GitHub write from
+ * the user's machine via `gh` keeps the Hub free of `workflow` /
+ * `repo` OAuth scopes.
+ *
+ * Flow:
+ *   1. Detect git repo + GitHub remote.
+ *   2. Resolve fullName → repoId via `GET /api/repos`.
+ *   3. POST install-ci-bundle (mints CI token, renders workflow YAML).
+ *   4. `gh` preflight (installed, authed, has `repo` scope).
+ *   5. Push branch + PUT workflow file + open PR.
+ *   6. Set GITNEXUS_TOKEN + CLAUDE_CODE_OAUTH_TOKEN secrets via stdin.
+ *
+ * The exported `runInstallCi` is the commander entry point; the
+ * GitHub-write helpers (`pushWorkflowAndOpenPr`, `setRepoSecret`)
+ * accept an injected `runGh` for unit-testability.
+ */
+/**
+ * Adapter for `gh` invocations. Real impl shells out via execFileSync;
+ * tests replace it with a recording fake. The Promise return shape
+ * mirrors what we actually need from `gh` — stdout, stderr, exit code.
+ *
+ * `input`, when set, is piped to stdin. We use this for `gh secret
+ * set NAME --repo OWNER/REPO`, which reads the secret value from stdin
+ * when no `--body` / `--body-file` flag is set. That keeps the secret
+ * out of argv (`ps` leak) and out of any shell history.
+ */
+export type GhRunner = (args: string[], opts?: {
+    input?: string;
+}) => Promise<{
+    stdout: string;
+    stderr: string;
+    code: number;
+}>;
+interface InstallCiOpts {
+    hub?: string;
+    /**
+     * Raw Claude Code OAuth token (output of `claude setup-token`). Lowest
+     * priority — leaks to argv / `ps` / shell history. Prefer the env var
+     * `CLAUDE_CODE_OAUTH_TOKEN` for routine use; this flag is the escape
+     * hatch for one-off / scripted runs.
+     */
+    claudeToken?: string;
+    /**
+     * Path to a file whose contents are the Claude OAuth token. Mid
+     * priority — keeps the token off argv. Useful for ops that pre-stage
+     * the token in a file rather than the environment.
+     */
+    claudeTokenFile?: string;
+}
+/**
+ * Entry point for `gnx install-ci`. Imported by index.ts so commander
+ * has a stable handle.
+ *
+ * Output is structured as 6 numbered steps with a final boxed summary.
+ * The styling matches the v1 install-ci output that the user explicitly
+ * called out as "polished" — we keep the visual contract.
+ */
+export declare function runInstallCi(opts: InstallCiOpts): Promise<void>;
+/**
+ * Returns the missing scope name (e.g. "repo") if the active gh auth
+ * session lacks one we need, else null. We check `repo` only — that
+ * scope covers everything install-ci does:
+ *   - push branches & file content (Contents API)
+ *   - open PRs (Pulls API)
+ *   - read+write Actions secrets (`repo` is sufficient for repo-level
+ *     secrets; only org-level secrets need `admin:org`)
+ *
+ * Falls back to "no missing scope" if we can't parse `gh auth status`
+ * — better to let the real call surface the real error than block on
+ * a parser misfire across gh versions.
+ */
+export declare function ghMissingScope(): string | null;
+/**
+ * Read the user's Claude Code OAuth token from local credentials so
+ * we can auto-set CLAUDE_CODE_OAUTH_TOKEN as a GitHub Actions secret
+ * — the same source Claude Code's own `/install-github-app` reads.
+ *
+ * Lookup order (descending preference — first hit wins):
+ *
+ *   1. `opts.claudeToken` from `--claude-token=<value>` (lowest priority,
+ *      flagged for completeness — leaks to argv / `ps` / shell history).
+ *   2. `opts.claudeTokenFile` from `--claude-token-file=<path>` — reads
+ *      the file's trimmed contents. Keeps the token off argv.
+ *   3. `process.env.CLAUDE_CODE_OAUTH_TOKEN` — the documented happy path.
+ *      User runs `claude setup-token` once, exports the result via shell
+ *      rc, then `gnx install-ci` picks it up automatically on every run.
+ *
+ * Why we no longer auto-detect from `~/.claude/.credentials.json`: that
+ * file's `claudeAiOauth.accessToken` is the user's *interactive session*
+ * token (~1h expiry, refreshed in-band). It is NOT a valid CI OAuth
+ * token — those are minted explicitly by `claude setup-token` and have
+ * the longer-lived headless scope set the GHA expects. Live testing on
+ * deer-flow PR #11 confirmed: shipping the session token to the GHA
+ * causes "Could not resolve auth credentials" inside the bundled
+ * Anthropic SDK. Better to fail loud with a clear instruction than to
+ * silently set the wrong token.
+ *
+ * Returns the trimmed token if any source yields one; null otherwise.
+ * The caller prints a clear "run `claude setup-token` first" instruction
+ * on null and exits non-zero rather than shipping a half-installed CI.
+ */
+export declare function readClaudeOAuthToken(opts: {
+    claudeToken?: string;
+    claudeTokenFile?: string;
+}): string | null;
+/**
+ * Default `gh` runner — shells out via execFileSync. Captures stdout
+ * + stderr separately so callers can inspect each. When `input` is set,
+ * pipes it to stdin (used for `gh secret set` so secret material never
+ * lands in argv or process listings). Translates non-zero exit into a
+ * thrown Error whose message is the stderr text, matching the contract
+ * tests expect.
+ */
+export declare const defaultGhRunner: GhRunner;
+/**
+ * Set a repository-level Actions secret without ever putting the value
+ * in argv. `gh secret set NAME --repo OWNER/REPO` reads the secret
+ * value from stdin when neither `--body` nor `--body-file` is set —
+ * documented behavior across all supported gh versions.
+ *
+ * (We deliberately avoid `--body-file -`. That flag was added later
+ * than our minimum supported gh version; older installs reject it as
+ * "unknown flag" and crash the install-ci flow even though the
+ * underlying API supports stdin natively.)
+ */
+export declare function setRepoSecret(runGh: GhRunner, fullName: string, name: string, value: string): Promise<void>;
+export interface PushResult {
+    prUrl: string;
+    /**
+     * True when we found the workflow file already present on the branch
+     * with byte-identical content AND a PR already exists. We still
+     * surface the PR URL so the user can check on it; the summary box
+     * formats this case as "already installed" rather than "completed".
+     */
+    alreadyInstalled: boolean;
+}
+/**
+ * Push the workflow file to `branchName` and open a PR.
+ *
+ * Idempotency:
+ *   - If `branchName` already exists we keep using it (gh's create-branch
+ *     fails with "Reference already exists" — caught and ignored).
+ *   - If the workflow file is already present with byte-identical
+ *     content AND a matching PR is already open from this head, we
+ *     mark `alreadyInstalled = true` and skip the PUT + create-PR
+ *     calls. The branch name embeds a timestamp so practical retries
+ *     never collide, but tests inject a fixed branch name to drive
+ *     this code path.
+ *   - If the file exists with different content, we PUT with the
+ *     existing sha so it's an update.
+ *   - If a PR creation returns 422 (duplicate), we fall back to the
+ *     `pulls?head=...&state=all` lookup and surface that URL.
+ *
+ * `runGh` is injected so tests can drive the full idempotency matrix
+ * without spawning a real `gh`.
+ */
+export declare function pushWorkflowAndOpenPr(args: {
+    owner: string;
+    repo: string;
+    branchName: string;
+    workflowYaml: string;
+    runGh: GhRunner;
+}): Promise<PushResult>;
+export {};